suma 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e610f30a75164dae1cff6714ab56cbc361e037a821ee86b24df8ec433e5f5f88
-  data.tar.gz: 96c1919f27ee0c08bef81b1bff069ec540df610fa929e8224805786283cdf974
+  metadata.gz: 041f227f2bd35c3d90138ab621e51b9abf68206f7b295523da2827d82d6b63c7
+  data.tar.gz: f64aed0f1f4aa096d66c4c299581a2437a991fe6f522b50170b26557b81a0092
 SHA512:
-  metadata.gz: bc8d37be81da1bad8755e2a4e9198f15ba6b75caad83f16562f9a53574b6d2241690cdaa2831c76097bf8b03210237fe9264241e32eb07e3b948544d167bc6ee
-  data.tar.gz: 9d599ad2271c5ff59e5c8e58eb714e8709a87420fa295bd77957e342e9912e255958685f49d866dba773a672354f9be4fe02a7f01bd69d2f2cb6986672449195
+  metadata.gz: ac0d654f283a393c6ae620763920decec16ce2bad44c5cc5722f123bf12ee7539069e35dbbb4909f061fdb14e240f26f033d04e357cfdaff814966cc5f185f8b
+  data.tar.gz: a2a4ca844993d87bc534c77d99e5767aa0f6f86b1f028a15c9a9387ddc761303fcef390a3fe98dce907580b8da1657bb83f96d7c4d0cdd0e03f59d690a1c688f

data/.github/workflows/rake.yml

@@ -2,6 +2,9 @@
 # See https://github.com/metanorma/cimas
 name: rake
 
+permissions:
+  contents: write
+
 on:
   push:
     branches: [ master, main ]

data/.github/workflows/release.yml

@@ -2,6 +2,11 @@
 # See https://github.com/metanorma/cimas
 name: release
 
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
 on:
   workflow_dispatch:
     inputs:
@@ -22,4 +27,3 @@ jobs:
     secrets:
       rubygems-api-key: ${{ secrets.METANORMA_CI_RUBYGEMS_API_KEY }}
       pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}
-

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,35 +1,168 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-12-18 05:29:37 UTC using RuboCop version 1.81.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
 # versions of RuboCop, may require this file to be generated again.
 
 # Offense count: 3
-# Configuration parameters: Severity.
 Gemspec/DuplicatedAssignment:
   Exclude:
     - 'suma.gemspec'
 
 # Offense count: 1
-# Configuration parameters: Severity.
 Gemspec/RequiredRubyVersion:
   Exclude:
     - 'suma.gemspec'
 
-# Offense count: 82
+# Offense count: 35
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# 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: 2
+# 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:
   Exclude:
     - 'lib/suma/jsdai/figure.rb'
+    - 'lib/suma/term_extractor.rb'
 
 # Offense count: 1
 Lint/DuplicateMethods:
@@ -41,48 +174,95 @@ Lint/IneffectiveAccessModifier:
   Exclude:
     - 'lib/suma/cli/export.rb'
 
-# Offense count: 11
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
+# NotImplementedExceptions: NotImplementedError
+Lint/UnusedMethodArgument:
+  Exclude:
+    - 'lib/suma/svg_quality.rb'
+
+# Offense count: 32
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
-    - 'lib/suma/cli/compare.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/schema_attachment.rb'
-    - 'lib/suma/schema_document.rb'
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/manifest_traverser.rb'
+    - 'lib/suma/processor.rb'
+    - 'lib/suma/schema_collection.rb'
+    - 'lib/suma/schema_comparer.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: 6
+# Offense count: 3
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 58
+
+# Offense count: 14
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
-    - 'lib/suma/cli/compare.rb'
+    - 'lib/suma/cli/check_svg_quality.rb'
     - 'lib/suma/eengine/wrapper.rb'
+    - 'lib/suma/express_schema.rb'
     - 'lib/suma/jsdai/figure.rb'
     - 'lib/suma/jsdai/figure_image.rb'
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/schema_comparer.rb'
+    - 'lib/suma/svg_quality/formatters/terminal_formatter.rb'
+    - 'lib/suma/term_extractor.rb'
     - 'lib/suma/thor_ext.rb'
 
-# Offense count: 5
+# Offense count: 31
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 60
+  Max: 63
 
-# Offense count: 4
+# Offense count: 3
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 9
+
+# Offense count: 8
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
-    - 'lib/suma/cli/compare.rb'
     - 'lib/suma/eengine/wrapper.rb'
     - 'lib/suma/jsdai/figure_image.rb'
+    - 'lib/suma/link_validator.rb'
+    - 'lib/suma/schema_comparer.rb'
+    - 'lib/suma/svg_quality/formatters/terminal_formatter.rb'
+    - 'lib/suma/term_extractor.rb'
 
 # Offense count: 1
 # Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
 # AllowedMethods: call
-# WaywardPredicates: nonzero?
+# WaywardPredicates: infinite?, nonzero?
 Naming/PredicateMethod:
   Exclude:
     - 'lib/suma/eengine/wrapper.rb'
 
+# Offense count: 1
+# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
+# NamePrefix: is_, has_, have_, does_
+# ForbiddenPrefixes: is_, has_, have_, does_
+# AllowedMethods: is_a?
+# MethodDefinitionMacros: define_method, define_singleton_method
+Naming/PredicatePrefix:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/suma/term_extractor.rb'
+
 # Offense count: 2
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
@@ -95,9 +275,9 @@ Naming/VariableNumber:
 # Configuration parameters: MinSize.
 Performance/CollectionLiteralInLoop:
   Exclude:
-    - 'spec/suma/cli/compare_spec.rb'
     - 'spec/suma/cli/export_spec.rb'
     - 'spec/suma/cli_spec.rb'
+    - 'spec/suma/schema_comparer_integration_spec.rb'
 
 # Offense count: 2
 # Configuration parameters: Prefixes, AllowedPatterns.
@@ -106,40 +286,40 @@ RSpec/ContextWording:
   Exclude:
     - 'spec/suma/cli/export_spec.rb'
 
-# Offense count: 64
+# Offense count: 111
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
-  Max: 61
+  Max: 60
 
 # Offense count: 4
 # Configuration parameters: Max, AllowedIdentifiers, AllowedPatterns.
 RSpec/IndexedLet:
   Exclude:
-    - 'spec/suma/cli/compare_spec.rb'
     - 'spec/suma/cli/export_spec.rb'
+    - 'spec/suma/schema_comparer_integration_spec.rb'
 
 # Offense count: 22
 # Configuration parameters: AssignmentOnly.
 RSpec/InstanceVariable:
   Exclude:
-    - 'spec/suma/cli/compare_spec.rb'
+    - 'spec/suma/schema_comparer_integration_spec.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 RSpec/IteratedExpectation:
   Exclude:
-    - 'spec/suma/cli/compare_spec.rb'
+    - 'spec/suma/schema_comparer_integration_spec.rb'
 
 # Offense count: 1
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: have_received, receive
 RSpec/MessageSpies:
   Exclude:
-    - 'spec/suma/cli/compare_spec.rb'
+    - 'spec/suma/schema_comparer_integration_spec.rb'
 
-# Offense count: 47
+# Offense count: 87
 RSpec/MultipleExpectations:
-  Max: 23
+  Max: 21
 
 # Offense count: 3
 # Configuration parameters: AllowedGroups.
@@ -147,7 +327,8 @@ RSpec/NestedGroups:
   Max: 4
 
 # Offense count: 1
-# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata.
+# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
+# SupportedInflectors: default, active_support
 RSpec/SpecFilePathFormat:
   Exclude:
     - '**/spec/routing/**/*'
@@ -156,4 +337,32 @@ RSpec/SpecFilePathFormat:
 # Offense count: 1
 RSpec/StubbedMock:
   Exclude:
-    - 'spec/suma/cli/compare_spec.rb'
+    - '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?
+Style/OptionalBooleanParameter:
+  Exclude:
+    - 'lib/suma/cli/check_svg_quality.rb'

data/CLAUDE.md

@@ -0,0 +1,102 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Suma is a Ruby gem for processing EXPRESS schemas (ISO 10303 STEP standards). It reads Metanorma site manifests, discovers EXPRESS schemas, compiles them into documentation, and can export/compare schemas.
+
+## Commands
+
+### Development
+
+```bash
+bundle install              # Install dependencies
+rake spec                   # Run RSpec tests
+rake rubocop                # Run RuboCop linter
+rake                        # Run both tests and linter (default task)
+rspec spec/path/to_spec.rb  # Run a single spec file
+rspec spec/path/to_spec.rb:42  # Run a single test at line 42
+```
+
+### CLI usage
+
+```bash
+exe/suma build METANORMA_YAML                          # Build collection from site manifest
+exe/suma export -o OUTPUT_DIR schema1.yml schema2.exp  # Export schemas (YAML manifest or .exp files)
+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 -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
+```
+
+## Architecture
+
+### Core pipeline (build command)
+
+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. `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`. 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`** — 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::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
+- **metanorma** — document compilation (`.adoc` → XML/HTML/PDF)
+- **lutaml-model** — YAML/XML model serialization (used in `SiteConfig`, `CollectionConfig`)
+- **glossarist** — term extraction output format
+- **eengine** (optional, external binary) — schema comparison via `Eengine::Wrapper`
+
+### Schema comparison flow
+
+The `compare` command uses an external `eengine` binary to diff two EXPRESS schemas, producing XML. `EengineConverter` then converts that XML into a `.changes.yaml` file managed by `Expressir::Changes::SchemaChange`.
+
+## Code style
+
+- 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`
+- 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,7 +6,9 @@ source "https://rubygems.org"
 gemspec
 
 gem "canon"
-gem "metanorma-standoc"
+# 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"