adamantite 0.40.0 → 0.42.0

package/README.md

@@ -52,7 +52,6 @@ and agent guidance. After setup, use the scripts written to `package.json`:
 ```sh
 bun run check
 bun run fix
-bun run format
 bun run analyze
 ```
 
@@ -62,9 +61,7 @@ scripts:
 ```sh
 adamantite check
 adamantite fix
-adamantite format
 adamantite analyze
-adamantite monorepo
 ```
 
 ## Non-interactive setup
@@ -77,7 +74,6 @@ npx adamantite init \
   --non-interactive \
   --script check \
   --script fix \
-  --script format \
   --script analyze \
   --preset react \
   --editor vscode \
@@ -89,19 +85,21 @@ npx adamantite init \
 
 Available setup values:
 
-- Scripts: `check`, `fix`, `format`, `analyze`, `check:monorepo`, and `fix:monorepo`.
-- Presets: `react`, `nextjs`, `vue`, `jest`, `vitest`, and `node`.
+- 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`.
 - Editors: `vscode` and `zed`.
 
 Presets and TypeScript require the `check` or `fix` script. Editor extension installation
-requires an editor. Monorepo scripts require a detected monorepo. GitHub Actions requires a
-compatible script and a supported package manager. Omitted boolean flags are disabled.
+requires an editor. GitHub Actions requires a compatible script and a supported package
+manager. Omitted boolean flags are disabled.
 
 Existing package scripts whose commands differ from Adamantite's are kept and reported
 instead of being replaced. The interactive initializer asks before overwriting them; in
 non-interactive mode, pass `--overwrite-scripts` to replace them. To keep custom flags,
 forward them to the Adamantite command after `--`, e.g.
-`adamantite monorepo -- --ignore-dependency tailwindcss`.
+`adamantite analyze -- --directory packages/app`.
 
 In a detected monorepo, TypeScript setup does not write a root `tsconfig.json`, because a
 catch-all root config makes TypeScript treat all packages as one project. Adamantite
@@ -114,16 +112,24 @@ Run `adamantite --help` or `adamantite <command> --help` for the complete CLI re
 
 ### `adamantite check`
 
-Find lint and type errors without changing files:
+Find formatting, lint, and type errors without changing files:
 
 ```sh
 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. Suggested and dangerous fixes require explicit flags:
+Apply safe Oxlint fixes, then format the files with Oxfmt. Suggested and dangerous fixes require explicit flags:
 
 ```sh
 adamantite fix
@@ -132,35 +138,47 @@ adamantite fix --dangerous
 adamantite fix --all
 ```
 
-### `adamantite format`
-
-Format files with Oxfmt, or check formatting without writing:
+Use `--only` to run one stage. Arguments after `--` go to that stage, and to Oxlint when
+both run:
 
 ```sh
-adamantite format
-adamantite format src/index.ts
-adamantite format --check
+adamantite fix --only lint
+adamantite fix --only format
 ```
 
 ### `adamantite analyze`
 
-Find unused dependencies, exports, and files with Knip. The `--fix` option can remove
+Find unused dependencies, exports, and files with Knip. In a detected monorepo, `analyze`
+first finds dependency consistency problems with Sherif. The `--fix` option can remove
 unused files, so review its effect before use.
 
 ```sh
 adamantite analyze
 adamantite analyze --strict
 adamantite analyze --fix
+adamantite analyze --only unused
+adamantite analyze --only monorepo --fix -- --select highest
 ```
 
-### `adamantite monorepo`
-
-Find dependency consistency problems in a monorepo with Sherif:
-
-```sh
-adamantite monorepo
-adamantite monorepo --fix
-```
+- The `monorepo` stage (Sherif) runs first, and only in a detected monorepo. The `unused`
+  stage (Knip) always runs.
+- Without `--fix`, both stages run and the exit code comes from the first failure. With
+  `--fix`, a Sherif failure skips Knip, because Knip must not remove code against a
+  dependency graph that Sherif did not repair.
+- `--fix` applies to each stage that runs. `--strict` applies to Knip only.
+- `--only monorepo` or `--only unused` runs one stage. `--only monorepo` fails outside a
+  monorepo and with `--strict`.
+- Arguments after `--` go to Knip, or to the stage that `--only` selects.
+- `analyze` runs Sherif without flags. Put project exceptions in the `sherif` field of the
+  root `package.json`, which Sherif reads. The keys are the Sherif CLI options in camelCase:
+  `ignoreDependency`, `ignoreRule`, `ignorePackage`, `select`, `noInstall`, and
+  `failOnWarnings`. For example: `"sherif": { "ignoreDependency": ["tailwindcss"] }`.
+- A Sherif fix that must choose between versions prompts in a terminal. Without a terminal,
+  set `"sherif": { "select": "highest" }` in the root `package.json`, or run
+  `adamantite analyze --only monorepo --fix -- --select highest`.
+- Use `--fix` locally, not in CI. Sherif refuses to fix in a CI environment (for example when
+  `CI` is set), so `analyze --fix` fails there in a monorepo. CI runs `adamantite analyze`
+  without `--fix`.
 
 ### `adamantite doctor`
 
@@ -173,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
@@ -207,8 +223,7 @@ Commands that invoke Knip, Oxlint, Oxfmt, or Sherif forward arguments after `--`
 ```sh
 adamantite analyze --strict -- --directory packages/app
 adamantite check src -- --deny-warnings
-adamantite format -- --ignore-path .formatignore
-adamantite monorepo -- --ignore-package package-a
+adamantite analyze --only monorepo -- --ignore-package package-a
 ```
 
 Package managers consume one separator, so package scripts need a second one:
@@ -225,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.                                                                                                                                                                                                                                                     |
-| `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
@@ -256,17 +275,140 @@ 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.
 - Adamantite manages recognized package scripts and supported configuration shapes. It
   reports custom configurations that require manual work instead of overwriting them.
-- `fix`, `format`, `analyze --fix`, `monorepo --fix`, `init`, and `update` can change
-  project files. Doctor is read-only.
+- `fix`, `analyze --fix`, `init`, and `update` can change project files. Doctor is read-only.
 
 ## Agent skill