@peerigon/configs 7.0.2 → 7.1.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# [7.1.0](https://github.com/peerigon/configs/compare/v7.0.2...v7.1.0) (2025-08-20)
+
+### Features
+
+- Add rules and instructions for AI coding agents ([#146](https://github.com/peerigon/configs/issues/146)) ([4fda35c](https://github.com/peerigon/configs/commit/4fda35c49ee8fe92559a88ffacc4dbce198fb32c)), closes [/#diff-31d17094bc63f56f4b4cc27a6e7d78e7b0a33b2a7d810f06a77f5f5814a32223R1-R77](https://github.com///issues/diff-31d17094bc63f56f4b4cc27a6e7d78e7b0a33b2a7d810f06a77f5f5814a32223R1-R77) [/#diff-687239070a6068b383fc9aab0bfacfc80b3ff2c1df6055e7f0273328b597e6d0R1-R160](https://github.com///issues/diff-687239070a6068b383fc9aab0bfacfc80b3ff2c1df6055e7f0273328b597e6d0R1-R160) [/#diff-f8bfdc4142ab84261ba9c23bfc9afeff1f98ee71da689ef951311cd54130f928R1-R14](https://github.com///issues/diff-f8bfdc4142ab84261ba9c23bfc9afeff1f98ee71da689ef951311cd54130f928R1-R14) [/#diff-97953bd7f578928372e273b64f032d3bb832202e334ea65cc2926ae1c3c27534R1-R17](https://github.com///issues/diff-97953bd7f578928372e273b64f032d3bb832202e334ea65cc2926ae1c3c27534R1-R17) [/#diff-5193a148ebdd2baf23b4f0a1c1add7ea02a8b92fb022e3a5780e886509d06693L25-R25](https://github.com///issues/diff-5193a148ebdd2baf23b4f0a1c1add7ea02a8b92fb022e3a5780e886509d06693L25-R25) [/#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519R44](https://github.com///issues/diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519R44)
+
 ## [7.0.2](https://github.com/peerigon/configs/compare/v7.0.1...v7.0.2) (2025-08-05)
 
 ### Bug Fixes

package/README.md

@@ -22,6 +22,16 @@ Also checkout the instructions for each respective config:
 - [Semantic release](/semantic-release/README.md)
 - [VSCode](/.vscode/README.md)
 
+### AI
+
+Furthermore, this package also contains [rules and instructions for AI coding agents](./ai/README.md) that are based on the configurations.
+
+If you want your AI coding agent to stick to our configs and coding principles, put this in your project-specific rules file (like `CLAUDE.md`, `.cursor/rules.mdc`, etc.):
+
+```md
+**Important**: You **must** follow [these rules](./node_modules/@peerigon/configs/ai/rules.mdc) and its language-specific rules referenced in that file.
+```
+
 ## Philosophy
 
 Linting, formatting and type-checking rules are always a balance between:

package/ai/README.md

@@ -0,0 +1,17 @@
+# AI
+
+Contains resources and styleguides for coding agents.
+
+## Coding agent rules
+
+[`rules.mdc`](./rules.mdc) contains Peerigon's universal coding principles and links to language-specific guides.
+
+Put this in your project-specific rules file (like `CLAUDE.md`, `.cursor/rules.mdc`, etc.):
+
+```md
+**Important**: You **must** follow [these rules](./node_modules/@peerigon/configs/ai/rules.mdc) and its language-specific rules referenced in that file.
+```
+
+## 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/coding-styleguide-html-css.mdc

@@ -0,0 +1,160 @@
+---
+description: HTML and CSS best practices with accessibility focus
+globs: **/*.html, **/*.htm, **/*.css, **/*.scss, **/*.sass, **/*.less, **/*.tsx, **/*.jsx, **/*.vue
+---
+
+# HTML & CSS
+
+## HTML
+
+### Semantic Elements
+
+Use semantic elements like `header`, `nav`, `main`, `article`, `section`, `aside`, `footer`, `figure`, `time` when content has inherent meaning:
+
+```html
+<article>
+  <h1>Breaking News</h1>
+  <time datetime="2025-01-15">January 15, 2025</time>
+</article>
+```
+
+### Form Labels
+
+Every input requires an associated label. Prefer wrapping the `input` with `label`. Otherwise use `for`/`id` (when using React, call `useId()`):
+
+```html
+<!-- Good -->
+<label for="user-email">Email Address</label>
+<input type="email" id="user-email" name="email" />
+
+<!-- Better -->
+<label>
+  Email Address:
+  <input type="email" name="email" />
+</label>
+```
+
+### Buttons vs. Links
+
+Use buttons for actions, links for navigation:
+
+```html
+<button type="button" onclick="saveData()">Save</button>
+<a href="/next">Next</a>
+```
+
+### Image Alt Text
+
+Provide descriptive alt text for content images, empty alt for decorative images:
+
+```html
+<img src="chart.png" alt="Sales increased 23% in Q4 2024" />
+<img src="decoration.png" alt="" />
+```
+
+## CSS
+
+### Selectors and naming
+
+Use purpose-based named classes for styling with a maximum of 3 levels specificity.
+
+```css
+.site-header {
+}
+.card {
+}
+.error-message {
+}
+.feature-highlight {
+}
+```
+
+Check what styling solution (CSS Modules, BEM, Tailwind, ...) is used in the project and follow its conventions.
+
+### Units
+
+Use typography units like `rem`, `ch`, ... for typography-related spacing:
+
+```css
+font-size: 1.125rem;
+```
+
+Use `px` for everything else:
+
+```css
+border: 1px solid #ccc;
+```
+
+## Accessibility
+
+### Focus Indicators
+
+Provide visible focus for all interactive elements:
+
+```css
+button:focus {
+  outline: 2px solid #007bff;
+  outline-offset: 2px;
+}
+```
+
+### Color Information
+
+Never use color alone to convey information. Use text labels or patterns to supplement color.
+
+### Motion Preferences
+
+Respect reduced motion preferences:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+### ARIA Usage
+
+- Only use ARIA when HTML semantics are insufficient.
+- Use ARIA for custom components without HTML equivalents.
+- Use `aria-label` when visible text is insufficient:
+
+```html
+<button aria-label="Close dialog">×</button>
+```
+
+Use `aria-describedby` for help text:
+
+```html
+<input type="password" aria-describedby="password-help" />
+<div id="password-help">Must be at least 8 characters</div>
+```
+
+### Screen Reader Content
+
+Use visually hidden class for screen reader only content:
+
+```css
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  white-space: nowrap;
+  clip-path: inset(50%);
+}
+```
+
+### Font Loading
+
+Use `font-display: swap` for web fonts:
+
+```css
+@font-face {
+  src: url("font.woff2") format("woff2");
+  font-family: "CustomFont";
+  font-display: swap;
+}
+```

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

@@ -0,0 +1,83 @@
+---
+description: JavaScript and TypeScript best practices and conventions
+globs: **/*.js, **/*.ts, **/*.mjs, **/*.cjs, **/*.mts, **/*.cts
+---
+
+# JavaScript & TypeScript
+
+- Use TypeScript. If .js files are requested, use JSDoc type annotations
+- Prefer functional over imperative
+- Prefer immutability
+
+## Formatting
+
+- Use Prettier's default formatting
+
+## Imports & exports
+
+- Use ESM unless you're editing a CommonJS file
+- Use file extensions in import specifiers. Use .ts extension in TypeScript files.
+- Avoid default imports and default exports
+- Avoid barrel files (index files that only re-export) unless its a package entry file
+
+## Naming Conventions
+
+- `camelCase` for variables, functions, methods
+- `PascalCase` for classes, enums and React components
+- `SCREAMING_SNAKE_CASE` for build-time constants
+- `kebab-case` for file names, CSS classes and DOM ids
+- Stick to existing naming conventions if present (e.g. `camelCase` and `PascalCase` for file names)
+- Use specific names instead of unspecific abbreviations like `obj`, `arr` and `err`
+- Only use abbreviations when they are widely used like `Api`
+- Abbreviations should be treated as separate words (e.g. `Api` instead of `API`)
+- Use short names when the variable or function is private and only accessible in the current file
+- Use longer and more specific names when the variable or function is exported and visible across the whole project
+- Use auxiliary verbs (e.g., isLoading, hasError) for boolean variables and type guards
+
+## Syntax
+
+- Use `const` by default, `let` when necessary
+- Use template literals for string interpolation
+- Prefer `undefined` over `null`
+- Destructure objects and arrays, especially when using default values
+- Use optional chaining (`?.`) and nullish coalescing (`??`) instead of `||`
+
+## Control flow
+
+- Use early returns to eliminate error and edge cases
+- Use assert functions to assert assumptions
+- Prefer simple if statements and avoid negated if statements where possible
+- Keep indentation level low and avoid more than 5 levels of nesting
+
+## Error handling
+
+- Write descriptive error messages and include error context (e.g. actual vs. expected values)
+- Use try-catch blocks sparingly and only when you can actually handle the error
+- Consider using Result types for operations that can fail
+
+## Functions
+
+- Use arrow functions unless there is no appropriate syntax like function overloads or generators
+- Use objects as parameters when there are more than 2 parameters
+- Keep functions small and focused on single responsibility
+- Write pure functions when possible
+- Optimize function names for readability on the call side
+
+## Types
+
+- Use strict mode
+- Only use `interface` for interfaces that are intended to be implemented by a `class`
+- Use `type` for all other cases, especially object types
+- Use the generic notation for types (e.g. `Array<string>` instead of `string[]`)
+- Do not use `any` to fix type errors. Search for a better alternative.
+- If you have to use `any`, try with `unknown` first
+- [Parse, don't validate](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/). Lift types into higher-level, special types as soon as they have been parsed (e.g. prefer explicit string literals over just `string`)
+- Infer types (using type utilities like `Pick`, `Omit`, ...) instead of duplicating them
+- Prefer `satisfies` over type declarations
+- Use explicit return types for functions when the function is exported and the return type is not a literal or when it has high cyclomatic complexity
+- Use erasable syntax only
+- **Important**: Use descriptive type parameter names in generic types, do not use single letter type parameter names
+
+## Testing
+
+See [Coding Styleguide Testing](./coding-styleguide-testing.mdc)

package/ai/coding-styleguide-react.mdc

@@ -0,0 +1,14 @@
+---
+description: React best practices and patterns
+globs: **/*.tsx, **/*.jsx
+---
+
+# React
+
+- Use arrow functions for components
+- 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`)
+- Avoid `useMemo` and `useCallback` unless its absolutely necessary
+- Create a story for each React component if Storybook is used

package/ai/coding-styleguide-sh.mdc

@@ -0,0 +1,17 @@
+---
+description: Shell scripting best practices
+globs: **/*.sh, **/*.bash, **/*.zsh
+---
+
+# Shell scripts
+
+- Prepend all shell scripts with
+
+```sh
+set -o errexit  # exit when there was a single error
+set -o pipefail # fail when there was a pipe error
+set -o nounset  # fail when an env variable is not set
+```
+
+- Make sure that shell scripts also work when file names contain spaces
+- Prefer commands that work on Linux, MacOS and Windows WSL

package/ai/coding-styleguide-testing.mdc

@@ -0,0 +1,46 @@
+---
+description: Best practices and conventions for testing JavaScript and TypeScript code
+globs: **/*.test.js, **/*.test.ts, **/*.test.tsx
+---
+
+# Testing
+
+## 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.
+
+## Structure & Organization
+
+- Hierarchical grouping: Use nested describe() blocks - outer for function/class, inner for scenarios
+- Logical categorization: Group by behavior, input type, or state (e.g., "with valid input", "error handling")
+- Each it() should test a single behavior
+
+## Test Coverage
+
+- Happy path: Test expected behavior with typical inputs
+- Edge cases: Test boundaries, empty values, maximum/minimum values
+- Error scenarios: Test all failure modes with proper error type/message validation
+- Type variations: Test all relevant data types (primitives, objects, arrays, functions)
+- Falsy values: Explicitly test null, undefined, 0, "", false, NaN
+
+## Type Safety
+
+- Type annotations: Include explicit types in test variables to verify inference
+- Compile-time checks: Some tests exist just to verify type compatibility
+
+## Best Practices
+
+- Descriptive names: Use clear it() descriptions stating expected behavior
+- Avoid "should" phrasing in it(): Use verbs like "does" or "returns" to describe behavior
+- Isolation: Each test should be independent and not rely on others
+- Arrange-Act-Assert: Follow AAA pattern for test structure
+- DRY with helpers: Extract repetitive setup into helper functions
+- Use real-life examples and descriptive names for test data
+
+## Assertions
+
+- Prefer `.toMatchObject()` over `.toEqual()` for object/array content checks
+- Do not over-assert: Only include relevant data into the expected value using `.toMatchObject()`
+- Check for reference equality only if it matters for the test
+- Multiple assertions: Group related checks in single test when testing same behavior
+- Use `.toThrowErrorMatchingInlineSnapshot()` for exact error messages

package/ai/migrate-to.md

@@ -0,0 +1,25 @@
+I want to migrate this module to use @peerigon/configs. Follow the instructions to install the configs:
+
+- [ESLint](https://github.com/peerigon/configs/blob/main/eslint/README.md)
+- [Prettier](https://github.com/peerigon/configs/blob/main/prettier/README.md)
+- [TypeScript](https://github.com/peerigon/configs/blob/main/typescript/README.md)
+- [Semantic release](https://github.com/peerigon/configs/blob/main/semantic-release/README.md)
+- [VSCode](https://github.com/peerigon/configs/blob/main/.vscode/README.md)
+
+Before writing code, plan the migration first. The migration should be done in granular steps, each step with its own PR.
+
+## Step 1: Add VSCode setting
+
+Read https://github.com/peerigon/configs/blob/main/.vscode/README.md for instructions how to add the vscode settings
+
+## Step 2: (Libraries only) Migrate semantic-release
+
+Only do this step if the project is a library (i.e. the `package.json` contains a `main` or `exports` field). Read https://github.com/peerigon/configs/blob/main/semantic-release/README.md for instructions how to configure semantic-release.
+
+## Step 3: Migrate prettier
+
+Read https://github.com/peerigon/configs/blob/main/prettier/README.md for instructions how to configure prettier. Before finishing the PR, format all files with the new prettier configuration.
+
+## Step 4: Migrate ESLint and TypeScript
+
+Read https://github.com/peerigon/configs/blob/main/typescript/README.md for instructions how to configure TypeScript. Run a type check after configuring TypeScript correctly. Read https://github.com/peerigon/configs/blob/main/eslint/README.md for instructions how to configure ESLint. Run the linter after configuring ESLint correctly.

package/ai/rules.mdc

@@ -0,0 +1,41 @@
+---
+description: Rules for coding agents to follow
+globs: **/*
+alwaysApply: true
+---
+
+# Coding Styleguide
+
+## Universal Principles
+
+- Write idiomatic, self-documenting code with clear, descriptive names
+- Optimize for readability
+- Use names consistently
+- Prefer explicit over implicit
+- Keep code close together that belongs together
+
+## JavaScript & TypeScript
+
+See [Coding Styleguide JavaScript & TypeScript](./coding-styleguide-js-ts.mdc)
+
+## HTML & CSS
+
+See [Coding Styleguide HTML & CSS](./coding-styleguide-html-css.mdc)
+
+## React
+
+See [Coding Styleguide React](./coding-styleguide-react.mdc)
+
+## Shell scripts
+
+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.
+- Write unit tests for simple, pure functions
+- 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peerigon/configs",
-  "version": "7.0.2",
+  "version": "7.1.0",
   "description": "Configs for ESLint, Prettier, TypeScript & friends",
   "keywords": [
     "eslint",
@@ -41,6 +41,7 @@
   },
   "files": [
     "dist",
+    "ai",
     "CHANGELOG.md",
     "README.md"
   ],
@@ -65,10 +66,10 @@
     "release": "semantic-release"
   },
   "dependencies": {
-    "@eslint-react/eslint-plugin": "^1.52.3",
-    "@eslint/compat": "^1.3.1",
+    "@eslint-react/eslint-plugin": "^1.52.5",
+    "@eslint/compat": "^1.3.2",
     "@eslint/js": "^9.32.0",
-    "@ianvs/prettier-plugin-sort-imports": "^4.5.1",
+    "@ianvs/prettier-plugin-sort-imports": "^4.6.2",
     "@prettier/plugin-oxc": "^0.0.4",
     "@sebbo2002/semantic-release-jsr": "^3.0.1",
     "@semantic-release/changelog": "^6.0.3",
@@ -90,23 +91,23 @@
     "prettier-plugin-jsdoc": "^1.3.3",
     "prettier-plugin-packagejson": "^2.5.19",
     "prettier-plugin-tailwindcss": "^0.6.14",
-    "typescript-eslint": "^8.38.0"
+    "typescript-eslint": "^8.39.1"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.2.0",
+    "@types/node": "^24.2.1",
     "@types/react": "^19.1.9",
     "@types/signale": "^1.4.7",
-    "eslint": "^9.32.0",
+    "eslint": "^9.33.0",
     "husky": "^9.1.7",
-    "lint-staged": "^16.1.4",
+    "lint-staged": "^16.1.5",
     "npm-run-all2": "^8.0.4",
     "pin-github-action": "^3.4.0",
     "prettier": "^3.6.2",
     "react": "^19.1.1",
     "rimraf": "^6.0.1",
     "semantic-release": "^24.2.7",
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.2"
   },
   "peerDependencies": {
     "eslint": "^9.21.0",