aw-spec-cli 0.1.19 → 0.1.21

package/assets/.appweaver/scripts/powershell/aw-xref.ps1

@@ -9,6 +9,9 @@
 #   aw-xref.ps1 concept-upsert   --aggregate X [--source-files a,b,c] [--description D] [--origin ...] [--root DIR]
 #   aw-xref.ps1 concept-overview --aggregate X (--text PROSE | --text-file F) [--root DIR]
 #   aw-xref.ps1 concept-paths    --aggregate X | --feature-dir <dir> [--root DIR] [--bundle knowledge]
+#   aw-xref.ps1 feature-aggregates --feature-dir <dir> [--root DIR]
+#                                (the aggregate(s) a feature acts on: its spec's Acts-on line,
+#                                then the boundary map, then the feature name itself)
 $ErrorActionPreference = "Stop"
 $core = Join-Path $PSScriptRoot "..\python\aw-xref.py"
 & python3 $core @args

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+aw-crstate — ONE definition of "this change has been merged", for every reader of it.
+
+Three places ask the question and each answered it differently: cr-merge-check's
+merged-open fence, cr-recall-check's already-merged guard, and close-delta through it.
+All three tested `cr_id in spec.md` — the id ANYWHERE in the file, including quoted in a
+rationale, and matching a prefix (`CR-001` inside `CR-0011`). A guard that fires on prose
+is a guard nobody can trust, and three copies of it drift.
+
+THE EVIDENCE IS A CHANGE HISTORY ROW. finalize-delta appends one when it merges, carrying
+the change's id in the row's CR cell. So a change is merged when its id is a CELL of such a
+row — matched whole, in a table row, never as a substring of a paragraph.
+
+WHERE IT LOOKS. `spec.md` is per feature, but `domain-model.md` is shared by every feature
+in the bounded context: a sibling feature's merge moves a master THIS delta was authored
+against and leaves nothing in this feature's spec. So the scan covers the context's model
+and every feature's spec, and reports which document carried the evidence.
+
+Importable (the bash payloads load it by path) and a CLI (the PowerShell twins call it), so
+both shells answer from the same code.
+
+Usage:
+  aw-crstate.py merged --cr <id> --doc <path> [--doc <path>…]
+      -> {"merged": bool, "evidence": "<the row>", "document": "<path>"}
+  aw-crstate.py merged-open --cr <id> --feature-dir <p> --context-dir <p>
+      -> {"merged_open": [{cr_id, feature, document, evidence, aggregates, shared, same_feature}], …}
+"""
+
+import argparse
+import glob
+import json
+import os
+import re
+import sys
+
+CR_RX = re.compile(r"CR-\d{8}-\d{6}-[0-9A-Za-z]+")
+TICK_RX = re.compile(r"`([^`]+)`")
+
+
+def read(path):
+    try:
+        return open(path, encoding="utf-8").read()
+    except Exception:
+        return ""
+
+
+def _cells(line):
+    s = line.strip()
+    if not s.startswith("|"):
+        return []
+    return [c.strip() for c in s.strip("|").split("|")]
+
+
+def merged_row(text, cr_id):
+    """The Change History row whose CR cell IS this change, or "" when there is none.
+
+    The cell may carry the bare id or the id with a link or a note beside it, so the test is
+    "the cell contains this id as a whole token" — not "the row mentions it", which is what
+    made a cited id in prose read as a merge.
+    """
+    if not text or not cr_id:
+        return ""
+    for line in text.split("\n"):
+        cells = _cells(line)
+        if len(cells) < 2 or set("".join(cells)) <= set("-: "):
+            continue
+        for cell in cells[1:]:                      # never the leading Version cell
+            if cr_id in CR_RX.findall(cell):
+                return line.strip()
+    return ""
+
+
+def merged_in(paths, cr_id):
+    """(row, document) for the first document whose Change History records this change."""
+    for p in paths:
+        row = merged_row(read(p), cr_id)
+        if row:
+            return row, p
+    return "", ""
+
+
+def aggregates(text):
+    """The `**Aggregates touched**:` header — the list finalize-delta opens sections for."""
+    m = re.search(r"^[ \t]*(?:[-*][ \t]+)?\*\*Aggregates touched(?:\*\*:|:\*\*)[ \t]*(.*)$",
+                  text or "", re.M)
+    if not m:
+        return set()
+    value = re.sub(r"<!--.*?(?:-->|$)", "", m.group(1)).strip()
+    names = TICK_RX.findall(value)
+    if not names:
+        parts = [p.strip() for p in re.split(r"[,;/&]|\band\b", value) if p.strip()]
+        names = [re.match(r"[A-Za-z_][A-Za-z0-9_]*", n).group(0)
+                 for n in parts if re.match(r"[A-Za-z_][A-Za-z0-9_]*", n)]
+    return {n for n in names if not n.startswith(("<", "[")) and not re.match(r"(?i)none\b", n)}
+
+
+def model_delta_of(ctx, cr_id):
+    """A change's model half: beside the master while open, in its archive once closed."""
+    p = os.path.join(ctx, "domain-model.%s.delta.md" % cr_id)
+    if os.path.isfile(p):
+        return read(p)
+    for feat in sorted(os.listdir(ctx)) if os.path.isdir(ctx) else []:
+        a = os.path.join(ctx, feat, "changes", "archive", cr_id, "domain-model.delta.md")
+        if os.path.isfile(a):
+            return read(a)
+    return ""
+
+
+def open_changes(ctx):
+    """{cr_id: feature} for every change OPEN in the context — the directory is the
+    authority, and a model delta with no change directory still counts."""
+    found = {}
+    if not os.path.isdir(ctx):
+        return found
+    for feat in sorted(os.listdir(ctx)):
+        ch = os.path.join(ctx, feat, "changes")
+        if not os.path.isdir(ch):
+            continue
+        for name in sorted(os.listdir(ch)):
+            if name != "archive" and os.path.isdir(os.path.join(ch, name)):
+                found.setdefault(name, feat)
+    for f in sorted(os.listdir(ctx)):
+        m = re.match(r"^domain-model\.(.+)\.delta\.md$", f)
+        if m:
+            found.setdefault(m.group(1), "")
+    return found
+
+
+def merged_open(ctx, feature_dir, cr_id):
+    """Changes that are MERGED into a master and still OPEN — the state in which the masters
+    carry a change the version does not yet reflect.
+
+    A merge in THIS feature moved this delta's own spec, so it blocks whatever it touched.
+    A SIBLING feature's merge moved the shared context model, so it blocks only where it
+    touched an aggregate this delta also names; `shared` carries that answer and a reader
+    that cannot read a delta's aggregates is told so (`unknown`) rather than cleared.
+    """
+    this_feat = os.path.basename(os.path.normpath(feature_dir))
+    mine = aggregates(model_delta_of(ctx, cr_id))
+    docs = {}
+    model_master = os.path.join(ctx, "domain-model.md")
+    if os.path.isfile(model_master):
+        docs[model_master] = ""
+    for spec in sorted(glob.glob(os.path.join(glob.escape(ctx), "*", "spec.md"))):
+        docs[spec] = os.path.basename(os.path.dirname(spec))
+
+    out = []
+    for other, feat in sorted(open_changes(ctx).items()):
+        if other == cr_id:
+            continue
+        row, doc = merged_in(list(docs), other)
+        if not row:
+            continue
+        theirs = aggregates(model_delta_of(ctx, other))
+        same_feature = (feat or docs.get(doc, "")) == this_feat
+        shared = sorted(mine & theirs)
+        out.append({
+            "cr_id": other, "feature": feat or docs.get(doc, ""),
+            "document": os.path.relpath(doc, ctx), "evidence": row,
+            "aggregates": sorted(theirs), "shared": shared,
+            "unknown": not theirs, "same_feature": same_feature,
+            # A sibling's merge blocks only where it moved something this delta also names.
+            "blocking": same_feature or bool(shared) or not theirs,
+        })
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(description="one definition of a merged change")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    m = sub.add_parser("merged")
+    m.add_argument("--cr", required=True)
+    m.add_argument("--doc", action="append", default=[])
+    o = sub.add_parser("merged-open")
+    o.add_argument("--cr", required=True)
+    o.add_argument("--feature-dir", required=True)
+    o.add_argument("--context-dir", required=True)
+    args = ap.parse_args()
+
+    if args.cmd == "merged":
+        row, doc = merged_in(args.doc, args.cr)
+        out = {"merged": bool(row), "evidence": row, "document": doc}
+    else:
+        rows = merged_open(args.context_dir, args.feature_dir, args.cr)
+        blocking = [r for r in rows if r["blocking"]]
+        out = {"merged_open": rows, "blocking": blocking,
+               "blocking_count": len(blocking),
+               "blocking_ids": ", ".join(r["cr_id"] for r in blocking)}
+    sys.stdout.write(json.dumps(out, separators=(",", ":")) + "\n")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+aw-foundation — the part of scaffolding that depends on the LANE MODEL.
+
+A foundation pack is a tree of files and an unpacker that writes it under one output
+directory. That output directory is now a LANE'S SOURCE PATH, so everything a pack
+carries lands inside the subtree its lane owns, and nothing a scaffold produces can
+appear outside a declared lane.
+
+A lane owns TWO subtrees, though — its source path and its test path — and for most
+backend stacks they are siblings rather than nested: .NET keeps `tests/` beside `src/`,
+not inside it. A pack that carries its own test project therefore has one directory
+that does NOT belong under the source path, and unpacking it verbatim would bury the
+tests at `src/tests/`, where the lane does not own them, `dotnet test` does not look for
+them, and every later phase that resolves the lane's test path finds nothing.
+
+So the test tree is LIFTED: whatever the pack placed at `<source path>/<test dir>` is
+merged into the lane's declared test path. The directory name comes from the lane's own
+test path rather than from a list here, which is what makes a lane with a custom
+`test_root` work and a stack whose tests live inside its source a no-op — the two paths
+are then the same subtree and there is nothing to lift.
+
+Called as a CLI by both the bash and the PowerShell actions, so the two answer from one
+implementation rather than from two that have to be kept in step.
+
+Usage:
+  aw-foundation.py redirect-tests --out <lane source path> --test-path <lane test path>
+                                  [--repo <root>] [--force]
+      -> {"moved": n, "conflicts": [...], "from": "...", "to": "...", "message": "..."}
+"""
+
+import argparse
+import json
+import os
+import shutil
+import sys
+
+
+def norm(path):
+    """A repo-relative directory, '/'-separated and '/'-terminated; "" when absent.
+
+    Mirrors aw-stack's `norm_root` for the shapes this reads, so the paths compared here
+    are the same strings the lane model stores. "./" — the repo root as a source path —
+    normalises to "" so that joining it yields the repo itself.
+    """
+    p = (path or "").replace("\\", "/").strip()
+    while p.startswith("./"):
+        p = p[2:]
+    p = p.lstrip("/")
+    if p in ("", "."):
+        return ""
+    return p if p.endswith("/") else p + "/"
+
+
+def emit(payload):
+    sys.stdout.write(json.dumps(payload, separators=(",", ":")) + "\n")
+
+
+def merge_move(src, dest, force):
+    """Move every file under `src` to the matching place under `dest`, keeping what is
+    already there unless `force`. Returns (moved, conflicts) as repo-relative-ish names.
+
+    A merge rather than a rename because the destination legitimately already exists: a
+    second foundation unpacked into the same lane, or a reference pack following the
+    primary one, both add to a test tree rather than replace it.
+    """
+    moved, conflicts = [], []
+    for dirpath, _dirnames, filenames in os.walk(src):
+        for name in sorted(filenames):
+            s = os.path.join(dirpath, name)
+            rel = os.path.relpath(s, src).replace("\\", "/")
+            d = os.path.join(dest, rel)
+            if os.path.exists(d):
+                if not force:
+                    conflicts.append(rel)
+                    continue
+                try:
+                    os.remove(d)
+                except OSError:
+                    conflicts.append(rel)
+                    continue
+            os.makedirs(os.path.dirname(d) or ".", exist_ok=True)
+            shutil.move(s, d)
+            moved.append(rel)
+    # Leave nothing behind but the directories a conflict kept a file in.
+    for dirpath, _dirnames, _filenames in sorted(os.walk(src), reverse=True):
+        try:
+            os.rmdir(dirpath)
+        except OSError:
+            pass
+    return moved, conflicts
+
+
+def redirect_tests(repo, out, test_path, force=False):
+    out_rel, test_rel = norm(out), norm(test_path)
+
+    def skip(why):
+        return {"moved": 0, "conflicts": [], "from": "", "to": test_rel,
+                "redirected": False, "message": why}
+
+    if not test_rel:
+        return skip("the lane declares no test path, so nothing is lifted")
+    # Nested or identical paths mean the pack's own layout is already the lane's: the
+    # tests it carries are inside the subtree they belong in, and moving them would
+    # take them out of it.
+    if out_rel and (test_rel == out_rel or test_rel.startswith(out_rel)):
+        return skip("this lane keeps its tests inside its source path (%s), "
+                    "so the pack's layout is already right" % out_rel)
+
+    # WHAT the pack would have called its test tree, had it placed one: the last segment
+    # of the path the lane keeps tests in. Reading it from the lane rather than from a
+    # fixed list is what makes a custom `test_root` work.
+    seg = test_rel.rstrip("/").rsplit("/", 1)[-1]
+    src = os.path.join(repo, out_rel, seg) if out_rel else os.path.join(repo, seg)
+    dest = os.path.join(repo, test_rel)
+
+    if os.path.abspath(src) == os.path.abspath(dest):
+        return skip("the pack already writes its tests to %s" % test_rel)
+    if not os.path.isdir(src):
+        return skip("this pack carries no %s/ directory, so there are no tests to lift" % seg)
+
+    os.makedirs(dest, exist_ok=True)
+    moved, conflicts = merge_move(src, dest, force)
+    src_rel = "%s%s/" % (out_rel, seg)
+    if conflicts:
+        msg = ("lifted %d test file(s) from %s to the lane's test path %s; %d left in place "
+               "because %s already holds them" % (len(moved), src_rel, test_rel,
+                                                  len(conflicts), test_rel))
+    else:
+        msg = ("lifted %d test file(s) from %s to the lane's test path %s"
+               % (len(moved), src_rel, test_rel))
+    return {"moved": len(moved), "conflicts": conflicts, "from": src_rel, "to": test_rel,
+            "redirected": bool(moved), "message": msg}
+
+
+def main():
+    ap = argparse.ArgumentParser(description="lane-aware scaffolding helpers")
+    ap.add_argument("--repo", default=os.getcwd())
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("redirect-tests")
+    r.add_argument("--out", required=True, help="the lane's source path, where the pack was unpacked")
+    r.add_argument("--test-path", default="", help="the lane's declared test path")
+    r.add_argument("--force", action="store_true")
+    args = ap.parse_args()
+
+    if args.cmd == "redirect-tests":
+        emit(redirect_tests(args.repo, args.out, args.test_path, args.force))
+
+
+if __name__ == "__main__":
+    main()