@drkmttr/adhere 0.10.0 → 0.11.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
@@ -110,10 +148,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 +234,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 +261,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.
 
@@ -337,6 +377,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 +512,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 +563,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 +625,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 +666,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 +728,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 +866,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 +874,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.11.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.11.0",
+    "@drkmttr/adhere-darwin-x64": "0.11.0",
+    "@drkmttr/adhere-linux-arm64": "0.11.0",
+    "@drkmttr/adhere-linux-x64": "0.11.0",
+    "@drkmttr/adhere-win32-x64": "0.11.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>;
+}
+```

package/presets/react/server/no-private-data-to-client.md

@@ -0,0 +1,23 @@
+---
+description: A Server Component must pass a Client Component only the fields it shows, never a whole database record, a secret, a token, or other data the user must not see, since every prop passed to a Client Component is sent to the browser.
+appliesTo: ["a React Server Component"]
+level: warning
+---
+
+## Must
+
+```tsx
+export default async function ProfilePage({ params }: { params: { id: string } }) {
+  const user = await db.user.findUniqueOrThrow({ where: { id: params.id } });
+  return <ProfileCard name={user.name} avatarUrl={user.avatarUrl} />;
+}
+```
+
+## Never
+
+```tsx
+export default async function ProfilePage({ params }: { params: { id: string } }) {
+  const user = await db.user.findUniqueOrThrow({ where: { id: params.id } });
+  return <ProfileCard user={user} />;
+}
+```

package/presets/react/server/server-functions-authorize-and-validate.md

@@ -0,0 +1,29 @@
+---
+description: A Server Function, one marked `"use server"`, is an endpoint any client can call with any arguments, so it must check that the caller is signed in and allowed to do what it does, and validate its arguments at runtime; it must never trust that only the app's own UI calls it.
+appliesTo: ["a Server Function, marked \"use server\""]
+---
+
+## Must
+
+```ts
+"use server";
+
+export async function deletePost(input: unknown) {
+  const session = await getSession();
+  if (!session) throw new Error("Not signed in");
+  const { postId } = DeletePostInput.parse(input);
+  const post = await db.post.findUnique({ where: { id: postId } });
+  if (post?.authorId !== session.userId) throw new Error("Not allowed");
+  await db.post.delete({ where: { id: postId } });
+}
+```
+
+## Never
+
+```ts
+"use server";
+
+export async function deletePost(postId: string) {
+  await db.post.delete({ where: { id: postId } });
+}
+```

package/presets/react/state/no-contradictory-state.md

@@ -0,0 +1,17 @@
+---
+description: State that describes one thing's status, such as whether a request is being sent, was sent, or failed, should be a single state that holds one status at a time, and should not be separate booleans that can say contradictory things at once.
+appliesTo: ["a React component or hook"]
+---
+
+## Should
+
+```tsx
+const [status, setStatus] = useState<"typing" | "sending" | "sent">("typing");
+```
+
+## Should not
+
+```tsx
+const [isSending, setIsSending] = useState(false);
+const [isSent, setIsSent] = useState(false);
+```