@starci/eslint-canon-be 3.4.57 → 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 (197) hide show
  1. package/CHANGELOG.md +19 -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 +22 -14
  177. package/runtime/knowledge/hfs/rules.yaml +23 -0
  178. package/runtime/scripts/lib/package-at.mjs +5 -5
  179. package/async-discipline.mjs +0 -83
  180. package/comments.mjs +0 -416
  181. package/edge-hardening.mjs +0 -139
  182. package/health-ready.mjs +0 -539
  183. package/jwt-alg.mjs +0 -45
  184. package/lib/ast.mjs +0 -88
  185. package/lib/import-source.mjs +0 -104
  186. package/lib/specifier.mjs +0 -27
  187. package/lib/subject-values.mjs +0 -55
  188. package/lib/types.mjs +0 -133
  189. package/log-safety.mjs +0 -303
  190. package/module-layering.mjs +0 -270
  191. package/naming.mjs +0 -251
  192. package/observability.mjs +0 -241
  193. package/resilience.mjs +0 -304
  194. package/service-isolation.mjs +0 -75
  195. package/spec-no-skip.mjs +0 -85
  196. package/testing.mjs +0 -384
  197. package/type-safety.mjs +0 -323
package/naming.mjs DELETED
@@ -1,251 +0,0 @@
1
- /**
2
- * The rules that hold `naming.md`.
3
- *
4
- * Three rules, which are the parts of naming a parser can actually judge: whether a name encodes a
5
- * schema VERSION, whether an exported function is a bare verb, and whether a `.module.ts` file's
6
- * OWN static factory borrows a vendor dynamic-module's exact name instead of this tree's `register`.
7
- *
8
- * `no-default-export` (BE-CONVENTION 1.15, R89) is the form rule beside them: named exports only, with one Jest
9
- * `global-setup.ts`/`global-teardown.ts` of slot `be.tests.world` (the Jest globalSetup API) as the single default export.
10
- *
11
- * A FOURTH RULE WAS WRITTEN AND DELETED, and the deletion is the useful part. It demanded that a
12
- * file name spell out the class it declares, and measured 616 offenders in 4430 files -- because
13
- * the convention is the opposite of what it assumed: the PATH carries the role and the scope
14
- * (`parsers/content.service.ts` and `path/content.service.ts` declare `ContentParserService` and
15
- * `ContentPathService`), and the file names only the subject. Fourteen percent of a tree is a
16
- * convention, not debt. Canon records what the code does; a rule that disagrees with the code at
17
- * that scale is the rule being wrong.
18
- *
19
- * The module-factory rule (NAME-1) stays narrow on purpose: it visits DECLARATIONS only -- a static
20
- * method on a class this repository declares, decorated `@Module(...)` -- and never a CallExpression,
21
- * so `BullModule.forRoot(...)`, `ConfigModule.forRoot(...)`, `TypeOrmModule.forFeature(...)` and
22
- * `SentryCoreModule.forRoot(...)` are calls into vendor code and are never reported. Its forbidden
23
- * set is closed to the four literal vendor names (`forRoot`, `forRootAsync`, `forFeature`,
24
- * `forFeatureAsync`); a repository-invented auxiliary factory like `registerQueue` does not collide
25
- * with a vendor shape and is left alone.
26
- *
27
- * The rest of the law is not enforced and should not be faked. Whether a name describes a folder
28
- * (NAME-3), a mechanism (NAME-4) or its first caller (NAME-7) needs to know what the thing IS --
29
- * `VolumeService` reads perfectly well until you know the folder was renamed, and no parser knows
30
- * that. Those are read by a person, which is why the law states them with the scars attached.
31
- */
32
-
33
- import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
34
- import { normalizePath } from "./lib/path.mjs"
35
-
36
- /** A schema generation baked into an identifier. */
37
- const VERSIONED_NAME = /(?:^|[a-z])V[0-9]+(?:$|[A-Z_])|_V[0-9]+/
38
-
39
- /** Bare verbs that say nothing about their object. */
40
- const BARE_VERBS = new Set([
41
- "generate",
42
- "parse",
43
- "run",
44
- "handle",
45
- "process",
46
- "build",
47
- "create",
48
- "load",
49
- "resolve",
50
- "check",
51
- "convert",
52
- "transform",
53
- "send",
54
- "fetch",
55
- "get",
56
- "set",
57
- "update",
58
- "apply",
59
- ])
60
-
61
- // -- NAME-1 ----------------------------------------------------------------------------------------
62
-
63
- /** Decorator names carried by a class declaration. */
64
- const decoratorNames = (node) =>
65
- (node.decorators || []).map((decorator) => {
66
- const expression = decorator.expression
67
- if (expression.type === "CallExpression" && expression.callee.type === "Identifier") return expression.callee.name
68
- if (expression.type === "Identifier") return expression.name
69
- return null
70
- }).filter(Boolean)
71
-
72
- /**
73
- * Vendor dynamic-module factory names, each mapped to the house name a `.module.ts` file's own
74
- * factory declares instead: `register`, or `registerAsync` for its async companion.
75
- *
76
- * This is a CLOSED list of the exact method names Nest's own modules publish
77
- * (`ConfigModule.forRoot`, `TypeOrmModule.forFeature`, `BullModule.forRootAsync`,
78
- * `SentryCoreModule.forRoot`). A repository class that declares its OWN static factory under one of
79
- * these names is not calling the vendor - it is shaped like the vendor, which is exactly what makes
80
- * `PrimaryPostgreSQLModule.forFeature()` unreadable at a glance from `TypeOrmModule.forFeature()`:
81
- * same literal name, two different owners, and nothing at the call site says which.
82
- */
83
- const VENDOR_FACTORY_NAMES = new Map([
84
- ["forRoot", "register"],
85
- ["forRootAsync", "registerAsync"],
86
- ["forFeature", "register"],
87
- ["forFeatureAsync", "registerAsync"],
88
- ])
89
-
90
- /** A `.module.ts` file's own static factory is named `register`, never a vendor's factory shape. */
91
- export const noVendorModuleFactoryName = {
92
- meta: {
93
- type: "problem",
94
- docs: {
95
- description:
96
- "NAME-1: a `.module.ts` file's own static factory is named `register` (`registerAsync` for its async companion), never a vendor dynamic-module name it does not own.",
97
- },
98
- schema: [],
99
- messages: {
100
- vendorShaped:
101
- "`{{name}}` is a module declared IN THIS REPOSITORY, but its static factory is named `{{method}}` - the exact name Nest's own vendor modules publish (`ConfigModule.forRoot`, `TypeOrmModule.forFeature`, `BullModule.forRootAsync`). A reader hitting `{{name}}.{{method}}(...)` in an `imports:` list cannot tell, from the name alone, whether that call lands in this class or forwards straight into a vendor's. Thirty-nine other modules in this tree already answer that question by calling this factory `{{suggestion}}` instead - a name no vendor already owns. Rename `{{method}}` to `{{suggestion}}`.",
102
- },
103
- },
104
- create(context) {
105
- return {
106
- MethodDefinition(node) {
107
- if (!node.static) return
108
- if (!node.key || node.key.type !== "Identifier") return
109
- const suggestion = VENDOR_FACTORY_NAMES.get(node.key.name)
110
- if (!suggestion) return
111
-
112
- const classBody = node.parent
113
- const classNode = classBody && classBody.parent
114
- if (!classNode || !decoratorNames(classNode).includes("Module")) return
115
-
116
- const name = (classNode.id && classNode.id.name) || "this module"
117
- context.report({
118
- node: node.key,
119
- messageId: "vendorShaped",
120
- data: { name, method: node.key.name, suggestion },
121
- })
122
- },
123
- }
124
- },
125
- }
126
-
127
- // -- NAME-2 ----------------------------------------------------------------------------------------
128
-
129
- /** A name says what a thing is, never which schema generation it was built for. */
130
- export const noVersionInName = {
131
- meta: {
132
- type: "problem",
133
- docs: { description: "Identifiers do not encode a schema version." },
134
- schema: [],
135
- messages: {
136
- versioned:
137
- "`{{name}}` bakes a schema generation into the name. It has to be renamed the day the next one arrives, and until then nobody can tell from the name whether it means the CURRENT shape or an old one -- so every reader goes and finds out. Name the property that generation introduced instead: `hasVerifiedMarker`, not `isV2`.",
138
- },
139
- },
140
- create(context) {
141
- const report = (node, name) => {
142
- if (!name || !VERSIONED_NAME.test(name)) return
143
- context.report({ node, messageId: "versioned", data: { name } })
144
- }
145
- return {
146
- FunctionDeclaration(node) {
147
- if (node.id) report(node.id, node.id.name)
148
- },
149
- ClassDeclaration(node) {
150
- if (node.id) report(node.id, node.id.name)
151
- },
152
- TSInterfaceDeclaration(node) {
153
- if (node.id) report(node.id, node.id.name)
154
- },
155
- TSTypeAliasDeclaration(node) {
156
- if (node.id) report(node.id, node.id.name)
157
- },
158
- MethodDefinition(node) {
159
- if (node.key && node.key.type === "Identifier") report(node.key, node.key.name)
160
- },
161
- }
162
- },
163
- }
164
-
165
- // -- NAME-5 ----------------------------------------------------------------------------------------
166
-
167
- /** An exported function is a verb plus its object. */
168
- export const noBareVerbExport = {
169
- meta: {
170
- type: "problem",
171
- docs: { description: "An exported function names its object, not just its verb." },
172
- schema: [],
173
- messages: {
174
- bareVerb:
175
- "`{{name}}` is a bare verb: {{name}} WHAT? At an import list it collides with every other module's `{{name}}`, so the reader falls back on reading the path to tell them apart -- and the path is the thing that moves. Give it its object.",
176
- },
177
- },
178
- create(context) {
179
- const check = (node, name) => {
180
- if (!name || !BARE_VERBS.has(name)) return
181
- context.report({ node, messageId: "bareVerb", data: { name } })
182
- }
183
- return {
184
- ExportNamedDeclaration(node) {
185
- const declaration = node.declaration
186
- if (!declaration) return
187
- if (declaration.type === "FunctionDeclaration" && declaration.id) {
188
- check(declaration.id, declaration.id.name)
189
- return
190
- }
191
- if (declaration.type !== "VariableDeclaration") return
192
- for (const one of declaration.declarations) {
193
- const init = one.init
194
- const isFunction = init
195
- && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")
196
- if (isFunction && one.id && one.id.type === "Identifier") check(one.id, one.id.name)
197
- }
198
- },
199
- }
200
- },
201
- }
202
-
203
- // -- no-default-export -------------------------------------------------------------------------------------------
204
-
205
- /** The one file kind that may default-export: a Jest global setup, whose API is a default function. */
206
- const isGlobalSetup = (context) => inTestWorld(hfsOf(context), context.filename) && /\/global-(?:setup|teardown)\.ts$/.test(normalizePath(context.filename))
207
-
208
- /** Named exports only: a default export has no name to grep, rename or import-check. */
209
- export const noDefaultExport = {
210
- meta: {
211
- type: "problem",
212
- docs: { description: "TypeScript source uses named exports only; the Jest global setup is the one exception." },
213
- schema: [],
214
- messages: {
215
- default:
216
- "A default export has no name of its own: every importer picks one, renames and greps stop working, and the file cannot be found by what it exports. Use a named export. (The only default export is the Jest `global-setup.ts`/`global-teardown.ts` of the e2e world, whose API requires it.)",
217
- },
218
- },
219
- create(context) {
220
- if (!/\.[cm]?ts$/.test(normalizePath(context.filename))) return {}
221
- if (isGlobalSetup(context)) return {}
222
- const isDefault = (name) => name && ((name.type === "Identifier" && name.name === "default") || (name.type === "Literal" && name.value === "default"))
223
- return {
224
- ExportDefaultDeclaration(node) {
225
- context.report({ node, messageId: "default" })
226
- },
227
- TSExportAssignment(node) {
228
- context.report({ node, messageId: "default" })
229
- },
230
- ExportSpecifier(node) {
231
- if (isDefault(node.exported) || (node.parent.source && isDefault(node.local))) context.report({ node, messageId: "default" })
232
- },
233
- }
234
- },
235
- }
236
-
237
- /** The rules this law contributes to the plugin. */
238
- export const rules = {
239
- "no-version-in-name": noVersionInName,
240
- "no-bare-verb-export": noBareVerbExport,
241
- "no-vendor-module-factory-name": noVendorModuleFactoryName,
242
- "no-default-export": noDefaultExport,
243
- }
244
-
245
- /** Every rule of this law at `error`. */
246
- export const recommended = {
247
- "starci-be/no-version-in-name": "error",
248
- "starci-be/no-bare-verb-export": "error",
249
- "starci-be/no-vendor-module-factory-name": "error",
250
- "starci-be/no-default-export": "error",
251
- }
package/observability.mjs DELETED
@@ -1,241 +0,0 @@
1
- /**
2
- * The rules that hold `observability.md` (catalog R40 `BE_LOGGER_REQUIRED`, logging half).
3
- *
4
- * Three rules covering the three ways a log escapes the pipeline: the framework's own logger, a name fused with its
5
- * data, and a failure line whose identity is its wording. The logger is identified by its TYPE - the `Logger` port of
6
- * `platform/logging` - never by what a receiver or a method is called, so a renamed receiver, a property injection and
7
- * a lookalike class are all judged correctly.
8
- *
9
- * `no-console` is not reimplemented here: the standard rule already does it exactly, and shipping a second
10
- * implementation of a rule everybody has would be a maintenance cost with no gain. It is named in `recommended` so a
11
- * consuming repository switches it on with the others.
12
- *
13
- * OBSERVABILITY-4 and -5 are judgements a rule cannot make. Whether a log records a decision or merely an arrival
14
- * needs to know what the code is FOR, and no parser knows that.
15
- */
16
- import { hfsOf } from "./lib/hfs.mjs"
17
- import { baseName, enumsOf, isLoggerCall, isOwnedBy } from "./lib/ports.mjs"
18
- import { isPackageType } from "./lib/types.mjs"
19
-
20
- /** The framework loggers of `@nestjs/common` this replaces, by the names the package declares them under. */
21
- const FRAMEWORK_LOGGERS = Object.freeze(["Logger", "ConsoleLogger"])
22
-
23
- /** The package the framework loggers come from. */
24
- const FRAMEWORK_PACKAGE = "@nestjs/common"
25
-
26
- // -- OBSERVABILITY-1 -------------------------------------------------------------------------------
27
-
28
- /** Logs leave through the `Logger` port, never the framework's own logger. */
29
- export const noFrameworkLogger = {
30
- meta: {
31
- type: "problem",
32
- docs: { description: "Only the `Logger` port of `platform/logging` logs; the framework's `Logger` is refused." },
33
- schema: [],
34
- messages: {
35
- imported:
36
- "`{{name}}` from `{{pkg}}` bypasses the JSON-lines adapter, the `Clock` stamp and the event vocabulary every other line carries - the line is written in the right SHAPE and still arrives without them. Inject the `Logger` port (`@InjectLogger() private readonly logger: Logger`).",
37
- constructed:
38
- "`new {{name}}(...)` builds the framework logger through a local construction rather than the import. Inject the `Logger` port (`@InjectLogger() private readonly logger: Logger`).",
39
- extended:
40
- "This class extends the framework logger from `{{pkg}}`. Implement the `Logger` port of `platform/logging` instead.",
41
- },
42
- },
43
- create(context) {
44
- // the adapter of the port is the one place that may know how lines are written
45
- if (isOwnedBy(hfsOf(context), context.filename || context.getFilename(), "platform", "logging")) return {}
46
- const framework = (node) => FRAMEWORK_LOGGERS.some((name) => isPackageType(context, node, name, FRAMEWORK_PACKAGE))
47
- return {
48
- ImportDeclaration(node) {
49
- if (node.source.value !== FRAMEWORK_PACKAGE) return
50
- for (const specifier of node.specifiers || []) {
51
- if (specifier.type !== "ImportSpecifier") continue
52
- const imported = specifier.imported.name ?? specifier.imported.value
53
- if (FRAMEWORK_LOGGERS.includes(imported)) context.report({ node: specifier, messageId: "imported", data: { name: imported, pkg: FRAMEWORK_PACKAGE } })
54
- }
55
- },
56
- // judged by the type of what is built, so an aliased import or a namespace import cannot walk past the check above
57
- NewExpression(node) {
58
- if (framework(node)) context.report({ node, messageId: "constructed", data: { name: node.callee.name ?? node.callee.property?.name ?? "Logger" } })
59
- },
60
- "ClassDeclaration, ClassExpression"(node) {
61
- if (node.superClass && framework(node.superClass)) context.report({ node: node.superClass, messageId: "extended", data: { pkg: FRAMEWORK_PACKAGE } })
62
- },
63
- }
64
- },
65
- }
66
-
67
- // -- OBSERVABILITY-2 -------------------------------------------------------------------------------
68
-
69
- /** The event name is a member of an owner's log-event enum, never a string built at the call site. */
70
- export const noInterpolatedLogMessage = {
71
- meta: {
72
- type: "problem",
73
- docs: { description: "A `Logger` call's first argument is a member of an owner's `<owner>.log-events.ts` enum, not a built string." },
74
- schema: [],
75
- messages: {
76
- notEvent:
77
- "The first argument to `{{method}}(...)` names WHAT happened and must be a member of the owner's `<owner>.log-events.ts` enum. A string or a value of any other type fuses the name with the data, so the name stops being groupable and the data stops being queryable - and the day somebody rewords it, every dashboard built on it goes quiet. Pass the enum member, and put the variable part in the fields beside it.",
78
- wrongHome:
79
- "`{{enumName}}` is an enum, but not one declared in a `<owner>.log-events.ts` file. Log events are declared by the owner that emits them, in `<owner>.log-events.ts`, so each owner's vocabulary is found in one place.",
80
- },
81
- },
82
- create(context) {
83
- return {
84
- CallExpression(node) {
85
- if (!isLoggerCall(context, node)) return
86
- const first = node.arguments[0]
87
- if (!first) return
88
- const method = node.callee.property.name
89
- const enums = enumsOf(context, first)
90
- if (!enums) {
91
- context.report({ node: first, messageId: "notEvent", data: { method } })
92
- return
93
- }
94
- const stray = enums.find((entry) => !baseName(entry.file).endsWith(".log-events.ts"))
95
- if (stray) context.report({ node: first, messageId: "wrongHome", data: { enumName: stray.name } })
96
- },
97
- }
98
- },
99
- }
100
-
101
- /** Whether `node` is a bare reference to the caught error, by name. */
102
- const isIdentifierNamed = (node, name) => Boolean(node) && node.type === "Identifier" && node.name === name
103
-
104
- /** How each wording shape reads back to the author, keyed by the `kind` pushed in `scanErrorUsage`. */
105
- const WORDING_SHAPES = {
106
- message: (name) => `\`${name}.message\``,
107
- stringWrap: (name) => `\`String(${name})\``,
108
- template: (name) => `a template literal that interpolates \`${name}\` directly`,
109
- }
110
-
111
- /**
112
- * Walk a log call's data arguments for two things beside the caught error: a reference that carries
113
- * only its rendered WORDING (`.message`, `String(error)`, `${error}` inside a template), and a
114
- * reference that carries its IDENTITY (`.code`). The walk is a shallow recursion over the expression
115
- * shapes a data object is normally built from - object properties, array elements, template
116
- * expressions, ternary branches, boolean joins. It does not need a type checker: these three wording
117
- * shapes and the one identity shape are syntactic, not semantic, which is exactly the boundary
118
- * OBSERVABILITY-5 draws between what a parser can hold and what needs a reader.
119
- */
120
- const scanErrorUsage = (node, errorName, found) => {
121
- if (!node || typeof node !== "object" || typeof node.type !== "string") return
122
- switch (node.type) {
123
- case "MemberExpression":
124
- if (!node.computed && isIdentifierNamed(node.object, errorName) && node.property.type === "Identifier") {
125
- if (node.property.name === "message") found.wording.push({ node, kind: "message" })
126
- if (node.property.name === "code") found.identity.push(node)
127
- }
128
- scanErrorUsage(node.object, errorName, found)
129
- break
130
- case "CallExpression":
131
- if (
132
- node.callee.type === "Identifier" && node.callee.name === "String"
133
- && node.arguments.length === 1 && isIdentifierNamed(node.arguments[0], errorName)
134
- ) {
135
- found.wording.push({ node, kind: "stringWrap" })
136
- }
137
- for (const arg of node.arguments) scanErrorUsage(arg, errorName, found)
138
- break
139
- case "TemplateLiteral":
140
- for (const expr of node.expressions) {
141
- if (isIdentifierNamed(expr, errorName)) found.wording.push({ node: expr, kind: "template" })
142
- else scanErrorUsage(expr, errorName, found)
143
- }
144
- break
145
- case "ObjectExpression":
146
- for (const prop of node.properties) scanErrorUsage(prop, errorName, found)
147
- break
148
- case "Property":
149
- scanErrorUsage(node.value, errorName, found)
150
- break
151
- case "ArrayExpression":
152
- for (const el of node.elements) scanErrorUsage(el, errorName, found)
153
- break
154
- case "ConditionalExpression":
155
- scanErrorUsage(node.consequent, errorName, found)
156
- scanErrorUsage(node.alternate, errorName, found)
157
- break
158
- case "LogicalExpression":
159
- case "BinaryExpression":
160
- scanErrorUsage(node.left, errorName, found)
161
- scanErrorUsage(node.right, errorName, found)
162
- break
163
- default:
164
- break
165
- }
166
- }
167
-
168
- /**
169
- * A failure log's data carries the exception's `code`, not only its rendered message. Scoped to log
170
- * calls sitting inside a `catch`, and to references to that `catch`'s OWN error identifier - a field
171
- * that happens to be named `error` elsewhere is not this rule's business, and neither is a call
172
- * outside a `catch`, since OBSERVABILITY-5 only binds where the line is what an alert groups by.
173
- */
174
- export const noErrorWordingAsLogIdentity = {
175
- meta: {
176
- type: "problem",
177
- docs: {
178
- description:
179
- "OBSERVABILITY-5 (Rule 5): a failure log's data carries the exception's `code`, so improving the wording never splits an alert in two.",
180
- },
181
- schema: [],
182
- messages: {
183
- wordingOnly:
184
- "This failure log carries {{shape}} but never `{{errorName}}.code`. Wording is what a person reads; code is what a dashboard groups by. Fuse the two and the alert lives or dies on how the sentence happens to be phrased today - reword it tomorrow for clarity and the old alert goes silent while a new one opens under the reworded text. Add `{{errorName}}.code` (and any other identity metadata) to the data, and keep the message only as a secondary field beside it.",
185
- },
186
- },
187
- create(context) {
188
- const catchStack = []
189
- return {
190
- CatchClause(node) {
191
- catchStack.push(node.param && node.param.type === "Identifier" ? node.param.name : null)
192
- },
193
- "CatchClause:exit"() {
194
- catchStack.pop()
195
- },
196
- CallExpression(node) {
197
- const errorName = catchStack[catchStack.length - 1]
198
- if (!errorName) return
199
- if (!isLoggerCall(context, node)) return
200
-
201
- // the event name (first argument) is OBSERVABILITY-2's business, not this rule's
202
- const dataArgs = node.arguments.slice(1)
203
- if (dataArgs.length === 0) return
204
-
205
- const found = { wording: [], identity: [] }
206
- for (const arg of dataArgs) {
207
- // the caught error passed whole is the port's `cause`: the adapter serializes its name, so identity rides with it
208
- if (isIdentifierNamed(arg, errorName)) found.identity.push(arg)
209
- scanErrorUsage(arg, errorName, found)
210
- }
211
- if (found.wording.length > 0 && found.identity.length === 0) {
212
- const first = found.wording[0]
213
- context.report({
214
- node: first.node,
215
- messageId: "wordingOnly",
216
- data: { errorName, shape: WORDING_SHAPES[first.kind](errorName) },
217
- })
218
- }
219
- },
220
- }
221
- },
222
- }
223
-
224
- /** The rules this law contributes to the plugin. */
225
- export const rules = {
226
- "no-framework-logger": noFrameworkLogger,
227
- "no-interpolated-log-message": noInterpolatedLogMessage,
228
- "no-error-wording-as-log-identity": noErrorWordingAsLogIdentity,
229
- }
230
-
231
- /**
232
- * The level this law asks for, as the plugin's own opinion: every rule at `error`, no exemption list.
233
- *
234
- * `no-console` is the standard rule rather than a house one; the config factory borrows it (`lib/config.mjs`
235
- * BORROWED) so it is on wherever these three are.
236
- */
237
- export const recommended = {
238
- "starci-be/no-framework-logger": "error",
239
- "starci-be/no-interpolated-log-message": "error",
240
- "starci-be/no-error-wording-as-log-identity": "error",
241
- }