suma 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc14e31d38fd5c02cf635587a9b69065ca52c6c96eefc28b6176253e328572e8
-  data.tar.gz: 15b6aa0f50e227bd70d21fd615d036befdac46466186ef53cdb71c2e53b03ab7
+  metadata.gz: 52f25d69f23dba6c3d0c420c241279354bc8e838ac1f1e58d32e1392408da68e
+  data.tar.gz: 5cfa1b2e128694c04c75a0ca3eda31be63c90e2c5759ee564230525529edf07c
 SHA512:
-  metadata.gz: 7d0b42b4e0bd3d3c777f869b181fa9ce13b02ed7d05cf691da75546406bc005c2c6ded60c68360048659d2102486029f5ccfd3bc648eff5d8eea43e89778f4c5
-  data.tar.gz: 89665aa02f15bba0314fa27850664bbf0483473dfdecabc2a69a408084861da6aade7e6f10b11f90a8bca06066690c04e7fd4a289d9c6e9f1ce7650e3e62c757
+  metadata.gz: 7db5c9725523372171efb9d4234cbf9e7819c0ac0093128e92dcaa737cf34653d33573df97816c9253645d0f6abce7e9e96d4ca503f787336ec4dd3824641db8
+  data.tar.gz: 8095d98452ac83ab609466df69ee064b9202342d9dfd1842262a2edf571002b2e76f1855b47582cda228f7f321904b1927a46d6b14b7ff2318f0e11cf4e2afa5

data/.rubocop.yml

@@ -1,11 +1,14 @@
-# Auto-generated by Cimas: Do not edit it manually!
-# See https://github.com/metanorma/cimas
 inherit_from:
-  - .rubocop_todo.yml
   - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+  - .rubocop_todo.yml
 
-# local repo-specific modifications
-# ...
+require:
+- rubocop-performance
+- rubocop-rake
+- rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 3.4
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2024-10-17 02:50:55 UTC using RuboCop version 1.67.0.
+# on 2025-03-21 11:43:08 UTC using RuboCop version 1.74.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -13,20 +13,56 @@ Gemspec/DuplicatedAssignment:
   Exclude:
     - 'suma.gemspec'
 
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: outdent, indent
+Layout/AccessModifierIndentation:
+  Exclude:
+    - 'lib/suma/cli/build.rb'
+    - 'lib/suma/cli/links.rb'
+
 # Offense count: 1
-# Configuration parameters: Severity, Include.
-# Include: **/*.gemspec
-Gemspec/RequiredRubyVersion:
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
   Exclude:
-    - 'suma.gemspec'
+    - 'lib/suma/cli/links.rb'
+
+# Offense count: 19
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment.
+Layout/CommentIndentation:
+  Exclude:
+    - 'lib/suma/cli/build.rb'
+    - 'lib/suma/cli/links.rb'
 
-# Offense count: 21
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith, Severity.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
+  Exclude:
+    - 'lib/suma/cli/build.rb'
+
+# Offense count: 28
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Max, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns.
+# Configuration parameters: Width, AllowedPatterns.
+Layout/IndentationWidth:
+  Exclude:
+    - 'lib/suma/cli/build.rb'
+    - 'lib/suma/cli/links.rb'
+
+# Offense count: 43
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Max, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Exclude:
     - 'lib/suma/cli.rb'
+    - 'lib/suma/cli/build.rb'
+    - 'lib/suma/cli/links.rb'
     - 'lib/suma/collection_manifest.rb'
     - 'lib/suma/processor.rb'
     - 'lib/suma/schema_attachment.rb'
@@ -35,43 +71,78 @@ Layout/LineLength:
     - 'lib/suma/thor_ext.rb'
     - 'suma.gemspec'
 
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/suma/cli/links.rb'
+
 # Offense count: 1
 Lint/DuplicateMethods:
   Exclude:
     - 'lib/suma/express_schema.rb'
 
-# Offense count: 8
+# Offense count: 11
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
-    - 'lib/suma/collection_manifest.rb'
-    - 'lib/suma/processor.rb'
+    - 'lib/suma/cli/links.rb'
     - 'lib/suma/schema_attachment.rb'
-    - 'lib/suma/schema_collection.rb'
-    - 'lib/suma/schema_config/config.rb'
     - 'lib/suma/schema_document.rb'
     - 'lib/suma/thor_ext.rb'
 
 # Offense count: 1
-# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 33
+  Max: 64
 
 # Offense count: 2
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
-    - 'lib/suma/collection_manifest.rb'
+    - 'lib/suma/cli/links.rb'
     - 'lib/suma/thor_ext.rb'
 
-# Offense count: 7
+# Offense count: 9
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 52
+  Max: 72
+
+# Offense count: 3
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 6
 
 # Offense count: 1
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
-    - 'lib/suma/schema_collection.rb'
+    - 'lib/suma/cli/links.rb'
+
+# Offense count: 1
+# Configuration parameters: MinSize.
+Performance/CollectionLiteralInLoop:
+  Exclude:
+    - 'spec/suma/cli_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: implicit, each, example
+RSpec/HookArgument:
+  Exclude:
+    - 'spec/suma/cli_spec.rb'
+
+# Offense count: 1
+RSpec/MultipleExpectations:
+  Max: 2
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AutoCorrect, EnforcedStyle, AllowComments.
+# SupportedStyles: empty, nil, both
+Style/EmptyElse:
+  Exclude:
+    - 'lib/suma/cli/links.rb'

data/Gemfile

@@ -5,8 +5,9 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in suma.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
-gem "rspec", "~> 3.0"
+gem "rake"
+gem "rspec"
 gem "rubocop"
 gem "rubocop-performance"
-gem "rubocop-rails"
+gem "rubocop-rake"
+gem "rubocop-rspec"

data/README.adoc

@@ -12,15 +12,23 @@ to build the following artifacts:
 
 * the STEP Resource Library (SRL)
 
+== Features
 
-== Install
+* EXPRESS schema management for STEP standards
+* Document collection building and compilation
+* EXPRESS links validation and extraction
+* Schema listing file generation
+* Integration with the Metanorma ecosystem
+* Progress tracking for schema loading operations
+
+== Installation
 
 [source,sh]
 ----
 $ gem install suma
 ----
 
-== Usage
+== Usage: CLI
 
 === General
 
@@ -30,17 +38,34 @@ $ gem install suma
 $ suma
 Commands:
   suma build METANORMA_SITE_MANIFEST  # Build collection specified in site manifest (`metanorma*.yml`)
+  suma links SUBCOMMAND ...ARGS       # Manage EXPRESS links
   suma help [COMMAND]                 # Describe available commands or one specific command
 ----
 
-Where:
+=== Build command
+
+The `build` command processes a Metanorma site manifest and generates the specified output.
+
+[source,sh]
+----
+$ suma build METANORMA_SITE_MANIFEST [options]
+----
+
+Parameters:
 
 `METANORMA_SITE_MANIFEST`:: This is the path to the Metanorma site manifest,
 typically `metanorma.yml`.
 
+Options:
 
-=== Compilation
+`--[no-]compile`:: Compile or skip compilation of collection (default: true)
+`--schemas-all-path=PATH`, `-s PATH`:: Generate file that contains all schemas in the collection
 
+The generated `schemas-*.yaml` file name is derived from the input file name
+with the word `metanorma` replaced with `schemas`.
+
+[example]
+====
 .To compile SRL subset test collection
 [source,sh]
 ----
@@ -53,31 +78,108 @@ $ bundle exec suma build metanorma-test.yml
 $ bundle exec suma build metanorma-srl.yml
 ----
 
-// .To compile all STEPmod migrated docs (without detached) individually
-// [source,sh]
-// ----
-// $ bundle exec metanorma site generate
-// ----
+.To generate schema listing without compilation
+[source,sh]
+----
+$ bundle exec suma build --no-compile metanorma-srl.yml
+# => generates schemas-srl.yml
+----
+====
 
+All documents need to have a `schemas.yaml` in their document root that lists
+out which schemas the document includes.
 
-=== Generating full schema listing files
+=== Links command
 
-We generate the full schema collection listing using the `--no-compile`
-option in the `suma` command.
+==== General
 
-The generated `schemas-*.yaml` file name is derived from the input file name
-with the word `metanorma` replaced with `schemas`.
+The `links` command provides utilities for managing EXPRESS links.
+
+==== Extract and validate
+
+Extracts and validates EXPRESS links without creating intermediate files.
 
 [source,sh]
 ----
-$ bundle exec suma build --no-compile metanorma-srl.yml
-# => generates schemas-srl.yml
+$ suma links extract_and_validate SCHEMAS_FILE DOCUMENTS_PATH [OUTPUT_FILE]
 ----
 
-All documents need to have a `schemas.yaml` in their document root that lists
-out which schemas the document includes.
+Parameters:
+
+`SCHEMAS_FILE`:: Path to the schemas file (default: "schemas-srl.yml")
+
+`DOCUMENTS_PATH`:: Path to the documents directory (default: "documents")
+
+`OUTPUT_FILE`:: Path to write validation results (default: "validation_results.txt")
+
+[example]
+====
+.To validate EXPRESS links in documents
+[source,sh]
+----
+$ bundle exec suma links extract_and_validate schemas-srl.yml documents validation_results.txt
+----
+====
+
+This command:
+
+* Loads the schemas specified in the `SCHEMAS_FILE`
+* Searches for EXPRESS links in all AsciiDoc files in the `DOCUMENTS_PATH`
+* Validates these links against the loaded schemas
+* Writes validation results to the `OUTPUT_FILE`
+* Provides progress bars to track schema loading and link validation
+
+
+== Usage: Ruby
+
+=== General
+
+Suma can be used programmatically in your Ruby applications. The following examples demonstrate common usage patterns.
+
+=== Building collections
+
+[source,ruby]
+----
+require 'suma'
+
+# Build a collection with default settings
+Suma::Processor.run(
+  metanorma_yaml_path: "metanorma-srl.yml",
+  schemas_all_path: "schemas-srl.yml",
+  compile: true,
+  output_directory: "_site"
+)
+
+# Generate schema listing without compilation
+Suma::Processor.run(
+  metanorma_yaml_path: "metanorma-srl.yml",
+  schemas_all_path: "schemas-srl.yml",
+  compile: false,
+  output_directory: "_site"
+)
+----
+
+=== Working with schema configurations
+
+[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)
+
+# Access schema information
+schemas_config.schemas.each do |schema|
+  puts "Schema ID: #{schema.id}"
+  puts "Schema path: #{schema.path}"
+end
+----
 
 
-== License
+== Copyright and license
 
 Copyright Ribose. BSD 2-clause license.

data/exe/suma

@@ -3,4 +3,4 @@
 
 require "suma/cli"
 
-Suma::Cli.start(ARGV)
+Suma::Cli::Core.start(ARGV)

data/lib/suma/cli/build.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "../thor_ext"
+
+module Suma
+  module Cli
+    # Build command for building collections
+    class Build < Thor
+      # Return true to exit with non-zero status on errors
+      def self.exit_on_failure?
+        true
+      end
+
+      default_command :default_build
+
+      desc "default_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 default_build(metanorma_site_manifest)
+        # Lazy-load dependencies only when this command is actually used
+        require_relative "../processor"
+        require_relative "../utils"
+
+        unless File.exist?(metanorma_site_manifest)
+          raise Errno::ENOENT, "Specified Metanorma site manifest file " \
+                               "`#{metanorma_site_manifest}` not found."
+        end
+
+        # Allow errors to propagate
+        run(metanorma_site_manifest, options)
+      end
+
+      private
+
+      def run(manifest, options)
+        # Set schemas_all_path to match metanorma_yaml_path
+        schemas_all_path = options[:schemas_all_path] ||
+          manifest.gsub("metanorma", "schemas")
+
+        Processor.run(
+          metanorma_yaml_path: manifest,
+          schemas_all_path: schemas_all_path,
+          compile: options[:compile],
+          output_directory: "_site",
+        )
+      end
+
+      def log_error(error)
+        Utils.log "[ERROR] Error occurred during processing. See details below."
+        Utils.log error
+        Utils.log error.inspect
+        Utils.log error.backtrace.join("\n")
+      end
+    end
+  end
+end

data/lib/suma/cli/links.rb

@@ -0,0 +1,446 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "../utils"
+
+module Suma
+  module Cli
+    # Links command for managing EXPRESS links
+    class Links < 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)
+
+        # Load schemas and extract links
+        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)
+
+        # Extract links from files
+        links_by_file = extract_links(all_files)
+
+        # Validate links against schemas
+        repo = load_express_schemas(schemas_config)
+        unresolved_links = validate_links(links_by_file, repo)
+
+        # Generate and output results
+        write_validation_results(paths[:output_file], paths[:output_file_rel],
+                                 unresolved_links, links_by_file)
+      end
+
+      private
+
+      # Load all required dependencies for link validation
+      def load_dependencies
+        # Lazy-load dependencies only when this command is actually used
+        require "expressir"
+        require "ruby-progressbar"
+        require_relative "../schema_config"
+        require "pathname"
+      end
+
+      # Prepare and normalize all file paths needed for the operation
+      def prepare_file_paths(schemas_file, documents_path, output_file)
+        # Convert to absolute paths
+        schemas_file_path = Pathname.new(schemas_file).expand_path
+        documents_path = Pathname.new(documents_path).expand_path
+        output_file_path = Pathname.new(output_file).expand_path
+
+        # Store relative paths for display
+        schemas_file_rel = Pathname.new(schemas_file_path).relative_path_from(Pathname.pwd).to_s
+        documents_path_rel = Pathname.new(documents_path).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,
+          documents_path_rel: documents_path_rel,
+          output_file: output_file_path,
+          output_file_rel: output_file_rel,
+        }
+      end
+
+      # Load and initialize the schemas configuration
+      def load_schemas_config(schemas_file_path)
+        schemas_config = Suma::SchemaConfig::Config.from_yaml(File.read(schemas_file_path))
+        # Ensure the config is initialized with the correct path to resolve relative paths
+        schemas_config.set_initial_path(schemas_file_path.to_s)
+        schemas_config
+      rescue StandardError => e
+        puts "Error loading schemas file: #{e.message}"
+        exit(1)
+      end
+
+      # Collect paths to all schema files from the config
+      def collect_schema_paths(schemas_config, schemas_file_rel)
+        exp_files = []
+        schemas_config.schemas.each do |schema|
+          exp_files << schema.path if schema.path
+        end
+
+        puts "Found #{exp_files.size} EXPRESS schema files from #{schemas_file_rel}"
+        exp_files
+      end
+
+      # Find all AsciiDoc files in the specified path
+      def find_adoc_files(documents_path)
+        Dir.glob(documents_path.join("**", "*.adoc").to_s)
+      end
+
+      # Display counts of discovered files
+      def display_file_counts(adoc_files, exp_files)
+        puts "Found #{adoc_files.size} AsciiDoc files and #{exp_files.size} EXPRESS files"
+      end
+
+      # Create a standardized progress bar
+      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
+
+      # Extract EXPRESS links from all files
+      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)
+            # Extract links while ignoring text after comma
+            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
+
+      # Load all EXPRESS schemas for validation
+      def load_express_schemas(schemas_config)
+        # Get all schema paths for validation
+        schema_paths = {}
+        schemas_config.schemas.each do |schema|
+          schema_paths[schema.id] = schema.path
+        end
+
+        puts "Loading #{schema_paths.size} EXPRESS schemas for validation..."
+
+        # Setup progress bar for schema loading
+        loading_progress = create_progress_bar("Loading schemas",
+                                               schema_paths.size)
+
+        # Try to load all schemas with progress tracking
+        begin
+          repo = Expressir::Express::Parser.from_files(schema_paths.values) do |filename, _schemas, error|
+            loading_progress.increment
+            if error
+              puts "\nWarning: Error loading schema #{filename}: #{error.message}"
+            end
+          end
+
+          puts "Successfully loaded #{repo.schemas.size} schemas"
+          repo
+        rescue StandardError => e
+          puts "Error loading schemas: #{e.message}"
+          exit(1)
+        end
+      end
+
+      # Validate all links against loaded schemas
+      def validate_links(links_by_file, repo)
+        unresolved_links = []
+        total_links = links_by_file.values.sum(&:size)
+
+        progress = create_progress_bar("Validating links", total_links)
+
+        links_by_file.each do |file, links|
+          validate_file_links(file, links, repo, progress, unresolved_links)
+        end
+
+        unresolved_links
+      end
+
+      # Validate links in a specific file
+      def validate_file_links(file, links, repo, progress, unresolved_links)
+        file_content = File.read(file)
+        file_lines = file_content.lines
+
+        links.each do |link|
+          progress.increment
+          line_idx = find_link_line(file_lines, link)
+          next unless line_idx
+
+          # Parse link (schema only, schema.element, or schema.element.path)
+          parts = link.split(".")
+
+          if parts.size == 1
+            validate_schema_only_link(parts[0], repo, file, line_idx, link,
+                                      unresolved_links)
+          else
+            validate_schema_element_link(parts, repo, file, line_idx, link,
+                                         unresolved_links)
+          end
+        end
+      rescue StandardError => e
+        puts "Warning: Error processing file #{file}: #{e.message}"
+      end
+
+      # Find the line where a link appears in the file
+      def find_link_line(file_lines, link)
+        file_lines.each_with_index do |line, idx|
+          # Match both with and without comma text
+          if /<<express:#{Regexp.escape(link)}(?:,[^>]+)?>>/.match?(line)
+            return idx
+          end
+        end
+        nil
+      end
+
+      # Validate a link that only references a schema
+      def validate_schema_only_link(schema_name, repo, file, line_idx, link,
+  unresolved_links)
+        # Check if schema exists
+        schema = repo.schemas.find do |s|
+          s.id.downcase == schema_name.downcase
+        end
+
+        if !schema
+          unresolved_links << {
+            file: file,
+            line: line_idx + 1,
+            link: link,
+            reason: "Schema '#{schema_name}' not found",
+          }
+        end
+      end
+
+      # Validate a link with schema.element or deeper paths
+      def validate_schema_element_link(parts, repo, file, line_idx, link,
+  unresolved_links)
+        schema_name = parts[0]
+        element_name = parts[1]
+
+        # Check if schema exists
+        schema = repo.schemas.find do |s|
+          s.id.downcase == schema_name.downcase
+        end
+
+        if !schema
+          unresolved_links << {
+            file: file,
+            line: line_idx + 1,
+            link: link,
+            reason: "Schema '#{schema_name}' not found",
+          }
+          return
+        end
+
+        # Find the element in the schema
+        element = find_schema_element(schema, element_name)
+
+        if !element
+          unresolved_links << {
+            file: file,
+            line: line_idx + 1,
+            link: link,
+            reason: "Element '#{element_name}' not found in schema '#{schema_name}'",
+          }
+          return
+        end
+
+        # If we have more than 2 parts, validate the deeper path
+        if parts.size > 2
+          validation_error = validate_deep_path(schema, element, parts[2..],
+                                                file, line_idx, link)
+          unresolved_links << validation_error if validation_error
+        end
+      end
+
+      # Find an element in a schema by name
+      def find_schema_element(schema, element_name)
+        # Try to find element in various collections
+        element_collections = [
+          schema.entities,
+          schema.types,
+          schema.constants,
+          schema.functions,
+          schema.rules,
+          schema.procedures,
+          schema.subtype_constraints,
+        ]
+
+        element_collections.each do |collection|
+          element = collection&.find do |e|
+            e.id.downcase == element_name.downcase
+          end
+          return element if element
+        end
+
+        nil
+      end
+
+      # Validate deeper paths in a link (schema.element.path.subpath)
+      def validate_deep_path(schema, element, path_parts, file, line_idx,
+  full_link)
+        current_element = element
+        current_path = "#{schema.id}.#{element.id}"
+
+        # Process each part of the path
+        path_parts.each do |part|
+          # The validation logic depends on the type of current element
+          case current_element
+          when Expressir::Express::Entity
+            # For entities, check attributes
+            attribute = current_element.attributes&.find do |a|
+              a.id.downcase == part.downcase
+            end
+
+            unless attribute
+              return {
+                file: file,
+                line: line_idx + 1,
+                link: full_link,
+                reason: "Attribute '#{part}' not found in entity '#{current_path}'",
+              }
+            end
+
+            current_element = attribute
+            current_path += ".#{part}"
+
+          when Expressir::Express::Type
+            # For types, validation depends on type kind
+            if current_element.respond_to?(:base_type) && current_element.base_type
+              # For derived types, find the base type
+              base_type = find_base_type(schema, current_element.base_type)
+
+              unless base_type
+                return {
+                  file: file,
+                  line: line_idx + 1,
+                  link: full_link,
+                  reason: "Base type not found for '#{current_path}'",
+                }
+              end
+
+              # Continue validation using base type
+              current_element = base_type
+
+            elsif current_element.respond_to?(:elements) && current_element.elements
+              # For enum types, check enum values
+              enum_value = current_element.elements.find do |e|
+                e.id.downcase == part.downcase
+              end
+
+              unless enum_value
+                return {
+                  file: file,
+                  line: line_idx + 1,
+                  link: full_link,
+                  reason: "Enumeration value '#{part}' not found in type '#{current_path}'",
+                }
+              end
+
+              current_element = enum_value
+              current_path += ".#{part}"
+
+            else
+              # For other types, we can't navigate deeper
+              return {
+                file: file,
+                line: line_idx + 1,
+                link: full_link,
+                reason: "Cannot navigate deeper from type '#{current_path}'",
+              }
+            end
+
+          else
+            # For other element types, navigation is not supported
+            return {
+              file: file,
+              line: line_idx + 1,
+              link: full_link,
+              reason: "Cannot navigate deeper from '#{current_path}'",
+            }
+          end
+        end
+
+        # If we've processed all parts without returning an error, path is valid
+        nil
+      end
+
+      # Find a base type in a schema
+      def find_base_type(schema, type_ref)
+        # Skip built-in types
+        return nil if %w[INTEGER REAL STRING BOOLEAN NUMBER BINARY
+                         LOGICAL].include?(type_ref.to_s.upcase)
+
+        # Find the referenced type in the schema
+        if type_ref.is_a?(String)
+          find_schema_element(schema, type_ref)
+        elsif type_ref.respond_to?(:id)
+          # It's already a type object
+          type_ref
+        else
+          nil
+        end
+      end
+
+      # Write validation results to the output file
+      def write_validation_results(output_file_path, output_file_rel,
+  unresolved_links, links_by_file)
+        total_links = links_by_file.values.sum(&:size)
+
+        # Prepare results for output
+        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
+
+        # Write results to output file
+        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}"
+          # Still print results to console as fallback
+          puts results
+        end
+      end
+    end
+  end
+end

data/lib/suma/cli.rb

@@ -2,53 +2,27 @@
 
 require "thor"
 require_relative "thor_ext"
-require_relative "processor"
-require_relative "utils"
 
 module Suma
-  class Cli < 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(metanorma_site_manifest)
-      unless File.exist?(metanorma_site_manifest)
-        raise Errno::ENOENT, "Specified Metanorma site manifest file " \
-          "`#{metanorma_site_manifest}` not found."
+  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`)"
+      def build(*args)
+        # If no arguments, add an empty array to ensure the default command is triggered
+        args = [] if args.empty?
+        require_relative "cli/build"
+        Cli::Build.start(args)
       end
 
-      begin
-        run(metanorma_site_manifest, options)
-      rescue StandardError => e
-        log_error(e)
+      desc "links SUBCOMMAND ...ARGS", "Manage EXPRESS links"
+      def links(*args)
+        require_relative "cli/links"
+        Cli::Links.start(args)
       end
     end
-
-    private
-
-    def run(manifest, options)
-      # Set schemas_all_path to match metanorma_yaml_path
-      schemas_all_path = options[:schemas_all_path] ||
-        manifest.gsub("metanorma", "schemas")
-
-      Processor.run(
-        metanorma_yaml_path: manifest,
-        schemas_all_path: schemas_all_path,
-        compile: options[:compile],
-        output_directory: "_site",
-      )
-    end
-
-    def log_error(error)
-      Utils.log "[ERROR] Error occurred during processing. See details below."
-      Utils.log error
-      Utils.log error.inspect
-      Utils.log error.backtrace.join("\n")
-    end
   end
 end

data/lib/suma/collection_config.rb

@@ -16,7 +16,7 @@ module Suma
     end
 
     def to_file(path)
-      File.open(path, "w") { |f| f.write to_yaml }
+      File.write(path, to_yaml)
     end
   end
 end

data/lib/suma/express_schema.rb

@@ -49,9 +49,7 @@ module Suma
       # return if File.exist?(filename_plain)
       FileUtils.mkdir_p(File.dirname(filename_plain))
 
-      File.open(filename_plain, "w") do |file|
-        file.write(to_plain)
-      end
+      File.write(filename_plain, to_plain)
     end
   end
 end

data/lib/suma/processor.rb

@@ -12,9 +12,12 @@ require "metanorma/collection/collection"
 module Suma
   class Processor
     class << self
-      def run(metanorma_yaml_path:, schemas_all_path:, compile:, output_directory: "_site")
+      # rubocop:disable Metrics/MethodLength
+      def run(metanorma_yaml_path:, schemas_all_path:, compile:,
+output_directory: "_site")
         Utils.log "Current directory: #{Dir.getwd}, writing #{schemas_all_path}..."
-        collection_config = export_schema_config(metanorma_yaml_path, schemas_all_path)
+        collection_config = export_schema_config(metanorma_yaml_path,
+                                                 schemas_all_path)
 
         unless compile
           Utils.log "No compile option set. Skipping schema compilation."
@@ -27,6 +30,7 @@ module Suma
         Utils.log "Compiling complete collection..."
         compile_collection(collection_config, output_directory)
       end
+      # rubocop:enable Metrics/MethodLength
 
       private
 
@@ -61,7 +65,9 @@ module Suma
       end
 
       def compile_collection(collection_config, output_directory)
-        metanorma_collection, collection_opts = build_collection(collection_config, output_directory)
+        metanorma_collection, collection_opts = build_collection(
+          collection_config, output_directory
+        )
 
         metanorma_collection.render(collection_opts)
 

data/lib/suma/schema_attachment.rb

@@ -59,9 +59,7 @@ module Suma
 
       # Utils.log "relative_path #{relative_path}"
 
-      File.open(filename_adoc, "w") do |file|
-        file.write(to_adoc(relative_path))
-      end
+      File.write(filename_adoc, to_adoc(relative_path))
     end
 
     def filename_config
@@ -102,7 +100,8 @@ module Suma
 
       relative_path = Pathname.new(filename_adoc).relative_path_from(Dir.pwd)
       Utils.log "Compiling schema (id: #{id}, type: #{self.class}) => #{relative_path}"
-      Metanorma::Compile.new.compile(filename_adoc, agree_to_terms: true, install_fonts: false)
+      Metanorma::Compile.new.compile(filename_adoc, agree_to_terms: true,
+                                                    install_fonts: false)
       Utils.log "Compiling schema (id: #{id}, type: #{self.class}) => #{relative_path}... done!"
 
       # clean_artifacts

data/lib/suma/schema_config/config.rb

@@ -13,7 +13,7 @@ module Suma
 
       def initialize(**args)
         @path = path_relative_to_absolute(path) if path
-        super(**args)
+        super
       end
 
       def base_path
@@ -31,9 +31,7 @@ module Suma
       end
 
       def to_file(to_path = path)
-        File.open(to_path, "w") do |f|
-          f.write(to_yaml)
-        end
+        File.write(to_path, to_yaml)
       end
 
       def set_initial_path(new_path)

data/lib/suma/schema_document.rb

@@ -5,7 +5,7 @@ require_relative "schema_attachment"
 module Suma
   class SchemaDocument < SchemaAttachment
     def bookmark(anchor)
-      a = anchor.gsub(/\}\}/, ' | replace: "\", "-"}}')
+      a = anchor.gsub("}}", ' | replace: "\", "-"}}')
       "[[#{@id}.#{a}]]"
     end
 

data/lib/suma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Suma
-  VERSION = "0.1.8"
+  VERSION = "0.1.9"
 end

data/suma.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.email = ["open.source@ribose.com"]
 
   spec.summary = "Utility for SUMA " \
-  "(STEP Unified Model-Based Standards Architecture)"
+                 "(STEP Unified Model-Based Standards Architecture)"
   spec.description = <<~DESCRIPTION
     Utility for SUMA (STEP Unified Model-Based Standards Architecture)
   DESCRIPTION
@@ -20,7 +20,6 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.bindir = "bin"
   spec.require_paths = ["lib"]
   spec.files = `git ls-files`.split("\n")
-  spec.test_files = `git ls-files -- {spec}/*`.split("\n")
   spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
 
   # Specify which files should be added to the gem when it is released.
@@ -34,8 +33,10 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "expressir"
+  spec.add_dependency "expressir", "~> 2.1.16"
   spec.add_dependency "lutaml-model", "~> 0.7"
   spec.add_dependency "metanorma-cli"
+  spec.add_dependency "ruby-progressbar"
   spec.add_dependency "thor", ">= 0.20"
+  spec.metadata["rubygems_mfa_required"] = "true"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: suma
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - Ribose Inc.
@@ -14,16 +14,16 @@ dependencies:
   name: expressir
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.1.16
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.1.16
 - !ruby/object:Gem::Dependency
   name: lutaml-model
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -91,6 +105,8 @@ files:
 - exe/suma
 - lib/suma.rb
 - lib/suma/cli.rb
+- lib/suma/cli/build.rb
+- lib/suma/cli/links.rb
 - lib/suma/collection_config.rb
 - lib/suma/collection_manifest.rb
 - lib/suma/express_schema.rb
@@ -110,7 +126,8 @@ files:
 homepage: https://github.com/metanorma/suma
 licenses:
 - BSD-2-Clause
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: