@shrkcrft/boundaries 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/wiring/scan-wiring-files.js

@@ -1,27 +1,49 @@
-import { matchesAny } from "../scan/glob.js";
+import { normalizeWiringRule, resolveSourceGlobs } from '@shrkcrft/core';
+import { globListSelects } from "../scan/glob.js";
 import { readMatchingFiles } from "../util/walk-files.js";
-import { evaluateWiring, wiringGlobsOf, } from "./evaluate-wiring.js";
+import { unreadMatching } from "../util/read-scope-coverage.js";
+import { globListUnits } from "../util/dead-glob-units.js";
+import { settleGlobLists } from "../util/settle-glob-lists.js";
+import { sourceLivenessRequest } from "../extract/source-liveness-request.js";
+import { loadTsconfigPaths } from "../scan/tsconfig-aliases.js";
+import { evaluateWiring, wiringGlobsOf, wiringSourcesOf, } from "./evaluate-wiring.js";
+import { wiringLabeledSources } from "./wiring-labeled-sources.js";
 /** All file globs a rule references: every side / every hop. */
 function ruleGlobs(rule) {
     return wiringGlobsOf(rule);
 }
 /**
  * Filesystem-backed wiring run: walks the project once, reads only the files a
- * rule references (skipping oversized files), and evaluates every (selected)
- * rule. Pure-engine output; the only IO is the read-only tree walk + reads.
+ * rule references, and evaluates every (selected) rule. A matched file the
+ * reader could not read (over the read cap) is handed to the engine as
+ * unread, so the rule's coverage names it instead of passing over it.
+ * Pure-engine output; the only IO is the read-only tree walk + reads.
  */
 export function runWiring(projectRoot, rules, options = {}) {
-    let selected = rules;
+    // The engine entry normalises idempotently (round 13): a loaded rule comes
+    // back equal, a hand-built `{ pattern, expectEmpty }` entry becomes a glob
+    // plus a marker. A MALFORMED entry stays on the authored rule, which
+    // `evaluateWiring` reports as misconfigured — no glob reader here sees it.
+    const malformed = new Set();
+    let selected = rules.map((r) => {
+        const n = normalizeWiringRule(r);
+        if (n.ok)
+            return n.value;
+        malformed.add(r);
+        return r;
+    });
     if (options.only && options.only.length > 0) {
         const ids = new Set(options.only);
         selected = selected.filter((r) => ids.has(r.id));
     }
     if (options.changedOnly) {
         const changed = options.changedFiles ?? [];
-        selected = selected.filter((r) => {
-            const globs = ruleGlobs(r);
-            return changed.some((c) => matchesAny(c, globs));
-        });
+        // Per SOURCE, never through the flattened union: a negation subtracts from
+        // its own list only, so one side's `!x` cannot hide a changed file another
+        // side reads, and a change touching only excluded files selects nothing.
+        // A malformed rule has no footprint to prove it out of scope: it stays in.
+        selected = selected.filter((r) => malformed.has(r) ||
+            wiringSourcesOf(r).some((s) => changed.some((c) => globListSelects(c, resolveSourceGlobs(s)))));
     }
     if (selected.length === 0) {
         return {
@@ -31,12 +53,31 @@ export function runWiring(projectRoot, rules, options = {}) {
             diagnostics: [],
             skipped: [],
             evaluated: 0,
+            acceptedEmpty: 0,
             verdict: 'pass',
         };
     }
-    // Union of all globs across selected rules → one tree walk, cached reads.
-    const allGlobs = [...new Set(selected.flatMap(ruleGlobs))];
-    const cache = readMatchingFiles(projectRoot, allGlobs, new Set(options.excludeDirs ?? []));
-    const entries = [...cache.entries()].map(([path, content]) => ({ path, content }));
-    return evaluateWiring(selected, (source) => entries.filter((f) => matchesAny(f.path, source.files)));
+    // Union of all globs across selected rules → one POSITIVE tree walk, cached
+    // reads; each source then selects its own files from it (`globListSelects`).
+    const allGlobs = [...new Set(selected.filter((r) => !malformed.has(r)).flatMap(ruleGlobs))];
+    const excludeDirs = options.excludeDirs ?? [];
+    const matched = readMatchingFiles(projectRoot, allGlobs, new Set(excludeDirs));
+    const entries = [...matched.files.entries()].map(([path, content]) => ({ path, content }));
+    const walked = entries.map((f) => f.path);
+    // THE one dead-unit decision (`globListUnits`, the one `gates coverage` and
+    // `policy-lint` read) over this run's positive walk.
+    const unitsOf = (globs) => globListUnits(walked, matched.unread, globs);
+    // The tsconfig paths let an `import-edges` source resolve alias specifiers the
+    // way the compiler does — the same map `check boundaries` resolves with.
+    return evaluateWiring(selected, (source) => entries.filter((f) => globListSelects(f.path, resolveSourceGlobs(source))), { tsconfigPaths: loadTsconfigPaths(projectRoot) }, (source) => unreadMatching(matched.unread, resolveSourceGlobs(source)), 
+    // Which negations emptied a source's list, so its skip reason says so (R12-DOC-2).
+    (source) => {
+        const units = unitsOf(resolveSourceGlobs(source));
+        return units.allExcluded ? units.negations : undefined;
+    }, 
+    // Every source's glob units settled with their `expectEmpty` markers
+    // (round 13) — THE per-source request `gates coverage` builds too
+    // (`sourceLivenessRequest` over the engine's own side labels), so `check
+    // wiring` and `gates coverage` accept, and word, one planned glob alike.
+    (rule) => settleGlobLists(sourceLivenessRequest(projectRoot, wiringLabeledSources(rule), excludeDirs, rule.id, unitsOf)));
 }

package/dist/wiring/sink-imports.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Import analysis for a wiring SINK file.
+ *
+ * `check wiring --fix` appends a token to a registry array. That edit is only
+ * safe when the token actually RESOLVES in the sink file. The common registry
+ * shape imports every member:
+ *
+ * ```ts
+ * import { ALPHA_HANDLER } from './ALPHA_HANDLER';
+ * export const HANDLERS = [ALPHA_HANDLER];
+ * ```
+ *
+ * Appending `NEW_HANDLER` to that array turns the wiring gate GREEN while
+ * leaving the file referencing an unbound symbol — it no longer compiles. A
+ * gate that goes green by breaking the build is the exact inverse of the
+ * point, so the planner has to know what the sink file binds before it writes.
+ *
+ * This is a lexer, not a compiler: it answers "is this name bound in this
+ * file?" and "do the existing members follow one derivable import pattern?" —
+ * both of which are decidable from the text, and neither of which is guessed.
+ */
+/** How a name entered the file's scope. */
+export type SinkBindingKind = 'named-import' | 'default-import' | 'namespace-import' | 'local';
+/** One value binding visible in the sink file. */
+export interface ISinkBinding {
+    /** The name as used in the file (the local name, after any `as` alias). */
+    readonly local: string;
+    readonly kind: SinkBindingKind;
+    /** The exported name, for a named import (differs from `local` when aliased). */
+    readonly imported?: string;
+    /** Module specifier, for an import binding. */
+    readonly specifier?: string;
+}
+/**
+ * Top-level value/type declarations — the names a file binds itself.
+ *
+ * Every whitespace run is single-line (`[ \t]`). The old form opened with
+ * `(?:^|\n)\s*`: from every newline of a long blank block, `\s*` ran across all
+ * the lines below it and backtracked through each — O(lines × run) per block
+ * (`findBlankRunHazards` flags that shape). Modifiers and the declared name sit
+ * on the declaration's own line in real TS, so the matches are the same
+ * (`r75-blank-run-linearity.test.ts` holds old ≡ new over every source file).
+ */
+export declare const LOCAL_DECL: RegExp;
+/**
+ * Every value name bound in the file: imports plus its own top-level
+ * declarations.
+ *
+ * Local declarations count because a registry that declares its members inline
+ * needs no import at all — refusing to fix those would be a false refusal.
+ */
+export declare function collectSinkBindings(content: string): ISinkBinding[];
+/** Whether `name` already resolves in the sink file. */
+export declare function isBoundInSink(content: string, name: string): boolean;
+/** A uniform import pattern the existing members all follow. */
+export interface IImportTemplate {
+    /** The specifier with every occurrence of the member name replaced by `{}`. */
+    readonly specifierTemplate: string;
+    /** Quote character used by the existing imports. */
+    readonly quote: string;
+    /** Whether existing import statements end in a semicolon. */
+    readonly semicolon: boolean;
+    /** How many members the template was derived from. */
+    readonly derivedFrom: number;
+}
+/**
+ * Derive the import pattern the sink's existing members follow, if there is
+ * exactly one.
+ *
+ * Derivation succeeds only when the specifier is a pure FUNCTION OF THE MEMBER
+ * NAME — every member `M` imported as `import { M } from '<something>M<something>'`
+ * with the same surrounding text. A barrel (`from './handlers'`), mixed paths,
+ * or an aliased import make the next specifier unknowable, and the planner must
+ * never invent a path: those return `undefined` so the caller refuses instead.
+ */
+export declare function deriveImportTemplate(content: string, members: readonly string[]): IImportTemplate | undefined;
+/** Render the import statement this template produces for `token`. */
+export declare function renderImport(template: IImportTemplate, token: string): string;
+/** The specifier a template yields for `token`, without the surrounding syntax. */
+export declare function renderSpecifier(template: IImportTemplate, token: string): string;
+/** Where a new import line goes, and the resulting content. */
+export interface IImportInsertion {
+    readonly nextContent: string;
+    /** 1-based line the inserted statement lands on. */
+    readonly line: number;
+}
+/**
+ * Insert an import statement after the LAST existing import.
+ *
+ * Appending to the import block (rather than sorting into it) keeps the edit a
+ * pure insertion: no existing line moves, so the diff shows exactly one added
+ * line and a reviewer can see the whole change at a glance.
+ */
+export declare function insertImportStatement(content: string, statement: string): IImportInsertion | undefined;
+//# sourceMappingURL=sink-imports.d.ts.map

package/dist/wiring/sink-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sink-imports.d.ts","sourceRoot":"","sources":["../../src/wiring/sink-imports.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,2CAA2C;AAC3C,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,OAAO,CAAC;AAE/F,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,QAC0I,CAAC;AAElK;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAsBnE;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,eAAe,GAAG,SAAS,CA6B7B;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,gBAAgB,GAAG,SAAS,CAe9B"}

package/dist/wiring/sink-imports.js

@@ -0,0 +1,124 @@
+import { lineOf } from "../extract/scan-literals.js";
+import { parseImportStatements } from "../extract/parse-imports.js";
+/**
+ * Top-level value/type declarations — the names a file binds itself.
+ *
+ * Every whitespace run is single-line (`[ \t]`). The old form opened with
+ * `(?:^|\n)\s*`: from every newline of a long blank block, `\s*` ran across all
+ * the lines below it and backtracked through each — O(lines × run) per block
+ * (`findBlankRunHazards` flags that shape). Modifiers and the declared name sit
+ * on the declaration's own line in real TS, so the matches are the same
+ * (`r75-blank-run-linearity.test.ts` holds old ≡ new over every source file).
+ */
+export const LOCAL_DECL = /(?:^|\n)[ \t]*(?:export[ \t]+)?(?:declare[ \t]+)?(?:default[ \t]+)?(?:const|let|var|function(?:[ \t]*\*)?|class|enum|interface|type)[ \t]+([A-Za-z_$][\w$]*)/g;
+/**
+ * Every value name bound in the file: imports plus its own top-level
+ * declarations.
+ *
+ * Local declarations count because a registry that declares its members inline
+ * needs no import at all — refusing to fix those would be a false refusal.
+ */
+export function collectSinkBindings(content) {
+    const bindings = [];
+    for (const statement of parseImportStatements(content)) {
+        // A type-only import binds no VALUE, so it can never make an array element
+        // resolve. Counting it would let the planner write a reference that erases
+        // at compile time.
+        if (statement.typeOnly)
+            continue;
+        for (const b of statement.bindings) {
+            bindings.push({
+                local: b.local,
+                kind: `${b.kind}-import`,
+                ...(b.imported !== undefined ? { imported: b.imported } : {}),
+                specifier: statement.specifier,
+            });
+        }
+    }
+    LOCAL_DECL.lastIndex = 0;
+    let m;
+    while ((m = LOCAL_DECL.exec(content)) !== null) {
+        bindings.push({ local: m[1], kind: 'local' });
+    }
+    return bindings;
+}
+/** Whether `name` already resolves in the sink file. */
+export function isBoundInSink(content, name) {
+    return collectSinkBindings(content).some((b) => b.local === name);
+}
+/**
+ * Derive the import pattern the sink's existing members follow, if there is
+ * exactly one.
+ *
+ * Derivation succeeds only when the specifier is a pure FUNCTION OF THE MEMBER
+ * NAME — every member `M` imported as `import { M } from '<something>M<something>'`
+ * with the same surrounding text. A barrel (`from './handlers'`), mixed paths,
+ * or an aliased import make the next specifier unknowable, and the planner must
+ * never invent a path: those return `undefined` so the caller refuses instead.
+ */
+export function deriveImportTemplate(content, members) {
+    const bindings = collectSinkBindings(content);
+    const byLocal = new Map(bindings.map((b) => [b.local, b]));
+    let template;
+    let derivedFrom = 0;
+    for (const member of members) {
+        const binding = byLocal.get(member);
+        if (!binding || binding.kind === 'local')
+            continue;
+        // An alias means the local name is NOT the exported name, so the next
+        // token's exported name cannot be derived from the name we would write.
+        if (binding.kind !== 'named-import' || binding.imported !== binding.local)
+            return undefined;
+        if (!binding.specifier || !binding.specifier.includes(member))
+            return undefined;
+        const candidate = binding.specifier.split(member).join('{}');
+        if (template === undefined)
+            template = candidate;
+        else if (template !== candidate)
+            return undefined;
+        derivedFrom += 1;
+    }
+    if (template === undefined || derivedFrom === 0)
+        return undefined;
+    // Mirror the file's existing punctuation so the inserted line does not fight
+    // the formatter that will run over it next.
+    const raw = parseImportStatements(content).find((st) => st.kind === 'import')?.raw ?? '';
+    return {
+        specifierTemplate: template,
+        quote: raw.includes('"') ? '"' : "'",
+        semicolon: raw.trimEnd().endsWith(';'),
+        derivedFrom,
+    };
+}
+/** Render the import statement this template produces for `token`. */
+export function renderImport(template, token) {
+    const specifier = template.specifierTemplate.split('{}').join(token);
+    return `import { ${token} } from ${template.quote}${specifier}${template.quote}${template.semicolon ? ';' : ''}`;
+}
+/** The specifier a template yields for `token`, without the surrounding syntax. */
+export function renderSpecifier(template, token) {
+    return template.specifierTemplate.split('{}').join(token);
+}
+/**
+ * Insert an import statement after the LAST existing import.
+ *
+ * Appending to the import block (rather than sorting into it) keeps the edit a
+ * pure insertion: no existing line moves, so the diff shows exactly one added
+ * line and a reviewer can see the whole change at a glance.
+ */
+export function insertImportStatement(content, statement) {
+    // Only the STATIC import block is a valid insertion point: landing after a
+    // dynamic `import()` deep in the file would put a top-level import in the
+    // middle of a function body.
+    const statements = parseImportStatements(content).filter((st) => st.kind === 'import');
+    const last = statements[statements.length - 1];
+    if (!last)
+        return undefined;
+    const endOfLast = last.index + last.raw.length;
+    // Land immediately after the statement's own newline so the insertion never
+    // splits a line, whatever trails the specifier.
+    const newline = content.indexOf('\n', endOfLast);
+    const at = newline === -1 ? content.length : newline + 1;
+    const nextContent = content.slice(0, at) + statement + '\n' + content.slice(at);
+    return { nextContent, line: lineOf(nextContent, at) };
+}

package/dist/wiring/trace-literal.d.ts

@@ -1,3 +1,4 @@
+import type { IUnreadFile } from '../util/unread-file.js';
 export declare const TRACE_SCHEMA: "sharkcraft.trace/v1";
 /** Default source globs scanned when `trace` is given no `--glob`. */
 export declare const TRACE_DEFAULT_GLOBS: readonly string[];
@@ -41,6 +42,11 @@ export interface ITraceReport {
     readonly byRole: Readonly<Record<TraceRole, readonly ITraceSite[]>>;
     /** Const names found bound to the literal (`const NAME = 'literal'`), if any. */
     readonly aliases: readonly string[];
+    /**
+     * Matched files the reader did not read (over the read cap, or unreadable),
+     * so a site inside one is missing from `byRole`. Set only when non-empty.
+     */
+    readonly unread?: readonly IUnreadFile[];
 }
 export interface ITraceOptions {
     /** Override the default source globs. */

package/dist/wiring/trace-literal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace-literal.d.ts","sourceRoot":"","sources":["../../src/wiring/trace-literal.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,EAAG,qBAA8B,CAAC;AAE3D,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAShD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,oBAAY,SAAS;IACnB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,SAAS,cAAc;CACxB;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,YAAY,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,UAAU,EAAE,CAAC,CAAC,CAAC;IACpE,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AA6ED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,YAAY,CAuFd"}
+{"version":3,"file":"trace-literal.d.ts","sourceRoot":"","sources":["../../src/wiring/trace-literal.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,eAAO,MAAM,YAAY,EAAG,qBAA8B,CAAC;AAE3D,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAShD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,oBAAY,SAAS;IACnB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,SAAS,cAAc;CACxB;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,YAAY,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,UAAU,EAAE,CAAC,CAAC,CAAC;IACpE,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AA6ED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,YAAY,CA0Fd"}

package/dist/wiring/trace-literal.js

@@ -1,4 +1,4 @@
-import { readMatchingFiles } from "../util/walk-files.js";
+import { readSelectedFiles } from "../util/read-selected-files.js";
 export const TRACE_SCHEMA = 'sharkcraft.trace/v1';
 /** Default source globs scanned when `trace` is given no `--glob`. */
 export const TRACE_DEFAULT_GLOBS = [
@@ -125,7 +125,9 @@ const ALIAS_NAME = /^[A-Z][\w$]*$/;
 export function traceLiteral(projectRoot, literal, options = {}) {
     const globs = options.globs && options.globs.length > 0 ? options.globs : TRACE_DEFAULT_GLOBS;
     const exclude = new Set(options.excludeDirs ?? []);
-    const cache = readMatchingFiles(projectRoot, globs, exclude);
+    // One glob list (the caller's `--glob`s, or the defaults): a `!` excludes.
+    const matched = readSelectedFiles(projectRoot, globs, exclude);
+    const cache = matched.files;
     const sites = [];
     const aliasNames = new Set();
     // Exact quoted-literal match: the closing quote immediately follows, so the
@@ -205,5 +207,6 @@ export function traceLiteral(projectRoot, literal, options = {}) {
             [TraceRole.Reference]: sortSites(byRole[TraceRole.Reference]),
         },
         aliases: [...aliasNames].sort(),
+        ...(matched.unread.length > 0 ? { unread: matched.unread } : {}),
     };
 }

package/dist/wiring/wiring-labeled-sources.d.ts

@@ -0,0 +1,12 @@
+import type { IWiringRule } from '@shrkcrft/core';
+import type { ILabeledSource } from '../extract/i-labeled-source.js';
+/**
+ * THE enumeration of a wiring rule's sources, each named by its side —
+ * `declared`, `registered` (or `registered[i]` when a rule unions several
+ * sinks), `chain[i]`. `gates coverage` / `gates explain` (the CLI's
+ * `gateRuleLabeledSources`) and the wiring engine's liveness settle
+ * (`runWiring`) both read it, so a marker or a dead glob is named by one side
+ * label on every surface.
+ */
+export declare function wiringLabeledSources(rule: IWiringRule): readonly ILabeledSource[];
+//# sourceMappingURL=wiring-labeled-sources.d.ts.map

package/dist/wiring/wiring-labeled-sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiring-labeled-sources.d.ts","sourceRoot":"","sources":["../../src/wiring/wiring-labeled-sources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,cAAc,EAAE,CAWjF"}

package/dist/wiring/wiring-labeled-sources.js

@@ -0,0 +1,20 @@
+/**
+ * THE enumeration of a wiring rule's sources, each named by its side —
+ * `declared`, `registered` (or `registered[i]` when a rule unions several
+ * sinks), `chain[i]`. `gates coverage` / `gates explain` (the CLI's
+ * `gateRuleLabeledSources`) and the wiring engine's liveness settle
+ * (`runWiring`) both read it, so a marker or a dead glob is named by one side
+ * label on every surface.
+ */
+export function wiringLabeledSources(rule) {
+    const registered = Array.isArray(rule.registered)
+        ? rule.registered
+        : rule.registered
+            ? [rule.registered]
+            : [];
+    return [
+        ...(rule.declared ? [{ label: 'declared', source: rule.declared }] : []),
+        ...registered.map((source, i) => ({ label: registered.length > 1 ? `registered[${i}]` : 'registered', source })),
+        ...(rule.chain ?? []).map((source, i) => ({ label: `chain[${i}]`, source })),
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/boundaries",
-  "version": "0.1.0-alpha.29",
+  "version": "0.1.0-alpha.31",
   "description": "SharkCraft boundary rules: detect when a repository violates its own architecture (forbidden imports across folder/package/layer boundaries).",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -43,7 +43,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.29"
+    "@shrkcrft/core": "^0.1.0-alpha.31"
   },
   "publishConfig": {
     "access": "public"