codetool-explore 0.5.0__tar.gz → 0.6.0__tar.gz

codetool_explore-0.6.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.py[cod]
+rust/target/
+benchmark-corpus/
+benchmarks/corpus/
+reports/
+research/
+.tmp*/
+.ruff_cache/

{codetool_explore-0.5.0 → codetool_explore-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codetool-explore
-Version: 0.5.0
+Version: 0.6.0
 Summary: Fast, dependency-free workspace search, read, and list exploration for coding-agent tools with Rust backend
 Project-URL: Homepage, https://github.com/pbi-agent/codetool-explore
 Project-URL: Repository, https://github.com/pbi-agent/codetool-explore
@@ -109,16 +109,19 @@ path-only rows under `target="content_or_path"` are returned without
 line/snippet fields.
 
 `target="read"` treats `pattern` as one known file path, resolves relative paths
-under a single `root`, and returns plain text with no line-number prefixes.
-Use `start_line` and `limit` to cap the returned line range; if more lines
-remain, text output starts with `-- more: cursor=N`. CSV files are read as
-ordinary text. Binary-looking, missing, unreadable, or directory paths fail with
+under each root, and returns plain text with no line-number prefixes. When more
+than one file is read, each file is prefixed by a compact `path:` header. Use
+`start_line` and `limit` to cap the returned line range; if more lines remain,
+text output starts with `-- more: cursor=N`. CSV files are read as ordinary
+text. Binary-looking, missing, unreadable, or directory paths fail with
 controlled `ExploreError` subclasses.
 
 `target="list"` treats `pattern` as one file/directory path and returns one
-directory level. Text output uses the same compact tree display as raw search
-output when that saves tokens. Directories end with `/`; file paths are returned
-as one entry. It honors `glob`, `exclude`, ignore files, `limit`, and `cursor`.
+directory level under each root. Text output uses the same compact tree display
+as raw search output when that saves tokens, appending each root's listing in
+root order. Directories end with `/`; file paths are returned as one entry. It
+honors multi-root common-base paths, `glob`, `exclude`, ignore files, `limit`,
+and `cursor`.
 Read/list use the pure-Python stdlib implementation even when `backend="auto"`
 or `"rust"` is requested.
 
@@ -139,9 +142,10 @@ treated as multiple roots when that exact path does not exist and every split
 token is an existing file or directory. Existing paths with spaces still take
 priority; quote individual spaced paths if combining them in one string.
 
-File roots search only that file and report paths relative to the file's parent
-directory. Multi-root searches report paths relative to the roots' common base,
-so sibling roots keep prefixes such as `src/...` and `tests/...`; this also lets
+File roots search/read only that file and report paths relative to the file's
+parent directory; listing a file path returns one file entry. Multi-root
+searches/reads/listings report paths relative to the roots' common base, so
+sibling roots keep prefixes such as `src/...` and `tests/...`; this also lets
 `exclude=["src/generated/**"]` target one root.
 
 Controlled failures raise `ExploreError` subclasses:
@@ -159,15 +163,16 @@ codetool-explore "service" . --target path --literal
 codetool-explore "User(Service|Repository)" --root src --mode snippets --raw
 codetool-explore "search_workspace" --root src --root webapp --root tests --literal
 codetool-explore --read README.md --start-line 20 --limit 40
-codetool-explore --list src --glob "*.py"
+codetool-explore --read settings.py --root src --root tests
+codetool-explore --list . --root src --root tests --glob "*.py"
 ```
 
 The CLI defaults to compact JSON for search, plain text for `--read`, and
 tree-compressed text for `--list`.
 Use `--format text` or `--raw` for raw search text; no search matches print
-`No Match`. Repeat `--root` for multiple search roots; read/list accept a single
-root only. A single quoted space-delimited `--root` is accepted as a compatibility
-fallback when it can be split into existing roots.
+`No Match`. Repeat `--root` for multiple search/read/list roots. A single
+quoted space-delimited `--root` is accepted as a compatibility fallback when it
+can be split into existing roots.
 
 ## Install
 
@@ -217,13 +222,11 @@ Token counts use `tiktoken` when available. The table compares output across 7 R
 
 | Output | Tokens | Bytes | Chart |
 | --- | ---: | ---: | --- |
-| `explore(..., result_format="text")` | 11,008 | 34.3 KB | ██░░░░░░░░░░░░░░░░ |
+| `codetool-explore` | 11,008 | 34.3 KB | ██░░░░░░░░░░░░░░░░ |
 | `rtk grep` stdout | 19,646 | 60.1 KB | ███░░░░░░░░░░░░░░░ |
-| default `explore(...)` | 38,393 | 125.3 KB | █████░░░░░░░░░░░░░ |
-| `explore(..., result_format="full")` | 39,027 | 134.7 KB | █████░░░░░░░░░░░░░ |
 | `rg` stdout | 129,775 | 402.4 KB | ██████████████████ |
 
-Default structured output is 7.03% smaller than the full structured shape. Raw text omits backend/totals metadata, includes only a cursor hint when truncated, and prints `No Match` for empty pages. Raw text is 0.56× the `rtk grep` token count in this run.
+`codetool-explore` is raw text from `explore(..., result_format="text")`; it omits backend/totals metadata, includes only a cursor hint when truncated, and prints `No Match` for empty pages. It is 0.56× the `rtk grep` token count in this run.
 
 Source: `reports/rtk_vs_codetool_output_lengths.json`.
 

{codetool_explore-0.5.0 → codetool_explore-0.6.0}/README.md

@@ -79,16 +79,19 @@ path-only rows under `target="content_or_path"` are returned without
 line/snippet fields.
 
 `target="read"` treats `pattern` as one known file path, resolves relative paths
-under a single `root`, and returns plain text with no line-number prefixes.
-Use `start_line` and `limit` to cap the returned line range; if more lines
-remain, text output starts with `-- more: cursor=N`. CSV files are read as
-ordinary text. Binary-looking, missing, unreadable, or directory paths fail with
+under each root, and returns plain text with no line-number prefixes. When more
+than one file is read, each file is prefixed by a compact `path:` header. Use
+`start_line` and `limit` to cap the returned line range; if more lines remain,
+text output starts with `-- more: cursor=N`. CSV files are read as ordinary
+text. Binary-looking, missing, unreadable, or directory paths fail with
 controlled `ExploreError` subclasses.
 
 `target="list"` treats `pattern` as one file/directory path and returns one
-directory level. Text output uses the same compact tree display as raw search
-output when that saves tokens. Directories end with `/`; file paths are returned
-as one entry. It honors `glob`, `exclude`, ignore files, `limit`, and `cursor`.
+directory level under each root. Text output uses the same compact tree display
+as raw search output when that saves tokens, appending each root's listing in
+root order. Directories end with `/`; file paths are returned as one entry. It
+honors multi-root common-base paths, `glob`, `exclude`, ignore files, `limit`,
+and `cursor`.
 Read/list use the pure-Python stdlib implementation even when `backend="auto"`
 or `"rust"` is requested.
 
@@ -109,9 +112,10 @@ treated as multiple roots when that exact path does not exist and every split
 token is an existing file or directory. Existing paths with spaces still take
 priority; quote individual spaced paths if combining them in one string.
 
-File roots search only that file and report paths relative to the file's parent
-directory. Multi-root searches report paths relative to the roots' common base,
-so sibling roots keep prefixes such as `src/...` and `tests/...`; this also lets
+File roots search/read only that file and report paths relative to the file's
+parent directory; listing a file path returns one file entry. Multi-root
+searches/reads/listings report paths relative to the roots' common base, so
+sibling roots keep prefixes such as `src/...` and `tests/...`; this also lets
 `exclude=["src/generated/**"]` target one root.
 
 Controlled failures raise `ExploreError` subclasses:
@@ -129,15 +133,16 @@ codetool-explore "service" . --target path --literal
 codetool-explore "User(Service|Repository)" --root src --mode snippets --raw
 codetool-explore "search_workspace" --root src --root webapp --root tests --literal
 codetool-explore --read README.md --start-line 20 --limit 40
-codetool-explore --list src --glob "*.py"
+codetool-explore --read settings.py --root src --root tests
+codetool-explore --list . --root src --root tests --glob "*.py"
 ```
 
 The CLI defaults to compact JSON for search, plain text for `--read`, and
 tree-compressed text for `--list`.
 Use `--format text` or `--raw` for raw search text; no search matches print
-`No Match`. Repeat `--root` for multiple search roots; read/list accept a single
-root only. A single quoted space-delimited `--root` is accepted as a compatibility
-fallback when it can be split into existing roots.
+`No Match`. Repeat `--root` for multiple search/read/list roots. A single
+quoted space-delimited `--root` is accepted as a compatibility fallback when it
+can be split into existing roots.
 
 ## Install
 
@@ -187,13 +192,11 @@ Token counts use `tiktoken` when available. The table compares output across 7 R
 
 | Output | Tokens | Bytes | Chart |
 | --- | ---: | ---: | --- |
-| `explore(..., result_format="text")` | 11,008 | 34.3 KB | ██░░░░░░░░░░░░░░░░ |
+| `codetool-explore` | 11,008 | 34.3 KB | ██░░░░░░░░░░░░░░░░ |
 | `rtk grep` stdout | 19,646 | 60.1 KB | ███░░░░░░░░░░░░░░░ |
-| default `explore(...)` | 38,393 | 125.3 KB | █████░░░░░░░░░░░░░ |
-| `explore(..., result_format="full")` | 39,027 | 134.7 KB | █████░░░░░░░░░░░░░ |
 | `rg` stdout | 129,775 | 402.4 KB | ██████████████████ |
 
-Default structured output is 7.03% smaller than the full structured shape. Raw text omits backend/totals metadata, includes only a cursor hint when truncated, and prints `No Match` for empty pages. Raw text is 0.56× the `rtk grep` token count in this run.
+`codetool-explore` is raw text from `explore(..., result_format="text")`; it omits backend/totals metadata, includes only a cursor hint when truncated, and prints `No Match` for empty pages. It is 0.56× the `rtk grep` token count in this run.
 
 Source: `reports/rtk_vs_codetool_output_lengths.json`.
 

{codetool_explore-0.5.0 → codetool_explore-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codetool-explore"
-version = "0.5.0"
+version = "0.6.0"
 description = "Fast, dependency-free workspace search, read, and list exploration for coding-agent tools with Rust backend"
 readme = "README.md"
 authors = [

{codetool_explore-0.5.0 → codetool_explore-0.6.0}/scripts/update_readme_benchmarks.py

@@ -175,37 +175,30 @@ def render_tokens(data: dict[str, Any], source: str) -> list[str]:
     if "summary" not in data:
         aggregate = compression_totals(data)
         totals = aggregate["totals"]
-        full = int(totals["full_bytes"])
-        compressed = int(totals["compressed_bytes"])
         raw = int(totals["raw_bytes"])
         rtk = int(totals["rtk_bytes"])
         rg = int(totals["rg_bytes"])
-        grep = int(totals["grep_bytes"])
-        full_tokens = int(totals["full_tokens"])
-        compressed_tokens = int(totals["compressed_tokens"])
         raw_tokens = int(totals["raw_tokens"])
         rtk_tokens = int(totals["rtk_tokens"])
         rg_tokens = int(totals["rg_tokens"])
-        grep_tokens = int(totals["grep_tokens"])
         savings = aggregate["savings"]
-        if not full or not compressed:
+        if not raw:
             raise SystemExit(f"{source} does not contain token-compression data")
-        rows = [
-            ('`explore(..., result_format="full")`', full_tokens, full),
-            ("default `explore(...)`", compressed_tokens, compressed),
-        ]
+        rows = []
         if raw:
-            rows.append(('`explore(..., result_format="text")`', raw_tokens, raw))
+            rows.append(("`codetool-explore`", raw_tokens, raw))
         if rtk:
             rows.append(("`rtk grep` stdout", rtk_tokens, rtk))
         if rg:
             rows.append(("`rg` stdout", rg_tokens, rg))
-        if grep:
-            rows.append(("GNU `grep` stdout", grep_tokens, grep))
         max_tokens = max(tokens for _, tokens, _ in rows)
-        percent = round(((full - compressed) / full) * 100, 2)
-        average_percent = round(mean(savings), 2) if savings else percent
         samples = aggregate["samples"] or len(savings)
+        raw_ratio = round(raw_tokens / rtk_tokens, 2) if rtk_tokens else None
+        raw_note = (
+            f" It is {raw_ratio}× the `rtk grep` token count in this run."
+            if raw_ratio is not None
+            else ""
+        )
         lines = [
             "### Token compression",
             "",
@@ -224,9 +217,9 @@ def render_tokens(data: dict[str, Any], source: str) -> list[str]:
         lines += [
             "",
             (
-                f"Default structured output is {percent}% smaller in bytes total and "
-                f"{average_percent}% smaller on average per sample than the full shape. "
-                "Raw text omits metadata and is optimized for minimum tokens."
+                "`codetool-explore` is raw text from "
+                '`explore(..., result_format="text")`; it omits metadata and '
+                "is optimized for minimum tokens." + raw_note
             ),
             "",
             f"Source: `{source}`.",
@@ -235,33 +228,20 @@ def render_tokens(data: dict[str, Any], source: str) -> list[str]:
 
     summary = data["summary"]
     totals = summary["total_bytes"]
-    compressed = int(totals["codetool_compressed_json"])
-    full = int(totals["codetool_full_json"])
     raw = int(totals.get("codetool_raw_text", 0))
     rtk = int(totals.get("rtk_grep_stdout", 0))
     rg = int(totals.get("rg_stdout", 0))
-    grep = int(totals.get("grep_stdout", 0))
     token_totals = summary.get("total_tokens", {})
-    full_tokens = int(token_totals.get("codetool_full_json", round(full / 4)))
-    compressed_tokens = int(
-        token_totals.get("codetool_compressed_json", round(compressed / 4))
-    )
     raw_tokens = int(token_totals.get("codetool_raw_text", round(raw / 4)))
     rtk_tokens = int(token_totals.get("rtk_grep_stdout", round(rtk / 4)))
     rg_tokens = int(token_totals.get("rg_stdout", round(rg / 4)))
-    grep_tokens = int(token_totals.get("grep_stdout", round(grep / 4)))
-    rows = [
-        ('`explore(..., result_format="full")`', full_tokens, full),
-        ("default `explore(...)`", compressed_tokens, compressed),
-    ]
+    rows = []
     if raw:
-        rows.append(('`explore(..., result_format="text")`', raw_tokens, raw))
+        rows.append(("`codetool-explore`", raw_tokens, raw))
     if rtk:
         rows.append(("`rtk grep` stdout", rtk_tokens, rtk))
     if rg:
         rows.append(("`rg` stdout", rg_tokens, rg))
-    if grep:
-        rows.append(("GNU `grep` stdout", grep_tokens, grep))
     max_tokens = max(tokens for _, tokens, _ in rows)
     comparison = summary["total_comparison"]
     lines = [
@@ -281,15 +261,15 @@ def render_tokens(data: dict[str, Any], source: str) -> list[str]:
         )
     raw_ratio = comparison.get("codetool_raw_over_rtk_tokens_ratio")
     raw_note = (
-        f" Raw text is {raw_ratio}× the `rtk grep` token count in this run."
+        f" It is {raw_ratio}× the `rtk grep` token count in this run."
         if raw_ratio is not None
         else ""
     )
     lines += [
         "",
         (
-            f"Default structured output is {comparison['codetool_compressed_vs_full_percent_smaller']}% "
-            "smaller than the full structured shape. Raw text omits backend/totals "
+            "`codetool-explore` is raw text from "
+            '`explore(..., result_format="text")`; it omits backend/totals '
             "metadata, includes only a cursor hint when truncated, and prints "
             "`No Match` for empty pages." + raw_note
         ),

{codetool_explore-0.5.0 → codetool_explore-0.6.0}/src/codetool_explore/api.py

@@ -107,12 +107,13 @@ def explore(
     paths without opening files, and ``"content_or_path"`` returns files
     matching either.
     ``"read"`` treats ``pattern`` as one file path and returns a controlled
-    line range. ``"list"`` treats ``pattern`` as one file/directory path and
-    returns a one-level listing.
+    line range for each root. ``"list"`` treats ``pattern`` as one
+    file/directory path and returns a one-level listing for each root.
     Patterns are interpreted as regex by default; pass ``regex=False`` for exact
     literal search. ``root`` may be one directory/file path or a non-empty list
-    of directory/file paths. Multi-root searches report paths relative to the
-    roots' common base, so sibling roots keep prefixes such as ``src/...``.
+    of directory/file paths. Multi-root searches/reads/listings report paths
+    relative to the roots' common base, so sibling roots keep prefixes such as
+    ``src/...``.
     To tolerate common JSON/tool-call mistakes, a whitespace-separated root
     string is treated as multiple roots only when that exact path does not
     exist and every split token is an existing file or directory.
@@ -122,8 +123,8 @@ def explore(
     compatibility fallback.
 
     Search results are returned in a compact structured shape by default; read
-    results default to plain text and list results default to tree-compressed
-    text. Pass
+    results default to plain text (with path headers only when multiple files
+    are read) and list results default to tree-compressed text. Pass
     ``result_format="full"`` to receive the pre-compression backend result
     dictionary unchanged. Pass ``result_format="text"`` (or ``"raw"``) for an
     RTK-inspired plain-text rendering optimized for token compression.

{codetool_explore-0.5.0 → codetool_explore-0.6.0}/src/codetool_explore/cli.py

@@ -26,12 +26,12 @@ def build_parser() -> argparse.ArgumentParser:
     action_group.add_argument(
         "--read",
         dest="read_path",
-        help="read one known file path with controlled line output",
+        help="read one known file path under each root with controlled line output",
     )
     action_group.add_argument(
         "--list",
         dest="list_path",
-        help="list one directory level or one file path",
+        help="list one directory level or one file path under each root",
     )
     parser.add_argument(
         "--root",

{codetool_explore-0.5.0 → codetool_explore-0.6.0}/src/codetool_explore/explorer.py

@@ -19,7 +19,8 @@ from .ignore import (
 )
 from .python_backend.constants import binary_check_bytes
 from .python_backend.ignore_rules import ignore_patterns_for_root
-from .roots import RootInput, normalize_search_roots
+from .python_backend.models import IgnorePatterns
+from .roots import NormalizedRoots, RootInput, SearchRoot, normalize_search_roots
 
 MAX_READ_CHARS = 100_000
 READ_CHUNK_BYTES = 8192
@@ -35,6 +36,9 @@ class ResolvedExplorePath:
     root_display: str | list[str]
     display_base: str | None
     root_base: str
+    search_root_abs: str
+    root_is_file: bool
+    rel_base_abs: str | None
 
 
 def read_file_target(
@@ -45,38 +49,58 @@ def read_file_target(
     limit: int = 50,
     cursor: str | int | None = None,
 ) -> dict[str, object]:
-    """Return a controlled line range from one text file."""
+    """Return a controlled line range from one text file under each root."""
 
     safe_limit = normalize_limit(limit)
     safe_start_line = _normalize_start_line(start_line, cursor=cursor)
-    resolved = _resolve_explore_path(path, root=root, target="read")
-
-    if not os.path.exists(resolved.abs_path):
-        raise ExploreRootError(f"file does not exist: {resolved.query!r}")
-    if os.path.isdir(resolved.abs_path):
-        raise ExploreRootError(f"read target is a directory: {resolved.query!r}")
-    if not os.path.isfile(resolved.abs_path):
-        raise ExploreRootError(f"read target is not a file: {resolved.query!r}")
-
-    _raise_if_binary(resolved.abs_path, resolved.display_path)
-    text, returned_lines, has_more_lines, content_truncated = _read_text_range(
-        resolved.abs_path,
-        display_path=resolved.display_path,
-        start_line=safe_start_line,
-        limit=safe_limit,
+    resolved_paths = _resolve_explore_paths(
+        path,
+        root=root,
+        target="read",
+        allow_multiple=True,
     )
-    next_cursor = (
-        str(safe_start_line + returned_lines)
-        if has_more_lines and returned_lines > 0
-        else None
+    files: list[dict[str, object]] = []
+    seen_files: set[str] = set()
+    for resolved in resolved_paths:
+        identity = os.path.normcase(os.path.abspath(resolved.abs_path))
+        if identity in seen_files:
+            continue
+        seen_files.add(identity)
+        error_path = (
+            resolved.query if len(resolved_paths) == 1 else resolved.display_path
+        )
+        files.append(
+            _read_resolved_file(
+                resolved,
+                error_path=error_path,
+                start_line=safe_start_line,
+                limit=safe_limit,
+            )
+        )
+
+    text = _format_read_files_text(files)
+    returned_lines = sum(int(item.get("returned", 0) or 0) for item in files)
+    content_truncated = any(bool(item.get("content_truncated")) for item in files)
+    next_cursor = next(
+        (
+            str(item_next)
+            for item in files
+            if (item_next := item.get("next_cursor")) not in (None, "")
+        ),
+        None,
     )
+    path_display: object
+    if len(files) == 1:
+        path_display = files[0]["path"]
+    else:
+        path_display = [item["path"] for item in files]
 
-    return {
-        "pattern": resolved.query,
-        "root": resolved.root_display,
+    result: dict[str, object] = {
+        "pattern": resolved_paths[0].query,
+        "root": resolved_paths[0].root_display,
         "target": "read",
         "mode": "read",
-        "path": resolved.display_path,
+        "path": path_display,
         "start_line": safe_start_line,
         "limit": safe_limit,
         "cursor": None if cursor in (None, "") else str(cursor),
@@ -84,12 +108,16 @@ def read_file_target(
         "returned": returned_lines,
         "line_count": returned_lines,
         "count": returned_lines,
-        "truncated": bool(has_more_lines or content_truncated),
+        "file_count": len(files),
+        "truncated": bool(next_cursor or content_truncated),
         "content_truncated": content_truncated,
         "next_cursor": next_cursor,
         "offset": safe_start_line - 1,
         "backend": "python",
     }
+    if len(files) > 1:
+        result["files"] = files
+    return result
 
 
 def list_path_target(
@@ -104,41 +132,64 @@ def list_path_target(
     """Return one ls-like page for a file or one directory level."""
 
     safe_limit = normalize_limit(limit)
-    resolved = _resolve_explore_path(path, root=root, target="list", allow_empty=True)
+    resolved_paths = _resolve_explore_paths(
+        path,
+        root=root,
+        target="list",
+        allow_empty=True,
+        allow_multiple=True,
+    )
     glob_patterns = normalize_patterns(glob)
     exclude_patterns = normalize_patterns(exclude)
 
-    if not os.path.exists(resolved.abs_path):
-        raise ExploreRootError(f"list target does not exist: {resolved.query!r}")
-    if os.path.isfile(resolved.abs_path):
-        entries = _list_single_file(
-            resolved,
-            glob_patterns=glob_patterns,
-            exclude_patterns=exclude_patterns,
-        )
-    elif os.path.isdir(resolved.abs_path):
-        entries = _list_directory(
-            resolved,
-            glob_patterns=glob_patterns,
-            exclude_patterns=exclude_patterns,
-        )
-    else:
-        raise ExploreRootError(
-            f"list target is neither a directory nor file: {resolved.query!r}"
+    entries: list[dict[str, object]] = []
+    seen_entries: set[tuple[str, str]] = set()
+    for resolved in resolved_paths:
+        error_path = (
+            resolved.query if len(resolved_paths) == 1 else resolved.display_path
         )
+        if not os.path.exists(resolved.abs_path):
+            raise ExploreRootError(f"list target does not exist: {error_path!r}")
+        if os.path.isfile(resolved.abs_path):
+            root_entries = _list_single_file(
+                resolved,
+                glob_patterns=glob_patterns,
+                exclude_patterns=exclude_patterns,
+            )
+        elif os.path.isdir(resolved.abs_path):
+            root_entries = _list_directory(
+                resolved,
+                glob_patterns=glob_patterns,
+                exclude_patterns=exclude_patterns,
+            )
+        else:
+            raise ExploreRootError(
+                f"list target is neither a directory nor file: {error_path!r}"
+            )
+        for entry in root_entries:
+            identity = _entry_identity(entry)
+            if identity in seen_entries:
+                continue
+            seen_entries.add(identity)
+            entries.append(entry)
 
     page, truncated, next_cursor, offset = page_items(
         entries, limit=safe_limit, cursor=cursor
     )
     total_files = sum(1 for entry in entries if entry.get("kind") == "file")
     total_dirs = sum(1 for entry in entries if entry.get("kind") == "dir")
+    path_display: object
+    if len(resolved_paths) == 1:
+        path_display = resolved_paths[0].display_path
+    else:
+        path_display = [resolved.display_path for resolved in resolved_paths]
 
     result: dict[str, object] = {
-        "pattern": resolved.query,
-        "root": resolved.root_display,
+        "pattern": resolved_paths[0].query,
+        "root": resolved_paths[0].root_display,
         "target": "list",
         "mode": "list",
-        "path": resolved.display_path,
+        "path": path_display,
         "entries": page,
         "returned": len(page),
         "total_entries": len(entries),
@@ -167,8 +218,25 @@ def _resolve_explore_path(
     target: str,
     allow_empty: bool = False,
 ) -> ResolvedExplorePath:
+    return _resolve_explore_paths(
+        path,
+        root=root,
+        target=target,
+        allow_empty=allow_empty,
+        allow_multiple=False,
+    )[0]
+
+
+def _resolve_explore_paths(
+    path: object,
+    *,
+    root: RootInput,
+    target: str,
+    allow_empty: bool = False,
+    allow_multiple: bool = False,
+) -> tuple[ResolvedExplorePath, ...]:
     root_set = normalize_search_roots(root)
-    if root_set.has_multiple:
+    if root_set.has_multiple and not allow_multiple:
         raise ExploreArgumentError(f"target={target!r} supports one root at a time")
 
     try:
@@ -183,15 +251,32 @@ def _resolve_explore_path(
         else:
             raise ExploreArgumentError(f"{target} path must not be empty")
 
-    search_root = root_set.roots[0]
+    return tuple(
+        _resolve_path_for_search_root(query, search_root=search_root, root_set=root_set)
+        for search_root in root_set.roots
+    )
+
+
+def _resolve_path_for_search_root(
+    query: str,
+    *,
+    search_root: SearchRoot,
+    root_set: NormalizedRoots,
+) -> ResolvedExplorePath:
     root_abs = search_root.abs_path
+    root_is_file = os.path.isfile(root_abs)
     root_base = root_abs if os.path.isdir(root_abs) else os.path.dirname(root_abs)
     if os.path.isabs(query):
         abs_path = os.path.abspath(query)
-        display_base = root_base if _is_under(abs_path, root_base) else None
+        base = root_set.rel_base if root_set.has_multiple else root_base
+        display_base = base if base and _is_under(abs_path, base) else None
     else:
-        abs_path = os.path.abspath(os.path.join(root_base, query))
-        display_base = root_base
+        abs_path = (
+            os.path.abspath(root_abs)
+            if root_is_file and query == "."
+            else os.path.abspath(os.path.join(root_base, query))
+        )
+        display_base = root_set.rel_base if root_set.has_multiple else root_base
     display_path = _display_path(abs_path, display_base)
     return ResolvedExplorePath(
         query=query,
@@ -200,6 +285,9 @@ def _resolve_explore_path(
         root_display=root_set.display,
         display_base=display_base,
         root_base=root_base,
+        search_root_abs=root_abs,
+        root_is_file=root_is_file,
+        rel_base_abs=root_set.rel_base,
     )
 
 
@@ -219,6 +307,56 @@ def _normalize_start_line(start_line: int, *, cursor: str | int | None) -> int:
     return value
 
 
+def _read_resolved_file(
+    resolved: ResolvedExplorePath,
+    *,
+    error_path: str,
+    start_line: int,
+    limit: int,
+) -> dict[str, object]:
+    if not os.path.exists(resolved.abs_path):
+        raise ExploreRootError(f"file does not exist: {error_path!r}")
+    if os.path.isdir(resolved.abs_path):
+        raise ExploreRootError(f"read target is a directory: {error_path!r}")
+    if not os.path.isfile(resolved.abs_path):
+        raise ExploreRootError(f"read target is not a file: {error_path!r}")
+
+    _raise_if_binary(resolved.abs_path, resolved.display_path)
+    text, returned_lines, has_more_lines, content_truncated = _read_text_range(
+        resolved.abs_path,
+        display_path=resolved.display_path,
+        start_line=start_line,
+        limit=limit,
+    )
+    next_cursor = (
+        str(start_line + returned_lines)
+        if has_more_lines and returned_lines > 0
+        else None
+    )
+    return {
+        "path": resolved.display_path,
+        "text": text,
+        "returned": returned_lines,
+        "line_count": returned_lines,
+        "content_truncated": content_truncated,
+        "next_cursor": next_cursor,
+    }
+
+
+def _format_read_files_text(files: list[dict[str, object]]) -> str:
+    if len(files) == 1:
+        return str(files[0].get("text", ""))
+    sections: list[str] = []
+    for item in files:
+        header = f"{item.get('path', '')}:"
+        text = str(item.get("text", ""))
+        if text or int(item.get("returned", 0) or 0) > 0:
+            sections.append(f"{header}\n{text}")
+        else:
+            sections.append(header)
+    return "\n".join(sections)
+
+
 def _is_under(path: str, base: str) -> bool:
     try:
         common_path = os.path.commonpath(
@@ -378,11 +516,9 @@ def _list_single_file(
 ) -> list[dict[str, object]]:
     parent = os.path.dirname(resolved.abs_path) or os.curdir
     rel_path = _display_path(resolved.abs_path, resolved.display_base)
-    api_ignore_base = _listing_api_ignore_base(resolved, is_file=True)
-    api_ignore_patterns = ignore_patterns_for_root(
-        api_ignore_base,
-        rel_base_abs=None,
-        is_file=False,
+    api_ignore_patterns, api_ignore_base = _listing_ignore_patterns(
+        resolved,
+        is_file=True,
     )
     local_ignore_patterns = ignore_patterns_for_root(
         resolved.abs_path,
@@ -393,6 +529,7 @@ def _list_single_file(
         rel_path,
         is_dir=False,
         exclude_patterns=exclude_patterns,
+        ignore_patterns=api_ignore_patterns.common,
         root_ignore_patterns=api_ignore_patterns.root,
         common_rel_path=relative_path(resolved.abs_path, api_ignore_base),
     ) or _is_ignored_by_local_listing_patterns(
@@ -412,10 +549,8 @@ def _list_directory(
     glob_patterns: tuple[str, ...],
     exclude_patterns: tuple[str, ...],
 ) -> list[dict[str, object]]:
-    api_ignore_base = _listing_api_ignore_base(resolved, is_file=False)
-    api_ignore_patterns = ignore_patterns_for_root(
-        api_ignore_base,
-        rel_base_abs=None,
+    api_ignore_patterns, api_ignore_base = _listing_ignore_patterns(
+        resolved,
         is_file=False,
     )
     local_ignore_patterns = ignore_patterns_for_root(
@@ -439,6 +574,7 @@ def _list_directory(
                     rel_path,
                     is_dir=is_dir,
                     exclude_patterns=exclude_patterns,
+                    ignore_patterns=api_ignore_patterns.common,
                     root_ignore_patterns=api_ignore_patterns.root,
                     common_rel_path=relative_path(entry.path, api_ignore_base),
                 ) or _is_ignored_by_local_listing_patterns(
@@ -466,6 +602,37 @@ def _list_directory(
     return entries
 
 
+def _listing_ignore_patterns(
+    resolved: ResolvedExplorePath,
+    *,
+    is_file: bool,
+) -> tuple[IgnorePatterns, str]:
+    root_filter_base = (
+        os.path.dirname(resolved.search_root_abs) or os.curdir
+        if resolved.root_is_file
+        else resolved.search_root_abs
+    )
+    if _is_under(resolved.abs_path, root_filter_base):
+        return (
+            ignore_patterns_for_root(
+                resolved.search_root_abs,
+                rel_base_abs=resolved.rel_base_abs,
+                is_file=resolved.root_is_file,
+            ),
+            root_filter_base,
+        )
+
+    api_ignore_base = _listing_api_ignore_base(resolved, is_file=is_file)
+    return (
+        ignore_patterns_for_root(
+            api_ignore_base,
+            rel_base_abs=None,
+            is_file=False,
+        ),
+        api_ignore_base,
+    )
+
+
 def _listing_api_ignore_base(resolved: ResolvedExplorePath, *, is_file: bool) -> str:
     if _is_under(resolved.abs_path, resolved.root_base):
         return resolved.root_base
@@ -494,4 +661,10 @@ def _is_ignored_by_local_listing_patterns(
 
 def _entry_sort_key(entry: dict[str, Any]) -> tuple[str, str]:
     path = str(entry.get("path", ""))
-    return (path.rstrip("/").casefold(), path)
+    return (path.rstrip("/").casefold(), path)
+
+
+def _entry_identity(entry: dict[str, object]) -> tuple[str, str]:
+    kind = str(entry.get("kind", ""))
+    path = normalize_relpath(str(entry.get("path", ""))).rstrip("/")
+    return (os.path.normcase(path), kind)

{codetool_explore-0.5.0 → codetool_explore-0.6.0}/tests/test_api.py

@@ -297,6 +297,67 @@ def test_read_target_reports_more_and_supports_csv_as_text(tmp_path):
     assert compressed["text"] == "name,value"
 
 
+def test_read_target_accepts_root_list_with_headers(tmp_path):
+    write(tmp_path / "src" / "settings.txt", "src one\nsrc two\n")
+    write(tmp_path / "tests" / "settings.txt", "test one\ntest two\n")
+
+    text = api.explore(
+        "settings.txt",
+        root=[str(tmp_path / "src"), str(tmp_path / "tests")],
+        target="read",
+        limit=1,
+    )
+    full = api.explore(
+        "settings.txt",
+        root=[str(tmp_path / "src"), str(tmp_path / "tests")],
+        target="read",
+        limit=1,
+        result_format="full",
+    )
+
+    assert text == "\n".join(
+        [
+            "-- more: cursor=2",
+            "src/settings.txt:",
+            "src one",
+            "tests/settings.txt:",
+            "test one",
+        ]
+    )
+    assert full["root"] == [str(tmp_path / "src"), str(tmp_path / "tests")]
+    assert full["path"] == ["src/settings.txt", "tests/settings.txt"]
+    assert full["text"] == "\n".join(
+        [
+            "src/settings.txt:",
+            "src one",
+            "tests/settings.txt:",
+            "test one",
+        ]
+    )
+    assert full["returned"] == 2
+    assert full["line_count"] == 2
+    assert full["file_count"] == 2
+    assert full["next_cursor"] == "2"
+    assert full["files"] == [
+        {
+            "path": "src/settings.txt",
+            "text": "src one",
+            "returned": 1,
+            "line_count": 1,
+            "content_truncated": False,
+            "next_cursor": "2",
+        },
+        {
+            "path": "tests/settings.txt",
+            "text": "test one",
+            "returned": 1,
+            "line_count": 1,
+            "content_truncated": False,
+            "next_cursor": "2",
+        },
+    ]
+
+
 def test_read_target_preserves_blank_line_when_more_marker_is_present(tmp_path):
     write(tmp_path / "blank.txt", "\nsecond\n")
 
@@ -331,7 +392,8 @@ def test_read_target_clean_errors(tmp_path):
         api.explore("src", root=str(tmp_path), target="read")
     with pytest.raises(ExploreRootError, match="binary"):
         api.explore("binary.dat", root=str(tmp_path), target="read")
-    with pytest.raises(ExploreArgumentError, match="one root"):
+    write(tmp_path / "src" / "a.py", "")
+    with pytest.raises(ExploreRootError, match="tests/a.py"):
         api.explore(
             "a.py",
             root=[str(tmp_path / "src"), str(tmp_path / "tests")],
@@ -442,6 +504,64 @@ def test_list_text_output_uses_tree_for_repeated_prefixes(tmp_path):
     assert "\n\n" not in result
 
 
+def test_list_target_accepts_root_list_and_appends_each_tree(tmp_path):
+    write(tmp_path / "src" / "codetool_explore" / "__init__.py", "")
+    for name in ("test_api.py", "test_cli.py", "test_cursor.py", "test_ignore.py"):
+        write(tmp_path / "tests" / name, "")
+
+    result = api.explore(
+        ".",
+        root=[str(tmp_path / "src"), str(tmp_path / "tests")],
+        target="list",
+    )
+    full = api.explore(
+        ".",
+        root=[str(tmp_path / "src"), str(tmp_path / "tests")],
+        target="list",
+        result_format="full",
+    )
+
+    assert result == "\n".join(
+        [
+            "src/",
+            " codetool_explore/",
+            "tests/",
+            " test_api.py",
+            " test_cli.py",
+            " test_cursor.py",
+            " test_ignore.py",
+        ]
+    )
+    assert full["root"] == [str(tmp_path / "src"), str(tmp_path / "tests")]
+    assert full["path"] == ["src", "tests"]
+    assert full["entries"] == [
+        {"path": "src/codetool_explore/", "kind": "dir"},
+        {"path": "tests/test_api.py", "kind": "file"},
+        {"path": "tests/test_cli.py", "kind": "file"},
+        {"path": "tests/test_cursor.py", "kind": "file"},
+        {"path": "tests/test_ignore.py", "kind": "file"},
+    ]
+
+
+def test_list_target_root_list_uses_search_ignore_logic(tmp_path):
+    write(tmp_path / ".gitignore", "build/\n*.tmp\n")
+    write(tmp_path / "build" / "keep.py", "")
+    write(tmp_path / "build" / "skip.tmp", "")
+    write(tmp_path / "src" / "app.py", "")
+
+    result = api.explore(
+        ".",
+        root=[str(tmp_path / "build"), str(tmp_path / "src")],
+        target="list",
+        result_format="full",
+    )
+
+    assert result["entries"] == [
+        {"path": "build/keep.py", "kind": "file"},
+        {"path": "src/app.py", "kind": "file"},
+    ]
+
+
 def test_compressed_snippets_preserve_line_snippet_context_and_page(tmp_path):
     write(tmp_path / "a.py", "before\nneedle one\nneedle two\n")
 

{codetool_explore-0.5.0 → codetool_explore-0.6.0}/tests/test_cli.py

@@ -212,6 +212,33 @@ def test_cli_read_defaults_to_text_and_honors_line_range(tmp_path, capsys):
     assert capsys.readouterr().out == "-- more: cursor=3\ntwo\n"
 
 
+def test_cli_read_accepts_repeated_roots_with_headers(tmp_path, capsys):
+    write(tmp_path / "src" / "settings.txt", "src one\n")
+    write(tmp_path / "tests" / "settings.txt", "test one\n")
+
+    code = cli.main(
+        [
+            "--read",
+            "settings.txt",
+            "--root",
+            str(tmp_path / "src"),
+            "--root",
+            str(tmp_path / "tests"),
+        ]
+    )
+
+    assert code == 0
+    assert capsys.readouterr().out == "\n".join(
+        [
+            "src/settings.txt:",
+            "src one",
+            "tests/settings.txt:",
+            "test one",
+            "",
+        ]
+    )
+
+
 def test_cli_list_defaults_to_text(tmp_path, capsys):
     write(tmp_path / "src" / "app.py", "")
     write(tmp_path / "src" / "pkg" / "mod.py", "")
@@ -222,6 +249,36 @@ def test_cli_list_defaults_to_text(tmp_path, capsys):
     assert capsys.readouterr().out == "src/\n app.py\n pkg/\n"
 
 
+def test_cli_list_accepts_repeated_roots(tmp_path, capsys):
+    write(tmp_path / "src" / "codetool_explore" / "__init__.py", "")
+    for name in ("test_api.py", "test_cli.py", "test_cursor.py"):
+        write(tmp_path / "tests" / name, "")
+
+    code = cli.main(
+        [
+            "--list",
+            ".",
+            "--root",
+            str(tmp_path / "src"),
+            "--root",
+            str(tmp_path / "tests"),
+        ]
+    )
+
+    assert code == 0
+    assert capsys.readouterr().out == "\n".join(
+        [
+            "src/",
+            " codetool_explore/",
+            "tests/",
+            " test_api.py",
+            " test_cli.py",
+            " test_cursor.py",
+            "",
+        ]
+    )
+
+
 def test_cli_read_full_format_returns_json(tmp_path, capsys):
     write(tmp_path / "docs" / "guide.txt", "one\ntwo\n")
 

{codetool_explore-0.5.0 → codetool_explore-0.6.0}/uv.lock

@@ -86,7 +86,7 @@ wheels = [
 
 [[package]]
 name = "codetool-explore"
-version = "0.5.0"
+version = "0.6.0"
 source = { editable = "." }
 
 [package.dev-dependencies]

codetool_explore-0.5.0/.gitignore

@@ -1,19 +0,0 @@
-.venv/
-__pycache__/
-.pytest_cache/
-*.py[cod]
-rust/target/
-benchmark-corpus/
-benchmarks/corpus/
-reports/*
-!reports/research_lab_benchmark.json
-!reports/research_lab_result.html
-!reports/rtk_vs_codetool_output_length_analysis.html
-!reports/rtk_vs_codetool_output_lengths.json
-!reports/search_benchmark.json
-!reports/search_benchmark_analysis.html
-!reports/search_benchmark_rtk_compression.json
-!reports/search_compression_analysis.html
-research/
-.tmp*/
-.ruff_cache/