expressir 2.1.18 → 2.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d20d882f0b9e6b30860d41294671b6c235cff0cc024521276ca9ca3283e1f79a
-  data.tar.gz: 8625cc4fa425c9d02c73e056b8ee9ee8aa69eaab566452b44e1a1ae137faacf6
+  metadata.gz: 4b68644d000b4b7d47a7e132922afa9b4e9f1d3fb19ba6c3b9e2a8db28c5fd33
+  data.tar.gz: 132ecfd9ca85168335536626fea46c3648757ccd973823242b04b0744869376c
 SHA512:
-  metadata.gz: 88dc6630b82e7b7c01f49df868664caa34d54e5d21d2af4d786094f7c880b7f39bbd7295f084e1e3558f9705a7798364740dfdc40086241b7d20e36419ae75b9
-  data.tar.gz: 0f87bcc8eda3e6b321202f64b9bcfc5a357c8b3ee4c1f0dc481a7610e9680f2af50a0b257838809d05888fda647f28be9583e1debfac557fa31c78b1b2c66fb2
+  metadata.gz: 895f018faf2bbdd075991d45fa22061459b918f907e568e4481a98dd2e0eb96a312cb98d96e2e7de381c7c85841d05631119f7c26e1773ac634377cdac8e6fe2
+  data.tar.gz: 025421a41b6463548b8ac099fe8b5bc94eb21ee58339f77a6ff028c59ebdb1ac27c5f24ea46050d1fa5b84ee5e80802efcb45b0a549bc733ea833f43c48e0e14

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-04 17:31:42 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
@@ -35,13 +35,17 @@ Lint/UnusedMethodArgument:
     - 'lib/expressir/express/cache.rb'
     - 'lib/expressir/express/parser.rb'
 
-# Offense count: 61
+# Offense count: 71
 # 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 +54,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: 51
 # 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 +75,18 @@ Metrics/CyclomaticComplexity:
     - 'lib/expressir/model/model_element.rb'
     - 'spec/support/model_element_helper.rb'
 
-# Offense count: 80
+# Offense count: 94
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 44
+  Max: 50
 
-# Offense count: 35
+# Offense count: 39
 # 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'

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,115 @@ 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 multiple entity types
+expressir coverage --exclude=TYPE,CONSTANT,FUNCTION schemas/resources/action_schema/action_schema.exp
+
+# Combine with output format options
+expressir coverage --exclude=TYPE --format=json schemas/resources/action_schema/action_schema.exp
+----
+
+Valid entity types that can be excluded:
+
+* `TYPE` - Type definitions
+* `ENTITY` - Entity definitions
+* `CONSTANT` - Constant definitions
+* `FUNCTION` - Function definitions
+* `RULE` - Rule definitions
+* `PROCEDURE` - Procedure definitions
+* `SUBTYPE_CONSTRAINT` - Subtype constraint definitions
+
+If you specify an invalid entity type, the command will display an error message
+with the list of valid types.
+
+.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 +478,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,8 @@ 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

data/lib/expressir/cli.rb

@@ -1,32 +1,32 @@
 require "thor"
 require "yaml"
+require "terminal-table"
+
+require_relative "commands/base"
+require_relative "commands/format"
+require_relative "commands/clean"
+require_relative "commands/benchmark"
+require_relative "commands/benchmark_cache"
+require_relative "commands/validate"
+require_relative "commands/coverage"
+require_relative "commands/version"
 
 module Expressir
   class Cli < Thor
+    # Exit with error code on command failures
+    def self.exit_on_failure?
+      true
+    end
+
     desc "format PATH", "pretty print EXPRESS schema located at PATH"
     def format(path)
-      repository = Expressir::Express::Parser.from_file(path)
-      repository.schemas.each do |schema|
-        puts "\n(* Expressir formatted schema: #{schema.id} *)\n"
-        puts schema.to_s(no_remarks: true)
-      end
+      Commands::Format.new(options).run(path)
     end
 
     desc "clean PATH", "Strip remarks and prettify EXPRESS schema at PATH"
     method_option :output, type: :string, desc: "Output file path (defaults to stdout)"
     def clean(path)
-      repository = Expressir::Express::Parser.from_file(path)
-      formatted_schemas = repository.schemas.map do |schema|
-        # Format schema without remarks
-        schema.to_s(no_remarks: true)
-      end.join("\n\n")
-
-      if options[:output]
-        File.write(options[:output], formatted_schemas)
-        puts "Cleaned schema written to #{options[:output]}"
-      else
-        puts formatted_schemas
-      end
+      Commands::Clean.new(options).run(path)
     end
 
     desc "benchmark FILE_OR_YAML", "Benchmark schema loading performance for a file or list of files from YAML"
@@ -35,18 +35,7 @@ module Expressir
     method_option :save, type: :boolean, desc: "Save benchmark results to file"
     method_option :format, type: :string, desc: "Output format (json, csv, default)"
     def benchmark(path)
-      # Enable benchmarking via configuration
-      Expressir.configuration.benchmark_enabled = true
-      Expressir.configuration.benchmark_ips = options[:ips]
-      Expressir.configuration.benchmark_verbose = options[:verbose]
-      Expressir.configuration.benchmark_save = options[:save]
-      Expressir.configuration.benchmark_format = options[:format] if options[:format]
-
-      if [".yml", ".yaml"].include?(File.extname(path).downcase)
-        benchmark_from_yaml(path)
-      else
-        benchmark_file(path)
-      end
+      Commands::Benchmark.new(options).run(path)
     end
 
     desc "benchmark-cache FILE_OR_YAML", "Benchmark schema loading with caching"
@@ -56,178 +45,24 @@ module Expressir
     method_option :format, type: :string, desc: "Output format (json, csv, default)"
     method_option :cache_path, type: :string, desc: "Path to store the cache file"
     def benchmark_cache(path)
-      # Same options as benchmark + cache_path
-      Expressir.configuration.benchmark_enabled = true
-      Expressir.configuration.benchmark_ips = options[:ips]
-      Expressir.configuration.benchmark_verbose = options[:verbose]
-      Expressir.configuration.benchmark_save = options[:save]
-      Expressir.configuration.benchmark_format = options[:format] if options[:format]
-
-      # Run benchmarks with cache
-      cache_path = options[:cache_path] || generate_temp_cache_path
-
-      if [".yml", ".yaml"].include?(File.extname(path).downcase)
-        benchmark_cache_from_yaml(path, cache_path)
-      else
-        benchmark_cache_file(path, cache_path)
-      end
-    end
-
-    no_commands do
-      def _validate_schema(path)
-        repository = Expressir::Express::Parser.from_file(path)
-        repository.schemas.inject([]) do |acc, schema|
-          acc << schema.id unless schema.version&.value
-          acc
-        end
-      rescue StandardError
-        nil
-      end
-
-      def _print_validation_errors(type, array)
-        return if array.empty?
-
-        puts "#{'*' * 20} RESULTS: #{type.to_s.upcase.tr('_', ' ')} #{'*' * 20}"
-        array.each do |msg|
-          puts msg
-        end
-      end
-
-      def benchmark_file(path)
-        puts "Express Schema Loading Benchmark"
-        puts "--------------------------------"
-
-        repository = Expressir::Benchmark.measure_file(path) do
-          Expressir::Express::Parser.from_file(path)
-        end
-
-        if repository
-          puts "Loaded #{repository.schemas.size} schemas"
-        else
-          puts "Failed to load schema"
-        end
-      end
-
-      def benchmark_from_yaml(yaml_path)
-        puts "Express Schema Loading Benchmark from YAML"
-        puts "--------------------------------"
-
-        # Load schema list from YAML
-        schema_list = YAML.load_file(yaml_path)
-        if schema_list.is_a?(Hash) && schema_list["schemas"]
-          # Handle format: { "schemas": ["path1", "path2", ...] }
-          schema_files = schema_list["schemas"]
-        elsif schema_list.is_a?(Array)
-          # Handle format: ["path1", "path2", ...]
-          schema_files = schema_list
-        else
-          puts "Invalid YAML format. Expected an array of schema paths or a hash with a 'schemas' key."
-          return
-        end
-
-        puts "YAML File: #{yaml_path}"
-        puts "Number of schemas in list: #{schema_files.size}"
-        puts "--------------------------------"
-
-        # Load the schemas
-        Expressir::Benchmark.measure_collection(schema_files) do |file|
-          repository = Expressir::Express::Parser.from_file(file)
-          repository.schemas
-        end
-      end
-
-      def benchmark_cache_file(path, cache_path)
-        puts "Express Schema Loading Benchmark with Caching"
-        puts "--------------------------------"
-        puts "Schema: #{path}"
-        puts "Cache: #{cache_path}"
-        puts "--------------------------------"
-
-        # Benchmark with caching
-        results = Expressir::Benchmark.measure_with_cache(path, cache_path) do |file|
-          Expressir::Express::Parser.from_file(file)
-        end
-
-        if results[:repository]
-          schema_count = results[:repository].schemas.size
-          puts "Loaded #{schema_count} schemas"
-        else
-          puts "Failed to load schema"
-        end
-      end
-
-      def benchmark_cache_from_yaml(yaml_path, cache_path)
-        puts "Express Schema Loading Benchmark with Caching from YAML"
-        puts "--------------------------------"
-
-        # Load schema list from YAML
-        schema_list = YAML.load_file(yaml_path)
-        if schema_list.is_a?(Hash) && schema_list["schemas"]
-          # Handle format: { "schemas": ["path1", "path2", ...] }
-          schema_files = schema_list["schemas"]
-        elsif schema_list.is_a?(Array)
-          # Handle format: ["path1", "path2", ...]
-          schema_files = schema_list
-        else
-          puts "Invalid YAML format. Expected an array of schema paths or a hash with a 'schemas' key."
-          return
-        end
-
-        puts "YAML File: #{yaml_path}"
-        puts "Number of schemas in list: #{schema_files.size}"
-        puts "Cache: #{cache_path}"
-        puts "--------------------------------"
-
-        # Process each file with caching
-        schema_files.each_with_index do |file, index|
-          puts "Processing file #{index + 1}/#{schema_files.size}: #{file}"
-
-          # Benchmark with caching
-          Expressir::Benchmark.measure_with_cache(file, cache_path) do |path|
-            Expressir::Express::Parser.from_file(path)
-          end
-
-          puts "--------------------------------"
-        end
-      end
-
-      def generate_temp_cache_path
-        require "tempfile"
-        Tempfile.new(["expressir_cache", ".bin"]).path
-      end
+      Commands::BenchmarkCache.new(options).run(path)
     end
 
     desc "validate *PATH", "validate EXPRESS schema located at PATH"
-    def validate(*paths) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-      no_version = []
-      no_valid = []
-
-      paths.each do |path|
-        x = Pathname.new(path).realpath.relative_path_from(Dir.pwd)
-        puts "Validating #{x}"
-        ret = _validate_schema(path)
-
-        if ret.nil?
-          no_valid << "Failed to parse: #{x}"
-          next
-        end
-
-        ret.each do |schema_id|
-          no_version << "Missing version string: schema `#{schema_id}` | #{x}"
-        end
-      end
-
-      _print_validation_errors(:failed_to_parse, no_valid)
-      _print_validation_errors(:missing_version_string, no_version)
-
-      exit 1 unless [no_valid, no_version].all?(&:empty?)
+    def validate(*paths)
+      Commands::Validate.new(options).run(paths)
+    end
 
-      puts "Validation passed for all EXPRESS schemas."
+    desc "coverage *PATH", "List EXPRESS entities and check documentation coverage"
+    method_option :format, type: :string, desc: "Output format (text, json, yaml)", default: "text"
+    method_option :exclude, type: :string, desc: "Comma-separated list of EXPRESS entity types to skip from coverage (e.g., TYPE,CONSTANT)"
+    def coverage(*paths)
+      Commands::Coverage.new(options).run(paths)
     end
 
     desc "version", "Expressir Version"
     def version
-      say(Expressir::VERSION)
+      Commands::Version.new(options).run
     end
   end
 end

data/lib/expressir/commands/base.rb

@@ -0,0 +1,32 @@
+module Expressir
+  module Commands
+    class Base
+      attr_reader :options
+
+      def initialize(options = {})
+        @options = options
+      end
+
+      # Common utilities that all commands might need
+      def say(message)
+        # Use instance variable for testability - if output is set, use it
+        if defined?(@output) && @output
+          @output.puts(message)
+        else
+          puts(message)
+        end
+      end
+
+      def exit_with_error(message, exit_code = 1)
+        say message
+        # In test mode, raise an exception instead of exiting
+        # This makes it easier to test error cases
+        if defined?(@test_mode) && @test_mode
+          raise message # Just raise the message as an exception
+        else
+          exit exit_code
+        end
+      end
+    end
+  end
+end