@aryam/fixmap 0.8.0 → 0.8.2

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.
@@ -4,18 +4,25 @@ import { dirname, join } from "node:path";
4
4
  import { fileURLToPath } from "node:url";
5
5
  import { compareReports, explainFile, renderComparisonMarkdown, renderExplanationMarkdown, renderJsonReport, renderVerifyMarkdown, resolveExclusions, verifyPlan, renderMarkdownReport, scanRepo } from "@aryam/fixmap-core";
6
6
  import { runDoctorChecks, renderDoctorReport } from "./doctor.js";
7
- import { buildReportForRepository, parseGitHubIssueSource } from "./repository-source.js";
7
+ import { buildReportForRepository, parseGitHubIssueSource, progressRequested, tryParseGitHubIssueSource } from "./repository-source.js";
8
8
  export const USAGE = `FixMap maps an issue, prompt, or diff to context files, test routes, and review risks.
9
9
 
10
10
  Usage:
11
+ fixmap owner/repository#123
12
+ fixmap https://github.com/owner/repository/issues/123
11
13
  fixmap plan --issue "Users cannot reset passwords"
12
14
  fixmap plan --issue https://github.com/owner/repository/issues/123
15
+ fixmap plan --issue https://github.com/owner/repository/pull/123
13
16
  fixmap plan --issue-file task.md
14
17
  fixmap plan --issue -
15
18
  fixmap plan --issue "Fix login" --repo https://github.com/owner/repository
16
19
  fixmap plan --diff main...HEAD
20
+ fixmap plan --working-tree --include-untracked --limit 12 --exclude "docs/**"
21
+ fixmap plan --issue "Fix login" --format json --output current.json --compare previous.json
17
22
  fixmap plan --base main --head HEAD --format json
18
23
  fixmap verify --report fixmap-report.json --diff main...HEAD
24
+ fixmap verify --report fixmap-report.json --working-tree
25
+ fixmap doctor --format json
19
26
  fixmap mcp
20
27
 
21
28
  Commands:
@@ -25,9 +32,9 @@ Commands:
25
32
  mcp Run FixMap as an MCP server over stdio for AI coding agents
26
33
 
27
34
  Options:
28
- --issue <text|url> Issue text, task description, or public GitHub issue URL
29
- --issue-file <file> Read task text from a UTF-8 file (use - for stdin)
30
- --diff <spec> Git diff spec, such as main...HEAD
35
+ --issue <text|url> Task text, or a public GitHub issue or pull request URL
36
+ --issue-file <file> Read task text from a UTF-8 or UTF-16 file (use - for stdin)
37
+ --diff <spec> Git diff spec, such as main...HEAD (the repository scan can still rank untracked candidates)
31
38
  --base <ref> Base ref for diffing when --diff is not given
32
39
  --head <ref> Head ref for diffing (defaults to HEAD)
33
40
  --working-tree Map staged and unstaged changes against HEAD
@@ -43,25 +50,37 @@ Options:
43
50
  --help, -h Show this help
44
51
  --version, -v Show the FixMap version
45
52
 
46
- A repository may also list exclusion patterns in .fixmapignore, one per line.
53
+ A repository may also list exclusion patterns in .fixmapignore, one per line. Supported
54
+ syntax is *, **, ?, root-leading /, directory-trailing /, comments, and ! negation.
47
55
  Set FIXMAP_PROGRESS=1 to print scan and clone phases to stderr.
48
56
  `;
57
+ const DOCTOR_USAGE = `Usage: fixmap doctor [--format markdown|json]\n\nChecks the running FixMap binary, PATH/global shadows, and known install blind spots.\n`;
58
+ const MCP_USAGE = `Usage: fixmap mcp\n\nRuns the FixMap MCP server over stdio. Configure your MCP client to execute \"fixmap mcp\".\n`;
49
59
  export async function runCli(args, dependencies = {}) {
50
60
  const stdout = dependencies.stdout ?? ((text) => process.stdout.write(text));
51
61
  const stderr = dependencies.stderr ?? ((text) => process.stderr.write(text));
62
+ args = expandIssueShorthand(args);
52
63
  if (args.length === 0) {
53
64
  stdout(USAGE);
54
65
  return 1;
55
66
  }
56
- if (args[0] === "help" || args.includes("--help") || args.includes("-h")) {
67
+ if (args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
57
68
  stdout(USAGE);
58
69
  return 0;
59
70
  }
60
- if (args[0] === "version" || args.includes("--version") || args.includes("-v")) {
71
+ if (args[0] === "version" || args[0] === "--version" || args[0] === "-v") {
61
72
  stdout(`${(dependencies.readVersion ?? readVersion)()}\n`);
62
73
  return 0;
63
74
  }
64
75
  if (args[0] === "mcp") {
76
+ if (args[1] === "--help" || args[1] === "-h") {
77
+ stdout(MCP_USAGE);
78
+ return 0;
79
+ }
80
+ if (args.length > 1) {
81
+ stderr(`mcp takes no options.\n\n${MCP_USAGE}`);
82
+ return 1;
83
+ }
65
84
  const runMcpServer = dependencies.runMcpServer ?? (async () => {
66
85
  const module = await import("./mcp.js");
67
86
  await module.runMcpServer();
@@ -70,15 +89,40 @@ export async function runCli(args, dependencies = {}) {
70
89
  return 0;
71
90
  }
72
91
  if (args[0] === "doctor") {
92
+ if (args[1] === "--help" || args[1] === "-h") {
93
+ stdout(DOCTOR_USAGE);
94
+ return 0;
95
+ }
96
+ const doctorArgs = args.slice(1);
97
+ let doctorFormat = "markdown";
98
+ if (doctorArgs.length > 0) {
99
+ const match = doctorArgs.length === 2 && doctorArgs[0] === "--format" ? doctorArgs[1] :
100
+ doctorArgs.length === 1 ? doctorArgs[0]?.match(/^--format=(.+)$/)?.[1] : undefined;
101
+ const normalized = match?.toLowerCase();
102
+ if (normalized === "markdown" || normalized === "json")
103
+ doctorFormat = normalized;
104
+ else {
105
+ stderr(`Unknown doctor option(s): ${doctorArgs.join(", ")}\n\n${DOCTOR_USAGE}`);
106
+ return 1;
107
+ }
108
+ }
73
109
  const report = await (dependencies.runDoctor ?? runDoctorChecks)();
74
- stdout(renderDoctorReport(report));
110
+ stdout(doctorFormat === "json" ? `${JSON.stringify(report, null, 2)}\n` : renderDoctorReport(report));
75
111
  // Non-zero on a detected shadow: a script that runs doctor in CI should fail there,
76
112
  // not read the text and carry on.
77
113
  return report.healthy ? 0 : 1;
78
114
  }
115
+ if ((args[0] === "plan" || args[0] === "verify") && args.slice(1).some((arg) => arg === "--help" || arg === "-h")) {
116
+ stdout(USAGE);
117
+ return 0;
118
+ }
79
119
  const options = parseArgs(args);
120
+ if (options.command.startsWith("-")) {
121
+ stderr(withUsageHint(`FixMap needs a subcommand. Try: fixmap plan ${args.join(" ")}`));
122
+ return 1;
123
+ }
80
124
  if (options.command !== "plan" && options.command !== "verify") {
81
- stderr(`Unknown command: ${options.command || "(none)"}\n\n${USAGE}`);
125
+ stderr(withUsageHint(`Unknown command: ${options.command || "(none)"}`));
82
126
  return 1;
83
127
  }
84
128
  if (options.invalidValues.length > 0 || options.unknownArgs.length > 0) {
@@ -88,12 +132,18 @@ export async function runCli(args, dependencies = {}) {
88
132
  : "",
89
133
  options.unknownArgs.length > 0
90
134
  ? `Unknown option(s): ${options.unknownArgs.join(", ")}`
91
- : ""
135
+ : "",
136
+ describeMisplacedGlobalFlags(options.unknownArgs)
92
137
  ].filter(Boolean);
93
- stderr(`${sections.join("\n")}\n\n${USAGE}`);
138
+ stderr(withUsageHint(sections.join("\n")));
94
139
  return 1;
95
140
  }
96
141
  if (options.command === "verify") {
142
+ const planOnly = [options.issueText && "--issue", options.issueFile && "--issue-file", options.comparePath && "--compare", options.limit !== undefined && "--limit", options.exclude.length > 0 && "--exclude", options.explainPath && "--explain"].filter(Boolean);
143
+ if (planOnly.length > 0) {
144
+ stderr(`verify does not accept plan-only option(s): ${planOnly.join(", ")}.\n`);
145
+ return 1;
146
+ }
97
147
  return runVerify(options, {
98
148
  stdout,
99
149
  stderr,
@@ -107,7 +157,11 @@ export async function runCli(args, dependencies = {}) {
107
157
  stderr(`${error instanceof Error ? error.message : String(error)}\n`);
108
158
  return 1;
109
159
  }
110
- if (!options.issueText && !options.diffSpec && !options.baseRef && !options.workingTree) {
160
+ // --explain answers two different kinds of question. "Why did this rank where it did?"
161
+ // needs a task to rank against; "was this file even scanned, or is it excluded?" is a
162
+ // property of the repository alone. Requiring a task signal for both made the second
163
+ // unaskable, which is the one you reach for when a file is missing from a report.
164
+ if (!options.issueText && !options.diffSpec && !options.baseRef && !options.workingTree && !options.explainPath) {
111
165
  stderr("Provide --issue, --diff, --base/--head, or --working-tree so FixMap has a task signal.\n");
112
166
  return 1;
113
167
  }
@@ -119,6 +173,27 @@ export async function runCli(args, dependencies = {}) {
119
173
  stderr("Use either --working-tree or --diff/--base, not both: they name different sets of changes.\n");
120
174
  return 1;
121
175
  }
176
+ if (options.diffSpec && (options.baseRef || options.headRef)) {
177
+ stderr("Use either --diff or --base/--head, not both.\n");
178
+ return 1;
179
+ }
180
+ if (options.headRef && !options.baseRef) {
181
+ stderr("--head requires --base; use --diff when you already have a complete range.\n");
182
+ return 1;
183
+ }
184
+ if (options.explainPath && options.comparePath) {
185
+ stderr("Use either --explain or --compare, not both.\n");
186
+ return 1;
187
+ }
188
+ if (/^https?:\/\//i.test(options.repo ?? "") && (options.workingTree || options.includeUntracked)) {
189
+ stderr("--working-tree and --include-untracked need a local checkout; remote URL checkouts are always clean.\n");
190
+ return 1;
191
+ }
192
+ const unsupportedTaskUrl = describeUnsupportedTaskUrl(options.issueText);
193
+ if (unsupportedTaskUrl) {
194
+ stderr(`${unsupportedTaskUrl}\n`);
195
+ return 1;
196
+ }
122
197
  if (options.explainPath) {
123
198
  // Explaining a ranking needs the scanned repository, not just the finished report,
124
199
  // so this runs against a local checkout. Remote mode already excludes anything
@@ -129,13 +204,14 @@ export async function runCli(args, dependencies = {}) {
129
204
  }
130
205
  try {
131
206
  const repoRoot = options.repo ?? process.cwd();
132
- const repo = await scanRepo({ repoRoot });
207
+ const repo = await scanRepo({ repoRoot, diffSpec: options.diffSpec, baseRef: options.baseRef, headRef: options.headRef, workingTree: options.workingTree, includeUntracked: options.includeUntracked });
133
208
  const explanation = explainFile(repo, {
134
209
  issueText: options.issueText,
135
210
  // Without this, a file left out by .fixmapignore would be reported as having
136
211
  // scored below the cutoff — a false answer to the exact question --explain exists
137
212
  // to answer.
138
- exclude: await resolveExclusions(repoRoot, options.exclude)
213
+ exclude: await resolveExclusions(repoRoot, options.exclude),
214
+ limit: options.limit
139
215
  }, options.explainPath);
140
216
  stdout(options.format === "json"
141
217
  ? `${JSON.stringify(explanation, null, 2)}\n`
@@ -165,16 +241,32 @@ export async function runCli(args, dependencies = {}) {
165
241
  stderr(`${error instanceof Error ? error.message : String(error)}\n`);
166
242
  return 1;
167
243
  }
244
+ // An explicitly requested diff that could not be resolved is a failed request, whether or
245
+ // not task text happened to be available to rank from. Exiting 0 with a warning buried in
246
+ // the diagnostics told every script and agent checking `$?` that the named diff had been
247
+ // applied, and the report says `changedFiles: []` with no way to tell the two apart.
248
+ const diffFailure = report.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
249
+ const changeRequested = Boolean(options.diffSpec || options.baseRef || options.headRef || options.workingTree);
250
+ // The report is still written and still useful, so it is not suppressed — but the exit
251
+ // code has to say the request failed. Reporting success told every script checking `$?`
252
+ // that the named diff had been applied, and `changedFiles: []` reads identically whether
253
+ // the diff was empty or never resolved.
254
+ const unresolvedChangeRequest = Boolean(diffFailure) && changeRequested;
255
+ if (unresolvedChangeRequest && options.issueText) {
256
+ stderr(`${diffFailure.message}\n` +
257
+ "This plan ranks from the task text alone and is not diff-aware. " +
258
+ "Fix the ref, or drop the change option to ask for a task-text plan deliberately.\n");
259
+ }
168
260
  if (!options.issueText) {
169
- const diffFailure = report.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
170
261
  if (diffFailure) {
171
262
  stderr(`${diffFailure.message}\n` +
172
263
  "No --issue text was provided to fall back to, so this report would be empty. Fix the ref or add --issue.\n");
173
264
  return 1;
174
265
  }
175
266
  if (report.changedFiles.length === 0) {
176
- stderr("The requested diff resolved to zero changed files and no --issue text was provided. " +
177
- "Choose a non-empty diff or add --issue.\n");
267
+ stderr((options.workingTree
268
+ ? "The working tree has zero selected changes and no --issue text was provided. Make a tracked change, add --include-untracked, or add --issue.\n"
269
+ : "The requested diff resolved to zero changed files and no --issue text was provided. Choose a non-empty diff or add --issue.\n"));
178
270
  return 1;
179
271
  }
180
272
  }
@@ -183,22 +275,62 @@ export async function runCli(args, dependencies = {}) {
183
275
  // report is what the reader already has from the previous run.
184
276
  if (options.comparePath) {
185
277
  let previous;
278
+ let previousText;
186
279
  try {
187
- previous = JSON.parse(readFileSync(options.comparePath, "utf8"));
280
+ previousText = readFileSync(options.comparePath, "utf8");
188
281
  }
189
282
  catch (error) {
190
- stderr(`Could not read "${options.comparePath}": ${error instanceof Error ? error.message : String(error)}\n` +
283
+ stderr(`Could not read comparison file "${options.comparePath}": ${error instanceof Error ? error.message : String(error)}\n` +
191
284
  "Save one first with: fixmap plan --issue \"...\" --format json --output previous.json\n");
192
285
  return 1;
193
286
  }
287
+ if (!previousText.trim()) {
288
+ stderr(`Comparison file "${options.comparePath}" is empty. Save a JSON plan with --format json first.\n`);
289
+ return 1;
290
+ }
291
+ if (/^\s*#\s*FixMap/i.test(previousText)) {
292
+ stderr(`"${options.comparePath}" is a Markdown report. --compare requires the JSON plan saved with --format json.\n`);
293
+ return 1;
294
+ }
295
+ try {
296
+ previous = JSON.parse(previousText);
297
+ }
298
+ catch (error) {
299
+ stderr(`"${options.comparePath}" is not valid JSON: ${error instanceof Error ? error.message : String(error)}\n`);
300
+ return 1;
301
+ }
194
302
  if (!Array.isArray(previous.contextFiles)) {
195
- stderr(`"${options.comparePath}" is not a FixMap JSON report: no contextFiles array.\n`);
303
+ stderr(`"${options.comparePath}" is valid JSON but not a FixMap report: no contextFiles array.\n`);
196
304
  return 1;
197
305
  }
198
306
  const comparison = compareReports(previous, report);
199
- stdout(options.format === "json"
307
+ const renderedComparison = options.format === "json"
200
308
  ? `${JSON.stringify(comparison, null, 2)}\n`
201
- : renderComparisonMarkdown(comparison));
309
+ : renderComparisonMarkdown(comparison);
310
+ if (options.output) {
311
+ try {
312
+ await (dependencies.writeReport ?? ((path, contents) => writeFile(path, contents, "utf8")))(options.output, renderedComparison);
313
+ }
314
+ catch (error) {
315
+ stderr(formatOutputError(options.output, error, "comparison"));
316
+ return 1;
317
+ }
318
+ // The file holds the comparison, not the plan that produced it — so the obvious next
319
+ // loop, comparing again against this run, needs a plan that was never saved. Saying so
320
+ // beats discovering it one run later.
321
+ stderr(`Wrote the comparison to "${options.output}". The plan itself was not saved; ` +
322
+ "rerun without --compare and with --output to keep it as the baseline for the next comparison.\n");
323
+ }
324
+ else
325
+ stdout(renderedComparison);
326
+ // Telling someone to inspect what entered, moved or changed confidence when nothing did
327
+ // reads as though the output were misread. An unchanged comparison is a real answer: the
328
+ // task edit made no difference, and the next move is a different edit, not a closer look.
329
+ const moved = comparison.entered.length + comparison.left.length +
330
+ comparison.moved.length + comparison.confidenceChanged.length;
331
+ stderr(moved === 0
332
+ ? "\nComparison complete. Nothing entered, left, moved, or changed confidence — that task edit did not affect the ranking. Try naming a symbol, error string, or path from the file you expect.\n"
333
+ : "\nComparison complete. Refine the task or inspect the files that entered, moved, or changed confidence, then rerun the plan.\n");
202
334
  return 0;
203
335
  }
204
336
  const rendered = options.format === "json" ? renderJsonReport(report) : renderMarkdownReport(report);
@@ -207,7 +339,7 @@ export async function runCli(args, dependencies = {}) {
207
339
  await (dependencies.writeReport ?? ((path, contents) => writeFile(path, contents, "utf8")))(options.output, rendered);
208
340
  }
209
341
  catch (error) {
210
- stderr(`Could not write report to "${options.output}": ${error instanceof Error ? error.message : String(error)}\n`);
342
+ stderr(formatOutputError(options.output, error, "report"));
211
343
  return 1;
212
344
  }
213
345
  }
@@ -218,7 +350,7 @@ export async function runCli(args, dependencies = {}) {
218
350
  if (hint) {
219
351
  stderr(hint);
220
352
  }
221
- return 0;
353
+ return unresolvedChangeRequest ? 1 : 0;
222
354
  }
223
355
  /**
224
356
  * Names the command that helps next, on stderr so the report itself stays clean for
@@ -252,6 +384,9 @@ function nextCommandHint(options, report) {
252
384
  // placeholder `<base>...HEAD` inside a copy-paste command replaced that with a line
253
385
  // that looks runnable and is not. Keep the command runnable-as-printed and put the
254
386
  // part the user must supply on its own line, outside it.
387
+ if (options.workingTree) {
388
+ return `${prefix}${command} --working-tree${options.includeUntracked ? " --include-untracked" : ""}${repo}\n`;
389
+ }
255
390
  const diff = options.diffSpec ??
256
391
  (options.baseRef ? `${options.baseRef}...${options.headRef ?? "HEAD"}` : undefined);
257
392
  if (!diff) {
@@ -262,6 +397,49 @@ function nextCommandHint(options, report) {
262
397
  }
263
398
  return undefined;
264
399
  }
400
+ /**
401
+ * The common first run should read like a destination, not parser plumbing. A canonical
402
+ * GitHub issue/PR URL and GitHub's familiar owner/repository#number shorthand both mean
403
+ * `plan --issue`; every existing explicit command remains valid.
404
+ */
405
+ /**
406
+ * Reprinting the whole USAGE block put the one line that mattered thirty lines above the
407
+ * cursor, and PowerShell's NativeCommandError wrapping buried it further. The cause comes
408
+ * first and the full block stays one flag away; FIXMAP_VERBOSE_USAGE=1 restores it inline
409
+ * for anyone who was relying on it.
410
+ */
411
+ function withUsageHint(message) {
412
+ return progressRequested(process.env.FIXMAP_VERBOSE_USAGE)
413
+ ? `${message}\n\n${USAGE}`
414
+ : `${message}\n\nRun "fixmap --help" for the full usage, or set FIXMAP_VERBOSE_USAGE=1 to print it with every error.\n`;
415
+ }
416
+ /**
417
+ * `--version` and `--help` are real flags that simply do not belong after a subcommand.
418
+ * "Unknown option" is true of the position and false of the flag, which reads as though
419
+ * FixMap has no such option at all.
420
+ */
421
+ function describeMisplacedGlobalFlags(unknownArgs) {
422
+ const misplaced = unknownArgs.filter((arg) => ["--version", "-v", "--help", "-h"].includes(arg));
423
+ if (misplaced.length === 0)
424
+ return "";
425
+ const canonical = misplaced[0] === "--help" || misplaced[0] === "-h" ? "--help" : "--version";
426
+ return `${misplaced.join(", ")} ${misplaced.length === 1 ? "is a global flag" : "are global flags"}, not a plan option. Run "fixmap ${canonical}" instead.`;
427
+ }
428
+ export function expandIssueShorthand(args) {
429
+ const first = args[0]?.trim();
430
+ if (!first)
431
+ return args;
432
+ // Any GitHub host we might normalize routes through plan, whether or not it parses:
433
+ // a malformed one should receive plan's specific URL guidance, not "unknown command".
434
+ if (/^https?:\/\/(?:www\.|api\.)?github\.com\//i.test(first)) {
435
+ return ["plan", "--issue", first, ...args.slice(1)];
436
+ }
437
+ const shorthand = first.match(/^([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]+)#([1-9]\d*)$/);
438
+ if (!shorthand)
439
+ return args;
440
+ const [, owner, repository, number] = shorthand;
441
+ return ["plan", "--issue", `https://github.com/${owner}/${repository}/issues/${number}`, ...args.slice(1)];
442
+ }
265
443
  // --exclude is deliberately absent: it is the one flag that accumulates, because naming
266
444
  // several directories to leave out is the normal way to use it.
267
445
  const SINGLE_VALUE_FLAGS = new Set([
@@ -311,6 +489,7 @@ export function parseArgs(args) {
311
489
  const canConsumeFollowing = inlineValue === undefined &&
312
490
  followingValue !== undefined &&
313
491
  (!followingValue.startsWith("-") ||
492
+ (arg === "--limit" && /^-\d/.test(followingValue)) ||
314
493
  ((arg === "--issue" || arg === "--issue-file") && followingValue === "-"));
315
494
  const value = inlineValue ?? (canConsumeFollowing ? followingValue : undefined);
316
495
  const consumeValue = () => {
@@ -375,8 +554,9 @@ export function parseArgs(args) {
375
554
  }
376
555
  else if (arg === "--format") {
377
556
  consumeValue();
378
- if (value === "markdown" || value === "json") {
379
- format = value;
557
+ const normalized = value?.toLowerCase();
558
+ if (normalized === "markdown" || normalized === "json") {
559
+ format = normalized;
380
560
  }
381
561
  else {
382
562
  invalidValues.push(`--format received ${JSON.stringify(value ?? "(missing)")}; expected "markdown" or "json"`);
@@ -421,9 +601,15 @@ export function parseArgs(args) {
421
601
  }
422
602
  }
423
603
  else if (arg === "--working-tree") {
604
+ if (flagCounts.has(arg))
605
+ invalidValues.push(`pass ${arg} only once`);
606
+ flagCounts.set(arg, 1);
424
607
  workingTree = true;
425
608
  }
426
609
  else if (arg === "--include-untracked") {
610
+ if (flagCounts.has(arg))
611
+ invalidValues.push(`pass ${arg} only once`);
612
+ flagCounts.set(arg, 1);
427
613
  includeUntracked = true;
428
614
  }
429
615
  else if (arg === "--output") {
@@ -468,21 +654,39 @@ function loadIssueText(options, read) {
468
654
  throw new Error("Use either --issue or --issue-file, not both.");
469
655
  }
470
656
  const source = path === "-" ? 0 : path;
471
- let text;
657
+ let raw;
472
658
  try {
473
- text = read(source);
659
+ raw = read(source);
474
660
  }
475
661
  catch (error) {
476
662
  throw new Error(`Could not read issue text from ${path === "-" ? "stdin" : `\"${path}\"`}: ` +
477
663
  `${error instanceof Error ? error.message : String(error)}`);
478
664
  }
665
+ const text = decodeIssueText(raw);
479
666
  if (!text.trim()) {
480
667
  throw new Error(`Issue text from ${path === "-" ? "stdin" : `\"${path}\"`} was empty.`);
481
668
  }
482
669
  return text.trim();
483
670
  }
484
671
  function defaultReadIssueFile(path) {
485
- return readFileSync(path, "utf8");
672
+ return readFileSync(path);
673
+ }
674
+ /** Decode the encodings commonly produced by editors on every supported platform. */
675
+ function decodeIssueText(raw) {
676
+ if (typeof raw === "string")
677
+ return raw.replace(/^\uFEFF/, "");
678
+ if (raw.length >= 2 && raw[0] === 0xff && raw[1] === 0xfe) {
679
+ return raw.subarray(2).toString("utf16le").replace(/^\uFEFF/, "");
680
+ }
681
+ if (raw.length >= 2 && raw[0] === 0xfe && raw[1] === 0xff) {
682
+ const swapped = Buffer.allocUnsafe(raw.length - 2);
683
+ for (let index = 2; index + 1 < raw.length; index += 2) {
684
+ swapped[index - 2] = raw[index + 1];
685
+ swapped[index - 1] = raw[index];
686
+ }
687
+ return swapped.toString("utf16le").replace(/^\uFEFF/, "");
688
+ }
689
+ return raw.toString("utf8").replace(/^\uFEFF/, "");
486
690
  }
487
691
  function quoteCliValue(value) {
488
692
  return /\s/.test(value) ? `"${value.replaceAll('"', '\\"')}"` : value;
@@ -496,28 +700,69 @@ function readVersion() {
496
700
  * user already has, so nothing is executed and no repository code runs.
497
701
  */
498
702
  async function runVerify(options, io) {
703
+ if (options.includeUntracked && !options.workingTree) {
704
+ io.stderr("--include-untracked only applies with --working-tree.\n");
705
+ return 1;
706
+ }
707
+ if (options.workingTree && (options.diffSpec || options.baseRef || options.headRef)) {
708
+ io.stderr("Use either --working-tree or --diff/--base, not both.\n");
709
+ return 1;
710
+ }
711
+ if (options.diffSpec && (options.baseRef || options.headRef)) {
712
+ io.stderr("Use either --diff or --base/--head, not both.\n");
713
+ return 1;
714
+ }
715
+ if (options.headRef && !options.baseRef) {
716
+ io.stderr("--head requires --base; use --diff when you already have a complete range.\n");
717
+ return 1;
718
+ }
499
719
  if (!options.reportPath) {
500
- io.stderr("Provide --report with the JSON report this change was planned from.\n");
720
+ const changeSource = !options.diffSpec && !options.baseRef && !options.workingTree
721
+ ? " Also provide --diff, --base/--head, or --working-tree so FixMap can see what changed."
722
+ : "";
723
+ io.stderr(`Provide --report with the JSON report this change was planned from.${changeSource}\n`);
501
724
  return 1;
502
725
  }
503
- if (!options.diffSpec && !options.baseRef) {
504
- io.stderr("Provide --diff or --base/--head so FixMap can see what changed.\n");
726
+ if (!options.diffSpec && !options.baseRef && !options.workingTree) {
727
+ io.stderr("Provide --diff, --base/--head, or --working-tree so FixMap can see what changed.\n");
505
728
  return 1;
506
729
  }
507
730
  if (/^https?:\/\//i.test(options.repo ?? "")) {
508
731
  io.stderr("verify needs a local checkout; remote mode cannot resolve a diff.\n");
509
732
  return 1;
510
733
  }
511
- let report;
734
+ let reportText;
512
735
  try {
513
- report = JSON.parse(readFileSync(options.reportPath, "utf8"));
736
+ reportText = readFileSync(options.reportPath, "utf8");
514
737
  }
515
738
  catch (error) {
516
739
  io.stderr(`Could not read "${options.reportPath}": ${error instanceof Error ? error.message : String(error)}\n` +
517
740
  "Generate one with: fixmap plan --issue \"...\" --format json --output fixmap-report.json\n");
518
741
  return 1;
519
742
  }
743
+ // --compare already detected this and said so plainly; verify raised a raw
744
+ // `Unexpected token '#'` from JSON.parse, which describes the parser rather than the
745
+ // mistake. Passing the markdown report is the obvious thing to try first.
746
+ if (/^\s*#\s*FixMap/i.test(reportText)) {
747
+ io.stderr(`"${options.reportPath}" is a Markdown report. verify --report requires the JSON plan saved with --format json.\n` +
748
+ "Generate one with: fixmap plan --issue \"...\" --format json --output fixmap-report.json\n");
749
+ return 1;
750
+ }
751
+ let report;
752
+ try {
753
+ report = JSON.parse(reportText);
754
+ }
755
+ catch (error) {
756
+ io.stderr(`"${options.reportPath}" is not valid JSON: ${error instanceof Error ? error.message : String(error)}\n` +
757
+ "Generate one with: fixmap plan --issue \"...\" --format json --output fixmap-report.json\n");
758
+ return 1;
759
+ }
520
760
  if (!Array.isArray(report.contextFiles)) {
761
+ if (isReportComparison(report)) {
762
+ io.stderr(`"${options.reportPath}" is a FixMap comparison result, not a plan report. ` +
763
+ "Pass the original JSON plan written by fixmap plan --format json.\n");
764
+ return 1;
765
+ }
521
766
  io.stderr(`"${options.reportPath}" is not a FixMap JSON report: no contextFiles array.\n`);
522
767
  return 1;
523
768
  }
@@ -526,7 +771,9 @@ async function runVerify(options, io) {
526
771
  repoRoot: options.repo ?? process.cwd(),
527
772
  diffSpec: options.diffSpec,
528
773
  baseRef: options.baseRef,
529
- headRef: options.headRef
774
+ headRef: options.headRef,
775
+ workingTree: options.workingTree,
776
+ includeUntracked: options.includeUntracked
530
777
  });
531
778
  const unresolvedDiff = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
532
779
  if (unresolvedDiff) {
@@ -542,8 +789,7 @@ async function runVerify(options, io) {
542
789
  await io.writeReport(options.output, rendered);
543
790
  }
544
791
  catch (error) {
545
- io.stderr(`Could not write verification to "${options.output}": ` +
546
- `${error instanceof Error ? error.message : String(error)}\n`);
792
+ io.stderr(formatOutputError(options.output, error, "verification"));
547
793
  return 1;
548
794
  }
549
795
  }
@@ -559,4 +805,30 @@ async function runVerify(options, io) {
559
805
  return 1;
560
806
  }
561
807
  }
808
+ function isReportComparison(candidate) {
809
+ if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate))
810
+ return false;
811
+ const record = candidate;
812
+ return ["entered", "left", "moved", "confidenceChanged", "unchanged"]
813
+ .every((key) => Array.isArray(record[key]));
814
+ }
815
+ function describeUnsupportedTaskUrl(issueText) {
816
+ const value = issueText.trim();
817
+ // `tryParse`, not `parse` — this is a boolean probe, and the throwing variant printed a
818
+ // Node stack here for URLs it could not classify instead of this one-line message.
819
+ if (!/^https?:\/\/\S+$/i.test(value) || tryParseGitHubIssueSource(value))
820
+ return undefined;
821
+ return "Unsupported task URL. Use a public GitHub issue or pull request URL such as " +
822
+ "https://github.com/owner/repository/issues/123 or /pull/123, or pass descriptive task text. " +
823
+ "A ?query, #fragment, and a www. or api. host are accepted and normalized; other hosts, credentials and ports are not.";
824
+ }
825
+ function formatOutputError(path, error, kind) {
826
+ const candidate = error;
827
+ const guidance = candidate?.code === "EISDIR"
828
+ ? " The output path must name a file, not a directory."
829
+ : candidate?.code === "ENOENT"
830
+ ? " Create the parent directory first, then retry."
831
+ : "";
832
+ return `Could not write ${kind} to "${path}": ${candidate?.message ?? String(error)}.${guidance}\n`;
833
+ }
562
834
  //# sourceMappingURL=cli-runner.js.map