Repository navigation
infra: clear outstanding validate --all violations at their source #356
Description
Problem
npm run validate (scripts/validate.js --all) reports violations on main that no PR ever surfaces, because CI validates only the files changed in a PR. That CI scope is deliberate: it exists so known pre-existing violations do not block unrelated PRs. The fix is therefore to clear the violations at their source, not to change the CI scope.
State at the time of filing: 11 errors.
| Count | File | Error | Where the fix belongs |
|---|---|---|---|
| 7 | docs/references/internet-identity-spec.md |
em-dash in prose | Upstream (dfinity/internet-identity) |
| 2 | docs/guides/backends/data-persistence.mdx |
mo:base is banned |
Validator (false positive) |
| 1 | docs/guides/backends/data-persistence.mdx |
em-dash in prose | Internal |
| 1 | docs/guides/digital-assets/chain-key-tokens.mdx |
em-dash in prose | Internal |
Status
- The 4 hand-written ones, in fix: clear hand-written validate --all violations, correct the mo:base check #357: two em-dashes replaced, plus a fix to the
mo:baserule. - The 7 in the synced II spec (below).
The mo:base rule was inverted
checkForbiddenPatterns skips fenced code, so the old /mo:base/ pattern could only match prose. An actual import Buffer "mo:base/Buffer"; lives inside a fence and was never flagged, while naming the legacy library in prose was. Both hits on main were the base-to-core migration table in data-persistence.mdx, which is legitimate and mirrors the mapping in AGENTS.md. #357 changes the pattern to the import path mo:base/ and checks it inside fences.
The 7 remaining: fix in dfinity/internet-identity
They are not ours to edit. docs/references/internet-identity-spec.md is generated by scripts/sync-ii-spec.mjs from .sources/internetidentity/docs/ii-spec.mdx, which contains exactly the same 7 em-dashes. Editing the output is pointless: the next sync restores them. They arrived with the release-2026-08-21 spec sync (#350), mostly in the new ii-app-metadata section.
Two ways to land it:
- Propose the change upstream in
dfinity/internet-identity, so both repos converge and nothing has to be rewritten on sync. Preferred, but it asks another team to adopt a style rule that is ours. - Normalize during the sync, the way
scripts/postprocess-motoko.mjsalready replaces em-dashes for Motoko. Entirely in our control and needs no coordination, but the published spec text then differs in punctuation from the canonical spec, which is a heavier thing to do to a specification than to a guide.
These are not exclusive; Motoko does normalization and upstream carries most of the style contract. Suggested order: propose upstream first, and add sync normalization only if it is declined or takes too long.
Instructions to update alongside
AGENTS.md should state the policy once it is decided: which synced targets are normalized at sync time, and that a new synced target has to be registered in the validator's SYNCED allowlist (which today lists only docs/languages/motoko, while the II spec output is not listed and so is checked like a hand-written page).
Related
- fix: clear hand-written validate --all violations, correct the mo:base check #357 clears the 4 hand-written violations
- docs: small frontmatter and style contract so docs/ can sync into developer-docs certified-assets#124 asks a third upstream to drop em-dashes for the same reason, so whatever is decided here should be consistent with it
- infra: reduce .sources/ submodules to what the site actually needs, watch releases for the rest #355 covers the wider
.sources/strategy and owns the AGENTS.md changes
Activity
[-]infra: validate --all fails on main; decide what synced trees are exempt from[/-][+]infra: clear outstanding validate --all violations at their source[/+]marc0olo commentedon Aug 27, 2026
Both halves are done, so closing. One nuance worth recording, because it changes when the last errors disappear.
The 4 hand-written violations are fixed in #357: two em-dashes replaced, and the
mo:baserule corrected to match the import path inside code fences rather than legitimate prose mentions in the base-to-core migration table.The 7 in the synced II spec are fixed at the source in dfinity/internet-identity#4284, merged 2026-08-26. Verified:
docs/ii-spec.mdxon IImainnow has zero em-dashes.They will not clear on the next sync run, though.
scripts/sync-ii-spec.mjspins to the newestrelease-YYYY-MM-DDtag, and we are already on it:So there is nothing to sync today. The fix arrives when Internet Identity cuts its next dated release containing that commit, which
.github/workflows/sync-ii-spec.ymlpicks up automatically on its weekly check. Until thennpm run validatereports 7 errors onmain, all indocs/references/internet-identity-spec.md, and none from hand-written content.Verify at any time with:
The decision this issue set out to make, normalize at sync time or exempt via the allowlist, was answered by fixing it upstream instead: the published text and the canonical spec stay identical, and no exemption was added. If II ever reintroduces em-dashes there, the choice comes back, and
postprocess-motoko.mjsalready shows what normalizing looks like.docs: sync content against the ten upstream releases the watcher surf…