expressir 2.4.0 → 2.4.2

data/TODO.max-perf/08-builder-build-perf.md

@@ -0,0 +1,45 @@
+# TODO.max-perf/08 — Instrument and optimize Builder.build internals
+
+## Context
+
+TODO.max-perf/06 established the split (CPU-time, parsanol 1.3.30, 4 mid-size
+SRL schemas): native parse 50%, `Builder.build_with_remarks` 48%, references
+2%; within the builder, model build is 1.12s vs remark attachment 0.06s.
+`fast_convert_keys`/`cached_snake_case` are already single-pass and
+allocation-avoiding. The unmeasured stages inside `Builder.build`:
+
+1. `builder.call(snake_data)` — registered handler → lutaml-model
+   instantiation (thousands of attribute setters per schema)
+2. `attach_source_info` → `extract_source_info` → `find_slice` — a
+   depth-capped recursive scan of each node's data subtree; nested data can
+   be re-scanned by ancestors, which is quadratic-ish on deep nesting
+3. The `when Array` recursion
+
+## Work
+
+Findings: fast_convert_keys ran 172k–266k times per schema (~60 calls per
+model node): build() descends into subtrees the parent's deep conversion
+already scanned, so every subtree was re-scanned once per ancestor level.
+attach_source_info is negligible (0.02–0.07s instrumented upper bound);
+the remaining unoptimized share is lutaml-model instantiation inside
+builder.call (upstream territory).
+
+- [x] Instrumented (counters + timers) over topology / presentation /
+      measure / action schemas; split recorded above
+- [x] Implemented the evidenced win: fast_convert_keys marks scanned or
+      converted Hash/Array containers with an invisible ivar and skips
+      them on re-visits
+- [x] Before/after (CPU-time, warm): topology 0.42→0.25s (−40%),
+      presentation 0.27→0.22s (−19%), measure 0.43→0.30s (−30%),
+      action 0.11→0.06s (−48%)
+- [x] Full suite green (1551 examples) including golden-file parser specs;
+      to_hash equality verified against pre-change output on all four
+      schemas
+
+- [x] Handler-level audit (TODO 14 overlap): `expression` 25.8% / `syntax` 15.4% of builder self-CPU — structural dispatch cost (per-level key cascades + build_node wrapper-hash allocations) spread across ~20k nodes; no single fixable waste. Architectural cure = skip the intermediate Hash AST via parsanol's stable parse_with_builder (blocked upstream, TODO 02 / parsanol#59).
+
+## Acceptance
+
+Numbers table for the three stages; either a measured improvement merged or
+the cost definitively attributed to lutaml-model instantiation (which moves
+the next step upstream to lutaml-model).

data/TODO.max-perf/09-grammar-cold-start.md

@@ -0,0 +1,25 @@
+# TODO.max-perf/09 — Grammar cold-start cost and disk cache
+
+## Context
+
+Every process boot builds the parsanol grammar and serializes ~2,300 atoms to
+JSON (`Grammar::Parser.cached_parser` / `cached_grammar_json`) before the
+first parse. Short-lived processes (CLI invocations, tests) pay this on every
+run. parsanol-ruby#59 tracks upstream grammar-to-code compilation; an
+expressir-side JSON disk cache would help regardless.
+
+## Work
+
+Measured (fresh process, 3 runs): boot (require expressir) 161–181ms,
+grammar build ~28ms, JSON serialization ~30ms (83KB), first parse ~25ms.
+Grammar-related cold cost is ~58ms — below the 100ms bar; a disk cache
+would save ~50ms per process at the cost of temp-file staleness machinery.
+
+- [x] Cold-start measured and recorded (above)
+- [x] Documented as negligible — no cache implemented (the larger cold
+      cost is the 161ms require boot, a separate lazy-loading concern)
+
+## Acceptance
+
+Cold-start number recorded; cache implemented with specs if the number
+justifies it, otherwise documented as negligible.

data/TODO.max-perf/10-parser-facade-hygiene.md

@@ -0,0 +1,23 @@
+# TODO.max-perf/10 — Parser facade API hygiene
+
+## Context
+
+The `Parser` facade accumulated internal helpers with public visibility
+during the parallel work: `parse_files_sequentially` and `build_repository`
+are implementation details of `from_files`. `Commands::Coverage` defines a
+`DEFAULT_MAX_PROCESSES` constant that duplicates
+`ParallelFiles::DEFAULT_MAX_PROCESSES` (the CLI option default already
+references the latter directly) — a DRY violation with a dead constant.
+
+## Work
+
+- [x] `parse_files_sequentially` and `build_repository` are now
+      `private_class_method` (no external callers existed)
+- [x] Dead `Coverage::DEFAULT_MAX_PROCESSES` removed; the CLI option
+      default references `ParallelFiles::DEFAULT_MAX_PROCESSES` directly
+- [x] Rubocop clean; full suite green (1551 examples, 40s)
+
+## Acceptance
+
+Facade exposes only the public contract; single source for the worker-cap
+constant.

data/TODO.max-perf/11-ci-green-closeout.md

@@ -0,0 +1,25 @@
+# TODO.max-perf/11 — CI green close-out
+
+## Context
+
+TODO 01's final checkbox. Main carries the Windows fork guard (#353), the
+engine-selection guard pinning :standard adapters on `Gem.win_platform?`
+(#354), and the builder memoization (#355). yeptris mingw remains broken
+upstream (leptris/yeptris#318); the guard must keep it unloaded.
+
+## Work
+
+- [x] Confirmed locally via full `bundle exec rake` (CI-equivalent):
+      1558 examples, 0 failures, rubocop clean across 325 files
+- [x] If red: diagnose the failing job, fix in expressir if the defect is
+      here, escalate upstream otherwise
+
+- [x] Root causes of the red run on 35c1f62 found and fixed: (1) rubocop offenses in the committed benchmark harness + a directive typo in another session's remark perf spec — fixed; (2) sequential-path nil-pad parity bug in from_files — fixed with regression spec; (3) strict-mode spec unguarded on fork-less platforms — guarded; (4) yeptris still loading on Windows: root cause is lutaml-model#798 (configured adapter fell through to detection, loading yeptris before any expressir pin could apply) — fixed upstream + expressir spec_helper now pins json too, with a temporary require-spy proving zero yeptris loads in the suite
+
+- [x] Landed on main via #357 (the #356 merge had gone to its stale base
+      branch `feat/max-perf-todos`; cherry-picked 17aa264 onto main and
+      re-landed as 0576a08)
+
+## Acceptance
+
+rake green on main; TODO 01's checkbox ticked.

data/TODO.max-perf/12-require-boot-profile.md

@@ -0,0 +1,25 @@
+# TODO.max-perf/12 — Require-boot profile and deferrable loads
+
+## Context
+
+TODO 09 measured the cold start: grammar work is only ~58ms; the dominant
+cold cost is `require "expressir"` itself at 161–181ms. Short-lived
+processes (CLI, CI) pay it per invocation. expressir.rb eagerly requires
+`lutaml/model` and `liquid` (for Lutaml::Model::Liquefiable); the gemspec
+also pulls csv, benchmark-ips, ruby-progressbar, nokogiri-adjacent moxml,
+thor — some needed only by CLI commands, not by library consumers.
+
+## Work
+
+- [x] Profiled: per-gem load times via a require-timing probe in a fresh
+      process (results below)
+- [x] Evaluated deferrals: nothing safely deferrable (results below)
+- [x] Full suite green (no deferred loads introduced)
+
+- [x] Per-gem boot profile (fresh process, 2 runs): liquid 172-207ms, lutaml/model 327-559ms (includes moxml chain), thor 19-40ms, expressir own lib ~1ms (autoloads already optimal)
+- [x] Documented as not safely deferrable: liquid backs Lutaml::Model::Liquefiable used by expressir models in metanorma rendering; lutaml-model's boot is upstream (its lazy-loading is tracked there). expressir's own load adds ~1ms — nothing to defer.
+
+## Acceptance
+
+Per-gem boot profile recorded; measured reduction if safely deferrable,
+otherwise documented why not.

data/TODO.max-perf/13-key-conversion-specs.md

@@ -0,0 +1,26 @@
+# TODO.max-perf/13 — Unit specs for the key-conversion memoization
+
+## Context
+
+PR #355 optimized `Builder.fast_convert_keys` with an invisible-ivar marker
+so re-visited containers are skipped. The optimization is currently covered
+only indirectly by golden-file parser specs. The memoization's own contract
+needs pinning so future edits cannot silently break it.
+
+## Work
+
+- [x] Unit specs for the converter (renamed `AstKeyConverter.convert`):
+      - converts CamelCase keys at every depth; untouched data keeps object
+        identity
+      - idempotence: converted results convert to themselves
+      - marked containers are skipped on re-visits (marker on both paths)
+      - frozen input hashes do not raise
+- [x] Marker invisibility: marked hashes remain == to unmarked copies and
+      survive Marshal round-trip without affecting content
+
+- [x] All contract specs written against the extracted public Expressir::Express::AstKeyConverter (key conversion was promoted from a private Builder helper to its own class — MECE: converting AST keys is not building models)
+- [x] Depth conversion, identity preservation, idempotence, marker set on both paths, frozen-hash safety, marker invisibility (== and Marshal), snake_case behavior — spec/expressir/express/ast_key_converter_spec.rb
+
+## Acceptance
+
+Dedicated spec file green; the optimization's behavior is pinned.

data/TODO.max-perf/14-builder-call-handler-audit.md

@@ -0,0 +1,28 @@
+# TODO.max-perf/14 — Per-handler builder.call audit
+
+## Context
+
+TODO 08 attributed the remaining (post-memoization) builder cost to model
+instantiation inside `builder.call` — but that was inferred, not measured
+per handler. ~200 registered handlers exist (builders/*.rb); expressir-side
+waste in the hottest handlers (e.g., redundant intermediate arrays, repeated
+`build()` calls, hash re-shaping) would be ours to fix.
+
+## Work
+
+- [x] Instrumented per handler via a self-time build wrapper (child CPU
+      subtracted) over representative schemas; top handlers recorded below
+- [x] Inspected the top handlers' source (expression_builder.rb et al.)
+- [x] No evident expressir-side waste to fix (see verdict below); the
+      optimization taken instead was the fast_convert_keys memoization
+      (merged in #355) after TODO 08's stage instrumentation
+- [x] Full suite green
+
+- [x] Handler-level instrumentation via a self-time build wrapper (child-time subtracted): 20,270 nodes, 1.58s self CPU over 3 schemas
+- [x] Top handlers: expression 25.8% (3,184 calls), syntax 15.4%, entity_ref 7.7%, simple_expression 6.0%, entity_decl 5.1% — long tail of leaf handlers below 4% each
+- [x] Verdict: no single expressir-side waste; `expression`'s share is structural dispatch (if/elsif key cascades + per-call build_node wrapper-hash allocations). The architectural fix is bypassing the intermediate Hash AST entirely — blocked on parsanol's stable parse_with_builder (TODO 02, parsanol#59). Recorded; not refactored blindly.
+
+## Acceptance
+
+Handler-level numbers table; either a merged improvement or the cost
+definitively attributed to lutaml-model constructors (upstream follow-up).

data/benchmark/srl_benchmark.rb

@@ -17,7 +17,8 @@ require "parsanol/native"
 require "expressir"
 
 # Configuration
-SRL_PATH = "/Users/mulgogi/src/mn/iso-10303/schemas/resources"
+SRL_PATH = ENV["SRL_PATH"] ||
+  "/Users/mulgogi/src/mn/iso-10303/schemas/resources"
 ITERATIONS = (ENV["ITERATIONS"] || 1).to_i
 TIMEOUT_SECONDS = (ENV["TIMEOUT"] || 30).to_i # Timeout per file
 
@@ -104,6 +105,69 @@ def find_exp_files
   end
 end
 
+# Parse one file in a forked child with a hard wall-clock kill.
+# Ruby's Timeout cannot interrupt the native parser (the GVL is held
+# for the whole FFI call), so process isolation is the only reliable
+# guard against pathological backtracking hangs.
+def parse_file_isolated(file, use_native:, timeout: TIMEOUT_SECONDS)
+  rd, wr = IO.pipe
+  pid = fork do
+    rd.close
+    t = Time.now
+    result = { status: "ok", elapsed: 0.0, error: nil }
+    begin
+      if use_native
+        content = File.read(file)
+        Expressir::Express::Parser.from_exp(content, skip_references: true,
+                                                     use_native: true)
+      else
+        Expressir::Express::Parser.from_file(file, skip_references: true,
+                                                   use_native: false)
+      end
+    rescue StandardError => e
+      result[:status] = "err"
+      result[:error] = "#{e.class}: #{e.message[0..60]}"
+    end
+    result[:elapsed] = Time.now - t
+    data = Marshal.dump(result)
+    wr.write([data.bytesize].pack("N"))
+    wr.write(data)
+    wr.close
+    exit!(0)
+  end
+  wr.close
+
+  deadline = Time.now + timeout
+  timed_out = false
+  loop do
+    done = Process.waitpid(pid, Process::WNOHANG)
+    break if done
+
+    if Time.now > deadline
+      Process.kill("TERM", pid)
+      sleep 1
+      begin
+        Process.kill("KILL", pid) if Process.waitpid(pid, Process::WNOHANG).nil?
+      rescue StandardError
+        nil
+      end
+      timed_out = true
+      break
+    end
+    sleep 0.1
+  end
+
+  if timed_out
+    rd.close
+    { status: "timeout", elapsed: timeout.to_f, error: "Timeout after #{timeout}s" }
+  else
+    header = rd.read(4)
+    payload = header && Marshal.load(rd.read(header.unpack1("N"))) # rubocop:disable Security/MarshalLoad
+    rd.close
+    payload
+  end
+end
+
 def count_lines(files)
   files.sum { |f| File.read(f).lines.count }
 end
@@ -176,28 +240,22 @@ class ParserBenchmark
       file_start = Time.now
       schema_lines = File.read(file).lines.count
 
-      begin
-        require "timeout"
-        Timeout.timeout(TIMEOUT_SECONDS) do
-          if @use_native
-            content = File.read(file)
-            Expressir::Express::Parser.from_exp(content, skip_references: true,
-                                                         use_native: true)
-          else
-            Expressir::Express::Parser.from_file(file, skip_references: true)
-          end
-        end
+      result = parse_file_isolated(file, use_native: @use_native)
+      result[:elapsed]
+
+      case result[:status]
+      when "ok"
         iteration_results[:success] += 1
         status = "#{BRIGHT_GREEN}✓#{RESET}"
-      rescue Timeout::Error
+      when "timeout"
         iteration_results[:failed] += 1
         iteration_results[:errors] << { file: File.basename(file),
-                                        error: "Timeout after #{TIMEOUT_SECONDS}s" }
+                                        error: result[:error] }
         status = "#{BRIGHT_YELLOW}⏱#{RESET}"
-      rescue StandardError => e
+      else
         iteration_results[:failed] += 1
         iteration_results[:errors] << { file: File.basename(file),
-                                        error: e.message[0..60] }
+                                        error: result[:error] }
         status = "#{BRIGHT_RED}✗#{RESET}"
       end
 
@@ -346,7 +404,8 @@ print_warmup_start
 warmup_file = files.first
 
 begin
-  Expressir::Express::Parser.from_file(warmup_file, skip_references: true)
+  Expressir::Express::Parser.from_file(warmup_file, skip_references: true,
+                                                    use_native: false)
 rescue StandardError => e
   puts "#{BRIGHT_YELLOW}⚠️  Ruby warmup warning: #{e.message[0..40]}#{RESET}"
 end

data/docs/_tutorials/formatting-schemas.adoc

@@ -0,0 +1,89 @@
+---
+title: Formatting Schemas
+nav_order: 7
+---
+
+== Formatting Schemas
+
+Expressir renders parsed EXPRESS schemas back to source text via the `Formatter`. This is what powers the `expressir format` CLI command, the `Schema#full_source` method, and the Liquid drop exposed to documentation templates.
+
+=== The default formatter
+
+The default `Expressir::Express::Formatter` produces a normalized, consistently-indented version of the schema — comments preserved, original line breaks normalized:
+
+[source,ruby]
+----
+require "expressir"
+
+exp_file = Expressir::Express::Parser.from_file("my_schema.exp")
+schema = exp_file.schemas.first
+
+puts Expressir::Express::Formatter.format(schema)
+----
+
+To format every schema in an ExpFile (or Repository), pass the container:
+
+[source,ruby]
+----
+puts Expressir::Express::Formatter.format(exp_file)
+----
+
+=== Stripping remarks (`no_remarks:`)
+
+Pass `no_remarks: true` to produce a listing without tail (`--`) or embedded (`(* ... *)`) remarks. Useful for diffs, license headers, and "code-only" outputs.
+
+[source,ruby]
+----
+formatter = Class.new(Expressir::Express::Formatter) do
+  def initialize
+    super(no_remarks: true)
+  end
+end
+
+puts formatter.format(schema)
+----
+
+=== CLI: `expressir format`
+
+The CLI wraps the same formatter:
+
+[source,sh]
+----
+expressir format my_schema.exp            # prints formatted output
+expressir format my_schema.exp -o out.exp # writes to a file
+expressir format --no-remarks my_schema.exp
+----
+
+=== Schema head and hyperlink formatters
+
+Two optional mixins layer on top of the base formatter:
+
+* `Expressir::Express::SchemaHeadFormatter` — emits a file-level header banner before each schema (schema name, version, source file).
+* `Expressir::Express::HyperlinkFormatter` — inserts cross-reference hyperlinks (`<<express:...>>` anchors) into the formatted text for use by the Metanorma documentation pipeline.
+
+Combine them by defining a subclass that includes both:
+
+[source,ruby]
+----
+formatter = Class.new(Expressir::Express::Formatter) do
+  include Expressir::Express::SchemaHeadFormatter
+  include Expressir::Express::HyperlinkFormatter
+end
+
+puts formatter.format(exp_file)
+----
+
+=== `Schema#full_source`
+
+For convenience, `Schema#full_source` returns the default-formatted text (memoized). This is what templates should use when they want the canonical rendered schema body:
+
+[source,ruby]
+----
+schema = exp_file.schemas.first
+puts schema.full_source
+----
+
+=== See also
+
+* link:querying-schemas.html[Querying Schemas] — find entities, types, and remarks programmatically.
+* link:liquid-templates.html[Liquid Templates] — use the formatted output inside documentation templates.

data/docs/_tutorials/index.adoc

@@ -58,6 +58,11 @@ Duration: 45-60 minutes
 +
 Analyze and improve schema documentation quality with coverage tools and metrics.
 
+**link:formatting-schemas.html[Formatting Schemas]**::
+Duration: 15-20 minutes
++
+Render parsed schemas back to EXPRESS source text — default formatting, remark stripping, schema-head and hyperlink mixins.
+
 === Tutorial Features
 
 Each tutorial includes:
@@ -121,6 +126,11 @@ Where to go after completing the tutorial
 | Advanced
 | Coverage analysis
 | 45-60 min
+
+| link:formatting-schemas.html[Formatting Schemas]
+| Beginner
+| Rendering schemas to source text
+| 15-20 min
 |===
 
 === Additional Resources

data/docs/lychee.toml

@@ -59,6 +59,9 @@ exclude = [
   "https://www\\.nist\\.gov/.*",
   "https://www\\.steptools\\.com/.*",
 
+  # iso.org returns 403 to bots — the ISO store page is reachable in a browser
+  "https://www\\.iso\\.org/.*",
+
   # GitHub URLs that require authentication
   "https://github\\.com/.*/(issues|pull)/[0-9]+/files.*",
 

data/expressir.gemspec

@@ -4,7 +4,7 @@ require "expressir/version"
 
 Gem::Specification.new do |spec|
   spec.name = "expressir"
-  spec.version = Expressir::VERSION
+  spec.version = Expressir::Version::VERSION
   spec.authors = ["Ribose Inc."]
   spec.email = ["open.source@ribose.com"]
 
@@ -42,7 +42,9 @@ Gem::Specification.new do |spec|
   spec.add_dependency "paint"
   spec.add_dependency "parsanol", "~> 1.3.9", ">= 1.3.9"
   spec.add_dependency "ruby-progressbar", "~> 1.11"
-  spec.add_dependency "rubyzip", "~> 2.3"
+  spec.add_dependency "rubyzip"
   spec.add_dependency "table_tennis"
   spec.add_dependency "thor", "~> 1.0"
+  # Native YAML/JSON engine (lutaml-model opt-in by bundle contents)
+  spec.add_dependency "yeptris", "~> 0.6.1"
 end

data/lib/expressir/cli.rb

@@ -67,6 +67,9 @@ module Expressir
                            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"
+    method_option :max_processes, type: :numeric,
+                                  default: Expressir::Express::ParallelFiles::DEFAULT_MAX_PROCESSES,
+                                  desc: "Parallel parse workers (1 = sequential; falls back to sequential where fork is unavailable)"
     def coverage(*paths)
       Expressir::Commands::Coverage.new(options).run(paths)
     end

data/lib/expressir/commands/changes_import_eengine.rb

@@ -12,8 +12,6 @@ module Expressir
       # @param options [Hash] Additional options
       # @return [Expressir::Changes::SchemaChange]
       def self.from_xml(xml_content, schema_name, version, **)
-        require "expressir/changes"
-
         # Parse into CompareReport using Lutaml::Model
         compare_report = Expressir::Eengine::CompareReport.from_xml(xml_content)
 
@@ -24,8 +22,6 @@ module Expressir
 
       # File-based workflow (backward compatible)
       def self.call(input_file, output_file, schema_name, version, **options)
-        require "expressir/changes"
-
         xml_content = File.read(input_file)
 
         # Load existing schema if output file exists
@@ -51,8 +47,6 @@ module Expressir
 
         def convert_to_schema_change(compare_report, schema_name, version,
 **options)
-          require "expressir/changes"
-
           # Extract changes from CompareReport
           changes = {
             additions: extract_items(compare_report.additions,

data/lib/expressir/commands/changes_validate.rb

@@ -5,8 +5,6 @@ module Expressir
     # Command to validate and normalize EXPRESS Changes YAML files
     class ChangesValidate < Base
       def run(path)
-        require "expressir/changes"
-
         # Check if file exists
         unless File.exist?(path)
           exit_with_error("File not found: #{path}")

data/lib/expressir/commands/clean.rb

@@ -5,7 +5,7 @@ module Expressir
         repository = Expressir::Express::Parser.from_file(path)
         formatted_schemas = repository.schemas.map do |schema|
           # Format schema without remarks
-          schema.to_s(no_remarks: true)
+          schema.format(no_remarks: true)
         end.join("\n\n")
 
         if options[:output]

data/lib/expressir/commands/coverage.rb

@@ -73,7 +73,9 @@ module Expressir
 
         # Parse all files and create a repository with progress tracking
         begin
-          repository = Expressir::Express::Parser.from_files(exp_files) do |filename, _schemas, error|
+          repository = Expressir::Express::Parser.from_files(
+            exp_files, max_processes: options[:max_processes]
+          ) do |filename, _schemas, error|
             if error
               say "  Error processing #{File.basename(filename)}: #{error.message}"
             end
@@ -125,7 +127,9 @@ module Expressir
             )
 
             # Process files with progress tracking
-            repository = Expressir::Express::Parser.from_files(schema_files) do |filename, _schemas, error|
+            repository = Expressir::Express::Parser.from_files(
+              schema_files, max_processes: options[:max_processes]
+            ) do |filename, _schemas, error|
               if error
                 say "  Error processing #{File.basename(filename)}: #{error.message}"
               end

data/lib/expressir/commands/file_violations.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Commands
+    class FileViolations
+      attr_reader :path, :filename, :directory, :violations
+
+      def initialize(file_path)
+        @path = file_path
+        @filename = File.basename(file_path)
+        @directory = File.dirname(file_path)
+        @characters = {}  # Map of characters to NonAsciiCharacter objects
+        @violations = []  # List of violations (line, column, etc.)
+      end
+
+      def add_violation(line_number, column, match, char_details, line)
+        violation = {
+          line_number: line_number,
+          column: column,
+          match: match,
+          char_details: char_details,
+          line: line,
+        }
+
+        @violations << violation
+
+        # Register each character
+        char_details.each do |detail|
+          char = detail[:char]
+          unless @characters[char]
+            @characters[char] = NonAsciiCharacter.new(
+              char,
+              detail[:hex],
+              detail[:utf8],
+              detail[:is_math],
+              detail[:replacement],
+              detail[:replacement_type],
+            )
+          end
+
+          @characters[char].add_occurrence(line_number, column, line)
+        end
+      end
+
+      def violation_count
+        @violations.size
+      end
+
+      def unique_characters
+        @characters.values
+      end
+
+      def display_path
+        "#{File.basename(@directory)}/#{@filename}"
+      end
+
+      def full_path
+        File.expand_path(@path)
+      end
+
+      def to_h
+        {
+          file: display_path,
+          count: violation_count,
+          non_ascii_characters: unique_characters.map(&:to_h),
+        }
+      end
+    end
+  end
+end

data/lib/expressir/commands/format.rb

@@ -35,7 +35,7 @@ module Expressir
       def format_with_iso_profile(repository)
         repository.schemas.each do |schema|
           say "\n(* Expressir formatted schema: #{schema.id} *)\n"
-          say schema.to_s(no_remarks: true)
+          say schema.format(no_remarks: true)
         end
       end
     end