@opetope/lint 0.11.0 → 0.12.1

package/README.ru.md

@@ -1,648 +0,0 @@
-# @opetope/lint
-
-Правила ESLint для кода, который пишет автор на Opetope. Плагин держит только то, что синтаксическая проверка может
-доказать об объявлении: формы, которые компилируются и работают, но говорят не то, что имел в виду автор. То, на что
-уже отвечают проверка типов, рантайм и анализ мёртвого кода, остаётся за ними (см. [`../docs/decisions.md`](https://www.npmjs.com/package/@opetope/runtime), D227).
-
-Пакет не зависит ни от одного другого пакета `@opetope/*` и не читает типы, поэтому хост может линтовать исходники,
-которые ещё не собирал.
-
-## Установка
-
-```sh
-npm install --save-dev @opetope/lint 'eslint@^9' '@typescript-eslint/parser@^8'
-```
-
-Используйте согласованные версии Opetope. Для release candidate добавьте `@next` каждому пакету `@opetope/*` в команде.
-API поставляется только в ESM; требуется Node 20.19+. Команды разработки ниже относятся к contributor checkout.
-
-Нормативные руководства EN/RU поставляются в `@opetope/runtime`: после его установки откройте
-`node_modules/@opetope/runtime/docs/spec.md` или `spec.ru.md`; рецепты находятся в `cookbook.md` и `cookbook.ru.md`.
-Для чтения установленных руководств доступ к GitHub не нужен.
-
-## Usage
-
-```js
-// eslint.config.mjs
-import opetope from '@opetope/lint';
-
-export default [
-  {
-    files: ['src/**/*.{ts,tsx}'],
-    ...opetope.configs.recommended,
-  },
-];
-```
-
-Плагин — это и default export, и именованный `opetopeLint`. Конфигурация регистрирует его в namespace `opetope`,
-поэтому правило называется `opetope/when-predicate`. Для разбора нужен `@typescript-eslint/parser`; он и `eslint`
-объявлены peer dependencies.
-
-## Configs
-
-### `recommended`
-
-Все правила, которые действуют везде, где пишут на Opetope: `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` и `require-declared-models` как error. Правило, которому нужно знать, где хост держит свои файлы, здесь выключено и
-приходит через `layers`; `prefer-model-selection` выключено потому, что число hooks, которое компонент вправе
-держать, каждый проект решает для себя.
-
-`configs.recommended.rules` целиком — и ровно это поставляется как `@opetope/lint/oxlintrc.json`:
-
-| Правило                         | `recommended` | Включает                                        |
-| ------------------------------- | ------------- | ----------------------------------------------- |
-| `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`       | плюс сужение через `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`         | проект, со своим `threshold`                    |
-| `require-declared-models`       | `error`       |                                                 |
-| `require-literal-id`            | `error`       |                                                 |
-| `when-predicate`                | `error`       |                                                 |
-
-Три `off` — это ровно те три, которым нужно знание, которое есть только у проекта: какие каталоги каким слоем
-являются и сколько hooks вправе держать один компонент.
-
-### `layers`
-
-`opetope.configs.layers({ integration, models, ui, tests })` принимает глобы собственных слоёв проекта и
-возвращает ту конфигурацию, которую каждый из них заслужил. Слой без глобов — это слой, которого у проекта нет, и
-он не даёт ничего; файл, который не заявил ни один глоб, не размещает никто.
-
-```js
-...opetope.configs.layers({
-  integration: ['src/features/*/integration/**/*.{ts,tsx}'],
-  models: ['src/features/*/models/**/*.ts'],
-  ui: ['src/features/*/ui/**/*.{ts,tsx}'],
-}),
-```
-
-`integration`, `models` и `ui` включают `layer-placement` для своих файлов. `models` вместе с этим включает
-`no-subscribe-outside-models` для всех исходников и отступает в самом слое моделей и в `tests`, у которых значение
-по умолчанию `['**/__tests__/**', '**/*.spec.ts', '**/*.spec.tsx']`. Подписка покрыта и в файле, который не заявил
-ни один слой: забытая подписка — это ровно то, как она переживает своего читателя.
-
-### `internalImports`
-
-`opetope.configs.internalImports({ allow, files })` настраивает `opetope/no-internal-imports` для JavaScript и
-TypeScript, включая `.mjs`-тесты моделей. Правило уже включено в `recommended`; helper полезен для ограничения
-области проверки или явного перечисления доверенных файлов реализации библиотеки и интеграции хоста.
-`allow` выключает только это правило в указанных файлах. Размещайте блоки helper **после** `recommended`:
-последующий блок `recommended` снова включает правило, в том числе для разрешённых файлов. Остальные ограничения
-проекта продолжают действовать.
-
-```js
-export default [
-  opetope.configs.recommended,
-  ...opetope.configs.internalImports({ allow: ['src/bootstrap/**/devtools.ts'] }),
-];
-```
-
-Отдельное правило не изменяет `no-restricted-imports`. Прежний экспорт `internalImportPattern` удалён:
-включайте это правило или helper вместо добавления паттерна Opetope в ограничения хоста (D261).
-
-## Rules
-
-### `no-internal-imports`
-
-Код приложения и тесты импортируют публичные входы Opetope. Правило запрещает `@opetope/*/internal` и вложенные
-пути в imports, re-exports, литеральных `import()`, незатенённых `require()`, TypeScript import types и
-`import = require`. Type-only импорты тоже проверяются: внутренний тип связывает потребителя с приватным ABI.
-Для запуска настоящего Call модели есть `runCall` из `@opetope/core/testing`, для открытия модели без фичи — `openModel` из `@opetope/runtime/testing`, для создания фикстуры — `command` из `@opetope/react/testing`.
-Автоматического исключения для тестов нет. Доверенные файлы реализации библиотеки или интеграции хоста можно
-разрешить явным override; autofix отсутствует, потому что публичная замена зависит от импортированной операции.
-
-**Граница.** Проверка синтаксическая: строковые пути модулей и шаблоны без подстановок. Она не разрешает алиасы,
-вычисляемые пути, граф re-exports или пользовательские загрузчики. Локальный `require` не считается загрузчиком
-Node. Применяйте конфигурацию ко всем используемым JavaScript/TypeScript исходникам и тестам.
-
-### `when-predicate`
-
-`when` вклада отвечает фактом видимости этого экземпляра, а не источником, который этот факт несёт (D220). Правило
-читает `when` у вкладов `slot`, `pipe` и `register`, а также любой `when`, чья функция деструктурирует контекст
-вычисления `{ exports, imports, own, read }`, и сообщает о трёх формах:
-
-| Написано                                   | О чём сообщает                                                                        |
-| ------------------------------------------ | ------------------------------------------------------------------------------------- |
-| `when: ({ imports }) => imports.x.allowed` | возвращает источник; фикс приводит к `({ imports, read }) => read(imports.x.allowed)` |
-| `when: async ({ read }) => read(x)`        | предикат отвечает синхронно; без фикса                                                |
-| `when: () => allowed`                      | `Readable<boolean>` передаётся в `when` как есть, без обёртки; без фикса              |
-
-Фикс оборачивает возвращённое обращение к полю в `read(...)` и добавляет `read` в деструктуризацию контекста, если
-его там нет. Именованный контекст читается через себя: `context => context.imports.x.allowed` становится
-`context => context.read(context.imports.x.allowed)`.
-
-**Граница.** Правило читает формы, а не типы. `({ read }) => read(counter)` над не-boolean источником остаётся
-ошибкой типов, как и `read` над тем, что не является `Readable`. Если обращение к полю контекста вычисления — это
-обычное значение, а не источник, предикат не может изменить свой ответ, и правило сообщает о нём как о написанном
-для источника; вынеси такое решение из `when` или заглуши строку. `when` вне вклада — позиционный
-`(current, previous)` у `effect` или значение источника у `scope.while` — правило не трогает.
-
-### `define-feature-property-order`
-
-Фича объявляет свои секции в одном порядке: `imports`, `requires`, `own`, `exports`, `provides`, `when` и
-загрузчик `body`, который заменяет три последние стадии (spec §2.1, D186). Идентичности среди них нет — фича
-называет себя первым аргументом (D280). Порядок совпадает с порядком чтения объявления — рёбра, стадии, затем
-время жизни и загрузчик, — поэтому читатель находит секцию по её месту, а сортировщик ключей можно настроить на
-тот же порядок вместо второго.
-
-Фикс переставляет свойства. Он отступает, если между двумя секциями стоит комментарий: такой комментарий не
-принадлежит ни одной из них, и перестановка увела бы его от строки, которую он объясняет; комментарий внутри секции
-переезжает вместе с ней. Объект с ключом, который не является секцией, или со spread остаётся проверке типов.
-
-### `no-redundant-const-tuple`
-
-`derive` принимает кортеж источников `const`-параметром типа, поэтому `[left, right]` выводит собственный кортеж, и
-селектор уже видит точные значения. Написанный рядом `as const` утверждает то, что и так утверждает сигнатура
-(D279, D309):
-
-```ts
-const summary = derive([total, label], (value, suffix) => `${value} ${suffix}`);
-```
-
-Правило читает первый аргумент `derive`, разрешённого к `@opetope/core`, и только там, где этот аргумент —
-литерал массива с `as const`. Фикс убирает утверждение и ничего больше. Он отступает, если между кортежем и
-утверждением стоит комментарий: такой комментарий не принадлежит ни одному из них, и удаление увело бы его вместе
-с диапазоном.
-
-**Граница.** Утверждение, написанное в другом месте, остаётся нетронутым: на одном элементе кортежа, где оно
-говорит об этом элементе; на результате селектора; на записи опций; и на форме с одним источником, аргумент
-которой вообще не кортеж. `as Sources` — другое утверждение и говорит другое. Импорт разрешается в пределах одного
-модуля: локальный alias, `const`, который держит импорт, и namespace-привязка достигают одного и того же экспорта,
-— а в отличие от `no-command-in-deps` правило узнаёт только импорт из `@opetope/core` и ничего больше: реэкспорт
-через собственный barrel хоста оно не видит. Это осознанная цена за безопасный фикс. Правило правит код, а у
-собственного `derive` хоста нет `const`-параметра типа, который делал бы утверждение лишним, — снятие `as const`
-там молча изменило бы выведенные типы.
-
-### `require-declared-models`
-
-Компонент, читающий UI-модель отдельного mount, объявляет её через `requiresModels`. Owner-модели остаются
-доступны всему subtree вклада без такого объявления (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)],
-    })),
-  }),
-});
-```
-
-Правило проверяет вклады, переданные capability `slot` из видимого callback `provides` в `defineFeature` или
-`defineFeature.body`. Локальный компонент, получающий UI-модели, объявляет свои требования; каждый видимый
-компонент или hook, читающий одну из этих моделей, объявляет собственный список. Обёртка родителя не объявляет
-требования вложенной функции.
-
-Поддерживаются named и namespace imports, aliases импортов и локальных значений, именованный контекст `provides`,
-inline и именованные компоненты. Bindings сравниваются в своих лексических scope: посторонняя локальная функция
-`useModel`, `requiresModels` или `slot` не становится API Opetope из-за совпадения имени. Named API из относительных
-реэкспортов распознаётся по экспортированным именам без чтения другого файла.
-
-**Граница.** Анализ ограничен одним модулем и следует видимым локальным объявлениям и возвратам фабрик.
-Произвольные объекты с `Component` и `models` не считаются вкладом. Реализации импортированных компонентов,
-динамические списки моделей и непрозрачные helpers остаются непроверенными: отсутствие диагностики не доказывает
-полноту их требований. Ссылки на модели должны быть видимыми локальными идентификаторами или aliases; правило не
-читает типы и не обходит отрендеренное React-дерево. Autofix отсутствует: выбор модели для чтения принадлежит
-автору. Проверки типов и runtime authority продолжают действовать.
-
-### `require-literal-id`
-
-Объявление называет себя строкой, которая написана, а не собрана там, где стоит объявление. Правило читает каждое
-объявление публичного словаря, которое называет себя: `defineFeature`, `defineApplication`, `defineCondition`,
-`defineHostContract`, `defineModel`, `definePort`, `defineSlot`, `defineSwitchSlot`, `definePipe` и
-`defineRegistry`, — и четыре из необязательного пакета Navigation: `defineScreen`, `defineSurface`, `defineLink` и
-`defineLinkHandlers`. D280 даёт им одну форму: id — первый аргумент у каждого.
-
-Написана — это строковый литерал, шаблон без выражений, имя, которое разрешается в импорт или в `const` того же
-модуля, и чтение поля у такого имени. Собрана — всё, что складывает место вызова: шаблон с выражением, конкатенация,
-вызов функции или имя, которое разрешается в параметр.
-
-Проект, который порождает набор объявлений по имени, говорит об этом один раз — называя такую фабрику:
-
-```js
-'opetope/require-literal-id': ['error', { allowInCallees: ['createSlots'] }],
-```
-
-Имя сверяется и с функцией, внутри которой написано объявление, и с вызовом, в который оно передано, поэтому
-покрыты обе формы фабрики.
-
-**Граница.** Имена правило отслеживает только внутри одного модуля: id, импортированный из другого файла, написан
-там, и там же проверяется его собственный текст. `defineModule`, `defineCallTarget` и `defineCallLane` из ядра оно
-не читает: их автор не пишет.
-
-### `id-naming`
-
-Id начинается с буквы и соединяет сегменты из букв и цифр одним из `.`, `/`, `:` или `-`, не длиннее 160 символов.
-Это грамматика, которую принимает `declarationId` в `@opetope/core`; id вне неё — это `DeclarationError` в момент
-выполнения объявления, а правило говорит об этом до запуска кода. Экран, поверхность и registry обработчиков ссылок
-проходят через тот же `declarationId`, поэтому правило читает и их; `defineLink` из него исключён: id ссылки — это
-канонический сегмент пути URL в нижнем регистре, который пакет проверяет сам и к которому зарезервированный префикс
-неприменим (D313).
-
-Проект, который зарезервировал первый сегмент, называет его, и каждое объявление таких файлов обязано с него
-начинаться:
-
-```js
-'opetope/id-naming': ['error', { prefix: 'workspace' }],
-```
-
-**Граница.** Правило проверяет те id, чей текст видно в файле: литерал или имя, которое разрешается в литерал того
-же модуля. Id, пришедший из другого модуля, проверяется там, где он написан.
-
-### `layer-placement`
-
-Каждое объявление написано в слое, который им владеет. Правило не сообщает ничего, пока проект не назвал свои слои
-через `configs.layers`: имена каталогов не являются законом фреймворка.
-
-| Объявление                                                                                                                               | Слой                                                           |
-| ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `defineFeature`                                                                                                                          | integration — фича сочленяет два других слоя                   |
-| `defineModel`                                                                                                                            | models или контракты UI, которые объявляют модель монтирования |
-| `defineSlot`, `defineSwitchSlot`, `defineSurface`, `definePipe`, `defineRegistry`, `definePort`, `defineCondition`, `defineHostContract` | integration или контракты UI рядом с компонентом               |
-| `defineApplication`                                                                                                                      | ни один из них: им владеет bootstrap хоста                     |
-
-**Это конвенция проекта, а не закон библиотеки.** Фреймворк говорит, что UI фичи импортирует только её собственные
-контракты, а модель не знает о фиче; где лежат эти файлы — выбор проекта, и правило держит тот выбор, который он
-объявил.
-
-### `no-snapshot-read-in-render`
-
-`getSnapshot()`, вызванный во время рендера компонента или хука, читает значение один раз и никогда не услышит
-следующее. Читайте через `useReadable` или выбирайте вместе с командами той же модели:
-`useModel(Declaration, (model, { read }) => ...)` (D205, D214).
-
-Область рендера — это функция с именем `use…` либо функция с заглавной буквы, возвращающая элементы. Правило
-смотрит на ту функцию, внутри которой написан вызов, поэтому снимок, прочитанный в обработчике события, эффекте
-или любом другом вложенном колбэке, остаётся: они выполняются после рендера, и им нужно значение того момента.
-
-**Граница.** Правило читает имя получателя, а не его тип: сообщается о каждом `getSnapshot()` в области рендера,
-какому бы объекту он ни принадлежал. Функция с заглавной буквы, не возвращающая элементов, — это фабрика, и её
-чтения остаются, включая фабрику модели вклада, которая читает props своего монтирования.
-
-### `no-snapshot-in-update`
-
-Значение, переданное в `update`, читает то состояние, которое собирается заменить, — и составное,
-`update(sessions, { items: sessions.getSnapshot().items, kind: 'loading' })`, и скалярное,
-`update(total, total.getSnapshot() + amount)`. Чтение выполняется там, где написан аргумент, — до записи и на
-состоянии, которое могло уже остановиться, где `getSnapshot()` отвечает значением, которое больше никто не
-сдвинет, — а вычисленное значение ложится на состояние, которое с тех пор могло уйти вперёд. У формы с апдейтером нет ни одной из этих бед: она
-читает в момент записи, а у записи, отброшенной вместе с отменённым контекстом, апдейтер не вызывается вовсе
-(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(...)`
-и молчит, пока `configs.layers` не назвал слой моделей, которому такая подписка разрешена; в компоненте читатель —
-это `useReadable` или выбор модели, а в фиче и в модели — `effect`, `event` или `connect` у `resource.live`.
-
-Передача функции без вызова подпиской здесь не является:
-`useSyncExternalStore(source.subscribe, source.getSnapshot)` передаёт ссылку, и читатель владеет тем, что начал.
-
-Не является ею и подписка, написанная там, где объявленный узел открывает свою работу и сам её освобождает.
-Disposer, который возвращает такой колбэк, принадлежит этому узлу и сливается вместе с поколением, которое его
-открыло, — поэтому правило там молчит: это ровно та форма, которую предписывает его собственное сообщение (D299):
-
-| Колбэк                                         | Где                         | Ингресс |
-| ---------------------------------------------- | --------------------------- | ------- |
-| `resource.live({ connect })`                   | член `connect`              | да      |
-| `event(from, subscribe, run)`                  | второй аргумент             | да      |
-| `scope.while` / `scope.switch` / `scope.keyed` | `open`, второй аргумент     | да      |
-| `attach(source, { open })`                     | член `open`                 | да      |
-| `attach(source, { open, close })`              | член `close`                | нет     |
-| `apply`, `load`, `run`, `when`, `key`          | модификаторы тех же вызовов | нет     |
-
-`resource.load` не открывает подписки и ингресса не имеет вовсе, поэтому `subscribe`, написанный в его `load`,
-сообщается как любая другая подписка руками (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,
-  }),
-});
-```
-
-«Внутри» считается до самого низа: вложенная стрелка, тело `function`, `await` на самой подписке, disposer,
-которому сначала дали имя. Контекст разрешается импортом, а не написанием: секция `own`, написанная прямо там, где
-её принимает `defineFeature`/`defineFeature.body`, взятый **из самого `@opetope/runtime`**, и фабрика модели —
-второй аргумент `model(Declaration, factory)` на том же `own` либо функция, первый параметр которой аннотирован
-`ModelContext` из `@opetope/core`. В отличие от `no-command-in-deps`, эти два якоря принимают только имя пакета:
-относительный импорт здесь позволил бы собственному `./my-own-context` хоста заглушить правило.
-`own.resource.live(...)` и деструктурированный `resource.live(...)` читаются одинаково, алиас отвечает тем ключом,
-из которого его достали (`{ resource: materialize }` — это по-прежнему `resource`), а `own.scope.while(...)`
-читается как деструктурированный `scope.while(...)`.
-
-Поэтому сообщение остаётся в четырёх формах, и каждая — граница того, что доказывает синтаксис: `resource.live`,
-который правило не проследило ни до одного якоря (импортированный откуда-то ещё, неразрешимый или принадлежащий чужому
-`defineFeature`); колбэк, написанный в другом месте и переданный сюда именем, — он не стоит лексически внутри;
-секция `own`, вынесенная в собственную привязку (`const own = ({ resource }) => …; defineFeature(id, { own })`); и
-`model(Decl, createOrderModel)`, где фабрика — именованная функция без аннотации `ModelContext`.
-
-### `prefer-effect-current`
-
-`run` эффекта уже получил то значение, ради которого его запустили. Чтение того же источника через
-`source.getSnapshot()` внутри этого прогона читает его второй раз и ничего не говорит о том, какой это прогон,
-поэтому правило переписывает его в `execution.current` (D296, D323):
-
-```js
-// было
-ctx.effect(quotes, execution => publish(quotes.getSnapshot()));
-// стало
-ctx.effect(quotes, execution => publish(execution.current));
-```
-
-Фикс пишет то слово, которое у прогона уже есть: имя контекста для `execution => …` и локальное имя, под которым
-взят `current`, для `({ current }) => …`. Прогон, не назвавший ни того ни другого, писать нечем, и тогда остаётся
-только сообщение.
-
-**Два случая, о которых правило сообщает, но не переписывает.** После первого `await` в прогоне `current` — это
-значение, с которым прогон начался, а снимок — значение текущего момента; смена источника обычно перезапускает
-прогон, поэтому обычно они совпадают, — а «обычно» не даёт права на правку. Под `when` они расходятся законно:
-фильтр допускает одни значения и пропускает другие, поэтому источник меняется без перезапуска прогона (D168, D296).
-Запись модификаторов, которую правило прочитать не может — собранную в другом месте, — оно считает несущей предикат.
-
-Чтение внутри вложенного колбэка прогона — в `timers.delay`, в обработчике подписки — остаётся как есть: этот код
-выполняется позже прогона, и ему нужно значение того момента. Как и всякое правило, которое правит код, это
-разрешает свой контекст точно: `effect`, о котором идёт речь, объявлен на параметре типа `ModelContext` либо на
-контексте `model(Declaration, factory)`, написанном внутри `defineFeature` из `@opetope/runtime` (D309).
-
-### `capture-command-cleanup`
-
-Писатель команды живёт столько же, сколько её вызывающий (D288). Запись в `finally` или `catch` у `try`, который
-ждёт `await`, выполняется после этого `await`, и после отмены вызова она отбрасывается без записи в reporter — так что
-уборка, которая должна была снять флаг занятости или метку ожидания, и есть та запись, которая не ляжет никогда.
-Правило сообщает о такой записи и называет слово, которое ляжет, — commit, взятый до `await` (D319, D330):
-
-```ts
-// сообщается: после отмены вызывающего `busy` остаётся `true`
-ctx.call(async (input, { signal, update }) => {
-  update(busy, true);
-  try {
-    await host.send(input, signal);
-  } finally {
-    update(busy, false);
-  }
-});
-
-// уборка ложится, пока жива модель
-ctx.call(async (input, { capture, signal, update }) => {
-  update(busy, true);
-  const done = capture(busy);
-  try {
-    await host.send(input, signal);
-  } finally {
-    done.update(() => false);
-  }
-});
-```
-
-Фикса нет: должна ли уборка лечь после ухода вызывающего — решение автора, а сброс — закон не без причины: поздняя
-запись отменённого вызова не должна затирать то, что написал более новый вызов. Поэтому сообщение называет оба выхода.
-Уборка, которая обязана выполниться для отменённого вызова, идёт через `capture(state)`, взятый до `await`; ответ,
-который не должен лечь после отмены, — отказ, результат, — стоит в `catch` после `rethrowIfCancelled(cause)`. Там, где
-вызывающий отменяет один прогон, чтобы начать следующий, — поиск, который потребитель запускает заново, Call,
-вызванный прогоном эффекта и отменённый более новым значением, — запись старого прогона и есть та, что лечь не должна,
-и об этом говорит комментарий-отключение.
-
-При `policy: 'parallel'` сообщение commit не советует. Вызовы такой команды перекрываются, поэтому захваченная уборка
-отменённого вызова сняла бы флаг, который ещё держит другой вызов, — флаг, общий для параллельных вызовов, гонится в
-любом случае, — и сообщение говорит держать такое состояние на вызов или оставить ход потребителю через `inFlight`.
-Правило видит политику, только когда `{ policy: 'parallel' }` написан на самом `call`; запись модификаторов,
-собранная в другом месте, читается как очередь по умолчанию, где lane ждёт физического тела и захваченная уборка
-ложится по порядку.
-
-Правило — эвристика над синтаксисом и ничего не доказывает о записи, о которой молчит. Писателя тела команды оно
-читает под такими именами: `execution.update(…)`; `({ update })` или `({ update: write })` в списке параметров;
-`const { update } = execution` внутри тела; и `const`, дающий одному из них второе имя, — `const write = update` или
-`const write = execution.update`. Тело, переданное локальной функцией, правило находит. Оно пропускает замыкание,
-держащее писателя (`const clear = () => update(busy, false)`, вызванное в `finally`), писателя, сохранённого не в
-`const`, и контекст, переданный helper-у. `try` считается, когда его защищённый блок ждёт в собственной функции тела:
-`await` или `for await` внутри вложенного колбэка приостанавливает этот колбэк, а не команду.
-
-В `catch` запись после `rethrowIfCancelled(cause)`, `signal.throwIfAborted()` или `if (signal.aborted)`, который
-бросает или возвращает, — в блоке, где стоит запись, или в любом охватывающем его блоке, — не сообщается. Такая
-проверка — заявление автора, что следующее за ней не должно выполняться для отменённого вызова, и правило верит ему на
-слово: в `catch (cause) { rethrowIfCancelled(cause); update(busy, false); throw cause }` флаг после отмены остаётся
-`true`, и сообщения нет. Поэтому флаг, который обязан сняться при отмене, пишется в `finally` через `capture(state)`.
-Проверка в `finally` ничего не спасает и сообщается по-прежнему, как и проверка `signal.aborted`, которая не бросает и
-не возвращает. `effect`, `event` и остальные реакции правило не трогает: их прогон отменило более новое значение, и
-сброс его записи — ровно то, что нужно (D288). Контекст разрешается точно: `call` параметра типа `ModelContext` либо
-контекста `model(Declaration, factory)` внутри `defineFeature` из `@opetope/runtime` (D309); собственный `call` фичи
-писателя телу не даёт.
-
-### `prefer-model-selection`
-
-Компонент, который берёт одну выданную модель и читает её поля по хуку на поле, повторяет одно и то же
-подключение. От трёх полей и выше правило показывает на один выбор вместо них (D205, D214):
-
-```js
-'opetope/prefer-model-selection': ['error', { threshold: 3 }],
-```
-
-Оно считает `useReadable(model.field)` и `useCommand(model.field)` над переменной из `useModel(Declaration)` без
-выбора и считает каждую выданную модель отдельно: две модели в одном компоненте — это два гранта, а одно и то же
-имя переменной в двух компонентах — два счёта. Фикса нет: форму выбора пишет автор.
-
-## Coexistence with key sorting
-
-Хост, который сортирует ключи объектов по алфавиту, разойдётся с `define-feature-property-order`: секции фичи
-упорядочены по смыслу, а не по имени. `recommended` не трогает ни одного правила сортировки — примирять их дело
-хоста, и способа два.
-
-**`perfectionist/sort-objects`** принимает именованный порядок ровно для двух callee, которые объявляют секции, и
-сохраняет обычную конфигурацию для всех остальных объектов:
-
-```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` и правило с тем же id в Oxlint** не настраиваются по callee и не знают исключения на
-объявление: они сообщают о каждом ключе, который идёт после большего, в любом объекте. Выключите правило для
-файлов, объявляющих фичи, или оберните объявление в `/* eslint-disable sort-keys */` и
-`/* eslint-enable sort-keys */` — `// eslint-disable-next-line sort-keys` покрывает одну строку, то есть глушит
-одну секцию, а не многострочное объявление. Oxlint читает те же директивы под своим префиксом,
-`// oxlint-disable-next-line sort-keys`.
-
-Фикс этого правила переставляет ключи только внутри объекта вызова `defineFeature`, поэтому он никогда не трогает
-то, чем правило сортировки владеет в остальном файле.
-
-## Running the rules under Oxlint
-
-Oxlint читает ESLint-плагины через `jsPlugins`: импортирует модуль по пути и берёт его default export. Правила
-остаются на чистом rule API — `meta`, `create(context)` с visitors, `context.report` с `fix`, `getText` и
-`getCommentsInside` у source code — без typed services и без ESLint-only возможностей, поэтому их выполняют оба
-линтера, вместе с автофиксом:
-
-```json
-{
-  "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 на валидной и невалидной фикстуре — через конфиг,
-который `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` идёт первым. `ci:test` заодно проверяет, что закоммиченный `oxlintrc.json`
-всё ещё равен `configs.recommended.rules`; после изменения этого конфига выполните `npm run oxlintrc:generate` и
-закоммитьте результат — именно поэтому файл не пишет сборка.