Skip to content

Add Polytypo.analyze, the reported-edits entry point - #4

Merged
rogulia merged 1 commit into
mainfrom
feat/analyze
Sep 18, 2026
Merged

rogulia merged 1 commit into
mainfrom
feat/analyze

Conversation

@rogulia

@rogulia rogulia commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Ports spec 1.3.0's spec/rules/analyze.md (canonical issue polytypo/polytypo#15), after polytypo/polytypo-js#13, polytypo/polytypo-python#4 and polytypo/polytypo-go#4.

Polytypo.analyze runs the identical pipeline as .transform and reports what it would do instead of doing it. Contract A1–A5: same arguments and same error codes, pure, empty exactly when .transform returns the input unchanged, only rules enabled for the call, code-point offsets inside the input. The decomposition into records is explicitly not contract (analyze.md §4), so no fixture asserts it and the five runtimes are not required to agree on it.

Nothing in the engine changed. The whole feature is an origin map travelling beside the code-point array (lib/polytypo/engine/origin.rb).

Two details worth a look in review:

  • Change lives in the Polytypo namespace, not Polytypo::Engine, even though Engine::Origin builds it — #inspect prints the defining namespace, and that is the name a reader copies out of a console session.
  • Document offsets, not span-local ones. In html/markdown the rules run over the marker-joined span concatenation; reporting those offsets passes every text-mode test and is useless to a caller (analyze.md §6). Spans.origin_of_spans maps them back, asserted in a three-span document too.

Checks: full suite 1122 examples, 0 failures, 5 pending (the mdx skips), run locally on Ruby 3.3.8 — including spec/packaging_spec.rb, which builds and installs the gem into a clean GEM_HOME and caught origin.rb being missing from the gemspec's git ls-files manifest before it could reach CI. RuboCop was not run locally (the gem does not build on this machine); CI covers it. .transform's behaviour is untouched.

🤖 Generated with Claude Code

Implements spec 1.3.0's spec/rules/analyze.md (polytypo/polytypo@691c180,
canonical issue #15), porting polytypo-js@1a2ef57. Same pipeline as .transform,
reporting what it would do instead of doing it:

  Polytypo.analyze(%q{Wait... "really"?}, locale: "en-US")
  # => [#<data Polytypo::Change rule_id="ellipsis", start=4, end=7, before="...", after="…">, …]

Nothing in the engine changed to support it. Rules already produce edits and the
pipeline already applies them, so the whole feature is one structure: an origin
map travelling alongside the code-point array (engine/origin.rb), holding the
input offset each code point came from. A same-length replacement keeps its
origins position by position, which is what makes a converted space still point
at the space it converted.

The mode adapters are where this could quietly go wrong, and analyze.md §6 says
so: in html and markdown the rules run over the marker-joined concatenation of
spans, so reporting those offsets would pass every text-mode test and be useless
to a caller. Spans.origin_of_spans maps them back to document offsets, asserted
in a three-span document as well as a single-span one, so a doubled or dropped
marker origin cannot hide.

Change is a Data defined in the Polytypo namespace rather than in Engine: it is
public API, and #inspect prints the namespace it was defined in, which is the
one a reader will copy.

Nineteen examples, including A3 against the entire vendored fixture corpus —
empty list exactly when in == out — and analyze.md §5's French overlap at the
spec's own offsets, spaces at 3–4 and nbsp at 4–4 on `Oui : non`.

Full suite 1122 examples, 0 failures, including the packaging spec that installs
the built gem into a clean GEM_HOME — the one that catches a new lib/ file the
gemspec's git-ls-files manifest would otherwise ship without. .transform's
behaviour is untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant