chore(dev): make pre-tag-check.sh mirror the lint job; fix stale local-CI docs

[TheHypnoo]

Third of the base-hygiene changes from studying oxc (after #6754 and #6755). Their just ready is a single "will CI pass?" command; Perry already had the pieces, but nothing tied them together and the docs pointed the wrong way.

What was actually wrong

scripts/pre-tag-check.sh opens by claiming it runs "the same fast lint gates that the Tests workflow's lint and api-docs-drift jobs run". That stopped being true a while ago. It ran fmt, a docs-fence lint, and cargo check — while the lint job also gates on the 2000-line file cap, the GC store-site inventory, the address-classification audit, the benchmark harness tests, and public-artifact freshness, plus the clippy job added in #6754. Those are exactly the gates CLAUDE.md files under "CI gates that surprise people", and none of them were reachable locally from one command.

CONTRIBUTING.md was worse than incomplete. Its "Running the full CI suite locally" section told contributors ./run_parity_tests.sh # (needs Node 22). Node is the oracle the suite diffs against, so its version is a correctness input — and Node 22 is precisely the pin that classified 14 tests as node_fail and silently dropped them from the gate for months (#6364). The docs were recommending the configuration that caused the incident.

The change

pre-tag-check.sh now mirrors the lint job, split so the cheap half is the habitual one:

• --quick (~10s) — every lint-job gate that compiles nothing: fmt, benchmark harness tests, public-artifact freshness, file-size cap, GC store-site inventory, address-classification audit, and (once test(parity): bidirectional snapshot ratchet for the gap suite (#797) #6755 lands) the gap-snapshot self-test, which is guarded so this script also works on a checkout predating it. Kept in the same order as test.yml so drift between the two is visible on sight.
• default — adds the docs-fence lint, cargo check --release, cargo clippy, and cargo deny check. cargo-deny is optional: missing tool skips cleanly rather than failing a contributor who lacks it.
• --thorough — unchanged.

The existing all-failures-then-exit behavior is preserved, so one run surfaces everything instead of trickling one failure per push.

CONTRIBUTING.md's section is rewritten around it, with the Node pin explained as a correctness input rather than a toolchain detail, and the changelog.d/ fragment requirement spelled out.

No new dependency: this is the existing script and the existing gates, wired together. A justfile would have meant every contributor installing just to run scripts they can already run.

Validation

--quick run end-to-end: 7 gates execute in CI order, exit 1 on failure, unknown flags still exit 2. It immediately reproduced the public benchmark evidence freshness failure that is currently red on main — which is the point: that gate went red in #6754 and only surfaced after pushing.

Two things it surfaced, not fixed here

• main's lint job is red. The freshness check fingerprints the root Cargo.toml, so chore(workspace): workspace lint policy, clippy + cargo-deny CI gates, dep unification #6754's [workspace.lints] / [workspace.dependencies] edits invalidated the public benchmark artifact. It needs ./benchmarks/run_public_baseline.sh re-run on the benchmark machine and committed. It matters more than one red check: the step aborts the job before the file-size, GC store-site, and address-classification gates run, so those are currently not executing on any PR.
• The addr-class ratchet baseline is stale in the improvement direction — buffer/from.rs 10→9, object_ops_frozen.rs 8→7, symbol/constructors.rs 3→2, thread.rs 13→10. Sites were fixed without recording it. The audit passes (it is a ratchet) and prints the fix, python3 scripts/addr_class_inventory.py --write-baseline; left out of this PR to keep the diff to tooling. Worth noting it is the same "improvements must be recorded" problem test(parity): bidirectional snapshot ratchet for the gap suite (#797) #6755 solves for the gap suite.

Summary by CodeRabbit

• Documentation

  • Updated contributor instructions for running CI checks locally, including a fast pre-tag gate followed by the full gap and doc/example test suites.
  • Pinned the Node.js version to match the repo’s .node-version.
  • Clarified the requirement for crates/ changes to include a changelog.d/<PR-number>-<slug>.md fragment.

• Chores

  • Expanded the pre-tag validation pipeline with additional freshness, size, inventory, and audit checks.
  • Improved separation of quick (non-compiling) vs comprehensive (compiling) stages, with clearer messaging when optional tooling is unavailable.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f03dff9e-9b95-46cb-81b5-c7decf9f5a3b

📥 Commits

Reviewing files that changed from the base of the PR and between f536f7f and 1fb80fc.

📒 Files selected for processing (1)

• CONTRIBUTING.md

🚧 Files skipped from review as they are similar to previous changes (1)

• CONTRIBUTING.md

---

📝 Walkthrough

Walkthrough

The pre-tag check script now separates non-compiling and compile-dependent tiers, with additional validation gates and optional cargo-deny handling. Contributor guidance documents the updated commands, Node version requirement, conformance tests, documentation tests, and changelog fragment requirement.

Changes

Pre-tag validation workflow

Layer / File(s)	Summary
Tiered pre-tag checks scripts/pre-tag-check.sh	The script documents expanded gate coverage and separates unconditional non-compiling checks from compile-dependent checks controlled by --quick; it also adds optional cargo-deny handling.
Contributor local workflow CONTRIBUTING.md	Local CI guidance covers the quick pre-tag gate, deeper checks, conformance and documentation tests, the pinned Node version, and changelog fragments for PRs touching crates/.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• PerryTS/perry#6755: Adds the gap snapshot self-test behavior referenced by the expanded pre-tag checks.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly names the main change: pre-tag-check parity with the lint job and stale CI docs fixes.
Description check	✅ Passed	The description covers summary, concrete changes, and validation, though it omits explicit related issue and checklist sections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/local-ci-entrypoint

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CONTRIBUTING.md`:
- Around line 102-106: Update the prerequisites table in CONTRIBUTING.md to
reference the Node.js version pinned in `.node-version` instead of prescribing
Node.js 22. Keep the surrounding guidance consistent with `.node-version` as the
authoritative contributor baseline.
- Around line 108-109: The contribution policy must require the mandatory
release metadata alongside the changelog fragment for PRs touching crates/.
Update the guidance near the changelog.d requirement to explicitly require a
Cargo.toml patch-version increment, a matching CLAUDE.md Current Version update,
and a new top-level CHANGELOG.md version block, or reconcile the wording so both
policies are consistent.
- Around line 82-92: Update the gate descriptions around
./scripts/pre-tag-check.sh --quick in CONTRIBUTING.md: state that --quick
excludes Clippy, clarify that the default run also includes the docs linter, and
note that cargo deny is skipped when unavailable. Keep the command examples and
remaining gate descriptions accurate.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5ff83eed-1173-40fa-b3ed-5aff22523fd7

📥 Commits

Reviewing files that changed from the base of the PR and between af8a094 and f536f7f.

📒 Files selected for processing (2)

• CONTRIBUTING.md
• scripts/pre-tag-check.sh

[coderabbitai]

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Reconcile the fragment policy with mandatory release metadata.

This .md change lacks the required Cargo.toml patch bump, CLAUDE.md Current Version update, and new top-level CHANGELOG.md version block. A fragment-only requirement does not satisfy that policy; add the metadata changes or align the policies before merge.

As per coding guidelines, “For every change landing on main, increment the patch version in Cargo.toml and the Current Version line in CLAUDE.md, [and] add a new top-level version block to CHANGELOG.md.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CONTRIBUTING.md` around lines 108 - 109, The contribution policy must require
the mandatory release metadata alongside the changelog fragment for PRs touching
crates/. Update the guidance near the changelog.d requirement to explicitly
require a Cargo.toml patch-version increment, a matching CLAUDE.md Current
Version update, and a new top-level CHANGELOG.md version block, or reconcile the
wording so both policies are consistent.

Source: Coding guidelines