@webpieces/nx-webpieces-rules 0.3.140 → 0.3.142

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.3.140",
+  "version": "0.3.142",
   "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.140",
-    "@webpieces/code-rules": "0.3.140",
-    "@webpieces/eslint-rules": "0.3.140",
-    "@webpieces/rules-config": "0.3.140",
+    "@webpieces/ai-hook-rules": "0.3.142",
+    "@webpieces/code-rules": "0.3.142",
+    "@webpieces/eslint-rules": "0.3.142",
+    "@webpieces/rules-config": "0.3.142",
     "madge": "8.0.0"
   },
   "peerDependencies": {

package/src/executors/validate-no-file-import-cycles/executor.d.ts

@@ -16,8 +16,11 @@
  *       "ignoreModifiedUntilEpoch": 1771931925,  // epoch SECONDS; while now < epoch,
  *                                            //   cycles are reported but the gate PASSES
  *                                            //   (warn, don't fail). After it, fails again.
- *       "ignoreTypeOnly": true              // ignore `import type` re-export cycles
+ *       "ignoreTypeOnly": true,             // ignore `import type` re-export cycles
  *                                            //   (erased at compile time, harmless at runtime)
+ *       "excludePackages": ["@kami/entities"] // npm package names whose source trees madge
+ *                                            //   should NOT traverse (stops foreign cycles
+ *                                            //   from leaking into this project's report)
  *   }
  *
  * Mirrors the dated-disable model already used for the method/file-size rules:

package/src/executors/validate-no-file-import-cycles/executor.js

@@ -17,8 +17,11 @@
  *       "ignoreModifiedUntilEpoch": 1771931925,  // epoch SECONDS; while now < epoch,
  *                                            //   cycles are reported but the gate PASSES
  *                                            //   (warn, don't fail). After it, fails again.
- *       "ignoreTypeOnly": true              // ignore `import type` re-export cycles
+ *       "ignoreTypeOnly": true,             // ignore `import type` re-export cycles
  *                                            //   (erased at compile time, harmless at runtime)
+ *       "excludePackages": ["@kami/entities"] // npm package names whose source trees madge
+ *                                            //   should NOT traverse (stops foreign cycles
+ *                                            //   from leaking into this project's report)
  *   }
  *
  * Mirrors the dated-disable model already used for the method/file-size rules:
@@ -31,7 +34,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = runExecutor;
 const tslib_1 = require("tslib");
 const rules_config_1 = require("@webpieces/rules-config");
+const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
+const toError_1 = require("../../toError");
 const RULE_NAME = 'no-file-import-cycles';
 function loadMadge() {
     // eslint-disable-next-line @typescript-eslint/no-var-requires
@@ -62,10 +67,31 @@ function isFailingActive(epoch) {
 // plain `madge src` run. Excluding these makes the gate scan source only.
 const EXCLUDE_BUILD_DIRS = '(^|/)(node_modules|dist|build|out|coverage|\\.nx|\\.next)(/|$)';
 const EXCLUDE_DECLARATION_FILES = '\\.d\\.ts$';
-function buildMadgeOptions(ignoreTypeOnly) {
+function escapeRegex(s) {
+    return s.replace(/[/\-\\^$*+?.()|[\]{}]/g, '\\$&');
+}
+function resolvePackageDir(pkgName, workspaceRoot) {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- resolution failure is expected for unknown packages; warn and skip
+    try {
+        const pkgJson = require.resolve(`${pkgName}/package.json`, { paths: [workspaceRoot] });
+        return fs.realpathSync(path.dirname(pkgJson));
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        console.warn(`⚠️  no-file-import-cycles: could not resolve excludePackages entry "${pkgName}" (${error.message}) — skipping`);
+        return null;
+    }
+}
+function buildMadgeOptions(ignoreTypeOnly, excludePackages, workspaceRoot) {
+    const excludeRegExp = [EXCLUDE_BUILD_DIRS, EXCLUDE_DECLARATION_FILES];
+    for (const pkg of excludePackages) {
+        const dir = resolvePackageDir(pkg, workspaceRoot);
+        if (dir)
+            excludeRegExp.push(`^${escapeRegex(dir)}(/|$)`);
+    }
     const options = {
         fileExtensions: ['ts', 'tsx'],
-        excludeRegExp: [EXCLUDE_BUILD_DIRS, EXCLUDE_DECLARATION_FILES],
+        excludeRegExp,
     };
     if (ignoreTypeOnly) {
         // dependency-tree's TS detective drops `import type {...}` edges with this flag.
@@ -98,9 +124,10 @@ async function runExecutor(_options, context) {
     const projectRoot = projectConfig ? path.join(context.root, projectConfig.root) : context.root;
     const epoch = rule?.options['ignoreModifiedUntilEpoch'];
     const ignoreTypeOnly = rule?.options['ignoreTypeOnly'] ?? false;
+    const excludePackages = rule?.options['excludePackages'] ?? [];
     console.log(`\n🔁 Checking import cycles in ${projectName} (madge)\n`);
     const madge = loadMadge();
-    const result = await madge(projectRoot, buildMadgeOptions(ignoreTypeOnly));
+    const result = await madge(projectRoot, buildMadgeOptions(ignoreTypeOnly, excludePackages, context.root));
     const cycles = result.circular();
     if (cycles.length === 0) {
         console.log('✅ No circular import cycles found\n');

package/src/executors/validate-no-file-import-cycles/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-no-file-import-cycles/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate No File Import Cycles Executor\n *\n * Per-project circular-dependency gate. Runs `madge` over the project's\n * TypeScript sources and fails when an import cycle is found.\n *\n * Unlike the old `nx:run-commands` target (which shelled out to a runtime\n * `npx madge` fetch — see NEEDED_CHANGES.md #1), this executor:\n *   - invokes the madge it bundles as a dependency (deterministic, no network),\n *   - is driven by webpieces.config.json like every other webpieces rule, so it\n *     supports an on/off `mode` and a time-boxed `ignoreModifiedUntilEpoch`.\n *\n * Config (webpieces.config.json, rule key `no-file-import-cycles`):\n *   \"no-file-import-cycles\": {\n *       \"mode\": \"ON\",                       // \"OFF\" disables the gate everywhere\n *       \"ignoreModifiedUntilEpoch\": 1771931925,  // epoch SECONDS; while now < epoch,\n *                                            //   cycles are reported but the gate PASSES\n *                                            //   (warn, don't fail). After it, fails again.\n *       \"ignoreTypeOnly\": true              // ignore `import type` re-export cycles\n *                                            //   (erased at compile time, harmless at runtime)\n *   }\n *\n * Mirrors the dated-disable model already used for the method/file-size rules:\n * the epoch is a grace window so a strict gate can be turned on against an\n * existing codebase without an open-ended \"off everywhere\" escape hatch.\n *\n * Usage: nx run <project>:validate-no-file-import-cycles\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { loadConfig } from '@webpieces/rules-config';\nimport * as path from 'path';\n\nexport type ValidateNoFileImportCyclesMode = 'ON' | 'OFF';\n\nexport interface ValidateNoFileImportCyclesOptions {\n    // No options here — config comes from webpieces.config.json at runtime.\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst RULE_NAME = 'no-file-import-cycles';\n\n// madge ships no type declarations; describe the slice of its API we use.\n// webpieces-disable no-any-unknown -- minimal hand-typed surface for an untyped dependency\ninterface MadgeOptions {\n    fileExtensions: string[];\n    excludeRegExp?: string[];\n    detectiveOptions?: Record<string, unknown>;\n}\ninterface MadgeInstance {\n    circular(): string[][];\n}\ntype MadgeFn = (target: string, options: MadgeOptions) => Promise<MadgeInstance>;\n\n// madge's CJS export is the callable itself; some bundlers wrap it under `.default`.\ninterface MadgeModuleExtras {\n    default?: MadgeFn;\n}\ntype MadgeModule = MadgeFn & MadgeModuleExtras;\n\nfunction loadMadge(): MadgeFn {\n    // eslint-disable-next-line @typescript-eslint/no-var-requires\n    const mod: MadgeModule = require('madge');\n    return mod.default ?? mod;\n}\n\n/**\n * Decide whether the gate should still FAIL on cycles (true) or only warn\n * (false), considering the ignoreModifiedUntilEpoch grace window. Logs a\n * one-line explanation when the grace window is active.\n */\nfunction isFailingActive(epoch: number | undefined): boolean {\n    if (epoch === undefined) return true;\n    const nowSeconds = Date.now() / 1000;\n    if (nowSeconds < epoch) {\n        const expires = new Date(epoch * 1000).toISOString().split('T')[0];\n        console.log(\n            `\\n⏳ no-file-import-cycles: ignoreModifiedUntilEpoch active (expires ${expires}).` +\n                '\\n   Cycles will be reported but NOT fail the build until then.\\n',\n        );\n        return false;\n    }\n    return true;\n}\n\n// Never scan build output or declaration files. A project that compiles into a\n// local `dist/` (or build/out/coverage) would otherwise report cycles among the\n// emitted `*.d.ts` files instead of — or in addition to — the real source\n// cycles, so the gate would flag compiled-output noise and could diverge from a\n// plain `madge src` run. Excluding these makes the gate scan source only.\nconst EXCLUDE_BUILD_DIRS = '(^|/)(node_modules|dist|build|out|coverage|\\\\.nx|\\\\.next)(/|$)';\nconst EXCLUDE_DECLARATION_FILES = '\\\\.d\\\\.ts$';\n\nfunction buildMadgeOptions(ignoreTypeOnly: boolean): MadgeOptions {\n    const options: MadgeOptions = {\n        fileExtensions: ['ts', 'tsx'],\n        excludeRegExp: [EXCLUDE_BUILD_DIRS, EXCLUDE_DECLARATION_FILES],\n    };\n    if (ignoreTypeOnly) {\n        // dependency-tree's TS detective drops `import type {...}` edges with this flag.\n        options.detectiveOptions = {\n            ts: { skipTypeImports: true },\n            tsx: { skipTypeImports: true },\n        };\n    }\n    return options;\n}\n\nfunction reportCycles(projectName: string, cycles: string[][]): void {\n    console.error(`\\n❌ Found ${cycles.length} circular import cycle(s) in ${projectName}:\\n`);\n    cycles.forEach((cycle: string[], i: number) => {\n        console.error(`  ${i + 1}. ${cycle.join(' → ')} → ${cycle[0]}`);\n    });\n    console.error('\\nTo fix, break the cycle (extract a shared module, or use an interface).');\n    console.error('To time-box a known cycle, a human can set \"ignoreModifiedUntilEpoch\"');\n    console.error(`(epoch seconds) on the \"${RULE_NAME}\" rule in webpieces.config.json.`);\n    console.error(`To turn the gate off entirely, set \"${RULE_NAME}\".mode to \"OFF\".\\n`);\n}\n\nexport default async function runExecutor(\n    _options: ValidateNoFileImportCyclesOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const shared = loadConfig(context.root);\n    const rule = shared.rules.get(RULE_NAME);\n\n    if (rule && rule.isOff) {\n        console.log(`\\n⏭️  Skipping ${RULE_NAME} (mode: OFF)\\n`);\n        return { success: true };\n    }\n\n    const projectName = context.projectName ?? 'project';\n    const projectConfig = context.projectsConfigurations?.projects[projectName];\n    const projectRoot = projectConfig ? path.join(context.root, projectConfig.root) : context.root;\n\n    const epoch = rule?.options['ignoreModifiedUntilEpoch'] as number | undefined;\n    const ignoreTypeOnly = (rule?.options['ignoreTypeOnly'] as boolean | undefined) ?? false;\n\n    console.log(`\\n🔁 Checking import cycles in ${projectName} (madge)\\n`);\n\n    const madge = loadMadge();\n    const result = await madge(projectRoot, buildMadgeOptions(ignoreTypeOnly));\n    const cycles = result.circular();\n\n    if (cycles.length === 0) {\n        console.log('✅ No circular import cycles found\\n');\n        return { success: true };\n    }\n\n    reportCycles(projectName, cycles);\n\n    // Grace window active → report but pass; otherwise fail.\n    return { success: !isFailingActive(epoch) };\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-no-file-import-cycles/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate No File Import Cycles Executor\n *\n * Per-project circular-dependency gate. Runs `madge` over the project's\n * TypeScript sources and fails when an import cycle is found.\n *\n * Unlike the old `nx:run-commands` target (which shelled out to a runtime\n * `npx madge` fetch — see NEEDED_CHANGES.md #1), this executor:\n *   - invokes the madge it bundles as a dependency (deterministic, no network),\n *   - is driven by webpieces.config.json like every other webpieces rule, so it\n *     supports an on/off `mode` and a time-boxed `ignoreModifiedUntilEpoch`.\n *\n * Config (webpieces.config.json, rule key `no-file-import-cycles`):\n *   \"no-file-import-cycles\": {\n *       \"mode\": \"ON\",                       // \"OFF\" disables the gate everywhere\n *       \"ignoreModifiedUntilEpoch\": 1771931925,  // epoch SECONDS; while now < epoch,\n *                                            //   cycles are reported but the gate PASSES\n *                                            //   (warn, don't fail). After it, fails again.\n *       \"ignoreTypeOnly\": true,             // ignore `import type` re-export cycles\n *                                            //   (erased at compile time, harmless at runtime)\n *       \"excludePackages\": [\"@kami/entities\"] // npm package names whose source trees madge\n *                                            //   should NOT traverse (stops foreign cycles\n *                                            //   from leaking into this project's report)\n *   }\n *\n * Mirrors the dated-disable model already used for the method/file-size rules:\n * the epoch is a grace window so a strict gate can be turned on against an\n * existing codebase without an open-ended \"off everywhere\" escape hatch.\n *\n * Usage: nx run <project>:validate-no-file-import-cycles\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { loadConfig } from '@webpieces/rules-config';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { toError } from '../../toError';\n\nexport type ValidateNoFileImportCyclesMode = 'ON' | 'OFF';\n\nexport interface ValidateNoFileImportCyclesOptions {\n    // No options here — config comes from webpieces.config.json at runtime.\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst RULE_NAME = 'no-file-import-cycles';\n\n// madge ships no type declarations; describe the slice of its API we use.\n// webpieces-disable no-any-unknown -- minimal hand-typed surface for an untyped dependency\ninterface MadgeOptions {\n    fileExtensions: string[];\n    excludeRegExp?: string[];\n    detectiveOptions?: Record<string, unknown>;\n}\ninterface MadgeInstance {\n    circular(): string[][];\n}\ntype MadgeFn = (target: string, options: MadgeOptions) => Promise<MadgeInstance>;\n\n// madge's CJS export is the callable itself; some bundlers wrap it under `.default`.\ninterface MadgeModuleExtras {\n    default?: MadgeFn;\n}\ntype MadgeModule = MadgeFn & MadgeModuleExtras;\n\nfunction loadMadge(): MadgeFn {\n    // eslint-disable-next-line @typescript-eslint/no-var-requires\n    const mod: MadgeModule = require('madge');\n    return mod.default ?? mod;\n}\n\n/**\n * Decide whether the gate should still FAIL on cycles (true) or only warn\n * (false), considering the ignoreModifiedUntilEpoch grace window. Logs a\n * one-line explanation when the grace window is active.\n */\nfunction isFailingActive(epoch: number | undefined): boolean {\n    if (epoch === undefined) return true;\n    const nowSeconds = Date.now() / 1000;\n    if (nowSeconds < epoch) {\n        const expires = new Date(epoch * 1000).toISOString().split('T')[0];\n        console.log(\n            `\\n⏳ no-file-import-cycles: ignoreModifiedUntilEpoch active (expires ${expires}).` +\n                '\\n   Cycles will be reported but NOT fail the build until then.\\n',\n        );\n        return false;\n    }\n    return true;\n}\n\n// Never scan build output or declaration files. A project that compiles into a\n// local `dist/` (or build/out/coverage) would otherwise report cycles among the\n// emitted `*.d.ts` files instead of — or in addition to — the real source\n// cycles, so the gate would flag compiled-output noise and could diverge from a\n// plain `madge src` run. Excluding these makes the gate scan source only.\nconst EXCLUDE_BUILD_DIRS = '(^|/)(node_modules|dist|build|out|coverage|\\\\.nx|\\\\.next)(/|$)';\nconst EXCLUDE_DECLARATION_FILES = '\\\\.d\\\\.ts$';\n\nfunction escapeRegex(s: string): string {\n    return s.replace(/[/\\-\\\\^$*+?.()|[\\]{}]/g, '\\\\$&');\n}\n\nfunction resolvePackageDir(pkgName: string, workspaceRoot: string): string | null {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- resolution failure is expected for unknown packages; warn and skip\n    try {\n        const pkgJson = require.resolve(`${pkgName}/package.json`, { paths: [workspaceRoot] });\n        return fs.realpathSync(path.dirname(pkgJson));\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.warn(`⚠️  no-file-import-cycles: could not resolve excludePackages entry \"${pkgName}\" (${error.message}) — skipping`);\n        return null;\n    }\n}\n\nfunction buildMadgeOptions(ignoreTypeOnly: boolean, excludePackages: string[], workspaceRoot: string): MadgeOptions {\n    const excludeRegExp = [EXCLUDE_BUILD_DIRS, EXCLUDE_DECLARATION_FILES];\n    for (const pkg of excludePackages) {\n        const dir = resolvePackageDir(pkg, workspaceRoot);\n        if (dir) excludeRegExp.push(`^${escapeRegex(dir)}(/|$)`);\n    }\n    const options: MadgeOptions = {\n        fileExtensions: ['ts', 'tsx'],\n        excludeRegExp,\n    };\n    if (ignoreTypeOnly) {\n        // dependency-tree's TS detective drops `import type {...}` edges with this flag.\n        options.detectiveOptions = {\n            ts: { skipTypeImports: true },\n            tsx: { skipTypeImports: true },\n        };\n    }\n    return options;\n}\n\nfunction reportCycles(projectName: string, cycles: string[][]): void {\n    console.error(`\\n❌ Found ${cycles.length} circular import cycle(s) in ${projectName}:\\n`);\n    cycles.forEach((cycle: string[], i: number) => {\n        console.error(`  ${i + 1}. ${cycle.join(' → ')} → ${cycle[0]}`);\n    });\n    console.error('\\nTo fix, break the cycle (extract a shared module, or use an interface).');\n    console.error('To time-box a known cycle, a human can set \"ignoreModifiedUntilEpoch\"');\n    console.error(`(epoch seconds) on the \"${RULE_NAME}\" rule in webpieces.config.json.`);\n    console.error(`To turn the gate off entirely, set \"${RULE_NAME}\".mode to \"OFF\".\\n`);\n}\n\nexport default async function runExecutor(\n    _options: ValidateNoFileImportCyclesOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const shared = loadConfig(context.root);\n    const rule = shared.rules.get(RULE_NAME);\n\n    if (rule && rule.isOff) {\n        console.log(`\\n⏭️  Skipping ${RULE_NAME} (mode: OFF)\\n`);\n        return { success: true };\n    }\n\n    const projectName = context.projectName ?? 'project';\n    const projectConfig = context.projectsConfigurations?.projects[projectName];\n    const projectRoot = projectConfig ? path.join(context.root, projectConfig.root) : context.root;\n\n    const epoch = rule?.options['ignoreModifiedUntilEpoch'] as number | undefined;\n    const ignoreTypeOnly = (rule?.options['ignoreTypeOnly'] as boolean | undefined) ?? false;\n    const excludePackages = (rule?.options['excludePackages'] as string[] | undefined) ?? [];\n\n    console.log(`\\n🔁 Checking import cycles in ${projectName} (madge)\\n`);\n\n    const madge = loadMadge();\n    const result = await madge(projectRoot, buildMadgeOptions(ignoreTypeOnly, excludePackages, context.root));\n    const cycles = result.circular();\n\n    if (cycles.length === 0) {\n        console.log('✅ No circular import cycles found\\n');\n        return { success: true };\n    }\n\n    reportCycles(projectName, cycles);\n\n    // Grace window active → report but pass; otherwise fail.\n    return { success: !isFailingActive(epoch) };\n}\n"]}