marvisx-cli 0.1.0__py3-none-any.whl

core/api/services/docs_governance/config.py

@@ -0,0 +1,87 @@
+"""Governance configuration loader for MarvisX docs."""
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from core.api.paths import repo_path
+
+DEFAULT_CONFIG_PATH = repo_path(__file__, "docs", ".governance.yml")
+
+ALLOWED_LAYERS = frozenset(
+    {
+        "api",
+        "mcp",
+        "llm-gateway",
+        "kg",
+        "code-examples",
+        "narrative",
+        "concept",
+    }
+)
+
+
+class GovernanceConfigError(ValueError):
+    """Raised when docs governance config is missing or malformed."""
+
+
+@lru_cache(maxsize=8)
+def load_governance_config(path: str | Path | None = None) -> dict[str, Any]:
+    """Load the single root governance config and validate its shape."""
+    config_path = Path(path) if path else DEFAULT_CONFIG_PATH
+    try:
+        raw = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    except FileNotFoundError as exc:
+        raise GovernanceConfigError(f"governance config not found: {config_path}") from exc
+    except yaml.YAMLError as exc:
+        raise GovernanceConfigError(f"governance config YAML error: {exc}") from exc
+
+    if not isinstance(raw, dict):
+        raise GovernanceConfigError("governance config must be a YAML mapping")
+
+    layers = raw.get("layers")
+    if not isinstance(layers, dict) or not layers:
+        raise GovernanceConfigError("governance config must define non-empty layers map")
+    if "auto_merge_on" in raw:
+        raise GovernanceConfigError("auto_merge_on is not supported; use auto_pr_label_on")
+
+    unknown = sorted(set(layers) - ALLOWED_LAYERS)
+    if unknown:
+        raise GovernanceConfigError(f"unknown governance layer(s): {unknown}")
+
+    for layer, layer_config in layers.items():
+        if not isinstance(layer_config, dict):
+            raise GovernanceConfigError(f"layer {layer!r} config must be a mapping")
+        if "auto_merge_on" in layer_config:
+            raise GovernanceConfigError(f"layer {layer!r} uses removed auto_merge_on key")
+        threshold = layer_config.get("threshold", raw.get("default_threshold", 1.0))
+        try:
+            threshold_value = float(threshold)
+        except (TypeError, ValueError) as exc:
+            raise GovernanceConfigError(f"layer {layer!r} threshold must be numeric") from exc
+        if threshold_value < 0.0 or threshold_value > 1.0:
+            raise GovernanceConfigError(f"layer {layer!r} threshold must be between 0 and 1")
+        if threshold_value != 1.0:
+            raise GovernanceConfigError(f"layer {layer!r} threshold must be 1.0")
+
+    return raw
+
+
+def layer_config(layer: str, config: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Return merged defaults for one layer."""
+    active = config or load_governance_config()
+    layers = active.get("layers") or {}
+    if layer not in layers:
+        raise GovernanceConfigError(f"unknown governance layer: {layer}")
+    merged = {
+        "threshold": active.get("default_threshold", 1.0),
+        "suggest_label_min_score": active.get("suggest_label_min_score", 0.85),
+        "hard_gates": [],
+        "auto_pr_label_on": active.get("auto_pr_label_on", {}),
+        "human_required_on": ["any"],
+    }
+    merged.update(layers[layer])
+    return merged

core/api/services/docs_governance/enrichment.py

@@ -0,0 +1,65 @@
+"""Markdown enrichment for human docs governance review."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from core.api.services.docs_governance.confidence import DocsTriageDecision
+
+DEFAULT_TEMPLATE = """# Docs Governance Review: {layer}
+
+Score: {score}
+PR label: {pr_label}
+Reason: {label_reason}
+
+## Signals
+
+- Syntax validity: {syntax_validity}
+- KG consistency: {kg_consistency}
+- LLM confidence: {llm_confidence}
+- Penalties: {penalties}
+
+## Risk
+
+{risk_summary}
+
+## Evidence
+
+{evidence}
+"""
+
+
+def build_enrichment_markdown(
+    *,
+    decision: DocsTriageDecision,
+    evidence: Mapping[str, Any] | None = None,
+    template_path: str | Path | None = None,
+) -> str:
+    """Render a compact human-review note for PR comments."""
+    evidence = evidence or {}
+    template = DEFAULT_TEMPLATE
+    if template_path:
+        path = Path(template_path)
+        if path.exists():
+            template = path.read_text(encoding="utf-8")
+
+    return template.format(
+        layer=decision.layer,
+        score=f"{decision.score:.2f}",
+        pr_label=decision.pr_label,
+        label_reason=decision.label_reason,
+        syntax_validity=f"{decision.syntax_validity:.2f}",
+        kg_consistency=f"{decision.kg_consistency:.2f}",
+        llm_confidence=f"{decision.llm_confidence:.2f}",
+        penalties=", ".join(decision.penalties) or "none",
+        risk_summary=str(evidence.get("risk_summary") or "No extra risk summary provided."),
+        evidence=_format_evidence(evidence),
+    ).rstrip() + "\n"
+
+
+def _format_evidence(evidence: Mapping[str, Any]) -> str:
+    lines: list[str] = []
+    for key in ("test_results", "caller_graph", "kg_context", "links"):
+        if key in evidence:
+            lines.append(f"- {key}: {evidence[key]}")
+    return "\n".join(lines) if lines else "No evidence attached."

core/api/services/docs_governance/frontmatter_validator.py

@@ -0,0 +1,83 @@
+"""Validate docs MDX frontmatter used by KG coverage tracking."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from core.scripts._frontmatter import parse_frontmatter
+
+AUDIENCES = frozenset({"integrator", "agent", "operator", "internal"})
+VISIBILITIES = frozenset({"external", "internal", "draft"})
+LAYERS = frozenset(
+    {"api", "mcp", "llm-gateway", "kg", "narrative", "concept", "code-examples"}
+)
+NODE_LAYERS_REQUIRING_DOCUMENTS = frozenset({"api", "mcp", "kg"})
+
+
+@dataclass(frozen=True)
+class FrontmatterValidation:
+    valid: bool
+    errors: list[str] = field(default_factory=list)
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+
+
+def validate_docs_frontmatter(path: str | Path) -> FrontmatterValidation:
+    """Validate one MDX/Markdown docs page.
+
+    `documents_nodes` is deliberately opt-in for narrative/concept layers, but
+    required for API/MCP/KG pages where coverage can be machine-derived.
+    """
+    data, _body = parse_frontmatter(path)
+    errors: list[str] = []
+    if data is None:
+        return FrontmatterValidation(False, ["missing_or_invalid_frontmatter"], {})
+
+    for required in ("title", "audience", "visibility", "layer"):
+        if required not in data:
+            errors.append(f"missing_{required}")
+
+    layer = str(data.get("layer") or "")
+    if layer and layer not in LAYERS:
+        errors.append(f"invalid_layer:{layer}")
+
+    visibility = str(data.get("visibility") or "")
+    if visibility and visibility not in VISIBILITIES:
+        errors.append(f"invalid_visibility:{visibility}")
+
+    audience = data.get("audience")
+    if not isinstance(audience, list) or not audience:
+        errors.append("audience_must_be_non_empty_list")
+    else:
+        invalid_audience = sorted(str(item) for item in audience if str(item) not in AUDIENCES)
+        if invalid_audience:
+            errors.append(f"invalid_audience:{','.join(invalid_audience)}")
+
+    documents_nodes = data.get("documents_nodes")
+    if documents_nodes is None:
+        if layer in NODE_LAYERS_REQUIRING_DOCUMENTS:
+            errors.append("missing_documents_nodes")
+    elif not isinstance(documents_nodes, list):
+        errors.append("documents_nodes_must_be_list")
+    else:
+        for node_id in documents_nodes:
+            if not isinstance(node_id, str) or node_id.count(":") < 2:
+                errors.append(f"invalid_documents_node:{node_id!r}")
+
+    return FrontmatterValidation(not errors, errors, data)
+
+
+def validate_docs_tree(root: str | Path) -> list[dict[str, Any]]:
+    """Validate all docs content pages under a root directory."""
+    root_path = Path(root)
+    results: list[dict[str, Any]] = []
+    for path in sorted([*root_path.rglob("*.md"), *root_path.rglob("*.mdx")]):
+        validation = validate_docs_frontmatter(path)
+        results.append(
+            {
+                "path": str(path),
+                "valid": validation.valid,
+                "errors": validation.errors,
+            }
+        )
+    return results

core/api/services/docs_governance/hard_gates.py

@@ -0,0 +1,221 @@
+"""Deterministic docs governance hard gates.
+
+These gates are opt-in per layer through `docs/.governance.yml`. Missing tools
+or unknown gate names fail the gate explicitly instead of silently approving.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+from core.api.services.docs_governance.config import layer_config, load_governance_config
+from core.api.services.docs_governance.frontmatter_validator import validate_docs_frontmatter
+
+
+@dataclass(frozen=True)
+class GateResult:
+    name: str
+    passed: bool
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class GateReport:
+    passed: bool
+    results: list[GateResult] = field(default_factory=list)
+
+    @property
+    def failed(self) -> list[GateResult]:
+        return [result for result in self.results if not result.passed]
+
+
+_INTERNAL_URL_PATTERN = r"https?://(?:100\.\d+\.\d+\.\d+|localhost|127\.0\.0\.1)(?::\d+)?"
+_PERSONAL_DOMAIN_PATTERN = os.environ.get(
+    "DOCS_GATE_PERSONAL_DOMAIN_REGEX", r"\bllm\.example\.invalid\b"
+)
+_INTERNAL_PATH_PATTERN = r"(?:/data/projects/|/home/[^/]+/|/data/pir/)"
+_INTERNAL_CODENAME_PATTERN = (
+    r"\b(marvis-brain|marvisx-core|wedge\s+W\d+|criterion\s+§\d+|R\d{2,})\b"
+)
+_AGENT_TRANSPARENCY_PATTERN = r"\b(subagent|\d+/\d+\s+agent|multi-agent\s+transparency)\b"
+_BARE_TAILSCALE_PATTERN = r"\b100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.\d+\.\d+\b"
+
+SECURITY_LEAK_PATTERN_SOURCES: tuple[tuple[str, str, int], ...] = (
+    ("internal_url", _INTERNAL_URL_PATTERN, 0),
+    ("personal_gateway_domain", _PERSONAL_DOMAIN_PATTERN, re.IGNORECASE),
+    ("internal_path", _INTERNAL_PATH_PATTERN, 0),
+    ("internal_codename", _INTERNAL_CODENAME_PATTERN, re.IGNORECASE),
+    ("agent_transparency", _AGENT_TRANSPARENCY_PATTERN, re.IGNORECASE),
+    ("bare_tailscale_ip", _BARE_TAILSCALE_PATTERN, 0),
+)
+SECURITY_LEAK_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = tuple(
+    (name, re.compile(pattern, flags)) for name, pattern, flags in SECURITY_LEAK_PATTERN_SOURCES
+)
+SECURITY_LEAK_GREP_PATTERN = "|".join(
+    f"(?:{pattern})" for _name, pattern, _flags in SECURITY_LEAK_PATTERN_SOURCES
+)
+
+
+def check_frontmatter_valid(path: str | Path) -> GateResult:
+    validation = validate_docs_frontmatter(path)
+    return GateResult(
+        "frontmatter_valid",
+        validation.valid,
+        ",".join(validation.errors),
+    )
+
+
+def check_no_security_leaks(text: str) -> GateResult:
+    """Block internal endpoints, paths, codenames, and implementation traces."""
+    matches = [
+        name
+        for name, pattern in SECURITY_LEAK_PATTERNS
+        if pattern.search(text)
+    ]
+    return GateResult("no_security_leaks", not matches, ",".join(matches))
+
+
+def check_schema_valid(payload: Mapping[str, Any]) -> GateResult:
+    """Validate minimal schema-ish payloads from generated references."""
+    ok = bool(payload) and not payload.get("errors")
+    return GateResult("schema_valid", ok, str(payload.get("errors") or ""))
+
+
+def check_no_breaking_removal(change_type: str) -> GateResult:
+    return GateResult(
+        "no_breaking_removal",
+        change_type not in {"breaking_removal", "signature_change", "tool_removed"},
+        change_type,
+    )
+
+
+def check_doc_detective_green(result: Mapping[str, Any]) -> GateResult:
+    status = str(result.get("status") or "").upper()
+    return GateResult("doc_detective_green", status == "PASS", status or "missing")
+
+
+def check_vale_pass(result: Mapping[str, Any]) -> GateResult:
+    errors = int(result.get("errors") or 0)
+    return GateResult("vale_pass", errors == 0, f"errors={errors}")
+
+
+def check_lychee_pass(result: Mapping[str, Any]) -> GateResult:
+    failures = int(result.get("failures") or result.get("failed") or 0)
+    return GateResult("lychee_pass", failures == 0, f"failures={failures}")
+
+
+def check_kg_xref_valid(xrefs: Iterable[str], known_nodes: set[str]) -> GateResult:
+    missing = sorted(str(node_id) for node_id in xrefs if str(node_id) not in known_nodes)
+    return GateResult("kg_xref_valid", not missing, ",".join(missing[:10]))
+
+
+def check_adr_consistency(result: Mapping[str, Any]) -> GateResult:
+    conflicts = result.get("conflicts") or []
+    return GateResult("adr_consistency", not conflicts, json.dumps(conflicts[:5]))
+
+
+def check_coverage_no_regression(
+    *,
+    removed_nodes: Iterable[str],
+    replacement_nodes: Iterable[str],
+    baseline_documented_nodes: set[str],
+) -> GateResult:
+    """Fail if a PR removes the only documented coverage for a baseline node."""
+    replacements = set(replacement_nodes)
+    regressions = sorted(
+        str(node_id)
+        for node_id in removed_nodes
+        if str(node_id) in baseline_documented_nodes and str(node_id) not in replacements
+    )
+    return GateResult(
+        "documented_coverage_no_regression",
+        not regressions,
+        ",".join(regressions[:10]),
+    )
+
+
+def check_no_undocumented_new_function(
+    *,
+    new_function_qualified_names: set[str],
+    documented_qualified_names: set[str],
+) -> GateResult:
+    """Fail if a newly added public function has no docs frontmatter claim."""
+    missing = sorted(new_function_qualified_names - documented_qualified_names)
+    return GateResult(
+        "no_undocumented_new_function",
+        not missing,
+        ",".join(missing[:10]),
+    )
+
+
+def run_configured_hard_gates(
+    *,
+    layer: str,
+    context: Mapping[str, Any],
+    config_path: str | Path | None = None,
+) -> GateReport:
+    """Run only gates configured for a layer.
+
+    Context keys intentionally mirror CI output names so callers can wire this
+    without creating a synthetic object graph.
+    """
+    config = load_governance_config(config_path)
+    gates = layer_config(layer, config).get("hard_gates") or []
+    results: list[GateResult] = []
+    text = str(context.get("text") or "")
+
+    for gate in gates:
+        if gate == "frontmatter_valid":
+            path = context.get("path")
+            if path:
+                results.append(check_frontmatter_valid(path))
+            else:
+                results.append(GateResult("frontmatter_valid", False, "missing_path"))
+        elif gate == "no_security_leaks":
+            results.append(check_no_security_leaks(text))
+        elif gate == "schema_valid":
+            results.append(check_schema_valid(context.get("schema") or {}))
+        elif gate == "no_breaking_removal":
+            results.append(check_no_breaking_removal(str(context.get("change_type") or "")))
+        elif gate == "doc_detective_green":
+            results.append(check_doc_detective_green(context.get("doc_detective") or {}))
+        elif gate == "vale_pass":
+            results.append(check_vale_pass(context.get("vale") or {}))
+        elif gate == "lychee_pass":
+            results.append(check_lychee_pass(context.get("lychee") or {}))
+        elif gate == "kg_xref_valid":
+            results.append(
+                check_kg_xref_valid(
+                    context.get("xrefs") or [],
+                    set(context.get("known_nodes") or []),
+                )
+            )
+        elif gate == "adr_consistency":
+            results.append(check_adr_consistency(context.get("adr") or {}))
+        elif gate == "documented_coverage_no_regression":
+            results.append(
+                check_coverage_no_regression(
+                    removed_nodes=context.get("removed_nodes") or [],
+                    replacement_nodes=context.get("replacement_nodes") or [],
+                    baseline_documented_nodes=set(context.get("baseline_documented_nodes") or []),
+                )
+            )
+        elif gate == "no_undocumented_new_function":
+            results.append(
+                check_no_undocumented_new_function(
+                    new_function_qualified_names=set(
+                        context.get("new_function_qualified_names") or []
+                    ),
+                    documented_qualified_names=set(
+                        context.get("documented_qualified_names") or []
+                    ),
+                )
+            )
+        else:
+            results.append(GateResult(str(gate), False, "unknown_gate"))
+
+    return GateReport(all(result.passed for result in results), results)

core/api/services/docs_governance/triage_orchestrator.py

@@ -0,0 +1,98 @@
+"""Slim docs governance orchestrator.
+
+Plan 0 deliberately uses a small deterministic orchestration layer. The P0
+review deferred LangGraph until the docs pipeline needs multiple conditional
+LLM nodes; for now this function is the durable decision boundary.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Mapping
+
+from core.api.services.docs_governance.confidence import (
+    compute_docs_confidence,
+    estimate_syntax_validity,
+)
+from core.api.services.docs_governance.config import layer_config, load_governance_config
+from core.api.services.docs_governance.enrichment import build_enrichment_markdown
+from core.api.services.docs_governance.hard_gates import run_configured_hard_gates
+
+
+@dataclass(frozen=True)
+class DocsGovernanceTriage:
+    decision: str
+    layer: str
+    score: float
+    pr_label: str
+    opens_pr_draft: bool
+    confidence: dict[str, Any]
+    hard_gates: list[dict[str, Any]]
+    enrichment_markdown: str
+
+    def as_json(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+async def triage_docs_change(
+    *,
+    layer: str,
+    change_type: str,
+    diff_text: str,
+    context: Mapping[str, Any],
+    llm_confidence: float = 0.0,
+    kg_consistency: float = 1.0,
+    kg_stale: bool = False,
+    corpus_state: str = "ready",
+    config_path: str | None = None,
+) -> DocsGovernanceTriage:
+    """Run configured deterministic gates and compute a PR draft label.
+
+    This function never merges. Callers use the result to open a draft PR for
+    Console Triage and attach `pr_label` as the governance suggestion.
+    """
+    gate_report = run_configured_hard_gates(
+        layer=layer,
+        context=context,
+        config_path=config_path,
+    )
+    cfg = layer_config(layer, load_governance_config(config_path))
+    syntax = estimate_syntax_validity(
+        frontmatter_valid=not any(result.name == "frontmatter_valid" and not result.passed for result in gate_report.results),
+        vale_errors=int((context.get("vale") or {}).get("errors") or 0),
+        link_failures=int((context.get("lychee") or {}).get("failures") or 0),
+        doc_detective_status=(context.get("doc_detective") or {}).get("status"),
+    )
+    confidence = compute_docs_confidence(
+        layer=layer,
+        change_type=change_type,
+        diff_text=diff_text,
+        syntax_validity=syntax,
+        kg_consistency=kg_consistency,
+        llm_confidence=llm_confidence,
+        suggest_label_min_score=float(cfg.get("suggest_label_min_score") or 0.85),
+        kg_stale=kg_stale,
+        corpus_state=corpus_state,
+        hard_gate_failures=[result.name for result in gate_report.failed],
+        pr_labels=cfg.get("auto_pr_label_on") or {},
+        human_required_change_types=set(cfg.get("human_required_on") or []),
+    )
+    enrichment = build_enrichment_markdown(
+        decision=confidence,
+        evidence={
+            "risk_summary": "Deterministic docs governance triage.",
+            "test_results": context.get("test_results", "not attached"),
+            "caller_graph": context.get("caller_graph", "not attached"),
+            "kg_context": context.get("kg_context", "not attached"),
+        },
+    )
+
+    return DocsGovernanceTriage(
+        decision="draft_pr",
+        layer=layer,
+        score=confidence.score,
+        pr_label=confidence.pr_label,
+        opens_pr_draft=True,
+        confidence=confidence.as_json(),
+        hard_gates=[asdict(result) for result in gate_report.results],
+        enrichment_markdown=enrichment,
+    )