@webpieces/nx-webpieces-rules 0.3.136 → 0.3.138

package/src/lib/runtime-cycles.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Runtime Cycles
+ *
+ * Enumerates ALL cycles in the runtime service graph using Tarjan's
+ * strongly-connected-components algorithm. The existing graph-sorter `findCycle`
+ * reports only one cycle; runtime validation needs every cycle so each can be
+ * checked against the per-cycle allowlist independently.
+ *
+ * A cycle is any SCC with more than one node, or a single node with a self-edge.
+ * Each cycle is keyed by its sorted, comma-joined node names so it can be
+ * matched against an `allowedCycles` entry regardless of traversal order.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cycleKey = cycleKey;
+exports.findRuntimeCycles = findRuntimeCycles;
+/** Canonical key for a set of service names (order-independent). */
+function cycleKey(services) {
+    return [...services].sort().join(',');
+}
+/**
+ * Find every cycle in a directed graph via Tarjan's SCC algorithm.
+ * `graph[node]` lists the nodes `node` points to.
+ */
+function findRuntimeCycles(graph) {
+    const indexOf = new Map();
+    const lowLink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    let counter = 0;
+    const nodes = Object.keys(graph);
+    const strongConnect = (node) => {
+        indexOf.set(node, counter);
+        lowLink.set(node, counter);
+        counter += 1;
+        stack.push(node);
+        onStack.add(node);
+        for (const next of graph[node] ?? []) {
+            if (!indexOf.has(next)) {
+                strongConnect(next);
+                lowLink.set(node, Math.min(lowLink.get(node), lowLink.get(next)));
+            }
+            else if (onStack.has(next)) {
+                lowLink.set(node, Math.min(lowLink.get(node), indexOf.get(next)));
+            }
+        }
+        if (lowLink.get(node) === indexOf.get(node)) {
+            const component = [];
+            let member = '';
+            do {
+                member = stack.pop();
+                onStack.delete(member);
+                component.push(member);
+            } while (member !== node);
+            sccs.push(component);
+        }
+    };
+    for (const node of nodes) {
+        if (!indexOf.has(node))
+            strongConnect(node);
+    }
+    const cycles = [];
+    for (const component of sccs) {
+        const isMultiNode = component.length > 1;
+        const isSelfLoop = component.length === 1 && (graph[component[0]] ?? []).includes(component[0]);
+        if (isMultiNode || isSelfLoop) {
+            const services = [...component].sort();
+            cycles.push({ services, key: cycleKey(services) });
+        }
+    }
+    return cycles;
+}
+//# sourceMappingURL=runtime-cycles.js.map

package/src/lib/runtime-cycles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-cycles.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-cycles.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime Cycles\n *\n * Enumerates ALL cycles in the runtime service graph using Tarjan's\n * strongly-connected-components algorithm. The existing graph-sorter `findCycle`\n * reports only one cycle; runtime validation needs every cycle so each can be\n * checked against the per-cycle allowlist independently.\n *\n * A cycle is any SCC with more than one node, or a single node with a self-edge.\n * Each cycle is keyed by its sorted, comma-joined node names so it can be\n * matched against an `allowedCycles` entry regardless of traversal order.\n */\n\nexport interface RuntimeCycle {\n    /** Sorted service names participating in the cycle. */\n    services: string[];\n    /** Canonical key: services sorted then joined with \",\". */\n    key: string;\n}\n\n/** Canonical key for a set of service names (order-independent). */\nexport function cycleKey(services: string[]): string {\n    return [...services].sort().join(',');\n}\n\n/**\n * Find every cycle in a directed graph via Tarjan's SCC algorithm.\n * `graph[node]` lists the nodes `node` points to.\n */\nexport function findRuntimeCycles(graph: Record<string, string[]>): RuntimeCycle[] {\n    const indexOf = new Map<string, number>();\n    const lowLink = new Map<string, number>();\n    const onStack = new Set<string>();\n    const stack: string[] = [];\n    const sccs: string[][] = [];\n    let counter = 0;\n\n    const nodes = Object.keys(graph);\n\n    const strongConnect = (node: string): void => {\n        indexOf.set(node, counter);\n        lowLink.set(node, counter);\n        counter += 1;\n        stack.push(node);\n        onStack.add(node);\n\n        for (const next of graph[node] ?? []) {\n            if (!indexOf.has(next)) {\n                strongConnect(next);\n                lowLink.set(node, Math.min(lowLink.get(node)!, lowLink.get(next)!));\n            } else if (onStack.has(next)) {\n                lowLink.set(node, Math.min(lowLink.get(node)!, indexOf.get(next)!));\n            }\n        }\n\n        if (lowLink.get(node) === indexOf.get(node)) {\n            const component: string[] = [];\n            let member = '';\n            do {\n                member = stack.pop()!;\n                onStack.delete(member);\n                component.push(member);\n            } while (member !== node);\n            sccs.push(component);\n        }\n    };\n\n    for (const node of nodes) {\n        if (!indexOf.has(node)) strongConnect(node);\n    }\n\n    const cycles: RuntimeCycle[] = [];\n    for (const component of sccs) {\n        const isMultiNode = component.length > 1;\n        const isSelfLoop = component.length === 1 && (graph[component[0]] ?? []).includes(component[0]);\n        if (isMultiNode || isSelfLoop) {\n            const services = [...component].sort();\n            cycles.push({ services, key: cycleKey(services) });\n        }\n    }\n    return cycles;\n}\n"]}

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

@@ -0,0 +1,47 @@
+/**
+ * Runtime Graph
+ *
+ * Assembles the runtime microservice graph from the per-service
+ * `service-contract.json` files, and saves/loads the committed
+ * `architecture/runtime-dependencies.json`.
+ *
+ * The runtime edge Z -> X (Z depends on X at runtime) is INFERRED: Z `uses` api
+ * Y and X `implements` api Y. This edge does not exist in the compile-time
+ * dependencies.json (both Z and X only compile-depend on the api library Y).
+ */
+import type { WorkspaceModel } from './runtime-markers';
+export declare const DEFAULT_RUNTIME_GRAPH_PATH = "architecture/runtime-dependencies.json";
+export interface RuntimeService {
+    level: number;
+    implements: string[];
+    uses: string[];
+    dependsOn: string[];
+}
+export interface RuntimeApi {
+    implementedBy: string[];
+    usedBy: string[];
+}
+export interface RuntimeEdge {
+    from: string;
+    to: string;
+    via: string[];
+}
+export interface RuntimeUnresolved {
+    service: string;
+    api: string;
+}
+export interface RuntimeGraph {
+    services: Record<string, RuntimeService>;
+    apis: Record<string, RuntimeApi>;
+    runtimeEdges: RuntimeEdge[];
+    unresolvedUses: RuntimeUnresolved[];
+}
+/** Adjacency (service -> [targets]) from a loaded runtime graph. */
+export declare function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]>;
+/** Assemble the full runtime graph from the workspace model + service contracts. */
+export declare function assembleRuntimeGraph(model: WorkspaceModel, workspaceRoot: string): RuntimeGraph;
+export declare function saveRuntimeGraph(graph: RuntimeGraph, workspaceRoot: string, graphPath?: string): void;
+export declare function runtimeGraphFileExists(workspaceRoot: string, graphPath?: string): boolean;
+export declare function loadRuntimeGraph(workspaceRoot: string, graphPath?: string): RuntimeGraph | null;
+/** Serialize for an in-memory equality check (matches the on-disk format). */
+export declare function serializeRuntimeGraph(graph: RuntimeGraph): string;

package/src/lib/runtime-graph.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Runtime Graph
+ *
+ * Assembles the runtime microservice graph from the per-service
+ * `service-contract.json` files, and saves/loads the committed
+ * `architecture/runtime-dependencies.json`.
+ *
+ * The runtime edge Z -> X (Z depends on X at runtime) is INFERRED: Z `uses` api
+ * Y and X `implements` api Y. This edge does not exist in the compile-time
+ * dependencies.json (both Z and X only compile-depend on the api library Y).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RUNTIME_GRAPH_PATH = void 0;
+exports.runtimeAdjacency = runtimeAdjacency;
+exports.assembleRuntimeGraph = assembleRuntimeGraph;
+exports.saveRuntimeGraph = saveRuntimeGraph;
+exports.runtimeGraphFileExists = runtimeGraphFileExists;
+exports.loadRuntimeGraph = loadRuntimeGraph;
+exports.serializeRuntimeGraph = serializeRuntimeGraph;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const graph_sorter_1 = require("./graph-sorter");
+const runtime_markers_1 = require("./runtime-markers");
+const toError_1 = require("../toError");
+exports.DEFAULT_RUNTIME_GRAPH_PATH = 'architecture/runtime-dependencies.json';
+/** Collect every service project (servicePaths), with its declarations resolved to projects. */
+function collectServiceDecls(model, workspaceRoot) {
+    const decls = [];
+    for (const info of model.projects.values()) {
+        if (!info.isService)
+            continue;
+        // A service missing its contract still appears as a node (empty edges);
+        // validate-runtime-markers fails it separately for the missing file.
+        const contract = (0, runtime_markers_1.readServiceContract)(workspaceRoot, info.root);
+        const implementsPkgs = contract ? contract.implements : [];
+        const usesPkgs = contract ? contract.uses : [];
+        decls.push({
+            name: info.name,
+            implements: (0, runtime_markers_1.resolvePackageNames)(model, implementsPkgs).projects.sort(),
+            uses: (0, runtime_markers_1.resolvePackageNames)(model, usesPkgs).projects.sort(),
+        });
+    }
+    return decls.sort((a, b) => a.name.localeCompare(b.name));
+}
+function buildApiIndex(decls) {
+    const apis = new Map();
+    const ensure = (api) => {
+        let entry = apis.get(api);
+        if (!entry) {
+            entry = { implementedBy: [], usedBy: [] };
+            apis.set(api, entry);
+        }
+        return entry;
+    };
+    for (const decl of decls) {
+        for (const api of decl.implements)
+            ensure(api).implementedBy.push(decl.name);
+        for (const api of decl.uses)
+            ensure(api).usedBy.push(decl.name);
+    }
+    for (const entry of apis.values()) {
+        entry.implementedBy.sort();
+        entry.usedBy.sort();
+    }
+    return apis;
+}
+/** Build inferred runtime edges (Z -> X via Y) and the unresolved-uses list. */
+function buildEdges(decls, apis) {
+    const viaByEdge = new Map();
+    const unresolved = [];
+    for (const decl of decls) {
+        for (const api of decl.uses) {
+            const implementers = apis.get(api)?.implementedBy ?? [];
+            if (implementers.length === 0) {
+                unresolved.push({ service: decl.name, api });
+                continue;
+            }
+            for (const target of implementers) {
+                if (target === decl.name)
+                    continue;
+                const key = `${decl.name} ${target}`;
+                if (!viaByEdge.has(key))
+                    viaByEdge.set(key, new Set());
+                viaByEdge.get(key).add(api);
+            }
+        }
+    }
+    const edges = [];
+    for (const key of viaByEdge.keys()) {
+        const parts = key.split(' ');
+        edges.push({ from: parts[0], to: parts[1], via: Array.from(viaByEdge.get(key)).sort() });
+    }
+    edges.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+    unresolved.sort((a, b) => a.service.localeCompare(b.service) || a.api.localeCompare(b.api));
+    return { edges, unresolved };
+}
+/** Adjacency (service -> [targets]) used for leveling + cycle checks. */
+function adjacencyFromEdges(serviceNames, edges) {
+    const adj = {};
+    for (const name of serviceNames)
+        adj[name] = [];
+    for (const edge of edges) {
+        if (!adj[edge.from])
+            adj[edge.from] = [];
+        adj[edge.from].push(edge.to);
+    }
+    return adj;
+}
+/** Adjacency (service -> [targets]) from a loaded runtime graph. */
+function runtimeAdjacency(graph) {
+    return adjacencyFromEdges(Object.keys(graph.services), graph.runtimeEdges);
+}
+/** Assign levels via topological sort; falls back to level 0 when a cycle exists. */
+function assignLevels(adjacency) {
+    const levels = {};
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const sorted = (0, graph_sorter_1.sortGraphTopologically)(adjacency);
+        for (const name of Object.keys(sorted))
+            levels[name] = sorted[name].level;
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        void error;
+        for (const name of Object.keys(adjacency))
+            levels[name] = 0;
+    }
+    return levels;
+}
+/** Assemble the full runtime graph from the workspace model + service contracts. */
+function assembleRuntimeGraph(model, workspaceRoot) {
+    const decls = collectServiceDecls(model, workspaceRoot);
+    const apis = buildApiIndex(decls);
+    const edgeResult = buildEdges(decls, apis);
+    const services = {};
+    for (const decl of decls) {
+        const dependsOn = Array.from(new Set(edgeResult.edges.filter((e) => e.from === decl.name).map((e) => e.to))).sort();
+        services[decl.name] = { level: 0, implements: decl.implements, uses: decl.uses, dependsOn };
+    }
+    const levels = assignLevels(adjacencyFromEdges(Object.keys(services), edgeResult.edges));
+    for (const name of Object.keys(services))
+        services[name].level = levels[name] ?? 0;
+    const apisObj = {};
+    for (const api of Array.from(apis.keys()).sort())
+        apisObj[api] = apis.get(api);
+    return {
+        services,
+        apis: apisObj,
+        runtimeEdges: edgeResult.edges,
+        unresolvedUses: edgeResult.unresolved,
+    };
+}
+/** Deterministic JSON (sorted keys + arrays already sorted during assembly). */
+function formatRuntimeJson(graph) {
+    return JSON.stringify(graph, null, 4) + '\n';
+}
+function saveRuntimeGraph(graph, workspaceRoot, graphPath = exports.DEFAULT_RUNTIME_GRAPH_PATH) {
+    const fullPath = path.join(workspaceRoot, graphPath);
+    const dir = path.dirname(fullPath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(fullPath, formatRuntimeJson(graph), 'utf-8');
+}
+function runtimeGraphFileExists(workspaceRoot, graphPath = exports.DEFAULT_RUNTIME_GRAPH_PATH) {
+    return fs.existsSync(path.join(workspaceRoot, graphPath));
+}
+function loadRuntimeGraph(workspaceRoot, graphPath = exports.DEFAULT_RUNTIME_GRAPH_PATH) {
+    const fullPath = path.join(workspaceRoot, graphPath);
+    if (!fs.existsSync(fullPath))
+        return null;
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        return JSON.parse(fs.readFileSync(fullPath, 'utf-8'));
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        throw new Error(`Failed to load runtime graph from ${fullPath}: ${error.message}`);
+    }
+}
+/** Serialize for an in-memory equality check (matches the on-disk format). */
+function serializeRuntimeGraph(graph) {
+    return formatRuntimeJson(graph);
+}
+//# sourceMappingURL=runtime-graph.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-graph.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime Graph\n *\n * Assembles the runtime microservice graph from the per-service\n * `service-contract.json` files, and saves/loads the committed\n * `architecture/runtime-dependencies.json`.\n *\n * The runtime edge Z -> X (Z depends on X at runtime) is INFERRED: Z `uses` api\n * Y and X `implements` api Y. This edge does not exist in the compile-time\n * dependencies.json (both Z and X only compile-depend on the api library Y).\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { sortGraphTopologically } from './graph-sorter';\nimport { readServiceContract, resolvePackageNames } from './runtime-markers';\nimport type { WorkspaceModel } from './runtime-markers';\nimport { toError } from '../toError';\n\nexport const DEFAULT_RUNTIME_GRAPH_PATH = 'architecture/runtime-dependencies.json';\n\nexport interface RuntimeService {\n    level: number;\n    implements: string[];\n    uses: string[];\n    dependsOn: string[];\n}\n\nexport interface RuntimeApi {\n    implementedBy: string[];\n    usedBy: string[];\n}\n\nexport interface RuntimeEdge {\n    from: string;\n    to: string;\n    via: string[];\n}\n\nexport interface RuntimeUnresolved {\n    service: string;\n    api: string;\n}\n\nexport interface RuntimeGraph {\n    services: Record<string, RuntimeService>;\n    apis: Record<string, RuntimeApi>;\n    runtimeEdges: RuntimeEdge[];\n    unresolvedUses: RuntimeUnresolved[];\n}\n\n/** One service's declared relationships, resolved to workspace project names. */\ninterface ServiceDecl {\n    name: string;\n    implements: string[];\n    uses: string[];\n}\n\ninterface EdgeResult {\n    edges: RuntimeEdge[];\n    unresolved: RuntimeUnresolved[];\n}\n\n/** Collect every service project (servicePaths), with its declarations resolved to projects. */\nfunction collectServiceDecls(model: WorkspaceModel, workspaceRoot: string): ServiceDecl[] {\n    const decls: ServiceDecl[] = [];\n    for (const info of model.projects.values()) {\n        if (!info.isService) continue;\n        // A service missing its contract still appears as a node (empty edges);\n        // validate-runtime-markers fails it separately for the missing file.\n        const contract = readServiceContract(workspaceRoot, info.root);\n        const implementsPkgs = contract ? contract.implements : [];\n        const usesPkgs = contract ? contract.uses : [];\n        decls.push({\n            name: info.name,\n            implements: resolvePackageNames(model, implementsPkgs).projects.sort(),\n            uses: resolvePackageNames(model, usesPkgs).projects.sort(),\n        });\n    }\n    return decls.sort((a: ServiceDecl, b: ServiceDecl) => a.name.localeCompare(b.name));\n}\n\nfunction buildApiIndex(decls: ServiceDecl[]): Map<string, RuntimeApi> {\n    const apis = new Map<string, RuntimeApi>();\n    const ensure = (api: string): RuntimeApi => {\n        let entry = apis.get(api);\n        if (!entry) {\n            entry = { implementedBy: [], usedBy: [] };\n            apis.set(api, entry);\n        }\n        return entry;\n    };\n    for (const decl of decls) {\n        for (const api of decl.implements) ensure(api).implementedBy.push(decl.name);\n        for (const api of decl.uses) ensure(api).usedBy.push(decl.name);\n    }\n    for (const entry of apis.values()) {\n        entry.implementedBy.sort();\n        entry.usedBy.sort();\n    }\n    return apis;\n}\n\n/** Build inferred runtime edges (Z -> X via Y) and the unresolved-uses list. */\nfunction buildEdges(decls: ServiceDecl[], apis: Map<string, RuntimeApi>): EdgeResult {\n    const viaByEdge = new Map<string, Set<string>>();\n    const unresolved: RuntimeUnresolved[] = [];\n\n    for (const decl of decls) {\n        for (const api of decl.uses) {\n            const implementers = apis.get(api)?.implementedBy ?? [];\n            if (implementers.length === 0) {\n                unresolved.push({ service: decl.name, api });\n                continue;\n            }\n            for (const target of implementers) {\n                if (target === decl.name) continue;\n                const key = `${decl.name} ${target}`;\n                if (!viaByEdge.has(key)) viaByEdge.set(key, new Set());\n                viaByEdge.get(key)!.add(api);\n            }\n        }\n    }\n\n    const edges: RuntimeEdge[] = [];\n    for (const key of viaByEdge.keys()) {\n        const parts = key.split(' ');\n        edges.push({ from: parts[0], to: parts[1], via: Array.from(viaByEdge.get(key)!).sort() });\n    }\n    edges.sort((a: RuntimeEdge, b: RuntimeEdge) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));\n    unresolved.sort(\n        (a: RuntimeUnresolved, b: RuntimeUnresolved) =>\n            a.service.localeCompare(b.service) || a.api.localeCompare(b.api),\n    );\n    return { edges, unresolved };\n}\n\n/** Adjacency (service -> [targets]) used for leveling + cycle checks. */\nfunction adjacencyFromEdges(serviceNames: string[], edges: RuntimeEdge[]): Record<string, string[]> {\n    const adj: Record<string, string[]> = {};\n    for (const name of serviceNames) adj[name] = [];\n    for (const edge of edges) {\n        if (!adj[edge.from]) adj[edge.from] = [];\n        adj[edge.from].push(edge.to);\n    }\n    return adj;\n}\n\n/** Adjacency (service -> [targets]) from a loaded runtime graph. */\nexport function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]> {\n    return adjacencyFromEdges(Object.keys(graph.services), graph.runtimeEdges);\n}\n\n/** Assign levels via topological sort; falls back to level 0 when a cycle exists. */\nfunction assignLevels(adjacency: Record<string, string[]>): Record<string, number> {\n    const levels: Record<string, number> = {};\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const sorted = sortGraphTopologically(adjacency);\n        for (const name of Object.keys(sorted)) levels[name] = sorted[name].level;\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        for (const name of Object.keys(adjacency)) levels[name] = 0;\n    }\n    return levels;\n}\n\n/** Assemble the full runtime graph from the workspace model + service contracts. */\nexport function assembleRuntimeGraph(model: WorkspaceModel, workspaceRoot: string): RuntimeGraph {\n    const decls = collectServiceDecls(model, workspaceRoot);\n    const apis = buildApiIndex(decls);\n    const edgeResult = buildEdges(decls, apis);\n\n    const services: Record<string, RuntimeService> = {};\n    for (const decl of decls) {\n        const dependsOn = Array.from(\n            new Set(edgeResult.edges.filter((e: RuntimeEdge) => e.from === decl.name).map((e: RuntimeEdge) => e.to)),\n        ).sort();\n        services[decl.name] = { level: 0, implements: decl.implements, uses: decl.uses, dependsOn };\n    }\n\n    const levels = assignLevels(adjacencyFromEdges(Object.keys(services), edgeResult.edges));\n    for (const name of Object.keys(services)) services[name].level = levels[name] ?? 0;\n\n    const apisObj: Record<string, RuntimeApi> = {};\n    for (const api of Array.from(apis.keys()).sort()) apisObj[api] = apis.get(api)!;\n\n    return {\n        services,\n        apis: apisObj,\n        runtimeEdges: edgeResult.edges,\n        unresolvedUses: edgeResult.unresolved,\n    };\n}\n\n/** Deterministic JSON (sorted keys + arrays already sorted during assembly). */\nfunction formatRuntimeJson(graph: RuntimeGraph): string {\n    return JSON.stringify(graph, null, 4) + '\\n';\n}\n\nexport function saveRuntimeGraph(\n    graph: RuntimeGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): void {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    const dir = path.dirname(fullPath);\n    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });\n    fs.writeFileSync(fullPath, formatRuntimeJson(graph), 'utf-8');\n}\n\nexport function runtimeGraphFileExists(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): boolean {\n    return fs.existsSync(path.join(workspaceRoot, graphPath));\n}\n\nexport function loadRuntimeGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): RuntimeGraph | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    if (!fs.existsSync(fullPath)) return null;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return JSON.parse(fs.readFileSync(fullPath, 'utf-8')) as RuntimeGraph;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`Failed to load runtime graph from ${fullPath}: ${error.message}`);\n    }\n}\n\n/** Serialize for an in-memory equality check (matches the on-disk format). */\nexport function serializeRuntimeGraph(graph: RuntimeGraph): string {\n    return formatRuntimeJson(graph);\n}\n"]}

package/src/lib/runtime-markers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Runtime Markers
+ *
+ * Reads the per-service `service-contract.json` files and builds a workspace
+ * model used to assemble the runtime microservice graph and to validate each
+ * service independently.
+ *
+ * `service-contract.json` (at a service's project root) declares, at api-PROJECT
+ * granularity (by package name), which api projects a service IMPLEMENTS (serves)
+ * and which it USES (calls as a client):
+ *
+ *   { "implements": ["@scope/checkout-api"], "uses": ["@scope/payments-api"] }
+ *
+ * Classification (from webpieces.config.json globs):
+ *   - api project: root matches `apiProjectPaths` (e.g. "libraries/apis/*").
+ *   - service:     root matches `servicePaths` (e.g. "services/*") AND is not an
+ *                  api project (api classification wins, so the lists may overlap
+ *                  harmlessly). Every service must have a service-contract.json.
+ */
+export declare const SERVICE_CONTRACT_FILENAME = "service-contract.json";
+/** Parsed `service-contract.json` contents (api package names). */
+export interface ServiceContract {
+    implements: string[];
+    uses: string[];
+}
+/** Everything we know about one workspace project for runtime analysis. */
+export interface ProjectInfo {
+    name: string;
+    root: string;
+    packageName: string | null;
+    isApi: boolean;
+    isService: boolean;
+    /** Workspace project names this project depends on (from the Nx graph). */
+    deps: string[];
+}
+/** The whole-workspace model used by the generator and validators. */
+export interface WorkspaceModel {
+    projects: Map<string, ProjectInfo>;
+    byPackageName: Map<string, string>;
+}
+/** Result of mapping package names to workspace projects. */
+export interface ResolvedNames {
+    projects: string[];
+    unknown: string[];
+}
+/**
+ * Build the workspace model from the Nx project graph. Dependency edges come
+ * from Nx (imports + package.json), the same source dependencies.json uses, so
+ * this works whether or not a service has its own package.json.
+ */
+export declare function buildWorkspaceModel(workspaceRoot: string, apiProjectPaths: string[], servicePaths: string[]): Promise<WorkspaceModel>;
+/** Read and normalize a project's `service-contract.json`, or null if it has none. */
+export declare function readServiceContract(workspaceRoot: string, projectRoot: string): ServiceContract | null;
+/**
+ * Map a list of api package names (from a service contract) to workspace project
+ * names. Unknown names (not a workspace package) are returned in `unknown`.
+ */
+export declare function resolvePackageNames(model: WorkspaceModel, packageNames: string[]): ResolvedNames;

package/src/lib/runtime-markers.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Runtime Markers
+ *
+ * Reads the per-service `service-contract.json` files and builds a workspace
+ * model used to assemble the runtime microservice graph and to validate each
+ * service independently.
+ *
+ * `service-contract.json` (at a service's project root) declares, at api-PROJECT
+ * granularity (by package name), which api projects a service IMPLEMENTS (serves)
+ * and which it USES (calls as a client):
+ *
+ *   { "implements": ["@scope/checkout-api"], "uses": ["@scope/payments-api"] }
+ *
+ * Classification (from webpieces.config.json globs):
+ *   - api project: root matches `apiProjectPaths` (e.g. "libraries/apis/*").
+ *   - service:     root matches `servicePaths` (e.g. "services/*") AND is not an
+ *                  api project (api classification wins, so the lists may overlap
+ *                  harmlessly). Every service must have a service-contract.json.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVICE_CONTRACT_FILENAME = void 0;
+exports.buildWorkspaceModel = buildWorkspaceModel;
+exports.readServiceContract = readServiceContract;
+exports.resolvePackageNames = resolvePackageNames;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const devkit_1 = require("@nx/devkit");
+const rules_config_1 = require("@webpieces/rules-config");
+const toError_1 = require("../toError");
+exports.SERVICE_CONTRACT_FILENAME = 'service-contract.json';
+/** True when a project root matches one of the given globs (segment/glob/dir-prefix). */
+function matchesGlobs(root, globs) {
+    if (globs.length === 0)
+        return false;
+    return (0, rules_config_1.isPathExcluded)(root, globs);
+}
+function readPackageName(workspaceRoot, projectRoot) {
+    const pkgPath = path.join(workspaceRoot, projectRoot, 'package.json');
+    if (!fs.existsSync(pkgPath))
+        return null;
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const raw = fs.readFileSync(pkgPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.name === 'string' ? parsed.name : null;
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        void error;
+        return null;
+    }
+}
+function collectDeps(name, dependencies, workspaceNames) {
+    const deps = [];
+    for (const edge of dependencies[name] ?? []) {
+        if (edge.target !== name && workspaceNames.has(edge.target)) {
+            deps.push(edge.target);
+        }
+    }
+    return Array.from(new Set(deps)).sort();
+}
+/**
+ * Build the workspace model from the Nx project graph. Dependency edges come
+ * from Nx (imports + package.json), the same source dependencies.json uses, so
+ * this works whether or not a service has its own package.json.
+ */
+async function buildWorkspaceModel(workspaceRoot, apiProjectPaths, servicePaths) {
+    const projectGraph = await (0, devkit_1.createProjectGraphAsync)();
+    const projectsConfig = (0, devkit_1.readProjectsConfigurationFromProjectGraph)(projectGraph);
+    const projects = new Map();
+    const byPackageName = new Map();
+    const workspaceNames = new Set(Object.keys(projectGraph.nodes));
+    for (const [name, cfg] of Object.entries(projectsConfig.projects)) {
+        const root = cfg.root;
+        if (root === '' || root === '.')
+            continue;
+        const packageName = readPackageName(workspaceRoot, root);
+        const isApi = matchesGlobs(root, apiProjectPaths);
+        projects.set(name, {
+            name,
+            root,
+            packageName,
+            isApi,
+            // api classification wins, so servicePaths and apiProjectPaths may overlap.
+            isService: !isApi && matchesGlobs(root, servicePaths),
+            deps: collectDeps(name, projectGraph.dependencies, workspaceNames),
+        });
+        if (packageName)
+            byPackageName.set(packageName, name);
+    }
+    return { projects, byPackageName };
+}
+/** Read and normalize a project's `service-contract.json`, or null if it has none. */
+function readServiceContract(workspaceRoot, projectRoot) {
+    const fullPath = path.join(workspaceRoot, projectRoot, exports.SERVICE_CONTRACT_FILENAME);
+    if (!fs.existsSync(fullPath))
+        return null;
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const raw = fs.readFileSync(fullPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return {
+            implements: Array.isArray(parsed.implements) ? parsed.implements : [],
+            uses: Array.isArray(parsed.uses) ? parsed.uses : [],
+        };
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        throw new Error(`Failed to parse ${projectRoot}/${exports.SERVICE_CONTRACT_FILENAME}: ${error.message}`);
+    }
+}
+/**
+ * Map a list of api package names (from a service contract) to workspace project
+ * names. Unknown names (not a workspace package) are returned in `unknown`.
+ */
+function resolvePackageNames(model, packageNames) {
+    const resolved = [];
+    const unknown = [];
+    for (const pkg of packageNames) {
+        const project = model.byPackageName.get(pkg);
+        if (project)
+            resolved.push(project);
+        else
+            unknown.push(pkg);
+    }
+    return { projects: resolved, unknown };
+}
+//# sourceMappingURL=runtime-markers.js.map

package/src/lib/runtime-markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-markers.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-markers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime Markers\n *\n * Reads the per-service `service-contract.json` files and builds a workspace\n * model used to assemble the runtime microservice graph and to validate each\n * service independently.\n *\n * `service-contract.json` (at a service's project root) declares, at api-PROJECT\n * granularity (by package name), which api projects a service IMPLEMENTS (serves)\n * and which it USES (calls as a client):\n *\n *   { \"implements\": [\"@scope/checkout-api\"], \"uses\": [\"@scope/payments-api\"] }\n *\n * Classification (from webpieces.config.json globs):\n *   - api project: root matches `apiProjectPaths` (e.g. \"libraries/apis/*\").\n *   - service:     root matches `servicePaths` (e.g. \"services/*\") AND is not an\n *                  api project (api classification wins, so the lists may overlap\n *                  harmlessly). Every service must have a service-contract.json.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { createProjectGraphAsync, readProjectsConfigurationFromProjectGraph } from '@nx/devkit';\nimport { isPathExcluded } from '@webpieces/rules-config';\nimport { toError } from '../toError';\n\nexport const SERVICE_CONTRACT_FILENAME = 'service-contract.json';\n\n/** Parsed `service-contract.json` contents (api package names). */\nexport interface ServiceContract {\n    implements: string[];\n    uses: string[];\n}\n\n/** Everything we know about one workspace project for runtime analysis. */\nexport interface ProjectInfo {\n    name: string;\n    root: string;\n    packageName: string | null;\n    isApi: boolean;\n    isService: boolean;\n    /** Workspace project names this project depends on (from the Nx graph). */\n    deps: string[];\n}\n\n/** The whole-workspace model used by the generator and validators. */\nexport interface WorkspaceModel {\n    projects: Map<string, ProjectInfo>;\n    byPackageName: Map<string, string>;\n}\n\n/** Result of mapping package names to workspace projects. */\nexport interface ResolvedNames {\n    projects: string[];\n    unknown: string[];\n}\n\n/** Minimal shapes for the JSON files we parse. */\ninterface PackageJsonShape {\n    name?: string;\n}\ninterface ServiceContractShape {\n    implements?: string[];\n    uses?: string[];\n}\n/** One Nx project-graph dependency edge (the slice we use). */\ninterface GraphEdge {\n    target: string;\n}\n\n/** True when a project root matches one of the given globs (segment/glob/dir-prefix). */\nfunction matchesGlobs(root: string, globs: string[]): boolean {\n    if (globs.length === 0) return false;\n    return isPathExcluded(root, globs);\n}\n\nfunction readPackageName(workspaceRoot: string, projectRoot: string): string | null {\n    const pkgPath = path.join(workspaceRoot, projectRoot, 'package.json');\n    if (!fs.existsSync(pkgPath)) return null;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const raw = fs.readFileSync(pkgPath, 'utf-8');\n        const parsed = JSON.parse(raw) as PackageJsonShape;\n        return typeof parsed.name === 'string' ? parsed.name : null;\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        return null;\n    }\n}\n\nfunction collectDeps(\n    name: string,\n    dependencies: Record<string, GraphEdge[]>,\n    workspaceNames: Set<string>,\n): string[] {\n    const deps: string[] = [];\n    for (const edge of dependencies[name] ?? []) {\n        if (edge.target !== name && workspaceNames.has(edge.target)) {\n            deps.push(edge.target);\n        }\n    }\n    return Array.from(new Set(deps)).sort();\n}\n\n/**\n * Build the workspace model from the Nx project graph. Dependency edges come\n * from Nx (imports + package.json), the same source dependencies.json uses, so\n * this works whether or not a service has its own package.json.\n */\nexport async function buildWorkspaceModel(\n    workspaceRoot: string,\n    apiProjectPaths: string[],\n    servicePaths: string[],\n): Promise<WorkspaceModel> {\n    const projectGraph = await createProjectGraphAsync();\n    const projectsConfig = readProjectsConfigurationFromProjectGraph(projectGraph);\n\n    const projects = new Map<string, ProjectInfo>();\n    const byPackageName = new Map<string, string>();\n    const workspaceNames = new Set(Object.keys(projectGraph.nodes));\n\n    for (const [name, cfg] of Object.entries(projectsConfig.projects)) {\n        const root = cfg.root;\n        if (root === '' || root === '.') continue;\n\n        const packageName = readPackageName(workspaceRoot, root);\n        const isApi = matchesGlobs(root, apiProjectPaths);\n        projects.set(name, {\n            name,\n            root,\n            packageName,\n            isApi,\n            // api classification wins, so servicePaths and apiProjectPaths may overlap.\n            isService: !isApi && matchesGlobs(root, servicePaths),\n            deps: collectDeps(name, projectGraph.dependencies, workspaceNames),\n        });\n        if (packageName) byPackageName.set(packageName, name);\n    }\n\n    return { projects, byPackageName };\n}\n\n/** Read and normalize a project's `service-contract.json`, or null if it has none. */\nexport function readServiceContract(workspaceRoot: string, projectRoot: string): ServiceContract | null {\n    const fullPath = path.join(workspaceRoot, projectRoot, SERVICE_CONTRACT_FILENAME);\n    if (!fs.existsSync(fullPath)) return null;\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const raw = fs.readFileSync(fullPath, 'utf-8');\n        const parsed = JSON.parse(raw) as ServiceContractShape;\n        return {\n            implements: Array.isArray(parsed.implements) ? parsed.implements : [],\n            uses: Array.isArray(parsed.uses) ? parsed.uses : [],\n        };\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`Failed to parse ${projectRoot}/${SERVICE_CONTRACT_FILENAME}: ${error.message}`);\n    }\n}\n\n/**\n * Map a list of api package names (from a service contract) to workspace project\n * names. Unknown names (not a workspace package) are returned in `unknown`.\n */\nexport function resolvePackageNames(\n    model: WorkspaceModel,\n    packageNames: string[],\n): ResolvedNames {\n    const resolved: string[] = [];\n    const unknown: string[] = [];\n    for (const pkg of packageNames) {\n        const project = model.byPackageName.get(pkg);\n        if (project) resolved.push(project);\n        else unknown.push(pkg);\n    }\n    return { projects: resolved, unknown };\n}\n"]}

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

@@ -0,0 +1,16 @@
+/**
+ * Runtime Visualizer
+ *
+ * Renders the runtime microservice graph (services + inferred Z -> X edges,
+ * each labeled with the api(s) they flow over) to DOT + interactive HTML in
+ * tmp/webpieces/runtime-architecture.{dot,html}.
+ */
+import type { RuntimeGraph } from './runtime-graph';
+/** Build the Graphviz DOT for the runtime service graph. */
+export declare function generateRuntimeDot(graph: RuntimeGraph, title?: string): string;
+export interface RuntimeVisualizationPaths {
+    dotPath: string;
+    htmlPath: string;
+}
+/** Write the DOT + HTML renderings to tmp/webpieces/. */
+export declare function writeRuntimeVisualization(graph: RuntimeGraph, workspaceRoot: string, title?: string): RuntimeVisualizationPaths;