expressir 2.1.18 → 2.1.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d20d882f0b9e6b30860d41294671b6c235cff0cc024521276ca9ca3283e1f79a
-  data.tar.gz: 8625cc4fa425c9d02c73e056b8ee9ee8aa69eaab566452b44e1a1ae137faacf6
+  metadata.gz: b0e1c52810ce3b1361d9f8327c0c270ac3a7f366f16d3b3236a0ed3e559155a9
+  data.tar.gz: a852899cbf8d6a7747b8609ae7ec00736eddfcfad6a9fd8d410cd453811a4188
 SHA512:
-  metadata.gz: 88dc6630b82e7b7c01f49df868664caa34d54e5d21d2af4d786094f7c880b7f39bbd7295f084e1e3558f9705a7798364740dfdc40086241b7d20e36419ae75b9
-  data.tar.gz: 0f87bcc8eda3e6b321202f64b9bcfc5a357c8b3ee4c1f0dc481a7610e9680f2af50a0b257838809d05888fda647f28be9583e1debfac557fa31c78b1b2c66fb2
+  metadata.gz: f8db59aa54a5a1edd29165ec3b79e9e98a35ebd51d8d0184735417c96bbd9d178328ddad2feef11f177bc140bd514913d5581f0c01ba8f9ee25b5a3cdf35a7d2
+  data.tar.gz: fef82dcf757767e2a1eea5b252083f0b8f9db85226263f74c7979fde768caa25895df05cca29ac525b799f21ffd19dfd138e26087d3351e0a210b62746bd1867

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-03-21 10:31:17 UTC using RuboCop version 1.74.0.
+# on 2025-06-05 12:41:11 UTC using RuboCop version 1.75.2.
 # 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
@@ -21,6 +21,12 @@ Layout/LineLength:
   Exclude:
     - 'lib/expressir/express/parser.rb'
 
+# Offense count: 1
+# Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
+Lint/DuplicateBranch:
+  Exclude:
+    - 'lib/expressir/coverage.rb'
+
 # Offense count: 3
 Lint/ShadowingOuterLocalVariable:
   Exclude:
@@ -35,13 +41,17 @@ Lint/UnusedMethodArgument:
     - 'lib/expressir/express/cache.rb'
     - 'lib/expressir/express/parser.rb'
 
-# Offense count: 61
+# Offense count: 75
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
     - 'lib/expressir/benchmark.rb'
-    - 'lib/expressir/cli.rb'
+    - 'lib/expressir/commands/benchmark.rb'
+    - 'lib/expressir/commands/benchmark_cache.rb'
+    - 'lib/expressir/commands/coverage.rb'
+    - 'lib/expressir/commands/validate.rb'
     - 'lib/expressir/config.rb'
+    - 'lib/expressir/coverage.rb'
     - 'lib/expressir/express/formatter.rb'
     - 'lib/expressir/express/hyperlink_formatter.rb'
     - 'lib/expressir/express/parser.rb'
@@ -50,17 +60,19 @@ Metrics/AbcSize:
     - 'lib/expressir/model/declarations/schema.rb'
     - 'lib/expressir/model/model_element.rb'
 
-# Offense count: 2
+# Offense count: 1
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 141
+  Max: 143
 
-# Offense count: 45
+# Offense count: 54
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
     - 'lib/expressir/benchmark.rb'
+    - 'lib/expressir/commands/coverage.rb'
+    - 'lib/expressir/coverage.rb'
     - 'lib/expressir/express/formatter.rb'
     - 'lib/expressir/express/model_visitor.rb'
     - 'lib/expressir/express/parser.rb'
@@ -69,16 +81,18 @@ Metrics/CyclomaticComplexity:
     - 'lib/expressir/model/model_element.rb'
     - 'spec/support/model_element_helper.rb'
 
-# Offense count: 80
+# Offense count: 99
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 44
+  Max: 82
 
-# Offense count: 35
+# Offense count: 43
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
     - 'lib/expressir/benchmark.rb'
+    - 'lib/expressir/commands/coverage.rb'
+    - 'lib/expressir/coverage.rb'
     - 'lib/expressir/express/formatter.rb'
     - 'lib/expressir/express/visitor.rb'
     - 'lib/expressir/model/declarations/schema.rb'
@@ -89,6 +103,13 @@ Performance/FixedSize:
   Exclude:
     - 'lib/expressir/express/formatter.rb'
 
+# Offense count: 6
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: AllowRegexpMatch.
+Performance/RedundantEqualityComparisonBlock:
+  Exclude:
+    - 'spec/expressir/coverage_spec.rb'
+
 # Offense count: 1
 Style/MissingRespondToMissing:
   Exclude:

data/README.adoc

@@ -80,20 +80,31 @@ Commands:
   expressir format PATH                        # pretty print EXPRESS schema located at PATH
   expressir help [COMMAND]                     # Describe available commands or one specific command
   expressir validate *PATH                     # validate EXPRESS schema located at PATH
+  expressir coverage *PATH                     # List EXPRESS entities and check documentation coverage
   expressir version                            # Expressir Version
 ----
 
-=== Pretty print
+=== Format schema
+
+The `format` command pretty prints an EXPRESS schema, making it more readable
+while preserving its structure.
 
 [source, sh]
 ----
+# Pretty print a schema to stdout
 expressir format schemas/resources/action_schema/action_schema.exp
 ----
 
+This command:
+1. Parses the EXPRESS schema
+2. Formats it with consistent indentation and spacing
+3. Outputs the formatted schema to stdout
+
 === Clean schema
 
-The `clean` command strips remarks and prettifies EXPRESS schemas. You can
-optionally save the result to a file.
+The `clean` command strips remarks and prettifies EXPRESS schemas. This is
+useful for removing all documentation comments while maintaining the schema's
+functional definition. You can optionally save the result to a file.
 
 [source, sh]
 ----
@@ -104,6 +115,46 @@ expressir clean schemas/resources/action_schema/action_schema.exp
 expressir clean schemas/resources/action_schema/action_schema.exp --output clean_schema.exp
 ----
 
+[options="header"]
+|===
+| Option | Description
+| `--output PATH` | Path to save the cleaned schema (optional, defaults to stdout)
+|===
+
+=== Validate schema
+
+The `validate` command performs validation checks on EXPRESS schema files.
+
+It verifies:
+
+. That the schema can be parsed correctly
+. That the schema includes a version string
+
+[source, sh]
+----
+# Validate a single schema
+expressir validate schemas/resources/action_schema/action_schema.exp
+
+# Validate multiple schemas
+expressir validate schemas/resources/action_schema/action_schema.exp schemas/resources/approval_schema/approval_schema.exp
+----
+
+The command reports any schemas that:
+
+* Failed to parse
+* Are missing a version string
+
+If all validations pass, it will display "Validation passed for all EXPRESS schemas."
+
+=== Version
+
+The `version` command displays the current version of the Expressir gem.
+
+[source, sh]
+----
+expressir version
+----
+
 === Benchmarking
 
 Expressir includes powerful benchmarking capabilities for measuring schema
@@ -181,6 +232,244 @@ The benchmark commands support several options:
 When using the `--format json` option, results will be output in JSON format,
 making it easy to parse for further analysis or visualization.
 
+=== Documentation coverage
+
+Expressir can analyze EXPRESS schemas to check for documentation coverage. This helps
+identify which entities are properly documented with remarks and which ones require
+documentation.
+
+==== Analyzing documentation coverage
+
+Use the `coverage` command to check documentation coverage of EXPRESS schemas:
+
+[source, sh]
+----
+# Analyze a single EXPRESS file
+expressir coverage schemas/resources/action_schema/action_schema.exp
+
+# Analyze multiple EXPRESS files
+expressir coverage schemas/resources/action_schema/action_schema.exp schemas/resources/approval_schema/approval_schema.exp
+
+# Analyze all EXPRESS files in a directory (recursively)
+expressir coverage schemas/resources/
+
+# Analyze files specified in a YAML file
+expressir coverage schemas.yml
+----
+
+The output shows which entities are missing documentation, calculates coverage percentages,
+and provides an overall documentation coverage summary.
+
+==== Coverage options
+
+The coverage command supports different output formats and exclusion options:
+
+[options="header"]
+|===
+| Option | Description
+| `--format text` | (Default) Display a human-readable table with coverage information
+| `--format json` | Output in JSON format for programmatic processing
+| `--format yaml` | Output in YAML format for programmatic processing
+| `--exclude TYPES` | Comma-separated list of EXPRESS entity types to exclude from coverage analysis
+|===
+
+==== Excluding entity types from coverage
+
+You can exclude specific EXPRESS entity types from coverage analysis using the
+`--exclude` option.
+
+This is useful when certain entity types don't require documentation coverage,
+such as TYPE entities whose descriptions are generated by template strings.
+
+[source, sh]
+----
+# Exclude TYPE entities from coverage analysis
+expressir coverage --exclude=TYPE schemas/resources/action_schema/action_schema.exp
+
+# Exclude only SELECT type definitions (useful since TYPE descriptions are often template-generated)
+expressir coverage --exclude=TYPE:SELECT schemas/resources/action_schema/action_schema.exp
+
+# Exclude multiple entity types
+expressir coverage --exclude=TYPE,CONSTANT,FUNCTION schemas/resources/action_schema/action_schema.exp
+
+# Exclude parameters and variables (often don't require individual documentation)
+expressir coverage --exclude=PARAMETER,VARIABLE schemas/resources/action_schema/action_schema.exp
+
+# Combine with output format options
+expressir coverage --exclude=TYPE:SELECT --format=json schemas/resources/action_schema/action_schema.exp
+----
+
+==== Elements checked in documentation coverage
+
+Expressir checks documentation coverage for all EXPRESS elements (ModelElement
+subclasses), including:
+
+Schema-level entities:
+
+`TYPE`:: Type definitions (supports subtype exclusion, see below)
+`ENTITY`:: Entity definitions
+`CONSTANT`:: Constant definitions
+`FUNCTION`:: Function definitions
+`RULE`:: Rule definitions
+`PROCEDURE`:: Procedure definitions
+`SUBTYPE_CONSTRAINT`:: Subtype constraint definitions
+`INTERFACE`:: Interface definitions
+
+Nested entities within other constructs:
+
+`PARAMETER`:: Function and procedure parameters
+`VARIABLE`:: Variables within functions, rules, and procedures
+`ATTRIBUTE`:: Entity attributes
+`DERIVED_ATTRIBUTE`:: Derived attributes in entities
+`INVERSE_ATTRIBUTE`:: Inverse attributes in entities
+`UNIQUE_RULE`:: Unique rules within entities
+`WHERE_RULE`:: Where rules within entities and types
+`ENUMERATION_ITEM`:: Items within enumeration types
+`INTERFACE_ITEM`:: Items within interfaces
+`INTERFACED_ITEM`:: Interfaced items
+`SCHEMA_VERSION`:: Schema version information
+`SCHEMA_VERSION_ITEM`:: Schema version items
+
+==== TYPE subtype exclusion
+
+For TYPE elements, you can exclude specific subtypes using the `TYPE:SUBTYPE`
+syntax:
+
+[source, sh]
+----
+# Exclude only SELECT types
+expressir coverage --exclude=TYPE:SELECT schemas/resources/action_schema/action_schema.exp
+
+# Exclude multiple TYPE subtypes
+expressir coverage --exclude=TYPE:SELECT,TYPE:ENUMERATION schemas/resources/action_schema/action_schema.exp
+----
+
+Valid TYPE subtypes that can be excluded:
+
+`AGGREGATE`:: Aggregate type
+`ARRAY`:: Array type
+`BAG`:: Bag type
+`BINARY`:: Binary type
+`BOOLEAN`:: Boolean type
+`ENUMERATION`:: Enumeration type
++
+[example]
+====
+----
+TYPE uuid_relationship_role = ENUMERATION OF
+  (supersedes,
+    merge,
+    split,
+    derive_from,
+    same_as,
+    similar_to);
+END_TYPE;
+----
+====
+
+`GENERIC`:: Generic type
+`GENERIC_ENTITY`:: Generic entity type
++
+[example]
+====
+----
+TYPE uuid_attribute_select = EXTENSIBLE GENERIC_ENTITY SELECT;
+END_TYPE;
+----
+====
+
+`INTEGER`:: Integer type
+`LIST`:: List type
++
+[example]
+====
+----
+TYPE uuid_list_item = LIST [1:?] OF UNIQUE LIST [1:?] OF UNIQUE uuid_attribute_select;
+END_TYPE;
+----
+====
+
+`LOGICAL`:: Logical type
+`NUMBER`:: Number type
+`REAL`:: Real type
+`SELECT`:: Select type
++
+[example]
+====
+----
+TYPE uuid_set_or_list_attribute_select = SELECT
+  (uuid_list_item,
+    uuid_set_item);
+END_TYPE;
+----
+====
+
+`SET`:: Set type
++
+[example]
+====
+----
+TYPE uuid_set_item = SET [1:?] OF uuid_attribute_select;
+END_TYPE;
+----
+====
+
+`STRING`::
+String type
++
+[example]
+====
+----
+TYPE uuid = STRING (36) FIXED;
+END_TYPE;
+----
+====
+
+This is particularly useful since TYPE entities with certain subtypes (like
+SELECT) often have descriptions generated by template strings and may not
+require individual remark item coverage.
+
+NOTE: ISO 10303 excludes documentation coverage for TYPE:SELECT and
+TYPE:ENUMERATION.
+
+If you specify an invalid entity type or subtype, the command will display an
+error message with the list of valid options.
+
+.Example with JSON output:
+[example]
+====
+[source, sh]
+----
+expressir coverage schemas/resources/ --format json
+----
+====
+
+When using JSON or YAML output formats, all file and directory paths are
+displayed relative to the current working directory:
+
+[source, yaml]
+----
+- file: "schemas/resources/action_schema/action_schema.exp"
+  file_basename: action_schema.exp
+  directory: "schemas/resources/action_schema"
+  # ... other fields
+----
+
+==== Coverage output
+
+The default text output displays:
+
+. Directory coverage (when analyzing multiple directories)
+
+. File coverage, showing:
+** File path
+** List of undocumented entities
+** Coverage percentage
+
+. Overall documentation coverage statistics
+
+This helps identify areas of your EXPRESS schemas that need documentation
+improvement.
 
 
 == Usage: Ruby
@@ -318,6 +607,68 @@ schema = repo_drop.schemas.first
 schema.file = "path/to/file.exp"
 ----
 
+=== Documentation coverage analysis
+
+Expressir's documentation coverage feature can be used programmatically to
+analyze and report on documentation coverage of EXPRESS schemas.
+
+[source,ruby]
+----
+# Create a coverage report from a file
+report = Expressir::Coverage::Report.from_file("path/to/schema.exp")
+
+# Or create a report from a repository
+repository = Expressir::Express::Parser.from_file("path/to/schema.exp")
+report = Expressir::Coverage::Report.from_repository(repository)
+
+# Access overall statistics
+puts "Overall coverage: #{report.coverage_percentage}%"
+puts "Total entities: #{report.total_entities.size}"
+puts "Documented entities: #{report.documented_entities.size}"
+puts "Undocumented entities: #{report.undocumented_entities.size}"
+
+# Access file-level reports
+report.file_reports.each do |file_report|
+  puts "File: #{file_report[:file]}"
+  puts "  Coverage: #{file_report[:coverage]}%"
+  puts "  Total entities: #{file_report[:total]}"
+  puts "  Documented entities: #{file_report[:documented]}"
+  puts "  Undocumented entities: #{file_report[:undocumented].join(', ')}"
+end
+
+# Access directory-level reports
+report.directory_reports.each do |dir_report|
+  puts "Directory: #{dir_report[:directory]}"
+  puts "  Coverage: #{dir_report[:coverage]}%"
+  puts "  Total entities: #{dir_report[:total]}"
+  puts "  Documented entities: #{dir_report[:documented]}"
+  puts "  Undocumented entities: #{dir_report[:undocumented]}"
+  puts "  Number of files: #{dir_report[:files]}"
+end
+
+# Generate a structured hash representation
+report_hash = report.to_h  # Contains overall, directories and files sections
+----
+
+You can also use the core methods directly to check documentation status:
+
+[source,ruby]
+----
+# Check if an entity has documentation
+schema = repository.schemas.first
+entity = schema.entities.first
+
+if Expressir::Coverage.entity_documented?(entity)
+  puts "Entity #{entity.id} is documented"
+else
+  puts "Entity #{entity.id} is not documented"
+end
+
+# Find all entities in a schema
+all_entities = Expressir::Coverage.find_entities(schema)
+puts "Found #{all_entities.size} entities in schema #{schema.id}"
+----
+
 
 == Contributing
 

data/expressir.gemspec

@@ -39,6 +39,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "liquid"
   spec.add_dependency "lutaml-model", "~>0.7"
   spec.add_dependency "parslet", "~> 2.0"
+  spec.add_dependency "ruby-progressbar", "~> 1.11"
+  spec.add_dependency "terminal-table", "~> 3.0"
   spec.add_dependency "thor", "~> 1.0"
-  spec.add_dependency "zeitwerk", "~> 2.6"
 end