suma 0.2.6 → 0.4.0

data/lib/suma/schema_category.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Suma
+  # Value object mapping an ExpressSchema::Type to its register/export category.
+  #
+  # Single source of truth for category identity across the codebase:
+  # directory layout (SchemaExporter), display prefix (SchemaNaming), and
+  # register.yaml sections (RegisterManifestGenerator) all derive from this.
+  #
+  # Each category carries: +id+ (slug used in register.yaml section id and
+  # export subdirectory), +label+ (human-readable section heading),
+  # +prefix+ (prefix used when forming display names, e.g. "Resource: ..."),
+  # +types+ (Array of ExpressSchema::Type symbols that belong to it),
+  # and +directory+ (subdirectory name; "." for the root output path).
+  class SchemaCategory
+    attr_reader :id, :label, :prefix, :types, :directory
+
+    def initialize(id:, label:, prefix:, types:, directory:)
+      @id = id
+      @label = label
+      @prefix = prefix
+      @types = types
+      @directory = directory
+    end
+
+    def member?(type)
+      types.include?(type)
+    end
+
+    RESOURCES = new(
+      id: "resources",
+      label: "Resources",
+      prefix: "Resource",
+      types: [ExpressSchema::Type::RESOURCE].freeze,
+      directory: "resources",
+    )
+    MODULES = new(
+      id: "modules",
+      label: "Application Modules",
+      prefix: "Module",
+      types: [ExpressSchema::Type::MODULE_ARM, ExpressSchema::Type::MODULE_MIM].freeze,
+      directory: "modules",
+    )
+    BUSINESS_OBJECT_MODELS = new(
+      id: "business_object_models",
+      label: "Business Object Models",
+      prefix: "Business Object Model",
+      types: [ExpressSchema::Type::BUSINESS_OBJECT_MODEL].freeze,
+      directory: "business_object_models",
+    )
+    CORE_MODEL = new(
+      id: "core_model",
+      label: "Core Model",
+      prefix: "Core Model",
+      types: [ExpressSchema::Type::CORE_MODEL].freeze,
+      directory: "core_model",
+    )
+    OTHER = new(
+      id: "other",
+      label: "Other Schemas",
+      prefix: "Schema",
+      types: [ExpressSchema::Type::STANDALONE].freeze,
+      directory: ".",
+    )
+
+    ALL = [
+      RESOURCES,
+      MODULES,
+      BUSINESS_OBJECT_MODELS,
+      CORE_MODEL,
+      OTHER,
+    ].freeze
+
+    def self.for_type(type)
+      ALL.find { |category| category.member?(type) } || OTHER
+    end
+
+    def self.for_schema(id:, path:)
+      type = ExpressSchema::Type.classify(id: id, path: path)
+      for_type(type)
+    end
+  end
+end

data/lib/suma/schema_collection.rb

@@ -1,11 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "express_schema"
-require_relative "schema_attachment"
-require_relative "schema_document"
-require_relative "schema_exporter"
 require "expressir"
-require_relative "utils"
 
 module Suma
   class SchemaCollection
@@ -30,36 +25,14 @@ module Suma
       @schema_name_to_docs[schema_name]
     end
 
-    def process_schemas(schemas, klass)
-      schemas.each do |config_schema|
-        process_schema(config_schema, klass)
-      end
-    end
-
-    def process_schema(config_schema, klass)
-      s = ExpressSchema.new(
-        id: config_schema.id, path: config_schema.path.to_s,
-        output_path: @output_path_schemas.to_s
-      )
-
-      doc = klass.new(
-        schema: s, output_path: @output_path_docs.join(s.id),
-      )
-
-      @docs[s.id] = doc
-      @schemas[s.id] = s
-      @schema_name_to_docs[s.id] = doc
-    end
-
     def finalize
-      process_schemas(@config.schemas, SchemaAttachment)
-
-      manifest_entry = @manifest.lookup_schemas_only
+      process_schemas(@config.schemas, SchemaTemplate::Plain)
 
-      manifest_entry.each do |entry|
+      schemas_only_entries = ManifestTraverser.new(@manifest).find_schemas_only
+      schemas_only_entries.each do |entry|
         next unless entry.schema_config
 
-        process_schemas(entry.schema_config.schemas, SchemaDocument)
+        process_schemas(entry.schema_config.schemas, SchemaTemplate::Document)
       end
     end
 
@@ -67,15 +40,38 @@ module Suma
       finalize
 
       exporter = SchemaExporter.new(
-        schemas: @config.schemas,
+        schemas: schemas.values,
         output_path: @output_path_schemas,
         options: { annotations: false },
       )
       exporter.export
 
-      docs.each_pair do |_schema_id, entry|
-        entry.compile
+      docs.each_pair do |_schema_id, compiler|
+        compiler.compile
       end
     end
+
+    private
+
+    def process_schemas(schemas, template_class)
+      schemas.each { |s| process_schema(s, template_class) }
+    end
+
+    def process_schema(config_schema, template_class)
+      express = ExpressSchema.new(
+        id: config_schema.id, path: config_schema.path.to_s,
+        output_path: @output_path_schemas.to_s
+      )
+
+      compiler = SchemaCompiler.new(
+        schema: express,
+        output_path: @output_path_docs.join(express.id),
+        template: template_class.new(express.id),
+      )
+
+      @docs[express.id] = compiler
+      @schemas[express.id] = express
+      @schema_name_to_docs[express.id] = compiler
+    end
   end
 end

data/lib/suma/schema_comparer.rb

@@ -2,8 +2,6 @@
 
 require "fileutils"
 require "tmpdir"
-require_relative "eengine/wrapper"
-require_relative "eengine_converter"
 
 module Suma
   class SchemaComparer
@@ -37,7 +35,10 @@ module Suma
         return nil
       end
 
-      raise Suma::CompilationError, "XML output not found" unless result[:xml_path]
+      unless result[:xml_path]
+        raise Suma::CompilationError,
+              "XML output not found"
+      end
 
       convert_to_change_yaml(result[:xml_path], out_dir)
     ensure

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,22 +1,22 @@
 # frozen_string_literal: true
 
-require_relative "express_schema"
-require_relative "utils"
 require "fileutils"
 
 module Suma
-  # SchemaExporter exports EXPRESS schemas from a manifest
-  # with configurable options for annotations and ZIP packaging
+  # Exports EXPRESS schemas to a directory, with optional ZIP packaging.
+  #
+  # Pure sink: the exporter accepts already-loaded +Suma::ExpressSchema+
+  # instances and writes their content to disk. Construction of those
+  # instances (with the right +output_path+ and +is_standalone_file+
+  # flags) is the caller's responsibility — the exporter does not
+  # reach across the seam to inspect manifest entries or classify
+  # schema types itself.
+  #
+  # This is a deep module: a small interface (one +export+ method, one
+  # option hash) backed by save_exp + zip packaging. The CLI and
+  # SchemaCollection adapters construct ExpressSchema instances; the
+  # exporter never inspects their shape.
   class SchemaExporter
-    CATEGORY_MAP = {
-      ExpressSchema::Type::RESOURCE => "resources",
-      ExpressSchema::Type::MODULE_ARM => "modules",
-      ExpressSchema::Type::MODULE_MIM => "modules",
-      ExpressSchema::Type::BUSINESS_OBJECT_MODEL => "business_object_models",
-      ExpressSchema::Type::CORE_MODEL => "core_model",
-      ExpressSchema::Type::STANDALONE => ".",
-    }.freeze
-
     attr_reader :schemas, :output_path, :options
 
     def initialize(schemas:, output_path:, options: {})
@@ -46,38 +46,10 @@ module Suma
 
     def export_to_directory(schemas)
       schemas.each do |schema|
-        export_single_schema(schema)
-      end
-    end
-
-    def export_single_schema(schema)
-      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,
-      )
-
-      express_schema.save_exp(with_annotations: options[:annotations])
-    end
-
-    def determine_output_path(schema, is_standalone)
-      if is_standalone
-        output_path.to_s
-      else
-        category = categorize_schema(schema)
-        output_path.join(category).to_s
+        schema.save_exp(with_annotations: options[:annotations])
       end
     end
 
-    def categorize_schema(schema)
-      type = ExpressSchema::Type.classify(id: schema.id, path: schema.path)
-      CATEGORY_MAP.fetch(type, "standalone")
-    end
-
     # rubocop:disable Metrics/MethodLength
     def create_zip_archive
       require "zip"

data/lib/suma/schema_manifest_generator.rb

@@ -2,13 +2,13 @@
 
 require "yaml"
 require "pathname"
-require_relative "utils"
 
 module Suma
   class SchemaManifestGenerator
     YAML_FILE_EXTENSIONS = [".yaml", ".yml"].freeze
 
-    def initialize(metanorma_manifest_file, schema_manifest_file, exclude_paths: nil)
+    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
@@ -27,9 +27,15 @@ module Suma
     private
 
     def validate_inputs
-      raise Errno::ENOENT, "Specified file `#{@metanorma_manifest_file}` not found." unless File.exist?(@metanorma_manifest_file)
+      unless File.exist?(@metanorma_manifest_file)
+        raise Errno::ENOENT,
+              "Specified file `#{@metanorma_manifest_file}` not found."
+      end
 
-      raise ArgumentError, "Specified path `#{@metanorma_manifest_file}` is not a file." unless File.file?(@metanorma_manifest_file)
+      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))
@@ -53,7 +59,8 @@ module Suma
       all_schemas = { "schemas" => {} }
 
       manifest_files.each do |file|
-        schemas_file_path = File.expand_path(file.gsub("collection.yml", "schemas.yaml"))
+        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}"
@@ -83,7 +90,8 @@ module Suma
       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))
+        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)),

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