@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
@@ -3,19 +3,14 @@
3
3
  * the framework enters, and which expression a call is made on. Every answer comes from a decorator's import, a value's
4
4
  * declared type or a declaration's origin, never from a spelling.
5
5
  */
6
- import ts from "typescript"
7
- import { walk } from "./ast.mjs"
8
- import { decoratorCallee, importOf, isImportedFrom } from "./import-source.mjs"
9
- import { typed } from "./types.mjs"
10
-
6
+ import ts from "typescript";
7
+ import { walk } from "./ast.js";
8
+ import { decoratorCallee, importOf, isImportedFrom } from "./import-source.js";
9
+ import { typed } from "./types.js";
11
10
  /** True when the class carries a decorator that is `name` exported by `source`. */
12
- export const hasClassDecorator = (context, node, source, name) =>
13
- (node.decorators ?? []).some((decorator) => isImportedFrom(context, decoratorCallee(decorator), source, name))
14
-
11
+ export const hasClassDecorator = (context, node, source, name) => (node.decorators ?? []).some((decorator) => isImportedFrom(context, decoratorCallee(decorator), source, name));
15
12
  /** The decorators of a method or class that are one of `names` exported by `source`. */
16
- export const decoratorsFrom = (context, node, source, names) =>
17
- (node.decorators ?? []).filter((decorator) => isImportedFrom(context, decoratorCallee(decorator), source, names))
18
-
13
+ export const decoratorsFrom = (context, node, source, names) => (node.decorators ?? []).filter((decorator) => isImportedFrom(context, decoratorCallee(decorator), source, names));
19
14
  /**
20
15
  * Every value injected into a class: a constructor parameter (plain or a parameter property) and a property that
21
16
  * carries a decorator which injects (`Inject` of Nest, a `@nestjs/typeorm` injector or a function declared in a
@@ -26,58 +21,58 @@ export const decoratorsFrom = (context, node, source, names) =>
26
21
  * @returns {Array<{ node: object, annotation: object | undefined }>} The injected members, each with its declared type annotation.
27
22
  */
28
23
  export const injectedMembers = (context, classNode) => {
29
- const members = []
30
- const constructor = classNode.body.body.find((member) => member.type === "MethodDefinition" && member.kind === "constructor")
24
+ const members = [];
25
+ const constructor = classNode.body.body.find((member) => member.type === "MethodDefinition" && member.kind === "constructor");
31
26
  for (const original of constructor?.value.params ?? []) {
32
- const param = original.type === "TSParameterProperty" ? original.parameter : original
33
- members.push({ node: original, annotation: param.typeAnnotation?.typeAnnotation })
27
+ const param = original.type === "TSParameterProperty" ? original.parameter : original;
28
+ members.push({ node: original, annotation: param.typeAnnotation?.typeAnnotation });
34
29
  }
35
30
  for (const member of classNode.body.body) {
36
- if (member.type !== "PropertyDefinition" || !(member.decorators ?? []).some((decorator) => isInjectorDecorator(context, decorator))) continue
37
- members.push({ node: member, annotation: member.typeAnnotation?.typeAnnotation })
31
+ if (member.type !== "PropertyDefinition" || !(member.decorators ?? []).some((decorator) => isInjectorDecorator(context, decorator)))
32
+ continue;
33
+ members.push({ node: member, annotation: member.typeAnnotation?.typeAnnotation });
38
34
  }
39
- return members
40
- }
41
-
35
+ return members;
36
+ };
42
37
  /** True for a decorator that injects: `Inject` of Nest, a `@nestjs/typeorm` injector, or a function declared in a `*.decorators.ts` file. */
43
38
  const isInjectorDecorator = (context, decorator) => {
44
- const callee = decoratorCallee(decorator)
45
- if (callee?.type !== "Identifier") return false
46
- const found = importOf(context, callee)
47
- if (found?.source === "@nestjs/common" && found.imported === "Inject") return true
48
- if (found?.source === "@nestjs/typeorm") return true
49
- const symbol = aliasTarget(context, callee)
50
- return (symbol?.getDeclarations() ?? []).some((declaration) => declaration.getSourceFile().fileName.split("\\").join("/").endsWith(".decorators.ts"))
51
- }
52
-
39
+ const callee = decoratorCallee(decorator);
40
+ if (callee?.type !== "Identifier")
41
+ return false;
42
+ const found = importOf(context, callee);
43
+ if (found?.source === "@nestjs/common" && found.imported === "Inject")
44
+ return true;
45
+ if (found?.source === "@nestjs/typeorm")
46
+ return true;
47
+ const symbol = aliasTarget(context, callee);
48
+ return (symbol?.getDeclarations() ?? []).some((declaration) => declaration.getSourceFile().fileName.split("\\").join("/").endsWith(".decorators.ts"));
49
+ };
53
50
  /** The symbol an identifier names, with an import alias resolved to its target. */
54
51
  export const aliasTarget = (context, identifier) => {
55
- const { checker, toTs } = typed(context)
56
- const tsNode = toTs(identifier)
57
- const symbol = tsNode && checker.getSymbolAtLocation(tsNode)
58
- if (!symbol) return symbol
59
- const isAlias = (symbol.flags & ts.SymbolFlags.Alias) !== 0
60
- return isAlias ? checker.getAliasedSymbol(symbol) : symbol
61
- }
62
-
52
+ const { checker, toTs } = typed(context);
53
+ const tsNode = toTs(identifier);
54
+ const symbol = tsNode && checker.getSymbolAtLocation(tsNode);
55
+ if (!symbol)
56
+ return symbol;
57
+ const isAlias = (symbol.flags & ts.SymbolFlags.Alias) !== 0;
58
+ return isAlias ? checker.getAliasedSymbol(symbol) : symbol;
59
+ };
63
60
  /** The methods of a class (instance, non-constructor) that carry one of the decorators `names` of `source`. */
64
- export const methodsDecoratedBy = (context, classNode, source, names) =>
65
- classNode.body.body.filter((member) => member.type === "MethodDefinition" && member.kind === "method" && !member.static && decoratorsFrom(context, member, source, names).length > 0)
66
-
61
+ export const methodsDecoratedBy = (context, classNode, source, names) => classNode.body.body.filter((member) => member.type === "MethodDefinition" && member.kind === "method" && !member.static && decoratorsFrom(context, member, source, names).length > 0);
67
62
  /**
68
63
  * Every call made in a method body, closures included: `<receiver>.<method>(...)` as `{ call, receiver, method }`, and any
69
64
  * other call as `{ call, receiver: null, method: null }`.
70
65
  */
71
66
  export const callsOf = (method) => {
72
- const calls = []
67
+ const calls = [];
73
68
  walk(method.value.body, (node) => {
74
- if (node.type !== "CallExpression") return
75
- const callee = node.callee
76
- const member = callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" ? callee : null
77
- calls.push({ call: node, receiver: member?.object ?? null, method: member?.property.name ?? null })
78
- })
79
- return calls
80
- }
81
-
69
+ if (node.type !== "CallExpression")
70
+ return;
71
+ const callee = node.callee;
72
+ const member = callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" ? callee : null;
73
+ calls.push({ call: node, receiver: member?.object ?? null, method: member?.property.name ?? null });
74
+ });
75
+ return calls;
76
+ };
82
77
  /** The parameters of a handler method, with the pattern a default value or a destructuring wraps unwrapped. */
83
- export const parametersOf = (method) => method.value.params.map((param) => (param.type === "TSParameterProperty" ? param.parameter : param))
78
+ export const parametersOf = (method) => method.value.params.map((param) => (param.type === "TSParameterProperty" ? param.parameter : param));
@@ -0,0 +1,25 @@
1
+ /**
2
+ * The edition gate of the back-end plugin.
3
+ *
4
+ * Edition applicability belongs to the HFS rule catalog, beside the law and its enforcer. A rule
5
+ * that the catalog does not judge in this app's edition still ships in the plugin, but its `create`
6
+ * returns no listeners. The plugin wiring therefore has one generic gate instead of edition checks
7
+ * scattered through rule bodies.
8
+ */
9
+ import { type RuleCatalog } from "../../runtime/scripts/hfs/slots.mjs";
10
+ import type { CanonPlugin } from "./config.js";
11
+ /**
12
+ * The plugin view for one HFS edition.
13
+ *
14
+ * Full is the default edition and the catalog's superset, so it needs no runtime catalog read. This
15
+ * keeps the source checkout testable before `sync-runtime` refreshes the generated bundle; lite
16
+ * loads the package's bundled catalog in a published installation. Tests may inject a catalog to
17
+ * prove the generic filtering independently of generated copies.
18
+ */
19
+ export declare const pluginForEdition: <P extends CanonPlugin>({ plugin, hfs, catalog }: {
20
+ plugin: P;
21
+ hfs?: {
22
+ readonly edition?: string;
23
+ } | null | undefined;
24
+ catalog?: Pick<RuleCatalog, "enforcerJudgedIn"> | undefined;
25
+ }) => P;
@@ -6,22 +6,16 @@
6
6
  * returns no listeners. The plugin wiring therefore has one generic gate instead of edition checks
7
7
  * scattered through rule bodies.
8
8
  */
9
- import { dirname, join } from "node:path"
10
- import { fileURLToPath } from "node:url"
11
- import { loadRuleCatalog } from "../runtime/scripts/hfs/slots.mjs"
12
-
13
- const RUNTIME = join(dirname(fileURLToPath(import.meta.url)), "..", "runtime")
14
- let catalogCache
15
-
9
+ import { loadRuleCatalog } from "../../runtime/scripts/hfs/slots.mjs";
10
+ import { RUNTIME_ROOT as RUNTIME } from "./runtime-root.js";
11
+ let catalogCache;
16
12
  /** The bundled rule catalog, loaded once per lint process. */
17
13
  const bundledCatalog = () => {
18
- catalogCache ??= loadRuleCatalog({ root: RUNTIME })
19
- return catalogCache
20
- }
21
-
14
+ catalogCache ??= loadRuleCatalog({ root: RUNTIME });
15
+ return catalogCache;
16
+ };
22
17
  /** A rule which intentionally registers no listeners in this edition. */
23
- const inactive = (rule) => Object.freeze({ ...rule, create: () => ({}) })
24
-
18
+ const inactive = (rule) => Object.freeze({ ...rule, create: () => ({}) });
25
19
  /**
26
20
  * The plugin view for one HFS edition.
27
21
  *
@@ -31,15 +25,16 @@ const inactive = (rule) => Object.freeze({ ...rule, create: () => ({}) })
31
25
  * prove the generic filtering independently of generated copies.
32
26
  */
33
27
  export const pluginForEdition = ({ plugin, hfs, catalog }) => {
34
- const edition = hfs?.edition === undefined ? "full" : hfs.edition
28
+ const edition = hfs?.edition === undefined ? "full" : hfs.edition;
35
29
  if (edition !== "full" && edition !== "lite") {
36
- throw new RangeError(`Unknown HFS edition ${JSON.stringify(edition)}; expected "full" or "lite"`)
30
+ throw new RangeError(`Unknown HFS edition ${JSON.stringify(edition)}; expected "full" or "lite"`);
37
31
  }
38
- if (edition === "full" && catalog === undefined) return plugin
39
- const loaded = catalog ?? bundledCatalog()
32
+ if (edition === "full" && catalog === undefined)
33
+ return plugin;
34
+ const loaded = catalog ?? bundledCatalog();
40
35
  const rules = Object.fromEntries(Object.entries(plugin.rules).map(([id, rule]) => [
41
36
  id,
42
37
  loaded.enforcerJudgedIn("eslint-be", id, edition) ? rule : inactive(rule),
43
- ]))
44
- return Object.freeze({ ...plugin, rules: Object.freeze(rules) })
45
- }
38
+ ]));
39
+ return Object.freeze({ ...plugin, rules: Object.freeze(rules) });
40
+ };
@@ -0,0 +1,7 @@
1
+ import type { TSESTree } from "@typescript-eslint/utils";
2
+ import type { Context } from "./rule.js";
3
+ import type { TypeOrigin } from "./types.js";
4
+ /** The methods of a manager or query builder that change rows. */
5
+ export declare const WRITE_METHODS: readonly string[];
6
+ /** The declarations (class origins) of the entities a database write call targets, or `[]` when the node is not such a call. */
7
+ export declare const writtenEntityOrigins: (context: Context, node: TSESTree.CallExpression) => TypeOrigin[];
@@ -3,33 +3,42 @@
3
3
  * `DataSource`, `QueryRunner`) or on a typeorm query builder, whose arguments (or, for a query builder, the arguments of any call
4
4
  * of the same chain) are the entity class or an instance of it. No variable, class or table name is read.
5
5
  */
6
- import { isDatabaseReceiver } from "./db-writes.mjs"
7
- import { typeOrigins } from "./types.mjs"
8
-
6
+ import { isDatabaseReceiver } from "./db-writes.js";
7
+ import { typeOrigins } from "./types.js";
9
8
  /** The methods of a manager or query builder that change rows. */
10
- export const WRITE_METHODS = Object.freeze(["update", "save", "insert", "upsert", "delete", "remove", "increment", "decrement", "softDelete", "softRemove", "recover", "restore", "clear"])
11
-
9
+ export const WRITE_METHODS = Object.freeze(["update", "save", "insert", "upsert", "delete", "remove", "increment", "decrement", "softDelete", "softRemove", "recover", "restore", "clear"]);
12
10
  /** True when the node's type is a query builder of `typeorm` (`SelectQueryBuilder`, `UpdateQueryBuilder` ...). */
13
- const isQueryBuilder = (context, node) => typeOrigins(context, node).some((origin) => origin.module === "typeorm" && origin.name.endsWith("QueryBuilder"))
14
-
11
+ const isQueryBuilder = (context, node) => typeOrigins(context, node).some((origin) => origin.module === "typeorm" && origin.name.endsWith("QueryBuilder"));
15
12
  /** The declarations (class origins) of the entities a database write call targets, or `[]` when the node is not such a call. */
16
13
  export const writtenEntityOrigins = (context, node) => {
17
- const callee = node.callee
18
- if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier" || !WRITE_METHODS.includes(callee.property.name)) return []
19
- if (!isDatabaseReceiver(context, callee.object) && !isQueryBuilder(context, callee.object)) return []
20
- const candidates = [...node.arguments]
21
- for (let link = callee.object; link; ) {
14
+ const callee = node.callee;
15
+ if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier" || !WRITE_METHODS.includes(callee.property.name))
16
+ return [];
17
+ if (!isDatabaseReceiver(context, callee.object) && !isQueryBuilder(context, callee.object))
18
+ return [];
19
+ const candidates = [...node.arguments];
20
+ for (let link = callee.object; link;) {
22
21
  if (link.type === "CallExpression") {
23
- candidates.push(...link.arguments)
24
- link = link.callee.type === "MemberExpression" ? link.callee.object : null
25
- } else if (link.type === "MemberExpression") link = link.object
26
- else if (link.type === "TSNonNullExpression" || link.type === "AwaitExpression") link = link.expression ?? link.argument
27
- else link = null
22
+ candidates.push(...link.arguments);
23
+ link = link.callee.type === "MemberExpression" ? link.callee.object : null;
24
+ }
25
+ else if (link.type === "MemberExpression")
26
+ link = link.object;
27
+ else if (link.type === "TSNonNullExpression")
28
+ link = link.expression;
29
+ else if (link.type === "AwaitExpression")
30
+ link = link.argument;
31
+ else
32
+ link = null;
28
33
  }
29
34
  // The entity of a builder write may come later in the same chain (`.delete().from(Entity)`, `.insert().into(Entity)`).
30
- for (let outer = node; outer.parent?.type === "MemberExpression" && outer.parent.object === outer && outer.parent.parent?.type === "CallExpression" && outer.parent.parent.callee === outer.parent; ) {
31
- outer = outer.parent.parent
32
- candidates.push(...outer.arguments)
35
+ for (let outer = node; outer;) {
36
+ const member = outer.parent;
37
+ const call = member?.parent;
38
+ if (member?.type !== "MemberExpression" || member.object !== outer || call?.type !== "CallExpression" || call.callee !== member)
39
+ break;
40
+ outer = call;
41
+ candidates.push(...outer.arguments);
33
42
  }
34
- return candidates.flatMap((candidate) => typeOrigins(context, candidate)).filter((origin) => origin.module === null)
35
- }
43
+ return candidates.flatMap((candidate) => typeOrigins(context, candidate)).filter((origin) => origin.module === null);
44
+ };
@@ -0,0 +1,34 @@
1
+ import { type HfsView } from "../../runtime/scripts/hfs/view.mjs";
2
+ import type { Context } from "./rule.js";
3
+ export type { HfsAllowsVerdict, HfsApp, HfsClassification, HfsConnection, HfsParamName, HfsRuleParams, HfsSlot, HfsSpecDouble, HfsUnitRole, HfsView, } from "../../runtime/scripts/hfs/view.mjs";
4
+ /**
5
+ * The HFS view of the side whose `eslint.config.mjs` (in be/) calls this.
6
+ *
7
+ * @param configUrl - `import.meta.url` of the repository's `eslint.config.mjs`.
8
+ * @returns The frozen HFS view (profile, apps, connections, ruleParams, slotOf, tierOf, ownerOf).
9
+ */
10
+ export declare const loadHfs: (configUrl: string) => HfsView;
11
+ /**
12
+ * The HFS view of the be side of an in-memory app declaration, for rule tests: no file is read except the shipped manifest.
13
+ *
14
+ * @param declaration - An app `hfs.json` object.
15
+ * @param repoRoot - The absolute be side folder the linted filenames live under.
16
+ * @returns The frozen HFS view.
17
+ */
18
+ export declare const hfsFromDeclaration: (declaration: object, repoRoot: string) => HfsView;
19
+ /**
20
+ * The HFS view a rule runs under; a rule that needs it and gets none refuses to guess.
21
+ *
22
+ * @param context - The ESLint rule context.
23
+ * @returns The HFS view from `settings.starci.hfs`.
24
+ */
25
+ export declare const hfsOf: (context: Context) => HfsView;
26
+ /**
27
+ * Whether a file belongs to the test world: the slot `be.tests.world` or one of its sub-slots (`be.tests.world.kit`, the world's
28
+ * inlined helpers). The world and its helpers form one test composition root.
29
+ *
30
+ * @param hfs - The HFS view of the repository.
31
+ * @param file - A file path.
32
+ * @returns True for a file of the test world family.
33
+ */
34
+ export declare const inTestWorld: (hfs: HfsView, file: string) => boolean;
@@ -11,52 +11,54 @@
11
11
  * `/src/modules/` or `/src/tests/`. A rule that needs the manifest and finds no `settings.starci.hfs` stops the lint run
12
12
  * with an error naming the fix, because a rule must not guess.
13
13
  */
14
- import { dirname, join } from "node:path"
15
- import { fileURLToPath } from "node:url"
16
- import { declaredHfsView, openHfsView } from "../runtime/scripts/hfs/view.mjs"
17
-
18
- const RUNTIME = join(dirname(fileURLToPath(import.meta.url)), "..", "runtime")
19
-
14
+ import { dirname } from "node:path";
15
+ import { fileURLToPath } from "node:url";
16
+ import { declaredHfsView, openHfsView } from "../../runtime/scripts/hfs/view.mjs";
17
+ import { RUNTIME_ROOT as RUNTIME } from "./runtime-root.js";
20
18
  /**
21
19
  * The HFS view of the side whose `eslint.config.mjs` (in be/) calls this.
22
20
  *
23
- * @param {string} configUrl - `import.meta.url` of the repository's `eslint.config.mjs`.
24
- * @returns {object} The frozen HFS view (profile, apps, connections, ruleParams, slotOf, tierOf, ownerOf).
21
+ * @param configUrl - `import.meta.url` of the repository's `eslint.config.mjs`.
22
+ * @returns The frozen HFS view (profile, apps, connections, ruleParams, slotOf, tierOf, ownerOf).
25
23
  */
26
- export const loadHfs = (configUrl) => openHfsView({ runtimeRoot: RUNTIME, repoRoot: dirname(fileURLToPath(configUrl)) })
27
-
24
+ export const loadHfs = (configUrl) => openHfsView({ runtimeRoot: RUNTIME, repoRoot: dirname(fileURLToPath(configUrl)) });
28
25
  /**
29
26
  * The HFS view of the be side of an in-memory app declaration, for rule tests: no file is read except the shipped manifest.
30
27
  *
31
- * @param {object} declaration - An app `hfs.json` object.
32
- * @param {string} repoRoot - The absolute be side folder the linted filenames live under.
33
- * @returns {object} The frozen HFS view.
28
+ * @param declaration - An app `hfs.json` object.
29
+ * @param repoRoot - The absolute be side folder the linted filenames live under.
30
+ * @returns The frozen HFS view.
34
31
  */
35
- export const hfsFromDeclaration = (declaration, repoRoot) => declaredHfsView({ runtimeRoot: RUNTIME, declaration, repoRoot, side: "be" })
36
-
32
+ export const hfsFromDeclaration = (declaration, repoRoot) => declaredHfsView({ runtimeRoot: RUNTIME, declaration, repoRoot, side: "be" });
33
+ /** Whether a settings value is an HFS view (it answers `slotOf`). */
34
+ const isHfsView = (value) => typeof value === "object" && value !== null && "slotOf" in value && typeof value.slotOf === "function";
35
+ /** The `settings.starci.hfs` value of a rule context, if any. */
36
+ const settingsHfs = (context) => {
37
+ const starci = context.settings?.["starci"];
38
+ return typeof starci === "object" && starci !== null && "hfs" in starci ? starci.hfs : undefined;
39
+ };
37
40
  /**
38
41
  * The HFS view a rule runs under; a rule that needs it and gets none refuses to guess.
39
42
  *
40
- * @param {object} context - The ESLint rule context.
41
- * @returns {object} The HFS view from `settings.starci.hfs`.
43
+ * @param context - The ESLint rule context.
44
+ * @returns The HFS view from `settings.starci.hfs`.
42
45
  */
43
46
  export const hfsOf = (context) => {
44
- const hfs = context.settings?.starci?.hfs
45
- if (!hfs || typeof hfs.slotOf !== "function") {
46
- throw new Error(`${context.id ?? "a starci-be rule"} needs settings.starci.hfs: lint through starciBeConfig({ hfs: loadHfs(import.meta.url) })`)
47
+ const hfs = settingsHfs(context);
48
+ if (!isHfsView(hfs)) {
49
+ throw new Error(`${context.id ?? "a starci-be rule"} needs settings.starci.hfs: lint through starciBeConfig({ hfs: loadHfs(import.meta.url) })`);
47
50
  }
48
- return hfs
49
- }
50
-
51
+ return hfs;
52
+ };
51
53
  /**
52
54
  * Whether a file belongs to the test world: the slot `be.tests.world` or one of its sub-slots (`be.tests.world.kit`, the world's
53
55
  * inlined helpers). The world and its helpers form one test composition root.
54
56
  *
55
- * @param {object} hfs - The HFS view of the repository.
56
- * @param {string} file - A file path.
57
- * @returns {boolean} True for a file of the test world family.
57
+ * @param hfs - The HFS view of the repository.
58
+ * @param file - A file path.
59
+ * @returns True for a file of the test world family.
58
60
  */
59
61
  export const inTestWorld = (hfs, file) => {
60
- const slot = hfs.slotOf(file)
61
- return slot === "be.tests.world" || (typeof slot === "string" && slot.startsWith("be.tests.world."))
62
- }
62
+ const slot = hfs.slotOf(file);
63
+ return slot === "be.tests.world" || (typeof slot === "string" && slot.startsWith("be.tests.world."));
64
+ };
@@ -0,0 +1,63 @@
1
+ /**
2
+ * Import-owner helpers: what a name written in a file IS, by the import that binds it, never by how it is spelled.
3
+ *
4
+ * `import { CommandHandler as Handler } from "@nestjs/cqrs"` and `import { CommandHandler } from "@nestjs/cqrs"` are the
5
+ * same decorator; a local class that happens to be called `CommandHandler` is not. A rule that asks
6
+ * `importOf(context, identifier)` sees that difference and a rule that compares identifier text does not.
7
+ */
8
+ import type { TSESTree } from "@typescript-eslint/utils";
9
+ import type { Context, Node } from "./rule.js";
10
+ /** An import binding: the module specifier and the exported name (`*` for a namespace import, `default` for a default import). */
11
+ export interface ImportBinding {
12
+ readonly source: string;
13
+ readonly imported: string | null;
14
+ }
15
+ /** One place a file names another module. */
16
+ export interface ModuleReference {
17
+ readonly node: Node;
18
+ readonly source: Node;
19
+ readonly value: string;
20
+ readonly names: ReadonlyArray<string | null>;
21
+ }
22
+ /**
23
+ * The import an identifier resolves to.
24
+ *
25
+ * @param context - The ESLint rule context.
26
+ * @param identifier - An `Identifier` node in a value or decorator position.
27
+ * @returns The module specifier and the exported name (`*` for a namespace import, `default` for a default import), or null when the name is not an import binding.
28
+ */
29
+ export declare const importOf: (context: Context, identifier: Node | null | undefined) => ImportBinding | null;
30
+ /**
31
+ * True when an expression is `name` exported by `source`, whether written as the imported (possibly renamed) identifier
32
+ * or as a member of a namespace import of that module.
33
+ *
34
+ * @param context - The ESLint rule context.
35
+ * @param expression - An `Identifier` or `MemberExpression` node.
36
+ * @param sources - The module specifier or specifiers.
37
+ * @param names - The exported name or names.
38
+ * @returns Whether the expression is one of those exports.
39
+ */
40
+ export declare const isImportedFrom: (context: Context, expression: Node | null | undefined, sources: string | ReadonlyArray<string>, names: string | ReadonlyArray<string>) => boolean;
41
+ /** The called expression of a decorator: `@Foo` and `@Foo(...)` both give `Foo`. */
42
+ export declare const decoratorCallee: (decorator: TSESTree.Decorator | null | undefined) => TSESTree.Expression | null;
43
+ /** The arguments of a decorator (`[]` for a bare `@Foo`). */
44
+ export declare const decoratorArguments: (decorator: TSESTree.Decorator | null | undefined) => TSESTree.CallExpressionArgument[];
45
+ /** The visitor object `moduleReferences` returns. */
46
+ export type ModuleReferenceVisitors = ReturnType<typeof moduleReferences>;
47
+ /** Run the `moduleReferences` visitor of a node's own type, if it has one (a walk that is not ESLint's traversal). */
48
+ export declare const visitModuleReference: (visitors: ModuleReferenceVisitors, node: Node) => void;
49
+ /**
50
+ * Visitors that report every place a file names another module: a static import, an `export ... from`, a dynamic
51
+ * `import()`, `import x = require()` and a `require()` call with a literal argument.
52
+ *
53
+ * @param onReference - Called once per reference; `names` are the exported names taken (`*` for a whole module).
54
+ * @returns An ESLint visitor object.
55
+ */
56
+ export declare const moduleReferences: (onReference: (reference: ModuleReference) => void) => {
57
+ ImportDeclaration(node: TSESTree.ImportDeclaration): void;
58
+ ExportNamedDeclaration(node: TSESTree.ExportNamedDeclaration): void;
59
+ ExportAllDeclaration(node: TSESTree.ExportAllDeclaration): void;
60
+ ImportExpression(node: TSESTree.ImportExpression): void;
61
+ CallExpression(node: TSESTree.CallExpression): void;
62
+ TSImportEqualsDeclaration(node: TSESTree.TSImportEqualsDeclaration): void;
63
+ };
@@ -0,0 +1,134 @@
1
+ const textOf = (node) => (node?.type === "Identifier" ? node.name : node?.type === "Literal" ? String(node.value) : null);
2
+ /**
3
+ * The import an identifier resolves to.
4
+ *
5
+ * @param context - The ESLint rule context.
6
+ * @param identifier - An `Identifier` node in a value or decorator position.
7
+ * @returns The module specifier and the exported name (`*` for a namespace import, `default` for a default import), or null when the name is not an import binding.
8
+ */
9
+ export const importOf = (context, identifier) => {
10
+ if (identifier?.type !== "Identifier")
11
+ return null;
12
+ for (let scope = context.sourceCode.getScope(identifier); scope; scope = scope.upper) {
13
+ const variable = scope.set.get(identifier.name);
14
+ if (!variable)
15
+ continue;
16
+ const definition = variable.defs[0];
17
+ if (definition?.type !== "ImportBinding")
18
+ return null;
19
+ const specifier = definition.node;
20
+ const source = importSourceOf(definition.parent);
21
+ if (specifier.type === "ImportSpecifier")
22
+ return { source, imported: textOf(specifier.imported) };
23
+ if (specifier.type === "ImportNamespaceSpecifier")
24
+ return { source, imported: "*" };
25
+ return { source, imported: "default" };
26
+ }
27
+ return null;
28
+ };
29
+ /** The module specifier of the declaration an import binding sits in. */
30
+ const importSourceOf = (parent) => {
31
+ if (parent?.type === "ImportDeclaration")
32
+ return parent.source.value;
33
+ throw new TypeError("an import binding outside an import declaration has no module specifier");
34
+ };
35
+ /**
36
+ * True when an expression is `name` exported by `source`, whether written as the imported (possibly renamed) identifier
37
+ * or as a member of a namespace import of that module.
38
+ *
39
+ * @param context - The ESLint rule context.
40
+ * @param expression - An `Identifier` or `MemberExpression` node.
41
+ * @param sources - The module specifier or specifiers.
42
+ * @param names - The exported name or names.
43
+ * @returns Whether the expression is one of those exports.
44
+ */
45
+ export const isImportedFrom = (context, expression, sources, names) => {
46
+ const wantedSources = typeof sources === "string" ? [sources] : sources;
47
+ const wantedNames = typeof names === "string" ? [names] : names;
48
+ if (expression?.type === "Identifier") {
49
+ const found = importOf(context, expression);
50
+ return found !== null && wantedSources.includes(found.source) && wantedNames.includes(found.imported);
51
+ }
52
+ if (expression?.type === "MemberExpression" && !expression.computed && expression.object.type === "Identifier") {
53
+ const found = importOf(context, expression.object);
54
+ return found !== null && found.imported === "*" && wantedSources.includes(found.source) && wantedNames.includes(textOf(expression.property));
55
+ }
56
+ return false;
57
+ };
58
+ /** The called expression of a decorator: `@Foo` and `@Foo(...)` both give `Foo`. */
59
+ export const decoratorCallee = (decorator) => {
60
+ const expression = decorator?.expression;
61
+ return expression?.type === "CallExpression" ? expression.callee : expression ?? null;
62
+ };
63
+ /** The arguments of a decorator (`[]` for a bare `@Foo`). */
64
+ export const decoratorArguments = (decorator) => (decorator?.expression?.type === "CallExpression" ? decorator.expression.arguments : []);
65
+ /** The text of a string literal, or of a template with no substitution, else null. */
66
+ const literal = (node) => (node?.type === "Literal" && typeof node.value === "string"
67
+ ? node.value
68
+ : node?.type === "TemplateLiteral" && node.expressions.length === 0 ? (node.quasis[0]?.value.cooked ?? null) : null);
69
+ /** Run the `moduleReferences` visitor of a node's own type, if it has one (a walk that is not ESLint's traversal). */
70
+ export const visitModuleReference = (visitors, node) => {
71
+ switch (node.type) {
72
+ case "ImportDeclaration":
73
+ visitors.ImportDeclaration(node);
74
+ break;
75
+ case "ExportNamedDeclaration":
76
+ visitors.ExportNamedDeclaration(node);
77
+ break;
78
+ case "ExportAllDeclaration":
79
+ visitors.ExportAllDeclaration(node);
80
+ break;
81
+ case "ImportExpression":
82
+ visitors.ImportExpression(node);
83
+ break;
84
+ case "CallExpression":
85
+ visitors.CallExpression(node);
86
+ break;
87
+ case "TSImportEqualsDeclaration":
88
+ visitors.TSImportEqualsDeclaration(node);
89
+ break;
90
+ default: break;
91
+ }
92
+ };
93
+ /**
94
+ * Visitors that report every place a file names another module: a static import, an `export ... from`, a dynamic
95
+ * `import()`, `import x = require()` and a `require()` call with a literal argument.
96
+ *
97
+ * @param onReference - Called once per reference; `names` are the exported names taken (`*` for a whole module).
98
+ * @returns An ESLint visitor object.
99
+ */
100
+ export const moduleReferences = (onReference) => ({
101
+ ImportDeclaration(node) {
102
+ const names = node.specifiers.map((specifier) => specifier.type === "ImportSpecifier" ? textOf(specifier.imported) : specifier.type === "ImportNamespaceSpecifier" ? "*" : "default");
103
+ onReference({ node, source: node.source, value: node.source.value, names: names.length > 0 ? names : ["*"] });
104
+ },
105
+ ExportNamedDeclaration(node) {
106
+ if (!node.source)
107
+ return;
108
+ onReference({ node, source: node.source, value: node.source.value, names: node.specifiers.map((specifier) => textOf(specifier.local)) });
109
+ },
110
+ ExportAllDeclaration(node) {
111
+ onReference({ node, source: node.source, value: node.source.value, names: ["*"] });
112
+ },
113
+ ImportExpression(node) {
114
+ const value = literal(node.source);
115
+ if (value !== null)
116
+ onReference({ node, source: node.source, value, names: ["*"] });
117
+ },
118
+ CallExpression(node) {
119
+ if (node.callee.type !== "Identifier" || node.callee.name !== "require")
120
+ return;
121
+ const argument = node.arguments[0];
122
+ const value = literal(argument);
123
+ if (value !== null && argument !== undefined)
124
+ onReference({ node, source: argument, value, names: ["*"] });
125
+ },
126
+ TSImportEqualsDeclaration(node) {
127
+ const reference = node.moduleReference;
128
+ if (reference.type !== "TSExternalModuleReference")
129
+ return;
130
+ const value = literal(reference.expression);
131
+ if (value !== null)
132
+ onReference({ node, source: reference.expression, value, names: ["*"] });
133
+ },
134
+ });
@@ -0,0 +1,8 @@
1
+ /** Forward-slash form of a filename, so Windows paths compare like every other path. */
2
+ export declare const normalizePath: (filename: string | null | undefined) => string;
3
+ /** A spec file: the unit lane, where a fixture may build a deliberately wrong value. */
4
+ export declare const isSpecFile: (filename: string | null | undefined) => boolean;
5
+ /** A migration: the one place schema-changing SQL is allowed to be written. */
6
+ export declare const isMigrationFile: (filename: string | null | undefined) => boolean;
7
+ /** A declaration file carries types only and no runtime behaviour to police. */
8
+ export declare const isDeclarationFile: (filename: string | null | undefined) => boolean;
@@ -1,11 +1,8 @@
1
1
  /** Forward-slash form of a filename, so Windows paths compare like every other path. */
2
- export const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
3
-
2
+ export const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/");
4
3
  /** A spec file: the unit lane, where a fixture may build a deliberately wrong value. */
5
- export const isSpecFile = (filename) => /\.(?:spec|test)\.[cm]?[jt]sx?$|-spec\.[cm]?[jt]sx?$/.test(normalizePath(filename))
6
-
4
+ export const isSpecFile = (filename) => /\.(?:spec|test)\.[cm]?[jt]sx?$|-spec\.[cm]?[jt]sx?$/.test(normalizePath(filename));
7
5
  /** A migration: the one place schema-changing SQL is allowed to be written. */
8
- export const isMigrationFile = (filename) => /\/persistence\/migrations\/[^/]+\.[cm]?[jt]s$/.test(normalizePath(filename))
9
-
6
+ export const isMigrationFile = (filename) => /\/persistence\/migrations\/[^/]+\.[cm]?[jt]s$/.test(normalizePath(filename));
10
7
  /** A declaration file carries types only and no runtime behaviour to police. */
11
- export const isDeclarationFile = (filename) => /\.d\.[cm]?ts$/.test(normalizePath(filename))
8
+ export const isDeclarationFile = (filename) => /\.d\.[cm]?ts$/.test(normalizePath(filename));