@grafema/core 0.2.4-beta → 0.2.6-beta

package/src/core/nodes/ServiceLayerNode.ts

@@ -0,0 +1,183 @@
+/**
+ * ServiceLayerNode - contracts for service layer domain-specific nodes
+ *
+ * Types: SERVICE_CLASS, SERVICE_INSTANCE, SERVICE_REGISTRATION, SERVICE_USAGE
+ *
+ * Used by ServiceLayerAnalyzer for detecting Service Layer Pattern.
+ *
+ * ID formats:
+ * - SERVICE_CLASS: <file>:SERVICE_CLASS:<className>:<line>
+ * - SERVICE_INSTANCE: <file>:SERVICE_INSTANCE:<className>:<line>
+ * - SERVICE_REGISTRATION: <file>:SERVICE_REGISTRATION:<serviceName>:<line>
+ * - SERVICE_USAGE: <file>:SERVICE_USAGE:<serviceName>:<line>
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+// --- SERVICE_CLASS ---
+
+export interface ServiceClassNodeRecord extends BaseNodeRecord {
+  type: 'SERVICE_CLASS';
+  name: string;
+  methods: string[];
+  file: string;
+  line: number;
+}
+
+// --- SERVICE_INSTANCE ---
+
+export interface ServiceInstanceNodeRecord extends BaseNodeRecord {
+  type: 'SERVICE_INSTANCE';
+  serviceClass: string;
+  file: string;
+  line: number;
+}
+
+// --- SERVICE_REGISTRATION ---
+
+export interface ServiceRegistrationNodeRecord extends BaseNodeRecord {
+  type: 'SERVICE_REGISTRATION';
+  serviceName: string;
+  objectName: string;
+  file: string;
+  line: number;
+}
+
+// --- SERVICE_USAGE ---
+
+export interface ServiceUsageNodeRecord extends BaseNodeRecord {
+  type: 'SERVICE_USAGE';
+  serviceName: string;
+  file: string;
+  line: number;
+}
+
+export class ServiceLayerNode {
+  /**
+   * Create a SERVICE_CLASS node.
+   *
+   * @param className - Service class name (e.g., 'UserService')
+   * @param file - File path
+   * @param line - Line number
+   * @param methods - List of method names in the service class
+   */
+  static createClass(
+    className: string,
+    file: string,
+    line: number,
+    methods: string[]
+  ): ServiceClassNodeRecord {
+    if (!className) throw new Error('ServiceLayerNode.createClass: className is required');
+    if (!file) throw new Error('ServiceLayerNode.createClass: file is required');
+
+    return {
+      id: `${file}:SERVICE_CLASS:${className}:${line}`,
+      type: 'SERVICE_CLASS',
+      name: className,
+      methods,
+      file,
+      line,
+    };
+  }
+
+  /**
+   * Create a SERVICE_INSTANCE node.
+   *
+   * @param serviceClass - Name of the service class being instantiated
+   * @param file - File path
+   * @param line - Line number
+   */
+  static createInstance(
+    serviceClass: string,
+    file: string,
+    line: number
+  ): ServiceInstanceNodeRecord {
+    if (!serviceClass) throw new Error('ServiceLayerNode.createInstance: serviceClass is required');
+    if (!file) throw new Error('ServiceLayerNode.createInstance: file is required');
+
+    return {
+      id: `${file}:SERVICE_INSTANCE:${serviceClass}:${line}`,
+      type: 'SERVICE_INSTANCE',
+      name: serviceClass,
+      serviceClass,
+      file,
+      line,
+    };
+  }
+
+  /**
+   * Create a SERVICE_REGISTRATION node.
+   *
+   * @param serviceName - Registered service name
+   * @param objectName - Object used for registration (e.g., 'app')
+   * @param file - File path
+   * @param line - Line number
+   */
+  static createRegistration(
+    serviceName: string,
+    objectName: string,
+    file: string,
+    line: number
+  ): ServiceRegistrationNodeRecord {
+    if (!serviceName) throw new Error('ServiceLayerNode.createRegistration: serviceName is required');
+    if (!file) throw new Error('ServiceLayerNode.createRegistration: file is required');
+
+    return {
+      id: `${file}:SERVICE_REGISTRATION:${serviceName}:${line}`,
+      type: 'SERVICE_REGISTRATION',
+      name: serviceName,
+      serviceName,
+      objectName,
+      file,
+      line,
+    };
+  }
+
+  /**
+   * Create a SERVICE_USAGE node.
+   *
+   * @param serviceName - Name of the service being used
+   * @param file - File path
+   * @param line - Line number
+   */
+  static createUsage(
+    serviceName: string,
+    file: string,
+    line: number
+  ): ServiceUsageNodeRecord {
+    if (!serviceName) throw new Error('ServiceLayerNode.createUsage: serviceName is required');
+    if (!file) throw new Error('ServiceLayerNode.createUsage: file is required');
+
+    return {
+      id: `${file}:SERVICE_USAGE:${serviceName}:${line}`,
+      type: 'SERVICE_USAGE',
+      name: serviceName,
+      serviceName,
+      file,
+      line,
+    };
+  }
+
+  /**
+   * Check if a type belongs to the service layer domain.
+   */
+  static isServiceLayerType(type: string): boolean {
+    return type === 'SERVICE_CLASS' || type === 'SERVICE_INSTANCE' ||
+           type === 'SERVICE_REGISTRATION' || type === 'SERVICE_USAGE';
+  }
+
+  /**
+   * Validate a service layer domain node.
+   */
+  static validate(node: BaseNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (!ServiceLayerNode.isServiceLayerType(node.type)) {
+      errors.push(`Expected SERVICE_* type, got ${node.type}`);
+    }
+
+    if (!node.id) errors.push('Missing required field: id');
+
+    return errors;
+  }
+}

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[] {
@@ -67,7 +110,7 @@ export class TypeNode {
 
     const nodeRecord = node as unknown as Record<string, unknown>;
     for (const field of this.REQUIRED) {
-      if (!nodeRecord[field]) {
+      if (nodeRecord[field] === undefined || nodeRecord[field] === null) {
         errors.push(`Missing required field: ${field}`);
       }
     }