@shrkcrft/boundaries 0.1.0-alpha.26 → 0.1.0-alpha.28

package/dist/generated/check-provenance.js

@@ -0,0 +1,89 @@
+import { safeCompile } from "../util/safe-regex.js";
+/** The head of a file, as the header contract sees it. */
+function headOf(content, withinLines) {
+    const lines = content.split('\n');
+    return lines.slice(0, Math.max(1, withinLines)).join('\n');
+}
+/**
+ * Derive the globs to search for MISLABELED files when the rule doesn't name
+ * them: one `**\/*.<ext>` per distinct extension in `generatedGlob`. Bounded and
+ * deterministic — never a whole-tree read of every file type.
+ */
+export function deriveOutsideGlobs(generatedGlob) {
+    const exts = new Set();
+    for (const g of generatedGlob) {
+        const m = /\.([A-Za-z0-9]+)$/.exec(g);
+        if (m)
+            exts.add(m[1]);
+    }
+    return [...exts].sort().map((e) => `**/*.${e}`);
+}
+/**
+ * Check the "this file is generated" header contract.
+ *
+ * Pure: the caller supplies the file contents, so this runs with no regen
+ * command, no temp dir, and no spawn — a header-only rule is fully useful (and
+ * safe to ship from a pack) on its own.
+ *
+ * `outside` should contain candidate files NOT in `generatedGlob`; pass an empty
+ * map when `forbidOutside` is off.
+ */
+export function checkProvenanceHeaders(rule, generated, outside) {
+    const header = rule.provenanceHeader;
+    if (!header)
+        return { findings: [] };
+    const { re, error } = safeCompile(header.mustMatch, header.flags);
+    if (error || !re)
+        return { findings: [], error: `provenanceHeader ${error}` };
+    const severity = rule.severity ?? 'error';
+    const within = header.withinLines ?? 10;
+    const findings = [];
+    const test = (content) => {
+        re.lastIndex = 0;
+        return re.test(headOf(content, within));
+    };
+    for (const file of [...generated.keys()].sort()) {
+        const content = generated.get(file);
+        if (!test(content)) {
+            findings.push({
+                ruleId: rule.id,
+                file,
+                kind: 'missing-header',
+                severity,
+                message: `generated file carries no provenance header matching /${header.mustMatch}/`,
+            });
+            continue;
+        }
+        // Advisory only — a header that names its regen command saves the next
+        // editor a search, but its absence is not a correctness defect.
+        if (header.pointsToRegenCommand && rule.regen) {
+            const head = headOf(content, within);
+            const verb = rule.regen.trim().split(/\s+/)[0] ?? '';
+            if (verb !== '' && !head.includes(verb)) {
+                findings.push({
+                    ruleId: rule.id,
+                    file,
+                    kind: 'no-regen-pointer',
+                    severity: 'warning',
+                    message: `provenance header does not name the regen command (\`${verb} …\`)`,
+                });
+            }
+        }
+    }
+    if (header.forbidOutside) {
+        for (const file of [...outside.keys()].sort()) {
+            if (generated.has(file))
+                continue;
+            if (!test(outside.get(file)))
+                continue;
+            findings.push({
+                ruleId: rule.id,
+                file,
+                kind: 'mislabeled',
+                severity,
+                message: 'hand-written file carries a generated-file header — either move it under the generated glob or drop the header',
+            });
+        }
+    }
+    return { findings };
+}

package/dist/generated/compare-trees.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Compare a committed generated tree against a freshly regenerated one.
+ *
+ * The comparison is deliberately SYMMETRIC. A regen that writes a subset (a
+ * template dropped, an input renamed) leaves stale committed files behind, and
+ * a one-directional check would report that as clean — the same one-way blind
+ * spot that makes hand-rolled drift tests untrustworthy.
+ */
+/** One file that differs between the committed tree and the regenerated one. */
+export interface IGeneratedFileDiff {
+    readonly file: string;
+    /**
+     * `content` — present on both sides, bytes differ (the hand-edit signal).
+     * `only-committed` — regen no longer produces it (stale committed file).
+     * `only-regenerated` — regen produces it but it was never committed.
+     */
+    readonly kind: 'content' | 'only-committed' | 'only-regenerated';
+}
+export interface IGeneratedTreeDiff {
+    readonly differences: readonly IGeneratedFileDiff[];
+    readonly committedCount: number;
+    readonly regeneratedCount: number;
+}
+/** Compare two path→content maps. Pure — the caller does all the IO. */
+export declare function compareGeneratedTrees(committed: ReadonlyMap<string, string>, regenerated: ReadonlyMap<string, string>, compare?: 'bytes' | 'normalized-whitespace'): IGeneratedTreeDiff;
+//# sourceMappingURL=compare-trees.d.ts.map

package/dist/generated/compare-trees.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare-trees.d.ts","sourceRoot":"","sources":["../../src/generated/compare-trees.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;CAClE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAYD,wEAAwE;AACxE,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,OAAO,GAAE,OAAO,GAAG,uBAAiC,GACnD,kBAAkB,CAqBpB"}

package/dist/generated/compare-trees.js

@@ -0,0 +1,41 @@
+/**
+ * Compare a committed generated tree against a freshly regenerated one.
+ *
+ * The comparison is deliberately SYMMETRIC. A regen that writes a subset (a
+ * template dropped, an input renamed) leaves stale committed files behind, and
+ * a one-directional check would report that as clean — the same one-way blind
+ * spot that makes hand-rolled drift tests untrustworthy.
+ */
+/** Normalize line endings + trailing whitespace, and drop a trailing newline. */
+function normalizeWhitespace(text) {
+    return text
+        .replace(/\r\n/g, '\n')
+        .split('\n')
+        .map((l) => l.replace(/[ \t]+$/, ''))
+        .join('\n')
+        .replace(/\n+$/, '');
+}
+/** Compare two path→content maps. Pure — the caller does all the IO. */
+export function compareGeneratedTrees(committed, regenerated, compare = 'bytes') {
+    const norm = (s) => (compare === 'bytes' ? s : normalizeWhitespace(s));
+    const differences = [];
+    for (const file of [...committed.keys()].sort()) {
+        const regen = regenerated.get(file);
+        if (regen === undefined) {
+            differences.push({ file, kind: 'only-committed' });
+            continue;
+        }
+        if (norm(committed.get(file)) !== norm(regen)) {
+            differences.push({ file, kind: 'content' });
+        }
+    }
+    for (const file of [...regenerated.keys()].sort()) {
+        if (!committed.has(file))
+            differences.push({ file, kind: 'only-regenerated' });
+    }
+    return {
+        differences,
+        committedCount: committed.size,
+        regeneratedCount: regenerated.size,
+    };
+}

package/dist/generated/scan-generated.d.ts

@@ -0,0 +1,17 @@
+import type { IGeneratedArtifactRule } from '@shrkcrft/core';
+/** The committed generated files plus the mislabel-candidate set. */
+export interface IGeneratedScan {
+    /** Files matching `generatedGlob` (project-relative path → content). */
+    readonly generated: ReadonlyMap<string, string>;
+    /** Candidates for the `forbidOutside` mislabel check (empty when it is off). */
+    readonly outside: ReadonlyMap<string, string>;
+    /** Globs actually used for the outside scan (derived or configured). */
+    readonly outsideGlobs: readonly string[];
+}
+/**
+ * Read the committed side of a generated-artifact rule. Pure filesystem reads —
+ * the regen command (if any) is orchestrated by the caller, which is also where
+ * the local-config-only trust decision is enforced.
+ */
+export declare function scanGeneratedFiles(projectRoot: string, rule: IGeneratedArtifactRule, excludeDirs?: readonly string[]): IGeneratedScan;
+//# sourceMappingURL=scan-generated.d.ts.map

package/dist/generated/scan-generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-generated.d.ts","sourceRoot":"","sources":["../../src/generated/scan-generated.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAK7D,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,sBAAsB,EAC5B,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,cAAc,CAmBhB"}

package/dist/generated/scan-generated.js

@@ -0,0 +1,27 @@
+import { matchesAny } from "../scan/glob.js";
+import { readMatchingFiles } from "../util/walk-files.js";
+import { deriveOutsideGlobs } from "./check-provenance.js";
+/**
+ * Read the committed side of a generated-artifact rule. Pure filesystem reads —
+ * the regen command (if any) is orchestrated by the caller, which is also where
+ * the local-config-only trust decision is enforced.
+ */
+export function scanGeneratedFiles(projectRoot, rule, excludeDirs = []) {
+    const exclude = new Set(excludeDirs);
+    const generated = readMatchingFiles(projectRoot, rule.generatedGlob, exclude);
+    const wantOutside = rule.provenanceHeader?.forbidOutside === true;
+    if (!wantOutside) {
+        return { generated, outside: new Map(), outsideGlobs: [] };
+    }
+    const outsideGlobs = rule.provenanceHeader?.outsideGlob && rule.provenanceHeader.outsideGlob.length > 0
+        ? [...rule.provenanceHeader.outsideGlob]
+        : deriveOutsideGlobs(rule.generatedGlob);
+    const all = readMatchingFiles(projectRoot, outsideGlobs, exclude);
+    const outside = new Map();
+    for (const [path, content] of all) {
+        if (matchesAny(path, rule.generatedGlob))
+            continue;
+        outside.set(path, content);
+    }
+    return { generated, outside, outsideGlobs };
+}

package/dist/index.d.ts

@@ -14,6 +14,17 @@ export * from './wiring/trace-literal.js';
 export * from './policy/extract-templates.js';
 export * from './policy/evaluate-policy.js';
 export * from './policy/run-policy.js';
+export * from './extract/scan-literals.js';
+export * from './extract/extract-tokens.js';
+export * from './extract/code-zones.js';
+export * from './extract/inspect-source.js';
+export * from './baseline/canonicalize.js';
+export * from './baseline/json-path-keys.js';
+export * from './baseline/diff-baseline.js';
+export * from './baseline/compute-baseline.js';
+export * from './generated/check-provenance.js';
+export * from './generated/compare-trees.js';
+export * from './generated/scan-generated.js';
 export * from './util/safe-regex.js';
 export * from './util/walk-files.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -14,5 +14,16 @@ export * from "./wiring/trace-literal.js";
 export * from "./policy/extract-templates.js";
 export * from "./policy/evaluate-policy.js";
 export * from "./policy/run-policy.js";
+export * from "./extract/scan-literals.js";
+export * from "./extract/extract-tokens.js";
+export * from "./extract/code-zones.js";
+export * from "./extract/inspect-source.js";
+export * from "./baseline/canonicalize.js";
+export * from "./baseline/json-path-keys.js";
+export * from "./baseline/diff-baseline.js";
+export * from "./baseline/compute-baseline.js";
+export * from "./generated/check-provenance.js";
+export * from "./generated/compare-trees.js";
+export * from "./generated/scan-generated.js";
 export * from "./util/safe-regex.js";
 export * from "./util/walk-files.js";

package/dist/policy/evaluate-policy.d.ts

@@ -11,6 +11,8 @@ export interface IPolicyUnit {
     readonly baseLine: number;
     /** Marks an inline-template unit (for clearer reporting). */
     readonly inlineTemplate?: boolean;
+    /** True when the file matched one of the rule's `exemptFiles` globs. */
+    readonly exemptFile?: boolean;
 }
 export interface IPolicyFinding {
     readonly ruleId: string;
@@ -24,24 +26,55 @@ export interface IPolicyFinding {
     readonly severity: 'error' | 'warning';
     readonly inlineTemplate?: boolean;
 }
+/** A hit that WAS matched but dropped by an exemption — kept so it can be shown. */
+export interface IPolicySuppression {
+    readonly ruleId: string;
+    readonly file: string;
+    readonly line: number;
+    readonly match: string;
+    /** Which exemption applied. */
+    readonly via: 'exemptFiles' | 'exemptLines' | 'scanZone';
+}
+/**
+ * Per-rule outcome. `skipped` is DISTINCT from `passed`: a rule that scanned no
+ * units checked nothing, and calling that a pass is exactly how a stale glob
+ * ships a real violation.
+ */
+export type PolicyRuleStatus = 'passed' | 'failed' | 'skipped' | 'error';
 export interface IPolicyRuleResult {
     readonly ruleId: string;
     readonly surface: PolicySurface;
     readonly severity: 'error' | 'warning';
+    readonly status: PolicyRuleStatus;
     readonly findingCount: number;
+    /** Hits dropped by an exemption (still counted, never silent). */
+    readonly suppressedCount: number;
+    /** Content units actually scanned — the stale-glob signal. */
+    readonly unitsScanned: number;
     readonly error?: string;
 }
+/** A rule that scanned nothing, reported loudly instead of as a green pass. */
+export interface IPolicySkip {
+    readonly ruleId: string;
+    readonly reason: string;
+    /** True when the rule set `failOnEmpty` — the skip counts as a failure. */
+    readonly failed: boolean;
+    readonly severity: 'error' | 'warning';
+}
 export interface IPolicyReport {
     readonly schema: typeof POLICY_LINT_SCHEMA;
     readonly rules: readonly IPolicyRuleResult[];
     readonly findings: readonly IPolicyFinding[];
     readonly diagnostics: readonly string[];
+    /** Hits an exemption dropped — surfaced by `policy-lint explain`. */
+    readonly suppressed: readonly IPolicySuppression[];
+    /** Rules that scanned nothing. */
+    readonly skipped: readonly IPolicySkip[];
     /**
      * Count of rules that actually scanned ≥1 unit. A rule whose globs matched 0
      * files (e.g. a `style` rule in a project with no stylesheets) is NOT
-     * evaluated — a silent no-op the gate surfaces as `skipped` rather than a
-     * green pass. Misconfigured rules count as evaluated so their error is not
-     * swallowed by the gate's `evaluated === 0` skip path.
+     * evaluated — a loud skip rather than a green pass. Misconfigured rules count
+     * as evaluated so their error is not swallowed.
      */
     readonly evaluated: number;
     readonly verdict: 'pass' | 'errors' | 'warnings';
@@ -51,8 +84,11 @@ export type PolicyUnitResolver = (rule: IPolicyRule) => readonly IPolicyUnit[];
 /**
  * Pure policy evaluation. Each rule's regex is run over the units the resolver
  * supplies; matches become findings (capture group 1 is the reported token when
- * present). A misconfigured rule (uncompilable regex) degrades to a diagnostic
- * — never throws, so one bad rule cannot crash the check.
+ * present). Exemptions (`exemptFiles` / `exemptLines`) and the lexical `scan`
+ * zone drop hits into {@link IPolicyReport.suppressed} rather than deleting
+ * them, so `explain` can show what was matched AND what was let through. A
+ * misconfigured rule (uncompilable regex) degrades to a diagnostic — never
+ * throws, so one bad rule cannot crash the check.
  */
 export declare function evaluatePolicy(rules: readonly IPolicyRule[], resolve: PolicyUnitResolver): IPolicyReport;
 //# sourceMappingURL=evaluate-policy.d.ts.map

package/dist/policy/evaluate-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate-policy.d.ts","sourceRoot":"","sources":["../../src/policy/evaluate-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGjE,eAAO,MAAM,kBAAkB,EAAG,2BAAoC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;CAClD;AAED,6FAA6F;AAC7F,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,WAAW,KAAK,SAAS,WAAW,EAAE,CAAC;AAgB/E;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,aAAa,CA2ExG"}
+{"version":3,"file":"evaluate-policy.d.ts","sourceRoot":"","sources":["../../src/policy/evaluate-policy.ts"],"names":[],"mappings":"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"}

package/dist/policy/evaluate-policy.js

@@ -1,3 +1,4 @@
+import { lexCodeZones, zoneAt } from "../extract/code-zones.js";
 import { safeCompile } from "../util/safe-regex.js";
 export const POLICY_LINT_SCHEMA = 'sharkcraft.policy-lint/v1';
 function lineWithin(content, index) {
@@ -13,16 +14,44 @@ function truncate(s, max = 120) {
     const oneLine = s.replace(/\s+/g, ' ').trim();
     return oneLine.length > max ? oneLine.slice(0, max - 1) + '…' : oneLine;
 }
+/** Does the marker appear on `line` (1-based, within `lines`) or the one above it? */
+function markerNear(lines, line, marker) {
+    const here = lines[line - 1];
+    if (here !== undefined && here.includes(marker))
+        return true;
+    const above = lines[line - 2];
+    return above !== undefined && above.includes(marker);
+}
+/**
+ * Whether the zone rule keeps a match at `index`. `all` keeps everything; the
+ * narrower zones require the match to START in the named zone. Not applied to
+ * inline-template units (their content is already a string body).
+ */
+function zoneKeeps(zone, unit, zones, index) {
+    if (zone === 'all' || unit.inlineTemplate || zones === undefined)
+        return true;
+    const kind = zoneAt(zones, index);
+    if (zone === 'code')
+        return kind === 'code';
+    if (zone === 'strings')
+        return kind === 'string';
+    return kind === 'comment';
+}
 /**
  * Pure policy evaluation. Each rule's regex is run over the units the resolver
  * supplies; matches become findings (capture group 1 is the reported token when
- * present). A misconfigured rule (uncompilable regex) degrades to a diagnostic
- * — never throws, so one bad rule cannot crash the check.
+ * present). Exemptions (`exemptFiles` / `exemptLines`) and the lexical `scan`
+ * zone drop hits into {@link IPolicyReport.suppressed} rather than deleting
+ * them, so `explain` can show what was matched AND what was let through. A
+ * misconfigured rule (uncompilable regex) degrades to a diagnostic — never
+ * throws, so one bad rule cannot crash the check.
  */
 export function evaluatePolicy(rules, resolve) {
     const ruleResults = [];
     const findings = [];
+    const suppressed = [];
     const diagnostics = [];
+    const skipped = [];
     let evaluated = 0;
     let misconfigError = false;
     let misconfigWarn = false;
@@ -36,18 +65,29 @@ export function evaluatePolicy(rules, resolve) {
                 misconfigError = true;
             else
                 misconfigWarn = true;
-            ruleResults.push({ ruleId: rule.id, surface: rule.surface, severity, findingCount: 0, error: msg });
+            ruleResults.push({
+                ruleId: rule.id,
+                surface: rule.surface,
+                severity,
+                status: 'error',
+                findingCount: 0,
+                suppressedCount: 0,
+                unitsScanned: 0,
+                error: msg,
+            });
             // A misconfigured rule attempted to run — count it as evaluated so its
             // error isn't swallowed by the gate's `evaluated === 0` skip path.
             evaluated += 1;
             continue;
         }
         const units = resolve(rule);
-        if (units.length > 0)
-            evaluated += 1;
+        const zone = rule.scan ?? 'all';
         let count = 0;
+        let suppressedCount = 0;
         let zeroWidth = false;
         for (const unit of units) {
+            const lines = rule.exemptLines ? unit.content.split('\n') : undefined;
+            const zones = zone !== 'all' && !unit.inlineTemplate ? lexCodeZones(unit.content) : undefined;
             re.lastIndex = 0;
             let m;
             while ((m = re.exec(unit.content)) !== null) {
@@ -59,13 +99,30 @@ export function evaluatePolicy(rules, resolve) {
                     continue;
                 }
                 const token = m[1] !== undefined ? m[1] : m[0];
-                const line = unit.baseLine - 1 + lineWithin(unit.content, m.index);
+                const localLine = lineWithin(unit.content, m.index);
+                const line = unit.baseLine - 1 + localLine;
+                const match = truncate(token);
+                if (unit.exemptFile) {
+                    suppressed.push({ ruleId: rule.id, file: unit.path, line, match, via: 'exemptFiles' });
+                    suppressedCount += 1;
+                    continue;
+                }
+                if (!zoneKeeps(zone, unit, zones, m.index)) {
+                    suppressed.push({ ruleId: rule.id, file: unit.path, line, match, via: 'scanZone' });
+                    suppressedCount += 1;
+                    continue;
+                }
+                if (lines && markerNear(lines, localLine, rule.exemptLines)) {
+                    suppressed.push({ ruleId: rule.id, file: unit.path, line, match, via: 'exemptLines' });
+                    suppressedCount += 1;
+                    continue;
+                }
                 findings.push({
                     ruleId: rule.id,
                     surface: rule.surface,
                     file: unit.path,
                     line,
-                    match: truncate(token),
+                    match,
                     message: rule.message,
                     ...(rule.suggest ? { suggest: rule.suggest } : {}),
                     severity,
@@ -81,11 +138,54 @@ export function evaluatePolicy(rules, resolve) {
                 misconfigError = true;
             else
                 misconfigWarn = true;
-            ruleResults.push({ ruleId: rule.id, surface: rule.surface, severity, findingCount: count, error: msg });
+            ruleResults.push({
+                ruleId: rule.id,
+                surface: rule.surface,
+                severity,
+                status: 'error',
+                findingCount: count,
+                suppressedCount,
+                unitsScanned: units.length,
+                error: msg,
+            });
+            evaluated += 1;
+            continue;
         }
-        else {
-            ruleResults.push({ ruleId: rule.id, surface: rule.surface, severity, findingCount: count });
+        if (units.length === 0) {
+            const failed = rule.failOnEmpty === true;
+            skipped.push({
+                ruleId: rule.id,
+                reason: '0 content units matched the rule globs',
+                failed,
+                severity,
+            });
+            if (failed) {
+                if (severity === 'error')
+                    misconfigError = true;
+                else
+                    misconfigWarn = true;
+            }
+            ruleResults.push({
+                ruleId: rule.id,
+                surface: rule.surface,
+                severity,
+                status: failed ? 'failed' : 'skipped',
+                findingCount: 0,
+                suppressedCount: 0,
+                unitsScanned: 0,
+            });
+            continue;
         }
+        evaluated += 1;
+        ruleResults.push({
+            ruleId: rule.id,
+            surface: rule.surface,
+            severity,
+            status: count > 0 ? 'failed' : 'passed',
+            findingCount: count,
+            suppressedCount,
+            unitsScanned: units.length,
+        });
     }
     const hasError = misconfigError || findings.some((f) => f.severity === 'error');
     const hasWarn = misconfigWarn || findings.some((f) => f.severity === 'warning');
@@ -94,6 +194,8 @@ export function evaluatePolicy(rules, resolve) {
         rules: ruleResults,
         findings,
         diagnostics,
+        suppressed,
+        skipped,
         evaluated,
         verdict: hasError ? 'errors' : hasWarn ? 'warnings' : 'pass',
     };

package/dist/policy/run-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-policy.d.ts","sourceRoot":"","sources":["../../src/policy/run-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIjE,OAAO,EAAkB,KAAK,aAAa,EAAoB,MAAM,sBAAsB,CAAC;AAY5F,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CA6Cf"}
+{"version":3,"file":"run-policy.d.ts","sourceRoot":"","sources":["../../src/policy/run-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIjE,OAAO,EAAkB,KAAK,aAAa,EAAoB,MAAM,sBAAsB,CAAC;AAY5F,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CAkEf"}

package/dist/policy/run-policy.js

@@ -35,7 +35,16 @@ export function runPolicyLint(projectRoot, rules, options = {}) {
         selected = selected.filter((r) => changed.some((c) => matchesAny(c, globsFor(r))));
     }
     if (selected.length === 0) {
-        return { schema: 'sharkcraft.policy-lint/v1', rules: [], findings: [], diagnostics: [], evaluated: 0, verdict: 'pass' };
+        return {
+            schema: 'sharkcraft.policy-lint/v1',
+            rules: [],
+            findings: [],
+            diagnostics: [],
+            suppressed: [],
+            skipped: [],
+            evaluated: 0,
+            verdict: 'pass',
+        };
     }
     // Under --changed-only, restrict the SCANNED files to the changed set too (not
     // just rule selection). Per-file regex findings have no cross-file dependency,
@@ -47,21 +56,33 @@ export function runPolicyLint(projectRoot, rules, options = {}) {
     const cache = readMatchingFiles(projectRoot, allGlobs, new Set(options.excludeDirs ?? []));
     return evaluatePolicy(selected, (rule) => {
         const globs = globsFor(rule);
+        // `exemptFiles` never removes the file from the scan — it MARKS it, so the
+        // hits it would have produced are reported as suppressed rather than
+        // vanishing. A silently-dropped exemption is indistinguishable from a stale
+        // glob, which is the failure mode this whole plane exists to prevent.
+        const exempt = rule.exemptFiles && rule.exemptFiles.length > 0 ? rule.exemptFiles : undefined;
         const units = [];
         for (const [path, content] of cache) {
             if (changedSet && !changedSet.has(path))
                 continue;
             if (!matchesAny(path, globs))
                 continue;
+            const exemptFile = exempt !== undefined && matchesAny(path, exempt);
             const ext = nodePath.extname(path).toLowerCase();
             if (rule.surface === 'template' && SOURCE_EXT.has(ext)) {
                 for (const tpl of extractInlineTemplates(content)) {
-                    units.push({ path, content: tpl.body, baseLine: tpl.startLine, inlineTemplate: true });
+                    units.push({
+                        path,
+                        content: tpl.body,
+                        baseLine: tpl.startLine,
+                        inlineTemplate: true,
+                        ...(exemptFile ? { exemptFile: true } : {}),
+                    });
                 }
             }
             else {
                 // .html on the template surface, and all style/ts files: scan whole.
-                units.push({ path, content, baseLine: 1 });
+                units.push({ path, content, baseLine: 1, ...(exemptFile ? { exemptFile: true } : {}) });
             }
         }
         return units;