peaks-loop 4.1.12 → 4.1.14

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 (76) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +118 -0
  3. package/dist/cli/commands/_register.js +2 -0
  4. package/dist/cli/commands/batch-commands.d.ts +6 -0
  5. package/dist/cli/commands/batch-commands.js +70 -0
  6. package/dist/cli/commands/batch-diagnose-command.d.ts +10 -0
  7. package/dist/cli/commands/batch-diagnose-command.js +196 -0
  8. package/dist/cli/commands/batch-diagnose-envelope.d.ts +25 -0
  9. package/dist/cli/commands/batch-diagnose-envelope.js +60 -0
  10. package/dist/cli/commands/batch-diagnose-record.d.ts +21 -0
  11. package/dist/cli/commands/batch-diagnose-record.js +51 -0
  12. package/dist/cli/commands/batch-item-input.d.ts +59 -0
  13. package/dist/cli/commands/batch-item-input.js +113 -0
  14. package/dist/cli/commands/batch-report-command.d.ts +22 -0
  15. package/dist/cli/commands/batch-report-command.js +199 -0
  16. package/dist/cli/commands/code-gate-command.d.ts +18 -0
  17. package/dist/cli/commands/code-gate-command.js +95 -32
  18. package/dist/cli/commands/core/skill-context-verdict.d.ts +16 -1
  19. package/dist/cli/commands/core/skill-context-verdict.js +38 -8
  20. package/dist/cli/commands/lint-commands.js +8 -0
  21. package/dist/cli/commands/lint-rules-command.d.ts +14 -0
  22. package/dist/cli/commands/lint-rules-command.js +44 -0
  23. package/dist/services/batch/batch-active-batch.d.ts +55 -0
  24. package/dist/services/batch/batch-active-batch.js +127 -0
  25. package/dist/services/batch/batch-context-reminder.d.ts +85 -0
  26. package/dist/services/batch/batch-context-reminder.js +201 -0
  27. package/dist/services/batch/batch-diagnosis-finding.d.ts +25 -0
  28. package/dist/services/batch/batch-diagnosis-finding.js +227 -0
  29. package/dist/services/batch/batch-diagnosis-report-store.d.ts +49 -0
  30. package/dist/services/batch/batch-diagnosis-report-store.js +133 -0
  31. package/dist/services/batch/batch-diagnosis-summary.d.ts +31 -0
  32. package/dist/services/batch/batch-diagnosis-summary.js +129 -0
  33. package/dist/services/batch/batch-diagnosis.d.ts +36 -0
  34. package/dist/services/batch/batch-diagnosis.js +107 -0
  35. package/dist/services/batch/batch-entry.d.ts +22 -0
  36. package/dist/services/batch/batch-entry.js +42 -0
  37. package/dist/services/batch/batch-fix-agent.d.ts +39 -0
  38. package/dist/services/batch/batch-fix-agent.js +126 -0
  39. package/dist/services/batch/batch-fix-types.d.ts +85 -0
  40. package/dist/services/batch/batch-fix-types.js +11 -0
  41. package/dist/services/batch/batch-fix.d.ts +15 -0
  42. package/dist/services/batch/batch-fix.js +229 -0
  43. package/dist/services/batch/batch-phase-advance.d.ts +45 -0
  44. package/dist/services/batch/batch-phase-advance.js +105 -0
  45. package/dist/services/batch/batch-progress-store.d.ts +52 -0
  46. package/dist/services/batch/batch-progress-store.js +219 -0
  47. package/dist/services/batch/batch-progress-types.d.ts +79 -0
  48. package/dist/services/batch/batch-progress-types.js +10 -0
  49. package/dist/services/batch/batch-recovery.d.ts +5 -0
  50. package/dist/services/batch/batch-recovery.js +24 -0
  51. package/dist/services/batch/batch-verify.d.ts +93 -0
  52. package/dist/services/batch/batch-verify.js +216 -0
  53. package/dist/services/code/auto-compact-decision.d.ts +17 -0
  54. package/dist/services/code/auto-compact-decision.js +6 -0
  55. package/dist/services/code/auto-compact-orchestrator.js +6 -0
  56. package/dist/services/code/batch-compaction-point.d.ts +45 -0
  57. package/dist/services/code/batch-compaction-point.js +99 -0
  58. package/dist/services/context/context-schema.d.ts +1 -1
  59. package/dist/services/hooks/pre-tool-code-gate.d.ts +33 -1
  60. package/dist/services/hooks/pre-tool-code-gate.js +67 -6
  61. package/dist/services/lint/curated-rule-reader.d.ts +37 -0
  62. package/dist/services/lint/curated-rule-reader.js +179 -0
  63. package/dist/services/lint/project-lint-declarations.d.ts +27 -0
  64. package/dist/services/lint/project-lint-declarations.js +217 -0
  65. package/dist/services/lint/project-lint-tool-detection.d.ts +14 -0
  66. package/dist/services/lint/project-lint-tool-detection.js +208 -0
  67. package/dist/services/lint/project-lint-tool-rules.d.ts +19 -0
  68. package/dist/services/lint/project-lint-tool-rules.js +199 -0
  69. package/dist/services/lint/rule-pre-read-types.d.ts +66 -0
  70. package/dist/services/lint/rule-pre-read-types.js +22 -0
  71. package/dist/services/lint/rule-pre-read.d.ts +20 -0
  72. package/dist/services/lint/rule-pre-read.js +145 -0
  73. package/dist/services/skill/skill-search-service.d.ts +3 -3
  74. package/package.json +5 -5
  75. package/skills/peaks-code/references/micro-cycle.md +13 -1
  76. package/skills/peaks-race-code/SKILL.md +40 -1
@@ -0,0 +1,208 @@
1
+ // src/services/lint/project-lint-tool-detection.ts
2
+ //
3
+ // L1, step one — DISCOVER the lint tooling a project declared for itself.
4
+ //
5
+ // THE QUESTION THIS ANSWERS: "what will THIS project's gate reject?" The
6
+ // answer is not ours to guess: the project already says, in the declaration
7
+ // sites it ships. This module reads those declarations (see
8
+ // `project-lint-declarations.ts`) and reports which of them name a lint tool.
9
+ //
10
+ // WHY THERE IS NO LANGUAGE SWITCH HERE. A Go project with golangci-lint, a
11
+ // Python project with ruff and a TypeScript project with eslint all travel the
12
+ // SAME code path: the file set is never inspected to decide which tool to ask.
13
+ // The only vocabulary in this file is a set of lint TOOL names — the DETECTORS,
14
+ // not a list of supported languages. Adding a tool to that set is a one-line
15
+ // data change; no branch anywhere keys on the language of a file.
16
+ //
17
+ // WHY "NOTHING FOUND" IS AN EXPLICIT ANSWER. A project that declares no lint
18
+ // tool is a real, common state, and reporting it as an empty list would be
19
+ // indistinguishable from "we looked and the tool said there is nothing wrong".
20
+ // The two are different answers, so the empty case carries a reason.
21
+ import { readProjectDeclarations } from './project-lint-declarations.js';
22
+ /** The reason a project with no lint tooling gets. Exact, and never empty. */
23
+ export const NO_LINT_TOOL_REASON = 'no lint tool declared by this project';
24
+ /**
25
+ * The lint vocabulary — tool names that report style or correctness findings.
26
+ *
27
+ * A tool whose NAME carries one of these markers is recognized without being
28
+ * listed here (`eslint`, `golangci-lint`, `gofmt`, `swiftlint`, …); the set
29
+ * below covers the tools whose name carries no marker. This is a list of
30
+ * DETECTORS, never a list of languages: nothing in this file branches on the
31
+ * language of a file.
32
+ */
33
+ const LINT_TOOL_NAMES = new Set([
34
+ 'bandit',
35
+ 'biome',
36
+ 'black',
37
+ 'clippy',
38
+ 'codespell',
39
+ 'credo',
40
+ 'flake8',
41
+ 'gosec',
42
+ 'govet',
43
+ 'isort',
44
+ 'misspell',
45
+ 'mypy',
46
+ 'perlcritic',
47
+ 'phpcs',
48
+ 'phpstan',
49
+ 'prettier',
50
+ 'pylint',
51
+ 'pyright',
52
+ 'radon',
53
+ 'revive',
54
+ 'rubocop',
55
+ 'ruff',
56
+ 'safety',
57
+ 'scalafix',
58
+ 'selene',
59
+ 'shellcheck',
60
+ 'shfmt',
61
+ 'spotbugs',
62
+ 'standardrb',
63
+ 'stylua',
64
+ 'tsc',
65
+ 'typos',
66
+ 'vulture'
67
+ ]);
68
+ /**
69
+ * A name that CARRIES a lint marker is a lint tool without being listed:
70
+ * `eslint`, `stylelint`, `golangci-lint`, `gofmt`, `rustfmt`, `ktlint`,
71
+ * `swiftlint`, `markdownlint`, `hadolint`, `clang-format`, `go vet`, …
72
+ */
73
+ const LINT_NAME_MARKER = /lint|fmt|format|style|vet/;
74
+ /** Package managers whose next argument is a SCRIPT the project declares. */
75
+ const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
76
+ /** Runners whose next argument is the tool itself. */
77
+ const DIRECT_RUNNERS = new Set(['npx', 'bunx', 'uvx', 'pipx', 'dlx']);
78
+ /** The tool a command line invokes, or `null` when it invokes no known tool. */
79
+ export function toolNameFromCommand(command, scripts, depth = 0) {
80
+ const tokens = tokenize(command);
81
+ const head = tokens[0];
82
+ if (head === undefined)
83
+ return null;
84
+ if (PACKAGE_MANAGERS.has(head))
85
+ return packageManagerTool(tokens, scripts, depth);
86
+ if (DIRECT_RUNNERS.has(head))
87
+ return baseName(tokens[1]);
88
+ const special = specialTool(head, tokens);
89
+ if (special !== null)
90
+ return special;
91
+ return baseName(head);
92
+ }
93
+ /** The command's words, without the environment assignments in front of it. */
94
+ function tokenize(command) {
95
+ return command
96
+ .trim()
97
+ .split(/\s+/)
98
+ .filter((token) => token.length > 0 && !/^[\w.-]+=/.test(token));
99
+ }
100
+ /**
101
+ * The tool a command reaches THROUGH another program: `poetry run ruff`,
102
+ * `go vet`, `cargo clippy`, `dotnet format`, `python -m flake8`.
103
+ */
104
+ function specialTool(head, tokens) {
105
+ if (head === 'poetry')
106
+ return tokens[1] === 'run' ? baseName(tokens[2]) : null;
107
+ if (head === 'go')
108
+ return goTool(tokens);
109
+ if (head === 'cargo')
110
+ return cargoTool(tokens);
111
+ if (head === 'dotnet')
112
+ return tokens[1] === 'format' ? 'dotnet format' : null;
113
+ if (head === 'python' || head === 'python3') {
114
+ return tokens[1] === '-m' ? baseName(tokens[2]) : null;
115
+ }
116
+ return null;
117
+ }
118
+ function packageManagerTool(tokens, scripts, depth) {
119
+ const next = tokens[1];
120
+ if (next === undefined)
121
+ return null;
122
+ if (next === 'run' || next === 'exec' || next === 'dlx')
123
+ return baseName(tokens[2]);
124
+ if (depth > 0)
125
+ return null;
126
+ const script = scripts.get(next);
127
+ return script === undefined ? null : toolNameFromCommand(script, scripts, depth + 1);
128
+ }
129
+ function goTool(tokens) {
130
+ if (tokens[1] === 'tool')
131
+ return baseName(tokens[2]);
132
+ if (tokens[1] === 'vet')
133
+ return 'go vet';
134
+ if (tokens[1] === 'fmt')
135
+ return 'gofmt';
136
+ return null;
137
+ }
138
+ function cargoTool(tokens) {
139
+ if (tokens[1] === 'clippy')
140
+ return 'clippy';
141
+ if (tokens[1] === 'fmt')
142
+ return 'rustfmt';
143
+ return null;
144
+ }
145
+ /** A command's executable, reduced to a comparable name. */
146
+ function baseName(token) {
147
+ if (token === undefined)
148
+ return null;
149
+ const name = token.split(/[\\/]/).pop() ?? token;
150
+ const stripped = name.replace(/\.(exe|cmd|bat|ps1|sh|py|js|mjs|cjs)$/i, '');
151
+ return stripped.toLowerCase();
152
+ }
153
+ /** Whether a name is a lint tool's name. */
154
+ export function isLintToolName(name) {
155
+ return LINT_TOOL_NAMES.has(name) || LINT_NAME_MARKER.test(name);
156
+ }
157
+ /**
158
+ * The project's own lint tooling, discovered from its declaration sites.
159
+ *
160
+ * A project that declares no lint tool gets an EXPLICIT reason, never a
161
+ * silent empty list.
162
+ */
163
+ export function detectProjectLintTools(projectRoot) {
164
+ const declarations = readProjectDeclarations(projectRoot);
165
+ const tools = [];
166
+ const seen = new Set();
167
+ for (const declared of declarations.commands) {
168
+ const name = declaredToolName(declared, declarations.scripts);
169
+ if (name === '')
170
+ continue;
171
+ const key = `${name}|${declared.command}`;
172
+ if (seen.has(key))
173
+ continue;
174
+ seen.add(key);
175
+ tools.push({ name, declaredBy: declared.declaredBy, command: declared.command });
176
+ }
177
+ if (tools.length === 0) {
178
+ const suffix = declarations.problems.length === 0 ? '' : ` (${declarations.problems.join('; ')})`;
179
+ return { tools, reason: `${NO_LINT_TOOL_REASON}${suffix}`, problems: declarations.problems };
180
+ }
181
+ return {
182
+ tools,
183
+ reason: `${String(tools.length)} lint tool(s) declared by this project`,
184
+ problems: declarations.problems
185
+ };
186
+ }
187
+ /**
188
+ * The name a declaration is reported under.
189
+ *
190
+ * The tool the command RUNS wins when that tool is a lint tool. Otherwise the
191
+ * declaration's own name is used — a script called `lint` that wraps a
192
+ * wrapper is still a lint step, and the reader deserves to see it.
193
+ *
194
+ * The NAME's own namespace decides, not the whole name: `lint:silent-warning`
195
+ * is a lint step, `test:lint` is a test that happens to run a lint config.
196
+ * A namespace's first segment says what the step IS; a later segment only
197
+ * says which variant it is.
198
+ */
199
+ function declaredToolName(declared, scripts) {
200
+ const resolved = toolNameFromCommand(declared.command, scripts);
201
+ if (resolved !== null && isLintToolName(resolved))
202
+ return resolved;
203
+ return isLintToolName(labelRoot(declared.label)) ? declared.label : '';
204
+ }
205
+ /** A declaration name's own namespace: `lint:silent-warning` → `lint`. */
206
+ function labelRoot(label) {
207
+ return label.split(/[:/]/)[0] ?? label;
208
+ }
@@ -0,0 +1,19 @@
1
+ import type { EffectiveRule, ProjectLintTool, RulePreReadDeps } from './rule-pre-read-types.js';
2
+ /**
3
+ * The rules inside a printed configuration, one per line, sorted by rule id.
4
+ *
5
+ * `null` means "this is not a configuration I can read" — a different answer
6
+ * from "the configuration enables no rules", which is an empty string.
7
+ */
8
+ export declare function renderRuleMap(config: unknown): string | null;
9
+ /**
10
+ * The project's own effective rules for a file set.
11
+ *
12
+ * Returns the rules AND the reasons the read could not produce them: a tool
13
+ * that is declared but not installed, or a file the tool could not resolve, is
14
+ * reported rather than dropped.
15
+ */
16
+ export declare function readProjectLintRules(projectRoot: string, tools: readonly ProjectLintTool[], files: readonly string[], deps: RulePreReadDeps): {
17
+ rules: readonly EffectiveRule[];
18
+ reasons: readonly string[];
19
+ };
@@ -0,0 +1,199 @@
1
+ // src/services/lint/project-lint-tool-rules.ts
2
+ //
3
+ // L1, step two — ask the PROJECT'S OWN tooling for its effective rules.
4
+ //
5
+ // The project already owns the answer to "what will your gate reject?"; this
6
+ // module asks that tool directly instead of re-implementing a lint engine or
7
+ // parsing a configuration format. ESLint answers with `eslint --print-config
8
+ // <file>`; stylelint has the equivalent. A tool that cannot answer is still
9
+ // reported — the reader learns what the project DECLARES it runs, which is the
10
+ // part of the answer that does not need a tool to be installed.
11
+ //
12
+ // GROUPING IS THE POINT. A project's configuration is resolved per file, so
13
+ // ten files of the same kind resolve to the SAME configuration. The resolved
14
+ // text is therefore keyed by content: one entry covers every file that shares
15
+ // it, and the entry names those files. Without that, N files would carry N
16
+ // copies of the same rule text into a fix prompt.
17
+ import { spawnSync } from 'node:child_process';
18
+ import { existsSync } from 'node:fs';
19
+ import { join } from 'node:path';
20
+ import { ESLINT_PACKAGE_PINS } from './eslint-runner-types.js';
21
+ import { resolveNpxInvocation } from './npx-resolver.js';
22
+ /** How long a project's own tool may take to print its configuration. */
23
+ const TOOL_TIMEOUT_MS = 60_000;
24
+ /** The buffer a tool's configuration may fill — 32 MiB. */
25
+ const TOOL_MAX_BUFFER_BYTES = 33_554_432;
26
+ /** How much of a failed tool's output is quoted back as the reason. */
27
+ const REASON_EXCERPT_CHARS = 400;
28
+ /**
29
+ * The tools that can be asked for their effective configuration. A tool that
30
+ * is not here is still detected and still reported — as a declaration.
31
+ */
32
+ const CONFIG_PRINTERS = [
33
+ {
34
+ tool: 'eslint',
35
+ commandFor: eslintCommand,
36
+ render: renderRuleMap
37
+ },
38
+ {
39
+ tool: 'stylelint',
40
+ commandFor: stylelintCommand,
41
+ render: renderRuleMap
42
+ }
43
+ ];
44
+ /** ESLint: the project's own copy when it has one, the pinned release otherwise. */
45
+ function eslintCommand(file, root) {
46
+ const local = join(root, 'node_modules', 'eslint', 'bin', 'eslint.js');
47
+ if (existsSync(local)) {
48
+ return { command: process.execPath, args: [local, '--print-config', file] };
49
+ }
50
+ const resolved = resolveNpxInvocation([
51
+ '--package',
52
+ `eslint@${ESLINT_PACKAGE_PINS.eslint}`,
53
+ '--',
54
+ 'eslint',
55
+ '--print-config',
56
+ file
57
+ ]);
58
+ return { command: resolved.command, args: resolved.args };
59
+ }
60
+ /** stylelint: the project's own copy when it has one, the registry release otherwise. */
61
+ function stylelintCommand(file, root) {
62
+ for (const relative of ['stylelint/bin/stylelint.mjs', 'stylelint/bin/stylelint.js']) {
63
+ const local = join(root, 'node_modules', relative);
64
+ if (existsSync(local)) {
65
+ return { command: process.execPath, args: [local, '--print-config', file] };
66
+ }
67
+ }
68
+ const resolved = resolveNpxInvocation([
69
+ '--package',
70
+ 'stylelint',
71
+ '--',
72
+ 'stylelint',
73
+ '--print-config',
74
+ file
75
+ ]);
76
+ return { command: resolved.command, args: resolved.args };
77
+ }
78
+ /**
79
+ * The rules inside a printed configuration, one per line, sorted by rule id.
80
+ *
81
+ * `null` means "this is not a configuration I can read" — a different answer
82
+ * from "the configuration enables no rules", which is an empty string.
83
+ */
84
+ export function renderRuleMap(config) {
85
+ if (config === null || typeof config !== 'object')
86
+ return null;
87
+ const rules = config['rules'];
88
+ if (rules === null || typeof rules !== 'object' || Array.isArray(rules))
89
+ return null;
90
+ const entries = Object.entries(rules).sort(([left], [right]) => left.localeCompare(right));
91
+ return entries.map(([id, value]) => `${id}: ${JSON.stringify(value)}`).join('\n');
92
+ }
93
+ /** The JSON object a tool printed, or the reason it printed none. */
94
+ function parsePrintedConfig(stdout) {
95
+ const start = stdout.indexOf('{');
96
+ const end = stdout.lastIndexOf('}');
97
+ if (start === -1 || end <= start) {
98
+ return { ok: false, reason: 'the tool printed no JSON object' };
99
+ }
100
+ try {
101
+ return { ok: true, config: JSON.parse(stdout.slice(start, end + 1)) };
102
+ }
103
+ catch (error) {
104
+ return { ok: false, reason: error instanceof Error ? error.message : String(error) };
105
+ }
106
+ }
107
+ /** Run one tool and hand back what it printed. */
108
+ function runTool(tool, cwd, deps) {
109
+ if (deps.invokeProjectTool !== undefined)
110
+ return deps.invokeProjectTool(tool.args, cwd);
111
+ const result = spawnSync(tool.command, [...tool.args], {
112
+ cwd,
113
+ encoding: 'utf8',
114
+ windowsHide: true,
115
+ timeout: TOOL_TIMEOUT_MS,
116
+ maxBuffer: TOOL_MAX_BUFFER_BYTES
117
+ });
118
+ if (result.error !== undefined && result.error !== null) {
119
+ return { ok: false, reason: result.error.message };
120
+ }
121
+ if (result.status !== 0) {
122
+ const output = result.stderr || result.stdout || `exit ${String(result.status)}`;
123
+ return { ok: false, reason: output.slice(0, REASON_EXCERPT_CHARS) };
124
+ }
125
+ return { ok: true, stdout: result.stdout ?? '' };
126
+ }
127
+ /**
128
+ * The project's own effective rules for a file set.
129
+ *
130
+ * Returns the rules AND the reasons the read could not produce them: a tool
131
+ * that is declared but not installed, or a file the tool could not resolve, is
132
+ * reported rather than dropped.
133
+ */
134
+ export function readProjectLintRules(projectRoot, tools, files, deps) {
135
+ const rules = [];
136
+ const reasons = [];
137
+ for (const tool of tools) {
138
+ const printer = CONFIG_PRINTERS.find((entry) => entry.tool === tool.name);
139
+ if (printer === undefined) {
140
+ rules.push(declaredCommandRule(tool));
141
+ continue;
142
+ }
143
+ const resolved = resolveWithTool(printer, projectRoot, files, deps);
144
+ rules.push(...resolved.rules);
145
+ reasons.push(...resolved.reasons);
146
+ // A tool that could not answer still tells the reader what the project
147
+ // DECLARES it runs — that part of the answer does not need the tool to be
148
+ // installed, and a reader who knows the gate runs `eslint .` is not lost.
149
+ if (resolved.rules.length === 0)
150
+ rules.push(declaredCommandRule(tool));
151
+ }
152
+ return { rules, reasons };
153
+ }
154
+ /** What a declared-but-unqueryable tool still tells the reader. */
155
+ function declaredCommandRule(tool) {
156
+ return {
157
+ layer: 'project',
158
+ source: tool.name,
159
+ pattern: tool.command,
160
+ rule: `the project runs \`${tool.command}\` (declared at ${tool.declaredBy})`
161
+ };
162
+ }
163
+ /** One tool's resolved configurations, grouped by content. */
164
+ function resolveWithTool(printer, projectRoot, files, deps) {
165
+ const byConfig = new Map();
166
+ const reasons = [];
167
+ for (const file of files) {
168
+ const invoked = runTool(printer.commandFor(file, projectRoot), projectRoot, deps);
169
+ if (!invoked.ok) {
170
+ reasons.push(`${printer.tool}: ${file}: ${invoked.reason}`);
171
+ continue;
172
+ }
173
+ const printed = parsePrintedConfig(invoked.stdout);
174
+ if (!printed.ok) {
175
+ reasons.push(`${printer.tool}: ${file}: ${printed.reason}`);
176
+ continue;
177
+ }
178
+ const rendered = printer.render(printed.config);
179
+ if (rendered === null) {
180
+ reasons.push(`${printer.tool}: ${file}: the tool printed no readable configuration`);
181
+ continue;
182
+ }
183
+ if (rendered.length === 0)
184
+ continue;
185
+ const covered = byConfig.get(rendered) ?? [];
186
+ covered.push(file);
187
+ byConfig.set(rendered, covered);
188
+ }
189
+ const rules = [];
190
+ for (const [rendered, covered] of byConfig) {
191
+ rules.push({
192
+ layer: 'project',
193
+ source: printer.tool,
194
+ pattern: covered.join(', '),
195
+ rule: rendered
196
+ });
197
+ }
198
+ return { rules, reasons };
199
+ }
@@ -0,0 +1,66 @@
1
+ /** Where a rule came from. */
2
+ export type RuleLayer = 'project' | 'language' | 'curated';
3
+ /** One effective rule, tagged with the layer that produced it. */
4
+ export interface EffectiveRule {
5
+ readonly layer: RuleLayer;
6
+ /** The concrete source: `eslint`, `ocr:system`, `ecc:typescript`, … */
7
+ readonly source: string;
8
+ /** The scope the rule was resolved for — a glob, or the files it covers. */
9
+ readonly pattern: string;
10
+ /** The rule text itself. */
11
+ readonly rule: string;
12
+ }
13
+ /** The three layers, read for one file set. */
14
+ export interface RuleSet {
15
+ /** The files the rules were read for, POSIX-normalized and deduplicated. */
16
+ readonly files: readonly string[];
17
+ readonly rules: readonly EffectiveRule[];
18
+ /** The lint tools the project declared, by name. */
19
+ readonly detectedTools: readonly string[];
20
+ /**
21
+ * Why the read looks the way it does. NEVER empty: a layer that could not
22
+ * be read says so here, because "no rules found" and "the layer never ran"
23
+ * are different answers and this repository has been bitten by that
24
+ * distinction before.
25
+ */
26
+ readonly reason: string;
27
+ }
28
+ /** A lint tool the project declared for itself. */
29
+ export interface ProjectLintTool {
30
+ /** The tool's name (`eslint`, `ruff`, `golangci-lint`, …). */
31
+ readonly name: string;
32
+ /** Where the project declared it — the declaration site, not a guess. */
33
+ readonly declaredBy: string;
34
+ /** The command the project declared. */
35
+ readonly command: string;
36
+ }
37
+ /** The outcome of looking for the project's own lint tooling. */
38
+ export interface ProjectLintToolDetection {
39
+ readonly tools: readonly ProjectLintTool[];
40
+ /**
41
+ * The explicit reason when no tool was found — never a silent empty list.
42
+ */
43
+ readonly reason: string;
44
+ /** Declaration sites that could not be read (malformed, unreadable, …). */
45
+ readonly problems: readonly string[];
46
+ }
47
+ /** The result of running one external tool as a subprocess. */
48
+ export type ToolInvocation = {
49
+ readonly ok: true;
50
+ readonly stdout: string;
51
+ } | {
52
+ readonly ok: false;
53
+ readonly reason: string;
54
+ };
55
+ /**
56
+ * The seams a test replaces so a rule read never spawns anything. Production
57
+ * callers pass nothing: every seam falls back to the real tool.
58
+ */
59
+ export interface RulePreReadDeps {
60
+ /** Replaces the OCR delegate rule invocation. */
61
+ readonly invokeDelegate?: (args: readonly string[], cwd: string) => ToolInvocation;
62
+ /** Replaces the invocation of a project's own lint tool. */
63
+ readonly invokeProjectTool?: (argv: readonly string[], cwd: string) => ToolInvocation;
64
+ /** Replaces the lookup of the curated (ECC) rule root. */
65
+ readonly resolveCuratedRoot?: () => string | null;
66
+ }
@@ -0,0 +1,22 @@
1
+ // src/services/lint/rule-pre-read-types.ts
2
+ //
3
+ // The shapes the rule pre-read speaks in.
4
+ //
5
+ // THREE LAYERS, THREE QUESTIONS. A rule set is only useful if a reader can
6
+ // tell WHERE a rule came from, because the three sources answer different
7
+ // questions and a fix that ignores one of them is still a fix that gets
8
+ // rejected:
9
+ //
10
+ // - `project` — "what will THIS project's gate reject?" (the project's own
11
+ // lint tooling, asked for its effective configuration)
12
+ // - `language` — "how should code in this language be written?" (the OCR
13
+ // delegate rule channel: deterministic, no key, no LLM call)
14
+ // - `curated` — "what are the general rules for this language?" (the ECC
15
+ // curated rule sets)
16
+ //
17
+ // `pattern` is the scope a rule was resolved for: a glob for the language and
18
+ // curated layers (the same pattern's text is emitted ONCE, never once per
19
+ // file), and the file list a project's resolved configuration covers for the
20
+ // project layer (a project's configuration is resolved per file, so the files
21
+ // that share one are named together).
22
+ export {};
@@ -0,0 +1,20 @@
1
+ import type { RulePreReadDeps, RuleSet } from './rule-pre-read-types.js';
2
+ export type { EffectiveRule, ProjectLintTool, ProjectLintToolDetection, RuleLayer, RulePreReadDeps, RuleSet, ToolInvocation } from './rule-pre-read-types.js';
3
+ export { detectProjectLintTools, NO_LINT_TOOL_REASON } from './project-lint-tool-detection.js';
4
+ /** The reason a read with no problem reports. */
5
+ export declare const RULES_RESOLVED_REASON = "all three layers resolved";
6
+ /**
7
+ * The effective rules for a file set, from all three layers.
8
+ *
9
+ * The returned `reason` is never empty: it names every layer that could not
10
+ * be read, and says so plainly when all three were.
11
+ */
12
+ export declare function readEffectiveRules(projectRoot: string, files: readonly string[], deps?: RulePreReadDeps): RuleSet;
13
+ /**
14
+ * The file set, repo-relative and POSIX-normalized.
15
+ *
16
+ * One file must be one string: a Windows path and a POSIX path naming the same
17
+ * file would otherwise be two entries, and a rule that governs one of them
18
+ * would look like it governs only half of the file.
19
+ */
20
+ export declare function normalizeFileSet(projectRoot: string, files: readonly string[]): readonly string[];
@@ -0,0 +1,145 @@
1
+ // src/services/lint/rule-pre-read.ts
2
+ //
3
+ // The rule pre-read — "what are the rules in force for these files?"
4
+ //
5
+ // THREE LAYERS, THREE QUESTIONS, NONE OF THEM OPTIONAL:
6
+ //
7
+ // L1 `project` — what will THIS project's gate reject? The project's own
8
+ // lint tooling, asked for its effective configuration.
9
+ // L2 `language` — how should code in this language be written? The OCR
10
+ // delegate rule channel: deterministic, no API key, no LLM
11
+ // call, and it accepts a plain path list.
12
+ // L3 `curated` — what are the general rules for this language? The ECC
13
+ // curated rule sets, matched by the file patterns each rule
14
+ // file declares.
15
+ //
16
+ // WHY THE FILE SET IS NEVER INSPECTED FOR A LANGUAGE. The mechanism is "ask
17
+ // the project what it declares", not "we support these languages". Nothing in
18
+ // this module — or in the three it composes — branches on the language of a
19
+ // file. A Go project, a Python project and a TypeScript project travel the
20
+ // same path; which rules come back is decided by what those projects declare.
21
+ //
22
+ // GROUPING IS WHAT KEEPS A FIX PROMPT SMALL. One TypeScript pattern carries
23
+ // about 2 KB of rule text, so the same pattern's text is emitted ONCE, never
24
+ // once per file. The layers that resolve per file (the project's own
25
+ // configuration) are grouped by the resolved text instead, so files that share
26
+ // a configuration share one entry.
27
+ //
28
+ // ZERO IS NOT "NEVER RAN". Every layer that could not be read says so in the
29
+ // reason, so a caller can tell "there are no rules" from "the layer was
30
+ // never asked".
31
+ import { buildDelegateRuleArgs, parseDelegateRules } from './ocr-18-delegate-payload.js';
32
+ import { invokeOcr } from './ocr-multilang-adapter.js';
33
+ import { readCuratedRules, resolveCuratedRulesRoot } from './curated-rule-reader.js';
34
+ import { detectProjectLintTools, NO_LINT_TOOL_REASON } from './project-lint-tool-detection.js';
35
+ import { readProjectLintRules } from './project-lint-tool-rules.js';
36
+ import { repoRelativeKey } from '../../shared/path-utils.js';
37
+ export { detectProjectLintTools, NO_LINT_TOOL_REASON } from './project-lint-tool-detection.js';
38
+ /** How long the language rule channel may take. */
39
+ const DELEGATE_TIMEOUT_MS = 60_000;
40
+ /** The reason a read with no problem reports. */
41
+ export const RULES_RESOLVED_REASON = 'all three layers resolved';
42
+ /**
43
+ * The effective rules for a file set, from all three layers.
44
+ *
45
+ * The returned `reason` is never empty: it names every layer that could not
46
+ * be read, and says so plainly when all three were.
47
+ */
48
+ export function readEffectiveRules(projectRoot, files, deps = {}) {
49
+ const normalized = normalizeFileSet(projectRoot, files);
50
+ const detection = detectProjectLintTools(projectRoot);
51
+ const reasons = [];
52
+ const rules = [];
53
+ if (detection.tools.length === 0) {
54
+ reasons.push(detection.reason === '' ? NO_LINT_TOOL_REASON : detection.reason);
55
+ }
56
+ else {
57
+ const project = readProjectLintRules(projectRoot, detection.tools, normalized, deps);
58
+ rules.push(...project.rules);
59
+ reasons.push(...project.reasons);
60
+ }
61
+ const language = readLanguageRules(projectRoot, normalized, deps);
62
+ rules.push(...language.rules);
63
+ reasons.push(...language.reasons);
64
+ const curated = readCuratedRules(normalized, curatedRootFor(deps));
65
+ rules.push(...curated.rules);
66
+ reasons.push(...curated.reasons);
67
+ return {
68
+ files: normalized,
69
+ rules,
70
+ detectedTools: detection.tools.map((tool) => tool.name),
71
+ reason: reasons.length === 0 ? RULES_RESOLVED_REASON : reasons.join('; ')
72
+ };
73
+ }
74
+ /**
75
+ * The file set, repo-relative and POSIX-normalized.
76
+ *
77
+ * One file must be one string: a Windows path and a POSIX path naming the same
78
+ * file would otherwise be two entries, and a rule that governs one of them
79
+ * would look like it governs only half of the file.
80
+ */
81
+ export function normalizeFileSet(projectRoot, files) {
82
+ const set = new Set();
83
+ for (const raw of files) {
84
+ if (typeof raw !== 'string' || raw.length === 0)
85
+ continue;
86
+ const relative = repoRelativeKey(raw, projectRoot).replace(/^\.\//, '');
87
+ if (relative.length > 0)
88
+ set.add(relative);
89
+ }
90
+ return [...set].sort();
91
+ }
92
+ /**
93
+ * L2 — the language rule channel.
94
+ *
95
+ * The channel is deterministic: it takes a path list and returns rule text
96
+ * grouped by pattern. No key is read and no model is called.
97
+ */
98
+ function readLanguageRules(projectRoot, files, deps) {
99
+ if (files.length === 0)
100
+ return { rules: [], reasons: [] };
101
+ const invoked = invokeDelegateChannel(files, projectRoot, deps);
102
+ if (!invoked.ok) {
103
+ return { rules: [], reasons: [`the language rule channel failed: ${invoked.reason}`] };
104
+ }
105
+ const parsed = parseDelegateRules(invoked.stdout);
106
+ if (!parsed.ok) {
107
+ return { rules: [], reasons: [`the language rule channel failed: ${parsed.rawOutput}`] };
108
+ }
109
+ const rules = [];
110
+ const seen = new Set();
111
+ for (const group of parsed.groups) {
112
+ // The same pattern's text is emitted ONCE — not once per file it covers.
113
+ const key = `${group.source} ${group.pattern}`;
114
+ if (seen.has(key))
115
+ continue;
116
+ seen.add(key);
117
+ rules.push({
118
+ layer: 'language',
119
+ source: `ocr:${group.source}`,
120
+ pattern: group.pattern,
121
+ rule: group.rule
122
+ });
123
+ }
124
+ return { rules, reasons: [] };
125
+ }
126
+ /** The language rule channel, through the test seam when there is one. */
127
+ function invokeDelegateChannel(files, projectRoot, deps) {
128
+ const args = buildDelegateRuleArgs(files, {});
129
+ if (deps.invokeDelegate !== undefined)
130
+ return deps.invokeDelegate(args, projectRoot);
131
+ const invoked = invokeOcr(args, projectRoot, DELEGATE_TIMEOUT_MS);
132
+ if (!invoked.ok) {
133
+ return { ok: false, reason: `${invoked.state}: ${invoked.rawOutput}` };
134
+ }
135
+ return { ok: true, stdout: invoked.stdout };
136
+ }
137
+ /** Where the curated rule sets live, through the test seam when there is one. */
138
+ function curatedRootFor(deps) {
139
+ if (deps.resolveCuratedRoot === undefined)
140
+ return resolveCuratedRulesRoot();
141
+ const path = deps.resolveCuratedRoot();
142
+ return path === null
143
+ ? { ok: false, reason: 'the curated rule sets are not available' }
144
+ : { ok: true, path };
145
+ }