@webpieces/nx-webpieces-rules 0.3.333 → 0.3.335

package/src/lib/graph-names.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Graph Names
+ *
+ * Shared helper for turning a scoped project name into the short display name
+ * used everywhere in the visualization (graph box titles, the lock-control
+ * options, and the responsibilities cards). Kept in its own class so both
+ * GraphVisualizer and ResponsibilitiesRenderer can depend on it without a
+ * circular dependency between them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphNames = void 0;
+class GraphNames {
+    /**
+     * Remove scope from name for display
+     * '@scope/name' → 'name'
+     * 'name' → 'name'
+     */
+    getShortName(name) {
+        return name.includes('/') ? name.split('/').pop() : name;
+    }
+}
+exports.GraphNames = GraphNames;
+//# sourceMappingURL=graph-names.js.map

package/src/lib/graph-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-names.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-names.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,MAAa,UAAU;IACnB;;;;OAIG;IACH,YAAY,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,CAAC;CACJ;AATD,gCASC","sourcesContent":["/**\n * Graph Names\n *\n * Shared helper for turning a scoped project name into the short display name\n * used everywhere in the visualization (graph box titles, the lock-control\n * options, and the responsibilities cards). Kept in its own class so both\n * GraphVisualizer and ResponsibilitiesRenderer can depend on it without a\n * circular dependency between them.\n */\n\nexport class GraphNames {\n    /**\n     * Remove scope from name for display\n     * '@scope/name' → 'name'\n     * 'name' → 'name'\n     */\n    getShortName(name: string): string {\n        return name.includes('/') ? name.split('/').pop()! : name;\n    }\n}\n"]}

package/src/lib/graph-responsibilities.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Responsibilities Section
+ *
+ * Renders every module's full `responsibilities.md` as a collapsible card below
+ * the dependency graph in architecture/dependencies.html. Cards are ordered by
+ * dependency level HIGH → LOW (top-level apps first, deepest libs last) so a
+ * reader scrolls from the runnable servers/clients down into the libraries.
+ *
+ * Each card carries `data-node="<shortName>"` matching the graph box's title, so
+ * the page script can filter the list to just the locked box's chain (see
+ * graph-visualizer.client.js). The summary paragraph is the `shortDescription`
+ * already on each graph entry; the expanded body is the rendered markdown file.
+ */
+import type { EnhancedGraph } from './graph-sorter';
+export declare class ResponsibilitiesRenderer {
+    private readonly names;
+    /**
+     * Build the responsibilities section HTML: one collapsible card per module,
+     * sorted by level descending (tie-break by name ascending). Returned as a
+     * <section> that GraphVisualizer injects below the graph.
+     */
+    generateSection(graph: EnhancedGraph, workspaceRoot: string): string;
+    private renderCard;
+    /**
+     * Read a module's responsibilities.md body. Generation already guarantees the
+     * file exists (metadata validation throws otherwise); a fallback line guards
+     * the edge case where the graph JSON is stale relative to disk.
+     */
+    private readBody;
+    /**
+     * Minimal markdown → HTML for a responsibilities.md body. Handles ATX headings
+     * (`#`..`######`), `-`/`*` bullet lists, and blank-line-separated paragraphs.
+     * Everything is HTML-escaped first; only a small inline set is re-marked. This
+     * is deliberately tiny — responsibilities.md files are short and structured,
+     * and the repo has no markdown dependency.
+     */
+    private renderMarkdown;
+    private renderLine;
+    /**
+     * Render inline markdown spans within an already HTML-escaped line: `code` →
+     * <code>, **bold** → <strong>, *italic* → <em>.
+     */
+    private renderInline;
+    /**
+     * Escape a string for safe embedding in HTML text/attributes.
+     */
+    private escapeHtml;
+}

package/src/lib/graph-responsibilities.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * Responsibilities Section
+ *
+ * Renders every module's full `responsibilities.md` as a collapsible card below
+ * the dependency graph in architecture/dependencies.html. Cards are ordered by
+ * dependency level HIGH → LOW (top-level apps first, deepest libs last) so a
+ * reader scrolls from the runnable servers/clients down into the libraries.
+ *
+ * Each card carries `data-node="<shortName>"` matching the graph box's title, so
+ * the page script can filter the list to just the locked box's chain (see
+ * graph-visualizer.client.js). The summary paragraph is the `shortDescription`
+ * already on each graph entry; the expanded body is the rendered markdown file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResponsibilitiesRenderer = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const graph_names_1 = require("./graph-names");
+/**
+ * Mutable cursor state threaded through the markdown line renderer: whether we
+ * are currently inside an open `<ul>` (so the next blank line / heading / non-
+ * bullet closes it).
+ */
+class MarkdownListState {
+    inList = false;
+}
+class ResponsibilitiesRenderer {
+    names = new graph_names_1.GraphNames();
+    /**
+     * Build the responsibilities section HTML: one collapsible card per module,
+     * sorted by level descending (tie-break by name ascending). Returned as a
+     * <section> that GraphVisualizer injects below the graph.
+     */
+    generateSection(graph, workspaceRoot) {
+        const projects = Object.keys(graph);
+        projects.sort((a, b) => {
+            const levelDiff = graph[b].level - graph[a].level;
+            if (levelDiff !== 0)
+                return levelDiff;
+            return a.localeCompare(b);
+        });
+        const cards = [];
+        for (const project of projects) {
+            cards.push(this.renderCard(project, graph[project], workspaceRoot));
+        }
+        return (`<section id="wp-responsibilities">` +
+            `<h2>Responsibilities (level high → low)</h2>` +
+            `<p class="hint">Lock a box above to narrow this list to just that box's dependency chain.</p>` +
+            cards.join('\n') +
+            `</section>`);
+    }
+    renderCard(project, entry, workspaceRoot) {
+        const shortName = this.names.getShortName(project);
+        const summary = entry.shortDescription ?? '';
+        const summaryHtml = summary ? ` — ${this.escapeHtml(summary)}` : '';
+        const body = this.readBody(entry, workspaceRoot);
+        return (`<details class="wp-resp-card" data-node="${this.escapeHtml(shortName)}">` +
+            `<summary><span class="wp-resp-level">L${entry.level}</span> ` +
+            `<strong>${this.escapeHtml(shortName)}</strong>${summaryHtml}</summary>` +
+            `<div class="wp-resp-body">${body}</div>` +
+            `</details>`);
+    }
+    /**
+     * Read a module's responsibilities.md body. Generation already guarantees the
+     * file exists (metadata validation throws otherwise); a fallback line guards
+     * the edge case where the graph JSON is stale relative to disk.
+     */
+    readBody(entry, workspaceRoot) {
+        const file = entry.responsibilitiesFile;
+        if (!file)
+            return '<p><em>No responsibilities.md recorded for this module.</em></p>';
+        const absolutePath = path.join(workspaceRoot, file);
+        if (!fs.existsSync(absolutePath)) {
+            return `<p><em>Missing ${this.escapeHtml(file)}.</em></p>`;
+        }
+        return this.renderMarkdown(fs.readFileSync(absolutePath, 'utf-8'));
+    }
+    /**
+     * Minimal markdown → HTML for a responsibilities.md body. Handles ATX headings
+     * (`#`..`######`), `-`/`*` bullet lists, and blank-line-separated paragraphs.
+     * Everything is HTML-escaped first; only a small inline set is re-marked. This
+     * is deliberately tiny — responsibilities.md files are short and structured,
+     * and the repo has no markdown dependency.
+     */
+    renderMarkdown(markdown) {
+        const out = [];
+        const state = new MarkdownListState();
+        for (const rawLine of markdown.split('\n')) {
+            this.renderLine(rawLine.trim(), out, state);
+        }
+        if (state.inList)
+            out.push('</ul>');
+        return out.join('\n');
+    }
+    renderLine(line, out, state) {
+        const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+        const bullet = /^[-*]\s+(.*)$/.exec(line);
+        if (line.length === 0) {
+            if (state.inList) {
+                out.push('</ul>');
+                state.inList = false;
+            }
+            return;
+        }
+        if (heading) {
+            if (state.inList) {
+                out.push('</ul>');
+                state.inList = false;
+            }
+            const level = Math.min(heading[1].length + 3, 6); // # → h4, ## → h5, deeper → h6
+            out.push(`<h${level}>${this.renderInline(this.escapeHtml(heading[2]))}</h${level}>`);
+            return;
+        }
+        if (bullet) {
+            if (!state.inList) {
+                out.push('<ul>');
+                state.inList = true;
+            }
+            out.push(`<li>${this.renderInline(this.escapeHtml(bullet[1]))}</li>`);
+            return;
+        }
+        if (state.inList) {
+            out.push('</ul>');
+            state.inList = false;
+        }
+        out.push(`<p>${this.renderInline(this.escapeHtml(line))}</p>`);
+    }
+    /**
+     * Render inline markdown spans within an already HTML-escaped line: `code` →
+     * <code>, **bold** → <strong>, *italic* → <em>.
+     */
+    renderInline(escaped) {
+        return escaped
+            .replace(/`([^`]+)`/g, '<code>$1</code>')
+            .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+            .replace(/(^|[^*])\*([^*]+)\*/g, '$1<em>$2</em>');
+    }
+    /**
+     * Escape a string for safe embedding in HTML text/attributes.
+     */
+    escapeHtml(text) {
+        return text
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;');
+    }
+}
+exports.ResponsibilitiesRenderer = ResponsibilitiesRenderer;
+//# sourceMappingURL=graph-responsibilities.js.map

package/src/lib/graph-responsibilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-responsibilities.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-responsibilities.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Responsibilities Section\n *\n * Renders every module's full `responsibilities.md` as a collapsible card below\n * the dependency graph in architecture/dependencies.html. Cards are ordered by\n * dependency level HIGH → LOW (top-level apps first, deepest libs last) so a\n * reader scrolls from the runnable servers/clients down into the libraries.\n *\n * Each card carries `data-node=\"<shortName>\"` matching the graph box's title, so\n * the page script can filter the list to just the locked box's chain (see\n * graph-visualizer.client.js). The summary paragraph is the `shortDescription`\n * already on each graph entry; the expanded body is the rendered markdown file.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { EnhancedGraph, GraphEntry } from './graph-sorter';\nimport { GraphNames } from './graph-names';\n\n/**\n * Mutable cursor state threaded through the markdown line renderer: whether we\n * are currently inside an open `<ul>` (so the next blank line / heading / non-\n * bullet closes it).\n */\nclass MarkdownListState {\n    inList = false;\n}\n\nexport class ResponsibilitiesRenderer {\n    private readonly names = new GraphNames();\n\n    /**\n     * Build the responsibilities section HTML: one collapsible card per module,\n     * sorted by level descending (tie-break by name ascending). Returned as a\n     * <section> that GraphVisualizer injects below the graph.\n     */\n    generateSection(graph: EnhancedGraph, workspaceRoot: string): string {\n        const projects = Object.keys(graph);\n        projects.sort((a: string, b: string): number => {\n            const levelDiff = graph[b].level - graph[a].level;\n            if (levelDiff !== 0) return levelDiff;\n            return a.localeCompare(b);\n        });\n\n        const cards: string[] = [];\n        for (const project of projects) {\n            cards.push(this.renderCard(project, graph[project], workspaceRoot));\n        }\n\n        return (\n            `<section id=\"wp-responsibilities\">` +\n            `<h2>Responsibilities (level high → low)</h2>` +\n            `<p class=\"hint\">Lock a box above to narrow this list to just that box's dependency chain.</p>` +\n            cards.join('\\n') +\n            `</section>`\n        );\n    }\n\n    private renderCard(project: string, entry: GraphEntry, workspaceRoot: string): string {\n        const shortName = this.names.getShortName(project);\n        const summary = entry.shortDescription ?? '';\n        const summaryHtml = summary ? ` — ${this.escapeHtml(summary)}` : '';\n        const body = this.readBody(entry, workspaceRoot);\n        return (\n            `<details class=\"wp-resp-card\" data-node=\"${this.escapeHtml(shortName)}\">` +\n            `<summary><span class=\"wp-resp-level\">L${entry.level}</span> ` +\n            `<strong>${this.escapeHtml(shortName)}</strong>${summaryHtml}</summary>` +\n            `<div class=\"wp-resp-body\">${body}</div>` +\n            `</details>`\n        );\n    }\n\n    /**\n     * Read a module's responsibilities.md body. Generation already guarantees the\n     * file exists (metadata validation throws otherwise); a fallback line guards\n     * the edge case where the graph JSON is stale relative to disk.\n     */\n    private readBody(entry: GraphEntry, workspaceRoot: string): string {\n        const file = entry.responsibilitiesFile;\n        if (!file) return '<p><em>No responsibilities.md recorded for this module.</em></p>';\n        const absolutePath = path.join(workspaceRoot, file);\n        if (!fs.existsSync(absolutePath)) {\n            return `<p><em>Missing ${this.escapeHtml(file)}.</em></p>`;\n        }\n        return this.renderMarkdown(fs.readFileSync(absolutePath, 'utf-8'));\n    }\n\n    /**\n     * Minimal markdown → HTML for a responsibilities.md body. Handles ATX headings\n     * (`#`..`######`), `-`/`*` bullet lists, and blank-line-separated paragraphs.\n     * Everything is HTML-escaped first; only a small inline set is re-marked. This\n     * is deliberately tiny — responsibilities.md files are short and structured,\n     * and the repo has no markdown dependency.\n     */\n    private renderMarkdown(markdown: string): string {\n        const out: string[] = [];\n        const state = new MarkdownListState();\n        for (const rawLine of markdown.split('\\n')) {\n            this.renderLine(rawLine.trim(), out, state);\n        }\n        if (state.inList) out.push('</ul>');\n        return out.join('\\n');\n    }\n\n    private renderLine(line: string, out: string[], state: MarkdownListState): void {\n        const heading = /^(#{1,6})\\s+(.*)$/.exec(line);\n        const bullet = /^[-*]\\s+(.*)$/.exec(line);\n        if (line.length === 0) {\n            if (state.inList) { out.push('</ul>'); state.inList = false; }\n            return;\n        }\n        if (heading) {\n            if (state.inList) { out.push('</ul>'); state.inList = false; }\n            const level = Math.min(heading[1].length + 3, 6); // # → h4, ## → h5, deeper → h6\n            out.push(`<h${level}>${this.renderInline(this.escapeHtml(heading[2]))}</h${level}>`);\n            return;\n        }\n        if (bullet) {\n            if (!state.inList) { out.push('<ul>'); state.inList = true; }\n            out.push(`<li>${this.renderInline(this.escapeHtml(bullet[1]))}</li>`);\n            return;\n        }\n        if (state.inList) { out.push('</ul>'); state.inList = false; }\n        out.push(`<p>${this.renderInline(this.escapeHtml(line))}</p>`);\n    }\n\n    /**\n     * Render inline markdown spans within an already HTML-escaped line: `code` →\n     * <code>, **bold** → <strong>, *italic* → <em>.\n     */\n    private renderInline(escaped: string): string {\n        return escaped\n            .replace(/`([^`]+)`/g, '<code>$1</code>')\n            .replace(/\\*\\*([^*]+)\\*\\*/g, '<strong>$1</strong>')\n            .replace(/(^|[^*])\\*([^*]+)\\*/g, '$1<em>$2</em>');\n    }\n\n    /**\n     * Escape a string for safe embedding in HTML text/attributes.\n     */\n    private escapeHtml(text: string): string {\n        return text\n            .replace(/&/g, '&amp;')\n            .replace(/</g, '&lt;')\n            .replace(/>/g, '&gt;')\n            .replace(/\"/g, '&quot;');\n    }\n}\n"]}

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

@@ -6,6 +6,7 @@
  * 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
  */
+import type { ProjectApiRelations } from './api-usage/api-relations';
 /**
  * Graph entry with level metadata plus AI-oriented metadata filled in by
  * enrichGraph() (lib/graph-metadata.ts) before the graph is saved:
@@ -17,6 +18,9 @@
  *  - responsibilitiesFile: repo-relative path to the FULL responsibilities doc
  *  - designFile: repo-relative path to the generated DI design.json (only for
  *    project.json projects)
+ *  - apiRelations: for each api-lib in `dependsOn`, WHY the edge exists — the
+ *    APIs this project implements (serves) and/or uses (calls), each with its
+ *    transport (rpc | pubsub). Derived by scanning source (see api-usage/).
  */
 export interface GraphEntry {
     level: number;
@@ -26,6 +30,7 @@ export interface GraphEntry {
     shortDescription?: string;
     responsibilitiesFile?: string;
     designFile?: string;
+    apiRelations?: ProjectApiRelations;
 }
 /**
  * Enhanced graph format with level information

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

@@ -1 +1 @@
-{"version":3,"file":"graph-sorter.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/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 plus AI-oriented metadata filled in by\n * enrichGraph() (lib/graph-metadata.ts) before the graph is saved:\n *  - framework: the project's libType — the SET of runtime environments it is\n *    validated to run in, drawn from browser | react | angular | node | express\n *    (e.g. [\"browser\",\"node\"]); from its `framework:` nx tags (source of truth)\n *    or inferred from package.json deps\n *  - shortDescription: summary extracted from the project's responsibilities.md\n *  - responsibilitiesFile: repo-relative path to the FULL responsibilities doc\n *  - designFile: repo-relative path to the generated DI design.json (only for\n *    project.json projects)\n */\nexport interface GraphEntry {\n    level: number;\n    dependsOn: string[];\n    framework?: string[];\n    role?: string;\n    shortDescription?: string;\n    responsibilitiesFile?: string;\n    designFile?: 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"]}
+{"version":3,"file":"graph-sorter.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/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\nimport type { ProjectApiRelations } from './api-usage/api-relations';\n\n/**\n * Graph entry with level metadata plus AI-oriented metadata filled in by\n * enrichGraph() (lib/graph-metadata.ts) before the graph is saved:\n *  - framework: the project's libType — the SET of runtime environments it is\n *    validated to run in, drawn from browser | react | angular | node | express\n *    (e.g. [\"browser\",\"node\"]); from its `framework:` nx tags (source of truth)\n *    or inferred from package.json deps\n *  - shortDescription: summary extracted from the project's responsibilities.md\n *  - responsibilitiesFile: repo-relative path to the FULL responsibilities doc\n *  - designFile: repo-relative path to the generated DI design.json (only for\n *    project.json projects)\n *  - apiRelations: for each api-lib in `dependsOn`, WHY the edge exists — the\n *    APIs this project implements (serves) and/or uses (calls), each with its\n *    transport (rpc | pubsub). Derived by scanning source (see api-usage/).\n */\nexport interface GraphEntry {\n    level: number;\n    dependsOn: string[];\n    framework?: string[];\n    role?: string;\n    shortDescription?: string;\n    responsibilitiesFile?: string;\n    designFile?: string;\n    apiRelations?: ProjectApiRelations;\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/src/lib/graph-visualizer.client.js

@@ -0,0 +1,127 @@
+/*
+ * Browser-side script for architecture/dependencies.html (inlined into a <script>
+ * tag by graph-visualizer.ts, which replaces the __DOT__ placeholder with the
+ * JSON-encoded Graphviz DOT). Kept as a plain .js asset — NOT a TypeScript
+ * template literal — so the dim/highlight/lock logic can define ordinary browser
+ * functions without tripping the TypeScript lint rules that scan .ts template
+ * strings. Copied into dist by the build's assets glob and read via readFileSync.
+ *
+ * After viz.js renders the SVG, wireHoverHighlight indexes nodes/edges and:
+ *   - hovering a box dims the rest and lights its full ancestor+descendant chain;
+ *   - the #wp-lock dropdown LOCKS one box's chain (dim persists on mouse-leave)
+ *     and filters the responsibilities cards below the graph to just that chain.
+ *     "All" (empty value) clears the lock and shows every card.
+ */
+(function () {
+    var dot = __DOT__;
+    var viz = new Viz();
+    viz.renderSVGElement(dot)
+        .then(function (element) {
+            document.getElementById('graph').appendChild(element);
+            wireHoverHighlight(element);
+        })
+        .catch(function (err) {
+            console.error(err);
+            document.getElementById('graph').innerHTML = '<pre>' + err + '</pre>';
+        });
+
+    function wireHoverHighlight(svg) {
+        var nodeByName = new Map();
+        svg.querySelectorAll('g.node').forEach(function (g) {
+            var t = g.querySelector('title');
+            if (t) nodeByName.set(t.textContent.trim(), g);
+        });
+        // Directed adjacency: in* = entering (up/ancestors), out* = leaving (down/deps).
+        var inEdges = new Map(), outEdges = new Map(), inNodes = new Map(), outNodes = new Map();
+        function ensure(map, key) {
+            var v = map.get(key);
+            if (!v) { v = new Set(); map.set(key, v); }
+            return v;
+        }
+        svg.querySelectorAll('g.edge').forEach(function (edge) {
+            var t = edge.querySelector('title');
+            if (!t) return;
+            var idx = t.textContent.indexOf('->');
+            if (idx < 0) return;
+            var from = t.textContent.slice(0, idx).trim();
+            var to = t.textContent.slice(idx + 2).trim();
+            ensure(outEdges, from).add(edge);
+            ensure(inEdges, to).add(edge);
+            ensure(outNodes, from).add(to);
+            ensure(inNodes, to).add(from);
+        });
+        function clear() {
+            svg.classList.remove('wp-dim');
+            svg.querySelectorAll('.wp-focus, .wp-neighbor, .wp-hl').forEach(function (el) {
+                el.classList.remove('wp-focus', 'wp-neighbor', 'wp-hl');
+            });
+        }
+        function highlight(name, focusEl) {
+            clear();
+            svg.classList.add('wp-dim');
+            focusEl.classList.add('wp-focus');
+            // Transitively light ancestors (up) then descendants (down): edges
+            // reached -> wp-hl, boxes -> wp-neighbor. visited guards cycles.
+            [[inNodes, inEdges], [outNodes, outEdges]].forEach(function (dir) {
+                var visited = new Set();
+                var stack = [name];
+                while (stack.length) {
+                    var cur = stack.pop();
+                    (dir[1].get(cur) || []).forEach(function (e) { e.classList.add('wp-hl'); });
+                    (dir[0].get(cur) || []).forEach(function (next) {
+                        if (visited.has(next)) return;
+                        visited.add(next);
+                        stack.push(next);
+                        var g = nodeByName.get(next);
+                        if (g) g.classList.add('wp-neighbor');
+                    });
+                }
+            });
+        }
+        // locked = the box the dropdown pinned (or null). Hover still works on top
+        // of a lock; leaving a box restores the locked view instead of clearing, so
+        // the pinned subgraph stays visible as you scroll to its responsibilities.
+        var locked = null;
+        function relight() {
+            if (locked) {
+                var lg = nodeByName.get(locked);
+                if (lg) highlight(locked, lg);
+            } else {
+                clear();
+            }
+        }
+        nodeByName.forEach(function (g, name) {
+            g.addEventListener('mouseenter', function () { highlight(name, g); });
+            g.addEventListener('mouseleave', relight);
+        });
+
+        // Filter the responsibilities cards to the locked box's chain by reading the
+        // .wp-focus/.wp-neighbor classes highlight() just set — no second graph walk.
+        var lockSelect = document.getElementById('wp-lock');
+        function filterCards() {
+            var lit = new Set();
+            if (locked) {
+                svg.querySelectorAll('.wp-focus, .wp-neighbor').forEach(function (el) {
+                    var t = el.querySelector('title');
+                    if (t) lit.add(t.textContent.trim());
+                });
+            }
+            document.querySelectorAll('.wp-resp-card').forEach(function (card) {
+                var nm = card.getAttribute('data-node');
+                card.classList.toggle('wp-hidden', !(!locked || lit.has(nm)));
+            });
+        }
+        if (lockSelect) {
+            lockSelect.addEventListener('change', function () {
+                locked = lockSelect.value || null;
+                if (locked) {
+                    var g = nodeByName.get(locked);
+                    if (g) highlight(locked, g);
+                } else {
+                    clear();
+                }
+                filterCards();
+            });
+        }
+    }
+})();

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

@@ -5,34 +5,94 @@
  * - DOT format (for Graphviz)
  * - Interactive HTML (using viz.js)
  *
- * Output files go to tmp/webpieces/ for easy viewing without committing.
+ * All behavior lives on the injectable GraphVisualizer class so webpieces DI +
+ * @DocumentDesign can wire it — module-scope functions are a dead end the DI
+ * graph can't reach.
  */
 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;
-interface VisualizationPaths {
+export declare class VisualizationPaths {
     htmlPath: string;
+    constructor(htmlPath: string);
+}
+export declare class GraphVisualizer {
+    private readonly names;
+    private readonly responsibilities;
+    /**
+     * Fill color for an env set — the color of the first env in the set that has
+     * a known color, else the default.
+     */
+    private frameworkColor;
+    /**
+     * Role border styling — fill stays keyed on framework; the border shows a
+     * project's ROLE at a glance. Server and client are the top-level runnable
+     * nodes, so they get bold, colored borders to stand out:
+     *   server       → thick GREEN border (a runnable server app)
+     *   client       → thick RED border   (a client app, e.g. angular)
+     *   designed-lib → bold border        (a library with a generated @DocumentDesign design)
+     *   lib / other  → plain thin border
+     */
+    private roleBorderAttrs;
+    /**
+     * Edge styling by API-relation kind (why the edge exists):
+     *   implements       → DASHED (a controller serves this api-lib's contract)
+     *   uses             → SOLID blue, thicker (a generated client calls it)
+     *   uses-implements  → DASHED purple, thicker (does both — implements some
+     *                      contracts of the api-lib, uses others)
+     *   plain lib (none) → the default thin solid arrow, unchanged.
+     * `kind` is undefined for every non-api-lib dependency edge.
+     */
+    private edgeAttrs;
+    /**
+     * Click-through href for a node: the project's committed design.html, made
+     * relative to architecture/dependencies.html. Returns null when the project
+     * has no generated DI design (no design.json → no clickable design page).
+     */
+    private designHtmlHref;
+    /**
+     * Generate Graphviz DOT format from the graph
+     */
+    generateDot(graph: EnhancedGraph, title?: string): string;
+    private dotNodes;
+    private dotEdges;
+    /**
+     * Generate interactive HTML with embedded SVG using viz.js
+     */
+    generateHTML(dot: string, title?: string, lockControl?: string, responsibilitiesHtml?: string): string;
+    /**
+     * The lock control (a single-select dropdown, rendered above the legend).
+     * Picking a module LOCKS the graph into that box's hover view — its full
+     * ancestor + descendant chain stays lit while everything else stays dimmed —
+     * and narrows the responsibilities list below the graph to just that chain.
+     * The first option, "All", is the default and clears the lock. Hover still
+     * works on top of a lock; leaving a box returns to the locked view.
+     *
+     * Options are ordered by level DESCENDING to match the responsibilities cards.
+     */
+    lockControl(graph: EnhancedGraph): string;
+    private styles;
+    private componentStyles;
+    private legend;
+    /**
+     * The page script. The browser code lives in graph-visualizer.client.js (a
+     * plain .js asset, NOT a TS template literal) so its dim/highlight/lock
+     * functions can be ordinary browser functions — the TS lint rules that scan
+     * .ts template strings would otherwise forbid them, and browser JS cannot
+     * carry TS return annotations. We inline it and substitute the DOT.
+     */
+    private script;
+    /**
+     * Write the committed architecture visualization to
+     * architecture/dependencies.html, next to dependencies.json.
+     *
+     * This is a checked-in artifact, regenerated deterministically by
+     * architecture:generate so the boxes stay clickable into each project's
+     * design.html. The DOT is embedded in the HTML (rendered client-side by
+     * viz.js). Output is deterministic (sorted graph in → same bytes out) so git
+     * only shows a diff when the architecture actually changed.
+     */
+    writeVisualization(graph: EnhancedGraph, workspaceRoot: string, title?: string): VisualizationPaths;
+    /**
+     * Open the HTML visualization in the default browser
+     */
+    openVisualization(htmlPath: string): boolean;
 }
-/**
- * Write the committed architecture visualization to architecture/dependencies.html,
- * next to dependencies.json.
- *
- * This is a checked-in artifact, regenerated deterministically by
- * architecture:generate so the boxes stay clickable into each project's
- * design.html. The DOT is embedded in the HTML (rendered client-side by
- * viz.js), so no separate .dot file is committed — same as design.html. Output
- * is deterministic (sorted graph in → same bytes out) so git only shows a diff
- * when the architecture actually changed.
- */
-export declare function writeVisualization(graph: EnhancedGraph, workspaceRoot: string, title?: string): VisualizationPaths;
-/**
- * Open the HTML visualization in the default browser
- */
-export declare function openVisualization(htmlPath: string): boolean;
-export {};