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

package/dist/wiring/explain-wiring.js

@@ -14,6 +14,22 @@ function sortSites(sites) {
  * committing a rule. The diff/verdict reuse {@link evaluateWiring} so they match
  * the gate exactly (incl. `groupBy` membership). Never throws.
  */
+/**
+ * The extractor a rule's registered side resolved from — only when EVERY sink
+ * shares it. A union of sinks where one is shared and another is inline has no
+ * single answer, and naming just one would be a claim the config does not make.
+ */
+function registeredExtractorRef(rule) {
+    const sinks = Array.isArray(rule.registered)
+        ? rule.registered
+        : rule.registered
+            ? [rule.registered]
+            : [];
+    if (sinks.length === 0)
+        return undefined;
+    const first = sinks[0].$use;
+    return first !== undefined && sinks.every((s) => s.$use === first) ? first : undefined;
+}
 export function explainWiring(projectRoot, rule, options = {}) {
     const sourceSide = wiringSourceSide(rule);
     // For a chain, the reported "registered" side is the LAST hop (the far end).
@@ -63,12 +79,14 @@ export function explainWiring(projectRoot, rule, options = {}) {
             distinctCount: ruleResult?.declaredCount ?? 0,
             filesScanned: declaredFiles.length,
             ...(declaredRes.error ? { error: declaredRes.error } : {}),
+            ...(rule.declared?.$use ? { viaExtractor: rule.declared.$use } : {}),
         },
         registered: {
             sites: sortSites(registeredSites),
             distinctCount: ruleResult?.registeredCount ?? 0,
             filesScanned: registeredFiles.size,
             ...(registeredError ? { error: registeredError } : {}),
+            ...(registeredExtractorRef(rule) ? { viaExtractor: registeredExtractorRef(rule) } : {}),
         },
         declaredNotRegistered: byDirection('declared-missing'),
         registeredNotDeclared: byDirection('registered-missing'),

package/dist/wiring/plan-wiring-fix.d.ts

@@ -12,7 +12,14 @@ export type WiringFixRefusal =
 /** The array literal could not be located in the sink file. */
  | 'array-not-found'
 /** The token is a quoted string in the sink; the declared side is a symbol (or vice versa). */
- | 'token-shape-mismatch';
+ | 'token-shape-mismatch'
+/**
+ * The sink IMPORTS its array members, so appending to the array alone would
+ * leave an unbound reference — a green gate over a file that does not
+ * compile. Raised whenever the needed import cannot be derived with
+ * certainty.
+ */
+ | 'needs-import';
 /** One planned edit: append `token` into the anchor array of `file`. */
 export interface IWiringFixEdit {
     readonly ruleId: string;
@@ -25,6 +32,14 @@ export interface IWiringFixEdit {
     readonly insert: string;
     /** The full new file contents, ready to write. */
     readonly nextContent: string;
+    /**
+     * The import statement added alongside the array append, when the sink
+     * imports its members and the specifier was derivable. Absent when the token
+     * was already bound in the sink file.
+     */
+    readonly importInsert?: string;
+    /** 1-based line the import statement lands on. */
+    readonly importLine?: number;
 }
 /** A violation the planner deliberately did not touch. */
 export interface IWiringFixSkip {

package/dist/wiring/plan-wiring-fix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-wiring-fix.d.ts","sourceRoot":"","sources":["../../src/wiring/plan-wiring-fix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,gBAAgB,CAAC;AAGjE,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGhF,eAAO,MAAM,iBAAiB,EAAG,0BAAmC,CAAC;AAErE,uDAAuD;AACvD,MAAM,MAAM,gBAAgB;AAC1B,mEAAmE;AACjE,gBAAgB;AAClB,iEAAiE;GAC/D,mBAAmB;AACrB,wDAAwD;GACtD,qBAAqB;AACvB,+DAA+D;GAC7D,iBAAiB;AACnB,+FAA+F;GAC7F,sBAAsB,CAAC;AAE3B,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,SAAS,gBAAgB,EAAE,EACvC,KAAK,EAAE,SAAS,cAAc,EAAE,GAC/B,cAAc,CAqHhB"}
+{"version":3,"file":"plan-wiring-fix.d.ts","sourceRoot":"","sources":["../../src/wiring/plan-wiring-fix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,gBAAgB,CAAC;AAIjE,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAWhF,eAAO,MAAM,iBAAiB,EAAG,0BAAmC,CAAC;AAErE,uDAAuD;AACvD,MAAM,MAAM,gBAAgB;AAC1B,mEAAmE;AACjE,gBAAgB;AAClB,iEAAiE;GAC/D,mBAAmB;AACrB,wDAAwD;GACtD,qBAAqB;AACvB,+DAA+D;GAC7D,iBAAiB;AACnB,+FAA+F;GAC7F,sBAAsB;AACxB;;;;;GAKG;GACD,cAAc,CAAC;AAEnB,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAuKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,SAAS,gBAAgB,EAAE,EACvC,KAAK,EAAE,SAAS,cAAc,EAAE,GAC/B,cAAc,CA2KhB"}

package/dist/wiring/plan-wiring-fix.js

@@ -1,6 +1,8 @@
 import { matchesAny } from "../scan/glob.js";
-import { escapeRegex, scanBalanced } from "../extract/scan-literals.js";
+import { elementToken, escapeRegex, scanBalanced } from "../extract/scan-literals.js";
+import { extractTokens } from "../extract/extract-tokens.js";
 import { registeredSources } from "./evaluate-wiring.js";
+import { collectSinkBindings, deriveImportTemplate, insertImportStatement, renderImport, renderSpecifier, } from "./sink-imports.js";
 import { resolveExtractorAnchor, resolveExtractorKind } from '@shrkcrft/core';
 export const WIRING_FIX_SCHEMA = 'sharkcraft.wiring-fix/v1';
 /** Indentation of the line containing `index`. */
@@ -17,6 +19,134 @@ function lineOf(content, index) {
     }
     return line;
 }
+/** Extensions a derived specifier may resolve through, in probe order. */
+const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+/**
+ * Resolve a relative specifier against the sink's directory, POSIX-style.
+ *
+ * Only relative specifiers are resolvable this way. A bare specifier is a
+ * package (or a tsconfig alias) whose target this engine cannot know without a
+ * resolver, so those are reported unresolved and the caller refuses.
+ */
+function resolveRelative(sinkPath, specifier) {
+    if (!specifier.startsWith('.'))
+        return undefined;
+    const dir = sinkPath.includes('/') ? sinkPath.slice(0, sinkPath.lastIndexOf('/')) : '';
+    const parts = [...dir.split('/').filter(Boolean), ...specifier.split('/')];
+    const stack = [];
+    for (const part of parts) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            if (stack.length === 0)
+                return undefined;
+            stack.pop();
+            continue;
+        }
+        stack.push(part);
+    }
+    return stack.join('/');
+}
+/**
+ * Whether a derived specifier really points at the file that DECLARES the
+ * token.
+ *
+ * This is the safety net that makes the derived-import path trustworthy rather
+ * than merely plausible. The template says what the specifier *should* be; this
+ * confirms it names the file the gate found the token in. A template that
+ * happens to fit the existing members but misses for the new one is caught
+ * here instead of being written to disk.
+ */
+function specifierPointsAtDeclaration(sinkPath, specifier, declaringFile) {
+    const base = resolveRelative(sinkPath, specifier);
+    if (base === undefined)
+        return false;
+    if (base === declaringFile)
+        return true;
+    for (const ext of RESOLVE_EXTENSIONS) {
+        if (base + ext === declaringFile)
+            return true;
+        if (`${base}/index${ext}` === declaringFile)
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether `file` exports `token`, per the same extractor the declared side of a
+ * rule most often uses.
+ *
+ * Reuses `extractTokens` rather than a second regex so "what counts as an
+ * export" has exactly one definition — a private answer here that drifted from
+ * the extractor would either block valid fixes or wave through invalid ones.
+ */
+function exportsToken(content, token) {
+    const res = extractTokens({ files: ['*'], extract: 'export-names' }, [{ path: 'x', content }]);
+    return res.sites.some((site) => site.token === token);
+}
+/**
+ * Decide whether appending `token` to the sink needs an import, and whether
+ * that import can be derived.
+ *
+ * The condition is an INCONSISTENCY check, not a resolvability check. An import
+ * is needed exactly when the sink's existing members are import-bound but the
+ * new token would not be — that is the case where the append introduces a
+ * reference the file cannot resolve, and where the gate would go green over a
+ * file that no longer compiles.
+ *
+ * Deliberately NOT "the token must be bound". If the existing members are
+ * themselves unbound (ambient globals, a `/// <reference>`, a fixture), then
+ * whatever makes them resolve applies equally to the new one, and the append is
+ * consistent with the file's own convention. Refusing there would be a false
+ * refusal on a file the edit does not make any worse.
+ */
+function decideImport(sinkPath, sinkContent, members, token, declaringFile, declaringContent) {
+    const bindings = collectSinkBindings(sinkContent);
+    // Already resolvable here — imported, or declared inline in the sink.
+    if (bindings.some((b) => b.local === token))
+        return { kind: 'append-only' };
+    // Only members brought in by an IMPORT establish a binding convention the new
+    // token has to follow. A locally-declared member says nothing about where an
+    // external one would come from.
+    const importedMembers = members.filter((m) => bindings.some((b) => b.local === m && b.kind !== 'local'));
+    // No member arrives by import, so there is no convention the new token is
+    // breaking — the append leaves the file exactly as consistent as it was.
+    if (importedMembers.length === 0)
+        return { kind: 'append-only' };
+    const template = deriveImportTemplate(sinkContent, members);
+    if (!template) {
+        return {
+            kind: 'refuse',
+            detail: `sink ${sinkPath} imports its members, but their import paths are not a function of the member name ` +
+                '(a barrel, mixed paths, or an aliased import) — the specifier for this token cannot be derived',
+        };
+    }
+    if (declaringFile === undefined) {
+        return {
+            kind: 'refuse',
+            detail: `sink ${sinkPath} imports its members and the declaring file of "${token}" is unknown, so the import cannot be verified`,
+        };
+    }
+    // A named import only works if the target actually EXPORTS the token. The
+    // gate may have found it with any extractor (`regex-capture` over `const (\w+)`
+    // matches un-exported locals too), so being declared there does not imply
+    // being exported from there.
+    if (declaringContent !== undefined && !exportsToken(declaringContent, token)) {
+        return {
+            kind: 'refuse',
+            detail: `"${token}" is declared in ${declaringFile} but not exported from it — ` +
+                'a named import would not resolve, so the array append is refused too',
+        };
+    }
+    const specifier = renderSpecifier(template, token);
+    if (!specifierPointsAtDeclaration(sinkPath, specifier, declaringFile)) {
+        return {
+            kind: 'refuse',
+            detail: `sink ${sinkPath} imports its members; the derived specifier "${specifier}" does not resolve to ` +
+                `${declaringFile}, where "${token}" is declared — refusing rather than writing a guess`,
+        };
+    }
+    return { kind: 'derived', template, statement: renderImport(template, token) };
+}
 /**
  * Plan the mechanically-unambiguous fixes for `declared-but-not-registered`
  * violations.
@@ -99,6 +229,25 @@ export function planWiringFix(rule, violations, files) {
         }
         const open = mm.index + mm[0].length - 1;
         const scan = scanBalanced(content, open);
+        // Decide the IMPORT before touching the array. An append that leaves the
+        // token unbound compiles-fails, and a gate that goes green by breaking the
+        // build is worse than one that refuses — so a token we cannot bind is
+        // skipped with the reason, never half-written.
+        const currentMembers = scan.elements
+            .map((el) => elementToken(el.text))
+            .filter((t) => t !== undefined);
+        const decision = quoted
+            ? { kind: 'append-only' } // string members bind nothing
+            : decideImport(target.path, content, currentMembers, v.token, v.file, v.file ? files.find((f) => f.path === v.file)?.content : undefined);
+        if (decision.kind === 'refuse') {
+            skipped.push({
+                ruleId: rule.id,
+                token: v.token,
+                reason: 'needs-import',
+                detail: decision.detail,
+            });
+            continue;
+        }
         insertAt = scan.end;
         const last = scan.elements[scan.elements.length - 1];
         const indent = last ? indentOf(content, last.index) : '  ';
@@ -116,13 +265,37 @@ export function planWiringFix(rule, violations, files) {
             ? `${needsComma ? ',' : ''}\n${indent}${rendered},`
             : `${needsComma ? ', ' : ''}${rendered}`;
         content = content.slice(0, cut) + insert + tail + content.slice(insertAt);
+        const arrayLine = lineOf(content, cut + insert.length);
+        // Add the derived import LAST, so the array line number reported above is
+        // computed before the insertion shifts it — the two edits are reported
+        // against the file the reviewer will actually see.
+        let importInsert;
+        let importLine;
+        if (decision.kind === 'derived') {
+            const inserted = insertImportStatement(content, decision.statement);
+            if (!inserted) {
+                // Unreachable in practice (a template implies an import exists), but a
+                // planner that silently dropped the import would reintroduce the bug.
+                skipped.push({
+                    ruleId: rule.id,
+                    token: v.token,
+                    reason: 'needs-import',
+                    detail: `could not locate an import block in ${target.path} to extend`,
+                });
+                continue;
+            }
+            content = inserted.nextContent;
+            importInsert = decision.statement;
+            importLine = inserted.line;
+        }
         edits.push({
             ruleId: rule.id,
             token: v.token,
             file: target.path,
-            line: lineOf(content, cut + insert.length),
+            line: arrayLine,
             insert: insert.trim(),
             nextContent: content,
+            ...(importInsert !== undefined ? { importInsert, importLine: importLine } : {}),
         });
     }
     return { schema: WIRING_FIX_SCHEMA, edits, skipped };

package/dist/wiring/registration-graph.d.ts

@@ -1,4 +1,4 @@
-import type { IRegistrationIdiom } from '@shrkcrft/core';
+import { type IRegistrationIdiom } from '@shrkcrft/core';
 import { type IWiringFileEntry } from './evaluate-wiring.js';
 export declare const REGISTRATION_GRAPH_SCHEMA: "sharkcraft.registration-graph/v1";
 /** A token role-site: which idiom + file:line it was found at. */

package/dist/wiring/registration-graph.d.ts.map

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

package/dist/wiring/registration-graph.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { statSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { resolveSourceGlobs } from '@shrkcrft/core';
 import { matchesAny } from "../scan/glob.js";
 import { readMatchingFiles, walkMatching } from "../util/walk-files.js";
 import { collectSourceSites } from "./evaluate-wiring.js";
@@ -11,7 +12,11 @@ function sortSites(sites) {
 /** Union (deduped) of every glob any role of any idiom references. */
 function registrationGlobs(idioms) {
     return [
-        ...new Set(idioms.flatMap((i) => [...i.declared.files, ...i.provided.files, ...i.consumed.files])),
+        ...new Set(idioms.flatMap((i) => [
+            ...resolveSourceGlobs(i.declared),
+            ...resolveSourceGlobs(i.provided),
+            ...resolveSourceGlobs(i.consumed),
+        ])),
     ];
 }
 /**
@@ -28,7 +33,7 @@ export function buildRegistrationGraph(projectRoot, idioms, options = {}) {
         path,
         content,
     }));
-    const filesFor = (source) => entries.filter((f) => matchesAny(f.path, source.files));
+    const filesFor = (source) => entries.filter((f) => matchesAny(f.path, resolveSourceGlobs(source)));
     const declared = new Map();
     const provided = new Map();
     const consumed = new Map();
@@ -96,7 +101,7 @@ export function registrationGraphSignature(projectRoot, idioms, options = {}) {
 export function providedTokensFromEntries(idioms, entries) {
     const tokens = new Set();
     for (const idiom of idioms) {
-        const files = entries.filter((f) => matchesAny(f.path, idiom.provided.files));
+        const files = entries.filter((f) => matchesAny(f.path, resolveSourceGlobs(idiom.provided)));
         for (const s of collectSourceSites(idiom.provided, files).sites)
             tokens.add(s.token);
     }

package/dist/wiring/registry-query.d.ts

@@ -1,4 +1,4 @@
-import type { IRegistryDeclaration } from '@shrkcrft/core';
+import { type IRegistryDeclaration } from '@shrkcrft/core';
 export declare const REGISTRY_SCHEMA: "sharkcraft.registry-inventory/v1";
 /** Where an id was found (project-relative path + 1-based line). */
 export interface IRegistrySite {

package/dist/wiring/registry-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry-query.d.ts","sourceRoot":"","sources":["../../src/wiring/registry-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAK3D,eAAO,MAAM,eAAe,EAAG,kCAA2C,CAAC;AAE3E,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACnD;AAED,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,eAAe,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,oBAAyB,GACjC,kBAAkB,CA+CpB;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,SAAS,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAEjF;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,SAAS,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEnG;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,kBAAkB,GAAG,SAAS,cAAc,EAAE,CAE3F"}
+{"version":3,"file":"registry-query.d.ts","sourceRoot":"","sources":["../../src/wiring/registry-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAK/E,eAAO,MAAM,eAAe,EAAG,kCAA2C,CAAC;AAE3E,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACnD;AAED,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,eAAe,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,oBAAyB,GACjC,kBAAkB,CAkDpB;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,SAAS,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAEjF;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,SAAS,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEnG;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,kBAAkB,GAAG,SAAS,cAAc,EAAE,CAE3F"}

package/dist/wiring/registry-query.js

@@ -1,3 +1,4 @@
+import { resolveSourceGlobs } from '@shrkcrft/core';
 import { matchesAny } from "../scan/glob.js";
 import { readMatchingFiles } from "../util/walk-files.js";
 import { collectSourceSites } from "./evaluate-wiring.js";
@@ -12,18 +13,21 @@ function sortSites(sites) {
  */
 export function scanRegistry(projectRoot, decl, options = {}) {
     const globs = [
-        ...new Set([...decl.source.files, ...(decl.consumer ? decl.consumer.files : [])]),
+        ...new Set([
+            ...resolveSourceGlobs(decl.source),
+            ...(decl.consumer ? resolveSourceGlobs(decl.consumer) : []),
+        ]),
     ];
     const cache = readMatchingFiles(projectRoot, globs, new Set(options.excludeDirs ?? []));
     const entries = [...cache.entries()].map(([path, content]) => ({ path, content }));
     const diagnostics = [];
-    const sourceFiles = entries.filter((f) => matchesAny(f.path, decl.source.files));
+    const sourceFiles = entries.filter((f) => matchesAny(f.path, resolveSourceGlobs(decl.source)));
     const declared = collectSourceSites(decl.source, sourceFiles);
     if (declared.error)
         diagnostics.push(`registry "${decl.name}" source: ${declared.error}`);
     const consumerByToken = new Map();
     if (decl.consumer) {
-        const consumerFiles = entries.filter((f) => matchesAny(f.path, decl.consumer.files));
+        const consumerFiles = entries.filter((f) => matchesAny(f.path, resolveSourceGlobs(decl.consumer)));
         const consumed = collectSourceSites(decl.consumer, consumerFiles);
         if (consumed.error)
             diagnostics.push(`registry "${decl.name}" consumer: ${consumed.error}`);

package/dist/wiring/scan-wiring-files.d.ts

@@ -1,4 +1,4 @@
-import type { IWiringRule } from '@shrkcrft/core';
+import { type IWiringRule } from '@shrkcrft/core';
 import { type IWiringReport } from './evaluate-wiring.js';
 export interface IRunWiringOptions {
     /** Only run rules touched by these (project-relative) changed files. */

package/dist/wiring/scan-wiring-files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan-wiring-files.d.ts","sourceRoot":"","sources":["../../src/wiring/scan-wiring-files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAO9B,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CA+Bf"}
+{"version":3,"file":"scan-wiring-files.d.ts","sourceRoot":"","sources":["../../src/wiring/scan-wiring-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAItE,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAO9B,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CAqCf"}

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

@@ -1,5 +1,7 @@
+import { resolveSourceGlobs } from '@shrkcrft/core';
 import { matchesAny } from "../scan/glob.js";
 import { readMatchingFiles } from "../util/walk-files.js";
+import { loadTsconfigPaths } from "../scan/tsconfig-aliases.js";
 import { evaluateWiring, wiringGlobsOf, } from "./evaluate-wiring.js";
 /** All file globs a rule references: every side / every hop. */
 function ruleGlobs(rule) {
@@ -38,5 +40,7 @@ export function runWiring(projectRoot, rules, options = {}) {
     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)));
+    // 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) => matchesAny(f.path, resolveSourceGlobs(source))), { tsconfigPaths: loadTsconfigPaths(projectRoot) });
 }

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

@@ -0,0 +1,84 @@
+/**
+ * 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;
+}
+/**
+ * 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;AAMD;;;;;;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,115 @@
+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. */
+const LOCAL_DECL = /(?:^|\n)\s*(?:export\s+)?(?:declare\s+)?(?:default\s+)?(?:const|let|var|function\s*\*?|class|enum|interface|type)\s+([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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/boundaries",
-  "version": "0.1.0-alpha.29",
+  "version": "0.1.0-alpha.30",
   "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.30"
   },
   "publishConfig": {
     "access": "public"