authoring-tsdoc
Use when writing or fixing TSDoc on a package built with `effected package build`, whose API Extractor pass reports ae-* and tsdoc-* codes in dist/prod/issues.json. Covers the binary release-tag policy (@public or @internal, never a guessed @beta), fixing ae-missing-release-tag, ae-forgotten-export (including TypeScript's `typeof local` declarations and inlined dependency types), ae-incompatible-release-tags and tsdoc-* syntax, the supported-tag allow-list, registering custom tags with [package.build.meta.tsdoc] tagDefinitions, and when a suppressWarnings rule is legitimate. JSDoc habits fail this toolchain; this corrects them.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 8
- Forks
- 2
01 前言 Front Matter
- name
- authoring-tsdoc
- targets
- { "copilot": { "description": "Use when writing or fixing TSDoc on a package built with `effected package build`, whose API Extractor pass reports ae-* and tsdoc-* codes in dist/prod/issues.json: the binary @public/@internal release-tag policy, fixing ae-missing-release-tag, ae-forgotten-export and tsdoc-* syntax, the supported-tag allow-list, custom tags via tagDefinitions, and when a suppressWarnings rule is legitimate." } }
- description
- Use when writing or fixing TSDoc on a package built with `effected package build`, whose API Extractor pass reports ae-* and tsdoc-* codes in dist/prod/issues.json. Covers the binary release-tag policy (@public or @internal, never a guessed @beta), fixing ae-missing-release-tag, ae-forgotten-export (including TypeScript's `typeof local` declarations and inlined dependency types), ae-incompatible-release-tags and tsdoc-* syntax, the supported-tag allow-list, registering custom tags with [package.build.meta.tsdoc] tagDefinitions, and when a suppressWarnings rule is legitimate. JSDoc habits fail this toolchain; this corrects them.
- when_to_use
- write a TSDoc comment, document this export, JSDoc vs TSDoc, what release tag, @public or @internal, @beta, ae-missing-release-tag, ae-forgotten-export, needs to be exported by the entry point, ae-incompatible-release-tags, ae-internal-missing-underscore, ae-wrong-input-file-type, tsdoc-undefined-tag, tsdoc-param-tag-missing-hyphen, tsdoc-at-sign-in-word, tsdoc-escape-right-brace, tsdoc-malformed-inline-tag, custom TSDoc tag, @since, tagDefinitions, suppressWarnings, suppress an api-extractor warning, ciFatal, forgotten export after a TypeScript upgrade, typeof local, @packageDocumentation, @example, @remarks, @privateRemarks, fix the api extractor warnings
02 资源文件 5
- 参考文档references/custom-tags-and-suppression.md4.1 KB
- 参考文档references/diagnostics.md11.3 KB
- 参考文档references/doc-quality.md2.9 KB
- 参考文档references/release-tags.md2.8 KB
- 参考文档references/supported-tags.md3.4 KB
03 SKILL.md 正文
Authoring TSDoc for the kit build
effected package build runs Microsoft API Extractor over each export entry's declarations and reports what it finds in dist/prod/issues.json. Every extractor message is a warning, every TSDoc parser message is a warning, and ae-forgotten-export is an error under CI: locally it is a warning marked ciFatal: true. Write TSDoc, not JSDoc: the parser enforces a specific tag set and syntax, and API Extractor enforces surface rules on top.
This skill owns the general policy. Two neighbours own the rest, and the three are meant to be read together:
| Concern | Owner |
|---|---|
Release tags, the tag allow-list, custom tags, suppression policy, every ae-*/tsdoc-* fix not listed below |
this skill |
The X_base forgotten-export of Effect class factories, {@link} selector rules, the second-entrypoint surface rule |
effect-api-extractor-bases |
effected.toml keys, reading issues.json, the build itself |
building-a-package |
| Fixing a package's diagnostics end to end | the tsdoc-fixer agent |
| Construct | Reach for it when |
|---|---|
@public |
an export a consumer is meant to call, construct, extend or name |
@internal |
an export not meant for consumers and named by no @public signature: a test seam, a helper another entry imports |
@beta, @alpha |
only when a human chose to mark a surface unstable |
[package.build.meta.tsdoc] tagDefinitions |
a project tag (@since, @category) that should parse instead of raising tsdoc-undefined-tag |
[package.build.meta.tsdoc] suppressWarnings |
a human-approved false positive, scoped by messageId and a narrow pattern |
Standards
- Give every exported declaration exactly one release tag and a one-line summary. A bare
@publicwith no sentence is half a fix, for@internalas much as@public. - Apply the binary policy: consumer-facing API, and every type a
@publicsignature names, is@public; a test seam or a helper another entry imports is@internal. Stop there;@betaand@alphaare a human's call. - Tag the declaration, not the export statement. For
export { X } from "./x.js", the tag goes onXinx.ts. - Fix the cause, then rebuild to prove it. A fix is done when a fresh build has
buildOk: trueand noae-*/tsdoc-*warning or error left. - Write types in TypeScript, never in tags:
@param name - description,@returns description, no{Type}. - Put
@packageDocumentationonly in an export entry's file, once per entry:src/index.ts, andsrc/testing.tswhen./testingis an export too. - Narrate a non-entry module with
//comments, not a/** */block, which the parser reads as a doc comment. - Leave
suppressWarningsto a human. The default_baserule is the one sanctioned suppression an agent keeps; a new rule is a reviewed decision with its reason in a comment beside it.
Fix-it map
issues.json code |
Fix | Detail |
|---|---|---|
ae-missing-release-tag |
add @public or @internal, plus a summary |
release-tags.md |
ae-forgotten-export on X_base |
already suppressed by default; inline the factory | effect-api-extractor-bases |
ae-forgotten-export on a lowercase local after a TypeScript upgrade |
inline, make it a static method, or annotate the member | diagnostics.md |
ae-forgotten-export on any other symbol |
export it @public, or inline its shape structurally |
diagnostics.md |
ae-incompatible-release-tags |
make the referenced type as visible as the signature | diagnostics.md |
ae-unresolved-link |
a selector, a link through the exported name, or backticks | effect-api-extractor-bases |
ae-wrong-input-file-type |
the package's own declarations reached its source; fix the import or tsconfig | diagnostics.md |
tsdoc-undefined-tag |
fix the tag, or register it | custom-tags-and-suppression.md |
other tsdoc-* |
fix the syntax | diagnostics.md |
| "what tags may I use?" | the standard TSDoc set, all enabled | supported-tags.md |
Footguns
@internalnever clears anae-forgotten-export: on an unexported type it changes nothing, and on an exported one it becomesae-incompatible-release-tags→ diagnostics.md.- A named type alias for an internal shape forgotten-exports under its own name → diagnostics.md.
static readonly x = xdeclares astypeof xand forgotten-exports the local; never export the local to silence it → diagnostics.md.- A
suppressWarningslist you write replaces the default_baserule; restate it → custom-tags-and-suppression.md. - A
patternis a regular expression first, so.and(match more than they say → custom-tags-and-suppression.md. - A scoped package name in prose (
@effected/x) parses as a tag; backtick it, even inside a markdown link's URL → diagnostics.md. - A backtick span wrapped across two comment lines fans out into brace and inline-tag warnings below it → diagnostics.md.
@decoratoris a block tag, not a modifier → supported-tags.md.
Additional resources
- references/release-tags.md — the binary policy, its decision tree, where the tag goes, and how release tags interact with the forgotten-export gate. Load when: choosing a release tag, or clearing
ae-missing-release-tag. - references/diagnostics.md — the fix for every
ae-*andtsdoc-*code the build reports, including thetypeof localrule and inlined dependency types. Load when:issues.jsonhas anae-*ortsdoc-*entry this table does not settle. - references/supported-tags.md — every tag the build's TSDoc config enables, with its syntax kind. Load when: reaching for a tag, or reading
tsdoc-undefined-tag. - references/custom-tags-and-suppression.md —
tagDefinitionsandsuppressWarningsineffected.toml, the exact matching semantics, and the suppressions that are legitimate. Load when: registering a project tag, reviewing a suppression, or a package overrides the default list. - references/doc-quality.md — documenting the whole public surface: summaries on every member,
@remarks,@privateRemarks, compilable@exampleblocks, barrels. Load when: documenting a@publicexport beyond what the build demands. effect-api-extractor-bases— the class-factory_basepolicy, every{@link}resolution rule, overload selectors, and a second entry point's own surface. Load when: the code isae-unresolved-link, orae-forgotten-exportnames anX_baseor a type reached through a class factory or a second entry point.building-a-package—effected.toml, the build commands and theissues.jsonread order. Load when: building, or deciding whether a build passed.
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.