Skip to content

superseded release prep draft #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
sting8k wants to merge 1 commit into from
Closed

superseded release prep draft #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
45 changes: 45 additions & 0 deletions .greptile/config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
]
}
]
}
188 changes: 51 additions & 137 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
23 changes: 23 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <target-a> <target-b>` 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 <file>` 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 <query>` 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
Expand Down
Loading
Loading