@starci/eslint-canon-be 3.5.0 → 3.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +11 -2
  3. package/dist/ambient-id.d.ts +9 -0
  4. package/{ambient-id.mjs → dist/ambient-id.js} +43 -39
  5. package/dist/app-composition.d.ts +21 -0
  6. package/{app-composition.mjs → dist/app-composition.js} +396 -300
  7. package/dist/async-discipline.d.ts +9 -0
  8. package/dist/async-discipline.js +77 -0
  9. package/dist/authorization.d.ts +12 -0
  10. package/{authorization.mjs → dist/authorization.js} +53 -59
  11. package/dist/boundary-schema.d.ts +15 -0
  12. package/{boundary-schema.mjs → dist/boundary-schema.js} +120 -105
  13. package/dist/builders.d.ts +21 -0
  14. package/{builders.mjs → dist/builders.js} +162 -146
  15. package/dist/cli.d.ts +15 -0
  16. package/{cli.mjs → dist/cli.js} +97 -82
  17. package/dist/comments.d.ts +52 -0
  18. package/dist/comments.js +412 -0
  19. package/dist/config-owner.d.ts +24 -0
  20. package/{config-owner.mjs → dist/config-owner.js} +256 -219
  21. package/dist/connections.d.ts +12 -0
  22. package/{connections.mjs → dist/connections.js} +138 -140
  23. package/dist/cookies.d.ts +9 -0
  24. package/{cookies.mjs → dist/cookies.js} +58 -58
  25. package/dist/cqrs.d.ts +27 -0
  26. package/{cqrs.mjs → dist/cqrs.js} +341 -282
  27. package/dist/data-access.d.ts +50 -0
  28. package/{data-access.mjs → dist/data-access.js} +238 -243
  29. package/dist/default-deny.d.ts +15 -0
  30. package/{default-deny.mjs → dist/default-deny.js} +103 -88
  31. package/dist/e2e-flow.d.ts +25 -0
  32. package/{e2e-flow.mjs → dist/e2e-flow.js} +113 -112
  33. package/dist/edge-hardening.d.ts +10 -0
  34. package/dist/edge-hardening.js +173 -0
  35. package/dist/error-handling.d.ts +21 -0
  36. package/{error-handling.mjs → dist/error-handling.js} +289 -239
  37. package/dist/event-bus.d.ts +14 -0
  38. package/{event-bus.mjs → dist/event-bus.js} +146 -129
  39. package/dist/feature-thin.d.ts +12 -0
  40. package/{feature-thin.mjs → dist/feature-thin.js} +208 -191
  41. package/dist/function-budget.d.ts +7 -0
  42. package/{function-budget.mjs → dist/function-budget.js} +24 -27
  43. package/dist/health-ready.d.ts +10 -0
  44. package/dist/health-ready.js +703 -0
  45. package/dist/idempotency.d.ts +10 -0
  46. package/{idempotency.mjs → dist/idempotency.js} +296 -226
  47. package/dist/index.d.ts +54 -0
  48. package/{index.mjs → dist/index.js} +91 -109
  49. package/dist/infra-owner.d.ts +18 -0
  50. package/{infra-owner.mjs → dist/infra-owner.js} +58 -51
  51. package/dist/injection.d.ts +30 -0
  52. package/{injection.mjs → dist/injection.js} +397 -344
  53. package/dist/input-bounds.d.ts +15 -0
  54. package/{input-bounds.mjs → dist/input-bounds.js} +143 -132
  55. package/dist/jobs.d.ts +17 -0
  56. package/{jobs.mjs → dist/jobs.js} +116 -99
  57. package/dist/jwt-alg.d.ts +6 -0
  58. package/dist/jwt-alg.js +49 -0
  59. package/dist/lib/app-roles.d.ts +25 -0
  60. package/{lib/app-roles.mjs → dist/lib/app-roles.js} +15 -17
  61. package/dist/lib/ast.d.ts +40 -0
  62. package/dist/lib/ast.js +100 -0
  63. package/dist/lib/client-idempotency.d.ts +3 -0
  64. package/{lib/client-idempotency.mjs → dist/lib/client-idempotency.js} +316 -268
  65. package/dist/lib/config.d.ts +36 -0
  66. package/{lib/config.mjs → dist/lib/config.js} +24 -27
  67. package/dist/lib/db-writes.d.ts +29 -0
  68. package/{lib/db-writes.mjs → dist/lib/db-writes.js} +27 -27
  69. package/dist/lib/declared.d.ts +77 -0
  70. package/{lib/declared.mjs → dist/lib/declared.js} +83 -78
  71. package/dist/lib/doors.d.ts +50 -0
  72. package/{lib/doors.mjs → dist/lib/doors.js} +45 -50
  73. package/dist/lib/edition.d.ts +25 -0
  74. package/{lib/edition.mjs → dist/lib/edition.js} +15 -20
  75. package/dist/lib/entity-writes.d.ts +7 -0
  76. package/{lib/entity-writes.mjs → dist/lib/entity-writes.js} +31 -22
  77. package/dist/lib/hfs.d.ts +34 -0
  78. package/{lib/hfs.mjs → dist/lib/hfs.js} +31 -29
  79. package/dist/lib/import-source.d.ts +63 -0
  80. package/dist/lib/import-source.js +134 -0
  81. package/dist/lib/path.d.ts +8 -0
  82. package/{lib/path.mjs → dist/lib/path.js} +4 -7
  83. package/dist/lib/persistence.d.ts +115 -0
  84. package/{lib/persistence.mjs → dist/lib/persistence.js} +55 -66
  85. package/dist/lib/ports.d.ts +70 -0
  86. package/{lib/ports.mjs → dist/lib/ports.js} +62 -66
  87. package/dist/lib/rule.d.ts +31 -0
  88. package/dist/lib/rule.js +2 -0
  89. package/dist/lib/runtime-root.d.ts +4 -0
  90. package/dist/lib/runtime-root.js +10 -0
  91. package/dist/lib/schema-values.d.ts +13 -0
  92. package/{lib/schema-values.mjs → dist/lib/schema-values.js} +67 -59
  93. package/dist/lib/specifier.d.ts +12 -0
  94. package/dist/lib/specifier.js +29 -0
  95. package/dist/lib/subject-values.d.ts +4 -0
  96. package/dist/lib/subject-values.js +61 -0
  97. package/dist/lib/transactions.d.ts +18 -0
  98. package/{lib/transactions.mjs → dist/lib/transactions.js} +17 -15
  99. package/dist/lib/transport-slots.d.ts +17 -0
  100. package/{lib/transport-slots.mjs → dist/lib/transport-slots.js} +2 -4
  101. package/dist/lib/types.d.ts +96 -0
  102. package/dist/lib/types.js +150 -0
  103. package/dist/lib/unit-spec.d.ts +48 -0
  104. package/{lib/unit-spec.mjs → dist/lib/unit-spec.js} +35 -44
  105. package/dist/lib/webhook-ack.d.ts +4 -0
  106. package/{lib/webhook-ack.mjs → dist/lib/webhook-ack.js} +78 -62
  107. package/dist/lib/webhook-handoff-inbox.d.ts +3 -0
  108. package/{lib/webhook-handoff-inbox.mjs → dist/lib/webhook-handoff-inbox.js} +195 -167
  109. package/dist/lib/webhook-handoff-intake.d.ts +4 -0
  110. package/{lib/webhook-handoff-intake.mjs → dist/lib/webhook-handoff-intake.js} +125 -102
  111. package/dist/lib/webhook-handoff.d.ts +15 -0
  112. package/{lib/webhook-handoff.mjs → dist/lib/webhook-handoff.js} +107 -100
  113. package/dist/lib/webhook-verifiers.d.ts +20 -0
  114. package/{lib/webhook-verifiers.mjs → dist/lib/webhook-verifiers.js} +108 -104
  115. package/dist/lib/why.d.ts +9 -0
  116. package/{lib/why.mjs → dist/lib/why.js} +6 -6
  117. package/dist/log-safety.d.ts +20 -0
  118. package/dist/log-safety.js +308 -0
  119. package/dist/module-layering.d.ts +42 -0
  120. package/dist/module-layering.js +257 -0
  121. package/dist/module-shape.d.ts +47 -0
  122. package/{module-shape.mjs → dist/module-shape.js} +278 -236
  123. package/dist/naming.d.ts +49 -0
  124. package/dist/naming.js +246 -0
  125. package/dist/observability.d.ts +25 -0
  126. package/dist/observability.js +245 -0
  127. package/dist/operations.d.ts +23 -0
  128. package/{operations.mjs → dist/operations.js} +410 -332
  129. package/dist/project-graph.d.ts +9 -0
  130. package/{project-graph.mjs → dist/project-graph.js} +8 -13
  131. package/dist/projections.d.ts +11 -0
  132. package/{projections.mjs → dist/projections.js} +60 -57
  133. package/dist/query-safety.d.ts +21 -0
  134. package/{query-safety.mjs → dist/query-safety.js} +92 -108
  135. package/dist/realtime.d.ts +15 -0
  136. package/{realtime.mjs → dist/realtime.js} +108 -106
  137. package/dist/resilience.d.ts +15 -0
  138. package/dist/resilience.js +319 -0
  139. package/dist/schema-authority.d.ts +15 -0
  140. package/{schema-authority.mjs → dist/schema-authority.js} +256 -220
  141. package/dist/service-deps.d.ts +17 -0
  142. package/{service-deps.mjs → dist/service-deps.js} +133 -130
  143. package/dist/service-isolation.d.ts +8 -0
  144. package/dist/service-isolation.js +76 -0
  145. package/dist/size-budget.d.ts +9 -0
  146. package/{size-budget.mjs → dist/size-budget.js} +27 -27
  147. package/dist/sonar-parity.d.ts +5 -0
  148. package/{sonar-parity.mjs → dist/sonar-parity.js} +7 -7
  149. package/dist/spec-no-skip.d.ts +9 -0
  150. package/dist/spec-no-skip.js +81 -0
  151. package/dist/spec-quality.d.ts +10 -0
  152. package/{spec-quality.mjs → dist/spec-quality.js} +103 -87
  153. package/dist/suppression.d.ts +26 -0
  154. package/{suppression.mjs → dist/suppression.js} +30 -45
  155. package/dist/temporal.d.ts +9 -0
  156. package/{temporal.mjs → dist/temporal.js} +75 -65
  157. package/dist/test-world.d.ts +28 -0
  158. package/{test-world.mjs → dist/test-world.js} +102 -83
  159. package/dist/testing.d.ts +51 -0
  160. package/dist/testing.js +368 -0
  161. package/dist/third-party-owner.d.ts +8 -0
  162. package/{third-party-owner.mjs → dist/third-party-owner.js} +105 -91
  163. package/dist/transport.d.ts +24 -0
  164. package/{transport.mjs → dist/transport.js} +279 -240
  165. package/dist/type-safety.d.ts +25 -0
  166. package/dist/type-safety.js +297 -0
  167. package/dist/unit-spec.d.ts +30 -0
  168. package/{unit-spec.mjs → dist/unit-spec.js} +473 -399
  169. package/dist/uploads.d.ts +9 -0
  170. package/{uploads.mjs → dist/uploads.js} +62 -54
  171. package/dist/user-copy.d.ts +9 -0
  172. package/{user-copy.mjs → dist/user-copy.js} +76 -67
  173. package/dist/webhooks.d.ts +16 -0
  174. package/{webhooks.mjs → dist/webhooks.js} +243 -231
  175. package/package.json +17 -8
  176. package/runtime/knowledge/hfs/canon-pins.yaml +17 -10
  177. package/async-discipline.mjs +0 -83
  178. package/comments.mjs +0 -416
  179. package/edge-hardening.mjs +0 -139
  180. package/health-ready.mjs +0 -539
  181. package/jwt-alg.mjs +0 -45
  182. package/lib/ast.mjs +0 -88
  183. package/lib/import-source.mjs +0 -104
  184. package/lib/specifier.mjs +0 -27
  185. package/lib/subject-values.mjs +0 -55
  186. package/lib/types.mjs +0 -133
  187. package/log-safety.mjs +0 -303
  188. package/module-layering.mjs +0 -270
  189. package/naming.mjs +0 -251
  190. package/observability.mjs +0 -241
  191. package/resilience.mjs +0 -304
  192. package/service-isolation.mjs +0 -75
  193. package/spec-no-skip.mjs +0 -85
  194. package/testing.mjs +0 -384
  195. package/type-safety.mjs +0 -323
@@ -0,0 +1,703 @@
1
+ /** R262: API health routes are wired and readiness checks a required dependency under a failing, bounded timeout. */
2
+ import fs from "node:fs";
3
+ import path from "node:path";
4
+ import tsParser from "@typescript-eslint/parser";
5
+ import { appRoleOf } from "./lib/app-roles.js";
6
+ import { hfsOf } from "./lib/hfs.js";
7
+ import { decoratorName, keyName, paramParts, staticText, walk } from "./lib/ast.js";
8
+ import { decoratorArguments } from "./lib/import-source.js";
9
+ import { isNode } from "./lib/rule.js";
10
+ const WIRING_FIELDS = ["imports", "controllers"];
11
+ const isWrapper = (node) => node?.type === "TSAsExpression" || node?.type === "TSNonNullExpression" || node?.type === "ChainExpression" || node?.type === "TSSatisfiesExpression";
12
+ const isNamedClass = (node) => node.type === "ClassDeclaration" && node.id !== null;
13
+ const isClassFound = (found) => found?.controller.type === "ClassDeclaration";
14
+ const isObjectExpression = (node) => node.type === "ObjectExpression";
15
+ /** `node.name` when it is a string (an identifier's name), else undefined. */
16
+ const nameOf = (node) => {
17
+ const name = node && "name" in node ? node.name : undefined;
18
+ return typeof name === "string" ? name : undefined;
19
+ };
20
+ /** `node.body` of any node, else undefined. */
21
+ const bodyOf = (node) => (node && "body" in node ? node.body : undefined);
22
+ /** `node.typeAnnotation` of any node, else undefined. */
23
+ const annotationOf = (node) => (node && "typeAnnotation" in node ? node.typeAnnotation : undefined);
24
+ /** `node.returnType` of any node, else undefined. */
25
+ const returnTypeOf = (node) => (node && "returnType" in node ? node.returnType : undefined);
26
+ /** `node.value` of any node when it is a node, else undefined. */
27
+ const valueNodeOf = (node) => {
28
+ const value = node && "value" in node ? node.value : undefined;
29
+ return isNode(value) ? value : undefined;
30
+ };
31
+ /** `node.params` of any node, else undefined. */
32
+ const paramsOf = (node) => (node && "params" in node ? node.params : undefined);
33
+ /** The key of an object literal entry (a spread has none). */
34
+ const propertyKey = (entry) => (entry.type === "Property" ? entry.key : undefined);
35
+ /** The value of the object literal entry keyed `name`. */
36
+ const propertyValue = (object, name) => {
37
+ const found = object.properties.find((entry) => keyName(propertyKey(entry)) === name);
38
+ return found?.type === "Property" ? found.value : undefined;
39
+ };
40
+ /** The name an import clause takes from its module (`undefined` for a default or namespace import). */
41
+ const importedNode = (specifier) => (specifier.type === "ImportSpecifier" ? specifier.imported : undefined);
42
+ const unwrap = (node) => {
43
+ while (isWrapper(node))
44
+ node = node.expression;
45
+ return node;
46
+ };
47
+ const memberName = (node) => node?.computed ? staticText(node.property) : keyName(node?.property);
48
+ const typeName = (node) => {
49
+ const annotation = node.typeAnnotation?.typeAnnotation;
50
+ return (annotation?.type === "TSTypeReference" ? nameOf(annotation.typeName) : undefined) ?? null;
51
+ };
52
+ const methodsOf = (node) => node.body.body.filter((entry) => entry.type === "MethodDefinition");
53
+ const classesOf = (program) => {
54
+ const classes = new Map();
55
+ walk(program, (node) => { if (isNamedClass(node))
56
+ classes.set(node.id.name, node); });
57
+ return classes;
58
+ };
59
+ const bindingsOf = (program) => {
60
+ const bindings = new Map();
61
+ walk(program, (node) => { if (node.type === "VariableDeclarator" && node.id.type === "Identifier" && node.init)
62
+ bindings.set(node.id.name, node.init); });
63
+ return bindings;
64
+ };
65
+ /** Expand local constants when proving a race: a timeout promise or duration may be held in a const. */
66
+ function expandedNodes(node, bindings, seen = new Set()) {
67
+ const nodes = [];
68
+ walk(node, (child) => {
69
+ nodes.push(child);
70
+ if (child.type !== "Identifier" || seen.has(child.name) || !bindings.has(child.name))
71
+ return;
72
+ const next = new Set(seen).add(child.name);
73
+ nodes.push(...expandedNodes(bindings.get(child.name), bindings, next));
74
+ });
75
+ return nodes;
76
+ }
77
+ function sourcePath(source, filename, root) {
78
+ let base = null;
79
+ if (source.startsWith("."))
80
+ base = path.resolve(path.dirname(filename), source);
81
+ if (source.startsWith("@modules/"))
82
+ base = path.join(root, "src/modules", source.slice(9));
83
+ if (source.startsWith("@features/"))
84
+ base = path.join(root, "src/features", source.slice(10));
85
+ if (!base || path.relative(root, base).startsWith(".."))
86
+ return null;
87
+ return [base, `${base}.ts`, path.join(base, "index.ts")].find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile()) ?? null;
88
+ }
89
+ function readProgram(filename) {
90
+ try {
91
+ return tsParser.parse(fs.readFileSync(filename, "utf8"), { sourceType: "module", ecmaVersion: "latest" });
92
+ }
93
+ catch {
94
+ return null;
95
+ }
96
+ }
97
+ const routesOf = (controller) => {
98
+ const decorator = controller.decorators?.find((entry) => decoratorName(entry) === "Controller");
99
+ if (!decorator)
100
+ return [];
101
+ const prefix = staticText(decoratorArguments(decorator)[0]) ?? "";
102
+ return methodsOf(controller).flatMap((method) => (method.decorators ?? []).filter((entry) => decoratorName(entry) === "Get").flatMap((entry) => {
103
+ const arg = decoratorArguments(entry)[0];
104
+ const paths = arg?.type === "ArrayExpression" ? arg.elements.map((element) => staticText(element)) : [staticText(arg) ?? ""];
105
+ return paths.filter((route) => route !== null).map((route) => ({ route: `/${prefix}/${route}`.replace(/\/+/g, "/").replace(/\/$/, ""), method }));
106
+ }));
107
+ };
108
+ function injectedOf(controller) {
109
+ const constructor = methodsOf(controller).find((entry) => entry.kind === "constructor");
110
+ return new Map((constructor?.value.params ?? []).flatMap((param) => {
111
+ const { target } = paramParts(param);
112
+ const name = nameOf(target);
113
+ return name ? [[name, typeName(target)]] : [];
114
+ }));
115
+ }
116
+ /** `controller.body?.body` of a declaration (`[]` for one without a body). */
117
+ const membersOf = (controller) => (controller.type === "ClassDeclaration" || controller.type === "TSInterfaceDeclaration" || controller.type === "FunctionDeclaration" ? controller.body?.body : undefined) ?? [];
118
+ /** `node.object` of a member expression, else undefined. */
119
+ const objectOf = (node) => (node?.type === "MemberExpression" ? node.object : undefined);
120
+ const injectedCall = (node, injected) => {
121
+ if (node.type !== "CallExpression")
122
+ return null;
123
+ const callee = unwrap(node.callee);
124
+ if (callee?.type !== "MemberExpression")
125
+ return null;
126
+ let owner = unwrap(objectOf(node.callee));
127
+ while (owner?.type === "CallExpression" && unwrap(owner.callee)?.type === "MemberExpression")
128
+ owner = unwrap(objectOf(owner.callee));
129
+ while (owner?.type === "MemberExpression" && owner.object?.type !== "ThisExpression")
130
+ owner = unwrap(owner.object);
131
+ if (owner?.type !== "MemberExpression" || owner.object?.type !== "ThisExpression")
132
+ return null;
133
+ const name = memberName(owner);
134
+ if (!injected.has(name) || /(?:queryBus|commandBus|logger|liveness|liveProbe)/i.test(`${name} ${injected.get(name)}`))
135
+ return null;
136
+ return { name, method: memberName(callee), type: injected.get(name) };
137
+ };
138
+ function positiveDuration(node, bindings, seen = new Set()) {
139
+ node = unwrap(node);
140
+ if (node?.type === "Identifier" && bindings.has(node.name) && !seen.has(node.name))
141
+ return positiveDuration(bindings.get(node.name), bindings, new Set(seen).add(node.name));
142
+ return node?.type === "Literal" && typeof node.value === "number" && Number.isFinite(node.value) && node.value > 0 && node.value <= 60000;
143
+ }
144
+ function resolvedType(node, source, seen = new Set()) {
145
+ if (node?.type !== "TSTypeReference")
146
+ return node;
147
+ const target = delegatedClass(nameOf(node.typeName), source.program, source.filename, source.root);
148
+ if (target?.controller.type !== "TSTypeAliasDeclaration")
149
+ return null;
150
+ const identity = `${target.filename}:${target.controller.id.name}`;
151
+ if (seen.has(identity))
152
+ return null;
153
+ return resolvedType(target.controller.typeAnnotation, { ...target, root: source.root }, new Set(seen).add(identity));
154
+ }
155
+ function timerMethod(call, injected, source) {
156
+ const dependency = injectedCall(call, injected);
157
+ if (!dependency)
158
+ return false;
159
+ const target = delegatedClass(dependency.type, source.program, source.filename, source.root);
160
+ if (!target)
161
+ return false;
162
+ const members = membersOf(target.controller);
163
+ const method = members.find((entry) => keyName("key" in entry ? entry.key : undefined) === dependency.method);
164
+ const params = paramsOf(method) ?? paramsOf(valueNodeOf(method)) ?? [];
165
+ const location = { ...target, root: source.root };
166
+ const callback = resolvedType(annotationOf(annotationOf(params[0])), location);
167
+ const returns = resolvedType(annotationOf(returnTypeOf(method)) ?? annotationOf(returnTypeOf(valueNodeOf(method))), location);
168
+ const delay = resolvedType(annotationOf(annotationOf(params[1])), location);
169
+ return callback?.type === "TSFunctionType" && callback.params.length === 0
170
+ && callback.returnType?.typeAnnotation?.type === "TSVoidKeyword"
171
+ && delay?.type === "TSNumberKeyword"
172
+ && returns?.type === "TSFunctionType" && returns.params.length === 0
173
+ && returns.returnType?.typeAnnotation?.type === "TSVoidKeyword"
174
+ && timerBinding(dependency, target, source);
175
+ }
176
+ function timerToken(name, source) {
177
+ const constructor = methodsOf(source.controller).find((entry) => entry.kind === "constructor");
178
+ const parameter = constructor?.value.params.map((param) => paramParts(param)).find((entry) => nameOf(entry.target) === name);
179
+ for (const decorator of parameter?.decorators ?? []) {
180
+ const target = delegatedClass(decoratorName(decorator), source.program, source.filename, source.root);
181
+ if (!target)
182
+ continue;
183
+ const init = "init" in target.controller ? target.controller.init : undefined;
184
+ const body = bodyOf(init) ?? bodyOf(target.controller);
185
+ const token = isNode(body) && body.type === "CallExpression" && nameOf(body.arguments[0]);
186
+ const resolved = token && delegatedClass(token, target.program, target.filename, source.root);
187
+ if (resolved)
188
+ return resolved;
189
+ }
190
+ return null;
191
+ }
192
+ function timerImplementation(target, methodName, contract, root) {
193
+ const controller = target.controller;
194
+ if (controller.type !== "ClassDeclaration")
195
+ return false;
196
+ const matches = controller.implements?.some((entry) => {
197
+ const implemented = delegatedClass(nameOf(entry.expression), target.program, target.filename, root);
198
+ return implemented && sameClass(implemented, contract);
199
+ });
200
+ if (!matches)
201
+ return false;
202
+ const method = methodsOf(controller).find((entry) => keyName(entry.key) === methodName);
203
+ if (!method?.value.body)
204
+ return false;
205
+ const [callback, delay] = method.value.params.map((entry) => nameOf(paramParts(entry).target));
206
+ const statements = method.value.body.body;
207
+ const declarations = statements.flatMap((entry) => entry.type === "VariableDeclaration" ? entry.declarations : []);
208
+ const scheduled = declarations.find((entry) => entry.init?.type === "CallExpression" && nameOf(entry.init.callee) === "setTimeout"
209
+ && nameOf(entry.init.arguments[0]) === callback && nameOf(entry.init.arguments[1]) === delay);
210
+ if (!scheduled)
211
+ return false;
212
+ return statements.some((entry) => entry.type === "ReturnStatement" && entry.argument?.type === "ArrowFunctionExpression"
213
+ && entry.argument.body?.type === "CallExpression" && nameOf(entry.argument.body.callee) === "clearTimeout"
214
+ && nameOf(entry.argument.body.arguments[0]) === nameOf(scheduled.id));
215
+ }
216
+ function providedTimer(module, token, dependency, contract, source) {
217
+ for (const object of moduleObjects(module)) {
218
+ const providers = propertyValue(object, "providers");
219
+ for (const node of expandedNodes(providers, bindingsOf(source.program)).filter(isObjectExpression)) {
220
+ const name = nameOf(propertyValue(node, "provide"));
221
+ const provided = name && delegatedClass(name, source.program, source.filename, source.root);
222
+ if (!provided || !sameClass(provided, token))
223
+ continue;
224
+ const implementation = nameOf(propertyValue(node, "useClass"));
225
+ const target = implementation && delegatedClass(implementation, source.program, source.filename, source.root);
226
+ if (target && target.controller.type === "ClassDeclaration" && timerImplementation(target, dependency.method, contract, source.root))
227
+ return true;
228
+ }
229
+ }
230
+ return false;
231
+ }
232
+ function timerBinding(dependency, contract, source) {
233
+ const token = timerToken(dependency.name, source);
234
+ if (!token)
235
+ return false;
236
+ const directory = path.dirname(contract.filename);
237
+ for (const entry of fs.readdirSync(directory).filter((name) => name.endsWith(".module.ts"))) {
238
+ const filename = path.join(directory, entry);
239
+ const program = readProgram(filename);
240
+ if (!program)
241
+ continue;
242
+ const location = { program, filename, root: source.root };
243
+ if ([...classesOf(program).values()].some((module) => providedTimer(module, token, dependency, contract, location)))
244
+ return true;
245
+ }
246
+ return false;
247
+ }
248
+ function rejectingTimeout(nodes, bindings, injected, source) {
249
+ return nodes.some((node) => {
250
+ if (node.type !== "CallExpression" || !positiveDuration(node.arguments[1], bindings))
251
+ return false;
252
+ const native = node.callee.type === "Identifier" && node.callee.name === "setTimeout";
253
+ if (!native && !timerMethod(node, injected, source))
254
+ return false;
255
+ return expandedNodes(node.arguments[0], bindings).some((entry) => entry.type === "CallExpression" && entry.callee.type === "Identifier" && entry.callee.name === "reject");
256
+ });
257
+ }
258
+ function parentsOf(body) {
259
+ const parents = new Map();
260
+ walk(body, (node) => {
261
+ const entries = Object.entries(node);
262
+ for (const [key, value] of entries) {
263
+ if (["parent", "loc", "range", "tokens", "comments"].includes(key))
264
+ continue;
265
+ const children = Array.isArray(value) ? value : [value];
266
+ for (const child of children)
267
+ if (isNode(child))
268
+ parents.set(child, node);
269
+ }
270
+ });
271
+ return parents;
272
+ }
273
+ function consumedCall(node, body, bindings) {
274
+ const parents = parentsOf(body);
275
+ const nodes = [];
276
+ walk(body, (entry) => nodes.push(entry));
277
+ return nodes.some((entry) => {
278
+ if (entry.type !== "AwaitExpression" && entry.type !== "ReturnStatement")
279
+ return false;
280
+ const parentType = parents.get(entry)?.type;
281
+ return expandedNodes(entry.argument, bindings).includes(node)
282
+ && !expandedNodes(entry.argument, bindings).some((child) => child.type === "UnaryExpression" && child.operator === "void")
283
+ && parentType !== "ArrowFunctionExpression" && parentType !== "FunctionExpression";
284
+ });
285
+ }
286
+ /** Whether a node is `Promise.reject(...)`. */
287
+ const rejected = (node) => isNode(node) && node.type === "CallExpression" && node.callee?.type === "MemberExpression"
288
+ && nameOf(node.callee.object) === "Promise" && memberName(node.callee) === "reject";
289
+ /** Whether a block throws or returns a rejection (undefined when the node holds no statement list). */
290
+ const fails = (block) => {
291
+ const statements = isNode(block) ? bodyOf(block) : undefined;
292
+ if (!Array.isArray(statements))
293
+ return undefined;
294
+ const list = statements;
295
+ return list.some((statement) => statement.type === "ThrowStatement" || statement.type === "ReturnStatement" && rejected(statement.argument));
296
+ };
297
+ /** A required dependency failure must still make the readiness promise fail. */
298
+ function propagatesFailures(body) {
299
+ const catches = [];
300
+ const promiseCatches = [];
301
+ walk(body, (node) => { if (node.type === "CatchClause")
302
+ catches.push(node); });
303
+ walk(body, (node) => { if (node.type === "CallExpression" && node.callee.type === "MemberExpression" && memberName(node.callee) === "catch")
304
+ promiseCatches.push(node.arguments[0]); });
305
+ return catches.every((node) => node.body.body.some((statement) => statement.type === "ThrowStatement"
306
+ || statement.type === "ReturnStatement" && statement.argument?.type === "CallExpression" && statement.argument.callee?.type === "MemberExpression"
307
+ && nameOf(statement.argument.callee.object) === "Promise" && memberName(statement.argument.callee) === "reject"))
308
+ && promiseCatches.every((callback) => callback && (rejected(bodyOf(callback)) || fails(bodyOf(callback))));
309
+ }
310
+ function boundedDependency(method, injected, bindings, source) {
311
+ if (!propagatesFailures(method.value.body))
312
+ return false;
313
+ const nodes = expandedNodes(method.value.body, bindings);
314
+ return nodes.some((node) => {
315
+ if (node.type !== "CallExpression" || !consumedCall(node, method.value.body, bindings))
316
+ return false;
317
+ const callee = unwrap(node.callee);
318
+ if (callee?.type !== "MemberExpression")
319
+ return false;
320
+ if (injectedCall(node, injected))
321
+ return requiredCall(node, injected, source) && expandedNodes(node, bindings).some((entry) => entry.type === "CallExpression"
322
+ && entry.callee.type === "MemberExpression" && nameOf(entry.callee.object) === "AbortSignal" && memberName(entry.callee) === "timeout" && positiveDuration(entry.arguments[0], bindings));
323
+ if (nameOf(callee.object) !== "Promise" || memberName(callee) !== "race")
324
+ return false;
325
+ const racers = expandedNodes(node.arguments[0], bindings);
326
+ return racers.some((entry) => requiredCall(entry, injected, source)) && rejectingTimeout(racers, bindings, injected, source);
327
+ });
328
+ }
329
+ function classInSource(name, program, filename, root, seen = new Set()) {
330
+ const identity = `${filename}:${name}`;
331
+ if (seen.has(identity))
332
+ return null;
333
+ const next = new Set(seen).add(identity);
334
+ let local = typeof name === "string" ? classesOf(program).get(name) : undefined;
335
+ walk(program, (node) => {
336
+ if ((node.type === "TSInterfaceDeclaration" || node.type === "TSTypeAliasDeclaration" || node.type === "VariableDeclarator" || node.type === "FunctionDeclaration") && nameOf(node.id) === name)
337
+ local = node;
338
+ });
339
+ if (local)
340
+ return { controller: local, program, filename };
341
+ for (const entry of program.body) {
342
+ if (entry.type !== "ExportNamedDeclaration" && entry.type !== "ExportAllDeclaration")
343
+ continue;
344
+ if (!entry.source)
345
+ continue;
346
+ const specifier = entry.type === "ExportNamedDeclaration" ? entry.specifiers?.find((node) => keyName(node.exported) === name) : undefined;
347
+ if (entry.type !== "ExportAllDeclaration" && !specifier)
348
+ continue;
349
+ const target = sourcePath(entry.source.value, filename, root);
350
+ const imported = target ? readProgram(target) : null;
351
+ const controller = imported && target ? classInSource(keyName(specifier?.local) ?? name, imported, target, root, next) : null;
352
+ if (controller)
353
+ return controller;
354
+ }
355
+ return null;
356
+ }
357
+ function delegatedClass(name, program, filename, root) {
358
+ const local = classInSource(name, program, filename, root);
359
+ if (local)
360
+ return local;
361
+ for (const entry of program.body) {
362
+ if (entry.type !== "ImportDeclaration")
363
+ continue;
364
+ const specifier = entry.specifiers.find((node) => node.local.name === name);
365
+ if (!specifier)
366
+ continue;
367
+ const target = sourcePath(entry.source.value, filename, root);
368
+ const imported = target ? readProgram(target) : null;
369
+ const controller = imported && target ? classInSource(nameOf(importedNode(specifier)) ?? name, imported, target, root) : null;
370
+ if (controller)
371
+ return controller;
372
+ }
373
+ return null;
374
+ }
375
+ function consumedDependencies(method, injected, source) {
376
+ const bindings = bindingsOf(source.program);
377
+ return expandedNodes(method.value.body, bindings).filter((node) => consumedCall(node, method.value.body, bindings))
378
+ .flatMap((node) => {
379
+ const call = injectedCall(node, injected);
380
+ return call ? [{ node, call }] : [];
381
+ });
382
+ }
383
+ function requiredCall(node, injected, source, visited = new Set()) {
384
+ const call = injectedCall(node, injected);
385
+ if (!call || timerMethod(node, injected, source))
386
+ return false;
387
+ const target = delegatedClass(call.type, source.program, source.filename, source.root);
388
+ if (!target)
389
+ return true;
390
+ if (!isClassFound(target))
391
+ return false;
392
+ const method = methodsOf(target.controller).find((entry) => keyName(entry.key) === call.method);
393
+ const identity = `${target.filename}:${call.type}:${call.method}`;
394
+ if (!method || visited.has(identity) || !propagatesFailures(method.value.body))
395
+ return false;
396
+ const next = new Set(visited).add(identity);
397
+ const location = { ...target, root: source.root };
398
+ const dependencies = injectedOf(target.controller);
399
+ return consumedDependencies(method, dependencies, location).some((entry) => requiredCall(entry.node, dependencies, location, next));
400
+ }
401
+ function importedAs(program, name, imported, module) {
402
+ return program.body.some((entry) => entry.type === "ImportDeclaration" && entry.source.value === module
403
+ && entry.specifiers.some((specifier) => specifier.local.name === name && keyName(importedNode(specifier)) === imported));
404
+ }
405
+ function moduleObjects(controller) {
406
+ const objects = [];
407
+ const decorator = controller.decorators?.find((entry) => decoratorName(entry) === "Module");
408
+ const declared = decoratorArguments(decorator)[0];
409
+ if (declared?.type === "ObjectExpression")
410
+ objects.push(declared);
411
+ for (const method of methodsOf(controller).filter((entry) => entry.static))
412
+ walk(method.value.body, (node) => {
413
+ if (node.type === "ReturnStatement" && node.argument?.type === "ObjectExpression")
414
+ objects.push(node.argument);
415
+ });
416
+ return objects;
417
+ }
418
+ function moduleReferences(controller, field, source) {
419
+ const names = new Set();
420
+ for (const object of moduleObjects(controller)) {
421
+ const value = propertyValue(object, field);
422
+ for (const node of expandedNodes(value, bindingsOf(source.program)))
423
+ if (node.type === "Identifier")
424
+ names.add(node.name);
425
+ }
426
+ return [...names].map((name) => delegatedClass(name, source.program, source.filename, source.root))
427
+ .filter(isClassFound);
428
+ }
429
+ const sameClass = (left, right) => left.filename === right.filename && nameOf(left.controller.id) === nameOf(right.controller.id);
430
+ function routeModules(controller, source) {
431
+ const roots = [];
432
+ let directory = path.dirname(source.filename);
433
+ while (!path.relative(source.root, directory).startsWith("..")) {
434
+ for (const entry of fs.readdirSync(directory).filter((name) => name.endsWith(".module.ts"))) {
435
+ const filename = path.join(directory, entry);
436
+ const program = readProgram(filename);
437
+ if (!program)
438
+ continue;
439
+ const location = { program, filename, root: source.root };
440
+ for (const module of classesOf(program).values()) {
441
+ const target = { controller, filename: source.filename };
442
+ if (moduleReferences(module, "controllers", location).some((candidate) => sameClass(candidate, target)))
443
+ roots.push({ ...location, controller: module });
444
+ }
445
+ }
446
+ if (directory === source.root)
447
+ break;
448
+ directory = path.dirname(directory);
449
+ }
450
+ return roots;
451
+ }
452
+ function registeredProviders(controller, source) {
453
+ const pending = routeModules(controller, source);
454
+ const visited = new Set();
455
+ const providers = [];
456
+ while (pending.length) {
457
+ const module = pending.pop();
458
+ if (!module)
459
+ break;
460
+ const identity = `${module.filename}:${module.controller.id.name}`;
461
+ if (visited.has(identity))
462
+ continue;
463
+ visited.add(identity);
464
+ providers.push(...moduleReferences(module.controller, "providers", { ...module, root: source.root }));
465
+ pending.push(...moduleReferences(module.controller, "imports", { ...module, root: source.root }));
466
+ }
467
+ return providers;
468
+ }
469
+ function thisCall(node, name) {
470
+ return node.type === "CallExpression" && node.callee.type === "MemberExpression"
471
+ && node.callee.object.type === "ThisExpression" && memberName(node.callee) === name;
472
+ }
473
+ function handlerEntry(target, root) {
474
+ const own = methodsOf(target.controller);
475
+ const execute = own.find((entry) => keyName(entry.key) === "execute");
476
+ if (execute)
477
+ return execute;
478
+ const base = target.controller.superClass;
479
+ const parent = base?.type === "Identifier" ? delegatedClass(base.name, target.program, target.filename, root) : null;
480
+ if (!isClassFound(parent))
481
+ return null;
482
+ const inherited = methodsOf(parent.controller).find((entry) => keyName(entry.key) === "execute");
483
+ if (!inherited || !propagatesFailures(inherited.value.body))
484
+ return null;
485
+ const bindings = bindingsOf(parent.program);
486
+ const consumesProcess = expandedNodes(inherited.value.body, bindings).some((node) => thisCall(node, "process") && consumedCall(node, inherited.value.body, bindings));
487
+ return consumesProcess && own.find((entry) => keyName(entry.key) === "process");
488
+ }
489
+ function handlerOf(target, query, root) {
490
+ return target.controller.decorators?.some((entry) => {
491
+ const expression = entry.expression;
492
+ if (!importedAs(target.program, "callee" in expression ? nameOf(expression.callee) : undefined, "QueryHandler", "@nestjs/cqrs"))
493
+ return false;
494
+ const name = nameOf("arguments" in expression ? expression.arguments[0] : undefined);
495
+ const handled = name && delegatedClass(name, target.program, target.filename, root);
496
+ return handled && sameClass(handled, query);
497
+ });
498
+ }
499
+ function dispatchedQueries(controller, method, source) {
500
+ const injected = injectedOf(controller);
501
+ const bindings = bindingsOf(source.program);
502
+ return expandedNodes(method.value.body, bindings).flatMap((node) => {
503
+ if (node.type !== "CallExpression")
504
+ return [];
505
+ const callee = unwrap(node.callee);
506
+ if (callee?.type !== "MemberExpression" || memberName(callee) !== "execute")
507
+ return [];
508
+ const owner = callee.object;
509
+ if (owner.type !== "MemberExpression" || owner.object.type !== "ThisExpression")
510
+ return [];
511
+ if (!importedAs(source.program, injected.get(memberName(owner)), "QueryBus", "@nestjs/cqrs"))
512
+ return [];
513
+ if (!consumedCall(node, method.value.body, bindings))
514
+ return [];
515
+ const message = unwrap(node.arguments[0]);
516
+ const target = message?.type === "NewExpression" && delegatedClass(nameOf(message.callee), source.program, source.filename, source.root);
517
+ return target ? [target] : [];
518
+ });
519
+ }
520
+ function busReadiness(controller, method, source, visited) {
521
+ const queries = dispatchedQueries(controller, method, source);
522
+ if (!queries.length)
523
+ return false;
524
+ return registeredProviders(controller, source).some((target) => {
525
+ if (!queries.some((query) => handlerOf(target, query, source.root)))
526
+ return false;
527
+ const entry = handlerEntry(target, source.root);
528
+ return entry && realReadiness(target.controller, entry, target.program, target.filename, source.root, visited);
529
+ });
530
+ }
531
+ function realReadiness(controller, method, program, filename, root, visited = new Set()) {
532
+ const identity = `${filename}:${controller.id.name}:${keyName(method.key)}`;
533
+ if (visited.has(identity))
534
+ return false;
535
+ const next = new Set(visited).add(identity);
536
+ const injected = injectedOf(controller);
537
+ const source = { program, filename, root, controller };
538
+ if (boundedDependency(method, injected, bindingsOf(program), source))
539
+ return true;
540
+ if (!propagatesFailures(method.value.body))
541
+ return false;
542
+ if (busReadiness(controller, method, source, next))
543
+ return true;
544
+ return consumedDependencies(method, injected, source).some(({ call }) => {
545
+ const target = call.type ? delegatedClass(call.type, program, filename, root) : null;
546
+ if (!isClassFound(target))
547
+ return false;
548
+ const delegated = methodsOf(target.controller).find((entry) => keyName(entry.key) === call.method);
549
+ return delegated && realReadiness(target.controller, delegated, target.program, target.filename, root, next);
550
+ });
551
+ }
552
+ /** Readiness delegation is proved through the injected service; the HTTP controller remains a thin door. */
553
+ export const readyReal = {
554
+ meta: {
555
+ type: "problem",
556
+ docs: { description: "BE_READY_REAL: readiness probes an injected required dependency and fails under a bounded timeout." },
557
+ schema: [],
558
+ messages: { real: "BE_READY_REAL: this readiness route must probe an injected required dependency with a failing, bounded timeout; a liveness query or an unconditional success is not readiness." },
559
+ },
560
+ create(context) {
561
+ const hfs = hfsOf(context);
562
+ const filename = context.filename || context.getFilename();
563
+ if (hfs.slotOf(filename) !== "be.transport.http")
564
+ return {};
565
+ return {
566
+ "Program:exit"(program) {
567
+ for (const controller of classesOf(program).values())
568
+ for (const { route, method } of routesOf(controller)) {
569
+ if (!/(?:\/health\/ready|\/readyz)$/.test(route))
570
+ continue;
571
+ if (!realReadiness(controller, method, program, filename, hfs.repoRoot))
572
+ context.report({ node: method, messageId: "real" });
573
+ }
574
+ },
575
+ };
576
+ },
577
+ };
578
+ /** Follow the app's local import closure; unused imports do not install a health transport. */
579
+ function wiringNames(program, wanted) {
580
+ const used = new Set();
581
+ const bindings = bindingsOf(program);
582
+ const collect = (node) => { for (const entry of expandedNodes(node, bindings))
583
+ if (entry.type === "Identifier")
584
+ used.add(entry.name); };
585
+ const moduleObject = (node) => {
586
+ if (node?.type !== "ObjectExpression")
587
+ return;
588
+ for (const property of node.properties)
589
+ if (WIRING_FIELDS.includes(keyName(propertyKey(property))))
590
+ collect(property.type === "Property" ? property.value : undefined);
591
+ };
592
+ for (const controller of classesOf(program).values()) {
593
+ if (wanted?.includes(controller.id.name) === false)
594
+ continue;
595
+ const module = controller.decorators?.find((entry) => decoratorName(entry) === "Module");
596
+ moduleObject(decoratorArguments(module)[0]);
597
+ for (const method of methodsOf(controller).filter((entry) => entry.static))
598
+ walk(method.value.body, (node) => {
599
+ if (node.type === "ReturnStatement" && node.argument?.type === "ObjectExpression" && node.argument.properties.some((entry) => keyName(propertyKey(entry)) === "module"))
600
+ moduleObject(node.argument);
601
+ });
602
+ }
603
+ walk(program, (node) => {
604
+ if (node.type === "VariableDeclarator") {
605
+ const id = nameOf(node.id);
606
+ if (id !== undefined && wanted?.includes(id))
607
+ collect(node.init);
608
+ }
609
+ if (node.type === "FunctionDeclaration") {
610
+ const id = nameOf(node.id);
611
+ if (id !== undefined && wanted?.includes(id))
612
+ collect(node.body);
613
+ }
614
+ if (node.type === "ExportNamedDeclaration" && !node.source)
615
+ for (const specifier of node.specifiers)
616
+ if (!wanted || wanted.includes(keyName(specifier.exported)))
617
+ used.add(keyName(specifier.local));
618
+ });
619
+ return used;
620
+ }
621
+ function importedTargets(program, filename, root, used) {
622
+ const targets = [];
623
+ for (const entry of program.body) {
624
+ if (entry.type !== "ImportDeclaration")
625
+ continue;
626
+ if (entry.importKind === "type" || !entry.specifiers.some((specifier) => used.has(specifier.local.name)))
627
+ continue;
628
+ const target = sourcePath(entry.source.value, filename, root);
629
+ const imported = entry.specifiers.filter((specifier) => used.has(specifier.local.name)).map((specifier) => keyName(importedNode(specifier)) ?? specifier.local.name);
630
+ if (target)
631
+ targets.push({ filename: target, wanted: imported });
632
+ }
633
+ return targets;
634
+ }
635
+ function exportedTargets(program, filename, root, wanted) {
636
+ const targets = [];
637
+ for (const entry of program.body) {
638
+ if (entry.type !== "ExportNamedDeclaration" && entry.type !== "ExportAllDeclaration")
639
+ continue;
640
+ if (!entry.source || entry.exportKind === "type")
641
+ continue;
642
+ const target = sourcePath(entry.source.value, filename, root);
643
+ const exported = entry.type === "ExportAllDeclaration" ? wanted : entry.specifiers.filter((specifier) => !wanted || wanted.includes(keyName(specifier.exported))).map((specifier) => keyName(specifier.local));
644
+ if (target && (!exported || exported.length))
645
+ targets.push({ filename: target, wanted: exported });
646
+ }
647
+ return targets;
648
+ }
649
+ function usedRoutes(program, wanted, used) {
650
+ return [...classesOf(program).values()].filter((controller) => !wanted || wanted.includes(controller.id.name) || used.has(controller.id.name))
651
+ .flatMap((controller) => routesOf(controller).map((entry) => entry.route));
652
+ }
653
+ function appRoutes(filename, root) {
654
+ const routes = new Set();
655
+ const pending = [{ filename, wanted: ["AppModule"] }];
656
+ const visited = new Set();
657
+ while (pending.length) {
658
+ const next = pending.pop();
659
+ if (!next)
660
+ break;
661
+ const { filename: current, wanted } = next;
662
+ const identity = `${current}:${wanted?.join(",") ?? "*"}`;
663
+ if (visited.has(identity))
664
+ continue;
665
+ visited.add(identity);
666
+ const program = readProgram(current);
667
+ if (!program)
668
+ continue;
669
+ const used = wiringNames(program, wanted);
670
+ for (const route of usedRoutes(program, wanted, used))
671
+ routes.add(route);
672
+ pending.push(...importedTargets(program, current, root, used), ...exportedTargets(program, current, root, wanted));
673
+ }
674
+ return routes;
675
+ }
676
+ /** Each declared API composition exposes both process-local liveness and required-dependency readiness. */
677
+ export const healthSignals = {
678
+ meta: {
679
+ type: "problem",
680
+ docs: { description: "BE_HEALTH_SIGNALS: every API app exposes /health/live and /health/ready." },
681
+ schema: [],
682
+ messages: { signals: "BE_HEALTH_SIGNALS: API {{app}} must register both /health/live and /health/ready in its module composition (missing {{missing}})." },
683
+ },
684
+ create(context) {
685
+ const hfs = hfsOf(context);
686
+ const filename = context.filename || context.getFilename();
687
+ if (appRoleOf(hfs, filename)?.entry !== "main.ts")
688
+ return {};
689
+ const app = hfs.apps.find((entry) => entry.name === hfs.classify(filename).bindings?.app);
690
+ if (app?.kind !== "api")
691
+ return {};
692
+ return {
693
+ "Program:exit"(node) {
694
+ const routes = appRoutes(path.join(path.dirname(filename), "app.module.ts"), hfs.repoRoot);
695
+ const missing = ["/health/live", "/health/ready"].filter((route) => !routes.has(route));
696
+ if (missing.length)
697
+ context.report({ node, messageId: "signals", data: { app: app.name, missing: missing.join(", ") } });
698
+ },
699
+ };
700
+ },
701
+ };
702
+ export const rules = { "ready-real": readyReal, "health-signals": healthSignals };
703
+ export const recommended = { "starci-be/ready-real": "error", "starci-be/health-signals": "error" };