@nielspeter/eess 0.2.2 → 0.5.0

package/dist/emitter-findings.js

@@ -0,0 +1,237 @@
+import { UNSUPPRESSABLE } from './unsuppressable.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 const EMITTER_NO_RECEIPT = 'emitter/no-receipt';
+/** Zero examined, zero violations, no declaration — a pass built from nothing. */
+export 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 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 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 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 const EMITTER_IDS = new Set([
+    EMITTER_NO_RECEIPT,
+    EMITTER_PASS_WITHOUT_EVIDENCE,
+    EMITTER_EXPIRED_DECLARATION,
+    EMITTER_CONTRADICTORY_EVIDENCE,
+    EMITTER_SOURCE_EMPTY,
+]);
+/** Is this one of the emitter's own findings, as opposed to a caller's? */
+export function isEmitterFinding(violation) {
+    return EMITTER_IDS.has(violation.ruleId ?? violation.rule ?? '');
+}
+/**
+ * Shared shape. `file: ''` / `line: 0` for the same reason `vacuity-findings.ts`
+ * uses them: the fault is the verdict, not a place in anyone's code.
+ * `bypassFilters` because a suppression mechanism that can suppress the
+ * complaint about itself is not a mechanism.
+ */
+function emitterFinding(ruleId, message) {
+    return {
+        rule: ruleId,
+        ruleId,
+        element: ruleId,
+        file: '',
+        line: 0,
+        message,
+        suggestion: `${message} ${UNSUPPRESSABLE}`,
+        bypassFilters: true,
+    };
+}
+/**
+ * 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 function sourceEmptyViolation() {
+    return emitterFinding(EMITTER_SOURCE_EMPTY, 'this verdict reports success over a source that loaded zero units before any ' +
+        'selection ran — an empty project, an unreadable config, or a glob resolving to ' +
+        'nothing. This outranks any declaration: declaring the emptiness cannot make an ' +
+        'absent source into evidence. Fix the source configuration — the project, the ' +
+        'tsconfig, or the glob — not the declaration.');
+}
+/**
+ * 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 function noReceiptViolation() {
+    return emitterFinding(EMITTER_NO_RECEIPT, 'this verdict arrived with no evidence of what was examined, so eess cannot tell a ' +
+        'clean run from a loop that never ran. Hand the emitter what the pipeline minted — ' +
+        "a builder's violations(), or a preset's result — rather than an array assembled by hand. " +
+        // Naming the call, because the audience changed. This message was written
+        // for someone calling `finishPreset([])` directly; since plan 0263 Phase 2
+        // it is also what a rule-file author meets, and THEIR builder is the thing
+        // returning the array — so "hand the emitter a builder's violations()"
+        // describes what they already did. The changeset's migration line was the
+        // actionable one and lived only in the changelog. `collectResult` and
+        // `mergeCollectResults` are kernel root exports, re-exported by the
+        // dialects, so naming them costs an adopter no second install.
+        'If you are writing the builder: return collectResult(violations, { examined }) ' +
+        'instead of a plain array, where `examined` is how many units you actually ' +
+        'looked at. If you are combining builders, use mergeCollectResults([...]).');
+}
+/**
+ * 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 function passWithoutEvidenceViolation() {
+    return emitterFinding(EMITTER_PASS_WITHOUT_EVIDENCE, 'this verdict reports success over zero examined units: the loop reached its ' +
+        'assertion no times, so nothing was checked and the pass certifies nothing. Widen ' +
+        'the selection, or — if the set is legitimately empty — declare it on the receipt: ' +
+        'collectResult(violations, { examined, declaredEmpty: true }), or .expectEmpty() ' +
+        'on a builder. The declaration expires the day the subject appears, which is why ' +
+        'it is not a mute button. Do not suppress this.');
+}
+/**
+ * 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 function expiredDeclarationViolation(examined) {
+    return emitterFinding(EMITTER_EXPIRED_DECLARATION, `this verdict was declared empty but examined ${String(examined)} unit(s) — the ` +
+        'declaration has expired. If the set legitimately grew past empty, remove the ' +
+        'declaration; the violations above (if any) still stand.');
+}
+/**
+ * `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 function contradictoryEvidenceViolation(examined, violations, flag = 'notRun') {
+    const claim = flag === 'notRun'
+        ? 'is marked as never having run'
+        : 'is marked as having loaded no source at all';
+    const why = flag === 'notRun'
+        ? 'a rule that did not run can have neither'
+        : 'a source that loaded nothing can yield neither';
+    const remedy = flag === 'notRun'
+        ? 'Drop the notRun flag if the rule ran, or drop the evidence if it did not; ' +
+            'notRun exists for a rule turned off, not for one whose result you want quiet.'
+        : 'Drop the sourceEmpty flag if the source loaded, or drop the evidence if it did ' +
+            'not; sourceEmpty describes an instrument that read nothing, not a result you ' +
+            'want quiet.';
+    return emitterFinding(EMITTER_CONTRADICTORY_EVIDENCE, `this verdict ${claim}, but examined ${String(examined)} unit(s) ` +
+        `and carries ${String(violations)} violation(s) — ${why}. ${remedy}`);
+}
+//# sourceMappingURL=emitter-findings.js.map

package/dist/emitter-findings.js.map

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

package/dist/errors.d.ts

@@ -11,4 +11,77 @@ export declare class ArchRuleError extends Error {
     /** The violations that failed the rule, in report order. */
     get violations(): ArchViolation[];
 }
+/**
+ * Is this an `ArchRuleError` — including one thrown by a DIFFERENT copy of this
+ * module?
+ *
+ * `instanceof` is an identity check, and a rule file does not necessarily load
+ * through the same module registry as the CLI that loads it. `load-rules.ts`
+ * uses jiti (bug 0074: a `.ts` rule file must load inside a `"type": "commonjs"`
+ * consumer project), and jiti keeps its own registry — so the `ArchRuleError`
+ * a self-executing rule file throws is a different class object from this one
+ * and `instanceof` is FALSE for an error that is, in every way that matters,
+ * an ArchRuleError.
+ *
+ * Measured: that made `check.ts` skip `ruleFileTruncated()`, so a rule file
+ * whose first rule threw reported the finding and said nothing about the rules
+ * after it that never ran — a silent gap in a red run, which is bug 0029
+ * reopened by the loader. The same hazard exists for any consumer with two
+ * copies of eess-ts on disk (a nested `node_modules`), where the loader is
+ * irrelevant.
+ *
+ * Structural, therefore: the `name` this class stamps in its constructor plus
+ * the `violations` array that is its whole reason to exist. Both are part of the
+ * documented public shape (`ArchViolation[]` on a thrown error), so matching on
+ * them is matching on the contract rather than on a coincidence.
+ */
+export declare function isArchRuleError(error: unknown): error is ArchRuleError;
+/**
+ * Thrown when a RULE is misconfigured — bad arguments to a condition, a
+ * malformed rule file — as opposed to {@link ArchRuleError}, which means the
+ * architecture under test is wrong.
+ *
+ * The two are different faults with different audiences and the CLI already
+ * wants to tell them apart: `rule-file-findings.ts` branches on
+ * `isArchRuleError(error)` and routes everything else into one generic
+ * "rule file failed" path. An untyped `Error` therefore arrives with its
+ * category erased, and a rule author who mistyped an argument is shown the
+ * same surface as an unhandled crash.
+ *
+ * `subject` names what was misconfigured — the condition, predicate or file —
+ * so a caller can render the fault without parsing the message.
+ *
+ * **Why this class exists at all is worth recording.** eess ships an
+ * `agentGuardrails` preset whose `no-generic-errors` rule says a bare `Error`
+ * "loses the type/context callers need to handle it". This repo exempted itself
+ * from running that preset, on a written rationale that the rule fired on
+ * legitimate style. When the preset was finally run here it flagged 17 bare
+ * `Error`s, and the rationale did not survive contact: the caller the rule
+ * describes is real and lives in this package. Dogfooding produced this type.
+ */
+export declare class ArchConfigError extends Error {
+    #private;
+    /**
+     * `options` forwards `cause`, and that is not decoration. `schema-loader.ts`
+     * distinguishes "the `graphql` package is missing" from "it is installed but
+     * failed to load", and the second case is only actionable because the
+     * underlying error travels with it — a fix whose own comment records that
+     * discarding it "used to be reported as 'not installed' too, discarding the
+     * one line that would have told the reader what actually happened". A typed
+     * error that dropped the cause would undo that.
+     */
+    constructor(subject: string, message: string, options?: ErrorOptions);
+    /** What was misconfigured — a condition name, a predicate name, a file path. */
+    get subject(): string;
+}
+/**
+ * Is this an `ArchConfigError` — including one thrown by a DIFFERENT copy of
+ * this module?
+ *
+ * Structural for the same reason {@link isArchRuleError} is: jiti and nested
+ * `node_modules` both put two copies of this class on disk, and `instanceof`
+ * is an identity check. Matches on `name` plus the `subject` accessor that is
+ * this class's whole reason to exist.
+ */
+export declare function isArchConfigError(error: unknown): error is ArchConfigError;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,KAAK;;gBAG1B,UAAU,EAAE,aAAa,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM;IAQxD,4DAA4D;IAC5D,IAAI,UAAU,IAAI,aAAa,EAAE,CAEhC;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,KAAK;;gBAG1B,UAAU,EAAE,aAAa,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM;IAQxD,4DAA4D;IAC5D,IAAI,UAAU,IAAI,aAAa,EAAE,CAEhC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAQtE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,eAAgB,SAAQ,KAAK;;IAGxC;;;;;;;;OAQG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAMpE,gFAAgF;IAChF,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAQ1E"}

package/dist/errors.js

@@ -18,4 +18,97 @@ export class ArchRuleError extends Error {
         return this.#violations;
     }
 }
+/**
+ * Is this an `ArchRuleError` — including one thrown by a DIFFERENT copy of this
+ * module?
+ *
+ * `instanceof` is an identity check, and a rule file does not necessarily load
+ * through the same module registry as the CLI that loads it. `load-rules.ts`
+ * uses jiti (bug 0074: a `.ts` rule file must load inside a `"type": "commonjs"`
+ * consumer project), and jiti keeps its own registry — so the `ArchRuleError`
+ * a self-executing rule file throws is a different class object from this one
+ * and `instanceof` is FALSE for an error that is, in every way that matters,
+ * an ArchRuleError.
+ *
+ * Measured: that made `check.ts` skip `ruleFileTruncated()`, so a rule file
+ * whose first rule threw reported the finding and said nothing about the rules
+ * after it that never ran — a silent gap in a red run, which is bug 0029
+ * reopened by the loader. The same hazard exists for any consumer with two
+ * copies of eess-ts on disk (a nested `node_modules`), where the loader is
+ * irrelevant.
+ *
+ * Structural, therefore: the `name` this class stamps in its constructor plus
+ * the `violations` array that is its whole reason to exist. Both are part of the
+ * documented public shape (`ArchViolation[]` on a thrown error), so matching on
+ * them is matching on the contract rather than on a coincidence.
+ */
+export function isArchRuleError(error) {
+    if (error instanceof ArchRuleError)
+        return true;
+    return (error instanceof Error &&
+        error.name === 'ArchRuleError' &&
+        'violations' in error &&
+        Array.isArray(error.violations));
+}
+/**
+ * Thrown when a RULE is misconfigured — bad arguments to a condition, a
+ * malformed rule file — as opposed to {@link ArchRuleError}, which means the
+ * architecture under test is wrong.
+ *
+ * The two are different faults with different audiences and the CLI already
+ * wants to tell them apart: `rule-file-findings.ts` branches on
+ * `isArchRuleError(error)` and routes everything else into one generic
+ * "rule file failed" path. An untyped `Error` therefore arrives with its
+ * category erased, and a rule author who mistyped an argument is shown the
+ * same surface as an unhandled crash.
+ *
+ * `subject` names what was misconfigured — the condition, predicate or file —
+ * so a caller can render the fault without parsing the message.
+ *
+ * **Why this class exists at all is worth recording.** eess ships an
+ * `agentGuardrails` preset whose `no-generic-errors` rule says a bare `Error`
+ * "loses the type/context callers need to handle it". This repo exempted itself
+ * from running that preset, on a written rationale that the rule fired on
+ * legitimate style. When the preset was finally run here it flagged 17 bare
+ * `Error`s, and the rationale did not survive contact: the caller the rule
+ * describes is real and lives in this package. Dogfooding produced this type.
+ */
+export class ArchConfigError extends Error {
+    #subject;
+    /**
+     * `options` forwards `cause`, and that is not decoration. `schema-loader.ts`
+     * distinguishes "the `graphql` package is missing" from "it is installed but
+     * failed to load", and the second case is only actionable because the
+     * underlying error travels with it — a fix whose own comment records that
+     * discarding it "used to be reported as 'not installed' too, discarding the
+     * one line that would have told the reader what actually happened". A typed
+     * error that dropped the cause would undo that.
+     */
+    constructor(subject, message, options) {
+        super(message, options);
+        this.name = 'ArchConfigError';
+        this.#subject = subject;
+    }
+    /** What was misconfigured — a condition name, a predicate name, a file path. */
+    get subject() {
+        return this.#subject;
+    }
+}
+/**
+ * Is this an `ArchConfigError` — including one thrown by a DIFFERENT copy of
+ * this module?
+ *
+ * Structural for the same reason {@link isArchRuleError} is: jiti and nested
+ * `node_modules` both put two copies of this class on disk, and `instanceof`
+ * is an identity check. Matches on `name` plus the `subject` accessor that is
+ * this class's whole reason to exist.
+ */
+export function isArchConfigError(error) {
+    if (error instanceof ArchConfigError)
+        return true;
+    return (error instanceof Error &&
+        error.name === 'ArchConfigError' &&
+        'subject' in error &&
+        typeof error.subject === 'string');
+}
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,WAAW,CAAiB;IAErC,YAAY,UAA2B,EAAE,MAAe;QACtD,MAAM,OAAO,GAAG,yBAAyB,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,CAAA;QAClH,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;QAC/C,KAAK,CAAC,GAAG,OAAO,GAAG,UAAU,EAAE,CAAC,CAAA;QAChC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAA;QAC3B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAA;IAC/B,CAAC;IAED,4DAA4D;IAC5D,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAA;IACzB,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,WAAW,CAAiB;IAErC,YAAY,UAA2B,EAAE,MAAe;QACtD,MAAM,OAAO,GAAG,yBAAyB,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,CAAA;QAClH,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;QAC/C,KAAK,CAAC,GAAG,OAAO,GAAG,UAAU,EAAE,CAAC,CAAA;QAChC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAA;QAC3B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAA;IAC/B,CAAC;IAED,4DAA4D;IAC5D,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAA;IACzB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,YAAY,aAAa;QAAE,OAAO,IAAI,CAAA;IAC/C,OAAO,CACL,KAAK,YAAY,KAAK;QACtB,KAAK,CAAC,IAAI,KAAK,eAAe;QAC9B,YAAY,IAAI,KAAK;QACrB,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAChC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,QAAQ,CAAQ;IAEzB;;;;;;;;OAQG;IACH,YAAY,OAAe,EAAE,OAAe,EAAE,OAAsB;QAClE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;QAC7B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;IACzB,CAAC;IAED,gFAAgF;IAChF,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAA;IACtB,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,KAAK,YAAY,eAAe;QAAE,OAAO,IAAI,CAAA;IACjD,OAAO,CACL,KAAK,YAAY,KAAK;QACtB,KAAK,CAAC,IAAI,KAAK,iBAAiB;QAChC,SAAS,IAAI,KAAK;QAClB,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAClC,CAAA;AACH,CAAC"}

package/dist/exclusion-comments.d.ts

@@ -26,6 +26,22 @@ export interface ExclusionWarning {
     file: string;
     /** Line number */
     line: number;
+    /**
+     * What kind of fault this is, so a caller can act on it differently.
+     *
+     * `'undocumented'` — the directive is well-formed but states no reason. It is
+     * refused (see the reason-free branches below), and a caller may additionally
+     * promote this to a finding so the author is told what to fix rather than
+     * shown the unrelated violation their waiver was covering. `eess-ts` does.
+     *
+     * `'malformed'` — the directive is broken syntax. Also refused, and the
+     * original violation is already firing, so a stderr line is the right weight.
+     *
+     * Added when the two parsers were unified (ADR-012): only `eess-ts`'s copy had
+     * it, and its `execute-rule` branches on it. Merging without it would have
+     * silently downgraded bug 0039's gate to a stderr line.
+     */
+    kind: 'undocumented' | 'malformed';
 }
 /**
  * Result of parsing exclusion comments from a source file.
@@ -47,6 +63,25 @@ export interface ParseResult {
  *   <!-- eess-exclude <rule-id>: <reason> -->      (markdown / text dialects)
  *   <!-- eess-exclude-start <rule-id>: <reason> --> / <!-- eess-exclude-end -->
  */
-export declare function parseExclusionComments(sourceText: string, filePath: string): ParseResult;
+/**
+ * Blanks the spans of a file that are NOT comments, length- and line-preserving
+ * so every reported position still points at the original.
+ *
+ * A dialect that knows its language supplies one; `eess-ts` passes a
+ * ts-morph-backed masker. See ADR-012.
+ */
+export type MaskNonComment = (sourceText: string, filePath: string) => string;
+export interface ParseExclusionOptions {
+    /**
+     * A dialect's own masker, applied BEFORE the kernel's default.
+     *
+     * Composition, not replacement (ADR-012 clause 3). An injected masker can only
+     * blank MORE than the default, never less, so the worst a bad one can do is
+     * hide a directive (loud) rather than expose one written inside a string
+     * literal (silent, and bug 0154).
+     */
+    mask?: MaskNonComment;
+}
+export declare function parseExclusionComments(sourceText: string, filePath: string, options?: ParseExclusionOptions): ParseResult;
 export declare function isExcludedByComment(violation: ArchViolation, comments: ExclusionComment[]): boolean;
 //# sourceMappingURL=exclusion-comments.d.ts.map

package/dist/exclusion-comments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exclusion-comments.d.ts","sourceRoot":"","sources":["../src/exclusion-comments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAA;IAChB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,UAAU,EAAE,gBAAgB,EAAE,CAAA;IAC9B,wCAAwC;IACxC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAC7B;AAuJD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAyCxF;AAuBD,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,aAAa,EACxB,QAAQ,EAAE,gBAAgB,EAAE,GAC3B,OAAO,CAUT"}
+{"version":3,"file":"exclusion-comments.d.ts","sourceRoot":"","sources":["../src/exclusion-comments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGnD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAA;IAChB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;;;;;;;OAcG;IACH,IAAI,EAAE,cAAc,GAAG,WAAW,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,UAAU,EAAE,gBAAgB,EAAE,CAAA;IAC9B,wCAAwC;IACxC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAC7B;AAuRD;;;;;;;;;;GAUG;AACH;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;AAE7E,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,cAAc,CAAA;CACtB;AAED,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,WAAW,CAsFb;AAuBD,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,aAAa,EACxB,QAAQ,EAAE,gBAAgB,EAAE,GAC3B,OAAO,CAUT"}