feat: pure-Ruby WMF/EMF/EMF+ parser — foundation + EMF MVP

[ronaldtse]

feat: pure-Ruby WMF/EMF/EMF+ parser — foundation + EMF MVP

Splitting the existing C-wrapper (emf2svg-ruby, an FFI shim around the
GPLv2 libemf2svg) into two gems:

• emf (this repo) — pure-Ruby parser. Binary → OOP domain model → binary.
• emfsvg (sibling repo, later) — transformer (model → SVG, SVG → model).

This PR lands the foundation and a working EMF MVP. WMF and EMF+ land in
follow-up TODOs tracked in TODO.impl/.

What's in this PR

Foundation (TODOs 01–06)

• Gem scaffold: emf.gemspec (BSD-2-Clause, Ruby ≥ 3.1, bindata runtime),
  Rakefile, .rspec, .rubocop.yml, bin/, exe/.
• Error hierarchy: Emf::Error / FormatError / ParseError / SerializeError.
• Bindata primitives (11): PointL, PointS, PointD, SizeL, RectL,
  RectS, ColorRef, XForm, PaletteEntry, LogPalette, FileTime —
  registered for reuse across all three formats.
• Codec helpers: UTF-16LE → UTF-8, CP1252 → UTF-8.
• Geometry value types (8): Point, PointF, PointS, Size, Rect,
  RectS, Color, Matrix — immutable, value-equal, hashable,
  from_wire / to_wire translators.
• Metafile: Enumerable container, frozen records + errors, ok? / errors?.
• Record abstract base with type_id and accept contracts.
• Visitor with register_visit — OCP-clean; subclasses override only the
  visit_* methods they need.
• Detector: APM WMF, standard WMF, EMF auto-detection.

EMF wire + parser (TODOs 09–11, 15)

• Emf::Emr::Binary::Header: full 100-byte fixed header + trailing-bytes
  capture for byte-faithful round-trip.
• Emf::Emr::Binary::Records: registry + autoload for 61 record types
  covering the most common EMR_* types (Polygon/Polyline/PolyBezier + 16
  variants, drawing primitives, state records, transforms, path control,
  Comment, EOF). Unknown types fall through to Records::Raw which
  preserves bytes verbatim.
• Emf::Emr::Parser: variable-length header read, record walk, registry
  dispatch, per-record error trapping, EMF+ payload extraction.
• Emf::Emr::Serializer: walks records, serializes each via bindata.
• Emf::Model::Emr::Header: domain value object preserving all 18 wire
  fields for round-trip.
• Emf::Model::Emr::Records::WireAdapter: interim domain wrapper around
  bindata records (TODO 10 replaces with semantic classes).
• Public API: Emf.parse / parse_file / serialize / serialize_file
  / detect_format.

Reference docs (TODO 02)

• scripts/convert_docs.rb: rubyzip + nokogiri converter, splits any
  MS Open Specifications .docx by Heading1 into GFM files.
• Generated markdown for MS-WMF, MS-EMF, MS-EMFPLUS (21 chapter files
  • INDEX.md + media/).

TODO roadmap

• TODO.impl/ with 21 self-contained TODOs + PROGRESS.md rolling up
  what's done vs what remains.

Architectural decisions

• Emf::Emr, not Emf::Emf. A namespace called Emf::Emf causes Ruby's
  constant lookup to confuse Emf::FormatError (resolved inside
  module Emf) with Emf::Emf::FormatError. Renamed to Emf::Emr,
  which mirrors the spec's EMR_* prefix.
• bindata for wire, PORO for domain. Wire records are byte-faithful
  bindata classes. Domain records are immutable value objects with
  from_wire / to_wire translators. No hand-rolled to_h / from_h.
• Registry + autoload for OCP. Adding an EMR record touches the
  record's own file plus three lines in records.rb. No central switch
  statement.
• Visitor pattern for consumers. emfsvg will provide its own visitor
  with visit_emr_* overrides.
• Errors are data, not exceptions, for per-record failures.
  Metafile#errors is an array of ParseError. Only header / magic
  failures raise.
• BSD-2-Clause. Clean-room Ruby; no GPL taint.

Constraints honored

• No require_relative and no require of internal paths in lib/ —
  everything autoloads via the parent-namespace file pattern.
• No double in specs — real instances only.
• No send to private methods, no instance_variable_set/get, no
  respond_to? for type checks.
• No AI attribution in any commit.
• All work on feat/pure-ruby-emf-parser; nothing committed to main.

Verification

• bundle exec rspec → 75 examples, 0 failures.
• bundle exec rubocop → 122 files, 0 offenses.
• bundle exec rake build → pkg/emf-0.1.0.gem.
• Byte-identical round-trip on 137/186 EMF fixtures (74%).
• All 186 EMF fixtures parse without raising.
• simple/image1.emf: 3538 records, 0 errors, byte-identical round-trip.

What's next (tracked in TODO.impl/)

TODO	Title	Priority
09	Finish remaining ~60 EMR_* wire types	P0
10	Replace WireAdapter with semantic domain classes	P0
11	2-pass path association (BEGINPATH ↔ FILLPATH/STROKEPATH)	P0
16	Round-trip harness on every non-corrupted fixture	P0
17	Corrupted-resilience spec on emf-corrupted/	P0
07, 08	WMF wire + domain + parser; source WMF fixtures	P1
12–14	EMF+ wire + domain + parser	P1
18–21	Visitors, CLI, docs, CI	P1