# Migration Guide

> How to upgrade between versions of `xml-xsd-engine`.

---

## v1.7.0 → v1.7.1

### Breaking changes

None. Patch release — packaging fix only.

### Bug fix

**`sha256.js` (and other utils) missing from published npm package.**

The `files` whitelist in `package.json` only named four `utils/` files explicitly; `sha256.js`, `XmlDiff.js`, `XmlCanonical.js`, and `SchemaInference.js` were never shipped in the tarball. Any consumer that imported `xml-xsd-engine` via the ESM entry-point on Node ≥ 12 received:

```
Error: Cannot find module '.../xml-xsd-engine/dist/esm/utils/sha256.js'
```

**Fix:** Update to v1.7.1. No code changes required on your side.

---

## v1.6.x → v1.7.0

### Breaking changes

None. v1.7.0 is fully backward-compatible.

### Bug fixes that change observable behavior

| Area | Change |
|------|--------|
| `ValidationResult.valid` | Was always `true` in v1.6.0 due to `_errorCount` not being incremented. Now accurately reflects whether errors occurred. If you used `result.errors.length === 0` instead of `result.valid`, both are now equivalent. |
| `AssertionEvaluator` | xs:assert errors now emitted in deterministic order (sorted by `test` string). If you pattern-match on error messages, sort your expected arrays. |
| `XmlCanonical` inclusive C14N | Now correctly renders all in-scope namespace bindings per C14N spec §2.4. Output may differ from v1.6.0 for documents with inherited namespace scopes. |
| `XmlDiff` | False-positive "no change" no longer occurs on structurally identical but different subtrees. |

### New exports

| Symbol | Description |
|--------|-------------|
| `extractPsvi` | Convert PSVI Map to path→annotation Map |
| `SchemaMerger` | Standalone xs:import/include/redefine merge class |
| `configureXPathCache` | Tune two-tier XPath LRU at runtime |
| `xpathCacheStats` | Inspect XPath cache state |
| `xpathCacheSize` | Current compiled-expression count |
| `clearCanonicalCache` | Invalidate Canonical XML subtree memo |
| `generateJsonSchemaStream` | Streaming JSON Schema generation |
| `generateTypeScriptStream` | Streaming TypeScript generation |
| `makePsviAnnotation` | PSVI annotation factory (plugin/test use) |

### SchemaCache `maxVersionsPerKey`

New option (default `2`). In long-running servers with watch-mode, at most 2 hash-versioned
entries are kept per logical key. Increase if you need more history.

---

## v1.7.0

### Breaking changes

None. All v1.7 changes are fully backward-compatible additions.

### `PsviMap` type change

`PsviMap` changed from `WeakMap<XmlElement, PsviAnnotation>` to a `Map`-based type.
This adds `.size`, `.forEach()`, `.entries()`, `.keys()`, `.values()`.

**Migration:** Replace any `new WeakMap()` typed as `PsviMap` with `new Map()`.

```ts
// Before
const psvi: PsviMap = new WeakMap();
// After
const psvi: PsviMap = new Map();
```

### `validateOne` well-formed error handling

XML parse errors in `--well-formed` CLI mode now return a structured `ValidationResult` instead of calling `process.exit(1)` directly. This only affects code that called the internal `validateOne` function programmatically — the CLI exit code (`2`) is unchanged.

```ts
// Before (v1.7.0 initial): parse error → process.exit(1)
// After (v1.7.x): parse error → ValidationResult with well-formedness issue
const result = validateOne(xmlSrc, compiled, args);
// result.valid === false, result.issues[0].category === 'well-formedness'
```

### New exports (v1.7)

| Symbol | Description |
|--------|-------------|
| `revalidateSubtree` | Incremental subtree revalidation (G38) |
| `validateStreamingGenerator` | Async generator emitting `StreamingIssue` per issue |
| `StreamingKeyrefTracker` | Public streaming xs:key/unique/keyref tracker |
| `IValidator` | Shared interface for DOM + streaming validators (A-01 partial) |
| `flattenGroupParticles` | Utility to inline xs:group ref particles; eliminates false `__group_sequence` DFA errors |
| `CompiledSchema.compiledDfas` | Pre-compiled `DfaModel` per complex type (G27) |
| `DfaModel.particleIndex` | O(1) element-name → particle lookup map |
| `SchemaCache.get(key)` | Direct retrieval by key |
| `SchemaCache.has(key)` | Boolean presence check |
| `SchemaCacheOptions.statFast` | `fs.stat` fast-path option for `getOrLoad` |

### `SchemaCacheOptions.statFast` (opt-in)

```ts
const cache = new SchemaCache({ statFast: true });
const schema = await cache.getOrLoad('./invoice.xsd');
```

### `revalidateSubtree` usage

```ts
import { revalidateSubtree } from 'xml-xsd-engine';
const result = revalidateSubtree(modifiedElement, schema, { recover: true });
```

### `validateStreamingGenerator` usage

```ts
import { validateStreamingGenerator, compileSchema, parseXsd } from 'xml-xsd-engine';
const compiled = compileSchema(parseXsd(xsdSource));
for await (const issue of validateStreamingGenerator(xmlSource, compiled)) {
  console.error(issue.message);
}
```

---

## v1.5.x → v1.6.0

### Breaking changes

None. Backward-compatible.

### New in v1.6.0

- `diffXml` / `XmlChange` — structural XML diff
- `inferSchema` / `InferredSchema` — infer XSD from XML samples
- `validateFragment` / `validateSubtree` / `rootType` option
- `ParseOptions.encoding` — preserve encoding metadata
- Source-mapped errors: `line` and `col` on every `ValidationIssue`

---

## v1.4.x → v1.5.0

### Breaking changes

None.

### New in v1.5.0

- `IdentityConstraintEngine` — xs:key, xs:unique, xs:keyref
- `AssertionEvaluator` — xs:assert
- `validateSchema` / `checkSchema` — schema preflight
- `SaxInstrumentation` — structured SAX events
- XPath 2.0 functions (22 functions)
- `xml:id` / `xml:base` processing
- DTD internal entity expansion
- `sha256Hex` / `sha256Short`
- Platform entry points (browser, deno, bun)

---

## v1.3.x → v1.4.0

### Breaking changes

- `ValidationIssue.line` and `.col` are now always present (were previously absent on some errors).
  Code that conditionally checks for their existence continues to work.
- `ValidationOptions` extended with `mode`, `recover`, `collectAll`, `profile`, `onProfile`.
  All new fields have defaults — existing calls unaffected.

### New in v1.4.0

- `ValidationPipeline` / `runPipeline` — formal 7-stage pipeline
- `compileSchema` / `CompiledSchema` — schema compiler
- `NamespaceEngine` — standalone namespace resolver
- `xml-format` CLI command
- Strict / lax / recover validation modes
- Error recovery mode
- Profiling hooks

---

## v1.2.x → v1.3.0

### New in v1.3.0

- `generateTypeScript` / `XsdToTypeScript`
- `generateJsonSchema` / `XsdToJsonSchema`
- `parseXsdAsync` / `AsyncSchemaLoader`

---

## v1.1.x → v1.2.0

### New in v1.2.0

- `xmlToJson` / `jsonToXml` / `jsonToXmlString`
- `transformXml` / `XsltTransformer` (XSLT-lite)
- `SchemaCache` / `globalSchemaCache`
- `BatchValidator`

---

## v1.0.x → v1.1.0

Incremental improvements only. No breaking changes.

---

## Semver Policy

This project follows [Semantic Versioning 2.0.0](https://semver.org/).

- **Patch** (1.x.Y): Bug fixes only. No new exports, no behavior changes.
- **Minor** (1.Y.0): New exports, new options with safe defaults. No breaking changes.
- **Major** (Y.0.0): Breaking changes, renamed exports, removed exports.

`XmlErrorCode` values are stable across minor and patch versions. Adding a new code is a minor change. Removing or renaming a code is a major change.