@webpieces/nx-webpieces-rules 0.4.920 → 0.4.922

package/src/executors/visualize-runtime-goal/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/visualize-runtime-goal/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Visualize Runtime Goal Executor (#1239)\n *\n * Renders the hand-authored runtime PROPOSAL, architecture/runtime-dependencies-goal.json, with the\n * same shared runtime renderer as visualize-runtime, into its own files:\n * tmp/webpieces/runtime-architecture-goal.{dot,html}. It never generates anything from source first,\n * never writes either JSON input, and never overwrites the current page.\n *\n * The page carries Goal vs Current when the saved current graph is usable; otherwise that mode says\n * why. A missing goal fails with its expected path and how to start one — the current graph is never\n * rendered in its place.\n *\n * `--prepare` is the one explicit, WRITING step: it recomputes the goal's derived levels, self-queue\n * flags, contract queues and maxLevel with the generator's own level machinery, saves the goal, and\n * then views it.\n *\n * Usage: nx run architecture:visualize-runtime-goal [--prepare]\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { ExecutorContext } from '@nx/devkit';\nimport { RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { DEFAULT_GRAPH_PATH } from '../../lib/graph-loader';\nimport { ImpactRefresh, ImpactSidecar, VISUALIZE_IMPACT_KINDS } from '../../lib/graph-impact';\nimport { SavedSnapshot } from '../../lib/saved-snapshot';\nimport { writeRuntimeVisualization, RuntimeVizOptions, RuntimePageKind } from '../../lib/runtime-visualizer';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { RuntimeComparisonInputs } from '../../lib/runtime-goal-view';\nimport { RuntimeGoalFile, RuntimeGoalProvenance, RUNTIME_GOAL_PREPARE_COMMAND } from '../../lib/runtime-goal-file';\nimport type { RuntimeGraph } from '../../lib/runtime-graph-model';\nimport { toError } from '../../toError';\n\nexport interface VisualizeRuntimeGoalOptions {\n    /** Recompute and SAVE the goal's derived levels before viewing. Viewing alone never writes. */\n    prepare?: boolean;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// webpieces-disable no-function-outside-class -- Nx executor entry point: Nx requires a default-exported function\nexport default async function runExecutor(\n    options: VisualizeRuntimeGoalOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n    const goalFile = new RuntimeGoalFile();\n    const snapshot = new SavedSnapshot();\n\n    console.log('\\n🎯 Runtime Goal Visualization\\n');\n    console.log(new RuntimeGoalProvenance().message());\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Nx command rendering boundary; success:false propagates failure to Nx\n    try {\n        const goal = options.prepare === true ? prepared(goalFile, workspaceRoot) : goalFile.load(workspaceRoot);\n        reportDrift(goalFile, goal);\n        const config = loadRuntimeConfig(workspaceRoot);\n        const projects = fs.existsSync(path.join(workspaceRoot, DEFAULT_GRAPH_PATH)) ? snapshot.loadProjects(workspaceRoot, DEFAULT_GRAPH_PATH).projects : null;\n        const vizOptions = new RuntimeVizOptions(config.showExternalNodes, projects, workspaceRoot, RuntimePageKind.GOAL);\n        const inputs = new RuntimeComparisonInputs(snapshot, goalFile);\n        const comparison = inputs.view(inputs.current(workspaceRoot), goal, vizOptions);\n        console.log(comparison.available ? `Goal vs Current: ${comparison.summary}` : `Goal vs Current unavailable: ${comparison.reason}`);\n        const vizPaths = writeRuntimeVisualization(goal, workspaceRoot, 'Goal / Proposed Runtime Architecture', vizOptions, comparison);\n        console.log(`✅ Generated: ${vizPaths.dotPath}`);\n        console.log(`✅ Generated: ${vizPaths.htmlPath}`);\n        if (projects !== null) console.log(await new ImpactRefresh().run(path.dirname(vizPaths.htmlPath), workspaceRoot, projects, VISUALIZE_IMPACT_KINDS));\n        else { new ImpactSidecar().remove(path.dirname(vizPaths.htmlPath)); console.log('Impact and framework metadata unavailable: no saved project graph. Proposed services carry their goal facts only.'); }\n\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (new GraphVisualizer().openVisualization(vizPaths.htmlPath)) console.log('✅ Browser opened');\n        else console.log(`⚠️  Could not auto-open. Open manually: ${vizPaths.htmlPath}`);\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        const rendered = error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error(`❌ Runtime goal visualization failed for ${goalFile.goalPath}:`, rendered);\n        return { success: false };\n    }\n}\n\n// webpieces-disable no-function-outside-class -- executor step helper, sibling of runExecutor\nfunction prepared(goalFile: RuntimeGoalFile, workspaceRoot: string): RuntimeGraph {\n    const preparation = goalFile.prepare(workspaceRoot);\n    if (!preparation.written) console.log(`✅ ${goalFile.goalPath} derived facts already consistent; nothing written.`);\n    else if (preparation.changes.length === 0) console.log(`✍️  Prepared ${goalFile.goalPath}: rewrote explanatory levelBecause text only.`);\n    else console.log(`✍️  Prepared ${goalFile.goalPath}:\\n  ${preparation.changes.join('\\n  ')}`);\n    return preparation.graph;\n}\n\n// webpieces-disable no-function-outside-class -- executor step helper, sibling of runExecutor\nfunction reportDrift(goalFile: RuntimeGoalFile, goal: RuntimeGraph): void {\n    const drift = goalFile.drift(goal);\n    if (drift.cycle !== null) {\n        console.warn(`⚠️  ${drift.cycle}\\n  Rendered with its saved levels. ${goalFile.cycleOption().text}`);\n        return;\n    }\n    if (drift.differences.length === 0) return;\n    console.warn(\n        `⚠️  ${goalFile.goalPath} saves derived facts that disagree with its relationships (rendered as saved):\\n  ` +\n            `${drift.differences.join('\\n  ')}\\n  Recompute them explicitly: ${RUNTIME_GOAL_PREPARE_COMMAND}`,\n    );\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/visualize-runtime-goal/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Visualize Runtime Goal Executor (#1239)\n *\n * Renders the hand-authored runtime PROPOSAL, architecture/runtime-dependencies-goal.json, with the\n * same shared runtime renderer as visualize-runtime, into its own files:\n * tmp/webpieces/runtime-architecture-goal.{dot,html}. It never generates anything from source first,\n * never writes either JSON input, and never overwrites the current page.\n *\n * The page carries Goal vs Current when the saved current graph is usable; otherwise that mode says\n * why. A missing goal fails with its expected path and how to start one — the current graph is never\n * rendered in its place.\n *\n * `--prepare` is the one explicit, WRITING step: it recomputes the goal's derived levels, self-queue\n * flags, contract queues and maxLevel with the generator's own level machinery, saves the goal, and\n * then views it.\n *\n * Usage: nx run architecture:visualize-runtime-goal [--prepare]\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { ExecutorContext } from '@nx/devkit';\nimport { RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { DEFAULT_GRAPH_PATH } from '../../lib/graph-loader';\nimport { ImpactRefresh, ImpactSidecar, VISUALIZE_IMPACT_KINDS } from '../../lib/graph-impact';\nimport { LiveGraphSource } from '../../lib/graph-edge-diff';\nimport { SavedSnapshot } from '../../lib/saved-snapshot';\nimport { writeRuntimeVisualization, RuntimeVizOptions, RuntimePageKind } from '../../lib/runtime-visualizer';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { RuntimeComparisonInputs } from '../../lib/runtime-goal-view';\nimport { RuntimeGoalFile, RuntimeGoalProvenance, RUNTIME_GOAL_PREPARE_COMMAND } from '../../lib/runtime-goal-file';\nimport type { RuntimeGraph } from '../../lib/runtime-graph-model';\nimport { toError } from '../../toError';\n\nexport interface VisualizeRuntimeGoalOptions {\n    /** Recompute and SAVE the goal's derived levels before viewing. Viewing alone never writes. */\n    prepare?: boolean;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// webpieces-disable no-function-outside-class -- Nx executor entry point: Nx requires a default-exported function\nexport default async function runExecutor(\n    options: VisualizeRuntimeGoalOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n    const goalFile = new RuntimeGoalFile();\n    const snapshot = new SavedSnapshot();\n\n    console.log('\\n🎯 Runtime Goal Visualization\\n');\n    console.log(new RuntimeGoalProvenance().message());\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Nx command rendering boundary; success:false propagates failure to Nx\n    try {\n        const goal = options.prepare === true ? prepared(goalFile, workspaceRoot) : goalFile.load(workspaceRoot);\n        reportDrift(goalFile, goal);\n        const config = loadRuntimeConfig(workspaceRoot);\n        const projects = fs.existsSync(path.join(workspaceRoot, DEFAULT_GRAPH_PATH)) ? snapshot.loadProjects(workspaceRoot, DEFAULT_GRAPH_PATH).projects : null;\n        const vizOptions = new RuntimeVizOptions(config.showExternalNodes, projects, workspaceRoot, RuntimePageKind.GOAL);\n        const inputs = new RuntimeComparisonInputs(snapshot, goalFile);\n        const comparison = inputs.view(inputs.current(workspaceRoot), goal, vizOptions);\n        console.log(comparison.available ? `Goal vs Current: ${comparison.summary}` : `Goal vs Current unavailable: ${comparison.reason}`);\n        const vizPaths = writeRuntimeVisualization(goal, workspaceRoot, 'Goal / Proposed Runtime Architecture', vizOptions, comparison);\n        console.log(`✅ Generated: ${vizPaths.dotPath}`);\n        console.log(`✅ Generated: ${vizPaths.htmlPath}`);\n        if (projects !== null) console.log(await new ImpactRefresh().run(path.dirname(vizPaths.htmlPath), workspaceRoot, projects, VISUALIZE_IMPACT_KINDS, new LiveGraphSource()));\n        else { new ImpactSidecar().remove(path.dirname(vizPaths.htmlPath)); console.log('Impact and framework metadata unavailable: no saved project graph. Proposed services carry their goal facts only.'); }\n\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (new GraphVisualizer().openVisualization(vizPaths.htmlPath)) console.log('✅ Browser opened');\n        else console.log(`⚠️  Could not auto-open. Open manually: ${vizPaths.htmlPath}`);\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        const rendered = error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error(`❌ Runtime goal visualization failed for ${goalFile.goalPath}:`, rendered);\n        return { success: false };\n    }\n}\n\n// webpieces-disable no-function-outside-class -- executor step helper, sibling of runExecutor\nfunction prepared(goalFile: RuntimeGoalFile, workspaceRoot: string): RuntimeGraph {\n    const preparation = goalFile.prepare(workspaceRoot);\n    if (!preparation.written) console.log(`✅ ${goalFile.goalPath} derived facts already consistent; nothing written.`);\n    else if (preparation.changes.length === 0) console.log(`✍️  Prepared ${goalFile.goalPath}: rewrote explanatory levelBecause text only.`);\n    else console.log(`✍️  Prepared ${goalFile.goalPath}:\\n  ${preparation.changes.join('\\n  ')}`);\n    return preparation.graph;\n}\n\n// webpieces-disable no-function-outside-class -- executor step helper, sibling of runExecutor\nfunction reportDrift(goalFile: RuntimeGoalFile, goal: RuntimeGraph): void {\n    const drift = goalFile.drift(goal);\n    if (drift.cycle !== null) {\n        console.warn(`⚠️  ${drift.cycle}\\n  Rendered with its saved levels. ${goalFile.cycleOption().text}`);\n        return;\n    }\n    if (drift.differences.length === 0) return;\n    console.warn(\n        `⚠️  ${goalFile.goalPath} saves derived facts that disagree with its relationships (rendered as saved):\\n  ` +\n            `${drift.differences.join('\\n  ')}\\n  Recompute them explicitly: ${RUNTIME_GOAL_PREPARE_COMMAND}`,\n    );\n}\n"]}

package/src/lib/current-architecture.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The architecture graph as the CURRENT source says it is, built live by the same pipeline
+ * `architecture:generate` runs — never read back from the committed architecture/*.json. Shared by
+ * `validate-architecture-unchanged` (which diffs it against the committed file) and the Impact view's
+ * edge changes (#1264, which diff it against the fork point's committed file).
+ */
+import type { EnhancedGraph } from './graph-sorter';
+import type { ExternalSystemDecls } from './api-usage/api-relations';
+import type { ApiContractFileRefs } from './api-contract-files';
+import type { RemoteServices } from './remote-services';
+/**
+ * Build the current dependency graph exactly as the generator does: reduce the nx
+ * graph, sort into levels, enrich with metadata, and attach the derived
+ * apiRelations — so this validator compares like-for-like against the committed file.
+ */
+export declare class CurrentGraphBuilder {
+    build(workspaceRoot: string, graphPath?: string): Promise<CurrentArchitecture>;
+}
+/** The regenerated graph plus the tables beside it — everything dependencies.json holds. */
+export declare class CurrentArchitecture {
+    readonly graph: EnhancedGraph;
+    readonly apiContractFiles: ApiContractFileRefs;
+    readonly externalSystems: ExternalSystemDecls;
+    readonly remoteServices: RemoteServices;
+    constructor(graph: EnhancedGraph, apiContractFiles: ApiContractFileRefs, externalSystems: ExternalSystemDecls, remoteServices: RemoteServices);
+}

package/src/lib/current-architecture.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * The architecture graph as the CURRENT source says it is, built live by the same pipeline
+ * `architecture:generate` runs — never read back from the committed architecture/*.json. Shared by
+ * `validate-architecture-unchanged` (which diffs it against the committed file) and the Impact view's
+ * edge changes (#1264, which diff it against the fork point's committed file).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CurrentArchitecture = exports.CurrentGraphBuilder = void 0;
+const rules_config_1 = require("@webpieces/rules-config");
+const graph_generator_1 = require("./graph-generator");
+const graph_sorter_1 = require("./graph-sorter");
+const graph_loader_1 = require("./graph-loader");
+const graph_metadata_1 = require("./graph-metadata");
+const tag_truth_1 = require("./tag-truth");
+const approved_graph_1 = require("./runtime-wiring/approved-graph");
+/**
+ * Build the current dependency graph exactly as the generator does: reduce the nx
+ * graph, sort into levels, enrich with metadata, and attach the derived
+ * apiRelations — so this validator compares like-for-like against the committed file.
+ */
+class CurrentGraphBuilder {
+    async build(workspaceRoot, graphPath) {
+        console.log('📊 Generating current dependency graph...');
+        const reducedGraph = await (0, graph_generator_1.generateReducedGraph)();
+        console.log('🔄 Computing topological layers...');
+        const currentGraph = (0, graph_sorter_1.sortGraphTopologically)(reducedGraph);
+        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');
+        const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
+        (0, graph_metadata_1.enrichGraph)(currentGraph, projectInfos, workspaceRoot);
+        new tag_truth_1.TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);
+        new approved_graph_1.ApprovedWiringGraph().attach(workspaceRoot, currentGraph, projectInfos, graphPath);
+        const saved = (0, graph_loader_1.loadBlessedGraph)(workspaceRoot, graphPath);
+        if (saved === null)
+            throw new rules_config_1.RuleFailError('validate-runtime-architecture', 'Missing approved graph.', undefined, undefined, [
+                new rules_config_1.Option('Migrate src/wiring.ts and review runtime-deps.json and API contract approvals.', true),
+            ]);
+        return new CurrentArchitecture(currentGraph, saved.apiContractFiles, saved.externalSystems, saved.remoteServices);
+    }
+}
+exports.CurrentGraphBuilder = CurrentGraphBuilder;
+/** The regenerated graph plus the tables beside it — everything dependencies.json holds. */
+class CurrentArchitecture {
+    graph;
+    apiContractFiles;
+    externalSystems;
+    remoteServices;
+    constructor(graph, apiContractFiles, externalSystems, remoteServices) {
+        this.graph = graph;
+        this.apiContractFiles = apiContractFiles;
+        this.externalSystems = externalSystems;
+        this.remoteServices = remoteServices;
+    }
+}
+exports.CurrentArchitecture = CurrentArchitecture;
+//# sourceMappingURL=current-architecture.js.map

package/src/lib/current-architecture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-architecture.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/current-architecture.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,0DAAgE;AAChE,uDAAyD;AACzD,iDAAwD;AAExD,iDAAkD;AAClD,qDAAmE;AACnE,2CAA4C;AAC5C,oEAAsE;AAKtE;;;;GAIG;AACH,MAAa,mBAAmB;IAC5B,KAAK,CAAC,KAAK,CAAC,aAAqB,EAAE,SAAkB;QACjD,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;QACzD,MAAM,YAAY,GAAG,MAAM,IAAA,sCAAoB,GAAE,CAAC;QAClD,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,IAAA,qCAAsB,EAAC,YAAY,CAAC,CAAC;QAC1D,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;QAClF,MAAM,YAAY,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QAChD,IAAA,4BAAW,EAAC,YAAY,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;QACvD,IAAI,yBAAa,EAAE,CAAC,UAAU,CAAC,YAAY,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;QAC1E,IAAI,oCAAmB,EAAE,CAAC,MAAM,CAAC,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;QACvF,MAAM,KAAK,GAAG,IAAA,+BAAgB,EAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QACzD,IAAI,KAAK,KAAK,IAAI;YACd,MAAM,IAAI,4BAAa,CACnB,+BAA+B,EAC/B,yBAAyB,EACzB,SAAS,EACT,SAAS,EACT;gBACI,IAAI,qBAAM,CACN,gFAAgF,EAChF,IAAI,CACP;aACJ,CACJ,CAAC;QACN,OAAO,IAAI,mBAAmB,CAC1B,YAAY,EACZ,KAAK,CAAC,gBAAgB,EACtB,KAAK,CAAC,eAAe,EACrB,KAAK,CAAC,cAAc,CACvB,CAAC;IACN,CAAC;CACJ;AAhCD,kDAgCC;AAED,4FAA4F;AAC5F,MAAa,mBAAmB;IAER;IACA;IACA;IACA;IAJpB,YACoB,KAAoB,EACpB,gBAAqC,EACrC,eAAoC,EACpC,cAA8B;QAH9B,UAAK,GAAL,KAAK,CAAe;QACpB,qBAAgB,GAAhB,gBAAgB,CAAqB;QACrC,oBAAe,GAAf,eAAe,CAAqB;QACpC,mBAAc,GAAd,cAAc,CAAgB;IAC/C,CAAC;CACP;AAPD,kDAOC","sourcesContent":["/**\n * The architecture graph as the CURRENT source says it is, built live by the same pipeline\n * `architecture:generate` runs — never read back from the committed architecture/*.json. Shared by\n * `validate-architecture-unchanged` (which diffs it against the committed file) and the Impact view's\n * edge changes (#1264, which diff it against the fork point's committed file).\n */\n\nimport { Option, RuleFailError } from '@webpieces/rules-config';\nimport { generateReducedGraph } from './graph-generator';\nimport { sortGraphTopologically } from './graph-sorter';\nimport type { EnhancedGraph } from './graph-sorter';\nimport { loadBlessedGraph } from './graph-loader';\nimport { collectProjectInfo, enrichGraph } from './graph-metadata';\nimport { TagTruthCheck } from './tag-truth';\nimport { ApprovedWiringGraph } from './runtime-wiring/approved-graph';\nimport type { ExternalSystemDecls } from './api-usage/api-relations';\nimport type { ApiContractFileRefs } from './api-contract-files';\nimport type { RemoteServices } from './remote-services';\n\n/**\n * Build the current dependency graph exactly as the generator does: reduce the nx\n * graph, sort into levels, enrich with metadata, and attach the derived\n * apiRelations — so this validator compares like-for-like against the committed file.\n */\nexport class CurrentGraphBuilder {\n    async build(workspaceRoot: string, graphPath?: string): Promise<CurrentArchitecture> {\n        console.log('📊 Generating current dependency graph...');\n        const reducedGraph = await generateReducedGraph();\n        console.log('🔄 Computing topological layers...');\n        const currentGraph = sortGraphTopologically(reducedGraph);\n        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n        const projectInfos = await collectProjectInfo();\n        enrichGraph(currentGraph, projectInfos, workspaceRoot);\n        new TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);\n        new ApprovedWiringGraph().attach(workspaceRoot, currentGraph, projectInfos, graphPath);\n        const saved = loadBlessedGraph(workspaceRoot, graphPath);\n        if (saved === null)\n            throw new RuleFailError(\n                'validate-runtime-architecture',\n                'Missing approved graph.',\n                undefined,\n                undefined,\n                [\n                    new Option(\n                        'Migrate src/wiring.ts and review runtime-deps.json and API contract approvals.',\n                        true,\n                    ),\n                ],\n            );\n        return new CurrentArchitecture(\n            currentGraph,\n            saved.apiContractFiles,\n            saved.externalSystems,\n            saved.remoteServices,\n        );\n    }\n}\n\n/** The regenerated graph plus the tables beside it — everything dependencies.json holds. */\nexport class CurrentArchitecture {\n    constructor(\n        public readonly graph: EnhancedGraph,\n        public readonly apiContractFiles: ApiContractFileRefs,\n        public readonly externalSystems: ExternalSystemDecls,\n        public readonly remoteServices: RemoteServices,\n    ) {}\n}\n"]}

package/src/lib/graph-edge-diff.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Edge changes against the base (#1264): which dependency and runtime edges this branch GAINED or
+ * LOST, so "why is this building?" is answerable for a project whose only change is an edge.
+ *
+ * BASE is the FORK POINT — the branch comparison's `git merge-base HEAD origin/main` — read as
+ * `git show <forkPoint>:architecture/dependencies.json` and `…:architecture/runtime-dependencies.json`.
+ * Main keeps both regenerated and validated (`validate-architecture-unchanged`), so the fork point's
+ * copies are trustworthy.
+ *
+ * CURRENT is the graph computed LIVE when the page is refreshed (`LiveGraphSource`: the same pipeline
+ * `architecture:generate` runs), NEVER HEAD's committed architecture/*.json. Whether or not the branch
+ * already regenerated and committed those files must not matter: comparing against HEAD's committed
+ * copy would show no change at all once it had been regenerated.
+ *
+ * Neither file at the fork point (first adoption) is an answer, not an error: no edge diff, and the
+ * page says why. Nothing here ever throws into generation.
+ */
+import type { EnhancedGraph } from './graph-sorter';
+import type { RuntimeGraph } from './runtime-graph-model';
+export declare enum EdgeChangeKind {
+    GAINED = "gained",
+    LOST = "lost"
+}
+export declare enum EdgeRelation {
+    /** A build dependency (architecture/dependencies.json `dependsOn`). */
+    DEPENDS = "depends",
+    /** A runtime call (architecture/runtime-dependencies.json `runtimeEdges`). */
+    CALLS = "calls"
+}
+/** One gained or lost edge, `from` → `to` (node ids), with the words the page shows for it. */
+export declare class EdgeChange {
+    readonly from: string;
+    readonly to: string;
+    readonly change: EdgeChangeKind;
+    readonly relation: EdgeRelation;
+    /** CALLS: the APIs gained or lost on this edge, sorted. Empty for DEPENDS. */
+    readonly apis: string[];
+    /** "new on this branch: a now depends on b" / "a no longer calls b (SaveApi)". */
+    readonly text: string;
+    constructor(from: string, to: string, change: EdgeChangeKind, relation: EdgeRelation, 
+    /** CALLS: the APIs gained or lost on this edge, sorted. Empty for DEPENDS. */
+    apis: string[], 
+    /** "new on this branch: a now depends on b" / "a no longer calls b (SaveApi)". */
+    text: string);
+}
+/** The edge changes of the dependency graph and of the runtime graph, or why each is not shown. */
+export declare class EdgeDiffReport {
+    /** The fork point's short sha ('' when there is none). */
+    readonly base: string;
+    /** '' when `dependency` was computed; otherwise why the page shows no dependency edge changes. */
+    readonly dependencyReason: string;
+    readonly dependency: EdgeChange[];
+    /** '' when `runtime` was computed; otherwise why the page shows no runtime edge changes. */
+    readonly runtimeReason: string;
+    readonly runtime: EdgeChange[];
+    constructor(
+    /** The fork point's short sha ('' when there is none). */
+    base: string, 
+    /** '' when `dependency` was computed; otherwise why the page shows no dependency edge changes. */
+    dependencyReason: string, dependency: EdgeChange[], 
+    /** '' when `runtime` was computed; otherwise why the page shows no runtime edge changes. */
+    runtimeReason: string, runtime: EdgeChange[]);
+}
+/** The two graphs the branch has NOW, computed live. `runtime` null when it could not be derived. */
+export declare class LiveGraphs {
+    readonly projects: EnhancedGraph;
+    readonly runtime: RuntimeGraph | null;
+    /** Why `runtime` is null ('' otherwise). */
+    readonly runtimeReason: string;
+    constructor(projects: EnhancedGraph, runtime: RuntimeGraph | null, 
+    /** Why `runtime` is null ('' otherwise). */
+    runtimeReason?: string);
+}
+/**
+ * Computes the live graphs: `CurrentGraphBuilder` (generate's own pipeline, writing nothing) and the
+ * runtime graph derived from it exactly as generate derives it. `architecture:generate` passes the
+ * graphs it just built instead (`FixedLiveGraphs`), so nothing is computed twice.
+ */
+export declare class LiveGraphSource {
+    graphs(workspaceRoot: string): Promise<LiveGraphs>;
+}
+/** The graphs a caller already holds (architecture:generate just built them). */
+export declare class FixedLiveGraphs extends LiveGraphSource {
+    private readonly live;
+    constructor(live: LiveGraphs);
+    graphs(): Promise<LiveGraphs>;
+}
+/** A committed file as it was at a commit. Injected so specs never spawn git. */
+export declare class GitFileAt {
+    /** The file's text at `sha`; null when it did not exist there (or git cannot answer). */
+    read(workspaceRoot: string, sha: string, file: string): string | null;
+}
+/** Diffs base against live; pure. */
+export declare class EdgeDiffer {
+    dependency(base: EnhancedGraph, live: EnhancedGraph): EdgeChange[];
+    runtime(base: RuntimeGraph, live: RuntimeGraph): EdgeChange[];
+    private dependencyEdges;
+    private runtimeEdges;
+    /** Per edge: gained when absent at base; lost when absent now; for a call, the APIs that came or went. */
+    private compare;
+    private change;
+}
+/** Reads the fork point's committed graphs and diffs them against the live ones. Never throws. */
+export declare class EdgeChangeScanner {
+    private readonly git;
+    private readonly differ;
+    constructor(git?: GitFileAt, differ?: EdgeDiffer);
+    scan(workspaceRoot: string, forkPoint: string | null, source: LiveGraphSource): Promise<EdgeDiffReport>;
+    /** No edge changes to show, with the one reason the page says instead. */
+    private none;
+    /** dependencies.json's `projects` at the fork point; null when absent or not that shape. */
+    private projectsAt;
+    private runtimeAt;
+    private parse;
+}

package/src/lib/graph-edge-diff.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Edge changes against the base (#1264): which dependency and runtime edges this branch GAINED or
+ * LOST, so "why is this building?" is answerable for a project whose only change is an edge.
+ *
+ * BASE is the FORK POINT — the branch comparison's `git merge-base HEAD origin/main` — read as
+ * `git show <forkPoint>:architecture/dependencies.json` and `…:architecture/runtime-dependencies.json`.
+ * Main keeps both regenerated and validated (`validate-architecture-unchanged`), so the fork point's
+ * copies are trustworthy.
+ *
+ * CURRENT is the graph computed LIVE when the page is refreshed (`LiveGraphSource`: the same pipeline
+ * `architecture:generate` runs), NEVER HEAD's committed architecture/*.json. Whether or not the branch
+ * already regenerated and committed those files must not matter: comparing against HEAD's committed
+ * copy would show no change at all once it had been regenerated.
+ *
+ * Neither file at the fork point (first adoption) is an answer, not an error: no edge diff, and the
+ * page says why. Nothing here ever throws into generation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EdgeChangeScanner = exports.EdgeDiffer = exports.GitFileAt = exports.FixedLiveGraphs = exports.LiveGraphSource = exports.LiveGraphs = exports.EdgeDiffReport = exports.EdgeChange = exports.EdgeRelation = exports.EdgeChangeKind = void 0;
+const child_process_1 = require("child_process");
+const graph_loader_1 = require("./graph-loader");
+const runtime_graph_io_1 = require("./runtime-graph-io");
+const runtime_graph_1 = require("./runtime-graph");
+const api_contract_files_1 = require("./api-contract-files");
+const current_architecture_1 = require("./current-architecture");
+const toError_1 = require("../toError");
+var EdgeChangeKind;
+(function (EdgeChangeKind) {
+    EdgeChangeKind["GAINED"] = "gained";
+    EdgeChangeKind["LOST"] = "lost";
+})(EdgeChangeKind || (exports.EdgeChangeKind = EdgeChangeKind = {}));
+var EdgeRelation;
+(function (EdgeRelation) {
+    /** A build dependency (architecture/dependencies.json `dependsOn`). */
+    EdgeRelation["DEPENDS"] = "depends";
+    /** A runtime call (architecture/runtime-dependencies.json `runtimeEdges`). */
+    EdgeRelation["CALLS"] = "calls";
+})(EdgeRelation || (exports.EdgeRelation = EdgeRelation = {}));
+/** One gained or lost edge, `from` → `to` (node ids), with the words the page shows for it. */
+class EdgeChange {
+    from;
+    to;
+    change;
+    relation;
+    apis;
+    text;
+    constructor(from, to, change, relation, 
+    /** CALLS: the APIs gained or lost on this edge, sorted. Empty for DEPENDS. */
+    apis, 
+    /** "new on this branch: a now depends on b" / "a no longer calls b (SaveApi)". */
+    text) {
+        this.from = from;
+        this.to = to;
+        this.change = change;
+        this.relation = relation;
+        this.apis = apis;
+        this.text = text;
+    }
+}
+exports.EdgeChange = EdgeChange;
+/** The edge changes of the dependency graph and of the runtime graph, or why each is not shown. */
+class EdgeDiffReport {
+    base;
+    dependencyReason;
+    dependency;
+    runtimeReason;
+    runtime;
+    constructor(
+    /** The fork point's short sha ('' when there is none). */
+    base, 
+    /** '' when `dependency` was computed; otherwise why the page shows no dependency edge changes. */
+    dependencyReason, dependency, 
+    /** '' when `runtime` was computed; otherwise why the page shows no runtime edge changes. */
+    runtimeReason, runtime) {
+        this.base = base;
+        this.dependencyReason = dependencyReason;
+        this.dependency = dependency;
+        this.runtimeReason = runtimeReason;
+        this.runtime = runtime;
+    }
+}
+exports.EdgeDiffReport = EdgeDiffReport;
+/** The two graphs the branch has NOW, computed live. `runtime` null when it could not be derived. */
+class LiveGraphs {
+    projects;
+    runtime;
+    runtimeReason;
+    constructor(projects, runtime, 
+    /** Why `runtime` is null ('' otherwise). */
+    runtimeReason = '') {
+        this.projects = projects;
+        this.runtime = runtime;
+        this.runtimeReason = runtimeReason;
+    }
+}
+exports.LiveGraphs = LiveGraphs;
+/**
+ * Computes the live graphs: `CurrentGraphBuilder` (generate's own pipeline, writing nothing) and the
+ * runtime graph derived from it exactly as generate derives it. `architecture:generate` passes the
+ * graphs it just built instead (`FixedLiveGraphs`), so nothing is computed twice.
+ */
+class LiveGraphSource {
+    async graphs(workspaceRoot) {
+        const current = await new current_architecture_1.CurrentGraphBuilder().build(workspaceRoot);
+        const hidden = new Set(Object.keys(current.graph).filter((name) => current.graph[name].drawOnGraph === false));
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- the runtime half is optional; the dependency half still shows
+        try {
+            const contracts = new api_contract_files_1.ApiContractFiles().load(workspaceRoot, graph_loader_1.DEFAULT_GRAPH_PATH, current.apiContractFiles);
+            const report = (0, runtime_graph_1.deriveRuntimeGraphReport)(current.graph, hidden, contracts, current.externalSystems, current.remoteServices);
+            return new LiveGraphs(current.graph, report.graph);
+        }
+        catch (err) {
+            const error = (0, toError_1.toError)(err);
+            return new LiveGraphs(current.graph, null, `the live runtime graph could not be derived (${error.message})`);
+        }
+    }
+}
+exports.LiveGraphSource = LiveGraphSource;
+/** The graphs a caller already holds (architecture:generate just built them). */
+class FixedLiveGraphs extends LiveGraphSource {
+    live;
+    constructor(live) {
+        super();
+        this.live = live;
+    }
+    async graphs() {
+        return this.live;
+    }
+}
+exports.FixedLiveGraphs = FixedLiveGraphs;
+/** A committed file as it was at a commit. Injected so specs never spawn git. */
+class GitFileAt {
+    /** The file's text at `sha`; null when it did not exist there (or git cannot answer). */
+    read(workspaceRoot, sha, file) {
+        const shown = (0, child_process_1.spawnSync)('git', ['show', `${sha}:${file}`], {
+            cwd: workspaceRoot,
+            encoding: 'utf8',
+            stdio: 'pipe',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        return shown.status === 0 ? shown.stdout : null;
+    }
+}
+exports.GitFileAt = GitFileAt;
+/** The base graphs' edges: `from|to` → the APIs on that edge (empty for a dependency). */
+class EdgeSet {
+    edges = new Map();
+    add(from, to, apis) {
+        const key = `${from}\u0000${to}`;
+        const known = this.edges.get(key) ?? new Set();
+        for (const api of apis)
+            known.add(api);
+        this.edges.set(key, known);
+    }
+}
+/** Diffs base against live; pure. */
+class EdgeDiffer {
+    dependency(base, live) {
+        return this.compare(this.dependencyEdges(base), this.dependencyEdges(live), EdgeRelation.DEPENDS);
+    }
+    runtime(base, live) {
+        return this.compare(this.runtimeEdges(base), this.runtimeEdges(live), EdgeRelation.CALLS);
+    }
+    dependencyEdges(graph) {
+        const set = new EdgeSet();
+        for (const name of Object.keys(graph))
+            for (const dep of graph[name].dependsOn ?? [])
+                set.add(name, dep, []);
+        return set;
+    }
+    runtimeEdges(graph) {
+        const set = new EdgeSet();
+        for (const edge of graph.runtimeEdges ?? [])
+            set.add(edge.from, edge.to, edge.via ?? []);
+        return set;
+    }
+    /** Per edge: gained when absent at base; lost when absent now; for a call, the APIs that came or went. */
+    compare(base, live, relation) {
+        const changes = [];
+        const keys = [...new Set([...base.edges.keys(), ...live.edges.keys()])].sort();
+        for (const key of keys) {
+            const ends = key.split('\u0000');
+            const before = base.edges.get(key);
+            const after = live.edges.get(key);
+            const gained = after === undefined ? [] : [...after].filter((api) => before === undefined || !before.has(api));
+            const lost = before === undefined ? [] : [...before].filter((api) => after === undefined || !after.has(api));
+            if (before === undefined || gained.length > 0)
+                changes.push(this.change(ends[0], ends[1], EdgeChangeKind.GAINED, relation, gained.sort()));
+            if (after === undefined || lost.length > 0)
+                changes.push(this.change(ends[0], ends[1], EdgeChangeKind.LOST, relation, lost.sort()));
+        }
+        return changes;
+    }
+    change(from, to, kind, relation, apis) {
+        const verb = relation === EdgeRelation.DEPENDS ? 'depends on' : 'calls';
+        const via = apis.length === 0 ? '' : ` (${apis.join(', ')})`;
+        const text = kind === EdgeChangeKind.GAINED
+            ? `new on this branch: ${from} now ${verb} ${to}${via}`
+            : `${from} no longer ${verb} ${to}${via}`;
+        return new EdgeChange(from, to, kind, relation, apis, text);
+    }
+}
+exports.EdgeDiffer = EdgeDiffer;
+/** Reads the fork point's committed graphs and diffs them against the live ones. Never throws. */
+class EdgeChangeScanner {
+    git;
+    differ;
+    constructor(git = new GitFileAt(), differ = new EdgeDiffer()) {
+        this.git = git;
+        this.differ = differ;
+    }
+    async scan(workspaceRoot, forkPoint, source) {
+        if (forkPoint === null)
+            return this.none('Edge changes compare a branch with its fork point; there is no branch comparison here (main or a detached HEAD)');
+        const short = forkPoint.slice(0, 7);
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- edge changes are optional; a failure becomes the reason the page shows
+        try {
+            const baseProjects = this.projectsAt(workspaceRoot, forkPoint);
+            const baseRuntime = this.runtimeAt(workspaceRoot, forkPoint);
+            if (baseProjects === null && baseRuntime === null)
+                return this.none(`No architecture graph at the fork point ${short} (first adoption), so there is nothing to compare edges against`, short);
+            const live = await source.graphs(workspaceRoot);
+            const dependencyReason = baseProjects === null ? `No ${graph_loader_1.DEFAULT_GRAPH_PATH} at the fork point ${short}` : '';
+            const runtimeReason = baseRuntime === null ? `No ${runtime_graph_io_1.DEFAULT_RUNTIME_GRAPH_PATH} at the fork point ${short}` : live.runtimeReason;
+            return new EdgeDiffReport(short, dependencyReason, baseProjects === null ? [] : this.differ.dependency(baseProjects, live.projects), runtimeReason, baseRuntime === null || live.runtime === null ? [] : this.differ.runtime(baseRuntime, live.runtime));
+        }
+        catch (err) {
+            const error = (0, toError_1.toError)(err);
+            return this.none(`Edge changes unavailable: ${error.message}`, short);
+        }
+    }
+    /** No edge changes to show, with the one reason the page says instead. */
+    none(reason, base = '') {
+        return new EdgeDiffReport(base, reason, [], reason, []);
+    }
+    /** dependencies.json's `projects` at the fork point; null when absent or not that shape. */
+    projectsAt(workspaceRoot, sha) {
+        const parsed = this.parse(this.git.read(workspaceRoot, sha, graph_loader_1.DEFAULT_GRAPH_PATH));
+        const projects = parsed === null ? undefined : parsed.projects;
+        return projects !== undefined && typeof projects === 'object' && projects !== null ? projects : null;
+    }
+    runtimeAt(workspaceRoot, sha) {
+        const parsed = this.parse(this.git.read(workspaceRoot, sha, runtime_graph_io_1.DEFAULT_RUNTIME_GRAPH_PATH));
+        return parsed !== null && Array.isArray(parsed.runtimeEdges) ? parsed : null;
+    }
+    // webpieces-disable no-any-unknown -- committed JSON from another commit is untrusted until narrowed by the caller
+    parse(text) {
+        if (text === null)
+            return null;
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an unreadable file at the fork point is the same as no file there
+        try {
+            return JSON.parse(text);
+        }
+        catch (err) {
+            const error = (0, toError_1.toError)(err);
+            void error; // not JSON at the fork point: treated as absent
+            return null;
+        }
+    }
+}
+exports.EdgeChangeScanner = EdgeChangeScanner;
+//# sourceMappingURL=graph-edge-diff.js.map

package/src/lib/graph-edge-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-edge-diff.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-edge-diff.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Edge changes against the base (#1264): which dependency and runtime edges this branch GAINED or\n * LOST, so \"why is this building?\" is answerable for a project whose only change is an edge.\n *\n * BASE is the FORK POINT — the branch comparison's `git merge-base HEAD origin/main` — read as\n * `git show <forkPoint>:architecture/dependencies.json` and `…:architecture/runtime-dependencies.json`.\n * Main keeps both regenerated and validated (`validate-architecture-unchanged`), so the fork point's\n * copies are trustworthy.\n *\n * CURRENT is the graph computed LIVE when the page is refreshed (`LiveGraphSource`: the same pipeline\n * `architecture:generate` runs), NEVER HEAD's committed architecture/*.json. Whether or not the branch\n * already regenerated and committed those files must not matter: comparing against HEAD's committed\n * copy would show no change at all once it had been regenerated.\n *\n * Neither file at the fork point (first adoption) is an answer, not an error: no edge diff, and the\n * page says why. Nothing here ever throws into generation.\n */\n\nimport { spawnSync } from 'child_process';\nimport { DEFAULT_GRAPH_PATH } from './graph-loader';\nimport type { EnhancedGraph } from './graph-sorter';\nimport { DEFAULT_RUNTIME_GRAPH_PATH } from './runtime-graph-io';\nimport type { RuntimeGraph } from './runtime-graph-model';\nimport { deriveRuntimeGraphReport } from './runtime-graph';\nimport { ApiContractFiles } from './api-contract-files';\nimport { CurrentGraphBuilder } from './current-architecture';\nimport { toError } from '../toError';\n\nexport enum EdgeChangeKind {\n    GAINED = 'gained',\n    LOST = 'lost',\n}\n\nexport enum EdgeRelation {\n    /** A build dependency (architecture/dependencies.json `dependsOn`). */\n    DEPENDS = 'depends',\n    /** A runtime call (architecture/runtime-dependencies.json `runtimeEdges`). */\n    CALLS = 'calls',\n}\n\n/** One gained or lost edge, `from` → `to` (node ids), with the words the page shows for it. */\nexport class EdgeChange {\n    constructor(\n        public readonly from: string,\n        public readonly to: string,\n        public readonly change: EdgeChangeKind,\n        public readonly relation: EdgeRelation,\n        /** CALLS: the APIs gained or lost on this edge, sorted. Empty for DEPENDS. */\n        public readonly apis: string[],\n        /** \"new on this branch: a now depends on b\" / \"a no longer calls b (SaveApi)\". */\n        public readonly text: string,\n    ) {}\n}\n\n/** The edge changes of the dependency graph and of the runtime graph, or why each is not shown. */\nexport class EdgeDiffReport {\n    constructor(\n        /** The fork point's short sha ('' when there is none). */\n        public readonly base: string,\n        /** '' when `dependency` was computed; otherwise why the page shows no dependency edge changes. */\n        public readonly dependencyReason: string,\n        public readonly dependency: EdgeChange[],\n        /** '' when `runtime` was computed; otherwise why the page shows no runtime edge changes. */\n        public readonly runtimeReason: string,\n        public readonly runtime: EdgeChange[],\n    ) {}\n}\n\n/** The one field of a committed dependencies.json the base side reads. */\ninterface SavedProjectsFile {\n    projects?: EnhancedGraph;\n}\n\n/** The two graphs the branch has NOW, computed live. `runtime` null when it could not be derived. */\nexport class LiveGraphs {\n    constructor(\n        public readonly projects: EnhancedGraph,\n        public readonly runtime: RuntimeGraph | null,\n        /** Why `runtime` is null ('' otherwise). */\n        public readonly runtimeReason: string = '',\n    ) {}\n}\n\n/**\n * Computes the live graphs: `CurrentGraphBuilder` (generate's own pipeline, writing nothing) and the\n * runtime graph derived from it exactly as generate derives it. `architecture:generate` passes the\n * graphs it just built instead (`FixedLiveGraphs`), so nothing is computed twice.\n */\nexport class LiveGraphSource {\n    async graphs(workspaceRoot: string): Promise<LiveGraphs> {\n        const current = await new CurrentGraphBuilder().build(workspaceRoot);\n        const hidden = new Set<string>(Object.keys(current.graph).filter((name: string): boolean => current.graph[name].drawOnGraph === false));\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- the runtime half is optional; the dependency half still shows\n        try {\n            const contracts = new ApiContractFiles().load(workspaceRoot, DEFAULT_GRAPH_PATH, current.apiContractFiles);\n            const report = deriveRuntimeGraphReport(current.graph, hidden, contracts, current.externalSystems, current.remoteServices);\n            return new LiveGraphs(current.graph, report.graph);\n        } catch (err: unknown) {\n            const error = toError(err);\n            return new LiveGraphs(current.graph, null, `the live runtime graph could not be derived (${error.message})`);\n        }\n    }\n}\n\n/** The graphs a caller already holds (architecture:generate just built them). */\nexport class FixedLiveGraphs extends LiveGraphSource {\n    constructor(private readonly live: LiveGraphs) {\n        super();\n    }\n\n    override async graphs(): Promise<LiveGraphs> {\n        return this.live;\n    }\n}\n\n/** A committed file as it was at a commit. Injected so specs never spawn git. */\nexport class GitFileAt {\n    /** The file's text at `sha`; null when it did not exist there (or git cannot answer). */\n    read(workspaceRoot: string, sha: string, file: string): string | null {\n        const shown = spawnSync('git', ['show', `${sha}:${file}`], {\n            cwd: workspaceRoot,\n            encoding: 'utf8',\n            stdio: 'pipe',\n            maxBuffer: 64 * 1024 * 1024,\n        });\n        return shown.status === 0 ? shown.stdout : null;\n    }\n}\n\n/** The base graphs' edges: `from|to` → the APIs on that edge (empty for a dependency). */\nclass EdgeSet {\n    readonly edges = new Map<string, Set<string>>();\n\n    add(from: string, to: string, apis: string[]): void {\n        const key = `${from}\\u0000${to}`;\n        const known = this.edges.get(key) ?? new Set<string>();\n        for (const api of apis) known.add(api);\n        this.edges.set(key, known);\n    }\n}\n\n/** Diffs base against live; pure. */\nexport class EdgeDiffer {\n    dependency(base: EnhancedGraph, live: EnhancedGraph): EdgeChange[] {\n        return this.compare(this.dependencyEdges(base), this.dependencyEdges(live), EdgeRelation.DEPENDS);\n    }\n\n    runtime(base: RuntimeGraph, live: RuntimeGraph): EdgeChange[] {\n        return this.compare(this.runtimeEdges(base), this.runtimeEdges(live), EdgeRelation.CALLS);\n    }\n\n    private dependencyEdges(graph: EnhancedGraph): EdgeSet {\n        const set = new EdgeSet();\n        for (const name of Object.keys(graph)) for (const dep of graph[name].dependsOn ?? []) set.add(name, dep, []);\n        return set;\n    }\n\n    private runtimeEdges(graph: RuntimeGraph): EdgeSet {\n        const set = new EdgeSet();\n        for (const edge of graph.runtimeEdges ?? []) set.add(edge.from, edge.to, edge.via ?? []);\n        return set;\n    }\n\n    /** Per edge: gained when absent at base; lost when absent now; for a call, the APIs that came or went. */\n    private compare(base: EdgeSet, live: EdgeSet, relation: EdgeRelation): EdgeChange[] {\n        const changes: EdgeChange[] = [];\n        const keys = [...new Set<string>([...base.edges.keys(), ...live.edges.keys()])].sort();\n        for (const key of keys) {\n            const ends = key.split('\\u0000');\n            const before = base.edges.get(key);\n            const after = live.edges.get(key);\n            const gained = after === undefined ? [] : [...after].filter((api: string): boolean => before === undefined || !before.has(api));\n            const lost = before === undefined ? [] : [...before].filter((api: string): boolean => after === undefined || !after.has(api));\n            if (before === undefined || gained.length > 0)\n                changes.push(this.change(ends[0], ends[1], EdgeChangeKind.GAINED, relation, gained.sort()));\n            if (after === undefined || lost.length > 0)\n                changes.push(this.change(ends[0], ends[1], EdgeChangeKind.LOST, relation, lost.sort()));\n        }\n        return changes;\n    }\n\n    private change(from: string, to: string, kind: EdgeChangeKind, relation: EdgeRelation, apis: string[]): EdgeChange {\n        const verb = relation === EdgeRelation.DEPENDS ? 'depends on' : 'calls';\n        const via = apis.length === 0 ? '' : ` (${apis.join(', ')})`;\n        const text =\n            kind === EdgeChangeKind.GAINED\n                ? `new on this branch: ${from} now ${verb} ${to}${via}`\n                : `${from} no longer ${verb} ${to}${via}`;\n        return new EdgeChange(from, to, kind, relation, apis, text);\n    }\n}\n\n/** Reads the fork point's committed graphs and diffs them against the live ones. Never throws. */\nexport class EdgeChangeScanner {\n    constructor(\n        private readonly git: GitFileAt = new GitFileAt(),\n        private readonly differ: EdgeDiffer = new EdgeDiffer(),\n    ) {}\n\n    async scan(workspaceRoot: string, forkPoint: string | null, source: LiveGraphSource): Promise<EdgeDiffReport> {\n        if (forkPoint === null)\n            return this.none('Edge changes compare a branch with its fork point; there is no branch comparison here (main or a detached HEAD)');\n        const short = forkPoint.slice(0, 7);\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- edge changes are optional; a failure becomes the reason the page shows\n        try {\n            const baseProjects = this.projectsAt(workspaceRoot, forkPoint);\n            const baseRuntime = this.runtimeAt(workspaceRoot, forkPoint);\n            if (baseProjects === null && baseRuntime === null)\n                return this.none(`No architecture graph at the fork point ${short} (first adoption), so there is nothing to compare edges against`, short);\n            const live = await source.graphs(workspaceRoot);\n            const dependencyReason = baseProjects === null ? `No ${DEFAULT_GRAPH_PATH} at the fork point ${short}` : '';\n            const runtimeReason = baseRuntime === null ? `No ${DEFAULT_RUNTIME_GRAPH_PATH} at the fork point ${short}` : live.runtimeReason;\n            return new EdgeDiffReport(\n                short,\n                dependencyReason,\n                baseProjects === null ? [] : this.differ.dependency(baseProjects, live.projects),\n                runtimeReason,\n                baseRuntime === null || live.runtime === null ? [] : this.differ.runtime(baseRuntime, live.runtime),\n            );\n        } catch (err: unknown) {\n            const error = toError(err);\n            return this.none(`Edge changes unavailable: ${error.message}`, short);\n        }\n    }\n\n    /** No edge changes to show, with the one reason the page says instead. */\n    private none(reason: string, base = ''): EdgeDiffReport {\n        return new EdgeDiffReport(base, reason, [], reason, []);\n    }\n\n    /** dependencies.json's `projects` at the fork point; null when absent or not that shape. */\n    private projectsAt(workspaceRoot: string, sha: string): EnhancedGraph | null {\n        const parsed = this.parse(this.git.read(workspaceRoot, sha, DEFAULT_GRAPH_PATH));\n        const projects = parsed === null ? undefined : (parsed as SavedProjectsFile).projects;\n        return projects !== undefined && typeof projects === 'object' && projects !== null ? projects : null;\n    }\n\n    private runtimeAt(workspaceRoot: string, sha: string): RuntimeGraph | null {\n        const parsed = this.parse(this.git.read(workspaceRoot, sha, DEFAULT_RUNTIME_GRAPH_PATH));\n        return parsed !== null && Array.isArray((parsed as RuntimeGraph).runtimeEdges) ? (parsed as RuntimeGraph) : null;\n    }\n\n    // webpieces-disable no-any-unknown -- committed JSON from another commit is untrusted until narrowed by the caller\n    private parse(text: string | null): unknown {\n        if (text === null) return null;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an unreadable file at the fork point is the same as no file there\n        try {\n            return JSON.parse(text);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error; // not JSON at the fork point: treated as absent\n            return null;\n        }\n    }\n}\n"]}

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

@@ -55,6 +55,7 @@ import type { FileChange } from 'nx/src/project-graph/file-utils';
 import type { PackageJson } from 'nx/src/utils/package-json';
 import { DiffScope } from '@webpieces/rules-config';
 import { AffectedClassification, AffectedClassifier, AffectedReason, WorkspaceNx } from './graph-impact-reasons';
+import { EdgeChangeScanner, EdgeDiffReport, LiveGraphSource } from './graph-edge-diff';
 import type { EnhancedGraph } from './graph-sorter';
 /** Relative to the architecture/ directory the page lives in; the page's `<script src>`. */
 export declare const IMPACT_SIDECAR_DIR = ".impact";
@@ -165,7 +166,19 @@ export declare class ImpactCounts {
 export declare class ImpactSidecarData {
     readonly scans: ImpactReport[];
     readonly defaultKind: ImpactKind;
-    constructor(scans: ImpactReport[], defaultKind: ImpactKind);
+    /**
+     * The edges this branch gained or lost since its FORK POINT, the live graph against the fork
+     * point's committed one (graph-edge-diff.ts, #1264). One per sidecar: it does not depend on
+     * which scan is shown.
+     */
+    readonly edges: EdgeDiffReport;
+    constructor(scans: ImpactReport[], defaultKind: ImpactKind, 
+    /**
+     * The edges this branch gained or lost since its FORK POINT, the live graph against the fork
+     * point's committed one (graph-edge-diff.ts, #1264). One per sidecar: it does not depend on
+     * which scan is shown.
+     */
+    edges: EdgeDiffReport);
 }
 /** A scan (or a whole plan) that could not produce an answer. */
 export declare class ImpactUnavailable {
@@ -303,12 +316,16 @@ export declare class ImpactRefresh {
     private readonly scanner;
     private readonly sidecar;
     private readonly resolver;
-    constructor(scanner?: NxImpactScanner, sidecar?: ImpactSidecar, resolver?: ImpactScopeResolver);
+    private readonly edges;
+    constructor(scanner?: NxImpactScanner, sidecar?: ImpactSidecar, resolver?: ImpactScopeResolver, edges?: EdgeChangeScanner);
     /**
      * Scans the comparisons in `kinds` that exist here (`VISUALIZE_IMPACT_KINDS` /
-     * `GENERATE_IMPACT_KINDS`). Never throws — Impact is optional, generation is not.
+     * `GENERATE_IMPACT_KINDS`), and the edge changes since the fork point against the LIVE graphs
+     * `live` computes. Never throws — Impact is optional, generation is not.
      */
-    run(architectureDir: string, workspaceRoot: string, graph: EnhancedGraph, kinds: readonly ImpactKind[]): Promise<string>;
+    run(architectureDir: string, workspaceRoot: string, graph: EnhancedGraph, kinds: readonly ImpactKind[], live: LiveGraphSource): Promise<string>;
+    /** `✅ Edges since abc1234: dependencies 1 gained · 1 lost; runtime 0 gained · 0 lost`, or why not. */
+    private edgeLine;
     /** The plan's default when that scan is available, else the first available one. */
     private defaultKind;
     private none;