js-docs-sync

# JS Package Docs Sync Verify and update hand-written `docs/` documentation in a JS package so it stays accurate against the actual source code. These docs ship in the npm package (via the `files` field in package.json) for coding agents to read from node_modules. ## When This Matters The docs are the contract between the package and coding agents that consume it. Stale signatures, missing exports, or invalid examples mean agents write broken code. Source code is the single source of truth — docs must reflect it exactly. ## Workflow ### Step 1: Identify the Package Determine which JS package to sync. If not clear from context, check which packages have a `docs/` directory: ```bash find js/packages -maxdepth 2 -name docs -type d ``` If only one package has docs, use it. Otherwise ask the user. ### Step 2: Understand the Doc Structure Read `docs/README.md` in the target package. It contains: - A **Documentation Guide** table mapping each doc file to its topic area - An **All Exports at a Glance** section listing every public export - A **Source Code Map** showing which source files contain what This is your roadmap — it tells you what each doc file covers and where to look in the source to verify it. ### Step 3: Identify What Changed If this is triggered by source edits, focus on the changed files: ```bash git diff --name-only HEAD~1 -- js/packages/<package>/src/ ``` Map changed source files to the doc files that cover them (using the Source Code Map in README.md). You only need to re-verify the affected docs. If this is a full review (user asks to "check all docs"), verify everything. ### Step 4: Verify Each Doc File For each doc file that needs checking, compare it against the source code. Check these things in order: #### 4a. Export Completeness Read the barrel files (`src/index.ts` and any sub-module `index.ts` files) to get the full list of public exports. Compare against what's listed in `docs/README.md` under "All Exports at a Glance". Flag any export that is: - In source but missing from docs (new export, needs documenting) - In docs but not actually exported (removed or renamed, needs removing from docs) #### 4b. Function Signatures For each documented function signature, read the actual source and compare: - Parameter names and types (including generics and template literals) - Return types - Optional vs required parameters - Default values mentioned in docs vs actual defaults in source Pay special attention to: - Union types that may have changed (e.g., `| string` vs `| \`${SomeEnum}\``) - Generic type parameters (e.g., `<Fn extends AnyFn>`) - Overloaded signatures #### 4c. Type/Interface Definitions For each documented type or interface: - Verify all fields exist with correct types and optionality - Check for new fields added to the source that aren't in docs - Check for removed fields that are still in docs #### 4d. Enum Values If the docs list enum values (like span kinds), verify the list is complete against the actual enum definition. Enums grow over time — new values get added but docs often lag behind. #### 4e. Code Examples For each code example in the docs: - Verify imports reference real exported names - Verify function calls use correct parameter shapes - Check that TypeScript syntax is valid (watch for `[0.1, 0.2, ...]` — the spread operator needs an iterable; use `/* ... */` for truncated arrays) - Verify any referenced types or constants actually exist ### Step 5: Update the Source Code Map If source files were added, removed, or renamed, update the Source Code Map tree in `docs/README.md` to match the current `src/` directory structure. ### Step 6: Apply Fixes For each discrepancy found, edit the affected doc file. When updating: - Match the existing documentation style (line width, heading levels, code fence language tags) - Preserve existing prose and examples where still accurate — only change what's wrong - If a new export needs a full doc section, follow the pattern of adjacent sections in the same file (signature block, then prose, then example) - Update the "All Exports at a Glance" in README.md if exports changed ### Step 7: Verify After making changes, do a final pass: - Read each modified doc file to confirm it reads coherently - Verify the package still builds: `cd js && pnpm run -r build` - Spot-check that the README.md export list matches what the barrel files export ## Common Pitfalls **Template literal types vs plain strings**: TypeScript template literal types like `` `${SomeEnum}` `` restrict to specific string values. Don't document these as `| string` — that's misleadingly broad. Show the actual type. **Internal vs public exports**: A function may be `export`ed from its own file but not re-exported through the barrel `index.ts` chain. Only document functions that are reachable from the package's main entry point. **Type-only exports**: Exports using `export type { ... }` are erased at runtime. They should still be documented (they're part of the TypeScript API) but note that they're type-only if relevant. **Generated docs conflict**: The repo has TypeDoc-generated API docs at `js/docs/` (gitignored). The hand-written docs in `js/packages/*/docs/` are separate — don't confuse the two. Hand-written docs focus on usage patterns and examples, not exhaustive API surface.