build(markdown): exempt the generated CHANGELOG from MD012 (RIG-3669) - #1116
Open
rigel-mintaka wants to merge 3 commits into
Open
build(markdown): exempt the generated CHANGELOG from MD012 (RIG-3669)#1116rigel-mintaka wants to merge 3 commits into
rigel-mintaka wants to merge 3 commits into
Conversation
…dl (RIG-3663) Replaces markdownlint-cli2 with rumdl as compass's whole-repo markdown gate — a parity swap to one Rust binary, matching orion (RIG-1994). ### What changed - New `.rumdl.toml` at the repo root is the single place the markdown rule policy lives. rumdl prunes `[global] exclude` before reading any file, so the exclusion set is plain config, not a command-line glob chain. - `moon.yml` `root:markdownlint` now runs `rumdl check .` (no glob operands, no --config chain); task name kept as `markdownlint`. Its inputs reference `/.rumdl.toml`. - `devenv.nix` and the CI toolchain comments swap the nixpkgs attribute markdownlint-cli2 → rumdl. The ci.yml PATH derives from parity.ts's parse of devenv.nix, so no literal attr to change there. - Deleted `.markdownlint.json` and `.markdownlint-cli2.jsonc` in the same change: rumdl reads markdownlint config files and `.markdownlint-cli2.jsonc` outranks `.markdownlint.json`, so leaving either would silently re-enable MD013 and drop the exclusions. - Repointed the docsite runtime consumer (`apps/eng-docs/scripts/gather.ts` + `deploy.ts`) at `.rumdl.toml` `[global] exclude` via a native `Bun.TOML.parse`; `parseExclusions`/`changedDocPages` now take the parsed array. Tests updated. - Rule dispositions on compass's own evidence: MD046 pinned `fenced` (config fix, clears 53); MD064 (14 stray double-spaces) fixed in prose via `rumdl fmt`, with 3 dependent DECISIONS.md anchor fragments corrected; MD057/MD032/MD076/MD077/MD075/MD049 disabled as verified false positives (MD057's 28 findings are all the DECISIONS paste-ready-row convention — zero genuine broken links). - CONTRIBUTING.md, docs/architecture/build-and-ci.md, and the renovate tooling comments updated. ### Notes - MD032 decided OFF on compass's own evidence, not copied: its 6 findings are all list-continuation false positives (auto-fix splits a sentence mid-line). It changes no file's fixability here. - The vendored `forks/` trees the issue's 916-file/51-issue figures assumed are already gone from this checkout (RIG-2336 landed), so the corpus is 217 tracked md; the gate scans 212 with exclusions. Spec-impact: none. Refs RIG-3663 Co-authored-by: Matt Wilkinson <matt@rigel.build>
…ile (RIG-3663) Review fix (Main): the repo-wide MD057 disable was wrong. MD057 is a valuable rule (broken relative links) and is now ENABLED, exempted only for the 11 design records whose `## Ledger delta` sections quote a paste-ready DECISIONS.md row. Those rows' links are written relative to the ledger's own directory (`docs/designs/`), so they resolve from `DECISIONS.md` (which passes MD057) but not from the record's own directory, which is where rumdl resolves a relative link. The authored ledger copies are correct; the record-body quotes only appear broken from their own vantage. A `[per-file-ignores]` scope keeps MD057 live everywhere else and keeps every other rule live on these records. Controls: a broken link injected into a non-exempt file (README.md) still fires MD057; MD001 still fires inside an exempt record (exemption is MD057-only). Spec-impact: none. Refs RIG-3663 Co-authored-by: Matt Wilkinson <matt@rigel.build>
release-please's `CHANGELOG.md` template emits a double blank line under each version heading, which trips MD012 and fails the `root:markdownlint` gate. It first fires on compass's very first release PR (#1032, `chore(main): release 0.2.0`), where the file is created — there was no CHANGELOG before, so the gate has never seen it. The fix has to live in config rather than in the file: release-please regenerates `CHANGELOG.md` on every version bump, so a hand-fix (or a `rumdl fmt` pass) is overwritten at the next release and CI goes red again on each one. ### What changed - `.rumdl.toml` `[per-file-ignores]` gains `"CHANGELOG.md" = ["MD012"]`. Scoped to MD012 alone, not a `[global] exclude`, so every other rule stays live on the file — a genuinely broken fence or heading in the changelog is still caught. This matches the block's existing posture of per-file scoping in preference to disabling a rule outright. The file is generated output rather than authored prose, which is the same basis as the agent-context payloads already carved out in `[global] exclude`. ### Verification Red/green against the real generated file from #1032's branch: - Without the exemption: `rc=1`, `MD012` at `CHANGELOG.md:5`, `:193`, `:268` — the exact three findings CI reported. - With the exemption: `rc=0`, `Success: No issues found`. - Repo-wide `rumdl check .`: `Success: No issues found in 212 files`. Stacked on #1094 (RIG-3663), which introduces `.rumdl.toml`; this change has no meaning before that lands. Ledger-impact: none — a lint-config carve-out, no design decision. Refs RIG-3669 Co-authored-by: Matt Wilkinson <matt@rigel.build>
|
Merging to
After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here |
rigel-mintaka
changed the title
rigel-mintaka
changed the base branch from
main
to
compass3663/rig-3663-rumdl-markdown-gate
September 11, 2026 20:31
|
Compass engineering docs preview: https://compass-repo-rig-3669-change.compass-eng-docs.pages.dev Deployed from |
mattwilkinsonn
added this pull request to stack #1127
September 12, 2026 01:19
mattwilkinsonn
approved these changes
Sep 12, 2026
Base automatically changed from
compass3663/rig-3663-rumdl-markdown-gate
to
main
September 12, 2026 02:02
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
2 participants
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.
release-please's
CHANGELOG.mdtemplate emits a double blank line under each version heading, which trips MD012 and fails theroot:markdownlintgate. It first fires on compass's very first release PR (#1032,chore(main): release 0.2.0), where the file is created — there was no CHANGELOG before, so the gate has never seen it.The fix has to live in config rather than in the file: release-please regenerates
CHANGELOG.mdon every version bump, so a hand-fix (or arumdl fmtpass) is overwritten at the next release and CI goes red again on each one.What changed
.rumdl.toml[per-file-ignores]gains"CHANGELOG.md" = ["MD012"].Scoped to MD012 alone, not a
[global] exclude, so every other rule stays live on the file — a genuinely broken fence or heading in the changelog is still caught. This matches the block's existing posture of per-file scoping in preference to disabling a rule outright.The file is generated output rather than authored prose, which is the same basis as the agent-context payloads already carved out in
[global] exclude.Verification
Red/green against the real generated file from #1032's branch:
rc=1,MD012atCHANGELOG.md:5,:193,:268— the exact three findings CI reported.rc=0,Success: No issues found.rumdl check .:Success: No issues found in 212 files.Stacked on #1094 (RIG-3663), which introduces
.rumdl.toml; this change has no meaning before that lands.Ledger-impact: none — a lint-config carve-out, no design decision.
Refs RIG-3669
Co-authored-by: Matt Wilkinson matt@rigel.build