Skip to content

Drop function-only paired .d.ts; JSDoc is the source of truth (phase 2) - #183

Merged
platypii merged 1 commit into
masterfrom
dts-phase2-drop-function-decls
Jun 28, 2026
Merged

Drop function-only paired .d.ts; JSDoc is the source of truth (phase 2)#183
platypii merged 1 commit into
masterfrom
dts-phase2-drop-function-decls

Conversation

@platypii

Copy link
Copy Markdown
Contributor

Phase 2 of the paired-.d.ts cleanup

Phase 1 (#182) relocated interfaces into per-directory types.d.ts, leaving eight paired .d.ts files that held only function/class declarations duplicating their sibling .js. Because a foo.d.ts next to foo.js shadows the JS, those declarations (not the JSDoc) were the authoritative module types.

This PR deletes the eight now-redundant declaration files so each .js's JSDoc becomes the single source of truth:

  • dep_graph, manifest
  • runtime/activation, runtime/loader, runtime/paths
  • cli/dispatch, cli/core_commands
  • registry/capabilities

Verification

Emitted declarations from the JS via tsc --emitDeclarationOnly and diffed against the deleted .d.ts. Every public signature is structurally identical: named aliases (ResolveDependenciesOptions, CreatePluginPathsArgs, ManifestLoadResult, ActivatePluginsArgs/Result) simply inline to their definitions under TypeScript's structural typing.

One real drift was found and fixed: capabilities.js carried a loose @returns that dropped fromProvider from the public type. It now returns the named CapabilityRegistryHandle, matching the old declaration exactly.

Kept on purpose

cli/integration.d.ts stays. It backs a public package entry (package.jsonexports"./integration") whose option/result types must remain importable by name, and a .js cannot re-export types at runtime. This is the sanctioned re-export exception established in phase 1.

Checks

  • npm run typecheck (skipLibCheck:false): green
  • npm run lint (423 files): green
  • npm test: 1473 pass / 0 fail

Phase 1 (#182) relocated interfaces into per-directory types.d.ts, leaving
eight paired .d.ts files holding only function/class declarations that
duplicated their sibling .js. A foo.d.ts next to foo.js shadows the JS, so
those declarations, not the JSDoc, were the authoritative module types.
Delete the eight now-redundant declaration files so each .js JSDoc becomes
the single source of truth:
dep_graph, manifest, runtime/{activation,loader,paths},
cli/{dispatch,core_commands}, registry/capabilities
Verified by emitting declarations from the JS via tsc and diffing against the
deleted .d.ts: every signature is structurally identical (named aliases like
ResolveDependenciesOptions / CreatePluginPathsArgs / ManifestLoadResult just
inline to their definitions). One real drift fixed: capabilities.js carried a
loose @returns that dropped fromProvider from the public type; it now returns
the named CapabilityRegistryHandle, matching the old declaration exactly.
cli/integration.d.ts is intentionally kept: it is a public package entry
(package.json exports "./integration") whose option/result types must stay
importable by name, and a .js cannot re-export types at runtime.
typecheck, lint (423 files), and npm test (1473 pass) all green.
@platypii

Copy link
Copy Markdown
ContributorAuthor

Local code-review (high effort, recall-biased) — clean

Ran 8-angle finder review over the deletion diff (git diff HEAD~1). 0 findings.

This is a deletion-only change (8 function-only .d.ts removed) plus one JSDoc annotation tightening in capabilities.js. The review focused on the angles that actually apply: lost exports, type drift, and conventions.

Lost-export / removed-behavior: none.

  • core_commands.js genuinely exports all 10 symbols the deleted .d.ts declared, including the runtime export { … } from re-exports (buildQuerySqlOutput, DEFAULT_QUERY_MAX_CELL/BYTES); every consumer (e.g. test/core/query-sql-output.test.js) still resolves.
  • The only type-position import from a deleted module is cli/types.d.ts doing ReturnType<typeof createKernelRuntime> — a value-function import that still resolves, and activation.js's @returns {KernelRuntime} matches the old declaration exactly.
  • The deleted files declared only functions/consts (no interface/type exports), so no named type export was dropped. Deletion actually widens the surface slightly (parseMcpArgv was previously hidden).

capabilities.js type-equivalence: the returned object implements every member of CapabilityRegistryHandle (provide/require/has/list/fromProvider/_registrations). fromProvider is part of the base CapabilityRegistry, so the surface is unchanged; the _registrations element type is structurally identical (the branded names are plain string aliases). Callers in sinks/materialize.js are unaffected.

Conventions (CLAUDE.md): compliant. Uses @import (no inline import('...')), no semicolons, no @typedef. The surviving per-directory types.d.ts still hold the interfaces; no @ref LLP annotations orphaned. The change moves toward "types defined in JSDoc, not TypeScript."

Gates:npm run typecheck (skipLibCheck:false) green · npm run lint (423 files) green · npm test 1473 pass / 0 fail.

@platypii
platypii merged commit ba3ef45 into masterJun 28, 2026
6 checks passed
@platypii
platypii deleted the dts-phase2-drop-function-decls branch June 28, 2026 22:26
philcunliffe added a commit that referenced this pull request Jul 30, 2026
Type-only trim. Each removed declaration had exactly one occurrence in
the tree (its own definition): no importer, no `@import`, no test
reference, no `@ref` annotation, and no re-export from any public entry.
- `src/core/runtime/types.d.ts`: `CreateKernelRuntimeArgs`,
`CreateActivationContextArgs`, `CreatePluginPathsArgs`,
`ActivatePluginsArgs`, `ActivatePluginsResult`. Leftovers from the
paired-.d.ts consolidation (#182/#183); `activation.js` and `paths.js`
spell these param shapes inline in JSDoc instead.
- `src/core/types.d.ts`: `ResolveDependenciesOptions`,
`ManifestLoadResult`. `manifest.js` writes
`Promise<LoadedManifest|FailedManifest>` directly; both members stay.
- `src/core/cli/types.d.ts`: `WalkthroughResult`, orphaned by "delete the
dead walkthrough" (#241).
Removing those left `PluginPaths` and `SourceWithholdResolver` as unused
type imports in `src/core/runtime/types.d.ts`; dropped both.
No runtime code changed. npm test: 3005 pass / 8 fail / 1 skipped, the
same eight `leave-command.test.js` failures present on origin/master.
npm run typecheck clean. `npm run smoke -- core_boot_noop` ok.
Co-authored-by: test <test@test.com>
Co-authored-by: Claude <noreply@anthropic.com>
Sign up for freeto 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

@platypii