Codebase Analysis

Codebase Analysis

Generate quantitative, language-agnostic analysis reports for any codebase. Reports are point-in-time snapshots saved as markdown in docs/codebase-analytics/.

When to Activate

• User asks to "analyze the codebase", "generate codebase report", or "profile the project"
• User wants an overview of project size, structure, dependencies, or complexity
• User asks about module coupling, dependency graphs, or largest files
• User says "codebase analytics" or "codebase analysis"

Prerequisites

cloc (required for stats report)

Check if installed:

which cloc

If not found, install it:

• macOS: brew install cloc
• npm: npm install -g cloc
• Debian/Ubuntu: sudo apt install cloc
• Red Hat/Fedora: sudo yum install cloc

git (required for all reports)

The project must be a git repository. All file discovery uses git ls-files or cloc --vcs=git to respect .gitignore and exclude generated/vendored files.

Reports

The skill produces up to 6 reports. The user can request all reports or specific ones.

Workflow

1. Initialize

If docs/codebase-analytics/ does not exist, create it with a README.md index.

2. Detect Project Structure

Before generating reports, understand the project layout:

1. Identify the primary language(s) — run cloc --vcs=git --quiet to see the language breakdown
2. Identify module boundaries — look for:
   • Package manifests: Package.swift, package.json, Cargo.toml, go.mod, build.gradle, pyproject.toml, *.csproj, pom.xml
   • Module directories: src/, lib/, packages/, modules/, features/, apps/
   • Test directories: tests/, test/, __tests__/, *Tests/, spec/
3. Identify dependency management — look for lock files and dependency declarations
4. Identify interface/implementation patterns — protocols, interfaces, abstract classes, traits

3. Generate Reports

For each requested report, follow the format specification below. Always include **Generated:** YYYY-MM-DD at the top of each report.

4. Update Index

After generating reports, update docs/codebase-analytics/README.md with links to all reports and a quick summary table.

Report Specifications

Stats (stats.md)

Data collection:

# Overall summary
cloc --vcs=git --quiet

# Per-module breakdown (adapt directory patterns to the project)
for dir in <module_dirs>; do
    name=$(basename "$dir")
    cloc --vcs=git "$dir" --include-lang=<primary_lang> --quiet --csv 2>/dev/null | grep '<primary_lang>' | awk -F, '{print $NF}'
done

Required sections:

1. Overall summary table (language, files, blank, comment, code)
2. Per-module source LOC breakdown (sorted by size descending)
3. Per-module test LOC breakdown
4. Distribution visualization (text-based bar chart)
5. Test coverage ratio by module (test LOC / source LOC)

Notes section explaining what was counted and what was excluded.

Dependency Graph (dependency-graph.md)

Data collection:

• Read all package manifests to extract declared dependencies
• For monorepos, map which internal modules depend on which

Required sections:

1. Module hierarchy with dependency levels (level 0 = no deps, level N = depends on level N-1)
2. ASCII dependency diagram showing direction of dependencies
3. Inter-module dependency table (what depends on what, why)
4. Key constraints (circular dependency prevention, layering rules)

Formatting:

• Use → for dependency direction
• Group by layer (foundation, infrastructure, feature, orchestrator)
• Note any circular or unusual dependencies

Third-Party Dependencies (third-party-dependencies.md)

Data collection:

• Parse package manifests for external dependency declarations
• Extract: package name, version constraint, URL/registry
• Check lock files for transitive dependencies

Required sections:

1. Direct dependencies table (name, version, URL, used in which modules, purpose)
2. Per-dependency description — what it does and why it was chosen
3. Transitive dependencies table (name, pulled by, purpose)
4. Dependency minimalism notes — what the project deliberately does NOT use externally and why

If ADRs exist for dependency choices, link to them.

Module Coupling (module-coupling.md)

Data collection:

# Count import/require/use statements per module
# Adapt the import pattern to the language:
#   Swift:      ^import ModuleName
#   TypeScript: ^import .* from ['"]module
#   Python:     ^(from module|import module)
#   Go:         "module/path"
#   Rust:       ^use crate::module
#   Java:       ^import package\.module

grep -r "^import " <module>/Sources/ | sort | uniq -c | sort -rn

Required sections:

1. Import frequency table by module (rows = importing module, columns = imported module)
2. Observations — which modules have unusually high or low coupling
3. Cross-module coupling — which modules import other same-level modules (horizontal coupling)
4. Coupling health summary table (metric, value, assessment)

Largest Files (largest-files.md)

Data collection:

git ls-files '*.<ext>' | xargs wc -l | sort -rn | head -25

Required sections:

1. Top 20 files by line count (rank, lines, file path, category)
2. Distribution by category (test, view/UI, model, service, etc.)
3. Notable source files (non-test) — the largest non-test files with brief descriptions of why they are large and whether they warrant attention

Service Inventory (service-inventory.md)

Applicability: Only generate this report if the codebase uses an interface/implementation pattern (protocols, interfaces, abstract classes, traits).

Data collection:

• Find all interface/protocol definitions
• For each, find implementations and test doubles
• Find dependency registration/wiring (DI container, module declarations)

Required sections:

1. Overview — total count, where interfaces/implementations/mocks live
2. Mapping table grouped by domain (name, implementation(s), mock, purpose)
3. Implementation patterns — naming conventions, multi-implementation services
4. Service directory layout (tree view of implementation files)

Output Directory Structure

docs/
└── codebase-analytics/
    ├── README.md                    ← Index with summary + regeneration commands
    ├── stats.md                     ← Lines of code
    ├── dependency-graph.md          ← Internal module DAG
    ├── third-party-dependencies.md  ← External packages
    ├── module-coupling.md           ← Import frequency analysis
    ├── largest-files.md             ← Complexity hotspots
    └── service-inventory.md         ← Interface-implementation mapping

README Index Format

# Codebase Analytics

Quantitative analysis of the codebase. These reports are point-in-time snapshots.

**Last updated:** YYYY-MM-DD

## Reports

| Report | Description |
|--------|-------------|
| [stats.md](stats.md) | Lines of code by language, directory, and module |
| [dependency-graph.md](dependency-graph.md) | Internal module dependency DAG |
| ... |

## Quick Summary

| Metric | Value |
|--------|-------|
| Total source LOC | X |
| Files | X |
| Modules | X |
| External dependencies | X |
| Test LOC ratio | X% |

## Regenerating

<shell commands to regenerate each report>

Guidelines

• Language-agnostic — adapt import patterns, file extensions, and package manifests to whatever language the project uses. Do not assume any specific language.
• Git-aware — always use --vcs=git or git ls-files to exclude generated files, build artifacts, and vendored dependencies.
• Point-in-time — every report includes the generation date. Reports become stale as the codebase evolves.
• Non-destructive — if reports already exist, regenerate them in place (overwrite with fresh data). Never delete reports the user may have manually edited without asking.
• Focused — the user can request a single report (e.g., "just the dependency graph") or all reports. Default to all when the user says "analyze the codebase".
• Actionable observations — don't just list data. Add brief observations highlighting unusual patterns, potential issues, or notable strengths.
• Link to other docs — if ADRs, feature docs, or architecture docs exist in the project, link to them where relevant.