docassert 0.3.0__tar.gz → 0.5.0__tar.gz

{docassert-0.3.0/docassert.egg-info → docassert-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.3.0
+Version: 0.5.0
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0
@@ -75,14 +75,18 @@ docassert pages --out _site           # a portfolio dashboard + a page per proje
 Config resolves **local override → packaged default**: docassert ships sensible
 defaults, and your repo's own `criteria/` (or `schema/`, `profiles/`,
 `consistency.yaml`) wins when present. `docassert init` copies the defaults in so
-you can customize them.
+you can customize them — including the **doc-to-pmo Claude skill** into
+`.claude/skills/`, so Claude Code in your repo knows how to convert existing
+Word/PDF documents into testable docassert documents (faithfully — gaps are
+flagged as TODOs, never invented). The skill's source is
+[`skills/doc-to-pmo/SKILL.md`](skills/doc-to-pmo/SKILL.md).
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `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 validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures (capped at 125). Reports: `--junit` / `--markdown` / `--json`. |
+| `docassert consistency` | Cross-document checks: referential integrity, coverage, required links, profile completeness. Reports: `--junit` / `--markdown` / `--json`. |
 | `docassert rtm [--project ID]` | Requirements traceability matrix (Markdown or CSV). |
 | `docassert status [--project ID] [--index]` | Derived project status (md / json / html). |
 | `docassert pages --out DIR` | Build the portfolio site (index + a page per project). |
@@ -113,6 +117,17 @@ kind is adding a trio — no code for the common cases.
 - **Semantic — AI-graded, advisory.** Scored via the Anthropic API and posted to
   the PR — never blocking. Set `ANTHROPIC_API_KEY` to enable; skipped otherwise.
 
+## Privacy
+
+Structural checks run **entirely locally** — no document content leaves your
+machine or CI runner. Semantic checks are the one exception: when
+`ANTHROPIC_API_KEY` is set, the graded excerpts (section text, linked item
+text) are sent to the **Anthropic API** for scoring. Without the key, semantic
+checks are skipped and nothing is sent anywhere. Alignment grading is capped at
+`alignment_limit` links per run (default 25). If your documents are
+confidential, run without the key or review [Anthropic's data-usage
+policies](https://www.anthropic.com/legal/commercial-terms) first.
+
 ## Development
 
 ```bash

{docassert-0.3.0 → docassert-0.5.0}/README.md

@@ -37,14 +37,18 @@ docassert pages --out _site           # a portfolio dashboard + a page per proje
 Config resolves **local override → packaged default**: docassert ships sensible
 defaults, and your repo's own `criteria/` (or `schema/`, `profiles/`,
 `consistency.yaml`) wins when present. `docassert init` copies the defaults in so
-you can customize them.
+you can customize them — including the **doc-to-pmo Claude skill** into
+`.claude/skills/`, so Claude Code in your repo knows how to convert existing
+Word/PDF documents into testable docassert documents (faithfully — gaps are
+flagged as TODOs, never invented). The skill's source is
+[`skills/doc-to-pmo/SKILL.md`](skills/doc-to-pmo/SKILL.md).
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `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 validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures (capped at 125). Reports: `--junit` / `--markdown` / `--json`. |
+| `docassert consistency` | Cross-document checks: referential integrity, coverage, required links, profile completeness. Reports: `--junit` / `--markdown` / `--json`. |
 | `docassert rtm [--project ID]` | Requirements traceability matrix (Markdown or CSV). |
 | `docassert status [--project ID] [--index]` | Derived project status (md / json / html). |
 | `docassert pages --out DIR` | Build the portfolio site (index + a page per project). |
@@ -75,6 +79,17 @@ kind is adding a trio — no code for the common cases.
 - **Semantic — AI-graded, advisory.** Scored via the Anthropic API and posted to
   the PR — never blocking. Set `ANTHROPIC_API_KEY` to enable; skipped otherwise.
 
+## Privacy
+
+Structural checks run **entirely locally** — no document content leaves your
+machine or CI runner. Semantic checks are the one exception: when
+`ANTHROPIC_API_KEY` is set, the graded excerpts (section text, linked item
+text) are sent to the **Anthropic API** for scoring. Without the key, semantic
+checks are skipped and nothing is sent anywhere. Alignment grading is capped at
+`alignment_limit` links per run (default 25). If your documents are
+confidential, run without the key or review [Anthropic's data-usage
+policies](https://www.anthropic.com/legal/commercial-terms) first.
+
 ## Development
 
 ```bash

{docassert-0.3.0 → docassert-0.5.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.3.0"
+__version__ = "0.5.0"

docassert-0.5.0/docassert/_data/skills/doc-to-pmo/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: doc-to-pmo
+description: Convert an existing business document (Word .docx, PDF, or pasted text) into a docassert Markdown document so it can be unit-tested and gated in CI. Use when someone wants to bring an existing charter, BRD, PRD, risk register, or any other supported kind into a PMO-as-Code repo.
+---
+
+# doc-to-pmo
+
+Convert a source document into a standard docassert document. **Map the content
+faithfully — never invent missing facts to make the audit pass.** A document
+that lacks measurable success criteria *should* fail the audit; your job is to
+surface that, not hide it.
+
+Requires docassert (`pipx install docassert`; add `"docassert[convert]"` for
+.docx/.pdf extraction).
+
+## Steps
+
+1. **Identify the kind.** Supported kinds: `charter`, `business-case`, `brd`,
+   `prd`, `frnfr`, `user-story`, `test-cases`, `adr`, `risk-register`,
+   `raci-stakeholder`, `qa-test-plan`, `data-migration-plan`,
+   `release-cutover-plan`, `rollback-plan`, `hypercare-plan`, `runbook`,
+   `status-report`, `post-implementation-review`, `benefits-realization`.
+   One source file may yield several documents (a "BRD" is often really a
+   BRD + PRD + NFRs + risks). Propose the split to the user before writing.
+
+2. **Anchor the project.** Every document belongs to a project
+   (`PRJ-NNN-CODE`). Check `projects.yaml` or `documents/` for an existing
+   anchor; if there is none, create one (ask the user for the code, name, and
+   sponsor — don't guess):
+
+   ```bash
+   docassert new project --code AUR --name "Aurora — Customer Onboarding"
+   ```
+
+3. **Extract the source text** (`.docx`, `.pdf`, `.md`, `.txt`):
+
+   ```bash
+   docassert extract path/to/source.docx
+   ```
+
+   For pasted text or Google Docs, ask the user to paste the content or export
+   to `.docx`/`.pdf` first.
+
+4. **Scaffold, then fill.** Let docassert create the file with the identity
+   (frontmatter `project:`, namespaced `id:`) already correct, then map the
+   source content into its sections:
+
+   ```bash
+   docassert new brd --project PRJ-001-AUR
+   # docassert: created documents/PRJ-001-AUR/brd.md
+   # docassert: next item id: AUR-BR-001
+   ```
+
+   Keep `status: draft` unless the source clearly states an approval.
+
+5. **Author traceable items where the kind defines them.** Requirements,
+   criteria, tests, risks, and decisions are bullets with a stable namespaced
+   id and typed links — use the `next item id` hints for numbering:
+
+   ```
+   - **AUR-BR-001**: The business shall reduce onboarding time to under 2 days.
+   - **AUR-PR-001** (traces: AUR-BR-001): The product shall provide a self-serve flow.
+   - **AUR-RISK-001** (threatens: AUR-BR-001): Migration may slip. Probability: High.
+     Impact: High. Owner: alex.kim. Response: dual-run for two weeks.
+   ```
+
+   Relations: `traces` (child → parent requirement), `verifies` (AC → PR/FR),
+   `tests` (TC → AC), `threatens` (RISK → BR/PR), `affects` (ADR → FR/NFR).
+   Only link items that genuinely relate in the source.
+
+6. **Flag gaps honestly.** Wherever the source does not supply required
+   information, insert a bullet or note beginning with `TODO:` describing what
+   is missing (e.g. `- TODO: no measurable success criteria found in the
+   source — add a metric and threshold.`). Do **not** fabricate a number, an
+   owner, a date, or a mitigation.
+
+7. **Validate and report.**
+
+   ```bash
+   docassert validate documents/PRJ-001-AUR/*.md
+   docassert consistency
+   ```
+
+   Summarise what passed, what blocks, and exactly which TODOs the user must
+   resolve before the document can merge.
+
+8. **Hand off.** Tell the user to review the generated files, resolve the
+   TODOs, then commit and open a pull request — CI re-runs the same audit and
+   gates the merge.
+
+## Guardrails
+
+- **Faithful over passing**: it is correct and expected for a weak source to
+  produce a document that fails the audit. That is the pipeline working.
+- Never invent approvals, owners, budgets, dates, or measurable thresholds.
+- Never mark a document `approved`; that is a human decision made in review.
+- If you are unsure whether something in the source is a real measurable
+  criterion, leave it as written and let the audit judge it.
+- Confidential sources stay local: don't push converted content to a public
+  repo without the user's say-so.

{docassert-0.3.0 → docassert-0.5.0}/docassert/cli.py

@@ -116,6 +116,8 @@ def cmd_validate(args: argparse.Namespace) -> int:
         Path(args.junit).write_text(report.junit(results_by_doc))
     if args.markdown:
         Path(args.markdown).write_text(report.markdown(results_by_doc))
+    if args.json:
+        Path(args.json).write_text(report.json_report(results_by_doc))
 
     return _capped(sum(1 for rs in results_by_doc.values()
                        for r in rs if r.is_blocking_failure))
@@ -133,6 +135,8 @@ def cmd_consistency(args: argparse.Namespace) -> int:
     if args.markdown:
         Path(args.markdown).write_text(
             report.markdown(results_by_doc, title="docassert consistency"))
+    if args.json:
+        Path(args.json).write_text(report.json_report(results_by_doc))
 
     return _capped(sum(1 for r in results if r.is_blocking_failure))
 
@@ -292,12 +296,14 @@ def main(argv: list[str] | None = None) -> int:
     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.")
+    v.add_argument("--json", help="Write a machine-readable JSON report to this path.")
     docs_dir_opt(v)
     v.set_defaults(func=cmd_validate)
 
     c = sub.add_parser("consistency", help="Check cross-document traceability.")
     c.add_argument("--junit", help="Write a JUnit XML report to this path.")
     c.add_argument("--markdown", help="Write a PR-comment markdown report to this path.")
+    c.add_argument("--json", help="Write a machine-readable JSON report to this path.")
     c.add_argument("--no-semantic", action="store_true",
                    help="Skip AI alignment (structural consistency only).")
     docs_dir_opt(c)

{docassert-0.3.0 → docassert-0.5.0}/docassert/config.py

@@ -101,22 +101,32 @@ def available_profiles() -> list[str]:
 
 
 # ── scaffolding (docassert init) ────────────────────────────────────────────
-_INIT_TREE = ["criteria", "schema", "profiles", "templates", "consistency.yaml"]
+# (packaged source, destination in the repo). The doc-to-pmo Claude skill lands
+# under .claude/skills/ so Claude Code discovers it in the user's repo.
+_INIT_TREE = [
+    ("criteria", "criteria"),
+    ("schema", "schema"),
+    ("profiles", "profiles"),
+    ("templates", "templates"),
+    ("consistency.yaml", "consistency.yaml"),
+    ("skills", ".claude/skills"),
+]
 
 
 def init(dest: str | Path = ".") -> list[str]:
     """Copy the packaged defaults into `dest`, skipping anything already present.
-    Returns the top-level names that were created."""
+    Returns the destination names that were created."""
     dest = Path(dest)
     created: list[str] = []
-    for name in _INIT_TREE:
-        target = dest / name
+    for src_name, dest_name in _INIT_TREE:
+        target = dest / dest_name
         if target.exists():
             continue
-        src = DATA_DIR / name
+        src = DATA_DIR / src_name
         if src.is_dir():
             shutil.copytree(src, target)
         else:
+            target.parent.mkdir(parents=True, exist_ok=True)
             target.write_text(src.read_text(encoding="utf-8"), encoding="utf-8")
-        created.append(name)
+        created.append(dest_name)
     return created

{docassert-0.3.0 → docassert-0.5.0}/docassert/report.py

@@ -1,6 +1,7 @@
-"""Render check results as console text, PR-comment markdown, or JUnit XML."""
+"""Render check results as console text, PR-comment markdown, JUnit XML, or JSON."""
 from __future__ import annotations
 
+import json as _json
 import xml.etree.ElementTree as ET
 from xml.dom import minidom
 
@@ -37,6 +38,31 @@ def summary_line(results_by_doc: dict[str, list[CheckResult]]) -> str:
     return f"{_TICK} All structural checks passed across {docs} document(s) {_DASH} clear to merge."
 
 
+def json_report(results_by_doc: dict[str, list[CheckResult]]) -> str:
+    """Machine-readable results: one entry per document, plus a summary."""
+    documents = {
+        path: [{
+            "check_id": r.check_id,
+            "passed": r.passed,
+            "blocking": r.blocking,
+            "kind": r.kind,
+            "score": r.score,
+            "detail": r.detail,
+        } for r in results]
+        for path, results in results_by_doc.items()
+    }
+    all_results = [r for rs in results_by_doc.values() for r in rs]
+    summary = {
+        "documents": len(results_by_doc),
+        "checks": len(all_results),
+        "blocking_failures": sum(1 for r in all_results if r.is_blocking_failure),
+        "advisory_failures": sum(1 for r in all_results
+                                 if not r.passed and not r.blocking),
+        "passed": not any(r.is_blocking_failure for r in all_results),
+    }
+    return _json.dumps({"summary": summary, "documents": documents}, indent=2) + "\n"
+
+
 def markdown(results_by_doc: dict[str, list[CheckResult]],
              title: str = "docassert audit") -> str:
     """PR-comment body."""

{docassert-0.3.0 → docassert-0.5.0/docassert.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.3.0
+Version: 0.5.0
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0
@@ -75,14 +75,18 @@ docassert pages --out _site           # a portfolio dashboard + a page per proje
 Config resolves **local override → packaged default**: docassert ships sensible
 defaults, and your repo's own `criteria/` (or `schema/`, `profiles/`,
 `consistency.yaml`) wins when present. `docassert init` copies the defaults in so
-you can customize them.
+you can customize them — including the **doc-to-pmo Claude skill** into
+`.claude/skills/`, so Claude Code in your repo knows how to convert existing
+Word/PDF documents into testable docassert documents (faithfully — gaps are
+flagged as TODOs, never invented). The skill's source is
+[`skills/doc-to-pmo/SKILL.md`](skills/doc-to-pmo/SKILL.md).
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `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 validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures (capped at 125). Reports: `--junit` / `--markdown` / `--json`. |
+| `docassert consistency` | Cross-document checks: referential integrity, coverage, required links, profile completeness. Reports: `--junit` / `--markdown` / `--json`. |
 | `docassert rtm [--project ID]` | Requirements traceability matrix (Markdown or CSV). |
 | `docassert status [--project ID] [--index]` | Derived project status (md / json / html). |
 | `docassert pages --out DIR` | Build the portfolio site (index + a page per project). |
@@ -113,6 +117,17 @@ kind is adding a trio — no code for the common cases.
 - **Semantic — AI-graded, advisory.** Scored via the Anthropic API and posted to
   the PR — never blocking. Set `ANTHROPIC_API_KEY` to enable; skipped otherwise.
 
+## Privacy
+
+Structural checks run **entirely locally** — no document content leaves your
+machine or CI runner. Semantic checks are the one exception: when
+`ANTHROPIC_API_KEY` is set, the graded excerpts (section text, linked item
+text) are sent to the **Anthropic API** for scoring. Without the key, semantic
+checks are skipped and nothing is sent anywhere. Alignment grading is capped at
+`alignment_limit` links per run (default 25). If your documents are
+confidential, run without the key or review [Anthropic's data-usage
+policies](https://www.anthropic.com/legal/commercial-terms) first.
+
 ## Development
 
 ```bash

{docassert-0.3.0 → docassert-0.5.0}/docassert.egg-info/SOURCES.txt

@@ -69,6 +69,7 @@ docassert/_data/schema/runbook.schema.json
 docassert/_data/schema/status-report.schema.json
 docassert/_data/schema/test-cases.schema.json
 docassert/_data/schema/user-story.schema.json
+docassert/_data/skills/doc-to-pmo/SKILL.md
 docassert/_data/templates/adr.template.md
 docassert/_data/templates/benefits-realization.template.md
 docassert/_data/templates/brd.template.md
@@ -94,6 +95,7 @@ tests/test_consistency.py
 tests/test_defects.py
 tests/test_extract.py
 tests/test_graph.py
+tests/test_json_report.py
 tests/test_kinds_delivery.py
 tests/test_kinds_governance.py
 tests/test_kinds_operate.py

{docassert-0.3.0 → docassert-0.5.0}/tests/test_config.py

@@ -23,6 +23,9 @@ def test_packaged_data_mirrors_root_config():
                 f"{name}/{fn} drifted between the repo root and packaged _data"
     assert filecmp.cmp(ROOT / "consistency.yaml",
                        config.DATA_DIR / "consistency.yaml", shallow=False)
+    assert filecmp.cmp(ROOT / "skills" / "doc-to-pmo" / "SKILL.md",
+                       config.DATA_DIR / "skills" / "doc-to-pmo" / "SKILL.md",
+                       shallow=False), "doc-to-pmo skill drifted between root and packaged copy"
 
 
 # ── resolution: packaged default when there's no local config ───────────────
@@ -52,8 +55,19 @@ def test_unknown_kind_raises(monkeypatch, tmp_path):
 # ── init scaffolds, and is idempotent ──────────────────────────────────────
 def test_init_scaffolds_defaults(tmp_path):
     created = config.init(tmp_path)
-    assert set(created) == {"criteria", "schema", "profiles", "templates", "consistency.yaml"}
+    assert set(created) == {"criteria", "schema", "profiles", "templates",
+                            "consistency.yaml", ".claude/skills"}
     assert (tmp_path / "criteria" / "charter.criteria.yaml").is_file()
     assert (tmp_path / "schema" / "project.schema.json").is_file()
     assert (tmp_path / "consistency.yaml").is_file()
+    assert (tmp_path / ".claude" / "skills" / "doc-to-pmo" / "SKILL.md").is_file()
     assert config.init(tmp_path) == []  # second run creates nothing
+
+
+def test_init_keeps_existing_skills(tmp_path):
+    mine = tmp_path / ".claude" / "skills"
+    mine.mkdir(parents=True)
+    (mine / "my-skill.md").write_text("mine", encoding="utf-8")
+    created = config.init(tmp_path)
+    assert ".claude/skills" not in created          # existing dir left alone
+    assert (mine / "my-skill.md").read_text() == "mine"

{docassert-0.3.0 → docassert-0.5.0}/tests/test_extract.py

@@ -30,6 +30,38 @@ def test_unsupported_type_raises(tmp_path):
         E.extract(f)
 
 
+def _minimal_pdf(text: str) -> bytes:
+    """Assemble a one-page PDF with `text` in a content stream, xref included."""
+    stream = f"BT /F1 24 Tf 72 720 Td ({text}) Tj ET".encode()
+    objects = [
+        b"<< /Type /Catalog /Pages 2 0 R >>",
+        b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+        (b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] "
+         b"/Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>"),
+        b"<< /Length " + str(len(stream)).encode() + b" >>\nstream\n" + stream + b"\nendstream",
+        b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+    ]
+    out = b"%PDF-1.4\n"
+    offsets = []
+    for i, body in enumerate(objects, start=1):
+        offsets.append(len(out))
+        out += f"{i} 0 obj\n".encode() + body + b"\nendobj\n"
+    xref_at = len(out)
+    out += f"xref\n0 {len(objects) + 1}\n0000000000 65535 f \n".encode()
+    for off in offsets:
+        out += f"{off:010d} 00000 n \n".encode()
+    out += (f"trailer\n<< /Size {len(objects) + 1} /Root 1 0 R >>\n"
+            f"startxref\n{xref_at}\n%%EOF\n").encode()
+    return out
+
+
+def test_extract_pdf(tmp_path):
+    pytest.importorskip("pypdf")  # needs the 'convert' extra
+    path = tmp_path / "s.pdf"
+    path.write_bytes(_minimal_pdf("Hello docassert PDF"))
+    assert "Hello docassert PDF" in E.extract(path)
+
+
 def test_extract_docx_paragraphs_and_tables(tmp_path):
     docx = pytest.importorskip("docx")  # needs the 'convert' extra
     d = docx.Document()

docassert-0.5.0/tests/test_json_report.py

@@ -0,0 +1,43 @@
+"""Tests for the machine-readable JSON report (`--json`)."""
+import json
+from pathlib import Path
+
+from docassert import report
+from docassert.cli import main
+from docassert.models import CheckResult
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def test_json_report_shape():
+    results = {
+        "a.md": [CheckResult("c1", True, True, "ok"),
+                 CheckResult("c2", False, True, "bad")],
+        "b.md": [CheckResult("c3", False, False, "meh", kind="semantic", score=0.4)],
+    }
+    data = json.loads(report.json_report(results))
+    assert data["summary"] == {"documents": 2, "checks": 3, "blocking_failures": 1,
+                               "advisory_failures": 1, "passed": False}
+    assert data["documents"]["a.md"][1]["check_id"] == "c2"
+    assert data["documents"]["b.md"][0]["score"] == 0.4
+
+
+def test_cli_validate_writes_json(tmp_path, monkeypatch):
+    monkeypatch.chdir(ROOT)  # criteria/schema resolve; sample documents exist
+    out = tmp_path / "r.json"
+    code = main(["validate", "documents/PRJ-001-AUR/charter.md", "--json", str(out)])
+    assert code == 0
+    data = json.loads(out.read_text())
+    assert data["summary"]["passed"] is True
+    assert "documents/PRJ-001-AUR/charter.md" in data["documents"]
+
+
+def test_cli_consistency_writes_json(tmp_path, monkeypatch):
+    monkeypatch.chdir(ROOT)
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+    out = tmp_path / "c.json"
+    code = main(["consistency", "--no-semantic", "--json", str(out)])
+    assert code == 0
+    data = json.loads(out.read_text())
+    checks = {c["check_id"] for c in data["documents"]["consistency (cross-document)"]}
+    assert {"item-id-uniqueness", "referential-integrity", "coverage"} <= checks