@grafema/core 0.2.5-beta → 0.2.7

package/src/core/nodes/RustMethodNode.ts

@@ -0,0 +1,125 @@
+/**
+ * RustMethodNode - contract for RUST_METHOD node
+ *
+ * Represents a method inside a Rust impl block, extracted by RustAnalyzer.
+ * Includes #[napi] attribute detection for FFI linking.
+ *
+ * ID format: RUST_METHOD#<name>#<file>#<line>
+ * Example: RUST_METHOD#add_node#src/engine.rs#55
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface RustMethodNodeRecord extends BaseNodeRecord {
+  type: 'RUST_METHOD';
+  column: number;
+  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;
+  implId: string;
+  implType: string;
+  unsafeBlocks: number;
+}
+
+interface RustMethodNodeOptions {
+  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;
+}
+
+export class RustMethodNode {
+  static readonly TYPE = 'RUST_METHOD' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'column', 'implId', 'implType'] as const;
+  static readonly OPTIONAL = ['pub', 'async', 'unsafe', 'const', 'napi', 'napiJsName', 'napiConstructor', 'napiGetter', 'napiSetter', 'params', 'returnType', 'selfType', 'unsafeBlocks'] as const;
+
+  /**
+   * Create RUST_METHOD node
+   *
+   * @param name - Method name
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param implId - ID of the parent RUST_IMPL node
+   * @param implType - Target type of the parent impl block
+   * @param options - Optional method attributes
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    implId: string,
+    implType: string,
+    options: RustMethodNodeOptions = {}
+  ): RustMethodNodeRecord {
+    if (!name) throw new Error('RustMethodNode.create: name is required');
+    if (!file) throw new Error('RustMethodNode.create: file is required');
+    if (line === undefined) throw new Error('RustMethodNode.create: line is required');
+    if (column === undefined) throw new Error('RustMethodNode.create: column is required');
+    if (!implId) throw new Error('RustMethodNode.create: implId is required');
+    if (!implType) throw new Error('RustMethodNode.create: implType is required');
+
+    return {
+      id: `RUST_METHOD#${name}#${file}#${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column,
+      pub: options.pub || false,
+      async: options.async || false,
+      unsafe: options.unsafe || false,
+      const: options.const || false,
+      napi: options.napi || false,
+      napiJsName: options.napiJsName || null,
+      napiConstructor: options.napiConstructor || false,
+      napiGetter: options.napiGetter || null,
+      napiSetter: options.napiSetter || null,
+      params: options.params || [],
+      returnType: options.returnType || null,
+      selfType: options.selfType || null,
+      implId,
+      implType,
+      unsafeBlocks: options.unsafeBlocks || 0,
+    };
+  }
+
+  static validate(node: BaseNodeRecord): 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 { RustMethodNodeRecord };

package/src/core/nodes/RustModuleNode.ts

@@ -0,0 +1,84 @@
+/**
+ * RustModuleNode - contract for RUST_MODULE node
+ *
+ * Represents a Rust source file (.rs) indexed from packages/rfdb-server/src/.
+ * Created by RustModuleIndexer during the INDEXING phase.
+ *
+ * ID format: RUST_MODULE#<moduleName>#<relativePath>
+ * Example: RUST_MODULE#ffi::napi_bindings#ffi/napi_bindings.rs
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface RustModuleNodeRecord extends BaseNodeRecord {
+  type: 'RUST_MODULE';
+  contentHash: string;
+  isLib: boolean;
+  isMod: boolean;
+  isTest: boolean;
+}
+
+interface RustModuleNodeOptions {
+  isLib?: boolean;
+  isMod?: boolean;
+  isTest?: boolean;
+}
+
+export class RustModuleNode {
+  static readonly TYPE = 'RUST_MODULE' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'contentHash'] as const;
+  static readonly OPTIONAL = ['isLib', 'isMod', 'isTest'] as const;
+
+  /**
+   * Create RUST_MODULE node
+   *
+   * @param moduleName - Rust module name (e.g., "crate", "ffi::napi_bindings")
+   * @param file - Absolute file path
+   * @param contentHash - SHA-256 hash of file content
+   * @param prefixedPath - Relative path, possibly prefixed for multi-root workspaces
+   * @param options - Optional flags (isLib, isMod, isTest)
+   */
+  static create(
+    moduleName: string,
+    file: string,
+    contentHash: string,
+    prefixedPath: string,
+    options: RustModuleNodeOptions = {}
+  ): RustModuleNodeRecord {
+    if (!moduleName) throw new Error('RustModuleNode.create: moduleName is required');
+    if (!file) throw new Error('RustModuleNode.create: file is required');
+    if (!contentHash) throw new Error('RustModuleNode.create: contentHash is required');
+    if (!prefixedPath) throw new Error('RustModuleNode.create: prefixedPath is required');
+
+    return {
+      id: `RUST_MODULE#${moduleName}#${prefixedPath}`,
+      type: this.TYPE,
+      name: moduleName,
+      file,
+      contentHash,
+      isLib: options.isLib || false,
+      isMod: options.isMod || false,
+      isTest: options.isTest || false,
+    };
+  }
+
+  static validate(node: BaseNodeRecord): 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 { RustModuleNodeRecord };

package/src/core/nodes/RustStructNode.ts

@@ -0,0 +1,80 @@
+/**
+ * RustStructNode - contract for RUST_STRUCT node
+ *
+ * Represents a Rust struct extracted by RustAnalyzer.
+ * Includes #[napi] attribute detection for FFI linking.
+ *
+ * ID format: RUST_STRUCT#<name>#<file>#<line>
+ * Example: RUST_STRUCT#GraphEngine#src/engine.rs#15
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface RustStructNodeRecord extends BaseNodeRecord {
+  type: 'RUST_STRUCT';
+  pub: boolean;
+  napi: boolean;
+  fields: unknown[];
+}
+
+interface RustStructNodeOptions {
+  pub?: boolean;
+  napi?: boolean;
+  fields?: unknown[];
+}
+
+export class RustStructNode {
+  static readonly TYPE = 'RUST_STRUCT' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['pub', 'napi', 'fields'] as const;
+
+  /**
+   * Create RUST_STRUCT node
+   *
+   * @param name - Struct name
+   * @param file - File path
+   * @param line - Line number
+   * @param options - Optional struct attributes
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    options: RustStructNodeOptions = {}
+  ): RustStructNodeRecord {
+    if (!name) throw new Error('RustStructNode.create: name is required');
+    if (!file) throw new Error('RustStructNode.create: file is required');
+    if (line === undefined) throw new Error('RustStructNode.create: line is required');
+
+    return {
+      id: `RUST_STRUCT#${name}#${file}#${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      pub: options.pub || false,
+      napi: options.napi || false,
+      fields: options.fields || [],
+    };
+  }
+
+  static validate(node: BaseNodeRecord): 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 { RustStructNodeRecord };

package/src/core/nodes/RustTraitNode.ts

@@ -0,0 +1,82 @@
+/**
+ * RustTraitNode - contract for RUST_TRAIT node
+ *
+ * Represents a Rust trait extracted by RustAnalyzer.
+ *
+ * ID format: RUST_TRAIT#<name>#<file>#<line>
+ * Example: RUST_TRAIT#QueryEngine#src/traits.rs#10
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface RustTraitMethodRecord {
+  name: string;
+  params: string[];
+  returnType: string;
+}
+
+interface RustTraitNodeRecord extends BaseNodeRecord {
+  type: 'RUST_TRAIT';
+  pub: boolean;
+  methods: RustTraitMethodRecord[];
+}
+
+interface RustTraitNodeOptions {
+  pub?: boolean;
+  methods?: RustTraitMethodRecord[];
+}
+
+export class RustTraitNode {
+  static readonly TYPE = 'RUST_TRAIT' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['pub', 'methods'] as const;
+
+  /**
+   * Create RUST_TRAIT node
+   *
+   * @param name - Trait name
+   * @param file - File path
+   * @param line - Line number
+   * @param options - Optional trait attributes
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    options: RustTraitNodeOptions = {}
+  ): RustTraitNodeRecord {
+    if (!name) throw new Error('RustTraitNode.create: name is required');
+    if (!file) throw new Error('RustTraitNode.create: file is required');
+    if (line === undefined) throw new Error('RustTraitNode.create: line is required');
+
+    return {
+      id: `RUST_TRAIT#${name}#${file}#${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      pub: options.pub || false,
+      methods: options.methods || [],
+    };
+  }
+
+  static validate(node: BaseNodeRecord): 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 { RustTraitNodeRecord, RustTraitMethodRecord };

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;
+  }
+}