@dependency-maritime/cli 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -127,3 +127,16 @@ This project uses **npm** for package management. Please ensure you lock files a
 ## 📝 License
 
 Distributed under the MIT License.
+
+### Render existing graph evidence
+
+With Graphviz `dot` installed, render without performing a second analysis:
+
+```bash
+maritime graph --input .maritime --output docs/images/dependency-graph.svg
+```
+
+`.maritime/dependency-graph.json` is canonical evidence; SVG and DOT outputs are derived
+presentations. The composite Action's reproducible committed-SVG contract is limited to its pinned
+Ubuntu Graphviz path; other runners must provide and pin `dot` themselves because layout can vary
+between Graphviz versions.

package/dist/cli/cli/commands/graph.d.ts

@@ -0,0 +1 @@
+export declare function runGraphCommand(args: string[]): Promise<number>;

package/dist/cli/cli/graph/render-dot.d.ts

@@ -0,0 +1,6 @@
+import type { MaritimeCruiseResult } from '../../schema/dependency-cruiser';
+declare function externalPackageName(value: string): string | undefined;
+/** Pure, deterministic conversion of a validated dependency-cruiser result to Graphviz DOT. */
+export declare function renderDependencyGraphToDot(graph: MaritimeCruiseResult): string;
+export declare function inferGraphvizFormat(outputPath: string): 'svg' | 'dot';
+export { externalPackageName };

package/dist/cli/cli/graph/render-graphviz.d.ts

@@ -0,0 +1,4 @@
+export declare function normalizeGraphvizSvg(svg: string): string;
+export declare function renderDotWithGraphviz(dot: string, outputPath: string, options?: {
+    executable?: string;
+}): Promise<void>;

package/dist/cli/cli/index.d.ts

@@ -1,7 +1,10 @@
 import { runAnalyzeCommand } from './commands/analyze';
 import { runValidateCommand } from './commands/validate';
+import { runGraphCommand } from './commands/graph';
 import { validateArtifacts } from './validate/validate';
-export { runAnalyzeCommand, runValidateCommand, validateArtifacts };
+export { runAnalyzeCommand, runValidateCommand, runGraphCommand, validateArtifacts };
+export { renderDependencyGraphToDot, inferGraphvizFormat } from './graph/render-dot';
+export { renderDotWithGraphviz, normalizeGraphvizSvg } from './graph/render-graphviz';
 export * from '../schema/manifest';
 export { readDependencyGraph, resolveDepcruiseConfig, generateDependencyGraph, runEslintComplexityScan, countLinesOfCode, writeOutputFiles } from './analyze/adapters';
 export { calculateMetrics, isSupportedTypeScriptFile, calculateInstability, calculateScore, calculateHealthScore } from './analyze/calculate-metrics';

package/dist/cli/index.d.ts

@@ -1,7 +1,10 @@
 import { runAnalyzeCommand } from './commands/analyze';
 import { runValidateCommand } from './commands/validate';
+import { runGraphCommand } from './commands/graph';
 import { validateArtifacts } from './validate/validate';
-export { runAnalyzeCommand, runValidateCommand, validateArtifacts };
+export { runAnalyzeCommand, runValidateCommand, runGraphCommand, validateArtifacts };
+export { renderDependencyGraphToDot, inferGraphvizFormat } from './graph/render-dot';
+export { renderDotWithGraphviz, normalizeGraphvizSvg } from './graph/render-graphviz';
 export * from '../schema/manifest';
 export { readDependencyGraph, resolveDepcruiseConfig, generateDependencyGraph, runEslintComplexityScan, countLinesOfCode, writeOutputFiles } from './analyze/adapters';
 export { calculateMetrics, isSupportedTypeScriptFile, calculateInstability, calculateScore, calculateHealthScore } from './analyze/calculate-metrics';

package/dist/cli/index.js

@@ -960,8 +960,8 @@ async function validateArtifacts(options = {}) {
   const artifactDirRelative = options.artifactDir ?? ".maritime";
   const artifactDir = path5.resolve(workingDir, artifactDirRelative);
   try {
-    const stat2 = await fsPromises2.stat(artifactDir);
-    if (!stat2.isDirectory()) {
+    const stat3 = await fsPromises2.stat(artifactDir);
+    if (!stat3.isDirectory()) {
       throw new ValidationError(`Artifact path is not a directory: ${artifactDirRelative}`);
     }
   } catch (err) {
@@ -1125,6 +1125,215 @@ Exit Codes:
   }
 }
 
+// src/cli/commands/graph.ts
+import { parseArgs as parseArgs3 } from "node:util";
+import * as fs4 from "node:fs/promises";
+import * as path9 from "node:path";
+
+// src/cli/graph/render-dot.ts
+import * as path7 from "node:path";
+var dotQuote = (value) => JSON.stringify(value);
+var normalizedPath = (value) => value.replaceAll("\\", "/").replace(/^\.\//, "");
+function externalPackageName(value) {
+  const normalized = normalizedPath(value);
+  const marker = "node_modules/";
+  const markerIndex = normalized.lastIndexOf(marker);
+  const packagePath = markerIndex >= 0 ? normalized.slice(markerIndex + marker.length) : normalized;
+  const parts = packagePath.split("/").filter(Boolean);
+  if (markerIndex < 0 && (packagePath.startsWith(".") || packagePath.startsWith("/") || parts.length === 0)) {
+    return void 0;
+  }
+  return parts[0]?.startsWith("@") && parts[1] ? `${parts[0]}/${parts[1]}` : parts[0];
+}
+function isExternalPath(value) {
+  return normalizedPath(value).split("/").includes("node_modules");
+}
+function addLocalModule(root, source) {
+  const parts = normalizedPath(source).split("/").filter((part) => part && part !== ".");
+  const name = parts.pop();
+  if (!name) return;
+  let directory = root;
+  for (const part of parts) {
+    let child = directory.directories.get(part);
+    if (!child) {
+      child = { directories: /* @__PURE__ */ new Map(), files: [] };
+      directory.directories.set(part, child);
+    }
+    directory = child;
+  }
+  directory.files.push({ source: normalizedPath(source), name });
+}
+function renderDirectory(directory, segments, indent) {
+  const lines = [];
+  for (const [name, child] of [...directory.directories].sort(([a], [b]) => a.localeCompare(b))) {
+    const childSegments = [...segments, name];
+    lines.push(`${indent}subgraph ${dotQuote(`cluster:${childSegments.join("/")}`)} {`);
+    lines.push(`${indent}  label=${dotQuote(name)};`);
+    lines.push(`${indent}  color="#94a3b8";`);
+    lines.push(...renderDirectory(child, childSegments, `${indent}  `));
+    lines.push(`${indent}}`);
+  }
+  for (const file of [...directory.files].sort((a, b) => a.name.localeCompare(b.name) || a.source.localeCompare(b.source))) {
+    lines.push(`${indent}${dotQuote(`local:${file.source}`)} [label=${dotQuote(file.name)}, shape="box"];`);
+  }
+  return lines;
+}
+function edgeAttributes(dependency) {
+  const attributes = [];
+  const dependencyTypes = [...dependency.dependencyTypes].sort();
+  if (dependencyTypes.length > 0) attributes.push(`label=${dotQuote(dependencyTypes.join(", "))}`);
+  if (dependency.typeOnly || dependency.preCompilationOnly) attributes.push('style="dashed"');
+  if (dependency.circular) attributes.push('color="#d97706"', 'penwidth="2"');
+  if (!dependency.valid) {
+    if (dependency.circular) attributes.push('xlabel="invalid"', 'fontcolor="#dc2626"');
+    else attributes.push('color="#dc2626"', 'penwidth="2"');
+  }
+  return attributes.length > 0 ? ` [${attributes.join(", ")}]` : "";
+}
+function renderDependencyGraphToDot(graph) {
+  const root = { directories: /* @__PURE__ */ new Map(), files: [] };
+  const localSources = /* @__PURE__ */ new Set();
+  const externalPackages = /* @__PURE__ */ new Set();
+  for (const module of graph.modules) {
+    const source = normalizedPath(module.source);
+    if (isExternalPath(source) || module.coreModule) continue;
+    localSources.add(source);
+    addLocalModule(root, source);
+  }
+  const edges = [];
+  for (const module of [...graph.modules].sort((a, b) => a.source.localeCompare(b.source))) {
+    const source = normalizedPath(module.source);
+    if (!localSources.has(source)) continue;
+    for (const dependency of module.dependencies) {
+      const resolved = normalizedPath(dependency.resolved);
+      let target;
+      if (localSources.has(resolved)) {
+        target = `local:${resolved}`;
+      } else if (!dependency.coreModule) {
+        const looksExternal = isExternalPath(resolved) || dependency.dependencyTypes.includes("npm");
+        const packageName = looksExternal ? externalPackageName(isExternalPath(resolved) ? resolved : dependency.module) : void 0;
+        if (packageName) {
+          externalPackages.add(packageName);
+          target = `external:${packageName}`;
+        }
+      }
+      if (target) edges.push({ from: `local:${source}`, to: target, dependency });
+    }
+  }
+  edges.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || JSON.stringify(a.dependency).localeCompare(JSON.stringify(b.dependency)));
+  const lines = [
+    'digraph "dependency-graph" {',
+    '  graph [compound="true", rankdir="LR", fontname="Helvetica"];',
+    '  node [fontname="Helvetica", fontsize="10"];',
+    '  edge [fontname="Helvetica", fontsize="8"];',
+    ...renderDirectory(root, [], "  ")
+  ];
+  if (externalPackages.size > 0) {
+    lines.push('  subgraph "cluster:external-packages" {', '    label="External packages";', '    style="dashed";', '    color="#64748b";');
+    for (const packageName of [...externalPackages].sort()) {
+      lines.push(`    ${dotQuote(`external:${packageName}`)} [label=${dotQuote(packageName)}, shape="component", style="filled", fillcolor="#e2e8f0"];`);
+    }
+    lines.push("  }");
+  }
+  for (const edge of edges) {
+    lines.push(`  ${dotQuote(edge.from)} -> ${dotQuote(edge.to)}${edgeAttributes(edge.dependency)};`);
+  }
+  lines.push("}", "");
+  return lines.join("\n");
+}
+function inferGraphvizFormat(outputPath) {
+  const extension = path7.extname(outputPath).toLowerCase();
+  if (extension === ".svg") return "svg";
+  if (extension === ".dot") return "dot";
+  throw new Error(`Unsupported graph output format "${extension || "(none)"}". Use an .svg or .dot output path.`);
+}
+
+// src/cli/graph/render-graphviz.ts
+import { spawn } from "node:child_process";
+import * as fs3 from "node:fs/promises";
+import * as path8 from "node:path";
+function normalizeGraphvizSvg(svg) {
+  return svg.replace(/<!-- Generated by graphviz version .*? -->/gi, "<!-- Generated by Graphviz -->");
+}
+async function renderDotWithGraphviz(dot, outputPath, options = {}) {
+  const executable = options.executable ?? "dot";
+  const svg = await new Promise((resolve7, reject) => {
+    const child = spawn(executable, ["-Tsvg"], { stdio: ["pipe", "pipe", "pipe"] });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.on("error", (error) => {
+      if (error.code === "ENOENT") {
+        reject(new Error(`Graphviz executable "${executable}" was not found. Install Graphviz and ensure "dot" is available on PATH.`));
+      } else {
+        reject(new Error(`Unable to start Graphviz: ${error.message}`));
+      }
+    });
+    child.on("close", (code) => {
+      if (code === 0) resolve7(Buffer.concat(stdout).toString("utf8"));
+      else reject(new Error(`Graphviz exited with code ${code}: ${Buffer.concat(stderr).toString("utf8").trim()}`));
+    });
+    child.stdin.end(dot);
+  });
+  await fs3.mkdir(path8.dirname(outputPath), { recursive: true });
+  await fs3.writeFile(outputPath, normalizeGraphvizSvg(svg));
+}
+
+// src/cli/commands/graph.ts
+async function runGraphCommand(args) {
+  let values;
+  try {
+    values = parseArgs3({ args, options: {
+      input: { type: "string", short: "i" },
+      output: { type: "string", short: "o" },
+      cwd: { type: "string" },
+      help: { type: "boolean", short: "h" }
+    } }).values;
+  } catch (error) {
+    console.error(`Error parsing arguments: ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+  if (values.help) {
+    console.log(`
+Usage: maritime graph --input <artifact-directory-or-graph.json> --output <graph.svg|graph.dot>
+
+Renders existing canonical graph evidence without running dependency analysis.
+
+Options:
+  -i, --input <path>   .maritime directory or dependency-graph.json (default: .maritime)
+  -o, --output <path>  SVG or DOT output path (required)
+  --cwd <dir>          Working directory root for resolution
+  -h, --help           Show help message
+`);
+    return 0;
+  }
+  if (!values.output) {
+    console.error("Error: --output is required.");
+    return 2;
+  }
+  const cwd = path9.resolve(values.cwd ?? process.cwd());
+  const input = path9.resolve(cwd, values.input ?? ".maritime");
+  const output = path9.resolve(cwd, values.output);
+  try {
+    const stat3 = await fs4.stat(input);
+    const graphPath = stat3.isDirectory() ? path9.resolve(input, (await validateArtifacts({ artifactDir: input, cwd })).manifest.artifacts.graph) : input;
+    const parsed = JSON.parse(await fs4.readFile(graphPath, "utf8"));
+    const result = CruiseResultSchema.safeParse(parsed);
+    if (!result.success) throw new Error(`Invalid Maritime dependency graph: ${result.error.message}`);
+    const dot = renderDependencyGraphToDot(result.data);
+    const format = inferGraphvizFormat(output);
+    await fs4.mkdir(path9.dirname(output), { recursive: true });
+    if (format === "dot") await fs4.writeFile(output, dot);
+    else await renderDotWithGraphviz(dot, output);
+    console.log(`\u2705 Dependency graph rendered from ${graphPath} to ${output}`);
+    return 0;
+  } catch (error) {
+    console.error(`Error rendering dependency graph: ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+}
+
 // src/cli/index.ts
 async function analyzeProject(options) {
   const args = [];
@@ -1181,13 +1390,18 @@ export {
   countLinesOfCode,
   detectEslintConfig,
   generateDependencyGraph,
+  inferGraphvizFormat,
   isSupportedTypeScriptFile,
+  normalizeGraphvizSvg,
   parseEslintComplexityReport,
   readDependencyGraph,
+  renderDependencyGraphToDot,
+  renderDotWithGraphviz,
   renderMarkdownReport,
   resolveDepcruiseConfig,
   runAnalyzeCommand,
   runEslintComplexityScan,
+  runGraphCommand,
   runValidateCommand,
   validateArtifacts,
   validateEslintEnvironment,

package/dist/cli/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/main.ts
-import { parseArgs as parseArgs3 } from "node:util";
+import { parseArgs as parseArgs4 } from "node:util";
 
 // src/cli/commands/analyze.ts
 import { parseArgs } from "node:util";
@@ -965,8 +965,8 @@ async function validateArtifacts(options = {}) {
   const artifactDirRelative = options.artifactDir ?? ".maritime";
   const artifactDir = path5.resolve(workingDir, artifactDirRelative);
   try {
-    const stat2 = await fsPromises2.stat(artifactDir);
-    if (!stat2.isDirectory()) {
+    const stat3 = await fsPromises2.stat(artifactDir);
+    if (!stat3.isDirectory()) {
       throw new ValidationError(`Artifact path is not a directory: ${artifactDirRelative}`);
     }
   } catch (err) {
@@ -1130,11 +1130,220 @@ Exit Codes:
   }
 }
 
+// src/cli/commands/graph.ts
+import { parseArgs as parseArgs3 } from "node:util";
+import * as fs4 from "node:fs/promises";
+import * as path9 from "node:path";
+
+// src/cli/graph/render-dot.ts
+import * as path7 from "node:path";
+var dotQuote = (value) => JSON.stringify(value);
+var normalizedPath = (value) => value.replaceAll("\\", "/").replace(/^\.\//, "");
+function externalPackageName(value) {
+  const normalized = normalizedPath(value);
+  const marker = "node_modules/";
+  const markerIndex = normalized.lastIndexOf(marker);
+  const packagePath = markerIndex >= 0 ? normalized.slice(markerIndex + marker.length) : normalized;
+  const parts = packagePath.split("/").filter(Boolean);
+  if (markerIndex < 0 && (packagePath.startsWith(".") || packagePath.startsWith("/") || parts.length === 0)) {
+    return void 0;
+  }
+  return parts[0]?.startsWith("@") && parts[1] ? `${parts[0]}/${parts[1]}` : parts[0];
+}
+function isExternalPath(value) {
+  return normalizedPath(value).split("/").includes("node_modules");
+}
+function addLocalModule(root, source) {
+  const parts = normalizedPath(source).split("/").filter((part) => part && part !== ".");
+  const name = parts.pop();
+  if (!name) return;
+  let directory = root;
+  for (const part of parts) {
+    let child = directory.directories.get(part);
+    if (!child) {
+      child = { directories: /* @__PURE__ */ new Map(), files: [] };
+      directory.directories.set(part, child);
+    }
+    directory = child;
+  }
+  directory.files.push({ source: normalizedPath(source), name });
+}
+function renderDirectory(directory, segments, indent) {
+  const lines = [];
+  for (const [name, child] of [...directory.directories].sort(([a], [b]) => a.localeCompare(b))) {
+    const childSegments = [...segments, name];
+    lines.push(`${indent}subgraph ${dotQuote(`cluster:${childSegments.join("/")}`)} {`);
+    lines.push(`${indent}  label=${dotQuote(name)};`);
+    lines.push(`${indent}  color="#94a3b8";`);
+    lines.push(...renderDirectory(child, childSegments, `${indent}  `));
+    lines.push(`${indent}}`);
+  }
+  for (const file of [...directory.files].sort((a, b) => a.name.localeCompare(b.name) || a.source.localeCompare(b.source))) {
+    lines.push(`${indent}${dotQuote(`local:${file.source}`)} [label=${dotQuote(file.name)}, shape="box"];`);
+  }
+  return lines;
+}
+function edgeAttributes(dependency) {
+  const attributes = [];
+  const dependencyTypes = [...dependency.dependencyTypes].sort();
+  if (dependencyTypes.length > 0) attributes.push(`label=${dotQuote(dependencyTypes.join(", "))}`);
+  if (dependency.typeOnly || dependency.preCompilationOnly) attributes.push('style="dashed"');
+  if (dependency.circular) attributes.push('color="#d97706"', 'penwidth="2"');
+  if (!dependency.valid) {
+    if (dependency.circular) attributes.push('xlabel="invalid"', 'fontcolor="#dc2626"');
+    else attributes.push('color="#dc2626"', 'penwidth="2"');
+  }
+  return attributes.length > 0 ? ` [${attributes.join(", ")}]` : "";
+}
+function renderDependencyGraphToDot(graph) {
+  const root = { directories: /* @__PURE__ */ new Map(), files: [] };
+  const localSources = /* @__PURE__ */ new Set();
+  const externalPackages = /* @__PURE__ */ new Set();
+  for (const module of graph.modules) {
+    const source = normalizedPath(module.source);
+    if (isExternalPath(source) || module.coreModule) continue;
+    localSources.add(source);
+    addLocalModule(root, source);
+  }
+  const edges = [];
+  for (const module of [...graph.modules].sort((a, b) => a.source.localeCompare(b.source))) {
+    const source = normalizedPath(module.source);
+    if (!localSources.has(source)) continue;
+    for (const dependency of module.dependencies) {
+      const resolved = normalizedPath(dependency.resolved);
+      let target;
+      if (localSources.has(resolved)) {
+        target = `local:${resolved}`;
+      } else if (!dependency.coreModule) {
+        const looksExternal = isExternalPath(resolved) || dependency.dependencyTypes.includes("npm");
+        const packageName = looksExternal ? externalPackageName(isExternalPath(resolved) ? resolved : dependency.module) : void 0;
+        if (packageName) {
+          externalPackages.add(packageName);
+          target = `external:${packageName}`;
+        }
+      }
+      if (target) edges.push({ from: `local:${source}`, to: target, dependency });
+    }
+  }
+  edges.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || JSON.stringify(a.dependency).localeCompare(JSON.stringify(b.dependency)));
+  const lines = [
+    'digraph "dependency-graph" {',
+    '  graph [compound="true", rankdir="LR", fontname="Helvetica"];',
+    '  node [fontname="Helvetica", fontsize="10"];',
+    '  edge [fontname="Helvetica", fontsize="8"];',
+    ...renderDirectory(root, [], "  ")
+  ];
+  if (externalPackages.size > 0) {
+    lines.push('  subgraph "cluster:external-packages" {', '    label="External packages";', '    style="dashed";', '    color="#64748b";');
+    for (const packageName of [...externalPackages].sort()) {
+      lines.push(`    ${dotQuote(`external:${packageName}`)} [label=${dotQuote(packageName)}, shape="component", style="filled", fillcolor="#e2e8f0"];`);
+    }
+    lines.push("  }");
+  }
+  for (const edge of edges) {
+    lines.push(`  ${dotQuote(edge.from)} -> ${dotQuote(edge.to)}${edgeAttributes(edge.dependency)};`);
+  }
+  lines.push("}", "");
+  return lines.join("\n");
+}
+function inferGraphvizFormat(outputPath) {
+  const extension = path7.extname(outputPath).toLowerCase();
+  if (extension === ".svg") return "svg";
+  if (extension === ".dot") return "dot";
+  throw new Error(`Unsupported graph output format "${extension || "(none)"}". Use an .svg or .dot output path.`);
+}
+
+// src/cli/graph/render-graphviz.ts
+import { spawn } from "node:child_process";
+import * as fs3 from "node:fs/promises";
+import * as path8 from "node:path";
+function normalizeGraphvizSvg(svg) {
+  return svg.replace(/<!-- Generated by graphviz version .*? -->/gi, "<!-- Generated by Graphviz -->");
+}
+async function renderDotWithGraphviz(dot, outputPath, options = {}) {
+  const executable = options.executable ?? "dot";
+  const svg = await new Promise((resolve7, reject) => {
+    const child = spawn(executable, ["-Tsvg"], { stdio: ["pipe", "pipe", "pipe"] });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.on("error", (error) => {
+      if (error.code === "ENOENT") {
+        reject(new Error(`Graphviz executable "${executable}" was not found. Install Graphviz and ensure "dot" is available on PATH.`));
+      } else {
+        reject(new Error(`Unable to start Graphviz: ${error.message}`));
+      }
+    });
+    child.on("close", (code) => {
+      if (code === 0) resolve7(Buffer.concat(stdout).toString("utf8"));
+      else reject(new Error(`Graphviz exited with code ${code}: ${Buffer.concat(stderr).toString("utf8").trim()}`));
+    });
+    child.stdin.end(dot);
+  });
+  await fs3.mkdir(path8.dirname(outputPath), { recursive: true });
+  await fs3.writeFile(outputPath, normalizeGraphvizSvg(svg));
+}
+
+// src/cli/commands/graph.ts
+async function runGraphCommand(args) {
+  let values;
+  try {
+    values = parseArgs3({ args, options: {
+      input: { type: "string", short: "i" },
+      output: { type: "string", short: "o" },
+      cwd: { type: "string" },
+      help: { type: "boolean", short: "h" }
+    } }).values;
+  } catch (error) {
+    console.error(`Error parsing arguments: ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+  if (values.help) {
+    console.log(`
+Usage: maritime graph --input <artifact-directory-or-graph.json> --output <graph.svg|graph.dot>
+
+Renders existing canonical graph evidence without running dependency analysis.
+
+Options:
+  -i, --input <path>   .maritime directory or dependency-graph.json (default: .maritime)
+  -o, --output <path>  SVG or DOT output path (required)
+  --cwd <dir>          Working directory root for resolution
+  -h, --help           Show help message
+`);
+    return 0;
+  }
+  if (!values.output) {
+    console.error("Error: --output is required.");
+    return 2;
+  }
+  const cwd = path9.resolve(values.cwd ?? process.cwd());
+  const input = path9.resolve(cwd, values.input ?? ".maritime");
+  const output = path9.resolve(cwd, values.output);
+  try {
+    const stat3 = await fs4.stat(input);
+    const graphPath = stat3.isDirectory() ? path9.resolve(input, (await validateArtifacts({ artifactDir: input, cwd })).manifest.artifacts.graph) : input;
+    const parsed = JSON.parse(await fs4.readFile(graphPath, "utf8"));
+    const result = CruiseResultSchema.safeParse(parsed);
+    if (!result.success) throw new Error(`Invalid Maritime dependency graph: ${result.error.message}`);
+    const dot = renderDependencyGraphToDot(result.data);
+    const format = inferGraphvizFormat(output);
+    await fs4.mkdir(path9.dirname(output), { recursive: true });
+    if (format === "dot") await fs4.writeFile(output, dot);
+    else await renderDotWithGraphviz(dot, output);
+    console.log(`\u2705 Dependency graph rendered from ${graphPath} to ${output}`);
+    return 0;
+  } catch (error) {
+    console.error(`Error rendering dependency graph: ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+}
+
 // src/cli/main.ts
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import * as fs3 from "node:fs";
+import * as fs5 from "node:fs";
 async function main() {
-  const { positionals } = parseArgs3({
+  const { positionals } = parseArgs4({
     args: process.argv.slice(2),
     allowPositionals: true,
     strict: false
@@ -1148,9 +1357,12 @@ async function main() {
     const args = process.argv.slice(3);
     const exitCode = await runValidateCommand(args);
     process.exit(exitCode);
+  } else if (command === "graph") {
+    const exitCode = await runGraphCommand(process.argv.slice(3));
+    process.exit(exitCode);
   } else {
     console.error(`Unknown command: ${command || "(none)"}`);
-    console.error("Available commands: analyze, validate");
+    console.error("Available commands: analyze, validate, graph");
     process.exit(1);
   }
 }
@@ -1159,7 +1371,7 @@ if (process.argv[1]) {
   try {
     const currentPath = fileURLToPath2(import.meta.url);
     const execPath = process.argv[1];
-    isMain = currentPath === execPath || currentPath === fs3.realpathSync(execPath);
+    isMain = currentPath === execPath || currentPath === fs5.realpathSync(execPath);
   } catch {
     isMain = false;
   }

package/dist/cli/schema/dependency-cruiser.d.ts

@@ -178,3 +178,7 @@ export declare const CruiseResultSchema: z.ZodObject<{
         optionsUsed: z.ZodUnknown;
     }, z.core.$loose>;
 }, z.core.$loose>;
+/** Canonical graph types guaranteed after Maritime schema validation. */
+export type MaritimeDependency = z.infer<typeof DependencySchema>;
+export type MaritimeModule = z.infer<typeof ModuleSchema>;
+export type MaritimeCruiseResult = z.infer<typeof CruiseResultSchema>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dependency-maritime/cli",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "type": "module",
   "main": "./dist/cli/index.js",
   "types": "./dist/cli/index.d.ts",
@@ -39,13 +39,12 @@
     "lint": "eslint .",
     "depcruise": "depcruise src --config config/.dependency-cruiser.cjs",
     "check:arch": "depcruise src --config config/.dependency-cruiser.cjs",
-    "generate:dot": "depcruise-fmt -T dot .maritime/dependency-graph.json > config/dependency-graph.dot",
-    "generate:graph": "dot -T svg config/dependency-graph.dot > docs/images/dependency-graph.svg && dot -T png config/dependency-graph.dot > docs/images/dependency-graph.png",
+    "generate:graph": "node dist/cli/main.js graph --input .maritime --output docs/images/dependency-graph.svg",
     "preview": "vite preview",
     "test": "vitest",
     "test:unit": "vitest",
     "test:bench": "vitest bench -c vitest.bench.config.ts",
-    "test:cli-package": "vitest run tests/cli-pack-smoke.test.ts",
+    "test:cli-package": "vitest run tests/cli-pack-smoke.test.ts tests/action-ref-resolution.test.ts",
     "test:e2e": "playwright test",
     "test:screenshots": "playwright test -c config/playwright.screenshots.config.ts"
   },