code-archaeology

Code Archaeology

Purpose

Understand code history and context through git archaeology to answer "why", "who", and "when" questions about code.

Capabilities

• git blame analysis (who wrote this, when, why)
• git log --follow (track file renames and moves)
• Find related PRs/issues via commit messages
• Identify original author for questions
• Find test coverage for legacy code
• Understand evolution of APIs and patterns
• Detect dead code and deprecated patterns

Triggers

• "why was this written"
• "who owns this code"
• "when was this added"
• "history of this function"
• "find related PRs"
• "track this file's history"

Implementation

1. Git Blame Analysis

# Basic blame for a file
git blame <file>

# Blame with commit messages (more context)
git blame -s --date=short <file>

# Blame a specific line range
git blame -L <start>,<end> <file>

# Blame ignoring whitespace changes
git blame -w <file>

# Blame with full commit hash and author email
git blame -e <file>

# Example: Find who wrote a specific function
git blame -L $(grep -n "function myFunction" file.ts | cut -d: -f1),+20 file.ts

Output format:

a1b2c3d4 (John Doe 2024-03-15) export function myFunction() {
e5f6g7h8 (Jane Smith 2024-06-20)   // Updated to support new API
a1b2c3d4 (John Doe 2024-03-15)   return doSomething();
i9j0k1l2 (John Doe 2024-08-10) }

Interpretation:

• Original author: John Doe (2024-03-15)
• Modified by: Jane Smith (2024-06-20) - comment update
• Last touch: John Doe (2024-08-10) - closing brace (probably refactor)

2. Commit History Deep Dive

# Get commit details
git show <commit-hash>

# Get commit message and diff
git log -p <commit-hash> -1

# Find commit that introduced a line
git log -S "specific code string" --source --all

# Find commits that modified a function
git log -L :<function-name>:<file>

# Show evolution of a function
git log -p -L :<function-name>:<file>

3. Track File Renames and Moves

# Follow file history through renames
git log --follow --name-status -- <file>

# Show all renames
git log --follow --stat -- <file>

# Find when file was renamed
git log --follow --diff-filter=R -- <file>

# Example: Track a file that moved packages
git log --follow --oneline \
  x-pack/platform/packages/shared/kbn-agent-builder/src/core.ts

Output:

abc1234 refactor: move agent-builder to shared packages
def5678 feat: add agent-builder core functionality
ghi9012 initial commit

4. Find Related PRs and Issues

# Get commit message with PR/issue references
git log --grep="PR" --grep="#[0-9]" --oneline

# Find PR number from commit
git log --format="%H %s" | grep -E "#[0-9]+"

# Get PR details via gh CLI
commit_hash="abc1234"
pr_number=$(git log --format="%s" $commit_hash -1 | grep -oE "#[0-9]+" | head -1 | tr -d '#')
gh pr view $pr_number

# Find all PRs by an author
gh pr list --author john.doe --state all --limit 100

# Search PRs by keyword
gh pr list --search "agent builder" --state all

5. Identify Code Ownership

# Get primary contributors to a file
git log --format="%an" -- <file> | sort | uniq -c | sort -rn | head -5

# Get recent contributors (last 6 months)
git log --since="6 months ago" --format="%an" -- <file> | sort | uniq -c | sort -rn

# Check CODEOWNERS
grep -r "path/to/file" .github/CODEOWNERS

# Find team ownership in Kibana
# CODEOWNERS format: path/pattern @elastic/team-name
grep "x-pack/platform/packages/shared/kbn-agent-builder" .github/CODEOWNERS

Example output:

  45 John Doe
  23 Jane Smith
   8 Bob Johnson

Result: John Doe is primary owner (45 commits), Jane Smith is secondary (23 commits)

6. Find Test Coverage for Legacy Code

# Find test files for a source file
source_file="src/core/server/http_server.ts"
test_file="${source_file%.ts}.test.ts"

# Check if test exists
if [ -f "$test_file" ]; then
  echo "Unit test found: $test_file"
else
  echo "No unit test found"
fi

# Find integration tests (search for imports)
grep -r "$(basename $source_file .ts)" --include="*.integration.test.ts" .

# Find FTR tests (search for test descriptions)
grep -r "http server" x-pack/test/api_integration/

# Find Scout tests (search for test descriptions)
find . -name "*.scout.ts" -exec grep -l "http server" {} \;

# Check test coverage report (if exists)
cat target/kibana-coverage/jest/coverage-summary.json | \
  jq ".\"$(pwd)/$source_file\""

7. Detect Dead Code and Deprecations

# Find deprecated markers
grep -r "@deprecated" --include="*.ts" <path>

# Find TODO/FIXME markers with dates
grep -r "TODO\|FIXME" --include="*.ts" <path> | grep -E "[0-9]{4}"

# Find unused exports (requires ripgrep)
# 1. Extract all exports from a file
exports=$(grep -E "^export (const|function|class|interface|type)" <file> | \
  sed -E 's/export (const|function|class|interface|type) ([a-zA-Z0-9_]+).*/\2/')

# 2. Search for usage of each export
for export in $exports; do
  count=$(rg -l "import.*$export.*from" | wc -l)
  if [ $count -eq 0 ]; then
    echo "Unused export: $export"
  fi
done

# Find when code was marked deprecated
git log --all -S "@deprecated" -- <file>

8. Understand API Evolution

# Show all changes to a function signature
function_name="myFunction"
file="src/core.ts"

# Show line-by-line evolution
git log -L :$function_name:$file --oneline

# Show detailed evolution with diffs
git log -p -L :$function_name:$file

# Find when parameters were added
git log -p -S "function $function_name" -- $file

# Example output interpretation:
# commit abc123 (2024-01-15) - Initial implementation
# commit def456 (2024-03-20) - Added optional 'options' parameter
# commit ghi789 (2024-06-10) - Changed return type from string to Result<string>

Example Workflow

User: "why was this function written this way?"

Context: User is looking at a complex function with unusual implementation

Step 1: Get function location

file="x-pack/platform/packages/shared/kbn-agent-builder/src/core.ts"
func="executeAgentWorkflow"
line_num=$(grep -n "executeAgentWorkflow" $file | head -1 | cut -d: -f1)

Step 2: Blame the function

git blame -L $line_num,+50 $file
# Output shows commit abc123 (John Doe, 2024-03-15)

Step 3: Get commit details

git show abc123
# Output:
# commit abc123
# Author: John Doe <[email protected]>
# Date: 2024-03-15
#
# fix: handle async workflow execution race condition
#
# Previous implementation used Promise.all which caused race conditions
# when multiple workflows modified shared state. This change serializes
# execution while maintaining parallelism for independent workflows.
#
# Fixes #12345

Step 4: Find related PR

pr_num=$(git log --format="%s" abc123 -1 | grep -oE "#[0-9]+" | tr -d '#')
gh pr view $pr_num
# Output shows PR discussion with context

Step 5: Show evolution

git log -p -L :executeAgentWorkflow:$file
# Shows 3 previous versions:
# - v1 (2024-01-10): Simple Promise.all implementation
# - v2 (2024-02-15): Added error handling
# - v3 (2024-03-15): Current serialization approach (fixes race condition)

Step 6: Find ownership

git log --format="%an" -- $file | sort | uniq -c | sort -rn | head -3
# Output:
#   15 John Doe
#    5 Jane Smith
#    2 Bob Johnson

grep "kbn-agent-builder" .github/CODEOWNERS
# Output: x-pack/platform/packages/shared/kbn-agent-builder @elastic/platform-core

Final Answer:

Code Archaeology Report for executeAgentWorkflow()
====================================================

Original Author: John Doe ([email protected])
Date: 2024-03-15
Commit: abc123

Why Written This Way:
The function uses sequential execution (not Promise.all) to avoid race
conditions when multiple workflows modify shared state. This was changed
from a simpler parallel implementation after discovering a bug in
production (issue #12345).

Evolution:
- v1 (2024-01-10): Simple Promise.all for parallelism
- v2 (2024-02-15): Added error handling
- v3 (2024-03-15): Serialized execution to fix race condition

Related PR: #12346
Discussion highlights:
- Trade-off: Serialization reduces throughput but ensures correctness
- Alternative approaches were considered (locking, immutable state)
- Current approach chosen for simplicity and safety

Code Ownership:
- Primary: @elastic/platform-core
- Contact: John Doe (15 commits), Jane Smith (5 commits)

Recommendation:
If questioning this approach, read PR #12346 first. Consider consulting
John Doe or @elastic/platform-core before refactoring.

Advanced Techniques

Find When a Bug Was Introduced

# Use git bisect to find the commit that introduced a bug
git bisect start
git bisect bad HEAD  # Current version has the bug
git bisect good v7.0.0  # Version 7.0.0 was good

# Git will checkout commits for you to test
# After each test, run:
git bisect good  # if bug not present
# or
git bisect bad   # if bug present

# Git will narrow down to the exact commit
git bisect reset  # when done

Find All Places a Pattern Was Changed

# Find all commits that touched a specific pattern
git log -p -G "pattern|regex" -- <path>

# Example: Find all changes to error handling
git log -p -G "try.*catch" -- src/

# Example: Find all changes to a specific API call
git log -p -G "client\.search\(" -- x-pack/

Visualize File History

# Generate a visual timeline (requires gitk or tig)
gitk --follow <file>

# Or use tig (terminal UI)
tig --follow <file>

# Or generate markdown timeline
git log --follow --format="%h|%ad|%an|%s" --date=short -- <file> | \
  awk -F'|' '{print "- **" $2 "** " $3 ": " $4 " (commit: " $1 ")"}'

Integration with Other Skills

• spike-builder: Research existing patterns before implementing new features
• buildkite-ci-debugger: Find when CI config was last changed
• pr-optimizer: Identify reviewers based on code ownership

Quality Principles

• Always provide context, not just facts (why, not just who/when)
• Link to PRs/issues for deeper discussion
• Identify current code owners for follow-up questions
• Respect git history as documentation of intent

References

• Git blame docs: https://git-scm.com/docs/git-blame
• Git log filtering: https://git-scm.com/docs/git-log
• Kibana CODEOWNERS: .github/CODEOWNERS