docassert 0.1.0__py3-none-any.whl

docassert/consistency.py

@@ -0,0 +1,167 @@
+"""Cross-document consistency checks over the traceable-item graph.
+
+Structural checks are deterministic and blocking:
+  - item-id-uniqueness   : IDs unique across the repo (always blocks)
+  - referential-integrity: every link target exists (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)
+
+Semantic alignment is AI-graded and advisory (never blocks).
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+
+from . import config as config_mod
+from .graph import build_graph
+from .models import CheckResult
+from .semantic import run_alignment
+
+CONFIG_PATH = Path("consistency.yaml")
+APPROVED_STATES = {"approved", "baselined"}
+
+
+def load_config(path: str | Path = CONFIG_PATH) -> dict:
+    if not Path(path).is_file():
+        return {}
+    with open(path, encoding="utf-8") as fh:
+        return yaml.safe_load(fh) or {}
+
+
+def _approved(item) -> bool:
+    return str(item.doc_status).lower() in APPROVED_STATES
+
+
+# ── structural (deterministic) ─────────────────────────────────────────────
+def check_unique_item_ids(graph) -> CheckResult:
+    dups = graph.duplicates()
+    if not dups:
+        return CheckResult("item-id-uniqueness", True, True,
+                           f"All {len(graph.occurrences)} item IDs are unique.")
+    detail = "; ".join(f"{iid} in {', '.join(paths)}" for iid, paths in dups.items())
+    return CheckResult("item-id-uniqueness", False, True,
+                       f"Duplicate item IDs: {detail}")
+
+
+def check_referential_integrity(graph) -> CheckResult:
+    broken = []
+    for item in graph.all_items():
+        for relation, targets in item.links.items():
+            for target in targets:
+                if not graph.exists(target):
+                    broken.append(f"{item.id} —{relation}→ {target} (missing)")
+    if broken:
+        return CheckResult("referential-integrity", False, True,
+                           f"{len(broken)} broken reference(s): " + "; ".join(broken))
+    return CheckResult("referential-integrity", True, True, "All references resolve.")
+
+
+def check_required_links(graph, config) -> CheckResult:
+    required = config.get("required_links", {})
+    approved_orphans, draft_orphans = [], []
+    for item in graph.all_items():
+        relation = required.get(item.type)
+        if relation and not item.targets(relation):
+            bucket = approved_orphans if _approved(item) else draft_orphans
+            bucket.append(f"{item.id} (missing '{relation}')")
+    parts = []
+    if approved_orphans:
+        parts.append("approved items missing a required link: " + "; ".join(approved_orphans))
+    if draft_orphans:
+        parts.append(f"{len(draft_orphans)} draft item(s) not yet linked (ok until approved)")
+    return CheckResult("required-links", not approved_orphans, True,
+                       " · ".join(parts) if parts else "All required upstream links present.")
+
+
+def check_coverage(graph, config) -> CheckResult:
+    approved_gaps, draft_gaps = [], []
+    for rule in config.get("coverage", []):
+        parent_prefix, relation = rule["parent"], rule["relation"]
+        by_prefix = rule.get("by_prefix")
+        label = rule.get("label", f"{parent_prefix} → {by_prefix}")
+        for parent in graph.by_type.get(parent_prefix, []):
+            if graph.children(parent.id, relation, by_prefix):
+                continue
+            bucket = approved_gaps if _approved(parent) else draft_gaps
+            bucket.append(f"{parent.id} ({label})")
+    parts = []
+    if approved_gaps:
+        parts.append("approved items with no downstream coverage: " + "; ".join(approved_gaps))
+    if draft_gaps:
+        parts.append(f"{len(draft_gaps)} draft item(s) not yet covered (ok until approved)")
+    return CheckResult("coverage", not approved_gaps, True,
+                       " · ".join(parts) if parts else "All approved items are covered.")
+
+
+def check_profile_completeness(documents_dir: str | Path = "documents") -> CheckResult:
+    """Every profiled project must carry the documents its profile requires.
+
+    Blocks when an *enforced* (e.g. active) project is missing a required kind,
+    or names a profile that doesn't exist. Projects not yet enforced (e.g.
+    proposed) surface their gaps as advisory only.
+    """
+    from . import status as status_mod
+    report = status_mod.completeness_report(documents_dir)
+    blockers, unknowns, advisories = [], [], []
+    for r in report:
+        if r.get("unknown"):
+            unknowns.append(f"{r['id']} → unknown profile '{r['profile']}'")
+        elif r["blocks"]:
+            blockers.append(f"{r['id']} ({r['profile']}) missing required: "
+                            + ", ".join(r["missing_required"]))
+        elif r["missing_required"] or r["incomplete_required"]:
+            n = len(r["missing_required"]) + len(r["incomplete_required"])
+            advisories.append(f"{r['id']} ({n} not yet complete)")
+    parts = []
+    if blockers:
+        parts.append("active projects missing required documents: " + "; ".join(blockers))
+    if unknowns:
+        parts.append("unknown profiles: " + "; ".join(unknowns))
+    if advisories:
+        parts.append(f"{len(advisories)} project(s) with advisory gaps (not enforced yet)")
+    return CheckResult("profile-completeness", not blockers and not unknowns, True,
+                       " · ".join(parts) if parts else
+                       "All profiled projects carry their required documents.")
+
+
+# ── semantic (advisory) ────────────────────────────────────────────────────
+def run_alignment_checks(graph, config) -> list[CheckResult]:
+    edges = []  # (prompt, parent, child, relation)
+    for rule in config.get("alignment", []):
+        relation, prompt = rule["relation"], rule.get("prompt", "").strip()
+        for child in graph.all_items():
+            for target in child.targets(relation):
+                parent = graph.canonical(target)
+                if parent is not None:
+                    edges.append((prompt, parent, child, relation))
+
+    if not edges:
+        return []
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        return [CheckResult("alignment", True, False,
+                            f"skipped — no ANTHROPIC_API_KEY ({len(edges)} link(s) to grade)",
+                            kind="semantic", score=None)]
+    return [run_alignment(f"align:{c.id}-{rel}-{p.id}", prompt, p.text, c.text)
+            for prompt, p, c, rel in edges]
+
+
+def run_consistency(documents_dir: str | Path = "documents",
+                    config_path: str | Path | None = None,
+                    with_semantic: bool = True) -> list[CheckResult]:
+    graph = build_graph(documents_dir)
+    cfg = load_config(config_path) if config_path is not None else config_mod.read_consistency_config()
+    results = [
+        check_unique_item_ids(graph),
+        check_referential_integrity(graph),
+        check_required_links(graph, cfg),
+        check_coverage(graph, cfg),
+        check_profile_completeness(documents_dir),
+    ]
+    if with_semantic:
+        results.extend(run_alignment_checks(graph, cfg))
+    return results

docassert/graph.py

@@ -0,0 +1,68 @@
+"""Build the cross-document item graph used by the consistency engine."""
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+
+from . import config
+from .loader import load, parse_items
+from .models import Item
+
+DOCUMENTS_DIR = Path("documents")
+
+
+class Graph:
+    """All traceable items across the repo, plus a reverse (incoming) index."""
+
+    def __init__(self) -> None:
+        self.occurrences: dict[str, list[Item]] = defaultdict(list)   # id -> items
+        self.by_type: dict[str, list[Item]] = defaultdict(list)       # BR/PR/… -> items
+        self.by_project: dict[str, list[Item]] = defaultdict(list)    # AUR/ATL/… -> items
+        self.incoming: dict[str, list[tuple[str, Item]]] = defaultdict(list)  # target -> (relation, source)
+
+    def add(self, item: Item) -> None:
+        self.occurrences[item.id].append(item)
+        self.by_type[item.type].append(item)
+        self.by_project[item.project].append(item)
+        for relation, targets in item.links.items():
+            for target in targets:
+                self.incoming[target].append((relation, item))
+
+    def exists(self, item_id: str) -> bool:
+        return item_id in self.occurrences
+
+    def canonical(self, item_id: str) -> Item | None:
+        occ = self.occurrences.get(item_id)
+        return occ[0] if occ else None
+
+    def duplicates(self) -> dict[str, list[str]]:
+        """id -> paths, for every id defined more than once."""
+        return {iid: [it.doc_path for it in occ]
+                for iid, occ in self.occurrences.items() if len(occ) > 1}
+
+    def all_items(self) -> list[Item]:
+        return [occ[0] for occ in self.occurrences.values()]
+
+    def children(self, target_id: str, relation: str,
+                 by_type: str | None = None) -> list[Item]:
+        """Items that link to `target_id` via `relation` (optionally by item type)."""
+        return [src for rel, src in self.incoming.get(target_id, [])
+                if rel == relation and (by_type is None or src.type == by_type)]
+
+
+def _item_sections_for(kind: str) -> list[dict]:
+    if not config.criteria_exists(kind):
+        return []
+    return config.read_criteria(kind).get("item_sections", []) or []
+
+
+def build_graph(documents_dir: str | Path = DOCUMENTS_DIR) -> Graph:
+    graph = Graph()
+    for path in sorted(Path(documents_dir).rglob("*.md")):
+        try:
+            doc = load(path)
+        except ValueError:
+            continue  # malformed frontmatter is caught by per-document validation
+        for item in parse_items(doc, _item_sections_for(doc.kind or "")):
+            graph.add(item)
+    return graph

docassert/loader.py

@@ -0,0 +1,116 @@
+"""Load and parse a business document into frontmatter + sections."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import frontmatter
+import yaml
+
+from .models import Document, Item, Section
+
+# A traceable item bullet, e.g.
+#   **AUR-PR-014** (traces: AUR-BR-001): The flow shall be self-serve.
+# The id is <CODE>-<TYPE>-<NNN>: project code, item type, number.
+ITEM_RE = re.compile(
+    r"^\*\*(?P<id>(?P<project>[A-Z]{2,6})-(?P<type>[A-Z]{2,6})-\d+)\*\*"   # **CODE-TYPE-123**
+    r"(?:\s*\((?P<links>[^)]*)\))?"                                          # optional (relation: id, …)
+    r"\s*:\s*(?P<text>.+)$"                                                  # : text
+)
+
+
+def parse_link_clause(clause: str) -> dict[str, list[str]]:
+    """Parse `traces: BR-001, BR-002; verifies: FR-3` -> {relation: [ids]}."""
+    links: dict[str, list[str]] = {}
+    for group in (clause or "").split(";"):
+        if ":" not in group:
+            continue
+        rel, ids = group.split(":", 1)
+        rel = rel.strip().lower()
+        id_list = [i.strip() for i in ids.split(",") if i.strip()]
+        if rel and id_list:
+            links.setdefault(rel, []).extend(id_list)
+    return links
+
+
+def parse_sections(body: str) -> dict[str, Section]:
+    """Split a markdown body into H2 (`## `) sections, preserving order."""
+    sections: dict[str, Section] = {}
+    current_title: str | None = None
+    current_lines: list[str] = []
+
+    def flush() -> None:
+        if current_title is not None:
+            sections[current_title] = Section(
+                title=current_title, body="\n".join(current_lines).strip()
+            )
+
+    for line in body.splitlines():
+        if line.startswith("## "):
+            flush()
+            current_title = line[3:].strip()
+            current_lines = []
+        else:
+            if current_title is not None:
+                current_lines.append(line)
+    flush()
+    return sections
+
+
+def load(path: str | Path) -> Document:
+    """Parse a document file. Raises ValueError on malformed frontmatter."""
+    path = Path(path)
+    text = path.read_text(encoding="utf-8")
+    try:
+        post = frontmatter.loads(text)
+    except yaml.YAMLError as exc:  # malformed YAML frontmatter
+        raise ValueError(f"{path}: invalid YAML frontmatter: {exc}") from exc
+
+    return Document(
+        path=str(path),
+        frontmatter=dict(post.metadata),
+        sections=parse_sections(post.content),
+        raw_body=post.content,
+    )
+
+
+def load_criteria(path: str | Path) -> dict:
+    """Load a criteria YAML file (e.g. criteria/charter.criteria.yaml)."""
+    with open(path, encoding="utf-8") as fh:
+        return yaml.safe_load(fh)
+
+
+def iter_item_lines(section: Section):
+    """Yield (raw_bullet, match_or_None) for each bullet in an item section."""
+    for raw in section.list_items:
+        yield raw, ITEM_RE.match(raw)
+
+
+def parse_items(doc: Document, item_sections: list[dict]) -> list[Item]:
+    """Extract traceable items from a document per its criteria item_sections.
+
+    Each entry in `item_sections` is {"section": <title>, "prefix": <PREFIX>}.
+    Bullets that don't parse are skipped here; the `items-well-formed`
+    structural check is what flags them.
+    """
+    status = str(doc.frontmatter.get("status", "draft"))
+    items: list[Item] = []
+    for spec in item_sections or []:
+        section = doc.section(spec["section"])
+        if section is None:
+            continue
+        for _raw, m in iter_item_lines(section):
+            if not m:
+                continue
+            items.append(Item(
+                id=m.group("id"),
+                project=m.group("project"),
+                type=m.group("type"),
+                text=m.group("text").strip(),
+                links=parse_link_clause(m.group("links") or ""),
+                doc_path=doc.path,
+                doc_kind=doc.kind or "",
+                doc_status=status,
+                section=spec["section"],
+            ))
+    return items

docassert/models.py

@@ -0,0 +1,99 @@
+"""Shared data types for docassert."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Section:
+    """A single H2 section of a document body."""
+    title: str
+    body: str
+
+    @property
+    def list_items(self) -> list[str]:
+        """Top-level markdown bullet items in this section, comments stripped."""
+        items: list[str] = []
+        for line in self.body.splitlines():
+            stripped = line.strip()
+            if stripped.startswith(("- ", "* ")):
+                text = stripped[2:].strip()
+                # drop HTML-comment-only placeholder bullets from the template
+                if text.startswith("<!--") or not text:
+                    continue
+                items.append(text)
+        return items
+
+    @property
+    def is_empty(self) -> bool:
+        """A section counts as empty if it has no prose or list items once
+        template HTML comments and whitespace are removed."""
+        meaningful = []
+        for line in self.body.splitlines():
+            s = line.strip()
+            if not s or s.startswith("<!--") and s.endswith("-->"):
+                continue
+            # strip inline comment fragments
+            if s.startswith("<!--") or s.endswith("-->"):
+                continue
+            meaningful.append(s)
+        return len("".join(meaningful).strip()) == 0
+
+
+@dataclass
+class Document:
+    """A parsed business document: frontmatter + ordered body sections."""
+    path: str
+    frontmatter: dict
+    sections: dict[str, Section] = field(default_factory=dict)
+    raw_body: str = ""
+
+    @property
+    def id(self) -> str | None:
+        return self.frontmatter.get("id")
+
+    @property
+    def kind(self) -> str | None:
+        return self.frontmatter.get("kind")
+
+    def section(self, title: str) -> Section | None:
+        return self.sections.get(title)
+
+
+@dataclass
+class CheckResult:
+    """The outcome of one audit check against one document."""
+    check_id: str
+    passed: bool
+    blocking: bool
+    detail: str
+    kind: str = "structural"           # structural | semantic
+    score: float | None = None      # semantic checks only, 0..1
+
+    @property
+    def is_blocking_failure(self) -> bool:
+        return self.blocking and not self.passed
+
+
+@dataclass
+class Item:
+    """A traceable item inside a document (a requirement, criterion, test, …).
+
+    Authored as a bullet like:
+        - **AUR-PR-014** (traces: AUR-BR-001): The onboarding flow shall be self-serve.
+
+    The id is <CODE>-<TYPE>-<NNN>: `project` is the project code (AUR), `type` is
+    the item type (PR). Ids are globally unique and self-identify their project.
+    """
+    id: str                              # e.g. "AUR-PR-014"
+    project: str                         # project code, e.g. "AUR"
+    type: str                            # item type, e.g. "PR"
+    text: str
+    links: dict[str, list[str]]          # relation -> [target ids], e.g. {"traces": ["AUR-BR-001"]}
+    doc_path: str
+    doc_kind: str
+    doc_status: str
+    section: str
+
+    def targets(self, relation: str) -> list[str]:
+        return self.links.get(relation, [])

docassert/profiles.py

@@ -0,0 +1,111 @@
+"""Profiles — the expected document set for a project.
+
+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.
+  - 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
+completeness expectations (fully backward-compatible).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from . import config as config_mod
+
+APPROVED = {"approved", "baselined"}
+
+
+def available(profiles_dir: str | Path | None = None) -> list[str]:
+    """Profile names. Default resolves local ./profiles + packaged defaults; pass
+    an explicit dir to look only there."""
+    if profiles_dir is not None:
+        d = Path(profiles_dir)
+        return sorted(p.stem for p in d.glob("*.yaml")) if d.is_dir() else []
+    return config_mod.available_profiles()
+
+
+def load_profile(name: str, profiles_dir: str | Path | None = None) -> dict | None:
+    """Load one profile, or None if there is no such file. Default resolves
+    ./profiles then the packaged defaults; pass an explicit dir to override."""
+    if profiles_dir is not None:
+        candidate = Path(profiles_dir) / f"{name}.yaml"
+        path = candidate if candidate.is_file() else None
+    else:
+        path = config_mod.profile_path(name)
+    if path is None:
+        return None
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    expects = data.get("expects", {}) or {}
+    return {
+        "name": data.get("name", name),
+        "enforce_when": data.get("enforce_when", "active"),
+        "required": list(expects.get("required", []) or []),
+        "recommended": list(expects.get("recommended", []) or []),
+    }
+
+
+def _kind_state(kind: str, by_kind: dict[str, list[dict]]) -> str:
+    """complete / incomplete / missing for one expected kind.
+
+    complete   = at least one document of the kind is approved/baselined AND
+                 passing its audit.
+    incomplete = present, but none is complete yet (draft/proposed or failing).
+    missing    = no document of the kind at all.
+    """
+    docs = by_kind.get(kind, [])
+    if not docs:
+        return "missing"
+    if any(str(d.get("status", "")).lower() in APPROVED and d.get("passing", True)
+           for d in docs):
+        return "complete"
+    return "incomplete"
+
+
+def completeness(profile: dict, documents: list[dict], project_status: str) -> dict:
+    """Assess a project's documents against its profile.
+
+    `documents` is a list of {kind, status, passing} dicts (the project's docs).
+    """
+    by_kind: dict[str, list[dict]] = {}
+    for d in documents:
+        by_kind.setdefault(d.get("kind"), []).append(d)
+
+    required = [{"kind": k, "state": _kind_state(k, by_kind)} for k in profile["required"]]
+    recommended = [{"kind": k, "state": _kind_state(k, by_kind)} for k in profile["recommended"]]
+
+    missing_required = [r["kind"] for r in required if r["state"] == "missing"]
+    incomplete_required = [r["kind"] for r in required if r["state"] == "incomplete"]
+    recommended_gaps = [r["kind"] for r in recommended if r["state"] != "complete"]
+
+    enforced = str(project_status).lower() == str(profile["enforce_when"]).lower()
+    return {
+        "profile": profile["name"],
+        "enforce_when": profile["enforce_when"],
+        "enforced": enforced,
+        "unknown": False,
+        "required": required,
+        "recommended": recommended,
+        "required_total": len(required),
+        "required_complete": sum(1 for r in required if r["state"] == "complete"),
+        "missing_required": missing_required,
+        "incomplete_required": incomplete_required,
+        "recommended_gaps": recommended_gaps,
+        # A missing required document blocks only once the project is enforced.
+        "blocks": enforced and bool(missing_required),
+    }
+
+
+def unknown(profile_name: str) -> dict:
+    """Placeholder completeness for a project that names a non-existent profile."""
+    return {
+        "profile": profile_name, "enforce_when": None, "enforced": False,
+        "unknown": True, "required": [], "recommended": [],
+        "required_total": 0, "required_complete": 0,
+        "missing_required": [], "incomplete_required": [], "recommended_gaps": [],
+        "blocks": False,
+    }

docassert/projects.py

@@ -0,0 +1,49 @@
+"""The project registry — derived from the `project.md` anchors.
+
+Each project folder holds a `project.md` (kind: project) declaring the canonical
+id (PRJ-NNN-CODE), the code, name, sponsor, and status. `projects.yaml` at the
+repo root is the generated index of them all.
+"""
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+
+import yaml
+
+from .loader import load
+
+DOCUMENTS_DIR = Path("documents")
+_FIELDS = ("id", "code", "name", "sponsor", "status")
+
+
+def load_projects(documents_dir: str | Path = DOCUMENTS_DIR) -> list[dict]:
+    """Every project anchor (kind: project), sorted by id."""
+    projects = []
+    for path in sorted(Path(documents_dir).rglob("*.md")):
+        try:
+            doc = load(path)
+        except ValueError:
+            continue
+        if doc.kind == "project":
+            entry = {k: str(doc.frontmatter.get(k, "")) for k in _FIELDS}
+            entry["path"] = doc.path
+            projects.append(entry)
+    projects.sort(key=lambda p: p["id"])
+    return projects
+
+
+def registry_issues(projects: list[dict]) -> list[str]:
+    """Cross-project validation: ids and codes must be unique."""
+    issues = []
+    for field in ("id", "code"):
+        dups = [v for v, n in Counter(p[field] for p in projects).items() if v and n > 1]
+        issues += [f"duplicate project {field}: {d}" for d in dups]
+    return issues
+
+
+def render_yaml(projects: list[dict]) -> str:
+    data = [{k: p[k] for k in _FIELDS} for p in projects]
+    header = ("# Generated by `docassert projects` — do not edit.\n"
+              "# The project.md anchors under documents/ are the source of truth.\n")
+    return header + yaml.safe_dump({"projects": data}, sort_keys=False, allow_unicode=True)