@kirill.konshin/lint 0.1.0

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/lintPrepare.js ADDED
@@ -0,0 +1,326 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * @kirill.konshin/lint
5
+ *
6
+ * This script symlinks all markdown rule files from the package into the consuming
7
+ * project's `.claude/rules` directory (auto-discovered by Claude Code), symlinks every
8
+ * package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/` (SKILL.md plus
9
+ * the package README.md alongside it, so a skill can reference `@README.md`), and generates
10
+ * an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
11
+ *
12
+ * Usage:
13
+ * lint-prepare init - Initialize AGENTS.md in the current directory (default)
14
+ * lint-prepare update - Force update AGENTS.md even if it exists
15
+ * lint-prepare - Same as init
16
+ *
17
+ * The module also exports its functions and only runs `main()` when executed directly,
18
+ * so it can be imported (for testing/reuse) without side effects.
19
+ */
20
+
21
+ import fs from 'node:fs';
22
+ import path from 'node:path';
23
+ import { fileURLToPath, pathToFileURL } from 'node:url';
24
+
25
+ const __filename = fileURLToPath(import.meta.url);
26
+ const __dirname = path.dirname(__filename);
27
+
28
+ const AGENTS_FILE = 'AGENTS.md';
29
+ const CLAUDE_FILE = 'CLAUDE.md';
30
+ const CLAUDE_RULES_DIR = '.claude/rules';
31
+ const RULES_DIR = path.join(__dirname, 'rules');
32
+ const SKILLS_DIR = path.join(__dirname, 'skills');
33
+ const README_FILE = path.join(__dirname, 'README.md');
34
+ const SKILLS_TARGET_DIRS = ['.claude/skills', '.codex/skills'];
35
+ const HEADER = `# AI Agent Rules
36
+
37
+ This file is auto-generated by @kirill.konshin/lint. Do not edit directly - customize by adding your own rules below the generated section.
38
+
39
+ ---`;
40
+
41
+ const FOOTER = `
42
+ ---
43
+
44
+ # Custom Rules
45
+
46
+ Add your project-specific rules below the comment line.`;
47
+
48
+ const GENERATED_MARKER = '<!-- @kirill.konshin/lint:generated -->';
49
+
50
+ /**
51
+ * Read all markdown files from the package rules directory.
52
+ */
53
+ export function readRules() {
54
+ const rules = [];
55
+
56
+ if (!fs.existsSync(RULES_DIR)) {
57
+ console.error(`Rules directory not found: ${RULES_DIR}`);
58
+ process.exit(1);
59
+ }
60
+
61
+ const files = fs
62
+ .readdirSync(RULES_DIR)
63
+ .filter((f) => f.endsWith('.md'))
64
+ .sort();
65
+
66
+ for (const file of files) {
67
+ const filePath = path.join(RULES_DIR, file);
68
+ const content = fs.readFileSync(filePath, 'utf-8');
69
+ rules.push({
70
+ file,
71
+ name: file.replace('.md', ''),
72
+ content,
73
+ });
74
+ }
75
+
76
+ return rules;
77
+ }
78
+
79
+ /**
80
+ * Read all markdown files from the package skills directory. Each file becomes its own skill, named after the file
81
+ * (without extension) - e.g. `lint-repo.md` becomes the `lint-repo` skill.
82
+ */
83
+ export function readSkills() {
84
+ if (!fs.existsSync(SKILLS_DIR)) return [];
85
+
86
+ return fs
87
+ .readdirSync(SKILLS_DIR)
88
+ .filter((f) => f.endsWith('.md'))
89
+ .sort()
90
+ .map((file) => ({ file, name: file.replace('.md', '') }));
91
+ }
92
+
93
+ /**
94
+ * Fail if `.claude/rules` contains anything that isn't a symlink - we don't want to
95
+ * silently blow away a real file/directory a user placed there by hand.
96
+ */
97
+ export function checkRulesDirSafety(rulesTargetDir) {
98
+ if (!fs.existsSync(rulesTargetDir)) return;
99
+
100
+ for (const entry of fs.readdirSync(rulesTargetDir)) {
101
+ const entryPath = path.join(rulesTargetDir, entry);
102
+
103
+ if (!fs.lstatSync(entryPath).isSymbolicLink()) {
104
+ console.error(`${CLAUDE_RULES_DIR}/${entry} exists and is not a symlink.`);
105
+ console.error('Remove or back it up manually, then re-run.');
106
+ process.exit(1);
107
+ }
108
+ }
109
+ }
110
+
111
+ /**
112
+ * Fail if `CLAUDE.md` exists and isn't a symlink - same reasoning as checkRulesDirSafety.
113
+ */
114
+ export function checkClaudeMdSafety(claudeMdPath) {
115
+ let stat;
116
+
117
+ try {
118
+ stat = fs.lstatSync(claudeMdPath);
119
+ } catch {
120
+ return;
121
+ }
122
+
123
+ if (!stat.isSymbolicLink()) {
124
+ console.error(`${CLAUDE_FILE} exists and is not a symlink.`);
125
+ console.error('Remove or back it up manually, then re-run.');
126
+ process.exit(1);
127
+ }
128
+ }
129
+
130
+ /**
131
+ * Symlink rules into the consuming project's `.claude/rules` directory.
132
+ * Safe to wipe and recreate: checkRulesDirSafety already guaranteed every existing
133
+ * entry is a symlink.
134
+ *
135
+ * FIXME Codex Includes
136
+ * https://github.com/openai/codex/issues/17401
137
+ * https://github.com/openai/codex/issues/6038
138
+ * 32kb limit https://github.com/openai/codex/issues/13386
139
+ *
140
+ * TODO: generate `.claude/CLAUDE.md` with an index of the symlinked rules, for humans browsing `.claude/rules` manually
141
+ * (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
142
+ * indexed anywhere).
143
+ */
144
+ export function symlinkRules(cwd, rules) {
145
+ const targetDir = path.join(cwd, CLAUDE_RULES_DIR);
146
+
147
+ fs.rmSync(targetDir, { recursive: true, force: true });
148
+ fs.mkdirSync(targetDir, { recursive: true });
149
+
150
+ for (const rule of rules) {
151
+ const source = path.join(RULES_DIR, rule.file);
152
+ const linkPath = path.join(targetDir, rule.file);
153
+ fs.symlinkSync(path.relative(targetDir, source), linkPath);
154
+ }
155
+
156
+ return targetDir;
157
+ }
158
+
159
+ /**
160
+ * Fail if a skill's target directory (e.g. `.claude/skills/lint-repo`) contains anything
161
+ * that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
162
+ * own subdirectory is checked/wiped, not the whole `.claude/skills` or `.codex/skills`
163
+ * parent, since other packages (or the user) may keep unrelated skills there.
164
+ */
165
+ export function checkSkillDirSafety(skillDir) {
166
+ if (!fs.existsSync(skillDir)) return;
167
+
168
+ for (const entry of fs.readdirSync(skillDir)) {
169
+ const entryPath = path.join(skillDir, entry);
170
+
171
+ if (!fs.lstatSync(entryPath).isSymbolicLink()) {
172
+ console.error(`${skillDir}/${entry} exists and is not a symlink.`);
173
+ console.error('Remove or back it up manually, then re-run.');
174
+ process.exit(1);
175
+ }
176
+ }
177
+ }
178
+
179
+ /**
180
+ * Symlink each package skill into `<cwd>/.claude/skills/<name>/` and
181
+ * `<cwd>/.codex/skills/<name>/`, so both Claude Code and Codex CLI can discover and run
182
+ * them. The package README.md is symlinked alongside SKILL.md so a skill can reference it
183
+ * via `@README.md` regardless of how the tool resolves relative mentions.
184
+ */
185
+ export function symlinkSkills(cwd, skills) {
186
+ const targetDirs = [];
187
+ const hasReadme = fs.existsSync(README_FILE);
188
+
189
+ for (const skill of skills) {
190
+ for (const targetRoot of SKILLS_TARGET_DIRS) {
191
+ const skillDir = path.join(cwd, targetRoot, skill.name);
192
+
193
+ checkSkillDirSafety(skillDir);
194
+
195
+ fs.rmSync(skillDir, { recursive: true, force: true });
196
+ fs.mkdirSync(skillDir, { recursive: true });
197
+
198
+ const source = path.join(SKILLS_DIR, skill.file);
199
+ const linkPath = path.join(skillDir, 'SKILL.md');
200
+ fs.symlinkSync(path.relative(skillDir, source), linkPath);
201
+
202
+ if (hasReadme) {
203
+ const readmeLink = path.join(skillDir, 'README.md');
204
+ fs.symlinkSync(path.relative(skillDir, README_FILE), readmeLink);
205
+ }
206
+
207
+ targetDirs.push(skillDir);
208
+ }
209
+ }
210
+
211
+ return targetDirs;
212
+ }
213
+
214
+ /**
215
+ * Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
216
+ */
217
+ export function symlinkClaudeMd(cwd) {
218
+ const claudeMdPath = path.join(cwd, CLAUDE_FILE);
219
+
220
+ fs.rmSync(claudeMdPath, { force: true });
221
+ fs.symlinkSync(AGENTS_FILE, claudeMdPath);
222
+ }
223
+
224
+ /**
225
+ * Generate AGENTS.md with references to the rule files.
226
+ *
227
+ * `.claude/rules/*.md` are symlinked by symlinkRules() above and auto-discovered by
228
+ * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
229
+ * under `.claude/rules`, symlinks included) - no reference to them is needed here.
230
+ * The sections below are for other tools that only read AGENTS.md.
231
+ */
232
+ export function generateAgentsFile(rules, cwd, customSection) {
233
+ const relativeRulesDir = path.relative(cwd, RULES_DIR).split(path.sep).join('/');
234
+
235
+ const includes = rules.map((rule) => `@include ${relativeRulesDir}/${rule.file}`).join('\n');
236
+
237
+ const links = rules.map((rule) => `- [${rule.file}](${relativeRulesDir}/${rule.file})`).join('\n');
238
+
239
+ const generated = `${HEADER}\n\n${includes}\n\n${links}\n\n${FOOTER}\n\n${GENERATED_MARKER}`;
240
+
241
+ return customSection ? `${generated}\n\n${customSection}\n` : `${generated}\n`;
242
+ }
243
+
244
+ /**
245
+ * Check if AGENTS.md exists and was generated by this tool. When it was, also return
246
+ * whatever follows the marker (the user's custom section) so it can be carried forward -
247
+ * generateAgentsFile() always rebuilds the part above the marker from scratch, but must
248
+ * never touch what a user wrote below it.
249
+ */
250
+ export function checkExisting(targetPath) {
251
+ if (!fs.existsSync(targetPath)) {
252
+ return { exists: false, generated: false, customSection: null };
253
+ }
254
+
255
+ const content = fs.readFileSync(targetPath, 'utf-8');
256
+ const markerIndex = content.indexOf(GENERATED_MARKER);
257
+ const generated = markerIndex !== -1;
258
+ const customSection = generated ? content.slice(markerIndex + GENERATED_MARKER.length).trim() : null;
259
+
260
+ return { exists: true, generated, customSection };
261
+ }
262
+
263
+ /**
264
+ * Main function
265
+ */
266
+ export function main() {
267
+ const args = process.argv.slice(2);
268
+ const command = args[0] || 'init';
269
+ const cwd = process.env.INIT_CWD || process.cwd();
270
+ const targetPath = path.join(cwd, AGENTS_FILE);
271
+ const claudeMdPath = path.join(cwd, CLAUDE_FILE);
272
+ const rulesTargetDir = path.join(cwd, CLAUDE_RULES_DIR);
273
+
274
+ console.log(`@kirill.konshin/lint: ${command}`);
275
+ console.log(`Target: ${targetPath}`);
276
+
277
+ const { exists, generated, customSection } = checkExisting(targetPath);
278
+
279
+ if (command === 'init') {
280
+ if (exists && !generated) {
281
+ console.log(`${AGENTS_FILE} exists and was not generated by this tool. Skipping.`);
282
+ console.log('Use "lint-prepare update" to force overwrite, then merge manually.');
283
+ return;
284
+ }
285
+
286
+ if (exists && generated) {
287
+ console.log(`${AGENTS_FILE} exists and was generated by this tool. Updating...`);
288
+ }
289
+ }
290
+
291
+ if (command === 'update' || command === 'init') {
292
+ checkRulesDirSafety(rulesTargetDir);
293
+ checkClaudeMdSafety(claudeMdPath);
294
+
295
+ const rules = readRules();
296
+ console.log(`Found ${rules.length} rule files: ${rules.map((r) => r.name).join(', ')}`);
297
+
298
+ const targetRulesDir = symlinkRules(cwd, rules);
299
+ console.log(`Symlinked rules to ${targetRulesDir}`);
300
+
301
+ const skills = readSkills();
302
+ console.log(`Found ${skills.length} skill(s): ${skills.map((s) => s.name).join(', ')}`);
303
+
304
+ const targetSkillDirs = symlinkSkills(cwd, skills);
305
+ for (const targetSkillDir of targetSkillDirs) {
306
+ console.log(`Symlinked skill to ${targetSkillDir}`);
307
+ }
308
+
309
+ const content = generateAgentsFile(rules, cwd, customSection);
310
+ fs.writeFileSync(targetPath, content, 'utf-8');
311
+ console.log(`${exists ? 'Updated' : 'Created'} ${AGENTS_FILE}`);
312
+
313
+ symlinkClaudeMd(cwd);
314
+ console.log(`Symlinked ${CLAUDE_FILE} -> ${AGENTS_FILE}`);
315
+ return;
316
+ }
317
+
318
+ console.log(`Unknown command: ${command}`);
319
+ console.log('Usage: lint-prepare [init|update]');
320
+ process.exit(1);
321
+ }
322
+
323
+ // Only run when executed directly (e.g. `lint-prepare init`), not when imported.
324
+ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
325
+ main();
326
+ }
package/package.json ADDED
@@ -0,0 +1,94 @@
1
+ {
2
+ "name": "@kirill.konshin/lint",
3
+ "description": "ESLint + Prettier + lint-staged config and AI agent rules/skills for monorepos",
4
+ "version": "0.1.0",
5
+ "type": "module",
6
+ "skipGenerate": true,
7
+ "bin": {
8
+ "lint-prepare": "./lintPrepare.js"
9
+ },
10
+ "main": "index.js",
11
+ "module": "index.js",
12
+ "scripts": {
13
+ "----- BUILD -----": "",
14
+ "clean": "rm -rf dist .tscache tsconfig.tsbuildinfo",
15
+ "build": "echo 'No build required'",
16
+ "start": "echo 'No start required'",
17
+ "----- TEST -----": "",
18
+ "test": "echo 'No tests yet'"
19
+ },
20
+ "files": [
21
+ "index.js",
22
+ "lintPrepare.js",
23
+ "ruleTestColocation.js",
24
+ "rules",
25
+ "skills"
26
+ ],
27
+ "dependencies": {
28
+ "@eslint/compat": "^2.0.3",
29
+ "@eslint/js": "^10.0.1",
30
+ "@next/eslint-plugin-next": "^16.2.1",
31
+ "@nx/eslint-plugin": "^23.1.0",
32
+ "@typescript-eslint/eslint-plugin": "^8.57.2",
33
+ "@typescript-eslint/parser": "^8.57.2",
34
+ "@vitest/eslint-plugin": "^1.6.23",
35
+ "eslint-config-next": "^16.2.1",
36
+ "eslint-config-prettier": "^10.1.8",
37
+ "eslint-import-resolver-typescript": "^4.4.5",
38
+ "eslint-plugin-import-x": "^4.17.1",
39
+ "eslint-plugin-jest": "^29.15.4",
40
+ "eslint-plugin-jsx-a11y": "^6.10.2",
41
+ "eslint-plugin-promise": "^7.3.0",
42
+ "eslint-plugin-react": "^7.37.5",
43
+ "eslint-plugin-react-hooks": "^7.0.1",
44
+ "eslint-plugin-simple-import-sort": "^14.0.0",
45
+ "eslint-plugin-storybook": "^10.5.2",
46
+ "eslint-plugin-turbo": "^2.10.5",
47
+ "eslint-plugin-unicorn": "^72.0.0",
48
+ "eslint-plugin-unused-imports": "^4.4.1",
49
+ "globals": "^16.4.0",
50
+ "jsonc-eslint-parser": "^2.4.2"
51
+ },
52
+ "peerDependencies": {
53
+ "eslint": "^10",
54
+ "husky": "^9",
55
+ "jest": "*",
56
+ "lint-staged": "^16",
57
+ "next": "^16",
58
+ "storybook": "^10.5.2",
59
+ "vite": "*",
60
+ "vitest": "*"
61
+ },
62
+ "peerDependenciesMeta": {
63
+ "jest": {
64
+ "optional": true
65
+ },
66
+ "next": {
67
+ "optional": true
68
+ },
69
+ "storybook": {
70
+ "optional": true
71
+ },
72
+ "vite": {
73
+ "optional": true
74
+ },
75
+ "vitest": {
76
+ "optional": true
77
+ }
78
+ },
79
+ "publishConfig": {
80
+ "access": "public"
81
+ },
82
+ "author": "Kirill Konshin <kirill@konshin.org> (https://konshin.org)",
83
+ "license": "MIT",
84
+ "repository": {
85
+ "type": "git",
86
+ "url": "https://github.com/kirill-konshin/utils.git",
87
+ "directory": "packages/lint"
88
+ },
89
+ "nx": {
90
+ "tags": [
91
+ "platform:tooling"
92
+ ]
93
+ }
94
+ }
@@ -0,0 +1,50 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+
4
+ const SOURCE_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs', '.cts', '.cjs'];
5
+ const TEST_SUFFIX = new RegExp(`\\.test\\.(${SOURCE_EXTS.map((ext) => ext.slice(1)).join('|')})$`);
6
+
7
+ /**
8
+ * Only `*.test.*` is checked, not `*.spec.*` - per testing.md, spec files cover e2e/integration
9
+ * flows that don't map 1:1 to a single sibling source file, so co-location isn't meaningful there.
10
+ */
11
+ export const testColocation = {
12
+ meta: {
13
+ type: 'problem',
14
+ docs: {
15
+ description: 'require *.test.* files to sit next to the source file they test, not in a separate folder',
16
+ },
17
+ schema: [],
18
+ messages: {
19
+ missingSibling:
20
+ "No sibling source file found for '{{testFile}}'. Expected e.g. '{{expected}}' in the same directory, not a separate __tests__/ folder.",
21
+ },
22
+ },
23
+ create(context) {
24
+ const base = path.basename(context.filename);
25
+ const match = base.match(TEST_SUFFIX);
26
+
27
+ if (!match) return {};
28
+
29
+ const stem = base.slice(0, -match[0].length);
30
+
31
+ let siblings;
32
+ try {
33
+ siblings = fs.readdirSync(path.dirname(context.filename));
34
+ } catch {
35
+ return {}; // virtual filename (stdin, editor buffer) - no directory to check against
36
+ }
37
+
38
+ if (SOURCE_EXTS.some((ext) => siblings.includes(`${stem}${ext}`))) return {};
39
+
40
+ return {
41
+ Program(node) {
42
+ context.report({
43
+ node,
44
+ messageId: 'missingSibling',
45
+ data: { testFile: base, expected: `${stem}.ts` },
46
+ });
47
+ },
48
+ };
49
+ },
50
+ };
@@ -0,0 +1,6 @@
1
+ ---
2
+ type: always_apply
3
+ description: Set of rules for ALL projects
4
+ ---
5
+
6
+ - When generating code respect max length set in `.editorconfig` or `.prettierrc` (could be with extension)
@@ -0,0 +1,25 @@
1
+ ---
2
+ type: always_apply
3
+ description: Set of rules for projects which use Expo
4
+ ---
5
+
6
+ # CI Builds
7
+
8
+ ```yml
9
+ variables:
10
+ USE_HARD_LINKS: 'false' # https://github.com/electron-userland/electron-builder/issues/3179#issuecomment-408347702
11
+
12
+ build:
13
+ image: macos-12-xcode-13
14
+ tags:
15
+ - shared-macos-amd64
16
+ script:
17
+ - yarn --immutable
18
+ - yarn build
19
+ - rm -rf electron/dist/mac # some cleanup to make artifacts leaner
20
+ only:
21
+ - master
22
+ artifacts:
23
+ paths:
24
+ - electron/dist
25
+ ```
package/rules/expo.md ADDED
@@ -0,0 +1,4 @@
1
+ ---
2
+ type: always_apply
3
+ description: Set of rules for projects which use Expo
4
+ ---
@@ -0,0 +1,71 @@
1
+ ---
2
+ type: always_apply
3
+ description: Set of rules for projects which use Github
4
+ paths:
5
+ - '**/.github/*.yml'
6
+ ---
7
+
8
+ # Example Workflow
9
+
10
+ ```yml
11
+ name: Release
12
+
13
+ on:
14
+ push:
15
+ branches:
16
+ - main
17
+
18
+ # If project publishes to NPM
19
+ permissions:
20
+ id-token: write # Required for OIDC
21
+ contents: read
22
+
23
+ concurrency: ${{ github.workflow }}-${{ github.ref }}
24
+
25
+ jobs:
26
+ release:
27
+ name: Release
28
+ runs-on: ubuntu-latest
29
+ env:
30
+ TURBO_CACHE_DIR: .turbo # if project uses Turbo
31
+
32
+ # If project publishes to NPM
33
+ # https://davistobias.com/articles/adding-changeset/#2.1.b-adding-changeset-to-github-workflows
34
+ if: github.repository == 'kirill-konshin/utils'
35
+ permissions:
36
+ id-token: write # Required for OIDC trusted publishing
37
+ contents: write
38
+ pull-requests: write
39
+
40
+ steps:
41
+ - name: Checkout Repo
42
+ uses: actions/checkout@v4
43
+
44
+ - name: Setup Node.js
45
+ uses: actions/setup-node@v6
46
+ with:
47
+ node-version: 26
48
+ registry-url: 'https://registry.npmjs.org'
49
+ cache: yarn
50
+ cache-dependency-path: yarn.lock
51
+
52
+ - name: Enable Corepack
53
+ run: corepack enable
54
+
55
+ - name: Install dependencies
56
+ run: yarn install --immutable
57
+
58
+ # Add this if Yarn 2+ is used and package is NOT private
59
+ - name: Prepare
60
+ run: yarn prepare
61
+
62
+ #TODO https://turbo.build/repo/docs/guides/ci-vendors/github-actions#remote-caching
63
+ #TODO https://turborepo.dev/docs/guides/ci-vendors/github-actions#remote-caching-with-github-actionscache
64
+ - name: Cache turbo build setup
65
+ uses: actions/cache@v4
66
+ with:
67
+ path: .turbo
68
+ key: ${{ runner.os }}-turbo-${{ github.sha }}
69
+ restore-keys: |
70
+ ${{ runner.os }}-turbo-
71
+ ```
@@ -0,0 +1,37 @@
1
+ ---
2
+ type: always_apply
3
+ description: Set of rules for projects which use Gitlab
4
+ paths:
5
+ - '**/.gitlab-ci.yml'
6
+ ---
7
+
8
+ - Always collect coverage from tests
9
+ - Always publish important build stats as artifacts
10
+
11
+ # Example
12
+
13
+ ```yml
14
+ build:
15
+ image: node:24
16
+ cache:
17
+ key:
18
+ files:
19
+ - yarn.lock
20
+ paths:
21
+ - .yarn/cache
22
+ - yarn.lock
23
+ - node_modules
24
+ - '**/node_modules'
25
+ - '**/.turbo'
26
+ - '**/.tscache'
27
+ - web/.next/cache
28
+ script:
29
+ - yarn --immutable
30
+ - yarn prepare # Add this if Yarn 2+ is used and package is NOT private
31
+ - yarn build
32
+ only:
33
+ - master
34
+ artifacts:
35
+ paths:
36
+ - web/build
37
+ ```
package/rules/i18n.md ADDED
@@ -0,0 +1,6 @@
1
+ ---
2
+ type: always_apply
3
+ description: I18n
4
+ ---
5
+
6
+ - When displaying date and time use `Intl.DateTimeFormat`.
package/rules/jest.md ADDED
@@ -0,0 +1,9 @@
1
+ ---
2
+ type: always_apply
3
+ description: Set of rules for projects with Jest
4
+ paths:
5
+ - '**/jest.config.{ts,js,mjs,cjs}'
6
+ ---
7
+
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
+ - In monorepo define root jest project https://jestjs.io/docs/configuration#projects-arraystring--projectconfig
@@ -0,0 +1,56 @@
1
+ ---
2
+ type: always_apply
3
+ description: Set of rules for MONOREPO projects which use Turbo or NX
4
+ paths:
5
+ - '**/turbo.json'
6
+ - '**/nx.json'
7
+ - '**/package.json'
8
+ - '**/project.json'
9
+ ---
10
+
11
+ - Existing projects may use what they use
12
+ - Root `package.json` defines:
13
+ - Public entrypoints for use in other tools (like `lint-staged`, CLI, Webstorm, CI) & useful presets
14
+ - Tasks to launch inner tasks (main `build` that launches `build` in each sub-package)
15
+ - Inner `package.json` MUST only define atomic orchestrator-agnostic tasks
16
+ - Prefer NX for new projects
17
+
18
+ # Task Consistency
19
+
20
+ ALWAYS verify `turbo.json` or `nx.json` task definitions when modifying scripts or package structure:
21
+
22
+ 1. **Task inheritance**: Common tasks like `build`, `clean`, `test`, `start`, `wait` should be defined in root `turbo.json` or `nx.json` and inherited by all packages
23
+ 2. **Package `turbo.json` or `nx.json` or `nx` section of `package.json`**: Only override when needed (e.g., adding `dependsOn` or custom `outputs`)
24
+ 3. **Check `dependsOn`**: Ensure build dependencies match actual package dependencies (e.g., `"dependsOn": ["^build"]` for packages that depend on other workspace packages)
25
+ 4. **Check `outputs`**: Must include all build artifacts (`dist/**/*`, `package.json`: all modified & generated files)
26
+ 5. **Cache settings**: `clean`, `wait`, `start` should have `"cache": false`
27
+
28
+ # The `dependsOn: ["^wait"]` Pattern
29
+
30
+ https://github.com/vercel/turborepo/issues/1497
31
+ https://github.com/vercel/turborepo/discussions/1299
32
+
33
+ Neither Turbo nor NX can run `persistent` or `continuous` dependent tasks in order. If package `A` depends on `B` and both have `start` command, in freshly checked out repo `A` will fail as `B` does not have anything built yet. Besides, two continuous tasks can't depend on each other as neither will ever exit. Options are:
34
+
35
+ 1. ❌ Build-then-start: waste of resources, since `start` will overwrite `build` and in most cases `build` cache is not useful, and `start` won't be smart enough by itself (DO NOT USE THIS APPROACH)
36
+ 2. ✅ Probe-before-start: condition `start` of `A` to wait for `B` to produce consumable artifacts
37
+
38
+ The `start` task uses `"dependsOn": ["^wait"]` (upstream):
39
+
40
+ ```json
41
+ {
42
+ "start": {
43
+ "persistent": true,
44
+ "cache": false,
45
+ "dependsOn": ["^wait"]
46
+ }
47
+ }
48
+ ```
49
+
50
+ ## How it works
51
+
52
+ 1. Package `A` has `"dependsOn": ["^wait"]`, which runs `wait` task of all upstream (dependency) packages
53
+ 2. Upstream package `B`'s `wait` task uses some probe, like `wait-on ./dist/index.js` or `wait-on http://localhost:3000` to block exit (must be defined in package `B`, so it can self-identify when it's ready)
54
+ 3. `B` also runs `"start": "build --watch"` task (for example) which produces `dist/index.js`
55
+ 4. Once the file exists, `B`'s `wait-on` unblocks and exits, and `A`'s `start` can proceed
56
+ 5. If file existed before, `A` starts immediately, the only issue could be `A`'s double-build if `B`'s `start` will eventually modify the file, causing `A`'s watcher to rebuild