docassert 0.20.0__tar.gz → 0.20.2__tar.gz

{docassert-0.20.0/docassert.egg-info → docassert-0.20.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.20.0
+Version: 0.20.2
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Text Processing :: Markup :: Markdown

{docassert-0.20.0 → docassert-0.20.2}/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.20.0"
+__version__ = "0.20.2"

{docassert-0.20.0 → docassert-0.20.2}/docassert/bridge/board.py

@@ -15,9 +15,7 @@ FIELD_SPECS: dict[str, dict] = {
     "PMO Project": {"dataType": "TEXT"},
 }
 
-_FIELDS_QUERY = """
-query($owner: String!, $number: Int!) {
-  user(login: $owner) {
+_PROJECT_FRAGMENT = """
     projectV2(number: $number) {
       id
       title
@@ -28,8 +26,18 @@ query($owner: String!, $number: Int!) {
         }
       }
     }
-  }
-}
+"""
+
+_FIELDS_QUERY = f"""
+query($owner: String!, $number: Int!) {{
+  user(login: $owner) {{ {_PROJECT_FRAGMENT} }}
+}}
+"""
+
+_FIELDS_QUERY_ORG = f"""
+query($owner: String!, $number: Int!) {{
+  organization(login: $owner) {{ {_PROJECT_FRAGMENT} }}
+}}
 """
 
 
@@ -48,7 +56,23 @@ def create_project(gh: GhRunner, title: str) -> dict:
 
 
 def get_project(gh: GhRunner, owner: str, number: int) -> dict:
-    proj = gh.graphql(_FIELDS_QUERY, owner=owner, number=number)["user"]["projectV2"]
+    """Look the board up under a user owner first, then an organization —
+    GraphQL has no owner-agnostic ProjectV2 lookup, and a login of the wrong
+    type raises NOT_FOUND rather than returning null."""
+    proj = None
+    try:
+        proj = (gh.graphql(_FIELDS_QUERY, owner=owner, number=number)
+                .get("user") or {}).get("projectV2")
+    except GhError:
+        pass
+    if proj is None:
+        try:
+            proj = (gh.graphql(_FIELDS_QUERY_ORG, owner=owner, number=number)
+                    .get("organization") or {}).get("projectV2")
+        except GhError:
+            pass
+    if proj is None:
+        raise GhError(f"no ProjectV2 #{number} owned by '{owner}' (user or organization)")
     fields = {}
     for node in proj["fields"]["nodes"]:
         if not node:

{docassert-0.20.0 → docassert-0.20.2}/docassert/bridge/ops.py

@@ -37,10 +37,16 @@ def _marker_of(issue: dict) -> str | None:
 
 
 def _index(issues: list[dict]) -> dict[str, dict]:
+    """marker -> its authoritative issue. The REST API lists issues newest
+    first, and a converged duplicate is always newer than the issue it lost
+    to — so rank open before closed, then lowest number, or a closed
+    duplicate would shadow the real open issue and report it as done."""
+    def rank(issue: dict) -> tuple:
+        return (issue.get("state") != "open", issue.get("number", 0))
     out: dict[str, dict] = {}
     for i in issues:
         key = _marker_of(i)
-        if key and key not in out:          # first (oldest) wins
+        if key and (key not in out or rank(i) < rank(out[key])):
             out[key] = i
     return out
 

{docassert-0.20.0 → docassert-0.20.2}/docassert/bridge/plan.py

@@ -186,8 +186,11 @@ def plans_by_repo(plan: BridgePlan) -> dict[str, BridgePlan]:
             + " (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)
+        if proj["repo"] not in groups:
+            # Each sub-plan gets its own copy: shared state across repos would
+            # let one repo's run mutate another's, and skip lines print per repo.
+            groups[proj["repo"]] = BridgePlan(skipped=list(plan.skipped))
+        groups[proj["repo"]].projects.append(proj)
     return groups
 
 

{docassert-0.20.0 → docassert-0.20.2}/docassert/cli.py

@@ -54,7 +54,13 @@ def _build_id_index(documents_dir: Path) -> dict[str, list[str]]:
 
 def _validate_one(path: str, id_index: dict) -> list[CheckResult]:
     doc = load(path)
-    kind = doc.kind or "charter"
+    kind = doc.kind or ""
+    if not kind:
+        # Refuse to guess: validating an unkinded document against an arbitrary
+        # kind's criteria would produce misleading failures (or worse, passes).
+        return [CheckResult("kind", False, True,
+                            "document declares no `kind` in its frontmatter",
+                            kind="structural")]
     criteria = config.read_criteria(kind)
     schema = config.read_schema(kind)
 
@@ -237,8 +243,14 @@ def cmd_pages(args: argparse.Namespace) -> int:
         import json as _json
         data = _json.loads(Path(args.execution).read_text())
         for proj in data.get("projects", []):
-            execution[proj["id"]] = {**proj, "scope": data.get("scope"),
-                                     "repo": proj.get("repo") or data.get("repo")}
+            repo = proj.get("repo") or data.get("repo")
+            # Scope findings belong to the repo a project routes to; showing
+            # another repo's strays on this project's page would misattribute.
+            scope = data.get("scope") or {}
+            scoped = {k: [i for i in scope.get(k, [])
+                          if not repo or i.get("repo") in (None, repo)]
+                      for k in ("unverified", "orphaned")}
+            execution[proj["id"]] = {**proj, "scope": scoped, "repo": repo}
 
     def _activity(project_id: str) -> list[dict]:
         """Recent documents/ commits for one project (best-effort, git only)."""
@@ -369,6 +381,10 @@ 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)
+        if not args.project_owner and not repo_plans:
+            print("docassert bridge: --project-number needs --project-owner when "
+                  "no project routes to a repository", file=sys.stderr)
+            return 2
         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}

{docassert-0.20.0 → docassert-0.20.2}/docassert/config.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 
 import json
 import shutil
+from functools import lru_cache
 from importlib.resources import files
 from pathlib import Path
 
@@ -30,8 +31,22 @@ def _resolve(local: Path, packaged_rel: str) -> Path | None:
     return packaged if packaged.is_file() else None
 
 
+# Criteria and schemas are read once per check per document, which multiplies
+# fast on a portfolio (projects × documents × checks). Cache on (path, mtime)
+# so an edit mid-process still invalidates. Cached objects are shared: callers
+# treat them as read-only.
+@lru_cache(maxsize=256)
+def _read_yaml_cached(path_str: str, mtime_ns: int) -> dict:
+    return yaml.safe_load(Path(path_str).read_text(encoding="utf-8")) or {}
+
+
+@lru_cache(maxsize=256)
+def _read_json_cached(path_str: str, mtime_ns: int) -> dict:
+    return json.loads(Path(path_str).read_text(encoding="utf-8"))
+
+
 def _read_yaml(path: Path) -> dict:
-    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    return _read_yaml_cached(str(path), path.stat().st_mtime_ns)
 
 
 # ── criteria ────────────────────────────────────────────────────────────────
@@ -57,7 +72,7 @@ def read_schema(kind: str) -> dict:
     path = _resolve(Path("schema") / f"{kind}.schema.json", f"schema/{kind}.schema.json")
     if path is None:
         raise FileNotFoundError(f"no schema for kind '{kind}'")
-    return json.loads(path.read_text(encoding="utf-8"))
+    return _read_json_cached(str(path), path.stat().st_mtime_ns)
 
 
 # ── consistency config ──────────────────────────────────────────────────────

{docassert-0.20.0 → docassert-0.20.2}/docassert/consistency.py

@@ -3,10 +3,13 @@
 Structural checks are deterministic and blocking:
   - item-id-uniqueness   : IDs unique across the repo (always blocks)
   - referential-integrity: every link target exists (always blocks)
+  - sequence-acyclic     : the `after` digraph has no cycle (always blocks)
   - required-links       : downstream items declare their upstream link
                            (blocks only when the item's doc is approved)
   - coverage             : every parent item has >=1 downstream child
                            (blocks only when the parent's doc is approved)
+  - profile-completeness : enforced projects carry their profile's required
+                           documents (blocks when enforced or profile unknown)
 
 Semantic alignment is AI-graded and advisory (never blocks).
 """
@@ -50,31 +53,40 @@ def check_unique_item_ids(graph) -> CheckResult:
 
 
 def check_sequence_acyclic(graph) -> CheckResult:
-    """The `after` digraph contains no cycle (a cycle is broken sequencing)."""
+    """The `after` digraph contains no cycle (a cycle is broken sequencing).
+
+    Iterative three-color DFS: a dependency chain as long as the item count
+    must not hit the interpreter recursion limit.
+    """
     edges: dict[str, list[str]] = {}
     for item in graph.all_items():
         for target in item.links.get("after", []):
             edges.setdefault(item.id, []).append(target)
-    state: dict[str, int] = {}  # 0 visiting, 1 done
-
-    def visit(node, path):
-        if state.get(node) == 1:
-            return None
-        if state.get(node) == 0:
-            return path[path.index(node):] + [node]
-        state[node] = 0
-        for nxt in edges.get(node, []):
-            cycle = visit(nxt, path + [node])
-            if cycle:
-                return cycle
-        state[node] = 1
-        return None
-
+    WHITE, GRAY, BLACK = 0, 1, 2
+    color: dict[str, int] = {}
     for start in list(edges):
-        cycle = visit(start, [])
-        if cycle:
-            return CheckResult("sequence-acyclic", False, True,
-                               "after-cycle: " + " → ".join(cycle))
+        if color.get(start, WHITE) != WHITE:
+            continue
+        color[start] = GRAY
+        path = [start]
+        stack = [iter(edges.get(start, ()))]
+        while stack:
+            advanced = False
+            for nxt in stack[-1]:
+                c = color.get(nxt, WHITE)
+                if c == GRAY:
+                    cycle = path[path.index(nxt):] + [nxt]
+                    return CheckResult("sequence-acyclic", False, True,
+                                       "after-cycle: " + " → ".join(cycle))
+                if c == WHITE:
+                    color[nxt] = GRAY
+                    path.append(nxt)
+                    stack.append(iter(edges.get(nxt, ())))
+                    advanced = True
+                    break
+            if not advanced:
+                color[path.pop()] = BLACK
+                stack.pop()
     n = sum(len(v) for v in edges.values())
     return CheckResult("sequence-acyclic", True, True,
                        f"{n} after link(s), no cycles.")

{docassert-0.20.0 → docassert-0.20.2}/docassert/profiles.py

@@ -2,8 +2,10 @@
 
 A profile (profiles/<name>.yaml) lists the document kinds a project is expected
 to carry, at two levels:
-  - required    : must be present and complete; a missing one blocks CI once the
-                  project reaches the profile's `enforce_when` lifecycle stage.
+  - required    : must be present and complete; a missing one blocks CI while
+                  the project's status equals the profile's `enforce_when`
+                  stage (deliberately exact: an on-hold or closed project is
+                  not punished for its document set).
   - recommended : surfaced as a gap on the project page, but never blocking.
 
 A project opts in with `profile: <name>` in its project.md. No profile means no

{docassert-0.20.0 → docassert-0.20.2}/docassert/status/__init__.py

@@ -8,6 +8,7 @@ from .derive import (
     build_status,
     completeness_report,
     derive_rag,
+    load_corpus,
 )
 from .render import (
     render_badge_json,
@@ -20,7 +21,7 @@ from .render import (
 
 __all__ = [
     "DOCUMENTS_DIR", "APPROVED",
-    "build_status", "build_index", "completeness_report", "derive_rag",
+    "build_status", "build_index", "completeness_report", "derive_rag", "load_corpus",
     "render_markdown", "render_json", "render_html",
     "render_index_markdown", "render_index_html", "render_badge_json",
 ]

{docassert-0.20.0 → docassert-0.20.2}/docassert/status/derive.py

@@ -234,16 +234,25 @@ def _latest_report(docs):
 
 
 # ── the model + derived RAG ─────────────────────────────────────────────────
-def build_status(documents_dir=DOCUMENTS_DIR, project: str | None = None) -> dict:
+def load_corpus(documents_dir=DOCUMENTS_DIR) -> tuple[list, object, dict]:
+    """(all documents, item graph, consistency config) for one tree — loaded
+    once and shared across the per-project derivations of an index or pages
+    build via build_status(..., _corpus=...)."""
+    all_docs = [load(p) for p in sorted(Path(documents_dir).rglob("*.md"))]
+    graph = build_graph(documents_dir)
+    cfg = config_mod.read_consistency_config()
+    return all_docs, graph, cfg
+
+
+def build_status(documents_dir=DOCUMENTS_DIR, project: str | None = None,
+                 *, _corpus=None) -> dict:
     """Derive the status model for the whole repo, or for one project.
 
     `project` is a canonical project id (PRJ-NNN-CODE). When given, documents,
     coverage, risks, broken references and the latest report are all scoped to
     that project; the graph stays global so cross-project targets still resolve.
     """
-    all_docs = [load(p) for p in sorted(Path(documents_dir).rglob("*.md"))]
-    graph = build_graph(documents_dir)
-    cfg = config_mod.read_consistency_config()
+    all_docs, graph, cfg = _corpus if _corpus else load_corpus(documents_dir)
 
     code = project.split("-")[-1] if project else None
     if project:
@@ -314,9 +323,11 @@ def completeness_report(documents_dir=DOCUMENTS_DIR) -> list[dict]:
     """Per-project completeness for every profiled project (used by the
     blocking profile-completeness consistency check)."""
     from .. import projects as projects_mod
+    corpus = load_corpus(documents_dir)
     out = []
     for p in projects_mod.load_projects(documents_dir):
-        comp = build_status(documents_dir, project=p["id"]).get("completeness")
+        comp = build_status(documents_dir, project=p["id"],
+                            _corpus=corpus).get("completeness")
         if comp:
             out.append({"id": p["id"], "name": p["name"], "lifecycle": p["status"], **comp})
     return out
@@ -339,9 +350,10 @@ def build_index(documents_dir=DOCUMENTS_DIR) -> dict:
     """The multi-project view: each project's derived RAG + headline signals,
     plus the whole-repo rollup."""
     from .. import projects as projects_mod
+    corpus = load_corpus(documents_dir)
     cards = []
     for p in projects_mod.load_projects(documents_dir):
-        m = build_status(documents_dir, project=p["id"])
+        m = build_status(documents_dir, project=p["id"], _corpus=corpus)
         cards.append({
             "id": p["id"], "code": p["code"], "name": p["name"],
             "sponsor": p["sponsor"], "lifecycle": p["status"],
@@ -357,7 +369,8 @@ def build_index(documents_dir=DOCUMENTS_DIR) -> dict:
             "broken": len(m["broken_references"]),
             "completeness": m.get("completeness"),
         })
-    return {"projects": cards, "overall": build_status(documents_dir)}
+    return {"projects": cards,
+            "overall": build_status(documents_dir, _corpus=corpus)}
 
 
 def derive_rag(model) -> str: