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

package/docs/no-owned-scope-writes.md

@@ -0,0 +1,117 @@
+# `solid/no-owned-scope-writes`
+
+Disallow writing to signals/stores or calling actions inside component bodies and reactive compute
+scopes.
+
+This matches Solid 2's `SIGNAL_WRITE_IN_OWNED_SCOPE` behavior. In these places, derive values instead of writing state back into the graph.
+It also matches beta.17's `ACTION_CALLED_IN_OWNED_SCOPE` error: actions belong at imperative
+boundaries such as event handlers.
+
+## Bad
+
+```ts
+createMemo(() => setCount(count() + 1));
+```
+
+```ts
+createMemo(() => refresh());
+```
+
+```ts
+createEffect(
+  () => {
+    setCount(count() + 1);
+    return count();
+  },
+  (value) => console.log(value),
+);
+```
+
+```tsx
+function Component() {
+  const [count, setCount] = createSignal(0);
+  setCount(1);
+  return <div>{count()}</div>;
+}
+```
+
+```ts
+const save = action(function* () {
+  yield api.save();
+});
+createMemo(() => save());
+```
+
+```tsx
+function Component() {
+  const [state, setState] = createStore({ count: 0 });
+  setState((s) => {
+    s.count += 1;
+  });
+  return <div>{state.count}</div>;
+}
+```
+
+## Good
+
+```ts
+const doubled = createMemo(() => count() * 2);
+```
+
+```ts
+createEffect(
+  () => count(),
+  (value) => {
+    setOther(value);
+  },
+);
+```
+
+```tsx
+function Component() {
+  const [count, setCount] = createSignal(0);
+  return <button onClick={() => setCount((c) => c + 1)}>Increment</button>;
+}
+```
+
+```tsx
+function Component() {
+  let button: HTMLButtonElement | undefined;
+  const [node, setNode] = createSignal<HTMLButtonElement | undefined>(undefined, {
+    ownedWrite: true,
+  });
+
+  createRenderEffect(() => {
+    setNode(button);
+  });
+
+  return <button ref={button}>{node() ? "Ready" : "Loading"}</button>;
+}
+```
+
+## Notes
+
+- Component bodies count as owned scopes.
+- The compute phase of effects, memos, projections, and derived signal/store factories counts as
+  an owned scope. The apply phase (second argument) of `createEffect`/`createRenderEffect` does not.
+- The 1.x single-callback form `createEffect(() => { ... })` is already deprecated in Solid 2 and is not flagged by this rule — the deprecation marker on the type is the relevant signal there.
+- `ownedWrite: true` is respected for `createSignal`, including aliased imports.
+- Actions created with `action(...)`, their `const` aliases, and immediately-invoked action
+  factories are detected.
+- `refresh()` is a write-like graph operation and is rejected in the same owned scopes.
+- Direct, aliased, and namespace `solid-js` imports are resolved by binding rather than by their
+  local spelling.
+
+## Options
+
+### `typescriptEnabled` (default `false`)
+
+Component bodies are recognised by annotation (`Component`/…) or in-file `<C/>` usage by default.
+Set `typescriptEnabled: true` to also detect components by their cross-file JSX usage and recognize
+Solid factories, setters, actions, and `refresh` through re-export chains. Direct, aliased, and
+namespace `solid-js` imports remain AST-only. The option is slower and requires ESLint type
+information.
+
+```json
+{ "rules": { "solid/no-owned-scope-writes": ["error", { "typescriptEnabled": true }] } }
+```

package/docs/no-reactive-read-after-await.md

@@ -0,0 +1,87 @@
+# `solid/no-reactive-read-after-await`
+
+Disallow reading a signal/memo accessor **after an `await`** inside an async reactive computation, where it is no longer tracked as a dependency.
+
+Solid registers dependencies **synchronously**: when a computation runs, tracking is enabled, the compute function is called, and tracking is torn down the instant it returns. For an `async` compute function, that return happens at the **first `await`** — it hands back a promise and the tracking context is gone. Any accessor read in the continuation after the await runs untracked: it still returns a value, so nothing breaks loudly, but it never records a dependency, so the computation **won't re-run when that signal changes**.
+
+Solid 2.0 has no dedicated `createAsync` primitive — the async primitive is an `async` compute function passed to `createMemo`, `createEffect`, `createRenderEffect`, or `createProjection`. This rule checks the compute callback (the first argument) of each.
+
+## Bad
+
+```ts
+const [count, setCount] = createSignal(0);
+
+const data = createMemo(async () => {
+  const res = await fetch(`/api?since=${lastSync}`);
+  return (await res.json()).filter((x) => x.id > count()); // ❌ count() after await — not tracked
+});
+```
+
+```ts
+createEffect(async () => {
+  await ready();
+  console.log(count()); // ❌ count() after await — the effect won't re-run when count changes
+});
+```
+
+## Good
+
+Read what you need **before** the first `await`, then use the captured value:
+
+```ts
+const [count, setCount] = createSignal(0);
+
+const data = createMemo(async () => {
+  const min = count(); // ✅ tracked
+  const res = await fetch(`/api?since=${lastSync}`);
+  return (await res.json()).filter((x) => x.id > min);
+});
+```
+
+If reading after the await is genuinely intentional (you do **not** want it to be a dependency), make that explicit with `untrack()`:
+
+```ts
+createMemo(async () => {
+  await ready();
+  return untrack(() => count()); // ✅ explicitly untracked
+});
+```
+
+## Why not a runtime warning?
+
+In the browser there is no reliable way to detect this at runtime: once an async function yields at `await`, native `await` resumes through the engine's internal machinery (not `Promise.prototype.then`), and there is no `AsyncContext` yet — so a post-await read is indistinguishable from any other untracked read (an event handler, `untrack`). Static analysis sees the source directly, which is why this is a lint rule.
+
+## Type-aware mode (additive)
+
+By default the rule is **AST-only**: it tracks accessors that come from a recognizable factory call
+in the same file (`createSignal`/`createMemo`/`createOptimistic`, plus `const` aliases). Async compute
+callbacks are recognized for effects, memos, projections, and derived signal/store factories,
+including direct, aliased, and namespace `solid-js` imports. With type information enabled (the
+`recommendedTypeChecked` config, or `{ typescriptEnabled: true }`), it additionally recognizes
+accessors **by type** — a callee whose type is Solid's `Accessor`, and factory calls resolved by
+symbol. This catches cases the AST path can't see:
+
+```ts
+// member accessor — only caught with type info
+function Row(props: { value: Accessor<number> }) {
+  return createMemo(async () => {
+    await fetch("/x");
+    return props.value(); // ❌ flagged under recommendedTypeChecked
+  });
+}
+```
+
+This is **purely additive** (ADR-0005): it never changes a verdict on code the AST path already handles, and it never reports more loosely — the type must be solid's `Accessor` (originating from `solid-js`/`@solidjs/signals`), so a plain `() => T` or a same-named non-solid `Accessor` is left alone. Both modes have **zero false positives**; type info only reduces false negatives.
+
+## Limitations
+
+The "after an await" check is intentionally **sound over complete** — it never reports correct code, at the cost of missing some genuinely-buggy shapes (false negatives):
+
+- An `await` reached only on one branch of an `if`/`switch`, or only on later iterations of a loop, is not treated as guaranteed, so a read after it is not flagged.
+- Reads inside a nested helper closure are not analyzed — the rule can't know when the helper is invoked.
+- Only signal/memo **accessors** are tracked. A store proxy read after an await is not covered (`createProjection` returns a store, so its _result_ isn't checked — but its async compute body is).
+
+## Notes
+
+- Accessors aliased through a plain `const` (`const c = count`) are still caught; `untrack(() => count())` is allowed.
+- The async **apply** callback of an effect (the second argument) is not checked here — its untracked reads are reported by [`no-untracked-read-in-effect-apply`](./no-untracked-read-in-effect-apply.md).

package/docs/no-stale-props-alias.md

@@ -0,0 +1,157 @@
+# `solid/no-stale-props-alias`
+
+Disallow provable untracked reactive reads in component bodies and Solid control-flow function
+children. This includes stale props aliases, direct props reads, local signal/memo accessor calls,
+store reads, and accessor parameters supplied by control flow.
+
+Solid 2 tracks prop reads when the property is read in JSX or another tracked scope. A top-level
+alias reads once during component setup, outside tracking, so the alias can become stale.
+
+The same execution rule applies to direct reads such as `console.log(props.name)` and to the
+structure-building bodies of `For`, `Show`, and `Match` function children. JSX expressions,
+reactive computations, nested event/helper closures, and explicit `untrack` calls are excluded.
+
+## Invalid
+
+```tsx
+const Card: Component = (props) => {
+  const name = props.name;
+  return <h1>{name}</h1>;
+};
+```
+
+```tsx
+const Counter: Component = () => {
+  const [count] = createSignal(0);
+  console.log(count()); // direct component-body accessor read
+  return <span>{count()}</span>;
+};
+```
+
+```tsx
+<Show when={user()}>
+  {(user) => {
+    const name = user().name; // function-child accessor read outside JSX tracking
+    return <span>{name}</span>;
+  }}
+</Show>
+```
+
+```tsx
+const Card: Component = (props) => {
+  const userName = props.user.name;
+  return <h1>{userName}</h1>;
+};
+```
+
+```tsx
+const Card: Component = (props) => {
+  const name = props.name;
+  validate(name);
+  return <h1>{props.name}</h1>;
+};
+```
+
+```tsx
+const Card: Component = (props) => {
+  const name = props.name ?? "Anonymous";
+  return <h1>{name}</h1>;
+};
+```
+
+```tsx
+const Card: Component = (props) => {
+  const label = formatName(props.name);
+  return <h1>{label}</h1>;
+};
+```
+
+```tsx
+const Card: Component = (props) => {
+  const alias = props;
+  const name = alias.name; // the read through the alias is reported, not the alias itself
+  return <h1>{name}</h1>;
+};
+```
+
+```tsx
+const Card: Component = (props) => {
+  const copy = { ...props }; // spreading reads every property eagerly
+  return <h1>{copy.name}</h1>;
+};
+```
+
+```tsx
+const Card: Component = (props) => {
+  let name;
+  name = props.name;
+  return <h1>{name}</h1>;
+};
+```
+
+## Valid
+
+```tsx
+const Card: Component = (props) => {
+  return <h1>{props.name}</h1>;
+};
+```
+
+```tsx
+const Card: Component = (props) => {
+  const name = untrack(() => props.name);
+  return <h1>{name}</h1>;
+};
+```
+
+```tsx
+// The canonical defaults / rest patterns: merge and omit return reactive proxies, so passing the
+// props object to them is a passthrough, not a read. Their results are tracked as props-like, so
+// a later top-level read from them is still reported.
+const Card: Component = (_props) => {
+  const props = merge({ size: "md" }, _props);
+  const rest = omit(props, "class");
+  return <div {...rest}>{props.size}</div>;
+};
+```
+
+```tsx
+// A whole-object alias performs no read; property reads through it in JSX stay reactive.
+const Card: Component = (props) => {
+  const alias = props;
+  return <h1>{alias.name}</h1>;
+};
+```
+
+## Options
+
+### `typescriptEnabled` (default `false`)
+
+Component bodies are recognised 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, recognize nominal Solid accessors, and follow re-exported Solid
+control-flow components (slower; requires ESLint type information).
+
+```json
+{ "rules": { "solid/no-stale-props-alias": ["warn", { "typescriptEnabled": true }] } }
+```
+
+## Notes
+
+- A props report requires an _eager read_: a member access rooted at the props object
+  (`props.name`, `props[key]`, reads through a stable alias) or a spread of it (`{ ...props }`). A
+  bare `props` reference is never a read — passing the object to `merge`/`omit` or another helper
+  keeps reactivity intact. A helper that reads eagerly inside (`createForm(props)`) is a tolerated
+  false negative because its behavior is undecidable from the call site.
+- Direct reads in nested functions and explicit `untrack(...)` calls are not reported.
+- Reassignable props aliases are not followed.
+- Destructured props are handled by `solid/no-destructure`.
+- Function children of binding-proven Solid `For`, `Repeat`, `Show`, and `Match` elements are also
+  checked, including `children={fn}`, immutable function aliases, namespace imports, and nested
+  Solid control flow. JSX reads and explicit `untrack(...)` reads inside those callbacks remain
+  valid because they execute in tracked contexts.
+- Callback parameters follow Solid 2's mode-specific semantics: default `For` indexes,
+  `keyed={false}` items, custom-key `For` items/indexes, and non-keyed `Show`/`Match` values are
+  accessors. Default `For` items, `Repeat` indexes, and keyed `Show`/`Match` values are raw.
+- Type-aware mode additionally recognizes canonically typed Solid control-flow components that
+  arrive through re-export chains.

package/docs/no-untracked-read-in-effect-apply.md

@@ -0,0 +1,97 @@
+# `solid/no-untracked-read-in-effect-apply`
+
+Disallow reading reactive state in a `createEffect` / `createRenderEffect` **apply** callback, which runs untracked.
+
+An effect has two phases: **compute** (tracked — reads here record dependencies) and **apply** (untracked — the side effect). Reading reactive state in the apply phase triggers `STRICT_READ_UNTRACKED` in dev and won't re-run the effect. There are two ways to trip this, both reported by this rule:
+
+1. **Calling a signal/memo accessor** directly in the apply callback.
+2. **Reading a store proxy** that was passed through the compute return into the apply callback.
+
+The fix for both: read what you need in the **compute** phase and use the passed value (or `untrack()` for signals, `deep()` for whole-store snapshots).
+
+## Bad
+
+```ts
+const [count, setCount] = createSignal(0);
+createEffect(
+  () => count(),
+  (value) => {
+    console.log(count());
+  }, // ❌ accessor called in apply
+);
+```
+
+```ts
+const [store] = createStore({ user: { name: "A" } });
+createEffect(
+  () => store.user,
+  (user) => sendAnalytics(user.name), // ❌ store proxy read in apply
+);
+```
+
+## Good
+
+```ts
+createEffect(
+  () => count(),
+  (value) => {
+    console.log(value);
+  }, // ✅ use the passed value
+);
+```
+
+```ts
+createEffect(
+  () => ({ name: store.user.name }), // ✅ extract in compute
+  (value) => sendAnalytics(value.name),
+);
+```
+
+```ts
+createEffect(
+  () => deep(store), // ✅ deep() returns a plain snapshot safe to read in apply
+  (snapshot) => saveToLocalStorage(JSON.stringify(snapshot)),
+);
+```
+
+```ts
+createEffect(
+  () => count(),
+  (value) => {
+    // ✅ the handler runs later, on click — untracked reads are sanctioned there,
+    // and the runtime's STRICT_READ_UNTRACKED does not fire for it either
+    el.addEventListener("click", () => setOpen(!open()));
+  },
+);
+```
+
+## Options
+
+### `typescriptEnabled` (default `false`)
+
+The AST-only path recognises accessors created in the same file. Set `typescriptEnabled: true` to
+also detect imported, parameter, and member accessors whose nominal type originates from Solid.
+Structurally similar plain functions and readonly objects are not treated as accessors or stores.
+
+```json
+{
+  "rules": {
+    "solid/no-untracked-read-in-effect-apply": ["warn", { "typescriptEnabled": true }]
+  }
+}
+```
+
+## Notes
+
+- Only reads that happen **directly** in the apply callback are reported — the read's nearest
+  enclosing function must be the apply callback itself. A read inside a closure created during
+  apply (an event handler, a `setInterval` callback) executes later, outside the apply phase, where
+  untracked reads are legitimate; flagging those was a false positive on sanctioned code. A closure
+  that is _invoked synchronously during apply_ (`arr.forEach(() => count())`) is a tolerated false
+  negative — the runtime diagnostic still covers it on executed paths.
+- The `EffectBundle` form (`{ effect(value) { ... } }`) is checked the same way as a bare apply callback.
+- Accessors aliased through a plain `const` (`const c = count`) are still caught; `untrack(() => count())` is allowed.
+- Store proxy reports require proof: a bare store or a member path known from a literal initializer
+  to be an object/array. Computed paths and non-literal initializer shapes are left alone because
+  they may return primitives.
+- This rule replaces the former `no-signal-in-effect-apply` and `no-store-proxy-in-effect-apply` rules (see [ADR-0006](./adr/0006-merge-leaf-owner-rules.md)).

package/docs/prefer-for.md

@@ -0,0 +1,81 @@
+# `solid/prefer-for`
+
+Prefer Solid's `<For />` component over `Array#map(...)` when rendering JSX lists.
+
+`<For />` matches Solid's list rendering model better than embedding `map(...)` inside JSX. In Solid 2's default `<For />`, the item callback parameter is a raw value (unlike `index`, which is an `Accessor<number>`), so the autofix leaves item reads untouched and only calls the index parameter.
+
+## Bad
+
+```tsx
+<ul>
+  {items.map((item) => (
+    <li>{item.name}</li>
+  ))}
+</ul>
+```
+
+```tsx
+<For each={groups}>{(group) => group.items.map((item) => <Row item={item} />)}</For>
+```
+
+```tsx
+<ol>
+  {props.data.map(({ text }) => (
+    <li>{text}</li>
+  ))}
+</ol>
+```
+
+## Good
+
+```tsx
+<ul>
+  <For each={items}>{(item) => <li>{item.name}</li>}</For>
+</ul>
+```
+
+```tsx
+<ol>
+  {props.data.map((item, i) => (
+    <li>
+      {i}: {item.name}
+    </li>
+  ))}
+</ol>
+// autofixable to (index is an accessor, so it is called):
+<ol>
+  <For each={props.data}>
+    {(item, i) => (
+      <li>
+        {i()}: {item.name}
+      </li>
+    )}
+  </For>
+</ol>
+```
+
+```tsx
+<ol>{props.data.map((value) => value.text)}</ol>
+```
+
+## Notes
+
+- The rule requires TypeScript to prove the receiver is an array. Syntax alone cannot distinguish
+  Array#map from an observable or another collection's `.map` method without false positives.
+- Autofix only applies to arrow callbacks with at most the item and index parameters. Array's third
+  callback argument, normal functions (`arguments`/`this`), destructuring, and rest parameters are
+  reported without a fixer.
+- The rule reports `map(...)` calls that produce JSX inside JSX, including when wrapped in a `{cond && …}` or `{cond ? … : …}` slot (those wrapped forms are reported but not autofixed).
+- Destructured parameters, rest parameters, and other complex callback shapes are reported without a fixer.
+
+## Options
+
+### `typescriptEnabled` (default `false`)
+
+Set `typescriptEnabled: true` to enable the rule. It reports only when the receiver is provably an
+array and skips `Map`, `Set`, observables, `any`, and `unknown`. This is enabled by
+`recommendedTypeChecked`; the AST-only `recommended` config leaves the rule off.
+
+```json
+{ "rules": { "solid/prefer-for": ["warn", { "typescriptEnabled": true }] } }
+```

package/docs/prefer-show.md

@@ -0,0 +1,59 @@
+# `solid/prefer-show`
+
+Prefer Solid's `<Show />` component over JSX `&&` and ternary conditionals when rendering content.
+
+`<Show />` makes conditional rendering explicit and aligns with Solid's control-flow components. Ternary cases can often be autofixed. `&&` cases are only reported because JSX and `<Show when={...}>` differ for falsy non-boolean values.
+
+## Bad
+
+```tsx
+<div>{cond && <span>Content</span>}</div>
+```
+
+```tsx
+<div>{cond ? <span>Content</span> : <span>Fallback</span>}</div>
+```
+
+```tsx
+<For each={items}>{(item) => (item.ready ? <Ready /> : <Pending />)}</For>
+```
+
+## Good
+
+```tsx
+<div>
+  <Show when={cond}>
+    <span>Content</span>
+  </Show>
+</div>
+```
+
+```tsx
+<div>
+  <Show when={cond} fallback={<span>Fallback</span>}>
+    <span>Content</span>
+  </Show>
+</div>
+```
+
+```tsx
+<For each={items}>
+  {(item) => (
+    <Show when={item.ready} fallback={<Pending />}>
+      <Ready />
+    </Show>
+  )}
+</For>
+```
+
+```tsx
+<Show when={cond}>Content</Show>
+```
+
+## Notes
+
+- Only conditionals with a JSX branch are reported; plain value conditionals like `{a ? b : c}` or `{cond && value}` are left alone (rewriting them into `<Show>` would change behavior).
+- Ternary expressions with a JSX branch are autofixable.
+- Render callbacks are inspected whether written with a concise body (`(item) => cond ? <A/> : <B/>`) or a block body (`(item) => { return cond ? <A/> : <B/>; }`).
+- `&&` expressions with JSX on the right are reported and offer the `<Show>` rewrite as an **editor suggestion**, never an autofix. `cond && <X/>` evaluates to the left operand when it is falsy, and Solid renders falsy-but-renderable values (`0`, `NaN`) as text — which `<Show>` would drop. A blanket `--fix` could therefore change behavior, so the rewrite is left for you to apply per occurrence after checking the condition's type.
+- Example: `0 && <X />` renders `0` in JSX, but `<Show when={0}><X /></Show>` renders nothing. (Do **not** "promote" this suggestion to an autofix.)

package/docs/self-closing-comp.md

@@ -0,0 +1,42 @@
+# `solid/self-closing-comp`
+
+Prefer self-closing syntax for empty JSX elements when allowed by the rule options.
+
+This is a formatting/layout rule. It reports empty JSX elements that should be written as self-closing, or self-closing elements that should keep explicit closing tags based on the configured `html` and `component` options.
+
+## Bad
+
+```tsx
+<div></div>
+```
+
+```tsx
+<Button></Button>
+```
+
+## Good
+
+```tsx
+<div />
+```
+
+```tsx
+<Button />
+```
+
+```tsx
+<div> </div>
+```
+
+## Notes
+
+- **Why a stylistic rule lives in a correctness plugin:** this is the one deliberate scope
+  exception. It survives because it is _semantically inert_ (the report and both autofix
+  directions cannot change behavior, so the zero-FP/zero-corrupting-autofix bars are trivially
+  met), no formatter in the toolchain performs this normalization, and it was carried forward from
+  the original `eslint-plugin-solid` where users expect it. It is held to the same bars as every
+  other rule; it just guards style rather than correctness.
+- `component` controls Solid/JSX components: `"all"` or `"none"`.
+- `html` controls DOM elements: `"all"`, `"void"`, or `"none"`.
+- Whitespace-only multiline children are treated as empty and can still be self-closed.
+- Non-breaking spaces and explicit space expressions are treated as real children and are not self-closed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thomaflette/eslint-plugin-solid-2",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Sound ESLint rules for Solid 2 reactivity and idiomatic control flow.",
   "keywords": [
     "eslint",
@@ -21,7 +21,8 @@
     "url": "git+https://github.com/yumemi-thomas/eslint-plugin-solid-2.git"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "main": "./dist/index.cjs",
@@ -38,15 +39,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@typescript-eslint/utils": "^8.59.1"
+    "@typescript-eslint/utils": "^8.63.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "@typescript-eslint/parser": "^8.59.1",
+    "@typescript-eslint/parser": "^8.63.0",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@typescript/native-preview": "7.0.0-dev.20260502.1",
     "bumpp": "^11.0.1",
-    "eslint": "^10.3.0",
+    "eslint": "10.7.0",
     "solid-js": "2.0.0-beta.17",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vite-plus": "^0.1.20"
@@ -60,6 +61,7 @@
   },
   "scripts": {
     "build": "vp pack",
+    "bench": "vp test bench",
     "dev": "vp pack --watch",
     "test": "vp test",
     "check": "vp check"