@nielspeter/eess 0.2.2 → 0.5.0

package/dist/diff-disclosure.js

@@ -0,0 +1,110 @@
+/**
+ * What diff-aware mode suppressed, said out loud.
+ *
+ * Plan 0071's first instrument. `--changed` (and `check({ diff })`) filter
+ * **reporting**, not evaluation — so a run with every finding suppressed is
+ * indistinguishable from a clean run: exit 0, no output, `total: 0`. That is
+ * the false green ADR-008 exists to prevent, and it is worse here than
+ * elsewhere because the reader chose the flag and then forgot it: CI configures
+ * `--changed` once and every subsequent run reads as clean.
+ *
+ * **The count is derived by the caller, never self-reported.** Each call site
+ * computes `before.length - after.length` around its own `filterToChanged`
+ * call. `DiffFilter` could keep that tally itself, and it deliberately does
+ * not: `CheckOptions.diff` is a structural interface (`DiffFilterLike`), so a
+ * consumer can pass any object with a `filterToChanged` method, and a filter
+ * that under-reports its own suppression would produce exactly the silence
+ * this module exists to break. Caller-side subtraction is a differently-derived
+ * value (ADR-009 rule 5) and it works for filters we did not write.
+ *
+ * **Two surfaces, because only one of them can count.**
+ *
+ * | surface                                  | disclosure           |
+ * | ---------------------------------------- | -------------------- |
+ * | CLI `check --changed`                    | `suppressionNotice`  |
+ * | `checkAll([...])`                        | `suppressionNotice`  |
+ * | `.check({ diff })` / `.warn({ diff })`   | `activeNotice`, once |
+ *
+ * The first two filter once over every collected violation, so they know the
+ * whole number. The per-rule terminals do not: `filterToChanged` is called
+ * once per rule (`execute-rule.ts`), and a diff-aware suite with 79 rules
+ * would print 79 lines — on the channel v0.26.0 made unconditionally visible.
+ * There is no per-run aggregation point on that path, so those terminals state
+ * the **configuration** instead, once per process. A configuration statement
+ * cannot be wrong; a per-rule count presented as a run total would be.
+ *
+ * A `process.on('exit')` flush was considered and rejected: it would let the
+ * per-rule path print one complete total, but a library that installs an exit
+ * hook to deliver a correctness-relevant message has made that message
+ * dependent on stderr surviving process teardown — untestable in the shape the
+ * rest of this project asserts (a real child `vitest run`, bug 0024) without
+ * asserting a race. Stating the configuration is weaker and honest.
+ */
+/** Prefix shared with the rest of the library's stderr output. */
+const TAG = '[eess]';
+/**
+ * One line naming what was suppressed, or `undefined` when nothing was.
+ *
+ * `undefined` rather than an empty string so a call site cannot print a blank
+ * line by forgetting to check — the two callers both feed this straight into
+ * `writeStderr`.
+ *
+ * @param suppressed - `before.length - after.length`, computed by the caller.
+ * @param changedFiles - How many files the filter considered changed, when the
+ *   filter exposes it. A user-supplied `DiffFilterLike` need not, in which case
+ *   the sentence drops that clause rather than guessing.
+ * @param baseBranch - The branch diffed against, when known.
+ */
+export function suppressionNotice(suppressed, changedFiles, baseBranch) {
+    if (suppressed <= 0)
+        return undefined;
+    const findings = suppressed === 1 ? 'finding' : 'findings';
+    // A negative size is `DiffFilter`'s "git was unavailable" sentinel. That path
+    // filters nothing, so `suppressed` is 0 and we never reach here — but the
+    // guard is cheap and keeps the sentinel from ever reaching a user's screen.
+    const scope = changedFiles !== undefined && changedFiles >= 0
+        ? ` outside the ${String(changedFiles)} changed ${changedFiles === 1 ? 'file' : 'files'}`
+        : ' outside the changed files';
+    const since = baseBranch === undefined ? '' : ` (diffed against '${baseBranch}')`;
+    return (`${TAG} Diff-aware mode suppressed ${String(suppressed)} ${findings}${scope}${since}. ` +
+        `Those findings are real and still present — this run did not check them. ` +
+        `Re-run without diff-aware mode to see every finding.`);
+}
+/**
+ * Whether {@link activeNotice} has already spoken in this process.
+ *
+ * Module-scoped rather than per-`DiffFilter`, because the documented pattern
+ * constructs a filter **inline per rule** — `.check({ diff: diffAware('main') })`
+ * in `docs/core-concepts.md:333` and `docs/what-to-check.md:515` — so
+ * per-instance state would still produce one line per rule.
+ */
+let noticed = false;
+/**
+ * State that diff-aware filtering is on, once per process. Returns `undefined`
+ * on every call after the first, and whenever nothing was suppressed.
+ *
+ * Keyed on a call that actually suppressed something: a diff-aware run whose
+ * findings all happen to be in changed files has hidden nothing, and a notice
+ * there would train the reader to skip the line that matters.
+ */
+export function activeNotice(suppressed, changedFiles, baseBranch) {
+    if (suppressed <= 0 || noticed)
+        return undefined;
+    noticed = true;
+    const scope = changedFiles !== undefined && changedFiles >= 0
+        ? `the ${String(changedFiles)} ${changedFiles === 1 ? 'file' : 'files'} changed`
+        : 'the files changed';
+    const since = baseBranch === undefined ? '' : ` since '${baseBranch}'`;
+    return (`${TAG} Diff-aware mode is active: this run reports only findings in ${scope}${since}. ` +
+        `Findings in unchanged files are suppressed and will not appear, however many there are. ` +
+        `Remove \`diff\` from the check options to see every finding.`);
+}
+/**
+ * Forget that {@link activeNotice} has spoken. **Tests only** — a suite
+ * asserting the once-per-process contract has to observe the first call, and
+ * whichever earlier test filtered first would otherwise have consumed it.
+ */
+export function resetDiffDisclosureForTests() {
+    noticed = false;
+}
+//# sourceMappingURL=diff-disclosure.js.map

package/dist/diff-disclosure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-disclosure.js","sourceRoot":"","sources":["../src/diff-disclosure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,kEAAkE;AAClE,MAAM,GAAG,GAAG,QAAQ,CAAA;AAEpB;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAkB,EAClB,YAAqB,EACrB,UAAmB;IAEnB,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,SAAS,CAAA;IAErC,MAAM,QAAQ,GAAG,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAA;IAC1D,8EAA8E;IAC9E,0EAA0E;IAC1E,4EAA4E;IAC5E,MAAM,KAAK,GACT,YAAY,KAAK,SAAS,IAAI,YAAY,IAAI,CAAC;QAC7C,CAAC,CAAC,gBAAgB,MAAM,CAAC,YAAY,CAAC,YAAY,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE;QACzF,CAAC,CAAC,4BAA4B,CAAA;IAClC,MAAM,KAAK,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,qBAAqB,UAAU,IAAI,CAAA;IAEjF,OAAO,CACL,GAAG,GAAG,+BAA+B,MAAM,CAAC,UAAU,CAAC,IAAI,QAAQ,GAAG,KAAK,GAAG,KAAK,IAAI;QACvF,2EAA2E;QAC3E,sDAAsD,CACvD,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,IAAI,OAAO,GAAG,KAAK,CAAA;AAEnB;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,UAAkB,EAClB,YAAqB,EACrB,UAAmB;IAEnB,IAAI,UAAU,IAAI,CAAC,IAAI,OAAO;QAAE,OAAO,SAAS,CAAA;IAChD,OAAO,GAAG,IAAI,CAAA;IAEd,MAAM,KAAK,GACT,YAAY,KAAK,SAAS,IAAI,YAAY,IAAI,CAAC;QAC7C,CAAC,CAAC,OAAO,MAAM,CAAC,YAAY,CAAC,IAAI,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,UAAU;QAChF,CAAC,CAAC,mBAAmB,CAAA;IACzB,MAAM,KAAK,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,UAAU,GAAG,CAAA;IAEtE,OAAO,CACL,GAAG,GAAG,iEAAiE,KAAK,GAAG,KAAK,IAAI;QACxF,0FAA0F;QAC1F,8DAA8D,CAC/D,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO,GAAG,KAAK,CAAA;AACjB,CAAC"}

package/dist/disk-set.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What the filesystem says about a glob that the compiler's file set does
+ * not — the shape of the data, not how to build it.
+ *
+ * `OnDisk`/`DiskSet` are pure: a materialized `DiskSet` is just a closure
+ * over already-walked filesystem data, so the type stays in the kernel.
+ * Walking a real project's filesystem needs Node's `fs`/`path` and the
+ * dialect's own project type to find the root, so the MATERIALIZER lives in
+ * that dialect (e.g. `packages/ts/src/core/disk-set.ts`'s `diskSet()`).
+ */
+/**
+ * What the filesystem knows that the compiler's file set does not.
+ *
+ * Distinguishes "your glob is misspelled" from "your glob is fine and your
+ * tsconfig scope excludes it" — the cheapest wrong action an agent can take
+ * on a dead-glob finding, and the common case in a real monorepo where a
+ * build-output or docs directory sits outside the loaded project.
+ */
+export type OnDisk = 'holds-typescript' | 'no-typescript' | 'absent' | 'not-determined';
+/**
+ * What the filesystem knows that the compiler's file set does not.
+ */
+export interface DiskSet {
+    /** Classify a glob by what exists on disk under the paths it matches. */
+    classify(glob: string): OnDisk;
+}
+//# sourceMappingURL=disk-set.d.ts.map

package/dist/disk-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk-set.d.ts","sourceRoot":"","sources":["../src/disk-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,kBAAkB,GAAG,eAAe,GAAG,QAAQ,GAAG,gBAAgB,CAAA;AAEvF;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAC/B"}

package/dist/disk-set.js

@@ -0,0 +1,12 @@
+/**
+ * What the filesystem says about a glob that the compiler's file set does
+ * not — the shape of the data, not how to build it.
+ *
+ * `OnDisk`/`DiskSet` are pure: a materialized `DiskSet` is just a closure
+ * over already-walked filesystem data, so the type stays in the kernel.
+ * Walking a real project's filesystem needs Node's `fs`/`path` and the
+ * dialect's own project type to find the root, so the MATERIALIZER lives in
+ * that dialect (e.g. `packages/ts/src/core/disk-set.ts`'s `diskSet()`).
+ */
+export {};
+//# sourceMappingURL=disk-set.js.map

package/dist/disk-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk-set.js","sourceRoot":"","sources":["../src/disk-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/edge-coverage.d.ts

@@ -0,0 +1,96 @@
+/**
+ * How much evidence an allowlist condition actually had — bug 0015.
+ *
+ * The `only*` family constrains **edges**, not subjects. Each iterates a
+ * subject's imports (or importers) and reports one violation per edge outside
+ * the allowlist, so a subject with **zero edges has nothing to violate and
+ * passes**, however broken the allowlist. Measured: one file with no imports,
+ * `onlyImportFrom('**\/nowhere/**')` → 1 subject selected, 0 violations.
+ *
+ * The shape it fails on is the target case, not an edge case: in a layered
+ * architecture the innermost layer is the one an allowlist protects and is
+ * characteristically the layer with the fewest outbound imports.
+ *
+ * ## Why this reports rather than fails
+ *
+ * [ts-archunit Bug 0015](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0015-allowlist-conditions-pass-vacuously-on-edgeless-subjects.md)
+ * refuted failing, per-subject and per-rule, on measurement:
+ *
+ * - **Per-subject has no statable remedy.** 14 of this repo's `src/` files have
+ *   zero static imports and 10 are pure leaf modules. `tarjan.ts` is a
+ *   dependency-free algorithm — the ideal innermost-layer citizen — and would
+ *   fail at error severity. The remedies available are: add an import (harmful),
+ *   exclude a working rule, narrow the selector, or delete the rule. None
+ *   improves anything, because **for the `only*` family zero edges is maximal
+ *   compliance**, not absent evidence. That fails ADR-009 rule 2.
+ * - **Per-rule multiplies.** Six boundaries and one dependency-free shared file
+ *   make `strictBoundaries` emit 13 rules, **12** with subjects and zero edges.
+ * - **`ignoreTypeImports` inverts it.** Counting edges after the filter means a
+ *   layer whose only dependency is `import type` counts zero and fires on the
+ *   best possible outcome — under the option the docs recommend for layers.
+ *
+ * So the remedy is genuinely optional and the reader must judge it, which under
+ * ADR-009 rule 1 is a disclosure, not a failure. This module is the disclosure.
+ *
+ * ## Why module state rather than a field on `ConditionContext`
+ *
+ * `ConditionContext` is a **public exported type** backing the documented
+ * `defineCondition()`, and bug 0015 records that extending `Condition<T>` for
+ * this was one reason the failing design could not ship. `diff-disclosure.ts`
+ * established the pattern for a run-scoped notice that conditions produce and
+ * the CLI consumes; this follows it, including the test reset.
+ */
+/**
+ * Why a rule tested no edges. The three are not interchangeable, and saying the
+ * wrong one is an ADR-009 rule 2 defect — a stated cause that is wrong for the
+ * input.
+ *
+ * The first version of this module printed "correct for a genuinely
+ * dependency-free module" for all three. Measured, that is false for two of
+ * them: a subject whose imports were filtered by `ignoreTypeImports` **has**
+ * dependencies, and a reader who opens the folder finds them and concludes the
+ * tool is broken; and a rule whose allowlist matched no import is pointing at
+ * the interesting case — the glob may be a typo — which that sentence hides.
+ */
+export type UntestedReason = 
+/** The subjects have no edges of any kind. Usually correct, and the layered case. */
+'no-edges'
+/** Edges existed, and every one was filtered out before the check saw it. */
+ | 'all-filtered'
+/** Edges existed, and none of them matched the allowlist glob. */
+ | 'none-matched';
+/** One rule's evidence: how many subjects it saw and how many edges it tested. */
+export interface EdgeCoverage {
+    readonly rule: string;
+    readonly subjects: number;
+    readonly edges: number;
+    readonly reason: UntestedReason;
+}
+/**
+ * Record what a condition had to work with.
+ *
+ * Keyed on the rule description, and **accumulated** rather than overwritten:
+ * one rule can evaluate its condition more than once (a `.check()` after a
+ * `.violations()`, or the same description in two files), and taking the last
+ * write would report the smaller run.
+ */
+export declare function recordEdgeCoverage(rule: string, subjects: number, edges: number, reason?: UntestedReason): void;
+/**
+ * Rules that had subjects and tested no edges — the vacuous passes.
+ *
+ * A rule with **no subjects** is deliberately excluded: that is an empty
+ * selector, which is `.expectNonEmpty()`'s business and plan 0067's, and
+ * reporting it here would give one fault two owners.
+ */
+export declare function untestedRules(): readonly EdgeCoverage[];
+/**
+ * The disclosure, or `undefined` when every allowlist was exercised.
+ *
+ * Names the rules rather than counting them (ADR-009 rule 4): "3 rules tested
+ * nothing" sends the reader to grep, and the whole point is that they must
+ * judge whether an edge-free population is correct here.
+ */
+export declare function edgeCoverageNotice(): string | undefined;
+/** Drop the tally. The CLI resets per run; tests reset per case. */
+export declare function resetEdgeCoverage(): void;
+//# sourceMappingURL=edge-coverage.d.ts.map

package/dist/edge-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-coverage.d.ts","sourceRoot":"","sources":["../src/edge-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc;AACxB,qFAAqF;AACnF,UAAU;AACZ,6EAA6E;GAC3E,cAAc;AAChB,kEAAkE;GAChE,cAAc,CAAA;AAElB,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAChC;AAID;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,cAA2B,GAClC,IAAI,CAeN;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,SAAS,YAAY,EAAE,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CA0BvD;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/edge-coverage.js

@@ -0,0 +1,108 @@
+/**
+ * How much evidence an allowlist condition actually had — bug 0015.
+ *
+ * The `only*` family constrains **edges**, not subjects. Each iterates a
+ * subject's imports (or importers) and reports one violation per edge outside
+ * the allowlist, so a subject with **zero edges has nothing to violate and
+ * passes**, however broken the allowlist. Measured: one file with no imports,
+ * `onlyImportFrom('**\/nowhere/**')` → 1 subject selected, 0 violations.
+ *
+ * The shape it fails on is the target case, not an edge case: in a layered
+ * architecture the innermost layer is the one an allowlist protects and is
+ * characteristically the layer with the fewest outbound imports.
+ *
+ * ## Why this reports rather than fails
+ *
+ * [ts-archunit Bug 0015](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0015-allowlist-conditions-pass-vacuously-on-edgeless-subjects.md)
+ * refuted failing, per-subject and per-rule, on measurement:
+ *
+ * - **Per-subject has no statable remedy.** 14 of this repo's `src/` files have
+ *   zero static imports and 10 are pure leaf modules. `tarjan.ts` is a
+ *   dependency-free algorithm — the ideal innermost-layer citizen — and would
+ *   fail at error severity. The remedies available are: add an import (harmful),
+ *   exclude a working rule, narrow the selector, or delete the rule. None
+ *   improves anything, because **for the `only*` family zero edges is maximal
+ *   compliance**, not absent evidence. That fails ADR-009 rule 2.
+ * - **Per-rule multiplies.** Six boundaries and one dependency-free shared file
+ *   make `strictBoundaries` emit 13 rules, **12** with subjects and zero edges.
+ * - **`ignoreTypeImports` inverts it.** Counting edges after the filter means a
+ *   layer whose only dependency is `import type` counts zero and fires on the
+ *   best possible outcome — under the option the docs recommend for layers.
+ *
+ * So the remedy is genuinely optional and the reader must judge it, which under
+ * ADR-009 rule 1 is a disclosure, not a failure. This module is the disclosure.
+ *
+ * ## Why module state rather than a field on `ConditionContext`
+ *
+ * `ConditionContext` is a **public exported type** backing the documented
+ * `defineCondition()`, and bug 0015 records that extending `Condition<T>` for
+ * this was one reason the failing design could not ship. `diff-disclosure.ts`
+ * established the pattern for a run-scoped notice that conditions produce and
+ * the CLI consumes; this follows it, including the test reset.
+ */
+const coverage = new Map();
+/**
+ * Record what a condition had to work with.
+ *
+ * Keyed on the rule description, and **accumulated** rather than overwritten:
+ * one rule can evaluate its condition more than once (a `.check()` after a
+ * `.violations()`, or the same description in two files), and taking the last
+ * write would report the smaller run.
+ */
+export function recordEdgeCoverage(rule, subjects, edges, reason = 'no-edges') {
+    const prior = coverage.get(rule);
+    // The MINIMUM edge count, not the maximum. Two evaluations of the same rule
+    // description — the same preset over two projects, or the same chain written
+    // twice — merge on this key, and taking the max let a run that tested edges
+    // erase a run that tested none. Measured: the vacuous run vanished from the
+    // report. For a disclosure OF vacuity the conservative direction is to keep
+    // the smaller evidence; over-disclosing costs a footnote, under-disclosing is
+    // the silent pass this module exists to surface.
+    coverage.set(rule, {
+        rule,
+        subjects: Math.max(prior?.subjects ?? 0, subjects),
+        edges: prior === undefined ? edges : Math.min(prior.edges, edges),
+        reason: prior !== undefined && prior.edges <= edges ? prior.reason : reason,
+    });
+}
+/**
+ * Rules that had subjects and tested no edges — the vacuous passes.
+ *
+ * A rule with **no subjects** is deliberately excluded: that is an empty
+ * selector, which is `.expectNonEmpty()`'s business and plan 0067's, and
+ * reporting it here would give one fault two owners.
+ */
+export function untestedRules() {
+    return [...coverage.values()].filter((c) => c.subjects > 0 && c.edges === 0);
+}
+/**
+ * The disclosure, or `undefined` when every allowlist was exercised.
+ *
+ * Names the rules rather than counting them (ADR-009 rule 4): "3 rules tested
+ * nothing" sends the reader to grep, and the whole point is that they must
+ * judge whether an edge-free population is correct here.
+ */
+export function edgeCoverageNotice() {
+    const untested = untestedRules();
+    if (untested.length === 0)
+        return undefined;
+    const because = {
+        'no-edges': 'those subjects have no imports at all, which is correct for a dependency-free module and ' +
+            'means the rule certified nothing otherwise',
+        'all-filtered': 'those subjects DO have imports — every one was excluded by `ignoreTypeImports` before the ' +
+            'check saw it, so the allowlist was never consulted',
+        'none-matched': 'those subjects have imports, and none matched the allowlist glob — so either nothing is ' +
+            'in scope by design, or the glob is wrong',
+    };
+    const lines = untested.map((c) => `  - ${c.rule}\n    ${String(c.subjects)} subject${c.subjects === 1 ? '' : 's'}, 0 edges tested — ${because[c.reason]}.`);
+    const count = untested.length;
+    return (`[eess] ${String(count)} allowlist rule${count === 1 ? '' : 's'} passed without ` +
+        `testing a single edge:\n${lines.join('\n')}\n` +
+        `  An allowlist constrains edges, so a subject with none cannot violate it. Only you can ` +
+        `tell an intended shape from a rule that certified nothing.`);
+}
+/** Drop the tally. The CLI resets per run; tests reset per case. */
+export function resetEdgeCoverage() {
+    coverage.clear();
+}
+//# sourceMappingURL=edge-coverage.js.map

package/dist/edge-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-coverage.js","sourceRoot":"","sources":["../src/edge-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AA8BH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAA;AAEhD;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,QAAgB,EAChB,KAAa,EACb,SAAyB,UAAU;IAEnC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAChC,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,4EAA4E;IAC5E,4EAA4E;IAC5E,8EAA8E;IAC9E,iDAAiD;IACjD,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE;QACjB,IAAI;QACJ,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,IAAI,CAAC,EAAE,QAAQ,CAAC;QAClD,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC;QACjE,MAAM,EAAE,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;KAC5E,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAA;AAC9E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,QAAQ,GAAG,aAAa,EAAE,CAAA;IAChC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IAE3C,MAAM,OAAO,GAAmC;QAC9C,UAAU,EACR,2FAA2F;YAC3F,4CAA4C;QAC9C,cAAc,EACZ,4FAA4F;YAC5F,oDAAoD;QACtD,cAAc,EACZ,0FAA0F;YAC1F,0CAA0C;KAC7C,CAAA;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CACxB,CAAC,CAAC,EAAE,EAAE,CACJ,OAAO,CAAC,CAAC,IAAI,SAAS,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,sBAAsB,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAC3H,CAAA;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAA;IAC7B,OAAO,CACL,UAAU,MAAM,CAAC,KAAK,CAAC,kBAAkB,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,kBAAkB;QACjF,2BAA2B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QAC/C,0FAA0F;QAC1F,4DAA4D,CAC7D,CAAA;AACH,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,iBAAiB;IAC/B,QAAQ,CAAC,KAAK,EAAE,CAAA;AAClB,CAAC"}

package/dist/emitter-findings.d.ts

@@ -0,0 +1,167 @@
+import type { ArchViolation } from './violation.js';
+/**
+ * The emitter's own configuration findings — [ADR-014](../../../adr/014-the-emitter-refuses-a-verdict-without-evidence.md).
+ *
+ * **Why these are not in `vacuity-findings.ts`.** Every finding there is built by
+ * `configFinding(facts, message)`, which reads its `ruleId` from
+ * `facts.describeRule()`. At the emitter there is no rule to describe: the value
+ * arrived from a preset, a loop, or a hand-assembled array, and the whole point
+ * of ADR-014 is that the emitter must speak about values it did not mint.
+ *
+ * That is not a stylistic difference, it is bug 0190's cause. The kernel's
+ * previous preset finding took `(presetName, optionsHint)` and carried **no
+ * `ruleId`**, so nothing could assert on it and no non-vacuity fixture could key
+ * on it — a finding no test could name is a finding no one can prove fires. It
+ * had no call site and was deleted rather than wired (plan 0235 Phase 0). These
+ * two carry **hardcoded, stable ids**, and they are the first hardcoded rule ids
+ * in the kernel for exactly that reason.
+ *
+ * **Why two and not one.** ADR-014 §4 separates them, and the remedies differ:
+ *
+ * - `emitter/no-receipt` — the value carried no evidence field at all. A shape
+ *   defect. The remedy ("hand over what the pipeline minted") is real on every
+ *   path, including one where the run was perfectly healthy.
+ * - `emitter/pass-without-evidence` — the value carried evidence, and it says
+ *   zero examined with zero violations and no declaration. A vacuous pass. The
+ *   remedy is about the selection, not the shape.
+ *
+ * Folding them into one id would make the fixture for either satisfiable by the
+ * other, which is the discrimination failure `check:nonvacuity` exists to catch.
+ *
+ * **What the kernel may say.** ADR-014 §4 is explicit that the kernel "never
+ * names a preset's options at a seam that may not be a preset": a preset that
+ * constructed zero rules owns its own remedy and names it before handing over.
+ * So these messages speak only about the value and the loop that produced it —
+ * the vocabulary any hand-assembler can act on.
+ *
+ * **`expectEmpty` is not an exception to that, it is the reason for the rule's
+ * shape.** It lives on the KERNEL's own `PresetReportOptions`, so naming it
+ * names this package's surface rather than a dialect's — and a product review
+ * found the vacuous-pass message, the one most likely to red an adopter's
+ * build, told them to "declare the set legitimately empty" without saying how.
+ * A remedy an author cannot act on is ADR-009 rule 2's failure, and it sends
+ * them to the one escape the message forbids in its next clause.
+ */
+/** The value handed to an emitter carried no evidence field at all. */
+export declare const EMITTER_NO_RECEIPT = "emitter/no-receipt";
+/** Zero examined, zero violations, no declaration — a pass built from nothing. */
+export declare const EMITTER_PASS_WITHOUT_EVIDENCE = "emitter/pass-without-evidence";
+/**
+ * A declaration that has expired: declared empty, then examined something.
+ *
+ * **This is what makes a declaration legitimate at all.** ADR-010 §3 admits
+ * `.expectEmpty()` precisely because it "fails the day it stops being true" —
+ * a claim that can never be contradicted is not an assertion, and the whole
+ * 2026-09-05 amendment to ADR-014 §3 turns on that property. Without this
+ * finding the emitter would accept a declaration nothing can ever falsify,
+ * which is the shape that amendment refused for `overrides: 'off'`.
+ */
+export declare const EMITTER_EXPIRED_DECLARATION = "emitter/expired-declaration";
+/**
+ * A receipt that claims it never ran, and carries evidence that it did.
+ *
+ * **The falsifier `notRun` was shipped without.** `declaredEmpty` has one — the
+ * expiry above — and that property is the entire reason ADR-010 §3 admits a
+ * declaration at all. `notRun` suppresses too: it is the one condition that
+ * excludes a member from `mergeCollectResults`'s dead-member filter, so a zero
+ * marked `notRun` is a zero the merge will not complain about. A suppressor with
+ * no contradiction is exactly the shape ADR-014 §3's amendment refuses, and
+ * shipping one inside the change that establishes the rule is the defect an
+ * enforcement review caught here.
+ *
+ * A rule that never ran examined nothing and found nothing. Both halves are
+ * checked, because either alone is a lie the other does not cover: `examined > 0`
+ * is a denominator that could not exist, and a violation is a finding that could
+ * not have been produced.
+ */
+export declare const EMITTER_CONTRADICTORY_EVIDENCE = "emitter/contradictory-evidence";
+/**
+ * The verdict's own source loaded nothing — ADR-014 §4.
+ *
+ * Distinct from `emitter/pass-without-evidence`, and the distinction is the
+ * point: a zero-examined verdict *may* be legitimate if the caller declares the
+ * emptiness, but an empty SOURCE may not. §4 states the precedence — "an empty
+ * source (`sourceEmpty`) outranks any declaration and names the source" — and
+ * ADR-010 §3 carries the same rule at the terminal as a `gated` row.
+ *
+ * The gate honoured `declaredEmpty` before it ever looked at `sourceEmpty`, so a
+ * hand-assembled receipt setting both passed silently: the escape hatch the
+ * comment beside that branch said this ADR had closed. Measured before the fix,
+ * `finishPreset(collectResult([], { examined: 0, sourceEmpty: true, declaredEmpty: true }))`
+ * returned green.
+ */
+export declare const EMITTER_SOURCE_EMPTY = "emitter/source-empty";
+/**
+ * Every id this module can produce.
+ *
+ * One list, because there were two: `report.ts` had a four-way `||` and
+ * `dedupe-config-findings.ts` grew a second `Set` of the same four. Both are
+ * private, neither knew about the other, and a fifth id added to one and not the
+ * other silently reintroduces the defect the second was written to fix — N
+ * distinct dead builders collapsing into one finding annotated "they are one
+ * edit". The argument for naming the constants rather than testing an `emitter/`
+ * prefix only holds if there is ONE place to add the next one.
+ *
+ * Internal: exported for the kernel's own consumers, not on the root surface.
+ */
+export declare const EMITTER_IDS: ReadonlySet<string>;
+/** Is this one of the emitter's own findings, as opposed to a caller's? */
+export declare function isEmitterFinding(violation: {
+    ruleId?: string;
+    rule?: string;
+}): boolean;
+/**
+ * The source loaded nothing, so no declaration can rescue the verdict.
+ *
+ * Names the SOURCE, per ADR-014 §4, and says so explicitly — the remedy is to
+ * fix the project or glob, never to declare the emptiness, and a reader told to
+ * "declare it" here would be sent to the one thing that cannot work. The
+ * terminal's `zeroLoadedSourceViolation` says the same thing in the same words;
+ * this is its emitter-seam sibling, for a receipt with no rule facts to carry.
+ */
+export declare function sourceEmptyViolation(): ArchViolation;
+/**
+ * A value reached an emitter with no evidence at all — a bare array, or an
+ * object with no `examined`.
+ *
+ * This fires even when the run was healthy and found real violations, because
+ * the defect is that the verdict cannot be checked, not that it is wrong. That
+ * is deliberate: a shape that *sometimes* carries evidence is a shape nobody can
+ * rely on, and the one path where it matters most is the path where the loop
+ * examined nothing.
+ */
+export declare function noReceiptViolation(): ArchViolation;
+/**
+ * A pass with evidence that proves nothing: zero examined, zero violations, no
+ * declaration.
+ *
+ * The remedy names the selection, never a preset's options — ADR-014 §4.
+ */
+export declare function passWithoutEvidenceViolation(): ArchViolation;
+/**
+ * The declaration was true when written and is not true now.
+ *
+ * The mirror of the terminal's own `expiredExpectEmptyViolation`, at the seam a
+ * preset's declaration reaches (ADR-014 §3). The number IS the finding, so it
+ * is named.
+ */
+export declare function expiredDeclarationViolation(examined: number): ArchViolation;
+/**
+ * `notRun` beside evidence of a run.
+ *
+ * The mirror of {@link expiredDeclarationViolation} for the third state. The
+ * numbers ARE the finding, so both are named: a caller debugging this needs to
+ * know which half contradicted the flag.
+ */
+/**
+ * A flag that quiets a zero, contradicted by the receipt's own evidence.
+ *
+ * **The flag is a parameter because the message names it.** It was hardcoded to
+ * `notRun`, and once `sourceEmpty` became contradictable too, a receipt claiming
+ * an empty source beside real evidence was told to "drop the notRun flag" — a
+ * flag nobody had set, and a remedy that cannot be applied. Four reviewers
+ * measured that on this branch's own headline scenario. ADR-009 rule 2: the
+ * finding names its cause, and the remedy remediates.
+ */
+export declare function contradictoryEvidenceViolation(examined: number, violations: number, flag?: 'notRun' | 'sourceEmpty'): ArchViolation;
+//# sourceMappingURL=emitter-findings.d.ts.map

package/dist/emitter-findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter-findings.d.ts","sourceRoot":"","sources":["../src/emitter-findings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,uBAAuB,CAAA;AAEtD,kFAAkF;AAClF,eAAO,MAAM,6BAA6B,kCAAkC,CAAA;AAE5E;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,gCAAgC,CAAA;AAExE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,8BAA8B,mCAAmC,CAAA;AAE9E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAA;AAE1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,CAM1C,CAAA;AAEF,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,SAAS,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAEvF;AAqBD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,aAAa,CASpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAkBlD;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,aAAa,CAU5D;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAO3E;AAED;;;;;;GAMG;AACH;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,QAAQ,GAAG,aAAwB,GACxC,aAAa,CAqBf"}