@drkmttr/adhere 0.10.0 → 0.12.0

package/README.md

@@ -1,14 +1,22 @@
 <div align="center">
 <h1>adhere</h1>
+  <sup>A linter for non-deterministic rules. Powered by Typesafe</sup>
 </div>
 
-A linter for rules a normal linter cannot check. A rule is a one-sentence
-description in RFC 2119's words, like "business logic must live in services",
-with code that must be written that way, code that must never be, or both. For
-each source file, adhere asks [Jev](https://typesafe.ai) (TypeSafe AI's System One
+A linter for rules a normal linter cannot check. Describe rules using RFC2119
+language, like "business logic MUST live in services", or "A 3rd-party API going down
+SHOULD NOT also take us down". A rule also includes a good example, a bad example, or 
+both (which is highly recommended according to [our studies](eval/studies/example-count.md).) 
+
+For each source file, adhere asks [Jev](https://typesafe.ai) (TypeSafe AI's System One
 model) whether the file breaks each rule, gets a calibrated probability per
-rule, and reports the ones above a threshold with the line Jev points at. The
-report uses the same frame as `vp lint`.
+rule, and reports the ones above a threshold with the section of the file Jev
+points at. The report uses the same frame as `vp lint`.
+
+Here's a demo of what the output looks like:
+
+<a href="https://asciinema.org/a/1266511" target="_blank"><img width="400" src="https://asciinema.org/a/1266511.svg" /></a>
+
 
 Rules a normal linter can check exactly, such as a banned import or a type
 error, belong in that linter. While it lints, adhere asks Jev whether a normal
@@ -16,10 +24,10 @@ linter could check each of your rules, and [`adhere validate`](#validate) lists
 rules that it thinks belong in a regular linter, and also detects any
 contradictions in your rules.
 
-A preset for effect is included which can be run without setup:
+Presets for TypeScript, React, security, Effect, and alchemy are included, and run without setup:
 
 ```sh
-TYPESAFE_API_KEY=xxx npx @drkmttr/adhere lint --preset effect
+TYPESAFE_API_KEY=xxx npx @drkmttr/adhere lint --preset typescript
 ```
 
 ## Install
@@ -54,6 +62,9 @@ built-in Effect rules. A finding looks like this:
 ```text
   × data/brand-ports (0.93): A port must be a branded, range-checked integer, never a bare number.
    ╭─[src/server.ts:6:3]
+ 1 │ import { Effect } from "effect";
+ 2 │ import { listen } from "./listen.ts";
+ 3 │
  4 │ export const serve = Effect.gen(function* () {
  5 │   const host = process.env.HOST ?? "localhost";
  6 │   const port: number = Number(process.env.PORT ?? 3000);
@@ -73,12 +84,38 @@ Found 1 error.
 
 The header is the rule id, Jev's probability, and the rule's description. A
 preset's rule has the preset's name first, as in
-`effect/basics/external-calls-are-resilient`, so a report that mixes presets
+`effect/basics/gen-for-sequencing`, so a report that mixes presets
 with a repo's own rules says where each came from.
-Under it is the line Jev points at, underlined, with the code around it: the
-largest statement around the line that is 30 lines or fewer, usually the whole
-function, and up to 3 lines of whole statements on either side. The
-hint is the rule's code that must be written; a rule with only code that must
+Under it is the section of the file Jev points at, with the line it names
+underlined, or the lines, when it names several, marked with a bar beside the
+code. adhere splits each file into sections of whole statements, such as
+its imports, constants, and functions, packed in order into runs of at most 30
+lines; a class or function longer than that splits into its methods or the
+statements of its body. Jev reads the file as these sections and chooses one,
+and in the same request the line in it where the violation starts and the one
+where it ends: on the eval it judged as well that way, and the lines it named
+held a violation for 94% of real findings, most often as one line. When it
+names no lines, the section is shown alone, at its first line.
+
+Jev is also asked whether the file shows enough to decide the rule at all:
+whether it turns on something the file does not show, such as what another
+file, a library, or a service does. When Jev's probability that it does is
+below 0.6, the finding gets a warning under its code, with the probability
+that it does not, and help on adding what is missing:
+
+```text
+  warning: this file may not show enough to check this rule (Jev: 0.55 that it does not)
+     help: add what the code relies on outside this file as a note Jev reads:
+           // @adhere <the fact>, and how you know it
+```
+
+On the eval, most findings with this warning were false, where about one in
+five of all findings was: check what the code relies on outside the file
+before acting on it. What you find can go in an `@adhere` note, which Jev
+reads (see [Comments](#comments)). `sufficiencyThreshold` in the config, or `--sufficiency-threshold`, sets
+the cutoff. The warning changes neither the finding's level nor the exit code.
+
+The hint is the rule's code that must be written; a rule with only code that must
 never be written shows that code, labeled `never:`, instead. A rule whose
 level is `warning` reports its findings with `⚠` in place of `×`, in amber. On
 a terminal, the report is in color and the code in it is highlighted. The exit
@@ -93,6 +130,7 @@ an unknown command or flag; a refusal prints its reason.
 adhere lint                    # audit the working directory
 adhere lint --preset effect    # add a built-in rule set; the config becomes optional
 adhere lint --threshold 0.9    # replace the config's threshold; per-rule thresholds still apply
+adhere lint --sufficiency-threshold 0.5  # warn on fewer findings that may turn on other files
 adhere lint --yes              # send the requests without asking first
 adhere lint --limit 500        # judge at most 500 checks; the rest wait for the next run
 adhere lint --rpm 30           # send at most 30 requests a minute
@@ -101,6 +139,9 @@ adhere lint --deny-warnings    # fail on warnings as well as errors
 adhere lint --log-level debug  # log each request to Jev on stderr
 adhere validate                # check the rules' wording; ask Jev whether any contradict
 adhere init [--force]          # scaffold .adhere/config.ts and two example rules
+adhere init --shared org/repo  # scaffold a repo of rules other repos install
+adhere list org/repo           # list the rules in another repo's .adhere/
+adhere install org/repo        # copy them into this repo's .adhere/org/repo/
 adhere login                   # save a TypeSafe AI API key for later runs
 adhere logout                  # delete the saved key
 adhere skill                   # print the agent skill (below)
@@ -110,10 +151,6 @@ Bare `adhere` prints the help, which lists the commands, and
 `adhere <command> --help` lists a command's flags. `adhere --completions <shell>`
 prints a completion script.
 
-### Demo
-
-<a href="https://asciinema.org/a/1266511" target="_blank"><img width="400" src="https://asciinema.org/a/1266511.svg" /></a>
-
 ### Before and during a run
 
 Until it knows what judging takes, a status line on stderr says what `lint` is
@@ -200,7 +237,8 @@ delete: Effect.fn(function* ({ output }) {
 
 On a line of its own, `adhere-ignore` covers the statement that starts on the
 next line of code: here the whole handler, wherever in it Jev points, since the
-line it points at can move between runs. At the end of a line of code, it
+lines it points at can move between runs. A finding without lines is covered
+when its section overlaps the statement. At the end of a line of code, it
 covers the statement that starts on that line. `adhere-ignore-file`, anywhere
 in a file, covers the whole file, and the rules it names are not judged there
 at all. A comment names rules as a report does, a preset's with its preset
@@ -226,17 +264,22 @@ adhere lint --log-level debug 2> adhere.log
 
 ### What gets read
 
-`adhere lint` reads the `.ts` files under the working directory, except `.d.ts`
-and config files. When the working directory contains `agents/`, `apps/`, or
+`adhere lint` reads the TypeScript files under the working directory, `.ts`,
+`.tsx`, `.mts`, and `.cts`, except declaration files such as `.d.ts` and
+config files. When the working directory contains `agents/`, `apps/`, or
 `packages/`, only those trees are read. Below the working directory, anything
 under `node_modules/`, `dist/`, `coverage/`, `vendor/`, `e2e/`, `references/`,
 `.adhere/`, `.agents/`, `.claude/`, `.direnv/`, `.alchemy/`, or `.vite/` is
-skipped; the directories above it do not count. `.tsx` files are not read, and
-`.gitignore` is not consulted.
-
-Tests are judged only by rules about tests. A test is a `.test.ts` or
-`.spec.ts` file, or any file under a `test/`, `tests/`, `__tests__/`, or
-`fixtures/` directory, and only a rule whose front matter says `tests` judges
+skipped; the directories above it do not count. JavaScript files are not read,
+and `.gitignore` is not consulted.
+
+Tests are judged only by rules about tests. A test is a `.test` or `.spec`
+file, such as `a.test.ts` or `Button.spec.tsx`; a fixture or test helper named
+as one, such as `fixtures.ts`, `GitHubHttpFixtures.ts`,
+`ledger-copy.fixture.ts`, `linear-test-helpers.ts`, or `test-utils.ts`; or any
+file under a `test/`, `tests/`, `__tests__/`,
+`testing/`, `fixtures/`, `fixture/`, `__fixtures__/`, or `__mocks__/`
+directory, and only a rule whose front matter says `tests` judges
 one (see [Rules as Markdown files](#rules-as-markdown-files)). On alchemy, 38%
 of the findings from rules not about tests were in test helpers and fixtures.
 
@@ -267,6 +310,52 @@ msgpackr-extract, an optional native add-on that comes with `effect` and that
 adhere never uses, with a warning instead of failing.
 It skips the install when `package.json` already lists adhere.
 
+`adhere init --shared org/repo` scaffolds a repo whose rules other repos copy
+in with `adhere install` (see [Sharing rules](#sharing-rules)) instead of one
+that lints itself. It writes the two example rules and no config, since
+install copies only rule files, and with them:
+
+- `README.md`, which says what the repo is for, how to install its rules, and
+  how to add one.
+- `.github/workflows/adhere.yaml`, which runs `adhere validate` on every push
+  to main and every pull request, with the `TYPESAFE_API_KEY` secret. A pull
+  request from a fork gets no secrets, so validate refuses there.
+- `alchemy.run.ts`, an [alchemy](https://alchemy.run) stack that creates the
+  private GitHub repo, or adopts it, and sets that secret from
+  `TYPESAFE_API_KEY` when deployed with `npx alchemy deploy`.
+- `package.json`, with alchemy and effect pinned to versions that work
+  together, which init installs, and a `.gitignore` for them and alchemy's
+  state.
+
+### Sharing rules
+
+An organization's rules can live in one repo's `.adhere/`, and other repos
+copy them in. `adhere list org/repo` prints each rule there with its
+description. `adhere install org/repo` copies every rule into this repo's
+`.adhere/org/repo/`, so `data/brand-ports` from darkmatter/standards is
+`.adhere/darkmatter/standards/data/brand-ports.md`, the rule
+`darkmatter/standards/data/brand-ports`, and two repos' rules never collide.
+A topic or a rule after the repo copies only that part, and `#` picks a branch
+or tag:
+
+```sh
+adhere install darkmatter/standards/data                # the data topic
+adhere install darkmatter/standards/data/brand-ports    # one rule
+adhere install darkmatter/standards#v3                  # every rule, as tagged v3
+```
+
+The copies are the repo's own rules from then on: commit them, edit them, or
+start new rules from them. Nothing tracks where they came from, so a later
+install skips a file already there, as init does, and `--force` overwrites it,
+edits and all. Only Markdown rule files are copied; the source's config, its
+inline rules, and its cache are not. A config with inline `rules` replaces
+the `.adhere/` rule files, so it replaces copied ones too.
+
+The source is cloned with `git` from `https://github.com/org/repo.git`, so a
+private repo needs git's credentials for GitHub, as `gh auth setup-git` sets
+up. To clone over SSH instead, let git rewrite the URL:
+`git config --global url.git@github.com:.insteadOf https://github.com/`.
+
 ### Validate
 
 `adhere validate` loads the config, rule files, and presets the way `lint`
@@ -337,6 +426,7 @@ import { defineConfig } from "@drkmttr/adhere";
 export default defineConfig({
   model: "jev-latest", // optional, default "jev-latest"
   threshold: 0.8, // optional, default 0.8
+  sufficiencyThreshold: 0.6, // optional, default 0.6: below it, a finding warns to check outside the file
   presets: ["effect"], // optional, built-in rule sets
   exclude: ["**/generated/**"], // optional, files no rule judges
   overrides: { "effect/basics/instrument-with-pipe": "off" }, // optional, see Presets
@@ -471,6 +561,33 @@ export default defineConfig({ presets: ["effect"], rules: "./docs/adhere" });
 
 Rules read through `rules` apply project-wide.
 
+### Scoping a rule
+
+A rule can say where it applies, apart from what it asks for, with
+`appliesTo` and `excludeIf`: each a list of descriptions of code, written in
+front matter as a JSON array on one line, or as an array inline in a config.
+
+```md
+---
+description: Structured variants must be Schema.TaggedClass members of a Schema.Union, never hand-written object types joined by a tag field.
+appliesTo: ["a declared union type or schema"]
+excludeIf: ["a type that mirrors a third-party format whose tag key that format fixes, such as a Slack Block Kit block"]
+---
+```
+
+Each goes to Jev as a question of its own, in the same request as the rule,
+about the code that breaks the rule rather than the whole file: for
+`appliesTo`, whether any of that code is as described, and for `excludeIf`,
+whether all of it is. A finding stands only when Jev says yes, above 0.5, to
+every `appliesTo` and to no `excludeIf`, so a file with a real violation
+beside code an `excludeIf` describes keeps its finding. The scores are cached
+with the rule's judgment, and editing a matcher judges the rule again, as
+editing its description does. At `--log-level debug`, lint logs each finding
+its matchers dropped, with their scores.
+
+Keeping the scope out of the description keeps the description to what the
+rule asks for, which the report shows, and gives each part a score of its own.
+
 ### Rule writing tips
 
 We've evaluated different ways of giving Jev a rule, to catch the most
@@ -495,13 +612,30 @@ A preset has the shape of a config without `presets`: `rules`, and optionally
 command line with `--preset`, repeated or separated by commas, as in
 `--preset effect,alchemy`, in which case the config file is optional. Presets
 named in both places apply together. Reports name a preset's rule with the
-preset first, as in `alchemy/secrets/…`. There are two:
-
+preset first, as in `alchemy/secrets/…`. There are five:
+
+- `typescript`: 11 rules in [`presets/typescript/`](./presets/typescript/) for
+  any TypeScript project, drawn from the TypeScript Handbook and the Google
+  TypeScript Style Guide: data from outside checked at runtime, invalid states
+  unrepresentable, errors never swallowed, resources released on every path,
+  arguments not mutated, and tests that assert outcomes and stand alone.
+- `react`: 10 rules in [`presets/react/`](./presets/react/) for components
+  and hooks, lifted from react.dev, mostly
+  [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
+  and [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure):
+  logic for an event in its handler rather than an effect, effects that clean
+  up and ignore stale fetches, `useSyncExternalStore` for outside stores, state
+  that neither copies props nor contradicts itself, and Server Functions and
+  Server Components that guard what crosses to the client.
+- `security`: 4 rules in [`presets/security/`](./presets/security/), drawn
+  from OWASP's cheat sheets: secrets kept out of logs, error messages, and
+  responses; parameterized SQL; no untrusted input in shell commands, `eval`,
+  or file paths; and secrets compared in constant time. It has no topics.
 - `effect`: Markdown rules in [`presets/effect/`](./presets/effect/), lifted
   from the [effect-solutions](https://github.com/kitlangton/effect-solutions)
   docs and the
   [effect/platform](https://effect.website/docs/platform/introduction/) docs.
-- `alchemy`: 43 rules in [`presets/alchemy/`](./presets/alchemy/) for code that
+- `alchemy`: 41 rules in [`presets/alchemy/`](./presets/alchemy/) for code that
   deploys with [alchemy](https://alchemy.run), lifted from its docs and blog:
   where Config and bindings are read, which resources keep their data, how
   secrets stay out of bundles and logs, authorization on public URLs,
@@ -540,10 +674,9 @@ file does not show, so the rule also flags deletes of APIs that succeed
 anyway; see [the study](eval/studies/idempotent-delete.md).
 
 A preset rule says "must" only where its source makes a requirement, and
-"should" where the source gives advice. In `effect`, three rules are
-guidelines: network calls carry a timeout and a retry schedule, unless their
-client already applies both; test layers are in memory, outside integration
-tests; and tests provide config through a layer. Config validation accepts
+"should" where the source gives advice. In `effect`, two rules are
+guidelines: test layers are in memory, outside integration tests, and tests
+provide config through a layer. Config validation accepts
 `Config.mapOrFail` as well as `Config.schema`, and the variants rule does not
 rule out a `switch`. The rule that a command handler only parses input is
 gone: the docs show that pattern but do not ask for it.
@@ -582,18 +715,56 @@ whose types have no requirements to find. The preset's
 `services/dependencies-through-layers` asks for that, and
 `services/operations-have-no-requirements` for the style it goes with.
 
+`typescript` leaves out what typescript-eslint and ESLint check exactly:
+unhandled promises (`no-floating-promises`), throwing non-errors
+(`only-throw-error`), `any` (`no-explicit-any`), exhaustive switches
+(`switch-exhaustiveness-check`), a lost `cause` (`preserve-caught-error`), and
+empty catch blocks (`no-empty`). Four of its rules report warnings. Three are
+advice that code often has reason to set aside: assertions that claim only
+what the code established, types derived rather than restated, and
+independent awaits run concurrently. The fourth, that HTTP requests carry a
+timeout, was right on fewer than half its findings above 0.8 on the eval:
+many of the rest were calls through a client with a default timeout that the
+file does not show.
+Two rules the eval found mostly wrong are gone: that tests use fake time
+rather than real waits, and that importing a module does no work.
+
+Where effect or alchemy had a rule that `typescript` or `security` has, that
+one is kept and the other is gone: typescript's
+`async/network-calls-have-timeouts` replaced effect's
+`basics/external-calls-are-resilient`, and `security/parameterized-queries`
+and `security/no-secrets-in-output` replaced alchemy's
+`data/parameterized-sql` and `secrets/never-logged-returned-or-output`. A
+project on Effect or alchemy names those presets too, for those rules.
+
+`react` leaves out what the React Compiler's lint rules check, in
+[eslint-plugin-react-hooks](https://react.dev/reference/eslint-plugin-react-hooks)'s
+recommended set and in Oxlint: pure render (`purity`), props and state never
+mutated (`immutability`), refs not read during render (`refs`), no `setState`
+in render or synchronously in an effect (`set-state-in-render`,
+`set-state-in-effect`), which covers state derived in an effect, and no
+component defined inside another (`static-components`). Its rules judge `.ts`
+files as well as `.tsx`, and apply only to components, hooks, effects, and
+Server Functions, so other files cost their checks and find nothing.
+`server/no-private-data-to-client` reports warnings: a file does not show
+whether the component it passes a record to is a Client Component. So does
+`state/store-ids-not-copies`, which also flags state that copies a string or
+an option from a fixed list, where a copy cannot go stale.
+
 ### Precedence
 
 Highest first: `--threshold` on the command line, the config file, presets in
 order (a later preset wins), then the defaults `jev-latest` and `0.8`. A rule
 in `rules` replaces a preset rule with the same id. A rule's own `threshold`
 beats all of the above for that rule, and an entry in `overrides` beats the
-rule's own `threshold` and `level`.
+rule's own `threshold` and `level`. `--sufficiency-threshold` beats the
+config's `sufficiencyThreshold`, which beats the default, `0.6`.
 
 ## How a file is judged
 
-1. One Jev request per file. The state is the file's numbered lines, without
-   their comments (see [Comments](#comments)), and nothing else. Each rule is one `noul` (yes/no probability) question that
+1. One Jev request per file. The state is the file's sections (see the
+   report, above) under their numbers from 1, as `{ "1": "…", "2": "…" }`,
+   without their comments (see [Comments](#comments)), and nothing else. Each rule is one `noul` (yes/no probability) question that
    carries the rule's description and its code under its words, `must` and
    `never` (or a guideline's `should` and `should_not`): whether the file
    diverges from the pattern `must` shows, with `never` as an example of
@@ -606,14 +777,22 @@ rule's own `threshold` and `level`.
    project rule, the rule's question has a second one beside it, the linter
    check (see [Validate](#validate)), with the same fields.
 2. A second request only when at least one rule's probability is above its
-   threshold: one `choice` question per flagged rule over the file's non-blank
-   lines, which yields the line to report. A file with more than 255 non-blank
-   lines is located in two steps (a block of 20 lines, then a line inside it).
+   threshold. Per flagged rule, when the file has more than one section, one
+   `choice` question among the sections' numbers, which yields the section to
+   report. The options carry no text of their own, since each is a key of the
+   state: describing each section by its first line, or by what it declares,
+   located no better on the eval. For each section, two `choice` questions
+   among its lines, each option the line's text, of the line the violation
+   starts on and the one it ends on; the chosen section's are underlined.
+   Beside them, one `noul` carrying the rule:
+   whether you can tell if `code` breaks it from `code` alone, without knowing
+   what other files, libraries, services, or configuration do. It yields the
+   warning (see the report, above).
 3. Jev reads at most 32k tokens of state and one question together, and 64k
    tokens in a request. adhere estimates tokens from the JSON it sends, at
    about three bytes a token. When a file's questions would not fit in one
    request, they are split across several. A file whose code and longest
-   question would not fit together, or that has more than 5100 lines, is
+   question would not fit together, or that has more than 255 sections, is
    skipped and counted in the summary, and the rest of the run goes on. So is
    a file Jev itself counts as over its context, which text denser than the
    estimate, such as CJK, can cause.
@@ -736,7 +915,7 @@ and `bun run test` runs the tests.
 ### Native executable
 
 `bun run build` compiles `dist/adhere`, a single binary with Bun and the
-`effect` preset inside it, through Bun's
+presets inside it, through Bun's
 [`--compile`](https://bun.sh/docs/bundler/executables) with
 `--asset ./presets`. It runs without Bun or `node_modules` on the target
 machine and still loads the repo's `config.ts` and Markdown rules from disk.
@@ -744,6 +923,12 @@ machine and still loads the repo's `config.ts` and Markdown rules from disk.
 into its package under `dist/npm/`
 ([`scripts/npm-packages.ts`](./scripts/npm-packages.ts)).
 
+`adhere --version` tells the builds apart. A release prints its version, as
+`adhere v0.10.0`. `bun run build` prints `git describe --tags --dirty` where
+it was built, as `adhere v0.10.0-16-g9a41328`: 16 commits after v0.10.0, at
+`9a41328`, ending in `-dirty` when the tree had changes. Run from source, it
+prints the checkout's version marked `(source)`.
+
 Each platform's executable is its own npm package,
 `@drkmttr/adhere-<platform>-<arch>`, limited by `os` and `cpu`, and an
 optional dependency of `@drkmttr/adhere`, so an install fetches only its own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "start": "bun src/main.ts",
     "test": "vp test",
     "typecheck": "tsc --noEmit && bun run lint",
-    "build": "bun build --compile --minify --sourcemap src/main.ts --asset ./presets --outfile dist/adhere",
+    "build": "bun build --compile --minify --sourcemap --define ADHERE_BUILD=\"\\\"$(git describe --tags --dirty --always)\\\"\" src/main.ts --asset ./presets --outfile dist/adhere",
     "build:npm": "bun scripts/npm-packages.ts build",
     "release": "release-it"
   },
@@ -68,10 +68,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.10.0",
-    "@drkmttr/adhere-darwin-x64": "0.10.0",
-    "@drkmttr/adhere-linux-arm64": "0.10.0",
-    "@drkmttr/adhere-linux-x64": "0.10.0",
-    "@drkmttr/adhere-win32-x64": "0.10.0"
+    "@drkmttr/adhere-darwin-arm64": "0.12.0",
+    "@drkmttr/adhere-darwin-x64": "0.12.0",
+    "@drkmttr/adhere-linux-arm64": "0.12.0",
+    "@drkmttr/adhere-linux-x64": "0.12.0",
+    "@drkmttr/adhere-win32-x64": "0.12.0"
   }
 }

package/presets/effect/basics/gen-for-sequencing.md

@@ -1,5 +1,5 @@
 ---
-description: Sequential effectful steps must be written with Effect.gen and yield*, never as nested flatMap or callback chains.
+description: Sequential effectful steps must be written with Effect.gen and yield*, never as nested flatMap or callback chains. A single flatMap or andThen in a flat pipe is out of scope; the rule is about a step whose callback holds further steps.
 ---
 
 ## Must

package/presets/effect/data/brand-meaningful-primitives.md

@@ -1,5 +1,5 @@
 ---
-description: A primitive with semantic meaning, such as an id, email, URL, port, or count, must be a branded schema, never a bare string or number.
+description: A primitive with semantic meaning, such as an id, email, URL, port, or count, must be declared as a branded schema, never as a bare string or number. The rule judges where a type is declared, such as a schema field, an interface, or a type alias; a literal value, local variable, or parameter whose type is declared elsewhere is out of scope.
 ---
 
 ## Must

package/presets/effect/data/variants-are-tagged-unions.md

@@ -1,5 +1,5 @@
 ---
-description: Structured variants, alternatives that carry fields, must be Schema.TaggedClass members of a Schema.Union, never hand-written object types joined by a tag field. Simple alternatives without fields may be Schema.Literals.
+description: Structured variants, alternatives that carry fields, must be Schema.TaggedClass members of a Schema.Union, never hand-written object types joined by a tag field. Simple alternatives without fields may be Schema.Literals. The rule judges declared union types and schemas; an object literal with a tag field is out of scope, and so is a type that mirrors a third-party format whose tag key that format fixes, such as the type of a Slack Block Kit block.
 ---
 
 ## Must

package/presets/effect/services/dependencies-through-layers.md

@@ -1,5 +1,5 @@
 ---
-description: A service that depends on other services must be a Context.Service built by a Layer that yields those services as it is constructed, never a factory function or class that takes services, clients, or their implementations as arguments.
+description: A service that depends on other services must be a Context.Service built by a Layer that yields those services as it is constructed, never a factory function or class that takes services, clients, or their implementations as arguments and returns the service's operations with them built in. A helper that takes a client and one call's arguments and returns a single Effect is not a factory and is out of scope; the code that assembles the service from such helpers is in scope.
 ---
 
 ## Must

package/presets/react/effects/clean-up-what-they-start.md

@@ -0,0 +1,23 @@
+---
+description: An effect that subscribes to something, adds an event listener, starts a timer or an interval, or opens a connection must return a cleanup function that undoes it, never leave it running after the component unmounts or the effect runs again.
+appliesTo: ["a React effect"]
+---
+
+## Must
+
+```tsx
+useEffect(() => {
+  const onResize = () => setWidth(window.innerWidth);
+  window.addEventListener("resize", onResize);
+  return () => window.removeEventListener("resize", onResize);
+}, []);
+```
+
+## Never
+
+```tsx
+useEffect(() => {
+  const onResize = () => setWidth(window.innerWidth);
+  window.addEventListener("resize", onResize);
+}, []);
+```

package/presets/react/effects/event-logic-in-handlers.md

@@ -0,0 +1,29 @@
+---
+description: Code that runs because the user did something, such as submitting a form, clicking a button, or choosing an option, must run in that event's handler, never in an effect that watches state the handler set. An effect is for keeping a component in sync with something outside React while it is shown.
+appliesTo: ["a React component or hook"]
+---
+
+## Must
+
+```tsx
+function CheckoutForm({ cart }: { cart: Cart }) {
+  const handleSubmit = async (event: FormEvent) => {
+    event.preventDefault();
+    await placeOrder(cart);
+    showToast("Order placed");
+  };
+  return <form onSubmit={handleSubmit}>{/* fields */}</form>;
+}
+```
+
+## Never
+
+```tsx
+function CheckoutForm({ cart }: { cart: Cart }) {
+  const [submitted, setSubmitted] = useState(false);
+  useEffect(() => {
+    if (submitted) placeOrder(cart).then(() => showToast("Order placed"));
+  }, [submitted, cart]);
+  return <form onSubmit={() => setSubmitted(true)}>{/* fields */}</form>;
+}
+```

package/presets/react/effects/external-stores-use-sync-external-store.md

@@ -0,0 +1,38 @@
+---
+description: A component or hook that reads a value from a store outside React, such as a browser API like `navigator.onLine` or a store module, should subscribe to it with `useSyncExternalStore`, and should not copy the value into state from a subscription an effect sets up.
+appliesTo: ["a React component or hook"]
+---
+
+## Should
+
+```tsx
+const subscribe = (callback: () => void) => {
+  window.addEventListener("online", callback);
+  window.addEventListener("offline", callback);
+  return () => {
+    window.removeEventListener("online", callback);
+    window.removeEventListener("offline", callback);
+  };
+};
+
+export const useOnlineStatus = () =>
+  useSyncExternalStore(subscribe, () => navigator.onLine, () => true);
+```
+
+## Should not
+
+```tsx
+export function useOnlineStatus() {
+  const [isOnline, setIsOnline] = useState(true);
+  useEffect(() => {
+    const update = () => setIsOnline(navigator.onLine);
+    window.addEventListener("online", update);
+    window.addEventListener("offline", update);
+    return () => {
+      window.removeEventListener("online", update);
+      window.removeEventListener("offline", update);
+    };
+  }, []);
+  return isOnline;
+}
+```

package/presets/react/effects/fetches-ignore-stale-responses.md

@@ -0,0 +1,26 @@
+---
+description: An effect that requests data over the network must ignore or abort a response that arrives after its inputs changed or the component unmounted, such as with an `ignore` flag or an AbortController that its cleanup sets, never set state from every response in whatever order they arrive.
+appliesTo: ["a React effect"]
+---
+
+## Must
+
+```tsx
+useEffect(() => {
+  let ignore = false;
+  fetchResults(query).then((results) => {
+    if (!ignore) setResults(results);
+  });
+  return () => {
+    ignore = true;
+  };
+}, [query]);
+```
+
+## Never
+
+```tsx
+useEffect(() => {
+  fetchResults(query).then((results) => setResults(results));
+}, [query]);
+```

package/presets/react/effects/notify-parents-in-handlers.md

@@ -0,0 +1,29 @@
+---
+description: A component must tell its parent about a change, through a callback prop such as `onChange`, in the event handler that makes the change, never from an effect that watches the component's own state.
+appliesTo: ["a React component or hook"]
+---
+
+## Must
+
+```tsx
+function Toggle({ onChange }: { onChange: (isOn: boolean) => void }) {
+  const [isOn, setIsOn] = useState(false);
+  const toggle = () => {
+    setIsOn(!isOn);
+    onChange(!isOn);
+  };
+  return <button onClick={toggle}>{isOn ? "On" : "Off"}</button>;
+}
+```
+
+## Never
+
+```tsx
+function Toggle({ onChange }: { onChange: (isOn: boolean) => void }) {
+  const [isOn, setIsOn] = useState(false);
+  useEffect(() => {
+    onChange(isOn);
+  }, [isOn, onChange]);
+  return <button onClick={() => setIsOn(!isOn)}>{isOn ? "On" : "Off"}</button>;
+}
+```