@aryam/fixmap-core 0.8.7 → 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 +24 -17
  14. package/dist/explain.js.map +1 -1
  15. package/dist/grounding.d.ts +3 -1
  16. package/dist/grounding.js +24 -19
  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 +6 -1
  22. package/dist/index.js +4 -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 +3 -1
  34. package/dist/plan.js +58 -15
  35. package/dist/plan.js.map +1 -1
  36. package/dist/rank.d.ts +9 -0
  37. package/dist/rank.js +171 -90
  38. package/dist/rank.js.map +1 -1
  39. package/dist/repo-scan.d.ts +3 -1
  40. package/dist/repo-scan.js +615 -116
  41. package/dist/repo-scan.js.map +1 -1
  42. package/dist/report.d.ts +6 -0
  43. package/dist/report.js +92 -55
  44. package/dist/report.js.map +1 -1
  45. package/dist/signals.d.ts +7 -0
  46. package/dist/signals.js +150 -44
  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 +8 -2
  54. package/dist/validate.d.ts +10 -0
  55. package/dist/validate.js +188 -0
  56. package/dist/validate.js.map +1 -0
  57. package/dist/verify.js +48 -6
  58. package/dist/verify.js.map +1 -1
  59. package/package.json +1 -1
package/dist/repo-scan.js CHANGED
@@ -1,33 +1,25 @@
1
1
  import { execFile } from "node:child_process";
2
- import { lstat, readdir, readFile, realpath, stat } from "node:fs/promises";
3
- import { dirname, extname, join, relative, resolve, sep } from "node:path";
2
+ import { createHash, randomUUID } from "node:crypto";
3
+ import { mkdir, readdir, readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
4
+ import { homedir } from "node:os";
5
+ import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
4
6
  import { promisify } from "node:util";
5
- import { ALWAYS_IGNORED_DIRS, GENERATED_DIRS, isGeneratedPath } from "./paths.js";
7
+ import { ALWAYS_IGNORED_DIRS, GENERATED_DIRS, SOURCE_FILE_EXTENSIONS, isGeneratedPath } from "./paths.js";
6
8
  import { DIAGNOSTIC_SPEC_LIMIT, truncateForDiagnostic } from "./text.js";
7
- const WALK_IGNORED_DIRS = new Set([...ALWAYS_IGNORED_DIRS, ...GENERATED_DIRS]);
8
- const SOURCE_EXTENSIONS = new Set([
9
- ".cjs",
10
- ".cs",
11
- ".css",
12
- ".cts",
13
- ".go",
14
- ".java",
15
- ".js",
16
- ".json",
17
- ".jsx",
18
- ".md",
19
- ".mjs",
20
- ".mts",
21
- ".php",
22
- ".py",
23
- ".rb",
24
- ".rs",
25
- ".svelte",
26
- ".ts",
27
- ".tsx",
28
- ".vue",
29
- ".yaml",
30
- ".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"
31
23
  ]);
32
24
  /**
33
25
  * A single-file component is mostly template and style. Sampling the whole file let markup
@@ -36,12 +28,27 @@ const SOURCE_EXTENSIONS = new Set([
36
28
  */
37
29
  const SFC_EXTENSIONS = new Set([".vue", ".svelte"]);
38
30
  const SFC_SCRIPT_BLOCK = /<script\b[^>]*>([\s\S]*?)<\/script>/gi;
39
- const TEST_PATTERNS = [/\.test\./, /\.spec\./, /(^|\/|\\)__tests__(\/|\\)/, /(^|\/|\\)tests?(\/|\\)/];
31
+ const TEST_PATTERNS = [
32
+ /\.test(?:\.|-d\.)/,
33
+ /\.spec\./,
34
+ /(^|\/|\\)__tests__(\/|\\)/,
35
+ /(^|\/|\\)tests?(\/|\\)/,
36
+ /(^|\/|\\)spec(\/|\\)/,
37
+ /_spec\.rb$/i,
38
+ /(?:Test\.java|Tests?\.cs|Test\.php)$/i,
39
+ /_test\.go$/,
40
+ /(^|\/|\\)(?:test_[^/\\]+|[^/\\]+_test)\.py$/
41
+ ];
40
42
  const MAX_TEXT_SAMPLE_BYTES = 64_000;
41
43
  const MAX_DIFF_TEXT_CHARS = 200_000;
42
44
  const MAX_SCANNED_FILES = 25_000;
43
45
  const GIT_MAX_BUFFER = 10 * 1024 * 1024;
44
46
  const exec = promisify(execFile);
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;
45
52
  export async function scanRepo(input) {
46
53
  const repoRoot = resolve(input.repoRoot);
47
54
  if (!(await isDirectory(repoRoot))) {
@@ -60,13 +67,67 @@ export async function scanRepo(input) {
60
67
  };
61
68
  }
62
69
  const diagnostics = [];
63
- const files = await listFiles(repoRoot, diagnostics);
64
- const trackedFiles = await listTrackedPaths(repoRoot);
65
- const packageScripts = await readPackageScripts(repoRoot, files, diagnostics);
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
+ }
93
+ const cached = cacheLocation ? await readScanCache(cacheLocation) : undefined;
94
+ let files;
95
+ let trackedFiles;
96
+ let packageScripts;
97
+ let packageManager;
98
+ if (cached) {
99
+ files = cached.files;
100
+ trackedFiles = cached.trackedFiles;
101
+ packageScripts = cached.packageScripts;
102
+ packageManager = cached.packageManager;
103
+ diagnostics.push(...cached.diagnostics, {
104
+ code: "cache-hit",
105
+ severity: "info",
106
+ message: `Reused the repository scan for the exact current git state (${files.length.toLocaleString()} files, ${describeCacheAge(cached.createdAt)}). Pass --no-cache to rescan.`
107
+ });
108
+ }
109
+ else {
110
+ files = await listFiles(repoRoot, diagnostics, internalCacheRoot, internalPaths);
111
+ trackedFiles = await listTrackedPaths(repoRoot, internalPaths);
112
+ packageScripts = await readPackageScripts(repoRoot, files, diagnostics);
113
+ packageManager = detectPackageManager(files, diagnostics);
114
+ if (cacheLocation) {
115
+ await writeScanCache(cacheLocation, {
116
+ version: SCAN_CACHE_VERSION,
117
+ stateKey: cacheLocation.stateKey,
118
+ createdAt: new Date().toISOString(),
119
+ files,
120
+ trackedFiles,
121
+ packageScripts,
122
+ packageManager,
123
+ diagnostics: [...diagnostics]
124
+ });
125
+ }
126
+ }
66
127
  const diffSpec = resolveDiffSpec(input);
67
128
  const diff = input.workingTree
68
- ? await readWorkingTree(repoRoot, input.includeUntracked === true, diagnostics)
69
- : await readDiff(repoRoot, diffSpec, diagnostics);
129
+ ? await readWorkingTree(repoRoot, input.includeUntracked === true, diagnostics, internalPaths)
130
+ : await readDiff(repoRoot, diffSpec, diagnostics, internalPaths);
70
131
  return {
71
132
  root: repoRoot,
72
133
  files,
@@ -74,14 +135,234 @@ export async function scanRepo(input) {
74
135
  packageScripts,
75
136
  changedFiles: diff.changedFiles,
76
137
  diffText: diff.diffText,
77
- packageManager: detectPackageManager(files),
138
+ packageManager,
78
139
  diagnostics
79
140
  };
80
141
  }
81
- async function listTrackedPaths(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
+ }
185
+ try {
186
+ const [{ stdout: head }, { stdout: status }] = await Promise.all([
187
+ exec("git", ["rev-parse", "HEAD"], { cwd: root, maxBuffer: GIT_MAX_BUFFER }),
188
+ exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all", ...gitPathspec(internalPaths)], {
189
+ cwd: root,
190
+ maxBuffer: GIT_MAX_BUFFER
191
+ })
192
+ ]);
193
+ // Untracked files are scanner inputs but are absent from `git diff`. Do not cache that
194
+ // state rather than keying it on names alone and serving stale contents after an edit.
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
+ }
200
+ const dirtyDiff = status.length > 0
201
+ ? (await exec("git", ["diff", "--binary", "--no-ext-diff", "HEAD", ...gitPathspec(internalPaths)], {
202
+ cwd: root,
203
+ maxBuffer: GIT_MAX_BUFFER
204
+ })).stdout
205
+ : "";
206
+ const stateKey = hashText([
207
+ String(SCAN_CACHE_VERSION),
208
+ resolve(root),
209
+ head.trim(),
210
+ status,
211
+ dirtyDiff,
212
+ ...[...internalPaths].sort((a, b) => a.localeCompare(b))
213
+ ].join("\0"));
214
+ return { location: {
215
+ path: join(cacheRoot, `${hashText(resolve(root))}-${stateKey}.json`),
216
+ stateKey
217
+ } };
218
+ }
219
+ catch {
220
+ // Non-git directories deliberately do not cache: they have no cheap exact invalidation key.
221
+ return {
222
+ skipReason: "Repository scan caching was skipped because this directory has no exact git state to key safely."
223
+ };
224
+ }
225
+ }
226
+ async function readScanCache(location) {
227
+ try {
228
+ const cached = JSON.parse(await readFile(location.path, "utf8"));
229
+ const createdAt = typeof cached.createdAt === "string" ? Date.parse(cached.createdAt) : Number.NaN;
230
+ if (cached.version !== SCAN_CACHE_VERSION ||
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 ||
236
+ !Array.isArray(cached.files) ||
237
+ !cached.files.every(isCachedRepoFile) ||
238
+ !Array.isArray(cached.trackedFiles) ||
239
+ !cached.trackedFiles.every(isCachedRelativePath) ||
240
+ !Array.isArray(cached.packageScripts) ||
241
+ !cached.packageScripts.every(isCachedPackageScript) ||
242
+ !Array.isArray(cached.diagnostics) ||
243
+ !cached.diagnostics.every(isCachedDiagnostic) ||
244
+ !["npm", "pnpm", "yarn", "bun"].includes(cached.packageManager ?? ""))
245
+ return undefined;
246
+ return cached;
247
+ }
248
+ catch {
249
+ return undefined;
250
+ }
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
+ }
300
+ async function writeScanCache(location, cached) {
301
+ const temporaryPath = `${location.path}.${process.pid}-${randomUUID()}.tmp`;
302
+ try {
303
+ await mkdir(dirname(location.path), { recursive: true });
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);
309
+ }
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.
313
+ try {
314
+ await unlink(temporaryPath);
315
+ }
316
+ catch { /* The rename may already have consumed it. */ }
317
+ }
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
+ }
358
+ function hashText(value) {
359
+ return createHash("sha256").update(value).digest("hex").slice(0, 24);
360
+ }
361
+ async function listTrackedPaths(root, internalPaths) {
82
362
  try {
83
363
  const { stdout } = await exec("git", ["ls-files", "--cached", "-z"], { cwd: root, maxBuffer: GIT_MAX_BUFFER });
84
- return stdout.split("\0").filter(Boolean).map(normalizePath);
364
+ return stdout.split("\0").filter(Boolean).map(normalizePath)
365
+ .filter((path) => !hasInternalPath(internalPaths, path));
85
366
  }
86
367
  catch {
87
368
  return [];
@@ -90,26 +371,56 @@ async function listTrackedPaths(root) {
90
371
  function resolveDiffSpec(input) {
91
372
  return input.diffSpec ?? (input.baseRef ? `${input.baseRef}...${input.headRef ?? "HEAD"}` : undefined);
92
373
  }
93
- async function listFiles(root, diagnostics) {
374
+ async function listFiles(root, diagnostics, internalCacheRoot, internalPaths) {
94
375
  const gitPaths = await listGitPaths(root);
95
- if (gitPaths) {
96
- return buildFilesFromPaths(root, gitPaths, diagnostics);
376
+ const visiblePaths = gitPaths?.paths.filter((path) => !hasInternalPath(internalPaths, normalizePath(path)) && !isInternalCachePath(root, path, internalCacheRoot));
377
+ const files = gitPaths
378
+ ? await buildFilesFromPaths(root, visiblePaths ?? [], diagnostics, gitPaths.gitLinks)
379
+ : (await walkFiles(root, root, diagnostics, { count: 0, limitReported: false }, internalCacheRoot, internalPaths))
380
+ .sort((a, b) => a.path.localeCompare(b.path));
381
+ // These are properties of the scanned files, not of git. Keeping them here makes an
382
+ // extracted archive and a checkout report the same content limitations.
383
+ reportUnreadContent(diagnostics, files);
384
+ reportGeneratedDominance(diagnostics, files);
385
+ return files;
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}/`);
97
395
  }
98
- const files = await walkFiles(root, root, diagnostics, { count: 0, limitReported: false });
99
- return files.sort((a, b) => a.path.localeCompare(b.path));
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));
100
400
  }
101
401
  async function listGitPaths(root) {
102
402
  try {
103
- const { stdout } = await exec("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], { cwd: root, maxBuffer: GIT_MAX_BUFFER });
104
- return [...new Set(stdout.split("\0").filter(Boolean))];
403
+ const [{ stdout }, { stdout: staged }] = await Promise.all([
404
+ exec("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], {
405
+ cwd: root,
406
+ maxBuffer: GIT_MAX_BUFFER
407
+ }),
408
+ exec("git", ["ls-files", "--stage", "-z"], { cwd: root, maxBuffer: GIT_MAX_BUFFER })
409
+ ]);
410
+ const gitLinks = new Set(staged.split("\0").flatMap((entry) => {
411
+ const match = /^160000\s+[0-9a-f]+\s+\d+\t(.+)$/i.exec(entry);
412
+ return match?.[1] ? [normalizePath(match[1])] : [];
413
+ }));
414
+ return { paths: [...new Set(stdout.split("\0").filter(Boolean))], gitLinks };
105
415
  }
106
416
  catch {
107
417
  return undefined;
108
418
  }
109
419
  }
110
- async function buildFilesFromPaths(root, paths, diagnostics) {
420
+ async function buildFilesFromPaths(root, paths, diagnostics, knownGitLinks = new Set()) {
111
421
  const results = [];
112
422
  const absent = [];
423
+ const gitLinks = [];
113
424
  // Git can hand back two tracked paths that are one file on disk: a symlink beside its
114
425
  // target, or anything under a Windows junction. `stat` follows both, so each produced an
115
426
  // identically scored row and one module filled two slots in the plan.
@@ -119,6 +430,10 @@ async function buildFilesFromPaths(root, paths, diagnostics) {
119
430
  // git listed first would have made that an alphabetical accident.
120
431
  const seenRealPaths = new Map();
121
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);
122
437
  for (const [index, rawPath] of paths.entries()) {
123
438
  if (results.length >= MAX_SCANNED_FILES) {
124
439
  // Git handed us the whole tracked list, so the remainder is known exactly.
@@ -131,20 +446,30 @@ async function buildFilesFromPaths(root, paths, diagnostics) {
131
446
  if (isInAlwaysIgnoredDir(relativePath)) {
132
447
  continue;
133
448
  }
449
+ if (knownGitLinks.has(relativePath)) {
450
+ gitLinks.push(relativePath);
451
+ continue;
452
+ }
134
453
  const scanned = await toRepoFile(join(root, rawPath), relativePath);
135
454
  if (scanned.status === "absent") {
136
455
  absent.push(relativePath);
137
456
  continue;
138
457
  }
458
+ if (scanned.status === "not-a-file") {
459
+ gitLinks.push(relativePath);
460
+ continue;
461
+ }
139
462
  if (scanned.status !== "ok") {
140
463
  continue;
141
464
  }
142
465
  const seenIndex = seenRealPaths.get(scanned.realPath);
143
466
  if (seenIndex !== undefined) {
144
467
  const seenFile = results[seenIndex];
145
- // Exactly one of the two can be the real file, so a single lstat settles it. This
146
- // runs only on a collision, which is rare by definition.
147
- if (await isSymbolicLink(join(root, seenFile.path))) {
468
+ // Looking only at the leaf with lstat misses Windows junctions, where the linked
469
+ // object is an ancestor directory. Comparing literal and resolved paths covers both.
470
+ const seenIsAlias = !sameFilesystemPath(resolve(realRoot, seenFile.path), scanned.realPath);
471
+ const currentIsAlias = !sameFilesystemPath(resolve(realRoot, relativePath), scanned.realPath);
472
+ if (seenIsAlias && !currentIsAlias) {
148
473
  linked.push({ path: seenFile.path, target: relativePath });
149
474
  results[seenIndex] = scanned.file;
150
475
  }
@@ -158,8 +483,7 @@ async function buildFilesFromPaths(root, paths, diagnostics) {
158
483
  }
159
484
  reportAbsentTrackedPaths(diagnostics, absent);
160
485
  reportLinkedDuplicates(diagnostics, linked);
161
- reportUnreadContent(diagnostics, results);
162
- reportGeneratedDominance(diagnostics, results);
486
+ reportSkippedSubmodules(diagnostics, gitLinks);
163
487
  return results.sort((a, b) => a.path.localeCompare(b.path));
164
488
  }
165
489
  /**
@@ -185,27 +509,61 @@ function reportAbsentTrackedPaths(diagnostics, absent) {
185
509
  }
186
510
  /**
187
511
  * A source file whose contents were never read still ranks — on its path alone. That is the
188
- * shape of the `got` miss behind #274: `source/core/index.ts` is 79KB, past the sample
512
+ * shape of the `got` miss behind #274: `source/core/index.ts` is 79 kB, past the sample
189
513
  * ceiling, so its entire content signal was silently absent and only an explicit path
190
514
  * mention kept it visible. Naming those files lets a reader see that the ranking for them
191
515
  * rests on the path and nothing else.
192
516
  */
193
517
  function reportUnreadContent(diagnostics, files) {
194
- const unread = files.filter((file) => file.isSource && file.textSampleComplete === false);
518
+ const unavailable = files.filter((file) => file.isSource &&
519
+ file.textSampleComplete === false &&
520
+ file.textSampleSkipReason !== "too-large");
521
+ for (const reason of ["not-text", "unreadable"]) {
522
+ const affected = unavailable.filter((file) => file.textSampleSkipReason === reason);
523
+ if (affected.length === 0)
524
+ continue;
525
+ const sample = affected.slice(0, 3).map((file) => file.path).join(", ");
526
+ const prefix = `${affected.length.toLocaleString()} source file${affected.length === 1 ? "" : "s"}`;
527
+ diagnostics.push({
528
+ code: reason === "not-text" ? "content-not-utf8" : "content-unreadable",
529
+ severity: "warning",
530
+ message: reason === "not-text"
531
+ ? `${prefix} ${affected.length === 1 ? "is" : "are"} not UTF-8 text (for example UTF-16 or binary) and ` +
532
+ `rank${affected.length === 1 ? "s" : ""} on path alone: ${sample}${affected.length > 3 ? ", ..." : ""}. Re-save source as UTF-8 to rank its contents.`
533
+ : `${prefix} could not be read and rank${affected.length === 1 ? "s" : ""} on path alone: ${sample}${affected.length > 3 ? ", ..." : ""}. Check file permissions and retry.`,
534
+ paths: affected.slice(0, 8).map((file) => file.path)
535
+ });
536
+ }
537
+ const unread = files.filter((file) => file.isSource &&
538
+ file.textSampleComplete === false &&
539
+ file.textSampleSkipReason === "too-large");
195
540
  if (unread.length === 0)
196
541
  return;
197
542
  const sample = unread
198
543
  .slice()
199
544
  .sort((a, b) => b.sizeBytes - a.sizeBytes)
200
545
  .slice(0, 3)
201
- .map((file) => `${file.path} (${Math.round(file.sizeBytes / 1024).toLocaleString()}KB)`)
546
+ .map((file) => `${file.path} (${Math.ceil(file.sizeBytes / 1000).toLocaleString()} kB)`)
202
547
  .join(", ");
203
548
  diagnostics.push({
204
- code: "content-unread",
549
+ code: "content-too-large",
205
550
  severity: "warning",
206
551
  message: `${unread.length.toLocaleString()} source file${unread.length === 1 ? "" : "s"} could not be read as text and ` +
207
552
  `rank${unread.length === 1 ? "s" : ""} on path alone — largest: ${sample}` +
208
- `${unread.length > 3 ? ", …" : ""}. Files over ${(MAX_TEXT_SAMPLE_BYTES / 1000).toLocaleString()}KB are not sampled.`
553
+ `${unread.length > 3 ? ", …" : ""}. Files over ${(MAX_TEXT_SAMPLE_BYTES / 1000).toLocaleString()} kB are not sampled.`,
554
+ paths: unread.slice(0, 8).map((file) => file.path)
555
+ });
556
+ }
557
+ function reportSkippedSubmodules(diagnostics, gitLinks) {
558
+ if (gitLinks.length === 0)
559
+ return;
560
+ diagnostics.push({
561
+ code: "submodules-skipped",
562
+ severity: "info",
563
+ message: `${gitLinks.length.toLocaleString()} git submodule${gitLinks.length === 1 ? " was" : "s were"} not scanned: ` +
564
+ `${gitLinks.slice(0, 3).join(", ")}${gitLinks.length > 3 ? ", …" : ""}. ` +
565
+ "Submodules are separate repositories; point --repo at one to map its contents.",
566
+ paths: gitLinks.slice(0, 8)
209
567
  });
210
568
  }
211
569
  /**
@@ -247,7 +605,7 @@ function reportLinkedDuplicates(diagnostics, linked) {
247
605
  `${linked.length > 3 ? ", …" : ""}.`
248
606
  });
249
607
  }
250
- async function walkFiles(root, current, diagnostics, state) {
608
+ async function walkFiles(root, current, diagnostics, state, internalCacheRoot, internalPaths) {
251
609
  let entries;
252
610
  try {
253
611
  entries = await readdir(current, { withFileTypes: true });
@@ -268,14 +626,20 @@ async function walkFiles(root, current, diagnostics, state) {
268
626
  if (WALK_IGNORED_DIRS.has(entry.name)) {
269
627
  continue;
270
628
  }
271
- 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));
272
633
  continue;
273
634
  }
274
635
  if (!entry.isFile()) {
275
636
  continue;
276
637
  }
277
638
  const absolutePath = join(current, entry.name);
278
- 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);
279
643
  if (scanned.status === "ok") {
280
644
  results.push(scanned.file);
281
645
  state.count += 1;
@@ -294,8 +658,9 @@ async function toRepoFile(absolutePath, relativePath) {
294
658
  if (!fileStat.isFile()) {
295
659
  return { status: "not-a-file" };
296
660
  }
297
- const extension = extname(relativePath);
298
- 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;
299
664
  const sample = isSource
300
665
  ? await readTextSample(absolutePath, fileStat.size)
301
666
  : { text: "", complete: true };
@@ -313,7 +678,8 @@ async function toRepoFile(absolutePath, relativePath) {
313
678
  isSource,
314
679
  kind: classifyFile(relativePath, extension),
315
680
  textSample: sample.text,
316
- textSampleComplete: sample.complete
681
+ textSampleComplete: sample.complete,
682
+ ...(sample.skipReason ? { textSampleSkipReason: sample.skipReason } : {})
317
683
  }
318
684
  };
319
685
  }
@@ -339,13 +705,10 @@ function extractScriptBlocks(text) {
339
705
  const joined = blocks.join("\n").trim();
340
706
  return joined || text;
341
707
  }
342
- async function isSymbolicLink(absolutePath) {
343
- try {
344
- return (await lstat(absolutePath)).isSymbolicLink();
345
- }
346
- catch {
347
- return false;
348
- }
708
+ function sameFilesystemPath(left, right) {
709
+ return process.platform === "win32"
710
+ ? left.toLowerCase() === right.toLowerCase()
711
+ : left === right;
349
712
  }
350
713
  function isInAlwaysIgnoredDir(relativePath) {
351
714
  return relativePath.split("/").slice(0, -1).some((segment) => ALWAYS_IGNORED_DIRS.has(segment));
@@ -392,8 +755,9 @@ async function readPackageScripts(root, files, diagnostics) {
392
755
  });
393
756
  continue;
394
757
  }
395
- const decoded = decodeManifest(bytes);
758
+ let decoded;
396
759
  try {
760
+ decoded = decodeManifest(bytes);
397
761
  const parsed = JSON.parse(decoded.text);
398
762
  const packageDir = normalizePath(dirname(manifest.path));
399
763
  // The declared workspace name, so a yarn route can address the package the way both
@@ -413,7 +777,7 @@ async function readPackageScripts(root, files, diagnostics) {
413
777
  message: `Could not parse ${manifest.path}; scripts from that package were skipped.` +
414
778
  // Encoding is no longer a cause of failure, so naming it here rules it out rather
415
779
  // than sending someone to re-save a file whose real problem is a syntax error.
416
- (decoded.encoding === "utf8" ? "" : ` It was decoded as ${decoded.encoding}, so the problem is the JSON itself, not the encoding.`)
780
+ (!decoded || decoded.encoding === "utf8" ? "" : ` It was decoded as ${decoded.encoding}, so the problem is the JSON itself, not the encoding.`)
417
781
  });
418
782
  }
419
783
  }
@@ -431,49 +795,118 @@ function decodeManifest(bytes) {
431
795
  return { text: bytes.subarray(2).toString("utf16le"), encoding: "UTF-16LE" };
432
796
  }
433
797
  if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
434
- return { text: bytes.subarray(2).swap16().toString("utf16le"), encoding: "UTF-16BE" };
798
+ const body = bytes.subarray(2);
799
+ if (body.length % 2 !== 0) {
800
+ throw new Error("Truncated UTF-16BE input has an odd byte count");
801
+ }
802
+ return { text: Buffer.from(body).swap16().toString("utf16le"), encoding: "UTF-16BE" };
435
803
  }
436
804
  if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
437
805
  return { text: bytes.subarray(3).toString("utf8"), encoding: "UTF-8 with a byte order mark" };
438
806
  }
439
807
  return { text: bytes.toString("utf8"), encoding: "utf8" };
440
808
  }
441
- async function readDiff(repoRoot, diffSpec, diagnostics) {
809
+ async function readDiff(repoRoot, diffSpec, diagnostics, internalPaths) {
442
810
  if (!diffSpec) {
443
811
  return { changedFiles: [], diffText: "" };
444
812
  }
445
813
  try {
446
814
  const [{ stdout: names }, { stdout: diffText }] = await Promise.all([
447
- exec("git", ["diff", "--relative", "--name-only", diffSpec], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
448
- 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 })
449
817
  ]);
450
818
  const tracked = names
451
819
  .split(/\r?\n/)
452
820
  .map((path) => path.trim())
453
821
  .filter(Boolean)
454
822
  .map(normalizePath);
455
- const untracked = diffSpec.includes("..") ? [] : await listUntrackedPaths(repoRoot);
456
- return {
457
- changedFiles: [...new Set([...tracked, ...untracked])].sort((a, b) => a.localeCompare(b)),
458
- diffText: diffText.slice(0, MAX_DIFF_TEXT_CHARS)
459
- };
823
+ const untracked = diffSpec.includes("..") ? [] : await listUntrackedPaths(repoRoot, internalPaths);
824
+ const changedFiles = [...new Set([...tracked, ...untracked])].sort((a, b) => a.localeCompare(b));
825
+ diagnostics.push({
826
+ code: "diff-resolved",
827
+ severity: "info",
828
+ message: changedFiles.length === 0
829
+ ? `The diff "${truncateForDiagnostic(diffSpec, DIAGNOSTIC_SPEC_LIMIT)}" resolved to zero changed files, so results use the task text only. Paths are relative to the working directory; run from the repository root to include changes outside it.`
830
+ : `Diff "${truncateForDiagnostic(diffSpec, DIAGNOSTIC_SPEC_LIMIT)}" resolved ${changedFiles.length} changed ${changedFiles.length === 1 ? "path" : "paths"}.`,
831
+ paths: changedFiles.slice(0, 8)
832
+ });
833
+ return { changedFiles, diffText: sampleDiffText(diffText, diagnostics) };
460
834
  }
461
835
  catch (error) {
462
- // git echoes the failing command back, so its own message contains the spec a second
463
- // time. Truncating only the interpolation above would leave the full string in `detail`.
464
- const rawDetail = error instanceof Error ? error.message.split(/\r?\n/)[0] : "unknown git error";
465
- const detail = truncateForDiagnostic(rawDetail ?? "unknown git error", DIAGNOSTIC_SPEC_LIMIT * 2);
836
+ const checkoutState = isMissingGit(error) ? undefined : await describeGitCheckout(repoRoot);
837
+ const detail = truncateForDiagnostic(gitErrorDetail(error), DIAGNOSTIC_SPEC_LIMIT * 2);
466
838
  diagnostics.push({
467
839
  code: "diff-unavailable",
468
840
  severity: "warning",
469
- message: describesMissingRepository(error)
841
+ message: checkoutState === "not-repository"
470
842
  ? `Could not resolve git diff "${truncateForDiagnostic(diffSpec, DIAGNOSTIC_SPEC_LIMIT)}": ${NOT_A_GIT_CHECKOUT}`
471
- : `Could not resolve git diff "${truncateForDiagnostic(diffSpec, DIAGNOSTIC_SPEC_LIMIT)}": ` +
472
- `${detail}. Results use the task text only.`
843
+ : checkoutState === "no-history"
844
+ ? `Could not resolve git diff "${truncateForDiagnostic(diffSpec, DIAGNOSTIC_SPEC_LIMIT)}": ${NO_GIT_HISTORY}`
845
+ : `Could not resolve git diff "${truncateForDiagnostic(diffSpec, DIAGNOSTIC_SPEC_LIMIT)}": ` +
846
+ `${detail}. Results use the task text only.`
473
847
  });
474
848
  return { changedFiles: [], diffText: "" };
475
849
  }
476
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
+ }
477
910
  /**
478
911
  * "Map what I am touching right now."
479
912
  *
@@ -482,18 +915,18 @@ async function readDiff(repoRoot, diffSpec, diagnostics) {
482
915
  * scratch notes ranking beside the edit. Staged and unstaged tracked changes are what
483
916
  * "what I am working on" means; untracked files are a separate, opt-in question.
484
917
  */
485
- async function readWorkingTree(repoRoot, includeUntracked, diagnostics) {
918
+ async function readWorkingTree(repoRoot, includeUntracked, diagnostics, internalPaths) {
486
919
  try {
487
920
  const [{ stdout: names }, { stdout: diffText }] = await Promise.all([
488
- exec("git", ["diff", "--relative", "--name-only", "HEAD"], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER }),
489
- 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 })
490
923
  ]);
491
924
  const tracked = names
492
925
  .split(/\r?\n/)
493
926
  .map((path) => path.trim())
494
927
  .filter(Boolean)
495
928
  .map(normalizePath);
496
- const untracked = includeUntracked ? await listUntrackedPaths(repoRoot) : [];
929
+ const untracked = includeUntracked ? await listUntrackedPaths(repoRoot, internalPaths) : [];
497
930
  const changedFiles = [...new Set([...tracked, ...untracked])].sort((a, b) => a.localeCompare(b));
498
931
  diagnostics.push({
499
932
  code: "working-tree-diff",
@@ -506,17 +939,19 @@ async function readWorkingTree(repoRoot, includeUntracked, diagnostics) {
506
939
  `against HEAD${includeUntracked ? ", including untracked files" : " (untracked files are not counted as changed, though they still rank; pass --include-untracked to count them)"}.`,
507
940
  paths: changedFiles.slice(0, 8)
508
941
  });
509
- return { changedFiles, diffText: diffText.slice(0, MAX_DIFF_TEXT_CHARS) };
942
+ return { changedFiles, diffText: sampleDiffText(diffText, diagnostics) };
510
943
  }
511
944
  catch (error) {
512
- const rawDetail = error instanceof Error ? error.message.split(/\r?\n/)[0] : "unknown git error";
945
+ const checkoutState = isMissingGit(error) ? undefined : await describeGitCheckout(repoRoot);
513
946
  diagnostics.push({
514
947
  code: "diff-unavailable",
515
948
  severity: "warning",
516
- message: describesMissingRepository(error)
949
+ message: checkoutState === "not-repository"
517
950
  ? `Could not read the working tree: ${NOT_A_GIT_CHECKOUT}`
518
- : `Could not read the working tree: ${truncateForDiagnostic(rawDetail ?? "unknown git error", DIAGNOSTIC_SPEC_LIMIT * 2)}. ` +
519
- "Results use the task text only."
951
+ : checkoutState === "no-history"
952
+ ? `Could not read the working tree: ${NO_GIT_HISTORY}`
953
+ : `Could not read the working tree: ${truncateForDiagnostic(gitErrorDetail(error), DIAGNOSTIC_SPEC_LIMIT * 2)}. ` +
954
+ "Results use the task text only."
520
955
  });
521
956
  return { changedFiles: [], diffText: "" };
522
957
  }
@@ -529,43 +964,106 @@ async function readWorkingTree(repoRoot, includeUntracked, diagnostics) {
529
964
  */
530
965
  const NOT_A_GIT_CHECKOUT = "this directory is not a git checkout. Ranking still works from the task text; " +
531
966
  "--diff, --base/--head and --working-tree need a repository with history.";
967
+ const NO_GIT_HISTORY = "this repository has no commits yet, so there is nothing to diff against. " +
968
+ "Commit the initial work first, or run with --issue alone to rank from the task text.";
532
969
  /**
533
970
  * `execFile` puts "Command failed: git ..." in `message` and git's own explanation in
534
971
  * `stderr`, so matching on the message alone never saw the reason. Both are checked.
535
972
  */
536
- function describesMissingRepository(error) {
973
+ async function describeGitCheckout(root) {
974
+ try {
975
+ const { stdout } = await exec("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root, maxBuffer: GIT_MAX_BUFFER });
976
+ if (stdout.trim() !== "true")
977
+ return "not-repository";
978
+ }
979
+ catch {
980
+ return "not-repository";
981
+ }
982
+ try {
983
+ await exec("git", ["rev-parse", "--verify", "HEAD"], { cwd: root, maxBuffer: GIT_MAX_BUFFER });
984
+ return undefined;
985
+ }
986
+ catch {
987
+ return "no-history";
988
+ }
989
+ }
990
+ function gitErrorDetail(error) {
537
991
  const candidate = error;
538
- const text = [
539
- typeof candidate?.message === "string" ? candidate.message : "",
540
- typeof candidate?.stderr === "string" ? candidate.stderr : ""
541
- ].join("\n");
542
- return /not a git repository|does not have a commit checked out/i.test(text);
543
- }
544
- function detectPackageManager(files) {
545
- const paths = new Set(files.map((file) => file.path));
546
- if (paths.has("pnpm-lock.yaml") || paths.has("pnpm-workspace.yaml"))
547
- return "pnpm";
548
- if (paths.has("yarn.lock") || paths.has(".yarnrc.yml"))
549
- return "yarn";
550
- if (paths.has("bun.lock") || paths.has("bun.lockb"))
551
- return "bun";
992
+ if (candidate?.code === "ENOENT")
993
+ return "Git is not installed or is not available on PATH";
994
+ const stderr = typeof candidate?.stderr === "string" ? candidate.stderr : "";
995
+ const message = typeof candidate?.message === "string" ? candidate.message : String(error);
996
+ return stderr.split(/\r?\n/).find((line) => line.trim()) ?? message.split(/\r?\n/)[0] ?? "unknown git error";
997
+ }
998
+ function isMissingGit(error) {
999
+ return error?.code === "ENOENT";
1000
+ }
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
+ }
552
1024
  return "npm";
553
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
+ }
554
1039
  function classifyFile(path, extension) {
555
1040
  const lower = path.toLowerCase();
556
- 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/"))
557
1045
  return "documentation";
558
1046
  if (lower.startsWith(".github/") ||
559
1047
  [".json", ".yaml", ".yml"].includes(extension) ||
560
- /(^|\/)([^/]+\.)?(config|rc)\.[^/]+$/.test(lower))
1048
+ /(^|\/)(?:[^/]+\.config|\.[^/]*rc)\.[^/]+$/.test(lower))
561
1049
  return "config";
562
1050
  if (SOURCE_EXTENSIONS.has(extension))
563
1051
  return "code";
564
1052
  return "other";
565
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
+ }
566
1064
  async function readTextSample(path, sizeBytes) {
567
1065
  if (sizeBytes > MAX_TEXT_SAMPLE_BYTES) {
568
- return { text: "", complete: false };
1066
+ return { text: "", complete: false, skipReason: "too-large" };
569
1067
  }
570
1068
  try {
571
1069
  const bytes = await readFile(path);
@@ -575,18 +1073,19 @@ async function readTextSample(path, sizeBytes) {
575
1073
  // Reporting it as incomplete routes it through the same "content unavailable" handling
576
1074
  // as an oversized file.
577
1075
  if (bytes.includes(0)) {
578
- return { text: "", complete: false };
1076
+ return { text: "", complete: false, skipReason: "not-text" };
579
1077
  }
580
1078
  return { text: bytes.toString("utf8"), complete: true };
581
1079
  }
582
1080
  catch {
583
- return { text: "", complete: false };
1081
+ return { text: "", complete: false, skipReason: "unreadable" };
584
1082
  }
585
1083
  }
586
- async function listUntrackedPaths(repoRoot) {
1084
+ async function listUntrackedPaths(repoRoot, internalPaths = new Set()) {
587
1085
  try {
588
1086
  const { stdout } = await exec("git", ["ls-files", "--others", "--exclude-standard", "-z"], { cwd: repoRoot, maxBuffer: GIT_MAX_BUFFER });
589
- return stdout.split("\0").filter(Boolean).map(normalizePath);
1087
+ return stdout.split("\0").filter(Boolean).map(normalizePath)
1088
+ .filter((path) => !hasInternalPath(internalPaths, path));
590
1089
  }
591
1090
  catch {
592
1091
  return [];