Skip to content

ci: guard code and docs against growth by appending - #733

Merged
eizedev merged 2 commits into
mainfrom
ci/growth-guards
Nov 22, 2026
Merged

eizedev merged 2 commits into
mainfrom
ci/growth-guards

Conversation

@eizedev

@eizedev eizedev commented Nov 22, 2026

Copy link
Copy Markdown
Owner

The code and the docs grew mostly by appending. This adds four checks so they can only shrink from here, without fixing the existing offenders.

npm run growth runs them. CI runs each one as its own step in the test job (Node 24).

The guards

  • Functions: ESLint's max-lines-per-function (120 lines, blank lines and comments not counted) and complexity (25) over packages/*/src. ESLint's defaults are 50 and 20. Airbnb lists the same values but switches both rules off; xo warns on complexity at the default. At 50/20 half the code would be listed, so the limits start where the outliers begin: 49 functions over 120 lines, 106 over complexity 25.
  • Unused exports and files: knip 6.45.1 with knip.json. Package entry points and the build entries (esbuild, test pages, type tests) count as used, so public API is not reported. 228 findings today. The analysis counted about 309 exports used outside their own file; knip also counts use by tests and only reports exports nobody imports.
  • Duplication: jscpd 5.4.3 over packages/*/src (.jscpd.json). Today 0.31 %, threshold 0.35 %.
  • Docs: lines per page by kind: use/ 300 (one task), concepts/ and embed/ 300, getting-started/ 400 (read in one go), reference/ 600 (looked up), decisions/ 150, pages directly in docs/ 400. Each limit sits at the upper end of that kind's ordinary pages, so 19 pages are listed, reference/rest.md (2,036 lines) the largest. The total (25,817 lines) is recorded; it may drift 1 % before the baseline must follow, so parallel docs PRs do not all edit the same line.

The ratchet

scripts/growth-baseline.json lists today's offenders with their numbers, sorted, one per line. It is written by node scripts/growth.js --update.

  • A listed function or page that grows, or a new one, fails.
  • One that shrank or went also fails, until --update lowers the baseline in the same PR.
  • --update never raises an entry. --accept-growth does, and the PR says why. A renamed or moved function counts as new.
  • Anonymous functions of one file compare by their sorted numbers, so a new callback does not shift the old ones.
  • Each guard fails closed: unexpected ESLint wording or knip output throws instead of reporting nothing. eslint-disable comments do not hide a function.

Why not plain ESLint rules or bulk suppressions

ESLint's bulk suppressions count violations per file and rule, so a 300-line function that grows to 400 lines would pass. The rules therefore run through the ESLint API in scripts/growth.js with the numbers kept in the baseline, not in eslint.config.js; editors do not show them.

Notes

  • knip and jscpd are dev dependencies only. They bring native binaries as optional platform packages (oxc parser and resolver, jscpd's Rust build). None has an install script. Licences: knip ISC, jscpd MIT.
  • knip releases often. A Dependabot bump can change its findings and then needs --update.
  • build(deps): Bump @playwright/test from 1.65.0 to 1.65.1 #677 also touches package.json and package-lock.json; whichever merges second needs a rebase.

Checked: npm run lint, npm run types, npm test, npm run growth. Places: AGENTS.md (Commands), CONTRIBUTING.md (Check your change), tests/AGENTS.md (Repository checks), eslint.config.js header. No package changed, so no package changelog.

🤖 Generated with Claude Code

eizedev and others added 2 commits November 22, 2026 17:51
Four checks in scripts/growth.js, each its own step in CI's test job:
function length and complexity (ESLint), unused exports and files (knip),
duplicated code (jscpd) and lines per docs page. Functions, unused code
and docs pages are ratchets on scripts/growth-baseline.json: an offender
may not grow, none may be added, and one that shrank lowers the baseline
in the same pull request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The disable comments no longer hide a function, the docs total and the
duplication threshold sit closer to today's values, unknown options and
a baseline without a section fail, and AGENTS.md names the baseline and
how to lower it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eizedev
eizedev merged commit 569ba63 into main Nov 22, 2026
25 checks passed
@eizedev
eizedev deleted the ci/growth-guards branch November 22, 2026 17:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant