@webpieces/nx-webpieces-rules 0.3.136 → 0.3.138

package/executors.json

@@ -10,6 +10,21 @@
             "schema": "./src/executors/visualize/schema.json",
             "description": "Generate visual representations of the architecture graph"
         },
+        "visualize-runtime": {
+            "implementation": "./src/executors/visualize-runtime/executor",
+            "schema": "./src/executors/visualize-runtime/schema.json",
+            "description": "Render the runtime microservice graph (runtime-dependencies.json)"
+        },
+        "validate-runtime-markers": {
+            "implementation": "./src/executors/validate-runtime-markers/executor",
+            "schema": "./src/executors/validate-runtime-markers/schema.json",
+            "description": "Per-project: validate live.json matches the project's api-project dependencies"
+        },
+        "validate-runtime-architecture": {
+            "implementation": "./src/executors/validate-runtime-architecture/executor",
+            "schema": "./src/executors/validate-runtime-architecture/schema.json",
+            "description": "Validate the runtime microservice graph: no disallowed cycles, unchanged vs committed"
+        },
         "validate-no-architecture-cycles": {
             "implementation": "./src/executors/validate-no-architecture-cycles/executor",
             "schema": "./src/executors/validate-no-architecture-cycles/schema.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.3.136",
+  "version": "0.3.138",
   "description": "Nx-specific webpieces validation rules and graph tooling. Bundles all @webpieces rule packages with Nx graph validators and an inference plugin.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -18,10 +18,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@webpieces/ai-hook-rules": "0.3.136",
-    "@webpieces/code-rules": "0.3.136",
-    "@webpieces/eslint-rules": "0.3.136",
-    "@webpieces/rules-config": "0.3.136",
+    "@webpieces/ai-hook-rules": "0.3.138",
+    "@webpieces/code-rules": "0.3.138",
+    "@webpieces/eslint-rules": "0.3.138",
+    "@webpieces/rules-config": "0.3.138",
     "madge": "8.0.0"
   },
   "peerDependencies": {

package/src/executors/generate/executor.js

@@ -12,7 +12,28 @@ exports.default = runExecutor;
 const graph_generator_1 = require("../../lib/graph-generator");
 const graph_sorter_1 = require("../../lib/graph-sorter");
 const graph_loader_1 = require("../../lib/graph-loader");
+const runtime_markers_1 = require("../../lib/runtime-markers");
+const runtime_graph_1 = require("../../lib/runtime-graph");
+const runtime_config_1 = require("../../lib/runtime-config");
 const toError_1 = require("../../toError");
+/**
+ * Generate the runtime microservice graph alongside the compile-time graph, so
+ * one regenerate produces both committed files. Skipped when the
+ * runtime-architecture rule is OFF or no apiProjectPaths are configured.
+ */
+async function generateRuntimeGraph(workspaceRoot) {
+    const config = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot);
+    if (config.off || config.servicePaths.length === 0) {
+        console.log('⏭️  Runtime graph skipped (runtime-architecture OFF or no servicePaths)');
+        return;
+    }
+    console.log('📡 Generating runtime graph from service-contract.json files...');
+    const model = await (0, runtime_markers_1.buildWorkspaceModel)(workspaceRoot, config.apiProjectPaths, config.servicePaths);
+    const runtimeGraph = (0, runtime_graph_1.assembleRuntimeGraph)(model, workspaceRoot);
+    (0, runtime_graph_1.saveRuntimeGraph)(runtimeGraph, workspaceRoot);
+    const serviceCount = Object.keys(runtimeGraph.services).length;
+    console.log(`✅ Runtime graph saved (${serviceCount} services, ${runtimeGraph.runtimeEdges.length} runtime edges)`);
+}
 async function runExecutor(options, context) {
     const graphPath = options.graphPath;
     const workspaceRoot = context.root;
@@ -29,6 +50,8 @@ async function runExecutor(options, context) {
         console.log('💾 Saving graph to architecture/dependencies.json...');
         (0, graph_loader_1.saveGraph)(enhancedGraph, workspaceRoot, graphPath);
         console.log('✅ Graph saved successfully');
+        // Step 4: Generate the runtime microservice graph at the same time
+        await generateRuntimeGraph(workspaceRoot);
         // Print summary
         const projectCount = Object.keys(enhancedGraph).length;
         const levels = new Set(Object.values(enhancedGraph).map((e) => e.level));

package/src/executors/generate/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/generate/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAgBH,8BAqCC;AAlDD,+DAAiE;AACjE,yDAAgE;AAChE,yDAAmD;AACnD,2CAAwC;AAUzB,KAAK,UAAU,WAAW,CACrC,OAAgC,EAChC,OAAwB;IAExB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAC;IAEnD,8DAA8D;IAC9D,IAAI,CAAC;QACD,gFAAgF;QAChF,OAAO,CAAC,GAAG,CAAC,2DAA2D,CAAC,CAAC;QACzE,MAAM,YAAY,GAAG,MAAM,IAAA,sCAAoB,GAAE,CAAC;QAElD,gEAAgE;QAChE,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;QAClD,MAAM,aAAa,GAAG,IAAA,qCAAsB,EAAC,YAAY,CAAC,CAAC;QAE3D,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,sDAAsD,CAAC,CAAC;QACpE,IAAA,wBAAS,EAAC,aAAa,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;QAE1C,gBAAgB;QAChB,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC;QACvD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QACzE,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QACnC,OAAO,CAAC,GAAG,CAAC,gBAAgB,YAAY,EAAE,CAAC,CAAC;QAC5C,OAAO,CAAC,GAAG,CAAC,cAAc,MAAM,CAAC,IAAI,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAEpE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json.\n *\n * Usage:\n * nx run architecture:generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { saveGraph } from '../../lib/graph-loader';\nimport { toError } from '../../toError';\n\nexport interface GenerateExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nexport default async function runExecutor(\n    options: GenerateExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n📊 Architecture Graph Generator\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Step 1: Build the full graph from nx, then transitively reduce it to the view\n        console.log(\"📊 Generating dependency graph from nx's project graph...\");\n        const reducedGraph = await generateReducedGraph();\n\n        // Step 2: Topological sort (to assign levels for visualization)\n        console.log('🔄 Computing topological layers...');\n        const enhancedGraph = sortGraphTopologically(reducedGraph);\n\n        // Step 3: Save the graph\n        console.log('💾 Saving graph to architecture/dependencies.json...');\n        saveGraph(enhancedGraph, workspaceRoot, graphPath);\n        console.log('✅ Graph saved successfully');\n\n        // Print summary\n        const projectCount = Object.keys(enhancedGraph).length;\n        const levels = new Set(Object.values(enhancedGraph).map((e) => e.level));\n        console.log(`\\n📈 Graph Summary:`);\n        console.log(`   Projects: ${projectCount}`);\n        console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Graph generation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json.\n *\n * Usage:\n * nx run architecture:generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { saveGraph } from '../../lib/graph-loader';\nimport { buildWorkspaceModel } from '../../lib/runtime-markers';\nimport { assembleRuntimeGraph, saveRuntimeGraph } from '../../lib/runtime-graph';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { toError } from '../../toError';\n\nexport interface GenerateExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n/**\n * Generate the runtime microservice graph alongside the compile-time graph, so\n * one regenerate produces both committed files. Skipped when the\n * runtime-architecture rule is OFF or no apiProjectPaths are configured.\n */\nasync function generateRuntimeGraph(workspaceRoot: string): Promise<void> {\n    const config = loadRuntimeConfig(workspaceRoot);\n    if (config.off || config.servicePaths.length === 0) {\n        console.log('⏭️  Runtime graph skipped (runtime-architecture OFF or no servicePaths)');\n        return;\n    }\n    console.log('📡 Generating runtime graph from service-contract.json files...');\n    const model = await buildWorkspaceModel(workspaceRoot, config.apiProjectPaths, config.servicePaths);\n    const runtimeGraph = assembleRuntimeGraph(model, workspaceRoot);\n    saveRuntimeGraph(runtimeGraph, workspaceRoot);\n    const serviceCount = Object.keys(runtimeGraph.services).length;\n    console.log(\n        `✅ Runtime graph saved (${serviceCount} services, ${runtimeGraph.runtimeEdges.length} runtime edges)`,\n    );\n}\n\nexport default async function runExecutor(\n    options: GenerateExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n📊 Architecture Graph Generator\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Step 1: Build the full graph from nx, then transitively reduce it to the view\n        console.log(\"📊 Generating dependency graph from nx's project graph...\");\n        const reducedGraph = await generateReducedGraph();\n\n        // Step 2: Topological sort (to assign levels for visualization)\n        console.log('🔄 Computing topological layers...');\n        const enhancedGraph = sortGraphTopologically(reducedGraph);\n\n        // Step 3: Save the graph\n        console.log('💾 Saving graph to architecture/dependencies.json...');\n        saveGraph(enhancedGraph, workspaceRoot, graphPath);\n        console.log('✅ Graph saved successfully');\n\n        // Step 4: Generate the runtime microservice graph at the same time\n        await generateRuntimeGraph(workspaceRoot);\n\n        // Print summary\n        const projectCount = Object.keys(enhancedGraph).length;\n        const levels = new Set(Object.values(enhancedGraph).map((e) => e.level));\n        console.log(`\\n📈 Graph Summary:`);\n        console.log(`   Projects: ${projectCount}`);\n        console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Graph generation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}

package/src/executors/validate-runtime-architecture/executor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Validate Runtime Architecture Executor (workspace)
+ *
+ * Two workspace-level checks on the runtime microservice graph:
+ *   1. No-cycles: every runtime cycle must be in the `allowedCycles` allowlist
+ *      with an unexpired `until`; any other cycle fails the build.
+ *   2. Unchanged: the freshly-assembled graph must match the committed
+ *      architecture/runtime-dependencies.json (run `architecture:generate`).
+ *
+ * On/off + a whole-rule grace window come from webpieces.config.json
+ * (rule: runtime-architecture).
+ *
+ * Usage: nx run microsvc:validate-runtime-architecture
+ */
+import type { ExecutorContext } from '@nx/devkit';
+export interface ValidateRuntimeArchitectureOptions {
+}
+export interface ExecutorResult {
+    success: boolean;
+}
+export default function runExecutor(_options: ValidateRuntimeArchitectureOptions, context: ExecutorContext): Promise<ExecutorResult>;

package/src/executors/validate-runtime-architecture/executor.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Validate Runtime Architecture Executor (workspace)
+ *
+ * Two workspace-level checks on the runtime microservice graph:
+ *   1. No-cycles: every runtime cycle must be in the `allowedCycles` allowlist
+ *      with an unexpired `until`; any other cycle fails the build.
+ *   2. Unchanged: the freshly-assembled graph must match the committed
+ *      architecture/runtime-dependencies.json (run `architecture:generate`).
+ *
+ * On/off + a whole-rule grace window come from webpieces.config.json
+ * (rule: runtime-architecture).
+ *
+ * Usage: nx run microsvc:validate-runtime-architecture
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = runExecutor;
+const runtime_markers_1 = require("../../lib/runtime-markers");
+const runtime_graph_1 = require("../../lib/runtime-graph");
+const runtime_cycles_1 = require("../../lib/runtime-cycles");
+const runtime_config_1 = require("../../lib/runtime-config");
+/** Allowlist keys (sorted-services -> entry) that are still in their grace window. */
+function activeAllowedKeys(allowed) {
+    const nowSeconds = Date.now() / 1000;
+    const map = new Map();
+    for (const entry of allowed) {
+        const active = entry.until === undefined || nowSeconds < entry.until;
+        if (active)
+            map.set((0, runtime_cycles_1.cycleKey)(entry.services), entry);
+    }
+    return map;
+}
+/** Returns disallowed-cycle messages (empty = all cycles allowed or none). */
+function checkCycles(graph, allowed) {
+    const cycles = (0, runtime_cycles_1.findRuntimeCycles)((0, runtime_graph_1.runtimeAdjacency)(graph));
+    if (cycles.length === 0)
+        return [];
+    const activeAllow = activeAllowedKeys(allowed);
+    const problems = [];
+    for (const cycle of cycles) {
+        const entry = activeAllow.get(cycle.key);
+        if (entry) {
+            console.log(`⏳ Allowed runtime cycle [${cycle.services.join(' <-> ')}] — ${entry.reason ?? 'no reason given'}`);
+            continue;
+        }
+        problems.push(`runtime cycle: ${cycle.services.join(' -> ')} -> ${cycle.services[0]}`);
+    }
+    return problems;
+}
+/** Returns an unchanged-check message, or null if the committed graph matches. */
+function checkUnchanged(workspaceRoot, current) {
+    if (!(0, runtime_graph_1.runtimeGraphFileExists)(workspaceRoot)) {
+        return 'No committed architecture/runtime-dependencies.json — run: nx run architecture:generate';
+    }
+    const saved = (0, runtime_graph_1.loadRuntimeGraph)(workspaceRoot);
+    if (saved && (0, runtime_graph_1.serializeRuntimeGraph)(saved) === (0, runtime_graph_1.serializeRuntimeGraph)(current))
+        return null;
+    return 'Runtime graph changed since last commit — run: nx run architecture:generate and commit the result';
+}
+async function runExecutor(_options, context) {
+    const workspaceRoot = context.root;
+    const config = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot);
+    if (config.off) {
+        console.log(`\n⏭️  Skipping ${runtime_config_1.RUNTIME_RULE_NAME} (mode: OFF)\n`);
+        return { success: true };
+    }
+    if (config.servicePaths.length === 0) {
+        console.log(`\n⏭️  ${runtime_config_1.RUNTIME_RULE_NAME}: no servicePaths configured — nothing to validate\n`);
+        return { success: true };
+    }
+    console.log('\n📡 Validating runtime microservice architecture\n');
+    const model = await (0, runtime_markers_1.buildWorkspaceModel)(workspaceRoot, config.apiProjectPaths, config.servicePaths);
+    const graph = (0, runtime_graph_1.assembleRuntimeGraph)(model, workspaceRoot);
+    const problems = checkCycles(graph, config.allowedCycles);
+    const unchanged = checkUnchanged(workspaceRoot, graph);
+    if (unchanged)
+        problems.push(unchanged);
+    for (const u of graph.unresolvedUses) {
+        console.log(`⚠️  ${u.service} uses "${u.api}" but no in-repo service implements it (external?)`);
+    }
+    if (problems.length === 0) {
+        console.log('✅ Runtime architecture valid (no disallowed cycles, graph unchanged)\n');
+        return { success: true };
+    }
+    console.error('\n❌ Runtime architecture validation failed:\n');
+    for (const p of problems)
+        console.error(`  - ${p}`);
+    console.error('\nAllow a cycle temporarily via runtime-architecture.allowedCycles (services + reason + until) in webpieces.config.json.\n');
+    if ((0, runtime_config_1.isGraceActive)(config.ignoreModifiedUntilEpoch)) {
+        console.log(`⏳ Reported but not failing (ignoreModifiedUntilEpoch active, expires ${(0, runtime_config_1.epochDate)(config.ignoreModifiedUntilEpoch)}).\n`);
+        return { success: true };
+    }
+    return { success: false };
+}
+//# sourceMappingURL=executor.js.map

package/src/executors/validate-runtime-architecture/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-runtime-architecture/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Runtime Architecture Executor (workspace)\n *\n * Two workspace-level checks on the runtime microservice graph:\n *   1. No-cycles: every runtime cycle must be in the `allowedCycles` allowlist\n *      with an unexpired `until`; any other cycle fails the build.\n *   2. Unchanged: the freshly-assembled graph must match the committed\n *      architecture/runtime-dependencies.json (run `architecture:generate`).\n *\n * On/off + a whole-rule grace window come from webpieces.config.json\n * (rule: runtime-architecture).\n *\n * Usage: nx run microsvc:validate-runtime-architecture\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { buildWorkspaceModel } from '../../lib/runtime-markers';\nimport {\n    assembleRuntimeGraph,\n    loadRuntimeGraph,\n    runtimeAdjacency,\n    runtimeGraphFileExists,\n    serializeRuntimeGraph,\n} from '../../lib/runtime-graph';\nimport type { RuntimeGraph } from '../../lib/runtime-graph';\nimport { findRuntimeCycles, cycleKey } from '../../lib/runtime-cycles';\nimport type { AllowedCycle } from '../../lib/runtime-config';\nimport { loadRuntimeConfig, isGraceActive, epochDate, RUNTIME_RULE_NAME } from '../../lib/runtime-config';\n\nexport interface ValidateRuntimeArchitectureOptions {\n    // Config comes from webpieces.config.json at runtime.\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n/** Allowlist keys (sorted-services -> entry) that are still in their grace window. */\nfunction activeAllowedKeys(allowed: AllowedCycle[]): Map<string, AllowedCycle> {\n    const nowSeconds = Date.now() / 1000;\n    const map = new Map<string, AllowedCycle>();\n    for (const entry of allowed) {\n        const active = entry.until === undefined || nowSeconds < entry.until;\n        if (active) map.set(cycleKey(entry.services), entry);\n    }\n    return map;\n}\n\n/** Returns disallowed-cycle messages (empty = all cycles allowed or none). */\nfunction checkCycles(graph: RuntimeGraph, allowed: AllowedCycle[]): string[] {\n    const cycles = findRuntimeCycles(runtimeAdjacency(graph));\n    if (cycles.length === 0) return [];\n\n    const activeAllow = activeAllowedKeys(allowed);\n    const problems: string[] = [];\n    for (const cycle of cycles) {\n        const entry = activeAllow.get(cycle.key);\n        if (entry) {\n            console.log(`⏳ Allowed runtime cycle [${cycle.services.join(' <-> ')}] — ${entry.reason ?? 'no reason given'}`);\n            continue;\n        }\n        problems.push(`runtime cycle: ${cycle.services.join(' -> ')} -> ${cycle.services[0]}`);\n    }\n    return problems;\n}\n\n/** Returns an unchanged-check message, or null if the committed graph matches. */\nfunction checkUnchanged(workspaceRoot: string, current: RuntimeGraph): string | null {\n    if (!runtimeGraphFileExists(workspaceRoot)) {\n        return 'No committed architecture/runtime-dependencies.json — run: nx run architecture:generate';\n    }\n    const saved = loadRuntimeGraph(workspaceRoot);\n    if (saved && serializeRuntimeGraph(saved) === serializeRuntimeGraph(current)) return null;\n    return 'Runtime graph changed since last commit — run: nx run architecture:generate and commit the result';\n}\n\nexport default async function runExecutor(\n    _options: ValidateRuntimeArchitectureOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n    const config = loadRuntimeConfig(workspaceRoot);\n\n    if (config.off) {\n        console.log(`\\n⏭️  Skipping ${RUNTIME_RULE_NAME} (mode: OFF)\\n`);\n        return { success: true };\n    }\n    if (config.servicePaths.length === 0) {\n        console.log(`\\n⏭️  ${RUNTIME_RULE_NAME}: no servicePaths configured — nothing to validate\\n`);\n        return { success: true };\n    }\n\n    console.log('\\n📡 Validating runtime microservice architecture\\n');\n    const model = await buildWorkspaceModel(workspaceRoot, config.apiProjectPaths, config.servicePaths);\n    const graph = assembleRuntimeGraph(model, workspaceRoot);\n\n    const problems: string[] = checkCycles(graph, config.allowedCycles);\n    const unchanged = checkUnchanged(workspaceRoot, graph);\n    if (unchanged) problems.push(unchanged);\n\n    for (const u of graph.unresolvedUses) {\n        console.log(`⚠️  ${u.service} uses \"${u.api}\" but no in-repo service implements it (external?)`);\n    }\n\n    if (problems.length === 0) {\n        console.log('✅ Runtime architecture valid (no disallowed cycles, graph unchanged)\\n');\n        return { success: true };\n    }\n\n    console.error('\\n❌ Runtime architecture validation failed:\\n');\n    for (const p of problems) console.error(`  - ${p}`);\n    console.error('\\nAllow a cycle temporarily via runtime-architecture.allowedCycles (services + reason + until) in webpieces.config.json.\\n');\n\n    if (isGraceActive(config.ignoreModifiedUntilEpoch)) {\n        console.log(`⏳ Reported but not failing (ignoreModifiedUntilEpoch active, expires ${epochDate(config.ignoreModifiedUntilEpoch!)}).\\n`);\n        return { success: true };\n    }\n    return { success: false };\n}\n"]}

package/src/executors/validate-runtime-architecture/schema.json

@@ -0,0 +1,8 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate Runtime Architecture Executor",
+    "description": "Workspace: validate the runtime microservice graph has no disallowed cycles and matches the committed runtime-dependencies.json. Config from webpieces.config.json (runtime-architecture).",
+    "type": "object",
+    "properties": {},
+    "required": []
+}

package/src/executors/validate-runtime-markers/executor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Validate Runtime Markers Executor (per-project)
+ *
+ * Validates ONE service's `service-contract.json` against its actual api-project
+ * dependencies (from the Nx graph), independently of all other projects:
+ *
+ *   set(api-project deps) === set(implements ∪ uses declared in the contract)
+ *
+ * - Every service (root matches servicePaths) MUST have a service-contract.json
+ *   -> FAIL if missing.
+ * - An api-project dependency not declared in the contract -> FAIL (undeclared).
+ * - A contract entry that is not an actual api dependency  -> FAIL (phantom).
+ *
+ * Only service projects are checked; non-services pass. On/off + a whole-rule
+ * grace window come from webpieces.config.json (rule: runtime-architecture).
+ *
+ * Usage: nx run <project>:validate-runtime-markers
+ */
+import type { ExecutorContext } from '@nx/devkit';
+export interface ValidateRuntimeMarkersOptions {
+}
+export interface ExecutorResult {
+    success: boolean;
+}
+export default function runExecutor(_options: ValidateRuntimeMarkersOptions, context: ExecutorContext): Promise<ExecutorResult>;

package/src/executors/validate-runtime-markers/executor.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Validate Runtime Markers Executor (per-project)
+ *
+ * Validates ONE service's `service-contract.json` against its actual api-project
+ * dependencies (from the Nx graph), independently of all other projects:
+ *
+ *   set(api-project deps) === set(implements ∪ uses declared in the contract)
+ *
+ * - Every service (root matches servicePaths) MUST have a service-contract.json
+ *   -> FAIL if missing.
+ * - An api-project dependency not declared in the contract -> FAIL (undeclared).
+ * - A contract entry that is not an actual api dependency  -> FAIL (phantom).
+ *
+ * Only service projects are checked; non-services pass. On/off + a whole-rule
+ * grace window come from webpieces.config.json (rule: runtime-architecture).
+ *
+ * Usage: nx run <project>:validate-runtime-markers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = runExecutor;
+const runtime_markers_1 = require("../../lib/runtime-markers");
+const runtime_config_1 = require("../../lib/runtime-config");
+function apiDepsOf(model, info) {
+    return info.deps.filter((dep) => model.projects.get(dep)?.isApi === true).sort();
+}
+async function runExecutor(_options, context) {
+    const workspaceRoot = context.root;
+    const config = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot);
+    if (config.off) {
+        console.log(`\n⏭️  Skipping ${runtime_config_1.RUNTIME_RULE_NAME} markers (mode: OFF)\n`);
+        return { success: true };
+    }
+    if (config.servicePaths.length === 0) {
+        return { success: true };
+    }
+    const projectName = context.projectName ?? '';
+    const model = await (0, runtime_markers_1.buildWorkspaceModel)(workspaceRoot, config.apiProjectPaths, config.servicePaths);
+    const info = model.projects.get(projectName);
+    if (!info || !info.isService) {
+        return { success: true };
+    }
+    const violations = collectViolations(model, info, workspaceRoot);
+    if (violations.length === 0) {
+        console.log(`\n✅ ${projectName}: service-contract.json matches api dependencies\n`);
+        return { success: true };
+    }
+    console.error(`\n❌ ${projectName}: service-contract.json does not match api dependencies:\n`);
+    for (const v of violations)
+        console.error(`  - ${v}`);
+    console.error(`\nFix ${info.root}/service-contract.json so "implements" ∪ "uses" equals the api projects in deps.\n`);
+    if ((0, runtime_config_1.isGraceActive)(config.ignoreModifiedUntilEpoch)) {
+        console.log(`⏳ Reported but not failing (ignoreModifiedUntilEpoch active, expires ${(0, runtime_config_1.epochDate)(config.ignoreModifiedUntilEpoch)}).\n`);
+        return { success: true };
+    }
+    return { success: false };
+}
+/** Bidirectional-exact comparison of api deps vs the service contract. */
+function collectViolations(model, info, workspaceRoot) {
+    const apiDeps = apiDepsOf(model, info);
+    const contract = (0, runtime_markers_1.readServiceContract)(workspaceRoot, info.root);
+    if (!contract) {
+        return [`missing service-contract.json (every service requires one)`];
+    }
+    const declaredNames = Array.from(new Set([...contract.implements, ...contract.uses]));
+    const resolved = (0, runtime_markers_1.resolvePackageNames)(model, declaredNames);
+    const declaredProjects = new Set(resolved.projects);
+    const apiDepSet = new Set(apiDeps);
+    const violations = [];
+    for (const pkg of resolved.unknown) {
+        violations.push(`declared "${pkg}" which is not a workspace package`);
+    }
+    for (const proj of resolved.projects) {
+        if (!model.projects.get(proj)?.isApi) {
+            violations.push(`declared "${proj}" which is not an api project`);
+        }
+    }
+    for (const dep of apiDeps) {
+        if (!declaredProjects.has(dep)) {
+            violations.push(`api dependency "${dep}" is not declared in service-contract.json`);
+        }
+    }
+    for (const proj of declaredProjects) {
+        if (model.projects.get(proj)?.isApi && !apiDepSet.has(proj)) {
+            violations.push(`service-contract.json declares "${proj}" but it is not an actual dependency`);
+        }
+    }
+    return violations;
+}
+//# sourceMappingURL=executor.js.map

package/src/executors/validate-runtime-markers/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-runtime-markers/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Runtime Markers Executor (per-project)\n *\n * Validates ONE service's `service-contract.json` against its actual api-project\n * dependencies (from the Nx graph), independently of all other projects:\n *\n *   set(api-project deps) === set(implements ∪ uses declared in the contract)\n *\n * - Every service (root matches servicePaths) MUST have a service-contract.json\n *   -> FAIL if missing.\n * - An api-project dependency not declared in the contract -> FAIL (undeclared).\n * - A contract entry that is not an actual api dependency  -> FAIL (phantom).\n *\n * Only service projects are checked; non-services pass. On/off + a whole-rule\n * grace window come from webpieces.config.json (rule: runtime-architecture).\n *\n * Usage: nx run <project>:validate-runtime-markers\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { buildWorkspaceModel, readServiceContract, resolvePackageNames } from '../../lib/runtime-markers';\nimport type { WorkspaceModel, ProjectInfo } from '../../lib/runtime-markers';\nimport { loadRuntimeConfig, isGraceActive, epochDate, RUNTIME_RULE_NAME } from '../../lib/runtime-config';\n\nexport interface ValidateRuntimeMarkersOptions {\n    // Config comes from webpieces.config.json at runtime.\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nfunction apiDepsOf(model: WorkspaceModel, info: ProjectInfo): string[] {\n    return info.deps.filter((dep: string) => model.projects.get(dep)?.isApi === true).sort();\n}\n\nexport default async function runExecutor(\n    _options: ValidateRuntimeMarkersOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n    const config = loadRuntimeConfig(workspaceRoot);\n\n    if (config.off) {\n        console.log(`\\n⏭️  Skipping ${RUNTIME_RULE_NAME} markers (mode: OFF)\\n`);\n        return { success: true };\n    }\n    if (config.servicePaths.length === 0) {\n        return { success: true };\n    }\n\n    const projectName = context.projectName ?? '';\n    const model = await buildWorkspaceModel(workspaceRoot, config.apiProjectPaths, config.servicePaths);\n    const info = model.projects.get(projectName);\n    if (!info || !info.isService) {\n        return { success: true };\n    }\n\n    const violations = collectViolations(model, info, workspaceRoot);\n    if (violations.length === 0) {\n        console.log(`\\n✅ ${projectName}: service-contract.json matches api dependencies\\n`);\n        return { success: true };\n    }\n\n    console.error(`\\n❌ ${projectName}: service-contract.json does not match api dependencies:\\n`);\n    for (const v of violations) console.error(`  - ${v}`);\n    console.error(`\\nFix ${info.root}/service-contract.json so \"implements\" ∪ \"uses\" equals the api projects in deps.\\n`);\n\n    if (isGraceActive(config.ignoreModifiedUntilEpoch)) {\n        console.log(`⏳ Reported but not failing (ignoreModifiedUntilEpoch active, expires ${epochDate(config.ignoreModifiedUntilEpoch!)}).\\n`);\n        return { success: true };\n    }\n    return { success: false };\n}\n\n/** Bidirectional-exact comparison of api deps vs the service contract. */\nfunction collectViolations(model: WorkspaceModel, info: ProjectInfo, workspaceRoot: string): string[] {\n    const apiDeps = apiDepsOf(model, info);\n    const contract = readServiceContract(workspaceRoot, info.root);\n\n    if (!contract) {\n        return [`missing service-contract.json (every service requires one)`];\n    }\n\n    const declaredNames = Array.from(new Set([...contract.implements, ...contract.uses]));\n    const resolved = resolvePackageNames(model, declaredNames);\n    const declaredProjects = new Set(resolved.projects);\n    const apiDepSet = new Set(apiDeps);\n\n    const violations: string[] = [];\n    for (const pkg of resolved.unknown) {\n        violations.push(`declared \"${pkg}\" which is not a workspace package`);\n    }\n    for (const proj of resolved.projects) {\n        if (!model.projects.get(proj)?.isApi) {\n            violations.push(`declared \"${proj}\" which is not an api project`);\n        }\n    }\n    for (const dep of apiDeps) {\n        if (!declaredProjects.has(dep)) {\n            violations.push(`api dependency \"${dep}\" is not declared in service-contract.json`);\n        }\n    }\n    for (const proj of declaredProjects) {\n        if (model.projects.get(proj)?.isApi && !apiDepSet.has(proj)) {\n            violations.push(`service-contract.json declares \"${proj}\" but it is not an actual dependency`);\n        }\n    }\n    return violations;\n}\n"]}

package/src/executors/validate-runtime-markers/schema.json

@@ -0,0 +1,8 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate Runtime Markers Executor",
+    "description": "Per-project: validate live.json matches the project's api-project dependencies. Config from webpieces.config.json (runtime-architecture).",
+    "type": "object",
+    "properties": {},
+    "required": []
+}

package/src/executors/visualize-runtime/executor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Visualize Runtime Executor
+ *
+ * Renders the runtime microservice graph (committed
+ * architecture/runtime-dependencies.json) to DOT + HTML and opens it.
+ *
+ * Usage: nx run microsvc:visualize
+ */
+import type { ExecutorContext } from '@nx/devkit';
+export interface VisualizeRuntimeOptions {
+}
+export interface ExecutorResult {
+    success: boolean;
+}
+export default function runExecutor(_options: VisualizeRuntimeOptions, context: ExecutorContext): Promise<ExecutorResult>;

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

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Visualize Runtime Executor
+ *
+ * Renders the runtime microservice graph (committed
+ * architecture/runtime-dependencies.json) to DOT + HTML and opens it.
+ *
+ * Usage: nx run microsvc:visualize
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = runExecutor;
+const runtime_graph_1 = require("../../lib/runtime-graph");
+const runtime_visualizer_1 = require("../../lib/runtime-visualizer");
+const graph_visualizer_1 = require("../../lib/graph-visualizer");
+const toError_1 = require("../../toError");
+async function runExecutor(_options, context) {
+    const workspaceRoot = context.root;
+    console.log('\n🎨 Runtime Microservice Visualization\n');
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const graph = (0, runtime_graph_1.loadRuntimeGraph)(workspaceRoot);
+        if (!graph) {
+            console.error('❌ No architecture/runtime-dependencies.json found');
+            console.error('   Run: nx run architecture:generate first');
+            return { success: false };
+        }
+        const vizPaths = (0, runtime_visualizer_1.writeRuntimeVisualization)(graph, workspaceRoot);
+        console.log(`✅ Generated: ${vizPaths.dotPath}`);
+        console.log(`✅ Generated: ${vizPaths.htmlPath}`);
+        console.log('\n🌐 Opening visualization in browser...');
+        if ((0, graph_visualizer_1.openVisualization)(vizPaths.htmlPath)) {
+            console.log('✅ Browser opened');
+        }
+        else {
+            console.log(`⚠️  Could not auto-open. Open manually: ${vizPaths.htmlPath}`);
+        }
+        return { success: true };
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        console.error('❌ Runtime visualization failed:', error.message);
+        return { success: false };
+    }
+}
+//# sourceMappingURL=executor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/visualize-runtime/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAgBH,8BAkCC;AA/CD,2DAA2D;AAC3D,qEAAyE;AACzE,iEAA+D;AAC/D,2CAAwC;AAUzB,KAAK,UAAU,WAAW,CACrC,QAAiC,EACjC,OAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;IAEzD,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,KAAK,GAAG,IAAA,gCAAgB,EAAC,aAAa,CAAC,CAAC;QAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,OAAO,CAAC,KAAK,CAAC,mDAAmD,CAAC,CAAC;YACnE,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAC5D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAED,MAAM,QAAQ,GAAG,IAAA,8CAAyB,EAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QACjE,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEjD,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACxD,IAAI,IAAA,oCAAiB,EAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,GAAG,CAAC,2CAA2C,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChF,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAChE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Visualize Runtime Executor\n *\n * Renders the runtime microservice graph (committed\n * architecture/runtime-dependencies.json) to DOT + HTML and opens it.\n *\n * Usage: nx run microsvc:visualize\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { loadRuntimeGraph } from '../../lib/runtime-graph';\nimport { writeRuntimeVisualization } from '../../lib/runtime-visualizer';\nimport { openVisualization } from '../../lib/graph-visualizer';\nimport { toError } from '../../toError';\n\nexport interface VisualizeRuntimeOptions {\n    // No options.\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nexport default async function runExecutor(\n    _options: VisualizeRuntimeOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n\n    console.log('\\n🎨 Runtime Microservice Visualization\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const graph = loadRuntimeGraph(workspaceRoot);\n        if (!graph) {\n            console.error('❌ No architecture/runtime-dependencies.json found');\n            console.error('   Run: nx run architecture:generate first');\n            return { success: false };\n        }\n\n        const vizPaths = writeRuntimeVisualization(graph, workspaceRoot);\n        console.log(`✅ Generated: ${vizPaths.dotPath}`);\n        console.log(`✅ Generated: ${vizPaths.htmlPath}`);\n\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (openVisualization(vizPaths.htmlPath)) {\n            console.log('✅ Browser opened');\n        } else {\n            console.log(`⚠️  Could not auto-open. Open manually: ${vizPaths.htmlPath}`);\n        }\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Runtime visualization failed:', error.message);\n        return { success: false };\n    }\n}\n"]}

package/src/executors/visualize-runtime/schema.json

@@ -0,0 +1,8 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Visualize Runtime Executor",
+    "description": "Render the runtime microservice graph (runtime-dependencies.json) to DOT + HTML.",
+    "type": "object",
+    "properties": {},
+    "required": []
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Runtime Config
+ *
+ * Loads the `runtime-architecture` rule from webpieces.config.json and exposes
+ * typed accessors shared by the generate + validate + visualize executors.
+ *
+ *   "runtime-architecture": {
+ *     "mode": "ON",                          // "OFF" disables the whole feature
+ *     "apiProjectPaths": ["libraries/apis/*"],
+ *     "ignoreModifiedUntilEpoch": 0,         // whole-rule punt (epoch seconds)
+ *     "allowedCycles": [ { "services": ["a","b"], "reason": "...", "until": 1771931925 } ]
+ *   }
+ */
+export declare const RUNTIME_RULE_NAME = "runtime-architecture";
+export interface AllowedCycle {
+    services: string[];
+    reason?: string;
+    until?: number;
+}
+export interface RuntimeRuleConfig {
+    off: boolean;
+    apiProjectPaths: string[];
+    servicePaths: string[];
+    ignoreModifiedUntilEpoch?: number;
+    allowedCycles: AllowedCycle[];
+}
+/** Load the runtime-architecture rule config (with safe defaults). */
+export declare function loadRuntimeConfig(workspaceRoot: string): RuntimeRuleConfig;
+/**
+ * Whole-rule grace window: while now < epoch, failures are reported but do not
+ * fail the build (warn). Mirrors the other webpieces rules.
+ */
+export declare function isGraceActive(epoch: number | undefined): boolean;
+/** Format the epoch as an ISO date for log messages. */
+export declare function epochDate(epoch: number): string;

package/src/lib/runtime-config.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Runtime Config
+ *
+ * Loads the `runtime-architecture` rule from webpieces.config.json and exposes
+ * typed accessors shared by the generate + validate + visualize executors.
+ *
+ *   "runtime-architecture": {
+ *     "mode": "ON",                          // "OFF" disables the whole feature
+ *     "apiProjectPaths": ["libraries/apis/*"],
+ *     "ignoreModifiedUntilEpoch": 0,         // whole-rule punt (epoch seconds)
+ *     "allowedCycles": [ { "services": ["a","b"], "reason": "...", "until": 1771931925 } ]
+ *   }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_RULE_NAME = void 0;
+exports.loadRuntimeConfig = loadRuntimeConfig;
+exports.isGraceActive = isGraceActive;
+exports.epochDate = epochDate;
+const rules_config_1 = require("@webpieces/rules-config");
+exports.RUNTIME_RULE_NAME = 'runtime-architecture';
+function isUsableCycle(cycle) {
+    return Array.isArray(cycle.services) && cycle.services.length > 0;
+}
+/** Load the runtime-architecture rule config (with safe defaults). */
+function loadRuntimeConfig(workspaceRoot) {
+    const shared = (0, rules_config_1.loadConfig)(workspaceRoot);
+    const rule = shared.rules.get(exports.RUNTIME_RULE_NAME);
+    const raw = (rule?.options ?? {});
+    return {
+        off: rule?.isOff ?? false,
+        apiProjectPaths: Array.isArray(raw.apiProjectPaths) ? raw.apiProjectPaths : [],
+        servicePaths: Array.isArray(raw.servicePaths) ? raw.servicePaths : [],
+        ignoreModifiedUntilEpoch: typeof raw.ignoreModifiedUntilEpoch === 'number' ? raw.ignoreModifiedUntilEpoch : undefined,
+        allowedCycles: Array.isArray(raw.allowedCycles) ? raw.allowedCycles.filter(isUsableCycle) : [],
+    };
+}
+/**
+ * Whole-rule grace window: while now < epoch, failures are reported but do not
+ * fail the build (warn). Mirrors the other webpieces rules.
+ */
+function isGraceActive(epoch) {
+    if (epoch === undefined)
+        return false;
+    return Date.now() / 1000 < epoch;
+}
+/** Format the epoch as an ISO date for log messages. */
+function epochDate(epoch) {
+    return new Date(epoch * 1000).toISOString().split('T')[0];
+}
+//# sourceMappingURL=runtime-config.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-config.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAqCH,8CAYC;AAMD,sCAGC;AAGD,8BAEC;AA7DD,0DAAqD;AAExC,QAAA,iBAAiB,GAAG,sBAAsB,CAAC;AA4BxD,SAAS,aAAa,CAAC,KAAmB;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACtE,CAAC;AAED,sEAAsE;AACtE,SAAgB,iBAAiB,CAAC,aAAqB;IACnD,MAAM,MAAM,GAAG,IAAA,yBAAU,EAAC,aAAa,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,yBAAiB,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAmB,CAAC;IACpD,OAAO;QACH,GAAG,EAAE,IAAI,EAAE,KAAK,IAAI,KAAK;QACzB,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE;QAC9E,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE;QACrE,wBAAwB,EACpB,OAAO,GAAG,CAAC,wBAAwB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS;QAC/F,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE;KACjG,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,KAAyB;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,KAAK,CAAC;AACrC,CAAC;AAED,wDAAwD;AACxD,SAAgB,SAAS,CAAC,KAAa;IACnC,OAAO,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["/**\n * Runtime Config\n *\n * Loads the `runtime-architecture` rule from webpieces.config.json and exposes\n * typed accessors shared by the generate + validate + visualize executors.\n *\n *   \"runtime-architecture\": {\n *     \"mode\": \"ON\",                          // \"OFF\" disables the whole feature\n *     \"apiProjectPaths\": [\"libraries/apis/*\"],\n *     \"ignoreModifiedUntilEpoch\": 0,         // whole-rule punt (epoch seconds)\n *     \"allowedCycles\": [ { \"services\": [\"a\",\"b\"], \"reason\": \"...\", \"until\": 1771931925 } ]\n *   }\n */\n\nimport { loadConfig } from '@webpieces/rules-config';\n\nexport const RUNTIME_RULE_NAME = 'runtime-architecture';\n\nexport interface AllowedCycle {\n    services: string[];\n    reason?: string;\n    until?: number;\n}\n\nexport interface RuntimeRuleConfig {\n    off: boolean;\n    apiProjectPaths: string[];\n    servicePaths: string[];\n    ignoreModifiedUntilEpoch?: number;\n    allowedCycles: AllowedCycle[];\n}\n\n/**\n * Typed view of the opaque webpieces.config.json option bag for this rule. The\n * config is trusted (it is the workspace's own file), so we cast once here and\n * defensively narrow arrays/numbers rather than threading `unknown` everywhere.\n */\ninterface RuntimeRuleRaw {\n    apiProjectPaths?: string[];\n    servicePaths?: string[];\n    ignoreModifiedUntilEpoch?: number;\n    allowedCycles?: AllowedCycle[];\n}\n\nfunction isUsableCycle(cycle: AllowedCycle): boolean {\n    return Array.isArray(cycle.services) && cycle.services.length > 0;\n}\n\n/** Load the runtime-architecture rule config (with safe defaults). */\nexport function loadRuntimeConfig(workspaceRoot: string): RuntimeRuleConfig {\n    const shared = loadConfig(workspaceRoot);\n    const rule = shared.rules.get(RUNTIME_RULE_NAME);\n    const raw = (rule?.options ?? {}) as RuntimeRuleRaw;\n    return {\n        off: rule?.isOff ?? false,\n        apiProjectPaths: Array.isArray(raw.apiProjectPaths) ? raw.apiProjectPaths : [],\n        servicePaths: Array.isArray(raw.servicePaths) ? raw.servicePaths : [],\n        ignoreModifiedUntilEpoch:\n            typeof raw.ignoreModifiedUntilEpoch === 'number' ? raw.ignoreModifiedUntilEpoch : undefined,\n        allowedCycles: Array.isArray(raw.allowedCycles) ? raw.allowedCycles.filter(isUsableCycle) : [],\n    };\n}\n\n/**\n * Whole-rule grace window: while now < epoch, failures are reported but do not\n * fail the build (warn). Mirrors the other webpieces rules.\n */\nexport function isGraceActive(epoch: number | undefined): boolean {\n    if (epoch === undefined) return false;\n    return Date.now() / 1000 < epoch;\n}\n\n/** Format the epoch as an ISO date for log messages. */\nexport function epochDate(epoch: number): string {\n    return new Date(epoch * 1000).toISOString().split('T')[0];\n}\n"]}

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

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+export interface RuntimeCycle {
+    /** Sorted service names participating in the cycle. */
+    services: string[];
+    /** Canonical key: services sorted then joined with ",". */
+    key: string;
+}
+/** Canonical key for a set of service names (order-independent). */
+export declare function cycleKey(services: string[]): string;
+/**
+ * Find every cycle in a directed graph via Tarjan's SCC algorithm.
+ * `graph[node]` lists the nodes `node` points to.
+ */
+export declare function findRuntimeCycles(graph: Record<string, string[]>): RuntimeCycle[];