oneport-debug-core 0.1.0__py3-none-any.whl

oneport_debug_core/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024 OnePort Debug Contributors
+"""oneport-debug-core: Shared foundation for all oneport-debug enterprise tools."""
+
+from oneport_debug_core.models.rca import RCAResult, CodeLocation, Evidence
+from oneport_debug_core.engine.orchestrator import Orchestrator
+from oneport_debug_core.config.settings import AppConfig, load_config
+
+__all__ = [
+    "RCAResult",
+    "CodeLocation",
+    "Evidence",
+    "Orchestrator",
+    "AppConfig",
+    "load_config",
+]
+
+__version__ = "0.1.0"

oneport_debug_core/cli/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024 OnePort Debug Contributors
+from oneport_debug_core.cli.output import print_rca, print_error, print_success, print_step, console
+
+__all__ = ["print_rca", "print_error", "print_success", "print_step", "console"]

oneport_debug_core/cli/output.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024 OnePort Debug Contributors
+"""
+Shared Rich-based terminal output utilities.
+All 5 CLI tools use these to produce consistent, readable output.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.syntax import Syntax
+from rich import box
+
+from oneport_debug_core.models.rca import RCAResult, Severity
+
+console = Console()
+
+
+def ensure_utf8_console() -> None:
+    """
+    Force stdout/stderr to UTF-8 so Unicode glyphs (✔ ✖ → ■ █) used in CLI
+    output don't raise UnicodeEncodeError on Windows consoles that default to
+    cp1252. Idempotent and safe to call from every CLI entry point; a no-op
+    where the stream can't be reconfigured (e.g. under pytest capture).
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (ValueError, OSError):
+            pass
+
+_SEVERITY_COLORS = {
+    Severity.CRITICAL: "bold red",
+    Severity.HIGH: "red",
+    Severity.MEDIUM: "yellow",
+    Severity.LOW: "green",
+}
+
+
+def print_rca(result: RCAResult, output_format: str = "rich") -> None:
+    if output_format == "json":
+        console.print_json(result.model_dump_json(indent=2))
+        return
+
+    color = _SEVERITY_COLORS.get(result.severity, "white")
+    confidence_bar = "█" * int(result.confidence * 10) + "░" * (10 - int(result.confidence * 10))
+
+    console.print()
+    console.print(Panel(
+        f"[bold]{result.summary}[/bold]",
+        title=f"[{color}]■ {result.severity.value.upper()}[/{color}]  oneport-debug/{result.module}",
+        border_style=color,
+    ))
+
+    console.print(f"\n[bold cyan]Root Cause[/bold cyan]\n{result.root_cause}\n")
+    console.print(f"[dim]Confidence:[/dim] [{color}]{confidence_bar}[/{color}] {result.confidence:.0%}  |  Model: {result.model_used}  |  {result.duration_ms}ms\n")
+
+    if result.locations:
+        table = Table(title="Affected Code Locations", box=box.SIMPLE_HEAVY, show_lines=False)
+        table.add_column("Repo", style="cyan", no_wrap=True)
+        table.add_column("File", style="white")
+        table.add_column("Line", style="yellow", justify="right")
+        table.add_column("Function", style="magenta")
+        table.add_column("Blame", style="dim")
+        for loc in result.locations:
+            table.add_row(
+                loc.repo.split("/")[-1],
+                loc.file_path,
+                str(loc.line_number or "—"),
+                loc.function_name or "—",
+                loc.blame_author or "—",
+            )
+        console.print(table)
+
+    if result.recommended_fix:
+        console.print(Panel(
+            result.recommended_fix,
+            title="[bold green]Recommended Fix[/bold green]",
+            border_style="green",
+        ))
+
+    console.print(f"[dim]Generated: {result.generated_at.isoformat()}  |  Trace: {result.trace_id or 'N/A'}[/dim]\n")
+
+
+def print_error(message: str, hint: str | None = None) -> None:
+    console.print(f"[bold red]✖ Error:[/bold red] {message}")
+    if hint:
+        console.print(f"[dim]  Hint: {hint}[/dim]")
+
+
+def print_success(message: str) -> None:
+    console.print(f"[bold green]✔[/bold green] {message}")
+
+
+def print_step(message: str) -> None:
+    console.print(f"[cyan]→[/cyan] {message}")

oneport_debug_core/config/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024 OnePort Debug Contributors
+from oneport_debug_core.config.settings import AppConfig, RunMode, load_config
+
+__all__ = ["AppConfig", "RunMode", "load_config"]

oneport_debug_core/config/settings.py

@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024 OnePort Debug Contributors
+"""
+AppConfig — single source of truth for every oneport-debug tool.
+Loaded from env vars, .env file, or YAML (enterprise config management compatible).
+All secrets are never logged (SecretStr).
+"""
+from __future__ import annotations
+
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import AliasChoices, Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class RunMode(str, Enum):
+    CLOUD = "cloud"     # Anthropic API (default)
+    LOCAL = "local"     # Air-gapped on-prem inference
+    HYBRID = "hybrid"   # Local primary, cloud fallback (with explicit opt-in)
+
+
+class AnthropicSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="ANTHROPIC_")
+    api_key: SecretStr = Field(default=SecretStr(""), description="ANTHROPIC_API_KEY")
+    model: str = Field("claude-sonnet-4-6", description="Model ID")
+    max_tokens: int = Field(4096, ge=256, le=8192)
+    timeout_s: int = Field(60, ge=10)
+
+
+class OpenAISettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="OPENAI_")
+    api_key: SecretStr = Field(default=SecretStr(""), description="OPENAI_API_KEY")
+    model: str = Field("gpt-4o", description="Fallback model ID")
+
+
+class LocalInferenceSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="LOCAL_INFERENCE_")
+    url: str = Field("http://localhost:11434", description="Ollama / vLLM / llama.cpp base URL")
+    model: str = Field("deepseek-coder:6.7b", description="Model name on local server")
+    api_key: SecretStr = Field(default=SecretStr(""), description="Optional bearer token")
+    allowed_hosts: list[str] = Field(
+        default_factory=lambda: ["localhost", "127.0.0.1"],
+        description="Allowlist — enforced by network_enforcer in air-gap mode",
+    )
+    timeout_s: int = Field(120, ge=10)
+
+
+class AuditSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="AUDIT_")
+    log_path: Path = Field(
+        default=Path("/var/log/oneport-debug/audit.jsonl"),
+        description="AUDIT_LOG_PATH — must be write-accessible; use /dev/stdout in containers",
+    )
+    enabled: bool = Field(True, description="Disable only in unit tests")
+    max_file_mb: int = Field(100, ge=1)
+
+
+class AppConfig(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        # Fields below use validation_alias for their documented env vars; without
+        # this, the field NAME (e.g. AppConfig(mode=...)) would be silently ignored.
+        populate_by_name=True,
+    )
+
+    # Each top-level field is read from its documented env var via validation_alias.
+    # The uppercased field name is kept as an alias so load_config()'s YAML overlay
+    # (which sets os.environ[KEY.upper()]) keeps working.
+    mode: RunMode = Field(
+        RunMode.CLOUD,
+        validation_alias=AliasChoices("ONEPORT_MODE", "MODE"),
+        description="ONEPORT_MODE=cloud|local|hybrid",
+    )
+    anthropic: AnthropicSettings = Field(default_factory=AnthropicSettings)
+    openai: OpenAISettings = Field(default_factory=OpenAISettings)
+    local_inference: LocalInferenceSettings = Field(default_factory=LocalInferenceSettings)
+    audit: AuditSettings = Field(default_factory=AuditSettings)
+
+    # Enterprise proxy / certificate settings
+    http_proxy: str | None = Field(
+        None,
+        validation_alias=AliasChoices("HTTPS_PROXY", "HTTP_PROXY"),
+        description="HTTPS_PROXY — for enterprise network egress",
+    )
+    ca_bundle: Path | None = Field(
+        None,
+        validation_alias=AliasChoices("SSL_CERT_FILE", "CA_BUNDLE"),
+        description="SSL_CERT_FILE — corporate CA bundle path",
+    )
+
+    # Telemetry — used by the tool itself (not the code being debugged)
+    otel_endpoint: str | None = Field(
+        None,
+        validation_alias=AliasChoices("OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_ENDPOINT"),
+        description="OTEL_EXPORTER_OTLP_ENDPOINT",
+    )
+    service_name: str = Field(
+        "oneport-debug",
+        validation_alias=AliasChoices("OTEL_SERVICE_NAME", "SERVICE_NAME"),
+        description="OTEL_SERVICE_NAME",
+    )
+
+    @field_validator("mode", mode="before")
+    @classmethod
+    def normalise_mode(cls, v: object) -> str:
+        # The default is a RunMode enum; str(RunMode.CLOUD) is 'RunMode.CLOUD',
+        # which would fail enum validation. Pass enums through by value and only
+        # normalise raw strings coming from env/YAML (e.g. "CLOUD" -> "cloud").
+        if isinstance(v, RunMode):
+            return v.value
+        return str(v).strip().lower()
+
+
+def load_config(yaml_path: Path | None = None) -> AppConfig:
+    """
+    Load AppConfig with optional YAML overlay.
+    YAML keys map 1-to-1 to env var names (snake_case), allowing enterprise
+    config management tools (Ansible, Helm values) to supply configuration
+    without polluting the environment.
+    """
+    overrides: dict = {}
+    if yaml_path and yaml_path.exists():
+        with yaml_path.open() as fh:
+            overrides = yaml.safe_load(fh) or {}
+
+    # Overlay YAML values as env vars so pydantic-settings picks them up
+    for key, value in overrides.items():
+        env_key = key.upper()
+        if env_key not in os.environ:
+            os.environ[env_key] = str(value)
+
+    return AppConfig()

oneport_debug_core/engine/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024 OnePort Debug Contributors
+from oneport_debug_core.engine.orchestrator import Orchestrator
+from oneport_debug_core.engine.context_builder import ContextBuilder
+
+__all__ = ["Orchestrator", "ContextBuilder"]

oneport_debug_core/engine/context_builder.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024 OnePort Debug Contributors
+"""
+ContextBuilder — assembles structured LLM prompts from evidence payloads.
+
+The prompt schema is intentionally strict:
+- JSON-only output is requested (no prose)
+- Required fields are listed so the model never omits them
+- Token budget is controlled (evidence is truncated, not silently dropped)
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from oneport_debug_core.models.rca import Evidence
+
+# Maximum characters of evidence raw data to include per source
+_MAX_EVIDENCE_CHARS = 6000
+_MAX_TOTAL_EVIDENCE_CHARS = 20_000
+
+
+class ContextBuilder:
+    def build_rca_prompt(
+        self,
+        module: str,
+        evidence: list[Evidence],
+        extra: dict[str, Any] | None = None,
+    ) -> str:
+        evidence_block = self._format_evidence(evidence)
+        extra_block = json.dumps(extra or {}, indent=2, default=str)
+
+        return f"""You are an expert enterprise software debugger analyzing a production incident.
+Module: {module}
+
+## Evidence
+{evidence_block}
+
+## Additional Context
+{extra_block}
+
+## Task
+Analyze the evidence and return a JSON object with EXACTLY these fields:
+{{
+  "severity": "critical|high|medium|low",
+  "summary": "One paragraph plain-English summary of what happened",
+  "root_cause": "Precise technical root cause — service, component, and mechanism",
+  "confidence": 0.0–1.0,
+  "locations": [
+    {{
+      "repo": "git remote URL or alias",
+      "file_path": "repo-relative path",
+      "line_number": integer or null,
+      "function_name": "string or null",
+      "commit_sha": "string or null",
+      "blame_author": "string or null"
+    }}
+  ],
+  "recommended_fix": "Step-by-step fix instructions with exact code changes",
+  "affected_services": ["service-a", "service-b"],
+  "tags": {{"env": "prod", "team": "payments"}}
+}}
+
+Rules:
+- Output ONLY the JSON object. No markdown, no explanation, no preamble.
+- If you cannot determine a field, use null — never omit it.
+- locations must reference actual symbols from the evidence; do not hallucinate file paths.
+- confidence = 1.0 only if you have direct log/heap/policy evidence pointing to the exact line.
+"""
+
+    @staticmethod
+    def _format_evidence(evidence: list[Evidence]) -> str:
+        parts: list[str] = []
+        total = 0
+        for ev in evidence:
+            raw_str = json.dumps(ev.raw, indent=2, default=str)
+            if len(raw_str) > _MAX_EVIDENCE_CHARS:
+                raw_str = raw_str[:_MAX_EVIDENCE_CHARS] + "\n... [truncated for token budget]"
+            chunk = f"### Source: {ev.source} (collected {ev.collected_at.isoformat()})\n{raw_str}"
+            if total + len(chunk) > _MAX_TOTAL_EVIDENCE_CHARS:
+                parts.append("... [remaining evidence truncated — token budget exceeded]")
+                break
+            parts.append(chunk)
+            total += len(chunk)
+        return "\n\n".join(parts) if parts else "(no evidence provided)"

oneport_debug_core/engine/orchestrator.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024 OnePort Debug Contributors
+"""
+Orchestrator — the shared analysis engine used by all 5 oneport-debug tools.
+
+Every public method:
+  1. Builds a structured prompt from evidence
+  2. Calls the LLMRouter (cloud or local depending on config)
+  3. Parses the response into a typed RCAResult
+  4. Writes a tamper-evident audit log entry (required for SOX/HIPAA/PCI-DSS)
+  5. Returns the RCAResult to the caller
+
+The orchestrator never crashes on a bad LLM response — it degrades gracefully
+to a low-confidence RCAResult so the CI pipeline / Slack alert still fires.
+"""
+from __future__ import annotations
+
+import json
+import re
+import time
+from typing import Any
+
+import os
+
+import structlog
+
+from oneport_debug_core.config.settings import AppConfig
+from oneport_debug_core.engine.context_builder import ContextBuilder
+from oneport_debug_core.llm.router import LLMRouter
+from oneport_debug_core.llm.base import LLMCompletionOptions
+from oneport_debug_core.models.rca import RCAResult, CodeLocation, Evidence, Severity
+from oneport_debug_core.security.audit_logger import AuditLogger
+from oneport_debug_core.security.secret_scanner import SecretScanner
+
+log = structlog.get_logger(__name__)
+
+
+class Orchestrator:
+    def __init__(self, config: AppConfig) -> None:
+        self._config = config
+        self.llm = LLMRouter(config)
+        self._audit = AuditLogger(config.audit)
+        self._ctx = ContextBuilder()
+        self._scanner = SecretScanner()
+
+    async def analyze(
+        self,
+        module: str,
+        evidence: list[Evidence],
+        extra_context: dict[str, Any] | None = None,
+        trace_id: str | None = None,
+    ) -> RCAResult:
+        """
+        Core entry point. Called by every tool's CLI command.
+        `module` identifies which tool is calling (tracer, apm, iam, cicd, local).
+        """
+        t0 = time.monotonic()
+
+        prompt = self._ctx.build_rca_prompt(
+            module=module,
+            evidence=evidence,
+            extra=extra_context or {},
+        )
+
+        try:
+            # Redact secrets before the prompt leaves the machine
+            scan_result = self._scanner.scan(prompt)
+            if scan_result.findings:
+                log.warning(
+                    "orchestrator.secrets_redacted",
+                    module=module,
+                    findings=[f["type"] for f in scan_result.findings],
+                )
+            safe_prompt = scan_result.redacted_content
+
+            raw = await self.llm.complete(safe_prompt, LLMCompletionOptions(temperature=0.05, max_tokens=4000))
+            result = self._parse_rca(raw, module, evidence, trace_id)
+        except Exception as err:
+            log.error("orchestrator.llm_failed", module=module, error=str(err))
+            result = self._degraded_rca(module, evidence, trace_id, reason=str(err))
+
+        result.duration_ms = int((time.monotonic() - t0) * 1000)
+        result.model_used = self.llm.active_provider
+
+        await self._audit.record(
+            action="rca_generated",
+            module=module,
+            provider=self.llm.active_provider,
+            mode=str(self._config.mode.value),
+            duration_ms=result.duration_ms,
+            confidence=result.confidence,
+            trace_id=trace_id,
+            secrets_redacted=len(scan_result.findings) if "scan_result" in dir() else 0,
+        )
+
+        return result
+
+    # ------------------------------------------------------------------ #
+    # Private helpers                                                       #
+    # ------------------------------------------------------------------ #
+
+    def _parse_rca(
+        self,
+        raw: str,
+        module: str,
+        evidence: list[Evidence],
+        trace_id: str | None,
+    ) -> RCAResult:
+        json_str = self._extract_json(raw)
+        try:
+            obj = json.loads(json_str)
+        except json.JSONDecodeError:
+            log.warning("orchestrator.json_parse_failed", raw_preview=raw[:300])
+            return self._degraded_rca(module, evidence, trace_id, reason="Model returned non-JSON")
+
+        locations = [
+            CodeLocation(
+                repo=str(loc.get("repo", "unknown")),
+                file_path=str(loc.get("file_path", "unknown")),
+                line_number=loc.get("line_number"),
+                function_name=loc.get("function_name"),
+                commit_sha=loc.get("commit_sha"),
+                blame_author=loc.get("blame_author"),
+            )
+            for loc in (obj.get("locations") or [])
+            if isinstance(loc, dict)
+        ]
+
+        return RCAResult(
+            module=module,
+            trace_id=trace_id,
+            severity=self._safe_severity(obj.get("severity", "medium")),
+            summary=str(obj.get("summary", "No summary returned.")),
+            root_cause=str(obj.get("root_cause", "Unable to determine root cause.")),
+            confidence=obj.get("confidence", 0.3),
+            locations=locations,
+            recommended_fix=obj.get("recommended_fix"),
+            evidence=evidence,
+            affected_services=obj.get("affected_services", []),
+            tags=obj.get("tags", {}),
+        )
+
+    @staticmethod
+    def _degraded_rca(
+        module: str,
+        evidence: list[Evidence],
+        trace_id: str | None,
+        reason: str,
+    ) -> RCAResult:
+        return RCAResult(
+            module=module,
+            trace_id=trace_id,
+            severity=Severity.LOW,
+            summary=f"Analysis degraded: {reason}",
+            root_cause=reason,
+            confidence=0.05,
+            evidence=evidence,
+        )
+
+    @staticmethod
+    def _extract_json(raw: str) -> str:
+        """Strip markdown fences and extract the outermost JSON object."""
+        fence = re.search(r"```(?:json)?\s*([\s\S]*?)```", raw, re.IGNORECASE)
+        if fence:
+            return fence.group(1).strip()
+        first, last = raw.find("{"), raw.rfind("}")
+        if first != -1 and last > first:
+            return raw[first : last + 1]
+        return raw
+
+    @staticmethod
+    def _safe_severity(v: Any) -> Severity:
+        try:
+            return Severity(str(v).lower())
+        except ValueError:
+            return Severity.MEDIUM

oneport_debug_core/git/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024 OnePort Debug Contributors
+from oneport_debug_core.git.multi_repo_client import MultiRepoClient
+from oneport_debug_core.git.diff_utils import parse_unified_diff, added_lines, line_to_function
+
+__all__ = ["MultiRepoClient", "parse_unified_diff", "added_lines", "line_to_function"]

oneport_debug_core/git/diff_utils.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024 OnePort Debug Contributors
+"""Unified diff parser and line-number mapper used by tracer and cicd modules."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class DiffHunk:
+    file_path: str
+    old_start: int
+    new_start: int
+    lines: list[str]
+
+
+def parse_unified_diff(diff_text: str) -> list[DiffHunk]:
+    """Parse a unified diff into structured hunks."""
+    hunks: list[DiffHunk] = []
+    current_file = ""
+    hunk_header = re.compile(r"^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+
+    for line in diff_text.splitlines():
+        if line.startswith("+++ b/"):
+            current_file = line[6:]
+        elif m := hunk_header.match(line):
+            hunks.append(DiffHunk(
+                file_path=current_file,
+                old_start=int(m.group(1)),
+                new_start=int(m.group(2)),
+                lines=[],
+            ))
+        elif hunks:
+            hunks[-1].lines.append(line)
+
+    return hunks
+
+
+def added_lines(hunks: list[DiffHunk], file_path: str) -> list[int]:
+    """Return new line numbers of added (+) lines for a given file."""
+    result: list[int] = []
+    for hunk in hunks:
+        if hunk.file_path != file_path:
+            continue
+        current_line = hunk.new_start
+        for line in hunk.lines:
+            if line.startswith("+"):
+                result.append(current_line)
+                current_line += 1
+            elif not line.startswith("-"):
+                current_line += 1
+    return result
+
+
+def line_to_function(source: str, line_number: int) -> str | None:
+    """
+    Heuristic: walk backwards from line_number to find the enclosing
+    function/method definition. Works for Python, Java, Go, JS/TS, Kotlin.
+    """
+    fn_patterns = [
+        re.compile(r"^\s*(?:async\s+)?def\s+(\w+)"),          # Python
+        re.compile(r"^\s*(?:public|private|protected|static|\s)*\w+\s+(\w+)\s*\("),  # Java/Kotlin
+        re.compile(r"^\s*func(?:\s+\(\w+\s+\*?\w+\))?\s+(\w+)"),  # Go
+        re.compile(r"^\s*(?:async\s+)?(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\()"),  # JS/TS
+    ]
+    lines = source.splitlines()
+    for i in range(min(line_number - 1, len(lines) - 1), -1, -1):
+        for pat in fn_patterns:
+            m = pat.match(lines[i])
+            if m:
+                return next(g for g in m.groups() if g)
+    return None