@webpieces/dev-config 0.2.17 → 0.2.21

package/architecture/lib/graph-loader.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Graph Loader
+ *
+ * Handles loading and saving the blessed dependency graph file.
+ * The graph is stored at architecture/dependencies.json in the workspace root.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GRAPH_PATH = void 0;
+exports.loadBlessedGraph = loadBlessedGraph;
+exports.saveGraph = saveGraph;
+exports.graphFileExists = graphFileExists;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+/**
+ * Default path for the dependencies file (relative to workspace root)
+ */
+exports.DEFAULT_GRAPH_PATH = 'architecture/dependencies.json';
+/**
+ * Load the blessed graph from disk
+ *
+ * @param workspaceRoot - Absolute path to workspace root
+ * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)
+ * @returns The blessed graph, or null if file doesn't exist
+ */
+function loadBlessedGraph(workspaceRoot, graphPath = exports.DEFAULT_GRAPH_PATH) {
+    const fullPath = path.join(workspaceRoot, graphPath);
+    if (!fs.existsSync(fullPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (err) {
+        throw new Error(`Failed to load graph from ${fullPath}: ${err}`);
+    }
+}
+/**
+ * Save the graph to disk
+ *
+ * @param graph - The graph to save
+ * @param workspaceRoot - Absolute path to workspace root
+ * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)
+ */
+function saveGraph(graph, workspaceRoot, graphPath = exports.DEFAULT_GRAPH_PATH) {
+    const fullPath = path.join(workspaceRoot, graphPath);
+    const dir = path.dirname(fullPath);
+    // Ensure directory exists
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Sort keys for deterministic output
+    const sortedGraph = {};
+    const sortedKeys = Object.keys(graph).sort();
+    for (const key of sortedKeys) {
+        sortedGraph[key] = graph[key];
+    }
+    const content = JSON.stringify(sortedGraph, null, 2) + '\n';
+    fs.writeFileSync(fullPath, content, 'utf-8');
+}
+/**
+ * Check if the graph file exists
+ */
+function graphFileExists(workspaceRoot, graphPath = exports.DEFAULT_GRAPH_PATH) {
+    const fullPath = path.join(workspaceRoot, graphPath);
+    return fs.existsSync(fullPath);
+}
+//# sourceMappingURL=graph-loader.js.map

package/architecture/lib/graph-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-loader.js","sourceRoot":"","sources":["../../../../../../packages/tooling/dev-config/architecture/lib/graph-loader.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAkBH,4CAgBC;AASD,8BAsBC;AAKD,0CAMC;;AA1ED,+CAAyB;AACzB,mDAA6B;AAG7B;;GAEG;AACU,QAAA,kBAAkB,GAAG,gCAAgC,CAAC;AAEnE;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAC5B,aAAqB,EACrB,YAAoB,0BAAkB;IAEtC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAErD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,IAAI,CAAC;QACD,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAkB,CAAC;IAChD,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,KAAK,GAAG,EAAE,CAAC,CAAC;IACrE,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CACrB,KAAoB,EACpB,aAAqB,EACrB,YAAoB,0BAAkB;IAEtC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEnC,0BAA0B;IAC1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,qCAAqC;IACrC,MAAM,WAAW,GAAkB,EAAE,CAAC;IACtC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC3B,WAAW,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IAC5D,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAC3B,aAAqB,EACrB,YAAoB,0BAAkB;IAEtC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACrD,OAAO,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC","sourcesContent":["/**\n * Graph Loader\n *\n * Handles loading and saving the blessed dependency graph file.\n * The graph is stored at architecture/dependencies.json in the workspace root.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { EnhancedGraph } from './graph-sorter';\n\n/**\n * Default path for the dependencies file (relative to workspace root)\n */\nexport const DEFAULT_GRAPH_PATH = 'architecture/dependencies.json';\n\n/**\n * Load the blessed graph from disk\n *\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)\n * @returns The blessed graph, or null if file doesn't exist\n */\nexport function loadBlessedGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH\n): EnhancedGraph | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n\n    if (!fs.existsSync(fullPath)) {\n        return null;\n    }\n\n    try {\n        const content = fs.readFileSync(fullPath, 'utf-8');\n        return JSON.parse(content) as EnhancedGraph;\n    } catch (err: unknown) {\n        throw new Error(`Failed to load graph from ${fullPath}: ${err}`);\n    }\n}\n\n/**\n * Save the graph to disk\n *\n * @param graph - The graph to save\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)\n */\nexport function saveGraph(\n    graph: EnhancedGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH\n): void {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    const dir = path.dirname(fullPath);\n\n    // Ensure directory exists\n    if (!fs.existsSync(dir)) {\n        fs.mkdirSync(dir, { recursive: true });\n    }\n\n    // Sort keys for deterministic output\n    const sortedGraph: EnhancedGraph = {};\n    const sortedKeys = Object.keys(graph).sort();\n    for (const key of sortedKeys) {\n        sortedGraph[key] = graph[key];\n    }\n\n    const content = JSON.stringify(sortedGraph, null, 2) + '\\n';\n    fs.writeFileSync(fullPath, content, 'utf-8');\n}\n\n/**\n * Check if the graph file exists\n */\nexport function graphFileExists(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH\n): boolean {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    return fs.existsSync(fullPath);\n}\n"]}

package/architecture/lib/graph-loader.ts

@@ -0,0 +1,82 @@
+/**
+ * Graph Loader
+ *
+ * Handles loading and saving the blessed dependency graph file.
+ * The graph is stored at architecture/dependencies.json in the workspace root.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { EnhancedGraph } from './graph-sorter';
+
+/**
+ * Default path for the dependencies file (relative to workspace root)
+ */
+export const DEFAULT_GRAPH_PATH = 'architecture/dependencies.json';
+
+/**
+ * Load the blessed graph from disk
+ *
+ * @param workspaceRoot - Absolute path to workspace root
+ * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)
+ * @returns The blessed graph, or null if file doesn't exist
+ */
+export function loadBlessedGraph(
+    workspaceRoot: string,
+    graphPath: string = DEFAULT_GRAPH_PATH
+): EnhancedGraph | null {
+    const fullPath = path.join(workspaceRoot, graphPath);
+
+    if (!fs.existsSync(fullPath)) {
+        return null;
+    }
+
+    try {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        return JSON.parse(content) as EnhancedGraph;
+    } catch (err: unknown) {
+        throw new Error(`Failed to load graph from ${fullPath}: ${err}`);
+    }
+}
+
+/**
+ * Save the graph to disk
+ *
+ * @param graph - The graph to save
+ * @param workspaceRoot - Absolute path to workspace root
+ * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)
+ */
+export function saveGraph(
+    graph: EnhancedGraph,
+    workspaceRoot: string,
+    graphPath: string = DEFAULT_GRAPH_PATH
+): void {
+    const fullPath = path.join(workspaceRoot, graphPath);
+    const dir = path.dirname(fullPath);
+
+    // Ensure directory exists
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+
+    // Sort keys for deterministic output
+    const sortedGraph: EnhancedGraph = {};
+    const sortedKeys = Object.keys(graph).sort();
+    for (const key of sortedKeys) {
+        sortedGraph[key] = graph[key];
+    }
+
+    const content = JSON.stringify(sortedGraph, null, 2) + '\n';
+    fs.writeFileSync(fullPath, content, 'utf-8');
+}
+
+/**
+ * Check if the graph file exists
+ */
+export function graphFileExists(
+    workspaceRoot: string,
+    graphPath: string = DEFAULT_GRAPH_PATH
+): boolean {
+    const fullPath = path.join(workspaceRoot, graphPath);
+    return fs.existsSync(fullPath);
+}

package/architecture/lib/graph-sorter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Graph Sorter
+ *
+ * Performs topological sorting on the dependency graph to:
+ * 1. Detect circular dependencies (fails if cycle found)
+ * 2. Assign level numbers to each project (level 0 = no deps, level 1 = depends on level 0, etc.)
+ * 3. Group projects into layers for deterministic ordering
+ */
+/**
+ * Graph entry with level metadata
+ */
+export interface GraphEntry {
+    level: number;
+    dependsOn: string[];
+}
+/**
+ * Enhanced graph format with level information
+ */
+export type EnhancedGraph = Record<string, GraphEntry>;
+/**
+ * Compute topological layers for dependency graph using Kahn's algorithm
+ *
+ * Projects are grouped into layers where each layer only depends on previous layers.
+ * Throws an error if a circular dependency is detected.
+ *
+ * @param graph - Dependency graph { project: [deps] }
+ * @returns Array of layers, each containing sorted project names
+ */
+export declare function computeTopologicalLayers(graph: Record<string, string[]>): string[][];
+/**
+ * Sort graph in topological order with alphabetical sorting within layers
+ * Returns enhanced format with level metadata
+ *
+ * @param graph - Unsorted dependency graph { project: [deps] }
+ * @returns Sorted graph with level metadata { project: { level: number, dependsOn: [deps] } }
+ */
+export declare function sortGraphTopologically(graph: Record<string, string[]>): EnhancedGraph;

package/architecture/lib/graph-sorter.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Graph Sorter
+ *
+ * Performs topological sorting on the dependency graph to:
+ * 1. Detect circular dependencies (fails if cycle found)
+ * 2. Assign level numbers to each project (level 0 = no deps, level 1 = depends on level 0, etc.)
+ * 3. Group projects into layers for deterministic ordering
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeTopologicalLayers = computeTopologicalLayers;
+exports.sortGraphTopologically = sortGraphTopologically;
+/**
+ * Compute topological layers for dependency graph using Kahn's algorithm
+ *
+ * Projects are grouped into layers where each layer only depends on previous layers.
+ * Throws an error if a circular dependency is detected.
+ *
+ * @param graph - Dependency graph { project: [deps] }
+ * @returns Array of layers, each containing sorted project names
+ */
+function computeTopologicalLayers(graph) {
+    const layers = [];
+    const processed = new Set();
+    const allProjects = Object.keys(graph);
+    while (processed.size < allProjects.length) {
+        const currentLayer = [];
+        for (const project of allProjects) {
+            if (processed.has(project))
+                continue;
+            const deps = graph[project] || [];
+            // Check if all dependencies are in previous layers (already processed)
+            const allDepsInPrevLayers = deps.every((dep) => processed.has(dep));
+            if (allDepsInPrevLayers) {
+                currentLayer.push(project);
+            }
+        }
+        if (currentLayer.length === 0) {
+            // No progress made = circular dependency detected
+            const remaining = allProjects.filter((p) => !processed.has(p));
+            // Try to identify the cycle
+            const cycleInfo = findCycle(graph, remaining);
+            throw new Error(`Circular dependency detected among: ${remaining.join(', ')}\n` +
+                (cycleInfo ? `Cycle: ${cycleInfo}\n` : '') +
+                'Fix: Remove one of the dependencies to break the cycle.');
+        }
+        // Sort alphabetically within layer for deterministic output
+        currentLayer.sort();
+        layers.push(currentLayer);
+        // Mark as processed
+        currentLayer.forEach((p) => processed.add(p));
+    }
+    return layers;
+}
+/**
+ * Try to find and describe a cycle in the graph
+ */
+function findCycle(graph, remaining) {
+    const visited = new Set();
+    const path = [];
+    function dfs(node) {
+        if (path.includes(node)) {
+            const cycleStart = path.indexOf(node);
+            return [...path.slice(cycleStart), node].join(' -> ');
+        }
+        if (visited.has(node))
+            return null;
+        visited.add(node);
+        path.push(node);
+        const deps = graph[node] || [];
+        for (const dep of deps) {
+            if (remaining.includes(dep)) {
+                const result = dfs(dep);
+                if (result)
+                    return result;
+            }
+        }
+        path.pop();
+        return null;
+    }
+    for (const node of remaining) {
+        const cycle = dfs(node);
+        if (cycle)
+            return cycle;
+    }
+    return null;
+}
+/**
+ * Sort graph in topological order with alphabetical sorting within layers
+ * Returns enhanced format with level metadata
+ *
+ * @param graph - Unsorted dependency graph { project: [deps] }
+ * @returns Sorted graph with level metadata { project: { level: number, dependsOn: [deps] } }
+ */
+function sortGraphTopologically(graph) {
+    const layers = computeTopologicalLayers(graph);
+    const result = {};
+    // Add projects layer by layer (dependencies before dependents)
+    layers.forEach((layer, levelIndex) => {
+        for (const project of layer) {
+            // Already sorted alphabetically within layer
+            result[project] = {
+                level: levelIndex,
+                dependsOn: (graph[project] || []).sort(),
+            };
+        }
+    });
+    return result;
+}
+//# sourceMappingURL=graph-sorter.js.map

package/architecture/lib/graph-sorter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-sorter.js","sourceRoot":"","sources":["../../../../../../packages/tooling/dev-config/architecture/lib/graph-sorter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Sorter\n *\n * Performs topological sorting on the dependency graph to:\n * 1. Detect circular dependencies (fails if cycle found)\n * 2. Assign level numbers to each project (level 0 = no deps, level 1 = depends on level 0, etc.)\n * 3. Group projects into layers for deterministic ordering\n */\n\n/**\n * Graph entry with level metadata\n */\nexport interface GraphEntry {\n    level: number;\n    dependsOn: string[];\n}\n\n/**\n * Enhanced graph format with level information\n */\nexport type EnhancedGraph = Record<string, GraphEntry>;\n\n/**\n * Compute topological layers for dependency graph using Kahn's algorithm\n *\n * Projects are grouped into layers where each layer only depends on previous layers.\n * Throws an error if a circular dependency is detected.\n *\n * @param graph - Dependency graph { project: [deps] }\n * @returns Array of layers, each containing sorted project names\n */\nexport function computeTopologicalLayers(graph: Record<string, string[]>): string[][] {\n    const layers: string[][] = [];\n    const processed = new Set<string>();\n    const allProjects = Object.keys(graph);\n\n    while (processed.size < allProjects.length) {\n        const currentLayer: string[] = [];\n\n        for (const project of allProjects) {\n            if (processed.has(project)) continue;\n\n            const deps = graph[project] || [];\n            // Check if all dependencies are in previous layers (already processed)\n            const allDepsInPrevLayers = deps.every((dep) => processed.has(dep));\n\n            if (allDepsInPrevLayers) {\n                currentLayer.push(project);\n            }\n        }\n\n        if (currentLayer.length === 0) {\n            // No progress made = circular dependency detected\n            const remaining = allProjects.filter((p) => !processed.has(p));\n\n            // Try to identify the cycle\n            const cycleInfo = findCycle(graph, remaining);\n\n            throw new Error(\n                `Circular dependency detected among: ${remaining.join(', ')}\\n` +\n                    (cycleInfo ? `Cycle: ${cycleInfo}\\n` : '') +\n                    'Fix: Remove one of the dependencies to break the cycle.'\n            );\n        }\n\n        // Sort alphabetically within layer for deterministic output\n        currentLayer.sort();\n        layers.push(currentLayer);\n\n        // Mark as processed\n        currentLayer.forEach((p) => processed.add(p));\n    }\n\n    return layers;\n}\n\n/**\n * Try to find and describe a cycle in the graph\n */\nfunction findCycle(graph: Record<string, string[]>, remaining: string[]): string | null {\n    const visited = new Set<string>();\n    const path: string[] = [];\n\n    function dfs(node: string): string | null {\n        if (path.includes(node)) {\n            const cycleStart = path.indexOf(node);\n            return [...path.slice(cycleStart), node].join(' -> ');\n        }\n        if (visited.has(node)) return null;\n\n        visited.add(node);\n        path.push(node);\n\n        const deps = graph[node] || [];\n        for (const dep of deps) {\n            if (remaining.includes(dep)) {\n                const result = dfs(dep);\n                if (result) return result;\n            }\n        }\n\n        path.pop();\n        return null;\n    }\n\n    for (const node of remaining) {\n        const cycle = dfs(node);\n        if (cycle) return cycle;\n    }\n\n    return null;\n}\n\n/**\n * Sort graph in topological order with alphabetical sorting within layers\n * Returns enhanced format with level metadata\n *\n * @param graph - Unsorted dependency graph { project: [deps] }\n * @returns Sorted graph with level metadata { project: { level: number, dependsOn: [deps] } }\n */\nexport function sortGraphTopologically(graph: Record<string, string[]>): EnhancedGraph {\n    const layers = computeTopologicalLayers(graph);\n    const result: EnhancedGraph = {};\n\n    // Add projects layer by layer (dependencies before dependents)\n    layers.forEach((layer, levelIndex) => {\n        for (const project of layer) {\n            // Already sorted alphabetically within layer\n            result[project] = {\n                level: levelIndex,\n                dependsOn: (graph[project] || []).sort(),\n            };\n        }\n    });\n\n    return result;\n}\n"]}

package/architecture/lib/graph-sorter.ts

@@ -0,0 +1,137 @@
+/**
+ * Graph Sorter
+ *
+ * Performs topological sorting on the dependency graph to:
+ * 1. Detect circular dependencies (fails if cycle found)
+ * 2. Assign level numbers to each project (level 0 = no deps, level 1 = depends on level 0, etc.)
+ * 3. Group projects into layers for deterministic ordering
+ */
+
+/**
+ * Graph entry with level metadata
+ */
+export interface GraphEntry {
+    level: number;
+    dependsOn: string[];
+}
+
+/**
+ * Enhanced graph format with level information
+ */
+export type EnhancedGraph = Record<string, GraphEntry>;
+
+/**
+ * Compute topological layers for dependency graph using Kahn's algorithm
+ *
+ * Projects are grouped into layers where each layer only depends on previous layers.
+ * Throws an error if a circular dependency is detected.
+ *
+ * @param graph - Dependency graph { project: [deps] }
+ * @returns Array of layers, each containing sorted project names
+ */
+export function computeTopologicalLayers(graph: Record<string, string[]>): string[][] {
+    const layers: string[][] = [];
+    const processed = new Set<string>();
+    const allProjects = Object.keys(graph);
+
+    while (processed.size < allProjects.length) {
+        const currentLayer: string[] = [];
+
+        for (const project of allProjects) {
+            if (processed.has(project)) continue;
+
+            const deps = graph[project] || [];
+            // Check if all dependencies are in previous layers (already processed)
+            const allDepsInPrevLayers = deps.every((dep) => processed.has(dep));
+
+            if (allDepsInPrevLayers) {
+                currentLayer.push(project);
+            }
+        }
+
+        if (currentLayer.length === 0) {
+            // No progress made = circular dependency detected
+            const remaining = allProjects.filter((p) => !processed.has(p));
+
+            // Try to identify the cycle
+            const cycleInfo = findCycle(graph, remaining);
+
+            throw new Error(
+                `Circular dependency detected among: ${remaining.join(', ')}\n` +
+                    (cycleInfo ? `Cycle: ${cycleInfo}\n` : '') +
+                    'Fix: Remove one of the dependencies to break the cycle.'
+            );
+        }
+
+        // Sort alphabetically within layer for deterministic output
+        currentLayer.sort();
+        layers.push(currentLayer);
+
+        // Mark as processed
+        currentLayer.forEach((p) => processed.add(p));
+    }
+
+    return layers;
+}
+
+/**
+ * Try to find and describe a cycle in the graph
+ */
+function findCycle(graph: Record<string, string[]>, remaining: string[]): string | null {
+    const visited = new Set<string>();
+    const path: string[] = [];
+
+    function dfs(node: string): string | null {
+        if (path.includes(node)) {
+            const cycleStart = path.indexOf(node);
+            return [...path.slice(cycleStart), node].join(' -> ');
+        }
+        if (visited.has(node)) return null;
+
+        visited.add(node);
+        path.push(node);
+
+        const deps = graph[node] || [];
+        for (const dep of deps) {
+            if (remaining.includes(dep)) {
+                const result = dfs(dep);
+                if (result) return result;
+            }
+        }
+
+        path.pop();
+        return null;
+    }
+
+    for (const node of remaining) {
+        const cycle = dfs(node);
+        if (cycle) return cycle;
+    }
+
+    return null;
+}
+
+/**
+ * Sort graph in topological order with alphabetical sorting within layers
+ * Returns enhanced format with level metadata
+ *
+ * @param graph - Unsorted dependency graph { project: [deps] }
+ * @returns Sorted graph with level metadata { project: { level: number, dependsOn: [deps] } }
+ */
+export function sortGraphTopologically(graph: Record<string, string[]>): EnhancedGraph {
+    const layers = computeTopologicalLayers(graph);
+    const result: EnhancedGraph = {};
+
+    // Add projects layer by layer (dependencies before dependents)
+    layers.forEach((layer, levelIndex) => {
+        for (const project of layer) {
+            // Already sorted alphabetically within layer
+            result[project] = {
+                level: levelIndex,
+                dependsOn: (graph[project] || []).sort(),
+            };
+        }
+    });
+
+    return result;
+}

package/architecture/lib/graph-visualizer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Graph Visualizer
+ *
+ * Generates visual representations of the architecture graph:
+ * - DOT format (for Graphviz)
+ * - Interactive HTML (using viz.js)
+ *
+ * Output files go to tmp/webpieces/ for easy viewing without committing.
+ */
+import type { EnhancedGraph } from './graph-sorter';
+/**
+ * Generate Graphviz DOT format from the graph
+ */
+export declare function generateDot(graph: EnhancedGraph, title?: string): string;
+/**
+ * Generate interactive HTML with embedded SVG using viz.js
+ */
+export declare function generateHTML(dot: string, title?: string): string;
+/**
+ * Write visualization files to tmp/webpieces/
+ */
+export declare function writeVisualization(graph: EnhancedGraph, workspaceRoot: string, title?: string): {
+    dotPath: string;
+    htmlPath: string;
+};
+/**
+ * Open the HTML visualization in the default browser
+ */
+export declare function openVisualization(htmlPath: string): boolean;