export interface EvolutionCommit {
  sha: string;
  date: string;
  author: string;
  subject: string;
}

export interface EvolutionAuthorStat {
  author: string;
  commits: number;
}

export interface CommitTheme {
  label: string;
  commits: number;
  examples: string[];
}

export interface HotspotFileStat {
  filePath: string;
  additions: number;
  deletions: number;
  touchedCommits: number;
  score: number;
}

export interface DirectoryStat {
  directoryPath: string;
  fileCount: number;
  touchedCommits: number;
  additions: number;
  deletions: number;
  score: number;
}

export interface RenameHistoryEntry {
  commit: string;
  fromPath: string;
  toPath: string;
}

export interface OwnershipAuthorStat {
  author: string;
  commits: number;
  lastTouchedAt: string;
  lastSubject: string;
}

export interface BlameOwnerStat {
  author: string;
  lines: number;
  commits: number;
}

export interface FileOwnerStat {
  filePath: string;
  primaryOwner: string;
  ownerCommits: number;
  touchedCommits: number;
  lastTouchedAt: string;
  lastSubject: string;
  additions: number;
  deletions: number;
}

export interface ReadingOrderEntry {
  path: string;
  reason: string;
}

export interface TraceScoreBreakdown {
  path: number;
  content: number;
  symbol: number;
  definition: number;
  hotspot: number;
  history: number;
  ownership: number;
  blame: number;
  rename: number;
  total: number;
}

export interface TraceMatchLine {
  filePath: string;
  lineNumber: number;
  preview: string;
}

export function collectEvolutionReport(params: {
  cwd: string;
  targetPath: string;
  sinceRef?: string | null;
  limit?: number;
  exec: (args: string[], runtimeOptions?: { allowFailure?: boolean }) => string;
}): {
  targetPath: string;
  pathKind: "file" | "directory";
  sinceRef: string | null;
  generatedAt: string;
  trackedFileCount: number;
  commitCount: number;
  commits: EvolutionCommit[];
  authors: EvolutionAuthorStat[];
  fileStats: HotspotFileStat[];
  topFiles: HotspotFileStat[];
  directoryStats: DirectoryStat[];
  commitThemes: CommitTheme[];
  whyChanged: string;
  renameHistory: RenameHistoryEntry[];
};

export function collectHotspotReport(params: {
  sinceRef?: string;
  limit?: number;
  exec: (args: string[], runtimeOptions?: { allowFailure?: boolean }) => string;
}): {
  sinceRef: string;
  generatedAt: string;
  files: HotspotFileStat[];
};

export function collectOwnershipReport(params: {
  cwd: string;
  targetPath: string;
  sinceRef?: string | null;
  limit?: number;
  exec: (args: string[], runtimeOptions?: { allowFailure?: boolean }) => string;
}): {
  targetPath: string;
  pathKind: "file" | "directory";
  sinceRef: string | null;
  generatedAt: string;
  trackedFileCount: number;
  owners: OwnershipAuthorStat[];
  blameOwners: BlameOwnerStat[];
  fileOwners: FileOwnerStat[];
  renameHistory: RenameHistoryEntry[];
};

export function collectStartHereReport(params: {
  cwd: string;
  targetPath: string;
  sinceRef?: string | null;
  limit?: number;
  exec: (args: string[], runtimeOptions?: { allowFailure?: boolean }) => string;
}): {
  targetPath: string;
  pathKind: "file" | "directory";
  sinceRef: string | null;
  generatedAt: string;
  trackedFileCount: number;
  summary: string;
  commitThemes: CommitTheme[];
  whyChanged: string;
  readingOrder: ReadingOrderEntry[];
  hotspotFiles: HotspotFileStat[];
  directoryStats: DirectoryStat[];
  owners: OwnershipAuthorStat[];
  fileOwners: FileOwnerStat[];
  recentCommits: EvolutionCommit[];
  renameHistory: RenameHistoryEntry[];
};

export function collectTraceReport(params: {
  cwd: string;
  query: string;
  sinceRef?: string | null;
  limit?: number;
  exec: (args: string[], runtimeOptions?: { allowFailure?: boolean }) => string;
}): {
  query: string;
  sinceRef: string | null;
  generatedAt: string;
  matches: Array<{
    filePath: string;
    score: number;
    matchType: string;
    matchSignals: string[];
    matchedLines: TraceMatchLine[];
    scoreBreakdown: TraceScoreBreakdown;
    evolution: ReturnType<typeof collectEvolutionReport>;
    ownership: ReturnType<typeof collectOwnershipReport>;
  }>;
};

export function parseCommitLog(raw: string): EvolutionCommit[];
export function parseNumstatLog(raw: string): Array<{
  commit: string;
  filePath: string;
  additions: number;
  deletions: number;
}>;
export function parseBlamePorcelain(raw: string): Array<{
  commit: string;
  author: string;
  lineCount: number;
}>;
export function parseGrepResults(raw: string): TraceMatchLine[];
export function parseNameStatusLog(raw: string): Array<{
  commit: string;
  status: string;
  fromPath: string;
  toPath: string | null;
}>;
export function parseDetailedNumstatLog(raw: string): Array<{
  commit: string;
  date: string;
  author: string;
  subject: string;
  filePath: string;
  additions: number;
  deletions: number;
}>;