repodna 0.1.0

A GPLv3-only CLI that profiles codebases and generates a deterministic DNA signature.

RepoDNA

Created by Magnexis.

RepoDNA is GPLv3-only software.

RepoDNA is a terminal-first Python CLI that scans a codebase and turns it into a deterministic "DNA profile" you can read at a glance.

It is designed to answer questions like:

• What languages dominate this repo?
• Is this a frontend app, API, package, or monorepo?
• How complex is the structure really?
• What is the short fingerprint for this project?
• How similar are two codebases?

What It Does

RepoDNA scans a project directory and extracts:

• language mix
• file types
• folder patterns
• package manifests
• config files
• framework and stack signals
• route-like files
• monorepo hints
• complexity signals
• hotspots and findings

It then renders a concise report in the terminal and can export the full profile as JSON.

Core Commands

• repodna init . - create a starter repodna.toml
• repodna scan . - generate a profile report
• repodna compare ./a ./b - compare two projects
• repodna export report.json - export the latest scan profile
• repodna watch . - live rescan while files change
• repodna explain . - explain the detected classification
• repodna doctor - verify the installation and workspace health
• repodna validate profile.json - validate a saved RepoDNA export
• repodna --theme ocean scan . - switch the CLI theme on the fly

Install

pip install .

For local release packaging:

python -m flit build

RepoDNA installs a console script named repodna.

If you want to run from the repository without installing first:

python scripts/repodna.py --help

Entry Points

RepoDNA supports two practical ways to launch the CLI:

repodna --help
python -m repodna --help

The repo also includes:

scripts/repodna.py

That launcher is useful during development when you want a direct repo-local entrypoint.

Configuration

Run this to create a starting config file:

repodna init .

That creates repodna.toml with sensible defaults for ignore rules and scan limits.

Example configuration:

[scan]
ignore = [
  "node_modules",
  "dist",
  "build",
  ".next",
  "coverage",
]
include_hidden = false
max_depth = 12
max_file_size_bytes = 250000
max_files = 5000
top_n = 5
sample_lines = 5

[report]
title = "RepoDNA profile"

[ui]
theme = "midnight"

[hardening]
recommendations = [
  "Keep manifests and lockfiles committed intentionally.",
  "Exclude generated build outputs and cache directories.",
]

RepoDNA will also look for config and ignore files in parent directories, so you can run scans from nested folders without losing the repo-level rules. You can change the terminal look with --theme on the CLI or by setting [ui] theme in repodna.toml.

Available themes:

• midnight
• aurora
• ember
• ocean

Output Overview

The main scan report is intentionally structured for terminal readability:

• snapshot panel
• language table
• architecture table
• complexity summary
• findings panel
• hotspots panel
• recommendations panel

The report is rendered with rich, so it stays readable even in narrow terminals.

UI Preview Gallery

Below are real CLI previews from this project.

Actual Screenshots

These images were generated from the live CLI output in this repository.

Compare Mode

RepoDNA can compare two projects and summarize:

• shared traits
• differences
• architecture overlap
• complexity gap
• package manager differences
• dominant language differences

Example:

repodna compare ./project-a ./project-b

What the DNA Signature Means

The DNA signature is a compact fingerprint built from the strongest detected traits.

Examples:

• NEXT-TS-TAILWIND-SUPABASE-MEDIUM
• PYTHON-CLI-TYPER-PACKAGE-LIGHT
• CLI-TOOL-PYTHON-TOML-CLI-LIGHT

The intent is to make it easy to compare repos without reading the full report.

Hardening Notes

RepoDNA includes guardrails that make it safer to use on real repositories:

• .gitignore support
• ancestor config detection
• hidden-file toggles
• file size limits
• depth limits
• max file caps
• JSON export and validation
• health checks for packaging and launcher setup

The scanner is heuristic-based and intentionally deterministic.

Development

Useful commands while iterating locally:

python -m unittest discover -s tests -v
python -m repodna --no-brand doctor
python -m repodna --no-brand scan . --compact
python -m repodna --no-brand watch . --max-cycles 1 --compact

Project Layout

src/repodna/
  cli.py
  compare.py
  config.py
  models.py
  reporting.py
  scanner.py
  assets/magnexis-logo.png
scripts/repodna.py
tests/test_repodna.py

Notes

• Version 1 is heuristic-based and does not use AI.
• The Magnexis splash banner is optional via --no-brand.
• The CLI theme can be changed with --theme or [ui] theme in config.
• repodna watch . is available for live rescans while you edit a codebase.
• The project uses Flit for packaging and ships as a standard Python CLI.
• RepoDNA is licensed under GPL-3.0-only. See LICENSE for the full notice.