@starci/eslint-canon-be 3.4.42 → 3.4.43

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,8 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.4.43 - 2026-10-26
4
+ - Changed: `inbox-dedupe-required` (R80 `BE_INBOX_DEDUPE_MISSING`) accepts a delivery whose one write transaction hands its work to a typed helper: the sole `.transaction(...)` runs on typeorm's `EntityManager` or on a port the `platform/database` owner declares, its arrow callback returns `this.<method>(..., tx, ...)` of the same class (resolved by the checker), and that async helper claims first with the never-reassigned manager parameter and returns on `false`. The database port also runs the inline claim callback. A helper that never claims, claims after other work or under a condition, claims with another manager, a lookalike runner, a callback that hands work to another object or detaches it, and an ignored claim answer stay refused; every form refused before stays refused.
5
+
3
6
  ## 3.4.42 - 2026-10-26
4
7
  - Changed: `operation-table-schemas` and `operation-contract-decidable` leave alone a stub table a spec keeps to itself, but judge one a spec exports (`export const`, `export { }`, `export default`); `rest-route-declared` never counts a table made in a spec as the app's declared table. The same stub table in a production file stays refused.
5
8
  - Changed: R95 requires named zod input/output schema exports for every `defineOperations` entry (`operation-table-schemas`) and a canon `OperationValidationPolicy` constructed with the same table on the route body (`operation-route-driven-by-table`). Schema provenance and route binding are proved in both editions, including strict empty inputs, aliases, mismatched tables and local imitations.
package/idempotency.mjs CHANGED
@@ -9,8 +9,8 @@
9
9
  * - `inbox-dedupe-required` judges every DELIVERY method of a service. Doors (consumers, `SignedWebhook` controllers) are
10
10
  * thin (R88): they map the delivery and dispatch one message, so the claim lives in the `*.service.ts` the handler calls,
11
11
  * inside its transaction. A delivery method is a public method of a `<name>.service.ts` whose FIRST parameter has an
12
- * `eventId` property, read by the parameter's TYPE. Its first awaited work is the Inbox claim, directly or inside
13
- * the callback of its own EntityManager transaction, with that callback's manager, and the method must return
12
+ * `eventId` property, read by the parameter's TYPE. Its first awaited work is the Inbox claim, directly or as the
13
+ * first work of the one write transaction it runs, with that transaction's manager, and the method must return
14
14
  * early when the claim answers `false`. A lookalike `Inbox` declared by another owner, a renamed receiver and a
15
15
  * property injection are all judged by the receiver's type, so only the real port satisfies the rule; a keyword or a
16
16
  * class name never does.
@@ -20,15 +20,27 @@
20
20
  * if ((await this.inbox.claim(source, id)) === false) { return }
21
21
  * const fresh = await this.inbox.claim(source, id)
22
22
  * if (!fresh) return
23
- * A transaction delivery returns or awaits one transaction as its sole statement. The actual selected inline callback
24
- * claims with its own manager in its first statement, then returns on false; no outer work runs after a duplicate.
25
- * Direct-claim synchronous effects, getters and called helpers stay review questions (the call graph is not read).
23
+ * A transaction delivery returns or awaits one `.transaction(...)` as its sole statement, on a receiver typed as typeorm's
24
+ * `EntityManager` or as a port the `platform/database` owner declares; the callback's one parameter is typed `EntityManager`.
25
+ * Either the actual selected inline async callback claims with that manager in its first statement, then returns on false,
26
+ * or an arrow callback hands its whole work to one `this.<method>(..., tx, ...)` of the same class, resolved by the checker:
27
+ * that async helper receives the manager in a never-reassigned `EntityManager` parameter, prepares only `const` arguments,
28
+ * and its first await is the claim with that parameter at its top level, followed by the return on false:
29
+ * return this.manager.transaction((tx) => this.recordInTransaction(delivery, tx))
30
+ * async recordInTransaction(delivery: Delivery, manager: EntityManager) {
31
+ * const key = keyOf(delivery)
32
+ * if (!(await this.inbox.claim(source, key, manager))) return this.readRepeat(delivery, manager)
33
+ * return this.write(delivery, manager)
34
+ * }
35
+ * No outer work runs after a duplicate. A lookalike runner (a `transaction` method on a type no package or database owner
36
+ * declares), a callback that hands work to another object and a helper reached through a further call are refused.
37
+ * Synchronous effects before a claim, getters and helpers called past the first one stay review questions.
26
38
  */
27
39
  import { hfsOf } from "./lib/hfs.mjs"
28
40
  import { walk } from "./lib/ast.mjs"
29
41
  import { baseName, isOwnedType, ownerNameOf } from "./lib/ports.mjs"
30
42
  import { resolveVariable } from "./lib/transactions.mjs"
31
- import { isPackageType, typed } from "./lib/types.mjs"
43
+ import { isPackageType, typeOrigins, typed } from "./lib/types.mjs"
32
44
  import { mutationIdempotent } from "./lib/client-idempotency.mjs"
33
45
 
34
46
  /** The `Inbox` port of `platform/inbox`. */
@@ -87,8 +99,15 @@ const hasPriorEffect = (expression, call) => {
87
99
  return found
88
100
  }
89
101
 
90
- /** The first awaited claim in the actual callback of a sole, returned or awaited EntityManager transaction. */
91
- const transactionClaim = (context, body) => {
102
+ /** A transaction port the `platform/database` owner declares: a receiver typed by that owner, never by its name. */
103
+ const isDatabasePort = (context, node) => {
104
+ const hfs = hfsOf(context)
105
+ return typeOrigins(context, node).some((origin) =>
106
+ origin.module === null && hfs.tierOf(origin.file) === "platform" && ownerNameOf(hfs, origin.file) === "database")
107
+ }
108
+
109
+ /** The callback a sole, returned or awaited `.transaction(...)` runs on an EntityManager or the database port, and its manager parameter. */
110
+ const soleTransactionCallback = (context, body) => {
92
111
  if (body.body.length !== 1) return null
93
112
  const outer = body.body[0]
94
113
  const expression = outer.type === "ReturnStatement" ? outer.argument
@@ -96,32 +115,100 @@ const transactionClaim = (context, body) => {
96
115
  const call = expression?.type === "AwaitExpression" ? expression.argument : expression
97
116
  const callee = call?.callee
98
117
  if (call?.type !== "CallExpression" || callee.type !== "MemberExpression" || callee.computed
99
- || callee.property.type !== "Identifier" || callee.property.name !== "transaction"
100
- || !isPackageType(context, callee.object, "EntityManager", "typeorm") || hasPriorEffect(call, call)) return null
101
- // TypeORM runs arg0 when it is a function, otherwise arg1. Never accept a later, ignored callback.
102
- const isolation = call.arguments[0]
103
- const callback = call.arguments.length === 1 ? isolation
104
- : call.arguments.length === 2 && isolation.type === "Literal"
105
- && ["READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", "SERIALIZABLE"].includes(isolation.value)
106
- ? call.arguments[1] : null
107
- if (!callback || !["ArrowFunctionExpression", "FunctionExpression"].includes(callback.type)
108
- || !callback.async || callback.body.type !== "BlockStatement" || callback.params.length !== 1) return null
118
+ || callee.property.type !== "Identifier" || callee.property.name !== "transaction" || hasPriorEffect(call, call)) return null
119
+ let callback = null
120
+ if (isPackageType(context, callee.object, "EntityManager", "typeorm")) {
121
+ // TypeORM runs arg0 when it is a function, otherwise arg1. Never accept a later, ignored callback.
122
+ const isolation = call.arguments[0]
123
+ callback = call.arguments.length === 1 ? isolation
124
+ : call.arguments.length === 2 && isolation.type === "Literal"
125
+ && ["READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", "SERIALIZABLE"].includes(isolation.value)
126
+ ? call.arguments[1] : null
127
+ } else if (isDatabasePort(context, callee.object) && call.arguments.length === 1) callback = call.arguments[0]
128
+ if (!callback || !["ArrowFunctionExpression", "FunctionExpression"].includes(callback.type) || callback.params.length !== 1) return null
109
129
  const manager = callback.params[0]
110
130
  if (manager.type !== "Identifier" || !isPackageType(context, manager, "EntityManager", "typeorm")) return null
111
- const awaited = firstAwait(callback.body)
131
+ return { callback, manager }
132
+ }
133
+
134
+ /** True when `argument` is the identifier bound to the parameter `param`; with `unwritten`, that parameter is also never reassigned. */
135
+ const isParameter = (context, argument, param, { unwritten = false } = {}) => {
136
+ const binding = resolveVariable(context.sourceCode, param)
137
+ const argumentBinding = argument?.type === "Identifier" ? resolveVariable(context.sourceCode, argument) : null
138
+ return !!binding && binding.defs[0]?.name === param && argumentBinding === binding
139
+ && !(unwritten && binding.references.some((reference) => reference.isWrite()))
140
+ }
141
+
142
+ /** The statement of a block that holds its first await as the claim it tests, stores or awaits; null when that await sits deeper. */
143
+ const claimStatement = (block) => {
144
+ const awaited = firstAwait(block)
112
145
  const parent = awaited?.parent
113
146
  const statement = parent?.type === "VariableDeclarator" && parent.init === awaited
114
147
  && parent.parent.declarations.length === 1 ? parent.parent
115
148
  : ["UnaryExpression", "BinaryExpression"].includes(parent?.type) ? parent.parent
116
149
  : parent?.type === "ExpressionStatement" ? parent : null
117
- if (statement !== callback.body.body[0] || statement?.parent !== callback.body) return null
118
- const claim = awaited.argument
119
- const argument = claim?.type === "CallExpression" ? claim.arguments[2] : null
120
- const managerBinding = resolveVariable(context.sourceCode, manager)
121
- const argumentBinding = argument?.type === "Identifier" ? resolveVariable(context.sourceCode, argument) : null
122
- if (!managerBinding || managerBinding.defs[0]?.name !== manager || !argumentBinding
123
- || argumentBinding !== managerBinding || hasPriorEffect(statement, claim)) return null
124
- return awaited
150
+ return statement?.parent === block ? { awaited, statement } : null
151
+ }
152
+
153
+ /** The claim that opens the inline async callback with its own manager, as its first statement. */
154
+ const inlineClaim = (context, { callback, manager }) => {
155
+ if (!callback.async || callback.body.type !== "BlockStatement") return null
156
+ const found = claimStatement(callback.body)
157
+ if (!found || found.statement !== callback.body.body[0]) return null
158
+ const claim = found.awaited.argument
159
+ if (claim?.type !== "CallExpression" || !isParameter(context, claim.arguments[2], manager) || hasPriorEffect(found.statement, claim)) return null
160
+ return found.awaited
161
+ }
162
+
163
+ /** The `this.<method>(...)` call an arrow callback hands its whole work to: its expression body, or its sole returned or awaited statement. */
164
+ const handedCall = (callback) => {
165
+ if (callback.type !== "ArrowFunctionExpression") return null
166
+ let expression = callback.body
167
+ if (expression.type === "BlockStatement") {
168
+ const [sole] = expression.body
169
+ if (expression.body.length !== 1) return null
170
+ expression = sole.type === "ReturnStatement" ? sole.argument
171
+ : sole.type === "ExpressionStatement" && sole.expression.type === "AwaitExpression" ? sole.expression : null
172
+ }
173
+ const call = expression?.type === "AwaitExpression" ? expression.argument : expression
174
+ const callee = call?.callee
175
+ return call?.type === "CallExpression" && callee.type === "MemberExpression" && !callee.computed
176
+ && callee.object.type === "ThisExpression" && callee.property.type === "Identifier" ? call : null
177
+ }
178
+
179
+ /**
180
+ * The claim of a typed helper the callback delegates to: a method of the delivery's own class, resolved by the checker, that receives
181
+ * the callback's manager, awaits nothing before the claim, claims with that parameter at its top level and runs no statement but `const`
182
+ * argument preparation before it.
183
+ */
184
+ const delegatedClaim = (context, delivery, { callback, manager }) => {
185
+ const call = handedCall(callback)
186
+ if (!call || hasPriorEffect(call, call)) return null
187
+ const position = call.arguments.findIndex((argument) => argument.type === "Identifier" && argument.name === manager.name)
188
+ if (position < 0 || !isParameter(context, call.arguments[position], manager)) return null
189
+ const { checker, toTs } = typed(context)
190
+ const declarations = checker.getSymbolAtLocation(toTs(call.callee.property))?.getDeclarations?.() ?? []
191
+ const helper = declarations.length === 1
192
+ ? delivery.parent.body.find((member) => member.type === "MethodDefinition" && toTs(member) === declarations[0]) : undefined
193
+ if (!helper || helper === delivery || helper.kind !== "method" || helper.static || !helper.value.async || !helper.value.body) return null
194
+ const param = helper.value.params[position]
195
+ if (param?.type !== "Identifier" || !isPackageType(context, param, "EntityManager", "typeorm")) return null
196
+ const body = helper.value.body
197
+ const found = claimStatement(body)
198
+ if (!found) return null
199
+ const before = body.body.slice(0, body.body.indexOf(found.statement))
200
+ if (before.some((statement) => statement.type !== "VariableDeclaration" || statement.kind !== "const")) return null
201
+ const claim = found.awaited.argument
202
+ if (claim?.type !== "CallExpression" || !isParameter(context, claim.arguments[2], param, { unwritten: true })
203
+ || hasPriorEffect(found.statement, claim)) return null
204
+ return found.awaited
205
+ }
206
+
207
+ /** The first awaited claim of a delivery that runs as one transaction: inline in its callback, or in the typed helper that callback delegates to. */
208
+ const transactionClaim = (context, delivery) => {
209
+ const transaction = soleTransactionCallback(context, delivery.value.body)
210
+ if (!transaction) return null
211
+ return inlineClaim(context, transaction) ?? delegatedClaim(context, delivery, transaction)
125
212
  }
126
213
  /** Whether a parameter's type has an `eventId` property: the shape of a delivery. */
127
214
  const isDeliveryParam = (context, param) => {
@@ -157,7 +244,7 @@ export const inboxDedupeRequired = {
157
244
  if (node.accessibility === "private" || node.accessibility === "protected") return
158
245
  const first = node.value.params[0]
159
246
  if (!first || !isDeliveryParam(context, first)) return
160
- const awaited = transactionClaim(context, node.value.body) ?? firstAwait(node.value.body)
247
+ const awaited = transactionClaim(context, node) ?? firstAwait(node.value.body)
161
248
  const call = awaited?.argument
162
249
  const claims = call?.type === "CallExpression"
163
250
  && call.callee.type === "MemberExpression"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.4.42",
3
+ "version": "3.4.43",
4
4
  "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -30,14 +30,14 @@ pins:
30
30
  source: packages/grammar/package.json
31
31
  why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
32
32
  '@starci/eslint-canon-be':
33
- version: 3.4.42
33
+ version: 3.4.43
34
34
  group: starci
35
35
  install: registry
36
36
  side: be
37
37
  source: packages/eslint/be/package.json
38
38
  why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
39
39
  '@starci/eslint-canon-fe':
40
- version: 8.4.41
40
+ version: 8.4.42
41
41
  group: starci
42
42
  install: registry
43
43
  side: fe
@@ -77,14 +77,14 @@ pins:
77
77
  source: packages/test-world/package.json
78
78
  why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
79
79
  '@starci/cli':
80
- version: 1.7.33
80
+ version: 1.7.34
81
81
  group: starci
82
82
  install: registry
83
83
  side: both
84
84
  source: packages/cli/package.json
85
85
  why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
86
86
  '@starci/hfs':
87
- version: 4.7.33
87
+ version: 4.7.34
88
88
  group: starci
89
89
  install: registry
90
90
  side: both