aw-spec-cli 0.1.20 → 0.1.22

package/assets/.appweaver/scripts/python/aw-plan-coverage.py

@@ -0,0 +1,503 @@
+#!/usr/bin/env python3
+"""
+aw-plan-coverage — which of a lane plan's elements the generated code realises.
+
+Backs the `plan-coverage` subcommand of aw-spec-actions, called identically by the bash
+and the powershell twin, so the two cannot drift.
+
+WHY IT EXISTS. `implement` hands a whole plan to one generation pass and gets back the list
+of files it wrote. A pass that stops part-way — five use-cases of seven — returns a
+non-empty list, and a non-empty list is all the workflow used to check. The missing
+elements have no failing test either, because nothing was ever written to fail. This
+reads the plan's element list deterministically and answers, per element, whether the
+lane's code names it and whether the generating model reported it done.
+
+TWO KINDS OF ELEMENT.
+  checked      an identifier the code must contain — an entity, value object, domain
+               event or use-case (backend); a component (frontend); an identifier in a
+               delta plan's ADDED table. Searched for in the lane's source path, test
+               files excluded. Entities and value objects must appear as a whole word.
+               Every other checked name may carry a suffix, because stacks add one by
+               convention: `MedicationOrderPlaced` is realised as
+               `MedicationOrderPlacedEvent`, `CancelOrder` as `CancelOrderCommand`.
+  report-only  an element whose plan name rarely survives into code verbatim — an
+               endpoint route (route groups split it), a screen, a state, a MODIFIED row,
+               and the ports and adapters, which the plan names by intent and a framework
+               often realises generically (`IRepository<MedicationOrder>` for
+               `IMedicationOrderRepository`). Only the model's own report can say it was
+               done.
+An element is a GAP when it is checked and not found, or when the model's report does not
+say it was done — including when the report does not mention it at all.
+
+THE REPORT. `--reported` takes the `elements` list a generation pass returned —
+[{"element": "<name as listed>", "status": "done|blocked", "reason": "…"}] — and may be
+given more than once; a later report overrides an earlier one for the same element, which
+is how a completion pass's answers replace the first pass's.
+
+`--list-only` returns the element names without scanning, for the generation prompt.
+
+Always exits 0 with a JSON object; the workflow decides what a gap means.
+
+Usage:
+  aw-plan-coverage.py --repo R --plan P --kind backend|frontend [--mode bootstrap|delta]
+                      [--source-path S] [--test-path T] [--reported JSON]... [--list-only]
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+
+IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$")
+TICK = re.compile(r"`([^`]+)`")
+
+DONE = {"done", "generated", "implemented", "ok", "exists", "existing", "complete",
+        "completed", "present", "extended", "modified", "created", "updated"}
+
+# Directories that never hold a lane's own source.
+SKIP_DIRS = {".git", ".hg", ".svn", ".appweaver", "node_modules", "bin", "obj", "dist",
+             "build", "out", "target", ".next", ".nuxt", ".svelte-kit", ".angular",
+             ".turbo", "coverage", "__pycache__", ".venv", "venv", ".gradle", ".idea",
+             ".vs", ".vscode", "specs", "guardrails", "knowledge", "foundations"}
+CODE_EXT = {".cs", ".fs", ".vb", ".java", ".kt", ".kts", ".scala", ".groovy", ".py",
+            ".go", ".rs", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue",
+            ".svelte", ".astro", ".razor", ".cshtml", ".html", ".rb", ".php", ".swift",
+            ".dart", ".ex", ".exs", ".clj", ".sql", ".proto", ".graphql"}
+TEST_DIRS = {"test", "tests", "__tests__", "__test__", "spec", "specs", "e2e", "testing"}
+TEST_FILE = re.compile(r"(\.(test|spec|e2e)\.[^.]+$)|(^test_.*\.py$)|(_test\.(py|go)$)"
+                       r"|(Tests?\.(cs|fs|vb|java|kt|scala)$)|(Spec\.(java|kt|scala|groovy)$)")
+MAX_FILES = 50000
+MAX_BYTES = 2 * 1024 * 1024
+
+
+def emit(obj):
+    # ONE LINE: the engine parses the last line of a script's stdout.
+    sys.stdout.write(json.dumps(obj, separators=(",", ":")) + "\n")
+
+
+def norm_path(p):
+    p = (p or "").replace("\\", "/").strip()
+    while p.startswith("./"):
+        p = p[2:]
+    return "" if p in ("", ".") else p.rstrip("/") + "/"
+
+
+def placeholder(text):
+    """A template slot the plan author never filled — `[Command/Query]`, `I[External]`."""
+    return "[" in text or "]" in text
+
+
+def split_row(line):
+    cells = line.strip().strip("|").split("|")
+    return [c.strip() for c in cells]
+
+
+def is_separator(line):
+    s = line.strip()
+    return s.startswith("|") and set(s.replace("|", "").replace(":", "").strip()) <= {"-"} \
+        and "-" in s
+
+
+def read_plan(path):
+    """The plan's lines with fenced blocks and HTML comments blanked out."""
+    text = open(path, encoding="utf-8").read()
+    text = re.sub(r"<!--.*?-->", lambda m: "\n" * m.group(0).count("\n"), text, flags=re.S)
+    out, fence = [], False
+    for line in text.splitlines():
+        if line.lstrip().startswith("```"):
+            fence = not fence
+            out.append("")
+            continue
+        out.append("" if fence else line)
+    return out
+
+
+def walk_sections(lines):
+    """Yield (h2, h3, kind, payload) for every heading and table row.
+
+    kind is "h2" / "h3" / "h4" with the heading text, or "row" with ({header: cell}).
+    h2 / h3 carry the enclosing headings' text so a caller can key on section numbers
+    ("## 2." / "### 2.2") or names ("## ADDED").
+    """
+    h2 = h3 = ""
+    headers = None
+    for i, line in enumerate(lines):
+        s = line.strip()
+        if s.startswith("#"):
+            headers = None
+            level = len(s) - len(s.lstrip("#"))
+            title = s[level:].strip()
+            if level == 2:
+                h2, h3 = title, ""
+            elif level == 3:
+                h3 = title
+            yield h2, h3, "h%d" % level, title
+            continue
+        if not s.startswith("|"):
+            headers = None
+            continue
+        if is_separator(s):
+            continue
+        nxt = lines[i + 1].strip() if i + 1 < len(lines) else ""
+        if is_separator(nxt):
+            headers = [c.lower() for c in split_row(s)]
+            continue
+        if headers:
+            cells = split_row(s)
+            yield h2, h3, "row", dict(zip(headers, cells))
+
+
+def section_no(title):
+    m = re.match(r"^(\d+(?:\.\d+)?)[.\s]", title + " ")
+    return m.group(1) if m else ""
+
+
+def col(row, prefix):
+    for k, v in row.items():
+        if k.startswith(prefix):
+            return v
+    return ""
+
+
+def first_tick(text):
+    toks = [t for t in TICK.findall(text) if not placeholder(t)]
+    return toks[0].strip() if toks else ""
+
+
+WHOLE_WORD_KINDS = {"entity", "value object"}
+
+
+def extract(lines, kind, mode):
+    """[(name, element_kind, checked)] in plan order, de-duplicated by name."""
+    found, seen = [], set()
+
+    def add(name, ekind, checked):
+        name = re.sub(r"\s+", " ", (name or "").strip())
+        if not name or placeholder(name) or name in seen:
+            return
+        seen.add(name)
+        found.append((name, ekind, bool(checked and IDENT.match(name))))
+
+    for h2, h3, what, payload in walk_sections(lines):
+        n2, n3 = section_no(h2), section_no(h3)
+        h2u = h2.upper()
+        if mode == "delta":
+            if what != "row":
+                continue
+            added, modified = h2u.startswith("ADDED"), h2u.startswith("MODIFIED")
+            if not (added or modified):
+                continue
+            cell = col(payload, "element")
+            ekind = col(payload, "kind").strip().lower() or ("modified" if modified else "")
+            toks = [t.strip() for t in TICK.findall(cell) if not placeholder(t)]
+            if not toks:
+                plain = cell.strip()
+                if plain and not placeholder(plain):
+                    add(plain, ekind or "element", False)
+                continue
+            # A MODIFIED element already exists, so finding its name proves nothing; routes,
+            # screens and states rarely keep their plan name in code.
+            report_only = modified or ekind in ("endpoint", "binding", "screen", "state")
+            for t in toks:
+                add(t, ekind or "element", not report_only)
+            continue
+        if kind == "backend":
+            if what == "h4" and n3 in ("1.3", "2.2"):
+                add(first_tick(payload), "entity" if n3 == "1.3" else "use-case", True)
+            elif what == "h3" and n2 == "3" and not n3:
+                add(first_tick(payload), "endpoint", False)
+            elif what == "row" and n3 == "1.2":
+                add(first_tick(col(payload, "event")), "event", True)
+            elif what == "row" and n3 == "1.4":
+                add(first_tick(col(payload, "value object")), "value object", True)
+            elif what == "row" and n3 == "2.1":
+                add(first_tick(col(payload, "port")), "port", False)
+            elif what == "row" and n3 == "4.1":
+                add(first_tick(col(payload, "adapter")), "adapter", False)
+        else:
+            if what == "row" and n2 == "1":
+                add(first_tick(col(payload, "screen")), "screen", False)
+            elif what == "row" and n2 == "3":
+                add(first_tick(col(payload, "component")), "component", True)
+    return found
+
+
+HASH_COMMENT_EXT = {".py", ".rb", ".ex", ".exs"}
+BLOCK_COMMENT = re.compile(r"/\*.*?\*/|<!--.*?-->|@\*.*?\*@", re.S)
+LINE_COMMENT = re.compile(r"(?<![:\"'])//[^\n]*")
+HASH_COMMENT = re.compile(r"(?m)^\s*#[^\n]*")
+
+
+def strip_comments(text, ext):
+    """Code without its comments, so a doc comment that MENTIONS an element — "returned by
+    GetOrder" — is not taken for the element itself."""
+    text = BLOCK_COMMENT.sub(" ", text)
+    if ext in HASH_COMMENT_EXT:
+        return HASH_COMMENT.sub("", text)
+    return LINE_COMMENT.sub("", text)
+
+
+def is_test_file(rel):
+    parts = rel.split("/")
+    if any(p.lower() in TEST_DIRS for p in parts[:-1]):
+        return True
+    return bool(TEST_FILE.search(parts[-1]))
+
+
+def scan(repo, source_path, test_path, names):
+    """{name: [relative files naming it]} over the lane's source path, tests excluded.
+
+    `names` holds (name, whole) keys: whole is True when the name must appear as a whole
+    word, False when an identifier that STARTS with it counts.
+    """
+    hits = {k: [] for k in names}
+    if not names:
+        return hits
+    patterns = {(n, whole): re.compile(r"(?<![A-Za-z0-9_])" + re.escape(n) +
+                                       (r"(?![A-Za-z0-9_])" if whole else ""))
+                for n, whole in names}
+    base = os.path.join(repo, source_path.rstrip("/")) if source_path else repo
+    if not os.path.isdir(base):
+        return hits
+    tests = norm_path(test_path)
+    src = norm_path(source_path)
+    exclude_tests_dir = tests and tests != src
+    count = 0
+    for dirpath, dirnames, filenames in os.walk(base):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
+        for fn in filenames:
+            if os.path.splitext(fn)[1].lower() not in CODE_EXT:
+                continue
+            full = os.path.join(dirpath, fn)
+            rel = os.path.relpath(full, repo).replace("\\", "/")
+            if exclude_tests_dir and (rel + "/").startswith(tests):
+                continue
+            if is_test_file(os.path.relpath(full, base).replace("\\", "/")):
+                continue
+            count += 1
+            if count > MAX_FILES:
+                return hits
+            try:
+                if os.path.getsize(full) > MAX_BYTES:
+                    continue
+                text = open(full, encoding="utf-8", errors="ignore").read()
+            except OSError:
+                continue
+            text = strip_comments(text, os.path.splitext(fn)[1].lower())
+            for key, rx in patterns.items():
+                if len(hits[key]) < 5 and key[0] in text and rx.search(text):
+                    hits[key].append(rel)
+    return hits
+
+
+def norm_name(s):
+    s = (s or "").replace("`", "")
+    s = re.sub(r"\{([A-Za-z_][A-Za-z0-9_]*)(?::[^}]*)?\}", r"{\1}", s)
+    return re.sub(r"\s+", " ", s).strip().lower()
+
+
+def parse_generated(raw):
+    """The files a generation pass wrote, as a list. `None` means the caller did not say.
+
+    The engine renders a list variable as JSON, so this normally arrives as `[]` or
+    `["a.cs", …]`; a bare comma-separated string is accepted for a caller driving the op
+    by hand. Unparseable input is treated as "did not say" rather than as "wrote nothing",
+    because reading a corrupt list as an empty one would turn a failed pass into an
+    already-implemented verdict.
+    """
+    if raw is None:
+        return None
+    raw = (raw or "").strip()
+    if raw in ("", "[]", "None", "null"):
+        return []
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        return [p.strip() for p in raw.split(",") if p.strip()]
+    if isinstance(data, list):
+        return [str(x).strip() for x in data if str(x).strip()]
+    return None
+
+
+def load_reports(raw_list):
+    """{normalised name: (status, reason)} — later reports win. Unreadable input counts as
+    no report, which leaves every report-only element unconfirmed."""
+    out, readable = {}, False
+    for raw in raw_list or []:
+        raw = (raw or "").strip()
+        if raw in ("", "None", "null"):
+            continue
+        try:
+            data = json.loads(raw)
+        except ValueError:
+            continue
+        if isinstance(data, dict):
+            data = data.get("elements") or []
+        if not isinstance(data, list):
+            continue
+        readable = True
+        for item in data:
+            if isinstance(item, str):
+                out[norm_name(item)] = ("done", "")
+                continue
+            if not isinstance(item, dict):
+                continue
+            name = item.get("element") or item.get("name") or ""
+            if not name:
+                continue
+            status = str(item.get("status") or "").strip().lower()
+            out[norm_name(name)] = (status, str(item.get("reason") or "").strip())
+    return out, readable
+
+
+def main():
+    ap = argparse.ArgumentParser(description="plan element coverage of a lane's code")
+    ap.add_argument("--repo", default=".")
+    ap.add_argument("--plan", required=True)
+    ap.add_argument("--kind", choices=["backend", "frontend"], required=True)
+    ap.add_argument("--mode", default="", help="bootstrap | delta (default: read the plan)")
+    ap.add_argument("--source-path", default="")
+    ap.add_argument("--test-path", default="")
+    ap.add_argument("--reported", action="append", default=[])
+    ap.add_argument("--generated", default=None,
+                    help="the files the generation pass wrote. An EMPTY list is the "
+                         "already-implemented probe: coverage is then judged on the code "
+                         "alone. Omitted entirely, every element is judged both ways.")
+    ap.add_argument("--reserved", default="",
+                    help="comma-separated names the lane's stack already defines in ambient "
+                         "scope. Element names matching one are reported as collisions.")
+    ap.add_argument("--list-only", action="store_true")
+    args = ap.parse_args()
+
+    repo = os.path.abspath(args.repo)
+    plan = args.plan if os.path.isabs(args.plan) else os.path.join(repo, args.plan)
+    base = {"plan": args.plan, "kind": args.kind, "source_path": args.source_path,
+            "test_path": args.test_path}
+
+    if not os.path.isfile(plan):
+        base.update({"ok": False, "outcome": "no-plan",
+                     "plan_exists": False, "mode": args.mode, "total": 0,
+                     "names": [], "names_csv": "", "names_text": "(the plan does not exist)",
+                     "elements": [], "gaps": [], "gap_names": [], "gap_names_csv": "",
+                     "gap_count": 1,
+                     "gaps_text": "the plan %s does not exist" % args.plan,
+                     "message": "plan-coverage: the plan %s does not exist" % args.plan})
+        emit(base)
+        return
+
+    lines = read_plan(plan)
+    mode = args.mode if args.mode in ("bootstrap", "delta") else (
+        "delta" if any(l.strip().upper().startswith("## ADDED") for l in lines) else "bootstrap")
+    elements = extract(lines, args.kind, mode)
+    names = [n for n, _, _ in elements]
+    # NAMES THE STACK ALREADY DEFINES. A plan element called `Route` or `Task` is not a
+    # naming mistake — the plan carries the ubiquitous language and the generator spells it
+    # verbatim — but on a stack whose ambient scope defines the same name, writing it bare
+    # is ambiguous and does not compile (C# CS0104). The conflict is invisible in the file,
+    # because the framework name arrives through an implicit using and appears in no line
+    # of it, so the generator is TOLD which of its own element names are affected.
+    reserved = {r.strip() for r in (args.reserved or "").replace(";", ",").split(",") if r.strip()}
+    collisions = []
+    for n in names:
+        leaf = n.split(".")[-1]
+        if leaf in reserved and leaf not in collisions:
+            collisions.append(leaf)
+    base.update({"plan_exists": True, "mode": mode, "total": len(elements),
+                 "names": names, "names_csv": ", ".join(names),
+                 "collisions": collisions, "collisions_csv": ", ".join(collisions),
+                 "collision_count": len(collisions),
+                 # Prompt-ready: never empty, so the sentence around it still reads.
+                 "collisions_text": (
+                     "%s — each of these is also a type this stack defines in ambient scope, "
+                     "so write it QUALIFIED at every use site" % ", ".join(collisions))
+                 if collisions else "none — no plan element collides with a framework type",
+                 # For a prompt: never empty, so the sentence around it still reads.
+                 "names_text": ", ".join(names) if names else
+                 "(none could be read from the plan — report each element you realise by "
+                 "the name the plan gives it)"})
+
+    if args.list_only:
+        base.update({"ok": True, "outcome": "listed",
+                     "message": "%d plan element(s) listed" % len(elements)})
+        emit(base)
+        return
+
+    def probe_key(name, ekind):
+        return (name.split(".")[-1], mode == "bootstrap" and ekind in WHOLE_WORD_KINDS)
+
+    checked = [n for n, _, c in elements if c]
+    probe = {probe_key(n, k) for n, k, c in elements if c}
+    hits = scan(repo, norm_path(args.source_path), args.test_path, probe)
+    reports, readable = load_reports(args.reported)
+
+    # A pass that wrote NOTHING is either a lane that is already built or one that failed,
+    # and the difference is written in the code, not in what the pass said about itself. So
+    # the report requirement is dropped for that probe: an element no scan can confirm — a
+    # port, an adapter — was confirmed by the run that created it and cannot be confirmed
+    # again without generating. An element the pass explicitly called blocked still counts
+    # against it either way.
+    generated = parse_generated(args.generated)
+    code_only = generated is not None and not generated
+
+    rows, gaps, gap_names = [], [], []
+    for name, ekind, is_checked in elements:
+        files = hits.get(probe_key(name, ekind), []) if is_checked else []
+        status, reason = reports.get(norm_name(name), ("", ""))
+        done = status in DONE
+        why = []
+        if is_checked and not files:
+            why.append("no code under %s names it" % (args.source_path or "the repo"))
+        if status and not done:
+            why.append("reported %s%s" % (status, (": " + reason) if reason else ""))
+        elif not status and not is_checked and not code_only:
+            why.append("not reported done")
+        rows.append({"element": name, "kind": ekind, "checked": is_checked,
+                     "found": bool(files) if is_checked else None, "files": files,
+                     "reported": status or "", "gap": bool(why)})
+        if why:
+            gaps.append("%s (%s) — %s" % (name, ekind, "; ".join(why)))
+            gap_names.append(name)
+
+    total_checked = len(checked)
+    found = sum(1 for r in rows if r["checked"] and r["found"])
+    ok = not gaps
+
+    # WHAT HAPPENED TO THIS LANE, as one word a caller can branch on. "no-plan-elements" is
+    # kept apart from "already-implemented" because they look identical from the file count
+    # and mean opposite things: a plan nothing can be read from proves nothing about the
+    # code, and a pass that wrote no files against one is unexplained, not finished.
+    if not elements:
+        outcome = "no-plan-elements"
+    elif gaps:
+        outcome = "gaps"
+    elif code_only:
+        outcome = "already-implemented"
+    else:
+        outcome = "complete"
+
+    if outcome == "no-plan-elements":
+        msg = ("no plan element could be read from %s — its layout does not follow the "
+               "plan template, so coverage was not checked" % args.plan)
+    elif outcome == "already-implemented":
+        msg = ("this pass wrote no files and every one of the %d plan element(s) is already "
+               "realised under %s — there was nothing left to write"
+               % (len(elements), args.source_path or "the repo"))
+    elif ok:
+        msg = "all %d plan element(s) realised (%d found in code, %d reported done)" % (
+            len(elements), found, len(elements) - total_checked)
+    else:
+        msg = "%d of %d plan element(s) not realised: %s" % (
+            len(gaps), len(elements), "; ".join(gaps))
+    base.update({"ok": ok, "outcome": outcome, "wrote_files": bool(generated),
+                 "judged_on": "code" if code_only else "code and report",
+                 "reported": readable, "checked_on_disk": total_checked,
+                 "found_on_disk": found, "elements": rows, "gaps": gaps,
+                 "gap_names": gap_names, "gap_names_csv": ", ".join(gap_names),
+                 "gap_count": len(gaps),
+                 "gaps_text": "; ".join(gaps) if gaps else "none", "message": msg})
+    emit(base)
+
+
+if __name__ == "__main__":
+    main()