suma 0.5.3 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd20e6823c86b989284cda93b4edf57c6ff7d16520e4a35fb111ee7df94c45e2
-  data.tar.gz: cd8763148b716e7ee6b226f4306fb4f33c825b9d6139978fb8f633496164b319
+  metadata.gz: 3924d8ea8d4f6e7dd9d94226840b4d6135606edfeffca7198d71d26b59f53208
+  data.tar.gz: adce8f15063a18626c2b7828e746078f2e1e588594e393aaa122e81144fd3ea0
 SHA512:
-  metadata.gz: ceb4f07c65cf174b04c0511d0f5cf9c0b753de5d1e55cf14c87d98276f4c11518d6c9d3367c4804eb7a7c0368f08ece16f36dc26fe07e6492ec24d07fc20ea85
-  data.tar.gz: d8f38fa09779fb06f5c8d6d0da109e6f3edf11be8dfb00b382bb0aba5a1c5e03cb4da981e8ea45a06cd6bebec093a6e50fa6acdb10d19013c94d517e5a286e1b
+  metadata.gz: f602953242571ffe779c059b4f5e16120fe08e6fa196dad10e7f095369ebe642afd7bc91d5f404ebadb4b8e48378bfca366c3f62697c001c2e2b0823ba81f1b8
+  data.tar.gz: 16b6596fe1658ccbb7ffa6b4d08969bf1ae9442835a498f99bb2bf756f713576b547dfb422741306753facd7a01fa3d790ff137f6b03f8a79b3a761427eddb09

data/Gemfile

@@ -13,10 +13,25 @@ gem "canon"
 # 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"
+# metanorma-iso releases (<= 3.5.0) require "pubid-iso"/"pubid-cen"/
+# "pubid-iec" (pubid 1.15 split gems) that do not exist on the relaton-3
+# chain, and whose lib/pubid/*.rb collide with the pubid 2 monolith's.
+# The pubid-2 migration is on metanorma-iso main; it needs the unreleased
+# metanorma-standoc "Standoc::Document" split, so pin that from main too.
+# Flip both to released gems once metanorma-iso releases the migration.
+gem "metanorma-iso", github: "metanorma/metanorma-iso", branch: "main"
+gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "main"
+# metanorma#607: Collection#bibitem must drop localized <edition> variants
+# (metanorma-iso main emits them) before the relaton parse.
+gem "metanorma", github: "metanorma/metanorma",
+                 branch: "fix/collection-bibdata-localized-edition"
+# iso/standoc main also use unreleased metanorma-document 0.5.x model
+# classes (e.g. Components::Inline::TermrefElement).
+gem "metanorma-document", github: "metanorma/metanorma-document", branch: "main"
 # 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 "expressir", "2.4.27"
 gem "nokogiri"
 gem "openssl", "~> 3.0"
 gem "rake"
@@ -25,3 +40,11 @@ gem "rubocop"
 gem "rubocop-performance"
 gem "rubocop-rake"
 gem "rubocop-rspec"
+# isodoc 3.7.3 `require`s "sassc-embedded" while rendering HTML but does
+# not declare it.
+gem "sassc-embedded", "~> 1.0"
+# relaton-render's floor (>= 2.0.0.pre.alpha.6) admits the stale June
+# 2.2.0.pre prerelease, which predates lutaml-model 0.8.78's strict
+# collection checks (duplicate <edition> raise). 2.1.9 is the current
+# lutaml-model-0.8 line.
+gem "relaton-bib", "2.1.9"

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/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/schema_template/document.rb

@@ -35,9 +35,9 @@ module Suma
           [%unnumbered,type=express]
           == #{schema_id} #{rendered_anchors}
 
-          [source%unnumbered]
+          [source%unnumbered,subs="+macros"]
           --
-          {{ schema.formatted }}
+          {{ schema.formatted_hyperlinked_adoc }}
           --
           {% endfor %}
           ----

data/lib/suma/version.rb

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

data/lib/suma.rb

@@ -16,6 +16,7 @@ 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"

data/suma.gemspec

@@ -40,7 +40,7 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.add_dependency "plurimath"
   spec.add_dependency "ruby-progressbar"
   spec.add_dependency "rubyzip"
-  spec.add_dependency "svg_conform", "~> 0.1.0"
+  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.3
+  version: 0.5.5
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expressir
@@ -118,14 +118,14 @@ dependencies:
   name: svg_conform
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.0
 - !ruby/object:Gem::Dependency
@@ -210,6 +210,7 @@ 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