@thomaflette/eslint-plugin-solid-2 0.1.0 → 0.2.1

package/docs/README.md

@@ -0,0 +1,24 @@
+# Rule documentation
+
+Each rule page explains the Solid 2 behavior it enforces, with examples and configuration details.
+
+## Reactivity and ownership
+
+- [components-return-once](./components-return-once.md)
+- [no-destructure](./no-destructure.md)
+- [no-leaf-owner-operations](./no-leaf-owner-operations.md)
+- [no-owned-scope-writes](./no-owned-scope-writes.md)
+- [no-reactive-read-after-await](./no-reactive-read-after-await.md)
+- [no-stale-props-alias](./no-stale-props-alias.md)
+- [no-untracked-read-in-effect-apply](./no-untracked-read-in-effect-apply.md)
+
+## JSX and control flow
+
+- [jsx-no-duplicate-props](./jsx-no-duplicate-props.md)
+- [prefer-for](./prefer-for.md)
+- [prefer-show](./prefer-show.md)
+- [self-closing-comp](./self-closing-comp.md)
+
+## Design records
+
+The [ADRs](./adr) document the plugin's false-positive policy, component detection strategy, and configuration decisions.

package/docs/adr/0001-only-false-positive-free-rules.md

@@ -0,0 +1,65 @@
+# Ship only false-positive-free rules; lean on tsc and runtime diagnostics
+
+**Context.** This is a brand-new Solid 2 plugin with no track record of bug
+reports, so we judge rules by _design-level_ false-positive risk, not by filed
+issues. Solid 2 also ships dev-mode runtime diagnostics (`STRICT_READ_UNTRACKED`,
+`SIGNAL_WRITE_IN_OWNED_SCOPE`, cleanup/flush/forbidden-scope errors, …) and the
+plugin targets TypeScript codebases where `tsc` is always running.
+
+**Decision.** A rule survives only if it has **zero false positives** (it may
+have false negatives — silently missing bad code is acceptable; lying about good
+code is not). We act on a rule's false positives by _cause_:
+
+- **Fix** it when the FP comes from a fixable implementation flaw (a crude
+  heuristic, a lagging allowlist, an unsafe autofix) _and_ it guards real value
+  that neither `tsc` nor the runtime covers.
+- **Delete** it (rule + tests + docs + config entry) when the FP is _fundamental_
+  (asks a statically undecidable question) or when `tsc` already flags the same
+  code in a TS codebase. "Disable in recommended" is not used.
+
+The plugin is **TypeScript-only** (we assume `tsc` runs) and every rule works
+from the AST/scope alone by default, so the default ruleset runs on **both oxlint
+and ESLint** (oxlint's plugin API has no type-checker). Type-aware analysis,
+where it helps, is **explicit and opt-in** via a per-rule `typescriptEnabled`
+option (off by default, documented as slower) and is **purely additive** — it
+finds more, never flips a verdict on correct code. See
+[ADR-0002](./0002-sound-component-detection.md) (component detection) and
+`prefer-for` (array-receiver check) for the rules that offer it.
+
+There is no exception for security-review heuristics. `no-innerhtml` and
+`jsx-no-script-url` were removed because sanitized HTML and author-defined URL-like
+props are valid code that static analysis cannot prove safe or unsafe.
+
+## Considered options
+
+- _Disable FP-prone rules in `recommended` but keep them shippable_ — rejected:
+  the default experience is where false positives hurt adoption, and we prefer a
+  small, trustworthy surface to a large, opt-out one.
+- _Keep all rules and accept some FPs_ — rejected: a linter that flags correct
+  code trains users to disable it.
+
+## Consequences
+
+- Deleted (fundamental FP): the original heuristic `no-untracked-reactive-read`,
+  `no-async-outside-loading-boundary`, `no-innerhtml`, `jsx-no-script-url`.
+- Deleted (tsc-subsumed): `jsx-no-undef`, `jsx-uses-vars`, `no-react-deps`,
+  `no-invalid-cleanup-return`, `no-array-handlers` (the `[handler, data]` tuple
+  is valid Solid 2 and `tsc` type-checks handlers), `no-unknown-namespaces`,
+  `accessor-as-prop-value`, `no-dynamic-keyed`, and duplicate JSX-attribute detection.
+- Verified empirically against Solid 2 `beta.17` types (tsgo): deletions fire on
+  correct code; survivors don't. `no-unknown-namespaces` is tsc-subsumed —
+  Solid 2's JSX types have no general namespace index signature (`prop:` needs
+  `ExplicitProperties` augmentation, the `class:${string}` index is commented
+  out, there is no `Directives`/`on:` mechanism), so `tsc` rejects every
+  removed/unknown/style/component-namespaced attribute the rule flags. The DOM
+  RFC (dom.md) also removed the `on:` namespace, which the rule still lists as
+  allowed — so it is stale as well as redundant.
+- A narrower strict-read analysis now lives behind `no-stale-props-alias`: it reports only reads
+  proven from bindings or nominal Solid accessor types, and recognizes JSX, nested closures,
+  reactive callbacks, and `untrack` as safe execution contexts. It does not restore the deleted
+  heuristic's guesses about arbitrary helper calls.
+- Runtime-state mirrors for `PENDING_ASYNC_FORBIDDEN_SCOPE`, `SETTLED_CLEANUP_UNOWNED`, and the
+  `NO_OWNER_*` diagnostics were prototyped and rejected. Whether they fire depends on the source's
+  pending state or the active owner at execution; an owner-backed scheduler and an already-settled
+  async memo are valid counterexamples to static callback/source heuristics. Solid's exact runtime
+  diagnostics own these cases.

package/docs/adr/0002-sound-component-detection.md

@@ -0,0 +1,66 @@
+# Sound component detection, with opt-in type-aware coverage
+
+**Context.** Several rules (`components-return-once`, `no-owned-scope-writes`,
+`no-destructure`) need to know "is this function a Solid component?" The original
+`isComponentLike` guessed _returns JSX and isn't lowercase-named_ — not sound: a
+JSX-returning helper called imperatively (`const cell = RenderRow(data)`) matched
+it and was falsely flagged. An earlier attempt made this two-tier with
+_automatic_ type-aware suppression, but that produced **corrective variance** —
+the AST-only result was a false positive that type info silently removed, so the
+same code was flagged under oxlint but clean under type-aware ESLint. Type-aware
+analysis also has a real cost (it forces a TS `Program`) that shouldn't be
+incurred silently.
+
+**Decision.** Detect components only by **sound** signals — never the leaky
+capitalized-JSX guess — and make any type-checker use **explicit and opt-in**:
+
+- **Default (AST/scope only, no type-checker):** a function is a component iff it
+  is annotated `Component`/`VoidComponent`/`ParentComponent`/`FlowComponent`, or
+  is used as `<C/>` in the same file. Zero false positives. Runs on oxlint.
+- **`typescriptEnabled: true` (per-rule option, off by default):** _additionally_
+  treat a function as a component when its symbol is used as a JSX tag anywhere
+  in the program (catches exported/cross-file components). Requires ESLint type
+  information and is slower; documented as such.
+
+The type-aware path is **purely additive** — it only ever finds _more_ real
+components, never flips a verdict on correct code. So there is no corrective
+variance: behaviour is consistent and zero-FP in every environment; the option
+only buys extra coverage at a cost the user opts into.
+
+## Consequences
+
+- Detection is exposed from `analysis/component-recognition.ts` as a self-indexing
+  `isComponent(node, context)`: it builds the in-file
+  `<C/>` usage index once per source (memoized on `SourceCode`) and reads `typescriptEnabled` from
+  `context` itself. Because that index is complete on first query, rules call it **inline during
+  traversal** — no rule threads a `jsxComponentNames` set or defers detection to `Program:exit`.
+  Do not push the index back onto callers.
+- The in-file `<C/>` index is keyed by **binding, not name** (`getInFileComponentVariables`): each
+  _direct_ identifier tag is resolved to the variable it references, so a local helper whose name
+  collides with an imported component is not conflated with it. Host elements (lowercase tags) and
+  member-tag roots (`<Foo.Bar/>` renders `Foo.Bar`, not `Foo`) are excluded — a function is detected
+  only when used as a bare `<Fn/>`. (An earlier name-string index false-positived on helpers named
+  like host elements — `title`, `summary` — or like an imported component.)
+- **Tolerated false negative (member tags):** a component rendered _only_ via a compound/namespaced
+  tag (`const Tabs = { Panel }; <Tabs.Panel/>`) is not detected by the default tier — excluding
+  member-tag roots is what removes the `<Theme.Provider/>` false positive (a config factory named
+  `Theme` is not a component). Zero-FP wins over this FN (ADR-0001); `typescriptEnabled` resolves the
+  member-tag symbol and still detects it.
+- The annotation signal resolves the type's **binding**, not just its name: a
+  function counts as a component only when `Component`/`VoidComponent`/… resolves
+  to a `solid-js` import (or an unresolved/ambient global), never a same-named
+  local `type`/`interface` or an import from another package. (The original
+  implementation matched the bare type name, which false-positived on a
+  user-defined `Component` type — an FP audit caught it; the annotation proof in
+  `analysis/component-recognition.ts` now enforces the binding, mirroring ADR-0003.)
+- **Tolerated false negative:** a bare, unannotated component used only in another
+  file is not detected by default. Close it by annotating it `Component<P>`,
+  using it as `<C/>` in-file, or enabling `typescriptEnabled`. Each rule's tests
+  include an explicit valid case documenting this, so the gap is visible.
+- Do **not** restore the capitalized-JSX heuristic — it reintroduces the false
+  positive and the corrective variance this decision removes.
+- `typescript` remains a peer dependency, used only by the opt-in path.
+- The original heuristic `no-untracked-reactive-read` stays deleted: sound component detection is
+  necessary but not sufficient. The narrower analyzer used by `no-stale-props-alias` additionally
+  proves the reactive binding and execution context; intentional one-time reads use explicit
+  `untrack`, matching the Solid 2 strict-read contract.

package/docs/adr/0003-require-solid-binding.md

@@ -0,0 +1,50 @@
+# Match Solid APIs by binding, not by bare name
+
+**Context.** The reactive-scope rules (`no-cleanup`/`no-flush`/`no-primitives-in-forbidden-scope`,
+`no-signal-in-effect-apply`) detected both the enclosing scope (`createTrackedEffect`, `onSettled`,
+`createEffect`) and the forbidden call (`flush`, `onCleanup`, a primitive factory) by **bare name**
+(`canonicalNames.has(name)`), with no check that the name actually came from `solid-js`. That
+false-positives on correct code that uses a same-named function from elsewhere — e.g. a stream
+library's `flush`, a state library's `createStore`, or a locally-defined `onCleanup` — called inside
+a genuine Solid scope. `flush`/`createStore`/`onCleanup` are common names, so this was real. (Verified
+by running the rules.) `resolveSolidCallee` had the same latent bug via an early bare-name fallback.
+
+**Decision.** Resolve the callee's binding before treating it as a Solid API (the shared resolver
+and binding-fact index live in `analysis/solid-bindings.ts`). A name counts as the Solid API only when it
+is a `solid-js` import (direct or aliased) **or** an unresolved global (auto-import). A name that
+binds to a local declaration or an import from another package is **not** the Solid API.
+`resolveSolidCallee` was tightened the same way and also handles namespace members and immutable
+`const` alias chains.
+
+## Consequences
+
+- The four rules (plus `no-store-proxy-in-effect-apply`, which uses `resolveSolidCallee`) no longer
+  false-positive on same-named non-Solid functions.
+- Genuinely-correct unresolved usage (`createTrackedEffect(() => flush())` with no import, relying on
+  auto-import/globals) still fires — we assume an unresolved canonical name is the Solid one.
+- This relies only on scope analysis (no type-checker), so it still runs under oxlint.
+- Rules with a `typescriptEnabled` path additionally use canonical TypeScript symbols to follow
+  Solid APIs through re-export chains; this remains additive to direct binding resolution.
+- Residual false negatives remain by design (a call indirected through a renamed local variable, or
+  reached via a nested helper) — tolerated per [ADR-0001](./0001-only-false-positive-free-rules.md).
+- **Resolution is self-contained (no caller-built alias index).** The shared source-level analysis
+  resolves direct, namespace, and `const`-aliased `solid-js` imports, so the per-rule alias `Set`s
+  and `ImportDeclaration` handlers that earlier fed a `(aliases, canonicalNames)` pair were redundant
+  and were removed; `bindsToSolid`/`resolveSolidCallee`/`isSolidApiCallbackArgument` now take only
+  `(identifier, context, canonicalNames)`. `resolveSolidCallee` returns the **canonical** name even
+  for an aliased import. The dead `collectSolidAliases` / `matchesSolidName` / `isCallbackArgumentOf`
+  helpers were deleted. Do not reintroduce a caller-side alias index "for speed" — `trace` is the
+  single resolution path. Reactive accessor/action/setter/store facts are indexed once per source
+  and reused by all consumers.
+- **The bare-canonical-name fallback fires only for a _truly unresolved_ global.** `trace` returns
+  the identifier unchanged both for an auto-import global _and_ for a local the tracer can't follow
+  (a `let`, a parameter, a destructured `const { onCleanup } = lib`). `resolveSolidCallee` therefore
+  re-checks with `findVariable`: a name that binds to any local declaration is the user's own and
+  resolves to null; only a name with no binding (or a defs-less global) is treated as the Solid API.
+  This closes a class of false positives on locally-named `flush`/`onCleanup`/`createSignal`.
+- **All three detection paths are now binding-based, not name-based** (the point of this ADR, now
+  applied uniformly): the callee (`resolveSolidCallee`), the component **type annotation**
+  (`typeNameBindsToSolid`, see [ADR-0002](./0002-sound-component-detection.md)), and **component
+  usage** (`getInFileComponentVariables` resolves each `<C/>` tag to the variable it references and
+  skips host elements / member-tag roots, so a local helper whose name merely collides with an
+  imported component is never misclassified).

package/docs/adr/0004-correctness-guard-not-migration-tool.md

@@ -0,0 +1,48 @@
+# A Solid 2.0 correctness guard, not a migration tool; refined deletion criterion and fix tiers
+
+**Context.** It was tempting to give `@thomaflette/eslint-plugin-solid-2` a second mandate:
+help people port 1.x→2.0 with rules that flag renamed/moved/removed APIs
+(`solid-js/store → solid-js`, `createResource`, `Index`, `classList`, …). We
+considered a separate `migration` config of such codemod rules. On reflection we
+rejected it: the plugin's job is to **stop people writing incorrect Solid 2.0
+code**, not to narrate what changed since 1.x. "This import moved" / "this API
+was renamed" is historical nagging, and `tsc` already errors when a removed
+symbol doesn't exist. A migration codemod is a separate, one-time tool, not a
+linter's standing job.
+
+Two refinements surfaced while reasoning this through and _do_ survive, because
+they govern the correctness rules we keep.
+
+**Decision.**
+
+1. **No migration config.** The plugin only detects code that is _wrong in 2.0_
+   — regardless of whether the author is migrating or writing fresh. It never
+   reports that an API moved or was renamed.
+
+2. **Deletion criterion.** A rule is deleted when `tsc` already reports the
+   same problem. An autofix does not justify duplicate diagnostics, especially
+   when the fix can fail for unions or otherwise change valid code.
+
+3. **Three fix tiers** — zero-FP extends to "zero-corrupting-autofix":
+   - **Safe autofix** (`meta.fixable`, applied by `--fix`) — only for rewrites
+     that cannot change behavior (for example ternary→`<Show>`).
+   - **Suggestion** (`meta.hasSuggestions`) — a concrete rewrite that _might_
+     change behavior; offered one-click in the editor, reviewed per occurrence,
+     never run by `--fix`. Home for `&&`→`<Show>`.
+   - **Report-only** — when no single mechanical rewrite exists.
+
+**Correctness rules added/affirmed under this scope:**
+
+- `prefer-for` remains essential idiomatic-Solid guidance, but is enabled only
+  with type information so Array#map is proven before a report.
+- `prefer-show` `&&` case: report-only or suggestion, never a safe autofix —
+  `cond && <X/>` renders falsy-but-renderable values (`0`, `NaN`) that
+  `<Show>` would drop, so a mechanical rewrite changes behavior.
+
+## Consequences
+
+- `recommended` keeps its trust property: a small, zero-FP correctness surface.
+- Porting help is explicitly out of scope — point migrators at a codemod, not
+  this plugin.
+- See [ADR-0005](./0005-recommended-type-checked-config.md) for how the
+  type-aware correctness rules are exposed.

package/docs/adr/0005-recommended-type-checked-config.md

@@ -0,0 +1,27 @@
+# Expose type-aware correctness rules via a `recommendedTypeChecked` config
+
+**Context.** Per ADR-0002, the highest-value detection (cross-file component
+detection, nominal accessor reads, and sound Array#map identification) needs the type-checker,
+but type info is currently reachable only through a per-rule `typescriptEnabled`
+flag that most users will never discover. Meanwhile every default rule is
+AST-only so the ruleset also runs on oxlint (which has no type-checker).
+
+**Decision.** Keep `recommended` exactly as-is — AST-only, zero-FP, oxlint-
+portable — and add a second config **`recommendedTypeChecked`** that turns on the
+type-aware paths in one line, mirroring typescript-eslint's own
+`recommended` / `recommendedTypeChecked` naming that users already know. The
+per-rule `typescriptEnabled` option remains the underlying mechanism; the config
+is just the discoverable door. The type-aware paths stay **purely additive**
+(ADR-0002) — they find more, never flip a verdict on correct code — so there is
+no corrective variance between the two configs.
+
+## Consequences
+
+- oxlint users and the speed-conscious stay on `recommended`; the majority who
+  run `tsc` + typescript-eslint flip to `recommendedTypeChecked` and get
+  cross-file component detection, nominal accessor detection, re-exported Solid API/control-flow
+  recognition, and sound `prefer-for` coverage without hunting per-rule flags.
+- `prefer-for` is enabled only in `recommendedTypeChecked`: syntax alone cannot
+  distinguish Array#map from an unrelated collection method without false positives.
+- The type-aware paths of `no-leaf-owner-operations`, `no-stale-props-alias`, and
+  `no-untracked-read-in-effect-apply` are enabled by the config as additive coverage.

package/docs/adr/0006-merge-leaf-owner-rules.md

@@ -0,0 +1,42 @@
+# Merge the forbidden-scope rules into one `no-leaf-owner-operations` rule
+
+**Context.** `no-cleanup-in-forbidden-scope`, `no-flush-in-forbidden-scope`, and
+`no-primitives-in-forbidden-scope` were three ~95%-identical files: same
+leaf-owner detection (`createTrackedEffect`/`onSettled`), same enter/exit stack,
+same binding check — differing only in the matched name-set and the message.
+All three are facets of **one** runtime constraint: a leaf owner cannot own or
+schedule. There is no sensible config that forbids `flush` in a leaf owner but
+allows `onCleanup` — they are invalid for the identical reason. (ESLint
+traverses each file once and fans out to all rules, so three rules bought no
+extra cost to remove — this is about code shape and API surface, not perf.)
+
+**Decision.** Merge the three into a single rule `no-leaf-owner-operations` with
+one `messageId` per violation kind (so the distinct remediation messages
+survive) and one doc page explaining leaf owners. Acceptable now because the
+plugin is pre-adoption (ADR-0001), so the breaking rename of three rule IDs
+costs effectively nothing. Apply the same treatment to the parallel pair
+`no-signal-in-effect-apply` + `no-store-proxy-in-effect-apply`, merged into
+`no-untracked-read-in-effect-apply` (both are "untracked read in the apply
+phase" — one concept, one rule, with `signalRead`/`storeProxyRead` messageIds).
+The two detection algorithms differ, so they are preserved intact inside the one
+rule rather than rewritten; the merge unifies the rule ID, doc, and config entry.
+
+## Consequences
+
+- Three rule IDs disappear from `recommended` and any disable comments — a
+  breaking change, hence done before adoption rather than after.
+- Do **not** re-split into per-operation rules: the granularity buys nothing
+  (the operations are never independently desirable) and reintroduces the
+  duplication this removes.
+- **Correction (was inaccurate):** an earlier draft of this ADR claimed "the
+  shared leaf-owner/scope-stack machinery lives in `solid-rule-utils.ts`." It
+  does not. Solid binding resolution is now shared by `analysis/solid-bindings.ts`, while
+  computation callback classification is shared by `analysis/computation-roles.ts`. The
+  **scope-tracking state itself is per-rule and
+  intentionally different**: `no-leaf-owner-operations` keeps a `forbiddenStack`
+  (it must know nesting for any descendant call), while
+  `no-untracked-read-in-effect-apply` keeps an `applyCallbacks` set of
+  pre-registered callbacks (it only queries known apply functions). A shared
+  `reactiveScopeTracker` seam was considered (the two rules are two adapters, so
+  the seam is real) but deferred: the two query shapes differ enough that a
+  unifying interface risks leaking. Revisit only if a third scope-kind appears.

package/docs/adr/0007-typescript-audience.md

@@ -0,0 +1,35 @@
+# The target audience runs TypeScript
+
+**Context.** The "No value in a TypeScript codebase" deletion criterion
+([ADR-0001](./0001-only-false-positive-free-rules.md)) removes a rule when `tsc`
+already flags the same problem and the rule adds no autofix or migration
+guidance. Six rules were deleted on that basis: `jsx-no-undef`, `jsx-uses-vars`,
+`no-react-deps`, `no-invalid-cleanup-return`, `no-array-handlers`, and
+`no-unknown-namespaces`. (Confirmed afresh for `no-invalid-cleanup-return`: tsc
+rejects a non-function literal cleanup return under both plausible Solid typings
+`void | CleanupFn` and `CleanupFn | undefined` — the void-return-bivariance
+exception applies only to a _bare_ `void` target, never a union, so the rule was
+genuinely redundant.)
+
+That criterion silently assumes the user runs `tsc`. But the lean `recommended`
+config is deliberately AST-only and oxlint-compatible, and AST-only/oxlint is
+exactly the toolchain a plain-JavaScript Solid project would use — for which
+`tsc` flags nothing and all six deleted rules would regain real, zero-FP value.
+The assumption needed to be made explicit and chosen, not left implicit.
+
+**Decision.** The target audience is **TypeScript Solid 2.0 codebases**. A
+pure-JavaScript Solid project with no `tsc` in the loop is **out of scope**. The
+AST-only nature of `recommended` is about ESLint/oxlint engine compatibility and
+speed only — it does **not** imply we serve a JS-only audience, and it does not
+re-open the six tsc-subsumed deletions.
+
+## Consequences
+
+- The six tsc-subsumed deletions stand on the stated assumption. Do not resurrect
+  them to serve JS users; that slice is explicitly unsupported.
+- Solid 2.0 adoption is overwhelmingly TypeScript (the 2.0 reactivity/types story
+  assumes it), so this matches the real audience rather than narrowing it.
+- If a JS audience ever becomes a goal, that is a deliberate scope expansion that
+  reopens this ADR and the six deletions together — not an incremental tweak.
+- `typescript` stays a peer dependency (already required by the opt-in type-aware
+  paths, see [ADR-0002](./0002-sound-component-detection.md)).

package/docs/components-return-once.md

@@ -0,0 +1,89 @@
+# `solid/components-return-once`
+
+Keep component JSX returns in one stable place.
+
+Solid components run once. If a component returns different JSX trees from separate `return` sites, or returns top-level JSX conditionals directly, and the decision is **reactive**, that control flow is no longer modeled inside Solid's reactive graph — it is evaluated a single time and goes stale. Keep the branching inside JSX with `<Show />`, `<Switch />`, fragments, or nested render helpers.
+
+A return decided by a **static** guard is fine: `if (isServer) return <noscript />;` or `import.meta.env.DEV` can never change after mount, so a one-time decision is exactly right. The rule therefore reports a conditional or early return only when its guard provably performs a reactive read: a `props` member access, a locally-declared signal/memo accessor call, a store read, or a `const` derived from one of those. Guards it cannot prove reactive (a helper call, a context read, an accessor imported from another file) are not reported — a tolerated false negative; the runtime's `STRICT_READ_UNTRACKED` still covers executed paths.
+
+## Bad
+
+```tsx
+function Component(props) {
+  const [loading] = createSignal(true);
+  if (loading()) {
+    return <Spinner />;
+  }
+
+  return <Content />;
+}
+```
+
+```tsx
+function Component(props) {
+  return props.ready ? <Content /> : <Fallback />;
+}
+```
+
+```tsx
+function Component(props) {
+  return props.ready && <Content />;
+}
+```
+
+## Good
+
+```tsx
+function Component() {
+  return (
+    <Show when={loading()} fallback={<Content />}>
+      <Spinner />
+    </Show>
+  );
+}
+```
+
+```tsx
+function Component() {
+  return (
+    <Show when={ready()} fallback={<Fallback />}>
+      <Content />
+    </Show>
+  );
+}
+```
+
+```tsx
+function Component() {
+  const renderBody = () => {
+    if (ready()) return <Content />;
+    return <Fallback />;
+  };
+
+  return <section>{renderBody()}</section>;
+}
+```
+
+```tsx
+// Static guards are allowed — the decision cannot change after the single run.
+function Page() {
+  if (isServer) return <noscript />;
+  return <div />;
+}
+```
+
+## Notes
+
+- Early component returns are reported (when reactively guarded), but not autofixed.
+- Final ternary returns can often be autofixed to `<Show />` or `<Switch />`.
+- Final `&&` returns are reported but not autofixed because `0 && <X />` and `<Show when={0}>` are not equivalent.
+
+## Options
+
+### `typescriptEnabled` (default `false`)
+
+By default a function is recognised as a component only when it is annotated `Component`/`VoidComponent`/`ParentComponent`/`FlowComponent` or used as `<C/>` in the same file — so a bare, unannotated component used only in another file is not checked. Set `typescriptEnabled: true` to also detect components by their cross-file JSX usage via the TypeScript type-checker. This requires ESLint type information and is slower.
+
+```json
+{ "rules": { "solid/components-return-once": ["warn", { "typescriptEnabled": true }] } }
+```

package/docs/dev-diagnostic-coverage.md

@@ -0,0 +1,29 @@
+# Solid 2 dev-diagnostic coverage
+
+The plugin complements Solid's
+[dev-mode diagnostics](https://github.com/solidjs/solid/blob/next/documentation/solid-2.0/08-dev-diagnostics.md).
+It reports a diagnostic statically only when the source proves the invalid runtime context. Dynamic
+ownership, pending state, disposal state, and scheduler behavior remain with the runtime.
+
+| Solid diagnostic                 | Static coverage                                                                                  | Rule or owner                                                                 |
+| -------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| `REACTIVE_WRITE_IN_OWNED_SCOPE`  | Strong, sound subset                                                                             | `no-owned-scope-writes`                                                       |
+| `PENDING_ASYNC_UNTRACKED_READ`   | Partial; catches provable untracked reads, regardless of pending state                           | `no-stale-props-alias`, `no-destructure`, `no-untracked-read-in-effect-apply` |
+| `ASYNC_OUTSIDE_LOADING_BOUNDARY` | Runtime only; loading ancestry and render timing are dynamic                                     | Solid runtime                                                                 |
+| `CLEANUP_IN_FORBIDDEN_SCOPE`     | Strong                                                                                           | `no-leaf-owner-operations`                                                    |
+| `SETTLED_CLEANUP_UNOWNED`        | Runtime only; ownership at execution determines whether cleanup is honored                       | Solid runtime                                                                 |
+| `PRIMITIVE_IN_FORBIDDEN_SCOPE`   | Strong for owner-creating primitives; plain value signals/stores follow current runtime behavior | `no-leaf-owner-operations`                                                    |
+| Invalid cleanup return           | Type-level cases are intentionally delegated                                                     | TypeScript and Solid runtime                                                  |
+| `flush()` in forbidden scope     | Strong                                                                                           | `no-leaf-owner-operations`                                                    |
+| Potential infinite loop          | Runtime only; depends on executed graph behavior                                                 | Solid runtime                                                                 |
+| `STRICT_READ_UNTRACKED`          | Strong, sound subset of binding-proven reads                                                     | `no-stale-props-alias`, `no-destructure`, `no-untracked-read-in-effect-apply` |
+| `PENDING_ASYNC_FORBIDDEN_SCOPE`  | Runtime only; the source must actually be pending when read                                      | Solid runtime                                                                 |
+| `NO_OWNER_EFFECT`                | Runtime only; the active owner is execution-context state                                        | Solid runtime                                                                 |
+| `NO_OWNER_CLEANUP`               | Runtime only; the active owner is execution-context state                                        | Solid runtime                                                                 |
+| `NO_OWNER_BOUNDARY`              | Runtime only; the active owner is execution-context state                                        | Solid runtime                                                                 |
+| `RUN_WITH_DISPOSED_OWNER`        | Runtime only; disposal is dynamic                                                                | Solid runtime                                                                 |
+
+Some plugin rules have no corresponding runtime diagnostic. For example,
+`no-reactive-read-after-await` catches dependency loss that native async continuation semantics make
+indistinguishable from an intentional untracked read at runtime. The control-flow and JSX rules
+likewise protect static structure or style rather than mirroring a dev diagnostic.

package/docs/jsx-no-duplicate-props.md

@@ -0,0 +1,34 @@
+# `solid/jsx-no-duplicate-props`
+
+Disallow competing JSX content sources.
+
+TypeScript already reports repeated JSX attributes, so this rule focuses only on Solid/DOM content
+semantics that the type system does not express: `children`, meaningful JSX children, `innerHTML`,
+and `textContent` cannot define the same host element at the same time.
+
+## Bad
+
+```tsx
+<div children={<span />}>
+  <span />
+</div>
+```
+
+```tsx
+<div innerHTML="<p>Hello</p>" textContent="Hello" />
+```
+
+## Good
+
+```tsx
+<div>
+  <span />
+</div>
+```
+
+```tsx
+<div innerHTML={html}>{/* comments and formatting whitespace are not content */}</div>
+```
+
+On custom components these names are author-defined props, so the host-element conflict checks do
+not apply.

package/docs/no-destructure.md

@@ -0,0 +1,92 @@
+# `solid/no-destructure`
+
+Disallow destructuring component props.
+
+In Solid 2, destructuring props performs top-level untracked reads. That breaks reactivity in the same way as assigning `const title = props.title` in a component body.
+
+## Bad
+
+```tsx
+function Component({ title }) {
+  return <h1>{title}</h1>;
+}
+```
+
+```tsx
+function Component({ title: heading }) {
+  return <h1>{heading}</h1>;
+}
+```
+
+```tsx
+function Component({ title = "Untitled" }) {
+  return <h1>{title}</h1>;
+}
+```
+
+```tsx
+function Component({ title, ...rest }) {
+  return <Card {...rest}>{title}</Card>;
+}
+```
+
+```tsx
+// destructuring the props object in the body is the same untracked read
+function Component(props) {
+  const { title } = props;
+  return <h1>{title}</h1>;
+}
+```
+
+## Good
+
+```tsx
+function Component(props) {
+  return <h1>{props.title}</h1>;
+}
+```
+
+```tsx
+function Component(_props) {
+  const props = merge({ title: "Untitled" }, _props);
+  return <h1>{props.title}</h1>;
+}
+```
+
+```tsx
+function Component(props) {
+  const rest = omit(props, "title");
+  return <Card {...rest}>{props.title}</Card>;
+}
+```
+
+```tsx
+function Component(props: Props) {
+  return <div p1={props.prop1} p2={props.prop2} />;
+}
+```
+
+## Notes
+
+- Simple destructures autofix directly to `props.foo` reads.
+- Helper-based fixes may rewrite to `merge(...)` and `omit(...)`; the fix also adds the
+  `solid-js` import for them when it is missing, so the fixed code always compiles.
+- If `merge` or `omit` is already used for something else in the file, the rule stays report-only for that case.
+- **The autofix changes observable behavior — deliberately.** The flagged code freezes prop values
+  at setup (the bug); the rewrite makes every read live. If a value was _intentionally_ frozen,
+  wrap it in `untrack(() => props.x)` instead of destructuring — that form is not reported. This is
+  a knowing exception to the "safe autofixes cannot change behavior" tier: the tier exists to
+  protect _correct_ code from corruption, and code flagged by this rule is incorrect by the
+  runtime's own `STRICT_READ_UNTRACKED` contract.
+- Arrow-body helper cases like `({ a = 5 }) => <div a={a} />` are reported but not autofixed.
+- Destructuring the props object in the body (`const { a } = props`) is also reported (report-only, no autofix). Only destructures of the component's first parameter are flagged — destructuring an arbitrary object is fine.
+
+## Options
+
+### `typescriptEnabled` (default `false`)
+
+A function is recognised as a component by annotation (`Component`/…) or in-file `<C/>` usage by default. Set `typescriptEnabled: true` to also detect components by their cross-file JSX usage via the TypeScript type-checker (slower; requires ESLint type information).
+
+```json
+{ "rules": { "solid/no-destructure": ["warn", { "typescriptEnabled": true }] } }
+```