docassert 0.14.0__tar.gz → 0.15.0__tar.gz

{docassert-0.14.0/docassert.egg-info → docassert-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.14.0
+Version: 0.15.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.14.0 → docassert-0.15.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.14.0"
+__version__ = "0.15.0"

{docassert-0.14.0 → docassert-0.15.0}/docassert/_data/criteria/risk-register.criteria.yaml

@@ -30,6 +30,11 @@ checks:
     type: structural
     blocking: once-proposed
     description: Every risk states a Probability, Impact, Owner, and Response.
+  - id: risk-disposition-valid
+    type: structural
+    blocking: true
+    description: Any Status field on a RISK item names a valid disposition (open/mitigated/accepted/closed).
+
   - id: unique-id
     type: structural
     blocking: true

{docassert-0.14.0 → docassert-0.15.0}/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.14.0 → docassert-0.15.0}/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.14.0 → docassert-0.15.0}/docassert/status/derive.py

@@ -82,6 +82,9 @@ def _risks(graph, code=None):
         description = (item.text[:m.start()] if m else item.text).strip()
         rm = re.search(r"Response\s*:\s*(.+)$", item.text,
                        re.IGNORECASE | re.DOTALL)
+        raw = (_field_value(item.text, "status") or "open").lower()
+        disposition = raw if raw in {"open", "mitigated", "accepted",
+                                     "closed"} else "open"
         risks.append({
             "id": item.id,
             "description": description,
@@ -90,9 +93,12 @@ def _risks(graph, code=None):
             "impact": impact or "?",
             "owner": _field_value(item.text, "owner") or "?",
             "response": rm.group(1).strip() if rm else "",
+            "disposition": disposition,
             "score": _SEVERITY.get(prob, 0) * _SEVERITY.get(impact, 0),
         })
-    return sorted(risks, key=lambda r: -r["score"])
+    # open risks first, then by severity; dispositioned risks stay as record
+    return sorted(risks, key=lambda r: (r["disposition"] != "open",
+                                        -r["score"]))
 
 
 def _broken_references(graph, code=None):
@@ -218,7 +224,7 @@ def build_index(documents_dir=DOCUMENTS_DIR) -> dict:
             "rag": m["rag"],
             "total": m["counts"]["total"],
             "failing": m["counts"]["failing"],
-            "risks": len(m["risks"]),
+            "risks": len([r for r in m["risks"] if r.get("disposition", "open") == "open"]),
             "coverage_gaps": sum(len(c["gaps"]) for c in m["coverage"]),
             "broken": len(m["broken_references"]),
             "completeness": m.get("completeness"),
@@ -238,7 +244,8 @@ def derive_rag(model) -> str:
     reported = (model["latest_report"] or {}).get("rag")
     completeness_gap = bool(comp and (comp["missing_required"] or comp["incomplete_required"]
                                       or comp["recommended_gaps"] or comp.get("unknown")))
-    if coverage_gap or model["risks"] or reported in {"amber", "red"} or completeness_gap:
+    open_risks = [r for r in model["risks"] if r.get("disposition", "open") == "open"]
+    if coverage_gap or open_risks or reported in {"amber", "red"} or completeness_gap:
         return "amber"
     return "green"
 

{docassert-0.14.0 → docassert-0.15.0}/docassert/status/render.py

@@ -55,8 +55,12 @@ def render_markdown(model, summary: bool = False) -> str:
         out.append(f"- 🔴 **Documents failing audit**: {', '.join(failing)}")
 
     if model["risks"]:
-        out.append(f"- 🟠 **Open risks**: {len(model['risks'])}")
-        for r in model["risks"][:5]:
+        open_r = [r for r in model["risks"] if r.get("disposition", "open") == "open"]
+        rest = len(model["risks"]) - len(open_r)
+        mark = "🟠" if open_r else "🟢"
+        out.append(f"- {mark} **Open risks**: {len(open_r)}"
+                   + (f" ({rest} dispositioned)" if rest else ""))
+        for r in open_r[:5]:
             out.append(f"    - `{r['id']}` — {r['probability']}/{r['impact']} · owner: {r['owner']}")
 
     lr = model["latest_report"]
@@ -149,6 +153,12 @@ def render_html(model) -> str:
                      value, "var(--muted)")
         return f'<td style="color:{color};font-weight:600;">{esc(value)}</td>'
 
+    def disp(value):
+        color = {"open": "var(--amber)", "mitigated": "var(--ok)",
+                 "accepted": "var(--muted)", "closed": "var(--muted)"}.get(
+                     value, "var(--amber)")
+        return f'<td style="color:{color};font-weight:600;">{esc(value)}</td>'
+
     if model["risks"]:
         risk_rows = "".join(
             f'<tr><td><code>{esc(r["id"])}</code></td>'
@@ -156,11 +166,12 @@ def render_html(model) -> str:
             f'<td>{", ".join(f"<code>{esc(b)}</code>" for b in r["threatens"]) or "—"}</td>'
             + sev(r["probability"]) + sev(r["impact"])
             + f'<td>{esc(r["owner"])}</td>'
-            f'<td>{esc(r["response"]) or "—"}</td></tr>'
+            + disp(r.get("disposition", "open"))
+            + f'<td>{esc(r["response"]) or "—"}</td></tr>'
             for r in model["risks"])
         risks = ('<table><thead><tr><th>ID</th><th>Risk</th><th>Threatens</th>'
                  '<th>Probability</th><th>Impact</th><th>Owner</th>'
-                 '<th>Response</th></tr></thead>'
+                 '<th>Status</th><th>Response</th></tr></thead>'
                  f'<tbody>{risk_rows}</tbody></table>')
     else:
         risks = "<p>None open.</p>"
@@ -280,7 +291,7 @@ def render_html(model) -> str:
   {document_set}
   {execution_html}
   {problems}
-  <section><h2>Open risks ({len(model['risks'])})</h2>{risks}</section>
+  <section><h2>Risks ({len([r for r in model['risks'] if r.get('disposition', 'open') == 'open'])} open of {len(model['risks'])})</h2>{risks}</section>
   <section><h2>Latest status report</h2><p>{report}</p></section>
   <section><h2>Documents ({c['total']})</h2>
     <table><thead><tr><th>Kind</th><th>ID</th><th>Status</th><th>Audit</th></tr></thead>

{docassert-0.14.0 → docassert-0.15.0}/docassert/structural.py

@@ -226,6 +226,7 @@ def check_project_id_format(doc: Document, ctx: dict) -> tuple[bool, str]:
 
 
 _RISK_FIELDS = ["Probability", "Impact", "Owner", "Response"]
+_DISPOSITIONS = {"open", "mitigated", "accepted", "closed"}
 _ADR_STATES = {"proposed", "accepted", "superseded", "deprecated", "rejected"}
 
 
@@ -255,6 +256,20 @@ def check_risk_items_complete(doc: Document, ctx: dict) -> tuple[bool, str]:
     return True, f"All {total} risk(s) state probability, impact, owner, and response."
 
 
+def check_risk_disposition_valid(doc: Document, ctx: dict) -> tuple[bool, str]:
+    """Where a RISK item yields Status, it names a valid disposition."""
+    bad, total = [], 0
+    for iid, text in _items_of_prefix(doc, ctx, "RISK"):
+        total += 1
+        value = _field_value(text, "Status")
+        if value is not None and value.lower() not in _DISPOSITIONS:
+            bad.append(f"{iid}: {value!r}")
+    if bad:
+        return False, ("invalid disposition (open|mitigated|accepted|closed): "
+                       + "; ".join(bad))
+    return True, f"All {total} risk disposition(s) valid (absent means open)."
+
+
 def check_adr_items_have_status(doc: Document, ctx: dict) -> tuple[bool, str]:
     """Every ADR item declares a valid Status."""
     bad, total = [], 0
@@ -402,6 +417,7 @@ CHECKS: dict[str, Callable[[Document, dict], tuple[bool, str]]] = {
     "unique-id": check_unique_id,
     "items-well-formed": check_items_well_formed,
     "risk-items-complete": check_risk_items_complete,
+    "risk-disposition-valid": check_risk_disposition_valid,
     "adr-items-have-status": check_adr_items_have_status,
     "raci-one-accountable": check_raci_one_accountable,
     "story-format": check_story_format,

{docassert-0.14.0 → docassert-0.15.0/docassert.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.14.0
+Version: 0.15.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.14.0 → docassert-0.15.0}/tests/test_bridge.py

@@ -441,3 +441,32 @@ def test_anchor_without_repo_keeps_single_repo_mode_working(tmp_path):
     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"]

{docassert-0.14.0 → docassert-0.15.0}/tests/test_status.py

@@ -162,3 +162,55 @@ def test_render_html_risk_table():
     # severity cells are colored
     assert 'style="color:var(--bad);font-weight:600;">high</td>' in out \
         or 'style="color:var(--amber);font-weight:600;">medium</td>' in out
+
+
+# ── risk disposition (ENG-PR-002) ────────────────────────────────────────────
+def _risk_graph(*status_clauses):
+    from docassert.graph import Graph
+    from docassert.models import Item
+    g = Graph()
+    for i, clause in enumerate(status_clauses, 1):
+        text = (f"Risk {i} description. Probability: low. Impact: high. "
+                f"Owner: o.{i}.{clause} Response: watch.")
+        g.add(Item(f"XX-RISK-{i:03d}", "XX", "RISK", text, {}, "d.md",
+                   "risk-register", "approved", "S"))
+    return g
+
+
+def test_disposition_parsed_and_defaulted():
+    from docassert.status.derive import _risks
+    g = _risk_graph(" Status: Mitigated.", " Status: accepted.", "")
+    rs = _risks(g)
+    assert [r["disposition"] for r in rs] == ["open", "mitigated", "accepted"]
+    assert rs[0]["id"] == "XX-RISK-003"          # open risks sort first
+
+
+def test_rag_green_when_all_risks_dispositioned():
+    base = {"documents": [], "coverage": [], "broken_references": [],
+            "latest_report": None, "completeness": None}
+    open_r = dict(base, risks=[{"id": "R", "score": 2, "disposition": "open"}])
+    done_r = dict(base, risks=[{"id": "R", "score": 2, "disposition": "accepted"}])
+    assert S.derive_rag(open_r) == "amber"
+    assert S.derive_rag(done_r) == "green"
+
+
+def test_disposition_check_blocks_invalid(tmp_path):
+    from docassert.loader import load
+    from docassert.structural import check_risk_disposition_valid
+    p = tmp_path / "r.md"
+    p.write_text(
+        "---\nkind: risk-register\nid: XX-risk-register\n"
+        "project: PRJ-001-XX\ntitle: T\nowner: o\nstatus: approved\n---\n\n"
+        "## Overview\nx\n\n## Risks\n\n"
+        "- **XX-RISK-001**: Bad. Probability: low. Impact: low. Owner: o. "
+        "Status: wontfix. Response: r.\n", encoding="utf-8")
+    doc = load(p)
+    ok, detail = check_risk_disposition_valid(
+        doc, {"item_sections": [{"section": "Risks", "prefix": "RISK"}]})
+    assert not ok and "wontfix" in detail
+
+
+def test_render_html_shows_disposition_column():
+    _cd_root()
+    out = S.render_html(S.build_status(ROOT / "documents"))
+    assert "<th>Status</th>" in out and "open of" in out