@nielspeter/eess 0.4.0 → 0.5.1

package/dist/path-suffix.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Resolve a cited path against a set of repo-relative paths.
+ *
+ * Two dialects had written this independently — `eess-md`'s `uniqueSuffix()`
+ * for `path:line` code pointers, and `eess-crossvalidate`'s `resolveFeature`
+ * for `.feature` citations. Same algorithm, same three-way answer, and after
+ * bug 0254 the same remedy text; bug 0257 is that duplication.
+ *
+ * **Why the kernel.** It is pure string work over a list of paths: no
+ * `ArchProject`, no ts-morph, nothing dialect-shaped. That is exactly
+ * `path-universe.ts`'s argument for living here, and
+ * [ADR-013](../../../adr/013-the-kernel-takes-the-fact-not-the-project.md)'s
+ * test is satisfied — the kernel takes the *fact* (a list of paths), not the
+ * project that produced it. It is family plumbing rather than public API, so it
+ * is exported from `internal.ts` (ADR-011).
+ *
+ * **What it deliberately does not decide.** Whether a `none` is broken, whether
+ * an `ambiguous` fails or warns, whether to consult external roots, what the
+ * message says — all of that is the caller's policy and differs between the two
+ * dialects for good reasons. This answers one question: *which path did they
+ * mean?*
+ */
+/** How a cited path resolves against a set of repo-relative paths. */
+export type PathSuffixMatch = 
+/** The citation IS a repo-relative path. Wins outright, even if the same tail also matches elsewhere. */
+{
+    readonly kind: 'exact';
+    readonly file: string;
+}
+/** Exactly one path ends with the citation on a `/` boundary. */
+ | {
+    readonly kind: 'unique';
+    readonly file: string;
+}
+/** Several do, so the citation names none of them. Candidates in index order. */
+ | {
+    readonly kind: 'ambiguous';
+    readonly files: readonly string[];
+}
+/** Nothing matches. */
+ | {
+    readonly kind: 'none';
+};
+/** A prepared path set. Build once, resolve many. Duplicate inputs collapse. */
+export interface PathSuffixIndex {
+    resolve(wanted: string): PathSuffixMatch;
+}
+/**
+ * Prepare a path set for repeated suffix lookups.
+ *
+ * Indexed by last segment, because the corpora this runs over resolve hundreds
+ * of citations against thousands of paths and a linear scan per citation was
+ * measurable in `eess-md`. The index is the reason this takes the whole set up
+ * front rather than being a plain two-argument function.
+ */
+export declare function pathSuffixIndex(paths: Iterable<string>): PathSuffixIndex;
+//# sourceMappingURL=path-suffix.d.ts.map

package/dist/path-suffix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-suffix.d.ts","sourceRoot":"","sources":["../src/path-suffix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,sEAAsE;AACtE,MAAM,MAAM,eAAe;AACzB,yGAAyG;AACvG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACnD,iEAAiE;GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACpD,iFAAiF;GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE;AACnE,uBAAuB;GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7B,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAA;CACzC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,eAAe,CAsCxE"}

package/dist/path-suffix.js

@@ -0,0 +1,73 @@
+/**
+ * Resolve a cited path against a set of repo-relative paths.
+ *
+ * Two dialects had written this independently — `eess-md`'s `uniqueSuffix()`
+ * for `path:line` code pointers, and `eess-crossvalidate`'s `resolveFeature`
+ * for `.feature` citations. Same algorithm, same three-way answer, and after
+ * bug 0254 the same remedy text; bug 0257 is that duplication.
+ *
+ * **Why the kernel.** It is pure string work over a list of paths: no
+ * `ArchProject`, no ts-morph, nothing dialect-shaped. That is exactly
+ * `path-universe.ts`'s argument for living here, and
+ * [ADR-013](../../../adr/013-the-kernel-takes-the-fact-not-the-project.md)'s
+ * test is satisfied — the kernel takes the *fact* (a list of paths), not the
+ * project that produced it. It is family plumbing rather than public API, so it
+ * is exported from `internal.ts` (ADR-011).
+ *
+ * **What it deliberately does not decide.** Whether a `none` is broken, whether
+ * an `ambiguous` fails or warns, whether to consult external roots, what the
+ * message says — all of that is the caller's policy and differs between the two
+ * dialects for good reasons. This answers one question: *which path did they
+ * mean?*
+ */
+/**
+ * Prepare a path set for repeated suffix lookups.
+ *
+ * Indexed by last segment, because the corpora this runs over resolve hundreds
+ * of citations against thousands of paths and a linear scan per citation was
+ * measurable in `eess-md`. The index is the reason this takes the whole set up
+ * front rather than being a plain two-argument function.
+ */
+export function pathSuffixIndex(paths) {
+    // Deduplicated on entry, not assumed deduplicated. `all` was always a `Set`,
+    // but the per-segment lists used to push every element of the iterable — so a
+    // path appearing twice came back as `{ kind: 'ambiguous', files: [x, x] }`:
+    // one file reported as ambiguous with itself. Unreachable through today's two
+    // callers (both hand it a set or a filesystem walk), which is exactly why it
+    // would have waited for the third — the parameter is an `Iterable<string>`
+    // and nothing in the type says the caller must have deduplicated. Found by
+    // differential fuzzing across 20,000 cases; it was the only class of
+    // disagreement with the implementations this replaced.
+    const all = new Set(paths);
+    const byLastSegment = new Map();
+    for (const rel of all) {
+        const seg = rel.slice(rel.lastIndexOf('/') + 1);
+        const list = byLastSegment.get(seg);
+        if (list)
+            list.push(rel);
+        else
+            byLastSegment.set(seg, [rel]);
+    }
+    return {
+        resolve(wanted) {
+            // Exact first, and it wins outright. A citation that IS a real path is not
+            // ambiguous just because some longer path happens to end the same way —
+            // both dialects had this precedence already, and getting it backwards
+            // would turn correct citations into findings.
+            if (all.has(wanted))
+                return { kind: 'exact', file: wanted };
+            const seg = wanted.slice(wanted.lastIndexOf('/') + 1);
+            // Narrow by last segment, then confirm the FULL suffix on a `/` boundary:
+            // `x.ts` must not match `prefix-x.ts`, and `a/x.ts` must not match
+            // `b/aa/x.ts`.
+            const matches = (byLastSegment.get(seg) ?? []).filter((f) => f.endsWith('/' + wanted));
+            const only = matches[0];
+            if (matches.length === 1 && only !== undefined)
+                return { kind: 'unique', file: only };
+            if (matches.length > 1)
+                return { kind: 'ambiguous', files: matches };
+            return { kind: 'none' };
+        },
+    };
+}
+//# sourceMappingURL=path-suffix.js.map

package/dist/path-suffix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-suffix.js","sourceRoot":"","sources":["../src/path-suffix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAkBH;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAuB;IACrD,6EAA6E;IAC7E,8EAA8E;IAC9E,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,2EAA2E;IAC3E,qEAAqE;IACrE,uDAAuD;IACvD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAS,KAAK,CAAC,CAAA;IAClC,MAAM,aAAa,GAAG,IAAI,GAAG,EAAoB,CAAA;IACjD,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;QAC/C,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;;YACnB,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;IACpC,CAAC;IAED,OAAO;QACL,OAAO,CAAC,MAAc;YACpB,2EAA2E;YAC3E,wEAAwE;YACxE,sEAAsE;YACtE,8CAA8C;YAC9C,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;YAE3D,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;YACrD,0EAA0E;YAC1E,mEAAmE;YACnE,eAAe;YACf,MAAM,OAAO,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC,CAAA;YACtF,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;YACvB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;YACrF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;YACpE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;QACzB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/predicate.d.ts

@@ -41,4 +41,16 @@ export interface Predicate<T> {
      */
     readonly originLabel?: string;
 }
+/**
+ * Record a predicate on a builder, noting it if it arrived after `.should()`.
+ *
+ * A free function for the same reason as `recordExclusions` and
+ * `selectMatching`: the two builders sit in incompatible hierarchies, so there
+ * is no common base to hold a method. The copies were 94% similar and differed
+ * only in comment wording and braces — no behaviour.
+ *
+ * `phase` is read, never written: recording a misplaced predicate is a
+ * diagnosis, not a state change.
+ */
+export declare function recordPredicate<T>(predicate: Predicate<T>, predicates: Predicate<T>[], misplaced: string[], phase: string): void;
 //# sourceMappingURL=predicate.d.ts.map

package/dist/predicate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predicate.d.ts","sourceRoot":"","sources":["../src/predicate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,0DAA0D;IAC1D,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAA;IACzB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;IAE9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B"}
+{"version":3,"file":"predicate.d.ts","sourceRoot":"","sources":["../src/predicate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,0DAA0D;IAC1D,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAA;IACzB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;IAE9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,EAC1B,SAAS,EAAE,MAAM,EAAE,EACnB,KAAK,EAAE,MAAM,GACZ,IAAI,CAON"}

package/dist/predicate.js

@@ -1,2 +1,21 @@
-export {};
+/**
+ * Record a predicate on a builder, noting it if it arrived after `.should()`.
+ *
+ * A free function for the same reason as `recordExclusions` and
+ * `selectMatching`: the two builders sit in incompatible hierarchies, so there
+ * is no common base to hold a method. The copies were 94% similar and differed
+ * only in comment wording and braces — no behaviour.
+ *
+ * `phase` is read, never written: recording a misplaced predicate is a
+ * diagnosis, not a state change.
+ */
+export function recordPredicate(predicate, predicates, misplaced, phase) {
+    predicates.push(predicate);
+    // Bug 0155 state 2: a predicate-only method used after `.should()`. Dual-use
+    // methods dispatch to conditions in that phase and never reach here, so this is
+    // a filter written where an assertion was meant — the one state whose fix is
+    // "move it before .should()", not "add a condition".
+    if (phase === 'condition')
+        misplaced.push(predicate.description);
+}
 //# sourceMappingURL=predicate.js.map

package/dist/predicate.js.map

@@ -1 +1 @@
-{"version":3,"file":"predicate.js","sourceRoot":"","sources":["../src/predicate.ts"],"names":[],"mappings":""}
+{"version":3,"file":"predicate.js","sourceRoot":"","sources":["../src/predicate.ts"],"names":[],"mappings":"AA8CA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAuB,EACvB,UAA0B,EAC1B,SAAmB,EACnB,KAAa;IAEb,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAC1B,6EAA6E;IAC7E,gFAAgF;IAChF,6EAA6E;IAC7E,qDAAqD;IACrD,IAAI,KAAK,KAAK,WAAW;QAAE,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAA;AAClE,CAAC"}

package/dist/preset-dispatch.d.ts

@@ -1,4 +1,4 @@
-import type { ArchViolation } from './violation.js';
+import { type CollectResult } from './collect-result.js';
 import type { RuleMetadata } from './rule-metadata.js';
 import { type PresetReportOptions } from './report.js';
 /** Per-rule severity within a preset. */
@@ -15,11 +15,11 @@ export interface PresetBaseOptions extends PresetReportOptions {
  * Anything with `.rule()` and `.violations()` — works with both
  * `RuleBuilder<T, P>` and `TerminalBuilder` hierarchies, across all dialects.
  */
-interface Dispatchable {
+export interface Dispatchable {
     rule(m: RuleMetadata): {
-        violations(): ArchViolation[];
+        violations(): CollectResult;
     };
-    violations(): ArchViolation[];
+    violations(): CollectResult;
 }
 /**
  * Dispatch a single rule within a preset.
@@ -30,38 +30,10 @@ interface Dispatchable {
  */
 export declare function dispatchRule(builder: Dispatchable, rule: string | (RuleMetadata & {
     id: string;
-}), defaultSeverity: RuleSeverity, overrides: Record<string, RuleSeverity> | undefined): ArchViolation[];
+}), defaultSeverity: RuleSeverity, overrides: Record<string, RuleSeverity> | undefined): CollectResult;
 /**
  * Validate override keys against known rule IDs. Warns for unrecognized keys
  * (likely typos).
  */
-export declare function validateOverrides(overrides: Record<string, RuleSeverity> | undefined, knownIds: string[]): void;
-/**
- * A configuration finding for a preset call that constructed **zero** rules —
- * every optional capability was left off, or a required discovery pattern
- * (a folder glob, a repositories glob) matched nothing, so the call checked
- * nothing and would otherwise pass silently. The vacuity matrix
- * (`scripts/vacuity-matrix.mjs`) is what proves a preset needs this: it
- * probes every published preset at its minimal type-correct call, and a
- * preset reaching `fail-open` there is exactly this shape.
- *
- * Unsuppressable (ADR-010) for the same reason a zero-examined rule is: the
- * caller's mistake is in how the preset was configured, not in the code the
- * preset would have checked, and `.excluding()`/a baseline/`--changed` all
- * aim at the latter.
- *
- * @param presetName - The preset's own name, e.g. `'agentGuardrails'`.
- * @param optionsHint - The option names that would enable a rule, for the
- *   remedy — e.g. `'noGenericErrors, noStubs, noEmptyBodies'`.
- */
-export declare function presetConstructsNothingViolation(presetName: string, optionsHint: string): ArchViolation;
-/**
- * Emit (stderr text) and throw a single `ArchRuleError` with all aggregated
- * violations, if any. Kept for backward compatibility; it is now `finishPreset`
- * in the default `throw` mode. New presets take `PresetReportOptions` and call
- * `finishPreset` so a caller can opt into `report: 'return'` / `--format json`
- * (plan 0070).
- */
-export declare function throwIfViolations(violations: ArchViolation[]): void;
-export {};
+export declare function validateOverrides(overrides: Partial<Record<string, RuleSeverity>> | undefined, knownIds: readonly string[]): void;
 //# sourceMappingURL=preset-dispatch.d.ts.map

package/dist/preset-dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preset-dispatch.d.ts","sourceRoot":"","sources":["../src/preset-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAIpE,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAA;AAEnD;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CACzC;AAED;;;GAGG;AACH,UAAU,YAAY;IACpB,IAAI,CAAC,CAAC,EAAE,YAAY,GAAG;QAAE,UAAU,IAAI,aAAa,EAAE,CAAA;KAAE,CAAA;IACxD,UAAU,IAAI,aAAa,EAAE,CAAA;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,MAAM,GAAG,CAAC,YAAY,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9C,eAAe,EAAE,YAAY,EAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,GAClD,aAAa,EAAE,CAwBjB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,EACnD,QAAQ,EAAE,MAAM,EAAE,GACjB,IAAI,CAWN;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,aAAa,CAcf;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,IAAI,CAEnE"}
+{"version":3,"file":"preset-dispatch.d.ts","sourceRoot":"","sources":["../src/preset-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,qBAAqB,CAAA;AAEvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGtD,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAA;AAEnD;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CACzC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,CAAC,EAAE,YAAY,GAAG;QAAE,UAAU,IAAI,aAAa,CAAA;KAAE,CAAA;IACtD,UAAU,IAAI,aAAa,CAAA;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,MAAM,GAAG,CAAC,YAAY,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9C,eAAe,EAAE,YAAY,EAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,GAClD,aAAa,CA2Cf;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAM/B,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,GAAG,SAAS,EAC5D,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,IAAI,CAWN"}

package/dist/preset-dispatch.js

@@ -1,8 +1,7 @@
+import { collectResult } from './collect-result.js';
 import { severityFor } from './violation.js';
 import { formatViolations } from './format.js';
-import { finishPreset } from './report.js';
 import { writeStderr } from './stderr.js';
-import { UNSUPPRESSABLE } from './unsuppressable.js';
 /**
  * Dispatch a single rule within a preset.
  *
@@ -17,19 +16,34 @@ export function dispatchRule(builder, rule, defaultSeverity, overrides) {
     // agent`, not just the id.
     const meta = typeof rule === 'string' ? { id: rule } : rule;
     const effective = overrides?.[meta.id] ?? defaultSeverity;
-    if (effective === 'off')
-        return [];
+    if (effective === 'off') {
+        // A real, measured zero — and deliberately NOT `declaredEmpty`.
+        //
+        // ADR-014 §3, amended 2026-09-05: a declaration is one a caller MADE over a
+        // live instrument, never one eess infers from a configuration.
+        // `overrides: { id: 'off' }` is an instruction, and it is byte-identical
+        // whether the author meant "I have scoped this out" or "I turned this off to
+        // stop a finding" — eess is not positioned to tell those apart, so by
+        // ADR-013's rule it must not decide. Marking it declared here would mint,
+        // on the author's behalf, exactly the declaration `declaredEmptyFindings`
+        // refuses to let them write ("'off' deleted the rule, so the declaration
+        // about it is dead").
+        //
+        // The consequence is deliberate: a preset with every rule off sums to zero
+        // examined with no declaration, and the emitter reports it (bug 0261).
+        return collectResult([], { examined: 0, notRun: true });
+    }
     const violations = builder.rule(meta).violations();
     if (effective === 'warn') {
         if (violations.length > 0) {
             writeStderr(formatViolations(violations));
         }
         // `bypassFilters` outranks a per-rule `overrides: { id: 'warn' }` — see
-        // `severityFor`. A config finding like `presetConstructsNothingViolation`
-        // is `UNSUPPRESSABLE` by its own text; silently dropping it here just
-        // because its OWN rule was downgraded is exactly the suppression path
-        // that text promises does not exist.
-        return violations.filter((v) => severityFor(v, 'warn') === 'error');
+        // `severityFor`. A config finding — a zero-examined rule, or a preset that
+        // constructed nothing — is `UNSUPPRESSABLE` by its own text; silently
+        // dropping it here just because its OWN rule was downgraded is exactly the
+        // suppression path that text promises does not exist.
+        return collectResult(violations.filter((v) => severityFor(v, 'warn') === 'error'), { examined: violations.examined });
     }
     return violations;
 }
@@ -37,7 +51,13 @@ export function dispatchRule(builder, rule, defaultSeverity, overrides) {
  * Validate override keys against known rule IDs. Warns for unrecognized keys
  * (likely typos).
  */
-export function validateOverrides(overrides, knownIds) {
+export function validateOverrides(
+// `Partial<Record<...>>` and `readonly`, widened from the narrower shapes this
+// signature had, so `eess-ts`'s byte-identical copy could be deleted rather
+// than kept for its types. Both are strictly more permissive: `Partial` admits
+// an explicit `undefined` value, `readonly` admits a frozen list. No caller
+// loses anything.
+overrides, knownIds) {
     if (!overrides)
         return;
     const knownSet = new Set(knownIds);
@@ -48,46 +68,4 @@ export function validateOverrides(overrides, knownIds) {
         }
     }
 }
-/**
- * A configuration finding for a preset call that constructed **zero** rules —
- * every optional capability was left off, or a required discovery pattern
- * (a folder glob, a repositories glob) matched nothing, so the call checked
- * nothing and would otherwise pass silently. The vacuity matrix
- * (`scripts/vacuity-matrix.mjs`) is what proves a preset needs this: it
- * probes every published preset at its minimal type-correct call, and a
- * preset reaching `fail-open` there is exactly this shape.
- *
- * Unsuppressable (ADR-010) for the same reason a zero-examined rule is: the
- * caller's mistake is in how the preset was configured, not in the code the
- * preset would have checked, and `.excluding()`/a baseline/`--changed` all
- * aim at the latter.
- *
- * @param presetName - The preset's own name, e.g. `'agentGuardrails'`.
- * @param optionsHint - The option names that would enable a rule, for the
- *   remedy — e.g. `'noGenericErrors, noStubs, noEmptyBodies'`.
- */
-export function presetConstructsNothingViolation(presetName, optionsHint) {
-    const message = `${presetName}(...) constructed zero rules at this call — no capability of this ` +
-        `preset was enabled, or a discovery pattern matched nothing, so it checks nothing ` +
-        `and passes silently. Enable at least one option (${optionsHint}), or remove the call.`;
-    return {
-        rule: presetName,
-        element: presetName,
-        file: '',
-        line: 0,
-        message,
-        suggestion: `${message} ${UNSUPPRESSABLE}`,
-        bypassFilters: true,
-    };
-}
-/**
- * Emit (stderr text) and throw a single `ArchRuleError` with all aggregated
- * violations, if any. Kept for backward compatibility; it is now `finishPreset`
- * in the default `throw` mode. New presets take `PresetReportOptions` and call
- * `finishPreset` so a caller can opt into `report: 'return'` / `--format json`
- * (plan 0070).
- */
-export function throwIfViolations(violations) {
-    finishPreset(violations, { report: 'throw' });
-}
 //# sourceMappingURL=preset-dispatch.js.map

package/dist/preset-dispatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"preset-dispatch.js","sourceRoot":"","sources":["../src/preset-dispatch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,YAAY,EAA4B,MAAM,aAAa,CAAA;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAuBpD;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAqB,EACrB,IAA8C,EAC9C,eAA6B,EAC7B,SAAmD;IAEnD,8EAA8E;IAC9E,gFAAgF;IAChF,6EAA6E;IAC7E,2BAA2B;IAC3B,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IAC3D,MAAM,SAAS,GAAG,SAAS,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,eAAe,CAAA;IACzD,IAAI,SAAS,KAAK,KAAK;QAAE,OAAO,EAAE,CAAA;IAElC,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAA;IAElD,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACzB,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,WAAW,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAA;QAC3C,CAAC;QACD,wEAAwE;QACxE,0EAA0E;QAC1E,sEAAsE;QACtE,sEAAsE;QACtE,qCAAqC;QACrC,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,CAAA;IACrE,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAmD,EACnD,QAAkB;IAElB,IAAI,CAAC,SAAS;QAAE,OAAM;IACtB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAA;IAClC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,WAAW,CACT,wBAAwB,GAAG,4CAA4C;gBACrE,oBAAoB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5C,CAAA;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gCAAgC,CAC9C,UAAkB,EAClB,WAAmB;IAEnB,MAAM,OAAO,GACX,GAAG,UAAU,oEAAoE;QACjF,mFAAmF;QACnF,oDAAoD,WAAW,wBAAwB,CAAA;IACzF,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,UAAU;QACnB,IAAI,EAAE,EAAE;QACR,IAAI,EAAE,CAAC;QACP,OAAO;QACP,UAAU,EAAE,GAAG,OAAO,IAAI,cAAc,EAAE;QAC1C,aAAa,EAAE,IAAI;KACpB,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA2B;IAC3D,YAAY,CAAC,UAAU,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAA;AAC/C,CAAC"}
+{"version":3,"file":"preset-dispatch.js","sourceRoot":"","sources":["../src/preset-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAuBzC;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAqB,EACrB,IAA8C,EAC9C,eAA6B,EAC7B,SAAmD;IAEnD,8EAA8E;IAC9E,gFAAgF;IAChF,6EAA6E;IAC7E,2BAA2B;IAC3B,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IAC3D,MAAM,SAAS,GAAG,SAAS,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,eAAe,CAAA;IACzD,IAAI,SAAS,KAAK,KAAK,EAAE,CAAC;QACxB,gEAAgE;QAChE,EAAE;QACF,4EAA4E;QAC5E,+DAA+D;QAC/D,yEAAyE;QACzE,6EAA6E;QAC7E,sEAAsE;QACtE,0EAA0E;QAC1E,0EAA0E;QAC1E,yEAAyE;QACzE,sBAAsB;QACtB,EAAE;QACF,2EAA2E;QAC3E,uEAAuE;QACvE,OAAO,aAAa,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IACzD,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAA;IAElD,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACzB,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,WAAW,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAA;QAC3C,CAAC;QACD,wEAAwE;QACxE,2EAA2E;QAC3E,sEAAsE;QACtE,2EAA2E;QAC3E,sDAAsD;QACtD,OAAO,aAAa,CAClB,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,EAC5D,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAClC,CAAA;IACH,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;AAC/B,+EAA+E;AAC/E,4EAA4E;AAC5E,+EAA+E;AAC/E,4EAA4E;AAC5E,kBAAkB;AAClB,SAA4D,EAC5D,QAA2B;IAE3B,IAAI,CAAC,SAAS;QAAE,OAAM;IACtB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAA;IAClC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,WAAW,CACT,wBAAwB,GAAG,4CAA4C;gBACrE,oBAAoB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5C,CAAA;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/report.d.ts

@@ -1,4 +1,4 @@
-import type { ArchViolation } from './violation.js';
+import { type CollectResult } from './collect-result.js';
 import type { OutputFormat } from './check-options.js';
 /**
  * How a preset delivers its violations (plan 0070, ADR-008):
@@ -18,6 +18,30 @@ export interface ReportOptions {
 export interface PresetReportOptions extends ReportOptions {
     /** Delivery mode. Default `throw`. */
     readonly report?: ReportMode;
+    /**
+     * Declare that this preset's subject legitimately does not exist here —
+     * [ADR-010](../../../adr/010-a-pass-is-constructed-from-evidence.md) §3.
+     *
+     * **On the shared options type, not on six preset interfaces**, because
+     * ADR-010 §3's second clause is about presets as a class: "A preset user does
+     * not hold the builder; if a preset option cannot carry the user's
+     * empty-declaration to the mint, their only reachable remedy is disabling the
+     * option — deleting coverage permanently (ADR-009 rule 1's trained-suppression
+     * dynamic, reproduced by this ADR's own gate if unaddressed)." A preset that
+     * examines nothing and cannot be told so leaves its user exactly one exit, and
+     * it is the wrong one.
+     *
+     * **It expires**, which is the only reason it is admissible at all: declare
+     * this and then examine something, and the emitter reports
+     * `emitter/expired-declaration`. A claim nothing can contradict is not an
+     * assertion — the property ADR-014 §3's 2026-09-05 amendment turns on when it
+     * refuses to infer a declaration from `overrides: 'off'`.
+     *
+     * Use it for a corpus with no ER diagrams, a suite with no exemptions, a
+     * project that genuinely has none of this preset's subject. Do not use it to
+     * quiet a preset whose glob is wrong: the day the glob is fixed, this reddens.
+     */
+    readonly expectEmpty?: boolean;
 }
 /**
  * How many violations this module has actually WRITTEN, ever.
@@ -32,13 +56,13 @@ export interface PresetReportOptions extends ReportOptions {
  * exactly that case. Count emissions, not silences.
  */
 export declare function violationsEmittedCount(): number;
-export declare function reportViolations(violations: ArchViolation[], options?: ReportOptions): void;
+export declare function reportViolations(violations: CollectResult, options?: ReportOptions): CollectResult;
 /**
  * Finish a preset: deliver its aggregated violations per the requested mode
- * (plan 0070). `throw` (default) emits then throws — backward-compatible with
- * `throwIfViolations`; `return` hands the violations back untouched (the caller
- * owns emission and control flow); `warn` emits without throwing. Always
- * returns the violations, so a caller can inspect them regardless of mode.
+ * (plan 0070). `throw` (default) emits then throws; `return` hands the
+ * violations back untouched (the caller owns emission and control flow);
+ * `warn` emits without throwing. Always returns the violations, so a caller can
+ * inspect them regardless of mode.
  */
-export declare function finishPreset(violations: ArchViolation[], options?: PresetReportOptions): ArchViolation[];
+export declare function finishPreset(violations: CollectResult, options?: PresetReportOptions): CollectResult;
 //# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAMtD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEpD,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAoB,SAAQ,aAAa;IACxD,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAC7B;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,aAAa,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI,CAa/F;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EAAE,EAC3B,OAAO,GAAE,mBAAwB,GAChC,aAAa,EAAE,CAQjB"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAA8B,MAAM,qBAAqB,CAAA;AAUpF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAMtD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEpD,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAoB,SAAQ,aAAa;IACxD,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAA;IAE5B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAC/B;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AA6HD,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,aAAa,EACzB,OAAO,GAAE,aAAkB,GAC1B,aAAa,CAqBf;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EACzB,OAAO,GAAE,mBAAwB,GAChC,aAAa,CAoCf"}