Diffsense-93

Make sense of what your AI coding session actually changed — semantically, not line-by-line.

Diffsense-93 analyzes your git changes after an AI coding session (Claude Code, Cursor, Copilot, Codex) and generates a structured, semantic report. Instead of scrolling through raw diffs, you get changes grouped by purpose, scored by risk, with a dependency audit and a clarity score telling you how much careful review is needed.

Quick Start

# Install globally
npm install -g diffsense-93

# Run in any git repo with uncommitted changes
diffsense-93

# Or analyze a specific commit range
diffsense-93 HEAD~3..HEAD

Sample Output

  Diffsense Session Report
  Branch: feat/auth-refactor

  Clarity Score: 62/100 ████████████░░░░░░░░
  8 files · 3 new entities · 2 API changes · 1 new deps

  8 files changed · +247 -89

  🔧  API Surface Changes  2 changes  🟡 Medium
    [modified] export handleAuth  src/auth/handler.ts:14
    [new] export validateToken  src/auth/validate.ts:1

  ✨  New Features  3 changes  🟢 Low
    [new] function getUserProfile  src/users/profile.ts:5
    [new] function formatUserData  src/users/format.ts:1
    [new] class ProfileCache  src/users/cache.ts:8

  📦 New Dependencies
    [email protected] (npm) — 3y 2mo old, 1.2M weekly downloads

  ── Other files (no AST analysis) ──

  📁  Configuration  2 files · +12 -3  🟢 Low
    tsconfig.json  +5 -1
    .env.example  +7 -2

Features

Semantic Change Grouping

Changes are clustered by purpose using tree-sitter AST analysis:

• API Surface Changes — modified or new exports
• New Features — added functions, classes, methods
• Refactored Code — modified internals with same API surface
• Import Changes — dependency graph modifications
• Test Changes — new or modified test code

For unsupported languages, files are grouped by path heuristics (tests, config, docs, dependencies).

Clarity Score (0–100)

A composite score reflecting session complexity:

• Higher score = more careful review needed
• Factors: files touched, new entities, API changes, new dependencies, high-risk changes
• Shown as a visual bar in the terminal and markdown reports

Risk Scoring

Each change group gets a risk level (Low / Medium / High / Critical) based on:

• File path patterns (auth, password, secret, migration)
• Dangerous function calls (eval, exec, dangerouslySetInnerHTML)
• Export/API surface modifications
• Security-sensitive code patterns

Dependency Audit

Newly added packages are automatically checked against the npm registry:

• Package age and weekly download count
• Flags for packages under 1 year old or under 100 weekly downloads
• Works for package.json, requirements.txt, and go.mod

Session Reports

Generate markdown reports to attach to PRs or save for reference:

diffsense-93 --report

Reports include all analysis sections plus an auto-generated review checklist.

CLI Reference

Usage: diffsense-93 [options] [commit-range]

Arguments:
  commit-range          Git commit range (e.g., HEAD~3..HEAD).
                        Defaults to uncommitted changes.

Options:
  -V, --version         Display version number
  --json                Output report as JSON
  --report              Generate a markdown session report
  --output <path>       Directory for markdown reports
                        (default: .diffsense/reports/)
  --quiet               Only print the clarity score
  --verbose             Show detailed debug output
  --cwd <path>          Path to git repository (default: cwd)
  -h, --help            Display help

Commands:
  init                  Install a post-commit git hook to
                        auto-generate session reports

Examples

# Analyze uncommitted changes
diffsense-93

# Analyze last 5 commits
diffsense-93 HEAD~5..HEAD

# Get JSON output for CI integration
diffsense-93 --json

# Generate markdown report in custom directory
diffsense-93 --report --output ./reports

# Just the clarity score (useful in scripts)
diffsense-93 --quiet

# Install auto-report git hook
diffsense-93 init

# Debug mode
diffsense-93 --verbose

How It Works

1. Git diff extraction — Uses simple-git to get the file-level diff with insertions/deletions per file.
2. AST parsing — For JS, TS, and Python files, uses web-tree-sitter to parse before/after versions and extract entities (functions, classes, imports, exports).
3. Entity diffing — Compares extracted entities to determine what was added, removed, or modified.
4. Classification — Groups changes semantically (API changes, new features, refactors) or by file-path heuristics for unsupported languages.
5. Risk scoring — Applies pattern-based rules to assign risk levels to each group.
6. Dependency audit — Detects newly added packages and queries the npm registry for metadata.
7. Report generation — Outputs to terminal (colored), JSON, or markdown.

Supported Languages (AST Analysis)

| Language | Functions | Classes | Imports | Exports | |------------|-----------|---------|---------|---------| | JavaScript | Yes | Yes | Yes | Yes | | TypeScript | Yes | Yes | Yes | Yes | | Python | Yes | Yes | Yes | — |

All other languages fall back to file-path heuristic classification — the tool is still useful, just without entity-level detail.

Contributing

1. Clone the repo
2. npm install
3. npm run dev to run the CLI in development mode
4. Make changes to src/
5. Test with npx tsx src/index.ts in a git repo with changes

License

MIT