feat: selector round-trip + canonical discover emission (1.7.0)

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to srcwalk are documented here.
 
+## [1.7.0] - 2026-08-13
+
+### Added
+- Shared typed `path:symbol` selector grammar with a single resolution seam, consumed by `show`, `context`, and `trace`, so canonical selectors round-trip between command output and command input.
+- `discover` emits the canonical owning-container selector for resolvable hits, including per-term sections of batch (comma-separated) queries, derived from outline primitives.
+
+### Fixed
+- Exact selector evidence is preserved through display instead of being rewritten into non-resolvable forms.
+- Copyable path displays are classified consistently across discover/show/callers output.
+
+### Known limitations
+- Dotted bare terms inside batch discover queries (e.g. `discover 'A.b,C'`) still resolve as free-text for the dotted term; the canonical selector for that term is not emitted. Single-term dotted queries are unaffected.
+
 ## [1.6.0] - 2026-08-12
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "srcwalk"
-version = "1.6.0"
+version = "1.7.0"
 edition = "2021"
 description = "Tree-sitter indexed lookups — smart code reading for AI agents"
 license = "MIT"

npm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "srcwalk",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Code-intelligence CLI for AI agents — tree-sitter outlines, symbol search, caller/callee graphs, deps, overview",
   "bin": {
     "srcwalk": "run.js"

skills/srcwalk/GUIDE.md

@@ -28,7 +28,7 @@ Turn the request's explicit evidence questions into a short coverage list. In ea
 - Multi-root symbol discovery may repeat the flag: `srcwalk discover 'foo,bar' --as symbol --scope src --scope tests`.
 - Other routes and `discover --as text|file|access` accept one scope; use a common ancestor or run independent commands in the same model/tool round.
 - Keep scope as small as the evidence question allows; narrow scopes can hide definitions.
-- Symbol batches accept 2-5 comma-separated symbols: `srcwalk discover 'foo,bar,baz' --as symbol --scope src`. Split larger symbol sets. One dot qualifies a method by receiver/container: `'Batch.Set'`.
+- Symbol batches accept 2-5 comma-separated symbols: `srcwalk discover 'foo,bar,baz' --as symbol --scope src`. Split larger symbol sets. One dot qualifies a method by receiver/container in a single-symbol query (`'Batch.Set'`); dotted terms inside a batch are a known matching limitation, so run that dotted term separately when exact qualification is required.
 - Text OR is separate: `srcwalk discover 'alloc,copy' --match any --as text --scope src` is literal text evidence, not a symbol batch.
 - Do not infer definitions, usages, callers, deps, or code paths from shell path lists, broad grep, or converted identifier paths.
 
@@ -66,7 +66,7 @@ Use auto overview depth first; explicit `--depth N` is strict. Narrow `overview
 
 Intent inference: path-like globs infer file discovery; punctuation/path comma lists infer literal Text OR; symbol globs stay symbol search. Add `--as symbol|file|text|access` when ambiguous. After a first pass, use `--expand=3`, `--filter kind:fn`, or `--exclude 'tests/**'` only when output is too broad. Regex-style queries are translated, not executed as regex: `foo\(` de-escapes to literal + symbol search, `a.*b` runs same-line ordered co-occurrence, `models\.json` behaves like `models.json`, and an unresolved path fragment like `packages/ai` lists matching relative paths (≤20). Each translation is labeled `interpreted as`; zero-match branches print a `> Try:` recovery line. Windows drive paths and `./`/`../` paths are never treated as regex. Text Search and Text OR may add a conditional `> Note:` when a term has at least 400 matches across at least 150 files and reaches at least 1.5% of eligible files; treat it as measured spread, then consider `overview`, a narrower term or scope, or a structural route when that spread was not intentional.
 
-If `discover` prints `## Confirmed structural targets`, run the printed `> Next:` command verbatim. It is symbol-addressed (`show <path> --section <symbol>`) when the selector round-trips to the exact body; a numeric `<path>:<start-end>` command is the safe fallback when ambiguity prevents a unique symbol selector. A numeric range shown beside a stable symbol is evidence metadata (a bounded preview), not the preferred body address. Use `srcwalk context <target>` only when you need a Flow Map, scoped occurrences, or call neighborhood; do not run `context` for each hop just to read source.
+If `discover` prints `## Confirmed structural targets`, run the printed `> Next:` command verbatim. The target is a canonical `<path>:<symbol>` built from parser outline primitives and proven to resolve to that one body; a numeric `<path>:<start-end>` command is the safe fallback when ambiguity prevents a unique symbol selector. A numeric range shown beside a stable symbol is evidence metadata (a bounded preview), not the preferred body address. Use `srcwalk context <target>` only when you need a Flow Map, scoped occurrences, or call neighborhood; do not run `context` for each hop just to read source. Reuse that `<path>:<symbol>` string unchanged across `show`, `context`, `trace callers`, and `trace callees`, keeping any `--scope` printed with it; never rebuild it from a displayed qualified name, because a namespace/module display prefix (`System.Text.Json.GetTypeInfoInternal`) is not a selector and the emitted form uses the owning container (`JsonSerializerOptions.GetTypeInfoInternal`). The path identifies the requested definition; it does not upgrade caller evidence — `trace callers` stays a direct by-name search and may include same-name definitions elsewhere. Unresolved or ambiguous targets fail explicitly instead of falling back to a bare-name search.
 
 Symbol discovery separates parser-backed definitions from text-matched name occurrences. Repeated same-name definitions receive an ambiguity caveat. Text discovery remains literal evidence; `--match all` is same-file co-occurrence, not semantic relation proof.
 
@@ -81,12 +81,12 @@ For Go `discover --as text --match any`, matched lines may carry a structural ow
 Use `show` for known bodies and citations. Use `context` when the task needs a rich local packet such as Flow Map, scoped occurrences, or call neighborhood. Exact path/range contexts may include bounded `Source Evidence`; `show` `Source frame` lines orient exact numeric reads and numeric `--section` blocks, not relation proof.
 
 ```bash
-srcwalk context <file>:<symbol>
-srcwalk context <file>:<line-or-range>
+srcwalk context <path>:<symbol>     # or <path>:<line-or-range>
 srcwalk context <symbol> --scope <dir>
 srcwalk show <path>:123 -C 10
 srcwalk show 'a.rs:12,b.rs:40-55'
 srcwalk show <file>:12,40-55        # same-file ranges route to --section
+srcwalk show <path>:<symbol>        # canonical exact target, reusable across all four commands
 srcwalk show <path> --section <symbol>
 srcwalk show README.md --section '# Install'
 ```
@@ -98,8 +98,8 @@ Do not pass a bare file to `context`; use `show` or root reads. `context` accept
 Use `trace callers` for upstream call sites and `trace callees` for downstream calls. Do not grep `foo(` for relation claims. Long result lists collapse to the top entries plus a `+N more → <command>` pointer, and wide evidence ranges may appear as an anchor plus an `expand: <command>` line. These pointer lines are exact commands: run them verbatim when you need the remaining items or the full range. Nothing is dropped — collapsed items are always one command away. Drill down with exact call-site reads or `context` on a caller/callee.
 
 ```bash
-srcwalk trace callers <symbol> --scope <dir>
-srcwalk trace callees <symbol> --detailed --scope <dir>
+srcwalk trace callers <symbol|path:symbol> --scope <dir>   # exact root; call sites still matched by name
+srcwalk trace callees <symbol|path:symbol> --detailed --scope <dir>
 srcwalk trace callees <symbol> --depth 2 --scope <dir>
 ```