suma 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1136a7e4a745c2e2dda6f8e3a42baca536732794bb5cb92a055831b7eaa9d967
-  data.tar.gz: f058690c21e1126054eb135ad09c76f7f95977068c05e195855b4ccafe78ab99
+  metadata.gz: bd20e6823c86b989284cda93b4edf57c6ff7d16520e4a35fb111ee7df94c45e2
+  data.tar.gz: cd8763148b716e7ee6b226f4306fb4f33c825b9d6139978fb8f633496164b319
 SHA512:
-  metadata.gz: dafc7f0fc01386c7568858a480d74da950c0c5b48a3f57fc02abe1e2104d68a0d612f1588a40a3046e5344baa3e177a088df6da0c0e47a47af9cf4d7ca79d365
-  data.tar.gz: 9fde63ff34104914a415c13280f29e6ed5e0c2e3c40d14d5e4ea8a3d4c8d45c80a6ba4cc12df6a98f687d2f21627b28532e2591a7071bf62fb7b287dcb6ae1a8
+  metadata.gz: ceb4f07c65cf174b04c0511d0f5cf9c0b753de5d1e55cf14c87d98276f4c11518d6c9d3367c4804eb7a7c0368f08ece16f36dc26fe07e6492ec24d07fc20ea85
+  data.tar.gz: d8f38fa09779fb06f5c8d6d0da109e6f3edf11be8dfb00b382bb0aba5a1c5e03cb4da981e8ea45a06cd6bebec093a6e50fa6acdb10d19013c94d517e5a286e1b

data/.github/workflows/release.yml

@@ -14,6 +14,12 @@ 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

data/.rubocop.yml

@@ -2,6 +2,14 @@
 # See https://github.com/metanorma/cimas
 inherit_from:
   - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
+  # .rubocop_todo.yml MUST be the last entry. inherit_from is last-wins:
+  # if listed before oss-guides, the shared config's stricter Metrics/
+  # (MethodLength, BlockLength, etc.) rules override the todo's per-file
+  # grandfathering, and the todo becomes inert on those cops. Empirically
+  # verified on suma 2026-07-06: with todo listed first, 34 Metrics/* offenses
+  # remained; moved last, cleared. Every gem in the metanorma-org fleet
+  # already ships a `.rubocop_todo.yml` on its live tree (audited 2026-07-06,
+  # 54/54 have it), so this reference is safe to emit unconditionally.
   - .rubocop_todo.yml
 
 # Rubocop plugins enabled centrally so every metanorma-org gem picks them up

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"

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/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/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
 
@@ -58,9 +60,12 @@ module Suma
     end
 
     def process_schema(config_schema, template_class)
+      category = SchemaCategory.for_schema(
+        id: config_schema.id, path: config_schema.path.to_s,
+      )
       express = ExpressSchema.new(
         id: config_schema.id, path: config_schema.path.to_s,
-        output_path: @output_path_schemas.to_s
+        output_path: @output_path_schemas.join(category.directory).to_s
       )
 
       compiler = SchemaCompiler.new(

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.1"
+  VERSION = "0.5.3"
 end

data/lib/suma.rb

@@ -17,7 +17,9 @@ module Suma
   autoload :LinkValidator,          "suma/link_validator"
   autoload :ManifestTraverser,      "suma/manifest_traverser"
   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,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: suma
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.3
 platform: ruby
 authors:
 - Ribose Inc.
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expressir
@@ -15,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
@@ -109,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,8 +211,10 @@ files:
 - lib/suma/link_validator/step.rb
 - lib/suma/manifest_traverser.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
@@ -253,6 +250,7 @@ licenses:
 - BSD-2-Clause
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -267,7 +265,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Utility for SUMA (STEP Unified Model-Based Standards Architecture)
 test_files: []