@starci/eslint-canon-be 3.24.0 → 3.25.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.25.0 - 2026-11-13
4
+
5
+ - Changed (PROJECT-LINT-3, breaking for an app that relied on the fixed layout): `starciBePackagesConfig` knows no folder of a root package. It judges every script file of `packages/<pkg>/src/**` but the slots the project declares `lint: "fe"` in `ext/manifest.json` `packages` (the package view's `packageLint`); a back-end slot declared before a front-end slot it lies in stays back end. The fixed `src/workbench/**` and `src/public/**` ignores and the `src/workbench/contract/**` block are gone, so an undeclared package is back end whole. Spec `src/packages-config.spec.ts`.
6
+ - Changed: spec fixtures, typed fixtures, rule comments and the README name neutral providers and domains; no rule id, message id or behaviour changes.
7
+ - Changed (R263, `webhook-inbox-key`): the claim of a delivery intake may be the method of a receipt port the app declares in hfs.json `sides.be.receiptPorts` (`{ class, method, repeat, reason }`), besides `claim` and `claimRow` of the platform Inbox. A declared call is held to the same contract: the first await inside the receipt transaction, the transaction's own manager as its first argument, an argument that comes from the delivery (never a literal, never the raw payload), no call inside its arguments (a `const` before it binds what they need), and the declared repeat answer (`false` or `undefined`) returned on in the next statement. The handoff half accepts exactly the declared method inside the receipt transaction; any other method of that class, a lookalike class and an undeclared port stay `handoff` and `key` findings. Spec `src/webhook-handoff-inbox.spec.ts`.
8
+ - Changed (R263, `webhook-inbox-key`): a receipt port declared with `many: true` (`{ class, method, many, reason }`, hfs 6.10.0) is the claim of a delivery that carries several events: the same contract up to the call, its answer (the list of the new events, empty on a repeat) bound to one `const`, and every later statement of the receipt transaction a `for (const event of <that const>)` whose body reads nothing of the intake but its own bindings and the transaction's manager (no raw delivery, no binding made before the claim, no answer list, no `arguments`); `for await`, another iterable, a statement outside the loops, and the single form's repeat test on a many port are `key` findings. Spec `src/webhook-handoff-inbox.spec.ts`.
9
+
3
10
  ## 3.24.0 - 2026-11-13
4
11
 
5
12
  - Changed (PROJECT-LINT-3, R381): `starciBeConfig` and `starciBePackagesConfig` load the lint rules of the project's extension (`ext/manifest.json`, `ext/lint/`) through `extEslintConfigs` of `@starci/hfs` 6.9.0: one block per rule, over the files its `appliesTo` names inside the config (the be side's own folder, `packages/` for the root packages), under the plugin `project-ext`. A refused extension throws `HFS_EXT_INVALID`. Rule packs (hfs.json `rulePacks`) are gone. Requires `@starci/hfs` `~6.9.0`. Spec `src/project-ext.spec.ts`.
package/README.md CHANGED
@@ -91,7 +91,7 @@ For an existing service with another name, declare the exact verification method
91
91
  `<provider>-http.module.ts`:
92
92
 
93
93
  ```ts
94
- export const webhookVerifiers = [BillingService.prototype.receiveCassoWebhook] as const
94
+ export const webhookVerifiers = [BillingService.prototype.receiveGammaPayWebhook] as const
95
95
  ```
96
96
 
97
97
  The declaration names TypeScript method symbols, never strings. Its first unconditional call must finish proof before
@@ -8,7 +8,7 @@
8
8
  *
9
9
  * - `schema-place` (R304) holds the territory. `zod` is imported only from a `<name>.schema.ts` file (or its spec) that sits
10
10
  * in a `domain`, `platform` or `integrations` owner, or from any file of a root workspace package (tier `package`, slots
11
- * `app.packages` and `app.module-registry`), whose node, block and vocabulary contracts are zod schemas; never in a feature
11
+ * `app.packages`), whose node, block and vocabulary contracts are zod schemas; never in a feature
12
12
  * (a transport door answers to `class-validator`), never in a `dto/` folder, and a schema file does not also carry
13
13
  * `class-validator` or a GraphQL type.
14
14
  * - `schema-bounded` (R305) holds the cost. Every string, array, set, map and record a schema builds has an upper bound
@@ -80,7 +80,7 @@ const isEntityManagerInjector = (context, hfs, node) => {
80
80
  };
81
81
  /** Whether a call reaches a value declared by `pkg` under one of `names`, however it was imported. */
82
82
  const callsPackage = (context, node, names, pkg) => typeOrigins(context, node).some((origin) => origin.module === pkg && names.has(origin.name));
83
- /** The constant a declared connection name is exported as: `expert-academy` gives `EXPERT_ACADEMY_CONNECTION`. */
83
+ /** The constant a declared connection name is exported as: `reporting` gives `REPORTING_CONNECTION`. */
84
84
  const constantOf = (name) => `${name.toUpperCase().replace(/-/g, "_")}_CONNECTION`;
85
85
  /** The string an env key argument spells, or null when it is not a plain string. */
86
86
  const keyText = (node) => {
@@ -38,17 +38,18 @@ export declare const buildBeConfig: ({ hfs, plugin, recommended }: {
38
38
  plugin: CanonPlugin | null | undefined;
39
39
  recommended?: Recommended | undefined;
40
40
  }) => Promise<TSESLint.FlatConfig.ConfigArray>;
41
- /** The back-end subpaths of a root workspace package: everything under `src/` but the front-end subpaths `workbench/` and `public/`; the workbench contract (`workbench/contract/`) is React-free and stays back end. */
41
+ /** The back-end files of a root workspace package: every script file under `src/` no slot of the project hands to the front-end canon (`lint: fe`, ext/manifest.json packages). */
42
42
  export declare const PACKAGE_SOURCE_FILES: readonly string[];
43
43
  /** What a package folder never lints: build output, coverage output and installed packages. */
44
44
  export declare const PACKAGE_IGNORED: readonly string[];
45
45
  /**
46
- * The flat config of the back-end subpaths of the root workspace packages of an app: the config of a back end, with the files narrowed to
47
- * `packages/<pkg>/src/**` (the front-end subpaths `workbench/` and `public/` left to the front-end canon, the workbench contract kept). It is
48
- * the very rule set of the be side, over the package view of the app root (`loadPackagesHfs`), so a module package obeys the laws of the side
49
- * its subpath belongs to and the infrastructure owners judge what the package imports.
46
+ * The flat config of the back-end files of the root workspace packages of an app: the config of a back end, with the files narrowed to
47
+ * `packages/<pkg>/src/**`. Which files are the front end's is the project's declaration, never a folder name this canon knows: a slot of
48
+ * `ext/manifest.json` `packages` with `lint: "fe"` is left to the front-end canon, and the first slot that holds a file decides
49
+ * (`hfs.packageLint`, PROJECT-LINT-3), so a back-end slot declared before a front-end slot it lies in stays back end. A package the project
50
+ * does not declare is back end whole. It is the very rule set of the be side, over the package view of the app root (`loadPackagesHfs`).
50
51
  *
51
52
  * @param {object} input - The attachment options of `buildBeConfig`.
52
- * @returns {Promise<Array<object>>} The flat config: one ignore block and the rule and Sonar way blocks over the package subpaths.
53
+ * @returns {Promise<Array<object>>} The flat config: one ignore block and the rule and Sonar way blocks over the package files.
53
54
  */
54
55
  export declare const buildBePackagesConfig: (input: Parameters<typeof buildBeConfig>[0]) => Promise<TSESLint.FlatConfig.ConfigArray>;
@@ -101,32 +101,34 @@ export const buildBeConfig = async ({ hfs, plugin, recommended }) => {
101
101
  { name: TEST_SCOPE_BLOCK, files: [...SPEC_FILES], plugins: { sonarjs }, rules: sonarWayTestRules(sonarjs) },
102
102
  ];
103
103
  };
104
- /** The back-end subpaths of a root workspace package: everything under `src/` but the front-end subpaths `workbench/` and `public/`; the workbench contract (`workbench/contract/`) is React-free and stays back end. */
104
+ /** The back-end files of a root workspace package: every script file under `src/` no slot of the project hands to the front-end canon (`lint: fe`, ext/manifest.json packages). */
105
105
  export const PACKAGE_SOURCE_FILES = Object.freeze(["packages/*/src/**/*.{ts,mts,cts,js,mjs,cjs}"]);
106
106
  const PACKAGE_SPEC_FILES = Object.freeze(["packages/*/src/**/*.{spec,e2e-spec}.{ts,mts,cts,js,mjs,cjs}"]);
107
- const PACKAGE_CONTRACT_SPEC_FILES = Object.freeze(["packages/*/src/workbench/contract/**/*.{spec,e2e-spec}.{ts,mts,cts,js,mjs,cjs}"]);
108
- const PACKAGE_FRONT_END = Object.freeze(["packages/*/src/workbench/**", "packages/*/src/public/**"]);
109
- const PACKAGE_CONTRACT_FILES = Object.freeze(["packages/*/src/workbench/contract/**/*.{ts,mts,cts,js,mjs,cjs}"]);
107
+ const SCRIPT = "**/*.{ts,mts,cts,js,mjs,cjs}";
108
+ const SCRIPT_SPEC = "**/*.{spec,e2e-spec}.{ts,mts,cts,js,mjs,cjs}";
110
109
  /** What a package folder never lints: build output, coverage output and installed packages. */
111
110
  export const PACKAGE_IGNORED = Object.freeze(["**/dist/**", "**/coverage/**", "**/node_modules/**"]);
112
111
  /**
113
- * The flat config of the back-end subpaths of the root workspace packages of an app: the config of a back end, with the files narrowed to
114
- * `packages/<pkg>/src/**` (the front-end subpaths `workbench/` and `public/` left to the front-end canon, the workbench contract kept). It is
115
- * the very rule set of the be side, over the package view of the app root (`loadPackagesHfs`), so a module package obeys the laws of the side
116
- * its subpath belongs to and the infrastructure owners judge what the package imports.
112
+ * The flat config of the back-end files of the root workspace packages of an app: the config of a back end, with the files narrowed to
113
+ * `packages/<pkg>/src/**`. Which files are the front end's is the project's declaration, never a folder name this canon knows: a slot of
114
+ * `ext/manifest.json` `packages` with `lint: "fe"` is left to the front-end canon, and the first slot that holds a file decides
115
+ * (`hfs.packageLint`, PROJECT-LINT-3), so a back-end slot declared before a front-end slot it lies in stays back end. A package the project
116
+ * does not declare is back end whole. It is the very rule set of the be side, over the package view of the app root (`loadPackagesHfs`).
117
117
  *
118
118
  * @param {object} input - The attachment options of `buildBeConfig`.
119
- * @returns {Promise<Array<object>>} The flat config: one ignore block and the rule and Sonar way blocks over the package subpaths.
119
+ * @returns {Promise<Array<object>>} The flat config: one ignore block and the rule and Sonar way blocks over the package files.
120
120
  */
121
121
  export const buildBePackagesConfig = async (input) => {
122
122
  const [, ...blocks] = await buildBeConfig(input);
123
+ const lint = input.hfs?.packageLint ?? { frontEnd: [], fe: [], be: [] };
123
124
  return [
124
125
  { ignores: [...PACKAGE_IGNORED] },
125
126
  ...blocks.flatMap((block) => {
126
127
  const tests = block.name === TEST_SCOPE_BLOCK;
127
128
  return [
128
- { ...block, files: [...(tests ? PACKAGE_SPEC_FILES : PACKAGE_SOURCE_FILES)], ignores: [...(block.ignores ?? []), ...PACKAGE_FRONT_END] },
129
- { ...block, files: [...(tests ? PACKAGE_CONTRACT_SPEC_FILES : PACKAGE_CONTRACT_FILES)] },
129
+ { ...block, files: [...(tests ? PACKAGE_SPEC_FILES : PACKAGE_SOURCE_FILES)], ignores: [...(block.ignores ?? []), ...lint.frontEnd] },
130
+ // A back-end slot declared before a front-end slot that reaches it: its files, less the front-end slots declared before it.
131
+ ...lint.be.map((scope) => ({ ...block, files: [[scope.files, tests ? SCRIPT_SPEC : SCRIPT]], ignores: [...(block.ignores ?? []), ...scope.ignores] })),
130
132
  ];
131
133
  }),
132
134
  ];
@@ -90,6 +90,18 @@ export interface HfsSpecDouble {
90
90
  readonly double: string;
91
91
  readonly forms: readonly string[];
92
92
  }
93
+ /** A declared receipt port (`ruleParams.receiptPorts`): the single form answers a repeat `false` or `undefined`; the many form answers the new events. */
94
+ export type HfsReceiptPort = {
95
+ readonly class: string;
96
+ readonly method: string;
97
+ readonly reason: string;
98
+ } & ({
99
+ readonly repeat: "false" | "undefined";
100
+ readonly many?: undefined;
101
+ } | {
102
+ readonly many: true;
103
+ readonly repeat?: undefined;
104
+ });
93
105
  /** The rule parameters of the be profile (`ruleParams.common` merged with `ruleParams.be`), by the keys the rules read. */
94
106
  export interface HfsRuleParams {
95
107
  readonly functionLines?: number;
@@ -126,6 +138,11 @@ export interface HfsRuleParams {
126
138
  readonly path: string;
127
139
  readonly reason: string;
128
140
  }[];
141
+ /**
142
+ * The receipt ports the app declares (hfs.json `sides.be.receiptPorts`): a class of the app, its method that records a delivery once, and the
143
+ * answer it gives a repeat; or `many: true` for a delivery of several events, whose method answers the list of the new ones (R263).
144
+ */
145
+ readonly receiptPorts?: readonly HfsReceiptPort[];
129
146
  }
130
147
  /** The frozen view of one side of an app. */
131
148
  export interface HfsView {
@@ -154,6 +171,19 @@ export interface HfsView {
154
171
  slot(id: string): HfsSlot | undefined;
155
172
  /** The vocabulary the root package of a file declares in the `starci` key of its manifest (the view of the root packages only), or null outside a package. */
156
173
  readonly packageContract?: (file: string) => HfsPackageContract | null;
174
+ /** What each canon lints of the root packages the project declares slots for (the view of the root packages only). */
175
+ readonly packageLint?: HfsPackageLint;
176
+ }
177
+ /** One lint scope of a declared package: the files of one slot (an app-relative glob), less the globs an earlier slot of the other canon holds. */
178
+ export interface HfsPackageLintScope {
179
+ readonly files: string;
180
+ readonly ignores: readonly string[];
181
+ }
182
+ /** The first-slot-wins partition of the declared packages: every `lint: fe` slot, the front-end scopes, and the back-end slots a later front-end slot reaches. */
183
+ export interface HfsPackageLint {
184
+ readonly frontEnd: readonly string[];
185
+ readonly fe: readonly HfsPackageLintScope[];
186
+ readonly be: readonly HfsPackageLintScope[];
157
187
  }
158
188
  /** A type a root package declares: its name and the app-root relative file that declares it. */
159
189
  export interface HfsPackageDeclaredType {
@@ -9,7 +9,7 @@ export interface InjectionSite {
9
9
  readonly annotation: TSESTree.TypeNode | null;
10
10
  }
11
11
  /**
12
- * PascalCase of a connection name: `expert-academy` gives `ExpertAcademy`.
12
+ * PascalCase of a connection name: `reporting` gives `Reporting`.
13
13
  *
14
14
  * @param {string} name - A kebab-case connection name from `hfs.json`.
15
15
  * @returns {string} The PascalCase form.
@@ -11,7 +11,7 @@ import { typeOrigins } from "./types.js";
11
11
  /** The `typeorm` types a class must never receive except through the platform database capability. */
12
12
  const INFRA_TYPES = new Set(["EntityManager", "DataSource", "QueryRunner"]);
13
13
  /**
14
- * PascalCase of a connection name: `expert-academy` gives `ExpertAcademy`.
14
+ * PascalCase of a connection name: `reporting` gives `Reporting`.
15
15
  *
16
16
  * @param {string} name - A kebab-case connection name from `hfs.json`.
17
17
  * @returns {string} The PascalCase form.
@@ -1,8 +1,18 @@
1
- /** R263 extends inbox dedupe to scalar delivery ids and signed raw-body intakes. */
1
+ /**
2
+ * R263 extends inbox dedupe to scalar delivery ids and signed raw-body intakes. The claim is the platform Inbox's `claim` or `claimRow`, or the
3
+ * method of a receipt port the app declares in hfs.json `sides.be.receiptPorts` (`{ class, method, repeat, reason }`): a class of the app whose
4
+ * method takes the transaction's manager first and answers a repeat exactly as the Inbox does (`false`, or `undefined`). A declared call is held
5
+ * to the same contract: inside the receipt transaction, on that transaction's manager, with an argument that comes from the delivery, before any
6
+ * other work, and followed at once by the return on a repeat. A port declared `many: true` (`{ class, method, many, reason }`) records a delivery
7
+ * of several events and answers the list of the new ones (a repeat answers the empty list): its answer is bound to one `const`, and every later
8
+ * statement of the receipt transaction is a `for (const <name> of <that const>)` whose body reads nothing of the intake but the transaction's
9
+ * manager and the loop's own bindings.
10
+ */
2
11
  import ts from "typescript";
3
12
  import { memberKeyValue, nameOrValue, walk } from "./ast.js";
4
13
  import { hfsOf } from "./hfs.js";
5
14
  import { baseName, inboxClaimOf, ownerNameOf, refusesRepeat } from "./ports.js";
15
+ import { typeOrigins } from "./types.js";
6
16
  import { resolveVariable } from "./transactions.js";
7
17
  import { isPackageType, typed } from "./types.js";
8
18
  import { webhookIntakeProcessesDelivery } from "./webhook-handoff-intake.js";
@@ -129,6 +139,102 @@ const usesKey = (context, argument, key) => {
129
139
  && sameBinding(context, argument.object, key.parameter)
130
140
  && key.properties.some((name) => name === memberKeyValue(argument));
131
141
  };
142
+ /**
143
+ * The repeat answer of a declared receipt port's call (`claim` for `false`, `claimRow` for `undefined`, `many` for the list of new events), or null:
144
+ * a plain member call, without a spread, of a declared method on a receiver whose type is the declared class, declared in the app's own source (a
145
+ * slot owns its file; a class of a package, or a lookalike under another name, is none).
146
+ */
147
+ const receiptPortClaimOf = (context, hfs, call) => {
148
+ const ports = hfs.ruleParams.receiptPorts ?? [];
149
+ if (ports.length === 0 || call?.type !== "CallExpression" || call.optional)
150
+ return null;
151
+ const callee = call.callee;
152
+ if (callee.type !== "MemberExpression" || callee.computed || callee.optional || callee.property.type !== "Identifier")
153
+ return null;
154
+ if (call.arguments.length < 2 || call.arguments.some((argument) => argument.type === "SpreadElement"))
155
+ return null;
156
+ const method = callee.property.name;
157
+ const origins = typeOrigins(context, callee.object).filter((origin) => origin.module === null && hfs.slotOf(origin.file) !== null && hfs.slotOf(origin.file) !== undefined);
158
+ const port = ports.find((entry) => entry.method === method && origins.some((origin) => origin.name === entry.class));
159
+ if (port === undefined)
160
+ return null;
161
+ if (port.many === true)
162
+ return "many";
163
+ return port.repeat === "false" ? "claim" : "claimRow";
164
+ };
165
+ /** A node lies inside another: its range is within the other's. */
166
+ const within = (inner, outer) => inner.range[0] >= outer.range[0] && inner.range[1] <= outer.range[1];
167
+ /**
168
+ * A loop body reads nothing of the intake but the receipt transaction's manager: every identifier it reads (in nested functions too, `arguments`
169
+ * included) binds outside the intake method, inside the loop itself, or to the manager. A non-computed property name reads nothing.
170
+ */
171
+ const readsOnlyLoop = (context, method, loop, manager) => {
172
+ const own = resolveVariable(context.sourceCode, manager);
173
+ let only = true;
174
+ walk(loop.body, (node) => {
175
+ if (node.type !== "Identifier")
176
+ return;
177
+ const parent = node.parent;
178
+ if (parent?.type === "MemberExpression" && parent.property === node && !parent.computed)
179
+ return;
180
+ if (parent?.type === "Property" && parent.key === node && !parent.computed && !parent.shorthand)
181
+ return;
182
+ const variable = resolveVariable(context.sourceCode, node);
183
+ if (variable && variable !== own && within(variable.scope.block, method.value) && !within(variable.scope.block, loop))
184
+ only = false;
185
+ });
186
+ return only;
187
+ };
188
+ /**
189
+ * The effects after a declared `many` call only iterate the new events it answers: the answer is bound by a `const` of one name, and every
190
+ * later statement of the receipt transaction is a plain `for (const <name> of <that const>)` (no `for await`, no other iterable, nothing between
191
+ * or after) whose body reads nothing of the intake but the manager and its own bindings; the raw delivery, the bindings made before the claim and
192
+ * the answer list itself stay out of reach.
193
+ */
194
+ const iteratesOnlyNew = (context, method, awaited, body, manager) => {
195
+ const parent = awaited.parent;
196
+ if (parent.type !== "VariableDeclarator" || parent.id.type !== "Identifier" || parent.init !== awaited)
197
+ return false;
198
+ const declaration = parent.parent;
199
+ const index = body.body.indexOf(declaration);
200
+ if (index === -1 || declaration.kind !== "const" || declaration.declarations.length !== 1)
201
+ return false;
202
+ const answer = parent.id;
203
+ return body.body.slice(index + 1).every((entry) => entry.type === "ForOfStatement" && !entry.await
204
+ && entry.left.type === "VariableDeclaration" && entry.left.kind === "const" && entry.left.declarations.length === 1
205
+ && entry.left.declarations[0]?.id.type === "Identifier"
206
+ && entry.right.type === "Identifier" && sameBinding(context, entry.right, answer)
207
+ && readsOnlyLoop(context, method, entry, manager));
208
+ };
209
+ /** An argument of a declared receipt call comes from the delivery: it reads a parameter of the intake, directly or through `const` bindings; a literal reads nothing. */
210
+ const fromDelivery = (context, method, expression, seen = new Set()) => {
211
+ if (!expression || seen.has(expression))
212
+ return false;
213
+ seen.add(expression);
214
+ let sourced = false;
215
+ walk(expression, (node) => {
216
+ if (node.type !== "Identifier")
217
+ return;
218
+ const variable = resolveVariable(context.sourceCode, node);
219
+ for (const definition of variable?.defs ?? []) {
220
+ if (definition.type === "Parameter" && definition.node === method.value)
221
+ sourced = true;
222
+ if (definition.type === "Variable" && definition.parent.kind === "const" && fromDelivery(context, method, definition.node.init, seen))
223
+ sourced = true;
224
+ }
225
+ }, { intoFunctions: false });
226
+ return sourced;
227
+ };
228
+ /** The arguments of a declared receipt call hold no call, construction or assignment: what they need is bound by a `const` before the claim. */
229
+ const plainArguments = (call) => {
230
+ let plain = true;
231
+ for (const argument of call.arguments)
232
+ walk(argument, (node) => {
233
+ if (["CallExpression", "NewExpression", "AssignmentExpression", "UpdateExpression", "AwaitExpression"].includes(node.type))
234
+ plain = false;
235
+ }, { intoFunctions: false });
236
+ return plain;
237
+ };
132
238
  /** Find the first completed await, without treating a nested helper as work performed here. */
133
239
  const firstAwait = (body) => {
134
240
  let result = null;
@@ -147,12 +253,12 @@ const preservesKey = (context, key, call) => {
147
253
  return variable !== null && !variable.references.some((reference) => reference.isWrite() && !reference.init
148
254
  && reference.identifier.range[0] < call.range[1]);
149
255
  };
150
- /** Scalar/DTO claims are the first statement; a raw intake may first bind its decoded key. */
151
- const claimsBeforeWork = (context, body, statement, key, call) => {
256
+ /** Scalar/DTO claims are the first statement; a raw intake may first bind its decoded key, and a declared receipt call the `const` bindings its arguments read. */
257
+ const claimsBeforeWork = (context, body, statement, key, call, declared = false) => {
152
258
  const index = body.body.findIndex((entry) => entry === statement);
153
259
  if (index === 0)
154
260
  return true;
155
- if (index < 0 || !key.raw)
261
+ if (index < 0 || (!key.raw && !declared))
156
262
  return false;
157
263
  const dependencies = new Set();
158
264
  const read = (expression) => {
@@ -170,7 +276,8 @@ const claimsBeforeWork = (context, body, statement, key, call) => {
170
276
  read(definition.node.init);
171
277
  }, { intoFunctions: false });
172
278
  };
173
- read(call.arguments[1]);
279
+ for (const argument of declared ? call.arguments.slice(1) : [call.arguments[1]])
280
+ read(argument);
174
281
  return body.body.slice(0, index).every((entry) => entry.type === "VariableDeclaration" && entry.kind === "const"
175
282
  && entry.declarations.every((declaration) => declaration.id.type === "Identifier" && dependencies.has(resolveVariable(context.sourceCode, declaration.id))));
176
283
  };
@@ -237,7 +344,7 @@ export const webhookInboxKey = {
237
344
  docs: { description: "Delivery methods with first *Id parameters or DTO properties, or raw-body signature contracts, claim the real Inbox (claim, or claimRow on its EntityInbox) with a stable delivery key before work and return on duplicates. Receipt transactions publish events and leave processing to a reactor/job." },
238
345
  schema: [],
239
346
  messages: {
240
- key: "[BE_WEBHOOK_INBOX_KEY] This delivery intake must first await the real platform/inbox claim(source, deliveryId), or claimRow(source, deliveryId, tx, receipt) on its EntityInbox, using its first *Id parameter or DTO property, or a decoded id for a signed raw-body intake, and return immediately on a repeat (claim answers false, claimRow undefined). A transaction claim uses that callback's own manager; raw payloads and fixed literals are not delivery keys.",
347
+ key: "[BE_WEBHOOK_INBOX_KEY] This delivery intake must first await the real platform/inbox claim(source, deliveryId), or claimRow(source, deliveryId, tx, receipt) on its EntityInbox, using its first *Id parameter or DTO property, or a decoded id for a signed raw-body intake, and return immediately on a repeat (claim answers false, claimRow undefined). A transaction claim uses that callback's own manager; raw payloads and fixed literals are not delivery keys. A receipt port the app declares in hfs.json sides.be.receiptPorts is held to the same contract: awaited first inside the receipt transaction, on that transaction's manager as its first argument, with an argument that comes from the delivery and no call inside its arguments, and its declared repeat answer (false or undefined) returned on at once; a port declared many: true answers the list of the new events, bound to one const, and every later statement of the transaction is a for (const event of <that const>) whose body reads nothing of the delivery.",
241
348
  handoff: "[BE_WEBHOOK_INBOX_KEY] A receipt transaction records the inbox delivery and publishes the typed event. Remove the process callback and domain/command processing from this transaction; a reactor or job processes the delivery after commit.",
242
349
  },
243
350
  },
@@ -275,7 +382,17 @@ export const webhookInboxKey = {
275
382
  && claimsBeforeWork(context, body, statement, key, call)
276
383
  && !priorWork(statement, call)
277
384
  && rejectsDuplicate(context, awaited, body, claimMethod);
278
- if (!claims)
385
+ // A declared receipt port: the same contract, on the transaction's own manager (its first argument), keyed by the delivery.
386
+ const portMethod = claimMethod === null ? receiptPortClaimOf(context, hfs, call) : null;
387
+ const receives = awaited !== null && call?.type === "CallExpression" && portMethod !== null
388
+ && manager !== null && sameBinding(context, call.arguments[0], manager)
389
+ && plainArguments(call)
390
+ && call.arguments.slice(1).some((argument) => argument.type !== "Literal" && fromDelivery(context, method, argument))
391
+ && !(key.raw && call.arguments.slice(1).some((argument) => sameBinding(context, argument, key.parameter)))
392
+ && claimsBeforeWork(context, body, statement, key, call, true)
393
+ && !priorWork(statement, call)
394
+ && (portMethod === "many" ? iteratesOnlyNew(context, method, awaited, body, manager) : rejectsDuplicate(context, awaited, body, portMethod));
395
+ if (!claims && !receives)
279
396
  context.report({ node: method.key, messageId: "key" });
280
397
  },
281
398
  };
@@ -68,6 +68,20 @@ const isReceiptPort = (checker, hfs, type) => {
68
68
  const isInbox = (origin) => origin.module === null && ["Inbox", "EntityInbox"].includes(origin.name) && hfs.tierOf(origin.file) === "platform" && ownerNameOf(hfs, origin.file) === "inbox";
69
69
  return dependencies.every((origins) => origins.length > 0 && origins.every(isPort)) && dependencies.some((origins) => origins.some(isInbox));
70
70
  };
71
+ /**
72
+ * A call of a receipt port the app declares (hfs.json `sides.be.receiptPorts`): the declared method on a receiver whose type is the declared class
73
+ * of the app's own source. Inside the receipt transaction it is the delivery's record itself, as a call on the platform Inbox is; any other
74
+ * method of that class is judged like any other domain call.
75
+ */
76
+ const isDeclaredReceiptCall = (checker, hfs, call) => {
77
+ const ports = hfs.ruleParams.receiptPorts ?? [];
78
+ const callee = call.expression;
79
+ if (ports.length === 0 || !ts.isPropertyAccessExpression(callee))
80
+ return false;
81
+ const method = callee.name.text;
82
+ return hasOrigin(checker, callee.expression, (origin) => origin.module === null && hfs.slotOf(origin.file) !== null && hfs.slotOf(origin.file) !== undefined
83
+ && ports.some((port) => port.class === origin.name && port.method === method));
84
+ };
71
85
  /** The transaction port's package establishes when the callback runs before commit. */
72
86
  const isTransactionCall = (checker, call, receiver) => memberName(call.expression) === "transaction"
73
87
  && hasOrigin(checker, receiver, (origin) => origin.module === "typeorm" && ["EntityManager", "DataSource"].includes(origin.name));
@@ -129,7 +143,7 @@ const processesDelivery = (checker, hfs, body) => {
129
143
  if (isProcessCallback(checker, node))
130
144
  found = true;
131
145
  if (ts.isCallExpression(node)) {
132
- if (inTransaction && isBusinessCall(checker, hfs, node.expression))
146
+ if (inTransaction && isBusinessCall(checker, hfs, node.expression) && !isDeclaredReceiptCall(checker, hfs, node))
133
147
  found = true;
134
148
  const callee = node.expression;
135
149
  if ((ts.isPropertyAccessExpression(callee) || ts.isElementAccessExpression(callee)) && isTransactionCall(checker, node, callee.expression)) {
@@ -34,7 +34,7 @@ const isDomainVerifierType = (context, hfs, receiver) => {
34
34
  };
35
35
  /**
36
36
  * A provider's adjacent HTTP module may export webhookVerifiers as an array of
37
- * domain methods, e.g. [BillingService.prototype.receiveCassoWebhook] as const.
37
+ * domain methods, e.g. [BillingService.prototype.receiveGammaPayWebhook] as const.
38
38
  * Compare symbols, so spelling an arbitrary receiver or alias as a verifier grants nothing.
39
39
  */
40
40
  const declaresMethod = (checker, statement, method) => {
@@ -499,7 +499,7 @@ const isModuleDeclaration = (declaration) => {
499
499
  };
500
500
  /** The array of an `imports` property (the `@Module({ imports })` metadata or a dynamic module literal), else null. */
501
501
  const importsArrayOf = (property) => (!property.computed && keyName(property.key) === "imports" && property.value.type === "ArrayExpression" ? property.value : null);
502
- /** The PascalCase options type name a module file name implies: `sepay-feed-http` gives `SepayFeedHttpOptions`. */
502
+ /** The PascalCase options type name a module file name implies: `acme-pay-feed-http` gives `AcmePayFeedHttpOptions`. */
503
503
  const optionsTypeOf = (name) => `${name.replace(/(?:^|-)(\w)/g, (_, letter) => letter.toUpperCase())}Options`;
504
504
  /**
505
505
  * Every Nest module has a module definition and is registered through it: its
@@ -21,7 +21,7 @@ const isTestComposition = (hfs, file) => {
21
21
  const tier = hfs.tierOf(file);
22
22
  return tier === "e2e" || tier === "fixtures" || inTestWorld(hfs, file);
23
23
  };
24
- /** The word a method name starts with (`recomputeUserXp` gives `recompute`), or null when the name has no camelCase boundary. */
24
+ /** The word a method name starts with (`recomputeUserScore` gives `recompute`), or null when the name has no camelCase boundary. */
25
25
  const verbOf = (name) => {
26
26
  const match = /^[a-z]+/.exec(name);
27
27
  return match && (match[0].length === name.length || /[A-Z]/.test(name.charAt(match[0].length))) ? match[0] : null;
package/dist/testing.js CHANGED
@@ -274,7 +274,7 @@ export const noApiShapedE2eFilename = {
274
274
  },
275
275
  schema: [],
276
276
  messages: {
277
- apiShaped: "`{{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.",
277
+ apiShaped: "`{{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 (`project-purchase.e2e-spec.ts`), not the API surface it happens to hit.",
278
278
  },
279
279
  },
280
280
  create(context) {
@@ -265,9 +265,8 @@ export const explicitHandlerReturnType = {
265
265
  // A rule was written here: two-or-more `is`/`has`-prefixed booleans sharing a type literal with a
266
266
  // field that is optional and not itself boolean. It was measured against the reference backend
267
267
  // before shipping, per this canon's own standard -- and both of its two real firings were wrong.
268
- // `GlobalSearchItem` (`isEnrolled` / `isFree` / `isPremium` beside an unrelated optional
269
- // `parentPath`) and `AdvertisementSeedItem` (`isHouseAd` / `isActive` beside an unrelated optional
270
- // `ctaText`) are both genuinely independent facts about one entity, not a product of states -- the
268
+ // They were a search-result item and a seed item, each with independent `is*` flags beside an
269
+ // unrelated optional field: both genuinely independent facts about one entity, not a product of states -- the
271
270
  // exact "transport type" and "independent booleans" exceptions `type-safety.md` already names. A
272
271
  // rule reporting a defect on 2 of its 2 real firings is not a rule with debt to burn down; it is
273
272
  // wrong, and shipping it at any level would teach a reader to distrust the machine rather than the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.24.0",
3
+ "version": "3.25.0",
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",
@@ -40,7 +40,7 @@
40
40
  "node": ">=22.13.0"
41
41
  },
42
42
  "peerDependencies": {
43
- "@starci/hfs": "~6.9.0",
43
+ "@starci/hfs": "~6.10.0",
44
44
  "eslint": ">=9",
45
45
  "typescript": ">=5.9"
46
46
  },
@@ -74,6 +74,6 @@
74
74
  "typescript": "^6.0.3"
75
75
  },
76
76
  "types": "./dist/index.d.ts",
77
- "gitHead": "85b3f8e7f6c3e4d1e7eb6f0ce3d9e98bf985daf7",
78
- "starciSource": "9ffd3cc5fc4f9b1f8fe749f27e0cadc3d7ae3ef29e8099d5571af387b9b1021e"
77
+ "gitHead": "5ba3e3393ad44562f0245d829949e70a2313af81",
78
+ "starciSource": "6e62b771ca5c89f41d89f7d50a5702e29eff3bcef3ac294388db07e07bd293ca"
79
79
  }