release: GT-658 — a broken renderer accused hundreds of innocent diagrams - #445
Merged
Conversation
…71 diagrams, and pin it (#444) `01-validate-docs --render-mermaid` spawned `npx -y @mermaid-js/mermaid-cli` with NO version, once per diagram. On 2026-08-08 that install came out INCOMPLETE on a runner — `Cannot find package 'import-meta-resolve'`, which the package DOES declare, so the tree was half-written rather than the publish being bad. Every diagram then failed as "mermaid render failed", blamed on the document containing it; 23m21s to reach hundreds of wrong accusations. Two defects in one invocation. The pin: `npx -y` with no version resolves @latest when CI runs, and the tool is in package-lock.json ZERO times, so npm ci, npm audit, Dependabot and GT-657's audit gate are all blind to it. The blame: the corpus and the renderer are different things and only one can be broken by a commit, but the guard asked about 371 diagrams before asking whether the renderer worked, so the loudest signal pointed at the only innocent party. A preflight now renders one trivial diagram first. A failure there is ONE error naming the renderer, stating no diagram is implicated. Exit 0 is not proof — a renderer that writes no SVG has not rendered. Pinned to 11.16.0 in one constant both paths read. Both halves measured on the runner before merging: broken renderer (non-existent pin) -> exit 1, ZERO "mermaid render failed" healthy renderer (dispatched full corpus) -> 405 of 405 rendered, success The PR's own green was NOT accepted as verification: it rendered 0 of 405, because pull_request builds scope rendering to changed files and this change touches no diagram-bearing markdown. A workflow_dispatch, where GITHUB_BASE_REF is unset and the whole corpus renders, is what proved it. The first version of this preflight carried the defect it removes: on a machine with no usable Chromium mermaid-cli exits 1 silently, and the message read "exited 1 on a trivial diagram: ". It now says the process was silent, names the likely cause and prints the command to reproduce. NOT done, deliberately: declaring the tool a pinned devDependency is the fuller fix but drags Puppeteer and Chromium into every npm ci. Recorded as a separate decision. Board: 643 / 656 done, 3 in progress, 3 pending, 7 deferred.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
📊 Bilingual Coverage ImpactPR Changes
Repository Coverage
✅ Good: All EN changes have ES counterparts. Generated by GitHub Actions |
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
1 participant
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.
Promotes
developtomain. One gap, found in the CI of the previous promotion (#443).01-validate-docs --render-mermaidspawnednpx -y @mermaid-js/mermaid-cliwith no version, once per diagram. That install came out incomplete on a runner —Cannot find package 'import-meta-resolve', which the package does declare — and every diagram then failed asmermaid render failed, blamed on the document containing it. 23m21s to reach hundreds of wrong accusations.Two defects in one invocation
The pin.
npx -ywith no version resolves@latestwhen CI runs, and the tool appears inpackage-lock.jsonzero times —npm ci,npm audit, Dependabot and GT-657's audit gate are all blind to it.The blame. The corpus and the renderer are different things and only one of them can be broken by a commit. The guard asked about 371 diagrams before asking whether the renderer worked, so the loudest signal pointed at the only innocent party.
A preflight now renders one trivial diagram first; a failure there is one error naming the renderer and saying no diagram is implicated. Exit 0 is not proof — a renderer that writes no SVG has not rendered. Pinned to
11.16.0in a single constant both paths read.Both halves measured on the runner, before merging
mermaid render failedlinesThe PR's own green was not accepted as verification. It rendered 0 of 405:
pull_requestbuilds scope rendering to changed files, and that change touched no diagram-bearing markdown. Aworkflow_dispatch, whereGITHUB_BASE_REFis unset and the whole corpus renders, is what actually proved it.Not done, deliberately
Declaring the tool a pinned devDependency is the fuller fix — lockfile,
npm audit, Dependabot, andnpm cifailing loudly on exactly the partial install that caused this — but it drags Puppeteer and a Chromium download into everynpm cito render diagrams only CI renders. Recorded in GT-658 as a separate decision.Board: 643 / 656 done, 3 in progress, 3 pending, 7 deferred.
🤖 Generated with Claude Code