forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/review/report.py

@@ -0,0 +1,311 @@
+"""Rich + JSON + Markdown renderers for a :class:`RepositoryReview`."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.table import Table
+
+from forgecli.review.finding import Finding, Severity
+from forgecli.review.repository import RepositoryReview
+from forgecli.review.suggestions import Suggestion
+from forgecli.utils.paths import to_privacy_path
+
+_SEVERITY_STYLE: dict[Severity, str] = {
+    Severity.INFO: "cyan",
+    Severity.LOW: "green",
+    Severity.MEDIUM: "yellow",
+    Severity.HIGH: "bold red",
+    Severity.CRITICAL: "bold magenta on red",
+}
+
+
+def print_review(
+    review: RepositoryReview,
+    console: Console | None = None,
+    *,
+    full: bool = False,
+) -> None:
+    """Print a :class:`RepositoryReview` using the given Rich console."""
+    console = console or Console()
+    for renderable in render_review(review, full=full):
+        console.print(renderable)
+
+
+def render_review(review: RepositoryReview, *, full: bool = False) -> list:
+    """Return a list of Rich renderables that visualize ``review``."""
+    out: list = []
+    out.append(_render_header(review))
+    out.append(_render_summary(review))
+    if review.suggestions:
+        out.append(_render_suggestions(review.suggestions))
+    if review.findings:
+        out.append(_render_findings(review.findings, full=full))
+    if not review.findings:
+        out.append(Panel("[green]No findings.[/green]", border_style="green"))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# JSON / Markdown
+# ---------------------------------------------------------------------------
+
+
+def review_to_json(review: RepositoryReview, *, indent: int = 2) -> str:
+    """Return the review as a JSON string."""
+    return json.dumps(review.to_dict(), indent=indent)
+
+
+def review_to_markdown(review: RepositoryReview) -> str:
+    """Return a Markdown rendering of ``review``."""
+    parts: list[str] = []
+    parts.append(f"# Review: {to_privacy_path(review.root)}\n")
+    counts = review.counts_by_severity()
+    parts.append("## Summary")
+    parts.append("")
+    parts.append(f"- Files analyzed: {review.stats.get('files', 0)}")
+    parts.append(f"- Analyzers run: {', '.join(review.analyzer_names)}")
+    parts.append(
+        f"- Findings: {len(review.findings)} "
+        f"(critical={counts[Severity.CRITICAL]}, "
+        f"high={counts[Severity.HIGH]}, "
+        f"medium={counts[Severity.MEDIUM]}, "
+        f"low={counts[Severity.LOW]}, "
+        f"info={counts[Severity.INFO]})"
+    )
+    if review.suggestions:
+        parts.append("## Suggestions")
+        parts.append("")
+        for suggestion in review.suggestions:
+            parts.append(
+                f"- **[{suggestion.severity.value}] {suggestion.title}** "
+                f"({suggestion.count} occurrence{'s' if suggestion.count != 1 else ''})"
+            )
+            if suggestion.rationale:
+                parts.append(f"    - {suggestion.rationale}")
+    if review.findings:
+        parts.append("## Findings")
+        parts.append("")
+        parts.append("| Severity | Category | Rule | Path | Line | Message |")
+        parts.append("| --- | --- | --- | --- | --- | --- |")
+        for finding in review.findings:
+            parts.append(
+                "| {sev} | {cat} | {rule} | {path} | {line} | {msg} |".format(
+                    sev=finding.severity.value,
+                    cat=finding.category,
+                    rule=finding.rule_id,
+                    path=_shorten_path(to_privacy_path(finding.path)) if finding.path else "",
+                    line=finding.line or "",
+                    msg=_escape(finding.message),
+                )
+            )
+    if not review.findings:
+        parts.append("\n_No findings._")
+    return "\n".join(parts) + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Rich sections
+# ---------------------------------------------------------------------------
+
+
+def _render_header(review: RepositoryReview) -> Panel:
+    counts = review.counts_by_severity()
+    critical = counts[Severity.CRITICAL]
+    high = counts[Severity.HIGH]
+    title_text = f"[bold]Code review:[/bold] {to_privacy_path(review.root)}"
+    if critical:
+        title_text += f"  [critical on red] {critical} critical [/]"
+    if high:
+        title_text += f"  [red] {high} high [/]"
+    return Panel(
+        title_text,
+        border_style="magenta",
+        title="forge review",
+    )
+
+
+def _render_summary(review: RepositoryReview) -> Panel:
+    counts = review.counts_by_severity()
+    by_category = review.counts_by_category()
+    table = Table(
+        title="Counts",
+        title_style="bold cyan",
+        header_style="bold magenta",
+        show_lines=False,
+        expand=True,
+    )
+    table.add_column("Severity")
+    table.add_column("Count", justify="right")
+    for severity in (Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW, Severity.INFO):
+        count = counts.get(severity, 0)
+        table.add_row(
+            TextRenderable(severity.value, style=_SEVERITY_STYLE[severity]),
+            str(count),
+        )
+    cat = Table(
+        title="By category",
+        title_style="bold cyan",
+        header_style="bold magenta",
+        show_lines=False,
+        expand=True,
+    )
+    cat.add_column("Category")
+    cat.add_column("Count", justify="right")
+    for name, count in sorted(by_category.items()):
+        cat.add_row(name, str(count))
+    stats = Table(
+        title="Stats",
+        title_style="bold cyan",
+        header_style="bold magenta",
+        show_lines=False,
+        expand=True,
+    )
+    stats.add_column("Field")
+    stats.add_column("Value")
+    for key, value in review.stats.items():
+        stats.add_row(key, str(value))
+    return Panel(
+        Group(table, TextRenderable(""), cat, TextRenderable(""), stats),
+        title="Summary",
+        border_style="cyan",
+    )
+
+
+def _render_suggestions(suggestions: Iterable[Suggestion]) -> Panel:
+    table = Table(
+        title="Suggested actions",
+        title_style="bold cyan",
+        header_style="bold magenta",
+        show_lines=False,
+        expand=True,
+    )
+    table.add_column("Severity", no_wrap=True)
+    table.add_column("Category", no_wrap=True)
+    table.add_column("Action")
+    table.add_column("Count", justify="right")
+    for suggestion in suggestions:
+        table.add_row(
+            TextRenderable(
+                suggestion.severity.value, style=_SEVERITY_STYLE[suggestion.severity]
+            ),
+            suggestion.category,
+            suggestion.title,
+            str(suggestion.count),
+        )
+    return Panel(table, title="Suggestions", border_style="cyan")
+
+
+def _render_findings(findings: Iterable[Finding], *, full: bool = False) -> Group:
+    # 1. Sort by severity weight descending
+    sorted_findings = sorted(findings, key=lambda f: f.severity.weight, reverse=True)
+
+    # 2. Slice to Top 10 if not full
+    capping_msg = ""
+    if not full and len(sorted_findings) > 10:
+        capping_msg = f" (Top 10 of {len(sorted_findings)} findings shown. Use --full for all)"
+        displayed_findings = sorted_findings[:10]
+    else:
+        displayed_findings = sorted_findings
+
+    # 3. Group by severity and then category
+    by_severity: dict[Severity, dict[str, list[Finding]]] = {}
+    for finding in displayed_findings:
+        by_severity.setdefault(finding.severity, {}).setdefault(finding.category, []).append(finding)
+
+    panels: list = []
+    # Loop over severity in order of weight descending
+    for severity in sorted(by_severity.keys(), key=lambda s: s.weight, reverse=True):
+        sev_style = _SEVERITY_STYLE.get(severity, "white")
+        panels.append(TextRenderable(f"\n[bold {sev_style}]▲ {severity.value.upper()} FINDINGS[/bold {sev_style}]"))
+
+        by_cat = by_severity[severity]
+        for category in sorted(by_cat.keys()):
+            rows = by_cat[category]
+            table = Table(
+                title=f"{category.capitalize()} ({len(rows)})",
+                title_style="bold cyan",
+                header_style="bold magenta",
+                show_lines=True,
+                expand=True,
+            )
+            table.add_column("Rule", no_wrap=True)
+            table.add_column("Path:Line", overflow="fold")
+            table.add_column("Message", overflow="fold")
+            table.add_column("Suggestion", overflow="fold", style="muted")
+
+            for finding in rows:
+                sanitized_path = to_privacy_path(finding.path) if finding.path else ""
+                location = (
+                    f"{_shorten_path(sanitized_path)}:{finding.line}"
+                    if sanitized_path and finding.line
+                    else sanitized_path
+                )
+                table.add_row(
+                    finding.rule_id,
+                    location,
+                    finding.message,
+                    finding.suggestion or "",
+                )
+            panels.append(table)
+
+    header = Panel(
+        TextRenderable(f"[bold cyan]Findings{capping_msg}[/bold cyan]"),
+        border_style="cyan",
+    )
+    return Group(header, *panels)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class TextRenderable:
+    """A small wrapper around :class:`rich.text.Text` that gives us a
+    :meth:`copy` method (Rich's Panel calls ``self.title.copy()`` on
+    non-string titles) without forcing every call site to import
+    ``rich.text``.
+    """
+
+    def __init__(self, text: str, style: str | None = None) -> None:
+        from rich.text import Text
+
+        self._text = Text(text, style=style or "")
+
+    def __rich_console__(self, console: Console, options):
+        yield from console.render(self._text, options)
+
+    def copy(self) -> TextRenderable:
+        return TextRenderable.__new__(TextRenderable)._copy_from(self)
+
+    def _copy_from(self, other: TextRenderable) -> TextRenderable:
+        self._text = other._text.copy()
+        return self
+
+    def __str__(self) -> str:
+        return str(self._text)
+
+
+def _shorten_path(path: str | None) -> str:
+    if path is None:
+        return ""
+    parts = path.split("/")
+    if len(parts) > 4:
+        return "/".join(parts[-3:])
+    return path
+
+
+def _escape(text: str) -> str:
+    return text.replace("|", "\\|").replace("\n", " ")
+
+
+__all__ = [
+    "print_review",
+    "render_review",
+    "review_to_json",
+    "review_to_markdown",
+]

forgecli/review/repository.py

@@ -0,0 +1,131 @@
+"""Top-level repository review.
+
+The :class:`RepositoryReview` is the entry point used by the CLI:
+load a project, run every registered analyzer, and produce a list of
+:class:`Finding` objects + a ranked :class:`Suggestion` list.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+
+from forgecli.review.analyzer import AnalysisContext, Analyzer
+from forgecli.review.analyzers.architecture import ArchitectureAnalyzer
+from forgecli.review.analyzers.complexity import ComplexityAnalyzer
+from forgecli.review.analyzers.dead_code import DeadCodeAnalyzer
+from forgecli.review.analyzers.duplicates import DuplicatesAnalyzer
+from forgecli.review.analyzers.performance import PerformanceAnalyzer
+from forgecli.review.analyzers.security import SecurityAnalyzer
+from forgecli.review.finding import Finding, Severity
+from forgecli.review.suggestions import Suggestion, build_suggestions
+
+
+@dataclass
+class RepositoryReview:
+    """The full report produced for a single repository scan."""
+
+    root: str
+    findings: list[Finding] = field(default_factory=list)
+    suggestions: list[Suggestion] = field(default_factory=list)
+    analyzer_names: list[str] = field(default_factory=list)
+    stats: dict[str, int] = field(default_factory=dict)
+
+    def counts_by_severity(self) -> dict[Severity, int]:
+        out: dict[Severity, int] = {
+            Severity.INFO: 0,
+            Severity.LOW: 0,
+            Severity.MEDIUM: 0,
+            Severity.HIGH: 0,
+            Severity.CRITICAL: 0,
+        }
+        for finding in self.findings:
+            out[finding.severity] += 1
+        return out
+
+    def counts_by_category(self) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for finding in self.findings:
+            out[finding.category] = out.get(finding.category, 0) + 1
+        return out
+
+    @property
+    def is_blocking(self) -> bool:
+        return any(finding.severity.is_blocking for finding in self.findings)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "root": self.root,
+            "stats": self.stats,
+            "analyzer_names": self.analyzer_names,
+            "counts_by_severity": {
+                severity.value: count
+                for severity, count in self.counts_by_severity().items()
+            },
+            "counts_by_category": self.counts_by_category(),
+            "findings": [finding.to_dict() for finding in self.findings],
+            "suggestions": [
+                {
+                    "title": suggestion.title,
+                    "severity": suggestion.severity.value,
+                    "category": suggestion.category,
+                    "count": suggestion.count,
+                    "rationale": suggestion.rationale,
+                    "findings": [finding.to_dict() for finding in suggestion.findings],
+                }
+                for suggestion in self.suggestions
+            ],
+        }
+
+
+def default_analyzers() -> list[Analyzer]:
+    """Return the default analyzer stack in stable order."""
+    return [
+        SecurityAnalyzer(),
+        PerformanceAnalyzer(),
+        ArchitectureAnalyzer(),
+        ComplexityAnalyzer(),
+        DeadCodeAnalyzer(),
+        DuplicatesAnalyzer(),
+    ]
+
+
+def review_repository(
+    root,
+    *,
+    analyzers: Sequence[Analyzer] | None = None,
+    context: AnalysisContext | None = None,
+) -> RepositoryReview:
+    """Run all analyzers on ``root`` and return a :class:`RepositoryReview`."""
+    analyzers = list(analyzers) if analyzers is not None else default_analyzers()
+    if context is None:
+        context = AnalysisContext.load(root)
+
+    findings: list[Finding] = []
+    for analyzer in analyzers:
+        findings.extend(analyzer.run(context))
+    suggestions = build_suggestions(findings)
+
+    counts = {
+        "files": len(context.files),
+        "analyzers": len(analyzers),
+    }
+
+    return RepositoryReview(
+        root=str(context.root),
+        findings=findings,
+        suggestions=suggestions,
+        analyzer_names=[analyzer.name for analyzer in analyzers],
+        stats=counts,
+    )
+
+
+__all__ = [
+    "RepositoryReview",
+    "default_analyzers",
+    "review_repository",
+]
+
+
+# Silence unused-import warnings for symbols only used in some branches.
+_ = Iterable

forgecli/review/suggestions.py

@@ -0,0 +1,98 @@
+"""Suggestions engine.
+
+Turns the raw :class:`Finding` list into a ranked list of
+``Suggestion`` items. The engine doesn't *fix* code; it produces a
+human-readable priority order and groups findings that share a
+root cause.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from forgecli.review.finding import Finding, Severity
+
+# A small map from rule_id -> friendly title for grouping.
+_RULE_TITLES: dict[str, str] = {
+    "SEC001": "Hard-coded AWS access key",
+    "SEC002": "Hard-coded API key/secret/password",
+    "SEC003": "PEM private key in source",
+    "SEC004": "Hard-coded Slack/bot token",
+    "SEC010": "Avoid os.system",
+    "SEC011": "Avoid os.popen",
+    "SEC012": "Avoid subprocess.call (no shell=True)",
+    "SEC013": "Avoid subprocess.Popen(shell=True)",
+    "SEC014": "Avoid eval()",
+    "SEC015": "Avoid exec()",
+    "SEC016": "Avoid compile()",
+    "SEC017": "Avoid pickle.load()",
+    "SEC018": "Avoid pickle.loads()",
+    "SEC019": "Avoid marshal.load()",
+    "SEC020": "Avoid marshal.loads()",
+    "SEC021": "Use a strong hash",
+    "SEC022": "Don't use assert for runtime checks",
+    "PERF001": "Avoid blocking I/O in async code",
+    "PERF002": "Avoid sync sleep / HTTP in async code",
+    "PERF010": "Deeply nested loops",
+    "ARCH001": "Layer dependency direction",
+    "ARCH002": "Circular import between layers",
+    "ARCH003": "Forbidden import",
+    "CPLX001": "Function too long",
+    "CPLX002": "Function has too many parameters",
+    "CPLX003": "Function has high cyclomatic complexity",
+    "DEAD001": "Unused private symbol",
+    "DUP001": "Duplicate code block",
+}
+
+
+@dataclass
+class Suggestion:
+    """A grouped, prioritized action item for the user."""
+
+    title: str
+    severity: Severity
+    category: str
+    findings: list[Finding] = field(default_factory=list)
+    rationale: str = ""
+
+    @property
+    def count(self) -> int:
+        return len(self.findings)
+
+
+def build_suggestions(findings: Iterable[Finding]) -> list[Suggestion]:
+    """Group findings by rule and rank by severity + count."""
+    grouped: dict[str, list[Finding]] = defaultdict(list)
+    for finding in findings:
+        grouped[finding.rule_id].append(finding)
+
+    suggestions: list[Suggestion] = []
+    for rule_id, bucket in grouped.items():
+        worst = max(bucket, key=lambda f: f.severity.weight)
+        suggestions.append(
+            Suggestion(
+                title=_RULE_TITLES.get(rule_id, rule_id),
+                severity=worst.severity,
+                category=worst.category,
+                findings=bucket,
+                rationale=_rationale_for(rule_id, bucket),
+            )
+        )
+    suggestions.sort(
+        key=lambda s: (-s.severity.weight, -s.count, s.title),
+    )
+    return suggestions
+
+
+def _rationale_for(rule_id: str, bucket: list[Finding]) -> str:
+    """Return a short rationale for the suggestion."""
+    if len(bucket) == 1:
+        return f"1 occurrence of {rule_id}."
+    files = {finding.path for finding in bucket if finding.path}
+    file_count = len(files)
+    return f"{len(bucket)} occurrences across {file_count} file(s)."
+
+
+__all__ = ["Suggestion", "build_suggestions"]

forgecli/runtime/__init__.py

@@ -0,0 +1,6 @@
+"""Runtime preparation for AI wrapper commands."""
+
+from forgecli.runtime.prepare import PreparedRuntime, prepare_runtime_sync
+from forgecli.runtime.wrappers import WRAPPERS, launch_wrapper
+
+__all__ = ["WRAPPERS", "PreparedRuntime", "launch_wrapper", "prepare_runtime_sync"]

forgecli/runtime/cache_store.py

@@ -0,0 +1,77 @@
+"""Disk-backed cache for prepared runtime context."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from forgecli.utils.paths import ProjectPaths
+
+_CACHE_TTL_SECONDS = 3600.0
+
+
+@dataclass(frozen=True)
+class CachedRuntime:
+    context_summary: str
+    context_file: str
+    node_count: int
+    edge_count: int
+    created_at: float
+
+
+def _cache_dir() -> Path:
+    path = ProjectPaths.from_env().cache_dir / "runtime"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def repo_fingerprint(root: Path) -> str:
+    """Fingerprint a repo for cache invalidation (git HEAD + shallow layout)."""
+    head = ""
+    git_head = root / ".git" / "HEAD"
+    if git_head.is_file():
+        head = git_head.read_text(encoding="utf-8", errors="replace").strip()
+
+    layout_sig = "0"
+    try:
+        names = sorted(
+            p.name for p in root.iterdir() if not p.name.startswith(".")
+        )[:48]
+        layout_sig = ",".join(names)
+    except OSError:
+        pass
+
+    payload = f"{root.resolve()}|{head}|{layout_sig}"
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:24]
+
+
+def load_runtime_cache(fingerprint: str) -> CachedRuntime | None:
+    path = _cache_dir() / f"{fingerprint}.json"
+    if not path.is_file():
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        created_at = float(payload.get("created_at", 0))
+        if time.time() - created_at > _CACHE_TTL_SECONDS:
+            path.unlink(missing_ok=True)
+            return None
+        context_file = Path(str(payload["context_file"]))
+        if not context_file.is_file():
+            return None
+        return CachedRuntime(
+            context_summary=str(payload["context_summary"]),
+            context_file=str(context_file),
+            node_count=int(payload.get("node_count", 0)),
+            edge_count=int(payload.get("edge_count", 0)),
+            created_at=created_at,
+        )
+    except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError):
+        return None
+
+
+def save_runtime_cache(fingerprint: str, runtime: CachedRuntime) -> None:
+    path = _cache_dir() / f"{fingerprint}.json"
+    path.write_text(json.dumps(asdict(runtime), indent=2), encoding="utf-8")