polytypo 1.0.0

data/lib/polytypo/engine/locale.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "codepoints"
+require_relative "../errors"
+
+module Polytypo
+  module Engine
+    # Locale resolution (spec/rules/locale-resolution.md) and locale data loading. Resolution is
+    # specified centrally and index-based -- no regex, no host locale, no platform
+    # locale-negotiation library (ARCHITECTURE.md sections 4.1, 4.4, 4.7). Data is embedded in the
+    # installed gem (lib/polytypo/data/), read once and memoized -- resolution itself stays a pure
+    # function of (locale, registry), never mutated after first load.
+    module Locale
+      DATA_DIR = File.join(__dir__, "..", "data")
+
+      HYPHEN = 0x2d
+      UNDERSCORE = 0x5f
+      UPPER_A = 0x41
+      UPPER_Z = 0x5a
+      LOWER_A = 0x61
+      LOWER_Z = 0x7a
+      CASE_GAP = 0x20
+
+      def self.registry
+        @registry ||= JSON.parse(File.read(File.join(DATA_DIR, "locales", "registry.json")))
+      end
+
+      def self.locale_data_raw(locale_id)
+        @locale_data_raw ||= {}
+        @locale_data_raw[locale_id] ||=
+          JSON.parse(File.read(File.join(DATA_DIR, "locales", "#{locale_id}.json")))
+      end
+
+      def self.lower_ascii?(cp)
+        cp >= LOWER_A && cp <= LOWER_Z
+      end
+      private_class_method :lower_ascii?
+
+      def self.upper_ascii?(cp)
+        cp >= UPPER_A && cp <= UPPER_Z
+      end
+      private_class_method :upper_ascii?
+
+      # spec/rules/locale-resolution.md 3.2. ASCII arithmetic only: no downcase/upcase, no ICU,
+      # no host locale, so a Turkish process resolves "EN-us" exactly as a Finnish one does
+      # (ARCHITECTURE.md 4.4).
+      def self.canonicalize(tag)
+        c = Codepoints.to_codepoints(tag).map { |cp| cp == UNDERSCORE ? HYPHEN : cp }
+        m = c.length
+        if m >= 2
+          [0, 1].each { |j| c[j] += CASE_GAP if upper_ascii?(c[j]) }
+        end
+        if m == 5 && c[2] == HYPHEN
+          [3, 4].each { |j| c[j] -= CASE_GAP if lower_ascii?(c[j]) }
+        end
+        c
+      end
+      private_class_method :canonicalize
+
+      # spec/rules/locale-resolution.md 3.3. Exactly two accepted shapes, tested by index rather
+      # than by pattern (ARCHITECTURE.md 4.1).
+      def self.accepted_shape?(c)
+        case c.length
+        when 2
+          lower_ascii?(c[0]) && lower_ascii?(c[1])
+        when 5
+          lower_ascii?(c[0]) && lower_ascii?(c[1]) && c[2] == HYPHEN &&
+            upper_ascii?(c[3]) && upper_ascii?(c[4])
+        else
+          false
+        end
+      end
+      private_class_method :accepted_shape?
+
+      # Alias values are concrete locales by registry invariant (locale-resolution.md 2). A
+      # violation is a spec-data bug, reported rather than trusted.
+      def self.alias_target(tag)
+        reg = registry
+        return nil unless reg["aliases"].key?(tag)
+
+        target = reg["aliases"][tag]
+        unless reg["locales"].include?(target)
+          raise Polytypo::Error.new(
+            Polytypo::CODE_MALFORMED_LOCALE_DATA,
+            "registry alias #{tag.inspect} points at #{target.inspect}, which is not a declared locale"
+          )
+        end
+        target
+      end
+      private_class_method :alias_target
+
+      # Exact match before alias, so a registry that wrongly lists a tag in both cannot make
+      # lookup order observable (locale-resolution.md 3.4).
+      def self.lookup(tag)
+        return tag if registry["locales"].include?(tag)
+
+        alias_target(tag)
+      end
+      private_class_method :lookup
+
+      # Exact match, then the registry alias table, then the language subtag alone once with no
+      # chain. Never a platform locale negotiator (ARCHITECTURE.md 4.7). An empty or malformed tag
+      # has no accepted shape and falls through to the same unknown-locale error as any other
+      # unresolvable tag.
+      def self.resolve(tag)
+        unless tag.is_a?(String) && !tag.empty?
+          raise Polytypo::Error.new(
+            Polytypo::CODE_UNKNOWN_LOCALE,
+            "the locale option is required and must be a non-empty string; received #{tag.inspect}"
+          )
+        end
+
+        c = canonicalize(tag)
+        if accepted_shape?(c)
+          canonical = Codepoints.from_codepoints(c)
+          direct = lookup(canonical)
+          return direct unless direct.nil?
+
+          if c.length == 5
+            base = Codepoints.from_codepoints(c[0, 2])
+            resolved = lookup(base)
+            return resolved unless resolved.nil?
+          end
+        end
+
+        raise Polytypo::Error.new(
+          Polytypo::CODE_UNKNOWN_LOCALE,
+          "unknown locale #{tag.inspect}. Known locales: #{registry["locales"].join(", ")}."
+        )
+      end
+
+      def self.locale_data(tag)
+        locale_data_raw(resolve(tag))
+      end
+    end
+  end
+end

data/lib/polytypo/engine/pipeline.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "edits"
+require_relative "locale"
+require_relative "registry"
+require_relative "../errors"
+
+module Polytypo
+  module Engine
+    # Per-call context every rule reads, alongside the code-point array and the locale data.
+    RuleContext = Struct.new(:mode, :dialect, :locale, keyword_init: true)
+
+    # Resolves the locale, builds the rule plan, and runs each enabled rule in
+    # spec/rules/order.json order over a code-point array, applying its edits before the next
+    # rule sees it. No module-level mutable state beyond the immutable, load-once-on-first-use
+    # spec data in Registry/Locale (ARCHITECTURE.md section 7).
+    module Pipeline
+      # Defaults + opt-out overrides. rules_option is opt-out only (ARCHITECTURE.md section 7):
+      # it may only disable a default-on rule or enable the one default-off rule ("ranges"). An
+      # unknown key raises POLYTYPO_UNKNOWN_RULE.
+      def self.resolve_rule_plan(rules_option)
+        defaults = Registry.rule_defaults
+        enabled = defaults.dup
+        (rules_option || {}).each do |rule_id, flag|
+          unless defaults.key?(rule_id)
+            raise Polytypo::Error.new(Polytypo::CODE_UNKNOWN_RULE, "unknown rule id: #{rule_id.inspect}")
+          end
+
+          enabled[rule_id] = flag ? true : false
+        end
+        Registry.rule_order.select { |id| enabled[id] }
+      end
+
+      # Builds the rule plan, then resolves the locale and loads its data -- the setup step
+      # shared by the text pipeline and the span-runner (html/markdown modes). Order matters and
+      # is public, tested behaviour: an unknown-rule error must win over an unknown-locale error
+      # when both are present (mirrors every other port exactly).
+      def self.prepare(locale, rules_option)
+        plan = resolve_rule_plan(rules_option)
+        resolved_locale = Locale.resolve(locale)
+        locale_data = Locale.locale_data_raw(resolved_locale)
+        [resolved_locale, locale_data, plan]
+      end
+
+      # Runs each enabled rule in order.json order over cp, applying its edits before the next
+      # rule sees the array. Shared by text mode and the span-runner (modes.md 3.5), which
+      # interposes the two boundary filters of modes.md 3.4 between rule and apply.
+      def self.run_rules(cp, plan, locale_data, ctx)
+        current = cp
+        plan.each do |rule_id|
+          fn = Registry.rule(rule_id)
+          edits = fn.call(current, locale_data, ctx)
+          next if edits.empty?
+
+          current = Edits.apply_edits(current, edits, rule_id)
+        end
+        current
+      end
+    end
+  end
+end

data/lib/polytypo/engine/registry.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Polytypo
+  module Engine
+    # Rule order and defaults, derived from lib/polytypo/data/rules/order.json at load time --
+    # never hand-duplicated (ARCHITECTURE.md section 4.5: order.json is the single source of
+    # truth, never registration order, never Hash-iteration order).
+    module Registry
+      DATA_DIR = File.join(__dir__, "..", "data")
+
+      def self.order_data
+        @order_data ||= JSON.parse(File.read(File.join(DATA_DIR, "rules", "order.json")))
+      end
+      private_class_method :order_data
+
+      # Rule ids in ascending pipeline order.
+      def self.rule_order
+        @rule_order ||= order_data["rules"].sort_by { |r| r["order"] }.map { |r| r["id"] }
+      end
+
+      # Rule id -> default enabled/disabled (only "ranges" defaults to false). order.json's
+      # "default" field is the string "on"/"off", not a JSON boolean.
+      def self.rule_defaults
+        @rule_defaults ||= order_data["rules"].to_h { |r| [r["id"], r["default"] == "on"] }
+      end
+
+      @rules = {}
+
+      # Adds a rule implementation to the registry. Called from each rule file's own load,
+      # mirroring the other ports' static-registration pattern -- requiring the rules directory
+      # is enough, with no separate caller-side step.
+      def self.register(rule_id, callable)
+        @rules[rule_id] = callable
+      end
+
+      def self.rule(rule_id)
+        @rules.fetch(rule_id)
+      end
+
+      def self.known_rule_ids
+        rule_defaults.keys
+      end
+    end
+  end
+end

data/lib/polytypo/engine/rules/apostrophe.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "quote_ambiguity"
+require_relative "../sentinels"
+require_relative "../unicode_util"
+require_relative "../edits"
+require_relative "../registry"
+
+module Polytypo
+  module Engine
+    module Rules
+      # spec/rules/apostrophe.md (spec 0.5.0), order 50.
+      #
+      # Converts a straight U+0027 to U+2019 where it is genuinely an apostrophe: a contraction,
+      # an elision, a possessive, or a decade elision. Runs immediately after `quotes` (order 40)
+      # and sees only the U+0027 marks quotes declined to claim. Every edit is one code point
+      # replacing one code point; the rule never inserts, never deletes, and never touches U+2019
+      # itself.
+      #
+      # As of spec 0.5.0 this rule additionally skips a small, precisely-defined set of positions
+      # entirely (apostrophe.md 3.4) -- the shared ambiguous-medial-span preserve set,
+      # QuoteAmbiguity.compute_preserve_indices -- rather than applying its case ladder to them.
+      module Apostrophe
+        SQ = 0x27
+        RIGHT_SINGLE = 0x2019
+
+        # OPENISH is apostrophe.md 3.1 OPENISH. Unlike quotes.md's OPENISH, this is not "every
+        # QUOTEMARK" -- only the specific opening-shaped glyphs the spec lists. Engine::MARKER is
+        # a member (modes.md 3.3's table names this rule explicitly).
+        OPENISH = [
+          Engine::MARKER,
+          0x28, 0x5B, 0x7B, 0xAB,
+          0x2018, 0x201A, 0x201B, 0x201C, 0x201E, 0x201F, 0x2039,
+          0x2D, 0x2011, 0x2013, 0x2014
+        ].freeze
+
+        # CLOSEISH is apostrophe.md 3.1 CLOSEISH. U+2019 is a member and U+0027 is a member of
+        # neither this nor OPENISH -- apostrophe.md 5 turns exactly that asymmetry into the
+        # idempotency argument. U+2011 sits beside U+002D because `hyphen` (order 35) converts one
+        # to the other.
+        CLOSEISH = [
+          Engine::MARKER,
+          0x29, 0x5D, 0x7D, 0xBB,
+          0x2019, 0x201D, 0x203A,
+          0x2C, 0x2E, 0x3B, 0x3A, 0x21, 0x3F, 0x2026,
+          0x2D, 0x2011, 0x2013, 0x2014
+        ].freeze
+
+        BREAK = [0x0A, 0x0D, 0x0B, 0x0C, 0x85, 0x2028, 0x2029, Engine::LINE_MARKER].freeze
+
+        # SPACELIKE, including Engine::LINE_MARKER as a member of BREAK for every rule everywhere
+        # (modes.md 3.2).
+        def self.spacelike?(cp)
+          QuoteAmbiguity.inline_space?(cp) || BREAK.include?(cp)
+        end
+
+        def self.digit?(cp)
+          cp >= 0x30 && cp <= 0x39
+        end
+
+        def self.alnum?(cp)
+          digit?(cp) || UnicodeUtil.letter?(cp)
+        end
+
+        # apostrophe? is the case ladder of apostrophe.md 3.3, first match wins. Every verdict
+        # is a pure function of exactly two neighbouring code points; there is no lookahead and no
+        # state carried between candidates.
+        def self.apostrophe?(left, right)
+          # Case 1 -- prime guard, first so it wins over case 3: `6' 2"`, `55° 40' N`, `6'2"`. A
+          # foot mark is not an apostrophe.
+          return false if digit?(left) && !UnicodeUtil.letter?(right)
+
+          # Case 2 -- medial apostrophe: `don't`, `l'été`, `O'Brien`, `1990's`.
+          return true if alnum?(left) && alnum?(right)
+
+          # Case 3 -- trailing elision or possessive: `the dogs' bowls`, `Jesus'`, `rock 'n'` (the
+          # trailing mark).
+          if left != Engine::NONE && UnicodeUtil.letter?(left) &&
+             (right == Engine::NONE || spacelike?(right) || CLOSEISH.include?(right))
+            return true
+          end
+
+          # Case 4 -- leading elision: `'90s`, `'tis`, `'em`, `'n'` (the leading mark). The
+          # replacement is U+2019, never U+2018 -- a leading elision is a raised comma, not an
+          # opening quotation mark, and `quotes` has already had its chance to claim the mark as a
+          # quotation and declined (quotes.md 3.2, 5).
+          if (left == Engine::NONE || spacelike?(left) || OPENISH.include?(left)) && alnum?(right)
+            return true
+          end
+
+          # Case 5 -- nothing inferable: `a ' b`, `''`. Leave it.
+          false
+        end
+
+        def self.scan(cp, locale_data, _ctx)
+          n = cp.length
+          # apostrophe.md 3.4, spec 0.5.0: positions in the shared ambiguous-medial-span preserve
+          # set (an ambiguous shape with no cited elisionIdioms match) are skipped entirely,
+          # before left/right are even read -- this rule's own case ladder would otherwise curl
+          # both marks of e.g. `rock 'n' roll` independently and silently defeat quotes'
+          # deliberate veto.
+          idioms = (locale_data["quotes"] || {})["elisionIdioms"] || []
+          preserve = QuoteAmbiguity.compute_preserve_indices(cp, idioms)
+
+          edits = []
+          (0...n).each do |i|
+            next unless cp[i] == SQ
+            next if preserve.key?(i)
+
+            left = QuoteAmbiguity.at(cp, i - 1)
+            right = QuoteAmbiguity.at(cp, i + 1)
+            next unless apostrophe?(left, right)
+
+            edits << Engine::Edit.new(i, i + 1, [RIGHT_SINGLE], "apostrophe")
+          end
+
+          edits
+        end
+      end
+    end
+  end
+end
+
+Polytypo::Engine::Registry.register(
+  "apostrophe",
+  ->(cp, locale_data, ctx) { Polytypo::Engine::Rules::Apostrophe.scan(cp, locale_data, ctx) }
+)