@shrkcrft/boundaries 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/boundaries
+
+SharkCraft boundary rules: detect when a repository violates its own architecture (forbidden imports across folder/package/layer boundaries).
+
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/boundaries
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

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

@@ -0,0 +1,48 @@
+import type { IBoundaryRule, BoundarySeverity } from '../model/boundary-rule.js';
+import type { IImportScanResult } from '../scan/scan-imports.js';
+import { type ITsconfigPathsMap } from '../scan/tsconfig-aliases.js';
+export interface IBoundaryViolation {
+    ruleId: string;
+    ruleTitle: string;
+    severity: BoundarySeverity;
+    file: string;
+    importSpecifier: string;
+    line: number;
+    /** Pattern from `from` that matched the file. */
+    matchedFrom: string;
+    /** Pattern from `forbiddenImports` that matched the specifier, if any. */
+    matchedForbidden?: string;
+    /** When triggered by allowedImports = [..] (none matched). */
+    notAllowed?: boolean;
+    /** When the match came from an alias-resolved candidate path. */
+    resolvedVia?: string;
+    message: string;
+    suggestedFix?: string;
+}
+export interface IEvaluateOptions {
+    /** Optional filter: only evaluate rules with this id. */
+    onlyRuleId?: string;
+    /**
+     * Optional tsconfig paths map. When supplied, every edge specifier is also
+     * resolved against the alias map and the resulting candidate paths are
+     * matched against rule patterns alongside the original specifier.
+     */
+    tsconfigPaths?: ITsconfigPathsMap;
+}
+export interface IEvaluateResult {
+    rulesEvaluated: number;
+    edgesEvaluated: number;
+    violations: IBoundaryViolation[];
+    /** Quick counts grouped by severity. */
+    counts: {
+        error: number;
+        warning: number;
+        info: number;
+    };
+}
+/**
+ * Evaluate every rule against every scanned edge. Returns the list of
+ * violations + counts. Pure function — no I/O.
+ */
+export declare function evaluateBoundaries(scan: IImportScanResult, rules: readonly IBoundaryRule[], options?: IEvaluateOptions): IEvaluateResult;
+//# sourceMappingURL=evaluate-boundaries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-boundaries.d.ts","sourceRoot":"","sources":["../../src/evaluate/evaluate-boundaries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEjF,OAAO,KAAK,EAAe,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,6BAA6B,CAAC;AAErC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,iBAAiB,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,wCAAwC;IACxC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CA6DjB"}

package/dist/evaluate/evaluate-boundaries.js

@@ -0,0 +1,96 @@
+import { matchesAny } from "../scan/glob.js";
+import { resolveAliasCandidates, } from "../scan/tsconfig-aliases.js";
+function severityOf(rule) {
+    return rule.severity ?? 'error';
+}
+/**
+ * Evaluate every rule against every scanned edge. Returns the list of
+ * violations + counts. Pure function — no I/O.
+ */
+export function evaluateBoundaries(scan, rules, options = {}) {
+    const filtered = options.onlyRuleId
+        ? rules.filter((r) => r.id === options.onlyRuleId)
+        : rules;
+    const violations = [];
+    for (const rule of filtered) {
+        for (const edge of scan.edges) {
+            const matchedFrom = firstMatch(edge.from, rule.from);
+            if (!matchedFrom)
+                continue;
+            // Build the candidate list: the literal specifier + any tsconfig
+            // alias resolutions. The first match wins; resolved paths give the
+            // boundary rule a chance to match against `libs/app/adapter/**`
+            // even when the source code wrote `@app/adapter-core`.
+            const specifiers = [edge.importSpecifier];
+            if (options.tsconfigPaths) {
+                for (const resolved of resolveAliasCandidates(edge.importSpecifier, options.tsconfigPaths)) {
+                    specifiers.push(resolved);
+                }
+            }
+            // Forbidden imports — match any candidate.
+            let matchedForbidden;
+            let matchedVia;
+            if (rule.forbiddenImports) {
+                for (const spec of specifiers) {
+                    const m = firstMatch(spec, rule.forbiddenImports);
+                    if (m) {
+                        matchedForbidden = m;
+                        matchedVia = spec !== edge.importSpecifier ? spec : undefined;
+                        break;
+                    }
+                }
+            }
+            if (matchedForbidden) {
+                const v = violationFor(rule, edge, matchedFrom, matchedForbidden);
+                if (matchedVia)
+                    v.resolvedVia = matchedVia;
+                violations.push(v);
+                continue;
+            }
+            // Allowed imports — when set, anything NOT matching (any candidate)
+            // is a violation.
+            if (rule.allowedImports && rule.allowedImports.length > 0) {
+                const matchedAllowed = specifiers.some((s) => matchesAny(s, rule.allowedImports));
+                if (!matchedAllowed && !edge.importSpecifier.startsWith('.')) {
+                    violations.push({
+                        ...violationFor(rule, edge, matchedFrom, undefined),
+                        notAllowed: true,
+                    });
+                }
+            }
+        }
+    }
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const v of violations)
+        counts[v.severity] += 1;
+    return {
+        rulesEvaluated: filtered.length,
+        edgesEvaluated: scan.edges.length,
+        violations,
+        counts,
+    };
+}
+function firstMatch(value, patterns) {
+    for (const p of patterns) {
+        if (matchesAny(value, [p]))
+            return p;
+    }
+    return undefined;
+}
+function violationFor(rule, edge, matchedFrom, matchedForbidden) {
+    return {
+        ruleId: rule.id,
+        ruleTitle: rule.title,
+        severity: severityOf(rule),
+        file: edge.from,
+        importSpecifier: edge.importSpecifier,
+        line: edge.line,
+        matchedFrom,
+        ...(matchedForbidden ? { matchedForbidden } : {}),
+        message: rule.message ??
+            (matchedForbidden
+                ? `Forbidden import in ${edge.from}: "${edge.importSpecifier}" matched "${matchedForbidden}"`
+                : `Import "${edge.importSpecifier}" not in allowed list for ${rule.id}`),
+        ...(rule.suggestedFix ? { suggestedFix: rule.suggestedFix } : {}),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './model/boundary-rule.js';
+export * from './registry/boundary-registry.js';
+export * from './registry/load-boundary-rules.js';
+export * from './scan/glob.js';
+export * from './scan/scan-imports.js';
+export * from './evaluate/evaluate-boundaries.js';
+export * from './scan/tsconfig-aliases.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./model/boundary-rule.js";
+export * from "./registry/boundary-registry.js";
+export * from "./registry/load-boundary-rules.js";
+export * from "./scan/glob.js";
+export * from "./scan/scan-imports.js";
+export * from "./evaluate/evaluate-boundaries.js";
+export * from "./scan/tsconfig-aliases.js";

package/dist/model/boundary-rule.d.ts

@@ -0,0 +1,38 @@
+export type BoundarySeverity = 'error' | 'warning' | 'info';
+export interface IBoundaryRule {
+    id: string;
+    title: string;
+    description?: string;
+    severity?: BoundarySeverity;
+    /**
+     * Glob patterns describing which files the rule applies to. Matched against
+     * the file path relative to the project root.
+     */
+    from: readonly string[];
+    /**
+     * Glob patterns describing imports that are forbidden from `from` files.
+     * Matched against the literal import specifier.
+     */
+    forbiddenImports?: readonly string[];
+    /**
+     * Optional whitelist of allowed imports (when set, non-matching imports
+     * also trigger the rule). Useful for "from X, only @x/y is allowed".
+     */
+    allowedImports?: readonly string[];
+    tags?: readonly string[];
+    appliesWhen?: readonly string[];
+    message?: string;
+    suggestedFix?: string;
+    relatedRules?: readonly string[];
+    relatedPathConventions?: readonly string[];
+}
+export declare function defineBoundaryRule<T extends IBoundaryRule>(rule: T): T;
+export interface IBoundaryRuleValidationIssue {
+    field: string;
+    message: string;
+}
+export declare function validateBoundaryRule(value: unknown): {
+    valid: boolean;
+    issues: IBoundaryRuleValidationIssue[];
+};
+//# sourceMappingURL=boundary-rule.d.ts.map

package/dist/model/boundary-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-rule.d.ts","sourceRoot":"","sources":["../../src/model/boundary-rule.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;;;OAGG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;OAGG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,aAAa,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAEtE;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG;IACpD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,4BAA4B,EAAE,CAAC;CACxC,CAyBA"}

package/dist/model/boundary-rule.js

@@ -0,0 +1,30 @@
+export function defineBoundaryRule(rule) {
+    return rule;
+}
+const ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+export function validateBoundaryRule(value) {
+    const issues = [];
+    if (!value || typeof value !== 'object') {
+        return {
+            valid: false,
+            issues: [{ field: '<root>', message: 'rule must be an object' }],
+        };
+    }
+    const r = value;
+    if (typeof r.id !== 'string' || !ID_PATTERN.test(r.id)) {
+        issues.push({ field: 'id', message: 'id required, slug-style' });
+    }
+    if (typeof r.title !== 'string' || r.title.length === 0) {
+        issues.push({ field: 'title', message: 'title required' });
+    }
+    if (!Array.isArray(r.from) || r.from.length === 0) {
+        issues.push({ field: 'from', message: 'from must be a non-empty string array' });
+    }
+    if (!Array.isArray(r.forbiddenImports) && !Array.isArray(r.allowedImports)) {
+        issues.push({
+            field: 'forbiddenImports|allowedImports',
+            message: 'either forbiddenImports or allowedImports must be set',
+        });
+    }
+    return { valid: issues.length === 0, issues };
+}

package/dist/registry/boundary-registry.d.ts

@@ -0,0 +1,11 @@
+import type { IBoundaryRule } from '../model/boundary-rule.js';
+export declare class BoundaryRegistry {
+    private readonly byId;
+    constructor(rules?: readonly IBoundaryRule[]);
+    add(rule: IBoundaryRule): void;
+    has(id: string): boolean;
+    get(id: string): IBoundaryRule | undefined;
+    list(): readonly IBoundaryRule[];
+    size(): number;
+}
+//# sourceMappingURL=boundary-registry.d.ts.map

package/dist/registry/boundary-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-registry.d.ts","sourceRoot":"","sources":["../../src/registry/boundary-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoC;gBAE7C,KAAK,GAAE,SAAS,aAAa,EAAO;IAGhD,GAAG,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAG9B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAGxB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAG1C,IAAI,IAAI,SAAS,aAAa,EAAE;IAGhC,IAAI,IAAI,MAAM;CAGf"}

package/dist/registry/boundary-registry.js

@@ -0,0 +1,22 @@
+export class BoundaryRegistry {
+    byId = new Map();
+    constructor(rules = []) {
+        for (const r of rules)
+            this.add(r);
+    }
+    add(rule) {
+        this.byId.set(rule.id, rule);
+    }
+    has(id) {
+        return this.byId.has(id);
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    list() {
+        return [...this.byId.values()];
+    }
+    size() {
+        return this.byId.size;
+    }
+}

package/dist/registry/load-boundary-rules.d.ts

@@ -0,0 +1,12 @@
+import { type IImportContext } from '@shrkcrft/core';
+import { type IBoundaryRule } from '../model/boundary-rule.js';
+export interface ILoadedBoundaryRulesFile {
+    source: string;
+    rules: IBoundaryRule[];
+    warnings: string[];
+}
+export interface ILoadBoundaryRulesOptions {
+    importContext?: IImportContext;
+}
+export declare function loadBoundaryRulesFromFile(absPath: string, options?: ILoadBoundaryRulesOptions): Promise<ILoadedBoundaryRulesFile>;
+//# sourceMappingURL=load-boundary-rules.d.ts.map

package/dist/registry/load-boundary-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-boundary-rules.d.ts","sourceRoot":"","sources":["../../src/registry/load-boundary-rules.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,cAAc,EAAc,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAErF,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,aAAa,CAAC,EAAE,cAAc,CAAC;CAChC;AAED,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CA0CnC"}

package/dist/registry/load-boundary-rules.js

@@ -0,0 +1,44 @@
+import { existsSync } from 'node:fs';
+import { safeImport } from '@shrkcrft/core';
+import { validateBoundaryRule } from "../model/boundary-rule.js";
+export async function loadBoundaryRulesFromFile(absPath, options = {}) {
+    const out = {
+        source: absPath,
+        rules: [],
+        warnings: [],
+    };
+    if (!existsSync(absPath)) {
+        out.warnings.push(`boundary rules file not found: ${absPath}`);
+        return out;
+    }
+    const result = options.importContext
+        ? await options.importContext.load(absPath)
+        : await safeImport(absPath, {
+            skipExistsCheck: true,
+        });
+    if (!result.ok) {
+        const label = result.timedOut
+            ? 'timed out loading boundary rules from'
+            : 'failed to load boundary rules from';
+        out.warnings.push(`${label} ${absPath}: ${result.error.message}`);
+        return out;
+    }
+    const candidates = pickArray(result.module.default) ??
+        pickArray(result.module.rules) ??
+        pickArray(result.module.boundaries) ??
+        [];
+    for (const c of candidates) {
+        const v = validateBoundaryRule(c);
+        if (!v.valid) {
+            out.warnings.push(`${absPath}: skipping invalid boundary rule (${v.issues.map((i) => i.field).join(', ')})`);
+            continue;
+        }
+        out.rules.push(c);
+    }
+    return out;
+}
+function pickArray(v) {
+    if (Array.isArray(v))
+        return v;
+    return null;
+}

package/dist/scan/glob.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Minimal glob matcher tuned for the patterns boundary rules use:
+ *   - `**` matches any number of path segments (including zero)
+ *   - `*`  matches any chars except `/`
+ *   - `?`  matches a single char except `/`
+ *   - everything else is literal
+ *
+ * Patterns are matched against the literal string (file path or import
+ * specifier) — no I/O, no resolution. The function is pure and deterministic.
+ */
+export declare function globToRegex(pattern: string): RegExp;
+export declare function matchesAny(value: string, patterns: readonly string[]): boolean;
+//# sourceMappingURL=glob.d.ts.map

package/dist/scan/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/scan/glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAmCnD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAK9E"}

package/dist/scan/glob.js

@@ -0,0 +1,55 @@
+/**
+ * Minimal glob matcher tuned for the patterns boundary rules use:
+ *   - `**` matches any number of path segments (including zero)
+ *   - `*`  matches any chars except `/`
+ *   - `?`  matches a single char except `/`
+ *   - everything else is literal
+ *
+ * Patterns are matched against the literal string (file path or import
+ * specifier) — no I/O, no resolution. The function is pure and deterministic.
+ */
+export function globToRegex(pattern) {
+    let r = '';
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern[i];
+        if (ch === '*') {
+            // ** vs *
+            const next = pattern[i + 1];
+            if (next === '*') {
+                // ** — zero or more segments
+                // Also consume a trailing `/` so `a/** /b` matches `a/b`.
+                const after = pattern[i + 2];
+                if (after === '/') {
+                    r += '(?:.*/)?';
+                    i += 2;
+                }
+                else {
+                    r += '.*';
+                    i += 1;
+                }
+            }
+            else {
+                r += '[^/]*';
+            }
+            continue;
+        }
+        if (ch === '?') {
+            r += '[^/]';
+            continue;
+        }
+        // Escape regex special chars.
+        if ('.+^$|(){}[]\\'.includes(ch)) {
+            r += '\\' + ch;
+            continue;
+        }
+        r += ch;
+    }
+    return new RegExp('^' + r + '$');
+}
+export function matchesAny(value, patterns) {
+    for (const p of patterns) {
+        if (globToRegex(p).test(value))
+            return true;
+    }
+    return false;
+}

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

@@ -0,0 +1,46 @@
+export interface IScanImportsOptions {
+    projectRoot: string;
+    extraIgnore?: readonly string[];
+    /** When set, only files under one of these globs are scanned. */
+    include?: readonly string[];
+}
+export interface IImportEdge {
+    /** Source file (relative to projectRoot). */
+    from: string;
+    /** Literal import specifier. */
+    importSpecifier: string;
+    /** Approximate 1-based line number in the source file. */
+    line: number;
+    /**
+     * Heuristic resolution. v1 sets:
+     *   - 'internal' if the specifier starts with './' or '../'
+     *   - 'external' otherwise
+     * (We do not attempt tsconfig path-mapping resolution here.)
+     */
+    kind: 'internal' | 'external';
+}
+export interface IImportScanResult {
+    filesScanned: number;
+    edges: IImportEdge[];
+    warnings: string[];
+}
+/**
+ * Walk the project root and return every detected import edge.
+ */
+export declare function scanImports(options: IScanImportsOptions): IImportScanResult;
+/**
+ * Aggregate summary for `shrk graph imports` / MCP get_import_graph_summary.
+ */
+export interface IImportGraphSummary {
+    filesScanned: number;
+    totalImports: number;
+    internalImports: number;
+    externalImports: number;
+    topExternalSpecifiers: readonly {
+        specifier: string;
+        count: number;
+    }[];
+    warnings: readonly string[];
+}
+export declare function summarizeImports(scan: IImportScanResult): IImportGraphSummary;
+//# sourceMappingURL=scan-imports.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scan-imports.d.ts","sourceRoot":"","sources":["../../src/scan/scan-imports.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,iEAAiE;IACjE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAoFD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,CAyB3E;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,SAAS;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAmB7E"}

package/dist/scan/scan-imports.js

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+const SUPPORTED_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+const DEFAULT_IGNORE = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.git',
+    '.sharkcraft',
+    '.next',
+    '.cache',
+    '.tmp-pack',
+    '.tmp-smoke-consumer.txt',
+]);
+// Match `import ... from 'x'`, `export ... from 'x'`, `require('x')`,
+// `import('x')` (static and dynamic). Captures the specifier as group 1.
+//
+// We DELIBERATELY use a single regex per kind rather than a real parser —
+// boundary rules need stable behavior across syntaxes and a regex scanner is
+// the simplest thing that works for v1. Comments and string escapes can fool
+// it; we filter the lowest-hanging fruit (single-line // and /* */ stripped
+// per line, but a `// import "x"` line is still ignored).
+const IMPORT_RE = /(?:^|\s)(?:import|export)\s+[^'"`]*?from\s+['"]([^'"`]+)['"]/g;
+const SIDE_EFFECT_IMPORT_RE = /(?:^|\s)import\s+['"]([^'"`]+)['"]/g;
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"`]+)['"]\s*\)/g;
+const REQUIRE_RE = /\brequire\s*\(\s*['"]([^'"`]+)['"]\s*\)/g;
+function isIgnored(name, extraIgnore) {
+    if (DEFAULT_IGNORE.has(name))
+        return true;
+    if (extraIgnore.has(name))
+        return true;
+    if (name.startsWith('.'))
+        return name !== '.';
+    return false;
+}
+function* walk(root, current, extraIgnore) {
+    let entries;
+    try {
+        entries = readdirSync(current, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const name = String(entry.name);
+        if (isIgnored(name, extraIgnore))
+            continue;
+        const full = nodePath.join(current, name);
+        try {
+            const isDir = entry.isDirectory() || entry.isSymbolicLink();
+            if (isDir) {
+                const stat = statSync(full);
+                if (stat.isDirectory()) {
+                    yield* walk(root, full, extraIgnore);
+                }
+                continue;
+            }
+        }
+        catch {
+            continue;
+        }
+        if (entry.isFile()) {
+            const ext = nodePath.extname(name);
+            if (!SUPPORTED_EXTS.has(ext))
+                continue;
+            yield full;
+        }
+    }
+}
+function lineFor(source, offset) {
+    let line = 1;
+    for (let i = 0; i < offset && i < source.length; i += 1) {
+        if (source[i] === '\n')
+            line += 1;
+    }
+    return line;
+}
+function extractImports(source, relPath) {
+    const edges = [];
+    for (const re of [IMPORT_RE, SIDE_EFFECT_IMPORT_RE, DYNAMIC_IMPORT_RE, REQUIRE_RE]) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            const spec = m[1];
+            const line = lineFor(source, m.index);
+            edges.push({
+                from: relPath,
+                importSpecifier: spec,
+                line,
+                kind: spec.startsWith('.') ? 'internal' : 'external',
+            });
+        }
+    }
+    return edges;
+}
+/**
+ * Walk the project root and return every detected import edge.
+ */
+export function scanImports(options) {
+    const root = nodePath.resolve(options.projectRoot);
+    const extraIgnore = new Set(options.extraIgnore ?? []);
+    const result = {
+        filesScanned: 0,
+        edges: [],
+        warnings: [],
+    };
+    if (!existsSync(root)) {
+        result.warnings.push(`scan root does not exist: ${root}`);
+        return result;
+    }
+    for (const file of walk(root, root, extraIgnore)) {
+        result.filesScanned += 1;
+        const rel = nodePath.relative(root, file);
+        let source;
+        try {
+            source = readFileSync(file, 'utf8');
+        }
+        catch (e) {
+            result.warnings.push(`unreadable: ${rel} (${e.message})`);
+            continue;
+        }
+        result.edges.push(...extractImports(source, rel));
+    }
+    return result;
+}
+export function summarizeImports(scan) {
+    const externalCounts = new Map();
+    let internal = 0;
+    for (const e of scan.edges) {
+        if (e.kind === 'internal')
+            internal += 1;
+        else
+            externalCounts.set(e.importSpecifier, (externalCounts.get(e.importSpecifier) ?? 0) + 1);
+    }
+    const top = [...externalCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([specifier, count]) => ({ specifier, count }));
+    return {
+        filesScanned: scan.filesScanned,
+        totalImports: scan.edges.length,
+        internalImports: internal,
+        externalImports: scan.edges.length - internal,
+        topExternalSpecifiers: top,
+        warnings: scan.warnings,
+    };
+}

package/dist/scan/tsconfig-aliases.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal tsconfig paths resolver. We read tsconfig.json and tsconfig.base.json
+ * from the project root, then build a map of import-specifier patterns to
+ * project-relative target paths. The resolver supports:
+ *
+ *   - Exact aliases:        "@scope/x": ["packages/x/src/index.ts"]
+ *   - Wildcard aliases:     "@scope/*": ["packages/*\/src/index.ts"]
+ *
+ * v1 does NOT resolve node_modules, .d.ts vs .js variants, or index lookups.
+ * The result is a list of *candidate paths*; the boundary evaluator matches
+ * those candidates against `from` patterns just like literal specifiers.
+ */
+export interface ITsconfigPathsMap {
+    baseUrl: string;
+    /** Each alias maps to one or more target patterns. */
+    aliases: ReadonlyMap<string, readonly string[]>;
+    /** Source files actually read (for cache invalidation / debug). */
+    sources: readonly string[];
+}
+/**
+ * Read tsconfig(.base).json from `projectRoot` and return a normalized map of
+ * paths aliases. Both files are tried; entries from tsconfig.json win on
+ * conflict.
+ */
+export declare function loadTsconfigPaths(projectRoot: string): ITsconfigPathsMap;
+/**
+ * Given an import specifier, return the list of project-relative target paths
+ * the tsconfig paths map would resolve it to.
+ *
+ * Returns an empty array when no alias matches. The original specifier is NOT
+ * included; the caller is expected to keep using both.
+ */
+export declare function resolveAliasCandidates(specifier: string, map: ITsconfigPathsMap): string[];
+//# sourceMappingURL=tsconfig-aliases.d.ts.map

package/dist/scan/tsconfig-aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsconfig-aliases.d.ts","sourceRoot":"","sources":["../../src/scan/tsconfig-aliases.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAChD,mEAAmE;IACnE,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AA2DD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,CA2BxE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,iBAAiB,GACrB,MAAM,EAAE,CAaV"}

package/dist/scan/tsconfig-aliases.js

@@ -0,0 +1,126 @@
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+function readJsonRelaxed(p) {
+    // tsconfig allows // line comments, /* block comments */, and trailing
+    // commas. The naive regex approach mangles real string values that happen
+    // to contain "/*" or "//" (e.g. wildcard paths like "packages/*/src/index.ts"
+    // or URL fragments). Walk char-by-char and track string state so we only
+    // strip syntactic comments + trailing commas, never content inside strings.
+    try {
+        const raw = readFileSync(p, 'utf8');
+        const out = [];
+        let i = 0;
+        let inString = false;
+        let stringQuote = '';
+        let escape = false;
+        while (i < raw.length) {
+            const ch = raw[i];
+            if (inString) {
+                out.push(ch);
+                if (escape) {
+                    escape = false;
+                }
+                else if (ch === '\\') {
+                    escape = true;
+                }
+                else if (ch === stringQuote) {
+                    inString = false;
+                }
+                i += 1;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                inString = true;
+                stringQuote = ch;
+                out.push(ch);
+                i += 1;
+                continue;
+            }
+            // Line comment
+            if (ch === '/' && raw[i + 1] === '/') {
+                while (i < raw.length && raw[i] !== '\n')
+                    i += 1;
+                continue;
+            }
+            // Block comment
+            if (ch === '/' && raw[i + 1] === '*') {
+                i += 2;
+                while (i < raw.length && !(raw[i] === '*' && raw[i + 1] === '/'))
+                    i += 1;
+                i += 2;
+                continue;
+            }
+            out.push(ch);
+            i += 1;
+        }
+        // Remove trailing commas before } or ]. Safe outside strings now.
+        const trimmed = out.join('').replace(/,(\s*[}\]])/g, '$1');
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read tsconfig(.base).json from `projectRoot` and return a normalized map of
+ * paths aliases. Both files are tried; entries from tsconfig.json win on
+ * conflict.
+ */
+export function loadTsconfigPaths(projectRoot) {
+    const sources = [];
+    const aliases = new Map();
+    let baseUrl;
+    const candidates = ['tsconfig.base.json', 'tsconfig.json'];
+    for (const name of candidates) {
+        const full = nodePath.join(projectRoot, name);
+        if (!existsSync(full))
+            continue;
+        const json = readJsonRelaxed(full);
+        if (!json?.compilerOptions)
+            continue;
+        sources.push(full);
+        if (json.compilerOptions.baseUrl && !baseUrl)
+            baseUrl = json.compilerOptions.baseUrl;
+        for (const [k, v] of Object.entries(json.compilerOptions.paths ?? {})) {
+            if (!aliases.has(k))
+                aliases.set(k, v);
+        }
+    }
+    return {
+        baseUrl: baseUrl ?? '.',
+        aliases,
+        sources,
+    };
+}
+/**
+ * Given an import specifier, return the list of project-relative target paths
+ * the tsconfig paths map would resolve it to.
+ *
+ * Returns an empty array when no alias matches. The original specifier is NOT
+ * included; the caller is expected to keep using both.
+ */
+export function resolveAliasCandidates(specifier, map) {
+    // Exact alias first.
+    const exact = map.aliases.get(specifier);
+    if (exact)
+        return [...exact.map((t) => normalize(map.baseUrl, t))];
+    // Wildcard alias: pattern ends with `*`.
+    for (const [pattern, targets] of map.aliases) {
+        if (!pattern.endsWith('*'))
+            continue;
+        const prefix = pattern.slice(0, -1);
+        if (!specifier.startsWith(prefix))
+            continue;
+        const suffix = specifier.slice(prefix.length);
+        return targets.map((t) => normalize(map.baseUrl, t.replace('*', suffix)));
+    }
+    return [];
+}
+function normalize(baseUrl, target) {
+    // Strip leading "./" and join with baseUrl if non-trivial.
+    let t = target.replace(/^\.\//, '');
+    if (baseUrl && baseUrl !== '.' && baseUrl !== './') {
+        t = nodePath.posix.join(baseUrl.replace(/^\.\//, ''), t);
+    }
+    return t;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@shrkcrft/boundaries",
+  "version": "0.1.0-alpha.2",
+  "description": "SharkCraft boundary rules: detect when a repository violates its own architecture (forbidden imports across folder/package/layer boundaries).",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shrkcrft/sharkcraft.git",
+    "directory": "packages/boundaries"
+  },
+  "homepage": "https://github.com/shrkcrft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/shrkcrft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "boundaries",
+    "architecture",
+    "imports"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}