@webpieces/nx-webpieces-rules 0.4.769 → 0.4.770

package/package.json

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

package/src/lib/api-usage/api-ast.d.ts

@@ -10,7 +10,7 @@
  * api-scanner's source pre-pass exists to guard against.
  */
 import * as ts from 'typescript';
-import { ApiClassInfo, ApiMethodMeta, ApiTransport, EmptiedApiContract, ExternalSystemDeclaration, NonLiteralDecoratorArg, UndeclaredExternalCaller, UnresolvedEndpointPath } from './api-relations';
+import { ApiClassInfo, ApiMethodMeta, ApiParameterMeta, ContractHttpMethod, ApiTransport, EmptiedApiContract, ExternalSystemDeclaration, NonLiteralDecoratorArg, UndeclaredExternalCaller, UnresolvedEndpointPath } from './api-relations';
 /**
  * The module-scope `const NAME = '<string literal>'` bindings of ONE source file.
  *
@@ -105,6 +105,12 @@ export declare function apiTransport(cls: ts.ClassDeclaration): ApiTransport;
  * zero-method classes, which is the door a gutted contract used to leave through unannounced.
  */
 export declare function endpointMethodsOf(cls: ts.ClassDeclaration, api: string, constants?: ModuleStringConstants, diagnostics?: DecoratorArgDiagnostics | null): ApiMethodMeta[];
+/** `@Endpoint(..., { httpMethod: 'GET' })`, defaulting to the runtime's POST default. */
+export declare function httpMethodOf(options: ts.Expression | undefined, constants: ModuleStringConstants, diagnostics: DecoratorArgDiagnostics | null, api: string, method: string, node: ts.Node): ContractHttpMethod;
+/** Only the non-default full-response marker needs an architecture field. */
+export declare function endpointResponseTypeOf(options: ts.Expression | undefined, constants: ModuleStringConstants): 'body' | 'full';
+/** Explicit `@PathParam` / `@QueryParam` mappings in source declaration order. */
+export declare function httpParametersOf(member: ts.MethodDeclaration, httpMethod: ContractHttpMethod, constants: ModuleStringConstants, diagnostics: DecoratorArgDiagnostics | null, api: string, method: string): ApiParameterMeta[];
 /**
  * The outcome of reading `@Endpoint(path, 'external', { calledBy, callerKind })`'s third argument:
  * either the resolved declaration, or the reason it could not be resolved (never both).
@@ -137,6 +143,8 @@ export declare function reportUnresolved(diagnostics: DecoratorArgDiagnostics |
 export declare function decoratorArgs(decorator: ts.Decorator): ts.NodeArray<ts.Expression> | ts.Expression[];
 /** The named decorator on a class member, or null. */
 export declare function memberDecorator(member: ts.ClassElement, name: string): ts.Decorator | null;
+/** The named decorator on any decorator-capable AST node (notably a method parameter). */
+export declare function decoratorOn(node: ts.HasDecorators, name: string): ts.Decorator | null;
 /**
  * The first argument of a class decorator as a string (`@ApiPath('/x')`, `@ApiPath(X_PATH)`), else
  * null. A same-module constant resolves; anything else is recorded on `diagnostics`.

package/src/lib/api-usage/api-ast.js

@@ -18,12 +18,16 @@ exports.decoratorArgValue = decoratorArgValue;
 exports.apiClassInfoFrom = apiClassInfoFrom;
 exports.apiTransport = apiTransport;
 exports.endpointMethodsOf = endpointMethodsOf;
+exports.httpMethodOf = httpMethodOf;
+exports.endpointResponseTypeOf = endpointResponseTypeOf;
+exports.httpParametersOf = httpParametersOf;
 exports.externalCallerOf = externalCallerOf;
 exports.objectPropertyValue = objectPropertyValue;
 exports.queueNameOf = queueNameOf;
 exports.reportUnresolved = reportUnresolved;
 exports.decoratorArgs = decoratorArgs;
 exports.memberDecorator = memberDecorator;
+exports.decoratorOn = decoratorOn;
 exports.decoratorStringArg = decoratorStringArg;
 exports.constructorParamsOf = constructorParamsOf;
 exports.typeReferenceName = typeReferenceName;
@@ -274,9 +278,22 @@ function endpointMethodsOf(cls, api, constants = new ModuleStringConstants(new M
             diagnostics.recordUnresolvedPath(api, name, pathArg.unresolvedName, endpoint);
         }
         const kind = kindArg.value;
-        if (pathArg.value === null || kind === null || !ENDPOINT_KINDS.includes(kind))
+        if (pathArg.value === null ||
+            kind === null ||
+            !ENDPOINT_KINDS.includes(kind))
             continue;
-        const method = { name, path: pathArg.value, kind: kind };
+        const httpMethod = httpMethodOf(args[2], constants, diagnostics, api, name, endpoint);
+        const method = {
+            name,
+            path: pathArg.value,
+            kind: kind,
+            httpMethod,
+        };
+        const parameters = httpParametersOf(member, httpMethod, constants, diagnostics, api, name);
+        if (parameters.length > 0)
+            method.parameters = parameters;
+        if (endpointResponseTypeOf(args[2], constants) === 'full')
+            method.responseType = 'full';
         // Only a queued or scheduled endpoint HAS a queue. Naming one for a synchronous rpc invited a
         // tool to read `methods.map(m => m.queueName)` as a provisioning list and create queues that
         // nothing will ever deliver to.
@@ -302,6 +319,47 @@ function endpointMethodsOf(cls, api, constants = new ModuleStringConstants(new M
     }
     return methods;
 }
+/** `@Endpoint(..., { httpMethod: 'GET' })`, defaulting to the runtime's POST default. */
+// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers
+function httpMethodOf(options, constants, diagnostics, api, method, node) {
+    if (options === undefined || !ts.isObjectLiteralExpression(options))
+        return 'POST';
+    const declared = objectPropertyValue(options, 'httpMethod', constants);
+    reportUnresolved(diagnostics, api, 'Endpoint.httpMethod', method, declared, node);
+    return declared.value === 'GET' ? 'GET' : 'POST';
+}
+/** Only the non-default full-response marker needs an architecture field. */
+// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers
+function endpointResponseTypeOf(options, constants) {
+    if (options === undefined || !ts.isObjectLiteralExpression(options))
+        return 'body';
+    return objectPropertyValue(options, 'responseType', constants).value === 'full'
+        ? 'full'
+        : 'body';
+}
+/** Explicit `@PathParam` / `@QueryParam` mappings in source declaration order. */
+// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers
+function httpParametersOf(member, httpMethod, constants, diagnostics, api, method) {
+    const parameters = [];
+    member.parameters.forEach((parameter, index) => {
+        let mapped = false;
+        for (const source of ['path', 'query']) {
+            const decoratorNameWanted = source === 'path' ? 'PathParam' : 'QueryParam';
+            const decorator = decoratorOn(parameter, decoratorNameWanted);
+            if (decorator === null)
+                continue;
+            mapped = true;
+            const wireName = decoratorArgValue(decoratorArgs(decorator)[0], constants);
+            reportUnresolved(diagnostics, api, decoratorNameWanted, method, wireName, decorator);
+            if (wireName.value !== null) {
+                parameters.push({ index, source, wireName: wireName.value });
+            }
+        }
+        if (!mapped && httpMethod === 'POST')
+            parameters.push({ index, source: 'body' });
+    });
+    return parameters;
+}
 /** Default `callerKind` when an `external` endpoint declares `calledBy` alone — mirrors core-util. */
 const DEFAULT_CALLER_KIND = 'saas';
 /**
@@ -353,7 +411,9 @@ function objectPropertyValue(literal, name, constants) {
     for (const property of literal.properties) {
         if (!ts.isPropertyAssignment(property) || property.name === undefined)
             continue;
-        const key = ts.isIdentifier(property.name) || ts.isStringLiteral(property.name) ? property.name.text : null;
+        const key = ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)
+            ? property.name.text
+            : null;
         if (key !== name)
             continue;
         return decoratorArgValue(property.initializer, constants);
@@ -388,6 +448,12 @@ function memberDecorator(member, name) {
     const decorators = ts.getDecorators(member) ?? [];
     return decorators.find((d) => (0, bindings_1.decoratorName)(d) === name) ?? null;
 }
+/** The named decorator on any decorator-capable AST node (notably a method parameter). */
+// webpieces-disable no-function-outside-class -- pure AST accessor, matching memberDecorator
+function decoratorOn(node, name) {
+    const decorators = ts.getDecorators(node) ?? [];
+    return decorators.find((decorator) => (0, bindings_1.decoratorName)(decorator) === name) ?? null;
+}
 /**
  * The first argument of a class decorator as a string (`@ApiPath('/x')`, `@ApiPath(X_PATH)`), else
  * null. A same-module constant resolves; anything else is recorded on `diagnostics`.
@@ -533,7 +599,10 @@ function externalSystemTagFrom(node, api) {
         if (tag.tagName.text !== EXTERNAL_SYSTEM_TAG)
             continue;
         const comment = typeof tag.comment === 'string' ? tag.comment : '';
-        const parts = comment.trim().split(/\s+/).filter((part) => part !== '');
+        const parts = comment
+            .trim()
+            .split(/\s+/)
+            .filter((part) => part !== '');
         if (parts.length === 0)
             continue;
         const kind = parts[0].toLowerCase();

package/src/lib/api-usage/api-ast.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-ast.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-ast.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * API contract AST accessors\n *\n * The pure, stateless half of the api scan: given a TypeScript node, what contract / endpoint /\n * injected type does it describe? Split out of api-scanner.ts, which owns the STATEFUL walk (project\n * programs, the source index, relation accumulation) and had grown past the file-size limit.\n *\n * Everything here is parser-level on purpose. Decorators must be read exactly as written, and a\n * plain parse cannot be diverted to a decorator-erased `.d.ts` by module resolution — the bug\n * api-scanner's source pre-pass exists to guard against.\n */\n\nimport * as ts from 'typescript';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { classDecorators, decoratorName } from '../di-graph/bindings';\nimport {\n    ApiClassInfo,\n    ApiMethodMeta,\n    ApiTransport,\n    EmptiedApiContract,\n    EndpointKind,\n    ExternalSystemDeclaration,\n    isExternalSystemKind,\n    NonLiteralDecoratorArg,\n    UndeclaredExternalCaller,\n    UnresolvedEndpointPath,\n} from './api-relations';\n\n/** Legal `@Endpoint(path, kind)` values; anything else is a source error, not a kind we invent. */\nconst ENDPOINT_KINDS: readonly EndpointKind[] = ['rpc', 'cloudtasks', 'cron', 'external'];\n\n/**\n * Name suffix that marks an exported type in an `externalApiPaths` project as a vendor CONTRACT\n * (`GmailApi`, `StorageApi`) rather than one of the DTOs, configs or clients sitting beside it.\n * The same convention the in-repo contracts already follow, applied where no decorator can be read.\n */\nconst EXTERNAL_CONTRACT_SUFFIX = 'Api';\n\n/** JSDoc tag a vendor contract uses to declare WHAT it is a seam to: `@externalSystem database Firestore`. */\nconst EXTERNAL_SYSTEM_TAG = 'externalSystem';\n\n/**\n * Client-config class-name suffix whose FIRST constructor argument is the target service name —\n * `ClientConfig('helper-fsdb')` (rpc) and `TaskClientConfig('helper-fsdb')` (pubsub) both take\n * `svcName` first, and a consumer's own `XxxClientConfig` follows the same shape.\n */\nconst CLIENT_CONFIG_SUFFIX = 'ClientConfig';\n\n/**\n * The module-scope `const NAME = '<string literal>'` bindings of ONE source file.\n *\n * A contract that hoists its route to a constant (`@ApiPath(WHATSAPP_API_PATH)`) is good practice —\n * it lets a sibling contract and its callers share the symbol — but a decorator argument is read as\n * TEXT here, with no checker to constant-fold it. Without this table such an argument resolved to\n * nothing: the class lost its basePath, and a class whose every @Endpoint path was a constant\n * resolved to zero methods and was dropped from the graph entirely.\n *\n * Deliberately SAME-MODULE only. Following an import would mean resolving modules, which is exactly\n * what the source pre-pass avoids (it can be diverted to a decorator-erased `.d.ts`). A cross-module\n * constant is therefore still unresolvable — and is REPORTED rather than silently dropped, see\n * DecoratorArgDiagnostics.\n */\nexport class ModuleStringConstants {\n    constructor(private readonly byName: Map<string, string>) {}\n\n    lookup(name: string): string | null {\n        return this.byName.get(name) ?? null;\n    }\n}\n\n/** Parsed constants per source file — every class in a file shares one table. */\nconst CONSTANTS_BY_FILE = new WeakMap<ts.SourceFile, ModuleStringConstants>();\n\n/** The module-scope string constants of `sourceFile`, parsed once per file. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function stringConstantsOf(sourceFile: ts.SourceFile): ModuleStringConstants {\n    const cached = CONSTANTS_BY_FILE.get(sourceFile);\n    if (cached !== undefined) return cached;\n    const byName = new Map<string, string>();\n    for (const statement of sourceFile.statements) {\n        if (!ts.isVariableStatement(statement)) continue;\n        if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;\n        for (const declaration of statement.declarationList.declarations) {\n            if (!ts.isIdentifier(declaration.name)) continue;\n            const text = stringValueOf(declaration.initializer);\n            if (text !== null) byName.set(declaration.name.text, text);\n        }\n    }\n    const constants = new ModuleStringConstants(byName);\n    CONSTANTS_BY_FILE.set(sourceFile, constants);\n    return constants;\n}\n\n/** The string an initializer denotes, unwrapping `as const` / parentheses, else null. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function stringValueOf(expr: ts.Expression | undefined): string | null {\n    if (expr === undefined) return null;\n    if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) return expr.text;\n    if (ts.isAsExpression(expr) || ts.isParenthesizedExpression(expr)) return stringValueOf(expr.expression);\n    return null;\n}\n\n/**\n * ONE decorator argument that had to be a string, and what came of it.\n *\n * `value` is the string when it was a literal or resolved through a same-module constant.\n * `unresolvedName` is the argument as written (`WHATSAPP_API_PATH`) when it is present but could not\n * be reduced — the case that must be reported, never silently dropped. Both are null when the\n * argument is simply absent.\n */\nexport class DecoratorArgValue {\n    constructor(\n        public readonly value: string | null,\n        public readonly unresolvedName: string | null,\n    ) {}\n}\n\n/** Read one decorator argument as a string, resolving same-module constants. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function decoratorArgValue(\n    expr: ts.Expression | undefined,\n    constants: ModuleStringConstants,\n): DecoratorArgValue {\n    if (expr === undefined) return new DecoratorArgValue(null, null);\n    const literal = stringValueOf(expr);\n    if (literal !== null) return new DecoratorArgValue(literal, null);\n    if (ts.isIdentifier(expr)) {\n        const resolved = constants.lookup(expr.text);\n        if (resolved !== null) return new DecoratorArgValue(resolved, null);\n        return new DecoratorArgValue(null, expr.text);\n    }\n    return new DecoratorArgValue(null, expr.getText());\n}\n\n/**\n * Collects everything this parser-only pass had to drop: decorator arguments it could not reduce to\n * a string, plus the two of those that are FATAL rather than merely lossy.\n *\n * A same-module constant now resolves, but a cross-module one (`import { PATH } from './paths'`)\n * genuinely cannot — the source pre-pass has no checker by design. That gap used to be invisible:\n * the contract simply came out with no basePath, or with fewer methods, or not at all. Recording it\n * turns a silent drop into a named one, pointing at the exact file, line and identifier.\n *\n * Three sinks, because the consequences differ. `record` is the warning stream (a @Queue name falls\n * back to a derived one, so the graph is degraded, not wrong). `recordUnresolvedPath` and\n * `recordEmptiedContract` are collected so generation can FAIL — one aggregated error naming every\n * offender, because an author fixing five constants wants all five in one run.\n */\nexport class DecoratorArgDiagnostics {\n    private readonly found: NonLiteralDecoratorArg[] = [];\n    private readonly unresolvedPaths: UnresolvedEndpointPath[] = [];\n    private readonly emptied: EmptiedApiContract[] = [];\n    private readonly undeclaredCallers: UndeclaredExternalCaller[] = [];\n\n    constructor(private readonly workspaceRoot: string) {}\n\n    /** Record `argument` (as written) as unresolvable at `node`'s location. */\n    record(api: string, decorator: string, method: string | null, argument: string, node: ts.Node): void {\n        this.found.push(new NonLiteralDecoratorArg(api, decorator, method, argument, this.locate(node)));\n    }\n\n    /** Record an `@Endpoint` whose path argument is unreadable — fatal, see UnresolvedEndpointPathError. */\n    recordUnresolvedPath(api: string, method: string, argument: string, node: ts.Node): void {\n        this.unresolvedPaths.push(new UnresolvedEndpointPath(api, method, argument, this.locate(node)));\n    }\n\n    /** Record a class that declared `declared` `@Endpoint` methods and kept none of them. */\n    recordEmptiedContract(api: string, declared: number, node: ts.Node): void {\n        this.emptied.push(new EmptiedApiContract(api, declared, this.locate(node)));\n    }\n\n    /** Record an `external` `@Endpoint` whose caller is unreadable — fatal, see UndeclaredExternalCallerError. */\n    recordUndeclaredCaller(api: string, method: string, argument: string, node: ts.Node): void {\n        this.undeclaredCallers.push(new UndeclaredExternalCaller(api, method, argument, this.locate(node)));\n    }\n\n    all(): NonLiteralDecoratorArg[] {\n        return this.found;\n    }\n\n    unresolvedEndpointPaths(): UnresolvedEndpointPath[] {\n        return this.unresolvedPaths;\n    }\n\n    emptiedContracts(): EmptiedApiContract[] {\n        return this.emptied;\n    }\n\n    undeclaredExternalCallers(): UndeclaredExternalCaller[] {\n        return this.undeclaredCallers;\n    }\n\n    private locate(node: ts.Node): string {\n        const sourceFile = node.getSourceFile();\n        const position = sourceFile.getLineAndCharacterOfPosition(node.getStart());\n        return `${path.relative(this.workspaceRoot, sourceFile.fileName)}:${position.line + 1}`;\n    }\n}\n\n/** {api, owner: `project`, type} when `cls` is an `abstract class` carrying `@ApiPath`, else null. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function apiClassInfoFrom(\n    cls: ts.ClassDeclaration,\n    project: string,\n    diagnostics: DecoratorArgDiagnostics | null = null,\n): ApiClassInfo | null {\n    if (!isAbstractClass(cls) || !hasClassDecorator(cls, 'ApiPath') || !cls.name) return null;\n    const api = cls.name.text;\n    const constants = stringConstantsOf(cls.getSourceFile());\n    const info: ApiClassInfo = {\n        api,\n        owner: project,\n        type: apiTransport(cls),\n        methods: endpointMethodsOf(cls, api, constants, diagnostics),\n    };\n    const basePath = decoratorStringArg(cls, 'ApiPath', constants, diagnostics, api);\n    if (basePath !== null) info.basePath = basePath;\n    return info;\n}\n\n// webpieces-disable no-function-outside-class -- pure AST predicate, matching the sibling helpers in di-graph/bindings.ts\nexport function apiTransport(cls: ts.ClassDeclaration): ApiTransport {\n    return hasClassDecorator(cls, 'PubSub') ? 'pubsub' : 'rpc';\n}\n\n/** The @Endpoint kinds that are actually DELIVERED through a named queue or schedule. */\nconst QUEUED_KINDS: readonly EndpointKind[] = ['cloudtasks', 'cron'];\n\n/**\n * Every `@Endpoint(path, kind)` method on a contract class, in declaration order.\n *\n * `kind` is a REQUIRED argument of the decorator, so a missing/non-literal second argument means the\n * source does not compile (or is mid-edit) — we skip the method rather than defaulting it. Defaulting\n * would put an undeclared cron or webhook into the graph as an ordinary rpc call, which is precisely\n * the blindness the required argument exists to remove.\n *\n * `path` is NOT skippable. It may be a same-module constant; an argument that is present but still\n * cannot be reduced is recorded on `diagnostics` as an UnresolvedEndpointPath, which FAILS generation\n * later. Upstream components need the URL — a client computes its request as `basePath + path` — so\n * dropping the method here shipped a contract missing routing information, and a class whose every\n * path was a constant lost every method and disappeared from the graph entirely.\n *\n * A class that declared endpoints and kept NONE of them is recorded too: `buildApiContracts` skips\n * zero-method classes, which is the door a gutted contract used to leave through unannounced.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function endpointMethodsOf(\n    cls: ts.ClassDeclaration,\n    api: string,\n    constants: ModuleStringConstants = new ModuleStringConstants(new Map<string, string>()),\n    diagnostics: DecoratorArgDiagnostics | null = null,\n): ApiMethodMeta[] {\n    const methods: ApiMethodMeta[] = [];\n    let declared = 0;\n    for (const member of cls.members) {\n        if (!ts.isMethodDeclaration(member) || !ts.isIdentifier(member.name)) continue;\n        const endpoint = memberDecorator(member, 'Endpoint');\n        if (endpoint === null) continue;\n        declared++;\n        const name = member.name.text;\n        const args = decoratorArgs(endpoint);\n        const pathArg = decoratorArgValue(args[0], constants);\n        const kindArg = decoratorArgValue(args[1], constants);\n        reportUnresolved(diagnostics, api, 'Endpoint', name, pathArg, endpoint);\n        reportUnresolved(diagnostics, api, 'Endpoint', name, kindArg, endpoint);\n        if (diagnostics !== null && pathArg.unresolvedName !== null) {\n            diagnostics.recordUnresolvedPath(api, name, pathArg.unresolvedName, endpoint);\n        }\n        const kind = kindArg.value;\n        if (pathArg.value === null || kind === null || !ENDPOINT_KINDS.includes(kind as EndpointKind)) continue;\n        const method: ApiMethodMeta = { name, path: pathArg.value, kind: kind as EndpointKind };\n        // Only a queued or scheduled endpoint HAS a queue. Naming one for a synchronous rpc invited a\n        // tool to read `methods.map(m => m.queueName)` as a provisioning list and create queues that\n        // nothing will ever deliver to.\n        if (QUEUED_KINDS.includes(method.kind)) {\n            method.queueName = queueNameOf(member, api, name, constants, diagnostics);\n        }\n        // Only an `external` endpoint HAS an outside caller, mirroring the queue rule above. A\n        // caller recorded on an rpc method would be a fact about nothing, and would put a vendor\n        // box on the graph beside an endpoint no vendor calls.\n        if (method.kind === 'external') {\n            const caller = externalCallerOf(args[2], constants);\n            if (caller.declaration !== null) method.caller = caller.declaration;\n            else if (diagnostics !== null) diagnostics.recordUndeclaredCaller(api, name, caller.problem!, endpoint);\n        }\n        methods.push(method);\n    }\n    // Declared endpoints, kept none: the class is about to be skipped as \"zero methods\" and would\n    // leave no trace. Never legitimate — a routeless contract declares no @Endpoint at all.\n    if (diagnostics !== null && declared > 0 && methods.length === 0) {\n        diagnostics.recordEmptiedContract(api, declared, cls);\n    }\n    return methods;\n}\n\n/** Default `callerKind` when an `external` endpoint declares `calledBy` alone — mirrors core-util. */\nconst DEFAULT_CALLER_KIND = 'saas';\n\n/**\n * The outcome of reading `@Endpoint(path, 'external', { calledBy, callerKind })`'s third argument:\n * either the resolved declaration, or the reason it could not be resolved (never both).\n */\nexport class ExternalCallerRead {\n    constructor(\n        public readonly declaration: ExternalSystemDeclaration | null,\n        /** What was wrong, as written, for the diagnostic. Null exactly when `declaration` is set. */\n        public readonly problem: string | null,\n    ) {}\n}\n\n/**\n * Read the declared caller out of the @Endpoint OPTIONS OBJECT LITERAL — `args[2]`, not a positional\n * argument, because that is where `formPost` already lives and one options bag beats two.\n *\n * Everything unreadable is a PROBLEM, never a default: an unknown `callerKind` draws the wrong shape\n * (which teaches the reader something false), and a missing `calledBy` puts us back at a box that can\n * only name our own contract. The kind default applies ONLY to the case the API deliberately allows —\n * `calledBy` present, `callerKind` absent.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function externalCallerOf(\n    arg: ts.Expression | undefined,\n    constants: ModuleStringConstants,\n): ExternalCallerRead {\n    if (arg === undefined) return new ExternalCallerRead(null, '<no options argument>');\n    if (!ts.isObjectLiteralExpression(arg)) return new ExternalCallerRead(null, arg.getText());\n    const calledBy = objectPropertyValue(arg, 'calledBy', constants);\n    if (calledBy.value === null || calledBy.value === '') {\n        return new ExternalCallerRead(null, calledBy.unresolvedName ?? '<no calledBy>');\n    }\n    const callerKind = objectPropertyValue(arg, 'callerKind', constants);\n    if (callerKind.value === null && callerKind.unresolvedName !== null) {\n        return new ExternalCallerRead(null, `callerKind: ${callerKind.unresolvedName}`);\n    }\n    const kind = callerKind.value ?? DEFAULT_CALLER_KIND;\n    if (!isExternalSystemKind(kind)) return new ExternalCallerRead(null, `callerKind: '${kind}'`);\n    return new ExternalCallerRead({ kind, label: calledBy.value }, null);\n}\n\n/** One property of an object literal, read as a string through the same constant folding as an argument. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function objectPropertyValue(\n    literal: ts.ObjectLiteralExpression,\n    name: string,\n    constants: ModuleStringConstants,\n): DecoratorArgValue {\n    for (const property of literal.properties) {\n        if (!ts.isPropertyAssignment(property) || property.name === undefined) continue;\n        const key = ts.isIdentifier(property.name) || ts.isStringLiteral(property.name) ? property.name.text : null;\n        if (key !== name) continue;\n        return decoratorArgValue(property.initializer, constants);\n    }\n    return new DecoratorArgValue(null, null);\n}\n\n/** `@Queue('...')` override when present and resolvable, else the derived `${Api}-${method}`. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function queueNameOf(\n    member: ts.MethodDeclaration,\n    api: string,\n    name: string,\n    constants: ModuleStringConstants,\n    diagnostics: DecoratorArgDiagnostics | null,\n): string {\n    const override = memberDecorator(member, 'Queue');\n    if (override === null) return `${api}-${name}`;\n    const queueArg = decoratorArgValue(decoratorArgs(override)[0], constants);\n    reportUnresolved(diagnostics, api, 'Queue', name, queueArg, override);\n    return queueArg.value ?? `${api}-${name}`;\n}\n\n/** Record an argument that is present but unresolvable; a resolved or absent one is silent. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function reportUnresolved(\n    diagnostics: DecoratorArgDiagnostics | null,\n    api: string,\n    decorator: string,\n    method: string | null,\n    arg: DecoratorArgValue,\n    node: ts.Node,\n): void {\n    if (diagnostics === null || arg.unresolvedName === null) return;\n    diagnostics.record(api, decorator, method, arg.unresolvedName, node);\n}\n\n/** The arguments of a decorator's call expression, or [] when it is a bare `@Foo` reference. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function decoratorArgs(decorator: ts.Decorator): ts.NodeArray<ts.Expression> | ts.Expression[] {\n    return ts.isCallExpression(decorator.expression) ? decorator.expression.arguments : [];\n}\n\n/** The named decorator on a class member, or null. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function memberDecorator(member: ts.ClassElement, name: string): ts.Decorator | null {\n    const decorators = ts.getDecorators(member as ts.HasDecorators) ?? [];\n    return decorators.find((d: ts.Decorator) => decoratorName(d) === name) ?? null;\n}\n\n/**\n * The first argument of a class decorator as a string (`@ApiPath('/x')`, `@ApiPath(X_PATH)`), else\n * null. A same-module constant resolves; anything else is recorded on `diagnostics`.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function decoratorStringArg(\n    cls: ts.ClassDeclaration,\n    name: string,\n    constants: ModuleStringConstants = new ModuleStringConstants(new Map<string, string>()),\n    diagnostics: DecoratorArgDiagnostics | null = null,\n    api: string = name,\n): string | null {\n    const decorator = classDecorators(cls).find((d: ts.Decorator) => decoratorName(d) === name);\n    if (decorator === undefined) return null;\n    const arg = decoratorArgValue(decoratorArgs(decorator)[0], constants);\n    reportUnresolved(diagnostics, api, name, null, arg, decorator);\n    return arg.value;\n}\n\n/** The constructor's parameters, or [] when the class declares no constructor. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function constructorParamsOf(cls: ts.ClassDeclaration): readonly ts.ParameterDeclaration[] {\n    for (const member of cls.members) {\n        if (ts.isConstructorDeclaration(member)) return member.parameters;\n    }\n    return [];\n}\n\n/**\n * The bare name of a type reference (`GmailApi`, or `gmail.GmailApi` -> `GmailApi`), else null.\n * Generic wrappers are deliberately NOT unwrapped: `Provider<GmailApi>` hands out the contract\n * lazily, which is still a use, but it is not the shape any of these seams take today and guessing\n * at type arguments would start matching things that merely mention a contract.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function typeReferenceName(type: ts.TypeNode | undefined): string | null {\n    if (type === undefined || !ts.isTypeReferenceNode(type)) return null;\n    const name = type.typeName;\n    if (ts.isIdentifier(name)) return name.text;\n    return ts.isQualifiedName(name) && ts.isIdentifier(name.right) ? name.right.text : null;\n}\n\n/** Every type name in the class's `implements` clause — the contracts this class IS, not ones it calls. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function implementedTypeNames(cls: ts.ClassDeclaration): Set<string> {\n    const names = new Set<string>();\n    for (const clause of cls.heritageClauses ?? []) {\n        if (clause.token !== ts.SyntaxKind.ImplementsKeyword) continue;\n        for (const type of clause.types) {\n            if (ts.isIdentifier(type.expression)) names.add(type.expression.text);\n        }\n    }\n    return names;\n}\n\n// webpieces-disable no-function-outside-class -- pure AST predicate, matching the sibling helpers in di-graph/bindings.ts\nexport function isAbstractClass(cls: ts.ClassDeclaration): boolean {\n    return (ts.getModifiers(cls) ?? []).some((m: ts.Modifier) => m.kind === ts.SyntaxKind.AbstractKeyword);\n}\n\n// webpieces-disable no-function-outside-class -- pure AST predicate, matching the sibling helpers in di-graph/bindings.ts\nexport function hasClassDecorator(cls: ts.ClassDeclaration, name: string): boolean {\n    return classDecorators(cls).some((d: ts.Decorator) => decoratorName(d) === name);\n}\n\n/**\n * The service a client-factory call aims at, from its config argument:\n * `createRpcClient(WarmupApi, new ClientConfig('helper-fsdb'))` → `'helper-fsdb'`.\n *\n * Only a `new <Xxx>ClientConfig('<string literal>')` yields a name. A variable, a template string\n * or a computed expression yields null — the target is genuinely unknown at scan time, and the\n * runtime graph must fall back to fan-out (loudly) rather than guess.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function targetServiceOf(call: ts.CallExpression): string | null {\n    if (call.arguments.length < 2) return null;\n    const config = call.arguments[1];\n    if (!ts.isNewExpression(config) || !ts.isIdentifier(config.expression)) return null;\n    if (!config.expression.text.endsWith(CLIENT_CONFIG_SUFFIX)) return null;\n    const first = config.arguments?.[0];\n    if (first === undefined || !ts.isStringLiteral(first)) return null;\n    return first.text.length > 0 ? first.text : null;\n}\n\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function calleeMethodName(call: ts.CallExpression): string | null {\n    const callee = call.expression;\n    if (ts.isPropertyAccessExpression(callee)) return callee.name.text;\n    if (ts.isIdentifier(callee)) return callee.text;\n    return null;\n}\n\n// webpieces-disable no-function-outside-class -- pure path predicate, matching the sibling helpers in di-graph/bindings.ts\nexport function isTestFile(fileName: string): boolean {\n    return (\n        fileName.includes('/__tests__/') ||\n        fileName.includes('.spec.') ||\n        fileName.includes('.test.')\n    );\n}\n\n\n/** {api, owner, type:'rpc'|'pubsub'} for an in-repo contract class, else null. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function apiClassInfoFromNode(\n    node: ts.Node,\n    project: string,\n    diagnostics: DecoratorArgDiagnostics | null = null,\n): ApiClassInfo | null {\n    return ts.isClassDeclaration(node) ? apiClassInfoFrom(node, project, diagnostics) : null;\n}\n\n/**\n * {api, owner, type:'external'} for a VENDOR contract, else null.\n *\n * A vendor contract cannot be detected the way an in-repo one is. It carries no @ApiPath (there is\n * no route — the call leaves through a vendor SDK), and it is usually a plain `interface` bound to a\n * Symbol token, which is not even a class. So inside a project the workspace has DECLARED external\n * (`runtime-architecture.externalApiPaths`) the signal is structural instead: an exported\n * `interface`/`abstract class` whose name ends in `Api`. That deliberately picks up `GmailApi` and\n * `StorageApi` while leaving their DTOs, `*Config` types and `*Client` implementations alone.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function externalApiInfoFrom(node: ts.Node, project: string): ApiClassInfo | null {\n    const named = ts.isInterfaceDeclaration(node) || (ts.isClassDeclaration(node) && isAbstractClass(node));\n    if (!named || !node.name || !isExported(node)) return null;\n    const api = node.name.text;\n    if (!api.endsWith(EXTERNAL_CONTRACT_SUFFIX)) return null;\n    const externalSystem = externalSystemTagFrom(node, api);\n    return externalSystem === null\n        ? { api, owner: project, type: 'external', methods: [] }\n        : { api, owner: project, type: 'external', methods: [], externalSystem };\n}\n\n/**\n * The `@externalSystem <kind> [label]` JSDoc tag on a vendor contract, or null when absent.\n *\n * JSDoc rather than a decorator is not a style choice: these seams are TS `interface`s, and TS has\n * no interface decorators. Without the tag the contract still renders — as the generic dashed box it\n * always was — so this is purely additive and nothing needs migrating.\n *\n * The label defaults to the contract name minus its `Api` suffix (`FirestoreAdminApi` →\n * `FirestoreAdmin`), because the label is the node IDENTITY: two contracts that mean the same system\n * must be given the SAME explicit label to converge on one node.\n *\n * An unrecognised kind is ignored rather than defaulted. Silently drawing a `@externalSystem\n * databse` typo as a generic box is recoverable; drawing it as the wrong shape teaches the reader\n * something false about the architecture.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function externalSystemTagFrom(node: ts.Node, api: string): ExternalSystemDeclaration | null {\n    for (const tag of ts.getJSDocTags(node)) {\n        if (tag.tagName.text !== EXTERNAL_SYSTEM_TAG) continue;\n        const comment = typeof tag.comment === 'string' ? tag.comment : '';\n        const parts = comment.trim().split(/\\s+/).filter((part: string) => part !== '');\n        if (parts.length === 0) continue;\n        const kind = parts[0].toLowerCase();\n        if (!isExternalSystemKind(kind)) continue;\n        const label = parts.slice(1).join(' ').trim();\n        return { kind, label: label === '' ? api.replace(/Api$/, '') : label };\n    }\n    return null;\n}\n\n/** True when the declaration carries an `export` modifier. */\n// webpieces-disable no-function-outside-class -- pure AST predicate, matching the sibling helpers in di-graph/bindings.ts\nexport function isExported(node: ts.InterfaceDeclaration | ts.ClassDeclaration): boolean {\n    return (ts.getModifiers(node) ?? []).some((m: ts.Modifier) => m.kind === ts.SyntaxKind.ExportKeyword);\n}\n\n// webpieces-disable no-function-outside-class -- recursive fs walker, matching the AST-helper style here\nexport function collectTsFiles(dir: string): string[] {\n    const out: string[] = [];\n    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {\n        const full = path.join(dir, entry.name);\n        if (entry.isDirectory()) {\n            if (entry.name !== 'node_modules') out.push(...collectTsFiles(full));\n        } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {\n            out.push(full);\n        }\n    }\n    return out;\n}\n"]}
+{"version":3,"file":"api-ast.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-ast.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * API contract AST accessors\n *\n * The pure, stateless half of the api scan: given a TypeScript node, what contract / endpoint /\n * injected type does it describe? Split out of api-scanner.ts, which owns the STATEFUL walk (project\n * programs, the source index, relation accumulation) and had grown past the file-size limit.\n *\n * Everything here is parser-level on purpose. Decorators must be read exactly as written, and a\n * plain parse cannot be diverted to a decorator-erased `.d.ts` by module resolution — the bug\n * api-scanner's source pre-pass exists to guard against.\n */\n\nimport * as ts from 'typescript';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { classDecorators, decoratorName } from '../di-graph/bindings';\nimport {\n    ApiClassInfo,\n    ApiMethodMeta,\n    ApiParameterMeta,\n    ContractHttpMethod,\n    ApiTransport,\n    EmptiedApiContract,\n    EndpointKind,\n    ExternalSystemDeclaration,\n    isExternalSystemKind,\n    NonLiteralDecoratorArg,\n    UndeclaredExternalCaller,\n    UnresolvedEndpointPath,\n} from './api-relations';\n\n/** Legal `@Endpoint(path, kind)` values; anything else is a source error, not a kind we invent. */\nconst ENDPOINT_KINDS: readonly EndpointKind[] = ['rpc', 'cloudtasks', 'cron', 'external'];\n\n/**\n * Name suffix that marks an exported type in an `externalApiPaths` project as a vendor CONTRACT\n * (`GmailApi`, `StorageApi`) rather than one of the DTOs, configs or clients sitting beside it.\n * The same convention the in-repo contracts already follow, applied where no decorator can be read.\n */\nconst EXTERNAL_CONTRACT_SUFFIX = 'Api';\n\n/** JSDoc tag a vendor contract uses to declare WHAT it is a seam to: `@externalSystem database Firestore`. */\nconst EXTERNAL_SYSTEM_TAG = 'externalSystem';\n\n/**\n * Client-config class-name suffix whose FIRST constructor argument is the target service name —\n * `ClientConfig('helper-fsdb')` (rpc) and `TaskClientConfig('helper-fsdb')` (pubsub) both take\n * `svcName` first, and a consumer's own `XxxClientConfig` follows the same shape.\n */\nconst CLIENT_CONFIG_SUFFIX = 'ClientConfig';\n\n/**\n * The module-scope `const NAME = '<string literal>'` bindings of ONE source file.\n *\n * A contract that hoists its route to a constant (`@ApiPath(WHATSAPP_API_PATH)`) is good practice —\n * it lets a sibling contract and its callers share the symbol — but a decorator argument is read as\n * TEXT here, with no checker to constant-fold it. Without this table such an argument resolved to\n * nothing: the class lost its basePath, and a class whose every @Endpoint path was a constant\n * resolved to zero methods and was dropped from the graph entirely.\n *\n * Deliberately SAME-MODULE only. Following an import would mean resolving modules, which is exactly\n * what the source pre-pass avoids (it can be diverted to a decorator-erased `.d.ts`). A cross-module\n * constant is therefore still unresolvable — and is REPORTED rather than silently dropped, see\n * DecoratorArgDiagnostics.\n */\nexport class ModuleStringConstants {\n    constructor(private readonly byName: Map<string, string>) {}\n\n    lookup(name: string): string | null {\n        return this.byName.get(name) ?? null;\n    }\n}\n\n/** Parsed constants per source file — every class in a file shares one table. */\nconst CONSTANTS_BY_FILE = new WeakMap<ts.SourceFile, ModuleStringConstants>();\n\n/** The module-scope string constants of `sourceFile`, parsed once per file. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function stringConstantsOf(sourceFile: ts.SourceFile): ModuleStringConstants {\n    const cached = CONSTANTS_BY_FILE.get(sourceFile);\n    if (cached !== undefined) return cached;\n    const byName = new Map<string, string>();\n    for (const statement of sourceFile.statements) {\n        if (!ts.isVariableStatement(statement)) continue;\n        if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;\n        for (const declaration of statement.declarationList.declarations) {\n            if (!ts.isIdentifier(declaration.name)) continue;\n            const text = stringValueOf(declaration.initializer);\n            if (text !== null) byName.set(declaration.name.text, text);\n        }\n    }\n    const constants = new ModuleStringConstants(byName);\n    CONSTANTS_BY_FILE.set(sourceFile, constants);\n    return constants;\n}\n\n/** The string an initializer denotes, unwrapping `as const` / parentheses, else null. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function stringValueOf(expr: ts.Expression | undefined): string | null {\n    if (expr === undefined) return null;\n    if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) return expr.text;\n    if (ts.isAsExpression(expr) || ts.isParenthesizedExpression(expr))\n        return stringValueOf(expr.expression);\n    return null;\n}\n\n/**\n * ONE decorator argument that had to be a string, and what came of it.\n *\n * `value` is the string when it was a literal or resolved through a same-module constant.\n * `unresolvedName` is the argument as written (`WHATSAPP_API_PATH`) when it is present but could not\n * be reduced — the case that must be reported, never silently dropped. Both are null when the\n * argument is simply absent.\n */\nexport class DecoratorArgValue {\n    constructor(\n        public readonly value: string | null,\n        public readonly unresolvedName: string | null,\n    ) {}\n}\n\n/** Read one decorator argument as a string, resolving same-module constants. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function decoratorArgValue(\n    expr: ts.Expression | undefined,\n    constants: ModuleStringConstants,\n): DecoratorArgValue {\n    if (expr === undefined) return new DecoratorArgValue(null, null);\n    const literal = stringValueOf(expr);\n    if (literal !== null) return new DecoratorArgValue(literal, null);\n    if (ts.isIdentifier(expr)) {\n        const resolved = constants.lookup(expr.text);\n        if (resolved !== null) return new DecoratorArgValue(resolved, null);\n        return new DecoratorArgValue(null, expr.text);\n    }\n    return new DecoratorArgValue(null, expr.getText());\n}\n\n/**\n * Collects everything this parser-only pass had to drop: decorator arguments it could not reduce to\n * a string, plus the two of those that are FATAL rather than merely lossy.\n *\n * A same-module constant now resolves, but a cross-module one (`import { PATH } from './paths'`)\n * genuinely cannot — the source pre-pass has no checker by design. That gap used to be invisible:\n * the contract simply came out with no basePath, or with fewer methods, or not at all. Recording it\n * turns a silent drop into a named one, pointing at the exact file, line and identifier.\n *\n * Three sinks, because the consequences differ. `record` is the warning stream (a @Queue name falls\n * back to a derived one, so the graph is degraded, not wrong). `recordUnresolvedPath` and\n * `recordEmptiedContract` are collected so generation can FAIL — one aggregated error naming every\n * offender, because an author fixing five constants wants all five in one run.\n */\nexport class DecoratorArgDiagnostics {\n    private readonly found: NonLiteralDecoratorArg[] = [];\n    private readonly unresolvedPaths: UnresolvedEndpointPath[] = [];\n    private readonly emptied: EmptiedApiContract[] = [];\n    private readonly undeclaredCallers: UndeclaredExternalCaller[] = [];\n\n    constructor(private readonly workspaceRoot: string) {}\n\n    /** Record `argument` (as written) as unresolvable at `node`'s location. */\n    record(\n        api: string,\n        decorator: string,\n        method: string | null,\n        argument: string,\n        node: ts.Node,\n    ): void {\n        this.found.push(\n            new NonLiteralDecoratorArg(api, decorator, method, argument, this.locate(node)),\n        );\n    }\n\n    /** Record an `@Endpoint` whose path argument is unreadable — fatal, see UnresolvedEndpointPathError. */\n    recordUnresolvedPath(api: string, method: string, argument: string, node: ts.Node): void {\n        this.unresolvedPaths.push(\n            new UnresolvedEndpointPath(api, method, argument, this.locate(node)),\n        );\n    }\n\n    /** Record a class that declared `declared` `@Endpoint` methods and kept none of them. */\n    recordEmptiedContract(api: string, declared: number, node: ts.Node): void {\n        this.emptied.push(new EmptiedApiContract(api, declared, this.locate(node)));\n    }\n\n    /** Record an `external` `@Endpoint` whose caller is unreadable — fatal, see UndeclaredExternalCallerError. */\n    recordUndeclaredCaller(api: string, method: string, argument: string, node: ts.Node): void {\n        this.undeclaredCallers.push(\n            new UndeclaredExternalCaller(api, method, argument, this.locate(node)),\n        );\n    }\n\n    all(): NonLiteralDecoratorArg[] {\n        return this.found;\n    }\n\n    unresolvedEndpointPaths(): UnresolvedEndpointPath[] {\n        return this.unresolvedPaths;\n    }\n\n    emptiedContracts(): EmptiedApiContract[] {\n        return this.emptied;\n    }\n\n    undeclaredExternalCallers(): UndeclaredExternalCaller[] {\n        return this.undeclaredCallers;\n    }\n\n    private locate(node: ts.Node): string {\n        const sourceFile = node.getSourceFile();\n        const position = sourceFile.getLineAndCharacterOfPosition(node.getStart());\n        return `${path.relative(this.workspaceRoot, sourceFile.fileName)}:${position.line + 1}`;\n    }\n}\n\n/** {api, owner: `project`, type} when `cls` is an `abstract class` carrying `@ApiPath`, else null. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function apiClassInfoFrom(\n    cls: ts.ClassDeclaration,\n    project: string,\n    diagnostics: DecoratorArgDiagnostics | null = null,\n): ApiClassInfo | null {\n    if (!isAbstractClass(cls) || !hasClassDecorator(cls, 'ApiPath') || !cls.name) return null;\n    const api = cls.name.text;\n    const constants = stringConstantsOf(cls.getSourceFile());\n    const info: ApiClassInfo = {\n        api,\n        owner: project,\n        type: apiTransport(cls),\n        methods: endpointMethodsOf(cls, api, constants, diagnostics),\n    };\n    const basePath = decoratorStringArg(cls, 'ApiPath', constants, diagnostics, api);\n    if (basePath !== null) info.basePath = basePath;\n    return info;\n}\n\n// webpieces-disable no-function-outside-class -- pure AST predicate, matching the sibling helpers in di-graph/bindings.ts\nexport function apiTransport(cls: ts.ClassDeclaration): ApiTransport {\n    return hasClassDecorator(cls, 'PubSub') ? 'pubsub' : 'rpc';\n}\n\n/** The @Endpoint kinds that are actually DELIVERED through a named queue or schedule. */\nconst QUEUED_KINDS: readonly EndpointKind[] = ['cloudtasks', 'cron'];\n\n/**\n * Every `@Endpoint(path, kind)` method on a contract class, in declaration order.\n *\n * `kind` is a REQUIRED argument of the decorator, so a missing/non-literal second argument means the\n * source does not compile (or is mid-edit) — we skip the method rather than defaulting it. Defaulting\n * would put an undeclared cron or webhook into the graph as an ordinary rpc call, which is precisely\n * the blindness the required argument exists to remove.\n *\n * `path` is NOT skippable. It may be a same-module constant; an argument that is present but still\n * cannot be reduced is recorded on `diagnostics` as an UnresolvedEndpointPath, which FAILS generation\n * later. Upstream components need the URL — a client computes its request as `basePath + path` — so\n * dropping the method here shipped a contract missing routing information, and a class whose every\n * path was a constant lost every method and disappeared from the graph entirely.\n *\n * A class that declared endpoints and kept NONE of them is recorded too: `buildApiContracts` skips\n * zero-method classes, which is the door a gutted contract used to leave through unannounced.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function endpointMethodsOf(\n    cls: ts.ClassDeclaration,\n    api: string,\n    constants: ModuleStringConstants = new ModuleStringConstants(new Map<string, string>()),\n    diagnostics: DecoratorArgDiagnostics | null = null,\n): ApiMethodMeta[] {\n    const methods: ApiMethodMeta[] = [];\n    let declared = 0;\n    for (const member of cls.members) {\n        if (!ts.isMethodDeclaration(member) || !ts.isIdentifier(member.name)) continue;\n        const endpoint = memberDecorator(member, 'Endpoint');\n        if (endpoint === null) continue;\n        declared++;\n        const name = member.name.text;\n        const args = decoratorArgs(endpoint);\n        const pathArg = decoratorArgValue(args[0], constants);\n        const kindArg = decoratorArgValue(args[1], constants);\n        reportUnresolved(diagnostics, api, 'Endpoint', name, pathArg, endpoint);\n        reportUnresolved(diagnostics, api, 'Endpoint', name, kindArg, endpoint);\n        if (diagnostics !== null && pathArg.unresolvedName !== null) {\n            diagnostics.recordUnresolvedPath(api, name, pathArg.unresolvedName, endpoint);\n        }\n        const kind = kindArg.value;\n        if (\n            pathArg.value === null ||\n            kind === null ||\n            !ENDPOINT_KINDS.includes(kind as EndpointKind)\n        )\n            continue;\n        const httpMethod = httpMethodOf(args[2], constants, diagnostics, api, name, endpoint);\n        const method: ApiMethodMeta = {\n            name,\n            path: pathArg.value,\n            kind: kind as EndpointKind,\n            httpMethod,\n        };\n        const parameters = httpParametersOf(\n            member,\n            httpMethod,\n            constants,\n            diagnostics,\n            api,\n            name,\n        );\n        if (parameters.length > 0) method.parameters = parameters;\n        if (endpointResponseTypeOf(args[2], constants) === 'full') method.responseType = 'full';\n        // Only a queued or scheduled endpoint HAS a queue. Naming one for a synchronous rpc invited a\n        // tool to read `methods.map(m => m.queueName)` as a provisioning list and create queues that\n        // nothing will ever deliver to.\n        if (QUEUED_KINDS.includes(method.kind)) {\n            method.queueName = queueNameOf(member, api, name, constants, diagnostics);\n        }\n        // Only an `external` endpoint HAS an outside caller, mirroring the queue rule above. A\n        // caller recorded on an rpc method would be a fact about nothing, and would put a vendor\n        // box on the graph beside an endpoint no vendor calls.\n        if (method.kind === 'external') {\n            const caller = externalCallerOf(args[2], constants);\n            if (caller.declaration !== null) method.caller = caller.declaration;\n            else if (diagnostics !== null)\n                diagnostics.recordUndeclaredCaller(api, name, caller.problem!, endpoint);\n        }\n        methods.push(method);\n    }\n    // Declared endpoints, kept none: the class is about to be skipped as \"zero methods\" and would\n    // leave no trace. Never legitimate — a routeless contract declares no @Endpoint at all.\n    if (diagnostics !== null && declared > 0 && methods.length === 0) {\n        diagnostics.recordEmptiedContract(api, declared, cls);\n    }\n    return methods;\n}\n\n/** `@Endpoint(..., { httpMethod: 'GET' })`, defaulting to the runtime's POST default. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers\nexport function httpMethodOf(\n    options: ts.Expression | undefined,\n    constants: ModuleStringConstants,\n    diagnostics: DecoratorArgDiagnostics | null,\n    api: string,\n    method: string,\n    node: ts.Node,\n): ContractHttpMethod {\n    if (options === undefined || !ts.isObjectLiteralExpression(options)) return 'POST';\n    const declared = objectPropertyValue(options, 'httpMethod', constants);\n    reportUnresolved(diagnostics, api, 'Endpoint.httpMethod', method, declared, node);\n    return declared.value === 'GET' ? 'GET' : 'POST';\n}\n\n/** Only the non-default full-response marker needs an architecture field. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers\nexport function endpointResponseTypeOf(\n    options: ts.Expression | undefined,\n    constants: ModuleStringConstants,\n): 'body' | 'full' {\n    if (options === undefined || !ts.isObjectLiteralExpression(options)) return 'body';\n    return objectPropertyValue(options, 'responseType', constants).value === 'full'\n        ? 'full'\n        : 'body';\n}\n\n/** Explicit `@PathParam` / `@QueryParam` mappings in source declaration order. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers\nexport function httpParametersOf(\n    member: ts.MethodDeclaration,\n    httpMethod: ContractHttpMethod,\n    constants: ModuleStringConstants,\n    diagnostics: DecoratorArgDiagnostics | null,\n    api: string,\n    method: string,\n): ApiParameterMeta[] {\n    const parameters: ApiParameterMeta[] = [];\n    member.parameters.forEach((parameter: ts.ParameterDeclaration, index: number) => {\n        let mapped = false;\n        for (const source of ['path', 'query'] as const) {\n            const decoratorNameWanted = source === 'path' ? 'PathParam' : 'QueryParam';\n            const decorator = decoratorOn(parameter, decoratorNameWanted);\n            if (decorator === null) continue;\n            mapped = true;\n            const wireName = decoratorArgValue(decoratorArgs(decorator)[0], constants);\n            reportUnresolved(diagnostics, api, decoratorNameWanted, method, wireName, decorator);\n            if (wireName.value !== null) {\n                parameters.push({ index, source, wireName: wireName.value });\n            }\n        }\n        if (!mapped && httpMethod === 'POST') parameters.push({ index, source: 'body' });\n    });\n    return parameters;\n}\n\n/** Default `callerKind` when an `external` endpoint declares `calledBy` alone — mirrors core-util. */\nconst DEFAULT_CALLER_KIND = 'saas';\n\n/**\n * The outcome of reading `@Endpoint(path, 'external', { calledBy, callerKind })`'s third argument:\n * either the resolved declaration, or the reason it could not be resolved (never both).\n */\nexport class ExternalCallerRead {\n    constructor(\n        public readonly declaration: ExternalSystemDeclaration | null,\n        /** What was wrong, as written, for the diagnostic. Null exactly when `declaration` is set. */\n        public readonly problem: string | null,\n    ) {}\n}\n\n/**\n * Read the declared caller out of the @Endpoint OPTIONS OBJECT LITERAL — `args[2]`, not a positional\n * argument, because that is where `formPost` already lives and one options bag beats two.\n *\n * Everything unreadable is a PROBLEM, never a default: an unknown `callerKind` draws the wrong shape\n * (which teaches the reader something false), and a missing `calledBy` puts us back at a box that can\n * only name our own contract. The kind default applies ONLY to the case the API deliberately allows —\n * `calledBy` present, `callerKind` absent.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function externalCallerOf(\n    arg: ts.Expression | undefined,\n    constants: ModuleStringConstants,\n): ExternalCallerRead {\n    if (arg === undefined) return new ExternalCallerRead(null, '<no options argument>');\n    if (!ts.isObjectLiteralExpression(arg)) return new ExternalCallerRead(null, arg.getText());\n    const calledBy = objectPropertyValue(arg, 'calledBy', constants);\n    if (calledBy.value === null || calledBy.value === '') {\n        return new ExternalCallerRead(null, calledBy.unresolvedName ?? '<no calledBy>');\n    }\n    const callerKind = objectPropertyValue(arg, 'callerKind', constants);\n    if (callerKind.value === null && callerKind.unresolvedName !== null) {\n        return new ExternalCallerRead(null, `callerKind: ${callerKind.unresolvedName}`);\n    }\n    const kind = callerKind.value ?? DEFAULT_CALLER_KIND;\n    if (!isExternalSystemKind(kind)) return new ExternalCallerRead(null, `callerKind: '${kind}'`);\n    return new ExternalCallerRead({ kind, label: calledBy.value }, null);\n}\n\n/** One property of an object literal, read as a string through the same constant folding as an argument. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function objectPropertyValue(\n    literal: ts.ObjectLiteralExpression,\n    name: string,\n    constants: ModuleStringConstants,\n): DecoratorArgValue {\n    for (const property of literal.properties) {\n        if (!ts.isPropertyAssignment(property) || property.name === undefined) continue;\n        const key =\n            ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)\n                ? property.name.text\n                : null;\n        if (key !== name) continue;\n        return decoratorArgValue(property.initializer, constants);\n    }\n    return new DecoratorArgValue(null, null);\n}\n\n/** `@Queue('...')` override when present and resolvable, else the derived `${Api}-${method}`. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function queueNameOf(\n    member: ts.MethodDeclaration,\n    api: string,\n    name: string,\n    constants: ModuleStringConstants,\n    diagnostics: DecoratorArgDiagnostics | null,\n): string {\n    const override = memberDecorator(member, 'Queue');\n    if (override === null) return `${api}-${name}`;\n    const queueArg = decoratorArgValue(decoratorArgs(override)[0], constants);\n    reportUnresolved(diagnostics, api, 'Queue', name, queueArg, override);\n    return queueArg.value ?? `${api}-${name}`;\n}\n\n/** Record an argument that is present but unresolvable; a resolved or absent one is silent. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function reportUnresolved(\n    diagnostics: DecoratorArgDiagnostics | null,\n    api: string,\n    decorator: string,\n    method: string | null,\n    arg: DecoratorArgValue,\n    node: ts.Node,\n): void {\n    if (diagnostics === null || arg.unresolvedName === null) return;\n    diagnostics.record(api, decorator, method, arg.unresolvedName, node);\n}\n\n/** The arguments of a decorator's call expression, or [] when it is a bare `@Foo` reference. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function decoratorArgs(\n    decorator: ts.Decorator,\n): ts.NodeArray<ts.Expression> | ts.Expression[] {\n    return ts.isCallExpression(decorator.expression) ? decorator.expression.arguments : [];\n}\n\n/** The named decorator on a class member, or null. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function memberDecorator(member: ts.ClassElement, name: string): ts.Decorator | null {\n    const decorators = ts.getDecorators(member as ts.HasDecorators) ?? [];\n    return decorators.find((d: ts.Decorator) => decoratorName(d) === name) ?? null;\n}\n\n/** The named decorator on any decorator-capable AST node (notably a method parameter). */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching memberDecorator\nexport function decoratorOn(node: ts.HasDecorators, name: string): ts.Decorator | null {\n    const decorators = ts.getDecorators(node) ?? [];\n    return decorators.find((decorator: ts.Decorator) => decoratorName(decorator) === name) ?? null;\n}\n\n/**\n * The first argument of a class decorator as a string (`@ApiPath('/x')`, `@ApiPath(X_PATH)`), else\n * null. A same-module constant resolves; anything else is recorded on `diagnostics`.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function decoratorStringArg(\n    cls: ts.ClassDeclaration,\n    name: string,\n    constants: ModuleStringConstants = new ModuleStringConstants(new Map<string, string>()),\n    diagnostics: DecoratorArgDiagnostics | null = null,\n    api: string = name,\n): string | null {\n    const decorator = classDecorators(cls).find((d: ts.Decorator) => decoratorName(d) === name);\n    if (decorator === undefined) return null;\n    const arg = decoratorArgValue(decoratorArgs(decorator)[0], constants);\n    reportUnresolved(diagnostics, api, name, null, arg, decorator);\n    return arg.value;\n}\n\n/** The constructor's parameters, or [] when the class declares no constructor. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function constructorParamsOf(cls: ts.ClassDeclaration): readonly ts.ParameterDeclaration[] {\n    for (const member of cls.members) {\n        if (ts.isConstructorDeclaration(member)) return member.parameters;\n    }\n    return [];\n}\n\n/**\n * The bare name of a type reference (`GmailApi`, or `gmail.GmailApi` -> `GmailApi`), else null.\n * Generic wrappers are deliberately NOT unwrapped: `Provider<GmailApi>` hands out the contract\n * lazily, which is still a use, but it is not the shape any of these seams take today and guessing\n * at type arguments would start matching things that merely mention a contract.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function typeReferenceName(type: ts.TypeNode | undefined): string | null {\n    if (type === undefined || !ts.isTypeReferenceNode(type)) return null;\n    const name = type.typeName;\n    if (ts.isIdentifier(name)) return name.text;\n    return ts.isQualifiedName(name) && ts.isIdentifier(name.right) ? name.right.text : null;\n}\n\n/** Every type name in the class's `implements` clause — the contracts this class IS, not ones it calls. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function implementedTypeNames(cls: ts.ClassDeclaration): Set<string> {\n    const names = new Set<string>();\n    for (const clause of cls.heritageClauses ?? []) {\n        if (clause.token !== ts.SyntaxKind.ImplementsKeyword) continue;\n        for (const type of clause.types) {\n            if (ts.isIdentifier(type.expression)) names.add(type.expression.text);\n        }\n    }\n    return names;\n}\n\n// webpieces-disable no-function-outside-class -- pure AST predicate, matching the sibling helpers in di-graph/bindings.ts\nexport function isAbstractClass(cls: ts.ClassDeclaration): boolean {\n    return (ts.getModifiers(cls) ?? []).some(\n        (m: ts.Modifier) => m.kind === ts.SyntaxKind.AbstractKeyword,\n    );\n}\n\n// webpieces-disable no-function-outside-class -- pure AST predicate, matching the sibling helpers in di-graph/bindings.ts\nexport function hasClassDecorator(cls: ts.ClassDeclaration, name: string): boolean {\n    return classDecorators(cls).some((d: ts.Decorator) => decoratorName(d) === name);\n}\n\n/**\n * The service a client-factory call aims at, from its config argument:\n * `createRpcClient(WarmupApi, new ClientConfig('helper-fsdb'))` → `'helper-fsdb'`.\n *\n * Only a `new <Xxx>ClientConfig('<string literal>')` yields a name. A variable, a template string\n * or a computed expression yields null — the target is genuinely unknown at scan time, and the\n * runtime graph must fall back to fan-out (loudly) rather than guess.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function targetServiceOf(call: ts.CallExpression): string | null {\n    if (call.arguments.length < 2) return null;\n    const config = call.arguments[1];\n    if (!ts.isNewExpression(config) || !ts.isIdentifier(config.expression)) return null;\n    if (!config.expression.text.endsWith(CLIENT_CONFIG_SUFFIX)) return null;\n    const first = config.arguments?.[0];\n    if (first === undefined || !ts.isStringLiteral(first)) return null;\n    return first.text.length > 0 ? first.text : null;\n}\n\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function calleeMethodName(call: ts.CallExpression): string | null {\n    const callee = call.expression;\n    if (ts.isPropertyAccessExpression(callee)) return callee.name.text;\n    if (ts.isIdentifier(callee)) return callee.text;\n    return null;\n}\n\n// webpieces-disable no-function-outside-class -- pure path predicate, matching the sibling helpers in di-graph/bindings.ts\nexport function isTestFile(fileName: string): boolean {\n    return (\n        fileName.includes('/__tests__/') ||\n        fileName.includes('.spec.') ||\n        fileName.includes('.test.')\n    );\n}\n\n/** {api, owner, type:'rpc'|'pubsub'} for an in-repo contract class, else null. */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function apiClassInfoFromNode(\n    node: ts.Node,\n    project: string,\n    diagnostics: DecoratorArgDiagnostics | null = null,\n): ApiClassInfo | null {\n    return ts.isClassDeclaration(node) ? apiClassInfoFrom(node, project, diagnostics) : null;\n}\n\n/**\n * {api, owner, type:'external'} for a VENDOR contract, else null.\n *\n * A vendor contract cannot be detected the way an in-repo one is. It carries no @ApiPath (there is\n * no route — the call leaves through a vendor SDK), and it is usually a plain `interface` bound to a\n * Symbol token, which is not even a class. So inside a project the workspace has DECLARED external\n * (`runtime-architecture.externalApiPaths`) the signal is structural instead: an exported\n * `interface`/`abstract class` whose name ends in `Api`. That deliberately picks up `GmailApi` and\n * `StorageApi` while leaving their DTOs, `*Config` types and `*Client` implementations alone.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function externalApiInfoFrom(node: ts.Node, project: string): ApiClassInfo | null {\n    const named =\n        ts.isInterfaceDeclaration(node) || (ts.isClassDeclaration(node) && isAbstractClass(node));\n    if (!named || !node.name || !isExported(node)) return null;\n    const api = node.name.text;\n    if (!api.endsWith(EXTERNAL_CONTRACT_SUFFIX)) return null;\n    const externalSystem = externalSystemTagFrom(node, api);\n    return externalSystem === null\n        ? { api, owner: project, type: 'external', methods: [] }\n        : { api, owner: project, type: 'external', methods: [], externalSystem };\n}\n\n/**\n * The `@externalSystem <kind> [label]` JSDoc tag on a vendor contract, or null when absent.\n *\n * JSDoc rather than a decorator is not a style choice: these seams are TS `interface`s, and TS has\n * no interface decorators. Without the tag the contract still renders — as the generic dashed box it\n * always was — so this is purely additive and nothing needs migrating.\n *\n * The label defaults to the contract name minus its `Api` suffix (`FirestoreAdminApi` →\n * `FirestoreAdmin`), because the label is the node IDENTITY: two contracts that mean the same system\n * must be given the SAME explicit label to converge on one node.\n *\n * An unrecognised kind is ignored rather than defaulted. Silently drawing a `@externalSystem\n * databse` typo as a generic box is recoverable; drawing it as the wrong shape teaches the reader\n * something false about the architecture.\n */\n// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts\nexport function externalSystemTagFrom(\n    node: ts.Node,\n    api: string,\n): ExternalSystemDeclaration | null {\n    for (const tag of ts.getJSDocTags(node)) {\n        if (tag.tagName.text !== EXTERNAL_SYSTEM_TAG) continue;\n        const comment = typeof tag.comment === 'string' ? tag.comment : '';\n        const parts = comment\n            .trim()\n            .split(/\\s+/)\n            .filter((part: string) => part !== '');\n        if (parts.length === 0) continue;\n        const kind = parts[0].toLowerCase();\n        if (!isExternalSystemKind(kind)) continue;\n        const label = parts.slice(1).join(' ').trim();\n        return { kind, label: label === '' ? api.replace(/Api$/, '') : label };\n    }\n    return null;\n}\n\n/** True when the declaration carries an `export` modifier. */\n// webpieces-disable no-function-outside-class -- pure AST predicate, matching the sibling helpers in di-graph/bindings.ts\nexport function isExported(node: ts.InterfaceDeclaration | ts.ClassDeclaration): boolean {\n    return (ts.getModifiers(node) ?? []).some(\n        (m: ts.Modifier) => m.kind === ts.SyntaxKind.ExportKeyword,\n    );\n}\n\n// webpieces-disable no-function-outside-class -- recursive fs walker, matching the AST-helper style here\nexport function collectTsFiles(dir: string): string[] {\n    const out: string[] = [];\n    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {\n        const full = path.join(dir, entry.name);\n        if (entry.isDirectory()) {\n            if (entry.name !== 'node_modules') out.push(...collectTsFiles(full));\n        } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {\n            out.push(full);\n        }\n    }\n    return out;\n}\n"]}

package/src/lib/api-usage/api-relations.d.ts

@@ -113,6 +113,15 @@ export type ProjectApiRelations = Record<string, ApiRelation>;
  * different @webpieces version than the tooling itself).
  */
 export type EndpointKind = 'rpc' | 'cloudtasks' | 'cron' | 'external';
+/** HTTP verbs understood by the generated contract runtime. */
+export type ContractHttpMethod = 'GET' | 'POST';
+/** One path/query/body mapping emitted into architecture/dependencies.json. */
+export interface ApiParameterMeta {
+    index: number;
+    source: 'path' | 'query' | 'body';
+    /** Path/query wire name; a JSON/form body occupies the whole entity and has no key. */
+    wireName?: string;
+}
 /**
  * One method on an API contract, as written in source: what triggers it, where it is mounted, and
  * (for a queued method) which Cloud Tasks queue delivers it.
@@ -122,6 +131,12 @@ export interface ApiMethodMeta {
     /** The @Endpoint path, relative to the class's @ApiPath basePath. */
     path: string;
     kind: EndpointKind;
+    /** The actual incoming/outgoing verb; POST when @Endpoint omits httpMethod. */
+    httpMethod?: ContractHttpMethod;
+    /** Explicit parameter mappings; absent only when the method has none. */
+    parameters?: ApiParameterMeta[];
+    /** Present when callers receive the transport-neutral full response. */
+    responseType?: 'full';
     /**
      * `@Queue(...)` override, else `${ApiClassName}-${methodName}`.
      *

package/src/lib/api-usage/api-relations.js

@@ -198,6 +198,7 @@ function deriveApiRelationKind(implementsRefs, usesRefs) {
  */
 // webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs
 function sortApiRefs(refs) {
-    return [...refs].sort((a, b) => a.api.localeCompare(b.api) || (a.targetService ?? '').localeCompare(b.targetService ?? ''));
+    return [...refs].sort((a, b) => a.api.localeCompare(b.api) ||
+        (a.targetService ?? '').localeCompare(b.targetService ?? ''));
 }
 //# sourceMappingURL=api-relations.js.map

package/src/lib/api-usage/api-relations.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-relations.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-relations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * API Relations model\n *\n * The typed classification of a compile-time dependency edge P -> apiLib in\n * architecture/dependencies.json. Where the flat `dependsOn` only says \"P depends\n * on apiLib\", `apiRelations[apiLib]` says WHY: which API contracts P IMPLEMENTS\n * (serves, `class Ctrl extends XxxApi`) and which it USES (calls as a client,\n * `factory.createRpcClient(XxxApi, ...)` / `createPubSubClient(...)`), each tagged\n * with its transport.\n *\n * Interfaces + object literals here mirror the sibling runtime-graph.ts model —\n * these are serialization DTOs written verbatim into the committed JSON, and\n * `implements`/`uses` are legal interface property names (they are reserved words\n * only as binding identifiers, not as member names).\n */\n\n/**\n * Transport of an API contract:\n *  - `rpc`      — synchronous request/response over HTTP\n *  - `pubsub`   — fire-and-forget, delivered later through a Cloud Tasks queue\n *  - `external` — a contract for a system OUTSIDE this repo (firestore, gmail, ...). Nothing in-repo\n *                 implements it, so it never becomes a service→service edge; it terminates the graph\n *                 at a dashed vendor node. Detected from `runtime-architecture.externalApiPaths`\n *                 rather than from a decorator, because a vendor contract is a plain interface bound\n *                 to a Symbol token, not an `abstract class` carrying @ApiPath.\n */\nexport type ApiTransport = 'rpc' | 'pubsub' | 'external';\n\n/**\n * The kinds an external system can be DECLARED as. Each draws its own shape in the runtime viz, so\n * a datastore stops looking like an HTTP service.\n *\n * Lives here rather than beside the runtime graph model because that model already imports from this\n * file; putting it there and importing back would close a module cycle.\n */\nexport const EXTERNAL_SYSTEM_KINDS = [\n    'database',\n    'cache',\n    'queue',\n    'storage',\n    'saas',\n    'system',\n    /**\n     * A destination whose ADDRESS is supplied at runtime — a URL a partner registered, an OAuth\n     * callback, a per-tenant host. Unlike every other kind it does not name one vendor: it names the\n     * PLACE in our own system where somebody else's address is dialled, which is the fact a security\n     * review is looking for.\n     *\n     * Declared like every other kind, on the CONTRACT: `@externalSystem runtime partner-webhooks`.\n     * On the contract rather than at a `createRpcClient` call site deliberately — \"the far end of\n     * this contract is outside our estate\" is a property of the CONTRACT, true for every caller of\n     * it, so putting it there means one declaration however many services deliver over it, and\n     * nothing to keep in step when a second one appears. It also means this kind rides the exact\n     * same declare → resolve → draw pipeline `saas` and `database` already ride, rather than a\n     * second mechanism that reads construction sites and can disagree with the first.\n     */\n    'runtime',\n] as const;\n\nexport type ExternalSystemKind = (typeof EXTERNAL_SYSTEM_KINDS)[number];\n\n/** True for a string that names one of {@link EXTERNAL_SYSTEM_KINDS}. */\n// webpieces-disable no-function-outside-class -- type guard beside the type it guards, matching this file's DTO style\nexport function isExternalSystemKind(value: string): value is ExternalSystemKind {\n    return (EXTERNAL_SYSTEM_KINDS as readonly string[]).includes(value);\n}\n\n/**\n * ONE declared external system, keyed in {@link ExternalSystemDecls} by its IDENTITY.\n *\n * Identity, not display text: two projects each tagged `external:database:postgres` name the same\n * `postgres` node and converge on it with one arrow apiece, instead of drawing a database each.\n *\n * The two arrays are the two declaration sites, and a system may legitimately have both — a repo can\n * wrap a datastore behind a contract in one service and open it directly in another.\n */\nexport interface ExternalSystemDecl {\n    kind: ExternalSystemKind;\n    label: string;\n    /** Contracts declaring it with an `@externalSystem` JSDoc tag; every user of one gets an arrow. */\n    apis: string[];\n    /** Projects declaring it with an `external:<kind>:<identity>` nx tag; each gets its OWN arrow. */\n    projects: string[];\n}\n\n/** identity -> its declaration. Serialized as the `externalSystems` key of dependencies.json. */\nexport type ExternalSystemDecls = Record<string, ExternalSystemDecl>;\n\n/**\n * How a project relates to ONE api-lib it depends on:\n *  - `implements`       — it serves the api (a controller extends it)\n *  - `uses`             — it calls the api (generates a client)\n *  - `uses-implements`  — it does BOTH (implements some of the api-lib's contracts,\n *                          uses others)\n */\nexport type ApiRelationKind = 'implements' | 'uses' | 'uses-implements';\n\n/** One API class a project implements or uses, with its transport. */\nexport interface ApiRef {\n    api: string;\n    type: ApiTransport;\n    /**\n     * ONLY on a `uses` ref: the service the call site aims at, read from the client config literal\n     * (`createRpcClient(XxxApi, new ClientConfig('helper-fsdb'))` → `helper-fsdb`). It is matched\n     * against a project's DECLARED `serviceName` to pick the ONE runtime edge target, instead of\n     * fanning the edge out to every implementer of the api — which is catastrophically wrong for a\n     * company-wide contract registered in a shared library and therefore implemented by every server.\n     *\n     * Absent when the config argument is not a `new <Xxx>ClientConfig('<literal>')` (a variable, a\n     * computed name, ...). Absent means \"unknown target\", NOT \"no target\" — the runtime graph then\n     * falls back to the old fan-out and says so out loud.\n     */\n    targetService?: string;\n    /**\n     * ONLY on a `pubsub` uses ref. True means \"this producer was attributed to EVERY cloudtasks\n     * method of the contract, not to the methods it actually enqueues\".\n     *\n     * A producer builds one client for the whole contract (`createPubSubClient(EmailTaskApi, cfg)`)\n     * and enqueues through a proxy (`emailTasks.send(req)`) somewhere else entirely — often after\n     * the client has been stored in a DI binding — so WHICH methods it enqueues is not statically\n     * recoverable. The consumer side IS exact (addRoutes + the contract's method table). Recording\n     * the difference keeps a producer-side queue from being read as proof that queue is used.\n     */\n    methodsInferred?: boolean;\n}\n\n/**\n * Identity of a ref for de-duplication: an api used twice against DIFFERENT services is two distinct\n * relations (two distinct runtime edges), so the api name alone is not the key.\n */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function apiRefKey(ref: ApiRef): string {\n    return `${ref.api} ${ref.targetService ?? ''}`;\n}\n\n/**\n * A project's relationship to ONE api-lib it depends on. Serialized verbatim into\n * architecture/dependencies.json under `apiRelations[apiLibProjectName]`.\n */\nexport interface ApiRelation {\n    kind: ApiRelationKind;\n    implements: ApiRef[];\n    uses: ApiRef[];\n}\n\n/** apiLibProjectName -> relation. Attached to a GraphEntry as `apiRelations`. */\nexport type ProjectApiRelations = Record<string, ApiRelation>;\n\n/**\n * What triggers ONE endpoint, mirroring core-util's `EndpointKind`. Duplicated as a string union\n * rather than imported: nx-webpieces-rules is build tooling and must not take a runtime dependency\n * on the framework it inspects (it reads decorators as TEXT, from projects that may be on a\n * different @webpieces version than the tooling itself).\n */\nexport type EndpointKind = 'rpc' | 'cloudtasks' | 'cron' | 'external';\n\n/**\n * One method on an API contract, as written in source: what triggers it, where it is mounted, and\n * (for a queued method) which Cloud Tasks queue delivers it.\n */\nexport interface ApiMethodMeta {\n    name: string;\n    /** The @Endpoint path, relative to the class's @ApiPath basePath. */\n    path: string;\n    kind: EndpointKind;\n    /**\n     * `@Queue(...)` override, else `${ApiClassName}-${methodName}`.\n     *\n     * ONLY on a `cloudtasks` or `cron` method — those are the kinds actually delivered through a\n     * named queue or schedule, and Terraform matches on this string. A synchronous `rpc` (or an\n     * inbound `external`) endpoint has no queue and needs none; emitting a plausible-looking name for\n     * one put every synchronous endpoint one naive `methods.map(m => m.queueName)` away from being\n     * provisioned as a queue.\n     */\n    queueName?: string;\n    /**\n     * WHO outside this repo drives this endpoint, from `@Endpoint(p, 'external', { calledBy })`.\n     *\n     * ONLY on an `external` method, the same way `queueName` is only on the kinds that HAVE a queue.\n     *\n     * Deliberately the SAME {@link ExternalSystemDeclaration} the OUTBOUND `@externalSystem` tag\n     * resolves to, not a parallel inbound-only type: an inbound `saas twilio` and an outbound\n     * `saas twilio` are the same vendor, so sharing the type makes them share an IDENTITY and\n     * converge on ONE node instead of drawing twilio twice facing opposite directions.\n     *\n     * Optional in the TYPE only for graphs generated before the caller was required — generation\n     * FAILS on an `external` method whose caller cannot be read (UndeclaredExternalCallerError).\n     */\n    caller?: ExternalSystemDeclaration;\n}\n\n/**\n * A discovered API contract class: its name, the api-lib project that owns it, its transport, and\n * its per-method trigger table.\n */\nexport interface ApiClassInfo {\n    api: string;\n    owner: string;\n    type: ApiTransport;\n    /** The class's @ApiPath basePath; absent for an external (vendor) contract, which has no route. */\n    basePath?: string;\n    /**\n     * Every @Endpoint method, in declaration order. Empty for an external contract (a vendor\n     * interface has no endpoints — it is called through a vendor SDK, not mounted).\n     */\n    methods: ApiMethodMeta[];\n    /**\n     * Set when the contract carries an `@externalSystem <kind> [label]` JSDoc tag — a vendor seam\n     * declaring WHAT it is a seam to. JSDoc rather than a decorator because these seams are plain TS\n     * `interface`s, which cannot carry one.\n     */\n    externalSystem?: ExternalSystemDeclaration;\n}\n\n/** The `(kind, label)` pair a single declaration resolves to. */\nexport interface ExternalSystemDeclaration {\n    kind: ExternalSystemKind;\n    label: string;\n}\n\n/**\n * The committed, per-contract view written to `architecture/dependencies.json` under `apiContracts`.\n *\n * The runtime graph is derived SOLELY from dependencies.json so generate and validate can never\n * diverge — which means anything the runtime graph needs must be COMMITTED there, not re-scanned.\n * Per-method trigger kinds and queue names are exactly that: without this table the derivation\n * cannot tell a queued endpoint from a cron sweep, and cannot name the queue between two services.\n */\nexport interface ApiContract {\n    owner: string;\n    /** 'rpc' | 'pubsub' for an in-repo contract, 'external' for a vendor seam. */\n    apiKind: ApiTransport;\n    /**\n     * REQUIRED. Every routed contract carries `@ApiPath`, so every entry in this table must carry the\n     * base path its methods hang off. Optional was worse than absent: a consumer joining\n     * `basePath + path` for the ONE entry that lost it computed `/test` where the real route was\n     * `/whatsapp/test`, and had no reason to suspect it — every other entry had the field. Generation\n     * now FAILS instead of shipping an entry that computes a confidently wrong URL.\n     */\n    basePath: string;\n    methods: ApiMethodMeta[];\n}\n\n/** apiClassName -> its committed contract. Serialized as the `apiContracts` key. */\nexport type ApiContracts = Record<string, ApiContract>;\n\n/**\n * ONE decorator argument the scan saw but could not reduce to a string — `@ApiPath(SOME_CONST)`\n * where SOME_CONST is imported from another module, a computed expression, an enum member, ...\n *\n * Recorded rather than dropped. Before this existed, an unresolvable argument cost the contract its\n * basePath, or a method, or (when EVERY method's path was one) the whole class — with nothing\n * printed anywhere. Same-module constants now resolve, so what remains here is the genuinely\n * unresolvable, which the author can fix by inlining the literal or moving the constant in-module.\n */\nexport class NonLiteralDecoratorArg {\n    constructor(\n        /** The contract class the argument was written on. */\n        public readonly api: string,\n        /** `ApiPath` | `Endpoint` | `Queue`. */\n        public readonly decorator: string,\n        /** The method name for a member decorator, null for a class decorator. */\n        public readonly method: string | null,\n        /** The argument exactly as written, e.g. `WHATSAPP_API_PATH`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * ONE `@Endpoint(path, kind)` whose PATH argument was present but could not be reduced to a string.\n *\n * Split out of NonLiteralDecoratorArg (which stays a warning, covering @Queue and the rest) because\n * this one is FATAL. Upstream components need the URL: an http client builds its request as\n * `basePath + path`, so an unreadable path is missing ROUTING, not missing metadata — the same\n * reasoning that already makes basePath required. Skipping the method instead used to delete it, and\n * a class whose every path was a constant lost every method and vanished from `apiContracts` with\n * nothing printed anywhere.\n */\nexport class UnresolvedEndpointPath {\n    constructor(\n        /** The contract class the method is declared on. */\n        public readonly api: string,\n        /** The method name. */\n        public readonly method: string,\n        /** The path argument exactly as written, e.g. `PROCESS_PATH`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * ONE `external` `@Endpoint` whose CALLER could not be read from the source.\n *\n * Fatal for the same reason {@link UnresolvedEndpointPath} is. The inbound box exists to say who is\n * calling us from outside; with no caller it can only restate our own contract name, which is the\n * exact bug this diagnostic exists to make impossible to reintroduce. `@Endpoint`'s TS overloads\n * already require `calledBy`, so anything reaching here is a JS caller, an `as any`, a cross-module\n * constant the parser-only scan cannot fold, or an unknown `callerKind`.\n */\nexport class UndeclaredExternalCaller {\n    constructor(\n        /** The contract class the method is declared on. */\n        public readonly api: string,\n        /** The method name. */\n        public readonly method: string,\n        /** What was wrong, as written — `<missing>`, `SOME_CONST`, `callerKind: 'vendor'`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * A contract class that DECLARED `@Endpoint` methods and kept none of them.\n *\n * The backstop for the mechanism that hid an entire service: `buildApiContracts` skips a zero-method\n * class (correctly — a vendor seam has no routes), so a class gutted by unreadable decorator\n * arguments left through the same door as a legitimately routeless one. A class that declared\n * endpoints and produced none is never legitimate, so it is named instead.\n */\nexport class EmptiedApiContract {\n    constructor(\n        /** The contract class name. */\n        public readonly api: string,\n        /** How many `@Endpoint` decorators were written on it. */\n        public readonly declared: number,\n        /** `path/to/file.ts:LINE` of the class, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/** Derive the relation kind from the (possibly empty) implements/uses ref lists. */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function deriveApiRelationKind(implementsRefs: ApiRef[], usesRefs: ApiRef[]): ApiRelationKind {\n    if (implementsRefs.length > 0 && usesRefs.length > 0) return 'uses-implements';\n    if (implementsRefs.length > 0) return 'implements';\n    return 'uses';\n}\n\n/**\n * Stable-sort a ref list by api name, then by target service, so the committed JSON is\n * deterministic even when one api is used against two different services.\n */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function sortApiRefs(refs: ApiRef[]): ApiRef[] {\n    return [...refs].sort(\n        (a: ApiRef, b: ApiRef) =>\n            a.api.localeCompare(b.api) || (a.targetService ?? '').localeCompare(b.targetService ?? ''),\n    );\n}\n"]}
+{"version":3,"file":"api-relations.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-relations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * API Relations model\n *\n * The typed classification of a compile-time dependency edge P -> apiLib in\n * architecture/dependencies.json. Where the flat `dependsOn` only says \"P depends\n * on apiLib\", `apiRelations[apiLib]` says WHY: which API contracts P IMPLEMENTS\n * (serves, `class Ctrl extends XxxApi`) and which it USES (calls as a client,\n * `factory.createRpcClient(XxxApi, ...)` / `createPubSubClient(...)`), each tagged\n * with its transport.\n *\n * Interfaces + object literals here mirror the sibling runtime-graph.ts model —\n * these are serialization DTOs written verbatim into the committed JSON, and\n * `implements`/`uses` are legal interface property names (they are reserved words\n * only as binding identifiers, not as member names).\n */\n\n/**\n * Transport of an API contract:\n *  - `rpc`      — synchronous request/response over HTTP\n *  - `pubsub`   — fire-and-forget, delivered later through a Cloud Tasks queue\n *  - `external` — a contract for a system OUTSIDE this repo (firestore, gmail, ...). Nothing in-repo\n *                 implements it, so it never becomes a service→service edge; it terminates the graph\n *                 at a dashed vendor node. Detected from `runtime-architecture.externalApiPaths`\n *                 rather than from a decorator, because a vendor contract is a plain interface bound\n *                 to a Symbol token, not an `abstract class` carrying @ApiPath.\n */\nexport type ApiTransport = 'rpc' | 'pubsub' | 'external';\n\n/**\n * The kinds an external system can be DECLARED as. Each draws its own shape in the runtime viz, so\n * a datastore stops looking like an HTTP service.\n *\n * Lives here rather than beside the runtime graph model because that model already imports from this\n * file; putting it there and importing back would close a module cycle.\n */\nexport const EXTERNAL_SYSTEM_KINDS = [\n    'database',\n    'cache',\n    'queue',\n    'storage',\n    'saas',\n    'system',\n    /**\n     * A destination whose ADDRESS is supplied at runtime — a URL a partner registered, an OAuth\n     * callback, a per-tenant host. Unlike every other kind it does not name one vendor: it names the\n     * PLACE in our own system where somebody else's address is dialled, which is the fact a security\n     * review is looking for.\n     *\n     * Declared like every other kind, on the CONTRACT: `@externalSystem runtime partner-webhooks`.\n     * On the contract rather than at a `createRpcClient` call site deliberately — \"the far end of\n     * this contract is outside our estate\" is a property of the CONTRACT, true for every caller of\n     * it, so putting it there means one declaration however many services deliver over it, and\n     * nothing to keep in step when a second one appears. It also means this kind rides the exact\n     * same declare → resolve → draw pipeline `saas` and `database` already ride, rather than a\n     * second mechanism that reads construction sites and can disagree with the first.\n     */\n    'runtime',\n] as const;\n\nexport type ExternalSystemKind = (typeof EXTERNAL_SYSTEM_KINDS)[number];\n\n/** True for a string that names one of {@link EXTERNAL_SYSTEM_KINDS}. */\n// webpieces-disable no-function-outside-class -- type guard beside the type it guards, matching this file's DTO style\nexport function isExternalSystemKind(value: string): value is ExternalSystemKind {\n    return (EXTERNAL_SYSTEM_KINDS as readonly string[]).includes(value);\n}\n\n/**\n * ONE declared external system, keyed in {@link ExternalSystemDecls} by its IDENTITY.\n *\n * Identity, not display text: two projects each tagged `external:database:postgres` name the same\n * `postgres` node and converge on it with one arrow apiece, instead of drawing a database each.\n *\n * The two arrays are the two declaration sites, and a system may legitimately have both — a repo can\n * wrap a datastore behind a contract in one service and open it directly in another.\n */\nexport interface ExternalSystemDecl {\n    kind: ExternalSystemKind;\n    label: string;\n    /** Contracts declaring it with an `@externalSystem` JSDoc tag; every user of one gets an arrow. */\n    apis: string[];\n    /** Projects declaring it with an `external:<kind>:<identity>` nx tag; each gets its OWN arrow. */\n    projects: string[];\n}\n\n/** identity -> its declaration. Serialized as the `externalSystems` key of dependencies.json. */\nexport type ExternalSystemDecls = Record<string, ExternalSystemDecl>;\n\n/**\n * How a project relates to ONE api-lib it depends on:\n *  - `implements`       — it serves the api (a controller extends it)\n *  - `uses`             — it calls the api (generates a client)\n *  - `uses-implements`  — it does BOTH (implements some of the api-lib's contracts,\n *                          uses others)\n */\nexport type ApiRelationKind = 'implements' | 'uses' | 'uses-implements';\n\n/** One API class a project implements or uses, with its transport. */\nexport interface ApiRef {\n    api: string;\n    type: ApiTransport;\n    /**\n     * ONLY on a `uses` ref: the service the call site aims at, read from the client config literal\n     * (`createRpcClient(XxxApi, new ClientConfig('helper-fsdb'))` → `helper-fsdb`). It is matched\n     * against a project's DECLARED `serviceName` to pick the ONE runtime edge target, instead of\n     * fanning the edge out to every implementer of the api — which is catastrophically wrong for a\n     * company-wide contract registered in a shared library and therefore implemented by every server.\n     *\n     * Absent when the config argument is not a `new <Xxx>ClientConfig('<literal>')` (a variable, a\n     * computed name, ...). Absent means \"unknown target\", NOT \"no target\" — the runtime graph then\n     * falls back to the old fan-out and says so out loud.\n     */\n    targetService?: string;\n    /**\n     * ONLY on a `pubsub` uses ref. True means \"this producer was attributed to EVERY cloudtasks\n     * method of the contract, not to the methods it actually enqueues\".\n     *\n     * A producer builds one client for the whole contract (`createPubSubClient(EmailTaskApi, cfg)`)\n     * and enqueues through a proxy (`emailTasks.send(req)`) somewhere else entirely — often after\n     * the client has been stored in a DI binding — so WHICH methods it enqueues is not statically\n     * recoverable. The consumer side IS exact (addRoutes + the contract's method table). Recording\n     * the difference keeps a producer-side queue from being read as proof that queue is used.\n     */\n    methodsInferred?: boolean;\n}\n\n/**\n * Identity of a ref for de-duplication: an api used twice against DIFFERENT services is two distinct\n * relations (two distinct runtime edges), so the api name alone is not the key.\n */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function apiRefKey(ref: ApiRef): string {\n    return `${ref.api} ${ref.targetService ?? ''}`;\n}\n\n/**\n * A project's relationship to ONE api-lib it depends on. Serialized verbatim into\n * architecture/dependencies.json under `apiRelations[apiLibProjectName]`.\n */\nexport interface ApiRelation {\n    kind: ApiRelationKind;\n    implements: ApiRef[];\n    uses: ApiRef[];\n}\n\n/** apiLibProjectName -> relation. Attached to a GraphEntry as `apiRelations`. */\nexport type ProjectApiRelations = Record<string, ApiRelation>;\n\n/**\n * What triggers ONE endpoint, mirroring core-util's `EndpointKind`. Duplicated as a string union\n * rather than imported: nx-webpieces-rules is build tooling and must not take a runtime dependency\n * on the framework it inspects (it reads decorators as TEXT, from projects that may be on a\n * different @webpieces version than the tooling itself).\n */\nexport type EndpointKind = 'rpc' | 'cloudtasks' | 'cron' | 'external';\n\n/** HTTP verbs understood by the generated contract runtime. */\nexport type ContractHttpMethod = 'GET' | 'POST';\n\n/** One path/query/body mapping emitted into architecture/dependencies.json. */\nexport interface ApiParameterMeta {\n    index: number;\n    source: 'path' | 'query' | 'body';\n    /** Path/query wire name; a JSON/form body occupies the whole entity and has no key. */\n    wireName?: string;\n}\n\n/**\n * One method on an API contract, as written in source: what triggers it, where it is mounted, and\n * (for a queued method) which Cloud Tasks queue delivers it.\n */\nexport interface ApiMethodMeta {\n    name: string;\n    /** The @Endpoint path, relative to the class's @ApiPath basePath. */\n    path: string;\n    kind: EndpointKind;\n    /** The actual incoming/outgoing verb; POST when @Endpoint omits httpMethod. */\n    httpMethod?: ContractHttpMethod;\n    /** Explicit parameter mappings; absent only when the method has none. */\n    parameters?: ApiParameterMeta[];\n    /** Present when callers receive the transport-neutral full response. */\n    responseType?: 'full';\n    /**\n     * `@Queue(...)` override, else `${ApiClassName}-${methodName}`.\n     *\n     * ONLY on a `cloudtasks` or `cron` method — those are the kinds actually delivered through a\n     * named queue or schedule, and Terraform matches on this string. A synchronous `rpc` (or an\n     * inbound `external`) endpoint has no queue and needs none; emitting a plausible-looking name for\n     * one put every synchronous endpoint one naive `methods.map(m => m.queueName)` away from being\n     * provisioned as a queue.\n     */\n    queueName?: string;\n    /**\n     * WHO outside this repo drives this endpoint, from `@Endpoint(p, 'external', { calledBy })`.\n     *\n     * ONLY on an `external` method, the same way `queueName` is only on the kinds that HAVE a queue.\n     *\n     * Deliberately the SAME {@link ExternalSystemDeclaration} the OUTBOUND `@externalSystem` tag\n     * resolves to, not a parallel inbound-only type: an inbound `saas twilio` and an outbound\n     * `saas twilio` are the same vendor, so sharing the type makes them share an IDENTITY and\n     * converge on ONE node instead of drawing twilio twice facing opposite directions.\n     *\n     * Optional in the TYPE only for graphs generated before the caller was required — generation\n     * FAILS on an `external` method whose caller cannot be read (UndeclaredExternalCallerError).\n     */\n    caller?: ExternalSystemDeclaration;\n}\n\n/**\n * A discovered API contract class: its name, the api-lib project that owns it, its transport, and\n * its per-method trigger table.\n */\nexport interface ApiClassInfo {\n    api: string;\n    owner: string;\n    type: ApiTransport;\n    /** The class's @ApiPath basePath; absent for an external (vendor) contract, which has no route. */\n    basePath?: string;\n    /**\n     * Every @Endpoint method, in declaration order. Empty for an external contract (a vendor\n     * interface has no endpoints — it is called through a vendor SDK, not mounted).\n     */\n    methods: ApiMethodMeta[];\n    /**\n     * Set when the contract carries an `@externalSystem <kind> [label]` JSDoc tag — a vendor seam\n     * declaring WHAT it is a seam to. JSDoc rather than a decorator because these seams are plain TS\n     * `interface`s, which cannot carry one.\n     */\n    externalSystem?: ExternalSystemDeclaration;\n}\n\n/** The `(kind, label)` pair a single declaration resolves to. */\nexport interface ExternalSystemDeclaration {\n    kind: ExternalSystemKind;\n    label: string;\n}\n\n/**\n * The committed, per-contract view written to `architecture/dependencies.json` under `apiContracts`.\n *\n * The runtime graph is derived SOLELY from dependencies.json so generate and validate can never\n * diverge — which means anything the runtime graph needs must be COMMITTED there, not re-scanned.\n * Per-method trigger kinds and queue names are exactly that: without this table the derivation\n * cannot tell a queued endpoint from a cron sweep, and cannot name the queue between two services.\n */\nexport interface ApiContract {\n    owner: string;\n    /** 'rpc' | 'pubsub' for an in-repo contract, 'external' for a vendor seam. */\n    apiKind: ApiTransport;\n    /**\n     * REQUIRED. Every routed contract carries `@ApiPath`, so every entry in this table must carry the\n     * base path its methods hang off. Optional was worse than absent: a consumer joining\n     * `basePath + path` for the ONE entry that lost it computed `/test` where the real route was\n     * `/whatsapp/test`, and had no reason to suspect it — every other entry had the field. Generation\n     * now FAILS instead of shipping an entry that computes a confidently wrong URL.\n     */\n    basePath: string;\n    methods: ApiMethodMeta[];\n}\n\n/** apiClassName -> its committed contract. Serialized as the `apiContracts` key. */\nexport type ApiContracts = Record<string, ApiContract>;\n\n/**\n * ONE decorator argument the scan saw but could not reduce to a string — `@ApiPath(SOME_CONST)`\n * where SOME_CONST is imported from another module, a computed expression, an enum member, ...\n *\n * Recorded rather than dropped. Before this existed, an unresolvable argument cost the contract its\n * basePath, or a method, or (when EVERY method's path was one) the whole class — with nothing\n * printed anywhere. Same-module constants now resolve, so what remains here is the genuinely\n * unresolvable, which the author can fix by inlining the literal or moving the constant in-module.\n */\nexport class NonLiteralDecoratorArg {\n    constructor(\n        /** The contract class the argument was written on. */\n        public readonly api: string,\n        /** `ApiPath` | `Endpoint` | `Queue`. */\n        public readonly decorator: string,\n        /** The method name for a member decorator, null for a class decorator. */\n        public readonly method: string | null,\n        /** The argument exactly as written, e.g. `WHATSAPP_API_PATH`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * ONE `@Endpoint(path, kind)` whose PATH argument was present but could not be reduced to a string.\n *\n * Split out of NonLiteralDecoratorArg (which stays a warning, covering @Queue and the rest) because\n * this one is FATAL. Upstream components need the URL: an http client builds its request as\n * `basePath + path`, so an unreadable path is missing ROUTING, not missing metadata — the same\n * reasoning that already makes basePath required. Skipping the method instead used to delete it, and\n * a class whose every path was a constant lost every method and vanished from `apiContracts` with\n * nothing printed anywhere.\n */\nexport class UnresolvedEndpointPath {\n    constructor(\n        /** The contract class the method is declared on. */\n        public readonly api: string,\n        /** The method name. */\n        public readonly method: string,\n        /** The path argument exactly as written, e.g. `PROCESS_PATH`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * ONE `external` `@Endpoint` whose CALLER could not be read from the source.\n *\n * Fatal for the same reason {@link UnresolvedEndpointPath} is. The inbound box exists to say who is\n * calling us from outside; with no caller it can only restate our own contract name, which is the\n * exact bug this diagnostic exists to make impossible to reintroduce. `@Endpoint`'s TS overloads\n * already require `calledBy`, so anything reaching here is a JS caller, an `as any`, a cross-module\n * constant the parser-only scan cannot fold, or an unknown `callerKind`.\n */\nexport class UndeclaredExternalCaller {\n    constructor(\n        /** The contract class the method is declared on. */\n        public readonly api: string,\n        /** The method name. */\n        public readonly method: string,\n        /** What was wrong, as written — `<missing>`, `SOME_CONST`, `callerKind: 'vendor'`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * A contract class that DECLARED `@Endpoint` methods and kept none of them.\n *\n * The backstop for the mechanism that hid an entire service: `buildApiContracts` skips a zero-method\n * class (correctly — a vendor seam has no routes), so a class gutted by unreadable decorator\n * arguments left through the same door as a legitimately routeless one. A class that declared\n * endpoints and produced none is never legitimate, so it is named instead.\n */\nexport class EmptiedApiContract {\n    constructor(\n        /** The contract class name. */\n        public readonly api: string,\n        /** How many `@Endpoint` decorators were written on it. */\n        public readonly declared: number,\n        /** `path/to/file.ts:LINE` of the class, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/** Derive the relation kind from the (possibly empty) implements/uses ref lists. */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function deriveApiRelationKind(\n    implementsRefs: ApiRef[],\n    usesRefs: ApiRef[],\n): ApiRelationKind {\n    if (implementsRefs.length > 0 && usesRefs.length > 0) return 'uses-implements';\n    if (implementsRefs.length > 0) return 'implements';\n    return 'uses';\n}\n\n/**\n * Stable-sort a ref list by api name, then by target service, so the committed JSON is\n * deterministic even when one api is used against two different services.\n */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function sortApiRefs(refs: ApiRef[]): ApiRef[] {\n    return [...refs].sort(\n        (a: ApiRef, b: ApiRef) =>\n            a.api.localeCompare(b.api) ||\n            (a.targetService ?? '').localeCompare(b.targetService ?? ''),\n    );\n}\n"]}