Skip to content

feat(treesitter): add ,imports and ,signatures flags to :symbol fences#9

Merged
phil-scott-78 merged 1 commit into
mainfrom
feat/treesitter-symbol-imports-signatures
May 25, 2026
Merged

feat(treesitter): add ,imports and ,signatures flags to :symbol fences#9
phil-scott-78 merged 1 commit into
mainfrom
feat/treesitter-symbol-imports-signatures

Conversation

@phil-scott-78
Copy link
Copy Markdown
Contributor

What

Two opt-in, comma-combinable flags for :symbol code fences:

  • ,imports — prepends the file's top-of-file using/import/require lines above the snippet (all of them, blank-line separated). Composes with ,bodyonly; no-op for whole-file embeds and import-less languages (Ruby).
  • ,signatures — elides member bodies to { … } ( for non-brace bodies) for an at-a-glance outline of a type's shape. Inverse of ,bodyonly.
```csharp:symbol,imports
examples/FocusedCodeSamplesExample/MonolithWordCounter.cs > MonolithWordCounter.CountWords
examples/FocusedCodeSamplesExample/ModularWordCounter.cs > ModularWordCounter

## Why

A member-scoped fence dropped the file's import context, so readers couldn't tell where types resolved from — the docs even shipped a standing "no `using` prepend" caveat, now retired. And embedding a whole type dumped every body, with no way to show just its surface.

## How

Both extend the existing **config-driven tree walk** (no `.scm` queries):

- Lifted the shared "descend transparent wrappers, match a node-type set" descent out of `NamePathResolver` into a reusable `TreeWalker`, now driving name resolution, import collection (`ImportCollector`), and outline elision.
- Flags flow through parsing → service → extractor in a new `FragmentOptions` record, replacing the bare `bodyOnly` bool.
- Per-language `ImportNodeTypes` seed import collection (`using_directive`, `import_statement`, `use_declaration`, …).
- The outline transform splices bodies out using start-position + body-length math (no byte-offset dependency).
- Scope: `,imports`/`,signatures` apply to `:symbol` only — `:symbol-diff` still honors just `,bodyonly`.

## Docs

New how-to sections (with live-rendered examples), updated fence grammar + suffix-forms table in `code-block-args.md`, and retired the false caveat in the docsite authoring guide.

## Testing

- `dotnet test Pennington.slnx` — **51** TreeSitter (11 new) + **806** unit + **48** integration passing.
- `dotnet run --project docs/Pennington.Docs -- build` — 458 pages, no unresolved references; confirmed on the rendered page that `,imports` prepends the using and `,signatures` elides bodies, with zero extraction errors.

The :symbol fence could scope to a member but always dropped the file's
import context, and there was no way to show a type's shape without
dumping every body. Add two opt-in, comma-combinable flags:

- ,imports prepends the file's top-of-file using/import/require lines
- ,signatures elides member bodies to { … } for an outline view

Both extend the existing config-driven tree walk. A shared TreeWalker,
lifted from NamePathResolver, now drives name resolution, import
collection, and outline elision. Flags flow through parsing → service →
extractor in a new FragmentOptions record (replacing the bare bodyOnly
bool); per-language ImportNodeTypes seed import collection. Imports and
signatures apply to :symbol only — :symbol-diff still honors just
,bodyonly.

Docs: new how-to sections with live examples, updated fence grammar and
suffix table, and retired the now-false "no using prepend" caveat.
@phil-scott-78 phil-scott-78 merged commit eb2caa7 into main May 25, 2026
5 checks passed
@phil-scott-78 phil-scott-78 deleted the feat/treesitter-symbol-imports-signatures branch May 25, 2026 04:22
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.

1 participant