@webpieces/nx-webpieces-rules 0.4.846 → 0.4.848

package/README.md

@@ -27,32 +27,45 @@ It is wired into the build: the `@nx/js:tsc` target default lists it in
 
 ### Configuration
 
-On/off and a time-boxed grace window come from `webpieces.config.json` at the
-workspace root — the same source of truth as every other webpieces rule — under
-the rule key `no-file-import-cycles`:
+`webpieces.config.json` declares each owning pack and its config path in the root
+`rulePacks` array. For example, the Nx entry is:
 
-```jsonc
+```json
 {
-  "rules": {
-    "no-file-import-cycles": {
-      "mode": "ON",                            // "OFF" disables the gate everywhere
-      "turnOffRuleUntilEpoch": 1771931925,  // epoch SECONDS — while now < epoch,
-                                               //   cycles are REPORTED but the build
-                                               //   PASSES; after it, the gate fails again
-      "ignoreTypeOnly": false                  // when true, ignore `import type`
-                                               //   re-export cycles (erased at compile
-                                               //   time, harmless at runtime)
-    }
+  "package": "@webpieces/nx-webpieces-rules",
+  "config": ".webpieces/rules/nx.json"
+}
+```
+
+Keep the other selected owners and required root settings. Policy settings come
+from the declared owner file's direct policy-ID map. This entry belongs directly
+in `.webpieces/rules/nx.json` (an excerpt; the other owned policies also require
+explicit settings):
+
+```json
+{
+  "no-file-import-cycles": {
+    "mode": "RUN_EVERY_TIME",
+    "turnOffRuleUntilEpoch": 0,
+    "turnOffRuleWhileOnBranch": null,
+    "ignoreTypeOnly": false
   }
 }
 ```
 
+Use complete `OFF` settings for an intentional opt-out. `ignoreTypeOnly: true`
+ignores type-only import/re-export cycles. A future `turnOffRuleUntilEpoch` value
+uses epoch seconds; `0` and a `null` branch hatch keep enforcement active.
+After reviewing the declarations, `pnpm wp-rules-sync` explicitly seeds missing
+owner settings and refreshes the lock/catalog artifacts. Review and commit its
+changes; normal loading never supplies missing required settings.
+
 Semantics, mirroring the method/file-size dated-disable model:
 
 | Situation                                   | Result                          |
 | ------------------------------------------- | ------------------------------- |
 | `mode: "OFF"`                               | Skipped (passes), no madge run  |
-| Cycle found, no `turnOffRuleUntilEpoch`  | **Fails**                       |
+| Cycle found, `turnOffRuleUntilEpoch: 0`  | **Fails**                       |
 | Cycle found, `now < turnOffRuleUntilEpoch` | Reported but **passes** (warn) |
 | Cycle found, `now >= turnOffRuleUntilEpoch` | **Fails** again               |
 | No cycle                                    | Passes                          |
@@ -66,3 +79,29 @@ forgotten because the gate starts failing again after the date.
 Setting `circularDeps.enabled: false` in the plugin options removes the target
 entirely (rather than toggling it via config). Prefer `mode: "OFF"` instead — it
 keeps the target present so any `dependsOn` references don't dangle.
+
+## View saved architecture and refresh explicitly
+
+`pnpm arch:visualize` and `pnpm arch:visualize-runtime` open saved generated
+snapshots. They render presentation files and open the browser without regenerating
+architecture, API contract, or runtime graph facts. Source edits do not update the
+snapshot. Freshness is unknown because these artifacts do not record reliable
+generation provenance; checkout/file modification times are not generation times.
+
+Refresh explicitly, then view:
+
+```sh
+pnpm arch:generate
+pnpm arch:visualize
+pnpm arch:visualize-runtime
+```
+
+In consuming workspaces without these npm shortcuts, use
+`pnpm nx run architecture:generate`, `pnpm nx run architecture:visualize`, and
+`pnpm nx run architecture:visualize-runtime`. The compile graph's configured
+`graphPath` (or `--graphPath=...`) is still supported. Missing or unusable saved
+artifacts fail with the artifact path and refresh command; viewing never generates
+as a fallback. A failed generation remains a failure, and viewing any saved files
+afterward does not establish that refresh succeeded. Browser-open failures print
+the HTML path for manual opening. Architecture/API validation and CI still run
+their existing checks independently of visualization.

package/executors.json

@@ -8,12 +8,12 @@
         "visualize": {
             "implementation": "./src/executors/visualize/executor",
             "schema": "./src/executors/visualize/schema.json",
-            "description": "Generate visual representations of the architecture graph"
+            "description": "View saved architecture without refreshing; refresh: pnpm nx run architecture:generate"
         },
         "visualize-runtime": {
             "implementation": "./src/executors/visualize-runtime/executor",
             "schema": "./src/executors/visualize-runtime/schema.json",
-            "description": "Render the runtime microservice graph (runtime-dependencies.json)"
+            "description": "View saved runtime architecture without refreshing; refresh: pnpm nx run architecture:generate"
         },
         "validate-runtime-architecture": {
             "implementation": "./src/executors/validate-runtime-architecture/executor",
@@ -65,75 +65,10 @@
             "schema": "./src/executors/validate-rules-config/schema.json",
             "description": "Validate webpieces.config.json once at the scoped rules:check boundary"
         },
-        "validate-no-any-unknown": {
-            "implementation": "./src/executors/validate-no-any-unknown/executor",
-            "schema": "./src/executors/validate-no-any-unknown/schema.json",
-            "description": "Validate no any/unknown keywords are used - use specific types instead"
-        },
-        "validate-new-methods": {
-            "implementation": "./src/executors/validate-new-methods/executor",
-            "schema": "./src/executors/validate-new-methods/schema.json",
-            "description": "Validate newly added methods don't exceed maximum line count"
-        },
-        "validate-modified-methods": {
-            "implementation": "./src/executors/validate-modified-methods/executor",
-            "schema": "./src/executors/validate-modified-methods/schema.json",
-            "description": "Validate modified methods don't exceed maximum line count"
-        },
-        "validate-modified-files": {
-            "implementation": "./src/executors/validate-modified-files/executor",
-            "schema": "./src/executors/validate-modified-files/schema.json",
-            "description": "Validate modified files don't exceed maximum line count"
-        },
-        "validate-return-types": {
-            "implementation": "./src/executors/validate-return-types/executor",
-            "schema": "./src/executors/validate-return-types/schema.json",
-            "description": "Validate methods have explicit return type annotations"
-        },
-        "validate-no-inline-types": {
-            "implementation": "./src/executors/validate-no-inline-types/executor",
-            "schema": "./src/executors/validate-no-inline-types/schema.json",
-            "description": "Validate no inline type literals are used - prefer named types"
-        },
-        "validate-no-implicit-any": {
-            "implementation": "./src/executors/validate-no-implicit-any/executor",
-            "schema": "./src/executors/validate-no-implicit-any/schema.json",
-            "description": "Validate no implicit-any inferences on parameters, variables, or properties"
-        },
-        "validate-catch-error-pattern": {
-            "implementation": "./src/executors/validate-catch-error-pattern/executor",
-            "schema": "./src/executors/validate-catch-error-pattern/schema.json",
-            "description": "Validate catch blocks follow standardized pattern: catch (err: unknown) { const error = toError(err); }"
-        },
-        "validate-no-unmanaged-exceptions": {
-            "implementation": "./src/executors/validate-no-unmanaged-exceptions/executor",
-            "schema": "./src/executors/validate-no-unmanaged-exceptions/schema.json",
-            "description": "Validate try/catch blocks are not used outside chokepoints"
-        },
-        "validate-no-destructure": {
-            "implementation": "./src/executors/validate-no-destructure/executor",
-            "schema": "./src/executors/validate-no-destructure/schema.json",
-            "description": "Validate no destructuring patterns are used - use explicit property access instead"
-        },
-        "validate-no-direct-api-resolver": {
-            "implementation": "./src/executors/validate-no-direct-api-resolver/executor",
-            "schema": "./src/executors/validate-no-direct-api-resolver/schema.json",
-            "description": "Validate resolvers use services (not APIs) and components subscribe to observables (not route.snapshot.data)"
-        },
-        "validate-dtos": {
-            "implementation": "./src/executors/validate-dtos/executor",
-            "schema": "./src/executors/validate-dtos/schema.json",
-            "description": "Validate DTO fields match Prisma Dbo model fields"
-        },
-        "validate-prisma-converters": {
-            "implementation": "./src/executors/validate-prisma-converters/executor",
-            "schema": "./src/executors/validate-prisma-converters/schema.json",
-            "description": "Validate Prisma converter method patterns and Dto creation locations"
-        },
         "validate-code": {
             "implementation": "./src/executors/validate-code/executor",
             "schema": "./src/executors/validate-code/schema.json",
-            "description": "Combined validation for new methods, modified methods, and file sizes"
+            "description": "Execute declared build contributions through their public owner runtimes, with optional single-rule debug execution"
         },
         "help": {
             "implementation": "./src/executors/help/executor",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.4.846",
+  "version": "0.4.848",
   "description": "Nx-specific webpieces validation rules, graph tooling, executors, and inference plugin.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -10,7 +10,8 @@
     "./package.json": "./package.json",
     "./plugin": "./src/plugin.js",
     "./executors.json": "./executors.json",
-    "./rule-pack": "./src/rule-pack.js"
+    "./rule-pack": "./src/rule-pack.js",
+    "./rule-runtime": "./src/rule-runtime.js"
   },
   "files": [
     "src/**/*",
@@ -19,13 +20,12 @@
     "README.md"
   ],
   "dependencies": {
-    "@webpieces/api-doc-model": "0.4.846",
-    "@webpieces/code-rules": "0.4.846",
-    "@webpieces/core-util": "0.4.846",
-    "@webpieces/eslint-rules": "0.4.846",
-    "@webpieces/rules-config": "0.4.846",
+    "@webpieces/api-doc-model": "0.4.848",
+    "@webpieces/core-util": "0.4.848",
+    "@webpieces/eslint-rules": "0.4.848",
+    "@webpieces/rules-config": "0.4.848",
     "madge": "8.0.0",
-    "@webpieces/rules-sdk": "0.4.846"
+    "@webpieces/rules-sdk": "0.4.848"
   },
   "peerDependencies": {
     "@nx/devkit": ">=18.0.0"
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@webpieces/tooling-testkit": "0.4.846"
+    "@webpieces/tooling-testkit": "0.4.848"
   },
   "types": "./src/index.d.ts",
   "bin": {

package/src/executors/help/executor.js

@@ -12,8 +12,9 @@ async function helpExecutor(options, context) {
     console.log(`${BOLD}📝 Available npm scripts (convenient shortcuts):${RESET}`);
     console.log('');
     console.log('  Architecture graph:');
-    console.log('    npm run arch:generate                  # Generate dependency graph');
-    console.log('    npm run arch:visualize                 # Visualize dependency graph');
+    console.log('    npm run arch:generate                  # Explicitly refresh architecture/API/runtime facts');
+    console.log('    npm run arch:visualize                 # View saved snapshot (does not refresh)');
+    console.log('    npm run arch:visualize-runtime         # View saved runtime snapshot (does not refresh)');
     console.log('');
     console.log('  Validation:');
     console.log('    npm run arch:validate                  # Quick validation (no-cycles)');
@@ -25,8 +26,9 @@ async function helpExecutor(options, context) {
     console.log(`${BOLD}📝 Available Nx targets:${RESET}`);
     console.log('');
     console.log('  Workspace-level architecture validation:');
-    console.log('    nx run architecture:generate                         # Generate dependency graph');
-    console.log('    nx run architecture:visualize                        # Visualize dependency graph');
+    console.log('    nx run architecture:generate                         # Explicitly refresh architecture/API/runtime facts');
+    console.log('    nx run architecture:visualize                        # View saved snapshot (does not refresh)');
+    console.log('    nx run architecture:visualize-runtime                # View saved runtime snapshot (does not refresh)');
     console.log('    nx run architecture:validate-no-architecture-cycles  # Check for circular project dependencies');
     console.log('    nx run architecture:validate-architecture-unchanged  # Validate against blessed graph');
     console.log('');

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

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/help/executor.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ExecutorContext } from '@nx/devkit';\n\nexport interface HelpExecutorOptions {}\n\ntype HelpExecutorResult = { success: true };\n\nexport default async function helpExecutor(\n    options: HelpExecutorOptions,\n    context: ExecutorContext\n): Promise<HelpExecutorResult> {\n    // ANSI color codes\n    const GREEN = '\\x1b[32m\\x1b[1m';\n    const BOLD = '\\x1b[1m';\n    const RESET = '\\x1b[0m';\n\n    console.log('');\n    console.log(`${GREEN}💡 @webpieces/nx-webpieces-rules - Available Commands${RESET}`);\n    console.log('');\n    console.log(`${BOLD}📝 Available npm scripts (convenient shortcuts):${RESET}`);\n    console.log('');\n    console.log('  Architecture graph:');\n    console.log('    npm run arch:generate                  # Generate dependency graph');\n    console.log('    npm run arch:visualize                 # Visualize dependency graph');\n    console.log('');\n    console.log('  Validation:');\n    console.log('    npm run arch:validate                  # Quick validation (no-cycles)');\n    console.log('    npm run arch:validate-all              # Full arch validation (+ unchanged check)');\n    console.log('    npm run arch:check-circular            # Check all projects for circular deps');\n    console.log('    npm run arch:check-circular-affected   # Check affected projects only');\n    console.log('    npm run arch:validate-complete         # Complete validation (arch + circular)');\n    console.log('');\n    console.log(`${BOLD}📝 Available Nx targets:${RESET}`);\n    console.log('');\n    console.log('  Workspace-level architecture validation:');\n    console.log('    nx run architecture:generate                         # Generate dependency graph');\n    console.log('    nx run architecture:visualize                        # Visualize dependency graph');\n    console.log('    nx run architecture:validate-no-architecture-cycles  # Check for circular project dependencies');\n    console.log('    nx run architecture:validate-architecture-unchanged  # Validate against blessed graph');\n    console.log('');\n    console.log('  Per-project file import cycle checking:');\n    console.log('    nx run <project>:validate-no-file-import-cycles           # Check project for file import cycles');\n    console.log('    nx affected --target=validate-no-file-import-cycles       # Check all affected projects');\n    console.log('    nx run-many --target=validate-no-file-import-cycles --all # Check all projects');\n    console.log('');\n    console.log('  Per-project CI target (lint + build + test):');\n    console.log('    nx run <project>:ci                    # Run lint, build, test together');\n    console.log('    nx run-many --target=ci --all          # Run ci for all projects');\n    console.log('');\n    console.log('    Execution order (test waits for build via targetDefaults):');\n    console.log('    ci (nx:noop)');\n    console.log('    ├── lint ─────────────────┐');\n    console.log('    ├── build ────────────────┼── run in parallel');\n    console.log('    └── test ─────────────────┘');\n    console.log('        └── depends on build (waits)');\n    console.log('');\n    console.log(`${GREEN}💡 Quick start:${RESET}`);\n    console.log(`   ${BOLD}npm run arch:generate${RESET}           # Generate the graph first`);\n    console.log(`   ${BOLD}npm run arch:validate-complete${RESET}  # Run complete validation`);\n    console.log('');\n\n    return { success: true };\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/help/executor.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ExecutorContext } from '@nx/devkit';\n\nexport interface HelpExecutorOptions {}\n\ntype HelpExecutorResult = { success: true };\n\nexport default async function helpExecutor(\n    options: HelpExecutorOptions,\n    context: ExecutorContext\n): Promise<HelpExecutorResult> {\n    // ANSI color codes\n    const GREEN = '\\x1b[32m\\x1b[1m';\n    const BOLD = '\\x1b[1m';\n    const RESET = '\\x1b[0m';\n\n    console.log('');\n    console.log(`${GREEN}💡 @webpieces/nx-webpieces-rules - Available Commands${RESET}`);\n    console.log('');\n    console.log(`${BOLD}📝 Available npm scripts (convenient shortcuts):${RESET}`);\n    console.log('');\n    console.log('  Architecture graph:');\n    console.log('    npm run arch:generate                  # Explicitly refresh architecture/API/runtime facts');\n    console.log('    npm run arch:visualize                 # View saved snapshot (does not refresh)');\n    console.log('    npm run arch:visualize-runtime         # View saved runtime snapshot (does not refresh)');\n    console.log('');\n    console.log('  Validation:');\n    console.log('    npm run arch:validate                  # Quick validation (no-cycles)');\n    console.log('    npm run arch:validate-all              # Full arch validation (+ unchanged check)');\n    console.log('    npm run arch:check-circular            # Check all projects for circular deps');\n    console.log('    npm run arch:check-circular-affected   # Check affected projects only');\n    console.log('    npm run arch:validate-complete         # Complete validation (arch + circular)');\n    console.log('');\n    console.log(`${BOLD}📝 Available Nx targets:${RESET}`);\n    console.log('');\n    console.log('  Workspace-level architecture validation:');\n    console.log('    nx run architecture:generate                         # Explicitly refresh architecture/API/runtime facts');\n    console.log('    nx run architecture:visualize                        # View saved snapshot (does not refresh)');\n    console.log('    nx run architecture:visualize-runtime                # View saved runtime snapshot (does not refresh)');\n    console.log('    nx run architecture:validate-no-architecture-cycles  # Check for circular project dependencies');\n    console.log('    nx run architecture:validate-architecture-unchanged  # Validate against blessed graph');\n    console.log('');\n    console.log('  Per-project file import cycle checking:');\n    console.log('    nx run <project>:validate-no-file-import-cycles           # Check project for file import cycles');\n    console.log('    nx affected --target=validate-no-file-import-cycles       # Check all affected projects');\n    console.log('    nx run-many --target=validate-no-file-import-cycles --all # Check all projects');\n    console.log('');\n    console.log('  Per-project CI target (lint + build + test):');\n    console.log('    nx run <project>:ci                    # Run lint, build, test together');\n    console.log('    nx run-many --target=ci --all          # Run ci for all projects');\n    console.log('');\n    console.log('    Execution order (test waits for build via targetDefaults):');\n    console.log('    ci (nx:noop)');\n    console.log('    ├── lint ─────────────────┐');\n    console.log('    ├── build ────────────────┼── run in parallel');\n    console.log('    └── test ─────────────────┘');\n    console.log('        └── depends on build (waits)');\n    console.log('');\n    console.log(`${GREEN}💡 Quick start:${RESET}`);\n    console.log(`   ${BOLD}npm run arch:generate${RESET}           # Generate the graph first`);\n    console.log(`   ${BOLD}npm run arch:validate-complete${RESET}  # Run complete validation`);\n    console.log('');\n\n    return { success: true };\n}\n"]}

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

@@ -24,6 +24,14 @@ export interface ExecutorResult {
  * fixing it is the same single command either way, so listing both adds noise rather than information.
  */
 export declare function describeTableDrift(current: CurrentArchitecture, saved: DependenciesFile): string | null;
+/**
+ * Build the current dependency graph exactly as the generator does: reduce the nx
+ * graph, sort into levels, enrich with metadata, and attach the derived
+ * apiRelations — so this validator compares like-for-like against the committed file.
+ */
+export declare class CurrentGraphBuilder {
+    build(workspaceRoot: string): Promise<CurrentArchitecture>;
+}
 /** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */
 export declare class CurrentArchitecture {
     readonly graph: EnhancedGraph;

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

@@ -9,7 +9,7 @@
  * nx run architecture:validate-architecture-unchanged
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CurrentArchitecture = void 0;
+exports.CurrentArchitecture = exports.CurrentGraphBuilder = void 0;
 exports.describeTableDrift = describeTableDrift;
 exports.default = runExecutor;
 const rules_config_1 = require("@webpieces/rules-config");
@@ -112,23 +112,25 @@ function describeExternalSystemDrift(current, saved) {
  * graph, sort into levels, enrich with metadata, and attach the derived
  * apiRelations — so this validator compares like-for-like against the committed file.
  */
-// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch/writeTmpInstructionsFile in this file
-async function buildCurrentGraph(workspaceRoot) {
-    console.log('📊 Generating current dependency graph...');
-    const reducedGraph = await (0, graph_generator_1.generateReducedGraph)();
-    console.log('🔄 Computing topological layers...');
-    const currentGraph = (0, graph_sorter_1.sortGraphTopologically)(reducedGraph);
-    console.log('🏷️  Enriching graph with framework + responsibilities metadata...');
-    const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
-    (0, graph_metadata_1.enrichGraph)(currentGraph, projectInfos, workspaceRoot);
-    new tag_truth_1.TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);
-    console.log('🔎 Scanning source for implements/uses API relations...');
-    // The SAME externalApiPaths the generator uses: scanning without them would drop every vendor
-    // relation from the regenerated graph and report drift against a perfectly fresh file.
-    const externalApiPaths = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot).externalApiPaths;
-    const scan = (0, api_scanner_1.scanAndAttachApiRelations)(workspaceRoot, currentGraph, projectInfos, externalApiPaths);
-    return new CurrentArchitecture(currentGraph, new api_contract_files_1.ApiContractFiles().refsFor((0, api_scanner_1.buildApiContracts)(scan)), (0, external_systems_1.buildExternalSystems)(scan.apiIndex, projectInfos));
+class CurrentGraphBuilder {
+    async build(workspaceRoot) {
+        console.log('📊 Generating current dependency graph...');
+        const reducedGraph = await (0, graph_generator_1.generateReducedGraph)();
+        console.log('🔄 Computing topological layers...');
+        const currentGraph = (0, graph_sorter_1.sortGraphTopologically)(reducedGraph);
+        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');
+        const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
+        (0, graph_metadata_1.enrichGraph)(currentGraph, projectInfos, workspaceRoot);
+        new tag_truth_1.TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);
+        console.log('🔎 Scanning source for implements/uses API relations...');
+        // The SAME externalApiPaths the generator uses: scanning without them would drop every vendor
+        // relation from the regenerated graph and report drift against a perfectly fresh file.
+        const externalApiPaths = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot).externalApiPaths;
+        const scan = (0, api_scanner_1.scanAndAttachApiRelations)(workspaceRoot, currentGraph, projectInfos, externalApiPaths);
+        return new CurrentArchitecture(currentGraph, new api_contract_files_1.ApiContractFiles().refsFor((0, api_scanner_1.buildApiContracts)(scan)), (0, external_systems_1.buildExternalSystems)(scan.apiIndex, projectInfos));
+    }
 }
+exports.CurrentGraphBuilder = CurrentGraphBuilder;
 /** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */
 class CurrentArchitecture {
     graph;
@@ -170,7 +172,7 @@ async function runExecutor(options, context) {
         }
         // Steps 1-3: build + enrich + scan the current graph (same pipeline the
         // generator runs, so any drift is caught).
-        const currentGraph = await buildCurrentGraph(workspaceRoot);
+        const currentGraph = await new CurrentGraphBuilder().build(workspaceRoot);
         // Step 4: Load saved graph
         console.log('📂 Loading saved graph...');
         const savedGraph = (0, graph_loader_1.loadBlessedGraph)(workspaceRoot, graphPath);

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

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Architecture Unchanged Executor\n *\n * Validates that the current architecture graph matches the saved blessed graph.\n * This ensures no unapproved architecture changes have been made.\n *\n * Usage:\n * nx run architecture:validate-architecture-unchanged\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate, RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { compareGraphs } from '../../lib/graph-comparator';\nimport { loadBlessedGraph, graphFileExists } from '../../lib/graph-loader';\nimport type { DependenciesFile } from '../../lib/graph-loader';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { TagTruthCheck } from '../../lib/tag-truth';\nimport { scanAndAttachApiRelations, buildApiContracts } from '../../lib/api-usage/api-scanner';\nimport { buildExternalSystems } from '../../lib/api-usage/external-systems';\nimport type { ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport type { ApiContractFileRefs } from '../../lib/api-contract-files';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { RuleGate } from '../../lib/rule-gate';\nimport type { EnhancedGraph } from '../../lib/graph-sorter';\nimport { toError } from '../../toError';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst TMP_MD_FILE = 'webpieces.dependencies.md';\n\n/**\n * Write the instructions documentation to .webpieces/instruct-ai/.\n * Sourced from @webpieces/rules-config.\n */\nfunction writeTmpInstructionsFile(workspaceRoot: string): string {\n    const mdPath = writeTemplate(workspaceRoot, TMP_MD_FILE);\n\n    return mdPath;\n}\n\n/**\n * Report a current-vs-saved graph mismatch and write the AI instructions file.\n */\nfunction reportMismatch(summary: string, workspaceRoot: string): void {\n    const mdPath = writeTmpInstructionsFile(workspaceRoot);\n\n    console.error('❌ Architecture has changed since last update!');\n    console.error('\\nDifferences:');\n    console.error(summary);\n    console.error('');\n    console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');\n    console.error('');\n    console.error('To fix:');\n    console.error('  1. Review the changes above');\n    console.error('  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change');\n    console.error('  3. Commit the updated architecture/dependencies.json');\n}\n\n/**\n * Which APIs dependencies.json links to a contract file, compared by LINK only — an added or removed\n * API. The endpoints inside `architecture/apis/<Api>.json` are deliberately NOT compared (#949): an\n * endpoint change must not fail this rule. Null when the links match.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction describeContractLinkDrift(current: ApiContractFileRefs, saved: ApiContractFileRefs): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined) changes.push(`  - ${name}: linked in dependencies.json but no longer in source`);\n        else if (b === undefined) changes.push(`  + ${name}: in source but not linked from dependencies.json`);\n        else if (a !== b) changes.push(`  ~ ${name}: contract file link changed (${b} -> ${a})`);\n    }\n    if (changes.length === 0) return null;\n    return `apiContractFiles drift (${changes.length} api(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Drift in EITHER side table of dependencies.json — the api contract-file links or the\n * external-system declarations — or null when both match. The first difference found is reported;\n * fixing it is the same single command either way, so listing both adds noise rather than information.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractLinkDrift above\nexport function describeTableDrift(current: CurrentArchitecture, saved: DependenciesFile): string | null {\n    const linkDrift = describeContractLinkDrift(current.apiContractFiles, saved.apiContractFiles);\n    if (linkDrift !== null) return linkDrift;\n    return describeExternalSystemDrift(current.externalSystems, saved.externalSystems);\n}\n\n/**\n * The same drift report for the declared external systems, or null when they match. Named per\n * system so the message points at the database that changed rather than dumping two JSON blobs.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractLinkDrift above\nfunction describeExternalSystemDrift(current: ExternalSystemDecls, saved: ExternalSystemDecls): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined) changes.push(`  - ${name}: in dependencies.json but no longer declared in source`);\n        else if (b === undefined) changes.push(`  + ${name}: declared in source but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b)) changes.push(`  ~ ${name}: kind/label/declarers changed`);\n    }\n    if (changes.length === 0) return null;\n    return `externalSystems drift (${changes.length} system(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Build the current dependency graph exactly as the generator does: reduce the nx\n * graph, sort into levels, enrich with metadata, and attach the derived\n * apiRelations — so this validator compares like-for-like against the committed file.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch/writeTmpInstructionsFile in this file\nasync function buildCurrentGraph(workspaceRoot: string): Promise<CurrentArchitecture> {\n    console.log('📊 Generating current dependency graph...');\n    const reducedGraph = await generateReducedGraph();\n    console.log('🔄 Computing topological layers...');\n    const currentGraph = sortGraphTopologically(reducedGraph);\n    console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n    const projectInfos = await collectProjectInfo();\n    enrichGraph(currentGraph, projectInfos, workspaceRoot);\n    new TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);\n    console.log('🔎 Scanning source for implements/uses API relations...');\n    // The SAME externalApiPaths the generator uses: scanning without them would drop every vendor\n    // relation from the regenerated graph and report drift against a perfectly fresh file.\n    const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n    const scan = scanAndAttachApiRelations(workspaceRoot, currentGraph, projectInfos, externalApiPaths);\n    return new CurrentArchitecture(\n        currentGraph,\n        new ApiContractFiles().refsFor(buildApiContracts(scan)),\n        buildExternalSystems(scan.apiIndex, projectInfos),\n    );\n}\n\n/** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */\nexport class CurrentArchitecture {\n    constructor(\n        public readonly graph: EnhancedGraph,\n        public readonly apiContractFiles: ApiContractFileRefs,\n        public readonly externalSystems: ExternalSystemDecls,\n    ) {}\n}\n\n/** The bootstrap path: there is nothing to diff against yet, so say how to create it. */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction reportMissingGraph(): void {\n    console.error('❌ No saved graph found at architecture/dependencies.json');\n    console.error('');\n    console.error('To initialize:');\n    console.error('  1. Run: nx run architecture:generate');\n    console.error('  2. Run: nx run architecture:visualize');\n    console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');\n    console.error('  4. Commit architecture/dependencies.json');\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    // Epoch-gateable: this rule diffs against the blessed architecture/dependencies.json, so\n    // \"grandfather the current drift until <epoch>\" is meaningful — hence honorEpoch = true.\n    if (new RuleGate().isDisabled(workspaceRoot, 'validate-architecture-unchanged', true)) {\n        return { success: true };\n    }\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Check if saved graph exists\n        if (!graphFileExists(workspaceRoot, graphPath)) {\n            reportMissingGraph();\n            return { success: false };\n        }\n\n        // Steps 1-3: build + enrich + scan the current graph (same pipeline the\n        // generator runs, so any drift is caught).\n        const currentGraph = await buildCurrentGraph(workspaceRoot);\n\n        // Step 4: Load saved graph\n        console.log('📂 Loading saved graph...');\n        const savedGraph = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!savedGraph) {\n            console.error('❌ Could not load saved graph');\n            return { success: false };\n        }\n\n        // Step 5: Compare graphs\n        console.log('🔍 Comparing current graph to saved graph...');\n        const comparison = compareGraphs(currentGraph.graph, savedGraph.projects);\n\n        if (!comparison.identical) {\n            reportMismatch(comparison.summary, workspaceRoot);\n            return { success: false };\n        }\n\n        // Step 6: Compare the two side tables as well: which APIs are linked to a contract file, and\n        // the external-system declarations. The endpoints inside architecture/apis/<Api>.json are\n        // NOT compared — an endpoint change must never fail this rule (#949).\n        const tableDrift = describeTableDrift(currentGraph, savedGraph);\n        if (tableDrift !== null) {\n            reportMismatch(tableDrift, workspaceRoot);\n            return { success: false };\n        }\n\n        console.log('✅ Architecture unchanged - current graph matches saved graph');\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        // A RuleFailError (e.g. a dependencies.json still carrying the moved `apiContracts` key)\n        // carries its cures in Option[]; render them rather than dropping them with `.message`.\n        const rendered = error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Architecture validation failed:', rendered);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Architecture Unchanged Executor\n *\n * Validates that the current architecture graph matches the saved blessed graph.\n * This ensures no unapproved architecture changes have been made.\n *\n * Usage:\n * nx run architecture:validate-architecture-unchanged\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate, RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { compareGraphs } from '../../lib/graph-comparator';\nimport { loadBlessedGraph, graphFileExists } from '../../lib/graph-loader';\nimport type { DependenciesFile } from '../../lib/graph-loader';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { TagTruthCheck } from '../../lib/tag-truth';\nimport { scanAndAttachApiRelations, buildApiContracts } from '../../lib/api-usage/api-scanner';\nimport { buildExternalSystems } from '../../lib/api-usage/external-systems';\nimport type { ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport type { ApiContractFileRefs } from '../../lib/api-contract-files';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { RuleGate } from '../../lib/rule-gate';\nimport type { EnhancedGraph } from '../../lib/graph-sorter';\nimport { toError } from '../../toError';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst TMP_MD_FILE = 'webpieces.dependencies.md';\n\n/**\n * Write the instructions documentation to .webpieces/instruct-ai/.\n * Sourced from @webpieces/rules-config.\n */\nfunction writeTmpInstructionsFile(workspaceRoot: string): string {\n    const mdPath = writeTemplate(workspaceRoot, TMP_MD_FILE);\n\n    return mdPath;\n}\n\n/**\n * Report a current-vs-saved graph mismatch and write the AI instructions file.\n */\nfunction reportMismatch(summary: string, workspaceRoot: string): void {\n    const mdPath = writeTmpInstructionsFile(workspaceRoot);\n\n    console.error('❌ Architecture has changed since last update!');\n    console.error('\\nDifferences:');\n    console.error(summary);\n    console.error('');\n    console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');\n    console.error('');\n    console.error('To fix:');\n    console.error('  1. Review the changes above');\n    console.error('  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change');\n    console.error('  3. Commit the updated architecture/dependencies.json');\n}\n\n/**\n * Which APIs dependencies.json links to a contract file, compared by LINK only — an added or removed\n * API. The endpoints inside `architecture/apis/<Api>.json` are deliberately NOT compared (#949): an\n * endpoint change must not fail this rule. Null when the links match.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction describeContractLinkDrift(\n    current: ApiContractFileRefs,\n    saved: ApiContractFileRefs,\n): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined)\n            changes.push(`  - ${name}: linked in dependencies.json but no longer in source`);\n        else if (b === undefined)\n            changes.push(`  + ${name}: in source but not linked from dependencies.json`);\n        else if (a !== b) changes.push(`  ~ ${name}: contract file link changed (${b} -> ${a})`);\n    }\n    if (changes.length === 0) return null;\n    return `apiContractFiles drift (${changes.length} api(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Drift in EITHER side table of dependencies.json — the api contract-file links or the\n * external-system declarations — or null when both match. The first difference found is reported;\n * fixing it is the same single command either way, so listing both adds noise rather than information.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractLinkDrift above\nexport function describeTableDrift(current: CurrentArchitecture, saved: DependenciesFile): string | null {\n    const linkDrift = describeContractLinkDrift(current.apiContractFiles, saved.apiContractFiles);\n    if (linkDrift !== null) return linkDrift;\n    return describeExternalSystemDrift(current.externalSystems, saved.externalSystems);\n}\n\n/**\n * The same drift report for the declared external systems, or null when they match. Named per\n * system so the message points at the database that changed rather than dumping two JSON blobs.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractLinkDrift above\nfunction describeExternalSystemDrift(\n    current: ExternalSystemDecls,\n    saved: ExternalSystemDecls,\n): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined)\n            changes.push(`  - ${name}: in dependencies.json but no longer declared in source`);\n        else if (b === undefined)\n            changes.push(`  + ${name}: declared in source but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b))\n            changes.push(`  ~ ${name}: kind/label/declarers changed`);\n    }\n    if (changes.length === 0) return null;\n    return `externalSystems drift (${changes.length} system(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Build the current dependency graph exactly as the generator does: reduce the nx\n * graph, sort into levels, enrich with metadata, and attach the derived\n * apiRelations — so this validator compares like-for-like against the committed file.\n */\nexport class CurrentGraphBuilder {\n    async build(workspaceRoot: string): Promise<CurrentArchitecture> {\n        console.log('📊 Generating current dependency graph...');\n        const reducedGraph = await generateReducedGraph();\n        console.log('🔄 Computing topological layers...');\n        const currentGraph = sortGraphTopologically(reducedGraph);\n        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n        const projectInfos = await collectProjectInfo();\n        enrichGraph(currentGraph, projectInfos, workspaceRoot);\n        new TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);\n        console.log('🔎 Scanning source for implements/uses API relations...');\n        // The SAME externalApiPaths the generator uses: scanning without them would drop every vendor\n        // relation from the regenerated graph and report drift against a perfectly fresh file.\n        const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n        const scan = scanAndAttachApiRelations(workspaceRoot, currentGraph, projectInfos, externalApiPaths);\n        return new CurrentArchitecture(\n            currentGraph,\n            new ApiContractFiles().refsFor(buildApiContracts(scan)),\n            buildExternalSystems(scan.apiIndex, projectInfos),\n        );\n    }\n}\n\n/** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */\nexport class CurrentArchitecture {\n    constructor(\n        public readonly graph: EnhancedGraph,\n        public readonly apiContractFiles: ApiContractFileRefs,\n        public readonly externalSystems: ExternalSystemDecls,\n    ) {}\n}\n\n/** The bootstrap path: there is nothing to diff against yet, so say how to create it. */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction reportMissingGraph(): void {\n    console.error('❌ No saved graph found at architecture/dependencies.json');\n    console.error('');\n    console.error('To initialize:');\n    console.error('  1. Run: nx run architecture:generate');\n    console.error('  2. Run: nx run architecture:visualize');\n    console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');\n    console.error('  4. Commit architecture/dependencies.json');\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    // Epoch-gateable: this rule diffs against the blessed architecture/dependencies.json, so\n    // \"grandfather the current drift until <epoch>\" is meaningful — hence honorEpoch = true.\n    if (new RuleGate().isDisabled(workspaceRoot, 'validate-architecture-unchanged', true)) {\n        return { success: true };\n    }\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Check if saved graph exists\n        if (!graphFileExists(workspaceRoot, graphPath)) {\n            reportMissingGraph();\n            return { success: false };\n        }\n\n        // Steps 1-3: build + enrich + scan the current graph (same pipeline the\n        // generator runs, so any drift is caught).\n        const currentGraph = await new CurrentGraphBuilder().build(workspaceRoot);\n\n        // Step 4: Load saved graph\n        console.log('📂 Loading saved graph...');\n        const savedGraph = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!savedGraph) {\n            console.error('❌ Could not load saved graph');\n            return { success: false };\n        }\n\n        // Step 5: Compare graphs\n        console.log('🔍 Comparing current graph to saved graph...');\n        const comparison = compareGraphs(currentGraph.graph, savedGraph.projects);\n\n        if (!comparison.identical) {\n            reportMismatch(comparison.summary, workspaceRoot);\n            return { success: false };\n        }\n\n        // Step 6: Compare the two side tables as well: which APIs are linked to a contract file, and\n        // the external-system declarations. The endpoints inside architecture/apis/<Api>.json are\n        // NOT compared — an endpoint change must never fail this rule (#949).\n        const tableDrift = describeTableDrift(currentGraph, savedGraph);\n        if (tableDrift !== null) {\n            reportMismatch(tableDrift, workspaceRoot);\n            return { success: false };\n        }\n\n        console.log('✅ Architecture unchanged - current graph matches saved graph');\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        // A RuleFailError (e.g. a dependencies.json still carrying the moved `apiContracts` key)\n        // carries its cures in Option[]; render them rather than dropping them with `.message`.\n        const rendered = error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Architecture validation failed:', rendered);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}

package/src/executors/validate-code/executor.d.ts

@@ -1,12 +1,7 @@
 import type { ExecutorContext } from '@nx/devkit';
 import { ExecutorResult } from '../../executor-result';
-/**
- * The three DEBUG options (#1027). Every rule's mode and settings come from webpieces.config.json, never
- * from here; these only turn ONE run into a debug run of one rule:
- *   nx run architecture:validate-code --rule=<name> [--mode=RUN_EVERY_TIME] [--projects=a,b]
- * All absent → the gate, at every committed mode.
- */
-export interface ValidateCodeOptions {
+/** Runtime policy options come only from validated owner files. These flags request one ephemeral debug run. */
+export declare class ValidateCodeOptions {
     rule?: string;
     mode?: string;
     projects?: string | string[];

package/src/executors/validate-code/executor.js

@@ -1,8 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidateCodeOptions = void 0;
 exports.default = runExecutor;
-const code_rules_1 = require("@webpieces/code-rules");
+const rules_sdk_1 = require("@webpieces/rules-sdk");
+const rules_config_1 = require("@webpieces/rules-config");
+const rules_config_2 = require("@webpieces/rules-config");
+const pack_build_runner_1 = require("../../pack-build-runner");
+/** Runtime policy options come only from validated owner files. These flags request one ephemeral debug run. */
+class ValidateCodeOptions {
+    rule;
+    mode;
+    projects;
+}
+exports.ValidateCodeOptions = ValidateCodeOptions;
+// webpieces-disable no-function-outside-class -- Nx's required public executor entry point
 async function runExecutor(options, context) {
-    return (0, code_rules_1.validateCode)(context.root, new code_rules_1.RunRequestParser().parse(options.rule, options.mode, options.projects));
+    const loaded = (0, rules_config_1.loadAndValidate)(context.root);
+    if (loaded.configPath === null)
+        throw new rules_config_2.RuleFailError('policy-configuration', 'Missing webpieces.config.json. Configure explicit rulePacks before running build policies.');
+    if (options.rule === undefined &&
+        options.mode === undefined &&
+        options.projects === undefined) {
+        return new pack_build_runner_1.PackBuildRunner().run(context.root, loaded);
+    }
+    if (options.rule === undefined)
+        throw new rules_config_2.RuleFailError('policy-configuration', '--mode and --projects require --rule=<name>: a debug run judges exactly one rule.');
+    const modules = new rules_config_1.RuleRuntimeModules();
+    const group = modules
+        .groups(loaded.ruleRegistry, 'build')
+        .find((entry) => entry.ruleIds.includes(options.rule));
+    if (!group)
+        throw new rules_config_2.RuleFailError('policy-configuration', `No declared build contribution for ${options.rule}. Use a rule from the generated policy catalog.`);
+    const exports = modules.load(group, loaded.ruleRegistry.manifestModules, new rules_config_1.NodeRuleRuntimeModuleLoader(context.root));
+    return modules.runBuildDebug(exports, new rules_sdk_1.BuildDebugRequest(context.root, new rules_sdk_1.PolicyDebugSelection(options.rule, options.mode, options.projects)));
 }
 //# sourceMappingURL=executor.js.map

package/src/executors/validate-code/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-code/executor.ts"],"names":[],"mappings":";;AAgBA,8BAKC;AAnBD,sDAAuE;AAcxD,KAAK,UAAU,WAAW,CACrC,OAA4B,EAC5B,OAAwB;IAExB,OAAO,IAAA,yBAAY,EAAC,OAAO,CAAC,IAAI,EAAE,IAAI,6BAAgB,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;AAClH,CAAC","sourcesContent":["import type { ExecutorContext } from '@nx/devkit';\nimport { ExecutorResult } from '../../executor-result';\nimport { validateCode, RunRequestParser } from '@webpieces/code-rules';\n\n/**\n * The three DEBUG options (#1027). Every rule's mode and settings come from webpieces.config.json, never\n * from here; these only turn ONE run into a debug run of one rule:\n *   nx run architecture:validate-code --rule=<name> [--mode=RUN_EVERY_TIME] [--projects=a,b]\n * All absent → the gate, at every committed mode.\n */\nexport interface ValidateCodeOptions {\n    rule?: string;\n    mode?: string;\n    projects?: string | string[];\n}\n\nexport default async function runExecutor(\n    options: ValidateCodeOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    return validateCode(context.root, new RunRequestParser().parse(options.rule, options.mode, options.projects));\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-code/executor.ts"],"names":[],"mappings":";;;AAoBA,8BA2CC;AA9DD,oDAA+E;AAC/E,0DAKiC;AACjC,0DAAwD;AACxD,+DAA0D;AAG1D,gHAAgH;AAChH,MAAa,mBAAmB;IAC5B,IAAI,CAAU;IACd,IAAI,CAAU;IACd,QAAQ,CAAqB;CAChC;AAJD,kDAIC;AAED,2FAA2F;AAC5E,KAAK,UAAU,WAAW,CACrC,OAA4B,EAC5B,OAAwB;IAExB,MAAM,MAAM,GAAG,IAAA,8BAAe,EAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,MAAM,CAAC,UAAU,KAAK,IAAI;QAC1B,MAAM,IAAI,4BAAa,CACnB,sBAAsB,EACtB,4FAA4F,CAC/F,CAAC;IACN,IACI,OAAO,CAAC,IAAI,KAAK,SAAS;QAC1B,OAAO,CAAC,IAAI,KAAK,SAAS;QAC1B,OAAO,CAAC,QAAQ,KAAK,SAAS,EAChC,CAAC;QACC,OAAO,IAAI,mCAAe,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;QAC1B,MAAM,IAAI,4BAAa,CACnB,sBAAsB,EACtB,mFAAmF,CACtF,CAAC;IACN,MAAM,OAAO,GAAG,IAAI,iCAAkB,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,OAAO;SAChB,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC;SACpC,IAAI,CAAC,CAAC,KAA+B,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAK,CAAC,CAAC,CAAC;IACtF,IAAI,CAAC,KAAK;QACN,MAAM,IAAI,4BAAa,CACnB,sBAAsB,EACtB,sCAAsC,OAAO,CAAC,IAAI,iDAAiD,CACtG,CAAC;IACN,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CACxB,KAAK,EACL,MAAM,CAAC,YAAY,CAAC,eAAe,EACnC,IAAI,0CAA2B,CAAC,OAAO,CAAC,IAAI,CAAC,CAChD,CAAC;IACF,OAAO,OAAO,CAAC,aAAa,CACxB,OAAO,EACP,IAAI,6BAAiB,CACjB,OAAO,CAAC,IAAI,EACZ,IAAI,gCAAoB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CACzE,CACJ,CAAC;AACN,CAAC","sourcesContent":["import type { ExecutorContext } from '@nx/devkit';\nimport { BuildDebugRequest, PolicyDebugSelection } from '@webpieces/rules-sdk';\nimport {\n    loadAndValidate,\n    NodeRuleRuntimeModuleLoader,\n    RuleRuntimeModules,\n    RuntimeContributionGroup,\n} from '@webpieces/rules-config';\nimport { RuleFailError } from '@webpieces/rules-config';\nimport { PackBuildRunner } from '../../pack-build-runner';\nimport { ExecutorResult } from '../../executor-result';\n\n/** Runtime policy options come only from validated owner files. These flags request one ephemeral debug run. */\nexport class ValidateCodeOptions {\n    rule?: string;\n    mode?: string;\n    projects?: string | string[];\n}\n\n// webpieces-disable no-function-outside-class -- Nx's required public executor entry point\nexport default async function runExecutor(\n    options: ValidateCodeOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const loaded = loadAndValidate(context.root);\n    if (loaded.configPath === null)\n        throw new RuleFailError(\n            'policy-configuration',\n            'Missing webpieces.config.json. Configure explicit rulePacks before running build policies.',\n        );\n    if (\n        options.rule === undefined &&\n        options.mode === undefined &&\n        options.projects === undefined\n    ) {\n        return new PackBuildRunner().run(context.root, loaded);\n    }\n    if (options.rule === undefined)\n        throw new RuleFailError(\n            'policy-configuration',\n            '--mode and --projects require --rule=<name>: a debug run judges exactly one rule.',\n        );\n    const modules = new RuleRuntimeModules();\n    const group = modules\n        .groups(loaded.ruleRegistry, 'build')\n        .find((entry: RuntimeContributionGroup) => entry.ruleIds.includes(options.rule!));\n    if (!group)\n        throw new RuleFailError(\n            'policy-configuration',\n            `No declared build contribution for ${options.rule}. Use a rule from the generated policy catalog.`,\n        );\n    const exports = modules.load(\n        group,\n        loaded.ruleRegistry.manifestModules,\n        new NodeRuleRuntimeModuleLoader(context.root),\n    );\n    return modules.runBuildDebug(\n        exports,\n        new BuildDebugRequest(\n            context.root,\n            new PolicyDebugSelection(options.rule, options.mode, options.projects),\n        ),\n    );\n}\n"]}