@grafema/core 0.2.5-beta → 0.2.7

package/src/core/factories/RustFactory.ts

@@ -0,0 +1,128 @@
+/**
+ * RustFactory - factory methods for Rust-specific graph nodes
+ *
+ * Handles: RUST_MODULE, RUST_FUNCTION, RUST_STRUCT, RUST_IMPL,
+ * RUST_METHOD, RUST_TRAIT, RUST_CALL
+ */
+
+import {
+  RustModuleNode,
+  RustFunctionNode,
+  RustStructNode,
+  RustImplNode,
+  RustMethodNode,
+  RustTraitNode,
+  RustCallNode,
+  type RustCallType,
+  type RustTraitMethodRecord,
+} from '../nodes/index.js';
+
+import { brandNodeInternal } from '../brandNodeInternal.js';
+
+export class RustFactory {
+  static createRustModule(
+    moduleName: string,
+    file: string,
+    contentHash: string,
+    prefixedPath: string,
+    options: { isLib?: boolean; isMod?: boolean; isTest?: boolean } = {}
+  ) {
+    return brandNodeInternal(RustModuleNode.create(moduleName, file, contentHash, prefixedPath, options));
+  }
+
+  static createRustFunction(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: {
+      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;
+    } = {}
+  ) {
+    return brandNodeInternal(RustFunctionNode.create(name, file, line, column, options));
+  }
+
+  static createRustStruct(
+    name: string,
+    file: string,
+    line: number,
+    options: { pub?: boolean; napi?: boolean; fields?: unknown[] } = {}
+  ) {
+    return brandNodeInternal(RustStructNode.create(name, file, line, options));
+  }
+
+  static createRustImpl(
+    targetType: string,
+    file: string,
+    line: number,
+    options: { traitName?: string | null } = {}
+  ) {
+    return brandNodeInternal(RustImplNode.create(targetType, file, line, options));
+  }
+
+  static createRustMethod(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    implId: string,
+    implType: string,
+    options: {
+      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;
+      selfType?: string | null;
+      unsafeBlocks?: number;
+    } = {}
+  ) {
+    return brandNodeInternal(RustMethodNode.create(name, file, line, column, implId, implType, options));
+  }
+
+  static createRustTrait(
+    name: string,
+    file: string,
+    line: number,
+    options: {
+      pub?: boolean;
+      methods?: RustTraitMethodRecord[];
+    } = {}
+  ) {
+    return brandNodeInternal(RustTraitNode.create(name, file, line, options));
+  }
+
+  static createRustCall(
+    parentName: string,
+    file: string,
+    line: number,
+    column: number,
+    callType: RustCallType,
+    argsCount: number,
+    options: {
+      name?: string | null;
+      receiver?: string | null;
+      method?: string | null;
+      sideEffect?: string | null;
+    } = {}
+  ) {
+    return brandNodeInternal(RustCallNode.create(parentName, file, line, column, callType, argsCount, options));
+  }
+}

package/src/core/factories/ServiceFactory.ts

@@ -0,0 +1,27 @@
+/**
+ * ServiceFactory - factory methods for service layer graph nodes
+ *
+ * Handles: SERVICE_CLASS, SERVICE_INSTANCE, SERVICE_REGISTRATION, SERVICE_USAGE
+ */
+
+import { ServiceLayerNode } from '../nodes/index.js';
+
+import { brandNodeInternal } from '../brandNodeInternal.js';
+
+export class ServiceFactory {
+  static createServiceClass(className: string, file: string, line: number, methods: string[]) {
+    return brandNodeInternal(ServiceLayerNode.createClass(className, file, line, methods));
+  }
+
+  static createServiceInstance(serviceClass: string, file: string, line: number) {
+    return brandNodeInternal(ServiceLayerNode.createInstance(serviceClass, file, line));
+  }
+
+  static createServiceRegistration(serviceName: string, objectName: string, file: string, line: number) {
+    return brandNodeInternal(ServiceLayerNode.createRegistration(serviceName, objectName, file, line));
+  }
+
+  static createServiceUsage(serviceName: string, file: string, line: number) {
+    return brandNodeInternal(ServiceLayerNode.createUsage(serviceName, file, line));
+  }
+}

package/src/core/factories/SocketFactory.ts

@@ -0,0 +1,94 @@
+/**
+ * SocketFactory - factory methods for Socket.IO and net socket graph nodes
+ *
+ * Handles: socketio:emit, socketio:on, socketio:room, socketio:event,
+ * os:unix-socket, net:tcp-connection, os:unix-server, net:tcp-server
+ */
+
+import {
+  SocketIONode,
+  SocketConnectionNode,
+} from '../nodes/index.js';
+
+import { brandNodeInternal } from '../brandNodeInternal.js';
+
+export class SocketFactory {
+  static createSocketIOEmit(
+    event: string,
+    objectName: string,
+    file: string,
+    line: number,
+    column: number,
+    options: { room?: string | null; namespace?: string | null; broadcast?: boolean } = {}
+  ) {
+    return brandNodeInternal(SocketIONode.createEmit(event, objectName, file, line, column, options));
+  }
+
+  static createSocketIOListener(
+    event: string,
+    objectName: string,
+    handlerName: string,
+    handlerLine: number,
+    file: string,
+    line: number,
+    column: number
+  ) {
+    return brandNodeInternal(SocketIONode.createListener(event, objectName, handlerName, handlerLine, file, line, column));
+  }
+
+  static createSocketIORoom(
+    roomName: string,
+    objectName: string,
+    file: string,
+    line: number,
+    column: number
+  ) {
+    return brandNodeInternal(SocketIONode.createRoom(roomName, objectName, file, line, column));
+  }
+
+  static createSocketIOEvent(eventName: string) {
+    return brandNodeInternal(SocketIONode.createEvent(eventName));
+  }
+
+  static createUnixSocket(
+    path: string,
+    file: string,
+    line: number,
+    column: number,
+    options: { library?: string } = {}
+  ) {
+    return brandNodeInternal(SocketConnectionNode.createUnixSocket(path, file, line, column, options));
+  }
+
+  static createTcpConnection(
+    host: string,
+    port: number,
+    file: string,
+    line: number,
+    column: number,
+    options: { library?: string } = {}
+  ) {
+    return brandNodeInternal(SocketConnectionNode.createTcpConnection(host, port, file, line, column, options));
+  }
+
+  static createUnixServer(
+    path: string,
+    file: string,
+    line: number,
+    column: number,
+    options: { library?: string; backlog?: number } = {}
+  ) {
+    return brandNodeInternal(SocketConnectionNode.createUnixServer(path, file, line, column, options));
+  }
+
+  static createTcpServer(
+    host: string,
+    port: number,
+    file: string,
+    line: number,
+    column: number,
+    options: { library?: string; backlog?: number } = {}
+  ) {
+    return brandNodeInternal(SocketConnectionNode.createTcpServer(host, port, file, line, column, options));
+  }
+}

package/src/core/nodes/DatabaseNode.ts

@@ -0,0 +1,175 @@
+/**
+ * DatabaseNode - contracts for database domain-specific nodes
+ *
+ * Types: db:connection, db:query, db:table
+ *
+ * Used by DatabaseAnalyzer and SQLiteAnalyzer for database access patterns.
+ * NOT the same as DatabaseQueryNode which handles legacy DATABASE_QUERY type.
+ *
+ * ID formats:
+ * - db:connection: EXTERNAL_DATABASE:<name>
+ * - db:query (DatabaseAnalyzer): <file>:DATABASE_QUERY:<counter>
+ * - db:query (SQLiteAnalyzer): <file>:DATABASE_QUERY:<method>:<line>
+ * - db:table: TABLE:<tableName>
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+// --- db:connection ---
+
+export interface DbConnectionNodeRecord extends BaseNodeRecord {
+  type: 'db:connection';
+  name: string;
+}
+
+// --- db:query (DatabaseAnalyzer variant) ---
+
+export interface DbQueryNodeRecord extends BaseNodeRecord {
+  type: 'db:query';
+  file: string;
+  line: number;
+  column: number;
+}
+
+// --- db:table ---
+
+export interface DbTableNodeRecord extends BaseNodeRecord {
+  type: 'db:table';
+  name: string;
+}
+
+export class DatabaseNode {
+  /**
+   * Create a db:connection node (singleton per database name).
+   *
+   * @param name - Database name (e.g., '__database__')
+   */
+  static createConnection(name: string): DbConnectionNodeRecord {
+    if (!name) throw new Error('DatabaseNode.createConnection: name is required');
+
+    return {
+      id: `EXTERNAL_DATABASE:${name}`,
+      type: 'db:connection',
+      name,
+    };
+  }
+
+  /**
+   * Create a db:query node for DatabaseAnalyzer.
+   *
+   * @param file - File path
+   * @param queryCounter - Sequential query counter within the file
+   * @param sql - Raw SQL string
+   * @param operation - SQL operation type (SELECT, INSERT, UPDATE, DELETE, etc.)
+   * @param options - Additional query metadata
+   */
+  static createQuery(
+    file: string,
+    queryCounter: number,
+    sql: string,
+    operation: string,
+    options: {
+      sqlSnippet?: string;
+      tableName?: string | null;
+      object?: string;
+      method?: string;
+      line?: number;
+      column?: number;
+    } = {}
+  ): DbQueryNodeRecord {
+    if (!file) throw new Error('DatabaseNode.createQuery: file is required');
+
+    return {
+      id: `${file}:DATABASE_QUERY:${queryCounter}`,
+      type: 'db:query',
+      name: sql,
+      sql,
+      sqlSnippet: options.sqlSnippet ?? (sql.length > 50 ? sql.substring(0, 50) + '...' : sql),
+      operation,
+      tableName: options.tableName ?? null,
+      object: options.object,
+      method: options.method,
+      file,
+      line: options.line ?? 0,
+      column: options.column ?? 0,
+    };
+  }
+
+  /**
+   * Create a db:query node for SQLiteAnalyzer.
+   *
+   * @param file - File path
+   * @param method - SQLite method name (e.g., 'all', 'get', 'run')
+   * @param line - Line number
+   * @param query - Raw SQL string
+   * @param operationType - SQL operation type
+   * @param options - Additional query metadata
+   */
+  static createSQLiteQuery(
+    file: string,
+    method: string,
+    line: number,
+    query: string,
+    operationType: string,
+    options: {
+      params?: string | null;
+      tableName?: string | null;
+      column?: number;
+      promiseWrapped?: boolean;
+    } = {}
+  ): DbQueryNodeRecord {
+    if (!file) throw new Error('DatabaseNode.createSQLiteQuery: file is required');
+
+    return {
+      id: `${file}:DATABASE_QUERY:${method}:${line}`,
+      type: 'db:query',
+      name: query,
+      method: method.toUpperCase(),
+      query,
+      params: options.params ?? null,
+      operationType,
+      tableName: options.tableName ?? null,
+      file,
+      line,
+      column: options.column ?? 0,
+      promiseWrapped: options.promiseWrapped,
+    };
+  }
+
+  /**
+   * Create a db:table node (singleton per table name).
+   *
+   * @param tableName - Table name
+   */
+  static createTable(tableName: string): DbTableNodeRecord {
+    if (!tableName) throw new Error('DatabaseNode.createTable: tableName is required');
+
+    return {
+      id: `TABLE:${tableName}`,
+      type: 'db:table',
+      name: tableName,
+    };
+  }
+
+  /**
+   * Check if a type belongs to the database domain.
+   */
+  static isDatabaseType(type: string): boolean {
+    return type === 'db:connection' || type === 'db:query' || type === 'db:table';
+  }
+
+  /**
+   * Validate a database domain node.
+   */
+  static validate(node: BaseNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (!DatabaseNode.isDatabaseType(node.type)) {
+      errors.push(`Expected db:* type, got ${node.type}`);
+    }
+
+    if (!node.id) errors.push('Missing required field: id');
+
+    return errors;
+  }
+}

package/src/core/nodes/ExpressMiddlewareNode.ts

@@ -0,0 +1,98 @@
+/**
+ * ExpressMiddlewareNode - contract for express:middleware nodes
+ *
+ * Represents an Express.js middleware in a route chain or global mount.
+ * Created by ExpressRouteAnalyzer.
+ *
+ * ID format: express:middleware#${name}#${file}#${line}
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ExpressMiddlewareNodeRecord extends BaseNodeRecord {
+  type: 'express:middleware';
+  name: string;
+  file: string;
+  line: number;
+  column: number;
+}
+
+interface ExpressMiddlewareNodeOptions {
+  /** Associated endpoint ID (for route-specific middleware) */
+  endpointId?: string;
+  /** Order in middleware chain */
+  order?: number;
+  /** Mount path (for app.use() middleware) */
+  mountPath?: string;
+  /** Whether this is a global middleware (mounted on '/') */
+  isGlobal?: boolean;
+}
+
+export class ExpressMiddlewareNode {
+  static readonly TYPE = 'express:middleware' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['endpointId', 'order', 'mountPath', 'isGlobal'] as const;
+
+  /**
+   * Create express:middleware node
+   *
+   * @param name - Middleware name (e.g., "cors", "authMiddleware", "inline:42")
+   * @param file - File path where middleware is used
+   * @param line - Line number
+   * @param column - Column number
+   * @param options - Optional fields
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ExpressMiddlewareNodeOptions = {}
+  ): ExpressMiddlewareNodeRecord {
+    const id = `express:middleware#${name}#${file}#${line}`;
+
+    const node: ExpressMiddlewareNodeRecord = {
+      id,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column,
+    };
+
+    if (options.endpointId !== undefined) {
+      (node as Record<string, unknown>).endpointId = options.endpointId;
+    }
+    if (options.order !== undefined) {
+      (node as Record<string, unknown>).order = options.order;
+    }
+    if (options.mountPath !== undefined) {
+      (node as Record<string, unknown>).mountPath = options.mountPath;
+    }
+    if (options.isGlobal !== undefined) {
+      (node as Record<string, unknown>).isGlobal = options.isGlobal;
+    }
+
+    return node;
+  }
+
+  /**
+   * Validate express:middleware node structure
+   */
+  static validate(node: ExpressMiddlewareNodeRecord): 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 { ExpressMiddlewareNodeRecord, ExpressMiddlewareNodeOptions };

package/src/core/nodes/ExpressMountNode.ts

@@ -0,0 +1,94 @@
+/**
+ * ExpressMountNode - contract for express:mount nodes
+ *
+ * Represents an Express.js mount point (app.use('/prefix', router)).
+ * Created by ExpressAnalyzer.
+ *
+ * ID format: express:mount#${prefix}#${file}#${line}
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ExpressMountNodeRecord extends BaseNodeRecord {
+  type: 'express:mount';
+  file: string;
+  line: number;
+  column: number;
+}
+
+interface ExpressMountNodeOptions {
+  /** Target function name (e.g., "createRouter") */
+  targetFunction?: string | null;
+  /** Target variable name (e.g., "router") */
+  targetVariable?: string | null;
+  /** App/router variable name this is mounted on */
+  mountedOn?: string;
+}
+
+export class ExpressMountNode {
+  static readonly TYPE = 'express:mount' as const;
+
+  static readonly REQUIRED = ['prefix', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['targetFunction', 'targetVariable', 'mountedOn'] as const;
+
+  /**
+   * Create express:mount node
+   *
+   * @param prefix - Mount path prefix (e.g., "/api", "/users")
+   * @param file - File path where mount is defined
+   * @param line - Line number
+   * @param column - Column number
+   * @param options - Optional fields
+   */
+  static create(
+    prefix: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ExpressMountNodeOptions = {}
+  ): ExpressMountNodeRecord {
+    const id = `express:mount#${prefix}#${file}#${line}`;
+
+    const node: ExpressMountNodeRecord = {
+      id,
+      type: this.TYPE,
+      name: `mount:${prefix}`,
+      file,
+      line,
+      column,
+    };
+
+    (node as Record<string, unknown>).prefix = prefix;
+
+    if (options.targetFunction !== undefined) {
+      (node as Record<string, unknown>).targetFunction = options.targetFunction;
+    }
+    if (options.targetVariable !== undefined) {
+      (node as Record<string, unknown>).targetVariable = options.targetVariable;
+    }
+    if (options.mountedOn !== undefined) {
+      (node as Record<string, unknown>).mountedOn = options.mountedOn;
+    }
+
+    return node;
+  }
+
+  /**
+   * Validate express:mount node structure
+   */
+  static validate(node: ExpressMountNodeRecord): 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 { ExpressMountNodeRecord, ExpressMountNodeOptions };

package/src/core/nodes/ExternalApiNode.ts

@@ -0,0 +1,53 @@
+/**
+ * ExternalApiNode - contract for EXTERNAL nodes
+ *
+ * Represents an external API domain detected from HTTP requests.
+ * Created by FetchAnalyzer when URLs point to external hosts.
+ *
+ * ID format: EXTERNAL#${domain}
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ExternalApiNodeRecord extends BaseNodeRecord {
+  type: 'EXTERNAL';
+}
+
+export class ExternalApiNode {
+  static readonly TYPE = 'EXTERNAL' as const;
+
+  static readonly REQUIRED = ['name'] as const;
+  static readonly OPTIONAL = ['domain'] as const;
+
+  /**
+   * Create EXTERNAL node for an API domain
+   *
+   * @param domain - External API domain (e.g., "api.github.com")
+   */
+  static create(domain: string): ExternalApiNodeRecord {
+    const id = `EXTERNAL#${domain}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name: domain,
+      domain,
+    } as ExternalApiNodeRecord;
+  }
+
+  /**
+   * Validate EXTERNAL node structure
+   */
+  static validate(node: ExternalApiNodeRecord): 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');
+    }
+    return errors;
+  }
+}
+
+export type { ExternalApiNodeRecord };