dlinter-ts-react 0.3.1 → 0.4.1

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
@@ -144,7 +159,9 @@ Every commit and release must pass the same architecture this package sells. Two
 
 ### 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 — 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.
+
+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.
 
 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).
 

package/dist/cli/index.mjs

@@ -52,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

@@ -1128,6 +1128,14 @@ 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/recommended.d.ts

package/dist/index.mjs

@@ -210,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$]*$`
 					}
 				}
 			},
@@ -525,28 +525,62 @@ const pluginBase = {
 	}
 };
 //#endregion
-//#region src/configs/severities.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".
-*/
-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/recommended.constants.ts
 /**
 * The @typescript-eslint plugin object types its rules more richly than core
 * ESLint's Plugin contract; the runtime shape is compatible.
 */
 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",
@@ -586,6 +620,21 @@ 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",
@@ -614,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,
@@ -656,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
 			}
 		},
 		{
@@ -675,6 +720,7 @@ function createRecommendedConfig(options = {}) {
 			files: ["**/*.ts", "**/*.tsx"],
 			plugins: { "@typescript-eslint": typescriptPlugin },
 			rules: {
+				...typescriptRecommendedRules,
 				"max-lines": ["error", {
 					max: 500,
 					skipBlankLines: true,
@@ -689,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 },
@@ -716,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" } : {}
 			}
 		},
 		{
@@ -791,7 +845,7 @@ function createRecommendedConfig(options = {}) {
 		},
 		{
 			files: ["src/**/use-*.ts"],
-			ignores: productionTestGlobs,
+			ignores: governedMainModuleExemptGlobs,
 			plugins: { dlinter: pluginBase },
 			rules: {
 				"dlinter/hook-anatomy": "error",
@@ -822,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.3.1",
+  "version": "0.4.1",
   "description": "Deterministic architecture governance for TypeScript + React projects: custom ESLint rules, architecture-concept presets, and pre-commit gate scaffolding.",
   "license": "MIT",
   "repository": {
@@ -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"
@@ -56,6 +57,7 @@
   "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",
@@ -72,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"
   }
 }