@webpieces/nx-webpieces-rules 0.4.832 → 0.4.834

package/src/lib/api-usage/api-lib-tag-validator.js

@@ -2,36 +2,274 @@
 /**
  * API-lib tag validator (two-way)
  *
- * Keeps the `role:api-lib` tag and the CODE in sync, both directions:
- *   - a project tagged `role:api-lib` MUST export ≥1 API contract (an `abstract class` carrying
- *     `@ApiPath`/`@Rpc`/`@PubSub`) — else the tag is a lie;
- *   - a project that DOES export such a contract MUST be tagged `role:api-lib` — else the arch
- *     graph, the edge line-styles, and validate-api-relations can't treat it as an api-lib.
+ * Keeps the two api roles and the CODE in sync, both directions (#1064, D1 + D3):
+ *   - a project that exports an `@ApiPath`/`@Rpc`/`@PubSub` contract (or a vendor contract under
+ *     `externalApiPaths`) MUST be tagged `role:api-lib` or `role:api-client` — else the arch graph, the
+ *     edge line-styles, and validate-api-relations can't treat it as one;
+ *   - a project tagged `role:api-lib` MUST export a contract or ONLY wire types — else the tag is a lie.
+ *     A contract is any of: an `@ApiPath`/`@Rpc`/`@PubSub` class (from the scan), an IPC contract
+ *     (`@WpInternal` / `@WpIpcEndpoint`), or an in-process abstract `…Api` behind a DI token. A DTO-only
+ *     library exports interfaces, type aliases, enums, data classes (no methods), and data-only constants;
+ *   - a project tagged `role:api-client` MUST export a contract: either an abstract `XxxApi`, or an
+ *     exported `XxxApi` interface implemented by a client registered with `@provideSingletonDefaultForApi`.
+ *     The bundled client beside it is the point of the role, so it is not judged as a wire type.
  *
- * "Exports an API contract" is answered by the same source scan that owns apiRelations
- * (scan.apiLibProjects), so the tag can never drift from the code.
+ * "Exports an @ApiPath contract" is answered by the same source scan that owns apiRelations
+ * (scan.apiLibProjects), so the tag can never drift from the code. The IPC / in-process / DTO-only
+ * reading is a parser-only pass over the project's own non-test `src/**` — {@link ApiLibExportShape}.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiLibExportShape = exports.ApiLibTagViolation = void 0;
 exports.findApiLibTagViolations = findApiLibTagViolations;
 exports.describeApiLibTagViolation = describeApiLibTagViolation;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const ts = tslib_1.__importStar(require("typescript"));
 const role_resolver_1 = require("../role-resolver");
+const api_ast_1 = require("./api-ast");
 const API_LIB_ROLE = 'api-lib';
-/** Both-directions tag ⇔ code check. Uses the scan's detected api-lib set as ground truth. */
+const API_CLIENT_ROLE = 'api-client';
+/** The decorators that make an abstract class an IPC contract. */
+const IPC_DECORATORS = ['WpInternal', 'WpIpcEndpoint'];
+/**
+ * A tag/code mismatch:
+ *  - 'missing-tag'     — exports an API contract but is tagged neither role:api-lib nor role:api-client.
+ *  - 'unnecessary-tag' — tagged role:api-lib / role:api-client but exports no contract, and (for
+ *                        api-lib) is not a DTO-only library either; `offenders` names what it exports.
+ */
+class ApiLibTagViolation {
+    project;
+    kind;
+    role;
+    offenders;
+    constructor(project, kind, 
+    /** The role it carries (for 'unnecessary-tag'), else the role it should carry. */
+    role, 
+    /** Exports that are neither a contract nor a wire type — empty for 'missing-tag'. */
+    offenders = []) {
+        this.project = project;
+        this.kind = kind;
+        this.role = role;
+        this.offenders = offenders;
+    }
+}
+exports.ApiLibTagViolation = ApiLibTagViolation;
+/** What a library's own source exports, sorted into contracts, wire types and everything else. */
+class ApiLibExportShape {
+    exportsContract;
+    exportsWireType;
+    offenders;
+    constructor(
+    /** True when it exports an IPC contract or an in-process abstract `…Api`. */
+    exportsContract, 
+    /** True when it exports at least one wire type (interface, alias, enum, data class). */
+    exportsWireType, 
+    /** `kind Name (file)` of every export that is neither — the implementation an api-lib must not hold. */
+    offenders) {
+        this.exportsContract = exportsContract;
+        this.exportsWireType = exportsWireType;
+        this.offenders = offenders;
+    }
+    /** A role:api-lib passes when it holds a contract or wire types, and nothing else. */
+    isApiLib() {
+        return (this.exportsContract || this.exportsWireType) && this.offenders.length === 0;
+    }
+    /** Parser-only: every top-level EXPORTED declaration in the project's non-test `src/**`. */
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static read(projectDir) {
+        const srcDir = path.join(projectDir, 'src');
+        const acc = new ExportShapeAccumulator(projectDir);
+        if (fs.existsSync(srcDir)) {
+            for (const file of (0, api_ast_1.collectTsFiles)(srcDir)) {
+                if ((0, api_ast_1.isTestFile)(file))
+                    continue;
+                const source = ts.createSourceFile(file, fs.readFileSync(file, 'utf8'), ts.ScriptTarget.Latest, true);
+                for (const statement of source.statements)
+                    acc.add(statement, file);
+            }
+        }
+        return acc.shape();
+    }
+}
+exports.ApiLibExportShape = ApiLibExportShape;
+/** Sorts each exported statement of one library into contract / wire type / offender. */
+class ExportShapeAccumulator {
+    projectDir;
+    contract = false;
+    wire = false;
+    offenders = [];
+    apiInterfaces = new Set();
+    registeredApiImplementations = new Set();
+    constructor(projectDir) {
+        this.projectDir = projectDir;
+    }
+    add(statement, file) {
+        if (!this.isExported(statement))
+            return;
+        const where = path.relative(this.projectDir, file);
+        if (ts.isInterfaceDeclaration(statement)) {
+            this.wire = true;
+            if (statement.name.text.endsWith('Api'))
+                this.apiInterfaces.add(statement.name.text);
+        }
+        else if (ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement)) {
+            this.wire = true;
+        }
+        else if (ts.isClassDeclaration(statement)) {
+            this.addClass(statement, where);
+        }
+        else if (ts.isVariableStatement(statement)) {
+            for (const decl of statement.declarationList.declarations) {
+                if (this.isDiToken(decl.initializer) || this.isDataConstant(decl.initializer))
+                    continue;
+                this.offenders.push(`const ${decl.name.getText()} (${where})`);
+            }
+        }
+        else if (ts.isFunctionDeclaration(statement)) {
+            this.offenders.push(`function ${statement.name?.text ?? '<default>'} (${where})`);
+        }
+    }
+    shape() {
+        const registeredInterface = [...this.apiInterfaces].some((name) => this.registeredApiImplementations.has(name));
+        return new ApiLibExportShape(this.contract || registeredInterface, this.wire, [...this.offenders].sort());
+    }
+    addClass(cls, where) {
+        const name = cls.name?.text ?? '<default>';
+        if (this.hasDecorator(cls, 'provideSingletonDefaultForApi')) {
+            for (const heritage of cls.heritageClauses ?? []) {
+                if (heritage.token !== ts.SyntaxKind.ImplementsKeyword)
+                    continue;
+                for (const type of heritage.types) {
+                    const implemented = type.expression.getText().split('.').pop();
+                    if (implemented !== undefined)
+                        this.registeredApiImplementations.add(implemented);
+                }
+            }
+        }
+        const isAbstract = (ts.getModifiers(cls) ?? []).some((m) => m.kind === ts.SyntaxKind.AbstractKeyword);
+        if (isAbstract && (name.endsWith('Api') || this.carriesIpc(cls))) {
+            this.contract = true;
+            return;
+        }
+        const hasMethod = cls.members.some((member) => ts.isMethodDeclaration(member) &&
+            !(ts.getModifiers(member) ?? []).some((m) => m.kind === ts.SyntaxKind.StaticKeyword));
+        if (hasMethod)
+            this.offenders.push(`class ${name} (${where}) — it has methods, so it is an implementation`);
+        else
+            this.wire = true;
+    }
+    /** `@WpInternal(...)` on the class or `@WpIpcEndpoint(...)` on any member. */
+    carriesIpc(cls) {
+        const named = (node) => IPC_DECORATORS.some((name) => this.hasDecorator(node, name));
+        return named(cls) || cls.members.some((member) => named(member));
+    }
+    hasDecorator(node, expected) {
+        return (ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : []).some((decorator) => {
+            const expr = ts.isCallExpression(decorator.expression)
+                ? decorator.expression.expression
+                : decorator.expression;
+            const name = ts.isPropertyAccessExpression(expr) ? expr.name.text : expr.getText();
+            return name === expected;
+        });
+    }
+    /** Literal/structural protocol data is contract support, not an executable implementation. */
+    isDataConstant(init) {
+        if (init === undefined)
+            return false;
+        const expr = this.unwrap(init);
+        if (ts.isStringLiteralLike(expr) ||
+            ts.isNumericLiteral(expr) ||
+            expr.kind === ts.SyntaxKind.TrueKeyword ||
+            expr.kind === ts.SyntaxKind.FalseKeyword ||
+            expr.kind === ts.SyntaxKind.NullKeyword ||
+            ts.isIdentifier(expr) ||
+            ts.isPropertyAccessExpression(expr)) {
+            return true;
+        }
+        if (ts.isPrefixUnaryExpression(expr))
+            return this.isDataConstant(expr.operand);
+        if (ts.isBinaryExpression(expr)) {
+            return this.isDataConstant(expr.left) && this.isDataConstant(expr.right);
+        }
+        if (ts.isConditionalExpression(expr)) {
+            return (this.isDataConstant(expr.condition) &&
+                this.isDataConstant(expr.whenTrue) &&
+                this.isDataConstant(expr.whenFalse));
+        }
+        if (ts.isTemplateExpression(expr)) {
+            return expr.templateSpans.every((span) => this.isDataConstant(span.expression));
+        }
+        if (ts.isArrayLiteralExpression(expr)) {
+            return expr.elements.every((element) => ts.isOmittedExpression(element) ||
+                (ts.isSpreadElement(element)
+                    ? this.isDataConstant(element.expression)
+                    : this.isDataConstant(element)));
+        }
+        if (ts.isObjectLiteralExpression(expr)) {
+            return expr.properties.every((prop) => {
+                if (ts.isPropertyAssignment(prop))
+                    return this.isDataConstant(prop.initializer);
+                if (ts.isShorthandPropertyAssignment(prop))
+                    return true;
+                if (ts.isSpreadAssignment(prop))
+                    return this.isDataConstant(prop.expression);
+                return false;
+            });
+        }
+        return false;
+    }
+    unwrap(expr) {
+        if (ts.isAsExpression(expr) ||
+            ts.isTypeAssertionExpression(expr) ||
+            ts.isSatisfiesExpression(expr) ||
+            ts.isParenthesizedExpression(expr) ||
+            ts.isNonNullExpression(expr)) {
+            return this.unwrap(expr.expression);
+        }
+        return expr;
+    }
+    /** `Symbol('x')`, `Symbol.for('x')`, or an object literal of them — the token an abstract `…Api` binds behind. */
+    isDiToken(init) {
+        if (init === undefined)
+            return false;
+        const expr = ts.isAsExpression(init) || ts.isSatisfiesExpression(init) ? init.expression : init;
+        if (ts.isCallExpression(expr)) {
+            const callee = expr.expression.getText();
+            return callee === 'Symbol' || callee === 'Symbol.for';
+        }
+        if (ts.isObjectLiteralExpression(expr)) {
+            return (expr.properties.length > 0 &&
+                expr.properties.every((prop) => ts.isPropertyAssignment(prop) && this.isDiToken(prop.initializer)));
+        }
+        return false;
+    }
+    isExported(statement) {
+        if (!ts.canHaveModifiers(statement))
+            return false;
+        return (ts.getModifiers(statement) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    }
+}
+/** Both-directions tag ⇔ code check. Uses the scan's detected api-lib set as ground truth for @ApiPath. */
 // webpieces-disable no-function-outside-class -- validator-lib entry point, matches api-relations-validator.ts
-function findApiLibTagViolations(projectInfos, scan) {
+function findApiLibTagViolations(projectInfos, scan, workspaceRoot) {
     const violations = [];
     for (const projectName of projectInfos.keys()) {
         const info = projectInfos.get(projectName);
-        const isTagged = (0, role_resolver_1.resolveRole)(info).role === API_LIB_ROLE;
+        const role = (0, role_resolver_1.resolveRole)(info).role;
+        const isApiRole = role === API_LIB_ROLE || role === API_CLIENT_ROLE;
         const exportsApi = scan.apiLibProjects.has(projectName);
-        if (exportsApi && !isTagged) {
-            violations.push({ project: projectName, kind: 'missing-tag' });
-        }
-        // Only flag an unnecessary tag when we actually SCANNED the project's source — otherwise we
-        // can't prove it exports no contract (an unscannable project would falsely look empty).
-        if (isTagged && !exportsApi && scan.scannedProjects.has(projectName)) {
-            violations.push({ project: projectName, kind: 'unnecessary-tag' });
+        if (exportsApi && !isApiRole) {
+            violations.push(new ApiLibTagViolation(projectName, 'missing-tag', API_LIB_ROLE));
         }
+        // Only judge a tag when we actually SCANNED the project's source — otherwise we can't prove it
+        // exports no contract (an unscannable project would falsely look empty).
+        if (!isApiRole || exportsApi || !scan.scannedProjects.has(projectName))
+            continue;
+        const shape = ApiLibExportShape.read(path.resolve(workspaceRoot, info.root));
+        const ok = role === API_CLIENT_ROLE ? shape.exportsContract : shape.isApiLib();
+        if (!ok)
+            violations.push(new ApiLibTagViolation(projectName, 'unnecessary-tag', role, shape.offenders));
     }
     return violations.sort((a, b) => a.project.localeCompare(b.project));
 }
@@ -40,11 +278,23 @@ function findApiLibTagViolations(projectInfos, scan) {
 function describeApiLibTagViolation(violation) {
     if (violation.kind === 'missing-tag') {
         return (`  ❌ '${violation.project}' exports an API contract (an abstract @ApiPath/@Rpc/@PubSub class) ` +
-            `but is not tagged 'role:api-lib'.\n` +
-            `     Add "role:api-lib" to its project.json "tags" (replacing any "role:lib").`);
+            `but is tagged neither 'role:api-lib' nor 'role:api-client'.\n` +
+            `     Add "role:api-lib" to its project.json "tags" (replacing any "role:lib"), or "role:api-client" ` +
+            `when it also bundles the default implementation that talks to an outside system.`);
+    }
+    if (violation.role === API_CLIENT_ROLE) {
+        return (`  ❌ '${violation.project}' is tagged 'role:api-client' but exports NO contract (no abstract ` +
+            `…Api class, no @WpInternal/@WpIpcEndpoint contract, and no exported …Api interface implemented ` +
+            `by an @provideSingletonDefaultForApi client).\n` +
+            `     An api-client is a contract PLUS its default implementation: export the XxxApi the registered ` +
+            `client implements, or retag it (e.g. "role:lib").`);
     }
-    return (`  ❌ '${violation.project}' is tagged 'role:api-lib' but exports NO API contract ` +
-        `(no abstract @ApiPath/@Rpc/@PubSub class).\n` +
-        `     Either add the API contract it should own, or retag it (e.g. "role:lib").`);
+    const offenders = violation.offenders.length === 0
+        ? ''
+        : `\n     It exports, besides contracts and wire types: ${violation.offenders.join('; ')}.`;
+    return (`  ❌ '${violation.project}' is tagged 'role:api-lib' but is neither a contract library (@ApiPath/@Rpc/` +
+        `@PubSub, @WpInternal/@WpIpcEndpoint, or an abstract …Api behind a DI token) nor a DTO-only library ` +
+        `(interfaces, type aliases, enums and data classes only).${offenders}\n` +
+        `     Move the implementation out to a role:lib / role:designed-lib project, or retag it.`);
 }
 //# sourceMappingURL=api-lib-tag-validator.js.map

package/src/lib/api-usage/api-lib-tag-validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-lib-tag-validator.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-lib-tag-validator.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAoBH,0DAoBC;AAID,gEAaC;AAtDD,oDAA+C;AAG/C,MAAM,YAAY,GAAG,SAAS,CAAC;AAY/B,8FAA8F;AAC9F,+GAA+G;AAC/G,SAAgB,uBAAuB,CACnC,YAAsC,EACtC,IAAmB;IAEnB,MAAM,UAAU,GAAyB,EAAE,CAAC;IAC5C,KAAK,MAAM,WAAW,IAAI,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,WAAW,CAAE,CAAC;QAC5C,MAAM,QAAQ,GAAG,IAAA,2BAAW,EAAC,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC;QACzD,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAExD,IAAI,UAAU,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC1B,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,4FAA4F;QAC5F,wFAAwF;QACxF,IAAI,QAAQ,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YACnE,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAC;QACvE,CAAC;IACL,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAqB,EAAE,CAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AACjH,CAAC;AAED,qEAAqE;AACrE,oGAAoG;AACpG,SAAgB,0BAA0B,CAAC,SAA6B;IACpE,IAAI,SAAS,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QACnC,OAAO,CACH,QAAQ,SAAS,CAAC,OAAO,sEAAsE;YAC/F,qCAAqC;YACrC,gFAAgF,CACnF,CAAC;IACN,CAAC;IACD,OAAO,CACH,QAAQ,SAAS,CAAC,OAAO,yDAAyD;QAClF,8CAA8C;QAC9C,gFAAgF,CACnF,CAAC;AACN,CAAC","sourcesContent":["/**\n * API-lib tag validator (two-way)\n *\n * Keeps the `role:api-lib` tag and the CODE in sync, both directions:\n *   - a project tagged `role:api-lib` MUST export ≥1 API contract (an `abstract class` carrying\n *     `@ApiPath`/`@Rpc`/`@PubSub`) — else the tag is a lie;\n *   - a project that DOES export such a contract MUST be tagged `role:api-lib` — else the arch\n *     graph, the edge line-styles, and validate-api-relations can't treat it as an api-lib.\n *\n * \"Exports an API contract\" is answered by the same source scan that owns apiRelations\n * (scan.apiLibProjects), so the tag can never drift from the code.\n */\n\nimport { ProjectInfo } from '../project-info';\nimport { resolveRole } from '../role-resolver';\nimport { ApiScanResult } from './api-scanner';\n\nconst API_LIB_ROLE = 'api-lib';\n\n/**\n * A tag/code mismatch:\n *  - 'missing-tag'     — exports an API contract but is not tagged role:api-lib.\n *  - 'unnecessary-tag' — tagged role:api-lib but exports no API contract.\n */\nexport interface ApiLibTagViolation {\n    project: string;\n    kind: 'missing-tag' | 'unnecessary-tag';\n}\n\n/** Both-directions tag ⇔ code check. Uses the scan's detected api-lib set as ground truth. */\n// webpieces-disable no-function-outside-class -- validator-lib entry point, matches api-relations-validator.ts\nexport function findApiLibTagViolations(\n    projectInfos: Map<string, ProjectInfo>,\n    scan: ApiScanResult,\n): ApiLibTagViolation[] {\n    const violations: ApiLibTagViolation[] = [];\n    for (const projectName of projectInfos.keys()) {\n        const info = projectInfos.get(projectName)!;\n        const isTagged = resolveRole(info).role === API_LIB_ROLE;\n        const exportsApi = scan.apiLibProjects.has(projectName);\n\n        if (exportsApi && !isTagged) {\n            violations.push({ project: projectName, kind: 'missing-tag' });\n        }\n        // Only flag an unnecessary tag when we actually SCANNED the project's source — otherwise we\n        // can't prove it exports no contract (an unscannable project would falsely look empty).\n        if (isTagged && !exportsApi && scan.scannedProjects.has(projectName)) {\n            violations.push({ project: projectName, kind: 'unnecessary-tag' });\n        }\n    }\n    return violations.sort((a: ApiLibTagViolation, b: ApiLibTagViolation) => a.project.localeCompare(b.project));\n}\n\n/** Human-readable, fix-oriented report for one tag/code mismatch. */\n// webpieces-disable no-function-outside-class -- pure formatter, matches api-relations-validator.ts\nexport function describeApiLibTagViolation(violation: ApiLibTagViolation): string {\n    if (violation.kind === 'missing-tag') {\n        return (\n            `  ❌ '${violation.project}' exports an API contract (an abstract @ApiPath/@Rpc/@PubSub class) ` +\n            `but is not tagged 'role:api-lib'.\\n` +\n            `     Add \"role:api-lib\" to its project.json \"tags\" (replacing any \"role:lib\").`\n        );\n    }\n    return (\n        `  ❌ '${violation.project}' is tagged 'role:api-lib' but exports NO API contract ` +\n        `(no abstract @ApiPath/@Rpc/@PubSub class).\\n` +\n        `     Either add the API contract it should own, or retag it (e.g. \"role:lib\").`\n    );\n}\n"]}
+{"version":3,"file":"api-lib-tag-validator.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-lib-tag-validator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * API-lib tag validator (two-way)\n *\n * Keeps the two api roles and the CODE in sync, both directions (#1064, D1 + D3):\n *   - a project that exports an `@ApiPath`/`@Rpc`/`@PubSub` contract (or a vendor contract under\n *     `externalApiPaths`) MUST be tagged `role:api-lib` or `role:api-client` — else the arch graph, the\n *     edge line-styles, and validate-api-relations can't treat it as one;\n *   - a project tagged `role:api-lib` MUST export a contract or ONLY wire types — else the tag is a lie.\n *     A contract is any of: an `@ApiPath`/`@Rpc`/`@PubSub` class (from the scan), an IPC contract\n *     (`@WpInternal` / `@WpIpcEndpoint`), or an in-process abstract `…Api` behind a DI token. A DTO-only\n *     library exports interfaces, type aliases, enums, data classes (no methods), and data-only constants;\n *   - a project tagged `role:api-client` MUST export a contract: either an abstract `XxxApi`, or an\n *     exported `XxxApi` interface implemented by a client registered with `@provideSingletonDefaultForApi`.\n *     The bundled client beside it is the point of the role, so it is not judged as a wire type.\n *\n * \"Exports an @ApiPath contract\" is answered by the same source scan that owns apiRelations\n * (scan.apiLibProjects), so the tag can never drift from the code. The IPC / in-process / DTO-only\n * reading is a parser-only pass over the project's own non-test `src/**` — {@link ApiLibExportShape}.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport * as ts from 'typescript';\nimport { ProjectInfo } from '../project-info';\nimport { resolveRole } from '../role-resolver';\nimport { ApiScanResult } from './api-scanner';\nimport { collectTsFiles, isTestFile } from './api-ast';\n\nconst API_LIB_ROLE = 'api-lib';\nconst API_CLIENT_ROLE = 'api-client';\n\n/** The decorators that make an abstract class an IPC contract. */\nconst IPC_DECORATORS: readonly string[] = ['WpInternal', 'WpIpcEndpoint'];\n\n/**\n * A tag/code mismatch:\n *  - 'missing-tag'     — exports an API contract but is tagged neither role:api-lib nor role:api-client.\n *  - 'unnecessary-tag' — tagged role:api-lib / role:api-client but exports no contract, and (for\n *                        api-lib) is not a DTO-only library either; `offenders` names what it exports.\n */\nexport class ApiLibTagViolation {\n    constructor(\n        public readonly project: string,\n        public readonly kind: 'missing-tag' | 'unnecessary-tag',\n        /** The role it carries (for 'unnecessary-tag'), else the role it should carry. */\n        public readonly role: string,\n        /** Exports that are neither a contract nor a wire type — empty for 'missing-tag'. */\n        public readonly offenders: readonly string[] = [],\n    ) {}\n}\n\n/** What a library's own source exports, sorted into contracts, wire types and everything else. */\nexport class ApiLibExportShape {\n    constructor(\n        /** True when it exports an IPC contract or an in-process abstract `…Api`. */\n        public readonly exportsContract: boolean,\n        /** True when it exports at least one wire type (interface, alias, enum, data class). */\n        public readonly exportsWireType: boolean,\n        /** `kind Name (file)` of every export that is neither — the implementation an api-lib must not hold. */\n        public readonly offenders: readonly string[],\n    ) {}\n\n    /** A role:api-lib passes when it holds a contract or wire types, and nothing else. */\n    isApiLib(): boolean {\n        return (this.exportsContract || this.exportsWireType) && this.offenders.length === 0;\n    }\n\n    /** Parser-only: every top-level EXPORTED declaration in the project's non-test `src/**`. */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static read(projectDir: string): ApiLibExportShape {\n        const srcDir = path.join(projectDir, 'src');\n        const acc = new ExportShapeAccumulator(projectDir);\n        if (fs.existsSync(srcDir)) {\n            for (const file of collectTsFiles(srcDir)) {\n                if (isTestFile(file)) continue;\n                const source = ts.createSourceFile(\n                    file,\n                    fs.readFileSync(file, 'utf8'),\n                    ts.ScriptTarget.Latest,\n                    true,\n                );\n                for (const statement of source.statements) acc.add(statement, file);\n            }\n        }\n        return acc.shape();\n    }\n}\n\n/** Sorts each exported statement of one library into contract / wire type / offender. */\nclass ExportShapeAccumulator {\n    private contract = false;\n    private wire = false;\n    private readonly offenders: string[] = [];\n    private readonly apiInterfaces = new Set<string>();\n    private readonly registeredApiImplementations = new Set<string>();\n\n    constructor(private readonly projectDir: string) {}\n\n    add(statement: ts.Statement, file: string): void {\n        if (!this.isExported(statement)) return;\n        const where = path.relative(this.projectDir, file);\n        if (ts.isInterfaceDeclaration(statement)) {\n            this.wire = true;\n            if (statement.name.text.endsWith('Api')) this.apiInterfaces.add(statement.name.text);\n        } else if (ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement)) {\n            this.wire = true;\n        } else if (ts.isClassDeclaration(statement)) {\n            this.addClass(statement, where);\n        } else if (ts.isVariableStatement(statement)) {\n            for (const decl of statement.declarationList.declarations) {\n                if (this.isDiToken(decl.initializer) || this.isDataConstant(decl.initializer))\n                    continue;\n                this.offenders.push(`const ${decl.name.getText()} (${where})`);\n            }\n        } else if (ts.isFunctionDeclaration(statement)) {\n            this.offenders.push(`function ${statement.name?.text ?? '<default>'} (${where})`);\n        }\n    }\n\n    shape(): ApiLibExportShape {\n        const registeredInterface = [...this.apiInterfaces].some((name: string) =>\n            this.registeredApiImplementations.has(name),\n        );\n        return new ApiLibExportShape(\n            this.contract || registeredInterface,\n            this.wire,\n            [...this.offenders].sort(),\n        );\n    }\n\n    private addClass(cls: ts.ClassDeclaration, where: string): void {\n        const name = cls.name?.text ?? '<default>';\n        if (this.hasDecorator(cls, 'provideSingletonDefaultForApi')) {\n            for (const heritage of cls.heritageClauses ?? []) {\n                if (heritage.token !== ts.SyntaxKind.ImplementsKeyword) continue;\n                for (const type of heritage.types) {\n                    const implemented = type.expression.getText().split('.').pop();\n                    if (implemented !== undefined)\n                        this.registeredApiImplementations.add(implemented);\n                }\n            }\n        }\n        const isAbstract = (ts.getModifiers(cls) ?? []).some(\n            (m: ts.Modifier) => m.kind === ts.SyntaxKind.AbstractKeyword,\n        );\n        if (isAbstract && (name.endsWith('Api') || this.carriesIpc(cls))) {\n            this.contract = true;\n            return;\n        }\n        const hasMethod = cls.members.some(\n            (member: ts.ClassElement) =>\n                ts.isMethodDeclaration(member) &&\n                !(ts.getModifiers(member) ?? []).some(\n                    (m: ts.Modifier) => m.kind === ts.SyntaxKind.StaticKeyword,\n                ),\n        );\n        if (hasMethod)\n            this.offenders.push(\n                `class ${name} (${where}) — it has methods, so it is an implementation`,\n            );\n        else this.wire = true;\n    }\n\n    /** `@WpInternal(...)` on the class or `@WpIpcEndpoint(...)` on any member. */\n    private carriesIpc(cls: ts.ClassDeclaration): boolean {\n        const named = (node: ts.Node): boolean =>\n            IPC_DECORATORS.some((name: string) => this.hasDecorator(node, name));\n        return named(cls) || cls.members.some((member: ts.ClassElement) => named(member));\n    }\n\n    private hasDecorator(node: ts.Node, expected: string): boolean {\n        return (ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : []).some(\n            (decorator: ts.Decorator) => {\n                const expr = ts.isCallExpression(decorator.expression)\n                    ? decorator.expression.expression\n                    : decorator.expression;\n                const name = ts.isPropertyAccessExpression(expr) ? expr.name.text : expr.getText();\n                return name === expected;\n            },\n        );\n    }\n\n    /** Literal/structural protocol data is contract support, not an executable implementation. */\n    private isDataConstant(init: ts.Expression | undefined): boolean {\n        if (init === undefined) return false;\n        const expr = this.unwrap(init);\n        if (\n            ts.isStringLiteralLike(expr) ||\n            ts.isNumericLiteral(expr) ||\n            expr.kind === ts.SyntaxKind.TrueKeyword ||\n            expr.kind === ts.SyntaxKind.FalseKeyword ||\n            expr.kind === ts.SyntaxKind.NullKeyword ||\n            ts.isIdentifier(expr) ||\n            ts.isPropertyAccessExpression(expr)\n        ) {\n            return true;\n        }\n        if (ts.isPrefixUnaryExpression(expr)) return this.isDataConstant(expr.operand);\n        if (ts.isBinaryExpression(expr)) {\n            return this.isDataConstant(expr.left) && this.isDataConstant(expr.right);\n        }\n        if (ts.isConditionalExpression(expr)) {\n            return (\n                this.isDataConstant(expr.condition) &&\n                this.isDataConstant(expr.whenTrue) &&\n                this.isDataConstant(expr.whenFalse)\n            );\n        }\n        if (ts.isTemplateExpression(expr)) {\n            return expr.templateSpans.every((span: ts.TemplateSpan) =>\n                this.isDataConstant(span.expression),\n            );\n        }\n        if (ts.isArrayLiteralExpression(expr)) {\n            return expr.elements.every(\n                (element: ts.Expression) =>\n                    ts.isOmittedExpression(element) ||\n                    (ts.isSpreadElement(element)\n                        ? this.isDataConstant(element.expression)\n                        : this.isDataConstant(element)),\n            );\n        }\n        if (ts.isObjectLiteralExpression(expr)) {\n            return expr.properties.every((prop: ts.ObjectLiteralElementLike) => {\n                if (ts.isPropertyAssignment(prop)) return this.isDataConstant(prop.initializer);\n                if (ts.isShorthandPropertyAssignment(prop)) return true;\n                if (ts.isSpreadAssignment(prop)) return this.isDataConstant(prop.expression);\n                return false;\n            });\n        }\n        return false;\n    }\n\n    private unwrap(expr: ts.Expression): ts.Expression {\n        if (\n            ts.isAsExpression(expr) ||\n            ts.isTypeAssertionExpression(expr) ||\n            ts.isSatisfiesExpression(expr) ||\n            ts.isParenthesizedExpression(expr) ||\n            ts.isNonNullExpression(expr)\n        ) {\n            return this.unwrap(expr.expression);\n        }\n        return expr;\n    }\n\n    /** `Symbol('x')`, `Symbol.for('x')`, or an object literal of them — the token an abstract `…Api` binds behind. */\n    private isDiToken(init: ts.Expression | undefined): boolean {\n        if (init === undefined) return false;\n        const expr =\n            ts.isAsExpression(init) || ts.isSatisfiesExpression(init) ? init.expression : init;\n        if (ts.isCallExpression(expr)) {\n            const callee = expr.expression.getText();\n            return callee === 'Symbol' || callee === 'Symbol.for';\n        }\n        if (ts.isObjectLiteralExpression(expr)) {\n            return (\n                expr.properties.length > 0 &&\n                expr.properties.every(\n                    (prop: ts.ObjectLiteralElementLike) =>\n                        ts.isPropertyAssignment(prop) && this.isDiToken(prop.initializer),\n                )\n            );\n        }\n        return false;\n    }\n\n    private isExported(statement: ts.Statement): boolean {\n        if (!ts.canHaveModifiers(statement)) return false;\n        return (ts.getModifiers(statement) ?? []).some(\n            (m: ts.Modifier) => m.kind === ts.SyntaxKind.ExportKeyword,\n        );\n    }\n}\n\n/** Both-directions tag ⇔ code check. Uses the scan's detected api-lib set as ground truth for @ApiPath. */\n// webpieces-disable no-function-outside-class -- validator-lib entry point, matches api-relations-validator.ts\nexport function findApiLibTagViolations(\n    projectInfos: Map<string, ProjectInfo>,\n    scan: ApiScanResult,\n    workspaceRoot: string,\n): ApiLibTagViolation[] {\n    const violations: ApiLibTagViolation[] = [];\n    for (const projectName of projectInfos.keys()) {\n        const info = projectInfos.get(projectName)!;\n        const role = resolveRole(info).role;\n        const isApiRole = role === API_LIB_ROLE || role === API_CLIENT_ROLE;\n        const exportsApi = scan.apiLibProjects.has(projectName);\n\n        if (exportsApi && !isApiRole) {\n            violations.push(new ApiLibTagViolation(projectName, 'missing-tag', API_LIB_ROLE));\n        }\n        // Only judge a tag when we actually SCANNED the project's source — otherwise we can't prove it\n        // exports no contract (an unscannable project would falsely look empty).\n        if (!isApiRole || exportsApi || !scan.scannedProjects.has(projectName)) continue;\n        const shape = ApiLibExportShape.read(path.resolve(workspaceRoot, info.root));\n        const ok = role === API_CLIENT_ROLE ? shape.exportsContract : shape.isApiLib();\n        if (!ok)\n            violations.push(\n                new ApiLibTagViolation(projectName, 'unnecessary-tag', role, shape.offenders),\n            );\n    }\n    return violations.sort((a: ApiLibTagViolation, b: ApiLibTagViolation) =>\n        a.project.localeCompare(b.project),\n    );\n}\n\n/** Human-readable, fix-oriented report for one tag/code mismatch. */\n// webpieces-disable no-function-outside-class -- pure formatter, matches api-relations-validator.ts\nexport function describeApiLibTagViolation(violation: ApiLibTagViolation): string {\n    if (violation.kind === 'missing-tag') {\n        return (\n            `  ❌ '${violation.project}' exports an API contract (an abstract @ApiPath/@Rpc/@PubSub class) ` +\n            `but is tagged neither 'role:api-lib' nor 'role:api-client'.\\n` +\n            `     Add \"role:api-lib\" to its project.json \"tags\" (replacing any \"role:lib\"), or \"role:api-client\" ` +\n            `when it also bundles the default implementation that talks to an outside system.`\n        );\n    }\n    if (violation.role === API_CLIENT_ROLE) {\n        return (\n            `  ❌ '${violation.project}' is tagged 'role:api-client' but exports NO contract (no abstract ` +\n            `…Api class, no @WpInternal/@WpIpcEndpoint contract, and no exported …Api interface implemented ` +\n            `by an @provideSingletonDefaultForApi client).\\n` +\n            `     An api-client is a contract PLUS its default implementation: export the XxxApi the registered ` +\n            `client implements, or retag it (e.g. \"role:lib\").`\n        );\n    }\n    const offenders =\n        violation.offenders.length === 0\n            ? ''\n            : `\\n     It exports, besides contracts and wire types: ${violation.offenders.join('; ')}.`;\n    return (\n        `  ❌ '${violation.project}' is tagged 'role:api-lib' but is neither a contract library (@ApiPath/@Rpc/` +\n        `@PubSub, @WpInternal/@WpIpcEndpoint, or an abstract …Api behind a DI token) nor a DTO-only library ` +\n        `(interfaces, type aliases, enums and data classes only).${offenders}\\n` +\n        `     Move the implementation out to a role:lib / role:designed-lib project, or retag it.`\n    );\n}\n"]}

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

@@ -32,6 +32,7 @@ import { ProjectInfo } from '../project-info';
 import { ApiClassInfo, ApiContracts, EmptiedApiContract, NonLiteralDecoratorArg, ProjectApiRelations, UndeclaredExternalCaller, UndeclaredEndpointOperation, UnresolvedApiCall, UnresolvedEndpointPath } from './api-relations';
 import { RootUnionFindings, RootUnionRule } from './root-union-scan';
 import { ApiDocRule, ApiDocRulesFindings } from './api-doc-rules';
+import { WireClosureRule } from './wire-closure';
 /** The whole-workspace result of a scan. */
 export interface ApiScanResult {
     /** projectName -> { apiLibProject -> relation }; only projects with ≥1 relation appear. */
@@ -95,6 +96,7 @@ export declare class ApiUsageScanner {
     private readonly openApiRule;
     /** `api-rules-for-mcp`'s switches — read from the config, which MUST state them (#1017). */
     private readonly mcpRule;
+    private readonly wireClosureRule;
     private readonly locator;
     private readonly relationsByProject;
     private readonly scannedProjects;
@@ -109,7 +111,7 @@ export declare class ApiUsageScanner {
     /** `api-rules-for-openapi`'s switches — read from the config, which MUST state them (#1017). */
     openApiRule?: ApiDocRule, 
     /** `api-rules-for-mcp`'s switches — read from the config, which MUST state them (#1017). */
-    mcpRule?: ApiDocRule);
+    mcpRule?: ApiDocRule, wireClosureRule?: WireClosureRule);
     scan(): ApiScanResult;
     private scanProject;
     private visit;

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

@@ -46,6 +46,7 @@ const api_contract_errors_1 = require("./api-contract-errors");
 const root_union_scan_1 = require("./root-union-scan");
 const api_doc_rules_1 = require("./api-doc-rules");
 const api_doc_rules_scan_1 = require("./api-doc-rules-scan");
+const wire_closure_1 = require("./wire-closure");
 const api_ast_1 = require("./api-ast");
 const RPC_CLIENT_METHOD = 'createRpcClient';
 const PUBSUB_CLIENT_METHOD = 'createPubSubClient';
@@ -210,6 +211,7 @@ class ApiUsageScanner {
     rootUnionRule;
     openApiRule;
     mcpRule;
+    wireClosureRule;
     locator;
     relationsByProject = new Map();
     scannedProjects = new Set();
@@ -224,13 +226,14 @@ class ApiUsageScanner {
     /** `api-rules-for-openapi`'s switches — read from the config, which MUST state them (#1017). */
     openApiRule = api_doc_rules_1.ApiDocRule.off(api_doc_rules_1.OPENAPI_RULE), 
     /** `api-rules-for-mcp`'s switches — read from the config, which MUST state them (#1017). */
-    mcpRule = api_doc_rules_1.ApiDocRule.off(api_doc_rules_1.MCP_RULE)) {
+    mcpRule = api_doc_rules_1.ApiDocRule.off(api_doc_rules_1.MCP_RULE), wireClosureRule = wire_closure_1.WireClosureRule.withoutSuffixes()) {
         this.workspaceRoot = workspaceRoot;
         this.projectInfos = projectInfos;
         this.externalApiPaths = externalApiPaths;
         this.rootUnionRule = rootUnionRule;
         this.openApiRule = openApiRule;
         this.mcpRule = mcpRule;
+        this.wireClosureRule = wireClosureRule;
         this.locator = new ProjectLocator(workspaceRoot, projectInfos);
         this.decoratorArgDiagnostics = new api_ast_1.DecoratorArgDiagnostics(workspaceRoot);
     }
@@ -255,7 +258,7 @@ class ApiUsageScanner {
             undeclaredExternalCallers: this.decoratorArgDiagnostics.undeclaredExternalCallers(),
             undeclaredEndpointOperations: this.decoratorArgDiagnostics.undeclaredEndpointOperations(),
             rootUnions: new root_union_scan_1.RootUnionScan(this.workspaceRoot, this.projectInfos, this.rootUnionRule).run(),
-            apiDocRules: new api_doc_rules_scan_1.ApiDocRulesScan(this.workspaceRoot, this.projectInfos, this.openApiRule, this.mcpRule).run(),
+            apiDocRules: new api_doc_rules_scan_1.ApiDocRulesScan(this.workspaceRoot, this.projectInfos, this.openApiRule, this.mcpRule, this.wireClosureRule).run(),
         };
     }
     scanProject(info) {
@@ -400,7 +403,7 @@ exports.ApiUsageScanner = ApiUsageScanner;
  */
 // webpieces-disable no-function-outside-class -- module entry point, mirrors generateReducedGraph/collectBindings
 function scanAndAttachApiRelations(workspaceRoot, graph, projectInfos, externalApiPaths = []) {
-    const result = new ApiUsageScanner(workspaceRoot, projectInfos, externalApiPaths, root_union_scan_1.RootUnionRule.fromConfig(workspaceRoot), api_doc_rules_1.ApiDocRule.fromConfig(workspaceRoot, api_doc_rules_1.OPENAPI_RULE), api_doc_rules_1.ApiDocRule.fromConfig(workspaceRoot, api_doc_rules_1.MCP_RULE)).scan();
+    const result = new ApiUsageScanner(workspaceRoot, projectInfos, externalApiPaths, root_union_scan_1.RootUnionRule.fromConfig(workspaceRoot), api_doc_rules_1.ApiDocRule.fromConfig(workspaceRoot, api_doc_rules_1.OPENAPI_RULE), api_doc_rules_1.ApiDocRule.fromConfig(workspaceRoot, api_doc_rules_1.MCP_RULE), wire_closure_1.WireClosureRule.fromConfig(workspaceRoot)).scan();
     for (const projectName of result.relationsByProject.keys()) {
         const entry = graph[projectName];
         if (entry)