@webpieces/nx-webpieces-rules 0.4.700 → 0.4.702

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

@@ -1 +1 @@
-{"version":3,"file":"graph-metadata.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-metadata.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Metadata Enrichment\n *\n * Fills the AI-oriented fields on each architecture/dependencies.json entry:\n *   framework            — from `framework:<x>` nx tag or package.json inference\n *   serviceName          — from project.json metadata.webpieces.serviceName; the\n *                          name clients address this app by at runtime\n *   shortDescription     — first paragraph of the project's responsibilities.md\n *   responsibilitiesFile — repo-relative path to the required responsibilities.md\n *   designFile           — repo-relative path to the generated DI design.json\n *\n * Validation is aggregated: ALL problems across ALL projects are collected and\n * thrown as one MetadataValidationError so a repo adopting this sees the full\n * seeding list in a single run. Callers must enrich BEFORE writing any file so\n * a failed run never clobbers dependencies.json.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { createProjectGraphAsync } from '@nx/devkit';\nimport type { EnhancedGraph, GraphEntry } from './graph-sorter';\nimport { ProjectInfo } from './project-info';\nimport { resolveFramework } from './framework-resolver';\nimport { resolveRole } from './role-resolver';\nimport { resolveDrawOnGraph } from './draw-on-graph-resolver';\nimport { resolveRuntimeParticipant } from './runtime-participant-resolver';\nimport { resolveCallsService, resolveServiceName, validateUniqueServiceNames } from './service-name-resolver';\nimport { extractShortDescription, validateShortDescription } from './responsibilities';\nimport { toError } from '../toError';\n\nexport const RESPONSIBILITIES_FILE_NAME = 'responsibilities.md';\n\n/**\n * Thrown when one or more projects fail metadata validation (missing/invalid\n * responsibilities.md, bad framework tags, ...). Executors catch this to point\n * AI at the webpieces.responsibilities.md instructions template.\n */\nexport class MetadataValidationError extends Error {\n    constructor(public readonly problems: string[]) {\n        super(\n            `Architecture metadata validation failed (${problems.length} problem(s)):\\n` +\n                problems.map((problem: string) => `  - ${problem}`).join('\\n')\n        );\n        this.name = 'MetadataValidationError';\n    }\n}\n\n/**\n * Read per-project root + tags from nx's project graph.\n */\nexport async function collectProjectInfo(): Promise<Map<string, ProjectInfo>> {\n    const projectGraph = await createProjectGraphAsync();\n    const infos = new Map<string, ProjectInfo>();\n    for (const [name, node] of Object.entries(projectGraph.nodes)) {\n        infos.set(name, new ProjectInfo(name, node.data.root, node.data.tags ?? []));\n    }\n    return infos;\n}\n\n/**\n * Enrich every graph entry in place with framework, shortDescription,\n * responsibilitiesFile and designFile. Throws MetadataValidationError listing\n * every problem when any project fails validation.\n */\nexport function enrichGraph(\n    graph: EnhancedGraph,\n    infos: Map<string, ProjectInfo>,\n    workspaceRoot: string\n): void {\n    const problems: string[] = [];\n    // project -> declared serviceName, collected so duplicates can be reported across the workspace.\n    const serviceNames = new Map<string, string>();\n\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const info = infos.get(projectName);\n        if (!info) {\n            problems.push(`${projectName}: not found in nx project graph`);\n            continue;\n        }\n\n        enrichDeclarations(entry, info, workspaceRoot, problems);\n        enrichClientNames(entry, info, workspaceRoot, projectName, serviceNames, problems);\n        enrichResponsibilities(entry, info, workspaceRoot, problems);\n\n        // Set designFile ONLY when the project has a REAL generated design (a\n        // non-empty `designs[]`), i.e. it has a @DocumentDesign root. A project\n        // without one has NO design.json at all (di-graph-generate stopped writing\n        // empty ones and reaps stale ones), and legacy repos may still carry an\n        // empty `{ designs: [] }` until their next build — both must read the same\n        // way, and neither gets a \"View Design\" item on its node menu in the arch\n        // viz (designLinks keys off designFile). See graph-visualizer.ts.\n        if (hasGeneratedDesign(workspaceRoot, info.root)) {\n            entry.designFile = toRepoRelative(info.root, 'design.json');\n        }\n    }\n\n    validateUniqueServiceNames(serviceNames, problems);\n    validateLibraryTypesMatch(graph, problems);\n    validateRoleDependencies(graph, problems);\n\n    if (problems.length > 0) {\n        throw new MetadataValidationError(problems);\n    }\n}\n\n/**\n * The fields a project DECLARES about itself — its framework env set and role (nx tags), the\n * webpieces runtime packages it depends on (package.json), and whether it opts out of the drawings\n * (nx tag). Grouped because they share a shape: resolve, record the problem, or write the field.\n *\n * Distinct from enrichResponsibilities/designFile, which read generated or hand-written FILES.\n */\n// webpieces-disable no-function-outside-class -- enrichGraph step helper, matching enrichClientNames/enrichResponsibilities in this file\nfunction enrichDeclarations(\n    entry: GraphEntry,\n    info: ProjectInfo,\n    workspaceRoot: string,\n    problems: string[]\n): void {\n    const resolution = resolveFramework(info, workspaceRoot);\n    if (resolution.problem !== null) {\n        problems.push(resolution.problem);\n    } else if (resolution.frameworks !== null) {\n        entry.framework = resolution.frameworks;\n    }\n\n    const roleResolution = resolveRole(info);\n    if (roleResolution.problem !== null) {\n        problems.push(roleResolution.problem);\n    } else if (roleResolution.role !== null) {\n        entry.role = roleResolution.role;\n    }\n\n    // Only persist when the project declares at least one — a repo full of\n    // \"webpiecesRuntime\": [] lines would be noise, and absence already means \"declares none\".\n    const participantResolution = resolveRuntimeParticipant(info, workspaceRoot);\n    if (participantResolution.problem !== null) {\n        problems.push(participantResolution.problem);\n    } else if (participantResolution.markers !== null && participantResolution.markers.length > 0) {\n        entry.webpiecesRuntime = participantResolution.markers;\n    }\n\n    // Only persist the field when hidden (false); drawn projects (the\n    // default) stay clean in dependencies.json with no drawOnGraph line.\n    const drawResolution = resolveDrawOnGraph(info);\n    if (drawResolution.problem !== null) {\n        problems.push(drawResolution.problem);\n    } else if (drawResolution.drawOnGraph === false) {\n        entry.drawOnGraph = false;\n    }\n}\n\n/**\n * Roles that are terminal APPS — nothing may depend on them. A server, a\n * non-HTTP `app`, or a client is a top-level runnable; being depended upon means\n * it is really a library and should be retagged `role:lib`/`role:designed-lib`.\n */\nexport const APP_ROLES: ReadonlyArray<string> = ['server', 'app', 'client'];\n\n/**\n * Compatibility lattice — the \"up-set\" of each atomic env is the env itself\n * PLUS every ancestor it can legally consume code from (specialization edges\n * child → parent: react → browser, angular → browser, express → node). A\n * consumer promising env `c` can be satisfied by any dependency env in `up(c)`.\n */\nexport const ENV_UP_SETS: Readonly<Record<string, ReadonlyArray<string>>> = {\n    react: ['react', 'browser'],\n    angular: ['angular', 'browser'],\n    browser: ['browser'],\n    express: ['express', 'node'],\n    node: ['node'],\n};\n\n/** The up-set of an env (env itself + ancestors); unknown envs map to just themselves. */\nfunction upSet(env: string): ReadonlyArray<string> {\n    return ENV_UP_SETS[env] ?? [env];\n}\n\n/**\n * `library-types-match-client` rule.\n *\n * A project's `framework` field is its libType — the SET of runtime\n * environments it is validated to run in (browser | react | angular | node |\n * express). For a dependency edge Consumer C → Library L, the edge is LEGAL iff\n * for EVERY env `c` in C's set, up(c) ∩ L's set ≠ ∅ — i.e. every environment\n * the consumer promises to run in can be satisfied by the dependency. This keeps\n * an express app from depending on a browser-only lib, and lets a `browser+node`\n * lib be consumed by both react and express projects. Every violation is\n * appended to `problems` so `arch:generate` fails with the full list.\n */\nexport function validateLibraryTypesMatch(graph: EnhancedGraph, problems: string[]): void {\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const fromSet = entry.framework;\n        if (fromSet === undefined) continue; // framework resolution already flagged this project\n\n        for (const dep of entry.dependsOn) {\n            const depEntry = graph[dep];\n            const toSet = depEntry?.framework;\n            if (toSet === undefined) continue;\n\n            const unsatisfied = fromSet.filter(\n                (env: string) => !upSet(env).some((up: string) => toSet.includes(up))\n            );\n            if (unsatisfied.length === 0) continue;\n\n            problems.push(\n                `library-types-match-client: '${projectName}' [${fromSet.join(', ')}] must not depend on ` +\n                    `'${dep}' [${toSet.join(', ')}] — the consumer env(s) ${unsatisfied.join(', ')} cannot be ` +\n                    `satisfied by the dependency (each consumer env must resolve to itself or an ancestor it ` +\n                    `consumes from: react/angular→browser, express→node). Widen '${dep}' framework tags or ` +\n                    `remove the dependency.`\n            );\n        }\n    }\n}\n\n/**\n * `role-dependency` rule.\n *\n * A project's `role` is its function (server | designed-lib | lib | client).\n * Apps are terminal — libraries and clients consume them, never the reverse:\n *   - a `client` is fully terminal: NOTHING may depend on it.\n *   - a `server` may only be depended upon by another `server` — the one\n *     legitimate case is a server-side orchestrator/e2e harness that boots\n *     other servers. A `lib`/`designed-lib`/`client` depending on a `server`\n *     inverts the dependency direction and is a violation.\n *   - a `bundle` is the one role permitted to depend on ANY app: it aggregates\n *     several apps into one distributable (e.g. an nx plugin re-exposing multiple\n *     tooling apps), so a `bundle → app` edge is legitimate, not inverted.\n */\nexport function validateRoleDependencies(graph: EnhancedGraph, problems: string[]): void {\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const fromRole = entry.role;\n        for (const dep of entry.dependsOn) {\n            const toRole = graph[dep]?.role;\n            if (toRole === undefined) continue; // role resolution already flagged this project\n            if (!APP_ROLES.includes(toRole)) continue;\n            // A server may orchestrate/boot other servers (e.g. an e2e harness).\n            if (toRole === 'server' && fromRole === 'server') continue;\n            // A bundle aggregates apps — it may depend on any app role.\n            if (fromRole === 'bundle') continue;\n\n            const why =\n                toRole === 'client'\n                    ? `a 'client' app is terminal and may never be depended upon`\n                    : `a 'server' may only be depended upon by another 'server' (an orchestrator/e2e harness)`;\n            problems.push(\n                `role-dependency: '${projectName}' (role:${fromRole ?? 'none'}) must not depend on ` +\n                    `'${dep}' (role:${toRole}) — ${why}. Retag '${dep}' role:lib/role:designed-lib if it ` +\n                    `is actually a library, or remove the dependency.`\n            );\n        }\n    }\n}\n\n/**\n * Fill the two symmetric client-addressing fields — `serviceName` (the name clients address THIS app\n * by) and `callsService` (the name THIS app's clients call when no literal ClientConfig sits at the\n * call site). Both are declared in project.json, never derived (see service-name-resolver.ts).\n */\n// webpieces-disable no-function-outside-class -- pure enrichment helper, mirrors enrichResponsibilities\nfunction enrichClientNames(\n    entry: EnhancedGraph[string],\n    info: ProjectInfo,\n    workspaceRoot: string,\n    projectName: string,\n    serviceNames: Map<string, string>,\n    problems: string[]\n): void {\n    const serviceResolution = resolveServiceName(info, workspaceRoot);\n    if (serviceResolution.problem !== null) {\n        problems.push(serviceResolution.problem);\n    } else if (serviceResolution.serviceName !== null) {\n        entry.serviceName = serviceResolution.serviceName;\n        serviceNames.set(projectName, serviceResolution.serviceName);\n    }\n\n    // Consumed by the runtime graph's target resolution (runtime-graph.ts), between the call-site\n    // literal and the fan-out fallback.\n    const callsResolution = resolveCallsService(info, workspaceRoot);\n    if (callsResolution.problem !== null) {\n        problems.push(callsResolution.problem);\n    } else if (callsResolution.callsService !== null) {\n        entry.callsService = callsResolution.callsService;\n    }\n}\n\nfunction enrichResponsibilities(\n    entry: EnhancedGraph[string],\n    info: ProjectInfo,\n    workspaceRoot: string,\n    problems: string[]\n): void {\n    const responsibilitiesFile = toRepoRelative(info.root, RESPONSIBILITIES_FILE_NAME);\n    entry.responsibilitiesFile = responsibilitiesFile;\n\n    const absolutePath = path.join(workspaceRoot, info.root, RESPONSIBILITIES_FILE_NAME);\n    if (!fs.existsSync(absolutePath)) {\n        problems.push(\n            `${info.name}: missing required ${responsibilitiesFile} — create it with a heading, ` +\n                `one short summary paragraph, then the full responsibilities of the module`\n        );\n        return;\n    }\n\n    const summary = extractShortDescription(fs.readFileSync(absolutePath, 'utf-8'));\n    const summaryProblem = validateShortDescription(summary, responsibilitiesFile);\n    if (summaryProblem !== null) {\n        problems.push(`${info.name}: ${summaryProblem}`);\n        return;\n    }\n    entry.shortDescription = summary;\n}\n\n/**\n * Repo-relative path with forward slashes (stable across platforms in the\n * committed JSON).\n */\nfunction toRepoRelative(projectRoot: string, fileName: string): string {\n    return [projectRoot.replace(/\\\\/g, '/').replace(/\\/+$/, ''), fileName].join('/');\n}\n\n/**\n * True when the project has a REAL generated DI design — a committed design.json\n * whose `designs[]` is non-empty (i.e. it has ≥1 @DocumentDesign root).\n *\n * MISSING, empty-`designs[]`, and unparseable all read as \"no design\", and that\n * equivalence is load-bearing rather than incidental: di-graph-generate writes NO\n * file for a project without a design root (and reaps a stale one), so \"absent\"\n * is now the normal state for every plain lib and legacy service. Repos that have\n * not rebuilt since still carry `{ designs: [] }` files. Either way the box's node\n * menu must offer no \"View Design\" item. See design-file-emission.spec.ts.\n */\nfunction hasGeneratedDesign(workspaceRoot: string, projectRoot: string): boolean {\n    const designPath = path.join(workspaceRoot, projectRoot, 'design.json');\n    if (!fs.existsSync(designPath)) return false;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const parsed = JSON.parse(fs.readFileSync(designPath, 'utf-8'));\n        return Array.isArray(parsed.designs) && parsed.designs.length > 0;\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.warn(`⚠️  Skipping unparseable ${designPath}: ${error.message}`);\n        return false;\n    }\n}\n"]}
+{"version":3,"file":"graph-metadata.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-metadata.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Metadata Enrichment\n *\n * Fills the AI-oriented fields on each architecture/dependencies.json entry:\n *   framework            — from `framework:<x>` nx tag or package.json inference\n *   serviceName          — from project.json metadata.webpieces.serviceName; the\n *                          name clients address this app by at runtime\n *   shortDescription     — first paragraph of the project's responsibilities.md\n *   responsibilitiesFile — repo-relative path to the required responsibilities.md\n *   designFile           — repo-relative path to the generated DI design.json\n *\n * Validation is aggregated: ALL problems across ALL projects are collected and\n * thrown as one MetadataValidationError so a repo adopting this sees the full\n * seeding list in a single run. Callers must enrich BEFORE writing any file so\n * a failed run never clobbers dependencies.json.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { createProjectGraphAsync } from '@nx/devkit';\nimport type { EnhancedGraph, GraphEntry } from './graph-sorter';\nimport { ProjectInfo } from './project-info';\nimport { resolveFramework } from './framework-resolver';\nimport { resolveRole } from './role-resolver';\nimport { resolveDrawOnGraph } from './draw-on-graph-resolver';\nimport { resolveCutLegacyCycles } from './cut-legacy-cycle-resolver';\nimport { resolveRuntimeParticipant } from './runtime-participant-resolver';\nimport { resolveCallsService, resolveServiceName, validateUniqueServiceNames } from './service-name-resolver';\nimport { extractShortDescription, validateShortDescription } from './responsibilities';\nimport { toError } from '../toError';\n\nexport const RESPONSIBILITIES_FILE_NAME = 'responsibilities.md';\n\n/**\n * Thrown when one or more projects fail metadata validation (missing/invalid\n * responsibilities.md, bad framework tags, ...). Executors catch this to point\n * AI at the webpieces.responsibilities.md instructions template.\n */\nexport class MetadataValidationError extends Error {\n    constructor(public readonly problems: string[]) {\n        super(\n            `Architecture metadata validation failed (${problems.length} problem(s)):\\n` +\n                problems.map((problem: string) => `  - ${problem}`).join('\\n')\n        );\n        this.name = 'MetadataValidationError';\n    }\n}\n\n/**\n * Read per-project root + tags from nx's project graph.\n */\nexport async function collectProjectInfo(): Promise<Map<string, ProjectInfo>> {\n    const projectGraph = await createProjectGraphAsync();\n    const infos = new Map<string, ProjectInfo>();\n    for (const [name, node] of Object.entries(projectGraph.nodes)) {\n        infos.set(name, new ProjectInfo(name, node.data.root, node.data.tags ?? []));\n    }\n    return infos;\n}\n\n/**\n * Enrich every graph entry in place with framework, shortDescription,\n * responsibilitiesFile and designFile. Throws MetadataValidationError listing\n * every problem when any project fails validation.\n */\nexport function enrichGraph(\n    graph: EnhancedGraph,\n    infos: Map<string, ProjectInfo>,\n    workspaceRoot: string\n): void {\n    const problems: string[] = [];\n    // project -> declared serviceName, collected so duplicates can be reported across the workspace.\n    const serviceNames = new Map<string, string>();\n\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const info = infos.get(projectName);\n        if (!info) {\n            problems.push(`${projectName}: not found in nx project graph`);\n            continue;\n        }\n\n        enrichDeclarations(entry, info, workspaceRoot, problems);\n        enrichClientNames(entry, info, workspaceRoot, projectName, serviceNames, problems);\n        enrichResponsibilities(entry, info, workspaceRoot, problems);\n\n        // Set designFile ONLY when the project has a REAL generated design (a\n        // non-empty `designs[]`), i.e. it has a @DocumentDesign root. A project\n        // without one has NO design.json at all (di-graph-generate stopped writing\n        // empty ones and reaps stale ones), and legacy repos may still carry an\n        // empty `{ designs: [] }` until their next build — both must read the same\n        // way, and neither gets a \"View Design\" item on its node menu in the arch\n        // viz (designLinks keys off designFile). See graph-visualizer.ts.\n        if (hasGeneratedDesign(workspaceRoot, info.root)) {\n            entry.designFile = toRepoRelative(info.root, 'design.json');\n        }\n    }\n\n    validateUniqueServiceNames(serviceNames, problems);\n    validateLibraryTypesMatch(graph, problems);\n    validateRoleDependencies(graph, problems);\n\n    if (problems.length > 0) {\n        throw new MetadataValidationError(problems);\n    }\n}\n\n/**\n * The fields a project DECLARES about itself — its framework env set and role (nx tags), the\n * webpieces runtime packages it depends on (package.json), and whether it opts out of the drawings\n * (nx tag). Grouped because they share a shape: resolve, record the problem, or write the field.\n *\n * Distinct from enrichResponsibilities/designFile, which read generated or hand-written FILES.\n */\n// webpieces-disable no-function-outside-class -- enrichGraph step helper, matching enrichClientNames/enrichResponsibilities in this file\nfunction enrichDeclarations(\n    entry: GraphEntry,\n    info: ProjectInfo,\n    workspaceRoot: string,\n    problems: string[]\n): void {\n    const resolution = resolveFramework(info, workspaceRoot);\n    if (resolution.problem !== null) {\n        problems.push(resolution.problem);\n    } else if (resolution.frameworks !== null) {\n        entry.framework = resolution.frameworks;\n    }\n\n    const roleResolution = resolveRole(info);\n    if (roleResolution.problem !== null) {\n        problems.push(roleResolution.problem);\n    } else if (roleResolution.role !== null) {\n        entry.role = roleResolution.role;\n    }\n\n    // Only persist when the project declares at least one — a repo full of\n    // \"webpiecesRuntime\": [] lines would be noise, and absence already means \"declares none\".\n    const participantResolution = resolveRuntimeParticipant(info, workspaceRoot);\n    if (participantResolution.problem !== null) {\n        problems.push(participantResolution.problem);\n    } else if (participantResolution.markers !== null && participantResolution.markers.length > 0) {\n        entry.webpiecesRuntime = participantResolution.markers;\n    }\n\n    // Only persist the field when hidden (false); drawn projects (the\n    // default) stay clean in dependencies.json with no drawOnGraph line.\n    const drawResolution = resolveDrawOnGraph(info);\n    if (drawResolution.problem !== null) {\n        problems.push(drawResolution.problem);\n    } else if (drawResolution.drawOnGraph === false) {\n        entry.drawOnGraph = false;\n    }\n\n    // Only persist when the project actually cuts an edge — absence is the normal state, and a repo\n    // full of \"cutLegacyCycle\": [] lines would bury the ones that mean something.\n    const cutResolution = resolveCutLegacyCycles(info);\n    if (cutResolution.problem !== null) {\n        problems.push(cutResolution.problem);\n    } else if (cutResolution.targets !== null && cutResolution.targets.length > 0) {\n        entry.cutLegacyCycle = cutResolution.targets;\n    }\n}\n\n/**\n * Roles that are terminal APPS — nothing may depend on them. A server, a\n * non-HTTP `app`, or a client is a top-level runnable; being depended upon means\n * it is really a library and should be retagged `role:lib`/`role:designed-lib`.\n */\nexport const APP_ROLES: ReadonlyArray<string> = ['server', 'app', 'client'];\n\n/**\n * Compatibility lattice — the \"up-set\" of each atomic env is the env itself\n * PLUS every ancestor it can legally consume code from (specialization edges\n * child → parent: react → browser, angular → browser, express → node). A\n * consumer promising env `c` can be satisfied by any dependency env in `up(c)`.\n */\nexport const ENV_UP_SETS: Readonly<Record<string, ReadonlyArray<string>>> = {\n    react: ['react', 'browser'],\n    angular: ['angular', 'browser'],\n    browser: ['browser'],\n    express: ['express', 'node'],\n    node: ['node'],\n};\n\n/** The up-set of an env (env itself + ancestors); unknown envs map to just themselves. */\nfunction upSet(env: string): ReadonlyArray<string> {\n    return ENV_UP_SETS[env] ?? [env];\n}\n\n/**\n * `library-types-match-client` rule.\n *\n * A project's `framework` field is its libType — the SET of runtime\n * environments it is validated to run in (browser | react | angular | node |\n * express). For a dependency edge Consumer C → Library L, the edge is LEGAL iff\n * for EVERY env `c` in C's set, up(c) ∩ L's set ≠ ∅ — i.e. every environment\n * the consumer promises to run in can be satisfied by the dependency. This keeps\n * an express app from depending on a browser-only lib, and lets a `browser+node`\n * lib be consumed by both react and express projects. Every violation is\n * appended to `problems` so `arch:generate` fails with the full list.\n */\nexport function validateLibraryTypesMatch(graph: EnhancedGraph, problems: string[]): void {\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const fromSet = entry.framework;\n        if (fromSet === undefined) continue; // framework resolution already flagged this project\n\n        for (const dep of entry.dependsOn) {\n            const depEntry = graph[dep];\n            const toSet = depEntry?.framework;\n            if (toSet === undefined) continue;\n\n            const unsatisfied = fromSet.filter(\n                (env: string) => !upSet(env).some((up: string) => toSet.includes(up))\n            );\n            if (unsatisfied.length === 0) continue;\n\n            problems.push(\n                `library-types-match-client: '${projectName}' [${fromSet.join(', ')}] must not depend on ` +\n                    `'${dep}' [${toSet.join(', ')}] — the consumer env(s) ${unsatisfied.join(', ')} cannot be ` +\n                    `satisfied by the dependency (each consumer env must resolve to itself or an ancestor it ` +\n                    `consumes from: react/angular→browser, express→node). Widen '${dep}' framework tags or ` +\n                    `remove the dependency.`\n            );\n        }\n    }\n}\n\n/**\n * `role-dependency` rule.\n *\n * A project's `role` is its function (server | designed-lib | lib | client).\n * Apps are terminal — libraries and clients consume them, never the reverse:\n *   - a `client` is fully terminal: NOTHING may depend on it.\n *   - a `server` may only be depended upon by another `server` — the one\n *     legitimate case is a server-side orchestrator/e2e harness that boots\n *     other servers. A `lib`/`designed-lib`/`client` depending on a `server`\n *     inverts the dependency direction and is a violation.\n *   - a `bundle` is the one role permitted to depend on ANY app: it aggregates\n *     several apps into one distributable (e.g. an nx plugin re-exposing multiple\n *     tooling apps), so a `bundle → app` edge is legitimate, not inverted.\n */\nexport function validateRoleDependencies(graph: EnhancedGraph, problems: string[]): void {\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const fromRole = entry.role;\n        for (const dep of entry.dependsOn) {\n            const toRole = graph[dep]?.role;\n            if (toRole === undefined) continue; // role resolution already flagged this project\n            if (!APP_ROLES.includes(toRole)) continue;\n            // A server may orchestrate/boot other servers (e.g. an e2e harness).\n            if (toRole === 'server' && fromRole === 'server') continue;\n            // A bundle aggregates apps — it may depend on any app role.\n            if (fromRole === 'bundle') continue;\n\n            const why =\n                toRole === 'client'\n                    ? `a 'client' app is terminal and may never be depended upon`\n                    : `a 'server' may only be depended upon by another 'server' (an orchestrator/e2e harness)`;\n            problems.push(\n                `role-dependency: '${projectName}' (role:${fromRole ?? 'none'}) must not depend on ` +\n                    `'${dep}' (role:${toRole}) — ${why}. Retag '${dep}' role:lib/role:designed-lib if it ` +\n                    `is actually a library, or remove the dependency.`\n            );\n        }\n    }\n}\n\n/**\n * Fill the two symmetric client-addressing fields — `serviceName` (the name clients address THIS app\n * by) and `callsService` (the name THIS app's clients call when no literal ClientConfig sits at the\n * call site). Both are declared in project.json, never derived (see service-name-resolver.ts).\n */\n// webpieces-disable no-function-outside-class -- pure enrichment helper, mirrors enrichResponsibilities\nfunction enrichClientNames(\n    entry: EnhancedGraph[string],\n    info: ProjectInfo,\n    workspaceRoot: string,\n    projectName: string,\n    serviceNames: Map<string, string>,\n    problems: string[]\n): void {\n    const serviceResolution = resolveServiceName(info, workspaceRoot);\n    if (serviceResolution.problem !== null) {\n        problems.push(serviceResolution.problem);\n    } else if (serviceResolution.serviceName !== null) {\n        entry.serviceName = serviceResolution.serviceName;\n        serviceNames.set(projectName, serviceResolution.serviceName);\n    }\n\n    // Consumed by the runtime graph's target resolution (runtime-graph.ts), between the call-site\n    // literal and the fan-out fallback.\n    const callsResolution = resolveCallsService(info, workspaceRoot);\n    if (callsResolution.problem !== null) {\n        problems.push(callsResolution.problem);\n    } else if (callsResolution.callsService !== null) {\n        entry.callsService = callsResolution.callsService;\n    }\n}\n\nfunction enrichResponsibilities(\n    entry: EnhancedGraph[string],\n    info: ProjectInfo,\n    workspaceRoot: string,\n    problems: string[]\n): void {\n    const responsibilitiesFile = toRepoRelative(info.root, RESPONSIBILITIES_FILE_NAME);\n    entry.responsibilitiesFile = responsibilitiesFile;\n\n    const absolutePath = path.join(workspaceRoot, info.root, RESPONSIBILITIES_FILE_NAME);\n    if (!fs.existsSync(absolutePath)) {\n        problems.push(\n            `${info.name}: missing required ${responsibilitiesFile} — create it with a heading, ` +\n                `one short summary paragraph, then the full responsibilities of the module`\n        );\n        return;\n    }\n\n    const summary = extractShortDescription(fs.readFileSync(absolutePath, 'utf-8'));\n    const summaryProblem = validateShortDescription(summary, responsibilitiesFile);\n    if (summaryProblem !== null) {\n        problems.push(`${info.name}: ${summaryProblem}`);\n        return;\n    }\n    entry.shortDescription = summary;\n}\n\n/**\n * Repo-relative path with forward slashes (stable across platforms in the\n * committed JSON).\n */\nfunction toRepoRelative(projectRoot: string, fileName: string): string {\n    return [projectRoot.replace(/\\\\/g, '/').replace(/\\/+$/, ''), fileName].join('/');\n}\n\n/**\n * True when the project has a REAL generated DI design — a committed design.json\n * whose `designs[]` is non-empty (i.e. it has ≥1 @DocumentDesign root).\n *\n * MISSING, empty-`designs[]`, and unparseable all read as \"no design\", and that\n * equivalence is load-bearing rather than incidental: di-graph-generate writes NO\n * file for a project without a design root (and reaps a stale one), so \"absent\"\n * is now the normal state for every plain lib and legacy service. Repos that have\n * not rebuilt since still carry `{ designs: [] }` files. Either way the box's node\n * menu must offer no \"View Design\" item. See design-file-emission.spec.ts.\n */\nfunction hasGeneratedDesign(workspaceRoot: string, projectRoot: string): boolean {\n    const designPath = path.join(workspaceRoot, projectRoot, 'design.json');\n    if (!fs.existsSync(designPath)) return false;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const parsed = JSON.parse(fs.readFileSync(designPath, 'utf-8'));\n        return Array.isArray(parsed.designs) && parsed.designs.length > 0;\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.warn(`⚠️  Skipping unparseable ${designPath}: ${error.message}`);\n        return false;\n    }\n}\n"]}

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

@@ -28,7 +28,7 @@ export interface GraphEntry {
     framework?: string[];
     role?: string;
     /**
-     * The name CLIENTS address this app by at runtime (`new ClientConfig('helper-fsdb', new DeployedServiceHost())`) — its
+     * The name CLIENTS address this app by at runtime (`new ClientConfig('helper-fsdb')`) — its
      * deployed service name, DECLARED in project.json as metadata.webpieces.serviceName. Absent for
      * anything nothing calls by name (libraries, browser apps). See service-name-resolver.ts.
      */
@@ -49,6 +49,13 @@ export interface GraphEntry {
      * Absent means drawn (the default). From the project's `drawOnGraph:` nx tag.
      */
     drawOnGraph?: boolean;
+    /**
+     * Target service names whose RUNTIME edge from this project is cut out of leveling and cycle
+     * detection, from this project's `cutLegacyCycle:<target>` nx tags. Per EDGE, not per project.
+     * An admission of legacy debt, never an approved pattern — see cut-legacy-cycle-resolver.ts.
+     * Absent (the overwhelmingly normal case) means this project cuts nothing.
+     */
+    cutLegacyCycle?: string[];
     shortDescription?: string;
     responsibilitiesFile?: string;
     designFile?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"graph-sorter.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-sorter.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AA8EH,4DAwCC;AASD,wDAgBC;AA5ID,iDAAsD;AAkEtD;;;;;;;;GAQG;AACH,SAAgB,wBAAwB,CAAC,KAA+B;IACpE,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEvC,OAAO,SAAS,CAAC,IAAI,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC;QACzC,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;YAChC,IAAI,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC;gBAAE,SAAS;YAErC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAClC,uEAAuE;YACvE,MAAM,mBAAmB,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YAEpE,IAAI,mBAAmB,EAAE,CAAC;gBACtB,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC/B,CAAC;QACL,CAAC;QAED,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,gFAAgF;YAChF,mFAAmF;YACnF,kFAAkF;YAClF,IAAI,mCAAoB,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC;YACrE,sFAAsF;YACtF,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAChF,MAAM,IAAI,KAAK,CACX,+EAA+E,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/G,CAAC;QAED,4DAA4D;QAC5D,YAAY,CAAC,IAAI,EAAE,CAAC;QACpB,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAE1B,oBAAoB;QACpB,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,sBAAsB,CAAC,KAA+B;IAClE,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,+DAA+D;IAC/D,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE;QACjC,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;YAC1B,6CAA6C;YAC7C,MAAM,CAAC,OAAO,CAAC,GAAG;gBACd,KAAK,EAAE,UAAU;gBACjB,SAAS,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;aAC3C,CAAC;QACN,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAClB,CAAC","sourcesContent":["/**\n * Graph Sorter\n *\n * Performs topological sorting on the dependency graph to:\n * 1. Detect circular dependencies (fails if cycle found)\n * 2. Assign level numbers to each project (level 0 = no deps, level 1 = depends on level 0, etc.)\n * 3. Group projects into layers for deterministic ordering\n */\n\nimport type { ProjectApiRelations } from './api-usage/api-relations';\nimport { ProjectCycleDetector } from './graph-cycles';\n\n/**\n * Graph entry with level metadata plus AI-oriented metadata filled in by\n * enrichGraph() (lib/graph-metadata.ts) before the graph is saved:\n *  - framework: the project's libType — the SET of runtime environments it is\n *    validated to run in, drawn from browser | react | angular | node | express\n *    (e.g. [\"browser\",\"node\"]); from its `framework:` nx tags (source of truth)\n *    or inferred from package.json deps\n *  - shortDescription: summary extracted from the project's responsibilities.md\n *  - responsibilitiesFile: repo-relative path to the FULL responsibilities doc\n *  - designFile: repo-relative path to the generated DI design.json (only for\n *    project.json projects)\n *  - apiRelations: for each api-lib in `dependsOn`, WHY the edge exists — the\n *    APIs this project implements (serves) and/or uses (calls), each with its\n *    transport (rpc | pubsub). Derived by scanning source (see api-usage/).\n */\nexport interface GraphEntry {\n    level: number;\n    dependsOn: string[];\n    framework?: string[];\n    role?: string;\n    /**\n     * The name CLIENTS address this app by at runtime (`new ClientConfig('helper-fsdb', new DeployedServiceHost())`) — its\n     * deployed service name, DECLARED in project.json as metadata.webpieces.serviceName. Absent for\n     * anything nothing calls by name (libraries, browser apps). See service-name-resolver.ts.\n     */\n    serviceName?: string;\n    /**\n     * The service(s) this project's clients call when the call site cannot carry a literal\n     * `ClientConfig` — the symmetric half of `serviceName`. DECLARED in project.json as\n     * metadata.webpieces.callsService, either a single service name (every untargeted `uses` aims\n     * there) or an `{ apiClassName: serviceName }` map (a client that calls several). Absent for a\n     * project that never calls anything, or one whose call sites all carry literals.\n     * See service-name-resolver.ts.\n     */\n    callsService?: string | Record<string, string>;\n    /**\n     * When false, the project is hidden from the rendered architecture graphs\n     * (its box AND every edge touching it are omitted from dependencies.html and\n     * the runtime graph). It stays in this JSON so the data view is complete.\n     * Absent means drawn (the default). From the project's `drawOnGraph:` nx tag.\n     */\n    drawOnGraph?: boolean;\n    shortDescription?: string;\n    responsibilitiesFile?: string;\n    designFile?: string;\n    apiRelations?: ProjectApiRelations;\n    /**\n     * The @webpieces runtime packages this project's OWN package.json declares — http-routing,\n     * http-server, http-client-node, http-client-browser, cloudtasks-client. Omitted when it\n     * declares none, so TOTAL absence across the file means the file predates this field and\n     * nothing is auto-hidden (see runtime-graph.ts). Core/util/logging packages are deliberately\n     * not markers; see runtime-participant-resolver.ts for why.\n     *\n     * The runtime graph ORs this over a node's library closure: a server whose whole webpieces\n     * stack comes from a shared bootstrap lib participates even though it declares nothing itself.\n     */\n    webpiecesRuntime?: string[];\n}\n\n/**\n * Enhanced graph format with level information\n */\nexport type EnhancedGraph = Record<string, GraphEntry>;\n\n/**\n * Compute topological layers for dependency graph using Kahn's algorithm\n *\n * Projects are grouped into layers where each layer only depends on previous layers.\n * Throws an error if a circular dependency is detected.\n *\n * @param graph - Dependency graph { project: [deps] }\n * @returns Array of layers, each containing sorted project names\n */\nexport function computeTopologicalLayers(graph: Record<string, string[]>): string[][] {\n    const layers: string[][] = [];\n    const processed = new Set<string>();\n    const allProjects = Object.keys(graph);\n\n    while (processed.size < allProjects.length) {\n        const currentLayer: string[] = [];\n\n        for (const project of allProjects) {\n            if (processed.has(project)) continue;\n\n            const deps = graph[project] || [];\n            // Check if all dependencies are in previous layers (already processed)\n            const allDepsInPrevLayers = deps.every((dep) => processed.has(dep));\n\n            if (allDepsInPrevLayers) {\n                currentLayer.push(project);\n            }\n        }\n\n        if (currentLayer.length === 0) {\n            // No progress made = circular dependency. ProjectCycleDetector is the ONE cycle\n            // implementation in this package — it names every chain, in project keys, with the\n            // fix — so this reports through it rather than keeping a second, weaker DFS here.\n            new ProjectCycleDetector().assertAcyclic(graph, 'the project graph');\n            // Unreachable: Kahn only stalls on a cycle, and the assert above throws on every one.\n            const remaining = allProjects.filter((p: string): boolean => !processed.has(p));\n            throw new Error(\n                `Topological sort stalled with no cycle to report — projects left unlayered: ${remaining.join(', ')}`);\n        }\n\n        // Sort alphabetically within layer for deterministic output\n        currentLayer.sort();\n        layers.push(currentLayer);\n\n        // Mark as processed\n        currentLayer.forEach((p) => processed.add(p));\n    }\n\n    return layers;\n}\n\n/**\n * Sort graph in topological order with alphabetical sorting within layers\n * Returns enhanced format with level metadata\n *\n * @param graph - Unsorted dependency graph { project: [deps] }\n * @returns Sorted graph with level metadata { project: { level: number, dependsOn: [deps] } }\n */\nexport function sortGraphTopologically(graph: Record<string, string[]>): EnhancedGraph {\n    const layers = computeTopologicalLayers(graph);\n    const result: EnhancedGraph = {};\n\n    // Add projects layer by layer (dependencies before dependents)\n    layers.forEach((layer, levelIndex) => {\n        for (const project of layer) {\n            // Already sorted alphabetically within layer\n            result[project] = {\n                level: levelIndex,\n                dependsOn: (graph[project] || []).sort(),\n            };\n        }\n    });\n\n    return result;\n}\n"]}
+{"version":3,"file":"graph-sorter.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-sorter.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAqFH,4DAwCC;AASD,wDAgBC;AAnJD,iDAAsD;AAyEtD;;;;;;;;GAQG;AACH,SAAgB,wBAAwB,CAAC,KAA+B;IACpE,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEvC,OAAO,SAAS,CAAC,IAAI,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC;QACzC,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;YAChC,IAAI,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC;gBAAE,SAAS;YAErC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAClC,uEAAuE;YACvE,MAAM,mBAAmB,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YAEpE,IAAI,mBAAmB,EAAE,CAAC;gBACtB,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC/B,CAAC;QACL,CAAC;QAED,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,gFAAgF;YAChF,mFAAmF;YACnF,kFAAkF;YAClF,IAAI,mCAAoB,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC;YACrE,sFAAsF;YACtF,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAChF,MAAM,IAAI,KAAK,CACX,+EAA+E,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/G,CAAC;QAED,4DAA4D;QAC5D,YAAY,CAAC,IAAI,EAAE,CAAC;QACpB,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAE1B,oBAAoB;QACpB,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,sBAAsB,CAAC,KAA+B;IAClE,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,+DAA+D;IAC/D,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE;QACjC,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;YAC1B,6CAA6C;YAC7C,MAAM,CAAC,OAAO,CAAC,GAAG;gBACd,KAAK,EAAE,UAAU;gBACjB,SAAS,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;aAC3C,CAAC;QACN,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAClB,CAAC","sourcesContent":["/**\n * Graph Sorter\n *\n * Performs topological sorting on the dependency graph to:\n * 1. Detect circular dependencies (fails if cycle found)\n * 2. Assign level numbers to each project (level 0 = no deps, level 1 = depends on level 0, etc.)\n * 3. Group projects into layers for deterministic ordering\n */\n\nimport type { ProjectApiRelations } from './api-usage/api-relations';\nimport { ProjectCycleDetector } from './graph-cycles';\n\n/**\n * Graph entry with level metadata plus AI-oriented metadata filled in by\n * enrichGraph() (lib/graph-metadata.ts) before the graph is saved:\n *  - framework: the project's libType — the SET of runtime environments it is\n *    validated to run in, drawn from browser | react | angular | node | express\n *    (e.g. [\"browser\",\"node\"]); from its `framework:` nx tags (source of truth)\n *    or inferred from package.json deps\n *  - shortDescription: summary extracted from the project's responsibilities.md\n *  - responsibilitiesFile: repo-relative path to the FULL responsibilities doc\n *  - designFile: repo-relative path to the generated DI design.json (only for\n *    project.json projects)\n *  - apiRelations: for each api-lib in `dependsOn`, WHY the edge exists — the\n *    APIs this project implements (serves) and/or uses (calls), each with its\n *    transport (rpc | pubsub). Derived by scanning source (see api-usage/).\n */\nexport interface GraphEntry {\n    level: number;\n    dependsOn: string[];\n    framework?: string[];\n    role?: string;\n    /**\n     * The name CLIENTS address this app by at runtime (`new ClientConfig('helper-fsdb')`) — its\n     * deployed service name, DECLARED in project.json as metadata.webpieces.serviceName. Absent for\n     * anything nothing calls by name (libraries, browser apps). See service-name-resolver.ts.\n     */\n    serviceName?: string;\n    /**\n     * The service(s) this project's clients call when the call site cannot carry a literal\n     * `ClientConfig` — the symmetric half of `serviceName`. DECLARED in project.json as\n     * metadata.webpieces.callsService, either a single service name (every untargeted `uses` aims\n     * there) or an `{ apiClassName: serviceName }` map (a client that calls several). Absent for a\n     * project that never calls anything, or one whose call sites all carry literals.\n     * See service-name-resolver.ts.\n     */\n    callsService?: string | Record<string, string>;\n    /**\n     * When false, the project is hidden from the rendered architecture graphs\n     * (its box AND every edge touching it are omitted from dependencies.html and\n     * the runtime graph). It stays in this JSON so the data view is complete.\n     * Absent means drawn (the default). From the project's `drawOnGraph:` nx tag.\n     */\n    drawOnGraph?: boolean;\n    /**\n     * Target service names whose RUNTIME edge from this project is cut out of leveling and cycle\n     * detection, from this project's `cutLegacyCycle:<target>` nx tags. Per EDGE, not per project.\n     * An admission of legacy debt, never an approved pattern — see cut-legacy-cycle-resolver.ts.\n     * Absent (the overwhelmingly normal case) means this project cuts nothing.\n     */\n    cutLegacyCycle?: string[];\n    shortDescription?: string;\n    responsibilitiesFile?: string;\n    designFile?: string;\n    apiRelations?: ProjectApiRelations;\n    /**\n     * The @webpieces runtime packages this project's OWN package.json declares — http-routing,\n     * http-server, http-client-node, http-client-browser, cloudtasks-client. Omitted when it\n     * declares none, so TOTAL absence across the file means the file predates this field and\n     * nothing is auto-hidden (see runtime-graph.ts). Core/util/logging packages are deliberately\n     * not markers; see runtime-participant-resolver.ts for why.\n     *\n     * The runtime graph ORs this over a node's library closure: a server whose whole webpieces\n     * stack comes from a shared bootstrap lib participates even though it declares nothing itself.\n     */\n    webpiecesRuntime?: string[];\n}\n\n/**\n * Enhanced graph format with level information\n */\nexport type EnhancedGraph = Record<string, GraphEntry>;\n\n/**\n * Compute topological layers for dependency graph using Kahn's algorithm\n *\n * Projects are grouped into layers where each layer only depends on previous layers.\n * Throws an error if a circular dependency is detected.\n *\n * @param graph - Dependency graph { project: [deps] }\n * @returns Array of layers, each containing sorted project names\n */\nexport function computeTopologicalLayers(graph: Record<string, string[]>): string[][] {\n    const layers: string[][] = [];\n    const processed = new Set<string>();\n    const allProjects = Object.keys(graph);\n\n    while (processed.size < allProjects.length) {\n        const currentLayer: string[] = [];\n\n        for (const project of allProjects) {\n            if (processed.has(project)) continue;\n\n            const deps = graph[project] || [];\n            // Check if all dependencies are in previous layers (already processed)\n            const allDepsInPrevLayers = deps.every((dep) => processed.has(dep));\n\n            if (allDepsInPrevLayers) {\n                currentLayer.push(project);\n            }\n        }\n\n        if (currentLayer.length === 0) {\n            // No progress made = circular dependency. ProjectCycleDetector is the ONE cycle\n            // implementation in this package — it names every chain, in project keys, with the\n            // fix — so this reports through it rather than keeping a second, weaker DFS here.\n            new ProjectCycleDetector().assertAcyclic(graph, 'the project graph');\n            // Unreachable: Kahn only stalls on a cycle, and the assert above throws on every one.\n            const remaining = allProjects.filter((p: string): boolean => !processed.has(p));\n            throw new Error(\n                `Topological sort stalled with no cycle to report — projects left unlayered: ${remaining.join(', ')}`);\n        }\n\n        // Sort alphabetically within layer for deterministic output\n        currentLayer.sort();\n        layers.push(currentLayer);\n\n        // Mark as processed\n        currentLayer.forEach((p) => processed.add(p));\n    }\n\n    return layers;\n}\n\n/**\n * Sort graph in topological order with alphabetical sorting within layers\n * Returns enhanced format with level metadata\n *\n * @param graph - Unsorted dependency graph { project: [deps] }\n * @returns Sorted graph with level metadata { project: { level: number, dependsOn: [deps] } }\n */\nexport function sortGraphTopologically(graph: Record<string, string[]>): EnhancedGraph {\n    const layers = computeTopologicalLayers(graph);\n    const result: EnhancedGraph = {};\n\n    // Add projects layer by layer (dependencies before dependents)\n    layers.forEach((layer, levelIndex) => {\n        for (const project of layer) {\n            // Already sorted alphabetically within layer\n            result[project] = {\n                level: levelIndex,\n                dependsOn: (graph[project] || []).sort(),\n            };\n        }\n    });\n\n    return result;\n}\n"]}

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

@@ -8,23 +8,16 @@
  *     "mode": "ON",                          // "OFF" disables the whole feature
  *     "turnOffRuleUntilEpoch": 0,            // whole-rule punt (epoch seconds)
  *     "turnOffRuleWhileOnBranch": null,      // whole-rule punt while on a named branch
- *     "allowedCycles": [ { "services": ["a","b"], "reason": "...", "until": 1771931925 } ],
  *     "showExternalNodes": true,              // draw firestore/gmail/... as terminal nodes
  *     "externalApiPaths": ["libraries/apis/external/**"]  // where those vendor contracts live
  *   }
  */
 import { SkipRuleResult } from '@webpieces/rules-config';
 export declare const RUNTIME_RULE_NAME = "runtime-architecture";
-export interface AllowedCycle {
-    services: string[];
-    reason?: string;
-    until?: number;
-}
 export interface RuntimeRuleConfig {
     off: boolean;
     turnOffRuleUntilEpoch?: number;
     turnOffRuleWhileOnBranch?: string;
-    allowedCycles: AllowedCycle[];
     /** Render the dashed external terminal nodes in the runtime viz (default true). */
     showExternalNodes: boolean;
     /**

package/src/lib/runtime-config.js

@@ -9,7 +9,6 @@
  *     "mode": "ON",                          // "OFF" disables the whole feature
  *     "turnOffRuleUntilEpoch": 0,            // whole-rule punt (epoch seconds)
  *     "turnOffRuleWhileOnBranch": null,      // whole-rule punt while on a named branch
- *     "allowedCycles": [ { "services": ["a","b"], "reason": "...", "until": 1771931925 } ],
  *     "showExternalNodes": true,              // draw firestore/gmail/... as terminal nodes
  *     "externalApiPaths": ["libraries/apis/external/**"]  // where those vendor contracts live
  *   }
@@ -22,9 +21,6 @@ exports.isGraceActive = isGraceActive;
 exports.epochDate = epochDate;
 const rules_config_1 = require("@webpieces/rules-config");
 exports.RUNTIME_RULE_NAME = 'runtime-architecture';
-function isUsableCycle(cycle) {
-    return Array.isArray(cycle.services) && cycle.services.length > 0;
-}
 /** Load the runtime-architecture rule config (with safe defaults). */
 function loadRuntimeConfig(workspaceRoot) {
     const shared = (0, rules_config_1.loadAndValidate)(workspaceRoot).resolved;
@@ -36,7 +32,6 @@ function loadRuntimeConfig(workspaceRoot) {
         // turnOffRuleWhileOnBranch is required-but-NULLABLE in the config ("null" = always on), so a
         // non-string (null) collapses to undefined, which shouldSkipRule treats as "no branch scoping".
         turnOffRuleWhileOnBranch: typeof raw.turnOffRuleWhileOnBranch === 'string' ? raw.turnOffRuleWhileOnBranch : undefined,
-        allowedCycles: Array.isArray(raw.allowedCycles) ? raw.allowedCycles.filter(isUsableCycle) : [],
         // Opt-OUT: the external systems are the ones that page you at 3am, so they are drawn unless
         // a repo explicitly says its external surface is too noisy to be useful.
         showExternalNodes: raw.showExternalNodes !== false,

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

@@ -1 +1 @@
-{"version":3,"file":"runtime-config.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AA4CH,8CAsBC;AAQD,8CAEC;AAMD,sCAGC;AAGD,8BAEC;AAxFD,0DAA0F;AAE7E,QAAA,iBAAiB,GAAG,sBAAsB,CAAC;AAmCxD,SAAS,aAAa,CAAC,KAAmB;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACtE,CAAC;AAED,sEAAsE;AACtE,SAAgB,iBAAiB,CAAC,aAAqB;IACnD,MAAM,MAAM,GAAG,IAAA,8BAAe,EAAC,aAAa,CAAC,CAAC,QAAQ,CAAC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,yBAAiB,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAmB,CAAC;IACpD,OAAO;QACH,GAAG,EAAE,IAAI,EAAE,KAAK,IAAI,KAAK;QACzB,qBAAqB,EACjB,OAAO,GAAG,CAAC,qBAAqB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAC,SAAS;QACzF,6FAA6F;QAC7F,gGAAgG;QAChG,wBAAwB,EACpB,OAAO,GAAG,CAAC,wBAAwB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS;QAC/F,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE;QAC9F,4FAA4F;QAC5F,yEAAyE;QACzE,iBAAiB,EAAE,GAAG,CAAC,iBAAiB,KAAK,KAAK;QAClD,0FAA0F;QAC1F,uEAAuE;QACvE,gBAAgB,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;YACjD,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,KAAa,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;YAC/F,CAAC,CAAC,EAAE;KACX,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,MAAyB;IACvD,OAAO,IAAA,6BAAc,EAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,wBAAwB,CAAC,CAAC;AACzF,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,KAAyB;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,KAAK,CAAC;AACrC,CAAC;AAED,wDAAwD;AACxD,SAAgB,SAAS,CAAC,KAAa;IACnC,OAAO,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["/**\n * Runtime Config\n *\n * Loads the `runtime-architecture` rule from webpieces.config.json and exposes\n * typed accessors shared by the generate + validate + visualize executors.\n *\n *   \"runtime-architecture\": {\n *     \"mode\": \"ON\",                          // \"OFF\" disables the whole feature\n *     \"turnOffRuleUntilEpoch\": 0,            // whole-rule punt (epoch seconds)\n *     \"turnOffRuleWhileOnBranch\": null,      // whole-rule punt while on a named branch\n *     \"allowedCycles\": [ { \"services\": [\"a\",\"b\"], \"reason\": \"...\", \"until\": 1771931925 } ],\n *     \"showExternalNodes\": true,              // draw firestore/gmail/... as terminal nodes\n *     \"externalApiPaths\": [\"libraries/apis/external/**\"]  // where those vendor contracts live\n *   }\n */\n\nimport { loadAndValidate, shouldSkipRule, SkipRuleResult } from '@webpieces/rules-config';\n\nexport const RUNTIME_RULE_NAME = 'runtime-architecture';\n\nexport interface AllowedCycle {\n    services: string[];\n    reason?: string;\n    until?: number;\n}\n\nexport interface RuntimeRuleConfig {\n    off: boolean;\n    turnOffRuleUntilEpoch?: number;\n    turnOffRuleWhileOnBranch?: string;\n    allowedCycles: AllowedCycle[];\n    /** Render the dashed external terminal nodes in the runtime viz (default true). */\n    showExternalNodes: boolean;\n    /**\n     * Globs of project roots whose exported `*Api` types are contracts for systems OUTSIDE this repo.\n     * Empty (the default) means the scan looks for no vendor seams at all.\n     */\n    externalApiPaths: string[];\n}\n\n/**\n * Typed view of the opaque webpieces.config.json option bag for this rule. The\n * config is trusted (it is the workspace's own file), so we cast once here and\n * defensively narrow arrays/numbers rather than threading `unknown` everywhere.\n */\ninterface RuntimeRuleRaw {\n    turnOffRuleUntilEpoch?: number;\n    turnOffRuleWhileOnBranch?: string | null;\n    allowedCycles?: AllowedCycle[];\n    showExternalNodes?: boolean;\n    externalApiPaths?: string[];\n}\n\nfunction isUsableCycle(cycle: AllowedCycle): boolean {\n    return Array.isArray(cycle.services) && cycle.services.length > 0;\n}\n\n/** Load the runtime-architecture rule config (with safe defaults). */\nexport function loadRuntimeConfig(workspaceRoot: string): RuntimeRuleConfig {\n    const shared = loadAndValidate(workspaceRoot).resolved;\n    const rule = shared.rules.get(RUNTIME_RULE_NAME);\n    const raw = (rule?.options ?? {}) as RuntimeRuleRaw;\n    return {\n        off: rule?.isOff ?? false,\n        turnOffRuleUntilEpoch:\n            typeof raw.turnOffRuleUntilEpoch === 'number' ? raw.turnOffRuleUntilEpoch : undefined,\n        // turnOffRuleWhileOnBranch is required-but-NULLABLE in the config (\"null\" = always on), so a\n        // non-string (null) collapses to undefined, which shouldSkipRule treats as \"no branch scoping\".\n        turnOffRuleWhileOnBranch:\n            typeof raw.turnOffRuleWhileOnBranch === 'string' ? raw.turnOffRuleWhileOnBranch : undefined,\n        allowedCycles: Array.isArray(raw.allowedCycles) ? raw.allowedCycles.filter(isUsableCycle) : [],\n        // Opt-OUT: the external systems are the ones that page you at 3am, so they are drawn unless\n        // a repo explicitly says its external surface is too noisy to be useful.\n        showExternalNodes: raw.showExternalNodes !== false,\n        // Opt-IN: there is no safe guess for where a repo keeps its vendor wrappers, and guessing\n        // wrong would classify ordinary libraries as systems outside the repo.\n        externalApiPaths: Array.isArray(raw.externalApiPaths)\n            ? raw.externalApiPaths.filter((entry: string) => typeof entry === 'string' && entry.length > 0)\n            : [],\n    };\n}\n\n/**\n * Whole-rule report-only window honoring BOTH escape hatches: skip while on the\n * named branch (turnOffRuleWhileOnBranch) or until the epoch passes\n * (turnOffRuleUntilEpoch). When `.skip` is true, problems are reported but\n * the build is not failed.\n */\nexport function runtimeReportOnly(config: RuntimeRuleConfig): SkipRuleResult {\n    return shouldSkipRule(config.turnOffRuleUntilEpoch, config.turnOffRuleWhileOnBranch);\n}\n\n/**\n * Whole-rule grace window: while now < epoch, failures are reported but do not\n * fail the build (warn). Mirrors the other webpieces rules.\n */\nexport function isGraceActive(epoch: number | undefined): boolean {\n    if (epoch === undefined) return false;\n    return Date.now() / 1000 < epoch;\n}\n\n/** Format the epoch as an ISO date for log messages. */\nexport function epochDate(epoch: number): string {\n    return new Date(epoch * 1000).toISOString().split('T')[0];\n}\n"]}
+{"version":3,"file":"runtime-config.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAgCH,8CAqBC;AAQD,8CAEC;AAMD,sCAGC;AAGD,8BAEC;AA3ED,0DAA0F;AAE7E,QAAA,iBAAiB,GAAG,sBAAsB,CAAC;AA2BxD,sEAAsE;AACtE,SAAgB,iBAAiB,CAAC,aAAqB;IACnD,MAAM,MAAM,GAAG,IAAA,8BAAe,EAAC,aAAa,CAAC,CAAC,QAAQ,CAAC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,yBAAiB,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAmB,CAAC;IACpD,OAAO;QACH,GAAG,EAAE,IAAI,EAAE,KAAK,IAAI,KAAK;QACzB,qBAAqB,EACjB,OAAO,GAAG,CAAC,qBAAqB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAC,SAAS;QACzF,6FAA6F;QAC7F,gGAAgG;QAChG,wBAAwB,EACpB,OAAO,GAAG,CAAC,wBAAwB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS;QAC/F,4FAA4F;QAC5F,yEAAyE;QACzE,iBAAiB,EAAE,GAAG,CAAC,iBAAiB,KAAK,KAAK;QAClD,0FAA0F;QAC1F,uEAAuE;QACvE,gBAAgB,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;YACjD,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,KAAa,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;YAC/F,CAAC,CAAC,EAAE;KACX,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,MAAyB;IACvD,OAAO,IAAA,6BAAc,EAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,wBAAwB,CAAC,CAAC;AACzF,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,KAAyB;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,KAAK,CAAC;AACrC,CAAC;AAED,wDAAwD;AACxD,SAAgB,SAAS,CAAC,KAAa;IACnC,OAAO,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["/**\n * Runtime Config\n *\n * Loads the `runtime-architecture` rule from webpieces.config.json and exposes\n * typed accessors shared by the generate + validate + visualize executors.\n *\n *   \"runtime-architecture\": {\n *     \"mode\": \"ON\",                          // \"OFF\" disables the whole feature\n *     \"turnOffRuleUntilEpoch\": 0,            // whole-rule punt (epoch seconds)\n *     \"turnOffRuleWhileOnBranch\": null,      // whole-rule punt while on a named branch\n *     \"showExternalNodes\": true,              // draw firestore/gmail/... as terminal nodes\n *     \"externalApiPaths\": [\"libraries/apis/external/**\"]  // where those vendor contracts live\n *   }\n */\n\nimport { loadAndValidate, shouldSkipRule, SkipRuleResult } from '@webpieces/rules-config';\n\nexport const RUNTIME_RULE_NAME = 'runtime-architecture';\n\nexport interface RuntimeRuleConfig {\n    off: boolean;\n    turnOffRuleUntilEpoch?: number;\n    turnOffRuleWhileOnBranch?: string;\n    /** Render the dashed external terminal nodes in the runtime viz (default true). */\n    showExternalNodes: boolean;\n    /**\n     * Globs of project roots whose exported `*Api` types are contracts for systems OUTSIDE this repo.\n     * Empty (the default) means the scan looks for no vendor seams at all.\n     */\n    externalApiPaths: string[];\n}\n\n/**\n * Typed view of the opaque webpieces.config.json option bag for this rule. The\n * config is trusted (it is the workspace's own file), so we cast once here and\n * defensively narrow arrays/numbers rather than threading `unknown` everywhere.\n */\ninterface RuntimeRuleRaw {\n    turnOffRuleUntilEpoch?: number;\n    turnOffRuleWhileOnBranch?: string | null;\n    showExternalNodes?: boolean;\n    externalApiPaths?: string[];\n}\n\n/** Load the runtime-architecture rule config (with safe defaults). */\nexport function loadRuntimeConfig(workspaceRoot: string): RuntimeRuleConfig {\n    const shared = loadAndValidate(workspaceRoot).resolved;\n    const rule = shared.rules.get(RUNTIME_RULE_NAME);\n    const raw = (rule?.options ?? {}) as RuntimeRuleRaw;\n    return {\n        off: rule?.isOff ?? false,\n        turnOffRuleUntilEpoch:\n            typeof raw.turnOffRuleUntilEpoch === 'number' ? raw.turnOffRuleUntilEpoch : undefined,\n        // turnOffRuleWhileOnBranch is required-but-NULLABLE in the config (\"null\" = always on), so a\n        // non-string (null) collapses to undefined, which shouldSkipRule treats as \"no branch scoping\".\n        turnOffRuleWhileOnBranch:\n            typeof raw.turnOffRuleWhileOnBranch === 'string' ? raw.turnOffRuleWhileOnBranch : undefined,\n        // Opt-OUT: the external systems are the ones that page you at 3am, so they are drawn unless\n        // a repo explicitly says its external surface is too noisy to be useful.\n        showExternalNodes: raw.showExternalNodes !== false,\n        // Opt-IN: there is no safe guess for where a repo keeps its vendor wrappers, and guessing\n        // wrong would classify ordinary libraries as systems outside the repo.\n        externalApiPaths: Array.isArray(raw.externalApiPaths)\n            ? raw.externalApiPaths.filter((entry: string) => typeof entry === 'string' && entry.length > 0)\n            : [],\n    };\n}\n\n/**\n * Whole-rule report-only window honoring BOTH escape hatches: skip while on the\n * named branch (turnOffRuleWhileOnBranch) or until the epoch passes\n * (turnOffRuleUntilEpoch). When `.skip` is true, problems are reported but\n * the build is not failed.\n */\nexport function runtimeReportOnly(config: RuntimeRuleConfig): SkipRuleResult {\n    return shouldSkipRule(config.turnOffRuleUntilEpoch, config.turnOffRuleWhileOnBranch);\n}\n\n/**\n * Whole-rule grace window: while now < epoch, failures are reported but do not\n * fail the build (warn). Mirrors the other webpieces rules.\n */\nexport function isGraceActive(epoch: number | undefined): boolean {\n    if (epoch === undefined) return false;\n    return Date.now() / 1000 < epoch;\n}\n\n/** Format the epoch as an ISO date for log messages. */\nexport function epochDate(epoch: number): string {\n    return new Date(epoch * 1000).toISOString().split('T')[0];\n}\n"]}

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

@@ -1,26 +1,24 @@
 /**
  * Runtime Cycles
  *
- * Enumerates ALL cycles in the runtime service graph using Tarjan's
- * strongly-connected-components algorithm. Runtime validation needs every cycle so each can be
- * checked against the per-cycle allowlist independently.
+ * Enumerates ALL cycles in a directed graph using Tarjan's strongly-connected-components algorithm.
+ * Every cycle rather than the first, so one run names everything a reader has to break.
  *
- * This is the ONE SCC implementation in the package: `ProjectCycleDetector` (lib/graph-cycles.ts)
- * calls it for the COMPILE-TIME project graph, where it likewise enumerates every cycle rather than
- * stopping at the first.
+ * This is the ONE SCC implementation in the package. `ProjectCycleDetector` (lib/graph-cycles.ts)
+ * calls it for BOTH graphs: the COMPILE-TIME project graph, and — through `assignLevels`
+ * (lib/runtime-graph-levels.ts) — the RUNTIME service graph.
  *
  * A cycle is any SCC with more than one node, or a single node with a self-edge.
- * Each cycle is keyed by its sorted, comma-joined node names so it can be
- * matched against an `allowedCycles` entry regardless of traversal order.
+ *
+ * There is no per-cycle allowlist any more. The `allowedCycles` config key that once keyed off a
+ * canonical sorted-name string is deleted: a cyclic architecture cannot be deployed in any order, so
+ * it fails outright, and the one escape is a per-EDGE `cutLegacyCycle:<targetService>` nx tag that
+ * keeps the edge out of the adjacency this ever sees.
  */
 export interface RuntimeCycle {
     /** Sorted service names participating in the cycle. */
     services: string[];
-    /** Canonical key: services sorted then joined with ",". */
-    key: string;
 }
-/** Canonical key for a set of service names (order-independent). */
-export declare function cycleKey(services: string[]): string;
 /**
  * Find every cycle in a directed graph via Tarjan's SCC algorithm.
  * `graph[node]` lists the nodes `node` points to.

package/src/lib/runtime-cycles.js

@@ -2,25 +2,22 @@
 /**
  * Runtime Cycles
  *
- * Enumerates ALL cycles in the runtime service graph using Tarjan's
- * strongly-connected-components algorithm. Runtime validation needs every cycle so each can be
- * checked against the per-cycle allowlist independently.
+ * Enumerates ALL cycles in a directed graph using Tarjan's strongly-connected-components algorithm.
+ * Every cycle rather than the first, so one run names everything a reader has to break.
  *
- * This is the ONE SCC implementation in the package: `ProjectCycleDetector` (lib/graph-cycles.ts)
- * calls it for the COMPILE-TIME project graph, where it likewise enumerates every cycle rather than
- * stopping at the first.
+ * This is the ONE SCC implementation in the package. `ProjectCycleDetector` (lib/graph-cycles.ts)
+ * calls it for BOTH graphs: the COMPILE-TIME project graph, and — through `assignLevels`
+ * (lib/runtime-graph-levels.ts) — the RUNTIME service graph.
  *
  * A cycle is any SCC with more than one node, or a single node with a self-edge.
- * Each cycle is keyed by its sorted, comma-joined node names so it can be
- * matched against an `allowedCycles` entry regardless of traversal order.
+ *
+ * There is no per-cycle allowlist any more. The `allowedCycles` config key that once keyed off a
+ * canonical sorted-name string is deleted: a cyclic architecture cannot be deployed in any order, so
+ * it fails outright, and the one escape is a per-EDGE `cutLegacyCycle:<targetService>` nx tag that
+ * keeps the edge out of the adjacency this ever sees.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cycleKey = cycleKey;
 exports.findRuntimeCycles = findRuntimeCycles;
-/** Canonical key for a set of service names (order-independent). */
-function cycleKey(services) {
-    return [...services].sort().join(',');
-}
 /**
  * Find every cycle in a directed graph via Tarjan's SCC algorithm.
  * `graph[node]` lists the nodes `node` points to.
@@ -69,7 +66,7 @@ function findRuntimeCycles(graph) {
         const isSelfLoop = component.length === 1 && (graph[component[0]] ?? []).includes(component[0]);
         if (isMultiNode || isSelfLoop) {
             const services = [...component].sort();
-            cycles.push({ services, key: cycleKey(services) });
+            cycles.push({ services });
         }
     }
     return cycles;

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

@@ -1 +1 @@
-{"version":3,"file":"runtime-cycles.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-cycles.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AAUH,4BAEC;AAMD,8CAoDC;AA7DD,oEAAoE;AACpE,SAAgB,QAAQ,CAAC,QAAkB;IACvC,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,KAA+B;IAC7D,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAe,EAAE,CAAC;IAC5B,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEjC,MAAM,aAAa,GAAG,CAAC,IAAY,EAAQ,EAAE;QACzC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3B,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC,CAAC;QACb,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAElB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACnC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrB,aAAa,CAAC,IAAI,CAAC,CAAC;gBACpB,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAE,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC,CAAC,CAAC;YACxE,CAAC;iBAAM,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3B,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAE,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC,CAAC,CAAC;YACxE,CAAC;QACL,CAAC;QAED,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,MAAM,SAAS,GAAa,EAAE,CAAC;YAC/B,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,GAAG,CAAC;gBACA,MAAM,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;gBACtB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACvB,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC3B,CAAC,QAAQ,MAAM,KAAK,IAAI,EAAE;YAC1B,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACzB,CAAC;IACL,CAAC,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;QAC3B,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QACzC,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QAChG,IAAI,WAAW,IAAI,UAAU,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;YACvC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACvD,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC","sourcesContent":["/**\n * Runtime Cycles\n *\n * Enumerates ALL cycles in the runtime service graph using Tarjan's\n * strongly-connected-components algorithm. Runtime validation needs every cycle so each can be\n * checked against the per-cycle allowlist independently.\n *\n * This is the ONE SCC implementation in the package: `ProjectCycleDetector` (lib/graph-cycles.ts)\n * calls it for the COMPILE-TIME project graph, where it likewise enumerates every cycle rather than\n * stopping at the first.\n *\n * A cycle is any SCC with more than one node, or a single node with a self-edge.\n * Each cycle is keyed by its sorted, comma-joined node names so it can be\n * matched against an `allowedCycles` entry regardless of traversal order.\n */\n\nexport interface RuntimeCycle {\n    /** Sorted service names participating in the cycle. */\n    services: string[];\n    /** Canonical key: services sorted then joined with \",\". */\n    key: string;\n}\n\n/** Canonical key for a set of service names (order-independent). */\nexport function cycleKey(services: string[]): string {\n    return [...services].sort().join(',');\n}\n\n/**\n * Find every cycle in a directed graph via Tarjan's SCC algorithm.\n * `graph[node]` lists the nodes `node` points to.\n */\nexport function findRuntimeCycles(graph: Record<string, string[]>): RuntimeCycle[] {\n    const indexOf = new Map<string, number>();\n    const lowLink = new Map<string, number>();\n    const onStack = new Set<string>();\n    const stack: string[] = [];\n    const sccs: string[][] = [];\n    let counter = 0;\n\n    const nodes = Object.keys(graph);\n\n    const strongConnect = (node: string): void => {\n        indexOf.set(node, counter);\n        lowLink.set(node, counter);\n        counter += 1;\n        stack.push(node);\n        onStack.add(node);\n\n        for (const next of graph[node] ?? []) {\n            if (!indexOf.has(next)) {\n                strongConnect(next);\n                lowLink.set(node, Math.min(lowLink.get(node)!, lowLink.get(next)!));\n            } else if (onStack.has(next)) {\n                lowLink.set(node, Math.min(lowLink.get(node)!, indexOf.get(next)!));\n            }\n        }\n\n        if (lowLink.get(node) === indexOf.get(node)) {\n            const component: string[] = [];\n            let member = '';\n            do {\n                member = stack.pop()!;\n                onStack.delete(member);\n                component.push(member);\n            } while (member !== node);\n            sccs.push(component);\n        }\n    };\n\n    for (const node of nodes) {\n        if (!indexOf.has(node)) strongConnect(node);\n    }\n\n    const cycles: RuntimeCycle[] = [];\n    for (const component of sccs) {\n        const isMultiNode = component.length > 1;\n        const isSelfLoop = component.length === 1 && (graph[component[0]] ?? []).includes(component[0]);\n        if (isMultiNode || isSelfLoop) {\n            const services = [...component].sort();\n            cycles.push({ services, key: cycleKey(services) });\n        }\n    }\n    return cycles;\n}\n"]}
+{"version":3,"file":"runtime-cycles.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-cycles.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime Cycles\n *\n * Enumerates ALL cycles in a directed graph using Tarjan's strongly-connected-components algorithm.\n * Every cycle rather than the first, so one run names everything a reader has to break.\n *\n * This is the ONE SCC implementation in the package. `ProjectCycleDetector` (lib/graph-cycles.ts)\n * calls it for BOTH graphs: the COMPILE-TIME project graph, and — through `assignLevels`\n * (lib/runtime-graph-levels.ts) — the RUNTIME service graph.\n *\n * A cycle is any SCC with more than one node, or a single node with a self-edge.\n *\n * There is no per-cycle allowlist any more. The `allowedCycles` config key that once keyed off a\n * canonical sorted-name string is deleted: a cyclic architecture cannot be deployed in any order, so\n * it fails outright, and the one escape is a per-EDGE `cutLegacyCycle:<targetService>` nx tag that\n * keeps the edge out of the adjacency this ever sees.\n */\n\nexport interface RuntimeCycle {\n    /** Sorted service names participating in the cycle. */\n    services: string[];\n}\n\n/**\n * Find every cycle in a directed graph via Tarjan's SCC algorithm.\n * `graph[node]` lists the nodes `node` points to.\n */\nexport function findRuntimeCycles(graph: Record<string, string[]>): RuntimeCycle[] {\n    const indexOf = new Map<string, number>();\n    const lowLink = new Map<string, number>();\n    const onStack = new Set<string>();\n    const stack: string[] = [];\n    const sccs: string[][] = [];\n    let counter = 0;\n\n    const nodes = Object.keys(graph);\n\n    const strongConnect = (node: string): void => {\n        indexOf.set(node, counter);\n        lowLink.set(node, counter);\n        counter += 1;\n        stack.push(node);\n        onStack.add(node);\n\n        for (const next of graph[node] ?? []) {\n            if (!indexOf.has(next)) {\n                strongConnect(next);\n                lowLink.set(node, Math.min(lowLink.get(node)!, lowLink.get(next)!));\n            } else if (onStack.has(next)) {\n                lowLink.set(node, Math.min(lowLink.get(node)!, indexOf.get(next)!));\n            }\n        }\n\n        if (lowLink.get(node) === indexOf.get(node)) {\n            const component: string[] = [];\n            let member = '';\n            do {\n                member = stack.pop()!;\n                onStack.delete(member);\n                component.push(member);\n            } while (member !== node);\n            sccs.push(component);\n        }\n    };\n\n    for (const node of nodes) {\n        if (!indexOf.has(node)) strongConnect(node);\n    }\n\n    const cycles: RuntimeCycle[] = [];\n    for (const component of sccs) {\n        const isMultiNode = component.length > 1;\n        const isSelfLoop = component.length === 1 && (graph[component[0]] ?? []).includes(component[0]);\n        if (isMultiNode || isSelfLoop) {\n            const services = [...component].sort();\n            cycles.push({ services });\n        }\n    }\n    return cycles;\n}\n"]}

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

@@ -1,3 +1,4 @@
+import type { EnhancedGraph } from './graph-sorter';
 import type { RuntimeEdge, RuntimeGraph } from './runtime-graph-model';
 /**
  * LEVELS and ADJACENCY for the runtime graph — how deep each service sits, and who calls whom.
@@ -10,14 +11,59 @@ import type { RuntimeEdge, RuntimeGraph } from './runtime-graph-model';
 /**
  * Adjacency (service -> [targets]) used for leveling + cycle checks.
  *
- * PUBSUB EDGES ARE EXCLUDED. A queue is precisely the thing that decouples producer from consumer:
- * the producer returns as soon as the task is enqueued and never waits on the consumer, so a queued
- * hop is not a runtime dependency in the sense levels and cycle detection mean. Counting them would
- * make the common and correct `A → queue → A` (a service deferring its own work) an architecture
- * cycle, and would rank services by an ordering that does not constrain deploy or startup.
+ * TWO KINDS OF EDGE ARE EXCLUDED, and the second is modelled on the first:
+ *
+ * PUBSUB EDGES. A queue is precisely the thing that decouples producer from consumer: the producer
+ * returns as soon as the task is enqueued and never waits on the consumer, so a queued hop is not a
+ * runtime dependency in the sense levels and cycle detection mean. Counting them would make the
+ * common and correct `A → queue → A` (a service deferring its own work) an architecture cycle, and
+ * would rank services by an ordering that does not constrain deploy or startup.
+ *
+ * EDGES STAMPED `cutLegacyCycle`. The calling project carries a `cutLegacyCycle:<target>` nx tag
+ * (see cut-legacy-cycle-resolver.ts) ADMITTING that this hop closes a real cycle which is being
+ * tolerated as legacy debt. Unlike a queued hop the coupling is real, so the edge is still drawn —
+ * it is only kept out of leveling and cycle detection, which are the two things a cycle makes
+ * meaningless.
  */
 export declare function adjacencyFromEdges(serviceNames: string[], edges: RuntimeEdge[]): Record<string, string[]>;
+/**
+ * Stamp `cutLegacyCycle` on every runtime edge a project declared a cut for — the DECLARATION
+ * (`cutLegacyCycle:<targetService>` nx tags, resolved into `GraphEntry.cutLegacyCycle` and committed
+ * to dependencies.json) turned into the mark {@link adjacencyFromEdges} above reads.
+ *
+ * IT FAILS THE BUILD ON A TAG THAT CUTS NOTHING, in both directions:
+ *
+ *  - the tag names a service no runtime node answers to — a typo or a rename. Silently doing nothing
+ *    is the worst outcome available: the check would look exempted while no edge was in fact cut, or
+ *    the tag would keep reading as a live IOU after the service it named was deleted. `serviceName`
+ *    is validated against real module names for exactly this reason.
+ *  - the tag resolves, but there is no direct edge to cut. The debt is PAID — delete the tag, so
+ *    `grep -rn cutLegacyCycle` keeps enumerating only cycles still actually tolerated.
+ *
+ * Returned as problems (the deriver's `problems` list) rather than thrown, so one run names every
+ * bad tag instead of stopping at the first.
+ *
+ * @param edges       the derived runtime edges, mutated in place.
+ * @param projects    the committed project entries carrying `cutLegacyCycle`.
+ * @param nodeByServiceName addressable name -> runtime node, the SAME map that resolves a call
+ *                          target, so a tag may name a module name or a declared serviceName.
+ */
+export declare function applyCycleCuts(edges: RuntimeEdge[], projects: EnhancedGraph, nodeByServiceName: Map<string, string>): string[];
 /** Adjacency (service -> [targets]) from a loaded runtime graph. */
 export declare function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]>;
-/** Assign levels via topological sort; falls back to level 0 when a cycle exists. */
+/**
+ * Assign levels via topological sort — and THROW on a cycle rather than levelling one.
+ *
+ * This used to swallow the cycle and flatten EVERY service to level 0, which was the worst available
+ * outcome twice over: one bad edge anywhere silently restratified the whole graph, and the reason
+ * was discarded, so the diagram rendered as one legitimate-looking flat row.
+ *
+ * Cycles are not allowed. CD deploys services in dependency order, and a cyclic architecture has no
+ * such order — whichever member rolls out first is calling one that is not up yet — so the graph is
+ * not deployable and its level numbers mean nothing.
+ *
+ * Detection is {@link ProjectCycleDetector}, the ONE cycle detector in this package (it guards the
+ * compile-time project graph too); only the audience and the cures differ, so only the message is
+ * written here.
+ */
 export declare function assignLevels(adjacency: Record<string, string[]>): Record<string, number>;