@kirill.konshin/lint 0.3.5 → 0.4.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.
Files changed (60) hide show
  1. package/README.md +135 -56
  2. package/dist/configs/base.d.ts +29 -0
  3. package/dist/configs/base.d.ts.map +1 -0
  4. package/{configs → dist/configs}/base.js +7 -25
  5. package/dist/configs/imports.d.ts +21 -0
  6. package/dist/configs/imports.d.ts.map +1 -0
  7. package/{configs → dist/configs}/imports.js +0 -10
  8. package/dist/configs/nx.d.ts +16 -0
  9. package/dist/configs/nx.d.ts.map +1 -0
  10. package/{configs → dist/configs}/nx.js +3 -8
  11. package/dist/configs/prettier.d.ts +17 -0
  12. package/dist/configs/prettier.d.ts.map +1 -0
  13. package/{configs → dist/configs}/prettier.js +0 -3
  14. package/dist/configs/promise.d.ts +6 -0
  15. package/dist/configs/promise.d.ts.map +1 -0
  16. package/{configs → dist/configs}/promise.js +0 -3
  17. package/dist/configs/react.d.ts +84 -0
  18. package/dist/configs/react.d.ts.map +1 -0
  19. package/{configs → dist/configs}/react.js +14 -41
  20. package/dist/configs/storybook.d.ts +14 -0
  21. package/dist/configs/storybook.d.ts.map +1 -0
  22. package/{configs → dist/configs}/storybook.js +3 -6
  23. package/dist/configs/tailwind.d.ts +29 -0
  24. package/dist/configs/tailwind.d.ts.map +1 -0
  25. package/{configs → dist/configs}/tailwind.js +9 -24
  26. package/dist/configs/testing.d.ts +22 -0
  27. package/dist/configs/testing.d.ts.map +1 -0
  28. package/{configs → dist/configs}/testing.js +11 -25
  29. package/dist/configs/turbo.d.ts +9 -0
  30. package/dist/configs/turbo.d.ts.map +1 -0
  31. package/{configs → dist/configs}/turbo.js +6 -6
  32. package/dist/configs/typescriptTypeAware.d.ts +20 -0
  33. package/dist/configs/typescriptTypeAware.d.ts.map +1 -0
  34. package/{configs → dist/configs}/typescriptTypeAware.js +10 -23
  35. package/dist/configs/unicorn.d.ts +10 -0
  36. package/dist/configs/unicorn.d.ts.map +1 -0
  37. package/{configs → dist/configs}/unicorn.js +0 -4
  38. package/dist/index.d.ts +80 -0
  39. package/dist/index.d.ts.map +1 -0
  40. package/{index.js → dist/index.js} +5 -54
  41. package/dist/lib.d.ts +116 -0
  42. package/dist/lib.d.ts.map +1 -0
  43. package/{lib.js → dist/lib.js} +69 -145
  44. package/dist/lintPrepare.d.ts +105 -0
  45. package/dist/lintPrepare.d.ts.map +1 -0
  46. package/{lintPrepare.js → dist/lintPrepare.js} +12 -67
  47. package/dist/yarn.cjs +117 -0
  48. package/dist/yarn.d.cts +8 -0
  49. package/dist/yarn.d.cts.map +1 -0
  50. package/package.json +42 -34
  51. package/rules/code-style.md +2 -0
  52. package/rules/github.md +17 -9
  53. package/rules/gitlab.md +68 -17
  54. package/rules/mui.md +1 -1
  55. package/rules/nextjs.md +1 -1
  56. package/rules/npm-yarn.md +51 -6
  57. package/rules/nx.md +6 -6
  58. package/rules/typescript.md +13 -7
  59. package/rules/webstorm.md +20 -0
  60. package/index.d.ts +0 -281
@@ -1,19 +1,16 @@
1
1
  import { existsSync } from 'node:fs';
2
2
  import { dirname, isAbsolute, relative, resolve } from 'node:path';
3
- import { includeIgnoreFile as includeIgnoreFileCompat } from '@eslint/compat';
3
+ import { includeIgnoreFile } from '@eslint/config-helpers';
4
4
  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
8
  export const tsExtsRaw = 'js,jsx,ts,tsx,cjs,cts,mjs,mts'; // TODO mdx, needs loader
10
9
  export const eslintExtsRaw = `${tsExtsRaw},md,mdx,htm,html,vue`;
11
10
  export const prettierExtsRaw = 'css,scss,sass,less,yml,yaml,json,json5,jsonc,graphql,graphqls,xml';
12
-
13
11
  export const tsExts = `{${tsExtsRaw}}`;
14
12
  export const eslintExts = `*.{${eslintExtsRaw}}`;
15
13
  export const prettierExts = `*.{${prettierExtsRaw}}`;
16
-
17
14
  //TODO coverage, dist, out, build?
18
15
  export const GLOBAL_IGNORES = [
19
16
  '**/next-env.d.ts',
@@ -24,45 +21,34 @@ export const GLOBAL_IGNORES = [
24
21
  '**/.turbo',
25
22
  '**/.yarn',
26
23
  ];
27
-
28
24
  const LINT_DEBUG = Boolean(process.env.LINT_DEBUG);
29
-
30
25
  /**
31
26
  * Structured debug logging, gated by the `LINT_DEBUG` env var (any non-empty value). Traces the
32
27
  * detection machinery: capability probes, workspace scans and per-tool gate verdicts.
33
28
  */
34
29
  function debug(message, ...args) {
35
- if (!LINT_DEBUG) return;
30
+ if (!LINT_DEBUG)
31
+ return;
36
32
  console.log(`[@kirill.konshin/lint] ${message}`, ...args);
37
33
  }
38
-
39
34
  /**
40
35
  * Capability gate: is a package resolvable from the workspace root - the scope the ESLint plugins
41
36
  * themselves resolve from at lint time?
42
- *
43
- * @param {string} packageName e.g. `'next'`
44
- * @returns {boolean}
45
37
  */
46
38
  export function isPackageResolvable(packageName) {
47
39
  return isPackageExists(packageName, { paths: [findWorkspaceRoot()] });
48
40
  }
49
-
50
41
  /**
51
42
  * An env-supplied root candidate is only plausible when it is an absolute existing directory that
52
43
  * contains (or is) `cwd` - guards against stale env leaking in from an unrelated checkout.
53
- *
54
- * @param {string | undefined} root
55
- * @param {string} cwd
56
- * @returns {boolean}
57
44
  */
58
45
  function isRootOf(root, cwd) {
59
- if (!root || !isAbsolute(root) || !existsSync(root)) return false;
46
+ if (!root || !isAbsolute(root) || !existsSync(root))
47
+ return false;
60
48
  const rel = relative(root, cwd);
61
49
  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
62
50
  }
63
-
64
51
  const workspaceRoots = new Map();
65
-
66
52
  /**
67
53
  * Workspace root of the consumer project - the anchor for every config-file scan (Tailwind entry,
68
54
  * `next.config.*`) and root-file detection (`nx.json`): `process.cwd()` alone is unreliable
@@ -78,73 +64,65 @@ const workspaceRoots = new Map();
78
64
  *
79
65
  * Cached per `cwd` - the config is rebuilt on every lint run.
80
66
  *
81
- * @param {string} [cwd]
82
- * @returns {string} absolute path; `cwd` itself when there is no package.json anywhere above
67
+ * Returns an absolute path, or `cwd` itself when there is no package.json anywhere above.
83
68
  */
84
69
  export function findWorkspaceRoot(cwd = process.cwd()) {
85
- if (workspaceRoots.has(cwd)) return workspaceRoots.get(cwd);
86
-
70
+ const cached = workspaceRoots.get(cwd);
71
+ if (cached)
72
+ return cached;
87
73
  let root = [process.env.PROJECT_CWD, process.env.npm_config_local_prefix].find((dir) => isRootOf(dir, cwd));
88
74
  if (root) {
89
75
  root = resolve(root);
90
- } else {
76
+ }
77
+ else {
91
78
  try {
92
79
  root = findRootSync(cwd).rootDir;
93
- } catch {
80
+ }
81
+ catch {
94
82
  root = cwd; // no package.json anywhere above - degenerate sandbox, scans just see less
95
83
  }
96
84
  }
97
-
98
85
  workspaceRoots.set(cwd, root);
99
86
  return root;
100
87
  }
101
-
102
88
  const workspacePackageDirs = new Map();
103
-
104
89
  /**
105
90
  * Absolute directories of all workspace packages - the real `workspaces` / `pnpm-workspace.yaml`
106
91
  * globs expanded by `@manypkg/get-packages`, NOT a scan heuristic. Single-package repos yield the
107
92
  * root itself; no package.json at all yields an empty list (degenerate sandboxes, tests).
108
- *
109
- * @returns {string[]}
110
93
  */
111
94
  function findWorkspacePackages() {
112
95
  const root = findWorkspaceRoot();
113
- if (workspacePackageDirs.has(root)) return workspacePackageDirs.get(root);
114
-
96
+ const cached = workspacePackageDirs.get(root);
97
+ if (cached)
98
+ return cached;
115
99
  let dirs = [];
116
100
  try {
117
101
  dirs = getPackagesSync(root).packages.map((pkg) => pkg.dir);
118
- } catch {
102
+ }
103
+ catch {
119
104
  // no package.json at the root - only the root scan applies
120
105
  }
121
-
122
106
  workspacePackageDirs.set(root, dirs);
123
107
  return dirs;
124
108
  }
125
-
126
109
  /**
127
110
  * The workspace package owning `file` (e.g. the Tailwind entry CSS) - matched against the real
128
111
  * workspace package dirs (see {@link findWorkspacePackages}), NOT by walking to the nearest
129
112
  * package.json: a directory that is not a declared workspace member belongs to the root. Returns
130
113
  * the workspace root when no package contains `file`.
131
114
  *
132
- * @param {string} file absolute path
133
- * @returns {string} absolute directory path
134
115
  */
135
116
  export function packageDirOf(file) {
136
117
  const root = findWorkspaceRoot();
137
- return (
138
- findWorkspacePackages()
139
- .filter((dir) => dir !== root)
140
- .sort((a, b) => b.length - a.length) // nested packages: the deepest match wins
141
- .find((dir) => {
142
- const rel = relative(dir, file);
143
- return !rel.startsWith('..') && !isAbsolute(rel);
144
- }) ?? root
145
- );
118
+ return (findWorkspacePackages()
119
+ .filter((dir) => dir !== root)
120
+ .sort((a, b) => b.length - a.length) // nested packages: the deepest match wins
121
+ .find((dir) => {
122
+ const rel = relative(dir, file);
123
+ return !rel.startsWith('..') && !isAbsolute(rel);
124
+ }) ?? root);
146
125
  }
147
-
148
126
  /*
149
127
  * Build outputs regularly contain COPIES of the scanned files (compiled css, a next.config.js in a
150
128
  * published dist) and would poison the scans even in repos that don't gitignore them. Scan-only -
@@ -162,7 +140,6 @@ const SCAN_IGNORES = [
162
140
  '**/storybook-static',
163
141
  '**/.git',
164
142
  ];
165
-
166
143
  /**
167
144
  * Glob for config-file candidates across the workspace: the root directory plus every workspace
168
145
  * package (the real `workspaces` globs via {@link findWorkspacePackages}, not a depth heuristic),
@@ -171,32 +148,25 @@ const SCAN_IGNORES = [
171
148
  *
172
149
  * Public - useful for building consumer file lists (e.g. `typeAware.allowDefaultProject`, see README "Type-aware rules").
173
150
  *
174
- * @param {string} fileGlob e.g. `'*.css'`, `'next.config.*'`
175
- * @param {string[]} [ignores] extra glob patterns to skip
176
- * @param {{ dot?: boolean }} [options] `dot` also scans dot directories (e.g. `.storybook`)
177
- * @returns {string[]} absolute paths
151
+ * `dot` also scans dot directories such as `.storybook`.
178
152
  */
179
153
  export function scanWorkspace(fileGlob, ignores = [], { dot = false } = {}) {
180
154
  const root = findWorkspaceRoot();
181
155
  const packages = findWorkspacePackages().filter((dir) => dir !== root);
182
-
183
156
  let gitignored = [];
184
157
  try {
185
158
  // Reuse ESLint's gitignore->minimatch conversion; glob's `ignore` speaks the same language.
186
159
  // Negations dropped: glob's ignore cannot un-ignore.
187
- gitignored = includeIgnoreFileCompat(resolve(root, '.gitignore')).ignores.filter(
188
- (pattern) => !pattern.startsWith('!'),
189
- );
190
- } catch {
160
+ gitignored = (includeIgnoreFile(resolve(root, '.gitignore')).ignores ?? []).filter((pattern) => !pattern.startsWith('!'));
161
+ }
162
+ catch {
191
163
  // no .gitignore - the scan is just less filtered
192
164
  }
193
-
194
165
  // `<dir-pattern>/**` variants prune the CONTENTS of ignored directories, not just the dir itself
195
166
  const ignore = [...ignores, ...SCAN_IGNORES, ...gitignored].flatMap((pattern) => [
196
167
  pattern,
197
168
  pattern.endsWith('/') ? `${pattern}**` : `${pattern}/**`,
198
169
  ]);
199
-
200
170
  // package dirs are scanned individually - keep the root scan from descending into them twice
201
171
  const rootIgnore = [
202
172
  ...ignore,
@@ -205,17 +175,13 @@ export function scanWorkspace(fileGlob, ignores = [], { dot = false } = {}) {
205
175
  return [rel, `${rel}/**`];
206
176
  }),
207
177
  ];
208
-
209
178
  const files = [
210
179
  ...globSync(`**/${fileGlob}`, { cwd: root, ignore: rootIgnore, absolute: true, dot }),
211
180
  ...packages.flatMap((dir) => globSync(`**/${fileGlob}`, { cwd: dir, ignore, absolute: true, dot })),
212
181
  ];
213
-
214
182
  // debug('scanWorkspace', { fileGlob, root, packages, dot, ignores, files });
215
-
216
183
  return files;
217
184
  }
218
-
219
185
  /*
220
186
  * Capability detection, exported for debugging. Package probes resolve from the WORKSPACE ROOT -
221
187
  * the same scope the plugins' own resolution sees at lint time (eslint-plugin-tailwindcss's
@@ -232,9 +198,7 @@ export const hasVitest = isPackageResolvable('vitest');
232
198
  export const hasTurbo = isPackageResolvable('turbo');
233
199
  export const hasNx = existsSync(resolve(findWorkspaceRoot(), 'nx.json'));
234
200
  export const hasTailwind = isPackageResolvable('tailwindcss');
235
-
236
201
  debug('capability probes', { hasNext, hasStorybook, hasVite, hasJest, hasVitest, hasTurbo, hasNx, hasTailwind });
237
-
238
202
  /**
239
203
  * Normalize a defineLintConfig flag into its options object with a canonical `enabled`:
240
204
  * - `true` / `false` → `{ enabled: true | false }`
@@ -243,19 +207,19 @@ debug('capability probes', { hasNext, hasStorybook, hasVite, hasJest, hasVitest,
243
207
  * - `undefined` (flag not passed) → `{}` - `enabled` stays undefined and the caller falls back to
244
208
  * detection: `const { enabled = hasX, ...options } = asOptions(option)`
245
209
  *
246
- * @param {boolean | { enabled?: boolean } | undefined} option user-supplied flag from `LintOptions`
247
- * @returns {{ enabled?: boolean } & object}
248
210
  */
249
211
  export function asOptions(option) {
250
- if (typeof option === 'boolean') return { enabled: option };
251
- if (typeof option === 'object' && option !== null) return { enabled: true, ...option };
212
+ if (typeof option === 'boolean')
213
+ return { enabled: option };
214
+ if (typeof option === 'object' && option !== null) {
215
+ return { enabled: true, ...option };
216
+ }
252
217
  return {};
253
218
  }
254
-
255
219
  /**
256
220
  * Shared activation gate of the tool-scoped config blocks (next, storybook, turbo, nx, jest,
257
221
  * vitest, tailwind) - the one decision every block repeats: is the tool ON, and can its plugin
258
- * actually run. The `configs/*.js` functions keep only their tool-specific parts (which blocks to
222
+ * actually run. The `configs/*.ts` functions keep only their tool-specific parts (which blocks to
259
223
  * emit, how the evidence feeds settings) and differ solely in the spec they pass here.
260
224
  *
261
225
  * Decision flow:
@@ -271,56 +235,30 @@ export function asOptions(option) {
271
235
  * symlink bridging - the plugins resolve from the root scope, so only hoisting actually fixes
272
236
  * them; the user or their AI agent picks it up from the error).
273
237
  *
274
- * @param {boolean | { enabled?: boolean } | undefined} option the tool's defineLintConfig flag
275
- * @param {boolean} strict same-scope detection only (defineLintConfig `detection.strict`)
276
- * @param {object} spec
277
- * @param {string} spec.tool flag name, used in error messages
278
- * @param {boolean} spec.has module-load package probe (chain resolvability, see the `has*` exports)
279
- * @param {boolean} [spec.strictHas] strict-mode detection gate when it differs from `has` (nx: `nx.json` at cwd)
280
- * @param {string} [spec.packageName] package the tool's plugin needs resolvable at lint time - ON + unresolvable from the workspace root is a hard error with hoisting guidance
281
- * @param {boolean} [spec.requirePackage] fail loudly when the tool is ON but `packageName` is unresolvable; defaults to `packageName` being set - pass `false` when the plugin works without the tool installed (jest/vitest)
282
- * @param {(options: object) => string[]} [spec.absolutizeOptions] evidence files derived from the options (absolute anchor paths for the package probes - the anchor itself need not exist, resolution walks up from its directory; allowed under strict)
283
- * @param {() => string[]} [spec.scan] evidence auto-discovery below the workspace root (absolute paths; never runs under strict or when `absolutizeOptions` produced files)
284
- * @param {boolean} [spec.allowMultiple] whether several evidence files are usable (default true - next supports several apps); when `false` several candidates are ALWAYS a hard error, even in auto mode - the right one cannot be guessed (tailwind's single entry CSS) and a silent skip of a tool that is evidently present would be hard to detect; zero candidates keeps the usual `needs` behavior
285
- * @param {{ what: string, detail: string, hint: string }} [spec.needs] makes evidence MANDATORY (the plugin crashes without it - tailwind's entry CSS): detection without evidence stays inert even when `has` hits, forcing the tool on without it throws
286
- * @returns {{ enabled: boolean, options: object, files: string[] }} the verdict, the normalized options (without `enabled`) and the evidence files
287
238
  */
288
239
  export function toolGate(option, strict, spec) {
289
- const { enabled, ...options } = asOptions(option);
240
+ const { enabled, ...rawOptions } = asOptions(option);
241
+ const options = rawOptions;
290
242
  let absolutized = [];
291
243
  let scanned = [];
292
244
  // every return path funnels through here so the effective verdict is always traceable
293
245
  const trace = (result, reason) => {
294
- debug(
295
- `toolGate \`${spec.tool}\` %o`,
296
- {
297
- strict,
298
- has: spec.has,
299
- enabled: result.enabled,
300
- reason,
301
- },
302
- {
303
- supplied: option,
304
- absolutized,
305
- scanned,
306
- },
307
- );
246
+ debug(`toolGate \`${spec.tool}\` %o`, {
247
+ strict,
248
+ has: spec.has,
249
+ enabled: result.enabled,
250
+ reason,
251
+ }, {
252
+ supplied: option,
253
+ absolutized,
254
+ scanned,
255
+ });
308
256
  return result;
309
257
  };
310
258
  const off = { enabled: false, options, files: [] };
311
- if (enabled === false) return trace(off, 'disabled explicitly');
312
-
313
- const {
314
- tool,
315
- has,
316
- strictHas = has,
317
- packageName,
318
- requirePackage = Boolean(packageName),
319
- absolutizeOptions,
320
- scan,
321
- allowMultiple = true,
322
- needs,
323
- } = spec;
259
+ if (enabled === false)
260
+ return trace(off, 'disabled explicitly');
261
+ const { tool, has, strictHas = has, packageName, requirePackage = Boolean(packageName), absolutizeOptions, scan, allowMultiple = true, needs, } = spec;
324
262
  const prefix = `[@kirill.konshin/lint] \`${tool}\``;
325
263
  /*
326
264
  * Several candidates with allowMultiple off are a hard error even in auto mode: the evidence
@@ -330,67 +268,53 @@ export function toolGate(option, strict, spec) {
330
268
  const usable = (candidates) => {
331
269
  if (!allowMultiple && candidates.length > 1) {
332
270
  const fix = needs ? `pass ${needs.hint} to pick one, or set` : `set`;
333
- throw new Error(
334
- `${prefix} found several ${needs?.what ?? 'evidence'} candidates and cannot pick one - ` +
335
- `${fix} \`${tool}: false\`:\n${candidates.map((file) => ` - ${file}`).join('\n')}`,
336
- );
271
+ throw new Error(`${prefix} found several ${needs?.what ?? 'evidence'} candidates and cannot pick one - ` +
272
+ `${fix} \`${tool}: false\`:\n${candidates.map((file) => ` - ${file}`).join('\n')}`);
337
273
  }
338
274
  return candidates;
339
275
  };
340
-
341
276
  if (strict) {
342
- if (!(enabled ?? strictHas)) return trace(off, 'strict probe negative');
277
+ if (!(enabled ?? strictHas))
278
+ return trace(off, 'strict probe negative');
343
279
  if (requirePackage && !has) {
344
- throw new Error(
345
- `${prefix} is on under strict detection, but the \`${packageName}\` package is not ` +
346
- `resolvable at this scope - install it here or set \`${tool}: false\`.`,
347
- );
280
+ throw new Error(`${prefix} is on under strict detection, but the \`${packageName}\` package is not ` +
281
+ `resolvable at this scope - install it here or set \`${tool}: false\`.`);
348
282
  }
349
283
  absolutized = absolutizeOptions?.(options) ?? [];
350
284
  const files = usable(absolutized);
351
285
  if (needs && files.length === 0) {
352
- throw new Error(
353
- `${prefix} is on under strict detection, which cannot scan for the ${needs.what} - ` +
354
- `pass ${needs.hint} or set \`${tool}: false\`.`,
355
- );
286
+ throw new Error(`${prefix} is on under strict detection, which cannot scan for the ${needs.what} - ` +
287
+ `pass ${needs.hint} or set \`${tool}: false\`.`);
356
288
  }
357
289
  return trace({ enabled: true, options, files }, enabled ? 'strict, forced on' : 'strict probe positive');
358
290
  }
359
-
360
291
  absolutized = absolutizeOptions?.(options) ?? [];
361
292
  scanned = absolutized.length > 0 ? [] : (scan?.() ?? []);
362
293
  const files = usable(absolutized.length > 0 ? absolutized : scanned);
363
-
364
294
  if (needs && files.length === 0) {
365
295
  // `enabled` is only defined when the consumer explicitly turned the tool on - fail loudly
366
296
  // then; detection-driven activation (enabled === undefined) stays inert instead.
367
297
  if (enabled) {
368
- throw new Error(
369
- `${prefix} was enabled explicitly, but no ${needs.detail} was found - zero or several ` +
370
- `candidates. Pass ${needs.hint} explicitly.`,
371
- );
298
+ throw new Error(`${prefix} was enabled explicitly, but no ${needs.detail} was found - zero or several ` +
299
+ `candidates. Pass ${needs.hint} explicitly.`);
372
300
  }
373
301
  return trace(off, `no ${needs.what} found`);
374
302
  }
375
-
376
- if (!(enabled ?? (has || files.length > 0))) return trace(off, 'not detected');
377
-
303
+ if (!(enabled ?? (has || files.length > 0)))
304
+ return trace(off, 'not detected');
378
305
  /*
379
306
  * The tool is ON but its package is invisible at the workspace root - the scope the plugins
380
307
  * resolve from at lint time. No silent skip and no symlink bridging: fail with the fix
381
308
  * (hoisting) and let the user or their AI agent pick it up from here.
382
309
  */
383
- if (requirePackage && !has) {
310
+ if (requirePackage && packageName && !has) {
384
311
  const leaf = files.map((file) => dirname(file)).find((dir) => isPackageExists(packageName, { paths: [dir] }));
385
- throw new Error(
386
- `${prefix} is in use, but the \`${packageName}\` package is not resolvable from the workspace root` +
387
- (leaf ? ` (it is installed near \`${leaf}\`)` : '') +
388
- ` - hoist it: keep the package manager's default hoisting (no \`installConfig.hoistingLimits\` / ` +
389
- `\`nohoist\`), on pnpm add \`public-hoist-pattern[]=${packageName}\` to .npmrc, or add ` +
390
- `\`${packageName}\` to the root devDependencies. Set \`${tool}: false\` to turn the tool off. ` +
391
- `Run eslint with LINT_DEBUG=1 to trace detection.`,
392
- );
312
+ throw new Error(`${prefix} is in use, but the \`${packageName}\` package is not resolvable from the workspace root` +
313
+ (leaf ? ` (it is installed near \`${leaf}\`)` : '') +
314
+ ` - hoist it: keep the package manager's default hoisting (no \`installConfig.hoistingLimits\` / ` +
315
+ `\`nohoist\`), on pnpm add \`public-hoist-pattern[]=${packageName}\` to .npmrc, or add ` +
316
+ `\`${packageName}\` to the root devDependencies. Set \`${tool}: false\` to turn the tool off. ` +
317
+ `Run eslint with LINT_DEBUG=1 to trace detection.`);
393
318
  }
394
-
395
319
  return trace({ enabled: true, options, files }, enabled ? 'forced on' : 'detected');
396
320
  }
@@ -0,0 +1,105 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * @kirill.konshin/lint
4
+ *
5
+ * This script symlinks all markdown rule files from the package into the consuming
6
+ * project's `.claude/rules` directory (auto-discovered by Claude Code), symlinks every
7
+ * package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/` (SKILL.md plus
8
+ * the package README.md alongside it, so a skill can reference `@README.md`), and generates
9
+ * an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
10
+ *
11
+ * Usage:
12
+ * lint-prepare init - Initialize AGENTS.md in the current directory (default)
13
+ * lint-prepare update - Force update AGENTS.md even if it exists
14
+ * lint-prepare - Same as init
15
+ *
16
+ * The module also exports its functions and only runs `main()` when executed directly,
17
+ * so it can be imported (for testing/reuse) without side effects.
18
+ */
19
+ type Rule = {
20
+ file: string;
21
+ name: string;
22
+ content: string;
23
+ };
24
+ type Skill = {
25
+ file: string;
26
+ name: string;
27
+ };
28
+ type ExistingFile = {
29
+ exists: boolean;
30
+ generated: boolean;
31
+ customSection: string | null;
32
+ };
33
+ /**
34
+ * Read all markdown files from the package rules directory.
35
+ */
36
+ export declare function readRules(): Rule[];
37
+ /**
38
+ * Read all markdown files from the package skills directory. Each file becomes its own skill, named after the file
39
+ * (without extension) - e.g. `lint-repo.md` becomes the `lint-repo` skill.
40
+ */
41
+ export declare function readSkills(): Skill[];
42
+ /**
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.
45
+ */
46
+ export declare function checkRulesDirSafety(rulesTargetDir: string): void;
47
+ /**
48
+ * Fail if `CLAUDE.md` exists and isn't a symlink - same reasoning as checkRulesDirSafety.
49
+ */
50
+ export declare function checkClaudeMdSafety(claudeMdPath: string): void;
51
+ /**
52
+ * Symlink rules into the consuming project's `.claude/rules` directory.
53
+ * Safe to wipe and recreate: checkRulesDirSafety already guaranteed every existing
54
+ * entry is a symlink.
55
+ *
56
+ * FIXME Codex Includes
57
+ * https://github.com/openai/codex/issues/17401
58
+ * https://github.com/openai/codex/issues/6038
59
+ * 32kb limit https://github.com/openai/codex/issues/13386
60
+ *
61
+ * TODO: generate `.claude/CLAUDE.md` with an index of the symlinked rules, for humans browsing `.claude/rules` manually
62
+ * (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
63
+ * indexed anywhere).
64
+ */
65
+ export declare function symlinkRules(cwd: string, rules: Rule[]): string;
66
+ /**
67
+ * Fail if a skill's target directory (e.g. `.claude/skills/lint-repo`) contains anything
68
+ * that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
69
+ * own subdirectory is checked/wiped, not the whole `.claude/skills` or `.codex/skills`
70
+ * parent, since other packages (or the user) may keep unrelated skills there.
71
+ */
72
+ export declare function checkSkillDirSafety(skillDir: string): void;
73
+ /**
74
+ * Symlink each package skill into `<cwd>/.claude/skills/<name>/` and
75
+ * `<cwd>/.codex/skills/<name>/`, so both Claude Code and Codex CLI can discover and run
76
+ * them. The package README.md is symlinked alongside SKILL.md so a skill can reference it
77
+ * via `@README.md` regardless of how the tool resolves relative mentions.
78
+ */
79
+ export declare function symlinkSkills(cwd: string, skills: Skill[]): string[];
80
+ /**
81
+ * Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
82
+ */
83
+ export declare function symlinkClaudeMd(cwd: string): void;
84
+ /**
85
+ * Generate AGENTS.md with references to the rule files.
86
+ *
87
+ * `.claude/rules/*.md` are symlinked by symlinkRules() above and auto-discovered by
88
+ * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
89
+ * under `.claude/rules`, symlinks included) - no reference to them is needed here.
90
+ * The sections below are for other tools that only read AGENTS.md.
91
+ */
92
+ export declare function generateAgentsFile(rules: Rule[], cwd: string, customSection: string | null): string;
93
+ /**
94
+ * Check if AGENTS.md exists and was generated by this tool. When it was, also return
95
+ * whatever follows the marker (the user's custom section) so it can be carried forward -
96
+ * generateAgentsFile() always rebuilds the part above the marker from scratch, but must
97
+ * never touch what a user wrote below it.
98
+ */
99
+ export declare function checkExisting(targetPath: string): ExistingFile;
100
+ /**
101
+ * Main function
102
+ */
103
+ export declare function main(): void;
104
+ export {};
105
+ //# sourceMappingURL=lintPrepare.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG;AASH,KAAK,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAC5D,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;AAuB1F;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAwBlC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAQpC;AAED;;;GAGG;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,CAa/D;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;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAUnG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAW9D;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAuD3B"}