@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/testing.mjs DELETED
@@ -1,384 +0,0 @@
1
- /**
2
- * The rules that hold `knowledge/patterns/be/test.yaml` (catalog R47 `BE_TEST_TOPOLOGY` and R48 `BE_SPEC_QUALITY`).
3
- *
4
- * MOST OF THAT LAW IS NOT MACHINE-CHECKABLE, and pretending otherwise would be worse than checking nothing. No rule
5
- * can tell whether a file represents a business flow, whether the unhappy path it covers drags a critical flow
6
- * behind it, or whether the decision branches are covered - those are read by a person. What a rule CAN see is a
7
- * shape that is wrong on its face regardless of intent:
8
- *
9
- * - a spec whose every assertion is about a call rather than a result (`no-call-only-spec`);
10
- * - a unit spec of anything but a service, a service with no `<name>.service.spec.ts` beside it, a service spec with no
11
- * service beside it, and a file of a kind the convention bans (`.test.ts`, `.int-spec.ts`, `.harness-spec.ts`)
12
- * (`unit-test-colocated`);
13
- * - an e2e that never reads persisted state back, and an e2e that reaches a model provider
14
- * (`e2e-asserts-persisted-state`, `no-model-call-in-e2e`);
15
- * - an e2e filename that names an API shape instead of a business flow (`no-api-shaped-e2e-filename`);
16
- * - a model stub that returns a bare marker instead of a payload the production parser can parse
17
- * (`no-marker-model-stub`).
18
- *
19
- * Every path question is asked of the slot manifest (`hfsOf(context)`): a rule never tests a path with a regular
20
- * expression. A file name is a role vocabulary of the slots (`*.spec.ts`, `*.e2e-spec.ts`, `*.handler.ts`) and is read
21
- * from the basename. A state read is recognised by the TYPE of the receiver (`EntityManager`, `DataSource`,
22
- * `QueryRunner` of `typeorm`), never by its variable name.
23
- */
24
-
25
- import { statSync } from "node:fs"
26
- import { basename, dirname, join } from "node:path"
27
- import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
28
- import { isPackageType, typeOrigins } from "./lib/types.mjs"
29
- import { doorOfSpec, isUnitSpecFile, unitRoleOfSpec, unitRoleOfSubject } from "./lib/unit-spec.mjs"
30
-
31
- /** The file name of a linted path, in forward-slash form. */
32
- const baseOf = (filename) => basename(String(filename || "").replace(/\\/g, "/"))
33
-
34
- /** Test kind `spec`: a unit spec, `<name>.service.spec.ts` beside its service. */
35
- const isUnitSpec = (filename) => /\.spec\.ts$/.test(baseOf(filename))
36
-
37
- /** Test kind `e2e-spec`: `*.e2e-spec.ts` under `src/tests/e2e/` (`integration-spec` and `contract-spec` are the other two kinds of the tests slots). */
38
- const isE2eSpec = (filename) => /\.e2e-spec\.ts$/.test(baseOf(filename))
39
-
40
- /**
41
- * Matchers that assert a CALL happened rather than what came out of it.
42
- *
43
- * Each is legitimate as a second assertion - "the mail went out" is a real observable effect. The
44
- * rule fires only when a whole file has nothing else.
45
- */
46
- const CALL_MATCHERS = new Set([
47
- "toHaveBeenCalled",
48
- "toHaveBeenCalledWith",
49
- "toHaveBeenCalledTimes",
50
- "toHaveBeenLastCalledWith",
51
- "toHaveBeenNthCalledWith",
52
- "toBeCalled",
53
- "toBeCalledWith",
54
- "toBeCalledTimes",
55
- "toHaveReturned",
56
- ])
57
-
58
- /**
59
- * The matcher a given `expect(...)` call ends in.
60
- *
61
- * Climbs the member chain so modifiers pass through: `expect(x).not.toHaveBeenCalled()` answers
62
- * `toHaveBeenCalled`, and `expect(p).resolves.toBe(1)` answers `toBe`.
63
- */
64
- const matcherOf = (expectCall) => {
65
- let cursor = expectCall
66
- let last = null
67
- while (cursor.parent && cursor.parent.type === "MemberExpression" && cursor.parent.object === cursor) {
68
- last = cursor.parent.property && cursor.parent.property.name
69
- cursor = cursor.parent
70
- }
71
- return last
72
- }
73
-
74
-
75
- // -- TESTING-6 -------------------------------------------------------------------------------------
76
-
77
- /** A spec whose every assertion is about a call restates the source instead of testing it. */
78
- export const noCallOnlySpec = {
79
- meta: {
80
- type: "problem",
81
- docs: { description: "A unit spec asserts a result or a state change, not only that a call happened." },
82
- schema: [],
83
- messages: {
84
- callOnly:
85
- "Every assertion in this spec is `{{matchers}}` - it restates the handler's own source. Rename a collaborator's method and this file goes red; change the business rule to a wrong value and it stays green. Assert what came back, or what changed. A call assertion is legitimate as a SECOND assertion, where the call itself is the observable effect.",
86
- },
87
- },
88
- create(context) {
89
- if (!isUnitSpec(context.filename || context.getFilename())) return {}
90
- let assertions = 0
91
- let callAssertions = 0
92
- const seen = new Set()
93
- return {
94
- CallExpression(node) {
95
- if (!node.callee || node.callee.type !== "Identifier" || node.callee.name !== "expect") return
96
- const matcher = matcherOf(node)
97
- if (matcher === null) return
98
- assertions += 1
99
- if (!CALL_MATCHERS.has(matcher)) return
100
- callAssertions += 1
101
- seen.add(matcher)
102
- },
103
- "Program:exit"(node) {
104
- // the file asserts nothing at all, or asserts something other than a call somewhere
105
- if (assertions === 0 || callAssertions !== assertions) return
106
- context.report({ node, messageId: "callOnly", data: { matchers: [...seen].join(", ") } })
107
- },
108
- }
109
- },
110
- }
111
-
112
-
113
- // -- R47 unit spec topology ------------------------------------------------------------------------
114
-
115
- /** Whether a file exists (a spec is beside its subject on disk, so this is the one question the disk answers). */
116
- const exists = (path) => {
117
- try {
118
- return statSync(path).isFile()
119
- } catch {
120
- return false
121
- }
122
- }
123
-
124
- /** Kinds of test file the convention bans: `.test.ts`, `*.int-spec.ts`, `*.harness-spec.ts` (any spec kind other than `spec`, `e2e-spec`, `integration-spec` and `contract-spec`). */
125
- const BANNED_TEST_FILE = /(?:\.test|\.int-spec|\.harness-spec)\.[cm]?[jt]sx?$/
126
-
127
- /**
128
- * Unit specs are for services only: every `<name>.service.ts` has its `<name>.service.spec.ts` beside it, every unit spec is
129
- * one of those, and there are no kinds of test file beyond `spec`, `e2e-spec`, `integration-spec` and `contract-spec`.
130
- */
131
- export const unitTestColocated = {
132
- meta: {
133
- type: "problem",
134
- docs: { description: "Only the unit-tested roles (`ruleParams.be.unitRoles`: a `<name>.service.ts`, a cli command `<name>.cli.ts` of `src/features/cli`) own a REQUIRED unit spec, each beside it as `<name>.<role>.spec.ts`; any other logic role (`ruleParams.be.logicRoles`: policy, client, guard, mapper, ...) inside a slot whose coverage is required may have one; any other unit spec is a finding, and there are only the spec kinds `spec`, `e2e-spec`, `integration-spec` and `contract-spec`." },
135
- schema: [],
136
- messages: {
137
- suffix: "`{{name}}` is a banned kind of test file. A test is a `<name>.service.spec.ts` unit beside its service, or a `*.e2e-spec.ts`, `*.integration-spec.ts` or `*.contract-spec.ts` under its `src/tests/` folder; there is no `.test.ts`, `.int-spec.ts` or `.harness-spec.ts`.",
138
- notService: "`{{name}}` is a unit spec of something that carries no unit-tested logic here. A unit spec sits beside a `<name>.<role>.ts` of a spec-required role (a service, a cli command of `src/features/cli`) or of a logic role (`ruleParams.be.logicRoles`: policy, client, guard, mapper, ...) inside the logic of `src/modules/**`, where every file owes 100 per file; a feature file (handler, resolver, controller, consumer, processor, step, ...) is thin (BE_FEATURE_THIN) and is proven by the integration and e2e flows, and an entity, module or composition is declaration. Delete this spec and move any business rule it checks into a service, policy or mapper of `src/modules/**`.",
139
- orphan: "`{{name}}` has nothing beside it to test. A unit spec is `<name>.<role>.spec.ts` next to the `<name>.<role>.ts` it tests (a service, or a cli command of `src/features/cli`; the roles are `ruleParams.be.unitRoles`); move it beside its subject, or rename it after the subject it tests.",
140
- missing: "This unit-tested subject has no spec. Add `{{spec}}` beside it: it builds the subject with `Test.createTestingModule`, provides only its constructor dependencies as typed doubles and asserts results or state.",
141
- },
142
- },
143
- create(context) {
144
- const filename = context.filename || context.getFilename()
145
- const name = baseOf(filename)
146
- const hfs = hfsOf(context)
147
- if (/\.d\.[cm]?ts$/.test(name)) return {}
148
- if (BANNED_TEST_FILE.test(name)) {
149
- return { Program(node) { context.report({ node, messageId: "suffix", data: { name } }) } }
150
- }
151
- if (isUnitSpecFile(hfs, filename)) {
152
- const door = doorOfSpec(hfs, filename)
153
- if (door !== null) return exists(join(dirname(filename), door)) ? {} : { Program(node) { context.report({ node, messageId: "orphan", data: { name } }) } }
154
- const role = unitRoleOfSpec(hfs, filename)
155
- if (!role) return { Program(node) { context.report({ node, messageId: "notService", data: { name } }) } }
156
- const subject = `${name.slice(0, -`.${role.spec}.ts`.length)}.${role.role}.ts`
157
- if (exists(join(dirname(filename), subject))) return {}
158
- return { Program(node) { context.report({ node, messageId: "orphan", data: { name } }) } }
159
- }
160
- // a unit-tested subject outside the test tree (ruleParams.be.unitRoles): its spec sits beside it
161
- const role = unitRoleOfSubject(hfs, filename)
162
- if (!role) return {}
163
- const spec = `${name.slice(0, -`.${role.role}.ts`.length)}.${role.spec}.ts`
164
- if (exists(join(dirname(filename), spec))) return {}
165
- return { Program(node) { context.report({ node, messageId: "missing", data: { spec } }) } }
166
- },
167
- }
168
-
169
-
170
- // -- TESTING-2 -------------------------------------------------------------------------------------
171
-
172
- /** The typeorm types a flow reads persisted state through. */
173
- const STATE_TYPES = ["EntityManager", "DataSource", "QueryRunner"]
174
-
175
- /** Whether an expression is a receiver of persisted state, by the TYPE it has and the package that declares it. */
176
- const isStateReader = (context, node) => STATE_TYPES.some((name) => isPackageType(context, node, name, "typeorm"))
177
-
178
- /** The handle `useTestWorld` answers, by where its type is declared: the `@starci/test-world` package or the repository's world slot. */
179
- const isWorldHandle = (context, node) => {
180
- const hfs = hfsOf(context)
181
- return typeOrigins(context, node).some((origin) => origin.name === "TestWorld" && (origin.module === "@starci/test-world" || inTestWorld(hfs, origin.file)))
182
- }
183
-
184
- /** The name a non-computed member access reads, or null. */
185
- const propertyNameOf = (node) => (node.type === "MemberExpression" && !node.computed && node.property.type === "Identifier" ? node.property.name : null)
186
-
187
- /**
188
- * Whether a member expression is the world's own state read: `<world>.db` (its connections are EntityManagers) or
189
- * `<world>.services.<name>.api` (a sibling service's own API). The receiver is judged by its type, not its name.
190
- */
191
- const isWorldStateRead = (context, node) => {
192
- if (propertyNameOf(node) === "db") return isWorldHandle(context, node.object)
193
- if (propertyNameOf(node) !== "api") return false
194
- const service = node.object
195
- const services = service.type === "MemberExpression" ? service.object : null
196
- return Boolean(services) && propertyNameOf(services) === "services" && isWorldHandle(context, services.object)
197
- }
198
-
199
- /** An end-to-end spec that never reads state back proves only that the server replied. */
200
- export const e2eAssertsPersistedState = {
201
- meta: {
202
- type: "problem",
203
- docs: { description: "An e2e spec reads state back rather than asserting only on the response." },
204
- schema: [],
205
- messages: {
206
- noState:
207
- "This e2e never reads any state back - it asserts on responses alone, so the flow can stop persisting and this file stays green. Read the row, the balance or the entitlement out of the database through the `EntityManager` and assert THAT.",
208
- },
209
- },
210
- create(context) {
211
- if (!isE2eSpec(context.filename || context.getFilename())) return {}
212
- let readsState = false
213
- return {
214
- MemberExpression(node) {
215
- if (!readsState && (isStateReader(context, node.object) || isWorldStateRead(context, node))) readsState = true
216
- },
217
- CallExpression(node) {
218
- if (!readsState && node.arguments.some((argument) => argument.type !== "SpreadElement" && isStateReader(context, argument))) readsState = true
219
- },
220
- "Program:exit"(node) {
221
- if (readsState) return
222
- context.report({ node, messageId: "noState" })
223
- },
224
- }
225
- },
226
- }
227
-
228
-
229
- // -- TESTING-9 -------------------------------------------------------------------------------------
230
-
231
- /** Provider SDKs. Importing one into a flow test is a real model call by any other name. */
232
- const PROVIDER_PACKAGES = /^(?:@anthropic-ai\/|openai$|openai\/|ollama$|@google\/generative-ai|@google\/genai|@mistralai\/|cohere-ai)/
233
-
234
- /** An e2e never calls a model; only a contract spec (`src/tests/contract/`, suffix `.contract-spec.ts`) may reach a provider. */
235
- export const noModelCallInE2e = {
236
- meta: {
237
- type: "problem",
238
- docs: { description: "An e2e spec never reaches a model provider." },
239
- schema: [],
240
- messages: {
241
- provider:
242
- "`{{source}}` reaches a model provider from an e2e. A model call costs money, takes seconds and answers differently every time - so this makes the flow suite expensive, slow and flaky at once, and the assertion has to be loosened until it stops catching anything. Point the model integration at the world's network fake (`world.fake.<provider>`) and assert what can actually break: the entitlement, the quota, the persisted answer. Judging the answer itself belongs in a contract spec under `src/tests/contract/<provider>/`.",
243
- },
244
- },
245
- create(context) {
246
- const filename = context.filename || context.getFilename()
247
- if (!isE2eSpec(filename)) return {}
248
- return {
249
- ImportDeclaration(node) {
250
- const source = node.source && node.source.value
251
- if (typeof source !== "string" || !PROVIDER_PACKAGES.test(source)) return
252
- context.report({ node, messageId: "provider", data: { source } })
253
- },
254
- }
255
- },
256
- }
257
-
258
-
259
- // -- TESTING-1 (and E2E-1 in e2e-flow.md, the same requirement on the same file) -------------------
260
-
261
- /** Nouns that name an API shape rather than a business promise. `rewards-queries` is the anchor. */
262
- const API_SHAPED_FILENAME_NOUNS = new Set([
263
- "queries", "query", "mutations", "mutation",
264
- "resolvers", "resolver", "endpoints", "endpoint",
265
- "controllers", "controller", "handlers", "handler",
266
- "modules", "module", "apis", "api",
267
- ])
268
-
269
- /** The hyphen-separated words of an e2e filename, with the lane suffix stripped. */
270
- const e2eFilenameSegments = (filename) => {
271
- const base = baseOf(filename)
272
- return base.replace(/\.e2e-spec\.ts$/, "").split("-").filter(Boolean)
273
- }
274
-
275
- /** An e2e file is one business flow; the filename may not be an API-shape noun wearing its clothes. */
276
- export const noApiShapedE2eFilename = {
277
- meta: {
278
- type: "problem",
279
- docs: {
280
- description:
281
- "An e2e filename reads as a business sentence (TESTING-1; E2E-1 in e2e-flow.md), not a resolver/endpoint/module group.",
282
- },
283
- schema: [],
284
- messages: {
285
- apiShaped:
286
- "`{{segment}}` names an API shape - a resolver group, an endpoint, a module - not a business promise. TESTING-1 / E2E-1: one e2e file is one business flow and the filename IS that flow; `rewards-queries.e2e-spec.ts` is exactly the shape this refuses. Name the file for the sentence it proves (`course-purchase.e2e-spec.ts`), not the API surface it happens to hit.",
287
- },
288
- },
289
- create(context) {
290
- const filename = context.filename || context.getFilename()
291
- if (!isE2eSpec(filename)) return {}
292
- const segments = e2eFilenameSegments(filename)
293
- if (segments.length === 0) return {}
294
- const last = segments[segments.length - 1].toLowerCase()
295
- if (!API_SHAPED_FILENAME_NOUNS.has(last)) return {}
296
- return {
297
- Program(node) {
298
- context.report({ node, messageId: "apiShaped", data: { segment: last } })
299
- },
300
- }
301
- },
302
- }
303
-
304
-
305
- // -- TESTING-7 -------------------------------------------------------------------------------------
306
-
307
- /** Test infrastructure: the fixtures and the test world, where the shared model stub lives (slots `be.tests.fixtures`, `be.tests.world`). */
308
- const isTestInfrastructure = (hfs, filename) => hfs.slotOf(filename) === "be.tests.fixtures" || inTestWorld(hfs, filename)
309
-
310
- /** Bare markers a stub returns when nobody gave it a real answer to stand in for. */
311
- const MARKER_STRINGS = new Set(["stubbed", "stub", "ok", "test", "mock", "fake", "todo", "tbd", "n/a", "pending", ""])
312
-
313
- /** A string literal that is nothing but a marker - not an object, not a `JSON.stringify(...)` call. */
314
- const isMarkerLiteral = (node) => Boolean(
315
- node && node.type === "Literal" && typeof node.value === "string" && MARKER_STRINGS.has(node.value.trim().toLowerCase()),
316
- )
317
-
318
- /** The world's default model stub returns a payload the production parser can actually parse. */
319
- export const noMarkerModelStub = {
320
- meta: {
321
- type: "problem",
322
- docs: {
323
- description: "A model stub in test infra returns a parseable payload (TESTING-7), never a bare marker string.",
324
- },
325
- schema: [],
326
- messages: {
327
- marker:
328
- "This stub resolves to `{{value}}`, a marker rather than an answer. TESTING-7: a stub of a model returns a payload the production parser can actually parse - a marker string means the strict-JSON parser the real flow depends on never runs, so the most fragile seam in the flow is never exercised. Return the shape the production parser expects (an object, or a `JSON.stringify(...)` of one), the way `DEFAULT_MODEL_ANSWER` does.",
329
- },
330
- },
331
- create(context) {
332
- if (!isTestInfrastructure(hfsOf(context), context.filename || context.getFilename())) return {}
333
- return {
334
- CallExpression(node) {
335
- const callee = node.callee
336
- if (!callee || callee.type !== "MemberExpression" || callee.computed) return
337
- const method = callee.property.name
338
- if (method === "mockResolvedValue" || method === "mockReturnValue") {
339
- const argument = node.arguments[0]
340
- if (isMarkerLiteral(argument)) {
341
- context.report({ node: argument, messageId: "marker", data: { value: JSON.stringify(argument.value) } })
342
- }
343
- return
344
- }
345
- if (method !== "mockImplementation") return
346
- const fn = node.arguments[0]
347
- if (!fn || (fn.type !== "ArrowFunctionExpression" && fn.type !== "FunctionExpression")) return
348
- if (fn.body.type !== "BlockStatement") {
349
- if (isMarkerLiteral(fn.body)) {
350
- context.report({ node: fn.body, messageId: "marker", data: { value: JSON.stringify(fn.body.value) } })
351
- }
352
- return
353
- }
354
- for (const statement of fn.body.body) {
355
- if (statement.type === "ReturnStatement" && isMarkerLiteral(statement.argument)) {
356
- context.report({ node: statement.argument, messageId: "marker", data: { value: JSON.stringify(statement.argument.value) } })
357
- }
358
- }
359
- },
360
- }
361
- },
362
- }
363
-
364
- /** The rules this law contributes to the plugin. */
365
-
366
- /** The rules this law contributes to the plugin. */
367
- export const rules = {
368
- "no-call-only-spec": noCallOnlySpec,
369
- "unit-test-colocated": unitTestColocated,
370
- "e2e-asserts-persisted-state": e2eAssertsPersistedState,
371
- "no-model-call-in-e2e": noModelCallInE2e,
372
- "no-api-shaped-e2e-filename": noApiShapedE2eFilename,
373
- "no-marker-model-stub": noMarkerModelStub,
374
- }
375
-
376
- /** Every rule of this law ships at `error`. */
377
- export const recommended = {
378
- "starci-be/no-call-only-spec": "error",
379
- "starci-be/unit-test-colocated": "error",
380
- "starci-be/e2e-asserts-persisted-state": "error",
381
- "starci-be/no-model-call-in-e2e": "error",
382
- "starci-be/no-api-shaped-e2e-filename": "error",
383
- "starci-be/no-marker-model-stub": "error",
384
- }