srcwalk 0.2.2

Tree-sitter indexed lookups — smart code reading for AI agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

# srcwalk

Code-intelligence CLI built on tree-sitter. Outlines, symbol search, caller/callee graphs, deps, maps — structured, token-efficient output for AI agents.

## Project structure

```
src/
  main.rs              CLI entry (clap). Dispatches to map, callees, or single-query.
  lib.rs               Public API: classify → read/search/glob → formatted output.
  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               Codebase map generation.
  overview.rs          Codebase fingerprinting.
  cache.rs             OutlineCache — DashMap of path → (mtime, outline).
  session.rs           Session state (expanded definition dedup).
  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             Smart file reading (full vs outline by token count).
    imports.rs         Import extraction for deps.
    outline/           Code, markdown, structured, tabular, fallback outlines.
  search/
    mod.rs             Search orchestration.
    symbol.rs          AST-based symbol search (definitions first).
    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 skill — full command reference.
benchmark/             Evaluation harness (26 tasks, 4 repos).
```

## Languages

Rust, TypeScript, TSX, JavaScript, Python, Go, Java, Scala, C, C++, Ruby, PHP, C#, Swift, Elixir.

## Build & test

```bash
cargo build --release
cargo test
cargo clippy -- -D warnings
cargo fmt --check
cargo install --path .       # → ~/.cargo/bin/srcwalk
```

## 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/SKILL.md` — update `compatible_srcwalk` when CLI behavior changes.
4. `CHANGELOG.md` — add a curated `## [X.Y.Z] - YYYY-MM-DD` section. GitHub Release body is extracted from this section.
5. `cargo update -p srcwalk` — refreshes `Cargo.lock`.
6. 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

# 2. Bump version + changelog
# Cargo.toml, npm/package.json, skills/srcwalk/SKILL.md, CHANGELOG.md, then:
cargo update -p srcwalk   # refreshes Cargo.lock
rg -n 'name = "srcwalk"|"name": "srcwalk"|version = "X.Y.Z"|"version": "X.Y.Z"|## \[X.Y.Z\]' \
  Cargo.toml npm/package.json Cargo.lock CHANGELOG.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-*.
```

## 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/`.