refactor(error): typed sub-enums in place of stringly-typed reason fields

[zrosenbauer]

Summary

Replaces reason: String on three public error variants with typed sub-enums, and wires regex::Error as a proper #[source] on SchemaError::InvalidRegex. Display output is byte-identical to the prior format.

• ParseError::MalformedTag.reason → kind: MalformedTagKind (5 variants)
• ParseError::MalformedAttribute.reason → kind: MalformedAttrKind (4 variants)
• SelectorError::Syntax.reason → kind: SyntaxKind (9 variants — distinct caps + structural Expected { what: &'static str })
• SchemaError::InvalidRegex.reason: String → #[source] source: regex::Error; SchemaError drops Eq (regex::Error is PartialEq but not Eq), retains PartialEq + Clone

Includes .changeset/typed-error-kinds.md (minor bump, breaking pre-1.0 per SemVer 4.0).

Why

Diagnostic prose buried in a String is opaque to programmatic consumers — they end up doing err.to_string().contains("…") to discriminate cases. With typed kinds, callers can match exhaustively on the failure mode. The #[source] wiring fixes the one place we were dropping a cause chain (regex::Error flattened via e.to_string()), so anyhow / eyre / tracing see the full chain.

Test plan

• cargo fmt --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test --all-features --workspace — 198 tests pass, incl. fixture_suite insta snapshots and malformed_tag_reports_useful_reason rstest (substring assertions on Display)
• pnpm run build:debug && pnpm test in bindings/node — 33 vitest tests pass (Node error.message is unchanged because Display is preserved)
• scripts/check-versions.sh — crate / npm version parity intact

Breaking?

Yes, for any consumer that constructed these variants directly or pattern-matched on the reason field. Consumers that only used matches!(e, ParseError::MalformedTag { .. }) or read Display output are unaffected.

[zrosenbauer]

Pushed 773cb8a on top — output of a multi-reviewer code audit (6 Claude agents — 3 Opus / 3 Sonnet — plus 1 Codex independent run) against Rust 1.95 / Rust API Guidelines / napi-rs v3, with every ERROR-class finding independently re-verified against the cited code before fix. One Codex finding (parser.rs:297 integer-overflow context loss) was invalidated during verification and dropped.

What landed in this commit

Public API (minor, new changeset review-fixes-2026-06.md):

• ValidationError::InvalidAttr.reason: String → kind: InvalidAttrKind. The new typed enum carries NotInEnum { allowed } and NoRegexMatch { pattern } as structured fields callers can match on. Display output is byte-identical (existing snapshots / log lines unchanged). Re-exported at the crate root. Only breaking for consumers that destructured reason.

Node binding:

• IntoNapi extension trait centralizes crate-error → napi::Error mapping. Call sites now read .into_napi()? instead of repeating .map_err(|e| Error::new(Status::InvalidArg, e.to_string())). Orphan rule blocks a direct From impl; the trait stands in.
• replace_in_content rustdoc fixed: the (?flags:…) claim was wrong about mechanism (the impl uses RegexBuilder setters). User-observable behavior unchanged.
• toJson JSDoc no longer claims "no string round-trip" — the wrapper hides one inside marxml.mjs and honesty was worth a sentence.

Internal cleanup:

• mutate::try_replace_content / try_replace_in → splice_content_report / splice_regex_report. The try_* prefix is reserved for fallible ops; these return MutationReport. Public re-exports (replace_content_report, replace_in_report) unchanged.
• Dropped the dead splice_regex one-line wrapper.

Hot-path microopts (no benchmark required):

• rewrite_open_tag and to_xml now allocate with String::with_capacity(...) sized from known byte budgets (tag + attrs / raw.len()).
• tokenizer::record_seen_attr builds the lazy HashSet via iter().map().collect().
• escape::decode_entities replaces .chars().next().expect("non-empty tail") with let-else + unreachable!.

Diagnostic bug:

• ParseError::MalformedAttribute { kind: UnterminatedValue, .. } now reports the line where input ran out, not the attribute-name line. Fixture snapshot updated (line 1 → line 2) — the new diagnostic is more accurate for multi-line attribute values.

Docs:

• Markdown::to_xml rustdoc warns the output is re-serialized, not byte-preserved; stored SourcePosition values from the parsed document don't apply.
• docs/dsl/selectors.md now describes nested :not() correctly (permitted up to depth 64; prior wording said "rejected" which contradicted the parser).
• [package.metadata.docs.rs] added to the crate manifest for future feature gates.
• New: contributing/rust-best-practices.md codifies the rubric reviewers used — Rust idiom checklist, napi-rs v3 specifics, 2024 edition deferrals, severity definitions. Companion to AGENTS.md's hard rules.

Validates clean

cargo fmt --all -- --check     ✓
cargo clippy --all-targets --all-features --workspace -- -D warnings  ✓
cargo test --all-features --workspace  ✓  (incl. 12 doc-tests)
pnpm test (bindings/node)      ✓  (33/33)

Deferred — Ask First items not in this commit

Tracked as follow-ups per the AGENTS.md "Ask First" rules:

• Compile-once Selector / Schema napi classes (Node API addition).
• Async parse / mutator variants for multi-MB inputs.
• linux-arm64-musl napi target.
• SelectorError::UnexpectedEnd { at: usize } field add.
• SerializeOpts::self_close_empty() builder rename to remove field/method shadow.
• is_name_start / is_name_char visibility decision.
• ElementRef PartialEq / Eq derives + pointer-vs-value semantic call.
• AttrConstraint accessor methods.
• Edition 2024 migration + MSRV bump to 1.85.

Full per-module review reports live at /tmp/marxml-review/A-tokenizer.md through G-codex.md (not checked in — local artifacts of the audit pass).