ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/summary_generator.py

@@ -0,0 +1,275 @@
+"""Executive Summary Generator for REF Dashboard.
+
+Aggregates metrics from security scans, debt scans, and compliance checks
+to generate ref-reports/executive-summary.json for dashboard consumption.
+"""
+
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import TypedDict
+
+import structlog
+
+from ref_agents.tools.debt_scanner import get_cached_debt_count
+
+logger = structlog.get_logger(__name__)
+
+
+class ExecutiveSummary(TypedDict):
+    """Schema for executive-summary.json."""
+
+    generated_at: str
+    score: float
+    critical_issues: int
+    debt_count: int
+    security_passed: bool
+    compliance_passed: bool
+
+
+def _find_latest_security_report(base_dir: Path) -> Path | None:
+    """Find the most recent security audit report.
+
+    Args:
+        base_dir: Base directory containing ref-reports.
+
+    Returns:
+        Path to latest security report or None if not found.
+    """
+    security_dir = base_dir / "ref-reports" / "security"
+    if not security_dir.exists():
+        return None
+
+    reports = list(security_dir.glob("security_audit_*.md"))
+    if not reports:
+        return None
+
+    # Sort by modification time, newest first
+    reports.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    return reports[0]
+
+
+def _parse_security_report(report_path: Path) -> tuple[bool, int]:
+    """Parse security report to extract pass/fail status and critical issues.
+
+    Args:
+        report_path: Path to security audit markdown file.
+
+    Returns:
+        Tuple of (security_passed, critical_issues_count).
+    """
+    try:
+        content = report_path.read_text(encoding="utf-8")
+
+        # Check for overall status
+        security_passed = "OVERALL: ✅ PASSED" in content
+
+        # Count critical issues (❌ FAIL lines, not FAILED overall status)
+        fail_pattern = re.compile(r"❌\s*FAIL\b(?!ED)")
+        critical_issues = len(fail_pattern.findall(content))
+
+        return security_passed, critical_issues
+
+    except OSError as e:
+        logger.warning(
+            "Failed to parse security report", path=str(report_path), error=str(e)
+        )
+        return True, 0  # Default to passed if can't read
+
+
+def _get_debt_count(directory: Path) -> int:
+    """Get technical debt item count from cache (non-blocking).
+
+    Reads from existing cache. Returns 0 if no cache exists.
+    Does NOT trigger a new scan - use scan_debt() separately.
+
+    Args:
+        directory: Directory containing .ref cache.
+
+    Returns:
+        Number of debt items in cache, or 0 if no cache.
+    """
+    # Try to read from cache first (instant, non-blocking)
+    cached_count = get_cached_debt_count(directory)
+    if cached_count is not None:
+        logger.info("debt_count_from_cache", count=cached_count)
+        return cached_count
+
+    # No cache exists - return 0 (user should run scan_debt first)
+    logger.info("no_debt_cache", directory=str(directory))
+    return 0
+
+
+def _check_compliance(base_dir: Path) -> bool:
+    """Check if compliance reports indicate passing status.
+
+    Args:
+        base_dir: Base directory containing ref-reports.
+
+    Returns:
+        True if compliance passed or no compliance reports exist.
+    """
+    reports_dir = base_dir / "ref-reports"
+    if not reports_dir.exists():
+        return True
+
+    # Look for compliance reports in any agent directory
+    compliance_files = list(reports_dir.glob("*/compliance_*.md"))
+    if not compliance_files:
+        return True  # No compliance reports = passed
+
+    # Check latest compliance report
+    compliance_files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    latest = compliance_files[0]
+
+    try:
+        content = latest.read_text(encoding="utf-8")
+        # If "Issues Found" appears, compliance failed
+        return "⚠️ Issues Found" not in content
+    except OSError:
+        return True
+
+
+def _calculate_score(
+    security_passed: bool,
+    critical_issues: int,
+    debt_count: int,
+    compliance_passed: bool,
+) -> float:
+    """Calculate project health score from metrics.
+
+    Args:
+        security_passed: Whether security audit passed.
+        critical_issues: Number of critical security issues.
+        debt_count: Number of technical debt items.
+        compliance_passed: Whether compliance checks passed.
+
+    Returns:
+        Score from 0.0 to 100.0.
+    """
+    score = 100.0
+
+    # Security failures
+    if not security_passed:
+        score -= 20.0
+    score -= min(critical_issues * 10.0, 30.0)
+
+    # Technical debt penalty (capped)
+    score -= min(debt_count * 2.0, 30.0)
+
+    # Compliance failure
+    if not compliance_passed:
+        score -= 10.0
+
+    return max(0.0, min(100.0, score))
+
+
+def generate_executive_summary(directory: str = "") -> ExecutiveSummary:
+    """Generate executive summary by aggregating all metrics.
+
+    Args:
+        directory: Base directory to scan. Defaults to project_root if set,
+                   otherwise current working directory.
+
+    Returns:
+        ExecutiveSummary dictionary with all metrics.
+    """
+    if directory:
+        base_dir = Path(directory)
+    else:
+        from ref_agents.session import SessionManager
+
+        session = SessionManager.get()
+        base_dir = session.project_root or Path.cwd()
+
+    security_report = _find_latest_security_report(base_dir)
+    if security_report:
+        security_passed, critical_issues = _parse_security_report(security_report)
+    else:
+        security_passed = True
+        critical_issues = 0
+
+    src_dir = base_dir / "src"
+    scan_dir = src_dir if src_dir.exists() else base_dir
+    debt_count = _get_debt_count(scan_dir)
+
+    compliance_passed = _check_compliance(base_dir)
+
+    # Calculate score
+    score = _calculate_score(
+        security_passed, critical_issues, debt_count, compliance_passed
+    )
+
+    return ExecutiveSummary(
+        generated_at=datetime.now().isoformat(),
+        score=round(score, 1),
+        critical_issues=critical_issues,
+        debt_count=debt_count,
+        security_passed=security_passed,
+        compliance_passed=compliance_passed,
+    )
+
+
+def write_executive_summary(directory: str = "") -> Path:
+    """Generate and write executive-summary.json to ref-reports/.
+
+    Args:
+        directory: Base directory. Defaults to project_root if set,
+                   otherwise current working directory.
+
+    Returns:
+        Path to written executive-summary.json.
+
+    Raises:
+        OSError: If file cannot be written.
+    """
+    if directory:
+        base_dir = Path(directory)
+    else:
+        from ref_agents.session import SessionManager
+
+        session = SessionManager.get()
+        base_dir = session.project_root or Path.cwd()
+    summary = generate_executive_summary(directory)
+
+    output_dir = base_dir / "ref-reports"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    output_path = output_dir / "executive-summary.json"
+    output_path.write_text(json.dumps(summary, indent=2), encoding="utf-8")
+
+    logger.info(
+        "executive_summary_written",
+        path=str(output_path),
+        score=summary["score"],
+        debt_count=summary["debt_count"],
+    )
+
+    return output_path
+
+
+def generate_project_summary_tool(directory: str = "") -> str:
+    """MCP tool wrapper for generating executive summary.
+
+    Args:
+        directory: Base directory to scan. Empty string for current directory.
+
+    Returns:
+        Status message with path to generated file.
+    """
+    try:
+        output_path = write_executive_summary(directory)
+        summary = generate_executive_summary(directory)
+
+        return (
+            f"Executive summary generated: `{output_path}`\n\n"
+            f"**Metrics:**\n"
+            f"- Score: {summary['score']}/100\n"
+            f"- Critical Issues: {summary['critical_issues']}\n"
+            f"- Tech Debt Items: {summary['debt_count']}\n"
+            f"- Security: {'✅ Passed' if summary['security_passed'] else '❌ Failed'}\n"
+            f"- Compliance: {'✅ Passed' if summary['compliance_passed'] else '❌ Failed'}"
+        )
+    except OSError as e:
+        return f"Error generating summary: {e}"

ref_agents/tools/symbol_resolver.py

@@ -0,0 +1,306 @@
+"""Symbol resolver for STORY-TQ-003 — grounded interface-contract lookup.
+
+Locates symbol names in deterministic precedence order from sources OUTSIDE the
+LLM chain: existing CODE_MAP entries, then the story's ``## Public Interface``
+table, then OpenAPI operation ids, then ``.pyi`` stub declarations. The resolver
+is read-only — never modifies any grounding source.
+
+OpenAPI and ``.pyi`` consumption is scaffolded but disabled in v1 per
+``docs/specs/SPEC-STORY-TQ-003.md`` FR-11. Tester generates executable tests
+only for ``code_map`` and ``story_public_interface`` candidates.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+CODEMAP_FRESHNESS_SECONDS: int = 4 * 3600  # 4 hours; matches existing scanner gate.
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """One grounded candidate for a ``symbol_under_test`` entry.
+
+    Attributes:
+        name: Bare or dotted symbol name (e.g. ``calculate_total`` or
+            ``Payment.process``).
+        source: One of ``code_map`` / ``story_public_interface`` / ``openapi``
+            / ``pyi_stub``. ``none`` is reserved for ungrounded entries — not
+            emitted here.
+        module_path: Optional dotted module path (best-effort).
+        grounding: Free-text descriptor naming the file + anchor that supplied
+            the symbol (e.g. ``CODE_MAP.md:src/pkg/foo.py``).
+    """
+
+    name: str
+    source: str
+    module_path: str | None
+    grounding: str
+
+
+VALID_SOURCES: tuple[str, ...] = (
+    "code_map",
+    "story_public_interface",
+    "openapi",
+    "pyi_stub",
+    "none",
+)
+
+
+def resolve(
+    name: str,
+    story_path: Path | None,
+    project_root: Path,
+) -> list[Candidate]:
+    """Return ordered candidates for ``name`` from all grounding sources.
+
+    First match per source is recorded. Caller picks the first element of the
+    returned list to honour precedence (CODE_MAP > story Public Interface >
+    OpenAPI > stub).
+
+    Args:
+        name: Symbol name being resolved. May contain ``.`` for class methods.
+        story_path: Path to the story file containing the optional Public
+            Interface table. ``None`` skips that source.
+        project_root: Project root for CODE_MAP, OpenAPI, and stub lookup.
+
+    Returns:
+        List of candidates ordered by source precedence. Empty when no source
+        contains the symbol.
+    """
+    candidates: list[Candidate] = []
+
+    codemap_path = _find_codemap(project_root)
+    if codemap_path is not None and not _is_stale(codemap_path):
+        candidates.extend(_lookup_codemap(name, codemap_path, project_root))
+    elif codemap_path is not None:
+        logger.info(
+            "codemap_stale_skipped",
+            path=str(codemap_path),
+            age_seconds=int(time.time() - codemap_path.stat().st_mtime),
+        )
+
+    if story_path is not None and story_path.exists():
+        candidates.extend(_lookup_public_interface(name, story_path))
+
+    # OpenAPI and .pyi sources scaffolded but disabled in v1 (FR-11).
+    # Hook points are kept here so M3b can wire them without re-design.
+    return candidates
+
+
+def is_valid_source(value: str) -> bool:
+    """True iff ``value`` is one of the documented enum entries."""
+    return value in VALID_SOURCES
+
+
+def _find_codemap(project_root: Path) -> Path | None:
+    """Return the project's CODE_MAP path, preferring root over ``docs/``."""
+    for candidate in (
+        project_root / "CODE_MAP.md",
+        project_root / "docs" / "CODE_MAP.md",
+    ):
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _is_stale(path: Path) -> bool:
+    try:
+        age = time.time() - path.stat().st_mtime
+    except OSError:
+        return True
+    return age > CODEMAP_FRESHNESS_SECONDS
+
+
+# --- CODE_MAP lookup ----------------------------------------------------------
+
+
+# Matches a single row in the "Key Classes / Functions" table.
+# Columns: | `name` | `file_path` | purpose | deps |
+_CODEMAP_ROW = re.compile(
+    r"^\|\s*`(?P<name>[^`]+?)`\s*\|\s*`(?P<file>[^`]+?)`\s*\|.*?\|.*?\|\s*$",
+)
+
+
+def _lookup_codemap(
+    name: str,
+    codemap_path: Path,
+    project_root: Path,
+) -> list[Candidate]:
+    """Extract all matching rows from the Key Classes / Functions table."""
+    try:
+        lines = codemap_path.read_text(encoding="utf-8").splitlines()
+    except OSError as exc:
+        logger.warning("codemap_read_failed", error=str(exc))
+        return []
+
+    candidates: list[Candidate] = []
+    seen_relative = codemap_path.relative_to(project_root)
+
+    in_symbols_table = False
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("## Key Classes / Functions") or stripped.startswith(
+            "## Functions"
+        ):
+            in_symbols_table = True
+            continue
+        if (
+            in_symbols_table
+            and stripped.startswith("## ")
+            and not stripped.startswith("## Key Classes / Functions")
+        ):
+            in_symbols_table = False
+            continue
+        if not in_symbols_table:
+            continue
+        match = _CODEMAP_ROW.match(line)
+        if not match:
+            continue
+        row_name = match.group("name").strip()
+        # Strip trailing parens: `do_thing()` → `do_thing`.
+        bare_name = row_name.split("(", 1)[0]
+        if bare_name != name:
+            continue
+        file_path = match.group("file").strip()
+        module_path = _module_path_from_file(file_path)
+        candidates.append(
+            Candidate(
+                name=bare_name,
+                source="code_map",
+                module_path=module_path,
+                grounding=f"{seen_relative}:{file_path}",
+            )
+        )
+
+    # Deterministic order: shortest module path first (matches lexical sort heuristic).
+    candidates.sort(key=lambda c: ((c.module_path or ""), c.grounding))
+    return candidates
+
+
+def _module_path_from_file(file_path: str) -> str | None:
+    """Convert a source-tree file path into a dotted module path.
+
+    Strips a leading ``src/`` prefix (common Python layout) and the ``.py``
+    extension. Returns ``None`` for paths that don't look like Python source.
+    """
+    path = Path(file_path)
+    if path.suffix not in (".py", ""):
+        return None
+    parts = list(path.with_suffix("").parts)
+    if parts and parts[0] == "src":
+        parts = parts[1:]
+    if not parts:
+        return None
+    # Drop a trailing __init__ for package imports.
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    if not parts:
+        return None
+    return ".".join(parts)
+
+
+# --- Public Interface table lookup --------------------------------------------
+
+
+_TABLE_HEADER = re.compile(
+    r"^\s*\|\s*symbol\s*\|\s*module_path\s*\|\s*signature\s*\|\s*description\s*\|\s*$",
+    re.IGNORECASE,
+)
+_TABLE_ROW = re.compile(
+    r"^\s*\|\s*`?(?P<symbol>[^|`]+?)`?\s*\|\s*`?(?P<module>[^|`]+?)`?\s*\|\s*`?(?P<signature>[^|]+?)`?\s*\|\s*(?P<description>[^|]*?)\s*\|\s*$",
+)
+
+
+def _lookup_public_interface(
+    name: str,
+    story_path: Path,
+) -> list[Candidate]:
+    """Parse the ``## Public Interface`` section of a story file."""
+    try:
+        text = story_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.warning("story_read_failed", path=str(story_path), error=str(exc))
+        return []
+
+    section = _extract_section(text, "Public Interface")
+    if section is None:
+        return []
+
+    rows = _parse_table(section)
+    candidates: list[Candidate] = []
+    for idx, row in enumerate(rows, start=1):
+        if row["symbol"].strip() == name:
+            candidates.append(
+                Candidate(
+                    name=name,
+                    source="story_public_interface",
+                    module_path=row["module_path"].strip() or None,
+                    grounding=f"{story_path.name}:Public Interface row {idx}",
+                )
+            )
+    return candidates
+
+
+def _extract_section(text: str, section_title: str) -> str | None:
+    """Return the markdown content of ``## {section_title}`` (without heading).
+
+    Tolerates leading whitespace before the heading (test fixtures sometimes
+    produce uneven indentation via ``textwrap.dedent``). Section ends at the
+    next ``## `` heading or EOF.
+    """
+    pattern = re.compile(
+        rf"^[ \t]*##\s+{re.escape(section_title)}\s*$",
+        re.MULTILINE,
+    )
+    match = pattern.search(text)
+    if not match:
+        return None
+    start = match.end()
+    next_heading = re.search(r"^[ \t]*##\s+", text[start:], re.MULTILINE)
+    end = start + next_heading.start() if next_heading else len(text)
+    return text[start:end]
+
+
+def _parse_table(section: str) -> list[dict[str, str]]:
+    """Parse a four-column markdown table in the section text.
+
+    Skips the header + separator lines. Returns a list of dicts with keys
+    ``symbol``, ``module_path``, ``signature``, ``description``.
+    """
+    rows: list[dict[str, str]] = []
+    saw_header = False
+    saw_separator = False
+    for raw in section.splitlines():
+        if not saw_header:
+            if _TABLE_HEADER.match(raw):
+                saw_header = True
+            continue
+        if not saw_separator:
+            stripped_for_sep = raw.lstrip()
+            if "---" in raw and stripped_for_sep.startswith("|"):
+                saw_separator = True
+            continue
+        match = _TABLE_ROW.match(raw)
+        if not match:
+            # Blank line or unrelated content ends the table.
+            if raw.strip() == "" or not raw.lstrip().startswith("|"):
+                break
+            continue
+        rows.append(
+            {
+                "symbol": match.group("symbol"),
+                "module_path": match.group("module"),
+                "signature": match.group("signature"),
+                "description": match.group("description"),
+            }
+        )
+    return rows