@alxwlw/repo-rules

Whole-repository checks that came out of a defect corpus: each one is a class of defect that already cost a review round. They run in CI and locally, on Node ≥ 20, with no dependencies.

pnpm add -D @alxwlw/repo-rules
pnpm exec repo-rules baseline --init   # once: record what is already there
pnpm exec repo-rules check             # every run: nothing new, nothing stale
pnpm exec repo-rules diff --base origin/main

repo-rules [-C <dir>] check [--json]
repo-rules [-C <dir>] diff [--base <ref>] [--json]
repo-rules [-C <dir>] baseline [--init] [--allow-grow]

-C <dir> runs in that directory (any place inside the repository). --json prints { violations, stale, notes } instead of text lines. --help prints the usage; a missing or unknown command prints it on stderr and exits 2.

Rules

A reason is at least three non-space characters.

Baseline

.repo-rules-baseline.json records the violations that already exist: line count per long file, hit count per file for the other rules. check fails when a file goes over its entry, and also when an entry is higher than reality (stale), so a fixed place cannot be reused by a new one. baseline only lowers entries; raising one takes --allow-grow, which shows in the PR diff.

Configuration

Optional .repo-rules.json:

{
    "maxLines": 800,
    "exclude": { "*": ["public/vendor/**"], "max-lines": ["docs/*.html"] },
    "testGlobs": [
        "**/*.{test,spec}.*",
        "**/__tests__/**",
        "**/test/**",
        "**/tests/**",
        "**/*.t.sol",
        "**/test_*.py",
        "**/*_test.py"
    ]
}

testGlobs replaces the default list, shown in full above; it does not add to it. exclude takes * or a rule name — the four rules above and removed-assertions.

Limits

• Comments are found by a line heuristic, not a parser: a quote inside a regex literal or JSX text can hide a directive later on that line.
• <!-- --> comments in .vue and .svelte files are not read.
• number-or-default misses || .5, and a ||= default applied to a variable that holds a Number(…) result.
• removed-assertions does not see a test disabled by a rename with no content change (for example a.test.ts → a.test.ts.off).
• removed-assertions reads a line inside a multi-line /* … */ block that does not start with * (for example a re-indented one) as code.
• Assertions moved into a helper count as removed; the Tests-Removed trailer is the way out.
• The scan is line-based and does not know whether a line sits inside a string or a template literal, so .only( or .skip( inside a fixture string is flagged.

CI

- uses: actions/checkout@v5
  with:
    fetch-depth: 0 # diff needs the merge-base
- run: pnpm exec repo-rules check
- run: pnpm exec repo-rules diff # base = origin/$GITHUB_BASE_REF in a pull_request job, skipped otherwise

Exit codes: 0 clean, 1 violations or stale baseline, 2 error (never read as clean).