suma 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 041f227f2bd35c3d90138ab621e51b9abf68206f7b295523da2827d82d6b63c7
-  data.tar.gz: f64aed0f1f4aa096d66c4c299581a2437a991fe6f522b50170b26557b81a0092
+  metadata.gz: 304c4c7a2ec03c83604a127370259b022e0102d303c4951c2d730d3681d3ad39
+  data.tar.gz: b8d9bcd807ea0aadb4f038dd58823d829d495827e4785316cb7c715e79b512cb
 SHA512:
-  metadata.gz: ac0d654f283a393c6ae620763920decec16ce2bad44c5cc5722f123bf12ee7539069e35dbbb4909f061fdb14e240f26f033d04e357cfdaff814966cc5f185f8b
-  data.tar.gz: a2a4ca844993d87bc534c77d99e5767aa0f6f86b1f028a15c9a9387ddc761303fcef390a3fe98dce907580b8da1657bb83f96d7c4d0cdd0e03f59d690a1c688f
+  metadata.gz: 21977b339cd0a16936940c50de766ba2130f3dc46df7965db1de04360a65c1d685e1b59786e9a49548d0e79f1d20befcf732a66482b6e8b8793a547bd557d28e
+  data.tar.gz: bd1122e6d73a9a22b3a3830c7cf654c909a541e7c332808349b15bb469f772338ad7a84a25590f1c8d13b46b84d8399673fa2f43f16f5d943e0e1f8e2469a08a

data/.gitignore

@@ -13,11 +13,8 @@
 .ruby-version
 Gemfile.lock
 
-# local planning scratch directories (not for commit)
-/TODO.clean/
-/TODO.cleanup/
-/TODO.refactor/
-/TODO.remaining/
+# local planning scratch directories and files (not for commit)
+/TODO*
 
 # vendored gems (use Gemfile / Gemfile.lock elsewhere)
 /*.gem

data/README.adoc

@@ -1065,34 +1065,31 @@ examples demonstrate common usage patterns.
 require 'suma'
 
 # Build a collection with default settings
-Suma::Processor.run(
+Suma::Processor.new(
   metanorma_yaml_path: "metanorma-srl.yml",
   schemas_all_path: "schemas-srl.yml",
   compile: true,
   output_directory: "_site"
-)
+).run
 
 # Generate schema listing without compilation
-Suma::Processor.run(
+Suma::Processor.new(
   metanorma_yaml_path: "metanorma-srl.yml",
   schemas_all_path: "schemas-srl.yml",
-  compile: false,
-  output_directory: "_site"
-)
+  compile: false
+).run
 ----
 
-=== Working with schema configurations
+=== Working with schema manifests
+
+Schema manifests are loaded via `Expressir::SchemaManifest`:
 
 [source,ruby]
 ----
 require 'suma'
 
-# Load schemas using SchemaConfig
 schemas_file_path = "schemas-srl.yml"
-schemas_config = Suma::SchemaConfig::Config.from_yaml(IO.read(schemas_file_path))
-
-# Set the initial path to resolve relative paths
-schemas_config.set_initial_path(schemas_file_path)
+schemas_config = Expressir::SchemaManifest.from_file(schemas_file_path)
 
 # Access schema information
 schemas_config.schemas.each do |schema|
@@ -1101,6 +1098,67 @@ schemas_config.schemas.each do |schema|
 end
 ----
 
+=== Extracting terms
+
+[source,ruby]
+----
+require 'suma'
+
+Suma::TermExtractor.new(
+  "schemas-smrl-part-2.yml",
+  "glossarist_output",
+  urn: "urn:iso:std:iso:10303:-2:ed-2:en:tech:*",
+).call
+----
+
+=== Generating a register.yaml
+
+[source,ruby]
+----
+require 'suma'
+
+Suma::RegisterManifestGenerator.new(
+  "schemas-smrl-part-2.yml",
+  "register_output",
+  urn: "urn:iso:std:iso:10303:-2:ed-2:en:tech:*",
+  id: "iso10303-2-express",
+  ref: "ISO 10303-2 EXPRESS Concepts",
+).generate
+----
+
+=== Architecture
+
+Suma's domain is split into MECE concerns:
+
+* **Data models** (pure): `CollectionManifest`, `ExpressSchema`
+* **Value objects** (pure): `SchemaCategory`, `Urn`
+* **Services** (single concern): `ManifestTraverser`, `SchemaDiscovery`,
+  `SchemaCompiler`, `SchemaExporter`, `SchemaIndex`, `LinkValidator`,
+  `SchemaComparer`, `SchemaManifestGenerator`, `TermExtractor`,
+  `RegisterManifestGenerator`, `Processor`
+* **Renderers** (pure, composable): `SchemaTemplate::Plain`,
+  `SchemaTemplate::Document`
+
+Key invariants:
+
+* The classifier `ExpressSchema::Type.classify(id:, path:)` is the single
+  source of truth for schema type. `SchemaCategory`, `SchemaNaming`,
+  `SchemaExporter`, and `RegisterManifestGenerator` all derive from it.
+* `Urn` owns URN semantics (wildcard stripping, base/alias split, leaf
+  composition).
+* `CollectionManifest` is a pure data model; tree walking lives in
+  `ManifestTraverser`, schema I/O lives in `SchemaDiscovery`.
+* `SchemaCompiler` orchestrates one Metanorma compilation; the adoc body
+  is injected via a `SchemaTemplate::*` renderer.
+
+Code-style rules enforced throughout `lib/suma/`:
+
+* Ruby `autoload` only — no `require_relative`
+* No `send` to call private methods
+* No `instance_variable_set` / `instance_variable_get`
+* No `respond_to?` for type checking
+* `Utils.log` writes to `$stderr`; debug level gated by `SUMA_DEBUG`
+
 
 == Copyright and license
 

data/lib/suma/cli/check_svg_quality.rb

@@ -4,16 +4,19 @@ require "pathname"
 
 module Suma
   module Cli
-    # Check SVG quality using svg_conform Validator API - thin CLI wrapper
+    # Check SVG quality. Thin adapter around +Suma::SvgQuality::Scanner+:
+    # argument parsing, file discovery, sorting, filtering, output
+    # formatting. The deep scanner module owns validation orchestration
+    # and is reachable from specs without invoking Thor.
     class CheckSvgQuality
       DATA_PATH = "schemas"
       DEFAULT_PATTERN = "**/*.svg"
       DEFAULT_PROFILE = :metanorma
 
       def initialize(pattern: DEFAULT_PATTERN, profile: DEFAULT_PROFILE,
-                    format: "terminal", output: nil, min_errors: nil,
-                    summary_only: false, progress: false, limit: nil,
-                    sort: "errors")
+                     format: "terminal", output: nil, min_errors: nil,
+                     summary_only: false, progress: false, limit: nil,
+                     sort: "errors")
         @options = {
           pattern: pattern,
           profile: profile,
@@ -31,71 +34,42 @@ module Suma
         require "svg_conform"
 
         path_obj = Pathname.new(path).expand_path
-
-        # Enable progress by default when outputting to terminal
         show_progress = options[:progress] || ($stdout.tty? && !options[:output])
-        if show_progress
-          $stdout.sync = true
-          $stderr.sync = true
-        end
-
-        if path_obj.file?
-          # Single file mode - show detailed errors
-          analyze_single_file(path_obj)
-        else
-          # Directory mode - show batch report
-          svg_files = find_svg_files(path_obj)
-
-          if svg_files.empty?
-            puts "No SVG files found in #{path}"
-            return
-          end
+        sync_stdio! if show_progress
 
-          puts "🔍 Scanning #{svg_files.size} SVG files..."
-          puts
+        files = discover_files(path_obj)
+        return if files.empty?
 
-          reports = analyze_files_one_by_one(svg_files, show_progress)
-          batch_report = SvgQuality::BatchReport.new(reports)
-          sorted_report = sort_report(batch_report)
-          output_report(sorted_report)
+        if single_file?(path_obj, files)
+          print_single_report(scan_single(files.first))
+        else
+          scan_and_output(files, show_progress)
         end
       end
 
-      def analyze_single_file(path)
-        validator = SvgConform::Validator.new
-        result = validator.validate_file(path.to_s, profile: options[:profile])
-
-        puts "📄 SVG Quality Report: #{path}"
-        puts ""
-        puts "  Valid: #{result.valid? ? 'YES ✅' : 'NO ❌'}"
-        puts "  Errors: #{result.error_count}"
-        puts ""
+      private
 
-        if result.errors.any?
-          puts "  📋 Error Details"
-          puts ""
+      attr_reader :options
 
-          # Group errors by requirement_id
-          by_req = result.errors.group_by(&:requirement_id)
-
-          by_req.each do |req_id, errors|
-            puts "  #{req_id} (#{errors.size} occurrences)"
-            errors.first(5).each do |e|
-              puts "    - #{e.message}"
-            end
-            if errors.size > 5
-              puts "    ... and #{errors.size - 5} more"
-            end
-            puts ""
-          end
-        end
+      def single_file?(path_obj, files)
+        path_obj.file? && files.size == 1
       end
 
-      private
+      def scan_and_output(files, show_progress)
+        puts "🔍 Scanning #{files.size} SVG files..." if show_progress
+        batch = SvgQuality::Scanner.new(
+          profile: options[:profile],
+          progress: progress_adapter(show_progress),
+        ).scan(files)
+        output_report(sort_report(batch))
+      end
 
-      attr_reader :options
+      def sync_stdio!
+        $stdout.sync = true
+        $stderr.sync = true
+      end
 
-      def find_svg_files(path)
+      def discover_files(path)
         if path.directory?
           Pathname.glob(path.join(options[:pattern])).select(&:file?)
         elsif path.file? && path.extname == ".svg"
@@ -105,34 +79,47 @@ module Suma
         end
       end
 
-      def analyze_files_one_by_one(files, show_progress = false)
-        validator = SvgConform::Validator.new
-        reports = []
-
-        files.each_with_index do |file, index|
-          result = validator.validate_file(file.to_s,
-                                           profile: options[:profile])
-          report = SvgQuality::Report.new(file.to_s, result)
-          reports << report
-
-          if show_progress
-            tier = report.quality_tier
-            status = report.valid? ? "✅" : "❌"
-            msg = "  [#{index + 1}/#{files.size}] #{tier[:emoji]} #{report.error_count} errors #{status} #{shorten_path(file)}\n"
-            $stderr.print msg
-            $stderr.flush
-          end
+      def scan_single(path)
+        SvgQuality::Scanner.new(profile: options[:profile]).scan_file(path)
+      end
+
+      def print_single_report(report)
+        result = report
+        puts "📄 SVG Quality Report: #{result.file_path}"
+        puts ""
+        puts "  Valid: #{result.valid? ? 'YES ✅' : 'NO ❌'}"
+        puts "  Errors: #{result.error_count}"
+        puts ""
+
+        return unless result.errors.any?
+
+        puts "  📋 Error Details"
+        puts ""
+        by_req = result.errors.group_by(&:requirement_id)
+        by_req.each do |req_id, errors|
+          puts "  #{req_id} (#{errors.size} occurrences)"
+          errors.first(5).each { |e| puts "    - #{e.message}" }
+          puts "    ... and #{errors.size - 5} more" if errors.size > 5
+          puts ""
         end
+      end
+
+      def progress_adapter(enabled)
+        return SvgQuality::Scanner::NullProgress.new unless enabled
 
-        reports
+        ->(_index, _total, report) do
+          tier = report.quality_tier
+          status = report.valid? ? "✅" : "❌"
+          $stderr.print "  #{tier[:emoji]} #{report.error_count} errors " \
+                        "#{status} #{shorten_path(report.file_path)}\n"
+          $stderr.flush
+        end
       end
 
       def sort_report(batch_report)
         case options[:sort]
-        when :quality
-          batch_report.sort_by_quality
-        else
-          batch_report.sort_by_errors
+        when :quality then batch_report.sort_by_quality
+        else batch_report.sort_by_errors
         end
       end
 
@@ -140,21 +127,25 @@ module Suma
         filtered = batch_report.filter_by_min_errors(options[:min_errors])
         limited = filtered.limit(options[:limit])
 
-        formatter = case options[:format].to_sym
-                    when :json
-                      SvgQuality::Formatters::JsonFormatter.new(limited,
-                                                                output: options[:output])
-                    when :yaml
-                      SvgQuality::Formatters::YamlFormatter.new(limited,
-                                                                output: options[:output])
-                    else
-                      SvgQuality::Formatters::TerminalFormatter.new(limited,
-                                                                    output: options[:output], sort: options[:sort])
-                    end
-
+        formatter = formatter_for(limited)
         puts formatter.format
       end
 
+      def formatter_for(batch_report)
+        case options[:format].to_sym
+        when :json
+          SvgQuality::Formatters::JsonFormatter.new(batch_report,
+                                                    output: options[:output])
+        when :yaml
+          SvgQuality::Formatters::YamlFormatter.new(batch_report,
+                                                    output: options[:output])
+        else
+          SvgQuality::Formatters::TerminalFormatter.new(batch_report,
+                                                        output: options[:output],
+                                                        sort: options[:sort])
+        end
+      end
+
       def shorten_path(path)
         p = Pathname.new(path)
         if p.absolute?

data/lib/suma/cli/export.rb

@@ -1,10 +1,19 @@
 # frozen_string_literal: true
 
 require "thor"
+require "pathname"
 
 module Suma
   module Cli
-    # Export command for exporting EXPRESS schemas from a manifest
+    # Export command. Thin Thor adapter that constructs
+    # +Suma::ExpressSchema+ instances from manifest entries or
+    # standalone +.exp+ files, then delegates the actual writing to
+    # +Suma::SchemaExporter+.
+    #
+    # The schema-type → output-subdirectory mapping lives in
+    # +Suma::SchemaCategory+, the single source of truth. The exporter
+    # itself never classifies — it consumes loaded ExpressSchema
+    # objects whose output paths were set by this adapter.
     class Export < Thor
       desc "export *FILES",
            "Export EXPRESS schemas from manifest files or " \
@@ -38,7 +47,7 @@ module Suma
       end
 
       def run(files, options)
-        schemas = load_schemas_from_files(files)
+        schemas = files.flat_map { |file| build_schemas(file) }
 
         exporter = SchemaExporter.new(
           schemas: schemas,
@@ -52,22 +61,12 @@ module Suma
         exporter.export
       end
 
-      def load_schemas_from_files(files)
-        all_schemas = []
-
-        files.each do |file|
-          all_schemas += process_file(file)
-        end
-
-        all_schemas
-      end
-
-      def process_file(file)
+      def build_schemas(file)
         case File.extname(file).downcase
         when ".yml", ".yaml"
-          load_manifest_schemas(file)
+          build_from_manifest(file)
         when ".exp"
-          [create_schema_from_exp_file(file)]
+          [build_standalone(file)]
         else
           raise ArgumentError, "Unsupported file type: #{file}. " \
                                "Only .yml, .yaml, and .exp files are " \
@@ -75,13 +74,32 @@ module Suma
         end
       end
 
-      def load_manifest_schemas(file)
+      def build_from_manifest(file)
         manifest = Expressir::SchemaManifest.from_file(file)
-        manifest.schemas
+        manifest.schemas.map { |entry| build_from_manifest_entry(entry) }
+      end
+
+      def build_from_manifest_entry(entry)
+        category = SchemaCategory.for_schema(id: entry.id, path: entry.path)
+        ExpressSchema.new(
+          id: entry.id,
+          path: entry.path.to_s,
+          output_path: output_root.join(category.directory).to_s,
+          is_standalone_file: false,
+        )
+      end
+
+      def build_standalone(exp_file)
+        ExpressSchema.new(
+          id: nil,
+          path: File.expand_path(exp_file),
+          output_path: output_root.to_s,
+          is_standalone_file: true,
+        )
       end
 
-      def create_schema_from_exp_file(exp_file)
-        Struct.new(:id, :path).new(nil, File.expand_path(exp_file))
+      def output_root
+        Pathname.new(options[:output]).expand_path
       end
 
       def self.exit_on_failure?

data/lib/suma/cli/reformat.rb

@@ -4,84 +4,60 @@ require "thor"
 
 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,14 +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)
-        # 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