t1k:cocos:playable:reuse-coverage
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | medium |
| Tools | — |
Keywords: coverage do reuse, đo reuse, reuse-coverage, stdlib coverage, strangler progress, tỉ lệ tái sử dụng
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:reuse-coverage[<project-root>] [--json <out>] [--index <clone-index-dir>] [--scope <glob>]... [--cc-thickness]reuse-coverage
Section titled “reuse-coverage”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”| bucket | numerator | denominator | what it is |
|---|---|---|---|
stdlib | yes | yes | @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) |
project | no | yes | gameplay/logic TS the project genuinely authored |
baseline | no | no | game-foundation, the pre-layering packages, and code inherited from PlayableAdsTemplate |
glue | no | no | @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, atry, anifwith anelse) - 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.
Preconditions
Section titled “Preconditions”| Check | Why |
|---|---|
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/scripts | ts-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/scripts | The 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 one | Without 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) |
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.
Reading the output
Section titled “Reading the output”coverage 0% (0/15497 codeLines)split: stdlib 0% · baseline 26.2% · project 73.2%templateBaseline: availablecoverage: nullis not0%. With no stdlib and no project code there is no denominator, and “0/0” is undefined. The report renders that asn/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”).splitis the strangler reading, not a second coverage number. Sincebaselineis excluded from the metric, a project whose baseline share grows while stdlib stays 0 has not improved.templateBaselineis a three-state honesty gate, and it must be read before trusting the number:
| state | meaning | what to do |
|---|---|---|
available | every candidate was fingerprinted, none threw | none — the figures are a clean reading |
partial | some candidates threw; those were not subtracted | fix the reported first error, then re-run |
unavailable | nothing could be fingerprinted, or no index was found | pass --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
availableand is still wrong: the WRONG index, found silently by the default resolution.--indexis 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 baretemplateBaseline: availableproves an index was read, not which one. Measured case:references/wrong-index.md. -
declaredSources[].matched: falseis 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 atfalsemeans the glob is wrong. -
A relocation-only commit moves
coveragethe WRONG way, by design — do not read it as regression. Relocated pure logic with no package vendored yet raises theprojectdenominator, socoveragedrops 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: codeLinesbun .claude/modules/playable/skills/t1k-cocos-playable-reuse-coverage/scripts/adoption.cjs \ <project-root> [--json <out>] [--index <clone-index-dir>] [--verdict] [--scope <glob>]...coverage | adoption | |
|---|---|---|
| the numerator is a property of | what was installed | what is used |
| install a package, never call it | rises | unchanged |
| delete a replaced file | denominator shrinks | denominator 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 invariant (do not weaken)
Section titled “The invariant (do not weaken)”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.
| mode | must score 0 | must score >0 |
|---|---|---|
(a) the import line itself | a file whose only library mention is the import | the same specifier with a real call |
(b) bare re-export export { X } from 'pkg' | a barrel index.ts | the same names imported and called |
| (c) unused import | the unused declaration | the sibling that really calls it |
(d) discarded value void pkg.f(); | the discarded call | const 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.
Reading the output
Section titled “Reading the output”adoption: nullis not0%. No project code means no denominator, and the report renders that asn/a— the parent’s rule, kept.denominatorSource.cleanReading: falsemeans the parent’s template fingerprint did not resolve, so template-inherited files are counted asproject. The denominator is an UPPER bound and adoption a LOWER bound — pass--index <clone-index-dir>for a clean reading.unresolvedSpecifierslists@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.--verdictis 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.
Specifier → source resolution
Section titled “Specifier → source resolution”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:
| form | example | how it resolves |
|---|---|---|
db:// | db://assets/packages/@playablelabs/core-utils/src/math | the path after the scheme IS project-root-relative |
| relative | ../packages/@playablelabs/game-foundation/x | resolved against the importing file’s own directory |
| bare | @playablelabs/core-utils | node_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.
Executed by
Section titled “Executed by”Coverage and adoption are deterministic measurements. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run reuse-coverage.cjs and adoption.cjs and report the four-bucket numbers verbatim | t1k-data-verifier |
| Decide what to do about low coverage or adoption | stays on the reasoning tier |