@grafema/util 0.3.22 → 0.3.23

package/src/queries/getShape.ts

@@ -0,0 +1,241 @@
+/**
+ * Shape Query Engine
+ *
+ * Computes the "shape" of a CLASS, INTERFACE, or typed VARIABLE:
+ * the set of methods and properties it has, including inherited ones.
+ *
+ * Shape = { members: ShapeMember[], extends: string[], implementedBy: string[] }
+ *
+ * For CLASS: own HAS_METHOD + HAS_PROPERTY + walk EXTENDS chain for inherited
+ * For INTERFACE: own HAS_METHOD + HAS_PROPERTY (METHOD_SIGNATURE + PROPERTY_SIGNATURE)
+ * For VARIABLE: follow INSTANCE_OF → CLASS/INTERFACE → shape
+ *
+ * @module queries/getShape
+ */
+
+export interface ShapeMember {
+  name: string;
+  kind: 'method' | 'property' | 'method_signature' | 'property_signature';
+  from: string;       // CLASS/INTERFACE name that defines this member
+  file?: string;
+  line?: number;
+  nodeId: string;
+}
+
+export interface ShapeResult {
+  name: string;
+  nodeId: string;
+  nodeType: string;
+  file?: string;
+  members: ShapeMember[];
+  extends: string[];
+  implements: string[];
+  implementedBy: string[];
+  confidence: 'high' | 'medium' | 'low';
+}
+
+interface GraphBackend {
+  getNode(id: string): Promise<{
+    id: string | number;
+    type?: string;
+    nodeType?: string;
+    name?: string;
+    file?: string;
+    line?: number;
+    metadata?: string | Record<string, unknown>;
+    semanticId?: string;
+  } | null>;
+  getOutgoingEdges(
+    nodeId: string,
+    edgeTypes?: string[] | null
+  ): Promise<Array<{ src: string; dst: string; type: string; metadata?: string }>>;
+  getIncomingEdges(
+    nodeId: string,
+    edgeTypes?: string[] | null
+  ): Promise<Array<{ src: string; dst: string; type: string }>>;
+}
+
+function nodeType(node: { type?: string; nodeType?: string }): string {
+  return node.nodeType ?? node.type ?? 'UNKNOWN';
+}
+
+function parseMeta(node: { metadata?: string | Record<string, unknown> }): Record<string, unknown> {
+  if (!node.metadata) return {};
+  if (typeof node.metadata === 'string') {
+    try { return JSON.parse(node.metadata); } catch { return {}; }
+  }
+  return node.metadata;
+}
+
+/** Index mapping class/interface name → node ID for EXTENDS chain walking */
+export type ClassIndex = Map<string, string>;
+
+/**
+ * Get the shape of a CLASS, INTERFACE, or VARIABLE.
+ * @param classIndex — optional name→ID index for resolving EXTENDS/IMPLEMENTS targets
+ */
+export async function getShape(
+  backend: GraphBackend,
+  targetId: string,
+  classIndex?: ClassIndex,
+): Promise<ShapeResult | null> {
+  const node = await backend.getNode(targetId);
+  if (!node) return null;
+
+  const nType = nodeType(node);
+  const nId = String(node.id);
+
+  if (nType === 'CLASS' || nType === 'INTERFACE') {
+    return getClassShape(backend, nId, node.name ?? '<unknown>', nType, node.file, classIndex);
+  }
+
+  if (nType === 'VARIABLE' || nType === 'CONSTANT' || nType === 'PARAMETER') {
+    // Follow INSTANCE_OF to find the class/interface
+    const edges = await backend.getOutgoingEdges(nId);
+    const instanceOf = edges.find(e => e.type === 'INSTANCE_OF');
+    if (!instanceOf) return null;
+
+    const classNode = await backend.getNode(instanceOf.dst);
+    if (!classNode) return null;
+
+    const shape = await getClassShape(
+      backend,
+      String(classNode.id),
+      classNode.name ?? '<unknown>',
+      nodeType(classNode),
+      classNode.file,
+      classIndex,
+    );
+    if (shape) {
+      shape.confidence = 'medium'; // inferred, not direct
+    }
+    return shape;
+  }
+
+  return null;
+}
+
+/**
+ * Get shape for a CLASS or INTERFACE, including inherited members.
+ */
+async function getClassShape(
+  backend: GraphBackend,
+  classId: string,
+  className: string,
+  classType: string,
+  classFile?: string,
+  classIndex?: ClassIndex,
+): Promise<ShapeResult> {
+  const members: ShapeMember[] = [];
+  const extendsChain: string[] = [];
+  const implementsList: string[] = [];
+  const implementedBy: string[] = [];
+  const visited = new Set<string>();
+
+  // Collect own + inherited members via BFS through EXTENDS
+  const queue: Array<{ id: string; name: string }> = [{ id: classId, name: className }];
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (visited.has(current.id)) continue;
+    visited.add(current.id);
+
+    // Collect HAS_METHOD edges
+    const edges = await backend.getOutgoingEdges(current.id);
+    for (const edge of edges) {
+      if (edge.type === 'HAS_METHOD') {
+        const member = await backend.getNode(edge.dst);
+        if (member) {
+          members.push({
+            name: member.name ?? '<unknown>',
+            kind: nodeType(member) === 'METHOD_SIGNATURE' ? 'method_signature' : 'method',
+            from: current.name,
+            file: member.file,
+            line: member.line,
+            nodeId: String(member.id),
+          });
+        }
+      }
+      if (edge.type === 'HAS_PROPERTY') {
+        const member = await backend.getNode(edge.dst);
+        if (member) {
+          const mType = nodeType(member);
+          // Skip if it's actually a METHOD_SIGNATURE that was incorrectly HAS_PROPERTY
+          // (this handles legacy data before the fix)
+          const kind = mType === 'PROPERTY_SIGNATURE' ? 'property_signature'
+            : mType === 'METHOD_SIGNATURE' ? 'method_signature'
+            : 'property';
+          members.push({
+            name: member.name ?? '<unknown>',
+            kind,
+            from: current.name,
+            file: member.file,
+            line: member.line,
+            nodeId: String(member.id),
+          });
+        }
+      }
+    }
+
+    // Follow EXTENDS chain
+    const meta = await getNodeMeta(backend, current.id);
+    const superClass = meta.superClass as string | undefined;
+    if (superClass && current.id !== classId) {
+      extendsChain.push(superClass);
+    } else if (superClass && current.id === classId) {
+      extendsChain.push(superClass);
+    }
+    if (superClass) {
+      // Find the superclass node
+      const superNode = await findClassByName(backend, superClass, classIndex);
+      if (superNode) {
+        queue.push({ id: String(superNode.id), name: superNode.name ?? superClass });
+      }
+    }
+
+    // Collect implements
+    const implementsStr = meta.implements as string | undefined;
+    if (implementsStr && current.id === classId) {
+      implementsList.push(...implementsStr.split(',').map(s => s.trim()).filter(Boolean));
+      // Also collect members from implemented interfaces
+      for (const ifaceName of implementsList) {
+        const ifaceNode = await findClassByName(backend, ifaceName, classIndex);
+        if (ifaceNode) {
+          queue.push({ id: String(ifaceNode.id), name: ifaceNode.name ?? ifaceName });
+        }
+      }
+    }
+  }
+
+  // Find implementedBy (classes that have INSTANCE_OF → this class, or metadata implements)
+  // Skip for now — expensive reverse lookup
+
+  return {
+    name: className,
+    nodeId: classId,
+    nodeType: classType,
+    file: classFile,
+    members,
+    extends: extendsChain,
+    implements: implementsList,
+    implementedBy,
+    confidence: 'high',
+  };
+}
+
+async function getNodeMeta(backend: GraphBackend, nodeId: string): Promise<Record<string, unknown>> {
+  const node = await backend.getNode(nodeId);
+  if (!node) return {};
+  return parseMeta(node);
+}
+
+async function findClassByName(
+  _backend: GraphBackend,
+  name: string,
+  classIndex?: ClassIndex,
+): Promise<{ id: string; name: string } | null> {
+  if (!classIndex) return null;
+  const id = classIndex.get(name);
+  if (!id) return null;
+  return { id, name };
+}

package/src/queries/index.ts

@@ -11,6 +11,9 @@ export { findCallsInFunction } from './findCallsInFunction.js';
 export { findContainingFunction } from './findContainingFunction.js';
 export { traceValues, aggregateValues, NONDETERMINISTIC_PATTERNS, NONDETERMINISTIC_OBJECTS } from './traceValues.js';
 export { traceDataflow, traceForwardBFS, traceBackwardBFS } from './traceDataflow.js';
+export { traceCallChain } from './traceCallChain.js';
+export { getShape } from './getShape.js';
+export type { ShapeResult, ShapeMember, ClassIndex } from './getShape.js';
 export {
   buildNodeContext,
   getNodeDisplayName,

package/src/queries/traceCallChain.ts

@@ -0,0 +1,341 @@
+/**
+ * Transitive call-chain traversal.
+ *
+ * Forward: from a function, follow CALLS/CALLS_REMOTE edges transitively
+ * to show what the function eventually calls (including cross-language hops).
+ *
+ * Backward: from a function, follow incoming CALLS/CALLS_REMOTE edges
+ * to show who eventually calls this function.
+ *
+ * Uses findCallsInFunction for forward traversal (handles both Layout A
+ * and Layout B edge patterns). Backward traversal uses incoming edge BFS.
+ *
+ * @module queries/traceCallChain
+ */
+
+import { findCallsInFunction } from './findCallsInFunction.js';
+import type { CallInfo } from './types.js';
+
+/**
+ * Graph backend interface.
+ * Accepts nodes with either `type` or `nodeType` field (RFDB uses `nodeType`).
+ */
+interface GraphBackend {
+  getNode(id: string): Promise<{
+    id: string;
+    type?: string;
+    nodeType?: string;
+    name?: string;
+    file?: string;
+    line?: number;
+    endLine?: number;
+  } | null>;
+  getOutgoingEdges(
+    nodeId: string,
+    edgeTypes: string[] | null
+  ): Promise<Array<{ src: string; dst: string; type: string }>>;
+  getIncomingEdges(
+    nodeId: string,
+    edgeTypes: string[] | null
+  ): Promise<Array<{ src: string; dst: string; type: string }>>;
+}
+
+/** Normalize node type field (RFDB uses nodeType, some backends use type) */
+function nodeType(node: { type?: string; nodeType?: string }): string {
+  return node.nodeType ?? node.type ?? 'UNKNOWN';
+}
+
+export interface CallChainHop {
+  /** The function/method being called */
+  name: string;
+  /** Semantic ID */
+  id: string;
+  /** File path */
+  file?: string;
+  /** Line number */
+  line?: number;
+  /** Depth in chain (0 = direct) */
+  depth: number;
+  /** Crosses process/language boundary */
+  remote: boolean;
+  /** Call was resolved to a target */
+  resolved: boolean;
+}
+
+export interface TraceCallChainResult {
+  direction: 'forward' | 'backward';
+  startNode: { id: string; name: string; file?: string; line?: number };
+  chain: CallChainHop[];
+  totalFound: number;
+}
+
+export interface TraceCallChainOptions {
+  direction?: 'forward' | 'backward' | 'both';
+  maxDepth?: number;
+  limit?: number;
+}
+
+const CALL_EDGE_TYPES = ['CALLS', 'CALLS_REMOTE'];
+const FUNCTION_TYPES = new Set(['FUNCTION', 'METHOD', 'CONSTRUCTOR', 'LAMBDA']);
+
+/**
+ * Trace call chain from a function forward or backward.
+ */
+export async function traceCallChain(
+  backend: GraphBackend,
+  startId: string,
+  options: TraceCallChainOptions = {},
+): Promise<TraceCallChainResult[]> {
+  const {
+    direction = 'forward',
+    maxDepth = 10,
+    limit = 100,
+  } = options;
+
+  const startNode = await backend.getNode(startId);
+  if (!startNode) return [];
+
+  const start = {
+    id: startNode.id,
+    name: startNode.name ?? '<unknown>',
+    file: startNode.file,
+    line: startNode.line,
+  };
+
+  const results: TraceCallChainResult[] = [];
+
+  if (direction === 'forward' || direction === 'both') {
+    const chain = await traceForward(backend, startId, maxDepth, limit);
+    results.push({ direction: 'forward', startNode: start, chain, totalFound: chain.length });
+  }
+
+  if (direction === 'backward' || direction === 'both') {
+    const chain = await traceBackward(backend, startId, maxDepth, limit);
+    results.push({ direction: 'backward', startNode: start, chain, totalFound: chain.length });
+  }
+
+  return results;
+}
+
+/**
+ * Forward: what does this function call (transitively)?
+ * Uses findCallsInFunction with transitive mode + follows CALLS_REMOTE.
+ * Falls back to line-range matching when METHOD nodes have no outgoing edges.
+ */
+async function traceForward(
+  backend: GraphBackend,
+  startId: string,
+  maxDepth: number,
+  limit: number,
+): Promise<CallChainHop[]> {
+  let calls = await findCallsInFunction(backend, startId, {
+    transitive: true,
+    transitiveDepth: maxDepth,
+  });
+
+  // Fallback: if no calls found via scope chain, try line-range matching
+  // (METHOD nodes often have no outgoing edges — calls are found by position)
+  if (calls.length === 0) {
+    calls = await findCallsByLineRange(backend, startId, maxDepth);
+  }
+
+  // Also check if any resolved target METHOD/FUNCTION has CALLS_REMOTE outgoing
+  const chain: CallChainHop[] = [];
+  const visited = new Set<string>();
+
+  for (const call of calls) {
+    if (chain.length >= limit) break;
+
+    chain.push({
+      name: call.name,
+      id: call.target?.id ?? call.id,
+      file: call.target?.file ?? call.file,
+      line: call.target?.line ?? call.line,
+      depth: call.depth ?? 0,
+      remote: call.remote ?? false,
+      resolved: call.resolved,
+    });
+
+    // If the target has CALLS_REMOTE outgoing, follow it
+    if (call.target && !visited.has(call.target.id)) {
+      visited.add(call.target.id);
+      const remoteEdges = await backend.getOutgoingEdges(call.target.id, ['CALLS_REMOTE']);
+      for (const re of remoteEdges) {
+        if (chain.length >= limit) break;
+        const remoteTarget = await backend.getNode(re.dst);
+        if (!remoteTarget) continue;
+
+        chain.push({
+          name: remoteTarget.name ?? '<unknown>',
+          id: remoteTarget.id,
+          file: remoteTarget.file,
+          line: remoteTarget.line,
+          depth: (call.depth ?? 0) + 1,
+          remote: true,
+          resolved: true,
+        });
+
+        // Recurse into the remote target's calls
+        if (!visited.has(remoteTarget.id)) {
+          visited.add(remoteTarget.id);
+          const remoteCalls = await findCallsInFunction(backend, remoteTarget.id, {
+            transitive: true,
+            transitiveDepth: Math.max(1, maxDepth - (call.depth ?? 0) - 1),
+          });
+          for (const rc of remoteCalls) {
+            if (chain.length >= limit) break;
+            chain.push({
+              name: rc.name,
+              id: rc.target?.id ?? rc.id,
+              file: rc.target?.file ?? rc.file,
+              line: rc.target?.line ?? rc.line,
+              depth: (call.depth ?? 0) + 2 + (rc.depth ?? 0),
+              remote: rc.remote ?? false,
+              resolved: rc.resolved,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return chain;
+}
+
+/**
+ * Backward: who calls this function (transitively)?
+ * BFS over incoming CALLS/CALLS_REMOTE edges, resolving containing functions.
+ */
+async function traceBackward(
+  backend: GraphBackend,
+  startId: string,
+  maxDepth: number,
+  limit: number,
+): Promise<CallChainHop[]> {
+  const chain: CallChainHop[] = [];
+  const visited = new Set<string>();
+  visited.add(startId);
+
+  interface QueueItem { functionId: string; depth: number; remote: boolean }
+  const queue: QueueItem[] = [{ functionId: startId, depth: 0, remote: false }];
+
+  while (queue.length > 0 && chain.length < limit) {
+    const { functionId, depth } = queue.shift()!;
+    if (depth > maxDepth) continue;
+
+    // Find all CALL/METHOD_CALL nodes that have CALLS/CALLS_REMOTE → this function
+    const incomingCalls = await backend.getIncomingEdges(functionId, CALL_EDGE_TYPES);
+
+    for (const edge of incomingCalls) {
+      if (chain.length >= limit) break;
+
+      const callNode = await backend.getNode(edge.src);
+      if (!callNode) continue;
+
+      const isRemote = edge.type === 'CALLS_REMOTE';
+
+      // Find the containing function of this CALL node
+      const containingFn = await findContainingFunction(backend, callNode.id);
+      if (!containingFn) {
+        // Can't determine caller — add the call node itself
+        chain.push({
+          name: callNode.name ?? '<unknown>',
+          id: callNode.id,
+          file: callNode.file,
+          line: callNode.line,
+          depth,
+          remote: isRemote,
+          resolved: true,
+        });
+        continue;
+      }
+
+      if (visited.has(containingFn.id)) continue;
+      visited.add(containingFn.id);
+
+      chain.push({
+        name: containingFn.name ?? '<unknown>',
+        id: containingFn.id,
+        file: containingFn.file,
+        line: containingFn.line,
+        depth,
+        remote: isRemote,
+        resolved: true,
+      });
+
+      // Continue BFS from the containing function
+      queue.push({ functionId: containingFn.id, depth: depth + 1, remote: isRemote });
+    }
+  }
+
+  return chain;
+}
+
+/**
+ * Walk up CONTAINS edges to find the enclosing FUNCTION/METHOD.
+ */
+async function findContainingFunction(
+  backend: GraphBackend,
+  nodeId: string,
+): Promise<{ id: string; name?: string; file?: string; line?: number } | null> {
+  let currentId = nodeId;
+  const seen = new Set<string>();
+
+  for (let i = 0; i < 10; i++) {
+    if (seen.has(currentId)) return null;
+    seen.add(currentId);
+
+    const incoming = await backend.getIncomingEdges(currentId, ['CONTAINS', 'HAS_SCOPE']);
+    if (incoming.length === 0) return null;
+
+    for (const edge of incoming) {
+      const parent = await backend.getNode(edge.src);
+      if (!parent) continue;
+      if (FUNCTION_TYPES.has(nodeType(parent))) {
+        return { id: parent.id, name: parent.name, file: parent.file, line: parent.line };
+      }
+      // Continue climbing from the parent
+      currentId = parent.id;
+      break;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Line-range fallback: find CALL nodes in the same file within the function's line range.
+ * Used when METHOD nodes have no outgoing edges (common for JS analyzer methods).
+ */
+async function findCallsByLineRange(
+  backend: GraphBackend,
+  functionId: string,
+  _maxDepth: number,
+): Promise<CallInfo[]> {
+  const fn = await backend.getNode(functionId);
+  if (!fn || !fn.file || !fn.line) return [];
+
+  // Query all CALL/METHOD_CALL nodes in the same file
+  // We use getIncomingEdges on the MODULE to find CONTAINS → CALL pattern
+  // But simpler: iterate all outgoing CALLS_REMOTE from this node directly
+  const directRemote = await backend.getOutgoingEdges(functionId, ['CALLS_REMOTE']);
+  const calls: CallInfo[] = [];
+
+  for (const edge of directRemote) {
+    const target = await backend.getNode(edge.dst);
+    if (!target) continue;
+    calls.push({
+      id: functionId,
+      name: target.name ?? '<unknown>',
+      type: 'CALL',
+      resolved: true,
+      target: { id: target.id, name: target.name ?? '<unknown>', file: target.file, line: target.line },
+      file: fn.file,
+      line: fn.line,
+      depth: 0,
+      remote: true,
+    });
+  }
+
+  return calls;
+}

package/src/queries/types.ts

@@ -34,6 +34,8 @@ export interface CallInfo {
   line?: number;
   /** Depth in transitive call chain (0 = direct call) */
   depth?: number;
+  /** Whether this call crosses a process/language boundary (CALLS_REMOTE) */
+  remote?: boolean;
 }
 
 /**

package/src/storage/backends/RFDBServerBackend.ts

@@ -21,6 +21,7 @@
 import { RFDBClient, type BatchHandle } from '@grafema/rfdb-client';
 import type { ChildProcess } from 'child_process';
 import { join, dirname } from 'path';
+import { createHash } from 'crypto';
 
 import type { WireNode, WireEdge, FieldDeclaration, CommitDelta, AttrQuery as RFDBAttrQuery, DatalogExplainResult, ServerStats, CypherResult } from '@grafema/types';
 import type { NodeType, EdgeType } from '@grafema/types';
@@ -119,11 +120,21 @@ export class RFDBServerBackend {
     this.silent = options.silent ?? false;
     this._clientName = options.clientName ?? 'core';
     // Default socket path: next to the database in .grafema folder
-    // This ensures each project has its own socket, avoiding conflicts
+    // This ensures each project has its own socket, avoiding conflicts.
+    // Unix socket paths have a hard limit (SUN_LEN: 104 on macOS, 108 on Linux).
+    // If the project path is too deep, fall back to /tmp with a hash to avoid conflicts.
     if (options.socketPath) {
       this.socketPath = options.socketPath;
     } else if (this.dbPath) {
-      this.socketPath = join(dirname(this.dbPath), 'rfdb.sock');
+      const localSocket = join(dirname(this.dbPath), 'rfdb.sock');
+      const SUN_LEN = process.platform === 'darwin' ? 104 : 108;
+      if (Buffer.byteLength(localSocket) < SUN_LEN) {
+        this.socketPath = localSocket;
+      } else {
+        // Hash the project path to create a unique but short socket path
+        const hash = createHash('md5').update(dirname(this.dbPath)).digest('hex').slice(0, 12);
+        this.socketPath = join('/tmp', `grafema-${hash}.sock`);
+      }
     } else {
       this.socketPath = '/tmp/rfdb.sock'; // fallback, not recommended
     }
@@ -283,6 +294,22 @@ export class RFDBServerBackend {
     this.serverProcess = null;
   }
 
+  /**
+   * Shutdown the RFDB server gracefully (flush + exit).
+   * Use before operations that invalidate the socket (e.g. clear + restart).
+   */
+  async shutdownServer(): Promise<void> {
+    if (!this.client) return;
+    try {
+      await this.client.shutdown();
+    } catch {
+      // Server may already be gone
+    }
+    this.client = null;
+    this.connected = false;
+    this.serverProcess = null;
+  }
+
   /**
    * Clear the database
    */

package/src/version.ts

@@ -26,3 +26,42 @@ export function getSchemaVersion(version: string): string {
   const base = version.split('-')[0];
   return base;
 }
+
+export interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+/**
+ * Parse a version string into structured major.minor.patch components.
+ * Strips pre-release tags before parsing.
+ *
+ * @param version - Version string (e.g., "0.2.5-beta")
+ * @returns Parsed version or null if the string is not a valid version
+ */
+export function parseVersion(version: string): ParsedVersion | null {
+  const base = getSchemaVersion(version);
+  const parts = base.split('.');
+  if (parts.length < 2) return null;
+  const major = parseInt(parts[0], 10);
+  const minor = parseInt(parts[1], 10);
+  const patch = parts.length >= 3 ? parseInt(parts[2], 10) : 0;
+  if (isNaN(major) || isNaN(minor) || isNaN(patch)) return null;
+  return { major, minor, patch };
+}
+
+/**
+ * Check if two versions are compatible (same major.minor).
+ * Patch differences are allowed — only major or minor mismatch is incompatible.
+ *
+ * @param configVersion - Version from the config file
+ * @param currentVersion - Currently running Grafema version
+ * @returns true if versions share the same major.minor
+ */
+export function isCompatibleVersion(configVersion: string, currentVersion: string): boolean {
+  const config = parseVersion(configVersion);
+  const current = parseVersion(currentVersion);
+  if (!config || !current) return false;
+  return config.major === current.major && config.minor === current.minor;
+}