Skip to main content

Audit a codebase

You just inherited a repository (or you're about to). This guide is the deterministic audit: ten minutes, no tribal knowledge required, every claim backed by file:line evidence.

0. Index once​

ovecc init          # optional: writes the commented config + .gitignore entry
ovecc index .

On large repositories, add --stats to see the per-phase breakdown, and use --exclude/--no-git to control scope — see index.

1. The one-screen picture​

$ ovecc summary
Files: 11
Modules: 6
Dependencies: 22
External dependencies: 6
Circular deps: 1
Boundary violations: 2
Coupling density: 26.67%
Risk score: High

Three numbers matter first: circular deps (architectural knots), coupling density (how entangled the modules are), and the composite risk score.

For a shareable version of everything below in one shot:

ovecc report --format markdown > architecture-report.md

2. Named architectural smells​

diagnose evaluates the component graph against established design principles and names what it finds — with evidence, a confidence, and a curated remediation:

[Medium] Cyclic Dependency — component-group src/core <-> src/services  (confidence 1.00)
  Principle: Acyclic Dependencies Principle
  Evidence: cycle_size=2 (>= 1), src/core/db.ts:2 — cycle_edge=1 (src/core -> src/services: ../services/billing), ...
  Fix: Break the cycle: invert one dependency or extract the shared core both sides depend on. [Dependency Inversion / Extract shared module]
  Action: break_cycle (auto-fixable: no)
  When not to act: Type-only/deferred imports are excluded; a tightly cohesive cluster may be intentional.

Note the When not to act line — diagnose tells you when a smell might be intentional instead of pretending everything is a defect.

3. The finding sweep​

Run the focused views in order of blast radius:

ovecc violations     # everything: architecture + security + quality, with file:line
ovecc security       # secrets, insecure patterns, weak crypto, tainted flows
ovecc audit --fetch  # known-vulnerable dependencies (the only networked command, opt-in)
ovecc health         # functions over the complexity thresholds
ovecc deadcode       # unused exports, unreachable files, phantom/unused dependencies
ovecc dupes          # duplicated code (clone families)

Each command supports --severity to cut noise and --format json|sarif|codeclimate for tooling. Details and real output for each: Findings commands.

4. Where does refactoring pay first?​

$ ovecc hotspots
1. services
   Score: 82
   Churn: 2
   Ownership fragmentation: 0%
   Coupling: 3 (fan-in 1, fan-out 2)
   Complexity: 2 (cognitive)
   Violations: 0
...

hotspots ranks modules by churn × coupling × ownership fragmentation × violations, normalized 0–100. A file nobody touches can be ugly in peace; a hotspot is where debt actually costs you.

5. Understand the structure​

ovecc query "cycles"            # actual elementary cycles with file:line witnesses
ovecc query "rdeps core"        # who depends on core?
ovecc impact services           # blast radius of touching services
ovecc explain core              # role, dependents, propagation paths, findings
ovecc export graph --html       # interactive offline dependency-graph viewer

The graph exploration guide covers these in depth.

6. Draw the baseline and ratchet​

You will not fix a legacy backlog in one PR. Accept the current state and fail builds only on new findings:

ovecc violations --write-baseline   # accept today's findings into .ovecc/baseline.json
ovecc violations --baseline         # from now on: only new findings are reported

Then wire the PR review loop so the backlog can only shrink.

The 10-minute audit, condensed​

ovecc index . && \
ovecc summary && \
ovecc diagnose && \
ovecc violations --severity medium && \
ovecc security && \
ovecc audit --fetch && \
ovecc hotspots --limit 5 && \
ovecc report --format markdown > report.md