codegraph-engine 3.0.0__2-py3-none-any.whl

codegraph/cli_output.py

@@ -0,0 +1,205 @@
+"""Centralized cross-platform CLI output utility for Windows/macOS/Linux encoding safety.
+
+Guarantees:
+- Never assumes stdout/stderr is UTF-8 (safe on Windows cp1252, cp437, ASCII, and redirected pipes).
+- Preserves rich Unicode symbols (`✓`, `✗`, `⚠`, `↻`, `(•)`) when the target stream supports them.
+- Automatically degrades to deterministic ASCII markers (`[OK]`, `[ERROR]`, `[WARN]`, `[REPAIRED]`, `(*)`)
+  when the stream encoding does not support Unicode box/status glyphs.
+- Ensures `--json` output is strictly machine-readable and never contains decorative Unicode glyphs.
+"""
+from __future__ import annotations
+
+import codecs
+import os
+import sys
+from dataclasses import dataclass
+from typing import Any, TextIO
+
+import typer
+
+_PROBE_GLYPHS = "✓✗⚠↻•→↓─—–├──└──│📄📞🌐🧪💾⚠️✅❌"
+
+# Ordered replacements so multi-char patterns (e.g. "(•)") are replaced before single chars ("•")
+_UNICODE_TO_ASCII_MAP: tuple[tuple[str, str], ...] = (
+    ("(•)", "(*)"),
+    ("├── ", "|-- "),
+    ("└── ", "\\-- "),
+    ("├──", "|--"),
+    ("└──", "\\--"),
+    ("├─", "|-"),
+    ("└─", "\\-"),
+    ("│", "|"),
+    ("─", "-"),
+    ("✓", "[OK]"),
+    ("✗", "[ERROR]"),
+    ("⚠", "[WARN]"),
+    ("↻", "[REPAIRED]"),
+    ("⚠️", "[WARN]"),
+    ("✅", "[OK]"),
+    ("❌", "[ERROR]"),
+    ("📄", "[FILE]"),
+    ("📞", "[CALLER]"),
+    ("🌐", "[ROUTE]"),
+    ("🧪", "[TEST]"),
+    ("💾", "[DB]"),
+    ("•", "*"),
+    ("→", "->"),
+    ("↓", "v"),
+    ("—", "--"),
+    ("–", "-"),
+)
+
+
+@dataclass(frozen=True)
+class CliSymbols:
+    """Encoding-aware CLI status symbols."""
+
+    unicode_enabled: bool
+    ok: str
+    error: str
+    warn: str
+    repair: str
+    radio_on: str
+    radio_off: str
+    arrow_right: str
+    arrow_down: str
+
+
+UNICODE_SYMBOLS = CliSymbols(
+    unicode_enabled=True,
+    ok="✓",
+    error="✗",
+    warn="⚠",
+    repair="↻",
+    radio_on="(•)",
+    radio_off="( )",
+    arrow_right="→",
+    arrow_down="↓",
+)
+
+ASCII_SYMBOLS = CliSymbols(
+    unicode_enabled=False,
+    ok="[OK]",
+    error="[ERROR]",
+    warn="[WARN]",
+    repair="[REPAIRED]",
+    radio_on="(*)",
+    radio_off="( )",
+    arrow_right="->",
+    arrow_down="v",
+)
+
+
+def detect_stream_encoding(stream: Any = None) -> str:
+    """Safely detect the character encoding of `stream` (defaults to `sys.stdout`)."""
+    target = stream if stream is not None else sys.stdout
+    enc = getattr(target, "encoding", None)
+    if not enc or not isinstance(enc, str):
+        return "ascii"
+    try:
+        info = codecs.lookup(enc)
+        return info.name
+    except LookupError:
+        return "ascii"
+
+
+def supports_unicode(
+    stream: Any = None,
+    *,
+    unicode_override: bool | None = None,
+) -> bool:
+    """Return True if `stream` can encode all CodeGraph Unicode status glyphs without error."""
+    if unicode_override is not None:
+        return unicode_override
+
+    env_ascii = os.environ.get("CODEGRAPH_ASCII_OUTPUT", "").strip().lower()
+    if env_ascii in ("1", "true", "yes", "on"):
+        return False
+
+    env_unicode = os.environ.get("CODEGRAPH_UNICODE_OUTPUT", "").strip().lower()
+    if env_unicode in ("1", "true", "yes", "on"):
+        return True
+    if env_unicode in ("0", "false", "no", "off"):
+        return False
+
+    enc = detect_stream_encoding(stream)
+    try:
+        _PROBE_GLYPHS.encode(enc, errors="strict")
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+def get_cli_symbols(
+    stream: Any = None,
+    *,
+    unicode_override: bool | None = None,
+) -> CliSymbols:
+    """Return `UNICODE_SYMBOLS` when supported by `stream`, else `ASCII_SYMBOLS`."""
+    if supports_unicode(stream, unicode_override=unicode_override):
+        return UNICODE_SYMBOLS
+    return ASCII_SYMBOLS
+
+
+def sanitize_text_for_stream(
+    text: str,
+    stream: Any = None,
+    *,
+    unicode_override: bool | None = None,
+) -> str:
+    """Format `text` safely for `stream`, converting decorative Unicode when unsupported."""
+    if not text:
+        return text
+
+    target = stream if stream is not None else sys.stdout
+    use_unicode = supports_unicode(target, unicode_override=unicode_override)
+    out = text
+    if not use_unicode:
+        for uni_tok, ascii_tok in _UNICODE_TO_ASCII_MAP:
+            if uni_tok in out:
+                out = out.replace(uni_tok, ascii_tok)
+
+    enc = detect_stream_encoding(target)
+    try:
+        out.encode(enc, errors="strict")
+        return out
+    except (UnicodeEncodeError, LookupError):
+        # Replace any remaining unencodable glyphs cleanly so write() never raises UnicodeEncodeError
+        for uni_tok, ascii_tok in _UNICODE_TO_ASCII_MAP:
+            if uni_tok in out:
+                out = out.replace(uni_tok, ascii_tok)
+        return out.encode(enc, errors="replace").decode(enc, errors="replace")
+
+
+def sanitize_json_string(raw_json: str, stream: Any = None) -> str:
+    """Ensure machine-readable JSON output never crashes non-UTF-8 streams."""
+    enc = detect_stream_encoding(stream)
+    try:
+        raw_json.encode(enc, errors="strict")
+        return raw_json
+    except (UnicodeEncodeError, LookupError):
+        # Escape non-ASCII characters using standard JSON \uXXXX escapes
+        return raw_json.encode("unicode_escape").decode("ascii")
+
+
+def cli_echo(
+    message: str = "",
+    *,
+    nl: bool = True,
+    err: bool = False,
+    json_mode: bool = False,
+    stream: TextIO | None = None,
+    unicode_override: bool | None = None,
+) -> None:
+    """Centralized safe CLI output function replacing raw `typer.echo`."""
+    target = stream if stream is not None else (sys.stderr if err else sys.stdout)
+    if json_mode:
+        safe_msg = sanitize_json_string(str(message), target)
+    else:
+        safe_msg = sanitize_text_for_stream(str(message), target, unicode_override=unicode_override)
+
+    if stream is not None:
+        stream.write(safe_msg + ("\n" if nl else ""))
+        stream.flush()
+    else:
+        typer.echo(safe_msg, nl=nl, err=err)

codegraph/config.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class Settings(BaseModel):
+    """Runtime settings. Environment values deliberately never include API keys."""
+
+    repository: Path | None = None
+    db_path: Path | None = None
+    max_file_size: int = Field(default=1_000_000, ge=1)
+    max_read_bytes: int = Field(default=256_000, ge=1024)
+    max_results: int = Field(default=10, ge=1, le=100)
+    max_context: int = Field(default=20_000, ge=100)
+    max_tool_calls: int = Field(default=12, ge=1)
+    exclude: tuple[str, ...] = ()
+    resource_profile: str = "BALANCED"
+    max_interactive_workers: int = Field(default=2, ge=1)
+    max_background_workers: int = Field(default=1, ge=0)
+    max_memory_mb: int = Field(default=1024, ge=128)
+    max_graph_nodes: int = Field(default=300, ge=10)
+    max_graph_edges: int = Field(default=1200, ge=10)
+    max_git_commits: int = Field(default=15, ge=1)
+    background_indexing: bool = True
+    debounce_ms: int = Field(default=500, ge=50)
+
+    @classmethod
+    def from_env(cls) -> Settings:
+        repo = os.getenv("CODEGRAPH_REPOSITORY")
+        db = os.getenv("CODEGRAPH_DB_PATH")
+        return cls(
+            repository=Path(repo) if repo else None,
+            db_path=Path(db) if db else None,
+            max_file_size=int(os.getenv("CODEGRAPH_MAX_FILE_SIZE", "1000000")),
+            max_read_bytes=int(os.getenv("CODEGRAPH_MAX_READ_BYTES", "256000")),
+            max_context=int(os.getenv("CODEGRAPH_MAX_CONTEXT", "20000")),
+            max_tool_calls=int(os.getenv("CODEGRAPH_MAX_TOOL_CALLS", "12")),
+            resource_profile=os.getenv("CODEGRAPH_RESOURCE_PROFILE", "BALANCED"),
+            max_memory_mb=int(os.getenv("CODEGRAPH_MAX_MEMORY_MB", "1024")),
+            background_indexing=os.getenv("CODEGRAPH_BACKGROUND_INDEXING", "true").lower() in ("true", "1"),
+            debounce_ms=int(os.getenv("CODEGRAPH_DEBOUNCE_MS", "500")),
+        )

codegraph/constraints.py

@@ -0,0 +1,238 @@
+"""Constraint Guard for CodeGraph MCP v2.1.
+
+Enforces deterministic hard constraints across every retrieval and compilation stage:
+- Explicit excluded symbols, hierarchical descendants, and canonical IDs
+- Explicit excluded files, directories, and path-component matching
+- Excluded modules and namespaces
+- Scope paths and scope modules
+- Repository and security boundary protection
+
+Architectural Invariant:
+  Hard constraints are HARD FILTERS, never ranking penalties.
+  No entity violating a hard constraint may participate in candidate generation,
+  graph traversal, ranking, coverage, or appear in the final ContextPacket.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath
+from typing import Any
+
+
+def _normalize_path(p: str | None) -> str:
+    if not p:
+        return ""
+    norm = p.replace("\\", "/").strip()
+    while norm.startswith("./"):
+        norm = norm[2:]
+    return norm.strip("/")
+
+
+def _is_hierarchical_symbol_match(sym: str, excl: str) -> bool:
+    """Return True if `sym` matches `excl` or is a hierarchical descendant of `excl`.
+
+    Examples:
+      - excl="AuthService", sym="AuthService" -> True
+      - excl="AuthService", sym="AuthService.login" -> True
+      - excl="AuthService", sym="auth.AuthService.login" -> True
+      - excl="AuthService", sym="AuthServiceHelper" -> False (distinct symbol)
+      - excl="AuthService", sym="UserAuthService" -> False (distinct symbol)
+    """
+    if not sym or not excl:
+        return False
+    if sym == excl:
+        return True
+    if sym.startswith(f"{excl}.") or sym.startswith(f"{excl}:"):
+        return True
+
+    # Check dot-separated hierarchy components
+    parts = sym.split(".")
+    for part in parts:
+        if part == excl:
+            return True
+
+    # Check colon-separated hierarchy components (e.g. file:Class.method)
+    col_parts = sym.split(":")
+    for part in col_parts:
+        if part == excl or part.startswith(f"{excl}."):
+            return True
+    return False
+
+
+@dataclass(frozen=True)
+class ConstraintGuard:
+    """Central hard-constraint enforcement guard."""
+
+    excluded_symbols: frozenset[str] = field(default_factory=frozenset)
+    excluded_files: frozenset[str] = field(default_factory=frozenset)
+    excluded_modules: frozenset[str] = field(default_factory=frozenset)
+    scope_paths: frozenset[str] = field(default_factory=frozenset)
+    scope_modules: frozenset[str] = field(default_factory=frozenset)
+
+    @classmethod
+    def from_task_spec(cls, task_spec: Any) -> ConstraintGuard:
+        """Construct a ConstraintGuard from a TaskSpec or dictionary."""
+        if not task_spec:
+            return cls()
+
+        excl_syms: set[str] = set()
+        excl_files: set[str] = set()
+        excl_mods: set[str] = set()
+
+        raw_exclusions = getattr(task_spec, "exclusions", ()) or ()
+        if isinstance(raw_exclusions, (list, tuple, set)):
+            for item in raw_exclusions:
+                if not item:
+                    continue
+                s = str(item).strip()
+                if "/" in s or "\\" in s or s.endswith(".py") or s.endswith(".ts") or s.endswith(".js"):
+                    excl_files.add(_normalize_path(s))
+                else:
+                    excl_syms.add(s)
+
+        raw_scope_paths = getattr(task_spec, "scope_paths", ()) or ()
+        scope_p = {_normalize_path(str(p)) for p in raw_scope_paths if p}
+
+        raw_scope_mods = getattr(task_spec, "scope_modules", ()) or ()
+        scope_m = {str(m).strip() for m in raw_scope_mods if m}
+
+        return cls(
+            excluded_symbols=frozenset(excl_syms),
+            excluded_files=frozenset(excl_files),
+            excluded_modules=frozenset(excl_mods),
+            scope_paths=frozenset(scope_p),
+            scope_modules=frozenset(scope_m),
+        )
+
+    def allows_symbol(self, symbol: str | None) -> bool:
+        """Check if symbol is permitted under exclusion and scope constraints."""
+        if not symbol:
+            return True
+        s = symbol.strip()
+        for excl in self.excluded_symbols:
+            if _is_hierarchical_symbol_match(s, excl):
+                return False
+        return True
+
+    def allows_canonical_id(self, canonical_id: str | None) -> bool:
+        """Check if canonical symbol ID is permitted."""
+        if not canonical_id:
+            return True
+        cid = canonical_id.strip()
+        if not self.allows_symbol(cid):
+            return False
+        # If canonical_id encodes a file path, verify file is allowed
+        if ":" in cid:
+            path_part = cid.split(":", 1)[0]
+            if "/" in path_part or path_part.endswith((".py", ".ts", ".js")):
+                if not self.allows_file(path_part):
+                    return False
+        return True
+
+    def allows_file(self, file_path: str | None) -> bool:
+        """Check if file path is permitted under exclusion, path-component, and scope constraints."""
+        if not file_path:
+            return True
+        path_norm = _normalize_path(file_path)
+
+        # 1. Security check: reject path traversal
+        path_obj = PurePosixPath(path_norm)
+        if ".." in path_obj.parts:
+            return False
+
+        # 2. Hard exclusions
+        for excl in self.excluded_files:
+            excl_norm = _normalize_path(excl)
+            if not excl_norm:
+                continue
+            # Exact path match
+            if path_norm == excl_norm:
+                return False
+            # Directory prefix match (e.g. excl="src/admin_panel", path="src/admin_panel/views.py")
+            if path_norm.startswith(f"{excl_norm}/"):
+                return False
+            # Suffix / component match if exclusion is just a filename
+            if "/" not in excl_norm and path_obj.name == excl_norm:
+                return False
+
+        # 3. Scope constraints (if scope paths specified, path must match at least one)
+        if self.scope_paths:
+            in_scope = False
+            for sp in self.scope_paths:
+                if path_norm == sp or path_norm.startswith(f"{sp}/"):
+                    in_scope = True
+                    break
+            if not in_scope:
+                return False
+
+        return True
+
+    def allows_module(self, module_name: str | None) -> bool:
+        """Check if module is permitted."""
+        if not module_name:
+            return True
+        m = module_name.strip()
+        for excl in self.excluded_modules:
+            if m == excl or m.startswith(f"{excl}."):
+                return False
+        if self.scope_modules:
+            in_scope = False
+            for sm in self.scope_modules:
+                if m == sm or m.startswith(f"{sm}."):
+                    in_scope = True
+                    break
+            if not in_scope:
+                return False
+        return True
+
+    def allows_relationship(
+        self,
+        source_id: str | None,
+        rel_type: str | None,
+        target_id: str | None,
+    ) -> bool:
+        """Check if relationship endpoints are permitted."""
+        if source_id and not self.allows_canonical_id(source_id) and not self.allows_symbol(source_id):
+            return False
+        if target_id and not self.allows_canonical_id(target_id) and not self.allows_symbol(target_id):
+            return False
+        return True
+
+    def allows_test(
+        self,
+        test_file: str | None,
+        test_symbol: str | None = None,
+    ) -> bool:
+        """Check if test artifact is permitted."""
+        if test_file and not self.allows_file(test_file):
+            return False
+        if test_symbol and not self.allows_symbol(test_symbol):
+            return False
+        return True
+
+    def allows_endpoint(
+        self,
+        route_path: str | None,
+        handler_name: str | None = None,
+        file_path: str | None = None,
+    ) -> bool:
+        """Check if framework route is permitted."""
+        if file_path and not self.allows_file(file_path):
+            return False
+        if handler_name and not self.allows_symbol(handler_name):
+            return False
+        if route_path and route_path in self.excluded_symbols:
+            return False
+        return True
+
+    def allows_evidence(
+        self,
+        file_path: str | None,
+        symbol: str | None = None,
+    ) -> bool:
+        """Check if evidence item is permitted."""
+        if file_path and not self.allows_file(file_path):
+            return False
+        if symbol and not self.allows_symbol(symbol):
+            return False
+        return True