@webpieces/nx-webpieces-rules 0.4.911 → 0.4.913

package/src/lib/runtime-goal-validator.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeGoalValidator = void 0;
+/** One queue flow and the goal path segment that names it. */
+class NamedFlow {
+    where;
+    flow;
+    constructor(where, flow) {
+        this.where = where;
+        this.flow = flow;
+    }
+}
+/**
+ * Shape and internal-reference checks for a HAND-AUTHORED runtime goal (#1239).
+ *
+ * The generated current graph is validated by regenerating it from source; a goal has no source to
+ * regenerate from, so every problem is named against the goal file itself, with the element that is
+ * wrong and the edit that fixes it. Problems are collected, never thrown one at a time, so one run
+ * names every broken reference.
+ *
+ * Two kinds of problem, because they have different cures:
+ *  - STRUCTURAL (shape, dangling references): only an edit of the goal file fixes them.
+ *  - DERIVED (a missing or invalid level, a missing contract queue, maxLevel): the explicit
+ *    `--prepare` step computes them from the relationships, so it must accept a goal that has them.
+ * Facts that are present but merely disagree with the relationships are drift, reported by
+ * RuntimeGoalFile.drift().
+ */
+class RuntimeGoalValidator {
+    goalPath;
+    constructor(goalPath) {
+        this.goalPath = goalPath;
+    }
+    /** Problems only an edit of the goal file can fix; empty when `--prepare` can run. */
+    // webpieces-disable no-any-unknown -- hand-authored JSON is untrusted until its shape has been checked
+    structural(graph) {
+        if (!this.isMap(graph))
+            return [`${this.goalPath} must contain a JSON object (a RuntimeGraph).`];
+        const typed = graph;
+        const shape = this.shape(typed);
+        if (shape.length > 0)
+            return shape;
+        return this.references(typed);
+    }
+    /** Derived facts `--prepare` computes; call only on a structurally valid goal. */
+    derived(graph) {
+        const problems = [];
+        if (!Number.isInteger(graph.maxLevel))
+            problems.push(`${this.goalPath}: "maxLevel" must be an integer.`);
+        if (graph.contractQueues === undefined)
+            problems.push(`${this.goalPath}: "contractQueues" is missing.`);
+        return [...problems, ...this.levels(graph), ...this.contractQueues(graph)];
+    }
+    shape(graph) {
+        const problems = [];
+        for (const key of ['services', 'apis', 'queues']) {
+            if (!this.isMap(graph[key]))
+                problems.push(`${this.goalPath}: "${key}" must be an object keyed by identity.`);
+        }
+        for (const key of ['runtimeEdges', 'unresolvedUses', 'triggers']) {
+            if (!Array.isArray(graph[key]))
+                problems.push(`${this.goalPath}: "${key}" must be an array.`);
+        }
+        for (const key of ['externalSystems', 'remoteServices', 'contractQueues']) {
+            if (graph[key] !== undefined && !this.isMap(graph[key]))
+                problems.push(`${this.goalPath}: "${key}" must be an object when present.`);
+        }
+        return problems;
+    }
+    /** The renderer places every node by its saved level, so each needs one. */
+    levels(graph) {
+        const problems = [];
+        const check = (where, node) => {
+            if (!this.isMap(node) || !Number.isInteger(node.level) || node.level < 0 || typeof node.levelBecause !== 'string')
+                problems.push(`${this.goalPath}: ${where} needs an integer "level" >= 0 and a string "levelBecause".`);
+        };
+        for (const [name, service] of Object.entries(graph.services))
+            check(`services["${name}"]`, service);
+        for (const [key, queue] of Object.entries(graph.queues))
+            check(`queues["${key}"]`, queue);
+        for (const [api, queue] of Object.entries(graph.contractQueues ?? {}))
+            check(`contractQueues["${api}"]`, queue);
+        graph.triggers.forEach((trigger, index) => check(`triggers[${index}]`, trigger));
+        graph.unresolvedUses.forEach((use, index) => check(`unresolvedUses[${index}]`, use));
+        for (const [id, system] of Object.entries(graph.externalSystems ?? {}))
+            check(`externalSystems["${id}"]`, system);
+        for (const [name, remote] of Object.entries(graph.remoteServices ?? {}))
+            check(`remoteServices["${name}"]`, remote);
+        return problems;
+    }
+    references(graph) {
+        return [
+            ...this.services(graph),
+            ...this.edges(graph),
+            ...this.queues(graph),
+            ...this.triggers(graph),
+            ...this.externals(graph),
+            ...this.remotes(graph),
+        ];
+    }
+    services(graph) {
+        const problems = [];
+        for (const [name, service] of Object.entries(graph.services)) {
+            for (const key of ['implements', 'uses', 'dependsOn']) {
+                if (!this.strings(service[key]))
+                    problems.push(`${this.goalPath}: services["${name}"].${key} must be an array of strings (use [] for none).`);
+            }
+            if (service.products !== undefined && !this.strings(service.products))
+                problems.push(`${this.goalPath}: services["${name}"].products must be an array of strings when present.`);
+        }
+        return problems;
+    }
+    edges(graph) {
+        const problems = [];
+        graph.runtimeEdges.forEach((edge, index) => problems.push(...this.edge(graph, edge, index)));
+        return problems;
+    }
+    edge(graph, edge, index) {
+        const where = `${this.goalPath}: runtimeEdges[${index}] (${edge?.from} -> ${edge?.to})`;
+        if (!this.isMap(edge) || !this.strings(edge.via) || edge.via.length === 0)
+            return [`${where} needs "from", "to" and a non-empty "via" contract list.`];
+        const problems = [];
+        for (const end of [edge.from, edge.to]) {
+            if (graph.services[end] === undefined)
+                problems.push(`${where} names '${end}', which is not in "services". Add services["${end}"] or remove the edge.`);
+        }
+        if (edge.type !== undefined && edge.type !== 'rpc' && edge.type !== 'pubsub')
+            problems.push(`${where} has type '${edge.type}'; use "rpc" or "pubsub".`);
+        if (edge.type === 'pubsub' && edge.queue !== undefined && graph.queues[edge.queue] === undefined)
+            problems.push(`${where} flows through queue '${edge.queue}', which is not in "queues". Add queues["${edge.queue}"] or drop "queue" for a contract-level edge.`);
+        return problems;
+    }
+    /** Every contract-level pubsub edge needs its contract queue, which `--prepare` derives. */
+    contractQueues(graph) {
+        const problems = [];
+        graph.runtimeEdges.forEach((edge, index) => {
+            if (edge.type !== 'pubsub' || edge.queue !== undefined)
+                return;
+            for (const api of edge.via) {
+                if (graph.contractQueues?.[api] === undefined)
+                    problems.push(`${this.goalPath}: runtimeEdges[${index}] (${edge.from} -> ${edge.to}) is a contract-level pubsub edge over ${api}, but contractQueues["${api}"] is missing.`);
+            }
+        });
+        return problems;
+    }
+    queues(graph) {
+        const problems = [];
+        const flows = [];
+        for (const key of Object.keys(graph.queues))
+            flows.push(new NamedFlow(`queues["${key}"]`, graph.queues[key]));
+        const contracts = graph.contractQueues ?? {};
+        for (const api of Object.keys(contracts))
+            flows.push(new NamedFlow(`contractQueues["${api}"]`, contracts[api]));
+        for (const named of flows) {
+            const where = named.where;
+            const flow = named.flow;
+            for (const key of ['producedBy', 'consumedBy']) {
+                if (!this.strings(flow[key])) {
+                    problems.push(`${this.goalPath}: ${where}.${key} must be an array of service names.`);
+                    continue;
+                }
+                for (const name of flow[key]) {
+                    if (graph.services[name] === undefined)
+                        problems.push(`${this.goalPath}: ${where}.${key} names '${name}', which is not in "services".`);
+                }
+            }
+        }
+        for (const [key, queue] of Object.entries(graph.queues)) {
+            if (typeof queue.api !== 'string' || typeof queue.method !== 'string' || typeof queue.queueName !== 'string')
+                problems.push(`${this.goalPath}: queues["${key}"] needs string "api", "method" and "queueName".`);
+        }
+        return problems;
+    }
+    triggers(graph) {
+        const problems = [];
+        graph.triggers.forEach((trigger, index) => {
+            const where = `${this.goalPath}: triggers[${index}]`;
+            if (trigger.kind !== 'cron' && trigger.kind !== 'external')
+                problems.push(`${where} has kind '${trigger.kind}'; use "cron" or "external".`);
+            if (typeof trigger.api !== 'string' || typeof trigger.method !== 'string')
+                problems.push(`${where} needs string "api" and "method".`);
+            if (graph.services[trigger.service] === undefined)
+                problems.push(`${where} targets '${trigger.service}', which is not in "services".`);
+        });
+        graph.unresolvedUses.forEach((use, index) => {
+            if (graph.services[use.service] === undefined)
+                problems.push(`${this.goalPath}: unresolvedUses[${index}] names '${use.service}', which is not in "services".`);
+            if (typeof use.api !== 'string')
+                problems.push(`${this.goalPath}: unresolvedUses[${index}] needs a string "api".`);
+        });
+        return problems;
+    }
+    externals(graph) {
+        const problems = [];
+        for (const [id, system] of Object.entries(graph.externalSystems ?? {})) {
+            const where = `${this.goalPath}: externalSystems["${id}"]`;
+            if (typeof system.kind !== 'string' || typeof system.label !== 'string' || !this.strings(system.apis))
+                problems.push(`${where} needs string "kind" and "label" and an "apis" string array.`);
+            if (!this.strings(system.usedBy)) {
+                problems.push(`${where}.usedBy must be an array of service names.`);
+                continue;
+            }
+            for (const name of system.usedBy) {
+                if (graph.services[name] === undefined)
+                    problems.push(`${where}.usedBy names '${name}', which is not in "services".`);
+            }
+        }
+        return problems;
+    }
+    remotes(graph) {
+        const problems = [];
+        for (const [name, remote] of Object.entries(graph.remoteServices ?? {})) {
+            const where = `${this.goalPath}: remoteServices["${name}"]`;
+            if (!this.strings(remote.implements) || !Array.isArray(remote.calledBy)) {
+                problems.push(`${where} needs an "implements" string array and a "calledBy" array.`);
+                continue;
+            }
+            remote.calledBy.forEach((call, index) => {
+                if (!this.isMap(call) || !this.strings(call.via) || (call.type !== 'rpc' && call.type !== 'pubsub'))
+                    problems.push(`${where}.calledBy[${index}] needs "from", a "via" string array and type "rpc" or "pubsub".`);
+                else if (graph.services[call.from] === undefined)
+                    problems.push(`${where}.calledBy[${index}] names '${call.from}', which is not in "services".`);
+            });
+        }
+        return problems;
+    }
+    // webpieces-disable no-any-unknown -- hand-authored JSON is untrusted until its shape has been checked
+    strings(value) {
+        return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+    }
+    // webpieces-disable no-any-unknown -- hand-authored JSON is untrusted until its shape has been checked
+    isMap(value) {
+        return value !== null && typeof value === 'object' && !Array.isArray(value);
+    }
+}
+exports.RuntimeGoalValidator = RuntimeGoalValidator;
+//# sourceMappingURL=runtime-goal-validator.js.map

package/src/lib/runtime-goal-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-goal-validator.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-goal-validator.ts"],"names":[],"mappings":";;;AAUA,8DAA8D;AAC9D,MAAM,SAAS;IAES;IACA;IAFpB,YACoB,KAAa,EACb,IAAsB;QADtB,UAAK,GAAL,KAAK,CAAQ;QACb,SAAI,GAAJ,IAAI,CAAkB;IACvC,CAAC;CACP;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAa,oBAAoB;IACA;IAA7B,YAA6B,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;IAAG,CAAC;IAEjD,sFAAsF;IACtF,uGAAuG;IACvG,UAAU,CAAC,KAAc;QACrB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,+CAA+C,CAAC,CAAC;QACjG,MAAM,KAAK,GAAG,KAAqB,CAAC;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACnC,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,kFAAkF;IAClF,OAAO,CAAC,KAAmB;QACvB,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,kCAAkC,CAAC,CAAC;QACzG,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,gCAAgC,CAAC,CAAC;QACxG,OAAO,CAAC,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/E,CAAC;IAEO,KAAK,CAAC,KAAmB;QAC7B,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAU,EAAE,CAAC;YACxD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,MAAM,GAAG,wCAAwC,CAAC,CAAC;QAClH,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,gBAAgB,EAAE,UAAU,CAAU,EAAE,CAAC;YACxE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,MAAM,GAAG,qBAAqB,CAAC,CAAC;QAClG,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,CAAU,EAAE,CAAC;YACjF,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBACnD,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,MAAM,GAAG,mCAAmC,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED,4EAA4E;IACpE,MAAM,CAAC,KAAmB;QAC9B,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,IAAkB,EAAQ,EAAE;YACtD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,OAAO,IAAI,CAAC,YAAY,KAAK,QAAQ;gBAC7G,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,KAAK,KAAK,6DAA6D,CAAC,CAAC;QAC/G,CAAC,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;YAAE,KAAK,CAAC,aAAa,IAAI,IAAI,EAAE,OAAO,CAAC,CAAC;QACpG,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;YAAE,KAAK,CAAC,WAAW,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC;QAC1F,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,IAAI,EAAE,CAAC;YAAE,KAAK,CAAC,mBAAmB,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC;QAChH,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAuB,EAAE,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,KAAK,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;QACzG,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,GAAsB,EAAE,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,kBAAkB,KAAK,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAChH,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,IAAI,EAAE,CAAC;YAAE,KAAK,CAAC,oBAAoB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAClH,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,IAAI,EAAE,CAAC;YAAE,KAAK,CAAC,mBAAmB,IAAI,IAAI,EAAE,MAAM,CAAC,CAAC;QACpH,OAAO,QAAQ,CAAC;IACpB,CAAC;IAEO,UAAU,CAAC,KAAmB;QAClC,OAAO;YACH,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YACvB,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;YACpB,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;YACrB,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YACvB,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YACxB,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;SACzB,CAAC;IACN,CAAC;IAEO,QAAQ,CAAC,KAAmB;QAChC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3D,KAAK,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,CAAU,EAAE,CAAC;gBAC7D,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;oBAC3B,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,eAAe,IAAI,MAAM,GAAG,iDAAiD,CAAC,CAAC;YACrH,CAAC;YACD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;gBACjE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,eAAe,IAAI,uDAAuD,CAAC,CAAC;QAClH,CAAC;QACD,OAAO,QAAQ,CAAC;IACpB,CAAC;IAEO,KAAK,CAAC,KAAmB;QAC7B,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,IAAiB,EAAE,KAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QAClH,OAAO,QAAQ,CAAC;IACpB,CAAC;IAEO,IAAI,CAAC,KAAmB,EAAE,IAAiB,EAAE,KAAa;QAC9D,MAAM,KAAK,GAAG,GAAG,IAAI,CAAC,QAAQ,kBAAkB,KAAK,MAAM,IAAI,EAAE,IAAI,OAAO,IAAI,EAAE,EAAE,GAAG,CAAC;QACxF,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;YACrE,OAAO,CAAC,GAAG,KAAK,0DAA0D,CAAC,CAAC;QAChF,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACrC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,SAAS;gBACjC,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,WAAW,GAAG,gDAAgD,GAAG,wBAAwB,CAAC,CAAC;QACzH,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YACxE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,cAAc,IAAI,CAAC,IAAI,2BAA2B,CAAC,CAAC;QAC9E,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,SAAS;YAC5F,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,yBAAyB,IAAI,CAAC,KAAK,4CAA4C,IAAI,CAAC,KAAK,+CAA+C,CAAC,CAAC;QACpK,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED,4FAA4F;IACpF,cAAc,CAAC,KAAmB;QACtC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,IAAiB,EAAE,KAAa,EAAE,EAAE;YAC5D,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;gBAAE,OAAO;YAC/D,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBACzB,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC,GAAG,CAAC,KAAK,SAAS;oBACzC,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,kBAAkB,KAAK,MAAM,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,EAAE,0CAA0C,GAAG,yBAAyB,GAAG,gBAAgB,CAAC,CAAC;YACrL,CAAC;QACL,CAAC,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC;IACpB,CAAC;IAEO,MAAM,CAAC,KAAmB;QAC9B,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAgB,EAAE,CAAC;QAC9B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,WAAW,GAAG,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9G,MAAM,SAAS,GAAG,KAAK,CAAC,cAAc,IAAI,EAAE,CAAC;QAC7C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,mBAAmB,GAAG,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChH,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;YAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;YACxB,KAAK,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,YAAY,CAAU,EAAE,CAAC;gBACtD,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;oBAC3B,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,KAAK,KAAK,IAAI,GAAG,qCAAqC,CAAC,CAAC;oBACtF,SAAS;gBACb,CAAC;gBACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC3B,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,SAAS;wBAClC,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,KAAK,KAAK,IAAI,GAAG,WAAW,IAAI,gCAAgC,CAAC,CAAC;gBACxG,CAAC;YACL,CAAC;QACL,CAAC;QACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YACtD,IAAI,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ;gBACxG,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,aAAa,GAAG,kDAAkD,CAAC,CAAC;QAC1G,CAAC;QACD,OAAO,QAAQ,CAAC;IACpB,CAAC;IAEO,QAAQ,CAAC,KAAmB;QAChC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAuB,EAAE,KAAa,EAAE,EAAE;YAC9D,MAAM,KAAK,GAAG,GAAG,IAAI,CAAC,QAAQ,cAAc,KAAK,GAAG,CAAC;YACrD,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU;gBACtD,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,cAAc,OAAO,CAAC,IAAI,8BAA8B,CAAC,CAAC;YACpF,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ;gBACrE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,mCAAmC,CAAC,CAAC;YAC/D,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,SAAS;gBAC7C,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,OAAO,CAAC,OAAO,gCAAgC,CAAC,CAAC;QAC5F,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,GAAsB,EAAE,KAAa,EAAE,EAAE;YACnE,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,SAAS;gBACzC,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,oBAAoB,KAAK,YAAY,GAAG,CAAC,OAAO,gCAAgC,CAAC,CAAC;YACpH,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,oBAAoB,KAAK,yBAAyB,CAAC,CAAC;QACvH,CAAC,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC;IACpB,CAAC;IAEO,SAAS,CAAC,KAAmB;QACjC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,IAAI,EAAE,CAAC,EAAE,CAAC;YACrE,MAAM,KAAK,GAAG,GAAG,IAAI,CAAC,QAAQ,sBAAsB,EAAE,IAAI,CAAC;YAC3D,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;gBACjG,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,8DAA8D,CAAC,CAAC;YAC1F,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC/B,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,4CAA4C,CAAC,CAAC;gBACpE,SAAS;YACb,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAC/B,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,SAAS;oBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,kBAAkB,IAAI,gCAAgC,CAAC,CAAC;YAC1H,CAAC;QACL,CAAC;QACD,OAAO,QAAQ,CAAC;IACpB,CAAC;IAEO,OAAO,CAAC,KAAmB;QAC/B,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,IAAI,EAAE,CAAC,EAAE,CAAC;YACtE,MAAM,KAAK,GAAG,GAAG,IAAI,CAAC,QAAQ,qBAAqB,IAAI,IAAI,CAAC;YAC5D,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACtE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,6DAA6D,CAAC,CAAC;gBACrF,SAAS;YACb,CAAC;YACD,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAuB,EAAE,KAAa,EAAE,EAAE;gBAC/D,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;oBAC/F,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,KAAK,kEAAkE,CAAC,CAAC;qBAC3G,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS;oBAC5C,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,KAAK,YAAY,IAAI,CAAC,IAAI,gCAAgC,CAAC,CAAC;YACvG,CAAC,CAAC,CAAC;QACP,CAAC;QACD,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED,uGAAuG;IAC/F,OAAO,CAAC,KAAc;QAC1B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,KAAgD,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC;IAChI,CAAC;IAED,uGAAuG;IAC/F,KAAK,CAAC,KAAc;QACxB,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAChF,CAAC;CACJ;AA1MD,oDA0MC","sourcesContent":["import type {\n    RuntimeEdge,\n    RuntimeGraph,\n    RuntimeLevel,\n    RuntimeQueueFlow,\n    RuntimeRemoteCall,\n    RuntimeTrigger,\n    RuntimeUnresolved,\n} from './runtime-graph-model';\n\n/** One queue flow and the goal path segment that names it. */\nclass NamedFlow {\n    constructor(\n        public readonly where: string,\n        public readonly flow: RuntimeQueueFlow,\n    ) {}\n}\n\n/**\n * Shape and internal-reference checks for a HAND-AUTHORED runtime goal (#1239).\n *\n * The generated current graph is validated by regenerating it from source; a goal has no source to\n * regenerate from, so every problem is named against the goal file itself, with the element that is\n * wrong and the edit that fixes it. Problems are collected, never thrown one at a time, so one run\n * names every broken reference.\n *\n * Two kinds of problem, because they have different cures:\n *  - STRUCTURAL (shape, dangling references): only an edit of the goal file fixes them.\n *  - DERIVED (a missing or invalid level, a missing contract queue, maxLevel): the explicit\n *    `--prepare` step computes them from the relationships, so it must accept a goal that has them.\n * Facts that are present but merely disagree with the relationships are drift, reported by\n * RuntimeGoalFile.drift().\n */\nexport class RuntimeGoalValidator {\n    constructor(private readonly goalPath: string) {}\n\n    /** Problems only an edit of the goal file can fix; empty when `--prepare` can run. */\n    // webpieces-disable no-any-unknown -- hand-authored JSON is untrusted until its shape has been checked\n    structural(graph: unknown): string[] {\n        if (!this.isMap(graph)) return [`${this.goalPath} must contain a JSON object (a RuntimeGraph).`];\n        const typed = graph as RuntimeGraph;\n        const shape = this.shape(typed);\n        if (shape.length > 0) return shape;\n        return this.references(typed);\n    }\n\n    /** Derived facts `--prepare` computes; call only on a structurally valid goal. */\n    derived(graph: RuntimeGraph): string[] {\n        const problems: string[] = [];\n        if (!Number.isInteger(graph.maxLevel)) problems.push(`${this.goalPath}: \"maxLevel\" must be an integer.`);\n        if (graph.contractQueues === undefined) problems.push(`${this.goalPath}: \"contractQueues\" is missing.`);\n        return [...problems, ...this.levels(graph), ...this.contractQueues(graph)];\n    }\n\n    private shape(graph: RuntimeGraph): string[] {\n        const problems: string[] = [];\n        for (const key of ['services', 'apis', 'queues'] as const) {\n            if (!this.isMap(graph[key])) problems.push(`${this.goalPath}: \"${key}\" must be an object keyed by identity.`);\n        }\n        for (const key of ['runtimeEdges', 'unresolvedUses', 'triggers'] as const) {\n            if (!Array.isArray(graph[key])) problems.push(`${this.goalPath}: \"${key}\" must be an array.`);\n        }\n        for (const key of ['externalSystems', 'remoteServices', 'contractQueues'] as const) {\n            if (graph[key] !== undefined && !this.isMap(graph[key]))\n                problems.push(`${this.goalPath}: \"${key}\" must be an object when present.`);\n        }\n        return problems;\n    }\n\n    /** The renderer places every node by its saved level, so each needs one. */\n    private levels(graph: RuntimeGraph): string[] {\n        const problems: string[] = [];\n        const check = (where: string, node: RuntimeLevel): void => {\n            if (!this.isMap(node) || !Number.isInteger(node.level) || node.level < 0 || typeof node.levelBecause !== 'string')\n                problems.push(`${this.goalPath}: ${where} needs an integer \"level\" >= 0 and a string \"levelBecause\".`);\n        };\n        for (const [name, service] of Object.entries(graph.services)) check(`services[\"${name}\"]`, service);\n        for (const [key, queue] of Object.entries(graph.queues)) check(`queues[\"${key}\"]`, queue);\n        for (const [api, queue] of Object.entries(graph.contractQueues ?? {})) check(`contractQueues[\"${api}\"]`, queue);\n        graph.triggers.forEach((trigger: RuntimeTrigger, index: number) => check(`triggers[${index}]`, trigger));\n        graph.unresolvedUses.forEach((use: RuntimeUnresolved, index: number) => check(`unresolvedUses[${index}]`, use));\n        for (const [id, system] of Object.entries(graph.externalSystems ?? {})) check(`externalSystems[\"${id}\"]`, system);\n        for (const [name, remote] of Object.entries(graph.remoteServices ?? {})) check(`remoteServices[\"${name}\"]`, remote);\n        return problems;\n    }\n\n    private references(graph: RuntimeGraph): string[] {\n        return [\n            ...this.services(graph),\n            ...this.edges(graph),\n            ...this.queues(graph),\n            ...this.triggers(graph),\n            ...this.externals(graph),\n            ...this.remotes(graph),\n        ];\n    }\n\n    private services(graph: RuntimeGraph): string[] {\n        const problems: string[] = [];\n        for (const [name, service] of Object.entries(graph.services)) {\n            for (const key of ['implements', 'uses', 'dependsOn'] as const) {\n                if (!this.strings(service[key]))\n                    problems.push(`${this.goalPath}: services[\"${name}\"].${key} must be an array of strings (use [] for none).`);\n            }\n            if (service.products !== undefined && !this.strings(service.products))\n                problems.push(`${this.goalPath}: services[\"${name}\"].products must be an array of strings when present.`);\n        }\n        return problems;\n    }\n\n    private edges(graph: RuntimeGraph): string[] {\n        const problems: string[] = [];\n        graph.runtimeEdges.forEach((edge: RuntimeEdge, index: number) => problems.push(...this.edge(graph, edge, index)));\n        return problems;\n    }\n\n    private edge(graph: RuntimeGraph, edge: RuntimeEdge, index: number): string[] {\n        const where = `${this.goalPath}: runtimeEdges[${index}] (${edge?.from} -> ${edge?.to})`;\n        if (!this.isMap(edge) || !this.strings(edge.via) || edge.via.length === 0)\n            return [`${where} needs \"from\", \"to\" and a non-empty \"via\" contract list.`];\n        const problems: string[] = [];\n        for (const end of [edge.from, edge.to]) {\n            if (graph.services[end] === undefined)\n                problems.push(`${where} names '${end}', which is not in \"services\". Add services[\"${end}\"] or remove the edge.`);\n        }\n        if (edge.type !== undefined && edge.type !== 'rpc' && edge.type !== 'pubsub')\n            problems.push(`${where} has type '${edge.type}'; use \"rpc\" or \"pubsub\".`);\n        if (edge.type === 'pubsub' && edge.queue !== undefined && graph.queues[edge.queue] === undefined)\n            problems.push(`${where} flows through queue '${edge.queue}', which is not in \"queues\". Add queues[\"${edge.queue}\"] or drop \"queue\" for a contract-level edge.`);\n        return problems;\n    }\n\n    /** Every contract-level pubsub edge needs its contract queue, which `--prepare` derives. */\n    private contractQueues(graph: RuntimeGraph): string[] {\n        const problems: string[] = [];\n        graph.runtimeEdges.forEach((edge: RuntimeEdge, index: number) => {\n            if (edge.type !== 'pubsub' || edge.queue !== undefined) return;\n            for (const api of edge.via) {\n                if (graph.contractQueues?.[api] === undefined)\n                    problems.push(`${this.goalPath}: runtimeEdges[${index}] (${edge.from} -> ${edge.to}) is a contract-level pubsub edge over ${api}, but contractQueues[\"${api}\"] is missing.`);\n            }\n        });\n        return problems;\n    }\n\n    private queues(graph: RuntimeGraph): string[] {\n        const problems: string[] = [];\n        const flows: NamedFlow[] = [];\n        for (const key of Object.keys(graph.queues)) flows.push(new NamedFlow(`queues[\"${key}\"]`, graph.queues[key]));\n        const contracts = graph.contractQueues ?? {};\n        for (const api of Object.keys(contracts)) flows.push(new NamedFlow(`contractQueues[\"${api}\"]`, contracts[api]));\n        for (const named of flows) {\n            const where = named.where;\n            const flow = named.flow;\n            for (const key of ['producedBy', 'consumedBy'] as const) {\n                if (!this.strings(flow[key])) {\n                    problems.push(`${this.goalPath}: ${where}.${key} must be an array of service names.`);\n                    continue;\n                }\n                for (const name of flow[key]) {\n                    if (graph.services[name] === undefined)\n                        problems.push(`${this.goalPath}: ${where}.${key} names '${name}', which is not in \"services\".`);\n                }\n            }\n        }\n        for (const [key, queue] of Object.entries(graph.queues)) {\n            if (typeof queue.api !== 'string' || typeof queue.method !== 'string' || typeof queue.queueName !== 'string')\n                problems.push(`${this.goalPath}: queues[\"${key}\"] needs string \"api\", \"method\" and \"queueName\".`);\n        }\n        return problems;\n    }\n\n    private triggers(graph: RuntimeGraph): string[] {\n        const problems: string[] = [];\n        graph.triggers.forEach((trigger: RuntimeTrigger, index: number) => {\n            const where = `${this.goalPath}: triggers[${index}]`;\n            if (trigger.kind !== 'cron' && trigger.kind !== 'external')\n                problems.push(`${where} has kind '${trigger.kind}'; use \"cron\" or \"external\".`);\n            if (typeof trigger.api !== 'string' || typeof trigger.method !== 'string')\n                problems.push(`${where} needs string \"api\" and \"method\".`);\n            if (graph.services[trigger.service] === undefined)\n                problems.push(`${where} targets '${trigger.service}', which is not in \"services\".`);\n        });\n        graph.unresolvedUses.forEach((use: RuntimeUnresolved, index: number) => {\n            if (graph.services[use.service] === undefined)\n                problems.push(`${this.goalPath}: unresolvedUses[${index}] names '${use.service}', which is not in \"services\".`);\n            if (typeof use.api !== 'string') problems.push(`${this.goalPath}: unresolvedUses[${index}] needs a string \"api\".`);\n        });\n        return problems;\n    }\n\n    private externals(graph: RuntimeGraph): string[] {\n        const problems: string[] = [];\n        for (const [id, system] of Object.entries(graph.externalSystems ?? {})) {\n            const where = `${this.goalPath}: externalSystems[\"${id}\"]`;\n            if (typeof system.kind !== 'string' || typeof system.label !== 'string' || !this.strings(system.apis))\n                problems.push(`${where} needs string \"kind\" and \"label\" and an \"apis\" string array.`);\n            if (!this.strings(system.usedBy)) {\n                problems.push(`${where}.usedBy must be an array of service names.`);\n                continue;\n            }\n            for (const name of system.usedBy) {\n                if (graph.services[name] === undefined) problems.push(`${where}.usedBy names '${name}', which is not in \"services\".`);\n            }\n        }\n        return problems;\n    }\n\n    private remotes(graph: RuntimeGraph): string[] {\n        const problems: string[] = [];\n        for (const [name, remote] of Object.entries(graph.remoteServices ?? {})) {\n            const where = `${this.goalPath}: remoteServices[\"${name}\"]`;\n            if (!this.strings(remote.implements) || !Array.isArray(remote.calledBy)) {\n                problems.push(`${where} needs an \"implements\" string array and a \"calledBy\" array.`);\n                continue;\n            }\n            remote.calledBy.forEach((call: RuntimeRemoteCall, index: number) => {\n                if (!this.isMap(call) || !this.strings(call.via) || (call.type !== 'rpc' && call.type !== 'pubsub'))\n                    problems.push(`${where}.calledBy[${index}] needs \"from\", a \"via\" string array and type \"rpc\" or \"pubsub\".`);\n                else if (graph.services[call.from] === undefined)\n                    problems.push(`${where}.calledBy[${index}] names '${call.from}', which is not in \"services\".`);\n            });\n        }\n        return problems;\n    }\n\n    // webpieces-disable no-any-unknown -- hand-authored JSON is untrusted until its shape has been checked\n    private strings(value: unknown): value is string[] {\n        return Array.isArray(value) && value.every((entry: string | number | boolean | object | null) => typeof entry === 'string');\n    }\n\n    // webpieces-disable no-any-unknown -- hand-authored JSON is untrusted until its shape has been checked\n    private isMap(value: unknown): boolean {\n        return value !== null && typeof value === 'object' && !Array.isArray(value);\n    }\n}\n"]}

package/src/lib/runtime-goal-view.d.ts

@@ -0,0 +1,22 @@
+import type { RuntimeGraph } from './runtime-graph-model';
+import { SavedSnapshot } from './saved-snapshot';
+import { RuntimeGoalFile } from './runtime-goal-file';
+import { RuntimeComparisonView } from './graph-render-model';
+import type { RuntimeVizOptions } from './runtime-viz-options';
+/**
+ * Loads either saved runtime file for the OTHER page's comparison, turning a missing or unusable file
+ * into the reason Goal vs Current is unavailable — never into "no differences".
+ */
+export declare class RuntimeComparisonInputs {
+    private readonly snapshot;
+    private readonly goalFile;
+    constructor(snapshot?: SavedSnapshot, goalFile?: RuntimeGoalFile);
+    /** The saved current graph, or why it cannot be compared. */
+    current(workspaceRoot: string): RuntimeGraph | string;
+    /** The saved goal, or why it cannot be compared (missing: how to start one). */
+    goal(workspaceRoot: string): RuntimeGraph | string;
+    view(current: RuntimeGraph | string, goal: RuntimeGraph | string, options: RuntimeVizOptions): RuntimeComparisonView;
+    /** Goal vs Current with no overlay: the mode is disabled and says `reason` instead. */
+    unavailable(reason: string): RuntimeComparisonView;
+    private text;
+}

package/src/lib/runtime-goal-view.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeComparisonInputs = void 0;
+const rules_config_1 = require("@webpieces/rules-config");
+const runtime_graph_io_1 = require("./runtime-graph-io");
+const saved_snapshot_1 = require("./saved-snapshot");
+const runtime_goal_file_1 = require("./runtime-goal-file");
+const graph_render_model_1 = require("./graph-render-model");
+const runtime_goal_comparison_1 = require("./runtime-goal-comparison");
+const toError_1 = require("../toError");
+/**
+ * Loads either saved runtime file for the OTHER page's comparison, turning a missing or unusable file
+ * into the reason Goal vs Current is unavailable — never into "no differences".
+ */
+class RuntimeComparisonInputs {
+    snapshot;
+    goalFile;
+    constructor(snapshot = new saved_snapshot_1.SavedSnapshot(), goalFile = new runtime_goal_file_1.RuntimeGoalFile()) {
+        this.snapshot = snapshot;
+        this.goalFile = goalFile;
+    }
+    /** The saved current graph, or why it cannot be compared. */
+    current(workspaceRoot) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an unusable comparison input becomes the mode's stated reason; the page itself still renders
+        try {
+            return this.snapshot.loadRuntime(workspaceRoot);
+        }
+        catch (err) {
+            const error = (0, toError_1.toError)(err);
+            return `No usable saved current runtime graph at ${runtime_graph_io_1.DEFAULT_RUNTIME_GRAPH_PATH}: ${this.text(error)}`;
+        }
+    }
+    /** The saved goal, or why it cannot be compared (missing: how to start one). */
+    goal(workspaceRoot) {
+        if (!this.goalFile.exists(workspaceRoot))
+            return `No runtime goal at ${runtime_goal_file_1.DEFAULT_RUNTIME_GOAL_PATH}. Start a proposal with: ${runtime_goal_file_1.RUNTIME_GOAL_INIT_COMMAND}`;
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an unusable comparison input becomes the mode's stated reason; the page itself still renders
+        try {
+            return this.goalFile.load(workspaceRoot);
+        }
+        catch (err) {
+            const error = (0, toError_1.toError)(err);
+            return this.text(error);
+        }
+    }
+    view(current, goal, options) {
+        if (typeof current === 'string')
+            return this.unavailable(current);
+        if (typeof goal === 'string')
+            return this.unavailable(goal);
+        return new runtime_goal_comparison_1.RuntimeGoalComparison().build(current, goal, options);
+    }
+    /** Goal vs Current with no overlay: the mode is disabled and says `reason` instead. */
+    unavailable(reason) {
+        return new graph_render_model_1.RuntimeComparisonView(false, reason, 'Current → Goal', '', null, {}, {}, []);
+    }
+    text(error) {
+        if (error instanceof rules_config_1.RuleFailError)
+            return (0, rules_config_1.renderRuleFailForHuman)(error);
+        throw error;
+    }
+}
+exports.RuntimeComparisonInputs = RuntimeComparisonInputs;
+//# sourceMappingURL=runtime-goal-view.js.map

package/src/lib/runtime-goal-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-goal-view.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-goal-view.ts"],"names":[],"mappings":";;;AAAA,0DAAgF;AAEhF,yDAAgE;AAChE,qDAAiD;AACjD,2DAA4G;AAC5G,6DAA6D;AAC7D,uEAAkE;AAElE,wCAAqC;AAErC;;;GAGG;AACH,MAAa,uBAAuB;IAEX;IACA;IAFrB,YACqB,WAA0B,IAAI,8BAAa,EAAE,EAC7C,WAA4B,IAAI,mCAAe,EAAE;QADjD,aAAQ,GAAR,QAAQ,CAAqC;QAC7C,aAAQ,GAAR,QAAQ,CAAyC;IACnE,CAAC;IAEJ,6DAA6D;IAC7D,OAAO,CAAC,aAAqB;QACzB,8JAA8J;QAC9J,IAAI,CAAC;YACD,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,OAAO,4CAA4C,6CAA0B,KAAK,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACzG,CAAC;IACL,CAAC;IAED,gFAAgF;IAChF,IAAI,CAAC,aAAqB;QACtB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC;YACpC,OAAO,sBAAsB,6CAAyB,4BAA4B,6CAAyB,EAAE,CAAC;QAClH,8JAA8J;QAC9J,IAAI,CAAC;YACD,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;IACL,CAAC;IAED,IAAI,CAAC,OAA8B,EAAE,IAA2B,EAAE,OAA0B;QACxF,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAClE,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC5D,OAAO,IAAI,+CAAqB,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACrE,CAAC;IAED,uFAAuF;IACvF,WAAW,CAAC,MAAc;QACtB,OAAO,IAAI,0CAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC5F,CAAC;IAEO,IAAI,CAAC,KAAY;QACrB,IAAI,KAAK,YAAY,4BAAa;YAAE,OAAO,IAAA,qCAAsB,EAAC,KAAK,CAAC,CAAC;QACzE,MAAM,KAAK,CAAC;IAChB,CAAC;CACJ;AA7CD,0DA6CC","sourcesContent":["import { RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport type { RuntimeGraph } from './runtime-graph-model';\nimport { DEFAULT_RUNTIME_GRAPH_PATH } from './runtime-graph-io';\nimport { SavedSnapshot } from './saved-snapshot';\nimport { DEFAULT_RUNTIME_GOAL_PATH, RUNTIME_GOAL_INIT_COMMAND, RuntimeGoalFile } from './runtime-goal-file';\nimport { RuntimeComparisonView } from './graph-render-model';\nimport { RuntimeGoalComparison } from './runtime-goal-comparison';\nimport type { RuntimeVizOptions } from './runtime-viz-options';\nimport { toError } from '../toError';\n\n/**\n * Loads either saved runtime file for the OTHER page's comparison, turning a missing or unusable file\n * into the reason Goal vs Current is unavailable — never into \"no differences\".\n */\nexport class RuntimeComparisonInputs {\n    constructor(\n        private readonly snapshot: SavedSnapshot = new SavedSnapshot(),\n        private readonly goalFile: RuntimeGoalFile = new RuntimeGoalFile(),\n    ) {}\n\n    /** The saved current graph, or why it cannot be compared. */\n    current(workspaceRoot: string): RuntimeGraph | string {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an unusable comparison input becomes the mode's stated reason; the page itself still renders\n        try {\n            return this.snapshot.loadRuntime(workspaceRoot);\n        } catch (err: unknown) {\n            const error = toError(err);\n            return `No usable saved current runtime graph at ${DEFAULT_RUNTIME_GRAPH_PATH}: ${this.text(error)}`;\n        }\n    }\n\n    /** The saved goal, or why it cannot be compared (missing: how to start one). */\n    goal(workspaceRoot: string): RuntimeGraph | string {\n        if (!this.goalFile.exists(workspaceRoot))\n            return `No runtime goal at ${DEFAULT_RUNTIME_GOAL_PATH}. Start a proposal with: ${RUNTIME_GOAL_INIT_COMMAND}`;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an unusable comparison input becomes the mode's stated reason; the page itself still renders\n        try {\n            return this.goalFile.load(workspaceRoot);\n        } catch (err: unknown) {\n            const error = toError(err);\n            return this.text(error);\n        }\n    }\n\n    view(current: RuntimeGraph | string, goal: RuntimeGraph | string, options: RuntimeVizOptions): RuntimeComparisonView {\n        if (typeof current === 'string') return this.unavailable(current);\n        if (typeof goal === 'string') return this.unavailable(goal);\n        return new RuntimeGoalComparison().build(current, goal, options);\n    }\n\n    /** Goal vs Current with no overlay: the mode is disabled and says `reason` instead. */\n    unavailable(reason: string): RuntimeComparisonView {\n        return new RuntimeComparisonView(false, reason, 'Current → Goal', '', null, {}, {}, []);\n    }\n\n    private text(error: Error): string {\n        if (error instanceof RuleFailError) return renderRuleFailForHuman(error);\n        throw error;\n    }\n}\n"]}

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

@@ -0,0 +1,107 @@
+/**
+ * Goal vs Current (#1239): a SEMANTIC diff of two saved RuntimeGraph files.
+ *
+ * Both graphs are flattened into FACTS keyed by stable underlying identities — a service's project
+ * key, a queue's `Api.method`, a contract queue's API, an external system's identity — never by a
+ * shortened display name or a renderer-generated edge id. A fact is a NODE (service, queue, contract
+ * queue, external system, remote service, external library, trigger), a RELATIONSHIP (rpc call,
+ * enqueue, delivery, external use, remote call, unresolved use) or a CONTRACT (an `apis` entry).
+ *
+ * Comparison policy:
+ *  - Values are canonical strings. Set-like arrays are de-duplicated and sorted, so object key order
+ *    and array order alone never produce a change.
+ *  - Queue facts are compared per method / per contract BEFORE presentation grouping, and every
+ *    pubsub edge is split into its enqueue and delivery relationships, so a merged queue box cannot
+ *    hide a difference between its members.
+ *  - Bookkeeping is ignored: `levelBecause` (explanatory text the level machinery regenerates),
+ *    `wiringUses` / `wiringImplements` (reviewed provenance), and `dependsOn` (the BUILD graph, which
+ *    this runtime comparison deliberately does not cover). `maxLevel` is reported in the summary.
+ *  - A service's outgoing relationships are one of its properties, so a service whose calls changed
+ *    is itself CHANGED and its details show the before/after call list.
+ */
+import type { RuntimeEdge, RuntimeGraph } from './runtime-graph-model';
+export declare enum RuntimeDiffStatus {
+    ADDED = "added",
+    REMOVED = "removed",
+    CHANGED = "changed",
+    UNCHANGED = "unchanged"
+}
+export declare enum RuntimeFactKind {
+    NODE = "node",
+    RELATIONSHIP = "relationship",
+    CONTRACT = "contract"
+}
+/** One identity's canonical properties in one graph. */
+export declare class RuntimeFact {
+    readonly id: string;
+    readonly kind: RuntimeFactKind;
+    readonly category: string;
+    readonly label: string;
+    readonly properties: Record<string, string>;
+    constructor(id: string, kind: RuntimeFactKind, category: string, label: string, properties: Record<string, string>);
+}
+/** One identity compared across Current → Goal. `before` is null when added, `after` when removed. */
+export declare class RuntimeFactChange {
+    readonly id: string;
+    readonly kind: RuntimeFactKind;
+    readonly category: string;
+    readonly label: string;
+    readonly status: RuntimeDiffStatus;
+    readonly before: Record<string, string> | null;
+    readonly after: Record<string, string> | null;
+    readonly changedFields: string[];
+    constructor(id: string, kind: RuntimeFactKind, category: string, label: string, status: RuntimeDiffStatus, before: Record<string, string> | null, after: Record<string, string> | null, changedFields: string[]);
+    /** Human lines for a details panel: the status, then `field: before → after` per changed field. */
+    lines(): string[];
+    private listing;
+}
+export declare class RuntimeDiffCounts {
+    readonly added: number;
+    readonly removed: number;
+    readonly changed: number;
+    readonly unchanged: number;
+    constructor(added: number, removed: number, changed: number, unchanged: number);
+}
+/** Every compared identity, sorted by id, plus graph-level bookkeeping. */
+export declare class RuntimeGraphDiffResult {
+    readonly changes: RuntimeFactChange[];
+    readonly maxLevelBefore: number;
+    readonly maxLevelAfter: number;
+    private readonly byId;
+    constructor(changes: RuntimeFactChange[], maxLevelBefore: number, maxLevelAfter: number);
+    get(id: string): RuntimeFactChange | undefined;
+    counts(): RuntimeDiffCounts;
+    identical(): boolean;
+    /** The changed identities only (added, removed, changed), in id order. */
+    differences(): RuntimeFactChange[];
+}
+/** Flattens one RuntimeGraph into its facts. */
+export declare class RuntimeFactSet {
+    private readonly graph;
+    readonly facts: Map<string, RuntimeFact>;
+    constructor(graph: RuntimeGraph);
+    private add;
+    private relationships;
+    /** `queue:Api.method` for a method-level hop; one `contract-queue:Api` per contract otherwise. */
+    queueIds(edge: RuntimeEdge): string[];
+    private services;
+    private queues;
+    private externals;
+    private remotes;
+    private triggers;
+    private contracts;
+    private owner;
+    private node;
+    private relation;
+    /** Set semantics: de-duplicated and sorted, so order alone is never a change. */
+    private set;
+    private split;
+    private value;
+    /** JSON with sorted keys, for the two map-or-string fields. */
+    private canonical;
+}
+/** Compares two saved runtime graphs, Current → Goal. Pure; deterministic for equivalent inputs. */
+export declare class RuntimeGraphDiff {
+    compare(current: RuntimeGraph, goal: RuntimeGraph): RuntimeGraphDiffResult;
+    private change;
+}