suma 0.2.6 → 0.3.0

data/lib/suma/register_manifest_generator.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+require "expressir"
+require "glossarist"
+
+module Suma
+  # Generates a Glossarist v3 register.yaml from an EXPRESS schema manifest.
+  #
+  # The schema manifest (schemas-smrl-part-2.yml) is the single source of
+  # truth for schema identities and paths. This class reads it, classifies
+  # each schema by type (resource/module), and emits a register.yaml with
+  # hierarchical sections and human-readable names.
+  #
+  # Architecture:
+  #   - Classification: delegates to ExpressSchema::Type (DRY)
+  #   - Naming: delegates to SchemaNaming (OCP — extend naming without
+  #     touching this class)
+  #   - Sections: built from Glossarist::Section models (model-driven)
+  #   - URN semantics: delegates to Suma::Urn (OCP)
+  #
+  # @example
+  #   generator = RegisterManifestGenerator.new(
+  #     "schemas-smrl-part-2.yml",
+  #     urn: "urn:iso:std:iso:10303:-2:ed-2:en:tech:*",
+  #     id: "iso10303-2-express",
+  #     ref: "ISO 10303-2 EXPRESS Concepts",
+  #   )
+  #   generator.generate  # writes register.yaml
+  class RegisterManifestGenerator
+    DEFAULT_OWNER = "ISO/TC 184/SC 4"
+    DEFAULT_STATUS = "current"
+    DEFAULT_ORDERING = "systematic"
+    DEFAULT_SCHEMA_TYPE = "glossarist"
+    DEFAULT_SCHEMA_VERSION = "3"
+
+    # @param schema_manifest_file [String] path to schemas-smrl-part-2.yml
+    # @param output_path [String] directory to write register.yaml
+    # @param urn [String] base URN for the dataset
+    # @param id [String] dataset identifier
+    # @param ref [String] human-readable reference label
+    # @param language_code [String] language for section names
+    # @param owner [String] dataset owner organisation
+    def initialize(schema_manifest_file, output_path, urn:, id:, ref:,
+                   language_code: "eng", owner: DEFAULT_OWNER)
+      @schema_manifest_file = File.expand_path(schema_manifest_file)
+      @output_path = output_path
+      @urn = Suma::Urn.new(urn)
+      @id = id
+      @ref = ref
+      @language_code = language_code
+      @owner = owner
+    end
+
+    # Generate and write register.yaml.
+    #
+    # @return [Glossarist::DatasetRegister] the generated register
+    def generate
+      validate_inputs
+      schemas = load_schemas
+      register = build_register(schemas)
+
+      FileUtils.mkdir_p(@output_path)
+      output_file = File.join(@output_path, "register.yaml")
+      File.write(output_file, register.to_yaml)
+      Utils.log "Generated register.yaml: #{output_file}"
+      Utils.log "  #{schemas.length} schemas in #{register.sections.length} categories"
+
+      register
+    end
+
+    private
+
+    # Verify that the manifest path exists, is a regular file, and contains
+    # at least one schema entry. Called from {#generate} so both the CLI
+    # shell and direct construction get the same validation behavior.
+    #
+    # @raise [Errno::ENOENT] when the manifest path is missing or not a file
+    # @raise [ArgumentError] when the manifest is empty
+    def validate_inputs
+      unless File.exist?(@schema_manifest_file)
+        raise Errno::ENOENT, "Specified SCHEMA_MANIFEST_FILE " \
+                             "`#{@schema_manifest_file}` not found."
+      end
+      unless File.file?(@schema_manifest_file)
+        raise Errno::ENOENT, "Specified SCHEMA_MANIFEST_FILE " \
+                             "`#{@schema_manifest_file}` is not a file."
+      end
+    end
+
+    # Load all schemas from the manifest file as SchemaManifestEntry models.
+    #
+    # @return [Array<Expressir::SchemaManifestEntry>]
+    def load_schemas
+      manifest = Expressir::SchemaManifest.from_file(@schema_manifest_file)
+      schemas = manifest.schemas.sort_by { |s| s.id.downcase }
+      if schemas.empty?
+        raise ArgumentError, "No schemas found in manifest " \
+                             "`#{@schema_manifest_file}`."
+      end
+      schemas
+    end
+
+    # Build a fully-populated DatasetRegister model.
+    #
+    # @param schemas [Array<Expressir::SchemaManifestEntry>]
+    # @return [Glossarist::DatasetRegister]
+    def build_register(schemas)
+      Glossarist::DatasetRegister.new(
+        schema_type: DEFAULT_SCHEMA_TYPE,
+        schema_version: DEFAULT_SCHEMA_VERSION,
+        id: @id,
+        ref: @ref,
+        urn: @urn.to_s,
+        urn_aliases: @urn.aliases,
+        status: DEFAULT_STATUS,
+        owner: @owner,
+        languages: [@language_code],
+        ordering: DEFAULT_ORDERING,
+        sections: build_sections(schemas),
+      )
+    end
+
+    # Build a list of top-level sections, one per category, in
+    # SchemaCategory::ALL declaration order. Categories with no
+    # schemas are omitted.
+    #
+    # @param schemas [Array<Expressir::SchemaManifestEntry>]
+    # @return [Array<Glossarist::Section>]
+    def build_sections(schemas)
+      groups = schemas.group_by do |s|
+        SchemaCategory.for_schema(id: s.id, path: s.path)
+      end
+
+      SchemaCategory::ALL.filter_map do |category|
+        children = groups[category] || []
+        next if children.empty?
+
+        Glossarist::Section.new(
+          id: category.id,
+          names: { @language_code => category.label },
+          children: children.map { |s| build_section(s) },
+        )
+      end
+    end
+
+    # Build a single leaf section from a schema descriptor.
+    #
+    # @param schema [Expressir::SchemaManifestEntry]
+    # @return [Glossarist::Section]
+    def build_section(schema)
+      Glossarist::Section.new(
+        id: schema.id,
+        names: {
+          @language_code => SchemaNaming.prefixed_name(
+            schema.id, path: schema.path
+          ),
+        },
+      )
+    end
+  end
+end

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
 
@@ -73,9 +46,32 @@ module Suma
       )
       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,11 @@
 # 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
   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: {})
@@ -68,16 +57,11 @@ module Suma
       if is_standalone
         output_path.to_s
       else
-        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
 
-    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)),