@aiready/cli 0.9.27 → 0.9.28

package/src/commands/visualize.ts

@@ -0,0 +1,253 @@
+/**
+ * Visualize command - Generate interactive visualization from an AIReady report
+ */
+
+import chalk from 'chalk';
+import { writeFileSync, readFileSync, existsSync, copyFileSync } from 'fs';
+import { resolve as resolvePath } from 'path';
+import { spawn } from 'child_process';
+import { handleCLIError } from '@aiready/core';
+import { generateHTML } from '@aiready/core';
+import { findLatestScanReport } from '../utils/helpers';
+
+interface VisualizeOptions {
+  report?: string;
+  output?: string;
+  open?: boolean;
+  serve?: boolean | number;
+  dev?: boolean;
+}
+
+export async function visualizeAction(directory: string, options: VisualizeOptions) {
+  try {
+    const dirPath = resolvePath(process.cwd(), directory || '.');
+    let reportPath = options.report ? resolvePath(dirPath, options.report) : null;
+    
+    // If report not provided or not found, try to find latest scan report
+    if (!reportPath || !existsSync(reportPath)) {
+      const latestScan = findLatestScanReport(dirPath);
+      if (latestScan) {
+        reportPath = latestScan;
+        console.log(chalk.dim(`Found latest report: ${latestScan.split('/').pop()}`));
+      } else {
+        console.error(chalk.red('❌ No AI readiness report found'));
+        console.log(chalk.dim(`\nGenerate a report with:\n  aiready scan --output json\n\nOr specify a custom report:\n  aiready visualise --report <path-to-report.json>`));
+        return;
+      }
+    }
+
+    const raw = readFileSync(reportPath, 'utf8');
+    const report = JSON.parse(raw);
+
+    // Load config to extract graph caps
+    const configPath = resolvePath(dirPath, 'aiready.json');
+    let graphConfig = { maxNodes: 400, maxEdges: 600 };
+    
+    if (existsSync(configPath)) {
+      try {
+        const rawConfig = JSON.parse(readFileSync(configPath, 'utf8'));
+        if (rawConfig.visualizer?.graph) {
+          graphConfig = {
+            maxNodes: rawConfig.visualizer.graph.maxNodes ?? graphConfig.maxNodes,
+            maxEdges: rawConfig.visualizer.graph.maxEdges ?? graphConfig.maxEdges,
+          };
+        }
+      } catch (e) {
+        // Silently ignore parse errors and use defaults
+      }
+    }
+    
+    // Store config in env for vite middleware to pass to client
+    const envVisualizerConfig = JSON.stringify(graphConfig);
+    process.env.AIREADY_VISUALIZER_CONFIG = envVisualizerConfig;
+
+    console.log("Building graph from report...");
+    const { GraphBuilder } = await import('@aiready/visualizer/graph');
+    const graph = GraphBuilder.buildFromReport(report, dirPath);
+
+    if (options.dev) {
+      try {
+        const monorepoWebDir = resolvePath(dirPath, 'packages/visualizer');
+        let webDir = '';
+        let visualizerAvailable = false;
+        if (existsSync(monorepoWebDir)) {
+          webDir = monorepoWebDir;
+          visualizerAvailable = true;
+        } else {
+          // Try to resolve installed @aiready/visualizer package from node_modules
+          // Check multiple locations to support pnpm, npm, yarn, etc.
+          const nodemodulesLocations: string[] = [
+            resolvePath(dirPath, 'node_modules', '@aiready', 'visualizer'),
+            resolvePath(process.cwd(), 'node_modules', '@aiready', 'visualizer'),
+          ];
+          
+          // Walk up directory tree to find node_modules in parent directories
+          let currentDir = dirPath;
+          while (currentDir !== '/' && currentDir !== '.') {
+            nodemodulesLocations.push(resolvePath(currentDir, 'node_modules', '@aiready', 'visualizer'));
+            const parent = resolvePath(currentDir, '..');
+            if (parent === currentDir) break; // Reached filesystem root
+            currentDir = parent;
+          }
+          
+          for (const location of nodemodulesLocations) {
+            if (existsSync(location) && existsSync(resolvePath(location, 'package.json'))) {
+              webDir = location;
+              visualizerAvailable = true;
+              break;
+            }
+          }
+          
+          // Fallback: try require.resolve
+          if (!visualizerAvailable) {
+            try {
+              const vizPkgPath = require.resolve('@aiready/visualizer/package.json');
+              webDir = resolvePath(vizPkgPath, '..');
+              visualizerAvailable = true;
+            } catch (e) {
+              // Visualizer not found
+            }
+          }
+        }
+        const spawnCwd = webDir || process.cwd();
+        const nodeBinCandidate = process.execPath;
+        const nodeBin = existsSync(nodeBinCandidate) ? nodeBinCandidate : 'node';
+        if (!visualizerAvailable) {
+          console.error(chalk.red('❌ Cannot start dev server: @aiready/visualizer not available.'));
+          console.log(chalk.dim('Install @aiready/visualizer in your project with:\n  npm install @aiready/visualizer'));
+          return;
+        }
+
+        // Inline report watcher: copy report to web/report-data.json and watch for changes
+        const { watch } = await import('fs');
+        const copyReportToViz = () => {
+          try {
+            const destPath = resolvePath(spawnCwd, 'web', 'report-data.json');
+            copyFileSync(reportPath!, destPath);
+            console.log(`📋 Report synced to ${destPath}`);
+          } catch (e) {
+            console.error('Failed to sync report:', e);
+          }
+        };
+        
+        // Initial copy
+        copyReportToViz();
+        
+        // Watch source report for changes
+        let watchTimeout: NodeJS.Timeout | null = null;
+        const reportWatcher = watch(reportPath, () => {
+          // Debounce to avoid multiple copies during file write
+          if (watchTimeout) clearTimeout(watchTimeout);
+          watchTimeout = setTimeout(copyReportToViz, 100);
+        });
+
+        const envForSpawn = { 
+          ...process.env, 
+          AIREADY_REPORT_PATH: reportPath,
+          AIREADY_VISUALIZER_CONFIG: envVisualizerConfig 
+        };
+        const vite = spawn("pnpm", ["run", "dev:web"], { cwd: spawnCwd, stdio: "inherit", shell: true, env: envForSpawn });
+        const onExit = () => {
+          try {
+            reportWatcher.close();
+          } catch (e) {}
+          try {
+            vite.kill();
+          } catch (e) {}
+          process.exit(0);
+        };
+        process.on("SIGINT", onExit);
+        process.on("SIGTERM", onExit);
+        return;
+      } catch (err) {
+        console.error("Failed to start dev server:", err);
+      }
+    }
+
+    console.log("Generating HTML...");
+    const html = generateHTML(graph);
+    const outPath = resolvePath(dirPath, options.output || 'packages/visualizer/visualization.html');
+    writeFileSync(outPath, html, 'utf8');
+    console.log("Visualization written to:", outPath);
+    
+
+    if (options.open) {
+      const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+      spawn(opener, [`"${outPath}"`], { shell: true });
+    }
+
+    if (options.serve) {
+      try {
+        const port = typeof options.serve === 'number' ? options.serve : 5173;
+        const http = await import('http');
+        const fsp = await import('fs/promises');
+
+        const server = http.createServer(async (req, res) => {
+          try {
+            const urlPath = req.url || '/';
+            if (urlPath === '/' || urlPath === '/index.html') {
+              const content = await fsp.readFile(outPath, 'utf8');
+              res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+              res.end(content);
+              return;
+            }
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            res.end('Not found');
+          } catch (e: any) {
+            res.writeHead(500, { 'Content-Type': 'text/plain' });
+            res.end('Server error');
+          }
+        });
+
+        server.listen(port, () => {
+          const addr = `http://localhost:${port}/`;
+          console.log(`Local visualization server running at ${addr}`);
+          const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+          spawn(opener, [`"${addr}"`], { shell: true });
+        });
+
+        process.on('SIGINT', () => {
+          server.close();
+          process.exit(0);
+        });
+      } catch (err) {
+        console.error('Failed to start local server:', err);
+      }
+    }
+
+  } catch (err: any) {
+    handleCLIError(err, 'Visualization');
+  }
+}
+
+export const visualizeHelpText = `
+EXAMPLES:
+  $ aiready visualize .  # Auto-detects latest report
+  $ aiready visualize . --report .aiready/aiready-report-20260217-143022.json
+  $ aiready visualize . --report report.json -o out/visualization.html --open
+  $ aiready visualize . --report report.json --serve
+  $ aiready visualize . --report report.json --serve 8080
+  $ aiready visualize . --report report.json --dev
+
+NOTES:
+  - The value passed to --report is interpreted relative to the directory argument (first positional).
+    If the report is not found, the CLI will suggest running 'aiready scan' to generate it.
+  - Default output path: packages/visualizer/visualization.html (relative to the directory argument).
+  - --serve starts a tiny single-file HTTP server (default port: 5173) and opens your browser.
+    It serves only the generated HTML (no additional asset folders).
+  - Relatedness is represented by node proximity and size; explicit 'related' edges are not drawn to
+    reduce clutter and improve interactivity on large graphs.
+  - For very large graphs, consider narrowing the input with --include/--exclude or use --serve and
+    allow the browser a moment to stabilize after load.
+`;
+
+export const visualiseHelpText = `
+EXAMPLES:
+  $ aiready visualise .  # Auto-detects latest report
+  $ aiready visualise . --report .aiready/aiready-report-20260217-143022.json
+  $ aiready visualise . --report report.json --dev
+  $ aiready visualise . --report report.json --serve 8080
+
+NOTES:
+  - Same options as 'visualize'. Use --dev for live reload and --serve to host a static HTML.
+`;

package/src/utils/helpers.ts

@@ -0,0 +1,133 @@
+/**
+ * Shared helper functions for CLI commands
+ */
+
+import { resolve as resolvePath } from 'path';
+import { existsSync, readdirSync, statSync, readFileSync, copyFileSync } from 'fs';
+import chalk from 'chalk';
+
+/**
+ * Generate timestamp for report filenames (YYYYMMDD-HHMMSS)
+ * Provides better granularity than date-only filenames
+ */
+export function getReportTimestamp(): string {
+  const now = new Date();
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+/**
+ * Find the latest aiready report in the .aiready directory
+ * Searches for both new format (aiready-report-*) and legacy format (aiready-scan-*)
+ */
+export function findLatestScanReport(dirPath: string): string | null {
+  const aireadyDir = resolvePath(dirPath, '.aiready');
+  if (!existsSync(aireadyDir)) {
+    return null;
+  }
+  
+  // Search for new format first, then legacy format
+  let files = readdirSync(aireadyDir).filter(f => f.startsWith('aiready-report-') && f.endsWith('.json'));
+  if (files.length === 0) {
+    files = readdirSync(aireadyDir).filter(f => f.startsWith('aiready-scan-') && f.endsWith('.json'));
+  }
+  
+  if (files.length === 0) {
+    return null;
+  }
+  
+  // Sort by modification time, most recent first
+  const sortedFiles = files
+    .map(f => ({ name: f, path: resolvePath(aireadyDir, f), mtime: statSync(resolvePath(aireadyDir, f)).mtime }))
+    .sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+  
+  return sortedFiles[0].path;
+}
+
+/**
+ * Warn if graph caps may be exceeded
+ */
+export function warnIfGraphCapExceeded(report: any, dirPath: string) {
+  try {
+    // Use dynamic import and loadConfig to get the raw visualizer config
+    const { loadConfig } = require('@aiready/core');
+    
+    let graphConfig = { maxNodes: 400, maxEdges: 600 };
+    
+    // Try to read aiready.json synchronously
+    const configPath = resolvePath(dirPath, 'aiready.json');
+    if (existsSync(configPath)) {
+      try {
+        const rawConfig = JSON.parse(readFileSync(configPath, 'utf8'));
+        if (rawConfig.visualizer?.graph) {
+          graphConfig = {
+            maxNodes: rawConfig.visualizer.graph.maxNodes ?? graphConfig.maxNodes,
+            maxEdges: rawConfig.visualizer.graph.maxEdges ?? graphConfig.maxEdges,
+          };
+        }
+      } catch (e) {
+        // Silently ignore parse errors and use defaults
+      }
+    }
+    
+    const nodeCount = (report.context?.length || 0) + (report.patterns?.length || 0);
+    const edgeCount = report.context?.reduce((sum: number, ctx: any) => {
+      const relCount = ctx.relatedFiles?.length || 0;
+      const depCount = ctx.dependencies?.length || 0;
+      return sum + relCount + depCount;
+    }, 0) || 0;
+    
+    if (nodeCount > graphConfig.maxNodes || edgeCount > graphConfig.maxEdges) {
+      console.log('');
+      console.log(chalk.yellow(`⚠️  Graph may be truncated at visualization time:`));
+      if (nodeCount > graphConfig.maxNodes) {
+        console.log(chalk.dim(`   • Nodes: ${nodeCount} > limit ${graphConfig.maxNodes}`));
+      }
+      if (edgeCount > graphConfig.maxEdges) {
+        console.log(chalk.dim(`   • Edges: ${edgeCount} > limit ${graphConfig.maxEdges}`));
+      }
+      console.log(chalk.dim(`   To increase limits, add to aiready.json:`));
+      console.log(chalk.dim(`   {`));
+      console.log(chalk.dim(`     "visualizer": {`));
+      console.log(chalk.dim(`       "graph": { "maxNodes": 2000, "maxEdges": 5000 }`));
+      console.log(chalk.dim(`     }`));
+      console.log(chalk.dim(`   }`));
+    }
+  } catch (e) {
+    // Silently fail on config read errors
+  }
+}
+
+/**
+ * Generate markdown report for consistency command
+ */
+export function generateMarkdownReport(report: any, elapsedTime: string): string {
+  let markdown = `# Consistency Analysis Report\n\n`;
+  markdown += `**Generated:** ${new Date().toISOString()}\n`;
+  markdown += `**Analysis Time:** ${elapsedTime}s\n\n`;
+
+  markdown += `## Summary\n\n`;
+  markdown += `- **Files Analyzed:** ${report.summary.filesAnalyzed}\n`;
+  markdown += `- **Total Issues:** ${report.summary.totalIssues}\n`;
+  markdown += `  - Naming: ${report.summary.namingIssues}\n`;
+  markdown += `  - Patterns: ${report.summary.patternIssues}\n\n`;
+
+  if (report.recommendations.length > 0) {
+    markdown += `## Recommendations\n\n`;
+    report.recommendations.forEach((rec: string, i: number) => {
+      markdown += `${i + 1}. ${rec}\n`;
+    });
+  }
+
+  return markdown;
+}
+
+/**
+ * Truncate array for display (show first N items with "... +N more")
+ */
+export function truncateArray(arr: any[] | undefined, cap = 8): string {
+  if (!Array.isArray(arr)) return '';
+  const shown = arr.slice(0, cap).map((v) => String(v));
+  const more = arr.length - shown.length;
+  return shown.join(', ') + (more > 0 ? `, ... (+${more} more)` : '');
+}

package/tsconfig.json

@@ -2,7 +2,10 @@
   "extends": "../core/tsconfig.json",
   "compilerOptions": {
     "outDir": "./dist",
-    "rootDir": "./src"
+    "rootDir": "./src",
+    "types": ["node"],
+    "lib": ["ES2020"],
+    "moduleResolution": "bundler"
   },
   "include": ["src/**/*"]
-}
+}