docassert 0.2.0__tar.gz → 0.2.1__tar.gz

{docassert-0.2.0/docassert.egg-info → docassert-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.2.0
+Version: 0.2.1
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0
@@ -80,7 +80,7 @@ you can customize them.
 
 | Command | What it does |
 |---|---|
-| `docassert validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures. |
+| `docassert validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures (capped at 125). |
 | `docassert consistency` | Cross-document checks: referential integrity, coverage, required links, profile completeness. |
 | `docassert rtm [--project ID]` | Requirements traceability matrix (Markdown or CSV). |
 | `docassert status [--project ID] [--index]` | Derived project status (md / json / html). |
@@ -89,6 +89,10 @@ you can customize them.
 | `docassert init [DIR]` | Scaffold the default config into a repo. |
 | `docassert extract <file>` | Extract plain text from a source `.docx` / `.pdf` / `.md` / `.txt` (the first step of doc-to-pmo conversion). Needs the `convert` extra: `pip install "docassert[convert]"`. |
 
+Every document-reading command accepts `--documents-dir` (default `documents/`).
+AI alignment grades at most `alignment_limit` links per run (default 25; set it
+in `consistency.yaml`, `0` = no cap) so API cost stays bounded on large graphs.
+
 ## Document kinds
 
 Twenty kinds, each a `templates/<kind>.template.md` + `schema/<kind>.schema.json`

{docassert-0.2.0 → docassert-0.2.1}/README.md

@@ -42,7 +42,7 @@ you can customize them.
 
 | Command | What it does |
 |---|---|
-| `docassert validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures. |
+| `docassert validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures (capped at 125). |
 | `docassert consistency` | Cross-document checks: referential integrity, coverage, required links, profile completeness. |
 | `docassert rtm [--project ID]` | Requirements traceability matrix (Markdown or CSV). |
 | `docassert status [--project ID] [--index]` | Derived project status (md / json / html). |
@@ -51,6 +51,10 @@ you can customize them.
 | `docassert init [DIR]` | Scaffold the default config into a repo. |
 | `docassert extract <file>` | Extract plain text from a source `.docx` / `.pdf` / `.md` / `.txt` (the first step of doc-to-pmo conversion). Needs the `convert` extra: `pip install "docassert[convert]"`. |
 
+Every document-reading command accepts `--documents-dir` (default `documents/`).
+AI alignment grades at most `alignment_limit` links per run (default 25; set it
+in `consistency.yaml`, `0` = no cap) so API cost stays bounded on large graphs.
+
 ## Document kinds
 
 Twenty kinds, each a `templates/<kind>.template.md` + `schema/<kind>.schema.json`

{docassert-0.2.0 → docassert-0.2.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.2.0"
+__version__ = "0.2.1"

{docassert-0.2.0 → docassert-0.2.1}/docassert/_data/consistency.yaml

@@ -35,6 +35,10 @@ coverage:
 
 # Advisory AI alignment: for each relation, judge whether the child genuinely
 # fulfils the parent it links to. Never blocks.
+# Each graded link costs one API call; `alignment_limit` caps calls per run
+# (0 = no cap).
+alignment_limit: 25
+
 alignment:
   - relation: traces
     prompt: >

{docassert-0.2.0 → docassert-0.2.1}/docassert/cli.py

@@ -3,8 +3,10 @@
     docassert validate documents/charters/aurora.md
     docassert validate documents/**/*.md --junit out.xml --markdown comment.md
 
-Exit code = number of BLOCKING (structural) failures. Advisory (AI) failures
-never affect the exit code, so CI is gated only by deterministic checks.
+Exit code = number of BLOCKING (structural) failures, capped at 125 so large
+counts can't wrap around the 8-bit exit-status space (256 failures must never
+read as success). Advisory (AI) failures never affect the exit code, so CI is
+gated only by deterministic checks.
 """
 from __future__ import annotations
 
@@ -23,15 +25,24 @@ from .models import CheckResult
 from .semantic import run_semantic
 from .structural import run_structural
 
-# The user's documents live here; criteria / schema / consistency.yaml / profiles
-# resolve via `config` (local override → packaged default).
-DOCUMENTS_DIR = Path("documents")
+# Default documents location; every document-reading command accepts
+# --documents-dir to override it. Criteria / schema / consistency.yaml /
+# profiles resolve via `config` (local override → packaged default).
+DEFAULT_DOCUMENTS_DIR = "documents"
 
+# POSIX exit statuses are 8-bit; 126+ carry shell meanings. Cap so a failure
+# count can never wrap to 0.
+_EXIT_CAP = 125
 
-def _build_id_index() -> dict[str, list[str]]:
-    """Map document id -> [paths] across all documents/, for uniqueness checks."""
+
+def _capped(failures: int) -> int:
+    return min(failures, _EXIT_CAP)
+
+
+def _build_id_index(documents_dir: Path) -> dict[str, list[str]]:
+    """Map document id -> [paths] across the documents tree, for uniqueness checks."""
     index: dict[str, list[str]] = defaultdict(list)
-    for path in DOCUMENTS_DIR.rglob("*.md"):
+    for path in documents_dir.rglob("*.md"):
         try:
             doc = load(path)
         except ValueError:
@@ -86,7 +97,7 @@ def cmd_validate(args: argparse.Namespace) -> int:
         print("docassert: no markdown documents matched.", file=sys.stderr)
         return 0
 
-    id_index = _build_id_index()
+    id_index = _build_id_index(Path(args.documents_dir))
     results_by_doc: dict[str, list[CheckResult]] = {}
     for path in files:
         try:
@@ -106,12 +117,12 @@ def cmd_validate(args: argparse.Namespace) -> int:
     if args.markdown:
         Path(args.markdown).write_text(report.markdown(results_by_doc))
 
-    return sum(1 for rs in results_by_doc.values()
-               for r in rs if r.is_blocking_failure)
+    return _capped(sum(1 for rs in results_by_doc.values()
+                       for r in rs if r.is_blocking_failure))
 
 
 def cmd_consistency(args: argparse.Namespace) -> int:
-    results = run_consistency(DOCUMENTS_DIR, with_semantic=not args.no_semantic)
+    results = run_consistency(args.documents_dir, with_semantic=not args.no_semantic)
     results_by_doc = {"consistency (cross-document)": results}
 
     print(report.console(results_by_doc))
@@ -123,7 +134,7 @@ def cmd_consistency(args: argparse.Namespace) -> int:
         Path(args.markdown).write_text(
             report.markdown(results_by_doc, title="docassert consistency"))
 
-    return sum(1 for r in results if r.is_blocking_failure)
+    return _capped(sum(1 for r in results if r.is_blocking_failure))
 
 
 def _project_code(value: str | None) -> str | None:
@@ -132,7 +143,7 @@ def _project_code(value: str | None) -> str | None:
 
 
 def cmd_rtm(args: argparse.Namespace) -> int:
-    graph = build_graph(DOCUMENTS_DIR)
+    graph = build_graph(args.documents_dir)
     code = _project_code(args.project)
     text = rtm.render_csv(graph, code) if args.csv else rtm.render_markdown(graph, code)
     if args.out:
@@ -145,7 +156,7 @@ def cmd_rtm(args: argparse.Namespace) -> int:
 
 def cmd_projects(args: argparse.Namespace) -> int:
     from . import projects as proj
-    plist = proj.load_projects(DOCUMENTS_DIR)
+    plist = proj.load_projects(args.documents_dir)
     issues = proj.registry_issues(plist)
     for issue in issues:
         print(f"docassert: {issue}", file=sys.stderr)
@@ -172,7 +183,7 @@ def cmd_projects(args: argparse.Namespace) -> int:
 def cmd_status(args: argparse.Namespace) -> int:
     from . import status as status_mod
     if args.index:
-        index = status_mod.build_index(DOCUMENTS_DIR)
+        index = status_mod.build_index(args.documents_dir)
         if args.format == "json":
             text = status_mod.render_json(index)
         elif args.format == "html":
@@ -181,7 +192,7 @@ def cmd_status(args: argparse.Namespace) -> int:
             text = status_mod.render_index_markdown(index)
         tag = index["overall"]["rag"]
     else:
-        model = status_mod.build_status(DOCUMENTS_DIR, project=args.project)
+        model = status_mod.build_status(args.documents_dir, project=args.project)
         if args.project and not model["documents"]:
             print(f"docassert: no documents for project {args.project!r}", file=sys.stderr)
             return 2
@@ -206,16 +217,17 @@ def cmd_pages(args: argparse.Namespace) -> int:
     from . import status as status_mod
     out = Path(args.out)
     out.mkdir(parents=True, exist_ok=True)
+    docs_dir = args.documents_dir
 
-    index = status_mod.build_index(DOCUMENTS_DIR)
+    index = status_mod.build_index(docs_dir)
     (out / "index.html").write_text(status_mod.render_index_html(index))
 
-    plist = projects_mod.load_projects(DOCUMENTS_DIR)
+    plist = projects_mod.load_projects(docs_dir)
     for p in plist:
-        model = status_mod.build_status(DOCUMENTS_DIR, project=p["id"])
+        model = status_mod.build_status(docs_dir, project=p["id"])
         (out / f"{p['id']}.html").write_text(status_mod.render_html(model))
 
-    (out / "RTM.md").write_text(rtm.render_markdown(build_graph(DOCUMENTS_DIR)))
+    (out / "RTM.md").write_text(rtm.render_markdown(build_graph(docs_dir)))
     print(f"docassert: wrote {out}/ — index + {len(plist)} project page(s) + RTM.md "
           f"(portfolio: {index['overall']['rag']})")
     return 0
@@ -256,10 +268,15 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--version", action="version", version=f"docassert {__version__}")
     sub = parser.add_subparsers(dest="command", required=True)
 
+    def docs_dir_opt(sp: argparse.ArgumentParser) -> None:
+        sp.add_argument("--documents-dir", default=DEFAULT_DOCUMENTS_DIR,
+                        help=f"Documents tree to read (default: {DEFAULT_DOCUMENTS_DIR}/).")
+
     v = sub.add_parser("validate", help="Validate documents against their criteria.")
     v.add_argument("paths", nargs="+", help="Markdown files or globs.")
     v.add_argument("--junit", help="Write a JUnit XML report to this path.")
     v.add_argument("--markdown", help="Write a PR-comment markdown report to this path.")
+    docs_dir_opt(v)
     v.set_defaults(func=cmd_validate)
 
     c = sub.add_parser("consistency", help="Check cross-document traceability.")
@@ -267,12 +284,14 @@ def main(argv: list[str] | None = None) -> int:
     c.add_argument("--markdown", help="Write a PR-comment markdown report to this path.")
     c.add_argument("--no-semantic", action="store_true",
                    help="Skip AI alignment (structural consistency only).")
+    docs_dir_opt(c)
     c.set_defaults(func=cmd_consistency)
 
     r = sub.add_parser("rtm", help="Generate the requirements traceability matrix.")
     r.add_argument("--out", help="Write to this path instead of stdout.")
     r.add_argument("--csv", action="store_true", help="Emit CSV instead of Markdown.")
     r.add_argument("--project", help="Scope to one project (PRJ-NNN-CODE id or CODE).")
+    docs_dir_opt(r)
     r.set_defaults(func=cmd_rtm)
 
     s = sub.add_parser("status", help="Derive a project status page from the documents.")
@@ -284,16 +303,19 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("--index", action="store_true",
                    help="Render the multi-project portfolio index instead of one status.")
     s.add_argument("--out", help="Write to this path instead of stdout.")
+    docs_dir_opt(s)
     s.set_defaults(func=cmd_status)
 
     pg = sub.add_parser("pages", help="Build the full Pages site (portfolio index + a page per project).")
     pg.add_argument("--out", default="_site", help="Output directory (default: _site).")
+    docs_dir_opt(pg)
     pg.set_defaults(func=cmd_pages)
 
     p = sub.add_parser("projects", help="Generate the project registry from the project.md anchors.")
     p.add_argument("--out", help="Write to this path instead of stdout (e.g. projects.yaml).")
     p.add_argument("--check", action="store_true",
                    help="Exit non-zero if the registry file is stale (CI freshness gate).")
+    docs_dir_opt(p)
     p.set_defaults(func=cmd_projects)
 
     ini = sub.add_parser("init", help="Scaffold the default criteria/schema/profiles/templates into a repo.")

{docassert-0.2.0 → docassert-0.2.1}/docassert/consistency.py

@@ -130,6 +130,12 @@ def check_profile_completeness(documents_dir: str | Path = "documents") -> Check
 
 
 # ── semantic (advisory) ────────────────────────────────────────────────────
+# Each alignment edge costs one API call, so a large graph could otherwise run
+# away on cost. Cap per run; tune with `alignment_limit` in consistency.yaml
+# (0 disables the cap).
+DEFAULT_ALIGNMENT_LIMIT = 25
+
+
 def run_alignment_checks(graph, config) -> list[CheckResult]:
     edges = []  # (prompt, parent, child, relation)
     for rule in config.get("alignment", []):
@@ -142,12 +148,26 @@ def run_alignment_checks(graph, config) -> list[CheckResult]:
 
     if not edges:
         return []
+
+    limit = int(config.get("alignment_limit", DEFAULT_ALIGNMENT_LIMIT) or 0)
+    note: CheckResult | None = None
+    if limit and len(edges) > limit:
+        note = CheckResult(
+            "alignment-limit", True, False,
+            f"graded {limit} of {len(edges)} link(s) — raise `alignment_limit` "
+            f"in consistency.yaml to grade more per run",
+            kind="semantic", score=None)
+        edges = edges[:limit]
+
     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]
+    results = [run_alignment(f"align:{c.id}-{rel}-{p.id}", prompt, p.text, c.text)
+               for prompt, p, c, rel in edges]
+    if note is not None:
+        results.append(note)
+    return results
 
 
 def run_consistency(documents_dir: str | Path = "documents",

{docassert-0.2.0 → docassert-0.2.1/docassert.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.2.0
+Version: 0.2.1
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0
@@ -80,7 +80,7 @@ you can customize them.
 
 | Command | What it does |
 |---|---|
-| `docassert validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures. |
+| `docassert validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures (capped at 125). |
 | `docassert consistency` | Cross-document checks: referential integrity, coverage, required links, profile completeness. |
 | `docassert rtm [--project ID]` | Requirements traceability matrix (Markdown or CSV). |
 | `docassert status [--project ID] [--index]` | Derived project status (md / json / html). |
@@ -89,6 +89,10 @@ you can customize them.
 | `docassert init [DIR]` | Scaffold the default config into a repo. |
 | `docassert extract <file>` | Extract plain text from a source `.docx` / `.pdf` / `.md` / `.txt` (the first step of doc-to-pmo conversion). Needs the `convert` extra: `pip install "docassert[convert]"`. |
 
+Every document-reading command accepts `--documents-dir` (default `documents/`).
+AI alignment grades at most `alignment_limit` links per run (default 25; set it
+in `consistency.yaml`, `0` = no cap) so API cost stays bounded on large graphs.
+
 ## Document kinds
 
 Twenty kinds, each a `templates/<kind>.template.md` + `schema/<kind>.schema.json`

{docassert-0.2.0 → docassert-0.2.1}/docassert.egg-info/SOURCES.txt

@@ -90,6 +90,7 @@ docassert/_data/templates/test-cases.template.md
 docassert/_data/templates/user-story.template.md
 tests/test_config.py
 tests/test_consistency.py
+tests/test_defects.py
 tests/test_extract.py
 tests/test_graph.py
 tests/test_kinds_delivery.py

docassert-0.2.1/tests/test_defects.py

@@ -0,0 +1,85 @@
+"""Tests for the 0.2.1 defect fixes: exit-code cap, --documents-dir, alignment cap."""
+from docassert import consistency as C
+from docassert.cli import _capped, main
+from docassert.graph import Graph
+from docassert.models import CheckResult, Item
+
+PROJECT_MD = """---
+kind: project
+id: PRJ-009-TST
+code: TST
+name: Test Project
+sponsor: jane.doe
+status: proposed
+---
+
+## Overview
+A test project.
+
+## Scope
+Everything.
+"""
+
+
+# ── exit-code cap ────────────────────────────────────────────────────────────
+def test_exit_code_capped_below_wraparound():
+    assert _capped(0) == 0
+    assert _capped(3) == 3
+    assert _capped(125) == 125
+    assert _capped(256) == 125   # would otherwise wrap to exit status 0
+    assert _capped(1000) == 125
+
+
+# ── --documents-dir ──────────────────────────────────────────────────────────
+def test_projects_reads_documents_dir_flag(tmp_path, monkeypatch, capsys):
+    docs = tmp_path / "elsewhere"
+    (docs / "PRJ-009-TST").mkdir(parents=True)
+    (docs / "PRJ-009-TST" / "project.md").write_text(PROJECT_MD, encoding="utf-8")
+    monkeypatch.chdir(tmp_path)   # cwd has no documents/ at all
+    assert main(["projects", "--documents-dir", str(docs)]) == 0
+    assert "PRJ-009-TST" in capsys.readouterr().out
+
+
+def test_status_reads_documents_dir_flag(tmp_path, monkeypatch, capsys):
+    docs = tmp_path / "elsewhere"
+    (docs / "PRJ-009-TST").mkdir(parents=True)
+    (docs / "PRJ-009-TST" / "project.md").write_text(PROJECT_MD, encoding="utf-8")
+    monkeypatch.chdir(tmp_path)
+    assert main(["status", "--documents-dir", str(docs), "--summary"]) == 0
+    assert "Derived from 1 documents" in capsys.readouterr().out
+
+
+# ── alignment call cap ───────────────────────────────────────────────────────
+def _graph_with_edges(n):
+    g = Graph()
+    g.add(Item("TST-BR-001", "TST", "BR", "parent", {}, "d.md", "k", "approved", "S"))
+    for i in range(n):
+        g.add(Item(f"TST-PR-{i:03d}", "TST", "PR", "child",
+                   {"traces": ["TST-BR-001"]}, "d.md", "k", "approved", "S"))
+    return g
+
+
+def _stub_calls(monkeypatch):
+    calls = []
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")
+    monkeypatch.setattr(C, "run_alignment",
+                        lambda cid, *a: calls.append(cid) or CheckResult(
+                            cid, True, False, "ok", kind="semantic", score=1.0))
+    return calls
+
+
+def test_alignment_capped(monkeypatch):
+    calls = _stub_calls(monkeypatch)
+    cfg = {"alignment": [{"relation": "traces", "prompt": "judge"}], "alignment_limit": 2}
+    results = C.run_alignment_checks(_graph_with_edges(4), cfg)
+    assert len(calls) == 2
+    note = next(r for r in results if r.check_id == "alignment-limit")
+    assert "graded 2 of 4" in note.detail and not note.blocking
+
+
+def test_alignment_cap_disabled_with_zero(monkeypatch):
+    calls = _stub_calls(monkeypatch)
+    cfg = {"alignment": [{"relation": "traces", "prompt": "judge"}], "alignment_limit": 0}
+    results = C.run_alignment_checks(_graph_with_edges(4), cfg)
+    assert len(calls) == 4
+    assert not any(r.check_id == "alignment-limit" for r in results)