Imported from jonime/ts-zxcvbn (AGENTS.md). Install upstream with npx skills add jonime/ts-zxcvbn. Copyright stays with the author.

Guide for AI agents

This file helps agents work effectively on ts-zxcvbn. Follow it when implementing features, fixing bugs, or refactoring.

When you change something

1. Keep README.md in sync

• API or options: If you add or change the public API, options, or return shape, update the README “API” and “Quick start” sections.
• Scripts: New or renamed npm scripts that users or contributors might run belong in the “Development” section.
• Notable behavior: Document any behavior that affects how people use the package (e.g. new entry points, breaking changes).

2. Keep docs in sync

• VitePress docs live in docs/. Update them when behavior or API changes.
  • docs/index.md — overview, installation, quick start, optional frequency and name lists.
  • docs/api.md — API reference (parameters, return value, example).
  • docs/demo.md — demo page; update if the demo’s behavior or data changes.
  • docs/performance.md — performance comparison and benchmark; update if the benchmark script or chart data changes.
• After edits, docs:dev / docs:build / docs:preview are available for local checks.

3. Add or update tests

• Test location: src/**/*.test.ts (see vitest.config.ts).
• Coverage: New or changed behavior should have tests so regressions are caught.
• Run: npm test. Before pushing, also run npm run test:packaging (build + bundle size + ESM/CJS consumer tests).

4. Check types

• Type checking: Run npm run typecheck to ensure TypeScript compiles without errors. Do this when changing types or adding code that uses match/result types.

5. Other conventions

• Commits: Use Conventional Commits so semantic-release can version and publish correctly:
  • fix: → patch
  • feat: → minor
  • feat!: or BREAKING CHANGE: in footer → major
• CHANGELOG: Do not edit CHANGELOG.md by hand; semantic-release updates it on release.
• Formatting: The project uses Prettier (see .prettierrc); keep formatting consistent.
• Bundle size: The packaging test fails if the main bundle grows; avoid adding large dependencies or data to the default entry point. Optional data (frequency lists, name lists) use separate entry points under ./frequencies/* and ./names/*.
• Publishing: When you add files that should not be shipped to npm (e.g. tooling, dev config, docs source), update .npmignore so they are excluded from the published package.

Quick reference

Project layout (relevant to agents)

• src/ — TypeScript source and tests (*.test.ts).
• docs/ — VitePress site (index, API, demo).
• data/, data-scripts/ — raw data and scripts that generate src/frequencies/*, src/adjacency_graphs.ts, and src/names/*. Run npm run build-frequency-lists, npm run build-name-lists (and other build-* scripts) if you change data or generation.
• tests/packaging/ — ESM/CJS consumer tests and bundle size check; run via npm run test:packaging.
• benchmark/ — performance comparison script (ts-zxcvbn vs zxcvbn, zxcvbn-typescript, @zxcvbn-ts/core); run via npm run benchmark.

When in doubt: update README and docs for user-facing changes, add or adjust tests for behavior changes, then run npm run typecheck, npm test, and npm run test:packaging.