ci: gate a merge on the checks a reviewer cannot run by eye - #8
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR introduces a CI “checks” workflow to gate merges on documentation-quality failures that are hard to catch in review (dead links/anchors, invalid frontmatter, banned terms/prose characters, spelling/casing rules, validation ledger consistency, and basic markdown structure). It also includes small content tweaks so the new checks pass cleanly on arrival.
Changes:
- Adds
.github/workflows/checks.ymlwith 10 separately-requirable jobs (links, anchors, frontmatter, banned-terms, prose-bans, spelling, casing, validation-consistency, markdownlint, starters). - Adds supporting scripts/config for code-stripped prose scanning, frontmatter parsing/validation, ledger/page consistency, markdownlint and typos configuration, plus ripgrep installation and Dependabot for pinned actions.
- Updates a handful of docs for casing consistency and adds a pinned baseline entry.
Reviewed changes
Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
validation-log.md |
Adds a pinned baseline entry for @wharfkit/antelope. |
reference/sdk/atomicmarket.md |
Fixes product/API casing in prose. |
reference/sdk/atomicassets.md |
Fixes WharfKit casing in prose. |
reference/atomicassets-api.md |
Fixes AtomicMarket casing in prose. |
guides/querying-the-api.md |
Fixes WharfKit casing in prose. |
guides/links.md |
Fixes AtomicTools casing in prose. |
.markdownlint-cli2.jsonc |
Defines a minimal, repo-wide markdownlint rule set aligned with site constraints. |
.github/workflows/checks.yml |
Introduces the CI gate workflow with 10 named jobs for branch protection. |
.github/scripts/strip-code.mjs |
Generates code-stripped markdown copies while preserving line/column alignment for findings. |
.github/scripts/lib/pages.mjs |
Implements frontmatter parsing and page-tree walking utilities used by checks. |
.github/scripts/install-ripgrep.sh |
Installs a pinned ripgrep build with checksum verification for PCRE2 rules. |
.github/scripts/check-validation-consistency.mjs |
Validates consistency between the provenance ledger and graded pages/baselines. |
.github/scripts/check-frontmatter.mjs |
Enforces frontmatter/site constraints and outputs YAML blocks for AJV schema validation. |
.github/dependabot.yml |
Enables Dependabot updates for pinned GitHub Actions SHAs. |
.github/banned-terms.txt |
Defines repo-specific banned terms enforced on prose (code-stripped) content. |
_typos.toml |
Configures spelling rules for the corpus when run over stripped prose. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| continue; | ||
| } | ||
| spans.push([partner.start, run.start + run.length]); | ||
| open.clear(); |
Comment on lines
+83
to
+94
| const graded = []; | ||
| for (const tree of GRADED) graded.push(...(await pagesUnder(root, tree))); | ||
|
|
||
| for (const page of graded) { | ||
| if (page === ledger.path) continue; | ||
| if (!rows.has(page)) findings.push(`${page} has no row in ${ledger.path}`); | ||
| } | ||
|
|
||
| for (const [page, count] of rows) { | ||
| if (!graded.includes(page)) findings.push(`${ledger.path} grades a page that does not exist: ${page}`); | ||
| if (count > 1) findings.push(`${ledger.path} grades ${page} in ${count} rows`); | ||
| } |
Comment on lines
+291
to
+295
| starters: | ||
| runs-on: ubuntu-latest | ||
| timeout-minutes: 20 | ||
| environment: wax-testnet | ||
| steps: |
Five sentences named a product with a bare lowercase word: the WharfKit client twice, an AtomicTools action, the AtomicMarket API, and the AtomicMarket indexer handler. This corpus already writes the contract account, the repository, and the package with a separator that keeps each of them lowercase, so a bare lowercase token in prose reads as one of those and sends a reader after an identifier that does not exist.
The ledger's row for the WharfKit page names the library and the version it was read at, while the pinned-baselines list above it carried no entry for the library at all. The list is what a reader takes as the full set of sources behind this corpus, and a Release body copies it verbatim, so a page resting on a source the list omits reads as a page resting on nothing.
robrigo
force-pushed
the
ci/corpus-checks
branch
from
August 18, 2026 20:04
ac44bf8 to
55c5627
Compare
Nothing checked a page before it merged, and the defects that reach a reader are exactly the ones a reviewer does not see: a fragment with no matching heading, a description outside the band the site renders it into, a ledger row for a page that no longer exists. Each of those surfaces in the docs-site repository at pin-bump time instead, where the person who caused it is not looking. Each job id is its check name, so branch protection requires ten names and a red pull request has already said which rule failed. The four prose rules read a copy of each page with its code blanked to spaces of the same shape, because this corpus writes account names and ABI type names in code, and a rule that cannot tell code from prose either fails on a sample or gets switched off. External URL checking and starter signing are the two arms that need the network, and both run on the weekly schedule so a third-party outage never blocks a merge.
robrigo
force-pushed
the
ci/corpus-checks
branch
from
August 18, 2026 20:06
55c5627 to
373c47e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The corpus has had no gate but a reviewer's eye, and the failures a reviewer cannot see by eye are exactly the ones that reach the docs site: a dead cross-reference, a scope line outside the band the site measures, a page with no provenance row, a banned term or an em-dash in prose, a product name in the wrong case. This pull request adds one workflow with ten jobs, each named for the check it runs (
links,anchors,frontmatter,banned-terms,prose-bans,spelling,casing,validation-consistency,markdownlint,starters), so branch protection can require them by id. The four text jobs run over a code-stripped copy of each page so that account names, ABI types, and shell samples do not trip prose rules, and every finding keeps its source line number. Two small content commits ride ahead of the workflow so every check is green on arrival: four product-name casings and one missing ledger baseline the new checks exposed. Dependabot watches the four pinned actions.Notes for the maintainer
Every job was run locally against this branch and negative-tested with a seeded defect. The
startersjob is declared and skips with an explanation until the starters directory exists; its signing arm runs on push and schedule only, under awax-testnetenvironment holdingWAX_TESTNET_ACTORandWAX_TESTNET_PRIVATE_KEY, and never on a pull request, so a fork can never reach a key. The environment applies to the whole job, so it must carry no required reviewer. ripgrep is installed from a pinned release with a checksum because the runner image lacks it and the apt package cannot promise PCRE2. The commits are unsigned; the squash merge carries GitHub's signature. Stacked on the links pull request.