@starci/eslint-canon-be 3.5.0 → 3.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (198) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +13 -2
  3. package/dist/ambient-id.d.ts +9 -0
  4. package/{ambient-id.mjs → dist/ambient-id.js} +43 -39
  5. package/dist/app-composition.d.ts +21 -0
  6. package/{app-composition.mjs → dist/app-composition.js} +396 -300
  7. package/dist/async-discipline.d.ts +9 -0
  8. package/dist/async-discipline.js +77 -0
  9. package/dist/authorization.d.ts +12 -0
  10. package/{authorization.mjs → dist/authorization.js} +53 -59
  11. package/dist/boundary-schema.d.ts +15 -0
  12. package/{boundary-schema.mjs → dist/boundary-schema.js} +120 -105
  13. package/dist/builders.d.ts +21 -0
  14. package/{builders.mjs → dist/builders.js} +162 -146
  15. package/dist/cli.d.ts +15 -0
  16. package/{cli.mjs → dist/cli.js} +97 -82
  17. package/dist/comments.d.ts +52 -0
  18. package/dist/comments.js +412 -0
  19. package/dist/config-owner.d.ts +24 -0
  20. package/{config-owner.mjs → dist/config-owner.js} +256 -219
  21. package/dist/connections.d.ts +12 -0
  22. package/{connections.mjs → dist/connections.js} +138 -140
  23. package/dist/cookies.d.ts +9 -0
  24. package/{cookies.mjs → dist/cookies.js} +58 -58
  25. package/dist/cqrs.d.ts +27 -0
  26. package/{cqrs.mjs → dist/cqrs.js} +341 -282
  27. package/dist/data-access.d.ts +50 -0
  28. package/{data-access.mjs → dist/data-access.js} +238 -243
  29. package/dist/default-deny.d.ts +15 -0
  30. package/{default-deny.mjs → dist/default-deny.js} +103 -88
  31. package/dist/e2e-flow.d.ts +25 -0
  32. package/{e2e-flow.mjs → dist/e2e-flow.js} +113 -112
  33. package/dist/edge-hardening.d.ts +10 -0
  34. package/dist/edge-hardening.js +173 -0
  35. package/dist/error-handling.d.ts +21 -0
  36. package/{error-handling.mjs → dist/error-handling.js} +289 -239
  37. package/dist/event-bus.d.ts +14 -0
  38. package/{event-bus.mjs → dist/event-bus.js} +146 -129
  39. package/dist/feature-thin.d.ts +12 -0
  40. package/{feature-thin.mjs → dist/feature-thin.js} +208 -191
  41. package/dist/function-budget.d.ts +7 -0
  42. package/{function-budget.mjs → dist/function-budget.js} +24 -27
  43. package/dist/health-ready.d.ts +10 -0
  44. package/dist/health-ready.js +703 -0
  45. package/dist/idempotency.d.ts +10 -0
  46. package/{idempotency.mjs → dist/idempotency.js} +296 -226
  47. package/dist/index.d.ts +54 -0
  48. package/{index.mjs → dist/index.js} +91 -109
  49. package/dist/infra-owner.d.ts +18 -0
  50. package/{infra-owner.mjs → dist/infra-owner.js} +58 -51
  51. package/dist/injection.d.ts +30 -0
  52. package/{injection.mjs → dist/injection.js} +397 -344
  53. package/dist/input-bounds.d.ts +15 -0
  54. package/{input-bounds.mjs → dist/input-bounds.js} +143 -132
  55. package/dist/jobs.d.ts +17 -0
  56. package/{jobs.mjs → dist/jobs.js} +116 -99
  57. package/dist/jwt-alg.d.ts +6 -0
  58. package/dist/jwt-alg.js +49 -0
  59. package/dist/lib/app-roles.d.ts +25 -0
  60. package/{lib/app-roles.mjs → dist/lib/app-roles.js} +15 -17
  61. package/dist/lib/ast.d.ts +40 -0
  62. package/dist/lib/ast.js +100 -0
  63. package/dist/lib/client-idempotency.d.ts +3 -0
  64. package/{lib/client-idempotency.mjs → dist/lib/client-idempotency.js} +316 -268
  65. package/dist/lib/config.d.ts +36 -0
  66. package/{lib/config.mjs → dist/lib/config.js} +24 -27
  67. package/dist/lib/db-writes.d.ts +29 -0
  68. package/{lib/db-writes.mjs → dist/lib/db-writes.js} +27 -27
  69. package/dist/lib/declared.d.ts +77 -0
  70. package/{lib/declared.mjs → dist/lib/declared.js} +83 -78
  71. package/dist/lib/doors.d.ts +50 -0
  72. package/{lib/doors.mjs → dist/lib/doors.js} +45 -50
  73. package/dist/lib/edition.d.ts +25 -0
  74. package/{lib/edition.mjs → dist/lib/edition.js} +15 -20
  75. package/dist/lib/entity-writes.d.ts +7 -0
  76. package/{lib/entity-writes.mjs → dist/lib/entity-writes.js} +31 -22
  77. package/dist/lib/hfs-view.d.ts +127 -0
  78. package/dist/lib/hfs-view.js +1 -0
  79. package/dist/lib/hfs.d.ts +34 -0
  80. package/{lib/hfs.mjs → dist/lib/hfs.js} +31 -29
  81. package/dist/lib/import-source.d.ts +63 -0
  82. package/dist/lib/import-source.js +134 -0
  83. package/dist/lib/path.d.ts +8 -0
  84. package/{lib/path.mjs → dist/lib/path.js} +4 -7
  85. package/dist/lib/persistence.d.ts +115 -0
  86. package/{lib/persistence.mjs → dist/lib/persistence.js} +55 -66
  87. package/dist/lib/ports.d.ts +70 -0
  88. package/{lib/ports.mjs → dist/lib/ports.js} +62 -66
  89. package/dist/lib/rule.d.ts +31 -0
  90. package/dist/lib/rule.js +2 -0
  91. package/dist/lib/runtime-root.d.ts +4 -0
  92. package/dist/lib/runtime-root.js +10 -0
  93. package/dist/lib/schema-values.d.ts +13 -0
  94. package/{lib/schema-values.mjs → dist/lib/schema-values.js} +67 -59
  95. package/dist/lib/specifier.d.ts +12 -0
  96. package/dist/lib/specifier.js +29 -0
  97. package/dist/lib/subject-values.d.ts +4 -0
  98. package/dist/lib/subject-values.js +61 -0
  99. package/dist/lib/transactions.d.ts +18 -0
  100. package/{lib/transactions.mjs → dist/lib/transactions.js} +17 -15
  101. package/dist/lib/transport-slots.d.ts +17 -0
  102. package/{lib/transport-slots.mjs → dist/lib/transport-slots.js} +2 -4
  103. package/dist/lib/types.d.ts +96 -0
  104. package/dist/lib/types.js +150 -0
  105. package/dist/lib/unit-spec.d.ts +48 -0
  106. package/{lib/unit-spec.mjs → dist/lib/unit-spec.js} +35 -44
  107. package/dist/lib/webhook-ack.d.ts +4 -0
  108. package/{lib/webhook-ack.mjs → dist/lib/webhook-ack.js} +78 -62
  109. package/dist/lib/webhook-handoff-inbox.d.ts +3 -0
  110. package/{lib/webhook-handoff-inbox.mjs → dist/lib/webhook-handoff-inbox.js} +195 -167
  111. package/dist/lib/webhook-handoff-intake.d.ts +4 -0
  112. package/{lib/webhook-handoff-intake.mjs → dist/lib/webhook-handoff-intake.js} +125 -102
  113. package/dist/lib/webhook-handoff.d.ts +15 -0
  114. package/{lib/webhook-handoff.mjs → dist/lib/webhook-handoff.js} +107 -100
  115. package/dist/lib/webhook-verifiers.d.ts +20 -0
  116. package/{lib/webhook-verifiers.mjs → dist/lib/webhook-verifiers.js} +108 -104
  117. package/dist/lib/why.d.ts +9 -0
  118. package/{lib/why.mjs → dist/lib/why.js} +6 -6
  119. package/dist/log-safety.d.ts +20 -0
  120. package/dist/log-safety.js +308 -0
  121. package/dist/module-layering.d.ts +42 -0
  122. package/dist/module-layering.js +257 -0
  123. package/dist/module-shape.d.ts +47 -0
  124. package/{module-shape.mjs → dist/module-shape.js} +278 -236
  125. package/dist/naming.d.ts +49 -0
  126. package/dist/naming.js +246 -0
  127. package/dist/observability.d.ts +25 -0
  128. package/dist/observability.js +245 -0
  129. package/dist/operations.d.ts +23 -0
  130. package/{operations.mjs → dist/operations.js} +410 -332
  131. package/dist/project-graph.d.ts +9 -0
  132. package/{project-graph.mjs → dist/project-graph.js} +8 -13
  133. package/dist/projections.d.ts +11 -0
  134. package/{projections.mjs → dist/projections.js} +60 -57
  135. package/dist/query-safety.d.ts +21 -0
  136. package/{query-safety.mjs → dist/query-safety.js} +92 -108
  137. package/dist/realtime.d.ts +15 -0
  138. package/{realtime.mjs → dist/realtime.js} +108 -106
  139. package/dist/resilience.d.ts +15 -0
  140. package/dist/resilience.js +319 -0
  141. package/dist/schema-authority.d.ts +15 -0
  142. package/{schema-authority.mjs → dist/schema-authority.js} +256 -220
  143. package/dist/service-deps.d.ts +17 -0
  144. package/{service-deps.mjs → dist/service-deps.js} +133 -130
  145. package/dist/service-isolation.d.ts +8 -0
  146. package/dist/service-isolation.js +76 -0
  147. package/dist/size-budget.d.ts +9 -0
  148. package/{size-budget.mjs → dist/size-budget.js} +27 -27
  149. package/dist/sonar-parity.d.ts +5 -0
  150. package/{sonar-parity.mjs → dist/sonar-parity.js} +7 -7
  151. package/dist/spec-no-skip.d.ts +9 -0
  152. package/dist/spec-no-skip.js +81 -0
  153. package/dist/spec-quality.d.ts +10 -0
  154. package/{spec-quality.mjs → dist/spec-quality.js} +103 -87
  155. package/dist/suppression.d.ts +26 -0
  156. package/{suppression.mjs → dist/suppression.js} +30 -45
  157. package/dist/temporal.d.ts +9 -0
  158. package/{temporal.mjs → dist/temporal.js} +75 -65
  159. package/dist/test-world.d.ts +28 -0
  160. package/{test-world.mjs → dist/test-world.js} +102 -83
  161. package/dist/testing.d.ts +51 -0
  162. package/dist/testing.js +368 -0
  163. package/dist/third-party-owner.d.ts +8 -0
  164. package/{third-party-owner.mjs → dist/third-party-owner.js} +105 -91
  165. package/dist/transport.d.ts +24 -0
  166. package/{transport.mjs → dist/transport.js} +279 -240
  167. package/dist/type-safety.d.ts +25 -0
  168. package/dist/type-safety.js +297 -0
  169. package/dist/unit-spec.d.ts +30 -0
  170. package/{unit-spec.mjs → dist/unit-spec.js} +473 -399
  171. package/dist/uploads.d.ts +9 -0
  172. package/{uploads.mjs → dist/uploads.js} +62 -54
  173. package/dist/user-copy.d.ts +9 -0
  174. package/{user-copy.mjs → dist/user-copy.js} +76 -67
  175. package/dist/webhooks.d.ts +16 -0
  176. package/{webhooks.mjs → dist/webhooks.js} +243 -231
  177. package/package.json +23 -8
  178. package/runtime/knowledge/hfs/canon-pins.yaml +18 -11
  179. package/runtime/scripts/hfs/repo-identity.mjs +5 -4
  180. package/async-discipline.mjs +0 -83
  181. package/comments.mjs +0 -416
  182. package/edge-hardening.mjs +0 -139
  183. package/health-ready.mjs +0 -539
  184. package/jwt-alg.mjs +0 -45
  185. package/lib/ast.mjs +0 -88
  186. package/lib/import-source.mjs +0 -104
  187. package/lib/specifier.mjs +0 -27
  188. package/lib/subject-values.mjs +0 -55
  189. package/lib/types.mjs +0 -133
  190. package/log-safety.mjs +0 -303
  191. package/module-layering.mjs +0 -270
  192. package/naming.mjs +0 -251
  193. package/observability.mjs +0 -241
  194. package/resilience.mjs +0 -304
  195. package/service-isolation.mjs +0 -75
  196. package/spec-no-skip.mjs +0 -85
  197. package/testing.mjs +0 -384
  198. package/type-safety.mjs +0 -323
@@ -0,0 +1,412 @@
1
+ /**
2
+ * The rules that hold `comments.md`.
3
+ *
4
+ * Six rules, and each is careful about a different false positive:
5
+ *
6
+ * - `require-export-jsdoc` skips plain data constants. `export const MAX_ATTEMPTS = 3` is already
7
+ * fully described by its own name, and demanding a sentence there produces sentences that
8
+ * restate the name - which COMMENT-3 forbids. Only declarations with a surface get the check.
9
+ * - `require-public-member-jsdoc` (R109) judges only what a caller reaches: a private, protected or `#` member, the
10
+ * constructor and an index signature are not surface, overload signatures of one name share one doc, and a property
11
+ * set to a literal or a named constant is a data constant (COMMENT-1's reason). Product source only: the test tiers
12
+ * (`e2e`, `fixtures` of the slot manifest) document their spec-read shapes at the type.
13
+ * - `require-enum-member-jsdoc` checks an adjacent non-empty description, never whether it states a
14
+ * consequence. That half is read by a person, and the rule says so rather than pretending.
15
+ * - `no-non-ascii-source` takes no exemption marker, so text a program depends on
16
+ * lives in a message catalog (slot be.domain.messages, of any module tier, or be.feature.messages), the only place Vietnamese may appear. Specs
17
+ * and fixtures get no exemption.
18
+ * - `no-restated-name-jsdoc` (law 7) holds the decidable slice of law 3 - a doc block whose only
19
+ * content is the declared name re-spelled in words teaches nothing beyond the import line, so it
20
+ * is COMMENT-3's violation wearing COMMENT-1's shape. It fires only on an exact match between the
21
+ * doc's content words and the name's own words, so a doc that adds any real information is left
22
+ * alone - the rest of law 3 (whether a sentence explains something outside the line) is not
23
+ * decidable and stays a human read.
24
+ */
25
+ import { nameOrValue } from "./lib/ast.js";
26
+ import { hfsOf } from "./lib/hfs.js";
27
+ import { normalizePath } from "./lib/path.js";
28
+ import { hasSecondLanguage } from "../runtime/scripts/lib/language.mjs";
29
+ import { jsdocBefore, jsdocDescription } from "../runtime/scripts/lib/jsdoc.mjs";
30
+ /** The slots of the per-owner message catalogs: the only source files that may hold Vietnamese. */
31
+ const CATALOG_SLOTS = new Set(["be.domain.messages", "be.feature.messages"]);
32
+ /**
33
+ * The character classes this refuses, and why it is NOT simply "ASCII only".
34
+ *
35
+ * A first cut of this rule banned every non-ASCII codepoint. Measured against the reference
36
+ * repository it reported 857 offenders -- and every one was an em dash, a box-drawing run in a
37
+ * comment banner, or a middle dot. The code has used those freely and deliberately for its whole
38
+ * life, so "ASCII only" was not the law being recorded; it was a stricter law being invented, which
39
+ * is the one thing canon must not do.
40
+ *
41
+ * What the law actually refuses is three things, for three different reasons:
42
+ *
43
+ * - VIETNAMESE letters, because a reader who does not share the author's first language loses
44
+ * exactly the half of the reasoning that explains the surprising parts. Matched precisely, so a
45
+ * European loanword (`naive`, `facade`, `Muller`) is never a false positive.
46
+ * - EMOJI, because they carry tone rather than information, and tone reads differently to
47
+ * everybody.
48
+ * - DECORATIVE symbols -- check marks, crosses, arrows used as ornament -- for the same reason.
49
+ *
50
+ * Typographic punctuation is none of those and stays.
51
+ */
52
+ // Vietnamese letters are detected by scripts/lib/language.mjs (`hasSecondLanguage`), structural on characters and folded to NFC so a decomposed spelling is caught too.
53
+ /** Emoji and pictographs. */
54
+ const EMOJI = /[\u{1F300}-\u{1FAFF}\u{1F000}-\u{1F0FF}\u{2600}-\u{27BF}\u{FE0F}\u{1F1E6}-\u{1F1FF}]/u;
55
+ /** Ornamental marks that stand in for a word. */
56
+ const ORNAMENT = /[✅❌✔✖✗✘⭐⬆⬇➡⬅]/;
57
+ /**
58
+ * The fixtures slot that may carry localized text: a test data file that reproduces a real localized string. Placement is
59
+ * the whole marker (there is no pragma), and specs never live there, so a test title is never exempt.
60
+ */
61
+ const FIXTURE_SLOTS = new Set(["be.tests.fixtures.i18n"]);
62
+ /** The Vietnamese language's own name, which is a label rather than prose. */
63
+ const ENDONYM = /Ti\u1ebfng Vi\u1ec7t/;
64
+ /** Declarations whose surface other files depend on. */
65
+ const DOCUMENTED_KINDS = new Set([
66
+ "TSInterfaceDeclaration",
67
+ "TSTypeAliasDeclaration",
68
+ "TSEnumDeclaration",
69
+ "ClassDeclaration",
70
+ "FunctionDeclaration",
71
+ ]);
72
+ /** What a line offends with, or null. */
73
+ const offenceIn = (line) => {
74
+ const withoutEndonym = line.normalize("NFC").replace(ENDONYM, "");
75
+ if (hasSecondLanguage(withoutEndonym))
76
+ return "a Vietnamese letter";
77
+ if (EMOJI.test(withoutEndonym))
78
+ return "an emoji";
79
+ if (ORNAMENT.test(withoutEndonym))
80
+ return "an ornamental symbol";
81
+ return null;
82
+ };
83
+ /**
84
+ * Whether an exported declaration has a surface a caller documents: a data constant is already described by its name,
85
+ * and a kind outside DOCUMENTED_KINDS has no surface at all.
86
+ */
87
+ const hasDocumentedSurface = (declaration) => {
88
+ if (declaration.type === "VariableDeclaration") {
89
+ // a later declarator can expose a function even when the first binding is plain data
90
+ return declaration.declarations.some(({ init }) => Boolean(init)
91
+ && (init?.type === "ArrowFunctionExpression" || init?.type === "FunctionExpression"));
92
+ }
93
+ return DOCUMENTED_KINDS.has(declaration.type);
94
+ };
95
+ /** Whether the adjacent JSDoc has a declaration description rather than only tags or a file header. */
96
+ const hasJsdocBefore = (sourceCode, node) => jsdocBefore(sourceCode, node) !== null;
97
+ /** The declared name, for the message. */
98
+ const nameOf = (declaration) => {
99
+ if ("id" in declaration && declaration.id)
100
+ return declaration.id.name;
101
+ const first = "declarations" in declaration && declaration.declarations && declaration.declarations[0];
102
+ return (first && first.id && first.id.type === "Identifier" && first.id.name) || "this export";
103
+ };
104
+ /** The node a finding on a declaration points at: its name, else the declaration itself. */
105
+ const reportedNode = (declaration) => ("id" in declaration && declaration.id) || declaration;
106
+ // -- COMMENT-1 -------------------------------------------------------------------------------------
107
+ /** Every export with a surface opens with a doc block. */
108
+ export const requireExportJsdoc = {
109
+ meta: {
110
+ type: "suggestion",
111
+ docs: { description: "An exported class/interface/type/enum/function opens with JSDoc." },
112
+ schema: [],
113
+ messages: {
114
+ jsdoc: "`{{name}}` is exported without an adjacent JSDoc description. This is surface other files depend on, and a name plus a signature says what it TAKES - never what it is for, or when to reach for it rather than the thing beside it.",
115
+ },
116
+ },
117
+ create(context) {
118
+ const sourceCode = context.sourceCode || context.getSourceCode();
119
+ const check = (node) => {
120
+ const declaration = node.declaration;
121
+ // a re-export has nothing here to attach a doc to
122
+ if (!declaration)
123
+ return;
124
+ if (!hasDocumentedSurface(declaration))
125
+ return;
126
+ if (hasJsdocBefore(sourceCode, node))
127
+ return;
128
+ context.report({
129
+ node: reportedNode(declaration),
130
+ messageId: "jsdoc",
131
+ data: { name: nameOf(declaration) },
132
+ });
133
+ };
134
+ return {
135
+ ExportNamedDeclaration: check,
136
+ ExportDefaultDeclaration: check,
137
+ };
138
+ },
139
+ };
140
+ // -- COMMENT-3 (R109) -----------------------------------------------------------------------------
141
+ /** Class members a caller reaches: everything but the constructor, static blocks and index signatures. */
142
+ const CLASS_MEMBER_KINDS = new Set([
143
+ "MethodDefinition",
144
+ "PropertyDefinition",
145
+ "AccessorProperty",
146
+ "TSAbstractMethodDefinition",
147
+ "TSAbstractPropertyDefinition",
148
+ "TSAbstractAccessorProperty",
149
+ ]);
150
+ /** Interface and type-literal members a caller reaches; call, construct and index signatures have no name to document. */
151
+ const SIGNATURE_MEMBER_KINDS = new Set(["TSPropertySignature", "TSMethodSignature"]);
152
+ /**
153
+ * A property set to a literal or a named constant (`name = "CreatePlans1758"`, `readonly queue = PLAN_QUEUE`) is already
154
+ * described by its own name and value, the same reason COMMENT-1 leaves a data constant alone.
155
+ */
156
+ const isDataProperty = (member) => {
157
+ if (member.type !== "PropertyDefinition" || !member.value)
158
+ return false;
159
+ const value = member.value;
160
+ if (value.type === "Literal" || value.type === "Identifier")
161
+ return true;
162
+ if (value.type === "TemplateLiteral")
163
+ return value.expressions.length === 0;
164
+ return value.type === "MemberExpression" && !value.computed && value.object.type === "Identifier";
165
+ };
166
+ /** The test tiers of the slot manifest: spec-read shapes there are documented at the type, not field by field. */
167
+ const TEST_TIERS = new Set(["e2e", "fixtures"]);
168
+ /** The members of an exported class, interface or object type alias that are its public surface. */
169
+ const publicMembersOf = (declaration) => {
170
+ if (declaration.type === "ClassDeclaration") {
171
+ return declaration.body.body.filter((member) => CLASS_MEMBER_KINDS.has(member.type)
172
+ && !("kind" in member && member.kind === "constructor")
173
+ && !isDataProperty(member)
174
+ && !("key" in member && member.key?.type === "PrivateIdentifier")
175
+ && !("accessibility" in member && member.accessibility === "private")
176
+ && !("accessibility" in member && member.accessibility === "protected"));
177
+ }
178
+ if (declaration.type === "TSInterfaceDeclaration")
179
+ return declaration.body.body.filter((member) => SIGNATURE_MEMBER_KINDS.has(member.type));
180
+ if (declaration.type === "TSTypeAliasDeclaration") {
181
+ const type = declaration.typeAnnotation;
182
+ const literals = type.type === "TSTypeLiteral" ? [type]
183
+ : type.type === "TSIntersectionType" ? type.types.filter((part) => part.type === "TSTypeLiteral") : [];
184
+ return literals.flatMap((literal) => literal.members.filter((member) => SIGNATURE_MEMBER_KINDS.has(member.type)));
185
+ }
186
+ return [];
187
+ };
188
+ /** The name a member is reached by, with its static side kept apart; null for a computed key the rule cannot name. */
189
+ const memberKey = (member) => {
190
+ if ("computed" in member && member.computed)
191
+ return null;
192
+ const key = "key" in member ? member.key : undefined;
193
+ const name = key?.type === "Identifier" ? key.name : key?.type === "Literal" ? String(key.value) : null;
194
+ return name === null ? null : `${"static" in member && member.static ? "static " : ""}${name}`;
195
+ };
196
+ /** Every public member of an exported class, interface or object type opens with a doc block (BE-COMMENT-3). */
197
+ export const requirePublicMemberJsdoc = {
198
+ meta: {
199
+ type: "suggestion",
200
+ docs: { description: "Every public member of an exported class, interface or object type alias opens with JSDoc." },
201
+ schema: [],
202
+ messages: {
203
+ jsdoc: "`{{owner}}.{{name}}` is public surface without an adjacent JSDoc description. A caller reaches the member, not the type's doc: say what it is for, what calling or reading it causes, or what it holds.",
204
+ },
205
+ },
206
+ create(context) {
207
+ const sourceCode = context.sourceCode || context.getSourceCode();
208
+ if (TEST_TIERS.has(hfsOf(context).tierOf(normalizePath(context.filename))))
209
+ return {};
210
+ const check = (node) => {
211
+ const declaration = node.declaration;
212
+ if (!declaration || !("id" in declaration) || !declaration.id)
213
+ return;
214
+ const id = declaration.id;
215
+ // overload signatures share one name; a doc on any of them documents the member
216
+ const groups = new Map();
217
+ for (const member of publicMembersOf(declaration)) {
218
+ const key = memberKey(member);
219
+ // a member memberKey names always has a key node; the second test only proves that to the types
220
+ const keyNode = "key" in member ? member.key : null;
221
+ if (key === null || keyNode === null)
222
+ continue;
223
+ let group = groups.get(key);
224
+ if (!group) {
225
+ group = { key: keyNode, members: [] };
226
+ groups.set(key, group);
227
+ }
228
+ group.members.push(member);
229
+ }
230
+ for (const [key, group] of groups) {
231
+ if (group.members.some((member) => hasJsdocBefore(sourceCode, member)))
232
+ continue;
233
+ context.report({ node: group.key, messageId: "jsdoc", data: { owner: "name" in id ? id.name : undefined, name: key.replace(/^static /, "") } });
234
+ }
235
+ };
236
+ return {
237
+ ExportNamedDeclaration: check,
238
+ ExportDefaultDeclaration: check,
239
+ };
240
+ },
241
+ };
242
+ // -- COMMENT-2 -------------------------------------------------------------------------------------
243
+ /** Every member of an exported enum carries its own doc. */
244
+ export const requireEnumMemberJsdoc = {
245
+ meta: {
246
+ type: "suggestion",
247
+ docs: { description: "Every member of an exported enum carries its own JSDoc." },
248
+ schema: [],
249
+ messages: {
250
+ jsdoc: "Enum member `{{name}}` has no adjacent JSDoc description. State what CHOOSING it causes, not what it is called - a member is picked at a call site far from the switch that gives it meaning. (A rule can only see that a doc exists; whether it states a consequence is read by a person.)",
251
+ },
252
+ },
253
+ create(context) {
254
+ const sourceCode = context.sourceCode || context.getSourceCode();
255
+ return {
256
+ TSEnumDeclaration(node) {
257
+ if (!node.parent || node.parent.type !== "ExportNamedDeclaration")
258
+ return;
259
+ for (const member of node.members || []) {
260
+ if (hasJsdocBefore(sourceCode, member))
261
+ continue;
262
+ const name = member.id && nameOrValue(member.id);
263
+ context.report({ node: member, messageId: "jsdoc", data: { name: name || "?" } });
264
+ }
265
+ },
266
+ };
267
+ },
268
+ };
269
+ // -- COMMENT-4 -------------------------------------------------------------------------------------
270
+ /** Source prose is English; there is no exemption marker. */
271
+ export const noNonAsciiSource = {
272
+ meta: {
273
+ type: "problem",
274
+ docs: { description: "Source stays English; no exemption marker." },
275
+ schema: [],
276
+ messages: {
277
+ nonAscii: "This line carries {{offence}}. The bar is a reader who does not share the author's first language: a codebase with two languages in it has somebody for whom half the reasoning is unavailable, and it is the half explaining the surprising parts - and an emoji or an ornament carries tone rather than information, which reads differently to everybody. There is no exemption marker: write the text in English, or keep product copy in a locale or data file.",
278
+ },
279
+ },
280
+ create(context) {
281
+ const sourceCode = context.sourceCode || context.getSourceCode();
282
+ // a message catalog is product copy in two languages; every other file is prose for the next reader
283
+ const slot = hfsOf(context).slotOf(context.filename);
284
+ if (CATALOG_SLOTS.has(slot) || FIXTURE_SLOTS.has(slot))
285
+ return {};
286
+ return {
287
+ "Program:exit"(node) {
288
+ const lines = sourceCode.getLines();
289
+ for (const [index, line] of lines.entries()) {
290
+ const offence = offenceIn(line);
291
+ if (offence === null)
292
+ continue;
293
+ context.report({
294
+ node,
295
+ loc: {
296
+ line: index + 1,
297
+ column: 0,
298
+ },
299
+ messageId: "nonAscii",
300
+ data: {
301
+ offence,
302
+ },
303
+ });
304
+ }
305
+ },
306
+ };
307
+ },
308
+ };
309
+ // -- law 7 -------------------------------------------------------------------------------------
310
+ /** Splits a declared name into its lowercase words, so `readUser` compares against "read user". */
311
+ const wordsOf = (name) => (String(name || "")
312
+ .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
313
+ .replace(/[_-]+/g, " ")
314
+ .toLowerCase()
315
+ .match(/[a-z0-9]+/g) || []);
316
+ /**
317
+ * Filler a doc contributes no information by using: articles and linking words, plus the two generic
318
+ * nouns the law's own anchor examples restate with ("the pending state", "the read user function").
319
+ * Nothing here strips a word that could carry real content, so a doc that explains anything beyond
320
+ * the name keeps enough leftover words to fail the equality check below.
321
+ */
322
+ const RESTATEMENT_FILLER = new Set(["a", "an", "the", "is", "of", "for", "to", "this", "that", "function", "state"]);
323
+ /** The content words a doc comment contributes once filler is stripped out. */
324
+ const docContentWords = (comment) => (jsdocDescription(comment).match(/[A-Za-z]+/g) || [])
325
+ .map((word) => word.toLowerCase())
326
+ .filter((word) => !RESTATEMENT_FILLER.has(word));
327
+ /** Whether a doc's leftover content words are exactly the declared name's own words - nothing added. */
328
+ const isPureRestatement = (comment, declaredName) => {
329
+ const content = docContentWords(comment);
330
+ const identifier = wordsOf(declaredName);
331
+ if (content.length === 0 || identifier.length === 0)
332
+ return false;
333
+ const contentSet = new Set(content);
334
+ const identifierSet = new Set(identifier);
335
+ if (contentSet.size !== identifierSet.size)
336
+ return false;
337
+ for (const word of contentSet)
338
+ if (!identifierSet.has(word))
339
+ return false;
340
+ return true;
341
+ };
342
+ /** A doc block that only re-spells the declared name is COMMENT-3's violation wearing COMMENT-1's shape. */
343
+ export const noRestatedNameJsdoc = {
344
+ meta: {
345
+ type: "suggestion",
346
+ docs: {
347
+ description: "COMMENT-3, law 7: a doc block that restates the declared name is a COMMENT-3 violation wearing a COMMENT-1 shape, even while the lint gate that checks a doc EXISTS stays green.",
348
+ },
349
+ schema: [],
350
+ messages: {
351
+ restated: "This doc block only re-spells `{{name}}` in words. A name plus a signature already says what it TAKES; the doc has to say what it is FOR, or what choosing it causes, or it is a COMMENT-3 violation wearing a COMMENT-1 shape. Delete the restatement and write the reason instead.",
352
+ },
353
+ },
354
+ create(context) {
355
+ const sourceCode = context.sourceCode || context.getSourceCode();
356
+ const checkExport = (node) => {
357
+ const declaration = node.declaration;
358
+ // a re-export has nothing here to attach a doc to
359
+ if (!declaration)
360
+ return;
361
+ if (!hasDocumentedSurface(declaration))
362
+ return;
363
+ const doc = jsdocBefore(sourceCode, node);
364
+ if (!doc)
365
+ return;
366
+ const name = nameOf(declaration);
367
+ if (!isPureRestatement(doc, name))
368
+ return;
369
+ context.report({ node: reportedNode(declaration), messageId: "restated", data: { name } });
370
+ };
371
+ return {
372
+ ExportNamedDeclaration: checkExport,
373
+ ExportDefaultDeclaration: checkExport,
374
+ TSEnumDeclaration(node) {
375
+ if (!node.parent || node.parent.type !== "ExportNamedDeclaration")
376
+ return;
377
+ for (const member of node.members || []) {
378
+ const doc = jsdocBefore(sourceCode, member);
379
+ if (!doc)
380
+ continue;
381
+ const name = member.id && nameOrValue(member.id);
382
+ if (!name || !isPureRestatement(doc, name))
383
+ continue;
384
+ context.report({ node: member, messageId: "restated", data: { name } });
385
+ }
386
+ },
387
+ };
388
+ },
389
+ };
390
+ /** The rules this law contributes to the plugin. */
391
+ export const rules = {
392
+ "require-export-jsdoc": requireExportJsdoc,
393
+ "require-enum-member-jsdoc": requireEnumMemberJsdoc,
394
+ "require-public-member-jsdoc": requirePublicMemberJsdoc,
395
+ "no-non-ascii-source": noNonAsciiSource,
396
+ "no-restated-name-jsdoc": noRestatedNameJsdoc,
397
+ };
398
+ /**
399
+ * The level this law asks for, as the plugin's own opinion.
400
+ *
401
+ * `no-non-ascii-source` replaces three separate rules in the reference plugin - one for Vietnamese,
402
+ * one for emoji, one for decorative symbols. They were three character classes answering one
403
+ * question, and a reader who hit the emoji rule learned nothing about the other two. One rule with
404
+ * one reason is easier to obey, and impossible to satisfy by switching alphabets.
405
+ */
406
+ export const recommended = {
407
+ "starci-be/require-export-jsdoc": "error",
408
+ "starci-be/require-enum-member-jsdoc": "error",
409
+ "starci-be/require-public-member-jsdoc": "error",
410
+ "starci-be/no-non-ascii-source": "error",
411
+ "starci-be/no-restated-name-jsdoc": "error",
412
+ };
@@ -0,0 +1,24 @@
1
+ import type { Recommended, RuleModule } from "./lib/rule.js";
2
+ /** Only EnvSource, the app bootstrap roles and the test world read the process environment. */
3
+ export declare const noDirectEnvRead: RuleModule;
4
+ /** Config is parsed once, in `main.ts` or its app's env file; other app roles do not read the environment. */
5
+ export declare const configParsedInMain: RuleModule;
6
+ /** No secret or URL value has a default of any kind: a missing value stops the boot. */
7
+ export declare const noSecretDefault: RuleModule;
8
+ /**
9
+ * Whether a value's own name says it IS a credential: its last word is one (`password`, `accessToken`, `clientSecret`,
10
+ * `signingKey`), unless the name is an UPPER_SNAKE constant naming a key or a counter or cursor qualifies it. Shared by the
11
+ * comparison rule here and the error rule of R71.
12
+ */
13
+ export declare const isCredentialName: (name: string) => boolean;
14
+ /** A secret is compared with `timingSafeEqual`, never with an equality operator. */
15
+ export declare const secretCompareTimingSafe: RuleModule;
16
+ /** The rules this law contributes to the plugin. */
17
+ export declare const rules: {
18
+ "no-direct-env-read": RuleModule;
19
+ "config-parsed-in-main": RuleModule;
20
+ "no-secret-default": RuleModule;
21
+ "secret-compare-timing-safe": RuleModule;
22
+ };
23
+ /** All four start at error: a secret in source or a timing leak is never a warning. */
24
+ export declare const recommended: Recommended;