ai-dev-cli-tools 0.5.0a1__py3-none-any.whl

ai_dev_tools/context/profiles.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ContextProfile:
+    name: str
+    max_chars: int
+    max_files: int
+    max_file_chars: int
+    max_diff_chars: int
+    changed_only: bool = False
+    description: str = ""
+
+
+PROFILES: dict[str, ContextProfile] = {
+    "minimal": ContextProfile(
+        "minimal", 12_000, 8, 2_500, 4_000, description="Smallest useful agent handoff"
+    ),
+    "debug": ContextProfile(
+        "debug", 60_000, 35, 10_000, 20_000, description="Failures, diffs, and nearby code"
+    ),
+    "review": ContextProfile(
+        "review",
+        40_000,
+        25,
+        6_000,
+        20_000,
+        changed_only=True,
+        description="Changed files and review evidence",
+    ),
+    "full": ContextProfile(
+        "full", 150_000, 100, 20_000, 50_000, description="Broad repository context"
+    ),
+}
+
+
+def get_context_profile(name: str) -> ContextProfile | None:
+    if name == "default":
+        return None
+    try:
+        return PROFILES[name]
+    except KeyError as exc:
+        raise ValueError(f"Unknown context profile: {name}") from exc
+
+
+def profile_names() -> tuple[str, ...]:
+    return tuple(PROFILES)

ai_dev_tools/context/selection.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import fnmatch
+import re
+from pathlib import Path
+
+from ai_dev_tools.context.models import ContextOptions, RejectedFile, SelectedFile
+from ai_dev_tools.context.symbols import SymbolSnippet, select_python_symbols
+from ai_dev_tools.detectors.repository_map import BINARY_EXTENSIONS
+from ai_dev_tools.security.secrets import mask_text
+
+BLOCKED_NAMES = {".env", ".env.local", ".env.production", ".env.development", ".DS_Store"}
+BLOCKED_SUFFIXES = {".pyc", ".pyo", ".pem", ".key", ".p12", ".pfx"}
+ALWAYS_IGNORE = {
+    ".ai/logs",
+    ".ai/reports",
+    ".ai/context",
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    "__pycache__",
+    "node_modules",
+    ".venv",
+    "venv",
+    "dist",
+    "build",
+}
+
+
+def _select_candidates(
+    root: Path,
+    options: ContextOptions,
+    changed_files: list[str],
+    scan_summary: dict[str, object],
+    map_summary: dict[str, object],
+    related_tests: list[str],
+) -> tuple[dict[Path, str], list[RejectedFile]]:
+    candidates: dict[Path, str] = {}
+    rejected: list[RejectedFile] = []
+    for pattern in options.include:
+        for path in root.glob(pattern):
+            _add_candidate(
+                root, path, f"included by pattern: {pattern}", candidates, rejected, options
+            )
+    for rel in changed_files:
+        _add_candidate(root, root / rel, "changed file", candidates, rejected, options)
+    for rel in related_tests:
+        _add_candidate(root, root / rel, "related affected test", candidates, rejected, options)
+    for rel in _object_list(scan_summary.get("entrypoints")):
+        if not rel.startswith("script:"):
+            _add_candidate(root, root / rel, "detected entrypoint", candidates, rejected, options)
+    for key, reason in (
+        ("important_files", "important project file"),
+        ("tests", "repository test file"),
+        ("ci_workflows", "CI workflow"),
+        ("documentation", "documentation"),
+    ):
+        for rel in _object_list(map_summary.get(key)):
+            _add_candidate(root, root / rel, reason, candidates, rejected, options)
+    return candidates, rejected
+
+
+def _add_candidate(
+    root: Path,
+    path: Path,
+    reason: str,
+    candidates: dict[Path, str],
+    rejected: list[RejectedFile],
+    options: ContextOptions,
+) -> None:
+    if not path.exists() or not path.is_file():
+        return
+    try:
+        resolved = path.resolve()
+        resolved.relative_to(root.resolve())
+    except ValueError:
+        rejected.append(RejectedFile(str(path), "outside project root", "OUTSIDE_PROJECT_ROOT"))
+        return
+    rel = _rel(root, path)
+    blocked = _blocked_reason(path, rel, options.exclude)
+    if blocked:
+        rejected.append(RejectedFile(rel, blocked, _rejection_reason_code(blocked)))
+        return
+    candidates[path] = reason
+
+
+def _blocked_reason(path: Path, rel: str, excludes: tuple[str, ...]) -> str | None:
+    normalized = rel.replace("\\", "/")
+    parts = set(Path(normalized).parts)
+    if path.name in BLOCKED_NAMES:
+        return "environment or secret-bearing file"
+    if path.suffix.lower() in BLOCKED_SUFFIXES or path.suffix.lower() in BINARY_EXTENSIONS:
+        return "binary or sensitive file type"
+    if any(pattern in parts or normalized.startswith(f"{pattern}/") for pattern in ALWAYS_IGNORE):
+        return "ignored generated/cache path"
+    if any(fnmatch.fnmatch(normalized, pattern.replace("\\", "/")) for pattern in excludes):
+        return "excluded by user pattern"
+    return None
+
+
+def _read_selected_files(
+    root: Path, paths: list[Path], reasons: dict[Path, str], options: ContextOptions
+) -> tuple[list[SelectedFile], list[RejectedFile]]:
+    selected: list[SelectedFile] = []
+    rejected: list[RejectedFile] = []
+    for path in paths:
+        rel = _rel(root, path)
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError as exc:
+            rejected.append(RejectedFile(rel, f"unreadable: {exc}", "UNREADABLE_FILE"))
+            continue
+        masked = mask_text(text)
+        symbol_selection = (
+            select_python_symbols(text, masked, options.task, options.max_file_chars)
+            if path.suffix.lower() == ".py"
+            else None
+        )
+        if symbol_selection is None:
+            snippet, truncated = _truncate_text(masked, options.max_file_chars)
+            strategy = "file-prefix"
+            omitted_content = truncated
+            snippets: list[SymbolSnippet] = []
+        else:
+            snippet = symbol_selection.content
+            truncated = symbol_selection.truncated
+            strategy = "python-ast"
+            omitted_content = symbol_selection.omitted_content
+            snippets = symbol_selection.snippets
+        selected.append(
+            SelectedFile(
+                path=rel,
+                reason=reasons[path],
+                reason_code=_selection_reason_code(reasons[path]),
+                chars=len(snippet),
+                truncated=truncated,
+                content=snippet,
+                selection_strategy=strategy,
+                omitted_content=omitted_content,
+                snippets=snippets,
+            )
+        )
+    return selected, rejected
+
+
+def _selection_reason_code(reason: str) -> str:
+    return {
+        "included by user": "USER_INCLUDE",
+        "changed file": "CHANGED_FILE",
+        "related affected test": "RELATED_TEST",
+        "detected entrypoint": "DETECTED_ENTRYPOINT",
+        "important project file": "IMPORTANT_FILE",
+        "repository test file": "TEST_FILE",
+        "CI workflow": "CI_WORKFLOW",
+        "documentation": "DOCUMENTATION",
+        "Python dependency": "PYTHON_DEPENDENCY",
+        "JavaScript/TypeScript dependency": "JS_TS_DEPENDENCY",
+        "Rust dependency": "RUST_DEPENDENCY",
+        "Java dependency": "JAVA_DEPENDENCY",
+        "PHP dependency": "PHP_DEPENDENCY",
+    }.get(reason, "SELECTED_FILE")
+
+
+def _rejection_reason_code(reason: str) -> str:
+    return {
+        "environment or secret-bearing file": "SENSITIVE_OR_ENV_FILE",
+        "binary or sensitive file type": "BINARY_OR_SENSITIVE_TYPE",
+        "ignored generated/cache path": "IGNORED_GENERATED_PATH",
+        "excluded by user pattern": "USER_EXCLUDED",
+    }.get(reason, "REJECTED_FILE")
+
+
+def _dependency_files(root: Path, candidates: dict[Path, str]) -> dict[Path, str]:
+    discovered: dict[Path, str] = {}
+    for path in list(candidates):
+        rel = _rel(root, path)
+        if path.suffix == ".py":
+            for module in _python_imports(path):
+                for dep in _python_module_paths(root, module):
+                    if dep.exists():
+                        discovered[dep] = f"local Python dependency imported by {rel}"
+        if path.suffix.lower() in {".js", ".jsx", ".ts", ".tsx"}:
+            for dep in _relative_js_imports(path):
+                discovered[dep] = f"local JS/TS dependency imported by {rel}"
+        if path.suffix == ".rs":
+            for dep in _rust_mod_paths(path):
+                discovered[dep] = f"local Rust module referenced by {rel}"
+        if path.suffix == ".java":
+            for dep in _java_same_package_paths(path):
+                discovered[dep] = f"nearby Java package file related to {rel}"
+        if path.suffix == ".php":
+            for dep in _php_nearby_paths(path):
+                discovered[dep] = f"nearby PHP file related to {rel}"
+    return {path: reason for path, reason in discovered.items() if path.is_file()}
+
+
+def _python_imports(path: Path) -> set[str]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    names: set[str] = set()
+    for line in text.splitlines():
+        match = re.match(
+            r"\s*(?:from\s+([A-Za-z_][\w.]*)\s+import|import\s+([A-Za-z_][\w.]*))",
+            line,
+        )
+        if match:
+            names.add(match.group(1) or match.group(2) or "")
+    return {name for name in names if name}
+
+
+def _python_module_paths(root: Path, module: str) -> list[Path]:
+    parts = module.split(".")
+    candidates = [
+        root / Path(*parts).with_suffix(".py"),
+        root / "src" / Path(*parts).with_suffix(".py"),
+    ]
+    candidates.extend(
+        [root / Path(*parts) / "__init__.py", root / "src" / Path(*parts) / "__init__.py"]
+    )
+    return candidates
+
+
+def _relative_js_imports(path: Path) -> list[Path]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    deps: list[Path] = []
+    for match in re.finditer(r"(?:from\s+|require\()(['\"])(\.{1,2}/[^'\"]+)\1", text):
+        base = (path.parent / match.group(2)).resolve()
+        for suffix in ("", ".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.js"):
+            candidate = Path(f"{base}{suffix}")
+            if candidate.exists() and candidate.is_file():
+                deps.append(candidate)
+                break
+    return deps
+
+
+def _rust_mod_paths(path: Path) -> list[Path]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    deps: list[Path] = []
+    for match in re.finditer(r"^\s*mod\s+([A-Za-z_][\w]*)\s*;", text, re.MULTILINE):
+        name = match.group(1)
+        deps.extend([path.parent / f"{name}.rs", path.parent / name / "mod.rs"])
+    return deps
+
+
+def _java_same_package_paths(path: Path) -> list[Path]:
+    return sorted(path.parent.glob("*.java"))[:5]
+
+
+def _php_nearby_paths(path: Path) -> list[Path]:
+    return sorted(path.parent.glob("*.php"))[:5]
+
+
+def _truncate_text(text: str, max_chars: int) -> tuple[str, bool]:
+    if max_chars < 0:
+        max_chars = 0
+    if len(text) <= max_chars:
+        return text, False
+    marker = "\n[TRUNCATED]\n"
+    keep = max(max_chars - len(marker), 0)
+    return text[:keep] + marker, True
+
+
+def _object_list(value: object) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item) for item in value]
+
+
+def _rel(root: Path, path: Path) -> str:
+    return path.resolve().relative_to(root.resolve()).as_posix()

ai_dev_tools/context/symbols.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class SymbolSnippet:
+    name: str
+    kind: str
+    start_line: int
+    end_line: int
+    reason: str
+    reason_code: str
+    referenced_local_symbols: list[str] = field(default_factory=list)
+    truncated: bool = False
+
+
+@dataclass(slots=True)
+class SymbolSelection:
+    content: str
+    snippets: list[SymbolSnippet]
+    omitted_content: bool
+    truncated: bool
+
+
+def select_python_symbols(
+    source: str,
+    display_source: str,
+    task: str,
+    max_chars: int,
+) -> SymbolSelection | None:
+    if len(display_source) <= max_chars:
+        return None
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+
+    definitions = [
+        node
+        for node in tree.body
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))
+    ]
+    if not definitions:
+        return None
+
+    task_tokens = _task_tokens(task)
+    matched = [node for node in definitions if _name_tokens(node.name) & task_tokens]
+    candidates = matched or [node for node in definitions if not node.name.startswith("_")]
+    if not candidates:
+        candidates = definitions
+    candidates = sorted(
+        candidates,
+        key=lambda node: (_symbol_score(node.name, task_tokens), -node.lineno),
+        reverse=True,
+    )
+
+    local_names = {node.name for node in definitions}
+    source_lines = display_source.splitlines(keepends=True)
+    selected: list[SymbolSnippet] = []
+    sections: list[str] = []
+    remaining = max(max_chars, 0)
+
+    imports = [node for node in tree.body if isinstance(node, (ast.Import, ast.ImportFrom))]
+    if imports and remaining > 0:
+        start = min(node.lineno for node in imports)
+        end = max(_end_line(node) for node in imports)
+        import_budget = min(remaining, max(200, min(1_500, max_chars // 4)))
+        unused_import_budget = _append_section(
+            sections,
+            selected,
+            source_lines,
+            SymbolSnippet(
+                "<imports>",
+                "imports",
+                start,
+                end,
+                "imports required by selected symbols",
+                "REQUIRED_IMPORTS",
+            ),
+            import_budget,
+        )
+        remaining -= import_budget - unused_import_budget
+
+    for node in candidates:
+        if remaining <= 0:
+            break
+        reason = (
+            "symbol name matches task terms"
+            if _name_tokens(node.name) & task_tokens
+            else "top-level public symbol"
+        )
+        referenced = sorted(
+            {
+                child.id
+                for child in ast.walk(node)
+                if isinstance(child, ast.Name) and child.id in local_names and child.id != node.name
+            }
+        )
+        snippet = SymbolSnippet(
+            name=node.name,
+            kind=_symbol_kind(node),
+            start_line=node.lineno,
+            end_line=_end_line(node),
+            reason=reason,
+            reason_code=(
+                "TASK_SYMBOL_MATCH"
+                if reason == "symbol name matches task terms"
+                else "PUBLIC_SYMBOL"
+            ),
+            referenced_local_symbols=referenced,
+        )
+        remaining = _append_section(sections, selected, source_lines, snippet, remaining)
+
+    if not selected:
+        return None
+    return SymbolSelection(
+        content="\n\n".join(sections).rstrip() + "\n",
+        snippets=selected,
+        omitted_content=True,
+        truncated=any(item.truncated for item in selected),
+    )
+
+
+def _append_section(
+    sections: list[str],
+    selected: list[SymbolSnippet],
+    lines: list[str],
+    snippet: SymbolSnippet,
+    remaining: int,
+) -> int:
+    header = (
+        f"# [{snippet.kind}] {snippet.name} "
+        f"(lines {snippet.start_line}-{snippet.end_line}; {snippet.reason})\n"
+    )
+    body = "".join(lines[snippet.start_line - 1 : snippet.end_line])
+    separator_cost = 2 if sections else 0
+    available = max(remaining - len(header) - separator_cost, 0)
+    if available <= 0:
+        return remaining
+    if len(body) > available:
+        marker = "\n# [SYMBOL TRUNCATED]\n"
+        body = body[: max(available - len(marker), 0)] + marker
+        snippet.truncated = True
+    sections.append(header + body.rstrip())
+    selected.append(snippet)
+    return max(remaining - len(sections[-1]) - separator_cost, 0)
+
+
+def _task_tokens(task: str) -> set[str]:
+    return {
+        token.lower() for token in re.findall(r"[A-Za-z_][A-Za-z0-9_]+", task) if len(token) >= 3
+    }
+
+
+def _name_tokens(name: str) -> set[str]:
+    split = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", name).lower()
+    return {token for token in split.split("_") if token}
+
+
+def _symbol_score(name: str, task_tokens: set[str]) -> int:
+    matches = len(_name_tokens(name) & task_tokens)
+    return matches * 100 + (10 if not name.startswith("_") else 0)
+
+
+def _end_line(node: ast.AST) -> int:
+    value = getattr(node, "end_lineno", None)
+    return value if isinstance(value, int) else getattr(node, "lineno", 1)
+
+
+def _symbol_kind(node: ast.AST) -> str:
+    if isinstance(node, ast.ClassDef):
+        return "class"
+    if isinstance(node, ast.AsyncFunctionDef):
+        return "async-function"
+    return "function"

ai_dev_tools/detectors/__init__.py

@@ -0,0 +1 @@
+"""Project and environment detectors."""

ai_dev_tools/detectors/environment.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from ai_dev_tools.config import load_settings
+from ai_dev_tools.detectors.runtime import (
+    detect_runtime_requirements,
+    evaluate_requirement,
+)
+from ai_dev_tools.models.report import Report
+from ai_dev_tools.reporters.writer import write_json, write_markdown
+from ai_dev_tools.security.secrets import mask_text
+from ai_dev_tools.utils.subprocess import run_command
+
+
+@dataclass(frozen=True, slots=True)
+class ToolSpec:
+    name: str
+    executable: str
+    version_command: list[str]
+    required: bool = False
+
+
+TOOLS: tuple[ToolSpec, ...] = (
+    ToolSpec("git", "git", ["git", "--version"], required=True),
+    ToolSpec("python", "python", ["python", "--version"], required=True),
+    ToolSpec("uv", "uv", ["uv", "--version"]),
+    ToolSpec("poetry", "poetry", ["poetry", "--version"]),
+    ToolSpec("node", "node", ["node", "--version"]),
+    ToolSpec("npm", "npm", ["npm", "--version"]),
+    ToolSpec("pnpm", "pnpm", ["pnpm", "--version"]),
+    ToolSpec("yarn", "yarn", ["yarn", "--version"]),
+    ToolSpec("java", "java", ["java", "--version"]),
+    ToolSpec("maven", "mvn", ["mvn", "--version"]),
+    ToolSpec("gradle", "gradle", ["gradle", "--version"]),
+    ToolSpec("php", "php", ["php", "--version"]),
+    ToolSpec("composer", "composer", ["composer", "--version"]),
+    ToolSpec("rust", "rustc", ["rustc", "--version"]),
+    ToolSpec("cargo", "cargo", ["cargo", "--version"]),
+    ToolSpec("docker", "docker", ["docker", "--version"]),
+    ToolSpec("docker_compose", "docker", ["docker", "compose", "version"]),
+    ToolSpec("github_cli", "gh", ["gh", "--version"]),
+)
+
+
+def run_doctor(project_root: Path) -> Report:
+    settings = load_settings(project_root)
+    report = Report(command="doctor", project_root=settings.project_root)
+    tools: dict[str, dict[str, str | bool | None]] = {}
+    for spec in TOOLS:
+        path = shutil.which(spec.executable)
+        if path is None:
+            tools[spec.name] = {
+                "status": "missing",
+                "version": None,
+                "path": None,
+                "required": spec.required,
+            }
+            continue
+        result = run_command(spec.version_command, project_root, timeout_seconds=20)
+        version = (
+            mask_text(result.stdout or result.stderr).splitlines()[0]
+            if result.combined_output
+            else "available"
+        )
+        status = "ok" if result.exit_code == 0 else "error"
+        tools[spec.name] = {
+            "status": status,
+            "version": version,
+            "path": path,
+            "required": spec.required,
+        }
+    requirements = detect_runtime_requirements(settings.project_root)
+    runtime_compatibility = [
+        evaluate_requirement(
+            requirement,
+            str(tools.get(requirement.runtime, {}).get("version"))
+            if tools.get(requirement.runtime, {}).get("version")
+            else None,
+        )
+        for requirement in requirements
+    ]
+    incompatible_runtimes = [
+        item for item in runtime_compatibility if item["status"] == "incompatible"
+    ]
+    missing_project_runtimes = [
+        item for item in runtime_compatibility if item["status"] == "missing"
+    ]
+    report.summary = {
+        "tools": tools,
+        "missing_required": [
+            k for k, v in tools.items() if v["required"] and v["status"] == "missing"
+        ],
+        "missing_optional": [
+            k for k, v in tools.items() if not v["required"] and v["status"] == "missing"
+        ],
+        "errors_required": [
+            k for k, v in tools.items() if v["required"] and v["status"] == "error"
+        ],
+        "runtime_requirements": [item.to_dict() for item in requirements],
+        "runtime_compatibility": runtime_compatibility,
+        "incompatible_runtimes": incompatible_runtimes,
+        "missing_project_runtimes": missing_project_runtimes,
+        "errors_optional": [
+            k for k, v in tools.items() if not v["required"] and v["status"] == "error"
+        ],
+    }
+    report.status = (
+        "failed"
+        if (
+            report.summary["missing_required"]
+            or report.summary["errors_required"]
+            or incompatible_runtimes
+            or missing_project_runtimes
+        )
+        else "warning"
+        if report.summary["errors_optional"]
+        else "success"
+    )
+    report.finish()
+    write_markdown(report, settings.reports_directory / "doctor.md")
+    write_json(report, settings.reports_directory / "doctor.json")
+    return report