adamantite 0.42.0 → 0.43.0

package/dist/presets/lint/plugin/rules/query-from-loader.js

@@ -0,0 +1,110 @@
+import { findImportedCalls } from "../imports.js";
+//#region presets/lint/plugin/rules/query-from-loader.ts
+const QUERY_MODULE = "@tanstack/react-query";
+const ROUTER_MODULE = "@tanstack/react-router";
+const QUERY_HOOKS = /* @__PURE__ */ new Set([
+	"useInfiniteQuery",
+	"useQuery",
+	"useSuspenseInfiniteQuery",
+	"useSuspenseQuery"
+]);
+const INFINITE_QUERY_HOOKS = /* @__PURE__ */ new Set(["useInfiniteQuery", "useSuspenseInfiniteQuery"]);
+const OPTIONS_FACTORIES = /* @__PURE__ */ new Set(["infiniteQueryOptions", "queryOptions"]);
+/**
+* A file that calls one of these defines a route, in file-based or code-based routing. Only route
+* files have a loader that can preload a query, so the rule checks only them.
+*/
+const ROUTE_FACTORIES = /* @__PURE__ */ new Set([
+	"createFileRoute",
+	"createLazyFileRoute",
+	"createLazyRoute",
+	"createRootRoute",
+	"createRootRouteWithContext",
+	"createRoute"
+]);
+function findVariable(context, identifier) {
+	let scope = context.sourceCode.getScope(identifier);
+	while (scope !== null && !scope.set.has(identifier.name)) scope = scope.upper;
+	return scope?.set.get(identifier.name);
+}
+/**
+* The initializer of a `const` that declares `variable` with a plain identifier, such as `const
+* options = { ... }`. Destructured, `let`, and imported bindings have none.
+*/
+function getConstInit(variable) {
+	const [definition] = variable.defs;
+	if (variable.defs.length !== 1 || definition?.type !== "Variable") return;
+	const { node, parent } = definition;
+	if (node.type !== "VariableDeclarator" || node.id.type !== "Identifier" || parent?.type !== "VariableDeclaration" || parent.kind !== "const") return;
+	return node.init ?? void 0;
+}
+function isModuleScope(variable) {
+	return variable.scope.type === "module" || variable.scope.type === "global";
+}
+const rule = {
+	create(context) {
+		const hookCalls = [];
+		const factoryCalls = /* @__PURE__ */ new Set();
+		let isRouteFile = false;
+		/**
+		* Why `options` does not come from a shared definition, or `undefined` when it does or when the
+		* rule cannot tell. `inModule` is true when the expression sits at module scope.
+		*/
+		function classify(options, inModule) {
+			if (options.type === "TSAsExpression" || options.type === "TSNonNullExpression" || options.type === "TSSatisfiesExpression" || options.type === "TSTypeAssertion") return classify(options.expression, inModule);
+			if (options.type === "ObjectExpression") return options.properties.some((property) => property.type === "SpreadElement") ? void 0 : "plainObject";
+			if (options.type === "CallExpression" && factoryCalls.has(options)) return inModule ? void 0 : "localOptions";
+			if (options.type === "Identifier") {
+				const variable = findVariable(context, options);
+				const init = variable === void 0 ? void 0 : getConstInit(variable);
+				return variable === void 0 || init === void 0 ? void 0 : classify(init, isModuleScope(variable));
+			}
+		}
+		return {
+			ImportDeclaration(node) {
+				if (node.source.value === ROUTER_MODULE) {
+					isRouteFile ||= findImportedCalls(context, node, ROUTE_FACTORIES).length > 0;
+					return;
+				}
+				if (node.source.value !== QUERY_MODULE) return;
+				hookCalls.push(...findImportedCalls(context, node, QUERY_HOOKS));
+				for (const { call } of findImportedCalls(context, node, OPTIONS_FACTORIES)) factoryCalls.add(call);
+			},
+			"Program:exit"() {
+				if (!isRouteFile) return;
+				for (const { call, name } of hookCalls) {
+					const [options] = call.arguments;
+					if (options === void 0) continue;
+					const messageId = classify(options, false);
+					if (messageId !== void 0) {
+						const data = INFINITE_QUERY_HOOKS.has(name) ? {
+							factory: "infiniteQueryOptions",
+							hook: name,
+							preload: "ensureInfiniteQueryData"
+						} : {
+							factory: "queryOptions",
+							hook: name,
+							preload: "ensureQueryData"
+						};
+						context.report({
+							data,
+							messageId,
+							node: options
+						});
+					}
+				}
+			}
+		};
+	},
+	meta: {
+		docs: { description: "Require TanStack Query hooks in route files to take options defined once with `queryOptions()` or `infiniteQueryOptions()`, so the route loader can preload the same query." },
+		messages: {
+			localOptions: "`{{hook}}` takes query options created inside a function, so the route loader cannot preload the same query. Move the `{{factory}}()` call to module scope, or into an exported factory such as `userQuery(id)`, preload it in this route's loader with `queryClient.{{preload}}()`, and pass the same options here.",
+			plainObject: "`{{hook}}` takes a plain options object instead of options defined with `{{factory}}()`. Define the options once with `{{factory}}()` at module scope or in a shared module, preload them in this route's loader with `queryClient.{{preload}}()`, and pass the same options here."
+		},
+		schema: [],
+		type: "suggestion"
+	}
+};
+//#endregion
+export { rule as default };

package/dist/presets/lint/tanstack.d.ts

@@ -0,0 +1,5 @@
+import { OxlintConfig } from "oxlint";
+//#region presets/lint/tanstack.d.ts
+declare const config: OxlintConfig;
+//#endregion
+export { config as default };

package/dist/presets/lint/tanstack.js

@@ -0,0 +1,14 @@
+//#region presets/lint/tanstack.ts
+const PLUGIN_EXTENSION = import.meta.url.endsWith(".ts") ? "ts" : "js";
+const config = {
+	jsPlugins: [{
+		name: "adamantite",
+		specifier: new URL(`plugin/index.${PLUGIN_EXTENSION}`, import.meta.url).href
+	}],
+	rules: {
+		"adamantite/no-query-data-in-state": "error",
+		"adamantite/query-from-loader": "error"
+	}
+};
+//#endregion
+export { config as default };

package/dist/presets/rules/index.d.ts

@@ -0,0 +1,9 @@
+import { Context, Diagnostic, ESTree, Fix, Fixer, Node, Options, Plugin, Rule, RuleMeta, SourceCode, Visitor, VisitorWithHooks, defineRule } from "@oxlint/plugins";
+//#region presets/rules/index.d.ts
+/**
+ * Import every rule file in a rules folder and return them as one Oxlint plugin. The entry module
+ * that `custom()` writes calls this function.
+ */
+export declare function loadRules(dir: string, name?: string): Promise<Plugin>;
+//#endregion
+export { type Context, type Diagnostic, type ESTree, type Fix, type Fixer, type Node, type Options, type Rule, type RuleMeta, type SourceCode, type Visitor, type VisitorWithHooks, defineRule };

package/dist/presets/rules/index.js

@@ -0,0 +1,29 @@
+import { DEFAULT_PLUGIN_NAME, getRuleName, listRuleFiles } from "../lint/custom.js";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { defineRule } from "@oxlint/plugins";
+//#region presets/rules/index.ts
+async function importRule(path) {
+	let module;
+	try {
+		module = await import(pathToFileURL(path).href);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`Custom rule ${path} failed to load: ${reason}\nRule files run with type stripping, so use erasable TypeScript only: no enum, namespace, or parameter properties.`, { cause: error });
+	}
+	if (module.default === void 0) throw new Error(`Custom rule ${path} has no default export. Export the rule as default.`);
+	return module.default;
+}
+/**
+* Import every rule file in a rules folder and return them as one Oxlint plugin. The entry module
+* that `custom()` writes calls this function.
+*/
+async function loadRules(dir, name = DEFAULT_PLUGIN_NAME) {
+	const rules = await Promise.all(listRuleFiles(dir).map(async (file) => [getRuleName(file), await importRule(join(dir, file))]));
+	return {
+		meta: { name },
+		rules: Object.fromEntries(rules)
+	};
+}
+//#endregion
+export { defineRule, loadRules };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adamantite",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "An strict and opinionated set of presets for modern TypeScript applications",
   "keywords": [
     "adamantite",
@@ -54,40 +54,45 @@
       "types": "./dist/presets/lint/*.d.ts",
       "default": "./dist/presets/lint/*.js"
     },
+    "./rules": {
+      "types": "./dist/presets/rules/index.d.ts",
+      "default": "./dist/presets/rules/index.js"
+    },
     "./typescript": "./dist/presets/tsconfig.json"
   },
   "dependencies": {
-    "@clack/prompts": "1.7.0",
+    "@clack/prompts": "1.8.1",
     "@effect/platform-node": "4.0.0",
+    "@oxlint/plugins": "1.86.0",
     "defu": "6.1.7",
     "effect": "4.0.0",
     "jsonc-parser": "3.3.1",
-    "nypm": "0.6.9",
-    "oxc-parser": "0.150.0"
+    "nypm": "0.6.10",
+    "oxc-parser": "0.152.0"
   },
   "devDependencies": {
-    "@changesets/changelog-github": "1.0.0",
-    "@changesets/cli": "3.0.1",
+    "@changesets/changelog-github": "1.0.1",
+    "@changesets/cli": "3.0.3",
+    "@effect/tsgo": "0.48.0",
     "@effect/vitest": "4.0.0",
-    "@oxlint/plugins": "1.83.0",
-    "@shadcn/lint": "0.1.5",
-    "@tanstack/intent": "0.3.7",
+    "@shadcn/lint": "0.2.0",
+    "@tanstack/intent": "0.5.0",
     "@types/figlet": "1.7.0",
-    "@types/node": "22.20.1",
-    "@vitest/coverage-v8": "5.0.1",
-    "@vitest/ui": "5.0.1",
-    "figlet": "1.11.4",
-    "knip": "6.32.2",
-    "oxfmt": "0.65.0",
-    "oxlint": "1.83.0",
+    "@types/node": "22.20.5",
+    "@vitest/coverage-v8": "5.0.3",
+    "@vitest/ui": "5.0.3",
+    "figlet": "1.12.0",
+    "knip": "6.39.0",
+    "oxfmt": "0.71.0",
+    "oxlint": "1.86.0",
     "oxlint-plugin-react-doctor": "0.9.14",
-    "oxlint-tsgolint": "7.0.2001",
+    "oxlint-tsgolint": "7.0.2003",
     "sherif": "1.13.0",
-    "tsdown": "0.22.14",
-    "type-fest": "5.8.0",
+    "tsdown": "0.23.0",
+    "type-fest": "5.10.0",
     "typescript": "7.0.2",
     "unplugin-macros": "0.23.2",
-    "vitest": "5.0.1"
+    "vitest": "5.0.3"
   },
   "peerDependencies": {
     "typescript": ">=7"

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,8 +29,8 @@ 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.
-- Presets: `react`, `react-strict`, `react-doctor`, `nextjs`, `vue`, `jest`, `vitest`, `node`,
-  `strict`, `antislop`, `shadcn`;
+- 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`
@@ -46,6 +47,17 @@ properties; keep the object and read its members, or split the pattern. Do not r
 `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
@@ -54,6 +66,18 @@ a modified MIT license: using it as machine learning training data or selling it
 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
@@ -133,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
 
@@ -143,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.