@nielspeter/eess-ts 0.2.0 → 0.4.0

package/dist/cli/rule-file-findings.d.ts

@@ -0,0 +1,178 @@
+import type { ArchViolation } from '@nielspeter/eess';
+/**
+ * Attribute findings that have no source location of their own to the rule file
+ * they came from.
+ *
+ * [ts-archunit Bug 0026](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0026-a-location-less-finding-does-not-say-which-rule-file-it-came-from.md):
+ * a configuration finding carries `file: ''` because it reports a fault in the
+ * rule rather than in the code, so two identical vacuous rules in two rule files
+ * rendered as two identical paragraphs with nothing saying which to open. In a
+ * test the frame comes free from vitest; in the CLI — the golden-path default —
+ * nothing supplied it, even though this loop knows the file and was discarding it.
+ *
+ * `line: 1`, following `tsconfig()`'s precedent for a fault that belongs to a
+ * file rather than to a position in it (`docs/config-rules.md` documents that
+ * choice). The builders cannot know the line: a rule with no glob has no
+ * position anywhere, and the assertion-gate findings are exactly the rules that
+ * may have none. Not `line: 0` — `::error file=x,line=0` is not a valid GitHub
+ * annotation and gets dropped or misplaced.
+ *
+ * **Safe against a `eess-exclude` comment only because these findings carry
+ * `bypassFilters`.** `execute-rule.ts` filters comment exclusions with
+ * `v.bypassFilters === true || !isExcludedByComment(...)`, and that first clause
+ * is what stops a real path here from making the finding suppressible by a
+ * comment in the rule file. It was written for this exact temptation, and until
+ * this change nothing tested it, because no such finding had a readable path.
+ * `tests/helpers/exclusion-comments.test.ts` now pins it.
+ */
+export declare function attributeToRuleFile(violations: readonly ArchViolation[], file: string): ArchViolation[];
+/**
+ * A rule file, or one rule in it, that could not be evaluated at all.
+ *
+ * [ts-archunit Bug 0025](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0025-a-non-archruleerror-from-one-rule-file-drops-every-other-finding.md):
+ * `runCheck` and `runBaseline` caught `ArchRuleError` and rethrew everything
+ * else, so any other error escaped the per-file loop and terminated the process
+ * — no report written, no exit code returned, and every finding already
+ * collected discarded. Measured: one malformed `crossProject()` in one file
+ * silenced a second file's four real violations, and printed a raw Node stack
+ * trace with `node_modules` paths in their place.
+ *
+ * Reported as a **configuration finding** (`bypassFilters`): a rule that could
+ * not run enforced nothing, which is not a violation of the rule and is not
+ * something to accept into a baseline. Same reasoning as the assertion gate,
+ * and it inherits the same treatment — `error` severity whatever the rule
+ * asked for, refused by `.excluding()`, skipped by diff and baseline.
+ *
+ * `line: 1` with the rule file as `file`, following `tsconfig()`'s precedent for
+ * a fault that belongs to a file rather than to a position in it. Not `line: 0`:
+ * `::error file=x,line=0` is not a valid GitHub annotation and gets dropped or
+ * misplaced (the v0.22.0 defect), and only a `file` of `''` takes the run-level
+ * branch that avoids it.
+ */
+export declare function ruleFileFailure(file: string, error: unknown, ruleFiles: number): ArchViolation;
+/**
+ * What to collect when evaluating a rule file, or one rule in it, threw.
+ *
+ * An `ArchRuleError` already carries findings — those ARE the report, and this
+ * is the pre-existing path for a rule file that self-executes a failing
+ * `.check()` at import. Anything else becomes one configuration finding naming
+ * the file. Never a rethrow: that discarded every finding already collected in
+ * the run, including other files' (bug 0025).
+ *
+ * One definition, imported by both `runCheck` and `runBaseline`. They had a copy
+ * each for the ArchRuleError half and the two had already diverged in what they
+ * did with everything else.
+ */
+export declare function failureOrViolations(file: string, error: unknown, ruleFiles: number): ArchViolation[];
+/**
+ * A rule file stopped evaluating partway, so the rules after that point never ran.
+ *
+ * [ts-archunit Bug 0029](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0029-a-throwing-warn-truncates-the-rest-of-the-rule-file.md),
+ * and the half [ts-archunit plan 0069](https://github.com/nielspeter/ts-archunit/blob/main/plans/completed/0069-no-rule-may-certify-nothing.md)'s R3a
+ * specified and did not build: *"R3a states the semantics, and the CLI **reports the
+ * truncation rather than absorbing it**."* The semantics shipped in v0.23.0; this is
+ * the reporting.
+ *
+ * In a **self-executing** rule file — the shape `init` scaffolds and `docs/cli.md`
+ * documents — every rule calls its own terminal at module scope. A throw there aborts
+ * the module, so every rule declared after it is never evaluated. The CLI then folds
+ * the thrown finding into the run and the output looks entirely ordinary. Measured on
+ * v0.28.0, the same two rules in each style:
+ *
+ * | rule file shape                  | findings reported |
+ * | -------------------------------- | ----------------- |
+ * | `export default [rule1, rule2]`  | **5** — the configuration finding and all four violations |
+ * | self-executing                   | **1** — the four violations silently absent |
+ *
+ * Worse than a crash, because the run is **red for the other finding**: someone fixes
+ * that, moves on, and never learns the rest of the file was skipped — or takes the
+ * sanctioned remedy for a dead glob, which is to delete the rule, and still never
+ * learns it.
+ *
+ * **What this can and cannot say.** The module never finished, so the CLI cannot know
+ * *what* was lost — only that anything after the throw did not run. Naming a count or
+ * a rule would be invention. It says the file stopped and what to do, which is all it
+ * has.
+ *
+ * `bypassFilters` because it reports missing coverage: nothing to grade, exclude or
+ * accept into a baseline.
+ */
+export declare function ruleFileTruncated(file: string, ruleFiles: number): ArchViolation;
+/**
+ * `--baseline` was passed, but the rule file printed findings the baseline never
+ * filtered. Bug 0199.
+ *
+ * **The mechanism, corrected TWICE. This is the third version and the measured one.**
+ *
+ * 1. *"The preset throws before baseline filtering runs."* False. `runCheck` collects
+ *    a thrown terminal's violations off the error (`failureOrViolations`) and filters
+ *    them; measured, its collection came back empty against a matching baseline.
+ * 2. *"`setCallerAggregatesReports` is module state that does not cross jiti's
+ *    registry."* Also false, and it was the premise of a whole record. The flag is
+ *    read at exactly ONE site — `core/execute-rule.ts`, inside `executeWarn`.
+ *    And jiti is not even the default loader: `cli/import-rule-module.ts` imports
+ *    natively first and reaches jiti only on a module-format refusal.
+ * (Line numbers deliberately omitted: the fix for (3) moved every one of them,
+ * and the first version of this docblock cited three that had already drifted.)
+ *
+ * 3. **What is actually true:** `executeCheck` calls `writeReport(...)`
+ *    **unconditionally** at `core/execute-rule.ts`, one line before it throws.
+ *    A `.check()` at module scope therefore prints its findings always — same
+ *    registry, no jiti, no flag involved. The CLI cannot un-print them.
+ *
+ * The disproof of (2) is one line: a fixture importing the same module graph as the
+ * test's `runCheck`, so the flag was fully visible, printed all four violations
+ * anyway.
+ *
+ * **Why a notice and not the repair.** Making `executeCheck` honour the flag is a
+ * change to when a terminal emits — ADR-008 territory, and it would alter behaviour
+ * for every caller that relies on `.check()` printing, including test files. That is
+ * bug 0201. Until it is decided the run must not be silent about output it could not
+ * filter.
+ *
+ * **Fires only when something was actually printed.** `executeWarn` throws the same
+ * error type, and when the CLI aggregates it writes only non-`bypassFilters` entries
+ * — for a configuration finding, nothing at all. The first version fired on the bare
+ * `isArchRuleError` condition and so claimed a leak that never happened, pointing at
+ * a finding whose own text says a baseline can never suppress it. Asserting a cause
+ * the run cannot verify is the ADR-009 rule 2 defect `ruleFileFailure` names above.
+ *
+ * **What this can and cannot say.** The leaked lines were written before the CLI saw
+ * them, so it cannot know how many there were. Naming a count would be invention.
+ *
+ * `bypassFilters` because it reports a gap in filtering — accepting it into a
+ * baseline would suppress the notice that the baseline is not being applied.
+ */
+export declare function baselineNotApplied(file: string, filters: {
+    baseline?: string;
+    changed: boolean;
+}): ArchViolation;
+/**
+ * A rule file loaded cleanly and contributed **zero** rules.
+ *
+ * `check` used to print `✓ eess-ts — 0 rules across 1 file · 0 failing` and exit 0
+ * over exactly this, while `doctor` on the same file already refused it with "no
+ * rules found in the given files". Two commands in one CLI disagreeing about
+ * whether "no rules" is an error, and the one wired into CI was the one blessing
+ * it.
+ *
+ * **The shape that makes it urgent** is a migration from `@nielspeter/ts-archunit`,
+ * whose `recommended()` returned builders unconditionally and had no `report`
+ * option. eess-ts's runs and throws by default, so the line ts-archunit's own
+ * `init` scaffolded — `export default [...recommended(p)]` — spreads a *violations*
+ * array. On a codebase with findings that fails loudly (the loader rejects a
+ * non-builder entry). **On a clean codebase the array is empty**, so the file
+ * exports `[]`, the CLI loads nothing, and the run is green with every rule gone.
+ * `tsc --noEmit` passes; nothing reaches stderr.
+ *
+ * The adopter this hits is the one who did the baseline work and cleaned up.
+ *
+ * `CLAUDE.md` already tells agents that a zero denominator "means the gate matched
+ * little or nothing — treat that as a red flag". This makes the CLI agree with its
+ * own instruction instead of printing `✓` over its alarm value.
+ *
+ * `bypassFilters` because it reports absent coverage: there is nothing to grade,
+ * exclude, or accept into a baseline.
+ */
+export declare function ruleFileContributedNoRules(file: string): ArchViolation;
+//# sourceMappingURL=rule-file-findings.d.ts.map

package/dist/cli/rule-file-findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-file-findings.d.ts","sourceRoot":"","sources":["../../src/cli/rule-file-findings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,IAAI,EAAE,MAAM,GACX,aAAa,EAAE,CAEjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,CA0B9F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,aAAa,EAAE,CAEjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,CAqBhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC/C,aAAa,CAkDf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAsBtE"}

package/dist/cli/rule-file-findings.js

@@ -0,0 +1,293 @@
+import { isArchRuleError } from '@nielspeter/eess';
+import { basename } from 'node:path';
+/**
+ * Attribute findings that have no source location of their own to the rule file
+ * they came from.
+ *
+ * [ts-archunit Bug 0026](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0026-a-location-less-finding-does-not-say-which-rule-file-it-came-from.md):
+ * a configuration finding carries `file: ''` because it reports a fault in the
+ * rule rather than in the code, so two identical vacuous rules in two rule files
+ * rendered as two identical paragraphs with nothing saying which to open. In a
+ * test the frame comes free from vitest; in the CLI — the golden-path default —
+ * nothing supplied it, even though this loop knows the file and was discarding it.
+ *
+ * `line: 1`, following `tsconfig()`'s precedent for a fault that belongs to a
+ * file rather than to a position in it (`docs/config-rules.md` documents that
+ * choice). The builders cannot know the line: a rule with no glob has no
+ * position anywhere, and the assertion-gate findings are exactly the rules that
+ * may have none. Not `line: 0` — `::error file=x,line=0` is not a valid GitHub
+ * annotation and gets dropped or misplaced.
+ *
+ * **Safe against a `eess-exclude` comment only because these findings carry
+ * `bypassFilters`.** `execute-rule.ts` filters comment exclusions with
+ * `v.bypassFilters === true || !isExcludedByComment(...)`, and that first clause
+ * is what stops a real path here from making the finding suppressible by a
+ * comment in the rule file. It was written for this exact temptation, and until
+ * this change nothing tested it, because no such finding had a readable path.
+ * `tests/helpers/exclusion-comments.test.ts` now pins it.
+ */
+export function attributeToRuleFile(violations, file) {
+    return violations.map((v) => (v.file === '' ? { ...v, file, line: 1 } : v));
+}
+/**
+ * A rule file, or one rule in it, that could not be evaluated at all.
+ *
+ * [ts-archunit Bug 0025](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0025-a-non-archruleerror-from-one-rule-file-drops-every-other-finding.md):
+ * `runCheck` and `runBaseline` caught `ArchRuleError` and rethrew everything
+ * else, so any other error escaped the per-file loop and terminated the process
+ * — no report written, no exit code returned, and every finding already
+ * collected discarded. Measured: one malformed `crossProject()` in one file
+ * silenced a second file's four real violations, and printed a raw Node stack
+ * trace with `node_modules` paths in their place.
+ *
+ * Reported as a **configuration finding** (`bypassFilters`): a rule that could
+ * not run enforced nothing, which is not a violation of the rule and is not
+ * something to accept into a baseline. Same reasoning as the assertion gate,
+ * and it inherits the same treatment — `error` severity whatever the rule
+ * asked for, refused by `.excluding()`, skipped by diff and baseline.
+ *
+ * `line: 1` with the rule file as `file`, following `tsconfig()`'s precedent for
+ * a fault that belongs to a file rather than to a position in it. Not `line: 0`:
+ * `::error file=x,line=0` is not a valid GitHub annotation and gets dropped or
+ * misplaced (the v0.22.0 defect), and only a `file` of `''` takes the run-level
+ * branch that avoids it.
+ */
+// eess-exclude eess/no-unused-exports: consumed by the test suite; the build tsconfig this gate reads excludes tests, so `src` is the only usage it can see
+export function ruleFileFailure(file, error, ruleFiles) {
+    const raw = error instanceof Error ? error.message : String(error);
+    // An error message may or may not end in punctuation, and the sentence after
+    // it ran straight on: "…(reading 'config') The other rule files…". Measured on
+    // the real CLI, which is the only place the two strings meet.
+    const detail = /[.!?]$/.test(raw.trimEnd()) ? raw.trimEnd() : `${raw.trimEnd()}.`;
+    const others = ruleFiles > 1 ? ' The other rule files in this run were still checked.' : '';
+    return {
+        // The path goes in `file` and nowhere else it would be re-rendered. It used
+        // to appear four times in one finding — in `rule`, in `element`, in the
+        // location line, and in the remedy — and the location line renders it
+        // through `path.relative(cwd, …)`, so a rule file outside the cwd printed as
+        // `../../../../../../private/tmp/…`. Measured on the real CLI.
+        rule: 'eess-ts: rule file',
+        element: basename(file),
+        file,
+        line: 1,
+        message: `This rule file could not be evaluated, so its rules enforced nothing in this run: ${detail}${others}`,
+        // Conditional, never asserted — this fires for any error a rule file or a
+        // builder can raise (a syntax error, a missing dependency, a misconfigured
+        // builder), and naming one cause for all of them is the ADR-009 rule 2
+        // defect. The error message above is the evidence; the builder sentence is
+        // offered as the common case that is fixable without touching source code.
+        suggestion: `Fix the error named above in this rule file. If it names a builder method — for example a crossProject() with the wrong number of .side(...) calls — the rule is misconfigured rather than violated, so the fix is in the rule file and not in the code it checks.`,
+        bypassFilters: true,
+    };
+}
+/**
+ * What to collect when evaluating a rule file, or one rule in it, threw.
+ *
+ * An `ArchRuleError` already carries findings — those ARE the report, and this
+ * is the pre-existing path for a rule file that self-executes a failing
+ * `.check()` at import. Anything else becomes one configuration finding naming
+ * the file. Never a rethrow: that discarded every finding already collected in
+ * the run, including other files' (bug 0025).
+ *
+ * One definition, imported by both `runCheck` and `runBaseline`. They had a copy
+ * each for the ArchRuleError half and the two had already diverged in what they
+ * did with everything else.
+ */
+export function failureOrViolations(file, error, ruleFiles) {
+    return isArchRuleError(error) ? error.violations : [ruleFileFailure(file, error, ruleFiles)];
+}
+/**
+ * A rule file stopped evaluating partway, so the rules after that point never ran.
+ *
+ * [ts-archunit Bug 0029](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0029-a-throwing-warn-truncates-the-rest-of-the-rule-file.md),
+ * and the half [ts-archunit plan 0069](https://github.com/nielspeter/ts-archunit/blob/main/plans/completed/0069-no-rule-may-certify-nothing.md)'s R3a
+ * specified and did not build: *"R3a states the semantics, and the CLI **reports the
+ * truncation rather than absorbing it**."* The semantics shipped in v0.23.0; this is
+ * the reporting.
+ *
+ * In a **self-executing** rule file — the shape `init` scaffolds and `docs/cli.md`
+ * documents — every rule calls its own terminal at module scope. A throw there aborts
+ * the module, so every rule declared after it is never evaluated. The CLI then folds
+ * the thrown finding into the run and the output looks entirely ordinary. Measured on
+ * v0.28.0, the same two rules in each style:
+ *
+ * | rule file shape                  | findings reported |
+ * | -------------------------------- | ----------------- |
+ * | `export default [rule1, rule2]`  | **5** — the configuration finding and all four violations |
+ * | self-executing                   | **1** — the four violations silently absent |
+ *
+ * Worse than a crash, because the run is **red for the other finding**: someone fixes
+ * that, moves on, and never learns the rest of the file was skipped — or takes the
+ * sanctioned remedy for a dead glob, which is to delete the rule, and still never
+ * learns it.
+ *
+ * **What this can and cannot say.** The module never finished, so the CLI cannot know
+ * *what* was lost — only that anything after the throw did not run. Naming a count or
+ * a rule would be invention. It says the file stopped and what to do, which is all it
+ * has.
+ *
+ * `bypassFilters` because it reports missing coverage: nothing to grade, exclude or
+ * accept into a baseline.
+ */
+export function ruleFileTruncated(file, ruleFiles) {
+    const others = ruleFiles > 1 ? ' The other rule files in this run were still checked.' : '';
+    return {
+        rule: 'eess-ts: rule file',
+        element: basename(file),
+        file,
+        line: 1,
+        message: `This rule file stopped evaluating at the finding above, so any rule declared after ` +
+            `that point never ran and its violations are not in this report. Rules that had already ` +
+            `run are reported normally.${others}`,
+        suggestion: `Fix the finding above, then re-run to see the rest of this file. To make the file ` +
+            `always evaluate in full: if its rules come from a preset, pass \`report: 'builders'\` — ` +
+            `e.g. \`recommended(p, { report: 'builders' })\` — which returns the builders instead of ` +
+            `running them at module scope. A spread like \`export default [...recommended(p)]\` does ` +
+            `NOT avoid this on its own, because the spread evaluates before the array exists. ` +
+            `Otherwise move the rules into \`export default [rule1, rule2]\` and drop the terminal ` +
+            `calls, so every rule is built before any of them runs.`,
+        bypassFilters: true,
+    };
+}
+/**
+ * `--baseline` was passed, but the rule file printed findings the baseline never
+ * filtered. Bug 0199.
+ *
+ * **The mechanism, corrected TWICE. This is the third version and the measured one.**
+ *
+ * 1. *"The preset throws before baseline filtering runs."* False. `runCheck` collects
+ *    a thrown terminal's violations off the error (`failureOrViolations`) and filters
+ *    them; measured, its collection came back empty against a matching baseline.
+ * 2. *"`setCallerAggregatesReports` is module state that does not cross jiti's
+ *    registry."* Also false, and it was the premise of a whole record. The flag is
+ *    read at exactly ONE site — `core/execute-rule.ts`, inside `executeWarn`.
+ *    And jiti is not even the default loader: `cli/import-rule-module.ts` imports
+ *    natively first and reaches jiti only on a module-format refusal.
+ * (Line numbers deliberately omitted: the fix for (3) moved every one of them,
+ * and the first version of this docblock cited three that had already drifted.)
+ *
+ * 3. **What is actually true:** `executeCheck` calls `writeReport(...)`
+ *    **unconditionally** at `core/execute-rule.ts`, one line before it throws.
+ *    A `.check()` at module scope therefore prints its findings always — same
+ *    registry, no jiti, no flag involved. The CLI cannot un-print them.
+ *
+ * The disproof of (2) is one line: a fixture importing the same module graph as the
+ * test's `runCheck`, so the flag was fully visible, printed all four violations
+ * anyway.
+ *
+ * **Why a notice and not the repair.** Making `executeCheck` honour the flag is a
+ * change to when a terminal emits — ADR-008 territory, and it would alter behaviour
+ * for every caller that relies on `.check()` printing, including test files. That is
+ * bug 0201. Until it is decided the run must not be silent about output it could not
+ * filter.
+ *
+ * **Fires only when something was actually printed.** `executeWarn` throws the same
+ * error type, and when the CLI aggregates it writes only non-`bypassFilters` entries
+ * — for a configuration finding, nothing at all. The first version fired on the bare
+ * `isArchRuleError` condition and so claimed a leak that never happened, pointing at
+ * a finding whose own text says a baseline can never suppress it. Asserting a cause
+ * the run cannot verify is the ADR-009 rule 2 defect `ruleFileFailure` names above.
+ *
+ * **What this can and cannot say.** The leaked lines were written before the CLI saw
+ * them, so it cannot know how many there were. Naming a count would be invention.
+ *
+ * `bypassFilters` because it reports a gap in filtering — accepting it into a
+ * baseline would suppress the notice that the baseline is not being applied.
+ */
+export function baselineNotApplied(file, filters) {
+    // Name the filters that were actually in play. `--baseline` is not the only one,
+    // and it is not always a FLAG — a config file can set it, and telling someone
+    // "`--baseline` was not applied" when they never typed it sends them looking for
+    // an argument they did not pass (adopter review of PR #74).
+    const names = [];
+    if (filters.baseline !== undefined)
+        names.push(`the baseline \`${basename(filters.baseline)}\``);
+    if (filters.changed)
+        names.push('`--changed` (diff-aware mode)');
+    const list = names.join(' and ');
+    return {
+        // NOT `eess-ts: rule file` — `dedupeConfigFindings` keys on
+        // `file + rule + element`, so sharing that label merges this into
+        // `ruleFileTruncated()` and the notice disappears. Measured: it did.
+        //
+        // NOT `eess-ts: baseline` either: it fires for `--changed` too, and three
+        // existing findings already use that label for baseline diagnostics.
+        //
+        // And NOT `eess-ts: filtering`, which it briefly was — across `docs/`
+        // "filtering" is the `.that()` predicate phase (`docs/core-concepts.md:91`,
+        // repeated on every dialect page), so a reader seeing it on a red build would
+        // most reasonably conclude their predicate was wrong. `reporting` is ADR-008's
+        // own noun for what this finding is actually about: who emitted, and when.
+        rule: 'eess-ts: reporting',
+        element: basename(file),
+        file,
+        line: 1,
+        message: `This rule file reported findings itself, so ${list} ` +
+            `${names.length > 1 ? 'were' : 'was'} NOT applied to them — anything it printed ` +
+            `reached you unfiltered, and findings you have already accepted or excluded can ` +
+            `appear as failures. The findings the CLI collected were filtered normally, which ` +
+            `is why the counts in this run disagree.`,
+        because: `A CLI-side filter can only act on findings the CLI collects. A rule file that ` +
+            `calls its own terminal at module scope prints them first, so the run you are ` +
+            `reading is not the run the filter describes.`,
+        // The remedy is ordered generic-first ON PURPOSE. This finding fires for ANY
+        // terminal throwing at module scope — a hand-written `.check()` with no preset
+        // in sight reaches it too — so naming the preset fix alone would be the ADR-009
+        // rule 2 defect its neighbour `ruleFileFailure` calls out by name.
+        suggestion: `Move this file's rules into \`export default [rule1, rule2]\` and drop the ` +
+            `terminal calls — an array export hands every rule to the CLI, which then owns ` +
+            `reporting and applies every filter to all of it. If the rules come from a ` +
+            `preset, pass \`report: 'builders'\` instead — e.g. ` +
+            `\`recommended(p, { report: 'builders' })\` — which returns the builders rather ` +
+            `than running them. \`eess-ts init\` scaffolds both forms correctly.`,
+        bypassFilters: true,
+    };
+}
+/**
+ * A rule file loaded cleanly and contributed **zero** rules.
+ *
+ * `check` used to print `✓ eess-ts — 0 rules across 1 file · 0 failing` and exit 0
+ * over exactly this, while `doctor` on the same file already refused it with "no
+ * rules found in the given files". Two commands in one CLI disagreeing about
+ * whether "no rules" is an error, and the one wired into CI was the one blessing
+ * it.
+ *
+ * **The shape that makes it urgent** is a migration from `@nielspeter/ts-archunit`,
+ * whose `recommended()` returned builders unconditionally and had no `report`
+ * option. eess-ts's runs and throws by default, so the line ts-archunit's own
+ * `init` scaffolded — `export default [...recommended(p)]` — spreads a *violations*
+ * array. On a codebase with findings that fails loudly (the loader rejects a
+ * non-builder entry). **On a clean codebase the array is empty**, so the file
+ * exports `[]`, the CLI loads nothing, and the run is green with every rule gone.
+ * `tsc --noEmit` passes; nothing reaches stderr.
+ *
+ * The adopter this hits is the one who did the baseline work and cleaned up.
+ *
+ * `CLAUDE.md` already tells agents that a zero denominator "means the gate matched
+ * little or nothing — treat that as a red flag". This makes the CLI agree with its
+ * own instruction instead of printing `✓` over its alarm value.
+ *
+ * `bypassFilters` because it reports absent coverage: there is nothing to grade,
+ * exclude, or accept into a baseline.
+ */
+export function ruleFileContributedNoRules(file) {
+    return {
+        rule: 'eess-ts: rule file',
+        element: basename(file),
+        file,
+        line: 1,
+        message: `This rule file loaded without error but contributed no rules, so it enforced ` +
+            `nothing in this run. A green result here would mean "every rule passed" when ` +
+            `what happened is "there were no rules".`,
+        because: `A gate that checks nothing cannot fail, and a passing build is only evidence ` +
+            `if something was actually examined.`,
+        suggestion: `Check what this file's default export actually contains. The usual cause is a ` +
+            `preset spread without \`report: 'builders'\` — \`export default ` +
+            `[...recommended(p)]\` spreads the preset's RESULT, which on a codebase with no ` +
+            `violations is an empty array. Use \`recommended(p, { report: 'builders' })\`. ` +
+            `If the file is deliberately empty, delete it rather than leaving a rule file ` +
+            `that enforces nothing.`,
+        bypassFilters: true,
+    };
+}
+//# sourceMappingURL=rule-file-findings.js.map

package/dist/cli/rule-file-findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-file-findings.js","sourceRoot":"","sources":["../../src/cli/rule-file-findings.ts"],"names":[],"mappings":"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"}

package/dist/cli/watch.d.ts

@@ -1,4 +1,4 @@
-export interface WatchOptions {
+interface WatchOptions {
     /** Directories to watch for changes */
     watchDirs: string[];
     /** Additional files to watch (e.g., rule files) */
@@ -22,13 +22,17 @@ export declare class RunScheduler {
     private _pendingRerun;
     private readonly debounceMs;
     private readonly onRun;
-    constructor(onRun: (trigger: string) => Promise<void>, debounceMs?: number);
+    /** Completed runs. */
     get runCount(): number;
+    constructor(onRun: (trigger: string) => Promise<void>, debounceMs?: number);
     get pendingRerun(): boolean;
     get isRunning(): boolean;
     /**
-     * Queue a run for the given trigger, resetting the debounce window.
-     * If a run is already in progress, marks a pending re-run instead.
+     * Queue a re-run, debounced.
+     *
+     * A run already in flight is not interrupted: the request is remembered and
+     * replayed when it finishes, so a save during a run is never dropped and
+     * never starts a second concurrent run.
      */
     schedule(trigger: string): void;
     private executeRun;
@@ -41,9 +45,18 @@ export declare class RunScheduler {
  * a run is in progress, it is queued and executed after the
  * current run completes.
  *
- * Known limitation: each re-run loads rule files with a fresh (cache-busting)
- * jiti instance. Over long sessions, memory grows — restart the watcher
- * periodically for long sessions.
+ * Known limitation: each re-run uses `importFresh` which creates
+ * a new ESM module cache entry. Over long sessions, memory grows.
+ * Restart the watcher periodically for long sessions.
  */
 export declare function watchAndRerun(options: WatchOptions): void;
+/**
+ * Import a module with cache-busting for watch mode.
+ *
+ * Node ESM has no cache eviction API. Each call creates a new
+ * module entry via a unique query string. Over long sessions
+ * this leaks memory — see watchAndRerun JSDoc.
+ */
+export declare function importFresh(filePath: string): Promise<unknown>;
+export {};
 //# sourceMappingURL=watch.d.ts.map

package/dist/cli/watch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/cli/watch.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,mDAAmD;IACnD,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,0CAA0C;IAC1C,gBAAgB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAGD,eAAO,MAAM,UAAU,QAAiB,CAAA;AAExC;;;;;GAKG;AAEH,qBAAa,YAAY;;IACvB,OAAO,CAAC,aAAa,CAA2C;IAChE,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;gBAG9C,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,SAAM;IAKvE,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAW/B,OAAO,CAAC,UAAU;CAwBnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAqDzD"}
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/cli/watch.ts"],"names":[],"mappings":"AAKA,UAAU,YAAY;IACpB,uCAAuC;IACvC,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,mDAAmD;IACnD,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,0CAA0C;IAC1C,gBAAgB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAGD,eAAO,MAAM,UAAU,QAAiB,CAAA;AAExC;;;;;GAKG;AAEH,qBAAa,YAAY;;IACvB,OAAO,CAAC,aAAa,CAA2C;IAChE,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAU1D,sBAAsB;IACtB,IAAI,QAAQ,IAAI,MAAM,CAErB;gBAEW,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,SAAM;IAKvE,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAW/B,OAAO,CAAC,UAAU;CAwBnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAsDzD;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAIpE"}

package/dist/cli/watch.js

@@ -1,7 +1,8 @@
 import { watch } from 'node:fs/promises';
+import { isNullaryCallable } from '@nielspeter/eess';
 import path from 'node:path';
-import { ArchRuleError } from '@nielspeter/eess';
-// eess-exclude eess/no-unused-exports: consumed by the test suite (tests are outside the build project)
+import { isArchRuleError } from '@nielspeter/eess';
+// eess-exclude eess/no-unused-exports: consumed by the test suite; the build tsconfig this gate reads excludes tests, so `src` is the only usage it can see
 export const TS_FILE_RE = /\.[cm]?tsx?$/;
 /**
  * Scheduling logic for watch mode — extracted for testability.
@@ -9,21 +10,29 @@ export const TS_FILE_RE = /\.[cm]?tsx?$/;
  * Debounces rapid triggers. If a trigger arrives while the callback
  * is running, it queues a re-run after the current run completes.
  */
-// eess-exclude eess/no-unused-exports: consumed by the test suite (tests are outside the build project)
+// eess-exclude eess/no-unused-exports: consumed by the test suite; the build tsconfig this gate reads excludes tests, so `src` is the only usage it can see
 export class RunScheduler {
     debounceTimer;
     running = false;
     _pendingRerun = false;
     debounceMs;
     onRun;
+    /**
+     * How many runs have completed — read by the watch loop's own tests.
+     *
+     * Hard-private with a getter, matching `eess-mermaid`'s `RunScheduler`: the
+     * counter is this class's bookkeeping and a caller that could reassign it
+     * would make the number mean nothing.
+     */
     #runCount = 0;
+    /** Completed runs. */
+    get runCount() {
+        return this.#runCount;
+    }
     constructor(onRun, debounceMs = 250) {
         this.onRun = onRun;
         this.debounceMs = debounceMs;
     }
-    get runCount() {
-        return this.#runCount;
-    }
     get pendingRerun() {
         return this._pendingRerun;
     }
@@ -31,8 +40,11 @@ export class RunScheduler {
         return this.running;
     }
     /**
-     * Queue a run for the given trigger, resetting the debounce window.
-     * If a run is already in progress, marks a pending re-run instead.
+     * Queue a re-run, debounced.
+     *
+     * A run already in flight is not interrupted: the request is remembered and
+     * replayed when it finishes, so a save during a run is never dropped and
+     * never starts a second concurrent run.
      */
     schedule(trigger) {
         if (this.debounceTimer)
@@ -54,7 +66,7 @@ export class RunScheduler {
         this.onRun(trigger)
             .catch((err) => {
             // Rule failures are expected — swallow ArchRuleError, print others
-            if (!(err instanceof ArchRuleError)) {
+            if (!isArchRuleError(err)) {
                 if (err instanceof Error) {
                     console.error(err.message);
                 }
@@ -79,9 +91,9 @@ export class RunScheduler {
  * a run is in progress, it is queued and executed after the
  * current run completes.
  *
- * Known limitation: each re-run loads rule files with a fresh (cache-busting)
- * jiti instance. Over long sessions, memory grows — restart the watcher
- * periodically for long sessions.
+ * Known limitation: each re-run uses `importFresh` which creates
+ * a new ESM module cache entry. Over long sessions, memory grows.
+ * Restart the watcher periodically for long sessions.
  */
 export function watchAndRerun(options) {
     const { watchDirs, watchFiles, onChangeDetected, debounceMs = 250 } = options;
@@ -129,10 +141,23 @@ export function watchAndRerun(options) {
     // Graceful shutdown — close all watchers on SIGINT
     process.on('SIGINT', () => {
         for (const w of watchers) {
-            // Ask each async iterator to release its underlying fs.watch handle.
-            void w[Symbol.asyncIterator]().return?.();
+            if ('return' in w && isNullaryCallable(w.return)) {
+                void w.return();
+            }
         }
         process.exit(0);
     });
 }
+/**
+ * Import a module with cache-busting for watch mode.
+ *
+ * Node ESM has no cache eviction API. Each call creates a new
+ * module entry via a unique query string. Over long sessions
+ * this leaks memory — see watchAndRerun JSDoc.
+ */
+export async function importFresh(filePath) {
+    const resolved = path.resolve(filePath);
+    const url = `file://${resolved}?t=${Date.now()}`;
+    return import(url);
+}
 //# sourceMappingURL=watch.js.map