@grafema/core 0.1.0-alpha.1

package/src/core/nodes/ExportNode.ts

@@ -0,0 +1,71 @@
+/**
+ * ExportNode - contract for EXPORT node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+type ExportKind = 'value' | 'type';
+
+interface ExportNodeRecord extends BaseNodeRecord {
+  type: 'EXPORT';
+  column: number;
+  exportKind: ExportKind;
+  local: string;
+  default: boolean;
+}
+
+interface ExportNodeOptions {
+  exportKind?: ExportKind;
+  local?: string;
+  default?: boolean;
+}
+
+export class ExportNode {
+  static readonly TYPE = 'EXPORT' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['column', 'exportKind', 'local', 'default'] as const;
+
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ExportNodeOptions = {}
+  ): ExportNodeRecord {
+    if (!name) throw new Error('ExportNode.create: name is required');
+    if (!file) throw new Error('ExportNode.create: file is required');
+    if (!line) throw new Error('ExportNode.create: line is required');
+
+    return {
+      id: `${file}:EXPORT:${name}:${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column: column || 0,
+      exportKind: options.exportKind || 'value',
+      local: options.local || name,
+      default: options.default || false
+    };
+  }
+
+  static validate(node: ExportNodeRecord): 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 { ExportNodeRecord, ExportKind };

package/src/core/nodes/ExternalStdioNode.ts

@@ -0,0 +1,36 @@
+/**
+ * ExternalStdioNode - contract for EXTERNAL_STDIO node (singleton)
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ExternalStdioNodeRecord extends BaseNodeRecord {
+  type: 'EXTERNAL_STDIO';
+}
+
+export class ExternalStdioNode {
+  static readonly TYPE = 'EXTERNAL_STDIO' as const;
+  static readonly SINGLETON_ID = 'EXTERNAL_STDIO:__stdio__';
+
+  static readonly REQUIRED = ['name', 'file'] as const;
+  static readonly OPTIONAL = [] as const;
+
+  static create(): ExternalStdioNodeRecord {
+    return {
+      id: this.SINGLETON_ID,
+      type: this.TYPE,
+      name: '__stdio__',
+      file: '__builtin__',
+      line: 0
+    };
+  }
+
+  static validate(node: ExternalStdioNodeRecord): string[] {
+    const errors: string[] = [];
+    if (node.type !== this.TYPE) errors.push(`Expected type ${this.TYPE}`);
+    if (node.id !== this.SINGLETON_ID) errors.push(`Invalid singleton ID`);
+    return errors;
+  }
+}
+
+export type { ExternalStdioNodeRecord };

package/src/core/nodes/FunctionNode.ts

@@ -0,0 +1,78 @@
+/**
+ * FunctionNode - contract for FUNCTION node
+ */
+
+import type { FunctionNodeRecord } from '@grafema/types';
+
+interface FunctionNodeOptions {
+  async?: boolean;
+  generator?: boolean;
+  exported?: boolean;
+  arrowFunction?: boolean;
+  parentScopeId?: string;
+  isClassMethod?: boolean;
+  className?: string;
+  params?: string[];
+  counter?: number;
+}
+
+export class FunctionNode {
+  static readonly TYPE = 'FUNCTION' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['async', 'generator', 'exported', 'arrowFunction', 'parentScopeId', 'isClassMethod', 'className', 'params'] as const;
+
+  /**
+   * Create FUNCTION node
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: FunctionNodeOptions = {}
+  ): FunctionNodeRecord {
+    if (!name) throw new Error('FunctionNode.create: name is required');
+    if (!file) throw new Error('FunctionNode.create: file is required');
+    if (line === undefined) throw new Error('FunctionNode.create: line is required');
+    if (column === undefined) throw new Error('FunctionNode.create: column is required');
+
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const id = `${file}:FUNCTION:${name}:${line}:${column}${counter}`;
+
+    return {
+      id,
+      stableId: id,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column,
+      async: options.async || false,
+      generator: options.generator || false,
+      exported: options.exported || false,
+      arrowFunction: options.arrowFunction || false,
+      parentScopeId: options.parentScopeId,
+      isClassMethod: options.isClassMethod || false,
+      className: options.className,
+      params: options.params || []
+    };
+  }
+
+  static validate(node: FunctionNodeRecord): 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;
+  }
+}

package/src/core/nodes/GuaranteeNode.ts

@@ -0,0 +1,162 @@
+/**
+ * GuaranteeNode - contract for contract-based guarantee nodes
+ *
+ * Types: guarantee:queue, guarantee:api, guarantee:permission
+ * ID format: guarantee:queue#orders, guarantee:api#rate-limit
+ *
+ * Unlike Datalog-based GUARANTEE nodes (handled by GuaranteeManager),
+ * these nodes use JSON schema validation for contract verification.
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+import { NAMESPACED_TYPE, isGuaranteeType } from './NodeKind.js';
+
+// Re-export types from nodes.ts for convenience
+export type GuaranteePriority = 'critical' | 'important' | 'observed' | 'tracked';
+export type GuaranteeStatus = 'discovered' | 'reviewed' | 'active' | 'changing' | 'deprecated';
+export type GuaranteeType = 'guarantee:queue' | 'guarantee:api' | 'guarantee:permission';
+
+export interface GuaranteeNodeRecord extends BaseNodeRecord {
+  type: GuaranteeType;
+  priority: GuaranteePriority;
+  status: GuaranteeStatus;
+  owner?: string;
+  schema?: Record<string, unknown>;
+  condition?: string;
+  description?: string;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+export interface GuaranteeNodeOptions {
+  priority?: GuaranteePriority;
+  status?: GuaranteeStatus;
+  owner?: string;
+  schema?: Record<string, unknown>;
+  condition?: string;
+  description?: string;
+}
+
+// Valid guarantee namespaces
+const GUARANTEE_NAMESPACES = ['queue', 'api', 'permission'] as const;
+type GuaranteeNamespace = typeof GUARANTEE_NAMESPACES[number];
+
+export class GuaranteeNode {
+  static readonly TYPE_QUEUE = NAMESPACED_TYPE.GUARANTEE_QUEUE;
+  static readonly TYPE_API = NAMESPACED_TYPE.GUARANTEE_API;
+  static readonly TYPE_PERMISSION = NAMESPACED_TYPE.GUARANTEE_PERMISSION;
+
+  static readonly REQUIRED = ['name', 'file', 'priority', 'status'] as const;
+  static readonly OPTIONAL = ['owner', 'schema', 'condition', 'description', 'createdAt', 'updatedAt'] as const;
+
+  /**
+   * Create guarantee node
+   * @param namespace - guarantee namespace (queue, api, permission)
+   * @param name - guarantee name (e.g., 'orders', 'rate-limit')
+   * @param options - optional fields
+   */
+  static create(
+    namespace: GuaranteeNamespace,
+    name: string,
+    options: GuaranteeNodeOptions = {}
+  ): GuaranteeNodeRecord {
+    if (!namespace) throw new Error('GuaranteeNode.create: namespace is required');
+    if (!name) throw new Error('GuaranteeNode.create: name is required');
+    if (!GUARANTEE_NAMESPACES.includes(namespace)) {
+      throw new Error(`GuaranteeNode.create: invalid namespace "${namespace}". Valid: ${GUARANTEE_NAMESPACES.join(', ')}`);
+    }
+
+    const type = `guarantee:${namespace}` as GuaranteeType;
+    const id = `${type}#${name}`;
+    const now = Date.now();
+
+    return {
+      id,
+      type,
+      name,
+      file: '', // Guarantees don't have a source file
+      line: undefined,
+      priority: options.priority || 'observed',
+      status: options.status || 'discovered',
+      owner: options.owner,
+      schema: options.schema,
+      condition: options.condition,
+      description: options.description,
+      createdAt: now,
+      updatedAt: now,
+    };
+  }
+
+  /**
+   * Validate guarantee node
+   * @returns array of error messages, empty if valid
+   */
+  static validate(node: GuaranteeNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (!isGuaranteeType(node.type)) {
+      errors.push(`Expected guarantee:* type, got ${node.type}`);
+    }
+
+    if (!node.name) {
+      errors.push('Missing required field: name');
+    }
+
+    if (!node.priority) {
+      errors.push('Missing required field: priority');
+    } else if (!['critical', 'important', 'observed', 'tracked'].includes(node.priority)) {
+      errors.push(`Invalid priority: ${node.priority}. Valid: critical, important, observed, tracked`);
+    }
+
+    if (!node.status) {
+      errors.push('Missing required field: status');
+    } else if (!['discovered', 'reviewed', 'active', 'changing', 'deprecated'].includes(node.status)) {
+      errors.push(`Invalid status: ${node.status}. Valid: discovered, reviewed, active, changing, deprecated`);
+    }
+
+    return errors;
+  }
+
+  /**
+   * Parse guarantee ID into components
+   * @param id - full ID (e.g., 'guarantee:queue#orders')
+   * @returns { namespace, name } or null if invalid
+   */
+  static parseId(id: string): { namespace: GuaranteeNamespace; name: string } | null {
+    if (!id) return null;
+
+    // Format: guarantee:namespace#name
+    const match = id.match(/^guarantee:(queue|api|permission)#(.+)$/);
+    if (!match) return null;
+
+    return {
+      namespace: match[1] as GuaranteeNamespace,
+      name: match[2],
+    };
+  }
+
+  /**
+   * Build ID from components
+   */
+  static buildId(namespace: GuaranteeNamespace, name: string): string {
+    return `guarantee:${namespace}#${name}`;
+  }
+
+  /**
+   * Check if node type is a guarantee type
+   */
+  static isGuaranteeType(type: string): boolean {
+    return isGuaranteeType(type);
+  }
+
+  /**
+   * Get all valid guarantee types
+   */
+  static getTypes(): GuaranteeType[] {
+    return [
+      NAMESPACED_TYPE.GUARANTEE_QUEUE,
+      NAMESPACED_TYPE.GUARANTEE_API,
+      NAMESPACED_TYPE.GUARANTEE_PERMISSION,
+    ];
+  }
+}

package/src/core/nodes/HttpRequestNode.ts

@@ -0,0 +1,63 @@
+/**
+ * HttpRequestNode - contract for HTTP_REQUEST node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface HttpRequestNodeRecord extends BaseNodeRecord {
+  type: 'HTTP_REQUEST';
+  url?: string;
+  method: string;
+  parentScopeId?: string;
+}
+
+interface HttpRequestNodeOptions {
+  column?: number;
+  parentScopeId?: string;
+  counter?: number;
+}
+
+export class HttpRequestNode {
+  static readonly TYPE = 'HTTP_REQUEST' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['url', 'method', 'column', 'parentScopeId'] as const;
+
+  static create(
+    url: string | undefined,
+    method: string | undefined,
+    file: string,
+    line: number,
+    options: HttpRequestNodeOptions = {}
+  ): HttpRequestNodeRecord {
+    if (!file) throw new Error('HttpRequestNode.create: file is required');
+    if (line === undefined) throw new Error('HttpRequestNode.create: line is required');
+
+    const httpMethod = method || 'GET';
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const id = `${file}:HTTP_REQUEST:${httpMethod}:${line}:${options.column || 0}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name: `${httpMethod} ${url || 'dynamic'}`,
+      url,
+      method: httpMethod,
+      file,
+      line,
+      parentScopeId: options.parentScopeId
+    };
+  }
+
+  static validate(node: HttpRequestNodeRecord): 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 { HttpRequestNodeRecord };

package/src/core/nodes/ImportNode.ts

@@ -0,0 +1,75 @@
+/**
+ * ImportNode - contract for IMPORT node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+type ImportKind = 'value' | 'type' | 'typeof';
+
+interface ImportNodeRecord extends BaseNodeRecord {
+  type: 'IMPORT';
+  column: number;
+  source: string;
+  importKind: ImportKind;
+  imported: string;
+  local: string;
+}
+
+interface ImportNodeOptions {
+  importKind?: ImportKind;
+  imported?: string;
+  local?: string;
+}
+
+export class ImportNode {
+  static readonly TYPE = 'IMPORT' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'source'] as const;
+  static readonly OPTIONAL = ['column', 'importKind', 'imported', 'local'] as const;
+
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    source: string,
+    options: ImportNodeOptions = {}
+  ): ImportNodeRecord {
+    if (!name) throw new Error('ImportNode.create: name is required');
+    if (!file) throw new Error('ImportNode.create: file is required');
+    if (!line) throw new Error('ImportNode.create: line is required');
+    if (!source) throw new Error('ImportNode.create: source is required');
+
+    return {
+      id: `${file}:IMPORT:${name}:${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column: column || 0,
+      source,
+      importKind: options.importKind || 'value',
+      imported: options.imported || name,
+      local: options.local || name
+    };
+  }
+
+  static validate(node: ImportNodeRecord): 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 { ImportNodeRecord, ImportKind };

package/src/core/nodes/LiteralNode.ts

@@ -0,0 +1,67 @@
+/**
+ * LiteralNode - contract for LITERAL node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface LiteralNodeRecord extends BaseNodeRecord {
+  type: 'LITERAL';
+  value: unknown;
+  valueType: string;
+  column: number;
+  parentCallId?: string;
+  argIndex?: number;
+}
+
+interface LiteralNodeOptions {
+  parentCallId?: string;
+  argIndex?: number;
+  counter?: number;
+}
+
+export class LiteralNode {
+  static readonly TYPE = 'LITERAL' as const;
+
+  static readonly REQUIRED = ['file', 'line'] as const;
+  static readonly OPTIONAL = ['value', 'valueType', 'column', 'parentCallId', 'argIndex'] as const;
+
+  static create(
+    value: unknown,
+    file: string,
+    line: number,
+    column: number,
+    options: LiteralNodeOptions = {}
+  ): LiteralNodeRecord {
+    if (!file) throw new Error('LiteralNode.create: file is required');
+    if (line === undefined) throw new Error('LiteralNode.create: line is required');
+
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const argIndex = options.argIndex !== undefined ? `arg${options.argIndex}` : 'value';
+    const id = `${file}:LITERAL:${argIndex}:${line}:${column || 0}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name: file,
+      value,
+      valueType: typeof value,
+      file,
+      line,
+      column: column || 0,
+      parentCallId: options.parentCallId,
+      argIndex: options.argIndex
+    };
+  }
+
+  static validate(node: LiteralNodeRecord): 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 { LiteralNodeRecord };

package/src/core/nodes/MethodCallNode.ts

@@ -0,0 +1,79 @@
+/**
+ * MethodCallNode - contract for METHOD_CALL node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface MethodCallNodeRecord extends BaseNodeRecord {
+  type: 'METHOD_CALL';
+  object?: string;
+  method: string;
+  column: number;
+  parentScopeId?: string;
+  args: unknown[];
+}
+
+interface MethodCallNodeOptions {
+  parentScopeId?: string;
+  args?: unknown[];
+  counter?: number;
+}
+
+export class MethodCallNode {
+  static readonly TYPE = 'METHOD_CALL' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'args'] as const;
+  static readonly OPTIONAL = ['object', 'method', 'column', 'parentScopeId'] as const;
+
+  /**
+   * Create METHOD_CALL node
+   */
+  static create(
+    objectName: string | undefined,
+    methodName: string,
+    file: string,
+    line: number,
+    column: number,
+    options: MethodCallNodeOptions = {}
+  ): MethodCallNodeRecord {
+    if (!methodName) throw new Error('MethodCallNode.create: methodName is required');
+    if (!file) throw new Error('MethodCallNode.create: file is required');
+    if (line === undefined) throw new Error('MethodCallNode.create: line is required');
+
+    const fullName = objectName ? `${objectName}.${methodName}` : methodName;
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const id = `${file}:METHOD_CALL:${fullName}:${line}:${column || 0}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name: fullName,
+      object: objectName,
+      method: methodName,
+      file,
+      line,
+      column: column || 0,
+      parentScopeId: options.parentScopeId,
+      args: options.args || []
+    };
+  }
+
+  static validate(node: MethodCallNodeRecord): 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 { MethodCallNodeRecord };