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

package/README.md

@@ -134,9 +134,16 @@ With Graphviz `dot` installed, render without performing a second analysis:
 
 ```bash
 maritime graph --input .maritime --output docs/images/dependency-graph.svg
+maritime graph --input .maritime --output docs/images/architecture.svg \
+  --external-packages none --folder-grouping nested --edge-labels none
 ```
 
-`.maritime/dependency-graph.json` is canonical evidence; SVG and DOT outputs are derived
+`.maritime/dependency-graph.json` is canonical evidence; SVG (and transient 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.
+
+The rendering flags are presentation-only: `--external-packages` accepts `none`, `summary`, or
+`direct`; `--folder-grouping` accepts `none`, `top-level`, or `nested`; and `--edge-labels` accepts
+`none` or `types`. Defaults (`direct`, `nested`, `types`) preserve existing output. The canonical
+`.maritime/dependency-graph.json` stays complete and is never rescanned or rewritten.

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

@@ -1,6 +1,22 @@
 import type { MaritimeCruiseResult } from '../../schema/dependency-cruiser';
+export declare const EXTERNAL_PACKAGE_MODES: readonly ["none", "summary", "direct"];
+export declare const FOLDER_GROUPING_MODES: readonly ["none", "top-level", "nested"];
+export declare const EDGE_LABEL_MODES: readonly ["none", "types"];
+export type ExternalPackagesMode = typeof EXTERNAL_PACKAGE_MODES[number];
+export type FolderGroupingMode = typeof FOLDER_GROUPING_MODES[number];
+export type EdgeLabelsMode = typeof EDGE_LABEL_MODES[number];
+export type GraphPresentationOptions = {
+    externalPackages?: ExternalPackagesMode;
+    folderGrouping?: FolderGroupingMode;
+    edgeLabels?: EdgeLabelsMode;
+};
+export declare const DEFAULT_GRAPH_PRESENTATION: {
+    readonly externalPackages: "direct";
+    readonly folderGrouping: "nested";
+    readonly edgeLabels: "types";
+};
 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 renderDependencyGraphToDot(graph: MaritimeCruiseResult, options?: GraphPresentationOptions): string;
 export declare function inferGraphvizFormat(outputPath: string): 'svg' | 'dot';
 export { externalPackageName };

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

@@ -3,7 +3,8 @@ import { runValidateCommand } from './commands/validate';
 import { runGraphCommand } from './commands/graph';
 import { validateArtifacts } from './validate/validate';
 export { runAnalyzeCommand, runValidateCommand, runGraphCommand, validateArtifacts };
-export { renderDependencyGraphToDot, inferGraphvizFormat } from './graph/render-dot';
+export { renderDependencyGraphToDot, inferGraphvizFormat, DEFAULT_GRAPH_PRESENTATION, EXTERNAL_PACKAGE_MODES, FOLDER_GROUPING_MODES, EDGE_LABEL_MODES } from './graph/render-dot';
+export type { GraphPresentationOptions, ExternalPackagesMode, FolderGroupingMode, EdgeLabelsMode } 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';

package/dist/cli/index.d.ts

@@ -3,7 +3,8 @@ import { runValidateCommand } from './commands/validate';
 import { runGraphCommand } from './commands/graph';
 import { validateArtifacts } from './validate/validate';
 export { runAnalyzeCommand, runValidateCommand, runGraphCommand, validateArtifacts };
-export { renderDependencyGraphToDot, inferGraphvizFormat } from './graph/render-dot';
+export { renderDependencyGraphToDot, inferGraphvizFormat, DEFAULT_GRAPH_PRESENTATION, EXTERNAL_PACKAGE_MODES, FOLDER_GROUPING_MODES, EDGE_LABEL_MODES } from './graph/render-dot';
+export type { GraphPresentationOptions, ExternalPackagesMode, FolderGroupingMode, EdgeLabelsMode } 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';

package/dist/cli/index.js

@@ -1132,6 +1132,14 @@ import * as path9 from "node:path";
 
 // src/cli/graph/render-dot.ts
 import * as path7 from "node:path";
+var EXTERNAL_PACKAGE_MODES = ["none", "summary", "direct"];
+var FOLDER_GROUPING_MODES = ["none", "top-level", "nested"];
+var EDGE_LABEL_MODES = ["none", "types"];
+var DEFAULT_GRAPH_PRESENTATION = {
+  externalPackages: "direct",
+  folderGrouping: "nested",
+  edgeLabels: "types"
+};
 var dotQuote = (value) => JSON.stringify(value);
 var normalizedPath = (value) => value.replaceAll("\\", "/").replace(/^\.\//, "");
 function externalPackageName(value) {
@@ -1178,10 +1186,10 @@ function renderDirectory(directory, segments, indent) {
   }
   return lines;
 }
-function edgeAttributes(dependency) {
+function edgeAttributes(dependency, edgeLabels) {
   const attributes = [];
   const dependencyTypes = [...dependency.dependencyTypes].sort();
-  if (dependencyTypes.length > 0) attributes.push(`label=${dotQuote(dependencyTypes.join(", "))}`);
+  if (edgeLabels === "types" && 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) {
@@ -1190,7 +1198,12 @@ function edgeAttributes(dependency) {
   }
   return attributes.length > 0 ? ` [${attributes.join(", ")}]` : "";
 }
-function renderDependencyGraphToDot(graph) {
+function renderDependencyGraphToDot(graph, options = {}) {
+  const presentation = {
+    externalPackages: options.externalPackages ?? DEFAULT_GRAPH_PRESENTATION.externalPackages,
+    folderGrouping: options.folderGrouping ?? DEFAULT_GRAPH_PRESENTATION.folderGrouping,
+    edgeLabels: options.edgeLabels ?? DEFAULT_GRAPH_PRESENTATION.edgeLabels
+  };
   const root = { directories: /* @__PURE__ */ new Map(), files: [] };
   const localSources = /* @__PURE__ */ new Set();
   const externalPackages = /* @__PURE__ */ new Set();
@@ -1198,7 +1211,17 @@ function renderDependencyGraphToDot(graph) {
     const source = normalizedPath(module.source);
     if (isExternalPath(source) || module.coreModule) continue;
     localSources.add(source);
-    addLocalModule(root, source);
+    if (presentation.folderGrouping === "nested") addLocalModule(root, source);
+    else if (presentation.folderGrouping === "top-level") {
+      if (!source.includes("/")) {
+        root.files.push({ source, name: source });
+        continue;
+      }
+      const [topLevel] = source.split("/");
+      const directory = root.directories.get(topLevel) ?? { directories: /* @__PURE__ */ new Map(), files: [] };
+      root.directories.set(topLevel, directory);
+      directory.files.push({ source, name: path7.posix.basename(source) });
+    } else root.files.push({ source, name: path7.posix.basename(source) });
   }
   const edges = [];
   for (const module of [...graph.modules].sort((a, b) => a.source.localeCompare(b.source))) {
@@ -1212,9 +1235,9 @@ function renderDependencyGraphToDot(graph) {
       } 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) {
+        if (packageName && presentation.externalPackages !== "none") {
           externalPackages.add(packageName);
-          target = `external:${packageName}`;
+          target = presentation.externalPackages === "summary" ? "external:boundary" : `external:${packageName}`;
         }
       }
       if (target) edges.push({ from: `local:${source}`, to: target, dependency });
@@ -1223,12 +1246,18 @@ function renderDependencyGraphToDot(graph) {
   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"];',
+    // Graphviz 2.42 can fail init_rank when the default cluster-local ranker
+    // encounters a large recursively nested directory hierarchy. newrank asks
+    // dot to compute one global ranking across clusters while preserving the
+    // cluster boxes and deterministic left-to-right presentation.
+    '  graph [compound="true", newrank="true", rankdir="LR", fontname="Helvetica"];',
     '  node [fontname="Helvetica", fontsize="10"];',
     '  edge [fontname="Helvetica", fontsize="8"];',
     ...renderDirectory(root, [], "  ")
   ];
-  if (externalPackages.size > 0) {
+  if (presentation.externalPackages === "summary" && externalPackages.size > 0) {
+    lines.push('  "external:boundary" [label="External packages", shape="component", style="filled,dashed", fillcolor="#e2e8f0", color="#64748b"];');
+  } else if (presentation.externalPackages === "direct" && 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"];`);
@@ -1236,7 +1265,7 @@ function renderDependencyGraphToDot(graph) {
     lines.push("  }");
   }
   for (const edge of edges) {
-    lines.push(`  ${dotQuote(edge.from)} -> ${dotQuote(edge.to)}${edgeAttributes(edge.dependency)};`);
+    lines.push(`  ${dotQuote(edge.from)} -> ${dotQuote(edge.to)}${edgeAttributes(edge.dependency, presentation.edgeLabels)};`);
   }
   lines.push("}", "");
   return lines.join("\n");
@@ -1288,7 +1317,10 @@ async function runGraphCommand(args) {
       input: { type: "string", short: "i" },
       output: { type: "string", short: "o" },
       cwd: { type: "string" },
-      help: { type: "boolean", short: "h" }
+      help: { type: "boolean", short: "h" },
+      "external-packages": { type: "string" },
+      "folder-grouping": { type: "string" },
+      "edge-labels": { type: "string" }
     } }).values;
   } catch (error) {
     console.error(`Error parsing arguments: ${error instanceof Error ? error.message : String(error)}`);
@@ -1303,6 +1335,9 @@ 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)
+  --external-packages <none|summary|direct>  External package presentation (default: direct)
+  --folder-grouping <none|top-level|nested>   Local folder clustering (default: nested)
+  --edge-labels <none|types>                  Dependency-type labels (default: types)
   --cwd <dir>          Working directory root for resolution
   -h, --help           Show help message
 `);
@@ -1312,6 +1347,22 @@ Options:
     console.error("Error: --output is required.");
     return 2;
   }
+  const validatePolicy = (flag, value, allowed, fallback) => {
+    if (value === void 0) return fallback;
+    if (allowed.includes(value)) return value;
+    throw new Error(`Invalid --${flag} value "${value}". Expected one of: ${allowed.join(", ")}.`);
+  };
+  let externalPackages;
+  let folderGrouping;
+  let edgeLabels;
+  try {
+    externalPackages = validatePolicy("external-packages", values["external-packages"], EXTERNAL_PACKAGE_MODES, "direct");
+    folderGrouping = validatePolicy("folder-grouping", values["folder-grouping"], FOLDER_GROUPING_MODES, "nested");
+    edgeLabels = validatePolicy("edge-labels", values["edge-labels"], EDGE_LABEL_MODES, "types");
+  } catch (error) {
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    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);
@@ -1321,7 +1372,7 @@ Options:
     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 dot = renderDependencyGraphToDot(result.data, { externalPackages, folderGrouping, edgeLabels });
     const format = inferGraphvizFormat(output);
     await fs4.mkdir(path9.dirname(output), { recursive: true });
     if (format === "dot") await fs4.writeFile(output, dot);
@@ -1380,6 +1431,10 @@ export {
   ArtifactManifestArtifactsSchema,
   ArtifactManifestSchema,
   ArtifactManifestSummarySchema,
+  DEFAULT_GRAPH_PRESENTATION,
+  EDGE_LABEL_MODES,
+  EXTERNAL_PACKAGE_MODES,
+  FOLDER_GROUPING_MODES,
   MANIFEST_SCHEMA_VERSION,
   ValidationError,
   analyzeProject,

package/dist/cli/main.js

@@ -1137,6 +1137,14 @@ import * as path9 from "node:path";
 
 // src/cli/graph/render-dot.ts
 import * as path7 from "node:path";
+var EXTERNAL_PACKAGE_MODES = ["none", "summary", "direct"];
+var FOLDER_GROUPING_MODES = ["none", "top-level", "nested"];
+var EDGE_LABEL_MODES = ["none", "types"];
+var DEFAULT_GRAPH_PRESENTATION = {
+  externalPackages: "direct",
+  folderGrouping: "nested",
+  edgeLabels: "types"
+};
 var dotQuote = (value) => JSON.stringify(value);
 var normalizedPath = (value) => value.replaceAll("\\", "/").replace(/^\.\//, "");
 function externalPackageName(value) {
@@ -1183,10 +1191,10 @@ function renderDirectory(directory, segments, indent) {
   }
   return lines;
 }
-function edgeAttributes(dependency) {
+function edgeAttributes(dependency, edgeLabels) {
   const attributes = [];
   const dependencyTypes = [...dependency.dependencyTypes].sort();
-  if (dependencyTypes.length > 0) attributes.push(`label=${dotQuote(dependencyTypes.join(", "))}`);
+  if (edgeLabels === "types" && 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) {
@@ -1195,7 +1203,12 @@ function edgeAttributes(dependency) {
   }
   return attributes.length > 0 ? ` [${attributes.join(", ")}]` : "";
 }
-function renderDependencyGraphToDot(graph) {
+function renderDependencyGraphToDot(graph, options = {}) {
+  const presentation = {
+    externalPackages: options.externalPackages ?? DEFAULT_GRAPH_PRESENTATION.externalPackages,
+    folderGrouping: options.folderGrouping ?? DEFAULT_GRAPH_PRESENTATION.folderGrouping,
+    edgeLabels: options.edgeLabels ?? DEFAULT_GRAPH_PRESENTATION.edgeLabels
+  };
   const root = { directories: /* @__PURE__ */ new Map(), files: [] };
   const localSources = /* @__PURE__ */ new Set();
   const externalPackages = /* @__PURE__ */ new Set();
@@ -1203,7 +1216,17 @@ function renderDependencyGraphToDot(graph) {
     const source = normalizedPath(module.source);
     if (isExternalPath(source) || module.coreModule) continue;
     localSources.add(source);
-    addLocalModule(root, source);
+    if (presentation.folderGrouping === "nested") addLocalModule(root, source);
+    else if (presentation.folderGrouping === "top-level") {
+      if (!source.includes("/")) {
+        root.files.push({ source, name: source });
+        continue;
+      }
+      const [topLevel] = source.split("/");
+      const directory = root.directories.get(topLevel) ?? { directories: /* @__PURE__ */ new Map(), files: [] };
+      root.directories.set(topLevel, directory);
+      directory.files.push({ source, name: path7.posix.basename(source) });
+    } else root.files.push({ source, name: path7.posix.basename(source) });
   }
   const edges = [];
   for (const module of [...graph.modules].sort((a, b) => a.source.localeCompare(b.source))) {
@@ -1217,9 +1240,9 @@ function renderDependencyGraphToDot(graph) {
       } 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) {
+        if (packageName && presentation.externalPackages !== "none") {
           externalPackages.add(packageName);
-          target = `external:${packageName}`;
+          target = presentation.externalPackages === "summary" ? "external:boundary" : `external:${packageName}`;
         }
       }
       if (target) edges.push({ from: `local:${source}`, to: target, dependency });
@@ -1228,12 +1251,18 @@ function renderDependencyGraphToDot(graph) {
   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"];',
+    // Graphviz 2.42 can fail init_rank when the default cluster-local ranker
+    // encounters a large recursively nested directory hierarchy. newrank asks
+    // dot to compute one global ranking across clusters while preserving the
+    // cluster boxes and deterministic left-to-right presentation.
+    '  graph [compound="true", newrank="true", rankdir="LR", fontname="Helvetica"];',
     '  node [fontname="Helvetica", fontsize="10"];',
     '  edge [fontname="Helvetica", fontsize="8"];',
     ...renderDirectory(root, [], "  ")
   ];
-  if (externalPackages.size > 0) {
+  if (presentation.externalPackages === "summary" && externalPackages.size > 0) {
+    lines.push('  "external:boundary" [label="External packages", shape="component", style="filled,dashed", fillcolor="#e2e8f0", color="#64748b"];');
+  } else if (presentation.externalPackages === "direct" && 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"];`);
@@ -1241,7 +1270,7 @@ function renderDependencyGraphToDot(graph) {
     lines.push("  }");
   }
   for (const edge of edges) {
-    lines.push(`  ${dotQuote(edge.from)} -> ${dotQuote(edge.to)}${edgeAttributes(edge.dependency)};`);
+    lines.push(`  ${dotQuote(edge.from)} -> ${dotQuote(edge.to)}${edgeAttributes(edge.dependency, presentation.edgeLabels)};`);
   }
   lines.push("}", "");
   return lines.join("\n");
@@ -1293,7 +1322,10 @@ async function runGraphCommand(args) {
       input: { type: "string", short: "i" },
       output: { type: "string", short: "o" },
       cwd: { type: "string" },
-      help: { type: "boolean", short: "h" }
+      help: { type: "boolean", short: "h" },
+      "external-packages": { type: "string" },
+      "folder-grouping": { type: "string" },
+      "edge-labels": { type: "string" }
     } }).values;
   } catch (error) {
     console.error(`Error parsing arguments: ${error instanceof Error ? error.message : String(error)}`);
@@ -1308,6 +1340,9 @@ 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)
+  --external-packages <none|summary|direct>  External package presentation (default: direct)
+  --folder-grouping <none|top-level|nested>   Local folder clustering (default: nested)
+  --edge-labels <none|types>                  Dependency-type labels (default: types)
   --cwd <dir>          Working directory root for resolution
   -h, --help           Show help message
 `);
@@ -1317,6 +1352,22 @@ Options:
     console.error("Error: --output is required.");
     return 2;
   }
+  const validatePolicy = (flag, value, allowed, fallback) => {
+    if (value === void 0) return fallback;
+    if (allowed.includes(value)) return value;
+    throw new Error(`Invalid --${flag} value "${value}". Expected one of: ${allowed.join(", ")}.`);
+  };
+  let externalPackages;
+  let folderGrouping;
+  let edgeLabels;
+  try {
+    externalPackages = validatePolicy("external-packages", values["external-packages"], EXTERNAL_PACKAGE_MODES, "direct");
+    folderGrouping = validatePolicy("folder-grouping", values["folder-grouping"], FOLDER_GROUPING_MODES, "nested");
+    edgeLabels = validatePolicy("edge-labels", values["edge-labels"], EDGE_LABEL_MODES, "types");
+  } catch (error) {
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    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);
@@ -1326,7 +1377,7 @@ Options:
     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 dot = renderDependencyGraphToDot(result.data, { externalPackages, folderGrouping, edgeLabels });
     const format = inferGraphvizFormat(output);
     await fs4.mkdir(path9.dirname(output), { recursive: true });
     if (format === "dot") await fs4.writeFile(output, dot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dependency-maritime/cli",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "type": "module",
   "main": "./dist/cli/index.js",
   "types": "./dist/cli/index.d.ts",