@brainwav/diagram 1.0.7 → 1.1.0

package/src/commands/generate-all.js

@@ -0,0 +1,170 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const {
+  SUPPORTED_DIAGRAM_TYPES,
+  generateDiagramArtifact,
+  toManifestEntry,
+} = require('../core/analysis-generation');
+const {
+  resolveArtifactProfile,
+  applyArtifactBudget,
+} = require('../artifacts/artifact-budget');
+const {
+  createGenerateAllManifest,
+  writeJsonFile,
+} = require('../artifacts/evidence-manifest');
+const {
+  applyDiagramRcDefaults,
+  getDiagramRcFromProgram,
+  maybeWriteArchitectureIR,
+  resolveRootPathOrExit,
+  runAnalysisPipeline,
+  validateOutputPath,
+} = require('./shared');
+const { buildMachineEnvelope } = require('./output');
+
+/**
+ * Register the `generate-all [path]` CLI command which generates Mermaid diagram files for all supported diagram types and writes a manifest describing outputs and compaction decisions.
+ *
+ * The command analyses the target path, applies RC defaults, validates and resolves output and artifact profile, runs the analysis pipeline, optionally emits a typed architecture IR, generates diagrams for every supported type, applies an artifact budget to decide which diagrams to include/truncate/omit, writes `.mmd` files and a `manifest.json`, and emits either a machine-readable JSON envelope or human-friendly text output depending on the `--format` option.
+ *
+ * @param {import('commander').Command} program - Commander program instance to register the command on.
+ */
+function registerGenerateAllCommand(program) {
+  program
+    .command('generate-all [path]')
+    .description('Generate all diagram types')
+    .option('-O, --output-dir <dir>', 'Output directory', '.diagram')
+    .option('--artifact-profile <profile>', 'Artifact output profile (full, agent, ultra-compact)', 'full')
+    .option('-q, --quiet', 'Suppress non-essential logging', false)
+    .option('-p, --patterns <list>', 'File patterns')
+    .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)
+    .action(async (targetPath, rawOptions) => {
+      const options = applyDiagramRcDefaults(rawOptions, getDiagramRcFromProgram(program), ['patterns', 'exclude', 'maxFiles']);
+      const root = resolveRootPathOrExit(targetPath);
+      let outDir;
+      let artifactProfile;
+      try {
+        outDir = validateOutputPath(options.outputDir, root);
+        artifactProfile = resolveArtifactProfile(options.artifactProfile);
+      } catch (error) {
+        console.error(chalk.red('❌ Configuration error:'), error.message);
+        process.exit(2);
+      }
+
+      if (!options.quiet) {
+        console.error(chalk.blue('Analyzing'), root);
+      }
+      const pipeline = await runAnalysisPipeline(root, options, 'generate-all');
+      const data = pipeline.analysis;
+      const irPath = options.emitIr
+        ? maybeWriteArchitectureIR(root, data, pipeline.analyzer, true)
+        : null;
+
+      if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
+
+      const types = [...SUPPORTED_DIAGRAM_TYPES];
+      const generatedDiagrams = types.map((type) => {
+        const artifact = generateDiagramArtifact(data, type);
+        return {
+          type,
+          mermaid: artifact.mermaid,
+          metadata: artifact.metadata,
+        };
+      });
+      const budgeted = applyArtifactBudget(generatedDiagrams, artifactProfile);
+
+      const staleMermaidFiles = fs
+        .readdirSync(outDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.mmd'))
+        .map((entry) => path.join(outDir, entry.name));
+      for (const staleFile of staleMermaidFiles) {
+        fs.rmSync(staleFile, { force: true });
+      }
+
+      const manifest = createGenerateAllManifest({
+        root,
+        outDir,
+        artifactProfile,
+        budgeted,
+        deterministic: Boolean(options.deterministic),
+      });
+
+      for (const entry of budgeted.included) {
+        const file = path.join(outDir, `${entry.type}.mmd`);
+        fs.writeFileSync(file, entry.mermaid);
+        const manifestEntry = toManifestEntry(entry.type, file, entry.mermaid, root, entry.metadata);
+        if (entry.truncated) {
+          manifestEntry.compacted = true;
+          manifestEntry.sourceBytes = entry.originalBytes;
+          manifestEntry.bytesSaved = entry.bytesSaved;
+        }
+        manifest.diagrams.push(manifestEntry);
+        if (!options.quiet) {
+          const truncationSuffix = entry.truncated ? chalk.yellow(' [truncated]') : '';
+          console.error(chalk.green('✅'), entry.type, '→', file, truncationSuffix);
+        }
+      }
+
+      manifest.diagrams = manifest.diagrams.sort((a, b) => a.type.localeCompare(b.type));
+      const manifestPath = path.join(outDir, 'manifest.json');
+      writeJsonFile(manifestPath, manifest);
+
+      const formatStr = (options.format || 'text').toLowerCase();
+      if (formatStr === 'json') {
+        const payload = buildMachineEnvelope({
+          schemaVersion: '1.0',
+          command: 'generate-all',
+          rootPath: root,
+          deterministic: Boolean(options.deterministic),
+          data: {
+            manifest,
+            artifacts: {
+              manifestPath,
+              architectureIrPath: irPath,
+            },
+            analyzer: pipeline.analyzer,
+            incremental: pipeline.incremental,
+          },
+          agentSummary: {
+            changedComponents: data.components?.length || 0,
+            riskReasons: manifest.compaction.omittedTypes.length > 0 ? ['artifact_budget_omitted_types'] : [],
+            suggestedReviewerChecks: [
+              'Review omitted diagram types when using compact profiles.',
+              'Attach `.diagram/manifest.json` to CI artifacts for agent consumers.',
+            ],
+          },
+        });
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      if (!options.quiet) {
+        if (manifest.compaction.omittedTypes.length > 0) {
+          console.error(
+            chalk.yellow('⚠️  omitted diagrams:'),
+            manifest.compaction.omittedTypes.join(', ')
+          );
+        }
+        console.error(chalk.green('✅ manifest'), '→', manifestPath);
+        if (irPath) {
+          console.error(chalk.gray('IR artifact:'), irPath);
+        }
+        console.error(chalk.cyan('\n🔗 Preview all at: https://mermaid.live'));
+        console.log(chalk.cyan('\nNext steps:'));
+        console.log('  1) Run `archscope context .` to refresh compact AI context pack files.');
+        console.log('  2) Upload `.diagram` artifacts in CI for PR analysis workflows.');
+      }
+    });
+}
+
+module.exports = {
+  registerGenerateAllCommand,
+};

package/src/commands/generate-animated.js

@@ -0,0 +1,50 @@
+const chalk = require('chalk');
+const {
+  buildMermaidForMedia,
+  getVideoModule,
+  resolveMediaCommandContext,
+} = require('./video-shared');
+
+/**
+ * Register the `generate-animated` CLI command on the provided program.
+ *
+ * The command generates an animated SVG from media files under a target path, accepting options
+ * for diagram type, output file, theme, include/exclude patterns and analysis limits; it resolves
+ * the command context, builds Mermaid content and writes the animated SVG.
+ */
+function registerGenerateAnimatedCommand(program) {
+  program
+    .command('generate-animated [path]')
+    .description('Generate animated SVG with CSS animations')
+    .option('-t, --type <type>', 'Diagram type', 'architecture')
+    .option('-o, --output <file>', 'Output file', 'diagram-animated.svg')
+    .option('--force', 'Overwrite output file if it exists', false)
+    .option('-q, --quiet', 'Suppress non-essential logging', false)
+    .option('--theme <theme>', 'Theme: default, dark, forest, neutral, light')
+    .option('-m, --max-files <n>', 'Max files to analyze')
+    .option('-p, --patterns <list>', 'File patterns (comma-separated)')
+    .option('-e, --exclude <list>', 'Exclude patterns')
+    .option('--format <type>', 'Output format (ignored for animated)', 'text')
+    .action(async (targetPath, rawOptions) => {
+      const { options, root, safeTheme, safeOutput } = resolveMediaCommandContext(
+        program,
+        targetPath,
+        rawOptions
+      );
+
+      if (!options.quiet) console.error(chalk.blue('✨ Generating animated SVG for'), root);
+      const mermaid = await buildMermaidForMedia(root, options);
+      const { generateAnimatedSVG } = getVideoModule('Animated output requires Playwright.');
+      await generateAnimatedSVG(mermaid, safeOutput, { theme: safeTheme });
+
+      if (!options.quiet) {
+        console.log(chalk.cyan('\nNext steps:'));
+        console.log('  1) Run `archscope generate-video` when you need MP4/WebM output.');
+        console.log('  2) Use `archscope doctor .` if Mermaid or Playwright toolchain checks fail.');
+      }
+    });
+}
+
+module.exports = {
+  registerGenerateAnimatedCommand,
+};

package/src/commands/generate-video.js

@@ -0,0 +1,65 @@
+const chalk = require('chalk');
+const {
+  buildMermaidForMedia,
+  getVideoModule,
+  resolveMediaCommandContext,
+} = require('./video-shared');
+
+/**
+ * Register the CLI subcommand `generate-video [path]` for producing an animated video from a diagram.
+ *
+ * The command accepts options for diagram type, output file, overwrite, verbosity, duration, FPS,
+ * dimensions, theme and analysis file patterns. When executed it resolves and validates the command
+ * context, builds a Mermaid representation of the diagram, loads the video generator (requires
+ * Playwright) and writes the resulting video to the specified output path using parsed numeric
+ * options for duration, fps, width and height.
+ *
+ * @param {import('commander').Command} program - Commander program instance to register the subcommand on.
+ */
+function registerGenerateVideoCommand(program) {
+  program
+    .command('generate-video [path]')
+    .description('Generate an animated video of the diagram')
+    .option('-t, --type <type>', 'Diagram type', 'architecture')
+    .option('-o, --output <file>', 'Output file (.mp4, .webm, .mov)', 'diagram.mp4')
+    .option('--force', 'Overwrite output file if it exists', false)
+    .option('-q, --quiet', 'Suppress non-essential logging', false)
+    .option('-d, --duration <sec>', 'Video duration in seconds', '5')
+    .option('-f, --fps <n>', 'Frames per second', '30')
+    .option('--width <n>', 'Video width', '1280')
+    .option('--height <n>', 'Video height', '720')
+    .option('--theme <theme>', 'Theme: default, dark, forest, neutral, light')
+    .option('-m, --max-files <n>', 'Max files to analyze')
+    .option('-p, --patterns <list>', 'File patterns (comma-separated)')
+    .option('-e, --exclude <list>', 'Exclude patterns')
+    .option('--format <type>', 'Output format (ignored for video)', 'text')
+    .action(async (targetPath, rawOptions) => {
+      const { options, root, safeTheme, safeOutput } = resolveMediaCommandContext(
+        program,
+        targetPath,
+        rawOptions
+      );
+
+      if (!options.quiet) console.error(chalk.blue('🎬 Generating video for'), root);
+      const mermaid = await buildMermaidForMedia(root, options);
+      const { generateVideo } = getVideoModule('Video generation requires Playwright.');
+
+      await generateVideo(mermaid, safeOutput, {
+        duration: parseInt(options.duration, 10) || 5,
+        fps: parseInt(options.fps, 10) || 30,
+        width: parseInt(options.width, 10) || 1280,
+        height: parseInt(options.height, 10) || 720,
+        theme: safeTheme,
+      });
+
+      if (!options.quiet) {
+        console.log(chalk.cyan('\nNext steps:'));
+        console.log('  1) Run `archscope doctor .` if rendering quality/tooling is unstable in CI.');
+        console.log('  2) Commit generated media only when required by your release workflow.');
+      }
+    });
+}
+
+module.exports = {
+  registerGenerateVideoCommand,
+};