t1k:cocos:base:script-graph

Field	Value
Module	`base`
Version	`1.10.0`
Effort	`medium`
Tools	—

Keywords: ccclass, class-diagram, cocos, cocos-creator, code-index, dependency-cruiser, doc-comments, doc-xml, docs, documentation, prefab, scene, script-graph, ts-morph, tsdoc, uuid

How to invoke

/t1k:cocos:base:script-graph

t1k-cocos-base-script-graph

Cocos Creator 3.x diagram adapter and TypeScript documenting tool for the T1K toolchain. Produces five outputs from Cocos project sources:

classes — @ccclass-decorated class diagram via ts-morph (inheritance + @property cross-refs)
modules — TypeScript module import graph via dependency-cruiser
scenes — Scene node hierarchy from assets/**/*.scene JSON via a custom JSON walker
prefabs — Prefab component tree from assets/**/*.prefab JSON via the same walker
docs — TSDoc doc-comment extraction into per-module doc-XML via ts-morph — the TypeScript analog of C#‘s <GenerateDocumentationFile> output (see Documentation extraction)

Prerequisites

Install the full Cocos toolchain:

t1k diagram install --preset cocos

Per-project tools (ts-morph, dependency-cruiser) are recorded as npm i --save-dev hints — version locks stay aligned with the project’s TypeScript version.

Global tools (mermaid-cli, graphviz) render Mermaid diagrams into images.

Usage

# Auto-detect and generate all diagrams
t1k diagram refresh

# Generate a specific type
node scripts/generate.cjs --type classes  --out-dir /tmp/out
node scripts/generate.cjs --type modules  --out-dir /tmp/out
node scripts/generate.cjs --type scenes   --out-dir /tmp/out
node scripts/generate.cjs --type prefabs  --out-dir /tmp/out
node scripts/generate.cjs --type docs     --out-dir /tmp/out   # per-module doc-XML + docs.md index

# Documentation extraction can also run standalone (the docs-xml.py analog):
node scripts/docs-ts.cjs export <src-dir> <out-dir> [--format xml|json|both]
node scripts/docs-ts.cjs convert <module.json> [module.xml]   # lossless JSON → XML

# Does this adapter apply to the current project?
node scripts/detect.cjs   # exit 0 = match

# List supported capabilities
node scripts/list-capabilities.cjs

# Tool requirements (mermaid-cli global + ts-morph/dep-cruiser per project)
node scripts/requirements.cjs

Output Files

Capability	Output
`classes`	`classes.md` — Mermaid `classDiagram` of `@ccclass` components
`modules`	`modules.md` — Mermaid graph from `dependency-cruiser --output-type mermaid`
`scenes`	`scenes.md` — Mermaid `flowchart TD` of scene node hierarchy (one section per `.scene` file)
`prefabs`	`prefabs.md` — Mermaid `flowchart TD` of prefab component tree (one section per `.prefab` file)
`docs`	`<module>.xml` (one per top-level `assets/scripts/` dir) in the C#-compiler doc-XML envelope, plus `docs.md` index

Stereotypes and Edge Semantics

<<ccclass>> stereotype on every detected @ccclass class.
Inheritance edge: class X extends Y where Y is another @ccclass.
Composition edge: @property(...) field labeled with the field name, pointing at the referenced class when resolvable.
Scene/prefab nodes: hierarchy follows _children; component attachments come from _components[].
UUID cross-references in components: resolved to a readable path via a prebuilt UUID → file map when possible; otherwise the first 8 chars of the UUID are kept for traceability.

Documentation extraction (`docs`)

The docs capability is the TypeScript analog of C#‘s per-assembly doc-XML (what the C# compiler emits with <GenerateDocumentationFile>true). It walks every .ts under the project via ts-morph and emits one <module>.xml per top-level assets/scripts/ dir, in the identical envelope:

<?xml version="1.0"?>
<doc>
    <assembly><name>gameplay</name></assembly>
    <members>
        <member name="M:BlockageDetector.scan(number,TileModel[])">
            <summary>Scan forward from the tip…</summary>
            <param name="arrowIndex">Index of the arrow being checked</param>
            <returns>ScanResult with the blocked flag and blocker index</returns>
        </member>
    </members>
</doc>

DOCUMENTED members only — a symbol with no TSDoc /** */ block is skipped (mirrors the C# pipeline); members sorted, 4-space indent, the “assembly” is the top-level script-folder name (Cocos has no .asmdef). Run it standalone or as a capability:

node scripts/docs-ts.cjs export <src> <out> [--format json|xml|both]
node scripts/docs-ts.cjs convert <module.json> [module.xml]   # lossless JSON → XML
node scripts/generate.cjs --type docs --out-dir <abs>          # XML + a docs.md index

The standalone docs-ts.cjs / generate.cjs --type docs are the primary entry points; the wider t1k diagram toolchain only invokes docs once it recognizes the 5th capability, so run it directly until then.

Full spec — cref-ID grammar (T:/M:/P:/F:), TSDoc→XML element mapping, the JSON↔XML model, grouping rules, and the docs-xml.py comparison: references/docs-extraction.md.

MVP Scope

The scene walker (Layer B, scenes/prefabs) and the docs extractor (ts-morph) are fully implemented. classes/modules still stub out with clear skip messages until the Mermaid Layer A/C extractors land. The adapter contract is stable; the capability surface is final at [classes, modules, scenes, prefabs, docs].

See references/scene-prefab-walker.md for the JSON walker design and references/ts-morph-ccclass.md for the class-diagram extractor spec (follow-up). The docs extractor lives in scripts/lib/ts-doc-extractor.cjs (consumed by both docs-ts.cjs and generate.cjs --type docs).

Known Limitations

Cocos Creator 2.x scene JSON shape differs — this adapter targets 3.x only. detect.cjs inspects project.json/package.json before accepting.
JSON.parse(fs.readFileSync) reads whole-file (~50 MB upper bound documented).
Deeply nested prefab variants are rendered as opaque leaves in v1 — variant-aware walking is a future enhancement.
Unresolved UUIDs fall back to their first-8-char prefix; not a hard error.

Gotchas

Cocos Creator class graphs depend on @ccclass decorator — utility scripts without @ccclass are skipped silently.
Component dependency graph != class graph — components reference each other through @property(Type), which is editor-only metadata. Use a separate parser pass for runtime deps.
Scene graph diagrams from .scene JSON are large — flat-collapse leaf transforms (Sprite, Label inside layout containers) before rendering.
Cocos 2.x is unsupported — detect.cjs only matches 3.x scene JSON; running against a 2.x project no-ops with a warning.
docs skips undocumented symbols by design — only members carrying a TSDoc /** */ block are emitted (matching the C# pipeline, which requires ///). A class with zero documented members produces no <member> entries.
docs needs per-project ts-morph — without it, generate.cjs --type docs emits a graceful stub with capabilities_skipped: ["docs"] (it does NOT hard-fail). Install with npm i --save-dev ts-morph. ts-morph is resolved from the target repo (and cwd), NOT from the skill’s own location — so you run the scripts in-place against any repo that has ts-morph installed; you do NOT install ts-morph next to the skill.
docs scans only under the scripts root — <src>/assets/scripts (or <src> when it has no such subtree). The repo’s node_modules/ and *.d.ts are auto-excluded, so a repo with hundreds of installed packages still yields only project members. Pointing --src at a single module dir scopes the scan to that dir.
docs cref uses written type nodes, not the type checker — param types are the annotated text (Vec3, TileModel[]), so inferred-only params fall back to any. Annotate public APIs (Cocos convention anyway).
docs grouping ≠ asset bundles — modules are top-level assets/scripts/ dirs, not Cocos asset-bundle roots. Bundle-aware grouping is a future enhancement.

References

File	Content
`references/scene-prefab-walker.md`	JSON shape notes for Cocos Creator 3.x + walker algorithm (~50 LOC)
`references/ts-morph-ccclass.md`	`@ccclass` decorator extraction spec
`references/dependency-cruiser-config.md`	Custom rule snippets for Cocos project layout
`references/docs-extraction.md`	`docs` capability: cref grammar, TSDoc→XML mapping, JSON↔XML, vs docs-xml.py