@nielspeter/eess-ts 0.2.1 → 0.5.0

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

@@ -0,0 +1,158 @@
+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;
+    /**
+     * 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.
+     */
+    describe?: () => 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;AAYpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD;;;;GAIG;AACH,UAAU,kBAAkB;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,GACtB,aAAa,EAAE,CAqXjB;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"}