chore: JSDoc total coverage + strict checkJs

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.2.2] — JSDoc total coverage (2026-02-28)
+
+### Added
+- `tsconfig.checkjs.json` — strict `checkJs` configuration; `tsc --noEmit` passes with zero errors.
+- `src/types/ambient.d.ts` — ambient type declarations for `@git-stunts/plumbing` and `bun` modules.
+- `@types/node` dev dependency for typecheck support.
+- JSDoc `@typedef` types: `EncryptionMeta`, `KdfParamSet`, `DeriveKeyParams` (CryptoPort); `VaultMetadata`, `VaultState`, `VaultEncryptionMeta` (VaultService).
+
+### Changed
+- Every exported and internal function, class method, and callback across all 32 source files now has complete JSDoc `@param`/`@returns` annotations.
+- CryptoPort return types widened to `string | Promise<string>` (sha256), `Buffer | Uint8Array` (randomBytes), sync-or-async for encrypt/decrypt — accurately reflecting adapter implementations.
+- Port `@param` names corrected to match underscore-prefixed abstract parameters (fixes TS8024).
+- Observer adapter methods (`SilentObserver`, `EventEmitterObserver`, `StatsCollector`) fully typed.
+- CLI files (`bin/`) comprehensively annotated with JSDoc types for all Commander callbacks and TUI render functions.
+
 ## [5.2.1] — Carousel polish (2026-02-28)
 
 ### Added

bin/actions.js

@@ -2,6 +2,9 @@
  * CLI error handler — wraps command actions with structured error output.
  */
 
+/** @typedef {{ code?: string, message?: string }} ErrorLike */
+
+/** @type {Readonly<Record<string, string>>} */
 const HINTS = {
   MISSING_KEY: 'Provide --key-file or --vault-passphrase',
   MANIFEST_NOT_FOUND: 'Verify the tree OID contains a manifest',
@@ -19,38 +22,52 @@ const HINTS = {
 /**
  * Format and write an error to stderr.
  *
- * @param {Error} err
+ * @param {ErrorLike} err
  * @param {boolean} json - Whether to output JSON.
  */
 function writeError(err, json) {
   const message = err?.message ?? String(err);
   const code = typeof err?.code === 'string' ? err.code : undefined;
   if (json) {
+    /** @type {{ error: string, code?: string }} */
     const obj = { error: message };
     if (code) { obj.code = code; }
     process.stderr.write(`${JSON.stringify(obj)}\n`);
   } else {
     const prefix = code ? `error [${code}]: ` : 'error: ';
     process.stderr.write(`${prefix}${message}\n`);
-    const hint = code ? HINTS[code] : undefined;
+    const hint = getHint(code);
     if (hint) {
       process.stderr.write(`hint: ${hint}\n`);
     }
   }
 }
 
+/**
+ * Look up a hint for the given error code, guarding against prototype keys.
+ *
+ * @param {string | undefined} code
+ * @returns {string | undefined}
+ */
+function getHint(code) {
+  if (code && Object.prototype.hasOwnProperty.call(HINTS, code)) {
+    return HINTS[code];
+  }
+  return undefined;
+}
+
 /**
  * Wrap a command action with structured error handling.
  *
- * @param {Function} fn - The async action function.
- * @param {Function} getJson - Lazy getter for --json flag value.
- * @returns {Function} Wrapped action.
+ * @param {(...args: any[]) => Promise<void>} fn - The async action function.
+ * @param {() => boolean} getJson - Lazy getter for --json flag value.
+ * @returns {(...args: any[]) => Promise<void>} Wrapped action.
  */
 export function runAction(fn, getJson) {
-  return async (...args) => {
+  return async (/** @type {any[]} */ ...args) => {
     try {
       await fn(...args);
-    } catch (err) {
+    } catch (/** @type {any} */ err) {
       writeError(err, getJson());
       process.exitCode = 1;
     }