expressir 2.1.20 → 2.1.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0e1c52810ce3b1361d9f8327c0c270ac3a7f366f16d3b3236a0ed3e559155a9
-  data.tar.gz: a852899cbf8d6a7747b8609ae7ec00736eddfcfad6a9fd8d410cd453811a4188
+  metadata.gz: fab262d4a8c290f1dc292ff8ea22e9f631356945fb76bed736594dad060078b0
+  data.tar.gz: 45e33a9920262038833f1f00113b12527eb9dc64a71d29d8e0b5f36bd89842ff
 SHA512:
-  metadata.gz: f8db59aa54a5a1edd29165ec3b79e9e98a35ebd51d8d0184735417c96bbd9d178328ddad2feef11f177bc140bd514913d5581f0c01ba8f9ee25b5a3cdf35a7d2
-  data.tar.gz: fef82dcf757767e2a1eea5b252083f0b8f9db85226263f74c7979fde768caa25895df05cca29ac525b799f21ffd19dfd138e26087d3351e0a210b62746bd1867
+  metadata.gz: 3bbc6a59dc02947a9c2ed5971900094ce183a4bbe0bdc4e3e762906d8d0675bc5c3ed145c37f17a406c406db783d4dcac1055938cdef2f54382bf1647bd57a61
+  data.tar.gz: ae2c40bc87334138a4ce2cbfdc04bf699da520f62483bf9a8760117ba00b7d45dde639e0c292b5cdb8a285c1d01bd59aef4f5bf70f976ded713c1d7fb4ec5a61

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-06-05 12:41:11 UTC using RuboCop version 1.75.2.
+# on 2025-06-07 07:39:56 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
@@ -13,6 +13,24 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'expressir.gemspec'
 
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: special_inside_parentheses, consistent, align_braces
+Layout/FirstHashElementIndentation:
+  Exclude:
+    - 'spec/expressir/commands/coverage_ignore_files_spec.rb'
+
+# Offense count: 1
+# 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:
+    - 'spec/expressir/commands/coverage_ignore_files_spec.rb'
+
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
@@ -41,7 +59,7 @@ Lint/UnusedMethodArgument:
     - 'lib/expressir/express/cache.rb'
     - 'lib/expressir/express/parser.rb'
 
-# Offense count: 75
+# Offense count: 79
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
@@ -60,13 +78,13 @@ Metrics/AbcSize:
     - 'lib/expressir/model/declarations/schema.rb'
     - 'lib/expressir/model/model_element.rb'
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
   Max: 143
 
-# Offense count: 54
+# Offense count: 57
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
@@ -81,12 +99,12 @@ Metrics/CyclomaticComplexity:
     - 'lib/expressir/model/model_element.rb'
     - 'spec/support/model_element_helper.rb'
 
-# Offense count: 99
+# Offense count: 103
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 82
 
-# Offense count: 43
+# Offense count: 45
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
@@ -98,19 +116,39 @@ Metrics/PerceivedComplexity:
     - 'lib/expressir/model/declarations/schema.rb'
     - 'lib/expressir/model/model_element.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/PredicateName:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/expressir/coverage.rb'
+
 # Offense count: 5
 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:
     - 'lib/expressir/express/visitor.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInArrayLiteral:
+  Exclude:
+    - 'spec/expressir/commands/coverage_ignore_files_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInHashLiteral:
+  Exclude:
+    - 'spec/expressir/commands/coverage_ignore_files_spec.rb'

data/README.adoc

@@ -271,6 +271,7 @@ The coverage command supports different output formats and exclusion options:
 | `--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
+| `--ignore-files PATH` | Path to YAML file containing array of files to ignore from overall coverage calculation
 |===
 
 ==== Excluding entity types from coverage
@@ -344,6 +345,201 @@ expressir coverage --exclude=TYPE:SELECT schemas/resources/action_schema/action_
 expressir coverage --exclude=TYPE:SELECT,TYPE:ENUMERATION schemas/resources/action_schema/action_schema.exp
 ----
 
+==== FUNCTION subtype exclusion
+
+For FUNCTION elements, you can exclude inner functions (functions nested within
+other functions, rules, or procedures) using the `FUNCTION:INNER` syntax:
+
+[source, sh]
+----
+# Exclude inner functions from coverage analysis
+expressir coverage --exclude=FUNCTION:INNER schemas/resources/action_schema/action_schema.exp
+
+# Combine with other exclusions
+expressir coverage --exclude=TYPE:SELECT,FUNCTION:INNER schemas/resources/action_schema/action_schema.exp
+----
+
+This is useful when you want to focus documentation coverage on top-level
+functions while excluding nested helper functions that may not require
+individual documentation. The exclusion works recursively, excluding functions
+at any nesting level within other constructs.
+
+Valid FUNCTION subtypes that can be excluded:
+
+`INNER`:: Inner functions nested within other functions, rules, or procedures (at any depth)
++
+[example]
+====
+----
+FUNCTION outer_function : BOOLEAN;
+  -- This inner function would be excluded with FUNCTION:INNER
+  FUNCTION inner_helper_function : BOOLEAN;
+    -- Even deeply nested functions are excluded
+    FUNCTION deeply_nested_function : BOOLEAN;
+      RETURN (TRUE);
+    END_FUNCTION;
+    RETURN (TRUE);
+  END_FUNCTION;
+
+  RETURN (TRUE);
+END_FUNCTION;
+
+RULE example_rule FOR (some_entity);
+  -- Inner functions in rules are also excluded
+  FUNCTION inner_function_in_rule : BOOLEAN;
+    RETURN (TRUE);
+  END_FUNCTION;
+WHERE
+  WR1: inner_function_in_rule();
+END_RULE;
+
+PROCEDURE example_procedure;
+  -- Inner functions in procedures are also excluded
+  FUNCTION inner_function_in_procedure : BOOLEAN;
+    RETURN (TRUE);
+  END_FUNCTION;
+END_PROCEDURE;
+----
+====
+
+The `FUNCTION:INNER` exclusion helps maintain focus on documenting the primary
+API functions while ignoring implementation details of nested helper functions.
+
+==== Ignoring files from coverage calculation
+
+You can exclude entire files from the overall coverage calculation using the
+`--ignore-files` option. This is useful when you have files that should not
+contribute to the overall documentation coverage statistics, such as test
+schemas, example files, or legacy schemas.
+
+[source, sh]
+----
+# Use ignore files to exclude specific files from coverage calculation
+expressir coverage --ignore-files ignore_list.yaml schemas/resources/
+
+# Combine with other options
+expressir coverage --ignore-files ignore_list.yaml --exclude=TYPE:SELECT --format=json schemas/resources/
+----
+
+===== Ignore files YAML format
+
+The ignore files YAML should contain an array of file patterns. Each pattern
+can be either an exact file path or use glob patterns for matching multiple files.
+
+.ignore_list.yaml
+[source, yaml]
+----
+# Array of file patterns to ignore
+- examples/test_schema.exp                    # Exact file path
+- examples/*_test_*.exp                       # Glob pattern for test files
+- legacy/old_*.exp                           # Glob pattern for legacy files
+- temp/temporary_schema.exp                   # Another exact path
+----
+
+===== Pattern matching behavior
+
+File patterns in the ignore files YAML support:
+
+* **Exact paths**: Match specific files exactly
+* **Glob patterns**: Use `*` for wildcard matching
+* **Relative paths**: Patterns are resolved relative to the YAML file's directory
+* **Absolute paths**: Full system paths are also supported
+
+[source, yaml]
+----
+# Examples of different pattern types
+- schemas/action_schema/action_schema.exp     # Exact relative path
+- /full/path/to/schema.exp                   # Absolute path
+- schemas/**/test_*.exp                      # Recursive glob pattern
+- temp/*.exp                                 # All .exp files in temp directory
+----
+
+===== Behavior of ignored files
+
+When files are ignored using the `--ignore-files` option:
+
+. **Excluded from overall statistics**: Ignored files do not contribute to the
+   overall coverage percentage calculation
+
+. **Still processed and reported**: Ignored files are still analyzed and appear
+   in the output, but marked with an `ignored: true` flag
+
+. **Separate reporting section**: In JSON/YAML output formats, ignored files
+   appear in both the main `files` section (with the ignored flag) and in a
+   separate `ignored_files` section
+
+. **Overall statistics updated**: The overall statistics include additional
+   fields showing the count of ignored files and entities
+
+.Example JSON output with ignored files:
+[source, json]
+----
+{
+  "overall": {
+    "coverage_percentage": 75.0,
+    "total_entities": 100,
+    "documented_entities": 75,
+    "undocumented_entities": 25,
+    "ignored_files_count": 2,
+    "ignored_entities_count": 15
+  },
+  "files": [
+    {
+      "file": "schemas/main_schema.exp",
+      "ignored": false,
+      "coverage": 80.0,
+      "total": 50,
+      "documented": 40,
+      "undocumented": ["entity1", "entity2"]
+    },
+    {
+      "file": "examples/test_schema.exp",
+      "ignored": true,
+      "matched_pattern": "examples/*_test_*.exp",
+      "coverage": 20.0,
+      "total": 10,
+      "documented": 2,
+      "undocumented": ["test_entity1", "test_entity2"]
+    }
+  ],
+  "ignored_files": [
+    {
+      "file": "examples/test_schema.exp",
+      "matched_pattern": "examples/*_test_*.exp",
+      "coverage": 20.0,
+      "total": 10,
+      "documented": 2,
+      "undocumented": ["test_entity1", "test_entity2"]
+    }
+  ]
+}
+----
+
+===== Error handling
+
+The ignore files functionality handles various error conditions gracefully:
+
+* **Missing YAML file**: If the specified ignore files YAML doesn't exist, a
+  warning is displayed and coverage analysis continues normally
+
+* **Invalid YAML format**: If the YAML file is malformed or doesn't contain an
+  array, a warning is displayed and the file is ignored
+
+* **Non-matching patterns**: Patterns that don't match any files are silently
+  ignored (no error or warning)
+
+* **Permission errors**: File access errors are reported as warnings
+
+===== Use cases for ignore files
+
+Common scenarios where ignore files are useful:
+
+* **Test schemas**: Exclude test or example schemas from production coverage metrics
+* **Legacy files**: Ignore old schemas that are being phased out
+* **Generated files**: Exclude automatically generated schemas
+* **Work-in-progress**: Temporarily ignore files under development
+* **Different coverage standards**: Apply different documentation standards to different file sets
+
 Valid TYPE subtypes that can be excluded:
 
 `AGGREGATE`:: Aggregate type

data/lib/expressir/cli.rb

@@ -57,6 +57,7 @@ module Expressir
     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,TYPE:SELECT)"
     method_option :output, type: :string, desc: "Output file path for JSON/YAML formats (defaults to coverage_report.json/yaml)"
+    method_option :ignore_files, type: :string, desc: "Path to YAML file containing array of files to ignore from overall coverage calculation"
     def coverage(*paths)
       Commands::Coverage.new(options).run(paths)
     end

data/lib/expressir/commands/coverage.rb

@@ -32,27 +32,28 @@ module Expressir
 
       def collect_reports(paths)
         reports = []
+        ignored_files = parse_ignore_files
 
         paths.each do |path|
-          handle_path(path, reports)
+          handle_path(path, reports, ignored_files)
         end
 
         reports
       end
 
-      def handle_path(path, reports)
+      def handle_path(path, reports, ignored_files)
         if File.directory?(path)
-          handle_directory(path, reports)
+          handle_directory(path, reports, ignored_files)
         elsif File.extname(path).downcase == ".exp"
-          handle_express_file(path, reports)
+          handle_express_file(path, reports, ignored_files)
         elsif [".yml", ".yaml"].include?(File.extname(path).downcase)
-          handle_yaml_manifest(path, reports)
+          handle_yaml_manifest(path, reports, ignored_files)
         else
           say "Unsupported file type: #{path}"
         end
       end
 
-      def handle_directory(path, reports)
+      def handle_directory(path, reports, ignored_files)
         say "Processing directory: #{path}"
         exp_files = Dir.glob(File.join(path, "**", "*.exp"))
         if exp_files.empty?
@@ -79,26 +80,26 @@ module Expressir
             progress.increment
           end
           skip_types = parse_skip_types
-          report = Expressir::Coverage::Report.from_repository(repository, skip_types)
+          report = Expressir::Coverage::Report.from_repository(repository, skip_types, ignored_files)
           reports << report
         rescue StandardError => e
           say "Error processing directory #{path}: #{e.message}"
         end
       end
 
-      def handle_express_file(path, reports)
+      def handle_express_file(path, reports, ignored_files)
         say "Processing file: #{path}"
         begin
           # For a single file, we don't need a progress bar
           skip_types = parse_skip_types
-          report = Expressir::Coverage::Report.from_file(path, skip_types)
+          report = Expressir::Coverage::Report.from_file(path, skip_types, ignored_files)
           reports << report
         rescue StandardError => e
           say "Error processing file #{path}: #{e.message}"
         end
       end
 
-      def handle_yaml_manifest(path, reports)
+      def handle_yaml_manifest(path, reports, ignored_files)
         say "Processing YAML manifest: #{path}"
         begin
           schema_list = YAML.load_file(path)
@@ -149,7 +150,7 @@ module Expressir
 
             # Create and add the report
             skip_types = parse_skip_types
-            report = Expressir::Coverage::Report.from_repository(repository, skip_types)
+            report = Expressir::Coverage::Report.from_repository(repository, skip_types, ignored_files)
             reports << report
           end
         rescue StandardError => e
@@ -258,20 +259,39 @@ module Expressir
       end
 
       def build_structured_report(reports)
-        {
-          "overall" => {
-            "total_entities" => reports.sum { |r| r.total_entities.size },
-            "documented_entities" => reports.sum { |r| r.documented_entities.size },
-            "undocumented_entities" => reports.sum { |r| r.undocumented_entities.size },
-            "coverage_percentage" => if reports.sum { |r| r.total_entities.size }.positive?
-                                       (reports.sum { |r| r.documented_entities.size }.to_f / reports.sum { |r| r.total_entities.size } * 100).round(2)
-                                     else
-                                       100.0
-                                     end,
-          },
+        # Calculate ignored file statistics
+        ignored_files = reports.flat_map(&:ignored_file_reports)
+        ignored_entities_count = ignored_files.sum { |f| f["total"] }
+
+        overall_stats = {
+          "total_entities" => reports.sum { |r| r.total_entities.size },
+          "documented_entities" => reports.sum { |r| r.documented_entities.size },
+          "undocumented_entities" => reports.sum { |r| r.undocumented_entities.size },
+          "coverage_percentage" => if reports.sum { |r| r.total_entities.size }.positive?
+                                     (reports.sum { |r| r.documented_entities.size }.to_f / reports.sum { |r| r.total_entities.size } * 100).round(2)
+                                   else
+                                     100.0
+                                   end,
+        }
+
+        # Add ignored file information if there are any
+        if ignored_files.any?
+          overall_stats["ignored_files_count"] = ignored_files.size
+          overall_stats["ignored_entities_count"] = ignored_entities_count
+        end
+
+        structured_report = {
+          "overall" => overall_stats,
           "files" => reports.flat_map(&:file_reports),
           "directories" => reports.flat_map(&:directory_reports),
         }
+
+        # Add ignored files section if there are any
+        if ignored_files.any?
+          structured_report["ignored_files"] = ignored_files
+        end
+
+        structured_report
       end
 
       def display_json_output(reports)
@@ -307,11 +327,11 @@ module Expressir
         requested_types
       end
 
-      # Validate a single skip type (supports TYPE:SUBTYPE syntax)
+      # Validate a single skip type (supports TYPE:SUBTYPE and FUNCTION:SUBTYPE syntax)
       # @param type [String] The type to validate
       def validate_skip_type(type)
         if type.include?(":")
-          # Handle TYPE:SUBTYPE format
+          # Handle TYPE:SUBTYPE and FUNCTION:SUBTYPE format
           main_type, subtype = type.split(":", 2)
 
           # Validate main type
@@ -326,8 +346,14 @@ module Expressir
               exit_with_error "Invalid TYPE subtype: #{subtype}. " \
                               "Valid TYPE subtypes are: #{Expressir::Coverage::TYPE_SUBTYPES.join(', ')}"
             end
+          # For FUNCTION, validate subtype
+          elsif main_type == "FUNCTION"
+            unless subtype == "INNER"
+              exit_with_error "Invalid FUNCTION subtype: #{subtype}. " \
+                              "Valid FUNCTION subtypes are: INNER"
+            end
           else
-            exit_with_error "Subtype syntax (#{type}) is only supported for TYPE entities"
+            exit_with_error "Subtype syntax (#{type}) is only supported for TYPE and FUNCTION entities"
           end
         else
           # Handle simple type format
@@ -337,6 +363,55 @@ module Expressir
           end
         end
       end
+
+      # Parse and expand ignore files from YAML
+      # @return [Hash] Hash mapping absolute file paths to their matched patterns
+      def parse_ignore_files
+        ignore_files_option = options["ignore_files"] || options[:ignore_files]
+        return {} unless ignore_files_option
+
+        unless File.exist?(ignore_files_option)
+          say "Warning: Ignore files YAML not found: #{ignore_files_option}"
+          return {}
+        end
+
+        begin
+          patterns = YAML.load_file(ignore_files_option)
+          unless patterns.is_a?(Array)
+            say "Warning: Invalid ignore files YAML format. Expected an array of file patterns."
+            return {}
+          end
+
+          ignore_files_dir = File.dirname(File.expand_path(ignore_files_option))
+          expanded_files = {}
+
+          patterns.each do |pattern|
+            # Resolve pattern relative to the YAML file's directory
+            full_pattern = File.expand_path(pattern, ignore_files_dir)
+
+            # Expand glob pattern
+            matched_files = Dir.glob(full_pattern)
+
+            if matched_files.empty?
+              say "Warning: No files matched pattern: #{pattern}"
+            else
+              matched_files.each do |file_path|
+                # Store absolute path and the original pattern that matched it
+                expanded_files[File.expand_path(file_path)] = pattern
+              end
+            end
+          end
+
+          if expanded_files.any?
+            say "Found #{expanded_files.size} files to ignore from patterns"
+          end
+
+          expanded_files
+        rescue StandardError => e
+          say "Warning: Error processing ignore files YAML #{ignore_files_option}: #{e.message}"
+          {}
+        end
+      end
     end
   end
 end

data/lib/expressir/coverage.rb

@@ -59,14 +59,16 @@ module Expressir
     # Represents a documentation coverage report for EXPRESS schemas
     class Report
       attr_reader :repository, :schema_reports, :total_entities, :documented_entities,
-                  :undocumented_entities
+                  :undocumented_entities, :ignored_files
 
       # Initialize a coverage report
       # @param repository [Expressir::Model::Repository] The repository to analyze
       # @param skip_types [Array<String>] Array of entity type names to skip from coverage
-      def initialize(repository, skip_types = [])
+      # @param ignored_files [Hash] Hash mapping absolute file paths to their matched patterns
+      def initialize(repository, skip_types = [], ignored_files = {})
         @repository = repository
         @skip_types = skip_types
+        @ignored_files = ignored_files
         @schema_reports = []
         @total_entities = []
         @documented_entities = []
@@ -78,18 +80,20 @@ module Expressir
       # Create a report from a repository
       # @param repository [Expressir::Model::Repository] The repository to analyze
       # @param skip_types [Array<String>] Array of entity type names to skip from coverage
+      # @param ignored_files [Hash] Hash mapping absolute file paths to their matched patterns
       # @return [Report] The coverage report
-      def self.from_repository(repository, skip_types = [])
-        new(repository, skip_types)
+      def self.from_repository(repository, skip_types = [], ignored_files = {})
+        new(repository, skip_types, ignored_files)
       end
 
       # Create a report from a schema file
       # @param path [String] Path to the schema file
       # @param skip_types [Array<String>] Array of entity type names to skip from coverage
+      # @param ignored_files [Hash] Hash mapping absolute file paths to their matched patterns
       # @return [Report] The coverage report
-      def self.from_file(path, skip_types = [])
+      def self.from_file(path, skip_types = [], ignored_files = {})
         repository = Expressir::Express::Parser.from_file(path)
-        new(repository, skip_types)
+        new(repository, skip_types, ignored_files)
       end
 
       # Calculate the overall coverage percentage
@@ -113,6 +117,39 @@ module Expressir
             absolute_path
           end
 
+          file_report = {
+            "file" => relative_path,
+            "file_basename" => File.basename(absolute_path),
+            "directory" => File.dirname(absolute_path),
+            "total" => report[:total].size,
+            "documented" => report[:documented].size,
+            "undocumented" => report[:undocumented],
+            "coverage" => report[:coverage],
+            "ignored" => report[:ignored] || false,
+          }
+
+          # Add matched pattern for ignored files
+          if report[:ignored] && report[:matched_pattern]
+            file_report["matched_pattern"] = report[:matched_pattern]
+          end
+
+          file_report
+        end
+      end
+
+      # Get ignored file reports
+      # @return [Array<Hash>] Array of ignored file report hashes
+      def ignored_file_reports
+        @schema_reports.select { |report| report[:ignored] }.map do |report|
+          absolute_path = report[:schema].file
+          relative_path = begin
+            Pathname.new(absolute_path).relative_path_from(Pathname.pwd).to_s
+          rescue ArgumentError
+            # If paths are on different drives or otherwise incompatible,
+            # fall back to the absolute path
+            absolute_path
+          end
+
           {
             "file" => relative_path,
             "file_basename" => File.basename(absolute_path),
@@ -121,6 +158,7 @@ module Expressir
             "documented" => report[:documented].size,
             "undocumented" => report[:undocumented],
             "coverage" => report[:coverage],
+            "matched_pattern" => report[:matched_pattern],
           }
         end
       end
@@ -182,11 +220,14 @@ module Expressir
           schema_report = process_schema(schema)
           @schema_reports << schema_report
 
-          @total_entities.concat(schema_report[:total])
-          @documented_entities.concat(schema_report[:documented])
-          @undocumented_entities.concat(schema_report[:undocumented].map do |entity|
-            { schema: schema.id, entity: entity }
-          end)
+          # Only include non-ignored files in overall statistics
+          unless schema_report[:ignored]
+            @total_entities.concat(schema_report[:total])
+            @documented_entities.concat(schema_report[:documented])
+            @undocumented_entities.concat(schema_report[:undocumented].map do |entity|
+              { schema: schema.id, entity: entity }
+            end)
+          end
         end
       end
 
@@ -200,12 +241,19 @@ module Expressir
 
         coverage = entities.empty? ? 100.0 : (documented.size.to_f / entities.size) * 100
 
+        # Check if this schema file is ignored
+        schema_file = File.expand_path(schema.file) if schema.file
+        ignored = @ignored_files.key?(schema_file)
+        matched_pattern = @ignored_files[schema_file] if ignored
+
         {
           schema: schema,
           total: entities,
           documented: documented,
           undocumented: undocumented.map { |e| format_entity(e) },
           coverage: coverage,
+          ignored: ignored,
+          matched_pattern: matched_pattern,
         }
       end
 
@@ -413,16 +461,19 @@ module Expressir
     def self.filter_skipped_entities(entities, skip_types)
       return entities if skip_types.empty?
 
-      # Parse skip_types into simple types and TYPE subtypes
+      # Parse skip_types into simple types, TYPE subtypes, and FUNCTION subtypes
       simple_skips = []
       type_subtype_skips = []
+      function_subtype_skips = []
 
       skip_types.each do |skip_type|
         if skip_type.include?(":")
-          # Handle TYPE:SUBTYPE format
+          # Handle TYPE:SUBTYPE and FUNCTION:SUBTYPE format
           main_type, subtype = skip_type.split(":", 2)
           if main_type == "TYPE" && TYPE_SUBTYPES.include?(subtype)
             type_subtype_skips << subtype
+          elsif main_type == "FUNCTION" && subtype == "INNER"
+            function_subtype_skips << subtype
           end
         else
           # Handle simple type format
@@ -445,6 +496,9 @@ module Expressir
         elsif entity_class == "Expressir::Model::Declarations::Type" && type_subtype_skips.any?
           entity_subtype = get_type_subtype(entity)
           type_subtype_skips.include?(entity_subtype)
+        # Check FUNCTION:INNER exclusions
+        elsif entity_class == "Expressir::Model::Declarations::Function" && function_subtype_skips.include?("INNER")
+          is_inner_function?(entity)
         else
           false
         end
@@ -470,5 +524,18 @@ module Expressir
         underlying_class.split("::").last&.upcase
       end
     end
+
+    # Check if a function is an inner function (nested within another function, rule, or procedure)
+    # @param function_entity [Expressir::Model::Declarations::Function] The function entity to check
+    # @return [Boolean] True if the function is nested within another function, rule, or procedure
+    def self.is_inner_function?(function_entity)
+      return false unless function_entity.respond_to?(:parent) && function_entity.parent
+
+      # Check if the parent is a function, rule, or procedure (not a schema)
+      parent = function_entity.parent
+      parent.is_a?(Expressir::Model::Declarations::Function) ||
+        parent.is_a?(Expressir::Model::Declarations::Rule) ||
+        parent.is_a?(Expressir::Model::Declarations::Procedure)
+    end
   end
 end

data/lib/expressir/express/formatter.rb

@@ -208,7 +208,8 @@ module Expressir
       private
 
       def format_repository(node)
-        node.schemas&.map { |x| format(x) }&.join("\n\n")
+        result = node.schemas&.map { |x| format(x) }&.join("\n\n")
+        result ? "#{result}\n" : ""
       end
 
       def format_declarations_attribute(node)
@@ -1615,39 +1616,65 @@ module Expressir
       end
 
       def format_remark(node, remark)
+        # Handle embedded remarks
         if remark.include?("\n")
           [
             [
-              "(*",
-              '"',
+              "(*\"",
               node.path || node.id,
-              '"',
+              "\"",
             ].join,
             remark,
             "*)",
           ].join("\n")
         else
+          # Handle tail remarks
           [
-            "--",
-            '"',
+            "--\"",
             node.path || node.id,
-            '"',
-            " ",
+            "\" ",
+            remark,
+          ].join
+        end
+      end
+
+      def format_untagged_remark(remark)
+        # Handle embedded remarks
+        if remark.include?("\n")
+          [
+            "(*",
+            remark,
+            "*)",
+          ].join("\n")
+        else
+          # Handle tail remarks
+          [
+            "-- ",
             remark,
           ].join
         end
       end
 
       def format_remarks(node)
+        remarks = []
+
+        # Add tagged remarks
         if node.class.method_defined?(:remarks) && !@no_remarks &&
             !node.remarks.nil?
-
-          node.remarks.map do |remark|
+          remarks.concat(node.remarks.map do |remark|
             format_remark(node, remark)
-          end
-        else
-          []
+          end)
+        end
+
+        # Add untagged remarks
+        if node.respond_to?(:untagged_remarks) && !@no_remarks &&
+            !node.untagged_remarks.nil?
+          remarks.concat(node.untagged_remarks.map do |remark|
+            format_untagged_remark(remark)
+          end)
         end
+
+        remarks
       end
 
       def format_scope_remarks(node)

data/lib/expressir/express/visitor.rb

@@ -271,32 +271,67 @@ module Expressir
         remark_tokens = remark_tokens.reject { |x| @attached_remark_tokens.include?(x) }
 
         # parse remarks, find remark targets
-        tagged_remark_tokens = remark_tokens.map do |span|
+        tagged_remark_tokens = []
+        untagged_remark_tokens = []
+
+        remark_tokens.each do |span|
           text = @source[span[0]..span[1] - 1]
-          _, remark_tag, remark_text = if text.start_with?("--")
-                                         text.match(/^--"([^"]*)"(.*)$/).to_a
-                                       else
-                                         text.match(/^\(\*"([^"]*)"(.*)\*\)$/m).to_a
-                                       end
-
-          if remark_tag
-            remark_target = find_remark_target(node, remark_tag)
-          end
-          if remark_text
-            remark_text = remark_text.strip.force_encoding("UTF-8")
+          remark_type = if text.start_with?("--")
+                          :tail
+                        else
+                          :embedded
+                        end
+
+          if text.start_with?("--\"") && text.include?("\"")
+            # Tagged tail remark: --"tag" content
+            quote_end = text.index("\"", 3)
+            if quote_end
+              remark_target_path = text[3...quote_end]
+              remark_text = text[(quote_end + 1)..].strip.force_encoding("UTF-8")
+              remark_target = find_remark_target(node, remark_target_path)
+              if remark_target
+                tagged_remark_tokens << [span, remark_target, remark_text]
+              end
+            end
+          elsif text.start_with?("(*\"") && text.include?("\"")
+            # Tagged embedded remark: (*"tag" content *)
+            quote_end = text.index("\"", 3)
+            if quote_end
+              remark_target_path = text[3...quote_end]
+              remark_text = text[(quote_end + 1)...-2].strip.force_encoding("UTF-8")
+              remark_target = find_remark_target(node, remark_target_path)
+              if remark_target
+                tagged_remark_tokens << [span, remark_target, remark_text]
+              end
+            end
+          elsif text.start_with?("--")
+            # Untagged tail remark: -- content
+            untagged_text = text[2..].strip.force_encoding("UTF-8")
+            untagged_remark_tokens << [span, untagged_text, remark_type]
+          else
+            # Untagged embedded remark: (* content *)
+            untagged_text = text[2...-2].strip.force_encoding("UTF-8")
+            untagged_remark_tokens << [span, untagged_text, remark_type]
           end
+        end
 
-          [span, remark_target, remark_text]
-        end.select { |x| x[1] }
-
+        # Attach tagged remarks
         tagged_remark_tokens.each do |span, remark_target, remark_text|
-          # attach remark
           remark_target.remarks ||= []
           remark_target.remarks << remark_text
-
-          # mark remark as attached, so that it is not attached again at higher nesting level
           @attached_remark_tokens << span
         end
+
+        # Attach untagged remarks to the current node if it supports them
+        # All ModelElements support untagged remarks, but we may get Arrays here
+        if node.respond_to?(:untagged_remarks) && !untagged_remark_tokens.empty?
+          node.untagged_remarks ||= []
+          untagged_remark_tokens.each do |span, untagged_text, _remark_type|
+            # Handle both embedded and tail remarks
+            node.untagged_remarks << untagged_text
+            @attached_remark_tokens << span
+          end
+        end
       end
 
       def visit_attribute_ref(ctx)

data/lib/expressir/model/identifier.rb

@@ -5,11 +5,13 @@ module Expressir
         mod.attribute :id, :string
         mod.attribute :remarks, :string, collection: true
         mod.attribute :remark_items, ::Expressir::Model::Declarations::RemarkItem, collection: true
+        mod.attribute :untagged_remarks, :string, collection: true
 
         mod.key_value do
           map "id", to: :id
           map "remarks", to: :remarks
           map "remark_items", to: :remark_items
+          map "untagged_remarks", to: :untagged_remarks
         end
       end
     end

data/lib/expressir/model/model_element.rb

@@ -13,6 +13,7 @@ module Expressir
       attribute :_class, :string, default: -> { send(:name) },
                                   polymorphic_class: true
       attribute :source, :string
+      attribute :untagged_remarks, :string, collection: true
 
       # TODO: Add basic mappings that can be inherited by all subclasses
       key_value do

data/lib/expressir/version.rb

@@ -1,3 +1,3 @@
 module Expressir
-  VERSION = "2.1.20".freeze
+  VERSION = "2.1.22".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: expressir
 version: !ruby/object:Gem::Version
-  version: 2.1.20
+  version: 2.1.22
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-05 00:00:00.000000000 Z
+date: 2025-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64