Imported from echecsjs/pgn (AGENTS.md). Install upstream with npx skills add echecsjs/pgn. Copyright stays with the author.

AGENTS.md — Coding Agent Reference

This file documents conventions, commands, and guidelines for agents working in the @echecs/pgn repository.

See also: REFERENCES.md | COMPARISON.md | SPEC.md

Backlog: tracked in GitHub Issues.

Project Overview

@echecs/pgn is a PGN (Portable Game Notation) chess parser and serializer. It uses a Peggy PEG parser compiled from src/grammar.pegjs. The public API exports three functions:

• parse(input: string, options?: ParseOptions): PGN[] — parse PGN into structured objects
• stringify(input: PGN | PGN[], options?: StringifyOptions): string — serialize back to valid PGN
• stream() — deprecated, use parse() instead

Key source files:

Commands

Use pnpm exclusively (no npm/yarn).

Build

pnpm build              # compile grammar + bundle dist/ via tsdown
pnpm grammar:compile    # peggy --format commonjs -o src/grammar.cjs src/grammar.pegjs

Test

pnpm test               # grammar:compile + vitest run (all tests)

pnpm test always recompiles the grammar first — no need to do it manually.

Run a single test by fixture label:

pnpm test -- --reporter=verbose -t "basic"

Available labels: basic, benko, checkmate, comment, comments, games32, lichess, long, multiple, promotion, single, twic, variants.

Update snapshots (only after intentional output changes):

pnpm test -- --update-snapshots

Snapshots live in src/__tests__/__snapshots__/<label>.snap and are committed to git. Do not update them for pure performance changes.

Lint & Format

pnpm lint               # ESLint + tsc --noEmit
pnpm lint:ci            # same, zero warnings allowed
pnpm format             # prettier --write
pnpm format:ci          # prettier --list-different (check only)

Benchmarks

pnpm bench              # vitest bench --run (all benchmarks, takes ~60s)

Grammar Workflow

Whenever src/grammar.pegjs is modified:

1. Run pnpm test — it recompiles and runs all 13 snapshots.
2. Never edit src/grammar.cjs directly — it is generated and gitignored.
3. Grammar rule names use SCREAMING_SNAKE_CASE (Peggy convention).

Validation

Input validation is mostly provided by TypeScript's strict type system at compile time. There is no runtime validation library — the type signatures enforce correct usage. Do not add runtime type-checking guards (e.g. typeof checks, assertion functions) unless there is an explicit trust boundary. The Peggy grammar handles syntactic validation of PGN input at parse time.

Release Protocol

Step-by-step process for releasing a new version. CI auto-publishes to npm when version in package.json changes on main.

1. Verify the package is clean:

   pnpm lint && pnpm test && pnpm build

   Do not proceed if any step fails.

2. Decide the semver level:

   • patch — bug fixes, internal refactors with no API change
   • minor — new features, new exports, non-breaking additions
   • major — breaking changes to the public API

3. Update CHANGELOG.md following Keep a Changelog format:

   ## [x.y.z] - YYYY-MM-DD
   
   ### Added
   
   - …
   
   ### Changed
   
   - …
   
   ### Fixed
   
   - …
   
   ### Removed
   
   - …

   Include only sections that apply. Use past tense.

4. Update README.md if the release introduces new public API, changes usage examples, or deprecates/removes existing features.

5. Bump the version:

   npm version <major|minor|patch> --no-git-tag-version

6. Open a release PR:

   git checkout -b release/x.y.z
   git add package.json CHANGELOG.md README.md
   git commit -m "release: @echecs/pgn@x.y.z"
   git push -u origin release/x.y.z
   gh pr create --title "release: @echecs/pgn@x.y.z" --body "<description>"

   Wait for CI (format, lint, test) to pass on the PR before merging.

7. Merge the PR: Once CI is green, merge (squash) into main. The release workflow detects the version bump, publishes to npm, and creates a GitHub Release with a git tag.

Do not manually publish with npm publish. Do not create git tags manually — the release workflow handles tagging.