codedebrief 0.11.0__py3-none-any.whl

codedebrief/config.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import fnmatch
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - Python 3.10
+    import tomli as tomllib
+
+DEFAULT_EXCLUDES = [
+    "**/__generated__/**",
+    "**/*.min.js",
+    "**/*.gen.*",
+    "**/*.generated.*",
+    "**/*.pb.*",
+    "**/*.d.ts",
+]
+
+DEFAULT_EXCLUDE_DIRS = [
+    ".angular",
+    ".aws-sam",
+    ".bundle",
+    ".cache",
+    ".expo",
+    ".git",
+    ".gradle",
+    ".hg",
+    ".codedebrief",
+    ".mypy_cache",
+    ".next",
+    ".nox",
+    ".nuxt",
+    ".parcel-cache",
+    ".pnpm-store",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".serverless",
+    ".svn",
+    ".svelte-kit",
+    ".terraform",
+    ".temp",
+    ".tox",
+    ".turbo",
+    ".tmp",
+    ".venv",
+    ".venv-*",
+    ".vite",
+    ".yarn",
+    "__generated__",
+    "__pycache__",
+    "bower_components",
+    "build",
+    "cdk.out",
+    "coverage",
+    "DerivedData",
+    "dist",
+    "env",
+    "graphify-out",
+    "htmlcov",
+    "jspm_packages",
+    "codedebrief-out",
+    "logs",
+    "node_modules",
+    "out",
+    "Pods",
+    "target",
+    "temp",
+    "tmp",
+    "vendor",
+    "venv",
+    "*.egg-info",
+]
+
+BUILTIN_PROFILES = ("self", "project")
+
+
+@dataclass(slots=True)
+class CodeDebriefConfig:
+    source_roots: list[str] = field(default_factory=lambda: ["."])
+    exclude: list[str] = field(default_factory=lambda: list(DEFAULT_EXCLUDES))
+    exclude_dirs: list[str] = field(default_factory=lambda: list(DEFAULT_EXCLUDE_DIRS))
+    include_public_functions: bool = True
+    max_call_depth: int = 4
+    output_dir: str = "codedebrief-out"
+    self_exclude: bool = True
+    entrypoint_include: list[str] = field(default_factory=list)
+    entrypoint_exclude: list[str] = field(default_factory=list)
+    # Named macro-parts of the codebase, e.g. {"backend": ["backend/**"], "edge": ["edge/**"]}.
+    scopes: dict[str, list[str]] = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, root: Path, profile: str | None = None) -> CodeDebriefConfig:
+        config = cls()
+        config_path = root / "codedebrief.toml"
+        if config_path.exists():
+            payload = tomllib.loads(config_path.read_text(encoding="utf-8"))
+            section = payload.get("codedebrief", {})
+            config.source_roots = list(section.get("source_roots", config.source_roots))
+            config.exclude.extend(section.get("exclude", []))
+            config.exclude_dirs.extend(section.get("exclude_dirs", []))
+            config.include_public_functions = bool(
+                section.get("include_public_functions", config.include_public_functions)
+            )
+            config.max_call_depth = int(section.get("max_call_depth", config.max_call_depth))
+            config.output_dir = str(section.get("output_dir", config.output_dir))
+            config.self_exclude = bool(section.get("self_exclude", config.self_exclude))
+            entrypoints = section.get("entrypoints", {})
+            config.entrypoint_include = list(entrypoints.get("include", []))
+            config.entrypoint_exclude = list(entrypoints.get("exclude", []))
+            config.scopes = {
+                str(name): [str(pattern) for pattern in patterns]
+                for name, patterns in section.get("scopes", {}).items()
+            }
+
+        if profile is not None:
+            config = _apply_profile(config, profile)
+
+        ignore_path = root / ".codedebriefignore"
+        if ignore_path.exists():
+            for raw_line in ignore_path.read_text(encoding="utf-8").splitlines():
+                line = raw_line.strip()
+                if line and not line.startswith("#"):
+                    config.exclude.append(_normalize_pattern(line))
+        return config
+
+    def is_excluded(self, relative_path: str) -> bool:
+        normalized = relative_path.replace("\\", "/")
+        return any(
+            fnmatch.fnmatch(normalized, pattern)
+            or fnmatch.fnmatch("/" + normalized, pattern)
+            or _directory_pattern_matches(normalized, pattern)
+            for pattern in self.exclude
+        )
+
+    def is_excluded_dir(self, relative_path: str) -> bool:
+        normalized = relative_path.replace("\\", "/").strip("/")
+        if not normalized:
+            return False
+        name = normalized.rsplit("/", 1)[-1]
+        return any(
+            _directory_name_or_path_matches(normalized, name, pattern)
+            for pattern in self.exclude_dirs
+        )
+
+    def entrypoint_override(self, symbol: str) -> bool | None:
+        if any(fnmatch.fnmatch(symbol, item) for item in self.entrypoint_exclude):
+            return False
+        if any(fnmatch.fnmatch(symbol, item) for item in self.entrypoint_include):
+            return True
+        return None
+
+    def scopes_for(self, relative_path: str) -> list[str]:
+        """The macro-part(s) a file belongs to.
+
+        With declared scopes, returns every named scope whose globs match. Otherwise the
+        top-level directory is the inferred scope, splitting a codebase into
+        backend/frontend/infra-style parts out of the box.
+        """
+        normalized = relative_path.replace("\\", "/")
+        if self.scopes:
+            return sorted(
+                name
+                for name, patterns in self.scopes.items()
+                if any(_scope_match(normalized, pattern) for pattern in patterns)
+            )
+        head, sep, _ = normalized.partition("/")
+        return [head] if sep else []
+
+
+def _apply_profile(config: CodeDebriefConfig, profile: str) -> CodeDebriefConfig:
+    """Apply one built-in analysis profile on top of the project config.
+
+    Profiles keep the normal config/ignore semantics, but give agents explicit choices:
+    self artifacts for CodeDebrief internals and project artifacts for the whole checkout.
+    Each non-default profile writes to its own output dir so focused dogfood models do not
+    overwrite one another.
+    """
+    if profile not in BUILTIN_PROFILES:
+        known = ", ".join(BUILTIN_PROFILES)
+        raise ValueError(f"unknown CodeDebrief profile {profile!r}; known profiles: {known}")
+    if profile == "self":
+        config.source_roots = ["src/codedebrief"]
+        config.self_exclude = False
+        config.output_dir = "codedebrief-out/self"
+    elif profile == "project":
+        config.source_roots = ["src", "tests"]
+        config.self_exclude = False
+        config.output_dir = "codedebrief-out/project"
+    return config
+
+
+def _normalize_pattern(pattern: str) -> str:
+    normalized = pattern.replace("\\", "/").lstrip("/")
+    if normalized.endswith("/"):
+        return normalized + "**"
+    return normalized
+
+
+def _directory_name_or_path_matches(path: str, name: str, pattern: str) -> bool:
+    normalized = pattern.replace("\\", "/").strip("/")
+    if not normalized:
+        return False
+    if "/" not in normalized:
+        return any(fnmatch.fnmatch(part, normalized) for part in path.split("/") if part)
+    return fnmatch.fnmatch(path, normalized) or _directory_pattern_matches(
+        path, normalized.rstrip("/") + "/**"
+    )
+
+
+def _directory_pattern_matches(path: str, pattern: str) -> bool:
+    if pattern.endswith("/**"):
+        directory = pattern[:-3].rstrip("/")
+        return path == directory or path.startswith(directory + "/")
+    return False
+
+
+def _scope_match(path: str, pattern: str) -> bool:
+    normalized = pattern.replace("\\", "/")
+    return (
+        fnmatch.fnmatch(path, normalized)
+        or fnmatch.fnmatch(path, normalized.rstrip("/") + "/**")
+        or _directory_pattern_matches(path, normalized)
+    )

codedebrief/doctor.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from dataclasses import asdict, dataclass
+from importlib import metadata
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeDependency:
+    package: str
+    import_name: str
+    purpose: str
+
+
+@dataclass(frozen=True, slots=True)
+class MissingDependency:
+    package: str
+    import_name: str
+    purpose: str
+
+
+@dataclass(frozen=True, slots=True)
+class LanguageCapabilitySummary:
+    supported_languages: list[str]
+    feature_count: int
+    limitation_note_count: int
+    contract: str
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorReport:
+    ok: bool
+    executable: str
+    package_version: str
+    package_location: str
+    missing_dependencies: list[MissingDependency]
+    repair_command: str
+    language_capabilities: LanguageCapabilitySummary
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = asdict(self)
+        payload["missing_dependencies"] = [asdict(item) for item in self.missing_dependencies]
+        return payload
+
+
+RUNTIME_DEPENDENCIES = (
+    RuntimeDependency("jsonschema", "jsonschema", "artifact validation"),
+    RuntimeDependency("tree-sitter", "tree_sitter", "parser runtime"),
+    RuntimeDependency("tree-sitter-typescript", "tree_sitter_typescript", "TypeScript/JavaScript"),
+    RuntimeDependency("tree-sitter-c", "tree_sitter_c", "C"),
+    RuntimeDependency("tree-sitter-c-sharp", "tree_sitter_c_sharp", "C#"),
+    RuntimeDependency("tree-sitter-go", "tree_sitter_go", "Go"),
+    RuntimeDependency("tree-sitter-java", "tree_sitter_java", "Java"),
+    RuntimeDependency("tree-sitter-php", "tree_sitter_php", "PHP"),
+    RuntimeDependency("tree-sitter-cpp", "tree_sitter_cpp", "C++"),
+    RuntimeDependency("tree-sitter-ruby", "tree_sitter_ruby", "Ruby"),
+    RuntimeDependency("tree-sitter-rust", "tree_sitter_rust", "Rust"),
+)
+
+
+def doctor_report(root: Path) -> DoctorReport:
+    missing = [
+        MissingDependency(item.package, item.import_name, item.purpose)
+        for item in RUNTIME_DEPENDENCIES
+        if importlib.util.find_spec(item.import_name) is None
+    ]
+    return DoctorReport(
+        ok=not missing,
+        executable=sys.executable,
+        package_version=_package_version(),
+        package_location=_package_location(),
+        missing_dependencies=missing,
+        repair_command=_repair_command(root),
+        language_capabilities=_language_capability_summary(),
+    )
+
+
+def render_doctor(report: DoctorReport) -> str:
+    capabilities = report.language_capabilities
+    lines = [
+        f"CodeDebrief doctor {'OK' if report.ok else 'FAILED'}",
+        f"Python: {report.executable}",
+        f"Package: codedebrief {report.package_version}",
+    ]
+    if report.package_location:
+        lines.append(f"Location: {report.package_location}")
+    lines.append(
+        "Language capabilities: "
+        f"{len(capabilities.supported_languages)} language ids, "
+        f"{capabilities.feature_count} feature flags, "
+        f"{capabilities.limitation_note_count} limitation notes"
+    )
+    lines.append(f"Capability contract: {capabilities.contract}")
+    if report.missing_dependencies:
+        lines.append("")
+        lines.append("Missing runtime dependencies:")
+        lines.extend(
+            f"- {item.package} (import {item.import_name}) for {item.purpose}"
+            for item in report.missing_dependencies
+        )
+        lines.append("")
+        lines.append("Repair this interpreter with:")
+        lines.append(f"  {report.repair_command}")
+    else:
+        lines.append("All runtime parser dependencies are importable.")
+    return "\n".join(lines)
+
+
+def render_doctor_json(report: DoctorReport) -> str:
+    return json.dumps(report.to_dict(), indent=2)
+
+
+def _package_version() -> str:
+    try:
+        return metadata.version("codedebrief")
+    except metadata.PackageNotFoundError:
+        return "not installed"
+
+
+def _package_location() -> str:
+    try:
+        distribution = metadata.distribution("codedebrief")
+    except metadata.PackageNotFoundError:
+        return ""
+    direct_url = distribution.read_text("direct_url.json")
+    if direct_url:
+        try:
+            payload = json.loads(direct_url)
+        except json.JSONDecodeError:
+            return ""
+        url = payload.get("url")
+        if isinstance(url, str) and url.startswith("file://"):
+            return url.removeprefix("file://")
+    return ""
+
+
+def _repair_command(root: Path) -> str:
+    project_root = root.resolve()
+    if _looks_like_codedebrief_checkout(project_root):
+        return f"{sys.executable} -m pip install -e {project_root}"
+    if _looks_like_codedebrief_checkout(Path.cwd()):
+        return f"{sys.executable} -m pip install -e {Path.cwd().resolve()}"
+    return (
+        f"{sys.executable} -m pip install --force-reinstall "
+        "git+https://github.com/ferdinandobons/CodeDebrief.git"
+    )
+
+
+def _looks_like_codedebrief_checkout(path: Path) -> bool:
+    return (path / "pyproject.toml").exists() and (path / "src" / "codedebrief" / "cli.py").exists()
+
+
+def _language_capability_summary() -> LanguageCapabilitySummary:
+    from codedebrief.analysis.registry import language_capability_matrix
+
+    matrix = language_capability_matrix()
+    feature_names: set[str] = set()
+    limitation_note_count = 0
+    for payload in matrix.values():
+        features = payload.get("features")
+        if isinstance(features, dict):
+            feature_names.update(str(name) for name in features)
+        limitations = payload.get("limitations")
+        if isinstance(limitations, dict):
+            limitation_note_count += len(limitations)
+    return LanguageCapabilitySummary(
+        supported_languages=sorted(matrix),
+        feature_count=len(feature_names),
+        limitation_note_count=limitation_note_count,
+        contract="metadata.language_capabilities; smoke-tested by tests/test_registry.py",
+    )