@webpieces/nx-webpieces-rules 0.4.919 → 0.4.921

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-reasons.d.ts

@@ -0,0 +1,160 @@
+/**
+ * WHY nx put each project into the affected set (#1264): the Impact view never claims a reason the
+ * graph cannot show.
+ *
+ * `nx show projects --affected` answers WHICH projects build; it does not say why. Painting every
+ * affected project that owns no changed file as "dependent: uses a changed project" was false for the
+ * projects nx marked through an IMPLICIT touch — a `{workspaceRoot}/...` target input matching a
+ * changed file — or through a ROOT FILE (a lockfile, package.json, tsconfig.base.json, nx.json). Those
+ * projects use no changed project, so the graph around them shows nothing changed and the view looked
+ * broken.
+ *
+ * So every affected project is classified by nx's OWN locators — the exact functions `filterAffected`
+ * runs (nx/src/project-graph/affected/affected-project-graph.js) — never a re-derivation of them:
+ *
+ * | class | nx locator | what the view says |
+ * |---|---|---|
+ * | changed | `getTouchedProjects` (workspace-projects) | the changed files it owns |
+ * | root-file touched | `nx.json` via `getImplicitlyTouchedProjects`; lockfile, package.json and tsconfig.base.json via the js plugin's locators; a deleted project config via `getTouchedProjectsFromProjectGlobChanges` | the root file, and which locator |
+ * | implicitly touched | `getImplicitlyTouchedProjects` (a `{workspaceRoot}` input glob) | the target, the glob, and the changed file it matched |
+ * | dependent | none: reached from one of the above over nx's REVERSED dependency edges, exactly as `filterAffectedProjects` walks them | the edge path to the nearest one (`a -> b -> c`) |
+ * | unexplained | — | nx marked it and nothing here explains it; said out loud, never guessed |
+ *
+ * A project with several reasons gets the first class in that table's order (changed, root-file,
+ * implicit, dependent). The locators are loaded from the WORKSPACE's own nx (the one that produced the
+ * affected set), resolved the way node resolves it from the workspace root. When they cannot be
+ * loaded, every affected project is "unexplained" with the load error as its reason — never a
+ * dependent.
+ */
+import type { NxJsonConfiguration, ProjectGraph } from '@nx/devkit';
+import type { FileChange } from 'nx/src/project-graph/file-utils';
+import type { PackageJson } from 'nx/src/utils/package-json';
+import type { TouchedProjectLocator } from 'nx/src/project-graph/affected/affected-project-graph-models';
+/** The class a project's colour and click explanation come from. Values are the page's status keys. */
+export declare enum AffectedClass {
+    CHANGED = "touched",
+    DEPENDENT = "dependent",
+    IMPLICIT = "implicit",
+    ROOT_FILE = "rootFile",
+    UNEXPLAINED = "unexplained"
+}
+/** Why one affected project is in the build. Exactly one per affected project. */
+export declare class AffectedReason {
+    /** The node id (project name). */
+    readonly project: string;
+    readonly kind: AffectedClass;
+    /** CHANGED: every changed file it owns. IMPLICIT / ROOT_FILE: the changed file that matched. */
+    readonly files: string[];
+    /** DEPENDENT: `[project, …, the nearest changed or touched project]`, following dependency edges. */
+    readonly path: string[];
+    /** IMPLICIT: the target whose inputs matched. */
+    readonly target: string;
+    /** IMPLICIT: the input glob as written, e.g. `{workspaceRoot}/libs/shared/wiring.ts`. */
+    readonly input: string;
+    /** One sentence for the click panel. */
+    readonly detail: string;
+    constructor(
+    /** The node id (project name). */
+    project: string, kind: AffectedClass, 
+    /** CHANGED: every changed file it owns. IMPLICIT / ROOT_FILE: the changed file that matched. */
+    files: string[], 
+    /** DEPENDENT: `[project, …, the nearest changed or touched project]`, following dependency edges. */
+    path: string[], 
+    /** IMPLICIT: the target whose inputs matched. */
+    target: string, 
+    /** IMPLICIT: the input glob as written, e.g. `{workspaceRoot}/libs/shared/wiring.ts`. */
+    input: string, 
+    /** One sentence for the click panel. */
+    detail: string);
+}
+/** The six locators `filterAffected` runs, as functions. Injected so specs pass nx's own imports. */
+export declare class NxAffectedLocators {
+    readonly touched: TouchedProjectLocator;
+    readonly implicit: TouchedProjectLocator;
+    readonly projectGlobs: TouchedProjectLocator;
+    readonly lockFile: TouchedProjectLocator;
+    readonly npmPackages: TouchedProjectLocator;
+    readonly tsConfig: TouchedProjectLocator;
+    constructor(touched: TouchedProjectLocator, implicit: TouchedProjectLocator, projectGlobs: TouchedProjectLocator, lockFile: TouchedProjectLocator, npmPackages: TouchedProjectLocator, tsConfig: TouchedProjectLocator);
+}
+/** Everything the classification reads; built from the workspace's nx, or by hand in a spec. */
+export declare class AffectedInputs {
+    readonly graph: ProjectGraph;
+    readonly nxJson: NxJsonConfiguration;
+    readonly packageJson: PackageJson;
+    readonly changes: FileChange[];
+    /** nx's affected set (project names), from `nx show projects --affected`. */
+    readonly affected: string[];
+    constructor(graph: ProjectGraph, nxJson: NxJsonConfiguration, packageJson: PackageJson, changes: FileChange[], 
+    /** nx's affected set (project names), from `nx show projects --affected`. */
+    affected: string[]);
+}
+/** The classification of one scan. */
+export declare class AffectedClassification {
+    /** One per affected project, sorted by project. */
+    readonly reasons: AffectedReason[];
+    /** Changed files no project owns (sorted): the workspace-global inputs. */
+    readonly globalFiles: string[];
+    constructor(
+    /** One per affected project, sorted by project. */
+    reasons: AffectedReason[], 
+    /** Changed files no project owns (sorted): the workspace-global inputs. */
+    globalFiles: string[]);
+    of(kind: AffectedClass): string[];
+}
+/** Classifies an affected set with nx's own locators. Pure given its inputs; spawns nothing itself. */
+export declare class AffectedClassifier {
+    private readonly locators;
+    constructor(locators: NxAffectedLocators);
+    classify(inputs: AffectedInputs): Promise<AffectedClassification>;
+    private isOwned;
+    /** project → the changed files it owns, by nx's own file → project locator. */
+    private owned;
+    /**
+     * nx.json, the lockfile, package.json, tsconfig.base.json and a deleted project config. A locator
+     * that answers even with NO change (nx.json's own `projectsAffectedByDependencyUpdates` list) is
+     * named as that configuration, never as a file.
+     */
+    private rootFiles;
+    private rootFileLocators;
+    private run;
+    /** `{workspaceRoot}` input globs: which target, which glob, which changed file. */
+    private implicit;
+    /**
+     * Which target, input and file: each candidate input is handed to nx's OWN implicit locator, alone,
+     * on a copy of the project carrying only that target, so the matcher is always nx's. Named inputs
+     * are opened (nx.json's merged with the project's, as the locator merges them).
+     */
+    private explainImplicit;
+    /** Every input, with named inputs opened (cycle-safe). */
+    private leaves;
+    private fileset;
+    private probe;
+    /**
+     * Dependents: a breadth-first walk over the REVERSED dependency edges from every changed and
+     * touched project (and every npm package a root file touched), the walk nx's own
+     * `filterAffectedProjects` does — so the first seed reached is the NEAREST one. A project one edge
+     * from a touched npm package is root-file touched itself ("uses npm:x: package.json changed").
+     */
+    private dependents;
+    /** For each project reachable from `starts` over reversed edges, the next hop toward the nearest start. */
+    private nearest;
+    private dependent;
+    unexplained(project: string, why?: string): AffectedReason;
+    /** First reason wins (changed, root-file, implicit, dependent); only affected projects count. */
+    private seed;
+    private reason;
+}
+/** The workspace's own nx, loaded the way node resolves it from the workspace root. */
+export declare class WorkspaceNx {
+    private readonly workspaceRoot;
+    constructor(workspaceRoot: string);
+    locators(): NxAffectedLocators;
+    /** nx's own FileChange list: base → working tree (no head), as `nx affected` builds it. */
+    fileChanges(files: string[], base: string): FileChange[];
+    nxJson(): NxJsonConfiguration;
+    packageJson(): PackageJson;
+    /** A file at `revision`, or in the working tree with none; '' when it does not exist there. */
+    private readAt;
+    private load;
+}