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

package/dist/generated/check-provenance.d.ts

@@ -6,7 +6,11 @@ export type ProvenanceFindingKind =
 /** A file OUTSIDE the glob carries the header — a hand-written file mislabeled. */
  | 'mislabeled'
 /** Advisory: the header does not name how to regenerate the file. */
- | 'no-regen-pointer';
+ | 'no-regen-pointer'
+/** In the tree, owned by no writer and not blessed as hand-maintained. */
+ | 'unclassified'
+/** A `handMaintained` bless whose file no longer exists. */
+ | 'stale-hand-maintained';
 export interface IProvenanceFinding {
     readonly ruleId: string;
     readonly file: string;
@@ -20,6 +24,20 @@ export interface IProvenanceFinding {
  * deterministic — never a whole-tree read of every file type.
  */
 export declare function deriveOutsideGlobs(generatedGlob: readonly string[]): string[];
+/**
+ * Tree-classification results a mixed-tree rule produces alongside its files.
+ *
+ * Passed in rather than recomputed so the classification a caller already did
+ * (see `scanGeneratedFiles`) is the same one reported — two implementations of
+ * "which files does this rule own?" is precisely the drift this plane exists
+ * to catch.
+ */
+export interface IClassificationFindings {
+    /** Files under the tree owned by no writer and not blessed. */
+    readonly unclassified?: readonly string[];
+    /** `handMaintained` patterns currently matching no file. */
+    readonly staleHandMaintained?: readonly string[];
+}
 /**
  * Check the "this file is generated" header contract.
  *
@@ -30,7 +48,7 @@ export declare function deriveOutsideGlobs(generatedGlob: readonly string[]): st
  * `outside` should contain candidate files NOT in `generatedGlob`; pass an empty
  * map when `forbidOutside` is off.
  */
-export declare function checkProvenanceHeaders(rule: IGeneratedArtifactRule, generated: ReadonlyMap<string, string>, outside: ReadonlyMap<string, string>): {
+export declare function checkProvenanceHeaders(rule: IGeneratedArtifactRule, generated: ReadonlyMap<string, string>, outside: ReadonlyMap<string, string>, classification?: IClassificationFindings): {
     findings: readonly IProvenanceFinding[];
     error?: string;
 };

package/dist/generated/check-provenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-provenance.d.ts","sourceRoot":"","sources":["../../src/generated/check-provenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAG7D,0CAA0C;AAC1C,MAAM,MAAM,qBAAqB;AAC/B,qEAAqE;AACnE,gBAAgB;AAClB,mFAAmF;GACjF,YAAY;AACd,qEAAqE;GACnE,kBAAkB,CAAC;AAEvB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAQD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAO7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,sBAAsB,EAC5B,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC;IAAE,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA2D7D"}
+{"version":3,"file":"check-provenance.d.ts","sourceRoot":"","sources":["../../src/generated/check-provenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAG7D,0CAA0C;AAC1C,MAAM,MAAM,qBAAqB;AAC/B,qEAAqE;AACnE,gBAAgB;AAClB,mFAAmF;GACjF,YAAY;AACd,qEAAqE;GACnE,kBAAkB;AACpB,0EAA0E;GACxE,cAAc;AAChB,4DAA4D;GAC1D,uBAAuB,CAAC;AAE5B,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAQD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAO7E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,sBAAsB,EAC5B,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,cAAc,GAAE,uBAA4B,GAC3C;IAAE,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAgF7D"}

package/dist/generated/check-provenance.js

@@ -28,16 +28,35 @@ export function deriveOutsideGlobs(generatedGlob) {
  * `outside` should contain candidate files NOT in `generatedGlob`; pass an empty
  * map when `forbidOutside` is off.
  */
-export function checkProvenanceHeaders(rule, generated, outside) {
+export function checkProvenanceHeaders(rule, generated, outside, classification = {}) {
+    const severity = rule.severity ?? 'error';
+    // Classification findings do not depend on the header contract — a mixed tree
+    // must be fully accounted for whether or not the rule asserts headers, so
+    // these are produced before the early return below.
+    const classFindings = [
+        ...(classification.unclassified ?? []).map((file) => ({
+            ruleId: rule.id,
+            file,
+            kind: 'unclassified',
+            severity,
+            message: 'in the generated tree but owned by no `sources[]` glob and not listed in `handMaintained` — classify it',
+        })),
+        ...(classification.staleHandMaintained ?? []).map((pattern) => ({
+            ruleId: rule.id,
+            file: pattern,
+            kind: 'stale-hand-maintained',
+            severity: 'warning',
+            message: '`handMaintained` entry matches no file — the blessed file was renamed or deleted',
+        })),
+    ];
     const header = rule.provenanceHeader;
     if (!header)
-        return { findings: [] };
+        return { findings: classFindings };
     const { re, error } = safeCompile(header.mustMatch, header.flags);
     if (error || !re)
-        return { findings: [], error: `provenanceHeader ${error}` };
-    const severity = rule.severity ?? 'error';
+        return { findings: classFindings, error: `provenanceHeader ${error}` };
     const within = header.withinLines ?? 10;
-    const findings = [];
+    const findings = [...classFindings];
     const test = (content) => {
         re.lastIndex = 0;
         return re.test(headOf(content, within));

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

@@ -1,17 +1,63 @@
 import type { IGeneratedArtifactRule } from '@shrkcrft/core';
+/** One writer's slice of a mixed generated tree. */
+export interface IGeneratedSourceSlice {
+    /** Label for output — the writer's `id`, or `source[<index>]`. */
+    readonly label: string;
+    /** The regen command that owns this slice. */
+    readonly regen: string;
+    /** Globs selecting the committed files this writer owns. */
+    readonly glob: readonly string[];
+    /** Committed files matching this writer's glob (path → content). */
+    readonly files: ReadonlyMap<string, string>;
+    readonly timeoutMs?: number;
+}
 /** The committed generated files plus the mislabel-candidate set. */
 export interface IGeneratedScan {
     /** Files matching `generatedGlob` (project-relative path → content). */
     readonly generated: ReadonlyMap<string, string>;
+    /**
+     * The subset of {@link generated} that is checkable — i.e. everything except
+     * the hand-maintained blesses. Header and byte checks run over this.
+     */
+    readonly checkable: ReadonlyMap<string, string>;
+    /** Files excluded by `handMaintained` or by the in-file marker, sorted. */
+    readonly handMaintained: readonly string[];
+    /** The subset of {@link handMaintained} that declared itself via the marker. */
+    readonly markedHandMaintained: readonly string[];
+    /**
+     * `handMaintained` patterns that currently match NO file. A bless whose file
+     * was renamed or deleted is a stale exemption: it silently widens nothing
+     * today, but it also documents a file that no longer exists, and the next
+     * file to take that name inherits an exemption nobody reviewed.
+     */
+    readonly staleHandMaintained: readonly string[];
+    /**
+     * Files under `generatedGlob` owned by NO writer and not blessed. Only
+     * populated for multi-writer rules, where the writers partition the tree —
+     * a single-writer rule owns everything its glob matches by definition.
+     */
+    readonly unclassified: readonly string[];
+    /** Per-writer slices for a multi-writer rule; empty for a single-writer one. */
+    readonly slices: readonly IGeneratedSourceSlice[];
     /** 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.
+ * Read + CLASSIFY the committed side of a generated-artifact rule.
+ *
+ * Classification is the part that makes this usable on a real tree. A blanket
+ * "everything under this glob is generated by that one command" holds only in a
+ * demo; a real `generated/` dir mixes several writers' output with files that
+ * are still hand-maintained. Partitioning the tree first means each writer is
+ * compared against its OWN slice (no cross-writer `only-committed` noise), the
+ * hand-written files are exempted from the header contract instead of failing
+ * it, and anything belonging to neither is surfaced as `unclassified` rather
+ * than silently assumed.
+ *
+ * Pure filesystem reads — the regen commands (if any) are 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

@@ -1 +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"}
+{"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;AAM7D,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAClD,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;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,sBAAsB,EAC5B,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,cAAc,CAiGhB"}

package/dist/generated/scan-generated.js

@@ -1,17 +1,92 @@
 import { matchesAny } from "../scan/glob.js";
+import { safeCompile } from "../util/safe-regex.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.
+ * Read + CLASSIFY the committed side of a generated-artifact rule.
+ *
+ * Classification is the part that makes this usable on a real tree. A blanket
+ * "everything under this glob is generated by that one command" holds only in a
+ * demo; a real `generated/` dir mixes several writers' output with files that
+ * are still hand-maintained. Partitioning the tree first means each writer is
+ * compared against its OWN slice (no cross-writer `only-committed` noise), the
+ * hand-written files are exempted from the header contract instead of failing
+ * it, and anything belonging to neither is surfaced as `unclassified` rather
+ * than silently assumed.
+ *
+ * Pure filesystem reads — the regen commands (if any) are 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 blessPatterns = rule.handMaintained ?? [];
+    // The in-file marker is read from the same head window the header contract
+    // uses, so "the top of the file" means one thing for both classifications.
+    const markerWindow = rule.provenanceHeader?.withinLines ?? 10;
+    const marker = rule.handMaintainedMarker
+        ? safeCompile(rule.handMaintainedMarker, rule.handMaintainedMarkerFlags).re
+        : undefined;
+    const carriesMarker = (content) => {
+        if (!marker)
+            return false;
+        marker.lastIndex = 0;
+        return marker.test(content.split('\n').slice(0, Math.max(1, markerWindow)).join('\n'));
+    };
+    const handMaintained = [];
+    const markedHandMaintained = [];
+    const checkable = new Map();
+    for (const [path, content] of generated) {
+        if (blessPatterns.length > 0 && matchesAny(path, blessPatterns)) {
+            handMaintained.push(path);
+            continue;
+        }
+        if (carriesMarker(content)) {
+            handMaintained.push(path);
+            markedHandMaintained.push(path);
+            continue;
+        }
+        checkable.set(path, content);
+    }
+    handMaintained.sort();
+    markedHandMaintained.sort();
+    // A bless is pinned to a NAMED file (the schema forbids a wildcard basename),
+    // so one that matches nothing points at a file that has been renamed away.
+    const staleHandMaintained = blessPatterns
+        .filter((pattern) => ![...generated.keys()].some((p) => matchesAny(p, [pattern])))
+        .sort();
+    const slices = (rule.sources ?? []).map((src, i) => {
+        const files = new Map();
+        for (const [path, content] of checkable) {
+            if (matchesAny(path, src.glob))
+                files.set(path, content);
+        }
+        return {
+            label: src.id ?? `source[${i}]`,
+            regen: src.regen,
+            glob: src.glob,
+            files,
+            ...(src.timeoutMs !== undefined ? { timeoutMs: src.timeoutMs } : {}),
+        };
+    });
+    // Only a multi-writer rule PARTITIONS the tree; a single-writer rule owns
+    // everything its glob matched, so nothing there can be unclassified.
+    const unclassified = slices.length === 0
+        ? []
+        : [...checkable.keys()].filter((p) => !slices.some((s) => matchesAny(p, s.glob))).sort();
     const wantOutside = rule.provenanceHeader?.forbidOutside === true;
     if (!wantOutside) {
-        return { generated, outside: new Map(), outsideGlobs: [] };
+        return {
+            generated,
+            checkable,
+            handMaintained,
+            markedHandMaintained,
+            staleHandMaintained,
+            unclassified,
+            slices,
+            outside: new Map(),
+            outsideGlobs: [],
+        };
     }
     const outsideGlobs = rule.provenanceHeader?.outsideGlob && rule.provenanceHeader.outsideGlob.length > 0
         ? [...rule.provenanceHeader.outsideGlob]
@@ -23,5 +98,15 @@ export function scanGeneratedFiles(projectRoot, rule, excludeDirs = []) {
             continue;
         outside.set(path, content);
     }
-    return { generated, outside, outsideGlobs };
+    return {
+        generated,
+        checkable,
+        handMaintained,
+        markedHandMaintained,
+        staleHandMaintained,
+        unclassified,
+        slices,
+        outside,
+        outsideGlobs,
+    };
 }

package/dist/index.d.ts

@@ -11,11 +11,15 @@ export * from './wiring/explain-wiring.js';
 export * from './wiring/registry-query.js';
 export * from './wiring/registration-graph.js';
 export * from './wiring/trace-literal.js';
+export * from './wiring/plan-wiring-fix.js';
+export * from './wiring/sink-imports.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/parse-imports.js';
+export * from './extract/import-edges.js';
 export * from './extract/code-zones.js';
 export * from './extract/inspect-source.js';
 export * from './baseline/canonicalize.js';

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,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"}
+{"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,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,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

@@ -11,11 +11,15 @@ export * from "./wiring/explain-wiring.js";
 export * from "./wiring/registry-query.js";
 export * from "./wiring/registration-graph.js";
 export * from "./wiring/trace-literal.js";
+export * from "./wiring/plan-wiring-fix.js";
+export * from "./wiring/sink-imports.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/parse-imports.js";
+export * from "./extract/import-edges.js";
 export * from "./extract/code-zones.js";
 export * from "./extract/inspect-source.js";
 export * from "./baseline/canonicalize.js";

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

@@ -1,4 +1,4 @@
-import type { IPolicyRule, PolicySurface } from '@shrkcrft/core';
+import { type IPolicyRule, type PolicySurface } from '@shrkcrft/core';
 export declare const POLICY_LINT_SCHEMA: "sharkcraft.policy-lint/v1";
 /**
  * A chunk of content to scan for one rule. For whole files `baseLine` is 1; for

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,EAAkB,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIjF,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;IAClC,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;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,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,aAAa,GAAG,UAAU,CAAC;CAC1D;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEzE,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,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CACxC;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,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC;;;;;OAKG;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;AA0C/E;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,aAAa,CAyJxG"}
+{"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 { failsWhenEmpty } from '@shrkcrft/core';
 import { lexCodeZones, zoneAt } from "../extract/code-zones.js";
 import { safeCompile } from "../util/safe-regex.js";
 export const POLICY_LINT_SCHEMA = 'sharkcraft.policy-lint/v1';
@@ -152,7 +153,7 @@ export function evaluatePolicy(rules, resolve) {
             continue;
         }
         if (units.length === 0) {
-            const failed = rule.failOnEmpty === true;
+            const failed = failsWhenEmpty(rule);
             skipped.push({
                 ruleId: rule.id,
                 reason: '0 content units matched the rule globs',

package/dist/util/walk-files.d.ts

@@ -7,7 +7,26 @@ export declare const MAX_SCAN_FILE_BYTES = 1000000;
  * `excludeDirs` is a set of project-relative POSIX directory paths to prune
  * entirely (e.g. the SharkCraft asset/config dir).
  */
-export declare function walkMatching(root: string, globs: readonly string[], excludeDirs?: ReadonlySet<string>): string[];
+export declare function walkMatching(root: string, globs: readonly string[], excludeDirs?: ReadonlySet<string>, allowDotDirs?: ReadonlySet<string>): string[];
+/**
+ * Run `fn` with the read memo enabled, then clear it.
+ *
+ * ONLY wrap a scan that performs no writes and spawns no commands for its
+ * duration — within such a window the tree cannot change beneath the memo, so
+ * reuse is exact rather than merely probable.
+ */
+export declare function withFileReadCache<T>(fn: () => T): T;
+/** Drop every memoized read. For tests, and for a caller that has just written. */
+export declare function clearFileReadCache(): void;
+/**
+ * The dot-directory segments a glob set explicitly names.
+ *
+ * `.claude/skills/**` asks for `.claude`; `docs/**` asks for nothing. Deriving
+ * the allowlist from the globs themselves means a rule gets exactly the
+ * directories it named and no others — a blanket "scan dot-dirs" switch would
+ * wander into `.venv` and `.yarn` the moment someone wrote a recursive glob.
+ */
+export declare function dotDirsNamedBy(globs: readonly string[]): Set<string>;
 /** Walk + read every file matching `globs`, skipping oversized/unreadable files. */
-export declare function readMatchingFiles(root: string, globs: readonly string[], excludeDirs?: ReadonlySet<string>): Map<string, string>;
+export declare function readMatchingFiles(root: string, globs: readonly string[], excludeDirs?: ReadonlySet<string>, allowDotDirs?: ReadonlySet<string>): Map<string, string>;
 //# sourceMappingURL=walk-files.d.ts.map

package/dist/util/walk-files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walk-files.d.ts","sourceRoot":"","sources":["../../src/util/walk-files.ts"],"names":[],"mappings":"AAIA,+CAA+C;AAC/C,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,MAAM,CAUxC,CAAC;AAEH,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,UAAY,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,GAC3C,MAAM,EAAE,CA2BV;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,GAC3C,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBrB"}
+{"version":3,"file":"walk-files.d.ts","sourceRoot":"","sources":["../../src/util/walk-files.ts"],"names":[],"mappings":"AAIA,+CAA+C;AAC/C,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,MAAM,CAUxC,CAAC;AAEH,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,UAAY,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,EAC5C,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,GAC5C,MAAM,EAAE,CAgCV;AAuBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CASnD;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAGD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAUpE;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,EAC5C,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,GAC5C,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAgCrB"}

package/dist/util/walk-files.js

@@ -20,7 +20,7 @@ export const MAX_SCAN_FILE_BYTES = 1_000_000;
  * `excludeDirs` is a set of project-relative POSIX directory paths to prune
  * entirely (e.g. the SharkCraft asset/config dir).
  */
-export function walkMatching(root, globs, excludeDirs = new Set()) {
+export function walkMatching(root, globs, excludeDirs = new Set(), allowDotDirs = new Set()) {
     const out = [];
     const visit = (abs) => {
         let entries;
@@ -39,7 +39,13 @@ export function walkMatching(root, globs, excludeDirs = new Set()) {
                 // so neither policy-lint nor wiring scans tooling/vendored sources.
                 // (Dirent.isDirectory() is false for symlinks, so symlinked dirs are
                 // never descended — no loop risk.)
-                if (e.name.startsWith('.') || SKIP_DIRS.has(e.name) || excludeDirs.has(rel))
+                // Dot-directories are vendored tooling by default (`.venv`, `.yarn`,
+                // `.gradle`). But a rule may legitimately target one — an agent skill
+                // file lives in `.claude/skills` — so a caller can name the dot-dirs
+                // its OWN globs ask for. `SKIP_DIRS` stays absolute either way.
+                if (SKIP_DIRS.has(e.name) || excludeDirs.has(rel))
+                    continue;
+                if (e.name.startsWith('.') && !allowDotDirs.has(e.name))
                     continue;
                 visit(childAbs);
             }
@@ -52,10 +58,83 @@ export function walkMatching(root, globs, excludeDirs = new Set()) {
     visit(root);
     return out;
 }
+/**
+ * Memo of `readMatchingFiles`, keyed by (root, glob set, excludes).
+ *
+ * One coverage run resolves the SAME globs many times over: every rule on every
+ * plane walks the tree for its own sources, and a shared `$use` extractor is by
+ * construction read once per consumer. The walk + read is roughly half the cost
+ * of a wide extraction, so memoizing turns N walks into one.
+ *
+ * It is OFF by default and enabled only by {@link withFileReadCache}, around a
+ * scan that provably neither spawns nor writes. That restriction is not
+ * caution for its own sake — a global memo really does hand back a stale
+ * snapshot when the same process writes a file between two scans, and a trust
+ * tool answering "nothing drifted" from a stale read is worse than a slow one.
+ * Making the safe window explicit means the condition cannot be forgotten at a
+ * call site.
+ */
+const READ_MEMO = new Map();
+/** True only inside {@link withFileReadCache}. */
+let memoEnabled = false;
+/**
+ * Run `fn` with the read memo enabled, then clear it.
+ *
+ * ONLY wrap a scan that performs no writes and spawns no commands for its
+ * duration — within such a window the tree cannot change beneath the memo, so
+ * reuse is exact rather than merely probable.
+ */
+export function withFileReadCache(fn) {
+    const previous = memoEnabled;
+    memoEnabled = true;
+    try {
+        return fn();
+    }
+    finally {
+        memoEnabled = previous;
+        if (!previous)
+            READ_MEMO.clear();
+    }
+}
+/** Drop every memoized read. For tests, and for a caller that has just written. */
+export function clearFileReadCache() {
+    READ_MEMO.clear();
+}
+/**
+ * The dot-directory segments a glob set explicitly names.
+ *
+ * `.claude/skills/**` asks for `.claude`; `docs/**` asks for nothing. Deriving
+ * the allowlist from the globs themselves means a rule gets exactly the
+ * directories it named and no others — a blanket "scan dot-dirs" switch would
+ * wander into `.venv` and `.yarn` the moment someone wrote a recursive glob.
+ */
+export function dotDirsNamedBy(globs) {
+    const out = new Set();
+    for (const glob of globs) {
+        for (const segment of glob.split('/')) {
+            if (segment.startsWith('.') && segment.length > 1 && !segment.includes('*') && !segment.includes('?')) {
+                out.add(segment);
+            }
+        }
+    }
+    return out;
+}
 /** Walk + read every file matching `globs`, skipping oversized/unreadable files. */
-export function readMatchingFiles(root, globs, excludeDirs = new Set()) {
+export function readMatchingFiles(root, globs, excludeDirs = new Set(), allowDotDirs = new Set()) {
+    const key = memoEnabled
+        ? `${root}\u0000${[...globs].sort().join('\u0001')}\u0000${[...excludeDirs].sort().join('\u0001')}` +
+            `\u0000${[...allowDotDirs].sort().join('\u0001')}`
+        : undefined;
+    if (key !== undefined) {
+        const hit = READ_MEMO.get(key);
+        // Hand back a COPY: callers routinely mutate the map they get (the wiring
+        // scan filters it, the generated scan partitions it), and a shared instance
+        // would let one rule's bookkeeping corrupt the next rule's inputs.
+        if (hit)
+            return new Map(hit);
+    }
     const out = new Map();
-    for (const rel of walkMatching(root, globs, excludeDirs)) {
+    for (const rel of walkMatching(root, globs, excludeDirs, allowDotDirs)) {
         const abs = nodePath.join(root, rel);
         let size = -1;
         try {
@@ -76,5 +155,7 @@ export function readMatchingFiles(root, globs, excludeDirs = new Set()) {
             // unreadable — skip
         }
     }
+    if (key !== undefined)
+        READ_MEMO.set(key, new Map(out));
     return out;
 }

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

@@ -1,5 +1,5 @@
 import { type IWiringRule, type IWiringSource } from '@shrkcrft/core';
-import { type IExtractFileEntry, type IExtractedSite } from '../extract/extract-tokens.js';
+import { type IExtractContext, type IExtractFileEntry, type IExtractedSite } from '../extract/extract-tokens.js';
 export declare const WIRING_SCHEMA: "sharkcraft.wiring/v1";
 /** A file made available to the engine. */
 export type IWiringFileEntry = IExtractFileEntry;
@@ -68,6 +68,13 @@ export interface IWiringRuleResult {
      * silently reported as N unrelated violations.
      */
     readonly emptySink?: boolean;
+    /**
+     * A diagnosis for a side that extracted nothing for a knowable reason — e.g.
+     * an `import-edges` sink targeting `to.files` against barrel imports. Carried
+     * so the empty-sink message can explain itself instead of sending the reader
+     * to check a glob that is fine.
+     */
+    readonly sinkHint?: string;
     /** Per-hop breakdown for a `chain` rule. */
     readonly hops?: readonly IWiringHopResult[];
 }
@@ -107,7 +114,7 @@ export declare function wiringGlobsOf(rule: IWiringRule): string[];
  * extractor-backed baseline compute, so all three honour identical semantics. A
  * misconfigured source returns an `error` and no sites (never throws).
  */
-export declare function collectSourceSites(source: IWiringSource, files: readonly IWiringFileEntry[]): {
+export declare function collectSourceSites(source: IWiringSource, files: readonly IWiringFileEntry[], context?: IExtractContext): {
     sites: readonly IWiringTokenSite[];
     error?: string;
 };
@@ -128,5 +135,5 @@ export declare function validateWiringRule(rule: IWiringRule): string | undefine
  * The `resolve` callback supplies the files for a given rule-side (injected so
  * the engine stays pure / testable — see `runWiring` for the fs-backed wiring).
  */
-export declare function evaluateWiring(rules: readonly IWiringRule[], resolve: WiringFileResolver): IWiringReport;
+export declare function evaluateWiring(rules: readonly IWiringRule[], resolve: WiringFileResolver, context?: IExtractContext): IWiringReport;
 //# sourceMappingURL=evaluate-wiring.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"evaluate-wiring.d.ts","sourceRoot":"","sources":["../../src/wiring/evaluate-wiring.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"evaluate-wiring.d.ts","sourceRoot":"","sources":["../../src/wiring/evaluate-wiring.ts"],"names":[],"mappings":"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"}

package/dist/wiring/evaluate-wiring.js

@@ -1,4 +1,4 @@
-import { validateWiringSource, } from '@shrkcrft/core';
+import { failsWhenEmpty, validateWiringSource, } from '@shrkcrft/core';
 import { extractTokens, } from "../extract/extract-tokens.js";
 export const WIRING_SCHEMA = 'sharkcraft.wiring/v1';
 /** Normalize the `registered` field (single source or union array) to an array. */
@@ -54,8 +54,8 @@ function hopPairs(rule) {
  * extractor-backed baseline compute, so all three honour identical semantics. A
  * misconfigured source returns an `error` and no sites (never throws).
  */
-export function collectSourceSites(source, files) {
-    const res = extractTokens(source, files);
+export function collectSourceSites(source, files, context = {}) {
+    const res = extractTokens(source, files, context);
     return res.error ? { sites: [], error: res.error } : { sites: res.sites };
 }
 /** Group key for a token site under `groupBy` (dir = dirname; package = first two segments). */
@@ -133,7 +133,7 @@ export function validateWiringRule(rule) {
  * The `resolve` callback supplies the files for a given rule-side (injected so
  * the engine stays pure / testable — see `runWiring` for the fs-backed wiring).
  */
-export function evaluateWiring(rules, resolve) {
+export function evaluateWiring(rules, resolve, context = {}) {
     const ruleResults = [];
     const all = [];
     const diagnostics = [];
@@ -179,9 +179,10 @@ export function evaluateWiring(rules, resolve) {
         let sinkFiles = 0;
         let sinkCount = 0;
         let emptySink = false;
+        let sinkHint;
         for (const [hopIndex, pair] of pairs.entries()) {
             const fromFiles = resolve(pair.from);
-            const fromSites = extractTokens(pair.from, fromFiles).sites;
+            const fromSites = extractTokens(pair.from, fromFiles, context).sites;
             const fromKeys = firstSites(fromSites, groupBy);
             // Each sink kept separate so `intersection` can require membership in ALL.
             const sinkKeySets = [];
@@ -189,7 +190,10 @@ export function evaluateWiring(rules, resolve) {
             for (const sink of pair.to) {
                 const files = resolve(sink);
                 hopSinkFiles += files.length;
-                sinkKeySets.push(firstSites(extractTokens(sink, files).sites, groupBy));
+                const sinkRes = extractTokens(sink, files, context);
+                if (sinkRes.hint && sinkHint === undefined)
+                    sinkHint = sinkRes.hint;
+                sinkKeySets.push(firstSites(sinkRes.sites, groupBy));
             }
             const unionKeys = new Map();
             for (const set of sinkKeySets) {
@@ -277,7 +281,7 @@ export function evaluateWiring(rules, resolve) {
                 ? '0 ids extracted from the source side'
                 : undefined;
         if (skipReason !== undefined) {
-            const failed = rule.failOnEmpty === true;
+            const failed = failsWhenEmpty(rule);
             skipped.push({ ruleId: rule.id, reason: skipReason, failed, severity });
             if (failed) {
                 if (severity === 'error')
@@ -310,6 +314,7 @@ export function evaluateWiring(rules, resolve) {
             registeredFiles: sinkFiles,
             violations,
             ...(emptySink ? { emptySink: true } : {}),
+            ...(emptySink && sinkHint !== undefined ? { sinkHint } : {}),
             ...(pairs.length > 1 ? { hops } : {}),
         });
         all.push(...violations);