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

package/dist/index.d.ts

@@ -25,6 +25,9 @@ export * from './indexer/resolve-imports.js';
 export * from './indexer/index-builder.js';
 export * from './indexer/incremental-updater.js';
 export * from './indexer/unresolved-imports.js';
+export * from './indexer/call-graph-support.js';
+export * from './indexer/resolve-reexports.js';
 export * from './query/query-api.js';
+export * from './query/graph-api-cache.js';
 export * from './query/cycle-detection.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAE3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AAEvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAEhD,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAE3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AAEvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAE/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC"}

package/dist/index.js

@@ -28,5 +28,8 @@ export * from "./indexer/resolve-imports.js";
 export * from "./indexer/index-builder.js";
 export * from "./indexer/incremental-updater.js";
 export * from "./indexer/unresolved-imports.js";
+export * from "./indexer/call-graph-support.js";
+export * from "./indexer/resolve-reexports.js";
 export * from "./query/query-api.js";
+export * from "./query/graph-api-cache.js";
 export * from "./query/cycle-detection.js";

package/dist/indexer/call-graph-support.d.ts

@@ -0,0 +1,3 @@
+/** True when call/reference edges are extracted for this file language. */
+export declare function hasCallGraphReferences(language: string | undefined): boolean;
+//# sourceMappingURL=call-graph-support.d.ts.map

package/dist/indexer/call-graph-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-graph-support.d.ts","sourceRoot":"","sources":["../../src/indexer/call-graph-support.ts"],"names":[],"mappings":"AA6BA,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE5E"}

package/dist/indexer/call-graph-support.js

@@ -0,0 +1,32 @@
+/**
+ * Languages whose dedicated extractor does NOT emit call/reference edges
+ * (`CallsSymbol` / `ReferencesSymbol`). Only the TS-family extractor
+ * (`extractTsFile`, for ts/tsx/js/jsx) walks an AST to build the call graph;
+ * the per-language extractors (Go, Python, Java, …) and the single-file
+ * component / SDL formats produce symbol + import nodes but no reference edges.
+ *
+ * Consumers (`graph callers`, `code_find_usages`) use this to tell an agent
+ * that an EMPTY caller list for a symbol in one of these files means
+ * "not tracked", not "nothing calls it" — so it doesn't read silence as proof.
+ */
+const NON_CALL_GRAPH_LANGUAGES = new Set([
+    'python',
+    'go',
+    'java',
+    'rust',
+    'kotlin',
+    'ruby',
+    'csharp',
+    'elixir',
+    'php',
+    'dart',
+    'swift',
+    'vue',
+    'svelte',
+    'astro',
+    'graphql',
+]);
+/** True when call/reference edges are extracted for this file language. */
+export function hasCallGraphReferences(language) {
+    return !language || !NON_CALL_GRAPH_LANGUAGES.has(language);
+}

package/dist/indexer/extract-ts-file.d.ts

@@ -22,6 +22,24 @@ export interface IExtractedFile {
      * symbols and emits `references-symbol` / `calls-symbol` edges.
      */
     identifierReferences: readonly IIdentifierReference[];
+    /**
+     * `class C extends B` / `class C implements I` / `interface I extends J`
+     * heritage relationships. The post-pass resolves each base name (like a
+     * reference) and emits a typed `extends-symbol` / `implements-symbol` edge
+     * FROM the subject symbol TO the base — richer than the generic reference
+     * edge the base identifier also produces, so "who implements I" / "is C a
+     * subtype of B" are first-class graph queries. Optional: only the TS/TSX/JS
+     * extractor populates it — the per-language extractors omit it.
+     */
+    heritageReferences?: readonly IHeritageReference[];
+}
+export interface IHeritageReference {
+    /** The declaring class/interface name (resolves to `symbol:<path>#<subject>`). */
+    subjectName: string;
+    /** The referenced base type name (resolved like an identifier reference). */
+    baseName: string;
+    kind: 'extends' | 'implements';
+    line: number;
 }
 export interface IRawImportSpecifier {
     specifier: string;
@@ -37,6 +55,14 @@ export interface IImportBinding {
     specifier: string;
     isDefault: boolean;
     line: number;
+    /**
+     * `import type { X }` / `import { type X }` — a type-only binding. These are
+     * NOT used to resolve value references (a type-only import is not a runtime
+     * use), but ARE used to resolve heritage clauses (`implements X` where `X` is
+     * an interface, near-always imported `import type`). Without this an
+     * interface implemented across files would never connect to its implementers.
+     */
+    isTypeOnly?: boolean;
 }
 export interface IIdentifierReference {
     /** Identifier text at the use site. */

package/dist/indexer/extract-ts-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-ts-file.d.ts","sourceRoot":"","sources":["../../src/indexer/extract-ts-file.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG/C,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAc3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,KAAK,CAAC;IAChB,WAAW,EAAE,SAAS,KAAK,EAAE,CAAC;IAC9B,KAAK,EAAE,SAAS,KAAK,EAAE,CAAC;IACxB,uEAAuE;IACvE,mBAAmB,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACpD;;;;;;OAMG;IACH,cAAc,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C;;;;OAIG;IACH,oBAAoB,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACvD;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,gBAAgB,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,cAAc,CA+EhB;AA6ID;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,cAAc,CAAC;IAC1B,4DAA4D;IAC5D,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACtD,iDAAiD;IACjD,uBAAuB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACjE,yEAAyE;IACzE,0BAA0B,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzD,GAAG,SAAS,KAAK,EAAE,CA+BnB"}
+{"version":3,"file":"extract-ts-file.d.ts","sourceRoot":"","sources":["../../src/indexer/extract-ts-file.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG/C,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAqB3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,KAAK,CAAC;IAChB,WAAW,EAAE,SAAS,KAAK,EAAE,CAAC;IAC9B,KAAK,EAAE,SAAS,KAAK,EAAE,CAAC;IACxB,uEAAuE;IACvE,mBAAmB,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACpD;;;;;;OAMG;IACH,cAAc,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C;;;;OAIG;IACH,oBAAoB,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACtD;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,SAAS,GAAG,YAAY,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,gBAAgB,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,cAAc,CA+EhB;AAgQD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,cAAc,CAAC;IAC1B,4DAA4D;IAC5D,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACtD,iDAAiD;IACjD,uBAAuB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACjE,yEAAyE;IACzE,0BAA0B,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzD,GAAG,SAAS,KAAK,EAAE,CAkDnB"}

package/dist/indexer/extract-ts-file.js

@@ -7,11 +7,18 @@ import { EdgeKind } from "../schema/edge-kind.js";
 import { NodeKind } from "../schema/node-kind.js";
 export const EXTRACT_TS_FILE_SOURCE = 'extract-ts-file@v1';
 /**
- * Per-file import scan. The boundaries package owns the project-wide
- * `scanImports`; for the graph extractor we need a per-file pass that
- * runs against a buffer we already have in hand. The regexes mirror
- * `boundaries/scan-imports.ts` deliberately — keeping them in sync is a
- * test obligation, not a runtime one.
+ * Per-file import scan for NON-TS single-file-component formats
+ * (Vue/Svelte/Astro `<script>` blocks) where no TypeScript AST is
+ * available.
+ *
+ * TS/TSX/JS/JSX files derive their import specifiers from the AST in
+ * `walkAst` instead — that is comment- and string-literal-safe, so an
+ * `import ... from '...'` that appears inside a comment, JSDoc block, a
+ * template-literal body (e.g. a generator template), rule documentation,
+ * or a test fixture string is never mistaken for a real import (the
+ * regexes below would, and that produced phantom `unresolved:` edges and
+ * phantom arch violations). The regexes still mirror
+ * `boundaries/scan-imports.ts` for the SFC formats that need them.
  */
 const IMPORT_RE = /(?:^|\s)(?:import|export)\s+[^'"`]*?from\s+['"]([^'"`]+)['"]/g;
 const SIDE_EFFECT_IMPORT_RE = /(?:^|\s)import\s+['"]([^'"`]+)['"]/g;
@@ -79,8 +86,7 @@ export function extractTsFile(fingerprint, absPath, content) {
             line: re.line,
         }));
     }
-    const rawImportSpecifiers = scanFileImports(text);
-    const { importBindings, identifierReferences } = walkAst(absPath, text);
+    const { importBindings, identifierReferences, rawImportSpecifiers, heritageReferences } = walkAst(absPath, text);
     return {
         fileNode,
         symbolNodes,
@@ -88,6 +94,7 @@ export function extractTsFile(fingerprint, absPath, content) {
         rawImportSpecifiers,
         importBindings,
         identifierReferences,
+        heritageReferences,
     };
 }
 function pickScriptKind(ext) {
@@ -116,10 +123,52 @@ function walkAst(absPath, text) {
         sf = ts.createSourceFile(absPath, text, ts.ScriptTarget.Latest, true, pickScriptKind(ext));
     }
     catch {
-        return { importBindings: [], identifierReferences: [] };
+        // AST unavailable — fall back to the raw-text regex so we don't lose
+        // import edges entirely (rare; createSourceFile is very lenient).
+        return {
+            importBindings: [],
+            identifierReferences: [],
+            rawImportSpecifiers: scanFileImports(text),
+            heritageReferences: [],
+        };
     }
     const bindings = [];
     const refs = [];
+    const rawSpecs = [];
+    const heritage = [];
+    // AST-sourced import specifiers (comment- and string-literal-safe). Every
+    // real import shape the regex caught must be reproduced here or a genuine
+    // unresolved/cross-package import would stop being flagged: static + side
+    // effect + type-only imports, `export ... from`, `import x = require()`,
+    // and dynamic `import()` / `require()` calls (the last two collected in
+    // the visitor below).
+    for (const stmt of sf.statements) {
+        if (ts.isImportDeclaration(stmt) && ts.isStringLiteral(stmt.moduleSpecifier)) {
+            rawSpecs.push({
+                specifier: stmt.moduleSpecifier.text,
+                line: lineOf(sf, stmt),
+                kind: stmt.importClause ? 'static' : 'side-effect',
+            });
+        }
+        else if (ts.isExportDeclaration(stmt) &&
+            stmt.moduleSpecifier &&
+            ts.isStringLiteral(stmt.moduleSpecifier)) {
+            rawSpecs.push({
+                specifier: stmt.moduleSpecifier.text,
+                line: lineOf(sf, stmt),
+                kind: 'static',
+            });
+        }
+        else if (ts.isImportEqualsDeclaration(stmt) &&
+            ts.isExternalModuleReference(stmt.moduleReference) &&
+            ts.isStringLiteral(stmt.moduleReference.expression)) {
+            rawSpecs.push({
+                specifier: stmt.moduleReference.expression.text,
+                line: lineOf(sf, stmt),
+                kind: 'require',
+            });
+        }
+    }
     for (const stmt of sf.statements) {
         if (!ts.isImportDeclaration(stmt))
             continue;
@@ -129,8 +178,9 @@ function walkAst(absPath, text) {
         const clause = stmt.importClause;
         if (!clause)
             continue;
-        if (clause.isTypeOnly)
-            continue;
+        // Type-only imports are TAGGED (not skipped) so heritage resolution can use
+        // them; the value-reference pass still ignores them (see stitchPerFileReferences).
+        const clauseTypeOnly = clause.isTypeOnly;
         if (clause.name) {
             bindings.push({
                 localName: clause.name.text,
@@ -138,18 +188,19 @@ function walkAst(absPath, text) {
                 specifier,
                 isDefault: true,
                 line: lineOf(sf, clause.name),
+                ...(clauseTypeOnly ? { isTypeOnly: true } : {}),
             });
         }
         if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
             for (const elem of clause.namedBindings.elements) {
-                if (elem.isTypeOnly)
-                    continue;
+                const typeOnly = clauseTypeOnly || elem.isTypeOnly;
                 bindings.push({
                     localName: elem.name.text,
                     importedName: elem.propertyName ? elem.propertyName.text : elem.name.text,
                     specifier,
                     isDefault: false,
                     line: lineOf(sf, elem),
+                    ...(typeOnly ? { isTypeOnly: true } : {}),
                 });
             }
         }
@@ -159,6 +210,36 @@ function walkAst(absPath, text) {
         // Skip the declaration sites we already harvested.
         if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node))
             return;
+        // Dynamic `import('...')` and `require('...')` calls — real call nodes,
+        // so text inside comments/strings never matches.
+        if (ts.isCallExpression(node)) {
+            const arg0 = node.arguments[0];
+            if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+                if (arg0 && ts.isStringLiteral(arg0)) {
+                    rawSpecs.push({ specifier: arg0.text, line: lineOf(sf, node), kind: 'dynamic' });
+                }
+            }
+            else if (ts.isIdentifier(node.expression) && node.expression.text === 'require') {
+                if (arg0 && ts.isStringLiteral(arg0)) {
+                    rawSpecs.push({ specifier: arg0.text, line: lineOf(sf, node), kind: 'require' });
+                }
+            }
+        }
+        // `class C extends B implements I` / `interface I extends J` — record the
+        // typed heritage relationship. The base identifier is ALSO captured as a
+        // generic reference below (kept, so reference-based queries still see it);
+        // the post-pass adds the richer extends/implements edge on top.
+        if ((ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node)) && node.name && node.heritageClauses) {
+            const subjectName = node.name.text;
+            for (const clause of node.heritageClauses) {
+                const hkind = clause.token === ts.SyntaxKind.ExtendsKeyword ? 'extends' : 'implements';
+                for (const t of clause.types) {
+                    const baseName = headIdentifierName(t.expression);
+                    if (baseName)
+                        heritage.push({ subjectName, baseName, kind: hkind, line: lineOf(sf, t.expression) });
+                }
+            }
+        }
         if (ts.isIdentifier(node) && !isDeclarationName(node)) {
             refs.push({
                 name: node.text,
@@ -180,7 +261,46 @@ function walkAst(absPath, text) {
         seen.add(k);
         dedupedRefs.push(r);
     }
-    return { importBindings: bindings, identifierReferences: dedupedRefs };
+    // De-dupe identical (kind, specifier, line) — same contract scanFileImports
+    // applied to the regex output.
+    const seenSpecs = new Set();
+    const dedupedSpecs = [];
+    for (const s of rawSpecs) {
+        const k = `${s.kind}|${s.specifier}|${s.line}`;
+        if (seenSpecs.has(k))
+            continue;
+        seenSpecs.add(k);
+        dedupedSpecs.push(s);
+    }
+    // De-dupe identical (subject, base, kind) heritage triples.
+    const seenHeritage = new Set();
+    const dedupedHeritage = [];
+    for (const h of heritage) {
+        const k = `${h.subjectName}|${h.baseName}|${h.kind}`;
+        if (seenHeritage.has(k))
+            continue;
+        seenHeritage.add(k);
+        dedupedHeritage.push(h);
+    }
+    return {
+        importBindings: bindings,
+        identifierReferences: dedupedRefs,
+        rawImportSpecifiers: dedupedSpecs,
+        heritageReferences: dedupedHeritage,
+    };
+}
+/**
+ * The leftmost identifier name of a heritage base expression: `Base` for
+ * `Base`, `Base<T>` (already unwrapped — `t.expression` is the head), and the
+ * leftmost for a qualified `ns.Base` (returns `ns`, matching how the generic
+ * reference walk resolves `ns` — namespace-qualified bases stay best-effort).
+ */
+function headIdentifierName(expr) {
+    if (ts.isIdentifier(expr))
+        return expr.text;
+    if (ts.isPropertyAccessExpression(expr))
+        return headIdentifierName(expr.expression);
+    return undefined;
 }
 function isDeclarationName(id) {
     const parent = id.parent;
@@ -247,18 +367,21 @@ function lineOf(sf, node) {
  */
 export function stitchPerFileReferences(input) {
     const { fileNodeId, extracted, resolvedSpec, defaultExportNameByPath, localSymbolNamesInThisFile } = input;
+    // `bindings` resolves VALUE references (type-only imports excluded — a type
+    // import is not a runtime use). `heritageBindings` additionally includes
+    // type-only imports, used only for `implements`/`extends` resolution.
     const bindings = new Map();
+    const heritageBindings = new Map();
     for (const b of extracted.importBindings) {
         const targetPath = resolvedSpec.get(b.specifier);
         if (!targetPath)
             continue;
-        if (b.isDefault) {
-            const defName = defaultExportNameByPath.get(targetPath);
-            bindings.set(b.localName, `symbol:${targetPath}#${defName ?? 'default'}`);
-        }
-        else {
-            bindings.set(b.localName, `symbol:${targetPath}#${b.importedName}`);
-        }
+        const id = b.isDefault
+            ? `symbol:${targetPath}#${defaultExportNameByPath.get(targetPath) ?? 'default'}`
+            : `symbol:${targetPath}#${b.importedName}`;
+        heritageBindings.set(b.localName, id);
+        if (!b.isTypeOnly)
+            bindings.set(b.localName, id);
     }
     const out = [];
     const seen = new Set();
@@ -281,6 +404,25 @@ export function stitchPerFileReferences(input) {
         seen.add(edgeKey);
         out.push(buildEdge(fileNodeId, target, kind, { line: r.line }));
     }
+    // Typed heritage edges, FROM the subject symbol TO the resolved base symbol.
+    // Resolved like a reference (import binding or local symbol); a base in an
+    // external lib (`extends Error`) resolves to nothing and is skipped, so only
+    // intra-project subtype relationships become edges.
+    const filePath = fileNodeId.replace(/^file:/, '');
+    for (const h of extracted.heritageReferences ?? []) {
+        const target = heritageBindings.get(h.baseName) ?? localSymbolNamesInThisFile.get(h.baseName);
+        if (!target)
+            continue;
+        const subjectId = `symbol:${filePath}#${h.subjectName}`;
+        if (subjectId === target)
+            continue; // ignore self-reference
+        const kind = h.kind === 'extends' ? EdgeKind.ExtendsSymbol : EdgeKind.ImplementsSymbol;
+        const edgeKey = `${subjectId}|${target}|${kind}`;
+        if (seen.has(edgeKey))
+            continue;
+        seen.add(edgeKey);
+        out.push(buildEdge(subjectId, target, kind, { line: h.line }));
+    }
     return out;
 }
 function makeFileNodeForNonTs(fp) {

package/dist/indexer/incremental-updater.d.ts

@@ -24,10 +24,28 @@ export interface IIncrementalUpdateResult {
  * append/compact is the optimisation when the cold-rewrite cost is felt.
  */
 export declare function updateChanged(options: IIncrementalUpdateOptions): IIncrementalUpdateResult;
+export interface IGraphFreshness {
+    hasIndex: boolean;
+    lastIndexedAt?: string;
+    /** Indexed files whose on-disk content changed since the index was built. */
+    modified: readonly string[];
+    /** Source files on disk that are not in the index yet. */
+    added: readonly string[];
+    /** Indexed files that no longer exist on disk. */
+    deleted: readonly string[];
+}
+/**
+ * Walk the project and categorise every source file against the stored
+ * snapshot: `modified` (indexed but content changed), `added` (on disk, not
+ * indexed), `deleted` (indexed, gone from disk). This is the per-file truth
+ * behind honest `graph status` freshness and the targeted per-query staleness
+ * check — so an agent never gets a silently-stale answer for a file it just
+ * edited. Outputs are sorted for determinism.
+ */
+export declare function detectGraphFreshness(projectRoot: string): IGraphFreshness;
 /**
- * Helper: detect changed files by walking the project and comparing
- * fingerprints against the stored snapshot. Used by
- * `shrk graph index --changed` when no explicit file list is provided.
+ * Back-compat adapter for `shrk graph index --changed`: `changed` is the
+ * union of modified + added (both need re-extraction); `deleted` unchanged.
  */
 export declare function detectChangedAndDeleted(projectRoot: string): {
     changed: readonly string[];

package/dist/indexer/incremental-updater.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"incremental-updater.d.ts","sourceRoot":"","sources":["../../src/indexer/incremental-updater.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAyC5D,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,2CAA2C;IAC3C,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,oCAAoC;IACpC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,qEAAqE;IACrE,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,yBAAyB,GACjC,wBAAwB,CAwM1B;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG;IAC5D,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,CAqEA;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAcrF"}
+{"version":3,"file":"incremental-updater.d.ts","sourceRoot":"","sources":["../../src/indexer/incremental-updater.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA0C5D,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,2CAA2C;IAC3C,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,oCAAoC;IACpC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,qEAAqE;IACrE,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,yBAAyB,GACjC,wBAAwB,CAiN1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,0DAA0D;IAC1D,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,kDAAkD;IAClD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CA+EzE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG;IAC5D,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,CAMA;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAcrF"}

package/dist/indexer/incremental-updater.js

@@ -8,6 +8,7 @@ import { fingerprintFile } from "../store/file-fingerprint.js";
 import { GraphStore } from "../store/graph-store.js";
 import { summarizeCycles } from "../query/cycle-detection.js";
 import { summarizeUnresolvedImports } from "./unresolved-imports.js";
+import { resolveReExportedReferenceEdges } from "./resolve-reexports.js";
 import { detectWorkspacePackages, } from "./detect-workspace.js";
 import { EXTRACT_TS_FILE_SOURCE, extractTsFile, stitchPerFileReferences, } from "./extract-ts-file.js";
 import { extractPythonFile } from "./extract-python-file.js";
@@ -179,7 +180,17 @@ export function updateChanged(options) {
         edges.set(e.id, e);
     }
     const nodeList = [...nodes.values()];
-    const edgeList = [...edges.values()];
+    // Resolve barrel re-export chains (rewrites phantom cross-package
+    // reference/call targets to the real symbol), then de-dupe since a rewrite
+    // can collide a rewritten edge id with an existing one.
+    const seenEdge = new Set();
+    const edgeList = [];
+    for (const e of resolveReExportedReferenceEdges(nodeList, [...edges.values()])) {
+        if (seenEdge.has(e.id))
+            continue;
+        seenEdge.add(e.id);
+        edgeList.push(e);
+    }
     const cycles = summarizeCycles(nodeList, edgeList);
     const unresolved = summarizeUnresolvedImports(edgeList);
     const manifest = store.writeSnapshot(nodeList, edgeList, [...files.values()], {
@@ -206,18 +217,22 @@ export function updateChanged(options) {
     };
 }
 /**
- * Helper: detect changed files by walking the project and comparing
- * fingerprints against the stored snapshot. Used by
- * `shrk graph index --changed` when no explicit file list is provided.
+ * Walk the project and categorise every source file against the stored
+ * snapshot: `modified` (indexed but content changed), `added` (on disk, not
+ * indexed), `deleted` (indexed, gone from disk). This is the per-file truth
+ * behind honest `graph status` freshness and the targeted per-query staleness
+ * check — so an agent never gets a silently-stale answer for a file it just
+ * edited. Outputs are sorted for determinism.
  */
-export function detectChangedAndDeleted(projectRoot) {
+export function detectGraphFreshness(projectRoot) {
     const store = new GraphStore(projectRoot);
     if (!store.exists()) {
-        return { changed: [], deleted: [] };
+        return { hasIndex: false, modified: [], added: [], deleted: [] };
     }
     const snap = store.loadSnapshot();
     const seen = new Set();
-    const changed = [];
+    const modified = [];
+    const added = [];
     const fsStack = [projectRoot];
     const skip = new Set([
         'node_modules',
@@ -269,7 +284,7 @@ export function detectChangedAndDeleted(projectRoot) {
             seen.add(rel);
             const oldFp = snap.files.get(rel);
             if (!oldFp) {
-                changed.push(rel);
+                added.push(rel);
                 continue;
             }
             // Cheap check: mtime first. If equal, trust it (assumes mtime
@@ -279,7 +294,7 @@ export function detectChangedAndDeleted(projectRoot) {
                 continue;
             const newFp = fingerprintFile(full, projectRoot);
             if (newFp.sha1 !== oldFp.sha1)
-                changed.push(rel);
+                modified.push(rel);
         }
     }
     const deleted = [];
@@ -287,7 +302,27 @@ export function detectChangedAndDeleted(projectRoot) {
         if (!seen.has(path))
             deleted.push(path);
     }
-    return { changed, deleted };
+    modified.sort((a, b) => a.localeCompare(b));
+    added.sort((a, b) => a.localeCompare(b));
+    deleted.sort((a, b) => a.localeCompare(b));
+    return {
+        hasIndex: true,
+        lastIndexedAt: snap.manifest.lastIndexedAt,
+        modified,
+        added,
+        deleted,
+    };
+}
+/**
+ * Back-compat adapter for `shrk graph index --changed`: `changed` is the
+ * union of modified + added (both need re-extraction); `deleted` unchanged.
+ */
+export function detectChangedAndDeleted(projectRoot) {
+    const f = detectGraphFreshness(projectRoot);
+    return {
+        changed: [...f.modified, ...f.added].sort((a, b) => a.localeCompare(b)),
+        deleted: f.deleted,
+    };
 }
 /**
  * Get the list of files changed since a git ref (e.g. `main`, `HEAD~5`,

package/dist/indexer/index-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-builder.d.ts","sourceRoot":"","sources":["../../src/indexer/index-builder.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA6D5D,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,gBAAgB,CA0I9E"}
+{"version":3,"file":"index-builder.d.ts","sourceRoot":"","sources":["../../src/indexer/index-builder.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA8D5D,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,gBAAgB,CAkJ9E"}

package/dist/indexer/index-builder.js

@@ -21,6 +21,7 @@ import { extractPhpFile } from "./extract-php-file.js";
 import { extractDartFile } from "./extract-dart-file.js";
 import { extractSwiftFile } from "./extract-swift-file.js";
 import { createImportResolverContext, ImportResolution, resolveImport, } from "./resolve-imports.js";
+import { resolveReExportedReferenceEdges } from "./resolve-reexports.js";
 const SOURCE_EXTS = new Set([
     '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts',
     // Web component formats — parsed by framework-scanners; the TS-AST
@@ -122,7 +123,9 @@ export function buildFullIndex(options) {
             else {
                 const externalId = r.kind === ImportResolution.External
                     ? `external:${r.specifier}`
-                    : `unresolved:${r.specifier}`;
+                    : r.kind === ImportResolution.Asset
+                        ? `asset:${r.specifier}`
+                        : `unresolved:${r.specifier}`;
                 edges.push(buildEdge(fp.nodeId, externalId, EdgeKind.ImportsFile, EXTRACT_TS_FILE_SOURCE, data));
             }
         }
@@ -144,15 +147,20 @@ export function buildFullIndex(options) {
         for (const e of refEdges)
             edges.push(e);
     }
+    // Resolve barrel re-export chains so reference/call edges that point at a
+    // phantom `symbol:<barrel>#name` are rewritten to the real declaring
+    // symbol — otherwise cross-package consumers (which import from a package
+    // barrel) never show up in `graph callers` / impact.
+    const resolvedEdges = resolveReExportedReferenceEdges(nodes, edges);
     // PackageDependsOn aggregates: collapse internal ImportsFile edges to
     // their owning package on both sides.
-    collectPackageDependsOn(edges, packageDirIndex);
+    collectPackageDependsOn(resolvedEdges, packageDirIndex);
     // Drop duplicate edges (extractor may emit identical edges for `export
     // { foo } from './foo'` and an `import` re-using the same line — same
-    // hashed id, last write wins). Edge dedupe by id.
+    // hashed id, last write wins; a re-export rewrite can also collide ids).
     const seen = new Set();
     const dedupedEdges = [];
-    for (const e of edges) {
+    for (const e of resolvedEdges) {
         if (seen.has(e.id))
             continue;
         seen.add(e.id);

package/dist/indexer/resolve-imports.d.ts

@@ -5,6 +5,7 @@ export declare enum ImportResolution {
     Alias = "alias",
     Workspace = "workspace",
     External = "external",
+    Asset = "asset",
     Unresolved = "unresolved"
 }
 export interface IResolvedImport {

package/dist/indexer/resolve-imports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-imports.d.ts","sourceRoot":"","sources":["../../src/indexer/resolve-imports.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAI/D,oBAAY,gBAAgB;IAC1B,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,UAAU,eAAe;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,gBAAgB,CAAC;IACvB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,aAAa,EAAE,iBAAiB,CAAC;CAClC;AAED,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,iBAAiB,EAAE,SAAS,iBAAiB,EAAE,GAC9C,sBAAsB,CAMxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,sBAAsB,GAC1B,eAAe,CAwCjB"}
+{"version":3,"file":"resolve-imports.d.ts","sourceRoot":"","sources":["../../src/indexer/resolve-imports.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAmB/D,oBAAY,gBAAgB;IAC1B,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,UAAU,eAAe;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,gBAAgB,CAAC;IACvB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,aAAa,EAAE,iBAAiB,CAAC;CAClC;AAED,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,iBAAiB,EAAE,SAAS,iBAAiB,EAAE,GAC9C,sBAAsB,CAMxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,sBAAsB,GAC1B,eAAe,CAkDjB"}

package/dist/indexer/resolve-imports.js

@@ -2,12 +2,27 @@ import { existsSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { loadTsconfigPaths, resolveAliasCandidates, } from '@shrkcrft/boundaries';
 const PROBE_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
+/**
+ * Extensions for non-code assets a TS/JS file can legitimately import
+ * (CSS modules, JSON, images, fonts, wasm). The graph only indexes source
+ * files, so these never resolve to a file node — but an asset that EXISTS
+ * on disk is NOT an unresolved import (the bundler handles it), whereas a
+ * missing one still is a real broken reference.
+ */
+const NON_CODE_ASSET_EXTS = new Set([
+    '.css', '.scss', '.sass', '.less', '.styl',
+    '.json', '.json5',
+    '.svg', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.ico', '.bmp',
+    '.woff', '.woff2', '.ttf', '.eot', '.otf',
+    '.wasm',
+]);
 export var ImportResolution;
 (function (ImportResolution) {
     ImportResolution["Relative"] = "relative";
     ImportResolution["Alias"] = "alias";
     ImportResolution["Workspace"] = "workspace";
     ImportResolution["External"] = "external";
+    ImportResolution["Asset"] = "asset";
     ImportResolution["Unresolved"] = "unresolved";
 })(ImportResolution || (ImportResolution = {}));
 export function createImportResolverContext(projectRoot, workspacePackages) {
@@ -32,7 +47,17 @@ export function createImportResolverContext(projectRoot, workspacePackages) {
 export function resolveImport(specifier, fromAbsPath, ctx) {
     if (specifier.startsWith('.')) {
         const dir = nodePath.dirname(fromAbsPath);
-        const probe = probeCandidate(nodePath.resolve(dir, specifier));
+        const abs = nodePath.resolve(dir, specifier);
+        const ext = nodePath.extname(specifier).toLowerCase();
+        if (NON_CODE_ASSET_EXTS.has(ext)) {
+            // Existing asset → resolved-enough (not counted as unresolved); a
+            // missing asset stays Unresolved so a real broken reference is caught.
+            if (existsSafe(abs) && isFile(abs)) {
+                return { specifier, kind: ImportResolution.Asset };
+            }
+            return { specifier, kind: ImportResolution.Unresolved };
+        }
+        const probe = probeCandidate(abs);
         if (probe) {
             return {
                 specifier,