agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/checks.py

@@ -0,0 +1,511 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+import re
+import yaml
+
+from agentic_project_kit.documentation_registry import check_documentation_registry
+from agentic_project_kit.workspace import Workspace, load_workspace
+
+
+STATE_GATE_DOCUMENTS = (
+    "docs/STATUS.md",
+    "docs/TEST_GATES.md",
+    "docs/handoff/CURRENT_HANDOFF.md",
+    "docs/architecture/ARCHITECTURE_CONTRACT.md",
+    "docs/DOCUMENTATION_COVERAGE.yaml",
+)
+
+STATE_GATE_SECTIONS = {
+    "docs/STATUS.md": ("## Current Goal", "## Next Safe Step"),
+    "docs/TEST_GATES.md": ("## Gate Matrix", "## Outcome Reporting"),
+    "docs/handoff/CURRENT_HANDOFF.md": ("# Current Handoff", "## Current", "## Next"),
+    "docs/architecture/ARCHITECTURE_CONTRACT.md": (
+        "## 1. Executive Summary",
+        "## 2. How to Use This Document",
+        "## 4. Decision Rules",
+        "## 7. Architectural Contract",
+        "## 17. Acceptance Criteria for Future Work",
+    ),
+}
+
+WORKSPACE_STATE_GATE_DOCUMENTS = (
+    ".agentic/state/status.md",
+    ".agentic/state/handoff/README.md",
+    ".agentic/registries/documentation.yaml",
+    ".agentic/registries/rules.yaml",
+)
+
+WORKSPACE_STATE_GATE_SECTIONS = {
+    ".agentic/state/status.md": ("# Workspace Status",),
+    ".agentic/state/handoff/README.md": ("# Workspace Handoff",),
+}
+
+STALE_HANDOFF_MARKERS = (
+    "Create project-level docs",
+    "Commit documentation-state files",
+    "Run the local gate, inspect the diff, then commit the documentation-state update",
+)
+
+CHANGELOG_QUALITY_MIN_VERSION = (0, 3, 36)
+CHANGELOG_RELEASE_HEADING = re.compile(
+    r"^##\s+v(?P<version>\d+\.\d+\.\d+)(?:\s+-\s+(?P<date>\d{4}-\d{2}-\d{2}))?.*$",
+    re.MULTILINE,
+)
+CHANGELOG_GENERIC_BULLET_PATTERNS = (
+    re.compile(r"^- prepare release metadata for v\d+\.\d+\.\d+\.?$", re.IGNORECASE),
+    re.compile(r"^- post-release verification complete:.*$", re.IGNORECASE),
+)
+CHANGELOG_SUBSTANCE_CATEGORIES = {
+    "release-evidence": (
+        "zenodo",
+        "doi",
+        "post-release",
+        "github release",
+        "release metadata",
+        "verified",
+    ),
+    "implementation-or-doc-change": (
+        "add",
+        "added",
+        "harden",
+        "hardened",
+        "close",
+        "closed",
+        "repair",
+        "repaired",
+        "wire",
+        "wired",
+        "extract",
+        "extracted",
+        "refresh",
+        "refreshed",
+        "record",
+        "recorded",
+        "translate",
+        "translated",
+        "preserve",
+        "preserved",
+    ),
+    "safety-or-scope": (
+        "bounded",
+        "read-only",
+        "disabled",
+        "guard",
+        "safety",
+        "without",
+        "no tag",
+        "no release",
+        "deferred",
+        "scope",
+    ),
+    "continuity-or-governance": (
+        "evidence",
+        "handoff",
+        "governance",
+        "contract",
+        "regression",
+        "successor",
+        "current-state",
+        "documentation boundary",
+    ),
+}
+
+
+def _open_marker_pattern(marker: str) -> re.Pattern[str]:
+    escaped_marker = re.escape(marker)
+    return re.compile(rf"(?:^|[\s\[{{(<]){escaped_marker}(?:\s*[:\-]|[\]}}>)])")
+
+
+QUALITY_PLACEHOLDER_PATTERNS = {
+    "TODO": _open_marker_pattern("TODO"),
+    "TBD": _open_marker_pattern("TBD"),
+    "FIXME": _open_marker_pattern("FIXME"),
+    "Lorem ipsum": re.compile(r"Lorem ipsum", re.IGNORECASE),
+    "coming soon": re.compile(r"coming soon", re.IGNORECASE),
+    "to be written": re.compile(r"to be written", re.IGNORECASE),
+    "to be defined": re.compile(r"to be defined", re.IGNORECASE),
+    "placeholder marker": re.compile(r"placeholder\s+(text|section|content|value)", re.IGNORECASE),
+}
+
+
+SEMANTIC_QUALITY_BOUNDARY = (
+    "Deterministic checks can detect placeholders, stale markers, coverage gaps, "
+    "and structural drift. They cannot prove semantic perfection. LLM review, "
+    "if added later, must remain advisory and separate from hard doctor gates."
+)
+
+
+@dataclass(frozen=True)
+class CheckContext:
+    root: str
+    mode: str
+    external_manifest_workspace: bool
+    gate_family: str
+    gate_documents: tuple[str, ...]
+    check_renders_statuses: bool
+    skip_status_renderer: str
+    invalid_manifest_error: str = ""
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "root": self.root,
+            "mode": self.mode,
+            "external_manifest_workspace": self.external_manifest_workspace,
+            "gate_family": self.gate_family,
+            "gate_documents": list(self.gate_documents),
+            "check_renders_statuses": self.check_renders_statuses,
+            "skip_status_renderer": self.skip_status_renderer,
+            "invalid_manifest_error": self.invalid_manifest_error,
+        }
+
+
+def load_yaml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise FileNotFoundError(f"Missing config file: {path}")
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        raise ValueError(f"YAML root must be a mapping: {path}")
+    return data
+
+
+def load_optional_yaml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    return load_yaml(path)
+
+
+def count_words(text: str) -> int:
+    return len(text.split())
+
+
+def check_docs(project_root: Path) -> list[str]:
+    config = load_optional_yaml(project_root / "sentinel.yaml")
+    errors: list[str] = []
+
+    for doc in config.get("documents", []):
+        path = project_root / doc["path"]
+        if not path.exists():
+            errors.append(f"Missing document: {doc['path']}")
+            continue
+
+        content = path.read_text(encoding="utf-8")
+        for section in doc.get("required_sections", []):
+            if section not in content:
+                errors.append(f"{doc['path']}: missing required section {section!r}")
+
+        max_words = doc.get("max_words")
+        if max_words is not None:
+            words = count_words(content)
+            if words > int(max_words):
+                errors.append(f"{doc['path']}: too long ({words}/{max_words} words)")
+
+        min_words = doc.get("min_words")
+        if min_words is not None:
+            words = count_words(content)
+            if words < int(min_words):
+                errors.append(f"{doc['path']}: too short ({words}/{min_words} words)")
+
+        if bool(doc.get("quality_checks", True)):
+            errors.extend(check_document_quality(doc["path"], content))
+
+    context = build_check_context(project_root)
+    if context.invalid_manifest_error:
+        errors.append(f"Invalid workspace manifest: {context.invalid_manifest_error}")
+    elif context.external_manifest_workspace:
+        errors.extend(check_workspace_state_gate_docs(project_root))
+    else:
+        errors.extend(check_state_gate_docs(project_root))
+        errors.extend(check_documentation_coverage(project_root))
+        errors.extend(check_documentation_registry(project_root))
+    errors.extend(check_changelog_quality(project_root))
+    return errors
+
+
+def _load_manifest_workspace_for_checks(project_root: Path) -> Workspace | None | ValueError:
+    if _is_agentic_project_kit_development_checkout(project_root):
+        return None
+    if not (project_root / ".agentic/config.yaml").exists():
+        return None
+    try:
+        return load_workspace(project_root, suppress_legacy_profile_warning=True)
+    except RuntimeError as exc:
+        return ValueError(str(exc))
+
+
+def build_check_context(project_root: Path) -> CheckContext:
+    project_root = project_root.resolve()
+    workspace = _load_manifest_workspace_for_checks(project_root)
+    if isinstance(workspace, ValueError):
+        return CheckContext(
+            root=project_root.as_posix(),
+            mode="invalid_manifest",
+            external_manifest_workspace=False,
+            gate_family="invalid_manifest",
+            gate_documents=(),
+            check_renders_statuses=False,
+            skip_status_renderer="agentic-kit doctor",
+            invalid_manifest_error=str(workspace),
+        )
+    if workspace is not None:
+        return CheckContext(
+            root=project_root.as_posix(),
+            mode="external_manifest_workspace",
+            external_manifest_workspace=True,
+            gate_family="workspace_state",
+            gate_documents=WORKSPACE_STATE_GATE_DOCUMENTS,
+            check_renders_statuses=False,
+            skip_status_renderer="agentic-kit doctor",
+        )
+    mode = (
+        "selfhosting_checkout"
+        if _is_agentic_project_kit_development_checkout(project_root)
+        else "repository_state"
+    )
+    return CheckContext(
+        root=project_root.as_posix(),
+        mode=mode,
+        external_manifest_workspace=False,
+        gate_family="repository_state",
+        gate_documents=STATE_GATE_DOCUMENTS,
+        check_renders_statuses=False,
+        skip_status_renderer="agentic-kit doctor",
+    )
+
+
+def _is_agentic_project_kit_development_checkout(project_root: Path) -> bool:
+    return (
+        (project_root / "src" / "agentic_project_kit").is_dir()
+        and (project_root / "docs" / "reference" / "agentic-kit-commands.json").exists()
+        and (project_root / "pyproject.toml").exists()
+    )
+
+
+def check_document_quality(relative_path: str, content: str) -> list[str]:
+    """Return deterministic document-quality findings.
+
+    These checks intentionally cover only machine-checkable quality signals.
+    They are not a claim of semantic perfection.
+    """
+    errors: list[str] = []
+    for marker, pattern in QUALITY_PLACEHOLDER_PATTERNS.items():
+        if pattern.search(content):
+            errors.append(f"{relative_path}: unresolved placeholder marker {marker!r}")
+    return errors
+
+
+def _release_version_tuple(version: str) -> tuple[int, int, int]:
+    major, minor, patch = version.split(".")
+    return int(major), int(minor), int(patch)
+
+
+def _release_sections(content: str) -> list[tuple[str, str | None, str]]:
+    matches = list(CHANGELOG_RELEASE_HEADING.finditer(content))
+    sections: list[tuple[str, str | None, str]] = []
+    for index, match in enumerate(matches):
+        start = match.end()
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(content)
+        sections.append((match.group("version"), match.group("date"), content[start:end].strip()))
+    return sections
+
+
+def _substance_categories(section_text: str) -> set[str]:
+    normalized = section_text.lower()
+    return {
+        category
+        for category, terms in CHANGELOG_SUBSTANCE_CATEGORIES.items()
+        if any(term in normalized for term in terms)
+    }
+
+
+def _substantive_changelog_bullets(section_text: str) -> list[str]:
+    bullets = [line.strip() for line in section_text.splitlines() if line.strip().startswith("- ")]
+    return [
+        bullet
+        for bullet in bullets
+        if not any(pattern.match(bullet) for pattern in CHANGELOG_GENERIC_BULLET_PATTERNS)
+    ]
+
+
+def check_changelog_quality(project_root: Path) -> list[str]:
+    """Check recent release-history quality without pretending to judge prose quality.
+
+    The guard is intentionally structural and category-based. It prevents recent
+    release entries from collapsing into generic metadata-only bullets, but it does
+    not require a naive minimum bullet count and does not rewrite historical evidence.
+    """
+    path = project_root / "CHANGELOG.md"
+    if not path.exists():
+        return []
+
+    content = path.read_text(encoding="utf-8")
+    errors: list[str] = []
+    seen_versions: set[str] = set()
+
+    for version, date, body in _release_sections(content):
+        if version in seen_versions:
+            errors.append(f"CHANGELOG.md: duplicate release section v{version}")
+        seen_versions.add(version)
+
+        if _release_version_tuple(version) < CHANGELOG_QUALITY_MIN_VERSION:
+            continue
+
+        section_text = f"v{version}\n{body}"
+        normalized = section_text.lower()
+        if date is None:
+            errors.append(f"CHANGELOG.md: v{version} missing release date in heading")
+
+        has_zenodo_state = "zenodo" in normalized and ("doi" in normalized or "pending" in normalized)
+        if not has_zenodo_state:
+            errors.append(f"CHANGELOG.md: v{version} missing Zenodo DOI or pending verification marker")
+
+        if not _substantive_changelog_bullets(body):
+            errors.append(f"CHANGELOG.md: v{version} has no substantive release bullet beyond generic metadata")
+
+        categories = _substance_categories(section_text)
+        if len(categories) < 3:
+            found = ", ".join(sorted(categories)) or "none"
+            errors.append(f"CHANGELOG.md: v{version} lacks enough release-quality categories (found: {found})")
+
+    return errors
+
+
+def check_state_gate_docs(project_root: Path) -> list[str]:
+    errors: list[str] = []
+
+    for relative_path in STATE_GATE_DOCUMENTS:
+        path = project_root / relative_path
+        if not path.exists():
+            errors.append(f"Missing state gate document: {relative_path}")
+            continue
+
+        content = path.read_text(encoding="utf-8")
+        for section in STATE_GATE_SECTIONS.get(relative_path, ()):  # defensive for future docs
+            if section not in content:
+                errors.append(f"{relative_path}: missing state gate section {section!r}")
+
+    handoff_path = project_root / "docs/handoff/CURRENT_HANDOFF.md"
+    if handoff_path.exists():
+        handoff = handoff_path.read_text(encoding="utf-8")
+        for marker in STALE_HANDOFF_MARKERS:
+            if marker in handoff:
+                errors.append(f"docs/handoff/CURRENT_HANDOFF.md: stale handoff marker {marker!r}")
+
+    return errors
+
+
+def check_workspace_state_gate_docs(project_root: Path) -> list[str]:
+    errors: list[str] = []
+
+    for relative_path in WORKSPACE_STATE_GATE_DOCUMENTS:
+        path = project_root / relative_path
+        if not path.exists():
+            errors.append(f"Missing workspace state document: {relative_path}")
+            continue
+
+        content = path.read_text(encoding="utf-8")
+        for section in WORKSPACE_STATE_GATE_SECTIONS.get(relative_path, ()):
+            if section not in content:
+                errors.append(f"{relative_path}: missing workspace state section {section!r}")
+
+    return errors
+
+
+def check_documentation_coverage(project_root: Path) -> list[str]:
+    matrix_path = project_root / "docs/DOCUMENTATION_COVERAGE.yaml"
+    if not matrix_path.exists():
+        return ["Missing state gate document: docs/DOCUMENTATION_COVERAGE.yaml"]
+
+    try:
+        matrix = load_yaml(matrix_path)
+    except (FileNotFoundError, ValueError, yaml.YAMLError) as exc:
+        return [f"docs/DOCUMENTATION_COVERAGE.yaml: invalid coverage matrix ({exc})"]
+
+    errors: list[str] = []
+    rules = matrix.get("rules", [])
+    if not isinstance(rules, list) or not rules:
+        return ["docs/DOCUMENTATION_COVERAGE.yaml: rules must be a non-empty list"]
+
+    for rule_index, rule in enumerate(rules, start=1):
+        if not isinstance(rule, dict):
+            errors.append(f"docs/DOCUMENTATION_COVERAGE.yaml: rule {rule_index} must be a mapping")
+            continue
+        rule_id = str(rule.get("id") or f"rule-{rule_index}")
+        documents = rule.get("documents", [])
+        if not isinstance(documents, list) or not documents:
+            errors.append(f"docs/DOCUMENTATION_COVERAGE.yaml: {rule_id} documents must be a non-empty list")
+            continue
+
+        for doc_index, doc in enumerate(documents, start=1):
+            if not isinstance(doc, dict):
+                errors.append(f"docs/DOCUMENTATION_COVERAGE.yaml: {rule_id} document {doc_index} must be a mapping")
+                continue
+            relative_path = str(doc.get("path") or "").strip()
+            if not relative_path:
+                errors.append(f"docs/DOCUMENTATION_COVERAGE.yaml: {rule_id} document {doc_index} missing path")
+                continue
+            path = project_root / relative_path
+            if not path.exists():
+                errors.append(f"documentation coverage {rule_id}: missing document {relative_path}")
+                continue
+
+            terms = doc.get("terms", [])
+            if not isinstance(terms, list) or not terms:
+                errors.append(f"docs/DOCUMENTATION_COVERAGE.yaml: {rule_id} {relative_path} terms must be a non-empty list")
+                continue
+
+            content = path.read_text(encoding="utf-8")
+            for term in terms:
+                needle = str(term)
+                if needle not in content:
+                    errors.append(f"documentation coverage {rule_id}: {relative_path} missing term {needle!r}")
+
+    return errors
+
+
+def check_todo(project_root: Path) -> list[str]:
+    workspace = _load_manifest_workspace_for_checks(project_root)
+    if isinstance(workspace, ValueError) and not (project_root / "sentinel.yaml").exists():
+        return [f"Invalid workspace manifest: {workspace}"]
+    if workspace is not None and not (project_root / "sentinel.yaml").exists():
+        return []
+    config = load_yaml(project_root / "sentinel.yaml")
+    todo_path = project_root / config.get("todo", {}).get("path", ".agentic/todo.yaml")
+    data = load_yaml(todo_path)
+    errors: list[str] = []
+
+    items = data.get("items", [])
+    if not isinstance(items, list):
+        return [f"{todo_path}: items must be a list"]
+
+    required = ["id", "title", "owner", "priority", "status", "evidence_required"]
+    seen_ids: set[str] = set()
+
+    for index, item in enumerate(items, start=1):
+        if not isinstance(item, dict):
+            errors.append(f"{todo_path}: item {index} must be a mapping")
+            continue
+
+        item_id = str(item.get("id", "")).strip()
+        if not item_id:
+            errors.append(f"{todo_path}: item {index} has no id")
+        elif item_id in seen_ids:
+            errors.append(f"{todo_path}: duplicate id {item_id}")
+        else:
+            seen_ids.add(item_id)
+
+        for field in required:
+            if not str(item.get(field, "")).strip():
+                errors.append(f"{todo_path}: {item_id or index} missing {field}")
+
+        if str(item.get("status", "")).strip() not in {"open", "done", "blocked"}:
+            errors.append(f"{todo_path}: {item_id or index} has invalid status")
+
+    return errors
+
+
+def check_all(project_root: Path) -> list[str]:
+    errors: list[str] = []
+    errors.extend(check_docs(project_root))
+    errors.extend(check_todo(project_root))
+    return errors