Skip to content

ByteTerrace/Puck / .claude/skills/symbol-analysis

symbol-analysis

Verified

Answers C# structure questions with puck references and declarations: which types derive from, implement or override a symbol, who references it, safe to delete or rename. Text: content-search.

FileKindSize
SKILL.mdskill md5.6 KB
evals/y01-implementers-of-frame-source/graders/implementers-flag.mdmarkdown119 B
evals/y01-implementers-of-frame-source/graders/narrows-the-member-query.mdmarkdown69 B
evals/y01-implementers-of-frame-source/graders/partial-locations.mdmarkdown108 B
evals/y01-implementers-of-frame-source/graders/skill-fired.mdmarkdown36 B
evals/y01-implementers-of-frame-source/prompt.mdmarkdown344 B
evals/y02-unused-extension-type/graders/builds-before-deleting.mdmarkdown156 B
evals/y02-unused-extension-type/graders/extension-call-sites.mdmarkdown108 B
evals/y02-unused-extension-type/graders/no-doc-flag.mdmarkdown65 B
evals/y02-unused-extension-type/graders/puck-references.mdmarkdown93 B
evals/y02-unused-extension-type/graders/skill-fired.mdmarkdown36 B
evals/y02-unused-extension-type/graders/type-versus-member.mdmarkdown108 B
evals/y02-unused-extension-type/graders/uncompiled-files.mdmarkdown117 B
evals/y02-unused-extension-type/prompt.mdmarkdown345 B
evals/y03-declarations-of-a-file/graders/declarations-members.mdmarkdown86 B
evals/y03-declarations-of-a-file/graders/missing-path-is-an-error.mdmarkdown108 B
evals/y03-declarations-of-a-file/graders/no-semantic-usage.mdmarkdown201 B
evals/y03-declarations-of-a-file/graders/sees-uncompiled-code.mdmarkdown83 B
evals/y03-declarations-of-a-file/graders/skill-fired.mdmarkdown36 B
evals/y03-declarations-of-a-file/graders/syntactic-and-build-free.mdmarkdown112 B
evals/y03-declarations-of-a-file/prompt.mdmarkdown467 B
evals/y04-workspace-load-fails-in-fresh-worktree/graders/rejects-allow-partial.mdmarkdown110 B
evals/y04-workspace-load-fails-in-fresh-worktree/graders/restores-the-solution.mdmarkdown98 B
evals/y04-workspace-load-fails-in-fresh-worktree/graders/skill-fired.mdmarkdown36 B
evals/y04-workspace-load-fails-in-fresh-worktree/prompt.mdmarkdown359 B
evals/y05-alias-hides-a-reference/graders/alias-hides-text-matches.mdmarkdown154 B
evals/y05-alias-hides-a-reference/graders/builds-after-the-rename.mdmarkdown134 B
evals/y05-alias-hides-a-reference/graders/puck-references.mdmarkdown93 B
evals/y05-alias-hides-a-reference/graders/skill-fired.mdmarkdown36 B
evals/y05-alias-hides-a-reference/prompt.mdmarkdown402 B
evals/y06-overrides-and-derived/graders/derived-flag.mdmarkdown114 B
evals/y06-overrides-and-derived/graders/narrows-same-named-members.mdmarkdown69 B
evals/y06-overrides-and-derived/graders/overrides-flag.mdmarkdown116 B
evals/y06-overrides-and-derived/graders/skill-fired.mdmarkdown36 B
evals/y06-overrides-and-derived/prompt.mdmarkdown362 B
references/complete-reference.mdmarkdown16.7 KB

references/complete-reference.md

View on GitHub
# Symbol-analysis complete reference

Read the relevant section when `SKILL.md` routes here.

## Contents

- [Picking the tier](#picking-the-tier)
- [`puck references`](#puck-references--the-semantic-tier)
- [`puck declarations`](#puck-declarations--the-syntax-tier)
- [Recipes](#recipes)
- [When neither verb fits](#when-neither-verb-fits)

Two verbs of the consolidated `puck` developer CLI (`src/Puck.Cli`) are
invoked from the repository root, through a copy of the checkout's own
`src/Puck.Cli/bin/Release/net11.0/` build (see `SKILL.md`):

```text
dotnet <scratch-copy>/Puck.Cli.dll <verb>
```

If that build is absent, build and copy it as `SKILL.md` describes.

Every command below writes just `puck <verb>` for short. Re-copy the build after
tool changes. `puck <verb> -h` prints that verb's usage and exits 0; `puck` with no verb,
like an unknown verb or option, prints the parse error and
`Run 'puck --help' for usage.` on stderr and exits 2.

| Verb | Tier | Answers |
|---|---|---|
| `puck references <name>` | **semantic** — loads the project graph, resolves symbols | who references it, what implements it, what overrides it, is it dead |
| `puck declarations [path…]` | **syntax** — parses files, no build | what is declared where, base lists, attributes, doc crefs |

**The core rule:** if the question contains *uses*, *references*, *implements*,
*overrides*, *dead*, *unused*, *rename*, or *safe to delete* about C# code, text
output is **not evidence**. Text matching cannot see extension methods, `using`
aliases, overload resolution, generic instantiation, or name collisions. Both
directions of that error are live in this tree and verified:
`AllocatorExtensions` looks dead when searching for the type name, while its
`Alloc` member has semantic call sites. Inverted, many references to
`QuadraticAlgebra<TScalar>.Element` do not spell `Element` because a
`using QFixElem = …` alias renames it.

## Picking the tier

| Question shape | Tool |
|---|---|
| Where is a literal string / a config value / a non-C# asset (HLSL, JSON, project files)? Orientation in unfamiliar code? | `puck search` — see the `content-search` skill. It is the only sanctioned content search. |
| Did my rename or refactor break anything? | `dotnet build` — the compiler is the cheapest full-semantic oracle, and this repo compiles IDE0005 as an error. Do not search for stragglers; build. |
| What does this tree declare? Members, base lists, attributes, doc crefs. Files no project compiles. | `puck declarations` |
| Who references this? What implements or overrides it? Is it dead? Is a delete safe? | `puck references` |
| Code metrics, call-graph shape, a walk no flag expresses | ad-hoc file-based app — recipe at the end. |

`references` costs a solution load (a design-time build per project, scaling
with the project count); `declarations` costs a parse per file and no build at
all. `--project` narrows `references` to one project's closure, which is cheaper
and answers a different question — see the closure trap.

## `puck references` — the semantic tier

```
references <name>   references to a source symbol, solution-wide
  --declarations      declarations only, no reference search
  --implementers      implementations of an interface or interface member
  --overrides         overrides of a virtual/abstract member
  --derived           derived types
  --containing <frag> keep declarations whose display string contains frag (ordinal)
  --contains          treat <name> as a substring, not an exact simple name
  --ignore-case       case-insensitive name match
  --kind <k,k>        type, member, namespace (default: type,member)
  --solution <path>   default: the nearest .slnx walking up from the cwd
  --project <path>    load one project instead
  --configuration <c> build configuration (default Release)
  --metadata          also match declarations from referenced assemblies
  --no-doc            drop locations inside documentation trivia
  --strict            keep only locations whose group definition IS the queried symbol
  --allow-partial     report anyway after a workspace load failure
  --json              one JSON object per line
  --quiet / -h
```

The mode flags are not exclusive at the parser; the first one set wins, in the
order `--declarations`, `--implementers`, `--overrides`, `--derived`. Output is
records and nothing else — no counts, no banner:

```
src/Puck.Abstractions/Memory/AllocatorExtensions.cs:14:24 decl Method Puck.Abstractions.Memory.AllocatorExtensions.Alloc(Puck.Abstractions.Memory.IAllocator, nint)
src/Puck.Vulkan/Apis/VulkanNativeCommandBufferRecordingApi.cs:352:35 ref Method Puck.Abstractions.Memory.AllocatorExtensions.Alloc(Puck.Abstractions.Memory.IAllocator, nint)
```

`path:line:col` leads, so a line parses like a `search` hit and pastes into an
editor as a jump target. Paths are working-directory-relative and
forward-slashed; running from a subdirectory changes only the prefix (verified:
the same query from the repo root and from `src/Puck.Maths` differs only in
`src/` vs `../`). Records are grouped by resolved definition and sorted by
position inside a group; two runs are byte-identical (verified). **Exit codes: 0
a declaration matched, 1 none did, 2 usage error or workspace load failure.**

### The symbol on a `ref` line is the RESOLVED definition, not what you asked for

The search cascades, and the cascade is not configurable. Both forms are
verified here:

- **Constructor cascade.**
  `references CaptureFrame --containing Puck.Abstractions.Capture` reports
  the `new CaptureFrame(…)` site in `src/Puck.Hosting/FrameCaptureController.cs` under
  `CaptureFrame.CaptureFrame(Surface, long, ulong)` — the constructor — because
  the site is `new CaptureFrame(…)`. **`--strict` on a type therefore hides
  every construction site** (verified: strict drops exactly that location).
- **Interface cascade.** `references CaptureFrame --containing ISdfFrameSource`
  reports locations under the interface method and under each implementation's
  own method, because an interface-dispatched call resolves to the interface
  while a direct call resolves to the implementation.

Read the definition column. When you want "sites that mention this exact
symbol", `--strict`; when you want "everything that reaches this behavior",
the default.

### Documentation crefs are real references

`<see cref="…"/>` targets come back as ordinary reference locations — not
implicit, not candidate. Verified: `references IAllocator` includes
`src/Puck.Abstractions/Memory/AllocatorExtensions.cs`, at the
`<see cref="IAllocator"/>` entries in that class's doc comment; `--no-doc` drops those
and the other documentation-only locations without dropping code references.

**Consequence for dead-code work:** a symbol whose only inbound references are
doc crefs is **not pinned**. Run `references <name> --no-doc`; a result that is
only `decl` lines is the dead-code candidate. Without `--no-doc` a cref-only
result reads as a live consumer and the dead code survives.

### This tier is blind to anything the project system does not compile

Verified in this tree: `experimental/scripts/recording/mux-check.cs`
contains `session.Consume(new CaptureFrame(` — a self-contained file-based
`.NET` app under the quarantined `experimental/` tree, in no project at all
(none of it is reached by the root build; see `experimental/README.md`). No
reference query reports that call.

So **"zero references" can mean "zero compiled references"**. Pair a deletion
decision with `puck search -M 0 -l <name>` or `puck declarations` over the same
tree — the two walk one identical file set, see the walk contract below;
`declarations` still parses that uncompiled script and lists what it declares.

### Other verified behavior worth knowing before you trust a result

- **`--project` narrows the closure, and the narrowing is silent.**
  `references Alloc --project src/Puck.Abstractions/Puck.Abstractions.csproj`
  reports the declaration but no consumers; the solution-wide form reports
  consumers. `OpenProjectAsync` loads the project and its project-reference
  closure, so every consumer outside it is invisible. Use `--project` to ask
  about one project, never to ask "is this used".
- **Declarations are source-only by default.** `--metadata` widens the search to
  referenced assemblies and is usually noise: on `Alloc` it adds
  `System.Runtime.InteropServices.NativeMemory.Alloc(nuint)` and its two-argument
  overload (verified), each of which then drives a reference search that can only
  come back empty. A declaration outside source is reported at `<assembly>:0:0`.
  `--contains` is source-only and pairing it with `--metadata` is a usage error.
- **A load failure is fatal by default.** Any `Failure` diagnostic prints as
  `references: workspace: <message>` and exits 2, because a partly loaded solution
  answers "no references" indistinguishably from a true zero. Verified against a
  solution naming a missing project: exit 2 with the diagnostic, and
  `--allow-partial` turns the same run into exit 0 with the partial answer.
  The commonest cause is an unrestored tree such as a fresh worktree: the
  design-time build resolves an incomplete reference closure, the message counts
  the projects with no `obj/project.assets.json`, and the remedy is
  `dotnet restore Puck.slnx -nodeReuse:false`, never `--allow-partial`. A
  restored `Puck.slnx` loads with no diagnostics.
- **Loading is not a pure read.** It runs a design-time build, which creates
  `obj/<Configuration>/net11.0/` and writes `AssemblyInfo.cs`,
  `AssemblyInfoInputs.cache` and `GeneratedMSBuildEditorConfig.editorconfig`
  there (verified on a throwaway project outside the repo that had no `obj/`
  before the run). The default Configuration is Release, the one every verb's
  `--configuration` defaults to; `--configuration` changes it.
- **An analyzer that was never built is skipped by name.** A project-built
  analyzer or generator (`Puck.Analyzers`) not yet built in the loaded
  configuration loads as an unresolved analyzer reference, which the reference
  search cannot hash. The verb drops each one and names it once on stderr
  (`references: skipping analyzer <path> in <n> project(s)`), and the answer is
  otherwise complete; build that configuration to include what the analyzer
  generates. Verified on a throwaway project naming a missing analyzer file.
- **An unrestored project degrades silently, it does not fail.** Verified on a
  throwaway project outside the repo with a `PackageReference` and no
  `obj/project.assets.json`: the workspace reported no diagnostic, source
  declarations resolved normally, and the package's assembly was simply absent
  from the compilation (a query for a type in it found nothing). Restore before
  trusting an answer that crosses a package boundary.
- **A symbol with several partial declarations reports one line per
  declaration.** `references IWorldServerHost --implementers` lists
  `WorldServer` at multiple positions — one per `partial` file. That is
  the symbol's location set, not duplication.
- **`--implementers` works on an interface and on an interface member**
  (verified on `ISdfFrameSource` and on its `CaptureFrame` method).
- **`--declarations` is how you see a name collision.**
  `references CaptureFrame --declarations` separates the record struct from
  same-named methods on unrelated types and signatures. A text count conflates
  those declarations.
- **Declarations the compiler creates are found too** (verified). A record's
  positional properties (`references FrameIndex --declarations` reaches
  `CaptureFrame.FrameIndex`) and the `Program` type a top-level-statements file
  gets (including under `--project`) are real
  source declarations, and the exact-name query reports them. Two invariants
  ride on the same discovery path: an exact name answers a subset of what
  `--contains` answers, and a narrower `--kind` only ever removes records.

## `puck declarations` — the syntax tier

```
declarations [path ...]   declaration inventory, parse-only (default path: cwd)
  --glob <glob> / --not <glob>   include/exclude globs, the same matcher search uses
  --kind <k,k>       class, struct, record, interface, enum, delegate,
                     method, property, field, event, ctor
  --name <frag>      declared simple name contains frag (ordinal)
  --base <frag>      base list contains frag (types only)
  --attribute <frag> an attribute name contains frag
  --members          list members inside each type (implied by a member --kind)
  --doc              also emit XML-doc cref targets, filtered by --name alone
  --json / --quiet / -h
```

Output is `path:line:col decl <kind> <qualified name>[ : <base list>]`, sorted by
path then position, with a `cref` relation under `--doc`. Exit codes are the same
0/1/2. Verified properties:

- **Inventory counts are outputs, not skill constants.** To establish a
  regression baseline, run `puck declarations src/Puck.Maths` against the
  revision under test and retain that run's output with the test evidence.
  Re-run after either the verb or the tree changes.
- **One record is one line.** Base lists, parameter lists and crefs are written
  across source lines often enough that this matters. Only the tokens are
  rendered: comments between them are dropped, two tokens the source separated
  are separated by one space, and the `///` that opens a continued line of a
  documentation comment is a continuation rather than a separator, so a cref
  split across two lines still reads as one dotted path. `--name` and `--base`
  filter that same rendered form.
- **A path that names nothing is a usage error** — `declarations: no such file
  or directory: <path>` and exit 2, so a typo cannot be read as "this tree
  declares nothing" (exit 1). A named file that is not `.cs` is called out on
  stderr and skipped.
- **It sees files no project compiles** (the `references` blind spot above), and
  it reads git's view of the tree through the shared `FileWalk`, as `puck
  search` does, so the two verbs paired on one question cover one tree and
  neither reaches an ignored scratch snapshot or a duplicate checkout that would
  answer as a live consumer. Naming an ignored directory as a root still walks
  it, for either verb.
- **Both record forms report the kind `record`.**
- Two runs are byte-identical, and running from a different directory changes
  only the path prefix (verified).

`--base` is the cheap implementers query when a build is unavailable or
unwanted: `declarations --base ISdfFrameSource src` returns the same types
that `references ISdfFrameSource --implementers` does over the same tree
(verified; the references run also reaches `tests/`). It matches
base-list *text*, so it cannot see an implementation inherited through a base
class, and an alias would fool it — that is the price of not building.

## Recipes

The common questions are the table in `SKILL.md`. The rest:

| Intent | Command |
|---|---|
| Implementers without a build | `puck declarations --base <name> src` |
| What carries this attribute? | `puck declarations --attribute <frag> --members src` |
| What do the docs point at? | `puck declarations --doc --name <frag> src` |
| Machine-readable | add `--json` to either verb |

## When neither verb fits

Comment, lock and clone sweeps are `puck scan`. For code metrics, call-graph
shape, or any other walk the flags do not express, write a
single-file .NET file-based app in the **session scratchpad** (never in the repo)
and run it with
`dotnet run -c Release -p:NuGetAudit=false <file>.cs -- <args>`. Release is
required by this repository's machine policy; disabling the audit prevents an
otherwise package-free probe from failing only because the vulnerability feed
is offline. The directives and traps that
still apply:

- `#:package Microsoft.CodeAnalysis.CSharp.Workspaces@<pinned>` for the semantic
  layer, or `Microsoft.CodeAnalysis.CSharp@<pinned>` for syntax only. Pin the
  version that `src/Puck.Cli/packages.lock.json` resolves — the compiler-platform
  packages pin each other at an exact version internally.
- `#:property PublishAot=false` — required as soon as anything reflects.
- **Do not add `Microsoft.Build.Locator`.** It fails the file-based-app build
  (MSBL001), and it fights the out-of-process build host in a project. Modern
  `MSBuildWorkspace` needs neither it nor a `RegisterDefaults()` call: it shells
  out to a `BuildHost-netcore/` process delivered with the package.
- Use `workspace.RegisterWorkspaceFailedHandler(…)`, not `workspace.WorkspaceFailed +=`
  — the event is `[Obsolete]`, and this repo compiles warnings as errors.
- `MSBuildWorkspace.OpenSolutionAsync` handles this repo's `.slnx` directly.
- Sort before printing. `ReferencedSymbol.Locations` comes back unordered.
- The design-time build writes `obj/`, and without a `Configuration` property it
  runs Debug. Treat a run against the repo as a build, not a read.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall