refactor: monorepo split + honest compat layer + honest benchmarks + honest docs [Phase 0-4]

[Isqanderm]

Summary

Phases 0-4 of the om-data-mapper v5 revival: monorepo split (Phase 0-1), the compat-honesty pass (Phase 2), honest benchmarks (Phase 3), and the documentation rewrite (Phase 4).

Phase 0-1 — monorepo split

• Split into @tech-pioneer/data-mapper-core (1.0.0), @tech-pioneer/data-mapper-class-transformer (1.0.0), @tech-pioneer/data-mapper-class-validator (1.0.0), and a meta-package om-data-mapper (5.0.0) that re-exports the v4 surface (including the class-transformer-compat / class-validator-compat subpaths).
• 518-test invariant held across the split: 34 files / 518 tests passing at root, unchanged from the pre-split baseline; coverage thresholds (70/80/70/70) pass.
• Replaced semantic-release with Changesets for versioning/release.
• Rewrote CI pipelines: 764-line ci.yml → 36 lines with a Node 20/22/24 matrix; changesets release workflow; benchmark workflow stubbed pending Phase 3.
• Deleted ~7.5k lines of stale root cruft (release announcements, AI-readiness meta-docs, committed benchmark build artifacts, tracked IDE dirs).

Phase 0-1 post-review fixes (whole-branch review)

• fix: add @types/node devDependency — pnpm's isolated linker exposed that @types/node was never a direct dependency (npm hoisting masked it); CI caught it, local runs did not.
• style: format repository with prettier — the new format:check CI gate required a one-time repo-wide format (style-only, verified with a whitespace-ignoring diff).
• fix: disarm release publish path until Phase 5 — with zero changeset files, changesets/action + publish: input would have published all 4 unpublished versions to npm on merge to main. The publish: input and NPM_TOKEN env are removed until Phase 5; merging this PR cannot trigger a release.

Phase 2 — compat honesty (13 commits, TDD, per-task subagent review)

Every declared compat option now either works or is removed, with honest compat tables.

class-validator (packages/class-validator):

• The 7 previously-dead ValidatorOptions are implemented in the JIT compiler as runtime checks (sync + async codegen): whitelist (now actually strips undecorated properties — recorded in the changeset as a behavior change under the 5.0.0 major), forbidNonWhitelisted, skipMissingProperties / skipNullProperties / skipUndefinedProperties (with the upstream @IsDefined exemption), stopAtFirstError (per-property; async path enforces via post-trim in constraint declaration order), forbidUnknownValues (default false — documented divergence from upstream ≥0.14).
• Function-form message — called at runtime with ValidationArguments; explicit message wins over a validator's defaultMessage; composite constraint envelopes are unwrapped so args.constraints carries the original decorator args.
• validationError: { target, value } stripping (recursive, all return paths); fixed the wrong doc comment on ValidationError.target.
• registerDecorator (TC39 addInitializer migration pattern, documented with a working example) + getMetadataStorage (minimal facade: getTargetValidationMetadatas).
• Codegen hardening: ValidateBy names are sanitized before being interpolated as identifiers.

class-transformer (packages/class-transformer):

• enableImplicitConversion implemented: @Type(() => Number|String|Boolean|Date)-gated primitive coercion (honest limitation documented: no reflect-metadata under TC39 decorators, so @Type is required).
• Removed dead ClassTransformOptions fields: enableCircularCheck, exposeUnsetFields, targetMaps, enableValidation.

Docs & release:

• docs/compat-class-validator.md and docs/compat-class-transformer.md — per-option/per-decorator tables, every row verified against the shipped code (including the honest ❌ rows: strictGroups, dismissDefaultMessages, $property-templating, ValidationError.contexts, @Type discriminator).
• Two changesets (minor for both compat packages; meta bumps via updateInternalDependencies).

Process: 9 plan tasks executed by fresh implementer subagents with per-task spec+quality review, two fix rounds, and a final whole-branch review (verdict "with fixes" — both findings fixed and re-review-verified). Known parked residual: @Matches function messages still receive the internal {pattern, modifiers} shape in args.constraints (follow-up for Phase 4).

Phase 3 — honest benchmarks (7 commits, per-task subagent review)

The v4 benchmark suite is deleted and rebuilt from scratch as a private benchmarks workspace package:

• Deleted the fraud: fabricated RESULTS.md ("20,000–60,000% faster" rows marked "(estimated)"), the no-op validation comparison (fed class-validator metadata to om's engine, which returned [] — the timed no-op produced the headline numbers), the dead prebuilt-JS pipeline, and 4 dead devDeps (@types/benchmark, chalk, ts-node, tinybench).
• Honesty guards (the core mechanism): every comparison file asserts at import time — before anything is measured — that both engines do real work on the exact scenario fixtures (validation: both engines error on invalid / pass valid; transformation: outputs deep-equal each other and a hand-written literal, password never leaks). A guard failure throws and fails the run; the v4 no-op failure mode is structurally impossible.
• Reproducible entry points: pnpm bench / bench:core / bench:compat (build packages first, then vitest bench). Core benches measure om's decorator API vs hand-written vanilla baselines (vanilla honestly wins 3/4). Compat benches measure om vs the real class-validator / class-transformer (upstream legacy decorators applied programmatically; metadata pre-warmed on both sides).
• Un-masked CI: benchmark.yml rebuilt (setup mirrors ci.yml, frozen lockfile, 30-min timeout, no || echo, no continue-on-error) — a red bench run fails red.
• Honest docs: benchmarks/README.md contains zero performance numbers, names the v4 failure explicitly, and documents the fairness rules.

Known carry-forward to Phase 4 (recorded in the final review): fabricated v4 numbers still live in the root README.md, CHANGELOG.md, SECURITY.md and docs//docs-ru/ — the Phase 4 docs rewrite must purge them all before Phase 5 publishes anything.

Phase 4 — documentation (13 commits, per-task subagent review)

The docs now tell one honest, consistent story across English, Russian, and npm surfaces:

• Root README.md: 1,474 → 178 lines. All fabricated numbers gone (17.28x, 42.7x, the self-contradicting "vs Vanilla" table, "98% coverage"), the class-validator adapter finally has a section (v4's README never mentioned the largest module), and the only numbers left are repo-regenerable (549 tests / 38 files, zero runtime deps, ~90 validator decorators). Performance section states outright: this project publishes no benchmark numbers it cannot regenerate in CI.
• Per-package READMEs for all 4 packages (npm landing pages, absolute GitHub links, files already ships them at publish).
• docs/troubleshooting.md extracted from the README's 590-line troubleshooting section, curated to the real v5 API (one factually wrong claim about @Default ordering caught and fixed against the test suite).
• docs/migration-v4-to-v5.md — package layout, import mapping (v4 subpaths still work), and every behavior change from the Phase-2 changesets, with the whitelist-now-actually-strips breaking change called out redundantly (NestJS ValidationPipe note included).
• docs/ honesty pass — complete index (compat tables and migration guides were unlisted), stale src/… paths → real packages/… paths, non-existent @MapNested/@When examples rewritten to the real API (verified against core's tests and codegen), every fabricated "10x" table deleted, both "100% API compatible" claims qualified.
• examples/ fixed — every example imported a deleted pre-monorepo src/; now a private workspace package (benchmarks pattern) importing published names, type-checked AND executed under node. Bonus finding: the legacy Mapper.create() class API is unreachable from the published packages (export { Mapper } from './decorators' shadows export * from './core/Mapper') — examples rewritten to the decorator API, docs don't advertise the legacy class; Phase 5 must decide: fix the export or drop the legacy API.
• docs-ru/ synced — 5 missing files translated (both compat tables, both migration guides, troubleshooting), honesty fixes mirrored into the 4 existing RU guides, index rebuilt; heading-parity and byte-identical code blocks verified for all 10 file pairs.
• Final-review catch: the phase itself had described the class-transformer adapter as "JIT-compiled / built on core" — it is neither (no codegen, no core dependency; it walks TC39 decorator metadata at call time). Corrected across ~14 EN/RU locations including the npm README and package.json description.
• SECURITY.md's live fabricated figure ("112-474% faster") purged; CHANGELOG.md got an [Unreleased] pointer to the migration guide (historical 4.x entries with their old numbers left untouched as historical record).

Post-phase docs-vs-code re-audit (4 parallel verifiers: READMEs, docs/, benchmarks, docs-ru): READMEs, benchmarks (incl. a live pnpm bench:core run — all honesty guards pass, vanilla honestly wins 2/4 core scenarios), and docs-ru came back clean; docs/ had 7 defects, all fixed and re-verified against source: the dead always ValidatorOption honestly marked ❌ (stored in metadata, never read by the compiler) and validationError added to the options listing; validation-jit-internals.md codegen examples corrected to the real generated code (bracket access not optional chaining, target field present, custom-validator key is custom, Debugging section rewritten to the public API only); transformer-jit-internals.md metadata-storage claim fixed (both APIs use WeakMap, not Symbols) and the "Both APIs compile a specialized transform function once" paragraph split into the honest per-API story (all EN + RU mirrors).

Known follow-ups: CHANGELOG historical entries link three deleted docs; two RU guides retain pre-existing partially-translated prose (full re-translation is a future pass); the always option is a candidate for actual implementation in a future code change.

Out of scope (tracked in the design spec)

Phase 5 (publish, dependabot PRs, PR #21 decision). See docs/superpowers/specs/2026-08-24-monorepo-v5-design.md.

No manual prerequisite remains for Phase 5's package names — see the namespace section at the end of this description. What is still manual: npm login, and an NPM_TOKEN with publish rights for @tech-pioneer.

Test plan

• Clean-room reinstall (rm -rf node_modules + package build dirs, pnpm install --frozen-lockfile)
• pnpm run build — all 4 packages build clean
• pnpm lint — clean
• pnpm exec prettier --check . — clean
• pnpm test — 38 files / 549 tests passing (518 baseline + 31 new Phase 2 tests)
• pnpm bench — full suite runs end-to-end, all honesty guards pass
• pnpm run test:esm — 12/12 ESM smoke scenarios passing
• pnpm --filter examples run typecheck — all 9 examples type-check against the built packages (Phase 4)
• Meta-package surface check (plainToInstance, Expose, validateSync, registerDecorator, getMetadataStorage all resolve via the export * re-export)

🤖 Generated with Claude Code

https://claude.ai/code/session_01E2BunJE88yu6YcADceinHe

---

Phase 4.5 — post-review fixes (27 commits)

The whole-branch adversarial review of this PR confirmed 20 code defects that the Phase 0-4 honesty pass had missed — they were in the code, not the prose. All 20 are fixed here, plan-driven (docs/superpowers/plans/2026-08-25-review-fixes.md), one task per finding, each task independently reviewed.

Two further defects surfaced afterwards, in the test suite itself: both the property tests and the memory-leak tests were non-deterministic, and the memory tests turned out to be incapable of detecting the leaks they claimed to guard against. Both are fixed below.

Finally, with the measurement infrastructure trustworthy, the README publishes performance numbers again — this time bound by rules (see the last section).

Silent-failure bugs (class-validator)

• stopAtFirstError could drop every error. The generated async trim resolved the first failing constraint with k in propertyErrors — in walks Object.prototype, so a validator named toString/constructor matched an inherited key, deleted every real error, and the invalid payload passed validate(). Now Object.hasOwn.
• __proto__ as an error key silently passed invalid data. propertyErrors.__proto__ = msg hits the prototype setter, creates no own property, and the failing constraint looked like a passing one. sanitizeValidatorName now rejects it.
• registerDecorator silently dropped registrations. A second unnamed inline validator, a constraint class re-registered with different constraints, and — worst — two registrations differing only by options.groups all collapsed into one, so validating with the dropped group ran no check at all. The dedup predicate now compares constraints, message, always and groups, and prefers validator reference identity.
• Unbounded metadata growth. @Matches/@Validate/@ValidateBy built a fresh value object inside addInitializer, which runs on every new Dto(), so the identity-based dedup never matched and the constraints array grew without bound. One constraint object per decorator application now.
• Null-prototype inputs threw instead of returning the upstream unknownValue result.
• Metadata keyed by a module-local Symbol — two installed copies of the package validated nothing. Now Symbol.for.

Upstream-fidelity fix (class-validator)

Class-based custom validators reported errors under a hard-coded custom key, so consumers migrating from upstream read errors[0].constraints.isLongerThan and got undefined. They now report under the registered name, with upstream's precedence (@ValidatorConstraint({name}) wins over an explicit name argument — verified against class-validator 0.14.4's ValidationExecutor.getConstraintType). Behavior change, recorded in a changeset.

class-transformer

• enableImplicitConversion returned NaN for arrays. @Type(() => Number) scores!: number[] with ['1','2'] produced Number(['1','2']) = NaN; upstream yields [1, 2]. Array elements are now coerced individually.
• Three decorators were broken in ESM. @TransformClassToPlain/@TransformClassToClass/@TransformPlainToClass used a literal require('./functions') that survived into build/esm/ ("type": "module") — ReferenceError: require is not defined in ES module scope for every ESM consumer. No test invoked them, so CI stayed green. Static imports now (verified acyclic), plus the package's first ESM smoke test, which executes the built output in a real Node process.

core (JIT codegen)

Field names and @Map() paths were interpolated verbatim into new Function source. @Map('content-type') emitted source?.content-type — a SyntaxError that killed the whole mapper class at first instantiation, so kebab-case API keys were simply unusable. A quote-bearing key escaped the cache['...'] literal and executed arbitrary code inside the compiled function; the regression test proves the injection ran against the old code. Every emission site now uses JSON.stringify-escaped bracket access — including one inside _wrapInTryCatch that the original audit missed. Side effect: numeric path segments (@Map('items.0.name')) work now instead of throwing.

Packaging and honesty

• All four packages would have published without a LICENSE — every manifest declared "files": [..., "LICENSE"] and no such file existed. npm ignores missing entries silently.
• The legacy Mapper.create() API was unreachable (the decorator Mapper shadows it under ES module semantics) yet the ESM "post-install simulation" reached it through a raw node_modules path that bypasses the very exports map it claimed to validate, then printed "Package is ready for npm publication". The dead re-export is removed, the simulation now resolves everything by package name, and its summary claims only what it tests. SECURITY.md no longer presents that API under "✅ Safe Usage", and CONTRIBUTING.md's test template works again.
• Tests imported @tech-pioneer/data-mapper-class-validator/decorators, which is not in the exports map and resolved only through a vitest alias — real consumers get ERR_PACKAGE_PATH_NOT_EXPORTED.
• Six more fabricated performance figures were still living in JSDoc (42.7x, 17.28x, 112-474%, 70% smaller bundle). Purged; the completeness grep returns nothing. (Numbers do return to the README at the end of this PR — measured ones, under rules. See the last section.)
• Codegen samples in docs/transformer-jit-internals.md (both mirrors) were stale after the escaping change and are now byte-accurate, with prettier-ignore so the formatter cannot re-break them.

CI holes that let all of this ship green

• examples/ and benchmarks/ are now typechecked in CI — the exact rot class that let v4's examples decay unnoticed. benchmarks/tsconfig.json had been failing tsc --noEmit with 4 errors that nothing ran.
• packages/class-transformer gained a test:esm script; the recursive root script picks it up automatically.
• Property tests are seeded. All 25 fast-check properties drew fresh inputs every run, so a failure landed on inputs nobody could reproduce — one URL property failed once and never again in ~65 subsequent runs, including 20 under full CPU saturation. Pinned to a shared seed, with a guard test that fails if the seed is dropped. Investigated and ruled out first: the wall-clock assertions in regression.test.ts (250x headroom even with every core busy), CPU contention, concurrent vitest runs, and a gap in @IsURL itself (20,000 draws, zero rejections).

Known follow-ups from Phase 3, now resolved

The fabricated figures Phase 3 flagged as "still living in the root README, CHANGELOG, SECURITY.md and docs" are gone, and the Phase 4 question "fix the export or drop the legacy API" is answered: dropped, with a warning comment left on the class recording that its own codegen is unescaped and must be fixed before anyone re-exports it.

• The memory-leak tests measured nothing. forceGC() was if (global.gc) global.gc() and global.gc is undefined under vitest, so every "Force GC before measurement" comment described an action that never happened. Without a collection the heapUsed delta conflates retained memory with garbage V8 had not freed yet: the same operation swung from −1.48MB to +4.09MB across runs. Consequence — the suite could not detect a leak at all, and a genuine 9MB retention passed the 10MB threshold silently. --expose-gc is now supplied via the root vitest config (pool/poolOptions are root-only in Vitest and are silently ignored in a project config), forceGC() throws instead of no-opping so a missing flag fails loudly, and the thresholds drop from 10/15MB to 1MB — sized from the measured 0.09MB worst case with ~10x headroom, not guessed. Verified the guard can still fail: a deliberate retention reads as 3.99MB, which trips 1MB and would not have tripped 10MB. Also removed Math.abs from the assertions, which contradicted the comment beside it ("negative growth is good — it means GC is working") by failing the test when the heap ended smaller.

Deliberately not fixed

• The legacy BaseMapper's codegen carries the same unescaped-interpolation defect. It is unreachable from the published surface, the decorator API uses it only in type positions, and it is now marked with a warning — escaping dead code would be busywork.

Performance numbers return to the README — under rules

With the benchmark suite trustworthy (honesty guards that abort if either engine is not doing the same real work) and the test suite deterministic, the README can finally answer "is this faster?" without lying. A README that says nothing about performance is not useful to someone deciding whether to adopt the library; the v4 failure was not publishing numbers, it was publishing numbers nobody could reproduce.

The new section is bound by three rules, and benchmarks/README.md now records them for whoever publishes the next figure:

1. It names the command that regenerates it — pnpm bench:compat / pnpm bench:core.
2. It stamps the environment — CPU, OS, Node version, upstream package versions, date — and discloses that some samples carry a relative margin of error up to ±66%.
3. It publishes the losses too. Against the upstream packages om wins by 2.0x-56.2x (the margin widening on invalid data, where upstream builds error objects the generated validator does not). Against hand-written JavaScript, om loses three of four core scenarios by up to 2.3x — and the README says so, with the honest conclusion: JIT pays off against interpreting decorator metadata on every call, not against direct property access.

benchmarks/README.md had argued that numbers in documentation are always stale and were what caused the v4 failure, which the new section would have flatly contradicted. Rather than leave two documents arguing with each other, it now states the split explicitly — no figures in the benchmark package, one dated snapshot in the root README — and carries the rules above.

Test plan (Phase 4.5)

• pnpm run build — 4 packages clean
• pnpm lint and pnpm exec prettier --check . — clean
• pnpm test — 44 files / 584 tests, 10 consecutive full-suite runs with zero failures after each of the two determinism fixes
• pnpm run test:esm — all 3 packages, including class-transformer's new smoke test
• pnpm --filter examples run typecheck and pnpm --filter benchmarks run typecheck — clean
• pnpm bench — honesty guards pass (verified they can still fail: the TypeScript fix touched only the diagnostic string inside each throw)

---

Phase 4.6 — npm namespace (3 commits)

The scoped packages move to @tech-pioneer, an npm namespace that already exists, instead of the @om-data-mapper org that Phase 0-1 left as a manual prerequisite for Phase 5:

@om-data-mapper/core               ->  @tech-pioneer/data-mapper-core
@om-data-mapper/class-transformer  ->  @tech-pioneer/data-mapper-class-transformer
@om-data-mapper/class-validator    ->  @tech-pioneer/data-mapper-class-validator
om-data-mapper                     ->  unchanged (5.0.0)

The meta-package keeps its published name. om-data-mapper has version history through 4.2.1 and live installs; keeping it unscoped means existing users upgrade to v5 under the name they already depend on, and the import mapping in docs/migration-v4-to-v5.md (om-data-mapper, ./class-transformer-compat, ./class-validator-compat) stays correct as written.

Directories are deliberately not renamed — packages/core still holds @tech-pioneer/data-mapper-core. Only registry names change.

Beyond the manifests, three things had to move with them or the release would have broken:

• Changeset frontmatter. The five pending changesets name their packages in YAML that Changesets resolves against the workspace; left at the old scope, changeset version fails on unknown packages and the Phase 2 / 4.5 release notes never reach the renamed packages. changeset status now resolves all four (2 minor, 2 patch) — unchanged from before.
• The lockfile. Re-resolved via pnpm install; the clean-room --frozen-lockfile run below is what proves it matches the new manifests.
• The design spec. docs/superpowers/specs/2026-08-24-monorepo-v5-design.md carries an amendment note, the Phase 1 step no longer says to register an org, and the "npm scope" risk is marked resolved. The Phase 0-4 plans under docs/superpowers/plans/ keep the old scope — they record what was executed at the time, not what ships.

Prettier re-wrapped six markdown files whose tables and prose lines no longer fit the longer names (verified line-by-line: table alignment only, no code block touched).

Test plan (Phase 4.6)

• Clean-room: rm -rf node_modules packages/*/build + pnpm install --frozen-lockfile — lockfile matches the renamed manifests
• pnpm run build — 4 packages clean
• pnpm lint and pnpm exec prettier --check . — clean
• pnpm test — 44 files / 584 tests, identical to the pre-rename baseline
• pnpm run test:esm — all 3 packages
• pnpm --filter examples run typecheck and pnpm --filter benchmarks run typecheck — clean
• pnpm bench — full suite, all honesty guards pass
• pnpm exec changeset status — all 4 packages resolve
• grep -r "@om-data-mapper" — only docs/superpowers/plans/ (historical) and the spec's amendment note, where it is named deliberately

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[chatgpt-codex-connector]

💡 Codex Review

data-mapper/examples/ergonomic-api.ts

Line 20 in dd2cf7b

} from '../src/decorators';

Update examples to stop importing the deleted src tree

This example still imports from ../src/decorators, but this commit moved the root src tree under packages/core/src, so the documented npx tsx examples/ergonomic-api.ts flow now fails with module-not-found before users can run it. Update the examples to import from the public package/workspace entry point (or the new package source path) along with the other stale example imports found by repo-wide search.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Export the decorators subpath used by consumers

Because this package now has an exports map but only declares the root entry, any real Node/npm consumer importing the subpath used in the moved meta tests (@om-data-mapper/class-validator/decorators) will get ERR_PACKAGE_PATH_NOT_EXPORTED; the Vitest alias masks this locally by rewriting to ../class-validator/src. Add an explicit ./decorators (and any intended nested subpaths such as ./decorators/custom) export, or change those imports to the package root.

Useful? React with 👍 / 👎.