@grafema/core 0.1.0-alpha.5 → 0.2.0-beta

package/dist/core/FileExplainer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * FileExplainer - Show what nodes exist in a file for discovery
+ *
+ * Purpose: Help users discover what nodes exist in the graph for a file,
+ * displaying semantic IDs so users can query them.
+ *
+ * This addresses the core UX problem: users can't find nodes because
+ * semantic IDs are opaque (e.g., "src/app.ts->fetchData->try#0->VARIABLE->response").
+ * This tool shows what's in the graph so users know what they can query.
+ *
+ * @see _tasks/REG-177/006-don-revised-plan.md for design rationale
+ */
+import type { GraphBackend, BaseNodeRecord } from '@grafema/types';
+/**
+ * Result of explaining a file's graph contents
+ */
+export interface FileExplainResult {
+    /** The file path that was explained */
+    file: string;
+    /** Whether the file has been analyzed */
+    status: 'ANALYZED' | 'NOT_ANALYZED';
+    /** All nodes in the graph for this file, enhanced with context */
+    nodes: EnhancedNode[];
+    /** Node counts grouped by type */
+    byType: Record<string, number>;
+    /** Total number of nodes in the file */
+    totalCount: number;
+}
+/**
+ * A node record enhanced with scope context information.
+ *
+ * The context field provides human-readable information about
+ * where the node appears (e.g., "inside try block", "catch parameter").
+ */
+export interface EnhancedNode extends BaseNodeRecord {
+    /** Human-readable context about the node's scope */
+    context?: string;
+}
+/**
+ * FileExplainer class - explains what nodes exist in a file's graph.
+ *
+ * Use this when:
+ * - User can't find a variable/function they expect to be in the graph
+ * - User wants to understand what's been analyzed for a file
+ * - User needs semantic IDs to construct queries
+ *
+ * Example:
+ * ```typescript
+ * const explainer = new FileExplainer(graphBackend);
+ * const result = await explainer.explain('src/app.ts');
+ *
+ * if (result.status === 'NOT_ANALYZED') {
+ *   console.log('File not in graph. Run: grafema analyze');
+ * } else {
+ *   for (const node of result.nodes) {
+ *     console.log(`[${node.type}] ${node.name}`);
+ *     console.log(`  ID: ${node.id}`);
+ *     if (node.context) {
+ *       console.log(`  Context: ${node.context}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class FileExplainer {
+    private graph;
+    constructor(graph: GraphBackend);
+    /**
+     * Explain what nodes exist in the graph for a file.
+     *
+     * @param filePath - The file path to explain (relative or absolute)
+     * @returns FileExplainResult with all nodes, grouped by type, with context
+     */
+    explain(filePath: string): Promise<FileExplainResult>;
+    /**
+     * Query graph for all nodes in a file
+     *
+     * Note: The server-side file filter may not work correctly in all cases,
+     * so we also filter client-side to ensure only nodes from the requested file are returned.
+     */
+    private getNodesForFile;
+    /**
+     * Group nodes by type, counting occurrences
+     */
+    private groupByType;
+    /**
+     * Enhance nodes with human-readable scope context.
+     *
+     * Detects patterns in semantic IDs like:
+     * - "file->func->try#0->VARIABLE->x" → "inside try block"
+     * - "file->func->catch#0->VARIABLE->error" → "inside catch block"
+     */
+    private enhanceWithContext;
+    /**
+     * Detect scope context from semantic ID patterns.
+     *
+     * Returns human-readable context string or undefined if no special scope.
+     */
+    private detectScopeContext;
+}
+//# sourceMappingURL=FileExplainer.d.ts.map

package/dist/core/FileExplainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileExplainer.d.ts","sourceRoot":"","sources":["../../src/core/FileExplainer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAc,MAAM,gBAAgB,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC;IACpC,kEAAkE;IAClE,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,YAAY;IAEvC;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0B3D;;;;;OAKG;YACW,eAAe;IAc7B;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;CAQ3B"}

package/dist/core/FileExplainer.js

@@ -0,0 +1,139 @@
+/**
+ * FileExplainer - Show what nodes exist in a file for discovery
+ *
+ * Purpose: Help users discover what nodes exist in the graph for a file,
+ * displaying semantic IDs so users can query them.
+ *
+ * This addresses the core UX problem: users can't find nodes because
+ * semantic IDs are opaque (e.g., "src/app.ts->fetchData->try#0->VARIABLE->response").
+ * This tool shows what's in the graph so users know what they can query.
+ *
+ * @see _tasks/REG-177/006-don-revised-plan.md for design rationale
+ */
+/**
+ * Scope patterns to detect from semantic IDs.
+ * Order matters - more specific patterns should come first.
+ */
+const SCOPE_PATTERNS = [
+    { pattern: /->catch#\d+->/, context: 'inside catch block' },
+    { pattern: /->try#\d+->/, context: 'inside try block' },
+    { pattern: /->if#\d+->/, context: 'inside conditional' },
+    { pattern: /->else#\d+->/, context: 'inside else block' },
+    { pattern: /->for#\d+->/, context: 'inside loop' },
+    { pattern: /->while#\d+->/, context: 'inside loop' },
+    { pattern: /->switch#\d+->/, context: 'inside switch' },
+];
+/**
+ * FileExplainer class - explains what nodes exist in a file's graph.
+ *
+ * Use this when:
+ * - User can't find a variable/function they expect to be in the graph
+ * - User wants to understand what's been analyzed for a file
+ * - User needs semantic IDs to construct queries
+ *
+ * Example:
+ * ```typescript
+ * const explainer = new FileExplainer(graphBackend);
+ * const result = await explainer.explain('src/app.ts');
+ *
+ * if (result.status === 'NOT_ANALYZED') {
+ *   console.log('File not in graph. Run: grafema analyze');
+ * } else {
+ *   for (const node of result.nodes) {
+ *     console.log(`[${node.type}] ${node.name}`);
+ *     console.log(`  ID: ${node.id}`);
+ *     if (node.context) {
+ *       console.log(`  Context: ${node.context}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class FileExplainer {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    /**
+     * Explain what nodes exist in the graph for a file.
+     *
+     * @param filePath - The file path to explain (relative or absolute)
+     * @returns FileExplainResult with all nodes, grouped by type, with context
+     */
+    async explain(filePath) {
+        // Query graph for all nodes in this file
+        const nodes = await this.getNodesForFile(filePath);
+        // Group by type
+        const byType = this.groupByType(nodes);
+        // Enhance with context from semantic ID parsing
+        const enhanced = this.enhanceWithContext(nodes);
+        // Sort nodes: by type, then by name
+        enhanced.sort((a, b) => {
+            const typeCompare = a.type.localeCompare(b.type);
+            if (typeCompare !== 0)
+                return typeCompare;
+            return (a.name || '').localeCompare(b.name || '');
+        });
+        return {
+            file: filePath,
+            status: nodes.length > 0 ? 'ANALYZED' : 'NOT_ANALYZED',
+            nodes: enhanced,
+            byType,
+            totalCount: nodes.length,
+        };
+    }
+    /**
+     * Query graph for all nodes in a file
+     *
+     * Note: The server-side file filter may not work correctly in all cases,
+     * so we also filter client-side to ensure only nodes from the requested file are returned.
+     */
+    async getNodesForFile(filePath) {
+        const filter = { file: filePath };
+        const nodes = [];
+        for await (const node of this.graph.queryNodes(filter)) {
+            // Client-side filter as backup (server filter may not work correctly)
+            if (node.file === filePath) {
+                nodes.push(node);
+            }
+        }
+        return nodes;
+    }
+    /**
+     * Group nodes by type, counting occurrences
+     */
+    groupByType(nodes) {
+        const counts = {};
+        for (const node of nodes) {
+            const type = node.type || 'UNKNOWN';
+            counts[type] = (counts[type] || 0) + 1;
+        }
+        return counts;
+    }
+    /**
+     * Enhance nodes with human-readable scope context.
+     *
+     * Detects patterns in semantic IDs like:
+     * - "file->func->try#0->VARIABLE->x" → "inside try block"
+     * - "file->func->catch#0->VARIABLE->error" → "inside catch block"
+     */
+    enhanceWithContext(nodes) {
+        return nodes.map((node) => {
+            const context = this.detectScopeContext(node.id);
+            return context ? { ...node, context } : { ...node };
+        });
+    }
+    /**
+     * Detect scope context from semantic ID patterns.
+     *
+     * Returns human-readable context string or undefined if no special scope.
+     */
+    detectScopeContext(semanticId) {
+        for (const { pattern, context } of SCOPE_PATTERNS) {
+            if (pattern.test(semanticId)) {
+                return context;
+            }
+        }
+        return undefined;
+    }
+}

package/dist/core/FileNodeManager.d.ts

@@ -0,0 +1,40 @@
+/**
+ * FileNodeManager - utility for idempotent file node clearing
+ *
+ * Problem: Multiple phases create nodes for the same file:
+ * - INDEXING creates MODULE nodes
+ * - ANALYSIS creates FUNCTION, CLASS, SCOPE, etc. nodes
+ *
+ * When re-analyzing with forceAnalysis=true, we need to clear existing
+ * nodes BEFORE any phase creates new nodes for that file.
+ *
+ * Solution: Track "touched" files. First touch clears all nodes for that file.
+ * Subsequent touches (from other phases) are no-ops.
+ */
+import type { GraphBackend } from '@grafema/types';
+/**
+ * Clear all nodes for a file if it hasn't been touched yet in this analysis run.
+ *
+ * Thread-safety note: The touchedFiles Set is shared across concurrent Promise.all
+ * calls, but this is safe because:
+ * 1. The check (has) and add are synchronous operations
+ * 2. We add to the set BEFORE the async clear operation
+ * 3. Other concurrent calls will see the file as touched immediately
+ *
+ * @param graph - Graph backend with deleteNode support
+ * @param file - Absolute file path to clear nodes for
+ * @param touchedFiles - Set tracking files already touched in this run
+ * @returns Number of nodes deleted (0 if file was already touched or backend doesn't support delete)
+ */
+export declare function clearFileNodesIfNeeded(graph: GraphBackend, file: string, touchedFiles: Set<string>): Promise<number>;
+/**
+ * Clear a SERVICE node by ID.
+ * SERVICE nodes have file=directory_path (not individual files), so they need
+ * explicit clearing separate from file-based clearing.
+ *
+ * @param graph - Graph backend with deleteNode support
+ * @param serviceId - SERVICE node ID (e.g., "SERVICE:apps/api")
+ * @returns true if node was deleted, false otherwise
+ */
+export declare function clearServiceNodeIfExists(graph: GraphBackend, serviceId: string): Promise<boolean>;
+//# sourceMappingURL=FileNodeManager.d.ts.map

package/dist/core/FileNodeManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileNodeManager.d.ts","sourceRoot":"","sources":["../../src/core/FileNodeManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,OAAO,CAAC,MAAM,CAAC,CAsCjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAalB"}

package/dist/core/FileNodeManager.js

@@ -0,0 +1,84 @@
+/**
+ * FileNodeManager - utility for idempotent file node clearing
+ *
+ * Problem: Multiple phases create nodes for the same file:
+ * - INDEXING creates MODULE nodes
+ * - ANALYSIS creates FUNCTION, CLASS, SCOPE, etc. nodes
+ *
+ * When re-analyzing with forceAnalysis=true, we need to clear existing
+ * nodes BEFORE any phase creates new nodes for that file.
+ *
+ * Solution: Track "touched" files. First touch clears all nodes for that file.
+ * Subsequent touches (from other phases) are no-ops.
+ */
+/**
+ * Clear all nodes for a file if it hasn't been touched yet in this analysis run.
+ *
+ * Thread-safety note: The touchedFiles Set is shared across concurrent Promise.all
+ * calls, but this is safe because:
+ * 1. The check (has) and add are synchronous operations
+ * 2. We add to the set BEFORE the async clear operation
+ * 3. Other concurrent calls will see the file as touched immediately
+ *
+ * @param graph - Graph backend with deleteNode support
+ * @param file - Absolute file path to clear nodes for
+ * @param touchedFiles - Set tracking files already touched in this run
+ * @returns Number of nodes deleted (0 if file was already touched or backend doesn't support delete)
+ */
+export async function clearFileNodesIfNeeded(graph, file, touchedFiles) {
+    // Already touched in this run - nothing to clear
+    if (touchedFiles.has(file)) {
+        return 0;
+    }
+    // Mark as touched BEFORE clearing (sync operation, makes subsequent concurrent calls no-op)
+    touchedFiles.add(file);
+    // Skip if backend doesn't support deletion
+    if (!graph.deleteNode) {
+        return 0;
+    }
+    // Collect all nodes for this file
+    const nodesToDelete = [];
+    for await (const node of graph.queryNodes({ file })) {
+        nodesToDelete.push(node.id);
+    }
+    // Delete all of them - NO EXCLUSIONS
+    // MODULE nodes will be recreated by INDEXING phase
+    // FUNCTION/CLASS/etc will be recreated by ANALYSIS phase
+    for (const id of nodesToDelete) {
+        try {
+            await graph.deleteNode(id);
+        }
+        catch (err) {
+            // Log but continue - node might already be deleted by concurrent operation
+            console.warn(`[FileNodeManager] Failed to delete ${id}:`, err.message);
+        }
+    }
+    if (nodesToDelete.length > 0) {
+        const fileName = file.split('/').pop() || file;
+        console.log(`[FileNodeManager] Cleared ${nodesToDelete.length} nodes for ${fileName}`);
+    }
+    return nodesToDelete.length;
+}
+/**
+ * Clear a SERVICE node by ID.
+ * SERVICE nodes have file=directory_path (not individual files), so they need
+ * explicit clearing separate from file-based clearing.
+ *
+ * @param graph - Graph backend with deleteNode support
+ * @param serviceId - SERVICE node ID (e.g., "SERVICE:apps/api")
+ * @returns true if node was deleted, false otherwise
+ */
+export async function clearServiceNodeIfExists(graph, serviceId) {
+    if (!graph.deleteNode) {
+        return false;
+    }
+    try {
+        await graph.deleteNode(serviceId);
+        console.log(`[FileNodeManager] Cleared SERVICE node: ${serviceId}`);
+        return true;
+    }
+    catch (err) {
+        // Node might not exist on fresh analysis - that's OK
+        return false;
+    }
+}

package/dist/core/GraphFreshnessChecker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GraphFreshnessChecker - checks if graph data matches current files
+ *
+ * Compares contentHash stored in MODULE nodes against current file hashes.
+ * Used by `grafema check` to detect when files have changed since analysis.
+ */
+import type { NodeRecord } from '@grafema/types';
+export interface StaleModule {
+    id: string;
+    file: string;
+    storedHash: string;
+    currentHash: string | null;
+    reason: 'changed' | 'deleted' | 'unreadable';
+}
+export interface FreshnessResult {
+    isFresh: boolean;
+    staleModules: StaleModule[];
+    freshCount: number;
+    staleCount: number;
+    deletedCount: number;
+    checkDurationMs: number;
+}
+export interface FreshnessGraph {
+    queryNodes(query: {
+        type: string;
+    }): AsyncGenerator<NodeRecord, void, unknown>;
+}
+export declare class GraphFreshnessChecker {
+    checkFreshness(graph: FreshnessGraph): Promise<FreshnessResult>;
+    private _checkModuleFreshness;
+    private _fileExists;
+}
+//# sourceMappingURL=GraphFreshnessChecker.d.ts.map

package/dist/core/GraphFreshnessChecker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphFreshnessChecker.d.ts","sourceRoot":"","sources":["../../src/core/GraphFreshnessChecker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,YAAY,CAAC;CAC9C;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;CAChF;AAUD,qBAAa,qBAAqB;IAC1B,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;YAyDvD,qBAAqB;YAoCrB,WAAW;CAQ1B"}

package/dist/core/GraphFreshnessChecker.js

@@ -0,0 +1,101 @@
+/**
+ * GraphFreshnessChecker - checks if graph data matches current files
+ *
+ * Compares contentHash stored in MODULE nodes against current file hashes.
+ * Used by `grafema check` to detect when files have changed since analysis.
+ */
+import { access, constants } from 'fs/promises';
+import { calculateFileHashAsync } from './HashUtils.js';
+const BATCH_SIZE = 50;
+export class GraphFreshnessChecker {
+    async checkFreshness(graph) {
+        const startTime = Date.now();
+        const modules = [];
+        for await (const node of graph.queryNodes({ type: 'MODULE' })) {
+            if (node.file && typeof node.contentHash === 'string') {
+                modules.push({
+                    id: node.id,
+                    file: node.file,
+                    contentHash: node.contentHash
+                });
+            }
+        }
+        if (modules.length === 0) {
+            return {
+                isFresh: true,
+                staleModules: [],
+                freshCount: 0,
+                staleCount: 0,
+                deletedCount: 0,
+                checkDurationMs: Date.now() - startTime
+            };
+        }
+        const staleModules = [];
+        let freshCount = 0;
+        let deletedCount = 0;
+        for (let i = 0; i < modules.length; i += BATCH_SIZE) {
+            const batch = modules.slice(i, i + BATCH_SIZE);
+            const results = await Promise.all(batch.map(module => this._checkModuleFreshness(module)));
+            for (const result of results) {
+                if (result === null) {
+                    freshCount++;
+                }
+                else {
+                    staleModules.push(result);
+                    if (result.reason === 'deleted') {
+                        deletedCount++;
+                    }
+                }
+            }
+        }
+        return {
+            isFresh: staleModules.length === 0,
+            staleModules,
+            freshCount,
+            staleCount: staleModules.length,
+            deletedCount,
+            checkDurationMs: Date.now() - startTime
+        };
+    }
+    async _checkModuleFreshness(module) {
+        const exists = await this._fileExists(module.file);
+        if (!exists) {
+            return {
+                id: module.id,
+                file: module.file,
+                storedHash: module.contentHash,
+                currentHash: null,
+                reason: 'deleted'
+            };
+        }
+        const currentHash = await calculateFileHashAsync(module.file);
+        if (currentHash === null) {
+            return {
+                id: module.id,
+                file: module.file,
+                storedHash: module.contentHash,
+                currentHash: null,
+                reason: 'unreadable'
+            };
+        }
+        if (currentHash !== module.contentHash) {
+            return {
+                id: module.id,
+                file: module.file,
+                storedHash: module.contentHash,
+                currentHash,
+                reason: 'changed'
+            };
+        }
+        return null;
+    }
+    async _fileExists(filePath) {
+        try {
+            await access(filePath, constants.R_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/core/HashUtils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * HashUtils - unified hash computation for Grafema
+ *
+ * WHY THIS EXISTS:
+ * - 6 copies of the same hash computation existed across the codebase
+ * - Single source of truth ensures consistent hashing everywhere
+ * - Makes future algorithm changes (e.g., SHA-256 -> BLAKE3) trivial
+ */
+/**
+ * Calculate hash from a file path (synchronous).
+ * Returns null if file doesn't exist or is unreadable.
+ */
+export declare function calculateFileHash(filePath: string): string | null;
+/**
+ * Calculate hash from a file path (asynchronous).
+ * Returns null if file doesn't exist or is unreadable.
+ */
+export declare function calculateFileHashAsync(filePath: string): Promise<string | null>;
+/**
+ * Calculate hash from content string.
+ * Always returns a hash (never null).
+ */
+export declare function calculateContentHash(content: string): string;
+//# sourceMappingURL=HashUtils.d.ts.map

package/dist/core/HashUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HashUtils.d.ts","sourceRoot":"","sources":["../../src/core/HashUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOjE;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOrF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/core/HashUtils.js

@@ -0,0 +1,45 @@
+/**
+ * HashUtils - unified hash computation for Grafema
+ *
+ * WHY THIS EXISTS:
+ * - 6 copies of the same hash computation existed across the codebase
+ * - Single source of truth ensures consistent hashing everywhere
+ * - Makes future algorithm changes (e.g., SHA-256 -> BLAKE3) trivial
+ */
+import { createHash } from 'crypto';
+import { readFileSync } from 'fs';
+import { readFile } from 'fs/promises';
+const HASH_ALGORITHM = 'sha256';
+/**
+ * Calculate hash from a file path (synchronous).
+ * Returns null if file doesn't exist or is unreadable.
+ */
+export function calculateFileHash(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        return createHash(HASH_ALGORITHM).update(content).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Calculate hash from a file path (asynchronous).
+ * Returns null if file doesn't exist or is unreadable.
+ */
+export async function calculateFileHashAsync(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        return createHash(HASH_ALGORITHM).update(content).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Calculate hash from content string.
+ * Always returns a hash (never null).
+ */
+export function calculateContentHash(content) {
+    return createHash(HASH_ALGORITHM).update(content).digest('hex');
+}

package/dist/core/IncrementalReanalyzer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * IncrementalReanalyzer - selective re-analysis of stale modules
+ *
+ * HOW IT WORKS:
+ * 1. Clear all nodes for stale files (using clearFileNodesIfNeeded)
+ * 2. Re-create MODULE nodes with updated contentHash
+ * 3. Run JSASTAnalyzer.analyzeModule() for each stale module
+ * 4. Re-run enrichment plugins to rebuild cross-file edges
+ */
+import type { GraphBackend } from '@grafema/types';
+import type { StaleModule } from './GraphFreshnessChecker.js';
+export interface ReanalysisOptions {
+    skipEnrichment?: boolean;
+    onProgress?: (info: ReanalysisProgress) => void;
+}
+export interface ReanalysisProgress {
+    phase: 'clearing' | 'indexing' | 'analysis' | 'enrichment';
+    current: number;
+    total: number;
+    currentFile?: string;
+}
+export interface ReanalysisResult {
+    modulesReanalyzed: number;
+    modulesDeleted: number;
+    nodesCreated: number;
+    edgesCreated: number;
+    nodesCleared: number;
+    durationMs: number;
+}
+export declare class IncrementalReanalyzer {
+    private graph;
+    private projectPath;
+    constructor(graph: GraphBackend, projectPath: string);
+    reanalyze(staleModules: StaleModule[], options?: ReanalysisOptions): Promise<ReanalysisResult>;
+}
+//# sourceMappingURL=IncrementalReanalyzer.d.ts.map

package/dist/core/IncrementalReanalyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IncrementalReanalyzer.d.ts","sourceRoot":"","sources":["../../src/core/IncrementalReanalyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAYD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,WAAW,CAAS;gBAEhB,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM;IAK9C,SAAS,CACb,YAAY,EAAE,WAAW,EAAE,EAC3B,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC;CAkI7B"}