effect-api-extractor-bases
Use when API Extractor reports ae-forgotten-export for the anonymous base of an Effect class factory (Schema.Class, TaggedClass, TaggedError, Opaque, Context.Service) under the `effected package build` pipeline — and for the OTHER ae-*/tsdoc-* diagnostics a package build surfaces, ae-unresolved-link above all ({@link} selector rules for merged value+type names, overloaded functions (the parenthesized index selector), namespace-object members, inherited members, schema-declared Schema.Class fields, and cross-package symbols, where backticks are the only correct form), plus how to read issues.json without being fooled. The house policy for bases is to write the factory INLINE and suppress the synthesized X_base warning narrowly via effected.toml [package.build.meta.tsdoc] suppressWarnings (the default already carries { messageId ae-forgotten-export, pattern _base }) — no @public base const, no hand-written annotation. Yields a zero-warning issues.json with the base warnings in the suppressed bucket.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 8
- Forks
- 2
01 前言 Front Matter
- name
- effect-api-extractor-bases
- description
- Use when API Extractor reports ae-forgotten-export for the anonymous base of an Effect class factory (Schema.Class, TaggedClass, TaggedError, Opaque, Context.Service) under the `effected package build` pipeline — and for the OTHER ae-*/tsdoc-* diagnostics a package build surfaces, ae-unresolved-link above all ({@link} selector rules for merged value+type names, overloaded functions (the parenthesized index selector), namespace-object members, inherited members, schema-declared Schema.Class fields, and cross-package symbols, where backticks are the only correct form), plus how to read issues.json without being fooled. The house policy for bases is to write the factory INLINE and suppress the synthesized X_base warning narrowly via effected.toml [package.build.meta.tsdoc] suppressWarnings (the default already carries { messageId ae-forgotten-export, pattern _base }) — no @public base const, no hand-written annotation. Yields a zero-warning issues.json with the base warnings in the suppressed bucket.
03 SKILL.md 正文
API Extractor × Effect class factories
class X extends Schema.Class<X>("X")({...}) {} (and TaggedClass /
TaggedError / Opaque / Context.Service) produces an anonymous
heritage type. API Extractor reports it as ae-forgotten-export on a
synthesized X_base symbol — CI-fatal under effected package build.
The policy: inline factory + scoped _base suppression
Write the factory inline — no split-out base const, no hand-written
annotation — and suppress the synthesized-base warning narrowly. The build's
default meta.tsdoc.suppressWarnings is exactly that one rule, so a package
with no effected.toml already has it. A package that sets its own list
replaces the default and must restate the rule in its effected.toml:
[package.build.meta.tsdoc]
suppressWarnings = [{ messageId = "ae-forgotten-export", pattern = "_base" }]
// src/X.ts — inline, no base const, no annotation
/** ... @public */
export class SemVer extends Schema.Class<SemVer>("SemVer")({
major: nonNegativeInteger,
minor: nonNegativeInteger,
patch: nonNegativeInteger,
}) {
/** ... */
static readonly FromString = /* ... */;
}
That yields dist/prod/issues.json = { warnings: 0, errors: 0, suppressed: N },
with the SemVer_base (and every other *_base) entry in the suppressed
bucket.
Why this is principled, not a "silence the warning" cop-out
The emitted .d.ts proves the base is genuinely internal:
declare const SemVer_base: Schema.Class<SemVer, /* full inlined shape */>;
declare class SemVer extends SemVer_base { /* full shape: fields, statics, methods */ }
export { SemVer /* , ... */ }; // <- SemVer_base is NOT exported
X_base is a module-local declare const that never appears in the export
list, and the exported class carries its full shape. A consumer can neither
name nor need X_base. The suppression is narrow (pattern: "_base"
matches only these synthesized symbols), accounted for (it lands in the
suppressed bucket and the build log reports the count — it is logged, not
silenced), and harmless (ae-forgotten-export means "a public API names a
type a consumer can't import"; here nothing a consumer needs is lost). That is
categorically different from muting, say, an ae-missing-release-tag you don't
feel like fixing.
Validated across every factory kind
Confirmed clean (warnings: 0, the *_base in suppressed) with tsgo
green and no hand-written annotations on:
Schema.Opaque,Schema.Class,TaggedClass,TaggedError. (Naming trap: there is noSchema.asClass— zero occurrences inSchema.ts. To give a schema value a class identity you subclass it directly:class MyString extends Schema.String {}.)- Recursive
Schema.Class+Schema.suspend(a node whose field references itself): the inline form has no TS2506 and needs none of the oldSchema.Schema<Self>base-annotation gymnastics — that failure mode was an artifact of splitting the annotated base const out of the heritage clause, and it evaporates inline. The suspend callback still takes its normal(): Schema.Schema<Self> => Selfreturn type; that is ordinary recursive-schema practice, not a base annotation. Context.Service(class R extends Context.Service<R, Shape>()("id") {}): sameR_basesuppression, no annotation.- Named field-schema consts (
major: nonNegativeInteger): the const's type inlines intoX_baserather than emitting astypeof nonNegativeInteger, so it does not forgotten-export and does not need@public. The old "schema helpers referenced by the annotation become@public" cascade retires with the annotation that caused it.
So the former ceremony — the @public X_base export, the mandatory explicit
annotation, the recursive Schema.Schema<Self> special-casing, re-exporting
every base from index.ts, and marking field consts @public — is all gone.
Write the class the way Effect's own docs write it and add the one-line
suppression.
The suppression is _base-scoped ONLY — it does not cover method signatures
The binary release-tag rule still applies to method and function
parameter/return types: anything a @public signature names must itself be
@public. An internal type on a public method signature is a different
symbol (not suffixed _base), so pattern: "_base" does not suppress it —
by design, so genuine surface leaks are never masked. In the yaml port, one
internal RawDiagnostic parameter on a @public
YamlDiagnostic.fromRaw(raw: RawDiagnostic, …) produced 12
forgotten-export warnings (the whole internal/diagnostics module). These are
real and must be fixed, not suppressed:
-
Inline a structural type on the public signature so no internal symbol is named — best for engine-internal record types that should not become public surface:
static fromRaw( raw: { readonly code: YamlErrorCode; readonly message: string; readonly offset: number; readonly length: number }, text: string, ): YamlDiagnostic { … }(This is the landed form, not a hypothetical:
@effected/yaml'sYamlDiagnostic.fromRawships exactly this structural-inline signature — the 12-warningRawDiagnosticincident above is what motivated it.) -
Or tag the referenced type
@publicand re-export it — only when it is genuinely part of the API.
Prefer the structural-inline form for anything under src/internal/. Watch for
this on X.fromRaw / X.of / codec-adapter statics that bridge the internal
engine to the public classes — exactly where an internal record type sneaks
onto a @public signature.
Three escapes that look like they should work and do not. Two build cycles were burned re-discovering this, so it is worth stating outright:
| Attempted escape | Result |
|---|---|
Mark the method @internal and leave it on the @public class |
Still fails. The gate follows the class's release tag; an @internal method of a @public class is still reachable rollup surface. |
Mark the referenced type @internal |
Still fails, and differently — now you get ae-incompatible-release-tags instead. @internal never resolves an ae-forgotten-export; it only relabels the problem. |
Extract the shape to a named type alias and use that |
Still fails. An alias is a named symbol like any other, so it forgotten-exports under its own name. Naming the thing is precisely what you cannot do. |
Only two things actually work: inline the type structurally (no name exists, so nothing can be forgotten), or export it and accept it as public API. There is no third option, and the effort spent looking for one is unrecoverable.
The positive counterpart: third-party generics are free
The mirror-image fear — that naming a dependency's generic type on a @public
signature will forgotten-export it — is unfounded. API Extractor resolves
declared-dependency third-party types as externals and emits real import
statements in the .d.ts: no ae-forgotten-export, no inlining, no
re-export ceremony. Confirmed at @effected/github's first build with octokit's
Endpoints[R] on a @public signature.
The condition is that the package be a declared dependency (it must be
resolvable from the emitted .d.ts, which a devDependency or a transitive
package is not). Given that, write the precise third-party type rather than
widening to unknown or hand-copying its shape — the gate does not charge you
for it.
…nor does it cover a type in the class factory's GENERIC
The same gap bites one step earlier, in the heritage clause itself. An unexported interface passed as a type argument to the factory —
import { Context } from "effect"
interface VersionCacheShape {
readonly current: string
} // NOT exported from index.ts
export class VersionCache extends Context.Service<VersionCache, VersionCacheShape>()(
"@effected/semver/VersionCache",
) {}
— leaks as a plain ae-forgotten-export on VersionCacheShape, whose symbol
name has no _base suffix, so pattern: "_base" does not match it.
Measured on @effected/semver by un-exporting exactly that interface and
rebuilding:
| warnings | suppressed | code | ciFatal |
|
|---|---|---|---|---|
| baseline | 0 | 12 | — | — |
| interface un-exported | 1 | 12 (unchanged) | ae-forgotten-export |
true |
The symbol "VersionCacheShape" needs to be exported by the entry point index.d.ts
The suppressed bucket stayed at 12 and every entry in it ends in _base — the
narrow suppression does exactly what it says and nothing more.
The fix is to export the shape type from the entrypoint (it is genuinely part
of the API — it is the service's contract), not to widen the suppression. This is
the case a reviewer walks you into: nitting "dedupe this shape into a named
interface" is right on the merits, but the moment the name exists it must also be
exported, or the gate goes red. Applies equally to Schema.Class<Self, Fields>
and every other class factory that takes a type argument.
TSDoc {@link} traps
The one rule the cases below are instances of:
{@link}resolves only to symbols the entry point exports, under the name it exports them by. Everything else is a backtick span.
Six ways a name fails that test:
- A schema-declared
Schema.Classfield — the class owns it, but only through the factory, which API Extractor does not see through. - A module-local renamed at export —
class Routeexported asexport { Route as RestRoute }resolves as{@link RestRoute}and never as{@link Route}, no matter thatRouteis the name in the file you are writing the comment in. Confirmed twice at the@effected/githubbuild. - A member of a const-only namespace object — link through the exported
const (
{@link Walker.ascend}), never the bare member. - A module-private const — never exported, so nothing resolves; backticks.
- A re-exported cross-package
Schema.Class,{@link}ed from a file that onlyimport types it — even when the entry point re-exports the symbol (export { Package } from "@effected/package-json"), a{@link Package}written in a module that reaches it viaimport typefails with a different message than the other cases: "This type of declaration is not supported yet by the resolver", and issues.json may attribute it to an unrelated line through the rollup. Backticks are the fix. Confirmed at the@effected/sbombuild; the re-export itself is fine — only the{@link}form is rejected. - A symbol exported only from the root
.,{@link}ed from a module that ships under a second entry point (./testing,./ui,./node) — each entry point is its own API Extractor pass with its own export list (see "A second published entrypoint models its own surface" below), so the root's{@link Foo}is unresolved from./testing's pass however publicFoois at.. This is the most common way a multi-entrypoint package breaks the rule. Backticks — or, when the symbol belongs to that surface, re-export it from the second entry point too, and the link resolves there.
The diagnostic distinguishes the fixable case from the unfixable one, so read it
rather than pattern-matching: "ambiguous… add a TSDoc member reference
selector" means a selector will work (below), with one exception: a class
member whose name is declared both static and on the instance (case 4 under
"Backtick spans" below); "does not have an export" means
no selector ever will; "not supported yet by the resolver" means the resolver
cannot follow the declaration shape at all — backticks, no selector to try.
Merged value + type names: use a member-reference selector, not a backtick.
Any name carrying both a value and a type declaration — an interface plus
a const of the same name (ConfigCodec, MergeStrategy, VersionAccess), or
a branded scalar's const schema plus its exported type (PackageName,
SpdxLicense) — cannot be disambiguated by API Extractor from a bare link. Both
{@link X} and {@link X.member} resolve to ae-unresolved-link, and the
diagnostic says so literally: "the reference is ambiguous… you need to add a
TSDoc member reference selector."
The fix is the selector, and the link keeps working:
/** Wrap any {@link (ConfigCodec:interface)} with AES-GCM encryption. */
/** See {@link (ConfigResolver:variable).staticDir}. */
/** The decoded form of {@link (ConfigEventPayload:variable)}. */
/** A branded scalar: {@link (PackageName:type)}. */
Pick the selector that names the declaration you mean: :interface, :variable,
:class, :type. Getting it wrong still emits ae-unresolved-link — :type on
an interface does not resolve — so a zero-warning build is the proof you chose
correctly. @effected/yaml ({@link (YamlSegment:type)}) and
@effected/config-file ({@link (ConfigCodec:interface)}) both ship these
zero-warning.
Do not "fix" these by deleting the link. Replacing a resolvable
{@link (X:interface)} with an inert backtick span silently removes an API-doc
cross-reference; a selector form resolves for every merged name.
Member of a const-only namespace object: link through the exported name — no selector, and the bare member name never resolves. Every package entry point in this repo exports the shape
const ascend = (path: string): string => path; // module-local, NOT exported
export const Walker = { ascend } as const; // the only export
Here {@link ascend} is ae-unresolved-link — not because the name is
ambiguous, but because there is no export by that name, so no selector can
fix it ({@link (ascend:variable)} stays red). Do not pattern-match "bare link
unresolved ⇒ reach for a selector"; that heuristic belongs to the merged-name
case above, where the diagnostic says "ambiguous". When the diagnostic says
"does not have an export", the fix is a plain member reference through the
exported const — {@link Walker.ascend} — with no selector, because Walker
carries a value declaration only. packages/config-file/src/ConfigMigration.ts
({@link ConfigMigration.make}) and packages/walker/src/Walker.ts both ship
this form warnings-clean. Expect the mistake to recur: Jsonc,
ConfigResolver, ConfigMigration, ConfigCodec, MergeStrategy, and
Walker all use this export shape, and the failure is invisible to pnpm test
and types:check — it only surfaces in the prod build's issues.json.
Backtick spans remain correct for four cases, where no selector helps:
- Inherited members —
{@link SemVer.make}wheremakecomes from the synthesized base. There is no selector for a member the declaration does not own. Write`SemVer.make`. - Cross-package symbols you only
import type. A selector disambiguates between local declarations; it cannot reach a symbol API Extractor never rolled up into this package entry point. An adapter that doesimport type { ConfigCodec } from "@effected/config-file"and writes{@link (ConfigCodec:interface)}still getsae-unresolved-link. Write`ConfigCodec`. Expect this on every adapter package that plugs into a seam it does not own. - A
Schema.ClassFIELD —{@link ReleaseAgeGate.exclude}or{@link WorkspaceCatalogs.set}, where the member is a schema-declared field rather than a hand-written class member. API Extractor does not see fields declared in the factory's field object as class members at all, so no selector form fixes it —{@link (ReleaseAgeGate:class).exclude}staysae-unresolved-linktoo. Write`ReleaseAgeGate.exclude`. Note the asymmetry with the inherited-member case above — there the declaration does not own the member; here the class does own it, but only through the factory, which is the same dead end from API Extractor's side. - A class with a same-named
staticand instance member — aFn.dualstaticRange.filterbeside an instancefilter(versions).{@link Range.filter}reports "ambiguous because "filter" has more than one declaration; you need to add a TSDoc member reference selector", and then rejects every selector you can write:{@link Range.(filter:static)}and{@link Range.(filter:instance)}are both Unsupported system selector. The advice in the diagnostic is a dead end. The house answer is to not create the collision: keep the instance method canonical and drop the static (derive a data-last form from anOrderor a lambda), or give the static a distinct name.@effected/semverdropped its seven comparison statics andRange.filterfor this reason. Where a collision cannot be avoided, write the name in backticks.
Overloaded exported functions: the index selector, parenthesized
Adding a second overload to an exported function is an ordinary additive
change, and it breaks every existing {@link fn} at once with the same
"ambiguous… add a TSDoc member reference selector" diagnostic the merged-name
case emits. The selector that fixes it is not :function — it is the
overload index, 1-based in .d.ts declaration order, and the whole
reference must be parenthesized:
/** The recipe form of {@link (descend:1)}; under `"record"` see {@link (descend:2)}. */
Probed at the @effected/walker prod build (descend carries two
overload signatures plus an implementation signature), every form in one
comment so the controls and the answer share a run:
| Form | Result |
|---|---|
{@link (descend:1)}, {@link (descend:2)} |
resolve, no warning |
{@link descend} |
ambiguous… add a TSDoc member reference selector |
{@link (descend:function)} |
More than one declaration "descend" matches the TSDoc selector "function" |
{@link descend:1} |
Syntax error… the member selector must be enclosed in parentheses |
{@link (descend:3)} |
An overload for "descend" was not found that matches the TSDoc selector ":3" |
Three consequences worth holding onto:
- The system selector cannot disambiguate overloads. Every overload is a
FunctionDeclaration, so:functionmatches all of them and fails on the count — reach for the number, not the kind. - The implementation signature does not count.
:3fails on a function with two overloads and an implementation, because the index walks the rolled-up.d.ts, where only the overload signatures survive (AstReferenceResolver.#selectUsingIndexSelector→Collector.getOverloadIndex, which numbers same-kind declarations of the symbol in order, from 1). - Reordering overloads renumbers links.
:1names position, not signature, so a refactor that swaps two overloads silently repoints every link without a warning — the build stays green either way. Prefer citing the overload whose position is stable, and re-read the links when you reorder.
Backticks still work here. Where the link would carry the reader to the right overload, use the selector; where any overload will do and the position is likely to move, a backtick is the honest form.
{@link X.member} where the member name IS a TSDoc selector keyword
A member whose name collides with a TSDoc system selector (variable,
function, class, interface, namespace, enum, constructor,
static, instance, …) makes {@link ActionInput.variable} ambiguous to
the parser, and the bundler warns "identifier must be quoted". Hit live on a
static genuinely named variable. The fix is the same as
every other unresolvable-link case in this skill: backticks
(`ActionInput.variable`) — do not try quoted-selector syntax, and do
not rename the API to appease the doc engine.
tsdoc-at-sign-in-word: never markdown-link a scoped package
A scoped package name in TSDoc must be backticked. That much is known — the trap is that a markdown link hides a second, unbackticked copy inside its URL, and that copy is the one that trips:
/** See [@effected/config-file](https://npmjs.com/package/@effected/config-file). */
// ^ backticked? no — but even fixing the label leaves the URL's copy
The label being wrapped in [...] is not backticking, and the @effected inside
the parenthesized URL is bare text as far as the TSDoc parser is concerned.
Worse, the diagnostic reports at the NEXT declaration's line, so the reported
position points at an innocent symbol below the comment — the same off-by-a-
declaration behaviour as the issues.json note below, compounded.
The rule: backticks only. Never markdown-link a scoped package name in TSDoc
— not in the label, not in the URL. If the URL genuinely matters, put the bare
URL on its own ({@link https://…} or plain text) and name the package in a
backtick span beside it.
A note on reading issues.json. Its file names the source, but its line
indexes the generated .d.ts. Locate a tsdoc-* or ae-unresolved-link
defect textually, not by jumping to that line number — the position routinely
lands on a class declaration thirty lines from the offending comment, which has
sent more than one agent chasing an innocent symbol.
tsdoc-code-span-missing-delimiter: a code span must not wrap
A backtick code span must open and close on the same comment line. Prose
reflow is how this breaks: a span like
`Unsupported package manager specification` wrapped across two comment
lines reads perfectly balanced in source — each line's fragment looks fine —
but the parser sees two half-spans and emits two
tsdoc-code-span-missing-delimiter warnings in the prod gate. When wrapping
would split a span, rewrap the sentence, not the span: move the whole span to
the next line, or shorten the prose around it. (Found live in
@effected/package-json, where an error-message quotation
wrapped during an ordinary TSDoc edit.)
The warning cascades and misdirects: once a span is unterminated, the
braces inside it go raw, so a single wrapped span like
`PATCH /repos/{owner}/{repo}` fans out into tsdoc-escape-right-brace
and tsdoc-malformed-inline-tag warnings whose reported lines sit BELOW the
comment (declaration-relative reporting). Do not chase those by escaping
braces — a properly closed one-line span protects {/} fine, and
brace-bearing spans like `{ status: "enabled" }` are legal as-is. Find
the one wrapped span and rejoin it; the whole fan collapses. (Bitten twice — 14 warnings in @effected/git, 5 in @effected/github, each
one wrapped argv/route literal; a reader triaging the second incident from
the brace warnings alone diagnosed brace-escaping, which is exactly the wrong
fix.)
A bin-only package has no API model — emitDts: false, not a fake entry point
A package whose published surface is a bin and nothing else (exports
limited to "./package.json", no index.ts) fails the build under the
default config with Cannot merge zero API models. Nothing is wrong
with the package: the declaration pass ran over zero entry points and the
prod meta pass then had nothing to extract. The fix is not an index.ts
that exports nothing, and not a meta: false (which still runs the dts
pass). It is emitDts = false in the package's effected.toml:
# Bin-only: no declarations to bundle, no API model to extract.
[package.build]
emitDts = false
BuildConfigInput.emitDts is documented as the switch for "JS-only artifacts
that never consume declarations (e2e fixtures, bins, internal tools)" — it
skips the dts pass (dev and prod) and therefore the meta pass, while still
emitting JS, the byte-variant targets and the transformed package.json.
Such a package therefore carries no _base suppression, no tsdoc.json, no
api-extractor model and no website page — all of that machinery reads a
.d.ts that does not exist. It is also the one package shape a
doc-model-driven enumerator (a construct index, a docs site) must exclude by
its exports map (every key "./package.json"), or it reports the bin as a
perpetually missing build. The effect-v4-cli skill covers the package shape
itself.
A second published entrypoint models its own surface
A package.json exports map can publish more than one subpath — . and
./testing, say — and api-extractor builds and gates each entrypoint
independently, as its own closed surface. A type that one entrypoint's
public signature reaches is not automatically visible through another
entrypoint just because both ship from the same package: every kit type an
entrypoint's own exported signatures name must be re-exported from that
entrypoint too, or that entrypoint alone reports ae-forgotten-export —
"already exported from ." is never the fix for a second entrypoint's own
gate.
Worked example: @effected/workspaces/testing
(packages/workspaces/src/testing.ts). WorkspaceLayering.checkWorkspace's
requirement and error channel reach the WorkspaceDiscovery service — its
shape, options and failures. WorkspaceDiscovery is not part of the
package's main . surface at all; ./testing re-exports it anyway, because
./testing's own signatures are the ones naming it. The module's own header
comment states the rule: "This module is an ENTRY POINT: api-extractor
models it as its own surface, so every kit type its signatures name is
re-exported here."
import type { WorkspaceDiscovery, WorkspaceLayering } from "@effected/workspaces/testing"
// Both resolve from the SAME subpath: WorkspaceLayering's own signatures
// reach WorkspaceDiscovery (edgesOf's parameter, checkWorkspace's
// requirement and error channel), so this entrypoint re-exports
// WorkspaceDiscovery too rather than relying on the package's main entry
// to already have done so.
declare const service: WorkspaceDiscovery
declare const layering: typeof WorkspaceLayering
A second entrypoint that re-exports types whose TSDoc {@link}s a class only
the main entry exports fails ae-unresolved-link on the second entry's own
report: the link has nothing to resolve against there. Spell those references
in backticks instead of {@link}. packages/commands/CLAUDE.md and
packages/memfs both do this.
A subpath that names the root's types: the self-import pattern
A second entrypoint whose signatures name types the root already exports —
@effected/npm/node names NpmConfig, @effected/pnpm/settings names
PnpmSettings, PeerDependencyRules and VersioningConfig — should import
them from the package's own name rather than carry a copy. Three parts, all
required:
- Keep the self-import external in the declarations, in the package's
effected.toml:[package.build] dtsExternals = ["@effected/npm"]. The subpath's.d.tsthen refers to the root's type instead of inlining it. - Scope a suppression to that entry point only. The second API Extractor
pass resolves the self-import to the built root declarations but still
reports the root types it reaches as forgotten, so add
{ messageId = "ae-forgotten-export", pattern = 'entry point node\.d\.ts$' }(the subpath's own file name) to[package.build.meta.tsdoc] suppressWarnings. A bare pattern would hide a real leak in the root. - Pin what the suppression could hide with a built-declaration test. The
suppression is never unpinned: a declaration local to the subpath and left
unexported would be silenced, so a test reads the built
<entry>.d.tsand asserts that every top-level declaration is exported and the import specifiers are the expected ones (__test__/node-declarations.test.tsin@effected/npm,__test__/settings/declarations.test.tsin@effected/pnpm). Build before the test reads it.
Reading the gate without fooling yourself
issues.json is a false-green oracle. Four rules, each learned by being burned:
-
Build through Turbo.
pnpm build --filter <pkg>from the repo root runstypes:checkfirst and caches. A directeffected package buildin the package directory is allowed but skips that gate and the cache, so a type error the typecheck would have caught surfaces as an API Extractor failure instead. -
A crashed build can leave every bucket empty — byte-shaped exactly like a perfectly clean gate. Read
buildOkfirst:false(withfailuresaying why) or a missing stamp means the buckets are not evidence. An unexpectedsuppressedcount is a second tell: counting onlysource: "api-extractor"entries (tsdown advisory noise such asTSGO_EXPERIMENTALlands there too), a package with class factories has at least one_baseentry per factory. Never conclude "clean" from empty buckets alone;building-a-package's reading-issues reference has the full read order. -
An incremental build can hide warnings. A stale
dist/.tsbuildinfo.libfeeds API Extractor an old.d.ts, so a warning present in a cold build is absent from the incremental one. Read the gate from a cold build (rm -rfthe package'sdistfirst) whenever the answer matters. -
Concurrent agents corrupt each other's gates.
dist/has no lock: two sessions building the same package (or one runningrm -rf dist && buildwhile another reads) produce torn artifacts that read as rule 2's clean-shaped truncation — what looks like a nondeterministic bundler flake is usually contention. Treat anyissues.jsonread as suspect unless it immediately follows YOUR serial, cold, exit-0 build of that package. And neverpkill -fa shared build-tool pattern (pkill -f "effected package build"killed other sessions' legitimate builds — the actual root cause of one "flake" storm); kill your own child process by PID or not at all.
dist/ is gitignored and shared. It carries no commit, no cleanliness, and no
exit-code provenance, so it is only evidence when your build exited 0 against
a clean tree with nothing else building. If you mutate source to prove a fix is
load-bearing, rebuild afterward — otherwise you leave an artifact that
describes a tree no commit ever contained.
One cosmetic non-defect while reading built declarations: core's dollar-alias
export names surface verbatim — a Schema.Array field emits as
Schema.$Array<…>, Schema.Record as Schema.$Record<…>. Correct output,
observed across multiple package builds; do not "fix" it, and do
not read it as a wrong import in the source.
Related skills
authoring-tsdoc owns the general policy this skill assumes: the binary
release-tag rule, the supported-tag allow-list, custom tags, when a
suppression is legitimate, the typeof local forgotten export, and every
other ae-*/tsdoc-* fix. building-a-package owns effected.toml and the
build itself. The tsdoc-fixer agent carries all three and runs the fix loop
end to end.
Rejected alternatives
Two other idioms are not used: the @internal-tagged base (it leaves a
residual non-fatal ae-incompatible-release-tags) and the @public X_base
const-with-explicit-annotation idiom (the inline form + scoped _base
suppression covers the recursive and Context.Service cases it existed for).
The inline factory + scoped _base suppression is the single policy, and
the transitional backlog is drained: no package in the kit carries a
@public X_base const. grep -rln "_base" packages/*/src/ returns a single
hit — a comment in runtimes/src/NodeResolver.ts explaining why the
suppression is scoped. The suppression is the build's default, so no package needs to carry the line unless it overrides
meta.tsdoc.suppressWarnings. Find the packages that override it live:
grep -l "suppressWarnings" packages/*/effected.toml
Every package that grep prints must still list the _base rule. If you find a
@public X_base const anywhere, it is new code written against the retired
idiom, not residue: inline the factory into the heritage clause and delete
the const.
04 同仓库更多 Skills
testing-actions
Use when writing or reviewing tests for @effected/github-actions, @effected/github, @effected/sbom or @effected/commands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre/main/post lifecycle through Action.run, or debugging why a test hits the real network or hangs.
supply-chain-attestation
Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.
structuring-an-action
Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.
running-commands-and-tools
Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.
release-and-publish
Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.
hardening-a-parser-port
Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.