@brainwav/diagram 1.0.7 → 1.1.0

package/src/commands/analyze.js

@@ -0,0 +1,125 @@
+const chalk = require('chalk');
+const {
+  applyDiagramRcDefaults,
+  getDiagramRcFromProgram,
+  maybeWriteArchitectureIR,
+  resolveRootPathOrExit,
+  runAnalysisPipeline,
+} = require('./shared');
+const { buildMachineEnvelope } = require('./output');
+
+/**
+ * Register the `analyze [path]` CLI subcommand on the provided commander program.
+ *
+ * The subcommand analyzes a codebase root, runs the analysis pipeline, and emits
+ * either a human-readable summary or a machine-friendly JSON envelope. It also
+ * supports options for file patterns, exclusions, max files, analyzer selection,
+ * emitting a typed architecture IR, incremental analysis, output format,
+ * deterministic output and quiet mode.
+ *
+ * @param {import('commander').Command} program - Commander program instance to attach the subcommand to.
+ */
+function registerAnalyzeCommand(program) {
+  program
+    .command('analyze [path]')
+    .description('Analyze codebase structure')
+    .option('-p, --patterns <list>', 'File patterns (comma-separated)')
+    .option('-e, --exclude <list>', 'Exclude patterns')
+    .option('-m, --max-files <n>', 'Max files to analyze')
+    .option('--analyzer <name>', 'Analyzer plugin to use', 'default')
+    .option('--emit-ir', 'Write typed architecture IR artifact', false)
+    .option('--incremental', 'Use incremental cache when available', false)
+    .option('-f, --format <type>', 'Output format (text, json)', 'text')
+    .option('--deterministic', 'Use deterministic machine output', false)
+    .option('-q, --quiet', 'Suppress non-essential logging', false)
+    .action(async (targetPath, rawOptions) => {
+      const options = applyDiagramRcDefaults(rawOptions, getDiagramRcFromProgram(program), ['patterns', 'exclude', 'maxFiles']);
+      const root = resolveRootPathOrExit(targetPath);
+      const formatStr = String(options.format || 'text').toLowerCase().trim();
+      const allowedFormats = new Set(['text', 'json']);
+      if (!allowedFormats.has(formatStr)) {
+        console.error(chalk.red('❌ Invalid format:'), options.format);
+        console.error(chalk.gray('Fix: use --format text or --format json.'));
+        process.exit(2);
+      }
+      const isJson = formatStr === 'json';
+      if (!options.quiet) {
+        console.error(chalk.blue('Analyzing'), root);
+      }
+
+      const pipeline = await runAnalysisPipeline(root, options, 'analyze');
+      const data = pipeline.analysis;
+      const irPath = options.emitIr
+        ? maybeWriteArchitectureIR(root, data, pipeline.analyzer, true)
+        : null;
+
+      if (isJson) {
+        const payload = buildMachineEnvelope({
+          schemaVersion: '1.0',
+          command: 'analyze',
+          rootPath: root,
+          deterministic: Boolean(options.deterministic),
+          data: {
+            analysis: data,
+            analyzer: pipeline.analyzer,
+            incremental: pipeline.incremental,
+            artifacts: {
+              architectureIrPath: irPath || null,
+            },
+          },
+          agentSummary: {
+            componentCount: data.components?.length || 0,
+            entryPoints: data.entryPoints || [],
+            dominantLanguages: Object.entries(data.languages || {})
+              .sort((a, b) => b[1] - a[1])
+              .slice(0, 3)
+              .map(([language]) => language),
+            suggestedReviewerChecks: [
+              'Inspect top dependency hubs for unwanted coupling.',
+              'Confirm entry points align with intended service boundaries.',
+            ],
+          },
+        });
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      if (irPath && !options.quiet) {
+        console.error(chalk.gray('  IR:'), irPath);
+      }
+
+      const components = data.components || [];
+      const languages = data.languages || {};
+      const entryPoints = data.entryPoints || [];
+      console.log(chalk.green('\n📊 Summary'));
+      console.log(`  Files: ${components.length}`);
+      console.log(`  Languages: ${Object.entries(languages).map(([k, v]) => `${k}(${v})`).join(', ') || 'none'}`);
+      console.log(`  Entry points: ${entryPoints.join(', ') || 'none'}`);
+      console.log(`\n${chalk.yellow('Components:')}`);
+      components.slice(0, 15).forEach((component) => {
+        const deps = component.dependencies.length > 0
+          ? ` → ${component.dependencies.slice(0, 3).join(', ')}`
+          : '';
+        console.log(`  ${component.originalName} (${component.type})${deps}`);
+      });
+      if (components.length > 15) {
+        console.log(chalk.gray(`  ... and ${components.length - 15} more`));
+      }
+      if (pipeline.incremental.requested) {
+        const message = pipeline.incremental.used
+          ? `cache hit (${pipeline.incremental.reason})`
+          : `fallback full scan (${pipeline.incremental.reason})`;
+        console.log(chalk.gray(`  Incremental: ${message}`));
+      }
+
+      if (!options.quiet) {
+        console.log(chalk.cyan('\nNext steps:'));
+        console.log('  1) Run `archscope generate . --type architecture` to visualize structure.');
+        console.log('  2) Run `archscope validate .` to enforce architecture policy.');
+      }
+    });
+}
+
+module.exports = {
+  registerAnalyzeCommand,
+};

package/src/commands/changed.js

@@ -0,0 +1,185 @@
+const chalk = require('chalk');
+const { generate } = require('../core/analysis-generation');
+const { validateGitRef, getChangedFiles, runGitCommand } = require('../workflow/git-helpers');
+const {
+  applyDiagramRcDefaults,
+  getDiagramRcFromProgram,
+  resolveRootPathOrExit,
+  runAnalysisPipeline,
+} = require('./shared');
+const { buildMachineEnvelope } = require('./output');
+
+/**
+ * Collects file paths changed in the working tree for the repository at `root`.
+ *
+ * Gathers tracked unstaged changes, staged changes and untracked files, then returns a deduplicated, alphabetically sorted list of file paths. If the repository has no commits (invalid `HEAD` / bad revision), tracked changes are treated as empty rather than causing an error.
+ * @param {string} root - Path to the git repository root.
+ * @returns {string[]} Deduplicated, alphabetically sorted file paths that are added, modified, renamed or untracked.
+ */
+function listWorkingTreeChangedFiles(root) {
+  let tracked = [];
+  try {
+    tracked = runGitCommand(['diff', '--name-only', '--diff-filter=ACMR', 'HEAD'], root)
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean);
+  } catch (error) {
+    // Repos with no commits will fail on HEAD reference
+    if (error.message && (error.message.includes('HEAD') || error.message.includes('bad revision'))) {
+      tracked = [];
+    } else {
+      throw error;
+    }
+  }
+  const staged = runGitCommand(['diff', '--cached', '--name-only', '--diff-filter=ACMR'], root)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const untracked = runGitCommand(['ls-files', '--others', '--exclude-standard'], root)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return [...new Set([...tracked, ...staged, ...untracked])].sort();
+}
+
+/**
+ * Register the `changed` CLI subcommand to analyse git-changed files.
+ *
+ * The command computes the set of changed files (either from a base..head git delta
+ * when `--base` is provided, or from the working tree otherwise), runs the analysis
+ * pipeline restricted to those files, and prints a summary in either text or JSON.
+ * When a diagram type is requested via `--type` a preview diagram may be included
+ * in the output. The command also supports common options for patterns, excludes,
+ * max files, analyzer selection, deterministic output and quiet mode.
+ *
+ * @param {Object} program - Commander `program` instance to attach the `changed` subcommand to.
+ */
+function registerChangedCommand(program) {
+  program
+    .command('changed [path]')
+    .description('Analyze only git-changed files')
+    .option('--base <ref>', 'Base git ref')
+    .option('--head <ref>', 'Head git ref', 'HEAD')
+    .option('-m, --max-files <n>', 'Max files to analyze')
+    .option('-p, --patterns <list>', 'File patterns (comma-separated)')
+    .option('-e, --exclude <list>', 'Exclude patterns')
+    .option('--analyzer <name>', 'Analyzer plugin to use', 'default')
+    .option('--type <diagramType>', 'Optional diagram type preview (e.g. architecture, dependency)')
+    .option('--format <type>', 'Output format (text, json)', 'text')
+    .option('--deterministic', 'Use deterministic machine output', false)
+    .option('-q, --quiet', 'Suppress non-essential logging', false)
+    .action(async (targetPath, rawOptions) => {
+      const options = applyDiagramRcDefaults(rawOptions, getDiagramRcFromProgram(program), ['patterns', 'exclude', 'maxFiles']);
+      const root = resolveRootPathOrExit(targetPath);
+      const formatStr = (options.format || 'text').toLowerCase();
+      const isJson = formatStr === 'json';
+
+      let changedFiles = [];
+      if (options.base) {
+        const baseSha = validateGitRef(options.base, root);
+        const headSha = validateGitRef(options.head || 'HEAD', root);
+        const delta = getChangedFiles(baseSha, headSha, root);
+        changedFiles = [
+          ...(delta.changed || []),
+          ...(delta.added || []),
+          ...((delta.renamed || []).map((entry) => entry?.to).filter(Boolean)),
+        ];
+      } else {
+        changedFiles = listWorkingTreeChangedFiles(root);
+      }
+
+      const includeFiles = [...new Set(changedFiles.filter((filePath) => filePath && !filePath.endsWith('/')))];
+      if (includeFiles.length === 0) {
+        if (isJson) {
+          const payload = buildMachineEnvelope({
+            schemaVersion: '1.0',
+            command: 'changed',
+            rootPath: root,
+            deterministic: Boolean(options.deterministic),
+            data: {
+              changedFiles: [],
+              analysis: null,
+              diagram: null,
+            },
+            agentSummary: {
+              changedComponents: 0,
+              riskReasons: [],
+              suggestedReviewerChecks: ['No changed files detected.'],
+            },
+          });
+          console.log(JSON.stringify(payload, null, 2));
+          return;
+        }
+        console.log(chalk.green('✅ No changed files detected.'));
+        console.log(chalk.cyan('\nNext steps:'));
+        console.log('  1) Continue with `archscope validate .` for full rule coverage.');
+        console.log('  2) Re-run `archscope changed .` after new branch edits.');
+        return;
+      }
+
+      if (!options.quiet) {
+        console.error(chalk.blue('Analyzing changed files only:'), includeFiles.length);
+      }
+
+      const pipeline = await runAnalysisPipeline(root, {
+        ...options,
+        includeFiles,
+      }, 'changed');
+      const analysis = pipeline.analysis;
+      const diagram = options.type ? generate(analysis, options.type) : null;
+
+      if (isJson) {
+        const payload = buildMachineEnvelope({
+          schemaVersion: '1.0',
+          command: 'changed',
+          rootPath: root,
+          deterministic: Boolean(options.deterministic),
+          data: {
+            changedFiles: includeFiles,
+            analyzer: pipeline.analyzer,
+            incremental: pipeline.incremental,
+            analysis,
+            diagramType: options.type || null,
+            diagram,
+          },
+          agentSummary: {
+            changedComponents: analysis.components?.length || 0,
+            riskReasons: [],
+            suggestedReviewerChecks: [
+              'Review changed-file coupling for unexpected cross-layer imports.',
+              'Use `archscope workflow pr` for blast-radius scoring before merge.',
+            ],
+          },
+        });
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      const components = analysis.components || [];
+      const languages = analysis.languages || {};
+      console.log(chalk.green('\n📊 Changed-file Analysis'));
+      console.log(`  Changed files: ${includeFiles.length}`);
+      console.log(`  Modeled components: ${components.length}`);
+      console.log(`  Languages: ${Object.entries(languages).map(([key, value]) => `${key}(${value})`).join(', ') || 'none'}`);
+      console.log(chalk.yellow('\nChanged files:'));
+      includeFiles.slice(0, 20).forEach((filePath) => console.log(`  - ${filePath}`));
+      if (includeFiles.length > 20) {
+        console.log(chalk.gray(`  ... and ${includeFiles.length - 20} more`));
+      }
+
+      if (diagram) {
+        console.log(chalk.green(`\n📐 ${options.type} diagram for changed scope:\n`));
+        console.log('```mermaid');
+        console.log(diagram);
+        console.log('```');
+      }
+
+      console.log(chalk.cyan('\nNext steps:'));
+      console.log('  1) Run `archscope workflow pr . --base origin/main --head HEAD` for risk scoring.');
+      console.log('  2) Run `archscope validate .` if changed scope touched architecture boundaries.');
+    });
+}
+
+module.exports = {
+  registerChangedCommand,
+};

package/src/commands/context.js

@@ -0,0 +1,110 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const chalk = require('chalk');
+const { resolveRootPathOrExit } = require('./shared');
+const { buildMachineEnvelope } = require('./output');
+
+/**
+ * Register the `context [path]` CLI subcommand that refreshes AI-focused context pack artifacts under `.diagram/context`.
+ *
+ * The command accepts flags `--force`, `--dry-run`, `--check`, `--quiet`, `--format <type>` (text|json, default `text`) and
+ * `--deterministic`. In `text` mode it streams script output and prints a success or failure message; in `json` mode
+ * it emits a structured machine envelope containing execution results and parsed `.diagram/context/diagram-context.meta.json`.
+ *
+ * The process exits with the executed script's status code on completion. If the refresh script is missing it exits
+ * with code `2`; on other failures it exits with the script's exit code or `1` as a fallback.
+ *
+ * @param {import('commander').Command} program - Commander program instance to register the command on.
+ */
+function registerContextCommand(program) {
+  program
+    .command('context [path]')
+    .description('Refresh AI-focused context pack artifacts under .diagram/context')
+    .option('--force', 'Force refresh even during cooldown', false)
+    .option('--dry-run', 'Preview actions without generating files', false)
+    .option('--check', 'Fail if context artifacts are stale without rewriting files', false)
+    .option('--quiet', 'Suppress script logs', false)
+    .option('--format <type>', 'Output format (text, json)', 'text')
+    .option('--deterministic', 'Use deterministic machine output', false)
+    .action((targetPath, options) => {
+      const root = resolveRootPathOrExit(targetPath);
+      const scriptPath = path.join(root, 'scripts', 'refresh-diagram-context.sh');
+      if (!fs.existsSync(scriptPath)) {
+        console.error(chalk.red('❌ Missing script:'), scriptPath);
+        console.error(chalk.gray('Fix: ensure repository scripts are intact and rerun.'));
+        process.exit(2);
+      }
+
+      const args = [];
+      if (options.force) args.push('--force');
+      if (options.dryRun) args.push('--dry-run');
+      if (options.check) args.push('--check');
+      if (options.quiet) args.push('--quiet');
+
+      const run = spawnSync('bash', [scriptPath, ...args], {
+        cwd: root,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      const stdout = run.stdout || '';
+      const stderr = run.stderr || '';
+      const formatStr = (options.format || 'text').toLowerCase();
+      const metaPath = path.join(root, '.diagram', 'context', 'diagram-context.meta.json');
+      let contextMeta = null;
+      if (fs.existsSync(metaPath)) {
+        try {
+          contextMeta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+        } catch (_error) {
+          // Keep null on parse failures.
+        }
+      }
+
+      if (formatStr === 'json') {
+        const payload = buildMachineEnvelope({
+          schemaVersion: '1.0',
+          command: 'context',
+          rootPath: root,
+          deterministic: Boolean(options.deterministic),
+          status: run.status === 0 ? 'success' : 'failure',
+          data: {
+            exitCode: run.status,
+            stdout,
+            stderr,
+            contextMeta,
+          },
+          errors: run.status === 0 ? [] : [{ message: stderr || `context refresh failed with code ${run.status}` }],
+          agentSummary: {
+            changedComponents: 0,
+            riskReasons: run.status === 0 ? [] : ['context_refresh_failed'],
+            suggestedReviewerChecks: [
+              'Verify `.diagram/context/diagram-context.md` is refreshed in CI artifacts.',
+              'Review omitted types in context metadata when compaction is applied.',
+            ],
+          },
+        });
+        console.log(JSON.stringify(payload, null, 2));
+        process.exit(run.status || 0);
+      }
+
+      if (stdout.trim()) process.stdout.write(stdout);
+      if (stderr.trim()) process.stderr.write(stderr);
+      if (run.status !== 0) {
+        console.error(chalk.red(`❌ Context refresh failed with code ${run.status}`));
+        process.exit(run.status || 1);
+      }
+      if (options.check) {
+        console.log(chalk.green('✅ Context pack is current.'));
+        process.exit(0);
+      }
+      console.log(chalk.green('✅ Context pack refreshed.'));
+      console.log(chalk.cyan('\nNext steps:'));
+      console.log('  1) Attach `.diagram/context/diagram-context.md` to AI review workflows.');
+      console.log('  2) Run `archscope generate-all . --artifact-profile agent` if source graph changed significantly.');
+    });
+}
+
+module.exports = {
+  registerContextCommand,
+};

package/src/commands/diff.js

@@ -0,0 +1,142 @@
+const chalk = require('chalk');
+const { spawnSync } = require('child_process');
+const {
+  analyzeAtRef,
+  computeArchitectureDiff,
+  printArchitectureDiff,
+} = require('../workflow/git-helpers');
+const {
+  applyDiagramRcDefaults,
+  getDiagramRcFromProgram,
+  resolveRootPathOrExit,
+  splitList,
+} = require('./shared');
+const { buildMachineEnvelope } = require('./output');
+
+/**
+ * Register the `diff <base> <head>` CLI command to compare architecture diagrams between two git refs.
+ *
+ * The command validates both git refs, analyses repository snapshots at each ref, computes an architectural diff,
+ * and emits results either as a human-readable text summary or as a JSON machine envelope.
+ *
+ * Behaviour highlights:
+ * - Accepts options for output format (`text` or `json`), verbosity, quiet mode, file patterns/exclusions,
+ *   maximum files to analyse and deterministic machine output.
+ * - Exits with code 2 and prints an error when a git ref is invalid or when analysis fails.
+ * - When `--format json` is used, prints a structured envelope containing `baseRef`, `headRef` and the `diff`.
+ * - When `--format text` is used, prints a textual diff and optional next-step guidance unless `--quiet` is set.
+ *
+ * @param {object} program - The CLI program object (e.g. commander) to which the command will be attached.
+ */
+function registerDiffCommand(program) {
+  program
+    .command('diff <base> <head>')
+    .description('Compare architecture diagrams between two git refs')
+    .option('-f, --format <type>', 'Output format (text, json)', 'text')
+    .option('-q, --quiet', 'Suppress non-essential logging', false)
+    .option('-m, --max-files <n>', 'Max files to analyze per ref')
+    .option('-p, --patterns <list>', 'File patterns to include (comma-separated)')
+    .option('-e, --exclude <list>', 'Paths to exclude (comma-separated)')
+    .option('--deterministic', 'Use deterministic machine output', false)
+    .option('--verbose', 'Show detailed output')
+    .action(async (baseRef, headRef, rawOptions) => {
+      const options = applyDiagramRcDefaults(rawOptions, getDiagramRcFromProgram(program), ['patterns', 'exclude', 'maxFiles']);
+      const root = resolveRootPathOrExit('.');
+      const verbose = options.verbose || false;
+
+      const baseCheck = spawnSync('git', ['rev-parse', '--verify', baseRef], {
+        cwd: root,
+        stdio: ['ignore', 'ignore', 'ignore'],
+        encoding: 'utf-8',
+      });
+      if (baseCheck.status !== 0) {
+        console.error(chalk.red('❌ Invalid base ref:'), baseRef);
+        process.exit(2);
+      }
+
+      const headCheck = spawnSync('git', ['rev-parse', '--verify', headRef], {
+        cwd: root,
+        stdio: ['ignore', 'ignore', 'ignore'],
+        encoding: 'utf-8',
+      });
+      if (headCheck.status !== 0) {
+        console.error(chalk.red('❌ Invalid head ref:'), headRef);
+        process.exit(2);
+      }
+
+      const formatStr = String(options.format || 'text').toLowerCase().trim();
+      const allowedFormats = new Set(['text', 'json']);
+      if (!allowedFormats.has(formatStr)) {
+        console.error(chalk.red('❌ Invalid format:'), options.format);
+        console.error(chalk.gray('Fix: use --format text or --format json.'));
+        process.exit(2);
+      }
+      const isJson = formatStr === 'json';
+      if (!isJson && !options.quiet) {
+        console.error(chalk.blue('\n🔍 Architecture Diff'));
+        console.error(chalk.gray(`   Base: ${baseRef}`));
+        console.error(chalk.gray(`   Head: ${headRef}`));
+        console.error('');
+      }
+
+      const analysisOptions = {
+        maxFiles: parseInt(options.maxFiles, 10) || 100,
+        patterns: Array.isArray(options.patterns) ? options.patterns : splitList(options.patterns),
+        exclude: Array.isArray(options.exclude) ? options.exclude : splitList(options.exclude),
+        deterministic: Boolean(options.deterministic),
+      };
+
+      let baseAnalysis;
+      let headAnalysis;
+      try {
+        baseAnalysis = await analyzeAtRef(baseRef, root, analysisOptions);
+        if (verbose && !isJson) {
+          console.error(chalk.gray(`   Base components: ${baseAnalysis.components.length}`));
+        }
+
+        headAnalysis = await analyzeAtRef(headRef, root, analysisOptions);
+        if (verbose && !isJson) {
+          console.error(chalk.gray(`   Head components: ${headAnalysis.components.length}`));
+        }
+      } catch (error) {
+        console.error(chalk.red('❌ Analysis error:'), error.message);
+        process.exit(2);
+      }
+
+      const diff = computeArchitectureDiff(baseAnalysis, headAnalysis);
+      if (isJson) {
+        const payload = buildMachineEnvelope({
+          schemaVersion: '1.0',
+          command: 'diff',
+          rootPath: root,
+          deterministic: Boolean(options.deterministic),
+          data: {
+            baseRef,
+            headRef,
+            diff,
+          },
+          agentSummary: {
+            changedComponents: Array.isArray(diff?.components?.changed) ? diff.components.changed.length : 0,
+            riskReasons: [],
+            suggestedReviewerChecks: [
+              'Verify added/removed components are expected for this ref comparison.',
+              'Inspect dependency edge changes for accidental coupling.',
+            ],
+          },
+        });
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      printArchitectureDiff(diff, baseRef, headRef);
+      if (!options.quiet) {
+        console.log(chalk.cyan('\nNext steps:'));
+        console.log('  1) Run `archscope workflow pr . --base <base> --head <head>` for risk scoring.');
+        console.log('  2) Use `archscope explain <component> .` to inspect local dependency neighborhoods.');
+      }
+    });
+}
+
+module.exports = {
+  registerDiffCommand,
+};