suma 0.2.5 → 0.3.0

data/lib/suma/schema_comparer.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Suma
+  class SchemaComparer
+    attr_reader :trial_schema, :reference_schema, :options
+
+    def initialize(trial_schema, reference_schema, options = {})
+      @trial_schema = trial_schema
+      @reference_schema = reference_schema
+      @options = options
+    end
+
+    def compare
+      validate_inputs
+
+      trial_stepmod = options[:trial_stepmod] || detect_repo_root(trial_schema)
+      reference_stepmod = options[:reference_stepmod] || detect_repo_root(reference_schema)
+
+      out_dir = Dir.mktmpdir("eengine-compare-")
+
+      result = Eengine::Wrapper.compare(
+        trial_schema,
+        reference_schema,
+        mode: options[:mode] || "resource",
+        trial_stepmod: trial_stepmod,
+        reference_stepmod: reference_stepmod,
+        out_dir: out_dir,
+      )
+
+      unless result[:has_changes]
+        FileUtils.rm_rf(out_dir) if File.directory?(out_dir)
+        return nil
+      end
+
+      unless result[:xml_path]
+        raise Suma::CompilationError,
+              "XML output not found"
+      end
+
+      convert_to_change_yaml(result[:xml_path], out_dir)
+    ensure
+      FileUtils.rm_rf(out_dir) if out_dir && File.directory?(out_dir)
+    end
+
+    private
+
+    def validate_inputs
+      unless File.exist?(trial_schema)
+        raise Suma::SchemaNotFoundError,
+              "Trial schema not found: #{trial_schema}"
+      end
+
+      unless File.exist?(reference_schema)
+        raise Suma::SchemaNotFoundError,
+              "Reference schema not found: #{reference_schema}"
+      end
+
+      unless Eengine::Wrapper.available?
+        raise Suma::EengineNotAvailableError,
+              "eengine not found in PATH. Install from:\n  " \
+              "macOS: https://github.com/expresslang/homebrew-eengine\n  " \
+              "Linux: https://github.com/expresslang/eengine-releases"
+      end
+    end
+
+    def detect_repo_root(schema_path)
+      current = File.expand_path(File.dirname(schema_path))
+
+      loop do
+        return current if File.directory?(File.join(current, ".git"))
+
+        parent = File.dirname(current)
+        break if parent == current
+
+        current = parent
+      end
+
+      File.dirname(schema_path)
+    end
+
+    def convert_to_change_yaml(xml_path, _out_dir)
+      schema_name = extract_schema_name(trial_schema)
+      output_path = determine_output_path
+
+      existing_schema = nil
+      if File.exist?(output_path)
+        require "expressir/changes"
+        existing_schema = Expressir::Changes::SchemaChange.from_file(output_path)
+      end
+
+      converter = EengineConverter.new(xml_path, schema_name)
+      change_schema = converter.convert(
+        version: options[:version],
+        existing_change_schema: existing_schema,
+      )
+
+      change_schema.to_file(output_path)
+      output_path
+    end
+
+    def extract_schema_name(path)
+      basename = File.basename(path, ".exp")
+      basename.sub(/_\d+$/, "")
+    end
+
+    def determine_output_path
+      options[:output] || begin
+        base = extract_schema_name(trial_schema)
+        dir = File.dirname(trial_schema)
+        File.join(dir, "#{base}.changes.yaml")
+      end
+    end
+  end
+end

data/lib/suma/schema_compiler.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Suma
+  # Orchestrates the compilation of a single EXPRESS schema into HTML/XML
+  # via Metanorma.
+  #
+  # SchemaCompiler owns all file I/O and the Metanorma::Compile invocation
+  # for one schema; the rendered AsciiDoc body is supplied by a SchemaTemplate
+  # that the caller injects. This split means templates can be tested as pure
+  # functions and the compiler can be tested with a real adoc fixture, without
+  # either depending on the other.
+  class SchemaCompiler
+    attr_reader :schema, :id, :output_path, :template
+
+    def initialize(schema:, output_path:, template:)
+      @schema = schema
+      @id = schema.id
+      @output_path = output_path
+      @template = template
+    end
+
+    def compile
+      save_config
+      save_adoc
+      invoke_metanorma
+      self
+    end
+
+    def output_xml_path
+      filename_adoc("xml")
+    end
+
+    def extensions
+      template.extensions
+    end
+
+    private
+
+    def filename_adoc(ext = "adoc")
+      File.join(output_path, "doc_#{id}.#{ext}")
+    end
+
+    def filename_config
+      File.join(output_path, "schema_#{id}.yaml")
+    end
+
+    def save_adoc
+      log_relative "Save EXPRESS adoc", filename_adoc
+
+      FileUtils.mkdir_p(File.dirname(filename_adoc))
+
+      config_relative = Pathname.new(filename_config)
+        .relative_path_from(Pathname.new(File.dirname(filename_adoc)))
+
+      File.write(filename_adoc, template.render(config_relative))
+    end
+
+    def save_config
+      log_relative "Save schema config", filename_config
+
+      FileUtils.mkdir_p(File.dirname(filename_config))
+      config = Expressir::SchemaManifest.new
+      config.schemas << Expressir::SchemaManifestEntry.new(id: id,
+                                                           path: schema.path)
+      config.save_to_path(filename_config)
+    end
+
+    def invoke_metanorma
+      log_relative "Compiling schema (id: #{id})", filename_adoc
+      Metanorma::Compile.new.compile(
+        filename_adoc,
+        agree_to_terms: true,
+        install_fonts: false,
+      )
+      log_relative "Compiling schema (id: #{id}) ... done!", filename_adoc
+    end
+
+    def log_relative(prefix, path)
+      relative = Pathname.new(path).relative_path_from(Dir.pwd)
+      Utils.log "#{prefix}: #{relative}"
+    end
+  end
+end

data/lib/suma/schema_discovery.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Suma
+  # Service for schema-config I/O on a single CollectionManifest node.
+  #
+  # SchemaDiscovery owns two concerns that previously lived on
+  # CollectionManifest:
+  #
+  # 1. Loading the `schemas.yaml` that sits next to a `collection.yml`
+  #    into the manifest's `schema_config` slot.
+  # 2. Building the doc CollectionManifest sub-tree that hosts the
+  #    compiled XML output for each schema in `schema_config`.
+  #
+  # It does not walk the manifest tree — that is ManifestTraverser's job.
+  # The split keeps schema I/O in one place and tree traversal in another,
+  # so each is independently testable.
+  class SchemaDiscovery
+    attr_reader :manifest
+
+    def initialize(manifest)
+      @manifest = manifest
+    end
+
+    # If the manifest's file is a `collection.yml` and a `schemas.yaml`
+    # sits alongside it, parse it into an Expressir::SchemaManifest and
+    # store it on the manifest. Otherwise leave `schema_config` untouched.
+    def load_config
+      return unless manifest.file
+      return unless File.basename(manifest.file) == "collection.yml"
+
+      schemas_yaml_path = File.join(File.dirname(manifest.file), "schemas.yaml")
+      return unless File.exist?(schemas_yaml_path)
+
+      manifest.schema_config = Expressir::SchemaManifest.from_file(schemas_yaml_path)
+    end
+
+    # Build a CollectionManifest sub-tree that hosts the compiled XML for
+    # every schema in `manifest.schema_config`. The wrapper is named with
+    # a trailing underscore so it does not collide with the parent id.
+    def build_added_manifest(schema_output_path)
+      doc = CollectionConfig.from_file(manifest.file)
+      doc_id = doc.bibdata.id
+
+      added = CollectionManifest.new(
+        title: "Collection",
+        type: "collection",
+        identifier: "#{manifest.identifier}_",
+      )
+
+      added.entry = [
+        CollectionManifest.new(
+          title: doc_id,
+          type: "document",
+          entry: build_doc_entries(schema_output_path),
+        ),
+      ]
+
+      added
+    end
+
+    # Build one CollectionManifest per schema in schema_config, naming
+    # each output file as `doc_<basename>.xml` under
+    # `<schema_output_path>/<schema_id>/`.
+    def build_doc_entries(schema_output_path)
+      manifest.schema_config.schemas.map do |schema|
+        xml_basename = "#{File.basename(schema.path, '.exp')}.xml"
+        CollectionManifest.new(
+          identifier: schema.id,
+          title: schema.id,
+          file: File.join(schema_output_path, schema.id, "doc_#{xml_basename}"),
+        )
+      end
+    end
+  end
+end

data/lib/suma/schema_exporter.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "express_schema"
-require_relative "utils"
-require_relative "export_standalone_schema"
 require "fileutils"
 
 module Suma
@@ -43,53 +40,28 @@ module Suma
     end
 
     def export_single_schema(schema)
-      # Check if this is a standalone EXPRESS file
-      # (not from a manifest structure)
-      is_standalone_file = schema.is_a?(ExportStandaloneSchema)
-      schema_output_path = determine_output_path(schema, is_standalone_file)
+      is_standalone = !schema.is_a?(Expressir::SchemaManifestEntry)
+      schema_output_path = determine_output_path(schema, is_standalone)
 
       express_schema = ExpressSchema.new(
         id: schema.id,
         path: schema.path.to_s,
         output_path: schema_output_path,
-        is_standalone_file: is_standalone_file,
+        is_standalone_file: is_standalone,
       )
 
       express_schema.save_exp(with_annotations: options[:annotations])
     end
 
-    def determine_output_path(schema, is_standalone_file)
-      if is_standalone_file
-        # For standalone files, output directly to the root
+    def determine_output_path(schema, is_standalone)
+      if is_standalone
         output_path.to_s
       else
-        # For manifest schemas, preserve directory structure
-        category = categorize_schema(schema)
-        output_path.join(category).to_s
+        category = SchemaCategory.for_schema(id: schema.id, path: schema.path)
+        output_path.join(category.directory).to_s
       end
     end
 
-    # rubocop:disable Metrics/MethodLength
-    def categorize_schema(schema)
-      path = schema.path.to_s
-
-      # Check if this is from a manifest structure or a standalone EXPRESS file
-      case path
-      when %r{/resources/}
-        "resources"
-      when %r{/modules/}
-        "modules"
-      when %r{/business_object_models/}
-        "business_object_models"
-      when %r{/core_model/}
-        "core_model"
-      else
-        # standalone EXPRESS file not from a manifest structure
-        "standalone"
-      end
-    end
-    # rubocop:enable Metrics/MethodLength
-
     # rubocop:disable Metrics/MethodLength
     def create_zip_archive
       require "zip"

data/lib/suma/schema_index.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "expressir"
+
+module Suma
+  # Pre-built index for O(1) schema and element lookup.
+  # Build once from a parsed repo, then query by name.
+  class SchemaIndex
+    def initialize(repo)
+      @schemas_by_name = {}
+      @elements_by_schema = {}
+
+      repo.schemas.each do |schema|
+        key = schema.id.downcase
+        @schemas_by_name[key] = schema
+        @elements_by_schema[key] = build_element_index(schema)
+      end
+    end
+
+    def find_schema(name)
+      @schemas_by_name[name.downcase]
+    end
+
+    def find_element(schema_name, element_name)
+      elements = @elements_by_schema[schema_name.downcase]
+      elements&.[](element_name.downcase)
+    end
+
+    private
+
+    def build_element_index(schema)
+      index = {}
+
+      element_collections(schema).each do |collection|
+        collection&.each { |e| index[e.id.downcase] = e }
+      end
+
+      index
+    end
+
+    def element_collections(schema)
+      [
+        schema.entities,
+        schema.types,
+        schema.constants,
+        schema.functions,
+        schema.rules,
+        schema.procedures,
+        schema.subtype_constraints,
+      ]
+    end
+  end
+end

data/lib/suma/schema_manifest_generator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module Suma
+  class SchemaManifestGenerator
+    YAML_FILE_EXTENSIONS = [".yaml", ".yml"].freeze
+
+    def initialize(metanorma_manifest_file, schema_manifest_file,
+exclude_paths: nil)
+      @metanorma_manifest_file = File.expand_path(metanorma_manifest_file)
+      @schema_manifest_file = schema_manifest_file
+      @exclude_paths = exclude_paths
+    end
+
+    def generate
+      validate_inputs
+      metanorma_data = load_yaml(@metanorma_manifest_file)
+      collection_files = metanorma_data["metanorma"]["source"]["files"]
+      manifest_files = load_manifest_files(collection_files)
+      all_schemas = load_project_schemas(manifest_files)
+      all_schemas["schemas"] = all_schemas["schemas"].sort.to_h
+      write_output(all_schemas)
+    end
+
+    private
+
+    def validate_inputs
+      unless File.exist?(@metanorma_manifest_file)
+        raise Errno::ENOENT,
+              "Specified file `#{@metanorma_manifest_file}` not found."
+      end
+
+      unless File.file?(@metanorma_manifest_file)
+        raise ArgumentError,
+              "Specified path `#{@metanorma_manifest_file}` is not a file."
+      end
+
+      [@metanorma_manifest_file, @schema_manifest_file].each do |file|
+        unless YAML_FILE_EXTENSIONS.include?(File.extname(file))
+          raise ArgumentError, "Specified file `#{file}` is not a YAML file."
+        end
+      end
+    end
+
+    def load_yaml(file_path)
+      YAML.safe_load(File.read(file_path, encoding: "UTF-8"), aliases: true)
+    end
+
+    def load_manifest_files(collection_files)
+      collection_files.map do |c|
+        collection_data = load_yaml(c)
+        collection_data["manifest"]["docref"].map { |docref| docref["file"] }
+      end.flatten
+    end
+
+    def load_project_schemas(manifest_files)
+      all_schemas = { "schemas" => {} }
+
+      manifest_files.each do |file|
+        schemas_file_path = File.expand_path(file.gsub("collection.yml",
+                                                       "schemas.yaml"))
+
+        unless File.exist?(schemas_file_path)
+          Utils.log "Schemas file not found: #{schemas_file_path}"
+          next
+        end
+
+        schemas_data = load_yaml(schemas_file_path)
+
+        if schemas_data["schemas"]
+          schemas_data["schemas"] = fix_path(schemas_data, schemas_file_path)
+          all_schemas["schemas"].merge!(schemas_data["schemas"])
+        end
+
+        if @exclude_paths
+          all_schemas["schemas"].delete_if do |_key, value|
+            value["path"].match?(
+              Regexp.new(@exclude_paths.gsub("*", "(.*){1,999}")),
+            )
+          end
+        end
+      end
+
+      all_schemas
+    end
+
+    def fix_path(schemas_data, schemas_file_path)
+      schema_manifest_path = File.expand_path(@schema_manifest_file, Dir.pwd)
+
+      schemas_data["schemas"].each do |key, value|
+        path_in_schema = File.expand_path(value["path"],
+                                          File.dirname(schemas_file_path))
+
+        fixed_path = Pathname.new(path_in_schema).relative_path_from(
+          Pathname.new(File.dirname(schema_manifest_path)),
+        )
+
+        { key => value.merge!("path" => fixed_path.to_s) }
+      end
+
+      schemas_data["schemas"]
+    end
+
+    def write_output(all_schemas)
+      output_path = File.expand_path(@schema_manifest_file)
+      Utils.log "Writing the Schemas YAML file to #{output_path}..."
+      File.write(output_path, all_schemas.to_yaml)
+      Utils.log "Writing the Schemas YAML file to #{output_path}...Done"
+    end
+  end
+end

data/lib/suma/schema_naming.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Suma
+  # Converts EXPRESS schema identifiers into human-readable display names.
+  #
+  # Naming is model-driven: the schema type (resource/module) and suffix
+  # determine how the identifier is formatted. Acronyms and numeric
+  # prefixes are preserved to match ISO 10303 conventions.
+  #
+  # @example
+  #   SchemaNaming.display_name("topology_schema")
+  #   # => "Topology"
+  #   SchemaNaming.display_name("Activity_method_assignment_mim")
+  #   # => "Activity Method Assignment (MIM)"
+  #   SchemaNaming.display_name("aic_advanced_brep")
+  #   # => "AIC Advanced Brep"
+  module SchemaNaming
+    # Acronyms preserved as uppercase during title-casing.
+    # Source: ISO 10303 naming conventions.
+    ACRONYMS = %w[
+      aic aec apu bom csg edraw id ifc pdf pld
+      xml xpdl 2d 3d
+    ].freeze
+
+    # Lowercase function words (ISO title-case convention).
+    LOWERCASE_WORDS = %w[a an and as for in of on or the to].freeze
+
+    # Suffixes stripped from the schema name before title-casing,
+    # mapped to the parenthesised label appended to the display name.
+    # A +nil+ label means the suffix is stripped silently.
+    SUFFIXES = {
+      "_arm" => "ARM",
+      "_mim" => "MIM",
+      "_bom" => "BOM",
+      "_schema" => nil,
+    }.freeze
+
+    class << self
+      # Produce a human-readable display name from a schema identifier.
+      #
+      # @param schema_id [String] the EXPRESS schema identifier
+      # @return [String] human-readable name
+      def display_name(schema_id)
+        base, label = decompose(schema_id)
+        title_cased = title_case(base)
+        label ? "#{title_cased} (#{label})" : title_cased
+      end
+
+      # Produce a prefixed display name with the schema category.
+      #
+      # @param schema_id [String] the EXPRESS schema identifier
+      # @param path [String, Pathname] the schema file path (for classification)
+      # @return [String] e.g. "Resource: Topology" or "Module: Activity (ARM)"
+      def prefixed_name(schema_id, path: nil)
+        type = ExpressSchema::Type.classify(id: schema_id, path: path)
+        prefix = category_prefix(type)
+        "#{prefix}: #{display_name(schema_id)}"
+      end
+
+      # Determine the category prefix for a schema type.
+      #
+      # @param type [Symbol] one of ExpressSchema::Type constants
+      # @return [String]
+      def category_prefix(type)
+        SchemaCategory.for_type(type).prefix
+      end
+
+      private
+
+      # Split a schema ID into (base_without_suffix, suffix_label_or_nil).
+      #
+      # @return [(String, String, nil)]
+      def decompose(schema_id)
+        SUFFIXES.each do |suffix, label|
+          if schema_id.end_with?(suffix)
+            return [schema_id.delete_suffix(suffix),
+                    label]
+          end
+        end
+        [schema_id, nil]
+      end
+
+      # Title-case a snake_case identifier, preserving acronyms.
+      # The +tr+ collapses runs of underscores (leading, trailing, and
+      # consecutive) into spaces, which +split+ then treats as a single
+      # separator.
+      #
+      # @param name [String] snake_case identifier
+      # @return [String] title-cased name
+      def title_case(name)
+        words = name.tr("_", " ").split
+        words.each_with_index.map do |word, i|
+          capitalize_word(word, first: i.zero?)
+        end.join(" ")
+      end
+
+      # Capitalise a single word, preserving acronyms and
+      # lowercasing function words (except when first in the name).
+      #
+      # @param word [String]
+      # @param first [Boolean] whether this is the first word
+      # @return [String]
+      def capitalize_word(word, first: false)
+        return word.upcase if ACRONYMS.include?(word.downcase)
+        return word.downcase if LOWERCASE_WORDS.include?(word.downcase) && !first
+
+        word.capitalize
+      end
+    end
+  end
+end