| name | gts-analyze |
| description | Analyze how the GTS (Global Type System) is used in a Gear — defined types, declared instances, and references across sdk / main / plugin / docs. Thin wrapper around the `gts-analyze` CLI under tools/. |
| user-invocable | true |
| allowed-tools | Bash |
gts-analyze
Thin wrapper around the workspace binary at tools/gts-analyze/. Source code, full docs, and human-readable usage live there: tools/gts-analyze/README.md.
How to invoke
- Parse the user's invocation for a gear path (absolute or repo-relative). If absent, ask once.
- Run from the workspace root:
cargo run --release -p gts-analyze -- <MODULE_PATH> [flags]
First invocation in a fresh checkout compiles the crate (~30s with syn); subsequent runs are instant.
- Show the markdown report verbatim — don't summarise away the per-type detail.
Flags
--format json — machine-readable JSON instead of markdown.--out FILE — write report to file instead of stdout.--include-tests — include Rust test files (default skips integration tests, benches, *_test(s).rs, and items behind #[test] / #[cfg(test)]).--skip-docs — drop every *.md and any file under docs/. Note: type definitions sourced from docs/schemas/*.schema.json disappear too — use only for code-only audits.-v / --verbose — expand reference lists to per-line file:line — context. Default is compact (file + count).
Report sections
- Summary — file counts and totals.
- GTS Types Defined Here — per defined type: schema source (
#[gts_type_schema] / *.schema.json / struct_to_gts_schema!), location, struct name when applicable, and usage breakdown across sdk / main / plugin / doc.
- GTS Instances Defined Here — per declared instance: macro form, inferred typed struct, base type, location, and usage breakdown.
- Other GTS IDs Referenced — table of IDs not defined here, plus a collapsible per-ID file breakdown.
Tips
- A GTS ID ending with
~ is a Type, otherwise an Instance (gts-spec §8.1).
- For doc-heavy gears with hundreds of
.md references, suggest --skip-docs if the user only cares about code usage.
cargo run builds on first invocation; if the user is running this often, cargo build --release -p gts-analyze once up front avoids latency.
