@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 +4 -4
- package/dist/cli-runner.d.ts +9 -1
- package/dist/cli-runner.js +316 -44
- package/dist/cli-runner.js.map +1 -1
- package/dist/doctor.d.ts +19 -0
- package/dist/doctor.js +103 -0
- package/dist/doctor.js.map +1 -0
- package/dist/mcp.d.ts +23 -0
- package/dist/mcp.js +341 -31
- package/dist/mcp.js.map +1 -1
- package/dist/repository-source.d.ts +15 -0
- package/dist/repository-source.js +52 -19
- package/dist/repository-source.js.map +1 -1
- package/package.json +3 -3
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/
|
|
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
|
|
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
|
|
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://
|
|
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.
|
package/dist/cli-runner.d.ts
CHANGED
|
@@ -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>
|
|
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;
|
package/dist/cli-runner.js
CHANGED
|
@@ -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>
|
|
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
|
|
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
|
|
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
|
-
|
|
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,
|
|
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
|
|
103
|
-
const
|
|
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
|
-
:
|
|
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(
|
|
137
|
-
"
|
|
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(
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 (
|
|
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
|
-
|
|
277
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
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
|