adamantite 0.41.0 → 0.43.0

package/skills/adamantite/SKILL.md

@@ -8,6 +8,7 @@ metadata:
 sources:
   - "adelrodriguez/adamantite:src/cli.ts"
   - "adelrodriguez/adamantite:src/commands/*.ts"
+  - "adelrodriguez/adamantite:src/lib/workspace/custom-rules.ts"
 ---
 
 # Adamantite
@@ -28,12 +29,66 @@ npx adamantite init --non-interactive --script check --script fix --typescript -
 Repeat `--script`, `--preset`, and `--editor` for multiple values. Available values are:
 
 - Scripts: `check`, `fix`, `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`, `node`, `antislop`; editors:
-  `vscode`, `zed`
+- Presets: `react`, `react-strict`, `react-doctor`, `tanstack`, `nextjs`, `vue`, `effect`, `jest`,
+  `vitest`, `node`, `strict`, `antislop`, `shadcn`;
+  editors: `vscode`, `zed`
 - Optional flags: `--typescript`, `--install-extensions`, `--github-actions`, `--agents`,
   `--overwrite-scripts`
 
+The `react-strict` preset needs no extra package. Its `adamantite/no-react-state-hooks` rule
+reports React state, effect, and memoization hooks outside hook modules (`useCart.ts`,
+`use-cart.ts`, and files under `hooks/`), and each message tells what to do instead. Do not move a hook call into
+a hook module only to silence the rule: follow the message. Set the rule's `allow` option
+when the project keeps hooks elsewhere.
+
+The `strict` preset needs no extra package either. Its `adamantite/no-overzealous-destructuring`
+rule reports destructuring nested more than 2 levels deep or object patterns with more than 5
+properties; keep the object and read its members, or split the pattern. Do not raise
+`maxDepth` or `maxProperties` only to silence a report. The preset also bans type assertions
+outside tests.
+
+The `tanstack` preset needs no extra package. Its `adamantite/query-from-loader` rule reports
+TanStack Query hooks in route files (files that call `createFileRoute`, `createRoute`, or another
+route factory from `@tanstack/react-router`) that take a plain options object or a `queryOptions()` call made inside a
+function; define the query once with `queryOptions()` at module scope or in an exported factory,
+preload it in the route loader with `ensureQueryData()`, and pass the same options to the hook. For
+`useInfiniteQuery` and `useSuspenseInfiniteQuery`, use `infiniteQueryOptions()` and
+`ensureInfiniteQueryData()`. Its
+`adamantite/no-query-data-in-state` rule reports `useState` initialized from query data; read the
+value from the query result and keep only the user's edits in state. Do not wrap options in a
+spread object, or move the hook out of the route file, only to silence `query-from-loader`.
+
+The `react-doctor` preset requires the `react` preset and the `oxlint-plugin-react-doctor`
+package, which `init` installs at a pinned version and doctor and `update` keep in sync. It
+enables curated React Doctor rules for React state and effect misuse, such as
+`no-effect-event-handler` and `no-fetch-in-effect`, and adds to `react-strict`. The package has
+a modified MIT license: using it as machine learning training data or selling it as a
+hosted product needs written permission from the copyright holder. Tell the user before you
+select the preset.
+
+The `effect` preset needs the `@effect/tsgo` package, which `init` installs at a pinned
+version and doctor and `update` keep in sync. Its rules exist only in Oxlint binaries that
+`adamantite prepare` patched, so the `prepare` script in `package.json` must run
+`adamantite prepare`; without the patch, Oxlint stops with `Unknown plugin: 'effecttsgo'`.
+Do not remove the patch or the preset to get past that error: run `adamantite prepare`. If a
+production-only install fails at `adamantite prepare`, add `--ignore-scripts` to that
+install instead of changing the script. `tsconfig.json` needs
+`{ "name": "@effect/language-service", "diagnostics": false }` in `compilerOptions.plugins`,
+and `knip.config.ts` needs `ignoreDependencies.effect`. To allow an unstable Effect module
+on purpose, add it to `allowedUnstableApis` in that tsconfig entry. Do not turn off
+`effecttsgo/unstable-api-usage`.
+
+The `shadcn` preset needs Tailwind v4 and the `@shadcn/lint` package, which `init` installs
+at a pinned version and doctor and `update` keep in sync. The plugin finds components and
+the theme through `components.json`. Without that file it looks in `components/ui` or
+`src/components/ui` and discovers the stylesheet that imports Tailwind; when components
+live elsewhere, set `settings.shadcn` (for example `{ ui: "@/ds" }`) in `oxlint.config.ts`.
+The preset turns off the component-owned rules under `**/components/ui/**`; add the same
+override for another component directory.
+
+Adamantite requires TypeScript 7 or later as a dependency in the project's own
+`package.json`. Without that entry, npm cannot add or update a managed plugin.
+
 Only select options supported by the project. Presets and TypeScript require `check` or `fix`;
 extension installation requires an editor; `--github-actions` requires a CI-compatible script
 and a supported package manager (bun, deno, npm, pnpm, or yarn). Omitted boolean flags are
@@ -53,11 +108,10 @@ adamantite fix
 adamantite analyze
 ```
 
-- Use `check` for read-only formatting, lint, and type-error validation.
+- Use `check` for read-only formatting, lint, and type-error validation. `check --only lint` or `check --only format`
+  runs one stage.
 - Use `fix` for automatic Oxlint fixes followed by Oxfmt formatting. Add `--suggested`, `--dangerous`, or `--all` only
-  with explicit permission after reviewing their impact.
-- Do not use `format`. It is deprecated and the next release removes it. `fix` writes formatting changes and `check`
-  verifies formatting for read-only CI checks.
+  with explicit permission after reviewing their impact. `fix --only lint` or `fix --only format` runs one stage.
 - Use `analyze` for unused dependencies, exports, and files. In a monorepo it first checks
   workspace dependency consistency with Sherif. `analyze --only monorepo` or
   `analyze --only unused` runs one stage. `analyze --fix` may remove files, so inspect
@@ -68,8 +122,6 @@ adamantite analyze
   use `analyze --only unused --fix` to skip Sherif.
 - `analyze` runs Sherif without flags. Put Sherif exceptions in the `sherif` field of the root
   `package.json` (camelCase CLI options, e.g. `"ignoreDependency": ["tailwindcss"]`).
-- Do not use `monorepo`. It is deprecated and the next release removes it. Use `analyze`, or
-  `analyze --only monorepo` to run only Sherif.
 
 To pass arguments to Knip, Oxlint, or Sherif, place them after `--`. For `check` and `fix` they
 go to Oxlint. For `analyze` they go to Knip, or to the stage that `--only` selects, so a Sherif
@@ -105,8 +157,48 @@ adamantite update
 adamantite doctor
 ```
 
-`update` updates Adamantite-managed dependencies. It then reports any remaining doctor
-findings. Follow those findings and review the resulting diff.
+`update` updates Adamantite-managed dependencies and, with the effect preset, patches Oxlint
+and TypeScript again. It then reports any remaining doctor findings. Follow those findings and review the resulting diff.
+
+## Custom rules
+
+<!-- Keep this section the same as the AGENTS.md text in src/lib/workspace/custom-rules.ts. -->
+
+Each file in the rules folder, `.adamantite/rules/` by default, is an Oxlint rule that this
+project owns. `custom()` from `adamantite/lint/custom` loads the folder and enables each
+rule as `error` under the `project` plugin: `no-process-env.ts` becomes
+`project/no-process-env`. Add a file to add a rule. Delete the file to remove the rule.
+`adamantite rule add <name>` writes a correct stub.
+
+- A file that starts with `_`, such as `_helpers.ts`, is a helper, not a rule. Subfolders are
+  not read.
+- Export the rule as default with `defineRule` from `adamantite/rules`. The same module exports
+  the `Context`, `Rule`, `Visitor`, and `ESTree` node types.
+- Use `createOnce`. It runs one time for each lint run, not one time for each file. Reset
+  per-file state in `before`, and report collected results in `after`. `context.filename`,
+  `context.sourceCode`, and `context.settings` are not available in the body of
+  `createOnce`. Read them in `before` or in a visitor.
+- Write erasable TypeScript only. Oxlint loads rule files with Node.js type stripping, so
+  `enum`, a `namespace` with values, parameter properties, and `import x = require()` stop
+  the lint run.
+- Rules get no type information. Use only the AST and `context.sourceCode`.
+- Report with a `messageId`, and put each message in `meta.messages`. Describe the options in
+  `meta.schema`, and read them from `context.options`.
+- A rule that throws prints an error for each file, and the lint run still exits 0. After you
+  change a rule, run the lint and read all of its output.
+- To find node names, run `adamantite rule ast <file>` on real code. It prints the same
+  ESTree-shaped AST that rules visit.
+- To test a rule, use `RuleTester` from `oxlint/plugins-dev`. Adamantite does not run rule
+  tests.
+- Oxlint caches the rules for each run. Restart the editor language server after you change a
+  rule.
+- TypeScript does not check `.adamantite/rules/` by default, because its name starts with a dot. Add
+  `".adamantite/rules"` to `include` in `tsconfig.json` to check it.
+- In a monorepo, give each rules folder its own plugin name, such as `custom({ name: "web" })`:
+  Oxlint rejects two plugins with the same name in one run. A relative `dir` resolves from the
+  file that calls `custom()`, so a shared tooling package can own the rules with
+  `custom({ dir: "rules", name: "acme" })`. A nested Oxlint config replaces the root config, so
+  a package that needs the root rules extends the root config.
 
 ## Decision guide
 
@@ -115,4 +207,6 @@ findings. Follow those findings and review the resulting diff.
 - Existing project upgrading Adamantite: `update`, then the doctor sequence.
 - Code-quality failure: choose `check` or `analyze` based on the failing subsystem; do not
   reinitialize the project.
+- Project-specific lint rule: add a custom rule with `adamantite rule add <name>`; do not
+  edit Adamantite presets.
 - Unknown option or behavior: run `adamantite <command> --help` before guessing.