suma 0.2.6 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e6db67576d42aaaed54f90f72960ad405774d4084be5f7c0e8f1b277ebbbd50
-  data.tar.gz: ed5cdf3967496436950306f0edcf553751bb3da06c4e4582a014b8e7610e6d35
+  metadata.gz: 041f227f2bd35c3d90138ab621e51b9abf68206f7b295523da2827d82d6b63c7
+  data.tar.gz: f64aed0f1f4aa096d66c4c299581a2437a991fe6f522b50170b26557b81a0092
 SHA512:
-  metadata.gz: 0e4e8fe19fb5b9ec7c8023258e55a8ed100c98bb4ee271898562eeed13d5e1646d09c673e0053f2271827c8413408d5cb9295e94cc39d298be7161d33a0805c2
-  data.tar.gz: 8110684a885977266204dace36b4b5bb8a88113c1b410aa78c19d8ad4c58c2a49858f14f9495e433414d43b0bd13716a49e47eb8ef7724ee34306826a215ff15
+  metadata.gz: ac0d654f283a393c6ae620763920decec16ce2bad44c5cc5722f123bf12ee7539069e35dbbb4909f061fdb14e240f26f033d04e357cfdaff814966cc5f185f8b
+  data.tar.gz: a2a4ca844993d87bc534c77d99e5767aa0f6f86b1f028a15c9a9387ddc761303fcef390a3fe98dce907580b8da1657bb83f96d7c4d0cdd0e03f59d690a1c688f

data/.gitignore

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

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-05-11 08:57:26 UTC using RuboCop version 1.86.1.
+# on 2026-07-02 16:27:30 UTC using RuboCop version 1.87.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
@@ -16,13 +16,147 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'suma.gemspec'
 
-# Offense count: 120
+# Offense count: 35
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/schema_comparer.rb'
+    - 'lib/suma/schema_compiler.rb'
+    - 'lib/suma/schema_manifest_generator.rb'
+    - 'lib/suma/svg_quality/formatters.rb'
+    - 'lib/suma/term_extractor.rb'
+    - 'spec/suma/link_validator_spec.rb'
+    - 'spec/suma/manifest_traverser_spec.rb'
+    - 'spec/suma/register_manifest_generator_spec.rb'
+    - 'spec/suma/schema_comparer_integration_spec.rb'
+    - 'spec/suma/schema_comparer_spec.rb'
+    - 'spec/suma/schema_discovery_spec.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_element, with_fixed_indentation
+Layout/ArrayAlignment:
+  Exclude:
+    - 'lib/suma/schema_naming.rb'
+    - 'spec/suma/register_manifest_generator_spec.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/register_manifest_generator.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/register_manifest_generator.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: IndentationWidth.
+Layout/ClosingParenthesisIndentation:
+  Exclude:
+    - 'lib/suma/schema_template/document.rb'
+    - 'spec/suma/link_validator_spec.rb'
+    - 'spec/suma/schema_index_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
+Layout/FirstArgumentIndentation:
+  Exclude:
+    - 'lib/suma/schema_template/document.rb'
+    - 'spec/suma/link_validator_spec.rb'
+    - 'spec/suma/schema_index_spec.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: special_inside_parentheses, consistent, align_brackets
+Layout/FirstArrayElementIndentation:
+  Exclude:
+    - 'spec/suma/manifest_traverser_spec.rb'
+
+# Offense count: 14
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'lib/suma/schema_compiler.rb'
+    - 'lib/suma/term_extractor.rb'
+    - 'spec/suma/manifest_traverser_spec.rb'
+
+# Offense count: 12
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/register_manifest_generator.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
+# Offense count: 189
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: symmetrical, new_line, same_line
+Layout/MultilineArrayBraceLayout:
+  Exclude:
+    - 'spec/suma/manifest_traverser_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: symmetrical, new_line, same_line
+Layout/MultilineMethodCallBraceLayout:
+  Exclude:
+    - 'lib/suma/schema_template/document.rb'
+    - 'spec/suma/link_validator_spec.rb'
+    - 'spec/suma/schema_index_spec.rb'
+
+# Offense count: 32
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/schema_comparer.rb'
+    - 'lib/suma/schema_compiler.rb'
+    - 'lib/suma/schema_manifest_generator.rb'
+    - 'lib/suma/schema_naming.rb'
+    - 'lib/suma/svg_quality/formatters.rb'
+    - 'lib/suma/term_extractor.rb'
+    - 'spec/suma/link_validator_spec.rb'
+    - 'spec/suma/manifest_traverser_spec.rb'
+    - 'spec/suma/register_manifest_generator_spec.rb'
+    - 'spec/suma/schema_comparer_integration_spec.rb'
+    - 'spec/suma/schema_comparer_spec.rb'
+    - 'spec/suma/schema_discovery_spec.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
 # Offense count: 4
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
@@ -48,29 +182,31 @@ Lint/UnusedMethodArgument:
   Exclude:
     - 'lib/suma/svg_quality.rb'
 
-# Offense count: 29
+# Offense count: 32
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
-    - 'lib/suma/cli.rb'
     - 'lib/suma/cli/check_svg_quality.rb'
+    - 'lib/suma/cli/core.rb'
     - 'lib/suma/jsdai/figure.rb'
     - 'lib/suma/jsdai/figure_image.rb'
     - 'lib/suma/link_validator.rb'
+    - 'lib/suma/manifest_traverser.rb'
     - 'lib/suma/processor.rb'
-    - 'lib/suma/schema_attachment.rb'
+    - 'lib/suma/schema_collection.rb'
     - 'lib/suma/schema_comparer.rb'
-    - 'lib/suma/schema_document.rb'
+    - 'lib/suma/schema_compiler.rb'
     - 'lib/suma/schema_manifest_generator.rb'
+    - 'lib/suma/schema_template/document.rb'
     - 'lib/suma/svg_quality/formatters/terminal_formatter.rb'
     - 'lib/suma/term_extractor.rb'
     - 'lib/suma/thor_ext.rb'
 
-# Offense count: 1
+# Offense count: 3
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 54
+  Max: 58
 
 # Offense count: 14
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
@@ -87,12 +223,12 @@ Metrics/CyclomaticComplexity:
     - 'lib/suma/term_extractor.rb'
     - 'lib/suma/thor_ext.rb'
 
-# Offense count: 25
+# Offense count: 31
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 59
+  Max: 63
 
-# Offense count: 2
+# Offense count: 3
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 9
@@ -150,7 +286,7 @@ RSpec/ContextWording:
   Exclude:
     - 'spec/suma/cli/export_spec.rb'
 
-# Offense count: 71
+# Offense count: 111
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 60
@@ -181,7 +317,7 @@ RSpec/MessageSpies:
   Exclude:
     - 'spec/suma/schema_comparer_integration_spec.rb'
 
-# Offense count: 50
+# Offense count: 87
 RSpec/MultipleExpectations:
   Max: 21
 
@@ -203,6 +339,27 @@ RSpec/StubbedMock:
   Exclude:
     - 'spec/suma/schema_comparer_integration_spec.rb'
 
+# Offense count: 9
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/register_manifest_generator.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineIfModifier:
+  Exclude:
+    - 'lib/suma/schema_comparer.rb'
+    - 'lib/suma/schema_manifest_generator.rb'
+    - 'lib/suma/schema_naming.rb'
+
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?

data/CLAUDE.md

@@ -27,7 +27,8 @@ exe/suma export -o OUTPUT_DIR schema1.yml schema2.exp  # Export schemas (YAML ma
 exe/suma compare TRIAL_SCHEMA REFERENCE_SCHEMA -v VER  # Compare schemas, generate .changes.yaml
 exe/suma reformat PATH                                  # Reformat EXP files (use -r for recursive)
 exe/suma generate-schemas METANORMA_YAML SCHEMAS_YAML  # Generate schema manifest from site manifest
-exe/suma extract-terms SCHEMA_YAML GLOSSARIST_DIR      # Extract terms to Glossarist v2 format
+exe/suma extract-terms SCHEMA_YAML GLOSSARIST_DIR -u URN   # Extract EXPRESS entity concepts to Glossarist v3 format
+exe/suma generate-register SCHEMA_YAML OUT_DIR -u URN --id ID --ref REF  # Generate hierarchical register.yaml from schema manifest
 exe/suma validate links SCHEMAS_FILE DOCS_PATH          # Validate EXPRESS cross-reference links
 ```
 
@@ -35,27 +36,50 @@ exe/suma validate links SCHEMAS_FILE DOCS_PATH          # Validate EXPRESS cross
 
 ### Core pipeline (build command)
 
-1. `Processor.run` receives a Metanorma site manifest YAML
+1. `Processor.new(...).run` receives a Metanorma site manifest YAML
 2. `SiteConfig` reads the site manifest, finds collection YAML paths
 3. `CollectionConfig` extends `Metanorma::Collection::Config` with a `CollectionManifest` that discovers `schemas.yaml` files
-4. `SchemaCollection` loads all discovered schemas via `Expressir`, exports plain `.exp` files, and compiles documentation (Metanorma `.adoc` → XML/HTML)
-5. `SchemaExporter` handles exporting schemas to a directory (with optional ZIP packaging)
+4. `ManifestTraverser` walks the manifest tree (`expand_schemas_only`, `export_schema_config`, `remove_schemas_only_sources`); `SchemaDiscovery` loads each `schemas.yaml` and builds doc sub-trees
+5. `SchemaCollection` loads all discovered schemas via `Expressir`, exports plain `.exp` files, and compiles documentation via `SchemaCompiler` + `SchemaTemplate::Plain|Document` (Metanorma `.adoc` → XML/HTML)
+6. `SchemaExporter` handles exporting schemas to a directory (with optional ZIP packaging)
 
 ### Key classes
 
-- **`ExpressSchema`** — wraps a single EXPRESS schema file; parses via `Expressir::Express::Parser`, can output plain or annotated `.exp`
-- **`SchemaAttachment`** — compiles one schema into a Metanorma `.adoc` document and renders it via `Metanorma::Compile`
-- **`SchemaDocument`** (extends `SchemaAttachment`) — adds cross-reference bookmarks and uses XML-only output
-- **`SchemaCollection`** — orchestrates processing of all schemas from a config
+- **`ExpressSchema`** — wraps a single EXPRESS schema file; parses via `Expressir::Express::Parser`, can output plain or annotated `.exp`. Includes nested `Type` module for schema classification (resource/module_arm/module_mim/business_object_model/core_model/standalone) based on ID suffixes and path segments
+- **`SchemaCategory`** — value object mapping `ExpressSchema::Type` to a register/export category (id, label, prefix, types, directory). Single source of truth for category identity across `SchemaExporter`, `SchemaNaming`, and `RegisterManifestGenerator`
+- **`Urn`** — value object encapsulating ISO URN semantics (wildcard stripping, base/alias split, leaf composition for `for_schema`/`for_term`/`for_entity`)
+- **`TermExtractor`** — extracts EXPRESS entity concepts from a schema manifest into Glossarist v3 YAML format. Generates definitions with URN cross-references, processes remarks into notes, and resolves EXPRESS xrefs to URN mentions. Assigns stable UUIDv5 identifiers
+- **`RegisterManifestGenerator`** (file: `lib/suma/register_manifest_generator.rb`) — generates a Glossarist v3 `register.yaml` with hierarchical sections from a schema manifest. Classifies schemas via `ExpressSchema::Type` (DRY), delegates naming to `SchemaNaming` (OCP), orders resources before modules. Uses the Section model's `children` field for hierarchy
+- **`SchemaNaming`** — pure module that converts EXPRESS schema IDs to human-readable display names. Strips type suffixes (`_schema`/`_arm`/`_mim`/`_bom`), title-cases with acronym preservation (AIC, AEC, BREP, 2D, 3D…), lowercases function words, appends type labels (ARM/MIM)
+- **`SchemaTemplate::Plain` / `SchemaTemplate::Document`** — pure renderers for the AsciiDoc body fed to Metanorma (no I/O, no schema knowledge). `Document` adds cross-reference anchors and produces XML-only output
+- **`SchemaCompiler`** — orchestrates one schema's compilation: writes adoc + config, invokes `Metanorma::Compile`. Templates are injected via the constructor (composition over inheritance)
+- **`SchemaCollection`** — orchestrates processing of all schemas from a config; selects `Plain` for top-level schemas and `Document` for schemas-only entries
 - **`SchemaExporter`** — standalone export of schemas from manifest or `.exp` files to a directory, with optional ZIP
-- **`CollectionManifest`** — traverses collection YAML files, builds unified `Expressir::SchemaManifest`
+- **`CollectionManifest`** — pure data model (lutaml-model attributes + YAML mappings) for one node of a Metanorma collection manifest. No imperative methods
+- **`ManifestTraverser`** — tree-walking service over a `CollectionManifest` (`find_schemas_only`, `export_schema_config`, `expand_schemas_only`, `remove_schemas_only_sources`)
+- **`SchemaDiscovery`** — schema-config I/O service on a single manifest node (`load_config` from `schemas.yaml`, `build_doc_entries`, `build_added_manifest`)
+- **`SchemaIndex`** — O(1) lookup index for schema and element names, used by `LinkValidator`
+- **`LinkValidator`** — validates EXPRESS cross-reference links against a `SchemaIndex`; returns `LinkValidationResult` structs for unresolved links
 
 ### CLI structure
 
 - `Suma::Cli::Core` (Thor subclass) — top-level CLI entrypoint
-- Subcommands delegate to `Cli::Build`, `Cli::Export`, `Cli::Compare`, `Cli::Validate`, `Cli::Reformat`, `Cli::GenerateSchemas`, `Cli::ExtractTerms`, `Cli::ConvertJsdai`
+- Subcommands delegate to `Cli::Build`, `Cli::Export`, `Cli::Compare`, `Cli::Validate`, `Cli::Reformat`, `Cli::GenerateSchemas`, `Cli::ExtractTerms`, `Cli::GenerateRegister`, `Cli::ConvertJsdai`
 - Thor extension (`ThorExt::Start`) adds `-h`/`--help` support and error formatting
 
+### Terminology extraction (extract-terms / generate-register)
+
+The `extract-terms` command reads an EXPRESS schema manifest, parses each `.exp` file via `Expressir`, and emits Glossarist v3 concept YAML with:
+- Entity definitions using URN cross-references (`{{urn:...term,entity data type}}`, `{{urn:...term,entity}}`)
+- Entity remarks processed into notes (first-sentence extraction, redundant note removal, invalid reference filtering)
+- Domain classification via `ExpressSchema::Type` (resource vs application module)
+- Section references for hierarchical grouping
+
+The `generate-register` command reads the same schema manifest and emits `register.yaml` with hierarchical sections:
+- Top-level groups: Resources (133) before Application Modules (1123)
+- Child sections use human-readable names from `SchemaNaming` (e.g. "Resource: Topology", "Module: Activity (ARM)")
+- Parent group IDs are included in concept metadata so the concept-browser can filter by group
+
 ### External dependencies
 
 - **expressir** — EXPRESS schema parsing and manifest handling
@@ -73,4 +97,6 @@ The `compare` command uses an external `eengine` binary to diff two EXPRESS sche
 - Ruby 3.0+ with `frozen_string_literal: true` in every file
 - RuboCop with performance, rake, and rspec plugins; inherits from riboseinc OSS guide
 - Some CLI files are excluded from RuboCop in `.rubocop.yml`
-- Use `Utils.log` for user-facing output (prefixes with `[suma]`)
+- Internal library code uses Ruby `autoload` (defined in the immediate parent namespace's file); no `require_relative`
+- No `send` to call private methods, no `instance_variable_set`/`get`, no `respond_to?` for type checking
+- Use `Utils.log` for user-facing output (writes to `$stderr`, prefix `[suma]`; `level: :debug` gated by `SUMA_DEBUG`)

data/Gemfile

@@ -6,9 +6,9 @@ source "https://rubygems.org"
 gemspec
 
 gem "canon"
-gem "metanorma", github: "metanorma/metanorma", branch: "main"
-gem "metanorma-plugin-lutaml", github: "metanorma/metanorma-plugin-lutaml", branch: "main"
-gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "main"
+# gem "metanorma", github: "metanorma/metanorma", branch: "main"
+# gem "metanorma-plugin-lutaml", github: "metanorma/metanorma-plugin-lutaml", branch: "main"
+# gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "main"
 gem "nokogiri"
 gem "openssl", "~> 3.0"
 gem "rake"

data/README.adoc

@@ -39,7 +39,8 @@ $ suma
  Commands:
   suma build METANORMA_SITE_MANIFEST                                  # Build collection specified in site manifest (`metanorma*.yml`)
   suma convert-jsdai XML_FILE IMAGE_FILE OUTPUT_DIR                   # Convert JSDAI XML and image files to SVG and EXP files
-  suma extract-terms SCHEMA_MANIFEST_FILE GLOSSARIST_OUTPUT_PATH      # Extract terms from SCHEMA_MANIFEST_FILE into Glossarist v2 format
+  suma extract-terms SCHEMA_MANIFEST_FILE GLOSSARIST_OUTPUT_PATH      # Extract EXPRESS entity concepts into Glossarist v3 format
+  suma generate-register SCHEMA_MANIFEST_FILE OUTPUT_PATH            # Generate hierarchical register.yaml from schema manifest
   suma generate-schemas METANORMA_MANIFEST_FILE SCHEMA_MANIFEST_FILE  # Generate EXPRESS schema manifest file from Metanorma site manifest
   suma help [COMMAND]                                                 # Describe available commands or one specific command
   suma reformat EXPRESS_FILE_PATH                                     # Reformat EXPRESS files
@@ -301,6 +302,61 @@ $ bundle exec suma extract-terms schemas-activity-modules.yml terms_output
 ====
 
 
+=== Generate register command
+
+The `suma generate-register` command reads an EXPRESS schema manifest and
+emits a Glossarist v3 `register.yaml` with hierarchical sections. The
+output is used by the concept browser to render a navigable sidebar of
+sections and to resolve concept cross-references.
+
+[source,sh]
+----
+$ suma generate-register SCHEMA_MANIFEST_FILE OUTPUT_PATH -u URN --id ID --ref REF
+----
+
+Parameters:
+
+`SCHEMA_MANIFEST_FILE`:: Path to the schema manifest (e.g., "schemas-smrl-part-2.yml")
+
+`OUTPUT_PATH`:: Directory where `register.yaml` will be written
+
+Options:
+
+`--urn`, `-u`:: Base URN prefix for the dataset (e.g. `urn:iso:std:iso:10303:-2:ed-2:en:tech:*`).
+The wildcard is stripped for the base URN and kept in `urnAliases`.
+*Required*.
+
+The URN is fully configurable — every component can be changed to match the
+dataset being exported. The general structure is:
+
+----
+urn:iso:std:iso:<part>:ed-<edition>:<lang>:tech:*
+----
+
+For example, to export edition 3 in French:
+
+----
+--urn urn:iso:std:iso:10303:-2:ed-3:fr:tech:*
+----
+
+The current ISO 10303-2 SMRL data is edition 2; use `ed-2` unless you are
+re-publishing an earlier edition.
+
+`--id`:: Dataset identifier (e.g. `iso10303-2-express`). *Required*.
+
+`--ref`:: Human-readable dataset reference label (e.g. `ISO 10303-2 EXPRESS Concepts`). *Required*.
+
+`--language_code`, `-l`:: Language code for section names (default: "eng")
+
+The generated register contains two top-level groups:
+
+* **Resources** — integrated resource schemas (path contains `schemas/resources/`)
+* **Application Modules** — ARM and MIM schemas (path contains `schemas/modules/`)
+
+Each schema gets a human-readable name via the `SchemaNaming` module
+(e.g. `topology_schema` → "Resource: Topology", `Activity_method_assignment_mim` → "Module: Activity Method Assignment (MIM)"). Acronyms (AIC, AEC, BREP, 2D, 3D) are preserved; function words (as, of, the) are lowercased per ISO title-case convention.
+
+
 === Convert JSDAI image outputs to SVG and Annotated EXPRESS
 
 The `suma convert-jsdai` command converts JSDAI EXPRESS-G diagram outputs

data/exe/suma

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "suma/cli"
+require "suma"
 
 Suma::Cli::Core.start(ARGV)

data/lib/suma/cli/build.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "thor"
-require_relative "../thor_ext"
 
 module Suma
   module Cli
@@ -15,10 +14,6 @@ module Suma
                                 desc: "Generate file that contains all schemas in the collection."
 
       def 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."

data/lib/suma/cli/check_svg_quality.rb

@@ -1,12 +1,6 @@
 # frozen_string_literal: true
 
 require "pathname"
-require_relative "../svg_quality"
-require_relative "../svg_quality/report"
-require_relative "../svg_quality/batch_report"
-require_relative "../svg_quality/formatters/terminal_formatter"
-require_relative "../svg_quality/formatters/json_formatter"
-require_relative "../svg_quality/formatters/yaml_formatter"
 
 module Suma
   module Cli

data/lib/suma/cli/compare.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "thor"
-require_relative "../schema_comparer"
 
 module Suma
   module Cli

data/lib/suma/cli/convert_jsdai.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require "thor"
-require_relative "../thor_ext"
-require_relative "../jsdai"
 require "fileutils"
 
 module Suma

data/lib/suma/cli/core.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "thor"
+require "expressir"
+require "expressir/cli"
+
+module Suma
+  module Cli
+    # Top-level CLI entrypoint.
+    #
+    # Each command delegates to a dedicated Thor class under +Suma::Cli::+,
+    # which reparses ARGV and therefore owns the canonical +option+
+    # declarations. Re-declaring options here would duplicate the inner
+    # classes' declarations and cause help text and validation logic to
+    # drift. Options are declared in exactly one place (the inner class).
+    #
+    # The exception is +check_svg_quality+, which constructs its analyzer
+    # inline (no inner Thor class), so its options belong here.
+    class Core < Thor
+      extend ThorExt::Start
+
+      desc "build METANORMA_SITE_MANIFEST",
+           "Build collection specified in site manifest (`metanorma*.yml`)"
+      def build(_site_manifest)
+        Cli::Build.start
+      end
+
+      desc "generate-schemas METANORMA_MANIFEST_FILE SCHEMA_MANIFEST_FILE",
+           "Generate EXPRESS schema manifest file from Metanorma site manifest"
+      def generate_schemas(_metanorma_manifest_file, _schema_manifest_file)
+        Cli::GenerateSchemas.start
+      end
+
+      desc "reformat EXPRESS_FILE_PATH",
+           "Reformat EXPRESS files"
+      def reformat(_express_file_path)
+        Cli::Reformat.start
+      end
+
+      desc "extract-terms SCHEMA_MANIFEST_FILE GLOSSARIST_OUTPUT_PATH",
+           "Extract terms from SCHEMA_MANIFEST_FILE into " \
+           "Glossarist v3 format"
+      def extract_terms(_schema_manifest_file, _glossarist_output_path)
+        Cli::ExtractTerms.start
+      end
+
+      desc "generate-register SCHEMA_MANIFEST_FILE OUTPUT_PATH",
+           "Generate a Glossarist register.yaml with hierarchical sections"
+      def generate_register(_schema_manifest_file, _output_path)
+        Cli::GenerateRegister.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)
+        Cli::ConvertJsdai.start
+      end
+
+      desc "export *FILES",
+           "Export EXPRESS schemas from manifest files or " \
+           "standalone EXPRESS files"
+      def export(*_files)
+        Cli::Export.start
+      end
+
+      desc "compare TRIAL_SCHEMA REFERENCE_SCHEMA",
+           "Compare EXPRESS schemas using eengine and generate Change YAML"
+      def compare(_trial_schema, _reference_schema)
+        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)
+        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
+  end
+end

data/lib/suma/cli/export.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "thor"
-require_relative "../thor_ext"
 
 module Suma
   module Cli
@@ -18,8 +17,6 @@ module Suma
                    desc: "Create ZIP archive of exported schemas"
 
       def export(*files)
-        require_relative "../schema_exporter"
-        require_relative "../utils"
         require "expressir"
 
         validate_files(files)