@webpieces/nx-webpieces-rules 0.4.853 → 0.4.855

package/src/lib/graph-filter.client.js

@@ -0,0 +1,190 @@
+"use strict";
+/** Plain browser helpers shared by architecture and runtime; no CommonJS imports. */
+class WpGraphChain {
+    model;
+    inNodes = new Map();
+    outNodes = new Map();
+    constructor(model) {
+        this.model = model;
+        const ids = new Set(model.nodes.map((node) => node.id));
+        for (const edge of model.edges) {
+            if (!ids.has(edge.from) || !ids.has(edge.to))
+                continue;
+            this.add(this.outNodes, edge.from, edge.to);
+            this.add(this.inNodes, edge.to, edge.from);
+        }
+    }
+    add(map, from, to) {
+        if (!map.has(from))
+            map.set(from, new Set());
+        map.get(from)?.add(to);
+    }
+    nodes(anchor) {
+        const retained = new Set();
+        if (!this.model.nodes.some((node) => node.id === anchor))
+            return retained;
+        for (const direction of [this.inNodes, this.outNodes]) {
+            const visited = new Set([anchor]);
+            const stack = [anchor];
+            while (stack.length > 0) {
+                const id = stack.pop();
+                retained.add(id);
+                for (const next of direction.get(id) ?? []) {
+                    if (visited.has(next))
+                        continue;
+                    visited.add(next);
+                    stack.push(next);
+                }
+            }
+        }
+        return retained;
+    }
+}
+class WpRenderBand {
+    level;
+    nodeNames;
+    constructor(level, nodeNames) {
+        this.level = level;
+        this.nodeNames = nodeNames;
+    }
+}
+/** Original records plus fresh ranks: removed nodes cannot reappear via a rank/edge. */
+class WpFilteredDot {
+    model;
+    constructor(model) {
+        this.model = model;
+    }
+    render(retained) {
+        const nodes = this.model.nodes.filter((node) => retained.has(node.id));
+        const edges = this.model.edges.filter((edge) => retained.has(edge.from) && retained.has(edge.to));
+        const bands = this.model.bands
+            .map((band) => new WpRenderBand(band.level, band.nodeNames.filter((id) => retained.has(id))))
+            .filter((band) => band.nodeNames.length > 0);
+        return (this.model.header +
+            nodes.map((node) => node.dot).join('') +
+            this.bandDot(bands) +
+            edges.map((edge) => edge.dot).join('') +
+            this.model.footer);
+    }
+    bandDot(bands) {
+        const nodeAttrs = '[style=invis, shape=point, width=0.01, height=0.01, label="", class="wp-layout"]';
+        const edgeAttrs = '[style=invis, class="wp-layout"]';
+        let dot = '';
+        for (const band of bands) {
+            const anchor = `__wp_layout_L${band.level}`;
+            dot += `  "${anchor}" ${nodeAttrs};\n  { rank=same; "${anchor}"; `;
+            dot += band.nodeNames.map((id) => `${JSON.stringify(id)}; `).join('') + '}\n';
+        }
+        for (let i = 0; i + 1 < bands.length; i++) {
+            const upper = bands[i];
+            const lower = bands[i + 1];
+            const from = `__wp_layout_L${upper.level}`;
+            const to = `__wp_layout_L${lower.level}`;
+            if (upper.nodeNames.length <= 10 && lower.nodeNames.length <= 10) {
+                dot += `  "${from}" -> "${to}" ${edgeAttrs};\n`;
+                continue;
+            }
+            const spacer = `__wp_layout_spacer_L${upper.level}_L${lower.level}`;
+            dot += `  "${spacer}" ${nodeAttrs};\n  { rank=same; "${spacer}"; }\n`;
+            dot += `  "${from}" -> "${spacer}" ${edgeAttrs};\n  "${spacer}" -> "${to}" ${edgeAttrs};\n`;
+        }
+        return dot;
+    }
+}
+/** Page-owned state survives replacements; rendering failures leave the usable SVG intact. */
+class WpFilterPage {
+    model;
+    chain;
+    locked = null;
+    anchor = null;
+    retained;
+    viz = null;
+    constructor(model) {
+        this.model = model;
+        this.chain = new WpGraphChain(model);
+        this.retained = new Set(model.nodes.map((node) => node.id));
+    }
+    render() {
+        document
+            .getElementById('wp-filter-off')
+            ?.addEventListener('click', () => this.filter(null));
+        this.wireControls();
+        Viz.instance()
+            .then((viz) => {
+            this.viz = viz;
+            this.filter(null);
+        })
+            // webpieces-disable no-any-unknown -- promise rejections may carry any JavaScript value
+            .catch((err) => this.error(err instanceof Error ? err : new Error(String(err))));
+    }
+    captureBinding(_svg) { return () => { }; }
+    wireControls() { }
+    prepareSvg(_svg) { }
+    filterItem(name) {
+        return new WpNodeMenuItem(this.anchor === null ? 'Filter Unconnected' : 'Turn off Filter', () => this.filter(this.anchor === null ? name : null));
+    }
+    filter(anchor) {
+        if (this.viz === null)
+            return;
+        const host = document.getElementById('graph');
+        if (host === null)
+            return;
+        const retained = anchor === null
+            ? new Set(this.model.nodes.map((node) => node.id))
+            : this.chain.nodes(anchor);
+        const previousAnchor = this.anchor;
+        const previousRetained = this.retained;
+        const previousSvg = host.querySelector('svg');
+        const rollback = this.captureBinding(previousSvg);
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- browser transaction restores the previous usable graph on failure
+        try {
+            const dot = anchor === null
+                ? this.model.fullDot
+                : new WpFilteredDot(this.model).render(retained);
+            const svg = this.viz.renderSVGElement(dot);
+            this.prepareSvg(svg);
+            WpNodeMenu.close();
+            this.anchor = anchor;
+            this.retained = retained;
+            host.replaceChildren(svg);
+            this.wireSvg(svg);
+            this.indicator();
+            this.error(null);
+            // webpieces-disable no-any-unknown -- JavaScript may throw any value at this browser boundary
+        }
+        catch (err) {
+            //const error = toError(err);
+            this.anchor = previousAnchor;
+            this.retained = previousRetained;
+            if (previousSvg !== null)
+                host.replaceChildren(previousSvg);
+            else
+                host.replaceChildren();
+            rollback();
+            this.error(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    indicator() {
+        const status = document.getElementById('wp-filter-status');
+        const label = document.getElementById('wp-filter-anchor');
+        if (status !== null)
+            status.hidden = this.anchor === null;
+        if (label !== null)
+            label.textContent = this.anchor;
+        if (this.anchor !== null)
+            document.getElementById('wp-filter-off')?.focus();
+        else
+            document.querySelector('#graph g.wp-node-clickable')?.focus();
+    }
+    error(err) {
+        const el = document.getElementById('wp-graph-error');
+        if (el === null)
+            return;
+        el.hidden = err === null;
+        el.textContent =
+            err === null
+                ? ''
+                : `Graph rendering failed: ${err.message}. Try Turn off Filter or reload the page.`;
+    }
+}
+//# sourceMappingURL=graph-filter.client.js.map

package/src/lib/graph-filter.client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-filter.client.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-filter.client.ts"],"names":[],"mappings":"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","sourcesContent":["/** Plain browser helpers shared by architecture and runtime; no CommonJS imports. */\nclass WpGraphChain {\n    readonly inNodes = new Map<string, Set<string>>();\n    readonly outNodes = new Map<string, Set<string>>();\n\n    constructor(private readonly model: RenderModelJson) {\n        const ids = new Set(model.nodes.map((node) => node.id));\n        for (const edge of model.edges) {\n            if (!ids.has(edge.from) || !ids.has(edge.to)) continue;\n            this.add(this.outNodes, edge.from, edge.to);\n            this.add(this.inNodes, edge.to, edge.from);\n        }\n    }\n\n    private add(map: Map<string, Set<string>>, from: string, to: string): void {\n        if (!map.has(from)) map.set(from, new Set());\n        map.get(from)?.add(to);\n    }\n\n    nodes(anchor: string): Set<string> {\n        const retained = new Set<string>();\n        if (!this.model.nodes.some((node) => node.id === anchor)) return retained;\n        for (const direction of [this.inNodes, this.outNodes]) {\n            const visited = new Set([anchor]);\n            const stack = [anchor];\n            while (stack.length > 0) {\n                const id = stack.pop() as string;\n                retained.add(id);\n                for (const next of direction.get(id) ?? []) {\n                    if (visited.has(next)) continue;\n                    visited.add(next);\n                    stack.push(next);\n                }\n            }\n        }\n        return retained;\n    }\n}\n\nclass WpRenderBand {\n    constructor(\n        readonly level: number,\n        readonly nodeNames: string[],\n    ) {}\n}\n\n/** Original records plus fresh ranks: removed nodes cannot reappear via a rank/edge. */\nclass WpFilteredDot {\n    constructor(private readonly model: RenderModelJson) {}\n\n    render(retained: Set<string>): string {\n        const nodes = this.model.nodes.filter((node) => retained.has(node.id));\n        const edges = this.model.edges.filter(\n            (edge) => retained.has(edge.from) && retained.has(edge.to),\n        );\n        const bands = this.model.bands\n            .map(\n                (band) =>\n                    new WpRenderBand(\n                        band.level,\n                        band.nodeNames.filter((id) => retained.has(id)),\n                    ),\n            )\n            .filter((band) => band.nodeNames.length > 0);\n        return (\n            this.model.header +\n            nodes.map((node) => node.dot).join('') +\n            this.bandDot(bands) +\n            edges.map((edge) => edge.dot).join('') +\n            this.model.footer\n        );\n    }\n\n    private bandDot(bands: WpRenderBand[]): string {\n        const nodeAttrs =\n            '[style=invis, shape=point, width=0.01, height=0.01, label=\"\", class=\"wp-layout\"]';\n        const edgeAttrs = '[style=invis, class=\"wp-layout\"]';\n        let dot = '';\n        for (const band of bands) {\n            const anchor = `__wp_layout_L${band.level}`;\n            dot += `  \"${anchor}\" ${nodeAttrs};\\n  { rank=same; \"${anchor}\"; `;\n            dot += band.nodeNames.map((id) => `${JSON.stringify(id)}; `).join('') + '}\\n';\n        }\n        for (let i = 0; i + 1 < bands.length; i++) {\n            const upper = bands[i];\n            const lower = bands[i + 1];\n            const from = `__wp_layout_L${upper.level}`;\n            const to = `__wp_layout_L${lower.level}`;\n            if (upper.nodeNames.length <= 10 && lower.nodeNames.length <= 10) {\n                dot += `  \"${from}\" -> \"${to}\" ${edgeAttrs};\\n`;\n                continue;\n            }\n            const spacer = `__wp_layout_spacer_L${upper.level}_L${lower.level}`;\n            dot += `  \"${spacer}\" ${nodeAttrs};\\n  { rank=same; \"${spacer}\"; }\\n`;\n            dot += `  \"${from}\" -> \"${spacer}\" ${edgeAttrs};\\n  \"${spacer}\" -> \"${to}\" ${edgeAttrs};\\n`;\n        }\n        return dot;\n    }\n}\n\n/** Page-owned state survives replacements; rendering failures leave the usable SVG intact. */\nabstract class WpFilterPage {\n    protected readonly chain: WpGraphChain;\n    protected locked: string | null = null;\n    protected anchor: string | null = null;\n    protected retained: Set<string>;\n    private viz: VizInstance | null = null;\n\n    constructor(protected readonly model: RenderModelJson) {\n        this.chain = new WpGraphChain(model);\n        this.retained = new Set(model.nodes.map((node) => node.id));\n    }\n\n    render(): void {\n        document\n            .getElementById('wp-filter-off')\n            ?.addEventListener('click', () => this.filter(null));\n        this.wireControls();\n        Viz.instance()\n            .then((viz) => {\n                this.viz = viz;\n                this.filter(null);\n            })\n            // webpieces-disable no-any-unknown -- promise rejections may carry any JavaScript value\n            .catch((err: unknown): void =>\n                this.error(err instanceof Error ? err : new Error(String(err))),\n            );\n    }\n\n    protected captureBinding(_svg: SVGSVGElement | null): () => void { return (): void => {}; }\n    protected wireControls(): void {}\n    protected abstract wireSvg(svg: SVGSVGElement): void;\n    protected prepareSvg(_svg: SVGSVGElement): void {}\n\n    filterItem(name: string): WpNodeMenuItem {\n        return new WpNodeMenuItem(\n            this.anchor === null ? 'Filter Unconnected' : 'Turn off Filter',\n            () => this.filter(this.anchor === null ? name : null),\n        );\n    }\n\n    filter(anchor: string | null): void {\n        if (this.viz === null) return;\n        const host = document.getElementById('graph');\n        if (host === null) return;\n        const retained =\n            anchor === null\n                ? new Set(this.model.nodes.map((node) => node.id))\n                : this.chain.nodes(anchor);\n        const previousAnchor = this.anchor;\n        const previousRetained = this.retained;\n        const previousSvg = host.querySelector('svg');\n        const rollback = this.captureBinding(previousSvg);\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- browser transaction restores the previous usable graph on failure\n        try {\n            const dot =\n                anchor === null\n                    ? this.model.fullDot\n                    : new WpFilteredDot(this.model).render(retained);\n            const svg = this.viz.renderSVGElement(dot);\n            this.prepareSvg(svg);\n            WpNodeMenu.close();\n            this.anchor = anchor;\n            this.retained = retained;\n            host.replaceChildren(svg);\n            this.wireSvg(svg);\n            this.indicator();\n            this.error(null);\n            // webpieces-disable no-any-unknown -- JavaScript may throw any value at this browser boundary\n        } catch (err: unknown) {\n            //const error = toError(err);\n            this.anchor = previousAnchor;\n            this.retained = previousRetained;\n            if (previousSvg !== null) host.replaceChildren(previousSvg);\n            else host.replaceChildren();\n            rollback();\n            this.error(err instanceof Error ? err : new Error(String(err)));\n        }\n    }\n\n    private indicator(): void {\n        const status = document.getElementById('wp-filter-status');\n        const label = document.getElementById('wp-filter-anchor');\n        if (status !== null) status.hidden = this.anchor === null;\n        if (label !== null) label.textContent = this.anchor;\n        if (this.anchor !== null) document.getElementById('wp-filter-off')?.focus();\n        else document.querySelector<SVGGElement>('#graph g.wp-node-clickable')?.focus();\n    }\n\n    private error(err: Error | null): void {\n        const el = document.getElementById('wp-graph-error');\n        if (el === null) return;\n        el.hidden = err === null;\n        el.textContent =\n            err === null\n                ? ''\n                : `Graph rendering failed: ${err.message}. Try Turn off Filter or reload the page.`;\n    }\n}\n"]}

package/src/lib/graph-level-bands.d.ts

@@ -1,21 +1,3 @@
-/**
- * Level bands for the architecture graph.
- *
- * Every row of architecture/dependencies.html is ONE dependency level: the highest level on top,
- * descending as you read down, L0 — the foundation everything is built on — always last.
- *
- * `{ rank=same; ... }` alone does not deliver that, and assuming it did was the bug. It ties a
- * level's boxes to one row but says nothing about where that row goes, so graphviz derived each
- * row's position from the edges. A level containing a box with no visible edges — a leaf sdk, an
- * api-lib whose only consumers are hidden — is unconstrained, so it was placed at the top rank and
- * dragged its ENTIRE level up with it (verified against graphviz: that is what put the L0 sdks in
- * the top row, and what parked an L0 lib in the same row as the L6 servers).
- *
- * So the ordering is STATED here rather than inferred: one invisible anchor per band, sitting in
- * that band's rank set, chained top-to-bottom with invisible edges. Ranks are then a function of
- * level and nothing else. The anchors — never the real boxes — carry the chain, so no fake
- * dependency is ever drawn between two projects.
- */
 /**
  * One horizontal band of the graph: every visible project sharing a dependency level, plus the
  * invisible anchor that pins the band's vertical position.

package/src/lib/graph-level-bands.js

@@ -1,4 +1,7 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LevelBandLayout = exports.LevelBand = void 0;
+const dot_syntax_1 = require("./dot-syntax");
 /**
  * Level bands for the architecture graph.
  *
@@ -17,8 +20,6 @@
  * level and nothing else. The anchors — never the real boxes — carry the chain, so no fake
  * dependency is ever drawn between two projects.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LevelBandLayout = exports.LevelBand = void 0;
 /**
  * A band bigger than this gets a blank spacer band inserted next to it, so the long edges leaving a
  * crowded row have vertical room to fan out instead of cutting straight through the row below.
@@ -66,7 +67,7 @@ class LevelBandLayout {
             dot += `  "${band.anchorName()}" ${LAYOUT_NODE_ATTRS};\n`;
             dot += `  { rank=same; "${band.anchorName()}"; `;
             for (const name of band.nodeNames)
-                dot += `"${name}"; `;
+                dot += `"${(0, dot_syntax_1.dotValue)(name)}"; `;
             dot += '}\n';
         }
         for (let i = 0; i + 1 < bands.length; i++) {

package/src/lib/graph-level-bands.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-level-bands.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-level-bands.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAEH;;;;GAIG;AACH,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,YAAY,GAAG,WAAW,CAAC;AAEjC,wFAAwF;AACxF,MAAM,iBAAiB,GACnB,wEAAwE,YAAY,IAAI,CAAC;AAE7F,sFAAsF;AACtF,MAAM,iBAAiB,GAAG,wBAAwB,YAAY,IAAI,CAAC;AAEnE;;;GAGG;AACH,MAAa,SAAS;IAClB,KAAK,CAAS;IACd,0FAA0F;IAC1F,SAAS,CAAW;IAEpB,YAAY,KAAa,EAAE,SAAmB;QAC1C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;IAED,UAAU;QACN,OAAO,gBAAgB,IAAI,CAAC,KAAK,EAAE,CAAC;IACxC,CAAC;CACJ;AAbD,8BAaC;AAED,oFAAoF;AACpF,MAAa,eAAe;IACxB;;;;OAIG;IACH,GAAG,CAAC,KAAkB;QAClB,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACvB,GAAG,IAAI,MAAM,IAAI,CAAC,UAAU,EAAE,KAAK,iBAAiB,KAAK,CAAC;YAC1D,GAAG,IAAI,mBAAmB,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC;YACjD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS;gBAAE,GAAG,IAAI,IAAI,IAAI,KAAK,CAAC;YACxD,GAAG,IAAI,KAAK,CAAC;QACjB,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACK,OAAO,CAAC,KAAgB,EAAE,KAAgB;QAC9C,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,oBAAoB;eACtD,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,oBAAoB,CAAC;QACrD,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,MAAM,KAAK,CAAC,UAAU,EAAE,SAAS,KAAK,CAAC,UAAU,EAAE,KAAK,iBAAiB,KAAK,CAAC;QAC1F,CAAC;QACD,MAAM,MAAM,GAAG,uBAAuB,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,EAAE,CAAC;QACpE,OAAO,MAAM,MAAM,KAAK,iBAAiB,KAAK;cACxC,mBAAmB,MAAM,QAAQ;cACjC,MAAM,KAAK,CAAC,UAAU,EAAE,SAAS,MAAM,KAAK,iBAAiB,KAAK;cAClE,MAAM,MAAM,SAAS,KAAK,CAAC,UAAU,EAAE,KAAK,iBAAiB,KAAK,CAAC;IAC7E,CAAC;CACJ;AAtCD,0CAsCC","sourcesContent":["/**\n * Level bands for the architecture graph.\n *\n * Every row of architecture/dependencies.html is ONE dependency level: the highest level on top,\n * descending as you read down, L0 — the foundation everything is built on — always last.\n *\n * `{ rank=same; ... }` alone does not deliver that, and assuming it did was the bug. It ties a\n * level's boxes to one row but says nothing about where that row goes, so graphviz derived each\n * row's position from the edges. A level containing a box with no visible edges — a leaf sdk, an\n * api-lib whose only consumers are hidden — is unconstrained, so it was placed at the top rank and\n * dragged its ENTIRE level up with it (verified against graphviz: that is what put the L0 sdks in\n * the top row, and what parked an L0 lib in the same row as the L6 servers).\n *\n * So the ordering is STATED here rather than inferred: one invisible anchor per band, sitting in\n * that band's rank set, chained top-to-bottom with invisible edges. Ranks are then a function of\n * level and nothing else. The anchors — never the real boxes — carry the chain, so no fake\n * dependency is ever drawn between two projects.\n */\n\n/**\n * A band bigger than this gets a blank spacer band inserted next to it, so the long edges leaving a\n * crowded row have vertical room to fan out instead of cutting straight through the row below.\n * Eleven-plus boxes in a row is where that became unreadable in practice.\n */\nconst SPACER_MIN_BAND_SIZE = 10;\n\n/**\n * The class stamped on every node and edge that exists ONLY to pin the layout. Graphviz drops\n * `style=invis` elements from its SVG entirely, so nothing carrying this class reaches the page\n * today; the class is how the DOT tells the browser client which elements are scaffolding, and the\n * client skips them when indexing so an anchor can never be walked as a dependency.\n */\nconst LAYOUT_CLASS = 'wp-layout';\n\n/** Attributes shared by every invisible layout node (rank anchors and spacer bands). */\nconst LAYOUT_NODE_ATTRS =\n    `[style=invis, shape=point, width=0.01, height=0.01, label=\"\", class=\"${LAYOUT_CLASS}\"]`;\n\n/** Attributes for the invisible edges that force one band strictly above the next. */\nconst LAYOUT_EDGE_ATTRS = `[style=invis, class=\"${LAYOUT_CLASS}\"]`;\n\n/**\n * One horizontal band of the graph: every visible project sharing a dependency level, plus the\n * invisible anchor that pins the band's vertical position.\n */\nexport class LevelBand {\n    level: number;\n    /** Short names of the visible projects on this level, sorted for deterministic output. */\n    nodeNames: string[];\n\n    constructor(level: number, nodeNames: string[]) {\n        this.level = level;\n        this.nodeNames = nodeNames;\n    }\n\n    anchorName(): string {\n        return `__wp_layout_L${this.level}`;\n    }\n}\n\n/** Emits the DOT that pins each band to its own rank, in descending level order. */\nexport class LevelBandLayout {\n    /**\n     * @param bands the visible projects grouped by level, HIGHEST LEVEL FIRST. Levels need not be\n     *        contiguous — only the levels actually present get a band, and the chain links\n     *        whichever ones exist.\n     */\n    dot(bands: LevelBand[]): string {\n        let dot = '';\n        for (const band of bands) {\n            dot += `  \"${band.anchorName()}\" ${LAYOUT_NODE_ATTRS};\\n`;\n            dot += `  { rank=same; \"${band.anchorName()}\"; `;\n            for (const name of band.nodeNames) dot += `\"${name}\"; `;\n            dot += '}\\n';\n        }\n        for (let i = 0; i + 1 < bands.length; i++) {\n            dot += this.bandGap(bands[i], bands[i + 1]);\n        }\n        return dot;\n    }\n\n    /**\n     * The ordering chain between two adjacent bands. When either band is crowded\n     * (> SPACER_MIN_BAND_SIZE boxes), an empty spacer band goes between them: the edges leaving a\n     * wide row then have a whole rank of vertical room to fan out in, instead of being drawn\n     * straight through the row below.\n     */\n    private bandGap(upper: LevelBand, lower: LevelBand): string {\n        const crowded = upper.nodeNames.length > SPACER_MIN_BAND_SIZE\n            || lower.nodeNames.length > SPACER_MIN_BAND_SIZE;\n        if (!crowded) {\n            return `  \"${upper.anchorName()}\" -> \"${lower.anchorName()}\" ${LAYOUT_EDGE_ATTRS};\\n`;\n        }\n        const spacer = `__wp_layout_spacer_L${upper.level}_L${lower.level}`;\n        return `  \"${spacer}\" ${LAYOUT_NODE_ATTRS};\\n`\n            + `  { rank=same; \"${spacer}\"; }\\n`\n            + `  \"${upper.anchorName()}\" -> \"${spacer}\" ${LAYOUT_EDGE_ATTRS};\\n`\n            + `  \"${spacer}\" -> \"${lower.anchorName()}\" ${LAYOUT_EDGE_ATTRS};\\n`;\n    }\n}\n"]}
+{"version":3,"file":"graph-level-bands.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-level-bands.ts"],"names":[],"mappings":";;;AAAA,6CAAwC;AAExC;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,YAAY,GAAG,WAAW,CAAC;AAEjC,wFAAwF;AACxF,MAAM,iBAAiB,GACnB,wEAAwE,YAAY,IAAI,CAAC;AAE7F,sFAAsF;AACtF,MAAM,iBAAiB,GAAG,wBAAwB,YAAY,IAAI,CAAC;AAEnE;;;GAGG;AACH,MAAa,SAAS;IAClB,KAAK,CAAS;IACd,0FAA0F;IAC1F,SAAS,CAAW;IAEpB,YAAY,KAAa,EAAE,SAAmB;QAC1C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;IAED,UAAU;QACN,OAAO,gBAAgB,IAAI,CAAC,KAAK,EAAE,CAAC;IACxC,CAAC;CACJ;AAbD,8BAaC;AAED,oFAAoF;AACpF,MAAa,eAAe;IACxB;;;;OAIG;IACH,GAAG,CAAC,KAAkB;QAClB,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACvB,GAAG,IAAI,MAAM,IAAI,CAAC,UAAU,EAAE,KAAK,iBAAiB,KAAK,CAAC;YAC1D,GAAG,IAAI,mBAAmB,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC;YACjD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS;gBAAE,GAAG,IAAI,IAAI,IAAA,qBAAQ,EAAC,IAAI,CAAC,KAAK,CAAC;YAClE,GAAG,IAAI,KAAK,CAAC;QACjB,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACK,OAAO,CAAC,KAAgB,EAAE,KAAgB;QAC9C,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,oBAAoB;eACtD,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,oBAAoB,CAAC;QACrD,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,MAAM,KAAK,CAAC,UAAU,EAAE,SAAS,KAAK,CAAC,UAAU,EAAE,KAAK,iBAAiB,KAAK,CAAC;QAC1F,CAAC;QACD,MAAM,MAAM,GAAG,uBAAuB,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,EAAE,CAAC;QACpE,OAAO,MAAM,MAAM,KAAK,iBAAiB,KAAK;cACxC,mBAAmB,MAAM,QAAQ;cACjC,MAAM,KAAK,CAAC,UAAU,EAAE,SAAS,MAAM,KAAK,iBAAiB,KAAK;cAClE,MAAM,MAAM,SAAS,KAAK,CAAC,UAAU,EAAE,KAAK,iBAAiB,KAAK,CAAC;IAC7E,CAAC;CACJ;AAtCD,0CAsCC","sourcesContent":["import { dotValue } from './dot-syntax';\n\n/**\n * Level bands for the architecture graph.\n *\n * Every row of architecture/dependencies.html is ONE dependency level: the highest level on top,\n * descending as you read down, L0 — the foundation everything is built on — always last.\n *\n * `{ rank=same; ... }` alone does not deliver that, and assuming it did was the bug. It ties a\n * level's boxes to one row but says nothing about where that row goes, so graphviz derived each\n * row's position from the edges. A level containing a box with no visible edges — a leaf sdk, an\n * api-lib whose only consumers are hidden — is unconstrained, so it was placed at the top rank and\n * dragged its ENTIRE level up with it (verified against graphviz: that is what put the L0 sdks in\n * the top row, and what parked an L0 lib in the same row as the L6 servers).\n *\n * So the ordering is STATED here rather than inferred: one invisible anchor per band, sitting in\n * that band's rank set, chained top-to-bottom with invisible edges. Ranks are then a function of\n * level and nothing else. The anchors — never the real boxes — carry the chain, so no fake\n * dependency is ever drawn between two projects.\n */\n\n/**\n * A band bigger than this gets a blank spacer band inserted next to it, so the long edges leaving a\n * crowded row have vertical room to fan out instead of cutting straight through the row below.\n * Eleven-plus boxes in a row is where that became unreadable in practice.\n */\nconst SPACER_MIN_BAND_SIZE = 10;\n\n/**\n * The class stamped on every node and edge that exists ONLY to pin the layout. Graphviz drops\n * `style=invis` elements from its SVG entirely, so nothing carrying this class reaches the page\n * today; the class is how the DOT tells the browser client which elements are scaffolding, and the\n * client skips them when indexing so an anchor can never be walked as a dependency.\n */\nconst LAYOUT_CLASS = 'wp-layout';\n\n/** Attributes shared by every invisible layout node (rank anchors and spacer bands). */\nconst LAYOUT_NODE_ATTRS =\n    `[style=invis, shape=point, width=0.01, height=0.01, label=\"\", class=\"${LAYOUT_CLASS}\"]`;\n\n/** Attributes for the invisible edges that force one band strictly above the next. */\nconst LAYOUT_EDGE_ATTRS = `[style=invis, class=\"${LAYOUT_CLASS}\"]`;\n\n/**\n * One horizontal band of the graph: every visible project sharing a dependency level, plus the\n * invisible anchor that pins the band's vertical position.\n */\nexport class LevelBand {\n    level: number;\n    /** Short names of the visible projects on this level, sorted for deterministic output. */\n    nodeNames: string[];\n\n    constructor(level: number, nodeNames: string[]) {\n        this.level = level;\n        this.nodeNames = nodeNames;\n    }\n\n    anchorName(): string {\n        return `__wp_layout_L${this.level}`;\n    }\n}\n\n/** Emits the DOT that pins each band to its own rank, in descending level order. */\nexport class LevelBandLayout {\n    /**\n     * @param bands the visible projects grouped by level, HIGHEST LEVEL FIRST. Levels need not be\n     *        contiguous — only the levels actually present get a band, and the chain links\n     *        whichever ones exist.\n     */\n    dot(bands: LevelBand[]): string {\n        let dot = '';\n        for (const band of bands) {\n            dot += `  \"${band.anchorName()}\" ${LAYOUT_NODE_ATTRS};\\n`;\n            dot += `  { rank=same; \"${band.anchorName()}\"; `;\n            for (const name of band.nodeNames) dot += `\"${dotValue(name)}\"; `;\n            dot += '}\\n';\n        }\n        for (let i = 0; i + 1 < bands.length; i++) {\n            dot += this.bandGap(bands[i], bands[i + 1]);\n        }\n        return dot;\n    }\n\n    /**\n     * The ordering chain between two adjacent bands. When either band is crowded\n     * (> SPACER_MIN_BAND_SIZE boxes), an empty spacer band goes between them: the edges leaving a\n     * wide row then have a whole rank of vertical room to fan out in, instead of being drawn\n     * straight through the row below.\n     */\n    private bandGap(upper: LevelBand, lower: LevelBand): string {\n        const crowded = upper.nodeNames.length > SPACER_MIN_BAND_SIZE\n            || lower.nodeNames.length > SPACER_MIN_BAND_SIZE;\n        if (!crowded) {\n            return `  \"${upper.anchorName()}\" -> \"${lower.anchorName()}\" ${LAYOUT_EDGE_ATTRS};\\n`;\n        }\n        const spacer = `__wp_layout_spacer_L${upper.level}_L${lower.level}`;\n        return `  \"${spacer}\" ${LAYOUT_NODE_ATTRS};\\n`\n            + `  { rank=same; \"${spacer}\"; }\\n`\n            + `  \"${upper.anchorName()}\" -> \"${spacer}\" ${LAYOUT_EDGE_ATTRS};\\n`\n            + `  \"${spacer}\" -> \"${lower.anchorName()}\" ${LAYOUT_EDGE_ATTRS};\\n`;\n    }\n}\n"]}

package/src/lib/graph-loader.js

@@ -48,15 +48,15 @@ exports.AI_INSTRUCTIONS = "Each project's shortDescription is only a summary. BE
     'project and what does not), and read its designFile to understand the DI design ' +
     'before reading the code. Use the entries in `commands` to regenerate these files ' +
     'or display any of the graphs in a browser. To hide a project (its box AND every ' +
-    "edge touching it) from BOTH rendered architecture graphs, add the nx tag " +
+    'edge touching it) from BOTH rendered architecture graphs, add the nx tag ' +
     "'drawOnGraph:false' to that project's project.json tags and regenerate; it stays " +
     'in this file (marked "drawOnGraph": false) but is omitted from the HTML. A role:server ' +
     'with no webpiecesRuntime package anywhere in its dependency closure and no apiRelations is ' +
     'omitted from the RUNTIME drawing the same way — it speaks none of the webpieces runtime, so ' +
-    'it can only ever draw as a disconnected box; it stays in both JSON files. An API\'s endpoints ' +
+    "it can only ever draw as a disconnected box; it stays in both JSON files. An API's endpoints " +
     '(name, kind, path, httpMethod, parameters, queueName, caller) are NOT in this file: ' +
     '`apiContractFiles` maps each API to its generated contract file, apis/<ApiName>.json relative to ' +
-    'this file — read that file for the API\'s endpoints.';
+    "this file — read that file for the API's endpoints.";
 /**
  * Commands embedded in dependencies.json so AI (and humans) know how to
  * regenerate and DISPLAY the architecture + design graphs. These work in any
@@ -65,7 +65,7 @@ exports.AI_INSTRUCTIONS = "Each project's shortDescription is only a summary. BE
 exports.GRAPH_COMMANDS = {
     regenerateArchitecture: 'pnpm nx run architecture:generate — rewrites architecture/dependencies.json, ' +
         'architecture/apis/<ApiName>.json and architecture/runtime-dependencies.json; run after ' +
-        'adding/removing project dependencies or changing an API\'s endpoints',
+        'reviewing project runtime-deps.json and API contract candidates into architecture/apis; generation reads approvals and never approves endpoint changes',
     visualizeArchitecture: 'pnpm nx run architecture:visualize — opens the monorepo dependency graph (this file) ' +
         'as HTML in a browser from saved data, without refreshing; freshness unknown',
     visualizeRuntimeArchitecture: 'pnpm nx run architecture:visualize-runtime — opens the runtime microservice call graph ' +
@@ -126,7 +126,9 @@ function loadBlessedGraph(workspaceRoot, graphPath = exports.DEFAULT_GRAPH_PATH)
             throw movedApiContractsError(fullPath, graphPath);
         }
         if (parsed !== null && typeof parsed === 'object' && 'projects' in parsed) {
-            return new DependenciesFile(typeof parsed.aiInstructions === 'string' ? parsed.aiInstructions : '', parsed.commands !== null && typeof parsed.commands === 'object' ? parsed.commands : {}, parsed.projects, parsed.apiContractFiles !== null && typeof parsed.apiContractFiles === 'object'
+            return new DependenciesFile(typeof parsed.aiInstructions === 'string' ? parsed.aiInstructions : '', parsed.commands !== null && typeof parsed.commands === 'object'
+                ? parsed.commands
+                : {}, parsed.projects, parsed.apiContractFiles !== null && typeof parsed.apiContractFiles === 'object'
                 ? parsed.apiContractFiles
                 : {}, 
             // Absent in any file written before external systems could be declared; an empty
@@ -154,7 +156,9 @@ function loadBlessedGraph(workspaceRoot, graphPath = exports.DEFAULT_GRAPH_PATH)
 function movedApiContractsError(fullPath, graphPath) {
     const apisDir = path.join(path.dirname(graphPath), api_contract_files_1.API_CONTRACTS_DIR);
     return new rules_config_1.RuleFailError(api_contract_files_1.API_CONTRACT_FILES_RULE, `${fullPath} still carries the \`apiContracts\` key. It moved: each API's contract now lives in ` +
-        `${apisDir}/<ApiName>.json, and dependencies.json only links to it under \`apiContractFiles\`.`, undefined, undefined, [new rules_config_1.Option('Regenerate the architecture files and commit the result: pnpm nx run architecture:generate', true)]);
+        `${apisDir}/<ApiName>.json, and dependencies.json only links to it under \`apiContractFiles\`.`, undefined, undefined, [
+        new rules_config_1.Option(`Explicitly move each saved apiContracts.<ApiName> value into ${apisDir}/<ApiName>.json, replace apiContracts with reviewed apiContractFiles entries mapping each name to apis/<ApiName>.json, preserve externalSystems, and approve runtime-deps.json for all runtime owners. Then run pnpm nx run architecture:generate and review the result.`, true),
+    ]);
 }
 /**
  * Format the dependencies file as JSON with multi-line arrays for readability
@@ -245,6 +249,8 @@ function formatEntryLines(entry) {
     pushOptionalField(lines, 'responsibilitiesFile', entry.responsibilitiesFile);
     pushOptionalField(lines, 'designFile', entry.designFile);
     pushApiRelationsField(lines, entry.apiRelations);
+    pushOptionalField(lines, 'runtimeDeclaration', entry.runtimeDeclaration);
+    pushOptionalBooleanField(lines, 'runtimeComposition', entry.runtimeComposition);
     if (entry.dependsOn.length === 0) {
         lines.push(`            "dependsOn": []`);
     }

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

@@ -1 +1 @@
-{"version":3,"file":"graph-loader.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-loader.ts"],"names":[],"mappings":"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","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 * File format (schema aimed at AI consumers):\n * {\n *     \"aiInstructions\": \"...how AI should use the per-project fields...\",\n *     \"apiContractFiles\": { \"<ApiName>\": \"apis/<ApiName>.json\" },\n *     \"projects\": {\n *         \"<project>\": { level, framework, shortDescription,\n *                        responsibilitiesFile, designFile, dependsOn }\n *     }\n * }\n *\n * `framework` is 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\"]). It comes from the project's `framework:` nx tags\n * and is enforced across edges by the `library-types-match-client` rule.\n *\n * The legacy format (flat { \"<project>\": { level, dependsOn } } map) is still\n * readable so validation against a pre-upgrade file produces a clean\n * \"re-run architecture:generate\" diff instead of a parse failure.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { EnhancedGraph, GraphEntry } from './graph-sorter';\nimport { RuleFailError, Option } from '@webpieces/rules-config';\nimport type { ExternalSystemDecls, ProjectApiRelations } from './api-usage/api-relations';\nimport { API_CONTRACT_FILES_RULE, API_CONTRACTS_DIR } from './api-contract-files';\nimport type { ApiContractFileRefs } from './api-contract-files';\nimport { toError } from '../toError';\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 * Top-level instructions embedded in dependencies.json telling AI how to use\n * the per-project metadata fields.\n */\nexport const AI_INSTRUCTIONS =\n    \"Each project's shortDescription is only a summary. BEFORE adding code to a project, \" +\n    'read its responsibilitiesFile for the full responsibilities (what belongs in that ' +\n    'project and what does not), and read its designFile to understand the DI design ' +\n    'before reading the code. Use the entries in `commands` to regenerate these files ' +\n    'or display any of the graphs in a browser. To hide a project (its box AND every ' +\n    \"edge touching it) from BOTH rendered architecture graphs, add the nx tag \" +\n    \"'drawOnGraph:false' to that project's project.json tags and regenerate; it stays \" +\n    'in this file (marked \"drawOnGraph\": false) but is omitted from the HTML. A role:server ' +\n    'with no webpiecesRuntime package anywhere in its dependency closure and no apiRelations is ' +\n    'omitted from the RUNTIME drawing the same way — it speaks none of the webpieces runtime, so ' +\n    'it can only ever draw as a disconnected box; it stays in both JSON files. An API\\'s endpoints ' +\n    '(name, kind, path, httpMethod, parameters, queueName, caller) are NOT in this file: ' +\n    '`apiContractFiles` maps each API to its generated contract file, apis/<ApiName>.json relative to ' +\n    'this file — read that file for the API\\'s endpoints.';\n\n/**\n * Named command → \"command — what it does\" map embedded in dependencies.json.\n */\nexport type CommandMap = Record<string, string>;\n\n/**\n * Commands embedded in dependencies.json so AI (and humans) know how to\n * regenerate and DISPLAY the architecture + design graphs. These work in any\n * repo consuming @webpieces/nx-webpieces-rules.\n */\nexport const GRAPH_COMMANDS: CommandMap = {\n    regenerateArchitecture:\n        'pnpm nx run architecture:generate — rewrites architecture/dependencies.json, ' +\n        'architecture/apis/<ApiName>.json and architecture/runtime-dependencies.json; run after ' +\n        'adding/removing project dependencies or changing an API\\'s endpoints',\n    visualizeArchitecture:\n        'pnpm nx run architecture:visualize — opens the monorepo dependency graph (this file) ' +\n        'as HTML in a browser from saved data, without refreshing; freshness unknown',\n    visualizeRuntimeArchitecture:\n        'pnpm nx run architecture:visualize-runtime — opens the runtime microservice call graph ' +\n        'as HTML in a browser from saved data, without refreshing; freshness unknown',\n    regenerateDesigns:\n        \"pnpm nx run-many --target=di-graph-generate — rewrites every project's \" +\n        'design.json/design.md (also runs automatically on every build)',\n    visualizeDesign:\n        \"pnpm wp-design-visualize <project> — opens a project's DI designs (its designFile) as \" +\n        'HTML, one graph per controller with the controller at the top; no args = interactive picker',\n};\n\n/**\n * The full contents of architecture/dependencies.json.\n */\nexport class DependenciesFile {\n    constructor(\n        public readonly aiInstructions: string,\n        public readonly commands: CommandMap,\n        public readonly projects: EnhancedGraph,\n        /**\n         * apiClassName -> its contract file (`apis/<ApiName>.json`, relative to this file's\n         * directory). Only the LINK lives here, so adding an endpoint never changes dependencies.json;\n         * the contract itself is read with ApiContractFiles.load.\n         */\n        public readonly apiContractFiles: ApiContractFileRefs = {},\n        /**\n         * Declared external systems (databases, buckets, ...) keyed by identity. MUST be persisted:\n         * the runtime graph is derived from the committed files, so a declaration that is scanned but\n         * not written would make generate and validate disagree.\n         */\n        public readonly externalSystems: ExternalSystemDecls = {}\n    ) {}\n}\n\n/**\n * Load the blessed graph from disk. Understands both the current wrapper\n * format and the legacy flat map (which loads with empty aiInstructions).\n *\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)\n * @returns The blessed graph file, or null if it doesn't exist\n */\nexport function loadBlessedGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH\n): DependenciesFile | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n\n    if (!fs.existsSync(fullPath)) {\n        return null;\n    }\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const content = fs.readFileSync(fullPath, 'utf-8');\n        const parsed = JSON.parse(content);\n        if (parsed !== null && typeof parsed === 'object' && 'apiContracts' in parsed) {\n            throw movedApiContractsError(fullPath, graphPath);\n        }\n        if (parsed !== null && typeof parsed === 'object' && 'projects' in parsed) {\n            return new DependenciesFile(\n                typeof parsed.aiInstructions === 'string' ? parsed.aiInstructions : '',\n                parsed.commands !== null && typeof parsed.commands === 'object' ? (parsed.commands as CommandMap) : {},\n                parsed.projects as EnhancedGraph,\n                parsed.apiContractFiles !== null && typeof parsed.apiContractFiles === 'object'\n                    ? (parsed.apiContractFiles as ApiContractFileRefs)\n                    : {},\n                // Absent in any file written before external systems could be declared; an empty\n                // table simply draws no shaped nodes, which is exactly the old rendering.\n                parsed.externalSystems !== null && typeof parsed.externalSystems === 'object'\n                    ? (parsed.externalSystems as ExternalSystemDecls)\n                    : {}\n            );\n        }\n        // Legacy flat format: the whole object is the project map\n        return new DependenciesFile('', {}, parsed as EnhancedGraph);\n    } catch (err: unknown) {\n        const error = toError(err);\n        if (error instanceof RuleFailError) throw error;\n        throw new Error(`Failed to load graph from ${fullPath}`, { cause: error });\n    }\n}\n\n/**\n * The endpoint table moved out of dependencies.json (#949). A file still carrying `apiContracts` was\n * written by an older generator; it is REJECTED rather than read, so there is one place a contract\n * lives and the runtime graph can never read a stale copy of it.\n */\n// webpieces-disable no-function-outside-class -- error builder for loadBlessedGraph, module-scope like its siblings\nfunction movedApiContractsError(fullPath: string, graphPath: string): RuleFailError {\n    const apisDir = path.join(path.dirname(graphPath), API_CONTRACTS_DIR);\n    return new RuleFailError(\n        API_CONTRACT_FILES_RULE,\n        `${fullPath} still carries the \\`apiContracts\\` key. It moved: each API's contract now lives in ` +\n            `${apisDir}/<ApiName>.json, and dependencies.json only links to it under \\`apiContractFiles\\`.`,\n        undefined,\n        undefined,\n        [new Option('Regenerate the architecture files and commit the result: pnpm nx run architecture:generate', true)],\n    );\n}\n\n/**\n * Format the dependencies file as JSON with multi-line arrays for readability\n */\nfunction formatGraphJson(file: DependenciesFile): string {\n    const lines: string[] = ['{'];\n    lines.push(`    \"aiInstructions\": ${JSON.stringify(file.aiInstructions)},`);\n    lines.push(`    \"commands\": {`);\n    const commandNames = Object.keys(file.commands);\n    commandNames.forEach((name: string, index: number) => {\n        const comma = index === commandNames.length - 1 ? '' : ',';\n        lines.push(`        ${JSON.stringify(name)}: ${JSON.stringify(file.commands[name])}${comma}`);\n    });\n    lines.push(`    },`);\n    lines.push(...apiContractFilesLines(file.apiContractFiles));\n    lines.push(...externalSystemsLines(file.externalSystems));\n    lines.push(`    \"projects\": {`);\n\n    const keys = Object.keys(file.projects).sort();\n    keys.forEach((key: string, index: number) => {\n        const entry = file.projects[key];\n        const isLast = index === keys.length - 1;\n        const comma = isLast ? '' : ',';\n\n        lines.push(`        ${JSON.stringify(key)}: {`);\n        lines.push(...formatEntryLines(entry));\n        lines.push(`        }${comma}`);\n    });\n\n    lines.push('    }');\n    lines.push('}');\n    return lines.join('\\n') + '\\n';\n}\n\n/**\n * The `\"apiContractFiles\": {...}` block (4-space indent), with a trailing comma since `projects`\n * always follows it. Omitted entirely when empty. Keys are sorted, so the output is deterministic.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling formatters here\nfunction apiContractFilesLines(refs: ApiContractFileRefs): string[] {\n    if (Object.keys(refs).length === 0) return [];\n    const sorted: ApiContractFileRefs = {};\n    for (const api of Object.keys(refs).sort()) sorted[api] = refs[api];\n    const pretty = JSON.stringify(sorted, null, 4).split('\\n');\n    return pretty.map((line: string, index: number) => {\n        const prefix = index === 0 ? '\"apiContractFiles\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        return `    ${prefix}${line}${suffix}`;\n    });\n}\n\n/**\n * The `\"externalSystems\": {...}` block (4-space indent), with a trailing comma since `projects`\n * always follows. Omitted entirely when empty, so a repo that declares none keeps the exact file\n * shape it had before this existed — which is what makes adopting it a no-op diff.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling formatters here\nfunction externalSystemsLines(systems: ExternalSystemDecls): string[] {\n    if (Object.keys(systems).length === 0) return [];\n    const sorted: ExternalSystemDecls = {};\n    for (const identity of Object.keys(systems).sort()) sorted[identity] = systems[identity];\n    const pretty = JSON.stringify(sorted, null, 4).split('\\n');\n    return pretty.map((line: string, index: number) => {\n        const prefix = index === 0 ? '\"externalSystems\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        return `    ${prefix}${line}${suffix}`;\n    });\n}\n\n/**\n * Format one project entry's fields (12-space indent). Optional metadata\n * fields are only emitted when present.\n */\nfunction formatEntryLines(entry: GraphEntry): string[] {\n    const lines: string[] = [];\n    lines.push(`            \"level\": ${entry.level},`);\n\n    pushOptionalArrayField(lines, 'framework', entry.framework);\n    pushOptionalField(lines, 'role', entry.role);\n    // Right after role — role says what the project IS, this says what runtime it speaks. MUST be\n    // persisted: validate re-derives the runtime graph from this file, so a field written only\n    // in-memory by generate would make the two derive different graphs.\n    pushOptionalArrayField(lines, 'webpiecesRuntime', entry.webpiecesRuntime);\n    pushOptionalField(lines, 'serviceName', entry.serviceName);\n    pushOptionalCallsServiceField(lines, entry.callsService);\n    pushOptionalBooleanField(lines, 'drawOnGraph', entry.drawOnGraph);\n    // MUST be persisted: validate re-derives the runtime graph from this file, so a cut written only\n    // in-memory by generate would make generate and validate level (and cycle-check) different graphs.\n    pushOptionalArrayField(lines, 'cutLegacyCycle', entry.cutLegacyCycle);\n    pushOptionalField(lines, 'shortDescription', entry.shortDescription);\n    pushOptionalField(lines, 'responsibilitiesFile', entry.responsibilitiesFile);\n    pushOptionalField(lines, 'designFile', entry.designFile);\n    pushApiRelationsField(lines, entry.apiRelations);\n\n    if (entry.dependsOn.length === 0) {\n        lines.push(`            \"dependsOn\": []`);\n    } else {\n        lines.push(`            \"dependsOn\": [`);\n        entry.dependsOn.forEach((dep: string, depIndex: number) => {\n            const depComma = depIndex === entry.dependsOn.length - 1 ? '' : ',';\n            lines.push(`                ${JSON.stringify(dep)}${depComma}`);\n        });\n        lines.push(`            ]`);\n    }\n    return lines;\n}\n\n/**\n * Emit one optional string field (12-space indent), skipped when undefined.\n */\nfunction pushOptionalField(lines: string[], field: string, value: string | undefined): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit the optional `callsService` field (12-space indent). Unlike serviceName it may be EITHER a\n * single service name (string) OR an { apiClassName: serviceName } map, so it is emitted with\n * JSON.stringify to cover both inline. MUST be persisted here: the runtime graph's target resolution\n * reads it back from the committed dependencies.json during validate — dropping it would make\n * generate (which enriches it in-memory) and validate (which loads this file) derive different graphs.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushOptionalCallsServiceField(\n    lines: string[],\n    value: string | Record<string, string> | undefined,\n): void {\n    if (value !== undefined) {\n        lines.push(`            \"callsService\": ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit one optional boolean field (12-space indent) as a raw JSON boolean\n * (e.g. `\"drawOnGraph\": false,`), skipped when undefined.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushOptionalBooleanField(lines: string[], field: string, value: boolean | undefined): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit one optional string-array field (12-space indent) as a compact inline\n * JSON array (e.g. `\"framework\": [\"browser\",\"node\"],`), skipped when undefined.\n */\nfunction pushOptionalArrayField(lines: string[], field: string, value: string[] | undefined): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit the optional `apiRelations` object (pretty, multi-line, reindented under\n * the 12-space entry block) with a trailing comma, since `dependsOn` always\n * follows it. Skipped when absent/empty so plain-lib-only projects stay compact.\n * The scanner already sorts owners + refs, so the JSON is deterministic.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushApiRelationsField(lines: string[], value: ProjectApiRelations | undefined): void {\n    if (value === undefined || Object.keys(value).length === 0) return;\n    const pretty = JSON.stringify(value, null, 4).split('\\n');\n    pretty.forEach((line: string, index: number) => {\n        const prefix = index === 0 ? '\"apiRelations\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        lines.push(`            ${prefix}${line}${suffix}`);\n    });\n}\n\n/**\n * Save the graph to disk in the wrapper format with the standard aiInstructions.\n *\n * @param graph - The enriched project graph to save\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)\n */\nexport function saveGraph(\n    graph: EnhancedGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH,\n    apiContractFiles: ApiContractFileRefs = {},\n    externalSystems: ExternalSystemDecls = {}\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 = formatGraphJson(\n        new DependenciesFile(AI_INSTRUCTIONS, GRAPH_COMMANDS, sortedGraph, apiContractFiles, externalSystems)\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"]}
+{"version":3,"file":"graph-loader.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-loader.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAgGH,4CAyCC;AAkND,8BAgCC;AAKD,0CAMC;;AApYD,+CAAyB;AACzB,mDAA6B;AAE7B,0DAAgE;AAEhE,6DAAkF;AAElF,wCAAqC;AAErC;;GAEG;AACU,QAAA,kBAAkB,GAAG,gCAAgC,CAAC;AAEnE;;;GAGG;AACU,QAAA,eAAe,GACxB,sFAAsF;IACtF,oFAAoF;IACpF,kFAAkF;IAClF,mFAAmF;IACnF,kFAAkF;IAClF,2EAA2E;IAC3E,mFAAmF;IACnF,yFAAyF;IACzF,6FAA6F;IAC7F,8FAA8F;IAC9F,+FAA+F;IAC/F,sFAAsF;IACtF,mGAAmG;IACnG,qDAAqD,CAAC;AAO1D;;;;GAIG;AACU,QAAA,cAAc,GAAe;IACtC,sBAAsB,EAClB,+EAA+E;QAC/E,yFAAyF;QACzF,wJAAwJ;IAC5J,qBAAqB,EACjB,uFAAuF;QACvF,6EAA6E;IACjF,4BAA4B,EACxB,yFAAyF;QACzF,6EAA6E;IACjF,iBAAiB,EACb,yEAAyE;QACzE,gEAAgE;IACpE,eAAe,EACX,wFAAwF;QACxF,6FAA6F;CACpG,CAAC;AAEF;;GAEG;AACH,MAAa,gBAAgB;IAEL;IACA;IACA;IAMA;IAMA;IAfpB,YACoB,cAAsB,EACtB,QAAoB,EACpB,QAAuB;IACvC;;;;OAIG;IACa,mBAAwC,EAAE;IAC1D;;;;OAIG;IACa,kBAAuC,EAAE;QAdzC,mBAAc,GAAd,cAAc,CAAQ;QACtB,aAAQ,GAAR,QAAQ,CAAY;QACpB,aAAQ,GAAR,QAAQ,CAAe;QAMvB,qBAAgB,GAAhB,gBAAgB,CAA0B;QAM1C,oBAAe,GAAf,eAAe,CAA0B;IAC1D,CAAC;CACP;AAlBD,4CAkBC;AAED;;;;;;;GAOG;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,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,cAAc,IAAI,MAAM,EAAE,CAAC;YAC5E,MAAM,sBAAsB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QACtD,CAAC;QACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,UAAU,IAAI,MAAM,EAAE,CAAC;YACxE,OAAO,IAAI,gBAAgB,CACvB,OAAO,MAAM,CAAC,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EACtE,MAAM,CAAC,QAAQ,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;gBAC3D,CAAC,CAAE,MAAM,CAAC,QAAuB;gBACjC,CAAC,CAAC,EAAE,EACR,MAAM,CAAC,QAAyB,EAChC,MAAM,CAAC,gBAAgB,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,gBAAgB,KAAK,QAAQ;gBAC3E,CAAC,CAAE,MAAM,CAAC,gBAAwC;gBAClD,CAAC,CAAC,EAAE;YACR,iFAAiF;YACjF,0EAA0E;YAC1E,MAAM,CAAC,eAAe,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,eAAe,KAAK,QAAQ;gBACzE,CAAC,CAAE,MAAM,CAAC,eAAuC;gBACjD,CAAC,CAAC,EAAE,CACX,CAAC;QACN,CAAC;QACD,0DAA0D;QAC1D,OAAO,IAAI,gBAAgB,CAAC,EAAE,EAAE,EAAE,EAAE,MAAuB,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,KAAK,YAAY,4BAAa;YAAE,MAAM,KAAK,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/E,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,oHAAoH;AACpH,SAAS,sBAAsB,CAAC,QAAgB,EAAE,SAAiB;IAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,sCAAiB,CAAC,CAAC;IACtE,OAAO,IAAI,4BAAa,CACpB,4CAAuB,EACvB,GAAG,QAAQ,sFAAsF;QAC7F,GAAG,OAAO,qFAAqF,EACnG,SAAS,EACT,SAAS,EACT;QACI,IAAI,qBAAM,CACN,gEAAgE,OAAO,0QAA0Q,EACjV,IAAI,CACP;KACJ,CACJ,CAAC;AACN,CAAC;AAED;;GAEG;AACH,SAAS,eAAe,CAAC,IAAsB;IAC3C,MAAM,KAAK,GAAa,CAAC,GAAG,CAAC,CAAC;IAC9B,KAAK,CAAC,IAAI,CAAC,yBAAyB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IAC5E,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAChC,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChD,YAAY,CAAC,OAAO,CAAC,CAAC,IAAY,EAAE,KAAa,EAAE,EAAE;QACjD,MAAM,KAAK,GAAG,KAAK,KAAK,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAC3D,KAAK,CAAC,IAAI,CACN,WAAW,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,EAAE,CACpF,CAAC;IACN,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrB,KAAK,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC5D,KAAK,CAAC,IAAI,CAAC,GAAG,oBAAoB,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;IAC1D,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAEhC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/C,IAAI,CAAC,OAAO,CAAC,CAAC,GAAW,EAAE,KAAa,EAAE,EAAE;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,MAAM,GAAG,KAAK,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAEhC,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,6GAA6G;AAC7G,SAAS,qBAAqB,CAAC,IAAyB;IACpD,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAwB,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3D,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,IAAY,EAAE,KAAa,EAAE,EAAE;QAC9C,MAAM,MAAM,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,MAAM,MAAM,GAAG,KAAK,KAAK,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,OAAO,OAAO,MAAM,GAAG,IAAI,GAAG,MAAM,EAAE,CAAC;IAC3C,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;GAIG;AACH,6GAA6G;AAC7G,SAAS,oBAAoB,CAAC,OAA4B;IACtD,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACjD,MAAM,MAAM,GAAwB,EAAE,CAAC;IACvC,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzF,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3D,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,IAAY,EAAE,KAAa,EAAE,EAAE;QAC9C,MAAM,MAAM,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,MAAM,MAAM,GAAG,KAAK,KAAK,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,OAAO,OAAO,MAAM,GAAG,IAAI,GAAG,MAAM,EAAE,CAAC;IAC3C,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,KAAiB;IACvC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,wBAAwB,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;IAEnD,sBAAsB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC5D,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7C,8FAA8F;IAC9F,2FAA2F;IAC3F,oEAAoE;IACpE,sBAAsB,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC1E,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3D,6BAA6B,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IACzD,wBAAwB,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAClE,iGAAiG;IACjG,mGAAmG;IACnG,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IACtE,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACrE,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC7E,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACzD,qBAAqB,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IACjD,iBAAiB,CAAC,KAAK,EAAE,oBAAoB,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACzE,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAEhF,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACJ,KAAK,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;QACzC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,GAAW,EAAE,QAAgB,EAAE,EAAE;YACtD,MAAM,QAAQ,GAAG,QAAQ,KAAK,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;YACpE,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,QAAQ,EAAE,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB,CAAC,KAAe,EAAE,KAAa,EAAE,KAAyB;IAChF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClF,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,qHAAqH;AACrH,SAAS,6BAA6B,CAClC,KAAe,EACf,KAAkD;IAElD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,+BAA+B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxE,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,qHAAqH;AACrH,SAAS,wBAAwB,CAC7B,KAAe,EACf,KAAa,EACb,KAA0B;IAE1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClF,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,SAAS,sBAAsB,CAAC,KAAe,EAAE,KAAa,EAAE,KAA2B;IACvF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClF,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,qHAAqH;AACrH,SAAS,qBAAqB,CAAC,KAAe,EAAE,KAAsC;IAClF,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACnE,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,CAAC,OAAO,CAAC,CAAC,IAAY,EAAE,KAAa,EAAE,EAAE;QAC3C,MAAM,MAAM,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,KAAK,KAAK,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,KAAK,CAAC,IAAI,CAAC,eAAe,MAAM,GAAG,IAAI,GAAG,MAAM,EAAE,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CACrB,KAAoB,EACpB,aAAqB,EACrB,YAAoB,0BAAkB,EACtC,mBAAwC,EAAE,EAC1C,kBAAuC,EAAE;IAEzC,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,eAAe,CAC3B,IAAI,gBAAgB,CAChB,uBAAe,EACf,sBAAc,EACd,WAAW,EACX,gBAAgB,EAChB,eAAe,CAClB,CACJ,CAAC;IACF,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 * File format (schema aimed at AI consumers):\n * {\n *     \"aiInstructions\": \"...how AI should use the per-project fields...\",\n *     \"apiContractFiles\": { \"<ApiName>\": \"apis/<ApiName>.json\" },\n *     \"projects\": {\n *         \"<project>\": { level, framework, shortDescription,\n *                        responsibilitiesFile, designFile, dependsOn }\n *     }\n * }\n *\n * `framework` is 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\"]). It comes from the project's `framework:` nx tags\n * and is enforced across edges by the `library-types-match-client` rule.\n *\n * The legacy format (flat { \"<project>\": { level, dependsOn } } map) is still\n * readable so validation against a pre-upgrade file produces a clean\n * \"re-run architecture:generate\" diff instead of a parse failure.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { EnhancedGraph, GraphEntry } from './graph-sorter';\nimport { RuleFailError, Option } from '@webpieces/rules-config';\nimport type { ExternalSystemDecls, ProjectApiRelations } from './api-usage/api-relations';\nimport { API_CONTRACT_FILES_RULE, API_CONTRACTS_DIR } from './api-contract-files';\nimport type { ApiContractFileRefs } from './api-contract-files';\nimport { toError } from '../toError';\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 * Top-level instructions embedded in dependencies.json telling AI how to use\n * the per-project metadata fields.\n */\nexport const AI_INSTRUCTIONS =\n    \"Each project's shortDescription is only a summary. BEFORE adding code to a project, \" +\n    'read its responsibilitiesFile for the full responsibilities (what belongs in that ' +\n    'project and what does not), and read its designFile to understand the DI design ' +\n    'before reading the code. Use the entries in `commands` to regenerate these files ' +\n    'or display any of the graphs in a browser. To hide a project (its box AND every ' +\n    'edge touching it) from BOTH rendered architecture graphs, add the nx tag ' +\n    \"'drawOnGraph:false' to that project's project.json tags and regenerate; it stays \" +\n    'in this file (marked \"drawOnGraph\": false) but is omitted from the HTML. A role:server ' +\n    'with no webpiecesRuntime package anywhere in its dependency closure and no apiRelations is ' +\n    'omitted from the RUNTIME drawing the same way — it speaks none of the webpieces runtime, so ' +\n    \"it can only ever draw as a disconnected box; it stays in both JSON files. An API's endpoints \" +\n    '(name, kind, path, httpMethod, parameters, queueName, caller) are NOT in this file: ' +\n    '`apiContractFiles` maps each API to its generated contract file, apis/<ApiName>.json relative to ' +\n    \"this file — read that file for the API's endpoints.\";\n\n/**\n * Named command → \"command — what it does\" map embedded in dependencies.json.\n */\nexport type CommandMap = Record<string, string>;\n\n/**\n * Commands embedded in dependencies.json so AI (and humans) know how to\n * regenerate and DISPLAY the architecture + design graphs. These work in any\n * repo consuming @webpieces/nx-webpieces-rules.\n */\nexport const GRAPH_COMMANDS: CommandMap = {\n    regenerateArchitecture:\n        'pnpm nx run architecture:generate — rewrites architecture/dependencies.json, ' +\n        'architecture/apis/<ApiName>.json and architecture/runtime-dependencies.json; run after ' +\n        'reviewing project runtime-deps.json and API contract candidates into architecture/apis; generation reads approvals and never approves endpoint changes',\n    visualizeArchitecture:\n        'pnpm nx run architecture:visualize — opens the monorepo dependency graph (this file) ' +\n        'as HTML in a browser from saved data, without refreshing; freshness unknown',\n    visualizeRuntimeArchitecture:\n        'pnpm nx run architecture:visualize-runtime — opens the runtime microservice call graph ' +\n        'as HTML in a browser from saved data, without refreshing; freshness unknown',\n    regenerateDesigns:\n        \"pnpm nx run-many --target=di-graph-generate — rewrites every project's \" +\n        'design.json/design.md (also runs automatically on every build)',\n    visualizeDesign:\n        \"pnpm wp-design-visualize <project> — opens a project's DI designs (its designFile) as \" +\n        'HTML, one graph per controller with the controller at the top; no args = interactive picker',\n};\n\n/**\n * The full contents of architecture/dependencies.json.\n */\nexport class DependenciesFile {\n    constructor(\n        public readonly aiInstructions: string,\n        public readonly commands: CommandMap,\n        public readonly projects: EnhancedGraph,\n        /**\n         * apiClassName -> its contract file (`apis/<ApiName>.json`, relative to this file's\n         * directory). Only the LINK lives here, so adding an endpoint never changes dependencies.json;\n         * the contract itself is read with ApiContractFiles.load.\n         */\n        public readonly apiContractFiles: ApiContractFileRefs = {},\n        /**\n         * Declared external systems (databases, buckets, ...) keyed by identity. MUST be persisted:\n         * the runtime graph is derived from the committed files, so a declaration that is scanned but\n         * not written would make generate and validate disagree.\n         */\n        public readonly externalSystems: ExternalSystemDecls = {},\n    ) {}\n}\n\n/**\n * Load the blessed graph from disk. Understands both the current wrapper\n * format and the legacy flat map (which loads with empty aiInstructions).\n *\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)\n * @returns The blessed graph file, or null if it doesn't exist\n */\nexport function loadBlessedGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH,\n): DependenciesFile | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n\n    if (!fs.existsSync(fullPath)) {\n        return null;\n    }\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const content = fs.readFileSync(fullPath, 'utf-8');\n        const parsed = JSON.parse(content);\n        if (parsed !== null && typeof parsed === 'object' && 'apiContracts' in parsed) {\n            throw movedApiContractsError(fullPath, graphPath);\n        }\n        if (parsed !== null && typeof parsed === 'object' && 'projects' in parsed) {\n            return new DependenciesFile(\n                typeof parsed.aiInstructions === 'string' ? parsed.aiInstructions : '',\n                parsed.commands !== null && typeof parsed.commands === 'object'\n                    ? (parsed.commands as CommandMap)\n                    : {},\n                parsed.projects as EnhancedGraph,\n                parsed.apiContractFiles !== null && typeof parsed.apiContractFiles === 'object'\n                    ? (parsed.apiContractFiles as ApiContractFileRefs)\n                    : {},\n                // Absent in any file written before external systems could be declared; an empty\n                // table simply draws no shaped nodes, which is exactly the old rendering.\n                parsed.externalSystems !== null && typeof parsed.externalSystems === 'object'\n                    ? (parsed.externalSystems as ExternalSystemDecls)\n                    : {},\n            );\n        }\n        // Legacy flat format: the whole object is the project map\n        return new DependenciesFile('', {}, parsed as EnhancedGraph);\n    } catch (err: unknown) {\n        const error = toError(err);\n        if (error instanceof RuleFailError) throw error;\n        throw new Error(`Failed to load graph from ${fullPath}`, { cause: error });\n    }\n}\n\n/**\n * The endpoint table moved out of dependencies.json (#949). A file still carrying `apiContracts` was\n * written by an older generator; it is REJECTED rather than read, so there is one place a contract\n * lives and the runtime graph can never read a stale copy of it.\n */\n// webpieces-disable no-function-outside-class -- error builder for loadBlessedGraph, module-scope like its siblings\nfunction movedApiContractsError(fullPath: string, graphPath: string): RuleFailError {\n    const apisDir = path.join(path.dirname(graphPath), API_CONTRACTS_DIR);\n    return new RuleFailError(\n        API_CONTRACT_FILES_RULE,\n        `${fullPath} still carries the \\`apiContracts\\` key. It moved: each API's contract now lives in ` +\n            `${apisDir}/<ApiName>.json, and dependencies.json only links to it under \\`apiContractFiles\\`.`,\n        undefined,\n        undefined,\n        [\n            new Option(\n                `Explicitly move each saved apiContracts.<ApiName> value into ${apisDir}/<ApiName>.json, replace apiContracts with reviewed apiContractFiles entries mapping each name to apis/<ApiName>.json, preserve externalSystems, and approve runtime-deps.json for all runtime owners. Then run pnpm nx run architecture:generate and review the result.`,\n                true,\n            ),\n        ],\n    );\n}\n\n/**\n * Format the dependencies file as JSON with multi-line arrays for readability\n */\nfunction formatGraphJson(file: DependenciesFile): string {\n    const lines: string[] = ['{'];\n    lines.push(`    \"aiInstructions\": ${JSON.stringify(file.aiInstructions)},`);\n    lines.push(`    \"commands\": {`);\n    const commandNames = Object.keys(file.commands);\n    commandNames.forEach((name: string, index: number) => {\n        const comma = index === commandNames.length - 1 ? '' : ',';\n        lines.push(\n            `        ${JSON.stringify(name)}: ${JSON.stringify(file.commands[name])}${comma}`,\n        );\n    });\n    lines.push(`    },`);\n    lines.push(...apiContractFilesLines(file.apiContractFiles));\n    lines.push(...externalSystemsLines(file.externalSystems));\n    lines.push(`    \"projects\": {`);\n\n    const keys = Object.keys(file.projects).sort();\n    keys.forEach((key: string, index: number) => {\n        const entry = file.projects[key];\n        const isLast = index === keys.length - 1;\n        const comma = isLast ? '' : ',';\n\n        lines.push(`        ${JSON.stringify(key)}: {`);\n        lines.push(...formatEntryLines(entry));\n        lines.push(`        }${comma}`);\n    });\n\n    lines.push('    }');\n    lines.push('}');\n    return lines.join('\\n') + '\\n';\n}\n\n/**\n * The `\"apiContractFiles\": {...}` block (4-space indent), with a trailing comma since `projects`\n * always follows it. Omitted entirely when empty. Keys are sorted, so the output is deterministic.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling formatters here\nfunction apiContractFilesLines(refs: ApiContractFileRefs): string[] {\n    if (Object.keys(refs).length === 0) return [];\n    const sorted: ApiContractFileRefs = {};\n    for (const api of Object.keys(refs).sort()) sorted[api] = refs[api];\n    const pretty = JSON.stringify(sorted, null, 4).split('\\n');\n    return pretty.map((line: string, index: number) => {\n        const prefix = index === 0 ? '\"apiContractFiles\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        return `    ${prefix}${line}${suffix}`;\n    });\n}\n\n/**\n * The `\"externalSystems\": {...}` block (4-space indent), with a trailing comma since `projects`\n * always follows. Omitted entirely when empty, so a repo that declares none keeps the exact file\n * shape it had before this existed — which is what makes adopting it a no-op diff.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling formatters here\nfunction externalSystemsLines(systems: ExternalSystemDecls): string[] {\n    if (Object.keys(systems).length === 0) return [];\n    const sorted: ExternalSystemDecls = {};\n    for (const identity of Object.keys(systems).sort()) sorted[identity] = systems[identity];\n    const pretty = JSON.stringify(sorted, null, 4).split('\\n');\n    return pretty.map((line: string, index: number) => {\n        const prefix = index === 0 ? '\"externalSystems\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        return `    ${prefix}${line}${suffix}`;\n    });\n}\n\n/**\n * Format one project entry's fields (12-space indent). Optional metadata\n * fields are only emitted when present.\n */\nfunction formatEntryLines(entry: GraphEntry): string[] {\n    const lines: string[] = [];\n    lines.push(`            \"level\": ${entry.level},`);\n\n    pushOptionalArrayField(lines, 'framework', entry.framework);\n    pushOptionalField(lines, 'role', entry.role);\n    // Right after role — role says what the project IS, this says what runtime it speaks. MUST be\n    // persisted: validate re-derives the runtime graph from this file, so a field written only\n    // in-memory by generate would make the two derive different graphs.\n    pushOptionalArrayField(lines, 'webpiecesRuntime', entry.webpiecesRuntime);\n    pushOptionalField(lines, 'serviceName', entry.serviceName);\n    pushOptionalCallsServiceField(lines, entry.callsService);\n    pushOptionalBooleanField(lines, 'drawOnGraph', entry.drawOnGraph);\n    // MUST be persisted: validate re-derives the runtime graph from this file, so a cut written only\n    // in-memory by generate would make generate and validate level (and cycle-check) different graphs.\n    pushOptionalArrayField(lines, 'cutLegacyCycle', entry.cutLegacyCycle);\n    pushOptionalField(lines, 'shortDescription', entry.shortDescription);\n    pushOptionalField(lines, 'responsibilitiesFile', entry.responsibilitiesFile);\n    pushOptionalField(lines, 'designFile', entry.designFile);\n    pushApiRelationsField(lines, entry.apiRelations);\n    pushOptionalField(lines, 'runtimeDeclaration', entry.runtimeDeclaration);\n    pushOptionalBooleanField(lines, 'runtimeComposition', entry.runtimeComposition);\n\n    if (entry.dependsOn.length === 0) {\n        lines.push(`            \"dependsOn\": []`);\n    } else {\n        lines.push(`            \"dependsOn\": [`);\n        entry.dependsOn.forEach((dep: string, depIndex: number) => {\n            const depComma = depIndex === entry.dependsOn.length - 1 ? '' : ',';\n            lines.push(`                ${JSON.stringify(dep)}${depComma}`);\n        });\n        lines.push(`            ]`);\n    }\n    return lines;\n}\n\n/**\n * Emit one optional string field (12-space indent), skipped when undefined.\n */\nfunction pushOptionalField(lines: string[], field: string, value: string | undefined): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit the optional `callsService` field (12-space indent). Unlike serviceName it may be EITHER a\n * single service name (string) OR an { apiClassName: serviceName } map, so it is emitted with\n * JSON.stringify to cover both inline. MUST be persisted here: the runtime graph's target resolution\n * reads it back from the committed dependencies.json during validate — dropping it would make\n * generate (which enriches it in-memory) and validate (which loads this file) derive different graphs.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushOptionalCallsServiceField(\n    lines: string[],\n    value: string | Record<string, string> | undefined,\n): void {\n    if (value !== undefined) {\n        lines.push(`            \"callsService\": ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit one optional boolean field (12-space indent) as a raw JSON boolean\n * (e.g. `\"drawOnGraph\": false,`), skipped when undefined.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushOptionalBooleanField(\n    lines: string[],\n    field: string,\n    value: boolean | undefined,\n): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit one optional string-array field (12-space indent) as a compact inline\n * JSON array (e.g. `\"framework\": [\"browser\",\"node\"],`), skipped when undefined.\n */\nfunction pushOptionalArrayField(lines: string[], field: string, value: string[] | undefined): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit the optional `apiRelations` object (pretty, multi-line, reindented under\n * the 12-space entry block) with a trailing comma, since `dependsOn` always\n * follows it. Skipped when absent/empty so plain-lib-only projects stay compact.\n * The scanner already sorts owners + refs, so the JSON is deterministic.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushApiRelationsField(lines: string[], value: ProjectApiRelations | undefined): void {\n    if (value === undefined || Object.keys(value).length === 0) return;\n    const pretty = JSON.stringify(value, null, 4).split('\\n');\n    pretty.forEach((line: string, index: number) => {\n        const prefix = index === 0 ? '\"apiRelations\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        lines.push(`            ${prefix}${line}${suffix}`);\n    });\n}\n\n/**\n * Save the graph to disk in the wrapper format with the standard aiInstructions.\n *\n * @param graph - The enriched project graph to save\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)\n */\nexport function saveGraph(\n    graph: EnhancedGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH,\n    apiContractFiles: ApiContractFileRefs = {},\n    externalSystems: ExternalSystemDecls = {},\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 = formatGraphJson(\n        new DependenciesFile(\n            AI_INSTRUCTIONS,\n            GRAPH_COMMANDS,\n            sortedGraph,\n            apiContractFiles,\n            externalSystems,\n        ),\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/src/lib/graph-navigation.d.ts

@@ -0,0 +1,5 @@
+/** Shared local-file navigation. Reset restores readable scale; Fit is an explicit overview. */
+export declare class GraphNavigation {
+    styles(): string;
+    script(): string;
+}

package/src/lib/graph-navigation.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphNavigation = void 0;
+/** Shared local-file navigation. Reset restores readable scale; Fit is an explicit overview. */
+class GraphNavigation {
+    styles() {
+        return `
+        #graph { overflow: auto; max-height: 75vh; text-align: left; touch-action: pan-x pan-y; }
+        #graph svg { max-width: none; max-height: none; display: block; }
+        .wp-navigation { display: flex; gap: 8px; align-items: center; margin: 10px 0; }
+        .wp-navigation button { padding: 6px 12px; cursor: pointer; }
+        .wp-graph-details { position: fixed; z-index: 1100; box-sizing: border-box; max-width: min(520px, calc(100vw - 24px)); max-height: min(480px, calc(100vh - 24px)); overflow: auto; background: white; padding: 12px; border: 1px solid #aaa; border-radius: 6px; box-shadow: 0 4px 16px #0003; font: 14px/1.5 Arial, sans-serif; overflow-wrap: anywhere; }
+        .wp-graph-details li { margin-bottom: 8px; }
+        .wp-api-detail { cursor: pointer; text-decoration: underline; }
+        .wp-api-detail:focus { outline: 2px solid #1565c0; }
+        `;
+    }
+    script() {
+        return `new (${GraphNavigationController.toString()})();`;
+    }
+}
+exports.GraphNavigation = GraphNavigation;
+/** Serialized browser controller; dependencies are native DOM APIs only. */
+class GraphNavigationController {
+    host = document.getElementById('graph');
+    toolbar = document.createElement('nav');
+    status = document.createElement('output');
+    svg = null;
+    scale = 1;
+    constructor() {
+        if (this.host === null)
+            return;
+        this.toolbar.className = 'wp-navigation';
+        this.toolbar.setAttribute('aria-label', 'Graph navigation');
+        this.host.before(this.toolbar);
+        this.button('Zoom in', () => this.zoom(1.25));
+        this.button('Zoom out', () => this.zoom(0.8));
+        this.button('Readable reset', () => this.reset());
+        this.button('Fit overview', () => this.fit());
+        this.toolbar.append(this.status);
+        new MutationObserver(() => this.attach()).observe(this.host, { childList: true });
+        this.attach();
+        window.addEventListener('resize', () => this.changed());
+        this.host.addEventListener('scroll', () => this.changed());
+    }
+    button(label, action) {
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.textContent = label;
+        button.addEventListener('click', action);
+        this.toolbar.append(button);
+    }
+    changed() {
+        document.dispatchEvent(new Event('wp-graph-transform'));
+    }
+    resize() {
+        if (this.svg === null)
+            return;
+        const box = this.svg.viewBox.baseVal;
+        this.svg.style.width = `${box.width * this.scale}px`;
+        this.svg.style.height = `${box.height * this.scale}px`;
+        this.status.textContent = `${Math.round(this.scale * 100)}%`;
+        this.changed();
+    }
+    zoom(factor) {
+        if (this.host === null)
+            return;
+        const before = this.scale;
+        this.scale = Math.max(0.1, Math.min(4, this.scale * factor));
+        const centerX = this.host.scrollLeft + this.host.clientWidth / 2;
+        const centerY = this.host.scrollTop + this.host.clientHeight / 2;
+        this.resize();
+        this.host.scrollLeft = (centerX * this.scale) / before - this.host.clientWidth / 2;
+        this.host.scrollTop = (centerY * this.scale) / before - this.host.clientHeight / 2;
+    }
+    reset() {
+        this.scale = 1;
+        this.resize();
+        this.scrollOrigin();
+    }
+    scrollOrigin() {
+        if (this.host === null)
+            return;
+        this.host.scrollLeft = 0;
+        this.host.scrollTop = 0;
+    }
+    fit() {
+        if (this.svg === null || this.host === null)
+            return;
+        this.scale = Math.min(1, this.host.clientWidth / this.svg.viewBox.baseVal.width, this.host.clientHeight / this.svg.viewBox.baseVal.height);
+        this.resize();
+        this.scrollOrigin();
+    }
+    attach() {
+        const next = this.host?.querySelector('svg');
+        if (next === null || next === undefined || next === this.svg)
+            return;
+        this.svg = next;
+        this.reset();
+    }
+}
+//# sourceMappingURL=graph-navigation.js.map