@grafema/util 0.3.18 → 0.3.20

package/src/federation/ShardDiscovery.ts

@@ -0,0 +1,130 @@
+/**
+ * ShardDiscovery — discovers registered RFDB shards via /tmp/rfdb-shards/.
+ *
+ * Each rfdb-server running with --federate writes a JSON registration file
+ * containing its root path, socket, port, and PID. ShardDiscovery scans
+ * these files and resolves file paths to the appropriate shard.
+ *
+ * Discovery is by file path prefix: if a target file's absolute path
+ * starts with a shard's root, that shard owns the file.
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+export interface ShardRegistration {
+  /** Absolute path of the project root this shard covers */
+  root: string;
+  /** Unix socket path for this shard */
+  socket: string;
+  /** WebSocket port (if available) */
+  wsPort?: number;
+  /** Process ID of the rfdb-server */
+  pid: number;
+  /** Epoch timestamp when the server started */
+  started: number;
+  /** Server version */
+  serverVersion: string;
+}
+
+const SHARDS_DIR = '/tmp/rfdb-shards';
+
+export class ShardDiscovery {
+  /** root path → registration (sorted by longest root first for prefix matching) */
+  private shards = new Map<string, ShardRegistration>();
+
+  /** Number of discovered shards */
+  get size(): number {
+    return this.shards.size;
+  }
+
+  /** All registered shard roots */
+  get roots(): string[] {
+    return [...this.shards.keys()];
+  }
+
+  /**
+   * Scan /tmp/rfdb-shards/ for registered shards.
+   * Validates each registration: checks PID is alive, parses JSON.
+   * Call this periodically or before federated queries.
+   */
+  scan(): number {
+    this.shards.clear();
+
+    if (!existsSync(SHARDS_DIR)) {
+      return 0;
+    }
+
+    const files = readdirSync(SHARDS_DIR).filter(f => f.endsWith('.json'));
+
+    for (const file of files) {
+      try {
+        const raw = readFileSync(join(SHARDS_DIR, file), 'utf-8');
+        const reg = JSON.parse(raw) as ShardRegistration;
+
+        if (!reg.root || !reg.socket || !reg.pid) continue;
+
+        // Check if process is still alive
+        if (!isProcessAlive(reg.pid)) continue;
+
+        // Normalize root path (ensure no trailing slash)
+        const root = reg.root.replace(/\/$/, '');
+        this.shards.set(root, { ...reg, root });
+      } catch {
+        // Skip malformed registration files
+      }
+    }
+
+    return this.shards.size;
+  }
+
+  /**
+   * Find the shard that owns a given absolute file path.
+   * Uses longest-prefix matching: /repo/packages/api/ wins over /repo/.
+   */
+  resolve(absoluteFilePath: string): ShardRegistration | null {
+    let bestMatch: ShardRegistration | null = null;
+    let bestLength = 0;
+
+    for (const [root, reg] of this.shards) {
+      if (absoluteFilePath.startsWith(root) && root.length > bestLength) {
+        bestMatch = reg;
+        bestLength = root.length;
+      }
+    }
+
+    return bestMatch;
+  }
+
+  /**
+   * Get all known shards (for scatter-gather queries).
+   */
+  all(): ShardRegistration[] {
+    return [...this.shards.values()];
+  }
+
+  /**
+   * Register a shard programmatically (for testing or remote shards).
+   */
+  register(reg: ShardRegistration): void {
+    const root = reg.root.replace(/\/$/, '');
+    this.shards.set(root, { ...reg, root });
+  }
+
+  /**
+   * Remove a shard by root path.
+   */
+  unregister(root: string): void {
+    this.shards.delete(root.replace(/\/$/, ''));
+  }
+}
+
+/** Check if a process with given PID is alive */
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/federation/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Federation module — cross-shard query routing for RFDB.
+ *
+ * Enables multiple RFDB shards to discover each other and resolve
+ * cross-shard references at query time. Within a shard, the graph
+ * is fully materialized (analysis-time). Between shards, references
+ * are resolved lazily (execution-time) via the SUBGRAPH primitive.
+ *
+ * ## Architecture
+ *
+ * - ShardDiscovery: scans /tmp/rfdb-shards/ for registered shards
+ * - FederatedRouter: orchestrates cross-shard traversal and scatter-gather
+ * - Each shard is a separate rfdb-server process with its own graph
+ * - Discovery is by file path prefix matching (zero-config)
+ *
+ * ## Usage
+ *
+ *   const discovery = new ShardDiscovery();
+ *   await discovery.scan();
+ *
+ *   const router = new FederatedRouter(discovery, localClient);
+ *   const result = await router.traceDataflow('src/app.ts->userInput', 'forward', 10);
+ */
+
+export { ShardDiscovery } from './ShardDiscovery.js';
+export type { ShardRegistration } from './ShardDiscovery.js';
+
+export { FederatedRouter } from './FederatedRouter.js';
+export type {
+  FederatedTraceResult,
+  FederatedTraceHop,
+  FrontierEdge,
+  SubgraphResponse,
+  ManifestResolvedNode,
+} from './FederatedRouter.js';

package/src/index.ts

@@ -257,8 +257,19 @@ export type {
   TraceNarrativeOptions,
 } from './notation/index.js';
 
+// Federation — cross-shard query routing
+export { ShardDiscovery, FederatedRouter } from './federation/index.js';
+export type {
+  ShardRegistration,
+  FederatedTraceResult,
+  FederatedTraceHop,
+  FrontierEdge,
+  SubgraphResponse,
+  ManifestResolvedNode,
+} from './federation/index.js';
+
 // Manifest generation & resolution (federation)
-export { ManifestGenerator, ManifestResolver } from './manifest/index.js';
+export { ManifestGenerator, ManifestResolver, RegistryBuilder, resolvePackageDir, detectSourceType, resolveEntryPoint } from './manifest/index.js';
 export type {
   Manifest,
   ManifestExport,
@@ -269,6 +280,10 @@ export type {
   ExportKind,
   ResolveResult,
   ManifestSummary,
+  RegistryEntry,
+  RegistryIndex,
+  RegistryBuilderOptions,
+  BuildResult,
 } from './manifest/index.js';
 
 // Re-export types for convenience

package/src/manifest/generator.ts

@@ -174,9 +174,13 @@ export class ManifestGenerator {
       // Graph-based approach:
       // EXPORT(named) --EXPORTS--> EXPORT_BINDING(name, source) --> definition in source file
       await this.collectExportsViaBindings(entryFile, exports, seen, new Set());
-    } else {
-      // Fallback: all exported definitions from the package
+    }
+
+    // Fallback: if entry-file mode found 0 exports (e.g., CJS barrel,
+    // broken re-export chain in compiled_js), scan all exported definitions
+    if (exports.length === 0) {
       const prefix = this.options.packagePrefix ?? '';
+      // Check standard definition types (FUNCTION, CLASS, CONSTANT, INTERFACE)
       for (const type of ManifestGenerator.DEF_TYPES) {
         for await (const node of this.backend.queryNodes({ type: type as never })) {
           if (prefix && !node.file?.startsWith(prefix)) continue;
@@ -187,6 +191,21 @@ export class ManifestGenerator {
           await this.addExportFromDefinition(node, exports);
         }
       }
+      // Also check EXPORT_BINDING nodes (from CJS exports.foo = ...)
+      if (exports.length === 0) {
+        for await (const node of this.backend.queryNodes({ type: 'EXPORT_BINDING' as never })) {
+          if (prefix && !node.file?.startsWith(prefix)) continue;
+          if (!node.name || node.name === 'named' || node.name === 'default') continue;
+          if (seen.has(node.name)) continue;
+          seen.add(node.name);
+          exports.push({
+            name: node.name,
+            kind: 'VARIABLE',
+            semanticId: node.id,
+            effects: ['UNKNOWN'],
+          });
+        }
+      }
     }
 
     exports.sort((a, b) => a.name.localeCompare(b.name));
@@ -276,7 +295,8 @@ export class ManifestGenerator {
     const dir = fromFile.substring(0, fromFile.lastIndexOf('/'));
     let resolved = source.startsWith('.') ? `${dir}/${source}` : source;
     resolved = resolved.replace(/\/\.\//g, '/');
-    if (resolved.endsWith('.js')) {
+    // Only replace .js → .ts for source TypeScript code, not compiled_js
+    if (this.options.sourceType !== 'compiled_js' && resolved.endsWith('.js')) {
       resolved = resolved.replace(/\.js$/, '.ts');
     }
     return resolved;
@@ -330,7 +350,8 @@ export class ManifestGenerator {
   /** Enrich all exports with computed effects (transitive call graph analysis) */
   private async enrichEffects(exports: ManifestExport[]): Promise<void> {
     for (const entry of exports) {
-      if (entry.kind !== 'FUNCTION' && entry.kind !== 'CLASS') continue;
+      // Enrich FUNCTION, CLASS, and VARIABLE (CJS exports may be VARIABLE kind)
+      if (entry.kind !== 'FUNCTION' && entry.kind !== 'CLASS' && entry.kind !== 'VARIABLE') continue;
 
       const effects = new Set<EffectType>();
       const visited = new Set<string>();

package/src/manifest/index.ts

@@ -1,6 +1,8 @@
 export { ManifestGenerator } from './generator.js';
 export { ManifestResolver } from './resolver.js';
 export type { ResolveResult, ManifestSummary } from './resolver.js';
+export { RegistryBuilder, resolvePackageDir, detectSourceType, resolveEntryPoint } from './registry.js';
+export type { RegistryEntry, RegistryIndex, RegistryBuilderOptions, BuildResult } from './registry.js';
 export type {
   Manifest,
   ManifestExport,