suma 0.5.3 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd20e6823c86b989284cda93b4edf57c6ff7d16520e4a35fb111ee7df94c45e2
-  data.tar.gz: cd8763148b716e7ee6b226f4306fb4f33c825b9d6139978fb8f633496164b319
+  metadata.gz: f6a70a78b69206429eb11f3798c6c7f6e0fcfb2a3c46fd2dcea9e605b9ed230f
+  data.tar.gz: 8ba4c119da7747d212a4e1e85d13a4cbf0191cc780566f4f8a0fbca0529eb91a
 SHA512:
-  metadata.gz: ceb4f07c65cf174b04c0511d0f5cf9c0b753de5d1e55cf14c87d98276f4c11518d6c9d3367c4804eb7a7c0368f08ece16f36dc26fe07e6492ec24d07fc20ea85
-  data.tar.gz: d8f38fa09779fb06f5c8d6d0da109e6f3edf11be8dfb00b382bb0aba5a1c5e03cb4da981e8ea45a06cd6bebec093a6e50fa6acdb10d19013c94d517e5a286e1b
+  metadata.gz: 2b695befb4db91a60adbb4b43739367e5187d9e07b4c97610b0843886cfbed4bc53ce6ac7ce43764fa27e9f6d9c46db9b57dfc2e298944429524b9fe7abbdd4b
+  data.tar.gz: d8c3bc865349f54b50425b130f527b863442d43a50cdafe820a0fa37dad103300b8cfd2e0c3fbf5304039e1af592db2b8d1cd03f3e0bbe8db7ccce1f55f9f9d4

data/Gemfile

@@ -25,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/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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Suma
-  VERSION = "0.5.3"
+  VERSION = "0.5.4"
 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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: suma
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.4
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expressir
@@ -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