@nielspeter/eess 0.4.0 → 0.5.0

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":"AA0CA,gEAAgE;AAChE,wDAAwD;AACxD,MAAM,cAAc,GAAG,4BAA4B,CAAA;AAEnD,sEAAsE;AACtE,MAAM,cAAc,GAAG,kCAAkC,CAAA;AAEzD,iCAAiC;AACjC,MAAM,YAAY,GAAG,2BAA2B,CAAA;AAEhD,2EAA2E;AAC3E,yEAAyE;AACzE,yDAAyD;AACzD,MAAM,cAAc,GAAG,mCAAmC,CAAA;AAC1D,MAAM,mBAAmB,GAAG,yCAAyC,CAAA;AACrE,MAAM,iBAAiB,GAAG,+BAA+B,CAAA;AAEzD;;;;;GAKG;AACH,SAAS,qBAAqB,CAAC,OAAe;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACvC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,gDAAgD;QAChD,MAAM,OAAO,GAAG,OAAO;aACpB,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;IAChC,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAA;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IACnD,MAAM,OAAO,GAAG,OAAO;SACpB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AAC5B,CAAC;AAED,yCAAyC;AACzC,SAAS,cAAc,CACrB,UAAyC,EACzC,UAA8B,EAC9B,QAA4B,EAC5B,QAAgB,EAChB,OAAe;IAEf,IAAI,UAAU,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CAAC;YACZ,OAAO,EAAE,yCAAyC;YAClD,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,OAAO;SACd,CAAC,CAAA;QACF,OAAM;IACR,CAAC;IAED,KAAK,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,UAAU,EAAE,CAAC;QACrC,OAAO,CAAC,OAAO,GAAG,OAAO,CAAA;QACzB,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAC1B,CAAC;IACD,UAAU,CAAC,KAAK,EAAE,CAAA;AACpB,CAAC;AAED,qFAAqF;AACrF,SAAS,gBAAgB,CACvB,QAA4B,EAC5B,OAAiB,EACjB,SAAiB,EACjB,QAAgB,EAChB,OAAe;IAEf,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,QAAQ,CAAC,IAAI,CAAC;YACZ,OAAO,EACL,6BAA6B,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK;gBAC7D,MAAM,SAAS,IAAI,MAAM,IAAI;gBAC7B,4BAA4B,SAAS,IAAI,MAAM,SAAS;YAC1D,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,OAAO;SACd,CAAC,CAAA;IACJ,CAAC;AACH,CAAC;AAED,2CAA2C;AAC3C,SAAS,gBAAgB,CACvB,OAAe,EACf,UAAyC,EACzC,QAA4B,EAC5B,QAAgB,EAChB,OAAe;IAEf,IAAI,UAAU,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC;YACZ,OAAO,EAAE,wDAAwD;YACjE,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,OAAO;SACd,CAAC,CAAA;QACF,OAAM;IACR,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAA;IAE1D,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAClB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;IAC9E,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE;YACrB,MAAM;YACN,MAAM;YACN,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,IAAI;SACd,CAAC,CAAA;IACJ,CAAC;AACH,CAAC;AAED,8CAA8C;AAC9C,SAAS,gBAAgB,CACvB,OAAe,EACf,UAA8B,EAC9B,QAA4B,EAC5B,QAAgB,EAChB,OAAe;IAEf,2EAA2E;IAC3E,IAAI,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAM;IAEtE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAA;IAE1D,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAClB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;IACxE,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,UAAU,CAAC,IAAI,CAAC;YACd,MAAM;YACN,MAAM;YACN,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,KAAK;SACf,CAAC,CAAA;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAkB,EAAE,QAAgB;IACzE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACpC,MAAM,UAAU,GAAuB,EAAE,CAAA;IACzC,MAAM,QAAQ,GAAuB,EAAE,CAAA;IACvC,MAAM,UAAU,GAAG,IAAI,GAAG,EAA4B,CAAA;IAEtD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QACrB,IAAI,IAAI,KAAK,SAAS;YAAE,SAAQ;QAChC,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,CAAA;QAErB,iFAAiF;QACjF,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5D,cAAc,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;YACnE,SAAQ;QACV,CAAC;QAED,oBAAoB;QACpB,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC9E,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpB,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;YACxE,SAAQ;QACV,CAAC;QAED,8DAA8D;QAC9D,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC1E,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrB,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;QAC3E,CAAC;IACH,CAAC;IAED,iCAAiC;IACjC,KAAK,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,UAAU,EAAE,CAAC;QACrC,QAAQ,CAAC,IAAI,CAAC;YACZ,OAAO,EAAE,qDAAqD,OAAO,CAAC,MAAM,GAAG;YAC/E,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,OAAO,CAAC,IAAI;SACnB,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAA;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,4DAA4D;AAC5D,SAAS,sBAAsB,CAAC,OAAyB,EAAE,aAAqB;IAC9E,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,CACL,OAAO,CAAC,OAAO,KAAK,SAAS;YAC7B,aAAa,IAAI,OAAO,CAAC,IAAI;YAC7B,aAAa,IAAI,OAAO,CAAC,OAAO,CACjC,CAAA;IACH,CAAC;IACD,OAAO,aAAa,KAAK,OAAO,CAAC,IAAI,GAAG,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,SAAwB,EACxB,QAA4B;IAE5B,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAA;IAC/B,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAEzB,OAAO,QAAQ,CAAC,IAAI,CAClB,CAAC,OAAO,EAAE,EAAE,CACV,OAAO,CAAC,MAAM,KAAK,MAAM;QACzB,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,IAAI;QAC/B,sBAAsB,CAAC,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,CAClD,CAAA;AACH,CAAC"}
+{"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"}

package/dist/execute-rule.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { collectResult } from './collect-result.js';
 import { severityFor } from './violation.js';
 import { ArchRuleError } from './errors.js';
 import { formatViolations } from './format.js';
@@ -6,6 +7,7 @@ import { formatViolationsJson } from './format-json.js';
 import { formatViolationsGitHub } from './format-github.js';
 import { reportViolations } from './report.js';
 import { parseExclusionComments, isExcludedByComment } from './exclusion-comments.js';
+import { UNSUPPRESSABLE } from './unsuppressable.js';
 import { writeStderr } from './stderr.js';
 import { activeNotice } from './diff-disclosure.js';
 import { recordCommentSuppression } from './comment-suppression.js';
@@ -94,15 +96,41 @@ export function applyFilters(violations, ctx) {
                 v.docs = ctx.metadata.docs;
         }
     }
-    // Scan source files for inline exclusion comments (when rule has an ID).
-    // Matching is on ruleId, which the block above has just guaranteed is present.
-    if (ctx.metadata?.id && result.length > 0) {
+    // Scan source files for inline exclusion comments.
+    //
+    // **Not gated on `ctx.metadata?.id` any more (bug 0255).** It used to be, and
+    // that made the worst case of an inert directive the quietest: with no
+    // `.rule({ id })` a comment can never match — `isExcludedByComment` returns
+    // false without a `ruleId` — and because the block was skipped, the file was
+    // never even parsed, so nothing could notice. An adopter following the
+    // documented sanction recipe got the same red build and no explanation.
+    //
+    // The cost is bounded the same way it always was: only files that already
+    // produced a violation are read. A rule with no id now pays one parse per
+    // violating file to be able to say why the sanction did nothing.
+    if (result.length > 0) {
         const filePaths = new Set(result.map((v) => v.file));
+        const undocumented = [];
         const allComments = [...filePaths].flatMap((filePath) => {
             try {
                 const sourceText = fs.readFileSync(filePath, 'utf-8');
                 const parseResult = parseExclusionComments(sourceText, filePath);
                 for (const warning of parseResult.warnings) {
+                    // An undocumented exclusion is well-formed and APPLIES, so a stderr
+                    // line would let a waiver nobody justified pass with exit 0. It
+                    // becomes an unsuppressable finding below instead — ADR-009 rule 3's
+                    // corollary, and bug 0039's design, which until ADR-012 only `eess-ts`
+                    // implemented. The malformed shapes decline to create the exclusion at
+                    // all, so the original violation still fires and the build is already
+                    // red; stderr is the right weight for those.
+                    if (warning.kind === 'undocumented' && ctx.metadata?.id !== undefined) {
+                        // The promotion below builds an unsuppressable finding keyed on the
+                        // rule id. Without one there is nothing to key it on — and the
+                        // directive is inert anyway, which the inert report says with a
+                        // remedy the author can act on. So it falls through to stderr.
+                        undocumented.push(warning);
+                        continue;
+                    }
                     writeStderr(`[eess] ${warning.message}`);
                 }
                 return parseResult.exclusions;
@@ -115,16 +143,152 @@ export function applyFilters(violations, ctx) {
                 return [];
             }
         });
-        if (allComments.length > 0) {
-            const ruleId = ctx.metadata.id;
+        const ruleId = ctx.metadata?.id;
+        if (allComments.length > 0 && ruleId !== undefined) {
+            // Which comments actually did something, so the ones that did nothing can
+            // be named. Reuses `isExcludedByComment` one comment at a time rather than
+            // re-deriving the match, so this can never drift from the real rule.
+            const spent = new Set();
             result = result.filter((v) => {
                 if (v.bypassFilters === true)
                     return true;
                 const excluded = isExcludedByComment(v, allComments);
-                if (excluded)
+                if (excluded) {
                     recordCommentSuppression(ruleId, v.file);
+                    for (const c of allComments)
+                        if (isExcludedByComment(v, [c]))
+                            spent.add(c);
+                }
                 return !excluded;
             });
+            // A directive naming THIS rule that suppressed nothing. Same shape and the
+            // same weight as the `.excluding()` "Unused exclusion" line above — that
+            // mechanism has warned about a stale pattern since bug 0044; the comment
+            // form never did, which is bug 0255.
+            //
+            // **The wording is domain-neutral on purpose.** The first version explained
+            // the next-line scope in terms of markdown table rows, because that is the
+            // corpus bug 0255 was filed against. This function is the kernel's, and
+            // `eess-mermaid` and `eess-gherkin` run it unforked — so a stale directive
+            // in a `.mmd` or `.feature` file was told it sat "inside a markdown table".
+            // Review caught it, and caught the tell: the hand-port into `eess-ts`
+            // silently dropped the table clause because it made no sense there, which
+            // is the evidence it never belonged at the shared layer. The table nuance
+            // now lives in `docs/markdown.md`, where the dialect that has tables is
+            // documented.
+            //
+            // Scoped to this rule's id on purpose: a file may carry directives for many
+            // rules, and one naming another rule matched nothing here for a good
+            // reason. Without that scope this would fire once per unrelated directive
+            // per rule.
+            for (const c of allComments) {
+                if (c.ruleId !== ruleId || spent.has(c))
+                    continue;
+                writeStderr(`[eess] Exclusion comment for '${ruleId}' at ${c.file}:${String(c.line)} ` +
+                    `suppressed nothing. It may be stale, or out of reach: a single-line ` +
+                    `directive covers only the NEXT line. eess-exclude-start/-end covers a ` +
+                    `region instead.`);
+            }
+        }
+        else if (allComments.length > 0) {
+            // No rule id, so no comment here can ever match: `isExcludedByComment`
+            // refuses without one.
+            //
+            // **This branch cannot say whose directive it is looking at, and the first
+            // version pretended otherwise.** It named each comment's own rule id and
+            // told the reader to add `.rule({ id: <that id> })` — but from inside one
+            // rule's execution there is no way to know whether that id already belongs
+            // to a different, working rule. Review reproduced the harm: a directive
+            // correctly waiving `other/rule` in a file where an id-less rule also
+            // fired produced advice to claim `other/rule` for the id-less one, which
+            // nothing prevents and which would collide two rules on one id.
+            //
+            // So it states the fact and leaves the id to the author. One line per
+            // file, not per comment, for the same reason its sibling scopes by id: a
+            // file may carry directives for many rules and none of them is evidence
+            // about this one.
+            const byFile = new Map();
+            for (const c of allComments) {
+                const lines = byFile.get(c.file);
+                if (lines)
+                    lines.push(c.line);
+                else
+                    byFile.set(c.file, [c.line]);
+            }
+            // Name the rule by its `.because()` reason when it has one (bug 0258).
+            // An id-less rule has no id to name, so several id-less chains over one
+            // file printed byte-identical lines and a reader could not tell which
+            // chain needed the id. The reason is a discriminator that already exists:
+            // `.because()` works without `.rule({ id })`, and `ctx.reason` is stamped
+            // onto violations a few lines above this. Whitespace is collapsed because
+            // the reason is prose and may wrap, and this report is deliberately one
+            // line per file. A rule with neither id nor reason is genuinely anonymous
+            // and the message stays exactly as it was.
+            // Name the rule, preferring its own sentence over its reason.
+            //
+            // The first version of this used `.because()` alone, on the premise that
+            // no rule description was reachable here. Review measured that false:
+            // every builder implements `describeRule()`, `filterContext()` is a method
+            // on the class that has it, and the kernel already names an id-less rule
+            // this way for its assertion-less finding a couple of hundred lines above.
+            // `.because()` is optional prose — the chains this diagnostic targets
+            // often have neither an id nor a reason — so leaning on it alone was a
+            // weaker floor for the same cost.
+            //
+            // `'unnamed'` is `TerminalBuilder`'s own fallback for a rule with no id;
+            // naming a rule "unnamed" tells the reader nothing, so it counts as absent
+            // and the reason takes over. Whitespace is collapsed either way: both are
+            // prose that may wrap, and this report is one line per file.
+            // Collapse to one line, and escape the delimiter. A `.because()` reason is
+            // arbitrary prose, so one containing a quoted term rendered as
+            // `("ignore the "legacy" path")` — three quotes before the paren, and no
+            // way for a reader to see where the label ends. Escaping keeps the
+            // author's words exact where replacing them would not.
+            const oneLine = (t) => t.replace(/\s+/g, ' ').trim().replace(/"/g, '\\"');
+            const described = ctx.describe?.();
+            const label = described !== undefined && described !== 'unnamed' && described !== ''
+                ? oneLine(described)
+                : ctx.reason === undefined
+                    ? undefined
+                    : oneLine(ctx.reason);
+            const named = label === undefined || label === '' ? '' : ` ("${label}")`;
+            for (const [file, lines] of byFile) {
+                const where = lines.length === 1 ? `line ${String(lines[0])}` : `lines ${lines.join(', ')}`;
+                writeStderr(`[eess] This rule${named} declares no id, so no exclusion comment can apply to it — ` +
+                    `a comment matches a violation by rule id. ${file} has a directive at ${where}. ` +
+                    `If one was meant for this rule, give the rule an id with .rule({ id: '<your-id>' }); ` +
+                    `directives naming other rules are not this rule's to honour.`);
+            }
+        }
+        // The waiver applied; this takes the suppressed finding's place, so the
+        // author is told what to fix rather than shown the violation they waived.
+        //
+        // Unsuppressable, because a suppression mechanism that can suppress the
+        // complaint about itself is not a mechanism.
+        //
+        // `undocumented` is only ever populated when the rule HAS an id (the push
+        // above is guarded on it), so this loop is unreachable without one — the
+        // local re-binding is what tells the compiler that after bug 0255 removed
+        // the outer `ctx.metadata?.id` gate.
+        for (const warning of undocumented) {
+            if (ruleId === undefined)
+                continue;
+            result.push({
+                rule: ruleId,
+                ruleId,
+                element: `${ruleId}@${warning.file}:${String(warning.line)}`,
+                file: warning.file,
+                line: warning.line,
+                message: `This exclusion states no reason, so nothing records why the rule is ` +
+                    `waived here — and it is silently suppressing a real finding.`,
+                suggestion: `Add a reason: // eess-exclude ${ruleId}: <why>. ` +
+                    `A reason is prose and nothing verifies it, so this raises the cost of a ` +
+                    `suppression rather than preventing one — the audience is the reviewer ` +
+                    `reading the diff. If the exemption is not justifiable, delete it and fix ` +
+                    `the finding instead. ${UNSUPPRESSABLE}`,
+                severity: 'error',
+                bypassFilters: true,
+            });
         }
     }
     return result;
@@ -133,6 +297,16 @@ export function applyFilters(violations, ctx) {
  * Execute the terminal "check" action: apply options, format, throw on violations.
  */
 export function executeCheck(violations, ctx, options) {
+    // The evidence survives every filter below. Baseline and `--changed` remove
+    // violations, never units examined: a run that examined 900 files and had its
+    // findings baselined away examined 900 files, and reporting 0 there would be
+    // the denominator lie bug 0174 is about.
+    const evidence = {
+        examined: violations.examined,
+        sourceEmpty: violations.sourceEmpty,
+        declaredEmpty: violations.declaredEmpty,
+        deadGlob: violations.deadGlob,
+    };
     let filtered = applyFilters(violations, ctx);
     if (options?.baseline) {
         filtered = options.baseline.filterNew(filtered);
@@ -146,7 +320,10 @@ export function executeCheck(violations, ctx, options) {
     }
     if (filtered.length > 0) {
         // One emitter for both paths (plan 0070) — text/json/github, then throw.
-        reportViolations(filtered, { format: options?.format, reason: ctx.reason });
+        reportViolations(collectResult(filtered, evidence), {
+            format: options?.format,
+            reason: ctx.reason,
+        });
         throw new ArchRuleError(filtered, ctx.reason);
     }
 }