suma 0.1.23 → 0.1.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c9cab2e048b99f3208e2956c0611dd64774a280afbe06cd60fb72474e4a8b4b
-  data.tar.gz: 9b12e455229ec616e08c3cba4d6e7e23adc14193241bfaeb33f605ba29a9ee2e
+  metadata.gz: 9fda8e972931c092b7c01d4eaafda7ada9d0f29739d584123b527bf2b5a75075
+  data.tar.gz: c9efe1f70b118180a770f843a6858b3d73e435349a6148e857516fe603dcb688
 SHA512:
-  metadata.gz: e31649ea7c3e8bd144f212f4f3568a017bcf4a85550d9ad17d8210bb8df674163bdee055484f94bab2d41b42281444bfaff9e8d234cf970e71da5e8dd27f5308
-  data.tar.gz: '0281f7449d90c3979507e7a834091970cfb2f380bcc2a9fe8186f0e4cad2315f3a7e82d8279093d4ca721190c63a24a227d70ee87b05931354c37a6a3ffc7972'
+  metadata.gz: ce79c333f25940d8a0a201a3ff65d40c68d816581c9cfadecf3900684ff2ca043597203e6d5a2fa728dfcdd0bfe5415ce80923ed385273dc0df0518f3f183631
+  data.tar.gz: aa335cf0c8669cd27d5d3b7c715c23d16278337b42db554d9971e0fd1b9a3e9d89e056756e1cc5c08d555635059f83a3688691f05763dcc8a1f267425a8f3ddb

data/.rubocop.yml

@@ -1,6 +1,6 @@
 inherit_from:
-  - .rubocop_todo.yml
   - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
+  - .rubocop_todo.yml
 
 plugins:
 - rubocop-performance

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-10-05 11:55:30 UTC using RuboCop version 1.81.1.
+# on 2025-10-15 10:00:06 UTC using RuboCop version 1.81.1.
 # 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
@@ -18,27 +18,12 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'suma.gemspec'
 
-# Offense count: 70
+# Offense count: 84
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
-  Exclude:
-    - 'lib/suma/cli.rb'
-    - 'lib/suma/cli/build.rb'
-    - 'lib/suma/cli/export.rb'
-    - 'lib/suma/cli/validate.rb'
-    - 'lib/suma/jsdai/figure.rb'
-    - 'lib/suma/jsdai/figure_image.rb'
-    - 'lib/suma/processor.rb'
-    - 'lib/suma/schema_attachment.rb'
-    - 'lib/suma/schema_collection.rb'
-    - 'lib/suma/schema_document.rb'
-    - 'lib/suma/thor_ext.rb'
-    - 'spec/suma/cli/extract_terms_spec.rb'
-    - 'spec/suma/cli/validate_ascii_spec.rb'
-    - 'spec/suma/jsdai/figure_spec.rb'
-    - 'suma.gemspec'
+  Enabled: false
 
 # Offense count: 2
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
@@ -56,35 +41,48 @@ Lint/IneffectiveAccessModifier:
   Exclude:
     - 'lib/suma/cli/export.rb'
 
-# Offense count: 9
+# Offense count: 11
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
+    - 'lib/suma/cli/compare.rb'
     - 'lib/suma/jsdai/figure.rb'
     - 'lib/suma/jsdai/figure_image.rb'
     - 'lib/suma/schema_attachment.rb'
     - 'lib/suma/schema_document.rb'
     - 'lib/suma/thor_ext.rb'
 
-# Offense count: 3
+# Offense count: 6
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
+    - 'lib/suma/cli/compare.rb'
+    - 'lib/suma/eengine/wrapper.rb'
     - 'lib/suma/jsdai/figure.rb'
     - 'lib/suma/jsdai/figure_image.rb'
     - 'lib/suma/thor_ext.rb'
 
-# Offense count: 4
+# Offense count: 5
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 13
+  Max: 60
 
-# Offense count: 1
+# Offense count: 4
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
+    - 'lib/suma/cli/compare.rb'
+    - 'lib/suma/eengine/wrapper.rb'
     - 'lib/suma/jsdai/figure_image.rb'
 
+# Offense count: 1
+# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
+# AllowedMethods: call
+# WaywardPredicates: nonzero?
+Naming/PredicateMethod:
+  Exclude:
+    - 'lib/suma/eengine/wrapper.rb'
+
 # Offense count: 6
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
@@ -94,30 +92,57 @@ Naming/VariableNumber:
     - 'spec/suma/cli/export_spec.rb'
     - 'spec/suma/cli/validate_ascii_spec.rb'
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: MinSize.
 Performance/CollectionLiteralInLoop:
   Exclude:
+    - 'spec/suma/cli/export_spec.rb'
     - 'spec/suma/cli_spec.rb'
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
   Exclude:
     - 'spec/suma/cli/export_spec.rb'
 
-# Offense count: 32
+# Offense count: 51
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 44
 
-# Offense count: 2
+# Offense count: 4
 # Configuration parameters: Max, AllowedIdentifiers, AllowedPatterns.
 RSpec/IndexedLet:
   Exclude:
+    - 'spec/suma/cli/compare_spec.rb'
     - 'spec/suma/cli/export_spec.rb'
 
-# Offense count: 28
+# Offense count: 22
+# Configuration parameters: AssignmentOnly.
+RSpec/InstanceVariable:
+  Exclude:
+    - 'spec/suma/cli/compare_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: have_received, receive
+RSpec/MessageSpies:
+  Exclude:
+    - 'spec/suma/cli/compare_spec.rb'
+
+# Offense count: 46
 RSpec/MultipleExpectations:
   Max: 12
+
+# Offense count: 1
+# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata.
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - '**/spec/routing/**/*'
+    - 'spec/suma/cli/expressir_spec.rb'
+
+# Offense count: 1
+RSpec/StubbedMock:
+  Exclude:
+    - 'spec/suma/cli/compare_spec.rb'

data/Gemfile

@@ -5,6 +5,7 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in suma.gemspec
 gemspec
 
+gem "canon"
 gem "nokogiri"
 gem "rake"
 gem "rspec"

data/README.adoc

@@ -138,8 +138,9 @@ $ suma validate SUBCOMMAND [options]
 ----
 
 Subcommands:
-- `links` - Validate EXPRESS links
-- `ascii` - Check for non-ASCII characters in EXPRESS files
+
+`links`:: Validate EXPRESS links
+`ascii`:: Check for non-ASCII characters in EXPRESS files
 
 ==== Links subcommand
 
@@ -552,38 +553,50 @@ list
 
 ==== General
 
-The `suma export` command exports EXPRESS schemas from a manifest file to a
-specified output directory. This command is useful for extracting plain or
-annotated EXPRESS schemas for distribution or further processing.
+The `suma export` command exports EXPRESS schemas from manifest files and/or
+standalone EXPRESS files to a specified output directory.
+
+This command is useful for extracting plain or annotated EXPRESS schemas for
+distribution or further processing.
 
 [source,sh]
 ----
-$ suma export MANIFEST_FILE [options]
+$ suma export -o OUTPUT_DIR FILE1 [FILE2 FILE3 ...]
 ----
 
 Parameters:
 
-`MANIFEST_FILE`:: Path to the EXPRESS schema manifest file (e.g., "schemas-srl.yml")
+`FILE1 [FILE2 FILE3 ...]`:: One or more files to export. Each file can be:
+
+An EXPRESS schema manifest file (`.yml`, `.yaml`)::: schemas listed in the
+manifest will be exported
+
+An standalone EXPRESS file (`.exp`)::: the schema will be exported directly
 
 Options:
 
 `--output=PATH`, `-o PATH`:: (required) Output directory path
 
-`--additional=PATH`, `-a PATH`:: Additional schemas manifest file to merge
-
 `--[no-]annotations`:: Include annotations (remarks/comments) in exported schemas (default: false)
 
 `--[no-]zip`:: Create ZIP archive of exported schemas (default: false)
 
 ==== Behavior
 
-The command exports schemas while preserving the directory structure from the
-manifest file paths:
+The command exports schemas based on the input file types:
+
+**For EXPRESS schema manifest files:**
 
+* Schemas are exported while preserving the directory structure from the manifest file paths
 * Schemas under `resources/` are exported to `OUTPUT/resources/`
 * Schemas under `modules/` are exported to `OUTPUT/modules/`
 * Other categories (`business_object_models/`, `core_model/`) follow the same pattern
 
+**For standalone EXPRESS files:**
+
+* Schemas are exported directly to the output directory root
+* Output filename format: `{schema_id}.exp`
+
 By default, schemas are exported without annotations (plain EXPRESS). Use the
 `--annotations` flag to include remarks and comments.
 
@@ -591,7 +604,7 @@ The `--zip` flag creates a ZIP archive in addition to the directory output,
 named `OUTPUT.zip`.
 
 [example]
-.To export schemas without annotations
+.To export schemas from a manifest file
 [source,sh]
 ----
 $ bundle exec suma export -o express-files schemas-srl.yml
@@ -599,52 +612,54 @@ $ bundle exec suma export -o express-files schemas-srl.yml
 ----
 
 [example]
-.To export schemas with annotations
+.To export a single plain schema
 [source,sh]
 ----
-$ bundle exec suma export -o express-files --annotations schemas-srl.yml
-# => generates express-files/ directory with annotated EXPRESS schemas
+$ bundle exec suma export -o express-files geometry_schema.exp
+# => generates express-files/geometry_schema.exp
 ----
 
 [example]
-.To export and create ZIP archive
+.To export multiple plain schemas
 [source,sh]
 ----
-$ bundle exec suma export -o express-files --zip schemas-srl.yml
-# => generates both:
-#    - express-files/ directory
-#    - express-files.zip archive
+$ bundle exec suma export -o express-files schema1.exp schema2.exp schema3.exp
+# => generates express-files/{schema1,schema2,schema3}.exp
 ----
 
 [example]
-.To merge additional schemas and export
+.To export from multiple manifest files
 [source,sh]
 ----
-$ bundle exec suma export -o express-files \
-    -a additional-schemas.yml \
-    schemas-srl.yml
+$ bundle exec suma export -o express-files schemas-srl.yml additional-schemas.yml
 # => exports schemas from both manifest files
 ----
 
 [example]
-.To merge multiple additional schemas
+.To export mix of manifest and plain schemas
 [source,sh]
 ----
-$ bundle exec suma export -o express-files \
-    -a additional-schemas-1.yml \
-    -a additional-schemas-2.yml \
-    schemas-srl.yml
-# => exports schemas from primary manifest and all additional manifests
+$ bundle exec suma export -o express-files schemas-srl.yml geometry_schema.exp
+# => exports schemas from manifest with directory structure
+#    plus geometry_schema.exp at the root
 ----
 
 [example]
-.To export with all options
+.To export schemas with annotations
 [source,sh]
 ----
-$ bundle exec suma export -o express-files \
-    -a additional-schemas.yml \
-    schemas-srl.yml
-# => exports schemas from both manifest files
+$ bundle exec suma export -o express-files --annotations schemas-srl.yml
+# => generates express-files/ directory with annotated EXPRESS schemas
+----
+
+[example]
+.To export and create ZIP archive
+[source,sh]
+----
+$ bundle exec suma export -o express-files --zip schemas-srl.yml
+# => generates both:
+#    - express-files/ directory
+#    - express-files.zip archive
 ----
 
 [example]
@@ -654,35 +669,316 @@ $ bundle exec suma export -o express-files \
 $ bundle exec suma export -o express-files \
     --annotations \
     --zip \
-    -a additional-schemas.yml \
-    schemas-srl.yml
-# => generates annotated schemas in both directory and ZIP format,
-#    including schemas from both manifest files
+    schemas-srl.yml geometry_schema.exp
+# => generates annotated schemas in both directory and ZIP format
 ----
 
 ==== Output structure
 
-The exported directory structure mirrors the schema paths in the manifest:
+The exported directory structure depends on the input file types:
 
 [source]
 ----
 express-files/
-├── resources/
+├── geometry_schema.exp          # standalone EXPRESS file (at root)
+├── topology_schema.exp          # standalone EXPRESS file (at root)
+├── resources/                   # from manifest files
 │   ├── action_schema/
 │   │   └── action_schema.exp
 │   └── ...
-├── modules/
+├── modules/                     # from manifest files
 │   ├── activity/
 │   │   ├── arm.exp
 │   │   └── mim.exp
 │   └── ...
-├── business_object_models/
+├── business_object_models/      # from manifest files
 │   └── ...
-└── core_model/
+└── core_model/                  # from manifest files
     └── ...
 ----
 
 
+=== Compare schemas command
+
+==== General
+
+The `suma compare` command compares two EXPRESS schemas using eengine and
+generates an EXPRESS Changes YAML file tracking the differences.
+
+This command is essential for managing schema evolution across versions,
+particularly when working with multiple git branches of the same repository.
+
+[source,sh]
+----
+$ suma compare TRIAL_SCHEMA REFERENCE_SCHEMA --version VERSION [options]
+----
+
+Parameters:
+
+`TRIAL_SCHEMA`:: Path to the new/trial EXPRESS schema file
+`REFERENCE_SCHEMA`:: Path to the old/reference EXPRESS schema file
+
+Options:
+
+`--version=VERSION`, `-v VERSION`:: (required) Version number for this change edition
+`--output=PATH`, `-o PATH`:: Output Change YAML file path (default: `{schema}.changes.yaml` in trial schema directory)
+`--mode=MODE`:: Schema comparison mode: `resource` or `module` (default: `resource`)
+`--trial-stepmod=PATH`:: Override auto-detected trial repository root
+`--reference-stepmod=PATH`:: Override auto-detected reference repository root
+`--verbose`:: Enable verbose output
+
+==== Typical workflow
+
+The compare command is designed for a two-repository workflow where you have
+different branches checked out:
+
+[source,sh]
+----
+# 1. Check out old version at /path/to/repo-old
+# 2. Check out new version at /path/to/repo-new
+# 3. Compare schemas:
+$ suma compare \
+    /path/to/repo-new/schemas/resources/action_schema/action_schema.exp \
+    /path/to/repo-old/schemas/resources/action_schema/action_schema.exp \
+    --version 2
+----
+
+==== Behavior
+
+The command:
+
+* Auto-detects git repository roots from schema file paths
+* Uses detected roots as stepmod paths for eengine
+* Generates or updates `.changes.yaml` file in the trial schema directory
+* **Replaces** existing change edition if the version already exists
+* **Adds** new change edition if the version is different
+
+==== Requirements
+
+This command requires `eengine` to be installed:
+
+* macOS: https://github.com/expresslang/homebrew-eengine
+* Linux: https://github.com/expresslang/eengine-releases
+
+[example]
+.To compare schemas with auto-detection
+[source,sh]
+----
+$ suma compare \
+    ~/iso-10303-new/schemas/resources/support_resource_schema/support_resource_schema.exp \
+    ~/iso-10303-old/schemas/resources/support_resource_schema/support_resource_schema.exp \
+    --version 2
+# => generates or updates support_resource_schema.changes.yaml
+----
+
+[example]
+.To compare with verbose output
+[source,sh]
+----
+$ suma compare schema_new.exp schema_old.exp --version 2 --verbose
+# Shows: eengine version, detected repo roots, XML generation, etc.
+----
+
+[example]
+.To specify custom output location
+[source,sh]
+----
+$ suma compare schema_new.exp schema_old.exp \
+    --version 2 \
+    --output /path/to/custom.changes.yaml
+----
+
+[example]
+.To override auto-detected repository roots
+[source,sh]
+----
+$ suma compare schema_new.exp schema_old.exp \
+    --version 2 \
+    --trial-stepmod ~/repo-new \
+    --reference-stepmod ~/repo-old
+----
+
+==== Generated Change YAML format
+
+The command generates EXPRESS Changes YAML files in the ISO 10303 format:
+
+[source,yaml]
+----
+---
+schema: support_resource_schema
+editions:
+- version: '2'
+  description: 'TYPE text: Underlying Type changed'
+  modifications:
+  - type: TYPE
+    name: text
+----
+
+For complete format documentation, see the
+https://www.expresslang.org/docs/express-changes[EXPRESS Changes specification].
+
+=== Expressir command
+
+==== General
+
+The `suma expressir` command provides access to all Expressir commands for
+working with EXPRESS schemas. This includes documentation coverage analysis,
+schema formatting, validation, and other EXPRESS-related operations.
+
+Expressir is a comprehensive toolkit for EXPRESS schema processing that Suma
+integrates to provide additional functionality beyond Suma's core features.
+
+[source,sh]
+----
+$ suma expressir SUBCOMMAND ...ARGS [options]
+----
+
+Available subcommands:
+
+`coverage`:: Check documentation coverage of EXPRESS schemas
+`format`:: Pretty print EXPRESS schemas
+`clean`:: Strip remarks and prettify EXPRESS schemas
+`validate`:: Validate EXPRESS schemas
+`benchmark`:: Benchmark schema loading performance
+`version`:: Display expressir version
+
+==== Coverage subcommand
+
+The `coverage` subcommand analyzes EXPRESS schemas to determine documentation
+coverage, reporting how many EXPRESS objects (entities, constants, functions,
+types, etc.) have been documented with Annotated EXPRESS.
+
+This addresses the need to measure and improve documentation quality in EXPRESS
+schema collections.
+
+[source,sh]
+----
+$ suma expressir coverage PATH [PATH...] [options]
+----
+
+Parameters:
+
+`PATH`:: One or more paths to analyze. Each path can be:
++
+--
+* An EXPRESS schema manifest file (`.yml`, `.yaml`)
+* A single EXPRESS file (`.exp`)
+* A directory containing EXPRESS files
+--
+
+Options:
+
+`--format=FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+`--output=FILE`:: Output file path for JSON/YAML formats (defaults to
+`coverage_report.json` or `coverage_report.yaml`)
+`--exclude=TYPES`:: Comma-separated list of EXPRESS entity types to exclude
+from coverage analysis (e.g., `TYPE,CONSTANT,TYPE:SELECT`)
+`--ignore-files=FILE`:: Path to YAML file containing array of file patterns
+to ignore from overall coverage calculation
+
+[example]
+.To analyze documentation coverage of a schema collection
+[source,sh]
+----
+$ suma expressir coverage schemas-srl.yml
+----
+
+.To analyze coverage and export as JSON
+[source,sh]
+----
+$ suma expressir coverage schemas-srl.yml --format=json --output=coverage.json
+----
+
+.To analyze with exclusions
+[source,sh]
+----
+$ suma expressir coverage schemas/ --exclude=TYPE:ENUMERATION,PARAMETER
+----
+
+.To analyze multiple sources
+[source,sh]
+----
+$ suma expressir coverage schemas-srl.yml additional-schemas.yml
+----
+
+The coverage report includes:
+
+* Overall coverage statistics (total entities, documented entities, percentage)
+* Per-file coverage details
+* Per-directory coverage summaries
+* List of undocumented entities by type and name
+
+==== Format subcommand
+
+The `format` subcommand pretty-prints EXPRESS schemas.
+
+[source,sh]
+----
+$ suma expressir format PATH
+----
+
+Parameters:
+
+`PATH`:: Path to the EXPRESS schema file to format
+
+[example]
+.To format an EXPRESS schema
+[source,sh]
+----
+$ suma expressir format schema.exp
+----
+
+==== Clean subcommand
+
+The `clean` subcommand strips remarks and prettifies EXPRESS schemas.
+
+[source,sh]
+----
+$ suma expressir clean PATH [options]
+----
+
+Parameters:
+
+`PATH`:: Path to the EXPRESS schema file to clean
+
+Options:
+
+`--output=FILE`:: Output file path (defaults to stdout)
+
+[example]
+.To clean an EXPRESS schema and save to file
+[source,sh]
+----
+$ suma expressir clean schema.exp --output=cleaned_schema.exp
+----
+
+==== Validate subcommand
+
+The `validate` subcommand validates EXPRESS schemas for syntactic correctness.
+
+[source,sh]
+----
+$ suma expressir validate PATH [PATH...]
+----
+
+Parameters:
+
+`PATH`:: One or more paths to EXPRESS schema files or directories to validate
+
+[example]
+.To validate EXPRESS schemas
+[source,sh]
+----
+$ suma expressir validate schema.exp
+$ suma expressir validate schemas/
+----
+
+==== Additional information
+
+For complete documentation of all Expressir commands and options, see the
+https://github.com/lutaml/expressir[Expressir documentation].
+
+
 == Usage: Ruby
 
 === General