@webpieces/nx-webpieces-rules 0.4.451 → 0.4.452

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.4.451",
+  "version": "0.4.452",
   "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",
@@ -21,11 +21,11 @@
     "README.md"
   ],
   "dependencies": {
-    "@webpieces/ai-hook-rules": "0.4.451",
-    "@webpieces/code-rules": "0.4.451",
-    "@webpieces/eslint-rules": "0.4.451",
-    "@webpieces/pr-gate": "0.4.451",
-    "@webpieces/rules-config": "0.4.451",
+    "@webpieces/ai-hook-rules": "0.4.452",
+    "@webpieces/code-rules": "0.4.452",
+    "@webpieces/eslint-rules": "0.4.452",
+    "@webpieces/pr-gate": "0.4.452",
+    "@webpieces/rules-config": "0.4.452",
     "madge": "8.0.0"
   },
   "peerDependencies": {

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

@@ -36,4 +36,11 @@ export interface ValidateNoFileImportCyclesOptions {
 export interface ExecutorResult {
     success: boolean;
 }
+interface MadgeOptions {
+    fileExtensions: string[];
+    excludeRegExp?: string[];
+    detectiveOptions?: Record<string, unknown>;
+}
+export declare function buildMadgeOptions(ignoreTypeOnly: boolean, excludePackages: string[], workspaceRoot: string, projectRoot: string): MadgeOptions;
 export default function runExecutor(_options: ValidateNoFileImportCyclesOptions, context: ExecutorContext): Promise<ExecutorResult>;
+export {};

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

@@ -31,6 +31,7 @@
  * Usage: nx run <project>:validate-no-file-import-cycles
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMadgeOptions = buildMadgeOptions;
 exports.default = runExecutor;
 const tslib_1 = require("tslib");
 const rules_config_1 = require("@webpieces/rules-config");
@@ -143,12 +144,78 @@ function resolvePackageDir(pkgName, workspaceRoot) {
         return null;
     }
 }
-function buildMadgeOptions(ignoreTypeOnly, excludePackages, workspaceRoot) {
+/**
+ * Realpath a directory, tolerating a non-existent path (returns the input).
+ * madge traverses through pnpm symlinks to real paths, and resolvePackageDir
+ * already realpaths its result, so projectRoot must be realpath'd too or the
+ * computed relative path won't line up with the ids madge emits.
+ */
+// webpieces-disable no-function-outside-class -- nx executor module; file is functional by convention (see resolvePackageDir/reportCycles above)
+function realpathOrSelf(dir) {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- best-effort; fall back to the raw path
+    try {
+        return fs.realpathSync(dir);
+        // webpieces-disable catch-error-pattern -- path may not exist yet; use it as-is
+    }
+    catch (err) {
+        //const error = toError(err);
+        return dir;
+    }
+}
+/** True if dir contains at least one .ts/.tsx source file anywhere beneath it. */
+// webpieces-disable no-function-outside-class -- nx executor module; file is functional by convention (see resolvePackageDir/reportCycles above)
+function hasSourceFiles(dir) {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- best-effort scan; false on any read failure
+    try {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build')
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (hasSourceFiles(full))
+                    return true;
+            }
+            else if (/\.tsx?$/.test(entry.name) && !entry.name.endsWith('.d.ts')) {
+                return true;
+            }
+        }
+        return false;
+        // webpieces-disable catch-error-pattern -- unreadable dir; treat as no source
+    }
+    catch (err) {
+        //const error = toError(err);
+        return false;
+    }
+}
+/**
+ * Build the exclude pattern for one resolved package dir, RELATIVE to the base
+ * madge is invoked with (projectRoot). madge matches excludeRegExp against ids
+ * relative to that base — e.g. '../../libraries/kami/src/x.ts' — so an absolute
+ * `^/abs/...` anchor can never match and silently excludes nothing. Returns the
+ * relative-anchored pattern. Warns (but still returns the pattern) when the dir
+ * holds no source madge would traverse, closing the resolves-but-matches-nothing
+ * silent-failure gap.
+ */
+// webpieces-disable no-function-outside-class -- nx executor module; file is functional by convention (see resolvePackageDir/reportCycles above)
+function buildExcludePattern(dir, base, pkgName) {
+    // madge ids always use forward slashes; normalise path.sep so this holds on Windows.
+    const rel = path.relative(base, dir).split(path.sep).join('/');
+    if (!hasSourceFiles(dir)) {
+        console.warn(`⚠️  no-file-import-cycles: excludePackages entry "${pkgName}" resolved to "${dir}"` +
+            ` but that directory contains no .ts/.tsx source — the exclusion will match nothing.`);
+    }
+    return `^${escapeRegex(rel)}(/|$)`;
+}
+// webpieces-disable no-function-outside-class -- nx executor module; file is functional by convention (see resolvePackageDir/reportCycles above)
+function buildMadgeOptions(ignoreTypeOnly, excludePackages, workspaceRoot, projectRoot) {
     const excludeRegExp = [EXCLUDE_BUILD_DIRS, EXCLUDE_DECLARATION_FILES];
+    // madge is invoked with projectRoot as its base and emits ids relative to it;
+    // realpath it to match resolvePackageDir's realpath'd result under pnpm symlinks.
+    const base = realpathOrSelf(projectRoot);
     for (const pkg of excludePackages) {
         const dir = resolvePackageDir(pkg, workspaceRoot);
         if (dir)
-            excludeRegExp.push(`^${escapeRegex(dir)}(/|$)`);
+            excludeRegExp.push(buildExcludePattern(dir, base, pkg));
     }
     const options = {
         fileExtensions: ['ts', 'tsx'],
@@ -189,7 +256,7 @@ async function runExecutor(_options, context) {
     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, excludePackages, context.root));
+    const result = await madge(projectRoot, buildMadgeOptions(ignoreTypeOnly, excludePackages, context.root, projectRoot));
     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\": \"RUN_EVERY_TIME\",           // \"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 { loadAndValidate, shouldSkipRule } from '@webpieces/rules-config';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { toError } from '../../toError';\n\nexport type ValidateNoFileImportCyclesMode = 'RUN_EVERY_TIME' | '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 universal escape hatches: the ignoreModifiedUntilEpoch\n * grace window and ignoreRuleWhileOnBranch. Logs a one-line explanation when a\n * hatch is active.\n */\nfunction isFailingActive(epoch: number | undefined, branch: string | undefined): boolean {\n    const skip = shouldSkipRule(epoch, branch);\n    if (skip.skip) {\n        console.log(\n            `\\n⏳ no-file-import-cycles: ${skip.reason}.` +\n                '\\n   Cycles will be reported but NOT fail the build.\\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\nclass TsconfigCompilerOptions {\n    paths?: Record<string, string[]>;\n}\nclass TsconfigBase {\n    compilerOptions?: TsconfigCompilerOptions;\n}\n\n/** Read tsconfig.base.json compilerOptions.paths from the workspace root, or null on failure. */\nfunction readTsconfigPaths(workspaceRoot: string): Record<string, string[]> | null {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- best-effort read; null on any failure\n    try {\n        const tsconfigPath = path.join(workspaceRoot, 'tsconfig.base.json');\n        const content = fs.readFileSync(tsconfigPath, 'utf8');\n        const tsconfig = JSON.parse(content) as TsconfigBase;\n        return tsconfig?.compilerOptions?.paths ?? null;\n    // webpieces-disable catch-error-pattern -- file missing or malformed JSON; caller handles null\n    } catch (err: unknown) {\n        //const error = toError(err);\n        return null;\n    }\n}\n\n/**\n * Walk up from startPath to find the nearest ancestor directory that contains\n * a package.json. Returns that directory path, or null if none found.\n */\nfunction findPackageRoot(startPath: string): string | null {\n    let dir = fs.statSync(startPath).isDirectory() ? startPath : path.dirname(startPath);\n    const fsRoot = path.parse(dir).root;\n    while (dir !== fsRoot) {\n        if (fs.existsSync(path.join(dir, 'package.json'))) return dir;\n        dir = path.dirname(dir);\n    }\n    return null;\n}\n\nfunction resolvePackageDir(pkgName: string, workspaceRoot: string): string | null {\n    // First try require.resolve (works for installed / symlinked packages).\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- resolution failure is expected; fall through to tsconfig path lookup\n    try {\n        const pkgJson = require.resolve(`${pkgName}/package.json`, { paths: [workspaceRoot] });\n        return fs.realpathSync(path.dirname(pkgJson));\n    // webpieces-disable catch-error-pattern -- expected for non-installed packages; fall through to tsconfig path lookup\n    } catch (err: unknown) {\n        //const error = toError(err);\n        // Fall through to tsconfig path resolution for pnpm workspace packages.\n    }\n\n    // Fallback: resolve via tsconfig.base.json compilerOptions.paths.\n    // pnpm workspace packages are not in node_modules, so require.resolve fails above;\n    // tsconfig.base.json maps e.g. \"@mealco-internal/kami\" → [\"libraries/kami/index.ts\"].\n    const tsconfigPaths = readTsconfigPaths(workspaceRoot);\n    const entries = tsconfigPaths?.[pkgName];\n    if (!entries || entries.length === 0) {\n        console.warn(\n            `⚠️  no-file-import-cycles: could not resolve excludePackages entry \"${pkgName}\"` +\n                ` — not found in node_modules or tsconfig.base.json paths. Skipping.`,\n        );\n        return null;\n    }\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- best-effort fallback; warn on any failure\n    try {\n        const resolved = path.resolve(workspaceRoot, entries[0]);\n        const pkgRoot = findPackageRoot(resolved);\n        if (!pkgRoot) {\n            console.warn(\n                `⚠️  no-file-import-cycles: resolved \"${pkgName}\" → \"${resolved}\"` +\n                    ` but found no package.json in parent directories — skipping.`,\n            );\n            return null;\n        }\n        return pkgRoot;\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.warn(\n            `⚠️  no-file-import-cycles: could not resolve excludePackages entry \"${pkgName}\"` +\n                ` via tsconfig paths (${error.message}) — skipping.`,\n        );\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 = loadAndValidate(context.root).resolved;\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 branch = rule?.options['ignoreRuleWhileOnBranch'] as string | 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 or branch hatch active → report but pass; otherwise fail.\n    return { success: !isFailingActive(epoch, branch) };\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\": \"RUN_EVERY_TIME\",           // \"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 { loadAndValidate, shouldSkipRule } from '@webpieces/rules-config';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { toError } from '../../toError';\n\nexport type ValidateNoFileImportCyclesMode = 'RUN_EVERY_TIME' | '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 universal escape hatches: the ignoreModifiedUntilEpoch\n * grace window and ignoreRuleWhileOnBranch. Logs a one-line explanation when a\n * hatch is active.\n */\nfunction isFailingActive(epoch: number | undefined, branch: string | undefined): boolean {\n    const skip = shouldSkipRule(epoch, branch);\n    if (skip.skip) {\n        console.log(\n            `\\n⏳ no-file-import-cycles: ${skip.reason}.` +\n                '\\n   Cycles will be reported but NOT fail the build.\\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\nclass TsconfigCompilerOptions {\n    paths?: Record<string, string[]>;\n}\nclass TsconfigBase {\n    compilerOptions?: TsconfigCompilerOptions;\n}\n\n/** Read tsconfig.base.json compilerOptions.paths from the workspace root, or null on failure. */\nfunction readTsconfigPaths(workspaceRoot: string): Record<string, string[]> | null {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- best-effort read; null on any failure\n    try {\n        const tsconfigPath = path.join(workspaceRoot, 'tsconfig.base.json');\n        const content = fs.readFileSync(tsconfigPath, 'utf8');\n        const tsconfig = JSON.parse(content) as TsconfigBase;\n        return tsconfig?.compilerOptions?.paths ?? null;\n    // webpieces-disable catch-error-pattern -- file missing or malformed JSON; caller handles null\n    } catch (err: unknown) {\n        //const error = toError(err);\n        return null;\n    }\n}\n\n/**\n * Walk up from startPath to find the nearest ancestor directory that contains\n * a package.json. Returns that directory path, or null if none found.\n */\nfunction findPackageRoot(startPath: string): string | null {\n    let dir = fs.statSync(startPath).isDirectory() ? startPath : path.dirname(startPath);\n    const fsRoot = path.parse(dir).root;\n    while (dir !== fsRoot) {\n        if (fs.existsSync(path.join(dir, 'package.json'))) return dir;\n        dir = path.dirname(dir);\n    }\n    return null;\n}\n\nfunction resolvePackageDir(pkgName: string, workspaceRoot: string): string | null {\n    // First try require.resolve (works for installed / symlinked packages).\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- resolution failure is expected; fall through to tsconfig path lookup\n    try {\n        const pkgJson = require.resolve(`${pkgName}/package.json`, { paths: [workspaceRoot] });\n        return fs.realpathSync(path.dirname(pkgJson));\n    // webpieces-disable catch-error-pattern -- expected for non-installed packages; fall through to tsconfig path lookup\n    } catch (err: unknown) {\n        //const error = toError(err);\n        // Fall through to tsconfig path resolution for pnpm workspace packages.\n    }\n\n    // Fallback: resolve via tsconfig.base.json compilerOptions.paths.\n    // pnpm workspace packages are not in node_modules, so require.resolve fails above;\n    // tsconfig.base.json maps e.g. \"@mealco-internal/kami\" → [\"libraries/kami/index.ts\"].\n    const tsconfigPaths = readTsconfigPaths(workspaceRoot);\n    const entries = tsconfigPaths?.[pkgName];\n    if (!entries || entries.length === 0) {\n        console.warn(\n            `⚠️  no-file-import-cycles: could not resolve excludePackages entry \"${pkgName}\"` +\n                ` — not found in node_modules or tsconfig.base.json paths. Skipping.`,\n        );\n        return null;\n    }\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- best-effort fallback; warn on any failure\n    try {\n        const resolved = path.resolve(workspaceRoot, entries[0]);\n        const pkgRoot = findPackageRoot(resolved);\n        if (!pkgRoot) {\n            console.warn(\n                `⚠️  no-file-import-cycles: resolved \"${pkgName}\" → \"${resolved}\"` +\n                    ` but found no package.json in parent directories — skipping.`,\n            );\n            return null;\n        }\n        return pkgRoot;\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.warn(\n            `⚠️  no-file-import-cycles: could not resolve excludePackages entry \"${pkgName}\"` +\n                ` via tsconfig paths (${error.message}) — skipping.`,\n        );\n        return null;\n    }\n}\n\n/**\n * Realpath a directory, tolerating a non-existent path (returns the input).\n * madge traverses through pnpm symlinks to real paths, and resolvePackageDir\n * already realpaths its result, so projectRoot must be realpath'd too or the\n * computed relative path won't line up with the ids madge emits.\n */\n// webpieces-disable no-function-outside-class -- nx executor module; file is functional by convention (see resolvePackageDir/reportCycles above)\nfunction realpathOrSelf(dir: string): string {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- best-effort; fall back to the raw path\n    try {\n        return fs.realpathSync(dir);\n    // webpieces-disable catch-error-pattern -- path may not exist yet; use it as-is\n    } catch (err: unknown) {\n        //const error = toError(err);\n        return dir;\n    }\n}\n\n/** True if dir contains at least one .ts/.tsx source file anywhere beneath it. */\n// webpieces-disable no-function-outside-class -- nx executor module; file is functional by convention (see resolvePackageDir/reportCycles above)\nfunction hasSourceFiles(dir: string): boolean {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- best-effort scan; false on any read failure\n    try {\n        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {\n            if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build') continue;\n            const full = path.join(dir, entry.name);\n            if (entry.isDirectory()) {\n                if (hasSourceFiles(full)) return true;\n            } else if (/\\.tsx?$/.test(entry.name) && !entry.name.endsWith('.d.ts')) {\n                return true;\n            }\n        }\n        return false;\n    // webpieces-disable catch-error-pattern -- unreadable dir; treat as no source\n    } catch (err: unknown) {\n        //const error = toError(err);\n        return false;\n    }\n}\n\n/**\n * Build the exclude pattern for one resolved package dir, RELATIVE to the base\n * madge is invoked with (projectRoot). madge matches excludeRegExp against ids\n * relative to that base — e.g. '../../libraries/kami/src/x.ts' — so an absolute\n * `^/abs/...` anchor can never match and silently excludes nothing. Returns the\n * relative-anchored pattern. Warns (but still returns the pattern) when the dir\n * holds no source madge would traverse, closing the resolves-but-matches-nothing\n * silent-failure gap.\n */\n// webpieces-disable no-function-outside-class -- nx executor module; file is functional by convention (see resolvePackageDir/reportCycles above)\nfunction buildExcludePattern(dir: string, base: string, pkgName: string): string {\n    // madge ids always use forward slashes; normalise path.sep so this holds on Windows.\n    const rel = path.relative(base, dir).split(path.sep).join('/');\n    if (!hasSourceFiles(dir)) {\n        console.warn(\n            `⚠️  no-file-import-cycles: excludePackages entry \"${pkgName}\" resolved to \"${dir}\"` +\n                ` but that directory contains no .ts/.tsx source — the exclusion will match nothing.`,\n        );\n    }\n    return `^${escapeRegex(rel)}(/|$)`;\n}\n\n// webpieces-disable no-function-outside-class -- nx executor module; file is functional by convention (see resolvePackageDir/reportCycles above)\nexport function buildMadgeOptions(\n    ignoreTypeOnly: boolean,\n    excludePackages: string[],\n    workspaceRoot: string,\n    projectRoot: string,\n): MadgeOptions {\n    const excludeRegExp = [EXCLUDE_BUILD_DIRS, EXCLUDE_DECLARATION_FILES];\n    // madge is invoked with projectRoot as its base and emits ids relative to it;\n    // realpath it to match resolvePackageDir's realpath'd result under pnpm symlinks.\n    const base = realpathOrSelf(projectRoot);\n    for (const pkg of excludePackages) {\n        const dir = resolvePackageDir(pkg, workspaceRoot);\n        if (dir) excludeRegExp.push(buildExcludePattern(dir, base, pkg));\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 = loadAndValidate(context.root).resolved;\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 branch = rule?.options['ignoreRuleWhileOnBranch'] as string | 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, projectRoot));\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 or branch hatch active → report but pass; otherwise fail.\n    return { success: !isFailingActive(epoch, branch) };\n}\n"]}