@kirill.konshin/lint 0.4.8 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -8
- package/dist/configs/imports.js +1 -1
- package/dist/configs/react.d.ts.map +1 -1
- package/dist/configs/react.js +2 -1
- package/dist/configs/testing.d.ts.map +1 -1
- package/dist/configs/testing.js +2 -1
- package/dist/configs/unicorn.js +1 -1
- package/dist/exts.d.ts +8 -0
- package/dist/exts.d.ts.map +1 -0
- package/dist/exts.js +11 -0
- package/dist/index.d.ts +3 -16
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -31
- package/dist/lib.d.ts +0 -6
- package/dist/lib.d.ts.map +1 -1
- package/dist/lib.js +17 -8
- package/dist/lintPrepare.d.ts +14 -11
- package/dist/lintPrepare.d.ts.map +1 -1
- package/dist/lintPrepare.js +76 -33
- package/dist/lintStaged.d.ts +22 -0
- package/dist/lintStaged.d.ts.map +1 -0
- package/dist/lintStaged.js +24 -0
- package/dist/prettier.d.ts +7 -0
- package/dist/prettier.d.ts.map +1 -0
- package/dist/prettier.js +19 -0
- package/package.json +14 -2
- package/rules/agent.md +117 -0
- package/rules/auth.md +1 -1
- package/rules/code-style.md +1 -1
- package/rules/db.md +9 -3
- package/rules/electron.md +1 -1
- package/rules/i18n.md +1 -1
- package/rules/jest.md +1 -0
- package/rules/nx.md +1 -1
- package/rules/turbo.md +1 -1
- package/rules/typescript.md +1 -1
- package/rules/webstorm.md +12 -7
package/README.md
CHANGED
|
@@ -206,14 +206,14 @@ The Tailwind block auto-scopes to the **workspace package** owning the entry CSS
|
|
|
206
206
|
## Prettier `.prettierrc.mjs`:
|
|
207
207
|
|
|
208
208
|
```js
|
|
209
|
-
import { prettier } from '@kirill.konshin/lint';
|
|
209
|
+
import { prettier } from '@kirill.konshin/lint/prettier';
|
|
210
210
|
export default prettier;
|
|
211
211
|
```
|
|
212
212
|
|
|
213
213
|
or
|
|
214
214
|
|
|
215
215
|
```js
|
|
216
|
-
import { prettier } from '@kirill.konshin/lint';
|
|
216
|
+
import { prettier } from '@kirill.konshin/lint/prettier';
|
|
217
217
|
|
|
218
218
|
export default {
|
|
219
219
|
...prettier,
|
|
@@ -221,6 +221,8 @@ export default {
|
|
|
221
221
|
};
|
|
222
222
|
```
|
|
223
223
|
|
|
224
|
+
Import from `/prettier`, not the package root: the root loads every ESLint plugin, which would slow down each Prettier run.
|
|
225
|
+
|
|
224
226
|
## Editor Config `.editorconfig`
|
|
225
227
|
|
|
226
228
|
```editorconfig
|
|
@@ -270,10 +272,12 @@ indent_style = tab
|
|
|
270
272
|
`.lintstagedrc.mjs`
|
|
271
273
|
|
|
272
274
|
```js
|
|
273
|
-
import { listStaged } from '@kirill.konshin/lint';
|
|
275
|
+
import { listStaged } from '@kirill.konshin/lint/lint-staged';
|
|
274
276
|
export default listStaged;
|
|
275
277
|
```
|
|
276
278
|
|
|
279
|
+
Import from `/lint-staged`, not the package root, for the same reason as `/prettier`. Tasks run the `eslint` / `prettier` scripts above through `node --run` (Node ≥ 22, `node_modules` linker), not `yarn`, which loads the whole project state before every script.
|
|
280
|
+
|
|
277
281
|
### Husky
|
|
278
282
|
|
|
279
283
|
By default, always use the `prepare` script, as [Husky recommends](https://typicode.github.io/husky/get-started.html) — it never runs on consumers' installs of a published package, so it needs no guards. The bare `husky` command (v9+; `husky install` is the deprecated v8 form) installs the git hooks:
|
|
@@ -296,9 +300,11 @@ By default, always use the `prepare` script, as [Husky recommends](https://typic
|
|
|
296
300
|
|
|
297
301
|
```bash
|
|
298
302
|
#!/bin/zsh
|
|
299
|
-
|
|
303
|
+
node --run lint:staged
|
|
300
304
|
```
|
|
301
305
|
|
|
306
|
+
Run scripts with `node --run` and tools directly (Husky puts `node_modules/.bin` on `PATH`): a `yarn` hop costs seconds.
|
|
307
|
+
|
|
302
308
|
Note `source ~/.zshrc # for VSCode terminal` may be added for VSCode terminal that is not aware of ZSH. Do not add unless specifically asked, and remove if present.
|
|
303
309
|
|
|
304
310
|
## AI Agent Rules
|
|
@@ -323,13 +329,13 @@ The generated `AGENTS.md` has a `# Custom Rules` section at the bottom — add p
|
|
|
323
329
|
|
|
324
330
|
In the project root, `lint-prepare`:
|
|
325
331
|
|
|
326
|
-
- Symlinks every `rules/*.md` into `.claude/rules
|
|
332
|
+
- Symlinks every `rules/*.md` into `.claude/rules/` (auto-discovered by Claude Code) and `.codex/rules/`.
|
|
327
333
|
- Symlinks every skill into `.claude/skills/<name>/` and `.codex/skills/<name>/` (`SKILL.md` plus this `README.md` alongside it, so a skill can reference `@README.md`) — e.g. `lint-repo`, which sets up the tooling above and audits the repo against the rules.
|
|
328
|
-
- Generates `AGENTS.md`
|
|
334
|
+
- Generates `AGENTS.md` for other assistants (Codex, Cursor, Copilot, …) with a `# Rules` section — per rule a `## <Title>` (from the file name), its frontmatter `description` and an `@path` to the rule file, relative to the project root from the package's real (symlink-resolved) location — and symlinks `CLAUDE.md` to it.
|
|
329
335
|
|
|
330
336
|
### Safety checks
|
|
331
337
|
|
|
332
|
-
`init`/`update` refuse to run if `.claude/rules`, a skill target dir, or `CLAUDE.md` contains anything that isn't a symlink — this avoids silently overwriting files you created by hand. If `AGENTS.md` exists and wasn't generated by this tool, `init` skips it; use `update` to force regeneration.
|
|
338
|
+
`init`/`update` refuse to run if `.claude/rules`, `.codex/rules`, a skill target dir, or `CLAUDE.md` contains anything that isn't a symlink — this avoids silently overwriting files you created by hand. Codex command policies (`.codex/rules/*.rules`) are left alone. If `AGENTS.md` exists and wasn't generated by this tool, `init` skips it; use `update` to force regeneration.
|
|
333
339
|
|
|
334
340
|
## Migration
|
|
335
341
|
|
|
@@ -404,7 +410,7 @@ Tool-gated functions take the same value as their `defineLintConfig` flag and ga
|
|
|
404
410
|
Due to limitations package visibility between leaf and root this package has to be creative to support config-free detection.
|
|
405
411
|
|
|
406
412
|
1. **Package probe** — `local-pkg`'s `isPackageExists` anchored at the **workspace root**, the same scope the plugins resolve from at lint time (`has<Pkg>` exported for debugging).
|
|
407
|
-
2. **Evidence scan** — tool config files across the workspace: the root directory plus every **workspace package** (the real `workspaces`/`pnpm-workspace.yaml` globs via `@manypkg/get-packages`, not a depth heuristic), skipping dot dirs, build outputs, and `.gitignore`d files; exported as `scanWorkspace`. Catches tools installed only in **leaf** packages, invisible to the probe (1). The workspace root itself comes from env (`PROJECT_CWD`/`npm_config_local_prefix`) with `@manypkg/find-root` as the fallback (workspace manifest walk, nearest `package.json` for single-package repos; exported as `findWorkspaceRoot`), so linting from inside a package still sees the whole repo.
|
|
413
|
+
2. **Evidence scan** — tool config files across the workspace: the root directory plus every **workspace package** (the real `workspaces`/`pnpm-workspace.yaml` globs via `@manypkg/get-packages`, not a depth heuristic), skipping dot dirs, build outputs, and `.gitignore`d files; exported as `scanWorkspace`. All scans of a process share one filesystem cache, so each directory is read once. Catches tools installed only in **leaf** packages, invisible to the probe (1). The workspace root itself comes from env (`PROJECT_CWD`/`npm_config_local_prefix`) with `@manypkg/find-root` as the fallback (workspace manifest walk, nearest `package.json` for single-package repos; exported as `findWorkspaceRoot`), so linting from inside a package still sees the whole repo.
|
|
408
414
|
3. **Hoisting, not bridging** — the plugins need the tool's package resolvable from the workspace root; a tool that is evidently in use (2) but not resolvable there (1) is a **hard error** with hoisting guidance (keep default hoisting, pnpm `public-hoist-pattern`, or a root devDependency — see the error text) instead of a silent skip or a cryptic plugin crash. Fix it once in the package manager config; nothing is symlinked at lint time.
|
|
409
415
|
4. **Yarn Berry PnP** — there is no hoisting to configure; declare the tools at the workspace root as well, keeping versions in sync with the leaves (e.g. the `"vitest": "$vitest"` version-alias hack); `next` documents its own monorepo ESLint setup.
|
|
410
416
|
|
package/dist/configs/imports.js
CHANGED
|
@@ -2,7 +2,7 @@ import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescrip
|
|
|
2
2
|
import importXPlugin, { createNodeResolver } from 'eslint-plugin-import-x';
|
|
3
3
|
import simpleImportSortPlugin from 'eslint-plugin-simple-import-sort';
|
|
4
4
|
import unusedImportsPlugin from 'eslint-plugin-unused-imports';
|
|
5
|
-
import { tsExts } from '../
|
|
5
|
+
import { tsExts } from '../exts.js';
|
|
6
6
|
/**
|
|
7
7
|
* Import linting via eslint-plugin-import-x: recommended rules + overrides + the default-export
|
|
8
8
|
* relaxation for files that legitimately default-export (framework/tooling conventions) - the
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/configs/react.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;
|
|
1
|
+
{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/configs/react.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAQrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI/C,eAAO,MAAM,UAAU,kDAAsE,CAAC;AAe9F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAWzD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAAC,EAAE,OAAuC,EAAE,GAAE,WAAgB,GAAG,OAAO,CACxG,MAAM,CAAC,MAAM,EAAE,CAClB,CAOA;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,CAOjD;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,MAAM,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CA6BzG;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,CAmD3D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,CAarD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,CAQrD;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,MAAM,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAO1G"}
|
package/dist/configs/react.js
CHANGED
|
@@ -5,7 +5,8 @@ import jsxA11yPlugin from 'eslint-plugin-jsx-a11y';
|
|
|
5
5
|
import reactPlugin from 'eslint-plugin-react';
|
|
6
6
|
import reactHooksPlugin from 'eslint-plugin-react-hooks';
|
|
7
7
|
import { globSync } from 'glob';
|
|
8
|
-
import {
|
|
8
|
+
import { tsExts } from '../exts.js';
|
|
9
|
+
import { findWorkspaceRoot, GLOBAL_IGNORES, hasNext, scanWorkspace, toolGate } from '../lib.js';
|
|
9
10
|
// lazy so consumers without Next don't pay the load cost - re-exported from index.js
|
|
10
11
|
export const nextPlugin = hasNext ? (await import('@next/eslint-plugin-next')).default : null;
|
|
11
12
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/configs/testing.ts"],"names":[],"mappings":"AAYA,OAAO,YAAY,MAAM,uBAAuB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAQ,MAAM,QAAQ,CAAC;AAC3C,OAAO,UAAU,MAAM,oBAAoB,CAAC;
|
|
1
|
+
{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/configs/testing.ts"],"names":[],"mappings":"AAYA,OAAO,YAAY,MAAM,uBAAuB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAQ,MAAM,QAAQ,CAAC;AAC3C,OAAO,UAAU,MAAM,oBAAoB,CAAC;AAG5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AA6DpC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE,MAAM,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAgB5F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE,MAAM,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAsB9F;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,CAmB5C"}
|
package/dist/configs/testing.js
CHANGED
|
@@ -12,7 +12,8 @@ import fs from 'node:fs';
|
|
|
12
12
|
import path from 'node:path';
|
|
13
13
|
import vitestPlugin from '@vitest/eslint-plugin';
|
|
14
14
|
import jestPlugin from 'eslint-plugin-jest';
|
|
15
|
-
import {
|
|
15
|
+
import { tsExts, tsExtsRaw } from '../exts.js';
|
|
16
|
+
import { GLOBAL_IGNORES, hasJest, hasVitest, scanWorkspace, toolGate } from '../lib.js';
|
|
16
17
|
export { jestPlugin, vitestPlugin };
|
|
17
18
|
/*
|
|
18
19
|
* Both runners use the evidence-based `toolGate` (see lib.js): a runner config file marks the repo
|
package/dist/configs/unicorn.js
CHANGED
package/dist/exts.d.ts
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export declare const tsExtsRaw = "js,jsx,ts,tsx,cjs,cts,mjs,mts";
|
|
2
|
+
export declare const markupExtsRaw = "md,mdx,htm,html,vue";
|
|
3
|
+
export declare const eslintExtsRaw = "js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue";
|
|
4
|
+
export declare const prettierExtsRaw = "css,scss,sass,less,yml,yaml,json,json5,jsonc,graphql,graphqls,xml";
|
|
5
|
+
export declare const tsExts = "{js,jsx,ts,tsx,cjs,cts,mjs,mts}";
|
|
6
|
+
export declare const eslintExts = "*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}";
|
|
7
|
+
export declare const prettierExts = "*.{css,scss,sass,less,yml,yaml,json,json5,jsonc,graphql,graphqls,xml}";
|
|
8
|
+
//# sourceMappingURL=exts.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"exts.d.ts","sourceRoot":"","sources":["../src/exts.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,SAAS,kCAAkC,CAAC;AACzD,eAAO,MAAM,aAAa,wBAAwB,CAAC;AACnD,eAAO,MAAM,aAAa,sDAAkC,CAAC;AAC7D,eAAO,MAAM,eAAe,sEAAsE,CAAC;AAEnG,eAAO,MAAM,MAAM,oCAAmB,CAAC;AACvC,eAAO,MAAM,UAAU,0DAAyB,CAAC;AACjD,eAAO,MAAM,YAAY,0EAA2B,CAAC"}
|
package/dist/exts.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* File extension lists shared by the ESLint blocks and the Prettier / lint-staged configs. Free of imports and side
|
|
3
|
+
* effects, so the `./prettier` and `./lint-staged` entries load nothing else.
|
|
4
|
+
*/
|
|
5
|
+
export const tsExtsRaw = 'js,jsx,ts,tsx,cjs,cts,mjs,mts'; // TODO mdx, needs loader
|
|
6
|
+
export const markupExtsRaw = 'md,mdx,htm,html,vue';
|
|
7
|
+
export const eslintExtsRaw = `${tsExtsRaw},${markupExtsRaw}`;
|
|
8
|
+
export const prettierExtsRaw = 'css,scss,sass,less,yml,yaml,json,json5,jsonc,graphql,graphqls,xml';
|
|
9
|
+
export const tsExts = `{${tsExtsRaw}}`;
|
|
10
|
+
export const eslintExts = `*.{${eslintExtsRaw}}`;
|
|
11
|
+
export const prettierExts = `*.{${prettierExtsRaw}}`;
|
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,6 @@
|
|
|
1
1
|
import type { ParserOptions as TsParserOptions } from '@typescript-eslint/parser';
|
|
2
2
|
import type { Linter } from 'eslint';
|
|
3
3
|
import type { PluginSettings as TailwindPluginSettings } from 'eslint-plugin-tailwindcss';
|
|
4
|
-
import type { Configuration as LintStagedConfiguration } from 'lint-staged';
|
|
5
|
-
import type { Config as PrettierConfig } from 'prettier';
|
|
6
4
|
export * from './configs/base.js';
|
|
7
5
|
export * from './configs/imports.js';
|
|
8
6
|
export * from './configs/react.js';
|
|
@@ -15,7 +13,10 @@ export * from './configs/testing.js';
|
|
|
15
13
|
export * from './configs/turbo.js';
|
|
16
14
|
export * from './configs/typescriptTypeAware.js';
|
|
17
15
|
export * from './configs/unicorn.js';
|
|
16
|
+
export * from './exts.js';
|
|
18
17
|
export * from './lib.js';
|
|
18
|
+
export * from './lintStaged.js';
|
|
19
|
+
export * from './prettier.js';
|
|
19
20
|
type ProjectServiceOptions = Exclude<NonNullable<TsParserOptions['projectService']>, boolean>;
|
|
20
21
|
export type ToggleOptions = {
|
|
21
22
|
enabled?: boolean;
|
|
@@ -63,18 +64,4 @@ export type LintOptions = {
|
|
|
63
64
|
*
|
|
64
65
|
*/
|
|
65
66
|
export declare function defineLintConfig(options?: LintOptions | Promise<LintOptions> | (() => LintOptions | Promise<LintOptions>)): Promise<Linter.Config[]>;
|
|
66
|
-
export declare const prettier: PrettierConfig;
|
|
67
|
-
/**
|
|
68
|
-
* https://nextjs.org/docs/app/api-reference/config/eslint#running-lint-on-staged-files
|
|
69
|
-
*
|
|
70
|
-
* Pay extra attention when the configured globs overlap, and tasks make edits to files. Prettier and eslint might try
|
|
71
|
-
* to make changes to the same *.ts file at the same time, causing a race condition.
|
|
72
|
-
*
|
|
73
|
-
* https://github.com/lint-staged/lint-staged?tab=readme-ov-file#reformatting-the-code
|
|
74
|
-
* https://github.com/lint-staged/lint-staged/issues/775
|
|
75
|
-
* You don't need git add since lint-staged 10
|
|
76
|
-
*
|
|
77
|
-
* TODO Screw yarn, just use eslint directly? Yarn gives greater control over what is in the console...
|
|
78
|
-
*/
|
|
79
|
-
export declare const listStaged: LintStagedConfiguration;
|
|
80
67
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,IAAI,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,IAAI,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAgB1F,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kCAAkC,CAAC;AACjD,cAAc,sBAAsB,CAAC;AAErC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAE9B,KAAK,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAE9F,MAAM,MAAM,aAAa,GAAG;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG;IACtC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG;IAC1C,aAAa,CAAC,EAAE,sBAAsB,CAAC,eAAe,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,aAAa,GACxC,IAAI,CACA,qBAAqB,EACrB,qBAAqB,GAAG,iEAAiE,CAC5F,GAAG;IACA,eAAe,CAAC,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;CACxD,CAAC;AAEN,MAAM,MAAM,oBAAoB,GAC5B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,CAAC,EAAE,IAAI,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3F,MAAM,MAAM,WAAW,GAAG;IACtB,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACvC,IAAI,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IACpC,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAChC,EAAE,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC/B,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IACrC,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACvC,aAAa,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CAClD,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAClC,OAAO,GAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAM,GAC9F,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAgD1B"}
|
package/dist/index.js
CHANGED
|
@@ -10,7 +10,7 @@ import { jestConfig, testConfig, vitestConfig } from './configs/testing.js';
|
|
|
10
10
|
import { turboConfig } from './configs/turbo.js';
|
|
11
11
|
import { typeAwareConfig } from './configs/typescriptTypeAware.js';
|
|
12
12
|
import { unicornConfig } from './configs/unicorn.js';
|
|
13
|
-
import { asOptions
|
|
13
|
+
import { asOptions } from './lib.js';
|
|
14
14
|
export * from './configs/base.js';
|
|
15
15
|
export * from './configs/imports.js';
|
|
16
16
|
export * from './configs/react.js';
|
|
@@ -23,7 +23,10 @@ export * from './configs/testing.js';
|
|
|
23
23
|
export * from './configs/turbo.js';
|
|
24
24
|
export * from './configs/typescriptTypeAware.js';
|
|
25
25
|
export * from './configs/unicorn.js';
|
|
26
|
+
export * from './exts.js';
|
|
26
27
|
export * from './lib.js';
|
|
28
|
+
export * from './lintStaged.js';
|
|
29
|
+
export * from './prettier.js';
|
|
27
30
|
/**
|
|
28
31
|
* Build the shared flat ESLint config.
|
|
29
32
|
*
|
|
@@ -81,33 +84,3 @@ export async function defineLintConfig(options = {}) {
|
|
|
81
84
|
...testConfig(),
|
|
82
85
|
];
|
|
83
86
|
}
|
|
84
|
-
export const prettier = {
|
|
85
|
-
printWidth: 120,
|
|
86
|
-
tabWidth: 2,
|
|
87
|
-
singleQuote: true,
|
|
88
|
-
proseWrap: 'never',
|
|
89
|
-
overrides: [
|
|
90
|
-
{
|
|
91
|
-
files: eslintExts,
|
|
92
|
-
options: {
|
|
93
|
-
tabWidth: 4,
|
|
94
|
-
},
|
|
95
|
-
},
|
|
96
|
-
],
|
|
97
|
-
};
|
|
98
|
-
/**
|
|
99
|
-
* https://nextjs.org/docs/app/api-reference/config/eslint#running-lint-on-staged-files
|
|
100
|
-
*
|
|
101
|
-
* Pay extra attention when the configured globs overlap, and tasks make edits to files. Prettier and eslint might try
|
|
102
|
-
* to make changes to the same *.ts file at the same time, causing a race condition.
|
|
103
|
-
*
|
|
104
|
-
* https://github.com/lint-staged/lint-staged?tab=readme-ov-file#reformatting-the-code
|
|
105
|
-
* https://github.com/lint-staged/lint-staged/issues/775
|
|
106
|
-
* You don't need git add since lint-staged 10
|
|
107
|
-
*
|
|
108
|
-
* TODO Screw yarn, just use eslint directly? Yarn gives greater control over what is in the console...
|
|
109
|
-
*/
|
|
110
|
-
export const listStaged = {
|
|
111
|
-
[prettierExts]: ['yarn prettier'],
|
|
112
|
-
[eslintExts]: ['yarn eslint', 'yarn prettier'],
|
|
113
|
-
};
|
package/dist/lib.d.ts
CHANGED
|
@@ -20,12 +20,6 @@ type ToolGateResult<T extends ToggleOptions> = {
|
|
|
20
20
|
options: NormalizedOptions<T>;
|
|
21
21
|
files: string[];
|
|
22
22
|
};
|
|
23
|
-
export declare const tsExtsRaw = "js,jsx,ts,tsx,cjs,cts,mjs,mts";
|
|
24
|
-
export declare const eslintExtsRaw = "js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue";
|
|
25
|
-
export declare const prettierExtsRaw = "css,scss,sass,less,yml,yaml,json,json5,jsonc,graphql,graphqls,xml";
|
|
26
|
-
export declare const tsExts = "{js,jsx,ts,tsx,cjs,cts,mjs,mts}";
|
|
27
|
-
export declare const eslintExts = "*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}";
|
|
28
|
-
export declare const prettierExts = "*.{css,scss,sass,less,yml,yaml,json,json5,jsonc,graphql,graphqls,xml}";
|
|
29
23
|
export declare const GLOBAL_IGNORES: string[];
|
|
30
24
|
/**
|
|
31
25
|
* Capability gate: is a package resolvable from the workspace root - the scope the ESLint plugins
|
package/dist/lib.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,KAAK,iBAAiB,CAAC,CAAC,SAAS,aAAa,IAAI,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AAErE,KAAK,YAAY,CAAC,CAAC,SAAS,aAAa,IAAI;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,OAAO,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;IAChE,IAAI,CAAC,EAAE,MAAM,MAAM,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D,CAAC;AAEF,KAAK,cAAc,CAAC,CAAC,SAAS,aAAa,IAAI;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAGF,eAAO,MAAM,cAAc,UAQ1B,CAAC;AAaF;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAEhE;AAcD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,SAAgB,GAAG,MAAM,CAiB7D;AAyBD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWjD;AAoCD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAAM,EAAO,EACtB,EAAE,GAAW,EAAE,GAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,MAAM,EAAE,CAwCV;AAUD,eAAO,MAAM,OAAO,SAA8B,CAAC;AACnD,eAAO,MAAM,YAAY,SAAmC,CAAC;AAC7D,eAAO,MAAM,OAAO,SAA8B,CAAC;AACnD,eAAO,MAAM,OAAO,SAA8B,CAAC;AACnD,eAAO,MAAM,SAAS,SAAgC,CAAC;AACvD,eAAO,MAAM,QAAQ,SAA+B,CAAC;AACrD,eAAO,MAAM,KAAK,SAAsD,CAAC;AACzE,eAAO,MAAM,WAAW,SAAqC,CAAC;AAI9D;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,aAAa,EAC7C,MAAM,EAAE,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,GACvC,iBAAiB,CAAC,CAAC,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAM9C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,aAAa,EAC5C,MAAM,EAAE,OAAO,GAAG,CAAC,GAAG,SAAS,EAC/B,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GACtB,cAAc,CAAC,CAAC,CAAC,CA6GnB"}
|
package/dist/lib.js
CHANGED
|
@@ -5,12 +5,7 @@ import { findRootSync } from '@manypkg/find-root';
|
|
|
5
5
|
import { getPackagesSync } from '@manypkg/get-packages';
|
|
6
6
|
import { globSync } from 'glob';
|
|
7
7
|
import { isPackageExists } from 'local-pkg';
|
|
8
|
-
|
|
9
|
-
export const eslintExtsRaw = `${tsExtsRaw},md,mdx,htm,html,vue`;
|
|
10
|
-
export const prettierExtsRaw = 'css,scss,sass,less,yml,yaml,json,json5,jsonc,graphql,graphqls,xml';
|
|
11
|
-
export const tsExts = `{${tsExtsRaw}}`;
|
|
12
|
-
export const eslintExts = `*.{${eslintExtsRaw}}`;
|
|
13
|
-
export const prettierExts = `*.{${prettierExtsRaw}}`;
|
|
8
|
+
import { PathScurry } from 'path-scurry';
|
|
14
9
|
//TODO coverage, dist, out, build?
|
|
15
10
|
export const GLOBAL_IGNORES = [
|
|
16
11
|
'**/next-env.d.ts',
|
|
@@ -140,6 +135,20 @@ const SCAN_IGNORES = [
|
|
|
140
135
|
'**/storybook-static',
|
|
141
136
|
'**/.git',
|
|
142
137
|
];
|
|
138
|
+
const scurries = new Map();
|
|
139
|
+
/**
|
|
140
|
+
* Filesystem cache of a scanned directory, shared by every {@link scanWorkspace} call: the detection scans all walk
|
|
141
|
+
* the same trees, so each directory is read once instead of once per scan. Cached per process, like the workspace
|
|
142
|
+
* root and packages.
|
|
143
|
+
*/
|
|
144
|
+
function scurryOf(dir) {
|
|
145
|
+
const cached = scurries.get(dir);
|
|
146
|
+
if (cached)
|
|
147
|
+
return cached;
|
|
148
|
+
const scurry = new PathScurry(dir);
|
|
149
|
+
scurries.set(dir, scurry);
|
|
150
|
+
return scurry;
|
|
151
|
+
}
|
|
143
152
|
/**
|
|
144
153
|
* Glob for config-file candidates across the workspace: the root directory plus every workspace
|
|
145
154
|
* package (the real `workspaces` globs via {@link findWorkspacePackages}, not a depth heuristic),
|
|
@@ -176,8 +185,8 @@ export function scanWorkspace(fileGlob, ignores = [], { dot = false } = {}) {
|
|
|
176
185
|
}),
|
|
177
186
|
];
|
|
178
187
|
const files = [
|
|
179
|
-
...globSync(`**/${fileGlob}`, { cwd: root, ignore: rootIgnore, absolute: true, dot }),
|
|
180
|
-
...packages.flatMap((dir) => globSync(`**/${fileGlob}`, { cwd: dir, ignore, absolute: true, dot })),
|
|
188
|
+
...globSync(`**/${fileGlob}`, { cwd: root, scurry: scurryOf(root), ignore: rootIgnore, absolute: true, dot }),
|
|
189
|
+
...packages.flatMap((dir) => globSync(`**/${fileGlob}`, { cwd: dir, scurry: scurryOf(dir), ignore, absolute: true, dot })),
|
|
181
190
|
];
|
|
182
191
|
// debug('scanWorkspace', { fileGlob, root, packages, dot, ignores, files });
|
|
183
192
|
return files;
|
package/dist/lintPrepare.d.ts
CHANGED
|
@@ -3,10 +3,10 @@
|
|
|
3
3
|
* @kirill.konshin/lint
|
|
4
4
|
*
|
|
5
5
|
* This script symlinks all markdown rule files from the package into the consuming
|
|
6
|
-
* project's `.claude/rules`
|
|
7
|
-
* package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/`
|
|
8
|
-
* the package README.md alongside it, so a skill can reference `@README.md`),
|
|
9
|
-
* an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
|
|
6
|
+
* project's `.claude/rules` (auto-discovered by Claude Code) and `.codex/rules` directories,
|
|
7
|
+
* symlinks every package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/`
|
|
8
|
+
* (SKILL.md plus the package README.md alongside it, so a skill can reference `@README.md`),
|
|
9
|
+
* and generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
|
|
10
10
|
*
|
|
11
11
|
* Usage:
|
|
12
12
|
* lint-prepare init - Initialize AGENTS.md in the current directory (default)
|
|
@@ -19,6 +19,7 @@
|
|
|
19
19
|
type Rule = {
|
|
20
20
|
file: string;
|
|
21
21
|
name: string;
|
|
22
|
+
description?: string;
|
|
22
23
|
content: string;
|
|
23
24
|
};
|
|
24
25
|
type Skill = {
|
|
@@ -40,8 +41,9 @@ export declare function readRules(): Rule[];
|
|
|
40
41
|
*/
|
|
41
42
|
export declare function readSkills(): Skill[];
|
|
42
43
|
/**
|
|
43
|
-
* Fail if `.claude/rules` contains anything that isn't a symlink - we don't want to
|
|
44
|
-
* silently blow away a real file/directory a user placed there by hand.
|
|
44
|
+
* Fail if `.claude/rules` or `.codex/rules` contains anything that isn't a symlink - we don't want to
|
|
45
|
+
* silently blow away a real file/directory a user placed there by hand. Codex command policies
|
|
46
|
+
* (`*.rules`) are not ours and are left alone.
|
|
45
47
|
*/
|
|
46
48
|
export declare function checkRulesDirSafety(rulesTargetDir: string): void;
|
|
47
49
|
/**
|
|
@@ -49,9 +51,9 @@ export declare function checkRulesDirSafety(rulesTargetDir: string): void;
|
|
|
49
51
|
*/
|
|
50
52
|
export declare function checkClaudeMdSafety(claudeMdPath: string): void;
|
|
51
53
|
/**
|
|
52
|
-
* Symlink rules into the consuming project's `.claude/rules`
|
|
53
|
-
* Safe to
|
|
54
|
-
* entry is a symlink.
|
|
54
|
+
* Symlink rules into the consuming project's `.claude/rules` and `.codex/rules` directories.
|
|
55
|
+
* Safe to clear and recreate: checkRulesDirSafety already guaranteed every existing
|
|
56
|
+
* entry except Codex command policies (kept) is a symlink.
|
|
55
57
|
*
|
|
56
58
|
* FIXME Codex Includes
|
|
57
59
|
* https://github.com/openai/codex/issues/17401
|
|
@@ -62,7 +64,7 @@ export declare function checkClaudeMdSafety(claudeMdPath: string): void;
|
|
|
62
64
|
* (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
|
|
63
65
|
* indexed anywhere).
|
|
64
66
|
*/
|
|
65
|
-
export declare function symlinkRules(cwd: string, rules: Rule[]): string;
|
|
67
|
+
export declare function symlinkRules(cwd: string, rules: Rule[]): string[];
|
|
66
68
|
/**
|
|
67
69
|
* Fail if a skill's target directory (e.g. `.claude/skills/lint-repo`) contains anything
|
|
68
70
|
* that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
|
|
@@ -82,7 +84,8 @@ export declare function symlinkSkills(cwd: string, skills: Skill[]): string[];
|
|
|
82
84
|
*/
|
|
83
85
|
export declare function symlinkClaudeMd(cwd: string): void;
|
|
84
86
|
/**
|
|
85
|
-
* Generate AGENTS.md with
|
|
87
|
+
* Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file with its
|
|
88
|
+
* frontmatter `description` and a reference to the file.
|
|
86
89
|
*
|
|
87
90
|
* `.claude/rules/*.md` are symlinked by symlinkRules() above and auto-discovered by
|
|
88
91
|
* Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG;
|
|
1
|
+
{"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG;AAUH,KAAK,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAClF,KAAK,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAC5C,KAAK,YAAY,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAiD1F;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAyBlC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAQpC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAYhE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAc9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAkBjE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAY1D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,EAAE,CA2BpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAwBnG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAW9D;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CA0D3B"}
|
package/dist/lintPrepare.js
CHANGED
|
@@ -3,10 +3,10 @@
|
|
|
3
3
|
* @kirill.konshin/lint
|
|
4
4
|
*
|
|
5
5
|
* This script symlinks all markdown rule files from the package into the consuming
|
|
6
|
-
* project's `.claude/rules`
|
|
7
|
-
* package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/`
|
|
8
|
-
* the package README.md alongside it, so a skill can reference `@README.md`),
|
|
9
|
-
* an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
|
|
6
|
+
* project's `.claude/rules` (auto-discovered by Claude Code) and `.codex/rules` directories,
|
|
7
|
+
* symlinks every package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/`
|
|
8
|
+
* (SKILL.md plus the package README.md alongside it, so a skill can reference `@README.md`),
|
|
9
|
+
* and generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
|
|
10
10
|
*
|
|
11
11
|
* Usage:
|
|
12
12
|
* lint-prepare init - Initialize AGENTS.md in the current directory (default)
|
|
@@ -19,15 +19,19 @@
|
|
|
19
19
|
import fs from 'node:fs';
|
|
20
20
|
import path from 'node:path';
|
|
21
21
|
import { fileURLToPath } from 'node:url';
|
|
22
|
+
import { parse } from 'yaml';
|
|
22
23
|
const __filename = fileURLToPath(import.meta.url);
|
|
23
24
|
const __dirname = path.dirname(__filename);
|
|
24
25
|
const AGENTS_FILE = 'AGENTS.md';
|
|
25
26
|
const CLAUDE_FILE = 'CLAUDE.md';
|
|
26
|
-
const CLAUDE_RULES_DIR = '.claude/rules';
|
|
27
27
|
const RULES_DIR = path.join(__dirname, '../rules');
|
|
28
28
|
const SKILLS_DIR = path.join(__dirname, '../skills');
|
|
29
29
|
const README_FILE = path.join(__dirname, '../README.md');
|
|
30
|
+
const RULES_TARGET_DIRS = ['.claude/rules', '.codex/rules'];
|
|
30
31
|
const SKILLS_TARGET_DIRS = ['.claude/skills', '.codex/skills'];
|
|
32
|
+
// Codex keeps its own command policies in `.codex/rules/*.rules` (https://developers.openai.com/codex/rules)
|
|
33
|
+
const CODEX_POLICY_EXT = '.rules';
|
|
34
|
+
const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
|
|
31
35
|
const HEADER = `# AI Agent Rules
|
|
32
36
|
|
|
33
37
|
This file is auto-generated by @kirill.konshin/lint. Do not edit directly - customize by adding your own rules below the generated section.
|
|
@@ -39,6 +43,26 @@ const FOOTER = `---
|
|
|
39
43
|
|
|
40
44
|
Add your project-specific rules below the comment line.`;
|
|
41
45
|
const GENERATED_MARKER = '<!-- @kirill.konshin/lint:generated -->';
|
|
46
|
+
/**
|
|
47
|
+
* Relative path between the REAL locations of `from` and `to`: the cwd and the package (workspaces, yalc, pnpm store)
|
|
48
|
+
* may be reached through symlinks, and a path computed between a symlinked and a real location dangles.
|
|
49
|
+
*/
|
|
50
|
+
const realRelative = (from, to) => path.relative(fs.realpathSync(from), fs.realpathSync(to));
|
|
51
|
+
/**
|
|
52
|
+
* `monorepo-turbo-nx` -> `Monorepo turbo nx`
|
|
53
|
+
*/
|
|
54
|
+
const toTitle = (name) => {
|
|
55
|
+
const title = name.replaceAll('-', ' ');
|
|
56
|
+
return title.charAt(0).toUpperCase() + title.slice(1);
|
|
57
|
+
};
|
|
58
|
+
/**
|
|
59
|
+
* The `description` field of a rule's YAML frontmatter.
|
|
60
|
+
*/
|
|
61
|
+
const readDescription = (content) => {
|
|
62
|
+
const frontmatter = FRONTMATTER.exec(content)?.[1];
|
|
63
|
+
const description = frontmatter ? parse(frontmatter)?.description : undefined;
|
|
64
|
+
return typeof description === 'string' ? description.trim() : undefined;
|
|
65
|
+
};
|
|
42
66
|
/**
|
|
43
67
|
* Read all markdown files from the package rules directory.
|
|
44
68
|
*/
|
|
@@ -58,6 +82,7 @@ export function readRules() {
|
|
|
58
82
|
rules.push({
|
|
59
83
|
file,
|
|
60
84
|
name: file.replace('.md', ''),
|
|
85
|
+
description: readDescription(content),
|
|
61
86
|
content,
|
|
62
87
|
});
|
|
63
88
|
}
|
|
@@ -77,16 +102,17 @@ export function readSkills() {
|
|
|
77
102
|
.map((file) => ({ file, name: file.replace('.md', '') }));
|
|
78
103
|
}
|
|
79
104
|
/**
|
|
80
|
-
* Fail if `.claude/rules` contains anything that isn't a symlink - we don't want to
|
|
81
|
-
* silently blow away a real file/directory a user placed there by hand.
|
|
105
|
+
* Fail if `.claude/rules` or `.codex/rules` contains anything that isn't a symlink - we don't want to
|
|
106
|
+
* silently blow away a real file/directory a user placed there by hand. Codex command policies
|
|
107
|
+
* (`*.rules`) are not ours and are left alone.
|
|
82
108
|
*/
|
|
83
109
|
export function checkRulesDirSafety(rulesTargetDir) {
|
|
84
110
|
if (!fs.existsSync(rulesTargetDir))
|
|
85
111
|
return;
|
|
86
112
|
for (const entry of fs.readdirSync(rulesTargetDir)) {
|
|
87
113
|
const entryPath = path.join(rulesTargetDir, entry);
|
|
88
|
-
if (!fs.lstatSync(entryPath).isSymbolicLink()) {
|
|
89
|
-
console.error(`${
|
|
114
|
+
if (!entry.endsWith(CODEX_POLICY_EXT) && !fs.lstatSync(entryPath).isSymbolicLink()) {
|
|
115
|
+
console.error(`${entryPath} exists and is not a symlink.`);
|
|
90
116
|
console.error('Remove or back it up manually, then re-run.');
|
|
91
117
|
process.exit(1);
|
|
92
118
|
}
|
|
@@ -110,9 +136,9 @@ export function checkClaudeMdSafety(claudeMdPath) {
|
|
|
110
136
|
}
|
|
111
137
|
}
|
|
112
138
|
/**
|
|
113
|
-
* Symlink rules into the consuming project's `.claude/rules`
|
|
114
|
-
* Safe to
|
|
115
|
-
* entry is a symlink.
|
|
139
|
+
* Symlink rules into the consuming project's `.claude/rules` and `.codex/rules` directories.
|
|
140
|
+
* Safe to clear and recreate: checkRulesDirSafety already guaranteed every existing
|
|
141
|
+
* entry except Codex command policies (kept) is a symlink.
|
|
116
142
|
*
|
|
117
143
|
* FIXME Codex Includes
|
|
118
144
|
* https://github.com/openai/codex/issues/17401
|
|
@@ -124,15 +150,20 @@ export function checkClaudeMdSafety(claudeMdPath) {
|
|
|
124
150
|
* indexed anywhere).
|
|
125
151
|
*/
|
|
126
152
|
export function symlinkRules(cwd, rules) {
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
153
|
+
return RULES_TARGET_DIRS.map((dir) => {
|
|
154
|
+
const targetDir = path.join(cwd, dir);
|
|
155
|
+
fs.mkdirSync(targetDir, { recursive: true });
|
|
156
|
+
for (const entry of fs.readdirSync(targetDir)) {
|
|
157
|
+
if (!entry.endsWith(CODEX_POLICY_EXT))
|
|
158
|
+
fs.unlinkSync(path.join(targetDir, entry));
|
|
159
|
+
}
|
|
160
|
+
for (const rule of rules) {
|
|
161
|
+
const source = path.join(RULES_DIR, rule.file);
|
|
162
|
+
const linkPath = path.join(targetDir, rule.file);
|
|
163
|
+
fs.symlinkSync(realRelative(targetDir, source), linkPath);
|
|
164
|
+
}
|
|
165
|
+
return targetDir;
|
|
166
|
+
});
|
|
136
167
|
}
|
|
137
168
|
/**
|
|
138
169
|
* Fail if a skill's target directory (e.g. `.claude/skills/lint-repo`) contains anything
|
|
@@ -169,10 +200,10 @@ export function symlinkSkills(cwd, skills) {
|
|
|
169
200
|
fs.mkdirSync(skillDir, { recursive: true });
|
|
170
201
|
const source = path.join(SKILLS_DIR, skill.file);
|
|
171
202
|
const linkPath = path.join(skillDir, 'SKILL.md');
|
|
172
|
-
fs.symlinkSync(
|
|
203
|
+
fs.symlinkSync(realRelative(skillDir, source), linkPath);
|
|
173
204
|
if (hasReadme) {
|
|
174
205
|
const readmeLink = path.join(skillDir, 'README.md');
|
|
175
|
-
fs.symlinkSync(
|
|
206
|
+
fs.symlinkSync(realRelative(skillDir, README_FILE), readmeLink);
|
|
176
207
|
}
|
|
177
208
|
targetDirs.push(skillDir);
|
|
178
209
|
}
|
|
@@ -188,7 +219,8 @@ export function symlinkClaudeMd(cwd) {
|
|
|
188
219
|
fs.symlinkSync(AGENTS_FILE, claudeMdPath);
|
|
189
220
|
}
|
|
190
221
|
/**
|
|
191
|
-
* Generate AGENTS.md with
|
|
222
|
+
* Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file with its
|
|
223
|
+
* frontmatter `description` and a reference to the file.
|
|
192
224
|
*
|
|
193
225
|
* `.claude/rules/*.md` are symlinked by symlinkRules() above and auto-discovered by
|
|
194
226
|
* Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
|
|
@@ -196,16 +228,24 @@ export function symlinkClaudeMd(cwd) {
|
|
|
196
228
|
* The sections below are for other tools that only read AGENTS.md.
|
|
197
229
|
*/
|
|
198
230
|
export function generateAgentsFile(rules, cwd, customSection) {
|
|
199
|
-
|
|
231
|
+
// where the rules really are, e.g. `node_modules/@kirill.konshin/lint/rules`, `packages/lint/rules` in a workspace
|
|
232
|
+
const relativeRulesDir = realRelative(cwd, RULES_DIR).split(path.sep).join('/');
|
|
200
233
|
/**
|
|
201
234
|
* @see https://code.claude.com/docs/en/memory#import-additional-files
|
|
202
235
|
* @see https://github.com/anthropics/claude-code/issues/13614 @import -> @path/file.md in Claude
|
|
203
236
|
* @see https://github.com/openai/codex/issues/17401 - no @path/file.md in Codex yet
|
|
204
237
|
*/
|
|
205
|
-
const
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
238
|
+
const sections = rules.map((rule) => {
|
|
239
|
+
const rulePath = `${relativeRulesDir}/${rule.file}`;
|
|
240
|
+
return [
|
|
241
|
+
`## ${toTitle(rule.name)}`,
|
|
242
|
+
rule.description,
|
|
243
|
+
`See instructions in @${rulePath} [${rulePath}](${rulePath}).`,
|
|
244
|
+
]
|
|
245
|
+
.filter(Boolean)
|
|
246
|
+
.join('\n\n');
|
|
247
|
+
});
|
|
248
|
+
const generated = `${HEADER}\n\n# Rules\n\n${sections.join('\n\n')}\n\n${FOOTER}\n\n${GENERATED_MARKER}`;
|
|
209
249
|
return customSection ? `${generated}\n\n${customSection}\n` : `${generated}\n`;
|
|
210
250
|
}
|
|
211
251
|
/**
|
|
@@ -233,7 +273,6 @@ export function main() {
|
|
|
233
273
|
const cwd = process.env.INIT_CWD || process.cwd();
|
|
234
274
|
const targetPath = path.join(cwd, AGENTS_FILE);
|
|
235
275
|
const claudeMdPath = path.join(cwd, CLAUDE_FILE);
|
|
236
|
-
const rulesTargetDir = path.join(cwd, CLAUDE_RULES_DIR);
|
|
237
276
|
console.log(`@kirill.konshin/lint: ${command}`);
|
|
238
277
|
console.log(`Target: ${targetPath}`);
|
|
239
278
|
const { exists, generated, customSection } = checkExisting(targetPath);
|
|
@@ -248,12 +287,16 @@ export function main() {
|
|
|
248
287
|
}
|
|
249
288
|
}
|
|
250
289
|
if (command === 'update' || command === 'init') {
|
|
251
|
-
|
|
290
|
+
for (const dir of RULES_TARGET_DIRS) {
|
|
291
|
+
checkRulesDirSafety(path.join(cwd, dir));
|
|
292
|
+
}
|
|
252
293
|
checkClaudeMdSafety(claudeMdPath);
|
|
253
294
|
const rules = readRules();
|
|
254
295
|
console.log(`Found ${rules.length} rule files: ${rules.map((r) => r.name).join(', ')}`);
|
|
255
|
-
const
|
|
256
|
-
|
|
296
|
+
const targetRulesDirs = symlinkRules(cwd, rules);
|
|
297
|
+
for (const targetRulesDir of targetRulesDirs) {
|
|
298
|
+
console.log(`Symlinked rules to ${targetRulesDir}`);
|
|
299
|
+
}
|
|
257
300
|
const skills = readSkills();
|
|
258
301
|
console.log(`Found ${skills.length} skill(s): ${skills.map((s) => s.name).join(', ')}`);
|
|
259
302
|
const targetSkillDirs = symlinkSkills(cwd, skills);
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { Configuration as LintStagedConfiguration } from 'lint-staged';
|
|
2
|
+
/**
|
|
3
|
+
* Shared lint-staged config, the `@kirill.konshin/lint/lint-staged` entry. Import it from there, not the package root:
|
|
4
|
+
* the root loads every ESLint plugin, which would slow down each commit.
|
|
5
|
+
*
|
|
6
|
+
* Markup goes to Prettier only: no block of this config lints it, so ESLint would skip it with a warning, after its
|
|
7
|
+
* full startup.
|
|
8
|
+
*
|
|
9
|
+
* Tasks run the `eslint` / `prettier` package.json scripts (README), so their flags live in one place, through
|
|
10
|
+
* `node --run` rather than `yarn`: Yarn loads the whole project state before every script, seconds per commit.
|
|
11
|
+
*
|
|
12
|
+
* https://nextjs.org/docs/app/api-reference/config/eslint#running-lint-on-staged-files
|
|
13
|
+
*
|
|
14
|
+
* Pay extra attention when the configured globs overlap, and tasks make edits to files. Prettier and eslint might try
|
|
15
|
+
* to make changes to the same *.ts file at the same time, causing a race condition.
|
|
16
|
+
*
|
|
17
|
+
* https://github.com/lint-staged/lint-staged?tab=readme-ov-file#reformatting-the-code
|
|
18
|
+
* https://github.com/lint-staged/lint-staged/issues/775
|
|
19
|
+
* You don't need git add since lint-staged 10
|
|
20
|
+
*/
|
|
21
|
+
export declare const listStaged: LintStagedConfiguration;
|
|
22
|
+
//# sourceMappingURL=lintStaged.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"lintStaged.d.ts","sourceRoot":"","sources":["../src/lintStaged.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,IAAI,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAI5E;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,UAAU,EAAE,uBAGxB,CAAC"}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { markupExtsRaw, prettierExtsRaw, tsExts } from './exts.js';
|
|
2
|
+
/**
|
|
3
|
+
* Shared lint-staged config, the `@kirill.konshin/lint/lint-staged` entry. Import it from there, not the package root:
|
|
4
|
+
* the root loads every ESLint plugin, which would slow down each commit.
|
|
5
|
+
*
|
|
6
|
+
* Markup goes to Prettier only: no block of this config lints it, so ESLint would skip it with a warning, after its
|
|
7
|
+
* full startup.
|
|
8
|
+
*
|
|
9
|
+
* Tasks run the `eslint` / `prettier` package.json scripts (README), so their flags live in one place, through
|
|
10
|
+
* `node --run` rather than `yarn`: Yarn loads the whole project state before every script, seconds per commit.
|
|
11
|
+
*
|
|
12
|
+
* https://nextjs.org/docs/app/api-reference/config/eslint#running-lint-on-staged-files
|
|
13
|
+
*
|
|
14
|
+
* Pay extra attention when the configured globs overlap, and tasks make edits to files. Prettier and eslint might try
|
|
15
|
+
* to make changes to the same *.ts file at the same time, causing a race condition.
|
|
16
|
+
*
|
|
17
|
+
* https://github.com/lint-staged/lint-staged?tab=readme-ov-file#reformatting-the-code
|
|
18
|
+
* https://github.com/lint-staged/lint-staged/issues/775
|
|
19
|
+
* You don't need git add since lint-staged 10
|
|
20
|
+
*/
|
|
21
|
+
export const listStaged = {
|
|
22
|
+
[`*.{${prettierExtsRaw},${markupExtsRaw}}`]: ['node --run prettier --'],
|
|
23
|
+
[`*.${tsExts}`]: ['node --run eslint --', 'node --run prettier --'],
|
|
24
|
+
};
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { Config as PrettierConfig } from 'prettier';
|
|
2
|
+
/**
|
|
3
|
+
* Shared Prettier config, the `@kirill.konshin/lint/prettier` entry. Import it from there, not the package root: the
|
|
4
|
+
* root loads every ESLint plugin, which would slow down each Prettier run.
|
|
5
|
+
*/
|
|
6
|
+
export declare const prettier: PrettierConfig;
|
|
7
|
+
//# sourceMappingURL=prettier.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"prettier.d.ts","sourceRoot":"","sources":["../src/prettier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,UAAU,CAAC;AAIzD;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,cAatB,CAAC"}
|
package/dist/prettier.js
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { eslintExts } from './exts.js';
|
|
2
|
+
/**
|
|
3
|
+
* Shared Prettier config, the `@kirill.konshin/lint/prettier` entry. Import it from there, not the package root: the
|
|
4
|
+
* root loads every ESLint plugin, which would slow down each Prettier run.
|
|
5
|
+
*/
|
|
6
|
+
export const prettier = {
|
|
7
|
+
printWidth: 120,
|
|
8
|
+
tabWidth: 2,
|
|
9
|
+
singleQuote: true,
|
|
10
|
+
proseWrap: 'never',
|
|
11
|
+
overrides: [
|
|
12
|
+
{
|
|
13
|
+
files: eslintExts,
|
|
14
|
+
options: {
|
|
15
|
+
tabWidth: 4,
|
|
16
|
+
},
|
|
17
|
+
},
|
|
18
|
+
],
|
|
19
|
+
};
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kirill.konshin/lint",
|
|
3
3
|
"description": "ESLint + Prettier + lint-staged config and AI agent rules/skills for monorepos",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.5.1",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"skipGenerate": true,
|
|
7
7
|
"bin": {
|
|
@@ -15,6 +15,16 @@
|
|
|
15
15
|
"types": "./dist/index.d.ts",
|
|
16
16
|
"import": "./dist/index.js"
|
|
17
17
|
},
|
|
18
|
+
"./lint-staged": {
|
|
19
|
+
"types": "./dist/lintStaged.d.ts",
|
|
20
|
+
"import": "./dist/lintStaged.js",
|
|
21
|
+
"default": "./dist/lintStaged.js"
|
|
22
|
+
},
|
|
23
|
+
"./prettier": {
|
|
24
|
+
"types": "./dist/prettier.d.ts",
|
|
25
|
+
"import": "./dist/prettier.js",
|
|
26
|
+
"default": "./dist/prettier.js"
|
|
27
|
+
},
|
|
18
28
|
"./yarn": {
|
|
19
29
|
"types": "./dist/yarn.d.cts",
|
|
20
30
|
"require": "./dist/yarn.cjs"
|
|
@@ -62,7 +72,9 @@
|
|
|
62
72
|
"glob": "^13.0.6",
|
|
63
73
|
"globals": "^17.11.0",
|
|
64
74
|
"jsonc-eslint-parser": "^3.3.0",
|
|
65
|
-
"local-pkg": "^1.2.1"
|
|
75
|
+
"local-pkg": "^1.2.1",
|
|
76
|
+
"path-scurry": "^2.0.2",
|
|
77
|
+
"yaml": "^2.9.0"
|
|
66
78
|
},
|
|
67
79
|
"devDependencies": {
|
|
68
80
|
"@types/eslint-plugin-jsx-a11y": "^6.10.1",
|
package/rules/agent.md
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: always_apply
|
|
3
|
+
description: Set of rules for agentic coding
|
|
4
|
+
# paths: # removed so ALL agents read it where to find information
|
|
5
|
+
# - '**/*.md'
|
|
6
|
+
# - 'openspec/config.yml'
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
IF IN DOUBT ASK USER!
|
|
10
|
+
|
|
11
|
+
# What Goes Where
|
|
12
|
+
|
|
13
|
+
Use this summarized guidance to consider where to place a set of instructions
|
|
14
|
+
|
|
15
|
+
- `README.md` — human-readable instructions how to work with repo
|
|
16
|
+
- Root `AGENTS.md` — default context for agents, always included
|
|
17
|
+
- Subdirectory `AGENTS.md` — scoped to this particular directory, auto-injected
|
|
18
|
+
- `.claude/rules` — forced rules (or automatic guardrails), that agent will read based on frontmatter, with paths scope; may pollute context if not scoped well; should NOT have detailed guidance, examples, etc.
|
|
19
|
+
- `rules/` referred from `AGENTS.md` — simple decomposition to clear up default context from specific / scoped / rarely used instructions, no frontmatter
|
|
20
|
+
- `.claude/skills` or `.codex/skills` — one-off flows, potentially complex; but also sets of rules that agent may or may not read/follow, good for progressive disclosure, examples, thorough guidance, and has to be well-defined in frontmatter to increase likelihood of success, example: https://www.skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
|
|
21
|
+
- `.claude/commands` — one-off commands, usually simpler than skills
|
|
22
|
+
- `openspec/specs` - SDD specifications, should define user facing behavior or API contracts, not coding instructions / best practices / etc.
|
|
23
|
+
- `openspec/config.yml#context` - should only have very narrow rules for OpenSpec specifically, when user entered flow
|
|
24
|
+
- `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
|
|
25
|
+
- `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of rules specifically for defined part of the flow when it's entered
|
|
26
|
+
|
|
27
|
+
# Placement Decision
|
|
28
|
+
|
|
29
|
+
When deciding where information belongs, use this order:
|
|
30
|
+
|
|
31
|
+
1. Is it durable observable system/component behavior?
|
|
32
|
+
- → **`openspec/specs`**
|
|
33
|
+
2. Must the agent always know it when touching a deterministically identifiable set of files?
|
|
34
|
+
- → **scoped `.claude/rules`**
|
|
35
|
+
3. Is it mandatory repo-wide or directory-wide context/routing?
|
|
36
|
+
- → **`AGENTS.md`**
|
|
37
|
+
4. Is it detailed knowledge, guidance, examples, best practices, or a reusable procedure that should be progressively disclosed?
|
|
38
|
+
- **→ skill**
|
|
39
|
+
5. Is it merely supporting material extracted from `AGENTS.md` to reduce default context?
|
|
40
|
+
- **→ `rules/`**, referenced explicitly from `AGENTS.md`
|
|
41
|
+
6. Is it primarily documentation for humans?
|
|
42
|
+
- **→ `README.md`**
|
|
43
|
+
|
|
44
|
+
When correctness depends on an instruction being observed, do NOT rely solely on skill discovery.
|
|
45
|
+
|
|
46
|
+
Prefer one authoritative location for each concern. Reference it elsewhere instead of duplicating it.
|
|
47
|
+
|
|
48
|
+
# `README.md`
|
|
49
|
+
|
|
50
|
+
- Should be targeted to be read by humans
|
|
51
|
+
- First file that's visible to humans
|
|
52
|
+
|
|
53
|
+
# `.claude/rules` and `.codex/rules`
|
|
54
|
+
|
|
55
|
+
- Can itself be a link to rules from a package; or individual files inside can be symlinks
|
|
56
|
+
- Must be accompanied by symlink `.codex/rules`
|
|
57
|
+
- Files should be scoped to certain paths
|
|
58
|
+
- Files should be small,
|
|
59
|
+
- Examples not allowed in general
|
|
60
|
+
- Should describe only coding conventions, recommendations, forced contextual instructions / automatic guardrails
|
|
61
|
+
- As bullet points
|
|
62
|
+
- Concise, terse and to the point
|
|
63
|
+
- Hard constraints
|
|
64
|
+
- That must appear in scope by `paths` glob
|
|
65
|
+
|
|
66
|
+
# `AGENTS.md`
|
|
67
|
+
|
|
68
|
+
- Root `AGENTS.md`
|
|
69
|
+
- Should be minimalistic and should refer to `rules/xxx.md` in order not to pollute default context if
|
|
70
|
+
- Can be decomposed as references to files in `rules/` folder also located at repo root
|
|
71
|
+
- Folder has no semantics of its own; it is not a standard but merely a convention for progressive-disclosure documentation referenced by AGENTS.md.
|
|
72
|
+
- Files in `rules/` should be referred conditionally, e.g. with minimal explanation what's inside so agent has better chances of reaching them
|
|
73
|
+
- Frontmatter not supported
|
|
74
|
+
- Decomposition should be used when
|
|
75
|
+
- Section is narrowly scoped (installation instructions / testing / particular framework or technology) and not always applicable
|
|
76
|
+
- Section is large
|
|
77
|
+
- `AGENTS.md` can refer to `README.md` in order not to restate things
|
|
78
|
+
- Repo-wide convention to use SDD should be defined here to be always visible
|
|
79
|
+
- Focus on mandatory routing and instructions
|
|
80
|
+
- Sub-directory `AGENTS.md`
|
|
81
|
+
- Directory-specific rules should be in `AGENTS.md` of that folder
|
|
82
|
+
- Lift rules up the tree to higher `AGENTS.md` if multiple dirs must adhere to rules, don't copy-paste them
|
|
83
|
+
- All `AGENTS.md` files should be accompanied by a symlink `CLAUDE.md`
|
|
84
|
+
|
|
85
|
+
# `.claude/skills` and `.codex/skills`
|
|
86
|
+
|
|
87
|
+
- May define either
|
|
88
|
+
- A workflow
|
|
89
|
+
- A process
|
|
90
|
+
- A set of rules
|
|
91
|
+
- Best practices
|
|
92
|
+
- Examples
|
|
93
|
+
- Engineering knowledge
|
|
94
|
+
- Agent decides to discover it or not, use it or not, so no guarantee of honoring
|
|
95
|
+
- A requirement/rule MUST NOT exist only in a skill if correctness depends on the agent always observing it
|
|
96
|
+
|
|
97
|
+
# `.claude/commands`
|
|
98
|
+
|
|
99
|
+
- Smaller and simpler than skills
|
|
100
|
+
- One-off commands, not flows
|
|
101
|
+
|
|
102
|
+
# `openspec`
|
|
103
|
+
|
|
104
|
+
- `OpenSpec` / `SpecKit` and similar SDD specifications should define
|
|
105
|
+
- User facing or externally observable behavior
|
|
106
|
+
- Durable component/system/API contracts & invariants
|
|
107
|
+
- Not general coding instructions
|
|
108
|
+
- Openspec-specific instructions must assume that flow WAS ENTERED, thus `AGENTS.md` or `[.claude|.codex]/skills` must be used to define how to enter the flow, and how flow should look like from outside perspective (without details)
|
|
109
|
+
- `openspec/config.yml#context` - should only have very narrow rules for OpenSpec specifically, when user entered flow
|
|
110
|
+
- Context will already contain root `AGENTS.md`, no duplication needed
|
|
111
|
+
- `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
|
|
112
|
+
- `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of rules specifically for defined part of the flow when it's entered
|
|
113
|
+
|
|
114
|
+
# Common rules for `.claude/rules`, `.codex/rules`, `AGENTS.md` and `rules/`
|
|
115
|
+
|
|
116
|
+
- If project uses Spec Driven Development framework like OpenSpec, these files should be free from product specifications / external behavior, and only focused on general coding instructions
|
|
117
|
+
- Preferred syntax rules to structure plain human language: `EARS` for requirements and `BDD` (Given/When/Then) for scenarios
|
package/rules/auth.md
CHANGED
package/rules/code-style.md
CHANGED
package/rules/db.md
CHANGED
|
@@ -10,8 +10,7 @@ description: Database persistence and migration rules
|
|
|
10
10
|
|
|
11
11
|
# Postgres
|
|
12
12
|
|
|
13
|
-
- Use
|
|
14
|
-
- Prefer Neon HTTP for simple stateless operations; use the pooled serverless driver for transactions, migrations, and connection-oriented work.
|
|
13
|
+
- Use Drizzle as ORM if user asks to add ORM
|
|
15
14
|
- Keep schemas, repositories, tenancy, and authorization app-owned; keep reusable driver plumbing in `@kirill.konshin/db`.
|
|
16
15
|
- Import `@kirill.konshin/db` through focused driver, migration, URL, and type subpaths so unrelated drivers are not loaded.
|
|
17
16
|
- Keep database access server-only and separate the database/repository layer from API, UI, and state-management layers.
|
|
@@ -20,9 +19,16 @@ description: Database persistence and migration rules
|
|
|
20
19
|
- Validate inputs at the application boundary and enforce critical invariants again in Postgres.
|
|
21
20
|
- Use `DATABASE_URL` at runtime; prefer `DATABASE_URL_UNPOOLED` for migrations and maintenance when available.
|
|
22
21
|
- Close owned pools in `finally`; do not leak clients or hide ownership of long-lived connections.
|
|
23
|
-
- Fold Neon Auth into [Iron Session](./auth.md): link identity server-side, store app context in the sealed session, then clear the transient Neon session.
|
|
24
22
|
- Enforce user and tenant scope on every read and mutation; authentication alone is not authorization.
|
|
25
23
|
- For LocalStorage or IndexedDB migrations, preserve behavior but improve the schema when normalization or consolidation is clearly safer.
|
|
26
24
|
- Make importers transactional, validated, idempotent, and count-verifiable; never delete server data merely because a mutable export became smaller.
|
|
27
25
|
- Keep one-off data transfers out of permanent migration machinery; verify source, destination, schema, counts, and runtime connectivity.
|
|
28
26
|
- After schema changes, generate migrations, confirm no drift, migrate a disposable database in tests, and run typecheck/build/tests.
|
|
27
|
+
|
|
28
|
+
# Neon
|
|
29
|
+
|
|
30
|
+
Only applies if user specifically asked to add Neon as DB, or project already uses Neon as DB.
|
|
31
|
+
|
|
32
|
+
- Prefer Neon HTTP for simple stateless operations; use the pooled serverless driver for transactions, migrations, and connection-oriented work.
|
|
33
|
+
- Use Neon Postgres with Drizzle and checked-in generated migrations.
|
|
34
|
+
- Fold Neon Auth into [Iron Session](./auth.md): link identity server-side, store app context in the sealed session, then clear the transient Neon session.
|
package/rules/electron.md
CHANGED
package/rules/i18n.md
CHANGED
package/rules/jest.md
CHANGED
|
@@ -7,3 +7,4 @@ paths:
|
|
|
7
7
|
|
|
8
8
|
- Always prefer TS-based config. Choice of loader is dictated by other installed packages, https://jestjs.io/docs/configuration (first tip about loaders)
|
|
9
9
|
- In monorepo define root jest project https://jestjs.io/docs/configuration#projects-arraystring--projectconfig
|
|
10
|
+
- Prefer Vitest instead of Jest
|
package/rules/nx.md
CHANGED
package/rules/turbo.md
CHANGED
package/rules/typescript.md
CHANGED
package/rules/webstorm.md
CHANGED
|
@@ -203,13 +203,18 @@ Ban build directories from search using examples:
|
|
|
203
203
|
`.idea/%projectName%.iml`, `.idea/modules.xml` and `.idea/.name` are usually tracked. Every git worktree therefore checks out a module with the same name as the main checkout's, and WebStorm refuses to attach it: `Cannot attach project: Module name '%projectName%' already exists`.
|
|
204
204
|
|
|
205
205
|
- When creating a worktree, ALWAYS give it a distinct module and project name derived from the branch, e.g. `Packing Travel App` for `travel-app`:
|
|
206
|
-
1.
|
|
207
|
-
2. Point `.idea/modules.xml` at the
|
|
206
|
+
1. **Rename** — do not copy — `.idea/%projectName%.iml` to `.idea/%projectName% %Branch Title%.iml`. The module name is the file name, and attaching the worktree registers whichever `.iml` it finds: a copy beside the original still attaches as `%projectName%`.
|
|
207
|
+
2. Point `.idea/modules.xml` at the renamed file.
|
|
208
208
|
3. Write the same name into `.idea/.name`.
|
|
209
|
+
4. A main project the worktree is attached to lists it in its own `.idea/modules.xml`: point that entry at the renamed file too.
|
|
209
210
|
- Keep the rename local, and NEVER commit it or merge it back:
|
|
210
|
-
-
|
|
211
|
-
- Ignore the
|
|
212
|
-
-
|
|
213
|
-
|
|
214
|
-
|
|
211
|
+
- The tracked `.iml` first: stage the branch's own edits to it (`git add .idea/%projectName%.iml`), then `git update-index --skip-worktree .idea/%projectName%.iml`, then rename. The staged content is what the branch commits; the rename never shows as a deletion. An edit the branch later makes to the renamed file has to be staged back the same way.
|
|
212
|
+
- Ignore the renamed file in the shared `.git/info/exclude` with the pattern `.idea/%projectName% *.iml`.
|
|
213
|
+
- A **tracked** `.idea/modules.xml` or `.idea/.name`: run `git update-index --skip-worktree` on it.
|
|
214
|
+
- An **untracked** one (often `modules.xml` is in `.idea/.gitignore` and `.name` does not exist yet): `skip-worktree` fails on it, so leave it to `.idea/.gitignore` or add it to the shared `.git/info/exclude` as well (e.g. `.idea/.name`).
|
|
215
|
+
- Verify with `git status --short .idea`: nothing from the rename is listed, only the staged edits.
|
|
216
|
+
- Before a rebase, merge or checkout that updates those files (tracked ones only):
|
|
217
|
+
1. Rename the `.iml` back and run `git update-index --no-skip-worktree` on every file marked above.
|
|
218
|
+
2. Restore them with `git checkout -- <files>`.
|
|
215
219
|
3. Redo the rename afterwards.
|
|
220
|
+
- A worktree created **inside** the main checkout (e.g. `.claude/worktrees/<name>`, where agents put theirs) is indexed by the main project as part of itself, a second copy of every source and `node_modules`, and the main project's save actions start reformatting the worktree's files. Exclude its folder in the main checkout's `.idea/%projectName%.iml` (`<excludeFolder url="file://$MODULE_DIR$/.claude/worktrees" />`) and list it in `.gitignore`, so the folder rule under [GitIgnore](#gitignore) holds. Attaching such a worktree can replace the main checkout's own entry in its `.idea/modules.xml`: keep both — the main `.idea/%projectName%.iml` and the worktree's renamed one — then reload the project. A nested worktree shows as its own module node inside the tree, not as a separate top-level project; for a top-level entry, create the worktree outside the main checkout.
|