aw-spec-cli 0.1.32 → 0.1.34

package/assets/.appweaver/scripts/python/aw-foundation.py

@@ -66,7 +66,8 @@ Usage:
   aw-foundation.py spec-capture --lane <id> [--kind <k>] (--file <path> | --input <path|text>)
                                 [--app <App>]
       -> {"ok": bool, "spec_path": ".appweaver/foundation/<id>.spec.md", "source": "...",
-          "contract_run": "...", "contract": "...", "client": "...", "settings_text": "...", ...}
+          "contract_write": "...", "contract_run": "...", "contract": "...", "client": "...",
+          "settings_text": "...", ...}
   aw-foundation.py lane-files --source <path> [--test <path>] [--workdir <path>] [--profile <id>]
       -> {"has_files": bool, "count": n, "sample": [...], "generated": [...],
           "root_files": [...], "folders": [...], "workdir": "...", "summary": "...",
@@ -83,8 +84,8 @@ Usage:
           "stale": [...], "note": "..."}
   aw-foundation.py rules-done [--state <repo-relative folder>]  -> {"ok": true, "removed": bool}
   aw-foundation.py pack-lane --name <Foundation> --app <App>
-      -> {"found": bool, "file": "...", "contract_run": "...", "contract": "...",
-          "client": "...", "reason": "..."}
+      -> {"found": bool, "file": "...", "contract_write": "...", "contract_run": "...",
+          "contract": "...", "client": "...", "reason": "..."}
 
 A pack may also carry LANE SETTINGS, `<pack name>.lane.json` beside it: values the lane
 records in stacks.json once the pack is unpacked (see pack_lane).
@@ -205,8 +206,8 @@ LABEL_SEP = "  — "
 MANUAL = "[manual spec]"
 SKIP = "[skip]"
 HEADER_KEYS = ("kind", "profiles", "title", "foundation", "sentinel", "files",
-               "contract_run", "contract", "client")
-# A key may be written with hyphens (`contract-run`); it is read as the underscored name.
+               "contract_write", "contract_run", "contract", "client")
+# A key may be written with hyphens (`contract-write`); it is read as the underscored name.
 HEADER_RE = re.compile(r"^#\s*([a-z][a-z_-]*)\s*:\s*(.*?)\s*$")
 
 
@@ -397,8 +398,8 @@ def resolve_choice(repo, selection, kind="", profile="", ecosystems=None):
 SPEC_LIMIT = 200_000
 
 
-SETTING_LABELS = (("contract_run", "start command"), ("contract", "document URL"),
-                  ("client", "client command"))
+SETTING_LABELS = (("contract_write", "document command"), ("contract_run", "start command"),
+                  ("contract", "document URL"), ("client", "client command"))
 
 
 def capture_spec(repo, lane, kind="", file="", text="", app=""):
@@ -410,8 +411,8 @@ def capture_spec(repo, lane, kind="", file="", text="", app=""):
     shaped like a path (a separator, or a file extension), which is a path that was
     mistyped: capturing it as a fifteen-character spec would build a project from it.
 
-    Also returns the lane settings the spec's header gives — `# contract-run:`,
-    `# contract:` and `# client:`, with `<App>` replaced by `app` — which foundation
+    Also returns the lane settings the spec's header gives — `# contract-write:`,
+    `# contract-run:`, `# contract:` and `# client:`, with `<App>` replaced by `app` — which foundation
     records on the lane once the project is built. They are read here, from the spec as
     given, because the copy opens with a comment and has no header left to read.
     """
@@ -887,7 +888,7 @@ def pack_rules(repo, name, app, out, reference=False, state=MERGE_STATE):
 
 
 LANE_FORMAT = "aw-spec-pack-lane/v1"
-LANE_KEYS = ("contract_run", "contract", "client")
+LANE_KEYS = ("contract_write", "contract_run", "contract", "client")
 
 
 def pack_lane(repo, name, app):
@@ -895,9 +896,11 @@ def pack_lane(repo, name, app):
     sentinel renamed as in the pack's own files.
 
     These are what only the pack knows about the project it scaffolds — chiefly how to
-    start its service on its own to export the API document, which for a solution with
-    an orchestration host is not the lane's `run` command. A pack with no such file has
-    nothing to add, and the lane keeps its stack profile's values.
+    write its service's API document (`contract_write`), or how to start the service on
+    its own to fetch it, which for a solution with an orchestration host is not the lane's
+    `run` command. The backend gates check the code's API against the plan with that
+    document. A pack with no such file has nothing to add, and the lane keeps its stack
+    profile's values.
 
       {"format": "aw-spec-pack-lane/v1",
        "contract_run": "dotnet run --project src/<Sentinel>.Service -- --urls http://localhost:5000",

package/assets/.appweaver/scripts/python/aw-gaps.py

@@ -12,6 +12,9 @@ The checks already tag each finding with the command that closes it (`fix`). Thi
 tag into the routing the caller reports: per-route counts, the ids involved, and a line of
 prose per route that a gate message can print without assembling it itself.
 
+A finding that a requirement has no test naming it is closed by `fix-test-coverage`, which
+writes tests and never code, so it has its own route, `tests`, after the code's.
+
 A finding whose `fix` is missing or unrecognised is NOT quietly folded into the biggest
 bucket. It goes to `review` and is counted there, because a finding nobody can be told to
 close is worse than one routed to the wrong place: the first is visible, the second is not.
@@ -19,7 +22,7 @@ close is worse than one routed to the wrong place: the first is visible, the sec
 Usage:
   aw-gaps.py route --gaps '<json>' [--gaps '<json>']...
       -> {total, implement_count/_refs/_text, plan_count/…, specify_count/…,
-          review_count/…, high_count, summary, routes}
+          tests_count/…, review_count/…, high_count, summary, routes}
 """
 
 import argparse
@@ -27,8 +30,9 @@ import json
 import sys
 
 # The commands a finding can be routed to, in the order a reader should act on them:
-# fix the spec before the plan that realises it, and the plan before the code it maps to.
-ROUTES = ["specify", "plan", "implement", "review"]
+# fix the spec before the plan that realises it, the plan before the code it maps to, and
+# the code before its tests.
+ROUTES = ["specify", "plan", "implement", "tests", "review"]
 
 HOW = {
     "specify": "/appweaver specify {cr} — the delta spec or the model delta is what is missing",
@@ -36,6 +40,8 @@ HOW = {
             "(then /appweaver analyze-plan-delta {cr} and /appweaver implement {cr})",
     "implement": "/appweaver implement {cr} — the code is missing or does not do what the "
                  "change asked",
+    "tests": "/appweaver fix-test-coverage {cr} — no test names these requirements, so "
+             "write their tests",
     "review": "no `fix` command was recorded for these — read them in the report and decide",
 }
 
@@ -62,6 +68,8 @@ def load(raw_list):
 
 def route_of(gap):
     fix = str(gap.get("fix") or "").strip().lower()
+    if "fix-test-coverage" in fix:
+        return "tests"
     # The tag may arrive as a whole command line ("/appweaver plan CR-…"); the verb is what
     # routes, and anything else is unrecognised rather than guessed at.
     for r in ("specify", "plan", "implement"):

package/assets/.appweaver/scripts/python/aw-model-guard.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""
+aw-model-guard — what a whole-file rewrite of a context's domain-model.md must keep.
+
+THE RISK. Two steps re-author the bounded context's domain-model.md whole: specify's
+boot_model_generate and adopt's reverse_model. The engine writes the agent's reply over the
+entire file. From a context's second feature on, that file already holds what other
+features rely on — their aggregate sections, the BR-/XBR- rules their specs cite by id, the
+ledger close-delta keeps — and the prompt's "do not rewrite, renumber or tidy" was the only
+thing between a slip and a sibling spec citing a rule that no longer exists. Nothing reads
+a finished sibling again until its next change, so such a loss stays silent.
+
+THE CHECK. `snapshot` copies the model aside before the step; `check` compares the rewrite
+with that copy. What must survive:
+  - every `## Aggregate: <Name>` section, under exactly that name;
+  - every BR-n and XBR-n, defined once, under the same `##` section, with the same rule
+    text (whitespace, line wrapping, bold and code markers ignored);
+  - each aggregate's `**Serving specs**` names;
+  - the Ubiquitous Language terms, and the other contexts the Context Map names;
+  - every Change History row, cell for cell;
+  - the `**Context version**` value.
+Additions are free: new aggregates, rules, entities, terms, rows and Serving specs names.
+A term's meaning, a Context Map row's other cells, and the prose of entities, value objects
+and events are not compared, because a later feature may legitimately extend them — a new
+event crossing to an existing neighbour context lands in that neighbour's row.
+
+ON A LOSS the model is put back from the copy byte for byte, the rewrite is kept beside it
+as domain-model.rejected.md, and the result lists every loss; the workflow's gate stops on
+it. A clean rewrite deletes the copy. Both commands exit 0 — the gate owns the stop.
+
+NOT RECORDED: template placeholders — a `[bracketed]` aggregate name, rule text, term,
+Serving specs name or Context Map name, and any Change History row with a bracketed cell —
+so a context's first feature, written over the template, is held to nothing but the
+Context version. The engine's MOCK transport writes a stub, not a model, so a mock rewrite
+is reported as skipped rather than checked.
+
+It reads Markdown only, so it is the same check for every stack and for a model reversed
+from legacy code.
+
+Usage:
+  aw-model-guard.py snapshot --model <path> --root <p>
+      -> {ok, model, before, exists, aggregates[], rules, cross_rules, guarded}
+  aw-model-guard.py check --model <path> --root <p>
+      -> {ok, checked, skipped, model, rejected, restored, losses[], loss_count, losses_text,
+          reason}
+"""
+
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+
+BEFORE_NAME = ".domain-model.before.md"
+REJECTED_NAME = "domain-model.rejected.md"
+MOCK_MARK = "<!-- authored by aw-orchestrator MOCK transport -->"
+
+_RULE_BULLET = re.compile(r"^\s*[-*+]\s+\**\s*(X?BR-\d+)\b\**(.*)$")
+_RULE_ROW = re.compile(r"^\s*\|\s*\**\s*(X?BR-\d+)\b\**\s*\|(.*)$")
+_SERVING = re.compile(r"^\s*(?:[-*+]\s+)?\*\*Serving specs(?:\*\*\s*:|:\*\*)\s*(.*)$", re.I)
+_CTX_VERSION = re.compile(r"^\s*(?:[-*+]\s+)?\*\*Context version(?:\*\*\s*:|:\*\*)\s*(.*)$", re.I)
+
+
+def _read(path):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return fh.read()
+    except Exception:
+        return None
+
+
+def _rel(path, root):
+    return os.path.relpath(path, root).replace(os.sep, "/")
+
+
+def _norm(s):
+    """Text as compared: markup that does not change meaning dropped, whitespace collapsed."""
+    s = s.replace("*", "").replace("`", "")
+    return re.sub(r"\s+", " ", s).strip()
+
+
+def _placeholder(s):
+    s = s.strip()
+    return s.startswith("[") and s.endswith("]")
+
+
+def _cells(line):
+    return [c.strip() for c in line.strip().strip("|").split("|")]
+
+
+def _is_separator(line):
+    return bool(re.match(r"^\s*\|[\s|:\-]+\|?\s*$", line))
+
+
+def inventory(text):
+    """Everything in one model that another document or script relies on."""
+    inv = {"aggregates": [], "rules": {}, "dupes": set(), "serving": {}, "terms": {},
+           "context_map": {}, "history": [], "context_version": ""}
+    text = re.sub(r"<!--.*?-->", "", text or "", flags=re.S)
+    section, aggregate, rule, in_fence = "", "", None, False
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        if line.lstrip().startswith("```"):
+            in_fence, rule = not in_fence, None
+            continue
+        if in_fence:
+            continue
+        m = re.match(r"^(#{1,6})\s+(.*)$", line)
+        if m:
+            rule = None
+            if len(m.group(1)) <= 2:
+                section, aggregate = _norm(m.group(2)), ""
+                am = re.match(r"^Aggregate:\s*(.+)$", section, re.I)
+                if am:
+                    aggregate = am.group(1).strip()
+                    if not _placeholder(aggregate) and aggregate not in inv["aggregates"]:
+                        inv["aggregates"].append(aggregate)
+            continue
+        if not line.strip():
+            rule = None
+            continue
+
+        rm = _RULE_BULLET.match(line) or _RULE_ROW.match(line)
+        if rm:
+            rid, rest = rm.group(1), rm.group(2).replace("|", " ")
+            body = re.sub(r"^[\s:\-–—]+", "", _norm(rest))
+            rule = None
+            if not _placeholder(body):
+                if rid in inv["rules"]:
+                    inv["dupes"].add(rid)
+                else:
+                    inv["rules"][rid] = [section, body]
+                    rule = rid
+            continue
+        # A rule's text runs on over wrapped lines and nested bullets until a blank line,
+        # a heading, a table row or the next bullet at its own level.
+        if rule and (re.match(r"^\s{2,}\S", line) or not re.match(r"^\s*([-*+]\s|\|)", line)):
+            inv["rules"][rule][1] = _norm(inv["rules"][rule][1] + " " + line)
+            continue
+        rule = None
+
+        sm = _SERVING.match(line)
+        if sm and aggregate and not _placeholder(aggregate):
+            names = {_norm(n) for n in sm.group(1).split(",")}
+            inv["serving"].setdefault(aggregate, {})
+            for n in names:
+                if n and not _placeholder(n):
+                    inv["serving"][aggregate][n.casefold()] = n
+            continue
+        cm = _CTX_VERSION.match(line)
+        if cm and not inv["context_version"]:
+            inv["context_version"] = _norm(cm.group(1))
+            continue
+
+        low = section.casefold()
+        is_row = line.lstrip().startswith("|") and not _is_separator(line)
+        if low == "ubiquitous language":
+            term = ""
+            if is_row:
+                term = _norm(_cells(line)[0])
+                if term.casefold() == "term":
+                    term = ""
+            else:
+                bm = re.match(r"^\s*[-*+]\s+\*\*(.+?)\*\*", line)
+                term = _norm(bm.group(1)) if bm else ""
+            if term and not _placeholder(term):
+                inv["terms"][term.casefold()] = term
+        elif low == "context map" and is_row:
+            name = _norm(_cells(line)[0])
+            if name and name.casefold() != "other context" and not _placeholder(name):
+                inv["context_map"][name.casefold()] = name
+        elif low == "change history" and is_row:
+            cells = [_norm(c) for c in _cells(line)]
+            if cells and cells[0].casefold() != "context version" \
+                    and not any(_placeholder(c) for c in cells):
+                row = " | ".join(cells)
+                if row not in inv["history"]:
+                    inv["history"].append(row)
+    return inv
+
+
+def losses(before, after):
+    """What `before` held that `after` no longer does, one sentence per item."""
+    out = []
+    for agg in before["aggregates"]:
+        if agg not in after["aggregates"]:
+            out.append(f"aggregate `{agg}` (its `## Aggregate: {agg}` section is gone or renamed)")
+    for rid, (sec, body) in before["rules"].items():
+        if rid not in after["rules"]:
+            out.append(f"{rid} is no longer defined")
+            continue
+        asec, abody = after["rules"][rid]
+        if asec != sec:
+            out.append(f"{rid} moved from `{sec}` to `{asec or 'no section'}`")
+        elif abody != body:
+            out.append(f"{rid}'s rule text changed")
+        if rid in after["dupes"] and rid not in before["dupes"]:
+            out.append(f"{rid} is now defined more than once")
+    for agg, names in before["serving"].items():
+        if agg not in after["aggregates"]:
+            continue
+        kept = after["serving"].get(agg, {})
+        for key, name in names.items():
+            if key not in kept:
+                out.append(f"Serving specs of `{agg}` no longer names `{name}`")
+    for key, term in before["terms"].items():
+        if key not in after["terms"]:
+            out.append(f"Ubiquitous Language term `{term}` is gone")
+    for key, name in before["context_map"].items():
+        if key not in after["context_map"]:
+            out.append(f"the Context Map row for `{name}` is gone")
+    for row in before["history"]:
+        if row not in after["history"]:
+            out.append(f"Change History row `{row}` is gone or changed")
+    if before["context_version"] and after["context_version"] != before["context_version"]:
+        now = after["context_version"]
+        out.append(f"Context version `{before['context_version']}` "
+                   + (f"changed to `{now}`" if now else "is gone"))
+    return out
+
+
+def snapshot(model, root):
+    before = os.path.join(os.path.dirname(model), BEFORE_NAME)
+    text = _read(model)
+    out = {"ok": True, "model": _rel(model, root), "before": "", "exists": text is not None,
+           "aggregates": [], "rules": 0, "cross_rules": 0, "guarded": 0}
+    if text is None:
+        # Nothing to lose. A copy left by an earlier, unfinished run would be compared
+        # against a model it never belonged to, so it goes.
+        if os.path.exists(before):
+            os.remove(before)
+        return out
+    shutil.copyfile(model, before)
+    inv = inventory(text)
+    rules = [r for r in inv["rules"] if r.startswith("BR-")]
+    cross = [r for r in inv["rules"] if r.startswith("XBR-")]
+    out.update({
+        "before": _rel(before, root), "aggregates": inv["aggregates"],
+        "rules": len(rules), "cross_rules": len(cross),
+        "guarded": (len(inv["aggregates"]) + len(inv["rules"])
+                    + sum(len(v) for v in inv["serving"].values()) + len(inv["terms"])
+                    + len(inv["context_map"]) + len(inv["history"])
+                    + (1 if inv["context_version"] else 0)),
+    })
+    return out
+
+
+def check(model, root):
+    before = os.path.join(os.path.dirname(model), BEFORE_NAME)
+    out = {"ok": True, "checked": False, "skipped": "", "model": _rel(model, root),
+           "rejected": "", "restored": False, "losses": [], "loss_count": 0,
+           "losses_text": "", "reason": ""}
+    old = _read(before)
+    if old is None:
+        out["reason"] = "no snapshot — the model did not exist before the rewrite"
+        return out
+    new = _read(model)
+    if new is not None and new.lstrip().startswith(MOCK_MARK):
+        os.remove(before)
+        out.update({"skipped": "mock", "reason": "the rewrite is mock-transport output, not a model"})
+        return out
+    lost = losses(inventory(old), inventory(new or ""))
+    out["checked"] = True
+    if not lost:
+        os.remove(before)
+        out["reason"] = "everything the model held before the rewrite is still there"
+        return out
+    rejected = os.path.join(os.path.dirname(model), REJECTED_NAME)
+    with open(rejected, "w", encoding="utf-8") as fh:
+        fh.write(new or "")
+    shutil.copyfile(before, model)
+    os.remove(before)
+    out.update({"ok": False, "rejected": _rel(rejected, root), "restored": True,
+                "losses": lost, "loss_count": len(lost), "losses_text": "; ".join(lost),
+                "reason": f"{len(lost)} item(s) other features rely on were lost; the model was restored"})
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(description="what a rewrite of domain-model.md must keep")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    for name in ("snapshot", "check"):
+        p = sub.add_parser(name)
+        p.add_argument("--model", required=True)
+        p.add_argument("--root", required=True)
+    args = ap.parse_args()
+    model = os.path.abspath(args.model)
+    root = os.path.abspath(args.root)
+    out = snapshot(model, root) if args.cmd == "snapshot" else check(model, root)
+    sys.stdout.write(json.dumps(out) + "\n")
+
+
+if __name__ == "__main__":
+    main()