ctx_parser 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19faa09b189e01bb0d76ad334a769bebe9c54fb2cc05bea40e335f81f02d2764
-  data.tar.gz: 1484eafe0166f0141d7dfdf3709364ef7cea19dca5cc56c4e2356711504f2876
+  metadata.gz: 488dca1bfd052afe8a7719c6e5c89d4b2b5c86f189243c02b651438ce45a69c1
+  data.tar.gz: 33e7aa374cc8285c6dbb76ff4c9d87849116c3fa1a61ddb1ee720d108baed8ee
 SHA512:
-  metadata.gz: 8bbc87c894cfe9c6db52ebcacbce0c0ceda4c1e979a670d2c63b7b2f80402bc91a8afa83987b3b3945c4c2e02481ffea80cf7b9bc9dfc6704489afbd2f196a17
-  data.tar.gz: 4d387bb4fb40ed03cd08b719064c33fa88978cccc1274d46236bc8b4a965cf07aa18aceab92f5f37d9cbce571852f202ad5fa08de532d98ea2f8fc082230c891
+  metadata.gz: 8459a636b16bdbe34e4446530714b1f686daa9bab80ca0cb713fdff9422066a388a7410dae7d083126c92415c8cb97f479a321da91d6113feb947cd03158bff6
+  data.tar.gz: ae3de9681c49c1d4be422c3b4b7c1fc47aeb0c152cb740370846fc3f80122435b184de6f2c977c3dac06d848c04a2c2d7191ad54d286214eee027c67d0b48abc

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 Changes to the public contract are recorded here. Versions follow Semantic Versioning.
 
+## Unreleased
+
+## 0.2.6 (2026-10-21)
+
+- Build immutable hash snapshots without temporary field-pair arrays, retaining ordinary key equality, cycle rejection and deep-tree support.
+
+- Add repository-specific AGENTS.md guidance for responsibilities, Ruby conventions, evidence boundaries and validation.
+- Snapshot requested profile views before parser callbacks can mutate caller selections.
+- Avoid redundant UTF-8 conversion and line-ending replacement for already normalized inputs while preserving mutable detached return values.
+
+## 0.2.5 (2026-10-19)
+
+- Keep offline example facts and configuration benchmark inputs independent of Ruby's global input and output separators.
+- Reuse validated dynamic command directories and membership indexes when their complete contents are frozen, avoiding repeated full-directory validation during discovered-query preparation. Mutable and replaced directories retain current lookup semantics.
+
 ## 0.2.4 (2026-10-18)
 
 - Clear Bundler bootstrap variables when verifying packages in an isolated gem installation, including calls made through bundle exec.

data/README-zh.md

@@ -46,7 +46,7 @@ class ExampleStatusParser < CtxParser::Parser
   def parse_output(text, complete:)
     records = []
     issues = []
-    text.each_line.with_index(1) do |line, number|
+    text.each_line("\n").with_index(1) do |line, number|
       next if line.strip.empty?
 
       match = /\A([A-Za-z0-9\/]+) (up|down)\z/.match(line.strip)
@@ -88,6 +88,8 @@ result.records.each { |row| puts "#{row[:name]}: #{row[:state]}" }
 
 `MODEL_PARSERS` 的型号键与请求型号一样去除两侧空白并转为小写，归一化冲突和无效覆盖均被拒绝。`Registry` 在注册时校验静态命令与解析器目录；动态目录在使用时仍需校验，缺失实现抛出 `ArgumentError`。
 
+Profile 为深冻结的普通命令目录复用查询列表与成员索引，包括发现阶段产生的目录。替换目录后重建索引；可变条目仍在每次查找时校验。`bundle exec ruby -Ilib benchmark/profile.rb` 测量 32、128、512 条合成命令的准备开销，并校验选择顺序与未知命令拒绝行为。
+
 `Records` 持有自己的筛选数组，行对象仍属于调用方；使用期间应保持行不变，需要快照时传入 `Immutable.copy(rows)`。`Immutable.copy` 在逐层校验后可复用深冻结普通容器；浅冻结、特殊 Hash 行为及循环引用仍按原规则复制或拒绝。整数转换仅在 `min` 允许负数或为 `nil` 时接受负号，默认仍只接受非负数。
 
 ## 开发与测试

data/README.md

@@ -46,7 +46,7 @@ class ExampleStatusParser < CtxParser::Parser
   def parse_output(text, complete:)
     records = []
     issues = []
-    text.each_line.with_index(1) do |line, number|
+    text.each_line("\n").with_index(1) do |line, number|
       next if line.strip.empty?
 
       match = /\A([A-Za-z0-9\/]+) (up|down)\z/.match(line.strip)
@@ -88,6 +88,8 @@ Address conversion uses `Values.ip_address`, `Values.ip_address?`, and `Values.m
 
 `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`.
 
+Profiles reuse query lists and membership indexes for fully frozen plain command directories, including directories created by discovery. Replacing a directory rebuilds its index; mutable entries are validated on each lookup. `bundle exec ruby -Ilib benchmark/profile.rb` measures preparation of 32, 128 and 512 synthetic commands and checks selection order and rejection of unknown commands.
+
 `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

data/docs/input-performance.md

@@ -0,0 +1,19 @@
+# 输入归一化验证（2026-10-21）
+
+`Input.text` 的常见路径原先会对 UTF-8 输入再次执行 `encode(UTF_8)`，并在 LF 正文上执行无匹配的 `gsub`。现在跳过相同编码的转换，在没有 CR 时跳过替换；需要修改时只操作归一化过程拥有的副本。返回值仍可变且独立于调用方；原文、编码策略、逻辑 NUL 校验和转码前字节预算不变。
+
+在 macOS arm64、Ruby 4.0.6 上使用 `benchmark/input.rb`，对修改前的 `b8746d9` 与本次源码执行相同脚本。每轮重复归一化同一正文 30 次，共三轮；语义和对象所有权断言在计时外执行。下表是三轮中位数，属于重复输入的本地微基准，不代表设备采集、完整配置解析或网络吞吐。
+
+| 正文 | 输入字节 | 修改前耗时 | 修改后耗时 | 修改前分配 | 修改后分配 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| UTF-8 / LF | 950000 | 67.354 ms | 0.866 ms | 120 | 30 |
+| UTF-8 / CRLF | 1000000 | 177.798 ms | 162.056 ms | 150 | 150 |
+| ISO-8859-1 / LF | 850000 | 169.909 ms | 90.748 ms | 150 | 60 |
+
+复测当前代码：
+
+```sh
+bundle exec ruby -Ilib benchmark/input.rb
+```
+
+比较基线时，把目标提交的 `lib/ctx_parser/input.rb` 放入独立临时目录的 `ctx_parser/input.rb`，然后使用 `bundle exec ruby -I<临时目录> benchmark/input.rb`。脚本输出实际加载的 Input 来源，避免误测已安装版本。不要覆盖工作区文件来切换基线。

data/examples/offline.rb

@@ -10,7 +10,7 @@ class ExampleStatusParser < CtxParser::Parser
   def parse_output(text, complete:)
     records = []
     issues = []
-    text.each_line.with_index(1) do |line, number|
+    text.each_line("\n").with_index(1) do |line, number|
       next if line.strip.empty?
 
       match = /\A([A-Za-z0-9\/]+) (up|down)\z/.match(line.strip)

data/lib/ctx_parser/immutable.rb

@@ -28,7 +28,9 @@ module CtxParser
           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
+          result = {}
+          value.each_pair { |key, item| result[copy_value(key, copies, depth + 1)] = copy_value(item, copies, depth + 1) }
+          result.freeze
         else
           value.map { |item| copy_value(item, copies, depth + 1) }.freeze
         end
@@ -69,7 +71,9 @@ module CtxParser
           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
+            result = {}
+            source.each_pair { |key, item| result[snapshot(key, copies)] = snapshot(item, copies) }
+            result.freeze
           else
             source.map { |item| snapshot(item, copies) }.freeze
           end

data/lib/ctx_parser/input.rb

@@ -18,14 +18,18 @@ module CtxParser
       value.force_encoding(Encoding::UTF_8) if encoding == :utf8 || value.encoding == Encoding::BINARY
       raise EncodingError, "CLI output encoding is invalid" unless value.valid_encoding?
 
-      value = value.encode(Encoding::UTF_8) if encoding == :transcode
+      value = value.encode(Encoding::UTF_8) if encoding == :transcode && value.encoding != Encoding::UTF_8
       # UTF-16/32 等编码不兼容 ASCII 字面量；仅在临时视图上检查逻辑字符。
       logical = value.encoding.ascii_compatible? ? value : value.encode(Encoding::UTF_8)
       raise ArgumentError, "CLI output contains a NUL byte" if !allow_nul && logical.include?("\0")
 
       normalized = case newlines
-      when :lf then logical.gsub(/\r\n?/, "\n")
-      when :delete_cr then logical.delete("\r")
+      when :lf
+        logical.gsub!(/\r\n?/, "\n") if logical.include?("\r")
+        logical
+      when :delete_cr
+        logical.delete!("\r")
+        logical
       else return value
       end
       normalized.encoding == value.encoding ? normalized : normalized.encode(value.encoding)

data/lib/ctx_parser/profile.rb

@@ -17,8 +17,7 @@ module CtxParser
 
       @model = model&.strip&.downcase&.freeze
       @model_parsers = model_parser_overrides
-      @static_commands = self.class::COMMANDS
-      @command_queries = compile_commands(@static_commands)
+      cache_commands(self.class::COMMANDS, strict: true)
     end
 
     # 注册时核对静态目录；动态实例仍在实际查询时重新校验。
@@ -73,7 +72,8 @@ module CtxParser
     def commands_for(name)
       directory = commands
       declaration = directory.fetch(name) { raise ArgumentError, "Unsupported parser dimension" }
-      return @command_queries.fetch(name) if @command_queries && directory.equal?(@static_commands)
+      cached = cache_commands(directory)
+      return cached[:queries].fetch(name) if cached
 
       validated_queries(declaration)
     end
@@ -102,6 +102,8 @@ module CtxParser
       unless dimensions.is_a?(Array) && dimensions.any? && dimensions.uniq == dimensions
         raise ArgumentError, "Parser dimensions must be a nonempty unique array"
       end
+      # 扩展解析器可调用外部代码；结果投影始终使用入口处的请求。
+      dimensions = dimensions.dup.freeze
       query = select_command(dimensions, command)
 
       # 查询已覆盖全部请求维度，无需再次遍历第一个维度的完整命令列表。
@@ -111,12 +113,32 @@ module CtxParser
 
     private
 
-    # 仅为深冻结的静态目录建立快照；可变或被替换的目录仍走实时校验。
+    # 发现阶段可替换实例目录；只缓存当前深冻结目录，不继承旧目录的选择结果。
+    def cache_commands(directory, strict: false)
+      cached = @command_cache
+      return cached if cached && directory.equal?(cached[:directory])
+      return if frozen?
+
+      queries = compile_commands(directory)
+      return unless queries
+
+      membership = queries.transform_values { |entries| entries.to_h { |query| [ query, true ] }.freeze }.freeze
+      # 一次发布完整索引；并发查找只读取自己取得的快照，不混合两份目录。
+      @command_cache = { directory: directory, queries: queries, membership: membership }.freeze
+    rescue ArgumentError
+      # 动态目录仍按请求维度报错，未使用的无效声明不能阻断其他维度。
+      raise if strict
+
+      nil
+    end
+
+    # 可变容器或文本仍逐次校验；普通深冻结目录允许共享验证后的顺序与成员索引。
     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? }
+        (!value.is_a?(Array) || value.instance_of?(Array) && value.frozen?) &&
+          entries.all? { |query| query.instance_of?(String) && query.frozen? }
       end
 
       directory.to_h { |name, declaration| [ name, validated_queries(declaration) ] }.freeze
@@ -134,13 +156,26 @@ module CtxParser
 
     # 仅当存在唯一公共查询时允许推断；显式命令必须覆盖全部请求视图。
     def select_command(dimensions, selected)
-      candidates = dimensions.map { |name| commands_for(name) }.reduce { |common, queries| common & queries }
+      declarations = dimensions.map do |name|
+        queries = commands_for(name)
+        cached = @command_cache
+        membership = cached[:membership][name] if cached && queries.equal?(cached[:queries][name])
+        [ queries, membership ]
+      end
       if selected.nil?
+        candidates = declarations.map(&:first).reduce { |common, queries| common & queries }
         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)
+        supported = declarations.all? do |queries, membership|
+          if selected.instance_of?(String) && membership
+            membership.key?(selected)
+          else
+            queries.include?(selected)
+          end
+        end
+        raise ArgumentError, "Selected command does not provide all parser dimensions" unless supported
 
         selected
       end

data/lib/ctx_parser/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ctx_parser
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 platform: ruby
 authors:
 - Gatework contributors
@@ -48,6 +48,7 @@ files:
 - README-zh.md
 - README.md
 - docs/architecture-zh.md
+- docs/input-performance.md
 - docs/release.md
 - examples/offline.rb
 - lib/ctx_parser.rb