@opetope/lint 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @opetope/lint
+
+## 0.1.0
+
+Initial release. See the package README for the supported API and usage.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksei Berezin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,335 @@
+# @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.
+
+## Installation
+
+```sh
+npm install --save-dev @opetope/lint 'eslint@^9' '@typescript-eslint/parser@^8'
+```
+
+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.
+
+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.
+
+## Usage
+
+```js
+// eslint.config.mjs
+import opetope from '@opetope/lint';
+
+export default [
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    ...opetope.configs.recommended,
+  },
+];
+```
+
+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-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.
+
+### `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 })` keeps `@opetope/*/internal` out of the code that is neither the
+runtime nor its host integration. `allow` names the files that do that work — the restriction does not reach them,
+so whatever else the project restricts there stays in force — and `files` is what the restriction covers, by
+default every `.ts` and `.tsx`.
+
+```js
+...opetope.configs.internalImports({ allow: ['src/bootstrap/**/devtools.ts'] }),
+```
+
+`no-restricted-imports` is a core rule with one value per file, and in a flat config the last entry that names it
+wins. A project that already configures that rule takes `opetope.internalImportPattern` into its own entry instead
+of spreading this configuration, which would replace that entry for every file it covers:
+
+```js
+'no-restricted-imports': ['error', { paths: myPaths, patterns: [...myPatterns, opetope.internalImportPattern] }],
+```
+
+The files that integrate the host then get the same entry without that one pattern, so they keep every other
+restriction the project makes.
+
+## Rules
+
+### `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: `id`, `imports`, `requires`, `own`, `exports`, `provides`, `when`,
+and the `body` loader that replaces the last three stages (spec §2.1, D186). The order is the reading order of the
+declaration — identity, 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.
+
+### `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({
+  id: '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`. `defineHostContract`, `defineModel` and `definePort` take the id as their first
+argument; the rest take the `id` key of their options.
+
+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.
+
+**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.
+
+### `id-naming`
+
+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 project that reserves a first segment names it, and every declaration of those files must open with it:
+
+```js
+'opetope/id-naming': ['error', { prefix: 'workspace' }],
+```
+
+**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.
+
+### `layer-placement`
+
+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:
+
+| Declaration                                                                                                             | Layer                                                  |
+| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `defineFeature`                                                                                                         | integration — a feature composes the other two layers  |
+| `defineModel`                                                                                                           | models, or the UI contracts that declare a mount model |
+| `defineSlot`, `defineSwitchSlot`, `definePipe`, `defineRegistry`, `definePort`, `defineCondition`, `defineHostContract` | integration, or the UI contracts beside the component  |
+| `defineApplication`                                                                                                     | none of them: the host bootstrap owns it               |
+
+**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.
+
+### `no-snapshot-read-in-render`
+
+`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 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.
+
+**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.
+
+### `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 `stream`.
+
+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.
+
+### `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):
+
+```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`.
+
+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
+{
+  "jsPlugins": [{ "name": "opetope", "specifier": "./node_modules/@opetope/lint/dist/index.js" }],
+  "rules": { "opetope/when-predicate": "error" }
+}
+```
+
+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.
+
+## 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.