CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm run build      # Compile TypeScript → es6/, lib/ (CommonJS), browser/
npm test           # Prettier check + Jest (also runs build first via pretest)
npm run format     # Auto-fix formatting with Prettier

Run a single test file:

npm test -- tests/unit/parser.spec.ts

Run tests matching a pattern:

npm test -- --testNamePattern "block with tags"

Architecture

comment-parser is a zero-dependency JSDoc comment parser. It converts /** */ comment strings into structured data and back (bidirectional).

Parse pipeline

raw source string
  → source-parser   (splits into Line[] with Tokens per line)
  → block-parser    (groups lines into description block + tag sections)
  → spec-parser     (runs tokenizers on each tag section → Spec[])
  → Block[]

Each stage is independently configurable. The public parse(source, options) function wires them together.

Key data types (`src/primitives.ts`)

Block — one /** */ comment; has description, tags (Spec[]), source (Line[]), problems
Spec — one @tag; has tag, type, name, optional, default, description, source
Line — a raw source line with its tokens
Tokens — fine-grained breakdown of a line: start, delimiter, postDelimiter, tag, postTag, type, postType, name, postName, description, end, lineEnd

Module layout

Directory	Responsibility
`src/parser/`	`index.ts` (factory), `source-parser.ts`, `block-parser.ts`, `spec-parser.ts`
`src/parser/tokenizers/`	`tag.ts`, `type.ts`, `name.ts`, `description.ts` — each extracts one Tokens field
`src/stringifier/`	Converts Block/Tokens back to source string; `inspect.ts` for debugging
`src/transforms/`	Post-parse transformations: `align`, `indent`, `crlf`, composed via `flow`
`src/util.ts`	`seedBlock`, `seedTokens`, `rewireSpecs`, `rewireSource` helpers

Customization points

Tokenizers and the source-line parser are injected via options, so callers can override any parsing step. Transforms are pure functions composed with transforms.flow(...).

Build outputs

es6/ — ES modules (primary dev target, what exports["."] points to for ESM consumers)
lib/ — CommonJS (.cjs extensions, generated by convert-extension)
browser/ — IIFE bundle via Rollup

Playground

The live demo at https://syavorsky.github.io/comment-parser is hosted in a separate public repo: syavorsky/syavorsky.github.io, under the comment-parser/ directory. It is not auto-deployed from this repo — the bundled library is updated manually.

To update the playground to a new version, in the syavorsky/syavorsky.github.io repo:

cd syavorsky.github.io
./comment-parser/upgrade.sh <version>   # e.g. ./comment-parser/upgrade.sh 1.4.5

This script:

Installs the specified version of comment-parser from npm
Copies browser/index.js and tests/e2e/examples.js into comment-parser/lib/
Updates comment-parser/lib/VERSION
Updates the version label in comment-parser/index.html
Commits package.json, package-lock.json, and comment-parser/

Branching

Always work on a dedicated branch, never directly on main:

GitHub issue → issue-186/non-optional-defaults
Bug without an issue → bug/short-description
Feature without an issue → feature/short-description

Versioning & releases

PRs must include a changeset file or carry the skip-changeset label (enforced by CI).

npm run release:add is interactive and can't be automated. Instead, create the changeset file directly:

# .changeset/<random-name>.md
---
'comment-parser': patch
---

Description of the fix or change.

Use patch for bug fixes, minor for new features, major for breaking changes. The filename can be anything unique (e.g. use a random word combo).

Add the changeset file as a separate commit alongside the code changes.

Full release flow

npm run release:version   # bumps version, updates CHANGELOG, commits
npm run release:publish   # publishes to npm, pushes tags

After publishing, update the playground (see above).

CI tests against Node 20, 22, and 24.