@grafema/cli 0.1.1-alpha → 0.2.0-beta

package/dist/utils/formatNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatNode.d.ts","sourceRoot":"","sources":["../../src/utils/formatNode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAmB3F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,WAAW,EAAE,MAAM,GAClB,MAAM,CAIR"}
+{"version":3,"file":"formatNode.d.ts","sourceRoot":"","sources":["../../src/utils/formatNode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAyBhE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAoB3F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,WAAW,EAAE,MAAM,GAClB,MAAM,CAIR"}

package/dist/utils/formatNode.js

@@ -5,6 +5,38 @@
  * Semantic IDs are shown as the PRIMARY identifier, with location as secondary.
  */
 import { relative } from 'path';
+/**
+ * Get the display name for a node based on its type.
+ *
+ * HTTP nodes use method + path/url instead of name.
+ * Other nodes use their name field.
+ */
+export function getNodeDisplayName(node) {
+    switch (node.type) {
+        case 'http:route':
+            // Express routes: "GET /users"
+            if (node.method && node.path) {
+                return `${node.method} ${node.path}`;
+            }
+            break;
+        case 'http:request':
+            // Fetch/axios requests: "POST /api/data"
+            if (node.method && node.url) {
+                return `${node.method} ${node.url}`;
+            }
+            break;
+    }
+    // Default: use name, but guard against JSON metadata corruption
+    if (node.name && !node.name.startsWith('{')) {
+        return node.name;
+    }
+    // Fallback: extract name from semantic ID if possible
+    const parts = node.id.split('#');
+    if (parts.length > 1) {
+        return parts[1]; // Usually contains the key identifier
+    }
+    return node.id;
+}
 /**
  * Format a node for primary display (multi-line)
  *
@@ -16,8 +48,9 @@ import { relative } from 'path';
 export function formatNodeDisplay(node, options) {
     const { projectPath, showLocation = true, indent = '' } = options;
     const lines = [];
-    // Line 1: [TYPE] name
-    lines.push(`${indent}[${node.type}] ${node.name}`);
+    // Line 1: [TYPE] display name (type-specific)
+    const displayName = getNodeDisplayName(node);
+    lines.push(`${indent}[${node.type}] ${displayName}`);
     // Line 2: ID (semantic ID)
     lines.push(`${indent}  ID: ${node.id}`);
     // Line 3: Location (optional)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafema/cli",
-  "version": "0.1.1-alpha",
+  "version": "0.2.0-beta",
   "description": "CLI for Grafema code analysis toolkit",
   "type": "module",
   "main": "./dist/cli.js",
@@ -37,8 +37,8 @@
     "ink-text-input": "^6.0.0",
     "react": "^19.2.3",
     "yaml": "^2.8.2",
-    "@grafema/core": "0.1.1-alpha",
-    "@grafema/types": "0.1.1-alpha"
+    "@grafema/core": "0.2.0-beta",
+    "@grafema/types": "0.2.0-beta"
   },
   "devDependencies": {
     "@types/node": "^25.0.8",

package/src/cli.ts

@@ -8,6 +8,8 @@ import { initCommand } from './commands/init.js';
 import { analyzeCommand } from './commands/analyze.js';
 import { overviewCommand } from './commands/overview.js';
 import { queryCommand } from './commands/query.js';
+import { typesCommand } from './commands/types.js';
+import { lsCommand } from './commands/ls.js';
 import { getCommand } from './commands/get.js';
 import { traceCommand } from './commands/trace.js';
 import { impactCommand } from './commands/impact.js';
@@ -16,6 +18,9 @@ import { statsCommand } from './commands/stats.js';
 import { checkCommand } from './commands/check.js';
 import { serverCommand } from './commands/server.js';
 import { coverageCommand } from './commands/coverage.js';
+import { doctorCommand } from './commands/doctor.js';
+import { schemaCommand } from './commands/schema.js';
+import { explainCommand } from './commands/explain.js';
 
 const program = new Command();
 
@@ -29,6 +34,8 @@ program.addCommand(initCommand);
 program.addCommand(analyzeCommand);
 program.addCommand(overviewCommand);
 program.addCommand(queryCommand);
+program.addCommand(typesCommand);
+program.addCommand(lsCommand);
 program.addCommand(getCommand);
 program.addCommand(traceCommand);
 program.addCommand(impactCommand);
@@ -37,5 +44,8 @@ program.addCommand(statsCommand);  // Keep for backwards compat
 program.addCommand(coverageCommand);
 program.addCommand(checkCommand);
 program.addCommand(serverCommand);
+program.addCommand(doctorCommand);
+program.addCommand(schemaCommand);
+program.addCommand(explainCommand);
 
 program.parse();

package/src/commands/analyze.ts

@@ -24,6 +24,7 @@ import {
   // Analysis
   JSASTAnalyzer,
   ExpressRouteAnalyzer,
+  ExpressResponseAnalyzer,
   SocketIOAnalyzer,
   DatabaseAnalyzer,
   FetchAnalyzer,
@@ -32,12 +33,14 @@ import {
   RustAnalyzer,
   // Enrichment
   MethodCallResolver,
+  ArgumentParameterLinker,
   AliasTracker,
   ValueDomainAnalyzer,
   MountPointResolver,
   PrefixEvaluator,
   InstanceOfResolver,
   ImportExportLinker,
+  FunctionCallResolver,
   HTTPConnectionEnricher,
   RustFFIEnricher,
   // Validation
@@ -48,6 +51,7 @@ import {
   GraphConnectivityValidator,
   DataFlowValidator,
   TypeScriptDeadCodeValidator,
+  BrokenImportValidator,
 } from '@grafema/core';
 import type { LogLevel } from '@grafema/types';
 
@@ -62,6 +66,7 @@ const BUILTIN_PLUGINS: Record<string, () => Plugin> = {
   // Analysis
   JSASTAnalyzer: () => new JSASTAnalyzer() as Plugin,
   ExpressRouteAnalyzer: () => new ExpressRouteAnalyzer() as Plugin,
+  ExpressResponseAnalyzer: () => new ExpressResponseAnalyzer() as Plugin,
   SocketIOAnalyzer: () => new SocketIOAnalyzer() as Plugin,
   DatabaseAnalyzer: () => new DatabaseAnalyzer() as Plugin,
   FetchAnalyzer: () => new FetchAnalyzer() as Plugin,
@@ -70,12 +75,14 @@ const BUILTIN_PLUGINS: Record<string, () => 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,
   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,
   RustFFIEnricher: () => new RustFFIEnricher() as Plugin,
   // Validation
@@ -86,6 +93,7 @@ const BUILTIN_PLUGINS: Record<string, () => Plugin> = {
   GraphConnectivityValidator: () => new GraphConnectivityValidator() as Plugin,
   DataFlowValidator: () => new DataFlowValidator() as Plugin,
   TypeScriptDeadCodeValidator: () => new TypeScriptDeadCodeValidator() as Plugin,
+  BrokenImportValidator: () => new BrokenImportValidator() as Plugin,
 };
 
 function createPlugins(config: GrafemaConfig['plugins']): Plugin[] {
@@ -133,7 +141,18 @@ export const analyzeCommand = new Command('analyze')
   .option('-v, --verbose', 'Show verbose logging')
   .option('--debug', 'Enable debug mode (writes diagnostics.log)')
   .option('--log-level <level>', 'Set log level (silent, errors, warnings, info, debug)')
-  .action(async (path: string, options: { service?: string; entrypoint?: string; clear?: boolean; quiet?: boolean; verbose?: boolean; debug?: boolean; logLevel?: string }) => {
+  .option('--strict', 'Enable strict mode (fail on unresolved references)')
+  .addHelpText('after', `
+Examples:
+  grafema analyze                Analyze current project
+  grafema analyze ./my-project   Analyze specific directory
+  grafema analyze --clear        Clear database and rebuild from scratch
+  grafema analyze -s api         Analyze only "api" service (monorepo)
+  grafema analyze -v             Verbose output with progress details
+  grafema analyze --debug        Write diagnostics.log for debugging
+  grafema analyze --strict       Fail on unresolved references (debugging)
+`)
+  .action(async (path: string, options: { service?: string; entrypoint?: string; clear?: boolean; quiet?: boolean; verbose?: boolean; debug?: boolean; logLevel?: string; strict?: boolean }) => {
     const projectPath = resolve(path);
     const grafemaDir = join(projectPath, '.grafema');
     const dbPath = join(grafemaDir, 'graph.rfdb');
@@ -173,6 +192,12 @@ export const analyzeCommand = new Command('analyze')
 
     log(`Loaded ${plugins.length} plugins`);
 
+    // Resolve strict mode: CLI flag overrides config
+    const strictMode = options.strict ?? config.strict ?? false;
+    if (strictMode) {
+      log('Strict mode enabled - analysis will fail on unresolved references');
+    }
+
     const startTime = Date.now();
 
     const orchestrator = new Orchestrator({
@@ -183,6 +208,7 @@ export const analyzeCommand = new Command('analyze')
       forceAnalysis: options.clear || false,
       logger,
       services: config.services.length > 0 ? config.services : undefined,  // Pass config services (REG-174)
+      strictMode, // REG-330: Pass strict mode flag
       onProgress: (progress) => {
         if (options.verbose) {
           log(`[${progress.phase}] ${progress.message}`);
@@ -211,7 +237,7 @@ export const analyzeCommand = new Command('analyze')
       // Print summary if there are any issues
       if (diagnostics.count() > 0) {
         log('');
-        log(reporter.summary());
+        log(reporter.categorizedSummary());
 
         // In verbose mode, print full report
         if (options.verbose) {
@@ -220,10 +246,10 @@ export const analyzeCommand = new Command('analyze')
         }
       }
 
-      // Write diagnostics.log in debug mode
+      // Always write diagnostics.log (required for `grafema check` command)
+      const writer = new DiagnosticWriter();
+      await writer.write(diagnostics, grafemaDir);
       if (options.debug) {
-        const writer = new DiagnosticWriter();
-        await writer.write(diagnostics, grafemaDir);
         log(`Diagnostics written to ${writer.getLogPath(grafemaDir)}`);
       }
 

package/src/commands/check.ts

@@ -38,6 +38,37 @@ const BUILT_IN_VALIDATORS: Record<string, { name: string; description: string }>
   }
 };
 
+// Category definition for diagnostic filtering
+export interface DiagnosticCheckCategory {
+  name: string;
+  description: string;
+  codes: string[];
+}
+
+// Available diagnostic categories
+export const CHECK_CATEGORIES: Record<string, DiagnosticCheckCategory> = {
+  'connectivity': {
+    name: 'Graph Connectivity',
+    description: 'Check for disconnected nodes in the graph',
+    codes: ['ERR_DISCONNECTED_NODES', 'ERR_DISCONNECTED_NODE'],
+  },
+  'calls': {
+    name: 'Call Resolution',
+    description: 'Check for unresolved function calls',
+    codes: ['ERR_UNRESOLVED_CALL'],
+  },
+  'dataflow': {
+    name: 'Data Flow',
+    description: 'Check for missing assignments and broken references',
+    codes: ['ERR_MISSING_ASSIGNMENT', 'ERR_BROKEN_REFERENCE', 'ERR_NO_LEAF_NODE'],
+  },
+  'imports': {
+    name: 'Import Validation',
+    description: 'Check for broken imports and undefined symbols',
+    codes: ['ERR_BROKEN_IMPORT', 'ERR_UNDEFINED_SYMBOL'],
+  },
+};
+
 export const checkCommand = new Command('check')
   .description('Check invariants/guarantees')
   .argument('[rule]', 'Specific rule ID to check (or "all" for all rules)')
@@ -47,8 +78,22 @@ export const checkCommand = new Command('check')
   .option('-j, --json', 'Output results as JSON')
   .option('-q, --quiet', 'Only output failures')
   .option('--list-guarantees', 'List available built-in guarantees')
+  .option('--list-categories', 'List available diagnostic categories')
   .option('--skip-reanalysis', 'Skip automatic reanalysis of stale modules')
   .option('--fail-on-stale', 'Exit with error if stale modules found (CI mode)')
+  .addHelpText('after', `
+Examples:
+  grafema check                          Run all guarantee checks
+  grafema check connectivity             Check graph connectivity
+  grafema check calls                    Check call resolution
+  grafema check dataflow                 Check data flow integrity
+  grafema check all                      Run all diagnostic categories
+  grafema check --guarantee node-creation    Run built-in validator
+  grafema check --list-categories        List available categories
+  grafema check --list-guarantees        List built-in guarantees
+  grafema check --fail-on-stale          CI mode: fail if graph is stale
+  grafema check -q                       Only show failures (quiet mode)
+`)
   .action(
     async (
       rule: string | undefined,
@@ -59,10 +104,25 @@ export const checkCommand = new Command('check')
         json?: boolean;
         quiet?: boolean;
         listGuarantees?: boolean;
+        listCategories?: boolean;
         skipReanalysis?: boolean;
         failOnStale?: boolean;
       }
     ) => {
+      // List available categories
+      if (options.listCategories) {
+        console.log('Available diagnostic categories:');
+        console.log('');
+        for (const [key, category] of Object.entries(CHECK_CATEGORIES)) {
+          console.log(`  ${key}`);
+          console.log(`    ${category.name}`);
+          console.log(`    ${category.description}`);
+          console.log(`    Usage: grafema check ${key}`);
+          console.log('');
+        }
+        return;
+      }
+
       // List available guarantees
       if (options.listGuarantees) {
         console.log('Available built-in guarantees:');
@@ -75,6 +135,12 @@ export const checkCommand = new Command('check')
         return;
       }
 
+      // Check if rule argument is a category name
+      if (rule && (rule in CHECK_CATEGORIES || rule === 'all')) {
+        await runCategoryCheck(rule, options);
+        return;
+      }
+
       // Run built-in guarantee validator
       if (options.guarantee) {
         const validatorInfo = BUILT_IN_VALIDATORS[options.guarantee];
@@ -377,3 +443,138 @@ async function runBuiltInValidator(
     await backend.close();
   }
 }
+
+/**
+ * Run category-based diagnostic check
+ */
+async function runCategoryCheck(
+  category: string,
+  options: { project: string; json?: boolean; quiet?: boolean }
+): Promise<void> {
+  const resolvedPath = resolve(options.project);
+  const grafemaDir = join(resolvedPath, '.grafema');
+  const diagnosticsLogPath = join(grafemaDir, 'diagnostics.log');
+
+  if (!existsSync(diagnosticsLogPath)) {
+    exitWithError('No diagnostics found', [
+      'Run: grafema analyze',
+      'Diagnostics are collected during analysis'
+    ]);
+  }
+
+  // Read diagnostics from log file (JSON lines format)
+  const diagnosticsContent = readFileSync(diagnosticsLogPath, 'utf-8');
+  const allDiagnostics = diagnosticsContent
+    .split('\n')
+    .filter(line => line.trim())
+    .map(line => {
+      try {
+        return JSON.parse(line);
+      } catch (e) {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  // Filter diagnostics by category codes
+  let filteredDiagnostics = allDiagnostics;
+  if (category !== 'all') {
+    const categoryInfo = CHECK_CATEGORIES[category];
+    if (!categoryInfo) {
+      exitWithError(`Unknown category: ${category}`, [
+        'Use --list-categories to see available options'
+      ]);
+    }
+    filteredDiagnostics = allDiagnostics.filter((d: any) =>
+      categoryInfo.codes.includes(d.code)
+    );
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      category: category,
+      total: filteredDiagnostics.length,
+      diagnostics: filteredDiagnostics
+    }, null, 2));
+  } else {
+    const categoryName = category === 'all'
+      ? 'All Categories'
+      : CHECK_CATEGORIES[category].name;
+
+    if (!options.quiet) {
+      console.log(`Checking ${categoryName}...`);
+      console.log('');
+    }
+
+    if (filteredDiagnostics.length === 0) {
+      console.log('\x1b[32m✓\x1b[0m No issues found');
+    } else {
+      console.log(`\x1b[33m⚠\x1b[0m Found ${filteredDiagnostics.length} diagnostic(s):`);
+      console.log('');
+
+      // Group by severity
+      const errors = filteredDiagnostics.filter((d: any) => d.severity === 'error' || d.severity === 'fatal');
+      const warnings = filteredDiagnostics.filter((d: any) => d.severity === 'warning');
+      const infos = filteredDiagnostics.filter((d: any) => d.severity === 'info');
+
+      // Display errors first
+      if (errors.length > 0) {
+        console.log(`\x1b[31mErrors (${errors.length}):\x1b[0m`);
+        for (const diag of errors.slice(0, 10)) {
+          const location = diag.file ? `${diag.file}${diag.line ? `:${diag.line}` : ''}` : '';
+          console.log(`  \x1b[31m•\x1b[0m [${diag.code}] ${diag.message}`);
+          if (location) {
+            console.log(`    ${location}`);
+          }
+          if (diag.suggestion && !options.quiet) {
+            console.log(`    Suggestion: ${diag.suggestion}`);
+          }
+        }
+        if (errors.length > 10) {
+          console.log(`  ... and ${errors.length - 10} more errors`);
+        }
+        console.log('');
+      }
+
+      // Display warnings
+      if (warnings.length > 0) {
+        console.log(`\x1b[33mWarnings (${warnings.length}):\x1b[0m`);
+        for (const diag of warnings.slice(0, 10)) {
+          const location = diag.file ? `${diag.file}${diag.line ? `:${diag.line}` : ''}` : '';
+          console.log(`  \x1b[33m•\x1b[0m [${diag.code}] ${diag.message}`);
+          if (location) {
+            console.log(`    ${location}`);
+          }
+          if (diag.suggestion && !options.quiet) {
+            console.log(`    Suggestion: ${diag.suggestion}`);
+          }
+        }
+        if (warnings.length > 10) {
+          console.log(`  ... and ${warnings.length - 10} more warnings`);
+        }
+        console.log('');
+      }
+
+      // Display infos
+      if (infos.length > 0 && !options.quiet) {
+        console.log(`\x1b[36mInfo (${infos.length}):\x1b[0m`);
+        for (const diag of infos.slice(0, 5)) {
+          const location = diag.file ? `${diag.file}${diag.line ? `:${diag.line}` : ''}` : '';
+          console.log(`  \x1b[36m•\x1b[0m [${diag.code}] ${diag.message}`);
+          if (location) {
+            console.log(`    ${location}`);
+          }
+        }
+        if (infos.length > 5) {
+          console.log(`  ... and ${infos.length - 5} more info messages`);
+        }
+        console.log('');
+      }
+    }
+
+    console.log('');
+    if (filteredDiagnostics.some((d: any) => d.severity === 'error' || d.severity === 'fatal')) {
+      process.exit(1);
+    }
+  }
+}

package/src/commands/coverage.ts

@@ -18,6 +18,13 @@ export const coverageCommand = new Command('coverage')
   .option('-p, --project <path>', 'Project path', '.')
   .option('-j, --json', 'Output as JSON')
   .option('-v, --verbose', 'Show detailed file lists')
+  .addHelpText('after', `
+Examples:
+  grafema coverage               Show coverage summary
+  grafema coverage --verbose     Show detailed file lists
+  grafema coverage --json        Output coverage as JSON
+  grafema coverage -p ./app      Coverage for specific project
+`)
   .action(async (options: { project: string; json?: boolean; verbose?: boolean }) => {
     const projectPath = resolve(options.project);
     const grafemaDir = join(projectPath, '.grafema');