@repolensai/cli 0.1.1

package/lib/git-history.mjs

@@ -0,0 +1,1064 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function collectEvolutionReport(params) {
+  const { cwd, targetPath, sinceRef = null, limit = 20, exec } = params;
+  const scopedTrackedFiles = listScopedTrackedFiles(targetPath, exec);
+  const pathKind = resolvePathKind(cwd, targetPath, scopedTrackedFiles);
+  const follow = pathKind === "file" && shouldFollowPathHistory(cwd, targetPath);
+  const range = sinceRef ? `${sinceRef}..HEAD` : null;
+
+  const logArgs = ["log", "--date=short", "--format=%H%x09%ad%x09%an%x09%s"];
+  if (follow) {
+    logArgs.push("--follow");
+  }
+  if (range) {
+    logArgs.push(range);
+  }
+  logArgs.push("--", targetPath);
+
+  const commits = parseCommitLog(exec(logArgs, { allowFailure: true })).slice(0, limit);
+  const authorStats = summarizeAuthors(commits);
+
+  const numstatArgs = ["log", "--numstat", "--format=commit\t%H"];
+  if (follow) {
+    numstatArgs.push("--follow");
+  }
+  if (range) {
+    numstatArgs.push(range);
+  }
+  numstatArgs.push("--", targetPath);
+
+  const sortedFileStats = summarizeNumstat(parseNumstatLog(exec(numstatArgs, { allowFailure: true })))
+    .sort((left, right) => right.score - left.score || right.touchedCommits - left.touchedCommits || left.filePath.localeCompare(right.filePath));
+  const renameHistory = collectRenameHistory({
+    targetPath,
+    follow,
+    range,
+    exec,
+  });
+  const topFiles = sortedFileStats.slice(0, Math.min(limit, 5));
+  const directoryStats = pathKind === "directory"
+    ? summarizeDirectoryStats(sortedFileStats, targetPath).slice(0, Math.min(limit, 5))
+    : [];
+  const commitThemes = summarizeCommitThemes(commits, Math.min(limit, 4), [targetPath, ...topFiles.map((file) => file.filePath)]);
+
+  return {
+    targetPath,
+    pathKind,
+    sinceRef,
+    generatedAt: new Date().toISOString(),
+    trackedFileCount: scopedTrackedFiles.length,
+    commitCount: commits.length,
+    commits,
+    authors: authorStats,
+    fileStats: sortedFileStats.slice(0, 10),
+    topFiles,
+    directoryStats,
+    commitThemes,
+    whyChanged: buildWhyChangedSummary({
+      targetPath,
+      pathKind,
+      commitThemes,
+      renameHistory,
+      topOwner: authorStats[0] ?? null,
+      topFile: topFiles[0] ?? null,
+      topDirectory: directoryStats[0] ?? null,
+    }),
+    renameHistory,
+  };
+}
+
+export function collectHotspotReport(params) {
+  const { sinceRef = "HEAD~100", limit = 15, exec } = params;
+  const range = `${sinceRef}..HEAD`;
+  const raw = exec(["log", "--numstat", "--format=commit\t%H", range], { allowFailure: true });
+  const rows = summarizeNumstat(parseNumstatLog(raw))
+    .sort((left, right) => right.score - left.score || right.touchedCommits - left.touchedCommits)
+    .slice(0, limit);
+
+  return {
+    sinceRef,
+    generatedAt: new Date().toISOString(),
+    files: rows,
+  };
+}
+
+export function collectOwnershipReport(params) {
+  const { cwd, targetPath, sinceRef = null, limit = 10, exec } = params;
+  const scopedTrackedFiles = listScopedTrackedFiles(targetPath, exec);
+  const pathKind = resolvePathKind(cwd, targetPath, scopedTrackedFiles);
+  const follow = pathKind === "file" && shouldFollowPathHistory(cwd, targetPath);
+  const range = sinceRef ? `${sinceRef}..HEAD` : null;
+
+  const logArgs = ["log", "--date=short", "--format=%H%x09%ad%x09%an%x09%s"];
+  if (follow) {
+    logArgs.push("--follow");
+  }
+  if (range) {
+    logArgs.push(range);
+  }
+  logArgs.push("--", targetPath);
+
+  const commits = parseCommitLog(exec(logArgs, { allowFailure: true }));
+  const byAuthor = new Map();
+
+  for (const commit of commits) {
+    const current = byAuthor.get(commit.author) ?? {
+      author: commit.author,
+      commits: 0,
+      lastTouchedAt: commit.date,
+      lastSubject: commit.subject,
+    };
+
+    current.commits += 1;
+    if (!current.lastTouchedAt || commit.date > current.lastTouchedAt) {
+      current.lastTouchedAt = commit.date;
+      current.lastSubject = commit.subject;
+    }
+
+    byAuthor.set(commit.author, current);
+  }
+
+  const detailedNumstatArgs = ["log", "--date=short", "--numstat", "--format=commit\t%H\t%ad\t%an\t%s"];
+  if (follow) {
+    detailedNumstatArgs.push("--follow");
+  }
+  if (range) {
+    detailedNumstatArgs.push(range);
+  }
+  detailedNumstatArgs.push("--", targetPath);
+
+  const blameOwners = pathKind === "file" && shouldReadBlamePath(cwd, targetPath)
+    ? summarizeBlameOwners(parseBlamePorcelain(exec(["blame", "--line-porcelain", "--", targetPath], { allowFailure: true })))
+        .slice(0, limit)
+    : [];
+  const fileOwners = summarizeFileOwners(parseDetailedNumstatLog(exec(detailedNumstatArgs, { allowFailure: true }))).slice(0, limit);
+  const renameHistory = collectRenameHistory({
+    targetPath,
+    follow,
+    range,
+    exec,
+  }).slice(0, limit);
+
+  return {
+    targetPath,
+    pathKind,
+    sinceRef,
+    generatedAt: new Date().toISOString(),
+    trackedFileCount: scopedTrackedFiles.length,
+    owners: Array.from(byAuthor.values())
+      .sort((left, right) => right.commits - left.commits || left.author.localeCompare(right.author))
+      .slice(0, limit),
+    blameOwners,
+    fileOwners,
+    renameHistory,
+  };
+}
+
+export function collectStartHereReport(params) {
+  const { cwd, targetPath, sinceRef = null, limit = 5, exec } = params;
+  const evolution = collectEvolutionReport({
+    cwd,
+    targetPath,
+    sinceRef,
+    limit: Math.max(limit, 5),
+    exec,
+  });
+  const ownership = collectOwnershipReport({
+    cwd,
+    targetPath,
+    sinceRef,
+    limit: Math.max(limit, 5),
+    exec,
+  });
+  const readingOrder = buildReadingOrder({
+    targetPath,
+    pathKind: evolution.pathKind,
+    trackedFileCount: evolution.trackedFileCount,
+    commitCount: evolution.commitCount,
+    topFiles: evolution.topFiles,
+    directoryStats: evolution.directoryStats,
+    fileOwners: ownership.fileOwners,
+    renameHistory: evolution.renameHistory,
+    limit,
+  });
+
+  return {
+    targetPath,
+    pathKind: evolution.pathKind,
+    sinceRef,
+    generatedAt: new Date().toISOString(),
+    trackedFileCount: evolution.trackedFileCount,
+    summary: buildStartHereSummary({
+      pathKind: evolution.pathKind,
+      targetPath,
+      commitCount: evolution.commitCount,
+      authorCount: evolution.authors.length,
+      trackedFileCount: evolution.trackedFileCount,
+      topOwner: ownership.owners[0] ?? null,
+      topFile: evolution.topFiles[0] ?? null,
+    }),
+    commitThemes: evolution.commitThemes,
+    whyChanged: evolution.whyChanged,
+    readingOrder,
+    hotspotFiles: evolution.topFiles.slice(0, limit),
+    directoryStats: evolution.directoryStats.slice(0, limit),
+    owners: ownership.owners.slice(0, limit),
+    fileOwners: ownership.fileOwners.slice(0, limit),
+    recentCommits: evolution.commits.slice(0, limit),
+    renameHistory: evolution.renameHistory.slice(0, limit),
+  };
+}
+
+export function collectTraceReport(params) {
+  const { cwd, query, sinceRef = null, limit = 5, exec } = params;
+  const trackedFiles = exec(["ls-files"], { allowFailure: true })
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  const matches = collectTraceSignalMatches({ query, trackedFiles, exec });
+
+  const hotspotReport = collectHotspotReport({
+    sinceRef: sinceRef ?? "HEAD~100",
+    limit: Math.max(limit * 10, 25),
+    exec,
+  });
+  const hotspotScores = new Map(hotspotReport.files.map((file) => [file.filePath, file.score]));
+
+  const candidateMatches = mergeTraceMatches(matches)
+    .sort((left, right) => right.score - left.score || left.filePath.localeCompare(right.filePath))
+    .slice(0, Math.max(limit * 3, 10));
+
+  const enrichedMatches = candidateMatches.map((match) => {
+    const evolution = collectEvolutionReport({
+      cwd,
+      targetPath: match.filePath,
+      sinceRef,
+      limit: 5,
+      exec,
+    });
+    const ownership = collectOwnershipReport({
+      cwd,
+      targetPath: match.filePath,
+      sinceRef,
+      limit: 3,
+      exec,
+    });
+    const scoreBreakdown = buildTraceScoreBreakdown({
+      signalScores: match.signalScores,
+      hotspotScore: hotspotScores.get(match.filePath) ?? 0,
+      evolution,
+      ownership,
+    });
+
+    return {
+      filePath: match.filePath,
+      score: scoreBreakdown.total,
+      matchType: match.matchType,
+      matchSignals: match.matchSignals,
+      matchedLines: match.matchedLines,
+      scoreBreakdown,
+      evolution,
+      ownership,
+    };
+  });
+
+  return {
+    query,
+    sinceRef,
+    generatedAt: new Date().toISOString(),
+    matches: enrichedMatches
+      .sort((left, right) => right.score - left.score || left.filePath.localeCompare(right.filePath))
+      .slice(0, limit),
+  };
+}
+
+export function parseCommitLog(raw) {
+  return raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [sha, date, author, ...subjectParts] = line.split("\t");
+      return {
+        sha: sha ?? "",
+        date: date ?? "",
+        author: author ?? "",
+        subject: subjectParts.join("\t"),
+      };
+    })
+    .filter((entry) => entry.sha);
+}
+
+export function parseNumstatLog(raw) {
+  const entries = [];
+  let currentCommit = null;
+
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+
+    if (line.startsWith("commit\t")) {
+      currentCommit = line.slice("commit\t".length).trim();
+      continue;
+    }
+
+    const [added, deleted, filePath] = line.split("\t");
+    if (!currentCommit || !filePath) {
+      continue;
+    }
+
+    entries.push({
+      commit: currentCommit,
+      filePath,
+      additions: parseNumstatNumber(added),
+      deletions: parseNumstatNumber(deleted),
+    });
+  }
+
+  return entries;
+}
+
+export function parseBlamePorcelain(raw) {
+  const entries = [];
+  let current = null;
+
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+
+    if (/^[0-9a-f]{40}\s/.test(line)) {
+      if (current) {
+        entries.push(current);
+      }
+      const [commit] = line.split(" ");
+      current = {
+        commit,
+        author: "Unknown",
+        lineCount: 1,
+      };
+      continue;
+    }
+
+    if (!current) {
+      continue;
+    }
+
+    if (line.startsWith("author ")) {
+      current.author = line.slice("author ".length).trim() || "Unknown";
+      continue;
+    }
+  }
+
+  if (current) {
+    entries.push(current);
+  }
+
+  return entries;
+}
+
+export function parseGrepResults(raw) {
+  return raw
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+    .map((line) => {
+      const firstColon = line.indexOf(":");
+      const secondColon = firstColon >= 0 ? line.indexOf(":", firstColon + 1) : -1;
+      if (firstColon < 0 || secondColon < 0) {
+        return null;
+      }
+
+      const filePath = line.slice(0, firstColon);
+      const lineNumber = Number.parseInt(line.slice(firstColon + 1, secondColon), 10);
+      const preview = line.slice(secondColon + 1).trim();
+
+      if (!filePath || Number.isNaN(lineNumber)) {
+        return null;
+      }
+
+      return { filePath, lineNumber, preview };
+    })
+    .filter(Boolean);
+}
+
+export function parseNameStatusLog(raw) {
+  const entries = [];
+  let currentCommit = null;
+
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+
+    if (line.startsWith("commit\t")) {
+      currentCommit = line.slice("commit\t".length).trim();
+      continue;
+    }
+
+    if (!currentCommit) {
+      continue;
+    }
+
+    const [status, fromPath, toPath] = line.split("\t");
+    if (!status || !fromPath) {
+      continue;
+    }
+
+    entries.push({
+      commit: currentCommit,
+      status,
+      fromPath,
+      toPath: toPath ?? null,
+    });
+  }
+
+  return entries;
+}
+
+export function parseDetailedNumstatLog(raw) {
+  const entries = [];
+  let currentCommit = null;
+
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+
+    if (line.startsWith("commit\t")) {
+      const [, sha = "", date = "", author = "", ...subjectParts] = line.split("\t");
+      currentCommit = {
+        sha,
+        date,
+        author,
+        subject: subjectParts.join("\t"),
+      };
+      continue;
+    }
+
+    const [added, deleted, filePath] = line.split("\t");
+    if (!currentCommit || !filePath) {
+      continue;
+    }
+
+    entries.push({
+      commit: currentCommit.sha,
+      date: currentCommit.date,
+      author: currentCommit.author,
+      subject: currentCommit.subject,
+      filePath,
+      additions: parseNumstatNumber(added),
+      deletions: parseNumstatNumber(deleted),
+    });
+  }
+
+  return entries;
+}
+
+function summarizeAuthors(commits) {
+  const counts = new Map();
+
+  for (const commit of commits) {
+    counts.set(commit.author, (counts.get(commit.author) ?? 0) + 1);
+  }
+
+  return Array.from(counts.entries())
+    .map(([author, commitsCount]) => ({ author, commits: commitsCount }))
+    .sort((left, right) => right.commits - left.commits || left.author.localeCompare(right.author));
+}
+
+function summarizeNumstat(entries) {
+  const files = new Map();
+
+  for (const entry of entries) {
+    const current = files.get(entry.filePath) ?? {
+      filePath: entry.filePath,
+      additions: 0,
+      deletions: 0,
+      touchedCommits: 0,
+      score: 0,
+    };
+
+    current.additions += entry.additions;
+    current.deletions += entry.deletions;
+    current.touchedCommits += 1;
+    current.score = current.touchedCommits * 5 + current.additions + current.deletions;
+    files.set(entry.filePath, current);
+  }
+
+  return Array.from(files.values());
+}
+
+function summarizeBlameOwners(entries) {
+  const owners = new Map();
+
+  for (const entry of entries) {
+    const current = owners.get(entry.author) ?? {
+      author: entry.author,
+      lines: 0,
+      commits: new Set(),
+    };
+
+    current.lines += entry.lineCount;
+    current.commits.add(entry.commit);
+    owners.set(entry.author, current);
+  }
+
+  return Array.from(owners.values())
+    .map((owner) => ({
+      author: owner.author,
+      lines: owner.lines,
+      commits: owner.commits.size,
+    }))
+    .sort((left, right) => right.lines - left.lines || right.commits - left.commits || left.author.localeCompare(right.author));
+}
+
+function summarizeFileOwners(entries) {
+  const files = new Map();
+
+  for (const entry of entries) {
+    const current = files.get(entry.filePath) ?? {
+      filePath: entry.filePath,
+      authors: new Map(),
+      touchedCommits: new Set(),
+      additions: 0,
+      deletions: 0,
+      lastTouchedAt: "",
+      lastSubject: "",
+    };
+
+    current.authors.set(entry.author, (current.authors.get(entry.author) ?? 0) + 1);
+    current.touchedCommits.add(entry.commit);
+    current.additions += entry.additions;
+    current.deletions += entry.deletions;
+    if (!current.lastTouchedAt || entry.date > current.lastTouchedAt) {
+      current.lastTouchedAt = entry.date;
+      current.lastSubject = entry.subject;
+    }
+
+    files.set(entry.filePath, current);
+  }
+
+  return Array.from(files.values())
+    .map((entry) => {
+      const rankedAuthors = Array.from(entry.authors.entries())
+        .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+      const [primaryOwner = "Unknown", ownerCommits = 0] = rankedAuthors[0] ?? [];
+      return {
+        filePath: entry.filePath,
+        primaryOwner,
+        ownerCommits,
+        touchedCommits: entry.touchedCommits.size,
+        lastTouchedAt: entry.lastTouchedAt,
+        lastSubject: entry.lastSubject,
+        additions: entry.additions,
+        deletions: entry.deletions,
+      };
+    })
+    .sort((left, right) => right.touchedCommits - left.touchedCommits || right.ownerCommits - left.ownerCommits || left.filePath.localeCompare(right.filePath));
+}
+
+function summarizeCommitThemes(commits, limit = 3, hints = []) {
+  const tokenStats = new Map();
+
+  for (const commit of commits) {
+    const tokens = Array.from(new Set(extractThemeTokens(commit.subject)));
+    for (const token of tokens) {
+      const current = tokenStats.get(token) ?? {
+        token,
+        count: 0,
+        subjects: [],
+      };
+
+      current.count += 1;
+      current.subjects.push(commit.subject);
+      tokenStats.set(token, current);
+    }
+  }
+
+  const ranked = Array.from(tokenStats.values())
+    .filter((entry) => entry.count >= 2)
+    .sort((left, right) => right.count - left.count || left.token.localeCompare(right.token))
+    .slice(0, limit)
+    .map((entry) => ({
+      label: `${toTitleCase(entry.token)} changes`,
+      commits: entry.count,
+      examples: Array.from(new Set(entry.subjects)).slice(0, 2),
+    }));
+
+  if (ranked.length > 0) {
+    return ranked;
+  }
+
+  const hintedTokens = Array.from(new Set(hints.flatMap((hint) => extractThemeTokens(hint))));
+  if (hintedTokens.length > 0 && commits.length > 0) {
+    return hintedTokens.slice(0, limit).map((token) => ({
+      label: `${toTitleCase(token)} changes`,
+      commits: commits.length,
+      examples: commits.slice(0, 2).map((commit) => commit.subject),
+    }));
+  }
+
+  return commits.slice(0, limit).map((commit) => ({
+    label: commit.subject,
+    commits: 1,
+    examples: [commit.subject],
+  }));
+}
+
+function parseNumstatNumber(value) {
+  if (value === "-" || value == null) {
+    return 0;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+function scoreTraceMatch(filePath, query) {
+  const normalized = filePath.toLowerCase();
+  const basename = path.basename(normalized);
+  const stem = basename.includes(".") ? basename.slice(0, basename.indexOf(".")) : basename;
+
+  if (!query) {
+    return 0;
+  }
+
+  if (normalized === query) {
+    return 1000;
+  }
+
+  if (normalized.endsWith(`/${query}`)) {
+    return 800;
+  }
+
+  if (stem === query) {
+    return 760;
+  }
+
+  if (basename.startsWith(`${query}.`) || basename.startsWith(`${query}-`) || basename.startsWith(`${query}_`)) {
+    return 700;
+  }
+
+  if (normalized.includes(`/${query}/`)) {
+    return 660;
+  }
+
+  if (normalized.includes(query)) {
+    return 400 - Math.max(normalized.length - query.length, 0);
+  }
+
+  if (basename.includes(query)) {
+    return 300 - Math.max(basename.length - query.length, 0);
+  }
+
+  return 0;
+}
+
+function choosePrimaryTraceSignal(signalScores) {
+  if ((signalScores.definition ?? 0) > 0) {
+    return "definition";
+  }
+
+  if ((signalScores.symbol ?? 0) > 0) {
+    return "symbol";
+  }
+
+  if ((signalScores.content ?? 0) > 0) {
+    return "content";
+  }
+
+  return "path";
+}
+
+function dedupeMatchedLines(lines) {
+  const seen = new Set();
+  const deduped = [];
+
+  for (const line of lines) {
+    const key = `${line.filePath}:${line.lineNumber}:${line.preview}`;
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    deduped.push(line);
+  }
+
+  return deduped;
+}
+
+function isLikelySymbolQuery(query) {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(query);
+}
+
+function buildDefinitionRegex(query) {
+  const escaped = escapeRegex(query);
+  return `(^|[^[:alnum:]_])(export[[:space:]]+)?(async[[:space:]]+)?(function|class|interface|type|enum|const|let|var)[[:space:]]+${escaped}([^[:alnum:]_]|$)`;
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function mergeTraceMatches(matches) {
+  const merged = new Map();
+
+  for (const match of matches) {
+    const current = merged.get(match.filePath) ?? {
+      filePath: match.filePath,
+      score: 0,
+      matchType: match.matchType,
+      matchSignals: [],
+      signalScores: {
+        path: 0,
+        content: 0,
+        symbol: 0,
+        definition: 0,
+      },
+      matchedLines: [],
+    };
+
+    current.score = Math.max(current.score, match.score);
+    current.signalScores[match.matchType] = Math.max(current.signalScores[match.matchType] ?? 0, match.score);
+    current.matchSignals = Array.from(new Set([...current.matchSignals, match.matchType]));
+    current.matchType = choosePrimaryTraceSignal(current.signalScores);
+    current.matchedLines = dedupeMatchedLines([...current.matchedLines, ...(match.matchedLines ?? [])]).slice(0, 3);
+    merged.set(match.filePath, current);
+  }
+
+  return Array.from(merged.values());
+}
+
+function buildTraceScoreBreakdown({ signalScores, hotspotScore, evolution, ownership }) {
+  const pathScore = signalScores.path ?? 0;
+  const contentScore = signalScores.content ?? 0;
+  const symbolScore = signalScores.symbol ?? 0;
+  const definitionScore = signalScores.definition ?? 0;
+  const hotspotBonus = Math.min(hotspotScore, 120);
+  const historyBonus = Math.min(evolution.commitCount * 12, 60);
+  const ownershipBonus = Math.min((ownership.owners[0]?.commits ?? 0) * 8, 32);
+  const blameBonus = ownership.blameOwners.length > 0 ? Math.min(ownership.blameOwners[0].lines, 25) : 0;
+  const renameBonus = evolution.renameHistory.length > 0 ? 12 : 0;
+
+  return {
+    path: pathScore,
+    content: contentScore,
+    symbol: symbolScore,
+    definition: definitionScore,
+    hotspot: hotspotBonus,
+    history: historyBonus,
+    ownership: ownershipBonus,
+    blame: blameBonus,
+    rename: renameBonus,
+    total: pathScore + contentScore + symbolScore + definitionScore + hotspotBonus + historyBonus + ownershipBonus + blameBonus + renameBonus,
+  };
+}
+
+function collectTraceSignalMatches({ query, trackedFiles, exec }) {
+  const normalizedQuery = query.toLowerCase();
+  const pathMatches = trackedFiles
+    .map((filePath) => ({
+      filePath,
+      score: scoreTraceMatch(filePath, normalizedQuery),
+      matchType: "path",
+      matchedLines: [],
+    }))
+    .filter((entry) => entry.score > 0);
+
+  const contentMatches = parseGrepResults(
+    exec(["grep", "-n", "-I", "--full-name", "-e", query, "--", ...trackedFiles], { allowFailure: true })
+  ).map((entry) => ({
+    filePath: entry.filePath,
+    score: 500 + Math.max(60 - entry.lineNumber, 0),
+    matchType: "content",
+    matchedLines: [entry],
+  }));
+
+  const symbolMatches = isLikelySymbolQuery(query)
+    ? parseGrepResults(
+        exec(["grep", "-n", "-I", "--full-name", "-w", "-e", query, "--", ...trackedFiles], { allowFailure: true })
+      ).map((entry) => ({
+        filePath: entry.filePath,
+        score: 700 + Math.max(40 - entry.lineNumber, 0),
+        matchType: "symbol",
+        matchedLines: [entry],
+      }))
+    : [];
+
+  const definitionMatches = isLikelySymbolQuery(query)
+    ? parseGrepResults(
+        exec(["grep", "-n", "-I", "--full-name", "-E", "-e", buildDefinitionRegex(query), "--", ...trackedFiles], { allowFailure: true })
+      ).map((entry) => ({
+        filePath: entry.filePath,
+        score: 920 + Math.max(30 - entry.lineNumber, 0),
+        matchType: "definition",
+        matchedLines: [entry],
+      }))
+    : [];
+
+  return pathMatches.concat(contentMatches, symbolMatches, definitionMatches);
+}
+
+function collectRenameHistory({ targetPath, follow, range, exec }) {
+  const args = ["log", "--name-status", "--format=commit\t%H", "--find-renames"];
+  if (follow) {
+    args.push("--follow");
+  }
+  if (range) {
+    args.push(range);
+  }
+  args.push("--", targetPath);
+
+  return parseNameStatusLog(exec(args, { allowFailure: true }))
+    .filter((entry) => entry.status.startsWith("R") && entry.toPath)
+    .map((entry) => ({
+      commit: entry.commit,
+      fromPath: entry.fromPath,
+      toPath: entry.toPath,
+    }));
+}
+
+function listScopedTrackedFiles(targetPath, exec) {
+  return exec(["ls-files", "--", targetPath], { allowFailure: true })
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function resolvePathKind(cwd, targetPath, scopedTrackedFiles) {
+  try {
+    const absolute = path.resolve(cwd, targetPath);
+    if (fs.existsSync(absolute)) {
+      return fs.statSync(absolute).isDirectory() ? "directory" : "file";
+    }
+  } catch {
+    return inferPathKind(targetPath, scopedTrackedFiles);
+  }
+
+  return inferPathKind(targetPath, scopedTrackedFiles);
+}
+
+function inferPathKind(targetPath, scopedTrackedFiles) {
+  const normalizedTarget = normalizeGitPath(targetPath);
+  const prefix = normalizedTarget ? `${normalizedTarget}/` : "";
+
+  if (scopedTrackedFiles.some((filePath) => normalizeGitPath(filePath).startsWith(prefix))) {
+    return "directory";
+  }
+
+  if (scopedTrackedFiles.length === 1 && normalizeGitPath(scopedTrackedFiles[0]) === normalizedTarget) {
+    return "file";
+  }
+
+  return path.basename(targetPath).includes(".") ? "file" : "directory";
+}
+
+function summarizeDirectoryStats(fileStats, targetPath) {
+  const normalizedTarget = normalizeGitPath(targetPath);
+  const directoryBuckets = new Map();
+
+  for (const file of fileStats) {
+    const directoryPath = resolveDirectoryBucket(normalizedTarget, file.filePath);
+    if (!directoryPath) {
+      continue;
+    }
+
+    const current = directoryBuckets.get(directoryPath) ?? {
+      directoryPath,
+      fileCount: 0,
+      touchedCommits: 0,
+      additions: 0,
+      deletions: 0,
+      score: 0,
+    };
+
+    current.fileCount += 1;
+    current.touchedCommits += file.touchedCommits;
+    current.additions += file.additions;
+    current.deletions += file.deletions;
+    current.score += file.score;
+    directoryBuckets.set(directoryPath, current);
+  }
+
+  return Array.from(directoryBuckets.values())
+    .sort((left, right) => right.score - left.score || right.touchedCommits - left.touchedCommits || left.directoryPath.localeCompare(right.directoryPath));
+}
+
+function resolveDirectoryBucket(normalizedTarget, filePath) {
+  const normalizedFile = normalizeGitPath(filePath);
+  const relative = normalizedTarget && normalizedFile.startsWith(`${normalizedTarget}/`)
+    ? normalizedFile.slice(normalizedTarget.length + 1)
+    : normalizedFile;
+
+  if (!relative.includes("/")) {
+    return null;
+  }
+
+  const [firstSegment] = relative.split("/");
+  return normalizedTarget ? `${normalizedTarget}/${firstSegment}` : firstSegment;
+}
+
+function normalizeGitPath(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
+}
+
+function buildReadingOrder(params) {
+  const entries = [];
+
+  entries.push({
+    path: params.targetPath,
+    reason: params.pathKind === "directory"
+      ? `Start with the subsystem root. ${params.trackedFileCount} tracked files and ${params.commitCount} recent commits were found here.`
+      : "Start with the primary implementation file for this area.",
+  });
+
+  for (const directory of params.directoryStats) {
+    entries.push({
+      path: directory.directoryPath,
+      reason: `Highest churn subdirectory: ${directory.fileCount} files touched across ${directory.touchedCommits} commits.`,
+    });
+  }
+
+  for (const file of params.fileOwners) {
+    entries.push({
+      path: file.filePath,
+      reason: `Frequently changed file. Primary owner ${file.primaryOwner} drove ${file.ownerCommits} commits here.`,
+    });
+  }
+
+  for (const file of params.topFiles) {
+    entries.push({
+      path: file.filePath,
+      reason: `High-activity file with ${file.touchedCommits} commits and score ${file.score}.`,
+    });
+  }
+
+  for (const rename of params.renameHistory) {
+    entries.push({
+      path: rename.toPath,
+      reason: `Recently renamed from ${rename.fromPath}; review it to understand how the area moved.`,
+    });
+  }
+
+  return dedupeReadingOrder(entries).slice(0, params.limit);
+}
+
+function dedupeReadingOrder(entries) {
+  const seen = new Set();
+  const deduped = [];
+
+  for (const entry of entries) {
+    if (!entry.path || seen.has(entry.path)) {
+      continue;
+    }
+
+    seen.add(entry.path);
+    deduped.push(entry);
+  }
+
+  return deduped;
+}
+
+function buildStartHereSummary(params) {
+  const scope = params.pathKind === "directory"
+    ? `${params.trackedFileCount} tracked files`
+    : "the primary implementation file";
+  const ownerSummary = params.topOwner
+    ? `${params.topOwner.author} is the most frequent recent contributor`
+    : "ownership is spread across multiple contributors";
+  const fileSummary = params.topFile
+    ? `${params.topFile.filePath} is the highest-churn entry point`
+    : params.targetPath;
+
+  return `${params.targetPath} spans ${scope}, with ${params.commitCount} recent commits from ${params.authorCount} authors. ${ownerSummary}, and ${fileSummary} is the best first stop.`;
+}
+
+function buildWhyChangedSummary(params) {
+  const parts = [];
+
+  if (params.commitThemes.length > 0) {
+    parts.push(`Recent work clusters around ${params.commitThemes.slice(0, 2).map((theme) => theme.label.toLowerCase()).join(" and ")}.`);
+  }
+
+  if (params.renameHistory.length > 0) {
+    const latestRename = params.renameHistory[0];
+    parts.push(`The area was recently moved from ${latestRename.fromPath} to ${latestRename.toPath}.`);
+  }
+
+  if (params.topOwner) {
+    parts.push(`${params.topOwner.author} drove the highest share of recent changes.`);
+  }
+
+  if (params.pathKind === "directory" && params.topDirectory) {
+    parts.push(`Churn is concentrated in ${params.topDirectory.directoryPath}.`);
+  } else if (params.topFile) {
+    parts.push(`${params.topFile.filePath} is the highest-churn file in this scope.`);
+  }
+
+  return parts.join(" ");
+}
+
+function extractThemeTokens(subject) {
+  return subject
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length > 2 && !STOP_WORDS.has(token));
+}
+
+function toTitleCase(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+const STOP_WORDS = new Set([
+  "add",
+  "adds",
+  "added",
+  "and",
+  "area",
+  "build",
+  "change",
+  "changes",
+  "cleanup",
+  "create",
+  "fix",
+  "flow",
+  "initial",
+  "into",
+  "move",
+  "moves",
+  "moving",
+  "refactor",
+  "refine",
+  "rename",
+  "support",
+  "update",
+  "wire",
+]);
+
+function shouldFollowPathHistory(cwd, targetPath) {
+  try {
+    const absolute = path.resolve(cwd, targetPath);
+    if (!fs.existsSync(absolute)) {
+      return !targetPath.endsWith(path.sep) && path.basename(targetPath).includes(".");
+    }
+
+    return fs.statSync(absolute).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function shouldReadBlamePath(cwd, targetPath) {
+  try {
+    const absolute = path.resolve(cwd, targetPath);
+    return fs.existsSync(absolute) && fs.statSync(absolute).isFile();
+  } catch {
+    return false;
+  }
+}