Uh oh!
There was an error while loading. Please reload this page.
Drop function-only paired .d.ts; JSDoc is the source of truth (phase 2) - #183
Conversation
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
commented
Jun 28, 2026
Local code-review (high effort, recall-biased) — cleanRan 8-angle finder review over the deletion diff ( This is a deletion-only change (8 function-only Lost-export / removed-behavior: none.
Conventions (CLAUDE.md): compliant. Uses Gates: |
Uh oh!
There was an error while loading. Please reload this page.
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>
Phase 2 of the paired-
.d.tscleanupPhase 1 (#182) relocated interfaces into per-directory
types.d.ts, leaving eight paired.d.tsfiles that held only function/class declarations duplicating their sibling.js. Because afoo.d.tsnext tofoo.jsshadows 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,manifestruntime/activation,runtime/loader,runtime/pathscli/dispatch,cli/core_commandsregistry/capabilitiesVerification
Emitted declarations from the JS via
tsc --emitDeclarationOnlyand 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.jscarried a loose@returnsthat droppedfromProviderfrom the public type. It now returns the namedCapabilityRegistryHandle, matching the old declaration exactly.Kept on purpose
cli/integration.d.tsstays. It backs a public package entry (package.jsonexports"./integration") whose option/result types must remain importable by name, and a.jscannot re-export types at runtime. This is the sanctioned re-export exception established in phase 1.Checks
npm run typecheck(skipLibCheck:false): greennpm run lint(423 files): greennpm test: 1473 pass / 0 fail