spotregen 0.1.0__tar.gz

spotregen-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.3
+Name: spotregen
+Version: 0.1.0
+Summary: Regenerative Software tooling: check intent, evaluations and provenance of regenerable units, and drive blind 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 gate (`spotregen check`) for `make guard`, plus reports
+  (`status`, `deletion-test`, `context`, `compact`, `new-unit`) and two
+  non-deterministic drivers (`blind`, `local`) that regenerate a unit with an LLM.
+
+## Install
+
+```bash
+uv add --dev spotregen
+```
+
+## Use
+
+```bash
+spotregen check [--strict]            # the gate: 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 new-unit MODULE --pace P --risk R [--dry-run]
+spotregen blind 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.
+
+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 gate before a push
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [RELEASING.md](RELEASING.md). The design
+is recorded in [ADR 0001](docs/adr/0001-spotregen-package.md).
+
+## License
+
+AGPL-3.0-or-later.

spotregen-0.1.0/README.md

@@ -0,0 +1,60 @@
+# 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 gate (`spotregen check`) for `make guard`, plus reports
+  (`status`, `deletion-test`, `context`, `compact`, `new-unit`) and two
+  non-deterministic drivers (`blind`, `local`) that regenerate a unit with an LLM.
+
+## Install
+
+```bash
+uv add --dev spotregen
+```
+
+## Use
+
+```bash
+spotregen check [--strict]            # the gate: 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 new-unit MODULE --pace P --risk R [--dry-run]
+spotregen blind 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.
+
+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 gate before a push
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [RELEASING.md](RELEASING.md). The design
+is recorded in [ADR 0001](docs/adr/0001-spotregen-package.md).
+
+## License
+
+AGPL-3.0-or-later.

spotregen-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "spotregen"
+version = "0.1.0"
+description = "Regenerative Software tooling: check intent, evaluations and provenance of regenerable units, and drive blind regeneration"
+readme = "README.md"
+classifiers = [
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+requires-python = ">=3.13"
+dependencies = []
+
+[project.license]
+text = "AGPL-3.0-or-later"
+
+[[project.authors]]
+name = "bartzbeielstein"
+email = "32470350+bartzbeielstein@users.noreply.github.com"
+
+[project.urls]
+Documentation = "https://advm1.gm.fh-koeln.de/~bartz/spotregen/"
+Repository = "https://git-ce.rwth-aachen.de/thomas.bartz-beielstein/spotregen"
+Issues = "https://git-ce.rwth-aachen.de/thomas.bartz-beielstein/spotregen/-/issues"
+
+[project.scripts]
+spotregen = "spotregen.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=6.0.0",
+    "black>=24.1.0",
+    "isort>=5.13.0",
+    "ruff>=0.3.0",
+    "ty>=0.0.29",
+    "reuse>=5.0.0",
+    "pre-commit>=4.0.0",
+    "quartodoc>=0.9.1",
+    "ipykernel>=7.1.0",
+    "jupyter>=1.1.1",
+    "nbformat>=5.10.4",
+    "pyyaml>=6.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+    "slow: end-to-end tests with fake claude / fake endpoint, and the parity test (deselect with -m 'not slow')",
+    "regen: durable evaluations of a regenerable unit (regen/units/*.toml); they must survive a rewrite of the implementation",
+]
+
+[tool.black]
+target-version = ["py313"]
+
+[tool.isort]
+profile = "black"
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+
+[tool.coverage.run]
+branch = true
+source = ["src/spotregen"]
+
+[tool.coverage.report]
+fail_under = 85
+
+[tool.ty.environment]
+python-version = "3.13"

spotregen-0.1.0/pyproject.toml.orig

@@ -0,0 +1,81 @@
+[project]
+name = "spotregen"
+version = "0.1.0"
+description = "Regenerative Software tooling: check intent, evaluations and provenance of regenerable units, and drive blind regeneration"
+readme = "README.md"
+license = { text = "AGPL-3.0-or-later" }
+classifiers = [
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+authors = [
+    { name = "bartzbeielstein", email = "32470350+bartzbeielstein@users.noreply.github.com" }
+]
+requires-python = ">=3.13"
+# Zero runtime dependencies is a contract (ADR 0001): `make guard` fails if this
+# list is ever non-empty. The tool uses the standard library only.
+dependencies = []
+
+[project.urls]
+Documentation = "https://advm1.gm.fh-koeln.de/~bartz/spotregen/"
+Repository = "https://git-ce.rwth-aachen.de/thomas.bartz-beielstein/spotregen"
+Issues = "https://git-ce.rwth-aachen.de/thomas.bartz-beielstein/spotregen/-/issues"
+
+[project.scripts]
+spotregen = "spotregen.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    # Testing
+    "pytest>=9.0.2",
+    "pytest-cov>=6.0.0",
+    # Linting / formatting / types / licences
+    "black>=24.1.0",
+    "isort>=5.13.0",
+    "ruff>=0.3.0",
+    "ty>=0.0.29",
+    "reuse>=5.0.0",
+    "pre-commit>=4.0.0",
+    # Documentation (Quarto + quartodoc)
+    "quartodoc>=0.9.1",
+    "ipykernel>=7.1.0",
+    "jupyter>=1.1.1",
+    "nbformat>=5.10.4",
+    "pyyaml>=6.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+    "slow: end-to-end tests with fake claude / fake endpoint, and the parity test (deselect with -m 'not slow')",
+    "regen: durable evaluations of a regenerable unit (regen/units/*.toml); they must survive a rewrite of the implementation",
+]
+
+[tool.black]
+target-version = ["py313"]
+
+[tool.isort]
+profile = "black"
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+
+[tool.coverage.run]
+branch = true
+source = ["src/spotregen"]
+
+[tool.coverage.report]
+fail_under = 85
+
+[tool.ty.environment]
+python-version = "3.13"

spotregen-0.1.0/src/spotregen/__init__.py

@@ -0,0 +1,82 @@
+# SPDX-FileCopyrightText: 2026 bartzbeielstein
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""spotregen: Regenerative Software tooling (stdlib only).
+
+Chad Fowler's *Regenerative Software* treats code as disposable and the system's
+knowledge as the asset. This package reads that knowledge from the tracked
+``regen/`` tree of a repository and checks it against the source tree. It uses the
+standard library only and never imports the modules it describes.
+
+The command line is ``spotregen [--root DIR] <command>`` (see `spotregen.cli.main`);
+the functions below are the programmatic interface. The drivers that regenerate a
+unit with an LLM live in `spotregen.drivers` and are not imported here.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from spotregen.checks import (
+    Finding,
+    check_architecture,
+    check_decisions,
+    check_unit,
+    run_checks,
+)
+from spotregen.compact import compaction_report
+from spotregen.context import build_context, public_contract
+from spotregen.reports import deletion_report, status_table
+from spotregen.sample import make_sample_repo
+from spotregen.scaffold import scaffold_unit
+from spotregen.scan import find_importers
+from spotregen.spec import (
+    Alternative,
+    Architecture,
+    Consumer,
+    Decision,
+    IntentItem,
+    RegenSpec,
+    SpecError,
+    Unit,
+    find_repo_root,
+    load_architecture,
+    load_decision,
+    load_spec,
+    load_unit,
+    resolve_unit,
+)
+
+try:
+    __version__ = version("spotregen")
+except PackageNotFoundError:  # pragma: no cover - running from an unbuilt tree
+    __version__ = "0+unknown"
+
+__all__ = [
+    "Alternative",
+    "Architecture",
+    "Consumer",
+    "Decision",
+    "Finding",
+    "IntentItem",
+    "RegenSpec",
+    "SpecError",
+    "Unit",
+    "__version__",
+    "build_context",
+    "check_architecture",
+    "check_decisions",
+    "check_unit",
+    "compaction_report",
+    "deletion_report",
+    "find_importers",
+    "find_repo_root",
+    "load_architecture",
+    "load_decision",
+    "load_spec",
+    "load_unit",
+    "make_sample_repo",
+    "public_contract",
+    "resolve_unit",
+    "run_checks",
+    "scaffold_unit",
+    "status_table",
+]

spotregen-0.1.0/src/spotregen/__main__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026 bartzbeielstein
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Entry point of ``python -m spotregen``."""
+
+from spotregen.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spotregen-0.1.0/src/spotregen/_tools.py

@@ -0,0 +1,115 @@
+# SPDX-FileCopyrightText: 2026 bartzbeielstein
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Checks for the external tools the drivers depend on (standard library only).
+
+The drivers call ``claude``, ``git`` and ``lsof``, or talk to a local model server.
+They fail early and clearly when one of these is missing: `ExternalToolError` for a
+missing executable or an unreachable endpoint, `ConfigurationError` for an option the
+drivers refuse. The command line maps both to exit code 2.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+
+__all__ = [
+    "ConfigurationError",
+    "ExternalToolError",
+    "probe_endpoint",
+    "require_executable",
+]
+
+
+class ExternalToolError(RuntimeError):
+    """A required executable is not installed or an endpoint is not reachable.
+
+    Examples:
+        ```{python}
+        from spotregen._tools import ExternalToolError, require_executable
+
+        try:
+            require_executable("no-such-tool-xyz", "install it first")
+        except ExternalToolError as exc:
+            print(exc)
+        ```
+    """
+
+
+class ConfigurationError(ValueError):
+    """A driver option is refused, for example a file outside the repository.
+
+    Examples:
+        ```{python}
+        from spotregen._tools import ConfigurationError
+
+        print(issubclass(ConfigurationError, ValueError))
+        ```
+    """
+
+
+def require_executable(name: str, hint: str = "") -> str:
+    """Find an executable on ``PATH`` or fail with a clear message.
+
+    Args:
+        name: Executable name, for example ``"claude"``.
+        hint: How to get it, appended to the error message. Defaults to ``""``.
+
+    Returns:
+        str: The absolute path of the executable.
+
+    Raises:
+        ExternalToolError: If the executable is not on ``PATH``.
+
+    Examples:
+        ```{python}
+        from spotregen._tools import require_executable
+
+        print(require_executable("sh").endswith("sh"))
+        ```
+    """
+    found = shutil.which(name)
+    if found is None:
+        suffix = f" ({hint})" if hint else ""
+        raise ExternalToolError(f"'{name}' was not found on PATH{suffix}")
+    return found
+
+
+def probe_endpoint(url: str, timeout: float = 5.0) -> list[str]:
+    """Ask an OpenAI-compatible server which models it serves (``GET /v1/models``).
+
+    Args:
+        url: Base URL of the server, for example ``"http://127.0.0.1:1234"``.
+        timeout: Seconds to wait. Defaults to 5.0.
+
+    Returns:
+        list[str]: The model identifiers the server lists.
+
+    Raises:
+        ExternalToolError: If the server cannot be reached or does not answer with the
+            expected JSON.
+
+    Examples:
+        ```{python}
+        from spotregen._tools import ExternalToolError, probe_endpoint
+
+        try:
+            probe_endpoint("http://127.0.0.1:9", timeout=1.0)
+        except ExternalToolError as exc:
+            print("unreachable:", "127.0.0.1:9" in str(exc))
+        ```
+    """
+    import urllib.error  # imported here: the command line imports this module
+    import urllib.request  # for its exceptions and must not pay for urllib
+
+    target = url.rstrip("/") + "/v1/models"
+    try:
+        with urllib.request.urlopen(target, timeout=timeout) as response:
+            payload = json.load(response)
+        return [str(item["id"]) for item in payload["data"]]
+    except (OSError, urllib.error.URLError, ValueError, KeyError, TypeError) as exc:
+        raise ExternalToolError(
+            f"cannot reach a model server at {target}: {exc}. "
+            "Start LM Studio's local server (or pass --endpoint)."
+        ) from exc