ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/codemap_freshness.py

@@ -0,0 +1,234 @@
+"""Codemap Freshness Scanner for REF Agents.
+
+Enforces codemap_standard.md § 6.1 freshness gate.
+Fixed threshold: 4 hours. No per-file configuration.
+
+NOTE: st_mtime may differ from wall clock in containerised/remote envs.
+      Acceptable — documented per risk register (REF-CODEMAP-001).
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+FRESHNESS_THRESHOLD_HOURS: float = 4.0
+
+
+@dataclass
+class CodemapFileStatus:
+    """Freshness status for a single codemap file.
+
+    Attributes:
+        path: Relative path from project root (e.g. 'codemap/CODE_MAP.md').
+        last_modified: ISO-8601 UTC timestamp of st_mtime.
+        age_hours: Age in decimal hours, rounded to 2 decimal places.
+        is_stale: True if age_hours > FRESHNESS_THRESHOLD_HOURS.
+    """
+
+    path: str
+    last_modified: str
+    age_hours: float
+    is_stale: bool
+
+
+@dataclass
+class CodemapFreshnessResult:
+    """Aggregated result of the codemap freshness scan.
+
+    Attributes:
+        status: One of 'fresh' | 'stale' | 'missing'.
+        files: Per-file breakdown. Empty when status == 'missing'.
+        codemap_dir: Resolved absolute path inspected.
+    """
+
+    status: str
+    files: list[CodemapFileStatus] = field(default_factory=list)
+    codemap_dir: str = ""
+
+
+def scan_codemap_freshness(directory: str) -> str:
+    """Scan codemap/ for freshness. Entry point for scan(target='codemap_freshness').
+
+    Constructs codemap path as Path(directory) / 'codemap', checks freshness,
+    logs codemap_stale artifact if stale, and returns formatted markdown report.
+
+    Args:
+        directory: Project root path string.
+
+    Returns:
+        Markdown string matching AC-1 format. Never raises.
+    """
+    # NOTE: Intentional broad catch — public entry point contract guarantees no raise.
+    try:
+        codemap_dir = Path(directory) / "codemap"
+        result = _check_freshness(codemap_dir)
+        if result.status == "stale":
+            _log_stale_artifact(directory)
+        return _format_result(result)
+    except (OSError, ValueError, TypeError, RuntimeError) as e:
+        logger.error("codemap_freshness_scan_failed", directory=directory, error=str(e))
+        return (
+            "## Codemap Freshness\nstatus: missing\n\n"
+            "Scan error. Run `generate_codemap('<project_root>')` to initialise."
+        )
+
+
+def get_freshness_result(directory: str) -> CodemapFreshnessResult:
+    """Return structured freshness result for a project root.
+
+    Public API for callers needing structured data (e.g. health_scanner).
+    Use scan_codemap_freshness() for the formatted string entry point.
+
+    Args:
+        directory: Project root path string.
+
+    Returns:
+        CodemapFreshnessResult with status fresh | stale | missing. Never raises.
+    """
+    try:
+        return _check_freshness(Path(directory) / "codemap")
+    except (OSError, ValueError, TypeError) as e:
+        logger.error(
+            "codemap_freshness_result_failed", directory=directory, error=str(e)
+        )
+        return CodemapFreshnessResult(status="missing")
+
+
+def _check_freshness(codemap_dir: Path) -> CodemapFreshnessResult:
+    """Check freshness of all .md files in codemap_dir.
+
+    Logic:
+      1. codemap_dir absent → missing
+      2. No .md files → missing
+      3. CODE_MAP.md absent → missing
+      4. stat() each file → build file list
+      5. Any is_stale=True → stale, else fresh
+
+    Args:
+        codemap_dir: Absolute path to the codemap/ directory.
+
+    Returns:
+        CodemapFreshnessResult. Never raises.
+    """
+    if not codemap_dir.exists():
+        return CodemapFreshnessResult(status="missing", codemap_dir=str(codemap_dir))
+
+    md_files = sorted(codemap_dir.glob("*.md"))
+    if not md_files:
+        return CodemapFreshnessResult(status="missing", codemap_dir=str(codemap_dir))
+
+    if not (codemap_dir / "CODE_MAP.md").exists():
+        return CodemapFreshnessResult(status="missing", codemap_dir=str(codemap_dir))
+
+    now = datetime.now(timezone.utc)
+    file_statuses: list[CodemapFileStatus] = []
+
+    for f in md_files:
+        file_status = _stat_file(f, now)
+        if file_status is not None:
+            file_statuses.append(file_status)
+
+    if not file_statuses:
+        return CodemapFreshnessResult(status="missing", codemap_dir=str(codemap_dir))
+
+    overall = "stale" if any(fs.is_stale for fs in file_statuses) else "fresh"
+    return CodemapFreshnessResult(
+        status=overall,
+        files=file_statuses,
+        codemap_dir=str(codemap_dir),
+    )
+
+
+def _stat_file(path: Path, now: datetime) -> CodemapFileStatus | None:
+    """Stat a single file and compute age.
+
+    Returns None on any OSError — handles TOCTOU race (file vanished between
+    glob and stat) and permission errors without surfacing to caller.
+
+    Args:
+        path: Absolute path to file.
+        now: Current UTC datetime for consistent age calculation across all files.
+
+    Returns:
+        CodemapFileStatus or None if stat failed.
+    """
+    try:
+        mtime = path.stat().st_mtime
+        last_modified_dt = datetime.fromtimestamp(mtime, tz=timezone.utc)
+        age_hours = round((now - last_modified_dt).total_seconds() / 3600, 2)
+        return CodemapFileStatus(
+            path=str(path.relative_to(path.parent.parent)),
+            last_modified=last_modified_dt.isoformat(),
+            age_hours=age_hours,
+            is_stale=age_hours > FRESHNESS_THRESHOLD_HOURS,
+        )
+    except PermissionError:
+        logger.warning("codemap_stat_permission_denied", path=str(path))
+        return None
+    except OSError as e:
+        logger.warning("codemap_stat_failed", path=str(path), error=str(e))
+        return None
+
+
+def _format_result(result: CodemapFreshnessResult) -> str:
+    """Format CodemapFreshnessResult as AC-1 markdown string.
+
+    Args:
+        result: Freshness result to render.
+
+    Returns:
+        Markdown string with status: header and file table.
+    """
+    lines = [f"## Codemap Freshness\nstatus: {result.status}"]
+
+    if result.status == "missing":
+        lines.append(
+            "\nCodemap not found or empty. "
+            "Run `generate_codemap('<project_root>')` to initialise."
+        )
+        return "\n".join(lines)
+
+    lines.append("\n| File | Last Modified (ISO-8601) | Age (hours) |")
+    lines.append("|------|--------------------------|-------------|")
+    for fs in result.files:
+        marker = " ⚠️" if fs.is_stale else ""
+        lines.append(f"| {fs.path}{marker} | {fs.last_modified} | {fs.age_hours:.2f} |")
+
+    if result.status == "stale":
+        lines.append(
+            f"\n⚠️ Stale files detected (threshold: {FRESHNESS_THRESHOLD_HOURS:.0f}h). "
+            "Codemap results are advisory until regenerated."
+        )
+
+    return "\n".join(lines)
+
+
+def _log_stale_artifact(directory: str) -> None:
+    """Log codemap_stale artifact to active workflow story if one exists.
+
+    Calls mark_artifact_complete(artifact='codemap_stale') with no story_id —
+    WorkflowManager resolves the active story internally from disk state.
+    If no active story: logs warning, skips call, does not raise.
+
+    Args:
+        directory: Project root path (used for log context only).
+    """
+    try:
+        from ref_agents.tools.workflow_tools import mark_artifact_complete
+
+        result = mark_artifact_complete(artifact="codemap_stale")
+        if "No active story" in result:
+            logger.warning(
+                "codemap_stale_no_active_story",
+                directory=directory,
+                detail="codemap_stale artifact not logged — no active workflow story",
+            )
+    # NOTE: Intentional broad catch — fire-and-forget, must not interrupt caller.
+    except (ImportError, AttributeError, RuntimeError, OSError) as e:
+        logger.warning(
+            "codemap_stale_artifact_log_failed", directory=directory, error=str(e)
+        )

ref_agents/tools/comment_smell_scanner.py

@@ -0,0 +1,346 @@
+"""Comment Smell Scanner — C5 (commented-out code) detector.
+
+Detects commented-out code in Python and JS/TS files using heuristic regex
+patterns, with optional eradicate integration for Python files.
+
+Runs against ANY target directory; no assumptions about target tooling.
+
+Usage:
+    from ref_agents.tools.comment_smell_scanner import scan_comment_smells
+    findings = scan_comment_smells(Path("/path/to/repo"))
+"""
+
+import re
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import structlog
+
+from ref_agents.constants import COMMENT_SMELL_EXTENSIONS
+
+logger = structlog.get_logger(__name__)
+
+# Directories that are never scanned (build artifacts, deps, VCS, caches).
+_SKIP_DIRS: frozenset[str] = frozenset(
+    {
+        ".venv",
+        "venv",
+        "node_modules",
+        ".git",
+        "dist",
+        "build",
+        "__pycache__",
+    }
+)
+
+# Python: commented-out function calls — `# old_func(arg)`
+_PY_CALL_RE: re.Pattern[str] = re.compile(r"^\s*#\s+[a-zA-Z_]\w*\s*\(")
+
+# Python: commented-out control-flow / structural keywords
+_PY_KEYWORD_RE: re.Pattern[str] = re.compile(
+    r"^\s*#\s+(return|if|for|while|class|def|import|from)\s"
+)
+
+# JS/TS: commented-out expressions
+_JS_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"//\s+[a-zA-Z_]\w*\("),  # function call
+    re.compile(r"//\s+return\s"),  # return statement
+    re.compile(r"//\s+const\s"),  # const declaration
+    re.compile(r"//\s+let\s"),  # let declaration
+    re.compile(r"//\s+function\s"),  # function declaration
+]
+
+# Suppression marker — any occurrence on the line disables C5 for that line.
+_SUPPRESS_MARKER: str = "ref:allow C5"
+
+
+@dataclass
+class CommentSmellFinding:
+    """Single C5 (commented-out code) finding.
+
+    Attributes:
+        file: Relative path to the file (relative to scanned directory).
+        line_number: 1-based line number of the finding.
+        line_content: Stripped line content.
+        language: Source language identifier ("python" or "js_ts").
+        severity: Always "HIGH" — commented-out code is an unconditional debt signal.
+    """
+
+    file: str
+    line_number: int
+    line_content: str
+    language: str
+    severity: str = field(default="HIGH")
+
+
+def _is_skipped_path(path: Path) -> bool:
+    """Return True if any path component is in the skip-dirs set.
+
+    Args:
+        path: Absolute or relative path to check.
+
+    Returns:
+        True when the path should be excluded from scanning.
+    """
+    return any(part in _SKIP_DIRS for part in path.parts)
+
+
+def _is_test_file(path: Path) -> bool:
+    """Return True when the file is a test file.
+
+    Criteria:
+    - Any component of the path is exactly ``tests``
+    - Filename starts with ``test_``
+
+    Args:
+        path: File path to evaluate.
+
+    Returns:
+        True for test files; False otherwise.
+    """
+    if path.name.startswith("test_"):
+        return True
+    return "tests" in path.parts
+
+
+def _is_generated_file(path: Path) -> bool:
+    """Heuristic: skip files that look machine-generated.
+
+    Currently matches ``*.min.js`` and ``*.min.css`` suffixes.
+
+    Args:
+        path: File path.
+
+    Returns:
+        True for generated files.
+    """
+    return path.name.endswith((".min.js", ".min.css"))
+
+
+def _eradicate_available() -> bool:
+    """Return True if ``eradicate`` binary is on PATH.
+
+    Returns:
+        True when ``eradicate --version`` exits without error.
+    """
+    try:
+        subprocess.run(  # noqa: S603  # NOTE: Controlled input — no shell expansion.
+            ["eradicate", "--version"],
+            capture_output=True,
+            timeout=5,
+        )
+        return True
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def _scan_python_with_eradicate(
+    file_path: Path, relative_path: Path
+) -> list[CommentSmellFinding]:
+    """Run eradicate --check and parse flagged line numbers.
+
+    Args:
+        file_path: Absolute path to the Python file.
+        relative_path: Relative path used in finding output.
+
+    Returns:
+        List of findings from eradicate. Empty on error or clean file.
+    """
+    findings: list[CommentSmellFinding] = []
+    try:
+        result = subprocess.run(  # noqa: S603  # NOTE: Controlled input — no shell expansion.
+            ["eradicate", "--check", str(file_path)],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        # eradicate prints lines like: filename.py:42: ...
+        for output_line in result.stdout.splitlines() + result.stderr.splitlines():
+            parts = output_line.split(":")
+            if len(parts) < 2:  # noqa: PLR2004
+                continue
+            try:
+                lineno = int(parts[1].strip())
+            except ValueError:
+                continue
+
+            # Re-read the source line for context
+            try:
+                src_lines = file_path.read_text(encoding="utf-8").splitlines()
+                if 1 <= lineno <= len(src_lines):
+                    raw_line = src_lines[lineno - 1]
+                    if _SUPPRESS_MARKER in raw_line:
+                        continue
+                    findings.append(
+                        CommentSmellFinding(
+                            file=str(relative_path),
+                            line_number=lineno,
+                            line_content=raw_line.strip(),
+                            language="python",
+                        )
+                    )
+            except (OSError, UnicodeDecodeError):
+                pass
+    except (subprocess.TimeoutExpired, OSError) as exc:
+        logger.debug("eradicate_run_failed", file=str(file_path), error=str(exc))
+    return findings
+
+
+def _scan_python_heuristic(
+    lines: list[str], relative_path: Path
+) -> list[CommentSmellFinding]:
+    """Regex heuristic fallback for Python C5 detection.
+
+    Args:
+        lines: File content split into lines (0-indexed).
+        relative_path: Relative path used in finding output.
+
+    Returns:
+        List of C5 findings.
+    """
+    findings: list[CommentSmellFinding] = []
+    for idx, raw in enumerate(lines, start=1):
+        if _SUPPRESS_MARKER in raw:
+            continue
+        if _PY_CALL_RE.search(raw) or _PY_KEYWORD_RE.search(raw):
+            findings.append(
+                CommentSmellFinding(
+                    file=str(relative_path),
+                    line_number=idx,
+                    line_content=raw.strip(),
+                    language="python",
+                )
+            )
+    return findings
+
+
+def _scan_js_ts_heuristic(
+    lines: list[str], relative_path: Path
+) -> list[CommentSmellFinding]:
+    """Regex heuristic for JS/TS C5 detection.
+
+    Args:
+        lines: File content split into lines (0-indexed).
+        relative_path: Relative path used in finding output.
+
+    Returns:
+        List of C5 findings.
+    """
+    findings: list[CommentSmellFinding] = []
+    for idx, raw in enumerate(lines, start=1):
+        if _SUPPRESS_MARKER in raw:
+            continue
+        if any(pat.search(raw) for pat in _JS_PATTERNS):
+            findings.append(
+                CommentSmellFinding(
+                    file=str(relative_path),
+                    line_number=idx,
+                    line_content=raw.strip(),
+                    language="js_ts",
+                )
+            )
+    return findings
+
+
+def _scan_file(
+    file_path: Path,
+    directory: Path,
+    use_eradicate: bool,
+) -> list[CommentSmellFinding]:
+    """Scan a single file for C5 violations.
+
+    Args:
+        file_path: Absolute path to the file.
+        directory: Root directory of the scan (for relative paths).
+        use_eradicate: Whether eradicate is available.
+
+    Returns:
+        List of findings; empty when file is clean or unreadable.
+    """
+    try:
+        content = file_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        logger.debug("comment_smell_read_error", file=str(file_path), error=str(exc))
+        return []
+
+    try:
+        relative_path = file_path.relative_to(directory)
+    except ValueError:
+        relative_path = file_path
+
+    suffix = file_path.suffix.lower()
+    lines = content.splitlines()
+
+    if suffix == ".py":
+        if use_eradicate:
+            eradicate_results = _scan_python_with_eradicate(file_path, relative_path)
+            if eradicate_results:
+                return eradicate_results
+        return _scan_python_heuristic(lines, relative_path)
+
+    # JS / TS family
+    return _scan_js_ts_heuristic(lines, relative_path)
+
+
+def scan_comment_smells(directory: Path) -> list[CommentSmellFinding]:
+    """Scan a directory tree for C5 (commented-out code) violations.
+
+    Self-contained: no target tooling assumed beyond optional ``eradicate``
+    for Python. Falls back to regex heuristics when eradicate is absent.
+
+    Skips:
+    - Directories: .venv, venv, node_modules, .git, dist, build, __pycache__
+    - Test files: path contains ``/tests/`` or filename starts with ``test_``
+    - Generated files: ``*.min.js``, ``*.min.css``
+    - Extensions not in ``COMMENT_SMELL_EXTENSIONS``
+
+    Args:
+        directory: Root directory to scan recursively.
+
+    Returns:
+        Sorted list of CommentSmellFinding (by file path, then line number).
+
+    Raises:
+        NotADirectoryError: If ``directory`` does not exist or is not a directory.
+    """
+    if not directory.is_dir():
+        raise NotADirectoryError(f"Not a directory: {directory}")
+
+    use_eradicate = _eradicate_available()
+    if use_eradicate:
+        logger.info("comment_smell_eradicate_active")
+    else:
+        logger.info("comment_smell_heuristic_mode")
+
+    all_findings: list[CommentSmellFinding] = []
+
+    for file_path in directory.rglob("*"):
+        if not file_path.is_file():
+            continue
+        if file_path.suffix.lower() not in COMMENT_SMELL_EXTENSIONS:
+            continue
+        if _is_skipped_path(file_path.relative_to(directory)):
+            continue
+        if _is_test_file(file_path):
+            continue
+        if _is_generated_file(file_path):
+            continue
+
+        findings = _scan_file(file_path, directory, use_eradicate)
+        all_findings.extend(findings)
+        if findings:
+            logger.debug(
+                "comment_smell_findings",
+                file=str(file_path),
+                count=len(findings),
+            )
+
+    all_findings.sort(key=lambda f: (f.file, f.line_number))
+
+    logger.info(
+        "comment_smell_scan_complete",
+        directory=str(directory),
+        total_findings=len(all_findings),
+    )
+    return all_findings