docassert 0.13.0__tar.gz → 0.14.1__tar.gz

{docassert-0.13.0/docassert.egg-info → docassert-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.13.0
+Version: 0.14.1
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0

{docassert-0.13.0 → docassert-0.14.1}/docassert/__init__.py

@@ -5,4 +5,4 @@ standard: deterministic structural checks that gate a merge, plus optional
 AI-graded semantic checks that advise.
 """
 
-__version__ = "0.13.0"
+__version__ = "0.14.1"

{docassert-0.13.0 → docassert-0.14.1}/docassert/_data/schema/project.schema.json

@@ -7,6 +7,11 @@
   "additionalProperties": true,
   "properties": {
     "kind": { "const": "project" },
+    "repo": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$",
+      "description": "Optional OWNER/NAME of the code repository this project's execution bridge targets."
+    },
     "id": {
       "type": "string",
       "pattern": "^PRJ-\\d{3,}-[A-Z]{2,6}$",

{docassert-0.13.0 → docassert-0.14.1}/docassert/bridge/board.py

@@ -7,7 +7,7 @@ writes converge on the same values.
 """
 from __future__ import annotations
 
-from .gh import GhRunner
+from .gh import GhError, GhRunner
 
 FIELD_SPECS: dict[str, dict] = {
     "Type": {"dataType": "SINGLE_SELECT", "options": ["Feature", "Story"]},
@@ -67,22 +67,28 @@ def ensure_fields(gh: GhRunner, owner: str, number: int) -> dict:
     for name, spec in FIELD_SPECS.items():
         if name in project["fields"]:
             continue
-        if spec["dataType"] == "SINGLE_SELECT":
-            opts = ", ".join(
-                f'{{name: "{o}", color: GRAY, description: ""}}'
-                for o in spec["options"])
-            gh.graphql(
-                "mutation($p: ID!, $n: String!) { createProjectV2Field(input: {"
-                "projectId: $p, dataType: SINGLE_SELECT, name: $n, "
-                f"singleSelectOptions: [{opts}]"
-                "}) { projectV2Field { ... on ProjectV2FieldCommon { id } } } }",
-                p=project["id"], n=name)
-        else:
-            gh.graphql(
-                "mutation($p: ID!, $n: String!) { createProjectV2Field(input: {"
-                "projectId: $p, dataType: TEXT, name: $n"
-                "}) { projectV2Field { ... on ProjectV2FieldCommon { id } } } }",
-                p=project["id"], n=name)
+        try:
+            if spec["dataType"] == "SINGLE_SELECT":
+                opts = ", ".join(
+                    f'{{name: "{o}", color: GRAY, description: ""}}'
+                    for o in spec["options"])
+                gh.graphql(
+                    "mutation($p: ID!, $n: String!) { createProjectV2Field(input: {"
+                    "projectId: $p, dataType: SINGLE_SELECT, name: $n, "
+                    f"singleSelectOptions: [{opts}]"
+                    "}) { projectV2Field { ... on ProjectV2FieldCommon { id } } } }",
+                    p=project["id"], n=name)
+            else:
+                gh.graphql(
+                    "mutation($p: ID!, $n: String!) { createProjectV2Field(input: {"
+                    "projectId: $p, dataType: TEXT, name: $n"
+                    "}) { projectV2Field { ... on ProjectV2FieldCommon { id } } } }",
+                    p=project["id"], n=name)
+        except GhError as exc:
+            # A concurrent sync created it between our read and our write;
+            # an existing field is the outcome we wanted.
+            if "already been taken" not in str(exc).lower():
+                raise
     return get_project(gh, owner, number)
 
 

{docassert-0.13.0 → docassert-0.14.1}/docassert/bridge/ops.py

@@ -45,6 +45,33 @@ def _index(issues: list[dict]) -> dict[str, dict]:
     return out
 
 
+def _converge_duplicates(gh, repo: str, issues: list[dict]) -> tuple[list[dict], list[str]]:
+    """One open issue per bridge marker: racing scaffolds may have created
+    duplicates, so close every open duplicate except the lowest-numbered one
+    and drop the closed ones from the working set. First writer wins."""
+    from collections import defaultdict
+    by_marker: dict[str, list[dict]] = defaultdict(list)
+    for issue in issues:
+        m = MARKER_RE.search(issue.get("body") or "")
+        if m and issue.get("state") == "open":
+            by_marker[m.group(1)].append(issue)
+    actions: list[str] = []
+    losers: set[int] = set()
+    for marker, dupes in by_marker.items():
+        if len(dupes) < 2:
+            continue
+        dupes.sort(key=lambda i: i["number"])
+        for extra in dupes[1:]:
+            G.update_issue(gh, repo, extra["number"], state="closed")
+            G.comment(gh, repo, extra["number"],
+                      f"Duplicate of #{dupes[0]['number']} (bridge marker "
+                      f"{marker}); racing scaffold runs converge on the "
+                      "lowest-numbered issue.")
+            losers.add(extra["number"])
+            actions.append(f"converged duplicate #{extra['number']} -> #{dupes[0]['number']}")
+    return [i for i in issues if i["number"] not in losers], actions
+
+
 def scaffold(plan: BridgePlan, gh: G.GhRunner, repo: str,
              docs_url: str | None = None,
              board_cfg: dict | None = None) -> list[str]:
@@ -59,6 +86,8 @@ def scaffold(plan: BridgePlan, gh: G.GhRunner, repo: str,
         G.ensure_label(gh, repo, name, color, desc)
 
     issues = G.list_issues(gh, repo)
+    issues, converge_actions = _converge_duplicates(gh, repo, issues)
+    actions.extend(converge_actions)
     by_key = _index(issues)
 
     def ensure(key: str, title: str, body: str, label: str) -> dict:

{docassert-0.13.0 → docassert-0.14.1}/docassert/bridge/plan.py

@@ -83,7 +83,8 @@ def _anchors(documents_dir: Path) -> dict[str, dict]:
             continue
         if doc.kind == "project" and doc.id:
             out[doc.id] = {"code": str(doc.frontmatter.get("code", "")),
-                           "name": str(doc.frontmatter.get("name", ""))}
+                           "name": str(doc.frontmatter.get("name", "")),
+                           "repo": str(doc.frontmatter.get("repo", "") or "")}
     return out
 
 
@@ -155,10 +156,41 @@ def build_bridge_plan(documents_dir: str | Path = "documents") -> BridgePlan:
                                  "reason": "; ".join(problems)})
             continue
         plan.projects.append({"id": proj_id, "code": code, "name": meta["name"],
+                              "repo": meta.get("repo", ""),
                               "features": list(features.values())})
     return plan
 
 
+def filter_plan(plan: BridgePlan, project: str) -> BridgePlan:
+    """A plan reduced to one project (matched by id or code). Unknown ids
+    yield an empty plan whose skipped list explains why."""
+    key = project.strip()
+    keep = [p for p in plan.projects
+            if p["id"] == key or p["code"] == key]
+    out = BridgePlan(projects=keep,
+                     skipped=[s for s in plan.skipped if s["id"] == key])
+    if not keep and not out.skipped:
+        out.skipped.append({"id": key, "reason": "no such project in the plan"})
+    return out
+
+
+def plans_by_repo(plan: BridgePlan) -> dict[str, BridgePlan]:
+    """Group a plan by each project's mapped repository (the `repo` field on
+    the project anchor). Projects sharing a repo share one sub-plan, so
+    reconciliation in that repo sees the union of their managed ids.
+    Raises ValueError naming any project without a mapping."""
+    unmapped = [p["id"] for p in plan.projects if not p.get("repo")]
+    if unmapped:
+        raise ValueError(
+            "no repo mapping on project anchor(s): " + ", ".join(unmapped)
+            + " (add `repo: OWNER/NAME` to project.md or pass --repo)")
+    groups: dict[str, BridgePlan] = {}
+    for proj in plan.projects:
+        groups.setdefault(proj["repo"],
+                          BridgePlan(skipped=plan.skipped)).projects.append(proj)
+    return groups
+
+
 def feature_title(f: Feature) -> str:
     return f"[{f.id}] {_title(f.text)}"
 

{docassert-0.13.0 → docassert-0.14.1}/docassert/cli.py

@@ -238,7 +238,7 @@ def cmd_pages(args: argparse.Namespace) -> int:
         data = _json.loads(Path(args.execution).read_text())
         for proj in data.get("projects", []):
             execution[proj["id"]] = {**proj, "scope": data.get("scope"),
-                                     "repo": data.get("repo")}
+                                     "repo": proj.get("repo") or data.get("repo")}
 
     plist = projects_mod.load_projects(docs_dir)
     for p in plist:
@@ -306,10 +306,30 @@ def cmd_bridge(args: argparse.Namespace) -> int:
     Scope flows documents -> GitHub only; the bridge never edits documents."""
     from .bridge import build_bridge_plan, ops
     from .bridge import gh as ghmod
+    from .bridge.plan import filter_plan, plans_by_repo
 
     plan = build_bridge_plan(args.documents_dir)
+    if getattr(args, "project", None):
+        plan = filter_plan(plan, args.project)
     gh = ghmod.DryRunner() if getattr(args, "dry_run", False) else ghmod.GhRunner()
 
+    # Repo resolution: an explicit --repo applies the whole plan to one
+    # repository (single-repo portfolios, back-compatible); without it, each
+    # project routes to the repo mapped on its anchor.
+    if args.action != "create-board":
+        if args.repo:
+            repo_plans = {args.repo: plan}
+        else:
+            try:
+                repo_plans = plans_by_repo(plan)
+            except ValueError as exc:
+                print(f"docassert bridge: {exc}", file=sys.stderr)
+                return 2
+            if not repo_plans and plan.skipped:
+                for s in plan.skipped:
+                    print(f"docassert bridge: skipped {s['id']}: {s['reason']}")
+                return 0
+
     if args.action == "create-board":
         from .bridge import board as board_mod
         token = os.environ.get(args.board_token_env, "")
@@ -329,30 +349,46 @@ def cmd_bridge(args: argparse.Namespace) -> int:
                   "(needed for --project-number)", file=sys.stderr)
             return 2
         bgh = gh if isinstance(gh, ghmod.DryRunner) else ghmod.GhRunner(token=token)
-        board_cfg = {"gh": bgh, "owner": args.project_owner or args.repo.split("/")[0],
+        owner = args.project_owner or next(iter(repo_plans)).split("/")[0]
+        board_cfg = {"gh": bgh, "owner": owner,
                      "number": args.project_number, "init": args.init_board}
 
     if args.action == "scaffold":
-        actions = ops.scaffold(plan, gh, args.repo, docs_url=args.docs_url,
-                               board_cfg=board_cfg)
-        for a in actions:
-            print(f"docassert bridge: {a}")
+        for repo, sub in repo_plans.items():
+            actions = ops.scaffold(sub, gh, repo, docs_url=args.docs_url,
+                                   board_cfg=board_cfg)
+            for a in actions:
+                print(f"docassert bridge: [{repo}] {a}")
         if isinstance(gh, ghmod.DryRunner):
             print(f"docassert bridge: dry run — {len(gh.planned)} mutation(s) planned")
             for m in gh.planned:
                 print(f"  {m}")
         return 0
     if args.action == "reconcile":
-        lines, code = ops.reconcile(plan, gh, args.repo)
-        for line in lines:
-            print(f"docassert bridge: {line}")
-        return code
+        worst = 0
+        for repo, sub in repo_plans.items():
+            lines, code = ops.reconcile(sub, gh, repo)
+            for line in lines:
+                print(f"docassert bridge: [{repo}] {line}")
+            worst = max(worst, code)
+        return worst
     if args.action == "status":
-        data = ops.status(plan, gh, args.repo)
-        sys.stdout.write(ops.to_json(data) if args.json else
-                         ops.render_status(data) + "\n")
+        merged: dict = {"repo": None, "projects": [], "scope": {"unverified": [], "orphaned": []}}
+        for repo, sub in repo_plans.items():
+            data = ops.status(sub, gh, repo)
+            for proj in data.get("projects", []):
+                proj["repo"] = repo
+                merged["projects"].append(proj)
+            for key in ("unverified", "orphaned"):
+                for item in data.get("scope", {}).get(key, []):
+                    item["repo"] = repo
+                    merged["scope"][key].append(item)
+        if len(repo_plans) == 1:
+            merged["repo"] = next(iter(repo_plans))
+        sys.stdout.write(ops.to_json(merged) if args.json else
+                         ops.render_status(merged) + "\n")
         if args.json and args.out:
-            Path(args.out).write_text(ops.to_json(data))
+            Path(args.out).write_text(ops.to_json(merged))
         return 0
     print(f"docassert bridge: unknown action {args.action!r}", file=sys.stderr)
     return 2
@@ -441,7 +477,9 @@ def main(argv: list[str] | None = None) -> int:
     b = sub.add_parser("bridge", help="Execution bridge: scaffold and police the GitHub board from approved stories.")
     b.add_argument("action", choices=["scaffold", "reconcile", "status", "create-board"],
                    help="scaffold: docs -> issues/board · reconcile: police the board · status: delivery figures.")
-    b.add_argument("--repo", required=True, help="Target GitHub repo (OWNER/NAME) holding the issues.")
+    b.add_argument("--repo", help="Target GitHub repo (OWNER/NAME) for the whole plan; "
+                   "omit to route each project to the `repo:` on its anchor.")
+    b.add_argument("--project", help="Scope to one project (PRJ-NNN-CODE id or CODE).")
     b.add_argument("--docs-url", help="Base URL of the documents repo, for source links in issue bodies.")
     b.add_argument("--dry-run", action="store_true", help="Print planned mutations without executing them.")
     b.add_argument("--json", action="store_true", help="status: emit JSON.")

{docassert-0.13.0 → docassert-0.14.1}/docassert/status/render.py

@@ -248,7 +248,7 @@ def render_html(model) -> str:
         bad = scope.get("unverified", []) + scope.get("orphaned", [])
         if bad:
             items = "".join(
-                f'<li><a href="https://github.com/{esc(ex.get("repo", ""))}/issues/{i["number"]}">#{i["number"]}</a> {esc(i["title"])}</li>'
+                f'<li><a href="https://github.com/{esc(i.get("repo") or ex.get("repo") or "")}/issues/{i["number"]}">#{i["number"]}</a> {esc(i["title"])}</li>'
                 for i in bad)
             execution_html += (
                 f'<section><h2 style="color:var(--bad)">Scope · {len(bad)} unmatched item(s)</h2>'

{docassert-0.13.0 → docassert-0.14.1/docassert.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.13.0
+Version: 0.14.1
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0

{docassert-0.13.0 → docassert-0.14.1}/tests/test_bridge.py

@@ -349,3 +349,124 @@ def test_status_includes_scope_classification(tmp_path):
     assert data["repo"] == "o/r"
     assert [i["number"] for i in data["scope"]["unverified"]] == [2]
     assert [i["doc"] for i in data["scope"]["orphaned"]] == ["TST-US-999"]
+
+
+# ── project filter and per-repo mapping (ENG-US-001 / ENG-US-002) ────────────
+from docassert.bridge.plan import filter_plan, plans_by_repo  # noqa: E402
+
+ANCHOR2 = """---
+kind: project
+id: PRJ-002-TWO
+code: TWO
+name: Second Project
+sponsor: S
+status: active
+repo: owner/two-repo
+---
+
+## Overview
+
+x
+
+## Scope
+
+x
+"""
+
+PRD2 = PRD.replace("PRJ-001-TST", "PRJ-002-TWO").replace("TST", "TWO")
+STORIES2 = STORIES.replace("PRJ-001-TST", "PRJ-002-TWO").replace("TST", "TWO")
+
+
+def _two_project_tree(tmp_path, repo_one="owner/one-repo"):
+    docs = _tree(tmp_path)
+    if repo_one:
+        anchor = docs / "PRJ-001-TST" / "project.md"
+        anchor.write_text(anchor.read_text().replace(
+            "status: active", f"status: active\nrepo: {repo_one}"), encoding="utf-8")
+    d = docs / "PRJ-002-TWO"
+    d.mkdir()
+    (d / "project.md").write_text(ANCHOR2, encoding="utf-8")
+    (d / "prd.md").write_text(PRD2, encoding="utf-8")
+    (d / "user-story.md").write_text(STORIES2.format(status="approved"), encoding="utf-8")
+    return docs
+
+
+def test_filter_plan_by_id_and_code(tmp_path):
+    plan = build_bridge_plan(_two_project_tree(tmp_path))
+    assert len(plan.projects) == 2
+    only = filter_plan(plan, "PRJ-002-TWO")
+    assert [p["id"] for p in only.projects] == ["PRJ-002-TWO"]
+    by_code = filter_plan(plan, "TST")
+    assert [p["code"] for p in by_code.projects] == ["TST"]
+    missing = filter_plan(plan, "PRJ-999-NOPE")
+    assert not missing.projects and missing.skipped
+
+
+def test_plans_by_repo_routes_each_project(tmp_path):
+    plan = build_bridge_plan(_two_project_tree(tmp_path))
+    groups = plans_by_repo(plan)
+    assert set(groups) == {"owner/one-repo", "owner/two-repo"}
+    assert [p["id"] for p in groups["owner/one-repo"].projects] == ["PRJ-001-TST"]
+    assert [p["id"] for p in groups["owner/two-repo"].projects] == ["PRJ-002-TWO"]
+
+
+def test_plans_by_repo_shares_a_repo_as_a_union(tmp_path):
+    docs = _two_project_tree(tmp_path)
+    anchor = docs / "PRJ-002-TWO" / "project.md"
+    anchor.write_text(anchor.read_text().replace("owner/two-repo", "owner/one-repo"),
+                      encoding="utf-8")
+    plan = build_bridge_plan(docs)
+    groups = plans_by_repo(plan)
+    assert set(groups) == {"owner/one-repo"}
+    union = groups["owner/one-repo"]
+    assert len(union.projects) == 2
+    # both projects' ids are managed, so neither would be orphaned in reconcile
+    assert any(i.startswith("TST-") for i in union.managed_ids)
+    assert any(i.startswith("TWO-") for i in union.managed_ids)
+
+
+def test_plans_by_repo_names_unmapped_projects(tmp_path):
+    plan = build_bridge_plan(_two_project_tree(tmp_path, repo_one=None))
+    try:
+        plans_by_repo(plan)
+        raise AssertionError("expected ValueError")
+    except ValueError as exc:
+        assert "PRJ-001-TST" in str(exc) and "--repo" in str(exc)
+
+
+def test_anchor_without_repo_keeps_single_repo_mode_working(tmp_path):
+    # the original single-repo path: no repo fields, explicit --repo, unchanged
+    plan = build_bridge_plan(_tree(tmp_path))
+    assert plan.projects[0].get("repo", "") == ""
+    gh = FakeGh()
+    ops.scaffold(plan, gh, "o/r", docs_url=None)
+    assert any("issues" in " ".join(c) for c in gh.calls)
+
+
+# ── concurrency safety (ENG-PR-006) ──────────────────────────────────────────
+def test_scaffold_converges_racing_duplicates(tmp_path):
+    plan = build_bridge_plan(_tree(tmp_path))
+    fid = plan.features[0].id
+    dupes = [_mk_issue(5, fid), _mk_issue(9, fid)]
+    gh = FakeGh(issues=dupes)
+    actions = ops.scaffold(plan, gh, "o/r", docs_url=None)
+    assert any("converged duplicate #9" in a for a in actions)
+    patches = [c for c in gh.calls if "repos/o/r/issues/9" in " ".join(c)
+               and "state=closed" in " ".join(c)]
+    assert patches, "the higher-numbered duplicate is closed"
+
+
+def test_ensure_fields_tolerates_existing_field():
+    gh = BoardGh()
+    original = gh.graphql
+
+    def racing(query, **kw):
+        if "createProjectV2Field" in query:
+            from docassert.bridge.gh import GhError
+            raise GhError('[{"message": "Name has already been taken"}]')
+        return original(query, **kw)
+
+    gh.graphql = racing
+    from docassert.bridge import board
+    project = board.ensure_fields(gh, "o", 1)   # must not raise
+    assert project["id"]