expressir 2.3.6 → 2.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6af1982d1df8fc35cf696c67614f670e45386121feb42b962290a8b40acbc7f6
-  data.tar.gz: c03425e140c7b68391efef97105a3c86124d4269a8bb564515b0e83596a62932
+  metadata.gz: ecbd13317e56cc0139eb317331134c80ba9f5ae95eaf221f2f5e2046ebe95387
+  data.tar.gz: 86dbdfe6818f5c751d11c6fc4cd81e53a60b38145d3f7d80f5bd1b5ff6869815
 SHA512:
-  metadata.gz: a330cbcd461ed7099e473a4a3d8c689f238096afce4c581b35a198bc487ddf5bd7a8bb777af698b1553efc1950eb878aa03874cc0b6904cb451b95a128962998
-  data.tar.gz: 1c995702e07eb2756811f35cbde5dfad4f1d32452c77a45404d551a1bfce1e374789219c72be5383eb5f804cf4489aee05cb2e29def2245ddd2d40cf591fa4c3
+  metadata.gz: b3b26b8456c55b2a5b342d508a2af8f1e3c46ed23f78b96b5900a036292533c33b68f140248f6c8b552f5ed571adc245fe71acf1159b21feca3aa6c0b7bb354f
+  data.tar.gz: 3d33e2d5c850898a8b451a91cd76a9a85736b7e4c6d846c29e1652dc5e8fbb080bec35b2c55a908c7da68bdb32c5b7940162ea88cd811a519643a5f97db65fcf

data/.github/workflows/rake.yml

@@ -3,7 +3,7 @@
 name: rake
 
 permissions:
-  contents: read
+  contents: write
   pull-requests: write
 
 on:

data/.gitignore

@@ -32,6 +32,7 @@ Gemfile.lock
 *.ler
 *.pax
 TODO.*.md
+TODO.refactor/
 debug_*.rb
 measure_mem.rb
 tmp_*.rb
@@ -40,3 +41,4 @@ Gemfile.local
 Gemfile.local.lock
 Gemfile.original
 benchmark/
+CLAUDE.md

data/.rubocop_todo.yml

@@ -1,12 +1,12 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-05-12 14:41:49 UTC using RuboCop version 1.86.0.
+# on 2026-06-05 10:03:10 UTC using RuboCop version 1.86.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: 1084
+# Offense count: 1072
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -24,11 +24,10 @@ Lint/DuplicateBranch:
     - 'lib/expressir/express/remark_attacher.rb'
     - 'lib/expressir/model/search_engine.rb'
 
-# Offense count: 2
+# Offense count: 1
 Lint/DuplicateCaseCondition:
   Exclude:
     - 'lib/expressir/commands/package.rb'
-    - 'lib/expressir/express/formatter.rb'
 
 # Offense count: 1
 Lint/DuplicateMethods:
@@ -51,7 +50,12 @@ Lint/UnusedMethodArgument:
     - 'lib/expressir/express/cache.rb'
     - 'lib/expressir/express/parser.rb'
 
-# Offense count: 239
+# Offense count: 2
+Lint/UselessConstantScoping:
+  Exclude:
+    - 'lib/expressir/express/remark_attacher.rb'
+
+# Offense count: 240
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -67,12 +71,12 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 6
 
-# Offense count: 194
+# Offense count: 190
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 289
+# Offense count: 290
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 167
@@ -82,7 +86,7 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 8
 
-# Offense count: 167
+# Offense count: 162
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -151,7 +155,7 @@ RSpec/ContextWording:
     - 'spec/expressir/commands/validate_ascii_spec.rb'
     - 'spec/expressir/model/repository_spec.rb'
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Exclude:
@@ -160,6 +164,7 @@ RSpec/DescribeClass:
     - '**/spec/routing/**/*'
     - '**/spec/system/**/*'
     - '**/spec/views/**/*'
+    - 'spec/expressir/express/formatter_architecture_spec.rb'
     - 'spec/expressir/integration/package_roundtrip_spec.rb'
 
 # Offense count: 6
@@ -172,7 +177,7 @@ RSpec/DescribeMethod:
     - 'spec/expressir/model/repository_statistics_spec.rb'
     - 'spec/expressir/model/search_engine_advanced_spec.rb'
 
-# Offense count: 453
+# Offense count: 480
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 122
@@ -213,7 +218,7 @@ RSpec/IteratedExpectation:
 RSpec/MessageSpies:
   EnforcedStyle: receive
 
-# Offense count: 583
+# Offense count: 596
 RSpec/MultipleExpectations:
   Max: 114
 
@@ -253,7 +258,7 @@ RSpec/SpecFilePathFormat:
     - 'spec/expressir/model/repository_statistics_spec.rb'
     - 'spec/expressir/model/search_engine_advanced_spec.rb'
 
-# Offense count: 4
+# Offense count: 2
 Security/MarshalLoad:
   Exclude:
     - 'lib/expressir/package/reader.rb'

data/CHANGELOG.md

@@ -0,0 +1,159 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Breaking Changes
+
+#### Repository Structure Change
+
+The `Repository` class now uses a `files` attribute containing `ExpFile` objects instead of a direct `schemas` attribute.
+
+**Old structure:**
+```ruby
+repository = Expressir::Model::Repository.new
+repository.schemas << schema1
+repository.schemas << schema2
+```
+
+**New structure:**
+```ruby
+repository = Expressir::Model::Repository.new
+repository.add_schema(schema1)
+repository.add_schema(schema2)
+
+# Or with files:
+exp_file = Expressir::Express::Parser.from_file("schema.exp")
+repository.files << exp_file
+```
+
+#### ExpFile Model Introduced
+
+A new `ExpFile` class represents a single EXPRESS file with its own preamble remarks and schemas:
+
+```ruby
+# ExpFile has:
+# - path: the file path
+# - schemas: array of schemas in the file
+# - untagged_remarks: file-level preamble remarks
+
+exp_file = Expressir::Model::ExpFile.new(path: "my_schema.exp")
+exp_file.schemas = [schema]
+exp_file.untagged_remarks = [remark_info]
+```
+
+#### Parser Return Type Changed
+
+`Expressir::Express::Parser.from_file` now returns an `ExpFile` instead of a `Repository`:
+
+```ruby
+# Old: returned Repository
+# New: returns ExpFile
+exp_file = Expressir::Express::Parser.from_file("schema.exp")
+exp_file.path   # => "schema.exp"
+exp_file.schemas # => [#<Expressir::Model::Declarations::Schema...>]
+```
+
+#### Error Class Changes
+
+- `InvalidSchemaManifestError` → Use `ManifestValidationError` instead
+- `Expressir::Express::CacheVersionMismatchError` → Use `Expressir::Express::Error::CacheVersionMismatchError`
+
+#### RemarkInfo Required
+
+Remark formatters now require `RemarkInfo` objects instead of strings:
+
+```ruby
+# Old:
+formatter.format_preamble_remark("This is a remark")
+
+# New:
+remark = Expressir::Model::RemarkInfo.new(text: "This is a remark")
+formatter.format_preamble_remark(remark)
+```
+
+### Added
+
+- `Expressir::Model::ExpFile` class for representing EXPRESS files
+- `Expressir::Model::Concerns` module with marker modules for O(1) type checking:
+  - `HasRemarkItems` - types that can have remark_items children
+  - `ScopeContainer` - types that can contain declarations
+  - `HasInformalPropositions` - types supporting informal propositions
+  - `HasWhereRules` - types supporting where rules
+- `Repository#add_schema(schema)` method for adding schemas
+- `Repository#files` attribute for storing ExpFile objects
+- `Package::Builder#normalize_repository` ensures proper serialization format
+
+### Changed
+
+- `Repository#schemas` now returns schemas from both `files` and internal storage
+- `Parser.from_file` returns `ExpFile` instead of `Repository`
+- `Parser.from_files` creates `Repository` with `ExpFile` objects
+- `Parser.from_exp` returns `ExpFile` instead of `Repository`
+- `format_repository` in formatters handles both file-based and direct schemas
+- Preamble remarks now attach to `ExpFile` instead of first `Schema`
+
+### Removed
+
+- All backward compatibility code for legacy serialized data
+- `Repository#schemas=` writer (use `add_schema` instead)
+- Legacy string handling in remark formatters
+- `InvalidSchemaManifestError` alias (use `ManifestValidationError`)
+- Legacy `@schemas` attribute migration in Repository
+- Array-based type checking in `remark_attacher.rb` (replaced with module markers)
+
+### Migration Guide
+
+#### Updating Code That Uses Repository
+
+```ruby
+# Before:
+repo = Expressir::Model::Repository.new
+repo.schemas << schema
+
+# After:
+repo = Expressir::Model::Repository.new
+repo.add_schema(schema)
+```
+
+#### Updating Code That Parses Files
+
+```ruby
+# Before:
+repo = Expressir::Express::Parser.from_file("schema.exp")
+schema = repo.schemas.first
+
+# After:
+exp_file = Expressir::Express::Parser.from_file("schema.exp")
+schema = exp_file.schemas.first
+
+# Or wrap in repository:
+repo = Expressir::Model::Repository.new
+repo.files << Expressir::Express::Parser.from_file("schema.exp")
+```
+
+#### Updating Serialized Packages
+
+Old `.ler` packages need to be regenerated with the new format:
+
+```ruby
+# Load old package (will fail with new code)
+# repo = Expressir::Model::Repository.from_package("old.ler")
+
+# Regenerate by parsing original EXPRESS files
+exp_file = Expressir::Express::Parser.from_file("schema.exp")
+repo = Expressir::Model::Repository.new
+repo.files << exp_file
+repo.export_to_package("new.ler", name: "My Package", version: "1.0.0")
+```
+
+## [2.2.1] - 2024-03-14
+
+### Changed
+
+- Refactored `require` to `autoload` pattern for better load performance
+- Updated error handling to use error classes instead of `abort`

data/docs/_guides/ler/step-packages.adoc

@@ -0,0 +1,385 @@
+---
+title: STEP Standard Packages
+parent: LER Packages
+grand_parent: Guides
+nav_order: 7
+---
+
+= STEP Standard Packages (SRL, SML, SMRL)
+
+== Purpose
+
+This guide explains how to create and use LER packages from STEP standard
+schema collections: the STEPmod Resource Library (SRL), STEPmod Module Library
+(SML), and the combined STEP Resource and Module Library (SMRL).
+
+== References
+
+* link:creating-packages.html[Creating Packages]
+* link:loading-packages.html[Loading Packages]
+* link:querying-packages.html[Querying Packages]
+
+== Concepts
+
+SRL (STEPmod Resource Library):: The collection of 133 resource schemas that
+define core EXPRESS types, entities, and functions used across STEP application
+protocols. Located in `schemas/resources/` of the STEPmod distribution.
+
+SML (STEP Module Library):: The collection of application modules (643 modules,
+1205 ARM and MIM schemas) that define modular data models. Located in
+`schemas/modules/` of the STEPmod distribution.
+
+SMRL (STEP Resource and Module Library):: The combined set of all SRL resource
+schemas and SML module schemas (1341 total).
+
+STEPmod:: The ISO 10303 standards maintenance and development toolkit that
+contains the source EXPRESS schemas for STEP.
+
+== Prerequisites
+
+You need a local copy of the STEPmod distribution (ISO 10303 repository). The
+schema directory structure looks like:
+
+[source]
+----
+iso-10303/
+├── schemas/
+│   ├── resources/              # SRL: 133 resource schemas
+│   │   ├── action_schema/
+│   │   │   └── action_schema.exp
+│   │   ├── geometry_schema/
+│   │   │   └── geometry_schema.exp
+│   │   └── ...
+│   └── modules/                # SML: 643 modules, 1205 schemas
+│       ├── colour/
+│       │   ├── arm.exp
+│       │   └── mim.exp
+│       ├── geometry/
+│       │   ├── arm.exp
+│       │   └── mim.exp
+│       └── ...
+└── ...
+----
+
+== Creating an SRL package
+
+The SRL contains resource schemas that provide common definitions reused across
+STEP application protocols.
+
+=== Using the Ruby API
+
+[source,ruby]
+----
+require "expressir"
+
+base_dir = "/path/to/iso-10303"
+resource_files = Dir.glob("#{base_dir}/schemas/resources/**/*.exp").sort
+
+puts "Building SRL from #{resource_files.length} resource schemas..."
+
+# Parse all resource schemas
+repo = Expressir::Express::Parser.from_files(resource_files)
+
+puts "Parsed #{repo.schemas.length} schemas"
+
+# Export as LER package
+repo.export_to_package(
+  "srl.ler",
+  name: "SRL",
+  description: "STEPmod Resource Library - ISO 10303 resource schemas",
+  serialization_format: "marshal"
+)
+
+puts "Created srl.ler"
+----
+
+=== Performance characteristics
+
+[example]
+====
+* 133 resource schemas
+* Parse time: ~10 seconds
+* Package size: ~5 MB
+====
+
+== Creating an SML package
+
+The SML contains application modules, each with ARM (Application Reference
+Model) and MIM (Mapped Information Model) schemas.
+
+=== Using the Ruby API
+
+[source,ruby]
+----
+require "expressir"
+
+base_dir = "/path/to/iso-10303"
+module_files = Dir.glob("#{base_dir}/schemas/modules/**/{arm,mim}.exp").sort
+
+puts "Building SML from #{module_files.length} module schemas..."
+
+# Parse all module schemas
+repo = Expressir::Express::Parser.from_files(module_files)
+
+puts "Parsed #{repo.schemas.length} schemas"
+
+# Export as LER package
+repo.export_to_package(
+  "sml.ler",
+  name: "SML",
+  description: "STEP Module Library - ISO 10303 application modules",
+  serialization_format: "marshal"
+)
+
+puts "Created sml.ler"
+----
+
+=== Performance characteristics
+
+[example]
+====
+* 1205 module schemas (643 modules)
+* Parse time: ~3 minutes
+* Package size: ~14 MB
+====
+
+== Creating an SMRL package
+
+The SMRL combines all resource and module schemas into a single package.
+
+=== Using the Ruby API
+
+[source,ruby]
+----
+require "expressir"
+
+base_dir = "/path/to/iso-10303"
+resource_files = Dir.glob("#{base_dir}/schemas/resources/**/*.exp").sort
+module_files = Dir.glob("#{base_dir}/schemas/modules/**/{arm,mim}.exp").sort
+all_files = resource_files + module_files
+
+puts "Building SMRL from #{all_files.length} schemas..."
+
+# Parse all schemas
+repo = Expressir::Express::Parser.from_files(all_files)
+
+puts "Parsed #{repo.schemas.length} schemas"
+
+# Export as LER package
+repo.export_to_package(
+  "smrl.ler",
+  name: "SMRL",
+  description: "STEP Resource and Module Library - Complete ISO 10303 schemas",
+  serialization_format: "marshal"
+)
+
+puts "Created smrl.ler"
+----
+
+=== Performance characteristics
+
+[example]
+====
+* 1341 schemas (133 resources + 1205 modules)
+* Parse time: ~8 minutes
+* Package size: ~24 MB
+====
+
+== Loading and searching packages
+
+All three package types use the same loading and querying API.
+
+=== Loading a package
+
+[source,ruby]
+----
+require "expressir"
+
+# Load any .ler package
+repo = Expressir::Model::Repository.from_package("smrl.ler")
+puts "Loaded #{repo.schemas.length} schemas"
+----
+
+Load times are fast regardless of package size:
+
+[example]
+====
+* SRL (133 schemas): ~1 second
+* SML (1205 schemas): ~3 seconds
+* SMRL (1340 schemas): ~5 seconds
+====
+
+=== Finding entities by qualified name
+
+Use `find_entity` for instant lookups when you know the schema and entity name:
+
+[source,ruby]
+----
+entity = repo.find_entity(qualified_name: "geometry_schema.axis2_placement_3d")
+if entity
+  puts "Found: #{entity.id}"
+  puts "Schema: #{entity.parent.id}"
+end
+----
+
+=== Listing all entities
+
+[source,ruby]
+----
+entities = repo.list_entities
+puts "Total: #{entities.length} entities"
+
+entities.first(5).each do |e|
+  puts "  #{e.parent.id}.#{e.id}"
+end
+----
+
+=== Listing entities from a specific schema
+
+[source,ruby]
+----
+entities = repo.list_entities(schema: "mathematical_functions_schema")
+puts "Entities in mathematical_functions_schema: #{entities.length}"
+----
+
+=== Listing all types
+
+[source,ruby]
+----
+types = repo.list_types
+puts "Total: #{types.length} types"
+----
+
+=== Finding a specific schema
+
+[source,ruby]
+----
+schema = repo.schemas.find { |s| s.id == "mathematical_functions_schema" }
+if schema
+  puts "Entities: #{schema.entities&.length || 0}"
+  puts "Types: #{schema.types&.length || 0}"
+  puts "Functions: #{schema.functions&.length || 0}"
+end
+----
+
+=== Using SearchEngine for pattern matching
+
+[source,ruby]
+----
+require "expressir"
+
+repo = Expressir::Model::Repository.from_package("smrl.ler")
+engine = Expressir::Model::SearchEngine.new(repo)
+
+# Find all entities containing "product"
+results = engine.search(pattern: "product", type: "entity")
+results.each do |r|
+  puts "#{r[:schema]}.#{r[:id]}"
+end
+
+# Find all SELECT types
+select_types = engine.list(type: "type", category: "select")
+puts "SELECT types: #{select_types.length}"
+
+# Wildcard search for geometry-related entities
+results = engine.search(pattern: "geometry*")
+----
+
+== Complete build script
+
+Here is a complete script for building all three STEP packages:
+
+[source,ruby]
+----
+#!/usr/bin/env ruby
+# build_step_packages.rb
+
+require "expressir"
+require "optparse"
+
+options = {
+  stepmod_dir: nil,
+  output_dir: ".",
+  packages: ["srl", "sml", "smrl"]
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: build_step_packages.rb [options]"
+
+  opts.on("--stepmod DIR", "Path to iso-10303 directory") do |v|
+    options[:stepmod_dir] = v
+  end
+
+  opts.on("--output DIR", "Output directory (default: .)") do |v|
+    options[:output_dir] = v
+  end
+
+  opts.on("--packages LIST", "Comma-separated list: srl,sml,smrl") do |v|
+    options[:packages] = v.split(",")
+  end
+end.parse!
+
+abort("--stepmod is required") unless options[:stepmod_dir]
+
+base_dir = options[:stepmod_dir]
+
+if options[:packages].include?("srl")
+  puts "=== Building SRL ==="
+  files = Dir.glob("#{base_dir}/schemas/resources/**/*.exp").sort
+  repo = Expressir::Express::Parser.from_files(files)
+  output = File.join(options[:output_dir], "srl.ler")
+  repo.export_to_package(output,
+    name: "SRL",
+    description: "STEPmod Resource Library",
+    serialization_format: "marshal")
+  puts "Created #{output} (#{repo.schemas.length} schemas)"
+end
+
+if options[:packages].include?("sml")
+  puts "\n=== Building SML ==="
+  files = Dir.glob("#{base_dir}/schemas/modules/**/{arm,mim}.exp").sort
+  repo = Expressir::Express::Parser.from_files(files)
+  output = File.join(options[:output_dir], "sml.ler")
+  repo.export_to_package(output,
+    name: "SML",
+    description: "STEP Module Library",
+    serialization_format: "marshal")
+  puts "Created #{output} (#{repo.schemas.length} schemas)"
+end
+
+if options[:packages].include?("smrl")
+  puts "\n=== Building SMRL ==="
+  resource_files = Dir.glob("#{base_dir}/schemas/resources/**/*.exp").sort
+  module_files = Dir.glob("#{base_dir}/schemas/modules/**/{arm,mim}.exp").sort
+  repo = Expressir::Express::Parser.from_files(resource_files + module_files)
+  output = File.join(options[:output_dir], "smrl.ler")
+  repo.export_to_package(output,
+    name: "SMRL",
+    description: "STEP Resource and Module Library",
+    serialization_format: "marshal")
+  puts "Created #{output} (#{repo.schemas.length} schemas)"
+end
+
+puts "\nDone!"
+----
+
+Usage:
+
+[source,bash]
+----
+ruby build_step_packages.rb \
+  --stepmod /path/to/iso-10303 \
+  --output ./packages \
+  --packages srl,sml,smrl
+----
+
+== Summary
+
+* Use `Dir.glob` to collect all EXPRESS files for SRL, SML, or SMRL
+* `Expressir::Express::Parser.from_files` parses all files into a single
+  repository
+* `repo.export_to_package` creates a `.ler` package with pre-built indexes
+* `Repository.from_package` loads packages in seconds
+* `find_entity(qualified_name:)` provides instant lookups
+* `list_entities` and `list_types` enumerate all items
+* `SearchEngine` supports pattern matching and filtering