Skip to content

t1k:cocos:base:code-graph

FieldValue
Modulebase
Version4.51.9
Effortlow
Tools—

Keywords: blast-radius, call-graph, cocos-graph, code-graph, cross-repo, extraction-candidate, god-nodes, pr-impact, shortest-path, who-calls

/t1k:cocos:base:code-graph
<structural question | symbol> [--repo <name>] [--json <out>]

Cocos Code Graph — Structural Answers, Cocos Recipes

Section titled “Cocos Code Graph — Structural Answers, Cocos Recipes”

The graph answers “what is connected to this?” by walking a tree-sitter AST across every enrolled Cocos repo. Where the corpus answers “does this exist?” by reading prose, the graph answers a question no text search can: aliasing, re-export and dynamic wiring are invisible to grep, so a grep miss is not an unused signal and a grep hit is not a dependency list.

Usage SSOT is core’s t1k-code-graph — reachability, the ten-tool surface, the known gaps and the corpus-first ordering all live there. Read it; this skill does not restate it. What this skill adds is the Cocos-specific recipe set (which tool answers which Cocos task) and the Cocos-only failure modes a recipe must route around.

Tool names are mcp__code-graph-cocos__<tool> — graph_stats, query_graph, get_node, get_neighbors, god_nodes, shortest_path, get_community, list_prs, get_pr_impact, triage_prs.

Before the first call — three preconditions

Section titled “Before the first call — three preconditions”
  1. Is the tool actually in this session? No mcp__code-graph-cocos__* in the tool list means the session is not connected. Record graph: unavailable and continue on grep — never a silent skip, and never a dead-code verdict in its place (below). Connect per core SKILL.md § Connecting.
  2. Is the repo enrolled? The Cocos scope covers the repos carrying the enrolment topic plus the engine topic. A repo outside it returns nothing — that is a scope fact, not “this symbol has no callers.”
  3. How old is the answer? The graph is built nightly, default branch only. A symbol you added today is not in it, and a call site you just deleted still is. Anything date-sensitive goes through graph_stats first; anything from a feature branch is absent by construction.

Each recipe names its tool and the Cocos twist that makes it non-obvious.

Blast radius before a rename, repoint or retire

Section titled “Blast radius before a rename, repoint or retire”

get_neighbors on the symbol, then widen transitively for a rename.

The Cocos twist is what “repoint” means here. Repointing db:// imports, retiring a vendored copy, or swapping a local subsystem for an @playablelabs package all delete or move source that the graph sees as an edge source — so a non-empty incoming set is the argument against retiring, and an empty one is still not a licence to delete. Nightly build: a call site added since the last build is invisible. Ground the graph answer with a grep on the same symbol before any destructive step (rules/knowledge-sweep-cocos.md Step 2). Used by t1k-cocos-playable-modularize-refactor (Tier 2/2.75 swaps) and t1k-cocos-playable-stdlib-adopt (its pre-retire reachability stage).

god_nodes for the scope, then get_node on each hit — dedupe by repo before reading the list as a candidate set.

This is the recipe with the sharpest Cocos trap: the merge does not dedupe symbols across repos, so the same vendored type appears once per repo that vendors it, at an identical edge count. A six-row MotionHandle result is one load-bearing NAME seen six times, not six types — read it as confidence that the name is load-bearing, and never as volume of extractable work. Confirm with get_node and keep only distinct (repo, qualified name) pairs before ranking. Also assume limit is advisory: it is not honoured, so ask for the count you want and read what arrives.

shortest_path between the two qualified names. This is the tool for indirection grep cannot follow at all — a signal published on a bus, a handler registered by string, an indirect dispatch. On a Cocos codebase the intermediate hops are frequently signalBus subscribers, which are exactly the edges no import graph records.

get_pr_impact for one PR, triage_prs for a queue, list_prs to discover them. These read the diff, and the diff is live while the graph is nightly — so a PR touching a symbol added since the last build gets an impact set that omits it. Use the PR tools to aim a review (which subsystems and callers to look at), then verify the flagged callers on disk. Never report a PR as “no impact” from a nightly graph.

get_community — and the label is a placeholder (Community N). Read membership, not the label (core SKILL.md § Known gaps). Useful here as a coarse coupling check: two subsystems in one community are candidates for the same vertical slice.

graph_stats — counts, extraction quality, and the answer to “is this thing current?”. Ask it before trusting any number, including the ones in core SKILL.md’s table, which is a dated snapshot and does not move with the nightly.

Cocos-only gaps — recipes must route around these

Section titled “Cocos-only gaps — recipes must route around these”

The general gaps (placeholder community names, no cross-repo dedupe, limit ignored, nightly not live) are stated once in core SKILL.md. Two more bite specifically here:

  • No dead-code verdicts on Cocos — not a weak answer, a wrong one. @ccclass components are attached in prefabs via __uuid__, not imported, so an import-graph reading of “unreferenced” is simply wrong: three such wrong verdicts were recorded before the graph was narrowed. Do not answer a Cocos dead-code question from this graph at all until prefab __uuid__ edges are indexed. “Is this component still used?” is a prefab question — answer it against the .prefab/.scene JSON (t1k-cocos-base-uuid-verify, t1k-cocos-playable-parameter-audit), never from a zero-caller graph result.
  • Enrolled-repo skew is silent. A vendored copy in a non-enrolled repo is invisible, so two repos can disagree on the same symbol and only one appears. When a result contradicts what is on disk, check enrolment before checking the disk.

Provenance — how a graph answer is recorded

Section titled “Provenance — how a graph answer is recorded”

Every claim carries its source; a negative states its scope (theonekit-core/.claude/modules/t1k-verification/rules/negative-result-scope.md). Emit, beside the existing discovery:/scope: line:

graph: cocos scope · <N> nodes / <M> edges · built <date from graph_stats> · repos: <enrolled>
graph: unavailable — mcp__code-graph-cocos__* absent this session; grounded by grep only

graph: unavailable is a recorded fact, never a silent skip and never grounds a CONTRIBUTE/greenfield claim on its own. That is the knowledge-sweep-cocos.md Step 2.5 contract.

  • t1k-code-graph (core) — the usage SSOT: endpoints, connecting, the ten tools, the full gap list, the corpus-first ordering. Cite it, do not restate it.
  • t1k-cocos-base-knowledge-sweep → skills/t1k-cocos-base-knowledge-sweep/references/graph-grounding.md — the sweep’s Step 2.5, which calls this skill.
  • rules/knowledge-sweep-cocos.md — the always-loaded loop this skill’s Step 2.5 slots into.
  • t1k-cocos-playable-modularize-reuse-scan, …-refactor, t1k-cocos-playable-stdlib-adopt — the pipelines that consume the blast-radius and extraction recipes.
  • t1k-graphify — a different tool over a different graph; not a substitute.