chore: release/repo hygiene, doc truth-up + drift gate, gate governance - #283
Merged
Conversation
…h CONTRIBUTING files - README.md: removed the duplicate codecov badge (kept the more informative `&label=Coverage` one) and the CII Best Practices badge, which had a literal `projects/XXXX` placeholder (broken image, dead link) — the project was never registered. Added a TODO.md entry with the registration URL; that's an external, interactive signup, so it stays a maintainer action, not something this pass does automatically. - Added .github/CODE_OF_CONDUCT.md (Contributor Covenant 2.1), with an enforcement-contact section that mirrors SECURITY.md's pattern (GitHub Private Vulnerability Reporting, no hardcoded personal email). - .github/CONTRIBUTING.md already referenced a Code of Conduct but linked externally to contributor-covenant.org instead of the new in-repo file — repointed it. - The root CONTRIBUTING.md — the one README.md actually links to — had no Code of Conduct section at all. Added one, linking to the new file. Investigated (no code changes, per the workstream's stop-and-ask boundaries): - The v1.5.0 GitHub release sits chronologically between v1.20.0 and v1.21.0 despite its lower semver, AND its 6 assets are all named "StoryCraft.Studio_1.20.0_..." — the project's pre-rebrand name (rebrand to WorldScript Studio shipped in v1.23.0) with a version that doesn't match the release tag at all. Flagged for the final report; deleting/retitling a public release is a maintainer decision. - Issue #60 (vendor-fork audit, "permanent reminder — do not close") already has a 2026-07-28 maintainer comment documenting the audit as done, and `pnpm run verify:vendor` passes all 12 invariants. No action needed — it's correctly staying open per its own instruction.
… drift gate ROADMAP.md still marked v1.24 as "(PLANNED)" though v1.24.0 (2026-06-21) and v1.24.1 (2026-07-28) had both already shipped, and gave the locale count as 17 — stale since the 11->17 expansion (v1.24.0) plus ru/ko (landed the next day, before v1.24.1). Same "17 locales" drift was independently present in docs/TRANSLATION-GUIDE.md (also missing 1 of 21 modules — desktop.json — from its module list and count), the root CONTRIBUTING.md (the one README.md actually links to), .github/copilot-instructions.md (2 occurrences), and docs/i18n/AUDIT_AND_IMPROVEMENT_PLAN.md's "current state" section. Fixed all of them; left every CHANGELOG.md and dated AUDIT.md/TODO.md historical entry untouched — they correctly describe what was true at a past release. Added scripts/check-doc-metrics.mjs (wired into ci.yml's quality job as `pnpm run docs:check`) so this class of drift fails CI instead of silently accumulating again. It computes the actual locale count, key count (dedup'd the same way check-i18n-keys.mjs does), and latest released version tag, then scans README/ROADMAP/TODO/TRANSLATION-GUIDE/CONTRIBUTING for stale numbers or a "vX.Y.Z ... PLANNED" claim for an already-released version. Historical sections are exempt (Keep-a-Changelog `## [x.y.z]`, `## vX.Y.Z ... RELEASED ...`, a heading suffixed with an emoji checkmark, a `**Status:** ✅ Released/Completed` line just below a heading, or this repo's own TODO.md "✅ = done" bullet convention) — the first version only recognized the Keep-a-Changelog/RELEASED-heading shapes and produced 26 false positives against TODO.md/ROADMAP.md's other historical conventions; broadened it before wiring the gate in. tests/unit/checkDocMetrics.test.ts covers the exclusion heuristic directly (the plan's explicit requirement — an untested exclusion rule turns a drift gate into noise).
…n, mutation-testing status - Re-pinned token-audit-baseline.json to the actual measured total (160, down from a stale 165 dated 2026-06-14) after WS-1..6 landed. Ratchets down only, per the project's hard rule against loosening a quality gate. - Added scripts/check-coverage-ratchet.mjs: reads coverage/coverage-summary.json (added the `json-summary` reporter to vitest.config.ts — it wasn't being generated at all) and suggests raising a threshold when the measured value sits 2+ points above it, matching the "3 green runs, max 5 pts/quarter" rule already documented as a comment in vitest.config.ts but never mechanized. Wired into ci.yml as `continue-on-error: true` — informational only, never blocks the build; the ratchet decision stays with the maintainer. - docs/CODE_QUALITY.md: added a Suppression Reduction Plan grouping all 33 noExplicitAny suppressions (of 52 total, at an exact-match baseline with no headroom) into clusters by root cause and effort — no code changes, visibility only. - docs/CI.md: corrected three places that still described Stryker mutation testing as part of the active `ci.yml` job graph (job-graph diagram, the `mutation` job's table row, and the CI-tier table) — it was removed from the merge pipeline on 2026-06-02 and now runs only via manual `workflow_dispatch` on mutation.yml. Documented why, how to trigger it, and the re-integration criterion.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (8)
🚧 Files skipped from review as they are similar to previous changes (8)
📝 WalkthroughWalkthroughThe PR adds documentation metric validation, a non-blocking coverage ratchet check, updated i18n and project metrics, refreshed release and CI documentation, and repository governance guidance. ChangesDocumentation and quality maintenance
Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant CIQualityGate
participant DocumentationChecker
participant RepositoryState
participant CoverageRatchet
CIQualityGate->>DocumentationChecker: run docs:check
DocumentationChecker->>RepositoryState: read locale data, release tags, and documentation
RepositoryState-->>DocumentationChecker: return current metrics and document content
DocumentationChecker-->>CIQualityGate: report drift or success
CIQualityGate->>CoverageRatchet: run informational ratchet check
CoverageRatchet->>RepositoryState: read coverage summary
RepositoryState-->>CoverageRatchet: return coverage metrics
CoverageRatchet-->>CIQualityGate: report ratchet suggestions
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
7 tasks
…module files The new docs:check drift gate (this same branch) immediately caught a real bug on its first CI run: README claimed 2859 i18n keys while the actual deduplicated count is 2849. Root cause is in sync-readme-metrics.mjs itself, not just the (already-fixed-elsewhere) duplicate source keys — getKeyCount() summed leaf counts per module file independently, so any key defined in two files (as 10 keys were, until the PR #281 dedup fix) got counted twice. This is a latent bug: it will silently drift again the moment any future PR reintroduces a cross-module duplicate, regardless of today's specific fix. Changed getKeyCount() to collect keys into a Set across all module files, matching check-i18n-keys.mjs's loadBundleKeys() dedup logic exactly — the two scripts can no longer disagree about the canonical key count.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
🏁 CodeAnt Quality Gate ResultsCommit: ✅ Overall Status: PASSEDQuality Gate Details
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🧹 Nitpick comments (1)
scripts/sync-readme-metrics.mjs (1)
59-72: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winAdd a regression test for cross-module key deduplication.
This is the behavior change that fixes the README drift. Add fixtures with the same key in two English modules and assert it is counted once, so future edits cannot silently restore per-file double counting.
🤖 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 `@scripts/sync-readme-metrics.mjs` around lines 59 - 72, Add a regression test for getKeyCount using English locale fixtures containing the same key in two module JSON files, and assert the result counts that key only once. Keep the test focused on cross-module deduplication and preserve counting of distinct keys.
🤖 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 @.github/CODE_OF_CONDUCT.md:
- Around line 59-64: Update the `SECURITY.md` reference in the reporting
paragraph of `.github/CODE_OF_CONDUCT.md` to use the repository-root relative
path `../SECURITY.md`, matching the existing repository convention and
preserving the link text.
In @.github/workflows/ci.yml:
- Around line 121-122: Update the CI checkout configuration used before the “Doc
metrics drift gate” step so repository tags are fetched, using fetch-tags: true
or fetch-depth: 0. Ensure pnpm run docs:check executes with tag history
available for the stale-PLANNED validation.
In `@docs/CI.md`:
- Around line 84-89: Update the quality row in the CI documentation to list pnpm
run typecheck instead of the direct tsc command, matching the package script and
the command used elsewhere in the document; leave the other quality checks
unchanged.
In `@docs/CODE_QUALITY.md`:
- Around line 58-66: Reconcile the cluster counts in the baseline table so they
clearly account for exactly 52 suppressions. Update the approximate values or
add a concise overlap/rounding explanation, ensuring the displayed cluster
totals and the “52/52 — no headroom” headline are consistent without changing
the documented remediation guidance.
In `@README.md`:
- Around line 460-461: Update the stale locale/module inventory references in
README.md to consistently document 19 locales and 21 modules, matching
docs/TRANSLATION-GUIDE.md and .github/copilot-instructions.md while preserving
the existing inventory format.
In `@scripts/check-coverage-ratchet.mjs`:
- Around line 35-42: Update the coverage-summary loading logic in the
check-coverage-ratchet flow to catch read or JSON.parse failures for malformed
artifacts, then print the existing non-blocking skip message and return.
Preserve the current behavior for valid summaries without a total field and
ensure these failures remain non-failing under the script’s “Always exits 0”
contract.
In `@scripts/check-doc-metrics.mjs`:
- Around line 45-176: Add adjacent one-line comments in
scripts/check-doc-metrics.mjs for the filesystem metric reads in
getActualLocaleCount and getActualKeyCount, tag lookup in
getLatestReleasedVersion, drift scanning in scanForDrift, and CLI orchestration
in main, each using the format “// QNBS-v3: [Grund / Impact / Kreativer
Mehrwert]”. Also add a direct QNBS-v3 rationale beside the non-blocking ratchet
orchestration in scripts/check-coverage-ratchet.mjs; do not alter the logic.
- Around line 19-25: Update the TARGET_FILES list in check-doc-metrics.mjs to
include .github/copilot-instructions.md so docs:check scans the documented drift
source alongside the existing target files.
In `@tests/unit/checkDocMetrics.test.ts`:
- Around line 2-7: Replace the multiline rationale above the tests with one
adjacent single-line QNBS-v3 comment using the required Reason / Impact /
Creative value format, preserving the intent of documenting protection against
historical-section regressions in the drift gate.
---
Nitpick comments:
In `@scripts/sync-readme-metrics.mjs`:
- Around line 59-72: Add a regression test for getKeyCount using English locale
fixtures containing the same key in two module JSON files, and assert the result
counts that key only once. Keep the test focused on cross-module deduplication
and preserve counting of distinct keys.
🪄 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
Run ID: 1d428c73-78e2-4094-b786-0ee05fc8afec
📒 Files selected for processing (20)
.github/CODE_OF_CONDUCT.md.github/CONTRIBUTING.md.github/copilot-instructions.md.github/workflows/ci.ymlCONTRIBUTING.mdREADME.mdROADMAP.mdTODO.mddocs/CI.mddocs/CODE_QUALITY.mddocs/TRANSLATION-GUIDE.mddocs/i18n/AUDIT_AND_IMPROVEMENT_PLAN.mdpackage.jsonscripts/check-coverage-ratchet.mjsscripts/check-doc-metrics.d.mtsscripts/check-doc-metrics.mjsscripts/sync-readme-metrics.mjstests/unit/checkDocMetrics.test.tstoken-audit-baseline.jsonvitest.config.ts
Real bugs found and fixed: - .github/CONTRIBUTING.md linked SECURITY.md as ../SECURITY.md, but that file lives at .github/SECURITY.md — a sibling of CONTRIBUTING.md, not one level up. The link resolved to a nonexistent repo-root file. CodeRabbit anchored this finding on .github/CODE_OF_CONDUCT.md, whose own (correct) sibling link I verified matches; the actual broken link was in CONTRIBUTING.md. - .github/workflows/ci.yml's quality-job checkout never fetched tags, so check-doc-metrics.mjs's stale-PLANNED-status check (which reads `git tag`) silently no-oped in every CI run. Added fetch-tags: true. - check-coverage-ratchet.mjs's JSON.parse had no try/catch — a truncated or invalid coverage-summary.json would throw uncaught, contradicting the script's own documented "always exits 0, never gates CI" contract. Now falls through to the same non-blocking skip message as a missing file. - check-doc-metrics.mjs's TARGET_FILES list didn't include .github/copilot-instructions.md or .github/CONTRIBUTING.md, despite the script's own header comment naming both as files that had the exact stale- locale-count regression this gate exists to catch — a recurrence there would have passed docs:check silently. - docs/CODE_QUALITY.md's suppression cluster table summed to ~53 against the stated 52/52 baseline. Recomputed exact per-cluster counts from `check-suppressions.mjs --details` (11 + 8 + 5 + 9 + 19 = 52) and corrected the useAppSelector/single-occurrence cluster file lists to match. - README.md's project-tree comment still said "15 modules"; the doc-truth-up work elsewhere in this PR already established 19 locales × 21 modules. - docs/CI.md's pipeline table said `tsc` where the actual quality-job step (and package.json) both use `pnpm run typecheck`. Convention-only: - Added the missing single-line QNBS-v3 rationale comments to check-doc-metrics.mjs (filesystem reads, tag lookup, drift scan, CLI orchestration) and check-coverage-ratchet.mjs (non-blocking contract). - Collapsed checkDocMetrics.test.ts's multiline file-header rationale to one line.
Owner
Author
|
@coderabbitai review |
✅ Action performedReview finished.
|
Owner
Author
|
@coderabbitai review |
✅ Action performedReview finished.
|
qnbs
added a commit
that referenced
this pull request
Jul 29, 2026
…, F-10 follow-up) CI's quality job (Node 22 and 24) failed on push: TS2305, module has no exported member 'getCanonicalProductionUrl'. A hand-maintained scripts/check-doc-metrics.d.mts (added in #283) shadows the .mjs source for TypeScript's purposes and wasn't updated with the two new function signatures (getCanonicalProductionUrl, scanForUrlDrift) added in the F-10 workstream. Reproduced locally with rm -f *.tsbuildinfo && pnpm run typecheck -- the earlier "clean" claim in the run log had trusted a background task's "completed, exit code 0" notification summary without reading its actual tail output, the same trap already hit once earlier in this sprint. Fixed by adding the missing declarations; re-verified clean. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
8 tasks
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.
Summary
Recreated PR (was #280, auto-closed by GitHub — see note below). Third stacked PR in the deployment-surface/OpenRouter/doc-gates audit sequence, now targeting
maindirectly since its previous base branch (fix/openrouter-live-catalog) was deleted when PR #279 merged.chore(repo)— fixes README badges (removes duplicate codecov badge, removes the CII Best Practices placeholder badge + adds a TODO.md registration entry since that requires an external interactive signup), adds.github/CODE_OF_CONDUCT.md(Contributor Covenant 2.1), links it from both.github/CONTRIBUTING.mdand the rootCONTRIBUTING.md.chore(docs)— truths up locale/release-status claims across ROADMAP.md/TODO.md/docs/TRANSLATION-GUIDE.md/CONTRIBUTING.md/.github/copilot-instructions.md (stale "17 locales" → 19), addsscripts/check-doc-metrics.mjs(+.d.mts, +checkDocMetrics.test.ts) as a new CI drift gate wired into.github/workflows/ci.ymlandpackage.json'sdocs:checkscript.chore(gates)— documentsscripts/check-coverage-ratchet.mjs(non-blocking, suggests threshold increases), a Suppression Reduction Plan indocs/CODE_QUALITY.md(groups the 33noExplicitAnysuppressions by cluster), and correctsdocs/CI.md's description of Stryker mutation testing's actual (manual-trigger-only) status in the pipeline.Why recreated
The original PR #280 was based on
fix/openrouter-live-catalog. That branch went through several force-pushed rebases during PR #279's CodeRabbit correction loop, and when PR #279 merged (deleting its branch), GitHub couldn't cleanly auto-retarget PR #280 tomainand closed it instead (gh pr reopenconfirmed: "Could not open the pull request — base branch no longer exists"). The underlyingchore/release-doc-gatesbranch and all its commits were unaffected; rebased it directly onto the currentmainand opened this replacement.Test plan
pnpm run docs:check— OK, 19 locales / 2859 keys (dedup fix is PR chore: WS-8 follow-ups — parity audit fix, README caveat, Dependabot auto-merge, locale key dedup #281, not yet merged) / latest v1.24.1pnpm run lint/ typecheck — cleanpnpm run i18n:check— key parity holds🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
CI & Quality Improvements