core-runtime 0.1.1__py3-none-any.whl

cli/logic/legacy_scan_logic.py

@@ -0,0 +1,306 @@
+# src/cli/logic/legacy_scan_logic.py
+
+"""
+Legacy Scanner Logic - Pure read-only analysis.
+
+Scans the codebase for markers that indicate technical debt:
+workarounds, healed violations, circular import patches,
+deprecated code, and unresolved TODOs.
+
+Constitutional Alignment:
+- Phase: PARSE (read-only fact extraction)
+- Authority: CODE (structural analysis)
+- Boundary: Accepts repo_root parameter (no settings access)
+- No side effects: same input → same output
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from shared.infrastructure.intent.operational_config import load_operational_config
+
+
+_CFG = load_operational_config().misc
+
+
+# ---------------------------------------------------------------------------
+# Marker definitions — the map of what we're hunting
+# ---------------------------------------------------------------------------
+
+LEGACY_MARKERS: dict[str, dict] = {
+    "HEALED": {
+        "label": "Healed Violation",
+        "description": "Was broken, patched in-place. Candidate for proper fix.",
+        "severity": "high",
+        "color": "red",
+    },
+    "CONSTITUTIONAL FIX": {
+        "label": "Constitutional Fix",
+        "description": "Layer boundary violation patched inline. Needs architectural resolution.",
+        "severity": "high",
+        "color": "red",
+    },
+    "CIRCULARITY FIX": {
+        "label": "Circularity Fix",
+        "description": "Circular import resolved with late import hack. Needs structural fix.",
+        "severity": "high",
+        "color": "red",
+    },
+    "DEPRECATED": {
+        "label": "Deprecated",
+        "description": "Kept for compatibility. Safe to delete after confirming no callers.",
+        "severity": "medium",
+        "color": "yellow",
+    },
+    "WORKAROUND": {
+        "label": "Workaround",
+        "description": "Known bad solution. Needs a real fix.",
+        "severity": "high",
+        "color": "red",
+    },
+    "LEGACY": {
+        "label": "Legacy",
+        "description": "Old pattern kept alive. Review for removal.",
+        "severity": "medium",
+        "color": "yellow",
+    },
+    "FUTURE": {
+        "label": "FUTURE",
+        "description": "Unfinished work. May be blocking or just aspirational.",
+        "severity": "low",
+        "color": "blue",
+    },
+    "PENDING": {
+        "label": "PENDING",
+        "description": "Known broken or fragile. Needs attention.",
+        "severity": "high",
+        "color": "red",
+    },
+    "HACK": {
+        "label": "Hack",
+        "description": "Intentionally dirty solution. Needs cleanup.",
+        "severity": "high",
+        "color": "red",
+    },
+    "TEMP": {
+        "label": "Temporary",
+        "description": "Meant to be short-lived. Likely overstayed its welcome.",
+        "severity": "medium",
+        "color": "yellow",
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+# ID: b2c3d4e5-f6a7-8901-bcde-f01234567bcd
+class LegacyHit:
+    """A single legacy marker found in the codebase."""
+
+    file_path: str
+    line_number: int
+    marker: str
+    line_content: str
+    severity: str
+    label: str
+    color: str
+
+
+@dataclass
+# ID: c3d4e5f6-a7b8-9012-cdef-012345678cde
+class FileLegacySummary:
+    """Aggregated legacy findings for a single file."""
+
+    file_path: str
+    hits: list[LegacyHit] = field(default_factory=list)
+
+    @property
+    # ID: d4e5f6a7-b8c9-0123-defa-0123456789de
+    def total(self) -> int:
+        return len(self.hits)
+
+    @property
+    # ID: e5f6a7b8-c9d0-1234-efab-123456789012
+    def high_severity_count(self) -> int:
+        return sum(1 for h in self.hits if h.severity == "high")
+
+    @property
+    # ID: f6a7b8c9-d0e1-2345-fabc-23456789012f
+    def by_marker(self) -> dict[str, int]:
+        counts: dict[str, int] = {}
+        for hit in self.hits:
+            counts[hit.marker] = counts.get(hit.marker, 0) + 1
+        return counts
+
+
+@dataclass
+# ID: a7b8c9d0-e1f2-3456-abcd-34567890123a
+class LegacyScanResult:
+    """Complete scan result across all files."""
+
+    repo_root: str
+    files_scanned: int
+    files_with_hits: list[FileLegacySummary] = field(default_factory=list)
+
+    @property
+    # ID: b8c9d0e1-f2a3-4567-bcde-45678901234b
+    def total_hits(self) -> int:
+        return sum(f.total for f in self.files_with_hits)
+
+    @property
+    # ID: c9d0e1f2-a3b4-5678-cdef-56789012345c
+    def total_high_severity(self) -> int:
+        return sum(f.high_severity_count for f in self.files_with_hits)
+
+    @property
+    # ID: d0e1f2a3-b4c5-6789-defa-67890123456d
+    def marker_totals(self) -> dict[str, int]:
+        totals: dict[str, int] = {}
+        for f in self.files_with_hits:
+            for marker, count in f.by_marker.items():
+                totals[marker] = totals.get(marker, 0) + count
+        return dict(sorted(totals.items(), key=lambda x: x[1], reverse=True))
+
+    @property
+    # ID: e1f2a3b4-c5d6-7890-efab-78901234567e
+    def files_sorted_by_debt(self) -> list[FileLegacySummary]:
+        """Files sorted by high-severity count descending, then total."""
+        return sorted(
+            self.files_with_hits,
+            key=lambda f: (f.high_severity_count, f.total),
+            reverse=True,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Scanner — pure function, no side effects
+# ---------------------------------------------------------------------------
+
+
+# ID: f2a3b4c5-d6e7-8901-fabc-890123456789
+def scan_for_legacy_markers(
+    repo_root: Path,
+    scan_dirs: list[str] | None = None,
+    severity_filter: str | None = None,
+) -> LegacyScanResult:
+    """
+    Scan Python source files for legacy/debt markers.
+
+    Args:
+        repo_root: Repository root path.
+        scan_dirs: Subdirectories to scan (default: ["src"]).
+        severity_filter: If set, only return hits of this severity
+                         ("high", "medium", "low").
+
+    Returns:
+        LegacyScanResult with all findings, sortable by debt load.
+    """
+    if scan_dirs is None:
+        scan_dirs = ["src"]
+
+    # Build one combined regex that matches any marker (case-insensitive)
+    pattern = re.compile(
+        r"#.*\b(" + "|".join(re.escape(m) for m in LEGACY_MARKERS) + r")\b",
+        re.IGNORECASE,
+    )
+
+    files_scanned = 0
+    file_summaries: list[FileLegacySummary] = []
+
+    for scan_dir in scan_dirs:
+        target = repo_root / scan_dir
+        if not target.exists():
+            continue
+
+        for py_file in sorted(target.rglob("*.py")):
+            # Skip __pycache__ and .venv
+            parts = py_file.parts
+            if any(p in ("__pycache__", ".venv", ".git") for p in parts):
+                continue
+
+            files_scanned += 1
+            summary = _scan_file(py_file, repo_root, pattern, severity_filter)
+            if summary.hits:
+                file_summaries.append(summary)
+
+    return LegacyScanResult(
+        repo_root=str(repo_root),
+        files_scanned=files_scanned,
+        files_with_hits=file_summaries,
+    )
+
+
+# ID: a3b4c5d6-e7f8-9012-abcd-901234567890
+def _scan_file(
+    file_path: Path,
+    repo_root: Path,
+    pattern: re.Pattern,
+    severity_filter: str | None,
+) -> FileLegacySummary:
+    """Scan a single file and return its legacy summary."""
+    rel_path = str(file_path.relative_to(repo_root))
+    summary = FileLegacySummary(file_path=rel_path)
+
+    try:
+        lines = file_path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return summary
+
+    for line_num, line in enumerate(lines, start=1):
+        match = pattern.search(line)
+        if not match:
+            continue
+
+        # Identify which marker was matched (use uppercase for lookup)
+        matched_text = match.group(1).upper()
+
+        # Find the canonical marker key (handles partial matches)
+        marker_key = _resolve_marker(matched_text)
+        if not marker_key:
+            continue
+
+        info = LEGACY_MARKERS[marker_key]
+
+        if severity_filter and info["severity"] != severity_filter:
+            continue
+
+        summary.hits.append(
+            LegacyHit(
+                file_path=rel_path,
+                line_number=line_num,
+                marker=marker_key,
+                line_content=line.strip()[:120],  # Truncate for display
+                severity=info["severity"],
+                label=info["label"],
+                color=info["color"],
+            )
+        )
+
+    return summary
+
+
+# ID: b4c5d6e7-f8a9-0123-bcde-012345678901
+def _resolve_marker(text: str) -> str | None:
+    """Match detected text to a canonical marker key."""
+    # Direct match first
+    if text in LEGACY_MARKERS:
+        return text
+    for key in LEGACY_MARKERS:
+        if text in key or key in text:
+            return key
+    return None
+
+
+# ID: c5d6e7f8-a9b0-1234-cdef-123456789012
+def get_top_debt_files(
+    result: LegacyScanResult, limit: int = _CFG.legacy_scan_display_limit
+) -> list[FileLegacySummary]:
+    """Return the files with the highest debt load."""
+    return result.files_sorted_by_debt[:limit]

cli/logic/list_audits.py

@@ -0,0 +1,49 @@
+# src/cli/logic/list_audits.py
+
+"""
+Provides functionality for the list_audits module.
+"""
+
+from __future__ import annotations
+
+import typer
+from sqlalchemy import text
+
+from cli.utils import core_command
+from shared.infrastructure.database.session_manager import get_session
+
+
+@core_command(dangerous=False, requires_context=False)
+# ID: 23254df2-9a4f-4195-b174-53ad4ee00af4
+async def list_audits(
+    ctx: typer.Context,
+    limit: int = typer.Option(
+        10, "--limit", help="How many to show (most recent first)"
+    ),
+) -> None:
+    """Show recent rows from core.audit_runs."""
+    stmt = text(
+        """
+        select run_id, started_at, source, score, verdict
+        from core.audit_runs
+        order by started_at desc
+        limit :lim
+        """
+    ).bindparams(lim=limit)
+
+    async with get_session() as session:
+        result = await session.execute(stmt)
+        rows = result.all()
+
+    if not rows:
+        typer.echo("— no audit rows yet —")
+        return
+
+    for r in rows:
+        when = r.started_at.strftime("%Y-%m-%d %H:%M:%S")
+        mark = "✅" if r.verdict == "PASS" else "❌"
+        score = f"{float(r.score):.3f}" if r.score is not None else "—    "
+        typer.echo(
+            f"{str(r.run_id)[:8]}  {when}  {r.source:<7}  "
+            f"score={score}  {r.verdict:<8}  {mark}"
+        )

cli/logic/log_audit.py

@@ -0,0 +1,53 @@
+# src/cli/logic/log_audit.py
+
+"""
+Provides functionality for the log_audit module.
+"""
+
+from __future__ import annotations
+
+import typer
+from sqlalchemy import text
+
+from shared.infrastructure.database.session_manager import get_session
+
+
+# ID: 90625b7b-b201-458d-84a3-895835a005c0
+async def log_audit(
+    score: float = typer.Option(..., "--score", help="Audit score, e.g. 0.92"),
+    passed: bool = typer.Option(
+        True, "--passed/--failed", help="Mark audit as passed or failed"
+    ),
+    source: str = typer.Option(
+        "manual", "--source", help="Source label: manual|pr|nightly"
+    ),
+    commit_sha: str = typer.Option(
+        "", "--commit", help="Optional git commit SHA (40 chars)"
+    ),
+) -> None:
+    """Insert one row into core.audit_runs."""
+
+    sha = commit_sha or ""
+    verdict = "PASS" if passed else "FAIL"
+    stmt = text(
+        """
+        insert into core.audit_runs
+            (source, commit_sha, score, verdict, status,
+             started_at, finished_at)
+        values (:source, :sha, :score, :verdict, 'completed',
+                now(), now())
+        returning run_id
+        """
+    )
+    async with get_session() as session:
+        async with session.begin():
+            result = await session.execute(
+                stmt,
+                dict(source=source, sha=sha, score=score, verdict=verdict),
+            )
+            new_run_id = result.scalar_one()
+
+    typer.echo(
+        f"📝 Logged audit run_id={new_run_id} "
+        f"(source={source}, score={score}, verdict={verdict})"
+    )

cli/logic/new.py

@@ -0,0 +1,8 @@
+# src/cli/logic/new.py
+"""
+Handles the 'core-admin new' command for creating new project scaffolds.
+Intent: Defines the 'core-admin new' command, a user-facing wrapper
+around the Scaffolder tool.
+"""
+
+from __future__ import annotations

cli/logic/project_docs.py

@@ -0,0 +1,28 @@
+# src/cli/logic/project_docs.py
+"""
+CLI wrapper for generating capability documentation.
+It reuses the existing Python module entrypoint to keep one source of truth.
+"""
+
+from __future__ import annotations
+
+import runpy
+import sys
+
+import typer
+
+
+# ID: 752ead32-df2a-48c5-bb30-3530397e2cd2
+def docs(output: str = "docs/10_CAPABILITY_REFERENCE.md") -> None:
+    """
+    Generate capability documentation into the given output path.
+    """
+    mod = "features.introspection.generate_capability_docs"
+    # Preserve original argv and invoke the module as if run with: python -m ... --output <path>
+    argv_backup = sys.argv[:]
+    try:
+        sys.argv = [mod, "--output", output]
+        runpy.run_module(mod, run_name="__main__")
+    finally:
+        sys.argv = argv_backup
+    typer.echo(f"📚 Capability documentation written to: {output}")

cli/logic/reconcile.py

@@ -0,0 +1,127 @@
+# src/cli/logic/reconcile.py
+
+"""
+Implements the 'knowledge reconcile-from-cli' command to link declared
+capabilities to their implementations in the database, using the DB-backed
+CLI registry (core.cli_commands) as the authoritative map.
+
+Legacy YAML registry files are deprecated and must not be referenced here.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import text
+
+from shared.infrastructure.repositories.db.engine import get_session
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+def _entrypoint_to_symbol_path(entrypoint: str) -> str | None:
+    """
+    Converts 'package.module::function' into 'src/package/module.py::function'.
+
+    Returns None for invalid entrypoints.
+    """
+    if "::" not in entrypoint:
+        return None
+    module_path, function_name = entrypoint.split("::", 1)
+    module_path = (module_path or "").strip()
+    function_name = (function_name or "").strip()
+    if not module_path or not function_name:
+        return None
+    file_path_str = "src/" + module_path.replace(".", "/") + ".py"
+    return f"{file_path_str}::{function_name}"
+
+
+async def _async_reconcile() -> None:
+    """
+    Reads DB CLI registry and updates 'core.symbols.key' for symbols that
+    implement registered commands (only when key is currently NULL).
+    """
+    logger.info("Reconciling capabilities from DB CLI registry to symbols table...")
+
+    fetch_stmt = text(
+        """
+        SELECT
+            name,
+            entrypoint,
+            implements
+        FROM core.cli_commands
+        WHERE entrypoint IS NOT NULL
+        """
+    )
+
+    updates: list[dict[str, str]] = []
+
+    async with get_session() as session:
+        result = await session.execute(fetch_stmt)
+        rows = result.mappings().all()
+
+    if not rows:
+        logger.warning("No CLI commands found in DB registry (core.cli_commands).")
+        return
+
+    for row in rows:
+        entrypoint = row.get("entrypoint")
+        implements = row.get(
+            "implements"
+        )  # may be TEXT, JSON, JSONB, or NULL depending on schema
+        if not entrypoint:
+            continue
+
+        symbol_path = _entrypoint_to_symbol_path(entrypoint)
+        if not symbol_path:
+            continue
+
+        # Implements handling:
+        # - If implements is a list/array -> take first element
+        # - If implements is a string -> treat as single capability
+        # - Otherwise -> skip
+        capability_key: str | None = None
+        if isinstance(implements, list) and implements:
+            first = implements[0]
+            capability_key = first if isinstance(first, str) and first.strip() else None
+        elif isinstance(implements, str) and implements.strip():
+            capability_key = implements.strip()
+
+        if not capability_key:
+            continue
+
+        updates.append({"key": capability_key, "symbol_path": symbol_path})
+
+    if not updates:
+        logger.warning(
+            "No reconcile candidates found (missing implements/entrypoints)."
+        )
+        return
+
+    logger.info("Found %s capability implementations to link.", len(updates))
+
+    update_stmt = text(
+        """
+        UPDATE core.symbols
+        SET key = :key,
+            updated_at = NOW()
+        WHERE symbol_path = :symbol_path
+          AND key IS NULL
+        """
+    )
+
+    linked_count = 0
+    async with get_session() as session:
+        async with session.begin():
+            for u in updates:
+                res = await session.execute(update_stmt, u)
+                if res.rowcount and res.rowcount > 0:
+                    linked_count += int(res.rowcount)
+
+    logger.info("Successfully linked %s capability mappings.", linked_count)
+
+
+# ID: 0bb0702a-9b3b-487a-8049-a1fe9ad7cf41
+async def reconcile_from_cli() -> None:
+    """Typer-compatible async entrypoint."""
+    await _async_reconcile()