@grafema/core 0.2.5-beta → 0.2.7

package/src/core/nodes/SocketIONode.ts

@@ -0,0 +1,177 @@
+/**
+ * SocketIONode - contract for Socket.IO domain-specific nodes
+ *
+ * Types: socketio:emit, socketio:on, socketio:room, socketio:event
+ *
+ * ID formats:
+ * - socketio:emit#<event>#<file>#<line>
+ * - socketio:on#<event>#<file>#<line>
+ * - socketio:room#<roomName>#<file>#<line>
+ * - socketio:event#<eventName> (singleton per event name)
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+import { getNamespace } from './NodeKind.js';
+
+// --- Emit ---
+
+export interface SocketIOEmitNodeRecord extends BaseNodeRecord {
+  type: 'socketio:emit';
+  event: string;
+  room: string | null;
+  namespace: string | null;
+  broadcast: boolean;
+  objectName: string;
+  column: number;
+}
+
+// --- Listener ---
+
+export interface SocketIOListenerNodeRecord extends BaseNodeRecord {
+  type: 'socketio:on';
+  event: string;
+  objectName: string;
+  handlerName: string;
+  handlerLine: number;
+  column: number;
+}
+
+// --- Room ---
+
+export interface SocketIORoomNodeRecord extends BaseNodeRecord {
+  type: 'socketio:room';
+  room: string;
+  objectName: string;
+  column: number;
+}
+
+// --- Event Channel ---
+
+export interface SocketIOEventNodeRecord extends BaseNodeRecord {
+  type: 'socketio:event';
+  event: string;
+}
+
+export class SocketIONode {
+  static readonly REQUIRED = ['id', 'type'] as const;
+
+  /**
+   * Create a socketio:emit node.
+   */
+  static createEmit(
+    event: string,
+    objectName: string,
+    file: string,
+    line: number,
+    column: number,
+    options: { room?: string | null; namespace?: string | null; broadcast?: boolean } = {}
+  ): SocketIOEmitNodeRecord {
+    if (!event) throw new Error('SocketIONode.createEmit: event is required');
+    if (!file) throw new Error('SocketIONode.createEmit: file is required');
+
+    return {
+      id: `socketio:emit#${event}#${file}#${line}`,
+      type: 'socketio:emit',
+      name: event,
+      event,
+      room: options.room ?? null,
+      namespace: options.namespace ?? null,
+      broadcast: options.broadcast ?? false,
+      objectName,
+      file,
+      line,
+      column
+    };
+  }
+
+  /**
+   * Create a socketio:on listener node.
+   */
+  static createListener(
+    event: string,
+    objectName: string,
+    handlerName: string,
+    handlerLine: number,
+    file: string,
+    line: number,
+    column: number
+  ): SocketIOListenerNodeRecord {
+    if (!event) throw new Error('SocketIONode.createListener: event is required');
+    if (!file) throw new Error('SocketIONode.createListener: file is required');
+
+    return {
+      id: `socketio:on#${event}#${file}#${line}`,
+      type: 'socketio:on',
+      name: event,
+      event,
+      objectName,
+      handlerName,
+      handlerLine,
+      file,
+      line,
+      column
+    };
+  }
+
+  /**
+   * Create a socketio:room node.
+   */
+  static createRoom(
+    roomName: string,
+    objectName: string,
+    file: string,
+    line: number,
+    column: number
+  ): SocketIORoomNodeRecord {
+    if (!roomName) throw new Error('SocketIONode.createRoom: roomName is required');
+    if (!file) throw new Error('SocketIONode.createRoom: file is required');
+
+    return {
+      id: `socketio:room#${roomName}#${file}#${line}`,
+      type: 'socketio:room',
+      name: roomName,
+      room: roomName,
+      objectName,
+      file,
+      line,
+      column
+    };
+  }
+
+  /**
+   * Create a socketio:event channel node (singleton per event name).
+   */
+  static createEvent(eventName: string): SocketIOEventNodeRecord {
+    if (!eventName) throw new Error('SocketIONode.createEvent: eventName is required');
+
+    return {
+      id: `socketio:event#${eventName}`,
+      type: 'socketio:event',
+      name: eventName,
+      event: eventName
+    };
+  }
+
+  /**
+   * Validate a Socket.IO domain node.
+   */
+  static validate(node: BaseNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (!SocketIONode.isSocketIOType(node.type)) {
+      errors.push(`Expected socketio:* type, got ${node.type}`);
+    }
+
+    if (!node.id) errors.push('Missing required field: id');
+
+    return errors;
+  }
+
+  /**
+   * Check if a type belongs to the Socket.IO domain.
+   */
+  static isSocketIOType(type: string): boolean {
+    if (!type) return false;
+    return getNamespace(type) === 'socketio';
+  }
+}

package/src/core/nodes/SocketNode.ts

@@ -0,0 +1,206 @@
+/**
+ * SocketNode - contract for low-level socket nodes (net module)
+ *
+ * Types:
+ * - os:unix-socket  — Unix domain socket client connection
+ * - os:unix-server  — Unix domain socket server
+ * - net:tcp-connection — TCP client connection
+ * - net:tcp-server    — TCP server
+ *
+ * ID formats:
+ * - os:unix-socket#<path>#<file>#<line>
+ * - os:unix-server#<path>#<file>#<line>
+ * - net:tcp-connection#<host>:<port>#<file>#<line>
+ * - net:tcp-server#<host>:<port>#<file>#<line>
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+// --- Unix Socket ---
+
+export interface UnixSocketNodeRecord extends BaseNodeRecord {
+  type: 'os:unix-socket';
+  protocol: 'unix';
+  path: string;
+  library: string;
+  column: number;
+}
+
+// --- TCP Connection ---
+
+export interface TcpConnectionNodeRecord extends BaseNodeRecord {
+  type: 'net:tcp-connection';
+  protocol: 'tcp';
+  host: string;
+  port: number;
+  library: string;
+  column: number;
+}
+
+// --- Unix Server ---
+
+export interface UnixServerNodeRecord extends BaseNodeRecord {
+  type: 'os:unix-server';
+  protocol: 'unix';
+  path: string;
+  library: string;
+  backlog?: number;
+  column: number;
+}
+
+// --- TCP Server ---
+
+export interface TcpServerNodeRecord extends BaseNodeRecord {
+  type: 'net:tcp-server';
+  protocol: 'tcp';
+  host: string;
+  port: number;
+  library: string;
+  backlog?: number;
+  column: number;
+}
+
+export type AnySocketNodeRecord =
+  | UnixSocketNodeRecord
+  | TcpConnectionNodeRecord
+  | UnixServerNodeRecord
+  | TcpServerNodeRecord;
+
+export class SocketNode {
+  static readonly REQUIRED = ['id', 'type', 'name', 'protocol', 'library', 'file', 'line', 'column'] as const;
+
+  /**
+   * Create an os:unix-socket node.
+   */
+  static createUnixSocket(
+    path: string,
+    file: string,
+    line: number,
+    column: number,
+    options: { library?: string } = {}
+  ): UnixSocketNodeRecord {
+    if (!path) throw new Error('SocketNode.createUnixSocket: path is required');
+    if (!file) throw new Error('SocketNode.createUnixSocket: file is required');
+
+    return {
+      id: `os:unix-socket#${path}#${file}#${line}`,
+      type: 'os:unix-socket',
+      name: `unix:${path}`,
+      protocol: 'unix',
+      path,
+      library: options.library ?? 'net',
+      file,
+      line,
+      column
+    };
+  }
+
+  /**
+   * Create a net:tcp-connection node.
+   */
+  static createTcpConnection(
+    host: string,
+    port: number,
+    file: string,
+    line: number,
+    column: number,
+    options: { library?: string } = {}
+  ): TcpConnectionNodeRecord {
+    if (!file) throw new Error('SocketNode.createTcpConnection: file is required');
+
+    return {
+      id: `net:tcp-connection#${host}:${port}#${file}#${line}`,
+      type: 'net:tcp-connection',
+      name: `tcp:${host}:${port}`,
+      protocol: 'tcp',
+      host,
+      port,
+      library: options.library ?? 'net',
+      file,
+      line,
+      column
+    };
+  }
+
+  /**
+   * Create an os:unix-server node.
+   */
+  static createUnixServer(
+    path: string,
+    file: string,
+    line: number,
+    column: number,
+    options: { library?: string; backlog?: number } = {}
+  ): UnixServerNodeRecord {
+    if (!path) throw new Error('SocketNode.createUnixServer: path is required');
+    if (!file) throw new Error('SocketNode.createUnixServer: file is required');
+
+    return {
+      id: `os:unix-server#${path}#${file}#${line}`,
+      type: 'os:unix-server',
+      name: `unix-server:${path}`,
+      protocol: 'unix',
+      path,
+      library: options.library ?? 'net',
+      backlog: options.backlog,
+      file,
+      line,
+      column
+    };
+  }
+
+  /**
+   * Create a net:tcp-server node.
+   */
+  static createTcpServer(
+    host: string,
+    port: number,
+    file: string,
+    line: number,
+    column: number,
+    options: { library?: string; backlog?: number } = {}
+  ): TcpServerNodeRecord {
+    if (!file) throw new Error('SocketNode.createTcpServer: file is required');
+
+    return {
+      id: `net:tcp-server#${host}:${port}#${file}#${line}`,
+      type: 'net:tcp-server',
+      name: `tcp-server:${host}:${port}`,
+      protocol: 'tcp',
+      host,
+      port,
+      library: options.library ?? 'net',
+      backlog: options.backlog,
+      file,
+      line,
+      column
+    };
+  }
+
+  /**
+   * Validate a socket domain node.
+   */
+  static validate(node: BaseNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (!SocketNode.isSocketType(node.type)) {
+      errors.push(`Expected socket type (os:unix-*, net:tcp-*), got ${node.type}`);
+    }
+
+    if (!node.id) errors.push('Missing required field: id');
+    if (!node.name) errors.push('Missing required field: name');
+    if (!node.file) errors.push('Missing required field: file');
+
+    return errors;
+  }
+
+  /**
+   * Check if a type is a low-level socket type.
+   */
+  static isSocketType(type: string): boolean {
+    return type === 'os:unix-socket' ||
+           type === 'os:unix-server' ||
+           type === 'net:tcp-connection' ||
+           type === 'net:tcp-server';
+  }
+}

package/src/core/nodes/TypeNode.ts

@@ -9,21 +9,47 @@
 
 import type { BaseNodeRecord } from '@grafema/types';
 
+type MappedModifier = boolean | '+' | '-';
+
 interface TypeNodeRecord extends BaseNodeRecord {
   type: 'TYPE';
   column: number;
   aliasOf?: string;
+  mappedType?: boolean;
+  keyName?: string;
+  keyConstraint?: string;
+  valueType?: string;
+  mappedReadonly?: MappedModifier;
+  mappedOptional?: MappedModifier;
+  nameType?: string;
+  conditionalType?: boolean;
+  checkType?: string;
+  extendsType?: string;
+  trueType?: string;
+  falseType?: string;
 }
 
 interface TypeNodeOptions {
   aliasOf?: string;
+  mappedType?: boolean;
+  keyName?: string;
+  keyConstraint?: string;
+  valueType?: string;
+  mappedReadonly?: MappedModifier;
+  mappedOptional?: MappedModifier;
+  nameType?: string;
+  conditionalType?: boolean;
+  checkType?: string;
+  extendsType?: string;
+  trueType?: string;
+  falseType?: string;
 }
 
 export class TypeNode {
   static readonly TYPE = 'TYPE' as const;
 
   static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
-  static readonly OPTIONAL = ['aliasOf'] as const;
+  static readonly OPTIONAL = ['aliasOf', 'mappedType', 'keyName', 'keyConstraint', 'valueType', 'mappedReadonly', 'mappedOptional', 'nameType', 'conditionalType', 'checkType', 'extendsType', 'trueType', 'falseType'] as const;
 
   /**
    * Create TYPE node
@@ -47,15 +73,32 @@ export class TypeNode {
     if (!line) throw new Error('TypeNode.create: line is required');
     if (column === undefined) throw new Error('TypeNode.create: column is required');
 
-    return {
+    const record: TypeNodeRecord = {
       id: `${file}:TYPE:${name}:${line}`,
       type: this.TYPE,
       name,
       file,
       line,
       column,
-      aliasOf: options.aliasOf
+      aliasOf: options.aliasOf,
+      conditionalType: options.conditionalType,
+      checkType: options.checkType,
+      extendsType: options.extendsType,
+      trueType: options.trueType,
+      falseType: options.falseType
     };
+
+    if (options.mappedType) {
+      record.mappedType = true;
+      record.keyName = options.keyName;
+      record.keyConstraint = options.keyConstraint;
+      record.valueType = options.valueType;
+      if (options.mappedReadonly !== undefined) record.mappedReadonly = options.mappedReadonly;
+      if (options.mappedOptional !== undefined) record.mappedOptional = options.mappedOptional;
+      if (options.nameType !== undefined) record.nameType = options.nameType;
+    }
+
+    return record;
   }
 
   static validate(node: TypeNodeRecord): string[] {

package/src/core/nodes/TypeParameterNode.ts

@@ -0,0 +1,91 @@
+/**
+ * TypeParameterNode - contract for TYPE_PARAMETER node
+ *
+ * Represents a generic type parameter on a function, class, interface, or type alias.
+ *
+ * ID format: {parentId}:TYPE_PARAMETER:{name}
+ * Example: /src/types.ts:INTERFACE:Container:5:TYPE_PARAMETER:T
+ *
+ * Type parameter names are unique within their declaration scope
+ * (TypeScript does not allow `<T, T>`), so {parentId}:{name} is sufficient.
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface TypeParameterNodeRecord extends BaseNodeRecord {
+  type: 'TYPE_PARAMETER';
+  column: number;
+  constraint?: string;
+  defaultType?: string;
+  variance?: 'in' | 'out' | 'in out';
+}
+
+interface TypeParameterNodeOptions {
+  constraint?: string;
+  defaultType?: string;
+  variance?: 'in' | 'out' | 'in out';
+}
+
+export class TypeParameterNode {
+  static readonly TYPE = 'TYPE_PARAMETER' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['constraint', 'defaultType', 'variance'] as const;
+
+  /**
+   * Create TYPE_PARAMETER node
+   *
+   * @param name - Type parameter name (e.g., "T", "K")
+   * @param parentId - ID of the owning declaration (function, class, interface, type)
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Optional constraint, defaultType, variance
+   * @returns TypeParameterNodeRecord
+   */
+  static create(
+    name: string,
+    parentId: string,
+    file: string,
+    line: number,
+    column: number,
+    options: TypeParameterNodeOptions = {}
+  ): TypeParameterNodeRecord {
+    if (!name) throw new Error('TypeParameterNode.create: name is required');
+    if (!parentId) throw new Error('TypeParameterNode.create: parentId is required');
+    if (!file) throw new Error('TypeParameterNode.create: file is required');
+    if (!line) throw new Error('TypeParameterNode.create: line is required');
+    if (column === undefined) throw new Error('TypeParameterNode.create: column is required');
+
+    return {
+      id: `${parentId}:TYPE_PARAMETER:${name}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column,
+      ...(options.constraint !== undefined && { constraint: options.constraint }),
+      ...(options.defaultType !== undefined && { defaultType: options.defaultType }),
+      ...(options.variance !== undefined && { variance: options.variance }),
+    };
+  }
+
+  static validate(node: TypeParameterNodeRecord): 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 { TypeParameterNodeRecord, TypeParameterNodeOptions };

package/src/core/nodes/index.ts

@@ -28,10 +28,12 @@ export { ArrayLiteralNode, type ArrayLiteralNodeRecord, type ArrayLiteralNodeOpt
 export { ImportNode, type ImportNodeRecord, type ImportBinding, type ImportType } from './ImportNode.js';
 export { ExportNode, type ExportNodeRecord, type ExportKind } from './ExportNode.js';
 export { ExternalModuleNode, type ExternalModuleNodeRecord } from './ExternalModuleNode.js';
+export { ExternalFunctionNode, type ExternalFunctionNodeRecord, type ExternalFunctionOptions } from './ExternalFunctionNode.js';
 
 // TypeScript declaration nodes
 export { InterfaceNode, type InterfaceNodeRecord, type InterfacePropertyRecord } from './InterfaceNode.js';
 export { TypeNode, type TypeNodeRecord } from './TypeNode.js';
+export { TypeParameterNode, type TypeParameterNodeRecord, type TypeParameterNodeOptions } from './TypeParameterNode.js';
 export { EnumNode, type EnumNodeRecord, type EnumMemberRecord } from './EnumNode.js';
 export { DecoratorNode, type DecoratorNodeRecord, type DecoratorTargetType } from './DecoratorNode.js';
 
@@ -46,6 +48,61 @@ export { EventListenerNode, type EventListenerNodeRecord } from './EventListener
 export { HttpRequestNode, type HttpRequestNodeRecord } from './HttpRequestNode.js';
 export { DatabaseQueryNode, type DatabaseQueryNodeRecord } from './DatabaseQueryNode.js';
 
+// HTTP/Express namespaced nodes
+export { HttpRouteNode, type HttpRouteNodeRecord, type HttpRouteNodeOptions } from './HttpRouteNode.js';
+export { FetchRequestNode, type FetchRequestNodeRecord, type FetchRequestNodeOptions } from './FetchRequestNode.js';
+export { ExpressMountNode, type ExpressMountNodeRecord, type ExpressMountNodeOptions } from './ExpressMountNode.js';
+export { ExpressMiddlewareNode, type ExpressMiddlewareNodeRecord, type ExpressMiddlewareNodeOptions } from './ExpressMiddlewareNode.js';
+export { ExternalApiNode, type ExternalApiNodeRecord } from './ExternalApiNode.js';
+
+// Rust nodes
+export { RustModuleNode, type RustModuleNodeRecord } from './RustModuleNode.js';
+export { RustFunctionNode, type RustFunctionNodeRecord } from './RustFunctionNode.js';
+export { RustStructNode, type RustStructNodeRecord } from './RustStructNode.js';
+export { RustImplNode, type RustImplNodeRecord } from './RustImplNode.js';
+export { RustMethodNode, type RustMethodNodeRecord } from './RustMethodNode.js';
+export { RustTraitNode, type RustTraitNodeRecord, type RustTraitMethodRecord } from './RustTraitNode.js';
+export { RustCallNode, type RustCallNodeRecord, type RustCallType } from './RustCallNode.js';
+
+// React domain nodes (react:*, dom:*, browser:*, canvas:*)
+export { ReactNode, type ReactNodeRecord } from './ReactNode.js';
+
+// Socket.IO domain nodes (socketio:*)
+export {
+  SocketIONode,
+  type SocketIOEmitNodeRecord,
+  type SocketIOListenerNodeRecord,
+  type SocketIORoomNodeRecord,
+  type SocketIOEventNodeRecord,
+} from './SocketIONode.js';
+
+// Socket domain nodes (os:unix-*, net:tcp-*)
+export {
+  SocketNode as SocketConnectionNode,
+  type UnixSocketNodeRecord,
+  type TcpConnectionNodeRecord,
+  type UnixServerNodeRecord,
+  type TcpServerNodeRecord,
+  type AnySocketNodeRecord,
+} from './SocketNode.js';
+
+// Database domain nodes (db:*)
+export {
+  DatabaseNode,
+  type DbConnectionNodeRecord,
+  type DbQueryNodeRecord,
+  type DbTableNodeRecord,
+} from './DatabaseNode.js';
+
+// Service Layer domain nodes (SERVICE_*)
+export {
+  ServiceLayerNode,
+  type ServiceClassNodeRecord,
+  type ServiceInstanceNodeRecord,
+  type ServiceRegistrationNodeRecord,
+  type ServiceUsageNodeRecord,
+} from './ServiceLayerNode.js';
+
 // Guarantee nodes (contract-based)
 export { GuaranteeNode, type GuaranteeNodeRecord, type GuaranteePriority, type GuaranteeStatus, type GuaranteeType } from './GuaranteeNode.js';