@shrkcrft/graph 0.1.0-alpha.10

package/dist/query/cycle-detection.js

@@ -0,0 +1,135 @@
+import { EdgeKind } from "../schema/edge-kind.js";
+/**
+ * Find every import cycle in the file-import directed graph. Returns
+ * one entry per SCC of size ≥ 2. Iterative Tarjan SCC over the
+ * `imports-file` subgraph; O(V+E) and stack-safe.
+ *
+ * `pathById` is optional — when supplied, the returned `paths` array
+ * is populated so callers don't have to re-resolve file ids.
+ */
+export function findFileCycles(nodes, edges, pathById) {
+    const adj = buildFileAdjacency(nodes, edges);
+    const sccs = stronglyConnectedComponentsIterative(adj);
+    const out = [];
+    for (const scc of sccs) {
+        if (scc.length < 2)
+            continue;
+        const cycle = {
+            nodeIds: [...scc],
+            size: scc.length,
+        };
+        if (pathById) {
+            cycle.paths = scc.map((id) => pathById.get(id) ?? id.replace(/^file:/, ''));
+        }
+        out.push(cycle);
+    }
+    // Stable order: by size DESC, then by first id ASC. Makes "show me
+    // the worst cycle first" deterministic across runs.
+    out.sort((a, b) => {
+        if (b.size !== a.size)
+            return b.size - a.size;
+        return (a.nodeIds[0] ?? '').localeCompare(b.nodeIds[0] ?? '');
+    });
+    return out;
+}
+/**
+ * Roll-up over `findFileCycles` results. Kept for downstream callers
+ * (the indexer, doctor) that only care about counts.
+ */
+export function summarizeCycles(nodes, edges) {
+    const cycles = findFileCycles(nodes, edges);
+    let largestCycleSize = 0;
+    let filesInCycles = 0;
+    for (const c of cycles) {
+        if (c.size > largestCycleSize)
+            largestCycleSize = c.size;
+        filesInCycles += c.size;
+    }
+    return {
+        cycleCount: cycles.length,
+        largestCycleSize,
+        filesInCycles,
+    };
+}
+function buildFileAdjacency(nodes, edges) {
+    const fileIds = new Set();
+    for (const n of nodes) {
+        if (n.id.startsWith('file:'))
+            fileIds.add(n.id);
+    }
+    const adj = new Map();
+    for (const id of fileIds)
+        adj.set(id, []);
+    for (const e of edges) {
+        if (e.kind !== EdgeKind.ImportsFile)
+            continue;
+        if (!fileIds.has(e.from) || !fileIds.has(e.to))
+            continue;
+        adj.get(e.from).push(e.to);
+    }
+    return adj;
+}
+/**
+ * Iterative Tarjan's strongly connected components. Returns one array
+ * per SCC; singletons are included so callers that care about all of
+ * them (e.g. `IGraphQueryApi.cycles()` once that ships) can filter
+ * themselves. Tarjan is single-pass O(V+E), and unlike the recursive
+ * form this version doesn't blow the stack on long import chains.
+ */
+function stronglyConnectedComponentsIterative(adj) {
+    const nodeIds = [...adj.keys()];
+    const indices = new Map();
+    const lowlinks = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const result = [];
+    let index = 0;
+    for (const start of nodeIds) {
+        if (indices.has(start))
+            continue;
+        const callStack = [{ v: start, iter: 0 }];
+        indices.set(start, index);
+        lowlinks.set(start, index);
+        index += 1;
+        stack.push(start);
+        onStack.add(start);
+        while (callStack.length > 0) {
+            const top = callStack[callStack.length - 1];
+            const successors = adj.get(top.v) ?? [];
+            if (top.iter < successors.length) {
+                const w = successors[top.iter];
+                top.iter += 1;
+                if (!indices.has(w)) {
+                    indices.set(w, index);
+                    lowlinks.set(w, index);
+                    index += 1;
+                    stack.push(w);
+                    onStack.add(w);
+                    callStack.push({ v: w, iter: 0 });
+                }
+                else if (onStack.has(w)) {
+                    lowlinks.set(top.v, Math.min(lowlinks.get(top.v), indices.get(w)));
+                }
+            }
+            else {
+                if (lowlinks.get(top.v) === indices.get(top.v)) {
+                    const scc = [];
+                    while (true) {
+                        const w = stack.pop();
+                        onStack.delete(w);
+                        scc.push(w);
+                        if (w === top.v)
+                            break;
+                    }
+                    result.push(scc);
+                }
+                callStack.pop();
+                if (callStack.length > 0) {
+                    const parent = callStack[callStack.length - 1];
+                    lowlinks.set(parent.v, Math.min(lowlinks.get(parent.v), lowlinks.get(top.v)));
+                }
+            }
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,87 @@
+import type { IEdge } from '../schema/edge.js';
+import type { IGraphSnapshot } from '../schema/graph-snapshot.js';
+import type { INode } from '../schema/node.js';
+import { type IFileCycle } from './cycle-detection.js';
+export interface IGraphStatus {
+    exists: boolean;
+    state: 'fresh' | 'stale' | 'missing' | 'corrupt';
+    fileCount: number;
+    nodeCount: number;
+    edgeCount: number;
+    lastIndexedAt?: string;
+    digestOk?: boolean;
+}
+export interface IGraphNeighbours {
+    node: INode;
+    /** Outgoing edges (this → other). */
+    out: readonly {
+        edge: IEdge;
+        target: INode | {
+            id: string;
+            resolved: false;
+        };
+    }[];
+    /** Incoming edges (other → this). */
+    in: readonly {
+        edge: IEdge;
+        source: INode | {
+            id: string;
+            resolved: false;
+        };
+    }[];
+}
+export interface IFindSymbolOptions {
+    /** Filter by symbol package. */
+    package?: string;
+    /** Hard cap on returned matches. Default 50. */
+    limit?: number;
+    /** Exact match required (no case-insensitive / prefix matching). */
+    exact?: boolean;
+}
+/**
+ * Read-only query layer over an in-memory graph snapshot.
+ *
+ * The CLI/MCP layer constructs one instance per request from a freshly
+ * loaded snapshot. The query API never writes; only the indexer does.
+ */
+export declare class GraphQueryApi {
+    private readonly snap;
+    private readonly fileByPath;
+    private readonly symbolByName;
+    private readonly outByFrom;
+    private readonly inByTo;
+    constructor(snap: IGraphSnapshot);
+    /** Load a snapshot from disk and construct the query API. */
+    static fromStore(projectRoot: string): GraphQueryApi;
+    status(): IGraphStatus;
+    findFile(path: string): INode | undefined;
+    /** Iterate every file node in the snapshot. Cheap; in-memory walk. */
+    allFiles(): IterableIterator<INode>;
+    /** Iterate every package node in the snapshot. */
+    allPackages(): IterableIterator<INode>;
+    findSymbol(name: string, opts?: IFindSymbolOptions): readonly INode[];
+    /** Files that import `nodeId` (directly). */
+    importersOf(nodeId: string): readonly INode[];
+    /** Files imported by `nodeId` (directly). Resolves only File-kind targets. */
+    importsFrom(nodeId: string): readonly INode[];
+    /** Symbols declared by a given file. */
+    symbolsIn(fileNodeId: string): readonly INode[];
+    /** Files that *call* the given symbol (Wave 3 — file-level precision). */
+    callersOf(symbolNodeId: string): readonly INode[];
+    /** Files that *reference* the given symbol (any use, including calls). */
+    referencesOf(symbolNodeId: string): readonly INode[];
+    /** Packages that this package depends on (PackageDependsOn). */
+    packageDeps(packageName: string): readonly INode[];
+    /**
+     * Every import cycle in the snapshot (SCC ≥ 2). Recomputes from the
+     * in-memory snapshot — file paths are filled in from the snapshot's
+     * file nodes. Sorted by size descending then id ascending so callers
+     * get a stable "worst first" ordering. Roadmap §3.1 long-promised
+     * this method on the query API; backed by `findFileCycles` so the
+     * indexer's manifest counts stay consistent with what callers see.
+     */
+    cycles(): readonly IFileCycle[];
+    /** 1-hop neighbours of a node, both in + out. */
+    neighbours(nodeId: string): IGraphNeighbours | undefined;
+}
+//# sourceMappingURL=query-api.d.ts.map

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

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

package/dist/query/query-api.js

@@ -0,0 +1,232 @@
+import { EdgeKind } from "../schema/edge-kind.js";
+import { NodeKind } from "../schema/node-kind.js";
+import { GraphStore } from "../store/graph-store.js";
+import { findFileCycles } from "./cycle-detection.js";
+/**
+ * Read-only query layer over an in-memory graph snapshot.
+ *
+ * The CLI/MCP layer constructs one instance per request from a freshly
+ * loaded snapshot. The query API never writes; only the indexer does.
+ */
+export class GraphQueryApi {
+    snap;
+    fileByPath;
+    symbolByName;
+    outByFrom;
+    inByTo;
+    constructor(snap) {
+        this.snap = snap;
+        const fileByPath = new Map();
+        const symbolByName = new Map();
+        for (const n of snap.nodes.values()) {
+            if (n.kind === NodeKind.File && n.path) {
+                fileByPath.set(n.path, n);
+            }
+            else if (n.kind === NodeKind.Symbol) {
+                const arr = symbolByName.get(n.label);
+                if (arr)
+                    arr.push(n);
+                else
+                    symbolByName.set(n.label, [n]);
+            }
+        }
+        const outByFrom = new Map();
+        const inByTo = new Map();
+        for (const e of snap.edges.values()) {
+            const ofrom = outByFrom.get(e.from);
+            if (ofrom)
+                ofrom.push(e);
+            else
+                outByFrom.set(e.from, [e]);
+            const ito = inByTo.get(e.to);
+            if (ito)
+                ito.push(e);
+            else
+                inByTo.set(e.to, [e]);
+        }
+        this.fileByPath = fileByPath;
+        this.symbolByName = symbolByName;
+        this.outByFrom = outByFrom;
+        this.inByTo = inByTo;
+    }
+    /** Load a snapshot from disk and construct the query API. */
+    static fromStore(projectRoot) {
+        const store = new GraphStore(projectRoot);
+        return new GraphQueryApi(store.loadSnapshot());
+    }
+    status() {
+        const m = this.snap.manifest;
+        return {
+            exists: true,
+            state: 'fresh',
+            fileCount: m.filesIndexed,
+            nodeCount: this.snap.nodes.size,
+            edgeCount: this.snap.edges.size,
+            lastIndexedAt: m.lastIndexedAt,
+        };
+    }
+    findFile(path) {
+        return this.fileByPath.get(path);
+    }
+    /** Iterate every file node in the snapshot. Cheap; in-memory walk. */
+    *allFiles() {
+        for (const n of this.fileByPath.values())
+            yield n;
+    }
+    /** Iterate every package node in the snapshot. */
+    *allPackages() {
+        for (const n of this.snap.nodes.values()) {
+            if (n.kind === NodeKind.Package)
+                yield n;
+        }
+    }
+    findSymbol(name, opts = {}) {
+        const limit = opts.limit ?? 50;
+        if (opts.exact !== false) {
+            const exact = this.symbolByName.get(name) ?? [];
+            return filterByPackage(exact, opts.package).slice(0, limit);
+        }
+        const lower = name.toLowerCase();
+        const out = [];
+        for (const [k, list] of this.symbolByName) {
+            if (!k.toLowerCase().includes(lower))
+                continue;
+            for (const n of list)
+                out.push(n);
+            if (out.length >= limit * 2)
+                break;
+        }
+        return filterByPackage(out, opts.package).slice(0, limit);
+    }
+    /** Files that import `nodeId` (directly). */
+    importersOf(nodeId) {
+        const edges = this.inByTo.get(nodeId) ?? [];
+        const out = [];
+        for (const e of edges) {
+            if (e.kind !== EdgeKind.ImportsFile)
+                continue;
+            const n = this.snap.nodes.get(e.from);
+            if (n)
+                out.push(n);
+        }
+        return out;
+    }
+    /** Files imported by `nodeId` (directly). Resolves only File-kind targets. */
+    importsFrom(nodeId) {
+        const edges = this.outByFrom.get(nodeId) ?? [];
+        const out = [];
+        for (const e of edges) {
+            if (e.kind !== EdgeKind.ImportsFile)
+                continue;
+            const n = this.snap.nodes.get(e.to);
+            if (n)
+                out.push(n);
+        }
+        return out;
+    }
+    /** Symbols declared by a given file. */
+    symbolsIn(fileNodeId) {
+        const edges = this.outByFrom.get(fileNodeId) ?? [];
+        const out = [];
+        for (const e of edges) {
+            if (e.kind !== EdgeKind.DeclaresSymbol)
+                continue;
+            const n = this.snap.nodes.get(e.to);
+            if (n)
+                out.push(n);
+        }
+        return out;
+    }
+    /** Files that *call* the given symbol (Wave 3 — file-level precision). */
+    callersOf(symbolNodeId) {
+        const edges = this.inByTo.get(symbolNodeId) ?? [];
+        const out = [];
+        for (const e of edges) {
+            if (e.kind !== EdgeKind.CallsSymbol)
+                continue;
+            const n = this.snap.nodes.get(e.from);
+            if (n)
+                out.push(n);
+        }
+        return out;
+    }
+    /** Files that *reference* the given symbol (any use, including calls). */
+    referencesOf(symbolNodeId) {
+        const edges = this.inByTo.get(symbolNodeId) ?? [];
+        const out = [];
+        const seen = new Set();
+        for (const e of edges) {
+            if (e.kind !== EdgeKind.ReferencesSymbol && e.kind !== EdgeKind.CallsSymbol)
+                continue;
+            if (seen.has(e.from))
+                continue;
+            seen.add(e.from);
+            const n = this.snap.nodes.get(e.from);
+            if (n)
+                out.push(n);
+        }
+        return out;
+    }
+    /** Packages that this package depends on (PackageDependsOn). */
+    packageDeps(packageName) {
+        const edges = this.outByFrom.get(`package:${packageName}`) ?? [];
+        const out = [];
+        for (const e of edges) {
+            if (e.kind !== EdgeKind.PackageDependsOn)
+                continue;
+            const n = this.snap.nodes.get(e.to);
+            if (n)
+                out.push(n);
+        }
+        return out;
+    }
+    /**
+     * Every import cycle in the snapshot (SCC ≥ 2). Recomputes from the
+     * in-memory snapshot — file paths are filled in from the snapshot's
+     * file nodes. Sorted by size descending then id ascending so callers
+     * get a stable "worst first" ordering. Roadmap §3.1 long-promised
+     * this method on the query API; backed by `findFileCycles` so the
+     * indexer's manifest counts stay consistent with what callers see.
+     */
+    cycles() {
+        const pathById = new Map();
+        for (const [id, n] of this.snap.nodes) {
+            if (n.kind === NodeKind.File && n.path)
+                pathById.set(id, n.path);
+        }
+        return findFileCycles([...this.snap.nodes.values()], [...this.snap.edges.values()], pathById);
+    }
+    /** 1-hop neighbours of a node, both in + out. */
+    neighbours(nodeId) {
+        const node = this.snap.nodes.get(nodeId);
+        if (!node)
+            return undefined;
+        const outEdges = this.outByFrom.get(nodeId) ?? [];
+        const inEdges = this.inByTo.get(nodeId) ?? [];
+        return {
+            node,
+            out: outEdges.map((edge) => {
+                const target = this.snap.nodes.get(edge.to);
+                return { edge, target: target ?? { id: edge.to, resolved: false } };
+            }),
+            in: inEdges.map((edge) => {
+                const source = this.snap.nodes.get(edge.from);
+                return { edge, source: source ?? { id: edge.from, resolved: false } };
+            }),
+        };
+    }
+}
+function filterByPackage(list, pkg) {
+    if (!pkg)
+        return [...list];
+    const prefix = pkg + '/';
+    return list.filter((n) => {
+        if (!n.path)
+            return false;
+        // Workspace packages live at `packages/<slug>/...`. Without a path-
+        // alias map at query time, the cheap proxy is "path starts with the
+        // package directory prefix". Caller passes the directory, not the
+        // package name, for now.
+        return n.path === pkg || n.path.startsWith(prefix);
+    });
+}

package/dist/schema/edge-kind.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Edge kinds in the code graph.
+ *
+ * MVP populates the "Code structure" group. Symbol-reference edges are
+ * reserved for Wave 3; bridge edges are reserved for Wave 2.
+ */
+export declare enum EdgeKind {
+    ImportsFile = "imports-file",
+    DeclaresSymbol = "declares-symbol",
+    ReExportsSymbol = "re-exports-symbol",
+    BelongsToPackage = "belongs-to-package",
+    PackageDependsOn = "package-depends-on",
+    ReferencesSymbol = "references-symbol",
+    CallsSymbol = "calls-symbol",
+    ExtendsSymbol = "extends-symbol",
+    ImplementsSymbol = "implements-symbol",
+    AppliesRule = "applies-rule",
+    ViolatesBoundary = "violates-boundary",
+    MatchesPath = "matches-path",
+    CoveredByTemplate = "covered-by-template",
+    CoveredByPipeline = "covered-by-pipeline",
+    ContributedByPack = "contributed-by-pack",
+    ContainsKnowledge = "contains-knowledge",
+    /** File declares a framework entity (e.g. controller/component/module). */
+    FrameworkDeclares = "framework-declares",
+    /** Controller / route handler → HTTP route. */
+    HandlesRoute = "handles-route",
+    /** Component → hook it uses. */
+    UsesHook = "uses-hook"
+}
+//# sourceMappingURL=edge-kind.d.ts.map

package/dist/schema/edge-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-kind.d.ts","sourceRoot":"","sources":["../../src/schema/edge-kind.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,oBAAY,QAAQ;IAElB,WAAW,iBAAiB;IAC5B,cAAc,oBAAoB;IAClC,eAAe,sBAAsB;IACrC,gBAAgB,uBAAuB;IACvC,gBAAgB,uBAAuB;IAGvC,gBAAgB,sBAAsB;IACtC,WAAW,iBAAiB;IAC5B,aAAa,mBAAmB;IAChC,gBAAgB,sBAAsB;IAGtC,WAAW,iBAAiB;IAC5B,gBAAgB,sBAAsB;IACtC,WAAW,iBAAiB;IAC5B,iBAAiB,wBAAwB;IACzC,iBAAiB,wBAAwB;IACzC,iBAAiB,wBAAwB;IACzC,iBAAiB,uBAAuB;IAGxC,2EAA2E;IAC3E,iBAAiB,uBAAuB;IACxC,+CAA+C;IAC/C,YAAY,kBAAkB;IAC9B,gCAAgC;IAChC,QAAQ,cAAc;CACvB"}

package/dist/schema/edge-kind.js

@@ -0,0 +1,35 @@
+/**
+ * Edge kinds in the code graph.
+ *
+ * MVP populates the "Code structure" group. Symbol-reference edges are
+ * reserved for Wave 3; bridge edges are reserved for Wave 2.
+ */
+export var EdgeKind;
+(function (EdgeKind) {
+    // ── Code structure (MVP) ─────────────────────────────────────────────
+    EdgeKind["ImportsFile"] = "imports-file";
+    EdgeKind["DeclaresSymbol"] = "declares-symbol";
+    EdgeKind["ReExportsSymbol"] = "re-exports-symbol";
+    EdgeKind["BelongsToPackage"] = "belongs-to-package";
+    EdgeKind["PackageDependsOn"] = "package-depends-on";
+    // ── Symbol references (reserved, Wave 3) ─────────────────────────────
+    EdgeKind["ReferencesSymbol"] = "references-symbol";
+    EdgeKind["CallsSymbol"] = "calls-symbol";
+    EdgeKind["ExtendsSymbol"] = "extends-symbol";
+    EdgeKind["ImplementsSymbol"] = "implements-symbol";
+    // ── Bridge to assets (reserved, Wave 2) ──────────────────────────────
+    EdgeKind["AppliesRule"] = "applies-rule";
+    EdgeKind["ViolatesBoundary"] = "violates-boundary";
+    EdgeKind["MatchesPath"] = "matches-path";
+    EdgeKind["CoveredByTemplate"] = "covered-by-template";
+    EdgeKind["CoveredByPipeline"] = "covered-by-pipeline";
+    EdgeKind["ContributedByPack"] = "contributed-by-pack";
+    EdgeKind["ContainsKnowledge"] = "contains-knowledge";
+    // ── Framework-aware edges (Wave 7) ───────────────────────────────────
+    /** File declares a framework entity (e.g. controller/component/module). */
+    EdgeKind["FrameworkDeclares"] = "framework-declares";
+    /** Controller / route handler → HTTP route. */
+    EdgeKind["HandlesRoute"] = "handles-route";
+    /** Component → hook it uses. */
+    EdgeKind["UsesHook"] = "uses-hook";
+})(EdgeKind || (EdgeKind = {}));

package/dist/schema/edge.d.ts

@@ -0,0 +1,22 @@
+import type { EdgeKind } from './edge-kind.js';
+/**
+ * An edge in the code graph.
+ *
+ * `id` is deterministic: sha1(from || '|' || to || '|' || kind). Two
+ * extractors emitting the same logical edge collapse to one row in the
+ * store.
+ *
+ * `source` records which extractor created the edge, with version. Used
+ * to invalidate edges when an extractor's behaviour changes.
+ */
+export interface IEdge {
+    id: string;
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    /** e.g. 'extract-ts-file@v1'. */
+    source: string;
+    /** Kind-specific structured payload. */
+    data?: Readonly<Record<string, unknown>>;
+}
+//# sourceMappingURL=edge.d.ts.map

package/dist/schema/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../src/schema/edge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1C"}

package/dist/schema/edge.js

@@ -0,0 +1 @@
+export {};

package/dist/schema/file-fingerprint.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Per-file fingerprint used for incremental indexing.
+ *
+ * MVP uses mtime + sha1(content). Falling back to sha1-only is fine when
+ * mtime is unreliable (e.g., docker bind mounts on Linux). The store keeps
+ * both so the comparison is cheap.
+ */
+export interface IFileFingerprint {
+    /** Project-relative path. */
+    path: string;
+    /** ms since epoch. */
+    mtime: number;
+    /** SHA-1 of file contents, hex. */
+    sha1: string;
+    /** File size in bytes. */
+    sizeBytes: number;
+    /** Resolved language tag, e.g. 'typescript' | 'javascript'. */
+    language: string;
+    /** Node id this file owns in the graph. */
+    nodeId: string;
+}
+//# sourceMappingURL=file-fingerprint.d.ts.map

package/dist/schema/file-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-fingerprint.d.ts","sourceRoot":"","sources":["../../src/schema/file-fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/schema/file-fingerprint.js

@@ -0,0 +1 @@
+export {};

package/dist/schema/graph-snapshot.d.ts

@@ -0,0 +1,18 @@
+import type { IEdge } from './edge.js';
+import type { IFileFingerprint } from './file-fingerprint.js';
+import type { IGraphManifest } from './manifest.js';
+import type { INode } from './node.js';
+/**
+ * In-memory snapshot of the graph — the unit the query API operates on.
+ *
+ * `nodes` and `edges` are flat maps keyed by id. The store loads JSONL
+ * into this shape; the indexer builds it before writing. Callers should
+ * treat it as immutable after construction.
+ */
+export interface IGraphSnapshot {
+    manifest: IGraphManifest;
+    nodes: ReadonlyMap<string, INode>;
+    edges: ReadonlyMap<string, IEdge>;
+    files: ReadonlyMap<string, IFileFingerprint>;
+}
+//# sourceMappingURL=graph-snapshot.d.ts.map

package/dist/schema/graph-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-snapshot.d.ts","sourceRoot":"","sources":["../../src/schema/graph-snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC9C"}

package/dist/schema/graph-snapshot.js

@@ -0,0 +1 @@
+export {};

package/dist/schema/manifest.d.ts

@@ -0,0 +1,47 @@
+import type { GraphSchemaVersion } from './schema-version.js';
+/**
+ * `.sharkcraft/graph/meta.json` shape.
+ *
+ * `digest` is SHA-256 over the concatenated JSONL files (alphabetical),
+ * computed at write time. A stale digest signals a tampered or partial
+ * store and must trigger a rebuild rather than silent use.
+ */
+export interface IGraphManifest {
+    schema: GraphSchemaVersion;
+    projectRoot: string;
+    lastIndexedAt: string;
+    /** Wall-clock duration of the last full index, in ms. */
+    lastIndexDurationMs: number;
+    filesIndexed: number;
+    nodesByKind: Readonly<Record<string, number>>;
+    edgesByKind: Readonly<Record<string, number>>;
+    /** SHA-256 of all JSONL files. */
+    digest: string;
+    /** Workspace packages discovered at index time. */
+    workspacePackages: readonly string[];
+    /**
+     * Count of strongly-connected components of size ≥ 2 in the
+     * `imports-file` subgraph, computed at index time. Optional for
+     * forward-compat with manifests written before this field existed
+     * (added 2026-05). Roadmap §3.1 promised cycle-aware queries; this
+     * is the persisted counter the doctor + dashboard read from.
+     */
+    cycleCount?: number;
+    /** Size of the largest SCC of size ≥ 2 (0 when no cycles). */
+    largestCycleSize?: number;
+    /** Total file nodes participating in any cycle. */
+    filesInCycles?: number;
+    /**
+     * Number of `imports-file` edges that resolved to the
+     * `unresolved:<spec>` sentinel (relative / alias / workspace path
+     * the resolver could not match against an on-disk file). Optional
+     * for forward-compat. The first ten distinct specifiers are kept
+     * in `unresolvedImportSamples` for doctor + dashboard.
+     */
+    unresolvedImportCount?: number;
+    /** Distinct files with at least one unresolved import. */
+    filesWithUnresolvedImports?: number;
+    /** First N distinct unresolved specifiers (sample for human/agent). */
+    unresolvedImportSamples?: readonly string[];
+}
+//# sourceMappingURL=manifest.d.ts.map

package/dist/schema/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/schema/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,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,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,0DAA0D;IAC1D,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,uEAAuE;IACvE,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C"}

package/dist/schema/manifest.js

@@ -0,0 +1 @@
+export {};