@shrkcrft/rule-graph 0.1.0-alpha.10

package/dist/bridge/bridge-builder.d.ts

@@ -0,0 +1,24 @@
+import { type ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { IBridgeManifest } from '../schema/bridge-schema.js';
+export interface IBridgeBuildOptions {
+    projectRoot: string;
+    /** Optional pre-loaded inspection; built on the fly when absent. */
+    inspection?: ISharkcraftInspection;
+}
+export interface IBridgeBuildResult {
+    manifest: IBridgeManifest;
+    durationMs: number;
+}
+/**
+ * Build bridge edges from the code graph (file nodes) to asset
+ * registries (boundary rules, path conventions, templates).
+ *
+ * Inputs:
+ *   - graph store (must already exist; run `shrk graph index` first)
+ *   - inspection (defaults to `inspectSharkcraft({ cwd: projectRoot })`)
+ *
+ * Output: writes to `.sharkcraft/bridge/` with schema
+ * `sharkcraft.rule-graph/v1`.
+ */
+export declare function buildBridge(options: IBridgeBuildOptions): Promise<IBridgeBuildResult>;
+//# sourceMappingURL=bridge-builder.d.ts.map

package/dist/bridge/bridge-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-builder.d.ts","sourceRoot":"","sources":["../../src/bridge/bridge-builder.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAKlE,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAkJ7B"}

package/dist/bridge/bridge-builder.js

@@ -0,0 +1,208 @@
+import { createHash } from 'node:crypto';
+import { globToRegex } from '@shrkcrft/boundaries';
+import { EdgeKind, GraphStore, NodeKind, } from '@shrkcrft/graph';
+import { inspectSharkcraft, } from '@shrkcrft/inspector';
+import { BridgeStore } from "../store/bridge-store.js";
+import { deriveApplicability } from "./knowledge-rule-matching.js";
+const BRIDGE_SOURCE = 'rule-graph-bridge@v1';
+/**
+ * Build bridge edges from the code graph (file nodes) to asset
+ * registries (boundary rules, path conventions, templates).
+ *
+ * Inputs:
+ *   - graph store (must already exist; run `shrk graph index` first)
+ *   - inspection (defaults to `inspectSharkcraft({ cwd: projectRoot })`)
+ *
+ * Output: writes to `.sharkcraft/bridge/` with schema
+ * `sharkcraft.rule-graph/v1`.
+ */
+export async function buildBridge(options) {
+    const start = Date.now();
+    const { projectRoot } = options;
+    const graphStore = new GraphStore(projectRoot);
+    if (!graphStore.exists()) {
+        throw new Error("code-graph store missing. Run 'shrk graph index' before 'shrk rule-graph index'.");
+    }
+    const graph = graphStore.loadSnapshot();
+    const inspection = options.inspection ?? (await inspectSharkcraft({ cwd: projectRoot }));
+    const files = [];
+    for (const n of graph.nodes.values()) {
+        if (n.kind === NodeKind.File && n.path)
+            files.push(n);
+    }
+    const nodes = [];
+    const edges = [];
+    const sourceCounts = { rule: 0, path: 0, template: 0 };
+    /**
+     * Track which file ids have at least one `applies-rule` edge — this
+     * is the set that backs the §3.2 "bridge coverage" doctor check. We
+     * deliberately exclude `matches-path` and `covered-by-template` here
+     * (those signal location / generation, not policy).
+     */
+    const filesWithRule = new Set();
+    // ── Boundary rules ─────────────────────────────────────────────────
+    const boundaries = inspection.boundaryRegistry.list();
+    for (const b of boundaries) {
+        nodes.push({
+            id: `boundary:${b.id}`,
+            kind: NodeKind.Boundary,
+            label: b.title ?? b.id,
+            data: {
+                severity: b.severity ?? 'error',
+                ...(b.tags ? { tags: [...b.tags] } : {}),
+            },
+        });
+        const regexes = b.from.map((p) => globToRegex(p));
+        for (const f of files) {
+            if (!regexes.some((re) => re.test(f.path)))
+                continue;
+            edges.push(edge(f.id, `boundary:${b.id}`, EdgeKind.AppliesRule, {
+                source: 'boundary',
+                severity: b.severity ?? 'error',
+            }));
+            sourceCounts['rule'] += 1;
+            filesWithRule.add(f.id);
+        }
+    }
+    // ── Knowledge rules (IKnowledgeEntry type=rule) ────────────────────
+    // Heuristic bridge via metadata.appliesTo or tag-based fallback. See
+    // `deriveApplicability` for the rationale.
+    const knowledgeRules = inspection.ruleService.list();
+    for (const r of knowledgeRules) {
+        const applicability = deriveApplicability(r);
+        if (applicability.source === 'none')
+            continue;
+        nodes.push({
+            id: `rule:${r.id}`,
+            kind: NodeKind.Rule,
+            label: r.title ?? r.id,
+            data: {
+                applicabilitySource: applicability.source,
+                ...(r.tags ? { tags: [...r.tags] } : {}),
+                ...(r.priority ? { priority: r.priority } : {}),
+            },
+        });
+        const regexes = applicability.patterns.map((p) => globToRegex(p));
+        const tagSet = new Set(applicability.fileTags);
+        const severity = (r.priority === 'critical' || r.priority === 'high') ? 'error' : 'warning';
+        for (const f of files) {
+            const pathMatch = regexes.some((re) => re.test(f.path));
+            const tagMatch = tagSet.size > 0 && (f.tags ?? []).some((t) => tagSet.has(t));
+            if (!pathMatch && !tagMatch)
+                continue;
+            edges.push(edge(f.id, `rule:${r.id}`, EdgeKind.AppliesRule, {
+                source: 'knowledge',
+                severity,
+                via: pathMatch ? 'path' : 'tag',
+            }));
+            sourceCounts['rule'] += 1;
+            filesWithRule.add(f.id);
+        }
+    }
+    // ── Path conventions ───────────────────────────────────────────────
+    const paths = inspection.pathService.list();
+    for (const p of paths) {
+        const target = p.metadata?.path ?? '';
+        if (!target)
+            continue;
+        nodes.push({
+            id: `path:${p.id}`,
+            kind: NodeKind.Path,
+            label: p.title ?? p.id,
+            data: { target },
+        });
+        const prefix = target.replace(/\/+$/, '');
+        for (const f of files) {
+            if (!isUnderPrefix(f.path, prefix))
+                continue;
+            edges.push(edge(f.id, `path:${p.id}`, EdgeKind.MatchesPath, { prefix }));
+            sourceCounts['path'] += 1;
+        }
+    }
+    // ── Templates (string + invertible-function targetPath) ────────────
+    const templates = inspection.templateRegistry.list();
+    for (const t of templates) {
+        nodes.push({
+            id: `template:${t.id}`,
+            kind: NodeKind.Template,
+            label: t.name ?? t.id,
+        });
+        const pattern = resolveTemplatePattern(t);
+        if (!pattern)
+            continue;
+        const re = globToRegex(pattern);
+        for (const f of files) {
+            if (!re.test(f.path))
+                continue;
+            edges.push(edge(f.id, `template:${t.id}`, EdgeKind.CoveredByTemplate, { pattern }));
+            sourceCounts['template'] += 1;
+        }
+    }
+    const store = new BridgeStore(projectRoot);
+    const filesTotal = files.length;
+    const filesCoveredByRules = filesWithRule.size;
+    const manifest = store.writeSnapshot(nodes, edges, {
+        projectRoot,
+        lastBuiltAt: new Date().toISOString(),
+        lastBuildDurationMs: Date.now() - start,
+        nodesByKind: {},
+        edgesByKind: {},
+        sourceCounts,
+        filesTotal,
+        filesCoveredByRules,
+        filesUncoveredByRules: filesTotal - filesCoveredByRules,
+    });
+    return { manifest, durationMs: Date.now() - start };
+}
+function edge(from, to, kind, data) {
+    return {
+        id: createHash('sha1').update(`${from}|${to}|${kind}`).digest('hex'),
+        from,
+        to,
+        kind,
+        source: BRIDGE_SOURCE,
+        ...(data ? { data } : {}),
+    };
+}
+function isUnderPrefix(filePath, prefix) {
+    if (!prefix)
+        return false;
+    if (prefix === '.' || prefix === '/')
+        return true;
+    return filePath === prefix || filePath.startsWith(prefix + '/');
+}
+/**
+ * Invert a template's path resolver to a glob pattern by substituting
+ * `*` for every declared variable. Handles:
+ *   - string targetPath
+ *   - function targetPath called with { var: '*' } for each declared var
+ *   - first-file targetPath from files() / changes() resolvers
+ *
+ * Returns undefined when the template doesn't expose a single-pattern
+ * target (multi-file with divergent paths) or when the resolver throws.
+ */
+function resolveTemplatePattern(t) {
+    const dummy = {};
+    for (const v of t.variables ?? [])
+        dummy[v.name] = '*';
+    try {
+        if (typeof t.targetPath === 'string')
+            return t.targetPath;
+        if (typeof t.targetPath === 'function')
+            return t.targetPath(dummy);
+        if (t.files) {
+            const f = t.files(dummy);
+            if (f.length === 1)
+                return f[0]?.targetPath;
+        }
+        if (t.changes) {
+            const c = t.changes(dummy);
+            if (c.length > 0 && c[0])
+                return c[0].targetPath;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}

package/dist/bridge/knowledge-rule-matching.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Heuristic file matchers for IKnowledgeEntry-style rules.
+ *
+ * Rules in the knowledge model don't carry path patterns directly the
+ * way boundary rules do. The bridge needs to know "which files does
+ * this rule apply to?" — we derive that from two sources, in order:
+ *
+ *   1. **Explicit**: `rule.metadata.appliesTo` — an array of glob
+ *      patterns. Authoritative when present.
+ *   2. **Tag-based heuristics**: well-known tags map to file
+ *      patterns. For example a rule tagged `mcp` likely applies to
+ *      files under `packages/mcp-server/**`. The map is intentionally
+ *      conservative — when no tag matches, the rule is *not* bridged
+ *      (better silent than noisy).
+ *
+ * Authors who want predictable bridging set `metadata.appliesTo`.
+ */
+export interface IRuleApplicability {
+    /** Glob patterns to match against file paths. */
+    patterns: readonly string[];
+    /**
+     * When non-empty, the rule applies to every file whose `tags` array
+     * intersects this set. Currently used by `testing`-tagged rules.
+     */
+    fileTags: readonly string[];
+    /** How we derived the applicability — useful for diagnostics. */
+    source: 'metadata' | 'tags' | 'none';
+}
+export declare function deriveApplicability(rule: {
+    tags?: readonly string[];
+    metadata?: Readonly<Record<string, unknown>>;
+}): IRuleApplicability;
+//# sourceMappingURL=knowledge-rule-matching.d.ts.map

package/dist/bridge/knowledge-rule-matching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-rule-matching.d.ts","sourceRoot":"","sources":["../../src/bridge/knowledge-rule-matching.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAyBH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;OAGG;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,iEAAiE;IACjE,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;CACtC;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9C,GAAG,kBAAkB,CAwBrB"}

package/dist/bridge/knowledge-rule-matching.js

@@ -0,0 +1,65 @@
+/**
+ * Heuristic file matchers for IKnowledgeEntry-style rules.
+ *
+ * Rules in the knowledge model don't carry path patterns directly the
+ * way boundary rules do. The bridge needs to know "which files does
+ * this rule apply to?" — we derive that from two sources, in order:
+ *
+ *   1. **Explicit**: `rule.metadata.appliesTo` — an array of glob
+ *      patterns. Authoritative when present.
+ *   2. **Tag-based heuristics**: well-known tags map to file
+ *      patterns. For example a rule tagged `mcp` likely applies to
+ *      files under `packages/mcp-server/**`. The map is intentionally
+ *      conservative — when no tag matches, the rule is *not* bridged
+ *      (better silent than noisy).
+ *
+ * Authors who want predictable bridging set `metadata.appliesTo`.
+ */
+const TAG_PATTERNS = new Map([
+    // Engine packages.
+    ['mcp', ['packages/mcp-server/**']],
+    ['cli', ['packages/cli/**']],
+    ['dashboard', ['packages/dashboard/**', 'packages/dashboard-api/**']],
+    ['generator', ['packages/generator/**']],
+    ['importer', ['packages/importer/**']],
+    ['inspector', ['packages/inspector/**']],
+    ['packs', ['packages/packs/**']],
+    ['core', ['packages/core/**']],
+    // Asset categories.
+    ['boundaries', ['sharkcraft/boundaries.ts', 'packages/boundaries/**']],
+    ['rules', ['sharkcraft/rules.ts', 'packages/rules/**']],
+    ['paths', ['sharkcraft/paths.ts', 'packages/paths/**']],
+    ['templates', ['sharkcraft/templates.ts', 'packages/templates/**']],
+    ['pipelines', ['sharkcraft/pipelines.ts', 'packages/pipelines/**']],
+    ['presets', ['sharkcraft/presets.ts', 'packages/presets/**']],
+    // Cross-cutting concerns.
+    ['imports', ['packages/**/*.ts']],
+    ['testing', []], // signal-only; the bridge attaches via the file's `tags: test` separately
+    ['tests', []],
+]);
+export function deriveApplicability(rule) {
+    const explicit = rule.metadata?.['appliesTo'];
+    if (Array.isArray(explicit) && explicit.every((p) => typeof p === 'string')) {
+        return { patterns: explicit, fileTags: [], source: 'metadata' };
+    }
+    const tags = rule.tags ?? [];
+    const patterns = [];
+    const fileTags = [];
+    for (const tag of tags) {
+        if (tag === 'testing' || tag === 'tests') {
+            fileTags.push('test');
+            continue;
+        }
+        const mapped = TAG_PATTERNS.get(tag);
+        if (mapped) {
+            for (const p of mapped) {
+                if (!patterns.includes(p))
+                    patterns.push(p);
+            }
+        }
+    }
+    if (patterns.length === 0 && fileTags.length === 0) {
+        return { patterns: [], fileTags: [], source: 'none' };
+    }
+    return { patterns, fileTags, source: 'tags' };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './schema/bridge-schema.js';
+export * from './store/bridge-store.js';
+export * from './bridge/bridge-builder.js';
+export * from './bridge/knowledge-rule-matching.js';
+export * from './query/rule-graph-query-api.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":"AACA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// Public surface of @shrkcrft/rule-graph.
+export * from "./schema/bridge-schema.js";
+export * from "./store/bridge-store.js";
+export * from "./bridge/bridge-builder.js";
+export * from "./bridge/knowledge-rule-matching.js";
+export * from "./query/rule-graph-query-api.js";

package/dist/query/rule-graph-query-api.d.ts

@@ -0,0 +1,37 @@
+import { type IEdge, type IGraphSnapshot, type INode } from '@shrkcrft/graph';
+import type { IBridgeSnapshot } from '../schema/bridge-schema.js';
+export interface IBridgeEdgeHit {
+    edge: IEdge;
+    target: INode;
+}
+export interface IRuleGraphForFile {
+    fileNodeId: string;
+    path: string;
+    rules: readonly IBridgeEdgeHit[];
+    paths: readonly IBridgeEdgeHit[];
+    templates: readonly IBridgeEdgeHit[];
+}
+/**
+ * Query API over the merged code-graph + bridge-graph snapshots.
+ *
+ * Loaded once per request; reads are O(edges-touching-the-anchor) once
+ * the inbound + outbound indexes are built.
+ */
+export declare class RuleGraphQueryApi {
+    private readonly graphSnap;
+    private readonly bridgeSnap;
+    private readonly outByFrom;
+    private readonly inByTo;
+    private readonly mergedNodes;
+    private readonly fileByPath;
+    constructor(graphSnap: IGraphSnapshot, bridgeSnap: IBridgeSnapshot);
+    static fromStores(projectRoot: string): RuleGraphQueryApi;
+    static missingDescription(projectRoot: string): string | undefined;
+    /** Resolve a file path to its file node, or undefined. */
+    findFile(path: string): INode | undefined;
+    /** Everything that applies to a file: rules, paths, templates. */
+    forFile(path: string): IRuleGraphForFile | undefined;
+    /** Files that a given rule / path / template applies to. */
+    filesFor(bridgeNodeId: string): readonly INode[];
+}
+//# sourceMappingURL=rule-graph-query-api.d.ts.map

package/dist/query/rule-graph-query-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-graph-query-api.d.ts","sourceRoot":"","sources":["../../src/query/rule-graph-query-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,KAAK,EACV,KAAK,cAAc,EACnB,KAAK,KAAK,EACX,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IACjC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IACjC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAO1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAP7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;gBAGrC,SAAS,EAAE,cAAc,EACzB,UAAU,EAAE,eAAe;IAyB9C,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB;IAMzD,MAAM,CAAC,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQlE,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAIzC,kEAAkE;IAClE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAiBpD,4DAA4D;IAC5D,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,KAAK,EAAE;CAiBjD"}

package/dist/query/rule-graph-query-api.js

@@ -0,0 +1,107 @@
+import { EdgeKind, GraphStore, } from '@shrkcrft/graph';
+import { BridgeStore } from "../store/bridge-store.js";
+/**
+ * Query API over the merged code-graph + bridge-graph snapshots.
+ *
+ * Loaded once per request; reads are O(edges-touching-the-anchor) once
+ * the inbound + outbound indexes are built.
+ */
+export class RuleGraphQueryApi {
+    graphSnap;
+    bridgeSnap;
+    outByFrom;
+    inByTo;
+    mergedNodes;
+    fileByPath;
+    constructor(graphSnap, bridgeSnap) {
+        this.graphSnap = graphSnap;
+        this.bridgeSnap = bridgeSnap;
+        const out = new Map();
+        const inn = new Map();
+        for (const e of [...graphSnap.edges.values(), ...bridgeSnap.edges.values()]) {
+            const o = out.get(e.from);
+            if (o)
+                o.push(e);
+            else
+                out.set(e.from, [e]);
+            const i = inn.get(e.to);
+            if (i)
+                i.push(e);
+            else
+                inn.set(e.to, [e]);
+        }
+        const merged = new Map();
+        for (const n of graphSnap.nodes.values())
+            merged.set(n.id, n);
+        for (const n of bridgeSnap.nodes.values())
+            merged.set(n.id, n);
+        const fileByPath = new Map();
+        for (const n of graphSnap.nodes.values()) {
+            if (n.path && n.kind === 'file')
+                fileByPath.set(n.path, n);
+        }
+        this.outByFrom = out;
+        this.inByTo = inn;
+        this.mergedNodes = merged;
+        this.fileByPath = fileByPath;
+    }
+    static fromStores(projectRoot) {
+        const g = new GraphStore(projectRoot).loadSnapshot();
+        const b = new BridgeStore(projectRoot).loadSnapshot();
+        return new RuleGraphQueryApi(g, b);
+    }
+    static missingDescription(projectRoot) {
+        const g = new GraphStore(projectRoot).exists();
+        const b = new BridgeStore(projectRoot).exists();
+        if (!g)
+            return "Code-graph store missing. Run 'shrk graph index' then 'shrk rule-graph index'.";
+        if (!b)
+            return "Bridge store missing. Run 'shrk rule-graph index'.";
+        return undefined;
+    }
+    /** Resolve a file path to its file node, or undefined. */
+    findFile(path) {
+        return this.fileByPath.get(path);
+    }
+    /** Everything that applies to a file: rules, paths, templates. */
+    forFile(path) {
+        const file = this.findFile(path);
+        if (!file)
+            return undefined;
+        const out = this.outByFrom.get(file.id) ?? [];
+        const rules = [];
+        const paths = [];
+        const templates = [];
+        for (const e of out) {
+            const target = this.mergedNodes.get(e.to);
+            if (!target)
+                continue;
+            if (e.kind === EdgeKind.AppliesRule)
+                rules.push({ edge: e, target });
+            else if (e.kind === EdgeKind.MatchesPath)
+                paths.push({ edge: e, target });
+            else if (e.kind === EdgeKind.CoveredByTemplate)
+                templates.push({ edge: e, target });
+        }
+        return { fileNodeId: file.id, path, rules, paths, templates };
+    }
+    /** Files that a given rule / path / template applies to. */
+    filesFor(bridgeNodeId) {
+        const inn = this.inByTo.get(bridgeNodeId) ?? [];
+        const out = [];
+        const seen = new Set();
+        for (const e of inn) {
+            if (e.kind !== EdgeKind.AppliesRule &&
+                e.kind !== EdgeKind.MatchesPath &&
+                e.kind !== EdgeKind.CoveredByTemplate)
+                continue;
+            if (seen.has(e.from))
+                continue;
+            seen.add(e.from);
+            const n = this.mergedNodes.get(e.from);
+            if (n)
+                out.push(n);
+        }
+        return out;
+    }
+}

package/dist/schema/bridge-schema.d.ts

@@ -0,0 +1,32 @@
+import type { IEdge, INode } from '@shrkcrft/graph';
+export declare const RULE_GRAPH_SCHEMA: "sharkcraft.rule-graph/v1";
+export type RuleGraphSchemaVersion = typeof RULE_GRAPH_SCHEMA;
+export interface IBridgeManifest {
+    schema: RuleGraphSchemaVersion;
+    projectRoot: string;
+    lastBuiltAt: string;
+    lastBuildDurationMs: number;
+    /** SHA-256 of the bridge store's JSONL files. */
+    digest: string;
+    /** Per-kind counters at build time. */
+    nodesByKind: Readonly<Record<string, number>>;
+    edgesByKind: Readonly<Record<string, number>>;
+    /** Counters by bridge source (rule / path / template). */
+    sourceCounts: Readonly<Record<string, number>>;
+    /**
+     * Coverage of the file set by `applies-rule` edges (boundaries +
+     * knowledge rules). Templates and path conventions are NOT counted —
+     * the roadmap (§3.2) defines coverage gap specifically as "files with
+     * no applicable rule". Optional for forward-compat with manifests
+     * written before the field existed.
+     */
+    filesTotal?: number;
+    filesCoveredByRules?: number;
+    filesUncoveredByRules?: number;
+}
+export interface IBridgeSnapshot {
+    manifest: IBridgeManifest;
+    nodes: ReadonlyMap<string, INode>;
+    edges: ReadonlyMap<string, IEdge>;
+}
+//# sourceMappingURL=bridge-schema.d.ts.map

package/dist/schema/bridge-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-schema.d.ts","sourceRoot":"","sources":["../../src/schema/bridge-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAEpD,eAAO,MAAM,iBAAiB,EAAG,0BAAmC,CAAC;AAErE,MAAM,MAAM,sBAAsB,GAAG,OAAO,iBAAiB,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,0DAA0D;IAC1D,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CACnC"}

package/dist/schema/bridge-schema.js

@@ -0,0 +1 @@
+export const RULE_GRAPH_SCHEMA = 'sharkcraft.rule-graph/v1';

package/dist/store/bridge-store.d.ts

@@ -0,0 +1,19 @@
+import type { IEdge, INode } from '@shrkcrft/graph';
+import { type IBridgeManifest, type IBridgeSnapshot } from '../schema/bridge-schema.js';
+/**
+ * On-disk store for bridge nodes + edges produced by `@shrkcrft/rule-graph`.
+ *
+ * Lives at `<root>/.sharkcraft/bridge/` so a `shrk graph index` rebuild of
+ * the code graph does not stomp on bridge data. Both stores merge in
+ * memory at query time.
+ */
+export declare class BridgeStore {
+    private readonly projectRoot;
+    readonly storeDir: string;
+    constructor(projectRoot: string);
+    exists(): boolean;
+    clear(): void;
+    writeSnapshot(nodes: readonly INode[], edges: readonly IEdge[], partial: Omit<IBridgeManifest, 'schema' | 'digest'>): IBridgeManifest;
+    loadSnapshot(): IBridgeSnapshot;
+}
+//# sourceMappingURL=bridge-store.d.ts.map

package/dist/store/bridge-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-store.d.ts","sourceRoot":"","sources":["../../src/store/bridge-store.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAMpC;;;;;;GAMG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,WAAW;IAFxC,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAEJ,WAAW,EAAE,MAAM;IAIhD,MAAM,IAAI,OAAO;IAIjB,KAAK,IAAI,IAAI;IAMb,aAAa,CACX,KAAK,EAAE,SAAS,KAAK,EAAE,EACvB,KAAK,EAAE,SAAS,KAAK,EAAE,EACvB,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,QAAQ,CAAC,GAClD,eAAe;IAoClB,YAAY,IAAI,eAAe;CAoChC"}

package/dist/store/bridge-store.js

@@ -0,0 +1,145 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from 'node:fs';
+import * as nodePath from 'node:path';
+import { RULE_GRAPH_SCHEMA, } from "../schema/bridge-schema.js";
+const NODES_DIR = 'nodes';
+const EDGES_DIR = 'edges';
+const META_FILE = 'meta.json';
+/**
+ * On-disk store for bridge nodes + edges produced by `@shrkcrft/rule-graph`.
+ *
+ * Lives at `<root>/.sharkcraft/bridge/` so a `shrk graph index` rebuild of
+ * the code graph does not stomp on bridge data. Both stores merge in
+ * memory at query time.
+ */
+export class BridgeStore {
+    projectRoot;
+    storeDir;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+        this.storeDir = nodePath.join(projectRoot, '.sharkcraft', 'bridge');
+    }
+    exists() {
+        return existsSync(nodePath.join(this.storeDir, META_FILE));
+    }
+    clear() {
+        if (existsSync(this.storeDir)) {
+            rmSync(this.storeDir, { recursive: true, force: true });
+        }
+    }
+    writeSnapshot(nodes, edges, partial) {
+        const nodesDir = nodePath.join(this.storeDir, NODES_DIR);
+        const edgesDir = nodePath.join(this.storeDir, EDGES_DIR);
+        if (existsSync(nodesDir))
+            rmSync(nodesDir, { recursive: true, force: true });
+        if (existsSync(edgesDir))
+            rmSync(edgesDir, { recursive: true, force: true });
+        mkdirSync(nodesDir, { recursive: true });
+        mkdirSync(edgesDir, { recursive: true });
+        const nodesByKind = bucket(nodes, (n) => n.kind);
+        const edgesByKind = bucket(edges, (e) => e.kind);
+        const nodeCounts = {};
+        const edgeCounts = {};
+        for (const [kind, list] of Object.entries(nodesByKind)) {
+            list.sort((a, b) => a.id.localeCompare(b.id));
+            writeJsonl(nodePath.join(nodesDir, `${kind}.jsonl`), list);
+            nodeCounts[kind] = list.length;
+        }
+        for (const [kind, list] of Object.entries(edgesByKind)) {
+            list.sort((a, b) => a.id.localeCompare(b.id));
+            writeJsonl(nodePath.join(edgesDir, `${kind}.jsonl`), list);
+            edgeCounts[kind] = list.length;
+        }
+        const digest = computeDigest(this.storeDir);
+        const manifest = {
+            schema: RULE_GRAPH_SCHEMA,
+            digest,
+            ...partial,
+            nodesByKind: nodeCounts,
+            edgesByKind: edgeCounts,
+        };
+        writeFileSync(nodePath.join(this.storeDir, META_FILE), JSON.stringify(manifest, null, 2));
+        return manifest;
+    }
+    loadSnapshot() {
+        if (!this.exists()) {
+            throw new Error(`bridge store not found under ${this.storeDir}. Run 'shrk rule-graph index'.`);
+        }
+        const manifest = JSON.parse(readFileSync(nodePath.join(this.storeDir, META_FILE), 'utf8'));
+        if (manifest.schema !== RULE_GRAPH_SCHEMA) {
+            throw new Error(`bridge schema mismatch: store=${manifest.schema}, expected=${RULE_GRAPH_SCHEMA}.`);
+        }
+        const nodes = new Map();
+        const nodesDir = nodePath.join(this.storeDir, NODES_DIR);
+        if (existsSync(nodesDir)) {
+            for (const fname of readdirSync(nodesDir)) {
+                if (!fname.endsWith('.jsonl'))
+                    continue;
+                for (const row of readJsonl(nodePath.join(nodesDir, fname))) {
+                    nodes.set(row.id, row);
+                }
+            }
+        }
+        const edges = new Map();
+        const edgesDir = nodePath.join(this.storeDir, EDGES_DIR);
+        if (existsSync(edgesDir)) {
+            for (const fname of readdirSync(edgesDir)) {
+                if (!fname.endsWith('.jsonl'))
+                    continue;
+                for (const row of readJsonl(nodePath.join(edgesDir, fname))) {
+                    edges.set(row.id, row);
+                }
+            }
+        }
+        return { manifest, nodes, edges };
+    }
+}
+function bucket(list, key) {
+    const out = {};
+    for (const item of list) {
+        const k = key(item);
+        if (!out[k])
+            out[k] = [];
+        out[k].push(item);
+    }
+    return out;
+}
+function writeJsonl(path, rows) {
+    const body = rows.map((r) => JSON.stringify(r)).join('\n');
+    writeFileSync(path, body.length > 0 ? body + '\n' : '');
+}
+function readJsonl(path) {
+    const raw = readFileSync(path, 'utf8');
+    if (!raw)
+        return [];
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        out.push(JSON.parse(t));
+    }
+    return out;
+}
+function computeDigest(storeDir) {
+    const hash = createHash('sha256');
+    const targets = [];
+    for (const sub of [NODES_DIR, EDGES_DIR]) {
+        const dir = nodePath.join(storeDir, sub);
+        if (!existsSync(dir))
+            continue;
+        for (const fname of readdirSync(dir).sort()) {
+            if (!fname.endsWith('.jsonl'))
+                continue;
+            targets.push(nodePath.join(dir, fname));
+        }
+    }
+    targets.sort();
+    for (const t of targets) {
+        hash.update(nodePath.relative(storeDir, t));
+        hash.update('\0');
+        hash.update(readFileSync(t));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@shrkcrft/rule-graph",
+  "version": "0.1.0-alpha.10",
+  "description": "SharkCraft rule-graph: bridges code-graph file nodes to rules / paths / templates / boundaries so 'which assets apply to this file?' is a 1-hop query.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sharkcraft/sharkcraft.git",
+    "directory": "packages/rule-graph"
+  },
+  "homepage": "https://github.com/sharkcraft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/sharkcraft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "rule-graph",
+    "bridge",
+    "code-intelligence"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.10",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.10",
+    "@shrkcrft/graph": "^0.1.0-alpha.10",
+    "@shrkcrft/inspector": "^0.1.0-alpha.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}