@grafema/util 0.3.0-beta

package/src/core/HashUtils.ts

@@ -0,0 +1,48 @@
+/**
+ * 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: string): string | null {
+  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: string): Promise<string | null> {
+  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: string): string {
+  return createHash(HASH_ALGORITHM).update(content).digest('hex');
+}

package/src/core/IncrementalReanalyzer.ts

@@ -0,0 +1,106 @@
+/**
+ * IncrementalReanalyzer - selective re-analysis of stale modules
+ *
+ * Shells out to grafema-orchestrator for reanalysis.
+ * The Rust orchestrator handles clearing, indexing, analysis, and enrichment.
+ */
+
+import { spawn } from 'child_process';
+import { join } from 'path';
+import type { GraphBackend } from '@grafema/types';
+import type { StaleModule } from './GraphFreshnessChecker.js';
+import { findOrchestratorBinary } from '../utils/findRfdbBinary.js';
+
+export interface ReanalysisOptions {
+  skipEnrichment?: boolean;
+  onProgress?: (info: ReanalysisProgress) => void;
+}
+
+export interface ReanalysisProgress {
+  phase: 'clearing' | 'indexing' | 'analysis' | 'enrichment';
+  processedFiles: number;
+  totalFiles: number;
+  currentService?: string;
+}
+
+export interface ReanalysisResult {
+  modulesReanalyzed: number;
+  modulesDeleted: number;
+  nodesCreated: number;
+  edgesCreated: number;
+  nodesCleared: number;
+  durationMs: number;
+}
+
+export class IncrementalReanalyzer {
+  private _graph: GraphBackend;
+  private projectPath: string;
+
+  constructor(graph: GraphBackend, projectPath: string) {
+    this._graph = graph;
+    this.projectPath = projectPath;
+  }
+
+  async reanalyze(
+    staleModules: StaleModule[],
+    _options: ReanalysisOptions = {}
+  ): Promise<ReanalysisResult> {
+    const startTime = Date.now();
+
+    if (staleModules.length === 0) {
+      return {
+        modulesReanalyzed: 0,
+        modulesDeleted: 0,
+        nodesCreated: 0,
+        edgesCreated: 0,
+        nodesCleared: 0,
+        durationMs: Date.now() - startTime,
+      };
+    }
+
+    const binary = findOrchestratorBinary();
+    if (!binary) {
+      throw new Error(
+        'grafema-orchestrator binary not found. ' +
+        'Build it with: cd packages/grafema-orchestrator && cargo build --release'
+      );
+    }
+
+    const socketPath = join(this.projectPath, '.grafema', 'rfdb.sock');
+
+    return new Promise<ReanalysisResult>((resolve, reject) => {
+      const child = spawn(binary, [
+        'analyze',
+        '--project', this.projectPath,
+        '--socket', socketPath,
+      ], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      let stderr = '';
+      child.stderr?.on('data', (data: Buffer) => {
+        stderr += data.toString();
+      });
+
+      child.on('error', (err) => {
+        reject(new Error(`Failed to start grafema-orchestrator: ${err.message}`));
+      });
+
+      child.on('close', (code) => {
+        if (code !== 0) {
+          reject(new Error(`grafema-orchestrator exited with code ${code}: ${stderr}`));
+          return;
+        }
+
+        resolve({
+          modulesReanalyzed: staleModules.filter(m => m.currentHash !== null).length,
+          modulesDeleted: staleModules.filter(m => m.currentHash === null).length,
+          nodesCreated: 0,
+          edgesCreated: 0,
+          nodesCleared: 0,
+          durationMs: Date.now() - startTime,
+        });
+      });
+    });
+  }
+}

package/src/core/ResourceRegistry.ts

@@ -0,0 +1,39 @@
+import type { Resource, ResourceId, ResourceRegistry as IResourceRegistry } from '@grafema/types';
+
+/**
+ * In-memory Resource registry for a single pipeline run.
+ * Created by Orchestrator at run start, cleared at run end.
+ *
+ * Thread safety: Not needed — Grafema runs plugins sequentially within
+ * each phase. Plugins are toposorted and run one at a time.
+ */
+export class ResourceRegistryImpl implements IResourceRegistry {
+  private resources = new Map<ResourceId, Resource>();
+
+  getOrCreate<T extends Resource>(id: ResourceId, factory: () => T): T {
+    let resource = this.resources.get(id);
+    if (!resource) {
+      resource = factory();
+      if (resource.id !== id) {
+        throw new Error(
+          `Resource factory returned resource with id "${resource.id}" but expected "${id}"`
+        );
+      }
+      this.resources.set(id, resource);
+    }
+    return resource as T;
+  }
+
+  get<T extends Resource>(id: ResourceId): T | undefined {
+    return this.resources.get(id) as T | undefined;
+  }
+
+  has(id: ResourceId): boolean {
+    return this.resources.has(id);
+  }
+
+  /** Clear all Resources. Called by Orchestrator at the end of a run. */
+  clear(): void {
+    this.resources.clear();
+  }
+}

package/src/core/SemanticId.ts

@@ -0,0 +1,423 @@
+/**
+ * SemanticId - Stable identifiers for code elements
+ *
+ * Semantic IDs provide stable identifiers for code elements that don't change
+ * when unrelated code is added/removed (no line numbers in IDs).
+ *
+ * Format: {file}->{scope_path}->{type}->{name}[#discriminator]
+ *
+ * Examples:
+ *   src/app.js->global->FUNCTION->processData
+ *   src/app.js->UserService->METHOD->login
+ *   src/app.js->getUser->if#0->CALL->console.log#0
+ *
+ * Special formats:
+ *   Singletons: net:stdio->__stdio__
+ *   External modules: EXTERNAL_MODULE->lodash
+ */
+
+/**
+ * Location in source file
+ */
+export interface Location {
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+}
+
+/**
+ * Scope context for semantic ID generation
+ */
+export interface ScopeContext {
+  /** Source file path */
+  file: string;
+  /** Array of scope names, e.g. ['MyClass', 'myMethod', 'if#1'] */
+  scopePath: string[];
+}
+
+/**
+ * Options for semantic ID generation
+ */
+export interface SemanticIdOptions {
+  /** Counter for disambiguation (#N) */
+  discriminator?: number;
+  /** Context string for special cases ([context]) */
+  context?: string;
+}
+
+/**
+ * Parsed semantic ID components
+ */
+export interface ParsedSemanticId {
+  file: string;
+  scopePath: string[];
+  type: string;
+  name: string;
+  discriminator?: number;
+  context?: string;
+}
+
+/**
+ * Item with name and location for discriminator computation
+ */
+export interface LocatedItem {
+  name: string;
+  location: Location;
+}
+
+// =============================================================================
+// Semantic ID v2
+// =============================================================================
+
+/**
+ * Parsed v2 semantic ID components.
+ *
+ * v2 format: file->TYPE->name[in:namedParent,h:xxxx]#N
+ *
+ * Key difference from v1: no scope path in ID. Only nearest named ancestor
+ * (namedParent) is encoded. Anonymous scopes (if, for, try) are invisible.
+ */
+export interface ParsedSemanticIdV2 {
+  file: string;
+  type: string;
+  name: string;
+  namedParent?: string;
+  contentHash?: string;
+  counter?: number;
+}
+
+/**
+ * Content hint data for computing content hash.
+ * Each node type supplies different hints for disambiguation.
+ */
+export interface ContentHashHints {
+  /** Number of arguments (CALL) or parameters (FUNCTION) */
+  arity?: number;
+  /** First literal argument value (CALL) */
+  firstLiteralArg?: string;
+  /** First parameter name (FUNCTION) */
+  firstParamName?: string;
+  /** RHS expression type (VARIABLE/CONSTANT) */
+  rhsType?: string;
+  /** First significant token of RHS (VARIABLE/CONSTANT) */
+  rhsToken?: string;
+  /** Object expression chain (PROPERTY_ACCESS) */
+  objectChain?: string;
+}
+
+/**
+ * Compute semantic ID for any node type.
+ *
+ * @param type - Node type (FUNCTION, CALL, VARIABLE, etc.)
+ * @param name - Node name
+ * @param context - Scope context from ScopeTracker
+ * @param options - Optional discriminator or context
+ * @returns Semantic ID string
+ */
+export function computeSemanticId(
+  type: string,
+  name: string,
+  context: ScopeContext,
+  options?: SemanticIdOptions
+): string {
+  const { file, scopePath } = context;
+  const scope = scopePath.length > 0 ? scopePath.join('->') : 'global';
+
+  let id = `${file}->${scope}->${type}->${name}`;
+
+  if (options?.discriminator !== undefined) {
+    id += `#${options.discriminator}`;
+  } else if (options?.context) {
+    id += `[${options.context}]`;
+  }
+
+  return id;
+}
+
+/**
+ * Parse semantic ID back to components.
+ *
+ * @param id - Semantic ID to parse
+ * @returns Parsed components or null if invalid
+ */
+export function parseSemanticId(id: string): ParsedSemanticId | null {
+  // Handle singletons
+  if (id.startsWith('net:stdio') || id.startsWith('net:request')) {
+    const [prefix, name] = id.split('->');
+    return {
+      file: '',
+      scopePath: [prefix],
+      type: 'SINGLETON',
+      name,
+      discriminator: undefined
+    };
+  }
+
+  if (id.startsWith('EXTERNAL_MODULE')) {
+    const [, name] = id.split('->');
+    return {
+      file: '',
+      scopePath: [],
+      type: 'EXTERNAL_MODULE',
+      name,
+      discriminator: undefined
+    };
+  }
+
+  const parts = id.split('->');
+  if (parts.length < 4) return null;
+
+  const file = parts[0];
+  const type = parts[parts.length - 2];
+  let name = parts[parts.length - 1];
+  const scopePath = parts.slice(1, -2);
+
+  // Parse discriminator or context
+  let discriminator: number | undefined;
+  let context: string | undefined;
+
+  const hashMatch = name.match(/^(.+)#(\d+)$/);
+  if (hashMatch) {
+    name = hashMatch[1];
+    discriminator = parseInt(hashMatch[2], 10);
+  }
+
+  const bracketMatch = name.match(/^(.+)\[(.+)\]$/);
+  if (bracketMatch) {
+    name = bracketMatch[1];
+    context = bracketMatch[2];
+  }
+
+  return { file, scopePath, type, name, discriminator, context };
+}
+
+/**
+ * Compute discriminator for items with same name in same scope.
+ * Uses line/column for stable ordering.
+ *
+ * @param items - All items in scope
+ * @param targetName - Name to find discriminator for
+ * @param targetLocation - Location of target item
+ * @returns Discriminator (0-based index among same-named items)
+ */
+export function computeDiscriminator(
+  items: LocatedItem[],
+  targetName: string,
+  targetLocation: Location
+): number {
+  // Filter items with same name
+  const sameNameItems = items.filter(item => item.name === targetName);
+
+  if (sameNameItems.length <= 1) {
+    return 0;
+  }
+
+  // Sort by line, then by column for stable ordering
+  sameNameItems.sort((a, b) => {
+    if (a.location.line !== b.location.line) {
+      return a.location.line - b.location.line;
+    }
+    return a.location.column - b.location.column;
+  });
+
+  // Find index of target
+  const index = sameNameItems.findIndex(
+    item =>
+      item.location.line === targetLocation.line &&
+      item.location.column === targetLocation.column
+  );
+
+  return index >= 0 ? index : 0;
+}
+
+// =============================================================================
+// Semantic ID v2 Functions
+// =============================================================================
+
+/**
+ * Compute v2 semantic ID.
+ *
+ * Format: file->TYPE->name                           (top-level, no collision)
+ * Format: file->TYPE->name[in:parent]                (nested, no collision)
+ * Format: file->TYPE->name[in:parent,h:xxxx]         (collision, hash disambiguates)
+ * Format: file->TYPE->name[in:parent,h:xxxx]#N       (hash collision, counter)
+ *
+ * @param type - Node type (FUNCTION, CALL, VARIABLE, etc.)
+ * @param name - Node name
+ * @param file - Source file path
+ * @param namedParent - Nearest named ancestor (undefined for top-level)
+ * @param contentHash - 4-hex content hash for disambiguation
+ * @param counter - Counter for hash collisions
+ */
+export function computeSemanticIdV2(
+  type: string,
+  name: string,
+  file: string,
+  namedParent?: string,
+  contentHash?: string,
+  counter?: number
+): string {
+  const brackets: string[] = [];
+  if (namedParent) brackets.push(`in:${namedParent}`);
+  if (contentHash) brackets.push(`h:${contentHash}`);
+
+  let id = `${file}->${type}->${name}`;
+  if (brackets.length > 0) {
+    id += `[${brackets.join(',')}]`;
+  }
+  if (counter !== undefined && counter > 0) {
+    id += `#${counter}`;
+  }
+  return id;
+}
+
+/**
+ * Parse v2 semantic ID back to components.
+ *
+ * Handles v2 format: file->TYPE->name[in:parent,h:xxxx]#N
+ * and special formats: net:stdio->__stdio__, EXTERNAL_MODULE->lodash
+ *
+ * @returns Parsed components or null if not a valid v2 ID
+ */
+export function parseSemanticIdV2(id: string): ParsedSemanticIdV2 | null {
+  // Handle grafema:// URI input — convert to compact first
+  if (id.startsWith('grafema://')) {
+    const scheme = 'grafema://';
+    const rest = id.slice(scheme.length);
+
+    const slashUnderscore = rest.indexOf('/_/');
+    const hashPos = rest.indexOf('#');
+
+    if (slashUnderscore !== -1 && (hashPos === -1 || slashUnderscore < hashPos)) {
+      // Virtual node: decode and re-parse
+      const encodedId = rest.slice(slashUnderscore + 3);
+      const decoded = encodedId
+        .replaceAll('%3E', '>').replaceAll('%3e', '>')
+        .replaceAll('%5B', '[').replaceAll('%5b', '[')
+        .replaceAll('%5D', ']').replaceAll('%5d', ']')
+        .replaceAll('%23', '#');
+      return parseSemanticIdV2(decoded);
+    }
+
+    if (hashPos !== -1) {
+      const pathPart = rest.slice(0, hashPos);
+      const fragment = rest.slice(hashPos + 1);
+      const decoded = fragment
+        .replaceAll('%3E', '>').replaceAll('%3e', '>')
+        .replaceAll('%5B', '[').replaceAll('%5b', '[')
+        .replaceAll('%5D', ']').replaceAll('%5d', ']')
+        .replaceAll('%23', '#');
+
+      if (decoded === 'MODULE') {
+        const segments = pathPart.split('/');
+        const host = segments[0];
+        const skip = (host === 'github.com' || host === 'gitlab.com' || host === 'bitbucket.org') ? 3 : 2;
+        const filePath = segments.slice(skip).join('/');
+        return { file: filePath, type: 'MODULE', name: filePath };
+      }
+
+      // Standard node: extract file and reconstruct compact ID
+      const segments = pathPart.split('/');
+      const host = segments[0];
+      const skip = (host === 'github.com' || host === 'gitlab.com' || host === 'bitbucket.org') ? 3 : 2;
+      const filePath = segments.slice(skip).join('/');
+      const compactId = `${filePath}->${decoded}`;
+      return parseSemanticIdV2(compactId);
+    }
+
+    return null;
+  }
+
+  // Handle singletons
+  if (id.startsWith('net:stdio') || id.startsWith('net:request')) {
+    const arrowIdx = id.indexOf('->');
+    if (arrowIdx === -1) return null;
+    return { file: '', type: 'SINGLETON', name: id.slice(arrowIdx + 2) };
+  }
+
+  if (id.startsWith('EXTERNAL_MODULE')) {
+    const arrowIdx = id.indexOf('->');
+    if (arrowIdx === -1) return null;
+    return { file: '', type: 'EXTERNAL_MODULE', name: id.slice(arrowIdx + 2) };
+  }
+
+  // v2 format: file->TYPE->name[in:parent,h:xxxx]#N
+  // Exactly two '->' delimiters: file->TYPE->rest
+  const firstArrow = id.indexOf('->');
+  if (firstArrow === -1) return null;
+
+  const secondArrow = id.indexOf('->', firstArrow + 2);
+  if (secondArrow === -1) return null;
+
+  const file = id.slice(0, firstArrow);
+  const type = id.slice(firstArrow + 2, secondArrow);
+  let rest = id.slice(secondArrow + 2);
+
+  // Check this isn't a v1 ID (v1 has 4+ parts, meaning rest contains '->')
+  // v2 names don't contain '->' in practice
+  if (rest.includes('->')) return null;
+
+  // Parse counter suffix: #N (only at the very end, after brackets)
+  let counter: number | undefined;
+  const counterMatch = rest.match(/#(\d+)$/);
+  if (counterMatch) {
+    counter = parseInt(counterMatch[1], 10);
+    rest = rest.slice(0, -counterMatch[0].length);
+  }
+
+  // Parse bracket content: [in:parent,h:xxxx]
+  let namedParent: string | undefined;
+  let contentHash: string | undefined;
+  let name = rest;
+
+  const bracketStart = rest.indexOf('[');
+  const bracketEnd = rest.lastIndexOf(']');
+  if (bracketStart !== -1 && bracketEnd === rest.length - 1) {
+    name = rest.slice(0, bracketStart);
+    const bracketContent = rest.slice(bracketStart + 1, bracketEnd);
+
+    for (const part of bracketContent.split(',')) {
+      const colonIdx = part.indexOf(':');
+      if (colonIdx === -1) continue;
+      const key = part.slice(0, colonIdx);
+      const value = part.slice(colonIdx + 1);
+      if (key === 'in') namedParent = value;
+      else if (key === 'h') contentHash = value;
+    }
+  }
+
+  return { file, type, name, namedParent, contentHash, counter };
+}
+
+/**
+ * FNV-1a hash function, returns 4-hex-char string.
+ *
+ * FNV-1a is simple, fast, and has good distribution for short strings.
+ * 4 hex chars = 16 bits = 65536 buckets.
+ *
+ * @param hints - Content data to hash
+ * @returns 4-char hex string (e.g., "a1b2")
+ */
+export function computeContentHash(hints: ContentHashHints): string {
+  const parts: string[] = [];
+  if (hints.arity !== undefined) parts.push(`a:${hints.arity}`);
+  if (hints.firstLiteralArg !== undefined) parts.push(`l:${hints.firstLiteralArg}`);
+  if (hints.firstParamName !== undefined) parts.push(`p:${hints.firstParamName}`);
+  if (hints.rhsType !== undefined) parts.push(`r:${hints.rhsType}`);
+  if (hints.rhsToken !== undefined) parts.push(`t:${hints.rhsToken}`);
+  if (hints.objectChain !== undefined) parts.push(`o:${hints.objectChain}`);
+
+  const input = parts.join('|');
+
+  // FNV-1a 32-bit
+  let hash = 0x811c9dc5; // FNV offset basis
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193); // FNV prime
+  }
+
+  // Truncate to 16 bits, format as 4-hex
+  const truncated = (hash >>> 0) & 0xffff;
+  return truncated.toString(16).padStart(4, '0');
+}