@starci/eslint-canon-be 3.5.0 → 3.6.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.
Files changed (195) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +11 -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.d.ts +34 -0
  78. package/{lib/hfs.mjs → dist/lib/hfs.js} +31 -29
  79. package/dist/lib/import-source.d.ts +63 -0
  80. package/dist/lib/import-source.js +134 -0
  81. package/dist/lib/path.d.ts +8 -0
  82. package/{lib/path.mjs → dist/lib/path.js} +4 -7
  83. package/dist/lib/persistence.d.ts +115 -0
  84. package/{lib/persistence.mjs → dist/lib/persistence.js} +55 -66
  85. package/dist/lib/ports.d.ts +70 -0
  86. package/{lib/ports.mjs → dist/lib/ports.js} +62 -66
  87. package/dist/lib/rule.d.ts +31 -0
  88. package/dist/lib/rule.js +2 -0
  89. package/dist/lib/runtime-root.d.ts +4 -0
  90. package/dist/lib/runtime-root.js +10 -0
  91. package/dist/lib/schema-values.d.ts +13 -0
  92. package/{lib/schema-values.mjs → dist/lib/schema-values.js} +67 -59
  93. package/dist/lib/specifier.d.ts +12 -0
  94. package/dist/lib/specifier.js +29 -0
  95. package/dist/lib/subject-values.d.ts +4 -0
  96. package/dist/lib/subject-values.js +61 -0
  97. package/dist/lib/transactions.d.ts +18 -0
  98. package/{lib/transactions.mjs → dist/lib/transactions.js} +17 -15
  99. package/dist/lib/transport-slots.d.ts +17 -0
  100. package/{lib/transport-slots.mjs → dist/lib/transport-slots.js} +2 -4
  101. package/dist/lib/types.d.ts +96 -0
  102. package/dist/lib/types.js +150 -0
  103. package/dist/lib/unit-spec.d.ts +48 -0
  104. package/{lib/unit-spec.mjs → dist/lib/unit-spec.js} +35 -44
  105. package/dist/lib/webhook-ack.d.ts +4 -0
  106. package/{lib/webhook-ack.mjs → dist/lib/webhook-ack.js} +78 -62
  107. package/dist/lib/webhook-handoff-inbox.d.ts +3 -0
  108. package/{lib/webhook-handoff-inbox.mjs → dist/lib/webhook-handoff-inbox.js} +195 -167
  109. package/dist/lib/webhook-handoff-intake.d.ts +4 -0
  110. package/{lib/webhook-handoff-intake.mjs → dist/lib/webhook-handoff-intake.js} +125 -102
  111. package/dist/lib/webhook-handoff.d.ts +15 -0
  112. package/{lib/webhook-handoff.mjs → dist/lib/webhook-handoff.js} +107 -100
  113. package/dist/lib/webhook-verifiers.d.ts +20 -0
  114. package/{lib/webhook-verifiers.mjs → dist/lib/webhook-verifiers.js} +108 -104
  115. package/dist/lib/why.d.ts +9 -0
  116. package/{lib/why.mjs → dist/lib/why.js} +6 -6
  117. package/dist/log-safety.d.ts +20 -0
  118. package/dist/log-safety.js +308 -0
  119. package/dist/module-layering.d.ts +42 -0
  120. package/dist/module-layering.js +257 -0
  121. package/dist/module-shape.d.ts +47 -0
  122. package/{module-shape.mjs → dist/module-shape.js} +278 -236
  123. package/dist/naming.d.ts +49 -0
  124. package/dist/naming.js +246 -0
  125. package/dist/observability.d.ts +25 -0
  126. package/dist/observability.js +245 -0
  127. package/dist/operations.d.ts +23 -0
  128. package/{operations.mjs → dist/operations.js} +410 -332
  129. package/dist/project-graph.d.ts +9 -0
  130. package/{project-graph.mjs → dist/project-graph.js} +8 -13
  131. package/dist/projections.d.ts +11 -0
  132. package/{projections.mjs → dist/projections.js} +60 -57
  133. package/dist/query-safety.d.ts +21 -0
  134. package/{query-safety.mjs → dist/query-safety.js} +92 -108
  135. package/dist/realtime.d.ts +15 -0
  136. package/{realtime.mjs → dist/realtime.js} +108 -106
  137. package/dist/resilience.d.ts +15 -0
  138. package/dist/resilience.js +319 -0
  139. package/dist/schema-authority.d.ts +15 -0
  140. package/{schema-authority.mjs → dist/schema-authority.js} +256 -220
  141. package/dist/service-deps.d.ts +17 -0
  142. package/{service-deps.mjs → dist/service-deps.js} +133 -130
  143. package/dist/service-isolation.d.ts +8 -0
  144. package/dist/service-isolation.js +76 -0
  145. package/dist/size-budget.d.ts +9 -0
  146. package/{size-budget.mjs → dist/size-budget.js} +27 -27
  147. package/dist/sonar-parity.d.ts +5 -0
  148. package/{sonar-parity.mjs → dist/sonar-parity.js} +7 -7
  149. package/dist/spec-no-skip.d.ts +9 -0
  150. package/dist/spec-no-skip.js +81 -0
  151. package/dist/spec-quality.d.ts +10 -0
  152. package/{spec-quality.mjs → dist/spec-quality.js} +103 -87
  153. package/dist/suppression.d.ts +26 -0
  154. package/{suppression.mjs → dist/suppression.js} +30 -45
  155. package/dist/temporal.d.ts +9 -0
  156. package/{temporal.mjs → dist/temporal.js} +75 -65
  157. package/dist/test-world.d.ts +28 -0
  158. package/{test-world.mjs → dist/test-world.js} +102 -83
  159. package/dist/testing.d.ts +51 -0
  160. package/dist/testing.js +368 -0
  161. package/dist/third-party-owner.d.ts +8 -0
  162. package/{third-party-owner.mjs → dist/third-party-owner.js} +105 -91
  163. package/dist/transport.d.ts +24 -0
  164. package/{transport.mjs → dist/transport.js} +279 -240
  165. package/dist/type-safety.d.ts +25 -0
  166. package/dist/type-safety.js +297 -0
  167. package/dist/unit-spec.d.ts +30 -0
  168. package/{unit-spec.mjs → dist/unit-spec.js} +473 -399
  169. package/dist/uploads.d.ts +9 -0
  170. package/{uploads.mjs → dist/uploads.js} +62 -54
  171. package/dist/user-copy.d.ts +9 -0
  172. package/{user-copy.mjs → dist/user-copy.js} +76 -67
  173. package/dist/webhooks.d.ts +16 -0
  174. package/{webhooks.mjs → dist/webhooks.js} +243 -231
  175. package/package.json +17 -8
  176. package/runtime/knowledge/hfs/canon-pins.yaml +17 -10
  177. package/async-discipline.mjs +0 -83
  178. package/comments.mjs +0 -416
  179. package/edge-hardening.mjs +0 -139
  180. package/health-ready.mjs +0 -539
  181. package/jwt-alg.mjs +0 -45
  182. package/lib/ast.mjs +0 -88
  183. package/lib/import-source.mjs +0 -104
  184. package/lib/specifier.mjs +0 -27
  185. package/lib/subject-values.mjs +0 -55
  186. package/lib/types.mjs +0 -133
  187. package/log-safety.mjs +0 -303
  188. package/module-layering.mjs +0 -270
  189. package/naming.mjs +0 -251
  190. package/observability.mjs +0 -241
  191. package/resilience.mjs +0 -304
  192. package/service-isolation.mjs +0 -75
  193. package/spec-no-skip.mjs +0 -85
  194. package/testing.mjs +0 -384
  195. package/type-safety.mjs +0 -323
@@ -0,0 +1,115 @@
1
+ import type { TSESTree } from "@typescript-eslint/utils";
2
+ import type { HfsConnection, HfsView } from "./hfs.js";
3
+ import type { Context, Node } from "./rule.js";
4
+ /** One place a class receives a dependency: a constructor parameter or a property, with its decorator names and type annotation. */
5
+ export interface InjectionSite {
6
+ readonly node: Node;
7
+ readonly kind: "param" | "property";
8
+ readonly decorators: string[];
9
+ readonly annotation: TSESTree.TypeNode | null;
10
+ }
11
+ /**
12
+ * PascalCase of a connection name: `expert-academy` gives `ExpertAcademy`.
13
+ *
14
+ * @param {string} name - A kebab-case connection name from `hfs.json`.
15
+ * @returns {string} The PascalCase form.
16
+ */
17
+ export declare const pascalOf: (name: unknown) => string;
18
+ /**
19
+ * The one injector name a declared connection owns.
20
+ *
21
+ * @param {string} connection - A connection name.
22
+ * @returns {string} `Inject<Pascal>EntityManager`.
23
+ */
24
+ export declare const injectorNameOf: (connection: string) => string;
25
+ /**
26
+ * The declared connections of the repository.
27
+ *
28
+ * @param {object} hfs - The HFS view of the repository.
29
+ * @returns {Array<{ name: string, envPrefix: string }>} The `hfs.json` connections.
30
+ */
31
+ export declare const connectionsOf: (hfs: HfsView) => readonly HfsConnection[];
32
+ /**
33
+ * The declared injector names, in declaration order.
34
+ *
35
+ * @param {object} hfs - The HFS view of the repository.
36
+ * @returns {Array<string>} One `Inject<Pascal>EntityManager` per declared connection.
37
+ */
38
+ export declare const declaredInjectorNames: (hfs: HfsView) => string[];
39
+ /**
40
+ * The last segment of a path.
41
+ *
42
+ * @param {string} filename - A file path.
43
+ * @returns {string} The base name.
44
+ */
45
+ export declare const baseNameOf: (filename: string) => string;
46
+ /**
47
+ * Whether a file belongs to the platform database capability.
48
+ *
49
+ * @param {object} hfs - The HFS view of the repository.
50
+ * @param {string} file - A file path.
51
+ * @returns {boolean} True for `be.platform` files of the `database` capability.
52
+ */
53
+ export declare const inDatabaseCapability: (hfs: HfsView, file: string) => boolean;
54
+ /**
55
+ * Whether a file is the command line of the back end: the cli app (slot `be.app.cli`) or the cli feature root (slot `be.cli`,
56
+ * `src/features/cli/`), where every one-off action runs, the migrate and seed commands among them.
57
+ *
58
+ * @param {object} hfs - The HFS view of the repository.
59
+ * @param {string} file - A file path.
60
+ * @returns {boolean} True for the files of the cli app and the cli feature root.
61
+ */
62
+ export declare const inCli: (hfs: HfsView, file: string) => boolean;
63
+ /**
64
+ * Whether a file is a migration: a `be.persistence` file below its `migrations/` folder.
65
+ *
66
+ * @param {object} hfs - The HFS view of the repository.
67
+ * @param {string} file - A file path.
68
+ * @returns {boolean} True for a migration file.
69
+ */
70
+ export declare const isMigrationFile: (hfs: HfsView, file: string) => boolean;
71
+ /**
72
+ * The connection a `<conn>.<role>.ts` file of the database capability is about, when that connection is declared.
73
+ *
74
+ * @param {object} hfs - The HFS view of the repository.
75
+ * @param {string} file - A file path.
76
+ * @param {string} role - `decorators`, `connection` or `config`.
77
+ * @returns {{ name: string, envPrefix: string } | null} The declared connection, or null.
78
+ */
79
+ export declare const connectionFileOf: (hfs: HfsView, file: string, role: string) => HfsConnection | null;
80
+ /**
81
+ * Whether a class in this file may receive an `EntityManager`: an application handler, a domain service, a projection, a typed queue producer (it takes the transaction of its caller), a platform persistence capability.
82
+ *
83
+ * @param {object} hfs - The HFS view of the repository.
84
+ * @param {string} file - A file path.
85
+ * @returns {boolean} True for the EntityManager-using service roles.
86
+ */
87
+ export declare const mayHoldEntityManager: (hfs: HfsView, file: string) => boolean;
88
+ /**
89
+ * The `typeorm` infrastructure type of a node (`EntityManager`, `DataSource`, `QueryRunner`), by type and not by name.
90
+ *
91
+ * @param {object} context - The ESLint rule context.
92
+ * @param {object} node - An expression, parameter or type annotation node.
93
+ * @returns {string | null} The type name, or null when the node is none of them.
94
+ */
95
+ export declare const infraTypeOf: (context: Context, node: Node) => string | null;
96
+ /**
97
+ * Whether a class is a TypeORM migration: it implements the `MigrationInterface` typeorm declares. A migration receives a
98
+ * `QueryRunner` by contract, wherever the file sits (a fixture migration is one too).
99
+ *
100
+ * @param {object} context - The ESLint rule context.
101
+ * @param {object} classNode - A ClassDeclaration or ClassExpression.
102
+ * @returns {boolean} True when the class implements typeorm's `MigrationInterface`.
103
+ */
104
+ export declare const implementsMigration: (context: Context, classNode: TSESTree.ClassDeclaration | TSESTree.ClassExpression) => boolean;
105
+ /**
106
+ * The visitors that find every place a class receives a value: a constructor parameter (a parameter property included)
107
+ * or a class property. Each place is handed to `handle` with its decorators and its type annotation.
108
+ *
109
+ * @param {(site: { node: object, kind: "param" | "property", decorators: Array<string>, annotation: object | null }) => void} handle - Called once per site.
110
+ * @returns {object} The ESLint visitors.
111
+ */
112
+ export declare const injectionSites: (handle: (site: InjectionSite) => void) => {
113
+ MethodDefinition(node: TSESTree.MethodDefinition): void;
114
+ PropertyDefinition(node: TSESTree.PropertyDefinition): void;
115
+ };
@@ -5,54 +5,46 @@
5
5
  * Nothing here matches a path or a variable name. A receiver is an `EntityManager` because its TypeScript type is
6
6
  * `typeorm`'s; a file is the database capability's because the HFS slot manifest says so.
7
7
  */
8
- import { normalizePath } from "./path.mjs"
9
- import { ownerNameOf } from "./ports.mjs"
10
- import { typeOrigins } from "./types.mjs"
11
-
8
+ import { normalizePath } from "./path.js";
9
+ import { ownerNameOf } from "./ports.js";
10
+ import { typeOrigins } from "./types.js";
12
11
  /** The `typeorm` types a class must never receive except through the platform database capability. */
13
- const INFRA_TYPES = new Set(["EntityManager", "DataSource", "QueryRunner"])
14
-
12
+ const INFRA_TYPES = new Set(["EntityManager", "DataSource", "QueryRunner"]);
15
13
  /**
16
14
  * PascalCase of a connection name: `expert-academy` gives `ExpertAcademy`.
17
15
  *
18
16
  * @param {string} name - A kebab-case connection name from `hfs.json`.
19
17
  * @returns {string} The PascalCase form.
20
18
  */
21
- export const pascalOf = (name) =>
22
- String(name).split(/[-_]/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join("")
23
-
19
+ export const pascalOf = (name) => String(name).split(/[-_]/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
24
20
  /**
25
21
  * The one injector name a declared connection owns.
26
22
  *
27
23
  * @param {string} connection - A connection name.
28
24
  * @returns {string} `Inject<Pascal>EntityManager`.
29
25
  */
30
- export const injectorNameOf = (connection) => `Inject${pascalOf(connection)}EntityManager`
31
-
26
+ export const injectorNameOf = (connection) => `Inject${pascalOf(connection)}EntityManager`;
32
27
  /**
33
28
  * The declared connections of the repository.
34
29
  *
35
30
  * @param {object} hfs - The HFS view of the repository.
36
31
  * @returns {Array<{ name: string, envPrefix: string }>} The `hfs.json` connections.
37
32
  */
38
- export const connectionsOf = (hfs) => hfs.connections ?? []
39
-
33
+ export const connectionsOf = (hfs) => hfs.connections ?? [];
40
34
  /**
41
35
  * The declared injector names, in declaration order.
42
36
  *
43
37
  * @param {object} hfs - The HFS view of the repository.
44
38
  * @returns {Array<string>} One `Inject<Pascal>EntityManager` per declared connection.
45
39
  */
46
- export const declaredInjectorNames = (hfs) => connectionsOf(hfs).map((connection) => injectorNameOf(connection.name))
47
-
40
+ export const declaredInjectorNames = (hfs) => connectionsOf(hfs).map((connection) => injectorNameOf(connection.name));
48
41
  /**
49
42
  * The last segment of a path.
50
43
  *
51
44
  * @param {string} filename - A file path.
52
45
  * @returns {string} The base name.
53
46
  */
54
- export const baseNameOf = (filename) => normalizePath(filename).split("/").pop()
55
-
47
+ export const baseNameOf = (filename) => normalizePath(filename).split("/").pop() ?? "";
56
48
  /**
57
49
  * Whether a file belongs to the platform database capability.
58
50
  *
@@ -61,10 +53,9 @@ export const baseNameOf = (filename) => normalizePath(filename).split("/").pop()
61
53
  * @returns {boolean} True for `be.platform` files of the `database` capability.
62
54
  */
63
55
  export const inDatabaseCapability = (hfs, file) => {
64
- const found = hfs.classify(file)
65
- return found.slot === "be.platform" && found.bindings?.capability === "database"
66
- }
67
-
56
+ const found = hfs.classify(file);
57
+ return found.slot === "be.platform" && found.bindings?.capability === "database";
58
+ };
68
59
  /**
69
60
  * Whether a file is the command line of the back end: the cli app (slot `be.app.cli`) or the cli feature root (slot `be.cli`,
70
61
  * `src/features/cli/`), where every one-off action runs, the migrate and seed commands among them.
@@ -73,8 +64,7 @@ export const inDatabaseCapability = (hfs, file) => {
73
64
  * @param {string} file - A file path.
74
65
  * @returns {boolean} True for the files of the cli app and the cli feature root.
75
66
  */
76
- export const inCli = (hfs, file) => hfs.slotOf(file) === "be.app.cli" || hfs.slotOf(file) === "be.cli"
77
-
67
+ export const inCli = (hfs, file) => hfs.slotOf(file) === "be.app.cli" || hfs.slotOf(file) === "be.cli";
78
68
  /**
79
69
  * Whether a file is a migration: a `be.persistence` file below its `migrations/` folder.
80
70
  *
@@ -83,10 +73,9 @@ export const inCli = (hfs, file) => hfs.slotOf(file) === "be.app.cli" || hfs.slo
83
73
  * @returns {boolean} True for a migration file.
84
74
  */
85
75
  export const isMigrationFile = (hfs, file) => {
86
- const found = hfs.classify(file)
87
- return found.slot === "be.persistence" && hfs.relative(file).startsWith(`${found.root}/migrations/`)
88
- }
89
-
76
+ const found = hfs.classify(file);
77
+ return found.slot === "be.persistence" && hfs.relative(file).startsWith(`${found.root}/migrations/`);
78
+ };
90
79
  /**
91
80
  * The connection a `<conn>.<role>.ts` file of the database capability is about, when that connection is declared.
92
81
  *
@@ -96,17 +85,17 @@ export const isMigrationFile = (hfs, file) => {
96
85
  * @returns {{ name: string, envPrefix: string } | null} The declared connection, or null.
97
86
  */
98
87
  export const connectionFileOf = (hfs, file, role) => {
99
- if (!inDatabaseCapability(hfs, file)) return null
100
- const suffix = `.${role}.ts`
101
- const base = baseNameOf(file)
102
- if (!base.endsWith(suffix)) return null
103
- const name = base.slice(0, -suffix.length)
104
- return connectionsOf(hfs).find((connection) => connection.name === name) ?? null
105
- }
106
-
88
+ if (!inDatabaseCapability(hfs, file))
89
+ return null;
90
+ const suffix = `.${role}.ts`;
91
+ const base = baseNameOf(file);
92
+ if (!base.endsWith(suffix))
93
+ return null;
94
+ const name = base.slice(0, -suffix.length);
95
+ return connectionsOf(hfs).find((connection) => connection.name === name) ?? null;
96
+ };
107
97
  /** The platform capabilities that own a `persistence/` and so may hold an `EntityManager` (a pattern capability is named by its folder). */
108
- const PERSISTENCE_CAPABILITIES = ["database", "inbox", "event-bus", "queue", "jobs", "saga", "outbox", "realtime"]
109
-
98
+ const PERSISTENCE_CAPABILITIES = ["database", "inbox", "event-bus", "queue", "jobs", "saga", "outbox", "realtime"];
110
99
  /**
111
100
  * Whether a class in this file may receive an `EntityManager`: an application handler, a domain service, a projection, a typed queue producer (it takes the transaction of its caller), a platform persistence capability.
112
101
  *
@@ -115,15 +104,18 @@ const PERSISTENCE_CAPABILITIES = ["database", "inbox", "event-bus", "queue", "jo
115
104
  * @returns {boolean} True for the EntityManager-using service roles.
116
105
  */
117
106
  export const mayHoldEntityManager = (hfs, file) => {
118
- const found = hfs.classify(file)
119
- const base = baseNameOf(file)
120
- if (found.slot === "be.feature.application") return base.endsWith(".handler.ts")
121
- if (found.slot === "be.domain") return base.endsWith(".service.ts")
122
- if (found.slot === "be.projections") return base.endsWith(".projection.ts")
123
- if (found.slot === "be.queues") return base.endsWith(".queue.ts")
124
- return typeof found.slot === "string" && found.slot.startsWith("be.platform") && PERSISTENCE_CAPABILITIES.includes(ownerNameOf(hfs, file))
125
- }
126
-
107
+ const found = hfs.classify(file);
108
+ const base = baseNameOf(file);
109
+ if (found.slot === "be.feature.application")
110
+ return base.endsWith(".handler.ts");
111
+ if (found.slot === "be.domain")
112
+ return base.endsWith(".service.ts");
113
+ if (found.slot === "be.projections")
114
+ return base.endsWith(".projection.ts");
115
+ if (found.slot === "be.queues")
116
+ return base.endsWith(".queue.ts");
117
+ return typeof found.slot === "string" && found.slot.startsWith("be.platform") && PERSISTENCE_CAPABILITIES.includes(ownerNameOf(hfs, file));
118
+ };
127
119
  /**
128
120
  * The `typeorm` infrastructure type of a node (`EntityManager`, `DataSource`, `QueryRunner`), by type and not by name.
129
121
  *
@@ -132,10 +124,9 @@ export const mayHoldEntityManager = (hfs, file) => {
132
124
  * @returns {string | null} The type name, or null when the node is none of them.
133
125
  */
134
126
  export const infraTypeOf = (context, node) => {
135
- const origin = typeOrigins(context, node).find((entry) => entry.module === "typeorm" && INFRA_TYPES.has(entry.name))
136
- return origin ? origin.name : null
137
- }
138
-
127
+ const origin = typeOrigins(context, node).find((entry) => entry.module === "typeorm" && INFRA_TYPES.has(entry.name));
128
+ return origin ? origin.name : null;
129
+ };
139
130
  /**
140
131
  * Whether a class is a TypeORM migration: it implements the `MigrationInterface` typeorm declares. A migration receives a
141
132
  * `QueryRunner` by contract, wherever the file sits (a fixture migration is one too).
@@ -144,17 +135,14 @@ export const infraTypeOf = (context, node) => {
144
135
  * @param {object} classNode - A ClassDeclaration or ClassExpression.
145
136
  * @returns {boolean} True when the class implements typeorm's `MigrationInterface`.
146
137
  */
147
- export const implementsMigration = (context, classNode) =>
148
- (classNode.implements ?? []).some((entry) => typeOrigins(context, entry).some((origin) => origin.module === "typeorm" && origin.name === "MigrationInterface"))
149
-
138
+ export const implementsMigration = (context, classNode) => (classNode.implements ?? []).some((entry) => typeOrigins(context, entry).some((origin) => origin.module === "typeorm" && origin.name === "MigrationInterface"));
150
139
  /** The decorator names written on a node: `@Foo()` and `@Foo` both give `Foo`. */
151
- const decoratorNamesOf = (node) =>
152
- (node.decorators ?? []).flatMap((decorator) => {
153
- const expression = decorator.expression
154
- if (expression.type === "CallExpression" && expression.callee.type === "Identifier") return [expression.callee.name]
155
- return expression.type === "Identifier" ? [expression.name] : []
156
- })
157
-
140
+ const decoratorNamesOf = (node) => (node.decorators ?? []).flatMap((decorator) => {
141
+ const expression = decorator.expression;
142
+ if (expression.type === "CallExpression" && expression.callee.type === "Identifier")
143
+ return [expression.callee.name];
144
+ return expression.type === "Identifier" ? [expression.name] : [];
145
+ });
158
146
  /**
159
147
  * The visitors that find every place a class receives a value: a constructor parameter (a parameter property included)
160
148
  * or a class property. Each place is handed to `handle` with its decorators and its type annotation.
@@ -164,19 +152,20 @@ const decoratorNamesOf = (node) =>
164
152
  */
165
153
  export const injectionSites = (handle) => ({
166
154
  MethodDefinition(node) {
167
- if (node.kind !== "constructor" || !node.value?.params) return
155
+ if (node.kind !== "constructor" || !node.value?.params)
156
+ return;
168
157
  for (const original of node.value.params) {
169
- const wrapped = original.type === "TSParameterProperty" ? original.parameter : original
170
- const param = wrapped.type === "AssignmentPattern" ? wrapped.left : wrapped
158
+ const wrapped = original.type === "TSParameterProperty" ? original.parameter : original;
159
+ const param = wrapped.type === "AssignmentPattern" ? wrapped.left : wrapped;
171
160
  handle({
172
161
  node: param,
173
162
  kind: "param",
174
163
  decorators: [...decoratorNamesOf(original), ...decoratorNamesOf(param)],
175
164
  annotation: param.typeAnnotation?.typeAnnotation ?? null,
176
- })
165
+ });
177
166
  }
178
167
  },
179
168
  PropertyDefinition(node) {
180
- handle({ node, kind: "property", decorators: decoratorNamesOf(node), annotation: node.typeAnnotation?.typeAnnotation ?? null })
169
+ handle({ node, kind: "property", decorators: decoratorNamesOf(node), annotation: node.typeAnnotation?.typeAnnotation ?? null });
181
170
  },
182
- })
171
+ });
@@ -0,0 +1,70 @@
1
+ import type { Context } from "./rule.js";
2
+ import type { HfsView } from "./hfs.js";
3
+ import type { TSESTree } from "@typescript-eslint/utils";
4
+ import type { Node } from "./rule.js";
5
+ /** The last segment of a forward-slash path. */
6
+ export declare const baseName: (file: string) => string;
7
+ /**
8
+ * The capability or feature an HFS slot binds a file to (`logging` for `src/modules/platform/logging/x.ts`), or null.
9
+ *
10
+ * @param {object} hfs - The HFS view.
11
+ * @param {string} file - A file path.
12
+ * @returns {string | null} The owner name the slot binds.
13
+ */
14
+ export declare const ownerNameOf: (hfs: HfsView, file: string) => string | null | undefined;
15
+ /** A migration: a file of slot `be.persistence` below its `migrations/` folder - the one place schema-changing SQL may be written. */
16
+ export declare const isMigrationFile: (hfs: HfsView, file: string) => boolean;
17
+ /** True when the file belongs to the named capability of the named tier (`platform`, `clock`). */
18
+ export declare const isOwnedBy: (hfs: HfsView, file: string, tier: string | null, capability: string | null | undefined) => boolean;
19
+ /**
20
+ * True when the node's type is `name` declared inside the repository by the given owner (a platform port, a brand).
21
+ *
22
+ * @param {object} context - The ESLint rule context.
23
+ * @param {object} node - The expression or type node to type.
24
+ * @param {{ name: string, capability: string, tier?: string }} owner - The declared name and its owner; without `tier` any tier matches.
25
+ * @returns {boolean} Whether one of the node's type origins matches.
26
+ */
27
+ export declare const isOwnedType: (context: Context, node: Node, { name, capability, tier }: {
28
+ name: string;
29
+ capability: string;
30
+ tier?: string;
31
+ }) => boolean;
32
+ /** The `Logger` port of `platform/logging`. */
33
+ export declare const isLoggerType: (context: Context, node: Node) => boolean;
34
+ /**
35
+ * True when the call is `<receiver>.<method>(...)` on a receiver typed as the `Logger` port.
36
+ *
37
+ * @param {object} context - The ESLint rule context.
38
+ * @param {object} node - A CallExpression.
39
+ * @returns {boolean} Whether it is a logger call.
40
+ */
41
+ export declare const isLoggerCall: (context: Context, node: TSESTree.CallExpression) => boolean;
42
+ /**
43
+ * The enums a node's value belongs to, when its type is an enum member, an enum, or a union of members.
44
+ *
45
+ * @param {object} context - The ESLint rule context.
46
+ * @param {object} node - The expression to type.
47
+ * @returns {Array<{ name: string, file: string }> | null} One entry per enum, or null when any part of the type is not an enum member.
48
+ */
49
+ export declare const enumsOf: (context: Context, node: Node) => {
50
+ name: string;
51
+ file: string;
52
+ }[] | null;
53
+ /**
54
+ * The name of the enum member an expression is, when its type is one enum-literal type (`PublicReason.SignedWebhook`).
55
+ *
56
+ * @param {object} context - The ESLint rule context.
57
+ * @param {object} node - The expression to type.
58
+ * @returns {{ enumName: string, member: string } | null} The enum and the member, or null.
59
+ */
60
+ export declare const enumMemberOf: (context: Context, node: Node) => {
61
+ enumName: string;
62
+ member: string;
63
+ } | null;
64
+ /**
65
+ * 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.
66
+ *
67
+ * @param {string} file - A declaration file path.
68
+ * @returns {string | null} The package name.
69
+ */
70
+ export declare const packageOfFile: (file: string) => string | null;
@@ -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");