Function reference
Reading the spec
Parse the regen/ tree of a repository into frozen dataclasses.
| spec.load_spec | Read the whole regen/ tree below root. |
| spec.load_architecture | Read regen/architecture.toml. |
| spec.load_unit | Read one regen/units/<unit>.toml file. |
| spec.load_decision | Read one regen/decisions/<id>.toml provenance record. |
| spec.find_repo_root | Walk up from start to the first directory that holds regen/architecture.toml. |
| spec.resolve_unit | Find a unit by its dotted name or by a unique suffix of it. |
| spec.RegenSpec | Everything under regen/: the architecture, the units and the decisions. |
| spec.Architecture | The compilation target every regenerated module must fit into. |
| spec.Unit | A regenerable unit: one module plus the knowledge needed to rebuild it. |
| spec.IntentItem | One intent item of a unit, in the three parts of Fowler, Regenerative Software, ch. 3. |
| spec.Consumer | Something that depends on a unit and would notice its deletion. |
| spec.Decision | A provenance record: why the system has a particular shape. |
| spec.Alternative | A rejected option of a decision, kept because negative knowledge is the most fragile. |
| spec.SpecError | A file under regen/ is missing a field or holds a value outside its vocabulary. |
| spec.locate | Find the line of a TOML key such as id = "C-1" in a file. |
Checks
The static check: architecture, units and decisions against the source tree.
| checks.run_checks | Run every check: architecture, all units, all decisions. |
| checks.check_architecture | Check every package import under the source directory against the allowed dependencies. |
| checks.check_unit | Check one unit against its implementation, its evaluations and its consumers. |
| checks.check_decisions | Check every provenance record: evidence resolves, review dates, orphans. |
| checks.Finding | One result of a check. |
| checks.exit_code | The exit code of spotregen check for a list of findings. |
| checks.summary_line | The last line of spotregen check: units, errors and warnings. |
| scan.find_importers | Every file below root that depends on the module unit. |
Reports and drafts
Markdown reports, the regeneration bundle, compaction candidates and unit drafts.
| reports.status_table | All units with pace, risk, intent count, evaluation coverage and consumer count. |
| reports.status_rows | All units with pace, risk, intent count, evaluation coverage and consumer count. |
| reports.UnitStatus | One row of the status table: a unit with its coverage figures. |
| reports.deletion_report | Fowler’s deletion test for one unit, as Markdown. |
| reports.deletion_test | Fowler’s deletion test for one unit: the report and the verdict. |
| reports.DeletionResult | The outcome of the deletion test of one unit. |
| context.public_contract | The public contract of a unit: module docstring, signatures and docstrings, no bodies. |
| context.build_context | The regeneration bundle of one unit, as Markdown. |
| compact.compaction_report | The sediment of the spec: what could be removed, merged or has to be re-examined. |
| compact.compaction_summary | The summary line of spotregen compact. |
| scaffold.scaffold_unit | Draft regen/units/<unit>.toml for a module that has no unit record yet. |
| scaffold.write_unit | Write the draft of scaffold_unit to disk, reload it and check it. |
| scaffold.unrecorded_modules | The modules below the source directory that have no unit record yet. |
Measures
Intent coverage and specification size (read from the files), and the mutation score (planted mutants; runs the evaluations, never part of make guard).
| measures.unit_measures | Measure the intent coverage and the specification size of one unit. |
| measures.measures_table | Intent coverage and specification size of every unit, as a Markdown table. |
| measures.total_measures | Add the measures of several units into one row named total. |
| measures.measure_units | The measures of every unit, ordered by name: the rows of spotregen measures. |
| measures.measure_cells | The cells of one row of the measures table, as spotregen measures prints them. |
| measures.UnitMeasures | Intent coverage and specification size of one unit. |
| mutation.mutation_score | Run the unit’s evaluations against every mutant of its module. |
| mutation.generate_mutants | All mutants of a module, in source order. |
| mutation.score_markdown | The surviving mutants and the mutation score, as Markdown. |
| mutation.score_toml | The full result as TOML, one [[mutant]] table per mutant, for archiving. |
| mutation.ScoreReport | Mutation score of one unit. |
| mutation.MutantResult | The outcome of running the evaluations against one mutant. |
| mutation.Mutant | One planted change of a module. |
Sample repository
A minimal consistent repository for tests, examples and tutorials.
| sample.make_sample_repo | Write a minimal, consistent repository below root. |
Command line
| cli.main | Run the spotregen command line. |
| parser.build_parser | Build the argument parser of the spotregen command line. |
| parser.command_parser | The parser of one subcommand, with every option a front end can render. |
Graphical interface
The tkinter interface (spotregen gui). Only spotregen.gui._tk imports tkinter, so everything listed here works without a display.
| gui.main | Open the graphical interface. |
| gui.model.load_repository | Load the regen/ tree of a repository; a failure is a state, not an exception. |
| gui.model.RepoState | A repository the interface has tried to open. |
| gui.model.initial_root | Which repository to open at start. |
| gui.model.run_check | Run every check, as spotregen check does. |
| gui.model.CheckResult | The outcome of spotregen check on a loaded spec. |
| gui.model.build_overview | Answer the three questions of the first screen. |
| gui.model.Overview | The answers of the first screen. |
| gui.model.NextAction | One suggested next step on the Overview. |
| gui.model.filter_findings | Select the findings the Check view shows. |
| gui.model.finding_location | Where to open a finding and how to label it. |
| gui.model.Location | Where to open a finding. |
| gui.model.cli_argv | The arguments of a spotregen command, as spotregen.cli.main takes them. |
| gui.model.display_command | The command line to show under a button and to copy. |
| gui.model.complete_path | Complete a directory path the way a shell does on Tab. |
| gui.model.run_directory | The directory a job writes to: regen/runs/<date>-<unit>-<label>. |
| gui.model.create_run_directory | Create the directory a job writes to, atomically: no two jobs share one. |
| gui.model.unit_names | The names of the units, sorted: what the unit pickers offer. |
| gui.model.verdict_label | The words of the verdict badge of a deletion test. |
| gui.model.default_timeout | The default of measures --timeout, read from the command line parser. |
| gui.model.job_argv | The argument list that runs a spotregen command in a child process. |
| gui.model.resolve_path | The file a typed path names: ~ is expanded and a relative path is below root. |
| gui.model.context_save_path | Where Save puts the context bundle by default: regen/runs/<date>-<unit>-context.md. |
| gui.model.write_text_file | Write a text file as UTF-8, the way spotregen context -o does. |
| gui.model.inside_repository | Whether a file lies below the repository root (symbolic links resolved). |
| gui.model.FormError | An entry of a form cannot be turned into an option. |
| gui.model.FormField | One option of a command, as the form shows it. |
| gui.model.MutationScore | The result of spotregen mutate, read from its score.toml. |
| gui.model.RunInfo | One directory below regen/runs/, as the Runs view lists it. |
| gui.model.form_fields | The options of a command that the form renders, read from the parser. |
| gui.model.form_options | Turn what the user typed into the options for cli_argv. |
| gui.model.list_runs | The run directories below regen/runs/, newest first. |
| gui.model.local_label | The run-directory label of a local run: local-<model> made safe for a path. |
| gui.model.read_score | Read the score.toml that spotregen mutate --out writes. |
| gui.jobs.InProcessJob | A function that runs in a worker thread, one run at a time that counts. |
| gui.jobs.JobResult | The outcome of one run of a job. |
| gui.jobs.SubprocessJob | A command in a child process, with a live log and a gentle cancel. |
| gui.jobs.JobLine | One line a child process wrote. |
| gui.jobs.JobExit | The end of a child process. It is always the last event of a job. |
| gui.settings.Settings | What the interface remembers between sessions. |
| gui.settings.settings_path | The settings file of the current user. |
| gui.settings.load_settings | Read the settings; a missing or damaged file gives the defaults. |
| gui.settings.save_settings | Write the settings as JSON, creating the directory. |
| gui.settings.add_recent | Put a repository at the top of the recent list. |
| gui.editor.find_code | The code command of VS Code, or None when VS Code is not installed. |
| gui.editor.default_template | The editor template to use when the settings name none. |
| gui.editor.editor_name | The name of the editor a template starts, for a button label. |
| gui.editor.editor_argv | The argument list that opens path at line. |
| gui.editor.open_in_editor | Start the editor on a file and return at once. |
| gui.editor.folder_argv | The argument list that shows a directory in the file manager. |
| gui.editor.open_folder | Show a directory in the file manager (Finder on macOS) and return at once. |
| gui.versions.installed_version | The version of spotregen that is running. |
| gui.versions.pinned_version | The version of package that uv.lock in root pins. |
| gui.versions.version_status | Compare the running version with the one the repository pins. |
| gui.versions.VersionStatus | The running version against the pinned one. |
| gui.palette.Badge | The colours of one badge: a background and the text colour on it. |
| gui.palette.badge_for | The badge of a level or state. |
| gui.palette.contrast_ratio | The WCAG contrast ratio of two #RRGGBB colours. |
Drivers
Regeneration with an LLM. Non-deterministic: never part of make guard.
| drivers.claude | Regeneration of one unit by Claude Code (spotregen claude). |
| drivers.local | Regeneration with a local model in short sessions (spotregen local). |