mycode-coding-agent 0.1.0__py3-none-any.whl

mycode/tools/glob.py

@@ -0,0 +1,247 @@
+from pathlib import Path
+
+from pydantic import Field, field_validator
+
+from mycode.permissions import PermissionChecker, PermissionDecision, PermissionRequest
+from mycode.tools.base import PydanticTool, ToolArgs, ToolResult
+from mycode.tools.bounds import clamp_positive_int_upper_bound
+from mycode.tools.ignore import is_ignored_path, is_low_relevance_path
+from mycode.tools.path_permissions import PathPermissionPolicy
+from mycode.tools.patterns import (
+    is_explicit_path_pattern,
+    is_sensitive_path_pattern,
+    validate_relative_pattern,
+)
+from mycode.tools.workspace import Workspace, WorkspacePathError
+
+
+DEFAULT_MAX_RESULTS = 100
+MAX_RESULTS_LIMIT = 1000
+
+
+class GlobArgs(ToolArgs):
+    pattern: str = Field(
+        min_length=1,
+        description=(
+            "用于匹配 workspace 内文件路径的相对 glob pattern，例如 **/*.py。"
+        ),
+    )
+    max_results: int = Field(
+        default=DEFAULT_MAX_RESULTS,
+        ge=1,
+        le=MAX_RESULTS_LIMIT,
+        strict=True,
+    )
+
+    @field_validator("max_results", mode="before")
+    @classmethod
+    def clamp_max_results(cls, value: object) -> object:
+        return clamp_positive_int_upper_bound(
+            value,
+            upper_bound=MAX_RESULTS_LIMIT,
+        )
+
+
+class GlobTool(PydanticTool[GlobArgs]):
+    name = "glob"
+    description = "按 glob pattern 查找 workspace 内文件。"
+    args_model = GlobArgs
+    capability = "read"
+    risk = "low"
+    concurrency_safe = True
+
+    def __init__(self, workspace: Workspace) -> None:
+        self.workspace = workspace
+
+    def build_permission_request(self, args: GlobArgs) -> PermissionRequest:
+        return PermissionRequest(
+            tool_name=self.name,
+            capability=self.capability,
+            action=self.name,
+            target=args.pattern,
+            arguments=args.model_dump(),
+        )
+
+    def check_permission(
+        self,
+        args: GlobArgs,
+        permission_checker: PermissionChecker,
+    ) -> tuple[PermissionRequest, PermissionDecision]:
+        request = self.build_permission_request(args)
+        pattern_error = validate_relative_pattern(
+            args.pattern,
+            label="Glob pattern",
+        )
+        if pattern_error is not None:
+            return request, PermissionDecision.deny(
+                reason="outside_workspace",
+                message=pattern_error,
+                metadata={"pattern": args.pattern},
+            )
+
+        if is_explicit_path_pattern(args.pattern):
+            path_decision = PathPermissionPolicy(self.workspace).check_path(
+                request,
+                args.pattern,
+            )
+            if path_decision.status != "allow":
+                return request, path_decision
+
+            decision = permission_checker.check(
+                request,
+                self.get_permission_profile(),
+            )
+            if decision.status != "allow":
+                return request, decision
+
+            return request, PermissionDecision.allow(
+                message=decision.message,
+                metadata={**decision.metadata, **path_decision.metadata},
+            )
+
+        if is_sensitive_path_pattern(args.pattern):
+            return request, PermissionDecision.ask(
+                reason="sensitive_path",
+                message=f"Sensitive path pattern requires confirmation: {args.pattern}",
+                metadata={
+                    "pattern": args.pattern,
+                    "pattern_scope": "sensitive_pattern",
+                },
+            )
+
+        return request, permission_checker.check(
+            request,
+            self.get_permission_profile(),
+        )
+
+    def run_authorized(
+        self,
+        args: GlobArgs,
+        decision: PermissionDecision,
+    ) -> ToolResult:
+        return self._run_with_options(
+            args,
+            include_ignored=_can_include_ignored(decision),
+            include_low_relevance=is_explicit_path_pattern(args.pattern),
+        )
+
+    def _run(self, args: GlobArgs) -> ToolResult:
+        return self._run_with_options(
+            args,
+            include_ignored=False,
+            include_low_relevance=is_explicit_path_pattern(args.pattern),
+        )
+
+    def _run_with_options(
+        self,
+        args: GlobArgs,
+        *,
+        include_ignored: bool,
+        include_low_relevance: bool,
+    ) -> ToolResult:
+        pattern_error = validate_relative_pattern(
+            args.pattern,
+            label="Glob pattern",
+        )
+        if pattern_error is not None:
+            return ToolResult.failure(
+                error=pattern_error,
+                metadata={"pattern": args.pattern},
+            )
+
+        try:
+            result = _find_file_matches(
+                self.workspace,
+                args.pattern,
+                include_ignored=include_ignored,
+                include_low_relevance=include_low_relevance,
+            )
+        except ValueError as error:
+            return ToolResult.failure(
+                error=f"Invalid glob pattern: {args.pattern}",
+                metadata={"pattern": args.pattern, "reason": str(error)},
+            )
+
+        matches = result.matches
+        selected_matches = matches[: args.max_results]
+        content = "\n".join(selected_matches)
+        if not content:
+            content = "No files matched."
+            if result.filtered_count > 0:
+                content += " Some matches were filtered by workspace relevance or safety rules."
+
+        return ToolResult.success(
+            content=content,
+            metadata={
+                "pattern": args.pattern,
+                "result_count": len(selected_matches),
+                "total_matches": len(matches),
+                "filtered_count": result.filtered_count,
+                "filtered_reasons": result.filtered_reasons,
+                "max_results": args.max_results,
+                "truncated": len(matches) > args.max_results,
+            },
+        )
+
+
+class GlobMatchResult:
+    def __init__(
+        self,
+        matches: list[str],
+        filtered_reasons: dict[str, int],
+    ) -> None:
+        self.matches = matches
+        self.filtered_reasons = filtered_reasons
+
+    @property
+    def filtered_count(self) -> int:
+        return sum(self.filtered_reasons.values())
+
+
+def _find_file_matches(
+    workspace: Workspace,
+    pattern: str,
+    *,
+    include_ignored: bool = False,
+    include_low_relevance: bool = False,
+) -> GlobMatchResult:
+    matches: list[str] = []
+    filtered_reasons: dict[str, int] = {}
+
+    for candidate in workspace.root.glob(pattern):
+        try:
+            workspace.resolve_path(candidate)
+            if not candidate.is_file():
+                continue
+            if not include_ignored and is_ignored_path(candidate, workspace.root):
+                _increment_reason(filtered_reasons, "ignored")
+                continue
+            if (
+                not include_low_relevance
+                and is_low_relevance_path(candidate, workspace.root)
+            ):
+                _increment_reason(filtered_reasons, "low_relevance")
+                continue
+        except (OSError, WorkspacePathError):
+            continue
+
+        matches.append(candidate.relative_to(workspace.root).as_posix())
+
+    return GlobMatchResult(
+        matches=sorted(matches),
+        filtered_reasons=filtered_reasons,
+    )
+
+
+def _increment_reason(reasons: dict[str, int], reason: str) -> None:
+    reasons[reason] = reasons.get(reason, 0) + 1
+
+
+def _can_include_ignored(decision: PermissionDecision) -> bool:
+    return (
+        decision.metadata.get("confirmation_status") == "approved"
+        and (
+            decision.metadata.get("path_scope") in {"ignored_path", "sensitive_path"}
+            or decision.metadata.get("pattern_scope") == "sensitive_pattern"
+        )
+    )

mycode/tools/grep.py

@@ -0,0 +1,324 @@
+import re
+from pathlib import Path
+
+from pydantic import Field, field_validator
+
+from mycode.permissions import PermissionChecker, PermissionDecision, PermissionRequest
+from mycode.tools.base import PydanticTool, ToolArgs, ToolResult
+from mycode.tools.bounds import clamp_positive_int_upper_bound
+from mycode.tools.ignore import is_ignored_path, is_low_relevance_path
+from mycode.tools.path_permissions import PathPermissionPolicy
+from mycode.tools.patterns import (
+    is_explicit_path_pattern,
+    is_sensitive_path_pattern,
+    validate_relative_pattern,
+)
+from mycode.tools.text import contains_nul_byte, decode_text
+from mycode.tools.workspace import Workspace, WorkspacePathError
+
+
+DEFAULT_PATH_PATTERN = "**/*"
+DEFAULT_MAX_RESULTS = 100
+MAX_RESULTS_LIMIT = 1000
+MAX_MATCH_LINE_CHARS = 240
+
+
+class GrepArgs(ToolArgs):
+    query: str = Field(
+        min_length=1,
+        description="用于匹配文件内容的正则表达式。",
+    )
+    path_pattern: str = Field(
+        default=DEFAULT_PATH_PATTERN,
+        min_length=1,
+        description=(
+            "限定搜索文件范围的 workspace 相对 glob pattern，例如 **/*.py。"
+        ),
+    )
+    case_sensitive: bool = False
+    max_results: int = Field(
+        default=DEFAULT_MAX_RESULTS,
+        ge=1,
+        le=MAX_RESULTS_LIMIT,
+        strict=True,
+    )
+
+    @field_validator("max_results", mode="before")
+    @classmethod
+    def clamp_max_results(cls, value: object) -> object:
+        return clamp_positive_int_upper_bound(
+            value,
+            upper_bound=MAX_RESULTS_LIMIT,
+        )
+
+
+class GrepTool(PydanticTool[GrepArgs]):
+    name = "grep"
+    description = "使用正则表达式搜索 workspace 文件内容。"
+    args_model = GrepArgs
+    capability = "read"
+    risk = "low"
+    concurrency_safe = True
+
+    def __init__(self, workspace: Workspace) -> None:
+        self.workspace = workspace
+
+    def build_permission_request(self, args: GrepArgs) -> PermissionRequest:
+        return PermissionRequest(
+            tool_name=self.name,
+            capability=self.capability,
+            action=self.name,
+            target=args.path_pattern,
+            arguments=args.model_dump(),
+        )
+
+    def check_permission(
+        self,
+        args: GrepArgs,
+        permission_checker: PermissionChecker,
+    ) -> tuple[PermissionRequest, PermissionDecision]:
+        request = self.build_permission_request(args)
+        pattern_error = validate_relative_pattern(
+            args.path_pattern,
+            label="Path pattern",
+        )
+        if pattern_error is not None:
+            return request, PermissionDecision.deny(
+                reason="outside_workspace",
+                message=pattern_error,
+                metadata={"path_pattern": args.path_pattern},
+            )
+
+        if is_explicit_path_pattern(args.path_pattern):
+            path_decision = PathPermissionPolicy(self.workspace).check_path(
+                request,
+                args.path_pattern,
+            )
+            if path_decision.status != "allow":
+                return request, path_decision
+
+            decision = permission_checker.check(
+                request,
+                self.get_permission_profile(),
+            )
+            if decision.status != "allow":
+                return request, decision
+
+            return request, PermissionDecision.allow(
+                message=decision.message,
+                metadata={**decision.metadata, **path_decision.metadata},
+            )
+
+        if is_sensitive_path_pattern(args.path_pattern):
+            return request, PermissionDecision.ask(
+                reason="sensitive_path",
+                message=(
+                    "Sensitive path pattern requires confirmation: "
+                    f"{args.path_pattern}"
+                ),
+                metadata={
+                    "path_pattern": args.path_pattern,
+                    "pattern_scope": "sensitive_pattern",
+                },
+            )
+
+        return request, permission_checker.check(
+            request,
+            self.get_permission_profile(),
+        )
+
+    def run_authorized(
+        self,
+        args: GrepArgs,
+        decision: PermissionDecision,
+    ) -> ToolResult:
+        return self._run_with_options(
+            args,
+            include_ignored=_can_include_ignored(decision),
+            include_low_relevance=is_explicit_path_pattern(args.path_pattern),
+        )
+
+    def _run(self, args: GrepArgs) -> ToolResult:
+        return self._run_with_options(
+            args,
+            include_ignored=False,
+            include_low_relevance=is_explicit_path_pattern(args.path_pattern),
+        )
+
+    def _run_with_options(
+        self,
+        args: GrepArgs,
+        *,
+        include_ignored: bool,
+        include_low_relevance: bool,
+    ) -> ToolResult:
+        pattern_error = validate_relative_pattern(
+            args.path_pattern,
+            label="Path pattern",
+        )
+        if pattern_error is not None:
+            return ToolResult.failure(
+                error=pattern_error,
+                metadata={"path_pattern": args.path_pattern},
+            )
+
+        flags = 0 if args.case_sensitive else re.IGNORECASE
+        try:
+            query_pattern = re.compile(args.query, flags=flags)
+        except re.error as error:
+            return ToolResult.failure(
+                error=f"Invalid regular expression: {error}",
+                metadata={"query": args.query, "reason": str(error)},
+            )
+
+        try:
+            search_result = _find_search_files(
+                self.workspace,
+                args.path_pattern,
+                include_ignored=include_ignored,
+                include_low_relevance=include_low_relevance,
+            )
+        except ValueError as error:
+            return ToolResult.failure(
+                error=f"Invalid path pattern: {args.path_pattern}",
+                metadata={"path_pattern": args.path_pattern, "reason": str(error)},
+            )
+
+        files = search_result.files
+        matches: list[str] = []
+        searched_files = 0
+        skipped_files = 0
+        truncated = False
+
+        for path in files:
+            raw_content = _read_bytes(path)
+            if raw_content is None or contains_nul_byte(raw_content):
+                skipped_files += 1
+                continue
+
+            decoded = decode_text(raw_content)
+            if decoded is None:
+                skipped_files += 1
+                continue
+
+            text, _encoding = decoded
+            searched_files += 1
+            relative_path = path.relative_to(self.workspace.root).as_posix()
+
+            for line_number, line in enumerate(text.splitlines(), start=1):
+                if not _line_matches(line, query_pattern):
+                    continue
+
+                if len(matches) >= args.max_results:
+                    truncated = True
+                    break
+
+                matches.append(_format_match(relative_path, line_number, line))
+
+            if truncated:
+                break
+
+        content = "\n".join(matches)
+        if not content:
+            content = "No matches found."
+
+        return ToolResult.success(
+            content=content,
+            metadata={
+                "query": args.query,
+                "path_pattern": args.path_pattern,
+                "case_sensitive": args.case_sensitive,
+                "result_count": len(matches),
+                "max_results": args.max_results,
+                "truncated": truncated,
+                "searched_files": searched_files,
+                "skipped_files": skipped_files,
+                "filtered_count": search_result.filtered_count,
+                "filtered_reasons": search_result.filtered_reasons,
+            },
+        )
+
+
+class GrepSearchResult:
+    def __init__(
+        self,
+        files: list[Path],
+        filtered_reasons: dict[str, int],
+    ) -> None:
+        self.files = files
+        self.filtered_reasons = filtered_reasons
+
+    @property
+    def filtered_count(self) -> int:
+        return sum(self.filtered_reasons.values())
+
+
+def _find_search_files(
+    workspace: Workspace,
+    path_pattern: str,
+    *,
+    include_ignored: bool = False,
+    include_low_relevance: bool = False,
+) -> GrepSearchResult:
+    files: list[Path] = []
+    filtered_reasons: dict[str, int] = {}
+
+    for candidate in workspace.root.glob(path_pattern):
+        try:
+            workspace.resolve_path(candidate)
+            if not candidate.is_file():
+                continue
+            if not include_ignored and is_ignored_path(candidate, workspace.root):
+                _increment_reason(filtered_reasons, "ignored")
+                continue
+            if (
+                not include_low_relevance
+                and is_low_relevance_path(candidate, workspace.root)
+            ):
+                _increment_reason(filtered_reasons, "low_relevance")
+                continue
+        except (OSError, WorkspacePathError):
+            continue
+
+        files.append(candidate)
+
+    return GrepSearchResult(
+        files=sorted(files),
+        filtered_reasons=filtered_reasons,
+    )
+
+
+def _increment_reason(reasons: dict[str, int], reason: str) -> None:
+    reasons[reason] = reasons.get(reason, 0) + 1
+
+
+def _can_include_ignored(decision: PermissionDecision) -> bool:
+    return (
+        decision.metadata.get("confirmation_status") == "approved"
+        and (
+            decision.metadata.get("path_scope") in {"ignored_path", "sensitive_path"}
+            or decision.metadata.get("pattern_scope") == "sensitive_pattern"
+        )
+    )
+
+
+def _read_bytes(path: Path) -> bytes | None:
+    try:
+        return path.read_bytes()
+    except OSError:
+        return None
+
+
+def _line_matches(line: str, query_pattern: re.Pattern[str]) -> bool:
+    return query_pattern.search(line) is not None
+
+
+def _format_match(path: str, line_number: int, line: str) -> str:
+    return f"{path}:{line_number} | {_truncate_line(line)}"
+
+
+def _truncate_line(line: str) -> str:
+    if len(line) <= MAX_MATCH_LINE_CHARS:
+        return line
+
+    return f"{line[: MAX_MATCH_LINE_CHARS - 3]}..."

mycode/tools/ignore.py

@@ -0,0 +1,122 @@
+from pathlib import Path
+
+
+DEFAULT_EXCLUDED_DIR_NAMES = frozenset(
+    {
+        ".git",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".venv",
+        "__pycache__",
+        "build",
+        "dist",
+        "node_modules",
+        "venv",
+    }
+)
+
+DEFAULT_LOW_RELEVANCE_DIR_NAMES = frozenset(
+    {
+        "__fixtures__",
+        "__snapshots__",
+        "archive",
+        "archives",
+        "demo",
+        "demos",
+        "example",
+        "examples",
+        "external",
+        "fixture",
+        "fixtures",
+        "reference",
+        "references",
+        "sample",
+        "samples",
+        "snapshot",
+        "snapshots",
+        "third_party",
+        "vendor",
+    }
+)
+
+DEFAULT_SENSITIVE_FILE_NAMES = frozenset(
+    {
+        ".env",
+        ".envrc",
+        ".npmrc",
+        ".pypirc",
+        "id_dsa",
+        "id_ecdsa",
+        "id_ed25519",
+        "id_rsa",
+    }
+)
+
+DEFAULT_SENSITIVE_FILE_SUFFIXES = (
+    ".key",
+    ".p12",
+    ".pem",
+    ".pfx",
+)
+
+DEFAULT_SAFE_ENV_TEMPLATE_FILE_NAMES = frozenset(
+    {
+        ".env.example",
+        ".env.sample",
+        ".env.template",
+    }
+)
+
+
+def is_ignored_path(
+    path: Path,
+    root: Path,
+    excluded_dir_names: frozenset[str] = DEFAULT_EXCLUDED_DIR_NAMES,
+) -> bool:
+    try:
+        relative_path = path.relative_to(root)
+    except ValueError:
+        return True
+
+    if any(part in excluded_dir_names for part in relative_path.parts[:-1]):
+        return True
+
+    return is_sensitive_path(path, root)
+
+
+def is_low_relevance_path(
+    path: Path,
+    root: Path,
+    low_relevance_dir_names: frozenset[str] = DEFAULT_LOW_RELEVANCE_DIR_NAMES,
+) -> bool:
+    try:
+        relative_path = path.relative_to(root)
+    except ValueError:
+        return True
+
+    return any(part.casefold() in low_relevance_dir_names for part in relative_path.parts[:-1])
+
+
+def is_sensitive_path(
+    path: Path,
+    root: Path,
+    sensitive_file_names: frozenset[str] = DEFAULT_SENSITIVE_FILE_NAMES,
+    sensitive_file_suffixes: tuple[str, ...] = DEFAULT_SENSITIVE_FILE_SUFFIXES,
+) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return True
+
+    name = path.name.casefold()
+    if name in DEFAULT_SAFE_ENV_TEMPLATE_FILE_NAMES:
+        return False
+
+    if name in sensitive_file_names:
+        return True
+
+    if name.startswith(".env."):
+        return True
+
+    return any(name.endswith(suffix) for suffix in sensitive_file_suffixes)