Skip to content

t1k:cocos:playable:reuse-coverage

FieldValue
Moduleplayable
Version4.33.13
Effortmedium
Tools—

Keywords: coverage do reuse, đo reuse, reuse-coverage, stdlib coverage, strangler progress, tỉ lệ tái sử dụng

/t1k:cocos:playable:reuse-coverage
[<project-root>] [--json <out>] [--index <clone-index-dir>] [--scope <glob>]... [--cc-thickness]

Phase 1 (ĐO) of plans/260916-stdlib-reuse-80. Answers one question, and answers it actionably:

Of the code a playable project had to write itself, how much did it consume from the studio library instead of writing?

coverage = stdlib / (stdlib + project)

The number alone is not the deliverable — a headline percentage is unfalsifiable and unfixable on its own. What makes it actionable is the per-subsystem line beside it (end-card 0% · tutorial 0% · scoring 100%): a 0% subsystem is a named migration target, and a 100% one is proof the seam already works. The strangler split (stdlib 12% · baseline 45% · project 43%) is printed for the same reason — it shows whether the 80% target is being reached by consuming the library or merely by the baseline growing underneath.

The four buckets, and why the denominator is only two of them

Section titled “The four buckets, and why the denominator is only two of them”
bucketnumeratordenominatorwhat it is
stdlibyesyes@playablelabs/{core,feature,mechanic,sdk,cc}-* — the cocos-stdlib layer (the exact prefix set is declared in assets/reuse-sources.json, not restated here as a second SSOT)
projectnoyesgameplay/logic TS the project genuinely authored
baselinenonogame-foundation, the pre-layering packages, and code inherited from PlayableAdsTemplate
gluenono@ccclass components that only forward, plus per-campaign config/parameter data

baseline is excluded from both sides by user ruling (2026-09-16): a playable template and game-foundation are present in essentially every project before any work starts, so counting them as reuse would let a project reach the target without consuming anything. glue is excluded because it is the coordinator shell the architecture requires to exist.

The anti-circumvention constraint is what stops those exclusions from being a loophole. A @ccclass component carrying REAL logic counts as project, not glue — that logic is logic that should have been extracted. Without this, every project reaches 95% by pushing logic into components. The implemented definition of “real logic” is the plan’s own, literally:

  • control flow beyond a guard clause (a loop, a switch, a try, an if with an else)
  • arithmetic / any binary operator on a value
  • state management (a compound assignment, ++/--, an accumulating field write)
  • any hand-written method whose body does non-forwarding work

A lifecycle hook is held to the same bar as a callback: onLoad() with a loop in it is project.

CheckWhy
The target is a Cocos project (<root>/assets/ exists)The walker is rooted there; a wrong root is exit 2, not an empty report
Pinned parser installed: bun install --frozen-lockfile --ignore-scripts --cwd .claude/modules/playable/skills/t1k-cocos-playable-reuse-coverage/scriptsts-morph 21.0.1 re-exports the TypeScript namespace. There is deliberately no regex fallback — a missing pin is exit 2 printing the exact install command (t1k-cocos-base-source-scan-guard convention)
The harvest pin is installed too, when reading a fingerprint index: … --prefix .claude/modules/playable/skills/t1k-cocos-playable-stdlib-harvest/scriptsThe template fingerprint is ast-normalize.cjs from that skill; it resolves its own node_modules. Missing → the fingerprint cannot run, and the run says so (partial / unavailable), never “no template code found”
A harvest/clone-index/The1Studio__PlayableAdsTemplate.jsonl is reachable, or --index / T1K_CLONE_INDEX points at oneWithout it, template-inherited code cannot be subtracted at all. Pass --index explicitly whenever a number will be recorded or compared — the default resolution walks from cwd first, which can silently find a DIFFERENT-but-real index than the one another invocation found (see “the WRONG index” below)
Terminal window
bun .claude/modules/playable/skills/t1k-cocos-playable-reuse-coverage/scripts/reuse-coverage.cjs \
<project-root> [--json <out>] [--index <clone-index-dir>] [--scope <glob>]... [--cc-thickness]

Default --json path is <project-root>/reports/reuse-coverage.json. The text table goes to stdout in every case, so the headline never requires opening the JSON.

--scope restricts which files may count as project — repeatable, ORed together; it never touches stdlib, and baseline/glue classification is unchanged. A glob with no */? scopes that path and everything nested under it, so --scope assets/scripts/BounceDefendersPLA needs no /**. The applied scope (or its absence) is always recorded at report.scope.

--cc-thickness adds report.ccThickness: per extends Component file, how many codeLines are still shell (glueLines) versus logic (logicLines), plus totals. It is the before/after measurement for Stage B4 of the PLA retrofit — logic moves OUT of components into pure-TS packages and this is the number that proves the move happened. gluePct is glue over the cc layer, and logicLines + glueLines === codeLines for every row. Absent the flag the report’s keys are exactly as they were; a pure-logic module gets no row, because it has no cc layer to measure. Full contract: references/hard-rules-and-references.md § “—cc-thickness”.

EXIT — 0 ok · 2 usage error, unreadable project, or missing pinned dependency. There is deliberately no exit 1: this script reports a NUMBER, and a nonzero exit would be read by a caller as “the gate failed” when the number may be perfectly acceptable. A dependency or usage problem is a crash, and a crash reusing a verdict code would be indistinguishable from a low-coverage verdict.

coverage 0% (0/15497 codeLines)
split: stdlib 0% · baseline 26.2% · project 73.2%
templateBaseline: available
  • coverage: null is not 0%. With no stdlib and no project code there is no denominator, and “0/0” is undefined. The report renders that as n/a — a real 0% and an undefined ratio must not look the same (theonekit-core/.claude/modules/t1k-verification/rules/green-that-proves-nothing.md § “rate over an empty denominator”).
  • split is the strangler reading, not a second coverage number. Since baseline is excluded from the metric, a project whose baseline share grows while stdlib stays 0 has not improved.
  • templateBaseline is a three-state honesty gate, and it must be read before trusting the number:
statemeaningwhat to do
availableevery candidate was fingerprinted, none threwnone — the figures are a clean reading
partialsome candidates threw; those were not subtractedfix the reported first error, then re-run
unavailablenothing could be fingerprinted, or no index was foundpass --index; until then project is an upper bound and coverage a lower bound

The gate exists because of a real defect: on RushTankPLA the index was found and parsed but every fingerprint threw (the harvest pin was absent), and the run reported available with 0 matches — 15,860 un-subtracted lines reading exactly like a project with no template inheritance. A step that did not run is indistinguishable from a step that ran and found nothing, unless the failure count is allowed to change the state. templateBaselineVerdict() is the pure function that does, and it is unit-pinned.

  • A second failure mode reads as available and is still wrong: the WRONG index, found silently by the default resolution. --index is optional, and the <cwd> candidate is checked before anything derived from the project root, so the same command can read two different clone-index directories. Always pass --index <clone-index-dir> when a number will be recorded, compared or handed on; a bare templateBaseline: available proves an index was read, not which one. Measured case: references/wrong-index.md.

  • declaredSources[].matched: false is how a stale glob surfaces: a source declared in the manifest that matches nothing in this project. That is informational (a project need not install every package) — but a source you expect to match and see at false means the glob is wrong.

  • A relocation-only commit moves coverage the WRONG way, by design — do not read it as regression. Relocated pure logic with no package vendored yet raises the project denominator, so coverage drops mid-retrofit. A retrofit reporting coverage mid-relocation must say so. Measured case: references/relocation-denominator.md.

The second metric: adoption — what is USED, not what was INSTALLED

Section titled “The second metric: adoption — what is USED, not what was INSTALLED”

coverage has a structural blind spot: its numerator is the codeLines of a vendored package directory, so a project raises its score by INSTALLING a package it never calls. adoption closes that gap with a numerator that is a property of the CALL SITE:

adoption = adoptingProjectLines / projectLines unit: codeLines
Terminal window
bun .claude/modules/playable/skills/t1k-cocos-playable-reuse-coverage/scripts/adoption.cjs \
<project-root> [--json <out>] [--index <clone-index-dir>] [--verdict] [--scope <glob>]...
coverageadoption
the numerator is a property ofwhat was installedwhat is used
install a package, never call itrisesunchanged
delete a replaced filedenominator shrinksdenominator shrinks and the surviving call sites are credited

Numerator — codeLines of adopting declarations inside files the parent classifies project. An adopting declaration is a FunctionDeclaration / ClassDeclaration / MethodDeclaration / module-scope VariableStatement / arrow-bodied PropertyDeclaration whose body contains at least one value-position reference to a name bound by an import from a declared reuse source.

Denominator — split.project.lines from the PARENT’s own report, read by running it as a child. There is no second classifier and therefore no second definition of “project” to drift; baseline and glue stay excluded from both sides by the one existing ruling. A side effect worth having: the parent’s every failure path becomes an observable exit code here, and its templateBaseline honesty gate travels with the number (denominatorSource.cleanReading) instead of being dropped at the boundary.

EXIT — 0 ran (good number or bad) · 2 usage error, unreadable project, missing pinned dep, or a parent run with no usable denominator. There is deliberately no exit 1, for the same reason as the parent: this reports a NUMBER, and a crash reusing a verdict code would be indistinguishable from a low-adoption verdict.

The numerator counts lines the project would have had to write itself and did not — so an adopting declaration must DELEGATE A VALUE, not merely mention a name.

Value positions = initializer, argument, return expression, operand, receiver. Type positions (TypeReference, TypeQuery, heritage clauses, as) and property-name positions (PropertyAccessExpression.name, PropertyAssignment.name) are not value positions.

Four anti-gaming modes, each pinned TWO-WAY

Section titled “Four anti-gaming modes, each pinned TWO-WAY”

A one-directional pin is satisfied by a rule that is simply always wrong in the other direction, so each mode is asserted on a declaration that must score 0 and a sibling that must score >0.

modemust score 0must score >0
(a) the import line itselfa file whose only library mention is the importthe same specifier with a real call
(b) bare re-export export { X } from 'pkg'a barrel index.tsthe same names imported and called
(c) unused importthe unused declarationthe sibling that really calls it
(d) discarded value void pkg.f();the discarded callconst x = pkg.f();

INNERMOST WINS. A class that delegates inside one of its methods contributes that METHOD’s span, not the whole class — presentation holds 35% of a real fleet’s project lines, and a class-level span would let a single library call credit a 500-line view class. Innermost-wins also makes all five declared kinds reachable: outermost-wins would make MethodDeclaration, VariableStatement and arrow PropertyDeclaration dead, since each nests inside a ClassDeclaration or a FunctionDeclaration.

  • adoption: null is not 0%. No project code means no denominator, and the report renders that as n/a — the parent’s rule, kept.
  • denominatorSource.cleanReading: false means the parent’s template fingerprint did not resolve, so template-inherited files are counted as project. The denominator is an UPPER bound and adoption a LOWER bound — pass --index <clone-index-dir> for a clean reading.
  • unresolvedSpecifiers lists @playablelabs/... specifiers that resolved to no declared source. Informational, but a specifier you expect to resolve and see here means the manifest glob is wrong.
  • --verdict is NOT a threshold gate (same policy as the parent, and plan § Phase 5a): green when the number is MEASURABLE, red only when measurement itself breaks. Adoption is 0% on every repo in the fleet today, so a 50% threshold would be red forever and get ignored while a 0% threshold would be green forever — both are a gate that cannot fail for the reason it exists. A project that wants a real threshold sets one in a project-scope fragment.

The parent’s packageDirOf derives a source from a FILE’S PATH; it cannot resolve an import specifier. adoption.cjs adds that half. Three forms occur in this fleet, all live:

formexamplehow it resolves
db://db://assets/packages/@playablelabs/core-utils/src/maththe path after the scheme IS project-root-relative
relative../packages/@playablelabs/game-foundation/xresolved against the importing file’s own directory
bare@playablelabs/core-utilsnode_modules — not vendored under assets/, so reported as unresolved, never guessed

Only a source declared kind: "reuse" makes an import an adoption. Importing from a baseline source (game-foundation, a pre-layering package) is the delivery mechanism the template already used, not something the project chose to consume.

Adding a new reuse source — no code change

Section titled “Adding a new reuse source — no code change”

Which sources count as reuse and which as baseline is declared in assets/reuse-sources.json, never in the script: one entry per source, and adding or deleting one needs no code change. Entry shape and the two-way pins: references/adding-reuse-source.md.

Coverage and adoption are deterministic measurements. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run reuse-coverage.cjs and adoption.cjs and report the four-bucket numbers verbatimt1k-data-verifier
Decide what to do about low coverage or adoptionstays on the reasoning tier