@grafema/cli 0.2.5-beta → 0.2.7

package/src/commands/setup-skill.ts

@@ -0,0 +1,162 @@
+/**
+ * Setup-skill command - Install Grafema Agent Skill into a project
+ */
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync, mkdirSync, readFileSync, cpSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+/** Default install paths per platform */
+const PLATFORM_PATHS: Record<string, string> = {
+  claude: '.claude/skills',
+  gemini: '.gemini/skills',
+  cursor: '.cursor/skills',
+};
+
+const SKILL_DIR_NAME = 'grafema-codebase-analysis';
+
+interface SetupSkillOptions {
+  outputDir?: string;
+  platform?: string;
+  force?: boolean;
+}
+
+/**
+ * Get the bundled skill source directory.
+ * In the published package, skills/ is at the package root alongside dist/.
+ */
+function getSkillSourceDir(): string {
+  // __dirname is dist/commands/ -> go up to package root, then into skills/
+  return join(__dirname, '..', '..', 'skills', SKILL_DIR_NAME);
+}
+
+/**
+ * Read version from skill metadata.
+ */
+function getSkillVersion(skillDir: string): string | null {
+  const skillMd = join(skillDir, 'SKILL.md');
+  if (!existsSync(skillMd)) return null;
+
+  const content = readFileSync(skillMd, 'utf-8');
+  const versionMatch = content.match(/version:\s*"?([^"\n]+)"?/);
+  return versionMatch ? versionMatch[1].trim() : null;
+}
+
+/**
+ * Resolve the target directory for skill installation.
+ */
+function resolveTargetDir(projectPath: string, options: SetupSkillOptions): string {
+  if (options.outputDir) {
+    return resolve(options.outputDir, SKILL_DIR_NAME);
+  }
+
+  const platform = options.platform || 'claude';
+  const basePath = PLATFORM_PATHS[platform];
+  if (!basePath) {
+    throw new Error(
+      `Unknown platform: ${platform}. Supported: ${Object.keys(PLATFORM_PATHS).join(', ')}`
+    );
+  }
+
+  return join(projectPath, basePath, SKILL_DIR_NAME);
+}
+
+/**
+ * Copy skill directory recursively.
+ */
+function copySkill(sourceDir: string, targetDir: string): void {
+  mkdirSync(targetDir, { recursive: true });
+  cpSync(sourceDir, targetDir, { recursive: true });
+}
+
+/**
+ * Install the Grafema Agent Skill into a project directory.
+ * Returns true if skill was installed, false if skipped.
+ */
+export function installSkill(projectPath: string, options: SetupSkillOptions = {}): boolean {
+  const sourceDir = getSkillSourceDir();
+
+  if (!existsSync(sourceDir)) {
+    throw new Error(`Skill source not found at ${sourceDir}. Package may be corrupted.`);
+  }
+
+  const targetDir = resolveTargetDir(projectPath, options);
+
+  // Check if already installed
+  if (existsSync(targetDir) && !options.force) {
+    const installedVersion = getSkillVersion(targetDir);
+    const sourceVersion = getSkillVersion(sourceDir);
+
+    if (installedVersion === sourceVersion) {
+      return false; // Same version, skip
+    }
+
+    // Different version — warn but don't overwrite without --force
+    console.log(`  Skill exists (v${installedVersion}), latest is v${sourceVersion}`);
+    console.log('  Use --force to update, or run: grafema setup-skill --force');
+    return false;
+  }
+
+  copySkill(sourceDir, targetDir);
+  return true;
+}
+
+export const setupSkillCommand = new Command('setup-skill')
+  .description('Install Grafema Agent Skill into your project')
+  .argument('[path]', 'Project path', '.')
+  .option('--output-dir <path>', 'Custom output directory (overrides --platform)')
+  .option('--platform <name>', 'Target platform: claude, gemini, cursor', 'claude')
+  .option('-f, --force', 'Overwrite existing skill')
+  .addHelpText('after', `
+Examples:
+  grafema setup-skill                     Install for Claude Code (.claude/skills/)
+  grafema setup-skill --platform gemini   Install for Gemini CLI (.gemini/skills/)
+  grafema setup-skill --force             Update existing skill
+  grafema setup-skill --output-dir ./my-skills/
+`)
+  .action(async (path: string, options: SetupSkillOptions) => {
+    const projectPath = resolve(path);
+    const sourceDir = getSkillSourceDir();
+
+    if (!existsSync(sourceDir)) {
+      console.error('✗ Skill source not found. Package may be corrupted.');
+      process.exit(1);
+    }
+
+    const targetDir = resolveTargetDir(projectPath, options);
+
+    // Check if already installed
+    if (existsSync(targetDir) && !options.force) {
+      const installedVersion = getSkillVersion(targetDir);
+      const sourceVersion = getSkillVersion(sourceDir);
+
+      if (installedVersion === sourceVersion) {
+        console.log(`✓ Grafema skill already installed (v${installedVersion})`);
+        console.log(`  Location: ${targetDir}`);
+        return;
+      }
+
+      console.log(`  Skill exists (v${installedVersion}), latest is v${sourceVersion}`);
+      console.log('  Use --force to update');
+      return;
+    }
+
+    try {
+      copySkill(sourceDir, targetDir);
+    } catch (err) {
+      console.error('✗ Failed to install skill:', (err as Error).message);
+      process.exit(1);
+    }
+
+    const sourceVersion = getSkillVersion(sourceDir);
+    console.log(`✓ Grafema skill installed (v${sourceVersion})`);
+    console.log(`  Location: ${targetDir}`);
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Ensure Grafema MCP server is configured in your AI agent');
+    console.log('  2. Run "grafema analyze" to build the code graph');
+    console.log('  3. Your AI agent will now prefer graph queries over reading files');
+  });

package/src/commands/trace.ts

@@ -8,9 +8,9 @@
  */
 
 import { Command } from 'commander';
-import { resolve, join } from 'path';
+import { isAbsolute, resolve, join } from 'path';
 import { existsSync } from 'fs';
-import { RFDBServerBackend, parseSemanticId, traceValues, type ValueSource } from '@grafema/core';
+import { RFDBServerBackend, parseSemanticId, parseSemanticIdV2, traceValues, type ValueSource } from '@grafema/core';
 import { formatNodeDisplay, formatNodeInline } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 
@@ -227,12 +227,21 @@ async function findVariables(
       if (name.toLowerCase() === varName.toLowerCase()) {
         // If scope specified, check if variable is in that scope
         if (scopeName) {
-          const parsed = parseSemanticId(node.id);
-          if (!parsed) continue; // Skip nodes with invalid IDs
+          // Try v2 parsing first
+          const parsedV2 = parseSemanticIdV2(node.id);
+          if (parsedV2) {
+            if (!parsedV2.namedParent || parsedV2.namedParent.toLowerCase() !== lowerScopeName) {
+              continue;
+            }
+          } else {
+            // Fallback to v1 parsing
+            const parsed = parseSemanticId(node.id);
+            if (!parsed) continue; // Skip nodes with invalid IDs
 
-          // Check if scopeName appears anywhere in the scope chain
-          if (!parsed.scopePath.some(s => s.toLowerCase() === lowerScopeName)) {
-            continue;
+            // Check if scopeName appears anywhere in the scope chain
+            if (!parsed.scopePath.some(s => s.toLowerCase() === lowerScopeName)) {
+              continue;
+            }
           }
         }
 
@@ -738,7 +747,7 @@ async function handleSinkTrace(
     const sourcesCount = pv.sources.length;
     console.log(`  - ${JSON.stringify(pv.value)} (${sourcesCount} source${sourcesCount === 1 ? '' : 's'})`);
     for (const src of pv.sources.slice(0, 3)) {
-      const relativePath = src.file.startsWith(projectPath)
+      const relativePath = isAbsolute(src.file)
         ? src.file.substring(projectPath.length + 1)
         : src.file;
       console.log(`    <- ${relativePath}:${src.line}`);
@@ -900,7 +909,7 @@ async function handleRouteTrace(
     // Format traced values
     const sources = await Promise.all(
       traced.map(async (t) => {
-        const relativePath = t.source.file.startsWith(projectPath)
+        const relativePath = isAbsolute(t.source.file)
           ? t.source.file.substring(projectPath.length + 1)
           : t.source.file;
 

package/src/plugins/builtinPlugins.ts

@@ -0,0 +1,108 @@
+/**
+ * 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,
+};

package/src/plugins/pluginLoader.ts

@@ -0,0 +1,123 @@
+/**
+ * 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;
+}

package/src/plugins/pluginResolver.js

@@ -0,0 +1,38 @@
+/**
+ * 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/.
+ *
+ * The hook maps @grafema/* bare specifiers to the actual package URLs
+ * within the CLI's dependency tree.
+ *
+ * Registered via module.register() before loading custom plugins.
+ * Must be plain JS — loader hooks run in a separate thread.
+ */
+
+/** @type {Record<string, string>} package name → resolved file URL */
+let grafemaPackages = {};
+
+/**
+ * Called once when the hook is registered via module.register().
+ * @param {{ grafemaPackages: Record<string, string> }} data
+ */
+export function initialize(data) {
+  grafemaPackages = data.grafemaPackages;
+}
+
+/**
+ * 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').
+ * All other specifiers pass through to the default resolver.
+ */
+export function resolve(specifier, context, next) {
+  if (grafemaPackages[specifier]) {
+    return { url: grafemaPackages[specifier], shortCircuit: true };
+  }
+
+  return next(specifier, context);
+}

package/src/utils/codePreview.ts

@@ -6,12 +6,14 @@
  */
 
 import { readFileSync, existsSync } from 'fs';
+import { isAbsolute, join } from 'path';
 
 export interface CodePreviewOptions {
   file: string;
   line: number;
   contextBefore?: number;  // default: 2
   contextAfter?: number;   // default: 12
+  projectPath?: string;
 }
 
 export interface CodePreviewResult {
@@ -25,14 +27,16 @@ export interface CodePreviewResult {
  * Returns lines around the specified line number with context.
  */
 export function getCodePreview(options: CodePreviewOptions): CodePreviewResult | null {
-  const { file, line, contextBefore = 2, contextAfter = 12 } = options;
+  const { file, line, contextBefore = 2, contextAfter = 12, projectPath } = options;
 
-  if (!existsSync(file)) {
+  const absoluteFile = projectPath && !isAbsolute(file) ? join(projectPath, file) : file;
+
+  if (!existsSync(absoluteFile)) {
     return null;
   }
 
   try {
-    const content = readFileSync(file, 'utf-8');
+    const content = readFileSync(absoluteFile, 'utf-8');
     const allLines = content.split('\n');
 
     // Calculate range (1-indexed)

package/src/utils/formatNode.ts

@@ -5,7 +5,7 @@
  * Semantic IDs are shown as the PRIMARY identifier, with location as secondary.
  */
 
-import { relative } from 'path';
+import { isAbsolute, relative } from 'path';
 
 /**
  * Format options for node display
@@ -29,7 +29,7 @@ export interface DisplayableNode {
   type: string;
   /** Human-readable name */
   name: string;
-  /** Absolute file path */
+  /** Source file path (relative to project root, or absolute for legacy) */
   file: string;
   /** Line number (optional) */
   line?: number;
@@ -123,6 +123,6 @@ export function formatLocation(
   projectPath: string
 ): string {
   if (!file) return '';
-  const relPath = relative(projectPath, file);
+  const relPath = isAbsolute(file) ? relative(projectPath, file) : file;
   return line ? `${relPath}:${line}` : relPath;
 }

package/src/utils/pathUtils.ts

@@ -0,0 +1,9 @@
+/**
+ * Convert a node file path to relative display format.
+ * Handles both legacy absolute paths and new relative paths (REG-408).
+ */
+import { relative, isAbsolute } from 'path';
+
+export function toRelativeDisplay(file: string, projectPath: string): string {
+  return isAbsolute(file) ? relative(projectPath, file) : file;
+}

package/src/utils/progressRenderer.ts

@@ -45,6 +45,8 @@ export class ProgressRenderer {
   private totalFiles: number = 0;
   private processedFiles: number = 0;
   private servicesAnalyzed: number = 0;
+  private totalServices: number = 0;
+  private currentService: string = '';
   private spinnerIndex: number = 0;
   private isInteractive: boolean;
   private startTime: number;
@@ -100,6 +102,12 @@ export class ProgressRenderer {
     if (info.servicesAnalyzed !== undefined) {
       this.servicesAnalyzed = info.servicesAnalyzed;
     }
+    if (info.totalServices !== undefined) {
+      this.totalServices = info.totalServices;
+    }
+    if (info.currentService !== undefined) {
+      this.currentService = info.currentService;
+    }
 
     // Update spinner
     this.spinnerIndex = (this.spinnerIndex + 1) % this.spinnerFrames.length;
@@ -222,11 +230,20 @@ export class ProgressRenderer {
         }
         return '';
       case 'indexing':
-      case 'analysis':
-        if (this.totalFiles > 0) {
-          return ` ${this.processedFiles}/${this.totalFiles} modules`;
+      case 'analysis': {
+        const parts: string[] = [];
+        if (this.totalServices > 0) {
+          parts.push(`${this.servicesAnalyzed}/${this.totalServices} services`);
         }
-        return '';
+        if (this.currentService) {
+          // Truncate long service names
+          const name = this.currentService.length > 30
+            ? '...' + this.currentService.slice(-27)
+            : this.currentService;
+          parts.push(name);
+        }
+        return parts.length > 0 ? ` ${parts.join(' | ')}` : '';
+      }
       case 'enrichment':
       case 'validation':
         if (this.activePlugins.length > 0) {
@@ -268,6 +285,8 @@ export class ProgressRenderer {
     processedFiles: number;
     totalFiles: number;
     servicesAnalyzed: number;
+    totalServices: number;
+    currentService: string;
     spinnerIndex: number;
     activePlugins: string[];
     nodeCount: number;
@@ -279,6 +298,8 @@ export class ProgressRenderer {
       processedFiles: this.processedFiles,
       totalFiles: this.totalFiles,
       servicesAnalyzed: this.servicesAnalyzed,
+      totalServices: this.totalServices,
+      currentService: this.currentService,
       spinnerIndex: this.spinnerIndex,
       activePlugins: [...this.activePlugins],
       nodeCount: this.nodeCount,