@nielspeter/eess-ts 0.2.0 → 0.4.0

package/dist/core/exclusion-comments.js

@@ -0,0 +1,310 @@
+import path from 'node:path';
+import { Project, SyntaxKind } from 'ts-morph';
+// A directive must BEGIN its comment. The regexes are anchored at `^` and the
+// caller slices each line from its first `//`, so they see the comment and
+// nothing before it — which keeps the documented TRAILING form working
+// (`const a = 1 // <directive>`), where the comment starts mid-line. Anchoring
+// to the start of the LINE instead was the first attempt and broke exactly
+// that; the guard's trailing rows caught it.
+//
+// It used to match anywhere in the line, which made any comment *mentioning*
+// the syntax a live directive. This file's own grammar documentation was one:
+// a line reading "Single-line without reason: <the directive>" declared a
+// real, reason-less exclusion against whatever rule was being evaluated, and
+// this repo's preset fan-out test caught it the moment comments started being
+// read correctly. Every user documenting the feature in a code comment would
+// have hit the same thing.
+//
+// A trailing directive still works — `const a = 1 // <directive>` — because
+// there the comment itself begins with it.
+const SINGLE_LINE_RE = /^\/\/\s*eess-exclude\s+(.+)/;
+// Block start: // eess-exclude-start <rule-id>[, <rule-id>]: <reason>
+const BLOCK_START_RE = /^\/\/\s*eess-exclude-start\s+(.+)/;
+// Block end: // eess-exclude-end
+const BLOCK_END_RE = /^\/\/\s*eess-exclude-end\b/;
+/**
+ * Parse rule IDs and reason from the content after the directive keyword.
+ *
+ * Format: `rule-a, rule-b: reason text`
+ * If no colon is present, all content is treated as rule IDs and reason is empty.
+ */
+function parseRuleIdsAndReason(content) {
+    const colonIndex = content.indexOf(':');
+    if (colonIndex < 0) {
+        // No colon — all content is rule IDs, no reason
+        const ruleIds = content
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+        return { ruleIds, reason: '' };
+    }
+    const idsPart = content.slice(0, colonIndex);
+    const reason = content.slice(colonIndex + 1).trim();
+    const ruleIds = idsPart
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    return { ruleIds, reason };
+}
+/** Handle a block-end directive line. */
+function handleBlockEnd(frames, exclusions, warnings, filePath, lineNum) {
+    const innermost = frames.pop();
+    if (innermost === undefined) {
+        warnings.push({
+            message: `eess-exclude-end without matching start`,
+            file: filePath,
+            line: lineNum,
+            kind: 'malformed',
+        });
+        return;
+    }
+    // Close the innermost frame only. This used to close **every** open block,
+    // which is how a nested region silently ended its parent early (bug 0039):
+    // the inner `-end` closed the outer, and everything after it was unexcluded
+    // while looking excluded in the source.
+    for (const comment of innermost) {
+        comment.endLine = lineNum;
+        exclusions.push(comment);
+    }
+}
+/** Emit undocumented-exclusion warnings for each rule ID when no reason is given. */
+function warnUndocumented(warnings, ruleIds, directive, filePath, lineNum) {
+    for (const ruleId of ruleIds) {
+        warnings.push({
+            message: `Undocumented exclusion at ${filePath}:${String(lineNum)} — ` +
+                `// ${directive} ${ruleId}\n` +
+                `  Fix: Add a reason — // ${directive} ${ruleId}: <why>`,
+            file: filePath,
+            line: lineNum,
+            kind: 'undocumented',
+        });
+    }
+}
+/** Handle a block-start directive line. */
+function handleBlockStart(content, frames, warnings, filePath, lineNum) {
+    const { ruleIds, reason } = parseRuleIdsAndReason(content);
+    if (reason === '') {
+        warnUndocumented(warnings, ruleIds, 'eess-exclude-start', filePath, lineNum);
+    }
+    // Nesting a DIFFERENT rule is legitimate and used to be refused outright —
+    // exempting `arch/no-cycles` across a module and `arch/no-any` across one
+    // function inside it is an ordinary thing to want. The old code warned and
+    // dropped the inner directive, then let the inner `-end` close the outer
+    // block, so both exemptions were wrong: the inner never applied and the outer
+    // stopped early. Frames make both work.
+    //
+    // Re-opening a rule that is ALREADY open is different — it is redundant, and
+    // the likeliest cause is a missing `-end`. Warned, but still pushed: refusing
+    // it is what produced the early-close bug.
+    const alreadyOpen = new Set(frames.flat().map((c) => c.ruleId));
+    for (const ruleId of ruleIds) {
+        if (alreadyOpen.has(ruleId)) {
+            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',
+            });
+        }
+    }
+    frames.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) {
+    // Skip if this was a block start or end (already handled above, but guard)
+    if (content.startsWith('-start') || content.startsWith('-end'))
+        return;
+    const { ruleIds, reason } = parseRuleIdsAndReason(content);
+    if (reason === '') {
+        warnUndocumented(warnings, ruleIds, 'eess-exclude', filePath, lineNum);
+    }
+    for (const ruleId of ruleIds) {
+        exclusions.push({
+            ruleId,
+            reason,
+            file: filePath,
+            line: lineNum,
+            isBlock: false,
+        });
+    }
+}
+/**
+ * Scan a source file for eess-ts exclusion comments.
+ *
+ * Supported formats:
+ *   // eess-exclude <rule-id>: <reason>
+ *   // eess-exclude-start <rule-id>: <reason>
+ *   // eess-exclude-end
+ *   // eess-exclude <rule-a>, <rule-b>: <reason>
+ */
+/**
+ * Every string-like literal, blanked — [ts-archunit bug 0043](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0043-an-exclusion-directive-inside-a-string-literal-suppresses.md).
+ *
+ * The scan below is line-based, and a line-based scan cannot tell a directive
+ * from the same characters inside a string. Measured before this existed: all
+ * three of `"…"`, `'…'` and `` `…` `` containing the directive text produced a
+ * **live exclusion** that silenced a real finding — silently, because a
+ * directive carrying a reason never triggers the undocumented-exclusion warning.
+ *
+ * **Newlines are preserved**, and that is the load-bearing part: the scan below
+ * is line-based and reports `line` on every exclusion, so a mask that dropped a
+ * newline would misreport every directive after it.
+ *
+ * Characters are replaced with spaces rather than removed, which keeps
+ * intra-line offsets stable too — but nothing downstream consumes a column, so
+ * that half is defence in depth rather than a guarded property. Measured:
+ * collapsing the blanks to `''`, and masking one character short, both leave the
+ * suite green. Recorded rather than dressed up — a sabotage row that survives
+ * for a real reason is a different thing from a missing guard.
+ *
+ * ## Why a parse, and not a scan
+ *
+ * The first attempt used `ts.createScanner`, which is the real lexer and fixed
+ * the three plain cases. It left two: `` `${x} // …` `` and JSX text. A bare
+ * scanner has no parser context, so it cannot know when to re-scan a template
+ * middle or JSX children, and both were classified as code — meaning the `//`
+ * inside them became a comment. Measured, not predicted.
+ *
+ * So: parse, and blank the literals. Everything remaining is code, where `//`
+ * genuinely does start a comment.
+ *
+ * A **ts-morph** project rather than the raw compiler API, per
+ * [ADR-002](../../../../adr/002-ts-morph-ast-engine.md), reusing one in-memory project
+ * across calls so the cost is a parse rather than a project construction. The
+ * whole scan is gated on a rule having already produced a violation in the file,
+ * so nothing is parsed for a clean run.
+ *
+ * A `TemplateExpression` is blanked **whole**, including its `${…}`
+ * substitutions. A comment is legal inside a substitution, so this can miss a
+ * real directive there — it errs toward *not* suppressing, which is the safe
+ * direction for a mechanism whose failure mode is a silent green.
+ */
+const LITERAL_KINDS = [
+    SyntaxKind.StringLiteral,
+    SyntaxKind.NoSubstitutionTemplateLiteral,
+    SyntaxKind.TemplateExpression,
+    SyntaxKind.RegularExpressionLiteral,
+    SyntaxKind.JsxText,
+];
+let scratch;
+function withoutLiterals(sourceText, filePath) {
+    scratch ??= new Project({ useInMemoryFileSystem: true });
+    // `.tsx` so JSX parses; a `.ts` parse reads `<div>` as a type assertion and
+    // the JsxText case silently stops being covered.
+    const sourceFile = scratch.createSourceFile(`/scan/${path.basename(filePath)}.tsx`, sourceText, {
+        overwrite: true,
+    });
+    const out = sourceText.split('');
+    for (const kind of LITERAL_KINDS) {
+        for (const node of sourceFile.getDescendantsOfKind(kind)) {
+            for (let i = node.getStart(); i < node.getEnd(); i++) {
+                if (out[i] !== undefined && out[i] !== '\n')
+                    out[i] = ' ';
+            }
+        }
+    }
+    const withoutLiteralText = out.join('');
+    // Block comments too, and this is not tidying — it is the difference between
+    // documenting the feature and invoking it.
+    //
+    // The grammar is `//`-only and always has been (a `/* … */` directive produced
+    // no exclusion before this fix and still produces none). But a JSDoc block
+    // that *mentions* the directive in prose puts the characters on a line, and
+    // the line scan below cannot tell prose from a directive.
+    //
+    // Found the hard way: this very file's docstring explains the bug, contains
+    // the directive text, and the moment comments started being read correctly it
+    // declared a live exclusion against `preset/boundaries/no-cross-boundary` —
+    // caught by this repo's own preset fan-out test. Any user writing a code
+    // comment about the feature would hit the same thing.
+    //
+    // Safe to do with a regex here, and only here: every string, template and
+    // regex literal has already been blanked, so a surviving `/*` is a real
+    // block-comment start.
+    return withoutLiteralText.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+}
+export function parseExclusionComments(sourceText, filePath) {
+    // A directive inside a string is not a directive (bug 0043).
+    const lines = withoutLiterals(sourceText, filePath).split('\n');
+    const exclusions = [];
+    const warnings = [];
+    // A STACK of frames, one per `-start` line, each holding that line's rule ids.
+    // One `-end` closes one frame. A single-level block behaves exactly as before;
+    // nesting now works instead of silently mangling both regions.
+    const frames = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const lineNum = i + 1;
+        // Slice from the comment start. Literals are already blanked, so the first
+        // `//` on the line is a real comment opener — and anything before it is
+        // code, which cannot contain a directive.
+        const commentStart = line.indexOf('//');
+        if (commentStart === -1)
+            continue;
+        const comment = line.slice(commentStart);
+        // Check block end first (before start/single so we don't match -start as single)
+        if (BLOCK_END_RE.test(comment)) {
+            handleBlockEnd(frames, exclusions, warnings, filePath, lineNum);
+            continue;
+        }
+        // Check block start
+        const startMatch = BLOCK_START_RE.exec(comment);
+        if (startMatch?.[1]) {
+            handleBlockStart(startMatch[1], frames, warnings, filePath, lineNum);
+            continue;
+        }
+        // Check single-line exclude (must not match block directives)
+        const singleMatch = SINGLE_LINE_RE.exec(comment);
+        if (singleMatch?.[1]) {
+            handleSingleLine(singleMatch[1], exclusions, warnings, filePath, lineNum);
+        }
+    }
+    // Any unclosed frame is an error, and pushes no exclusion — so an unterminated
+    // block fails closed: the violation it meant to cover still fires.
+    for (const comment of frames.flat()) {
+        warnings.push({
+            message: `eess-exclude-start without matching end for rule '${comment.ruleId}'`,
+            file: filePath,
+            line: comment.line,
+            kind: 'malformed',
+        });
+    }
+    return { exclusions, warnings };
+}
+/**
+ * Check if a violation is covered by an exclusion comment.
+ *
+ * For single-line comments: the violation must be in the same file and
+ * on the line immediately after the comment.
+ *
+ * For block comments: the violation must be in the same file and
+ * within the line range (start line, end line) inclusive.
+ */
+/** Check if a single comment covers the given violation. */
+function commentCoversViolation(comment, violationLine) {
+    if (comment.isBlock) {
+        return (comment.endLine !== undefined &&
+            violationLine >= comment.line &&
+            violationLine <= comment.endLine);
+    }
+    return violationLine === comment.line + 1;
+}
+export function isExcludedByComment(violation, comments) {
+    const ruleId = violation.ruleId;
+    if (!ruleId)
+        return false;
+    return comments.some((comment) => comment.ruleId === ruleId &&
+        comment.file === violation.file &&
+        commentCoversViolation(comment, violation.line));
+}
+//# sourceMappingURL=exclusion-comments.js.map

package/dist/core/exclusion-comments.js.map

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

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

@@ -0,0 +1,150 @@
+import type { ArchViolation } from '@nielspeter/eess';
+import type { CheckOptions, OutputFormat } from '@nielspeter/eess';
+import type { RuleMetadata } from '@nielspeter/eess';
+import type { EdgeCoverage } from '@nielspeter/eess';
+/**
+ * Context for executing a rule's terminal methods.
+ * Shared across all builder types (RuleBuilder, SliceRuleBuilder,
+ * SchemaRuleBuilder, ResolverRuleBuilder, PairFinalBuilder, SmellBuilder).
+ */
+interface ExecuteRuleContext {
+    reason?: string;
+    metadata?: RuleMetadata;
+    exclusions?: (string | RegExp)[];
+    silentIndices?: Set<number>;
+}
+/**
+ * Complete each violation's identity, then apply `.excluding()` patterns and
+ * inline exclusion comments.
+ *
+ * Extracted to eliminate terminal-method duplication across builders.
+ *
+ * **Not** baseline or diff filtering, despite what this said for several
+ * releases — those run in `executeCheck` / `executeWarn`, after this returns.
+ *
+ * ## The invariant, for whoever adds the next filter
+ *
+ * **Enrichment runs first, so every filter sees a complete violation.** That is
+ * the whole reason for the ordering, and it is easy to undo by accident because
+ * enrichment looks like output formatting rather than identity. It is not: the
+ * comment filter matches on `ruleId`, and when enrichment ran last that filter
+ * saw `undefined` for every condition that did not stamp the field itself
+ * (bug 0041) — a documented feature that silently did nothing.
+ *
+ * Enrichment is pure, idempotent, and writes a **disjoint field set** from
+ * everything the filters read: it touches `ruleId`, `because`, `suggestion` and
+ * `docs`; `.excluding()` matches on `element`/`file`/`message`, and the
+ * `bypassFilters` refusal path reads a flag enrichment never writes. So
+ * "identity is complete before anything reads it" is a simpler invariant to hold
+ * than "each filter must know which fields exist yet". Add a filter that reads
+ * one of those four fields and it will work; add a mutation of them below a
+ * filter and you have reintroduced 0041.
+ */
+export declare function applyFilters(violations: ArchViolation[], ctx: ExecuteRuleContext): ArchViolation[];
+/**
+ * Write a severity-aware, single-document report for the given format.
+ *
+ * Shared by the CLI runner and the throwing `check` terminal so the three
+ * format branches live in one place:
+ * - `json` ALWAYS emits one valid document (even with zero violations) so
+ *   consumers/agents can parse a clean run.
+ * - `github` partitions by severity so warnings render as `::warning`, not
+ *   `::error`.
+ * - terminal (default) writes the rich format to stderr.
+ *
+ * Terminal/github emit nothing when there are no violations.
+ */
+export declare function writeReport(violations: ArchViolation[], format?: OutputFormat, reason?: string, 
+/** Allowlist rules that tested no edges, for the JSON document (bug 0015). */
+untested?: readonly EdgeCoverage[]): void;
+/**
+ * Run `fn` with report aggregation on, restoring the previous value afterwards.
+ *
+ * **A dynamic extent, not a latch.** This replaced an exported
+ * `setCallerAggregatesReports(on)` that the CLI called once and nothing ever set
+ * back. Aggregation is a property of a RUN, and while `executeCheck` was the only
+ * reader the difference was invisible — the CLI wanted suppression for its whole
+ * life. It stopped being invisible the moment `deliver()` and `checkAll()` read it
+ * too (bug 0203): measured, a preset called directly in a process that had already
+ * run `runCheck` once emitted **6 violation blocks before and 0 after**. It still
+ * threw, so nothing went falsely green — but the report, the `Why:` and the `Fix:`
+ * were gone, with no signal that anything had been swallowed.
+ *
+ * Not an option on `CheckOptions`: a self-executing rule file writes `.check()`
+ * with no arguments and a preset is called by the RULE FILE, not by the CLI, so
+ * there is no per-call site the CLI could set. This is a property of who is
+ * driving the run.
+ *
+ * Restores rather than clears, so nesting cannot switch a still-running outer
+ * aggregation off.
+ */
+export declare function withCallerAggregating<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * How many violations have actually been WRITTEN by either emitter, ever.
+ *
+ * Read as a delta across one rule file's evaluation, this answers the only
+ * question the CLI's "your output was not filtered" notice may assert: *did
+ * anything emit while that module was loading?*
+ *
+ * **This replaced an inverted signal, and the inversion was a measured defect.**
+ * The first version counted the writes `executeCheck` SUPPRESSED and concluded
+ * "then nothing leaked" from the absence of a suppression. That is a double
+ * negative, and a rule file that suppresses one terminal while leaking through
+ * another satisfies it while leaking — measured: a `report: 'warn'` preset plus a
+ * silenced `.check()` in one file leaked 7 violation blocks and the notice stayed
+ * silent. A silence built from a stale signal is worse than the false claim it was
+ * introduced to fix, because the run says nothing at all.
+ *
+ * **Three emitters are counted, not two, and an earlier version of this docblock
+ * got the list wrong.** It said `writeReport` was "used by `executeCheck`,
+ * `executeWarn` and `check-all.ts`" — `executeWarn` does not call it. It writes
+ * through `writeStderr` / `process.stdout.write` directly, with its own
+ * json/github/terminal branching, so it moved neither counter and the leak
+ * detector could not see it. Measured: a live `.warn()` beside a throwing
+ * `.check()` under `--baseline` leaked its advisory findings in silence.
+ *
+ * The three: this module's `writeReport` (`executeCheck`, `check-all.ts`), this
+ * module's `executeWarn` advisory write, and the kernel's `reportViolations`
+ * (`finishPreset`). Missing any one reproduces the blind spot on that path — which
+ * is exactly what happened, twice.
+ *
+ * That every emitter must be counted, and that nothing enforces it, is
+ * [bug 0205](../../../../work/bugs/0205-four-emitters-restate-the-suppression-rule-and-disagree.md).
+ */
+/**
+ * Is a caller aggregating reports for this run?
+ *
+ * Exposed so the two OTHER ts-side emitters can honour the same contract
+ * `executeCheck` does: `presets/shared.ts`'s `deliver()` and `core/check-all.ts`.
+ * Both used to emit unconditionally, so a preset or a `checkAll()` at module scope
+ * printed its findings before the aggregating caller saw them — and the caller then
+ * reported the same violations again off the throw. Bug 0203.
+ */
+export declare function callerAggregates(): boolean;
+export declare function violationsWritten(): number;
+/**
+ * Execute the terminal "check" action: apply options, format, throw on violations.
+ */
+export declare function executeCheck(violations: ArchViolation[], ctx: ExecuteRuleContext, options?: CheckOptions): void;
+/**
+ * Execute the terminal "warn" action: apply options, format, log to stderr.
+ *
+ * Advisory for ordinary violations, which are logged exactly as before and
+ * never throw. **A `bypassFilters` configuration finding throws**, carrying
+ * only those findings.
+ *
+ * `.warn()` says "this rule's violations are advisory". A finding that the
+ * rule enforces nothing is not a violation of the rule — it reports that the
+ * rule cannot fire — and there is nothing advisory about that. Leaving the
+ * hole open would make `.warn()` the documented escape hatch for exactly the
+ * class of finding this release exists to surface, on exactly the
+ * gradual-adoption audience the docs point at it.
+ *
+ * The payload matters as much as the throw: an error carrying 200 warn-level
+ * violations plus one meta-finding would make "these findings are true" false
+ * for 200 of 201 entries. `.violations()` remains the non-throwing
+ * programmatic surface.
+ */
+export declare function executeWarn(violations: ArchViolation[], ctx: ExecuteRuleContext, options?: CheckOptions): void;
+export {};
+//# sourceMappingURL=execute-rule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"execute-rule.d.ts","sourceRoot":"","sources":["../../src/core/execute-rule.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAOrD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAWpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,GACtB,aAAa,EAAE,CAgSjB;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,aAAa,EAAE,EAC3B,MAAM,CAAC,EAAE,YAAY,EACrB,MAAM,CAAC,EAAE,MAAM;AACf,8EAA8E;AAC9E,QAAQ,GAAE,SAAS,YAAY,EAAO,GACrC,IAAI,CAoBN;AAwBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAQ/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,EACvB,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CAqCN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,EACvB,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CA+DN"}