ctx_parser 0.2.9 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '05721084ade7516289ec28e3d1330349e1a24536838523b386a04c1e760cca40'
-  data.tar.gz: 17812aad28594b7fee5e3abb9e287e8a8876831aea01bbcb3e672282103cc90f
+  metadata.gz: 207ae07b7f1f12d8d8a91ce6ea1a89fc39bb2c566f3d1cebe289ab71012aadd5
+  data.tar.gz: 1249139af57dd39b634ad948028af664af72eea4af7e5cb9a0137e4117f8eecd
 SHA512:
-  metadata.gz: 93ae2fc0264f54382ae02aae0c5de52bbba3ed7c0b56466c251d314b990c3846e33b57716672d9f9a7273722de42d0b8f0d1e07e511631b5b0e96d43c555126b
-  data.tar.gz: be753612b50f307c882ca33bcdc2aae5f17fc84206c3cb935107777e7f7886323f107ba1b42b329f819cbcc302e37c86556b12c64b0948ea5fc030d70b739fc4
+  metadata.gz: 43e613f54ffa2b660d9badc6e2ce1195ed9fbf5b3fd864c8b85102c0cfae4eb9aa3cac477c7e7c9e92116d3c3e40234ce58e0e6c08db1757106c78a1c0e976f4
+  data.tar.gz: d8a2b623628265babbcaedc0f3d15b29257945917e6e4db13d6958680457c1d4f3028066d416c77ff2c2d29a3da8dde5d7520da920d8a40b8ca3794a7247bf04

data/CHANGELOG.md

@@ -4,6 +4,15 @@ Changes to the public contract are recorded here. Versions follow Semantic Versi
 
 ## Unreleased
 
+## 0.4.0 (2026-10-29)
+
+- Add immutable `covered_scopes` to Result, including equality, hashing, pattern matching and `with` semantics.
+- Centralize single-line command validation in `Commands.command_text` and strict UTC timestamp parsing in `Values.timestamp`.
+
+## 0.3.0 (2026-10-29)
+
+- Add `Result#partial?` and `#available?`; reject records on failed or unsupported results.
+
 ## 0.2.9 (2026-10-24)
 
 - Correct dependency documentation to match the unconstrained ipaddr and digest declarations; applications select and validate their runtime dependency combination.

data/README-zh.md

@@ -122,3 +122,6 @@ CI 在 Linux、macOS 上执行测试、lint、示例、构建和隔离安装。`
 ## 许可证
 
 MIT，见 [LICENSE](LICENSE)。
+
+
+`Result#partial?` identifies partial parsing; `#available?` is true for complete or partial results. Failed and unsupported results cannot contain records. Availability does not establish completeness or network health.

data/README.md

@@ -122,3 +122,8 @@ Publish dependency gems first. A Git tag, a successful build, or a workflow file
 ## License
 
 MIT. See [LICENSE](LICENSE).
+
+
+`Result#partial?` identifies partial parsing; `#available?` is true for complete or partial results. Failed and unsupported results cannot contain records. Availability does not establish completeness or network health.
+
+本次使用 ctx_parser 0.4 系列契约；`Result` 新增 `covered_scopes`，单行命令统一由 `CtxParser::Commands.command_text` 校验。跨模块约定见 [ctx_runner 契约迁移](https://github.com/gatework/ctx_runner/blob/main/docs/contracts-2026-10-29.md)。

data/lib/ctx_parser/commands.rb

@@ -7,6 +7,14 @@ module CtxParser
   class Commands
     attr_reader :entries, :by_dimension, :parsers
 
+    # 查询文本的唯一值边界；复制后冻结，不冻结调用方提供的字符串。
+    def self.command_text(value)
+      unless value.is_a?(String) && !value.strip.empty? && !/[\x00-\x1f\x7f]/.match?(value)
+        raise ArgumentError, "One command without control characters is required"
+      end
+      value.frozen? ? value : value.dup.freeze
+    end
+
     # 校验并冻结受支持的维度到命令声明。
     def initialize(entries, multi_command: false)
       unless entries.is_a?(Array) && entries.any?
@@ -36,13 +44,10 @@ module CtxParser
           dimensions.uniq == dimensions && (@multi_command || dimensions.none? { |name| @by_dimension.key?(name) })
         raise ArgumentError, "Command dimensions must be unique nonempty symbols"
       end
-      unless command.is_a?(String) && !command.strip.empty? && !/[\x00-\x1f\x7f]/.match?(command)
-        raise ArgumentError, "Command must be nonempty text without control characters"
-      end
+      command = self.class.command_text(command)
       raise ArgumentError, "Command is already declared" if @parsers.key?(command)
       raise ArgumentError, "Command parser must inherit from Parser" unless parser.is_a?(Class) && parser < Parser
 
-      command = command.dup.freeze
       dimensions = dimensions.dup.freeze
       dimensions.each do |name|
         # 索引数组由本实例持有，构建完成后统一冻结；追加不复制已有命令。

data/lib/ctx_parser/profile.rb

@@ -45,7 +45,10 @@ module CtxParser
 
     # 校验静态目录中的单命令文本，不接受控制字符。
     def self.valid_command?(value)
-      value.is_a?(String) && !value.strip.empty? && !/[\x00-\x1f\x7f]/.match?(value)
+      Commands.command_text(value)
+      true
+    rescue ArgumentError
+      false
     end
     private_class_method :valid_command?
 
@@ -147,11 +150,11 @@ module CtxParser
     # 查询快照不冻结调用方的数组或字符串。
     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) }
+      unless queries.any? && queries.uniq == queries
         raise ArgumentError, "Parser dimension must declare one or more unique commands"
       end
 
-      queries.map { |query| query.frozen? ? query : query.dup.freeze }.freeze
+      queries.map { |query| Commands.command_text(query) }.freeze
     end
 
     # 仅当存在唯一公共查询时允许推断；显式命令必须覆盖全部请求视图。

data/lib/ctx_parser/result.rb

@@ -4,18 +4,28 @@ require_relative "immutable"
 
 module CtxParser
   # 仅保存解析结果；采集命令、时间与证据由调用方管理。
-  Result = Data.define(:status, :records, :issues) do
+  Result = Data.define(:status, :records, :issues, :covered_scopes) do
     # 冻结解析状态、归一化记录与诊断证据。
-    def initialize(status:, records: [], issues: [])
+    def initialize(status:, records: [], issues: [], covered_scopes: [])
       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) }
       raise ArgumentError, "Issues must be hashes" unless issues.is_a?(Array) && issues.all? { |issue| issue.is_a?(Hash) }
+      unless covered_scopes.is_a?(Array) && covered_scopes.all? { |scope| scope.is_a?(Hash) } && covered_scopes.uniq == covered_scopes
+        raise ArgumentError, "Covered scopes must be unique hashes"
+      end
 
-      super(status: status, records: Immutable.copy(records), issues: Immutable.copy(issues))
+      if %i[failed unsupported].include?(status) && (records.any? || covered_scopes.any?)
+        raise ArgumentError, "Unavailable parser results cannot contain records or covered scopes"
+      end
+
+      super(status: status, records: Immutable.copy(records), issues: Immutable.copy(issues), covered_scopes: Immutable.copy(covered_scopes))
     end
 
     # 判断解析结果是否具有完整证据。
     def complete? = status == :complete
+    # 不完整事实仍可用于报告已观察到的问题。
+    def partial? = status == :partial
+    def available? = complete? || partial?
 
     # 展示对象身份与状态，避免泄露原始回显或凭据。
     def inspect = "#<#{self.class.name} status=#{status} records=#{records.size}>"

data/lib/ctx_parser/values.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "ipaddr"
+require "time"
+require "date"
 
 module CtxParser
   # 严格转换标量；单位及可选字段语法仍由命令解析器负责。
@@ -9,6 +11,19 @@ module CtxParser
 
     module_function
 
+    # 严格时刻包含时区；拒绝 Time.iso8601 自动归一化的非法日期或时分秒。
+    def timestamp(raw)
+      unless raw.is_a?(String) && /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/.match?(raw)
+        raise ArgumentError, "Timestamp requires an explicit offset"
+      end
+      Date.iso8601(raw[0, 10])
+      if raw[11, 2].to_i >= 24 || raw[14, 2].to_i >= 60 || raw[17, 2].to_i >= 60 ||
+          (offset = /[+-](\d{2}):(\d{2})\z/.match(raw)) && (offset[1].to_i >= 24 || offset[2].to_i >= 60)
+        raise ArgumentError, "Invalid timestamp"
+      end
+      Time.iso8601(raw).getutc.freeze
+    end
+
     # 解析十进制整数，并校验声明的边界。
     def integer(raw, min: 0, max: nil)
       unless (min.nil? || min.is_a?(Integer)) && (max.nil? || max.is_a?(Integer)) && (min.nil? || max.nil? || min <= max)

data/lib/ctx_parser/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ctx_parser
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.4.0
 platform: ruby
 authors:
 - Gatework contributors
@@ -9,6 +9,34 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: date
+  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: time
+  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: digest
   requirement: !ruby/object:Gem::Requirement