Judgment

Lookup sheet for stage 7. The question it exists to answer: which edit breaks a consumer, whose settings decided what a declaration is allowed to claim, and which construct still leaves something running once the type is gone?

Edit to verdict

An edit is safe exactly when every program that compiled against the old type still compiles against the new one, a question about assignability in a fixed direction, not about how large the edit looks on a diff. See lesson 43.

Publishing checklist

Three checks, run in order. See lesson 44.

1. Generate. Compile with declaration set, and emitDeclarationOnly too if a separate step already produces the JavaScript, then open the .d.ts the compiler actually wrote.
2. Resolve from a scratch consumer. Build a second, real package with its own package.json and tsconfig.json, install the library the way a real consumer would, and import the names a consumer would.
3. Read the declaration. Go through the .d.ts top to bottom, asking of every exported function whether each type it mentions is a primitive, exported by name, or accepted as unnamed.

Step 1 confirms only that the source type checks; step 2 only that resolution worked. Only step 3 catches a surface wider than intended, since a dragged-in internal type compiles as cleanly as a deliberately exported one. Step 2 is more forgiving than expected: with no types field and no exports map, resolution still finds a .d.ts beside whatever main names, the same fallback lesson 21 covers for a specifier missing its extension. The field only matters once that fallback finds nothing too, for example once a build moves the declaration file without updating a types condition; the consumer then gets the same TS7016 a dependency shipping no declarations at all would produce.

What the surface includes

An exported function's signature drags in every type it mentions, whether or not the author meant to publish that part; leaving it unexported removes only the name a consumer could use to write an annotation with. See lesson 44.

The author's settings are part of the contract

The stage's sharpest finding, verified end to end: a loose author setting publishes a false declaration that no consumer's own strictness can detect, since the wrongness was baked in before the declaration reached them. See lesson 45.

The last column of the table is a consequence of the arrow. A consumer's flags are not weaker than the author's, they are pointed at different code: everything to the right of the line. The declaration was already false to the left of it, and there is no second arrow going back.

A tsconfig.json behind a published package reads as a private build detail, but it decides which claims in the declaration are backed by a check, which makes it part of the interface whether a consumer reads it or not.

What does not erase

erasableSyntaxOnly names, in the compiler's own words, what it exists to refuse: "Do not allow runtime constructs that are not part of ECMAScript." A construct fails it exactly when compiling it invents JavaScript beyond the plain expression underneath. See lesson 46.

The decorator row differs because a standard decorator is itself an ECMAScript feature, so the code it produces is JavaScript's own semantics, not a TypeScript invention, exactly the flag's line. The trap runs the other way: the same decorator under the older experimentalDecorators flag fails with TS1241, expecting the pre-ECMAScript calling convention; the fix is migrating the flag off, not the decorator. If the reverse mapping or iteration is genuinely needed, an as const object paired with a derived type, (typeof Colour)[keyof typeof Colour], keeps a real value without the unwanted mapping, though it still lacks the numeric reverse lookup.

Which source answers which question

TypeScript has no specification; an early attempt was abandoned years ago and nothing replaced it, so the compiler is the definition and every other document is commentary about what it does. See lesson 47.

When a Handbook citation and a compiler diagnostic disagree, the diagnostic wins, and the review comment should quote it rather than paraphrase the page.

Review

The method names three things rather than a reaction: what a construct costs, as a fact about the code; who pays; and what the alternative looks like. "This looks complicated" fails all three and gives the author nothing to fix. See lesson 48.

• A conditional type. Compare what the caller writes, and sees when wrong, against a plain generic doing the same job; wrong when the plainer alternative buys the same guarantee with a legible error, right only when the caller is measurably better off for having nothing left to narrow.
• An assertion. Ask what it claims, what establishes the claim, and if nothing does, what would; a defensible assertion carries a comment stating a checkable fact, and one without stands in for a check that never ran.
• An enum. Point at the mutable object with the reverse mapping it builds, the evidence lesson 46 verified in the emitted output, and ask whether the diff reads either direction of it; if not, a union of literals covers it and erases completely, and if iteration or the reverse lookup is genuinely needed, offer the as const fallback rather than repeat "avoid enum" as a slogan.
• The shorter catches. An any with no comment removes checking from everything built on it. A type predicate whose body does not test its is claim is trusted at every call site. A value crossing a boundary unparsed needs a schema check, not an assertion standing in for one. A hard-to-change published signature is lesson 43's territory: who rebuilds against it, and on what schedule.

"It compiles" is never an answer to a named cost, since every construct above compiles cleanly while doing exactly the damage described; a reply worth having names what the construct buys a caller that the alternative does not, or accepts the rewrite.

Diagnostics seen in this stage

Sources

• TypeScript Design Goals
• Handbook, Declaration Files
• TSConfig Reference
• Node, Modules, Packages
• TypeScript Release Notes
• Effective TypeScript
• TypeScript Handbook, Conditional Types