docassert 0.5.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.5.0
+Version: 0.7.0
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0
@@ -33,7 +33,9 @@ Requires-Dist: python-docx>=1.1; extra == "convert"
 Requires-Dist: pypdf>=4.0; extra == "convert"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
 Dynamic: license-file
 
 # docassert
@@ -49,7 +51,8 @@ semantic checks that advise. Requirements trace end to end, and project status i
 derived from the documents rather than self-reported.
 
 docassert is the reference implementation of **[PMO as Code](https://c4g-john.github.io/pmo-as-code/)** —
-a vendor-neutral standard for running a PMO from version-controlled, declarative files.
+a vendor-neutral standard for running a PMO from version-controlled, declarative
+files. It implements the [PMO as Code specification](https://github.com/c4g-john/pmo-as-code-spec) **v0.1**.
 
 ## Install
 
@@ -89,7 +92,7 @@ flagged as TODOs, never invented). The skill's source is
 | `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). |
+| `docassert pages --out DIR` | Build the portfolio site (index + a page per project + shields.io badge endpoints `badge.json` / `badges/<ID>.json`). |
 | `docassert projects [--out] [--check]` | Generate / verify the project registry. |
 | `docassert new <kind> --project ID` | Scaffold a document from its template with identity filled in (`new project --code XYZ` auto-numbers the id); suggests the next free item ids. |
 | `docassert init [DIR]` | Scaffold the default config into a repo. |
@@ -114,6 +117,9 @@ kind is adding a trio — no code for the common cases.
 - **Structural — deterministic, blocking.** Required fields and sections,
   measurable success criteria, risks with owner + mitigation, resolving
   references, unique ids. Plain Python, reliable enough to gate a merge.
+  Within this tier, *integrity* checks (malformed items, bad types, duplicate
+  ids) block at any status, while *completeness* checks relax to advisory on
+  `status: draft` and gate once a document is proposed — WIP is never punished.
 - **Semantic — AI-graded, advisory.** Scored via the Anthropic API and posted to
   the PR — never blocking. Set `ANTHROPIC_API_KEY` to enable; skipped otherwise.
 

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

@@ -11,7 +11,8 @@ semantic checks that advise. Requirements trace end to end, and project status i
 derived from the documents rather than self-reported.
 
 docassert is the reference implementation of **[PMO as Code](https://c4g-john.github.io/pmo-as-code/)** —
-a vendor-neutral standard for running a PMO from version-controlled, declarative files.
+a vendor-neutral standard for running a PMO from version-controlled, declarative
+files. It implements the [PMO as Code specification](https://github.com/c4g-john/pmo-as-code-spec) **v0.1**.
 
 ## Install
 
@@ -51,7 +52,7 @@ flagged as TODOs, never invented). The skill's source is
 | `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). |
+| `docassert pages --out DIR` | Build the portfolio site (index + a page per project + shields.io badge endpoints `badge.json` / `badges/<ID>.json`). |
 | `docassert projects [--out] [--check]` | Generate / verify the project registry. |
 | `docassert new <kind> --project ID` | Scaffold a document from its template with identity filled in (`new project --code XYZ` auto-numbers the id); suggests the next free item ids. |
 | `docassert init [DIR]` | Scaffold the default config into a repo. |
@@ -76,6 +77,9 @@ kind is adding a trio — no code for the common cases.
 - **Structural — deterministic, blocking.** Required fields and sections,
   measurable success criteria, risks with owner + mitigation, resolving
   references, unique ids. Plain Python, reliable enough to gate a merge.
+  Within this tier, *integrity* checks (malformed items, bad types, duplicate
+  ids) block at any status, while *completeness* checks relax to advisory on
+  `status: draft` and gate once a document is proposed — WIP is never punished.
 - **Semantic — AI-graded, advisory.** Scored via the Anthropic API and posted to
   the PR — never blocking. Set `ANTHROPIC_API_KEY` to enable; skipped otherwise.
 

{docassert-0.5.0 → docassert-0.7.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.5.0"
+__version__ = "0.7.0"

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/adr.criteria.yaml

@@ -18,9 +18,13 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/adr.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: items-well-formed
     type: structural
@@ -28,7 +32,7 @@ checks:
     description: Every decision is a valid **ADR-###** item.
   - id: adr-items-have-status
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every decision declares a valid Status (proposed | accepted | superseded | deprecated | rejected).
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/benefits-realization.criteria.yaml

@@ -16,13 +16,17 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/benefits-realization.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: measurable-items
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every benefit states a measurable target.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/brd.criteria.yaml

@@ -16,9 +16,13 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/brd.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: items-well-formed
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/business-case.criteria.yaml

@@ -13,9 +13,13 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/business-case.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/charter.criteria.yaml

@@ -26,19 +26,23 @@ checks:
     blocking: true
     description: Frontmatter is present and valid against schema/charter.schema.json.
 
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
 
   - id: measurable-success-criteria
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every Success Criteria bullet states a measurable threshold (number, %, currency, or date).
 
   - id: risks-have-owner-and-mitigation
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every Risks bullet names an Owner and a Mitigation.
 
   - id: dates-consistent

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/data-migration-plan.criteria.yaml

@@ -14,13 +14,17 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/data-migration-plan.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: mapping-table
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: The Field Mapping section contains a mapping table.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/frnfr.criteria.yaml

@@ -17,9 +17,13 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/frnfr.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: items-well-formed
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/hypercare-plan.criteria.yaml

@@ -13,13 +13,17 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/hypercare-plan.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: measurable-exit-criteria
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every hypercare exit criterion states a measurable threshold.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/post-implementation-review.criteria.yaml

@@ -14,9 +14,13 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/post-implementation-review.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/prd.criteria.yaml

@@ -17,9 +17,13 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/prd.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: items-well-formed
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/project.criteria.yaml

@@ -16,6 +16,10 @@ checks:
     blocking: true
     description: Frontmatter is present and valid against schema/project.schema.json.
 
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: project-id-format
     type: structural
     blocking: true
@@ -23,7 +27,7 @@ checks:
 
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
 
   - id: unique-id

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/qa-test-plan.criteria.yaml

@@ -13,13 +13,17 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/qa-test-plan.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: measurable-exit-criteria
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every exit criterion states a measurable threshold.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/raci-stakeholder.criteria.yaml

@@ -10,13 +10,17 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/raci-stakeholder.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: raci-one-accountable
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every activity in the RACI Matrix has exactly one Accountable (A) role.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/release-cutover-plan.criteria.yaml

@@ -16,13 +16,17 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/release-cutover-plan.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: numbered-steps
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Cutover Steps is an ordered list of at least two numbered steps.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/risk-register.criteria.yaml

@@ -14,9 +14,13 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/risk-register.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: items-well-formed
     type: structural
@@ -24,7 +28,7 @@ checks:
     description: Every risk is a valid **RISK-###** item.
   - id: risk-items-complete
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every risk states a Probability, Impact, Owner, and Response.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/rollback-plan.criteria.yaml

@@ -15,13 +15,17 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/rollback-plan.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: numbered-steps
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Rollback Steps is an ordered list of at least two numbered steps.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/runbook.criteria.yaml

@@ -16,13 +16,17 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/runbook.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: numbered-steps
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Procedures is an ordered list of at least two numbered steps.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/status-report.criteria.yaml

@@ -12,13 +12,17 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid (includes a period date and a green/amber/red rag).
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: references-risk
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: The Risks & Issues section cites at least one RISK-### from the register.
   - id: unique-id
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/test-cases.criteria.yaml

@@ -14,9 +14,13 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/test-cases.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: items-well-formed
     type: structural

{docassert-0.5.0 → docassert-0.7.0}/docassert/_data/criteria/user-story.criteria.yaml

@@ -14,9 +14,13 @@ checks:
     type: structural
     blocking: true
     description: Frontmatter is valid against schema/user-story.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
   - id: required-sections
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every required section is present and non-empty.
   - id: items-well-formed
     type: structural
@@ -24,7 +28,7 @@ checks:
     description: Every story is a valid **US-###** item.
   - id: story-format
     type: structural
-    blocking: true
+    blocking: once-proposed
     description: Every story follows "As a … I want … so that …".
   - id: unique-id
     type: structural

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

@@ -226,13 +226,21 @@ def cmd_pages(args: argparse.Namespace) -> int:
     index = status_mod.build_index(docs_dir)
     (out / "index.html").write_text(status_mod.render_index_html(index))
 
+    # shields.io endpoint badges: one for the portfolio, one per project
+    # (https://img.shields.io/endpoint?url=<site>/badge.json)
+    (out / "badge.json").write_text(
+        status_mod.render_badge_json(index["overall"]["rag"]))
+    (out / "badges").mkdir(exist_ok=True)
+
     plist = projects_mod.load_projects(docs_dir)
     for p in plist:
         model = status_mod.build_status(docs_dir, project=p["id"])
         (out / f"{p['id']}.html").write_text(status_mod.render_html(model))
+        (out / "badges" / f"{p['id']}.json").write_text(
+            status_mod.render_badge_json(model["rag"], label=p["code"].lower()))
 
     (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 "
+    print(f"docassert: wrote {out}/ — index + {len(plist)} project page(s) + badges + RTM.md "
           f"(portfolio: {index['overall']['rag']})")
     return 0
 

{docassert-0.5.0 → docassert-0.7.0}/docassert/consistency.py

@@ -63,7 +63,8 @@ def check_referential_integrity(graph) -> CheckResult:
 
 def check_required_links(graph, config) -> CheckResult:
     required = config.get("required_links", {})
-    approved_orphans, draft_orphans = [], []
+    approved_orphans: list[str] = []
+    draft_orphans: list[str] = []
     for item in graph.all_items():
         relation = required.get(item.type)
         if relation and not item.targets(relation):
@@ -79,7 +80,8 @@ def check_required_links(graph, config) -> CheckResult:
 
 
 def check_coverage(graph, config) -> CheckResult:
-    approved_gaps, draft_gaps = [], []
+    approved_gaps: list[str] = []
+    draft_gaps: list[str] = []
     for rule in config.get("coverage", []):
         parent_prefix, relation = rule["parent"], rule["relation"]
         by_prefix = rule.get("by_prefix")

{docassert-0.5.0 → docassert-0.7.0}/docassert/profiles.py

@@ -73,7 +73,7 @@ def completeness(profile: dict, documents: list[dict], project_status: str) -> d
     """
     by_kind: dict[str, list[dict]] = {}
     for d in documents:
-        by_kind.setdefault(d.get("kind"), []).append(d)
+        by_kind.setdefault(str(d.get("kind") or ""), []).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"]]

{docassert-0.5.0 → docassert-0.7.0}/docassert/semantic.py

@@ -69,7 +69,7 @@ def _grade(prompt: str, content: str, model: str) -> dict:
             "content": f"AUDIT CRITERION:\n{prompt}\n\nDOCUMENT:\n{content}",
         }],
     )
-    text = "".join(block.text for block in message.content
+    text = "".join(getattr(block, "text", "") for block in message.content
                    if getattr(block, "type", None) == "text").strip()
     # tolerate models that wrap JSON in prose or fences
     start, end = text.find("{"), text.rfind("}")

{docassert-0.5.0 → docassert-0.7.0}/docassert/status.py

@@ -128,9 +128,9 @@ def build_status(documents_dir=DOCUMENTS_DIR, project: str | None = None) -> dic
     else:
         docs = all_docs
 
-    id_index = {}
+    id_index: dict[str, list[str]] = {}
     for d in all_docs:                       # uniqueness is always global
-        id_index.setdefault(d.id, []).append(d.path)
+        id_index.setdefault(d.id or "", []).append(d.path)
 
     documents = [{
         "kind": d.kind,
@@ -460,6 +460,14 @@ def render_html(model) -> str:
 
 
 _RAG_COLOR = {"green": "var(--ok)", "amber": "var(--amber)", "red": "var(--bad)"}
+_BADGE_COLOR = {"green": "brightgreen", "amber": "orange", "red": "red"}
+
+
+def render_badge_json(rag: str, label: str = "pmo docs") -> str:
+    """A shields.io endpoint payload (https://shields.io/badges/endpoint-badge),
+    so a README can carry a live derived-status badge."""
+    return json.dumps({"schemaVersion": 1, "label": label,
+                       "message": rag, "color": _BADGE_COLOR[rag]}) + "\n"
 
 
 def _index_card(p, esc) -> str: