comment-parser/CLAUDE.md

Generic JSDoc-like comment parser

# CLAUDE.md

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

## Commands

```bash
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:
```bash
npm test -- tests/unit/parser.spec.ts
```

Run tests matching a pattern:
```bash
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:

```bash
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:

```bash
# .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

```bash
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.