core-runtime 0.1.1__py3-none-any.whl

cli/commands/audit_reporter.py

@@ -0,0 +1,272 @@
+# src/cli/commands/audit_reporter.py
+
+"""
+AuditRunReporter: structured reporting for `core-admin check audit`.
+
+Responsibilities:
+- Print a clear run header
+- Record and display phases (e.g. knowledge graph build)
+- Record and display per-check results in a table
+- Print a summary with key offenders and suggested fix commands
+- Emit structured activity events via ActivityRun/log_activity
+"""
+
+from __future__ import annotations
+
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from mind.governance.audit_types import AuditCheckResult
+from shared.activity_logging import ActivityRun, log_activity
+from shared.models import AuditSeverity
+
+
+# Use Console for user-facing report output (CLI Exemption)
+console = Console()
+
+
+@dataclass
+# ID: 130b3778-81fa-4f45-b08a-ec7be01cb664
+class AuditPhase:
+    """Represents a phase of an audit process.
+
+    Stores metadata about each stage, such as its name and duration,
+    along with optional detailed information if applicable.
+
+    Args:
+        name: The human-readable name for this audit phase.
+        duration_sec: The time taken to complete this phase in seconds (optional).
+        details: Additional context or findings related to this phase (optional).
+
+    Returns:
+        None
+
+    Raises:
+        None"""
+
+    name: str
+    duration_sec: float | None = None
+    details: dict | None = None
+
+
+@dataclass
+# ID: 7e587f02-70d1-413b-8d32-884614e42670
+class AuditRunReporter:
+    """
+    Coordinates user-facing reporting for a single audit run.
+
+    Typical usage (inside the audit runner):
+
+        reporter = AuditRunReporter(run, repo_path=..., total_checks=len(checks))
+        reporter.print_header()
+
+        # Phase 1: knowledge graph
+        reporter.record_phase("Knowledge graph", duration_sec=2.65, details={"symbols": 1464})
+
+        # For each check:
+        result = AuditCheckResult.from_raw(check_cls, findings, duration_sec)
+        reporter.record_check_result(result)
+
+        # Finally:
+        reporter.print_phases()
+        reporter.print_checks_table()
+        reporter.print_summary()
+    """
+
+    run: ActivityRun
+    repo_path: str
+    total_checks: int
+    phases: list[AuditPhase] = field(default_factory=list)
+    check_results: list[AuditCheckResult] = field(default_factory=list)
+
+    # ID: c3b86fe8-f82a-4af4-be0b-0aef027dcaf2
+    def print_header(self) -> None:
+        """Prints a header for the CORE audit run, indicating the workflow, repository path, and run ID.
+
+        Args:
+            None
+
+        Returns:
+            None
+
+        Raises:
+            None"""
+        console.rule("[bold]CORE Audit Run[/bold]")
+        logger.info("Workflow : check.audit")
+        logger.info("Repo     : %s", self.repo_path)
+        logger.info("Run ID   : %s", self.run.run_id)
+        logger.info("-")
+
+    # ---------- Phases ----------
+
+    # ID: 29238d29-d5d9-4518-b392-28b7651290df
+    def record_phase(
+        self,
+        name: str,
+        duration_sec: float | None = None,
+        details: dict | None = None,
+    ) -> None:
+        """Record a high-level audit phase (e.g. knowledge graph build)."""
+        self.phases.append(
+            AuditPhase(name=name, duration_sec=duration_sec, details=details)
+        )
+
+    # ID: ca1e280d-f07d-493c-a43d-57f0271c02b2
+    def print_phases(self) -> None:
+        """Render recorded phases to the console."""
+        if not self.phases:
+            return
+
+        for phase in self.phases:
+            logger.info("[Phase] %s", phase.name)
+            if phase.details:
+                for key, value in phase.details.items():
+                    logger.info("  • %s: %s", key, value)
+            if phase.duration_sec is not None:
+                logger.info("  • Duration: %.2fs", phase.duration_sec)
+            logger.info("")  # FIXED: Empty string for blank line
+
+    # ---------- Checks ----------
+
+    # ID: 93d0968b-c2b9-4deb-a3ad-d6925bf49e33
+    def record_check_result(
+        self,
+        result: AuditCheckResult,
+        check_cls: type | None = None,
+    ) -> None:
+        """
+        Record a normalized check result and emit a structured activity event.
+
+        If check_cls is provided, the event name will include the class name.
+        """
+        self.check_results.append(result)
+
+        event_name = "check"
+        if check_cls is not None:
+            event_name = f"check:{check_cls.__name__}"
+
+        status = "ok" if result.findings_count == 0 else "warning"
+
+        log_activity(
+            self.run,
+            event=event_name,
+            status=status,
+            message=(
+                f"Check {result.name} completed with "
+                f"{result.findings_count} findings in {result.duration_sec:.2f}s"
+            ),
+            details={
+                "check_name": result.name,
+                "category": result.category,
+                "duration_sec": result.duration_sec,
+                "findings_count": result.findings_count,
+                "max_severity": (
+                    result.max_severity.name if result.max_severity else None
+                ),
+            },
+        )
+
+    # ID: de543ad4-2e18-431f-9730-2af1917e753c
+    def print_checks_table(self) -> None:
+        """Render a table of all check results."""
+        if not self.check_results:
+            logger.info("No checks recorded.")
+            return
+
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("CHECK", style="bold", min_width=26)
+        table.add_column("CATEGORY", min_width=10)
+        table.add_column("TIME", justify="right")
+        table.add_column("FINDINGS", justify="right")
+        table.add_column("STATUS", min_width=10)
+
+        for result in self.check_results:
+            if result.findings_count == 0:
+                status_text = Text("OK")
+            else:
+                status_text = Text("WARN")
+                status_text.stylize("yellow")
+
+            table.add_row(
+                result.name,
+                result.category or "-",
+                f"{result.duration_sec:.2f}s",
+                str(result.findings_count),
+                status_text,
+            )
+
+        console.print(
+            f"[bold][Phase][/bold] Running checks ({self.total_checks} total)"
+        )
+        console.print(table)
+        logger.info("")  # FIXED: Empty string for blank line
+
+    # ---------- Summary ----------
+
+    # ID: f8c33425-418f-40e2-b059-811098ae0c1c
+    def print_summary(self) -> None:
+        """Render a summary block with counts and suggested next steps."""
+        if not self.check_results:
+            logger.info("Summary")
+            logger.info("  No checks were executed.")
+            console.rule()
+            return
+
+        total = len(self.check_results)
+        with_issues = [r for r in self.check_results if r.has_issues]
+        findings_total = sum(r.findings_count for r in self.check_results)
+
+        # Determine highest severity present (if any)
+        severities: list[AuditSeverity] = []
+        for r in self.check_results:
+            if r.max_severity is not None:
+                severities.append(r.max_severity)
+        highest_severity = max(severities) if severities else None
+
+        logger.info("[Summary]")
+        logger.info("  Total checks      : %s", total)
+        logger.info("  Checks with issues: %s", len(with_issues))
+        logger.info("  Total findings    : %s", findings_total)
+        if highest_severity:
+            logger.info("  Highest severity  : %s", highest_severity.name)
+        logger.info("")  # FIXED: Empty string for blank line
+
+        offenders = sorted(with_issues, key=lambda r: r.findings_count, reverse=True)[
+            :5
+        ]
+        if offenders:
+            logger.info("  Key offenders:")
+            for r in offenders:
+                logger.info("    - %s: %s findings", r.name, r.findings_count)
+            logger.info("")  # FIXED: Empty string for blank line
+
+        hints = _collect_fix_hints(offenders)
+        if hints:
+            logger.info("  Suggested next steps:")
+            for cmd in hints:
+                logger.info("    - Run: %s", cmd)
+            logger.info("")  # FIXED: Empty string for blank line
+
+        console.rule()
+
+
+def _collect_fix_hints(results: Iterable[AuditCheckResult]) -> list[str]:
+    """Return a de-duplicated list of fix hints from check results."""
+    seen: set[str] = set()
+    hints: list[str] = []
+
+    for r in results:
+        if r.fix_hint and r.fix_hint not in seen:
+            seen.add(r.fix_hint)
+            hints.append(r.fix_hint)
+
+    return hints

cli/commands/check/__init__.py

@@ -0,0 +1,115 @@
+# src/cli/commands/check/__init__.py
+"""
+Check command group - Constitutional compliance verification.
+
+This module orchestrates the registration of all read-only validation
+and health checks. It has been cleaned to remove transitional V1/V2
+hybrid audit commands.
+"""
+
+from __future__ import annotations
+
+import typer
+
+
+# Create the main command group
+check_app = typer.Typer(
+    help="Read-only validation and health checks.", no_args_is_help=True
+)
+
+
+def _register_rule_commands():
+    """Register specific rule-based audit commands."""
+    import cli.commands.check.rule as rule_module
+
+    for attr_name in dir(rule_module):
+        attr = getattr(rule_module, attr_name)
+        if callable(attr) and hasattr(attr, "__name__") and attr.__name__ == "rule_cmd":
+            check_app.command("rule")(attr)
+            break
+
+
+def _register_audit_commands():
+    """
+    Register core audit commands.
+
+    V2 ALIGNMENT: Removed 'audit-v2' and 'audit-hybrid' as the
+    primary 'audit' command is now fully unified.
+    """
+    import cli.commands.check.audit as audit_module
+
+    for attr_name in dir(audit_module):
+        attr = getattr(audit_module, attr_name)
+        if callable(attr) and hasattr(attr, "__name__"):
+            if attr.__name__ == "audit_cmd":
+                check_app.command("audit")(attr)
+                break
+
+
+def _register_quality_commands():
+    """Register general code quality and system health commands."""
+    import cli.commands.check.quality as quality_module
+
+    for attr_name in dir(quality_module):
+        attr = getattr(quality_module, attr_name)
+        if callable(attr) and hasattr(attr, "__name__"):
+            if attr.__name__ == "lint_cmd":
+                check_app.command("lint")(attr)
+            elif attr.__name__ == "tests_cmd":
+                check_app.command("tests")(attr)
+            elif attr.__name__ == "system_cmd":
+                check_app.command("system")(attr)
+
+
+def _register_diagnostic_commands():
+    """Register deep diagnostic and contract verification commands."""
+    import cli.commands.check.diagnostics_commands as diag_module
+
+    for attr_name in dir(diag_module):
+        attr = getattr(diag_module, attr_name)
+        if callable(attr) and hasattr(attr, "__name__"):
+            if attr.__name__ == "diagnostics_cmd":
+                check_app.command("diagnostics")(attr)
+            elif attr.__name__ == "check_body_ui_cmd":
+                check_app.command("body-ui")(attr)
+
+
+def _register_quality_gates_commands():
+    """Register automated industry-standard quality gates."""
+    import cli.commands.check.quality_gates as qg_module
+
+    for attr_name in dir(qg_module):
+        attr = getattr(qg_module, attr_name)
+        if (
+            callable(attr)
+            and hasattr(attr, "__name__")
+            and attr.__name__ == "quality_gates_cmd"
+        ):
+            check_app.command("quality-gates")(attr)
+            break
+
+
+def _register_imports_commands():
+    """Register import integrity check command."""
+    import cli.commands.check.imports as imports_module
+
+    for attr_name in dir(imports_module):
+        attr = getattr(imports_module, attr_name)
+        if (
+            callable(attr)
+            and hasattr(attr, "__name__")
+            and attr.__name__ == "imports_cmd"
+        ):
+            check_app.command("imports")(attr)
+            break
+
+
+# Trigger all registrations
+_register_audit_commands()
+_register_rule_commands()
+_register_quality_commands()
+_register_diagnostic_commands()
+_register_quality_gates_commands()
+_register_imports_commands()
+
+__all__ = ["check_app"]

cli/commands/check/audit.py

@@ -0,0 +1,130 @@
+# src/cli/commands/check/audit.py
+"""
+Core audit commands: audit.
+Refactored to use the canonical CoreContext provided by the framework.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from sqlalchemy import text
+
+from cli.commands.check.converters import parse_min_severity
+from cli.commands.check.formatters import print_summary_findings, print_verbose_findings
+from cli.utils import core_command
+from mind.governance.auditor import ConstitutionalAuditor
+from shared.infrastructure.database.session_manager import get_session
+from shared.logger import getLogger
+from shared.models import AuditFinding, AuditSeverity
+
+
+console = Console()
+logger = getLogger(__name__)
+
+
+def _to_audit_finding(raw: dict) -> AuditFinding:
+    severity_map = {str(s): s for s in AuditSeverity}
+    raw_severity = str(raw.get("severity", "info")).lower()
+    severity = severity_map.get(raw_severity, AuditSeverity.INFO)
+    return AuditFinding(
+        check_id=raw.get("check_id", "unknown"),
+        severity=severity,
+        message=raw.get("message", ""),
+        file_path=raw.get("file_path"),
+        line_number=raw.get("line_number"),
+        context=raw.get("context", {}),
+    )
+
+
+async def _persist_findings_to_db(findings: list[AuditFinding]) -> None:
+    """Persist audit findings to core.audit_findings (DB SSOT)."""
+    logger.info("_persist_findings_to_db called with %d findings.", len(findings))
+    if not findings:
+        logger.warning("No findings to persist — skipping.")
+        return
+    rows = [
+        {
+            "check_id": f.check_id,
+            "severity": (
+                f.severity.value if hasattr(f.severity, "value") else str(f.severity)
+            ),
+            "message": f.message,
+            "file_path": f.file_path,
+            "line_number": f.line_number,
+            "context": json.dumps(f.context) if f.context else None,
+        }
+        for f in findings
+    ]
+    logger.info("Persisting %d rows to core.audit_findings.", len(rows))
+    try:
+        async with get_session() as session:
+            await session.execute(text("TRUNCATE TABLE core.audit_findings"))
+            await session.execute(
+                text(
+                    "\n                    INSERT INTO core.audit_findings\n                        (check_id, severity, message, file_path, line_number, context)\n                    VALUES\n                        (:check_id, :severity, :message, :file_path,\n                         :line_number, cast(:context as jsonb))\n                    "
+                ),
+                rows,
+            )
+            await session.commit()
+        logger.info("Persisted %d findings to core.audit_findings.", len(rows))
+    except Exception as exc:
+        logger.error("Failed to persist findings to DB: %s", exc, exc_info=True)
+
+
+@core_command(dangerous=False)
+# ID: 1102d899-cc3e-4483-8d20-a4e520fa3c07
+async def audit_cmd(
+    ctx: typer.Context,
+    target: Path = typer.Argument(Path("src"), help="File or directory to audit."),
+    severity: str = typer.Option(
+        "high",
+        "--severity",
+        "-s",
+        help="Minimum severity level (info, low, medium, high, block).",
+        case_sensitive=False,
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Show individual findings."
+    ),
+) -> None:
+    """
+    Run the full constitutional self-audit.
+    """
+    min_severity = parse_min_severity(severity)
+    auditor_context = ctx.obj.auditor_context
+    auditor = ConstitutionalAuditor(auditor_context)
+    result = await auditor.run_full_audit_async()
+    findings = result["findings"]
+    logger.info("Audit returned %d findings.", len(findings))
+    all_findings = [
+        _to_audit_finding(f.as_dict() if hasattr(f, "as_dict") else f) for f in findings
+    ]
+    logger.info("Converted to %d AuditFinding objects.", len(all_findings))
+    await _persist_findings_to_db(all_findings)
+    filtered_findings = [f for f in all_findings if f.severity >= min_severity]
+    errors = [f for f in all_findings if f.severity.is_blocking]
+    warnings = [f for f in all_findings if f.severity == AuditSeverity.HIGH]
+    infos = [f for f in all_findings if f.severity == AuditSeverity.INFO]
+    passed = result["passed"]
+    summary_table = Table.grid(expand=True, padding=(0, 1))
+    summary_table.add_row("Total Findings:", str(len(all_findings)))
+    summary_table.add_row("Errors:", f"[red]{len(errors)}[/red]")
+    summary_table.add_row("Warnings:", f"[yellow]{len(warnings)}[/yellow]")
+    summary_table.add_row("Info:", f"[cyan]{len(infos)}[/cyan]")
+    summary_table.add_row("Verdict:", f"[bold]{result['verdict'].value}[/bold]")
+    title = "✅ AUDIT PASSED" if passed else "❌ AUDIT FAILED"
+    style = "bold green" if passed else "bold red"
+    console.print(Panel(summary_table, title=title, style=style, expand=False))
+    if filtered_findings:
+        if verbose:
+            print_verbose_findings(filtered_findings)
+        else:
+            print_summary_findings(filtered_findings)
+    if not passed:
+        raise typer.Exit(1)

cli/commands/check/converters.py

@@ -0,0 +1,129 @@
+# src/cli/commands/check/converters.py
+"""
+Data converters for audit results.
+
+Handles conversion between different audit finding formats:
+- Engine findings (dicts) -> AuditFinding objects
+- String severities -> AuditSeverity enums
+- File path resolution
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from shared.models import AuditFinding, AuditSeverity
+from shared.path_resolver import PathResolver
+from shared.path_utils import get_repo_root
+
+
+# Evidence artifact path written by the governance auditor
+LEGACY_AUDIT_EVIDENCE_PATH = (
+    PathResolver.from_repo(get_repo_root()).reports_dir / "audit" / "latest_audit.json"
+)
+
+
+# ID: a9b8c7d6-e5f4-3a2b-1c0d-9e8f7a6b5c4d
+def parse_min_severity(severity: str) -> AuditSeverity:
+    """Parse severity string to AuditSeverity enum with validation."""
+    try:
+        return AuditSeverity[severity.upper()]
+    except KeyError as exc:
+        raise typer.BadParameter(
+            f"Invalid severity level '{severity}'. "
+            f"Must be one of: info, low, medium, high, block."
+        ) from exc
+
+
+# ID: b8c7d6e5-f4a3-2b1c-0d9e-8f7a6b5c4d3e
+def severity_from_string(value: str | None) -> AuditSeverity:
+    """Convert lowercase string severity to enum, defaulting to BLOCK."""
+    if not value:
+        return AuditSeverity.BLOCK
+    v = value.strip().lower()
+    try:
+        return AuditSeverity[v.upper()]
+    except KeyError:
+        return AuditSeverity.BLOCK
+
+
+# ID: c7d6e5f4-a3b2-1c0d-9e8f-7a6b5c4d3e2f
+def convert_engine_findings_to_audit_findings(
+    *,
+    file_path: Path,
+    engine_findings: list[dict],
+    tag_check_ids: bool,
+) -> list[AuditFinding]:
+    """
+    Convert engine-based auditor findings (dicts) to AuditFinding objects.
+
+    Args:
+        file_path: Source file path for findings
+        engine_findings: List of finding dicts from engine
+        tag_check_ids: If True, prefix check_id with "v2:" for hybrid output
+
+    Returns:
+        List of AuditFinding objects
+    """
+    converted: list[AuditFinding] = []
+    for f in engine_findings:
+        rule_id = str(f.get("rule_id") or "unknown")
+        engine = str(f.get("engine") or "").strip()
+        message = str(f.get("message") or "Violation")
+        severity = severity_from_string(f.get("severity"))
+
+        check_id = f"v2:{rule_id}" if tag_check_ids else rule_id
+        if engine:
+            message = f"[{engine}] {message}"
+
+        converted.append(
+            AuditFinding(
+                check_id=check_id,
+                severity=severity,
+                message=message,
+                file_path=str(file_path),
+                line_number=None,
+            )
+        )
+    return converted
+
+
+# ID: d6e5f4a3-b2c1-0d9e-8f7a-6b5c4d3e2f1a
+def convert_finding_dicts_to_models(findings_dicts: list[dict]) -> list[AuditFinding]:
+    """
+    Convert finding dictionaries to AuditFinding model objects.
+
+    Handles severity string -> enum conversion.
+    """
+    severity_map = {str(s): s for s in AuditSeverity}
+    findings = []
+
+    for f_dict in findings_dicts:
+        severity_val = f_dict.get("severity", "info")
+        if isinstance(severity_val, str):
+            f_dict["severity"] = severity_map.get(severity_val, AuditSeverity.INFO)
+        findings.append(AuditFinding(**f_dict))
+
+    return findings
+
+
+# ID: e5f4a3b2-c1d0-9e8f-7a6b-5c4d3e2f1a0b
+def read_legacy_executed_ids_from_evidence() -> set[str]:
+    """
+    Read legacy auditor evidence to learn which checks/rules executed.
+
+    Returns empty set if evidence is missing or invalid.
+    """
+    try:
+        if not LEGACY_AUDIT_EVIDENCE_PATH.exists():
+            return set()
+        payload = json.loads(LEGACY_AUDIT_EVIDENCE_PATH.read_text(encoding="utf-8"))
+        executed = payload.get("executed_checks", [])
+        if not isinstance(executed, list):
+            return set()
+        return {str(x).strip() for x in executed if isinstance(x, str) and x.strip()}
+    except Exception:
+        return set()