ctx_parser 0.1.1

data/lib/ctx_parser/profile.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative "command_catalog"
+
+module CtxParser
+  # 组合平台命令策略，仅覆盖已确认的型号差异。
+  class Profile
+    COMMANDS = {}.freeze
+    PARSERS = {}.freeze
+    MODEL_PARSERS = {}.freeze
+
+    attr_reader :model
+
+    # 根据传入设备型号选择命令与解析行为。
+    def initialize(model: nil)
+      raise ArgumentError, "Device model must be text" unless model.nil? || model.is_a?(String)
+
+      @model = model&.strip&.downcase&.freeze
+      @model_parsers = model_parsers
+    end
+
+    # 返回当前平台策略声明的命令目录。
+    def commands = self.class::COMMANDS
+
+    # 动态目录可替换解析器索引，同时保留型号特定选择。
+    def parsers = self.class::PARSERS
+
+    # 保留选择顺序并归组共享视图，不混用不同命令的正文。
+    def queries(names)
+      unless names.is_a?(Array) && names.uniq == names && (names - commands.keys).empty?
+        raise ArgumentError, "Query dimensions must be unique supported names"
+      end
+
+      plan = names.each_with_object({}) do |name, queries|
+        commands_for(name).each { |command| (queries[command] ||= []) << name }
+      end
+      plan.each_value(&:freeze)
+      plan.freeze
+    end
+
+    # 单个维度可能需要多个独立回显；调用方必须分别保存正文。
+    def commands_for(name)
+      declaration = commands.fetch(name) { raise ArgumentError, "Unsupported parser dimension" }
+      queries = declaration.is_a?(Array) ? declaration : [ declaration ]
+      unless queries.any? && queries.uniq == queries && queries.all? { |query| query.is_a?(String) && !query.strip.empty? && !/[\x00-\x1f\x7f]/.match?(query) }
+        raise ArgumentError, "Parser dimension must declare one or more unique commands"
+      end
+
+      queries.map { |query| query.frozen? ? query : query.dup.freeze }.freeze
+    end
+
+    # 解析支持的观测维度对应的命令。
+    def command(name)
+      queries = commands_for(name)
+      raise ArgumentError, "Parser dimension has multiple commands; select one explicitly" unless queries.one?
+
+      queries.first
+    end
+
+    # 确定维度使用的解析器，包括命令特定变体。
+    def parser_for(name, command: nil)
+      query = select_command([ name ], command)
+      @model_parsers.fetch(query) { parsers.fetch(query) }
+    end
+
+    # 选择目标命令解析器，并投影单个请求维度。
+    def parse(name, text, complete: false, command: nil)
+      parse_many([ name ], text, complete: complete, command: command).fetch(name)
+    end
+
+    # AP、Radio 等共享视图仅解析一次，确保状态与数量证据一致。
+    def parse_many(names, text, complete: false, command: nil)
+      unless names.is_a?(Array) && names.any? && names.uniq == names
+        raise ArgumentError, "Parser dimensions must be a nonempty unique array"
+      end
+      query = select_command(names, command)
+
+      result = parser_for(names.first, command: query).parse(text, complete: complete)
+      names.to_h { |name| [ name, project_independently(name, result) ] }
+    end
+
+    private
+
+    # 仅当存在唯一公共查询时允许推断；显式命令必须覆盖全部请求视图。
+    def select_command(names, selected)
+      candidates = names.map { |name| commands_for(name) }.reduce { |common, queries| common & queries }
+      unless selected.nil?
+        raise ArgumentError, "Selected command does not provide all parser dimensions" unless candidates.include?(selected)
+
+        selected
+      else
+        raise ArgumentError, "One CLI output must belong to one command" unless candidates.one?
+
+        candidates.first
+      end
+    end
+
+    # 采集前校验所选型号，并隔离后续修改对型号查找的影响。
+    def model_parsers
+      declarations = self.class::MODEL_PARSERS
+      raise ArgumentError, "Model parsers must be a hash" unless declarations.is_a?(Hash)
+
+      overrides = declarations.fetch(model, {})
+      unless overrides.is_a?(Hash) && overrides.all? do |command, parser|
+          self.class::PARSERS.key?(command) && parser.is_a?(Class) && parser < Parser
+        end
+        raise ArgumentError, "Model parsers must override declared commands with Parser subclasses"
+      end
+
+      overrides.dup.freeze
+    end
+
+    # 投影失败仅影响单个视图；命令选择及解析错误仍正常抛出。
+    def project_independently(name, result)
+      return failed_projection(:invalid_parser_result) unless result.is_a?(Result) || result.is_a?(ResultSet)
+
+      projected = project(name, result)
+      projected.is_a?(Result) ? projected : failed_projection(:invalid_parser_result)
+    rescue KeyError
+      code = result.is_a?(ResultSet) && !result.results.key?(name) ? :missing_parser_view : :parser_projection_failed
+      failed_projection(code)
+    rescue StandardError
+      failed_projection(:parser_projection_failed)
+    end
+
+    # 诊断代码描述边界失败，不保留异常消息或原始值。
+    def failed_projection(code) = Result.new(status: :failed, issues: [ { code: code } ])
+
+    # 从共享命令结果中提取请求维度。
+    def project(name, result)
+      result.is_a?(ResultSet) ? result.fetch(name) : result
+    end
+  end
+end

data/lib/ctx_parser/records.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CtxParser
+  # 检测身份冲突，不附加厂商特定的保留或完整性策略。
+  class Records
+    attr_reader :rows, :first_occurrences, :unambiguous, :duplicate_identity_count, :duplicate_row_count
+
+    # 冻结筛选结果数组，记录值的所有权仍属于调用方。
+    def initialize(rows, identity: nil, &key)
+      unless rows.is_a?(Array) && rows.all? { |row| row.is_a?(Hash) }
+        raise ArgumentError, "Records must be hashes"
+      end
+
+      key ||= identity if identity.respond_to?(:call)
+      key ||= ->(row) { row.values_at(*identity) } if identity.is_a?(Array) && identity.any?
+      raise ArgumentError, "Identity must be a nonempty array or callable" unless key
+
+      @rows = rows.dup.freeze
+      groups = @rows.group_by { |row| key.call(row) }.values
+      @first_occurrences = groups.map(&:first).freeze
+      @unambiguous = groups.filter_map { |group| group.first if group.one? }.freeze
+      @duplicate_identity_count = groups.count { |group| group.size > 1 }
+      @duplicate_row_count = @rows.size - groups.size
+      freeze
+    end
+
+    # 判断是否有多条记录声明相同逻辑身份。
+    def duplicates? = duplicate_identity_count.positive?
+    # 序列化诊断元数据，不包含原始来源文本。
+    def as_json(*) = { rows: rows.size, duplicate_identities: duplicate_identity_count }
+
+    # 提供身份统计，不记录可能包含敏感信息的记录正文。
+    def inspect = "#<#{self.class.name} size=#{rows.size} duplicate_identities=#{duplicate_identity_count}>"
+    alias to_s inspect
+  end
+end

data/lib/ctx_parser/registry.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "profile"
+
+module CtxParser
+  # 各领域独立持有注册表；不支持的平台直接拒绝，不猜测其他厂商语法。
+  class Registry
+    # 注册平台策略及其声明的别名。
+    def initialize(profiles:, aliases: {})
+      @profiles = profiles.transform_keys { |key| platform_key(key) }.freeze
+      @aliases = aliases.transform_keys { |key| platform_key(key) }.transform_values { |key| platform_key(key) }.freeze
+      unless @profiles.size == profiles.size && @aliases.size == aliases.size &&
+          @profiles.values.all? { |profile| profile.is_a?(Class) && profile < Profile } &&
+          @aliases.values.all? { |key| @profiles.key?(key) } && (@profiles.keys & @aliases.keys).empty?
+        raise ArgumentError, "Invalid parser registry"
+      end
+    end
+
+    # 解析请求的解析结果或平台策略，拒绝未知名称。
+    def fetch(platform, model: nil)
+      key = platform_key(platform)
+      key = @aliases.fetch(key, key)
+      profile = @profiles.fetch(key) { raise ArgumentError, "Unsupported parser platform" }
+      profile.new(model: model)
+    end
+
+    private
+
+    # 选择已注册平台策略前，先归一化平台别名。
+    def platform_key(value)
+      raise ArgumentError, "Parser platform must be a name" unless value.is_a?(String) || value.is_a?(Symbol)
+
+      key = value.to_s.strip.downcase
+      raise ArgumentError, "Parser platform must be a name" if key.empty?
+
+      key.to_sym
+    end
+  end
+end

data/lib/ctx_parser/result.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "immutable"
+
+module CtxParser
+  # 仅保存解析结果；采集命令、时间与证据由调用方管理。
+  Result = Data.define(:status, :records, :issues) do
+    # 冻结解析状态、归一化记录与诊断证据。
+    def initialize(status:, records: [], issues: [])
+      raise ArgumentError, "Invalid parser status" unless %i[complete partial failed unsupported].include?(status)
+      raise ArgumentError, "Records must be hashes" unless records.is_a?(Array) && records.all? { |row| row.is_a?(Hash) }
+
+      super(status: status, records: Immutable.copy(records), issues: Immutable.copy(issues))
+    end
+
+    # 判断解析结果是否具有完整证据。
+    def complete? = status == :complete
+
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class.name} status=#{status} records=#{records.size}>"
+  end
+end

data/lib/ctx_parser/result_set.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "result"
+
+module CtxParser
+  # 同一回显可产生多份清单，各自保留完整性与诊断。
+  ResultSet = Data.define(:results) do
+    # 冻结具名章节结果，同时保留各章节的独立状态。
+    def initialize(results:)
+      unless results.is_a?(Hash) && results.any? && results.values.all? { |result| result.is_a?(Result) }
+        raise ArgumentError, "Result set must contain parser results"
+      end
+      super(results: results.dup.freeze)
+    end
+
+    # 返回必需的具名章节结果。
+    def fetch(name) = results.fetch(name)
+
+    # 判断所有已选事实是否都有完整证据支持。
+    def complete? = results.values.all?(&:complete?)
+
+    # 推导汇总状态，避免将证据缺失当作成功。
+    def status
+      return :complete if complete?
+      return :partial if results.values.any? { |result| %i[complete partial].include?(result.status) }
+
+      results.values.all? { |result| result.status == :unsupported } ? :unsupported : :failed
+    end
+
+    # 从全部章节结果汇总去重后的诊断。
+    def issues = results.values.flat_map(&:issues).uniq
+
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class.name} status=#{status} sections=#{results.keys.join(',')}>"
+  end
+end

data/lib/ctx_parser/values.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module CtxParser
+  # 严格转换标量；单位及可选字段语法仍由命令解析器负责。
+  module Values
+    class OutOfRange < ArgumentError; end
+
+    module_function
+
+    # 解析十进制整数，并校验声明的边界。
+    def integer(raw, min: 0, max: nil)
+      return if raw.nil?
+      raise ArgumentError, "Invalid decimal integer" unless /\A\d+\z/.match?(raw.to_s)
+
+      value = Integer(raw.to_s, 10)
+      raise OutOfRange, "Integer out of range" if (min && value < min) || (max && value > max)
+
+      value
+    end
+
+    # 归一化 MAC 地址，拒绝格式错误的输入。
+    def mac(raw)
+      return if raw.nil?
+      unless /\A(?:[0-9a-f]{12}|(?:[0-9a-f]{4}[-.]){2}[0-9a-f]{4}|(?:[0-9a-f]{2}:){5}[0-9a-f]{2})\z/i.match?(raw)
+        raise ArgumentError, "Invalid MAC address"
+      end
+
+      raw.delete("-.:").downcase.scan(/../).join(":")
+    end
+
+    # 归一化主机地址，保留 IPv4 与 IPv6 语义。
+    def host(raw, allow_zone: false)
+      return if raw.nil?
+      raise ArgumentError, "Invalid host address" if raw.include?("/") || (!allow_zone && raw.include?("%"))
+
+      IPAddr.new(raw).to_s
+    end
+
+    # 校验主机地址有效性，不让格式错误值继续传播。
+    def valid_host?(raw, allow_zone: false)
+      !host(raw, allow_zone: allow_zone).nil?
+    rescue ArgumentError, IPAddr::Error
+      false
+    end
+
+    # 统一校验网段与接口地址，仅接口投影保留主机位。
+    def ipv4_prefix(raw, host: false)
+      unless raw.is_a?(String) && raw.match?(%r{\A\d+(?:\.\d+){3}/\d+\z})
+        raise ArgumentError, "IPv4 prefix required"
+      end
+      network = IPAddr.new(raw)
+      raise ArgumentError, "IPv4 prefix required" unless network.ipv4?
+
+      host ? raw : "#{network}/#{network.prefix}"
+    end
+  end
+end

data/lib/ctx_parser/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module CtxParser
+  # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
+  VERSION = "0.1.1"
+end

data/lib/ctx_parser.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "ctx_parser/version"
+
+# 加载可能被独立自动加载的依赖前，先定义命名空间。
+module CtxParser
+end
+
+require_relative "ctx_parser/parser"
+if CtxParser.const_defined?(:Parser, false)
+  require_relative "ctx_parser/configuration_parser"
+  require_relative "ctx_parser/values"
+  require_relative "ctx_parser/records"
+  require_relative "ctx_parser/command_catalog"
+  require_relative "ctx_parser/profile"
+  require_relative "ctx_parser/registry"
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: ctx_parser
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Gatework contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: digest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ipaddr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Reusable configuration documents, command catalogs, platform profiles,
+  immutable results and parsing primitives for network automation.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README-zh.md
+- README.md
+- docs/architecture-zh.md
+- docs/release.md
+- examples/offline.rb
+- lib/ctx_parser.rb
+- lib/ctx_parser/banner.rb
+- lib/ctx_parser/block.rb
+- lib/ctx_parser/capture.rb
+- lib/ctx_parser/command_catalog.rb
+- lib/ctx_parser/configuration_parser.rb
+- lib/ctx_parser/cursor.rb
+- lib/ctx_parser/document.rb
+- lib/ctx_parser/immutable.rb
+- lib/ctx_parser/input.rb
+- lib/ctx_parser/line.rb
+- lib/ctx_parser/parser.rb
+- lib/ctx_parser/profile.rb
+- lib/ctx_parser/records.rb
+- lib/ctx_parser/registry.rb
+- lib/ctx_parser/result.rb
+- lib/ctx_parser/result_set.rb
+- lib/ctx_parser/values.rb
+- lib/ctx_parser/version.rb
+homepage: https://github.com/gatework/ctx_parser
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/gatework/ctx_parser
+  bug_tracker_uri: https://github.com/gatework/ctx_parser/issues
+  changelog_uri: https://github.com/gatework/ctx_parser/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/gatework/ctx_parser#readme
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.6
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Parse network CLI evidence into normalized facts.
+test_files: []