Skip to content

docs: MapStruct parity matrix + migration guide (audit deliverables)#224

Merged
eschizoid merged 6 commits into
mainfrom
docs/mapstruct-parity-and-migration
Jul 9, 2026
Merged

docs: MapStruct parity matrix + migration guide (audit deliverables)#224
eschizoid merged 6 commits into
mainfrom
docs/mapstruct-parity-and-migration

Conversation

@eschizoid

@eschizoid eschizoid commented Jul 9, 2026

Copy link
Copy Markdown
Owner

What

The two adoption documents from the MapStruct parity audit (items 2 and 1 of the kill-MapStruct plan), plus the stale javadocs the audit surfaced.

docs/mapstruct-parity.md — the verified matrix

  • 29 MapStruct features audited: 13 ✅ full · 16 ⚠️ partial · 0 ❌ missing — no feature is unreachable; every ⚠️ states its concrete limitation.
  • Every row carries the telescope idiom (migration-recipe quality) and the file:line evidence it rests on.
  • Produced by 7 feature-group audit agents, each adversarially re-verified by a second pass that re-opened every citation — two verdicts were downgraded (records/constructor @Default, config inheritance) and two snippets corrected in that pass.

docs/mapstruct-migration.md — the migration guide

One-mapper-at-a-time recipe: coexistence setup, MapStruct→telescope translation table, introspection-based verification asserts (explain().skipped() empty + golden-input equality against the still-present MapStruct impl), and up-front gotchas.

Audit follow-ups (javadoc fixes)

  • Mapper.into claimed a missing setter throws IllegalArgumentException; the implementation (pinned by MapperIntoTest) silently skips — matching MapStruct's @MappingTarget semantics. Javadoc now tells the truth.
  • MergeStep referenced the removed Mapping.auto() factory.

Related

Test

./gradlew spotlessApply build green; MapperIntoTest green against the corrected javadoc.

@eschizoid
docs: MapStruct parity matrix + migration guide (audit deliverables)
bd75e95 
Ships the two adoption documents produced by the evidence-grounded parity
audit (7 feature-group auditors, each adversarially re-verified against the
cited source and tests):

- docs/mapstruct-parity.md — 29 MapStruct features scored 13 full / 16 partial
  / 0 missing, each with the concrete telescope idiom, honest limitations, and
  the file:line evidence the verdict rests on. Two verdicts were downgraded and
  two snippets corrected by the verification pass.
- docs/mapstruct-migration.md — the one-mapper-at-a-time migration recipe:
  coexistence setup, a MapStruct->telescope translation table, introspection-
  based verification asserts, and the up-front gotchas.

Audit follow-ups fixed in the same pass:
- Mapper.into javadoc claimed a missing setter throws IllegalArgumentException;
  the implementation (and MapperIntoTest) silently skips it, matching
  MapStruct's @MappingTarget semantics — javadoc now says so.
- MergeStep javadoc referenced the removed Mapping.auto() factory; reworded to
  the class-inference mechanism the Mapping row factories actually share.
@eschizoid eschizoid requested a review from Copilot July 9, 2026 04:16
Copilot AI reviewed Jul 9, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds the two documentation deliverables from the MapStruct parity audit (a feature-parity matrix and a migration recipe), and corrects stale/inaccurate Javadocs surfaced during the audit.

Changes:

  • Add docs/mapstruct-parity.md: evidence-backed MapStruct↔telescope parity matrix with per-row citations and limitations.
  • Add docs/mapstruct-migration.md: step-by-step “one mapper at a time” migration guide with verification assertions.
  • Update Javadocs to reflect current behavior/API references (Mapper.into setter behavior; MergeStep doc no longer references removed Mapping.auto()).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File Description
docs/mapstruct-parity.md Adds the parity matrix with citations and feature-status notes.
docs/mapstruct-migration.md Adds a practical migration guide and verification workflow.
core/src/main/java/io/github/eschizoid/telescope/mapping/MergeStep.java Fixes stale Javadoc reference to removed API.
core/src/main/java/io/github/eschizoid/telescope/conversion/Mapper.java Updates into() Javadoc to match “missing setter is skipped” semantics.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/mapstruct-parity.md Outdated
Comment thread docs/mapstruct-migration.md
Comment thread docs/mapstruct-migration.md
@codecov

codecov Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.63%. Comparing base (6f789fc) to head (68953a9).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files 
@@             Coverage Diff              @@
##               main     #224      +/-   ##
============================================
+ Coverage     79.59%   79.63%   +0.04%     
- Complexity     1841     1842       +1     
============================================
  Files            80       80              
  Lines          5783     5790       +7     
  Branches       1215     1209       -6     
============================================
+ Hits           4603     4611       +8     
- Misses          660      661       +1     
+ Partials        520      518       -2

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

@eschizoid
docs: review-fleet fixes — working anchors, rendered generics, honest…
46d20f8 
… wording

Parity matrix:
- Detail headings are now plain feature names, so every summary-table anchor
  resolves under GitHub's slugger (emoji headings produced leading-dash slugs;
  generics in headings were swallowed as HTML). Status moved into each section
  body.
- Bare generic type expressions in prose are backticked — previously rendered
  as vanished HTML tags (List<CarDto> showed as 'List').
- De-puffed three 'strictly better/safer' claims and acknowledged the
  broader-scope trade-off of pair-keyed rename rows; the tally line now says
  'no feature area is unreachable' since the collection-merge residual gap has
  no workaround.

Migration guide:
- constant/defaultValue row now names the real first-class factories
  (constant(...), toOrElse(...)) instead of a hand-rolled transform row.
- ignore=true row distinguishes source-side drop(...) from target-only fields.
- Merge example uses the bean accessor shape (CustomerDto::getCity).
- WARN row states the silent-vs-warning nuance (-Atelescope.verify=warn is the
  build-time analog), aligned with the matrix.
- Introspection links point at the README (the matrix has no introspection row)
  and the 'every row above' claim is scoped to mapping rows.
@eschizoid eschizoid requested a review from Copilot July 9, 2026 04:35
Copilot AI reviewed Jul 9, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

Comment thread core/src/main/java/io/github/eschizoid/telescope/conversion/Mapper.java
Comment thread docs/mapstruct-migration.md Outdated
Comment thread docs/mapstruct-parity.md Outdated
Comment thread docs/mapstruct-parity.md Outdated
@eschizoid
docs: Copilot round — parseable snippets, copy-pasteable import, self…
81b3b43 
…-consistent evidence

- The migration guide's side-by-side opener is now two valid java fences
  (MapStruct interface vs telescope value) instead of one unparseable mixed
  block.
- The verification snippet imports OpticNode.Mapped so it compiles as pasted.
- The @objectfactory evidence note no longer cites a repo-wide grep that this
  document itself now invalidates.
@eschizoid eschizoid requested a review from Copilot July 9, 2026 04:41
Copilot AI reviewed Jul 9, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

@eschizoid
docs: Copilot round two — consistent citations, unambiguous conversio…
6a11b3d 
…n row, harmonized into() javadoc

- Parity-matrix evidence citations now carry the full module path everywhere
  (four bare module-relative cites expanded).
- The migration table's type-conversion row states its direction (source
  String -> target LocalDate: forward parses, backward formats) so the
  function order can't be misread.
- Mapper.into's equivalence paragraph no longer contradicts the silent-skip
  setter note — 'each property ... is written' with the skip cross-reference.
@eschizoid eschizoid requested a review from Copilot July 9, 2026 11:30
Copilot AI reviewed Jul 9, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

Comment thread docs/mapstruct-parity.md
Comment thread docs/mapstruct-parity.md Outdated
Comment thread docs/mapstruct-parity.md Outdated
@eschizoid
docs: second-round fleet fixes — truthful verifier claim, typed patch…
c5facc0 
… snippet, residual contradictions

- The WARN-analog cell no longer claims -Atelescope.verify=warn warns on
  mapperForward sites (the verifier skips completeness on lenient factories);
  the real build-time-warning path is strict mapper(...) at verify=warn.
- The in-place-update snippet's patch(...) call is typed correctly
  (patch(base A, partial B) -> A; all three positions were inverted).
- MergeStep.from javadoc drops the build-time source-bag validation claim (the
  check happens at forward time via Sources.byClass).
- Mapper.into's scoping comment no longer cites an IllegalArgumentException the
  silent-skip write path can't raise.
- Merge's auto-mismatch error stops recommending a converter-taking from(...)
  overload that doesn't exist.
- Expressions snippet separates compute vs toOrElseGet on the same field (the
  fixup would stamp over the default, leaving a dead row); traceId is typed
  String consistently across snippets.
@eschizoid eschizoid requested a review from Copilot July 9, 2026 11:42
Copilot AI reviewed Jul 9, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

@eschizoid
docs: repair inline-code spans split across <-> tokens
68953a9 
The generics-backticking pass wrapped the type name up to '<' as its own span,
splitting String<->number style tokens into broken markdown. Each conversion
pair is now one clean code span.
@eschizoid eschizoid requested a review from Copilot July 9, 2026 11:47
Copilot AI reviewed Jul 9, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

@eschizoid eschizoid merged commit e0ba9e4 into main Jul 9, 2026
5 checks passed
@eschizoid eschizoid deleted the docs/mapstruct-parity-and-migration branch July 9, 2026 11:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@eschizoid