@aryam/fixmap 0.8.8 → 0.9.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.
@@ -1,10 +1,13 @@
1
1
  import { readFileSync } from "node:fs";
2
- import { writeFile } from "node:fs/promises";
3
- import { dirname, join } from "node:path";
2
+ import { realpath, stat, writeFile } from "node:fs/promises";
3
+ import { homedir } from "node:os";
4
+ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
4
5
  import { fileURLToPath } from "node:url";
5
- import { compareReports, explainFile, renderComparisonMarkdown, renderExplanationMarkdown, renderJsonReport, renderVerifyMarkdown, resolveExclusions, verifyPlan, renderMarkdownReport, scanRepo, validateFixMapReport } from "@aryam/fixmap-core";
6
+ import { compareReports, explainFile, quoteCliValue as formatCliValue, renderComparisonMarkdown, renderExplanationMarkdown, renderAgentReport, renderJsonReport, renderVerifyMarkdown, resolveExclusions, verifyPlan, renderMarkdownReport, scanRepo, stripByteOrderMark, validateFixMapReport } from "@aryam/fixmap-core";
6
7
  import { runDoctorChecks, renderDoctorReport } from "./doctor.js";
7
- import { buildReportForRepository, parseGitHubIssueSource, progressRequested, tryParseGitHubIssueSource } from "./repository-source.js";
8
+ import { installAgentCommands, renderFeatureCatalog } from "./agent-setup.js";
9
+ import { clarifyMissingPath } from "./explain-path.js";
10
+ import { buildReportForRepository, isSafeGitRefName, parseGitHubIssueSource, progressRequested, tryParseGitHubIssueSource } from "./repository-source.js";
8
11
  export const USAGE = `FixMap maps an issue, prompt, or diff to context files, test routes, and review risks.
9
12
 
10
13
  Usage:
@@ -16,20 +19,38 @@ Usage:
16
19
  fixmap plan --issue-file task.md
17
20
  fixmap plan --issue -
18
21
  fixmap plan --issue "Fix login" --repo https://github.com/owner/repository
22
+ fixmap plan --issue "Fix login" --repo https://github.com/owner/repository --ref release-2.x
19
23
  fixmap plan --diff main...HEAD
20
24
  fixmap plan --working-tree --include-untracked --limit 12 --exclude "docs/**"
25
+ fixmap plan --no-cache --issue "Fix login" --repo .
21
26
  fixmap plan --issue "Fix login" --format json --output plan.json
27
+ fixmap plan --issue "Fix login" --format agent
22
28
  fixmap plan --issue "Fix login in auth middleware" --compare plan.json
23
29
  fixmap plan --base main --head HEAD --format json
24
30
  fixmap verify --report plan.json --diff main...HEAD
25
31
  fixmap verify --report plan.json --working-tree
32
+ fixmap verify --report plan.json --working-tree --fail-on warning
26
33
  fixmap doctor --format json
27
- fixmap mcp
34
+ fixmap validate plan.json
35
+ fixmap benchmark --repo . --last 50
36
+ fixmap context --issue "Fix login" --budget 10000
37
+ fixmap graph --issue "Fix login" --format mermaid
38
+ fixmap watch --report plan.json --repo .
39
+ fixmap features
40
+ fixmap setup [--agent claude|cursor|copilot|agents|all] [--repo <path>]
41
+ fixmap mcp [--repo <path>]
28
42
 
29
43
  Commands:
30
44
  plan Generate a FixMap report for a task or diff
31
45
  verify Compare a saved report against the diff that followed it
32
46
  doctor Check the FixMap install for stale global or npx shadows
47
+ validate Validate a saved FixMap JSON report
48
+ benchmark Backtest BM25, FixMap, and Impact Graph on pre-change snapshots
49
+ context Package the highest-value source ranges within a token budget
50
+ graph Export the evidence-backed Impact Graph as Mermaid or JSON
51
+ watch Recheck working-tree drift and impact whenever edits change
52
+ features List every FixMap capability and its command
53
+ setup Install a discoverable /fixmap command for coding agents
33
54
  mcp Run FixMap as an MCP server over stdio for AI coding agents
34
55
 
35
56
  Options:
@@ -42,22 +63,30 @@ Options:
42
63
  --include-untracked With --working-tree, also include untracked files
43
64
  --no-cache Bypass the exact git-state repository scan cache
44
65
  --repo <source> Local path or public GitHub HTTPS URL (defaults to current directory)
66
+ --ref <branch|tag> Branch or tag to scan when --repo is a remote GitHub URL
45
67
  --limit <n> Maximum context files to report (default 8, max 20)
46
68
  --exclude <glob> Path pattern to leave out of ranking (repeatable)
47
- --format <fmt> Output format: markdown (default) or json
69
+ --format <fmt> Output format: markdown (default), json, or compact agent
48
70
  --output <file> Write the report or verification to a file instead of stdout
49
71
  --explain <path> Explain why one file was ranked where it was, or left out
50
72
  --compare <file> Compare this plan against an earlier JSON report
51
73
  --report <file> Verify command only: the JSON report the change was planned from
74
+ --fail-on <level> Verify exit policy: error (default) or warning
52
75
  --help, -h Show this help
53
76
  --version, -v Show the FixMap version
54
77
 
55
78
  A repository may also list exclusion patterns in .fixmapignore, one per line. Supported
56
- syntax is *, **, ?, root-leading /, directory-trailing /, comments, and ! negation.
79
+ syntax is *, **, ?, repository-root-leading /, directory-trailing /, comments, and ! negation.
80
+ Absolute paths pasted from inside the repository are normalized to repository-relative patterns.
57
81
  Set FIXMAP_PROGRESS=1 to print scan and clone phases to stderr.
82
+ Set FIXMAP_CACHE_DIR to move the OS scan cache, and FIXMAP_VERBOSE_USAGE=1 to include this full help after argument errors.
58
83
  `;
59
84
  const DOCTOR_USAGE = `Usage: fixmap doctor [--format markdown|json]\n\nChecks the running FixMap binary, PATH/global shadows, and known install blind spots.\n`;
60
- const MCP_USAGE = `Usage: fixmap mcp\n\nRuns the FixMap MCP server over stdio. Configure your MCP client to execute \"fixmap mcp\".\n`;
85
+ const MCP_USAGE = `Usage: fixmap mcp [--repo <path>]\n\nRuns the FixMap MCP server over stdio. --repo sets the default local repository for tool calls that omit repo.\n`;
86
+ const FEATURES_USAGE = `Usage: fixmap features [--format markdown|json]\n\nLists every FixMap capability and the command that exposes it.\n`;
87
+ const SETUP_USAGE = `Usage: fixmap setup [--agent claude|cursor|copilot|agents|all] [--repo <path>] [--force]\n\nInstalls a /fixmap command that lists and runs FixMap workflows.\n`;
88
+ const VALIDATE_USAGE = `Usage: fixmap validate <report.json> [--format markdown|json]\n\nChecks a saved report against FixMap's structural compatibility contract.\n`;
89
+ const BENCHMARK_USAGE = `Usage: fixmap benchmark [--repo <local-path>] [--last <1-100>] [--format markdown|json] [--output <file>]\n\nBacktests BM25, FixMap, and Impact Graph against historical parent snapshots without executing repository code.\n`;
61
90
  export async function runCli(args, dependencies = {}) {
62
91
  const stdout = dependencies.stdout ?? ((text) => process.stdout.write(text));
63
92
  const stderr = dependencies.stderr ?? ((text) => process.stderr.write(text));
@@ -71,25 +100,333 @@ export async function runCli(args, dependencies = {}) {
71
100
  return 0;
72
101
  }
73
102
  if (args[0] === "version" || args[0] === "--version" || args[0] === "-v") {
74
- stdout(`${(dependencies.readVersion ?? readVersion)()}\n`);
75
- return 0;
103
+ try {
104
+ stdout(`${(dependencies.readVersion ?? readVersion)()}\n`);
105
+ return 0;
106
+ }
107
+ catch (error) {
108
+ stderr(`${error instanceof Error ? error.message : String(error)}\n`);
109
+ return 1;
110
+ }
76
111
  }
77
112
  if (args[0] === "mcp") {
78
113
  if (args[1] === "--help" || args[1] === "-h") {
79
114
  stdout(MCP_USAGE);
80
115
  return 0;
81
116
  }
82
- if (args.length > 1) {
83
- stderr(`mcp takes no options.\n\n${MCP_USAGE}`);
117
+ const mcpArgs = args.slice(1);
118
+ let defaultRepo;
119
+ if (mcpArgs.length === 1 && mcpArgs[0]?.startsWith("--repo=")) {
120
+ defaultRepo = mcpArgs[0].slice("--repo=".length).trim();
121
+ }
122
+ else if (mcpArgs.length === 2 && mcpArgs[0] === "--repo") {
123
+ defaultRepo = mcpArgs[1]?.trim();
124
+ }
125
+ else if (mcpArgs.length > 0) {
126
+ stderr(`mcp accepts only --repo <path>.\n\n${MCP_USAGE}`);
127
+ return 1;
128
+ }
129
+ if (defaultRepo !== undefined && !defaultRepo) {
130
+ stderr(`--repo needs a non-blank local path.\n\n${MCP_USAGE}`);
131
+ return 1;
132
+ }
133
+ if (defaultRepo && /^https?:\/\//i.test(defaultRepo)) {
134
+ stderr(`mcp --repo needs a local checkout, not a remote URL.\n\n${MCP_USAGE}`);
84
135
  return 1;
85
136
  }
86
137
  const runMcpServer = dependencies.runMcpServer ?? (async () => {
87
138
  const module = await import("./mcp.js");
88
- await module.runMcpServer();
139
+ await module.runMcpServer(defaultRepo);
89
140
  });
90
- await runMcpServer();
141
+ await runMcpServer(defaultRepo);
91
142
  return 0;
92
143
  }
144
+ if (args[0] === "features") {
145
+ const featureArgs = args.slice(1);
146
+ if (featureArgs[0] === "--help" || featureArgs[0] === "-h") {
147
+ stdout(FEATURES_USAGE);
148
+ return 0;
149
+ }
150
+ let format = "markdown";
151
+ if (featureArgs.length > 0) {
152
+ const value = featureArgs.length === 2 && featureArgs[0] === "--format"
153
+ ? featureArgs[1]
154
+ : featureArgs.length === 1
155
+ ? featureArgs[0]?.match(/^--format=(.+)$/)?.[1]
156
+ : undefined;
157
+ const normalized = value?.trim().toLowerCase();
158
+ if (normalized !== "markdown" && normalized !== "json") {
159
+ stderr('features accepts only --format markdown or --format json.\n');
160
+ return 1;
161
+ }
162
+ format = normalized;
163
+ }
164
+ stdout(renderFeatureCatalog(format));
165
+ return 0;
166
+ }
167
+ if (args[0] === "setup") {
168
+ if (args[1] === "--help" || args[1] === "-h") {
169
+ stdout(SETUP_USAGE);
170
+ return 0;
171
+ }
172
+ let repoRoot = process.cwd();
173
+ let targets = ["claude", "cursor", "copilot", "agents"];
174
+ let force = false;
175
+ let repoSeen = false;
176
+ let agentSeen = false;
177
+ for (let index = 1; index < args.length; index += 1) {
178
+ const arg = args[index];
179
+ if (arg === "--force") {
180
+ force = true;
181
+ continue;
182
+ }
183
+ if (arg?.startsWith("--repo=")) {
184
+ if (repoSeen) {
185
+ stderr(`Pass --repo only once.\n\n${SETUP_USAGE}`);
186
+ return 1;
187
+ }
188
+ const value = arg.slice("--repo=".length).trim();
189
+ if (!value) {
190
+ stderr(`--repo requires a directory.\n\n${SETUP_USAGE}`);
191
+ return 1;
192
+ }
193
+ repoRoot = expandHomePath(value);
194
+ repoSeen = true;
195
+ continue;
196
+ }
197
+ if (arg === "--repo") {
198
+ if (repoSeen) {
199
+ stderr(`Pass --repo only once.\n\n${SETUP_USAGE}`);
200
+ return 1;
201
+ }
202
+ const value = args[index + 1];
203
+ if (!value?.trim() || value.startsWith("--")) {
204
+ stderr(`--repo requires a directory.\n\n${SETUP_USAGE}`);
205
+ return 1;
206
+ }
207
+ repoRoot = expandHomePath(value.trim());
208
+ repoSeen = true;
209
+ index += 1;
210
+ continue;
211
+ }
212
+ if (arg?.startsWith("--agent=")) {
213
+ if (agentSeen) {
214
+ stderr(`Pass --agent only once.\n\n${SETUP_USAGE}`);
215
+ return 1;
216
+ }
217
+ const value = arg.slice("--agent=".length).trim().toLowerCase();
218
+ if (!["claude", "cursor", "copilot", "agents", "all"].includes(value)) {
219
+ stderr(`--agent must be claude, cursor, copilot, agents, or all.\n\n${SETUP_USAGE}`);
220
+ return 1;
221
+ }
222
+ targets = value === "all" ? ["claude", "cursor", "copilot", "agents"] : [value];
223
+ agentSeen = true;
224
+ continue;
225
+ }
226
+ if (arg === "--agent") {
227
+ if (agentSeen) {
228
+ stderr(`Pass --agent only once.\n\n${SETUP_USAGE}`);
229
+ return 1;
230
+ }
231
+ const value = args[index + 1]?.trim().toLowerCase();
232
+ if (!value || !["claude", "cursor", "copilot", "agents", "all"].includes(value)) {
233
+ stderr(`--agent must be claude, cursor, copilot, agents, or all.\n\n${SETUP_USAGE}`);
234
+ return 1;
235
+ }
236
+ targets = value === "all" ? ["claude", "cursor", "copilot", "agents"] : [value];
237
+ agentSeen = true;
238
+ index += 1;
239
+ continue;
240
+ }
241
+ stderr(`Unknown setup option: ${arg}\n\n${SETUP_USAGE}`);
242
+ return 1;
243
+ }
244
+ try {
245
+ const installed = await installAgentCommands({ repoRoot, targets, force });
246
+ stdout(`${installed.map((entry) => `${entry.status}: ${entry.path}`).join("\n")}\n\nType /fixmap in a supported agent to open the full FixMap feature menu.\n`);
247
+ return 0;
248
+ }
249
+ catch (error) {
250
+ stderr(`${error instanceof Error ? error.message : String(error)}\n`);
251
+ return 1;
252
+ }
253
+ }
254
+ if (args[0] === "validate") {
255
+ if (args[1] === "--help" || args[1] === "-h") {
256
+ stdout(VALIDATE_USAGE);
257
+ return 0;
258
+ }
259
+ let reportPath;
260
+ let format = "markdown";
261
+ let formatSeen = false;
262
+ for (let index = 1; index < args.length; index += 1) {
263
+ const arg = args[index];
264
+ if (arg === "--format") {
265
+ if (formatSeen) {
266
+ stderr(`Pass --format only once.\n\n${VALIDATE_USAGE}`);
267
+ return 1;
268
+ }
269
+ const value = args[index + 1]?.trim().toLowerCase();
270
+ if (value !== "markdown" && value !== "json") {
271
+ stderr(`--format must be markdown or json.\n\n${VALIDATE_USAGE}`);
272
+ return 1;
273
+ }
274
+ format = value;
275
+ formatSeen = true;
276
+ index += 1;
277
+ }
278
+ else if (arg.startsWith("--format=")) {
279
+ if (formatSeen) {
280
+ stderr(`Pass --format only once.\n\n${VALIDATE_USAGE}`);
281
+ return 1;
282
+ }
283
+ const value = arg.slice("--format=".length).trim().toLowerCase();
284
+ if (value !== "markdown" && value !== "json") {
285
+ stderr(`--format must be markdown or json.\n\n${VALIDATE_USAGE}`);
286
+ return 1;
287
+ }
288
+ format = value;
289
+ formatSeen = true;
290
+ }
291
+ else if (arg.startsWith("-") || reportPath) {
292
+ stderr(`Unknown validate argument: ${arg}\n\n${VALIDATE_USAGE}`);
293
+ return 1;
294
+ }
295
+ else {
296
+ reportPath = expandHomePath(arg);
297
+ }
298
+ }
299
+ if (!reportPath) {
300
+ stderr(`validate requires a report path.\n\n${VALIDATE_USAGE}`);
301
+ return 1;
302
+ }
303
+ try {
304
+ const parsed = JSON.parse(stripByteOrderMark(readFileSync(reportPath, "utf8")));
305
+ const result = validateFixMapReport(parsed, `"${reportPath}"`);
306
+ if (!result.success) {
307
+ stderr(`${result.message}\n`);
308
+ return 1;
309
+ }
310
+ const payload = {
311
+ valid: true,
312
+ path: reportPath,
313
+ reportVersion: result.report.reportVersion ?? "legacy",
314
+ contextFiles: result.report.contextFiles.length
315
+ };
316
+ stdout(format === "json"
317
+ ? `${JSON.stringify(payload, null, 2)}\n`
318
+ : `Valid FixMap report: ${reportPath} (${payload.contextFiles} context files, reportVersion ${payload.reportVersion}).\n`);
319
+ return 0;
320
+ }
321
+ catch (error) {
322
+ stderr(`Could not validate "${reportPath}": ${error instanceof Error ? error.message : String(error)}\n`);
323
+ return 1;
324
+ }
325
+ }
326
+ if (args[0] === "benchmark") {
327
+ if (args[1] === "--help" || args[1] === "-h") {
328
+ stdout(BENCHMARK_USAGE);
329
+ return 0;
330
+ }
331
+ let repoRoot = process.cwd();
332
+ let last;
333
+ let format = "markdown";
334
+ let output;
335
+ const seen = new Set();
336
+ for (let index = 1; index < args.length; index += 1) {
337
+ const raw = args[index];
338
+ const separator = raw.indexOf("=");
339
+ const flag = separator === -1 ? raw : raw.slice(0, separator);
340
+ const inline = separator === -1 ? undefined : raw.slice(separator + 1);
341
+ if (!new Set(["--repo", "--last", "--format", "--output"]).has(flag) || seen.has(flag)) {
342
+ stderr(`${seen.has(flag) ? `Pass ${flag} only once.` : `Unknown benchmark option: ${raw}`}\n\n${BENCHMARK_USAGE}`);
343
+ return 1;
344
+ }
345
+ seen.add(flag);
346
+ const following = args[index + 1];
347
+ const value = inline ?? (following && !following.startsWith("-") ? following : undefined);
348
+ if (inline === undefined && value !== undefined)
349
+ index += 1;
350
+ if (!value?.trim()) {
351
+ stderr(`${flag} requires a value.\n\n${BENCHMARK_USAGE}`);
352
+ return 1;
353
+ }
354
+ if (flag === "--repo")
355
+ repoRoot = expandHomePath(value.trim());
356
+ else if (flag === "--output")
357
+ output = expandHomePath(value.trim());
358
+ else if (flag === "--format") {
359
+ const normalized = value.trim().toLowerCase();
360
+ if (normalized !== "markdown" && normalized !== "json") {
361
+ stderr(`--format must be markdown or json.\n\n${BENCHMARK_USAGE}`);
362
+ return 1;
363
+ }
364
+ format = normalized;
365
+ }
366
+ else {
367
+ const parsed = Number(value);
368
+ if (!/^\d+$/.test(value) || !Number.isSafeInteger(parsed) || parsed < 1 || parsed > 100) {
369
+ stderr(`--last must be a whole number from 1 to 100.\n\n${BENCHMARK_USAGE}`);
370
+ return 1;
371
+ }
372
+ last = parsed;
373
+ }
374
+ }
375
+ if (/^https?:\/\//i.test(repoRoot)) {
376
+ stderr(`benchmark --repo needs a local Git checkout so history cutoffs can be enforced.\n\n${BENCHMARK_USAGE}`);
377
+ return 1;
378
+ }
379
+ try {
380
+ const benchmarkModule = dependencies.benchmarkRepository && dependencies.renderBenchmark
381
+ ? undefined
382
+ : await import("./benchmark.js");
383
+ const result = await (dependencies.benchmarkRepository ?? benchmarkModule.benchmarkRepository)({
384
+ repoRoot,
385
+ ...(last === undefined ? {} : { last }),
386
+ progress: (message) => {
387
+ if (progressRequested(process.env.FIXMAP_PROGRESS) || process.stderr.isTTY)
388
+ stderr(`${message}\n`);
389
+ }
390
+ });
391
+ const rendered = format === "json"
392
+ ? `${JSON.stringify(result, null, 2)}\n`
393
+ : (dependencies.renderBenchmark ?? benchmarkModule.renderRepositoryBenchmark)(result);
394
+ if (output)
395
+ await (dependencies.writeReport ?? ((path, contents) => writeFile(path, contents, "utf8")))(output, rendered);
396
+ else
397
+ stdout(rendered);
398
+ return 0;
399
+ }
400
+ catch (error) {
401
+ stderr(`${error instanceof Error ? error.message : String(error)}\n`);
402
+ return 1;
403
+ }
404
+ }
405
+ if (args[0] === "context") {
406
+ const { runContextCommand } = await import("./analysis-commands.js");
407
+ return runContextCommand(args.slice(1), {
408
+ stdout,
409
+ stderr,
410
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
411
+ });
412
+ }
413
+ if (args[0] === "graph") {
414
+ const { runGraphCommand } = await import("./analysis-commands.js");
415
+ return runGraphCommand(args.slice(1), {
416
+ stdout,
417
+ stderr,
418
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
419
+ });
420
+ }
421
+ if (args[0] === "watch") {
422
+ const { runWatchCommand } = await import("./watch-command.js");
423
+ return runWatchCommand(args.slice(1), {
424
+ stdout,
425
+ stderr,
426
+ watchRepository: dependencies.watchRepository,
427
+ renderWatchUpdate: dependencies.renderWatchUpdate
428
+ });
429
+ }
93
430
  if (args[0] === "doctor") {
94
431
  if (args[1] === "--help" || args[1] === "-h") {
95
432
  stdout(DOCTOR_USAGE);
@@ -100,7 +437,7 @@ export async function runCli(args, dependencies = {}) {
100
437
  if (doctorArgs.length > 0) {
101
438
  const match = doctorArgs.length === 2 && doctorArgs[0] === "--format" ? doctorArgs[1] :
102
439
  doctorArgs.length === 1 ? doctorArgs[0]?.match(/^--format=(.+)$/)?.[1] : undefined;
103
- const normalized = match?.toLowerCase();
440
+ const normalized = match?.trim().toLowerCase();
104
441
  if (normalized === "markdown" || normalized === "json")
105
442
  doctorFormat = normalized;
106
443
  else {
@@ -114,7 +451,7 @@ export async function runCli(args, dependencies = {}) {
114
451
  // not read the text and carry on.
115
452
  return report.healthy ? 0 : 1;
116
453
  }
117
- if ((args[0] === "plan" || args[0] === "verify") && args.slice(1).some((arg) => arg === "--help" || arg === "-h")) {
454
+ if ((args[0] === "plan" || args[0] === "verify") && hasStandaloneHelpFlag(args)) {
118
455
  stdout(USAGE);
119
456
  return 0;
120
457
  }
@@ -146,6 +483,11 @@ export async function runCli(args, dependencies = {}) {
146
483
  stderr(`verify does not accept plan-only option(s): ${planOnly.join(", ")}.\n`);
147
484
  return 1;
148
485
  }
486
+ const outputCollision = await describeOutputInputCollision(options);
487
+ if (outputCollision) {
488
+ stderr(`${outputCollision}\n`);
489
+ return 1;
490
+ }
149
491
  return runVerify(options, {
150
492
  stdout,
151
493
  stderr,
@@ -156,6 +498,15 @@ export async function runCli(args, dependencies = {}) {
156
498
  stderr(withUsageHint("--report is a verify option. Did you mean --output to write this plan to a file?"));
157
499
  return 1;
158
500
  }
501
+ if (options.failOn) {
502
+ stderr(withUsageHint("--fail-on is a verify option. Use it with fixmap verify."));
503
+ return 1;
504
+ }
505
+ const outputCollision = await describeOutputInputCollision(options);
506
+ if (outputCollision) {
507
+ stderr(`${outputCollision}\n`);
508
+ return 1;
509
+ }
159
510
  try {
160
511
  options.issueText = loadIssueText(options, dependencies.readIssueFile ?? defaultReadIssueFile);
161
512
  }
@@ -175,7 +526,7 @@ export async function runCli(args, dependencies = {}) {
175
526
  stderr("--include-untracked only applies with --working-tree.\n");
176
527
  return 1;
177
528
  }
178
- if (options.workingTree && (options.diffSpec || options.baseRef)) {
529
+ if (options.workingTree && (options.diffSpec || options.baseRef || options.headRef)) {
179
530
  stderr("Use either --working-tree or --diff/--base, not both: they name different sets of changes.\n");
180
531
  return 1;
181
532
  }
@@ -195,6 +546,12 @@ export async function runCli(args, dependencies = {}) {
195
546
  stderr("--working-tree and --include-untracked need a local checkout; remote URL checkouts are always clean.\n");
196
547
  return 1;
197
548
  }
549
+ const remoteIssueSource = options.issueText ? tryParseGitHubIssueSource(options.issueText) : undefined;
550
+ const remoteRepository = /^https?:\/\//i.test(options.repo ?? "") || (!options.repo && remoteIssueSource !== undefined);
551
+ if (options.checkoutRef && !remoteRepository) {
552
+ stderr("--ref only applies when --repo is a remote GitHub URL or the issue URL infers one.\n");
553
+ return 1;
554
+ }
198
555
  const unsupportedTaskUrl = describeUnsupportedTaskUrl(options.issueText);
199
556
  if (unsupportedTaskUrl) {
200
557
  stderr(`${unsupportedTaskUrl}\n`);
@@ -210,19 +567,48 @@ export async function runCli(args, dependencies = {}) {
210
567
  }
211
568
  try {
212
569
  const repoRoot = options.repo ?? process.cwd();
213
- const repo = await scanRepo({ repoRoot, diffSpec: options.diffSpec, baseRef: options.baseRef, headRef: options.headRef, workingTree: options.workingTree, includeUntracked: options.includeUntracked, useCache: !options.noCache });
214
- const explanation = explainFile(repo, {
570
+ const repo = await scanRepo({
571
+ repoRoot,
572
+ diffSpec: options.diffSpec,
573
+ baseRef: options.baseRef,
574
+ headRef: options.headRef,
575
+ workingTree: options.workingTree,
576
+ includeUntracked: options.includeUntracked,
577
+ useCache: !options.noCache,
578
+ internalExclude: localPlanArtifactExclusions(options)
579
+ });
580
+ const unresolvedDiff = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
581
+ if (unresolvedDiff && (options.diffSpec || options.baseRef || options.headRef || options.workingTree)) {
582
+ stderr(`${unresolvedDiff.message}\nExplanation needs a resolvable diff to include change evidence.\n`);
583
+ return 1;
584
+ }
585
+ const explanation = await clarifyMissingPath(explainFile(repo, {
215
586
  issueText: options.issueText,
216
587
  diffText: repo.diffText,
217
588
  // Without this, a file left out by .fixmapignore would be reported as having
218
589
  // scored below the cutoff — a false answer to the exact question --explain exists
219
590
  // to answer.
220
- exclude: await resolveExclusions(repoRoot, options.exclude),
591
+ exclude: await resolveExclusions(repoRoot, [
592
+ ...options.exclude,
593
+ ...localPlanArtifactExclusions(options)
594
+ ]),
221
595
  limit: options.limit
222
- }, options.explainPath);
223
- stdout(options.format === "json"
596
+ }, options.explainPath), repo, options.explainPath);
597
+ const renderedExplanation = options.format === "json"
224
598
  ? `${JSON.stringify(explanation, null, 2)}\n`
225
- : renderExplanationMarkdown(explanation));
599
+ : renderExplanationMarkdown(explanation);
600
+ if (options.output) {
601
+ try {
602
+ await (dependencies.writeReport ?? ((path, contents) => writeFile(path, contents, "utf8")))(options.output, renderedExplanation);
603
+ }
604
+ catch (error) {
605
+ stderr(formatOutputError(options.output, error, "explanation"));
606
+ return 1;
607
+ }
608
+ }
609
+ else {
610
+ stdout(renderedExplanation);
611
+ }
226
612
  return 0;
227
613
  }
228
614
  catch (error) {
@@ -238,11 +624,13 @@ export async function runCli(args, dependencies = {}) {
238
624
  diffSpec: options.diffSpec,
239
625
  baseRef: options.baseRef,
240
626
  headRef: options.headRef,
627
+ checkoutRef: options.checkoutRef,
241
628
  workingTree: options.workingTree,
242
629
  includeUntracked: options.includeUntracked,
243
630
  useCache: !options.noCache,
244
631
  limit: options.limit,
245
- exclude: options.exclude
632
+ exclude: options.exclude,
633
+ internalExclude: localPlanArtifactExclusions(options)
246
634
  });
247
635
  }
248
636
  catch (error) {
@@ -285,7 +673,7 @@ export async function runCli(args, dependencies = {}) {
285
673
  let previous;
286
674
  let previousText;
287
675
  try {
288
- previousText = readFileSync(options.comparePath, "utf8");
676
+ previousText = stripByteOrderMark(readFileSync(options.comparePath, "utf8"));
289
677
  }
290
678
  catch (error) {
291
679
  stderr(`Could not read comparison file "${options.comparePath}": ${error instanceof Error ? error.message : String(error)}\n` +
@@ -347,7 +735,11 @@ export async function runCli(args, dependencies = {}) {
347
735
  : "\nComparison complete. Refine the task or inspect the files that entered, moved, or changed confidence, then rerun the plan.\n");
348
736
  return unresolvedChangeRequest ? 1 : 0;
349
737
  }
350
- const rendered = options.format === "json" ? renderJsonReport(report) : renderMarkdownReport(report);
738
+ const rendered = options.format === "json"
739
+ ? renderJsonReport(report)
740
+ : options.format === "agent"
741
+ ? renderAgentReport(report)
742
+ : renderMarkdownReport(report);
351
743
  if (options.output) {
352
744
  try {
353
745
  await (dependencies.writeReport ?? ((path, contents) => writeFile(path, contents, "utf8")))(options.output, rendered);
@@ -452,6 +844,8 @@ export function expandIssueShorthand(args) {
452
844
  if (!shorthand)
453
845
  return args;
454
846
  const [, owner, repository, number] = shorthand;
847
+ if (!/[A-Za-z]/.test(owner ?? ""))
848
+ return ["plan", "--issue", first, ...args.slice(1)];
455
849
  return ["plan", "--issue", `https://github.com/${owner}/${repository}/issues/${number}`, ...args.slice(1)];
456
850
  }
457
851
  // --exclude is deliberately absent: it is the one flag that accumulates, because naming
@@ -462,14 +856,34 @@ const SINGLE_VALUE_FLAGS = new Set([
462
856
  "--diff",
463
857
  "--base",
464
858
  "--head",
859
+ "--ref",
465
860
  "--repo",
466
861
  "--format",
467
862
  "--report",
468
863
  "--explain",
469
864
  "--compare",
470
865
  "--limit",
866
+ "--fail-on",
471
867
  "--output"
472
868
  ]);
869
+ const BOOLEAN_FLAGS = new Set(["--working-tree", "--include-untracked", "--no-cache"]);
870
+ function hasStandaloneHelpFlag(args) {
871
+ for (let index = 1; index < args.length; index += 1) {
872
+ const raw = args[index] ?? "";
873
+ if (raw === "--help" || raw === "-h")
874
+ return true;
875
+ const separator = raw.indexOf("=");
876
+ const flag = separator === -1 ? raw : raw.slice(0, separator);
877
+ if (separator === -1 && (SINGLE_VALUE_FLAGS.has(flag) || flag === "--exclude"))
878
+ index += 1;
879
+ }
880
+ return false;
881
+ }
882
+ function isKnownOptionToken(value) {
883
+ const separator = value.indexOf("=");
884
+ const flag = separator === -1 ? value : value.slice(0, separator);
885
+ return SINGLE_VALUE_FLAGS.has(flag) || BOOLEAN_FLAGS.has(flag) || flag === "--exclude" || flag === "--help" || flag === "-h";
886
+ }
473
887
  export const MAX_CONTEXT_FILE_LIMIT = 20;
474
888
  export function parseArgs(args) {
475
889
  const command = args[0] ?? "";
@@ -479,12 +893,14 @@ export function parseArgs(args) {
479
893
  let diffSpec;
480
894
  let baseRef;
481
895
  let headRef;
896
+ let checkoutRef;
482
897
  let format = "markdown";
483
898
  let output;
484
899
  let explainPath;
485
900
  let reportPath;
486
901
  let comparePath;
487
902
  let limit;
903
+ let failOn;
488
904
  let workingTree = false;
489
905
  let includeUntracked = false;
490
906
  let noCache = false;
@@ -504,6 +920,7 @@ export function parseArgs(args) {
504
920
  const canConsumeFollowing = inlineValue === undefined &&
505
921
  followingValue !== undefined &&
506
922
  (!followingValue.startsWith("-") ||
923
+ (arg === "--issue" && !isKnownOptionToken(followingValue)) ||
507
924
  (arg === "--limit" && /^-\d/.test(followingValue)) ||
508
925
  ((arg === "--issue" || arg === "--issue-file") && followingValue === "-"));
509
926
  const value = inlineValue ?? (canConsumeFollowing ? followingValue : undefined);
@@ -535,52 +952,61 @@ export function parseArgs(args) {
535
952
  else if (arg === "--issue-file") {
536
953
  consumeValue();
537
954
  if (value?.trim())
538
- issueFile = value.trim();
955
+ issueFile = expandHomePath(value.trim());
539
956
  else
540
957
  invalidValues.push("--issue-file requires a UTF-8 file path or - for stdin");
541
958
  }
542
959
  else if (arg === "--diff") {
543
960
  consumeValue();
544
961
  if (value?.trim())
545
- diffSpec = value;
962
+ diffSpec = value.trim();
546
963
  else
547
964
  invalidValues.push("--diff requires a non-empty git diff spec");
548
965
  }
549
966
  else if (arg === "--base") {
550
967
  consumeValue();
551
968
  if (value?.trim())
552
- baseRef = value;
969
+ baseRef = value.trim();
553
970
  else
554
971
  invalidValues.push("--base requires a non-empty git ref");
555
972
  }
556
973
  else if (arg === "--head") {
557
974
  consumeValue();
558
975
  if (value?.trim())
559
- headRef = value;
976
+ headRef = value.trim();
560
977
  else
561
978
  invalidValues.push("--head requires a non-empty git ref");
562
979
  }
980
+ else if (arg === "--ref") {
981
+ consumeValue();
982
+ if (value?.trim() && isSafeGitRefName(value.trim())) {
983
+ checkoutRef = value.trim();
984
+ }
985
+ else {
986
+ invalidValues.push("--ref requires a safe branch or tag name");
987
+ }
988
+ }
563
989
  else if (arg === "--repo") {
564
990
  consumeValue();
565
991
  if (value?.trim())
566
- repo = value;
992
+ repo = expandHomePath(value.trim());
567
993
  else
568
994
  invalidValues.push("--repo requires a local path or public GitHub repository URL");
569
995
  }
570
996
  else if (arg === "--format") {
571
997
  consumeValue();
572
- const normalized = value?.toLowerCase();
573
- if (normalized === "markdown" || normalized === "json") {
998
+ const normalized = value?.trim().toLowerCase();
999
+ if (normalized === "markdown" || normalized === "json" || normalized === "agent") {
574
1000
  format = normalized;
575
1001
  }
576
1002
  else {
577
- invalidValues.push(`--format received ${JSON.stringify(value ?? "(missing)")}; expected "markdown" or "json"`);
1003
+ invalidValues.push(`--format received ${JSON.stringify(value ?? "(missing)")}; expected "markdown", "json", or "agent"`);
578
1004
  }
579
1005
  }
580
1006
  else if (arg === "--report") {
581
1007
  consumeValue();
582
1008
  if (value?.trim())
583
- reportPath = value.trim();
1009
+ reportPath = expandHomePath(value.trim());
584
1010
  else
585
1011
  invalidValues.push("--report requires a path to a FixMap JSON report");
586
1012
  }
@@ -594,7 +1020,7 @@ export function parseArgs(args) {
594
1020
  else if (arg === "--compare") {
595
1021
  consumeValue();
596
1022
  if (value?.trim())
597
- comparePath = value.trim();
1023
+ comparePath = expandHomePath(value.trim());
598
1024
  else
599
1025
  invalidValues.push("--compare requires a path to an earlier FixMap JSON report");
600
1026
  }
@@ -607,36 +1033,54 @@ export function parseArgs(args) {
607
1033
  }
608
1034
  else if (arg === "--limit") {
609
1035
  consumeValue();
610
- const parsed = Number(value);
611
- if (value?.trim() && Number.isSafeInteger(parsed) && parsed >= 1 && parsed <= MAX_CONTEXT_FILE_LIMIT) {
1036
+ const normalized = value?.trim() ?? "";
1037
+ const parsed = Number(normalized);
1038
+ if (/^\d+$/.test(normalized) && Number.isSafeInteger(parsed) && parsed >= 1 && parsed <= MAX_CONTEXT_FILE_LIMIT) {
612
1039
  limit = parsed;
613
1040
  }
614
1041
  else {
615
1042
  invalidValues.push(`--limit received ${JSON.stringify(value ?? "(missing)")}; expected a whole number from 1 to ${MAX_CONTEXT_FILE_LIMIT}`);
616
1043
  }
617
1044
  }
1045
+ else if (arg === "--fail-on") {
1046
+ consumeValue();
1047
+ const normalized = value?.trim().toLowerCase();
1048
+ if (normalized === "error" || normalized === "warning")
1049
+ failOn = normalized;
1050
+ else
1051
+ invalidValues.push(`--fail-on received ${JSON.stringify(value ?? "(missing)")}; expected "error" or "warning"`);
1052
+ }
618
1053
  else if (arg === "--working-tree") {
619
1054
  if (flagCounts.has(arg))
620
1055
  invalidValues.push(`pass ${arg} only once`);
621
1056
  flagCounts.set(arg, 1);
622
- workingTree = true;
1057
+ if (inlineValue !== undefined)
1058
+ invalidValues.push(`${arg} does not accept a value; pass ${arg} by itself`);
1059
+ else
1060
+ workingTree = true;
623
1061
  }
624
1062
  else if (arg === "--include-untracked") {
625
1063
  if (flagCounts.has(arg))
626
1064
  invalidValues.push(`pass ${arg} only once`);
627
1065
  flagCounts.set(arg, 1);
628
- includeUntracked = true;
1066
+ if (inlineValue !== undefined)
1067
+ invalidValues.push(`${arg} does not accept a value; pass ${arg} by itself`);
1068
+ else
1069
+ includeUntracked = true;
629
1070
  }
630
1071
  else if (arg === "--no-cache") {
631
1072
  if (flagCounts.has(arg))
632
1073
  invalidValues.push(`pass ${arg} only once`);
633
1074
  flagCounts.set(arg, 1);
634
- noCache = true;
1075
+ if (inlineValue !== undefined)
1076
+ invalidValues.push(`${arg} does not accept a value; pass ${arg} by itself`);
1077
+ else
1078
+ noCache = true;
635
1079
  }
636
1080
  else if (arg === "--output") {
637
1081
  consumeValue();
638
1082
  if (value?.trim())
639
- output = value;
1083
+ output = expandHomePath(value.trim());
640
1084
  else
641
1085
  invalidValues.push("--output requires a non-empty file path");
642
1086
  }
@@ -652,12 +1096,14 @@ export function parseArgs(args) {
652
1096
  diffSpec,
653
1097
  baseRef,
654
1098
  headRef,
1099
+ checkoutRef,
655
1100
  format,
656
1101
  output,
657
1102
  explainPath,
658
1103
  reportPath,
659
1104
  comparePath,
660
1105
  limit,
1106
+ failOn,
661
1107
  exclude,
662
1108
  workingTree,
663
1109
  includeUntracked,
@@ -666,6 +1112,100 @@ export function parseArgs(args) {
666
1112
  invalidValues
667
1113
  };
668
1114
  }
1115
+ function expandHomePath(value) {
1116
+ if (value === "~")
1117
+ return homedir();
1118
+ if (value.startsWith("~/") || value.startsWith("~\\")) {
1119
+ return join(homedir(), value.slice(2));
1120
+ }
1121
+ return value;
1122
+ }
1123
+ /**
1124
+ * Inputs and outputs generated by the current FixMap workflow are rich in the task's own
1125
+ * vocabulary. If they live inside the scanned checkout, ranking them as repository context
1126
+ * creates a self-fulfilling result (`plan.json` explaining why `plan.json` is relevant).
1127
+ */
1128
+ function localPlanArtifactExclusions(options) {
1129
+ const remoteIssue = options.issueText ? parseGitHubIssueSource(options.issueText) : undefined;
1130
+ const remoteRepository = /^https?:\/\//i.test(options.repo ?? "") || (remoteIssue && !options.repo);
1131
+ if (remoteRepository)
1132
+ return [];
1133
+ const root = resolve(options.repo ?? process.cwd());
1134
+ return [
1135
+ options.output,
1136
+ options.comparePath,
1137
+ options.reportPath,
1138
+ options.issueFile === "-" ? undefined : options.issueFile
1139
+ ]
1140
+ .filter((path) => path !== undefined)
1141
+ .map((path) => resolve(path))
1142
+ .filter((path) => {
1143
+ const distance = relative(root, path);
1144
+ return distance !== "" && distance !== ".." && !distance.startsWith(`..${sep}`) && !isAbsolute(distance);
1145
+ });
1146
+ }
1147
+ /**
1148
+ * A workflow input must remain usable after the command finishes. Reading a plan, task, or
1149
+ * source file and then writing the result back through the same path silently destroyed the
1150
+ * only copy while still exiting zero. Compare both path spelling and filesystem identity so
1151
+ * relative aliases, symlinks, and hardlinks receive the same protection.
1152
+ */
1153
+ async function describeOutputInputCollision(options) {
1154
+ if (!options.output)
1155
+ return undefined;
1156
+ const inputs = [];
1157
+ if (options.command === "verify" && options.reportPath) {
1158
+ inputs.push({ flag: "--report", path: options.reportPath });
1159
+ }
1160
+ else {
1161
+ if (options.issueFile && options.issueFile !== "-") {
1162
+ inputs.push({ flag: "--issue-file", path: options.issueFile });
1163
+ }
1164
+ if (options.comparePath) {
1165
+ inputs.push({ flag: "--compare", path: options.comparePath });
1166
+ }
1167
+ if (options.explainPath) {
1168
+ inputs.push({
1169
+ flag: "--explain",
1170
+ path: isAbsolute(options.explainPath)
1171
+ ? options.explainPath
1172
+ : resolve(options.repo ?? process.cwd(), options.explainPath)
1173
+ });
1174
+ }
1175
+ }
1176
+ for (const input of inputs) {
1177
+ if (await pathsReferToSameFile(options.output, input.path)) {
1178
+ return `Refusing to write --output "${options.output}" because it is the same file as ${input.flag} "${input.path}". ` +
1179
+ "Choose a different --output path so FixMap does not overwrite its input.";
1180
+ }
1181
+ }
1182
+ return undefined;
1183
+ }
1184
+ async function pathsReferToSameFile(leftPath, rightPath) {
1185
+ const left = resolve(leftPath);
1186
+ const right = resolve(rightPath);
1187
+ const normalize = process.platform === "win32"
1188
+ ? (path) => path.toLowerCase()
1189
+ : (path) => path;
1190
+ if (normalize(left) === normalize(right))
1191
+ return true;
1192
+ try {
1193
+ const [leftReal, rightReal] = await Promise.all([realpath(left), realpath(right)]);
1194
+ if (normalize(leftReal) === normalize(rightReal))
1195
+ return true;
1196
+ }
1197
+ catch {
1198
+ // A missing path cannot already alias an existing input. The command that consumes it
1199
+ // will produce the more useful read/write error later.
1200
+ }
1201
+ try {
1202
+ const [leftStat, rightStat] = await Promise.all([stat(left), stat(right)]);
1203
+ return leftStat.ino !== 0 && leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
1204
+ }
1205
+ catch {
1206
+ return false;
1207
+ }
1208
+ }
669
1209
  function loadIssueText(options, read) {
670
1210
  const path = options.issueFile ?? (options.issueText === "-" ? "-" : undefined);
671
1211
  if (!path) {
@@ -707,14 +1247,39 @@ function decodeIssueText(raw) {
707
1247
  }
708
1248
  return swapped.toString("utf16le").replace(/^\uFEFF/, "");
709
1249
  }
1250
+ if (raw.length >= 4 && raw.length % 2 === 0) {
1251
+ let evenNuls = 0;
1252
+ let oddNuls = 0;
1253
+ for (let index = 0; index < raw.length; index += 2) {
1254
+ if (raw[index] === 0)
1255
+ evenNuls += 1;
1256
+ if (raw[index + 1] === 0)
1257
+ oddNuls += 1;
1258
+ }
1259
+ const pairs = raw.length / 2;
1260
+ if (oddNuls / pairs >= 0.3 && evenNuls / pairs < 0.1)
1261
+ return raw.toString("utf16le");
1262
+ if (evenNuls / pairs >= 0.3 && oddNuls / pairs < 0.1)
1263
+ return Buffer.from(raw).swap16().toString("utf16le");
1264
+ }
710
1265
  return raw.toString("utf8").replace(/^\uFEFF/, "");
711
1266
  }
712
1267
  function quoteCliValue(value) {
713
- return /\s/.test(value) ? `"${value.replaceAll('"', '\\"')}"` : value;
1268
+ return formatCliValue(value, process.platform === "win32" ? "powershell" : "posix");
714
1269
  }
715
1270
  function readVersion() {
716
- const packageJson = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
717
- return packageJson.version;
1271
+ const path = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
1272
+ try {
1273
+ const packageJson = JSON.parse(readFileSync(path, "utf8"));
1274
+ if (typeof packageJson.version !== "string" || !packageJson.version.trim()) {
1275
+ throw new Error("the version field is missing or invalid");
1276
+ }
1277
+ return packageJson.version;
1278
+ }
1279
+ catch (error) {
1280
+ throw new Error(`FixMap could not read its version from "${path}"; the installation looks incomplete: ` +
1281
+ `${error instanceof Error ? error.message : String(error)}`);
1282
+ }
718
1283
  }
719
1284
  /**
720
1285
  * Compares a saved plan against the diff that followed it. Both inputs are things the
@@ -754,7 +1319,7 @@ async function runVerify(options, io) {
754
1319
  }
755
1320
  let reportText;
756
1321
  try {
757
- reportText = readFileSync(options.reportPath, "utf8");
1322
+ reportText = stripByteOrderMark(readFileSync(options.reportPath, "utf8"));
758
1323
  }
759
1324
  catch (error) {
760
1325
  io.stderr(`Could not read "${options.reportPath}": ${error instanceof Error ? error.message : String(error)}\n` +
@@ -801,7 +1366,9 @@ async function runVerify(options, io) {
801
1366
  headRef: options.headRef,
802
1367
  workingTree: options.workingTree,
803
1368
  includeUntracked: options.includeUntracked,
804
- useCache: !options.noCache
1369
+ useCache: !options.noCache,
1370
+ includeHistory: true,
1371
+ internalExclude: localPlanArtifactExclusions(options)
805
1372
  });
806
1373
  const unresolvedDiff = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
807
1374
  if (unresolvedDiff) {
@@ -826,7 +1393,8 @@ async function runVerify(options, io) {
826
1393
  }
827
1394
  // A generated-location edit is discarded by the next build, so it fails the command
828
1395
  // rather than being reported and ignored. Everything else is advisory.
829
- return result.findings.some((finding) => finding.severity === "error") ? 1 : 0;
1396
+ const failOn = options.failOn ?? "error";
1397
+ return result.findings.some((finding) => finding.severity === "error" || (failOn === "warning" && finding.severity === "warning")) ? 1 : 0;
830
1398
  }
831
1399
  catch (error) {
832
1400
  io.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
@@ -848,7 +1416,8 @@ function describeUnsupportedTaskUrl(issueText) {
848
1416
  return undefined;
849
1417
  return "Unsupported task URL. Use a public GitHub issue or pull request URL such as " +
850
1418
  "https://github.com/owner/repository/issues/123 or /pull/123, or pass descriptive task text. " +
851
- "A ?query, #fragment, and a www. or api. host are accepted and normalized; other hosts, credentials and ports are not.";
1419
+ "The URL must use https. A ?query, #fragment, and a www. or api. host are accepted and normalized; " +
1420
+ "other hosts, credentials and ports are not.";
852
1421
  }
853
1422
  function formatOutputError(path, error, kind) {
854
1423
  const candidate = error;