Skip to content

docs: describe check:file-size PR mode accurately #15345

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
diegosouzapw merged 2 commits into from
Oct 6, 2026
Merged

docs: describe check:file-size PR mode accurately #15345

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d1f0a4f
docs: describe check:file-size PR mode accurately
woodsonl Oct 2, 2026
1499db6
chore: add the changelog fragment for #15345
woodsonl Oct 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/maintenance/15345-quality-gates-file-size-doc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **docs:** `QUALITY_GATES.md` describes the `check:file-size` PR mode as the whole-tree, base-relative check it runs, and its gate-table row states the source and test-file caps ([#15345](https://github.com/diegosouzapw/OmniRoute/pull/15345)) — thanks @woodsonl
16 changes: 11 additions & 5 deletions docs/architecture/QUALITY_GATES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ Runs on every PR to `main`. Blocks merge on failure.
| `check:tracked-artifacts` | No build artifacts / committed `node_modules` symlinks (also runs in husky pre-commit; pre-push is intentionally light — #6716) | Yes |
| `check:ai-attribution` | No AI/bot `Co-Authored-By` trailer or AI-generation footer in PR commits, title or body — Hard Rule #16 (in the `quality.yml` fast-gates loop for PR→`release/**` — reads the event payload, no-op off PRs — and a PR-only step in `ci.yml` lint for PR→`main`; also the husky `commit-msg` hook; human co-authors allowed; #14436) |
| `check:vitest-exclusions` | Every Vitest exclusion names a tracking issue and appears in `config/quality/vitest-exclusions.json` (#13204) | Yes |
| `check:file-size` | No source file exceeds the per-extension cap (ratchet: frozen large files in `frozen` list) | Yes |
| `check:file-size` | Source files (`.ts`/`.tsx` in `src/`, `open-sse/`, `electron/`, `bin/`) stay within `cap` and test files (`*.test.ts(x)`) within `testCap`; files frozen in `file-size-baseline.json` (`frozen` / `testFrozen`) must not grow past their recorded size | Yes |
| `check:error-helper` | Error responses in executors/handlers use `buildErrorBody()` / `sanitizeErrorMessage()` (Hard Rule #12) | Yes |
| `check:migration-numbering` | Migration SQL files are sequentially numbered, no gaps or duplicates | Yes |
| `check:public-creds` | No literal OAuth `client_id`/`client_secret` or Firebase Web keys outside `publicCreds.ts` (Hard Rule #11) | Yes |
Expand Down Expand Up @@ -317,16 +317,22 @@ docs/env contract, i18n parity, unit tests) are unchanged — a red test is stil
**New-code mode (Clean-as-You-Code) — since 2026-08-30, PR fast-path only**

On `pull_request` events `quality.yml` passes `--base-ref <PR base SHA>` to `check:file-size`,
`check:complexity-ratchets` and `check:dead-code`. In that mode the gate compares HEAD with the
merge-base **restricted to the files the PR touched** (`scripts/check/newCodeMode.mjs`: the
merge-base is materialized in a throwaway `git worktree`, ESLint/knip run there and on HEAD, the
per-file counts are diffed):
`check:complexity-ratchets` and `check:dead-code`. For `check:complexity-ratchets` and
`check:dead-code` the gate compares HEAD with the merge-base **restricted to the files the PR
touched** (`scripts/check/newCodeMode.mjs`: the merge-base is materialized in a throwaway
`git worktree`, ESLint/knip run there and on HEAD, the per-file counts are diffed):

- **blocking** — the PR added cyclomatic/cognitive violations or dead exports in files it changed
(`complexityNewCode=`, `cognitiveComplexityNewCode=`, `deadExportsNewCode=` in the log);
- **advisory** — the global total vs. the frozen baseline. Inherited drift never reds an
innocent PR; the drift is re-frozen at release reconciliation and watched by the headroom job.

`check:file-size` uses the base ref on its own terms (`scripts/check/check-file-size.mjs`, #8522):
it checks every source and test file in the tree, reads each one's line count at the PR base
with `git show`, and fails a file only when it grows past the larger of its baseline ceiling
(`frozen` / `testFrozen`, or `cap` / `testCap` for a file outside the baseline) and its base
size. A file that already drifted on the base therefore never reds an innocent PR.

`workflow_dispatch` runs, the release-green sweep and the nightly headroom job have no PR base
and keep the absolute (global) comparison. Coverage, duplication and type-coverage stay global
for now (their tools do not produce a per-file diff cheaply) — candidates for the same treatment.
Expand Down
Loading