@grafema/core 0.2.5-beta → 0.2.7

package/src/core/nodes/ExternalFunctionNode.ts

@@ -0,0 +1,77 @@
+/**
+ * ExternalFunctionNode - contract for EXTERNAL_FUNCTION node
+ *
+ * Represents an external function from a Node.js built-in module
+ * (e.g., fs.readFile, path.join, crypto.createHash).
+ *
+ * Created lazily by NodejsBuiltinsResolver when a call to a builtin function is detected.
+ *
+ * ID format: EXTERNAL_FUNCTION:{module}.{function}
+ * Example: EXTERNAL_FUNCTION:fs.readFile, EXTERNAL_FUNCTION:path.join
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+import type { SecurityCategory } from '../../data/builtins/types.js';
+
+interface ExternalFunctionNodeRecord extends BaseNodeRecord {
+  type: 'EXTERNAL_FUNCTION';
+  isBuiltin: boolean;
+  security?: SecurityCategory;
+  pure?: boolean;
+}
+
+interface ExternalFunctionOptions {
+  security?: SecurityCategory;
+  pure?: boolean;
+}
+
+export class ExternalFunctionNode {
+  static readonly TYPE = 'EXTERNAL_FUNCTION' as const;
+
+  static readonly REQUIRED = ['name', 'isBuiltin'] as const;
+  static readonly OPTIONAL = ['security', 'pure'] as const;
+
+  /**
+   * Create EXTERNAL_FUNCTION node
+   *
+   * @param moduleName - Normalized module name (e.g., 'fs', 'path', 'crypto')
+   * @param functionName - Function name (e.g., 'readFile', 'join')
+   * @param options - Optional security and pure fields
+   * @returns ExternalFunctionNodeRecord
+   */
+  static create(moduleName: string, functionName: string, options: ExternalFunctionOptions = {}): ExternalFunctionNodeRecord {
+    if (!moduleName) throw new Error('ExternalFunctionNode.create: moduleName is required');
+    if (!functionName) throw new Error('ExternalFunctionNode.create: functionName is required');
+
+    return {
+      id: `EXTERNAL_FUNCTION:${moduleName}.${functionName}`,
+      type: this.TYPE,
+      name: `${moduleName}.${functionName}`,
+      file: '',
+      line: 0,
+      isBuiltin: true,
+      ...(options.security && { security: options.security }),
+      ...(options.pure !== undefined && { pure: options.pure }),
+    };
+  }
+
+  static validate(node: ExternalFunctionNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+
+    if (!node.name) {
+      errors.push('Missing required field: name');
+    }
+
+    if (node.isBuiltin === undefined) {
+      errors.push('Missing required field: isBuiltin');
+    }
+
+    return errors;
+  }
+}
+
+export type { ExternalFunctionNodeRecord, ExternalFunctionOptions };

package/src/core/nodes/FetchRequestNode.ts

@@ -0,0 +1,105 @@
+/**
+ * FetchRequestNode - contract for http:request nodes
+ *
+ * Represents an HTTP request call site detected from fetch(), axios,
+ * or custom wrapper patterns. Created by FetchAnalyzer.
+ *
+ * NOT the same as HttpRequestNode (type: HTTP_REQUEST), which is the
+ * older contract for generic HTTP request nodes created by GraphBuilder.
+ * This uses namespaced type 'http:request' for semantic grouping.
+ *
+ * ID format: http:request#${method}:${url}#${file}#${line}
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface FetchRequestNodeRecord extends BaseNodeRecord {
+  type: 'http:request';
+  method: string;
+  url: string;
+  library: string;
+  file: string;
+  line: number;
+  column: number;
+  staticUrl: 'yes' | 'no';
+}
+
+interface FetchRequestNodeOptions {
+  /** Human-readable name (e.g., "GET /api/users") */
+  name?: string;
+  /** How the method was determined */
+  methodSource?: 'explicit' | 'default' | 'unknown';
+  /** ID of CALL node for response.json(), response.text(), etc. */
+  responseDataNode?: string | null;
+}
+
+export class FetchRequestNode {
+  static readonly TYPE = 'http:request' as const;
+
+  static readonly REQUIRED = ['method', 'url', 'library', 'file', 'line', 'column', 'staticUrl'] as const;
+  static readonly OPTIONAL = ['name', 'methodSource', 'responseDataNode'] as const;
+
+  /**
+   * Create http:request node
+   *
+   * @param method - HTTP method (GET, POST, etc.)
+   * @param url - Request URL or 'dynamic'/'unknown'
+   * @param library - Library name ('fetch', 'axios', or custom wrapper name)
+   * @param file - File path where request is made
+   * @param line - Line number
+   * @param column - Column number
+   * @param options - Optional fields
+   */
+  static create(
+    method: string,
+    url: string,
+    library: string,
+    file: string,
+    line: number,
+    column: number,
+    options: FetchRequestNodeOptions = {}
+  ): FetchRequestNodeRecord {
+    const id = `http:request#${method}:${url}#${file}#${line}`;
+
+    const node: FetchRequestNodeRecord = {
+      id,
+      type: this.TYPE,
+      name: options.name || `${method} ${url}`,
+      method,
+      url,
+      library,
+      file,
+      line,
+      column,
+      staticUrl: url !== 'dynamic' && url !== 'unknown' ? 'yes' : 'no',
+    };
+
+    if (options.methodSource !== undefined) {
+      (node as Record<string, unknown>).methodSource = options.methodSource;
+    }
+    if (options.responseDataNode !== undefined) {
+      (node as Record<string, unknown>).responseDataNode = options.responseDataNode;
+    }
+
+    return node;
+  }
+
+  /**
+   * Validate http:request node structure
+   */
+  static validate(node: FetchRequestNodeRecord): string[] {
+    const errors: string[] = [];
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+    const record = node as unknown as Record<string, unknown>;
+    for (const field of this.REQUIRED) {
+      if (record[field] === undefined) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+    return errors;
+  }
+}
+
+export type { FetchRequestNodeRecord, FetchRequestNodeOptions };

package/src/core/nodes/HttpRouteNode.ts

@@ -0,0 +1,113 @@
+/**
+ * HttpRouteNode - contract for http:route nodes
+ *
+ * Represents an HTTP route endpoint detected from framework patterns.
+ * Used by ExpressAnalyzer, ExpressRouteAnalyzer, and NestJSRouteAnalyzer.
+ *
+ * Each analyzer may add different optional fields, but all share
+ * the same core: method, path, file, line.
+ *
+ * ID format: http:route#${method}:${path}#${file}#${line}
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface HttpRouteNodeRecord extends BaseNodeRecord {
+  type: 'http:route';
+  method: string;
+  path: string;
+  file: string;
+  line: number;
+  column?: number;
+}
+
+interface HttpRouteNodeOptions {
+  /** Human-readable name (e.g., "GET /api/users") */
+  name?: string;
+  column?: number;
+
+  // Express-specific
+  /** Local path before mounting */
+  localPath?: string;
+  /** Router/app variable name this route is mounted on */
+  mountedOn?: string;
+  /** Router variable name (alternative to mountedOn) */
+  routerName?: string;
+
+  // NestJS-specific
+  /** Framework that defined this route */
+  framework?: string;
+  /** Handler function name (e.g., "UserController.findAll") */
+  handlerName?: string;
+
+  /** Arbitrary metadata (handler location, etc.) */
+  metadata?: Record<string, unknown>;
+}
+
+export class HttpRouteNode {
+  static readonly TYPE = 'http:route' as const;
+
+  static readonly REQUIRED = ['method', 'path', 'file', 'line'] as const;
+  static readonly OPTIONAL = [
+    'name', 'column', 'localPath', 'mountedOn', 'routerName',
+    'framework', 'handlerName', 'metadata'
+  ] as const;
+
+  /**
+   * Create http:route node
+   *
+   * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
+   * @param path - Route path (e.g., "/api/users", "/users/:id")
+   * @param file - File path where route is defined
+   * @param line - Line number of route definition
+   * @param options - Optional fields for framework-specific metadata
+   */
+  static create(
+    method: string,
+    path: string,
+    file: string,
+    line: number,
+    options: HttpRouteNodeOptions = {}
+  ): HttpRouteNodeRecord {
+    const id = `http:route#${method}:${path}#${file}#${line}`;
+
+    const node: HttpRouteNodeRecord = {
+      id,
+      type: this.TYPE,
+      name: options.name || `${method} ${path}`,
+      method,
+      path,
+      file,
+      line,
+    };
+
+    if (options.column !== undefined) node.column = options.column;
+    if (options.localPath !== undefined) (node as Record<string, unknown>).localPath = options.localPath;
+    if (options.mountedOn !== undefined) (node as Record<string, unknown>).mountedOn = options.mountedOn;
+    if (options.routerName !== undefined) (node as Record<string, unknown>).routerName = options.routerName;
+    if (options.framework !== undefined) (node as Record<string, unknown>).framework = options.framework;
+    if (options.handlerName !== undefined) (node as Record<string, unknown>).handlerName = options.handlerName;
+    if (options.metadata !== undefined) node.metadata = options.metadata;
+
+    return node;
+  }
+
+  /**
+   * Validate http:route node structure
+   */
+  static validate(node: HttpRouteNodeRecord): string[] {
+    const errors: string[] = [];
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+    const record = node as unknown as Record<string, unknown>;
+    for (const field of this.REQUIRED) {
+      if (record[field] === undefined) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+    return errors;
+  }
+}
+
+export type { HttpRouteNodeRecord, HttpRouteNodeOptions };

package/src/core/nodes/NodeKind.ts

@@ -25,6 +25,7 @@ export const NODE_TYPE = {
   CONSTANT: 'CONSTANT',
   LITERAL: 'LITERAL',
   EXPRESSION: 'EXPRESSION',  // Generic expression node for data flow tracking
+  TYPE_PARAMETER: 'TYPE_PARAMETER',
 
   // Module system
   MODULE: 'MODULE',

package/src/core/nodes/ReactNode.ts

@@ -0,0 +1,78 @@
+/**
+ * ReactNode - contract for React domain-specific nodes
+ *
+ * Handles all namespaced types from ReactAnalyzer:
+ * - react:component, react:state, react:effect, react:layout-effect,
+ *   react:insertion-effect, react:callback, react:memo, react:ref,
+ *   react:reducer, react:context, react:context-use, react:imperative-handle
+ * - dom:event
+ * - browser:timer, browser:blocking, browser:async, browser:storage,
+ *   browser:dom, browser:history, browser:clipboard, browser:geolocation,
+ *   browser:media-query
+ * - canvas:draw
+ *
+ * Issue nodes (issue:stale-closure, issue:missing-cleanup, issue:raf-leak)
+ * are handled by the existing IssueNode contract.
+ *
+ * These nodes use domain-specific ID formats generated by the analyzer
+ * helpers (react-internal/), so the contract provides a generic create()
+ * that validates required fields and brands the node.
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+import { getNamespace } from './NodeKind.js';
+
+export interface ReactNodeRecord extends BaseNodeRecord {
+  type: string;
+  [key: string]: unknown;
+}
+
+const REACT_NAMESPACES = ['react', 'dom', 'browser', 'canvas'] as const;
+
+export class ReactNode {
+  static readonly REQUIRED = ['id', 'type', 'file', 'line'] as const;
+
+  /**
+   * Create a React domain node from pre-built fields.
+   *
+   * The analyzers' helper modules (react-internal/) build the full node
+   * shape including ID. This method validates required fields and returns
+   * a properly typed record ready for branding.
+   *
+   * @param fields - Complete node fields including id, type, file, line
+   * @returns ReactNodeRecord ready for brandNodeInternal()
+   */
+  static create<T extends { id: string; type: string; file: string; line: number }>(fields: T): ReactNodeRecord {
+    if (!fields.id) throw new Error('ReactNode.create: id is required');
+    if (!fields.type) throw new Error('ReactNode.create: type is required');
+    if (!fields.file) throw new Error('ReactNode.create: file is required');
+    if (fields.line === undefined) throw new Error('ReactNode.create: line is required');
+
+    return fields as unknown as ReactNodeRecord;
+  }
+
+  /**
+   * Validate a React domain node.
+   */
+  static validate(node: BaseNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (!ReactNode.isReactDomainType(node.type)) {
+      errors.push(`Expected react/dom/browser/canvas type, got ${node.type}`);
+    }
+
+    if (!node.id) errors.push('Missing required field: id');
+    if (!node.file) errors.push('Missing required field: file');
+
+    return errors;
+  }
+
+  /**
+   * Check if a type belongs to the React domain.
+   */
+  static isReactDomainType(type: string): boolean {
+    if (!type) return false;
+    const ns = getNamespace(type);
+    return ns !== null && (REACT_NAMESPACES as readonly string[]).includes(ns);
+  }
+}

package/src/core/nodes/RustCallNode.ts

@@ -0,0 +1,96 @@
+/**
+ * RustCallNode - contract for RUST_CALL node
+ *
+ * Represents a function/method/macro call inside a Rust function or method,
+ * extracted by RustAnalyzer. Tracks side effects (fs:write, panic, io:print, etc.).
+ *
+ * ID format: RUST_CALL#<parentName>#<line>#<column>#<file>
+ * Example: RUST_CALL#parse_file#42#8#src/parser.rs
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+type RustCallType = 'function' | 'method' | 'macro';
+
+interface RustCallNodeRecord extends BaseNodeRecord {
+  type: 'RUST_CALL';
+  column: number;
+  callType: RustCallType;
+  argsCount: number;
+  receiver: string | null;
+  method: string | null;
+  sideEffect: string | null;
+}
+
+interface RustCallNodeOptions {
+  name?: string | null;
+  receiver?: string | null;
+  method?: string | null;
+  sideEffect?: string | null;
+}
+
+export class RustCallNode {
+  static readonly TYPE = 'RUST_CALL' as const;
+
+  static readonly REQUIRED = ['file', 'line', 'column', 'callType', 'argsCount'] as const;
+  static readonly OPTIONAL = ['name', 'receiver', 'method', 'sideEffect'] as const;
+
+  /**
+   * Create RUST_CALL node
+   *
+   * @param parentName - Name of the containing function/method (used in ID)
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param callType - "function" | "method" | "macro"
+   * @param argsCount - Number of arguments
+   * @param options - Optional call attributes (name, receiver, method, sideEffect)
+   */
+  static create(
+    parentName: string,
+    file: string,
+    line: number,
+    column: number,
+    callType: RustCallType,
+    argsCount: number,
+    options: RustCallNodeOptions = {}
+  ): RustCallNodeRecord {
+    if (!file) throw new Error('RustCallNode.create: file is required');
+    if (line === undefined) throw new Error('RustCallNode.create: line is required');
+    if (column === undefined) throw new Error('RustCallNode.create: column is required');
+    if (!callType) throw new Error('RustCallNode.create: callType is required');
+
+    return {
+      id: `RUST_CALL#${parentName}#${line}#${column}#${file}`,
+      type: this.TYPE,
+      name: options.name || undefined,
+      file,
+      line,
+      column,
+      callType,
+      argsCount,
+      receiver: options.receiver || null,
+      method: options.method || null,
+      sideEffect: options.sideEffect || null,
+    };
+  }
+
+  static validate(node: BaseNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+
+    const nodeRecord = node as unknown as Record<string, unknown>;
+    for (const field of this.REQUIRED) {
+      if (nodeRecord[field] === undefined || nodeRecord[field] === null) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+
+    return errors;
+  }
+}
+
+export type { RustCallNodeRecord, RustCallType };

package/src/core/nodes/RustFunctionNode.ts

@@ -0,0 +1,112 @@
+/**
+ * RustFunctionNode - contract for RUST_FUNCTION node
+ *
+ * Represents a top-level Rust function extracted by RustAnalyzer.
+ * Includes #[napi] attribute detection for FFI linking.
+ *
+ * ID format: RUST_FUNCTION#<name>#<file>#<line>
+ * Example: RUST_FUNCTION#parse_file#src/parser.rs#42
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface RustFunctionNodeRecord extends BaseNodeRecord {
+  type: 'RUST_FUNCTION';
+  column: number;
+  pub: boolean;
+  async: boolean;
+  unsafe: boolean;
+  const: boolean;
+  napi: boolean;
+  napiJsName: string | null;
+  napiConstructor: boolean;
+  napiGetter: string | null;
+  napiSetter: string | null;
+  params: string[];
+  returnType: string | null;
+  unsafeBlocks: number;
+}
+
+interface RustFunctionNodeOptions {
+  pub?: boolean;
+  async?: boolean;
+  unsafe?: boolean;
+  const?: boolean;
+  napi?: boolean;
+  napiJsName?: string | null;
+  napiConstructor?: boolean;
+  napiGetter?: string | null;
+  napiSetter?: string | null;
+  params?: string[];
+  returnType?: string | null;
+  unsafeBlocks?: number;
+}
+
+export class RustFunctionNode {
+  static readonly TYPE = 'RUST_FUNCTION' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['pub', 'async', 'unsafe', 'const', 'napi', 'napiJsName', 'napiConstructor', 'napiGetter', 'napiSetter', 'params', 'returnType', 'unsafeBlocks'] as const;
+
+  /**
+   * Create RUST_FUNCTION node
+   *
+   * @param name - Function name
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Optional function attributes
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: RustFunctionNodeOptions = {}
+  ): RustFunctionNodeRecord {
+    if (!name) throw new Error('RustFunctionNode.create: name is required');
+    if (!file) throw new Error('RustFunctionNode.create: file is required');
+    if (line === undefined) throw new Error('RustFunctionNode.create: line is required');
+    if (column === undefined) throw new Error('RustFunctionNode.create: column is required');
+
+    return {
+      id: `RUST_FUNCTION#${name}#${file}#${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column,
+      pub: options.pub || false,
+      async: options.async || false,
+      unsafe: options.unsafe || false,
+      const: options.const || false,
+      napi: options.napi || false,
+      napiJsName: options.napiJsName || null,
+      napiConstructor: options.napiConstructor || false,
+      napiGetter: options.napiGetter || null,
+      napiSetter: options.napiSetter || null,
+      params: options.params || [],
+      returnType: options.returnType || null,
+      unsafeBlocks: options.unsafeBlocks || 0,
+    };
+  }
+
+  static validate(node: BaseNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+
+    const nodeRecord = node as unknown as Record<string, unknown>;
+    for (const field of this.REQUIRED) {
+      if (nodeRecord[field] === undefined || nodeRecord[field] === null) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+
+    return errors;
+  }
+}
+
+export type { RustFunctionNodeRecord };

package/src/core/nodes/RustImplNode.ts

@@ -0,0 +1,78 @@
+/**
+ * RustImplNode - contract for RUST_IMPL node
+ *
+ * Represents a Rust impl block extracted by RustAnalyzer.
+ * Handles both inherent impls and trait impls.
+ *
+ * ID format: RUST_IMPL#<targetType>[:<traitName>]#<file>#<line>
+ * Example: RUST_IMPL#GraphEngine#src/engine.rs#42
+ * Example: RUST_IMPL#GraphEngine:Display#src/engine.rs#100
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface RustImplNodeRecord extends BaseNodeRecord {
+  type: 'RUST_IMPL';
+  traitName: string | null;
+}
+
+interface RustImplNodeOptions {
+  traitName?: string | null;
+}
+
+export class RustImplNode {
+  static readonly TYPE = 'RUST_IMPL' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['traitName'] as const;
+
+  /**
+   * Create RUST_IMPL node
+   *
+   * @param targetType - The type being implemented (used as node name)
+   * @param file - File path
+   * @param line - Line number
+   * @param options - Optional traitName for trait implementations
+   */
+  static create(
+    targetType: string,
+    file: string,
+    line: number,
+    options: RustImplNodeOptions = {}
+  ): RustImplNodeRecord {
+    if (!targetType) throw new Error('RustImplNode.create: targetType is required');
+    if (!file) throw new Error('RustImplNode.create: file is required');
+    if (line === undefined) throw new Error('RustImplNode.create: line is required');
+
+    const traitName = options.traitName || null;
+    const traitSuffix = traitName ? ':' + traitName : '';
+
+    return {
+      id: `RUST_IMPL#${targetType}${traitSuffix}#${file}#${line}`,
+      type: this.TYPE,
+      name: targetType,
+      file,
+      line,
+      traitName,
+    };
+  }
+
+  static validate(node: BaseNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+
+    const nodeRecord = node as unknown as Record<string, unknown>;
+    for (const field of this.REQUIRED) {
+      if (!nodeRecord[field]) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+
+    return errors;
+  }
+}
+
+export type { RustImplNodeRecord };