@aryam/fixmap-core 0.8.8 → 0.8.9

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.
Files changed (59) hide show
  1. package/README.md +5 -1
  2. package/dist/browser.d.ts +5 -1
  3. package/dist/browser.js +3 -1
  4. package/dist/browser.js.map +1 -1
  5. package/dist/cli-quote.d.ts +3 -0
  6. package/dist/cli-quote.js +9 -0
  7. package/dist/cli-quote.js.map +1 -0
  8. package/dist/compare.js +45 -12
  9. package/dist/compare.js.map +1 -1
  10. package/dist/exclude.d.ts +2 -0
  11. package/dist/exclude.js +8 -3
  12. package/dist/exclude.js.map +1 -1
  13. package/dist/explain.js +16 -17
  14. package/dist/explain.js.map +1 -1
  15. package/dist/grounding.d.ts +3 -1
  16. package/dist/grounding.js +21 -17
  17. package/dist/grounding.js.map +1 -1
  18. package/dist/import-graph.d.ts +2 -0
  19. package/dist/import-graph.js +84 -10
  20. package/dist/import-graph.js.map +1 -1
  21. package/dist/index.d.ts +4 -1
  22. package/dist/index.js +3 -1
  23. package/dist/index.js.map +1 -1
  24. package/dist/languages.d.ts +1 -1
  25. package/dist/languages.js +60 -12
  26. package/dist/languages.js.map +1 -1
  27. package/dist/markdown.d.ts +2 -0
  28. package/dist/markdown.js +8 -0
  29. package/dist/markdown.js.map +1 -0
  30. package/dist/paths.d.ts +8 -0
  31. package/dist/paths.js +38 -8
  32. package/dist/paths.js.map +1 -1
  33. package/dist/plan.d.ts +2 -0
  34. package/dist/plan.js +58 -14
  35. package/dist/plan.js.map +1 -1
  36. package/dist/rank.d.ts +9 -0
  37. package/dist/rank.js +167 -89
  38. package/dist/rank.js.map +1 -1
  39. package/dist/repo-scan.d.ts +3 -1
  40. package/dist/repo-scan.js +386 -104
  41. package/dist/repo-scan.js.map +1 -1
  42. package/dist/report.d.ts +6 -0
  43. package/dist/report.js +40 -51
  44. package/dist/report.js.map +1 -1
  45. package/dist/signals.d.ts +5 -0
  46. package/dist/signals.js +130 -38
  47. package/dist/signals.js.map +1 -1
  48. package/dist/test-gates.js +15 -3
  49. package/dist/test-gates.js.map +1 -1
  50. package/dist/text.d.ts +2 -0
  51. package/dist/text.js +4 -0
  52. package/dist/text.js.map +1 -1
  53. package/dist/types.d.ts +2 -2
  54. package/dist/validate.d.ts +1 -1
  55. package/dist/validate.js +148 -16
  56. package/dist/validate.js.map +1 -1
  57. package/dist/verify.js +25 -3
  58. package/dist/verify.js.map +1 -1
  59. package/package.json +1 -1
package/dist/repo-scan.js CHANGED
@@ -1,35 +1,25 @@
1
1
  import { execFile } from "node:child_process";
2
- import { createHash } from "node:crypto";
3
- import { mkdir, readdir, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";
2
+ import { createHash, randomUUID } from "node:crypto";
3
+ import { mkdir, readdir, readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
4
4
  import { homedir } from "node:os";
5
- import { dirname, extname, join, relative, resolve, sep } from "node:path";
5
+ import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
6
6
  import { promisify } from "node:util";
7
- import { ALWAYS_IGNORED_DIRS, GENERATED_DIRS, isGeneratedPath } from "./paths.js";
7
+ import { ALWAYS_IGNORED_DIRS, GENERATED_DIRS, SOURCE_FILE_EXTENSIONS, isGeneratedPath } from "./paths.js";
8
8
  import { DIAGNOSTIC_SPEC_LIMIT, truncateForDiagnostic } from "./text.js";
9
- const WALK_IGNORED_DIRS = new Set([...ALWAYS_IGNORED_DIRS, ...GENERATED_DIRS]);
10
- const SOURCE_EXTENSIONS = new Set([
11
- ".cjs",
12
- ".cs",
13
- ".css",
14
- ".cts",
15
- ".go",
16
- ".java",
17
- ".js",
18
- ".json",
19
- ".jsx",
20
- ".md",
21
- ".mjs",
22
- ".mts",
23
- ".php",
24
- ".py",
25
- ".rb",
26
- ".rs",
27
- ".svelte",
28
- ".ts",
29
- ".tsx",
30
- ".vue",
31
- ".yaml",
32
- ".yml"
9
+ // Vendored source is intentionally scannable and receives a ranking penalty. Git mode has
10
+ // always kept tracked vendor/ files; walk mode must not silently use a smaller corpus.
11
+ const WALK_IGNORED_DIRS = new Set([
12
+ ...ALWAYS_IGNORED_DIRS,
13
+ ...[...GENERATED_DIRS].filter((directory) => directory !== "vendor")
14
+ ]);
15
+ const SOURCE_EXTENSIONS = SOURCE_FILE_EXTENSIONS;
16
+ const CONVENTIONAL_DOCUMENT_NAMES = new Set([
17
+ "authors", "changelog", "code_of_conduct", "contributing", "license", "notice", "readme", "security"
18
+ ]);
19
+ const CONVENTIONAL_CONFIG_NAMES = new Set([
20
+ ".dockerignore", ".editorconfig", ".gitattributes", ".gitignore", ".npmignore",
21
+ "codeowners", "dockerfile", "gemfile", "jenkinsfile", "makefile", "procfile", "rakefile", "vagrantfile",
22
+ "pom.xml", "build.gradle", "settings.gradle"
33
23
  ]);
34
24
  /**
35
25
  * A single-file component is mostly template and style. Sampling the whole file let markup
@@ -43,6 +33,9 @@ const TEST_PATTERNS = [
43
33
  /\.spec\./,
44
34
  /(^|\/|\\)__tests__(\/|\\)/,
45
35
  /(^|\/|\\)tests?(\/|\\)/,
36
+ /(^|\/|\\)spec(\/|\\)/,
37
+ /_spec\.rb$/i,
38
+ /(?:Test\.java|Tests?\.cs|Test\.php)$/i,
46
39
  /_test\.go$/,
47
40
  /(^|\/|\\)(?:test_[^/\\]+|[^/\\]+_test)\.py$/
48
41
  ];
@@ -51,7 +44,11 @@ const MAX_DIFF_TEXT_CHARS = 200_000;
51
44
  const MAX_SCANNED_FILES = 25_000;
52
45
  const GIT_MAX_BUFFER = 10 * 1024 * 1024;
53
46
  const exec = promisify(execFile);
54
- const SCAN_CACHE_VERSION = 1;
47
+ const SCAN_CACHE_VERSION = 3;
48
+ const SCAN_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
49
+ const SCAN_CACHE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
50
+ const SCAN_CACHE_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json$/;
51
+ const SCAN_CACHE_TEMP_FILE = /^[a-f0-9]{24}-[a-f0-9]{24}\.json\.\d+-[0-9a-f-]+\.tmp$/i;
55
52
  export async function scanRepo(input) {
56
53
  const repoRoot = resolve(input.repoRoot);
57
54
  if (!(await isDirectory(repoRoot))) {
@@ -70,7 +67,29 @@ export async function scanRepo(input) {
70
67
  };
71
68
  }
72
69
  const diagnostics = [];
73
- const cacheLocation = input.useCache ? await buildScanCacheLocation(repoRoot) : undefined;
70
+ const internalPaths = await resolveInternalPaths(repoRoot, input.internalExclude ?? []);
71
+ const cacheRoot = configuredScanCacheRoot();
72
+ const internalCacheRoot = sameFilesystemPath(cacheRoot, repoRoot) || containedPath(repoRoot, cacheRoot) !== undefined
73
+ ? cacheRoot
74
+ : undefined;
75
+ const cacheDecision = input.useCache === true
76
+ ? await buildScanCacheLocation(repoRoot, cacheRoot, internalPaths)
77
+ : undefined;
78
+ const cacheLocation = cacheDecision?.location;
79
+ if (input.useCache === false) {
80
+ diagnostics.push({
81
+ code: "cache-bypass",
82
+ severity: "info",
83
+ message: "Repository scan caching was bypassed by --no-cache; this report used a fresh scan."
84
+ });
85
+ }
86
+ else if (input.useCache === true && cacheDecision?.skipReason) {
87
+ diagnostics.push({
88
+ code: "cache-skip",
89
+ severity: "info",
90
+ message: cacheDecision.skipReason
91
+ });
92
+ }
74
93
  const cached = cacheLocation ? await readScanCache(cacheLocation) : undefined;
75
94
  let files;
76
95
  let trackedFiles;
@@ -84,18 +103,19 @@ export async function scanRepo(input) {
84
103
  diagnostics.push(...cached.diagnostics, {
85
104
  code: "cache-hit",
86
105
  severity: "info",
87
- message: `Reused the repository scan for the exact current git state (${files.length.toLocaleString()} files). Pass --no-cache to rescan.`
106
+ message: `Reused the repository scan for the exact current git state (${files.length.toLocaleString()} files, ${describeCacheAge(cached.createdAt)}). Pass --no-cache to rescan.`
88
107
  });
89
108
  }
90
109
  else {
91
- files = await listFiles(repoRoot, diagnostics);
92
- trackedFiles = await listTrackedPaths(repoRoot);
110
+ files = await listFiles(repoRoot, diagnostics, internalCacheRoot, internalPaths);
111
+ trackedFiles = await listTrackedPaths(repoRoot, internalPaths);
93
112
  packageScripts = await readPackageScripts(repoRoot, files, diagnostics);
94
- packageManager = detectPackageManager(files);
113
+ packageManager = detectPackageManager(files, diagnostics);
95
114
  if (cacheLocation) {
96
115
  await writeScanCache(cacheLocation, {
97
116
  version: SCAN_CACHE_VERSION,
98
117
  stateKey: cacheLocation.stateKey,
118
+ createdAt: new Date().toISOString(),
99
119
  files,
100
120
  trackedFiles,
101
121
  packageScripts,
@@ -106,8 +126,8 @@ export async function scanRepo(input) {
106
126
  }
107
127
  const diffSpec = resolveDiffSpec(input);
108
128
  const diff = input.workingTree
109
- ? await readWorkingTree(repoRoot, input.includeUntracked === true, diagnostics)
110
- : await readDiff(repoRoot, diffSpec, diagnostics);
129
+ ? await readWorkingTree(repoRoot, input.includeUntracked === true, diagnostics, internalPaths)
130
+ : await readDiff(repoRoot, diffSpec, diagnostics, internalPaths);
111
131
  return {
112
132
  root: repoRoot,
113
133
  files,
@@ -119,21 +139,66 @@ export async function scanRepo(input) {
119
139
  diagnostics
120
140
  };
121
141
  }
122
- async function buildScanCacheLocation(root) {
142
+ function configuredScanCacheRoot() {
143
+ return resolve(process.env.FIXMAP_CACHE_DIR ?? join(process.env.LOCALAPPDATA ?? process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "fixmap", "scans"));
144
+ }
145
+ function containedPath(root, candidate) {
146
+ const distance = relative(root, candidate);
147
+ return distance === "" || distance === ".." || distance.startsWith(`..${sep}`) || isAbsolute(distance)
148
+ ? undefined
149
+ : normalizePath(distance);
150
+ }
151
+ async function resolveInternalPaths(root, paths) {
152
+ const requested = paths.flatMap((path) => {
153
+ const relativePath = containedPath(root, resolve(path));
154
+ return relativePath ? [relativePath] : [];
155
+ });
156
+ if (requested.length === 0 || process.platform !== "win32")
157
+ return new Set(requested);
158
+ // Git pathspecs remain case-sensitive even on a case-insensitive Windows worktree. A
159
+ // caller can open PLAN.JSON when the directory entry is plan.json, so recover Git's
160
+ // canonical spelling before using exact exclusions in status and diff commands.
161
+ try {
162
+ const { stdout } = await exec("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], { cwd: root, maxBuffer: GIT_MAX_BUFFER });
163
+ const repositoryPaths = stdout.split("\0").filter(Boolean).map(normalizePath);
164
+ return new Set(requested.map((path) => repositoryPaths.find((candidate) => sameFilesystemPath(candidate, path)) ?? path));
165
+ }
166
+ catch {
167
+ return new Set(requested);
168
+ }
169
+ }
170
+ function hasInternalPath(paths, path) {
171
+ return [...paths].some((candidate) => sameFilesystemPath(candidate, path));
172
+ }
173
+ function gitPathspec(internalPaths) {
174
+ return ["--", ".", ...[...internalPaths]
175
+ .sort((a, b) => a.localeCompare(b))
176
+ .map((path) => `:(exclude,literal)${path}`)];
177
+ }
178
+ async function buildScanCacheLocation(root, cacheRoot, internalPaths) {
179
+ if (sameFilesystemPath(cacheRoot, root) || containedPath(root, cacheRoot) !== undefined) {
180
+ return {
181
+ skipReason: "Repository scan caching was skipped because FIXMAP_CACHE_DIR is inside the scanned repository. " +
182
+ "Move the cache outside the repository to enable exact-state reuse."
183
+ };
184
+ }
123
185
  try {
124
186
  const [{ stdout: head }, { stdout: status }] = await Promise.all([
125
187
  exec("git", ["rev-parse", "HEAD"], { cwd: root, maxBuffer: GIT_MAX_BUFFER }),
126
- exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--", "."], {
188
+ exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all", ...gitPathspec(internalPaths)], {
127
189
  cwd: root,
128
190
  maxBuffer: GIT_MAX_BUFFER
129
191
  })
130
192
  ]);
131
193
  // Untracked files are scanner inputs but are absent from `git diff`. Do not cache that
132
194
  // state rather than keying it on names alone and serving stale contents after an edit.
133
- if (status.split("\0").some((entry) => entry.startsWith("?? ")))
134
- return undefined;
195
+ if (status.split("\0").some((entry) => entry.startsWith("?? "))) {
196
+ return {
197
+ skipReason: "Repository scan caching was skipped because untracked files are scanner inputs and can change without a stable git diff."
198
+ };
199
+ }
135
200
  const dirtyDiff = status.length > 0
136
- ? (await exec("git", ["diff", "--binary", "--no-ext-diff", "HEAD", "--", "."], {
201
+ ? (await exec("git", ["diff", "--binary", "--no-ext-diff", "HEAD", ...gitPathspec(internalPaths)], {
137
202
  cwd: root,
138
203
  maxBuffer: GIT_MAX_BUFFER
139
204
  })).stdout
@@ -143,28 +208,39 @@ async function buildScanCacheLocation(root) {
143
208
  resolve(root),
144
209
  head.trim(),
145
210
  status,
146
- dirtyDiff
211
+ dirtyDiff,
212
+ ...[...internalPaths].sort((a, b) => a.localeCompare(b))
147
213
  ].join("\0"));
148
- const cacheRoot = process.env.FIXMAP_CACHE_DIR ?? join(process.env.LOCALAPPDATA ?? process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "fixmap", "scans");
149
- return {
150
- path: join(cacheRoot, `${hashText(resolve(root))}-${stateKey}.json`),
151
- stateKey
152
- };
214
+ return { location: {
215
+ path: join(cacheRoot, `${hashText(resolve(root))}-${stateKey}.json`),
216
+ stateKey
217
+ } };
153
218
  }
154
219
  catch {
155
220
  // Non-git directories deliberately do not cache: they have no cheap exact invalidation key.
156
- return undefined;
221
+ return {
222
+ skipReason: "Repository scan caching was skipped because this directory has no exact git state to key safely."
223
+ };
157
224
  }
158
225
  }
159
226
  async function readScanCache(location) {
160
227
  try {
161
228
  const cached = JSON.parse(await readFile(location.path, "utf8"));
229
+ const createdAt = typeof cached.createdAt === "string" ? Date.parse(cached.createdAt) : Number.NaN;
162
230
  if (cached.version !== SCAN_CACHE_VERSION ||
163
231
  cached.stateKey !== location.stateKey ||
232
+ typeof cached.createdAt !== "string" ||
233
+ !Number.isFinite(createdAt) ||
234
+ Date.now() - createdAt > SCAN_CACHE_MAX_AGE_MS ||
235
+ createdAt - Date.now() > SCAN_CACHE_MAX_FUTURE_SKEW_MS ||
164
236
  !Array.isArray(cached.files) ||
237
+ !cached.files.every(isCachedRepoFile) ||
165
238
  !Array.isArray(cached.trackedFiles) ||
239
+ !cached.trackedFiles.every(isCachedRelativePath) ||
166
240
  !Array.isArray(cached.packageScripts) ||
241
+ !cached.packageScripts.every(isCachedPackageScript) ||
167
242
  !Array.isArray(cached.diagnostics) ||
243
+ !cached.diagnostics.every(isCachedDiagnostic) ||
168
244
  !["npm", "pnpm", "yarn", "bun"].includes(cached.packageManager ?? ""))
169
245
  return undefined;
170
246
  return cached;
@@ -173,38 +249,120 @@ async function readScanCache(location) {
173
249
  return undefined;
174
250
  }
175
251
  }
252
+ function isCachedRepoFile(candidate) {
253
+ if (!isRecord(candidate))
254
+ return false;
255
+ const validSkipReason = candidate.textSampleSkipReason === "too-large" ||
256
+ candidate.textSampleSkipReason === "not-text" || candidate.textSampleSkipReason === "unreadable";
257
+ return isCachedRelativePath(candidate.path) &&
258
+ typeof candidate.extension === "string" &&
259
+ typeof candidate.sizeBytes === "number" && Number.isFinite(candidate.sizeBytes) && candidate.sizeBytes >= 0 &&
260
+ typeof candidate.isTest === "boolean" &&
261
+ typeof candidate.isSource === "boolean" &&
262
+ (candidate.kind === "code" || candidate.kind === "config" || candidate.kind === "documentation" || candidate.kind === "other") &&
263
+ typeof candidate.textSample === "string" &&
264
+ typeof candidate.textSampleComplete === "boolean" &&
265
+ ((candidate.textSampleComplete && candidate.textSampleSkipReason === undefined) ||
266
+ (!candidate.textSampleComplete && validSkipReason));
267
+ }
268
+ function isCachedPackageScript(candidate) {
269
+ if (!isRecord(candidate))
270
+ return false;
271
+ return typeof candidate.name === "string" && candidate.name.trim().length > 0 &&
272
+ typeof candidate.command === "string" &&
273
+ (candidate.packageDir === "" || isCachedRelativePath(candidate.packageDir)) &&
274
+ (candidate.packageName === undefined ||
275
+ (typeof candidate.packageName === "string" && candidate.packageName.trim().length > 0));
276
+ }
277
+ function isCachedDiagnostic(candidate) {
278
+ if (!isRecord(candidate))
279
+ return false;
280
+ return typeof candidate.code === "string" && candidate.code.trim().length > 0 &&
281
+ typeof candidate.message === "string" && candidate.message.trim().length > 0 &&
282
+ (candidate.severity === "info" || candidate.severity === "warning" || candidate.severity === "error") &&
283
+ (candidate.paths === undefined ||
284
+ (Array.isArray(candidate.paths) && candidate.paths.every(isCachedRelativePath)));
285
+ }
286
+ function isRecord(candidate) {
287
+ return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
288
+ }
289
+ function isCachedRelativePath(candidate) {
290
+ if (typeof candidate !== "string" || candidate.trim().length === 0 || candidate.includes("\0") ||
291
+ isAbsolute(candidate) || /^[\\/]/.test(candidate) || /^[A-Za-z]:/.test(candidate)) {
292
+ return false;
293
+ }
294
+ // Cache files may move between Windows and POSIX. Normalize both separators regardless
295
+ // of the current host so `..\secret`, UNC paths, and drive-relative paths cannot become
296
+ // trusted repository paths merely because they were read on Linux.
297
+ const segments = candidate.replace(/\\/g, "/").split("/");
298
+ return segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
299
+ }
176
300
  async function writeScanCache(location, cached) {
301
+ const temporaryPath = `${location.path}.${process.pid}-${randomUUID()}.tmp`;
177
302
  try {
178
303
  await mkdir(dirname(location.path), { recursive: true });
179
- await writeFile(location.path, `${JSON.stringify(cached)}\n`, { encoding: "utf8", flag: "wx" });
304
+ await pruneExpiredScanCache(dirname(location.path));
305
+ // Write beside the destination and rename only after the JSON is complete. Readers never
306
+ // observe a truncated cache file, and a corrupt/expired exact-key entry heals immediately.
307
+ await writeFile(temporaryPath, `${JSON.stringify(cached)}\n`, { encoding: "utf8", flag: "wx" });
308
+ await rename(temporaryPath, location.path);
180
309
  }
181
- catch (error) {
182
- const code = error.code;
183
- if (code !== "EEXIST") {
184
- // Cache writes are an optimization. A read-only cache directory must not fail a plan.
185
- return;
186
- }
187
- // An interrupted prior write can leave an invalid exact-key file. Replace only that
188
- // FixMap-owned cache entry; never touch a repository path.
189
- const existing = await readScanCache(location);
190
- if (existing)
191
- return;
310
+ catch {
311
+ // Cache writes are an optimization. Read-only directories and concurrent writers must not
312
+ // fail a report. Remove only this process's uniquely named temporary file.
192
313
  try {
193
- await unlink(location.path);
194
- await writeFile(location.path, `${JSON.stringify(cached)}\n`, { encoding: "utf8", flag: "wx" });
195
- }
196
- catch {
197
- // Another process may have won the replacement race; the current scan is still valid.
314
+ await unlink(temporaryPath);
198
315
  }
316
+ catch { /* The rename may already have consumed it. */ }
199
317
  }
200
318
  }
319
+ async function pruneExpiredScanCache(cacheRoot) {
320
+ try {
321
+ const entries = await readdir(cacheRoot, { withFileTypes: true });
322
+ const now = Date.now();
323
+ await Promise.all(entries
324
+ // A killed process can leave its uniquely named atomic-write file behind. It is not
325
+ // readable as a cache entry, but without pruning it the cache directory grows forever.
326
+ // The same seven-day horizon preserves any plausible active writer.
327
+ .filter((entry) => entry.isFile() && (SCAN_CACHE_FILE.test(entry.name) || SCAN_CACHE_TEMP_FILE.test(entry.name)))
328
+ .map(async (entry) => {
329
+ const path = join(cacheRoot, entry.name);
330
+ try {
331
+ const metadata = await stat(path);
332
+ if (now - metadata.mtimeMs > SCAN_CACHE_MAX_AGE_MS)
333
+ await unlink(path);
334
+ }
335
+ catch {
336
+ // Cache cleanup is best effort and must never block a report.
337
+ }
338
+ }));
339
+ }
340
+ catch {
341
+ // A read-only or concurrently removed cache directory is harmless.
342
+ }
343
+ }
344
+ function describeCacheAge(createdAt) {
345
+ const ageMs = Math.max(0, Date.now() - Date.parse(createdAt));
346
+ if (ageMs < 5_000)
347
+ return "scanned just now";
348
+ const minutes = Math.floor(ageMs / 60_000);
349
+ if (minutes < 1)
350
+ return "scanned less than a minute ago";
351
+ if (minutes < 60)
352
+ return `scanned ${minutes}m ago`;
353
+ const hours = Math.floor(minutes / 60);
354
+ if (hours < 24)
355
+ return `scanned ${hours}h ago`;
356
+ return `scanned ${Math.floor(hours / 24)}d ago`;
357
+ }
201
358
  function hashText(value) {
202
359
  return createHash("sha256").update(value).digest("hex").slice(0, 24);
203
360
  }
204
- async function listTrackedPaths(root) {
361
+ async function listTrackedPaths(root, internalPaths) {
205
362
  try {
206
363
  const { stdout } = await exec("git", ["ls-files", "--cached", "-z"], { cwd: root, maxBuffer: GIT_MAX_BUFFER });
207
- return stdout.split("\0").filter(Boolean).map(normalizePath);
364
+ return stdout.split("\0").filter(Boolean).map(normalizePath)
365
+ .filter((path) => !hasInternalPath(internalPaths, path));
208
366
  }
209
367
  catch {
210
368
  return [];
@@ -213,11 +371,12 @@ async function listTrackedPaths(root) {
213
371
  function resolveDiffSpec(input) {
214
372
  return input.diffSpec ?? (input.baseRef ? `${input.baseRef}...${input.headRef ?? "HEAD"}` : undefined);
215
373
  }
216
- async function listFiles(root, diagnostics) {
374
+ async function listFiles(root, diagnostics, internalCacheRoot, internalPaths) {
217
375
  const gitPaths = await listGitPaths(root);
376
+ const visiblePaths = gitPaths?.paths.filter((path) => !hasInternalPath(internalPaths, normalizePath(path)) && !isInternalCachePath(root, path, internalCacheRoot));
218
377
  const files = gitPaths
219
- ? await buildFilesFromPaths(root, gitPaths.paths, diagnostics, gitPaths.gitLinks)
220
- : (await walkFiles(root, root, diagnostics, { count: 0, limitReported: false }))
378
+ ? await buildFilesFromPaths(root, visiblePaths ?? [], diagnostics, gitPaths.gitLinks)
379
+ : (await walkFiles(root, root, diagnostics, { count: 0, limitReported: false }, internalCacheRoot, internalPaths))
221
380
  .sort((a, b) => a.path.localeCompare(b.path));
222
381
  // These are properties of the scanned files, not of git. Keeping them here makes an
223
382
  // extracted archive and a checkout report the same content limitations.
@@ -225,6 +384,20 @@ async function listFiles(root, diagnostics) {
225
384
  reportGeneratedDominance(diagnostics, files);
226
385
  return files;
227
386
  }
387
+ function isInternalCachePath(root, path, internalCacheRoot) {
388
+ if (!internalCacheRoot)
389
+ return false;
390
+ const relativeCacheRoot = containedPath(root, internalCacheRoot);
391
+ if (relativeCacheRoot) {
392
+ const candidate = process.platform === "win32" ? path.toLowerCase() : path;
393
+ const cachePath = process.platform === "win32" ? relativeCacheRoot.toLowerCase() : relativeCacheRoot;
394
+ return candidate === cachePath || candidate.startsWith(`${cachePath}/`);
395
+ }
396
+ // If someone points FIXMAP_CACHE_DIR at the repository root itself, do not hide the
397
+ // repository. Hide only filenames owned by FixMap's cache format.
398
+ return sameFilesystemPath(internalCacheRoot, root) && (SCAN_CACHE_FILE.test(path) ||
399
+ SCAN_CACHE_TEMP_FILE.test(path));
400
+ }
228
401
  async function listGitPaths(root) {
229
402
  try {
230
403
  const [{ stdout }, { stdout: staged }] = await Promise.all([
@@ -257,6 +430,10 @@ async function buildFilesFromPaths(root, paths, diagnostics, knownGitLinks = new
257
430
  // git listed first would have made that an alphabetical accident.
258
431
  const seenRealPaths = new Map();
259
432
  const linked = [];
433
+ // macOS temporary directories commonly enter through /var while realpath returns
434
+ // /private/var. Resolve the repository root once so that prefix alias does not make
435
+ // every ordinary file look like a symlink.
436
+ const realRoot = await resolveRealPath(root);
260
437
  for (const [index, rawPath] of paths.entries()) {
261
438
  if (results.length >= MAX_SCANNED_FILES) {
262
439
  // Git handed us the whole tracked list, so the remainder is known exactly.
@@ -290,8 +467,8 @@ async function buildFilesFromPaths(root, paths, diagnostics, knownGitLinks = new
290
467
  const seenFile = results[seenIndex];
291
468
  // Looking only at the leaf with lstat misses Windows junctions, where the linked
292
469
  // object is an ancestor directory. Comparing literal and resolved paths covers both.
293
- const seenIsAlias = !sameFilesystemPath(resolve(root, seenFile.path), scanned.realPath);
294
- const currentIsAlias = !sameFilesystemPath(resolve(root, relativePath), scanned.realPath);
470
+ const seenIsAlias = !sameFilesystemPath(resolve(realRoot, seenFile.path), scanned.realPath);
471
+ const currentIsAlias = !sameFilesystemPath(resolve(realRoot, relativePath), scanned.realPath);
295
472
  if (seenIsAlias && !currentIsAlias) {
296
473
  linked.push({ path: seenFile.path, target: relativePath });
297
474
  results[seenIndex] = scanned.file;
@@ -348,7 +525,7 @@ function reportUnreadContent(diagnostics, files) {
348
525
  const sample = affected.slice(0, 3).map((file) => file.path).join(", ");
349
526
  const prefix = `${affected.length.toLocaleString()} source file${affected.length === 1 ? "" : "s"}`;
350
527
  diagnostics.push({
351
- code: "content-unread",
528
+ code: reason === "not-text" ? "content-not-utf8" : "content-unreadable",
352
529
  severity: "warning",
353
530
  message: reason === "not-text"
354
531
  ? `${prefix} ${affected.length === 1 ? "is" : "are"} not UTF-8 text (for example UTF-16 or binary) and ` +
@@ -369,7 +546,7 @@ function reportUnreadContent(diagnostics, files) {
369
546
  .map((file) => `${file.path} (${Math.ceil(file.sizeBytes / 1000).toLocaleString()} kB)`)
370
547
  .join(", ");
371
548
  diagnostics.push({
372
- code: "content-unread",
549
+ code: "content-too-large",
373
550
  severity: "warning",
374
551
  message: `${unread.length.toLocaleString()} source file${unread.length === 1 ? "" : "s"} could not be read as text and ` +
375
552
  `rank${unread.length === 1 ? "s" : ""} on path alone — largest: ${sample}` +
@@ -428,7 +605,7 @@ function reportLinkedDuplicates(diagnostics, linked) {
428
605
  `${linked.length > 3 ? ", …" : ""}.`
429
606
  });
430
607
  }
431
- async function walkFiles(root, current, diagnostics, state) {
608
+ async function walkFiles(root, current, diagnostics, state, internalCacheRoot, internalPaths) {
432
609
  let entries;
433
610
  try {
434
611
  entries = await readdir(current, { withFileTypes: true });
@@ -449,14 +626,20 @@ async function walkFiles(root, current, diagnostics, state) {
449
626
  if (WALK_IGNORED_DIRS.has(entry.name)) {
450
627
  continue;
451
628
  }
452
- results.push(...await walkFiles(root, join(current, entry.name), diagnostics, state));
629
+ const directory = join(current, entry.name);
630
+ if (internalCacheRoot && sameFilesystemPath(directory, internalCacheRoot))
631
+ continue;
632
+ results.push(...await walkFiles(root, directory, diagnostics, state, internalCacheRoot, internalPaths));
453
633
  continue;
454
634
  }
455
635
  if (!entry.isFile()) {
456
636
  continue;
457
637
  }
458
638
  const absolutePath = join(current, entry.name);
459
- const scanned = await toRepoFile(absolutePath, normalizePath(relative(root, absolutePath)));
639
+ const relativePath = normalizePath(relative(root, absolutePath));
640
+ if (hasInternalPath(internalPaths, relativePath) || isInternalCachePath(root, relativePath, internalCacheRoot))
641
+ continue;
642
+ const scanned = await toRepoFile(absolutePath, relativePath);
460
643
  if (scanned.status === "ok") {
461
644
  results.push(scanned.file);
462
645
  state.count += 1;
@@ -475,8 +658,9 @@ async function toRepoFile(absolutePath, relativePath) {
475
658
  if (!fileStat.isFile()) {
476
659
  return { status: "not-a-file" };
477
660
  }
478
- const extension = extname(relativePath);
479
- const isSource = SOURCE_EXTENSIONS.has(extension);
661
+ const extension = extname(relativePath).toLowerCase();
662
+ const conventionalKind = classifyConventionalTextFile(relativePath);
663
+ const isSource = SOURCE_EXTENSIONS.has(extension) || conventionalKind !== undefined;
480
664
  const sample = isSource
481
665
  ? await readTextSample(absolutePath, fileStat.size)
482
666
  : { text: "", complete: true };
@@ -622,21 +806,21 @@ function decodeManifest(bytes) {
622
806
  }
623
807
  return { text: bytes.toString("utf8"), encoding: "utf8" };
624
808
  }
625
- async function readDiff(repoRoot, diffSpec, diagnostics) {
809
+ async function readDiff(repoRoot, diffSpec, diagnostics, internalPaths) {
626
810
  if (!diffSpec) {
627
811
  return { changedFiles: [], diffText: "" };
628
812
  }
629
813
  try {
630
814
  const [{ stdout: names }, { stdout: diffText }] = await Promise.all([
631
- exec("git", ["diff", "--relative", "--name-only", diffSpec], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
632
- exec("git", ["diff", "--relative", diffSpec], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
815
+ exec("git", ["diff", "--relative", "--name-only", diffSpec, ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
816
+ exec("git", ["diff", "--relative", diffSpec, ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
633
817
  ]);
634
818
  const tracked = names
635
819
  .split(/\r?\n/)
636
820
  .map((path) => path.trim())
637
821
  .filter(Boolean)
638
822
  .map(normalizePath);
639
- const untracked = diffSpec.includes("..") ? [] : await listUntrackedPaths(repoRoot);
823
+ const untracked = diffSpec.includes("..") ? [] : await listUntrackedPaths(repoRoot, internalPaths);
640
824
  const changedFiles = [...new Set([...tracked, ...untracked])].sort((a, b) => a.localeCompare(b));
641
825
  diagnostics.push({
642
826
  code: "diff-resolved",
@@ -646,10 +830,7 @@ async function readDiff(repoRoot, diffSpec, diagnostics) {
646
830
  : `Diff "${truncateForDiagnostic(diffSpec, DIAGNOSTIC_SPEC_LIMIT)}" resolved ${changedFiles.length} changed ${changedFiles.length === 1 ? "path" : "paths"}.`,
647
831
  paths: changedFiles.slice(0, 8)
648
832
  });
649
- return {
650
- changedFiles,
651
- diffText: diffText.slice(0, MAX_DIFF_TEXT_CHARS)
652
- };
833
+ return { changedFiles, diffText: sampleDiffText(diffText, diagnostics) };
653
834
  }
654
835
  catch (error) {
655
836
  const checkoutState = isMissingGit(error) ? undefined : await describeGitCheckout(repoRoot);
@@ -667,6 +848,65 @@ async function readDiff(repoRoot, diffSpec, diagnostics) {
667
848
  return { changedFiles: [], diffText: "" };
668
849
  }
669
850
  }
851
+ /**
852
+ * Large diffs used to be cut at an arbitrary UTF-16 offset. That could split a line and,
853
+ * because git orders files, erase every content signal from files later in the diff. For an
854
+ * oversized diff the ranker only needs added lines, so sample complete added lines from every
855
+ * file in round-robin order and say exactly what was omitted.
856
+ */
857
+ function sampleDiffText(diffText, diagnostics) {
858
+ if (diffText.length <= MAX_DIFF_TEXT_CHARS)
859
+ return diffText;
860
+ const groups = [];
861
+ let current;
862
+ for (const line of diffText.split(/\r?\n/)) {
863
+ if (line.startsWith("diff --git ")) {
864
+ current = [];
865
+ groups.push(current);
866
+ continue;
867
+ }
868
+ if (line.startsWith("+") && !line.startsWith("+++")) {
869
+ if (!current) {
870
+ current = [];
871
+ groups.push(current);
872
+ }
873
+ current.push(line);
874
+ }
875
+ }
876
+ const queues = groups.filter((group) => group.length > 0);
877
+ const selected = [];
878
+ let selectedChars = 0;
879
+ let selectedLines = 0;
880
+ const totalLines = queues.reduce((total, group) => total + group.length, 0);
881
+ let cursor = 0;
882
+ let madeProgress = true;
883
+ while (madeProgress && selectedChars < MAX_DIFF_TEXT_CHARS) {
884
+ madeProgress = false;
885
+ for (const group of queues) {
886
+ const line = group[cursor];
887
+ if (line === undefined)
888
+ continue;
889
+ madeProgress = true;
890
+ const separator = selected.length === 0 ? 0 : 1;
891
+ if (selectedChars + separator + line.length <= MAX_DIFF_TEXT_CHARS) {
892
+ selected.push(line);
893
+ selectedChars += separator + line.length;
894
+ selectedLines += 1;
895
+ }
896
+ }
897
+ cursor += 1;
898
+ }
899
+ diagnostics.push({
900
+ code: "diff-text-truncated",
901
+ severity: "warning",
902
+ message: `The git diff was ${diffText.length.toLocaleString()} characters, above FixMap's ` +
903
+ `${MAX_DIFF_TEXT_CHARS.toLocaleString()}-character signal budget. FixMap sampled ` +
904
+ `${selectedLines.toLocaleString()} of ${totalLines.toLocaleString()} complete added lines ` +
905
+ `across ${queues.length.toLocaleString()} changed ${queues.length === 1 ? "file" : "files"}; ` +
906
+ "changed-file paths remain complete, but omitted diff content could reduce ranking precision."
907
+ });
908
+ return selected.join("\n");
909
+ }
670
910
  /**
671
911
  * "Map what I am touching right now."
672
912
  *
@@ -675,18 +915,18 @@ async function readDiff(repoRoot, diffSpec, diagnostics) {
675
915
  * scratch notes ranking beside the edit. Staged and unstaged tracked changes are what
676
916
  * "what I am working on" means; untracked files are a separate, opt-in question.
677
917
  */
678
- async function readWorkingTree(repoRoot, includeUntracked, diagnostics) {
918
+ async function readWorkingTree(repoRoot, includeUntracked, diagnostics, internalPaths) {
679
919
  try {
680
920
  const [{ stdout: names }, { stdout: diffText }] = await Promise.all([
681
- exec("git", ["diff", "--relative", "--name-only", "HEAD"], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
682
- exec("git", ["diff", "--relative", "HEAD"], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
921
+ exec("git", ["diff", "--relative", "--name-only", "HEAD", ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
922
+ exec("git", ["diff", "--relative", "HEAD", ...gitPathspec(internalPaths)], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER })
683
923
  ]);
684
924
  const tracked = names
685
925
  .split(/\r?\n/)
686
926
  .map((path) => path.trim())
687
927
  .filter(Boolean)
688
928
  .map(normalizePath);
689
- const untracked = includeUntracked ? await listUntrackedPaths(repoRoot) : [];
929
+ const untracked = includeUntracked ? await listUntrackedPaths(repoRoot, internalPaths) : [];
690
930
  const changedFiles = [...new Set([...tracked, ...untracked])].sort((a, b) => a.localeCompare(b));
691
931
  diagnostics.push({
692
932
  code: "working-tree-diff",
@@ -699,7 +939,7 @@ async function readWorkingTree(repoRoot, includeUntracked, diagnostics) {
699
939
  `against HEAD${includeUntracked ? ", including untracked files" : " (untracked files are not counted as changed, though they still rank; pass --include-untracked to count them)"}.`,
700
940
  paths: changedFiles.slice(0, 8)
701
941
  });
702
- return { changedFiles, diffText: diffText.slice(0, MAX_DIFF_TEXT_CHARS) };
942
+ return { changedFiles, diffText: sampleDiffText(diffText, diagnostics) };
703
943
  }
704
944
  catch (error) {
705
945
  const checkoutState = isMissingGit(error) ? undefined : await describeGitCheckout(repoRoot);
@@ -758,28 +998,69 @@ function gitErrorDetail(error) {
758
998
  function isMissingGit(error) {
759
999
  return error?.code === "ENOENT";
760
1000
  }
761
- function detectPackageManager(files) {
762
- const paths = new Set(files.map((file) => file.path));
763
- if (paths.has("pnpm-lock.yaml") || paths.has("pnpm-workspace.yaml"))
764
- return "pnpm";
765
- if (paths.has("yarn.lock") || paths.has(".yarnrc.yml"))
766
- return "yarn";
767
- if (paths.has("bun.lock") || paths.has("bun.lockb"))
768
- return "bun";
1001
+ function detectPackageManager(files, diagnostics) {
1002
+ const rootManagers = packageManagersForPaths(files.map((file) => file.path).filter((path) => !path.includes("/")));
1003
+ if (rootManagers.length > 1) {
1004
+ diagnostics.push({
1005
+ code: "package-manager-conflict",
1006
+ severity: "warning",
1007
+ message: `Conflicting root package-manager files were found (${rootManagers.join(", ")}); using ${rootManagers[0]} deterministically. Remove the stale lockfile so routed commands are unambiguous.`
1008
+ });
1009
+ }
1010
+ if (rootManagers[0])
1011
+ return rootManagers[0];
1012
+ // Archives and workspace extracts do not always carry a root lockfile. When every nested
1013
+ // declaration agrees, use that manager rather than printing npm commands that cannot run.
1014
+ const nestedManagers = packageManagersForPaths(files.map((file) => file.path));
1015
+ if (nestedManagers.length === 1)
1016
+ return nestedManagers[0];
1017
+ if (nestedManagers.length > 1) {
1018
+ diagnostics.push({
1019
+ code: "package-manager-conflict",
1020
+ severity: "warning",
1021
+ message: `Nested package-manager files disagree (${nestedManagers.join(", ")}); defaulting to npm for root routes. Point --repo at one workspace to get an unambiguous command.`
1022
+ });
1023
+ }
769
1024
  return "npm";
770
1025
  }
1026
+ function packageManagersForPaths(paths) {
1027
+ const names = new Set(paths.map((path) => path.split("/").at(-1) ?? path));
1028
+ const managers = [];
1029
+ if (names.has("pnpm-lock.yaml") || names.has("pnpm-workspace.yaml"))
1030
+ managers.push("pnpm");
1031
+ if (names.has("yarn.lock") || names.has(".yarnrc.yml"))
1032
+ managers.push("yarn");
1033
+ if (names.has("bun.lock") || names.has("bun.lockb"))
1034
+ managers.push("bun");
1035
+ if (names.has("package-lock.json") || names.has("npm-shrinkwrap.json"))
1036
+ managers.push("npm");
1037
+ return managers;
1038
+ }
771
1039
  function classifyFile(path, extension) {
772
1040
  const lower = path.toLowerCase();
773
- if (extension === ".md" || lower.startsWith("docs/") || lower === "license")
1041
+ const conventionalKind = classifyConventionalTextFile(path);
1042
+ if (conventionalKind)
1043
+ return conventionalKind;
1044
+ if (extension === ".md" || lower.startsWith("docs/"))
774
1045
  return "documentation";
775
1046
  if (lower.startsWith(".github/") ||
776
1047
  [".json", ".yaml", ".yml"].includes(extension) ||
777
- /(^|\/)([^/]+\.)?(config|rc)\.[^/]+$/.test(lower))
1048
+ /(^|\/)(?:[^/]+\.config|\.[^/]*rc)\.[^/]+$/.test(lower))
778
1049
  return "config";
779
1050
  if (SOURCE_EXTENSIONS.has(extension))
780
1051
  return "code";
781
1052
  return "other";
782
1053
  }
1054
+ function classifyConventionalTextFile(path) {
1055
+ const name = path.replace(/\\/g, "/").split("/").at(-1)?.toLowerCase() ?? "";
1056
+ if (CONVENTIONAL_DOCUMENT_NAMES.has(name))
1057
+ return "documentation";
1058
+ if (CONVENTIONAL_CONFIG_NAMES.has(name))
1059
+ return "config";
1060
+ if (/\.(?:csproj|fsproj|vbproj)$/.test(name))
1061
+ return "config";
1062
+ return undefined;
1063
+ }
783
1064
  async function readTextSample(path, sizeBytes) {
784
1065
  if (sizeBytes > MAX_TEXT_SAMPLE_BYTES) {
785
1066
  return { text: "", complete: false, skipReason: "too-large" };
@@ -800,10 +1081,11 @@ async function readTextSample(path, sizeBytes) {
800
1081
  return { text: "", complete: false, skipReason: "unreadable" };
801
1082
  }
802
1083
  }
803
- async function listUntrackedPaths(repoRoot) {
1084
+ async function listUntrackedPaths(repoRoot, internalPaths = new Set()) {
804
1085
  try {
805
1086
  const { stdout } = await exec("git", ["ls-files", "--others", "--exclude-standard", "-z"], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER });
806
- return stdout.split("\0").filter(Boolean).map(normalizePath);
1087
+ return stdout.split("\0").filter(Boolean).map(normalizePath)
1088
+ .filter((path) => !hasInternalPath(internalPaths, path));
807
1089
  }
808
1090
  catch {
809
1091
  return [];