@nielspeter/eess 0.4.0 → 0.5.1

package/dist/errors.d.ts

@@ -36,4 +36,52 @@ export declare class ArchRuleError extends Error {
  * 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;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAQtE"}
+{"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

@@ -50,4 +50,65 @@ export function isArchRuleError(error) {
         '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;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"}
+{"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"}

package/dist/exclusion-comments.js

@@ -1,10 +1,55 @@
+import { maskNonCommentSpans, maskMarkdownCodeSpans } from './mask-non-comment.js';
 // Single-line: // eess-exclude <rule-id>[, <rule-id>]: <reason>
 // Single-line without reason: // eess-exclude <rule-id>
-const SINGLE_LINE_RE = /\/\/\s*eess-exclude\s+(.+)/;
+// The directive must OPEN its comment (bug 0154). Masking alone took this file's
+// own false-positive count from 12 to 7; the rest were genuine line comments that
+// merely DESCRIBE the grammar — like the line above this one. No lexical rule can
+// separate those, but anchoring to the start of the comment body separates all of
+// them from every real directive, including the trailing `code // eess-exclude …`
+// form.
+//
+// Rejected alternative: validating the rule-id's shape. It rejects `<rule-id>`
+// and still accepts `// see eess-exclude a/b: why`, and it couples this parser to
+// an id grammar nothing else enforces.
+const SINGLE_LINE_RE = /^[ \t]*eess-exclude[ \t]+(.+)/;
+/**
+ * The body of a line's FIRST `//` comment, or undefined if it has none.
+ *
+ * The directive must open the comment, and it must be the comment the line
+ * actually starts — not any `//` on the line. A grammar description carries two:
+ *
+ *     // Single-line: // eess-exclude <rule-id>: <reason>
+ *
+ * Anchoring to `//` alone matches the second one and reads the file's own
+ * documentation as 8 live waivers. Taking the first `//` and requiring the
+ * directive at the start of its body separates every description from every real
+ * directive, including the trailing `code // eess-exclude …` form, whose first
+ * `//` is the directive's own.
+ */
+const CODE_LIKE = /\.(?:[cm]?[jt]sx?|vue|svelte)$/i;
+const MARKDOWN_LIKE = /\.(?:md|markdown|mdx)$/i;
+/**
+ * The HTML-comment forms exist for text dialects whose sources have no `//` —
+ * markdown corpora and the like. In a `.ts` file `// <!-- eess-exclude … -->` is
+ * prose describing the grammar, and reading it accounted for the last 2 of this
+ * very file's own false hits (bug 0154).
+ */
+function htmlFormsApply(filePath) {
+    return !CODE_LIKE.test(filePath);
+}
+function firstCommentBody(line) {
+    const at = line.indexOf('//');
+    return at === -1 ? undefined : line.slice(at + 2);
+}
 // Block start: // eess-exclude-start <rule-id>[, <rule-id>]: <reason>
-const BLOCK_START_RE = /\/\/\s*eess-exclude-start\s+(.+)/;
+// The trailing group is OPTIONAL. A bare `// eess-exclude-start` (no ids, no
+// reason) used to match nothing at all — so it pushed no frame, said nothing,
+// and the next `-end` closed the ENCLOSING block. Same two symptoms as the
+// reason-free case, through a shape the reason-free fix did not reach: it is a
+// bracket the reader can see, so it must consume the `-end` written for it.
+const BLOCK_START_RE = /^[ \t]*eess-exclude-start(?:[ \t]+(.*))?[ \t]*$/;
 // Block end: // eess-exclude-end
-const BLOCK_END_RE = /\/\/\s*eess-exclude-end\b/;
+const BLOCK_END_RE = /^[ \t]*eess-exclude-end\b/;
 // HTML-comment forms — the same directives for text dialects whose sources
 // aren't `//`-commented (markdown corpora, and any future text dialect).
 // <!-- eess-exclude <rule-id>[, <rule-id>]: <reason> -->
@@ -37,19 +82,24 @@ function parseRuleIdsAndReason(content) {
 }
 /** Handle a block-end directive line. */
 function handleBlockEnd(openBlocks, exclusions, warnings, filePath, lineNum) {
-    if (openBlocks.size === 0) {
+    // Bug 0158: pop the INNERMOST frame. Closing every open block meant an inner
+    // `-end` silently ended the outer one, so the outer waiver stopped applying
+    // partway through the region it was written for — two wrong results from one
+    // input, and neither reported.
+    const frame = openBlocks.pop();
+    if (frame === undefined) {
         warnings.push({
             message: `eess-exclude-end without matching start`,
             file: filePath,
             line: lineNum,
+            kind: 'malformed',
         });
         return;
     }
-    for (const [, comment] of openBlocks) {
+    for (const comment of frame) {
         comment.endLine = lineNum;
         exclusions.push(comment);
     }
-    openBlocks.clear();
 }
 /** Emit undocumented-exclusion warnings for each rule ID when no reason is given. */
 function warnUndocumented(warnings, ruleIds, directive, filePath, lineNum) {
@@ -60,32 +110,85 @@ function warnUndocumented(warnings, ruleIds, directive, filePath, lineNum) {
                 `  Fix: Add a reason — // ${directive} ${ruleId}: <why>`,
             file: filePath,
             line: lineNum,
+            kind: 'undocumented',
         });
     }
 }
 /** Handle a block-start directive line. */
 function handleBlockStart(content, openBlocks, warnings, filePath, lineNum) {
-    if (openBlocks.size > 0) {
+    const { ruleIds, reason } = parseRuleIdsAndReason(content);
+    if (ruleIds.length === 0) {
+        // A `-start` naming no rule at all. It still consumes its `-end` (see the
+        // regex comment), but it is malformed and saying nothing about it would be
+        // the silence this whole grammar is written to refuse.
         warnings.push({
-            message: `Nested eess-exclude-start — close existing block first`,
+            message: `eess-exclude-start names no rule id. ` +
+                `Fix: write // eess-exclude-start <rule-id>: <why>, or delete the directive ` +
+                `and its matching -end.`,
             file: filePath,
             line: lineNum,
+            kind: 'malformed',
         });
+        openBlocks.push(ruleIds.map((ruleId) => ({
+            ruleId,
+            reason,
+            file: filePath,
+            line: lineNum,
+            isBlock: true,
+        })));
         return;
     }
-    const { ruleIds, reason } = parseRuleIdsAndReason(content);
     if (reason === '') {
         warnUndocumented(warnings, ruleIds, 'eess-exclude-start', filePath, lineNum);
-    }
-    for (const ruleId of ruleIds) {
-        openBlocks.set(ruleId, {
+        // Push an EMPTY frame rather than returning. Refusing the waiver and
+        // refusing the frame are different things: `-start`/`-end` is a bracket
+        // language, so a `-start` the reader can see must consume the `-end` the
+        // reader wrote for it, whatever we decide about its reason.
+        //
+        // Returning here — as this did when bug 0158's two halves shipped together —
+        // let the next `-end` pop the OUTER frame, so a valid enclosing waiver
+        // stopped early and a balanced file reported "end without matching start".
+        // That is precisely the frame-mangling 0158's nesting half removed,
+        // reintroduced by its reason-required half. Empty means it suppresses
+        // nothing, which is the refusal; present means the brackets still pair.
+        openBlocks.push(ruleIds.map((ruleId) => ({
             ruleId,
             reason,
             file: filePath,
             line: lineNum,
             isBlock: true,
+        })));
+        return;
+    }
+    // A rule re-opened while already open is warned but still applied. The likeliest
+    // cause is a missing `-end`, which the author wants to know; refusing it is what
+    // produced the early-close bug. Ported from `eess-ts` when the parsers were
+    // unified (ADR-012) — the kernel had no such warning, so `eess-md`,
+    // `eess-mermaid` and `eess-gherkin` never got it.
+    const alreadyOpen = new Set(openBlocks.flat().map((c) => c.ruleId));
+    for (const ruleId of ruleIds) {
+        if (!alreadyOpen.has(ruleId))
+            continue;
+        warnings.push({
+            message: `eess-exclude-start for '${ruleId}' is already open — ` +
+                `the enclosing block covers this region. Fix: remove this directive, ` +
+                `or close the enclosing block first if the nesting was unintended.`,
+            file: filePath,
+            line: lineNum,
+            kind: 'malformed',
         });
     }
+    // Bug 0158: nesting is supported rather than refused. Blocks are a STACK, not
+    // a map keyed by rule id — the map dropped an inner `-start` outright, and a
+    // second start for the same id overwrote the first. One `-start` pushes one
+    // frame, whatever number of ids it names.
+    openBlocks.push(ruleIds.map((ruleId) => ({
+        ruleId,
+        reason,
+        file: filePath,
+        line: lineNum,
+        isBlock: true,
+    })));
 }
 /** Handle a single-line exclude directive. */
 function handleSingleLine(content, exclusions, warnings, filePath, lineNum) {
@@ -93,6 +196,21 @@ function handleSingleLine(content, exclusions, warnings, filePath, lineNum) {
     if (content.startsWith('-start') || content.startsWith('-end'))
         return;
     const { ruleIds, reason } = parseRuleIdsAndReason(content);
+    // Bug 0158: the grammar documents `<rule-id>: <reason>`, and a reason-free
+    // directive must not silence a real finding while the build exits 0.
+    //
+    // **How that is enforced changed in ADR-012, and the change is the point.**
+    // This used to `return` — refusing the waiver — so the author saw the original
+    // violation and a line on stderr about their directive. `eess-ts` had always
+    // done the opposite (bug 0039): apply the waiver, and let `execute-rule`
+    // replace the suppressed finding with an UNSUPPRESSABLE one saying the waiver
+    // states no reason. Both end red; the second tells the author what to fix
+    // instead of showing them the thing they were waiving.
+    //
+    // Unifying the two parsers forced a choice, and `eess-ts`'s is the better
+    // design, so the kernel adopts it — which means the other four dialects gain
+    // it. It is safe here because the kernel's own `execute-rule` now does the
+    // promotion; applying without promoting would be the fail-open.
     if (reason === '') {
         warnUndocumented(warnings, ruleIds, 'eess-exclude', filePath, lineNum);
     }
@@ -106,51 +224,81 @@ function handleSingleLine(content, exclusions, warnings, filePath, lineNum) {
         });
     }
 }
-/**
- * Scan a source file for eess-exclude comments.
- *
- * Supported formats:
- *   // eess-exclude <rule-id>: <reason>
- *   // eess-exclude-start <rule-id>: <reason>
- *   // eess-exclude-end
- *   // eess-exclude <rule-a>, <rule-b>: <reason>
- *   <!-- eess-exclude <rule-id>: <reason> -->      (markdown / text dialects)
- *   <!-- eess-exclude-start <rule-id>: <reason> --> / <!-- eess-exclude-end -->
- */
-export function parseExclusionComments(sourceText, filePath) {
-    const lines = sourceText.split('\n');
+export function parseExclusionComments(sourceText, filePath, options) {
+    // Bug 0154: read directives from MASKED text, never the raw source. Strings,
+    // templates, regex literals and block comments are blanked first — a directive
+    // written inside one is prose, and reading it silently waived a real finding on
+    // the next line. Masking is length- and line-preserving, so every position
+    // reported below is still the position in the original file.
+    // Mask with the lexer that matches the file. Running the JS/TS one over
+    // markdown made a stray backtick swallow every directive after it — the same
+    // question (is this text an example or an instance?) needs the host language's
+    // answer, not one language's answer everywhere.
+    //
+    // Routed on MARKDOWN specifically, not on "not code". The first version used
+    // `!CODE_LIKE`, which handed `.mmd`, `.feature`, `.yml` and everything else to
+    // the markdown lexer — and a `.mmd` node label is a quoted string, which the
+    // JS masker blanks and the markdown one does not. That is the very mistake this
+    // comment describes, committed by the fix for it. Anything neither code nor
+    // markdown keeps the conservative masker: over-masking hides a directive
+    // (loud), under-masking invents one (silent).
+    const defaultMask = CODE_LIKE.test(filePath)
+        ? maskNonCommentSpans
+        : MARKDOWN_LIKE.test(filePath)
+            ? maskMarkdownCodeSpans
+            : maskNonCommentSpans;
+    // The dialect's masker runs FIRST and the default runs over its output, so the
+    // default's protection cannot be opted out of (ADR-012). A dialect supplies
+    // accuracy; it cannot supply permission.
+    const injected = options?.mask;
+    const masked = injected ? defaultMask(injected(sourceText, filePath)) : defaultMask(sourceText);
+    const lines = masked.split('\n');
+    const htmlApply = htmlFormsApply(filePath);
     const exclusions = [];
     const warnings = [];
-    const openBlocks = new Map();
+    const openBlocks = [];
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         if (line === undefined)
             continue;
         const lineNum = i + 1;
         // Check block end first (before start/single so we don't match -start as single)
-        if (BLOCK_END_RE.test(line) || HTML_BLOCK_END_RE.test(line)) {
+        // The `//` forms read the FIRST comment's body; the HTML forms read the
+        // whole line, since they are for text dialects with no `//` at all.
+        const body = firstCommentBody(line);
+        if ((body !== undefined && BLOCK_END_RE.test(body)) ||
+            (htmlApply && HTML_BLOCK_END_RE.test(line))) {
             handleBlockEnd(openBlocks, exclusions, warnings, filePath, lineNum);
             continue;
         }
         // Check block start
-        const startMatch = BLOCK_START_RE.exec(line) ?? HTML_BLOCK_START_RE.exec(line);
-        if (startMatch?.[1]) {
-            handleBlockStart(startMatch[1], openBlocks, warnings, filePath, lineNum);
+        const startMatch = (body === undefined ? null : BLOCK_START_RE.exec(body)) ??
+            (htmlApply ? HTML_BLOCK_START_RE.exec(line) : null);
+        // `startMatch !== null`, not `startMatch?.[1]`. The capture is optional now, so
+        // a bare `// eess-exclude-start` matches with group 1 undefined — and testing
+        // the GROUP threw that line away again, which is the same "no frame, silent,
+        // enclosing block closes early" defect one level up from the regex.
+        if (startMatch !== null) {
+            handleBlockStart(startMatch[1] ?? '', openBlocks, warnings, filePath, lineNum);
             continue;
         }
         // Check single-line exclude (must not match block directives)
-        const singleMatch = SINGLE_LINE_RE.exec(line) ?? HTML_SINGLE_RE.exec(line);
+        const singleMatch = (body === undefined ? null : SINGLE_LINE_RE.exec(body)) ??
+            (htmlApply ? HTML_SINGLE_RE.exec(line) : null);
         if (singleMatch?.[1]) {
             handleSingleLine(singleMatch[1], exclusions, warnings, filePath, lineNum);
         }
     }
     // Any unclosed blocks are errors
-    for (const [, comment] of openBlocks) {
-        warnings.push({
-            message: `eess-exclude-start without matching end for rule '${comment.ruleId}'`,
-            file: filePath,
-            line: comment.line,
-        });
+    for (const frame of openBlocks) {
+        for (const comment of frame) {
+            warnings.push({
+                message: `eess-exclude-start without matching end for rule '${comment.ruleId}'`,
+                file: filePath,
+                line: comment.line,
+                kind: 'malformed',
+            });
+        }
     }
     return { exclusions, warnings };
 }

package/dist/exclusion-comments.js.map

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

package/dist/execute-rule.d.ts

@@ -1,4 +1,5 @@
 import type { ArchViolation } from './violation.js';
+import { type CollectResult } from './collect-result.js';
 import type { CheckOptions } from './check-options.js';
 import type { RuleMetadata } from './rule-metadata.js';
 /**
@@ -6,8 +7,17 @@ import type { RuleMetadata } from './rule-metadata.js';
  * Shared across all builder types (RuleBuilder, SliceRuleBuilder,
  * SchemaRuleBuilder, ResolverRuleBuilder, PairFinalBuilder, SmellBuilder).
  */
-interface ExecuteRuleContext {
+export interface ExecuteRuleContext {
     reason?: string;
+    /**
+     * This rule's own sentence, deferred (bug 0258).
+     *
+     * A thunk rather than a string because `filterContext()` runs on every
+     * terminal call and this is only read when an id-less rule turns out to have
+     * an exclusion comment it cannot honour — the same shape `facts()` already
+     * uses for `describeRule` a few lines above it.
+     */
+    describe?: () => string;
     metadata?: RuleMetadata;
     exclusions?: (string | RegExp)[];
     silentIndices?: Set<number>;
@@ -28,10 +38,9 @@ export declare function applyFilters(violations: ArchViolation[], ctx: ExecuteRu
 /**
  * Execute the terminal "check" action: apply options, format, throw on violations.
  */
-export declare function executeCheck(violations: ArchViolation[], ctx: ExecuteRuleContext, options?: CheckOptions): void;
+export declare function executeCheck(violations: CollectResult, ctx: ExecuteRuleContext, options?: CheckOptions): void;
 /**
  * Execute the terminal "warn" action: apply options, format, log to stderr.
  */
 export declare function executeWarn(violations: ArchViolation[], ctx: ExecuteRuleContext, options?: CheckOptions): void;
-export {};
 //# sourceMappingURL=execute-rule.d.ts.map

package/dist/execute-rule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute-rule.d.ts","sourceRoot":"","sources":["../src/execute-rule.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAWtD;;;;GAIG;AACH,UAAU,kBAAkB;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,UAAU,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;IAChC,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,GACtB,aAAa,EAAE,CA8GjB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,EACvB,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CAkBN;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,EACvB,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CA8BN"}
+{"version":3,"file":"execute-rule.d.ts","sourceRoot":"","sources":["../src/execute-rule.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,qBAAqB,CAAA;AAEvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AActD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,UAAU,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;IAChC,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,GACtB,aAAa,EAAE,CAmRjB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EACzB,GAAG,EAAE,kBAAkB,EACvB,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CA+BN;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,EACvB,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CA8BN"}