tediparse 2.0.0

data/lib/stupidedi/schema/generation/runner.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Stupidedi
+  module Schema
+    module Generation
+      # Orchestrates a full-release generation run. Reads the flat files, then
+      # runs every generator in dependency order. Mirrors the Tediware
+      # +stupidedi:generate_version+ pipeline.
+      #
+      # All files are generated into a temporary staging directory first. The
+      # registration and master-loader generators scan that staging tree (not
+      # the live +out+), so their content is always consistent with the run -
+      # including under write: false (dry-run previews are accurate). On a
+      # successful write run the staging tree is copied into +out+ in one step,
+      # so a failure partway through never leaves a half-written tree.
+      class Runner
+        # Describes one generated file.
+        Result = Struct.new(:path, :relative_path, :content, :written, keyword_init: true)
+
+        def initialize(table_data:, release:, out:, namespace: "Edi", write: true, master_loader: false, logger: nil)
+          @table_data = table_data
+          @release_code = release
+          @out = out
+          @namespace = namespace
+          @write = write
+          @master_loader = master_loader
+          @logger = logger
+        end
+
+        # @return [Array<Result>] one entry per generated file
+        def run
+          Generation.validate_namespace!(@namespace)
+          validate_release!
+
+          release = FlatFileReader.read(@table_data, @release_code)
+          guard_against_empty!(release)
+          log "Read release #{release.code}: " \
+              "#{release.elements.size} elements, #{release.segments.size} segments, " \
+              "#{release.transaction_sets.size} transaction sets"
+
+          results = []
+          Dir.mktmpdir("tediparse-gen") do |staging|
+            @staging = staging
+            results = generate_all(release)
+            if @write
+              ensure_out
+              replace_staged_release_dirs
+              FileUtils.cp_r(File.join(staging, "."), @out)
+            end
+          end
+
+          log "#{@write ? 'Wrote' : 'Previewed'} #{results.size} files under #{@out}"
+          results
+        end
+
+        private
+
+        def generate_all(release)
+          results = []
+          results.concat(run_support_modules(release))
+          results << emit(ElementGenerator.new(release, namespace: @namespace))
+          results << emit(SegmentGenerator.new(release, include_control_segments: true, namespace: @namespace))
+          results << emit(FunctionalGroupGenerator.new(release, namespace: @namespace))
+          results << emit(ModuleLoaderGenerator.new(release, namespace: @namespace))
+          results << emit(InterchangeGenerator.new(release, namespace: @namespace))
+
+          release.transaction_sets.each do |ts|
+            results << emit(DefinitionGenerator.new(ts, namespace: @namespace))
+          end
+
+          # Registration and master loader are whole-tree artifacts. They scan
+          # [staging, out] so the emitted files cover the release just generated
+          # (in staging) UNION the releases already present under out, with
+          # staging shadowing out for the regenerated release. This keeps a
+          # multi-release output tree consistent and makes dry-run previews
+          # reflect the true resulting tree.
+          roots = [@staging, @out]
+          results << emit(RegistrationGenerator.new(roots: roots, namespace: @namespace))
+          results << emit(MasterLoaderGenerator.new(roots: roots, namespace: @namespace)) if @master_loader
+          results
+        end
+
+        def run_support_modules(release)
+          generator = SupportModulesGenerator.new(release, namespace: @namespace)
+          paths = generator.output_paths
+          generator.generate_all.map do |mod, content|
+            write_result(paths[mod], content)
+          end
+        end
+
+        def emit(generator)
+          write_result(generator.output_path, generator.generate)
+        end
+
+        # Always writes into the staging tree (so the disk-scanning generators
+        # see a complete, consistent picture); the staging tree is copied to
+        # +out+ once, at the end, only on a successful write run.
+        def write_result(relative_path, content)
+          staged_path = File.join(@staging, relative_path)
+          FileUtils.mkdir_p(File.dirname(staged_path))
+          File.write(staged_path, content)
+
+          full_path = File.join(@out, relative_path)
+          log(@write ? "  #{full_path}" : "  would write #{full_path} (#{content.lines.size} lines)")
+
+          Result.new(path: full_path, relative_path: relative_path, content: content, written: @write)
+        end
+
+        def validate_release!
+          return if VERSION_MODULES.key?(@release_code)
+
+          raise ArgumentError, "Unsupported release code: #{@release_code}. " \
+            "Supported: #{VERSION_MODULES.keys.join(', ')}"
+        end
+
+        def guard_against_empty!(release)
+          return unless release.segments.empty? || release.elements.empty?
+
+          raise ArgumentError,
+            "No X12 table data found in #{@table_data} " \
+            "(expected ELEDETL.TXT, SEGHEAD.TXT, SETHEAD.TXT, ... — got " \
+            "#{release.elements.size} elements, #{release.segments.size} segments). " \
+            "Check the --table-data path points at the release's table-data directory."
+        end
+
+        def ensure_out
+          FileUtils.mkdir_p(@out)
+          @out
+        end
+
+        # Remove the live-tree counterpart of every release directory the staging
+        # tree is about to deliver, so the regenerated release REPLACES (rather
+        # than merges into) what was there. Without this, a regeneration whose
+        # transaction-set list shrank would leave orphaned standards/*.rb behind -
+        # which the run itself shadows correctly, but which would later mislead a
+        # standalone Generation.register scan. The shared `interchanges/` dir and
+        # other releases are left untouched.
+        def replace_staged_release_dirs
+          Dir.glob(File.join(@staging, "*")).each do |namespace_dir|
+            next unless File.directory?(namespace_dir)
+
+            namespace_name = File.basename(namespace_dir)
+            Dir.glob(File.join(namespace_dir, "*")).each do |release_dir|
+              next unless File.directory?(release_dir)
+              next if File.basename(release_dir) == "interchanges"
+
+              FileUtils.rm_rf(File.join(@out, namespace_name, File.basename(release_dir)))
+            end
+          end
+        end
+
+        def log(message)
+          @logger&.call(message)
+        end
+      end
+    end
+  end
+end

data/lib/stupidedi/schema/generation/segment_generator.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Stupidedi
+  module Schema
+    module Generation
+      # Generates segment_defs.rb for a release: every segment definition with
+      # its ordered element uses and syntax notes. With include_control_segments:
+      # true it also emits ISA/IEA/GS/GE/TA1.
+      class SegmentGenerator
+        include Support
+
+        SYNTAX_NOTE_MAP = {
+          "paired"           => "P",
+          "required"         => "R",
+          "conditional"      => "C",
+          "excluded"         => "E",
+          "list_conditional" => "L"
+        }.freeze
+
+        # Interchange control segments - included when include_control_segments: true
+        CONTROL_SEGMENTS = %w[ISA IEA GS GE TA1].freeze
+
+        def initialize(release, include_control_segments: false, namespace: "Edi")
+          @release = release
+          @include_control_segments = include_control_segments
+          @namespace = namespace
+        end
+
+        def generate
+          validate_release!
+          build_ruby_content
+        end
+
+        def output_path
+          "#{namespace_path}/#{underscore(version_module)}/segment_defs.rb"
+        end
+
+        private
+
+        attr_reader :release
+
+        def release_code
+          release.code
+        end
+
+        def include_control_segments?
+          @include_control_segments
+        end
+
+        def build_ruby_content
+          lines = []
+          lines << 'require "tediparse"'
+          lines << "module #{namespace}"
+          lines << "  module #{version_module}"
+          lines << "    module SegmentDefs"
+          lines << "      s = Stupidedi::Schema"
+          lines << "      e = #{namespace}::#{version_module}::ElementDefs"
+          lines << "      r = #{namespace}::#{version_module}::ElementReqs"
+          lines << ""
+          lines << build_segment_definitions
+          lines << "    end"
+          lines << "  end"
+          lines << "end"
+          lines.join("\n") + "\n"
+        end
+
+        def build_segment_definitions
+          segments = release.segments.sort_by(&:code)
+          segments = segments.reject { |seg| CONTROL_SEGMENTS.include?(seg.code) } unless include_control_segments?
+
+          segments.map { |segment| generate_segment_def(segment) }.join("\n")
+        end
+
+        def generate_segment_def(segment)
+          lines = []
+          lines << "#{indent(3)}#{segment.code} ||= s::SegmentDef.build(:#{segment.code},"
+          lines << "#{indent(4)}#{escape_string(segment.name)},"
+          lines << "#{indent(4)}#{escape_string(segment.purpose || '')},"
+
+          element_uses = segment.element_uses.sort_by(&:position)
+          syntax_notes = segment.syntax_notes.to_a
+
+          element_uses.each_with_index do |element_use, index|
+            is_last = index == element_uses.length - 1 && syntax_notes.empty?
+            lines << generate_element_use(element_use, is_last: is_last)
+          end
+
+          syntax_notes.each_with_index do |syntax_note, index|
+            is_last = index == syntax_notes.length - 1
+            lines << generate_syntax_note(syntax_note, is_last: is_last)
+          end
+
+          lines << "#{indent(3)})"
+          lines.join("\n")
+        end
+
+        def generate_element_use(element_use, is_last:)
+          element = element_use.element
+          requirement = format_requirement(element_use.requirement)
+          trailing_comma = is_last ? "" : ","
+
+          comment = " # Min #{element.min_length}/Max #{element.max_length}"
+
+          # Composite elements don't have the E prefix
+          element_ref = element.is_composite ? element.code : "E#{element.code}"
+
+          "#{indent(4)}e::#{element_ref}.simple_use(#{requirement}, #{repeat_count_expr(element_use.max_reps)})#{trailing_comma}#{comment}"
+        end
+
+        # nil max_reps -> unbounded (the ">1" repetition marker); an integer
+        # count -> bounded(n). A non-repeating element use carries 1.
+        def repeat_count_expr(max_reps)
+          max_reps.nil? ? "s::RepeatCount.unbounded" : "s::RepeatCount.bounded(#{max_reps})"
+        end
+
+        def generate_syntax_note(syntax_note, is_last:)
+          note_class = SYNTAX_NOTE_MAP.fetch(syntax_note.condition_type) do
+            raise ArgumentError, "Unknown condition_type: #{syntax_note.condition_type}"
+          end
+
+          positions = syntax_note.element_positions
+          positions_str = positions.join(", ")
+          trailing_comma = is_last ? "" : ","
+
+          "#{indent(4)}#{namespace}::#{version_module}::SyntaxNotes::#{note_class}.build(#{positions_str})#{trailing_comma}"
+        end
+      end
+    end
+  end
+end

data/lib/stupidedi/schema/generation/support.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Stupidedi
+  module Schema
+    module Generation
+      # Shared helpers mixed into every generator.
+      #
+      # The host class must provide a private +#release_code+ returning the
+      # 6-character release string (e.g. "005010") and may set +@namespace+,
+      # the root Ruby module for the emitted code (defaults to "Edi").
+      module Support
+        # Root module for generated constants, e.g. "Edi". Consumers override
+        # this to emit into their own namespace. Validated (and memoized) on
+        # first use so an invalid namespace fails before any code is emitted.
+        def namespace
+          @validated_namespace ||= Generation.validate_namespace!(@namespace || "Edi")
+        end
+
+        # Filesystem/require-path root derived from the namespace ("Edi" -> "edi").
+        def namespace_path
+          underscore(namespace)
+        end
+
+        private
+
+        def version_module
+          VERSION_MODULES.fetch(release_code)
+        end
+
+        def validate_release!
+          return if VERSION_MODULES.key?(release_code)
+
+          raise ArgumentError, "Unsupported release code: #{release_code}. " \
+            "Supported: #{VERSION_MODULES.keys.join(', ')}"
+        end
+
+        def format_requirement(requirement)
+          stupidedi_req = REQUIREMENT_MAP.fetch(requirement) do
+            raise ArgumentError, "Unknown requirement: #{requirement}"
+          end
+          "r::#{stupidedi_req}"
+        end
+
+        def escape_string(str)
+          return '""' if str.nil? || str.empty?
+
+          escaped = str.gsub('\\', '\\\\\\\\').gsub('"', '\\"')
+          "\"#{escaped}\""
+        end
+
+        def indent(level)
+          "  " * level
+        end
+
+        # Convert release code to interchange version code.
+        # "004010" -> "00401", "005010" -> "00501"
+        def interchange_version_code
+          release_code[0..4]
+        end
+
+        # Minimal ActiveSupport-free String#underscore.
+        # "FortyTen" -> "forty_ten", "FourOhOne" -> "four_oh_one"
+        def underscore(str)
+          str.gsub("::", "/")
+             .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+             .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+             .downcase
+        end
+
+        # Minimal ActiveSupport-free String#camelize.
+        # "forty_ten" -> "FortyTen", "four_oh_one" -> "FourOhOne"
+        def camelize(str)
+          str.split(%r{[_/]}).reject(&:empty?).map { |part| part[0].upcase + part[1..] }.join
+        end
+      end
+    end
+  end
+end

data/lib/stupidedi/schema/generation/support_modules_generator.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Stupidedi
+  module Schema
+    module Generation
+      # Generates the four small per-version wrapper modules that alias common
+      # Stupidedi types into the version-scoped namespace so the other generated
+      # files can use short names.
+      class SupportModulesGenerator
+        include Support
+
+        SUPPORT_MODULES = %i[element_reqs element_types segment_reqs syntax_notes].freeze
+
+        def initialize(release, namespace: "Edi")
+          @release = release
+          @namespace = namespace
+        end
+
+        def generate_all
+          validate_release!
+          SUPPORT_MODULES.to_h { |mod| [mod, send(:"generate_#{mod}")] }
+        end
+
+        def output_paths
+          base_path = "#{namespace_path}/#{underscore(version_module)}"
+          SUPPORT_MODULES.to_h { |mod| [mod, "#{base_path}/#{mod}.rb"] }
+        end
+
+        def generate_element_reqs
+          <<~RUBY
+            # frozen_string_literal: true
+
+            require "tediparse"
+
+            module #{namespace}
+              module #{version_module}
+                module ElementReqs
+                  Mandatory  = Stupidedi::Versions::Common::ElementReqs::Mandatory
+                  Optional   = Stupidedi::Versions::Common::ElementReqs::Optional
+                  Relational = Stupidedi::Versions::Common::ElementReqs::Relational
+                end
+              end
+            end
+          RUBY
+        end
+
+        def generate_element_types
+          <<~RUBY
+            # frozen_string_literal: true
+
+            require "tediparse"
+
+            module #{namespace}
+              module #{version_module}
+                module ElementTypes
+                  DT               = Stupidedi::Versions::Common::ElementTypes::DT
+                  DateVal          = Stupidedi::Versions::Common::ElementTypes::DateVal
+
+                  R                = Stupidedi::Versions::Common::ElementTypes::R
+                  FloatVal         = Stupidedi::Versions::Common::ElementTypes::FloatVal
+
+                  ID               = Stupidedi::Versions::Common::ElementTypes::ID
+                  IdentifierVal    = Stupidedi::Versions::Common::ElementTypes::IdentifierVal
+
+                  Nn               = Stupidedi::Versions::Common::ElementTypes::Nn
+                  FixnumVal        = Stupidedi::Versions::Common::ElementTypes::FixnumVal
+
+                  AN               = Stupidedi::Versions::Common::ElementTypes::AN
+                  StringVal        = Stupidedi::Versions::Common::ElementTypes::StringVal
+
+                  TM               = Stupidedi::Versions::Common::ElementTypes::TM
+                  TimeVal          = Stupidedi::Versions::Common::ElementTypes::TimeVal
+
+                  SimpleElementDef = Stupidedi::Versions::Common::ElementTypes::SimpleElementDef
+                end
+              end
+            end
+          RUBY
+        end
+
+        def generate_segment_reqs
+          <<~RUBY
+            # frozen_string_literal: true
+
+            require "tediparse"
+
+            module #{namespace}
+              module #{version_module}
+                module SegmentReqs
+                  Mandatory = Stupidedi::Versions::Common::SegmentReqs::Mandatory
+                  Optional  = Stupidedi::Versions::Common::SegmentReqs::Optional
+                end
+              end
+            end
+          RUBY
+        end
+
+        def generate_syntax_notes
+          <<~RUBY
+            # frozen_string_literal: true
+
+            module #{namespace}
+              module #{version_module}
+                module SyntaxNotes
+                  P = Stupidedi::Versions::Common::SyntaxNotes::P
+                  R = Stupidedi::Versions::Common::SyntaxNotes::R
+                  E = Stupidedi::Versions::Common::SyntaxNotes::E
+                  C = Stupidedi::Versions::Common::SyntaxNotes::C
+                  L = Stupidedi::Versions::Common::SyntaxNotes::L
+                end
+              end
+            end
+          RUBY
+        end
+
+        private
+
+        attr_reader :release
+
+        def release_code
+          release.code
+        end
+      end
+    end
+  end
+end

data/lib/stupidedi/schema/generation/version_modules.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Stupidedi
+  module Schema
+    module Generation
+      # Maps 6-digit ASC X12 release codes to the Ruby module names used by the
+      # generated grammar (e.g. "005010" => "FiftyTen"). This is the canonical
+      # list of releases the generator supports.
+      VERSION_MODULES = {
+        "003060" => "ThirtySixty",
+        "004010" => "FortyTen",
+        "004060" => "FortySixty",
+        "005010" => "FiftyTen",
+        "006010" => "SixtyTen",
+        "007010" => "SeventyTen",
+        "008010" => "EightyTen"
+      }.freeze
+
+      # Maps X12 requirement designators to Stupidedi ElementReq names.
+      # Note: Conditional -> Relational and NotUsed -> Optional are deliberate.
+      REQUIREMENT_MAP = {
+        "Mandatory"   => "Mandatory",
+        "Optional"    => "Optional",
+        "Conditional" => "Relational",
+        "NotUsed"     => "Optional"
+      }.freeze
+
+      # A valid output namespace is a single Ruby constant name (e.g. "Edi").
+      # Nested namespaces ("Acme::Grammars") are not supported: the generated
+      # code uses `module <namespace>` directly, which only works for a single
+      # top-level constant.
+      NAMESPACE_FORMAT = /\A[A-Z]\w*\z/
+    end
+  end
+end

data/lib/stupidedi/schema/generation.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "generation/version_modules"
+
+module Stupidedi
+  module Schema
+    # Grammar generation: turns ASC X12 Table Data flat files into Stupidedi
+    # grammar definition source files.
+    #
+    # The gem ships the generation *machine* only. The X12 Table Data it reads is
+    # licensed X12 IP and is supplied by the consumer; the generated grammar
+    # files are a derivative of that IP and belong to the consumer. Nothing here
+    # bundles X12 content.
+    #
+    #   Stupidedi::Schema::Generation.run(
+    #     table_data: "vendor/x12/table_data/005010",
+    #     release:    "005010",
+    #     out:        "lib"
+    #   )
+    module Generation
+      autoload :Support,                  "stupidedi/schema/generation/support"
+      autoload :Models,                   "stupidedi/schema/generation/models"
+      autoload :FlatFileReader,           "stupidedi/schema/generation/flat_file_reader"
+      autoload :SupportModulesGenerator,  "stupidedi/schema/generation/support_modules_generator"
+      autoload :ElementGenerator,         "stupidedi/schema/generation/element_generator"
+      autoload :SegmentGenerator,         "stupidedi/schema/generation/segment_generator"
+      autoload :DefinitionGenerator,      "stupidedi/schema/generation/definition_generator"
+      autoload :FunctionalGroupGenerator, "stupidedi/schema/generation/functional_group_generator"
+      autoload :InterchangeGenerator,     "stupidedi/schema/generation/interchange_generator"
+      autoload :ModuleLoaderGenerator,    "stupidedi/schema/generation/module_loader_generator"
+      autoload :RegistrationGenerator,    "stupidedi/schema/generation/registration_generator"
+      autoload :MasterLoaderGenerator,    "stupidedi/schema/generation/master_loader_generator"
+      autoload :Runner,                   "stupidedi/schema/generation/runner"
+
+      # Validates the output namespace is a single Ruby constant name and
+      # returns it. Raises ArgumentError otherwise. See NAMESPACE_FORMAT.
+      def self.validate_namespace!(namespace)
+        return namespace if namespace.to_s =~ NAMESPACE_FORMAT
+
+        raise ArgumentError,
+          %(namespace must be a single Ruby constant name like "Edi" ) +
+          %(got #{namespace.inspect}; nested namespaces ("::") are not supported)
+      end
+
+      # Generate the full grammar for one release. See Runner for options.
+      # master_loader: true also emits a single-require entry file (e.g. edi.rb).
+      def self.run(table_data:, release:, out:, namespace: "Edi", write: true, master_loader: false, logger: nil)
+        Runner.new(
+          table_data:    table_data,
+          release:       release,
+          out:           out,
+          namespace:     namespace,
+          write:         write,
+          master_loader: master_loader,
+          logger:        logger
+        ).run
+      end
+
+      # Rebuild the whole-tree aggregation artifacts by scanning the live output
+      # tree: stupidedi_registration.rb always, and the master loader too when one
+      # is present (so the rebuilt registration's constants are actually required;
+      # otherwise require "edi" would resolve to a NameError). Useful after adding
+      # or removing releases by other means; `run` already keeps these current for
+      # the releases it generates. Returns the paths (re)generated.
+      def self.register(out:, namespace: "Edi", write: true, logger: nil)
+        validate_namespace!(namespace)
+
+        paths = [write_artifact(RegistrationGenerator.new(roots: [out], namespace: namespace), out, write, logger)]
+
+        master_loader = MasterLoaderGenerator.new(roots: [out], namespace: namespace)
+        if File.exist?(File.join(out, master_loader.output_path))
+          paths << write_artifact(master_loader, out, write, logger)
+        end
+
+        paths
+      end
+
+      def self.write_artifact(generator, out, write, logger)
+        content = generator.generate
+        path = File.join(out, generator.output_path)
+
+        if write
+          require "fileutils"
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, content)
+          logger&.call("wrote #{path}")
+        end
+
+        path
+      end
+      private_class_method :write_artifact
+    end
+  end
+end