@grafema/cli 0.2.12-beta → 0.3.1-beta

package/src/commands/wtf.ts

@@ -0,0 +1,140 @@
+/**
+ * wtf command — "Where does this come from?"
+ *
+ * Backward dataflow trace with arrow-formatted output.
+ *
+ * Usage:
+ *   grafema wtf req.user              # Backward trace
+ *   grafema wtf config.apiKey         # Where does this value originate?
+ */
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+import {
+  RFDBServerBackend,
+  traceDataflow,
+  renderTraceNarrative,
+} from '@grafema/util';
+import type { DataflowBackend } from '@grafema/util';
+import { exitWithError } from '../utils/errorFormatter.js';
+import { Spinner } from '../utils/spinner.js';
+
+interface WtfCommandOptions {
+  project: string;
+  depth: string;
+  json?: boolean;
+}
+
+export const wtfCommand = new Command('wtf')
+  .description('Where does this come from? — backward dataflow trace')
+  .argument('<symbol>', 'Variable, constant, or parameter name to trace')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-d, --depth <n>', 'Max trace depth', '10')
+  .option('-j, --json', 'Output as JSON')
+  .addHelpText('after', `
+Examples:
+  grafema wtf req.user              Trace where req.user comes from
+  grafema wtf config.apiKey         Where does this value originate?
+  grafema wtf userId --depth 5      Limit trace depth
+  grafema wtf token --json          Output as JSON
+`)
+  .action(async (symbol: string, options: WtfCommandOptions) => {
+    const projectPath = resolve(options.project);
+    const grafemaDir = join(projectPath, '.grafema');
+    const dbPath = join(grafemaDir, 'graph.rfdb');
+
+    if (!existsSync(dbPath)) {
+      exitWithError('No graph database found', ['Run: grafema analyze']);
+    }
+
+    const maxDepth = parseInt(options.depth, 10);
+    if (isNaN(maxDepth) || maxDepth < 1) {
+      exitWithError('Invalid depth', ['Provide a positive integer']);
+    }
+
+    const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
+    await backend.connect();
+
+    const spinner = new Spinner('Searching for symbol...');
+    spinner.start();
+
+    try {
+      // Find the node: search VARIABLE, CONSTANT, PARAMETER by name (case-insensitive)
+      // Also try PROPERTY_ACCESS by matching method part after last dot
+      const lowerSymbol = symbol.toLowerCase();
+      // If symbol has a dot, extract the part after the last dot for method matching
+      const dotIndex = symbol.lastIndexOf('.');
+      const methodPart = dotIndex >= 0 ? symbol.substring(dotIndex + 1).toLowerCase() : null;
+
+      type FoundNode = { id: string; type: string; name: string; file: string; line?: number };
+      let found: FoundNode | null = null;
+
+      for (const nodeType of ['VARIABLE', 'CONSTANT', 'PARAMETER'] as const) {
+        for await (const n of backend.queryNodes({ type: nodeType })) {
+          const name = (n.name || '').toLowerCase();
+          if (name === lowerSymbol) {
+            found = { id: n.id, type: n.type || nodeType, name: n.name || '', file: n.file || '', line: n.line };
+            break;
+          }
+        }
+        if (found) break;
+      }
+
+      // Try PROPERTY_ACCESS if not found and symbol has a dot
+      if (!found && methodPart) {
+        for await (const n of backend.queryNodes({ type: 'PROPERTY_ACCESS' as any })) {
+          const name = (n.name || '').toLowerCase();
+          // Match by full name or by the part after last dot
+          const nameMethodPart = name.lastIndexOf('.') >= 0
+            ? name.substring(name.lastIndexOf('.') + 1)
+            : name;
+          if (name === lowerSymbol || nameMethodPart === methodPart) {
+            found = { id: n.id, type: n.type || 'PROPERTY_ACCESS', name: n.name || '', file: n.file || '', line: n.line };
+            break;
+          }
+        }
+      }
+
+      if (!found) {
+        spinner.stop();
+        exitWithError(`Symbol not found: "${symbol}"`, [
+          'Check the symbol name and try again',
+          'Use: grafema query "<name>" to search available nodes',
+        ]);
+        return;
+      }
+
+      spinner.stop();
+
+      // Cast backend to DataflowBackend
+      const dfDb = backend as unknown as DataflowBackend;
+
+      // Trace backward
+      const results = await traceDataflow(dfDb, found.id, {
+        direction: 'backward',
+        maxDepth,
+      });
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          symbol: found.name,
+          node: found,
+          results: results.map(r => ({
+            direction: r.direction,
+            startNode: r.startNode,
+            reached: r.reached,
+            totalReached: r.totalReached,
+          })),
+        }, null, 2));
+      } else {
+        console.log(`${found.name} (${found.type}) — ${found.file}${found.line ? ':' + found.line : ''}`);
+        console.log('');
+        const narrative = renderTraceNarrative(results, found.name, { detail: 'normal' });
+        console.log(narrative);
+      }
+    } finally {
+      spinner.stop();
+      await backend.close();
+    }
+  });

package/src/plugins/builtinPlugins.ts

@@ -1,108 +1 @@
-/**
- * Built-in plugin registry — maps plugin names to factory functions.
- *
- * Each entry creates a fresh plugin instance. Plugin names match the class names
- * and are referenced by name in .grafema/config.yaml under phases:
- * discovery, indexing, analysis, enrichment, validation.
- */
-
-import type { Plugin } from '@grafema/core';
-import {
-  // Discovery
-  SimpleProjectDiscovery,
-  MonorepoServiceDiscovery,
-  WorkspaceDiscovery,
-  // Indexing
-  JSModuleIndexer,
-  RustModuleIndexer,
-  // Analysis
-  JSASTAnalyzer,
-  ExpressRouteAnalyzer,
-  ExpressResponseAnalyzer,
-  NestJSRouteAnalyzer,
-  SocketIOAnalyzer,
-  DatabaseAnalyzer,
-  FetchAnalyzer,
-  ServiceLayerAnalyzer,
-  ReactAnalyzer,
-  RustAnalyzer,
-  // Enrichment
-  MethodCallResolver,
-  ArgumentParameterLinker,
-  AliasTracker,
-  ValueDomainAnalyzer,
-  MountPointResolver,
-  ExpressHandlerLinker,
-  PrefixEvaluator,
-  InstanceOfResolver,
-  ImportExportLinker,
-  FunctionCallResolver,
-  HTTPConnectionEnricher,
-  ConfigRoutingMapBuilder,
-  ServiceConnectionEnricher,
-  RustFFIEnricher,
-  RejectionPropagationEnricher,
-  CallbackCallResolver,
-  // Validation
-  CallResolverValidator,
-  EvalBanValidator,
-  SQLInjectionValidator,
-  AwaitInLoopValidator,
-  ShadowingDetector,
-  GraphConnectivityValidator,
-  DataFlowValidator,
-  TypeScriptDeadCodeValidator,
-  BrokenImportValidator,
-  UnconnectedRouteValidator,
-  PackageCoverageValidator,
-} from '@grafema/core';
-
-export const BUILTIN_PLUGINS: Record<string, () => Plugin> = {
-  // Discovery
-  SimpleProjectDiscovery: () => new SimpleProjectDiscovery() as Plugin,
-  MonorepoServiceDiscovery: () => new MonorepoServiceDiscovery() as Plugin,
-  WorkspaceDiscovery: () => new WorkspaceDiscovery() as Plugin,
-  // Indexing
-  JSModuleIndexer: () => new JSModuleIndexer() as Plugin,
-  RustModuleIndexer: () => new RustModuleIndexer() as Plugin,
-  // Analysis
-  JSASTAnalyzer: () => new JSASTAnalyzer() as Plugin,
-  ExpressRouteAnalyzer: () => new ExpressRouteAnalyzer() as Plugin,
-  ExpressResponseAnalyzer: () => new ExpressResponseAnalyzer() as Plugin,
-  NestJSRouteAnalyzer: () => new NestJSRouteAnalyzer() as Plugin,
-  SocketIOAnalyzer: () => new SocketIOAnalyzer() as Plugin,
-  DatabaseAnalyzer: () => new DatabaseAnalyzer() as Plugin,
-  FetchAnalyzer: () => new FetchAnalyzer() as Plugin,
-  ServiceLayerAnalyzer: () => new ServiceLayerAnalyzer() as Plugin,
-  ReactAnalyzer: () => new ReactAnalyzer() as Plugin,
-  RustAnalyzer: () => new RustAnalyzer() as Plugin,
-  // Enrichment
-  MethodCallResolver: () => new MethodCallResolver() as Plugin,
-  ArgumentParameterLinker: () => new ArgumentParameterLinker() as Plugin,
-  AliasTracker: () => new AliasTracker() as Plugin,
-  ValueDomainAnalyzer: () => new ValueDomainAnalyzer() as Plugin,
-  MountPointResolver: () => new MountPointResolver() as Plugin,
-  ExpressHandlerLinker: () => new ExpressHandlerLinker() as Plugin,
-  PrefixEvaluator: () => new PrefixEvaluator() as Plugin,
-  InstanceOfResolver: () => new InstanceOfResolver() as Plugin,
-  ImportExportLinker: () => new ImportExportLinker() as Plugin,
-  FunctionCallResolver: () => new FunctionCallResolver() as Plugin,
-  HTTPConnectionEnricher: () => new HTTPConnectionEnricher() as Plugin,
-  ConfigRoutingMapBuilder: () => new ConfigRoutingMapBuilder() as Plugin,
-  ServiceConnectionEnricher: () => new ServiceConnectionEnricher() as Plugin,
-  RustFFIEnricher: () => new RustFFIEnricher() as Plugin,
-  RejectionPropagationEnricher: () => new RejectionPropagationEnricher() as Plugin,
-  CallbackCallResolver: () => new CallbackCallResolver() as Plugin,
-  // Validation
-  CallResolverValidator: () => new CallResolverValidator() as Plugin,
-  EvalBanValidator: () => new EvalBanValidator() as Plugin,
-  SQLInjectionValidator: () => new SQLInjectionValidator() as Plugin,
-  AwaitInLoopValidator: () => new AwaitInLoopValidator() as Plugin,
-  ShadowingDetector: () => new ShadowingDetector() as Plugin,
-  GraphConnectivityValidator: () => new GraphConnectivityValidator() as Plugin,
-  DataFlowValidator: () => new DataFlowValidator() as Plugin,
-  TypeScriptDeadCodeValidator: () => new TypeScriptDeadCodeValidator() as Plugin,
-  BrokenImportValidator: () => new BrokenImportValidator() as Plugin,
-  UnconnectedRouteValidator: () => new UnconnectedRouteValidator() as Plugin,
-  PackageCoverageValidator: () => new PackageCoverageValidator() as Plugin,
-};
+// Deleted: plugin registration moved to grafema-orchestrator (Rust).

package/src/plugins/pluginLoader.ts

@@ -1,123 +1 @@
-/**
- * Plugin loading — resolves built-in and custom plugins from config.
- *
- * Handles:
- * - ESM resolve hook for custom plugin @grafema/* imports
- * - Loading custom plugins from .grafema/plugins/
- * - Creating plugin instances from config phases
- */
-
-import { join } from 'path';
-import { existsSync, readdirSync } from 'fs';
-import { pathToFileURL } from 'url';
-import { register } from 'node:module';
-import type { Plugin, GrafemaConfig } from '@grafema/core';
-import { BUILTIN_PLUGINS } from './builtinPlugins.js';
-
-/**
- * Register ESM resolve hook so custom plugins can import @grafema/* packages.
- *
- * Plugins in .grafema/plugins/ do `import { Plugin } from '@grafema/core'`,
- * but @grafema/core isn't in the target project's node_modules/.
- * This hook redirects those imports to the CLI's bundled packages.
- *
- * Uses module.register() (stable Node.js 20.6+ API).
- * Safe to call multiple times — subsequent calls add redundant hooks
- * that short-circuit on the same specifiers.
- */
-let pluginResolverRegistered = false;
-
-export function registerPluginResolver(): void {
-  if (pluginResolverRegistered) return;
-  pluginResolverRegistered = true;
-
-  const grafemaPackages: Record<string, string> = {};
-  for (const pkg of ['@grafema/core', '@grafema/types']) {
-    try {
-      grafemaPackages[pkg] = import.meta.resolve(pkg);
-    } catch {
-      // Package not available from CLI context — skip
-    }
-  }
-
-  register(
-    new URL('./pluginResolver.js', import.meta.url),
-    { data: { grafemaPackages } },
-  );
-}
-
-/**
- * Load custom plugins from .grafema/plugins/ directory
- */
-export async function loadCustomPlugins(
-  projectPath: string,
-  log: (msg: string) => void
-): Promise<Record<string, () => Plugin>> {
-  const pluginsDir = join(projectPath, '.grafema', 'plugins');
-  if (!existsSync(pluginsDir)) {
-    return {};
-  }
-
-  // Ensure @grafema/* imports resolve for custom plugins (REG-380)
-  registerPluginResolver();
-
-  const customPlugins: Record<string, () => Plugin> = {};
-
-  try {
-    const files = readdirSync(pluginsDir).filter(
-      (f) => f.endsWith('.js') || f.endsWith('.mjs') || f.endsWith('.cjs')
-    );
-
-    for (const file of files) {
-      try {
-        const pluginPath = join(pluginsDir, file);
-        const pluginUrl = pathToFileURL(pluginPath).href;
-        const module = await import(pluginUrl);
-
-        const PluginClass = module.default || module[file.replace(/\.[cm]?js$/, '')];
-        if (PluginClass && typeof PluginClass === 'function') {
-          const pluginName = PluginClass.name || file.replace(/\.[cm]?js$/, '');
-          customPlugins[pluginName] = () => {
-            const instance = new PluginClass() as Plugin;
-            instance.config.sourceFile = pluginPath;
-            return instance;
-          };
-          log(`Loaded custom plugin: ${pluginName}`);
-        }
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.warn(`Failed to load plugin ${file}: ${message}`);
-      }
-    }
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.warn(`Error loading custom plugins: ${message}`);
-  }
-
-  return customPlugins;
-}
-
-export function createPlugins(
-  config: GrafemaConfig['plugins'],
-  customPlugins: Record<string, () => Plugin> = {},
-  verbose: boolean = false
-): Plugin[] {
-  const plugins: Plugin[] = [];
-  const phases: (keyof GrafemaConfig['plugins'])[] = ['discovery', 'indexing', 'analysis', 'enrichment', 'validation'];
-
-  for (const phase of phases) {
-    const names = config[phase] || [];
-    for (const name of names) {
-      // Check built-in first, then custom
-      const factory = BUILTIN_PLUGINS[name] || customPlugins[name];
-      if (factory) {
-        plugins.push(factory());
-      } else if (verbose) {
-        // Only show plugin warning in verbose mode
-        console.warn(`Plugin not found: ${name} (skipping). Check .grafema/config.yaml or add to .grafema/plugins/`);
-      }
-    }
-  }
-
-  return plugins;
-}
+// Deleted: plugin loading moved to grafema-orchestrator (Rust).

package/src/plugins/pluginResolver.js

@@ -1,8 +1,8 @@
 /**
  * ESM resolve hook for custom Grafema plugins.
  *
- * Allows plugins in .grafema/plugins/ to `import { Plugin } from '@grafema/core'`
- * without requiring @grafema/core in the target project's node_modules/.
+ * Allows plugins in .grafema/plugins/ to `import { Plugin } from '@grafema/util'`
+ * without requiring @grafema/util in the target project's node_modules/.
  *
  * The hook maps @grafema/* bare specifiers to the actual package URLs
  * within the CLI's dependency tree.
@@ -26,7 +26,7 @@ export function initialize(data) {
  * Resolve hook — intercepts bare specifier imports for @grafema/* packages
  * and redirects them to the CLI's bundled versions.
  *
- * Only exact package name matches are handled (e.g. '@grafema/core').
+ * Only exact package name matches are handled (e.g. '@grafema/util').
  * All other specifiers pass through to the default resolver.
  */
 export function resolve(specifier, context, next) {

package/src/utils/progressRenderer.ts

@@ -15,7 +15,21 @@
  * ```
  */
 
-import type { ProgressInfo } from '@grafema/core';
+/**
+ * Progress information from the analysis pipeline.
+ * Defined locally to avoid dependency on @grafema/util.
+ */
+export interface ProgressInfo {
+  phase: string;
+  currentPlugin?: string;
+  message?: string;
+  servicesDiscovered?: number;
+  servicesAnalyzed?: number;
+  totalServices?: number;
+  totalFiles?: number;
+  processedFiles?: number;
+  currentService?: string;
+}
 
 /**
  * Options for creating a ProgressRenderer instance.

package/src/utils/queryHints.ts

@@ -0,0 +1,46 @@
+/**
+ * Query hint utilities for the CLI raw query path.
+ *
+ * Note: extractQueriedTypes() is intentionally duplicated from packages/mcp/src/utils.ts.
+ * The CLI cannot import @grafema/mcp (dependency direction). If the Datalog syntax changes,
+ * both copies must be updated.
+ */
+import { levenshtein } from '@grafema/util';
+
+export function extractQueriedTypes(query: string): { nodeTypes: string[]; edgeTypes: string[] } {
+  const nodeTypes: string[] = [];
+  const edgeTypes: string[] = [];
+
+  // Match node(VAR, "TYPE") — only working node predicate.
+  // type(VAR, "TYPE") is excluded: Rust evaluator has no "type" branch.
+  const nodeRegex = /\bnode\([^,)]+,\s*"([^"]+)"\)/g;
+  let m: RegExpExecArray | null;
+  while ((m = nodeRegex.exec(query)) !== null) {
+    nodeTypes.push(m[1]);
+  }
+
+  const edgeRegex = /\b(?:edge|incoming)\([^,)]+,\s*[^,)]+,\s*"([^"]+)"\)/g;
+  while ((m = edgeRegex.exec(query)) !== null) {
+    edgeTypes.push(m[1]);
+  }
+
+  return { nodeTypes, edgeTypes };
+}
+
+export function findSimilarTypes(
+  queriedType: string,
+  availableTypes: string[],
+  maxDistance: number = 2
+): string[] {
+  const queriedLower = queriedType.toLowerCase();
+  const similar: string[] = [];
+
+  for (const type of availableTypes) {
+    const dist = levenshtein(queriedLower, type.toLowerCase());
+    if (dist <= maxDistance && (dist > 0 || queriedType !== type)) {
+      similar.push(type);
+    }
+  }
+
+  return similar;
+}