@grafema/core 0.2.4-beta → 0.2.6-beta

package/src/core/nodes/RustFunctionNode.ts

@@ -0,0 +1,112 @@
+/**
+ * RustFunctionNode - contract for RUST_FUNCTION node
+ *
+ * Represents a top-level Rust function extracted by RustAnalyzer.
+ * Includes #[napi] attribute detection for FFI linking.
+ *
+ * ID format: RUST_FUNCTION#<name>#<file>#<line>
+ * Example: RUST_FUNCTION#parse_file#src/parser.rs#42
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface RustFunctionNodeRecord extends BaseNodeRecord {
+  type: 'RUST_FUNCTION';
+  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;
+  unsafeBlocks: number;
+}
+
+interface RustFunctionNodeOptions {
+  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;
+}
+
+export class RustFunctionNode {
+  static readonly TYPE = 'RUST_FUNCTION' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['pub', 'async', 'unsafe', 'const', 'napi', 'napiJsName', 'napiConstructor', 'napiGetter', 'napiSetter', 'params', 'returnType', 'unsafeBlocks'] as const;
+
+  /**
+   * Create RUST_FUNCTION node
+   *
+   * @param name - Function name
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Optional function attributes
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: RustFunctionNodeOptions = {}
+  ): RustFunctionNodeRecord {
+    if (!name) throw new Error('RustFunctionNode.create: name is required');
+    if (!file) throw new Error('RustFunctionNode.create: file is required');
+    if (line === undefined) throw new Error('RustFunctionNode.create: line is required');
+    if (column === undefined) throw new Error('RustFunctionNode.create: column is required');
+
+    return {
+      id: `RUST_FUNCTION#${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,
+      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 { RustFunctionNodeRecord };

package/src/core/nodes/RustImplNode.ts

@@ -0,0 +1,78 @@
+/**
+ * RustImplNode - contract for RUST_IMPL node
+ *
+ * Represents a Rust impl block extracted by RustAnalyzer.
+ * Handles both inherent impls and trait impls.
+ *
+ * ID format: RUST_IMPL#<targetType>[:<traitName>]#<file>#<line>
+ * Example: RUST_IMPL#GraphEngine#src/engine.rs#42
+ * Example: RUST_IMPL#GraphEngine:Display#src/engine.rs#100
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface RustImplNodeRecord extends BaseNodeRecord {
+  type: 'RUST_IMPL';
+  traitName: string | null;
+}
+
+interface RustImplNodeOptions {
+  traitName?: string | null;
+}
+
+export class RustImplNode {
+  static readonly TYPE = 'RUST_IMPL' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['traitName'] as const;
+
+  /**
+   * Create RUST_IMPL node
+   *
+   * @param targetType - The type being implemented (used as node name)
+   * @param file - File path
+   * @param line - Line number
+   * @param options - Optional traitName for trait implementations
+   */
+  static create(
+    targetType: string,
+    file: string,
+    line: number,
+    options: RustImplNodeOptions = {}
+  ): RustImplNodeRecord {
+    if (!targetType) throw new Error('RustImplNode.create: targetType is required');
+    if (!file) throw new Error('RustImplNode.create: file is required');
+    if (line === undefined) throw new Error('RustImplNode.create: line is required');
+
+    const traitName = options.traitName || null;
+    const traitSuffix = traitName ? ':' + traitName : '';
+
+    return {
+      id: `RUST_IMPL#${targetType}${traitSuffix}#${file}#${line}`,
+      type: this.TYPE,
+      name: targetType,
+      file,
+      line,
+      traitName,
+    };
+  }
+
+  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 { RustImplNodeRecord };

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