# Publishing Guide

> How to build, test, and publish xml-xsd-engine to npm.

---

## Prerequisites

- Node.js >= 18
- npm >= 9
- Access to the npm package (run `npm whoami`)

---

## Version Bump Workflow

1. Update `package.json` version
2. Update `CHANGELOG.md` — move `[Unreleased]` to `[x.y.z] — YYYY-MM-DD`
3. Run full test suite and coverage check
4. Build all targets
5. Publish

---

## Build

```bash
# Full build (CJS + ESM + types)
npm run build

# Individual targets
npm run build:cjs    # CommonJS
npm run build:esm    # ESM + fix .js extensions
npm run build:types  # TypeScript declarations

# Verify build output
ls dist/cjs/ dist/esm/ dist/types/
```

The ESM build runs `scripts/fix-esm-extensions.mjs` to add `.js` extensions to all imports (required for Node.js ESM compatibility).

---

## Test Before Publishing

```bash
npm test                         # all 2460 tests
npm run test:coverage            # coverage report
npm run lint                     # ESLint
```

Coverage targets: 87%+ statements, 89%+ lines.

---

## Pack and Inspect

```bash
npm pack --dry-run               # see what will be published
npm pack                         # create .tgz for inspection
tar -tzf xml-xsd-engine-*.tgz   # list contents
```

Expected package contents:
```
dist/cjs/
dist/esm/
dist/types/
src/                 (TypeScript sources for sourcemap support)
README.md
CHANGELOG.md
LICENSE
package.json
```

---

## Publish

```bash
npm publish          # publish to npm (requires OTP if 2FA enabled)
npm publish --tag next  # publish as 'next' pre-release tag
```

---

## Post-Publish

1. Create a GitHub Release with the CHANGELOG entry
2. Tag the release: `git tag v1.7.0 && git push --tags`
3. Update documentation links if needed
4. Announce in relevant channels

---

## package.json Key Fields

```json
{
  "name": "xml-xsd-engine",
  "version": "1.7.0",
  "type": "module",
  "main": "./dist/cjs/index.js",
  "module": "./dist/esm/index.js",
  "types": "./dist/types/index.d.ts",
  "sideEffects": false,
  "exports": {
    ".":         { "import": "./dist/esm/index.js", "require": "./dist/cjs/index.js", "types": "./dist/types/index.d.ts" },
    "./browser": { "import": "./dist/esm/browser.js", "types": "./dist/types/browser.d.ts" },
    "./deno":    { "import": "./dist/esm/deno.js",    "types": "./dist/types/deno.d.ts" },
    "./bun":     { "import": "./dist/esm/bun.js",     "types": "./dist/types/bun.d.ts" },
    "./async":   { "import": "./dist/esm/async.js",   "types": "./dist/types/async.d.ts" }
  }
}
```

---

## Semver Policy

| Change type | Version bump |
|-------------|-------------|
| Bug fix (no API change) | Patch (1.x.Y) |
| New export, new option with default | Minor (1.Y.0) |
| Renamed/removed export, changed behavior | Major (Y.0.0) |
| New XmlErrorCode value | Minor |
| Removed/renamed XmlErrorCode | Major |