@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
@@ -7,13 +7,11 @@
7
7
  * (`isOwnedType`), so a renamed receiver, a property injection and a lookalike class in another owner all get the
8
8
  * right answer. Everything here refuses to run without typed linting (see `types.mjs`).
9
9
  */
10
- import ts from "typescript"
11
- import { hfsOf } from "./hfs.mjs"
12
- import { typeOrigins, typed } from "./types.mjs"
13
-
10
+ import ts from "typescript";
11
+ import { hfsOf } from "./hfs.js";
12
+ import { typeOrigins, typed } from "./types.js";
14
13
  /** The last segment of a forward-slash path. */
15
- export const baseName = (file) => String(file).replace(/\\/g, "/").split("/").pop() ?? ""
16
-
14
+ export const baseName = (file) => String(file).replace(/\\/g, "/").split("/").pop() ?? "";
17
15
  /**
18
16
  * The capability or feature an HFS slot binds a file to (`logging` for `src/modules/platform/logging/x.ts`), or null.
19
17
  *
@@ -22,13 +20,13 @@ export const baseName = (file) => String(file).replace(/\\/g, "/").split("/").po
22
20
  * @returns {string | null} The owner name the slot binds.
23
21
  */
24
22
  export const ownerNameOf = (hfs, file) => {
25
- const bindings = hfs.classify(file).bindings ?? {}
26
- if (bindings.capability ?? bindings.feature) return bindings.capability ?? bindings.feature
23
+ const bindings = hfs.classify(file).bindings ?? {};
24
+ if (bindings.capability ?? bindings.feature)
25
+ return bindings.capability ?? bindings.feature;
27
26
  // A pattern slot names its capability literally (`src/modules/platform/event-bus/`), so no variable binds it: the owner folder is its name.
28
- const root = hfs.ownerOf(file)
29
- return root === null || root === undefined ? null : root.split("/").pop()
30
- }
31
-
27
+ const root = hfs.ownerOf(file);
28
+ return root === null || root === undefined ? null : root.split("/").pop();
29
+ };
32
30
  /**
33
31
  * The part of a file's path below its slot root (`migrations/1-x.ts` for a file of `be.persistence`), or null when no slot owns it.
34
32
  *
@@ -37,18 +35,16 @@ export const ownerNameOf = (hfs, file) => {
37
35
  * @returns {string | null} The slot-relative path.
38
36
  */
39
37
  const pathInSlot = (hfs, file) => {
40
- const found = hfs.classify(file)
41
- if (!found.slot) return null
42
- const rel = hfs.relative(file)
43
- return found.root ? rel.slice(found.root.length + 1) : rel
44
- }
45
-
38
+ const found = hfs.classify(file);
39
+ if (!found.slot)
40
+ return null;
41
+ const rel = hfs.relative(file);
42
+ return found.root ? rel.slice(found.root.length + 1) : rel;
43
+ };
46
44
  /** A migration: a file of slot `be.persistence` below its `migrations/` folder - the one place schema-changing SQL may be written. */
47
- export const isMigrationFile = (hfs, file) => hfs.slotOf(file) === "be.persistence" && (pathInSlot(hfs, file) ?? "").startsWith("migrations/")
48
-
45
+ export const isMigrationFile = (hfs, file) => hfs.slotOf(file) === "be.persistence" && (pathInSlot(hfs, file) ?? "").startsWith("migrations/");
49
46
  /** True when the file belongs to the named capability of the named tier (`platform`, `clock`). */
50
- export const isOwnedBy = (hfs, file, tier, capability) => hfs.tierOf(file) === tier && ownerNameOf(hfs, file) === capability
51
-
47
+ export const isOwnedBy = (hfs, file, tier, capability) => hfs.tierOf(file) === tier && ownerNameOf(hfs, file) === capability;
52
48
  /**
53
49
  * True when the node's type is `name` declared inside the repository by the given owner (a platform port, a brand).
54
50
  *
@@ -58,17 +54,14 @@ export const isOwnedBy = (hfs, file, tier, capability) => hfs.tierOf(file) === t
58
54
  * @returns {boolean} Whether one of the node's type origins matches.
59
55
  */
60
56
  export const isOwnedType = (context, node, { name, capability, tier }) => {
61
- const hfs = hfsOf(context)
62
- return typeOrigins(context, node).some((origin) =>
63
- origin.module === null
57
+ const hfs = hfsOf(context);
58
+ return typeOrigins(context, node).some((origin) => origin.module === null
64
59
  && origin.name === name
65
60
  && ownerNameOf(hfs, origin.file) === capability
66
- && (tier === undefined || hfs.tierOf(origin.file) === tier))
67
- }
68
-
61
+ && (tier === undefined || hfs.tierOf(origin.file) === tier));
62
+ };
69
63
  /** The `Logger` port of `platform/logging`. */
70
- export const isLoggerType = (context, node) => isOwnedType(context, node, { name: "Logger", capability: "logging", tier: "platform" })
71
-
64
+ export const isLoggerType = (context, node) => isOwnedType(context, node, { name: "Logger", capability: "logging", tier: "platform" });
72
65
  /**
73
66
  * True when the call is `<receiver>.<method>(...)` on a receiver typed as the `Logger` port.
74
67
  *
@@ -76,16 +69,15 @@ export const isLoggerType = (context, node) => isOwnedType(context, node, { name
76
69
  * @param {object} node - A CallExpression.
77
70
  * @returns {boolean} Whether it is a logger call.
78
71
  */
79
- export const isLoggerCall = (context, node) =>
80
- node.callee.type === "MemberExpression" && !node.callee.computed && isLoggerType(context, node.callee.object)
81
-
72
+ export const isLoggerCall = (context, node) => node.callee.type === "MemberExpression" && !node.callee.computed && isLoggerType(context, node.callee.object);
82
73
  /** What one enum-typed value is: the enum's name and file, or null when the type is not (only) enum members. */
83
74
  const enumOf = (declaration) => {
84
- if (declaration && ts.isEnumMember(declaration)) return declaration.parent
85
- if (declaration && ts.isEnumDeclaration(declaration)) return declaration
86
- return null
87
- }
88
-
75
+ if (declaration && ts.isEnumMember(declaration))
76
+ return declaration.parent;
77
+ if (declaration && ts.isEnumDeclaration(declaration))
78
+ return declaration;
79
+ return null;
80
+ };
89
81
  /**
90
82
  * The enums a node's value belongs to, when its type is an enum member, an enum, or a union of members.
91
83
  *
@@ -94,21 +86,22 @@ const enumOf = (declaration) => {
94
86
  * @returns {Array<{ name: string, file: string }> | null} One entry per enum, or null when any part of the type is not an enum member.
95
87
  */
96
88
  export const enumsOf = (context, node) => {
97
- const { checker, toTs } = typed(context)
98
- const tsNode = toTs(node)
99
- if (!tsNode) return null
100
- const type = checker.getTypeAtLocation(tsNode)
101
- const parts = type.isUnion() ? type.types : [type]
102
- const found = []
89
+ const { checker, toTs } = typed(context);
90
+ const tsNode = toTs(node);
91
+ if (!tsNode)
92
+ return null;
93
+ const type = checker.getTypeAtLocation(tsNode);
94
+ const parts = type.isUnion() ? type.types : [type];
95
+ const found = [];
103
96
  for (const part of parts) {
104
- const symbol = part.getSymbol?.()
105
- const owner = enumOf(symbol?.valueDeclaration ?? symbol?.declarations?.[0])
106
- if (!owner) return null
107
- found.push({ name: owner.name.text, file: String(owner.getSourceFile().fileName).replace(/\\/g, "/") })
97
+ const symbol = part.getSymbol?.();
98
+ const owner = enumOf(symbol?.valueDeclaration ?? symbol?.declarations?.[0]);
99
+ if (!owner)
100
+ return null;
101
+ found.push({ name: owner.name.text, file: String(owner.getSourceFile().fileName).replace(/\\/g, "/") });
108
102
  }
109
- return found.length > 0 ? found : null
110
- }
111
-
103
+ return found.length > 0 ? found : null;
104
+ };
112
105
  /**
113
106
  * The name of the enum member an expression is, when its type is one enum-literal type (`PublicReason.SignedWebhook`).
114
107
  *
@@ -117,15 +110,16 @@ export const enumsOf = (context, node) => {
117
110
  * @returns {{ enumName: string, member: string } | null} The enum and the member, or null.
118
111
  */
119
112
  export const enumMemberOf = (context, node) => {
120
- const { checker, toTs } = typed(context)
121
- const tsNode = toTs(node)
122
- if (!tsNode) return null
123
- const symbol = checker.getTypeAtLocation(tsNode).getSymbol?.()
124
- const declaration = symbol?.valueDeclaration ?? symbol?.declarations?.[0]
125
- if (!declaration || !ts.isEnumMember(declaration)) return null
126
- return { enumName: declaration.parent.name.text, member: declaration.name.getText() }
127
- }
128
-
113
+ const { checker, toTs } = typed(context);
114
+ const tsNode = toTs(node);
115
+ if (!tsNode)
116
+ return null;
117
+ const symbol = checker.getTypeAtLocation(tsNode).getSymbol?.();
118
+ const declaration = symbol?.valueDeclaration ?? symbol?.declarations?.[0];
119
+ if (!declaration || !ts.isEnumMember(declaration))
120
+ return null;
121
+ return { enumName: declaration.parent.name.text, member: declaration.name.getText() };
122
+ };
129
123
  /**
130
124
  * The package a declaration file belongs to (`typeorm`, `@nestjs/typeorm`), read from its innermost `node_modules/` folder, or null for the repository's own source.
131
125
  *
@@ -133,9 +127,11 @@ export const enumMemberOf = (context, node) => {
133
127
  * @returns {string | null} The package name.
134
128
  */
135
129
  export const packageOfFile = (file) => {
136
- const normal = String(file).replace(/\\/g, "/")
137
- const at = normal.lastIndexOf("/node_modules/")
138
- if (at < 0) return null
139
- const parts = normal.slice(at + "/node_modules/".length).split("/")
140
- return parts[0].startsWith("@") ? `${parts[0]}/${parts[1]}` : parts[0]
141
- }
130
+ const normal = String(file).replace(/\\/g, "/");
131
+ const at = normal.lastIndexOf("/node_modules/");
132
+ if (at < 0)
133
+ return null;
134
+ const parts = normal.slice(at + "/node_modules/".length).split("/");
135
+ const head = parts[0] ?? "";
136
+ return head.startsWith("@") ? `${head}/${parts[1]}` : head;
137
+ };
@@ -0,0 +1,31 @@
1
+ /**
2
+ * The types every law module shares: the rule a law publishes, the context ESLint hands its `create`, the AST node it walks
3
+ * and the recommended levels it asks for. They are typescript-eslint's own (`@typescript-eslint/utils`), since every file the
4
+ * canon lints is parsed by `@typescript-eslint/parser` and carries its TypeScript nodes (decorators, parameter properties,
5
+ * type annotations) beside the ESTree ones.
6
+ */
7
+ import type { TSESLint, TSESTree } from "@typescript-eslint/utils";
8
+ /** Any node of the typescript-eslint AST. */
9
+ export type Node = TSESTree.Node;
10
+ /** The options a canon rule receives: every rule reads its options as data and checks them itself. */
11
+ export type RuleOptions = unknown[];
12
+ /** The context of one rule run. */
13
+ export type Context = Readonly<TSESLint.RuleContext<string, RuleOptions>>;
14
+ /** The visitor a rule's `create` returns. */
15
+ export type RuleListener = TSESLint.RuleListener;
16
+ /** One rule a law publishes. */
17
+ export type RuleModule = TSESLint.RuleModule<string, RuleOptions>;
18
+ /** The rules of a law (or of the plugin), by published name. */
19
+ export type Rules = Readonly<Record<string, RuleModule>>;
20
+ /** A level ESLint understands. */
21
+ export type Level = "error" | "warn" | "off";
22
+ /** A recommended entry: a level, or a level with the rule's options (ESLint's own shape). */
23
+ export type RuleEntry = TSESLint.SharedConfig.RuleEntry;
24
+ /** The recommended levels of a law, by `starci-be/<name>` (or a stock rule's own name). */
25
+ export type Recommended = Readonly<Record<string, RuleEntry>>;
26
+ /** A single report a rule makes. */
27
+ export type Report = TSESLint.ReportDescriptor<string>;
28
+ /** A comment of the linted source. */
29
+ export type Comment = TSESTree.Comment;
30
+ /** Whether a value is a node of the typescript-eslint AST (any object with a string `type`). */
31
+ export declare const isNode: (value: unknown) => value is Node;
@@ -0,0 +1,2 @@
1
+ /** Whether a value is a node of the typescript-eslint AST (any object with a string `type`). */
2
+ export const isNode = (value) => value !== null && typeof value === "object" && "type" in value && typeof value.type === "string";
@@ -0,0 +1,4 @@
1
+ /** The package root: the folder holding package.json, runtime/ and fixtures/. */
2
+ export declare const PACKAGE_ROOT: string;
3
+ /** The bundled runtime the slot manifest, rule catalog and architecture machine are read from. */
4
+ export declare const RUNTIME_ROOT: string;
@@ -0,0 +1,10 @@
1
+ /**
2
+ * The package root and its bundled `runtime/` folder. `src/` (run by the specs) and `dist/` (published) both sit one level below the
3
+ * package root, so the same relative step finds the runtime from either.
4
+ */
5
+ import { dirname, join } from "node:path";
6
+ import { fileURLToPath } from "node:url";
7
+ /** The package root: the folder holding package.json, runtime/ and fixtures/. */
8
+ export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
9
+ /** The bundled runtime the slot manifest, rule catalog and architecture machine are read from. */
10
+ export const RUNTIME_ROOT = join(PACKAGE_ROOT, "runtime");
@@ -0,0 +1,13 @@
1
+ import type { HfsView } from "./hfs.js";
2
+ /** Tiers a schema file may live in: the owners of boundary data (R304). */
3
+ export declare const SCHEMA_TIERS: ReadonlySet<string | null>;
4
+ /**
5
+ * The reasons a source text is not a pure boundary schema file: it imports zod and holds nothing but imports, types and
6
+ * `const X = <zod chain>` values, with no class, function, provider or other logic. An empty list means a value-only schema file.
7
+ */
8
+ export declare const schemaFileProblems: (text: string) => string[];
9
+ /**
10
+ * Whether the sibling `<name>.schema.ts` of a `<name>.schema.spec.ts` is a real boundary schema: it exists, lives in an owner tier of R304 and is
11
+ * value-only (schemaFileProblems). Read from disk once per file and modification time.
12
+ */
13
+ export declare const siblingIsValueSchema: (hfs: HfsView, specFile: string) => boolean;
@@ -1,90 +1,98 @@
1
- import fs from "node:fs"
2
- import path from "node:path"
3
- import ts from "typescript"
4
- import { normalizePath } from "./path.mjs"
5
-
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+ import ts from "typescript";
4
+ import { normalizePath } from "./path.js";
6
5
  /** Tiers a schema file may live in: the owners of boundary data (R304). */
7
- export const SCHEMA_TIERS = new Set(["domain", "platform", "integrations"])
8
-
9
- const ZOD = /^zod(?:\/|$)/
6
+ export const SCHEMA_TIERS = new Set(["domain", "platform", "integrations"]);
7
+ const ZOD = /^zod(?:\/|$)/;
10
8
  /** A sibling schema module: its exports are schemas too, so a chain may start from them. */
11
- const SIBLING_SCHEMA = /^\.{1,2}\/(?:.*\/)?[^/]+\.schema(?:\.[cm]?[jt]s)?$/
12
-
9
+ const SIBLING_SCHEMA = /^\.{1,2}\/(?:.*\/)?[^/]+\.schema(?:\.[cm]?[jt]s)?$/;
13
10
  /** The local names the imports of a source file bind whose module specifier matches `specifier`. */
14
11
  const importedNames = (sourceFile, specifier) => {
15
- const names = new Set()
12
+ const names = new Set();
16
13
  for (const statement of sourceFile.statements) {
17
- if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !specifier.test(statement.moduleSpecifier.text)) continue
18
- const clause = statement.importClause
19
- if (clause?.name) names.add(clause.name.text)
20
- const bindings = clause?.namedBindings
21
- if (bindings && ts.isNamespaceImport(bindings)) names.add(bindings.name.text)
22
- if (bindings && ts.isNamedImports(bindings)) for (const element of bindings.elements) names.add(element.name.text)
14
+ if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !specifier.test(statement.moduleSpecifier.text))
15
+ continue;
16
+ const clause = statement.importClause;
17
+ if (clause?.name)
18
+ names.add(clause.name.text);
19
+ const bindings = clause?.namedBindings;
20
+ if (bindings && ts.isNamespaceImport(bindings))
21
+ names.add(bindings.name.text);
22
+ if (bindings && ts.isNamedImports(bindings))
23
+ for (const element of bindings.elements)
24
+ names.add(element.name.text);
23
25
  }
24
- return names
25
- }
26
-
26
+ return names;
27
+ };
27
28
  /** The identifier a call/member chain starts from (`z.string().max(5)` gives `z`), or null when it starts from anything else. */
28
29
  const rootOf = (expression) => {
29
- let current = expression
30
+ let current = expression;
30
31
  for (;;) {
31
- if (ts.isIdentifier(current)) return current.text
32
+ if (ts.isIdentifier(current))
33
+ return current.text;
32
34
  if (ts.isCallExpression(current) || ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current)
33
- || ts.isNonNullExpression(current) || ts.isParenthesizedExpression(current) || ts.isAsExpression(current)) current = current.expression
34
- else return null
35
+ || ts.isNonNullExpression(current) || ts.isParenthesizedExpression(current) || ts.isAsExpression(current))
36
+ current = current.expression;
37
+ else
38
+ return null;
35
39
  }
36
- }
37
-
40
+ };
38
41
  /** A literal bound (`100`, `-1`, `"x"`, `true`): data a schema reads, nothing that runs. */
39
42
  const isLiteral = (expression) => ts.isNumericLiteral(expression) || ts.isStringLiteralLike(expression)
40
43
  || expression.kind === ts.SyntaxKind.TrueKeyword || expression.kind === ts.SyntaxKind.FalseKeyword
41
- || (ts.isPrefixUnaryExpression(expression) && ts.isNumericLiteral(expression.operand))
42
-
44
+ || (ts.isPrefixUnaryExpression(expression) && ts.isNumericLiteral(expression.operand));
43
45
  /** A statement a schema file may hold: an import, a type, or `export const X = <zod chain or a sibling schema>`. */
44
46
  const statementProblem = (statement, zodNames, declared) => {
45
- if (ts.isImportDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isInterfaceDeclaration(statement)) return null
46
- if (ts.isExportDeclaration(statement)) return null
47
- if (!ts.isVariableStatement(statement)) return `a ${ts.SyntaxKind[statement.kind]} is logic, not a schema value`
47
+ if (ts.isImportDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isInterfaceDeclaration(statement))
48
+ return null;
49
+ if (ts.isExportDeclaration(statement))
50
+ return null;
51
+ if (!ts.isVariableStatement(statement))
52
+ return `a ${ts.SyntaxKind[statement.kind]} is logic, not a schema value`;
48
53
  for (const declaration of statement.declarationList.declarations) {
49
- const init = declaration.initializer
50
- if (init && isLiteral(init) && ts.isIdentifier(declaration.name)) { declared.add(declaration.name.text); continue }
51
- const root = init ? rootOf(init) : null
54
+ const init = declaration.initializer;
55
+ if (init && isLiteral(init) && ts.isIdentifier(declaration.name)) {
56
+ declared.add(declaration.name.text);
57
+ continue;
58
+ }
59
+ const root = init ? rootOf(init) : null;
52
60
  if (!ts.isIdentifier(declaration.name) || root === null || !(zodNames.has(root) || declared.has(root))) {
53
- return `${declaration.name.getText()} is not a zod schema (a schema file declares only zod chains and types)`
61
+ return `${declaration.name.getText()} is not a zod schema (a schema file declares only zod chains and types)`;
54
62
  }
55
- declared.add(declaration.name.text)
63
+ declared.add(declaration.name.text);
56
64
  }
57
- return null
58
- }
59
-
65
+ return null;
66
+ };
60
67
  /**
61
68
  * The reasons a source text is not a pure boundary schema file: it imports zod and holds nothing but imports, types and
62
69
  * `const X = <zod chain>` values, with no class, function, provider or other logic. An empty list means a value-only schema file.
63
70
  */
64
71
  export const schemaFileProblems = (text) => {
65
- const sourceFile = ts.createSourceFile("subject.schema.ts", text, ts.ScriptTarget.Latest, true)
66
- const zodNames = importedNames(sourceFile, ZOD)
67
- if (zodNames.size === 0) return ["it imports no zod, so it is not a boundary schema"]
68
- const declared = importedNames(sourceFile, SIBLING_SCHEMA)
72
+ const sourceFile = ts.createSourceFile("subject.schema.ts", text, ts.ScriptTarget.Latest, true);
73
+ const zodNames = importedNames(sourceFile, ZOD);
74
+ if (zodNames.size === 0)
75
+ return ["it imports no zod, so it is not a boundary schema"];
76
+ const declared = importedNames(sourceFile, SIBLING_SCHEMA);
69
77
  return sourceFile.statements.flatMap((statement) => {
70
- const problem = statementProblem(statement, zodNames, declared)
71
- return problem === null ? [] : [problem]
72
- })
73
- }
74
-
75
- const CACHE = new Map()
76
-
78
+ const problem = statementProblem(statement, zodNames, declared);
79
+ return problem === null ? [] : [problem];
80
+ });
81
+ };
82
+ const CACHE = new Map();
77
83
  /**
78
84
  * Whether the sibling `<name>.schema.ts` of a `<name>.schema.spec.ts` is a real boundary schema: it exists, lives in an owner tier of R304 and is
79
85
  * value-only (schemaFileProblems). Read from disk once per file and modification time.
80
86
  */
81
87
  export const siblingIsValueSchema = (hfs, specFile) => {
82
- const sibling = normalizePath(path.resolve(specFile.replace(/\.spec\.ts$/u, ".ts")))
83
- if (!fs.existsSync(sibling) || !SCHEMA_TIERS.has(hfs.tierOf(sibling))) return false
84
- const stamp = fs.statSync(sibling).mtimeMs
85
- const cached = CACHE.get(sibling)
86
- if (cached?.stamp === stamp) return cached.ok
87
- const ok = schemaFileProblems(fs.readFileSync(sibling, "utf8")).length === 0
88
- CACHE.set(sibling, { stamp, ok })
89
- return ok
90
- }
88
+ const sibling = normalizePath(path.resolve(specFile.replace(/\.spec\.ts$/u, ".ts")));
89
+ if (!fs.existsSync(sibling) || !SCHEMA_TIERS.has(hfs.tierOf(sibling)))
90
+ return false;
91
+ const stamp = fs.statSync(sibling).mtimeMs;
92
+ const cached = CACHE.get(sibling);
93
+ if (cached?.stamp === stamp)
94
+ return cached.ok;
95
+ const ok = schemaFileProblems(fs.readFileSync(sibling, "utf8")).length === 0;
96
+ CACHE.set(sibling, { stamp, ok });
97
+ return ok;
98
+ };
@@ -0,0 +1,12 @@
1
+ import type { Context } from "./rule.js";
2
+ /**
3
+ * The absolute path an alias specifier maps to under the program's `compilerOptions.paths`, or null when no pattern matches.
4
+ *
5
+ * @param context - The ESLint rule context.
6
+ * @param specifier - An import specifier.
7
+ * @returns The absolute target without extension and the part the wildcard matched.
8
+ */
9
+ export declare const resolveAlias: (context: Context, specifier: string) => {
10
+ target: string;
11
+ rest: string;
12
+ } | null;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Where an import specifier points. A `compilerOptions.paths` alias resolves through the program's own options, so a
3
+ * rule asks the same question TypeScript asks instead of maintaining a second alias table.
4
+ */
5
+ import { posix } from "node:path";
6
+ import { typed } from "./types.js";
7
+ /**
8
+ * The absolute path an alias specifier maps to under the program's `compilerOptions.paths`, or null when no pattern matches.
9
+ *
10
+ * @param context - The ESLint rule context.
11
+ * @param specifier - An import specifier.
12
+ * @returns The absolute target without extension and the part the wildcard matched.
13
+ */
14
+ export const resolveAlias = (context, specifier) => {
15
+ const options = typed(context).program.getCompilerOptions();
16
+ const base = options.baseUrl ?? options.pathsBasePath;
17
+ if (!options.paths || typeof base !== "string")
18
+ return null;
19
+ for (const [pattern, targets] of Object.entries(options.paths)) {
20
+ if (!pattern.endsWith("/*") || !targets[0])
21
+ continue;
22
+ const prefix = pattern.slice(0, -1);
23
+ if (!specifier.startsWith(prefix))
24
+ continue;
25
+ const rest = specifier.slice(prefix.length);
26
+ return { target: posix.normalize(`${base.replace(/\\/g, "/")}/${targets[0].replace("*", rest)}`), rest };
27
+ }
28
+ return null;
29
+ };
@@ -0,0 +1,4 @@
1
+ import type { Context, Node } from "./rule.js";
2
+ /** The sibling module's value-object classes (undecorated, no constructor injection token), read from disk once per file; `[]` when none. */
3
+ export declare const valueObjectsOfSibling: (context: Context) => string[];
4
+ export declare const isRealSubjectValue: (context: Context, value: Node) => boolean;
@@ -0,0 +1,61 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+ import ts from "typescript";
4
+ import { functionSubjectExports, valueObjectSubjects } from "../../runtime/scripts/hfs/architecture/function-spec-providers.mjs";
5
+ import { importOf } from "./import-source.js";
6
+ import { typed } from "./types.js";
7
+ /** The exported real function of a function-only sibling subject, with aliases resolved by TypeScript. */
8
+ const realSubjectFunction = (context, value) => {
9
+ if (value.type !== "Identifier")
10
+ return null;
11
+ const imported = importOf(context, value);
12
+ if (!imported || !imported.source.startsWith("."))
13
+ return null;
14
+ const { checker, toTs } = typed(context);
15
+ const tsNode = toTs(value);
16
+ const symbol = ts.isShorthandPropertyAssignment(tsNode.parent)
17
+ ? checker.getShorthandAssignmentValueSymbol(tsNode.parent) : checker.getSymbolAtLocation(tsNode);
18
+ const alias = symbol?.declarations?.some(declaration => ts.isImportSpecifier(declaration));
19
+ const target = alias && symbol ? checker.getAliasedSymbol(symbol) : symbol;
20
+ const declaration = target?.valueDeclaration;
21
+ if (!declaration)
22
+ return null;
23
+ const sourceFile = declaration.getSourceFile();
24
+ const sibling = (context.filename || context.getFilename()).replace(/\.spec\.ts$/u, ".ts");
25
+ if (path.resolve(sourceFile.fileName) !== path.resolve(sibling))
26
+ return null;
27
+ const names = functionSubjectExports(ts, sourceFile);
28
+ return imported.imported !== null && names?.includes(imported.imported) ? imported.imported : null;
29
+ };
30
+ const VALUE_OBJECTS = new Map();
31
+ /** The sibling module's value-object classes (undecorated, no constructor injection token), read from disk once per file; `[]` when none. */
32
+ export const valueObjectsOfSibling = (context) => {
33
+ const sibling = path.resolve((context.filename || context.getFilename()).replace(/\.spec\.ts$/u, ".ts"));
34
+ const stamp = fs.existsSync(sibling) ? fs.statSync(sibling).mtimeMs : -1;
35
+ const cached = VALUE_OBJECTS.get(sibling);
36
+ if (cached?.stamp === stamp)
37
+ return cached.names;
38
+ const names = stamp < 0 ? [] : valueObjectSubjects(ts, ts.createSourceFile(sibling, fs.readFileSync(sibling, "utf8"), ts.ScriptTarget.Latest, true)) ?? [];
39
+ VALUE_OBJECTS.set(sibling, { stamp, names });
40
+ return names;
41
+ };
42
+ /** `new Subject(...)` where Subject is a value-object class imported from the sibling module. */
43
+ const isValueObjectSubject = (context, value) => {
44
+ if (value.type !== "NewExpression" || value.callee.type !== "Identifier")
45
+ return false;
46
+ const imported = importOf(context, value.callee);
47
+ return Boolean(imported && imported.source.startsWith(".") && imported.imported !== null && valueObjectsOfSibling(context).includes(imported.imported));
48
+ };
49
+ /** Real functions under test are subject values; an inline fake or a collaborator remains a kit double. */
50
+ /** The name or value a non-computed property key spells. */
51
+ const keyOf = (key) => (key.type === "Identifier" || key.type === "PrivateIdentifier" ? key.name : "value" in key ? key.value : undefined);
52
+ export const isRealSubjectValue = (context, value) => {
53
+ if (isValueObjectSubject(context, value))
54
+ return true;
55
+ if (value.type === "Identifier")
56
+ return realSubjectFunction(context, value) !== null;
57
+ if (value.type !== "ObjectExpression" || value.properties.length === 0)
58
+ return false;
59
+ return value.properties.every((property) => property.type === "Property" && !property.computed
60
+ && keyOf(property.key) === realSubjectFunction(context, property.value));
61
+ };
@@ -0,0 +1,18 @@
1
+ import type { TSESLint, TSESTree } from "@typescript-eslint/utils";
2
+ import type { Context } from "./rule.js";
3
+ /**
4
+ * The callback of a `.transaction(...)` call on a manager or data source, or null.
5
+ *
6
+ * @param {object} context - The ESLint rule context.
7
+ * @param {object} node - A CallExpression.
8
+ * @returns {object | null} The arrow or function expression that receives the transactional manager.
9
+ */
10
+ export declare const transactionCallback: (context: Context, node: TSESTree.CallExpression) => TSESTree.ArrowFunctionExpression | TSESTree.FunctionExpression | null;
11
+ /**
12
+ * The variable an identifier resolves to, looking outward from the identifier's own scope.
13
+ *
14
+ * @param {object} sourceCode - The ESLint source code.
15
+ * @param {object} node - An Identifier.
16
+ * @returns {object | null} The scope variable.
17
+ */
18
+ export declare const resolveVariable: (sourceCode: Readonly<TSESLint.SourceCode>, node: TSESTree.Identifier) => TSESLint.Scope.Variable | null;
@@ -2,8 +2,7 @@
2
2
  * Questions a rule asks about database transactions: the callback of a `.transaction(...)` call and the variable an identifier
3
3
  * resolves to. The receiver of `.transaction` is judged by its TYPE (typeorm's `EntityManager` or `DataSource`), never by its name.
4
4
  */
5
- import { infraTypeOf } from "./persistence.mjs"
6
-
5
+ import { infraTypeOf } from "./persistence.js";
7
6
  /**
8
7
  * The callback of a `.transaction(...)` call on a manager or data source, or null.
9
8
  *
@@ -12,15 +11,17 @@ import { infraTypeOf } from "./persistence.mjs"
12
11
  * @returns {object | null} The arrow or function expression that receives the transactional manager.
13
12
  */
14
13
  export const transactionCallback = (context, node) => {
15
- const callee = node.callee
16
- if (callee.type !== "MemberExpression" || callee.computed) return null
17
- if (callee.property.type !== "Identifier" || callee.property.name !== "transaction") return null
18
- const receiver = infraTypeOf(context, callee.object)
19
- if (receiver !== "EntityManager" && receiver !== "DataSource") return null
20
- const callback = node.arguments[node.arguments.length - 1]
21
- return callback && (callback.type === "ArrowFunctionExpression" || callback.type === "FunctionExpression") ? callback : null
22
- }
23
-
14
+ const callee = node.callee;
15
+ if (callee.type !== "MemberExpression" || callee.computed)
16
+ return null;
17
+ if (callee.property.type !== "Identifier" || callee.property.name !== "transaction")
18
+ return null;
19
+ const receiver = infraTypeOf(context, callee.object);
20
+ if (receiver !== "EntityManager" && receiver !== "DataSource")
21
+ return null;
22
+ const callback = node.arguments[node.arguments.length - 1];
23
+ return callback && (callback.type === "ArrowFunctionExpression" || callback.type === "FunctionExpression") ? callback : null;
24
+ };
24
25
  /**
25
26
  * The variable an identifier resolves to, looking outward from the identifier's own scope.
26
27
  *
@@ -30,8 +31,9 @@ export const transactionCallback = (context, node) => {
30
31
  */
31
32
  export const resolveVariable = (sourceCode, node) => {
32
33
  for (let scope = sourceCode.getScope(node); scope; scope = scope.upper) {
33
- const variable = scope.set.get(node.name)
34
- if (variable) return variable
34
+ const variable = scope.set.get(node.name);
35
+ if (variable)
36
+ return variable;
35
37
  }
36
- return null
37
- }
38
+ return null;
39
+ };
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The transport slots of the HFS manifest, in one place.
3
+ *
4
+ * A slot id is manifest vocabulary, not a path: every rule that judges "a transport file" asks this instead of spelling
5
+ * the ids itself. A cli command is no transport: it is an action runner of the cli feature root (slot `be.cli`). The
6
+ * webhook and realtime kinds hold their doors in slots of their own (`be.feature.webhooks.http`, `be.feature.realtime.graphql`, `be.feature.realtime.websocket`, `be.feature.realtime.sse`): a provider webhook and a
7
+ * push channel are doors like any other and answer to the door laws (default deny, bounded input, no envelope).
8
+ */
9
+ /** The slots of the feature kinds that are doors but are not an api's `transport/<protocol>/` folders. */
10
+ export declare const KIND_DOOR_SLOTS: readonly string[];
11
+ /**
12
+ * True for a slot that holds transport code (`be.transport.<protocol>` and the door slots of the webhook and realtime kinds).
13
+ *
14
+ * @param {string | null} slot - A slot id from `hfs.slotOf`.
15
+ * @returns {boolean} Whether files of that slot are transport files.
16
+ */
17
+ export declare const isTransportSlot: (slot: unknown) => boolean;
@@ -6,14 +6,12 @@
6
6
  * webhook and realtime kinds hold their doors in slots of their own (`be.feature.webhooks.http`, `be.feature.realtime.graphql`, `be.feature.realtime.websocket`, `be.feature.realtime.sse`): a provider webhook and a
7
7
  * push channel are doors like any other and answer to the door laws (default deny, bounded input, no envelope).
8
8
  */
9
-
10
9
  /** The slots of the feature kinds that are doors but are not an api's `transport/<protocol>/` folders. */
11
- export const KIND_DOOR_SLOTS = Object.freeze(["be.feature.webhooks.http", "be.feature.realtime.graphql", "be.feature.realtime.websocket", "be.feature.realtime.sse"])
12
-
10
+ export const KIND_DOOR_SLOTS = Object.freeze(["be.feature.webhooks.http", "be.feature.realtime.graphql", "be.feature.realtime.websocket", "be.feature.realtime.sse"]);
13
11
  /**
14
12
  * True for a slot that holds transport code (`be.transport.<protocol>` and the door slots of the webhook and realtime kinds).
15
13
  *
16
14
  * @param {string | null} slot - A slot id from `hfs.slotOf`.
17
15
  * @returns {boolean} Whether files of that slot are transport files.
18
16
  */
19
- export const isTransportSlot = (slot) => typeof slot === "string" && (slot.startsWith("be.transport.") || KIND_DOOR_SLOTS.includes(slot))
17
+ export const isTransportSlot = (slot) => typeof slot === "string" && (slot.startsWith("be.transport.") || KIND_DOOR_SLOTS.includes(slot));