@opetope/lint 0.11.0 → 0.12.1

package/README.md

@@ -1,26 +1,20 @@
-# @opetope/lint
+# `@opetope/lint`
 
-ESLint rules for the code an Opetope author writes. The plugin holds only what a syntactic check can prove about a
-declaration: shapes that compile and run, yet say something other than what their author meant. What the type
-checker, the runtime and dead-code analysis already answer stays with them (see [`../docs/decisions.md`](https://www.npmjs.com/package/@opetope/runtime), D227).
-
-The package depends on no other `@opetope/*` package and reads no types, so a host can lint sources it has not
-built yet.
+ESLint rules for the Opetope authoring and layer boundaries. The rules guide model writes, feature declarations, hook dependencies and imports; they do not replace type checking or runtime validation.
 
 ## Installation
 
 ```sh
-npm install --save-dev @opetope/lint 'eslint@^9' '@typescript-eslint/parser@^8'
+npm install --save-exact --save-dev @opetope/lint
 ```
 
-Use matching Opetope versions. For release candidates, append `@next` to every `@opetope/*` package in the command.
-The API is ESM-only; Node 20.19+ is required. Development check commands below apply to a contributor checkout.
+Use matching exact Opetope versions; for release candidates, install every Opetope package from `@next`.
+Packages are ESM-only and support Node 20.19+. React integrations support React and React DOM 19.
 
-The normative EN/RU guides are shipped in `@opetope/runtime`: after installing it, open
-`node_modules/@opetope/runtime/docs/spec.md` or `spec.ru.md`; recipes are in `cookbook.md` and `cookbook.ru.md`.
-No GitHub access is needed to read those installed guides.
+## Example
 
-## Usage
+This focused example shows the package boundary. [Start](../runtime/docs/start.md) includes a complete
+feature, host, React entry and cleanup in one visible module.
 
 ```js
 // eslint.config.mjs
@@ -34,614 +28,93 @@ export default [
 ];
 ```
 
-The plugin is both the default export and the named `opetopeLint`. The configuration registers it under the
-namespace `opetope`, so a rule is named `opetope/when-predicate`. Parsing requires `@typescript-eslint/parser`;
-both it and `eslint` are peer dependencies.
-
-## Configs
-
-### `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`, `no-snapshot-in-update`,
-`no-redundant-const-tuple`, `no-command-in-deps`, `prefer-effect-current`, `capture-command-cleanup` 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                                |
-| ------------------------------- | ------------- | ------------------------------------------- |
-| `capture-command-cleanup`       | `error`       |                                             |
-| `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-redundant-const-tuple`      | `error`       |                                             |
-| `no-snapshot-in-update`         | `error`       |                                             |
-| `no-snapshot-read-in-render`    | `error`       |                                             |
-| `no-subscribe-outside-models`   | `off`         | `layers({ models })`                        |
-| `prefer-effect-current`         | `error`       |                                             |
-| `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`
-
-`opetope.configs.layers({ integration, models, ui, tests })` takes the globs of a project's own layers and returns
-the configuration each of them earns. A layer without globs is a layer this project does not have, and it produces
-nothing; a file no glob claims is placed by nobody.
-
-```js
-...opetope.configs.layers({
-  integration: ['src/features/*/integration/**/*.{ts,tsx}'],
-  models: ['src/features/*/models/**/*.ts'],
-  ui: ['src/features/*/ui/**/*.{ts,tsx}'],
-}),
-```
-
-`integration`, `models` and `ui` each turn on `layer-placement` for their files. `models` also turns on
-`no-subscribe-outside-models` for every source file and steps aside in that layer and in `tests`, which defaults to
-`['**/__tests__/**', '**/*.spec.ts', '**/*.spec.tsx']`. A subscription is covered even in a file no layer claims,
-because forgetting one is how a subscription outlives its reader.
-
-### `internalImports`
-
-`opetope.configs.internalImports({ allow, files })` configures `opetope/no-internal-imports` across JavaScript and
-TypeScript, including `.mjs` model tests. The rule is already enabled by `recommended`; this helper is useful for
-scoping it or naming trusted library implementation and host integration files. `allow` explicitly switches off
-only this rule for those files. Place the helper's blocks **after** `recommended`: a later `recommended` block
-re-enables the rule, including for the allowed files. Other project restrictions stay intact.
-
-```js
-export default [
-  opetope.configs.recommended,
-  ...opetope.configs.internalImports({ allow: ['src/bootstrap/**/devtools.ts'] }),
-];
-```
-
-The dedicated rule never changes `no-restricted-imports`. The former `internalImportPattern` export is removed:
-enable this rule or use the helper instead of merging an Opetope pattern into the host's restrictions (D261).
-
-## Rules
-
-### `no-internal-imports`
-
-Application code and tests import public Opetope entries. The rule rejects `@opetope/*/internal` and its deeper
-paths in imports, re-exports, literal `import()` calls, unshadowed `require()` calls, TypeScript import types and
-`import = require`. It includes type-only imports; an internal type is still coupled to the private ABI.
-Use `runCall` from `@opetope/core/testing` to run a real model Call, `openModel` from `@opetope/runtime/testing` to open one without a feature, and `command` from `@opetope/react/testing` to construct a fixture Call.
-Tests do not receive an automatic exception. Trusted library implementation or host integration can use an explicit
-file override; the rule has no autofix because the correct public replacement depends on the imported operation.
-
-**The boundary.** This is a syntactic check of literal module paths and templates without substitutions. It does
-not resolve aliases, computed import paths, re-export graphs or custom loaders. A locally shadowed `require` is not
-treated as Node's loader. Apply the config to every JavaScript/TypeScript source and test glob the project uses.
-
-### `when-predicate`
-
-A contribution's `when` answers the visibility fact of this instance, not the source that carries it (D220). The
-rule reads the `when` of a `slot`, `pipe` or `register` contribution, and any `when` whose function destructures the
-evaluation context `{ exports, imports, own, read }`, and reports three shapes:
-
-| Written                                    | Reported                                                                      |
-| ------------------------------------------ | ----------------------------------------------------------------------------- |
-| `when: ({ imports }) => imports.x.allowed` | returns a source; fixed to `({ imports, read }) => read(imports.x.allowed)`   |
-| `when: async ({ read }) => read(x)`        | a predicate answers synchronously; no fix                                     |
-| `when: () => allowed`                      | a `Readable<boolean>` is passed as `when` directly, without a wrapper; no fix |
-
-The fix wraps the returned member expression in `read(...)` and adds `read` to the destructured context when it is
-absent. A named context is read through itself: `context => context.imports.x.allowed` becomes
-`context => context.read(context.imports.x.allowed)`.
-
-**The boundary.** The rule reads shapes, not types. `({ read }) => read(counter)` over a non-boolean source stays a
-type error, and so does a `read` of something that is not a `Readable`. Where a member access of the evaluation
-context is a plain value rather than a source, the predicate cannot change its answer, and the rule reports it as
-one written for a source; hoist that decision out of `when`, or silence the line. `when` outside a contribution —
-the positional `(current, previous)` of `effect`, or the source value of `scope.while` — is left alone.
-
-### `define-feature-property-order`
-
-A feature declares its sections in one order: `imports`, `requires`, `own`, `exports`, `provides`, `when`, and the
-`body` loader that replaces the last three stages (spec §2.1, D186). The identity is not among them — a feature
-names itself with its first argument (D280). The order is the reading order of the declaration — the edges, the
-stages, then the lifetime and the loader — so a reader finds a section by position, and a key sorter can be
-configured to hold the same order instead of a second one.
-
-The fix reorders the properties. It stands down when a comment sits between two sections, because such a comment
-belongs to neither and reordering would move it away from the line it explains; a comment inside a section travels
-with it. An object with a key that is not a section, or with a spread, is left to the type checker.
-
-### `no-redundant-const-tuple`
-
-`derive` takes its tuple of sources as a `const` type parameter, so `[left, right]` infers its own tuple and the
-selector already sees exact values. The `as const` written beside it states what the signature already states
-(D279, D309):
-
-```ts
-const summary = derive([total, label], (value, suffix) => `${value} ${suffix}`);
-```
-
-The rule reads the first argument of a `derive` resolved to `@opetope/core`, and only where that argument is an
-array literal carrying `as const`. The fix removes the assertion and nothing else. It stands down when a comment
-sits between the tuple and the assertion, because such a comment belongs to neither and the removal would take it
-along.
-
-**The boundary.** An assertion written anywhere else is left alone: on one element of the tuple, where it says
-something about that element; on the result of the selector; on the options record; and on the single-source form,
-whose argument is not a tuple at all. `as Sources` is a different assertion and says something else. The import is
-resolved within one module — a local alias, a `const` that holds the import and a namespace binding all reach the
-same export — and, unlike `no-command-in-deps`, this rule recognizes the import from `@opetope/core` and nothing
-else: a re-export through a host's own barrel it does not see. That is the deliberate price of a safe fix. This
-rule rewrites code, and a host's own `derive` has no `const` type parameter to make the assertion redundant, so
-removing it there would change the inferred types in silence.
-
-### `require-declared-models`
-
-A component that reads a per-mount UI model declares that model with `requiresModels`. Owner models remain
-available to the contribution subtree without this declaration (D158, D250).
-
-```tsx
-import { defineFeature } from '@opetope/runtime';
-import { requiresModels, useModel } from '@opetope/react';
-
-const Form = () => {
-  const actions = useModel(FormActions);
-  return null;
-};
-const DeclaredForm = requiresModels([FormActions])(Form);
-
-defineFeature('example.form', {
-  provides: ({ slot }) => ({
-    form: slot(FormSlot, ({ model }) => ({
-      Component: DeclaredForm,
-      models: [model(FormActions, createActions)],
-    })),
-  }),
-});
-```
-
-The rule checks contributions passed to the `slot` capability of a visible `defineFeature` or
-`defineFeature.body` `provides` callback. A local component receiving UI models must declare its requirements;
-each visible component or hook that reads one of those models declares its own list. Wrapping a parent does not
-declare the requirements of a nested function.
-
-Named and namespace imports, import aliases, local aliases, a named `provides` context, and both inline and named
-components are recognized. Bindings are compared within their lexical scopes; an unrelated local `useModel`,
-`requiresModels` or `slot` does not become an Opetope API by sharing its name. Named APIs from relative re-exports
-are recognized by their exported names, without reading the other file.
-
-**The boundary.** Analysis stays within one module and follows visible local declarations and factory returns.
-Arbitrary objects with `Component` and `models` are not contribution sites. Imported component implementations,
-dynamic model lists and opaque helpers remain unverified: silence is not proof that their model requirements are
-complete. Model references must be locally visible identifiers or aliases; the rule does not inspect types or walk
-the rendered React tree. It has no autofix, because choosing which model a component should read is an authoring
-choice. Types and runtime authority checks continue to apply.
-
-### `require-literal-id`
-
-A declaration names itself with a string that is written, not built where the declaration stands. The rule reads
-every declaration of the public vocabulary that names itself — `defineFeature`, `defineApplication`,
-`defineCondition`, `defineHostContract`, `defineModel`, `definePort`, `defineSlot`, `defineSwitchSlot`,
-`definePipe` and `defineRegistry`, and the four of the optional Navigation package: `defineScreen`,
-`defineSurface`, `defineLink` and `defineLinkHandlers`. D280 gives them one form: the id is the first argument of
-every one of them.
-
-Written means a string literal, a template with no expressions, a name that resolves to an import or to a `const`
-of the same module, and a property read from such a name. Built means anything the call site assembles: a template
-with an expression, a concatenation, a call, or a name that resolves to a parameter.
-
-A project that generates a set of declarations from a name says so once, by naming that factory:
-
-```js
-'opetope/require-literal-id': ['error', { allowInCallees: ['createSlots'] }],
-```
-
-The name is matched against the function the declaration is written in and against the call it is passed to, so
-both shapes of a factory are covered.
+## Documentation
 
-**The boundary.** The rule follows names inside one module only: an id imported from another file is written
-there, and that is where its own text is checked. The kernel's `defineModule`, `defineCallTarget` and
-`defineCallLane` are not read, because an author never writes them.
+The [reference](../runtime/docs/reference/lint.md) owns the detailed contract, options and failure semantics.
+[Guides](../runtime/docs/guides/index.md) show individual tasks. Documentation is shipped with
+`@opetope/runtime` in `docs/`, so an installed application can read it without access to this repository.
 
-### `id-naming`
+For a contributor checkout, use `npm run ci:type --workspace @opetope/lint` and
+`npm run ci:test --workspace @opetope/lint` where provided. The root `npm run check` performs full acceptance;
+[contributor commands](../runtime/docs/maintainers/contributing.md) describe the build and package checks.
 
-An id starts with a letter and joins segments of letters and digits with one of `.`, `/`, `:` or `-`, within 160
-characters. That is the grammar `declarationId` accepts in `@opetope/core`; an id outside it is a `DeclarationError`
-the moment the declaration runs, and this rule says so before the code runs. A screen, a surface and a link handler
-registry pass their id through the same `declarationId`, so this rule reads them too; `defineLink` is left out of it
-because a link id is a canonical lower-case path segment of a URL, which the package checks itself and which no
-reserved prefix applies to (D313).
+<a id="opetopelint"></a>
+[See @opetope/lint](../runtime/docs/reference/lint.md).
 
-A project that reserves a first segment names it, and every declaration of those files must open with it:
+<a id="usage"></a>
+[See Usage](../runtime/docs/reference/lint.md#lint-usage).
 
-```js
-'opetope/id-naming': ['error', { prefix: 'workspace' }],
-```
+<a id="configs"></a>
+[See Configs](../runtime/docs/reference/lint.md#configs).
 
-**The boundary.** The rule checks the ids whose text it can see in the file — a literal, or a name that resolves to
-one in the same module. An id that arrives from another module is checked where it is written.
+<a id="recommended"></a>
+[See `recommended`](../runtime/docs/reference/lint.md#recommended).
 
-### `layer-placement`
+<a id="layers"></a>
+[See `layers`](../runtime/docs/reference/lint.md#layers).
 
-Each declaration is written in the layer that owns it. The rule reports nothing until a project names its layers
-through `configs.layers`, because the names of directories are not a law of the framework:
+<a id="internalimports"></a>
+[See `internalImports`](../runtime/docs/reference/lint.md#internalimports).
 
-| Declaration                                                                                                                              | Layer                                                  |
-| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| `defineFeature`                                                                                                                          | integration — a feature composes the other two layers  |
-| `defineModel`                                                                                                                            | models, or the UI contracts that declare a mount model |
-| `defineSlot`, `defineSwitchSlot`, `defineSurface`, `definePipe`, `defineRegistry`, `definePort`, `defineCondition`, `defineHostContract` | integration, or the UI contracts beside the component  |
-| `defineApplication`                                                                                                                      | none of them: the host bootstrap owns it               |
+<a id="rules"></a>
+[See Rules](../runtime/docs/reference/lint.md#rules).
 
-**This is a convention of the project, not a law of the library.** The framework says a feature's UI imports only
-that feature's own contracts, and that a model knows nothing about the feature; where those files live is the
-project's choice, and this rule holds whatever choice it declared.
+<a id="no-internal-imports"></a>
+[See `no-internal-imports`](../runtime/docs/reference/lint.md#no-internal-imports).
 
-### `no-snapshot-read-in-render`
+<a id="enabled-predicate"></a>
+[See `enabled-predicate`](../runtime/docs/reference/lint.md#enabled-predicate).
 
-`getSnapshot()` called while a component or a hook renders reads the value once and never hears the next one. Read
-it with `useReadable`, or select it together with the commands of the same model:
-`useModel(Declaration, (model, { read }) => ...)` (D205, D214).
+<a id="define-feature-property-order"></a>
+[See `define-feature-property-order`](../runtime/docs/reference/lint.md#define-feature-property-order).
 
-A render scope is a function named `use…`, or a capitalized function that returns elements. The rule looks at the
-function the call is written in, so a snapshot read in an event handler, an effect or any other nested callback
-stays: those run after render, and the value of that moment is the one they want.
+<a id="no-redundant-const-tuple"></a>
+[See `no-redundant-const-tuple`](../runtime/docs/reference/lint.md#no-redundant-const-tuple).
 
-**The boundary.** The rule reads the name of the receiver, not its type: every `getSnapshot()` in a render scope is
-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.
+<a id="require-declared-models"></a>
+[See `require-declared-models`](../runtime/docs/reference/lint.md#require-declared-models).
 
-### `no-snapshot-in-update`
+<a id="require-literal-id"></a>
+[See `require-literal-id`](../runtime/docs/reference/lint.md#require-literal-id).
 
-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 have stopped, where `getSnapshot()` answers a value nothing will move again
-— 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).
+<a id="id-naming"></a>
+[See `id-naming`](../runtime/docs/reference/lint.md#id-naming).
 
-```ts
-update(sessions, previous => ({ ...previous, kind: 'loading' }));
-update(total, previous => previous + amount);
-```
+<a id="layer-placement"></a>
+[See `layer-placement`](../runtime/docs/reference/lint.md#layer-placement).
 
-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]);
-```
+<a id="no-snapshot-read-in-render"></a>
+[See `no-snapshot-read-in-render`](../runtime/docs/reference/lint.md#no-snapshot-read-in-render).
 
-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(...)`
-and stays off until `configs.layers` names the model layer that is allowed to hold one; in a component the reader
-is `useReadable` or a model selection, and in a feature or a model it is `effect`, `event` or the `connect` of
-`resource.live`.
-
-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 |
-| ---------------------------------------------- | --------------------------- | ------- |
-| `resource.live({ connect })`                   | the `connect` member        | 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      |
-| `apply`, `load`, `run`, `when`, `key`          | modifiers of the same calls | no      |
-
-`resource.load` opens no subscription and has no ingress at all, so a `subscribe` written in its `load` is reported
-like any other hand-written one (D349).
-
-```ts
-own: ({ imports, resource }) => ({
-  book: resource.live({
-    apply: { change: (_current: ResourceData<Quote>, change: Quote) => change },
-    connect: ({ emit, signal, source }) => source.repository.subscribe('BTCUSD', emit, signal),
-    lifetime: 'owner',
-    source: imports.exchange,
-  }),
-});
-```
+<a id="no-snapshot-in-update"></a>
+[See `no-snapshot-in-update`](../runtime/docs/reference/lint.md#no-snapshot-in-update).
 
-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.resource.live(...)` and a destructured `resource.live(...)` read alike, an alias answers with the key it was
-taken from (`{ resource: materialize }` is still `resource`), and `own.scope.while(...)` reads like the destructured
-`scope.while(...)`.
+<a id="no-command-in-deps"></a>
+[See `no-command-in-deps`](../runtime/docs/reference/lint.md#no-command-in-deps).
 
-Four shapes therefore keep the report, and each is a limit of what syntax proves: a `resource.live` 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 = ({ resource }) => …; defineFeature(id, { own })`); and `model(Decl, createOrderModel)` where the factory
-is a named function without the `ModelContext` annotation.
+<a id="no-subscribe-outside-models"></a>
+[See `no-subscribe-outside-models`](../runtime/docs/reference/lint.md#no-subscribe-outside-models).
 
-### `prefer-effect-current`
+<a id="prefer-effect-current"></a>
+[See `prefer-effect-current`](../runtime/docs/reference/lint.md#prefer-effect-current).
 
-The `run` of an effect is already given the value it was started for. Reading the same source through
-`source.getSnapshot()` inside that run reads it a second time and says nothing about which run this is, so the rule
-rewrites it to `execution.current` (D296, D323):
+<a id="no-write-after-source-write"></a>
+[See `no-write-after-source-write`](../runtime/docs/reference/lint.md#no-write-after-source-write).
 
-```js
-// before
-ctx.effect(quotes, execution => publish(quotes.getSnapshot()));
-// after
-ctx.effect(quotes, execution => publish(execution.current));
-```
+<a id="capture-command-cleanup"></a>
+[See `capture-command-cleanup`](../runtime/docs/reference/lint.md#capture-command-cleanup).
 
-The fix writes the word the run already has: the name of the context for `execution => …`, and the local name
-`current` was destructured under for `({ current }) => …`. A run that named neither has no word to write, so the
-report stands alone.
-
-**The two cases it reports without rewriting.** Past the first `await` of the run, `current` is the value this run
-started with and the snapshot is the value of the moment; a change of the source normally restarts the run, so the
-two normally agree — and «normally» is not a licence to rewrite. Under `when` they legitimately differ: the filter
-admits some values and skips others, so the source moves without restarting the run (D168, D296). A modifier record
-this rule cannot read — one assembled elsewhere — is treated as if it carried the predicate.
-
-A read inside a nested callback of the run — a `timers.delay`, a subscription handler — is left alone: that code
-runs later than the run does, and the value of that moment is the one it wants. Like every rule that rewrites code,
-this one resolves its context exactly: the `effect` it acts on is the one declared on a `ModelContext` parameter or
-on the context of a `model(Declaration, factory)` written inside a `defineFeature` of `@opetope/runtime` (D309).
-
-### `capture-command-cleanup`
-
-The writer of a command lives as long as its caller (D288). A write in the `finally` or the `catch` of a `try` that
-awaits runs after the `await`, and once the call is cancelled it is dropped without a record — so the cleanup that
-was supposed to clear a busy flag or a pending mark is exactly the write that never lands. The rule reports that write
-and names the word that does land, a commit taken before the `await` (D319, D330):
-
-```ts
-// reported: once the caller is cancelled, `busy` stays `true`
-ctx.call(async (input, { signal, update }) => {
-  update(busy, true);
-  try {
-    await host.send(input, signal);
-  } finally {
-    update(busy, false);
-  }
-});
-
-// the cleanup lands while the model lives
-ctx.call(async (input, { capture, signal, update }) => {
-  update(busy, true);
-  const done = capture(busy);
-  try {
-    await host.send(input, signal);
-  } finally {
-    done.update(() => false);
-  }
-});
-```
+<a id="prefer-model-selection"></a>
+[See `prefer-model-selection`](../runtime/docs/reference/lint.md#prefer-model-selection).
 
-There is no fix: whether a cleanup must land after its caller left is the author's decision, and the drop is the law
-for a reason — a late write of a cancelled call must not overwrite what a newer call wrote. The report therefore names
-both ways out. A cleanup that must run for a cancelled call goes through `capture(state)` taken before the `await`; an
-answer that must not land after cancellation — a failure, a result — belongs in a `catch` after
-`rethrowIfCancelled(cause)`. Where a caller cancels one run to start the next — a search its consumer issues again, a
-Call an effect run invokes and a newer value cancels — the older run's write is exactly the one that should not land,
-and a disable comment says so.
-
-Under `policy: 'parallel'` the report does not advise a commit. Calls of such a command overlap, so a cancelled call's
-captured cleanup would clear a flag another call still holds — a flag shared by parallel calls is racy either way —
-and the report says to keep that state per call, or to leave progress to the consumer's `inFlight`. The rule sees the
-policy only when `{ policy: 'parallel' }` is written on the `call` itself; a modifier record assembled elsewhere reads
-as the default queue, where the lane waits for the physical body and a captured cleanup lands in order.
-
-The rule is a heuristic over syntax, and it proves nothing about a write it does not report. It reads the writer of a
-command body under these names: `execution.update(…)`; `({ update })` or `({ update: write })` in the parameter list;
-`const { update } = execution` inside the body; and a `const` that gives one of those a second name —
-`const write = update` or `const write = execution.update`. It follows a body passed as a local function. It misses a
-closure that holds the writer (`const clear = () => update(busy, false)` called in `finally`), a writer stored anywhere
-but a `const`, and a context handed to a helper. A `try` counts when its protected block awaits in the body's own
-function: an `await` or a `for await` inside a nested callback suspends that callback, not the command.
-
-In a `catch`, a write that follows `rethrowIfCancelled(cause)`, `signal.throwIfAborted()` or an `if (signal.aborted)`
-that throws or returns — in the block that holds the write or in any block around it — is not reported. Such a guard
-is the author's statement that what follows must not run for a cancelled call, and the rule takes it at its word: in
-`catch (cause) { rethrowIfCancelled(cause); update(busy, false); throw cause }` the flag stays `true` on cancellation
-and nothing is reported. A flag that must clear on cancellation is therefore written in `finally` through
-`capture(state)`. A guard in a `finally` saves nothing and is still reported, and so is a check of `signal.aborted`
-that neither throws nor returns. `effect`, `event` and the other reactions are left alone: a newer value is what
-cancelled their run, and dropping its write is the point (D288). The context is resolved exactly: the `call` of a
-`ModelContext` parameter or of the context of `model(Declaration, factory)` inside a `defineFeature` of
-`@opetope/runtime` (D309); a feature's own `call` hands its body no writer.
-
-### `prefer-model-selection`
-
-A component that takes one granted model and reads its fields through a hook each repeats the same wiring. From
-three fields upwards the rule points at one selection instead (D205, D214):
+<a id="no-retired-vocabulary"></a>
+[See `no-retired-vocabulary`](../runtime/docs/reference/lint.md#no-retired-vocabulary).
 
-```js
-'opetope/prefer-model-selection': ['error', { threshold: 3 }],
-```
-
-It counts `useReadable(model.field)` and `useCommand(model.field)` over the variable of a `useModel(Declaration)`
-without a selection, and it counts each granted model separately: two models in one component are two grants, and
-the same variable name in two components is two counts. There is no fix — the shape of the selection is the
-author's to write.
-
-## Coexistence with key sorting
-
-A host that sorts object keys alphabetically will disagree with `define-feature-property-order`, because the
-sections of a feature are ordered by meaning and not by name. `recommended` touches no sorting rule: reconciling
-them belongs to the host, and there are two ways.
-
-**`perfectionist/sort-objects`** takes a named order for exactly the two callees that declare sections, and keeps
-its plain configuration for every other object:
-
-```js
-'perfectionist/sort-objects': [
-  'error',
-  {
-    customGroups: [
-      { elementNamePattern: '^id$', groupName: 'feature-id' },
-      { elementNamePattern: '^imports$', groupName: 'feature-imports' },
-      { elementNamePattern: '^requires$', groupName: 'feature-requires' },
-      { elementNamePattern: '^own$', groupName: 'feature-own' },
-      { elementNamePattern: '^exports$', groupName: 'feature-exports' },
-      { elementNamePattern: '^provides$', groupName: 'feature-provides' },
-      { elementNamePattern: '^when$', groupName: 'feature-when' },
-      { elementNamePattern: '^body$', groupName: 'feature-body' },
-    ],
-    groups: [
-      'feature-id',
-      'feature-imports',
-      'feature-requires',
-      'feature-own',
-      'feature-exports',
-      'feature-provides',
-      'feature-when',
-      'feature-body',
-      'unknown',
-    ],
-    order: 'asc',
-    type: 'natural',
-    useConfigurationIf: { callingFunctionNamePattern: '^(?:defineFeature|defineFeature\\.body)$' },
-  },
-  { order: 'asc', type: 'natural' },
-],
-```
-
-**ESLint core `sort-keys`, and the rule of the same id in Oxlint**, has no per-callee configuration and no
-per-declaration exception: it reports each key that follows a larger one, wherever the object is. Turn it off for
-the files that declare features, or wrap a declaration in `/* eslint-disable sort-keys */` and
-`/* eslint-enable sort-keys */` — a `// eslint-disable-next-line sort-keys` covers one line, so it silences one
-section, not a multi-line declaration. Oxlint reads the same directives under its own prefix,
-`// oxlint-disable-next-line sort-keys`.
+<a id="coexistence-with-key-sorting"></a>
+[See Coexistence with key sorting](../runtime/docs/reference/lint.md#coexistence-with-key-sorting).
 
-The fix of this rule moves keys only inside the object of a `defineFeature` call, so it never reorders anything a
-sorting rule owns elsewhere in the file.
-
-## Running the rules under Oxlint
-
-Oxlint reads ESLint plugins through `jsPlugins`: it imports the module by path and takes its default export. The
-rules stay on the plain rule API — `meta`, `create(context)` with visitors, `context.report` with a `fix`, and
-`getText`/`getCommentsInside` on the source code — with no typed services and no ESLint-only capability, so both
-linters run them, autofix included:
-
-```json
-{
-  "extends": ["./node_modules/@opetope/lint/oxlintrc.json"],
-  "jsPlugins": [{ "name": "opetope", "specifier": "./node_modules/@opetope/lint/dist/index.js" }]
-}
-```
+<a id="running-the-rules-under-oxlint"></a>
+[See Running the rules under Oxlint](../runtime/docs/reference/lint.md#running-the-rules-under-oxlint).
 
-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, 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. `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.
+<a id="checks"></a>
+[See contributor checks](../runtime/docs/maintainers/contributing.md).