Compaction

import subprocess
import sys
import tempfile
from pathlib import Path

from spotregen import make_sample_repo

tmp = tempfile.TemporaryDirectory()
root = make_sample_repo(Path(tmp.name) / "demo")


def spotregen(*args, drop=None):
    """Run `spotregen` in the sample repository; show the call and its output."""
    done = subprocess.run(
        [sys.executable, "-m", "spotregen", *args],
        cwd=root,
        capture_output=True,
        text=True,
        check=False,
    )
    print("$ spotregen", *args)
    lines = (done.stdout + done.stderr).splitlines()
    print("\n".join(x for x in lines if not (drop and drop in x)))
    print(f"[exit {done.returncode}]")

Definition 1 (Compaction) Knowledge accumulates sediment. spotregen compact collects the warnings that mark it: unused depends_on entries (UNIT05), evaluations that no intent item uses (EVAL05), consumers that no longer reference their unit (DEL03), decisions past their review date (PROV03), decisions resting on superseded records (PROV04) and decisions nobody cites (PROV05). Each is a candidate to remove, merge or re-examine. The command always exits 0.

Example 1 (Nothing to compact)  

spotregen("compact")

$ spotregen compact
regen compact: 0 candidates
[exit 0]

Example 2 (Three kinds of sediment)  

import re

# a consumer that no longer mentions the unit
(root / "docs" / "guide.qmd").write_text("No mention any more.\n")
# a decision that is past its review date
decision = root / "regen" / "decisions" / "why-add.toml"
decision.write_text(re.sub(r"review_after = .*", "review_after = 2020-01-01", decision.read_text()))
# a decision nobody cites
orphan = root / "regen" / "decisions" / "orphan.toml"
orphan.write_text(decision.read_text().replace("Addition is needed", "An orphan"))
spotregen("compact")

$ spotregen compact
WARNING DEL03   samplepkg.core.calc: consumer docs/guide.qmd no longer references the unit
WARNING PROV03  regen/decisions/orphan.toml: review was due 2020-01-01: do the assumptions still hold? ['integers only']
WARNING PROV05  regen/decisions/orphan.toml: no intent item references this decision
WARNING PROV03  regen/decisions/why-add.toml: review was due 2020-01-01: do the assumptions still hold? ['integers only']
regen compact: 4 candidates
[exit 0]

TipReviews

The same findings appear as warnings in spotregen check; compact shows only them. Run it before a release, and turn each line into an edit of the spec or a deliberate decision to keep it.

Next: measures.