ctx_parser 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34175c1684f6dc5b5a7ef9a12649f16d393965f87c506d1f672f63a8301a7ebd
-  data.tar.gz: 55f14e3f497e6a3fa5484f6e5465effc39acadcfff0e908932abe41b43696b94
+  metadata.gz: c642815fd4891349acb98052cf1601b9b69217f4025db17d02c64705506eca12
+  data.tar.gz: 91e34bd39b1116a3228c9653dd51322bc0ac8d47dec25e3fcf94a41af947ed92
 SHA512:
-  metadata.gz: fc1d527a3d2a6a0c2001bfc270d6afb7f8b21e3f779d5f61b31de69757ea598f2b255a5a5eb15db41ebde8de6274c99e3ade55f89cb1b577041cdab8d4563bbf
-  data.tar.gz: 4708ac383d49d5f2ade14747800d6d5d52db0e1cdc78ac2acbd87e828fb41695e41ebf2a98a72b1c81c13d4612c2419e40ba189d429c39be7bb4afebd074100c
+  metadata.gz: 9cd537e0188eda9578bfb03e5a1cc26d703a62da5bbd1cbc2beb4fcce66233ab03de5959f20cc9821b7780ab5a2c4edc764fa063cc8afb5ca7148cf9ffd6f955
+  data.tar.gz: '022948b2a66b03ba946c748cf5aaf5dfca9eff72710f859147e8c69e195de7e1b7f055eff54c21e28eb83d763ce3c1128520c726ae3eabd655fa0f943cc91b88'

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Changes to the public contract are recorded here. Versions follow Semantic Versioning.
 
+## 0.2.3 (2026-10-18)
+
+- Redact Result, Results and Line during pretty printing, including nested containers.
+- Normalize model override names, reject normalized collisions, and validate static registry command/parser consistency.
+- Report missing dynamic parser implementations as argument errors; retain dynamic command lookup.
+- Accept signed decimal integers when bounds permit negative values, and detach host-bit-preserving prefix results from caller strings.
+- Add optional byte budgets to Cursor and Document, load Banner from the root, and remove the source-type circular require.
+- Reuse validated deeply frozen plain containers and frozen source strings while preserving cycle detection and defensive copies for mutable values.
+- Require ipaddr 1.2.3 or newer for strict address parsing; retain the Ruby 4.0.6 support policy.
+
+## 0.2.2 (2026-10-18)
+
+- Preserve exact block, capture and unresolved source text independently of Ruby's global output separator.
+- Normalize source lines independently of Ruby's global input separator, without an intermediate chomp allocation.
+- Build cursor lines directly during scanning instead of retaining an intermediate source-line array.
+- Return false from IP address validation for incompatible string encodings.
+
 ## 0.2.1 (2026-10-17)
 
 - Update the configuration benchmark to use the Baseline 0.2 vendor parser namespace.

data/README-zh.md

@@ -21,7 +21,7 @@ gem "ctx_parser"
 
 然后执行 `bundle install`；也可直接执行 `gem install ctx_parser`。Ruby 加载入口为 `ctx_parser`，公开命名空间为 `CtxParser`；gem 包名与 Ruby 命名空间分别维护。
 
-本模块不依赖其他 Gatework 领域 gem。 gemspec 的运行依赖不添加版本约束；应用应提交自己的 `Gemfile.lock`，保持部署可复现。使用本库不需要启动 Rails 或配置兄弟模块的本地路径。
+本模块不依赖其他 Gatework 领域 gem。 gemspec 要求 `ipaddr >= 1.2.3` 以确保严格地址解析，`digest` 不设版本约束；应用应提交自己的 `Gemfile.lock`，保持部署可复现。使用本库不需要启动 Rails 或配置兄弟模块的本地路径。
 
 发布产物和校验值见 [GitHub Releases](https://github.com/gatework/ctx_parser/releases)，已发布版本以 [RubyGems](https://rubygems.org/gems/ctx_parser) 为准。
 
@@ -70,7 +70,7 @@ result.records.each { |row| puts "#{row[:name]}: #{row[:state]}" }
 
 `Parser.parse(text, complete: false)` 返回包含 `status`、`records`、`issues` 的 `Result`；多视图解析器可返回 `Results`。状态为 `complete`、`partial`、`failed`、`unsupported`。子类实现 `parse_output`，配置子类通过 `analyze` 和 `capture` 保留来源。
 
-`complete: true` 只表示调用方确认输入完整接收，不证明所有语法都已理解。未知行、身份冲突及空表证据不足必须明确表达。结果的记录和诊断均须为 Hash 数组；结果及构建完成的文档诊断持有不可变快照。`inspect` 和 `to_s` 不输出结果正文与诊断内容，显式读取记录仍返回原始事实。来源游标有意保留输入原文，含秘密时不可写入日志。
+`complete: true` 只表示调用方确认输入完整接收，不证明所有语法都已理解。未知行、身份冲突及空表证据不足必须明确表达。结果的记录和诊断均须为 Hash 数组；结果及构建完成的文档诊断持有不可变快照。`inspect`、`to_s` 和 pretty printing 不输出结果正文与诊断内容，显式读取记录仍返回原始事实。来源游标有意保留输入原文，含秘密时不可写入日志。
 
 本 gem 不提供厂商命令目录、传输、持久化或健康策略。参数和注册表配置错误保持异常，由调用方在对应边界处理。
 
@@ -84,6 +84,12 @@ result.records.each { |row| puts "#{row[:name]}: #{row[:state]}" }
 
 地址转换使用 `Values.ip_address`、`Values.ip_address?`、`Values.mac_address`。`Values.ipv4_prefix(..., preserve_host_bits: true)` 明确保留接口主机位，默认返回网段前缀。
 
+`Cursor.new(text, max_bytes: limit)` 和 `Document.new(source, max_bytes: limit)` 可在构建或消费来源行前限制输入字节数。传入已有游标时，限制针对其归一化内容。非法编码仍抛出错误；已知为 Latin-1 的输入可先标记 `Encoding::ISO_8859_1`，随后自动转为 UTF-8，不静默替换字节并生成事实。
+
+`MODEL_PARSERS` 的型号键与请求型号一样去除两侧空白并转为小写，归一化冲突和无效覆盖均被拒绝。`Registry` 在注册时校验静态命令与解析器目录；动态目录在使用时仍需校验，缺失实现抛出 `ArgumentError`。
+
+`Records` 持有自己的筛选数组，行对象仍属于调用方；使用期间应保持行不变，需要快照时传入 `Immutable.copy(rows)`。`Immutable.copy` 在逐层校验后可复用深冻结普通容器；浅冻结、特殊 Hash 行为及循环引用仍按原规则复制或拒绝。整数转换仅在 `min` 允许负数或为 `nil` 时接受负号，默认仍只接受非负数。
+
 ## 开发与测试
 
 共享类按实际职责命名，平台信息放在命名空间中。直接对应设备命令的解析器保留文件名和类名。
@@ -99,6 +105,10 @@ bundle exec rake build
 
 使用声明的最低 Ruby 版本检查兼容性。方法用途统一使用简明中文注释；复杂实现还需说明业务规则、实现思路及关键分支。保持公开返回值与错误契约。真实回显和凭据不可进入示例、fixture、日志或发布包。
 
+这些开发命令须在源码检出目录执行；测试、基准和脚本有意排除在安装包之外。
+
+执行 `bundle exec ruby -Ilib benchmark/snapshots.rb` 可测量冻结结果的重复封装；执行 `bundle exec ruby -Ilib benchmark/source.rb`，可使用合成输入和语义断言测量游标及文档构建的耗时与对象分配量，无需领域 gem。此类本地测量不代表设备性能。
+
 ## 发布
 
 本目录可独立维护为 [ctx_parser](https://github.com/gatework/ctx_parser) 仓库。更新 `VERSION` 和 `CHANGELOG.md`，运行上述验证与构建命令，检查包内文件，再创建 `vVERSION` 标签。

data/README.md

@@ -21,7 +21,7 @@ gem "ctx_parser"
 
 Then run `bundle install`, or install directly with `gem install ctx_parser`. The require path is `ctx_parser` and the public namespace is `CtxParser`; package names and Ruby namespaces are intentionally separate.
 
-This package has no dependency on the other Gatework domain gems. The gemspec declares runtime dependencies without version constraints. Applications should commit their own `Gemfile.lock` to make deployments reproducible. No Rails boot or sibling checkout paths are required.
+This package has no dependency on the other Gatework domain gems. The gemspec requires `ipaddr >= 1.2.3` for strict address parsing; `digest` has no version constraint. Applications should commit their own `Gemfile.lock` to make deployments reproducible. No Rails boot or sibling checkout paths are required.
 
 Release artifacts and checksums are available from [GitHub Releases](https://github.com/gatework/ctx_parser/releases). Check [RubyGems](https://rubygems.org/gems/ctx_parser) for published versions.
 
@@ -70,7 +70,7 @@ result.records.each { |row| puts "#{row[:name]}: #{row[:state]}" }
 
 `Parser.parse(text, complete: false)` returns a `Result` with `status`, `records`, and `issues`; a multi-view parser can return `Results`. Result statuses are `complete`, `partial`, `failed`, and `unsupported`. Subclasses implement `parse_output`. Configuration subclasses can use `analyze` and `capture` to preserve provenance.
 
-`complete: true` confirms that the caller received the entire input; it does not certify that all syntax was understood. Unknown rows, identity conflicts, and insufficient empty-table evidence must remain explicit. Result records and issues must be arrays of hashes. Results and completed document diagnostics own immutable snapshots. `inspect` and `to_s` omit result facts and diagnostics; explicit record access still returns the original facts. Source cursors intentionally retain original input and must not be logged when it contains secrets.
+`complete: true` confirms that the caller received the entire input; it does not certify that all syntax was understood. Unknown rows, identity conflicts, and insufficient empty-table evidence must remain explicit. Result records and issues must be arrays of hashes. Results and completed document diagnostics own immutable snapshots. `inspect`, `to_s`, and pretty printing omit result facts and diagnostics; explicit record access still returns the original facts. Source cursors intentionally retain original input and must not be logged when it contains secrets.
 
 This gem supplies no vendor command declarations, transport, persistence, or health policy. Parser/registry argument errors remain exceptions for callers to handle at their own boundary.
 
@@ -84,6 +84,12 @@ A dimension is a named view of facts; a command is the CLI query that supplies t
 
 Address conversion uses `Values.ip_address`, `Values.ip_address?`, and `Values.mac_address`. `Values.ipv4_prefix(..., preserve_host_bits: true)` explicitly preserves interface host bits; its default returns a network prefix.
 
+`Cursor.new(text, max_bytes: limit)` and `Document.new(source, max_bytes: limit)` enforce an optional input byte budget before constructing or consuming lines. For an existing cursor, the budget applies to its normalized content. Invalid encoding remains an error: known Latin-1 input can be tagged as `Encoding::ISO_8859_1` before parsing and is transcoded to UTF-8; bytes are never silently scrubbed into facts.
+
+`MODEL_PARSERS` model names are stripped and lowercased just like the requested model. Normalization collisions and invalid overrides are rejected. `Registry` validates static command/parser declarations when registering a profile; dynamic directory lookup remains validated when used and reports missing implementations as `ArgumentError`.
+
+`Records` owns selection arrays, while row objects remain caller-owned: treat those rows as stable during use, or pass `Immutable.copy(rows)` when a snapshot is needed. `Immutable.copy` can reuse fully frozen plain trees after validating all descendants; shallow-frozen containers, custom Hash behavior, and cycles receive the existing copy or rejection behavior. Integer conversion accepts a minus sign only when `min` permits negative values (or is `nil`); the default remains nonnegative.
+
 ## Development and tests
 
 Name shared classes by their responsibility and use the namespace for platform context. Preserve filenames and class names that directly match device commands.
@@ -99,6 +105,10 @@ bundle exec rake build
 
 Use the declared minimum Ruby version for compatibility checks. Document source methods and non-obvious business logic in concise Chinese, preserve public return/error contracts, and never add raw device captures or credentials to examples, fixtures, logs, or release archives.
 
+Development commands below require a source checkout; tests, benchmarks, and scripts are intentionally excluded from the installed gem archive.
+
+Run `bundle exec ruby -Ilib benchmark/snapshots.rb` to measure repeated wrapping of frozen results, and `bundle exec ruby -Ilib benchmark/source.rb` to measure cursor and document construction with synthetic input and semantic checks. It needs no domain gems and reports elapsed time and allocated objects; these local measurements do not establish device performance.
+
 ## Release
 
 This directory can be maintained as the independent [ctx_parser](https://github.com/gatework/ctx_parser) repository. Update `VERSION` and `CHANGELOG.md`, run the validation and build commands above, and inspect the packaged file list before tagging `vVERSION`.

data/lib/ctx_parser/block.rb

@@ -23,6 +23,7 @@ module CtxParser
             child.index > previous_index && child.last_index <= last_index && child.header.indent > header.indent
 
           previous_index = child.last_index
+          true
         end
         raise ArgumentError, "Child blocks must be ordered within their parent source"
       end
@@ -88,7 +89,7 @@ module CtxParser
 
     # 返回配置块标题的零起始索引。
     def index = header.index
-    # 返回配置块标题的一起始来源行号。
+    # 返回配置块标题从 1 开始的来源行号。
     def line = header.number
     # 返回已去除外围缩进和行结束符的来源内容。
     def text = header.text
@@ -97,7 +98,7 @@ module CtxParser
     # 返回属于当前配置块的原始来源行。
     def lines = cursor.lines[index..last_index].freeze
     # 返回配置块或捕获事实对应的精确来源文本。
-    def content = lines.map(&:raw).join.freeze
+    def content = lines.map(&:raw).join("").freeze
     # 返回当前配置块各来源行的处理状态。
     def states = lines.map { |source| cursor.state(source.index) }.freeze
     # 要求块内所有来源行均已解析或明确忽略。

data/lib/ctx_parser/capture.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "block"
 require_relative "immutable"
 
 module CtxParser
@@ -22,6 +21,7 @@ module CtxParser
 
     # 冻结解析事实及其来源块和结果路径。
     def initialize(block:, data:, path:)
+      require_relative "block" unless defined?(Block)
       raise ArgumentError, "Capture source must be a block" unless block.is_a?(Block)
 
       initialize_snapshot(block, Snapshot.new(data: data, path: path))
@@ -29,6 +29,7 @@ module CtxParser
 
     # 同一事实的多个来源共享已复制的值，不共享未经校验的调用方容器。
     def self.for_blocks(blocks, data:, path:)
+      require_relative "block" unless defined?(Block)
       unless blocks.is_a?(Array) && blocks.all? { |block| block.is_a?(Block) }
         raise ArgumentError, "Capture sources must be blocks"
       end

data/lib/ctx_parser/cursor.rb

@@ -14,14 +14,17 @@ module CtxParser
     attr_reader :content, :lines, :checksum, :position
 
     # 为单次解析创建独立的来源行、语义状态及事实索引。
-    def initialize(content)
+    def initialize(content, max_bytes: nil)
       raise ArgumentError, "Configuration content must be text" unless content.is_a?(String)
 
-      @content = Input.text(content, encoding: :transcode).freeze
+      @content = Input.text(content, encoding: :transcode, max_bytes: max_bytes).freeze
 
-      @lines = @content.scan(/[^\r\n]*(?:\r\n|\r|\n)|[^\r\n]+\z/).each_with_index.map do |raw, index|
-        Line.new(index: index, raw: raw)
-      end.freeze
+      # scan 直接交付每行，避免同时保留原始行数组与 Line 数组。
+      @lines = []
+      @content.scan(/[^\r\n]*(?:\r\n|\r|\n)|[^\r\n]+\z/) do |raw|
+        @lines << Line.new(index: @lines.size, raw: raw.freeze)
+      end
+      @lines.freeze
       @checksum = Digest::SHA256.hexdigest(@content).freeze
       reset!
     end
@@ -123,7 +126,7 @@ module CtxParser
     end
 
     # 拼接未解决来源行，并保留原有格式。
-    def unparsed_content = unparsed_lines.map(&:raw).join.freeze
+    def unparsed_content = unparsed_lines.map(&:raw).join("").freeze
 
     # 将事实快照关联到来源块，不将整个块标记为解析成功。
     def capture(block, data:, path:)
@@ -132,6 +135,7 @@ module CtxParser
 
     # 注册归纳事实的不可变快照前，先校验全部来源。
     def capture_many(blocks, data:, path:)
+      require_relative "block" unless defined?(Block)
       unless blocks.is_a?(Array) && blocks.all? { |block| block.is_a?(Block) && block.cursor.equal?(self) }
         raise ArgumentError, "Blocks must belong to this cursor"
       end

data/lib/ctx_parser/document.rb

@@ -9,8 +9,14 @@ module CtxParser
     attr_reader :cursor, :roots, :issues
 
     # 使用平台提供的注释及边界规则构建来源文档。
-    def initialize(source, comments: nil, boundaries: nil)
-      @cursor = source.is_a?(Cursor) ? source : Cursor.new(source)
+    def initialize(source, comments: nil, boundaries: nil, max_bytes: nil)
+      if source.is_a?(Cursor)
+        unless max_bytes.nil? || max_bytes.is_a?(Integer) && max_bytes >= 0
+          raise ArgumentError, "Invalid byte limit"
+        end
+        raise ArgumentError, "CLI output exceeds byte limit" if max_bytes && source.content.bytesize > max_bytes
+      end
+      @cursor = source.is_a?(Cursor) ? source : Cursor.new(source, max_bytes: max_bytes)
       @comments, @boundaries, @issues = comments, boundaries, []
       @roots = Block.read(cursor) { |line| classify(line) }
       finish

data/lib/ctx_parser/immutable.rb

@@ -23,6 +23,10 @@ module CtxParser
         return copy_deep(value, copies) if depth == 64
 
         copies[value] = COPYING
+        if reusable?(value, copies, depth)
+          copies[value] = value
+          return value
+        end
         copies[value] = if value.is_a?(Hash)
           value.to_h { |key, item| [ copy_value(key, copies, depth + 1), copy_value(item, copies, depth + 1) ] }.freeze
         else
@@ -40,13 +44,31 @@ module CtxParser
     end
     private_class_method :copy_value
 
+    # 仅复用无特殊 Hash 行为的深冻结普通容器；逐层验证，不信任外层 frozen?。
+    def self.reusable?(value, copies, depth)
+      return false unless value.frozen? && value.instance_variables.empty?
+      if value.instance_of?(Array)
+        value.all? { |item| copy_value(item, copies, depth + 1).equal?(item) }
+      elsif value.instance_of?(Hash) && value.default.nil? && !value.default_proc && !value.compare_by_identity?
+        value.each_pair do |key, item|
+          return false unless copy_value(key, copies, depth + 1).equal?(key) && copy_value(item, copies, depth + 1).equal?(item)
+        end
+        true
+      else
+        false
+      end
+    end
+    private_class_method :reusable?
+
     # 容器缓存按来源身份查找，普通 Hash 的键仍沿用值相等语义。
     def self.copy_deep(value, copies)
       pending = [ [ value, false ] ]
       until pending.empty?
         source, finishing = pending.pop
         if finishing
-          copies[source] = if source.is_a?(Hash)
+          copies[source] = if reusable?(source, copies, 0)
+            source
+          elsif source.is_a?(Hash)
             source.to_h { |key, item| [ snapshot(key, copies), snapshot(item, copies) ] }.freeze
           else
             source.map { |item| snapshot(item, copies) }.freeze

data/lib/ctx_parser/line.rb

@@ -8,12 +8,13 @@ module CtxParser
       raise ArgumentError, "Line index must be nonnegative" unless index.is_a?(Integer) && index >= 0
       raise ArgumentError, "Line content must be text" unless raw.is_a?(String)
 
-      @text = raw.chomp.strip.freeze
+      # strip 已移除行结束空白，避免 chomp 依赖宿主进程的 $/。
+      @text = raw.strip.freeze
       @indent = raw[/\A[ \t]*/].size
-      super(index: index, raw: raw.dup.freeze)
+      super(index: index, raw: raw.frozen? ? raw : raw.dup.freeze)
     end
 
-    # 返回诊断使用的一起始行号。
+    # 返回诊断使用的从 1 开始的行号。
     def number = index + 1
     # 返回已去除外围缩进和行结束符的来源内容。
     def text = @text
@@ -24,5 +25,8 @@ module CtxParser
     # 展示对象身份与状态，避免泄露原始回显或凭据。
     def inspect = "#<#{self.class.name} number=#{number}>"
     alias to_s inspect
+
+    # PP 不得绕过 inspect 暴露来源行。
+    def pretty_print(printer) = printer.text(inspect)
   end
 end

data/lib/ctx_parser/profile.rb

@@ -17,8 +17,39 @@ module CtxParser
 
       @model = model&.strip&.downcase&.freeze
       @model_parsers = model_parser_overrides
+      @static_commands = self.class::COMMANDS
+      @command_queries = compile_commands(@static_commands)
     end
 
+    # 注册时核对静态目录；动态实例仍在实际查询时重新校验。
+    def self.validate_declarations!
+      directory, implementations = self::COMMANDS, self::PARSERS
+      unless directory.is_a?(Hash) && implementations.is_a?(Hash) &&
+          directory.keys.all? { |name| name.is_a?(Symbol) && !name.empty? }
+        raise ArgumentError, "Profile commands and parsers must be named mappings"
+      end
+
+      queries = directory.values.flat_map do |value|
+        entries = value.is_a?(Array) ? value : [ value ]
+        unless entries.any? && entries.uniq == entries && entries.all? { |entry| valid_command?(entry) }
+          raise ArgumentError, "Parser dimension must declare one or more unique commands"
+        end
+        entries
+      end.uniq
+      unless (queries - implementations.keys).empty? && (implementations.keys - queries).empty? &&
+          implementations.values.all? { |parser| parser.is_a?(Class) && parser < Parser }
+        raise ArgumentError, "Profile commands must match Parser implementations"
+      end
+      normalized_model_parsers
+      true
+    end
+
+    # 校验静态目录中的单命令文本，不接受控制字符。
+    def self.valid_command?(value)
+      value.is_a?(String) && !value.strip.empty? && !/[\x00-\x1f\x7f]/.match?(value)
+    end
+    private_class_method :valid_command?
+
     # 返回当前平台策略声明的命令目录。
     def commands = self.class::COMMANDS
 
@@ -40,13 +71,11 @@ module CtxParser
 
     # 单个维度可能需要多个独立回显；调用方必须分别保存正文。
     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
+      directory = commands
+      declaration = directory.fetch(name) { raise ArgumentError, "Unsupported parser dimension" }
+      return @command_queries.fetch(name) if @command_queries && directory.equal?(@static_commands)
 
-      queries.map { |query| query.frozen? ? query : query.dup.freeze }.freeze
+      validated_queries(declaration)
     end
 
     # 解析支持的观测维度对应的命令。
@@ -60,7 +89,7 @@ module CtxParser
     # 确定维度使用的解析器，包括命令特定变体。
     def parser_for(name, command: nil)
       query = select_command([ name ], command)
-      @model_parsers.fetch(query) { parsers.fetch(query) }
+      implementation_for(query)
     end
 
     # 选择目标命令解析器，并投影单个请求维度。
@@ -76,39 +105,83 @@ module CtxParser
       query = select_command(dimensions, command)
 
       # 查询已覆盖全部请求维度，无需再次遍历第一个维度的完整命令列表。
-      result = @model_parsers.fetch(query) { parsers.fetch(query) }.parse(text, complete: complete)
+      result = implementation_for(query).parse(text, complete: complete)
       dimensions.to_h { |name| [ name, project_independently(name, result) ] }
     end
 
     private
 
+    # 仅为深冻结的静态目录建立快照；可变或被替换的目录仍走实时校验。
+    def compile_commands(directory)
+      return unless directory.instance_of?(Hash) && directory.frozen? && !directory.compare_by_identity? &&
+          directory.keys.all? { |name| name.is_a?(Symbol) && !name.empty? } && directory.values.all? do |value|
+        entries = value.is_a?(Array) ? value : [ value ]
+        (!value.is_a?(Array) || value.frozen?) && entries.all? { |query| query.is_a?(String) && query.frozen? }
+      end
+
+      directory.to_h { |name, declaration| [ name, validated_queries(declaration) ] }.freeze
+    end
+
+    # 查询快照不冻结调用方的数组或字符串。
+    def validated_queries(declaration)
+      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 select_command(dimensions, selected)
       candidates = dimensions.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
+      if selected.nil?
         raise ArgumentError, "One CLI output must belong to one command" unless candidates.one?
 
         candidates.first
+      else
+        raise ArgumentError, "Selected command does not provide all parser dimensions" unless candidates.include?(selected)
+
+        selected
       end
     end
 
     # 采集前校验所选型号，并隔离后续修改对型号查找的影响。
-    def model_parser_overrides
-      declarations = self.class::MODEL_PARSERS
+    def self.normalized_model_parsers
+      declarations = self::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
+      normalized = {}
+      declarations.each do |name, overrides|
+        unless name.nil? || name.is_a?(String) && !name.strip.empty?
+          raise ArgumentError, "Model parser keys must be device model names"
         end
-        raise ArgumentError, "Model parsers must override declared commands with Parser subclasses"
+        key = name&.strip&.downcase
+        raise ArgumentError, "Model parser names must be unique after normalization" if normalized.key?(key)
+        unless overrides.is_a?(Hash) && overrides.all? do |command, parser|
+            self::PARSERS.key?(command) && parser.is_a?(Class) && parser < Parser
+          end
+          raise ArgumentError, "Model parsers must override declared commands with Parser subclasses"
+        end
+        normalized[key] = overrides
       end
 
-      overrides.dup.freeze
+      normalized
+    end
+    private_class_method :normalized_model_parsers
+
+    # 注册与实例选择共用声明校验，所选覆盖仍独立于后续调用方修改。
+    def model_parser_overrides
+      self.class.send(:normalized_model_parsers).fetch(model, {}).dup.freeze
+    end
+
+    # 动态目录的错误仍在调用边界报告，不暴露底层 Hash 的 KeyError。
+    def implementation_for(query)
+      implementation = @model_parsers.fetch(query) { parsers.fetch(query) { raise ArgumentError, "Missing command parser" } }
+      unless implementation.is_a?(Class) && implementation < Parser
+        raise ArgumentError, "Command parser must inherit from Parser"
+      end
+      implementation
     end
 
     # 投影失败仅影响单个视图；命令选择及解析错误仍正常抛出。

data/lib/ctx_parser/registry.rb

@@ -18,9 +18,10 @@ module CtxParser
           @aliases.values.all? { |key| @profiles.key?(key) } && (@profiles.keys & @aliases.keys).empty?
         raise ArgumentError, "Invalid parser registry"
       end
+      @profiles.each_value(&:validate_declarations!)
     end
 
-    # 解析请求的解析结果或平台策略，拒绝未知名称。
+    # 按平台或别名创建 Profile 实例，拒绝未知名称。
     def fetch(platform, model: nil)
       key = platform_key(platform)
       key = @aliases.fetch(key, key)

data/lib/ctx_parser/result.rb

@@ -20,5 +20,8 @@ module CtxParser
     # 展示对象身份与状态，避免泄露原始回显或凭据。
     def inspect = "#<#{self.class.name} status=#{status} records=#{records.size}>"
     alias to_s inspect
+
+    # PP 对 Data 默认展开成员，必须显式沿用脱敏展示。
+    def pretty_print(printer) = printer.text(inspect)
   end
 end

data/lib/ctx_parser/results.rb

@@ -39,5 +39,8 @@ module CtxParser
     # 展示对象身份与状态，避免泄露原始回显或凭据。
     def inspect = "#<#{self.class.name} status=#{status} dimensions=#{by_dimension.keys.join(',')}>"
     alias to_s inspect
+
+    # 具名结果的嵌套展示同样不能展开事实或诊断。
+    def pretty_print(printer) = printer.text(inspect)
   end
 end

data/lib/ctx_parser/values.rb

@@ -15,7 +15,8 @@ module CtxParser
         raise ArgumentError, "Invalid integer limits"
       end
       return if raw.nil?
-      unless (raw.is_a?(String) || raw.is_a?(Integer)) && /\A\d+\z/.match?(raw.to_s)
+      pattern = min.nil? || min.negative? ? /\A-?\d+\z/ : /\A\d+\z/
+      unless (raw.is_a?(String) || raw.is_a?(Integer)) && pattern.match?(raw.to_s)
         raise ArgumentError, "Invalid decimal integer"
       end
 
@@ -48,7 +49,7 @@ module CtxParser
     # 校验主机地址有效性，不让格式错误值继续传播。
     def ip_address?(raw, allow_zone: false)
       !ip_address(raw, allow_zone: allow_zone).nil?
-    rescue ArgumentError, IPAddr::Error
+    rescue ArgumentError, IPAddr::Error, EncodingError
       false
     end
 
@@ -61,7 +62,7 @@ module CtxParser
       network = IPAddr.new(raw)
       raise ArgumentError, "IPv4 prefix required" unless network.ipv4?
 
-      preserve_host_bits ? raw : "#{network}/#{network.prefix}"
+      preserve_host_bits ? raw.dup : "#{network}/#{network.prefix}"
     end
   end
 end

data/lib/ctx_parser/version.rb

@@ -2,5 +2,5 @@
 
 module CtxParser
   # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

data/lib/ctx_parser.rb

@@ -7,6 +7,7 @@ module CtxParser
 end
 
 require_relative "ctx_parser/parser"
+# 直接加载 parser 时，命名空间 autoload 可能重入此入口；此时 Parser 尚未定义。
 if CtxParser.const_defined?(:Parser, false)
   require_relative "ctx_parser/configuration"
   require_relative "ctx_parser/values"
@@ -14,4 +15,5 @@ if CtxParser.const_defined?(:Parser, false)
   require_relative "ctx_parser/commands"
   require_relative "ctx_parser/profile"
   require_relative "ctx_parser/registry"
+  require_relative "ctx_parser/banner"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ctx_parser
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Gatework contributors
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.2.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.2.3
 description: Reusable configuration documents, command declarations, platform profiles,
   immutable results and parsing primitives for network automation.
 executables: []