@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/README.md +203 -0
- package/index.js +657 -0
- package/lintPrepare.js +326 -0
- package/package.json +94 -0
- package/ruleTestColocation.js +50 -0
- package/rules/code-style.md +6 -0
- package/rules/electron.md +25 -0
- package/rules/expo.md +4 -0
- package/rules/github.md +71 -0
- package/rules/gitlab.md +37 -0
- package/rules/i18n.md +6 -0
- package/rules/jest.md +9 -0
- package/rules/monorepo-turbo-nx.md +56 -0
- package/rules/mui.md +10 -0
- package/rules/nextjs.md +69 -0
- package/rules/npm-yarn.md +61 -0
- package/rules/nx.md +31 -0
- package/rules/react.md +87 -0
- package/rules/redux.md +4 -0
- package/rules/storybook.md +38 -0
- package/rules/tailwind.md +17 -0
- package/rules/testing.md +25 -0
- package/rules/turbo.md +58 -0
- package/rules/typescript.md +95 -0
- package/rules/vite.md +21 -0
- package/rules/webstorm.md +133 -0
- package/skills/lint-repo.md +58 -0
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,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
package/rules/github.md
ADDED
|
@@ -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
|
+
```
|
package/rules/gitlab.md
ADDED
|
@@ -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
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
|