@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.
- package/CHANGELOG.md +21 -0
- package/README.md +13 -2
- package/dist/ambient-id.d.ts +9 -0
- package/{ambient-id.mjs → dist/ambient-id.js} +43 -39
- package/dist/app-composition.d.ts +21 -0
- package/{app-composition.mjs → dist/app-composition.js} +396 -300
- package/dist/async-discipline.d.ts +9 -0
- package/dist/async-discipline.js +77 -0
- package/dist/authorization.d.ts +12 -0
- package/{authorization.mjs → dist/authorization.js} +53 -59
- package/dist/boundary-schema.d.ts +15 -0
- package/{boundary-schema.mjs → dist/boundary-schema.js} +120 -105
- package/dist/builders.d.ts +21 -0
- package/{builders.mjs → dist/builders.js} +162 -146
- package/dist/cli.d.ts +15 -0
- package/{cli.mjs → dist/cli.js} +97 -82
- package/dist/comments.d.ts +52 -0
- package/dist/comments.js +412 -0
- package/dist/config-owner.d.ts +24 -0
- package/{config-owner.mjs → dist/config-owner.js} +256 -219
- package/dist/connections.d.ts +12 -0
- package/{connections.mjs → dist/connections.js} +138 -140
- package/dist/cookies.d.ts +9 -0
- package/{cookies.mjs → dist/cookies.js} +58 -58
- package/dist/cqrs.d.ts +27 -0
- package/{cqrs.mjs → dist/cqrs.js} +341 -282
- package/dist/data-access.d.ts +50 -0
- package/{data-access.mjs → dist/data-access.js} +238 -243
- package/dist/default-deny.d.ts +15 -0
- package/{default-deny.mjs → dist/default-deny.js} +103 -88
- package/dist/e2e-flow.d.ts +25 -0
- package/{e2e-flow.mjs → dist/e2e-flow.js} +113 -112
- package/dist/edge-hardening.d.ts +10 -0
- package/dist/edge-hardening.js +173 -0
- package/dist/error-handling.d.ts +21 -0
- package/{error-handling.mjs → dist/error-handling.js} +289 -239
- package/dist/event-bus.d.ts +14 -0
- package/{event-bus.mjs → dist/event-bus.js} +146 -129
- package/dist/feature-thin.d.ts +12 -0
- package/{feature-thin.mjs → dist/feature-thin.js} +208 -191
- package/dist/function-budget.d.ts +7 -0
- package/{function-budget.mjs → dist/function-budget.js} +24 -27
- package/dist/health-ready.d.ts +10 -0
- package/dist/health-ready.js +703 -0
- package/dist/idempotency.d.ts +10 -0
- package/{idempotency.mjs → dist/idempotency.js} +296 -226
- package/dist/index.d.ts +54 -0
- package/{index.mjs → dist/index.js} +91 -109
- package/dist/infra-owner.d.ts +18 -0
- package/{infra-owner.mjs → dist/infra-owner.js} +58 -51
- package/dist/injection.d.ts +30 -0
- package/{injection.mjs → dist/injection.js} +397 -344
- package/dist/input-bounds.d.ts +15 -0
- package/{input-bounds.mjs → dist/input-bounds.js} +143 -132
- package/dist/jobs.d.ts +17 -0
- package/{jobs.mjs → dist/jobs.js} +116 -99
- package/dist/jwt-alg.d.ts +6 -0
- package/dist/jwt-alg.js +49 -0
- package/dist/lib/app-roles.d.ts +25 -0
- package/{lib/app-roles.mjs → dist/lib/app-roles.js} +15 -17
- package/dist/lib/ast.d.ts +40 -0
- package/dist/lib/ast.js +100 -0
- package/dist/lib/client-idempotency.d.ts +3 -0
- package/{lib/client-idempotency.mjs → dist/lib/client-idempotency.js} +316 -268
- package/dist/lib/config.d.ts +36 -0
- package/{lib/config.mjs → dist/lib/config.js} +24 -27
- package/dist/lib/db-writes.d.ts +29 -0
- package/{lib/db-writes.mjs → dist/lib/db-writes.js} +27 -27
- package/dist/lib/declared.d.ts +77 -0
- package/{lib/declared.mjs → dist/lib/declared.js} +83 -78
- package/dist/lib/doors.d.ts +50 -0
- package/{lib/doors.mjs → dist/lib/doors.js} +45 -50
- package/dist/lib/edition.d.ts +25 -0
- package/{lib/edition.mjs → dist/lib/edition.js} +15 -20
- package/dist/lib/entity-writes.d.ts +7 -0
- package/{lib/entity-writes.mjs → dist/lib/entity-writes.js} +31 -22
- package/dist/lib/hfs-view.d.ts +127 -0
- package/dist/lib/hfs-view.js +1 -0
- package/dist/lib/hfs.d.ts +34 -0
- package/{lib/hfs.mjs → dist/lib/hfs.js} +31 -29
- package/dist/lib/import-source.d.ts +63 -0
- package/dist/lib/import-source.js +134 -0
- package/dist/lib/path.d.ts +8 -0
- package/{lib/path.mjs → dist/lib/path.js} +4 -7
- package/dist/lib/persistence.d.ts +115 -0
- package/{lib/persistence.mjs → dist/lib/persistence.js} +55 -66
- package/dist/lib/ports.d.ts +70 -0
- package/{lib/ports.mjs → dist/lib/ports.js} +62 -66
- package/dist/lib/rule.d.ts +31 -0
- package/dist/lib/rule.js +2 -0
- package/dist/lib/runtime-root.d.ts +4 -0
- package/dist/lib/runtime-root.js +10 -0
- package/dist/lib/schema-values.d.ts +13 -0
- package/{lib/schema-values.mjs → dist/lib/schema-values.js} +67 -59
- package/dist/lib/specifier.d.ts +12 -0
- package/dist/lib/specifier.js +29 -0
- package/dist/lib/subject-values.d.ts +4 -0
- package/dist/lib/subject-values.js +61 -0
- package/dist/lib/transactions.d.ts +18 -0
- package/{lib/transactions.mjs → dist/lib/transactions.js} +17 -15
- package/dist/lib/transport-slots.d.ts +17 -0
- package/{lib/transport-slots.mjs → dist/lib/transport-slots.js} +2 -4
- package/dist/lib/types.d.ts +96 -0
- package/dist/lib/types.js +150 -0
- package/dist/lib/unit-spec.d.ts +48 -0
- package/{lib/unit-spec.mjs → dist/lib/unit-spec.js} +35 -44
- package/dist/lib/webhook-ack.d.ts +4 -0
- package/{lib/webhook-ack.mjs → dist/lib/webhook-ack.js} +78 -62
- package/dist/lib/webhook-handoff-inbox.d.ts +3 -0
- package/{lib/webhook-handoff-inbox.mjs → dist/lib/webhook-handoff-inbox.js} +195 -167
- package/dist/lib/webhook-handoff-intake.d.ts +4 -0
- package/{lib/webhook-handoff-intake.mjs → dist/lib/webhook-handoff-intake.js} +125 -102
- package/dist/lib/webhook-handoff.d.ts +15 -0
- package/{lib/webhook-handoff.mjs → dist/lib/webhook-handoff.js} +107 -100
- package/dist/lib/webhook-verifiers.d.ts +20 -0
- package/{lib/webhook-verifiers.mjs → dist/lib/webhook-verifiers.js} +108 -104
- package/dist/lib/why.d.ts +9 -0
- package/{lib/why.mjs → dist/lib/why.js} +6 -6
- package/dist/log-safety.d.ts +20 -0
- package/dist/log-safety.js +308 -0
- package/dist/module-layering.d.ts +42 -0
- package/dist/module-layering.js +257 -0
- package/dist/module-shape.d.ts +47 -0
- package/{module-shape.mjs → dist/module-shape.js} +278 -236
- package/dist/naming.d.ts +49 -0
- package/dist/naming.js +246 -0
- package/dist/observability.d.ts +25 -0
- package/dist/observability.js +245 -0
- package/dist/operations.d.ts +23 -0
- package/{operations.mjs → dist/operations.js} +410 -332
- package/dist/project-graph.d.ts +9 -0
- package/{project-graph.mjs → dist/project-graph.js} +8 -13
- package/dist/projections.d.ts +11 -0
- package/{projections.mjs → dist/projections.js} +60 -57
- package/dist/query-safety.d.ts +21 -0
- package/{query-safety.mjs → dist/query-safety.js} +92 -108
- package/dist/realtime.d.ts +15 -0
- package/{realtime.mjs → dist/realtime.js} +108 -106
- package/dist/resilience.d.ts +15 -0
- package/dist/resilience.js +319 -0
- package/dist/schema-authority.d.ts +15 -0
- package/{schema-authority.mjs → dist/schema-authority.js} +256 -220
- package/dist/service-deps.d.ts +17 -0
- package/{service-deps.mjs → dist/service-deps.js} +133 -130
- package/dist/service-isolation.d.ts +8 -0
- package/dist/service-isolation.js +76 -0
- package/dist/size-budget.d.ts +9 -0
- package/{size-budget.mjs → dist/size-budget.js} +27 -27
- package/dist/sonar-parity.d.ts +5 -0
- package/{sonar-parity.mjs → dist/sonar-parity.js} +7 -7
- package/dist/spec-no-skip.d.ts +9 -0
- package/dist/spec-no-skip.js +81 -0
- package/dist/spec-quality.d.ts +10 -0
- package/{spec-quality.mjs → dist/spec-quality.js} +103 -87
- package/dist/suppression.d.ts +26 -0
- package/{suppression.mjs → dist/suppression.js} +30 -45
- package/dist/temporal.d.ts +9 -0
- package/{temporal.mjs → dist/temporal.js} +75 -65
- package/dist/test-world.d.ts +28 -0
- package/{test-world.mjs → dist/test-world.js} +102 -83
- package/dist/testing.d.ts +51 -0
- package/dist/testing.js +368 -0
- package/dist/third-party-owner.d.ts +8 -0
- package/{third-party-owner.mjs → dist/third-party-owner.js} +105 -91
- package/dist/transport.d.ts +24 -0
- package/{transport.mjs → dist/transport.js} +279 -240
- package/dist/type-safety.d.ts +25 -0
- package/dist/type-safety.js +297 -0
- package/dist/unit-spec.d.ts +30 -0
- package/{unit-spec.mjs → dist/unit-spec.js} +473 -399
- package/dist/uploads.d.ts +9 -0
- package/{uploads.mjs → dist/uploads.js} +62 -54
- package/dist/user-copy.d.ts +9 -0
- package/{user-copy.mjs → dist/user-copy.js} +76 -67
- package/dist/webhooks.d.ts +16 -0
- package/{webhooks.mjs → dist/webhooks.js} +243 -231
- package/package.json +23 -8
- package/runtime/knowledge/hfs/canon-pins.yaml +18 -11
- package/runtime/scripts/hfs/repo-identity.mjs +5 -4
- package/async-discipline.mjs +0 -83
- package/comments.mjs +0 -416
- package/edge-hardening.mjs +0 -139
- package/health-ready.mjs +0 -539
- package/jwt-alg.mjs +0 -45
- package/lib/ast.mjs +0 -88
- package/lib/import-source.mjs +0 -104
- package/lib/specifier.mjs +0 -27
- package/lib/subject-values.mjs +0 -55
- package/lib/types.mjs +0 -133
- package/log-safety.mjs +0 -303
- package/module-layering.mjs +0 -270
- package/naming.mjs +0 -251
- package/observability.mjs +0 -241
- package/resilience.mjs +0 -304
- package/service-isolation.mjs +0 -75
- package/spec-no-skip.mjs +0 -85
- package/testing.mjs +0 -384
- 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
|
-
}
|