@brainwav/diagram 1.0.8 → 1.1.0

package/src/commands/doctor.js

@@ -0,0 +1,335 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const { execFileSync } = require('child_process');
+const { getNpxCommandCandidates, getFfmpegCommandCandidates } = require('../utils/commands');
+const { isShallowClone } = require('../workflow/git-helpers');
+const { resolveRootPathOrExit } = require('./shared');
+const { buildMachineEnvelope } = require('./output');
+
+/**
+ * Checks whether the Mermaid CLI can be invoked via npx from the specified project root.
+ *
+ * Attempts platform-specific npx command candidates to run `@mermaid-js/mermaid-cli --version`.
+ * @param {string} root - Filesystem path used as the child process working directory when probing.
+ * @returns {{status: 'pass'|'warn', message: string, fix?: string}} An object describing the probe result.
+ * - `status: 'pass'` when a candidate successfully returns version output; `message` contains the trimmed output or `'mermaid-cli available'`.
+ * - `status: 'warn'` when no candidate succeeded; `message` explains the absence and `fix` suggests `npm install -g @mermaid-js/mermaid-cli`.
+ */
+function checkMermaidCli(root) {
+  const candidates = getNpxCommandCandidates(process.platform);
+  for (const candidate of candidates) {
+    try {
+      const output = execFileSync(candidate, ['-y', '@mermaid-js/mermaid-cli', '--version'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd: root,
+        encoding: 'utf8',
+        timeout: 10000,
+      }).trim();
+      return { status: 'pass', message: output || 'mermaid-cli available' };
+    } catch (_error) {
+      // Try next candidate.
+    }
+  }
+  return {
+    status: 'warn',
+    message: 'Mermaid CLI is not currently available via npx',
+    fix: 'npm install -g @mermaid-js/mermaid-cli',
+  };
+}
+
+/**
+ * Verify that Playwright (and its Chromium runtime) is available for the project at the given root.
+ *
+ * Attempts to resolve a local `playwright` package and perform a headless Chromium launch; if not found, falls back to checking available npx candidates for the Playwright CLI.
+ *
+ * @param {string} root - Filesystem path of the project root used to resolve packages and run probes.
+ * @returns {{status: 'pass'|'warn'|'fail', message: string, fix?: string}} `status` is `'pass'` when a runtime or CLI was detected; `'warn'` when Playwright is present but Chromium is unavailable or no runtime/CLI was detected. `message` summarises the detection result; `fix` provides an installation hint when applicable.
+ */
+function checkPlaywright(root) {
+  const quickLaunchScript = [
+    'const { chromium } = require("playwright");',
+    '(async () => {',
+    '  const browser = await chromium.launch({ headless: true });',
+    '  await browser.close();',
+    '})().catch((error) => {',
+    '  console.error(error.message || String(error));',
+    '  process.exit(1);',
+    '});',
+  ].join('\n');
+  let pkg = null;
+  try {
+    pkg = require.resolve('playwright', { paths: [path.join(root, 'node_modules')] });
+  } catch (_resolveError) {
+    pkg = null;
+  }
+
+  if (pkg) {
+    try {
+      execFileSync('node', ['-e', quickLaunchScript], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd: root,
+        encoding: 'utf8',
+        timeout: 15000,
+      });
+      return { status: 'pass', message: `playwright runtime verified (${pkg})` };
+    } catch (_launchError) {
+      return {
+        status: 'warn',
+        message: 'Playwright package found but Chromium runtime is unavailable',
+        fix: 'npx playwright install chromium',
+      };
+    }
+  }
+
+  const candidates = getNpxCommandCandidates(process.platform);
+  for (const candidate of candidates) {
+    try {
+      const output = execFileSync(candidate, ['playwright', '--version'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd: root,
+        encoding: 'utf8',
+        timeout: 10000,
+      }).trim();
+      return { status: 'pass', message: output || 'playwright CLI available' };
+    } catch (_playwrightError) {
+      // Try next npx candidate.
+    }
+  }
+  return {
+    status: 'warn',
+    message: 'Playwright runtime not detected',
+    fix: 'npx playwright install chromium',
+  };
+}
+
+/**
+ * Checks whether an ffmpeg executable can be invoked from the environment.
+ *
+ * Tries to detect a usable ffmpeg binary and, on success, returns a pass result whose message is the first line of ffmpeg's version output (trimmed). If detection fails, returns a warning with a platform-appropriate installation hint in `fix`.
+ *
+ * @param {string} root - Directory used as the current working directory when probing for ffmpeg.
+ * @returns {{status: 'pass'|'warn', message: string, fix?: string}} `status` is `'pass'` when ffmpeg was detected, otherwise `'warn'`. `message` summarises the detection or the absence; `fix` is provided for the `'warn'` case with an installation hint.
+ */
+function checkFfmpeg(root) {
+  const candidates = getFfmpegCommandCandidates(process.platform);
+  for (const candidate of candidates) {
+    try {
+      const output = execFileSync(candidate, ['-version'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd: root,
+        encoding: 'utf8',
+        timeout: 5000,
+        windowsHide: true,
+      });
+      const firstLine = output.split('\n')[0] || `${candidate} available`;
+      return { status: 'pass', message: firstLine.trim() };
+    } catch (_error) {
+      // Continue.
+    }
+  }
+  let installHint = 'install ffmpeg and ensure it is on PATH';
+  if (process.platform === 'darwin') {
+    installHint = 'brew install ffmpeg';
+  } else if (process.platform === 'linux') {
+    installHint = 'sudo apt install ffmpeg';
+  } else if (process.platform === 'win32') {
+    installHint = 'Install ffmpeg (for example with winget: winget install Gyan.FFmpeg)';
+  }
+  return {
+    status: 'warn',
+    message: 'ffmpeg not detected',
+    fix: installHint,
+  };
+}
+
+/**
+ * Remove the probe directory created by the doctor checks if it did not exist beforehand.
+ *
+ * Attempts to remove `diagramDir` only when `existedBefore` is false; errors during removal are ignored.
+ * @param {string} diagramDir - Filesystem path of the probe directory to remove.
+ * @param {boolean} existedBefore - Whether the directory existed prior to the probe. If `true`, no action is taken.
+ */
+function removeDoctorProbeDirIfCreated(diagramDir, existedBefore) {
+  if (existedBefore) {
+    return;
+  }
+  try {
+    fs.rmdirSync(diagramDir);
+  } catch (_cleanupError) {
+    // Keep directory if not empty or not removable.
+  }
+}
+
+/**
+ * Verifies that the process can create and remove files under the repository diagram directory.
+ *
+ * Attempts to create a probe file inside <root>/.diagram and cleans up any probe artifacts it created.
+ *
+ * @param {string} root - Filesystem path of the repository root to test write access for.
+ * @returns {{status: 'pass'|'fail', message: string, fix?: string}} An object where `status` is `'pass'` when write access is confirmed or `'fail'` when it is not; `message` describes the outcome; `fix` suggests a permission command when applicable.
+ */
+function checkWritePermissions(root) {
+  const diagramDir = path.join(root, '.diagram');
+  const existedBefore = fs.existsSync(diagramDir);
+  try {
+    if (!existedBefore) {
+      fs.mkdirSync(diagramDir, { recursive: true });
+    }
+    const probePath = path.join(diagramDir, '.doctor-write-probe');
+    fs.writeFileSync(probePath, 'ok');
+    fs.rmSync(probePath, { force: true });
+    removeDoctorProbeDirIfCreated(diagramDir, existedBefore);
+    return { status: 'pass', message: `write access confirmed for ${diagramDir}` };
+  } catch (error) {
+    removeDoctorProbeDirIfCreated(diagramDir, existedBefore);
+    return {
+      status: 'fail',
+      message: `write access failed for ${diagramDir}: ${error.message}`,
+      fix: `chmod -R u+rw "${diagramDir}"`,
+    };
+  }
+}
+
+/**
+ * Check that npm's cache directory is configured and is writable.
+ *
+ * Attempts to read the npm cache path from configuration and verify write access by creating and removing a probe file.
+ *
+ * @returns {{status: 'pass'|'warn'|'fail', message: string, fix?: string}}
+ * - `status: 'pass'` when the cache directory is writable; `message` contains the cache path.
+ * - `status: 'warn'` when the cache path is empty or the npm config could not be read; `fix` suggests how to inspect or set the cache.
+ * - `status: 'fail'` when the cache path exists but is not writable; `message` contains the path and error, and `fix` suggests permission commands (platform-specific).
+ */
+function checkNpmCacheHealth() {
+  try {
+    const cachePath = execFileSync('npm', ['config', 'get', 'cache'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+      timeout: 10000,
+    }).trim();
+    if (!cachePath) {
+      return { status: 'warn', message: 'npm cache path is empty', fix: 'npm config set cache ~/.npm' };
+    }
+
+    try {
+      fs.mkdirSync(cachePath, { recursive: true });
+      const probePath = path.join(cachePath, '.doctor-npm-cache-probe');
+      fs.writeFileSync(probePath, 'ok');
+      fs.rmSync(probePath, { force: true });
+      return { status: 'pass', message: `npm cache writable: ${cachePath}` };
+    } catch (error) {
+      let fix = `sudo chown -R "$(id -u):$(id -g)" "${cachePath}"`;
+      if (process.platform === 'win32') {
+        fix = `Run an elevated PowerShell and grant cache access (for example: takeown /F "${cachePath}" /R /D Y && icacls "${cachePath}" /grant "%USERNAME%":(OI)(CI)F /T).`;
+      }
+      return {
+        status: 'fail',
+        message: `npm cache not writable: ${cachePath} (${error.message})`,
+        fix,
+      };
+    }
+  } catch (error) {
+    return {
+      status: 'warn',
+      message: `could not read npm cache config: ${error.message}`,
+      fix: 'npm config get cache',
+    };
+  }
+}
+
+/**
+ * Register the `doctor` CLI command that runs environment diagnostics for a diagram project.
+ *
+ * The command performs a fixed set of checks (Mermaid CLI, Playwright, ffmpeg, Git history depth,
+ * write permissions and npm cache health), summarises results, and prints output in either text
+ * (default) or JSON formats. When invoked the command will call `process.exit` with a non-zero
+ * status if any checks fail or if `--strict` is set and warnings are present.
+ *
+ * @param {import('commander').Command} program - Commander program instance to register the command on.
+ */
+function registerDoctorCommand(program) {
+  program
+    .command('doctor [path]')
+    .description('Run environment diagnostics for architecture evidence workflows')
+    .option('--format <type>', 'Output format (text, json)', 'text')
+    .option('--strict', 'Fail when diagnostics include warnings', false)
+    .option('--deterministic', 'Use deterministic machine output', false)
+    .action((targetPath, options) => {
+      const root = resolveRootPathOrExit(targetPath);
+      const checks = [
+        { id: 'mermaid_cli', label: 'Mermaid CLI', ...checkMermaidCli(root) },
+        { id: 'playwright', label: 'Playwright', ...checkPlaywright(root) },
+        { id: 'ffmpeg', label: 'ffmpeg', ...checkFfmpeg(root) },
+        {
+          id: 'git_shallow_clone',
+          label: 'Git history depth',
+          ...(isShallowClone(root)
+            ? { status: 'warn', message: 'shallow clone detected', fix: 'git fetch --unshallow' }
+            : { status: 'pass', message: 'full git history available' }),
+        },
+        { id: 'write_permissions', label: 'Write permissions', ...checkWritePermissions(root) },
+        { id: 'npm_cache', label: 'npm cache health', ...checkNpmCacheHealth() },
+      ];
+      const strictFailure = Boolean(options.strict) && checks.some((check) => check.status === 'warn');
+      const failedChecks = checks.filter((check) => check.status === 'fail');
+      const exitCode = (failedChecks.length > 0 || strictFailure) ? 1 : 0;
+
+      const summary = {
+        pass: checks.filter((check) => check.status === 'pass').length,
+        warn: checks.filter((check) => check.status === 'warn').length,
+        fail: failedChecks.length,
+      };
+      const formatStr = (options.format || 'text').toLowerCase();
+      if (formatStr === 'json') {
+        const payload = buildMachineEnvelope({
+          schemaVersion: '1.0',
+          command: 'doctor',
+          rootPath: root,
+          deterministic: Boolean(options.deterministic),
+          status: exitCode === 0 ? 'success' : 'failure',
+          data: { checks, summary },
+          errors: [
+            ...failedChecks,
+            ...(strictFailure ? [{ id: 'strict_warn_policy', message: 'Strict mode treats warnings as failures.' }] : []),
+          ],
+          agentSummary: {
+            changedComponents: 0,
+            riskReasons: checks.filter((check) => check.status !== 'pass').map((check) => check.id),
+            suggestedReviewerChecks: [
+              'Resolve all fail-status diagnostics before CI artifact generation.',
+              'Treat warn-status diagnostics as reliability debt if not immediately blocking.',
+            ],
+          },
+        });
+        console.log(JSON.stringify(payload, null, 2));
+        process.exit(exitCode);
+      }
+
+      console.log(chalk.blue('\n🩺 archscope doctor'));
+      for (const check of checks) {
+        const icon = check.status === 'pass' ? '✅' : (check.status === 'warn' ? '⚠️' : '❌');
+        const line = `${icon} ${check.label}: ${check.message}`;
+        if (check.status === 'pass') {
+          console.log(chalk.green(line));
+        } else if (check.status === 'warn') {
+          console.log(chalk.yellow(line));
+        } else {
+          console.log(chalk.red(line));
+        }
+        if (check.fix) {
+          console.log(chalk.gray(`   Fix: ${check.fix}`));
+        }
+      }
+
+      console.log(chalk.cyan('\nNext steps:'));
+      console.log('  1) Resolve any ❌ checks first, then rerun `archscope doctor`.');
+      console.log('  2) Run `archscope generate-all . --artifact-profile agent` once diagnostics are clean.');
+
+      process.exit(exitCode);
+    });
+}
+
+module.exports = {
+  registerDoctorCommand,
+};

package/src/commands/explain.js

@@ -0,0 +1,273 @@
+const chalk = require('chalk');
+const {
+  applyDiagramRcDefaults,
+  getDiagramRcFromProgram,
+  resolveRootPathOrExit,
+  runAnalysisPipeline,
+} = require('./shared');
+const { buildMachineEnvelope } = require('./output');
+
+/**
+ * Produce a sanitized node identifier suitable for Mermaid by replacing any character
+ * that is not a letter, digit or underscore with an underscore; optionally ensure uniqueness.
+ *
+ * @param {any} name - Value to convert into an identifier; will be stringified.
+ * @param {Map<string,number>} [registry] - Optional map that tracks occurrences of generated bases;
+ *   when provided, the first occurrence returns the base, subsequent occurrences return `base_<N>` where
+ *   `N` is the zero-based occurrence index.
+ * @returns {string} The sanitised identifier, uniquified with a `_<N>` suffix when `registry` indicates a duplicate.
+ */
+function sanitizeNodeId(name, registry) {
+  const base = String(name).replace(/[^a-zA-Z0-9_]/g, '_');
+  if (!registry) {
+    return base;
+  }
+  const seen = registry.get(base) || 0;
+  registry.set(base, seen + 1);
+  return seen === 0 ? base : `${base}_${seen}`;
+}
+
+/**
+ * Locate a component whose `name`, `originalName` or `filePath` matches a query, preferring exact matches.
+ * @param {Array<Object>} components - Array of component objects; each should have `name`, `originalName` and `filePath` properties.
+ * @param {string} query - Search term; compared case-insensitively. An empty or missing query returns `null`.
+ * @returns {Object|null} The first component with an exact case-insensitive match on `name`, `originalName` or `filePath`, or if none, the first component where any of those fields contains the query as a substring; `null` if no match.
+ */
+function findComponent(components, query) {
+  const normalizedQuery = String(query || '').toLowerCase().trim();
+  if (!normalizedQuery) {
+    return null;
+  }
+  return components.find((component) =>
+    component.name.toLowerCase() === normalizedQuery
+    || component.originalName.toLowerCase() === normalizedQuery
+    || component.filePath.toLowerCase() === normalizedQuery
+  ) || components.find((component) =>
+    component.name.toLowerCase().includes(normalizedQuery)
+    || component.originalName.toLowerCase().includes(normalizedQuery)
+    || component.filePath.toLowerCase().includes(normalizedQuery)
+  ) || null;
+}
+
+/**
+ * Build the dependency neighbourhood around a target component up to a specified depth.
+ *
+ * @param {Array<Object>} components - All analysed components; each object is expected to include `name` and may include `originalName`, `filePath`, `roleTags`, `type` and `dependencies` (array of component names).
+ * @param {Object} target - The component to centre the neighbourhood on; its `name` is used as the seed and its `dependencies` are treated as outgoing edges.
+ * @param {number} maxDepth - Maximum traversal depth from the target (direct neighbours are at depth 1).
+ * @returns {Object} An object containing:
+ *  - `neighborhood` {Array<Object>} — components included in the neighbourhood set,
+ *  - `incoming` {Array<string>} — sorted names of components whose dependencies include the target,
+ *  - `outgoing` {Array<string>} — sorted names of the target's direct dependencies.
+ */
+function buildNeighborhood(components, target, maxDepth) {
+  const byName = new Map(components.map((component) => [component.name, component]));
+  const selected = new Set([target.name]);
+  const queue = [{ name: target.name, depth: 0 }];
+
+  // Precompute reverse-dependency index
+  const reverseDeps = new Map();
+  for (const component of components) {
+    for (const depName of component.dependencies || []) {
+      if (!reverseDeps.has(depName)) {
+        reverseDeps.set(depName, []);
+      }
+      reverseDeps.get(depName).push(component.name);
+    }
+  }
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current.depth >= maxDepth) continue;
+    const component = byName.get(current.name);
+    if (!component) continue;
+
+    for (const depName of component.dependencies || []) {
+      if (!selected.has(depName)) {
+        selected.add(depName);
+        queue.push({ name: depName, depth: current.depth + 1 });
+      }
+    }
+
+    const dependents = reverseDeps.get(component.name) || [];
+    for (const dependentName of dependents) {
+      if (!selected.has(dependentName)) {
+        selected.add(dependentName);
+        queue.push({ name: dependentName, depth: current.depth + 1 });
+      }
+    }
+  }
+
+  const neighborhood = components.filter((component) => selected.has(component.name));
+  const incoming = components
+    .filter((component) => (component.dependencies || []).includes(target.name))
+    .map((component) => component.name)
+    .sort();
+  const outgoing = [...(target.dependencies || [])].sort();
+  return { neighborhood, incoming, outgoing };
+}
+
+/**
+ * Build a Mermaid graph describing the dependency neighbourhood around a target component.
+ *
+ * Produces a `graph TD` Mermaid string that declares nodes for each component in `neighborhood`,
+ * adds edges for dependencies that exist within the neighbourhood, and applies distinct classes
+ * to highlight the target component versus other neighbours.
+ *
+ * @param {Array<Object>} neighborhood - Array of component objects; each should include `name`, `originalName`, and `dependencies`.
+ * @param {string} targetName - The `name` of the target component to be highlighted.
+ * @returns {string} A Mermaid diagram string representing the neighbourhood graph with styling for the target and neighbour nodes.
+ */
+function buildNeighborhoodDiagram(neighborhood, targetName) {
+  const byName = new Map(neighborhood.map((component) => [component.name, component]));
+  const idRegistry = new Map();
+  const idByName = new Map();
+  const lines = ['graph TD'];
+  const classTarget = [];
+  const classNeighbor = [];
+
+  for (const component of neighborhood) {
+    const id = sanitizeNodeId(component.name, idRegistry);
+    idByName.set(component.name, id);
+    lines.push(`  ${id}["${component.originalName}"]`);
+    if (component.name === targetName) {
+      classTarget.push(id);
+    } else {
+      classNeighbor.push(id);
+    }
+  }
+
+  for (const component of neighborhood) {
+    const from = idByName.get(component.name);
+    for (const depName of component.dependencies || []) {
+      if (!byName.has(depName)) continue;
+      const to = idByName.get(depName);
+      lines.push(`  ${from} --> ${to}`);
+    }
+  }
+
+  if (classTarget.length > 0) {
+    lines.push('  classDef target fill:#1f2937,color:#fff,stroke:#111827,stroke-width:2px;');
+    lines.push(`  class ${classTarget.join(',')} target;`);
+  }
+  if (classNeighbor.length > 0) {
+    lines.push('  classDef neighbor fill:#dbeafe,color:#1e3a8a,stroke:#3b82f6,stroke-width:1px;');
+    lines.push(`  class ${classNeighbor.join(',')} neighbor;`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Register the `explain` CLI command which reports a component's dependency neighbourhood as human-readable text or JSON and includes a Mermaid diagram.
+ *
+ * The command is mounted on the provided `program` and accepts a component query and optional path, plus options such as `--depth`, `--format=json`, `--deterministic` and filtering patterns. When `--format json` is used the command emits a structured machine envelope including target details, sorted neighborhood entries, incoming/outgoing lists and the Mermaid diagram. If the queried component cannot be found the process exits with code `2`.
+ *
+ * @param {import('commander').Command} program - Commander program instance to register the command on.
+ */
+function registerExplainCommand(program) {
+  program
+    .command('explain <component> [path]')
+    .description('Explain a component dependency neighborhood with text + Mermaid')
+    .option('--depth <n>', 'Neighborhood depth', '2')
+    .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('-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 (componentQuery, 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';
+      const depth = Math.max(1, parseInt(options.depth, 10) || 2);
+
+      const pipeline = await runAnalysisPipeline(root, options, 'explain');
+      const components = pipeline.analysis.components || [];
+      const target = findComponent(components, componentQuery);
+      if (!target) {
+        console.error(chalk.red(`❌ Component "${componentQuery}" not found.`));
+        console.error(chalk.gray('Fix: run `diagram analyze .` and choose a component name from the output list.'));
+        process.exit(2);
+      }
+
+      const { neighborhood, incoming, outgoing } = buildNeighborhood(components, target, depth);
+      const mermaid = buildNeighborhoodDiagram(neighborhood, target.name);
+
+      if (isJson) {
+        const payload = buildMachineEnvelope({
+          schemaVersion: '1.0',
+          command: 'explain',
+          rootPath: root,
+          deterministic: Boolean(options.deterministic),
+          data: {
+            target: {
+              name: target.name,
+              originalName: target.originalName,
+              filePath: target.filePath,
+              roleTags: target.roleTags || [],
+              type: target.type,
+            },
+            incoming,
+            outgoing,
+            neighborhood: neighborhood
+              .map((component) => ({
+                name: component.name,
+                originalName: component.originalName,
+                filePath: component.filePath,
+                roleTags: component.roleTags || [],
+                type: component.type,
+              }))
+              .sort((a, b) => a.filePath.localeCompare(b.filePath)),
+            mermaid,
+          },
+          agentSummary: {
+            changedComponents: neighborhood.length,
+            riskReasons: [],
+            suggestedReviewerChecks: [
+              'Inspect incoming dependencies for unintended coupling.',
+              'Confirm outgoing dependencies reflect intended layer direction.',
+            ],
+          },
+        });
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      if (!options.quiet) {
+        console.log(chalk.green('\n🔎 Component Explanation'));
+        console.log(`  Target: ${target.originalName} (${target.filePath})`);
+        console.log(`  Depth: ${depth}`);
+        console.log(`  Incoming: ${incoming.length}`);
+        console.log(`  Outgoing: ${outgoing.length}`);
+        console.log(`  Neighborhood size: ${neighborhood.length}`);
+
+        console.log(chalk.yellow('\nIncoming dependencies:'));
+        if (incoming.length === 0) {
+          console.log('  - none');
+        } else {
+          incoming.forEach((item) => console.log(`  - ${item}`));
+        }
+
+        console.log(chalk.yellow('\nOutgoing dependencies:'));
+        if (outgoing.length === 0) {
+          console.log('  - none');
+        } else {
+          outgoing.forEach((item) => console.log(`  - ${item}`));
+        }
+
+        console.log(chalk.green('\n📐 Mermaid neighborhood:\n'));
+        console.log('```mermaid');
+        console.log(mermaid);
+        console.log('```');
+        console.log(chalk.cyan('\nNext steps:'));
+        console.log('  1) Run `archscope validate .` if this component crosses protected boundaries.');
+        console.log('  2) Run `archscope workflow pr` to estimate blast-radius risk for current changes.');
+      }
+    });
+}
+
+module.exports = {
+  registerExplainCommand,
+};