cg
Trace code and assess change impact via the pre-built symbol, call-graph and co-edit index.
Surething-io · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Surething-io/cockpit --skill cg技能说明
name: cg description: "Trace code and assess change impact via the pre-built symbol, call-graph and co-edit index."
Enter project graph exploration mode (CodeGraph).
CodeGraph = pre-built symbol + call-graph index + git co-edit view. Six endpoints, each answers one class of question:
| Question | Endpoint |
|---|---|
| Where is X defined / which files share the name? | search?q=X |
| Who calls X? | callers?qname=X |
| What does X call? | callees?qname=X |
| Changing X affects which symbols? | impact?qname=X&depth=2 |
| What symbols does file F contain? | file?path=F |
| Which files are commonly edited alongside F? (conventional coupling / parallel registries) | coedit?filePath=F |
All responses are coordinates / file paths — never source bodies. (One exception: search&includeLiterals=true echoes each matched literal's own text in value.) More precise than grep's textual match, cheaper in tokens than Reading whole files.
The 6 graph endpoints ({{BASE_URL}})
# search: find symbols by name → hits carry the same node shape as every other
# endpoint, so a hit's startLine/endLine feed Read directly.
# q is normalized for naming style: user_profile / userProfile / user-profile / USER_PROFILE are equivalent
# Pass includeLiterals=true to also search identifier-shaped string literals (tool names, event names,
# config keys, route paths — the "looks like a name but isn't an identifier" strings). The response
# then carries an extra literals[] array with value / filePath / line / enclosingSymbol per hit.
curl -fsS "{{BASE_URL}}/api/projectGraph/search?cwd=$PWD&q=<NAME>"
curl -fsS "{{BASE_URL}}/api/projectGraph/search?cwd=$PWD&q=<NAME>&includeLiterals=true"
# callers / callees: 1-hop call relations
curl -fsS "{{BASE_URL}}/api/projectGraph/callers?cwd=$PWD&qname=<QNAME>"
curl -fsS "{{BASE_URL}}/api/projectGraph/callees?cwd=$PWD&qname=<QNAME>"
# impact: transitive callers BFS (depth 1-5, default 2; out-of-range is clamped
# silently, not rejected). `truncated: true` = node ceiling hit, list is partial.
curl -fsS "{{BASE_URL}}/api/projectGraph/impact?cwd=$PWD&qname=<QNAME>&depth=2"
# file: file symbol tree (no source). Hierarchical: nested symbols live in
# children[] — always an array, empty for leaves (never null / never absent).
curl -fsS "{{BASE_URL}}/api/projectGraph/file?cwd=$PWD&path=<REL_PATH>"
# coedit: files commonly edited alongside the target = git log history + current working-tree co-edits
# catches "conventional coupling" the call-graph can't see (parallel registries / double-writes / sibling .md configs)
# history[] entries may name PRE-RENAME paths (git --follow), so a path here need not exist today.
# `cooccurrence` is a RAW COUNT; the ratio ships alongside as `probability`.
curl -fsS "{{BASE_URL}}/api/projectGraph/coedit?cwd=$PWD&filePath=<REL_PATH>"
Response shapes
Every endpoint speaks ONE node shape (call it NODE):
{ filePath, qualifiedName, name, kind, startLine, endLine, params?[] }
params is OPTIONAL: absent for non-callables (class / interface / type / enum /
const) and for languages without a tree-sitter grammar. params: [] is different —
it means "0 parameters", not "unknown".
search { files[], symbols[], literals?[] } # literals only with includeLiterals=true
files[] = { type:'file', label, hint?, target: { filePath } }
symbols[] = { type:'symbol', label, hint?, target: NODE }
literals[] = { type:'literal', value, filePath, line, enclosingSymbol? }
# narrow on the outer `type`
file { filePath, language, symbols[] }
symbols[] = NODE plus { contentHash, children[] }
# children[] is always an array, empty for leaves (never null / absent)
callers { qname, target: NODE|null, callers[]: { caller: NODE, callLines[] }, ambiguousIn? }
callees { qname, target: NODE|null, callees[]: { callee: NODE, callLines[] }, ambiguousIn? }
impact { qname, target: NODE|null, nodes[]: { symbol: NODE, depth }, truncated, ambiguousIn? }
coedit { target: string, totalCommits, uncommitted[],
history[]: { filePath, cooccurrence, probability, lastCoEdit } }
# probability = cooccurrence / totalCommits, precomputed. `cooccurrence`
# alone is a RAW COUNT — never compare it against a ratio threshold.
context { results[]: NODE + { score, signals[] }, seeds[]: { node, weight, from }, degraded }
related { target, results[]: NODE + { score, relations[] }, coedit[], degraded, ambiguousIn? }
risk { target, totalImpactedNodes, highRisk[]: NODE + { depth, risk{}, tags[] },
suggestedTests[], coedit[], degraded, degradedReason? } # NOTE: no ambiguousIn
affected { testFiles[], byInput[]: { filePath, reachable, reachableTests[] },
unresolved[], stats: { visited, bfsMs, truncated }, degraded }
The coedit[] embedded in related / risk is a strict SUPERSET of a /coedit
history row (same fields plus a per-row totalCommits) — you never need a second
request to get recency.
Errors are { error, tag }. Tags seen from these routes: ValidationError (400),
NotFoundError (404), AppError (500 — every endpoint wraps its lookup in one, so
an index/git failure surfaces here), InternalError (500, uncaught defect).
Silent-failure traps
- An unknown qname returns HTTP 200, not 404.
callers/callees/impact/related/riskanswer a typo'd or non-indexed name withtarget: null(every endpoint spells this slottarget, callees included) and empty arrays — byte-identical to a real symbol that genuinely has no callers. Always checktarget !== nullbefore concluding "nothing calls this" / "this change is safe". Same forcoediton an unknown path (200, empty). Onlyfile404s. - A non-null
targetwithcallers: []does NOT mean "nothing calls this".obj.method()resolves only when the receiver's imported name directly names the conta