@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.
- package/README.md +14 -7
- package/dist/cli-runner.d.ts +3 -2
- package/dist/cli-runner.js +309 -37
- package/dist/cli-runner.js.map +1 -1
- package/dist/cli.js +17 -1
- package/dist/cli.js.map +1 -1
- package/dist/mcp.d.ts +9 -0
- package/dist/mcp.js +197 -47
- package/dist/mcp.js.map +1 -1
- package/dist/repository-source.d.ts +14 -0
- package/dist/repository-source.js +98 -18
- package/dist/repository-source.js.map +1 -1
- package/package.json +3 -3
package/dist/cli-runner.js
CHANGED
|
@@ -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>
|
|
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
|
|
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
|
|
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)"}
|
|
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(
|
|
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
|
-
|
|
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(
|
|
177
|
-
"
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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(
|
|
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
|
-
|
|
379
|
-
|
|
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
|
|
657
|
+
let raw;
|
|
472
658
|
try {
|
|
473
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
734
|
+
let reportText;
|
|
512
735
|
try {
|
|
513
|
-
|
|
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(
|
|
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
|