Metadata-Version: 2.4
Name: repodna
Version: 0.1.0
Summary: A GPLv3-only CLI that profiles codebases and generates a deterministic DNA signature.
Keywords: cli,codebase,scanner,analysis,typer,rich
Author: RepoDNA
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
License-File: LICENSE
Requires-Dist: Pillow>=10
Requires-Dist: pathspec>=0.12
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Requires-Dist: tomli; python_version < '3.11'
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: build ; extra == "dev"
Requires-Dist: twine ; extra == "dev"
Requires-Dist: pytest ; extra == "test"
Project-URL: Homepage, https://github.com/repodna/repodna
Project-URL: Issues, https://github.com/repodna/repodna/issues
Project-URL: Repository, https://github.com/repodna/repodna
Provides-Extra: dev
Provides-Extra: test

# RepoDNA

<img src="src/repodna/assets/magnexis-logo.png" alt="Magnexis Logo" width="120">

[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
[![Packaging: Flit](https://img.shields.io/badge/Packaging-Flit-7a5cff)](https://flit.pypa.io/)
[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-green)](LICENSE)
[![Built by Magnexis](https://img.shields.io/badge/Built%20by-Magnexis-ff8a00)](#)

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

```bash
pip install .
```

For local release packaging:

```bash
python -m flit build
```

RepoDNA installs a console script named `repodna`.

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

```bash
python scripts/repodna.py --help
```

## Entry Points

RepoDNA supports two practical ways to launch the CLI:

```bash
repodna --help
python -m repodna --help
```

The repo also includes:

```bash
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:

```bash
repodna init .
```

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

Example configuration:

```toml
[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.

![RepoDNA help screenshot](docs/screenshots/help.png)

![RepoDNA doctor screenshot](docs/screenshots/doctor.png)

![RepoDNA scan screenshot](docs/screenshots/scan.png)

![RepoDNA watch screenshot](docs/screenshots/watch.png)

## Compare Mode

RepoDNA can compare two projects and summarize:

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

Example:

```bash
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:

```bash
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

```text
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`](LICENSE) for the full notice.

