Skip to content

feat(for): add surf for <path> reverse lookup (#31)#33

Merged
Connorrmcd6 merged 1 commit into
mainfrom
feat/surf-for-reverse-lookup
Jun 9, 2026
Merged

feat(for): add surf for <path> reverse lookup (#31)#33
Connorrmcd6 merged 1 commit into
mainfrom
feat/surf-for-reverse-lookup

Conversation

@Connorrmcd6

Copy link
Copy Markdown
Owner

Summary

Surface's pitch is that hubs/ give documentation a standard home people and agents actually find — but there was no command for the inverse of authoring: "I'm about to edit this file, which claims govern it?" suggest only finds unanchored functions; check/lint don't expose a per-path view. This delivers that discoverability half of the thesis.

Changes

  • New surf for <path> [symbol] [--format human|json] — lists every hub + claim anchored into <path>, optionally narrowed to anchors whose first segment matches symbol.
  • Reuses the existing hub/anchor machinery and matches on the anchored path only — no source parse, no model, no network. Stays deterministic and dependency-free.
  • A query, not a gate: always exits 0, whether or not anything matched.
  • --format json emits a versioned {version, path, matches} envelope for agents.
  • Path is normalized to workspace-root-relative (strips a leading ./, relativizes an absolute path under the root).

Out of scope (per #31): git-moved-path resolution and blast-radius / call-graph analysis (those drift and would break the no-model/no-network core).

Verification

  • Unit tests: finds all claims for a file, symbol narrowing, empty result, path normalization, versioned JSON envelope.
  • End-to-end against this repo's own hubs: surf for surf-cli/src/check.rs lists both its claims; narrowing to a symbol returns one; a path with no anchors reports empty and exits 0; JSON envelope verified.
  • Dogfood: added hubs/cli-for.md documenting the new command; surf lint and surf check stay green (the CLI command-list hub was updated to include for).

Closes #31.

🤖 Generated with Claude Code

Closes #31.

`hubs/` give documentation a standard home, but nothing answered the inverse
of authoring: "I'm about to edit this file — which hubs/claims describe it?"
`suggest` only finds *un*anchored functions; `check`/`lint` don't expose a
per-path view. So the discoverability half of the thesis wasn't delivered by
the tooling.

- New `surf for <path> [symbol] [--format human|json]`. Lists every hub +
  claim anchored into the path, optionally narrowed to a first-segment symbol.
- Reuses the existing hub/anchor machinery and matches on the anchored path
  only — no source parse, no model, no network. A query, not a gate: exits 0.
- JSON emits a versioned `{version, path, matches}` envelope for agents.
- Path is normalized to workspace-root-relative (strips `./`, relativizes an
  absolute path under the root).

Out of scope (per #31): git-moved-path resolution and blast-radius/call-graph
analysis.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Connorrmcd6 Connorrmcd6 force-pushed the feat/surf-for-reverse-lookup branch from d9017f0 to e0045d1 Compare June 9, 2026 06:34
@Connorrmcd6 Connorrmcd6 merged commit be56302 into main Jun 9, 2026
1 check passed
@Connorrmcd6 Connorrmcd6 deleted the feat/surf-for-reverse-lookup branch June 9, 2026 06:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add reverse lookup: surf for <path> — which hubs/claims anchor into a file

1 participant