oxlint-plugin-arch 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,61 @@
 # Changelog
 
-## Unreleased
+## 0.6.0
+
+- Add `tests.profile` (`fixtures` by default, or `standard`), explicit custom test/assertion names, parameterized-test recognition and assertion-based narrowing guidance. Both profiles retain assertion, mock and type-safety checks; fixtures additionally require named fixture/support imports.
+- Add explicit `modules.migrationFiles` scopes to exempt framework migration functions from service function/signature and folder-layout conventions without globally ignoring their safety checks.
+- Recognize `test.for` titles and configured custom test modifiers; cover profiles and migration isolation with real Oxlint CLI regressions.
+- Replace the preset’s native assertion-presence/placement checks with `modules/test-assertions`, covering native and extended tests, called local helpers and static table-row assertion callbacks. Require an assertion in every row; retain errors for standalone assertions, unused helpers and shadowed expectations. Custom assertion DSLs use `tests.additionalAssertionFunctions` or scoped module-rule options.
+- Recognize polling/soft assertions without mistaking table builders or asymmetric matchers for assertions. Verify Tailwind fixes converge by file contents rather than assuming exit zero means an unchanged next pass.
+- Add `arch/component-props`: every React component with props, exported or local, uses `interface XProps` declared directly above it; inline props always fail. Pass-through components may take a plain `ComponentProps<'tag'>` or `ComponentProps<typeof X>`. `filePrefix` requires local components to carry the file prefix. Enabled in the preset (with `filePrefix`) for `components/**/*.tsx`, excluding `components/ui` and tests; hooks, routes and non-component functions are unaffected. Opt out with `react: { componentProps: false }`, which leaves the other type-placement rules on.
+
+## 0.5.0
+
+- Replace the preset's `eslint-plugin-better-tailwindcss` dependency with `oxlint-tailwindcss` 1.14.0. Preserve seven Tailwind checks, per-root CSS themes and root font size, with shadcn retaining unknown-class and component checks. Consumer rule overrides must use the new `tailwindcss/*` IDs documented in the README. Add real autofix/idempotence coverage; deprecated classes now belong to the dedicated deprecation diagnostic.
+
+- Breaking unreleased preset API cleanup: grouped limits, modules, imports, oRPC, SQL, forms, React and TanStack Start settings; all boolean/callback policies now live under `policies`. Use `severity`, `cliFiles` and `ruleExclusions`; Tailwind/shadcn leaves use explicit names. Old flat preset keys are removed. Rule behavior, defaults, callback order and standalone rule APIs are unchanged.
+
+- Configure per-root folder layouts through role/object architecture entries; keep shorthand defaults, exact flat/domain structure, hook/component naming and layout-derived RPC ownership.
+- Permit strictly named public method-only frontend service objects without changing factory-returned APIs; check their trivial wrappers and parameter contracts.
+- Add TanStack runtime boundary checks with scoped imported factory recognition, an RPC-owner server-branch exception, direct dependency/global checks and exact-file computed-import customization.
+- Expose the existing max-lines ceiling as maxLines (default 400); improve helper, constants, namespace, alias, filename and portable-contract diagnostics with exact-message regressions.
+
+- Web runtime service entries support cohesive public operations with domain-prefixed nested helpers and no private module-level functions. Explicit actions/queries and backend service rules remain strict. Web module data moves to domain-prefixed constants files; real service instances keep their lifetimes.
+
+- Enable `arch/prefer-namespace-type-import` at `max: 3` in the preset imports policy. Add CLI threshold, namespace acceptance, qualified-reference autofix/idempotence, TypeScript and consumer-option regressions plus rule-coverage fixtures.
+
+- Keep every configured frontend library portable: reject app service/API dependencies and foreign domain types, allowing only type-only consumption of a same-root, same-stem contract. Reject app-type re-exports; normalize optional utility stems and resolve relative/configured aliases. Keep backend scopes and existing consumer exceptions intact, with CLI regressions for multiple web roots and domain utilities.
+
+- Replace the unreleased preset's fixed architecture slots with normalized path-to-role mappings supporting multiple apps per role and rejecting overlapping roots. Add explicitly declared concept file roles with full domain-role function prefixes and same-app domain boundaries; public service/utils surfaces reject private re-exports. Retain scope-resolved returned-method support for standalone consumers; backend factories remain strict.
+
+- Enable precise trivial-function detection in the preset: configurable helper names, renamed generic guards and unchanged-argument wrappers; preserve legacy defaults and meaningful transformations.
+- Require domain prefixes for private utility/action/query functions with `allFunctions`; keep exact filename matching for exported operations and strict service helper boundaries.
+
+- Allow meaningful imported generic type instantiations; add opt-in camel-case filename placeholders and enable them for preset action/query names.
+
+- Allow standard caller opacity utilities in the preset's shadcn policy; retain bans on other appearance overrides and arbitrary opacity, verified with a real CLI fixture.
+
+- Allow private nested helpers only in action/query operations, require exactly one named function export there, and reject additional type/value/re-exports. Keep module-level helpers and other service scopes strict. Add configurable guidance explaining that `.utils.ts` is reserved for genuinely shared helpers.
+
+- Disable render-time function/object/array/JSX prop bans for React Compiler projects; keep them when `reactCompiler: false`. Allow frontend service constants while retaining backend separation under configurable architecture roots. Keep portable-type and intentional-wrapper exceptions consumer-owned and file-specific.
+
+- Restore missing type-file/helper restrictions and close utility-type, prompt-comment and UI-kit safety/formatting exceptions. Type and constant files reject ordinary and SAFETY comments; constants cannot hide functions.
+- Enable unbound-method, catch-callback typing, noninteractive-tabindex and render-time object/function prop checks. Require typed mocks, enforce file-size/complexity limits in tests, and restrict all console methods to configured scripts/CLI or explicit adapter exceptions.
+- Compare Crauler's enabled rules, disabled rules, exclusions and options against the baseline; retain its route-handler helper restriction without copying product-specific ignores. Add scope regressions and retain passing/failing fixtures for every enabled preset rule.
+
+- Cover all 475 enabled preset rules, including implicit Oxlint defaults, with positive and negative CLI fixtures. Compare the manifest to resolved configuration and verify fixture discovery so newly enabled rules cannot silently lack coverage.
+- Recognize SAFETY comments immediately above exported assertions without allowing comments to leak across statement boundaries.
+
+- Add checked-in valid, invalid and customized preset mini-projects with real CLI diagnostics and a TypeScript-clean baseline. Fix public-entry export naming, domain type filename scopes, intrinsic JSX dynamic classes and TypeScript package import resolution.
+- Add opt-in `multilineVariables` padding and `operatorMethods` SQL sanitizer checks without changing either rule's existing defaults. The preset enables both.
+
+- Keep preset entry points under `src/presets`, explicit configuration groups under `src/configs`, and named contracts under `src/types`. Separate plugin loading, architecture resolution and policy composition; remove runtime rule-name classification and nested preset helpers.
+
+- Keep Dillon Mulroy's vendored rules under `src/rules/dillon-anti-slop`, using the `dillon-anti-slop/*` namespace, with upstream attribution and the original MIT license included in the package.
+
+- Verify standalone frontend paths, custom import-alias boundaries, exported Props interfaces, public endpoint scopes and policy switches in preset mini projects. Promote native correctness defaults without repeating their rule entries.
+
+- Add the typed `tanstack-start-react-modules-preset` export with configurable architecture roots, error/warn level, boolean/callback policies, rule-specific exclusions and native Oxlint composition. Include React, effects, Tailwind/shadcn, formatting, module boundaries and supporting safety rules; verify behavior with CLI mini projects. The preset requires Oxlint 1.85+ and its type-aware engine.
 
 - Add `prefer-namespace-type-import` with a configurable named-type-import limit (default 3), module-specific namespace names, and scope-aware autofixes that qualify type references while reporting unsafe rewrites without a fix.
 

package/README.md

@@ -11,6 +11,226 @@ Keep a codebase shaped the way you designed it: files in the right folders, expo
 
 ---
 
+## TanStack Start React modules preset
+
+The optional **`tanstack-start-react-modules-preset`** supplies an opinionated application policy. The individual `arch` rules remain generic; importing the plugin alone does not enable the preset.
+
+```sh
+bun add -d oxlint oxlint-tsgolint oxlint-plugin-arch
+```
+
+In your root `oxlint.config.ts`:
+
+```ts
+import preset from 'oxlint-plugin-arch/presets/tanstack-start-react-modules-preset';
+
+export default preset({ root: import.meta.dirname });
+```
+
+The equivalent named import is `tanstackStartReactModulesPreset` from `oxlint-plugin-arch/presets`. Both return a normal `OxlintConfig` object. The preset ships its JS-plugin dependencies and resolves them from its own package, including React, effects, Tailwind, shadcn, import ordering, formatting and type-safety rules. Type-aware linting is enabled; install `oxlint-tsgolint` and provide a tsconfig for the files you lint. Oxlint 1.85 or newer is required.
+
+Tailwind checks use `oxlint-tailwindcss`: canonical names, ordering, shorthand, conflicts, duplicates, deprecated classes and whitespace. Shadcn retains unknown-class validation and component styling contracts. The Tailwind plugin caches compiled theme data on disk; cold runs can cost more than subsequent runs. Set `OXLINT_TAILWINDCSS_CACHE_DIR` to control its cache location. Existing `better-tailwindcss/*` consumer overrides must migrate to `tailwindcss/*`: `enforce-canonical-classes` becomes `enforce-canonical`, `enforce-consistent-class-order` becomes `enforce-sort-order`, and `enforce-shorthand-classes` becomes `enforce-shorthand`; the other enabled rule suffixes remain the same.
+
+Custom utilities must be declared in the configured CSS entry point or its imports. Conflicts with properties defined by those utilities are still reported. Review intentional property overrides instead of globally allowing custom class names. In Oxlint 1.85, overlapping autofixes to the same class string can require another `--fix` run before it is clean.
+
+### Architecture
+
+Paths are relative **app roots**, not `src` directories. These are the defaults:
+
+```ts
+export default preset({
+  root: import.meta.dirname,
+  architecture: {
+    'apps/web': 'web',
+    'apps/server': 'server',
+    scripts: 'scripts',
+    packages: 'packages',
+  },
+});
+```
+
+`architecture` maps paths to roles and replaces the defaults when supplied. Multiple apps may share a role: `{ 'apps/dashboard': 'web', 'apps/storefront': 'web', 'apps/api': 'server', packages: 'packages', scripts: 'scripts' }`. Use `runner` for another strict backend, or `{ '.': 'web' }` for a standalone frontend. Omit absent roots. Paths are normalized; duplicates, overlapping roots and paths outside the project are rejected. Web and backend roles derive `src/services`, `src/types` and other application scopes; packages have no assumed app layout, and scripts permit console output. Shared baseline policies still apply everywhere. Each web root defaults to its own `src/application/styles.css`. Set `tailwind.cssEntryPointsByRoot: { 'apps/storefront': 'themes/store.css' }` for per-root paths, or `tailwind.cssEntryPoint` for an explicitly shared stylesheet. Entry paths are relative to `root`; `tailwind: false` disables Tailwind. Per-root CSS is supplied through Tailwind rule options because Oxlint 1.85 has no override-level `settings`. Shadcn discovers each app's theme through its own `components.json` (or package-local discovery). `root` makes asset and package resolution independent of the lint command's working directory; invoke the root config from its real filesystem location.
+
+Folder layout is independent of role/content rules. Shorthand roles use defaults: web has domain services and flat hooks; server/runner have domain services. Other folders keep their existing role conventions unless explicitly configured. Object entries merge folder choices into those defaults:
+
+```ts
+architecture: {
+  'apps/dashboard': { role: 'web', layout: { services: 'flat', hooks: 'domain', features: 'domain' } },
+  'apps/storefront': { role: 'web', layout: { services: 'domain', features: 'flat' } },
+  'apps/api': { role: 'server', layout: { services: 'domain' } },
+}
+```
+
+Folder keys are literal paths relative to an app's `src` (relative to the root for packages/scripts), not new architecture slots. Segments use letters, numbers, underscores and hyphens; absolute paths, escapes, globs, empty segments and overlapping configured/default folders are rejected. `flat` requires source files directly in that folder. `domain` requires exactly one directory and filename ownership by that directory; loose/deeper files cannot coexist. Checks cover TS/TSX/MTS/CTS source files, not asset directory trees. Generic domain filenames start with their owning directory plus a dot/hyphen; hooks retain `use-` and components retain their existing singular-name convention. Choosing layout never disables service exports, types, constants, runtime suffixes or anti-slop. Existing policy callbacks and native overrides remain available.
+
+RPC ownership follows each web root's service layout: `services/rpc.client.ts` for flat, `services/rpc/rpc.client.ts` for domain. `orpc.clientOwnerFile` remains the explicit consumer override. There is no mixed-layout mode.
+
+### Configure settings and policies
+
+Settings are grouped by responsibility. The unreleased preset uses only this grouped API; old flat preset keys are not aliases. Standalone rule options are unchanged.
+
+```ts
+export default preset({
+  root: import.meta.dirname,
+  severity: 'warn',
+  limits: { maxFileLines: 400, maxFunctionComplexity: 32 },
+  modules: { customFileRoles: ['prompts'] },
+  imports: {
+    backendEntryPoints: ['@app/server/client'],
+    aliases: { '@backend': 'apps/server/src' },
+    internalSortPatterns: ['^@app/'],
+  },
+  orpc: {
+    publicProcedureFiles: ['apps/server/src/rpc/public/**/*.ts'],
+    outputSchemaComposers: ['paginatedOutput'],
+    clientOwnerFile: 'apps/web/src/services/rpc/rpc.client.ts',
+  },
+  react: { compiler: true },
+  forms: { schemaResolver: 'standardSchemaResolver' },
+  sql: { likeSanitizers: ['escapeLikeWildcards'] },
+  policies: {
+    typePlacement: (current) => current.map((scope) => ({
+      ...scope,
+      excludeFiles: [...(scope.excludeFiles ?? []), '**/portable/**'],
+    })),
+  },
+});
+```
+
+Each entry under `policies` accepts `true` (default configuration), `false` (disabled), or a callback receiving fresh native Oxlint override objects. Callbacks run in the existing policy order before overall severity is applied; deliberately disabled rules stay disabled. They never mutate another preset invocation. Append an override to the callback's returned array to extend a policy.
+
+Available policies: `typePlacement`, `typeSafety`, `serviceStructure`, `fileLayout`, `naming`, `comments`, `formatting`, `statementLayout`, `imports`, `react`, `effects`, `memoization`, `routes`, `forms`, `schemas`, `boundaries`, `tests`, `trivialFunctions`, `mutableState`, `backend`, `rpcClientOwnership`, `tailwind`, and `shadcn`.
+
+`policies.typePlacement: false` disables type location restrictions; `policies.typeSafety` still rejects explicit any/unknown. `imports` contains import settings, while `policies.imports` customizes rule overrides. Backend entry points govern permitted imports and schema ownership; internal sort patterns only classify import ordering. `orpc.publicProcedureFiles` identifies endpoint files requiring output schemas. `cliFiles` lists CLI files receiving console/switch exceptions.
+
+`severity` defaults to `error` and accepts `warn`. File and function limits default to 400 and 32. React Compiler is assumed by default: manual memoization is banned and the four React performance rules against render-time function/object/array/JSX props are off. `react: { compiler: false }` allows manual memoization and enables those four rules. `react: { componentProps: false }` turns off only `arch/component-props` (props typed with `interface XProps` directly above each component); it is on by default. `shadcn: false` disables shadcn integration while retaining Tailwind checks. `tailwind` accepts `cssEntryPoint`, `cssEntryPointsByRoot` and `rootFontSize`; `shadcn` accepts `uiImportPath` and `componentImportSources`. UI-kit files remain linted, with architecture/appearance exceptions rather than a global ignore.
+
+Shadcn allows caller-owned layout and standard opacity utilities. Add product-specific component contracts through `policies.shadcn` or native overrides, keeping `layout` and `opacity` in replacement allowances.
+
+Module configuration, lookup tables, limits and defaults belong in domain `.constants.ts` files, including frontend services. All frontend constant declarations carry the domain prefix (for example `BOT_MODEL_PRIORITY`). Frontend service scopes enable `modules/domain-constants` with `includeData: true`: it detects module-level literal/object/array data, literal calculations and seeded Map/Set tables, plus the existing uppercase constants. Function-local calculations and call-created service instances remain in their owner; empty Map/Set state is not classified as configuration. This is syntactic enforcement, not semantic data-flow analysis: imported aliases and arbitrary call-created configuration still need review. Backend rule defaults are unchanged. Every scope follows the configured architecture roots; a web `.server.ts` file remains frontend-owned.
+
+### Tests
+
+Both test profiles use the same assertion, typed-mock, type-safety and no-module-mocking rules. `fixtures` is the default and preserves the backend convention of importing named fixtures or `tests/support`, rather than `tests/helpers`. `standard` leaves helper-folder organization open. Neither profile chooses a database, constructs a test kit, changes fixture lifetimes, or requires a particular service assembly.
+
+```ts
+export default preset({
+  tests: {
+    profile: 'fixtures', // Or 'standard'.
+    additionalTestFunctions: ['integrationTest'],
+    additionalAssertionFunctions: ['expectRejectsWithInternal'],
+  },
+});
+```
+
+Regular tests, `test.for`/`test.each` tables and their `it` equivalents are recognized in both profiles, including concurrent/sequential forms. Additional test names also register those forms. Test-function names must be literal identifiers or dotted names. Assertion helpers also accept rooted dotted patterns, for example `arch.**.to*` for an explicitly reviewed fluent assertion API. Register only assertion helpers that actually fail on incorrect results; registering a name does not inspect its implementation. Standard Vitest `expect`, `expectTypeOf`, `assert`, `assert.*` and `assertType` assertions remain enabled.
+
+`modules/test-assertions` checks assertion presence and placement for native Vitest tests, locally extended fixture tests and configured custom functions. It replaces the preset’s `vitest/expect-expect` and `vitest/no-standalone-expect` checks: those cannot consistently follow fixture and table-row callbacks. It follows called local helpers and statically declared object table rows, including destructured/renamed callbacks, and requires an assertion for every row. Unused assertion callbacks do not satisfy it. Assertions outside tests or assertion helpers remain errors.
+
+Move custom native assertion-name overrides to `tests.additionalAssertionFunctions` (or scoped `modules/test-assertions` options through `policies.tests`). This is a static check, not proof that every execution reaches an assertion. Imported callbacks, dynamically constructed tables and cross-file helper bodies are not inferred; keep a direct assertion or register a reviewed imported assertion helper. Conditional assertions remain forbidden by the separate Vitest rule.
+
+Prefer a throwing assertion to conditional expectations when narrowing a discriminated result:
+
+```ts
+import { assert, expect } from 'vitest';
+
+const result = await service.run(params);
+
+assert(result.ok, 'Expected the operation to succeed');
+
+expect(result.data.ordersCreated).toBe(1);
+```
+
+`assert` fails the test and narrows the TypeScript type. No cast, custom unwrap helper or conditional expectation is needed. A prior success expectation followed by an `if` can be logically sound, but this form is simpler and keeps the conditional-expect rule enabled. Use `policies.tests` for native policy customization and `ignorePatterns` only when intentionally excluding tests from the entire lint run.
+
+### Framework migrations
+
+Migration files can have framework-required exports such as Kysely's `up`/`down`. Declare their exact scope instead of restructuring them into service factories:
+
+```ts
+export default preset({
+  modules: {
+    migrationFiles: ['apps/server/src/services/database/migrations/**/*.ts'],
+  },
+});
+```
+
+No migration paths are assumed by default. The supplied files are excluded from flat/domain folder-depth enforcement and the general service-functions/inline-signature scope. Formatting, naming, imports, type safety, constants and other rules still apply; this is not a whole-file ignore. Keep scopes narrow. In particular, `unknown` or framework-specific type exceptions require their own explicit `ruleExclusions`.
+
+### Exceptions and native customization
+
+Action/query files (`services/**/*-{action,query}.*.ts` under configured app roots) export exactly one named operation. Helpers used only by that operation may be private nested functions or arrows inside it. Extra exports, including types, constants and re-exports, fail. Module-level private helpers still fail. Backend service files retain the stricter helper policy; `.utils.ts` files are for genuinely shared domain helpers, not a destination for every extraction. The trivial-function rule still applies.
+
+Frontend `.client.ts`, `.server.ts` and `.rsc.{ts,tsx}` service entries are cohesive modules: multiple public domain-prefixed operations are allowed. No private module-level function satellites are allowed. Operation-only helpers stay nested inside their public operation and retain the domain prefix; genuinely shared helpers belong in domain `.utils.ts`. Factories are optional for real state, injection or lifetimes, and existing singleton exports remain valid. Do not export helpers just to evade this rule. Runtime suffix checks, React-free client checks and anti-slop rules remain enabled. A direct `export const themeService = { themeApply(...) { ... } }` is also allowed: a nonempty method-only object, static identifier keys, both binding and methods domain-prefixed. Data fields, getters/setters, strings/computed keys, spreads, arrow properties and callback-reference tables do not qualify. Returned factory API keys retain their existing contract. `allowServiceMethods` on domain-constants, `serviceMethods` on naming/object-parameter rules and `checkServiceMethods` on no-trivial-functions are enabled only for frontend runtime scopes; backend defaults remain unchanged. Object methods receive wrapper/generic-guard checks and named-parameter-contract rules. This is a syntax form, not proof that an object owns meaningful state.
+
+Frontend actions/queries retain their runtime suffix: `theme-action.apply.client.ts` exports exactly `themeActionApply`, not `themeActionApplyClient`. Related helpers stay inside that operation. Backend operations remain `domain-action.name.ts` / `domain-query.name.ts`, without runtime suffixes.
+
+Shared frontend domain helpers use `<domain>.utils.ts` in the configured services layout. Domain mode groups all runtime, utility, constants and action/query files under `services/<domain>/`; flat mode keeps all directly under `services/`. Utility functions, including private helpers, keep their domain prefix. Pure implementation does not make an application-specific helper portable: the preset enables `portableLib` in `modules/import-boundaries` for every configured web root. Files under `src/lib/` cannot import or re-export any configured app's services or app package APIs, including otherwise public backend entrypoints and type-only references. Backend library scopes retain their existing rules.
+
+A portable module may consume its own contract using a type-only import from exactly the same web root's `types/<module>.types.ts`. The module stem removes the source extension and optional `.utils` suffix: both `lib/fade.ts` and `lib/fade.utils.ts` may consume `types/fade.types.ts`. Value imports, other-domain types, same-stem types from another app, and app-type re-exports (including imported bindings subsequently exported) fail. Relative paths, the built-in `@/` alias and configured aliases use the same ownership check. This is a filename ownership convention, not transitive semantic portability proof: the rule does not inspect imported contracts or follow module graphs. Static imports/re-exports, literal dynamic imports and TypeScript import types are checked; computed imports and arbitrary alias/data flow are not resolved. Custom aliases must be configured explicitly. An own-type match never overrides a services/backend/API ban.
+
+The supporting rule's `portableLib` option defaults to `false` outside the preset for compatibility. Use the existing `policies.boundaries` callback, native overrides or file-specific `ruleExclusions['modules/import-boundaries']` for explicit consumer exceptions; an exclusion skips that rule's entire boundary check for the named file, so keep it narrow and documented.
+
+The preset's imports policy enables `arch/prefer-namespace-type-import` with `{ max: 3 }` for checked TypeScript files. Up to three named type imports stay named; four or more become a type namespace (for example, `BotTypes` from `bot.types`) with qualified references. The scope-aware autofix preserves aliases and rewrites only supported type references. Imports with namespace collisions, inline comments, local re-exports or unsupported reference syntax remain reported for manual review. Domain exports keep their names. Customize `max` or the rule's source-to-namespace `names` map through the existing `policies.imports` callback or a native override; file-specific exclusions remain available.
+
+Declare cohesive private concept roles with `modules: { customFileRoles: ['prompts'] }`. Built-in roles (`service`, `client`, `server`, `rsc`, `utils`, `action`, `query`, `types`, `constants`, `handler`, `test`, `spec`) cannot be redefined. A `route.prompts.ts` file may contain multiple builders, but every named function, including private functions, starts with the full `routePrompts` prefix. Arbitrary suffixes grant no exemption. Anti-slop checks remain enabled and comment exceptions remain explicit.
+
+With declared file roles, private service-domain files can be imported or re-exported only within their owning domain in the same app root. Cross-domain callers use service APIs (`.service`, `.client`, `.server`, `.rsc`) or genuinely shared `.utils`, types or constants. Public service/utility surfaces cannot re-export private internals, including private barrels; this checks export-from, export-star and directly imported bindings exported by name or namespace. Operations may use private concepts internally. This is a per-file surface contract, not a transitive module graph or arbitrary data-flow/alias analysis; do not move concept logic into utilities to evade ownership.
+
+`modules/service-functions` accepts `frontend`, `allowLocalHelpers`, `allowReturnedMethods`, `singleExport`, and `message` through the `policies.serviceStructure` callback or native overrides. The booleans default to `false` outside the preset's scoped overrides. `frontend: true` permits multiple public operations and their nested helpers; `singleExport: true` still requires exactly one operation. The preset enables frontend mode only for web runtime entries and applies the stricter single-export override to explicit actions/queries. The preset's diagnostic explains where helpers belong; consumers can replace `message` without disabling the rule.
+
+`ruleExclusions` disables only the named rule in the selected files, including rules enabled through several scopes. `ignorePatterns` adds whole-file ignores to the generated/build/dependency defaults.
+
+```ts
+export default preset({
+  ruleExclusions: {
+    'arch/no-trivial-functions': ['apps/web/src/services/adapter.client.ts'],
+    'modules/service-types': ['apps/server/src/services/portable-parser.ts'],
+  },
+  ignorePatterns: ['vendor/**'],
+});
+```
+
+Native composition remains available; later matching overrides can change an individual rule without a policy callback:
+
+```ts
+import { defineConfig } from 'oxlint';
+import preset from 'oxlint-plugin-arch/presets/tanstack-start-react-modules-preset';
+
+export default defineConfig({
+  options: { typeAware: true },
+  extends: [preset({ root: import.meta.dirname })],
+  overrides: [{
+    files: ['scripts/**/*.ts'],
+    rules: { 'unicorn/filename-case': 'off' },
+  }],
+});
+```
+
+Rule-specific inline disables are allowed with a reason after `--`. The preset does not force warnings to fail or define a CI/Fallow/compiler workflow.
+
+Oxlint reads `typeAware` from the root config only. The direct `export default preset(...)` form already sets it; when using `extends`, keep the explicit root option shown above.
+
+### Application conventions
+
+- Single quotes, semicolons, two spaces, braced multiline control flow, early returns, 160-character lines and 400-line app and test files. Promise arrays and call objects expand; method chains are not forced multiline.
+- Components live in one group folder with matching prefixed names. Hooks default to flat `use-*.ts` files; an explicit domain layout retains the hook filename convention. Local React types are prefixed interfaces; exported Props interfaces are allowed. Component props are never inline: every component `X` takes `interface XProps` declared directly above it, and local components carry the file prefix. Other types belong in domain `types/*.types.ts` files.
+- Backend operations use `domain-action.name.ts` / `domain-query.name.ts`. Services allow one domain folder, one exported operation without private helpers, object parameters and named signature types. Explicit `.utils.ts` files can hold generic helpers, but their types still belong in domain type files. Domain type and constant files cannot contain top-level functions. Frontend services use `.client.ts`, `.server.ts` or `.rsc.{ts,tsx}`. RSC JSX entries retain `domainRscName` exports and the same helper/constants policies.
+- Routes wire components, forms use a schema resolver, context creation has an owner directory, and effects cannot replace derived values or event handlers. React Compiler projects reject manual memoization. Test IDs are allowed. JSX rejects new object/function props inside render, and noninteractive elements cannot receive a tab index.
+- Safety rules reject unknown/any, chained assertions, unjustified assertions, loose dictionaries, module mocks, shared mutable bindings and focused/skipped/placeholder tests. Comments are limited to supported directives, SAFETY notes and explicit exceptions. Type/constant files do not allow SAFETY comments; prompt files require explicit comment exceptions. UI-kit code retains type-safety, formatting and layout checks.
+- Unbound methods and untyped mocks are rejected, including in tests. Console calls require an explicit script/CLI scope or adapter exclusion. Promise rejection callbacks must not receive implicit `any`; omitting the error parameter is allowed. App code needing an `unknown` boundary must use an explicit rule-specific exception.
+- Backend owns shared schemas and exposes a public client entry point; frontend type files are runtime-free. Packages cannot import app internals, RPC handlers delegate database work, and service dependencies are injected.
+
+Provide `orpc: { publicProcedureFiles: ['apps/server/src/rpc/api/**/*.ts'] }` for externally exposed oRPC endpoints requiring output schemas; exposure cannot be inferred from filenames or authentication. `imports.backendEntryPoints` defaults to `<backend package name>/client` read from each configured backend manifest. Configure it for another public import surface.
+
+For custom import aliases, supply `imports: { aliases: { '@backend': 'apps/server/src' } }`. Keys are import prefixes without wildcards, and values are directories relative to `root`. Boundary checks then treat `@backend/services/chat.service` like its relative path. `imports.internalSortPatterns` controls import sorting only.
+
+Native correctness defaults are promoted through `categories.correctness`; redundant rule entries are omitted after checking Oxlint's resolved configuration. Framework policies add the opinionated options on top. Other future presets can have their own named subpath under `/presets`; this factory does not enable any other preset.
+
+The preset has [paired CLI fixtures for every enabled rule](tests/fixtures/tanstack-start-react-modules/README.md), including Oxlint defaults, plus architecture and consumer-override scenarios. The coverage guard detects newly enabled rules without fixtures.
+
+The preset's supporting `modules/*` rules keep independent policies from overwriting one another: service type/factory matching, helper restrictions, import boundaries, reasoned lint directives, Shape-suffix names, empty effects, memoization and test modifiers. Dillon Mulroy's vendored [anti-slop rules](https://github.com/dmmulroy/anti-slop) live in `src/rules/dillon-anti-slop` and use the `dillon-anti-slop/*` namespace. They ship in this package; consumers do not need local plugin files. These supporting plugins are loaded by the preset, not registered by the generic plugin entry point.
+
 ## 📦 Install
 
 ```bash
@@ -65,7 +285,7 @@ export default defineConfig({
 | --- | --- |
 | [`minimal.oxlint.config.ts`](examples/minimal.oxlint.config.ts) | You want the smallest possible starting point. |
 | [`monorepo.oxlint.config.ts`](examples/monorepo.oxlint.config.ts) | ⭐ You are starting an `apps/server` + `apps/web` monorepo and want a strict, copy-ready setup. |
-| [`full.oxlint.config.ts`](examples/full.oxlint.config.ts) | You want to see every one of the 43 rules with its options. |
+| [`full.oxlint.config.ts`](examples/full.oxlint.config.ts) | You want to see every one of the 44 rules with its options. |
 
 > [!TIP]
 > `monorepo.oxlint.config.ts` already loads `oxlint-plugin-arch`, so you can copy it as-is and adjust globs and names. The other two load `../src/index.ts`; change that specifier to `oxlint-plugin-arch` when you copy them.
@@ -74,7 +294,7 @@ export default defineConfig({
 
 ## 🧩 Rules
 
-43 rules in 9 groups. 🔧 means the rule can autofix. Each rule file in [`src/rules/`](src/rules) explains its behavior in plain English, and the tests in [`src/tests/`](src/tests) show every option shape.
+44 rules in 9 groups. 🔧 means the rule can autofix. Each rule file in [`src/rules/`](src/rules) explains its behavior in plain English, and the tests in [`src/tests/`](src/tests) show every option shape.
 
 Options that take one regex string (`pattern`, `allowPattern`, `forbid`, `require`, and the other `*Pattern` options) also take a non-empty list; any pattern in the list may match. Options that were already lists, such as `allowPatterns` and `allowCallees`, are unchanged.
 
@@ -91,9 +311,9 @@ Options that take one regex string (`pattern`, `allowPattern`, `forbid`, `requir
 | Rule | What it enforces |
 | --- | --- |
 | `declaration-name` | Selected declarations start with a prefix taken from the filename, or match a pattern. |
-| `export-file-prefix` | Export names (or every function and type) start with the filename prefix. `trailingRoles` treats `onchain-utils.ts` like `onchain.utils.ts`. |
+| `export-file-prefix` | Names start with the filename prefix. `allFunctions` includes private functions; `allDeclarations` includes every declaration. `trailingRoles` handles role suffixes. |
 | `export-name-pattern` | Export names (or every function and type) match a regular expression. |
-| `filename-export-name` | Function names follow a template built from the filename. |
+| `filename-export-name` | Function names follow a template built from the filename. Set `camelCase: true` to convert lowercase placeholders such as `{domain}` from `user-profile` to `userProfile`; the default preserves captured text. |
 | `no-extra-exports` | A file exports only the names you allow. `patterns` accepts families such as `{Domain}[A-Z]\w*`. |
 | `only-export-constants` | Constant files export only local `const` values. [Details ↓](#only-export-constants) |
 
@@ -106,7 +326,7 @@ Options that take one regex string (`pattern`, `allowPattern`, `forbid`, `requir
 | `require-object-params` | Functions take object parameters instead of long positional lists. `maxParams: 2` allows `(deps, params)`. |
 | `no-file-level-helpers` | No stray helper functions at module scope. |
 | `no-top-level-functions` | No top-level functions (and optionally no re-exports) in matched files. |
-| `no-trivial-functions` | No empty or pass-through wrapper functions. `allowCallees` keeps intentional wrappers. |
+| `no-trivial-functions` | No empty/pass-through functions. `mode: 'precise'` preserves transformations and checks forbidden helper names and renamed generic guards. |
 | `no-module-mutable-state` | No module-level `let`/`var`, which is shared across requests and tests. |
 
 ### 🔷 Types
@@ -116,7 +336,7 @@ Options that take one regex string (`pattern`, `allowPattern`, `forbid`, `requir
 | `no-inline-types` | Function signatures use named types instead of inline `{ ... }` objects. [Details ↓](#no-inline-types) |
 | `no-type-declarations` | No type aliases or interfaces in matched files, so types live in one place. |
 | `no-runtime-in-types` | Type modules stay free of runtime code. Opt in to also ban runtime imports and re-exports. |
-| `no-imported-type-alias` | No exported aliases that only rename an imported type. |
+| `no-imported-type-alias` | No exported aliases that only rename an imported type; generic instantiations such as `Selectable<Table>` remain allowed. |
 | `prefer-namespace-type-import` 🔧 | Long type-only named imports become a namespace import with qualified references. [Details ↓](#prefer-namespace-type-import) |
 
 ### 🧪 Schemas & APIs
@@ -128,7 +348,7 @@ Options that take one regex string (`pattern`, `allowPattern`, `forbid`, `requir
 | `no-rederive-schema` | No re-deriving types from schemas imported from elsewhere. |
 | `no-single-use-scalar-schema` | Scalar Zod aliases used once get inlined. |
 | `require-orpc-output` | oRPC procedures declare a named `.output()` schema. |
-| `no-unescaped-like` | `LIKE` / `ILIKE` values pass through your sanitizer. |
+| `no-unescaped-like` | `LIKE` / `ILIKE` values pass through your sanitizer; optional `operatorMethods` covers calls such as `.where(column, 'like', value)`. |
 
 ### 🚧 Boundaries & safety
 
@@ -144,6 +364,7 @@ Options that take one regex string (`pattern`, `allowPattern`, `forbid`, `requir
 
 | Rule | What it enforces |
 | --- | --- |
+| `component-props` | Components type props with `interface XProps` declared directly above them; pass-through components may use `ComponentProps<'tag'>`. [Details ↓](#component-props) |
 | `only-export-components` | Component files export only components. `denyTypePattern: 'Props$'` keeps props private. |
 | `route-surface` | Route files export the route only, with no banned hooks or raw JSX. |
 
@@ -159,7 +380,7 @@ Options that take one regex string (`pattern`, `allowPattern`, `forbid`, `requir
 
 | Rule | What it enforces |
 | --- | --- |
-| `padding-between-statements` 🔧 | Blank lines around functions and classes, around control flow, and before `return` in longer blocks. |
+| `padding-between-statements` 🔧 | Blank lines around functions and classes, around control flow, and before `return` in longer blocks; `multilineVariables: true` also separates multiline declarations, including exports (default `false`). |
 | `object-multiline` 🔧 | Objects with 3+ properties passed to a call go one property per line (`scope: 'all'` for every object). |
 | `key-value-same-line` 🔧 | An object key and the start of its value stay on the same line. |
 | `chain-newline` 🔧 | Long method chains go one call per line. You pick which chains with `groups`. |
@@ -173,6 +394,56 @@ Options that take one regex string (`pattern`, `allowPattern`, `forbid`, `requir
 
 ## 🔍 Rule details
 
+### File size
+
+`limits.maxFileLines?: number` sets the existing ESLint `max-lines` ceiling on checked safety scopes; default `400`. Blank lines and comments remain skipped. Use native Oxlint overrides or the existing `ruleExclusions` configuration for deliberate per-file exceptions. File size is a ceiling, not a cohesion proof.
+
+### TanStack runtime boundaries
+
+`modules/tanstack-runtime` checks every configured web root's services and lib. Server dependencies include Node builtins (bare and `node:`), Bun/Cloudflare modules, `@orpc/server`, configured backend server/RPC APIs, `.server` files, TanStack server APIs/markers and React DOM server rendering. Known RSC renderer imports are checked by symbol; the entire mixed RSC package is not banned. Pure public backend client/schema imports remain governed by existing architecture rules.
+
+`.client.ts` is the preset's frontend-facing, potentially SSR-used service convention. Known server runtime dependencies require inline callbacks of scope-resolved imports of `createServerFn().handler`, `createServerOnlyFn`, `createMiddleware().server` or `createIsomorphicFn().server`. Alias/namespace imports are recognized; lookalike names and shadowed parameters are not. Static isomorphic server imports are allowed only in the actual configured RPC owner, and every runtime reference must stay in its server branch. Elsewhere that branch can load a literal dynamic import. Module-level execution and re-exports do not inherit the exception.
+
+`.server` files may statically import server implementation; dynamic loading alone proves nothing. RSC permits JSX, React and server-component definitions, but server renderer/dependency references still require a server callback. Server/RSC modules reject browser globals, local hook imports, client-only markers/APIs and React/TanStack client hooks outside recognized client branches. Global checks respect lexical shadowing and direct `globalThis.name` / literal-key access. Shared utilities/constants/lib cannot launder known server or client-only imports. Type-only imports/re-exports erase at runtime but retain all architecture restrictions.
+
+`tanstackStart.additionalServerOnlyImports` and `additionalClientOnlyImports` add package/module prefixes. `tanstackStart.computedImportAllowedFiles` permits computed imports only in explicitly named project-relative files; review all targets before using it. Other checks still run. This is direct syntax and lexical-reference enforcement, not an import graph, interprocedural alias analysis, sandbox, or proof of SSR safety. Wrapper factories, indirect callback references, re-exported framework factories and arbitrary computed member aliases are not recognized as boundary proofs. Native rule exclusions remain explicit consumer decisions.
+
+TanStack's [environment functions](https://tanstack.com/start/latest/docs/framework/react/guide/environment-functions) remove opposite branches, and [import protection](https://tanstack.com/start/latest/docs/framework/react/guide/import-protection) checks the resulting graph. Start's default import protection treats `.client.*` as browser-only, unlike this preset's service convention: SSR consumers must deliberately configure its server file pattern (Orbs uses `server.files: []`). Keep build-side protection enabled for server dependencies; lint does not replace it.
+
+### Private domain helpers and precise wrapper detection
+
+The preset requires all named functions in `room.utils.ts`, exported or private, to start with `room`, such as `roomUserIsOwner`. Private action/query helpers use the same domain prefix; the exported operation must exactly match its filename (`room-action.send-message.ts` → `roomActionSendMessage`). Ordinary local variables are unaffected. Standalone `export-file-prefix` users opt in with `allFunctions: true`.
+
+The preset enables `no-trivial-functions` with `mode: 'precise'`; standalone defaults retain legacy behavior. Precise mode rejects empty/constant/identity functions and unchanged-argument forwarding. Transformed arguments, query chains and interpolated prompts remain allowed. Nested generic runtime guards are checked too.
+
+Default exact banned names: `isRecord`, `isPlainObject`, `isObject`, `isString`, `isNumber`, `isBoolean`, `isArray`, `asRecord`, `asArray`. `bannedNames` replaces the list; `[]` disables name checks. `checkGenericGuards: false` disables structural checks. `allowPattern` exempts named helpers; `allowCallees` and `allowAsync` exempt wrappers only. No usage-count threshold, cross-file analysis or automatic rewrite is used.
+
+### `component-props`
+
+Every top-level React component with props, exported or local, must use exactly `interface XProps`, declared directly above the component with only blank lines between. A file with `ProbeCard` and `ProbeCardInline` declares `ProbeCardProps` above `ProbeCard` and `ProbeCardInlineProps` above `ProbeCardInline`. Inline object types always fail. Components without parameters pass. `memo` and `forwardRef` are unwrapped, and `forwardRef<Ref, XProps>` type arguments count as the props type. Hooks and functions that do not return JSX are ignored.
+
+A component that adds no props of its own may take a plain `ComponentProps<'header'>` or `ComponentProps<typeof Button>` instead of an empty `interface XProps extends ComponentProps<'header'> {}`. Once it adds, omits or intersects anything, it needs `XProps`.
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `filePrefix` | `false` | Local components with props must start with the filename prefix, so `XProps` also matches prefix rules such as `declaration-name`. In `rooms-chat-tools.tsx`, rename `RoomsChatTool` to `RoomsChatToolsItem`. |
+
+```ts
+// ✅ Pass
+interface ProbeCardProps extends ComponentProps<'button'> { tone: string }
+
+export function ProbeCard({ tone, ...rest }: ProbeCardProps) { return <button {...rest} /> }
+
+export function ProbeCardHeader(props: ComponentProps<'header'>) { return <header {...props} /> }
+
+// ❌ Fail: inline, wrong name, wrapped props
+export function ProbeCard({ title }: { title: string }) { return <h2>{title}</h2> }
+export function ProbeCard(props: ProbeCardOptions) { return <h2>{props.title}</h2> }
+export function ProbeCard(props: PropsWithChildren<ProbeCardProps>) { return props.children }
+```
+
+There is no autofix: moving an interface is a code change, not whitespace. It replaces `no-inline-types` for component files, which would also flag inline types on event handlers and callbacks inside components and cannot require the `XProps` name. The preset enables `filePrefix`.
+
 ### `no-inline-types`
 
 Requires named types in function signatures: local functions, callbacks, methods, constructors, and overloads. It checks explicit annotations only; inferred types, variable annotations, and generic constraints are left alone.
@@ -277,7 +548,7 @@ Keeps identifiers and member calls inside the files that own them.
 ```ts
 'arch/no-restricted-token': ['error', {
   restrictions: [
-    { token: 'RouterClient', allowIn: ['/src/services/rpc.client.ts'] },
+    { token: 'RouterClient', allowIn: ['/src/services/rpc/rpc.client.ts'] },
     { member: 'process.platform', allowIn: ['/src/runtime.ts'] },
     { member: '*.insertInto', message: 'Queries are read-only; move writes to an action.' },
   ],

package/dist/configs/boundaries.d.ts

@@ -0,0 +1,2 @@
+import type { PresetContext, PresetPolicies } from '../types/preset.types.ts';
+export declare function presetBoundariesConfig(context: PresetContext): PresetPolicies;

package/dist/configs/modules.d.ts

@@ -0,0 +1,2 @@
+import type { PresetContext, PresetPolicies } from '../types/preset.types.ts';
+export declare function presetModulesConfig(context: PresetContext): PresetPolicies;

package/dist/configs/plugins.d.ts

@@ -0,0 +1,3 @@
+import type { OxlintConfig } from 'oxlint';
+import type { PresetContext } from '../types/preset.types.ts';
+export declare function presetPluginsConfig(context: PresetContext): OxlintConfig;

package/dist/configs/react.d.ts

@@ -0,0 +1,2 @@
+import type { PresetContext, PresetPolicies } from '../types/preset.types.ts';
+export declare function presetReactConfig(context: PresetContext): PresetPolicies;

package/dist/configs/source.d.ts

@@ -0,0 +1,2 @@
+import type { PresetContext, PresetPolicies } from '../types/preset.types.ts';
+export declare function presetSourceConfig(context: PresetContext): PresetPolicies;

package/dist/configs/tests.d.ts

@@ -0,0 +1,2 @@
+import type { PresetContext, PresetPolicies } from '../types/preset.types.ts';
+export declare function presetTestsConfig(context: PresetContext): PresetPolicies;

package/dist/configs/types.d.ts

@@ -0,0 +1,2 @@
+import type { PresetContext, PresetPolicies } from '../types/preset.types.ts';
+export declare function presetTypesConfig(context: PresetContext): PresetPolicies;

package/dist/constants/preset.constants.d.ts

@@ -0,0 +1,28 @@
+import type { PresetRules, PresetPolicyName } from '../types/preset.types.ts';
+export declare const presetExtensions = "*.{ts,tsx,mts,cts}";
+export declare const presetPolicyOrder: PresetPolicyName[];
+export declare const presetCommonRules: PresetRules;
+export declare const presetFormattingRules: PresetRules;
+export declare const presetReactRules: PresetRules;
+export declare const presetEffectsRules: PresetRules;
+export declare const presetTailwindRules: {
+    'tailwindcss/enforce-canonical': "error";
+    'tailwindcss/enforce-sort-order': "error";
+    'tailwindcss/enforce-shorthand': "error";
+    'tailwindcss/no-conflicting-classes': "error";
+    'tailwindcss/no-duplicate-classes': "error";
+    'tailwindcss/no-unknown-classes': "off";
+    'tailwindcss/no-unnecessary-whitespace': "error";
+    'tailwindcss/no-deprecated-classes': "error";
+};
+export declare const presetImportRules: PresetRules;
+export declare const presetNamingRules: PresetRules;
+export declare const presetTestRules: PresetRules;
+export declare const presetExportPrefix: {
+    stem: string;
+    trailingRoles: string[];
+    roleSeparators: string[];
+    normalize: string;
+    allowPattern: string;
+};
+export declare const presetGeneratedFiles: string[];

package/dist/constants/test.constants.d.ts

@@ -0,0 +1 @@
+export declare const testAssertionFunctions: string[];