@peerigon/configs 14.6.0 → 14.8.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [14.8.0](https://github.com/peerigon/configs/compare/v14.7.0...v14.8.0) (2026-03-16)
+
+### Features
+
+- **ai:** Apply best practices from "A Philosophy of Software Design" ([ad5f17d](https://github.com/peerigon/configs/commit/ad5f17dfc6534196fb65813682a2a429f7eb0495))
+
+# [14.7.0](https://github.com/peerigon/configs/compare/v14.6.0...v14.7.0) (2026-03-16)
+
+### Features
+
+- **ai:** Improve agent instructions for large repos ([89e8298](https://github.com/peerigon/configs/commit/89e82983d9a13439cc75e90b41cc2f13c345b5c8))
+- Update dependencies ([ee6e1ed](https://github.com/peerigon/configs/commit/ee6e1ed3fc64563792437ab102e0dacbc9e6ca24))
+
 # [14.6.0](https://github.com/peerigon/configs/compare/v14.5.0...v14.6.0) (2026-03-15)
 
 ### Features

package/ai/README.md

@@ -12,6 +12,9 @@ Put this in your project-specific rules file (like `CLAUDE.md`, `.cursor/rules.m
 **Important**: You **must** follow [these rules](./node_modules/@peerigon/configs/ai/rules.mdc) and its language-specific rules referenced in that file.
 ```
 
+For large repositories, we recommend maintaining a repo-level routing document at `docs/agent-routing.md` to help agents find the right entrypoints quickly.
+You can start from [`agent-routing.example.md`](./agent-routing.example.md) and adapt it to your needs.
+
 ## Migration Guide
 
 [`migrate-to.md`](./migrate-to.md) provides step-by-step instructions for coding agents for migrating projects to use `@peerigon/configs`.

package/ai/agent-routing.example.md

@@ -0,0 +1,41 @@
+# Agent Routing
+
+Use this file as a fast index for coding agents in large repositories. Keep entries short and practical.
+
+## Scope
+
+Describe the repository purpose in 2-4 lines.
+
+## Quick task map
+
+- "<task type>" -> `<path-a>`, `<path-b>`, `<path-c>`
+- "Add or modify API endpoint" -> `src/api/*`, `src/routes/*`, `tests/api/*`
+- "UI component change" -> `src/components/*`, `src/pages/*`, `*.stories.*`
+- "Build or release change" -> `package.json`, `.github/workflows/*`, `semantic-release/*`
+
+## Entry points by area
+
+### Authentication
+
+- Start reading: `src/auth/index.ts`
+- Core flow: `src/auth/service.ts`
+- Tests: `src/auth/*.test.ts`
+
+### Data layer
+
+- Start reading: `src/db/client.ts`
+- Migrations: `db/migrations/*`
+- Contract tests: `tests/db/*`
+
+## Validation commands
+
+- Unit (scoped): `npm run test -- <path>`
+- Types: `npm run test:types`
+- Lint: `npm run test:lint`
+- Full: `npm test && npm run build`
+
+## Known traps
+
+- "Import style is extensionless in app packages."
+- "Feature flags are defined in `src/flags.ts`."
+- "Integration tests require `.env.test`."

package/ai/coding-styleguide-js-ts.mdc

@@ -8,6 +8,7 @@ globs: **/*.js, **/*.ts, **/*.mjs, **/*.cjs, **/*.mts, **/*.cts
 - Use TypeScript. If .js files are requested, use JSDoc type annotations
 - Prefer functional over imperative
 - Prefer immutability
+- **Priority rule (MUST)**: order every file by importance. Start with the primary logic and keep less important helpers/details at the end.
 
 ## Formatting
 
@@ -16,17 +17,21 @@ globs: **/*.js, **/*.ts, **/*.mjs, **/*.cjs, **/*.mts, **/*.cts
 ## Imports & exports
 
 - Use ESM unless you're editing a CommonJS file
-- Use file extensions in import specifiers. Use .ts extension in TypeScript files.
+- Follow the consuming repository's established import-specifier convention (extensions vs extensionless; `.js` vs `.ts` in TypeScript source files)
+- Determine convention from nearby files and configuration before introducing new imports
+- Keep import style consistent within a module/package; avoid mixed styles unless already established
+- If conventions are unclear or conflicting, ask the user before changing or introducing import-specifier style
 - Avoid default imports and default exports
 - Avoid barrel files (index files that only re-export) unless its a package entry file
 
 ## File structure
 
-- Begin with a `@module` overview JSDoc comment (**not** for test or config files)
+- Do not add a file header comment by default
+- For complex or high-impact files only, add a short context comment near the top (3-6 lines) that explains purpose, where to start reading, and non-obvious caveats
 - Then imports
 - Then important top-level constants or variables
-- Then order by importance (in relation to the file purpose): the most important classes/functions of the file should be at the beginning
-- Unimportant helper functions and variables should be at the bottom of the file
+- Then order by importance (in relation to the file purpose): the file **must** start with its most important classes/functions
+- Move unimportant helper functions, variables, and secondary details to the bottom of the file
 - Exception: when module execution requires a function to be defined before it is used, define it earlier
 
 ## Naming Conventions
@@ -95,7 +100,9 @@ globs: **/*.js, **/*.ts, **/*.mjs, **/*.cjs, **/*.mts, **/*.cts
 
 ## Comments
 
-- Use JSDoc comments and its tags where appropriate
+- Use comments to explain why, invariants, constraints, and non-obvious trade-offs
+- Do not write comments that only restate what the code already makes obvious
+- Add short contract comments only for complex or high-impact exports. Focus on purpose, guarantees, and important caveats.
 
 ## Testing
 

package/ai/coding-styleguide-react.mdc

@@ -9,6 +9,7 @@ globs: **/*.tsx, **/*.jsx
 - Inline component props next to the component prop argument
 - Derive state where possible
 - Avoid unnecessary `useState` and `useEffect`
-- `useEffect` **must** contain an async function call (unless it's a synchronous browser api like `localStorage`)
+- Use `useEffect` only when synchronizing with external systems (for example browser APIs, subscriptions, timers, network interactions)
+- Keep effects small, deterministic, and cleanup-safe
 - Avoid `useMemo` and `useCallback` unless its absolutely necessary
 - Create a story for each React component if Storybook is used

package/ai/coding-styleguide-testing.mdc

@@ -7,7 +7,7 @@ globs: **/*.test.js, **/*.test.ts, **/*.test.tsx
 
 ## General principle
 
-**Important**: Write as less tests as possible while covering all relevant scenarios. Focus on testing the behavior of the code rather than implementation details.
+**Important**: Aim for the smallest high-value test set that protects behavior, interface contracts, invariants, and regression-prone paths. Focus on testing behavior rather than implementation details.
 
 ## Structure & Organization
 

package/ai/rules.mdc

@@ -14,6 +14,12 @@ alwaysApply: true
 - Prefer explicit over implicit
 - Keep code close together that belongs together
 
+## Complexity and module design
+
+- Treat complexity as the primary enemy. Prefer designs that reduce mental load, special cases, and cross-module coupling.
+- Prefer deep modules with shallow interfaces: expose minimal API surface and hide implementation details by default.
+- Avoid pass-through abstractions that add layers but do not hide meaningful complexity.
+
 ## JavaScript & TypeScript
 
 See [Coding Styleguide JavaScript & TypeScript](./coding-styleguide-js-ts.mdc)
@@ -33,9 +39,34 @@ See [Coding Styleguide Shell Scripts](./coding-styleguide-sh.mdc)
 ## Development Practices
 
 - Breakdown complex tasks into smaller, manageable todos and write them down to a dedicated TODO file
-- Aim for small pull-requests. Each TODO should be a single pull-request. Use stacked PRs.
+- Aim for small, reviewable pull-requests. Split work into logical units, and use stacked PRs when scope or risk justifies incremental review.
 - Write unit tests for simple, pure functions
-- Unit test files are colocated with source files (*.test.ts)
+- Unit test files are colocated with source files (\*.test.ts)
 - Write integration or e2e tests for more complex functions/classes/components
-- Run the linter and type checker only once after the implementation is complete and the tests are passing
-- Adjust documentation both in comments and markdown files once you're done
+- Prefer staged validation for non-trivial tasks: run focused checks after meaningful changes, then run broader lint/type/test checks before handoff. For trivial tasks, a single final validation is acceptable.
+- Adjust documentation both in comments and markdown files once you're done
+
+## Consumer-repo uncertainty protocol
+
+Some guidance depends on the consuming repository's runtime and toolchain (module resolution, transpilation, bundler, test runner).
+
+- First infer conventions from local evidence:
+  - nearby files and existing import style
+  - tsconfig compiler options
+  - eslint and import rules
+  - package scripts and build tooling
+- If evidence is insufficient or conflicting, ask one concise question before changing conventions.
+- Do not silently introduce a new convention in a mixed or unknown setup.
+- If no answer is possible, follow the closest existing local convention and explicitly document the assumption.
+
+## Repo-level routing system
+
+To reduce exploration cost in large repositories, use a repo-level routing document.
+
+- Preferred path in consuming repositories: `docs/agent-routing.md` (or the nearest existing equivalent).
+- Use `@peerigon/configs/ai/agent-routing.example.md` as a starting structure and adapt it to the consuming repository.
+- At task start, check whether routing exists.
+- If routing is missing and the task is non-trivial, create an initial routing file before implementation. If local policy may restrict docs changes, ask one concise question first.
+- Use routing-first navigation: read the relevant routing section before broad codebase exploration.
+- Keep routing concise and practical. Update it when better entrypoints, caveats, or validation commands are discovered.
+- Do not duplicate full architecture docs. Routing should be an index for fast task orientation.

package/dist/eslint/rules/react.js

@@ -2,7 +2,6 @@
 import reactPlugin2 from "@eslint-react/eslint-plugin";
 import jsxA11yPlugin from "eslint-plugin-jsx-a11y";
 import reactPlugin from "eslint-plugin-react";
-import reactCompilerPlugin from "eslint-plugin-react-compiler";
 import reactHooksPlugin from "eslint-plugin-react-hooks";
 import reactRefreshPlugin from "eslint-plugin-react-refresh";
 import reactYouMightNotNeedAnEffect from "eslint-plugin-react-you-might-not-need-an-effect";
@@ -66,28 +65,9 @@ export const react = [
             ],
         },
     },
-    // There's currently no official recommended flat config for react-hooks.
-    // TODO: Use recommended config when it's available.
     {
         files,
-        plugins: {
-            "react-hooks": reactHooksPlugin,
-        },
-        rules: {
-            "react-hooks/rules-of-hooks": "error",
-            "react-hooks/exhaustive-deps": "warn",
-        },
-    },
-    // There's currently no official recommended flat config for react-compiler.
-    // TODO: Use recommended config when it's available.
-    {
-        files,
-        plugins: {
-            "react-compiler": reactCompilerPlugin,
-        },
-        rules: {
-            "react-compiler/react-compiler": "error",
-        },
+        ...reactHooksPlugin.configs.flat.recommended,
     },
     {
         files,

package/dist/eslint/rules/react.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/eslint/rules/react.test.js

@@ -0,0 +1,8 @@
+import assert from "node:assert/strict";
+import reactHooksPlugin from "eslint-plugin-react-hooks";
+import { react } from "./react.js";
+const reactHooksConfigs = react.filter((config) => config.rules &&
+    typeof config.rules === "object" &&
+    "react-hooks/rules-of-hooks" in config.rules);
+assert.equal(reactHooksConfigs.length, 1, "react config should include exactly one react-hooks recommended config entry");
+assert.deepEqual(reactHooksConfigs[0]?.rules, reactHooksPlugin.configs.flat.recommended.rules, "react config should mirror eslint-plugin-react-hooks flat recommended rules");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peerigon/configs",
-  "version": "14.6.0",
+  "version": "14.8.0",
   "description": "Configs for ESLint, Prettier, TypeScript & friends",
   "keywords": [
     "eslint",
@@ -79,25 +79,24 @@
   },
   "dependencies": {
     "@eslint-react/eslint-plugin": "^2.13.0",
-    "@eslint/compat": "^2.0.2",
+    "@eslint/compat": "^2.0.3",
     "@eslint/js": "^9.39.1",
     "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
     "@prettier/plugin-oxc": "^0.1.3",
-    "@sebbo2002/semantic-release-jsr": "^3.2.0",
+    "@sebbo2002/semantic-release-jsr": "^3.2.1",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
     "@tanstack/eslint-plugin-query": "^5.91.4",
     "@types/eslint-config-prettier": "^6.11.3",
     "@types/eslint-plugin-jsx-a11y": "^6.10.1",
-    "@vitest/eslint-plugin": "^1.6.9",
+    "@vitest/eslint-plugin": "^1.6.12",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-no-only-tests": "^3.3.0",
-    "eslint-plugin-playwright": "^2.8.0",
+    "eslint-plugin-playwright": "^2.10.0",
     "eslint-plugin-prefer-arrow": "^1.2.3",
     "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-compiler": "^19.1.0-rc.2",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.2",
     "eslint-plugin-react-you-might-not-need-an-effect": "^0.9.1",
@@ -105,18 +104,18 @@
     "globals": "^17.4.0",
     "prettier-plugin-css-order": "^2.2.0",
     "prettier-plugin-jsdoc": "^1.8.0",
-    "prettier-plugin-packagejson": "^3.0.0",
+    "prettier-plugin-packagejson": "^3.0.2",
     "prettier-plugin-tailwindcss": "^0.7.2",
-    "typescript-eslint": "^8.56.0"
+    "typescript-eslint": "^8.57.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
     "@types/signale": "^1.4.7",
     "eslint": "^9.39.1",
     "husky": "^9.1.7",
-    "lint-staged": "^16.3.1",
+    "lint-staged": "^16.4.0",
     "npm-run-all2": "^8.0.4",
     "pin-github-action": "^3.4.0",
     "prettier": "^3.8.1",