Dev Archaeologist

Software archaeology and repository intelligence from Magnexis

Dev Archaeologist is a Magnexis-built Python CLI for excavating hidden technical debt, structural decay, and forgotten implementation artifacts in software repositories.

It treats every codebase like an archaeological dig site and helps you answer questions like:

• What code is ancient and likely abandoned?
• Where is the repository accumulating risk?
• Which files are structural weak points?
• What can be safely removed, refactored, or archived?
• How is the project evolving over time?

Project Overview

The tool scans a repository and turns the results into a rich, terminal-first excavation report.

It can surface:

• dead code
• ancient files
• TODO, FIXME, HACK, BUG, TEMP, and XXX markers
• duplicated logic
• unused assets and empty directories
• suspicious backup-style filenames
• oversized, complex "monster" files
• dependency hotspots and fragile chains
• architectural drift and release readiness issues
• remediation suggestions with estimated effort

The design goals are:

• strong terminal UX
• modular analyzers
• readable artifact reports
• release-friendly packaging
• future plugin support

Magnexis Brand

Dev Archaeologist is presented as part of the Magnexis tooling line.

Brand cues used in this repository:

• the archaeological emblem in the project logo
• the Magnexis name treatment in the README header
• the Magnexis mark used as a small brand seal
• a dedicated brand badge in the top badge row
• consistent earth-toned release and CLI styling

Installation

Install from PyPI:

pip install devarch

Install with optional extras:

pip install devarch[extended]
pip install devarch[release]
pip install devarch[test]

The release extra is useful if you want to build local distributions.

Quick Start

Run a full excavation over the current directory:

devarch scan .

List every available command:

devarch help

Generate a markdown report:

devarch export markdown

Generate a PDF report:

devarch report pdf

Release Artifacts

Dev Archaeologist includes a repeatable release build flow for local packaging and CI artifact generation.

Build the release bundle locally:

pip install .[release]
python scripts/build_release.py

This produces the following artifacts in dist/:

• devarch-0.2.0-py3-none-any.whl for the Python wheel
• devarch-0.2.0.tar.gz for the source distribution
• devarch-0.2.0-release.zip for the bundled release archive
• release-manifest.json for artifact metadata
• SHA256SUMS.txt for checksum verification

Command Reference

Core excavation

devarch scan .
devarch help
devarch ancient .
devarch dead-code .
devarch todos .
devarch duplicates .
devarch monsters .
devarch ruins .
devarch suspicious .
devarch inspect src/app.py
devarch trace auth
devarch evidence auth
devarch bugmark src/app.py --line 128
devarch errorcode "ModuleNotFoundError: No module named 'rich'"

Repository intelligence

devarch dependencies .
devarch genealogy .
devarch civilizations .
devarch debt .
devarch timeline .
devarch personality .
devarch forecast .
devarch explore .
devarch investigate .
devarch weaknesses .
devarch quake .
devarch architecture .
devarch contributors .
devarch mutations .
devarch map .
devarch survival .
devarch notes .

Forensic helpers

devarch investigate .
devarch inspect src/app.py
devarch trace auth
devarch evidence auth
devarch bugmark src/app.py --line 128
devarch errorcode "ModuleNotFoundError: No module named 'rich'"

Recovery and maintenance

devarch plan .
devarch delete-check src/legacy_auth.py
devarch refactor .
devarch routes .
devarch configs .
devarch migrations .
devarch deps .
devarch drift .
devarch pr-report .
devarch status .
devarch baseline .
devarch regressions .
devarch budget .
devarch release-check .
devarch ownership .
devarch dependency-health .
devarch cleanup .
devarch standards .
devarch history .
devarch recommend .
devarch prescribe .
devarch repair-plan .

Reporting

devarch export json
devarch export markdown
devarch export html
devarch report markdown
devarch report html
devarch report pdf

Output Philosophy

Each finding is designed to be actionable instead of just descriptive.

Typical output includes:

• problem
• evidence
• impact
• confidence
• recommended fix
• estimated effort
• risk level

That makes the tool useful not just for audits, but also for cleanup planning, code review, and release preparation.

Plugin Architecture

Dev Archaeologist exposes a lightweight plugin registry via the devarch.plugins entry-point group so future extensions can hook into the excavation pipeline.

Planned extension areas include:

• devarch-plugin-security
• devarch-plugin-ai
• devarch-plugin-performance

Development

Project layout:

devarch/
├── analyzers/
├── cli/
├── reports/
├── scanner/
├── utils/
└── tests/

Useful commands:

python -m pytest -q
python -m compileall devarch
python scripts/build_release.py

Repository Maintenance

The maintenance engine supports:

• baseline snapshots
• regression detection
• debt budgets
• release readiness checks
• ownership analysis
• dependency health monitoring
• cleanup recommendations
• standards checks
• health history
• remediation prescriptions

License

MIT