suma 0.2.6 → 0.4.0

data/lib/suma/cli/reformat.rb

@@ -1,88 +1,63 @@
 # frozen_string_literal: true
 
 require "thor"
-require_relative "../thor_ext"
 
 module Suma
   module Cli
-    # Reformat command for reformatting EXPRESS files
+    # Reformat command for reformatting EXPRESS files.
+    #
+    # Thin Thor adapter around Suma::ExpressReformatter: argument
+    # parsing, file discovery, and read/transform/write. The content
+    # transformation itself lives in the deep module and is tested
+    # independently.
     class Reformat < Thor
-      desc "reformat EXPRESS_FILE_PATH",
-           "Reformat EXPRESS files"
+      desc "reformat EXPRESS_FILE_PATH", "Reformat EXPRESS files"
       option :recursive, type: :boolean, default: false, aliases: "-r",
                          desc: "Reformat EXPRESS files under the specified " \
                                "path recursively"
 
-      def reformat(express_file_path) # rubocop:disable Metrics/AbcSize
-        if File.file?(express_file_path)
-          unless File.exist?(express_file_path)
-            raise Errno::ENOENT, "Specified EXPRESS file " \
-                                 "`#{express_file_path}` not found."
-          end
-
-          if File.extname(express_file_path) != ".exp"
-            raise ArgumentError, "Specified file `#{express_file_path}` is " \
-                                 "not an EXPRESS file."
-          end
-
-          exp_files = [express_file_path]
-        elsif options[:recursive]
-          exp_files = Dir.glob("#{express_file_path}/**/*.exp")
-        else
-          exp_files = Dir.glob("#{express_file_path}/*.exp")
-        end
-
-        if exp_files.empty?
-          raise Errno::ENOENT, "No EXPRESS files found in " \
-                               "`#{express_file_path}`."
-        end
-
-        run(exp_files)
+      def reformat(express_file_path)
+        files = discover_files(express_file_path)
+        ensure_files_found!(files, express_file_path)
+        process_files(files)
       end
 
       private
 
-      def run(exp_files)
-        exp_files.each do |exp_file|
-          reformat_exp(exp_file)
-        end
-      end
+      def discover_files(path)
+        return [path] if File.file?(path)
+        return Dir.glob("#{path}/**/*.exp") if options[:recursive]
 
-      def reformat_exp(file) # rubocop:disable Metrics/AbcSize
-        # Read the file content
-        file_content = File.read(file)
-
-        # Extract all comments between '(*"' and '\n*)'
-        # Avoid incorrect selection of some comment blocks
-        # containing '(*text*)' inside
-        comments = file_content.scan(/\(\*"(.*?)\n\*\)/m).map(&:first)
-
-        if comments.any?
-          content_without_comments = file_content.gsub(/\(\*".*?\n\*\)/m, "")
-
-          # remove extra newlines
-          new_content = content_without_comments.gsub(/(\n\n+)/, "\n\n")
-          # Add '(*"' and '\n*)' to enclose the comment block
-          new_comments = comments.map { |c| "(*\"#{c}\n*)" }.join("\n\n")
-          # Append the comments to the end of the file
-          new_content = "#{new_content}\n\n#{new_comments}\n"
+        Dir.glob("#{path}/*.exp")
+      end
 
-          # Compare the changes between the original content with the modified
-          # content, if the changes are just whitespaces, skip modifying the
-          # file
-          if file_content.gsub(/(\n+)/, "\n") == new_content.gsub(/(\n+)/, "\n")
-            puts "No changes made to #{file}"
-            return
+      def ensure_files_found!(files, path)
+        if File.file?(path)
+          unless File.extname(path) == ".exp"
+            raise ArgumentError,
+                  "Specified file `#{path}` is not an EXPRESS file."
           end
-
-          update_exp(file, new_content)
+        elsif !File.exist?(path)
+          raise Errno::ENOENT,
+                "Specified EXPRESS file `#{path}` not found."
         end
+        return unless files.empty?
+
+        raise Errno::ENOENT, "No EXPRESS files found in `#{path}`."
+      end
+
+      def process_files(files)
+        files.each { |file| reformat_one(file) }
       end
 
-      def update_exp(file, content)
-        # Write the modified content to a new file
-        File.write(file, content)
-        puts "Reformatted EXPRESS file and saved to #{file}"
+      def reformat_one(file)
+        result = ExpressReformatter.call(File.read(file))
+        if result.changed?
+          File.write(file, result.content)
+          puts "Reformatted EXPRESS file and saved to #{file}"
+        else
+          puts "No changes made to #{file}"
+        end
       end
     end
   end

data/lib/suma/cli/validate.rb

@@ -4,16 +4,23 @@ require "thor"
 
 module Suma
   module Cli
-    # Main validate command that groups the validation subcommands
+    # Validate command group. Thin Thor adapter around
+    # +Suma::LinkValidation+ — argument parsing, result presentation.
+    # All orchestration (manifest loading, link extraction, schema
+    # indexing, validation) lives in the deep module and is reachable
+    # from specs without invoking Thor.
     class Validate < Thor
       desc "links SCHEMAS_FILE DOCUMENTS_PATH [OUTPUT_FILE]",
            "Extract and validate express links without creating intermediate file"
-      def links(*args)
-        require_relative "validate_links"
-
-        # Forward the command to ValidateLinks
-        links = Cli::ValidateLinks.new
-        links.extract_and_validate(*args)
+      def links(schemas_file = "schemas-srl.yml",
+                documents_path = "documents",
+                output_file = "validation_results.txt")
+        result = LinkValidation.new(
+          schemas_file: schemas_file,
+          documents_path: documents_path,
+          output_file: output_file,
+        ).call
+        puts LinkValidation.generate_summary(result)
       end
     end
   end

data/lib/suma/cli/validate_links.rb

@@ -1,170 +1,24 @@
 # frozen_string_literal: true
 
 require "thor"
-require_relative "../utils"
-require_relative "../link_validator"
-require "expressir"
 
 module Suma
   module Cli
+    # Deprecated: prefer +Cli::Validate#links+ (the +suma validate links+
+    # subcommand). This class is retained as a backwards-compat entry
+    # point — all orchestration now lives in +Suma::LinkValidation+.
     class ValidateLinks < Thor
       desc "extract_and_validate SCHEMAS_FILE DOCUMENTS_PATH [OUTPUT_FILE]",
            "Extract and validate express links without creating intermediate file"
       def extract_and_validate(schemas_file = "schemas-srl.yml",
-                              documents_path = "documents",
-                              output_file = "validation_results.txt")
-        load_dependencies
-        paths = prepare_file_paths(schemas_file, documents_path, output_file)
-
-        schemas_config = load_schemas_config(paths[:schemas_file])
-        exp_files = collect_schema_paths(schemas_config, paths[:schemas_file_rel])
-        adoc_files = find_adoc_files(paths[:documents_path])
-
-        all_files = adoc_files + exp_files
-        display_file_counts(adoc_files, exp_files)
-
-        links_by_file = extract_links(all_files)
-
-        repo = load_express_schemas(schemas_config)
-        index = SchemaIndex.new(repo)
-        unresolved = LinkValidator.new(index).validate(links_by_file)
-
-        write_validation_results(paths[:output_file], paths[:output_file_rel],
-                                 unresolved, links_by_file)
-      end
-
-      private
-
-      def load_dependencies
-        require "expressir"
-        require "ruby-progressbar"
-        require "pathname"
-      end
-
-      def prepare_file_paths(schemas_file, documents_path, output_file)
-        schemas_file_path = Pathname.new(schemas_file).expand_path
-        documents_path_exp = Pathname.new(documents_path).expand_path
-        output_file_path = Pathname.new(output_file).expand_path
-
-        schemas_file_rel = Pathname.new(schemas_file_path).relative_path_from(Pathname.pwd).to_s
-        documents_path_rel = Pathname.new(documents_path_exp).relative_path_from(Pathname.pwd).to_s
-        output_file_rel = Pathname.new(output_file_path).relative_path_from(Pathname.pwd).to_s
-
-        puts "Extracting and validating express links using schemas from #{schemas_file_rel}..."
-        puts "Looking for documents in #{documents_path_rel}..."
-
-        {
-          schemas_file: schemas_file_path,
-          schemas_file_rel: schemas_file_rel,
-          documents_path: documents_path_exp,
-          documents_path_rel: documents_path_rel,
-          output_file: output_file_path,
-          output_file_rel: output_file_rel,
-        }
-      end
-
-      def load_schemas_config(schemas_file_path)
-        schemas_config = Expressir::SchemaManifest.from_yaml(File.read(schemas_file_path))
-        schemas_config.set_initial_path(schemas_file_path.to_s)
-        schemas_config
-      rescue StandardError => e
-        raise Suma::Error, "Error loading schemas file: #{e.message}"
-      end
-
-      def collect_schema_paths(schemas_config, schemas_file_rel)
-        exp_files = schemas_config.schemas.filter_map(&:path)
-        puts "Found #{exp_files.size} EXPRESS schema files from #{schemas_file_rel}"
-        exp_files
-      end
-
-      def find_adoc_files(documents_path)
-        Dir.glob(documents_path.join("**", "*.adoc").to_s)
-      end
-
-      def display_file_counts(adoc_files, exp_files)
-        puts "Found #{adoc_files.size} AsciiDoc files and #{exp_files.size} EXPRESS files"
-      end
-
-      def create_progress_bar(title, total)
-        ProgressBar.create(
-          title: title,
-          total: total,
-          format: "%t: [%B] %p%% %c/%C %e",
-          progress_mark: "=",
-          remainder_mark: " ",
-          length: 80,
-        )
-      end
-
-      def extract_links(files)
-        links_by_file = {}
-        link_count = 0
-
-        progress = create_progress_bar("Processing files", files.size)
-
-        files.each do |file|
-          progress.increment
-          begin
-            content = File.read(file)
-            express_links = content.scan(/<<express:([^,>]+)(?:,[^>]+)?>>/).flatten.uniq
-
-            if express_links.any?
-              links_by_file[file] = express_links
-              link_count += express_links.size
-            end
-          rescue StandardError => e
-            puts "\nWarning: Could not read file #{file}: #{e.message}"
-          end
-        end
-
-        puts "\nExtracted #{link_count} unique express links from #{links_by_file.size} files"
-        links_by_file
-      end
-
-      def load_express_schemas(schemas_config)
-        schema_paths = {}
-        schemas_config.schemas.each { |s| schema_paths[s.id] = s.path }
-
-        puts "Loading #{schema_paths.size} EXPRESS schemas for validation..."
-
-        loading_progress = create_progress_bar("Loading schemas", schema_paths.size)
-
-        begin
-          repo = Expressir::Express::Parser.from_files(schema_paths.values) do |filename, _schemas, error|
-            loading_progress.increment
-            puts "\nWarning: Error loading schema #{filename}: #{error.message}" if error
-          end
-
-          puts "Successfully loaded #{repo.schemas.size} schemas"
-          repo
-        rescue StandardError => e
-          raise Suma::Error, "Error loading schemas: #{e.message}"
-        end
-      end
-
-      def write_validation_results(output_file_path, output_file_rel,
-  unresolved_links, links_by_file)
-        total_links = links_by_file.values.sum(&:size)
-
-        results = []
-        results << "Validation complete. Checked #{total_links} links."
-
-        if unresolved_links.empty?
-          results << "✅ All links resolved successfully!"
-        else
-          results << "❌ Found #{unresolved_links.size} unresolved links:"
-          unresolved_links.each do |issue|
-            results << "#{issue.file}:#{issue.line} - <<express:#{issue.link}>> - #{issue.reason}"
-          end
-        end
-
-        begin
-          File.write(output_file_path, results.join("\n"))
-          puts "Validation results written to #{output_file_rel}"
-        rescue StandardError => e
-          puts "Error writing to output file: #{e.message}"
-          puts results
-        end
+                               documents_path = "documents",
+                               output_file = "validation_results.txt")
+        result = LinkValidation.new(
+          schemas_file: schemas_file,
+          documents_path: documents_path,
+          output_file: output_file,
+        ).call
+        puts LinkValidation.generate_summary(result)
       end
     end
   end

data/lib/suma/cli.rb

@@ -1,147 +1,18 @@
 # frozen_string_literal: true
 
-require "thor"
-require_relative "thor_ext"
-require_relative "cli/validate"
-require_relative "cli/check_svg_quality"
-require "expressir"
-require "expressir/cli"
-
 module Suma
   module Cli
-    # Core command class for handling CLI entrypoints
-    class Core < Thor
-      extend ThorExt::Start
-
-      desc "build METANORMA_SITE_MANIFEST",
-           "Build collection specified in site manifest (`metanorma*.yml`)"
-      option :compile, type: :boolean, default: true,
-                       desc: "Compile or skip compile of collection"
-      option :schemas_all_path, type: :string, aliases: "-s",
-                                desc: "Generate file that contains all " \
-                                      "schemas in the collection."
-      def build(_site_manifest)
-        require_relative "cli/build"
-        Cli::Build.start
-      end
-
-      desc "generate-schemas METANORMA_MANIFEST_FILE SCHEMA_MANIFEST_FILE",
-           "Generate EXPRESS schema manifest file from Metanorma site manifest"
-      option :exclude_paths, type: :string, default: nil, aliases: "-e",
-                             desc: "Exclude schemas paths by pattern " \
-                                   "(e.g. `*_lf.exp`)"
-      def generate_schemas(_metanorma_manifest_file, _schema_manifest_file)
-        require_relative "cli/generate_schemas"
-        Cli::GenerateSchemas.start
-      end
-
-      desc "reformat EXPRESS_FILE_PATH",
-           "Reformat EXPRESS files"
-      option :recursive, type: :boolean, default: false, aliases: "-r",
-                         desc: "Reformat EXPRESS files under the specified " \
-                               "path recursively"
-      def reformat(_express_file_path)
-        require_relative "cli/reformat"
-        Cli::Reformat.start
-      end
-
-      desc "extract-terms SCHEMA_MANIFEST_FILE GLOSSARIST_OUTPUT_PATH",
-           "Extract terms from SCHEMA_MANIFEST_FILE into " \
-           "Glossarist v2 format"
-      option :language_code, type: :string, default: "eng", aliases: "-l",
-                             desc: "Language code for the Glossarist"
-      def extract_terms(_schema_manifest_file, _glossarist_output_path)
-        require_relative "cli/extract_terms"
-        Cli::ExtractTerms.start
-      end
-
-      desc "convert-jsdai XML_FILE IMAGE_FILE OUTPUT_DIR",
-           "Convert JSDAI XML and image files to SVG and EXP files"
-      def convert_jsdai(_xml_file, _image_file, _output_dir)
-        require_relative "cli/convert_jsdai"
-        Cli::ConvertJsdai.start
-      end
-
-      desc "export *FILES",
-           "Export EXPRESS schemas from manifest files or " \
-           "standalone EXPRESS files"
-      option :output, type: :string, aliases: "-o", required: true,
-                      desc: "Output directory path"
-      option :annotations, type: :boolean, default: false,
-                           desc: "Include annotations (remarks/comments)"
-      option :zip, type: :boolean, default: false,
-                   desc: "Create ZIP archive of exported schemas"
-      def export(*_files)
-        require_relative "cli/export"
-        Cli::Export.start
-      end
-
-      desc "compare TRIAL_SCHEMA REFERENCE_SCHEMA",
-           "Compare EXPRESS schemas using eengine and generate Change YAML"
-      option :output, type: :string, aliases: "-o",
-                      desc: "Output Change YAML file path"
-      option :version, type: :string, aliases: "-v", required: true,
-                       desc: "Version number for this change version"
-      option :mode, type: :string, default: "resource",
-                    desc: "Schema comparison mode (resource/module)"
-      option :trial_stepmod, type: :string,
-                             desc: "Override auto-detected trial repo root"
-      option :reference_stepmod, type: :string,
-                                 desc: "Override auto-detected reference repo root"
-      option :verbose, type: :boolean, default: false,
-                       desc: "Enable verbose output"
-      def compare(_trial_schema, _reference_schema)
-        require_relative "cli/compare"
-        Cli::Compare.start
-      end
-
-      desc "validate SUBCOMMAND ...ARGS", "Validate express documents"
-      subcommand "validate", Cli::Validate
-
-      desc "check_svg_quality [PATH]",
-           "Check SVG quality and sort by severity (critical files first)"
-      option :pattern, type: :string, default: Cli::CheckSvgQuality::DEFAULT_PATTERN,
-                       desc: "Glob pattern for finding SVG files"
-      option :profile, type: :string,
-                       default: Cli::CheckSvgQuality::DEFAULT_PROFILE,
-                       desc: "Validation profile to use (metanorma, svg_1_2_rfc, etc.)"
-      option :format, type: :string, default: "terminal",
-                      desc: "Output format: terminal, yaml, json"
-      option :output, type: :string, aliases: "-o",
-                      desc: "Output file path"
-      option :min_errors, type: :numeric,
-                          desc: "Minimum error count threshold"
-      option :limit, type: :numeric, default: nil,
-                     desc: "Maximum number of files to show (default: unlimited)"
-      option :sort, type: :string, default: "errors",
-                    desc: "Sort by: errors (most errors first) or quality (lowest scores first)"
-      option :progress, type: :boolean, default: false,
-                        desc: "Show progress during processing"
-      option :summary_only, type: :boolean, default: false,
-                            desc: "Show only summary"
-      def check_svg_quality(path = Cli::CheckSvgQuality::DATA_PATH)
-        require_relative "cli/check_svg_quality"
-
-        analyzer = Cli::CheckSvgQuality.new(
-          pattern: options[:pattern],
-          profile: options[:profile],
-          format: options[:format],
-          output: options[:output],
-          min_errors: options[:min_errors],
-          summary_only: options[:summary_only],
-          progress: options[:progress],
-          limit: options[:limit],
-          sort: options[:sort],
-        )
-        analyzer.run(path)
-      end
-
-      desc "expressir SUBCOMMAND ...ARGS", "Expressir commands"
-      subcommand "expressir", Expressir::Cli
-
-      def self.exit_on_failure?
-        true
-      end
-    end
+    autoload :Core,             "suma/cli/core"
+    autoload :Build,            "suma/cli/build"
+    autoload :CheckSvgQuality,  "suma/cli/check_svg_quality"
+    autoload :Compare,          "suma/cli/compare"
+    autoload :ConvertJsdai,     "suma/cli/convert_jsdai"
+    autoload :Export,           "suma/cli/export"
+    autoload :ExtractTerms,     "suma/cli/extract_terms"
+    autoload :GenerateRegister, "suma/cli/generate_register"
+    autoload :GenerateSchemas,  "suma/cli/generate_schemas"
+    autoload :Reformat,         "suma/cli/reformat"
+    autoload :Validate,         "suma/cli/validate"
+    autoload :ValidateLinks,    "suma/cli/validate_links"
   end
 end

data/lib/suma/collection_config.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "utils"
 require "lutaml/model"
-require_relative "collection_manifest"
 require "metanorma"
 
 module Suma

data/lib/suma/collection_manifest.rb

@@ -4,6 +4,13 @@ require "metanorma"
 require "expressir"
 
 module Suma
+  # Pure data model for one node of a Metanorma collection manifest.
+  #
+  # CollectionManifest extends the Metanorma config manifest to add the
+  # `schemas_only` flag and an `entry` sub-collection. It owns only state:
+  # attributes, YAML mappings, and the `schema_config` slot populated by
+  # SchemaDiscovery. Tree-walking logic lives in ManifestTraverser; schema
+  # I/O lives in SchemaDiscovery.
   class CollectionManifest < Metanorma::Collection::Config::Manifest
     attribute :schemas_only, Lutaml::Model::Type::Boolean
     attribute :entry, CollectionManifest, collection: true,
@@ -32,115 +39,5 @@ module Suma
     def docref_from_yaml(model, value)
       model.entry = CollectionManifest.from_yaml(value.to_yaml)
     end
-
-    # Recursively exports schema configuration by traversing collection manifests.
-    #
-    # This method builds an EXPRESS Schema Manifest (Expressir::SchemaManifest) by:
-    # 1. Starting with an empty or existing Expressir::SchemaManifest
-    # 2. Recursively traversing child entries to collect schemas
-    # 3. Using Expressir::SchemaManifest#concat to combine manifests
-    #
-    # The actual schema manifest operations (creation, concatenation, serialization)
-    # are handled by Expressir's SchemaManifest class, keeping the logic DRY.
-    #
-    # @param path [String] Base path for resolving relative schema paths
-    # @return [Expressir::SchemaManifest] Combined schema manifest
-    def export_schema_config(path)
-      export_config = @schema_config || Expressir::SchemaManifest.new
-      return export_config unless entry
-
-      entry.each do |x|
-        child_config = x.export_schema_config(path)
-        # Use Expressir's concat method to combine schema manifests
-        export_config.concat(child_config) if child_config
-      end
-
-      export_config
-    end
-
-    def lookup_schemas_only
-      results = entry.select(&:schemas_only)
-      results << self if schemas_only
-      results
-    end
-
-    def process_entry(schema_output_path)
-      return [self] unless entry
-
-      ret = entry.each_with_object([]) do |e, m|
-        add = e.expand_schemas_only(schema_output_path)
-        m.concat(add)
-      end
-
-      self.entry = ret
-      [self]
-    end
-
-    def expand_schemas_only(schema_output_path)
-      return process_entry(schema_output_path) unless file
-
-      update_schema_config
-
-      return process_entry(schema_output_path) unless schemas_only
-
-      # If we are going to keep the schemas-only file and compile it, we can't
-      # have it showing up in output.
-      self.index = false
-
-      [self, added_collection_manifest(schema_output_path)]
-    end
-
-    def remove_schemas_only_sources
-      ret = entry.each_with_object([]) do |e, m|
-        e.schemas_only or m << e
-      end
-      self.entry = ret
-    end
-
-    def entries(schema_output_path)
-      @schema_config.schemas.map do |schema|
-        fname = [File.basename(schema.path, ".exp"), ".xml"].join
-
-        CollectionManifest.new(
-          identifier: schema.id,
-          title: schema.id,
-          file: File.join(schema_output_path, schema.id, "doc_#{fname}"),
-          # schema_source: schema.path
-        )
-      end
-    end
-
-    def added_collection_manifest(schema_output_path)
-      doc = CollectionConfig.from_file(file)
-      doc_id = doc.bibdata.id
-
-      # we need to separate this file from the following new entries
-      added = CollectionManifest.new(
-        title: "Collection",
-        type: "collection",
-        identifier: "#{identifier}_",
-      )
-
-      added.entry = [
-        CollectionManifest.new(
-          title: doc_id,
-          type: "document",
-          entry: entries(schema_output_path),
-        ),
-      ]
-
-      added
-    end
-
-    def update_schema_config
-      # If there is collection.yml, this is a document collection, we process
-      # schemas.yaml.
-      if File.basename(file) == "collection.yml"
-        schemas_yaml_path = File.join(File.dirname(file), "schemas.yaml")
-        if schemas_yaml_path && File.exist?(schemas_yaml_path)
-          @schema_config = Expressir::SchemaManifest.from_file(schemas_yaml_path)
-        end
-      end
-    end
   end
 end

data/lib/suma/eengine/wrapper.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "open3"
-require_relative "errors"
 
 module Suma
   module Eengine

data/lib/suma/eengine.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Suma
+  module Eengine
+    autoload :Errors,  "suma/eengine/errors"
+    autoload :Wrapper, "suma/eengine/wrapper"
+  end
+end