suma 0.5.2 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f9f2ba538c3f9515549875292447ece09cc661afd3357af6b2662052afeb8aa
-  data.tar.gz: a8fbfe210cb3d5e112ef03632c8f93678a02a59c307bb2407491dae30471d455
+  metadata.gz: f6a70a78b69206429eb11f3798c6c7f6e0fcfb2a3c46fd2dcea9e605b9ed230f
+  data.tar.gz: 8ba4c119da7747d212a4e1e85d13a4cbf0191cc780566f4f8a0fbca0529eb91a
 SHA512:
-  metadata.gz: b9b4920a4a4961319ac8ee67abccf38557b41d19f12d579711f20310429af4a9532be3204e11384ecb52fe6a22db82967fa7afd7a24bca15fb5f77357a0bdffe
-  data.tar.gz: 1a03d235c43500e7361fe8002cfb877944285a608cca4ee8be5edde1904cccb6fb0d7cda2df0b93b1f3a56574ff642651f1461bbda8f0c0f5875fdec7ca56ab0
+  metadata.gz: 2b695befb4db91a60adbb4b43739367e5187d9e07b4c97610b0843886cfbed4bc53ce6ac7ce43764fa27e9f6d9c46db9b57dfc2e298944429524b9fe7abbdd4b
+  data.tar.gz: d8c3bc865349f54b50425b130f527b863442d43a50cdafe820a0fa37dad103300b8cfd2e0c3fbf5304039e1af592db2b8d1cd03f3e0bbe8db7ccce1f55f9f9d4

data/.github/workflows/release.yml

@@ -14,21 +14,17 @@ on:
   repository_dispatch:
     types: [ do-release ]
 
+# Least-privilege ceiling for the called rubygems-release.yml: its release job
+# needs contents:write (git tag push) and id-token:write (OIDC Trusted Publishing).
+permissions:
+  contents: write
+  id-token: write
+
 jobs:
   release:
     uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
     with:
       next_version: ${{ github.event.inputs.next_version }}
-      # Explicit release_command needed since metanorma/ci#314 deprecated
-      # `bundler_cache` (hardcoded to false) — the reusable's release job no
-      # longer runs `bundle install` implicitly via ruby/setup-ruby, so the
-      # default `bundle exec rake release` fires against uninstalled gems.
-      # Surfaced by kwkwan on metanorma-plugin-lutaml#285. Deeper fix
-      # (bundle install inside rubygems-release.yml's release job) tracked
-      # separately.
-      release_command: |
-        bundle install
-        bundle exec rake release
     secrets:
       rubygems-api-key: ${{ secrets.METANORMA_CI_RUBYGEMS_API_KEY }}
       pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/Gemfile

@@ -6,13 +6,17 @@ source "https://rubygems.org"
 gemspec
 
 gem "canon"
-# Staged build (suma#94) needs the preserve_unresolved: / artifact_store_dir: /
-# reinflate: render options from metanorma#578 (metanorma 2.5.0). Point at the
-# feature branch until it is released; drop this once 2.5.0 is on rubygems.
-gem "metanorma", github: "metanorma/metanorma",
-                 branch: "feature/collection-incremental-resumable"
+# metanorma resolves from the gemspec constraint (~> 2.3) to the released gem.
+# The staged-build render options (preserve_unresolved:/artifact_store_dir:/
+# reinflate:, metanorma#578) landed in metanorma 2.5.0, now on rubygems, so the
+# former feature-branch override (feature/collection-incremental-resumable) is
+# dropped: CI builds against a stable released metanorma, not a floating branch.
+# Flavor gem needed to compile the dummy-collection integration fixture
+# (spec/fixtures/dummy_collection, suma#107).
+gem "metanorma-iso"
 # gem "metanorma-plugin-lutaml", github: "metanorma/metanorma-plugin-lutaml", branch: "main"
 # gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "main"
+# gem "expressir", github: "lutaml/expressir", branch: "main"
 gem "nokogiri"
 gem "openssl", "~> 3.0"
 gem "rake"
@@ -21,3 +25,25 @@ gem "rubocop"
 gem "rubocop-performance"
 gem "rubocop-rake"
 gem "rubocop-rspec"
+# Expressir >= 2.4.4 passes the lutaml-model `serialize:` mapping
+# kwarg, which needs lutaml-model >= 0.8.50, which needs rubyzip ~> 3,
+# which needs glossarist >= 2.14, which needs relaton ~> 3.0.0.pre.alpha
+# — a chain no RELEASED metanorma accepts. Left unpinned, the resolver
+# lands on expressir 2.4.5 (whose gemspec under-declares its
+# lutaml-model floor) + lutaml-model 0.8.29, a pair that crashes at
+# load with `unknown keyword: :serialize`. Pin the last released
+# expressir that works on this chain; lift once a released metanorma
+# accepts relaton 3.
+gem "expressir", "2.4.3"
+
+# Metanorma 2.5.5 was released referencing Metanorma::Core::Flavors,
+# which only exists in unreleased metanorma-core; its gemspec
+# under-declares the metanorma-core floor, so fresh resolves crash at
+# Metanorma::Collection.parse. Stay on the last consistent release
+# until metanorma-core ships.
+gem "metanorma", "< 2.5.5"
+
+# metanorma-plugin-lutaml 0.7.52+ calls Expressir::Express::LazyRepository
+# (expressir >= 2.4.20) but its gemspec still allows expressir >= 2.3.5,
+# breaking builds on the pinned expressir line above.
+gem "metanorma-plugin-lutaml", "< 0.7.52"

data/lib/suma/cli/convert_jsdai.rb

@@ -10,7 +10,7 @@ module Suma
       desc "convert_jsdai XML_FILE IMAGE_FILE OUTPUT_DIR",
            "Convert JSDAI XML and image files to SVG and EXP files"
 
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def convert_jsdai(xml_file, image_file, output_dir)
         xml_file = File.expand_path(xml_file)
         image_file = File.expand_path(image_file)
@@ -34,11 +34,10 @@ module Suma
 
         run(xml_file, image_file, output_dir)
       end
-      # rubocop:enable Metrics/MethodLength
 
       private
 
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def run(xml_file, image_file, output_dir)
         FileUtils.mkdir_p(output_dir)
 
@@ -57,7 +56,6 @@ module Suma
 
         puts "Conversion complete."
       end
-      # rubocop:enable Metrics/MethodLength
     end
   end
 end

data/lib/suma/cli/validate.rb

@@ -10,6 +10,9 @@ module Suma
     # indexing, validation) lives in the deep module and is reachable
     # from specs without invoking Thor.
     class Validate < Thor
+      def self.exit_on_failure?
+        true
+      end
       desc "links SCHEMAS_FILE DOCUMENTS_PATH [OUTPUT_FILE]",
            "Extract and validate express links without creating intermediate file"
       def links(schemas_file = "schemas-srl.yml",
@@ -22,6 +25,52 @@ module Suma
         ).call
         puts LinkValidation.generate_summary(result)
       end
+
+      desc "mappings DOCUMENTS_PATH",
+           "Validate module mapping.yaml links and reference paths " \
+           "against the parsed module corpus; only NEW drift " \
+           "(not in the baseline) fails"
+      option :baseline, type: :string, default: nil,
+                        desc: "Baseline YAML path (default: " \
+                              "mapping-drift-baseline.yml under DOCUMENTS_PATH)"
+      option :write_baseline, type: :boolean, default: false,
+                              desc: "Write the scanned drift as the new " \
+                                    "baseline instead of checking"
+      def mappings(documents_path = "documents")
+        drift = MappingDrift.new(documents_path)
+        path = options[:baseline] || default_baseline_path(documents_path)
+
+        return write_baseline(drift, path) if options[:write_baseline]
+
+        assert_baseline!(path)
+        fail_on_new_drift(*drift.check(path), path)
+      end
+
+      private
+
+      def default_baseline_path(documents_path)
+        File.join(documents_path, "mapping-drift-baseline.yml")
+      end
+
+      def assert_baseline!(path)
+        return if File.file?(path)
+
+        raise Thor::Error, "no baseline at #{path} — generate one with " \
+                           "--write-baseline and commit it"
+      end
+
+      def fail_on_new_drift(report, fresh, path)
+        say "#{report.entries.size} drift entr(ies), #{fresh.size} new vs #{path}"
+        return if fresh.empty?
+
+        raise Thor::Error, "#{fresh.size} new mapping drift:\n#{fresh.join("\n")}"
+      end
+
+      def write_baseline(drift, path)
+        report = drift.scan
+        File.write(path, report.to_yaml)
+        say "baseline written: #{path} (#{report.entries.size} entries)"
+      end
     end
   end
 end

data/lib/suma/express_schema.rb

@@ -64,7 +64,7 @@ module Suma
     end
 
     def to_plain
-      parsed.to_s(no_remarks: true)
+      parsed.to_s
     end
 
     def filename_plain
@@ -92,7 +92,7 @@ module Suma
 
       FileUtils.mkdir_p(File.dirname(filename_plain))
 
-      content = with_annotations ? parsed.to_s(no_remarks: false) : to_plain
+      content = with_annotations ? parsed.format(no_remarks: false) : to_plain
       File.write(filename_plain, content)
     end
 

data/lib/suma/jsdai/figure.rb

@@ -12,7 +12,7 @@ module Suma
         @xml_file = xml_file
       end
 
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def to_svg
         width, height = @image.dimensions
         svg_parts = []
@@ -46,9 +46,8 @@ module Suma
         svg_parts << "\n\t\t</svg>"
         svg_parts.join
       end
-      # rubocop:enable Metrics/MethodLength
 
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def to_exp
         basename = File.basename(@xml_file, ".xml")
         schema_name = extract_schema_name(basename)
@@ -73,11 +72,10 @@ module Suma
         exp_parts << "\n*)\n"
         exp_parts.join
       end
-      # rubocop:enable Metrics/MethodLength
 
       private
 
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def generate_shape_element(area)
         shape_attrs = []
         shape_attrs << 'onmouseout="this.style.opacity=0" '
@@ -108,7 +106,6 @@ module Suma
           "<rect #{shape_attrs.join}"
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
       def parse_rect_coords(coords_str)
         parts = coords_str.split(",").map(&:to_i)
@@ -140,7 +137,7 @@ module Suma
         end
       end
 
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def extract_schema_name(basename)
         # For module schemas like "armexpg1" with module="activity"
         # Result should be "Activity_arm"
@@ -159,9 +156,8 @@ module Suma
           basename.sub(/expg\d+$/, "")
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def extract_target_from_href(href)
         # Extract the target from href
         # Type 1: "../../resources/action_schema/action_schema.xml#action_schema.as_name_attribute_select"
@@ -201,7 +197,6 @@ module Suma
           href
         end
       end
-      # rubocop:enable Metrics/MethodLength
     end
   end
 end

data/lib/suma/jsdai/figure_image.rb

@@ -58,7 +58,7 @@ module Suma
         end
       end
 
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def extract_jpeg_dimensions
         # Read JPEG file to extract dimensions
         # JPEG uses markers, we look for SOF (Start of Frame) markers
@@ -90,7 +90,6 @@ module Suma
           end
         end
       end
-      # rubocop:enable Metrics/MethodLength
     end
   end
 end

data/lib/suma/link_validation.rb

@@ -127,13 +127,28 @@ module Suma
     def validate_links(schemas_config, links_by_file)
       paths_by_id = schemas_config.schemas.to_h { |s| [s.id, s.path] }
       progress.start("Loading schemas", paths_by_id.size)
-      repo = Expressir::Express::Parser.from_files(paths_by_id.values) do |*_args|
-        progress.increment
-      end
+      repo = load_repository(paths_by_id.values)
       index = SchemaIndex.new(repo)
       LinkValidator.new(index).validate(links_by_file)
     end
 
+    # Compiled-set warm start (expressir TODO.suma-improvements/04),
+    # opt-in via SUMA_COMPILED_SET=1: parse the closure once into an
+    # EXSCS1 artifact beside the output and hydrate from it on
+    # subsequent runs.
+    def load_repository(paths)
+      return Expressir::Express::Parser.from_files(paths) unless ENV["SUMA_COMPILED_SET"] == "1"
+
+      dir = output_file ? output_file.dirname : Pathname.new(Dir.pwd)
+      set_path = File.join(dir, "schema-closure.exscs")
+      if File.file?(set_path)
+        return Expressir::Express::LazyRepository.new(set_path).to_eager
+      end
+
+      FileUtils.mkdir_p(dir)
+      Expressir::Express::Parser.from_files(paths, compiled_set: set_path)
+    end
+
     def write_summary(result)
       FileUtils.mkdir_p(output_file.dirname)
       File.write(output_file, self.class.generate_summary(result))

data/lib/suma/mapping_drift.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "expressir"
+
+module Suma
+  # Mapping validation surfaced in builds (expressir
+  # TODO.suma-improvements/05): validate every module mapping.yaml —
+  # its <<express:...>> links and reference paths — against the parsed
+  # module corpus, and compare the drift against a committed baseline
+  # so only NEW drift fails a build.
+  #
+  # Owns: module discovery, the shared repository parse, per-module
+  # validation, and the baseline comparison. Does not own: presentation
+  # and exit codes (the CLI adapter), or the validation rules
+  # (Expressir::Mapping does).
+  class MappingDrift
+    # One drift finding; +key+ is the stable identity compared across
+    # runs: "<module path>|<kind>|<detail>".
+    class Entry < Lutaml::Model::Serializable
+      attribute :key, :string
+
+      key_value do
+        map "key", to: :key
+      end
+    end
+
+    # Serializable drift report / baseline (same wire shape).
+    class Report < Lutaml::Model::Serializable
+      attribute :entries, Entry, collection: true
+
+      key_value do
+        map "entries", to: :entries
+      end
+
+      def keys
+        entries.map(&:key)
+      end
+    end
+
+    MAPPING_GLOB = "**/mapping.yaml"
+    MODULE_SCHEMAS = %w[arm.exp mim.exp].freeze
+    private_constant :MAPPING_GLOB, :MODULE_SCHEMAS
+
+    attr_reader :documents_path, :stepmod
+
+    # +stepmod+ overrides where closure schema resolution looks up
+    # USE/REFERENCE dependencies (STEPmod `schemas/**/<name>.exp`
+    # layout); it defaults to +documents_path+ itself.
+    def initialize(documents_path, stepmod: nil)
+      @documents_path = Pathname.new(documents_path).expand_path
+      @stepmod = stepmod
+    end
+
+    # Every module mapping under documents_path that has arm/mim
+    # schemas next to it.
+    def discover
+      Dir[documents_path.join(MAPPING_GLOB).to_s].filter_map do |mapping|
+        schemas = module_schemas(File.dirname(mapping))
+        { mapping: mapping, schemas: schemas } if schemas.any?
+      end
+    end
+
+    # Validate every discovered module against one shared repository.
+    # @return [Report]
+    def scan
+      modules = discover
+      return Report.new(entries: []) if modules.empty?
+
+      paths, gaps = closure(modules)
+      repository = Expressir::Express::Parser.from_files(paths)
+      Report.new(entries: gaps + modules.flat_map do |mod|
+        drift_for(mod, repository)
+      end)
+    end
+
+    # Scan and compare against the baseline file.
+    # @return [[Report, Array<String>]] the full report and the keys
+    #   not present in the baseline (the NEW drift).
+    def check(baseline_path)
+      known = Report.from_yaml(File.read(baseline_path)).keys
+      report = scan
+      [report, report.keys - known]
+    end
+
+    private
+
+    def module_schemas(dir)
+      MODULE_SCHEMAS
+        .map { |name| File.join(dir, name) }
+        .select { |path| File.file?(path) }
+    end
+
+    # The repository covers every module schema plus its transitive
+    # USE/REFERENCE closure — reference paths name resource-schema
+    # types the modules themselves never declare. A schema the corpus
+    # does not carry (e.g. external PLIB templates) becomes a closure
+    # gap entry instead of aborting the whole scan; the affected
+    # module still validates against its own schemas.
+    def closure(modules)
+      paths = []
+      gaps = []
+      modules.each do |mod|
+        mod[:schemas].each do |root|
+          paths.concat(closure_of(root, mod[:mapping], gaps))
+        end
+      end
+      [paths.compact.uniq, gaps]
+    end
+
+    def closure_of(root, mapping_path, gaps)
+      Expressir::Commands::ParityInputs.closure_paths(root,
+                                                      stepmod: stepmod_root)
+    rescue StandardError => e
+      gaps << Entry.new(key: entry_key(mapping_path, "closure", e.message))
+      [root]
+    end
+
+    def stepmod_root
+      stepmod || documents_path.to_s
+    end
+
+    def drift_for(mod, repository)
+      mapping_path = mod[:mapping]
+      begin
+        document = Expressir::Mapping.load_file(mapping_path)
+      rescue StandardError => e
+        return [Entry.new(key: entry_key(mapping_path, "load", e.message))]
+      end
+
+      unknown = Expressir::Mapping.unknown_links(document, repository)
+      unknown.map do |link|
+        Entry.new(key: entry_key(mapping_path, "unknown_link", link.text))
+      end + refpath_issues(mapping_path, document, repository)
+    end
+
+    def refpath_issues(mapping_path, document, repository)
+      Expressir::Mapping.refpaths(document).flat_map do |location, content|
+        parsed = Expressir::Mapping::RefPath.parse(content)
+        parse_error_entries(mapping_path, location, parsed) +
+          validate_entries(mapping_path, location, parsed, repository)
+      end
+    end
+
+    def parse_error_entries(mapping_path, location, parsed)
+      parsed.parse_errors.map do |error|
+        Entry.new(key: entry_key(mapping_path, "refpath",
+                                 "#{location}: #{error}"))
+      end
+    end
+
+    def validate_entries(mapping_path, location, parsed, repository)
+      Expressir::Mapping::RefPath.validate(parsed, repository).map do |issue|
+        detail = "#{location} [step #{issue.step}]: #{issue.message}"
+        Entry.new(key: entry_key(mapping_path, "refpath", detail))
+      end
+    end
+
+    def entry_key(mapping_path, kind, detail)
+      "#{relative(mapping_path)}|#{kind}|#{detail}"
+    end
+
+    def relative(path)
+      Pathname.new(path).expand_path.relative_path_from(documents_path).to_s
+    end
+  end
+end

data/lib/suma/null_cache.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Suma
+  # Null-object cache used when schema caching is disabled: every fetch misses
+  # and nothing is stored, so callers need no conditional guards around a cache.
+  class NullCache
+    def fetch(*, **) = nil
+
+    def store(*, **) = nil
+  end
+end

data/lib/suma/schema_cache.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+
+module Suma
+  # Content-addressed, on-disk cache of *generated* EXPRESS schema output --
+  # the plain (annotations stripped, ISO copyright kept) or annotated `.exp`
+  # text produced from a source schema.
+  #
+  # The cache key composes the source bytes, the Expressir version, and the
+  # annotation mode. Those three fully determine the output (Expressir's
+  # serialiser is deterministic), so a hit is guaranteed byte-identical to a
+  # fresh generation -- and the store can be shared across builds and git
+  # worktrees: identical source content hits regardless of which build wrote it.
+  #
+  # Supersedes the parsed-AST `Marshal` approach of metanorma/suma#35, which was
+  # brittle across Ruby/Expressir versions and cached the wrong artifact (the
+  # parse, not the output).
+  class SchemaCache
+    def initialize(directory)
+      @directory = directory.to_s
+    end
+
+    # The cached output for +source+, or +nil+ on a miss.
+    def fetch(source, annotations:)
+      path = entry_path(source, annotations: annotations)
+      return unless File.exist?(path)
+
+      File.read(path, encoding: "UTF-8")
+    end
+
+    # Cache +content+ as the output for +source+. Returns the entry path.
+    def store(source, annotations:, content:)
+      path = entry_path(source, annotations: annotations)
+      FileUtils.mkdir_p(@directory)
+      write_atomically(path, content)
+      path
+    end
+
+    private
+
+    def entry_path(source, annotations:)
+      File.join(@directory, key(source, annotations: annotations))
+    end
+
+    def key(source, annotations:)
+      mode = annotations ? "annotated" : "plain"
+      "#{Digest::SHA256.hexdigest(source)}-#{expressir_version}-#{mode}.exp"
+    end
+
+    def expressir_version
+      @expressir_version ||= Expressir::VERSION
+    end
+
+    # Write through a sibling temp file and rename, so a concurrent reader never
+    # observes a half-written entry.
+    def write_atomically(path, content)
+      temp = "#{path}.#{Process.pid}.tmp"
+      File.write(temp, content, encoding: "UTF-8")
+      File.rename(temp, path)
+    ensure
+      File.delete(temp) if temp && File.exist?(temp)
+    end
+  end
+end

data/lib/suma/schema_collection.rb

@@ -7,8 +7,9 @@ module Suma
     attr_accessor :config, :schemas, :docs, :output_path_docs,
                   :output_path_schemas, :manifest
 
-    def initialize(config: nil, config_yaml: nil, output_path_docs: nil,
-                   output_path_schemas: nil, manifest: nil)
+    def initialize(config: nil, config_yaml: nil, output_path_docs: nil, # rubocop:disable Metrics/ParameterLists
+                   output_path_schemas: nil, manifest: nil,
+                   options: { annotations: true })
       @schemas = {}
       @docs = {}
       @schema_name_to_docs = {}
@@ -19,6 +20,7 @@ module Suma
       @config = config
       @config ||= config_yaml && Expressir::SchemaManifest.from_file(config_yaml)
       @manifest = manifest
+      @options = options
     end
 
     def doc_from_schema_name(schema_name)
@@ -42,7 +44,7 @@ module Suma
       exporter = SchemaExporter.new(
         schemas: schemas.values,
         output_path: @output_path_schemas,
-        options: { annotations: false },
+        options: @options,
       )
       exporter.export
 

data/lib/suma/schema_exporter.rb

@@ -23,6 +23,7 @@ module Suma
       @schemas = schemas
       @output_path = Pathname.new(output_path).expand_path
       @options = default_options.merge(options)
+      @cache = build_cache
     end
 
     def export
@@ -45,19 +46,51 @@ module Suma
     end
 
     def export_to_directory(schemas)
-      schemas.each do |schema|
-        schema.save_exp(with_annotations: options[:annotations])
-      end
+      schemas.each { |schema| export_single_schema(schema) }
+    end
+
+    # Reuse cached plain/annotated output when the schema source is unchanged,
+    # otherwise generate it via +save_exp+ and cache the result. The Expressir
+    # parse (the cost) happens only on a cache miss. Caching is an orchestration
+    # concern, so it lives here in the service rather than in the ExpressSchema
+    # data model.
+    def export_single_schema(schema)
+      source = File.read(schema.path.to_s, encoding: "UTF-8")
+      cached = @cache.fetch(source, annotations: options[:annotations])
+      cached ? write_cached(schema, cached) : generate_and_cache(schema, source)
+    end
+
+    def generate_and_cache(schema, source)
+      schema.save_exp(with_annotations: options[:annotations])
+      content = File.read(schema.filename_plain)
+      @cache.store(source, annotations: options[:annotations], content: content)
+    end
+
+    def write_cached(schema, content)
+      relative = Pathname.new(schema.filename_plain).relative_path_from(Dir.pwd)
+      Utils.log "Save schema (cached): #{relative}"
+      FileUtils.mkdir_p(File.dirname(schema.filename_plain))
+      File.write(schema.filename_plain, content)
+    end
+
+    # A shared, content-addressed cache when a cache directory is configured
+    # (via the +:cache_dir+ option or the SUMA_SCHEMA_CACHE_DIR environment
+    # variable), otherwise a null cache (caching disabled).
+    def build_cache
+      directory = options[:cache_dir] || ENV.fetch("SUMA_SCHEMA_CACHE_DIR", nil)
+      return NullCache.new if directory.nil? || directory.empty?
+
+      SchemaCache.new(directory)
     end
 
-    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable-next Metrics/MethodLength
     def create_zip_archive
       require "zip"
 
       zip_path = "#{output_path}.zip"
       Utils.log "Creating ZIP archive: #{zip_path}"
 
-      Zip::File.open(zip_path, Zip::File::CREATE) do |zipfile|
+      Zip::File.open(zip_path, create: true) do |zipfile|
         Dir.glob("#{output_path}/**/*").each do |file|
           next if File.directory?(file)
 
@@ -68,6 +101,5 @@ module Suma
 
       Utils.log "ZIP archive created: #{zip_path}"
     end
-    # rubocop:enable Metrics/MethodLength
   end
 end

data/lib/suma/svg_quality/formatters.rb

@@ -5,8 +5,8 @@ module Suma
     module Formatters
       autoload :TerminalFormatter,
                "suma/svg_quality/formatters/terminal_formatter"
-      autoload :JsonFormatter,     "suma/svg_quality/formatters/json_formatter"
-      autoload :YamlFormatter,     "suma/svg_quality/formatters/yaml_formatter"
+      autoload :JsonFormatter, "suma/svg_quality/formatters/json_formatter"
+      autoload :YamlFormatter, "suma/svg_quality/formatters/yaml_formatter"
     end
   end
 end

data/lib/suma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Suma
-  VERSION = "0.5.2"
+  VERSION = "0.5.4"
 end

data/lib/suma.rb

@@ -16,8 +16,11 @@ module Suma
   autoload :LinkValidation,         "suma/link_validation"
   autoload :LinkValidator,          "suma/link_validator"
   autoload :ManifestTraverser,      "suma/manifest_traverser"
+  autoload :MappingDrift,           "suma/mapping_drift"
   autoload :NoteProcessor,          "suma/note_processor"
+  autoload :NullCache,              "suma/null_cache"
   autoload :RegisterManifestGenerator, "suma/register_manifest_generator"
+  autoload :SchemaCache,            "suma/schema_cache"
   autoload :SchemaCategory,         "suma/schema_category"
   autoload :SchemaCollection,       "suma/schema_collection"
   autoload :SchemaComparer,         "suma/schema_comparer"

data/suma.gemspec

@@ -33,13 +33,13 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "expressir", ">= 2.1.29", "~> 2.1"
+  spec.add_dependency "expressir"
   spec.add_dependency "glossarist", "~> 2.8", ">= 2.8.7"
   spec.add_dependency "lutaml-model", "~> 0.8.0"
   spec.add_dependency "metanorma", "~> 2.3"
   spec.add_dependency "plurimath"
   spec.add_dependency "ruby-progressbar"
-  spec.add_dependency "rubyzip", "~> 2.3"
+  spec.add_dependency "rubyzip"
   spec.add_dependency "svg_conform", "~> 0.1.0"
   spec.add_dependency "table_tennis"
   spec.add_dependency "thor", ">= 0.20"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: suma
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.4
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-28 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expressir
@@ -16,20 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.1.29
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.1.29
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: glossarist
   requirement: !ruby/object:Gem::Requirement
@@ -110,16 +104,16 @@ dependencies:
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: svg_conform
   requirement: !ruby/object:Gem::Requirement
@@ -216,9 +210,12 @@ files:
 - lib/suma/link_validator.rb
 - lib/suma/link_validator/step.rb
 - lib/suma/manifest_traverser.rb
+- lib/suma/mapping_drift.rb
 - lib/suma/note_processor.rb
+- lib/suma/null_cache.rb
 - lib/suma/processor.rb
 - lib/suma/register_manifest_generator.rb
+- lib/suma/schema_cache.rb
 - lib/suma/schema_category.rb
 - lib/suma/schema_collection.rb
 - lib/suma/schema_comparer.rb