@grafema/core 0.1.0-alpha.1

package/src/core/nodes/MethodNode.ts

@@ -0,0 +1,78 @@
+/**
+ * MethodNode - contract for METHOD node (class method)
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+type MethodKind = 'method' | 'get' | 'set' | 'constructor';
+
+interface MethodNodeRecord extends BaseNodeRecord {
+  type: 'METHOD';
+  column: number;
+  className: string;
+  async: boolean;
+  generator: boolean;
+  static: boolean;
+  kind: MethodKind;
+}
+
+interface MethodNodeOptions {
+  async?: boolean;
+  generator?: boolean;
+  static?: boolean;
+  kind?: MethodKind;
+}
+
+export class MethodNode {
+  static readonly TYPE = 'METHOD' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'className'] as const;
+  static readonly OPTIONAL = ['column', 'async', 'generator', 'static', 'kind'] as const;
+
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    className: string,
+    options: MethodNodeOptions = {}
+  ): MethodNodeRecord {
+    if (!name) throw new Error('MethodNode.create: name is required');
+    if (!file) throw new Error('MethodNode.create: file is required');
+    if (!line) throw new Error('MethodNode.create: line is required');
+    if (!className) throw new Error('MethodNode.create: className is required');
+
+    return {
+      id: `${file}:METHOD:${className}.${name}:${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column: column || 0,
+      className,
+      async: options.async || false,
+      generator: options.generator || false,
+      static: options.static || false,
+      kind: options.kind || 'method'
+    };
+  }
+
+  static validate(node: MethodNodeRecord): 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 { MethodNodeRecord, MethodKind };

package/src/core/nodes/ModuleNode.ts

@@ -0,0 +1,74 @@
+/**
+ * ModuleNode - contract for MODULE node
+ */
+
+import { createHash } from 'crypto';
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ModuleNodeRecord extends BaseNodeRecord {
+  type: 'MODULE';
+  contentHash: string;
+  isTest: boolean;
+}
+
+interface ModuleNodeOptions {
+  isTest?: boolean;
+}
+
+export class ModuleNode {
+  static readonly TYPE = 'MODULE' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'contentHash'] as const;
+  static readonly OPTIONAL = ['isTest'] as const;
+
+  /**
+   * Create MODULE node
+   * @param filePath - Full file path
+   * @param relativePath - Relative path (module name)
+   * @param contentHash - Content hash
+   * @param options - Additional options (isTest, etc.)
+   */
+  static create(
+    filePath: string,
+    relativePath: string,
+    contentHash: string,
+    options: ModuleNodeOptions = {}
+  ): ModuleNodeRecord {
+    if (!filePath) throw new Error('ModuleNode.create: filePath is required');
+    if (!relativePath) throw new Error('ModuleNode.create: relativePath is required');
+    if (!contentHash) throw new Error('ModuleNode.create: contentHash is required');
+
+    return {
+      id: `MODULE:${contentHash}`,
+      type: this.TYPE,
+      name: relativePath,
+      file: filePath,
+      line: 0,
+      contentHash,
+      isTest: options.isTest || false
+    };
+  }
+
+  static _hashPath(path: string): string {
+    return createHash('md5').update(path).digest('hex').substring(0, 12);
+  }
+
+  static validate(node: ModuleNodeRecord): 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 { ModuleNodeRecord };

package/src/core/nodes/NodeKind.ts

@@ -0,0 +1,171 @@
+/**
+ * Node Types - string type system for nodes
+ *
+ * Base types: FUNCTION, CLASS, METHOD, etc.
+ * Namespaced types: http:route, socketio:emit, express:router, etc.
+ *
+ * Namespace convention:
+ * - http:* - HTTP endpoints and requests
+ * - express:* - Express.js specifics
+ * - socketio:* - Socket.IO
+ * - db:* - Database queries
+ * - fs:* - Filesystem operations
+ */
+
+// === BASE TYPES ===
+// Abstract types, not tied to language or framework
+
+export const NODE_TYPE = {
+  // Core code entities
+  FUNCTION: 'FUNCTION',
+  CLASS: 'CLASS',
+  METHOD: 'METHOD',
+  VARIABLE: 'VARIABLE',
+  PARAMETER: 'PARAMETER',
+  CONSTANT: 'CONSTANT',
+  LITERAL: 'LITERAL',
+  EXPRESSION: 'EXPRESSION',  // Generic expression node for data flow tracking
+
+  // Module system
+  MODULE: 'MODULE',
+  IMPORT: 'IMPORT',
+  EXPORT: 'EXPORT',
+
+  // Call graph
+  CALL: 'CALL', // unified METHOD_CALL + CALL_SITE
+
+  // Project structure
+  PROJECT: 'PROJECT',
+  SERVICE: 'SERVICE',
+  FILE: 'FILE',
+  SCOPE: 'SCOPE',
+
+  // External dependencies
+  EXTERNAL: 'EXTERNAL',
+  EXTERNAL_MODULE: 'EXTERNAL_MODULE',
+
+  // Generic side effects
+  SIDE_EFFECT: 'SIDE_EFFECT',
+} as const;
+
+export type BaseNodeType = typeof NODE_TYPE[keyof typeof NODE_TYPE];
+
+// === NAMESPACED TYPES ===
+// Types specific to frameworks and libraries
+
+export const NAMESPACED_TYPE = {
+  // HTTP (generic)
+  HTTP_ROUTE: 'http:route',
+  HTTP_REQUEST: 'http:request',
+
+  // Express.js
+  EXPRESS_ROUTER: 'express:router',
+  EXPRESS_MIDDLEWARE: 'express:middleware',
+  EXPRESS_MOUNT: 'express:mount',
+
+  // Socket.IO
+  SOCKETIO_EMIT: 'socketio:emit',
+  SOCKETIO_ON: 'socketio:on',
+  SOCKETIO_NAMESPACE: 'socketio:namespace',
+
+  // Database
+  DB_QUERY: 'db:query',
+  DB_CONNECTION: 'db:connection',
+
+  // Filesystem
+  FS_READ: 'fs:read',
+  FS_WRITE: 'fs:write',
+  FS_OPERATION: 'fs:operation',
+
+  // Network
+  NET_REQUEST: 'net:request',
+  NET_STDIO: 'net:stdio',
+
+  // Events
+  EVENT_LISTENER: 'event:listener',
+  EVENT_EMIT: 'event:emit',
+
+  // Guarantees (contract-based)
+  GUARANTEE_QUEUE: 'guarantee:queue',
+  GUARANTEE_API: 'guarantee:api',
+  GUARANTEE_PERMISSION: 'guarantee:permission',
+} as const;
+
+export type NamespacedNodeType = typeof NAMESPACED_TYPE[keyof typeof NAMESPACED_TYPE];
+
+// Combined node type
+export type NodeType = BaseNodeType | NamespacedNodeType | string;
+
+// === HELPERS ===
+
+/**
+ * Check if type is namespaced (contains :)
+ */
+export function isNamespacedType(nodeType: string): boolean {
+  return nodeType !== undefined && nodeType !== null && nodeType.includes(':');
+}
+
+/**
+ * Get namespace from type
+ * @returns namespace or null for base types
+ */
+export function getNamespace(nodeType: string): string | null {
+  if (!nodeType || !nodeType.includes(':')) return null;
+  return nodeType.split(':')[0];
+}
+
+/**
+ * Get base name from namespaced type
+ */
+export function getBaseName(nodeType: string): string {
+  if (!nodeType) return '';
+  if (!nodeType.includes(':')) return nodeType;
+  return nodeType.split(':').slice(1).join(':');
+}
+
+/**
+ * Check if type is an endpoint (HTTP route, WebSocket handler, etc.)
+ */
+export function isEndpointType(nodeType: string): boolean {
+  if (!nodeType) return false;
+  const ns = getNamespace(nodeType);
+  return ns === 'http' || ns === 'express' || ns === 'socketio';
+}
+
+/**
+ * Check if type is a side effect (DB, FS, Network)
+ */
+export function isSideEffectType(nodeType: string): boolean {
+  if (!nodeType) return false;
+  if (nodeType === NODE_TYPE.SIDE_EFFECT) return true;
+  const ns = getNamespace(nodeType);
+  return ns === 'db' || ns === 'fs' || ns === 'net';
+}
+
+/**
+ * Check if type matches a pattern with wildcard
+ * @param nodeType - node type
+ * @param pattern - pattern (e.g., "http:*", "FUNCTION")
+ */
+export function matchesTypePattern(nodeType: string, pattern: string): boolean {
+  if (!nodeType || !pattern) return false;
+
+  // Exact match
+  if (nodeType === pattern) return true;
+
+  // Wildcard match (e.g., "http:*" matches "http:route")
+  if (pattern.endsWith(':*')) {
+    const patternNs = pattern.slice(0, -2);
+    return getNamespace(nodeType) === patternNs;
+  }
+
+  return false;
+}
+
+/**
+ * Check if type is a guarantee type (guarantee:queue, guarantee:api, etc.)
+ */
+export function isGuaranteeType(nodeType: string): boolean {
+  if (!nodeType) return false;
+  return getNamespace(nodeType) === 'guarantee';
+}

package/src/core/nodes/ParameterNode.ts

@@ -0,0 +1,73 @@
+/**
+ * ParameterNode - contract for PARAMETER node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ParameterNodeRecord extends BaseNodeRecord {
+  type: 'PARAMETER';
+  column: number;
+  functionId: string;
+  index: number;
+  defaultValue?: unknown;
+  rest: boolean;
+}
+
+interface ParameterNodeOptions {
+  index?: number;
+  defaultValue?: unknown;
+  rest?: boolean;
+}
+
+export class ParameterNode {
+  static readonly TYPE = 'PARAMETER' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'functionId'] as const;
+  static readonly OPTIONAL = ['column', 'index', 'defaultValue', 'rest'] as const;
+
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    functionId: string,
+    options: ParameterNodeOptions = {}
+  ): ParameterNodeRecord {
+    if (!name) throw new Error('ParameterNode.create: name is required');
+    if (!file) throw new Error('ParameterNode.create: file is required');
+    if (!line) throw new Error('ParameterNode.create: line is required');
+    if (!functionId) throw new Error('ParameterNode.create: functionId is required');
+
+    return {
+      id: `${file}:PARAMETER:${name}:${line}:${options.index || 0}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column: column || 0,
+      functionId,
+      index: options.index || 0,
+      defaultValue: options.defaultValue,
+      rest: options.rest || false
+    };
+  }
+
+  static validate(node: ParameterNodeRecord): 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 { ParameterNodeRecord };

package/src/core/nodes/ScopeNode.ts

@@ -0,0 +1,80 @@
+/**
+ * ScopeNode - contract for SCOPE node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ScopeNodeRecord extends BaseNodeRecord {
+  type: 'SCOPE';
+  scopeType: string;
+  conditional: boolean;
+  parentScopeId?: string;
+  parentFunctionId?: string;
+  capturesFrom?: string[];
+}
+
+interface ScopeNodeOptions {
+  name?: string;
+  conditional?: boolean;
+  parentScopeId?: string;
+  parentFunctionId?: string;
+  capturesFrom?: string[];
+  counter?: number;
+}
+
+export class ScopeNode {
+  static readonly TYPE = 'SCOPE' as const;
+
+  static readonly REQUIRED = ['scopeType', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['name', 'conditional', 'parentScopeId', 'parentFunctionId', 'capturesFrom'] as const;
+
+  /**
+   * Create SCOPE node
+   */
+  static create(
+    scopeType: string,
+    file: string,
+    line: number,
+    options: ScopeNodeOptions = {}
+  ): ScopeNodeRecord {
+    if (!scopeType) throw new Error('ScopeNode.create: scopeType is required');
+    if (!file) throw new Error('ScopeNode.create: file is required');
+    if (line === undefined) throw new Error('ScopeNode.create: line is required');
+
+    const name = options.name || scopeType;
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const id = `${file}:SCOPE:${name}:${line}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      scopeType,
+      name,
+      file,
+      line,
+      conditional: options.conditional || false,
+      parentScopeId: options.parentScopeId,
+      parentFunctionId: options.parentFunctionId,
+      capturesFrom: options.capturesFrom
+    };
+  }
+
+  static validate(node: ScopeNodeRecord): 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 { ScopeNodeRecord };

package/src/core/nodes/ServiceNode.ts

@@ -0,0 +1,86 @@
+/**
+ * ServiceNode - contract for SERVICE node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ServiceNodeRecord extends BaseNodeRecord {
+  type: 'SERVICE';
+  kind: 'SERVICE';
+  filePath: string;
+  version: string;
+  entrypoint: string;
+  discoveryMethod: string;
+  description?: string;
+  dependencies: string[];
+  serviceType?: string;
+  testFiles?: string[];
+}
+
+interface ServiceNodeOptions {
+  version?: string;
+  entrypoint?: string;
+  discoveryMethod?: string;
+  description?: string;
+  dependencies?: string[];
+  serviceType?: string;
+  testFiles?: string[];
+  metadata?: {
+    type?: string;
+    testFiles?: string[];
+  };
+}
+
+export class ServiceNode {
+  static readonly TYPE = 'SERVICE' as const;
+
+  static readonly REQUIRED = ['name', 'file'] as const;
+  static readonly OPTIONAL = ['version', 'entrypoint', 'discoveryMethod', 'description', 'dependencies', 'metadata', 'testFiles', 'serviceType'] as const;
+
+  /**
+   * Create SERVICE node
+   */
+  static create(name: string, projectPath: string, options: ServiceNodeOptions = {}): ServiceNodeRecord {
+    if (!name) throw new Error('ServiceNode.create: name is required');
+    if (!projectPath) throw new Error('ServiceNode.create: projectPath is required');
+
+    return {
+      id: `SERVICE:${name}`,
+      type: this.TYPE,
+      kind: this.TYPE,
+      name,
+      file: projectPath,
+      line: 0,
+      filePath: projectPath,
+      version: options.version || '0.0.0',
+      entrypoint: options.entrypoint || 'index.js',
+      discoveryMethod: options.discoveryMethod || 'unknown',
+      description: options.description,
+      dependencies: options.dependencies || [],
+      serviceType: options.metadata?.type || options.serviceType,
+      testFiles: options.metadata?.testFiles || options.testFiles
+    };
+  }
+
+  /**
+   * Validate SERVICE node
+   */
+  static validate(node: ServiceNodeRecord): 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 { ServiceNodeRecord };

package/src/core/nodes/VariableDeclarationNode.ts

@@ -0,0 +1,60 @@
+/**
+ * VariableDeclarationNode - contract for VARIABLE_DECLARATION node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface VariableDeclarationNodeRecord extends BaseNodeRecord {
+  type: 'VARIABLE_DECLARATION';
+  column: number;
+  parentScopeId?: string;
+}
+
+interface VariableDeclarationNodeOptions {
+  parentScopeId?: string;
+  counter?: number;
+}
+
+export class VariableDeclarationNode {
+  static readonly TYPE = 'VARIABLE_DECLARATION' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['column', 'parentScopeId'] as const;
+
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: VariableDeclarationNodeOptions = {}
+  ): VariableDeclarationNodeRecord {
+    if (!name) throw new Error('VariableDeclarationNode.create: name is required');
+    if (!file) throw new Error('VariableDeclarationNode.create: file is required');
+    if (line === undefined) throw new Error('VariableDeclarationNode.create: line is required');
+
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const id = `${file}:VARIABLE_DECLARATION:${name}:${line}:${column || 0}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column: column || 0,
+      parentScopeId: options.parentScopeId
+    };
+  }
+
+  static validate(node: VariableDeclarationNodeRecord): string[] {
+    const errors: string[] = [];
+    if (node.type !== this.TYPE) errors.push(`Expected type ${this.TYPE}`);
+    const nodeRecord = node as unknown as Record<string, unknown>;
+    for (const field of this.REQUIRED) {
+      if (nodeRecord[field] === undefined) errors.push(`Missing: ${field}`);
+    }
+    return errors;
+  }
+}
+
+export type { VariableDeclarationNodeRecord };

package/src/core/nodes/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Node Types - export all node types and their contracts
+ */
+
+// Core nodes
+export { ServiceNode, type ServiceNodeRecord } from './ServiceNode.js';
+export { EntrypointNode, type EntrypointNodeRecord, type EntrypointType, type EntrypointTrigger, type EntrypointSource, ENTRYPOINT_TYPES, ENTRYPOINT_TRIGGERS, ENTRYPOINT_SOURCES } from './EntrypointNode.js';
+export { ModuleNode, type ModuleNodeRecord } from './ModuleNode.js';
+export { FunctionNode } from './FunctionNode.js';
+export { ClassNode, type ClassNodeRecord } from './ClassNode.js';
+export { MethodNode, type MethodNodeRecord, type MethodKind } from './MethodNode.js';
+export { ParameterNode, type ParameterNodeRecord } from './ParameterNode.js';
+export { ScopeNode, type ScopeNodeRecord } from './ScopeNode.js';
+
+// Call/reference nodes
+export { CallSiteNode, type CallSiteNodeRecord } from './CallSiteNode.js';
+export { MethodCallNode, type MethodCallNodeRecord } from './MethodCallNode.js';
+export { VariableDeclarationNode, type VariableDeclarationNodeRecord } from './VariableDeclarationNode.js';
+export { ConstantNode, type ConstantNodeRecord } from './ConstantNode.js';
+export { LiteralNode, type LiteralNodeRecord } from './LiteralNode.js';
+
+// Import/Export nodes
+export { ImportNode, type ImportNodeRecord, type ImportKind } from './ImportNode.js';
+export { ExportNode, type ExportNodeRecord, type ExportKind } from './ExportNode.js';
+
+// External/IO nodes
+export { ExternalStdioNode, type ExternalStdioNodeRecord } from './ExternalStdioNode.js';
+export { EventListenerNode, type EventListenerNodeRecord } from './EventListenerNode.js';
+export { HttpRequestNode, type HttpRequestNodeRecord } from './HttpRequestNode.js';
+export { DatabaseQueryNode, type DatabaseQueryNodeRecord } from './DatabaseQueryNode.js';
+
+// Guarantee nodes (contract-based)
+export { GuaranteeNode, type GuaranteeNodeRecord, type GuaranteePriority, type GuaranteeStatus, type GuaranteeType } from './GuaranteeNode.js';
+
+// Node type constants and helpers
+export {
+  NODE_TYPE,
+  NAMESPACED_TYPE,
+  isNamespacedType,
+  getNamespace,
+  getBaseName,
+  isEndpointType,
+  isSideEffectType,
+  matchesTypePattern,
+  isGuaranteeType,
+  type BaseNodeType,
+  type NamespacedNodeType,
+  type NodeType,
+} from './NodeKind.js';