@aryam/fixmap 0.7.4 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,7 +9,7 @@ FixMap turns an issue, prompt, or git diff into ranked context files, test route
9
9
  Paste a public GitHub issue URL; FixMap fetches its task context and infers the repository:
10
10
 
11
11
  ```bash
12
- npx -y @aryam/fixmap plan --issue https://github.com/aryamthecodebreaker/FixMap/issues/59
12
+ npx -y @aryam/fixmap plan --issue https://github.com/aryamthecodebreaker/FixMap/issues/152
13
13
  ```
14
14
 
15
15
  Or supply your own task and public repository:
@@ -38,9 +38,9 @@ Machine-readable output:
38
38
  npx @aryam/fixmap plan --base main --head HEAD --format json --output fixmap-report.json
39
39
  ```
40
40
 
41
- Public GitHub issue and repository URL modes are available in the CLI and MCP server for issue-only analysis. FixMap fetches issue context anonymously, shallow-clones the default branch into an isolated temporary directory, disables credentials and repository execution surfaces, and removes the checkout before returning. Clone locally to use `--diff`, `--base`, or `--head`.
41
+ Public GitHub issue, pull request, and repository URL modes are available in the CLI and MCP server for issue-only analysis. FixMap fetches task context anonymously, shallow-clones the default branch into an isolated temporary directory, disables credentials and repository execution surfaces, and removes the checkout before returning. Clone locally to use `--diff`, `--base`, `--head`, or working-tree inputs.
42
42
 
43
- For long task text, use `--issue-file task.md`, `--issue @task.md`, or pipe text to `--issue -`. If a stale global installation shadows a pinned npx package on Windows, run `npm uninstall -g @aryam/fixmap` or use `npm exec --yes --package=@aryam/fixmap@0.7.4 -- fixmap ...`.
43
+ For long task text, use `--issue-file task.md`, `--issue @task.md`, or pipe text to `--issue -`. If a stale global installation shadows a pinned npx package on Windows, run `fixmap doctor`, remove the stale install with `npm uninstall -g @aryam/fixmap`, or use `npm exec --yes --package=@aryam/fixmap@0.8.1 -- fixmap ...`.
44
44
 
45
45
  ## MCP server
46
46
 
@@ -98,7 +98,7 @@ fixmap mcp Run FixMap as an MCP server over stdio
98
98
  ## Links
99
99
 
100
100
  - [GitHub repository](https://github.com/aryamthecodebreaker/FixMap)
101
- - [Live demo](https://fixmap-flax.vercel.app)
101
+ - [Live demo](https://usefixmap.vercel.app)
102
102
  - [Changelog](https://github.com/aryamthecodebreaker/FixMap/blob/main/CHANGELOG.md)
103
103
 
104
104
  MIT © FixMap contributors.
@@ -1,4 +1,5 @@
1
1
  import { type FixMapReport } from "@aryam/fixmap-core";
2
+ import { type DoctorReport } from "./doctor.js";
2
3
  import { type RepositoryPlanInput } from "./repository-source.js";
3
4
  export type CliOptions = {
4
5
  command: string;
@@ -12,6 +13,11 @@ export type CliOptions = {
12
13
  output?: string | undefined;
13
14
  explainPath?: string | undefined;
14
15
  reportPath?: string | undefined;
16
+ comparePath?: string | undefined;
17
+ limit?: number | undefined;
18
+ exclude: string[];
19
+ workingTree: boolean;
20
+ includeUntracked: boolean;
15
21
  unknownArgs: string[];
16
22
  invalidValues: string[];
17
23
  };
@@ -19,11 +25,13 @@ export type CliDependencies = {
19
25
  buildReport?: (input: RepositoryPlanInput) => Promise<FixMapReport>;
20
26
  readVersion?: () => string;
21
27
  runMcpServer?: () => Promise<void>;
28
+ runDoctor?: () => Promise<DoctorReport>;
22
29
  stderr?: (text: string) => void;
23
30
  stdout?: (text: string) => void;
24
31
  writeReport?: (path: string, contents: string) => Promise<void>;
25
32
  readIssueFile?: (path: string | number) => string;
26
33
  };
27
- export declare const USAGE = "FixMap maps an issue, prompt, or diff to context files, test routes, and review risks.\n\nUsage:\n fixmap plan --issue \"Users cannot reset passwords\"\n fixmap plan --issue https://github.com/owner/repository/issues/123\n fixmap plan --issue-file task.md\n fixmap plan --issue -\n fixmap plan --issue \"Fix login\" --repo https://github.com/owner/repository\n fixmap plan --diff main...HEAD\n fixmap plan --base main --head HEAD --format json\n fixmap verify --report fixmap-report.json --diff main...HEAD\n fixmap mcp\n\nCommands:\n plan Generate a FixMap report for a task or diff\n verify Compare a saved report against the diff that followed it\n mcp Run FixMap as an MCP server over stdio for AI coding agents\n\nOptions:\n --issue <text|url> Issue text, task description, or public GitHub issue URL\n --issue-file <file> Read task text from a UTF-8 file (use - for stdin)\n --diff <spec> Git diff spec, such as main...HEAD\n --base <ref> Base ref for diffing when --diff is not given\n --head <ref> Head ref for diffing (defaults to HEAD)\n --repo <source> Local path or public GitHub HTTPS URL (defaults to current directory)\n --format <fmt> Output format: markdown (default) or json\n --output <file> Write the report to a file instead of stdout\n --explain <path> Explain why one file was ranked where it was, or left out\n --report <file> Verify command only: the JSON report the change was planned from\n --help, -h Show this help\n --version, -v Show the FixMap version\n";
34
+ export declare const USAGE = "FixMap maps an issue, prompt, or diff to context files, test routes, and review risks.\n\nUsage:\n fixmap plan --issue \"Users cannot reset passwords\"\n fixmap plan --issue https://github.com/owner/repository/issues/123\n fixmap plan --issue https://github.com/owner/repository/pull/123\n fixmap plan --issue-file task.md\n fixmap plan --issue -\n fixmap plan --issue \"Fix login\" --repo https://github.com/owner/repository\n fixmap plan --diff main...HEAD\n fixmap plan --working-tree --include-untracked --limit 12 --exclude \"docs/**\"\n fixmap plan --issue \"Fix login\" --format json --output current.json --compare previous.json\n fixmap plan --base main --head HEAD --format json\n fixmap verify --report fixmap-report.json --diff main...HEAD\n fixmap verify --report fixmap-report.json --working-tree\n fixmap doctor --format json\n fixmap mcp\n\nCommands:\n plan Generate a FixMap report for a task or diff\n verify Compare a saved report against the diff that followed it\n doctor Check the FixMap install for stale global or npx shadows\n mcp Run FixMap as an MCP server over stdio for AI coding agents\n\nOptions:\n --issue <text|url> Task text, or a public GitHub issue or pull request URL\n --issue-file <file> Read task text from a UTF-8 file (use - for stdin)\n --diff <spec> Git diff spec, such as main...HEAD (the repository scan can still rank untracked candidates)\n --base <ref> Base ref for diffing when --diff is not given\n --head <ref> Head ref for diffing (defaults to HEAD)\n --working-tree Map staged and unstaged changes against HEAD\n --include-untracked With --working-tree, also include untracked files\n --repo <source> Local path or public GitHub HTTPS URL (defaults to current directory)\n --limit <n> Maximum context files to report (default 8, max 20)\n --exclude <glob> Path pattern to leave out of ranking (repeatable)\n --format <fmt> Output format: markdown (default) or json\n --output <file> Write the report or verification to a file instead of stdout\n --explain <path> Explain why one file was ranked where it was, or left out\n --compare <file> Compare this plan against an earlier JSON report\n --report <file> Verify command only: the JSON report the change was planned from\n --help, -h Show this help\n --version, -v Show the FixMap version\n\nA repository may also list exclusion patterns in .fixmapignore, one per line. Supported\nsyntax is *, **, ?, root-leading /, directory-trailing /, comments, and ! negation.\nSet FIXMAP_PROGRESS=1 to print scan and clone phases to stderr.\n";
28
35
  export declare function runCli(args: string[], dependencies?: CliDependencies): Promise<number>;
36
+ export declare const MAX_CONTEXT_FILE_LIMIT = 20;
29
37
  export declare function parseArgs(args: string[]): CliOptions;
@@ -2,40 +2,58 @@ import { readFileSync } from "node:fs";
2
2
  import { writeFile } from "node:fs/promises";
3
3
  import { dirname, join } from "node:path";
4
4
  import { fileURLToPath } from "node:url";
5
- import { explainFile, renderJsonReport, renderVerifyMarkdown, verifyPlan, renderMarkdownReport, scanRepo } from "@aryam/fixmap-core";
5
+ import { compareReports, explainFile, renderComparisonMarkdown, renderExplanationMarkdown, renderJsonReport, renderVerifyMarkdown, resolveExclusions, verifyPlan, renderMarkdownReport, scanRepo } from "@aryam/fixmap-core";
6
+ import { runDoctorChecks, renderDoctorReport } from "./doctor.js";
6
7
  import { buildReportForRepository, parseGitHubIssueSource } from "./repository-source.js";
7
8
  export const USAGE = `FixMap maps an issue, prompt, or diff to context files, test routes, and review risks.
8
9
 
9
10
  Usage:
10
11
  fixmap plan --issue "Users cannot reset passwords"
11
12
  fixmap plan --issue https://github.com/owner/repository/issues/123
13
+ fixmap plan --issue https://github.com/owner/repository/pull/123
12
14
  fixmap plan --issue-file task.md
13
15
  fixmap plan --issue -
14
16
  fixmap plan --issue "Fix login" --repo https://github.com/owner/repository
15
17
  fixmap plan --diff main...HEAD
18
+ fixmap plan --working-tree --include-untracked --limit 12 --exclude "docs/**"
19
+ fixmap plan --issue "Fix login" --format json --output current.json --compare previous.json
16
20
  fixmap plan --base main --head HEAD --format json
17
21
  fixmap verify --report fixmap-report.json --diff main...HEAD
22
+ fixmap verify --report fixmap-report.json --working-tree
23
+ fixmap doctor --format json
18
24
  fixmap mcp
19
25
 
20
26
  Commands:
21
27
  plan Generate a FixMap report for a task or diff
22
28
  verify Compare a saved report against the diff that followed it
29
+ doctor Check the FixMap install for stale global or npx shadows
23
30
  mcp Run FixMap as an MCP server over stdio for AI coding agents
24
31
 
25
32
  Options:
26
- --issue <text|url> Issue text, task description, or public GitHub issue URL
33
+ --issue <text|url> Task text, or a public GitHub issue or pull request URL
27
34
  --issue-file <file> Read task text from a UTF-8 file (use - for stdin)
28
- --diff <spec> Git diff spec, such as main...HEAD
35
+ --diff <spec> Git diff spec, such as main...HEAD (the repository scan can still rank untracked candidates)
29
36
  --base <ref> Base ref for diffing when --diff is not given
30
37
  --head <ref> Head ref for diffing (defaults to HEAD)
38
+ --working-tree Map staged and unstaged changes against HEAD
39
+ --include-untracked With --working-tree, also include untracked files
31
40
  --repo <source> Local path or public GitHub HTTPS URL (defaults to current directory)
41
+ --limit <n> Maximum context files to report (default 8, max 20)
42
+ --exclude <glob> Path pattern to leave out of ranking (repeatable)
32
43
  --format <fmt> Output format: markdown (default) or json
33
- --output <file> Write the report to a file instead of stdout
44
+ --output <file> Write the report or verification to a file instead of stdout
34
45
  --explain <path> Explain why one file was ranked where it was, or left out
46
+ --compare <file> Compare this plan against an earlier JSON report
35
47
  --report <file> Verify command only: the JSON report the change was planned from
36
48
  --help, -h Show this help
37
49
  --version, -v Show the FixMap version
50
+
51
+ A repository may also list exclusion patterns in .fixmapignore, one per line. Supported
52
+ syntax is *, **, ?, root-leading /, directory-trailing /, comments, and ! negation.
53
+ Set FIXMAP_PROGRESS=1 to print scan and clone phases to stderr.
38
54
  `;
55
+ const DOCTOR_USAGE = `Usage: fixmap doctor [--format markdown|json]\n\nChecks the running FixMap binary, PATH/global shadows, and known install blind spots.\n`;
56
+ const MCP_USAGE = `Usage: fixmap mcp\n\nRuns the FixMap MCP server over stdio. Configure your MCP client to execute \"fixmap mcp\".\n`;
39
57
  export async function runCli(args, dependencies = {}) {
40
58
  const stdout = dependencies.stdout ?? ((text) => process.stdout.write(text));
41
59
  const stderr = dependencies.stderr ?? ((text) => process.stderr.write(text));
@@ -43,15 +61,23 @@ export async function runCli(args, dependencies = {}) {
43
61
  stdout(USAGE);
44
62
  return 1;
45
63
  }
46
- if (args[0] === "help" || args.includes("--help") || args.includes("-h")) {
64
+ if (args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
47
65
  stdout(USAGE);
48
66
  return 0;
49
67
  }
50
- if (args[0] === "version" || args.includes("--version") || args.includes("-v")) {
68
+ if (args[0] === "version" || args[0] === "--version" || args[0] === "-v") {
51
69
  stdout(`${(dependencies.readVersion ?? readVersion)()}\n`);
52
70
  return 0;
53
71
  }
54
72
  if (args[0] === "mcp") {
73
+ if (args[1] === "--help" || args[1] === "-h") {
74
+ stdout(MCP_USAGE);
75
+ return 0;
76
+ }
77
+ if (args.length > 1) {
78
+ stderr(`mcp takes no options.\n\n${MCP_USAGE}`);
79
+ return 1;
80
+ }
55
81
  const runMcpServer = dependencies.runMcpServer ?? (async () => {
56
82
  const module = await import("./mcp.js");
57
83
  await module.runMcpServer();
@@ -59,7 +85,35 @@ export async function runCli(args, dependencies = {}) {
59
85
  await runMcpServer();
60
86
  return 0;
61
87
  }
88
+ if (args[0] === "doctor") {
89
+ if (args[1] === "--help" || args[1] === "-h") {
90
+ stdout(DOCTOR_USAGE);
91
+ return 0;
92
+ }
93
+ const doctorArgs = args.slice(1);
94
+ let doctorFormat = "markdown";
95
+ if (doctorArgs.length > 0) {
96
+ const match = doctorArgs.length === 2 && doctorArgs[0] === "--format" ? doctorArgs[1] :
97
+ doctorArgs.length === 1 ? doctorArgs[0]?.match(/^--format=(.+)$/)?.[1] : undefined;
98
+ const normalized = match?.toLowerCase();
99
+ if (normalized === "markdown" || normalized === "json")
100
+ doctorFormat = normalized;
101
+ else {
102
+ stderr(`Unknown doctor option(s): ${doctorArgs.join(", ")}\n\n${DOCTOR_USAGE}`);
103
+ return 1;
104
+ }
105
+ }
106
+ const report = await (dependencies.runDoctor ?? runDoctorChecks)();
107
+ stdout(doctorFormat === "json" ? `${JSON.stringify(report, null, 2)}\n` : renderDoctorReport(report));
108
+ // Non-zero on a detected shadow: a script that runs doctor in CI should fail there,
109
+ // not read the text and carry on.
110
+ return report.healthy ? 0 : 1;
111
+ }
62
112
  const options = parseArgs(args);
113
+ if (options.command.startsWith("-")) {
114
+ stderr(`FixMap needs a subcommand. Try: fixmap plan ${args.join(" ")}\n\n${USAGE}`);
115
+ return 1;
116
+ }
63
117
  if (options.command !== "plan" && options.command !== "verify") {
64
118
  stderr(`Unknown command: ${options.command || "(none)"}\n\n${USAGE}`);
65
119
  return 1;
@@ -77,7 +131,16 @@ export async function runCli(args, dependencies = {}) {
77
131
  return 1;
78
132
  }
79
133
  if (options.command === "verify") {
80
- return runVerify(options, { stdout, stderr });
134
+ 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);
135
+ if (planOnly.length > 0) {
136
+ stderr(`verify does not accept plan-only option(s): ${planOnly.join(", ")}.\n`);
137
+ return 1;
138
+ }
139
+ return runVerify(options, {
140
+ stdout,
141
+ stderr,
142
+ writeReport: dependencies.writeReport ?? ((path, contents) => writeFile(path, contents, "utf8"))
143
+ });
81
144
  }
82
145
  try {
83
146
  options.issueText = loadIssueText(options, dependencies.readIssueFile ?? defaultReadIssueFile);
@@ -86,8 +149,37 @@ export async function runCli(args, dependencies = {}) {
86
149
  stderr(`${error instanceof Error ? error.message : String(error)}\n`);
87
150
  return 1;
88
151
  }
89
- if (!options.issueText && !options.diffSpec && !options.baseRef) {
90
- stderr("Provide --issue, --diff, or --base/--head so FixMap has a task signal.\n");
152
+ if (!options.issueText && !options.diffSpec && !options.baseRef && !options.workingTree) {
153
+ stderr("Provide --issue, --diff, --base/--head, or --working-tree so FixMap has a task signal.\n");
154
+ return 1;
155
+ }
156
+ if (options.includeUntracked && !options.workingTree) {
157
+ stderr("--include-untracked only applies with --working-tree.\n");
158
+ return 1;
159
+ }
160
+ if (options.workingTree && (options.diffSpec || options.baseRef)) {
161
+ stderr("Use either --working-tree or --diff/--base, not both: they name different sets of changes.\n");
162
+ return 1;
163
+ }
164
+ if (options.diffSpec && (options.baseRef || options.headRef)) {
165
+ stderr("Use either --diff or --base/--head, not both.\n");
166
+ return 1;
167
+ }
168
+ if (options.headRef && !options.baseRef) {
169
+ stderr("--head requires --base; use --diff when you already have a complete range.\n");
170
+ return 1;
171
+ }
172
+ if (options.explainPath && options.comparePath) {
173
+ stderr("Use either --explain or --compare, not both.\n");
174
+ return 1;
175
+ }
176
+ if (/^https?:\/\//i.test(options.repo ?? "") && (options.workingTree || options.includeUntracked)) {
177
+ stderr("--working-tree and --include-untracked need a local checkout; remote URL checkouts are always clean.\n");
178
+ return 1;
179
+ }
180
+ const unsupportedTaskUrl = describeUnsupportedTaskUrl(options.issueText);
181
+ if (unsupportedTaskUrl) {
182
+ stderr(`${unsupportedTaskUrl}\n`);
91
183
  return 1;
92
184
  }
93
185
  if (options.explainPath) {
@@ -99,11 +191,19 @@ export async function runCli(args, dependencies = {}) {
99
191
  return 1;
100
192
  }
101
193
  try {
102
- const repo = await scanRepo({ repoRoot: options.repo ?? process.cwd() });
103
- const explanation = explainFile(repo, { issueText: options.issueText }, options.explainPath);
194
+ const repoRoot = options.repo ?? process.cwd();
195
+ const repo = await scanRepo({ repoRoot, diffSpec: options.diffSpec, baseRef: options.baseRef, headRef: options.headRef, workingTree: options.workingTree, includeUntracked: options.includeUntracked });
196
+ const explanation = explainFile(repo, {
197
+ issueText: options.issueText,
198
+ // Without this, a file left out by .fixmapignore would be reported as having
199
+ // scored below the cutoff — a false answer to the exact question --explain exists
200
+ // to answer.
201
+ exclude: await resolveExclusions(repoRoot, options.exclude),
202
+ limit: options.limit
203
+ }, options.explainPath);
104
204
  stdout(options.format === "json"
105
205
  ? `${JSON.stringify(explanation, null, 2)}\n`
106
- : renderExplanation(explanation));
206
+ : renderExplanationMarkdown(explanation));
107
207
  return 0;
108
208
  }
109
209
  catch (error) {
@@ -118,7 +218,11 @@ export async function runCli(args, dependencies = {}) {
118
218
  issueText: options.issueText,
119
219
  diffSpec: options.diffSpec,
120
220
  baseRef: options.baseRef,
121
- headRef: options.headRef
221
+ headRef: options.headRef,
222
+ workingTree: options.workingTree,
223
+ includeUntracked: options.includeUntracked,
224
+ limit: options.limit,
225
+ exclude: options.exclude
122
226
  });
123
227
  }
124
228
  catch (error) {
@@ -133,18 +237,70 @@ export async function runCli(args, dependencies = {}) {
133
237
  return 1;
134
238
  }
135
239
  if (report.changedFiles.length === 0) {
136
- stderr("The requested diff resolved to zero changed files and no --issue text was provided. " +
137
- "Choose a non-empty diff or add --issue.\n");
240
+ stderr((options.workingTree
241
+ ? "The working tree has zero selected changes and no --issue text was provided. Make a tracked change, add --include-untracked, or add --issue.\n"
242
+ : "The requested diff resolved to zero changed files and no --issue text was provided. Choose a non-empty diff or add --issue.\n"));
138
243
  return 1;
139
244
  }
140
245
  }
246
+ // The habit worth having: plan, add the identifier the task was missing, re-plan, and
247
+ // check whether the real file rose. When comparing, the delta is the answer — the full
248
+ // report is what the reader already has from the previous run.
249
+ if (options.comparePath) {
250
+ let previous;
251
+ let previousText;
252
+ try {
253
+ previousText = readFileSync(options.comparePath, "utf8");
254
+ }
255
+ catch (error) {
256
+ stderr(`Could not read comparison file "${options.comparePath}": ${error instanceof Error ? error.message : String(error)}\n` +
257
+ "Save one first with: fixmap plan --issue \"...\" --format json --output previous.json\n");
258
+ return 1;
259
+ }
260
+ if (!previousText.trim()) {
261
+ stderr(`Comparison file "${options.comparePath}" is empty. Save a JSON plan with --format json first.\n`);
262
+ return 1;
263
+ }
264
+ if (/^\s*#\s*FixMap/i.test(previousText)) {
265
+ stderr(`"${options.comparePath}" is a Markdown report. --compare requires the JSON plan saved with --format json.\n`);
266
+ return 1;
267
+ }
268
+ try {
269
+ previous = JSON.parse(previousText);
270
+ }
271
+ catch (error) {
272
+ stderr(`"${options.comparePath}" is not valid JSON: ${error instanceof Error ? error.message : String(error)}\n`);
273
+ return 1;
274
+ }
275
+ if (!Array.isArray(previous.contextFiles)) {
276
+ stderr(`"${options.comparePath}" is valid JSON but not a FixMap report: no contextFiles array.\n`);
277
+ return 1;
278
+ }
279
+ const comparison = compareReports(previous, report);
280
+ const renderedComparison = options.format === "json"
281
+ ? `${JSON.stringify(comparison, null, 2)}\n`
282
+ : renderComparisonMarkdown(comparison);
283
+ if (options.output) {
284
+ try {
285
+ await (dependencies.writeReport ?? ((path, contents) => writeFile(path, contents, "utf8")))(options.output, renderedComparison);
286
+ }
287
+ catch (error) {
288
+ stderr(formatOutputError(options.output, error, "comparison"));
289
+ return 1;
290
+ }
291
+ }
292
+ else
293
+ stdout(renderedComparison);
294
+ stderr("\nComparison complete. Refine the task or inspect the files that entered, moved, or changed confidence, then rerun the plan.\n");
295
+ return 0;
296
+ }
141
297
  const rendered = options.format === "json" ? renderJsonReport(report) : renderMarkdownReport(report);
142
298
  if (options.output) {
143
299
  try {
144
300
  await (dependencies.writeReport ?? ((path, contents) => writeFile(path, contents, "utf8")))(options.output, rendered);
145
301
  }
146
302
  catch (error) {
147
- stderr(`Could not write report to "${options.output}": ${error instanceof Error ? error.message : String(error)}\n`);
303
+ stderr(formatOutputError(options.output, error, "report"));
148
304
  return 1;
149
305
  }
150
306
  }
@@ -176,8 +332,6 @@ function nextCommandHint(options, report) {
176
332
  if (options.output && options.format === "json") {
177
333
  const remoteIssue = options.issueText ? parseGitHubIssueSource(options.issueText) : undefined;
178
334
  const remoteRepo = /^https?:\/\//i.test(options.repo ?? "") || (remoteIssue && !options.repo);
179
- const diff = options.diffSpec ??
180
- (options.baseRef ? `${options.baseRef}...${options.headRef ?? "HEAD"}` : "<base>...HEAD");
181
335
  const repo = remoteRepo
182
336
  ? " --repo <local-checkout>"
183
337
  : options.repo
@@ -186,10 +340,38 @@ function nextCommandHint(options, report) {
186
340
  const prefix = remoteRepo
187
341
  ? "\nAfter you clone and edit the scanned repository, check it against this plan:\n"
188
342
  : "\nAfter you make the change, check it against this plan:\n";
189
- return `${prefix} fixmap verify --report ${quoteCliValue(options.output)} --diff ${diff}${repo}\n`;
343
+ const command = ` fixmap verify --report ${quoteCliValue(options.output)}`;
344
+ // An issue-only plan has no base to name. Inventing one was #110; printing the
345
+ // placeholder `<base>...HEAD` inside a copy-paste command replaced that with a line
346
+ // that looks runnable and is not. Keep the command runnable-as-printed and put the
347
+ // part the user must supply on its own line, outside it.
348
+ const diff = options.diffSpec ??
349
+ (options.baseRef ? `${options.baseRef}...${options.headRef ?? "HEAD"}` : undefined);
350
+ if (!diff) {
351
+ return `${prefix}${command}${repo}\n` +
352
+ "Add --diff with the range holding your edit, such as HEAD~1...HEAD.\n";
353
+ }
354
+ return `${prefix}${command} --diff ${diff}${repo}\n`;
190
355
  }
191
356
  return undefined;
192
357
  }
358
+ // --exclude is deliberately absent: it is the one flag that accumulates, because naming
359
+ // several directories to leave out is the normal way to use it.
360
+ const SINGLE_VALUE_FLAGS = new Set([
361
+ "--issue",
362
+ "--issue-file",
363
+ "--diff",
364
+ "--base",
365
+ "--head",
366
+ "--repo",
367
+ "--format",
368
+ "--report",
369
+ "--explain",
370
+ "--compare",
371
+ "--limit",
372
+ "--output"
373
+ ]);
374
+ export const MAX_CONTEXT_FILE_LIMIT = 20;
193
375
  export function parseArgs(args) {
194
376
  const command = args[0] ?? "";
195
377
  let issueText = "";
@@ -202,9 +384,14 @@ export function parseArgs(args) {
202
384
  let output;
203
385
  let explainPath;
204
386
  let reportPath;
387
+ let comparePath;
388
+ let limit;
389
+ let workingTree = false;
390
+ let includeUntracked = false;
391
+ const exclude = [];
205
392
  const unknownArgs = [];
206
393
  const invalidValues = [];
207
- let issueCount = 0;
394
+ const flagCounts = new Map();
208
395
  for (let index = 1; index < args.length; index += 1) {
209
396
  const rawArg = args[index];
210
397
  if (!rawArg) {
@@ -217,6 +404,7 @@ export function parseArgs(args) {
217
404
  const canConsumeFollowing = inlineValue === undefined &&
218
405
  followingValue !== undefined &&
219
406
  (!followingValue.startsWith("-") ||
407
+ (arg === "--limit" && /^-\d/.test(followingValue)) ||
220
408
  ((arg === "--issue" || arg === "--issue-file") && followingValue === "-"));
221
409
  const value = inlineValue ?? (canConsumeFollowing ? followingValue : undefined);
222
410
  const consumeValue = () => {
@@ -224,21 +412,29 @@ export function parseArgs(args) {
224
412
  index += 1;
225
413
  }
226
414
  };
415
+ // Every one of these takes a single value, so a repeat is a mistake rather than a
416
+ // refinement. Silently keeping the last one is worst for --repo, which then scans a
417
+ // different tree than the one the user named first, and --format, which hands the
418
+ // consumer a contract it did not ask for.
419
+ if (SINGLE_VALUE_FLAGS.has(arg)) {
420
+ const occurrence = (flagCounts.get(arg) ?? 0) + 1;
421
+ flagCounts.set(arg, occurrence);
422
+ if (occurrence > 1) {
423
+ consumeValue();
424
+ invalidValues.push(`pass only one ${arg} value`);
425
+ continue;
426
+ }
427
+ }
227
428
  if (arg === "--issue") {
228
429
  consumeValue();
229
- issueCount += 1;
230
- if (issueCount > 1)
231
- invalidValues.push("pass only one --issue value");
232
- else if (value?.trim())
430
+ if (value?.trim())
233
431
  issueText = value;
234
432
  else
235
433
  invalidValues.push('--issue requires non-empty text or a GitHub issue URL');
236
434
  }
237
435
  else if (arg === "--issue-file") {
238
436
  consumeValue();
239
- if (issueFile !== undefined)
240
- invalidValues.push("pass only one --issue-file value");
241
- else if (value?.trim())
437
+ if (value?.trim())
242
438
  issueFile = value.trim();
243
439
  else
244
440
  invalidValues.push("--issue-file requires a UTF-8 file path or - for stdin");
@@ -273,8 +469,9 @@ export function parseArgs(args) {
273
469
  }
274
470
  else if (arg === "--format") {
275
471
  consumeValue();
276
- if (value === "markdown" || value === "json") {
277
- format = value;
472
+ const normalized = value?.toLowerCase();
473
+ if (normalized === "markdown" || normalized === "json") {
474
+ format = normalized;
278
475
  }
279
476
  else {
280
477
  invalidValues.push(`--format received ${JSON.stringify(value ?? "(missing)")}; expected "markdown" or "json"`);
@@ -294,6 +491,42 @@ export function parseArgs(args) {
294
491
  else
295
492
  invalidValues.push("--explain requires a repository-relative file path");
296
493
  }
494
+ else if (arg === "--compare") {
495
+ consumeValue();
496
+ if (value?.trim())
497
+ comparePath = value.trim();
498
+ else
499
+ invalidValues.push("--compare requires a path to an earlier FixMap JSON report");
500
+ }
501
+ else if (arg === "--exclude") {
502
+ consumeValue();
503
+ if (value?.trim())
504
+ exclude.push(value.trim());
505
+ else
506
+ invalidValues.push("--exclude requires a path or glob pattern");
507
+ }
508
+ else if (arg === "--limit") {
509
+ consumeValue();
510
+ const parsed = Number(value);
511
+ if (value?.trim() && Number.isSafeInteger(parsed) && parsed >= 1 && parsed <= MAX_CONTEXT_FILE_LIMIT) {
512
+ limit = parsed;
513
+ }
514
+ else {
515
+ invalidValues.push(`--limit received ${JSON.stringify(value ?? "(missing)")}; expected a whole number from 1 to ${MAX_CONTEXT_FILE_LIMIT}`);
516
+ }
517
+ }
518
+ else if (arg === "--working-tree") {
519
+ if (flagCounts.has(arg))
520
+ invalidValues.push(`pass ${arg} only once`);
521
+ flagCounts.set(arg, 1);
522
+ workingTree = true;
523
+ }
524
+ else if (arg === "--include-untracked") {
525
+ if (flagCounts.has(arg))
526
+ invalidValues.push(`pass ${arg} only once`);
527
+ flagCounts.set(arg, 1);
528
+ includeUntracked = true;
529
+ }
297
530
  else if (arg === "--output") {
298
531
  consumeValue();
299
532
  if (value?.trim())
@@ -317,6 +550,11 @@ export function parseArgs(args) {
317
550
  output,
318
551
  explainPath,
319
552
  reportPath,
553
+ comparePath,
554
+ limit,
555
+ exclude,
556
+ workingTree,
557
+ includeUntracked,
320
558
  unknownArgs,
321
559
  invalidValues
322
560
  };
@@ -359,12 +597,28 @@ function readVersion() {
359
597
  * user already has, so nothing is executed and no repository code runs.
360
598
  */
361
599
  async function runVerify(options, io) {
600
+ if (options.includeUntracked && !options.workingTree) {
601
+ io.stderr("--include-untracked only applies with --working-tree.\n");
602
+ return 1;
603
+ }
604
+ if (options.workingTree && (options.diffSpec || options.baseRef || options.headRef)) {
605
+ io.stderr("Use either --working-tree or --diff/--base, not both.\n");
606
+ return 1;
607
+ }
608
+ if (options.diffSpec && (options.baseRef || options.headRef)) {
609
+ io.stderr("Use either --diff or --base/--head, not both.\n");
610
+ return 1;
611
+ }
612
+ if (options.headRef && !options.baseRef) {
613
+ io.stderr("--head requires --base; use --diff when you already have a complete range.\n");
614
+ return 1;
615
+ }
362
616
  if (!options.reportPath) {
363
617
  io.stderr("Provide --report with the JSON report this change was planned from.\n");
364
618
  return 1;
365
619
  }
366
- if (!options.diffSpec && !options.baseRef) {
367
- io.stderr("Provide --diff or --base/--head so FixMap can see what changed.\n");
620
+ if (!options.diffSpec && !options.baseRef && !options.workingTree) {
621
+ io.stderr("Provide --diff, --base/--head, or --working-tree so FixMap can see what changed.\n");
368
622
  return 1;
369
623
  }
370
624
  if (/^https?:\/\//i.test(options.repo ?? "")) {
@@ -389,7 +643,9 @@ async function runVerify(options, io) {
389
643
  repoRoot: options.repo ?? process.cwd(),
390
644
  diffSpec: options.diffSpec,
391
645
  baseRef: options.baseRef,
392
- headRef: options.headRef
646
+ headRef: options.headRef,
647
+ workingTree: options.workingTree,
648
+ includeUntracked: options.includeUntracked
393
649
  });
394
650
  const unresolvedDiff = repo.diagnostics.find((diagnostic) => diagnostic.code === "diff-unavailable");
395
651
  if (unresolvedDiff) {
@@ -397,9 +653,21 @@ async function runVerify(options, io) {
397
653
  return 1;
398
654
  }
399
655
  const result = verifyPlan(report, repo);
400
- io.stdout(options.format === "json"
656
+ const rendered = options.format === "json"
401
657
  ? `${JSON.stringify(result, null, 2)}\n`
402
- : renderVerifyMarkdown(result));
658
+ : renderVerifyMarkdown(result);
659
+ if (options.output) {
660
+ try {
661
+ await io.writeReport(options.output, rendered);
662
+ }
663
+ catch (error) {
664
+ io.stderr(formatOutputError(options.output, error, "verification"));
665
+ return 1;
666
+ }
667
+ }
668
+ else {
669
+ io.stdout(rendered);
670
+ }
403
671
  // A generated-location edit is discarded by the next build, so it fails the command
404
672
  // rather than being reported and ignored. Everything else is advisory.
405
673
  return result.findings.some((finding) => finding.severity === "error") ? 1 : 0;
@@ -409,15 +677,19 @@ async function runVerify(options, io) {
409
677
  return 1;
410
678
  }
411
679
  }
412
- /** Renders one file's explanation. The summary carries the answer; reasons show the working. */
413
- function renderExplanation(explanation) {
414
- const lines = [`# Why ${explanation.path}`, "", explanation.summary];
415
- if (explanation.reasons.length > 0) {
416
- lines.push("", "## Signals", "");
417
- for (const reason of explanation.reasons) {
418
- lines.push(`- ${reason}`);
419
- }
420
- }
421
- return `${lines.join("\n")}\n`;
680
+ function describeUnsupportedTaskUrl(issueText) {
681
+ const value = issueText.trim();
682
+ if (!/^https?:\/\/\S+$/i.test(value) || parseGitHubIssueSource(value))
683
+ return undefined;
684
+ return "Unsupported task URL. Use a canonical public GitHub issue or pull request URL such as https://github.com/owner/repository/issues/123 or /pull/123, or pass descriptive task text.";
685
+ }
686
+ function formatOutputError(path, error, kind) {
687
+ const candidate = error;
688
+ const guidance = candidate?.code === "EISDIR"
689
+ ? " The output path must name a file, not a directory."
690
+ : candidate?.code === "ENOENT"
691
+ ? " Create the parent directory first, then retry."
692
+ : "";
693
+ return `Could not write ${kind} to "${path}": ${candidate?.message ?? String(error)}.${guidance}\n`;
422
694
  }
423
695
  //# sourceMappingURL=cli-runner.js.map