# Excavate

Excavate gives every repo a simple codebase health score, explains why it changed, and tells teams what to fix first.

## What It Does
Excavate scans JavaScript and TypeScript codebases using local git history and static analysis to surface technical debt risk by file.

## Why Git History?
Code risk is not only about how code looks today. Risk often appears in change behavior over time.

Excavate uses historical signals such as churn, temporal coupling, authorship concentration, and file survival to identify maintainability risks that style-only tools may miss.

## How Excavate Is Different
Traditional static analysis tools focus on source structure in the current snapshot.

Excavate complements tools like ESLint, SonarQube, and dependency scanners by adding historical repository signals:
- How often a file changes
- Which files repeatedly change together
- Where ownership is too concentrated
- Which files appear disconnected or unused

## Analysis Signals
- Git churn
- Test coverage gaps
- Code complexity
- Knowledge concentration risk
- Temporal coupling
- Documentation debt (TODO/FIXME/HACK markers)
- Orphan files
- Dead exports
- Dependency risk

## Example Output
Excavate reports can identify:
- High-churn files
- Load-bearing modules
- Temporal coupling pairs
- Orphan files
- Dead exports
- Knowledge concentration risks
- Repo-level health grade
- Plain-English improvement prompts

## Security and Privacy
- Analysis runs locally
- No source upload
- No telemetry requirement
- Works offline

## Audience
- Engineering leads
- Staff and principal engineers
- Software architects
- Platform and DevOps teams
- Compliance-focused engineering teams

## Research Background
Excavate is informed by research and practice in mining software repositories, code churn, temporal coupling, ownership concentration, and technical debt management.

## References
- Zimmermann, T., Zeller, A., Weissgerber, P., & Diehl, S. Mining Version Histories to Guide Software Changes.
- Nagappan, N., & Ball, T. Use of Relative Code Churn Measures to Predict System Defect Density.
- Gall, H., Hajek, K., & Jazayeri, M. Detection of Logical Coupling Based on Product Release History.
- Cataldo, M., Herbsleb, J. D., & Carley, K. M. Socio-Technical Congruence.
- Li, Z., Avgeriou, P., & Liang, P. A Systematic Mapping Study on Technical Debt and Its Management.

## Blog
- Index: https://tryexcavate.com/blog
- What is an Excavate Score: https://tryexcavate.com/blog/what-is-an-excavate-score
- Excavate CLI guide: https://tryexcavate.com/blog/excavate-your-codebase-laid-bare

## Links
- Website: https://tryexcavate.com
- NPM: https://www.npmjs.com/package/excavate
- GitHub: https://github.com/sonic-sabers/excavate
- Issues: https://github.com/sonic-sabers/excavate/issues
- Docs: https://github.com/sonic-sabers/excavate#readme