@starci/eslint-canon-be 3.5.0 → 3.6.1

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 (198) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +13 -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-view.d.ts +127 -0
  78. package/dist/lib/hfs-view.js +1 -0
  79. package/dist/lib/hfs.d.ts +34 -0
  80. package/{lib/hfs.mjs → dist/lib/hfs.js} +31 -29
  81. package/dist/lib/import-source.d.ts +63 -0
  82. package/dist/lib/import-source.js +134 -0
  83. package/dist/lib/path.d.ts +8 -0
  84. package/{lib/path.mjs → dist/lib/path.js} +4 -7
  85. package/dist/lib/persistence.d.ts +115 -0
  86. package/{lib/persistence.mjs → dist/lib/persistence.js} +55 -66
  87. package/dist/lib/ports.d.ts +70 -0
  88. package/{lib/ports.mjs → dist/lib/ports.js} +62 -66
  89. package/dist/lib/rule.d.ts +31 -0
  90. package/dist/lib/rule.js +2 -0
  91. package/dist/lib/runtime-root.d.ts +4 -0
  92. package/dist/lib/runtime-root.js +10 -0
  93. package/dist/lib/schema-values.d.ts +13 -0
  94. package/{lib/schema-values.mjs → dist/lib/schema-values.js} +67 -59
  95. package/dist/lib/specifier.d.ts +12 -0
  96. package/dist/lib/specifier.js +29 -0
  97. package/dist/lib/subject-values.d.ts +4 -0
  98. package/dist/lib/subject-values.js +61 -0
  99. package/dist/lib/transactions.d.ts +18 -0
  100. package/{lib/transactions.mjs → dist/lib/transactions.js} +17 -15
  101. package/dist/lib/transport-slots.d.ts +17 -0
  102. package/{lib/transport-slots.mjs → dist/lib/transport-slots.js} +2 -4
  103. package/dist/lib/types.d.ts +96 -0
  104. package/dist/lib/types.js +150 -0
  105. package/dist/lib/unit-spec.d.ts +48 -0
  106. package/{lib/unit-spec.mjs → dist/lib/unit-spec.js} +35 -44
  107. package/dist/lib/webhook-ack.d.ts +4 -0
  108. package/{lib/webhook-ack.mjs → dist/lib/webhook-ack.js} +78 -62
  109. package/dist/lib/webhook-handoff-inbox.d.ts +3 -0
  110. package/{lib/webhook-handoff-inbox.mjs → dist/lib/webhook-handoff-inbox.js} +195 -167
  111. package/dist/lib/webhook-handoff-intake.d.ts +4 -0
  112. package/{lib/webhook-handoff-intake.mjs → dist/lib/webhook-handoff-intake.js} +125 -102
  113. package/dist/lib/webhook-handoff.d.ts +15 -0
  114. package/{lib/webhook-handoff.mjs → dist/lib/webhook-handoff.js} +107 -100
  115. package/dist/lib/webhook-verifiers.d.ts +20 -0
  116. package/{lib/webhook-verifiers.mjs → dist/lib/webhook-verifiers.js} +108 -104
  117. package/dist/lib/why.d.ts +9 -0
  118. package/{lib/why.mjs → dist/lib/why.js} +6 -6
  119. package/dist/log-safety.d.ts +20 -0
  120. package/dist/log-safety.js +308 -0
  121. package/dist/module-layering.d.ts +42 -0
  122. package/dist/module-layering.js +257 -0
  123. package/dist/module-shape.d.ts +47 -0
  124. package/{module-shape.mjs → dist/module-shape.js} +278 -236
  125. package/dist/naming.d.ts +49 -0
  126. package/dist/naming.js +246 -0
  127. package/dist/observability.d.ts +25 -0
  128. package/dist/observability.js +245 -0
  129. package/dist/operations.d.ts +23 -0
  130. package/{operations.mjs → dist/operations.js} +410 -332
  131. package/dist/project-graph.d.ts +9 -0
  132. package/{project-graph.mjs → dist/project-graph.js} +8 -13
  133. package/dist/projections.d.ts +11 -0
  134. package/{projections.mjs → dist/projections.js} +60 -57
  135. package/dist/query-safety.d.ts +21 -0
  136. package/{query-safety.mjs → dist/query-safety.js} +92 -108
  137. package/dist/realtime.d.ts +15 -0
  138. package/{realtime.mjs → dist/realtime.js} +108 -106
  139. package/dist/resilience.d.ts +15 -0
  140. package/dist/resilience.js +319 -0
  141. package/dist/schema-authority.d.ts +15 -0
  142. package/{schema-authority.mjs → dist/schema-authority.js} +256 -220
  143. package/dist/service-deps.d.ts +17 -0
  144. package/{service-deps.mjs → dist/service-deps.js} +133 -130
  145. package/dist/service-isolation.d.ts +8 -0
  146. package/dist/service-isolation.js +76 -0
  147. package/dist/size-budget.d.ts +9 -0
  148. package/{size-budget.mjs → dist/size-budget.js} +27 -27
  149. package/dist/sonar-parity.d.ts +5 -0
  150. package/{sonar-parity.mjs → dist/sonar-parity.js} +7 -7
  151. package/dist/spec-no-skip.d.ts +9 -0
  152. package/dist/spec-no-skip.js +81 -0
  153. package/dist/spec-quality.d.ts +10 -0
  154. package/{spec-quality.mjs → dist/spec-quality.js} +103 -87
  155. package/dist/suppression.d.ts +26 -0
  156. package/{suppression.mjs → dist/suppression.js} +30 -45
  157. package/dist/temporal.d.ts +9 -0
  158. package/{temporal.mjs → dist/temporal.js} +75 -65
  159. package/dist/test-world.d.ts +28 -0
  160. package/{test-world.mjs → dist/test-world.js} +102 -83
  161. package/dist/testing.d.ts +51 -0
  162. package/dist/testing.js +368 -0
  163. package/dist/third-party-owner.d.ts +8 -0
  164. package/{third-party-owner.mjs → dist/third-party-owner.js} +105 -91
  165. package/dist/transport.d.ts +24 -0
  166. package/{transport.mjs → dist/transport.js} +279 -240
  167. package/dist/type-safety.d.ts +25 -0
  168. package/dist/type-safety.js +297 -0
  169. package/dist/unit-spec.d.ts +30 -0
  170. package/{unit-spec.mjs → dist/unit-spec.js} +473 -399
  171. package/dist/uploads.d.ts +9 -0
  172. package/{uploads.mjs → dist/uploads.js} +62 -54
  173. package/dist/user-copy.d.ts +9 -0
  174. package/{user-copy.mjs → dist/user-copy.js} +76 -67
  175. package/dist/webhooks.d.ts +16 -0
  176. package/{webhooks.mjs → dist/webhooks.js} +243 -231
  177. package/package.json +23 -8
  178. package/runtime/knowledge/hfs/canon-pins.yaml +18 -11
  179. package/runtime/scripts/hfs/repo-identity.mjs +5 -4
  180. package/async-discipline.mjs +0 -83
  181. package/comments.mjs +0 -416
  182. package/edge-hardening.mjs +0 -139
  183. package/health-ready.mjs +0 -539
  184. package/jwt-alg.mjs +0 -45
  185. package/lib/ast.mjs +0 -88
  186. package/lib/import-source.mjs +0 -104
  187. package/lib/specifier.mjs +0 -27
  188. package/lib/subject-values.mjs +0 -55
  189. package/lib/types.mjs +0 -133
  190. package/log-safety.mjs +0 -303
  191. package/module-layering.mjs +0 -270
  192. package/naming.mjs +0 -251
  193. package/observability.mjs +0 -241
  194. package/resilience.mjs +0 -304
  195. package/service-isolation.mjs +0 -75
  196. package/spec-no-skip.mjs +0 -85
  197. package/testing.mjs +0 -384
  198. package/type-safety.mjs +0 -323
package/resilience.mjs DELETED
@@ -1,304 +0,0 @@
1
- /**
2
- * The rules that keep one slow or malformed dependency from taking a process down.
3
- *
4
- * - `http-needs-timeout` (R70 `BE_HTTP_TIMEOUT`): an outbound HTTP call states how long it may take. A socket
5
- * with no deadline holds a request, a connection and a worker slot for as long as the far side sleeps.
6
- * - `json-parse-needs-guard` (R76 `BE_JSON_PARSE_UNGUARDED`): `JSON.parse` of text that came from outside the
7
- * function sits inside a `try`. A corrupt row or a hostile payload then becomes a typed outcome instead of a 500.
8
- * - `no-hand-rolled-retry` (R81 `BE_HAND_ROLLED_RETRY`): a loop that catches an error and waits before trying
9
- * again re-implements retry by hand, outside `platform/retry`'s bounded, jittered, abortable helper.
10
- *
11
- * A config held in a variable or returned by a helper proves its deadline through its type.
12
- */
13
- import ts from "typescript"
14
- import { keyName, staticText, walk } from "./lib/ast.mjs"
15
- import { hfsOf } from "./lib/hfs.mjs"
16
- import { isOwnedBy } from "./lib/ports.mjs"
17
- import { isPackageType, isTypeNamed, typed } from "./lib/types.mjs"
18
- import { isDeclarationFile } from "./lib/path.mjs"
19
-
20
- const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "request"])
21
-
22
- /** The outbound HTTP client types a call may be made on, by the package that declares each. */
23
- const HTTP_CLIENT_TYPES = Object.freeze([["AxiosInstance", "axios"], ["AxiosStatic", "axios"], ["HttpService", "@nestjs/axios"]])
24
-
25
- /** Whether the node's TYPE is an outbound HTTP client (an axios instance or the Nest `HttpService`), whatever it is called. */
26
- const isHttpClient = (context, node) => HTTP_CLIENT_TYPES.some(([name, pkg]) => isPackageType(context, node, name, pkg))
27
-
28
- const hasSpread = (objectNode) => objectNode.properties.some((property) => property.type === "SpreadElement")
29
-
30
- /** A deadline value cannot be absent in any branch of its type. */
31
- const mayBeAbsent = (type) => type.isUnion()
32
- ? type.types.some(mayBeAbsent)
33
- : (type.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null | ts.TypeFlags.Void)) !== 0
34
-
35
- /** A non-literal config promises a present deadline in every possible branch, including a generic's constraint. */
36
- const typeHasDeadline = (checker, type, atNode, names) => {
37
- if ((type.flags & ts.TypeFlags.TypeParameter) !== 0) {
38
- const constraint = checker.getBaseConstraintOfType(type)
39
- return Boolean(constraint && constraint !== type) && typeHasDeadline(checker, constraint, atNode, names)
40
- }
41
- if (type.isUnion()) return type.types.every((part) => typeHasDeadline(checker, part, atNode, names))
42
- if ((type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) !== 0 || mayBeAbsent(type)) return false
43
- return names.some((name) => {
44
- const property = checker.getPropertyOfType(type, name)
45
- if (!property || (property.flags & ts.SymbolFlags.Optional) !== 0) return false
46
- const valueType = checker.getTypeOfSymbolAtLocation(property, atNode)
47
- return !mayBeAbsent(valueType) && (valueType.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) === 0
48
- })
49
- }
50
-
51
- /** Literal keys state a deadline directly; other configs must prove it with a required, present typed member. */
52
- const hasDeadline = (context, config, names) => {
53
- if (!config) return false
54
- const { checker, toTs } = typed(context)
55
- if (config.type === "ObjectExpression" && !hasSpread(config)) {
56
- return names.some((name) => {
57
- const property = config.properties.findLast((entry) => entry.type === "Property"
58
- && (entry.computed ? staticText(entry.key) : keyName(entry.key)) === name)
59
- if (!property) return false
60
- let expression = property.value
61
- while (["TSAsExpression", "TSTypeAssertion", "TSNonNullExpression", "TSSatisfiesExpression"].includes(expression.type)) expression = expression.expression
62
- const value = toTs(expression)
63
- return Boolean(value) && !mayBeAbsent(checker.getTypeAtLocation(value))
64
- })
65
- }
66
- const configNode = toTs(config)
67
- return Boolean(configNode) && typeHasDeadline(checker, checker.getTypeAtLocation(configNode), configNode, names)
68
- }
69
-
70
- /** Every outbound HTTP call carries a deadline. */
71
- export const httpNeedsTimeout = {
72
- meta: {
73
- type: "problem",
74
- docs: { description: "`fetch`, axios and HttpService calls state a `timeout` or an abort `signal`." },
75
- schema: [],
76
- messages: {
77
- fetchNoSignal:
78
- "`fetch` without a `signal`. A peer that accepts the connection and then goes quiet holds this request for as long as it likes. Pass `{ signal: AbortSignal.timeout(<named ms>) }`.",
79
- clientNoTimeout:
80
- "`{{call}}` states no `timeout` or `signal`. A peer that goes quiet holds this request, its socket and a worker slot indefinitely. Pass `{ timeout: <named ms> }` (or an abort `signal`) in the request config, or set it once on `axios.create({ timeout })`.",
81
- createNoTimeout:
82
- "`axios.create` without a `timeout`. Every call through this instance inherits no deadline. Set `timeout: <named ms>` here.",
83
- },
84
- },
85
- create(context) {
86
- const filename = context.filename || context.getFilename()
87
- if (isDeclarationFile(filename)) return {}
88
- return {
89
- CallExpression(node) {
90
- const { callee } = node
91
- if (callee.type === "Identifier" && callee.name === "fetch") {
92
- const init = node.arguments[1]
93
- if (!hasDeadline(context, init, ["signal"])) context.report({ node, messageId: "fetchNoSignal" })
94
- return
95
- }
96
- if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier") return
97
- const method = callee.property.name
98
- if (!isHttpClient(context, callee.object)) return
99
- const receiver = callee.object.type === "Identifier" ? callee.object.name : "client"
100
- if (method === "create" && isPackageType(context, callee.object, "AxiosStatic", "axios")) {
101
- const config = node.arguments[0]
102
- if (!hasDeadline(context, config, ["timeout", "signal"])) {
103
- context.report({ node, messageId: "createNoTimeout" })
104
- }
105
- return
106
- }
107
- if (!HTTP_METHODS.has(method)) return
108
- const configAt = method === "request" ? 0 : ["post", "put", "patch"].includes(method) ? 2 : 1
109
- const config = node.arguments[configAt]
110
- if (!hasDeadline(context, config, ["timeout", "signal"])) {
111
- context.report({ node, messageId: "clientNoTimeout", data: { call: `${receiver}.${method}` } })
112
- }
113
- },
114
- }
115
- },
116
- }
117
-
118
- /** Whether `node` sits inside a `try` block of its own function. */
119
- const insideTry = (node) => {
120
- let child = node
121
- let current = node.parent
122
- while (current) {
123
- if (current.type === "TryStatement" && current.block === child) return true
124
- if (current.type === "FunctionDeclaration" || current.type === "FunctionExpression" || current.type === "ArrowFunctionExpression") return false
125
- child = current
126
- current = current.parent
127
- }
128
- return false
129
- }
130
-
131
- /** `JSON.parse` of outside text fails inside a guard. */
132
- export const jsonParseNeedsGuard = {
133
- meta: {
134
- type: "problem",
135
- docs: { description: "`JSON.parse` sits inside a `try` in its own function." },
136
- schema: [],
137
- messages: {
138
- unguarded:
139
- "`JSON.parse` outside a `try`. Stored text, a webhook body and a provider reply can all be malformed, and the throw surfaces far from here as an unmasked 500. Wrap it and return a typed outcome (or a `DomainError`) naming what was being parsed.",
140
- },
141
- },
142
- create(context) {
143
- const filename = context.filename || context.getFilename()
144
- if (isDeclarationFile(filename)) return {}
145
- return {
146
- CallExpression(node) {
147
- const { callee } = node
148
- if (callee.type !== "MemberExpression" || callee.computed) return
149
- if (callee.object.type !== "Identifier" || callee.object.name !== "JSON") return
150
- if (callee.property.type !== "Identifier" || callee.property.name !== "parse") return
151
- if (insideTry(node)) return
152
- context.report({ node, messageId: "unguarded" })
153
- },
154
- }
155
- },
156
- }
157
-
158
- /** Modules whose functions wait: `node:timers/promises` `setTimeout` and `scheduler.wait`, and the callback timers. */
159
- const TIMER_MODULES = new Set(["node:timers/promises", "timers/promises", "node:timers", "timers"])
160
- const LOOP_TYPES = ["ForStatement", "WhileStatement", "DoWhileStatement", "ForOfStatement", "ForInStatement"]
161
-
162
- /** The variable a name resolves to from `node`'s scope, or null when it is a global. */
163
- const variableOf = (context, node, name) => {
164
- let scope = (context.sourceCode || context.getSourceCode()).getScope(node)
165
- while (scope) {
166
- const found = scope.set.get(name)
167
- if (found) return found
168
- scope = scope.upper
169
- }
170
- return null
171
- }
172
-
173
- /** Whether an identifier is the global timer function of that name, not a local one. */
174
- const isGlobalTimer = (context, identifier) => identifier.name === "setTimeout" && (variableOf(context, identifier, identifier.name)?.defs.length ?? 0) === 0
175
-
176
- /** Whether an identifier is bound by an import of a timers module (`import { setTimeout as pause } from "node:timers/promises"`). */
177
- const isTimerImport = (context, identifier) =>
178
- variableOf(context, identifier, identifier.name)?.defs.some((def) => def.type === "ImportBinding" && TIMER_MODULES.has(def.parent.source.value)) ?? false
179
-
180
- /** The leftmost identifier of `a.b.c`, else null. */
181
- const rootOf = (node) => {
182
- let current = node
183
- while (current.type === "MemberExpression") current = current.object
184
- return current.type === "Identifier" ? current : null
185
- }
186
-
187
- /** The import a TypeScript identifier resolves to, when it is an import of a timers module. */
188
- const isTimerImportTs = (checker, identifier) => {
189
- const declarations = checker.getSymbolAtLocation(identifier)?.declarations ?? []
190
- return declarations.some((declaration) => {
191
- const importDeclaration = ts.findAncestor(declaration, ts.isImportDeclaration)
192
- return Boolean(importDeclaration) && ts.isStringLiteral(importDeclaration.moduleSpecifier) && TIMER_MODULES.has(importDeclaration.moduleSpecifier.text)
193
- })
194
- }
195
-
196
- /** Whether a TypeScript identifier named `setTimeout` is the ambient timer (declared by a `.d.ts`, or by nothing), not a function of the repository. */
197
- const isGlobalTimerTs = (checker, identifier) =>
198
- (checker.getSymbolAtLocation(identifier)?.declarations ?? []).every((declaration) => declaration.getSourceFile().isDeclarationFile)
199
-
200
- /** The functions a TypeScript declaration is or holds (`function f`, `const f = () => ...`, a method, a property arrow). */
201
- const bodiesOf = (declaration) => {
202
- if (ts.isFunctionLike(declaration) && declaration.body) return [declaration.body]
203
- if ((ts.isVariableDeclaration(declaration) || ts.isPropertyDeclaration(declaration) || ts.isPropertyAssignment(declaration)) && declaration.initializer) {
204
- return ts.isFunctionLike(declaration.initializer) && declaration.initializer.body ? [declaration.initializer.body] : []
205
- }
206
- return []
207
- }
208
-
209
- /**
210
- * Whether calling the function a TypeScript call resolves to WAITS: its body calls the global `setTimeout`, a
211
- * `node:timers` function, or another function that does (followed up to three levels deep). A function declared by
212
- * the `platform/retry` owner is the sanctioned helper and never counts. A function whose body is not in the program
213
- * (a package declaration file) cannot be judged and does not count; the timer-import ban (R90) closes that door.
214
- */
215
- const waitsThrough = (context, checker, call, depth, seen) => {
216
- const hfs = hfsOf(context)
217
- const target = ts.isPropertyAccessExpression(call.expression) ? call.expression.name : call.expression
218
- let symbol = checker.getSymbolAtLocation(target)
219
- if (symbol && (symbol.flags & ts.SymbolFlags.Alias) !== 0) symbol = checker.getAliasedSymbol(symbol)
220
- for (const declaration of symbol?.declarations ?? []) {
221
- if (seen.has(declaration)) continue
222
- seen.add(declaration)
223
- if (isOwnedBy(hfs, declaration.getSourceFile().fileName, "platform", "retry")) continue
224
- for (const body of bodiesOf(declaration)) if (waitsIn(context, checker, body, depth, seen)) return true
225
- }
226
- return false
227
- }
228
-
229
- /** Whether a TypeScript subtree waits: it calls a timer, or a function that waits. */
230
- const waitsIn = (context, checker, root, depth, seen) => {
231
- let found = false
232
- const visit = (node) => {
233
- if (found) return
234
- if (ts.isCallExpression(node)) {
235
- let base = node.expression
236
- while (ts.isPropertyAccessExpression(base)) base = base.expression
237
- if (ts.isIdentifier(base) && ((base.text === "setTimeout" && isGlobalTimerTs(checker, base)) || isTimerImportTs(checker, base))) found = true
238
- else if (depth > 0 && waitsThrough(context, checker, node, depth - 1, seen)) found = true
239
- }
240
- if (!found) ts.forEachChild(node, visit)
241
- }
242
- visit(root)
243
- return found
244
- }
245
-
246
- /** Whether an ESTree call waits: a global or imported timer, or a function declared outside `platform/retry` whose body waits. */
247
- const isWaitCall = (context, node) => {
248
- const { callee } = node
249
- const root = rootOf(callee)
250
- if (root && (isGlobalTimer(context, root) || isTimerImport(context, root))) return true
251
- const { checker, toTs } = typed(context)
252
- const tsCall = toTs(node)
253
- return Boolean(tsCall) && waitsThrough(context, checker, tsCall, 3, new Set())
254
- }
255
-
256
- /** Whether a call catches: a `.catch(...)` on a Promise. */
257
- const isPromiseCatch = (context, node) =>
258
- node.type === "CallExpression" && node.callee.type === "MemberExpression" && !node.callee.computed && node.callee.property.type === "Identifier"
259
- && node.callee.property.name === "catch" && isTypeNamed(context, node.callee.object, "Promise")
260
-
261
- /** A loop that both catches an error and waits is retrying by hand. */
262
- export const noHandRolledRetry = {
263
- meta: {
264
- type: "problem",
265
- docs: { description: "A loop that catches an error and waits before trying again goes through `platform/retry`, not a hand-written loop." },
266
- schema: [],
267
- messages: {
268
- handRolled:
269
- "This loop catches an error and waits before trying again - a hand-rolled retry with no attempt bound visible here, no jitter and no way to honor an abort signal. Retry through `retry(work, { maxAttempts, baseDelayMs, maxDelayMs, signal })` from `platform/retry` (or the queue's declared `attempts`/`backoff`) instead of a loop written at the call site.",
270
- },
271
- },
272
- create(context) {
273
- const filename = context.filename || context.getFilename()
274
- if (isDeclarationFile(filename) || isOwnedBy(hfsOf(context), filename, "platform", "retry")) return {}
275
- const check = (node) => {
276
- let hasCatch = false
277
- walk(node.body, (child) => {
278
- if (child.type === "CatchClause" || isPromiseCatch(context, child)) hasCatch = true
279
- }, { intoFunctions: false })
280
- if (!hasCatch) return
281
- // a wait is often a `new Promise((resolve) => setTimeout(resolve, ms))` executor, so the wait search enters functions
282
- let hasWait = false
283
- walk(node.body, (child) => {
284
- if (!hasWait && child.type === "CallExpression" && isWaitCall(context, child)) hasWait = true
285
- })
286
- if (hasWait) context.report({ node, messageId: "handRolled" })
287
- }
288
- return Object.fromEntries(LOOP_TYPES.map((type) => [type, check]))
289
- },
290
- }
291
-
292
- /** The rules this law contributes to the plugin. */
293
- export const rules = {
294
- "http-needs-timeout": httpNeedsTimeout,
295
- "json-parse-needs-guard": jsonParseNeedsGuard,
296
- "no-hand-rolled-retry": noHandRolledRetry,
297
- }
298
-
299
- /** All three start at error: no baseline exists, and the repositories' fix lanes clear the debt. */
300
- export const recommended = {
301
- "starci-be/http-needs-timeout": "error",
302
- "starci-be/json-parse-needs-guard": "error",
303
- "starci-be/no-hand-rolled-retry": "error",
304
- }
@@ -1,75 +0,0 @@
1
- /**
2
- * The rule that keeps the services of one product apart (catalog R168 `BE_SERVICE_ISOLATION`).
3
- *
4
- * A back-end service is a Nest app at `be/apps/<service>/` of the one repository; services share the `be/src` libraries and talk
5
- * to each other only through the wire (a client of the sibling's API, or the events of its vendored contract under
6
- * `be/contracts/<service>/`). One service importing a file of another service's `apps/<other>/` folder reaches into a sibling's
7
- * composition and options, which makes the two one deployable. The check asks the HFS slot view which app owns a file (the owner of
8
- * an `apps/<app>/src/` slot) for both the importing file and the file the specifier resolves to, through a relative path or the
9
- * program's own `compilerOptions.paths`; it never matches a path by name.
10
- */
11
- import { posix } from "node:path"
12
- import { hfsOf } from "./lib/hfs.mjs"
13
- import { resolveAlias } from "./lib/specifier.mjs"
14
-
15
- /** The app slots: the slot ids of a service app's `apps/<app>/src/` folder. */
16
- const isAppSlot = (slotId) => typeof slotId === "string" && slotId.startsWith("be.app.")
17
-
18
- const isRelative = (specifier) => specifier === "." || specifier === ".." || specifier.startsWith("./") || specifier.startsWith("../")
19
-
20
- /** Calls `check(node, specifier)` for every import and re-export that names a module. */
21
- const onSpecifiers = (check) => ({
22
- ImportExpression(node) {
23
- check(node.source, node.source.value)
24
- },
25
- ImportDeclaration(node) {
26
- check(node.source, node.source.value)
27
- },
28
- ExportNamedDeclaration(node) {
29
- if (node.source) check(node.source, node.source.value)
30
- },
31
- ExportAllDeclaration(node) {
32
- if (node.source) check(node.source, node.source.value)
33
- },
34
- })
35
-
36
- /** A file of one service app imports no file of a sibling service app. */
37
- export const serviceIsolation = {
38
- meta: {
39
- type: "problem",
40
- docs: { description: "A service app (`apps/<service>/`) imports no file of a sibling service app; services share only the `src` libraries and meet through the wire." },
41
- schema: [],
42
- messages: {
43
- sibling:
44
- "`{{specifier}}` reaches into the service app `{{other}}` from `{{self}}`. Services share only the `src` libraries; call the sibling through its API client or consume its events through the vendored contract (`be/contracts/{{other}}/`).",
45
- },
46
- },
47
- create(context) {
48
- const filename = context.filename || context.getFilename()
49
- const hfs = hfsOf(context)
50
- if (!isAppSlot(hfs.slotOf(filename))) return {}
51
- const self = hfs.ownerOf(filename)
52
- if (!self) return {}
53
- return onSpecifiers((node, specifier) => {
54
- if (typeof specifier !== "string") return
55
- const target = isRelative(specifier)
56
- ? posix.normalize(`${posix.dirname(filename.replaceAll("\\", "/"))}/${specifier}`)
57
- : resolveAlias(context, specifier)?.target
58
- if (!target) return
59
- const reached = [`${target}.ts`, `${target}/index.ts`].find((candidate) => isAppSlot(hfs.slotOf(candidate)))
60
- if (!reached) return
61
- const other = hfs.ownerOf(reached)
62
- if (!other || other === self) return
63
- context.report({ node, messageId: "sibling", data: { specifier, self: posix.basename(posix.dirname(self)), other: posix.basename(posix.dirname(other)) } })
64
- })
65
- },
66
- }
67
-
68
- export const rules = {
69
- "service-isolation": serviceIsolation,
70
- }
71
-
72
- /** The level this law asks for: `error`, switched off nowhere. */
73
- export const recommended = {
74
- "starci-be/service-isolation": "error",
75
- }
package/spec-no-skip.mjs DELETED
@@ -1,85 +0,0 @@
1
- /**
2
- * The rule that keeps every back-end spec running (catalog R48 `BE_SPEC_QUALITY`, owner test policy 2026-09-30).
3
- *
4
- * A unit, integration, e2e or contract spec never skips, focuses, marks as todo or picks its own runner: a test that does
5
- * not run is a claim nobody checks. There is no legitimate skip, the contract layer included: a contract spec writes
6
- * `sandbox.describe(...)` from `useSandbox(...)` of `@starci/test-world`, and when the provider sandbox is not configured
7
- * that describe registers one FAILING test naming the missing keys (the body never runs). No file of the repository writes a
8
- * skip: the rule judges every spec AND every file of the test tree (`be.tests.*` slots: world, fixtures, kit), so a
9
- * repo-local helper cannot become a skip path.
10
- *
11
- * Refused in a spec: `it|test|describe` followed by `.skip`, `.skipIf`, `.runIf`, `.todo` or `.only`; `xit`, `xtest`,
12
- * `xdescribe`, `fit`, `ftest`, `fdescribe`; and a runner used as a value (a conditional `(cond ? describe : describe.skip)`,
13
- * `const run = describe`, a computed member), because the choice then hides a skip. `it.each` and `it.concurrent` stay.
14
- * A runner is the test global or the import of `@jest/globals` / `vitest`, judged by its scope binding, never by a name
15
- * alone: a local variable called `it` is not one.
16
- */
17
- import { hfsOf } from "./lib/hfs.mjs"
18
- import { isSpecFile } from "./lib/path.mjs"
19
-
20
- const RUNNERS = new Set(["describe", "it", "test"])
21
- const MARKED = new Set(["xit", "xtest", "xdescribe", "fit", "ftest", "fdescribe"])
22
- const BLOCKING_MEMBERS = new Set(["skip", "skipIf", "runIf", "todo", "only"])
23
- const RUNNER_PACKAGES = new Set(["@jest/globals", "vitest"])
24
-
25
- /** The variable a name resolves to from a scope, or null for an unresolved (global) name. */
26
- const resolve = (scope, name) => {
27
- for (let current = scope; current; current = current.upper) {
28
- const variable = current.set.get(name)
29
- if (variable && variable.defs.length > 0) return variable
30
- }
31
- return null
32
- }
33
-
34
- /** A spec runs every test it declares; the skip lives in the world's contract helper. */
35
- export const specNoSkip = {
36
- meta: {
37
- type: "problem",
38
- docs: { description: "No spec or test-tree file skips, focuses, marks todo or selects its runner conditionally; a contract spec's missing sandbox is a failing test of the test-world library's `sandbox.describe`, never a skip." },
39
- schema: [],
40
- messages: {
41
- skip: "`{{what}}` keeps a test from running. A spec runs every test it declares: delete it or write it. Nothing skips: a contract spec calls `useSandbox(...)` of `@starci/test-world` and writes `sandbox.describe(...)`, which fails naming the missing keys when the sandbox is not configured.",
42
- select: "A test runner (`{{what}}`) is used as a value here, so the spec picks or hides what runs. Call `describe`/`it`/`test` directly; a contract spec writes `sandbox.describe(...)` from `useSandbox(...)` of `@starci/test-world`, which fails naming the missing keys when the sandbox is not configured.",
43
- },
44
- },
45
- create(context) {
46
- const filename = context.filename || context.getFilename()
47
- const slot = hfsOf(context).slotOf(filename)
48
- if (!isSpecFile(filename) && !String(slot ?? "").startsWith("be.tests.")) return {}
49
- const isRunner = (node) => {
50
- const variable = resolve(context.sourceCode.getScope(node), node.name)
51
- if (variable === null) return true
52
- return variable.defs.some((def) => def.type === "ImportBinding" && RUNNER_PACKAGES.has(String(def.parent?.source?.value)))
53
- }
54
- return {
55
- Identifier(node) {
56
- const parent = node.parent
57
- if (parent.type === "TSTypeQuery" || parent.type === "ImportSpecifier" || parent.type === "ExportSpecifier") return
58
- if (parent.type === "MemberExpression" && parent.property === node && !parent.computed) return
59
- if (parent.key === node && !parent.computed && !parent.shorthand) return
60
- const marked = MARKED.has(node.name)
61
- if (!marked && !RUNNERS.has(node.name)) return
62
- if (!isRunner(node)) return
63
- if (marked) return context.report({ node, messageId: "skip", data: { what: node.name } })
64
- if (parent.type === "CallExpression" && parent.callee === node) return
65
- if (parent.type === "MemberExpression" && parent.object === node) {
66
- const member = parent.computed ? (parent.property.type === "Literal" ? String(parent.property.value) : null) : parent.property.name
67
- if (member === null) return context.report({ node: parent, messageId: "select", data: { what: node.name } })
68
- if (BLOCKING_MEMBERS.has(member)) return context.report({ node: parent, messageId: "skip", data: { what: `${node.name}.${member}` } })
69
- return
70
- }
71
- context.report({ node, messageId: "select", data: { what: node.name } })
72
- },
73
- }
74
- },
75
- }
76
-
77
- /** The rules this law contributes to the plugin. */
78
- export const rules = {
79
- "spec-no-skip": specNoSkip,
80
- }
81
-
82
- /** Every rule of this law ships at `error`. */
83
- export const recommended = {
84
- "starci-be/spec-no-skip": "error",
85
- }