cursedbelt 4.1.1 → 4.4.0

package/scripts/guardrailsEnforce.spec.ts

@@ -1,8 +1,13 @@
+// 🔴 `package.json`'s `test` script globs `src scripts`, not `src` — this file is the only
+// spec outside `src`, and until 2026-09-18 nothing ran it. The gate was green while every
+// assertion in here (129 of them, the scanner's entire behavioural contract) was inert, so a
+// rule could rot and `bun run verify` would still say ok. If you narrow that glob back, the
+// tests below stop being checks and become a document.
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { describe, expect, test } from 'bun:test';
-import { parseFileAllows, RULES, setReimplementedNames, walk } from './guardrailsEnforce';
+import { beltExportedComponentNames, parseFileAllows, RULES, setReimplementedNames, walk } from './guardrailsEnforce';
 
 function check(rule: keyof typeof RULES, source: string) {
   return RULES[rule].check('test.tsx', source);
@@ -107,6 +112,70 @@ describe('opening-tag extraction (comment-aware)', () => {
   });
 });
 
+// Filed 2026-09-18, found while proving the fix above: the first negative test came back
+// green for the WRONG reason. Making the walker comment-aware widened what it returns, and
+// the opt-out checks then read prose with regexes that look for a real ATTRIBUTE — so a
+// comment merely QUOTING `role="radio"` suppressed no-raw-action-button on a raw button
+// that had no presentational role at all. The rule could not be trusted to read zero in
+// exactly the well-documented files it should be strictest about. The input was wrong, not
+// the pattern: the comment check reads the tag as written, the attribute check reads it
+// comment-blanked.
+describe('a presentational marker must be an ATTRIBUTE, not prose about one', () => {
+  test('role="radio" only inside a comment does NOT opt the button out', () => {
+    const source = `<button
+      // A radio-like list: \`role="radio"\` + \`aria-checked\` says so to a screen reader.
+      type="button"
+      onClick={() => onPick(id)}
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(1);
+  });
+
+  test('aria-selected= only inside a block comment does NOT opt the button out', () => {
+    const source = `<button
+      /* The row is the control here; aria-selected= would be the tab-ish spelling. */
+      type="button"
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(1);
+  });
+
+  test('the guardrails-ignore comment still opts out beside that same prose', () => {
+    const source = `<button
+      // A radio-like list: \`role="radio"\` + \`aria-checked\` says so to a screen reader.
+      // guardrails-ignore no-raw-action-button: presentational row in a radio-like list
+      type="button"
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(0);
+  });
+
+  test('the REAL attributes still pass silently, prose and all', () => {
+    const source = `<button
+      // A radio-like list: \`role="radio"\` + \`aria-checked\` says so to a screen reader.
+      role="radio"
+      aria-checked={selected}
+      type="button"
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(0);
+  });
+
+  // The same shape on no-raw-title-attr, which fires the other way: there the attribute
+  // regex is what CREATES the violation, so prose mentioning `title=` invented one.
+  test('a title= written only in a comment is not a title attribute', () => {
+    const source = `<span
+      // Not a title= hover hint — the expansion is rendered beside it.
+      className="tabular"
+    >UTC</span>`;
+    expect(check('no-raw-title-attr', source)).toHaveLength(0);
+  });
+
+  test('a real title attribute below that prose is still flagged', () => {
+    const source = `<span
+      // Reads as a title= hover hint, and that is the bug.
+      title="Coordinated Universal Time"
+    >UTC</span>`;
+    expect(check('no-raw-title-attr', source)).toHaveLength(1);
+  });
+});
+
 describe('no-raw-overflow', () => {
   test('flags inline style overflow: auto', () => {
     expect(check('no-raw-overflow', '<div style={{ overflow: "auto" }} />')).toHaveLength(1);
@@ -864,3 +933,246 @@ describe('no-fast-tooltip', () => {
     ).toHaveLength(0);
   });
 });
+
+// ── the CLI's two ratchets, and the flags that let an app use one ──────────────
+// Nine apps each carried an identical ~140-line wrapper (`apps/*/scripts/guardrails.ts`)
+// because this CLI could only read the baseline shipped INSIDE the package. These
+// exercise the flags that replaced them, as a subprocess — the wrappers' only contract
+// was this script's exit code and its verdict lines, and that is what an app's `verify`
+// still depends on.
+
+const CLI = join(import.meta.dir, 'guardrailsEnforce.ts');
+
+function withFixture(files: Record<string, string>, body: (dir: string) => void): void {
+  const root = mkdtempSync(join(tmpdir(), 'guardrails-cli-'));
+  try {
+    for (const [rel, contents] of Object.entries(files)) {
+      const full = join(root, rel);
+      mkdirSync(join(full, '..'), { recursive: true });
+      writeFileSync(full, contents);
+    }
+    body(root);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function runCli(cwd: string, args: string[]): { code: number; report: string } {
+  const run = Bun.spawnSync([process.execPath, CLI, ...args], { cwd });
+  return { code: run.exitCode, report: `${run.stdout.toString()}${run.stderr.toString()}` };
+}
+
+/** Two hex colours and one raw <input>: counts a baseline row can be wrong about. */
+const FIXTURE = {
+  'src/ui/theme.css': '.a { color: #ff0000; }\n.b { background: #00ff00; }\n',
+  'src/ui/Form.tsx': 'export const Form = () => <input name="q" />;\n',
+};
+
+const rowsFor = (colors: number, inputs: number) =>
+  JSON.stringify({ 'no-hardcoded-colors': colors, 'no-raw-inputs': inputs });
+
+describe('--baseline (a consuming repo\'s ratchet)', () => {
+  test('passes when every row equals the count that is actually there', () => {
+    withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 1) }, (dir) => {
+      const { code, report } = runCli(dir, [
+        'no-hardcoded-colors,no-raw-inputs',
+        '--baseline',
+        'scripts/baseline.json',
+        'src',
+      ]);
+      expect(report).toContain('✓ no-hardcoded-colors: 2 violation(s)');
+      expect(report).toContain('✓ no-raw-inputs: 1 violation(s)');
+      expect(code).toBe(0);
+    });
+  });
+
+  test('🔴 a row ABOVE the real count FAILS, printing the number to paste', () => {
+    // The half a one-sided ratchet gets wrong: fix a violation, leave the row where it
+    // was, and the slack is available for the next one to grow back into silently.
+    withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(9, 1) }, (dir) => {
+      const { code, report } = runCli(dir, [
+        'no-hardcoded-colors,no-raw-inputs',
+        '--baseline',
+        'scripts/baseline.json',
+        'src',
+      ]);
+      expect(code).toBe(1);
+      expect(report).toContain('✗ no-hardcoded-colors: 2 violation(s), below the baseline of 9');
+      expect(report).toContain('lower "no-hardcoded-colors" to 2 in scripts/baseline.json');
+    });
+  });
+
+  test('a count above its row fails, the way it always did', () => {
+    withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 0) }, (dir) => {
+      const { code, report } = runCli(dir, [
+        'no-hardcoded-colors,no-raw-inputs',
+        '--baseline',
+        'scripts/baseline.json',
+        'src',
+      ]);
+      expect(code).toBe(1);
+      expect(report).toContain('✗ no-raw-inputs: 1 violation(s) — exceeds baseline of 0');
+    });
+  });
+
+  test('a row for a rule nobody scans is refused — coverage that is not there', () => {
+    withFixture(
+      { ...FIXTURE, 'scripts/baseline.json': JSON.stringify({ 'no-hardcoded-colors': 2, 'no-raw-zindex': 0 }) },
+      (dir) => {
+        const { code, report } = runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/baseline.json', 'src']);
+        expect(code).toBe(2);
+        expect(report).toContain('row(s) for rules nobody scans: no-raw-zindex');
+      },
+    );
+  });
+
+  test('a scanned rule with no row is refused — a silent 0 demands the whole pile at once', () => {
+    withFixture({ ...FIXTURE, 'scripts/baseline.json': JSON.stringify({ 'no-hardcoded-colors': 2 }) }, (dir) => {
+      const { code, report } = runCli(dir, [
+        'no-hardcoded-colors,no-raw-inputs',
+        '--baseline',
+        'scripts/baseline.json',
+        'src',
+      ]);
+      expect(code).toBe(2);
+      expect(report).toContain('no row for rule(s) being scanned: no-raw-inputs');
+    });
+  });
+
+  test('"$comment" carries the why; any OTHER non-number is a typo in a row', () => {
+    withFixture(
+      {
+        ...FIXTURE,
+        'scripts/baseline.json': JSON.stringify({ $comment: ['the why', 'over several lines'], 'no-hardcoded-colors': 2 }),
+      },
+      (dir) => {
+        expect(runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/baseline.json', 'src']).code).toBe(0);
+      },
+    );
+    withFixture({ ...FIXTURE, 'scripts/baseline.json': JSON.stringify({ 'no-hardcoded-colors': '2' }) }, (dir) => {
+      const { code, report } = runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/baseline.json', 'src']);
+      expect(code).toBe(2);
+      expect(report).toContain('"no-hardcoded-colors" is "2", not a violation count');
+    });
+  });
+
+  test('a missing baseline file stops the run rather than defaulting every row to 0', () => {
+    withFixture(FIXTURE, (dir) => {
+      const { code, report } = runCli(dir, ['no-hardcoded-colors', '--baseline', 'scripts/nope.json', 'src']);
+      expect(code).toBe(2);
+      expect(report).toContain('no such file');
+    });
+  });
+
+  test('is not the packaged --scope ratchet, and says so rather than picking one', () => {
+    withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 1) }, (dir) => {
+      const { code, report } = runCli(dir, [
+        'no-hardcoded-colors',
+        '--scope',
+        'cursedbelt',
+        '--baseline',
+        'scripts/baseline.json',
+        'src',
+      ]);
+      expect(code).toBe(2);
+      expect(report).toContain('two different ratchets');
+    });
+  });
+
+  test('--scope stays ONE-sided: below its row passes and only suggests', () => {
+    // The packaged baseline lives inside node_modules, so a consumer cannot lower a row
+    // in it. Failing them for a number only a cursedbelt release can change would be a
+    // gate nobody can turn green — which is why only --baseline is two-sided.
+    withFixture(FIXTURE, (dir) => {
+      const { code, report } = runCli(dir, ['no-hardcoded-colors', '--scope', 'cursedbelt', 'src']);
+      expect(code).toBe(1); // 2 found against the packaged cursedbelt row of 0
+      expect(report).toContain('exceeds baseline of 0');
+    });
+  });
+});
+
+describe('--reimplements-from-belt', () => {
+  test('flags a local component named after one this package exports', () => {
+    // Read off this package's own react index files, so the list is the truth of the
+    // version an app installed rather than a copy it maintains.
+    withFixture(
+      {
+        'src/Button.tsx': 'export function Button() { return null; }\n',
+        'scripts/baseline.json': JSON.stringify({ 'no-local-reimplementation': 0 }),
+      },
+      (dir) => {
+        const { code, report } = runCli(dir, [
+          'no-local-reimplementation',
+          '--baseline',
+          'scripts/baseline.json',
+          '--reimplements-from-belt',
+          'src',
+        ]);
+        expect(code).toBe(1);
+        expect(report).toContain('✗ no-local-reimplementation: 1 violation(s)');
+        expect(report).toContain('src/Button.tsx');
+      },
+    );
+  });
+
+  test('the derived list is this package\'s real exports, not a handful', () => {
+    const names = beltExportedComponentNames();
+    expect(names.length).toBeGreaterThan(100);
+    expect(names).toContain('Button');
+    expect(names).toContain('DataTable');
+  });
+
+  test('🔴 fails CLOSED on an empty list rather than scoring an inert rule 0', () => {
+    // Without this, a moved react tree makes `no-local-reimplementation` print
+    // "0 violation(s)" for a check that never ran, and its 0 row looks earned.
+    const empty = mkdtempSync(join(tmpdir(), 'guardrails-belt-'));
+    try {
+      expect(beltExportedComponentNames(empty)).toEqual([]);
+    } finally {
+      rmSync(empty, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('--exclude', () => {
+  test('drops build output that lives under a source root', () => {
+    // desk's `src/generated/assets.ts` is the compiled browser app inlined as a module:
+    // 282 double-counted violations that move with the bundle, reddening a two-sided
+    // ratchet over work nobody did.
+    const files = {
+      ...FIXTURE,
+      'src/generated/assets.css': '.x { color: #123456; }\n.y { color: #654321; }\n',
+      'scripts/baseline.json': rowsFor(2, 1),
+    };
+    withFixture(files, (dir) => {
+      const scanned = runCli(dir, ['no-hardcoded-colors,no-raw-inputs', '--baseline', 'scripts/baseline.json', 'src']);
+      expect(scanned.code).toBe(1); // 4 colours, not 2 — the artifact counted as source
+
+      const { code, report } = runCli(dir, [
+        'no-hardcoded-colors,no-raw-inputs',
+        '--baseline',
+        'scripts/baseline.json',
+        '--exclude',
+        'src/generated',
+        'src',
+      ]);
+      expect(report).toContain('✓ no-hardcoded-colors: 2 violation(s)');
+      expect(code).toBe(0);
+    });
+  });
+
+  test('an exclusion matching nothing is refused, never read as handled', () => {
+    withFixture({ ...FIXTURE, 'scripts/baseline.json': rowsFor(2, 1) }, (dir) => {
+      const { code, report } = runCli(dir, [
+        'no-hardcoded-colors,no-raw-inputs',
+        '--baseline',
+        'scripts/baseline.json',
+        '--exclude',
+        'src/generated',
+        'src',
+      ]);
+      expect(code).toBe(2);
+      expect(report).toContain('--exclude matched no scanned file');
+    });
+  });
+});