From a0db68740f1912caa0dc92ce5c2b70907d3d9697 Mon Sep 17 00:00:00 2001 From: sting8k Date: Sun, 24 May 2026 22:33:31 +0700 Subject: [PATCH] feat: prepare v1.0.0 public update --- .github/workflows/ci.yml | 7 +- .greptile/config.json | 45 + AGENTS.md | 188 +--- CHANGELOG.md | 23 + Cargo.lock | 86 +- Cargo.toml | 7 + README.md | 398 ++++++-- npm/package.json | 2 +- skills/srcwalk/GUIDE.md | 254 ++--- src/artifact.rs | 64 +- src/capabilities/mod.rs | 327 +++++++ src/classify.rs | 7 +- src/cli.rs | 558 +++++++---- src/cli_run.rs | 717 ++++++++++++-- src/commands/callees.rs | 20 +- src/commands/callers.rs | 12 +- src/commands/compare.rs | 873 +++++++++++++++++ src/commands/context.rs | 80 +- src/commands/decision_flow.rs | 184 ++++ src/commands/diff.rs | 756 +++++++++++++++ src/commands/find.rs | 584 +++++++++++- src/commands/flow.rs | 306 ++++-- src/commands/impact.rs | 28 +- src/commands/mod.rs | 4 + src/commands/multi_scope.rs | 18 +- src/commands/path.rs | 79 +- src/commands/review.rs | 587 ++++++++++++ src/commands/section_disambiguation.rs | 13 +- src/error.rs | 16 +- src/evidence/anchor.rs | 106 +++ src/evidence/atom.rs | 193 ++++ src/evidence/confidence.rs | 123 +++ src/evidence/mod.rs | 12 + src/evidence/next_action.rs | 199 ++++ src/index/symbol.rs | 30 +- src/lang/css.rs | 971 +++++++++++++++++++ src/lang/decision_flow.rs | 1106 +++++++++++++++++++++ src/lang/decision_flow/evidence.rs | 393 ++++++++ src/lang/decision_flow/render.rs | 567 +++++++++++ src/lang/decision_flow/types.rs | 191 ++++ src/lang/document/html.rs | 364 +++++++ src/lang/document/markdown.rs | 327 +++++++ src/lang/document/mod.rs | 406 ++++++++ src/lang/mod.rs | 12 +- src/lang/outline.rs | 151 ++- src/lang/treesitter.rs | 47 + src/lib.rs | 282 +++++- src/main.rs | 53 +- src/map.rs | 51 +- src/output.rs | 33 +- src/read/full.rs | 54 +- src/read/imports.rs | 47 +- src/read/mod.rs | 35 +- src/read/outline/code.rs | 28 +- src/read/outline/markdown.rs | 154 --- src/read/outline/mod.rs | 6 +- src/read/section.rs | 104 +- src/read/tests.rs | 36 +- src/search/access.rs | 1219 ++++++++++++++++++++++++ src/search/callees.rs | 23 + src/search/callers/bfs.rs | 152 +-- src/search/callers/mod.rs | 4 +- src/search/callers/single.rs | 181 +++- src/search/deps.rs | 356 +++++-- src/search/display/expand.rs | 11 +- src/search/display/glob_result.rs | 37 +- src/search/display/match_item.rs | 25 +- src/search/display/mod.rs | 266 +++++- src/search/display/semantic.rs | 275 +++++- src/search/filter.rs | 38 +- src/search/glob.rs | 42 +- src/search/io.rs | 30 +- src/search/mod.rs | 82 +- src/search/symbol/batch.rs | 41 +- src/search/symbol/definitions.rs | 117 ++- src/search/symbol/glob_search.rs | 6 +- src/search/symbol/tests.rs | 35 + src/search/symbol/usages.rs | 16 +- src/types.rs | 221 ++++- tests/access_grouping.rs | 988 +++++++++++++++++++ tests/artifact_mode.rs | 261 ++++- tests/bfs_snapshots.rs | 179 ++-- tests/callees_detailed.rs | 43 +- tests/compare_command.rs | 250 +++++ tests/csharp_definitions.rs | 10 +- tests/css_support.rs | 201 ++++ tests/decision_flow.rs | 643 +++++++++++++ tests/diff_command.rs | 416 ++++++++ tests/document_support.rs | 289 ++++++ tests/files_and_symbol_glob.rs | 466 ++++++++- tests/flow_filter.rs | 683 ++++++++++++- tests/footer_tips.rs | 82 +- tests/ignore_policy.rs | 2 + tests/impact_output.rs | 10 +- tests/intent_first_cli.rs | 768 +++++++++++++++ tests/map_output.rs | 170 ++-- tests/multi_scope.rs | 56 +- tests/path_display.rs | 18 +- tests/path_exact.rs | 48 +- tests/review_command.rs | 725 ++++++++++++++ tests/semantic_compact.rs | 168 +++- tests/stylesheet_support.rs | 205 ++++ tests/subcommand_aliases.rs | 287 +++--- tests/windows_paths.rs | 49 +- 104 files changed, 20566 insertions(+), 1952 deletions(-) create mode 100644 .greptile/config.json create mode 100644 src/capabilities/mod.rs create mode 100644 src/commands/compare.rs create mode 100644 src/commands/decision_flow.rs create mode 100644 src/commands/diff.rs create mode 100644 src/commands/review.rs create mode 100644 src/evidence/anchor.rs create mode 100644 src/evidence/atom.rs create mode 100644 src/evidence/confidence.rs create mode 100644 src/evidence/mod.rs create mode 100644 src/evidence/next_action.rs create mode 100644 src/lang/css.rs create mode 100644 src/lang/decision_flow.rs create mode 100644 src/lang/decision_flow/evidence.rs create mode 100644 src/lang/decision_flow/render.rs create mode 100644 src/lang/decision_flow/types.rs create mode 100644 src/lang/document/html.rs create mode 100644 src/lang/document/markdown.rs create mode 100644 src/lang/document/mod.rs delete mode 100644 src/read/outline/markdown.rs create mode 100644 src/search/access.rs create mode 100644 tests/access_grouping.rs create mode 100644 tests/compare_command.rs create mode 100644 tests/css_support.rs create mode 100644 tests/decision_flow.rs create mode 100644 tests/diff_command.rs create mode 100644 tests/document_support.rs create mode 100644 tests/intent_first_cli.rs create mode 100644 tests/review_command.rs create mode 100644 tests/stylesheet_support.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e29c60a..7836af4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,10 +25,13 @@ jobs: - uses: Swatinem/rust-cache@v2 - run: cargo fmt --check - run: cargo clippy -- -D warnings - - run: cargo test + - run: cargo test --locked windows: runs-on: windows-latest + env: + CC: clang-cl + CXX: clang-cl steps: - uses: actions/checkout@v4 with: @@ -39,4 +42,4 @@ jobs: - uses: Swatinem/rust-cache@v2 - run: cargo fmt --check - run: cargo clippy -- -D warnings - - run: cargo test + - run: cargo test --locked diff --git a/.greptile/config.json b/.greptile/config.json new file mode 100644 index 0000000..efe87b8 --- /dev/null +++ b/.greptile/config.json @@ -0,0 +1,45 @@ +{ + "strictness": 3, + "commentTypes": [ + "logic", + "syntax" + ], + "fileChangeLimit": 200, + "triggerOnUpdates": true, + "statusCheck": true, + "statusCommentsEnabled": true, + "updateExistingSummaryComment": true, + "ignorePatterns": "target/**\nnode_modules/**\ndist/**\ncoverage/**\n.tmp*/**\n**/*.generated.*\nCargo.lock.orig\npackage-lock.json", + "excludeAuthors": [ + "github-actions[bot]", + "dependabot[bot]" + ], + "ignoreKeywords": "release:\nwip:", + "disabledLabels": [ + "no-greptile", + "wip" + ], + "instructions": "Prioritize clear correctness bugs, runtime errors, data loss risks, and missing validation. Avoid speculative edge cases and style nits. For srcwalk, focus on semantic correctness, bounded output, command behavior regressions, path/platform handling, and test coverage for changed CLI behavior.", + "rules": [ + { + "id": "bounded-agent-output", + "rule": "CLI output shown to users or agents should be bounded and avoid dumping large file contents unless explicitly requested.", + "severity": "medium", + "scope": [ + "src/**/*.rs", + "tests/**/*.rs" + ] + }, + { + "id": "semantic-evidence-honesty", + "rule": "Do not imply stronger semantic confidence than the parser or artifact evidence supports; label syntax-level or heuristic evidence clearly.", + "severity": "medium", + "scope": [ + "src/**/*.rs", + "tests/**/*.rs", + "skills/srcwalk/GUIDE.md", + "README.md" + ] + } + ] +} diff --git a/AGENTS.md b/AGENTS.md index 5ade0ff..40042e8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,162 +1,76 @@ # srcwalk -Code-intelligence CLI built on tree-sitter. Outlines, symbol search, caller/callee graphs, deps, maps — structured, token-efficient output for AI agents. +Code-intelligence CLI for AI agents. It provides target-first file reads, +structural discovery, caller/callee navigation, dependency evidence, context and +review packets, and token-aware output. ## Product North Star -srcwalk exists to maximize accurate, evidence-based links between knowledge components in a source/artifact tree, so agents can reduce manual navigation steps. +srcwalk exists to maximize accurate, evidence-based links between knowledge +components in a source or artifact tree, so agents can reduce manual navigation +steps. Priority order: + 1. Accuracy and semantic correctness. 2. Avoiding confusion, guessing, and false conclusions. 3. Reducing agent steps through structured navigation. 4. Token/output efficiency. -Do not trade correctness for prettier or shorter output. When semantic confidence is low, label the output honestly rather than implying source-level truth. +Do not trade correctness for prettier or shorter output. When semantic +confidence is low, label the output honestly rather than implying source-level +truth. -Before implementing artifact/minified/binary-tool language support, you must read `core/project/srcwalk-artifact-language-implementation-playbook-2026-05-08.md`. +## Source Of Truth -## Project structure +Read in this order: -``` -src/ - main.rs Tiny CLI entrypoint (parse CLI, completions, guide, thread pool). - cli.rs Clap CLI definitions, subcommands, RunConfig normalization. - cli_run.rs CLI dispatch/runtime routing to map/find/read/callers/callees/etc. - version.rs Version command, latest-version fetch/parse helpers. - output.rs stdout/json direct output helpers. - lib.rs Public API facade/wrappers; command implementations live in commands/. - classify.rs Query type detection (file path, glob, symbol, content). - types.rs Shared types (QueryType, Lang, OutlineEntry, etc.). - error.rs Error types with exit codes. - format.rs Output formatting helpers. - budget.rs Token budget enforcement. - map.rs Source-focused codebase map generation: structure + static local dependency relations with fixed hard cap/degrade. - cache.rs OutlineCache — DashMap of path → (mtime, outline). - session.rs Session state (expanded definition dedup). - commands/ - find.rs Core find/read/glob dispatch behind public lib wrappers. - multi_scope.rs Multi-scope find merge/header/query handling. - path.rs Exact path reads. - callers.rs Callers command service. - callees.rs Callees command service. - flow.rs Flow command service and helpers. - impact.rs Impact command service. - deps.rs Deps command service. - context.rs ArtifactMode, expanded context, artifact output helpers. - section_disambiguation.rs Bare filename + --section glob disambiguation. - lang/ - mod.rs detect_file_type(), package_root(). - outline.rs Tree-sitter outline extraction. - treesitter.rs DEFINITION_KINDS, extract_definition_name(). - detection.rs Generated/binary file detection. - read/ - mod.rs Read facade and default smart file reading. - full.rs Full/raw rendering, caps, budget cascade. - section.rs Section/range/heading/symbol/multi-section reads. - directory.rs Directory listing. - suggest.rs Similar-file suggestions and edit distance. - imports.rs Import extraction for deps. - outline/ Code, markdown, structured, tabular, fallback outlines. - search/ - mod.rs Search public wrappers/orchestration. - artifact_snippet.rs Artifact result snippet compaction. - filter.rs General field filters for search results. - display/ Search result formatting, expand budget, semantic rows, glob output. - symbol.rs Symbol search facade/wrappers. - symbol/ Definitions, usages, batch, glob, suggestions, comments helpers. - content.rs Text/regex search. - callers/ Single-hop + multi-hop BFS (up to 5 hops). - callees.rs Forward call graph extraction + resolution. - deps.rs File-level imports + dependents. - rank.rs Result ranking. - facets.rs Grouping (definitions, usages, implementations). - siblings.rs Sibling symbol surfacing. - strip.rs Noise stripping in expanded code. - truncate.rs Smart truncation for budget. - glob.rs File glob search. - io.rs Search I/O helpers. - pagination.rs Offset/limit pagination. - index/ - symbol.rs In-memory symbol index. - bloom.rs Bloom filter for fast pre-check. -npm/ npm distribution wrapper (postinstall downloads binary). -skills/srcwalk/ Agent guide sources: GUIDE.md embeds into binary; SKILL.md bootstraps agents to `srcwalk guide`. -benchmark/ Evaluation harness (26 tasks, 4 repos). -``` +1. `README.md` for user-facing behavior and install/use examples. +2. `skills/srcwalk/GUIDE.md` for agent-facing command routing behavior embedded + in the distributed skill/binary. +3. `skills/srcwalk/SKILL.md` for the small bootstrap skill contract. +4. The relevant source files and tests. -## Languages +## Build And Test -Rust, TypeScript, TSX, JavaScript, Python, Go, Java, Scala, C, C++, Ruby, PHP, C#, Swift, Elixir, Kotlin. - -## Build & test +Common commands: ```bash cargo build --release cargo test --locked cargo clippy -- -D warnings cargo fmt --check -cargo install --path . # → ~/.cargo/bin/srcwalk -``` - -Formatting workflow: after editing Rust source/tests, run `cargo fmt` before any `cargo fmt --check`/full verify command. Use `cargo fmt --check` first only when no Rust edits were made since the last format. - -Windows is part of the required verification surface. For the full current workflow, use memory `projects/srcwalk/session-state.md`; in-repo references are `.github/workflows/ci.yml` for the Linux + Windows x64 CI matrix and `tests/windows_paths.rs` for Windows path/range/filter coverage. - -When touching path parsing/display, traversal, deps/callers output, artifact/file matching, npm/release binary behavior, or other platform-sensitive code, verify the affected behavior on Windows too. Prefer the existing Windows integration tests and CI job; add or extend Windows-specific tests when the behavior is not covered. For semantic/UX changes, live-test on multiple real repos and include Windows x64 binary smoke when platform behavior could be affected. - -Do not document private VM hosts, credentials, or other sensitive environment details in this file. - -## Version bumps - -Update all release metadata, then tag: -1. `Cargo.toml` — `version = "X.Y.Z"` and package name must be `srcwalk`. -2. `npm/package.json` — `"version": "X.Y.Z"` and package name must be `srcwalk`. -3. `skills/srcwalk/GUIDE.md` — full embedded agent guide printed by `srcwalk guide`; update it when command routing, workflows, examples, caveats, or agent-facing UX changes. -4. `skills/srcwalk/SKILL.md` — small bootstrap entry; update `compatible_srcwalk` only when the bootstrap contract changes (for example, first release requiring `srcwalk guide`). Do not duplicate the full guide here. -5. `CHANGELOG.md` — add a curated `## [X.Y.Z] - YYYY-MM-DD` section. GitHub Release body is extracted from this section. -6. `cargo update -p srcwalk` — refreshes `Cargo.lock`. -7. Tag `vX.Y.Z` → CI builds binaries, creates GitHub Release, publishes crates.io/npm. - -## Release flow - -```bash -# 1. Validate -git status --short -cargo fmt --check -cargo clippy -- -D warnings -cargo test --locked -# CI must also pass the Windows x64 job. -# 2. Bump version + changelog -# Cargo.toml, npm/package.json, GUIDE.md if agent-facing behavior changed, -# SKILL.md only if bootstrap compatibility changed, CHANGELOG.md, then: -cargo update -p srcwalk # refreshes Cargo.lock -rg -n 'name = "srcwalk"|"name": "srcwalk"|version = "X.Y.Z"|"version": "X.Y.Z"|compatible_srcwalk: ">=X.Y.Z"|## \[X.Y.Z\]' \ - Cargo.toml npm/package.json Cargo.lock CHANGELOG.md skills/srcwalk/GUIDE.md skills/srcwalk/SKILL.md - -# 3. Commit & push, wait for CI green -git add -A && git commit -m "chore: bump vX.Y.Z" -git push srcwalk main -gh run list --repo sting8k/srcwalk --branch main --limit 3 -# Wait for CI ✅ - -# 4. Tag sanity: tag must not already exist and must point at current main -git fetch srcwalk --tags -git rev-parse -q --verify refs/tags/vX.Y.Z && echo "tag already exists; stop" -git tag vX.Y.Z main -git show vX.Y.Z:Cargo.toml | sed -n '1,20p' # confirm name=srcwalk, version=X.Y.Z - -# 5. Release (triggers build + publish) -git push srcwalk vX.Y.Z -gh run watch --repo sting8k/srcwalk $(gh run list --repo sting8k/srcwalk --workflow Release --limit 1 --json databaseId -q '.[0].databaseId') --exit-status - -# 6. Post-release checks -gh release view vX.Y.Z --repo sting8k/srcwalk --json assets,body | jq -# Confirm release body came from CHANGELOG.md and assets are srcwalk-*. +cargo install --path . # -> ~/.cargo/bin/srcwalk ``` -## Key conventions - -- **Split-on-touch**: modifying a mega-file (>800 LOC) >50 LOC? Split the affected concern first. -- **No speculative features**: every line traces to a request. -- **Tests**: in-source `#[cfg(test)]` modules + integration tests in `tests/`. +Formatting workflow: after editing Rust source or tests, run `cargo fmt` before +`cargo fmt --check` or full verification. Use `cargo fmt --check` first only when +no Rust edits were made since the last format. + +Windows is part of the required verification surface. When touching path +parsing/display, traversal, deps/callers output, artifact/file matching, +npm/release binary behavior, or other platform-sensitive code, verify the +affected behavior on Windows too. + +## Implementation Guardrails + +- No speculative features: every changed line must trace to a request. +- Keep output evidence-first. Do not imply stronger semantic confidence than the + parser, artifact source, or command evidence supports. +- Keep `skills/srcwalk/GUIDE.md`, `skills/srcwalk/SKILL.md`, README examples, + and CLI behavior aligned when command routing, examples, caveats, or + agent-facing UX changes. +- Tests live in in-source `#[cfg(test)]` modules and integration tests in + `tests/`. + +## Release Metadata + +For version bumps, keep these files in sync: + +1. `Cargo.toml` +2. `npm/package.json` +3. `skills/srcwalk/GUIDE.md` when agent-facing behavior changes +4. `skills/srcwalk/SKILL.md` only when the bootstrap compatibility contract + changes +5. `CHANGELOG.md` +6. `Cargo.lock` via `cargo update -p srcwalk` diff --git a/CHANGELOG.md b/CHANGELOG.md index eb3e5ba..0f59bd8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,29 @@ All notable changes to srcwalk are documented here. ## Unreleased +### Added +- Added HTML and Markdown-style document navigation support: sections, elements, + code blocks, and explicit links/assets without runtime or renderer claims. +- Added smart routing for exact minified JS/TS artifact file reads and exact + artifact-file scopes, inferred path-like file glob discovery, and explicit + comma-separated literal text OR through `discover --match any --as text`. +- Added `compare ` for structural shared/only evidence + between two known function-like source targets, with exact anchors and no + equivalence/runtime/verdict claims. +- Added intent-first CLI routing: `discover`, `show`, `trace callers`, `trace callees`, `context`, and `assess`, while preserving `overview`, `deps`, `guide`, and `version`. +- Added `show -C/--context-lines`, strict comma-separated multi-location `show`, `discover --as`, `discover --match all` same-file co-occurrence, and conservative `discover --exclude` file-pattern filtering. + +### Changed +- Renamed the repo-orientation command from `map` to `overview` to make the intent explicit. +- Upgraded `context` into the one-target understanding packet with Flow Map evidence, caller/callee neighborhood summaries, and exact next reads. +- Made `deps ` show explicit empty outbound/inbound sections so imports and dependents are visible by default. +- Updated `compare` follow-up footers to route one-target follow-up reads through `context`. +- Compact discover facets now group multiple definitions from the same file under one file header, preserving exact `:line-range` evidence while reducing repeated path tokens. +- Removed the old action-first command surface (`find`, `files`, `callers`, `callees`, `flow`, `impact`, and root analysis flags); use the intent-first commands instead. +- Root non-path query fallback was removed. Root positional input is now exact path evidence; use `srcwalk discover ` for search. +- Slash-delimited text queries are now literal text; raw regex grep belongs to + `rg`, while srcwalk text discovery stays focused on literal navigation evidence. + ## [0.5.0] - 2026-05-11 ### Added diff --git a/Cargo.lock b/Cargo.lock index 659e8d4..8e01e3c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -86,9 +86,9 @@ dependencies = [ [[package]] name = "cc" -version = "1.2.60" +version = "1.2.62" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20" +checksum = "a1dce859f0832a7d088c4f1119888ab94ef4b5d6795d1ce05afb7fe159d79f98" dependencies = [ "find-msvc-tools", "shlex", @@ -124,9 +124,9 @@ dependencies = [ [[package]] name = "clap_complete" -version = "4.6.2" +version = "4.6.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3ff7a1dccbdd8b078c2bdebff47e404615151534d5043da397ec50286816f9cb" +checksum = "e0a7a9bfdb35811f9e59832f0f05975114d2251b415fb534108e6f34060fd772" dependencies = [ "clap", ] @@ -182,9 +182,9 @@ checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28" [[package]] name = "dashmap" -version = "6.1.0" +version = "6.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5041cc499144891f3790297212f32a74fb938e5136a14943f338ef9e0ae276cf" +checksum = "e6361d5c062261c78a176addb82d4c821ae42bed6089de0e12603cd25de2059c" dependencies = [ "cfg-if", "crossbeam-utils", @@ -196,9 +196,9 @@ dependencies = [ [[package]] name = "either" -version = "1.15.0" +version = "1.16.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719" +checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e" [[package]] name = "encoding_rs" @@ -332,9 +332,9 @@ dependencies = [ [[package]] name = "hashbrown" -version = "0.17.0" +version = "0.17.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4f467dd6dccf739c208452f8014c75c18bb8301b050ad1cfb27153803edb0f51" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" [[package]] name = "heck" @@ -371,7 +371,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9" dependencies = [ "equivalent", - "hashbrown 0.17.0", + "hashbrown 0.17.1", "serde", "serde_core", ] @@ -396,15 +396,15 @@ checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2" [[package]] name = "libc" -version = "0.2.185" +version = "0.2.186" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f" +checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66" [[package]] name = "libmimalloc-sys" -version = "0.1.47" +version = "0.1.49" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2d1eacfa31c33ec25e873c136ba5669f00f9866d0688bea7be4d3f7e43067df6" +checksum = "6a45a52f43e1c16f667ccfe4dd8c85b7f7c204fd5e3bf46c5b0db9a5c3c0b8e9" dependencies = [ "cc", ] @@ -447,9 +447,9 @@ dependencies = [ [[package]] name = "mimalloc" -version = "0.1.50" +version = "0.1.52" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b3627c4272df786b9260cabaa46aec1d59c93ede723d4c3ef646c503816b0640" +checksum = "2d4139bb28d14ad1facf21d5eb8825051b326e172d216b39f6d31df53cc97862" dependencies = [ "libmimalloc-sys", ] @@ -637,9 +637,9 @@ dependencies = [ [[package]] name = "serde_json" -version = "1.0.149" +version = "1.0.150" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86" +checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9" dependencies = [ "indexmap", "itoa", @@ -698,16 +698,20 @@ dependencies = [ "tree-sitter-c", "tree-sitter-c-sharp", "tree-sitter-cpp", + "tree-sitter-css", "tree-sitter-elixir", "tree-sitter-go", + "tree-sitter-html", "tree-sitter-java", "tree-sitter-javascript", "tree-sitter-kotlin-ng", + "tree-sitter-less", "tree-sitter-php", "tree-sitter-python", "tree-sitter-ruby", "tree-sitter-rust", "tree-sitter-scala", + "tree-sitter-scss", "tree-sitter-swift", "tree-sitter-typescript", ] @@ -833,6 +837,16 @@ dependencies = [ "tree-sitter-language", ] +[[package]] +name = "tree-sitter-css" +version = "0.25.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a5cbc5e18f29a2c6d6435891f42569525cf95435a3e01c2f1947abcde178686f" +dependencies = [ + "cc", + "tree-sitter-language", +] + [[package]] name = "tree-sitter-elixir" version = "0.3.5" @@ -853,6 +867,16 @@ dependencies = [ "tree-sitter-language", ] +[[package]] +name = "tree-sitter-html" +version = "0.23.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "261b708e5d92061ede329babaaa427b819329a9d427a1d710abb0f67bbef63ee" +dependencies = [ + "cc", + "tree-sitter-language", +] + [[package]] name = "tree-sitter-java" version = "0.23.5" @@ -889,6 +913,16 @@ version = "0.1.7" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "009994f150cc0cd50ff54917d5bc8bffe8cad10ca10d81c34da2ec421ae61782" +[[package]] +name = "tree-sitter-less" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "66d4fd0af04a7338929f0e27ca078b4831de8e1ebf90ce8182e69012094a0ae0" +dependencies = [ + "cc", + "tree-sitter", +] + [[package]] name = "tree-sitter-php" version = "0.24.2" @@ -939,11 +973,21 @@ dependencies = [ "tree-sitter-language", ] +[[package]] +name = "tree-sitter-scss" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "33909a9ca86390ebbf3461e9949c4bbe2767d2d024b486306d27616641d4ba24" +dependencies = [ + "cc", + "tree-sitter", +] + [[package]] name = "tree-sitter-swift" -version = "0.7.1" +version = "0.7.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4ef216011c3e3df4fa864736f347cb8d509b1066cf0c8549fb1fd81ac9832e59" +checksum = "f3b98fb6bc8e6a6a10023f401aa6a1858115e849dfaf7de57dd8b8ea0f257bd9" dependencies = [ "cc", "tree-sitter-language", diff --git a/Cargo.toml b/Cargo.toml index b3a7a7a..eb465fb 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,9 @@ keywords = ["code-search", "tree-sitter", "developer-tools", "ai-agents", "code- categories = ["command-line-utilities", "development-tools"] authors = ["sting8k"] +[features] +default = [] + [[bin]] name = "srcwalk" path = "src/main.rs" @@ -65,6 +68,10 @@ serde = { version = "1", features = ["derive"] } serde_json = "1" toml = "0.8" indexmap = "2.14.0" +tree-sitter-css = "0.25.0" +tree-sitter-scss = "1.0.0" +tree-sitter-less = "1.0.0" +tree-sitter-html = "0.23.2" [dev-dependencies] diff --git a/README.md b/README.md index efab1f0..330c4ca 100644 --- a/README.md +++ b/README.md @@ -7,22 +7,25 @@ **Agent's code navigator CLI** — target-first file reading, action-first code analysis, one binary, zero config. -> Tree-sitter outlines · symbol search · caller/callee graphs · deps · maps · token-aware footers +> Tree-sitter outlines · symbol search · caller/callee graphs · context/review packets · deps · overview -File reads default to structural views, not raw full-file dumps. Use target-first reads for files (`srcwalk `, `:`, `--section`) and action-first commands for analysis (`find`, `callers`, `callees`, `deps`, `map`). +File reads default to structural views, not raw full-file dumps. Use target-first reads for files (`srcwalk `, `:`, `--section`) and action-first commands for analysis (`discover`, `review`, `callers`, `callees`, `deps`, `overview`). > Originally forked from [jahala/tilth](https://github.com/jahala/tilth), now developed independently. ## What it does - **Read** — structural outline by default; `--section` and capped `--full` for explicit raw pages -- **Find** — tree-sitter definitions first, then usages, with optional inline source +- **Find** — tree-sitter definitions first, usages, smart literal OR defaults, field/member access grouping, confirmed context next targets, and optional inline source - **Callers** — single-hop or multi-hop BFS (up to 5 hops), hub guard, collision warnings - **Callees** — forward call graph, resolved + unresolved, with depth support -- **Deps** — blast-radius: imports and dependents of a file -- **Map** — token-annotated directory skeleton, respects `.gitignore`, `.ignore`, git excludes, and parent ignores +- **Deps** — blast-radius: imports, document links/assets, and dependents of a file +- **Context** — one-target understanding packets with Flow Maps, compact call/read evidence, bounded call neighborhood summaries, and exact `> Next:` commands +- **Review** — Review Packets for git changes, with bounded Flow Maps for changed targets, changed evidence, and exact `> Next:` footer commands +- **Compare** — structural shared/only evidence for two known source targets without equivalence or verdict claims +- **Overview** — token-annotated directory skeleton, respects `.gitignore`, `.ignore`, git excludes, and parent ignores -Structural support for Rust, TypeScript, TSX, JavaScript, Python, Go, Java, Scala, C, C++, Ruby, PHP, C#, Swift, Elixir, and Kotlin. Unsupported files still get smart text/outline reads. +Structural support covers Rust, TypeScript, TSX, JavaScript, Python, Go, Java, Scala, C, C++, Ruby, PHP, C#, Swift, Elixir, Kotlin, CSS (`.css`), SCSS (`.scss`), and Less (`.less`). Document navigation support covers HTML (`.html`, `.htm`) and Markdown-style files (`.md`, `.mdx`; `.rst` uses the same document fallback) with sections/elements/code blocks and explicit links/assets. Stylesheet support covers selectors, at-rules, heading-like comment sections, variables/properties, mixins/functions where the language has them, and explicit import/`url(...)` deps; call graph commands remain for executable code. Unsupported files still get smart text/outline reads. ## Install @@ -70,6 +73,8 @@ See [`CHANGELOG.md`](./CHANGELOG.md) for curated release notes. Maintainers shou ## Quick examples +Agent routing order lives in `srcwalk guide`; examples below are command reference, not a workflow. + ```sh # Read a file (structural view by default; raw pages are explicit) srcwalk src/auth.ts @@ -78,58 +83,103 @@ srcwalk src/auth.ts --section handleAuth # drill into symbol srcwalk src/auth.ts --section 72 # focused line context srcwalk src/auth.ts --section 44-89 # line range -# Find definitions/usages/text/name globs -srcwalk find handleAuth --scope src/ # definitions + usages -srcwalk find "foo, bar" --scope src/ --scope tests/ # multi-symbol + multi-scope -srcwalk find '*Controller' --scope src/ --filter kind:class -srcwalk find handleAuth --scope src/ --expand # inline source context -srcwalk files '*.ts' --scope src/ # file globs live under files - -# Callers (reverse call graph) -srcwalk callers handleAuth --scope src/ -srcwalk callers decompileFunction --filter 'args:3' --scope src/ -srcwalk callers handleAuth --count-by caller --scope src/ - -# Callees (forward call graph) -srcwalk callees handleAuth --scope src/ -srcwalk callees handleAuth --detailed --filter 'callee:validateToken' --scope src/ -srcwalk callees handleAuth --depth 2 --scope src/ # transitive - -# Flow (compact slice: ordered calls + local resolves + callers) -srcwalk flow handleAuth --filter 'callee:validateToken' --scope src/ - -# Impact (heuristic blast-radius triage) -srcwalk impact validateToken --scope src/ - -# Deps (blast radius) +# Discover definitions/usages/text/name globs/files +srcwalk discover handleAuth --scope src/ # definitions + usages +srcwalk discover handleAuth --scope src/auth.ts # exact-file scope +srcwalk discover handleAuth --scope 'src/**/*.ts' # glob scope +srcwalk discover handleAuth --scope src/auth.ts:40-90 # exact-file range scope +srcwalk discover "foo, bar" --scope src/ --scope tests/ # multi-symbol + multi-scope +srcwalk discover is_args --as access --scope src/ # file-grouped field/member access +srcwalk discover '*Controller' --as symbol --scope src/ --filter kind:class +srcwalk discover handleAuth --scope src/ --expand # inline source context +srcwalk discover '*.ts' --scope src/ # file globs are inferred +srcwalk discover handleAuth --scope src/ --exclude '*test*' # exclude file patterns +srcwalk discover 'alloc,copy' --match any --as text --scope src/ # literal text OR +srcwalk discover 'alloc,copy' --match all --as text --scope src/ # same-file co-occurrence +# Raw regex grep remains an rg job; srcwalk text discovery is literal navigation evidence. + +# Trace callers (reverse call graph) +srcwalk trace callers handleAuth --scope src/ +srcwalk trace callers decompileFunction --filter 'args:3' --scope src/ +srcwalk trace callers handleAuth --count-by caller --scope src/ # grouped compact output + +# Trace callees (forward call graph) +srcwalk trace callees handleAuth --scope src/ +srcwalk trace callees handleAuth --detailed --filter 'callee:validateToken' --scope src/ +srcwalk trace callees handleAuth --depth 2 --scope src/ # transitive + +# Context and Review Packets with Flow Maps +srcwalk context src/auth.ts:handleAuth # one-target Flow Map + neighborhood + Next footer +srcwalk review --staged # staged change Review Packet +srcwalk review HEAD~1..HEAD --scope src # changed evidence + changed-symbol Flow Maps + +# Compare two known targets structurally +srcwalk compare src/auth.ts:validateToken src/auth.ts:validateSession + +# Context (compact slice: ordered calls + local resolves + callers) +srcwalk context handleAuth --filter 'callee:validateToken' --scope src/ + +# Assess (heuristic blast-radius triage) +srcwalk assess validateToken --scope src/ + +# Deps (file coupling) srcwalk deps src/auth.ts +srcwalk deps docs/guide.md # Markdown/HTML links and assets -# Map -srcwalk map --scope src/ +# Overview +srcwalk overview --scope src/ ``` Discovery commands respect ignore files; explicit file reads can still inspect ignored paths. ## Output examples +Examples below use this repository. Timings may vary between machines; snippets are abbreviated only where `...` is shown. +
-Outline of a large file +Outline of a file ``` -$ srcwalk src/auth.ts -# src/auth.ts (258 lines, ~3.4k tokens) [outline] - -[1-12] imports: express(2), jsonwebtoken, @/config -[14-22] interface AuthConfig -[24-42] fn validateToken - function validateToken(token: string): Claims | null -[44-89] fn handleAuth - export function handleAuth(req, res, next) -[91-258] class AuthManager - [99-130] fn authenticate - [132-180] fn authorize +$ srcwalk src/evidence/next_action.rs +# src/evidence/next_action.rs (198 lines, ~1.2k tokens) [outline] + +[1-] imports: std::collections::BTreeMap, std::fmt::Write as _, crate::evidence +[7-13] struct NextAction +[16-21] enum NextActionConfidence +[23-107] mod impl NextAction + [24-38] fn new + pub(crate) fn new( + [40-54] fn from_evidence + pub(crate) fn from_evidence( + [56-68] fn metadata + pub(crate) fn metadata( + [70-76] fn guidance + pub(crate) fn guidance( + [78-80] fn command + pub(crate) fn command(&self) -> &str + [82-84] fn reason + pub(crate) fn reason(&self) -> &str + [86-88] fn rank + pub(crate) const fn rank(&self) -> u16 + [90-92] fn confidence + pub(crate) const fn confidence(&self) -> NextActionConfidence + [94-96] fn source_anchor + pub(crate) fn source_anchor(&self) -> Option<&Anchor> + [98-106] fn sort_key + fn sort_key(&self) -> (u16, u8, u32, &str, &str) +[109-118] mod impl NextActionConfidence + [110-117] fn sort_rank + const fn sort_rank(self) -> u8 +[120-127] mod impl NextActionConfidence + [121-126] fn from + fn from(source: EvidenceSource) -> Self +[129-139] fn render_next_actions + pub(crate) fn render_next_actions(actions: &[NextAction]) -> String +[141-157] fn ordered_unique + fn ordered_unique(actions: &[NextAction]) -> Vec > Next: drill into a symbol with --section or a line range +> Next: need raw file text? retry with --full, or use --section for a smaller slice. ```
@@ -137,48 +187,196 @@ $ srcwalk src/auth.ts Compact multi-section read ``` -$ srcwalk src/auth.ts --section "handleAuth,120-140,authorize" --budget 900 -# src/auth.ts (86 lines, ~1.1k tokens) [2 sections, compact (over limit)] +$ srcwalk src/evidence/next_action.rs --section "NextAction,render_next_actions,ordered_unique" --budget 260 +# src/evidence/next_action.rs (35 lines, ~272 tokens) [3 symbols, compact (over limit)] + +## section: NextAction [7-13] (compact) + + 7 │ pub(crate) struct NextAction { + 8 │ command: String, + 9 │ reason: String, + ... 4 lines omitted; narrow --section or raise --budget. + +--- -## section: handleAuth, 120-140 [44-140] (compact) +## section: render_next_actions [129-139] (compact) - 44 │ export function handleAuth(req, res, next) { - 45 │ const token = req.headers.authorization?.split(' ')[1]; - ... -► 120 │ audit.log({ user, route: req.path }); - ... 82 lines omitted; narrow --section or raise --budget. + 129 │ pub(crate) fn render_next_actions(actions: &[NextAction]) -> String { + 130 │ let actions = ordered_unique(actions); + 131 │ let mut out = String::new(); + ... 8 lines omitted; narrow --section or raise --budget. --- -## section: authorize [132-180] (compact) +## section: ordered_unique [141-157] (compact) - 132 │ authorize(user, resource) { - 133 │ return this.policy.can(user, resource); - ... 46 lines omitted; narrow --section or raise --budget. + 141 │ fn ordered_unique(actions: &[NextAction]) -> Vec { + 142 │ let mut by_command = BTreeMap::::new(); + 143 │ for action in actions { + ... 14 lines omitted; narrow --section or raise --budget. -> Caveat: compacted ~1100/900 tokens; shown 2 sections. +> Caveat: compacted ~272/260 tokens; shown 3 symbols. > Next: narrow --section or raise --budget. ```
-Find — multi-symbol and multi-scope +Context packet — Flow Map + call neighborhood ``` -$ srcwalk find "handleAuth, validateToken" --scope src --scope tests --limit 2 -# Search: "handleAuth" in 2 scopes — 2 matches (1 definitions, 1 usages) -Scopes on this page: src (1), tests (1) - [fn] handleAuth src/auth.ts:44-89 - [usage] tests/auth.test.ts:18 handleAuth(req, res, next) +$ srcwalk context src/evidence/next_action.rs:ordered_unique --budget 1400 +# Context Packet: src/evidence/next_action.rs:ordered_unique +confidence: structural syntax +caveat: source-evidence navigation only; no runtime proof + +## Target +- src/evidence/next_action.rs:141-157 ordered_unique + +## Flow Map +shape: 1 entry, 0 decisions, 1 loop, 1 exit, 4 actions +N1 entry :141-157 entry + next -> N2 action :142 BTreeMap::::new() +N2 action :142 BTreeMap::::new() + calls: BTreeMap::::new :142 + next -> N3 loop :143-152 actions +N3 loop :143-152 actions + body -> N4 action :144-151 by_command .entry(action.command.clone()) .and_modify(|existing| { if action.sort_key() < exist… + next -> N5 action :154 by_command.into_values().collect() +N4 action :144-151 by_command .entry(action.command.clone()) .and_modify(|existing| { if action.sort_key() < exist… + calls: by_command .entry :144 + reads: action.clone call_arg :151 + loop_back -> N3 loop :143-152 actions +N5 action :154 by_command.into_values().collect() + calls: by_command.into_values :154 + next -> N6 action :155 actions.sort_by(|left, right| left.sort_key().cmp(&right.sort_key())) +N6 action :155 actions.sort_by(|left, right| left.sort_key().cmp(&right.sort_key())) + calls: actions.sort_by :155 + reads: left.sort_key().cmp call_arg :155; right.sort_key call_arg :155 + next -> N7 return :157 end +N7 return :157 end + +## Exits +- :157 end + +## Call Neighborhood +### Callees (ordered) +- L142 by_command = BTreeMap::::new() +- L151 by_command.entry(action.command.clone()).and_modify(|existing| { if action.sort_key() < existing.sort_key() { *existing = action.clone(); } }).or_insert_with(arg1=|| action.clone()) +- L154 actions = by_command.into_values().collect() +- L155 actions.sort_by(arg1=|left, right| left.sort_key().cmp(&right.sort_key())) + +### Resolved local callees + [fn] NextAction src/evidence/next_action.rs:7-13 + [fn] new src/evidence/next_action.rs:24-38 pub(crate) fn new( + [fn] sort_key src/evidence/next_action.rs:98-106 fn sort_key(&self) -> (u16, u8, u32, &str, &str) + + +### Callers +- [fn] render_next_actions src/evidence/next_action.rs:130 + +> Caveat: static context packet is capped; verify exact edges with trace commands. + +> Next: srcwalk show src/evidence/next_action.rs:141-157 -C 20 +> Next: srcwalk trace callers ordered_unique +> Next: srcwalk trace callees ordered_unique --detailed +``` +
+ +
+Review packet — changed evidence + next reads + +For staged or revision-range reviews, srcwalk summarizes the changed files, +hunks, changed symbols, bounded Flow Maps, and exact follow-up reads. + +``` +$ srcwalk review --staged --budget 1200 +# Review Packet: staged +confidence: structural syntax + diff metadata +caveat: source-evidence navigation only; no runtime proof +files: changed=1 shown=1 +hunks: total=1 shown=1 +symbols: total=0 shown=0 + +## changed evidence + +### README.md +status: modified +hunks: +- :286-323 file-level + +## changed symbols +- none function-like in selected diff evidence -> Next: 3 more matches available. Continue with --offset 2 --limit 2. +## flow maps +- none rendered; no changed function-like symbols in selected files + +## omitted +- files: 0 +- flow maps: 0 + +> Next: srcwalk show README.md:286-323 -C 20 + +(~131 tokens) +``` +
+ +
+Discover — multi-symbol and multi-scope + +``` +$ srcwalk discover "render_next_actions, Anchor" --scope src/evidence --scope src/commands --limit 2 +# Search: "render_next_actions" in 2 scopes — 2 matches (1 definitions, 1 usages) +Scopes on this page: src/evidence (2), src/commands (0) + [fn] render_next_actions src/evidence/next_action.rs:129-139 + +## src/evidence/mod.rs:9 [usage] +→ [9] pub(crate) use next_action::{render_next_actions, NextAction}; + +## Confirmed next context targets +> Next: srcwalk context src/evidence/next_action.rs:129-139 + +(~101 tokens) + +> Next: 25 more matches available. Continue with --offset 2 --limit 2. > Next: drill into any hit with `srcwalk :`. --- -# Search: "validateToken" in 2 scopes — 2 matches (1 definitions, 1 usages) -Scopes on this page: src (1), tests (1) - [fn] validateToken src/auth.ts:24-42 - [usage] tests/auth.test.ts:9 validateToken(token) +# Search: "Anchor" in 2 scopes — 2 matches (1 definitions, 1 usages) +Scopes on this page: src/evidence (2), src/commands (0) + +### File overview: src/evidence/anchor.rs (106 lines) +[1-] imports: std::path, crate::format +[6-9] struct Anchor +[12-16] enum AnchorRange +[18-65] mod impl Anchor + [19-24] fn file + pub(crate) fn file(path: &Path) -> Self + [26-32] fn line + pub(crate) fn line(path: &Path, line: u32) -> Self + [34-41] fn lines + pub(crate) fn lines(path: &Path, start: u32, end: u32) -> Self + [43-48] fn start_line + pub(crate) const fn start_line(&self) -> u32 + [50-52] fn display + pub(crate) fn display(&self) -> String + [54-56] fn display_relative_to + pub(crate) fn display_relative_to(&self, scope: &Path) -> String + [58-64] fn display_with_path + fn display_with_path(&self, path: &str) -> String + [struct] Anchor src/evidence/anchor.rs:6-9 + +## src/evidence/anchor.rs:18 [usage] +→ [18] impl Anchor { + [6-9] struct Anchor + [12-16] enum AnchorRange +→ [18-65] mod impl Anchor + [19-24] fn file + pub(crate) fn file(path: &Path) -> Self + +(~418 tokens) + +> Next: 38 more matches available. Continue with --offset 2 --limit 2. +> Next: drill into any hit with `srcwalk :`. ```
@@ -188,22 +386,24 @@ Scopes on this page: src (1), tests (1) Trace callers transitively in one call: ``` -$ srcwalk callers NewClient --depth 3 --json -{ - "edges": [ - { "hop": 1, "from": "newDefaultClient", "from_file": "client/factory.go", - "to": "NewClient", "call_text": "return NewClient(opts)" }, - { "hop": 2, "from": "Bootstrap", "from_file": "cmd/server/main.go", - "to": "newDefaultClient", "call_text": "c, err := newDefaultClient(cfg)" }, - { "hop": 3, "from": "main", "from_file": "cmd/server/main.go", - "to": "Bootstrap", "call_text": "if err := Bootstrap(ctx); err != nil {" } - ], - "stats": { "edges_per_hop": [4, 7, 3], "suspicious_hops": [] }, - "elided": { "auto_hubs_promoted": ["Error"], "edges_truncated": 0 } -} +$ srcwalk trace callers sort_key --scope src --depth 2 +# BFS callers of "sort_key" in src — depth=2/2, 5 edges, 13 ms + +── hop 1 (4 edges) ── + ordered_unique src/evidence/next_action.rs:147 → if action.sort_key() < existing.sort_key() { + ordered_unique src/evidence/next_action.rs:147 → if action.sort_key() < existing.sort_key() { + ordered_unique src/evidence/next_action.rs:155 → actions.sort_by(|left, right| left.sort_key().cmp(&right.sort_key())); + ordered_unique src/evidence/next_action.rs:155 → actions.sort_by(|left, right| left.sort_key().cmp(&right.sort_key())); + +── hop 2 (1 edge) ── + render_next_actions src/evidence/next_action.rs:130 → let actions = ordered_unique(actions); + +Static by-name call graph only. May miss indirect dispatch, reflection, macros, and calls from files > 500KB or from languages without a tree-sitter call query. + +(~225 tokens) ``` -`call_text` disambiguates overloads. `suspicious_hops` flags cross-package name collisions. `auto_hubs_promoted` shows fan-out-capped symbols. +Call-site source text disambiguates overloads. Budget notes flag cross-package name collisions and fan-out-capped symbols when they occur. @@ -211,28 +411,29 @@ $ srcwalk callers NewClient --depth 3 --json Did-you-mean — cross-convention + typo tolerance ``` -$ srcwalk find read_file_with_budgt --scope src -# Search: "read_file_with_budgt" in src — 0 matches +$ srcwalk discover next_actoin --scope src/evidence +# Search: "next_actoin" in src/evidence — 0 matches (~14 tokens) -> Did you mean: read_file_with_budget (src/lib.rs:686)? +> Did you mean: NextAction (src/evidence/next_action.rs:7), next_action (src/evidence/mod.rs:4)? ```
-Token-aware map +Token-aware overview ``` -$ srcwalk map --scope . -# Map: . (depth 3, sizes ~= tokens) -# Note: respects .gitignore, .ignore, and parent ignores; explicit file reads can still inspect ignored paths. - -src/ ~180k - search/ ~87k - read/ ~26k - -> Next: add --symbols, or narrow with --scope . +$ srcwalk overview --scope src/evidence --depth 1 +# Overview: src/evidence (depth 1, sizes ~= tokens) +# Note: respects .gitignore, .git/info/exclude, core.excludesFile, .ignore (+ parents); dotfiles included; built-in SKIP_DIRS still apply (target, node_modules, …). Use `srcwalk ` to inspect an ignored file directly. +atom.rs ~1.3k +next_action.rs ~1.3k +anchor.rs ~714 +confidence.rs ~269 +mod.rs ~82 + +> Next: no cross-group relations shown. Use `srcwalk deps ` for file-level deps, or adjust --scope/--depth. ```
@@ -242,13 +443,14 @@ src/ ~180k |-----------|-----------|-------------| | File read + outline | ~18ms | ~18ms | | Find definitions/usages | ~27ms | — | -| Map | ~21ms | ~240ms | +| Overview | ~21ms | ~240ms | Bloom-filter pruning + length-sorted memchr + tree-sitter parse cache. ## Key features -- **Command-first analysis** — `find`, `callers`, `callees`, `flow`, `impact`, `deps`, `map`. +- **Intent-first analysis** — `discover`, `review`, `context`, `trace callers`, + `trace callees`, `assess`, `deps`, `overview`. - **Target-first reading** — `srcwalk `, `:`, and `--section `. - **Multi-hop caller BFS** — up to 5 hops, hub guard, collision detection. - **Forward callees** — resolved/unresolved calls, detailed ordered call sites, and depth support. diff --git a/npm/package.json b/npm/package.json index 6314d13..d973143 100644 --- a/npm/package.json +++ b/npm/package.json @@ -1,7 +1,7 @@ { "name": "srcwalk", "version": "0.5.0", - "description": "Code-intelligence CLI for AI agents — tree-sitter outlines, symbol search, caller/callee graphs, deps, maps", + "description": "Code-intelligence CLI for AI agents — tree-sitter outlines, symbol search, caller/callee graphs, deps, overview", "bin": { "srcwalk": "run.js" }, diff --git a/skills/srcwalk/GUIDE.md b/skills/srcwalk/GUIDE.md index 32da4ba..d664a18 100644 --- a/skills/srcwalk/GUIDE.md +++ b/skills/srcwalk/GUIDE.md @@ -1,187 +1,227 @@ # srcwalk — agent routing policy -Use srcwalk before shell search for code navigation. Route by task. Keep `--scope` narrow. Use raw `rg` only for last-mile text confirmation. +Use srcwalk before shell search for code navigation. Keep `--scope` narrow. +Use raw `rg` only for final text confirmation. + +## Default workflow + +Use this command flow for broad, unfamiliar, or risky code tasks: + +```text +request / bug / feature question + -> srcwalk overview --scope + -> srcwalk discover --scope + -> pick one plausible target from discovery output + -> srcwalk context --scope + -> srcwalk show : + -> srcwalk trace callers --scope + -> srcwalk trace callees --detailed --scope + -> srcwalk deps + -> srcwalk assess --scope + -> edit + -> srcwalk review --staged + -> run relevant tests + -> rg for final raw text or regex confirmation only +``` + +## Interpret evidence labels + +When output includes `source`, `kind`, `confidence`, or `caveat`, treat them as trust bounds. + +- structural syntax/source: navigation evidence, not runtime proof. +- text/comment/file: literal evidence, not semantic relation proof. +- document: navigation structure, not rendered or runtime behavior. +- artifact: artifact-level or byte-span evidence unless labeled source-level. ## Routes +### Orient an unfamiliar area + Do not start orientation with shell `tree`, shell `find`, repeated `ls`, or repo-wide `rg`. ```bash -srcwalk map --scope +srcwalk overview --scope ``` -Use `srcwalk find` for symbols, usages, text, and symbol/name globs. +Use auto depth first. Do not pass `--depth` first. Explicit `--depth N` is strict. -```bash -srcwalk find --scope -srcwalk find "A, B, C" --scope src --scope tests -srcwalk find '*Controller' --scope -srcwalk find 'displayAjax{Update,Refresh}*' --scope --filter kind:fn -``` +`[relations]` are static local dependency groups, not runtime calls. +`[outbound deps]` imports targets outside `--scope`. -Use `srcwalk files` for project file discovery by filename/glob. Do not use shell `find`/`fd` for codebase navigation. Do not use `srcwalk find` as filename search. +Drill down with candidate intake, then context. ```bash -srcwalk files '' --scope -srcwalk files '**/*.' --scope -srcwalk files '**' --scope +srcwalk discover --scope +srcwalk discover '' --as file --scope +srcwalk discover --as text --scope +srcwalk context --scope ``` -Use shell `find`/`fd` only for filesystem metadata that srcwalk does not model: permissions, mtimes, empty dirs, symlinks, binary assets, generated outputs, or cleanup candidate lists. +`discover` searches only inside `--scope`; narrow scopes can hide definitions. -```bash -# filesystem metadata / cleanup inventory -find -type f -mtime -1 -find -empty -fd -HI -t f -x stat -``` +`--filter kind: