swiss-netex 1.0.0

data/lib/swiss_netex/lines.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "stringio"
+
+module SwissNetex
+  # Streaming SERVICE `Line` inventory for discovery (`lines` CLI).
+  #
+  # Optional `--operator` / `--line` aliases narrow the list (same alias rules as
+  # filter). Does not load TIMETABLE shards.
+  class Lines
+    HEADERS = %w[line_id public_code slnid operator_ref name].freeze
+
+    Entry = Data.define(
+      :id, :public_code, :short_name, :slnid, :operator_ref, :name
+    ) do
+      # Discovery columns (short_name is match-only, not exported).
+      def to_row
+        [id, public_code, slnid, operator_ref, name]
+      end
+    end
+
+    def self.load(path, operators: [], lines: [])
+      new(path, operators: operators, lines: lines).call
+    end
+
+    def initialize(path, operators: [], lines: [])
+      @path = path.to_s
+      @operator_aliases = Array(operators)
+      @line_aliases = normalize_aliases(lines)
+    end
+
+    def call
+      raise Error, "Missing --from package path" if @path.empty?
+      raise Error, "Package path not found: #{@path}" unless File.exist?(@path)
+
+      operator_ids = resolve_operator_ids
+      entries = []
+      Package.open(@path) do |pkg|
+        pkg.open_one(:service) do |io|
+          each_line(io) do |entry|
+            next unless keep?(entry, operator_ids)
+
+            entries << entry
+          end
+        end
+      end
+      sort_entries(entries)
+    end
+
+    private
+
+    def keep?(entry, operator_ids)
+      return false if operator_ids && !operator_ids.key?(entry.operator_ref)
+      return true if @line_aliases.empty?
+
+      line_matches_alias?(entry)
+    end
+
+    def line_matches_alias?(entry)
+      [
+        entry.id,
+        entry.public_code,
+        entry.short_name,
+        entry.slnid,
+        entry.name
+      ].compact.map { |value| normalize(value) }.any? { |key| @line_aliases.key?(key) }
+    end
+
+    def resolve_operator_ids
+      return nil if @operator_aliases.empty?
+
+      ids = Operators.load(@path).resolve(@operator_aliases)
+      ids.to_h { |id| [id, true] }
+    end
+
+    def each_line(source)
+      reader = Nokogiri::XML::Reader(to_io(source))
+      while reader.read
+        next unless line_element?(reader)
+
+        entry = parse_line(reader.outer_xml)
+        yield entry if entry
+      end
+    end
+
+    def line_element?(reader)
+      reader.node_type == Nokogiri::XML::Reader::TYPE_ELEMENT &&
+        reader.local_name == "Line"
+    end
+
+    def parse_line(xml)
+      root = Nokogiri::XML(xml).root
+      return unless root
+
+      id = root["id"].to_s.strip
+      return if id.empty?
+
+      Entry.new(
+        id: id,
+        public_code: text_at(root, "PublicCode"),
+        short_name: text_at(root, "ShortName"),
+        slnid: key_value(root, "SLNID"),
+        operator_ref: attr_ref(root, "OperatorRef"),
+        name: text_at(root, "Name")
+      )
+    end
+
+    def sort_entries(entries)
+      entries.sort_by do |entry|
+        [
+          entry.operator_ref.to_s,
+          entry.public_code.to_s,
+          entry.id
+        ]
+      end
+    end
+
+    def attr_ref(node, element_name)
+      child = node.at_xpath(".//*[local-name()=#{element_name.inspect}]")
+      blank_to_nil(child&.[]("ref")&.strip)
+    end
+
+    def text_at(node, element_name)
+      child = node.at_xpath(".//*[local-name()=#{element_name.inspect}]")
+      blank_to_nil(child&.text&.strip)
+    end
+
+    def key_value(node, key_name)
+      node.xpath(".//*[local-name()='KeyValue']").each do |kv|
+        key = kv.at_xpath(".//*[local-name()='Key']")&.text&.strip
+        next unless key&.casecmp?(key_name)
+
+        return blank_to_nil(kv.at_xpath(".//*[local-name()='Value']")&.text&.strip)
+      end
+      nil
+    end
+
+    def blank_to_nil(text)
+      text.nil? || text.empty? ? nil : text
+    end
+
+    def normalize_aliases(aliases)
+      Array(aliases).each_with_object({}) do |value, hash|
+        key = normalize(value)
+        hash[key] = true unless key.empty?
+      end
+    end
+
+    def normalize(value)
+      value.to_s.strip.downcase
+    end
+
+    def to_io(source)
+      return StringIO.new(source) if source.is_a?(String)
+      return source if source.respond_to?(:read)
+
+      raise Error, "Lines expects a String or IO-like object"
+    end
+  end
+end

data/lib/swiss_netex/operators.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "stringio"
+
+module SwissNetex
+  # Streaming index of NeTEx `Operator` entries from a RESOURCE frame.
+  #
+  # Resolves CLI-style aliases (GO, zero-padded GO, `ch:1:Operator:…`, SBOID,
+  # ShortName) to canonical Operator `@id` values.
+  class Operators
+    OPERATOR_ID_RE = /\Ach:1:Operator:/i
+    SBOID_RE = /\Ach:1:sboid:/i
+    GO_RE = /\A0*\d+\z/
+
+    HEADERS = %w[go operator_id sboid short_name name].freeze
+    Entry = Data.define(:id, :private_code, :didok, :sboid, :short_name, :name)
+
+    def self.parse(source)
+      new.parse(source)
+    end
+
+    def self.load(path)
+      ResourceFrame.open(path) { |io| parse(io) }
+    end
+
+    def initialize
+      @entries = []
+      @by_id = {}
+      @alias_to_id = {}
+      @ambiguous = {}
+    end
+
+    def parse(source)
+      each_operator_xml(source) { |xml| index_operator(xml) }
+      self
+    end
+
+    def entries
+      @entries.dup
+    end
+
+    def size
+      @entries.size
+    end
+
+    def empty?
+      @entries.empty?
+    end
+
+    # Resolve one or more aliases to unique Operator `@id` values (input order).
+    # Raises SwissNetex::Error when any alias is missing or ambiguous.
+    def resolve(aliases)
+      list = alias_list(aliases)
+      ids, unknown, ambiguous = collect_resolutions(list)
+      raise_resolve_errors!(unknown, ambiguous)
+      ids
+    end
+
+    def lookup(alias_name)
+      key = normalize_alias(alias_name)
+      return nil if key.nil? || key.empty? || @ambiguous.key?(key)
+
+      @alias_to_id[key]
+    end
+
+    def include_id?(operator_id)
+      @by_id.key?(operator_id.to_s)
+    end
+
+    def fetch_entry(operator_id)
+      @by_id[operator_id.to_s]
+    end
+
+    # Stable ordered rows for `operators` discovery TSV.
+    def rows
+      entries
+        .sort_by { |entry| [go_for(entry).to_s, entry.id] }
+        .map { |entry| row_for(entry) }
+    end
+
+    private
+
+    def row_for(entry)
+      [go_for(entry), entry.id, entry.sboid, entry.short_name, entry.name]
+    end
+
+    def go_for(entry)
+      entry.private_code || entry.didok
+    end
+
+    def alias_list(aliases)
+      list = Array(aliases).map { |value| value.to_s.strip }.reject(&:empty?)
+      raise Error, "No operator aliases given" if list.empty?
+
+      list
+    end
+
+    def collect_resolutions(list)
+      ids = []
+      unknown = []
+      ambiguous = []
+      seen = {}
+
+      list.each do |alias_name|
+        id = lookup(alias_name)
+        if id.nil?
+          bucket = ambiguous_alias?(alias_name) ? ambiguous : unknown
+          bucket << alias_name
+          next
+        end
+        next if seen[id]
+
+        seen[id] = true
+        ids << id
+      end
+
+      [ids, unknown, ambiguous]
+    end
+
+    def raise_resolve_errors!(unknown, ambiguous)
+      parts = []
+      parts << "Unknown operator alias(es): #{unknown.join(", ")}" if unknown.any?
+      parts << "Ambiguous operator alias(es): #{ambiguous.join(", ")}" if ambiguous.any?
+      raise Error, parts.join("; ") if parts.any?
+    end
+
+    def each_operator_xml(source)
+      reader = Nokogiri::XML::Reader(to_io(source))
+      while reader.read
+        next unless operator_element?(reader)
+
+        xml = reader.outer_xml
+        yield xml if xml && !xml.empty?
+      end
+    end
+
+    def operator_element?(reader)
+      reader.node_type == Nokogiri::XML::Reader::TYPE_ELEMENT &&
+        local_name(reader.name) == "Operator"
+    end
+
+    def to_io(source)
+      return StringIO.new(source) if source.is_a?(String)
+      return source if source.respond_to?(:read)
+
+      raise Error, "Operators.parse expects a String or IO-like object"
+    end
+
+    def local_name(name)
+      name.to_s.split(":", 2).last
+    end
+
+    def index_operator(xml)
+      entry = entry_from_xml(xml)
+      return unless entry
+
+      store_entry(entry)
+      register_entry_aliases(entry)
+    end
+
+    def entry_from_xml(xml)
+      root = Nokogiri::XML(xml).root
+      return unless root
+
+      id = root["id"].to_s.strip
+      return if id.empty?
+
+      Entry.new(
+        id: id,
+        private_code: text_at(root, "PrivateCode"),
+        didok: key_value(root, "DIDOK"),
+        sboid: key_value(root, "SBOID"),
+        short_name: text_at(root, "ShortName"),
+        name: text_at(root, "Name")
+      )
+    end
+
+    def store_entry(entry)
+      @entries << entry
+      @by_id[entry.id] = entry
+    end
+
+    def register_entry_aliases(entry)
+      register_alias(entry.id, entry.id)
+      register_go(entry.id, entry.private_code)
+      register_go(entry.id, entry.didok)
+      register_alias(entry.id, entry.sboid) if entry.sboid
+      register_alias(entry.id, entry.short_name) if entry.short_name
+    end
+
+    def text_at(node, element_name)
+      child = node.at_xpath(".//*[local-name()=#{element_name.inspect}]")
+      blank_to_nil(child&.text&.strip)
+    end
+
+    def key_value(node, key_name)
+      node.xpath(".//*[local-name()='KeyValue']").each do |kv|
+        key = kv.at_xpath(".//*[local-name()='Key']")&.text&.strip
+        next unless key&.casecmp?(key_name)
+
+        return blank_to_nil(kv.at_xpath(".//*[local-name()='Value']")&.text&.strip)
+      end
+      nil
+    end
+
+    def blank_to_nil(text)
+      text.nil? || text.empty? ? nil : text
+    end
+
+    def register_go(id, go_code)
+      return if go_code.nil? || go_code.empty? || !go_code.match?(GO_RE)
+
+      # normalize_alias collapses 000151 / 151 to the same key.
+      register_alias(id, go_code)
+    end
+
+    def ambiguous_alias?(alias_name)
+      key = normalize_alias(alias_name)
+      !key.nil? && !key.empty? && @ambiguous.key?(key)
+    end
+
+    def register_alias(id, raw_key)
+      key = normalize_alias(raw_key)
+      return if key.nil? || key.empty?
+
+      existing = @alias_to_id[key]
+      if existing.nil?
+        @alias_to_id[key] = id
+      elsif existing != id
+        mark_ambiguous(key)
+      end
+    end
+
+    def mark_ambiguous(key)
+      @alias_to_id.delete(key)
+      @ambiguous[key] = true
+    end
+
+    def normalize_alias(value)
+      text = value.to_s.strip
+      return nil if text.empty?
+      return text.downcase if text.match?(OPERATOR_ID_RE) || text.match?(SBOID_RE)
+      return strip_leading_zeros(text) if text.match?(GO_RE)
+
+      text.downcase
+    end
+
+    def strip_leading_zeros(text)
+      stripped = text.sub(/\A0+/, "")
+      stripped.empty? ? "0" : stripped
+    end
+  end
+end

data/lib/swiss_netex/package.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "zip"
+
+module SwissNetex
+  # Read-only access to a Swiss NeTEx package (zip or extracted directory).
+  class Package
+    Member = Data.define(:name, :kind)
+
+    def self.open(path, &)
+      new(path).open(&)
+    end
+
+    def self.frame_kind(name)
+      return :resource if name.match?(/RESOURCE/i)
+      return :service_calendar if name.match?(/SERVICECALENDAR|SERVICE_CALENDAR/i)
+      return :service if name.match?(/SERVICE/i)
+      return :site if name.match?(/SITE/i)
+      return :common if name.match?(/COMMON/i)
+      return :timetable if name.match?(/TIMETABLE/i)
+
+      :other
+    end
+
+    def initialize(path)
+      @path = path.to_s
+    end
+
+    def open
+      raise Error, "Package path not found: #{@path}" unless File.exist?(@path)
+
+      if File.directory?(@path)
+        yield DirectorySource.new(@path)
+      elsif zip_path?
+        Zip::File.open(@path) { |zip| yield ZipSource.new(zip, @path) }
+      else
+        raise Error, "Package must be a zip or directory: #{@path}"
+      end
+    end
+
+    private
+
+    def zip_path?
+      @path.match?(/\.zip\z/i)
+    end
+
+    # Shared listing / open helpers for zip and directory packages.
+    module Source
+      def members
+        names.map { |name| Member.new(name: name, kind: Package.frame_kind(name)) }
+      end
+
+      def each_of(kind, &)
+        names_for(kind).each { |name| open_member(name, &) }
+      end
+
+      def open_one(kind, &)
+        matches = names_for(kind)
+        raise Error, "No #{kind} frame found in #{label}" if matches.empty?
+
+        if matches.size > 1
+          raise Error, "Multiple #{kind} frames found in #{label}: #{matches.join(", ")}"
+        end
+
+        open_member(matches.first, &)
+      end
+
+      def names_for(kind)
+        names.select { |name| Package.frame_kind(name) == kind }
+      end
+    end
+
+    class ZipSource
+      include Source
+
+      def initialize(zip, path)
+        @zip = zip
+        @path = path
+      end
+
+      def label = @path
+
+      def names
+        @names ||= @zip.select { |e| !e.directory? && !workflow?(e.name) }.map(&:name)
+      end
+
+      def open_member(name, &)
+        entry = @zip.find_entry(name)
+        raise Error, "Missing package member: #{name}" unless entry
+
+        entry.get_input_stream(&)
+      end
+
+      private
+
+      def workflow?(name)
+        name.match?(%r{\AWorkflow/}i)
+      end
+    end
+
+    class DirectorySource
+      include Source
+
+      def initialize(path)
+        @path = path
+      end
+
+      def label = @path
+
+      def names
+        @names ||= Dir.children(@path).select do |name|
+          file = File.join(@path, name)
+          File.file?(file) && name.match?(/\.xml\z/i)
+        end.sort
+      end
+
+      def open_member(name, &)
+        path = member_path(name)
+        raise Error, "Missing package member: #{name}" unless File.file?(path)
+
+        File.open(path, "rb", &)
+      end
+
+      private
+
+      # Members are flat top-level basenames from Dir.children. Reject traversal
+      # so a public Package API call cannot escape the package root.
+      def member_path(name)
+        raw = name.to_s
+        if raw.empty? || raw.include?("/") || raw.include?("\\") ||
+           raw == "." || raw == ".." || File.absolute_path?(raw)
+          raise Error, "Invalid package member name: #{name}"
+        end
+
+        root = File.expand_path(@path)
+        path = File.expand_path(File.join(root, raw))
+        unless path == root || path.start_with?("#{root}#{File::SEPARATOR}")
+          raise Error, "Invalid package member name: #{name}"
+        end
+
+        path
+      end
+    end
+  end
+end

data/lib/swiss_netex/package_source.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SwissNetex
+  # Resolve a national package path: use `--from` when set, otherwise download
+  # (or reuse cache). Shared by `extract`, `operators`, and `lines`.
+  module PackageSource
+    module_function
+
+    def resolve(
+      from: nil,
+      dataset: nil,
+      cache_dir: Download::DEFAULT_CACHE_DIR,
+      force: false,
+      http: nil,
+      progress_io: nil
+    )
+      path = from.to_s.strip
+      return path unless path.empty?
+
+      progress_io&.puts("No --from given; downloading national package…")
+      Download.new(
+        dataset: dataset,
+        cache_dir: cache_dir,
+        force: force,
+        http: http || Http.new,
+        progress_io: progress_io
+      ).call.path
+    end
+  end
+end

data/lib/swiss_netex/resource_frame.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "zip"
+
+module SwissNetex
+  # Opens the single RESOURCE frame from a Swiss NeTEx package path.
+  #
+  # Accepts a bare XML file, a national/export zip, or an extracted directory.
+  # Yields a readable IO; callers stream with Nokogiri Reader (never full DOM
+  # of large frames).
+  class ResourceFrame
+    NAME_RE = /RESOURCE/i
+
+    def self.open(path, &)
+      new(path).open(&)
+    end
+
+    def initialize(path)
+      @path = path.to_s
+    end
+
+    def open(&)
+      raise Error, "Package path not found: #{@path}" unless File.exist?(@path)
+
+      if File.directory?(@path)
+        open_directory(&)
+      elsif zip_path?
+        open_zip(&)
+      else
+        File.open(@path, "rb", &)
+      end
+    end
+
+    private
+
+    def zip_path?
+      @path.match?(/\.zip\z/i)
+    end
+
+    def open_zip(&)
+      Zip::File.open(@path) do |zip|
+        entry = single_match(
+          zip.select { |e| !e.directory? && e.name.match?(NAME_RE) },
+          kind: "member"
+        )
+        entry.get_input_stream(&)
+      end
+    end
+
+    def open_directory(&)
+      names = Dir.children(@path).select { |name| resource_xml?(name) }
+      name = single_match(names, kind: "file")
+      File.open(File.join(@path, name), "rb", &)
+    end
+
+    def resource_xml?(name)
+      file = File.join(@path, name)
+      File.file?(file) && name.match?(NAME_RE) && name.match?(/\.xml\z/i)
+    end
+
+    def single_match(matches, kind:)
+      raise Error, "No RESOURCE XML #{kind} found in #{@path}" if matches.empty?
+
+      if matches.size > 1
+        labels = matches.map { |m| m.respond_to?(:name) ? m.name : m }
+        raise Error,
+              "Multiple RESOURCE XML #{kind}s found in #{@path}: #{labels.join(", ")}"
+      end
+
+      matches.first
+    end
+  end
+end

data/lib/swiss_netex/tsv.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SwissNetex
+  # Discovery-command table writer: aligned columns on a TTY, raw TSV when piped.
+  module Tsv
+    module_function
+
+    def write(io, headers, rows)
+      cells = [headers.map { |h| escape(h) }] +
+              rows.map { |row| row.map { |cell| escape(cell) } }
+
+      if tty?(io)
+        write_aligned(io, cells)
+      else
+        write_tsv(io, cells)
+      end
+    end
+
+    def escape(value)
+      text = value.nil? ? "" : value.to_s
+      text.gsub(/[\t\r\n]/, " ")
+    end
+
+    def tty?(io)
+      io.respond_to?(:tty?) && io.tty?
+    end
+
+    def write_tsv(io, cells)
+      cells.each { |row| io.puts(row.join("\t")) }
+    end
+
+    def write_aligned(io, cells)
+      widths = column_widths(cells)
+      cells.each do |row|
+        padded = row.each_with_index.map do |cell, index|
+          index == row.size - 1 ? cell : cell.ljust(widths[index])
+        end
+        io.puts(padded.join("  ").rstrip)
+      end
+    end
+
+    def column_widths(cells)
+      widths = Array.new(cells.first.size, 0)
+      cells.each do |row|
+        row.each_with_index do |cell, index|
+          size = cell.to_s.size
+          widths[index] = size if size > widths[index]
+        end
+      end
+      widths
+    end
+  end
+end