@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
@@ -0,0 +1,9 @@
1
+ import type { RuleModule } from "./lib/rule.js";
2
+ /** The rules this law contributes to the plugin: one per graph enforcer of this profile. */
3
+ export declare const rules: {
4
+ [k: string]: RuleModule;
5
+ };
6
+ /** Every one at error. */
7
+ export declare const recommended: {
8
+ [k: string]: "error";
9
+ };
@@ -7,20 +7,15 @@
7
7
  * rules and their codes is `LINT_ENFORCERS` of the machine (scripts/hfs/architecture/surface.mjs); `starci app check` keeps the
8
8
  * findings that have no TypeScript file to sit on. A graph that cannot be built stops the run with the machine's message.
9
9
  */
10
- import { LINT_ENFORCERS } from "./runtime/scripts/hfs/architecture/surface.mjs"
11
- import { projectRule } from "./runtime/scripts/hfs/project-rule.mjs"
12
- import { hfsOf } from "./lib/hfs.mjs"
13
- import { dirname, join } from "node:path"
14
- import { fileURLToPath } from "node:url"
15
-
16
- const RUNTIME = join(dirname(fileURLToPath(import.meta.url)), "runtime")
17
- const mine = LINT_ENFORCERS.filter((enforcer) => enforcer.plugins.includes("be"))
18
-
10
+ import { LINT_ENFORCERS } from "../runtime/scripts/hfs/architecture/surface.mjs";
11
+ import { projectRule } from "../runtime/scripts/hfs/project-rule.mjs";
12
+ import { hfsOf } from "./lib/hfs.js";
13
+ import { RUNTIME_ROOT } from "./lib/runtime-root.js";
14
+ const mine = LINT_ENFORCERS.filter((enforcer) => enforcer.plugins.includes("be"));
19
15
  /** The rules this law contributes to the plugin: one per graph enforcer of this profile. */
20
16
  export const rules = Object.fromEntries(mine.map((enforcer) => [
21
17
  enforcer.id,
22
- projectRule({ enforcer, runtimeRoot: RUNTIME, hfsOf }),
23
- ]))
24
-
18
+ projectRule({ enforcer, runtimeRoot: RUNTIME_ROOT, hfsOf }),
19
+ ]));
25
20
  /** Every one at error. */
26
- export const recommended = Object.fromEntries(mine.map((e) => [`starci-be/${e.id}`, "error"]))
21
+ export const recommended = Object.fromEntries(mine.map((e) => [`starci-be/${e.id}`, "error"]));
@@ -0,0 +1,11 @@
1
+ import type { Recommended, RuleModule } from "./lib/rule.js";
2
+ /** Only a projection writes its table, from its own `<name>.projection.ts`. */
3
+ export declare const projectionWriteOwner: RuleModule;
4
+ /** The projection class speaks only `recompute*` and `get*`, never exports its entity, and an api feature never recomputes. */
5
+ export declare const projectionShape: RuleModule;
6
+ export declare const rules: {
7
+ "projection-write-owner": RuleModule;
8
+ "projection-shape": RuleModule;
9
+ };
10
+ /** The level these laws ask for: `error`, switched off nowhere. */
11
+ export declare const recommended: Recommended;
@@ -9,27 +9,23 @@
9
9
  * Entities are found by TYPE ORIGIN; the owner and the kind of a file by the slot view. The vocabulary `recompute` and `get` is the
10
10
  * pattern's own method contract.
11
11
  */
12
- import { writtenEntityOrigins } from "./lib/entity-writes.mjs"
13
- import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
14
- import { baseName } from "./lib/ports.mjs"
15
- import { typed } from "./lib/types.mjs"
16
-
17
- const PROJECTION_SLOT = "be.projections"
18
- const ENTITY_SUFFIX = ".projection-entity.ts"
19
- const PROJECTION_SUFFIX = ".projection.ts"
20
-
12
+ import { writtenEntityOrigins } from "./lib/entity-writes.js";
13
+ import { hfsOf, inTestWorld } from "./lib/hfs.js";
14
+ import { baseName } from "./lib/ports.js";
15
+ import { typed } from "./lib/types.js";
16
+ const PROJECTION_SLOT = "be.projections";
17
+ const ENTITY_SUFFIX = ".projection-entity.ts";
18
+ const PROJECTION_SUFFIX = ".projection.ts";
21
19
  /** True for the test composition, which seeds and inspects tables directly. */
22
20
  const isTestComposition = (hfs, file) => {
23
- const tier = hfs.tierOf(file)
24
- return tier === "e2e" || tier === "fixtures" || inTestWorld(hfs, file)
25
- }
26
-
21
+ const tier = hfs.tierOf(file);
22
+ return tier === "e2e" || tier === "fixtures" || inTestWorld(hfs, file);
23
+ };
27
24
  /** The word a method name starts with (`recomputeUserXp` gives `recompute`), or null when the name has no camelCase boundary. */
28
25
  const verbOf = (name) => {
29
- const match = /^[a-z]+/.exec(name)
30
- return match && (match[0].length === name.length || /[A-Z]/.test(name[match[0].length])) ? match[0] : null
31
- }
32
-
26
+ const match = /^[a-z]+/.exec(name);
27
+ return match && (match[0].length === name.length || /[A-Z]/.test(name.charAt(match[0].length))) ? match[0] : null;
28
+ };
33
29
  /** Only a projection writes its table, from its own `<name>.projection.ts`. */
34
30
  export const projectionWriteOwner = {
35
31
  meta: {
@@ -41,28 +37,29 @@ export const projectionWriteOwner = {
41
37
  },
42
38
  },
43
39
  create(context) {
44
- const hfs = hfsOf(context)
45
- const file = context.filename
46
- if (isTestComposition(hfs, file)) return {}
40
+ const hfs = hfsOf(context);
41
+ const file = context.filename;
42
+ if (isTestComposition(hfs, file))
43
+ return {};
47
44
  return {
48
45
  CallExpression(node) {
49
- const entities = writtenEntityOrigins(context, node).filter((origin) => hfs.slotOf(origin.file) === PROJECTION_SLOT && baseName(origin.file).endsWith(ENTITY_SUFFIX))
50
- if (entities.length === 0) return
51
- const mine = hfs.slotOf(file) === PROJECTION_SLOT && baseName(file).endsWith(PROJECTION_SUFFIX)
52
- if (mine && entities.every((origin) => hfs.ownerOf(origin.file) === hfs.ownerOf(file))) return
53
- context.report({ node, messageId: "foreign", data: { call: context.sourceCode.getText(node.callee) } })
46
+ const entities = writtenEntityOrigins(context, node).filter((origin) => hfs.slotOf(origin.file) === PROJECTION_SLOT && baseName(origin.file).endsWith(ENTITY_SUFFIX));
47
+ if (entities.length === 0)
48
+ return;
49
+ const mine = hfs.slotOf(file) === PROJECTION_SLOT && baseName(file).endsWith(PROJECTION_SUFFIX);
50
+ if (mine && entities.every((origin) => hfs.ownerOf(origin.file) === hfs.ownerOf(file)))
51
+ return;
52
+ context.report({ node, messageId: "foreign", data: { call: context.sourceCode.getText(node.callee) } });
54
53
  },
55
- }
54
+ };
56
55
  },
57
- }
58
-
56
+ };
59
57
  /** The slot of an owner's root file: its kind lives there (`trigger`). */
60
58
  const triggerOfOwner = (hfs, file) => {
61
- const root = hfs.ownerOf(file)
62
- const slot = root ? hfs.slotOf(`${root}/index.ts`) : null
63
- return slot ? (hfs.slot(slot)?.trigger ?? null) : null
64
- }
65
-
59
+ const root = hfs.ownerOf(file);
60
+ const slot = root ? hfs.slotOf(`${root}/index.ts`) : null;
61
+ return slot ? (hfs.slot(slot)?.trigger ?? null) : null;
62
+ };
66
63
  /** The projection class speaks only `recompute*` and `get*`, never exports its entity, and an api feature never recomputes. */
67
64
  export const projectionShape = {
68
65
  meta: {
@@ -76,42 +73,48 @@ export const projectionShape = {
76
73
  },
77
74
  },
78
75
  create(context) {
79
- const hfs = hfsOf(context)
80
- const file = context.filename
81
- const found = hfs.classify(file)
82
- const base = baseName(file)
83
- const inProjection = found.slot === PROJECTION_SLOT
84
- const trigger = triggerOfOwner(hfs, file)
76
+ const hfs = hfsOf(context);
77
+ const file = context.filename;
78
+ const found = hfs.classify(file);
79
+ const base = baseName(file);
80
+ const inProjection = found.slot === PROJECTION_SLOT;
81
+ const trigger = triggerOfOwner(hfs, file);
85
82
  return {
86
83
  MethodDefinition(node) {
87
- if (!inProjection || !base.endsWith(PROJECTION_SUFFIX) || node.kind !== "method" || node.computed || node.key.type !== "Identifier") return
88
- if (node.accessibility === "private" || node.accessibility === "protected" || node.key.type === "PrivateIdentifier") return
89
- const verb = verbOf(node.key.name)
90
- if (verb !== "recompute" && verb !== "get") context.report({ node: node.key, messageId: "vocabulary", data: { name: node.key.name } })
84
+ if (!inProjection || !base.endsWith(PROJECTION_SUFFIX) || node.kind !== "method" || node.computed || node.key.type !== "Identifier")
85
+ return;
86
+ if (node.accessibility === "private" || node.accessibility === "protected")
87
+ return;
88
+ const verb = verbOf(node.key.name);
89
+ if (verb !== "recompute" && verb !== "get")
90
+ context.report({ node: node.key, messageId: "vocabulary", data: { name: node.key.name } });
91
91
  },
92
92
  ExportNamedDeclaration(node) {
93
- if (!inProjection || base !== "index.ts" || !node.source) return
94
- if (String(node.source.value).endsWith(".projection-entity")) context.report({ node, messageId: "entityExported", data: { source: node.source.value } })
93
+ if (!inProjection || base !== "index.ts" || !node.source)
94
+ return;
95
+ if (String(node.source.value).endsWith(".projection-entity"))
96
+ context.report({ node, messageId: "entityExported", data: { source: node.source.value } });
95
97
  },
96
98
  CallExpression(node) {
97
- if (trigger !== "api" || node.callee.type !== "MemberExpression" || node.callee.computed || node.callee.property.type !== "Identifier") return
98
- if (verbOf(node.callee.property.name) !== "recompute") return
99
- const { checker, toTs } = typed(context)
100
- const tsNode = toTs(node)
101
- const declaration = tsNode ? checker.getResolvedSignature(tsNode)?.declaration : undefined
102
- if (declaration && hfs.slotOf(declaration.getSourceFile().fileName) === PROJECTION_SLOT) context.report({ node, messageId: "apiRecompute", data: { call: context.sourceCode.getText(node.callee) } })
99
+ if (trigger !== "api" || node.callee.type !== "MemberExpression" || node.callee.computed || node.callee.property.type !== "Identifier")
100
+ return;
101
+ if (verbOf(node.callee.property.name) !== "recompute")
102
+ return;
103
+ const { checker, toTs } = typed(context);
104
+ const tsNode = toTs(node);
105
+ const declaration = tsNode ? checker.getResolvedSignature(tsNode)?.declaration : undefined;
106
+ if (declaration && hfs.slotOf(declaration.getSourceFile().fileName) === PROJECTION_SLOT)
107
+ context.report({ node, messageId: "apiRecompute", data: { call: context.sourceCode.getText(node.callee) } });
103
108
  },
104
- }
109
+ };
105
110
  },
106
- }
107
-
111
+ };
108
112
  export const rules = {
109
113
  "projection-write-owner": projectionWriteOwner,
110
114
  "projection-shape": projectionShape,
111
- }
112
-
115
+ };
113
116
  /** The level these laws ask for: `error`, switched off nowhere. */
114
117
  export const recommended = {
115
118
  "starci-be/projection-write-owner": "error",
116
119
  "starci-be/projection-shape": "error",
117
- }
120
+ };
@@ -0,0 +1,21 @@
1
+ import type { Recommended, RuleModule } from "./lib/rule.js";
2
+ /** SQL text is `SqlText`, and only a persistence `.sql.ts` builds it. */
3
+ export declare const sqlTextOnly: RuleModule;
4
+ /** There is one way to write a complex read, and it is SQL. */
5
+ export declare const noQueryBuilder: RuleModule;
6
+ /** A statement is text plus parameters; a value never becomes part of the text. */
7
+ export declare const noInterpolatedSql: RuleModule;
8
+ /** A list read states its bound. */
9
+ export declare const queryNeedsLimit: RuleModule;
10
+ /** A read inside an iteration is N+1: one round trip per element. */
11
+ export declare const noQueryInLoop: RuleModule;
12
+ /** The rules this law contributes to the plugin. */
13
+ export declare const rules: {
14
+ "sql-text-only": RuleModule;
15
+ "no-query-builder": RuleModule;
16
+ "no-interpolated-sql": RuleModule;
17
+ "query-needs-limit": RuleModule;
18
+ "no-query-in-loop": RuleModule;
19
+ };
20
+ /** Every rule of this law ships at `error`; no baseline exists. */
21
+ export declare const recommended: Recommended;
@@ -17,31 +17,24 @@
17
17
  *
18
18
  * A migration is hand-written DDL run once by the cli migrate command; its `queryRunner.query(...)` takes plain text.
19
19
  */
20
- import { keyName } from "./lib/ast.mjs"
21
- import { hfsOf } from "./lib/hfs.mjs"
22
- import { baseNameOf, infraTypeOf, isMigrationFile } from "./lib/persistence.mjs"
23
- import { isPackageType, typeOrigins } from "./lib/types.mjs"
24
-
20
+ import { keyName } from "./lib/ast.js";
21
+ import { hfsOf } from "./lib/hfs.js";
22
+ import { baseNameOf, infraTypeOf, isMigrationFile } from "./lib/persistence.js";
23
+ import { isPackageType, typeOrigins } from "./lib/types.js";
25
24
  /** The property a call goes through: `manager.query(...)` gives `query`. */
26
- const calleeProperty = (node) =>
27
- node.callee.type === "MemberExpression" && !node.callee.computed && node.callee.property.type === "Identifier"
28
- ? node.callee.property.name
29
- : null
30
-
25
+ const calleeProperty = (node) => node.callee.type === "MemberExpression" && !node.callee.computed && node.callee.property.type === "Identifier"
26
+ ? node.callee.property.name
27
+ : null;
31
28
  /** Whether a type origin is declared by the platform database capability (where `SqlText`, `SqlIdent` and `sql` live). */
32
29
  const fromDatabaseCapability = (hfs, origin) => {
33
- const found = hfs.classify(origin.file)
34
- return found.slot === "be.platform" && found.bindings?.capability === "database"
35
- }
36
-
30
+ const found = hfs.classify(origin.file);
31
+ return found.slot === "be.platform" && found.bindings?.capability === "database";
32
+ };
37
33
  /** Whether the value at `node` has the branded type `name` exported by the platform database capability. */
38
- const hasBrand = (context, hfs, node, name) => typeOrigins(context, node).some((origin) => origin.name === name && fromDatabaseCapability(hfs, origin))
39
-
34
+ const hasBrand = (context, hfs, node, name) => typeOrigins(context, node).some((origin) => origin.name === name && fromDatabaseCapability(hfs, origin));
40
35
  /** Whether a call goes through `.query` on a manager, runner or data source. */
41
- const isQueryCall = (context, node) => calleeProperty(node) === "query" && infraTypeOf(context, node.callee.object) !== null
42
-
36
+ const isQueryCall = (context, node) => calleeProperty(node) === "query" && node.callee.type === "MemberExpression" && infraTypeOf(context, node.callee.object) !== null;
43
37
  // -- R36 -----------------------------------------------------------------------------------------------
44
-
45
38
  /** SQL text is `SqlText`, and only a persistence `.sql.ts` builds it. */
46
39
  export const sqlTextOnly = {
47
40
  meta: {
@@ -49,32 +42,33 @@ export const sqlTextOnly = {
49
42
  docs: { description: "`.query(...)` takes a `SqlText`, and the `sql` tag is called only in a persistence `<name>.sql.ts`." },
50
43
  schema: [],
51
44
  messages: {
52
- notSqlText:
53
- "The first argument of `.query(...)` is not a `SqlText`. SQL text is a constant built with the `sql` tag in the `persistence/<name>.sql.ts` of the owning capability and imported here; the row shape and its mapper live in `<name>.rows.ts`.",
54
- tagOutsideSqlFile:
55
- "The `sql` tag is called outside a persistence `<name>.sql.ts`. Write the statement as an exported constant in the `persistence/<name>.sql.ts` of the capability that owns the tables, and import it.",
45
+ notSqlText: "The first argument of `.query(...)` is not a `SqlText`. SQL text is a constant built with the `sql` tag in the `persistence/<name>.sql.ts` of the owning capability and imported here; the row shape and its mapper live in `<name>.rows.ts`.",
46
+ tagOutsideSqlFile: "The `sql` tag is called outside a persistence `<name>.sql.ts`. Write the statement as an exported constant in the `persistence/<name>.sql.ts` of the capability that owns the tables, and import it.",
56
47
  },
57
48
  },
58
49
  create(context) {
59
- const hfs = hfsOf(context)
60
- const filename = context.filename || context.getFilename()
61
- const migration = isMigrationFile(hfs, filename)
62
- const sqlFile = hfs.slotOf(filename) === "be.persistence" && baseNameOf(filename).endsWith(".sql.ts")
63
- const isSqlTag = (node) => typeOrigins(context, node).some((origin) => origin.name === "sql" && fromDatabaseCapability(hfs, origin))
50
+ const hfs = hfsOf(context);
51
+ const filename = context.filename || context.getFilename();
52
+ const migration = isMigrationFile(hfs, filename);
53
+ const sqlFile = hfs.slotOf(filename) === "be.persistence" && baseNameOf(filename).endsWith(".sql.ts");
54
+ const isSqlTag = (node) => typeOrigins(context, node).some((origin) => origin.name === "sql" && fromDatabaseCapability(hfs, origin));
64
55
  return {
65
56
  CallExpression(node) {
66
- if (isSqlTag(node.callee) && !sqlFile) context.report({ node, messageId: "tagOutsideSqlFile" })
67
- if (migration || !isQueryCall(context, node)) return
68
- const first = node.arguments[0]
69
- if (!first || !hasBrand(context, hfs, first, "SqlText")) context.report({ node: first ?? node, messageId: "notSqlText" })
57
+ if (isSqlTag(node.callee) && !sqlFile)
58
+ context.report({ node, messageId: "tagOutsideSqlFile" });
59
+ if (migration || !isQueryCall(context, node))
60
+ return;
61
+ const first = node.arguments[0];
62
+ if (!first || !hasBrand(context, hfs, first, "SqlText"))
63
+ context.report({ node: first ?? node, messageId: "notSqlText" });
70
64
  },
71
65
  TaggedTemplateExpression(node) {
72
- if (isSqlTag(node.tag) && !sqlFile) context.report({ node, messageId: "tagOutsideSqlFile" })
66
+ if (isSqlTag(node.tag) && !sqlFile)
67
+ context.report({ node, messageId: "tagOutsideSqlFile" });
73
68
  },
74
- }
69
+ };
75
70
  },
76
- }
77
-
71
+ };
78
72
  /** There is one way to write a complex read, and it is SQL. */
79
73
  export const noQueryBuilder = {
80
74
  meta: {
@@ -82,23 +76,21 @@ export const noQueryBuilder = {
82
76
  docs: { description: "No `createQueryBuilder(...)` call." },
83
77
  schema: [],
84
78
  messages: {
85
- builder:
86
- "`createQueryBuilder(...)` is banned. A read is `manager.find(Entity, { where, take })`, or a `SqlText` constant in the capability's `persistence/<name>.sql.ts` run with `manager.query(...)`.",
79
+ builder: "`createQueryBuilder(...)` is banned. A read is `manager.find(Entity, { where, take })`, or a `SqlText` constant in the capability's `persistence/<name>.sql.ts` run with `manager.query(...)`.",
87
80
  },
88
81
  },
89
82
  create(context) {
90
83
  return {
91
84
  CallExpression(node) {
92
- const callee = node.callee
93
- const name = callee.type === "Identifier" ? callee.name : calleeProperty(node)
94
- if (name === "createQueryBuilder") context.report({ node, messageId: "builder" })
85
+ const callee = node.callee;
86
+ const name = callee.type === "Identifier" ? callee.name : calleeProperty(node);
87
+ if (name === "createQueryBuilder")
88
+ context.report({ node, messageId: "builder" });
95
89
  },
96
- }
90
+ };
97
91
  },
98
- }
99
-
92
+ };
100
93
  // -- R68 -----------------------------------------------------------------------------------------------
101
-
102
94
  /** A statement is text plus parameters; a value never becomes part of the text. */
103
95
  export const noInterpolatedSql = {
104
96
  meta: {
@@ -106,40 +98,39 @@ export const noInterpolatedSql = {
106
98
  docs: { description: "Inside the `sql` tag every substitution is a `SqlIdent`; a `.query(...)` string is never built by template or concatenation." },
107
99
  schema: [],
108
100
  messages: {
109
- substitution:
110
- "This substitution (`{{expression}}`) is not a `SqlIdent`. A value spliced into a statement is an injection hole and defeats the plan cache. Pass a value as a numbered parameter (`$1`) in the array argument; a dynamic identifier goes through `ident(name, allowed)`, which checks it against a fixed list and is the only substitution the `sql` tag accepts.",
111
- built:
112
- "This SQL text is built with a template or a `+`. A value spliced into a statement is an injection hole. Write the statement as a `SqlText` constant with the `sql` tag in `persistence/<name>.sql.ts` and pass values as numbered parameters (`$1`) in the array argument.",
101
+ substitution: "This substitution (`{{expression}}`) is not a `SqlIdent`. A value spliced into a statement is an injection hole and defeats the plan cache. Pass a value as a numbered parameter (`$1`) in the array argument; a dynamic identifier goes through `ident(name, allowed)`, which checks it against a fixed list and is the only substitution the `sql` tag accepts.",
102
+ built: "This SQL text is built with a template or a `+`. A value spliced into a statement is an injection hole. Write the statement as a `SqlText` constant with the `sql` tag in `persistence/<name>.sql.ts` and pass values as numbered parameters (`$1`) in the array argument.",
113
103
  },
114
104
  },
115
105
  create(context) {
116
- const hfs = hfsOf(context)
117
- const sourceCode = context.sourceCode || context.getSourceCode()
118
- const filename = context.filename || context.getFilename()
119
- const migration = isMigrationFile(hfs, filename)
106
+ const hfs = hfsOf(context);
107
+ const sourceCode = context.sourceCode || context.getSourceCode();
108
+ const filename = context.filename || context.getFilename();
109
+ const migration = isMigrationFile(hfs, filename);
120
110
  return {
121
111
  TaggedTemplateExpression(node) {
122
- if (!typeOrigins(context, node.tag).some((origin) => origin.name === "sql" && fromDatabaseCapability(hfs, origin))) return
112
+ if (!typeOrigins(context, node.tag).some((origin) => origin.name === "sql" && fromDatabaseCapability(hfs, origin)))
113
+ return;
123
114
  for (const expression of node.quasi.expressions) {
124
115
  if (!hasBrand(context, hfs, expression, "SqlIdent")) {
125
- context.report({ node: expression, messageId: "substitution", data: { expression: sourceCode.getText(expression).slice(0, 60) } })
116
+ context.report({ node: expression, messageId: "substitution", data: { expression: sourceCode.getText(expression).slice(0, 60) } });
126
117
  }
127
118
  }
128
119
  },
129
120
  CallExpression(node) {
130
- if (migration || !isQueryCall(context, node)) return
131
- const first = node.arguments[0]
132
- if (first?.type === "TemplateLiteral" && first.expressions.length > 0) context.report({ node: first, messageId: "built" })
133
- else if (first?.type === "BinaryExpression" && first.operator === "+") context.report({ node: first, messageId: "built" })
121
+ if (migration || !isQueryCall(context, node))
122
+ return;
123
+ const first = node.arguments[0];
124
+ if (first?.type === "TemplateLiteral" && first.expressions.length > 0)
125
+ context.report({ node: first, messageId: "built" });
126
+ else if (first?.type === "BinaryExpression" && first.operator === "+")
127
+ context.report({ node: first, messageId: "built" });
134
128
  },
135
- }
129
+ };
136
130
  },
137
- }
138
-
131
+ };
139
132
  // -- R69 -----------------------------------------------------------------------------------------------
140
-
141
- const BOUNDED_READS = new Set(["find", "findBy", "findAndCount", "findAndCountBy"])
142
-
133
+ const BOUNDED_READS = new Set(["find", "findBy", "findAndCount", "findAndCountBy"]);
143
134
  /** A list read states its bound. */
144
135
  export const queryNeedsLimit = {
145
136
  meta: {
@@ -147,58 +138,52 @@ export const queryNeedsLimit = {
147
138
  docs: { description: "`find`, `findBy` and `findAndCount` on an `EntityManager` state `take`." },
148
139
  schema: [],
149
140
  messages: {
150
- find:
151
- "`.{{method}}(...)` reads every matching row and states no `take` in its options object. Pass `take` with a named bound (`manager.find(Entity, { where, take: LIST_ROWS_MAX })`), or page by keyset.",
152
- findBy:
153
- "`.{{method}}(...)` cannot take a bound, so it reads every matching row. Use `manager.find(Entity, { where, take })` with a named bound, or page by keyset.",
141
+ find: "`.{{method}}(...)` reads every matching row and states no `take` in its options object. Pass `take` with a named bound (`manager.find(Entity, { where, take: LIST_ROWS_MAX })`), or page by keyset.",
142
+ findBy: "`.{{method}}(...)` cannot take a bound, so it reads every matching row. Use `manager.find(Entity, { where, take })` with a named bound, or page by keyset.",
154
143
  },
155
144
  },
156
145
  create(context) {
157
146
  return {
158
147
  CallExpression(node) {
159
- const method = calleeProperty(node)
160
- if (!method || !BOUNDED_READS.has(method) || !isPackageType(context, node.callee.object, "EntityManager", "typeorm")) return
148
+ const method = calleeProperty(node);
149
+ if (!method || !BOUNDED_READS.has(method) || node.callee.type !== "MemberExpression" || !isPackageType(context, node.callee.object, "EntityManager", "typeorm"))
150
+ return;
161
151
  if (method === "findBy" || method === "findAndCountBy") {
162
- context.report({ node: node.callee.property, messageId: "findBy", data: { method } })
163
- return
152
+ context.report({ node: node.callee.property, messageId: "findBy", data: { method } });
153
+ return;
164
154
  }
165
- const options = node.arguments[node.arguments.length - 1]
166
- const hasTake =
167
- options?.type === "ObjectExpression"
168
- && options.properties.some((property) => property.type === "Property" && keyName(property.key) === "take")
169
- if (!hasTake) context.report({ node: node.callee.property, messageId: "find", data: { method } })
155
+ const options = node.arguments[node.arguments.length - 1];
156
+ const hasTake = options?.type === "ObjectExpression"
157
+ && options.properties.some((property) => property.type === "Property" && keyName(property.key) === "take");
158
+ if (!hasTake)
159
+ context.report({ node: node.callee.property, messageId: "find", data: { method } });
170
160
  },
171
- }
161
+ };
172
162
  },
173
- }
174
-
163
+ };
175
164
  // -- R77 -----------------------------------------------------------------------------------------------
176
-
177
- const LOOP_READS = new Set(["find", "findBy", "findOne", "findOneBy", "findOneOrFail", "findOneByOrFail", "findAndCount", "findAndCountBy", "count", "countBy", "exists", "existsBy"])
178
- const ITERATION_METHODS = new Set(["map", "forEach", "flatMap", "filter", "reduce", "some", "every"])
179
- const LOOP_STATEMENTS = new Set(["ForStatement", "ForOfStatement", "ForInStatement"])
180
-
165
+ const LOOP_READS = new Set(["find", "findBy", "findOne", "findOneBy", "findOneOrFail", "findOneByOrFail", "findAndCount", "findAndCountBy", "count", "countBy", "exists", "existsBy"]);
166
+ const ITERATION_METHODS = new Set(["map", "forEach", "flatMap", "filter", "reduce", "some", "every"]);
167
+ const LOOP_STATEMENTS = new Set(["ForStatement", "ForOfStatement", "ForInStatement"]);
181
168
  /** Whether `node` runs once per element: inside a `for` loop, or inside a callback of an array iteration method. */
182
169
  const insideIteration = (node) => {
183
- let current = node.parent
170
+ let current = node.parent;
184
171
  while (current) {
185
- if (LOOP_STATEMENTS.has(current.type)) return true
172
+ if (LOOP_STATEMENTS.has(current.type))
173
+ return true;
186
174
  if (current.type === "FunctionDeclaration" || current.type === "FunctionExpression" || current.type === "ArrowFunctionExpression") {
187
- const call = current.parent
188
- return (
189
- call?.type === "CallExpression"
175
+ const call = current.parent;
176
+ return (call?.type === "CallExpression"
190
177
  && call.callee.type === "MemberExpression"
191
178
  && !call.callee.computed
192
179
  && call.callee.property.type === "Identifier"
193
180
  && ITERATION_METHODS.has(call.callee.property.name)
194
- && call.arguments.includes(current)
195
- )
181
+ && call.arguments.some((argument) => argument === current));
196
182
  }
197
- current = current.parent
183
+ current = current.parent;
198
184
  }
199
- return false
200
- }
201
-
185
+ return false;
186
+ };
202
187
  /** A read inside an iteration is N+1: one round trip per element. */
203
188
  export const noQueryInLoop = {
204
189
  meta: {
@@ -206,21 +191,21 @@ export const noQueryInLoop = {
206
191
  docs: { description: "An `EntityManager` read does not run once per element of a loop." },
207
192
  schema: [],
208
193
  messages: {
209
- inLoop:
210
- "`.{{method}}(...)` runs once per element, so the number of round trips grows with the input (N+1) and one large request holds a connection for as long as it takes. Read the rows once before the loop with `find(Entity, { where: { <key>: In(keys) }, take })` or a `SqlText` with `WHERE <key> = ANY($1)`, index them in a `Map`, and look up inside the loop. A polling `while` loop is not this rule's business.",
194
+ inLoop: "`.{{method}}(...)` runs once per element, so the number of round trips grows with the input (N+1) and one large request holds a connection for as long as it takes. Read the rows once before the loop with `find(Entity, { where: { <key>: In(keys) }, take })` or a `SqlText` with `WHERE <key> = ANY($1)`, index them in a `Map`, and look up inside the loop. A polling `while` loop is not this rule's business.",
211
195
  },
212
196
  },
213
197
  create(context) {
214
198
  return {
215
199
  CallExpression(node) {
216
- const method = calleeProperty(node)
217
- if (!method || !LOOP_READS.has(method) || !insideIteration(node)) return
218
- if (infraTypeOf(context, node.callee.object) === "EntityManager") context.report({ node: node.callee.property, messageId: "inLoop", data: { method } })
200
+ const method = calleeProperty(node);
201
+ if (!method || !LOOP_READS.has(method) || !insideIteration(node))
202
+ return;
203
+ if (node.callee.type === "MemberExpression" && infraTypeOf(context, node.callee.object) === "EntityManager")
204
+ context.report({ node: node.callee.property, messageId: "inLoop", data: { method } });
219
205
  },
220
- }
206
+ };
221
207
  },
222
- }
223
-
208
+ };
224
209
  /** The rules this law contributes to the plugin. */
225
210
  export const rules = {
226
211
  "sql-text-only": sqlTextOnly,
@@ -228,8 +213,7 @@ export const rules = {
228
213
  "no-interpolated-sql": noInterpolatedSql,
229
214
  "query-needs-limit": queryNeedsLimit,
230
215
  "no-query-in-loop": noQueryInLoop,
231
- }
232
-
216
+ };
233
217
  /** Every rule of this law ships at `error`; no baseline exists. */
234
218
  export const recommended = {
235
219
  "starci-be/sql-text-only": "error",
@@ -237,4 +221,4 @@ export const recommended = {
237
221
  "starci-be/no-interpolated-sql": "error",
238
222
  "starci-be/query-needs-limit": "error",
239
223
  "starci-be/no-query-in-loop": "error",
240
- }
224
+ };
@@ -0,0 +1,15 @@
1
+ import type { Recommended, RuleModule } from "./lib/rule.js";
2
+ /** A realtime file is the one door its role names, and nothing else. */
3
+ export declare const realtimeShape: RuleModule;
4
+ /** A realtime door injects the hub and nothing else: it reads and pushes, it never writes. */
5
+ export declare const realtimeReadOnly: RuleModule;
6
+ /** The topic a client subscribes to is built from the principal the handler receives. */
7
+ export declare const realtimeTopicScope: RuleModule;
8
+ /** The rules this law contributes to the plugin. */
9
+ export declare const rules: {
10
+ "realtime-shape": RuleModule;
11
+ "realtime-read-only": RuleModule;
12
+ "realtime-topic-scope": RuleModule;
13
+ };
14
+ /** Every rule of this law at `error`. */
15
+ export declare const recommended: Recommended;