dlinter-ts-react 0.2.0 → 0.4.0

package/README.md

@@ -79,6 +79,7 @@ export default createRecommendedConfig({
 | `infrastructure` | `undefined` (rule off) | Import patterns + runtime globals that views must never touch directly |
 | `deliveryGlobs` | `['src/App.tsx', 'src/app/**/*.{ts,tsx}']` | Which files form the composition-only delivery layer |
 | `tsconfigPath` | `./tsconfig.json` | tsconfig used by the import resolver |
+| `reactCompiler` | `false` | Project compiles with React Compiler → `react-doctor/react-compiler-no-manual-memoization` activates at its upstream severity (manual memoization becomes redundant noise). Without the compiler it stays off — manual memoization is load-bearing |
 
 Presets are named after **architecture concepts** (`recommended`, `dumb-ui`), never after projects. Your project's specifics are options, not preset names.
 
@@ -90,9 +91,18 @@ Beyond the `dlinter/` rules, the preset composes the bundled ecosystem with prov
 - **`import-x`**: cycle detection (`no-cycle`), duplicate imports, TypeScript-aware resolution.
 - **`jsdoc/require-jsdoc`** on every exported function, interface, and type alias.
 - **`check-file`**: tests belong in `__tests__/`, feature folders are kebab-case, `utils.ts` is banned (name the role: `*.helpers.ts`).
-- **`sonarjs` + `react-doctor` as warnings** — advisory signal, never gate failures.
 - **`max-lines`**: 500 effective lines, hard error.
-- **`react-hooks`**: `rules-of-hooks` stays an error; nothing else replaces that safety net.
+- **`react-hooks`**: `rules-of-hooks` blocks (zero false positives; violations corrupt React's hook order at runtime). `exhaustive-deps` is deliberately advisory — its documented false-positive patterns would force worse code or disable-comments at `error`.
+
+### Upstream severities are respected, never blanket-downgraded
+
+Every bundled plugin whose recommended config the preset spreads keeps **its own author's per-rule triage** — that triage is exactly the work this package does for you, and sweeping a whole ruleset to `warn` would throw it away. Only *named* rules are re-tuned, each with a documented reason in the source:
+
+- **`@typescript-eslint`** — the recommended tier (20 definite-bug rules at `error`: `no-explicit-any`, `no-misused-new`, `no-unsafe-function-type`, …) applies to all TypeScript. The **type-checked tier** (`no-floating-promises`, `no-misused-promises`, `await-thenable`, the `no-unsafe-*` family) runs on production `src/**` through the TypeScript project service — **your tsconfig must cover `src/`**. Tests are exempt (mock-assertion patterns are documented `unbound-method` misfires).
+- **`sonarjs`** — upstream ships 206 bug and security rules at `error` and they block as-is, including `cognitive-complexity`, `no-identical-functions`, and `no-nested-conditional` (kept at `error` so the ESLint gate and a Fallow audit agree on one standard) and `prefer-read-only-props` (kept for SonarQube Cloud parity — it coexists with `dlinter/readonly-props`, which additionally governs `*.types.ts` contracts and needs no type information). Surgical exceptions, each with a reason: `todo-tag`/`fixme-tag` warn instead of blocking tracked work, `pseudo-random` warns (Math.random is legitimate for non-crypto frontend uses), `no-unused-vars` is off because `@typescript-eslint` owns that contract with the underscore convention. In test files only the fake-credential rules go quiet — mirroring SonarQube Cloud's reduced test-file profile — while `no-exclusive-tests` keeps guarding your suite.
+- **`react-doctor`** — 34 upstream `error` rules block (definite bugs and a11y: `jsx-key`, `no-direct-mutation-state`, `require-render-return`, `alt-text`, the `aria-*` set…); ~198 heuristics stay warnings. Sole override: `react-compiler-no-manual-memoization` is off by default and returns at upstream severity via `createRecommendedConfig({ reactCompiler: true })`.
+
+Each spread plugin is **pinned to an exact version**, and a drift test locks its upstream error-set (`src/configs/__tests__/upstream-severity-contracts/`) — a bump that changes the set fails CI and forces a deliberate re-triage, never silent drift.
 
 ## CLI
 
@@ -110,17 +120,22 @@ Scaffolds `lefthook.yml` with a lint + typecheck + test pre-commit gate. Never o
 | `typescript` | `>=5.0.0 <6.1.0` — TypeScript 7 (native) is not yet supported by `@typescript-eslint`; the ceiling moves when the ecosystem does |
 | `node` | `>=20.19.0` |
 
+The type-checked rule tier builds a real TypeScript program via the project service: every file under `src/` must be covered by a `tsconfig.json` (the nearest one to each file wins). A standard `"include": ["src"]` already satisfies this.
+
 ## Design principles
 
 | Principle | In practice |
 |-----------|-------------|
 | First-class rules, never selector catalogs | `no-restricted-syntax` is a single rule slot consumers can silently override; every constraint here has its own rule ID, its own docs, and per-rule disable |
 | Don't reinvent the wheel | Existing plugins are bundled wheels (`max-lines`, `check-file`, `import-x`, …). Custom rules exist only for contracts no plugin ships — e.g. conditional folder ownership, pure-barrel enforcement |
+| Respect upstream triage, never blanket-downgrade | A bundled plugin's own per-rule severities are the plugin author's triage — honored as-is. Only specific rule IDs are re-tuned, each with a documented reason; a drift test locks the upstream error-set so a version bump forces a deliberate re-triage instead of silent drift. Bulk-demoting a whole ruleset is the exact config archaeology this package exists to spare consumers |
 | Tests are the proof | Every rule is TDD-built with RED/GREEN `RuleTester` cases; presets are tested through a real `ESLint` instance; releases are gated by installing the actual tarball into a fresh consumer project |
 | Validated against production | The full preset reproduces the source system's lint verdicts at exact file:line parity (30/30) on the codebase it was extracted from |
 
 ## Development
 
+Contributor and agent documentation lives in [`docs/`](./docs/README.md) — architecture (with diagrams), the severity policy and its override ledger, the add-a-rule recipe, and the testing harnesses.
+
 ```bash
 bun install
 bun run test        # vitest: RuleTester per rule + ESLint-instance integration harness
@@ -132,13 +147,23 @@ bun run validate    # typecheck + test
 
 The repo self-hosts its own gate (lefthook: fallow audit + typecheck + test). Contributions follow strict TDD — a rule without a failing test proving it fires is a disabled rule — and conventional commits.
 
+### Self-governance
+
+This package enforces its own rules on itself. A permanent test (`src/__tests__/self-governance.test.ts`, part of `bun run validate`) lints `src/**` with the universal subset of the shipped rules — strict colocation, folder ownership, pure barrels, exported-variable JSDoc, `max-lines` — plus a layer contract on import direction:
+
+```
+src/index.ts → src/configs/ → src/plugin.ts → src/rules/     (src/cli/ is a standalone bin)
+```
+
+Every commit and release must pass the same architecture this package sells. Two documented exceptions: rule modules are exported const objects (the ESLint plugin contract requires it), and the package entrypoints (`main`, `bin`) are composition modules, not barrels.
+
 ### Releasing
 
-Releases are automated with [release-please](https://github.com/googleapis/release-please): conventional commits on `main` drive the next semver (`fix:` → patch, `feat:` → minor, `feat!:`/`BREAKING CHANGE:` → major). The bot maintains a Release PR with the computed version and CHANGELOG; **merging that PR** cuts the GitHub release and publishes to npm with provenance — after the tarball end-to-end gate passes.
+Code lands on `main` only through **feature-branch pull requests** — `main` is protected and rejects direct pushes, so CI and SonarCloud analyze the real diff on every change. See [docs/release-and-ci.md](./docs/release-and-ci.md) for branch protection, CI, and the CI-based Sonar setup.
 
-Manual escape hatch: pushing a `v*` tag triggers the same publish pipeline directly.
+Releases are automated with [release-please](https://github.com/googleapis/release-please): the conventional commits merged into `main` drive the next semver (`fix:` → patch, `feat:` → minor, `feat!:`/`BREAKING CHANGE:` → major). The bot maintains a Release PR with the computed version and CHANGELOG; **merging that PR** cuts the GitHub release and publishes to npm — after the tarball end-to-end gate passes.
 
-Requires the `NPM_TOKEN` secret in the repository settings.
+Publishing authenticates via [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC): no tokens, nothing to rotate, provenance built in. The trusted publisher is configured in the package settings on npmjs.com, bound to this repository's `release-please.yml` workflow. Emergency escape hatch: publish locally with `npm publish` (2FA OTP applies).
 
 ## Roadmap
 

package/dist/cli/index.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { existsSync, writeFileSync } from "node:fs";
 import path from "node:path";
-//#region src/cli/init.ts
+//#region src/cli/init/init.constants.ts
+/** Default lefthook pre-commit gate scaffolded into consumer projects. */
 const lefthookTemplate = `pre-commit:
   parallel: false
   jobs:
@@ -14,6 +15,8 @@ const lefthookTemplate = `pre-commit:
     - name: test
       run: npm run test
 `;
+//#endregion
+//#region src/cli/init/init.ts
 /**
 * Scaffolds the dlinter pre-commit gate into a consumer project. Existing
 * files are never overwritten — a hand-tuned gate always wins over the template.
@@ -49,9 +52,12 @@ async function main() {
 	for (const file of result.created) process.stdout.write(`created ${file}\n`);
 	for (const file of result.skipped) process.stdout.write(`skipped ${file} (already exists)\n`);
 }
-main().catch((error) => {
-	process.stderr.write(`dlinter failed: ${error.message}\n`);
+try {
+	await main();
+} catch (error) {
+	const message = error instanceof Error ? error.message : String(error);
+	process.stderr.write(`dlinter failed: ${message}\n`);
 	process.exitCode = 1;
-});
+}
 //#endregion
 export {};

package/dist/index.d.mts

@@ -1106,7 +1106,7 @@ interface Directive {
   justification?: string;
 }
 //#endregion
-//#region src/configs/recommended.types.d.ts
+//#region src/configs/recommended/recommended.types.d.ts
 /**
  * Consumer-defined infrastructure edge: which import specifiers and runtime
  * globals count as "infrastructure" that views must never touch directly.
@@ -1128,9 +1128,17 @@ interface RecommendedConfigOptions {
   readonly deliveryGlobs?: readonly string[];
   /** tsconfig used by the import resolver. Default: `./tsconfig.json`. */
   readonly tsconfigPath?: string;
+  /**
+   * The project compiles with React Compiler. Activates
+   * `react-doctor/react-compiler-no-manual-memoization` at its upstream
+   * severity (manual `useMemo`/`useCallback` become redundant noise once the
+   * compiler memoizes). Default `false`: without the compiler, manual
+   * memoization is load-bearing and the rule would only mislead.
+   */
+  readonly reactCompiler?: boolean;
 }
 //#endregion
-//#region src/configs/recommended.d.ts
+//#region src/configs/recommended/recommended.d.ts
 /**
  * Builds the full governance preset: bundled third-party plugin stack plus
  * every dlinter architecture rule, composed with the glob topology proven in

package/dist/index.mjs

@@ -1,6 +1,5 @@
 import tsParser from "@typescript-eslint/parser";
 import js from "@eslint/js";
-import tsPlugin from "@typescript-eslint/eslint-plugin";
 import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
 import checkFilePlugin from "eslint-plugin-check-file";
 import { createNodeResolver, importX } from "eslint-plugin-import-x";
@@ -11,6 +10,7 @@ import reactHooksPlugin from "eslint-plugin-react-hooks";
 import sonarjsPlugin from "eslint-plugin-sonarjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
+import tsPlugin from "@typescript-eslint/eslint-plugin";
 //#region src/configs/dumb-ui.ts
 /**
 * Dumb UI preset: every `.tsx` file is presentational. Side effects live in
@@ -33,9 +33,13 @@ function createDumbUiConfig(plugin) {
 	}];
 }
 //#endregion
-//#region src/rules/composition-only-delivery.ts
+//#region src/rules/composition-only-delivery/composition-only-delivery.constants.ts
+/** Matches every built-in React hook name, including bare `use`. */
 const reactHookNamePattern = "^use(State|Reducer|Effect|LayoutEffect|InsertionEffect|SyncExternalStore|Memo|Callback|Ref|Context|Transition|DeferredValue|ImperativeHandle|DebugValue|Id|Optimistic|ActionState)?$";
+/** Matches module specifiers that resolve to a custom `use-*` hook file. */
 const customHookModulePattern = /(^|\/)use-[^/]+$/u;
+//#endregion
+//#region src/rules/composition-only-delivery/composition-only-delivery.ts
 /**
 * Delivery Layer Rule: delivery files (App.tsx, app/**) compose feature
 * entrypoints — they never orchestrate. No React hooks, no custom hook
@@ -76,13 +80,16 @@ const compositionOnlyDelivery = {
 	}
 };
 //#endregion
-//#region src/rules/folder-ownership.ts
+//#region src/rules/folder-ownership/folder-ownership.constants.ts
+/** Role-file suffixes a split main module may own next to its entrypoint. */
 const roleSuffixes = [
 	".constants.ts",
 	".helpers.ts",
 	".schema.ts",
 	".types.ts"
 ];
+//#endregion
+//#region src/rules/folder-ownership/folder-ownership.ts
 /**
 * Split Module Ownership Rule: when a main module splits into role files
 * (`*.helpers.ts`, `*.types.ts`, `*.constants.ts`, `*.schema.ts`), the whole
@@ -124,8 +131,11 @@ const folderOwnership = {
 	}
 };
 //#endregion
-//#region src/rules/hook-anatomy.ts
+//#region src/rules/hook-anatomy/hook-anatomy.constants.ts
+/** Selector prefix targeting the body of every exported `use*` hook declaration. */
 const hookBlock = "ExportNamedDeclaration > FunctionDeclaration[id.name=/^use[A-Z0-9]/] > BlockStatement";
+//#endregion
+//#region src/rules/hook-anatomy/hook-anatomy.ts
 /**
 * Hook Anatomy Rule: exported hooks follow one ordering — derived state
 * (useMemo) before callbacks (useCallback) before effects (useEffect) — and
@@ -200,7 +210,7 @@ const noInfrastructureInView = {
 					type: "array",
 					items: {
 						type: "string",
-						pattern: "^[A-Za-z_$][\\w$]*\\.[A-Za-z_$][\\w$]*$"
+						pattern: String.raw`^[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*$`
 					}
 				}
 			},
@@ -243,8 +253,11 @@ const noInfrastructureInView = {
 	}
 };
 //#endregion
-//#region src/rules/no-view-effects.ts
+//#region src/rules/no-view-effects/no-view-effects.constants.ts
+/** Matches the React effect hooks that are forbidden inside view components. */
 const effectHookPattern = /^use(?:Effect|LayoutEffect)$/u;
+//#endregion
+//#region src/rules/no-view-effects/no-view-effects.ts
 /**
 * Dumb UI Rule: view components (.tsx) must stay presentational. Side effects
 * belong in the colocated `use-*.ts` hook, never in the view itself.
@@ -299,8 +312,11 @@ const pureIndexBarrel = {
 	}
 };
 //#endregion
-//#region src/rules/readonly-props.ts
+//#region src/rules/readonly-props/readonly-props.constants.ts
+/** Selector fragment matching parameters annotated with a bare `*Props` type reference. */
 const propsBoundary = "[typeAnnotation.typeAnnotation.type=\"TSTypeReference\"][typeAnnotation.typeAnnotation.typeName.name=/Props$/]";
+//#endregion
+//#region src/rules/readonly-props/readonly-props.ts
 /**
 * Type Contract Rule: component props are immutable. Parameters use
 * `Readonly<Props>` at the function boundary, and every field of a `*Props`
@@ -366,7 +382,11 @@ const requireExportedVariableJsdoc = {
 	}
 };
 //#endregion
-//#region src/rules/strict-colocation.ts
+//#region src/rules/strict-colocation/strict-colocation.constants.ts
+/**
+* Every check id the rule can enforce; the `checks` option narrows this set
+* for role files that legitimately own a subset of declaration kinds.
+*/
 const allChecks = [
 	"root-variable",
 	"root-helper-function",
@@ -376,13 +396,86 @@ const allChecks = [
 	"inline-type-alias",
 	"zod-import"
 ];
+/** Matches `zod` itself and any `zod/*` subpath import. */
 const zodImportPattern = /^zod(?:\/.*)?$/u;
 //#endregion
+//#region src/rules/strict-colocation/strict-colocation.helpers.ts
+/**
+* Collects every identifier a module exports through specifier statements —
+* `export default App` and `export { App }` — so root function declarations
+* exported that way are recognized as main modules rather than helpers.
+*/
+function collectSpecifierExportedNames(program) {
+	const names = /* @__PURE__ */ new Set();
+	for (const statement of program.body) {
+		if (statement.type === "ExportDefaultDeclaration" && statement.declaration.type === "Identifier") names.add(statement.declaration.name);
+		if (statement.type === "ExportNamedDeclaration" && statement.declaration === null) {
+			for (const specifier of statement.specifiers) if (specifier.local.type === "Identifier") names.add(specifier.local.name);
+		}
+	}
+	return names;
+}
+/**
+* Builds the visitor fragment owned by each check id; the rule merges the
+* fragments for whichever checks its options enable.
+*/
+function createCheckVisitors(context) {
+	return {
+		"root-variable": { "Program > VariableDeclaration": (node) => {
+			context.report({
+				node,
+				messageId: "rootVariable"
+			});
+		} },
+		"root-helper-function": { "Program > FunctionDeclaration": (node) => {
+			if (node.type === "FunctionDeclaration" && node.parent.type === "Program") {
+				const exportedNames = collectSpecifierExportedNames(node.parent);
+				if (node.id !== null && exportedNames.has(node.id.name)) return;
+			}
+			context.report({
+				node,
+				messageId: "rootHelperFunction"
+			});
+		} },
+		"exported-const": { "Program > ExportNamedDeclaration > VariableDeclaration": (node) => {
+			context.report({
+				node,
+				messageId: "exportedConst"
+			});
+		} },
+		"default-arrow-export": { "Program > ExportDefaultDeclaration > ArrowFunctionExpression": (node) => {
+			context.report({
+				node,
+				messageId: "defaultArrowExport"
+			});
+		} },
+		"inline-interface": { TSInterfaceDeclaration: (node) => {
+			context.report({
+				node,
+				messageId: "inlineInterface"
+			});
+		} },
+		"inline-type-alias": { TSTypeAliasDeclaration: (node) => {
+			context.report({
+				node,
+				messageId: "inlineTypeAlias"
+			});
+		} },
+		"zod-import": { ImportDeclaration: (node) => {
+			if (node.type === "ImportDeclaration" && zodImportPattern.test(String(node.source.value))) context.report({
+				node,
+				messageId: "zodImport"
+			});
+		} }
+	};
+}
+//#endregion
 //#region src/plugin.ts
 /**
-* Plugin core shared by every preset: metadata plus the dlinter rule registry.
-* Presets receive this object so config factories never import the package
-* entrypoint back (which would create a module cycle).
+* Plugin core shared by every preset: metadata plus the dlinter rule registry
+* keyed by published rule name. Presets receive this object so config
+* factories never import the package entrypoint back (which would create a
+* module cycle).
 */
 const pluginBase = {
 	meta: {
@@ -423,73 +516,72 @@ const pluginBase = {
 			create(context) {
 				const configuredChecks = context.options[0]?.checks ?? allChecks;
 				const enabled = new Set(configuredChecks);
+				const checkVisitors = createCheckVisitors(context);
 				const visitor = {};
-				if (enabled.has("root-variable")) visitor["Program > VariableDeclaration"] = (node) => {
-					context.report({
-						node,
-						messageId: "rootVariable"
-					});
-				};
-				if (enabled.has("root-helper-function")) visitor["Program > FunctionDeclaration"] = (node) => {
-					context.report({
-						node,
-						messageId: "rootHelperFunction"
-					});
-				};
-				if (enabled.has("exported-const")) visitor["Program > ExportNamedDeclaration > VariableDeclaration"] = (node) => {
-					context.report({
-						node,
-						messageId: "exportedConst"
-					});
-				};
-				if (enabled.has("default-arrow-export")) visitor["Program > ExportDefaultDeclaration > ArrowFunctionExpression"] = (node) => {
-					context.report({
-						node,
-						messageId: "defaultArrowExport"
-					});
-				};
-				if (enabled.has("inline-interface")) visitor["TSInterfaceDeclaration"] = (node) => {
-					context.report({
-						node,
-						messageId: "inlineInterface"
-					});
-				};
-				if (enabled.has("inline-type-alias")) visitor["TSTypeAliasDeclaration"] = (node) => {
-					context.report({
-						node,
-						messageId: "inlineTypeAlias"
-					});
-				};
-				if (enabled.has("zod-import")) visitor["ImportDeclaration"] = (node) => {
-					if (node.type === "ImportDeclaration" && zodImportPattern.test(String(node.source.value))) context.report({
-						node,
-						messageId: "zodImport"
-					});
-				};
+				for (const check of allChecks) if (enabled.has(check)) Object.assign(visitor, checkVisitors[check]);
 				return visitor;
 			}
 		}
 	}
 };
 //#endregion
-//#region src/configs/severities.ts
+//#region src/configs/recommended/recommended.constants.ts
 /**
-* Re-emits a rules map with every active severity downgraded to "warn".
-* Used to surface advisory plugins (react-doctor) as warnings instead of hard
-* errors that would break the gate on pre-existing patterns.
-* @param rules - source rules map keyed by rule name.
-* @returns the same rules with non-off severities set to "warn".
+* The @typescript-eslint plugin object types its rules more richly than core
+* ESLint's Plugin contract; the runtime shape is compatible.
 */
-function downgradeRuleSeverities(rules) {
-	return Object.fromEntries(Object.entries(rules).map(([ruleName, ruleValue]) => {
-		if (ruleValue === "off" || ruleValue === 0) return [ruleName, "off"];
-		if (Array.isArray(ruleValue)) return [ruleName, ["warn", ...ruleValue.slice(1)]];
-		return [ruleName, "warn"];
-	}));
-}
-//#endregion
-//#region src/configs/recommended.ts
 const typescriptPlugin = tsPlugin;
+const tsPluginConfigs = tsPlugin.configs;
+/**
+* @typescript-eslint's recommended (non-type-checked) rules — the plugin's own
+* per-rule triage (20 definite-bug rules at "error"), spread as-is across all
+* maintained TypeScript. The error-set is locked by the drift test in
+* upstream-severity-drift.test.ts; the plugin is pinned to an exact version.
+*/
+const typescriptRecommendedRules = tsPluginConfigs["recommended"]?.rules ?? {};
+/**
+* @typescript-eslint's type-checked-only tier — the highest-value bug rules a
+* real TypeScript program unlocks (no-floating-promises, no-misused-promises,
+* await-thenable, the no-unsafe-* family), upstream severities respected
+* as-is. Applied only where the project service can build a program
+* (production src); locked by the same drift test.
+*/
+const typescriptTypeCheckedOnlyRules = tsPluginConfigs["recommended-type-checked-only"]?.rules ?? {};
+/**
+* sonarjs' recommended rules — the plugin author's per-rule triage (206 rules
+* at "error", 62 off upstream), spread AS-IS. The preset never
+* blanket-downgrades a bundled plugin: only the named rules in
+* sonarjsSurgicalOverrides are re-tuned, each with a documented reason. The
+* upstream error-set is locked by the drift test and sonarjs is pinned exact.
+*/
+const sonarjsRecommendedRules = sonarjsPlugin.configs.recommended?.rules ?? {};
+/**
+* Surgical severity overrides for sonarjs' recommended set — the ONLY rules
+* re-tuned from upstream, each a deliberate decision with a reason. Everything
+* else in the 206-rule error tier blocks, exactly as sonarjs triaged it.
+*/
+const sonarjsSurgicalOverrides = {
+	"sonarjs/fixme-tag": "warn",
+	"sonarjs/todo-tag": "warn",
+	"sonarjs/no-unused-vars": "off",
+	"sonarjs/pseudo-random": "warn"
+};
+/**
+* sonarjs rules that misfire specifically on test code: fixtures legitimately
+* contain fake credentials, fake secrets, and literal IPs. This MIRRORS
+* SonarQube Cloud behavior — files under `sonar.tests` get a reduced rule
+* profile there and these main-code rules do not run on them — so local
+* verdicts and Cloud verdicts stay aligned. Everything else in sonarjs stays
+* ON in tests — no-exclusive-tests, no-skipped-tests, and the assertion rules
+* earn their keep there.
+*/
+const sonarjsTestContextOverrides = {
+	"sonarjs/hardcoded-secret-signatures": "off",
+	"sonarjs/no-hardcoded-ip": "off",
+	"sonarjs/no-hardcoded-passwords": "off",
+	"sonarjs/no-hardcoded-secrets": "off"
+};
+/** Extensions the import-x node resolver probes when resolving specifiers. */
 const importXExtensions = [
 	".js",
 	".jsx",
@@ -497,15 +589,20 @@ const importXExtensions = [
 	".tsx",
 	".d.ts"
 ];
+/** Globs identifying test files, which stay outside the architecture contract. */
 const productionTestGlobs = [
 	"**/__tests__/**/*.{ts,tsx}",
 	"**/*.test.{ts,tsx}",
 	"src/test/**/*.{ts,tsx}",
 	"test/**/*.{ts,tsx}"
 ];
+/** Globs for repository automation scripts that run under Node. */
 const nodeScriptGlobs = ["scripts/**/*.{js,mjs,cjs}"];
+/** Globs for application source that runs in the browser. */
 const sourceBrowserGlobs = ["src/**/*.{ts,tsx,js,jsx}"];
+/** Files exempt from the public-documentation contract: tests and documented-invalid fixtures. */
 const documentationExemptGlobs = [...productionTestGlobs, "**/*.invalid.{ts,tsx,js,jsx}"];
+/** Files that are not governed main modules: exempt files plus barrels and role files. */
 const governedMainModuleExemptGlobs = [
 	...documentationExemptGlobs,
 	"**/index.ts",
@@ -514,6 +611,7 @@ const governedMainModuleExemptGlobs = [
 	"**/*.schema.ts",
 	"**/*.types.ts"
 ];
+/** AST selector contexts that `jsdoc/require-jsdoc` treats as public documentation surface. */
 const documentationContexts = [
 	"ExportNamedDeclaration > FunctionDeclaration",
 	"ExportNamedDeclaration > TSInterfaceDeclaration",
@@ -522,6 +620,22 @@ const documentationContexts = [
 	"ExportDefaultDeclaration > ArrowFunctionExpression",
 	"ExportDefaultDeclaration > CallExpression > ArrowFunctionExpression"
 ];
+/**
+* Surgical severity overrides for react-doctor's recommended set.
+*
+* POLICY — never blanket-downgrade a third-party plugin's ruleset. react-doctor
+* already triages every rule it ships (upstream: 34 error / 198 warn), and that
+* per-rule judgment is exactly the work this package exists to do for consumers.
+* The preset therefore spreads react-doctor's recommended rules AS-IS and
+* overrides ONLY the specific rule IDs that genuinely misfire in this
+* architecture — each entry below is a deliberate decision with a documented
+* reason, not a bulk sweep. The upstream error-set is locked by a drift test
+* (`recommended.test.ts`), and react-doctor is pinned to an exact version, so
+* the set cannot shift silently: a bump that changes it fails CI and forces a
+* re-triage here.
+*/
+const reactDoctorSurgicalOverrides = { "react-doctor/react-compiler-no-manual-memoization": "off" };
+/** Full dlinter rule map at severity "off" — the final reset applied to test files. */
 const allDlinterRulesOff = {
 	"dlinter/composition-only-delivery": "off",
 	"dlinter/folder-ownership": "off",
@@ -533,6 +647,8 @@ const allDlinterRulesOff = {
 	"dlinter/require-exported-variable-jsdoc": "off",
 	"dlinter/strict-colocation": "off"
 };
+//#endregion
+//#region src/configs/recommended/recommended.ts
 /**
 * Builds the full governance preset: bundled third-party plugin stack plus
 * every dlinter architecture rule, composed with the glob topology proven in
@@ -547,7 +663,6 @@ function createRecommendedConfig(options = {}) {
 		importPatterns: [...options.infrastructure.importPatterns],
 		runtimeGlobals: [...options.infrastructure.runtimeGlobals]
 	}] : "off";
-	const reactDoctorWarnRules = downgradeRuleSeverities(reactDoctor.configs.recommended.rules);
 	return [
 		js.configs.recommended,
 		importX.flatConfigs.recommended,
@@ -589,11 +704,8 @@ function createRecommendedConfig(options = {}) {
 				"import-x/no-cycle": ["error", { maxDepth: 1 }],
 				"import-x/no-duplicates": "error",
 				"import-x/no-unresolved": "error",
-				"sonarjs/cognitive-complexity": ["warn", 15],
-				"sonarjs/no-all-duplicated-branches": "warn",
-				"sonarjs/no-identical-functions": "warn",
-				"sonarjs/no-redundant-boolean": "warn",
-				"sonarjs/no-small-switch": "warn"
+				...sonarjsRecommendedRules,
+				...sonarjsSurgicalOverrides
 			}
 		},
 		{
@@ -608,6 +720,7 @@ function createRecommendedConfig(options = {}) {
 			files: ["**/*.ts", "**/*.tsx"],
 			plugins: { "@typescript-eslint": typescriptPlugin },
 			rules: {
+				...typescriptRecommendedRules,
 				"max-lines": ["error", {
 					max: 500,
 					skipBlankLines: true,
@@ -622,6 +735,13 @@ function createRecommendedConfig(options = {}) {
 				}]
 			}
 		},
+		{
+			files: ["src/**/*.{ts,tsx}"],
+			ignores: productionTestGlobs,
+			languageOptions: { parserOptions: { projectService: true } },
+			plugins: { "@typescript-eslint": typescriptPlugin },
+			rules: { ...typescriptTypeCheckedOnlyRules }
+		},
 		{
 			files: productionTestGlobs,
 			plugins: { "@typescript-eslint": typescriptPlugin },
@@ -649,8 +769,9 @@ function createRecommendedConfig(options = {}) {
 			ignores: productionTestGlobs,
 			plugins: { "react-doctor": reactDoctor },
 			rules: {
-				...reactDoctorWarnRules,
-				"react-doctor/react-compiler-no-manual-memoization": "off"
+				...reactDoctor.configs.recommended.rules,
+				...reactDoctorSurgicalOverrides,
+				...options.reactCompiler ? { "react-doctor/react-compiler-no-manual-memoization": reactDoctor.configs.recommended.rules["react-doctor/react-compiler-no-manual-memoization"] ?? "warn" } : {}
 			}
 		},
 		{
@@ -741,7 +862,11 @@ function createRecommendedConfig(options = {}) {
 			files: ["src/**/*.helpers.ts"],
 			ignores: productionTestGlobs,
 			plugins: { dlinter: pluginBase },
-			rules: { "dlinter/strict-colocation": ["error", { checks: ["inline-interface", "inline-type-alias"] }] }
+			rules: { "dlinter/strict-colocation": ["error", { checks: [
+				"root-variable",
+				"inline-interface",
+				"inline-type-alias"
+			] }] }
 		},
 		{
 			files: productionTestGlobs,
@@ -751,7 +876,8 @@ function createRecommendedConfig(options = {}) {
 			},
 			rules: {
 				...allDlinterRulesOff,
-				"jsdoc/require-jsdoc": "off"
+				"jsdoc/require-jsdoc": "off",
+				...sonarjsTestContextOverrides
 			}
 		}
 	];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dlinter-ts-react",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Deterministic architecture governance for TypeScript + React projects: custom ESLint rules, architecture-concept presets, and pre-commit gate scaffolding.",
   "license": "MIT",
   "repository": {
@@ -25,7 +25,7 @@
     }
   },
   "bin": {
-    "dlinter": "./dist/cli/index.mjs"
+    "dlinter": "dist/cli/index.mjs"
   },
   "files": [
     "dist"
@@ -35,6 +35,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "validate": "bun run typecheck && bun run test",
     "e2e:pack": "node ./scripts/pack-e2e.mjs",
     "prepublishOnly": "bun run validate && bun run build"
@@ -54,7 +55,9 @@
     "typescript": ">=5.0.0 <6.1.0"
   },
   "devDependencies": {
+    "@types/estree": "^1.0.9",
     "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.6.0",
     "fallow": "^3.3.0",
     "lefthook": "^2.1.10",
@@ -71,8 +74,8 @@
     "eslint-plugin-import-x": "^4.17.1",
     "eslint-plugin-jsdoc": "^63.0.13",
     "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-doctor": "^0.7.4",
+    "eslint-plugin-react-doctor": "0.7.4",
     "eslint-plugin-react-hooks": "^7.1.1",
-    "eslint-plugin-sonarjs": "^4.1.0"
+    "eslint-plugin-sonarjs": "4.1.0"
   }
 }