@descent-vtt/spec-guard 0.4.0 → 0.5.0

package/dist/types.d.ts

@@ -76,6 +76,31 @@ export interface SearchOptions {
     /** Absolute file paths to exclude from results (the spec files themselves). */
     excludeFiles: ReadonlySet<string>;
 }
+/**
+ * One line of a debt baseline: a file that is allowed to violate, and by how
+ * much.
+ *
+ * Counts, not line numbers. A line number is invalidated by every edit above
+ * it, which would turn the baseline into a file nobody can keep current; a
+ * per-file count survives refactoring and still catches the two cases that
+ * matter - a new file starting to violate, and an existing one violating more.
+ * What it does not catch is a violation moving within a file it already
+ * covers, and ADR-0009 says so rather than implying otherwise.
+ */
+export interface BaselineEntry {
+    /** Path relative to the root, forward slashes. */
+    path: string;
+    /** How many matches this file is allowed to contribute. */
+    declared: number;
+}
+/** How strictly the baseline has to match reality. */
+export type RatchetMode = 'two-sided' | 'one-way';
+/** A baseline entry that claims more violations than the code has. */
+export interface StaleBaselineEntry {
+    path: string;
+    declared: number;
+    found: number;
+}
 /** Inclusive bounds an actual count must satisfy. */
 export interface Bounds {
     min?: number;
@@ -101,10 +126,18 @@ export interface SearchResult {
     commentMatches: number;
     /** Files whose language has no known comment syntax, so nothing was excluded. */
     unclassifiedFiles: number;
-    /** What was not inspected, and why. Never empty for a reason nobody stated. */
-    scope: ScopeLedger;
     /** Up to `maxSnippets` match locations, in file order. */
     matches: MatchLocation[];
+    /**
+     * How many matches each matching file holds.
+     *
+     * Uncapped, unlike `matches`, because a baseline has to be evaluated against
+     * every file that matched rather than the first few - a ratchet that only saw
+     * the first five violations would let the sixth through.
+     */
+    fileCounts: ReadonlyMap<string, number>;
+    /** What was not inspected, and why. Never empty for a reason nobody stated. */
+    scope: ScopeLedger;
     /** Engine that produced this result. */
     engine: EngineName;
 }
@@ -127,8 +160,29 @@ export interface Assertion {
     search?: SearchOptions;
     /** Present on the import assertions. */
     imports?: ImportQuery;
+    /**
+     * Known violations that do not count. Empty when the directive declared none.
+     *
+     * Always present rather than optional: `baseline ?? []` at the two places
+     * that read it was a branch nothing could reach, because resolution always
+     * fills this in. An unreachable fallback is indistinguishable from a
+     * reachable one when you are reading the code.
+     */
+    baseline: readonly BaselineEntry[];
+    /** Whether a baseline entry that no longer matches fails the run. */
+    ratchet: RatchetMode;
     /** Targets that do not exist on disk. */
     missingTargets: string[];
+    /**
+     * Tolerate a scope containing no files.
+     *
+     * Off by default. An assertion over an empty scope passes without inspecting
+     * anything, which is indistinguishable in a report from an assertion that
+     * inspected a thousand files and found nothing - and one of those two is a
+     * lie. Set by `allow-empty="true"` for the rules where covering nothing yet
+     * is the honest state of the world.
+     */
+    allowEmpty: boolean;
 }
 export interface AssertionResult {
     ok: boolean;
@@ -156,6 +210,26 @@ export interface AssertionResult {
     unclassifiedFiles: number;
     /** What this assertion did not inspect, and why. */
     scope: ScopeLedger;
+    /**
+     * Matches excluded because a baseline entry accounted for them.
+     *
+     * Reported for the same reason `commentMatches` is: this is the other way an
+     * assertion can pass without the code being clean, and a reader is entitled
+     * to know it happened.
+     */
+    baselinedMatches: number;
+    /** Baseline entries that claim more violations than the code has. */
+    staleBaseline: StaleBaselineEntry[];
+    /**
+     * How many matches each matching file holds, in file order.
+     *
+     * The raw material for writing a baseline, which is why it is not capped the
+     * way `matches` is.
+     */
+    fileMatches: Array<{
+        file: string;
+        count: number;
+    }>;
     engine?: EngineName;
     durationMs: number;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;GAKG;AAEH,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAChB,uBAAuB,GACvB,qBAAqB,CAAC;AAE1B,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mEAAmE;IACnE,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C,QAAQ,EAAE,cAAc,CAAC;IACzB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAC;IACf,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,iCAAiC;IACjC,UAAU,EAAE,OAAO,CAAC;IACpB,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB;;;;;;OAMG;IACH,KAAK,EAAE,WAAW,CAAC;IACnB,+EAA+E;IAC/E,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;AAElD,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,MAAM;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB;;;;;;OAMG;IACH,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,+EAA+E;IAC/E,KAAK,EAAE,WAAW,CAAC;IACnB,wCAAwC;IACxC,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,YAAY,CAAC;AAElD,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,cAAc,CAAC;IACzB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,wCAAwC;IACxC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,qEAAqE;IACrE,OAAO,EAAE,WAAW,CAAC;IACrB,yCAAyC;IACzC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;;;OAQG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,cAAc,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,KAAK,EAAE,WAAW,CAAC;IACnB;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC;;;;;OAKG;IACH,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,oEAAoE;IACpE,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descent-vtt/spec-guard",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Executable architecture assertions for Markdown specs & ADRs.",
   "keywords": [
     "adr",