@appchy/jarvis 0.1.37 → 0.1.39

package/harness/harness/generate.py

@@ -0,0 +1,267 @@
+import os
+import re
+
+from . import ids
+import shutil
+from pathlib import Path
+
+from .tree import (BACKLOG_END, BACKLOG_START, DONE_TIER, SYSTEMS_END,
+                    SYSTEMS_START, die, rel)
+from .model import Task, Version, _ordered, scan
+from .registry import rules_by_domain, scan_domains, scan_systems
+from .lint import print_lint
+
+
+def _relpath_from_readme(folder: Path, root: Path) -> str:
+    return str(folder.relative_to(root)).replace(os.sep, "/")
+def _task_row(t: Task, root: Path) -> str:
+    link = f"[{t.name}]({_relpath_from_readme(t.md, root)})"
+    deps = ", ".join(t.depends_on) if t.depends_on else "—"
+    return (f"| {link} — {t.title} | {t.priority} | "
+            f"{t.display_status()} | {deps} |")
+def _table(tasks: list, root: Path) -> str:
+    rows = ["| Task | Priority | Status | Depends on |", "|---|---|---|---|"]
+    rows += [_task_row(t, root) for t in tasks]
+    return "\n".join(rows)
+def _epic_block(e, root: Path) -> str:
+    """An epic's table under its own heading. `epic.md` is gone once the version
+    released, so the heading only links when there is something to link to."""
+    tasks = _ordered(e.tasks) if not e.in_backlog else sorted(
+        e.backlog_tasks, key=lambda t: (t.priority_rank(), t.name))
+    head = (f"[{e.title}]({_relpath_from_readme(e.md, root)})"
+            if e.planned else f"{e.title} _( planned; epic.md archived at release )_")
+    if not tasks:
+        return f"#### Epic — {head}\n\n_no tasks yet_"
+    return f"#### Epic — {head}\n\n" + _table(tasks, root)
+def _version_section(v: Version, root: Path) -> str:
+    status = v.status()
+    badge = {
+        "released": f"released {v.released}",
+        "current": "current",
+        "planned": "planned" + (f" · target {v.target}" if v.target else ""),
+    }[status]
+    link = f"[{v.title}]({_relpath_from_readme(v.md, root)})"
+    head = f"### Version — {link} _( {badge} )_"
+    if v.outcome:
+        head += f"\n\n{v.outcome}"
+    parts = []
+    # Loose tasks first — the pre-epic shape, still rendered so grandfathered
+    # versions read normally — then one block per epic.
+    loose = _ordered(v.tasks)
+    if loose:
+        parts.append(_table(loose, root))
+    parts += [_epic_block(e, root) for e in v.epics]
+    if not parts:
+        return f"{head}\n\n_no tasks yet_"
+    return head + "\n\n" + "\n\n".join(parts)
+def _regen_readme(root: Path) -> str:
+    """Rebuild the README backlog table between its markers. Returns a status
+    line. Raises via die() when the file or its markers are missing."""
+    readme = root / "README.md"
+    # SELF-HEALING, not fatal — the same call already made for the SYSTEMS markers,
+    # and for the same reason. `_sync` runs at the END of every mutating command, so
+    # dying here reports failure *after* the mutation has landed: `version-new` in a
+    # tree without this file created the version, printed an error and exited 1. A
+    # generator that owns a block can create the block it owns.
+    if not readme.is_file():
+        readme.parent.mkdir(parents=True, exist_ok=True)
+        readme.write_text(f"# Work\n\n{BACKLOG_START}\n{BACKLOG_END}\n")
+    text = readme.read_text()
+    if BACKLOG_START not in text or BACKLOG_END not in text:
+        text = text.rstrip() + f"\n\n{BACKLOG_START}\n{BACKLOG_END}\n"
+        readme.write_text(text)
+
+    s = scan(root)
+    sections = []
+
+    for v in sorted(s["versions"], key=lambda x: (x.order, x.name)):
+        sections.append(_version_section(v, root))
+
+    if s["backlog"]:
+        # The backlog is where epics are PLANNED — a version is a release and is
+        # expensive to open, so an epic waits here until its cut can.
+        blocks = [_epic_block(e, root) for e in s["backlog_epics"]]
+        loose = sorted((t for t in s["backlog"] if not t.epic),
+                       key=lambda x: (x.priority_rank(), x.name))
+        if loose:
+            blocks.append(_table(loose, root))
+        sections.append(
+            "### Backlog _( unscheduled — pull an epic into a version to start )_"
+            "\n\n" + "\n\n".join(blocks)
+        )
+
+    # The domain map, in READING ORDER, above the board. `scan_domains` sorts by
+    # `domains.order` from config, so this block and `list` cannot disagree — and a
+    # repo that adds a tenth domain gets it here with no code change.
+    domains = scan_domains(root)
+    if domains:
+        rows = ["### The domains", "",
+                "Where a durable call goes, in reading order — what it does → how it's",
+                "built → how it looks → how we know it's good → what keeps it safe → how we",
+                "run it → how users get unblocked → how we reach and earn → what binds us.",
+                "", "| Domain | Rules |", "|---|---|"]
+        counts = rules_by_domain(root)
+        for d in domains:
+            rows.append(f"| [{d.name}]({d.name}/README.md) | {counts.get(d.name) or '—'} |")
+        sections.insert(0, "\n".join(rows))
+
+    block = "\n\n".join(sections) if sections else "_backlog is empty_"
+    # The replacement is a CALLABLE so that what goes in comes back out. A title is
+    # something a person typed, and as a replacement template `\d` is a bad escape
+    # that raises — after the task folder is already on disk, so the tree is mutated,
+    # the command dies, and every later command that regenerates this file dies too.
+    # `\n` and `\t` do not raise; they quietly become a real newline in the table.
+    new_text = re.sub(
+        re.escape(BACKLOG_START) + r".*?" + re.escape(BACKLOG_END),
+        lambda _: BACKLOG_START + "\n" + block + "\n" + BACKLOG_END,
+        text,
+        flags=re.DOTALL,
+    )
+    if new_text != text:
+        readme.write_text(new_text)
+        total_tasks = (sum(len(v.all_tasks()) for v in s["versions"])
+                       + len(s["backlog"]))
+        return (f"updated {rel(readme, root)} "
+                f"({len(s['versions'])} version(s), {total_tasks} task(s))")
+    return "README.md backlog table already up to date"
+def _regen_architecture_readme(root: Path) -> str:
+    """Rewrite the system index + mermaid dependency map INSIDE
+    `architecture/README.md`'s `<!-- SYSTEMS -->` markers. Both are DERIVED — a
+    hand-drawn architecture diagram is the most reliably stale artifact a repo
+    can own, and a hand-kept index is the second.
+
+    A marked block rather than a whole generated file, because `README.md` is
+    also the domain's own landing doc: one file per folder, so a reader never
+    has to work out which of two entry docs is authoritative. The generator owns
+    its block and nothing else — the same split `work/README.md` already uses
+    for the backlog table."""
+    arch = root / "architecture"
+    systems = scan_systems(root)
+    readme = arch / "README.md"
+    if not arch.is_dir() or not systems or not readme.is_file():
+        return "no systems yet — architecture/README.md not generated"
+    text = readme.read_text()
+    if SYSTEMS_START not in text or SYSTEMS_END not in text:
+        # SELF-HEALING, not fatal. This used to `die()`, which made a fresh repo
+        # unusable: `domain-new architecture` scaffolds this README without the
+        # markers, so the very first `system-new` hard-failed on a file the tool
+        # itself had just written. The generated block is the generator's business
+        # — if there is no marked block to own, it appends one rather than
+        # demanding the author hand-place two HTML comments they were never told
+        # about. Only the block between the markers is ever rewritten, so an
+        # author's own prose above it is untouched either way.
+        text = text.rstrip() + f"\n\n## The systems\n\n{SYSTEMS_START}\n{SYSTEMS_END}\n"
+        readme.write_text(text)
+
+    names = {s.name for s in systems}
+    lines = [
+        "A **system** is a capability boundary with durable rules: it owns `code:`",
+        "regions and hosts the rules that govern them. Deliberately not",
+        "one per package — packages are derivable from the file tree.", "",
+        "| System | Owns (`code:`) | Rules | Depends on |", "|---|---|---|---|",
+    ]
+    for s in systems:
+        unenforced = sum(1 for v in s.rules.values() if not v)
+        n = f"{len(s.rules)}" + (f" ({unenforced} unenforced)" if unenforced else "")
+        lines.append(f"| [{s.title}]({s.name}.md) | "
+                     f"{', '.join(f'`{c}`' for c in s.code)} | {n} | "
+                     f"{', '.join(s.depends_on) or '—'} |")
+
+    lines += ["", "## How they depend", "", "```mermaid", "flowchart TD"]
+    for s in systems:
+        lines.append(f'  {s.name.replace("-", "_")}["{s.title}"]')
+    for s in systems:
+        for dep in s.depends_on:
+            if dep in names:
+                lines.append(f'  {s.name.replace("-", "_")} --> '
+                             f'{dep.replace("-", "_")}')
+    lines += ["```", "",
+              "An arrow means *depends on*. A cycle here is a design smell, not a",
+              "drawing choice — it means two systems can't be reasoned about apart."]
+
+    new_text = re.sub(
+        re.escape(SYSTEMS_START) + r".*?" + re.escape(SYSTEMS_END),
+        lambda _: SYSTEMS_START + "\n" + "\n".join(lines) + "\n" + SYSTEMS_END,
+        text,
+        flags=re.DOTALL,
+    )
+    if new_text == text:
+        return "architecture/README.md already up to date"
+    readme.write_text(new_text)
+    return f"updated {rel(readme, root)} ({len(systems)} systems)"
+def _regen_decisions_index(root: Path) -> str:
+    """Rebuild a legacy DECISIONS.md's Index from its `### <id> — …` headings, so
+    hand-maintained lines stop being a thing anyone syncs.
+
+    REFUSES when the existing index says MORE than the headings do. Today many
+    index lines carry annotations the heading lacks (a bare title in the
+    heading vs `… : Brilliant-style, AI-authored-on-the-fly learning for any topic
+    (expanded by <another id>)` in the index), so generating would silently delete
+    rationale. Phase 2b re-authors each entry with a self-sufficient heading;
+    until then this stays inert on purpose — a generator that destroys content is
+    worse than the hand-sync it replaces."""
+    md = root / "DECISIONS.md"
+    if not md.is_file():
+        return "no DECISIONS.md"
+    text = md.read_text()
+    m = re.search(r"^## Index\s*$(.*?)(?=^###\s|\Z)", text, re.MULTILINE | re.DOTALL)
+    if not m:
+        return "DECISIONS.md has no ## Index section — not generated"
+    headings = dict(ids.titled_heading(3).findall(text))
+    existing = dict(ids.index_entry().findall(m.group(1)))
+    richer = [id_ for id_, line in existing.items()
+              if len(line.strip()) > len(headings.get(id_, "").strip()) + 8]
+    if richer:
+        return (f"DECISIONS.md index NOT regenerated — {len(richer)} index line(s) "
+                f"say more than their `###` heading; generating would delete that "
+                f"text (Phase 2b makes headings self-sufficient)")
+
+    block = ("\n\n<!-- GENERATED by jarvis work — do not hand-edit. Edit the entries. -->\n\n"
+             + "\n".join(f"- **{id_}** — {t.strip()}" for id_, t in headings.items())
+             + "\n\n")
+    new_text = text[:m.start(1)] + block + text[m.end(1):]
+    if new_text == text:
+        return "DECISIONS.md index already up to date"
+    md.write_text(new_text)
+    return f"updated {rel(md, root)} index ({len(headings)} entries)"
+def settle_epic_tier(root: Path, include_released: bool = False) -> list:
+    """Put every epic in the tier its own TASKS put it in, and report what moved.
+
+    This is what keeps `<v>/complete/` from being a second, hand-maintained opinion
+    about status. The fact is derived — an epic is done when all its tasks are —
+    and this materializes it in BOTH directions on every mutation, so reopening one
+    task lifts its epic straight back onto the board. Nothing is ever parked by
+    hand, and nothing can sit in `complete/` disagreeing with what it contains.
+
+    Released versions are skipped: they are a record, not a board, and `release`
+    flattens the tier before stamping so an archived cut keeps a flat epic list."""
+    moved = []
+    for v in scan(root)["versions"]:
+        if v.released and not include_released:
+            continue
+        for e in v.epics:
+            done = e.is_done()
+            if done == e.done_tier:
+                continue
+            dest = (v.folder / DONE_TIER / e.name) if done else (v.folder / e.name)
+            if dest.exists():
+                continue
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.move(str(e.folder), str(dest))
+            moved.append((e.name, "complete" if done else "in flight"))
+        # Leave no empty `complete/` behind — an empty tier reads as a claim that
+        # something finished here.
+        tier = v.folder / DONE_TIER
+        if tier.is_dir() and not any(tier.iterdir()):
+            tier.rmdir()
+    return moved
+
+
+def _sync(root: Path):
+    """Post-mutation housekeeping: regenerate every derived artifact, surface lint."""
+    for name, where in settle_epic_tier(root):
+        print(f"epic '{name}' -> {where}")
+    print(_regen_readme(root))
+    print(_regen_architecture_readme(root))
+    print(_regen_decisions_index(root))
+    print_lint(root)