Request: discovery‑first commands built on top of `find` (happy to PR)

[joshka-oai]

Context / Motivation
I was about to build a lightweight Rust discovery tool (syn‑based, no typecheck) and found rs‑hack.
It already solves AST‑aware search/refactor. I asked Codex to list the discovery operations it
struggles with. The proposals below are purely Codex‑generated from a longer conversation, not a
human gap analysis. If they align with your vision, I’m happy to implement PRs (I whatever agent we use would make a reasonably good pass at implementing these ideas).

What rs‑hack already covers

• find with --node-type / --kind / --limit is excellent
• JSON output already exists for find
• No typecheck required

Proposed discovery commands (with examples + output)

1. describe — type‑centric summary
   Current: multiple find calls + manual stitching.
   Command:

rs-hack describe --type FileSearchPopup --paths src --calls

Output (example):

Type: FileSearchPopup (struct)
Defined at: tui/src/file_search.rs:12
Fields: query, results, state
Impls: FileSearchPopup, Default
Methods: set_query, clear, on_result
Call sites (set_query): 3
  - tui/src/app.rs:145
  - tui/src/file_search.rs:98

Value: replaces 4–6 find/rg steps with one “what is this type?” command.

2. owners — field embedding graph
   Current: find --node-type struct + manual scan.
   Command:

rs-hack owners --type FileSearchPopup --paths src

Output:

Owners of FileSearchPopup:
  AppState::file_search (tui/src/app.rs:55)
  UiState::popup (tui/src/ui_state.rs:18)

Value: instantly shows where a type lives in state.

3. callsites — method calls scoped to receiver type
   Current: find --node-type method-call --name set_query (unscoped).
   Command:

rs-hack callsites --method set_query --type FileSearchPopup --paths tui

Output:

Calls to FileSearchPopup::set_query (3):
  tui/src/app.rs:145  self.file_search.set_query(...)
  tui/src/file_search.rs:98  popup.set_query(...)

Value: avoids irrelevant results from other types with same method name.

4. impls — trait implementors
   Current: manual find across impl blocks.
   Command:

rs-hack impls --trait HistoryCell --paths tui

Output:

Trait HistoryCell implemented by:
  CodeCell (tui/src/history/cells/code.rs:12)
  TextCell (tui/src/history/cells/text.rs:9)

Value: one‑shot answer to “who implements this trait?”

5. summary — module inventory
   Current: multiple find calls, manual summary.
   Command:

rs-hack summary --path tui/src/history_cell.rs

Output:

Module: tui/src/history_cell.rs
Public items: HistoryCell, RenderedCell
Types: 2 structs, 1 enum
Functions: render_cell, measure_cell
Re-exports: pub use cells::*
Doc: "History rendering entrypoints."

Value: 1‑line “what’s in this module?”

6. doc-coverage — missing docs list
   Current: no doc coverage command.
   Command:

rs-hack doc-coverage --path tui/src --fields

Output:

Missing docs (items): 12
Missing docs (fields): 31
Top offenders:
  tui/src/app.rs: AppState
  tui/src/history_cell.rs: RenderedCell::width

Value: makes doc passes actionable.

7. neighbors — related modules
   Current: manual file navigation.
   Command:

rs-hack neighbors --path tui/src/file_search.rs

Output:

Neighbors for tui/src/file_search.rs:
  Siblings: tui/src/file_search_tests.rs, tui/src/file_search_state.rs
  Twin dirs: tui2/src/file_search.rs
  Tests: tui/tests/file_search.rs

Value: quickly surfaces adjacent context, test files, or “tui ↔ tui2” pairs.

8. xref — cross‑reference map for a symbol
   Current: multiple find calls grouped by hand.
   Command:

rs-hack xref --name FileSearchPopup --paths tui

Output:

Definition:
  tui/src/file_search.rs:12 (struct)

Impls:
  tui/src/file_search.rs:55

Methods:
  set_query, clear, on_result

Uses:
  tui/src/app.rs:145 (field)
  tui/src/ui_state.rs:18 (field)

Value: single structured view of definition + usage.

9. relate — relationships view
   Current: find --field-name and find --node-type match-arm manually assembled.
   Command:

rs-hack relate --type AppState --paths tui

Output:

Fields + reads/writes (top 5):
  file_search (writes: 6, reads: 12)
  history (writes: 2, reads: 20)

And for enums:

rs-hack relate --enum View --paths tui

Output:

Enum View variants:
  List, Popup, Empty
Match coverage:
  handle_view: missing Popup
  render_view: complete

Value: gives dataflow and match coverage quickly.

10. calls — local call graph
    Current: find --node-type function-call + manual trace.
    Command:

rs-hack calls --fn render_view --paths tui --depth 1

Output:

render_view calls:
  render_list
  render_popup

Value: local call graph without LSP.

11. type-usage — positional usage stats
    Current: find --node-type type-ref only.
    Command:

rs-hack type-usage --type FileSearchPopup --paths tui

Output:

Usage of FileSearchPopup:
  fields: 2
  function args: 1
  return types: 0
  trait bounds: 0

Value: shows whether a type is API boundary or internal.

12. struct-audit — literal coverage
    Current: find --node-type struct-literal only.
    Command:

rs-hack struct-audit --type FileSearchPopup --paths tui

Output:

Struct literal audit: FileSearchPopup
  3 literals found
  missing fields: state (2 literals)

Value: “where is this constructed and what’s missing?”

13. match-audit — missing enum variants
    Current: find --node-type match-arm only.
    Command:

rs-hack match-audit --enum View --paths tui

Output:

Missing variants:
  render_view: Popup
  handle_view: Popup

Value: complements add-match-arm with discovery.

14. snippet — context‑sized extraction
    Current: find --format snippets only.
    Command:

rs-hack snippet --name FileSearchPopup --node-type struct --context 3

Output:

tui/src/file_search.rs:12
/// Popup state for file search UI.
pub struct FileSearchPopup {
    query: String,
    results: Vec<SearchResult>,
    state: PopupState,
}

Value: fast skimming without opening files.

15. describe presets
    Current: manual multi‑step flows.
    Command:

rs-hack explain type FileSearchPopup --paths tui

Output: wrapper around describe + owners + callsites with a concise summary.

Request
Would you consider adding a small set of discovery‑first commands (implemented as thin wrappers on
top of find/--kind/--node-type)? I’m happy to help implement these.

[1e1f]

Thanks for the thoughtful gap analysis — the framing of "thin wrappers over find" is a good shape for these. went ahead and shipped six of them:

Landed:

#	Command	Notes
4	impls --trait <Name>	New trait-impl node-type; also reachable via find --node-type trait-impl and via --kind trait (now expands to both definitions and implementors).
5	summary --path <file>	Single-file inventory: public items, type counts, fns, re-exports, module doc.
6	doc-coverage --paths <p>	Missing-doc count + top offenders. --fields descends into struct fields, enum variants, and impl/trait methods.
7	neighbors --path <file>	Pure FS: siblings, twin dirs (e.g. tui ↔ tui2), tests.
13	match-audit --enum <Name>	Per-match-site missing-variant report; wildcards count as covering. Honest heuristic: a match is "for enum X" iff at least one arm uses X::Variant syntax — no typecheck.
14	find --context N	Adds N raw lines before each snippet, like grep -B. Mostly redundant with the existing --include-comments default, but ergonomic.

Deferred and why:

• Add yah-kg knowledge graph contract crate #3 callsites --type — needs the receiver's type, which syn alone can't give us. Doable as a heuristic on the receiver expression's text but I'd rather not ship something that silently misses dispatched calls. Open to a --receiver-text mode that's honest about being syntactic.
• #9 relate (read/write counts) — needs lvalue/rvalue classification of field accesses; requires new analysis, not a wrapper. Worth doing but wants its own design pass.
• Request: discovery‑first commands built on top of find (happy to PR) #1 describe / #8 xref / #15 explain — pure compositions over find + the new impls. Probably collapse to one describe --type X command rather than three.
• Track formatter/lint cleanup and next tidy-ups #2 owners and #11 type-usage — both want positional classification of type-ref (field vs arg vs return vs bound). A --position flag on find --node-type type-ref covers both with one knob.
• #10 calls --fn X — body walker is fine, but --depth is misleading without name-resolution (we'd be reporting syntactic call names, not resolved targets). Needs an output spec before building.
• #12 struct-audit — useful complement to the existing field ops; just bigger than a wrapper because the visitor has to collect struct-def fields then re-walk literals. Happy to take this as a follow-up PR.

Happy to take PRs on any of the deferred ones, especially #1/#8/#15 (the unified describe) and the --position flag for #2/#11. For #3 and #9, would prefer to discuss the design first since they cross the syn-only line.

[joshka]

There's a bunch more deeper work that I started documenting over on joshka#1 as I wasn't sure if this repo was maintained and didn't want to slap a bunch of high frequency ai generated issues and code your way if not. There's a whole bunch of preparatory refactoring in main...joshka:rs-hack:main but I haven't looked at it since then.

Happy to move the issues over to this repo / cut PRs for all the various refactoring, but I'm aware a bunch of this might not be shared vision type stuff. Maybe have your agent take a look to get an overview of what works well from your perspective / is worth considering (have it look at the commit messages and issues for justification / context).

[1e1f]

I factored in your tooling change commits as best I could -- and as far as extracting files to slim down source (main.rs) etc was easier to stick with current structure (commands folder instead of cli) since it was accomplishing mostly, the same thing. I'm trying to settle on an api that will support both cli as an entrypoint and other rust binaries pulling in rs-hack as a library.

Open to additional PR for sure, both fixed and "shared vision" / new directions -- I built this originally because I had an AI doing a lot of refactoring for me rather than net-new stuff. I thought a language specific tool as opposed to a general tree-sitter types solution would serve better.

I finished that refactor and find myself reaching for rs-hack less now days. that said I'm working on a harness that will want to provide it's own tools directly to the "inference on wire" and I'm hoping this will become useful as the general i/o for rust files for that agent instead of grep etc. so if I'm adding stuff here it will probably be in that direction.

[joshka]

ok, cool I'm not in a rush on this either - some time in the next week I'll set codex to it.