JSDoc types are unchecked, so they drift silently

[alistair3149]

Problem

The command palette's types.js is the de-facto API reference for third-party mode and provider authors, but nothing validates it. There is no tsconfig.json, no typescript dependency, and no type-check step anywhere in the skin, so the annotations are prose that happens to use type syntax.

The consequence is not hypothetical. #1772 had to correct six accumulated discrepancies, three of which documented a contract that never existed:

• isAsync and keepStaleResultsOnQueryChange on the provider interface — the real fields are debounceMs and keepStaleResults
• loadMore on the search client — no implementation anywhere
• addToken, detail.media, highlightTerm and metadata[].status shipped but undocumented

Fixing those by hand addresses the symptom. Nothing prevents the same drift recurring, and an external author has no way to tell a stale annotation from a live one.

Related: jsdoc/valid-types currently emits 47 warnings that nobody can act on. They are not caused by any one idiom — the rule also rejects typeof IntersectionObserver (7 occurrences), generics such as Ref<number>, and object-literal types like { setup: () => void }. The codebase writes TypeScript-flavoured JSDoc while the linter is configured for classic Closure-style JSDoc, so it flags valid annotations while validating nothing useful.

Prior art

Vector solves this with the same CommonJS-plus-JSDoc style we use: a tsconfig.json with allowJs, checkJs and strict, real .d.ts files, and tsc wired into npm test so type errors fail the build. It is a proven pattern in a first-party skin rather than a speculative rewrite.

Possible direction

Roughly in order of value, and each independently useful:

1. Add type checking. A tsconfig.json with checkJs plus a lint:types script, scoped initially to skins.citizen.commandPalette. This is the only step that makes drift impossible rather than fixed-for-now. Vue SFCs need vue-tsc and are the harder part, so the plain .js modules are the sensible entry point.
2. Convert types.js to a declaration file. A .d.ts is the artifact designed for this. It also drops out of packageFiles — the skin currently ships module.exports = {} to every browser for a module that, since docs(commandPalette): sync type definitions with the shipped contract #1772, nothing imports at runtime.
3. Fix or drop the jsdoc/valid-types configuration so the rule either understands the JSDoc dialect actually in use or stops reporting.

An easy way to size this before committing to it: run tsc --checkJs over the palette module and see how large the initial fix-up is.

Not urgent

Filed for the record rather than for immediate action. The types are accurate as of #1772; this is about keeping them that way.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UnWqmgRUvoSDMgbiGjichr