@opetope/lint 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # @opetope/lint
 
+## 0.9.2
+
+No changes in this release.
+
+## 0.9.1
+
+### Patch Changes
+
+- d7f346a: `no-subscribe-outside-models` leaves the ingress of a declared node alone, `@opetope/lint` ships an Oxlint config
+  fragment, and `combineAbortSignals` becomes host vocabulary on `@opetope/runtime` (D299).
+
+  **The rule.** `x.subscribe(...)` written lexically inside a callback where a declared node opens its work and owns
+  the release of it is no longer reported: the disposer that callback returns belongs to the node and is drained with
+  the generation that opened it. Four callbacks qualify, and each returns `Awaitable<Disposer | void>` — `connect` of
+  a `stream` (third argument), `subscribe` of an `event` (second), the `open` of
+  `scope.while`/`scope.switch`/`scope.keyed` (second), and the `open` member of an `attach`. This was a false
+  positive under this package's own `configs.layers` — a feature's `own.stream` lives in the integration layer, where
+  the rule is `error`, and it was reported for exactly the shape its own message prescribes. The position is the
+  contract, so `attach`'s `close`, and `consume`, `run`, `load`, `when` and `key`, keep the report; so does a node
+  whose origin the rule cannot prove. The context resolves by import: the `own` section written right where a
+  `defineFeature`/`defineFeature.body` from `@opetope/runtime` receives it, and a model factory — the second argument
+  of `model(Declaration, factory)` on that `own`, or a function whose first parameter is annotated `ModelContext`
+  from `@opetope/core`. Both anchors take the package name exactly, unlike `no-command-in-deps`, because a check that
+  uses an import to stay silent must not accept a host's own `./my-own-context`. `own.stream(...)` and a destructured
+  `stream(...)` read alike, alias included, as do `own.scope.while(...)` and `scope.while(...)`. There is no fix to
+  write: the change removes reports.
+
+  **The fragment.** `@opetope/lint/oxlintrc.json` is generated from `configs.recommended.rules` and shipped in the
+  package, so an Oxlint host extends the list instead of transcribing it:
+
+  ```json
+  {
+    "extends": ["./node_modules/@opetope/lint/oxlintrc.json"],
+    "jsPlugins": [{ "name": "opetope", "specifier": "./node_modules/@opetope/lint/dist/index.js" }]
+  }
+  ```
+
+  `extends` takes a file path, not a package specifier, which is why the fragment sits at the root of the package.
+  It carries rules only: Oxlint merges a `jsPlugins` entry through `extends` too, but a host that declares the plugin
+  itself would then register the name `opetope` twice, and that fails the configuration. Configurations merge first
+  to last, so rules a project wants stricter go after `extends`. `configs.recommended.rules` is also documented as a
+  readable table in the package README.
+
+  **The export.** `combineAbortSignals(signals)` and its result type `CombinedAbortSignalHandle` are published on
+  `@opetope/runtime`. It answers `{ signal, dispose }`: `signal` aborts with the exact reason of whichever input
+  aborts first, including one already aborted at the call, and `dispose` releases the listeners it took and is
+  idempotent. The name says handle because that is what it is — a handle over a signal, not a signal. The published
+  browser floor has no `AbortSignal.any`. The public surface moves to 39 values and 38 types against targets of 40
+  and 60; the size consumers are unchanged to the byte, because the symbol already reaches them from a module those
+  consumers treat as external.
+
+  **Migrating a host.** The gain is that a subscription inside an ingress callback is legal on its own, not because
+  a directory override silences the rule. In the application this was measured on, three such subscriptions — inside
+  the `connect` of a `stream` in three models — are today covered only by that project's `off` override for its model
+  layer; after this release the same code is correct one directory up as well, and the override can narrow to what it
+  is actually for. Directives are a smaller story: the one `// oxlint-disable-next-line
+opetope/no-subscribe-outside-models` in that application sits on a subscription inside a `new Promise` executor,
+  which is not an ingress, is still reported, and keeps its directive until `refresh()` returns a promise (D297). A
+  hand-written `opetope/*` block in `.oxlintrc.json` is replaced by the two lines above, leaving only the rules the
+  project turns on for its own directories — for this package's own layers that is `layer-placement`,
+  `no-subscribe-outside-models` and `prefer-model-selection`. A local copy of a combined-signal helper — the one an
+  application kept because `@opetope/core/internal` is closed to it — is deleted in favour of the import from
+  `@opetope/runtime`.
+
+- d7f346a: `opetope/no-command-in-deps` keeps a command hook out of a React dependency array.
+
+  A hook read from `useCommand`, from a key of `useCommands` or from a `Call` field of a `useModel` selection is a
+  snapshot of the render it was read in: the object is rebuilt on every `inFlight` and `outcome` change, while `run`
+  keeps one identity for the life of the binding. An application that wrote
+  `useEffect(() => { load.run(); return () => { unload.run(); }; }, [load, unload])` therefore started the command,
+  saw the status flip, saw the dependency change, ran the cleanup and ran the effect again — an infinite render loop.
+  The same application kept eight `useCallback(() => void submit.run('buy'), [submit])`, which looped over nothing but
+  voided their memo on each status of the command. Both shapes compile and run, and say something other than what
+  their author meant, which is what this package is for (D290).
+
+  The rule reads the dependency array of React's `useEffect`, `useLayoutEffect`, `useInsertionEffect`, `useCallback`,
+  `useMemo` and `useImperativeHandle`, and reports an element that is the hook binding taken whole; `x.run` and the
+  statuses `x.inFlight` and `x.outcome` are members of that object and stay. The record itself carries its own report:
+  `useCommands` builds a new object on every render, and so does `useModel` with a selection, so `[hooks]` and
+  `[order]` change on every render rather than on every status.
+
+  A callback that reaches the binding through a single `run` is fixed to that path — past an `as`, a `satisfies` or a
+  `!`, and without doubling a path the array already names. A callback that reads more than one path gets one
+  suggestion per path, statuses before `run`; a callback the rule cannot read through — written elsewhere, keeping
+  the object itself, taking it apart, or reading a member outside those three — gets the report and no suggestion,
+  because a suggestion is applied unattended under Oxlint's `--fix-suggestions`. Names are resolved by import and not
+  by spelling, a local alias included; a `useModel` selection field is a hook only where the same code proves it by
+  reading `run` on it, and a field read as data is of unknown kind and is left alone. The rule is `error` in
+  `configs.recommended`.
+
+- d7f346a: `opetope/no-snapshot-in-update` keeps a snapshot read out of the value of the write that replaces it.
+
+  `update(sessions, { items: sessions.getSnapshot().items, kind: 'loading' })` reads the state it is about to
+  replace. The argument is computed where it is written and the write happens after it, so the value is built from
+  what the state held at one moment and lands on what it holds at another. After D288 the same shape has a second
+  fault: a write through a context whose signal is aborted is dropped silently and its updater is never called, but
+  an argument is already computed by then — and the cells of a closed model are closed, so `getSnapshot()` throws
+  `ReadableError('closed')` and a silently dropped write becomes an exception in the author's body. An application
+  wrote the shape nine times, eight of them `loading`/`failed` transitions that keep what is already loaded (D295).
+
+  The rule reads a call of `update` — by that name or through a context — with exactly two arguments, whose first
+  argument names a state and whose value reads `getSnapshot()` on that same state, written into the value or through
+  a name of the same function that holds the read: `const current = s.getSnapshot()`,
+  `const { items } = s.getSnapshot()`, or a `let` nothing writes again. A snapshot of another readable inside the
+  value is a read of another state and stays, as do a value that is already an updater and a second argument that is
+  a spread, whose arguments are assembled somewhere else. The scalar form counts too:
+  `update(total, total.getSnapshot() + amount)` is the same write.
+
+  The fix writes the updater: `update(sessions, previous => ({ ...previous, kind: 'loading' }))`, with every read of
+  that state replaced by the parameter — a destructured field by the field of it — and a `const` that held the read
+  removed, comment and all, where this value was its only reader. The parameter is `previous`, or `snapshot` where an
+  enclosing scope already holds `previous`. Where the parameter would shadow a name the file has, where the named
+  read has another reader, and wherever the read was taken apart or opened with a `let`, the same rewrite arrives as
+  a suggestion; a value that cannot become the body of an updater at all — one that writes an `await` or a `yield`
+  there, assigns, increments, `delete`s, or keeps a read for a later call — gets the report and nothing else, because
+  Oxlint applies the first suggestion unattended. Everything else the value called travels into the updater with it,
+  so it runs at write time and not at all for a dropped write. The rule is `error` in `configs.recommended`.
+
 ## 0.9.0
 
 No changes in this release.

package/README.md

@@ -43,9 +43,30 @@ both it and `eslint` are peer dependencies.
 ### `recommended`
 
 Every rule that holds wherever Opetope is written: `when-predicate`, `define-feature-property-order`,
-`require-literal-id`, `id-naming`, `no-internal-imports`, `no-snapshot-read-in-render` and `require-declared-models` as errors. A rule that needs to know where a
-host keeps its files is off here and arrives through `layers`; `prefer-model-selection` is off because the number
-of hooks a component may keep is a taste a project settles for itself.
+`require-literal-id`, `id-naming`, `no-internal-imports`, `no-snapshot-read-in-render`, `no-snapshot-in-update`,
+`no-command-in-deps` and `require-declared-models` as errors. A rule that needs to know where a host keeps its files is off here and arrives
+through `layers`; `prefer-model-selection` is off because the number of hooks a component may keep is a taste a
+project settles for itself.
+
+`configs.recommended.rules` in full, which is also what `@opetope/lint/oxlintrc.json` ships:
+
+| Rule                            | `recommended` | Turned on by                                |
+| ------------------------------- | ------------- | ------------------------------------------- |
+| `define-feature-property-order` | `error`       |                                             |
+| `id-naming`                     | `error`       |                                             |
+| `layer-placement`               | `off`         | `layers({ integration, models, ui })`       |
+| `no-command-in-deps`            | `error`       |                                             |
+| `no-internal-imports`           | `error`       | also scoped by `internalImports({ allow })` |
+| `no-snapshot-in-update`         | `error`       |                                             |
+| `no-snapshot-read-in-render`    | `error`       |                                             |
+| `no-subscribe-outside-models`   | `off`         | `layers({ models })`                        |
+| `prefer-model-selection`        | `off`         | the project, with its own `threshold`       |
+| `require-declared-models`       | `error`       |                                             |
+| `require-literal-id`            | `error`       |                                             |
+| `when-predicate`                | `error`       |                                             |
+
+The three `off` rules are the three that need something only the project knows: which directories are which layer,
+and how many hooks one component may keep.
 
 ### `layers`
 
@@ -244,6 +265,95 @@ stays: those run after render, and the value of that moment is the one they want
 reported, whichever object it belongs to. A capitalized function that returns no element is a factory and keeps its
 reads — including a contribution's model factory, which reads the props of its own mount.
 
+### `no-snapshot-in-update`
+
+A value passed to `update` reads the state it is about to replace — a composite one,
+`update(sessions, { items: sessions.getSnapshot().items, kind: 'loading' })`, and a scalar one,
+`update(total, total.getSnapshot() + amount)`, alike. The read runs where the argument is written — before the
+write, and on a state that may already be closed, where `getSnapshot()` throws a `ReadableError` — and the value it
+computed then lands on a state that may have moved since. The updater form has neither problem: it reads at write
+time, and a write dropped because its context was aborted never calls the updater at all (D282, D288, D295).
+
+```ts
+update(sessions, previous => ({ ...previous, kind: 'loading' }));
+update(total, previous => previous + amount);
+```
+
+The rule reports a call of `update` — by that name or through a context, `ctx.update` — with exactly two arguments,
+whose first argument names a state and whose value reads `getSnapshot()` on that same state: written into the value
+itself, or through a name of the same function that holds the read — `const current = s.getSnapshot()`,
+`const { items } = s.getSnapshot()`, or a `let` nothing writes again. A `getSnapshot()` of another readable inside
+the value is a read of another state and stays; so do a value that is already an updater, a read written anywhere
+but in that value, and a second argument that is a spread, whose arguments are assembled somewhere else.
+
+The fix writes the updater: the value becomes `previous => ...` with every read of that state replaced by the
+parameter — a destructured field by the field of it, `previous.items` — and the `const` that held the read goes with
+it, comment and all, where this value was its only reader. The parameter is named `previous`, or `snapshot` where an
+enclosing scope already holds `previous`. Where the parameter would shadow a name the file has, where the named read
+has another reader that stays behind, and wherever the read was taken apart or opened with a `let`, the same rewrite
+arrives as a suggestion instead, because those are the rewrites a reader should look at. A value that cannot move
+into a function body at all — one that writes an `await` or a `yield` there, assigns, increments or `delete`s —
+gets the report and nothing else, and so does a read this value keeps for a later call.
+
+**The boundary.** `update(S, ...S.getSnapshot()...)` is specific enough on its own, so the rule resolves no import
+and reads no type: a host's own `update` of the same shape is reported too, and the fix is right for it only if it
+accepts an updater as its second argument. A name is the binding it resolves to, but a member expression is the
+path it spells, so two different objects written `this.state` are one state here. The rewrite moves the whole value
+into a function body, so everything else the value called — `Date.now()`, a helper, a formatter — is computed at
+write time instead of where it was written, and is not computed at all for a write the runtime drops; that is what
+the updater form means, and it is worth reading once before the rewrite lands. A read the value reaches by any other
+route — a helper that takes the state and reads it, a name declared in another function, a name the code writes
+again, a value that is already an updater — is not seen, and silence is not proof that a value computed itself from
+the previous one.
+
+### `no-command-in-deps`
+
+A command hook is a snapshot of the render it was read in: the object is rebuilt on every `inFlight` and `outcome`
+change, while `run` keeps one identity for the life of the binding (D290). A dependency array that names the object
+therefore fires on each of those changes: an effect re-runs, a memo is voided, and an effect that calls `run` from
+it never settles — it starts the command, the status flips, the dependency changes, the cleanup runs, and the
+effect runs again.
+
+```tsx
+const load = useCommand(Screen.load);
+const unload = useCommand(Screen.unload);
+
+useEffect(() => {
+  load.run();
+  return () => void unload.run();
+}, [load.run, unload.run]);
+```
+
+The rule reads the dependency array of `useEffect`, `useLayoutEffect`, `useInsertionEffect`, `useCallback`,
+`useMemo` and `useImperativeHandle`, and reports an element that is a command hook binding taken whole: the
+variable of a `useCommand`, a key or a destructured name of `useCommands`, and a field of a `useModel` selection
+the same code reads `run` on. `x.run` and the statuses `x.inFlight` and `x.outcome` are members of that object rather
+than the object, and they stay.
+
+The record itself is the worse shape and carries its own report: `useCommands` builds a new object on every render,
+and so does `useModel` with a selection, so `[hooks]` and `[order]` change on every render rather than on every
+status. The answer is the field the callback reads — `hooks.save.run`.
+
+The fix is written where the answer is one: a callback that reaches the binding through a single `run` gets that
+path in place of the element, whatever the element was written past — an `as`, a `satisfies` or a `!` is replaced
+along with it, and an array that already names the path loses the element instead of doubling it. Where the callback
+reads more than one path, or reads a status, the rule offers suggestions instead — one per path, statuses first —
+because which of them the dependency means is the author's to say. A callback this rule cannot read through — one
+written elsewhere, one that keeps the object itself, takes it apart, or reads a member outside those four — gets the
+report and no suggestion at all.
+
+**The boundary.** Names are resolved by import within one module, not by spelling: `useCommand`, `useCommands` and
+`useModel` are the imports of `@opetope/react`, the six hooks are React's own, and a local alias of either —
+`import { useEffect as effect }` — is the same import. React is the module named `react` exactly; an `@opetope/*`
+name is also taken from a relative import, which is how a package re-exports its own entry through a barrel, so a
+neighbouring `./scheduling` is React's no more than `@host/scheduling` is. React's hooks are read through a
+namespace or a default binding as well (`React.useEffect`); an `@opetope/*` entry has no default export, and only a
+namespace reaches it. Only a `const` holds the hook it was opened with, so a `let` is left alone. A selected
+`useModel` field is a hook only where the code proves it by reading `run` on it — a status name proves nothing,
+since plain data carries one as easily — and a field read as data is of unknown kind and is left alone, as is
+`useModel(Declaration)` without a selection, which keeps returning the granted model. A dependency array of a call
+that is not one of the six hooks belongs to whoever declared it.
+
 ### `no-subscribe-outside-models`
 
 A subscription written by hand owns a cleanup that nothing around it can see. The rule reports `x.subscribe(...)`
@@ -253,6 +363,47 @@ is `useReadable` or a model selection, and in a feature or a model it is `effect
 Handing the function over without calling it is not a subscription written here:
 `useSyncExternalStore(source.subscribe, source.getSnapshot)` passes a reference, and the reader owns what it starts.
 
+Neither is a subscription written where a declared node opens its work and owns the release of it. The disposer
+such a callback returns belongs to that node and is drained with the generation that opened it, so the rule stays
+silent there — this is the shape its own message asks for (D299):
+
+| Callback                                       | Where                       | Ingress |
+| ---------------------------------------------- | --------------------------- | ------- |
+| `stream(from, target, connect)`                | third argument              | yes     |
+| `event(from, subscribe, run)`                  | second argument             | yes     |
+| `scope.while` / `scope.switch` / `scope.keyed` | `open`, second argument     | yes     |
+| `attach(source, { open })`                     | the `open` member           | yes     |
+| `attach(source, { open, close })`              | the `close` member          | no      |
+| `consume`, `run`, `load`, `when`, `key`        | modifiers of the same calls | no      |
+
+```ts
+own: ({ imports, stream }) => ({
+  book: stream(
+    imports.exchange,
+    () => 'BTCUSD',
+    async ({ emit, signal }) => {
+      return imports.exchange.repository.subscribe('BTCUSD', emit, signal);
+    },
+  ),
+});
+```
+
+Inside counts all the way down — a nested arrow, a `function` body, an `await` on the subscription itself, a
+disposer named before it is returned. The context is resolved by import, not by spelling: the `own` section written
+right where a `defineFeature`/`defineFeature.body` **taken from `@opetope/runtime` itself** receives it, and a model
+factory — the second argument of `model(Declaration, factory)` on that same `own`, or a function whose first
+parameter is annotated `ModelContext` from `@opetope/core`. Unlike `no-command-in-deps`, these two anchors take the
+package name and nothing else: a relative import here would let a host's own `./my-own-context` silence the rule.
+`own.stream(...)` and a destructured `stream(...)` read alike, an alias answers with the key it was taken from
+(`{ stream: openStream }` is still `stream`), and `own.scope.while(...)` reads like the destructured
+`scope.while(...)`.
+
+Four shapes therefore keep the report, and each is a limit of what syntax proves: a `stream` traced to none of
+those anchors (imported from elsewhere, unresolvable, or belonging to another `defineFeature`); a callback written
+elsewhere and passed in by name, which is not lexically inside; an `own` section hoisted to its own binding
+(`const own = ({ stream }) => …; defineFeature(id, { own })`); and `model(Decl, createOrderModel)` where the factory
+is a named function without the `ModelContext` annotation.
+
 ### `prefer-model-selection`
 
 A component that takes one granted model and reads its fields through a hook each repeats the same wiring. From
@@ -328,16 +479,43 @@ linters run them, autofix included:
 
 ```json
 {
-  "jsPlugins": [{ "name": "opetope", "specifier": "./node_modules/@opetope/lint/dist/index.js" }],
-  "rules": { "opetope/when-predicate": "error" }
+  "extends": ["./node_modules/@opetope/lint/oxlintrc.json"],
+  "jsPlugins": [{ "name": "opetope", "specifier": "./node_modules/@opetope/lint/dist/index.js" }]
 }
 ```
 
+Those are the two lines, and neither of them is a transcription. `@opetope/lint/oxlintrc.json` is generated from
+`configs.recommended.rules` and shipped in the package, so a rule the package adds arrives with the upgrade instead
+of being missed by a hand-written severity map. `extends` in `.oxlintrc.json` takes a **file path**, resolved
+relative to the config that names it — not a package specifier — which is why the fragment sits at the root of the
+package and the path a host writes is the same string as its export name. Configurations merge first to last, so a
+rule the project wants stricter goes in its own `rules` after `extends`: the three `off` entries above are exactly
+the ones a project turns on by its own directories.
+
+The fragment carries rules and nothing else. Oxlint does merge a `jsPlugins` entry through `extends`, but a host
+that declares the plugin itself — under a wrapper package, as an isolated peer install needs — would then register
+the name `opetope` twice, and the second registration fails the whole configuration. Where the plugin comes from is
+the host's deployment; the severities are this package's contract.
+
 The alias `name` fixes the namespace, so a rule keeps the same id under either linter. `jsPlugins` is alpha and
-outside semver: `npm run ci:test` runs the built plugin under Oxlint on a valid and an invalid fixture and checks
-the fix it writes, so a break in that bridge fails here instead of in a host.
+outside semver: `npm run ci:test` runs the built plugin under Oxlint on a valid and an invalid fixture, through a
+config that extends the shipped fragment, and checks the fix it writes, so a break in that bridge fails here
+instead of in a host.
+
+`--fix-suggestions` applies the first suggestion of a report without asking, so a suggestion here is only ever a
+rewrite the reported code already justifies. `no-command-in-deps` offers the paths the callback itself reads, the
+status it watches before the `run` it calls; where it cannot read the use through — the object passed on, taken
+apart, or read past the members the rule knows — it reports and offers nothing, and the dependency stays as written
+until its author changes it.
+
+`no-snapshot-in-update` holds the same line from the other side: its suggestion is the fix it would not write
+unasked — a parameter that shadows a name the file already has, or a named read that stays behind for its other
+reader — and both rewrites leave the code doing what it did. Where the value cannot become the body of an updater
+at all, there is no rewrite to offer and the report stands alone.
 
 ## Checks
 
 From this package: `npm run ci:test`, `npm run ci:type`, `npm run ci:eslint`, `npm run build`. The Oxlint bridge
-test reads `dist`, so `npm run build` comes first.
+test reads `dist`, so `npm run build` comes first. `ci:test` also checks that the committed `oxlintrc.json` still
+equals `configs.recommended.rules`; after changing that config run `npm run oxlintrc:generate` and commit the
+result, which is why the build never writes it.

package/README.ru.md

@@ -43,9 +43,30 @@ export default [
 ### `recommended`
 
 Все правила, которые действуют везде, где пишут на Opetope: `when-predicate`, `define-feature-property-order`,
-`require-literal-id`, `id-naming`, `no-internal-imports`, `no-snapshot-read-in-render` и `require-declared-models` как error. Правило, которому нужно знать, где хост
-держит свои файлы, здесь выключено и приходит через `layers`; `prefer-model-selection` выключено потому, что число
-hooks, которое компонент вправе держать, каждый проект решает для себя.
+`require-literal-id`, `id-naming`, `no-internal-imports`, `no-snapshot-read-in-render`, `no-snapshot-in-update`,
+`no-command-in-deps` и `require-declared-models` как error. Правило, которому нужно знать, где хост держит свои файлы, здесь выключено и
+приходит через `layers`; `prefer-model-selection` выключено потому, что число hooks, которое компонент вправе
+держать, каждый проект решает для себя.
+
+`configs.recommended.rules` целиком — и ровно это поставляется как `@opetope/lint/oxlintrc.json`:
+
+| Правило                         | `recommended` | Включает                                        |
+| ------------------------------- | ------------- | ----------------------------------------------- |
+| `define-feature-property-order` | `error`       |                                                 |
+| `id-naming`                     | `error`       |                                                 |
+| `layer-placement`               | `off`         | `layers({ integration, models, ui })`           |
+| `no-command-in-deps`            | `error`       |                                                 |
+| `no-internal-imports`           | `error`       | плюс сужение через `internalImports({ allow })` |
+| `no-snapshot-in-update`         | `error`       |                                                 |
+| `no-snapshot-read-in-render`    | `error`       |                                                 |
+| `no-subscribe-outside-models`   | `off`         | `layers({ models })`                            |
+| `prefer-model-selection`        | `off`         | проект, со своим `threshold`                    |
+| `require-declared-models`       | `error`       |                                                 |
+| `require-literal-id`            | `error`       |                                                 |
+| `when-predicate`                | `error`       |                                                 |
+
+Три `off` — это ровно те три, которым нужно знание, которое есть только у проекта: какие каталоги каким слоем
+являются и сколько hooks вправе держать один компонент.
 
 ### `layers`
 
@@ -246,6 +267,96 @@ Id начинается с буквы и соединяет сегменты и
 какому бы объекту он ни принадлежал. Функция с заглавной буквы, не возвращающая элементов, — это фабрика, и её
 чтения остаются, включая фабрику модели вклада, которая читает props своего монтирования.
 
+### `no-snapshot-in-update`
+
+Значение, переданное в `update`, читает то состояние, которое собирается заменить, — и составное,
+`update(sessions, { items: sessions.getSnapshot().items, kind: 'loading' })`, и скалярное,
+`update(total, total.getSnapshot() + amount)`. Чтение выполняется там, где написан аргумент, — до записи и на
+состоянии, которое может быть уже закрыто, где `getSnapshot()` бросает `ReadableError`, — а вычисленное значение
+ложится на состояние, которое с тех пор могло уйти вперёд. У формы с апдейтером нет ни одной из этих бед: она
+читает в момент записи, а у записи, отброшенной вместе с отменённым контекстом, апдейтер не вызывается вовсе
+(D282, D288, D295).
+
+```ts
+update(sessions, previous => ({ ...previous, kind: 'loading' }));
+update(total, previous => previous + amount);
+```
+
+Правило сообщает о вызове `update` — по этому имени или через контекст, `ctx.update`, — ровно с двумя аргументами,
+у которого первым аргументом назван state, а значение читает `getSnapshot()` на нём же: написанный прямо в
+значении или через имя той же функции, которое держит это чтение, — `const current = s.getSnapshot()`,
+`const { items } = s.getSnapshot()` или `let`, который больше никто не переписывает. `getSnapshot()` другого
+readable внутри значения — чтение другого состояния, и оно остаётся; остаются и значение, которое уже является
+апдейтером, и чтение, написанное где угодно, кроме этого значения, и второй аргумент-spread, чьи аргументы
+собраны в другом месте.
+
+Фикс пишет апдейтер: значение становится `previous => ...`, где каждое чтение этого состояния заменено параметром —
+а разобранное поле тем же полем параметра, `previous.items`, — и `const`, державший чтение, уходит вместе с ним, с
+комментарием на той же строке, там, где это значение было его единственным читателем. Параметр называется
+`previous`, а где `previous` уже занят объемлющей областью — `snapshot`. Там, где параметр затенил бы имя, которое
+в файле есть, там, где у именованного чтения остаётся другой читатель, и везде, где чтение разобрано или открыто
+через `let`, та же правка приходит suggestion'ом: это ровно те правки, на которые стоит посмотреть. Значение,
+которое вообще нельзя перенести в тело функции — написанные в нём `await` или `yield`, присваивание, инкремент,
+`delete`, — получает сообщение и ничего больше, и так же остаётся чтение, отложенное до более позднего вызова.
+
+**Граница.** Форма `update(S, ...S.getSnapshot()...)` достаточно определённа сама по себе, поэтому правило не
+разрешает импортов и не читает типов: собственный `update` хоста той же формы тоже получает сообщение, и фикс
+верен для него только тогда, когда вторым аргументом он принимает апдейтер. Имя — это привязка, к которой оно
+разрешается, а member expression — путь, который он пишет, поэтому два разных объекта, записанных как `this.state`,
+здесь одно состояние. Правка переносит всё значение в тело функции, поэтому и всё остальное, что значение вызывало
+— `Date.now()`, помощник, форматтер, — вычисляется в момент записи, а не там, где написано, и не вычисляется вовсе
+для записи, которую рантайм отбросил; это и значит форма с апдейтером, и это стоит прочитать один раз до того, как
+правка ляжет. Чтение, до которого значение дотягивается любым другим путём — помощник, который принимает state и
+читает его сам, имя, объявленное в другой функции, имя, которое код переписывает, значение, уже являющееся
+апдейтером, — не видно, и молчание правила не доказывает, что значение вычислено из предыдущего.
+
+### `no-command-in-deps`
+
+Хук команды — это снимок того рендера, в котором его прочитали: объект пересобирается на каждой смене `inFlight` и
+`outcome`, а `run` держит одну идентичность всё время жизни привязки (D290). Массив зависимостей, который называет
+этот объект, срабатывает поэтому на каждой такой смене: эффект перезапускается, memo обнуляется, а эффект, который
+вызывает из него `run`, не останавливается никогда — он запускает команду, статус переключается, зависимость
+меняется, выполняется уборка, и эффект запускается снова.
+
+```tsx
+const load = useCommand(Screen.load);
+const unload = useCommand(Screen.unload);
+
+useEffect(() => {
+  load.run();
+  return () => void unload.run();
+}, [load.run, unload.run]);
+```
+
+Правило читает массив зависимостей `useEffect`, `useLayoutEffect`, `useInsertionEffect`, `useCallback`, `useMemo` и
+`useImperativeHandle` и сообщает об элементе, который целиком является привязкой хука команды: о переменной
+`useCommand`, о ключе или деструктурированном имени `useCommands` и о поле выбора `useModel`, на котором тот же код
+читает `run`. `x.run` и статусы `x.inFlight` и `x.outcome` — это члены объекта, а не сам объект, и они остаются.
+
+Сама запись — форма ещё хуже, и у неё собственное сообщение: `useCommands` строит новый объект на каждом рендере, и
+то же делает `useModel` с выбором, поэтому `[hooks]` и `[order]` меняются на каждом рендере, а не на каждом
+статусе. Ответ здесь — то поле, которое читает колбэк: `hooks.save.run`.
+
+Фикс пишется там, где ответ один: колбэк, который дотягивается до привязки единственным путём через `run`, получает
+на месте элемента этот путь — вместе со всем, через что элемент был написан: `as`, `satisfies` или `!` заменяются
+вместе с ним, а массив, в котором этот путь уже есть, теряет элемент вместо того, чтобы удвоить его. Там, где
+колбэк читает больше одного пути или читает статус, правило предлагает suggestions — по одной на путь, статусы
+первыми, — потому что какой из них имеет в виду зависимость, говорит автор. Колбэк, сквозь который правило не
+видит, — написанный в другом месте, держащий сам объект, разбирающий его или читающий член вне этих четырёх —
+получает сообщение и ни одной suggestion.
+
+**Граница.** Имена разрешаются импортом в пределах одного модуля, а не написанием: `useCommand`, `useCommands` и
+`useModel` — это импорты `@opetope/react`, шесть хуков — собственные хуки React, а локальный алиас любого из них —
+`import { useEffect as effect }` — это тот же импорт. React — это модуль, названный ровно `react`; имя `@opetope/*`
+берётся ещё и из относительного импорта, потому что так пакет реэкспортирует собственный вход через barrel, и
+соседний `./scheduling` — React не больше, чем `@host/scheduling`. Хуки React читаются и через namespace, и через
+default-привязку (`React.useEffect`); у входа `@opetope/*` default-экспорта нет, и до него дотягивается только
+namespace. Только `const` держит тот хук, которым его открыли, поэтому `let` остаётся в стороне. Выбранное поле
+`useModel` — хук только там, где код доказал это чтением `run` на нём: имя статуса не доказывает ничего, такое имя
+столь же легко носят обычные данные. Поле, прочитанное как данные, остаётся полем неизвестного рода, и так же
+остаётся `useModel(Declaration)` без выбора, который по-прежнему возвращает выданную модель. Массив зависимостей
+вызова, который не является одним из шести хуков, принадлежит тому, кто его объявил.
+
 ### `no-subscribe-outside-models`
 
 Подписка, написанная руками, владеет уборкой, которой не видит ничто вокруг. Правило сообщает о `x.subscribe(...)`
@@ -255,6 +366,47 @@ Id начинается с буквы и соединяет сегменты и
 Передача функции без вызова подпиской здесь не является:
 `useSyncExternalStore(source.subscribe, source.getSnapshot)` передаёт ссылку, и читатель владеет тем, что начал.
 
+Не является ею и подписка, написанная там, где объявленный узел открывает свою работу и сам её освобождает.
+Disposer, который возвращает такой колбэк, принадлежит этому узлу и сливается вместе с поколением, которое его
+открыло, — поэтому правило там молчит: это ровно та форма, которую предписывает его собственное сообщение (D299):
+
+| Колбэк                                         | Где                         | Ингресс |
+| ---------------------------------------------- | --------------------------- | ------- |
+| `stream(from, target, connect)`                | третий аргумент             | да      |
+| `event(from, subscribe, run)`                  | второй аргумент             | да      |
+| `scope.while` / `scope.switch` / `scope.keyed` | `open`, второй аргумент     | да      |
+| `attach(source, { open })`                     | член `open`                 | да      |
+| `attach(source, { open, close })`              | член `close`                | нет     |
+| `consume`, `run`, `load`, `when`, `key`        | модификаторы тех же вызовов | нет     |
+
+```ts
+own: ({ imports, stream }) => ({
+  book: stream(
+    imports.exchange,
+    () => 'BTCUSD',
+    async ({ emit, signal }) => {
+      return imports.exchange.repository.subscribe('BTCUSD', emit, signal);
+    },
+  ),
+});
+```
+
+«Внутри» считается до самого низа: вложенная стрелка, тело `function`, `await` на самой подписке, disposer,
+которому сначала дали имя. Контекст разрешается импортом, а не написанием: секция `own`, написанная прямо там, где
+её принимает `defineFeature`/`defineFeature.body`, взятый **из самого `@opetope/runtime`**, и фабрика модели —
+второй аргумент `model(Declaration, factory)` на том же `own` либо функция, первый параметр которой аннотирован
+`ModelContext` из `@opetope/core`. В отличие от `no-command-in-deps`, эти два якоря принимают только имя пакета:
+относительный импорт здесь позволил бы собственному `./my-own-context` хоста заглушить правило.
+`own.stream(...)` и деструктурированный `stream(...)` читаются одинаково, алиас отвечает тем ключом, из которого его
+достали (`{ stream: openStream }` — это по-прежнему `stream`), а `own.scope.while(...)` читается как
+деструктурированный `scope.while(...)`.
+
+Поэтому сообщение остаётся в четырёх формах, и каждая — граница того, что доказывает синтаксис: `stream`, который
+правило не проследило ни до одного якоря (импортированный откуда-то ещё, неразрешимый или принадлежащий чужому
+`defineFeature`); колбэк, написанный в другом месте и переданный сюда именем, — он не стоит лексически внутри;
+секция `own`, вынесенная в собственную привязку (`const own = ({ stream }) => …; defineFeature(id, { own })`); и
+`model(Decl, createOrderModel)`, где фабрика — именованная функция без аннотации `ModelContext`.
+
 ### `prefer-model-selection`
 
 Компонент, который берёт одну выданную модель и читает её поля по хуку на поле, повторяет одно и то же
@@ -329,16 +481,43 @@ Oxlint читает ESLint-плагины через `jsPlugins`: импорти
 
 ```json
 {
-  "jsPlugins": [{ "name": "opetope", "specifier": "./node_modules/@opetope/lint/dist/index.js" }],
-  "rules": { "opetope/when-predicate": "error" }
+  "extends": ["./node_modules/@opetope/lint/oxlintrc.json"],
+  "jsPlugins": [{ "name": "opetope", "specifier": "./node_modules/@opetope/lint/dist/index.js" }]
 }
 ```
 
+Это две строки, и ни одна из них не транскрипция. `@opetope/lint/oxlintrc.json` сгенерирован из
+`configs.recommended.rules` и поставляется в пакете, поэтому правило, которое пакет добавил, приходит вместе с
+обновлением, а не теряется в написанной руками severity-карте. `extends` в `.oxlintrc.json` принимает **путь
+файла**, разрешаемый относительно конфига, который его назвал, — не specifier пакета; поэтому фрагмент лежит в корне
+пакета, и путь, который пишет хост, совпадает с именем его экспорта. Конфигурации сливаются от первой к последней,
+поэтому правило, которое проект хочет строже, он пишет в собственных `rules` после `extends`: три `off` выше — ровно
+те, которые проект включает по своим каталогам.
+
+Фрагмент несёт правила и ничего больше. Oxlint действительно сливает через `extends` и запись `jsPlugins`, но хост,
+который объявляет плагин сам — под пакетом-обёрткой, как того требует изолированная установка peer-ов, — объявит имя
+`opetope` второй раз, и это отвергнет всю конфигурацию. Откуда берётся плагин — деплой хоста; severities — контракт
+этого пакета.
+
 Алиас `name` фиксирует namespace, поэтому id правила одинаков в обоих линтерах. `jsPlugins` находится в alpha и вне
-semver: `npm run ci:test` запускает собранный плагин под Oxlint на валидной и невалидной фикстуре и проверяет
-фикс, который тот пишет, — поломка этого моста падает здесь, а не у хоста.
+semver: `npm run ci:test` запускает собранный плагин под Oxlint на валидной и невалидной фикстуре — через конфиг,
+который `extends`-ит поставляемый фрагмент, — и проверяет фикс, который тот пишет: поломка этого моста падает здесь,
+а не у хоста.
+
+`--fix-suggestions` применяет первую suggestion сообщения, ничего не спрашивая, поэтому suggestion здесь — только
+такая правка, которую оправдывает сам прочитанный код. `no-command-in-deps` предлагает те пути, которые читает сам
+колбэк: статус, за которым он следит, раньше `run`, который он вызывает. Там, где правило не видит использование
+насквозь — объект передан дальше, разобран или прочитан за пределами известных ему членов, — оно сообщает и не
+предлагает ничего, и зависимость остаётся написанной так, как её написали, пока её не изменит автор.
+
+`no-snapshot-in-update` держит ту же линию с другой стороны: его suggestion — это тот самый фикс, который правило
+не стало писать без спроса: параметр, затеняющий имя, которое в файле уже есть, или именованное чтение, которое
+остаётся ради другого читателя. Обе правки оставляют код делать то же, что он делал. Там, где значение вообще не
+может стать телом апдейтера, предлагать нечего, и сообщение стоит одно.
 
 ## Checks
 
 Из этого пакета: `npm run ci:test`, `npm run ci:type`, `npm run ci:eslint`, `npm run build`. Тест моста Oxlint
-читает `dist`, поэтому `npm run build` идёт первым.
+читает `dist`, поэтому `npm run build` идёт первым. `ci:test` заодно проверяет, что закоммиченный `oxlintrc.json`
+всё ещё равен `configs.recommended.rules`; после изменения этого конфига выполните `npm run oxlintrc:generate` и
+закоммитьте результат — именно поэтому файл не пишет сборка.

package/dist/command-hooks.d.ts

@@ -0,0 +1,34 @@
+import type { TSESLint, TSESTree } from '@typescript-eslint/utils';
+/** What a name holds: one hook, a record of them, a selection whose fields may be hooks, or one such field. */
+type HookKind = 'candidate' | 'hook' | 'hooks' | 'selection';
+type HookKinds = Map<TSESLint.Scope.Variable, HookKind>;
+/**
+ * What a dependency element names: one hook (no key, not a record), one key of a record, or the record itself,
+ * which is a fresh object on every render.
+ */
+type Binding = {
+    readonly key: string | undefined;
+    readonly proved: boolean;
+    readonly record: boolean;
+    readonly variable: TSESLint.Scope.Variable;
+};
+/** One read of the binding: the member it ends in, and the text the author wrote to reach it. */
+type Access = {
+    readonly member: string | undefined;
+    readonly optional: boolean;
+    readonly text: string;
+};
+/** `opaque` is a use no member replaces: the object passed on, destructured, or read past a member we know. */
+type Usage = {
+    readonly accesses: readonly Access[];
+    readonly opaque: boolean;
+};
+declare const STATUS_MEMBERS: string[];
+/** Every read of the binding inside one callback, and whether any of them takes the object as a whole. */
+declare function usageIn(source: TSESLint.SourceCode, binding: Binding, callback: TSESTree.Node | undefined): Usage;
+/** The binding a dependency element names as a whole; a member of one is a member, and this returns nothing. */
+declare function bindingAt(source: TSESLint.SourceCode, kinds: HookKinds, element: TSESTree.Node): Binding | undefined;
+/** Records what one declaration binds, so a later dependency array is read against names and not against spelling. */
+declare function classifyDeclaration(source: TSESLint.SourceCode, declarator: TSESTree.VariableDeclarator, kinds: HookKinds): void;
+export type { Access, Binding, HookKinds, Usage };
+export { bindingAt, classifyDeclaration, STATUS_MEMBERS, usageIn };