Metadata-Version: 2.3
Name: spotregen
Version: 0.10.1
Summary: Regenerative Software tooling: check intent, evaluations and provenance of regenerable units, and drive regeneration
Author: bartzbeielstein
Author-email: bartzbeielstein <32470350+bartzbeielstein@users.noreply.github.com>
License: AGPL-3.0-or-later
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.13
Project-URL: Documentation, https://advm1.gm.fh-koeln.de/~bartz/spotregen/
Project-URL: Repository, https://git-ce.rwth-aachen.de/thomas.bartz-beielstein/spotregen
Project-URL: Issues, https://git-ce.rwth-aachen.de/thomas.bartz-beielstein/spotregen/-/issues
Description-Content-Type: text/markdown

# spotregen

Tooling for **Regenerative Software** in the sense of Chad Fowler: code is
disposable, the knowledge around it is the asset. A module is safely replaceable
when it can be deleted and rebuilt from knowledge that lives outside its
implementation. `spotregen` reads that knowledge from a tracked `regen/` tree and
checks it against the source tree.

* Standard library only: zero runtime dependencies, Python 3.13 or later.
* It never imports the modules it describes; it reads the source with `ast`.
* A deterministic static check (`spotregen check`) for `make guard`, plus reports
  (`status`, `deletion-test`, `context`, `compact`, `new-unit`), three measures
  (`measures` for intent coverage and specification size, `mutate` for the mutation score
  of one unit, `measures --mutation-score` for all three of every unit) and two
  non-deterministic drivers (`claude`, `local`) that regenerate a unit with an LLM.

## Install

```bash
uv add --dev spotregen
```

## Use

```bash
spotregen check [--strict]            # the static check: exit 1 on errors
spotregen status                      # units by pace and coverage
spotregen deletion-test UNIT          # blast radius and knowledge gaps
spotregen context UNIT [-o FILE]      # regeneration bundle, no bodies
spotregen compact                     # compaction candidates
spotregen measures [--mutation-score]  # intent coverage and specification size;
                                      # --mutation-score adds the score (slow: runs every mutant)
spotregen mutate UNIT [--out FILE]    # mutation score: planted mutants
spotregen new-unit MODULE --pace P --risk R [--dry-run]
spotregen gui                         # the graphical interface (tkinter, see below)
spotregen claude UNIT [...]           # regenerate with `claude -p` (needs claude)
spotregen local UNIT --model M [...]  # regenerate with a local LM Studio model
```

`--root DIR` selects the repository (default: search upwards for
`regen/architecture.toml`); `python -m spotregen` works as well. A repository
carries:

* `regen/architecture.toml`: the compilation target (allowed imports, accepted
  cycles, pace policy, conventions, scan directories).
* `regen/units/<unit>.toml`: one regenerable unit with intent, evaluations and
  consumers.
* `regen/decisions/<id>.toml`: provenance records.

## Graphical interface

`spotregen gui` (also `spotregen-gui` and `python -m spotregen.gui`) opens a window
with an Overview and a view for each command except the drivers: Check, Status,
Context, Deletion test, Compact, Measures and New unit, plus Runs, Mutate and Local for
the long-running jobs. It uses tkinter from the standard
library, so it adds no dependency, and it shows the exact command line under every
action. A Python without tkinter gets a message with the fix; Python builds managed by
`uv` include it. [QUICKSTART.md](QUICKSTART.md) walks through one example on the
sample repository. See [docs/gui.qmd](docs/gui.qmd) and
[ADR 0002](docs/adr/0002-graphical-interface.md).

The schema, the finding codes and the tutorials are in the documentation,
<https://advm1.gm.fh-koeln.de/~bartz/spotregen/>. A minimal repository for trying
it out is built by `spotregen.make_sample_repo`.

## Develop

```bash
make sync && make test-fast     # environment and fast tests
make verify                     # guard + lint + test + doc, the pre-release verification
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [RELEASING.md](RELEASING.md). The design
is recorded in [ADR 0001](docs/adr/0001-spotregen-package.md) and, for the graphical
interface, [ADR 0002](docs/adr/0002-graphical-interface.md).

## License

AGPL-3.0-or-later.
