100+ AI Agents, Agent Skills and RAG Apps - Free and Open Source.
#!/usr/bin/env python3
"""Reconstruct why a file or line range exists from local git history.
Usage:
python3 archaeologist.py REPO FILE [--lines A-B] [--json]
Python 3.8+, stdlib only. Read-only and offline.
"""
import argparse
import json
import os
import re
import subprocess
import sys
from collections import Counter, defaultdict
LINE_RANGE_RE = re.compile(r"^([1-9][0-9]*)-([1-9][0-9]*)$")
ISSUE_RE = re.compile(r"(?<![\w/])(?:#[0-9]+|(?:pr|issue|gh)[\s:#-]*[0-9]+)", re.I)
INTENT_PATTERNS = (
("revert", re.compile(r"\brevert(?:ed|s|ing)?\b", re.I)),
("workaround", re.compile(r"\bwork[ -]?around\b", re.I)),
("temporary", re.compile(r"\b(?:temporary|temporarily|temp)\b", re.I)),
("todo", re.compile(r"\bTODO\b", re.I)),
)
class ArchaeologistError(Exception):
"""A user-facing validation or git error."""
def git(repo, args, required=True):
"""Run a read-only git command and return stdout."""
try:
result = subprocess.run(
["git", "-C", repo, *args],
capture_output=True,
timeout=30,
)
except FileNotFoundError as exc:
raise ArchaeologistError("git is not installed or is not on PATH") from exc
except subprocess.TimeoutExpired as exc:
raise ArchaeologistError("git command timed out") from exc
# Explicit UTF-8 decoding avoids locale-dependent failures on Windows and
# preserves carriage returns in NUL-delimited paths (text mode changes them).
stdout = result.stdout.decode("utf-8", errors="replace")
stderr = result.stderr.decode("utf-8", errors="replace")
if result.returncode != 0 and required:
detail = stderr.strip() or stdout.strip() or "git command failed"
raise ArchaeologistError(detail)
return stdout if result.returncode == 0 else ""
def normalize_inputs(repo_arg, file_arg):
repo_hint = os.path.abspath(os.path.expanduser(repo_arg))
if not os.path.isdir(repo_hint):
raise ArchaeologistError("repository path is not a directory: %s" % repo_arg)
root = git(repo_hint, ["rev-parse", "--show-toplevel"]).strip()
if not root:
raise ArchaeologistError("not a git repository: %s" % repo_arg)
root = os.path.abspath(root)
if os.path.isabs(file_arg):
candidate = os.path.abspath(os.path.expanduser(file_arg))
else:
candidate = os.path.abspath(os.path.join(root, file_arg))
try:
inside = os.path.commonpath([root, candidate]) == root
except ValueError:
inside = False
if not inside:
raise ArchaeologistError("file must be inside the repository")
relative = os.path.relpath(candidate, root).replace(os.sep, "/")
tracked = git(root, ["ls-files", "--error-unmatch", "--", relative], required=False)
if not tracked.strip():
raise ArchaeologistError("file is not tracked at HEAD: %s" % relative)
return root, relative
def parse_line_range(value):
if value is None:
return None
match = LINE_RANGE_RE.match(value)
if not match:
raise ArchaeologistError("line range must use positive A-B form, such as 40-72")
start, end = int(match.group(1)), int(match.group(2))
if start > end:
raise ArchaeologistError("line range start must not exceed its end")
return start, end
def validate_range(repo, path, line_range):
if line_range is None:
return
content = git(repo, ["show", "HEAD:%s" % path])
line_count = len(content.splitlines())
if line_range[1] > line_count:
raise ArchaeologistError(
"line range ends at %d, but %s has %d lines at HEAD"
% (line_range[1], path, line_count)
)
def history_hashes(repo, path, line_range):
if line_range:
selector = "%d,%d:%s" % (line_range[0], line_range[1], path)
output = git(repo, ["log", "--format=%H", "--no-patch", "-L", selector])
else:
output = git(
repo,
["log", "--format=%H", "--no-patch", "--follow", "--", path],
)
newest_first = [line.strip() for line in output.splitlines() if line.strip()]
hashes = []
seen = set()
for commit_hash in reversed(newest_first):
if commit_hash not in seen:
seen.add(commit_hash)
hashes.append(commit_hash)
if not hashes:
raise ArchaeologistError("no commits found for %s" % path)
return hashes
def classify_message(subject, body):
text = "%s\n%s" % (subject, body)
lowered = text.lower()
if subject.lower().startswith("merge "):
return "merge"
if re.search(r"\brevert(?:ed|s|ing)?\b", lowered):
return "revert"
if re.search(r"\bhot[ -]?fix\b", lowered):
return "hotfix"
if re.search(r"\b(refactor|cleanup|restructure|rename)\b", lowered):
return "refactor"
if re.search(r"\b(fix|fixed|fixes|bug|patch)\b", lowered):
return "fix"
if re.search(r"\b(feat|feature|add|added|introduce|implement)\b", lowered):
return "feat"
return "other"
def changed_file_details(repo, commit_hash):
output = git(
repo,
[
"diff-tree", "--root", "--no-commit-id", "--name-status", "-z", "-r",
"-M", commit_hash, "--",
],
)
paths = set()
renames = []
fields = iter(output.split("\0"))
for status in fields:
if not status:
continue
path = next(fields)
if status.startswith(("R", "C")):
new_path = next(fields)
paths.add(new_path)
if status.startswith("R"):
paths.add(path)
renames.append({"from": path, "to": new_path})
else:
paths.add(path)
return sorted(paths), renames
def intent_signals(commit_hash, subject, body):
text = "%s\n%s" % (subject, body)
signals = []
for match in ISSUE_RE.finditer(text):
signals.append({
"type": "issue_reference",
"commit": commit_hash,
"evidence": match.group(0),
"subject": subject,
})
for signal_type, pattern in INTENT_PATTERNS:
match = pattern.search(text)
if match:
signals.append({
"type": signal_type,
"commit": commit_hash,
"evidence": match.group(0),
"subject": subject,
})
return signals
def read_commit(repo, commit_hash):
fmt = "%H%x00%an%x00%ae%x00%aI%x00%s%x00%b"
raw = git(repo, ["show", "-s", "--format=%s" % fmt, commit_hash]).rstrip("\n")
parts = raw.split("\x00", 5)
if len(parts) != 6:
raise ArchaeologistError("could not parse commit metadata for %s" % commit_hash)
full_hash, author, email, date, subject, body = parts
signals = intent_signals(full_hash, subject, body)
files, renames = changed_file_details(repo, full_hash)
return {
"hash": full_hash,
"short_hash": full_hash[:12],
"author": author,
"email": email,
"date": date,
"subject": subject,
"body": body.strip(),
"category": classify_message(subject, body),
"changed_files": files,
"renames": renames,
"intent_signals": [signal["type"] for signal in signals],
}, signals
def blame_authors(repo, path, line_range):
args = ["blame", "--line-porcelain"]
if line_range:
args.extend(["-L", "%d,%d" % line_range])
args.extend(["HEAD", "--", path])
output = git(repo, args, required=False)
counts = Counter()
names = {}
current_name = ""
current_email = ""
for line in output.splitlines():
if line.startswith("author "):
current_name = line[7:]
elif line.startswith("author-mail "):
current_email = line[12:].strip("<>")
elif line.startswith("\t"):
if current_email:
key = current_email.lower()
counts[key] += 1
names[key] = (current_name, current_email)
current_name = ""
current_email = ""
return counts, names
def summarize_authors(repo, path, line_range, timeline):
line_counts, names = blame_authors(repo, path, line_range)
commit_counts = Counter()
for entry in timeline:
key = entry["email"].lower()
commit_counts[key] += 1
names.setdefault(key, (entry["author"], entry["email"]))
authors = []
for key in set(line_counts) | set(commit_counts):
name, email = names[key]
authors.append({
"name": name,
"email": email,
"current_lines": line_counts[key],
"timeline_commits": commit_counts[key],
})
return sorted(
authors,
key=lambda author: (
-author["current_lines"], -author["timeline_commits"],
author["name"].lower(), author["email"].lower(),
),
)
def historical_paths(path, timeline):
aliases = {path}
for entry in reversed(timeline):
for rename in entry["renames"]:
if rename["to"] in aliases:
aliases.add(rename["from"])
return aliases
def summarize_co_changes(path, timeline):
threshold = max(2, (len(timeline) + 2) // 3)
aliases = historical_paths(path, timeline)
commits_by_file = defaultdict(list)
for entry in timeline:
for changed in entry["changed_files"]:
if changed not in aliases:
commits_by_file[changed].append(entry["hash"])
co_changed = []
for changed, commits in commits_by_file.items():
if len(commits) >= threshold:
co_changed.append({
"file": changed,
"count": len(commits),
"commit_ratio": round(len(commits) / len(timeline), 3),
"commits": commits,
})
return (
threshold,
sorted(co_changed, key=lambda item: (-item["count"], item["file"])),
sorted(aliases),
)
def build_report(repo, path, line_range):
hashes = history_hashes(repo, path, line_range)
timeline = []
signals = []
for commit_hash in hashes:
entry, commit_signals = read_commit(repo, commit_hash)
timeline.append(entry)
signals.extend(commit_signals)
threshold, co_changed, aliases = summarize_co_changes(path, timeline)
return {
"region": {
"repo": repo,
"file": path,
"mode": "lines" if line_range else "file",
"lines": (
{"start": line_range[0], "end": line_range[1]}
if line_range else None
),
"co_change_threshold": threshold,
"historical_paths": aliases,
},
"introduced_by": timeline[0],
"timeline": timeline,
"co_changed": co_changed,
"authors": summarize_authors(repo, path, line_range, timeline),
"intent_signals": signals,
}
def print_human(report):
region = report["region"]
target = region["file"]
if region["lines"]:
target += ":%d-%d" % (
region["lines"]["start"], region["lines"]["end"],
)
intro = report["introduced_by"]
print("COMMIT ARCHAEOLOGIST: %s" % target)
print("Introduced by %s %s: %s" % (
intro["short_hash"], intro["author"], intro["subject"],
))
print("\nTIMELINE")
for entry in report["timeline"]:
print(" %s %-8s %s" % (
entry["short_hash"], entry["category"], entry["subject"],
))
print("\nREPEATED CO-CHANGES")
if report["co_changed"]:
for item in report["co_changed"]:
print(" %dx %s" % (item["count"], item["file"]))
else:
print(" none above threshold")
print("\nINTENT SIGNALS")
if report["intent_signals"]:
for signal in report["intent_signals"]:
print(" %s %s %s" % (
signal["commit"][:12], signal["type"], signal["evidence"],
))
else:
print(" none found in commit messages")
def main(argv=None):
parser = argparse.ArgumentParser(
description="Explain why a file or line range exists from local git history.",
)
parser.add_argument("repo", help="path to a local git repository")
parser.add_argument("file", help="tracked file path, relative to the repository")
parser.add_argument("--lines", metavar="A-B", help="current line range to trace")
parser.add_argument("--json", action="store_true", dest="as_json",
help="emit the structured dig report as JSON")
args = parser.parse_args(argv)
try:
repo, path = normalize_inputs(args.repo, args.file)
line_range = parse_line_range(args.lines)
validate_range(repo, path, line_range)
report = build_report(repo, path, line_range)
except ArchaeologistError as exc:
print("error: %s" % exc, file=sys.stderr)
return 2
if args.as_json:
print(json.dumps(report, indent=2, sort_keys=True))
else:
print_human(report)
return 0
if __name__ == "__main__":
sys.exit(main())