@shrkcrft/graph 0.1.0-alpha.10

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

@@ -0,0 +1,403 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import * as ts from 'typescript';
+import { buildSymbolIndex, SymbolVisibility, } from '@shrkcrft/inspector';
+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.
+ */
+const IMPORT_RE = /(?:^|\s)(?:import|export)\s+[^'"`]*?from\s+['"]([^'"`]+)['"]/g;
+const SIDE_EFFECT_IMPORT_RE = /(?:^|\s)import\s+['"]([^'"`]+)['"]/g;
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"`]+)['"]\s*\)/g;
+const REQUIRE_RE = /\brequire\s*\(\s*['"]([^'"`]+)['"]\s*\)/g;
+/**
+ * Extract graph entities from a single TS/TSX/JS/JSX file.
+ *
+ * Re-uses `buildSymbolIndex` for symbol detection (per-file AST, no full
+ * program). Import edges carry the literal specifier; resolution to the
+ * target file id happens in `resolve-imports.ts` (R64).
+ */
+export function extractTsFile(fingerprint, absPath, content) {
+    const text = content ?? readFileSync(absPath, 'utf8');
+    // Single-file-component languages (Vue, Svelte, Astro) are not pure TS.
+    // We produce a minimal File node and let `@shrkcrft/framework-scanners`
+    // detect component-level structure. Imports still extracted from
+    // `<script>` blocks via the regex pass below.
+    if (fingerprint.language === 'vue' ||
+        fingerprint.language === 'svelte' ||
+        fingerprint.language === 'astro' ||
+        fingerprint.language === 'graphql') {
+        const fileNode = makeFileNodeForNonTs(fingerprint);
+        return {
+            fileNode,
+            symbolNodes: [],
+            edges: [],
+            rawImportSpecifiers: fingerprint.language === 'graphql' ? [] : scanFileImports(text),
+            importBindings: [],
+            identifierReferences: [],
+        };
+    }
+    const idx = buildSymbolIndex(absPath, text);
+    const fileNode = makeFileNode(fingerprint, idx);
+    const symbolNodes = [];
+    const edges = [];
+    for (const e of idx.exports) {
+        const sym = makeSymbolNode(fingerprint, e.name, e.kind, e.visibility, e.line);
+        symbolNodes.push(sym);
+        edges.push(buildEdge(fileNode.id, sym.id, EdgeKind.DeclaresSymbol, {
+            visibility: e.visibility,
+            declKind: e.kind,
+            line: e.line,
+        }));
+    }
+    for (const l of idx.locals) {
+        const sym = makeSymbolNode(fingerprint, l.name, l.kind, l.visibility, l.line);
+        symbolNodes.push(sym);
+        edges.push(buildEdge(fileNode.id, sym.id, EdgeKind.DeclaresSymbol, {
+            visibility: l.visibility,
+            declKind: l.kind,
+            line: l.line,
+        }));
+    }
+    for (const re of idx.reExports) {
+        // The target file is unresolved at extract-time; we record the spec.
+        // The indexer post-pass adds the resolved symbol edge once imports
+        // resolve. The placeholder symbol id below intentionally has no
+        // matching node — the resolver replaces it.
+        const placeholderTarget = `symbol:unresolved:${re.from}#${re.name}`;
+        edges.push(buildEdge(fileNode.id, placeholderTarget, EdgeKind.ReExportsSymbol, {
+            specifier: re.from,
+            name: re.name,
+            star: re.star,
+            line: re.line,
+        }));
+    }
+    const rawImportSpecifiers = scanFileImports(text);
+    const { importBindings, identifierReferences } = walkAst(absPath, text);
+    return {
+        fileNode,
+        symbolNodes,
+        edges,
+        rawImportSpecifiers,
+        importBindings,
+        identifierReferences,
+    };
+}
+function pickScriptKind(ext) {
+    switch (ext) {
+        case '.tsx': return ts.ScriptKind.TSX;
+        case '.jsx': return ts.ScriptKind.JSX;
+        case '.js':
+        case '.mjs':
+        case '.cjs': return ts.ScriptKind.JS;
+        default: return ts.ScriptKind.TS;
+    }
+}
+/**
+ * AST walk that collects:
+ *   - Named + default import bindings (skip namespace + type-only).
+ *   - Identifier references in the file body, flagged as `isCall` when
+ *     the identifier is the callee of a `CallExpression`.
+ *
+ * Identifiers inside import declarations themselves are not collected —
+ * they're declaration sites, not uses.
+ */
+function walkAst(absPath, text) {
+    const ext = nodePath.extname(absPath).toLowerCase();
+    let sf;
+    try {
+        sf = ts.createSourceFile(absPath, text, ts.ScriptTarget.Latest, true, pickScriptKind(ext));
+    }
+    catch {
+        return { importBindings: [], identifierReferences: [] };
+    }
+    const bindings = [];
+    const refs = [];
+    for (const stmt of sf.statements) {
+        if (!ts.isImportDeclaration(stmt))
+            continue;
+        if (!ts.isStringLiteral(stmt.moduleSpecifier))
+            continue;
+        const specifier = stmt.moduleSpecifier.text;
+        const clause = stmt.importClause;
+        if (!clause)
+            continue;
+        if (clause.isTypeOnly)
+            continue;
+        if (clause.name) {
+            bindings.push({
+                localName: clause.name.text,
+                importedName: 'default',
+                specifier,
+                isDefault: true,
+                line: lineOf(sf, clause.name),
+            });
+        }
+        if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+            for (const elem of clause.namedBindings.elements) {
+                if (elem.isTypeOnly)
+                    continue;
+                bindings.push({
+                    localName: elem.name.text,
+                    importedName: elem.propertyName ? elem.propertyName.text : elem.name.text,
+                    specifier,
+                    isDefault: false,
+                    line: lineOf(sf, elem),
+                });
+            }
+        }
+        // NamespaceImport (`import * as X`) intentionally skipped.
+    }
+    function visit(node) {
+        // Skip the declaration sites we already harvested.
+        if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node))
+            return;
+        if (ts.isIdentifier(node) && !isDeclarationName(node)) {
+            refs.push({
+                name: node.text,
+                line: lineOf(sf, node),
+                isCall: isCallCallee(node),
+            });
+        }
+        ts.forEachChild(node, visit);
+    }
+    ts.forEachChild(sf, visit);
+    // De-dupe identical (name, line, isCall) triples; a single AST often
+    // visits the same identifier twice (e.g. in computed property names).
+    const seen = new Set();
+    const dedupedRefs = [];
+    for (const r of refs) {
+        const k = `${r.name}|${r.line}|${r.isCall ? 1 : 0}`;
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        dedupedRefs.push(r);
+    }
+    return { importBindings: bindings, identifierReferences: dedupedRefs };
+}
+function isDeclarationName(id) {
+    const parent = id.parent;
+    if (!parent)
+        return false;
+    // The `name` of various declarations; we don't want to record those.
+    if ((ts.isVariableDeclaration(parent) ||
+        ts.isFunctionDeclaration(parent) ||
+        ts.isClassDeclaration(parent) ||
+        ts.isInterfaceDeclaration(parent) ||
+        ts.isTypeAliasDeclaration(parent) ||
+        ts.isEnumDeclaration(parent) ||
+        ts.isParameter(parent) ||
+        ts.isPropertyDeclaration(parent) ||
+        ts.isPropertySignature(parent) ||
+        ts.isMethodDeclaration(parent) ||
+        ts.isMethodSignature(parent) ||
+        ts.isEnumMember(parent) ||
+        ts.isBindingElement(parent)) &&
+        parent.name === id) {
+        return true;
+    }
+    // Property accesses: `foo.bar` — `bar` is a property name, not a free
+    // identifier. We DO want to capture `foo`.
+    if (ts.isPropertyAccessExpression(parent) && parent.name === id)
+        return true;
+    if (ts.isQualifiedName(parent) && parent.right === id)
+        return true;
+    // Property assignment in object literal: `{ bar: x }` — `bar` is a key.
+    if (ts.isPropertyAssignment(parent) && parent.name === id)
+        return true;
+    if (ts.isShorthandPropertyAssignment(parent) && parent.name === id) {
+        // `{ foo }` — `foo` is BOTH key and value; we want it.
+        return false;
+    }
+    return false;
+}
+function isCallCallee(id) {
+    const parent = id.parent;
+    if (!parent)
+        return false;
+    if (ts.isCallExpression(parent) && parent.expression === id)
+        return true;
+    // `new Foo(...)` — semantically an invocation; count it as a call.
+    if (ts.isNewExpression(parent) && parent.expression === id)
+        return true;
+    return false;
+}
+function lineOf(sf, node) {
+    return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+}
+/**
+ * Stitch identifier references + import bindings into edges.
+ *
+ * Called by the indexer after per-file extraction + import resolution.
+ * Emits `references-symbol` / `calls-symbol` edges from a file to the
+ * symbol(s) it uses. Same-file references resolve against the file's
+ * own declared symbols; cross-file references resolve via the import
+ * bindings + the resolver's spec → targetPath map.
+ *
+ * Default imports target `symbol:<targetPath>#<defaultExportName>`
+ * when the default export name is known (via the file node's
+ * `defaultExportName` data), or `#default` as a placeholder when not.
+ */
+export function stitchPerFileReferences(input) {
+    const { fileNodeId, extracted, resolvedSpec, defaultExportNameByPath, localSymbolNamesInThisFile } = input;
+    const bindings = 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 out = [];
+    const seen = new Set();
+    for (const r of extracted.identifierReferences) {
+        let target = bindings.get(r.name);
+        if (!target)
+            target = localSymbolNamesInThisFile.get(r.name);
+        if (!target)
+            continue;
+        if (target === fileNodeId)
+            continue; // ignore self-loops
+        const kind = r.isCall ? EdgeKind.CallsSymbol : EdgeKind.ReferencesSymbol;
+        // De-dupe (target, kind) — many call sites of the same function on
+        // different lines collapse to a single file-level edge. We keep
+        // line info via the data of the first occurrence; the schema is
+        // ready for symbol-level edges in Wave 3 proper.
+        const edgeKey = `${target}|${kind}`;
+        if (seen.has(edgeKey))
+            continue;
+        seen.add(edgeKey);
+        out.push(buildEdge(fileNodeId, target, kind, { line: r.line }));
+    }
+    return out;
+}
+function makeFileNodeForNonTs(fp) {
+    const label = fp.path.split('/').pop() ?? fp.path;
+    const tags = [fp.language];
+    if (isTestPath(fp.path))
+        tags.push('test');
+    return {
+        id: fp.nodeId,
+        kind: NodeKind.File,
+        label,
+        path: fp.path,
+        tags,
+        data: {
+            language: fp.language,
+            sizeBytes: fp.sizeBytes,
+            sha1: fp.sha1,
+            hasDefaultExport: false,
+            exportCount: 0,
+            localCount: 0,
+            reExportCount: 0,
+        },
+    };
+}
+function makeFileNode(fp, idx) {
+    const label = fp.path.split('/').pop() ?? fp.path;
+    const tags = [];
+    if (isTestPath(fp.path))
+        tags.push('test');
+    if (isGenerated(idx))
+        tags.push('generated');
+    return {
+        id: fp.nodeId,
+        kind: NodeKind.File,
+        label,
+        path: fp.path,
+        tags: tags.length > 0 ? tags : undefined,
+        data: {
+            language: fp.language,
+            sizeBytes: fp.sizeBytes,
+            sha1: fp.sha1,
+            hasDefaultExport: idx.hasDefaultExport,
+            ...(idx.defaultExportName ? { defaultExportName: idx.defaultExportName } : {}),
+            exportCount: idx.exports.length,
+            localCount: idx.locals.length,
+            reExportCount: idx.reExports.length,
+        },
+    };
+}
+function makeSymbolNode(fp, name, declKind, visibility, line) {
+    return {
+        id: `symbol:${fp.path}#${name}`,
+        kind: NodeKind.Symbol,
+        label: name,
+        path: fp.path,
+        line,
+        data: {
+            declKind,
+            visibility,
+            isExported: visibility === SymbolVisibility.Export || visibility === SymbolVisibility.Default,
+        },
+    };
+}
+function buildEdge(from, to, kind, data) {
+    const id = createHash('sha1').update(`${from}|${to}|${kind}`).digest('hex');
+    return {
+        id,
+        from,
+        to,
+        kind,
+        source: EXTRACT_TS_FILE_SOURCE,
+        ...(data ? { data } : {}),
+    };
+}
+function isTestPath(rel) {
+    return /(?:^|\/)(?:__tests__|__mocks__)\//.test(rel) || /\.(?:test|spec)\.[tj]sx?$/.test(rel);
+}
+function isGenerated(idx) {
+    // Symbol-index doesn't preserve raw text; the file-level header check
+    // happens in the indexer where the buffer is in hand. Stays false here
+    // and is corrected by the indexer when needed.
+    return false;
+}
+function scanFileImports(text) {
+    const out = [];
+    collect(text, IMPORT_RE, 'static', out);
+    collect(text, SIDE_EFFECT_IMPORT_RE, 'side-effect', out);
+    collect(text, DYNAMIC_IMPORT_RE, 'dynamic', out);
+    collect(text, REQUIRE_RE, 'require', out);
+    // Dedupe identical (specifier, line, kind).
+    const seen = new Set();
+    const deduped = [];
+    for (const it of out) {
+        const k = `${it.kind}|${it.specifier}|${it.line}`;
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        deduped.push(it);
+    }
+    return deduped;
+}
+function collect(text, re, kind, out) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const specifier = m[1];
+        if (!specifier)
+            continue;
+        const line = lineFromOffset(text, m.index);
+        out.push({ specifier, line, kind });
+    }
+}
+function lineFromOffset(text, offset) {
+    let line = 1;
+    for (let i = 0; i < offset && i < text.length; i++) {
+        if (text.charCodeAt(i) === 10)
+            line += 1;
+    }
+    return line;
+}

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

@@ -0,0 +1,41 @@
+import type { IGraphManifest } from '../schema/manifest.js';
+export interface IIncrementalUpdateOptions {
+    projectRoot: string;
+    /** Project-relative file paths (POSIX). */
+    changedFiles?: readonly string[];
+    /** Project-relative file paths (POSIX). */
+    deletedFiles?: readonly string[];
+}
+export interface IIncrementalUpdateResult {
+    manifest: IGraphManifest;
+    durationMs: number;
+    /** Files actually re-extracted (skipped == fingerprint unchanged). */
+    updated: readonly string[];
+    /** Files removed from the index. */
+    deleted: readonly string[];
+    /** Files marked as changed but whose fingerprint matched (no-op). */
+    skipped: readonly string[];
+}
+/**
+ * Apply a delta to the on-disk index.
+ *
+ * Strategy (MVP): load the snapshot, mutate in memory, rewrite the full
+ * store. Cheap for SharkCraft-sized indexes (a few MB on disk). Per-kind
+ * append/compact is the optimisation when the cold-rewrite cost is felt.
+ */
+export declare function updateChanged(options: IIncrementalUpdateOptions): IIncrementalUpdateResult;
+/**
+ * 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.
+ */
+export declare function detectChangedAndDeleted(projectRoot: string): {
+    changed: readonly string[];
+    deleted: readonly string[];
+};
+/**
+ * Get the list of files changed since a git ref (e.g. `main`, `HEAD~5`,
+ * a tag). Returns project-relative POSIX paths. Errors → empty list.
+ */
+export declare function changedFilesSince(projectRoot: string, ref: string): readonly string[];
+//# sourceMappingURL=incremental-updater.d.ts.map

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

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