jsdoc-scribe

Automated, AST-based JSDoc comment generator and static documentation site builder for JavaScript & TypeScript. Fast, deterministic, and 100% local (No AI involved). No AI. No LLM. No surprises. Same input always produces the same output.

Documentation

The official documentation site is available at imchintoo.github.io/jsdoc-scribe.

Resource	Link
Website	What is jsdoc-scribe?
Quick Start	Install and generate your first docs
CLI Usage	Commands, checks, lint, and fix
GitHub Pages	Deploy generated docs
API Reference	Generated API docs
Blog	Guides and release notes

Two CLIs, one dependency (typescript >=5.0.0, used purely as a syntax parser), 234 passing tests (deterministic, zero network calls — same self-test suite runs on every npm test and before every npm publish). typescript ships as a regular dependency, not a peerDependency, because it parses every file this tool touches (.js included, not just .ts) and can't be left for a consumer to optionally provide.

Tool	What it does
gen-comments	Inserts /** */ JSDoc blocks into your source by reading the AST — no guessing
gen-docs	Builds a static, multi-page HTML documentation site from your documented source

---

Preview

Sticky topnav with centered search, white sidebar with an N-level folder tree, two-column symbol cards (prose left / dark code panel right), and a scroll-spy TOC on module pages.

Code Health dashboard (--quality)

With --quality, the index page becomes a Code Health dashboard — health score, maintainability, complexity, duplicate-code, and orphan-file stats, each linking to a full detail page — and every module page gets a compact per-file health strip. Full breakdown: Features.

---

Real-world sample code

sample/ is a real, runnable-shaped fixture set — not toy one-liners — covering the stacks teams actually ship with:

Path	Stack	What's in it
sample/express/	Express.js (TS)	app.ts, routes, a controller, a service, and auth middleware for a small task API
sample/nestjs/	NestJS (TS, decorators)	A UsersModule with @Controller/@Injectable classes, a DTO using class-validator decorators, an entity, and a guard
sample/vanilla-js/	Plain JavaScript (CommonJS, no types)	A logger, an event emitter, a retry/circuit-breaker helper, and input validators
sample/*.ts (top-level)	Generic TS	A fully-documented DI container, error hierarchy, event bus, HTTP middleware, models, and API layer — used as the "already good" reference case for --check-drift/--lint

Run any of the CLIs directly against them to see real output on real code, not a demo script:

gen-comments sample/nestjs --dry-run   # see what would be generated for decorator-heavy NestJS classes
gen-comments sample/express --check    # coverage on an undocumented Express app
gen-docs sample --out docs --title "jsdoc-scribe sample"

---

Benchmarks

Measured directly against the CLIs, single Node process, no caching between runs.

Source size	gen-comments --dry-run	gen-docs (single file)
231 LOC	1.15s · 96 MB	0.49s · 94 MB
23K LOC	1.47s · 167 MB	0.71s · 155 MB
233K LOC	4.17s · 345 MB	2.29s · 445 MB

Both CLIs scale close to linearly with source size. A real 1,000-file/70K-LOC project finishes gen-comments --write in 1.03s at 115 MB. gen-docs's multi-file scaling had a superlinear ceiling past ~300-500 files, fixed in v2.4.2 (400→1,000 files is now ~5.2x time for 2.5x files, down from an unbounded curve) — enforced continuously by npm run bench:perf-gate in CI. Full numbers and root cause: CHANGELOG; residual memory-footprint notes at very large file counts: Known limitations.

---

Install

npx jsdoc-scribe . --write            # run once, no install
npm install --save-dev jsdoc-scribe   # add to project
npm install -g jsdoc-scribe           # or install globally

---

Three ways to use jsdoc-scribe

Comments, docs, and lint are all reachable from the CLI, from inside your own Node code, or wired into CI — pick whichever fits the moment. Everything below is expanded in its own section further down; this is the map.

	Comments (gen-comments)	Docs (gen-docs)	Lint (--lint)
CLI	gen-comments src --write	gen-docs src --out docs	gen-comments src --lint / --lint --fix
Inside your codebase	require('jsdoc-scribe').processFile(file, { write: true })	require('jsdoc-scribe/docs').generateSite(['src'], opts)	require('jsdoc-scribe/lint').lintModule(moduleData)
GitHub Actions	run: npx gen-comments src --check (PR gate)	run: npx gen-docs src --out _site (Pages deploy)	run: npx gen-comments src --lint (PR gate)

1. CLI

gen-comments src --write          # insert missing JSDoc blocks in place
gen-comments src --check          # CI gate: fail if anything is undocumented
gen-comments src --check-drift    # CI gate: fail if JSDoc has drifted from the AST
gen-comments src --lint --fix     # validate JSDoc content, autofix what's safe to fix
gen-docs src --out docs --quality # build the docs site (add --quality for the Code Health dashboard)

Full flag references and walkthroughs live on the docs site: Quick Start · CLI Usage · Features.

2. Inside your codebase

Every CLI capability is also a plain function import — no child-process spawning, no parsing your own stdout. Three subpath exports, one per capability, all with hand-written TypeScript declarations (no @types/jsdoc-scribe needed):

const { processFile, analyseFile, collectFiles } = require('jsdoc-scribe');       // comments
const { generateSite, extractModule } = require('jsdoc-scribe/docs');             // docs
const { lintModule } = require('jsdoc-scribe/lint');                              // lint

Full walkthrough with real return shapes: Programmatic API.

3. GitHub Actions

Every CLI flag is a plain process exit code (0/1), so any of them drop straight into a run: step. Copy-pasteable workflows (a PR quality gate covering comments + drift + lint, plus a docs-to-Pages deploy) are documented in GitHub Actions Integration and GitHub Pages Deployment — this repo's own test.yml, docs.yml, and publish.yml (npm OIDC trusted publishing, no stored token) are the same workflows running live.

---

Highlights

• JSDoc linting without ESLint. gen-comments --lint runs the same category of checks eslint-plugin-jsdoc's recommended config does — missing tags, bad ordering, blank descriptions — with zero new dependencies. --lint --fix rewrites what's mechanically safe to fix (tag order, stray asterisks, placeholder TODO: descriptions) and never touches what it can't safely resolve (a missing block entirely, or a typo'd tag name).
• Already on ESLint? The same rules ship as a native flat-config plugin — packages/eslint-plugin-jsdoc-scribe — so findings and fixes show up in your existing eslint/eslint --fix run instead of a separate CLI invocation.
• Optional code-quality dashboard. gen-docs --quality can run code-multivitals (complexity, maintainability, duplicate-code, orphan-file detection) against the same files it documents. It's an optional peerDependency — never installed by default, and gen-docs behaves identically whether it's present or not.
• Config file support. .jsdoc-scribe.json for gen-docs output dir, title, source URL, and ignore globs — CLI flags override it. Full reference: Features.

---

Contributing

Bug reports and PRs welcome — see CONTRIBUTING.md for dev setup and guidelines (determinism is non-negotiable, no new runtime dependency without discussion first). This project follows the Code of Conduct. Found a security issue? See SECURITY.md rather than opening a public issue with exploit details.

---

Known limitations

• Inline anonymous callbacks (arr.map(x => x * 2)) aren't documented — named declarations only.
• Type inference is 100% syntactic — no evaluation, no imports, no type-checking.
• Multi-declarator statements (const a = 1, b = 2;) get one combined block.
• .d.ts files are skipped.
• gen-docs doesn't serve — use npx serve docs or deploy statically.
• gen-docs's per-page superlinear scaling past ~300-500 files (unmemoized sidebar path-prefix recomputation) is fixed as of v2.4.2 — see Benchmarks and the CHANGELOG. The parse phase (TS Compiler API per file) was profiled and confirmed not co-dominant at the file counts tested, so it stays single-threaded (worker_threads explicitly out of scope for this fix — see docs/backlog/adr-linear-scaling-fix.md).
• gen-docs holds every generated page's full HTML (including its own embedded sidebar markup) in memory until the whole site has been built, then writes it all to disk — at very large file counts (order of thousands) this is a memory-footprint concern independent of the scaling fix above. Not yet sized against real hardware; tracked in docs/backlog/task-ls-04-sidebar-node-caching.md's implementation notes.

See CHANGELOG.md for release history.

---

License

MIT © Chintan