@orkestrel/scaffold 0.0.140 → 0.0.142

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/dist/bin/main.js CHANGED
@@ -10,7 +10,7 @@ import { readdirSync } from "node:fs";
10
10
  import { parseArgs } from "node:util";
11
11
  var package_default = {
12
12
  name: "@orkestrel/scaffold",
13
- version: "0.0.140",
13
+ version: "0.0.142",
14
14
  description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
15
15
  keywords: [
16
16
  "audit",
@@ -37,7 +37,8 @@ signatures or the reading before you run the item over the checkout.
37
37
 
38
38
  ## Keys outside the census
39
39
 
40
- - Run no item for the **Variables** bullet; the lint rules it names decide it.
40
+ - Run no item for the **Variables** and **Counted loops** bullets; the lint rules they name decide
41
+ them, apart from where a counted loop is worth writing, which review rules.
41
42
  - Run no item for these keys: `derivation.expression`, `iteration.counter`, `try.helper`, `try.log`, `running.definition`, `lists.derived`, `logs.loop`,
42
43
  `logs.scan`, `exemptions.reach`, `percall.entity`, `percall.lifetime`, `percall.relative`,
43
44
  `entity.home`, `entity.pointers`, `slots.route`, `slots.exclusions`, `resets.home`, `bound.read`,
@@ -44,7 +44,7 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
44
44
  | Package | Version | Layer | Runtime dependencies | Peer dependencies |
45
45
  | ----------------------- | --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
46
46
  | `@orkestrel/abort` | `0.0.19` | L1 | `@orkestrel/contract` `^0.0.26` | |
47
- | `@orkestrel/agent` | `0.0.46` | L5 | `@orkestrel/tool` `^0.0.25`, `@orkestrel/abort` `^0.0.19`, `@orkestrel/queue` `^0.0.25`, `@orkestrel/budget` `^0.0.20`, `@orkestrel/ndjson` `^0.0.19`, `@orkestrel/emitter` `^0.0.18`, `@orkestrel/timeout` `^0.0.19`, `@orkestrel/contract` `^0.0.26`, `@orkestrel/database` `^0.0.28`, `@orkestrel/workflow` `^0.0.31`, `@orkestrel/workspace` `^0.0.21` | |
47
+ | `@orkestrel/agent` | `0.0.47` | L5 | `@orkestrel/tool` `^0.0.25`, `@orkestrel/abort` `^0.0.19`, `@orkestrel/queue` `^0.0.25`, `@orkestrel/budget` `^0.0.20`, `@orkestrel/ndjson` `^0.0.19`, `@orkestrel/emitter` `^0.0.18`, `@orkestrel/timeout` `^0.0.19`, `@orkestrel/contract` `^0.0.26`, `@orkestrel/database` `^0.0.28`, `@orkestrel/workflow` `^0.0.31`, `@orkestrel/workspace` `^0.0.21` | |
48
48
  | `@orkestrel/brief` | `0.0.20` | L4 | `@orkestrel/reason` `^0.0.20`, `@orkestrel/emitter` `^0.0.18`, `@orkestrel/contract` `^0.0.26`, `@orkestrel/interpret` `^0.0.25` | |
49
49
  | `@orkestrel/browser` | `0.0.35` | L5 | `@orkestrel/mcp` `^0.0.45`, `@orkestrel/html` `^0.0.18`, `@orkestrel/pool` `^0.0.23`, `@orkestrel/tool` `^0.0.25`, `@orkestrel/codec` `^0.0.12`, `@orkestrel/router` `^0.0.24`, `@orkestrel/server` `^0.0.30`, `@orkestrel/emitter` `^0.0.18`, `@orkestrel/process` `^0.0.22`, `@orkestrel/contract` `^0.0.26`, `@orkestrel/markdown` `^0.0.23`, `@orkestrel/websocket` `^0.0.21` | |
50
50
  | `@orkestrel/budget` | `0.0.20` | L1 | `@orkestrel/contract` `^0.0.26` | |
@@ -67,7 +67,7 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
67
67
  | `@orkestrel/middleware` | `0.0.36` | L4 | `@orkestrel/budget` `^0.0.20`, `@orkestrel/timeout` `^0.0.19`, `@orkestrel/contract` `^0.0.26` | `@orkestrel/router` `^0.0.24`, `@orkestrel/server` `^0.0.30`, `@orkestrel/database` `^0.0.28` |
68
68
  | `@orkestrel/msg` | `0.0.19` | L2 | `@orkestrel/codec` `^0.0.12`, `@orkestrel/contract` `^0.0.26` | |
69
69
  | `@orkestrel/ndjson` | `0.0.19` | L1 | `@orkestrel/contract` `^0.0.26` | |
70
- | `@orkestrel/ollama` | `0.0.40` | L6 | `@orkestrel/tool` `^0.0.25`, `@orkestrel/agent` `^0.0.46`, `@orkestrel/budget` `^0.0.20`, `@orkestrel/ndjson` `^0.0.19`, `@orkestrel/emitter` `^0.0.18`, `@orkestrel/process` `^0.0.22`, `@orkestrel/contract` `^0.0.26` | |
70
+ | `@orkestrel/ollama` | `0.0.44` | L6 | `@orkestrel/tool` `^0.0.25`, `@orkestrel/agent` `^0.0.47`, `@orkestrel/budget` `^0.0.20`, `@orkestrel/ndjson` `^0.0.19`, `@orkestrel/emitter` `^0.0.18`, `@orkestrel/process` `^0.0.22`, `@orkestrel/contract` `^0.0.26` | |
71
71
  | `@orkestrel/pool` | `0.0.23` | L2 | `@orkestrel/emitter` `^0.0.18`, `@orkestrel/contract` `^0.0.26` | |
72
72
  | `@orkestrel/probe` | `0.0.32` | L5 | `@orkestrel/lsp` `^0.0.17`, `@orkestrel/mcp` `^0.0.45`, `@orkestrel/pool` `^0.0.23`, `@orkestrel/tool` `^0.0.25`, `@orkestrel/emitter` `^0.0.18`, `@orkestrel/process` `^0.0.22`, `@orkestrel/timeout` `^0.0.19`, `@orkestrel/contract` `^0.0.26` | `vitest` `^4.1.12 \|\| ^5.1.0`, `typescript` `^6.0.3 \|\| ^7.0.2` |
73
73
  | `@orkestrel/process` | `0.0.22` | L2 | `@orkestrel/emitter` `^0.0.18`, `@orkestrel/contract` `^0.0.26` | |
@@ -78,12 +78,12 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
78
78
  | `@orkestrel/reason` | `0.0.20` | L2 | `@orkestrel/emitter` `^0.0.18`, `@orkestrel/contract` `^0.0.26` | |
79
79
  | `@orkestrel/relation` | `0.0.26` | L3 | `@orkestrel/emitter` `^0.0.18`, `@orkestrel/contract` `^0.0.26`, `@orkestrel/database` `^0.0.28` | |
80
80
  | `@orkestrel/router` | `0.0.24` | L2 | `@orkestrel/abort` `^0.0.19`, `@orkestrel/emitter` `^0.0.18`, `@orkestrel/contract` `^0.0.26` | |
81
- | `@orkestrel/scaffold` | `0.0.139` | L3 | `@orkestrel/console` `^0.0.21`, `@orkestrel/emitter` `^0.0.17`, `@orkestrel/process` `^0.0.21`, `@orkestrel/contract` `^0.0.26`, `@orkestrel/markdown` `^0.0.22`, `@orkestrel/template` `^0.0.15` | |
81
+ | `@orkestrel/scaffold` | `0.0.141` | L3 | `@orkestrel/console` `^0.0.22`, `@orkestrel/emitter` `^0.0.18`, `@orkestrel/process` `^0.0.22`, `@orkestrel/contract` `^0.0.26`, `@orkestrel/markdown` `^0.0.23`, `@orkestrel/template` `^0.0.16` | |
82
82
  | `@orkestrel/sea` | `0.0.25` | L3 | `@orkestrel/emitter` `^0.0.18`, `@orkestrel/process` `^0.0.22`, `@orkestrel/contract` `^0.0.26` | |
83
83
  | `@orkestrel/server` | `0.0.30` | L3 | `@orkestrel/abort` `^0.0.19`, `@orkestrel/codec` `^0.0.12`, `@orkestrel/router` `^0.0.24`, `@orkestrel/emitter` `^0.0.18`, `@orkestrel/timeout` `^0.0.19`, `@orkestrel/contract` `^0.0.26` | |
84
84
  | `@orkestrel/sqlite` | `0.0.20` | L1 | `@orkestrel/contract` `^0.0.26` | |
85
85
  | `@orkestrel/sse` | `0.0.16` | L2 | `@orkestrel/codec` `^0.0.12`, `@orkestrel/contract` `^0.0.26` | |
86
- | `@orkestrel/study` | `0.0.22` | L7 | `@orkestrel/tool` `^0.0.25`, `@orkestrel/abort` `^0.0.19`, `@orkestrel/agent` `^0.0.46`, `@orkestrel/budget` `^0.0.20`, `@orkestrel/ollama` `^0.0.40`, `@orkestrel/timeout` `^0.0.19`, `@orkestrel/contract` `^0.0.26` | |
86
+ | `@orkestrel/study` | `0.0.28` | L7 | `@orkestrel/tool` `^0.0.25`, `@orkestrel/abort` `^0.0.19`, `@orkestrel/agent` `^0.0.47`, `@orkestrel/budget` `^0.0.20`, `@orkestrel/ollama` `^0.0.44`, `@orkestrel/timeout` `^0.0.19`, `@orkestrel/contract` `^0.0.26` | |
87
87
  | `@orkestrel/table` | `0.0.19` | L2 | `@orkestrel/emitter` `^0.0.18`, `@orkestrel/contract` `^0.0.26` | |
88
88
  | `@orkestrel/template` | `0.0.16` | L2 | `@orkestrel/emitter` `^0.0.18`, `@orkestrel/contract` `^0.0.26` | |
89
89
  | `@orkestrel/terminal` | `0.0.28` | L3 | `@orkestrel/sse` `^0.0.16`, `@orkestrel/form` `^0.0.20`, `@orkestrel/console` `^0.0.22`, `@orkestrel/emitter` `^0.0.18`, `@orkestrel/contract` `^0.0.26`, `@orkestrel/database` `^0.0.28` | |
@@ -105,9 +105,11 @@ neither reads meaning.
105
105
  data-kind file, that every centralized declaration is exported, that a class sits in its matching
106
106
  implementation or errors file, that `constants.ts` declares only UPPER_SNAKE_CASE consts with
107
107
  no bare collection literal, and that every interface or type-alias property is `readonly`.
108
- - The plugin proves that no file declares a `let` that `prefer-const` leaves, and, over
108
+ - The plugin proves that no file declares a `let` that `prefer-const` leaves, other than the counted
109
+ loop index and accumulators `.claude/rules/typescript.md` § Bindings admits, and, over
109
110
  `POLICY_NESTED_GLOBS` and `POLICY_SCRIPT_GLOBS`, that no function sits inside another outside the
110
- callback positions.
111
+ callback positions. It does not read whether a counted loop's body computes over a typed array,
112
+ an array, or a string; review rules that.
111
113
  - The plugin proves that a skill script exports every top-level declaration with a doc block and
112
114
  runs nothing but its entry guard, over `POLICY_SCRIPT_GLOBS`.
113
115
  - The sweep proves that no source, test, config, script, or sheet file carries an `eslint-disable`,
@@ -40,16 +40,27 @@ The non-negotiables and design laws in `AGENTS.md` apply without exception and a
40
40
 
41
41
  ## Bindings
42
42
 
43
- - **Variables.** Never write a `let` or `var` declaration, at module scope, in a function, in a loop
44
- head, or in a test; declare each variable with the `const` keyword. Never assign to a parameter or
43
+ - **Variables.** Never write a `var` declaration. Declare each variable with the `const` keyword,
44
+ and write `let` only where the **Counted loops** bullet admits it. Never assign to a parameter or
45
45
  a `catch` binding, whether by `=`, by a compound operator such as `+=` or `??=`, by `++` or `--`,
46
46
  or as a destructuring target. The lint rules `no-var`, `prefer-const`, `policy/no-let`,
47
- `no-param-reassign`, and `no-ex-assign` enforce this bullet.
48
- - **Derivation.** Derive a value instead of accumulating it: write the expression that produces it
49
- (`some`, `every`, `find`, `filter`, `map`, `reduce`, a conditional expression), or extract a
50
- `{verb}{Noun}` helper that returns it. Build text from its parts with `join` or a template literal,
51
- never with a fold whose step appends a part to the text it carries.
52
- - **Iteration.** Iterate with `for…of` over `entries()` or an iterable instead of an index counter.
47
+ `no-param-reassign`, and `no-ex-assign` enforce this bullet and the `let` shapes of the next.
48
+ - **Counted loops.** In a `for (…; …; …)` statement, declare the index with `let` in the head when
49
+ the update clause makes its only write; a bound that nothing writes can sit beside it in that
50
+ head. Declare an accumulator with `let` and a value in a block inside a function, before an
51
+ unlabeled loop of that form with only variable declarations between them; write it only in that
52
+ loop's body and read it only in that loop and after it. Never write an index or an accumulator
53
+ inside a nested function or class, never write an accumulator inside a `while`, `do…while`, or
54
+ `try` statement, and never read an accumulator from a nested function or class. Write a counted
55
+ loop only where its body computes from the index over a typed array, an array, or a string, and
56
+ iterate everything else with `for…of`.
57
+ - **Derivation.** Outside a counted loop's accumulator, derive a value instead of accumulating it:
58
+ write the expression that produces it (`some`, `every`, `find`, `filter`, `map`, `reduce`, a
59
+ conditional expression), or extract a `{verb}{Noun}` helper that returns it. Build text from its
60
+ parts with `join` or a template literal, never with a fold whose step appends a part to the text
61
+ it carries.
62
+ - **Iteration.** Iterate with `for…of` over `entries()` or an iterable instead of an index counter,
63
+ except in a counted loop.
53
64
  - **Try results.** Take a value out of a `try` block through a helper that runs the block and
54
65
  returns the value. Treat a log that the block appends to as a log rather than such a value, and
55
66
  apply the **Lists and logs** rule to it.
@@ -102,8 +113,10 @@ The non-negotiables and design laws in `AGENTS.md` apply without exception and a
102
113
  value, and one write per key into a fresh local object that builds a fixture a literal cannot
103
114
  express, such as a cycle or a sparse array;
104
115
  - a preallocated typed array written once per index, in index order, as the input a byte API
105
- requires, such as zlib, a PNG encoder, or `Buffer`, which is a platform-API write; write no
106
- index twice.
116
+ requires, such as zlib, a PNG encoder, or `Buffer`, which is a platform-API write, or as the
117
+ result a counted loop computes into a typed array its own function creates; write no index
118
+ twice;
119
+ - a counted loop's index and its accumulators, which the **Counted loops** bullet admits.
107
120
  - **Per-call state.** Keep state that the awaits or callbacks of one call change, other than a log,
108
121
  in `#` fields of an entity created for that call. Treat a list that more than one concurrently
109
122
  pending async path of one call appends to, such as the workers of a pool, as state of that call:
@@ -302,19 +302,19 @@ then runs the configured scoped checks that prove environment isolation.
302
302
  - Lint is a separate complementary gate; neither lint nor root checking replaces
303
303
  environment-isolation checks.
304
304
 
305
- | Scope | `lib` | `types` | Permitted host globals |
306
- | ---------------------------- | --------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
307
- | `src:core`, `app:core` | `["ESNext","WebWorker"]` | `[]` | WHATWG web interop: fetch family, streams, URL, Abort, encoders, crypto, timers, console, DOMException, structuredClone; no DOM, no Node |
308
- | `src:browser`, `app:browser` | `["ESNext","DOM","DOM.Iterable"]` | `["vite/client"]` | DOM; no Node |
309
- | `src:server`, `app:server` | `["ESNext"]` | `["node"]` | Node; no DOM |
310
- | `src:styles`, `src:<name>` | `["ESNext"]` | `["vite/client"]` | Vite SCSS module declaration only |
311
- | `src:vue` | `["ESNext","DOM","DOM.Iterable"]` | `["vite/client"]` | DOM; no Node |
312
- | `app:vue` | `["ESNext","DOM","DOM.Iterable"]` | `["vite/client","vue"]` | DOM and Vue; no Node |
305
+ | Scope | `lib` | `types` | Permitted host globals |
306
+ | ------------------------------------- | --------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
307
+ | `src:core`, `app:core` | `["ESNext","WebWorker"]` | `[]` | Web interop: fetch family, streams, URL, Abort, encoders, crypto, timers, console, DOMException, structuredClone, WebAssembly; no DOM, no Node |
308
+ | `src:browser`, `app:browser` | `["ESNext","DOM","DOM.Iterable"]` | `["vite/client"]` | DOM; no Node |
309
+ | `src:server`, `app:server`, `src:bin` | `["ESNext","WebWorker"]` | `["node"]` | Node, plus the core globals; no DOM |
310
+ | `src:styles`, `src:<name>` | `["ESNext"]` | `["vite/client"]` | Vite SCSS module declaration only |
311
+ | `src:vue` | `["ESNext","DOM","DOM.Iterable"]` | `["vite/client"]` | DOM; no Node |
312
+ | `app:vue` | `["ESNext","DOM","DOM.Iterable"]` | `["vite/client","vue"]` | DOM and Vue; no Node |
313
313
 
314
314
  Strict core is load-bearing:
315
315
 
316
316
  - Put a host-dependent helper in its host environment. A `generateId` reading `node:crypto` belongs in server, not core.
317
- - Core declares `WebWorker` to widen the WHATWG interop surface, not to admit a worker host. Policy fences these worker-only globals out of core sources: `name`, `onrtctransform`, `close`, `postMessage`, `dispatchEvent`, `location`, `onerror`, `onlanguagechange`, `onoffline`, `ononline`, `onrejectionhandled`, `onunhandledrejection`, `self`, `importScripts`, `fonts`, `caches`, `crossOriginIsolated`, `indexedDB`, `isSecureContext`, `origin`, `scheduler`, `createImageBitmap`, `reportError`, `cancelAnimationFrame`, `requestAnimationFrame`, `onmessage`, `onmessageerror`, `addEventListener`, `removeEventListener`.
317
+ - Core declares `WebWorker` to widen the web interop surface, not to admit a worker host. Give `src:server`, `app:server`, and `src:bin` core's library; a browser scope keeps DOM, which declares every global core names. The vendored `.oxlintrc.json` fences these worker-only globals out of `src/core`, `app/core`, `src/server`, `app/server`, and `src/bin` sources through `no-restricted-globals`, which reads an unresolved identifier and not a `globalThis` member: `name`, `onrtctransform`, `close`, `postMessage`, `dispatchEvent`, `location`, `onerror`, `onlanguagechange`, `onoffline`, `ononline`, `onrejectionhandled`, `onunhandledrejection`, `self`, `importScripts`, `fonts`, `caches`, `crossOriginIsolated`, `indexedDB`, `isSecureContext`, `origin`, `scheduler`, `createImageBitmap`, `reportError`, `cancelAnimationFrame`, `requestAnimationFrame`, `onmessage`, `onmessageerror`, `addEventListener`, `removeEventListener`.
318
318
 
319
319
  Build/check config alignment:
320
320
 
@@ -2,6 +2,7 @@
2
2
  export interface PolicyNode {
3
3
  readonly type: string
4
4
  readonly range: [number, number]
5
+ readonly parent?: PolicyNode | null
5
6
  }
6
7
 
7
8
  /** Describes the expression fields the policy rules inspect. */
@@ -41,6 +42,7 @@ export interface PolicyExpression extends PolicyNode {
41
42
  readonly declaration?: PolicyExpression
42
43
  readonly declarations?: readonly PolicyExpression[]
43
44
  readonly init?: PolicyExpression | null
45
+ readonly update?: PolicyExpression | null
44
46
  readonly source?: PolicyExpression | null
45
47
  readonly specifiers?: readonly PolicyExpression[]
46
48
  readonly imported?: PolicyExpression
@@ -691,7 +693,7 @@ export function expressionToPolicyBody(node: PolicyExpression): PolicyExpression
691
693
  return 'type' in body ? body : undefined
692
694
  }
693
695
 
694
- /** Returns the top-level statements a program holds. */
696
+ /** Returns the statements a program or a block holds. */
695
697
  export function programToPolicyStatements(node: PolicyExpression): readonly PolicyExpression[] {
696
698
  const body = node.body
697
699
  if (body === undefined || 'type' in body) return []
@@ -718,7 +720,7 @@ export function isPolicyTop(node: PolicyExpression): boolean {
718
720
  }
719
721
 
720
722
  /** Reports whether a policy expression is runtime function syntax. */
721
- export function isPolicyFunction(node: PolicyExpression): boolean {
723
+ export function isPolicyFunction(node: PolicyNode): boolean {
722
724
  return (
723
725
  node.type === 'FunctionDeclaration' ||
724
726
  node.type === 'FunctionExpression' ||
@@ -1146,16 +1148,168 @@ export function reportPrivacy(context: PolicyContext, node: PolicyExpression): v
1146
1148
  }
1147
1149
  }
1148
1150
 
1151
+ /** Lists the references to a declared variable, leaving out its own declaration and initializer. */
1152
+ export function filterPolicyUses(variable: PolicyVariable): readonly PolicyReference[] {
1153
+ return variable.references.filter(
1154
+ (reference) => reference.init !== true && !variable.identifiers.includes(reference.identifier),
1155
+ )
1156
+ }
1157
+
1149
1158
  /** Checks whether code writes a declared variable anywhere but in its own declaration. */
1150
1159
  export function isPolicyReassigned(variable: PolicyVariable): boolean {
1151
- return variable.references.some(
1152
- (reference) =>
1153
- reference.isWrite() &&
1154
- reference.init !== true &&
1155
- !variable.identifiers.includes(reference.identifier),
1160
+ return filterPolicyUses(variable).some((reference) => reference.isWrite())
1161
+ }
1162
+
1163
+ /** Checks whether the source range of one node lies inside the source range of another. */
1164
+ export function isPolicyWithin(node: PolicyNode, outer: PolicyNode): boolean {
1165
+ return node.range[0] >= outer.range[0] && node.range[1] <= outer.range[1]
1166
+ }
1167
+
1168
+ /**
1169
+ * Checks whether an ancestor of a node, below a boundary node, satisfies a test.
1170
+ *
1171
+ * @remarks
1172
+ * The walk starts at the node's parent and ends before the boundary, so neither the node nor the
1173
+ * boundary is tested. A boundary that is not an ancestor leaves the walk to end at the root.
1174
+ */
1175
+ export function isPolicyBeneath(
1176
+ node: PolicyNode,
1177
+ boundary: PolicyNode,
1178
+ matches: (ancestor: PolicyNode) => boolean,
1179
+ ): boolean {
1180
+ const parent = node.parent
1181
+ if (parent === undefined || parent === null || parent === boundary) return false
1182
+ return matches(parent) || isPolicyBeneath(parent, boundary, matches)
1183
+ }
1184
+
1185
+ /** Checks whether a node is a statement that diverts control flow away from a counted loop's steps. */
1186
+ export function isPolicyDiversion(node: PolicyNode): boolean {
1187
+ return (
1188
+ node.type === 'WhileStatement' ||
1189
+ node.type === 'DoWhileStatement' ||
1190
+ node.type === 'TryStatement'
1156
1191
  )
1157
1192
  }
1158
1193
 
1194
+ /**
1195
+ * Checks whether a node defers the code inside it past the statement that holds it.
1196
+ *
1197
+ * @remarks
1198
+ * A function runs when called, and a class body's field initializers run when the class is
1199
+ * instantiated, so a write or read inside either can run after a counted loop ends.
1200
+ */
1201
+ export function isPolicyClosure(node: PolicyNode): boolean {
1202
+ return isPolicyFunction(node) || node.type === 'ClassBody'
1203
+ }
1204
+
1205
+ /**
1206
+ * Checks whether a function encloses a node before any class body, static block, or program does.
1207
+ *
1208
+ * @remarks
1209
+ * A module scope, a top-level block, and a class static block hold no function, so each refuses.
1210
+ */
1211
+ export function isPolicyInFunction(node: PolicyExpression): boolean {
1212
+ const parent = node.parent
1213
+ if (parent === undefined || parent === null) return false
1214
+ if (isPolicyFunction(parent)) return true
1215
+ if (parent.type === 'StaticBlock' || parent.type === 'ClassBody' || parent.type === 'Program') {
1216
+ return false
1217
+ }
1218
+ return isPolicyInFunction(parent)
1219
+ }
1220
+
1221
+ /**
1222
+ * Checks whether a let declaration is a counted loop index.
1223
+ *
1224
+ * @remarks
1225
+ * The declaration is the head of a `for` statement, and the update clause alone writes each variable
1226
+ * it declares, outside any closure. A write in the test or the body refuses, and a variable that
1227
+ * nothing writes passes as a bound beside the index.
1228
+ */
1229
+ export function isPolicyIndex(
1230
+ node: PolicyExpression,
1231
+ variables: readonly PolicyVariable[],
1232
+ ): boolean {
1233
+ const loop = node.parent
1234
+ if (loop === undefined || loop === null || loop.type !== 'ForStatement' || loop.init !== node) {
1235
+ return false
1236
+ }
1237
+ const update = loop.update
1238
+ if (update === undefined || update === null) return false
1239
+ return variables
1240
+ .flatMap(filterPolicyUses)
1241
+ .every(
1242
+ (reference) =>
1243
+ !reference.isWrite() ||
1244
+ (isPolicyWithin(reference.identifier, update) &&
1245
+ !isPolicyBeneath(reference.identifier, loop, isPolicyClosure)),
1246
+ )
1247
+ }
1248
+
1249
+ /**
1250
+ * Checks whether one reference to an accumulator stays inside the block, loop, and body that contain
1251
+ * it.
1252
+ *
1253
+ * @remarks
1254
+ * The reference sits in no function or class body inside the block and starts at or after the loop.
1255
+ * A write also sits in the loop body, beneath no `while`, `do…while`, or `try`.
1256
+ */
1257
+ export function isPolicyContained(
1258
+ reference: PolicyReference,
1259
+ block: PolicyExpression,
1260
+ loop: PolicyExpression,
1261
+ ): boolean {
1262
+ const identifier = reference.identifier
1263
+ const body = expressionToPolicyBody(loop)
1264
+ if (
1265
+ body === undefined ||
1266
+ identifier.range[0] < loop.range[0] ||
1267
+ isPolicyBeneath(identifier, block, isPolicyClosure)
1268
+ ) {
1269
+ return false
1270
+ }
1271
+ return (
1272
+ !reference.isWrite() ||
1273
+ (isPolicyWithin(identifier, body) && !isPolicyBeneath(identifier, loop, isPolicyDiversion))
1274
+ )
1275
+ }
1276
+
1277
+ /**
1278
+ * Checks whether a let declaration is a block-local accumulator of the counted loop that follows it.
1279
+ *
1280
+ * @remarks
1281
+ * The declaration sits in a block inside a function and reaches a `for` statement with a `let` head
1282
+ * through variable declarations alone. Each reference to its variables is contained by
1283
+ * `isPolicyContained`. `reportLet` refuses a declarator without a value before this check runs.
1284
+ */
1285
+ export function isPolicyAccumulator(
1286
+ node: PolicyExpression,
1287
+ variables: readonly PolicyVariable[],
1288
+ ): boolean {
1289
+ const block = node.parent
1290
+ if (block === undefined || block === null || block.type !== 'BlockStatement') return false
1291
+ const statements = programToPolicyStatements(block)
1292
+ const rest = statements.slice(statements.indexOf(node) + 1)
1293
+ const loop = rest.find((statement) => statement.type === 'ForStatement')
1294
+ const head = loop?.init
1295
+ if (
1296
+ loop === undefined ||
1297
+ head === undefined ||
1298
+ head === null ||
1299
+ head.type !== 'VariableDeclaration' ||
1300
+ head.kind !== 'let' ||
1301
+ !isPolicyInFunction(node) ||
1302
+ !rest
1303
+ .slice(0, rest.indexOf(loop))
1304
+ .every((statement) => statement.type === 'VariableDeclaration')
1305
+ ) {
1306
+ return false
1307
+ }
1308
+ return variables
1309
+ .flatMap(filterPolicyUses)
1310
+ .every((reference) => isPolicyContained(reference, block, loop))
1311
+ }
1312
+
1159
1313
  /**
1160
1314
  * Checks whether a node sits inside a `declare` module, namespace, or global augmentation.
1161
1315
  *
@@ -1173,7 +1327,10 @@ export function isPolicyInDeclaredModule(node: PolicyExpression): boolean {
1173
1327
  )
1174
1328
  }
1175
1329
 
1176
- /** Reports a let declaration that prefer-const leaves: one reassigned or declared without a value. */
1330
+ /**
1331
+ * Reports a let declaration that prefer-const leaves: one reassigned or declared without a value,
1332
+ * unless it is a counted loop index or a block-local accumulator.
1333
+ */
1177
1334
  export function reportLet(context: PolicyContext, node: PolicyExpression): void {
1178
1335
  if (
1179
1336
  node.kind !== 'let' ||
@@ -1189,7 +1346,13 @@ export function reportLet(context: PolicyContext, node: PolicyExpression): void
1189
1346
  (node.declarations ?? []).some(
1190
1347
  (declarator) => declarator.init === undefined || declarator.init === null,
1191
1348
  )
1192
- if (bare || context.sourceCode.getDeclaredVariables(node).some(isPolicyReassigned)) {
1349
+ const variables = context.sourceCode.getDeclaredVariables(node)
1350
+ if (
1351
+ bare ||
1352
+ (variables.some(isPolicyReassigned) &&
1353
+ !isPolicyIndex(node, variables) &&
1354
+ !isPolicyAccumulator(node, variables))
1355
+ ) {
1193
1356
  context.report({ node, messageId: 'let' })
1194
1357
  }
1195
1358
  }
@@ -1513,10 +1676,10 @@ export const LET_RULE: PolicyRuleInterface = {
1513
1676
  type: 'problem',
1514
1677
  docs: {
1515
1678
  description:
1516
- 'Disallow a let declaration that is reassigned or declared without a value; prefer-const reports the rest.',
1679
+ 'Disallow a let declaration that is reassigned or declared without a value, except a counted loop index that only its update clause writes and a block-local accumulator that only the body of the counted loop after it writes; prefer-const reports the rest.',
1517
1680
  },
1518
1681
  messages: {
1519
- let: 'Declare this binding with const and derive its value: an expression, a helper that returns it, or a for…of over entries() in place of a counter.',
1682
+ let: 'Declare this binding with const and derive its value: an expression, a helper that returns it, or a for…of over entries() in place of a counter. A let stands only as the index of a for loop whose update clause alone writes it, beside a bound in that head that nothing writes, or as an accumulator declared with a value in a block inside a function before a counted for loop, with only variable declarations between, written only in that loop body and read only in and after the loop, never from a function or class inside the block, and never written inside a while, do…while, or try.',
1520
1683
  },
1521
1684
  },
1522
1685
  create(context) {