Repo audit

Repository Audit

Audit a Git repository across nine categories and score each one. The report must show evidence and concrete next steps. The categories are independent, so run their diagnostic commands in parallel.

Common exclusions for all find/grep commands: .git, node_modules, .claude, __pycache__, .venv, vendor, dist, build, target.

Category Shortnames

Shortname	Category	Max
git	Repository & Git Health	15
structure	Project Structure & Organization	15
code	Code Quality	15
config	Config & Environment	10
data	Data & Database	10
docs	Documentation	10
testing	Testing & CI	15
deps	Dependencies & Packaging	5
security	Security	5

Audit Categories

1. Repository & Git Health (15 pts)

git rev-list --count HEAD
git log --oneline -20
git remote -v
git branch -a
git status
git stash list
git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | awk '/^blob/ {print $3, $4}' | sort -rn | head -20

Scoring:

• Remote configured (3 pts)
• Clean working tree (3 pts)
• Descriptive commit messages (3 pts)
• No unexplained blobs larger than 10 MB in history (3 pts)
• Sensible branching strategy (3 pts)

2. Project Structure & Organization (15 pts)

ls -la
find . -maxdepth 2 -type d -not -path './.git/*' | sort
find . -type f -not -path './.git/*' -not -path './.claude/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/.venv/*' -not -path '*/vendor/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/target/*' -print0 | xargs -0 ls -lhS 2>/dev/null | head -30

Scoring:

• Clear separation of concerns (4 pts)
• Logical module/directory naming (3 pts)
• No loose files that belong in subdirs (3 pts)
• Config/data/code properly separated (3 pts)
• No clutter such as temp files, old backups, or duplicates (2 pts)

3. Code Quality (15 pts)

Detect the primary language first, then run appropriate checks.

For any language:

# Line counts; only show files over 500 lines for review
find . -type f \( -name '*.py' -o -name '*.js' -o -name '*.ts' -o -name '*.go' -o -name '*.rs' -o -name '*.java' \) -not -path '*/node_modules/*' -not -path './.git/*' -not -path '*/.venv/*' -exec wc -l {} + | awk '$1 > 500' | sort -rn

Language-specific checks:

• Python: imports, docstrings ("""), type hints, TODO/FIXME/HACK markers
• JavaScript/TypeScript: ESLint config, JSDoc, console.log left in, any type usage
• Go: go vet, exported function docs, error handling patterns
• Rust: clippy warnings, unsafe blocks, documentation
• General: dead code indicators (pass, commented-out blocks), consistency

Scoring:

• No god files (> 500 lines without good reason) (3 pts)
• Consistent code style (3 pts)
• Documentation on public interfaces (3 pts)
• No dead code or commented-out blocks (3 pts)
• Type annotations or equivalent (3 pts)

4. Config & Environment (10 pts)

ls .env .env.example .gitignore requirements.txt package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
cat .gitignore 2>/dev/null

Scoring:

• Comprehensive .gitignore (3 pts)
• No credentials committed (3 pts). Run the sensitive-file scan from Category 9; if this category is running alone, run those commands here.
• .env.example or equivalent provided (2 pts)
• Proper packaging config present (2 pts)

5. Data & Database (10 pts)

find . \( -name '*.db' -o -name '*.sqlite' -o -name '*.sqlite3' \) -not -path './.git/*' -exec ls -lh {} \; 2>/dev/null
# Look for migration patterns
grep -rn 'CREATE TABLE\|ALTER TABLE\|migration\|schema_version' --include='*.py' --include='*.js' --include='*.ts' --include='*.go' --include='*.rs' --include='*.java' --include='*.sql' . 2>/dev/null | grep -v 'node_modules\|\.git' | head -20

Scoring:

• No stale/legacy databases checked in (3 pts)
• Migration system in place if DB exists (3 pts)
• Data files organized, not in root (2 pts)
• Reasonable DB sizes (2 pts)

If no database is used, award 10/10 and note "N/A: no database". Deduct only if stale data files or disorganized data are present.

6. Documentation (10 pts)

ls README.md CHANGELOG.md CONTRIBUTING.md LICENSE CLAUDE.md .cursorrules .github/copilot-instructions.md 2>/dev/null
wc -l README.md 2>/dev/null

Scoring:

• README with setup instructions (3 pts)
• LICENSE present (2 pts)
• CHANGELOG or version history (2 pts)
• Agent instructions such as CLAUDE.md (1 pt). Award if present; otherwise award and note "N/A" when the repository does not use Claude Code.
• Code-level documentation adequate (2 pts)

7. Testing & CI (15 pts)

find . \( -name 'test_*' -o -name '*_test.*' -o -name '*.test.*' -o -name '*_spec.*' -o -name 'conftest.py' \) -not -path '*/node_modules/*' -not -path './.git/*' -not -path '*/.venv/*' -not -path '*/vendor/*' -not -path '*/dist/*' -not -path '*/build/*' 2>/dev/null | head -20
ls -d .github/workflows/ .circleci/ .travis.yml Jenkinsfile .flake8 .pylintrc ruff.toml biome.json .pre-commit-config.yaml .husky/ 2>/dev/null; ls .eslintrc* 2>/dev/null

Scoring:

• Tests exist and cover core logic (5 pts)
• CI/CD pipeline configured (4 pts)
• Linting configured and enforced (3 pts)
• Pre-commit hooks or equivalent (3 pts)

8. Dependencies & Packaging (5 pts)

ls requirements.txt package-lock.json yarn.lock pnpm-lock.yaml Cargo.lock go.sum .python-version .nvmrc .tool-versions 2>/dev/null
head -20 requirements.txt 2>/dev/null

Scoring:

• All deps pinned with versions (2 pts)
• No unused dependencies (1 pt)
• Runtime version documented (1 pt)
• Lock file committed (1 pt)

9. Security (5 pts)

# Sensitive files anywhere in the repo (no depth limit)
find . \( -name 'credentials*' -o -name 'token*' -o -name '*.pem' -o -name '*.key' -o -name '.env' \) -not -path './.git/*' -not -path '*/node_modules/*' 2>/dev/null
# Hardcoded secrets patterns
grep -rnE '(api_key|password|secret|token)\s*[=:]\s*["\x27][^"\x27]{4,}' --include='*.py' --include='*.js' --include='*.ts' --include='*.go' --include='*.rs' --include='*.java' . 2>/dev/null | grep -v 'node_modules\|\.git\|test_\|_test\.\|\.example' | head -20
# Check permissions on sensitive files found above
find . \( -name '.env' -o -name '*.pem' -o -name '*.key' -o -name 'credentials*' \) -not -path './.git/*' -not -path '*/node_modules/*' -exec ls -la {} \; 2>/dev/null
# Check for secrets in git history
git log --diff-filter=A --name-only --pretty=format: | grep -iE '\.env$|\.pem$|\.key$|credentials|secret' | head -10

The sensitive-file scan also covers the credentials check in Category 4. Do not run it twice.

Scoring:

• No hardcoded secrets in code (2 pts)
• Sensitive files have restrictive permissions. Check ls -la; files such as .env, .pem, and .key should not be world-readable. (1 pt)
• No secrets in Git history. Check whether sensitive files were ever committed. (1 pt)
• No overly broad API scopes or credentials stored in plaintext config (1 pt)

Report Format

.-----------------------------------------------.
|          PROJECT HEALTH REPORT                 |
|          {repo-name}                           |
'-----------------------------------------------'

  OVERALL SCORE: XX / 100

  BREAKDOWN
  ---------------------------------------------
  Category                Score    Status
  ---------------------------------------------
  Repository & Git        __/15    [??????????]
  Project Structure       __/15    [??????????]
  Code Quality            __/15    [??????????]
  Config & Environment    __/10    [??????????]
  Data & Database         __/10    [??????????]
  Documentation           __/10    [??????????]
  Testing & CI            __/15    [??????????]
  Dependencies            __/5     [??????????]
  Security                __/5     [??????????]
  ---------------------------------------------

  TOP IMPROVEMENTS (by impact)
  ---------------------------------------------
  1. [+N pts] Description of improvement
     -> Concrete action to take

  2. [+N pts] Description of improvement
     -> Concrete action to take

  STRENGTHS
  ---------------------------------------------
  - Thing the project does well
  - Another strength

Progress bars: 10 chars wide. filled = round(score / max_score * 10). Use # for filled, - for empty.

Notes

• Be specific. Do not use vague findings such as "could be better."
• Each improvement must have a concrete next step
• Acknowledge what's already good
• This is read-only analysis. Never modify files.
• Auto-detect the primary language and adapt checks accordingly
• Skip categories that do not apply, such as database checks for a frontend-only project. Award full points and note "N/A."