@shrkcrft/graph 0.1.0-alpha.17 → 0.1.0-alpha.19

package/dist/query/query-api.js

@@ -1,7 +1,31 @@
+import { statSync } from 'node:fs';
+import * as nodePath from 'node:path';
 import { EdgeKind } from "../schema/edge-kind.js";
 import { NodeKind } from "../schema/node-kind.js";
 import { GraphStore } from "../store/graph-store.js";
+import { fingerprintFile } from "../store/file-fingerprint.js";
 import { findFileCycles } from "./cycle-detection.js";
+/** Read the representative source line stored on a reference/call edge. */
+function edgeLine(e) {
+    const v = e.data?.['line'];
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+/**
+ * Forward "code uses code" edge kinds traversed by {@link GraphQueryApi.pathBetween}.
+ * Structural source-level dependencies only — package-aggregate edges
+ * (`belongs-to-package` / `package-depends-on`) and asset-bridge edges
+ * (rules / framework) are deliberately excluded so a path is always a real
+ * import/call/reference/heritage chain, not a routing through a package node.
+ */
+const CODE_PATH_EDGE_KINDS = new Set([
+    EdgeKind.ImportsFile,
+    EdgeKind.CallsSymbol,
+    EdgeKind.ReferencesSymbol,
+    EdgeKind.DeclaresSymbol,
+    EdgeKind.ReExportsSymbol,
+    EdgeKind.ExtendsSymbol,
+    EdgeKind.ImplementsSymbol,
+]);
 /**
  * Read-only query layer over an in-memory graph snapshot.
  *
@@ -187,6 +211,117 @@ export class GraphQueryApi {
         }
         return out;
     }
+    /**
+     * Symbols that EXTEND or IMPLEMENT the given symbol — the precise "who
+     * implements this interface / who subclasses this" answer that a generic
+     * reference cannot give (a reference might be a call, a type annotation, or
+     * a heritage clause; these are typed `extends-symbol`/`implements-symbol`
+     * edges only). Returns the subtype symbol nodes.
+     */
+    subtypesOf(symbolNodeId) {
+        const edges = this.inByTo.get(symbolNodeId) ?? [];
+        const out = [];
+        for (const e of edges) {
+            if (e.kind !== EdgeKind.ExtendsSymbol && e.kind !== EdgeKind.ImplementsSymbol)
+                continue;
+            const n = this.snap.nodes.get(e.from);
+            if (n)
+                out.push(n);
+        }
+        return out;
+    }
+    /** Symbols the given symbol EXTENDS or IMPLEMENTS (its supertypes). */
+    supertypesOf(symbolNodeId) {
+        const edges = this.outByFrom.get(symbolNodeId) ?? [];
+        const out = [];
+        for (const e of edges) {
+            if (e.kind !== EdgeKind.ExtendsSymbol && e.kind !== EdgeKind.ImplementsSymbol)
+                continue;
+            const n = this.snap.nodes.get(e.to);
+            if (n)
+                out.push(n);
+        }
+        return out;
+    }
+    /**
+     * Like {@link callersOf}, but keeps the call-site line carried on each
+     * edge so a caller can render `path:line` (jump-straight-to-source)
+     * instead of just the file path — the difference between "grep, then grep
+     * again inside each file" and a direct hit.
+     */
+    callerSitesOf(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({ node: n, line: edgeLine(e) });
+        }
+        return out;
+    }
+    /** Like {@link referencesOf}, but keeps the representative use-site line. */
+    referenceSitesOf(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({ node: n, line: edgeLine(e) });
+        }
+        return out;
+    }
+    /**
+     * Targeted, cheap staleness check over a handful of RESULT file paths (the
+     * declaring file + caller/dependent files of a query) — NOT a full tree
+     * walk. For each project-relative path that the index knows about: stat it
+     * (mtime+size gate, sha1 only on mismatch) and classify as `modified`
+     * (content changed → results may be wrong: stale lines / a removed caller
+     * still listed) or `deleted` (gone from disk → drop it). Lets a query flag
+     * or prune a silently-stale answer for a file the agent just edited without
+     * paying for a whole-repo freshness walk. `cwd` is passed explicitly: the
+     * snapshot's index-time absolute root is wrong if the repo moved.
+     */
+    staleFilesAmong(cwd, paths) {
+        const modified = [];
+        const deleted = [];
+        const seen = new Set();
+        for (const rel of paths) {
+            if (seen.has(rel))
+                continue;
+            seen.add(rel);
+            const fp = this.snap.files.get(rel);
+            if (!fp)
+                continue; // not an indexed file — nothing to compare against
+            const abs = nodePath.isAbsolute(rel) ? rel : nodePath.join(cwd, rel);
+            let st;
+            try {
+                st = statSync(abs);
+            }
+            catch {
+                deleted.push(rel);
+                continue;
+            }
+            if (!st.isFile()) {
+                deleted.push(rel);
+                continue;
+            }
+            if (Math.floor(st.mtimeMs) === fp.mtime && st.size === fp.sizeBytes)
+                continue; // fresh
+            if (fingerprintFile(abs, cwd).sha1 !== fp.sha1)
+                modified.push(rel);
+        }
+        modified.sort((a, b) => a.localeCompare(b));
+        deleted.sort((a, b) => a.localeCompare(b));
+        return { modified, deleted };
+    }
     /** Packages that this package depends on (PackageDependsOn). */
     packageDeps(packageName) {
         const edges = this.outByFrom.get(`package:${packageName}`) ?? [];
@@ -248,6 +383,205 @@ export class GraphQueryApi {
             }),
         };
     }
+    /**
+     * Shortest directed code path from `fromId` to `toId` over the
+     * "code uses code" edges (imports / calls / references / declares /
+     * re-exports / extends / implements). Answers "is A actually wired to B?"
+     * deterministically: a found path lists every hop with its edge kind (and
+     * call-site line where the edge carries one) so a caller sees HOW they are
+     * wired — a chain of `imports-file` hops reads very differently from a
+     * `calls-symbol` one. Breadth-first, so the returned path is minimal-hop;
+     * `explored` reports how many nodes were visited so a "no path" answer is
+     * honestly bounded rather than read as "definitely unrelated".
+     */
+    pathBetween(fromId, toId, opts = {}) {
+        const maxDepth = opts.maxDepth && opts.maxDepth > 0 ? opts.maxDepth : 16;
+        const from = this.snap.nodes.get(fromId);
+        const to = this.snap.nodes.get(toId);
+        if (!from || !to) {
+            return {
+                found: false,
+                ...(from ? { from } : {}),
+                ...(to ? { to } : {}),
+                hops: [],
+                explored: 0,
+                reason: !from && !to
+                    ? 'neither endpoint is in the graph'
+                    : !from
+                        ? 'source node is not in the graph'
+                        : 'target node is not in the graph',
+            };
+        }
+        if (fromId === toId)
+            return { found: true, from, to, hops: [], explored: 1 };
+        // BFS. `parent` maps a discovered node id to the edge that first reached it.
+        const parent = new Map();
+        const depth = new Map([[fromId, 0]]);
+        const queue = [fromId];
+        let head = 0;
+        let explored = 0;
+        while (head < queue.length) {
+            const cur = queue[head++];
+            explored++;
+            const d = depth.get(cur);
+            if (d >= maxDepth)
+                continue;
+            for (const e of this.outByFrom.get(cur) ?? []) {
+                if (!CODE_PATH_EDGE_KINDS.has(e.kind))
+                    continue;
+                if (e.to === cur || e.to === fromId || parent.has(e.to))
+                    continue;
+                parent.set(e.to, e);
+                depth.set(e.to, d + 1);
+                if (e.to === toId) {
+                    return { found: true, from, to, hops: this.reconstructPath(parent, fromId, toId), explored };
+                }
+                queue.push(e.to);
+            }
+        }
+        return { found: false, from, to, hops: [], explored, reason: `no code path within ${maxDepth} hops` };
+    }
+    /** Walk the BFS `parent` map back from `toId` to `fromId` into ordered hops. */
+    reconstructPath(parent, fromId, toId) {
+        const chain = [];
+        let cur = toId;
+        while (cur !== fromId) {
+            const e = parent.get(cur);
+            if (!e)
+                break;
+            chain.push(e);
+            cur = e.from;
+        }
+        chain.reverse();
+        const hops = [];
+        for (const e of chain) {
+            const f = this.snap.nodes.get(e.from);
+            const t = this.snap.nodes.get(e.to);
+            if (!f || !t)
+                continue;
+            const line = edgeLine(e);
+            hops.push({ from: f, to: t, kind: e.kind, ...(line !== undefined ? { line } : {}) });
+        }
+        return hops;
+    }
+    /**
+     * The most-depended-on code in the snapshot: symbols ranked by how many
+     * distinct files reference/call them and files ranked by how many distinct
+     * files import them. This is the "load-bearing code" view — the surface an
+     * agent should change most carefully and a human should understand first.
+     * In-degree counts DISTINCT dependent files (a file that calls a symbol
+     * ten times counts once), so the rank reflects blast radius, not call volume.
+     */
+    /**
+     * The DIRECT dependents of a node — what breaks if you change it, one hop out.
+     * Kind-aware, because the edge that carries "depends on" differs by kind:
+     *   - Symbol: the files that reference/call it, PLUS the files declaring its
+     *     subtypes (a class that `import type`s an interface has no value-reference
+     *     edge, so subtypes must be added explicitly or implementers are missed).
+     *     Falls back to the importers of its declaring file when nothing references
+     *     the symbol directly.
+     *   - File: its importers (`imports-file`).
+     *   - Package: the packages that depend on it.
+     * The shared building block for impact reverse-closures (CLI + MCP) — keep this
+     * the ONE source of truth so the two surfaces never disagree on a symbol's
+     * blast radius (they once did: an importers-only closure returned NOTHING for a
+     * symbol, a confidently-wrong "nothing breaks").
+     */
+    directDependentsOf(anchor) {
+        if (anchor.kind === NodeKind.Symbol) {
+            const owner = this.declaringFileOf(anchor.id);
+            const out = new Map();
+            for (const n of this.referencesOf(anchor.id)) {
+                if (n.kind === NodeKind.File && n.id !== owner?.id)
+                    out.set(n.id, n);
+            }
+            for (const n of this.callersOf(anchor.id)) {
+                if (n.kind === NodeKind.File && n.id !== owner?.id)
+                    out.set(n.id, n);
+            }
+            for (const s of this.subtypesOf(anchor.id)) {
+                if (!s.path)
+                    continue;
+                const fileNode = this.fileByPath.get(s.path);
+                if (fileNode && fileNode.id !== owner?.id)
+                    out.set(fileNode.id, fileNode);
+            }
+            if (out.size > 0)
+                return [...out.values()];
+            return owner ? [...this.importersOf(owner.id)] : [];
+        }
+        if (anchor.kind === NodeKind.Package) {
+            return this.packageDependents(anchor.id.replace(/^package:/, ''));
+        }
+        return [...this.importersOf(anchor.id)];
+    }
+    /** The file that declares a symbol (the `declares-symbol` source), if known. */
+    declaringFileOf(symbolId) {
+        for (const e of this.inByTo.get(symbolId) ?? []) {
+            if (e.kind !== EdgeKind.DeclaresSymbol)
+                continue;
+            const n = this.snap.nodes.get(e.from);
+            if (n && n.kind === NodeKind.File)
+                return n;
+        }
+        return undefined;
+    }
+    topHubs(limit = 10, pathPrefix) {
+        // Optional path scope: rank only the load-bearing code WITHIN a subsystem
+        // (e.g. `packages/inspector`) — the global hubs are dominated by the biggest
+        // packages, but an agent working in one area wants that area's hubs. The
+        // in-degree still counts ALL dependents (anyone in the repo), answering
+        // "within this dir, what is most depended-on?".
+        const prefix = pathPrefix ? pathPrefix.replace(/\\/g, '/').replace(/\/+$/, '') : undefined;
+        const inScope = (path) => !prefix || (path !== undefined && (path === prefix || path.startsWith(prefix + '/')));
+        const symbolDeps = new Map();
+        const fileDeps = new Map();
+        for (const [toId, edges] of this.inByTo) {
+            const target = this.snap.nodes.get(toId);
+            if (!target)
+                continue;
+            if (!inScope(target.path))
+                continue;
+            if (target.kind === NodeKind.Symbol) {
+                const set = new Set();
+                for (const e of edges) {
+                    if (e.kind === EdgeKind.ReferencesSymbol || e.kind === EdgeKind.CallsSymbol) {
+                        set.add(e.from); // reference/call edges originate on a file node
+                    }
+                    else if (e.kind === EdgeKind.ExtendsSymbol || e.kind === EdgeKind.ImplementsSymbol) {
+                        // Heritage edges originate on the SUBTYPE symbol — count its file so
+                        // an interface implemented only via `import type` (no reference edge)
+                        // still ranks as load-bearing, at the same file granularity.
+                        const sub = this.snap.nodes.get(e.from);
+                        set.add(sub?.path ? `file:${sub.path}` : e.from);
+                    }
+                }
+                if (set.size > 0)
+                    symbolDeps.set(toId, set);
+            }
+            else if (target.kind === NodeKind.File) {
+                const set = new Set();
+                for (const e of edges) {
+                    if (e.kind === EdgeKind.ImportsFile)
+                        set.add(e.from);
+                }
+                if (set.size > 0)
+                    fileDeps.set(toId, set);
+            }
+        }
+        const cap = Math.max(0, limit);
+        const toHubs = (m) => {
+            const arr = [];
+            for (const [id, set] of m) {
+                const node = this.snap.nodes.get(id);
+                if (node)
+                    arr.push({ node, inDegree: set.size });
+            }
+            arr.sort((a, b) => b.inDegree - a.inDegree || a.node.label.localeCompare(b.node.label) || a.node.id.localeCompare(b.node.id));
+            return arr.slice(0, cap);
+        };
+        return { symbols: toHubs(symbolDeps), files: toHubs(fileDeps) };
+    }
 }
 function filterByPackage(list, pkg) {
     if (!pkg)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/graph",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.19",
   "description": "SharkCraft code intelligence graph: files, symbols, packages, imports and exports. Persistent JSONL store; on-disk index queried by every other code-intelligence package.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -45,9 +45,9 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.17",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.17",
-    "@shrkcrft/inspector": "^0.1.0-alpha.17",
+    "@shrkcrft/core": "^0.1.0-alpha.19",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.19",
+    "@shrkcrft/inspector": "^0.1.0-alpha.19",
     "typescript": "^5.6.0"
   },
   "publishConfig": {