adamantite 0.42.0 → 0.43.0

package/README.md

@@ -34,6 +34,8 @@ and Sherif so humans and coding agents can use the same project workflow.
   through an interactive or non-interactive initializer.
 - **Setup maintenance**: Assess managed integrations with `doctor`, update managed
   dependencies, and give humans or agents repair instructions.
+- **Custom rules**: Write project-specific Oxlint rules in `.adamantite/rules/`, one rule
+  for each file, and enable all of them with one line.
 - **Workspace checks**: Find unused code with Knip and dependency inconsistencies with
   Sherif.
 - **Agent guidance**: Add a managed Adamantite section to `AGENTS.md`.
@@ -87,8 +89,8 @@ Available setup values:
 
 - Scripts: `check`, `fix`, and `analyze`. In a detected monorepo, `analyze` also installs
   Sherif.
-- Presets: `react`, `react-strict`, `react-doctor`, `nextjs`, `vue`, `jest`, `vitest`,
-  `node`, `strict`, `antislop`, and `shadcn`. `react-doctor` requires `react`.
+- Presets: `react`, `react-strict`, `react-doctor`, `tanstack`, `nextjs`, `vue`, `effect`,
+  `jest`, `vitest`, `node`, `strict`, `antislop`, and `shadcn`. `react-doctor` requires `react`.
 - Editors: `vscode` and `zed`.
 
 Presets and TypeScript require the `check` or `fix` script. Editor extension installation
@@ -214,7 +216,34 @@ adamantite doctor
 ```
 
 `update` exits 0 when dependency updates succeed, even if doctor findings remain. Use
-`adamantite doctor` as the CI gate.
+`adamantite doctor` as the CI gate. After it installs packages, `update` patches Oxlint and TypeScript again for
+[the effect preset](#the-effect-preset).
+
+### `adamantite prepare`
+
+Patch Oxlint and TypeScript for [the effect preset](#the-effect-preset). The `prepare`
+script in `package.json` runs it after each install:
+
+```json
+{ "scripts": { "prepare": "adamantite prepare" } }
+```
+
+Without the effect preset, `prepare` does nothing and exits 0. If the patch fails, `prepare`
+fails, so the install fails.
+
+### `adamantite rule`
+
+Write and inspect [custom rules](#custom-rules):
+
+```sh
+adamantite rule add no-process-env
+adamantite rule add no-window --dir tooling/lint/rules
+adamantite rule ast src/index.ts
+```
+
+`rule add` writes a rule stub to `.adamantite/rules/`, or to the folder that `--dir` names,
+and an `AGENTS.md` with the authoring guidance when the folder has none. `rule ast` prints the
+ESTree-shaped AST that Oxlint rules visit, so you can read node names off real code.
 
 ### Pass arguments to underlying tools
 
@@ -246,16 +275,20 @@ Adamantite publishes configuration that can also be consumed directly:
 | `adamantite/lint/react`        | React, JSX accessibility, and performance.                                                                                                                                                                                                                                             |
 | `adamantite/lint/react-strict` | Opinions for React feature code: no state, effect, or memoization hooks outside hook modules. See [the react-strict preset](#the-react-strict-preset).                                                                                                                                 |
 | `adamantite/lint/react-doctor` | Curated [React Doctor](https://github.com/millionco/react-doctor) rules for React state and effect misuse. See [the react-doctor preset](#the-react-doctor-preset).                                                                                                                    |
+| `adamantite/lint/tanstack`     | Opinions for [TanStack Query](https://tanstack.com/query) with route loaders: queries defined once with `queryOptions()`, and no query data copied into state. See [the tanstack preset](#the-tanstack-preset).                                                                        |
 | `adamantite/lint/nextjs`       | Next.js rules.                                                                                                                                                                                                                                                                         |
 | `adamantite/lint/vue`          | Vue rules.                                                                                                                                                                                                                                                                             |
+| `adamantite/lint/effect`       | Curated [@effect/tsgo](https://github.com/Effect-TS/tsgo) rules for Effect misuse, such as effects that never run and unhandled errors. See [the effect preset](#the-effect-preset).                                                                                                   |
 | `adamantite/lint/node`         | Node.js rules.                                                                                                                                                                                                                                                                         |
 | `adamantite/lint/jest`         | Jest rules.                                                                                                                                                                                                                                                                            |
 | `adamantite/lint/vitest`       | Vitest rules.                                                                                                                                                                                                                                                                          |
 | `adamantite/lint/strict`       | Framework-neutral opinions: no deep or wide destructuring, and no type assertions outside tests. See [the strict preset](#the-strict-preset).                                                                                                                                          |
 | `adamantite/lint/antislop`     | Vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules that reject low-evidence, low-signal patterns. Also turns off `typescript/consistent-indexed-object-style` and `unicorn/no-immediate-mutation` from the core preset, which conflict with these rules.                |
 | `adamantite/lint/shadcn`       | [@shadcn/lint](https://github.com/shadcn-ui/lint) rules for Tailwind v4 design systems: no restyled components, raw colors, arbitrary values, inline styles, unknown classes, or unreadable class expressions. shadcn/ui is not required. See [the shadcn preset](#the-shadcn-preset). |
+| `adamantite/lint/custom`       | A function, `custom()`, that loads the project's own rules from `.adamantite/rules/`. See [custom rules](#custom-rules).                                                                                                                                                               |
+| `adamantite/rules`             | `defineRule` and the rule and AST types for custom rules.                                                                                                                                                                                                                              |
 | `adamantite/format`            | Oxfmt configuration.                                                                                                                                                                                                                                                                   |
-| `adamantite/analyze`           | Knip configuration. The `ignoreDependencies` named export groups suggested ignore lists; `init` sets `ignoreDependencies.monorepo` in a monorepo.                                                                                                                                      |
+| `adamantite/analyze`           | Knip configuration. The `ignoreDependencies` named export groups suggested ignore lists; `init` sets `ignoreDependencies.monorepo` in a monorepo and `ignoreDependencies.effect` with the effect preset.                                                                               |
 | `adamantite/typescript`        | Strict TypeScript configuration for TS 7+.                                                                                                                                                                                                                                             |
 
 When consuming the lint presets directly, hoist the core preset's ignore patterns onto the
@@ -338,6 +371,103 @@ as a hosted product. Read the
 [license](https://www.npmjs.com/package/oxlint-plugin-react-doctor?activeTab=code) before
 you select the preset.
 
+### The tanstack preset
+
+`adamantite/lint/tanstack` holds opinions for TanStack Query (`@tanstack/react-query`) in
+apps that preload queries in route loaders, such as TanStack Router and TanStack Start apps.
+Like `react-strict`, it needs no extra package.
+
+- `adamantite/query-from-loader` reports `useQuery`, `useSuspenseQuery`, `useInfiniteQuery`,
+  and `useSuspenseInfiniteQuery` calls in route files that take a plain options object or a `queryOptions()`
+  call made inside a function. Define each query once with `queryOptions()` at module scope
+  or in an exported factory such as `userQuery(id)`, preload it in the route loader with
+  `queryClient.ensureQueryData()`, and pass the same options to the hook. For the infinite
+  hooks, use `infiniteQueryOptions()` and `queryClient.ensureInfiniteQueryData()`. The rule
+  looks through type-only wrappers such as `as const` and `satisfies`. Then a route with
+  `preload="intent"` renders from the cache without a request waterfall. An object that
+  spreads shared options, such as `{ ...userQuery(id), select }`, stays allowed.
+- `adamantite/no-query-data-in-state` reports `useState` calls whose initial value comes from
+  the data of a query in the same component, such as `useState(query.data)` or
+  `useState(() => data.user)`. The copy stops updating when the query refetches. Read the
+  value from the query result, and keep only the user's edits in state.
+
+A route file is a file that calls a route factory from `@tanstack/react-router`, such as
+`createFileRoute`, `createRootRoute`, or `createRoute`. Only a route has a loader to preload
+the query, so components outside route files can define their queries inline.
+`query-from-loader` checks one file at a time. It cannot prove that a loader preloads the
+options, so it moves queries toward shared definitions but does not guarantee the preload.
+The `react-doctor` preset reports other query misuse, such as refetches from effects and
+mutations that do not invalidate queries. See
+[ADR 0008](docs/adr/0008-tanstack-query-options-from-loaders.md).
+
+### The effect preset
+
+`adamantite/lint/effect` reports misuse of [Effect](https://effect.website), such as an
+effect that is neither yielded nor assigned (`floating-effect`), an unhandled error or
+requirement (`missing-effect-error`, `missing-effect-context`), and a combinator with a
+simpler replacement (`catch-all-to-map-error`). The rules come from
+[@effect/tsgo](https://github.com/Effect-TS/tsgo), the Effect Language Service for
+TypeScript-Go, and need Oxlint's type-aware mode.
+
+The rules are not a JavaScript plugin. They exist only after `effect-tsgo patch --oxlint
+--typescript` replaces the Oxlint, oxlint-tsgolint, and TypeScript binaries in
+`node_modules`. Without the patch, Oxlint stops with `Unknown plugin: 'effecttsgo'`. Each
+install of one of those packages restores the original binaries, so the patch must run again
+after it. Adamantite runs it in these places:
+
+- `adamantite prepare`, which the `prepare` script runs after a bare install, such as
+  `npm install`, `npm ci`, or a fresh clone in CI.
+- `adamantite init` and `adamantite update`, after they install packages. A named install,
+  such as `npm install -D oxlint@1.86.0`, does not run the `prepare` script. If you change one
+  of those versions yourself, doctor reports the version drift, and `adamantite update`
+  installs the pinned version and patches it.
+
+When you select the preset, `adamantite init` does these steps:
+
+- Installs the pinned `@effect/tsgo` and runs the patch.
+- Adds `"prepare": "adamantite prepare"` to `package.json`. If the project already has a
+  `prepare` script, init rewrites it as `adamantite prepare && (<existing>)`. A command such as
+  `cd ..` then cannot move the patch out of the project, and a fallback such as `|| true`
+  cannot hide a failed patch.
+- Adds `{ "name": "@effect/language-service", "diagnostics": false }` to
+  `compilerOptions.plugins` in `tsconfig.json`. Editors that use the workspace TypeScript
+  get Effect quick fixes, refactors, and hovers. Oxlint reports the diagnostics, so the
+  language service does not report them a second time.
+- Sets `ignoreDependencies.effect` in `knip.config.ts`, because no package has the name
+  `@effect/language-service`.
+
+`adamantite doctor` reports each missing part, and `adamantite update` keeps
+`@effect/tsgo` on its pinned version. Each `@effect/tsgo` release supports only some Oxlint,
+oxlint-tsgolint, and TypeScript versions, so Adamantite moves the pins together.
+
+A production-only install, such as `npm ci --omit=dev` or `pnpm install --prod`, still runs
+the `prepare` script, but it does not install Adamantite, so the install fails with
+`adamantite: not found`. Add `--ignore-scripts` to those installs. Nothing in a production
+install needs the patch.
+
+The rules read their options from the tsconfig entry. For example, `unstable-api-usage`
+reports each use of an API marked `@stability unstable`. To allow a module on purpose, list
+it in `allowedUnstableApis`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "diagnostics": false,
+        "allowedUnstableApis": ["effect/cli"],
+      },
+    ],
+  },
+}
+```
+
+The preset enables only rules that report Effect code. It does not ban platform APIs, such
+as `Date.now()` or `process.env`, in code that is not Effect code. Inside Effect code, it
+reports them, because `Clock`, `Random`, and `Config` let tests control them. See
+[ADR 0007](docs/adr/0007-effect-preset-patches-oxlint.md) for the criteria.
+
 ### The strict preset
 
 `adamantite/lint/strict` holds framework-neutral opinions. Use it with any other preset. Like
@@ -395,6 +525,103 @@ another component directory. See the
 [@shadcn/lint documentation](https://github.com/shadcn-ui/lint#settings) for settings,
 contracts, and custom messages.
 
+## Custom rules
+
+Custom rules are Oxlint rules that your project writes and owns. Each file in
+`.adamantite/rules/` is one rule. `custom()` from `adamantite/lint/custom` loads the folder
+and enables each rule as `error` under the `project` plugin, so `no-process-env.ts` becomes
+`project/no-process-env`. Add a file to add a rule, and delete the file to remove it. A file
+that starts with `_`, such as `_helpers.ts`, is a helper, not a rule.
+
+```text
+.adamantite/rules/
+  no-process-env.ts      # enabled as project/no-process-env
+  _helpers.ts            # skipped
+```
+
+```ts
+// .adamantite/rules/no-process-env.ts
+import { defineRule } from "adamantite/rules"
+
+export default defineRule({
+  meta: {
+    messages: { unexpected: "Read configuration through the config module." },
+    type: "problem",
+  },
+  createOnce(context) {
+    return {
+      MemberExpression(node) {
+        if (node.object.type === "Identifier" && node.object.name === "process") {
+          context.report({ messageId: "unexpected", node })
+        }
+      },
+    }
+  },
+})
+```
+
+```ts
+// oxlint.config.ts
+import { defineConfig } from "oxlint"
+import core from "adamantite/lint"
+import custom from "adamantite/lint/custom"
+
+export default defineConfig({
+  extends: [core, custom()],
+  ignorePatterns: core.ignorePatterns,
+})
+```
+
+`custom()` returns an empty config when the folder does not exist, so `adamantite init` adds
+it to every generated config. It takes these options:
+
+- `dir`: the rules folder. A relative path resolves from the file that calls `custom()`, not
+  from the working directory. Default: `.adamantite/rules`.
+- `name`: the plugin name that prefixes each rule. Default: `project`.
+- `rules`: severity or options for a rule, by rule name without the prefix, such as
+  `{ "no-process-env": "warn" }`.
+
+Rule files run with Node.js type stripping, so use erasable TypeScript only: no `enum`,
+`namespace` with values, or parameter properties. Rules get no type information. A rule
+that throws prints an error for each file, and the lint run still exits 0. Adamantite owns
+the wiring and the authoring guidance; your project owns the correctness and the tests of
+its rules. To test a rule, use `RuleTester` from `oxlint/plugins-dev`. `adamantite rule add`
+writes the full authoring guidance to `.adamantite/rules/AGENTS.md`.
+
+`adamantite doctor` reports a rule file that cannot load, with the reason, a rules folder
+that no `custom()` call loads, and two rules folders that use the same plugin name.
+
+### Custom rules in a monorepo
+
+Oxlint rejects two plugins with the same name in one run, so give each rules folder its own
+name. A nested Oxlint config replaces the root config, so a workspace package that needs the
+root rules extends the root config:
+
+```ts
+// packages/web/oxlint.config.ts
+import { defineConfig } from "oxlint"
+import custom from "adamantite/lint/custom"
+import root from "../../oxlint.config.ts"
+
+export default defineConfig({ extends: [root, custom({ name: "web" })] })
+```
+
+To share one rules folder across the workspace, keep it in a tooling package and call
+`custom()` there. The relative `dir` resolves from the tooling package, so every config that
+extends it loads the same rules:
+
+```ts
+// tooling/lint/index.ts
+import custom from "adamantite/lint/custom"
+
+export default custom({ dir: "rules", name: "acme" })
+```
+
+Run `adamantite rule add <name> --dir tooling/lint/rules` to add a rule to that folder.
+Doctor starts from the Oxlint config of the root and of each workspace package, and follows
+relative imports and imports of workspace packages to find the `custom()` calls. It resolves
+`dir` and `name` when they are string literals.
+
 ## Requirements and boundaries
 
 - Adamantite requires Bun 1.0 or later when run with Bun, or Node.js 22.19 or later when