@peerigon/configs 14.5.0 → 14.7.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [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
+
+- **eslint:** Disable no-unreachable-loop in tests ([4638cb2](https://github.com/peerigon/configs/commit/4638cb20ca44cd2455319138141b51ef08299e55))
+
 # [14.5.0](https://github.com/peerigon/configs/compare/v14.4.0...v14.5.0) (2026-03-10)
 
 ### 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

package/ai/rules.mdc

@@ -33,9 +33,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
+- 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/javascript.js

@@ -151,6 +151,8 @@ export const javascript = [
             "max-nested-callbacks": "off",
             // await in loops is pretty common in Playwright tests
             "no-await-in-loop": "off",
+            // Unreachable loops are sometimes used in tests to assert loop body runs at most once
+            "no-unreachable-loop": "off",
             // In case you want to test errors thrown by a constructor
             "no-new": "off",
             // Generators without yield are common in test helpers/setup

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.5.0",
+  "version": "14.7.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",