@shrkcrft/boundaries 0.1.0-alpha.21 → 0.1.0-alpha.22

package/dist/index.d.ts

@@ -5,4 +5,11 @@ export * from './scan/glob.js';
 export * from './scan/scan-imports.js';
 export * from './evaluate/evaluate-boundaries.js';
 export * from './scan/tsconfig-aliases.js';
+export * from './wiring/evaluate-wiring.js';
+export * from './wiring/scan-wiring-files.js';
+export * from './policy/extract-templates.js';
+export * from './policy/evaluate-policy.js';
+export * from './policy/run-policy.js';
+export * from './util/safe-regex.js';
+export * from './util/walk-files.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC"}
+{"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,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -5,3 +5,10 @@ export * from "./scan/glob.js";
 export * from "./scan/scan-imports.js";
 export * from "./evaluate/evaluate-boundaries.js";
 export * from "./scan/tsconfig-aliases.js";
+export * from "./wiring/evaluate-wiring.js";
+export * from "./wiring/scan-wiring-files.js";
+export * from "./policy/extract-templates.js";
+export * from "./policy/evaluate-policy.js";
+export * from "./policy/run-policy.js";
+export * from "./util/safe-regex.js";
+export * from "./util/walk-files.js";

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

@@ -0,0 +1,50 @@
+import type { IPolicyRule, 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
+ * an inline template it is the source line where the template body begins, so
+ * findings map back to the real file line.
+ */
+export interface IPolicyUnit {
+    readonly path: string;
+    readonly content: string;
+    readonly baseLine: number;
+    /** Marks an inline-template unit (for clearer reporting). */
+    readonly inlineTemplate?: boolean;
+}
+export interface IPolicyFinding {
+    readonly ruleId: string;
+    readonly surface: PolicySurface;
+    readonly file: string;
+    readonly line: number;
+    /** The matched token (capture group 1 if present, else the whole match, truncated). */
+    readonly match: string;
+    readonly message: string;
+    readonly suggest?: string;
+    readonly severity: 'error' | 'warning';
+    readonly inlineTemplate?: boolean;
+}
+export interface IPolicyRuleResult {
+    readonly ruleId: string;
+    readonly surface: PolicySurface;
+    readonly severity: 'error' | 'warning';
+    readonly findingCount: number;
+    readonly error?: string;
+}
+export interface IPolicyReport {
+    readonly schema: typeof POLICY_LINT_SCHEMA;
+    readonly rules: readonly IPolicyRuleResult[];
+    readonly findings: readonly IPolicyFinding[];
+    readonly diagnostics: readonly string[];
+    readonly verdict: 'pass' | 'errors' | 'warnings';
+}
+/** Resolves the content units to scan for a given rule (injected for purity/testability). */
+export type PolicyUnitResolver = (rule: IPolicyRule) => readonly IPolicyUnit[];
+/**
+ * Pure policy evaluation. Each rule's regex is run over the units the resolver
+ * supplies; matches become findings (capture group 1 is the reported token when
+ * present). A misconfigured rule (uncompilable regex) degrades to a diagnostic
+ * — never throws, so one bad rule cannot crash the check.
+ */
+export declare function evaluatePolicy(rules: readonly IPolicyRule[], resolve: PolicyUnitResolver): IPolicyReport;
+//# sourceMappingURL=evaluate-policy.d.ts.map

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

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

package/dist/policy/evaluate-policy.js

@@ -0,0 +1,92 @@
+import { safeCompile } from "../util/safe-regex.js";
+export const POLICY_LINT_SCHEMA = 'sharkcraft.policy-lint/v1';
+function lineWithin(content, index) {
+    let line = 1;
+    const end = Math.min(index, content.length);
+    for (let i = 0; i < end; i += 1) {
+        if (content[i] === '\n')
+            line += 1;
+    }
+    return line;
+}
+function truncate(s, max = 120) {
+    const oneLine = s.replace(/\s+/g, ' ').trim();
+    return oneLine.length > max ? oneLine.slice(0, max - 1) + '…' : oneLine;
+}
+/**
+ * Pure policy evaluation. Each rule's regex is run over the units the resolver
+ * supplies; matches become findings (capture group 1 is the reported token when
+ * present). A misconfigured rule (uncompilable regex) degrades to a diagnostic
+ * — never throws, so one bad rule cannot crash the check.
+ */
+export function evaluatePolicy(rules, resolve) {
+    const ruleResults = [];
+    const findings = [];
+    const diagnostics = [];
+    let misconfigError = false;
+    let misconfigWarn = false;
+    for (const rule of rules) {
+        const severity = rule.severity ?? 'error';
+        const { re, error } = safeCompile(rule.pattern, rule.flags);
+        if (error || !re) {
+            const msg = `rule "${rule.id}": ${error}`;
+            diagnostics.push(msg);
+            if (severity === 'error')
+                misconfigError = true;
+            else
+                misconfigWarn = true;
+            ruleResults.push({ ruleId: rule.id, surface: rule.surface, severity, findingCount: 0, error: msg });
+            continue;
+        }
+        let count = 0;
+        let zeroWidth = false;
+        for (const unit of resolve(rule)) {
+            re.lastIndex = 0;
+            let m;
+            while ((m = re.exec(unit.content)) !== null) {
+                if (m[0] === '') {
+                    // A zero-width pattern (`a?`, a lookahead, …) would otherwise emit one
+                    // empty finding per position. Advance and refuse to record; flag it.
+                    zeroWidth = true;
+                    re.lastIndex += 1;
+                    continue;
+                }
+                const token = m[1] !== undefined ? m[1] : m[0];
+                const line = unit.baseLine - 1 + lineWithin(unit.content, m.index);
+                findings.push({
+                    ruleId: rule.id,
+                    surface: rule.surface,
+                    file: unit.path,
+                    line,
+                    match: truncate(token),
+                    message: rule.message,
+                    ...(rule.suggest ? { suggest: rule.suggest } : {}),
+                    severity,
+                    ...(unit.inlineTemplate ? { inlineTemplate: true } : {}),
+                });
+                count += 1;
+            }
+        }
+        if (zeroWidth) {
+            const msg = `rule "${rule.id}": pattern matches the empty string (zero-width) — likely a misconfiguration`;
+            diagnostics.push(msg);
+            if (severity === 'error')
+                misconfigError = true;
+            else
+                misconfigWarn = true;
+            ruleResults.push({ ruleId: rule.id, surface: rule.surface, severity, findingCount: count, error: msg });
+        }
+        else {
+            ruleResults.push({ ruleId: rule.id, surface: rule.surface, severity, findingCount: count });
+        }
+    }
+    const hasError = misconfigError || findings.some((f) => f.severity === 'error');
+    const hasWarn = misconfigWarn || findings.some((f) => f.severity === 'warning');
+    return {
+        schema: POLICY_LINT_SCHEMA,
+        rules: ruleResults,
+        findings,
+        diagnostics,
+        verdict: hasError ? 'errors' : hasWarn ? 'warnings' : 'pass',
+    };
+}

package/dist/policy/extract-templates.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extract inline `template:` string literals from source files so the template
+ * policy surface can see markup that AOT/tsc treat as an opaque string. This is
+ * a deterministic, framework-agnostic regex extraction (Angular/Vue/Lit-style
+ * `template:` properties) — not a full TS parse. `templateUrl` is intentionally
+ * NOT followed (the referenced `.html` file is scanned directly).
+ */
+export interface IExtractedTemplate {
+    /** The template body (literal contents, quotes/backticks stripped). */
+    readonly body: string;
+    /** 1-based line in the source file where the body begins. */
+    readonly startLine: number;
+}
+export declare function extractInlineTemplates(content: string): IExtractedTemplate[];
+//# sourceMappingURL=extract-templates.d.ts.map

package/dist/policy/extract-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-templates.d.ts","sourceRoot":"","sources":["../../src/policy/extract-templates.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAmBD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAe5E"}

package/dist/policy/extract-templates.js

@@ -0,0 +1,42 @@
+/**
+ * Extract inline `template:` string literals from source files so the template
+ * policy surface can see markup that AOT/tsc treat as an opaque string. This is
+ * a deterministic, framework-agnostic regex extraction (Angular/Vue/Lit-style
+ * `template:` properties) — not a full TS parse. `templateUrl` is intentionally
+ * NOT followed (the referenced `.html` file is scanned directly).
+ */
+// `template:` followed by a single-quoted, double-quoted, or backtick literal.
+// Backtick allows newlines (multi-line templates). The `(?:\\.|[^delim\\])*`
+// form is escape-aware, so an escaped same-delimiter quote (`\"` inside `"…"`)
+// or an escaped backtick does NOT truncate the captured literal (which would
+// silently drop violations after it). A nested backtick inside a `${…}`
+// interpolation is still not handled (rare).
+const TEMPLATE_RE = /\btemplate\s*:\s*(`(?:\\.|[^`\\])*`|'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*")/g;
+function lineOf(content, index) {
+    let line = 1;
+    const end = Math.min(index, content.length);
+    for (let i = 0; i < end; i += 1) {
+        if (content[i] === '\n')
+            line += 1;
+    }
+    return line;
+}
+export function extractInlineTemplates(content) {
+    const out = [];
+    TEMPLATE_RE.lastIndex = 0;
+    let m;
+    while ((m = TEMPLATE_RE.exec(content)) !== null) {
+        if (m.index === TEMPLATE_RE.lastIndex)
+            TEMPLATE_RE.lastIndex += 1; // zero-width guard
+        const literal = m[1];
+        if (!literal)
+            continue;
+        const body = literal.slice(1, -1);
+        if (body.length === 0)
+            continue;
+        // Index of the opening delimiter, then +1 for the first body char.
+        const literalStart = m.index + m[0].length - literal.length;
+        out.push({ body, startLine: lineOf(content, literalStart + 1) });
+    }
+    return out;
+}

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

@@ -0,0 +1,21 @@
+import type { IPolicyRule, PolicySurface } from '@shrkcrft/core';
+import { type IPolicyReport } from './evaluate-policy.js';
+export interface IRunPolicyOptions {
+    /** Restrict to rules on these surfaces. */
+    readonly surfaces?: readonly PolicySurface[];
+    /** Run only these rule ids. */
+    readonly only?: readonly string[];
+    /** When true, only run rules whose globs match a changed file. */
+    readonly changedOnly?: boolean;
+    readonly changedFiles?: readonly string[];
+    /** Project-relative directories to prune from the walk (e.g. the SharkCraft asset dir). */
+    readonly excludeDirs?: readonly string[];
+}
+/**
+ * Filesystem-backed policy-lint. Walks the project once; on the `template`
+ * surface, source files contribute their inline `template:` bodies (with real
+ * source line numbers) while `.html` files are scanned whole. Pure-engine
+ * output; the only IO is the read-only walk + reads.
+ */
+export declare function runPolicyLint(projectRoot: string, rules: readonly IPolicyRule[], options?: IRunPolicyOptions): IPolicyReport;
+//# sourceMappingURL=run-policy.d.ts.map

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

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

package/dist/policy/run-policy.js

@@ -0,0 +1,61 @@
+import * as nodePath from 'node:path';
+import { matchesAny } from "../scan/glob.js";
+import { readMatchingFiles } from "../util/walk-files.js";
+import { extractInlineTemplates } from "./extract-templates.js";
+import { evaluatePolicy } from "./evaluate-policy.js";
+/** Per-surface default globs when a rule omits `files`. */
+const SURFACE_DEFAULT_GLOBS = {
+    // markup files (scanned whole) + source files (inline `template:` extracted).
+    template: ['**/*.html', '**/*.htm', '**/*.ts', '**/*.tsx'],
+    style: ['**/*.css', '**/*.scss', '**/*.sass', '**/*.less', '**/*.styl'],
+    ts: ['**/*.ts', '**/*.tsx'],
+};
+const SOURCE_EXT = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs']);
+function globsFor(rule) {
+    return rule.files && rule.files.length > 0 ? rule.files : SURFACE_DEFAULT_GLOBS[rule.surface];
+}
+/**
+ * Filesystem-backed policy-lint. Walks the project once; on the `template`
+ * surface, source files contribute their inline `template:` bodies (with real
+ * source line numbers) while `.html` files are scanned whole. Pure-engine
+ * output; the only IO is the read-only walk + reads.
+ */
+export function runPolicyLint(projectRoot, rules, options = {}) {
+    let selected = rules;
+    if (options.surfaces && options.surfaces.length > 0) {
+        const s = new Set(options.surfaces);
+        selected = selected.filter((r) => s.has(r.surface));
+    }
+    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) => changed.some((c) => matchesAny(c, globsFor(r))));
+    }
+    if (selected.length === 0) {
+        return { schema: 'sharkcraft.policy-lint/v1', rules: [], findings: [], diagnostics: [], verdict: 'pass' };
+    }
+    const allGlobs = [...new Set(selected.flatMap((r) => [...globsFor(r)]))];
+    const cache = readMatchingFiles(projectRoot, allGlobs, new Set(options.excludeDirs ?? []));
+    return evaluatePolicy(selected, (rule) => {
+        const globs = globsFor(rule);
+        const units = [];
+        for (const [path, content] of cache) {
+            if (!matchesAny(path, globs))
+                continue;
+            const ext = nodePath.extname(path).toLowerCase();
+            if (rule.surface === 'template' && SOURCE_EXT.has(ext)) {
+                for (const tpl of extractInlineTemplates(content)) {
+                    units.push({ path, content: tpl.body, baseLine: tpl.startLine, inlineTemplate: true });
+                }
+            }
+            else {
+                // .html on the template surface, and all style/ts files: scan whole.
+                units.push({ path, content, baseLine: 1 });
+            }
+        }
+        return units;
+    });
+}

package/dist/util/safe-regex.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Compile a user/pack-supplied regex without ever throwing. The `g` flag is
+ * always applied (engines scan with `exec` loops); extra flags are merged and
+ * de-duped. A bad pattern / bad flags returns a clear `error` string so callers
+ * degrade a misconfigured rule to a diagnostic instead of crashing.
+ */
+export declare function safeCompile(pattern: string, flags?: string): {
+    re?: RegExp;
+    error?: string;
+};
+/** Number of capture groups in a compiled regex (probe via an always-empty variant). */
+export declare function countCaptureGroups(re: RegExp): number;
+//# sourceMappingURL=safe-regex.d.ts.map

package/dist/util/safe-regex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-regex.d.ts","sourceRoot":"","sources":["../../src/util/safe-regex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAO5F;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAMrD"}

package/dist/util/safe-regex.js

@@ -0,0 +1,24 @@
+/**
+ * Compile a user/pack-supplied regex without ever throwing. The `g` flag is
+ * always applied (engines scan with `exec` loops); extra flags are merged and
+ * de-duped. A bad pattern / bad flags returns a clear `error` string so callers
+ * degrade a misconfigured rule to a diagnostic instead of crashing.
+ */
+export function safeCompile(pattern, flags) {
+    try {
+        const f = [...new Set(['g', ...(flags ?? '').split('')].filter(Boolean))].join('');
+        return { re: new RegExp(pattern, f) };
+    }
+    catch (e) {
+        return { error: `invalid regex /${pattern}/${flags ?? ''}: ${e.message}` };
+    }
+}
+/** Number of capture groups in a compiled regex (probe via an always-empty variant). */
+export function countCaptureGroups(re) {
+    try {
+        return (new RegExp(re.source + '|').exec('')?.length ?? 1) - 1;
+    }
+    catch {
+        return 1; // can't determine → assume valid
+    }
+}

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

@@ -0,0 +1,13 @@
+/** Vendor / build / VCS dirs never scanned. */
+export declare const SKIP_DIRS: ReadonlySet<string>;
+/** Files larger than this are skipped (regex token extraction over multi-MB blobs is pointless). */
+export declare const MAX_SCAN_FILE_BYTES = 1000000;
+/**
+ * Walk `root`, returning project-relative POSIX paths that match any glob.
+ * `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[];
+/** 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>;
+//# sourceMappingURL=walk-files.d.ts.map

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

@@ -0,0 +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"}

package/dist/util/walk-files.js

@@ -0,0 +1,80 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { matchesAny } from "../scan/glob.js";
+/** Vendor / build / VCS dirs never scanned. */
+export const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'coverage',
+    '.sharkcraft',
+    '.next',
+    '.turbo',
+    '.cache',
+]);
+/** Files larger than this are skipped (regex token extraction over multi-MB blobs is pointless). */
+export const MAX_SCAN_FILE_BYTES = 1_000_000;
+/**
+ * Walk `root`, returning project-relative POSIX paths that match any glob.
+ * `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()) {
+    const out = [];
+    const visit = (abs) => {
+        let entries;
+        try {
+            entries = readdirSync(abs, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const childAbs = nodePath.join(abs, e.name);
+            const rel = nodePath.relative(root, childAbs).split(nodePath.sep).join('/');
+            if (e.isDirectory()) {
+                // Skip vendor/build/VCS dirs AND every dot-directory (`.yarn`, `.pnp`,
+                // `.venv`, `.gradle`, …) — matching the established scan-imports walker,
+                // 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))
+                    continue;
+                visit(childAbs);
+            }
+            else if (e.isFile()) {
+                if (matchesAny(rel, globs))
+                    out.push(rel);
+            }
+        }
+    };
+    visit(root);
+    return out;
+}
+/** Walk + read every file matching `globs`, skipping oversized/unreadable files. */
+export function readMatchingFiles(root, globs, excludeDirs = new Set()) {
+    const out = new Map();
+    for (const rel of walkMatching(root, globs, excludeDirs)) {
+        const abs = nodePath.join(root, rel);
+        let size = -1;
+        try {
+            const st = statSync(abs);
+            if (!st.isFile())
+                continue;
+            size = st.size;
+        }
+        catch {
+            continue;
+        }
+        if (size > MAX_SCAN_FILE_BYTES)
+            continue;
+        try {
+            out.set(rel, readFileSync(abs, 'utf8'));
+        }
+        catch {
+            // unreadable — skip
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,52 @@
+import type { IWiringRule, IWiringSource } from '@shrkcrft/core';
+export declare const WIRING_SCHEMA: "sharkcraft.wiring/v1";
+/** A file made available to the engine. */
+export interface IWiringFileEntry {
+    /** Project-relative POSIX path. */
+    readonly path: string;
+    readonly content: string;
+}
+/** A captured token + where it was captured (for declared tokens). */
+export interface IWiringTokenSite {
+    readonly token: string;
+    readonly file: string;
+    readonly line: number;
+}
+export interface IWiringViolation {
+    readonly ruleId: string;
+    /** The declared token that is not present in the registered set. */
+    readonly token: string;
+    /** Declaring file (project-relative) + 1-based line. */
+    readonly file: string;
+    readonly line: number;
+    readonly severity: 'error' | 'warning';
+    readonly hint?: string;
+}
+export interface IWiringRuleResult {
+    readonly ruleId: string;
+    readonly description?: string;
+    readonly severity: 'error' | 'warning';
+    readonly declaredCount: number;
+    readonly registeredCount: number;
+    readonly violations: readonly IWiringViolation[];
+    /** Set when the rule is misconfigured (bad regex / no capture group). */
+    readonly error?: string;
+}
+export interface IWiringReport {
+    readonly schema: typeof WIRING_SCHEMA;
+    readonly rules: readonly IWiringRuleResult[];
+    readonly violations: readonly IWiringViolation[];
+    /** Rule-level misconfiguration messages (never throws — degrades gracefully). */
+    readonly diagnostics: readonly string[];
+    readonly verdict: 'pass' | 'errors' | 'warnings';
+}
+/** Resolves a rule-side's globs to the concrete files (path + content) to scan. */
+export type WiringFileResolver = (source: IWiringSource) => readonly IWiringFileEntry[];
+/**
+ * Pure wiring evaluation. For each rule: every DECLARED token that is not in the
+ * REGISTERED set is a violation, reported at its first declaring site. 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;
+//# sourceMappingURL=evaluate-wiring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-wiring.d.ts","sourceRoot":"","sources":["../../src/wiring/evaluate-wiring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGjE,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAE7D,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;CAClD;AAED,mFAAmF;AACnF,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,aAAa,KAAK,SAAS,gBAAgB,EAAE,CAAC;AAiDxF;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,aAAa,CAkFf"}

package/dist/wiring/evaluate-wiring.js

@@ -0,0 +1,131 @@
+import { safeCompile, countCaptureGroups } from "../util/safe-regex.js";
+export const WIRING_SCHEMA = 'sharkcraft.wiring/v1';
+/**
+ * Compile a rule-side's pattern, never throwing. Returns the regex or a clear
+ * error string for an uncompilable pattern / bad flags / missing capture group
+ * (group 1 is the token contract). A misconfigured rule must degrade to a
+ * diagnostic, not crash the check or the whole gate aggregator.
+ */
+function compileSafe(source) {
+    const { re, error } = safeCompile(source.pattern, source.flags);
+    if (error)
+        return { error };
+    if (countCaptureGroups(re) < 1) {
+        return {
+            error: `pattern /${source.pattern}/ has no capture group — group 1 must capture the token`,
+        };
+    }
+    return { re };
+}
+/** Collect every capture-group-1 token from a precompiled side, with declaring sites. */
+function collectTokens(re, files) {
+    const tokens = new Set();
+    const sites = [];
+    for (const f of files) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(f.content)) !== null) {
+            // Guard against a zero-width match looping forever.
+            if (m.index === re.lastIndex)
+                re.lastIndex += 1;
+            const token = m[1];
+            if (token === undefined || token === '')
+                continue;
+            tokens.add(token);
+            sites.push({ token, file: f.path, line: lineOf(f.content, m.index) });
+        }
+    }
+    return { tokens, sites };
+}
+function lineOf(content, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < content.length; i += 1) {
+        if (content[i] === '\n')
+            line += 1;
+    }
+    return line;
+}
+/**
+ * Pure wiring evaluation. For each rule: every DECLARED token that is not in the
+ * REGISTERED set is a violation, reported at its first declaring site. 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) {
+    const ruleResults = [];
+    const all = [];
+    const diagnostics = [];
+    let misconfigError = false;
+    let misconfigWarn = false;
+    for (const rule of rules) {
+        const severity = rule.severity ?? 'error';
+        // Compile both sides defensively — a misconfigured rule becomes a
+        // diagnostic, never a thrown exception that would crash the gate.
+        const declaredRe = compileSafe(rule.declared);
+        const registeredRe = compileSafe(rule.registered);
+        if (declaredRe.error || registeredRe.error) {
+            const parts = [
+                declaredRe.error ? `declared ${declaredRe.error}` : '',
+                registeredRe.error ? `registered ${registeredRe.error}` : '',
+            ].filter(Boolean);
+            const msg = `rule "${rule.id}": ${parts.join('; ')}`;
+            diagnostics.push(msg);
+            if (severity === 'error')
+                misconfigError = true;
+            else
+                misconfigWarn = true;
+            ruleResults.push({
+                ruleId: rule.id,
+                ...(rule.description ? { description: rule.description } : {}),
+                severity,
+                declaredCount: 0,
+                registeredCount: 0,
+                violations: [],
+                error: msg,
+            });
+            continue;
+        }
+        const declared = collectTokens(declaredRe.re, resolve(rule.declared));
+        const registered = collectTokens(registeredRe.re, resolve(rule.registered));
+        // First declaring site per token, in stable (file, line) order.
+        const firstSite = new Map();
+        for (const s of [...declared.sites].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)) {
+            if (!firstSite.has(s.token))
+                firstSite.set(s.token, s);
+        }
+        const violations = [];
+        for (const token of [...declared.tokens].sort()) {
+            if (registered.tokens.has(token))
+                continue;
+            const site = firstSite.get(token);
+            violations.push({
+                ruleId: rule.id,
+                token,
+                file: site?.file ?? '',
+                line: site?.line ?? 0,
+                severity,
+                ...(rule.hint ? { hint: rule.hint } : {}),
+            });
+        }
+        ruleResults.push({
+            ruleId: rule.id,
+            ...(rule.description ? { description: rule.description } : {}),
+            severity,
+            declaredCount: declared.tokens.size,
+            registeredCount: registered.tokens.size,
+            violations,
+        });
+        all.push(...violations);
+    }
+    // A misconfigured rule must not pass as a silent green — it counts toward the
+    // verdict at its own severity (default error).
+    const hasError = misconfigError || all.some((v) => v.severity === 'error');
+    const hasWarn = misconfigWarn || all.some((v) => v.severity === 'warning');
+    return {
+        schema: WIRING_SCHEMA,
+        rules: ruleResults,
+        violations: all,
+        diagnostics,
+        verdict: hasError ? 'errors' : hasWarn ? 'warnings' : 'pass',
+    };
+}

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

@@ -0,0 +1,19 @@
+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. */
+    readonly changedFiles?: readonly string[];
+    /** When true with no changed files, run nothing (matches `--changed-only` with a clean tree). */
+    readonly changedOnly?: boolean;
+    /** Run only these rule ids. */
+    readonly only?: readonly string[];
+    /** Project-relative directories to prune from the walk (e.g. the SharkCraft asset dir). */
+    readonly excludeDirs?: readonly string[];
+}
+/**
+ * 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.
+ */
+export declare function runWiring(projectRoot: string, rules: readonly IWiringRule[], options?: IRunWiringOptions): IWiringReport;
+//# sourceMappingURL=scan-wiring-files.d.ts.map

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

@@ -0,0 +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,EAGL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,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,CAyBf"}

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

@@ -0,0 +1,32 @@
+import { matchesAny } from "../scan/glob.js";
+import { readMatchingFiles } from "../util/walk-files.js";
+import { evaluateWiring, } from "./evaluate-wiring.js";
+/**
+ * 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.
+ */
+export function runWiring(projectRoot, rules, options = {}) {
+    let selected = rules;
+    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 = [...r.declared.files, ...r.registered.files];
+            return changed.some((c) => matchesAny(c, globs));
+        });
+    }
+    if (selected.length === 0) {
+        return { schema: 'sharkcraft.wiring/v1', rules: [], violations: [], diagnostics: [], verdict: 'pass' };
+    }
+    // Union of all globs across selected rules → one tree walk, cached reads.
+    const allGlobs = [
+        ...new Set(selected.flatMap((r) => [...r.declared.files, ...r.registered.files])),
+    ];
+    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)));
+}

package/package.json

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