@grafema/core 0.1.0-alpha.1

package/src/core/ManifestStore.ts

@@ -0,0 +1,196 @@
+/**
+ * ManifestStore - simple persistent processing state storage
+ *
+ * Format: StableID|Phase|Status|Timestamp
+ * Operations: grep for search, sed for update
+ */
+
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from 'fs';
+import { execSync } from 'child_process';
+
+/**
+ * Processing status type
+ */
+export type ProcessingStatus = 'done' | 'in_progress' | 'pending' | 'crashed';
+
+/**
+ * Phase statistics
+ */
+export interface PhaseStats {
+  done: number;
+  in_progress: number;
+  pending: number;
+  crashed?: number;
+}
+
+/**
+ * All phases statistics
+ */
+export interface ManifestStats {
+  [phase: string]: PhaseStats;
+}
+
+export class ManifestStore {
+  private filePath: string;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+
+    // Create file if doesn't exist
+    if (!existsSync(filePath)) {
+      writeFileSync(filePath, '# StableID|Phase|Status|Timestamp\n', 'utf-8');
+    }
+  }
+
+  /**
+   * Check if file is processed in phase
+   * @param key - Full key like "PHASE|Plugin|Hash" or stableId
+   * @param phase - For backward compat, ignored if key contains |
+   */
+  isDone(key: string, phase?: string): boolean {
+    try {
+      // If key already contains pipe, use as-is, else build pattern
+      const searchKey = key.includes('|') ? key : `${key}|${phase}`;
+      const pattern = `^${searchKey}\\|done`;
+      execSync(`grep -q "${pattern}" "${this.filePath}"`, { encoding: 'utf-8' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Mark file as processed in phase
+   * @param key - Full key like "PHASE|Plugin|Hash" or stableId
+   * @param phase - For backward compat, ignored if key contains |
+   */
+  markDone(key: string, phase?: string): void {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const fullKey = key.includes('|') ? key : `${key}|${phase}`;
+    const line = `${fullKey}|done|${timestamp}\n`;
+
+    // Atomic append
+    appendFileSync(this.filePath, line, 'utf-8');
+  }
+
+  /**
+   * Mark file as in progress
+   * @param key - Full key like "PHASE|Plugin|Hash" or stableId
+   * @param phase - For backward compat, ignored if key contains |
+   */
+  markInProgress(key: string, phase?: string): void {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const fullKey = key.includes('|') ? key : `${key}|${phase}`;
+    const line = `${fullKey}|in_progress|${timestamp}\n`;
+
+    appendFileSync(this.filePath, line, 'utf-8');
+  }
+
+  /**
+   * Get status of file in phase
+   * @param key - Full key like "PHASE|Plugin|Hash" or stableId
+   * @param phase - For backward compat, ignored if key contains |
+   */
+  getStatus(key: string, phase?: string): ProcessingStatus {
+    try {
+      const searchKey = key.includes('|') ? key : `${key}|${phase}`;
+      const pattern = `^${searchKey}\\|`;
+      const result = execSync(
+        `grep "${pattern}" "${this.filePath}" | tail -1`,
+        { encoding: 'utf-8' }
+      ).trim();
+
+      if (!result) return 'pending';
+
+      const parts = result.split('|');
+      // Status is after the key parts
+      const statusIndex = key.includes('|') ? key.split('|').length : 2;
+      return parts[statusIndex] as ProcessingStatus;
+    } catch {
+      return 'pending';
+    }
+  }
+
+  /**
+   * Get all files for phase with specific status
+   */
+  getByStatus(phase: string, status: ProcessingStatus): string[] {
+    try {
+      const pattern = `\\|${phase}\\|${status}\\|`;
+      const result = execSync(
+        `grep "${pattern}" "${this.filePath}" | cut -d'|' -f1`,
+        { encoding: 'utf-8' }
+      ).trim();
+
+      return result ? result.split('\n') : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Get statistics by phases
+   */
+  getStats(): ManifestStats {
+    const content = readFileSync(this.filePath, 'utf-8');
+    const lines = content.split('\n').filter(l => l && !l.startsWith('#'));
+
+    const stats: ManifestStats = {};
+
+    for (const line of lines) {
+      const parts = line.split('|');
+      const phase = parts[1];
+      const status = parts[2] as ProcessingStatus;
+
+      if (!phase || !status) continue;
+
+      if (!stats[phase]) {
+        stats[phase] = { done: 0, in_progress: 0, pending: 0 };
+      }
+
+      if (status in stats[phase]) {
+        (stats[phase] as unknown as Record<string, number>)[status]++;
+      }
+    }
+
+    return stats;
+  }
+
+  /**
+   * Clean up stale in_progress (crashed processes)
+   * @param olderThanSeconds - older than N seconds considered dead
+   */
+  cleanupStaleProgress(olderThanSeconds: number = 300): void {
+    const now = Math.floor(Date.now() / 1000);
+    const content = readFileSync(this.filePath, 'utf-8');
+    const lines = content.split('\n');
+
+    const cleaned = lines.map(line => {
+      if (!line || line.startsWith('#')) return line;
+
+      const parts = line.split('|');
+      const status = parts[2];
+      const timestamp = parts[3];
+
+      if (status === 'in_progress' && timestamp) {
+        const age = now - parseInt(timestamp);
+        if (age > olderThanSeconds) {
+          // Mark as crashed (process died)
+          parts[2] = 'crashed';
+          return parts.join('|');
+        }
+      }
+
+      return line;
+    });
+
+    writeFileSync(this.filePath, cleaned.join('\n'), 'utf-8');
+  }
+
+  /**
+   * Clear entire manifest (for testing)
+   */
+  clear(): void {
+    writeFileSync(this.filePath, '# StableID|Phase|Status|Timestamp\n', 'utf-8');
+  }
+}

package/src/core/NodeFactory.ts

@@ -0,0 +1,274 @@
+/**
+ * NodeFactory - centralized graph node creation
+ *
+ * Single point for creating all node types with:
+ * - Required field validation
+ * - Standard field set for each type
+ * - Automatic ID generation
+ *
+ * Delegates creation to node contracts from ./nodes/
+ */
+
+import { createHash } from 'crypto';
+import { basename, relative } from 'path';
+
+import {
+  ServiceNode,
+  EntrypointNode,
+  ModuleNode,
+  FunctionNode,
+  ScopeNode,
+  CallSiteNode,
+  MethodCallNode,
+  VariableDeclarationNode,
+  ConstantNode,
+  LiteralNode,
+  ExternalStdioNode,
+  EventListenerNode,
+  HttpRequestNode,
+  DatabaseQueryNode,
+  type EntrypointType,
+  type EntrypointTrigger,
+} from './nodes/index.js';
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ServiceOptions {
+  version?: string;
+  entrypoint?: string;
+  discoveryMethod?: string;
+  description?: string;
+  dependencies?: string[];
+  serviceType?: string;
+  testFiles?: string[];
+  metadata?: {
+    type?: string;
+    testFiles?: string[];
+  };
+}
+
+interface EntrypointOptions {
+  id?: string;
+  name?: string;
+  trigger?: EntrypointTrigger;
+  source?: string;
+  serviceId?: string;
+}
+
+interface ModuleOptions {
+  contentHash?: string;
+  isTest?: boolean;
+}
+
+interface FunctionOptions {
+  async?: boolean;
+  generator?: boolean;
+  exported?: boolean;
+  arrowFunction?: boolean;
+  parentScopeId?: string;
+  isClassMethod?: boolean;
+  className?: string;
+  params?: string[];
+  counter?: number;
+}
+
+interface ScopeOptions {
+  name?: string;
+  conditional?: boolean;
+  parentScopeId?: string;
+  parentFunctionId?: string;
+  capturesFrom?: string[];
+  counter?: number;
+}
+
+interface CallSiteOptions {
+  parentScopeId?: string;
+  counter?: number;
+}
+
+interface MethodCallOptions {
+  parentScopeId?: string;
+  args?: unknown[];
+  counter?: number;
+}
+
+interface VariableOptions {
+  parentScopeId?: string;
+  counter?: number;
+}
+
+interface ConstantOptions {
+  value?: unknown;
+  parentScopeId?: string;
+  counter?: number;
+}
+
+interface LiteralOptions {
+  parentCallId?: string;
+  argIndex?: number;
+  counter?: number;
+}
+
+interface EventListenerOptions {
+  column?: number;
+  parentScopeId?: string;
+  callbackArg?: string;
+  counter?: number;
+}
+
+interface HttpRequestOptions {
+  column?: number;
+  parentScopeId?: string;
+  counter?: number;
+}
+
+interface DatabaseQueryOptions {
+  parentScopeId?: string;
+}
+
+// Validator type for node classes
+interface NodeValidator {
+  validate(node: BaseNodeRecord): string[];
+}
+
+export class NodeFactory {
+  /**
+   * Create SERVICE node
+   */
+  static createService(name: string, projectPath: string, options: ServiceOptions = {}) {
+    return ServiceNode.create(name, projectPath, options);
+  }
+
+  /**
+   * Create ENTRYPOINT node
+   */
+  static createEntrypoint(file: string, entrypointType: EntrypointType, options: EntrypointOptions = {}) {
+    return EntrypointNode.create(file, entrypointType, options);
+  }
+
+  /**
+   * Create MODULE node
+   */
+  static createModule(filePath: string, projectPath: string, options: ModuleOptions = {}) {
+    if (!filePath) throw new Error('NodeFactory.createModule: filePath is required');
+    if (!projectPath) throw new Error('NodeFactory.createModule: projectPath is required');
+
+    const contentHash = options.contentHash || this._hashFile(filePath);
+    const relativePath = relative(projectPath, filePath) || basename(filePath);
+
+    return ModuleNode.create(filePath, relativePath, contentHash, options);
+  }
+
+  /**
+   * Create FUNCTION node
+   */
+  static createFunction(name: string, file: string, line: number, column: number, options: FunctionOptions = {}) {
+    return FunctionNode.create(name, file, line, column, options);
+  }
+
+  /**
+   * Create SCOPE node
+   */
+  static createScope(scopeType: string, file: string, line: number, options: ScopeOptions = {}) {
+    return ScopeNode.create(scopeType, file, line, options);
+  }
+
+  /**
+   * Create CALL_SITE node
+   */
+  static createCallSite(targetName: string, file: string, line: number, column: number, options: CallSiteOptions = {}) {
+    return CallSiteNode.create(targetName, file, line, column, options);
+  }
+
+  /**
+   * Create METHOD_CALL node
+   */
+  static createMethodCall(objectName: string | undefined, methodName: string, file: string, line: number, column: number, options: MethodCallOptions = {}) {
+    return MethodCallNode.create(objectName, methodName, file, line, column, options);
+  }
+
+  /**
+   * Create VARIABLE_DECLARATION node
+   */
+  static createVariableDeclaration(name: string, file: string, line: number, column: number, options: VariableOptions = {}) {
+    return VariableDeclarationNode.create(name, file, line, column, options);
+  }
+
+  /**
+   * Create CONSTANT node
+   */
+  static createConstant(name: string, file: string, line: number, column: number, options: ConstantOptions = {}) {
+    return ConstantNode.create(name, file, line, column, options);
+  }
+
+  /**
+   * Create LITERAL node
+   */
+  static createLiteral(value: unknown, file: string, line: number, column: number, options: LiteralOptions = {}) {
+    return LiteralNode.create(value, file, line, column, options);
+  }
+
+  /**
+   * Create EXTERNAL_STDIO node (singleton)
+   */
+  static createExternalStdio() {
+    return ExternalStdioNode.create();
+  }
+
+  /**
+   * Create EVENT_LISTENER node
+   */
+  static createEventListener(eventName: string, objectName: string | undefined, file: string, line: number, options: EventListenerOptions = {}) {
+    return EventListenerNode.create(eventName, objectName, file, line, options);
+  }
+
+  /**
+   * Create HTTP_REQUEST node
+   */
+  static createHttpRequest(url: string | undefined, method: string | undefined, file: string, line: number, options: HttpRequestOptions = {}) {
+    return HttpRequestNode.create(url, method, file, line, options);
+  }
+
+  /**
+   * Create DATABASE_QUERY node
+   */
+  static createDatabaseQuery(query: string | undefined, operation: string | undefined, file: string, line: number, options: DatabaseQueryOptions = {}) {
+    return DatabaseQueryNode.create(query, operation, file, line, options);
+  }
+
+  /**
+   * Validate node by its type
+   */
+  static validate(node: BaseNodeRecord): string[] {
+    const validators: Record<string, NodeValidator> = {
+      'SERVICE': ServiceNode,
+      'ENTRYPOINT': EntrypointNode,
+      'MODULE': ModuleNode,
+      'FUNCTION': FunctionNode,
+      'SCOPE': ScopeNode,
+      'CALL_SITE': CallSiteNode,
+      'METHOD_CALL': MethodCallNode,
+      'VARIABLE_DECLARATION': VariableDeclarationNode,
+      'CONSTANT': ConstantNode,
+      'LITERAL': LiteralNode,
+      'EXTERNAL_STDIO': ExternalStdioNode,
+      'EVENT_LISTENER': EventListenerNode,
+      'HTTP_REQUEST': HttpRequestNode,
+      'DATABASE_QUERY': DatabaseQueryNode
+    };
+
+    const validator = validators[node.type];
+    if (!validator) {
+      return [`Unknown node type: ${node.type}`];
+    }
+
+    return validator.validate(node);
+  }
+
+  /**
+   * Helper: hash file path for stable ID
+   */
+  static _hashFile(filePath: string): string {
+    return createHash('md5').update(filePath).digest('hex').substring(0, 12);
+  }
+}

package/src/core/NodeId.ts

@@ -0,0 +1,257 @@
+/**
+ * Deterministic Node ID generation scheme for the graph
+ *
+ * Format: TYPE|SCOPE|FILE|IDENTIFIER|LINE:COL
+ *
+ * Components:
+ * - TYPE: node type (MODULE, FUNCTION, CLASS, METHOD, VARIABLE, etc.)
+ * - SCOPE: context/scope (path to parent or project)
+ * - FILE: relative file path from project root
+ * - IDENTIFIER: entity name (for MODULE can be empty)
+ * - LINE:COL: position in file (for uniqueness of anonymous functions)
+ *
+ * Examples:
+ * MODULE|/project|src/index.js||0:0
+ * FUNCTION|/project|src/index.js|handleRequest|42:5
+ * CLASS|/project|src/User.js|User|10:0
+ * METHOD|User|src/User.js|login|25:2
+ * VARIABLE|handleRequest|src/index.js|userId|45:10
+ * EXTERNAL_MODULE|/project||express|0:0
+ */
+
+import { createHash } from 'crypto';
+
+/**
+ * Parameters for computing Node ID
+ */
+export interface NodeIdParams {
+  type: string;
+  scope?: string;
+  file?: string;
+  identifier?: string;
+  line?: number;
+  column?: number;
+}
+
+/**
+ * Parsed Node ID components
+ */
+export interface ParsedNodeId {
+  type: string;
+  scope: string;
+  file: string;
+  identifier: string;
+  line: number;
+  column: number;
+}
+
+/**
+ * Compute deterministic Node ID
+ */
+export function computeNodeId({
+  type,
+  scope = '',
+  file = '',
+  identifier = '',
+  line = 0,
+  column = 0
+}: NodeIdParams): string {
+  // Normalize: remove empty values
+  const parts = [
+    type,
+    scope || '',
+    file || '',
+    identifier || '',
+    `${line}:${column}`
+  ];
+
+  return parts.join('|');
+}
+
+/**
+ * Compute u128 numeric ID from string (for Rust backend)
+ * Uses SHA-256 hash and takes first 16 bytes
+ */
+export function computeNumericId(stringId: string): bigint {
+  const hash = createHash('sha256').update(stringId).digest();
+
+  // Take first 16 bytes (128 bits) and convert to BigInt
+  let numericId = 0n;
+  for (let i = 0; i < 16; i++) {
+    numericId = (numericId << 8n) | BigInt(hash[i]);
+  }
+
+  return numericId;
+}
+
+/**
+ * Parse Node ID back into components
+ */
+export function parseNodeId(nodeId: string): ParsedNodeId {
+  const parts = nodeId.split('|');
+
+  if (parts.length !== 5) {
+    throw new Error(`Invalid Node ID format: ${nodeId}`);
+  }
+
+  const [lineStr, columnStr] = parts[4].split(':');
+
+  return {
+    type: parts[0],
+    scope: parts[1],
+    file: parts[2],
+    identifier: parts[3],
+    line: Number(lineStr),
+    column: Number(columnStr)
+  };
+}
+
+/**
+ * Helper for creating MODULE ID
+ */
+export function createModuleId(filePath: string, projectPath: string = '/project'): string {
+  return computeNodeId({
+    type: 'MODULE',
+    scope: projectPath,
+    file: filePath,
+    identifier: '',
+    line: 0,
+    column: 0
+  });
+}
+
+/**
+ * Helper for creating FUNCTION ID
+ */
+export function createFunctionId(
+  filePath: string,
+  functionName: string,
+  line: number,
+  column: number,
+  scope: string = '/project'
+): string {
+  return computeNodeId({
+    type: 'FUNCTION',
+    scope,
+    file: filePath,
+    identifier: functionName,
+    line,
+    column
+  });
+}
+
+/**
+ * Helper for creating CLASS ID
+ */
+export function createClassId(
+  filePath: string,
+  className: string,
+  line: number,
+  column: number,
+  scope: string = '/project'
+): string {
+  return computeNodeId({
+    type: 'CLASS',
+    scope,
+    file: filePath,
+    identifier: className,
+    line,
+    column
+  });
+}
+
+/**
+ * Helper for creating METHOD ID
+ */
+export function createMethodId(
+  filePath: string,
+  className: string,
+  methodName: string,
+  line: number,
+  column: number
+): string {
+  return computeNodeId({
+    type: 'METHOD',
+    scope: className, // Scope = parent class
+    file: filePath,
+    identifier: methodName,
+    line,
+    column
+  });
+}
+
+/**
+ * Helper for creating VARIABLE ID
+ */
+export function createVariableId(
+  filePath: string,
+  varName: string,
+  line: number,
+  column: number,
+  scope: string
+): string {
+  return computeNodeId({
+    type: 'VARIABLE',
+    scope, // Scope = containing function/class
+    file: filePath,
+    identifier: varName,
+    line,
+    column
+  });
+}
+
+/**
+ * Helper for creating EXTERNAL_MODULE ID
+ */
+export function createExternalModuleId(
+  moduleName: string,
+  projectPath: string = '/project'
+): string {
+  return computeNodeId({
+    type: 'EXTERNAL_MODULE',
+    scope: projectPath,
+    file: '',
+    identifier: moduleName,
+    line: 0,
+    column: 0
+  });
+}
+
+/**
+ * Helper for creating IMPORT ID
+ */
+export function createImportId(
+  filePath: string,
+  source: string,
+  localName: string,
+  line: number,
+  scope: string = '/project'
+): string {
+  return computeNodeId({
+    type: 'IMPORT',
+    scope,
+    file: filePath,
+    identifier: `${source}:${localName}`,
+    line,
+    column: 0
+  });
+}
+
+/**
+ * Helper for creating EXPORT ID
+ */
+export function createExportId(
+  filePath: string,
+  exportName: string,
+  line: number,
+  scope: string = '/project'
+): string {
+  return computeNodeId({
+    type: 'EXPORT',
+    scope,
+    file: filePath,
+    identifier: exportName,
+    line,
+    column: 0
+  });
+}