adamantite 0.41.0 → 0.42.0

package/README.md

@@ -86,8 +86,9 @@ npx adamantite init \
 Available setup values:
 
 - Scripts: `check`, `fix`, and `analyze`. In a detected monorepo, `analyze` also installs
-  Sherif. The legacy `check:monorepo` and `fix:monorepo` values are rejected.
-- Presets: `react`, `nextjs`, `vue`, `jest`, `vitest`, and `node`.
+  Sherif.
+- Presets: `react`, `react-strict`, `react-doctor`, `nextjs`, `vue`, `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
@@ -118,6 +119,14 @@ adamantite check
 adamantite check src
 ```
 
+Use `--only` to run one stage. Arguments after `--` go to that stage, and to Oxlint when
+both run:
+
+```sh
+adamantite check --only lint
+adamantite check --only format
+```
+
 ### `adamantite fix`
 
 Apply safe Oxlint fixes, then format the files with Oxfmt. Suggested and dangerous fixes require explicit flags:
@@ -129,10 +138,13 @@ adamantite fix --dangerous
 adamantite fix --all
 ```
 
-### `adamantite format` (deprecated)
+Use `--only` to run one stage. Arguments after `--` go to that stage, and to Oxlint when
+both run:
 
-`adamantite format` is deprecated and prints a warning. The next release removes it. Use
-`adamantite fix` to apply formatting and `adamantite check` to verify formatting.
+```sh
+adamantite fix --only lint
+adamantite fix --only format
+```
 
 ### `adamantite analyze`
 
@@ -168,13 +180,6 @@ adamantite analyze --only monorepo --fix -- --select highest
   `CI` is set), so `analyze --fix` fails there in a monorepo. CI runs `adamantite analyze`
   without `--fix`.
 
-### `adamantite monorepo` (deprecated)
-
-`adamantite monorepo` is deprecated and prints a warning with the replacement command. The
-next release removes it. Use `adamantite analyze`, or `adamantite analyze --only monorepo`
-to run only Sherif. `adamantite doctor` reports the legacy `check:monorepo` and
-`fix:monorepo` scripts and says how to remove them.
-
 ### `adamantite doctor`
 
 Assess every Adamantite-managed integration. Doctor is read-only. Each finding describes
@@ -186,15 +191,13 @@ adamantite doctor
 
 In an interactive terminal, Doctor presents each finding as formatted text and offers to
 hand off to an installed coding agent, or to copy one combined Markdown repair prompt. A
-handoff starts the selected agent CLI in the terminal with a short seed prompt; the agent
-runs `adamantite doctor` itself to read the findings and edits the project under its own
-permission and trust flow. When the agent session ends, Doctor reassesses and exits 0
-only when no findings remain. Doctor detects installed agents by probing each supported
-CLI — Claude Code (`claude`), Codex (`codex`), Cursor (`cursor-agent`), Gemini CLI
-(`gemini`), Grok Build (`grok`), and OpenCode (`opencode`) — and lists only the ones
-found on `PATH`. It warns before starting an agent on a working tree that is not known
-to be clean. OpenCode pre-fills its input with the seed prompt, so that handoff needs
-one Enter press to start.
+handoff starts the selected agent CLI in the terminal seeded with that same Markdown
+repair prompt; the agent edits the project under its own permission and trust flow. When
+the agent session ends, Doctor reassesses and exits 0 only when no findings remain.
+Doctor detects installed agents by probing each supported CLI — Claude Code (`claude`),
+Codex (`codex`), Cursor (`cursor-agent`), Gemini CLI (`gemini`), Grok Build (`grok`),
+and OpenCode (`opencode`) — and lists only the ones found on `PATH`. OpenCode pre-fills
+its input with the seed prompt, so that handoff needs one Enter press to start.
 
 A coding agent can also run `adamantite doctor` in the target project to receive Markdown
 directly. In a non-interactive run, Doctor prints the combined repair prompt and exits 1
@@ -237,19 +240,23 @@ underlying CLI.
 
 Adamantite publishes configuration that can also be consumed directly:
 
-| Export                     | Purpose                                                                                                                                                                                                                                                                 |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `adamantite/lint`          | Core Oxlint rules.                                                                                                                                                                                                                                                      |
-| `adamantite/lint/react`    | React, JSX accessibility, and performance.                                                                                                                                                                                                                              |
-| `adamantite/lint/nextjs`   | Next.js rules.                                                                                                                                                                                                                                                          |
-| `adamantite/lint/vue`      | Vue rules.                                                                                                                                                                                                                                                              |
-| `adamantite/lint/node`     | Node.js rules.                                                                                                                                                                                                                                                          |
-| `adamantite/lint/jest`     | Jest rules.                                                                                                                                                                                                                                                             |
-| `adamantite/lint/vitest`   | Vitest rules.                                                                                                                                                                                                                                                           |
-| `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/format`        | Oxfmt configuration.                                                                                                                                                                                                                                                    |
-| `adamantite/analyze`       | Knip configuration. The `ignoreDependencies` named export groups suggested ignore lists; `init` sets `ignoreDependencies.monorepo` in a monorepo.                                                                                                                       |
-| `adamantite/typescript`    | Strict TypeScript configuration for TS 7+.                                                                                                                                                                                                                              |
+| Export                         | Purpose                                                                                                                                                                                                                                                                                |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `adamantite/lint`              | Core Oxlint rules.                                                                                                                                                                                                                                                                     |
+| `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/nextjs`       | Next.js rules.                                                                                                                                                                                                                                                                         |
+| `adamantite/lint/vue`          | Vue rules.                                                                                                                                                                                                                                                                             |
+| `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/format`            | Oxfmt configuration.                                                                                                                                                                                                                                                                   |
+| `adamantite/analyze`           | Knip configuration. The `ignoreDependencies` named export groups suggested ignore lists; `init` sets `ignoreDependencies.monorepo` in a monorepo.                                                                                                                                      |
+| `adamantite/typescript`        | Strict TypeScript configuration for TS 7+.                                                                                                                                                                                                                                             |
 
 When consuming the lint presets directly, hoist the core preset's ignore patterns onto the
 root config. Oxlint does not merge `ignorePatterns` from extended configs, so without the
@@ -268,10 +275,134 @@ export default defineConfig({
 
 Configs generated by `adamantite init` include this automatically.
 
+### The react-strict preset
+
+`adamantite/lint/react-strict` keeps state and side effects out of React feature code. Use
+it together with `adamantite/lint/react`. It needs no extra package: the rules come from
+Adamantite's own Oxlint plugin, which ships inside the package.
+
+`adamantite/no-react-state-hooks` reports calls to `useState`, `useReducer`, `useEffect`,
+`useLayoutEffect`, `useSyncExternalStore`, `useMemo`, and `useCallback` imported from
+`react`, including aliased imports and `React.useState(...)`. Each message tells what to do
+instead: derive state from loader data or URL params, move side effects to loaders, actions,
+or event handlers, and let the React Compiler memoize. For the opinions that do not depend
+on React, add [the strict preset](#the-strict-preset).
+
+Hooks stay allowed in hook modules: files that match `**/use[A-Z]*.{ts,tsx}`, `**/use-*.{ts,tsx}`, or `**/hooks/**`, such as `useCart.ts`
+or `use-cart.ts`. A file such as `userProfile.tsx` is feature code.
+Globs match paths relative to the working directory. Set `allow` to use another layout, and
+`hooks` to change the list of reported hooks:
+
+```ts
+import { defineConfig } from "oxlint"
+import core from "adamantite/lint"
+import react from "adamantite/lint/react"
+import reactStrict from "adamantite/lint/react-strict"
+
+export default defineConfig({
+  extends: [core, react, reactStrict],
+  ignorePatterns: core.ignorePatterns,
+  rules: {
+    "adamantite/no-react-state-hooks": [
+      "error",
+      { allow: ["src/state/**", "**/use[A-Z]*.{ts,tsx}"], hooks: ["useState", "useEffect"] },
+    ],
+  },
+})
+```
+
+Each option replaces its default list.
+
+### The react-doctor preset
+
+`adamantite/lint/react-doctor` reports specific misuse of React state and effects. Use it
+together with `adamantite/lint/react`. It needs the `oxlint-plugin-react-doctor` package.
+`adamantite init` installs the pinned version when you select the preset, and
+`adamantite doctor` and `adamantite update` keep it on that version. If you add the preset
+by hand, install `oxlint-plugin-react-doctor` as a devDependency too.
+
+The plugin exports more than 900 rules. The preset enables only rules that run on one file
+and that the native `react`, `react-hooks`, `jsx-a11y`, and `unicorn` rules do not already
+report. Examples are an effect that does the work of an event handler (`no-effect-event-handler`), data fetched in an effect
+(`no-fetch-in-effect`), and state changed in place (`no-direct-state-mutation`). The
+TanStack Query and TanStack Start rules are not in this preset. See
+[ADR 0005](docs/adr/0005-curate-react-doctor-rules.md) for the criteria.
+
+The preset works together with `adamantite/lint/react-strict`. React Doctor rules report
+specific misuse, and `react-strict` bans the hooks in feature code. Some React Doctor rules
+skip test files and fixtures by path, such as `__tests__/` and `*.test.tsx`.
+
+`oxlint-plugin-react-doctor` has a modified MIT license. It needs written permission from
+the copyright holder to use the software as machine learning training data, or to sell it
+as a hosted product. Read the
+[license](https://www.npmjs.com/package/oxlint-plugin-react-doctor?activeTab=code) before
+you select the preset.
+
+### The strict preset
+
+`adamantite/lint/strict` holds framework-neutral opinions. Use it with any other preset. Like
+`react-strict`, it needs no extra package.
+
+- `adamantite/no-overzealous-destructuring` reports destructuring patterns nested more than
+  `maxDepth` levels deep (default 2), such as `const { data: { user: { name } } } = query`,
+  and object patterns that take more than `maxProperties` properties (default 5). A rest
+  element does not count. Keep the object and read its members, or split the pattern.
+- `typescript/consistent-type-assertions` bans type assertions. `as const` stays allowed,
+  and test files (`*.test.*`, `*.spec.*`, and `__tests__/`) keep the core preset's setting.
+
+Set `maxDepth` and `maxProperties` to change the destructuring limits:
+
+```ts
+import { defineConfig } from "oxlint"
+import core from "adamantite/lint"
+import strict from "adamantite/lint/strict"
+
+export default defineConfig({
+  extends: [core, strict],
+  ignorePatterns: core.ignorePatterns,
+  rules: {
+    "adamantite/no-overzealous-destructuring": ["error", { maxDepth: 1, maxProperties: 3 }],
+  },
+})
+```
+
+### The shadcn preset
+
+`adamantite/lint/shadcn` needs Tailwind v4 and the `@shadcn/lint` package. `adamantite init`
+installs the pinned version when you select the preset, and `adamantite doctor` and
+`adamantite update` keep it on that version. If you add the preset by hand, install
+`@shadcn/lint` as a devDependency too. The plugin finds your components and theme
+through `components.json`. Without that file it looks for components in `components/ui`
+or `src/components/ui` and discovers the stylesheet that imports Tailwind. When your
+components live elsewhere, set `settings.shadcn.ui`:
+
+```ts
+import { defineConfig } from "oxlint"
+import core from "adamantite/lint"
+import shadcn from "adamantite/lint/shadcn"
+
+export default defineConfig({
+  extends: [core, shadcn],
+  ignorePatterns: core.ignorePatterns,
+  settings: { shadcn: { ui: "@/ds" } },
+})
+```
+
+The preset allows layout classes such as `mt-4` and `w-[320px]` on components, and turns
+off `no-restyle`, `no-arbitrary-values`, and `require-static-classes` under
+`**/components/ui/**`, where components own their appearance. Add the same override for
+another component directory. See the
+[@shadcn/lint documentation](https://github.com/shadcn-ui/lint#settings) for settings,
+contracts, and custom messages.
+
 ## Requirements and boundaries
 
 - Adamantite requires Bun 1.0 or later when run with Bun, or Node.js 22.19 or later when
   run with Node.js.
+- Adamantite requires TypeScript 7 or later. List `typescript` as a dependency in your own
+  `package.json`. Do not rely on the copy that a package manager installs for Adamantite's
+  peer dependency: npm cannot add or update a managed plugin such as `@shadcn/lint` in a
+  project that has no `typescript` entry of its own.
 - This repository uses pnpm and Node.js for development, but the CLI can configure
   projects that use Bun, Deno, npm, pnpm, or Yarn where the selected integration supports
   them.