From 09a1d9f7cd8ea1c77812ee135305309d631262ab Mon Sep 17 00:00:00 2001 From: fred Date: Wed, 19 Aug 2026 10:47:50 -0500 Subject: [PATCH 1/2] guides: two measurement rules about pinned tool versions Earned on #1313, where I reported three guides as failing the format gate and was wrong. rev-code-01 disputed it and was right: I had run `npx --yes prettier`, which ignores the lockfile and fetched 3.9.6. Measuring it out was more useful than conceding it. Same three files: 3.0.0 floor of the declared ^3.0.0 CI-CD-PIPELINES fails, other two pass 3.8.1 pinned by the lockfile all three pass, and this is CI's answer 3.9.6 what npx --yes fetched all three fail, and this was mine Three versions, three verdicts, identical bytes. Rule 13 says run the pinned tool. Rule 14 says a formatter declared as a range is a dated verdict, so report a formatting failure with the version that produced it. Worth recording separately: those three guides DO fail under 3.9.6, so they become a real format-gate failure the day the pin moves past 3.8.1. Not fixed here, and not in scope for a guides change. Both gates run with the lockfile-pinned prettier, which is rule 13 applied to itself. --- packages/mosaic/framework/guides/CODE-REVIEW.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/packages/mosaic/framework/guides/CODE-REVIEW.md b/packages/mosaic/framework/guides/CODE-REVIEW.md index f4834bd8..c4ea6b3c 100755 --- a/packages/mosaic/framework/guides/CODE-REVIEW.md +++ b/packages/mosaic/framework/guides/CODE-REVIEW.md @@ -65,6 +65,16 @@ Each of these produced a wrong conclusion before it was written down. conclusion drawn from it describes the wrong tree. Confirm `git rev-parse --show-toplevel` is the tree you think it is before trusting any git output. +13. **Run the repository's PINNED tool version, not `npx --yes `.** `npx --yes` ignores the + lockfile and fetches the latest release, so it answers about a version the project does not + use. Measured on mosaicstack#1313: the lockfile pins prettier 3.8.1, under which three guides + pass; `npx --yes prettier` fetched 3.9.6, under which the same three fail; and 3.0.0, the floor + of the declared `^3.0.0` range, fails a different one. Three versions, three verdicts, same + bytes. Use `node_modules/.bin/`, or name the version the lockfile pins. +14. **A formatter or linter declared as a range is a dated verdict, not a fact.** If a lockfile + pins it, the gate is reproducible today and will disagree with itself the day the pin moves. + Report a formatting failure with the version that produced it, always. + ### Feedback Categories - **Blocker**: must fix before merge (security, bugs, test failures) -- 2.54.0 From 453f4956307f6c3bc2ce453bdffae4af9ffaebff Mon Sep 17 00:00:00 2001 From: fred Date: Wed, 19 Aug 2026 11:03:18 -0500 Subject: [PATCH 2/2] guides: correct rule 13's mechanism per rev-code-02 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit rev-code-02's suggestion on #1316, and it is right. I wrote that 'npx --yes' ignores the lockfile. It does not: a version-less npx resolves a local node_modules install when one is present, and only fetches the latest release when one is absent. That makes the rule sharper rather than weaker. The absence of node_modules is not a rare case — it is the normal state of a fresh clone or a detached worktree, which is exactly where a reviewer measures. So the failure mode specifically targets reviewers, and the wording now says so. Gates re-run with the pinned prettier. --- packages/mosaic/framework/guides/CODE-REVIEW.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/packages/mosaic/framework/guides/CODE-REVIEW.md b/packages/mosaic/framework/guides/CODE-REVIEW.md index c4ea6b3c..75db13c5 100755 --- a/packages/mosaic/framework/guides/CODE-REVIEW.md +++ b/packages/mosaic/framework/guides/CODE-REVIEW.md @@ -65,12 +65,15 @@ Each of these produced a wrong conclusion before it was written down. conclusion drawn from it describes the wrong tree. Confirm `git rev-parse --show-toplevel` is the tree you think it is before trusting any git output. -13. **Run the repository's PINNED tool version, not `npx --yes `.** `npx --yes` ignores the - lockfile and fetches the latest release, so it answers about a version the project does not - use. Measured on mosaicstack#1313: the lockfile pins prettier 3.8.1, under which three guides - pass; `npx --yes prettier` fetched 3.9.6, under which the same three fail; and 3.0.0, the floor - of the declared `^3.0.0` range, fails a different one. Three versions, three verdicts, same - bytes. Use `node_modules/.bin/`, or name the version the lockfile pins. +13. **Run the repository's PINNED tool version.** `npx ` resolves a local `node_modules` + install when one is present and fetches the latest release when one is not, so the same + command answers differently depending on where it ran. A reviewer measuring in a fresh clone + or a detached worktree — which is exactly where reviewers measure — has no `node_modules` and + silently gets the latest release instead of the pinned one. Measured on mosaicstack#1313: the + lockfile pins prettier 3.8.1, under which three guides pass; a version-less `npx` in a + worktree resolved 3.9.6, under which the same three fail; and 3.0.0, the floor of the declared + `^3.0.0` range, fails a different one. Three versions, three verdicts, identical bytes. Use + `node_modules/.bin/`, or name the version the lockfile pins. 14. **A formatter or linter declared as a range is a dated verdict, not a fact.** If a lockfile pins it, the gate is reproducible today and will disagree with itself the day the pin moves. Report a formatting failure with the version that produced it, always. -- 2.54.0