[sundaysebasidian-byte]

Summary

Closes #49.

get_file_map("src") now selects that directory, sorts files before pagination, defaults to 200 files (maximum 1000), and reports directory-wide totals plus limit, offset, and truncated. Unmatched directories and invalid pagination return an error.

CLI statistics and scan --all explicitly request the complete selected index, including already-indexed files outside its project directory. MCP responses remain scoped and paginated.

Merged main d8d9152e3a63d1bea342af32ddd37ee06be08bac into the existing branch without rewriting history. Both changelog entries are retained, along with #75's symbol-search ranking/pagination and upstream CLI behavior and tests. The PR still changes the original seven files. No repository dependencies or workflows changed.

Validation

Cloud Linux/Python 3.12.14, using an isolated environment installed from the existing .[dev] dependencies and temporary XDG data/config directories:

• File-map, search-pagination, CLI query/stats, query-engine and MCP tests: 136 passed.
• Full suite: 832 passed, 1 existing skip; 89.57% coverage (80% required).
• Repository-wide Ruff lint/format checks and git diff --check passed.
• Advisory mypy: the same 335 existing errors as main, with no additions after mapping unchanged source lines.
• A separate Codex agent independently reviewed preservation of both parents and reran file-map/search tests: 58 passed, no blocking findings.

Current head: 35e0277a61cb900f32f2dede4f91a1ce55f2fa41. Its tree 0c43719666d11907f3fb2b1cca3098ebc997f84d matches the tested and independently reviewed tree. New-head CI and token benchmark passed for this head: Ubuntu/Python 3.12 and 3.13 full test/coverage jobs, Ruff, and the token benchmark. The CI merge tree also matches the tested tree.

Checklist

• Tests cover changed behavior with real SQLite.
• Ruff lint and formatting pass.
• No new mypy errors.
• Existing tests pass.
• Public documentation, README, agent-guide example and changelog updated.
• Conventional commits.

The limit bounds returned file count; indexed records are still loaded, so database work and response bytes are not bounded. truncated includes files before a nonzero offset. Python callers can use limit=None for a complete map. Windows and an actual 8.6K-file monorepo were not tested here.

AI assistance: implementation, synchronization, validation and this description were prepared with Codex; a separate Codex agent performed the independent review.

[knight22-21]

Thanks for working on this! Please note that this pull request is currently marked as draft, so it cannot be reviewed or merged until it is marked as ready for review. Please convert it to ready for review when you are ready for maintainer review.

[knight22-21]

Thanks @sundaysebasidian-byte! We have merged PR #75 into \main, which introduced a merge conflict (primarily in \docs/changelog.md). Could you please update your branch / rebase onto the latest \main\ to resolve the conflict? Once updated and CI checks pass, we will be ready to review and merge this.

[knight22-21]

Thanks @sundaysebasidian-byte! We have merged PR #76 into \main, which introduced a merge conflict (primarily in \docs/changelog.md). Could you please update your branch / rebase onto the latest \main\ to resolve the conflict? Once updated and CI checks pass, we will be ready to review and merge this.

[knight22-21]

LGTM! Clean implementation scoping get_file_map with pagination limits and metadata, backed by solid SQLite regression tests.

[knight22-21]

Merged, thank you @sundaysebasidian-byte! This scopes file map queries to the requested directory and bounds responses with pagination limits.