routie/frontend/node_modules/comment-parser/CLAUDE.md

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:

1. Installs the specified version of comment-parser from npm
2. Copies browser/index.js and tests/e2e/examples.js into comment-parser/lib/
3. Updates comment-parser/lib/VERSION
4. Updates the version label in comment-parser/index.html
5. 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.