docassert 0.8.0__tar.gz → 0.9.0__tar.gz

{docassert-0.8.0/docassert.egg-info → docassert-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.8.0
+Version: 0.9.0
 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.8.0 → docassert-0.9.0}/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.8.0"
+__version__ = "0.9.0"

docassert-0.9.0/docassert/bridge/board.py

@@ -0,0 +1,126 @@
+"""Projects v2 board operations (require a token with the `project` scope).
+
+The board is a *view* over the bridge-managed issues: every Feature and Story
+issue becomes a project item carrying Type, Doc, and PMO Project fields. All
+mutations are idempotent: re-adding an existing item returns it, and field
+writes converge on the same values.
+"""
+from __future__ import annotations
+
+from .gh import GhRunner
+
+FIELD_SPECS: dict[str, dict] = {
+    "Type": {"dataType": "SINGLE_SELECT", "options": ["Feature", "Story"]},
+    "Doc": {"dataType": "TEXT"},
+    "PMO Project": {"dataType": "TEXT"},
+}
+
+_FIELDS_QUERY = """
+query($owner: String!, $number: Int!) {
+  user(login: $owner) {
+    projectV2(number: $number) {
+      id
+      title
+      fields(first: 30) {
+        nodes {
+          ... on ProjectV2FieldCommon { id name dataType }
+          ... on ProjectV2SingleSelectField { id name dataType options { id name } }
+        }
+      }
+    }
+  }
+}
+"""
+
+
+def create_project(gh: GhRunner, title: str) -> dict:
+    viewer = gh.graphql("query { viewer { id login } }")["viewer"]
+    data = gh.graphql(
+        """
+        mutation($owner: ID!, $title: String!) {
+          createProjectV2(input: {ownerId: $owner, title: $title}) {
+            projectV2 { id number title }
+          }
+        }
+        """,
+        owner=viewer["id"], title=title)
+    return data["createProjectV2"]["projectV2"]
+
+
+def get_project(gh: GhRunner, owner: str, number: int) -> dict:
+    proj = gh.graphql(_FIELDS_QUERY, owner=owner, number=number)["user"]["projectV2"]
+    fields = {}
+    for node in proj["fields"]["nodes"]:
+        if not node:
+            continue
+        fields[node["name"]] = {
+            "id": node["id"],
+            "dataType": node.get("dataType"),
+            "options": {o["name"]: o["id"] for o in node.get("options", [])},
+        }
+    return {"id": proj["id"], "title": proj["title"], "fields": fields}
+
+
+def ensure_fields(gh: GhRunner, owner: str, number: int) -> dict:
+    """Create any missing bridge fields, then return the refreshed project."""
+    project = get_project(gh, owner, number)
+    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)
+    return get_project(gh, owner, number)
+
+
+def add_item(gh: GhRunner, project_id: str, content_id: str) -> str:
+    data = gh.graphql(
+        "mutation($p: ID!, $c: ID!) { addProjectV2ItemById(input: {"
+        "projectId: $p, contentId: $c}) { item { id } } }",
+        p=project_id, c=content_id)
+    return data["addProjectV2ItemById"]["item"]["id"]
+
+
+def set_text(gh: GhRunner, project_id: str, item_id: str, field_id: str,
+             value: str) -> None:
+    gh.graphql(
+        "mutation($p: ID!, $i: ID!, $f: ID!, $v: String!) {"
+        "updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, "
+        "fieldId: $f, value: {text: $v}}) { projectV2Item { id } } }",
+        p=project_id, i=item_id, f=field_id, v=value)
+
+
+def set_option(gh: GhRunner, project_id: str, item_id: str, field_id: str,
+               option_id: str) -> None:
+    gh.graphql(
+        "mutation($p: ID!, $i: ID!, $f: ID!, $o: String!) {"
+        "updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, "
+        "fieldId: $f, value: {singleSelectOptionId: $o}}) "
+        "{ projectV2Item { id } } }",
+        p=project_id, i=item_id, f=field_id, o=option_id)
+
+
+def sync_items(gh: GhRunner, project: dict, entries: list[dict]) -> int:
+    """entries: [{node_id, doc_id, type ('Feature'|'Story'), pmo_project}]."""
+    f = project["fields"]
+    type_field, doc_field, pmo_field = f["Type"], f["Doc"], f["PMO Project"]
+    for e in entries:
+        item = add_item(gh, project["id"], e["node_id"])
+        set_option(gh, project["id"], item, type_field["id"],
+                   type_field["options"][e["type"]])
+        set_text(gh, project["id"], item, doc_field["id"], e["doc_id"])
+        set_text(gh, project["id"], item, pmo_field["id"], e["pmo_project"])
+    return len(entries)

{docassert-0.8.0 → docassert-0.9.0}/docassert/bridge/gh.py

@@ -15,11 +15,22 @@ class GhError(RuntimeError):
 
 
 class GhRunner:
-    """Executes gh commands. Tests substitute a fake with the same interface."""
+    """Executes gh commands. Tests substitute a fake with the same interface.
+
+    `token` overrides GH_TOKEN for this runner only, so board operations can
+    use the project-scoped credential while issue operations keep the
+    default one.
+    """
+
+    def __init__(self, token: str | None = None) -> None:
+        self._env: dict[str, str] | None = None
+        if token:
+            import os
+            self._env = dict(os.environ, GH_TOKEN=token)
 
     def run(self, args: list[str], input_: str | None = None) -> str:
         proc = subprocess.run(["gh", *args], capture_output=True, text=True,
-                              input=input_)
+                              input=input_, env=self._env)
         if proc.returncode != 0:
             raise GhError(proc.stderr.strip() or f"gh {' '.join(args)} failed")
         return proc.stdout
@@ -44,7 +55,8 @@ class DryRunner(GhRunner):
 
     MUTATING = ("-X POST", "-X PATCH", "-X PUT", "-X DELETE", "mutation")
 
-    def __init__(self) -> None:
+    def __init__(self, token: str | None = None) -> None:
+        super().__init__(token)
         self.planned: list[str] = []
 
     def run(self, args: list[str], input_: str | None = None) -> str:
@@ -110,5 +122,9 @@ def add_sub_issue(gh: GhRunner, parent_node: str, child_node: str) -> None:
     try:
         gh.graphql(q, p=parent_node, c=child_node)
     except GhError as exc:
-        if "already" not in str(exc).lower():   # re-link is fine
+        # An existing identical link is success, not failure. GitHub words it
+        # several ways ("duplicate sub-issues", "may only have one parent").
+        msg = str(exc).lower()
+        if not any(s in msg for s in ("already", "duplicate sub-issue",
+                                      "only have one parent")):
             raise

{docassert-0.8.0 → docassert-0.9.0}/docassert/bridge/ops.py

@@ -46,8 +46,14 @@ def _index(issues: list[dict]) -> dict[str, dict]:
 
 
 def scaffold(plan: BridgePlan, gh: G.GhRunner, repo: str,
-             docs_url: str | None = None) -> list[str]:
-    """Make the repo's issues match the plan. Returns human-readable actions."""
+             docs_url: str | None = None,
+             board_cfg: dict | None = None) -> list[str]:
+    """Make the repo's issues match the plan. Returns human-readable actions.
+
+    board_cfg (optional): {"gh": GhRunner with project scope, "owner": login,
+    "number": int, "init": bool} — mirrors every managed issue onto the
+    Projects v2 board with Type/Doc/PMO Project fields.
+    """
     actions: list[str] = []
     for name, (color, desc) in LABELS.items():
         G.ensure_label(gh, repo, name, color, desc)
@@ -80,6 +86,28 @@ def scaffold(plan: BridgePlan, gh: G.GhRunner, repo: str,
             if pnode and cnode:
                 G.add_sub_issue(gh, pnode, cnode)
 
+    if board_cfg:
+        from . import board as B
+        bgh = board_cfg["gh"]
+        if board_cfg.get("init"):
+            project = B.ensure_fields(bgh, board_cfg["owner"], board_cfg["number"])
+            actions.append(f"board: fields ensured on '{project['title']}'")
+        else:
+            project = B.get_project(bgh, board_cfg["owner"], board_cfg["number"])
+        entries = []
+        for f in plan.features:
+            issue = by_key.get(f.id)
+            if issue and issue.get("node_id"):
+                entries.append({"node_id": issue["node_id"], "doc_id": f.id,
+                                "type": "Feature", "pmo_project": f.project})
+            for s in f.stories:
+                sissue = by_key.get(s.id)
+                if sissue and sissue.get("node_id"):
+                    entries.append({"node_id": sissue["node_id"], "doc_id": s.id,
+                                    "type": "Story", "pmo_project": f.project})
+        n = B.sync_items(bgh, project, entries)
+        actions.append(f"board: {n} item(s) synced to '{project['title']}'")
+
     for sk in plan.skipped:
         actions.append(f"skipped {sk['id']}: {sk['reason']}")
     return actions

{docassert-0.8.0 → docassert-0.9.0}/docassert/cli.py

@@ -300,8 +300,31 @@ def cmd_bridge(args: argparse.Namespace) -> int:
     plan = build_bridge_plan(args.documents_dir)
     gh = ghmod.DryRunner() if getattr(args, "dry_run", False) else ghmod.GhRunner()
 
+    if args.action == "create-board":
+        from .bridge import board as board_mod
+        token = os.environ.get(args.board_token_env, "")
+        if not token and not getattr(args, "dry_run", False):
+            print(f"docassert bridge: no token in ${args.board_token_env}", file=sys.stderr)
+            return 2
+        bgh = gh if isinstance(gh, ghmod.DryRunner) else ghmod.GhRunner(token=token)
+        proj = board_mod.create_project(bgh, args.title or "PMO board")
+        print(f"docassert bridge: created project #{proj.get('number')} '{proj.get('title')}'")
+        return 0
+
+    board_cfg = None
+    if args.project_number:
+        token = os.environ.get(args.board_token_env, "")
+        if not token and not getattr(args, "dry_run", False):
+            print(f"docassert bridge: no token in ${args.board_token_env} "
+                  "(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],
+                     "number": args.project_number, "init": args.init_board}
+
     if args.action == "scaffold":
-        actions = ops.scaffold(plan, gh, args.repo, docs_url=args.docs_url)
+        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}")
         if isinstance(gh, ghmod.DryRunner):
@@ -405,13 +428,19 @@ 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"],
+    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("--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.")
     b.add_argument("--out", help="status --json: also write to this path.")
+    b.add_argument("--title", help="create-board: the new project's title.")
+    b.add_argument("--project-owner", help="Board owner login (default: the repo owner).")
+    b.add_argument("--project-number", type=int, help="Projects v2 board number to sync items onto.")
+    b.add_argument("--init-board", action="store_true", help="Ensure the Type/Doc/PMO Project fields exist.")
+    b.add_argument("--board-token-env", default="PROJECTS_TOKEN",
+                   help="Env var holding the project-scoped token (default: PROJECTS_TOKEN).")
     docs_dir_opt(b)
     b.set_defaults(func=cmd_bridge)
 

{docassert-0.8.0 → docassert-0.9.0/docassert.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.8.0
+Version: 0.9.0
 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.8.0 → docassert-0.9.0}/docassert.egg-info/SOURCES.txt

@@ -90,6 +90,7 @@ docassert/_data/templates/status-report.template.md
 docassert/_data/templates/test-cases.template.md
 docassert/_data/templates/user-story.template.md
 docassert/bridge/__init__.py
+docassert/bridge/board.py
 docassert/bridge/gh.py
 docassert/bridge/ops.py
 docassert/bridge/plan.py

{docassert-0.8.0 → docassert-0.9.0}/tests/test_bridge.py

@@ -153,9 +153,7 @@ def test_scaffold_creates_then_is_idempotent(tmp_path):
     gh = FakeGh()
     actions = ops.scaffold(plan, gh, "o/r")
     assert sum(1 for a in actions if a.startswith("created")) == 5  # 2 feat + 3 stories
-    # second run against the issues the first created
-    issues = [_mk_issue(101, "TST-PR-001", feature_title(plan.features[0]))]
-    # simulate full existing state: everything exists with correct title/body
+    # second run: simulate full existing state with correct titles/bodies
     existing = []
     for i, f in enumerate(plan.features):
         e = _mk_issue(200 + i, f.id, feature_title(f))
@@ -222,3 +220,103 @@ def test_status_counts_closed_stories(tmp_path):
     assert feats["TST-PR-001"]["stories_closed"] == 1
     assert feats["TST-PR-001"]["stories_total"] == 2
     assert "1/2" in ops.render_status(data)
+
+
+def test_scaffold_tolerates_existing_sub_issue_link(tmp_path):
+    """GitHub's duplicate-link error (observed live 2026-07-02) is success."""
+    from docassert.bridge.gh import GhError
+
+    class LinkedGh(FakeGh):
+        def graphql(self, query, **vars_):
+            raise GhError("gh: Failed to add sub-issue #2 to parent #1. "
+                          "Issue may not contain duplicate sub-issues and "
+                          "Sub issue may only have one parent")
+
+    plan = build_bridge_plan(_tree(tmp_path))
+    gh = LinkedGh()
+    ops.scaffold(plan, gh, "o/r")   # must not raise
+
+
+def test_add_sub_issue_still_raises_on_real_errors(tmp_path):
+    from docassert.bridge.gh import GhError, add_sub_issue
+
+    class BoomGh(FakeGh):
+        def graphql(self, query, **vars_):
+            raise GhError("gh: Something else entirely")
+
+    import pytest
+    with pytest.raises(GhError):
+        add_sub_issue(BoomGh(), "N1", "N2")
+
+
+# ── board ops ────────────────────────────────────────────────────────────────
+class BoardGh(FakeGh):
+    """GraphQL router for Projects v2 shapes."""
+
+    def __init__(self, existing_fields=()):
+        super().__init__()
+        self.gql: list[str] = []
+        self._fields = list(existing_fields)
+
+    def graphql(self, query, **vars_):
+        self.gql.append(query)
+        if "viewer" in query:
+            return {"viewer": {"id": "U1", "login": "tester"}}
+        if "createProjectV2(" in query:
+            return {"createProjectV2": {"projectV2": {"id": "P1", "number": 7,
+                                                      "title": vars_.get("title")}}}
+        if "projectV2(number" in query:
+            nodes = [{"id": f"F-{n}", "name": n, "dataType": "TEXT"}
+                     for n in self._fields]
+            if "Type" in self._fields:
+                for node in nodes:
+                    if node["name"] == "Type":
+                        node["dataType"] = "SINGLE_SELECT"
+                        node["options"] = [{"id": "O1", "name": "Feature"},
+                                           {"id": "O2", "name": "Story"}]
+            return {"user": {"projectV2": {"id": "P1", "title": "Board",
+                                           "fields": {"nodes": nodes}}}}
+        if "createProjectV2Field" in query:
+            self._fields.append(vars_["n"])
+            return {"createProjectV2Field": {"projectV2Field": {"id": "F-new"}}}
+        if "addProjectV2ItemById" in query:
+            return {"addProjectV2ItemById": {"item": {"id": "I1"}}}
+        if "updateProjectV2ItemFieldValue" in query:
+            return {"updateProjectV2ItemFieldValue": {"projectV2Item": {"id": "I1"}}}
+        return {}
+
+
+def test_create_project():
+    from docassert.bridge import board
+    gh = BoardGh()
+    proj = board.create_project(gh, "Refuge for Humans")
+    assert proj["number"] == 7 and proj["title"] == "Refuge for Humans"
+
+
+def test_ensure_fields_creates_missing():
+    from docassert.bridge import board
+    gh = BoardGh(existing_fields=["Status"])
+    project = board.ensure_fields(gh, "tester", 7)
+    assert set(project["fields"]) >= {"Type", "Doc", "PMO Project"}
+
+
+def test_scaffold_syncs_board(tmp_path):
+    plan = build_bridge_plan(_tree(tmp_path))
+    existing = []
+    for i, f in enumerate(plan.features):
+        e = _mk_issue(200 + i, f.id, feature_title(f))
+        e["body"] = feature_body(f, None)
+        existing.append(e)
+        for j, s in enumerate(f.stories):
+            from docassert.bridge.plan import story_title
+            e2 = _mk_issue(300 + i * 10 + j, s.id, story_title(s))
+            e2["body"] = story_body(s, None)
+            existing.append(e2)
+    gh = FakeGh(existing)
+    bgh = BoardGh(existing_fields=["Type", "Doc", "PMO Project"])
+    actions = ops.scaffold(plan, gh, "o/r",
+                           board_cfg={"gh": bgh, "owner": "tester", "number": 7,
+                                      "init": False})
+    assert any("5 item(s) synced" in a for a in actions)
+    adds = [q for q in bgh.gql if "addProjectV2ItemById" in q]
+    assert len(adds) == 5