perturb 0.0.1__py3-none-any.whl

perturb/__init__.py

@@ -0,0 +1,3 @@
+"""Planning ledger for agent-driven development. See docs/ for the design."""
+
+__version__ = "0.0.1"

perturb/ack.py

@@ -0,0 +1,47 @@
+from perturb.envelope import Refusal
+from perturb.events import EventStore
+
+
+def ack(events_dir, *, target, event_ids, all_pending, plan, plan_blob, by, note, now=None):
+    kwargs = {} if now is None else {"now": now}
+    store = EventStore(events_dir, **kwargs)
+    load_result = store.load()
+    events_by_id = {e.id: e for e in load_result.events}
+
+    if all_pending and event_ids:
+        raise Refusal("ack_conflicting_selection")
+    if not all_pending and not event_ids:
+        raise Refusal("ack_no_selection")
+
+    if all_pending:
+        ids_to_ack = [
+            e.id for e in load_result.events if e.target == target and e.status == "pending"
+        ]
+    else:
+        for event_id in event_ids:
+            if event_id not in events_by_id:
+                raise Refusal("unknown_event", f"event {event_id!r} not found")
+            event = events_by_id[event_id]
+            if event.target != target:
+                raise Refusal("event_target_mismatch", f"{event_id} targets {event.target}")
+            if event.status not in ("pending", "acknowledged"):
+                raise Refusal("event_not_pending", f"{event_id} is {event.status!r}")
+        ids_to_ack = list(event_ids)
+
+    acked = []
+    for event_id in ids_to_ack:
+        was_acknowledged = events_by_id[event_id].status == "acknowledged"
+        store.acknowledge(event_id, by=by, plan=plan, plan_blob=plan_blob, note=note)
+        acked.append({"id": event_id, "target": target, "was_acknowledged": was_acknowledged})
+
+    return {"acked": acked}
+
+
+def render_ack(data):
+    acked = data["acked"]
+    target = acked[0]["target"] if acked else ""
+    lines = [f"Acked {len(acked)} event(s) for {target}:"]
+    for entry in acked:
+        suffix = " (re-acked)" if entry["was_acknowledged"] else ""
+        lines.append(f"  {entry['id']}{suffix}")
+    return "\n".join(lines) + "\n"

perturb/adr.py

@@ -0,0 +1,294 @@
+import datetime
+import json
+import re
+from dataclasses import dataclass
+
+import yaml
+
+
+class AdrError(ValueError):
+    def __init__(self, reason: str, detail: str = "") -> None:
+        super().__init__(detail or reason)
+        self.reason = reason
+        self.detail = detail
+
+
+@dataclass(frozen=True)
+class Consequence:
+    id: str
+    text: str
+    affects: list
+    kind: str
+
+
+@dataclass(frozen=True)
+class Adr:
+    id: int
+    title: str
+    status: str
+    date: str
+    supersedes: list
+    areas: list
+    consequences: list
+    superseded_by: str | None = None
+    no_propagation: bool = False
+    no_propagation_reason: str | None = None
+
+
+_SUPERSEDES_REF = re.compile(r"adr:(\d+)(?:#([A-Za-z0-9][\w.-]*))?")
+_PROSE_ADR_REF = re.compile(r"\bADR[\s:-]*(\d+)", re.IGNORECASE)
+_MARKDOWN_LINK = re.compile(r"\[([^\]]*)\]\([^)]*\)")
+_STATUS_SEPARATORS = " \t·•|,;—–-"
+
+
+def parse_supersedes_ref(entry) -> tuple[int, str | None] | None:
+    """`adr:NNNN` → (N, None); `adr:NNNN#consequence-id` → (N, id); anything else → None."""
+    if not isinstance(entry, str):
+        return None
+    m = _SUPERSEDES_REF.fullmatch(entry)
+    if m is None:
+        return None
+    return int(m.group(1)), m.group(2)
+
+
+def _whole_adr_numbers(text: str) -> list[int] | None:
+    """The ADR numbers a prose Supersedes line names, when it names nothing but whole ADRs."""
+    plain = _MARKDOWN_LINK.sub(r"\1", text)
+    numbers = [int(n) for n in _PROSE_ADR_REF.findall(plain)]
+    rest = re.sub(r"\band\b|[,;&.\s]", "", _PROSE_ADR_REF.sub("", plain), flags=re.IGNORECASE)
+    return numbers if numbers and not rest else None
+
+
+def migrate_adr(text: str, adr_id: int) -> tuple[str, list[str]]:
+    """Rewrite a prose ADR in the structured format. Returns the new text and warnings about
+    anything that could not be carried into the front-matter."""
+    if text.lstrip().startswith("---"):
+        raise AdrError("already_structured", "ADR already has front-matter; not re-migrating")
+
+    lines = text.split("\n")
+    warnings: list[str] = []
+    first_heading = next((i for i, line in enumerate(lines) if line.startswith("## ")), len(lines))
+    carried: set[int] = set()
+
+    # Extract title from first # heading, stripping "ADR NNNN [—–-] " prefix
+    title = ""
+    for i, line in enumerate(lines):
+        if line.startswith("# "):
+            raw = line[2:].strip()
+            raw = re.sub(r"^ADR\s+\d+\s*[—–-]\s*", "", raw)
+            title = raw
+            carried.add(i)
+            break
+
+    # Extract status and date from the **Status:** line
+    status = ""
+    date = ""
+    for i, line in enumerate(lines):
+        if "**Status:**" in line:
+            carried.add(i)
+            rest = line.split("**Status:**", 1)[1]
+            m_status = re.match(r"\s*([A-Za-z]+)", rest)
+            if m_status:
+                status = m_status.group(1).lower()
+                rest = rest[m_status.end() :]
+            m_date = re.search(r"\d{4}-\d{2}-\d{2}", rest)
+            if m_date:
+                date = m_date.group(0)
+                rest = rest[: m_date.start()] + rest[m_date.end() :]
+            annotation = rest.strip(_STATUS_SEPARATORS)
+            if annotation:
+                warnings.append(
+                    f"status line annotation not carried into the front-matter: {annotation}"
+                )
+            break
+
+    # Carry a **Supersedes:** line naming whole ADRs; keep any other in the body
+    supersedes: list[str] = []
+    for i, line in enumerate(lines[:first_heading]):
+        if "**Supersedes:**" not in line:
+            continue
+        named = line.split("**Supersedes:**", 1)[1].strip()
+        numbers = _whole_adr_numbers(named)
+        if numbers is not None:
+            supersedes = [f"adr:{n:04d}" for n in numbers]
+            carried.add(i)
+        else:
+            mentioned = _PROSE_ADR_REF.search(_MARKDOWN_LINK.sub(r"\1", named))
+            example = f"adr:{int(mentioned.group(1)):04d}" if mentioned else "adr:NNNN"
+            warnings.append(
+                f"**Supersedes:** line kept in the body, not carried into supersedes: {named}. "
+                f'To supersede one consequence, add supersedes: ["{example}#<consequence-id>"]'
+            )
+        break
+
+    preamble = [line for i, line in enumerate(lines[:first_heading]) if i not in carried]
+    while preamble and not preamble[0].strip():
+        preamble.pop(0)
+    while preamble and not preamble[-1].strip():
+        preamble.pop()
+
+    # Extract the Context/Decision body (verbatim slice before ## Consequences)
+    body_lines: list[str] = []
+    in_body = False
+    consequence_lines: list[str] = []
+    in_consequences = False
+    for line in lines:
+        if line.startswith("## Consequences"):
+            in_consequences = True
+            continue
+        if in_consequences and line.startswith("## "):
+            break
+        if in_consequences:
+            consequence_lines.append(line)
+            continue
+        if not in_body and line.startswith("## ") and not line.startswith("## Consequences"):
+            in_body = True
+        if in_body:
+            body_lines.append(line)
+
+    bullets = _parse_prose_bullets(consequence_lines)
+
+    entries = []
+    seen_slugs: dict[str, int] = {}
+    for bullet_text in bullets:
+        affects = list(dict.fromkeys(f"#{m}" for m in re.findall(r"#(\d+)", bullet_text)))
+        slug = _consequence_slug(bullet_text)
+        if slug in seen_slugs:
+            seen_slugs[slug] += 1
+            slug = f"{slug}-{seen_slugs[slug]}"
+        else:
+            seen_slugs[slug] = 1
+        entry: dict = {"id": slug, "text": bullet_text, "kind": "decision"}
+        if affects:
+            entry["affects"] = affects
+        entries.append(entry)
+
+    fm = (
+        f"---\nid: {adr_id}\ntitle: {title}\nstatus: {status}\n"
+        f"date: {date}\nsupersedes: {json.dumps(supersedes)}\nareas: []\n---\n"
+    )
+    body = "\n".join(body_lines).rstrip("\n") + "\n" if body_lines else ""
+    if preamble:
+        body = "\n".join(preamble) + "\n" + ("\n" + body if body else "")
+    consequences_yaml = yaml.safe_dump(
+        entries, sort_keys=False, default_flow_style=False, allow_unicode=True, width=100
+    )
+    return f"{fm}\n{body}\n## Consequences\n\n```yaml\n{consequences_yaml}```\n", warnings
+
+
+def _parse_prose_bullets(lines: list[str]) -> list[str]:
+    bullets: list[str] = []
+    current: list[str] = []
+    for line in lines:
+        if line.startswith("- "):
+            if current:
+                bullets.append(" ".join(current))
+            current = [line[2:].rstrip()]
+        elif line.startswith("### "):
+            continue
+        elif line.strip() == "":
+            if current:
+                bullets.append(" ".join(current))
+                current = []
+        elif current:
+            current.append(line.strip())
+    if current:
+        bullets.append(" ".join(current))
+    return bullets
+
+
+def _consequence_slug(text: str) -> str:
+    cleaned = re.sub(r"#\d+", "", text).lower()
+    words = re.findall(r"[A-Za-z0-9]+", cleaned)[:5]
+    return "-".join(words)
+
+
+def parse_adr(text: str) -> Adr:
+    lines = text.split("\n")
+    try:
+        first = lines.index("---")
+        second = lines.index("---", first + 1)
+    except ValueError:
+        raise AdrError("bad_frontmatter", "ADR must begin with a --- front-matter block") from None
+    raw_fm = "\n".join(lines[first + 1 : second])
+    try:
+        fm = yaml.safe_load(raw_fm)
+    except yaml.YAMLError as exc:
+        raise AdrError("bad_frontmatter", f"front-matter is not valid YAML: {exc}") from exc
+    if not isinstance(fm, dict):
+        raise AdrError("bad_frontmatter", "front-matter parsed to a non-mapping")
+
+    for field in ("id", "title", "status", "date"):
+        if fm.get(field) is None:
+            raise AdrError("missing_field", f"required front-matter field '{field}' is absent")
+
+    date_val = fm.get("date")
+    if isinstance(date_val, datetime.date):
+        date_val = str(date_val)
+
+    consequences = _parse_consequences(lines[second + 1 :])
+
+    r = fm.get("no-propagation-reason")
+    return Adr(
+        id=fm.get("id"),
+        title=fm.get("title"),
+        status=fm.get("status"),
+        date=date_val,
+        supersedes=fm.get("supersedes") or [],
+        areas=fm.get("areas") or [],
+        consequences=consequences,
+        superseded_by=fm.get("superseded_by"),
+        no_propagation=fm.get("no-propagation") is True,
+        no_propagation_reason=r if isinstance(r, str) else None,
+    )
+
+
+def _parse_consequences(lines: list) -> list:
+    in_section = False
+    section_lines = []
+    for line in lines:
+        if line.startswith("## Consequences"):
+            in_section = True
+            continue
+        if in_section and line.startswith("## "):
+            break
+        if in_section:
+            section_lines.append(line)
+
+    content = "\n".join(section_lines)
+    # strip optional ```yaml ... ``` fence
+    stripped = content.strip()
+    if stripped.startswith("```"):
+        first_nl = stripped.index("\n")
+        stripped = stripped[first_nl + 1 :]
+        if stripped.endswith("```"):
+            stripped = stripped[: stripped.rfind("```")]
+
+    entries = yaml.safe_load(stripped) or []
+    if not isinstance(entries, list):
+        raise AdrError("bad_consequences", "Consequences block must be a YAML list")
+    result = []
+    seen_ids: set[str] = set()
+    for entry in entries:
+        for field in ("id", "text"):
+            if entry.get(field) is None:
+                raise AdrError(
+                    "missing_consequence_field",
+                    f"consequence missing required field '{field}'",
+                )
+        cid = entry.get("id")
+        if cid in seen_ids:
+            raise AdrError(
+                "duplicate_consequence_id",
+                f"consequence id '{cid}' appears more than once",
+            )
+        seen_ids.add(cid)
+        result.append(
+            Consequence(
+                id=entry.get("id"),
+                text=entry.get("text"),
+                affects=entry.get("affects") or [],
+                kind=entry.get("kind", "decision"),
+            )
+        )
+    return result

perturb/areas.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+import pathspec
+import yaml
+
+
+@dataclass(frozen=True)
+class Area:
+    slug: str
+    paths: list[str]
+    issues_label: str
+
+
+@dataclass(frozen=True)
+class AreaSet:
+    areas: list[Area]
+    errors: list[str]
+
+    def touches(self, files: Iterable[str]) -> set[str]:
+        file_list = list(files)
+        result: set[str] = set()
+        for area in self.areas:
+            spec = pathspec.PathSpec.from_lines("gitignore", area.paths)
+            if any(spec.match_file(f) for f in file_list):
+                result.add(area.slug)
+        return result
+
+    def in_area(
+        self,
+        labels: Iterable[str] = (),
+        plan_areas: Iterable[str] = (),
+    ) -> set[str]:
+        label_set = set(labels)
+        plan_area_set = set(plan_areas)
+        result: set[str] = set()
+        for area in self.areas:
+            if area.issues_label in label_set or area.slug in plan_area_set:
+                result.add(area.slug)
+        return result
+
+
+def load_areas(path: Path) -> AreaSet:
+    if not path.exists():
+        return AreaSet([], [])
+    doc = yaml.safe_load(path.read_text())
+    if not isinstance(doc, dict) or not isinstance(doc.get("areas"), dict):
+        return AreaSet([], ["areas.yaml: expected a dict with an 'areas' dict"])
+    areas_map: dict = doc["areas"]
+    areas: list[Area] = []
+    errors: list[str] = []
+    for slug, entry in areas_map.items():
+        if not isinstance(entry, dict) or "paths" not in entry:
+            errors.append(f"area '{slug}': missing 'paths' key, skipped")
+            continue
+        issues_label = entry.get("issues_label") or f"area:{slug}"
+        areas.append(Area(slug=slug, paths=list(entry["paths"]), issues_label=issues_label))
+    return AreaSet(areas=areas, errors=errors)
+
+
+def read_plan_areas(text: str) -> list[str]:
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return []
+    fm = yaml.safe_load(parts[1])
+    if not isinstance(fm, dict):
+        return []
+    areas = fm.get("areas")
+    return areas if isinstance(areas, list) else []

perturb/check.py

@@ -0,0 +1,244 @@
+import re
+from pathlib import Path
+
+from perturb.adr import Adr, AdrError, parse_adr, parse_supersedes_ref
+from perturb.areas import AreaSet
+from perturb.inbox import resolve_excerpt
+from perturb.refs import RefError, parse_ref
+from perturb.stale import stale_findings
+
+
+def adr_findings(adr_dir: Path, graph: dict, area_set: AreaSet | None = None) -> list[dict]:
+    findings = []
+    parsed: dict[int, Adr] = {}
+
+    for path in sorted(adr_dir.glob("*.md")):
+        try:
+            adr = parse_adr(path.read_text())
+        except AdrError as exc:
+            findings.append(
+                {
+                    "kind": "adr_parse",
+                    "ref": path.name,
+                    "detail": str(exc),
+                    "fix": f"fix the front-matter or body of {path.name}",
+                }
+            )
+            continue
+        parsed[adr.id] = adr
+        m = re.match(r"(\d+)", path.name)
+        if m and int(m.group(1)) != adr.id:
+            findings.append(
+                {
+                    "kind": "filename_id_mismatch",
+                    "ref": path.name,
+                    "detail": f"filename number {int(m.group(1))} != front-matter id {adr.id}",
+                    "fix": f"rename the file to {adr.id:04d}-*.md or update the front-matter id",
+                }
+            )
+        if adr.status == "superseded" and not adr.superseded_by:
+            findings.append(
+                {
+                    "kind": "superseded_no_link",
+                    "ref": path.name,
+                    "detail": "status is superseded but superseded_by is absent",
+                    "fix": f"add superseded_by: adr:NNNN to the front-matter of {path.name}",
+                }
+            )
+        for consequence in adr.consequences:
+            for affects_entry in consequence.affects:
+                try:
+                    ref = parse_ref(affects_entry)
+                except RefError:
+                    continue
+                if ref.kind == "issue" and ref.id not in graph.get("issues", {}):
+                    findings.append(
+                        {
+                            "kind": "affects_unresolved",
+                            "ref": affects_entry,
+                            "detail": f"issue {affects_entry} not found in graph",
+                            "fix": (
+                                f"perturb sync  # then re-check, or remove "
+                                f"{affects_entry} from affects"
+                            ),
+                        }
+                    )
+                elif ref.kind == "area" and area_set is not None:
+                    declared = {a.slug for a in area_set.areas}
+                    if ref.id not in declared:
+                        findings.append(
+                            {
+                                "kind": "affects_unresolved",
+                                "ref": affects_entry,
+                                "detail": f"area {affects_entry} not declared in areas.yaml",
+                                "fix": (
+                                    f"add {ref.id} to perturb/areas.yaml, or remove "
+                                    f"{affects_entry} from affects"
+                                ),
+                            }
+                        )
+
+    # Supersedes entries must name an ADR in this directory, and a consequence it has
+    for adr in parsed.values():
+        own = f"adr:{adr.id:04d}"
+        for entry in adr.supersedes:
+            target_ref = parse_supersedes_ref(entry)
+            if target_ref is None:
+                findings.append(
+                    {
+                        "kind": "supersedes_invalid",
+                        "ref": str(entry),
+                        "detail": f"{own} supersedes {entry!r}, not adr:NNNN or adr:NNNN#id",
+                        "fix": f"write it as adr:NNNN or adr:NNNN#<consequence-id> in {own}",
+                    }
+                )
+                continue
+            number, consequence_id = target_ref
+            target = parsed.get(number)
+            if target is None:
+                detail = f"{own} supersedes adr:{number:04d}, which is not in {adr_dir}"
+            elif consequence_id is not None and consequence_id not in {
+                c.id for c in target.consequences
+            }:
+                detail = f"adr:{number:04d} has no consequence {consequence_id!r}"
+            else:
+                continue
+            findings.append(
+                {
+                    "kind": "supersedes_unresolved",
+                    "ref": str(entry),
+                    "detail": detail,
+                    "fix": f"correct the supersedes entry {entry!r} in {own}",
+                }
+            )
+
+    # Backlink check: superseded_by target must list this ADR in its supersedes
+    for adr in parsed.values():
+        if not adr.superseded_by:
+            continue
+        try:
+            target_ref = parse_ref(adr.superseded_by)
+        except RefError:
+            continue
+        if target_ref.kind != "adr":
+            continue
+        target_id = int(target_ref.id)
+        target = parsed.get(target_id)
+        if target is None:
+            continue
+        expected_back = f"adr:{adr.id:04d}"
+        if expected_back not in target.supersedes:
+            findings.append(
+                {
+                    "kind": "supersede_backlink",
+                    "ref": f"adr:{adr.id:04d}",
+                    "detail": (
+                        f"adr:{adr.id:04d} has superseded_by adr:{target_id:04d} "
+                        f"but adr:{target_id:04d} does not list adr:{adr.id:04d} in supersedes"
+                    ),
+                    "fix": (f"add adr:{adr.id:04d} to the supersedes list of adr:{target_id:04d}"),
+                }
+            )
+
+    return findings
+
+
+def event_findings(events: list, graph: dict, repo_root: Path) -> list[dict]:
+    findings = []
+    for event in events:
+        if event.detail:
+            _excerpt, warning = resolve_excerpt(repo_root, event.detail)
+            if warning is not None:
+                findings.append(
+                    {
+                        "kind": "dead_anchor",
+                        "ref": event.id,
+                        "detail": warning,
+                        "fix": f"update the detail field of event {event.id}",
+                    }
+                )
+        if event.status == "pending":
+            try:
+                ref = parse_ref(event.target)
+            except RefError:
+                ref = None
+            if (
+                ref is not None
+                and ref.kind == "issue"
+                and graph.get("issues", {}).get(ref.id, {}).get("state") == "CLOSED"
+            ):
+                findings.append(
+                    {
+                        "kind": "pending_on_closed",
+                        "ref": event.target,
+                        "detail": (
+                            f"event {event.id} is pending but its target {event.target} is closed"
+                        ),
+                        "fix": (f"perturb dismiss {event.id}  # issue {event.target} is closed"),
+                    }
+                )
+    return findings
+
+
+def stale_check_findings(planned: list, events: list) -> list[dict]:
+    findings = []
+    for s in stale_findings(planned, events):
+        findings.append(
+            {
+                "kind": "stale_plan",
+                "ref": f"#{s['issue']}",
+                "detail": f"plan {s['plan']} has {len(s['stale_events'])} stale event(s)",
+                "fix": f"perturb ack  # or update the plan for #{s['issue']}",
+            }
+        )
+    return findings
+
+
+def render_check(findings: list[dict]) -> str:
+    if not findings:
+        return "ok\n"
+    lines = []
+    for f in findings:
+        lines.append(f"{f['kind']}  {f['ref']}  {f['detail']}")
+        lines.append(f"  fix: {f['fix']}")
+    return "\n".join(lines) + "\n"
+
+
+def unpropagated_adr_findings(adr_dir: Path, events: list) -> list[dict]:
+    findings = []
+    for path in sorted(adr_dir.glob("*.md")):
+        try:
+            adr = parse_adr(path.read_text())
+        except AdrError:
+            continue
+        if adr.status != "accepted":
+            continue
+        padded = f"adr:{adr.id:04d}"
+        if adr.no_propagation:
+            reason = adr.no_propagation_reason
+            if reason is None or not reason.strip():
+                findings.append(
+                    {
+                        "kind": "no_propagation_without_reason",
+                        "ref": path.name,
+                        "detail": "no-propagation: true needs a non-empty no-propagation-reason",
+                        "fix": (
+                            f'add no-propagation-reason: "<why>" to the front-matter of {path.name}'
+                        ),
+                    }
+                )
+            continue
+        has_event = any(e.source == padded or e.source.startswith(padded + "#") for e in events)
+        if not has_event:
+            findings.append(
+                {
+                    "kind": "adr_unpropagated",
+                    "ref": path.name,
+                    "detail": f"accepted ADR {padded} has no events and no no-propagation flag",
+                    "fix": (
+                        f"perturb propose {padded}"
+                        f"  # or set no-propagation: true and no-propagation-reason in {path.name}"
+                    ),
+                }
+            )
+    return findings