chore: land janitor round 1 and graft integration
Round 1 findings and fixes, all previously uncommitted: - FXProcessor per-slot DSP history repair (HEAD does not compile without it) - SynthVoice::getModulationValue, editor control-lock guard - ExactCompare.h naming the deliberate exact float comparisons - KnobLookAndFeel replacing the never-installed SerumLookAndFeel - 55 first-party compiler warnings to 0 - AGENT.md renamed to AGENTS.md across Source/ - graft repository context graph and its hooks - JANITOR_TASKS.md and UI_UX_AUDIT.md records
This commit is contained in:
biggy committed
1 parent
5c942cad0c
commit
e4cea300db
63 files changed
+2360
-805
No files matched your search
@@ -64,4 +64,4 @@ function entry(name) {
|
||||
return path.join(dir, 'dist', 'claude', name); // last-ditch; import will no-op if absent
|
||||
}
|
||||
|
||||
import(pathToFileURL(entry("hooks.js")).href).then((m) => m.main(process.argv[2])).catch(() => { /* graft unavailable — no-op */ });
|
||||
import(pathToFileURL(entry("hooks.js")).href).then((m) => m.main(process.argv[2])).catch(() => { /* graft unavailable, no-op */ });
|
||||
@@ -64,4 +64,4 @@ function entry(name) {
|
||||
return path.join(dir, 'dist', 'claude', name); // last-ditch; import will no-op if absent
|
||||
}
|
||||
|
||||
import(pathToFileURL(entry("statusline.js")).href).then((m) => m.main()).catch(() => { /* graft unavailable — no-op */ });
|
||||
import(pathToFileURL(entry("statusline.js")).href).then((m) => m.main()).catch(() => { /* graft unavailable, no-op */ });
|
||||
@@ -14,34 +14,35 @@ graph of who-calls-what. Querying a node costs a few hundred tokens; rebuilding
|
||||
that understanding by reading source costs thousands, and misses the edges.
|
||||
|
||||
Every command below is `$0`, needs no API key, and returns in under a second.
|
||||
There are six of them. **Pick the one that fits the task, run it, act on the
|
||||
answer; don't chain tools hoping for more. Most tasks need one call.**
|
||||
There are six of them. Pick the one that fits the task, run it, and act on the
|
||||
answer. Do not chain tools hoping for more. Most tasks need one call.
|
||||
|
||||
## The tools
|
||||
|
||||
### 1 · `graft ask "<question>" --source`: locate + understand (the default)
|
||||
Ranked retrieval over the graph, routed automatically between prose nodes and
|
||||
the wiring graph, returning the top hits with exact `file:line`.
|
||||
- `--source` inlines the code at each hit, the ≤8-line **crux** of each
|
||||
- `--source` inlines the code at each hit, the ≤8-line crux of each
|
||||
definition, so the result IS the code you need, no follow-up file read. Add
|
||||
`--full` only when the crux is too small to act on.
|
||||
- `--in <path>` narrows to a subtree before ranking; `-n N` caps results (default 8).
|
||||
- **Use it when** the question is conceptual or locational: "how does auth
|
||||
work", "where is rate-limiting handled", "what assembles the request pipeline".
|
||||
- Use it when the question is conceptual or locational, for example "how does
|
||||
auth work", "where is rate-limiting handled", "what assembles the request
|
||||
pipeline".
|
||||
- One ask usually answers. A genuinely multi-part question needs one ask per
|
||||
distinct sub-aspect, never the same question reworded. Few or weak hits mean
|
||||
switch tool (grep / skeleton / callers), don't re-ask.
|
||||
|
||||
### 2 · `graft grep "<pattern>"`: exhaustive find
|
||||
Regex (or `--fixed` for a literal) over every indexed file, hits **grouped by
|
||||
enclosing symbol** and ranked by coupling; it also reports files it couldn't read.
|
||||
- **Use it when** you need every occurrence: all call sites, all uses of a
|
||||
constant, all providers. `ask` is ranked top-N and *will* miss instances;
|
||||
grep won't. One grep replaces a spray of asks.
|
||||
- Search a **short symbol name or literal**, not a full guessed signature: an
|
||||
Regex (or `--fixed` for a literal) over every indexed file, hits grouped by
|
||||
enclosing symbol and ranked by coupling; it also reports files it could not read.
|
||||
- Use it when you need every occurrence: all call sites, all uses of a
|
||||
constant, all providers. `ask` is ranked top-N and can miss instances;
|
||||
grep does not. One grep replaces a spray of asks.
|
||||
- Search a short symbol name or literal, not a full guessed signature: an
|
||||
over-specific regex (`func (s *Server) GenerateHandler`) returns nothing even
|
||||
when the code is indexed. If a grep misses, **loosen it** (drop the receiver
|
||||
and signature, keep the bare name) and retry `graft grep` — do NOT switch to
|
||||
when the code is indexed. If a grep misses, loosen it (drop the receiver
|
||||
and signature, keep the bare name) and retry `graft grep`. Do not switch to
|
||||
raw `grep -rn`, which is slower and unranked.
|
||||
- `-i` case-insensitive; `--in <path>` scopes to a subtree. Raw `grep -rn` is
|
||||
only for files graft genuinely doesn't index (docs, configs, brand-new files).
|
||||
@@ -49,38 +50,38 @@ enclosing symbol** and ranked by coupling; it also reports files it couldn't rea
|
||||
### 3 · `graft skeleton <file>`: a file's API at a glance
|
||||
Signatures-only view of one file (every function / method / type with its span)
|
||||
in ~200 tokens, ~10x cheaper than reading the file.
|
||||
- **Use it when** you need "what's in this file / what can I call here" before
|
||||
editing or wiring into it. One skeleton is the whole answer for a file; don't
|
||||
re-skeleton the same file, and don't skeleton every file `map` already named.
|
||||
- Use it when you need "what's in this file / what can I call here" before
|
||||
editing or wiring into it. One skeleton is the whole answer for a file; do not
|
||||
re-skeleton the same file, and do not skeleton every file `map` already named.
|
||||
|
||||
### 4 · `graft callers <symbol>`: the exact edges
|
||||
Precomputed call/reference edges, not a text search. Symbol can be bare
|
||||
(`Foo`), qualified (`Class.method`), or package-qualified (`pkg.Fn`).
|
||||
- default `--direction in`: **who calls/references** this; run before you
|
||||
- default `--direction in`: who calls or references this; run before you
|
||||
rename, delete, or change its signature.
|
||||
- `--direction out`: **what this symbol itself calls/depends on** (the old `callees`).
|
||||
- `--depth N`: walk transitively N hops for the **full blast radius** (the old
|
||||
- `--direction out`: what this symbol itself calls or depends on (the old `callees`).
|
||||
- `--depth N`: walk transitively N hops for the full blast radius (the old
|
||||
`impact`); `--depth 2` is the usual "what breaks if I touch this".
|
||||
- `--depth all`: the **entire connected closure** — every source reachable
|
||||
through the edges. Reach for this before a **refactor, rename, or any
|
||||
multi-file change**: it surfaces the sibling and downstream files (platform
|
||||
- `--depth all`: the entire connected closure, meaning every source reachable
|
||||
through the edges. Reach for this before a refactor, rename, or any
|
||||
multi-file change: it surfaces the sibling and downstream files (platform
|
||||
variants, a module you must split out) that a single-file edit would miss.
|
||||
|
||||
### 5 · `graft map`: orientation for an unfamiliar repo or area
|
||||
A token-budgeted tour: directory clusters, per-directory hubs, and global
|
||||
hotspots, straight from the wiring graph.
|
||||
- **Use it when** you land in a repo cold or are asked for "the architecture".
|
||||
`map` alone is the answer: read the hub cards it names; do NOT then skeleton
|
||||
- Use it when you land in a repo cold or are asked for "the architecture".
|
||||
`map` alone is the answer: read the hub cards it names; do not then skeleton
|
||||
or ask your way through every subsystem it lists. `--max-dirs N` widens it.
|
||||
|
||||
### 6 · Lifecycle: `graft build` / `graft check`
|
||||
Every tool above refreshes the graph itself before answering, so what those tools
|
||||
return always describes the code as it is right now — including edits you just made
|
||||
and have not committed. You do **not** need to run `build` after editing.
|
||||
return always describes the code as it is right now, including edits you just made
|
||||
and have not committed. You do not need to run `build` after editing.
|
||||
|
||||
One caveat, if you `grep` the markdown under `graft/` directly: those cards are a
|
||||
One caveat: if you `grep` the markdown under `graft/` directly, those cards are a
|
||||
projection, rebuilt at the end of the turn rather than on each query, so after an edit
|
||||
they can lag. The tools above never do — prefer them, and treat a card's spans as
|
||||
they can lag. The tools above never do. Prefer them, and treat a card's spans as
|
||||
stale if you have edited that file this turn.
|
||||
|
||||
`build` is for the LLM layer (`--deep` adds a concept map; skip unless asked);
|
||||
@@ -93,9 +94,9 @@ stale if you have edited that file this turn.
|
||||
| Onboarding / "explain this codebase" | `graft map`, then read the named hub cards | 1 |
|
||||
| Understanding a flow ("how does X work") | `graft ask "<flow>" --source` | 1 |
|
||||
| Finding where a change belongs | `graft ask "where is <behavior>" --source` | 1 |
|
||||
| Editing a symbol you can already name | `graft grep "<symbol>"`, edit at the `file:line` (skip `ask` — you know where it is) | 1 |
|
||||
| Editing a symbol you can already name | `graft grep "<symbol>"`, edit at the `file:line` (skip `ask`, you know where it is) | 1 |
|
||||
| Renaming / deleting / changing a signature | `graft callers <sym> --depth 2` first | 1 |
|
||||
| Refactor / multi-file change (before editing) | `graft callers <sym> --depth all` — map every connected file, don't stop at the first | 1 |
|
||||
| Refactor / multi-file change (before editing) | `graft callers <sym> --depth all` to map every connected file, do not stop at the first | 1 |
|
||||
| "What does this depend on?" | `graft callers <sym> --direction out` | 1 |
|
||||
| Finding every occurrence of a pattern | `graft grep "<literal>"` | 1 |
|
||||
| "What's the API of this file?" | `graft skeleton <file>` | 1 |
|
||||
@@ -113,25 +114,26 @@ you already know where you're working, narrow with `graft ask "<task>" --in <sco
|
||||
don't re-open or re-grep files to "double-check".
|
||||
- When the task already names the file or symbol to change, go straight there:
|
||||
`graft grep "<symbol>"` for the exact `file:line`, then edit. Reserve
|
||||
`graft ask` for when you don't yet know where the code lives — an `ask`
|
||||
round-trip is wasted on a target you can already name.
|
||||
`graft ask` for when you do not yet know where the code lives, because an
|
||||
`ask` round-trip is wasted on a target you can already name.
|
||||
- Trust the answer and act. Reach for a second tool only when the first genuinely
|
||||
fell short: weak hits, a truncated span, or a need to be exhaustive.
|
||||
- If graft names a path that isn't on disk, its index is ahead of your checkout
|
||||
(a branch switch or unpulled move). Don't read the missing file — `graft grep`
|
||||
the symbol to find where it lives now, or run `graft build` to refresh.
|
||||
(a branch switch or unpulled move). Do not read the missing file. Instead
|
||||
`graft grep` the symbol to find where it lives now, or run `graft build` to
|
||||
refresh.
|
||||
|
||||
## Report what graft saved, every turn
|
||||
Each retrieval tool **opens** its output with a `[graft] tokens saved ≈ N` line:
|
||||
Each retrieval tool opens its output with a `[graft] tokens saved ≈ N` line:
|
||||
the estimated tokens that call saved versus reading the files it covers whole.
|
||||
Whenever you used any graft tool in a turn, close your reply with a one-line
|
||||
tally summing those numbers across every graft call you made, e.g.
|
||||
`🌱 graft saved ~12,400 tokens this turn (3 calls)`. A call with no such line
|
||||
tally summing those numbers across every graft call you made, for example
|
||||
`graft saved ~12,400 tokens this turn (3 calls)`. A call with no such line
|
||||
(tiny files, where the pointers cost as much as the source) saved nothing, so
|
||||
skip it. This is the per-turn figure; the statusline carries the running
|
||||
session total.
|
||||
|
||||
**Never pipe a graft command through `head`, `tail`, or `sed -n`.** Every tool
|
||||
Never pipe a graft command through `head`, `tail`, or `sed -n`. Every tool
|
||||
is already capped and states what it dropped; clipping it costs you hits you
|
||||
asked for, and it silently drops the savings line the statusline's running
|
||||
total is parsed from.
|
||||
|
||||
Reference in new issue
Block a user