git-diff-auditor

name

git-diff-auditor

description

Audit Git workspace changes (staged, unstaged, and untracked files) to produce a structured code review report. Analyzes diffs, detects cross-file reference inconsistencies (deleted fields/types/functions still referenced), checks Prisma schema vs API/component alignment, CSS vs DOM class alignment, and classifies issues by severity. Use when: (1) the user asks to audit, review, or code-review workspace changes, (2) there are uncommitted modifications that need risk assessment, (3) changes may have deleted fields, types, or functions that could still be referenced elsewhere, (4) the user wants a change-impact report or migration-risk analysis, (5) reviewing Prisma schema changes for API/frontend breakage, (6) evaluating CSS removals for orphaned DOM classes.

git-diff-auditor

Audit uncommitted Git workspace changes and generate a structured Markdown report.

Workflow

1. Discover Changes

Run the following to get the full change picture:

git status
git diff --stat
git diff
git diff --cached

Also list untracked files that are relevant (exclude node_modules, .next, build artifacts).

Record:

• Total files changed / added / deleted
• Lines added / removed summary
• List of modified files with change types

2. Analyze Each Modified File

For every modified file, read its git diff in detail. Identify:

Interface / Type / API Changes

• Deleted or renamed function parameters
• Deleted or renamed exported types / interfaces
• Changed function signatures
• Removed Prisma model fields or indexes
• Removed database columns (Prisma schema changes)

Component / DOM Changes

• Removed CSS classes — note the exact class names
• Removed React props — note the prop names
• Changed component prop interfaces

Data Semantics Changes

• Fields repurposed (e.g., className changing from "class" to "school")
• Hardcoded values replacing dynamic configuration
• Default value changes

3. Scan for Residual References

For every deleted / renamed / changed symbol identified in Step 2, search the entire codebase for residual references.

Use grep (ripgrep) to search:

grep -r "deletedFieldName" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.prisma" .

Pay special attention to:

• Files that import from the changed module but were NOT in the change list
• Prisma include / select queries referencing deleted relations
• TypeScript types consuming deleted interfaces
• CSS class names still used in JSX/HTML
• API routes passing deleted fields to Prisma create / update

4. Check Cross-Layer Consistency

Layer Pair	What to Check
Prisma Schema ↔ API Routes	Deleted fields still passed in prisma.model.create() / prisma.model.update()
Prisma Schema ↔ TypeScript Types	Generated Prisma types mismatch with manual types
API Response ↔ Frontend Components	Components expecting deleted props / fields
CSS ↔ Components	DOM classes with no matching CSS rules
URL Params ↔ Backend Filters	Query parameter names changed but backend parser not updated

5. Classify Issues

Assign every finding to one of three severity levels:

🔴 Blocker — Compile or Runtime Error

• TypeScript compilation failure
• Prisma runtime error (writing to non-existent columns)
• Missing import / unresolved symbol
• Function call with wrong arity

🟡 Data Compatibility — Silent Breakage

• Database field semantics changed without migration
• Existing data no longer matches new query filters
• Deleted fallback fields lose historical data display
• Enum / constant values changed but persisted data uses old values

🟢 Architecture — Maintainability Debt

• Hardcoded brand / config values
• Dead code (logic present but styles removed)
• Semantic mismatches (column name vs displayed label)
• Fragile reverse-lookup logic
• Missing data migration scripts

6. Generate Report

Write a Markdown report to reports/CODE_REVIEW_REPORT.md (create reports/ if needed).

Structure:

# Code Review Report

**Audit Date**: YYYY-MM-DD  
**Scope**: N files (M modified, A added, D deleted)  
**Total Δ**: +X / -Y lines

## 1. Change Overview

## 2. Blockers (Compile / Runtime Errors)

| # | File | Line | Issue | Evidence |
|---|------|------|-------|----------|

## 3. Data Compatibility Risks

| # | File | Issue | Impact |
|---|------|-------|--------|

## 4. Architecture Concerns

| # | File | Issue | Recommendation |
|---|------|-------|----------------|

## 5. Cross-File Reference Audit

List all symbols deleted/renamed and their residual references:
- `SymbolName` (deleted in `file.ts`) → still referenced in:
  - `other-file.ts:42`
  - `another.tsx:88`

## 6. Verdict

**Safe to merge?** Yes / No / With fixes

**Required before merge:**
- [ ] Fix blocker #1
- [ ] Fix blocker #2
- [ ] ...

**Recommended:**
- [ ] Data migration for ...
- [ ] Remove dead code in ...

7. Post-Report Actions

After generating the report:

• Offer to create a reports/ directory if not present
• Offer to add reports/ to .gitignore so audit artifacts are not committed
• If the user wants to reject changes, run git checkout -- . (after confirming which files to preserve)
• If the user wants to fix issues, iterate file-by-file

Guidelines

• Be exhaustive: scan the entire codebase, not just changed files, for residual references
• Show evidence: include exact file paths and line numbers in the report
• Distinguish severity: a TypeScript error is a blocker; a hardcoded string is architecture debt
• Check untracked files: they may contain new code that references deleted symbols
• Prisma awareness: schema changes are especially risky — always verify API routes, types, and queries
• CSS awareness: deleted CSS classes may leave invisible DOM elements or broken layouts