Skip to content

Generate the API reference; export the types public signatures name - #51

Merged
kkdev92 merged 1 commit into
mainfrom
feat/api-reference-4.1.0
Aug 29, 2026
Merged

Generate the API reference; export the types public signatures name#51
kkdev92 merged 1 commit into
mainfrom
feat/api-reference-4.1.0

Conversation

@kkdev92

@kkdev92 kkdev92 commented Aug 29, 2026

Copy link
Copy Markdown
Owner

Summary

npm run docs:api renders every public entry point (., ./testing, ./testing/vitest, ./testing/vitest-config, ./testing/mock, ./vscode, ./std, ./ui) with TypeDoc, and CI runs it with warnings as errors.

Setting that up found what the warnings exist to find: types that public signatures name but the package never exported. A consumer who got a TreeItemLike back from a tree source, a StatusBarItemHandle from a fake, a SettingBaseOptions from setting.boolean, or a CancellationReason off an OperationCancelledError could hold the value and not be able to write its type. They are exported now — type-only, from the entry whose signatures name them. CancellationReason and OperationKind are exported as values too, since they are compared against.

ApplicationPlan and ModuleDefinition are handled differently: their members are marked @internal. Both are handles — defineExtension and createTestHost consume them — and describePlan is the readable form. Exporting fifteen registration record types would have widened the public surface without giving a consumer anything describePlan does not.

What changed

  • typedoc.json, npm run docs:api, a CI step after knip, and docs/api/ in .gitignore. npm run quality includes the step.
  • Root exports: the port vocabulary public signatures use (TreeItemLike, PlatformRegistration, ProgressReporterLike, QuickPickItemLike, QuickInputButtonLike, TreeDataSource, TreeDragAndDrop, MarkdownLike, TooltipLike, LanguageSelectorLike, LanguageFilterLike, CommandLike, CommandLinkLike, AccessibilityInformationLike, RelativePatternLike, NotificationSeverity, ProgressArea, QuickInputCapability), plus DisposableLike, SubscriptionsHost, WebviewLike, WebviewCspSourceLike, DefineExtensionOptionsWithExports, StandardSchemaResult, SettingBaseOptions (previously the unexported BaseOptions), CommandDescriptor, SchemaPathSegment, RememberedChoice, Emitter, StatusBarItemDefinition, LanguageStatusItemDefinition, CancellationReason, OperationKind.
  • ./testing exports: the port types the fakes implement or hand back (CancellationTokenLike, FileWatcherHandle, InputBoxLike, QuickPickLike, LanguageStatusItemHandle, LanguageStatusItemFields, StatusBarItemHandle, StatusBarItemFields, NotificationActionLike, LocalizedMessage, SettingsChangeSource, ActiveTextEditor, WebviewPanelSurface, WebviewViewSurface) and the host types TestHost exposes (Application, ApplicationHost, ExtensionHostContext, HostInspection, HostState, StopReason).
  • {@link} tags that pointed at internal symbols became plain code.

No runtime behaviour changes. The API reference is generated, not hosted yet; publishing it is a separate step.

Verification

  • npm run quality (now including docs:api): 1074 tests, 0 TypeDoc warnings with treatWarningsAsErrors.
  • npm run verify:package: the tarball installs and type-checks from a consumer; the CLI runs from the installed package.
  • A real extension built on this package installed the tarball with no source changes: typecheck, lint, 236 unit and 35 integration tests pass.

🤖 Generated with Claude Code

…ignatures name

`npm run docs:api` renders every public entry point with TypeDoc, and CI
runs it with warnings as errors. Setting that up found what the warnings
exist to find: types that public signatures name — the port a tree
provider returns, the surface a fake hands back, the options
`setting.boolean` takes, the reason on a cancelled operation — which the
package never exported, so a consumer could receive one and not be able
to write its type. They are exported now, from the entry whose
signatures name them. `{@link}` tags that pointed at internal symbols
became plain code.

`ApplicationPlan` and `ModuleDefinition` keep their members internal:
both are handles — `defineExtension` and `createTestHost` consume them —
and `describePlan` is the readable form.

The output lands in `docs/api/`, ignored by git; hosting it is a
separate step.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kkdev92
kkdev92 merged commit b5901cb into main Aug 29, 2026
10 checks passed
@kkdev92
kkdev92 deleted the feat/api-reference-4.1.0 branch August 29, 2026 15:36
@kkdev92 kkdev92 mentioned this pull request Aug 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant