ctx_parser 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1fa31bb20dcff8d61e0855e926e92be68473aa7b3bc33fea86e95bfd08caaac8
+  data.tar.gz: 02d5738230c47a01921c8e2f530bfe4acc740f607f46fe3677c355092cd3e068
+SHA512:
+  metadata.gz: af7037925fd0ecdaccb72464cdcab399daeb35e3939e51e72b7a53fedd3f55f5962f390bac4a1558c0f704e2995c7fe526e4d1fd7c3411bed068fd34671a9b4b
+  data.tar.gz: 1a7fc7f989267dcde2c9f9d4b0f6e7abe59348ffbcca529ae73c0425043ec36fcbff70ebd14d8b92931bcb823d4a4970454d61c36d5f198539b61e5a551842cb

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+Changes to the public contract are recorded here. Versions follow Semantic Versioning.
+
+## 0.1.1 (2026-10-16)
+
+- Publish verified artifacts using either an environment API key or RubyGems Trusted Publishing.
+- The v0.1.0 tag did not reach RubyGems because credential setup failed.
+
+## 0.1.0 (2026-10-16, unpublished)
+
+### Added
+
+- Shared parser contracts, configuration provenance, immutable values, and platform registries.
+- Standalone RubyGems packaging under `ctx_parser` with the `ctx_parser` require path and `CtxParser` namespace.
+- English and Chinese documentation, an offline example, and standalone RSpec/RuboCop development tasks.
+- Linux/macOS CI, isolated package verification, and automatic RubyGems and GitHub Releases with identical artifacts.
+
+### Changed
+
+- Cross-module dependencies resolve through RubyGems/Bundler instead of relative sibling paths.
+- Motor persistence and application-specific adapters remain in the host application.

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Song Huang
+Copyright (c) 2026 Gatework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README-zh.md

@@ -0,0 +1,102 @@
+# ctx_parser
+
+[English](README.md) | [源码](https://github.com/gatework/ctx_parser) | [变更记录](CHANGELOG.md)
+
+面向网络 CLI 解析的纯 Ruby 公共组件，提供不可变结果、来源游标、配置树、命令目录及平台策略。厂商语法和设备会话由对应领域模块负责。
+
+## 能力
+
+- `Parser`、`ConfigurationParser` 定义文本输入及完整性边界。
+- `Cursor`、`Document`、`Capture` 保留来源位置和嵌套配置上下文。
+- `Profile`、`CommandCatalog`、`Registry` 声明平台/型号行为，同一回显可共享解析。
+- `Values`、`Records`、`Immutable` 统一值转换、身份检查与防御性复制。
+
+## 安装
+
+要求 **Ruby 4.0.6 或更新版本**。在应用的 `Gemfile` 中添加：
+
+```ruby
+gem "ctx_parser"
+```
+
+然后执行 `bundle install`；也可直接执行 `gem install ctx_parser`。Ruby 加载入口为 `ctx_parser`，公开命名空间为 `CtxParser`；gem 包名与 Ruby 命名空间分别维护。
+
+本模块不依赖其他 Gatework 领域 gem。 gemspec 的运行依赖不添加版本约束；应用应提交自己的 `Gemfile.lock`，保持部署可复现。使用本库不需要启动 Rails 或配置兄弟模块的本地路径。
+
+发布产物和校验值见 [GitHub Releases](https://github.com/gatework/ctx_parser/releases)，已发布版本以 [RubyGems](https://rubygems.org/gems/ctx_parser) 为准。
+
+## 离线示例
+
+在开发检出目录安装依赖后执行：
+
+```sh
+bundle exec ruby examples/offline.rb
+```
+
+示例使用合成数据，不访问网络。完整代码见 [examples/offline.rb](examples/offline.rb)：
+
+```ruby
+require "ctx_parser"
+
+# 示例仅实现小型语法；厂商语法应放入对应领域 gem。
+class ExampleStatusParser < CtxParser::Parser
+  private
+
+  # 保留未知行，并遵循调用方声明的传输完整性。
+  def parse_output(text, complete:)
+    records = []
+    issues = []
+    text.each_line.with_index(1) do |line, number|
+      next if line.strip.empty?
+
+      match = /\A([A-Za-z0-9\/]+) (up|down)\z/.match(line.strip)
+      if match
+        records << { name: match[1], state: match[2].to_sym }
+      else
+        issues << { code: :unrecognized_row, line: number }
+      end
+    end
+    status = complete && issues.empty? && !records.empty? ? :complete : :partial
+    CtxParser::Result.new(status: status, records: records, issues: issues)
+  end
+end
+
+result = ExampleStatusParser.parse("Eth1/1 up\nEth1/2 down\n", complete: true)
+puts "Parse status: #{result.status}"
+result.records.each { |row| puts "#{row[:name]}: #{row[:state]}" }
+```
+
+## 公开契约与限制
+
+`Parser.parse(text, complete: false)` 返回包含 `status`、`records`、`issues` 的 `Result`；多视图解析器可返回 `ResultSet`。状态为 `complete`、`partial`、`failed`、`unsupported`。子类实现 `parse_output`，配置子类通过 `analyze` 和 `capture` 保留来源。
+
+`complete: true` 只表示调用方确认输入完整接收，不证明所有语法都已理解。未知行、身份冲突及空表证据不足必须明确表达。结果不可变；来源游标有意保留输入原文，含秘密时不可写入日志。
+
+本 gem 不提供厂商命令目录、传输、持久化或健康策略。参数和注册表配置错误保持异常，由调用方在对应边界处理。
+
+详细厂商语义、历史验证记录和 Motor 专用集成说明保留在[架构参考](docs/architecture-zh.md)。其中宿主集成代码需要 Motor，不属于独立 gem API。适配层位于 [Motor 仓库](https://github.com/gatework/motor/tree/main/backend/lib) 的 `backend/lib/baseline`、`backend/lib/vxlan` 和 `backend/lib/wireless`。
+
+## 开发与测试
+
+```sh
+bundle install
+bundle exec rake
+bundle exec ruby examples/offline.rb
+bundle exec rake build
+```
+
+`bundle exec rake` 执行 RSpec、RuboCop 及离线示例。测试放在 `spec/`，沿用项目 RSpec 约定；样例采用合成或脱敏证据。新增解析格式时补充成功、不完整、不支持及非法输入回归。离线测试不代表所有设备版本均通过实机验证。
+
+使用声明的最低 Ruby 版本检查兼容性。方法用途统一使用简明中文注释；复杂实现还需说明业务规则、实现思路及关键分支。保持公开返回值与错误契约。真实回显和凭据不可进入示例、fixture、日志或发布包。
+
+## 发布
+
+本目录可独立维护为 [ctx_parser](https://github.com/gatework/ctx_parser) 仓库。更新 `VERSION` 和 `CHANGELOG.md`，运行上述验证与构建命令，检查包内文件，再创建 `vVERSION` 标签。
+
+CI 在 Linux、macOS 上执行测试、lint、示例、构建和隔离安装。`main` 的 CI 通过后推送 `vVERSION` 标签，工作流将已验证的 Linux 产物发布到 RubyGems 和 GitHub Release，附带 `SHA256SUMS` 并回读下载字节。GitHub `release` environment 可配置 `RUBYGEMS_API_KEY` secret；未配置时使用 RubyGems Trusted Publishing，绑定本仓库、`release.yml` 和 `release` environment。失败时重跑失败的发布 job，以复用原 CI 产物；同版本已存在时必须校验字节一致。详见[发布说明](docs/release.md)。
+
+先发布依赖模块。标签、构建成功或工作流文件都不等于已经发布，需单独确认 RubyGems 的实际结果。版本变化见 [CHANGELOG.md](CHANGELOG.md)。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。

data/README.md

@@ -0,0 +1,102 @@
+# ctx_parser
+
+[简体中文](README-zh.md) | [Source](https://github.com/gatework/ctx_parser) | [Changelog](CHANGELOG.md)
+
+Shared, pure Ruby building blocks for network CLI parsing. It provides immutable results, source cursors, configuration trees, command catalogs, and platform profiles without owning vendor syntax or device sessions.
+
+## Features
+
+- `Parser` and `ConfigurationParser` define explicit text and completeness boundaries.
+- `Cursor`, `Document`, and `Capture` preserve source positions and nested configuration context.
+- `Profile`, `CommandCatalog`, and `Registry` select declared platform/model behavior and share parsing across views.
+- `Values`, `Records`, and `Immutable` centralize conversion, identity checks, and defensive copies.
+
+## Installation
+
+Requires **Ruby 4.0.6 or newer**. Add this line to your application's `Gemfile`:
+
+```ruby
+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.
+
+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.
+
+## Offline example
+
+From a development checkout after installing dependencies:
+
+```sh
+bundle exec ruby examples/offline.rb
+```
+
+The example uses synthetic data and performs no network access:
+
+```ruby
+require "ctx_parser"
+
+# 示例仅实现小型语法；厂商语法应放入对应领域 gem。
+class ExampleStatusParser < CtxParser::Parser
+  private
+
+  # 保留未知行，并遵循调用方声明的传输完整性。
+  def parse_output(text, complete:)
+    records = []
+    issues = []
+    text.each_line.with_index(1) do |line, number|
+      next if line.strip.empty?
+
+      match = /\A([A-Za-z0-9\/]+) (up|down)\z/.match(line.strip)
+      if match
+        records << { name: match[1], state: match[2].to_sym }
+      else
+        issues << { code: :unrecognized_row, line: number }
+      end
+    end
+    status = complete && issues.empty? && !records.empty? ? :complete : :partial
+    CtxParser::Result.new(status: status, records: records, issues: issues)
+  end
+end
+
+result = ExampleStatusParser.parse("Eth1/1 up\nEth1/2 down\n", complete: true)
+puts "Parse status: #{result.status}"
+result.records.each { |row| puts "#{row[:name]}: #{row[:state]}" }
+```
+
+## Public contract and limits
+
+`Parser.parse(text, complete: false)` returns a `Result` with `status`, `records`, and `issues`; a multi-view parser can return `ResultSet`. 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. Results are immutable. Source cursors intentionally retain original input and must not be logged when it contains secrets.
+
+This gem supplies no vendor command catalog, transport, persistence, or health policy. Parser/registry argument errors remain exceptions for callers to handle at their own boundary.
+
+Detailed vendor behavior, historical validation notes, and Motor-only integration are preserved in [the architecture reference](docs/architecture-zh.md). Host integration examples in that reference require Motor; they are not standalone gem APIs. Motor adapters live under `backend/lib/baseline`, `backend/lib/vxlan`, and `backend/lib/wireless` in the [Motor repository](https://github.com/gatework/motor/tree/main/backend/lib).
+
+## Development and tests
+
+```sh
+bundle install
+bundle exec rake
+bundle exec ruby examples/offline.rb
+bundle exec rake build
+```
+
+`bundle exec rake` runs RSpec, RuboCop, and the offline examples. Tests live in `spec/`, following the existing project's RSpec convention; fixtures use synthetic or sanitized evidence. Add regression cases for successful, incomplete, unsupported, and malformed inputs when extending a parser. Offline tests do not certify all device versions or replace live integration checks.
+
+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.
+
+## 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`.
+
+CI runs tests, lint, examples, build, and an isolated installation on Linux and macOS. After CI passes on `main`, push `vVERSION` to run the release workflow. It publishes the tested Linux artifact to RubyGems and GitHub Releases, attaches `SHA256SUMS`, and verifies downloaded bytes. The GitHub `release` environment accepts a `RUBYGEMS_API_KEY` secret; without it, configure RubyGems Trusted Publishing for this repository, `release.yml`, and the `release` environment. Retry a failed publish job to reuse its CI artifact; an already published version must have identical bytes. See [release details](docs/release.md).
+
+Publish dependency gems first. A Git tag, a successful build, or a workflow file does not establish that the gem has reached RubyGems; confirm the registry result separately. See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/docs/architecture-zh.md

@@ -0,0 +1,273 @@
+> 本文保留模块从 Motor 提取前的领域设计、覆盖范围、限制与验证记录，供兼容迁移和故障分析使用。
+> 当前独立 gem 的安装、依赖、开发与发布入口以 [README-zh.md](../README-zh.md) 为准。
+> 涉及 `Motor::*`、`Sync`、`Baseline::Check`、数据库、Rails、Rake 运维任务及私有实机证据的内容均属于 Motor 宿主集成，不随 gem 提供；历史验证记录不代表当前用户设备已经验证。
+
+# 多厂商 CLI 解析基础
+
+`CtxParser` 是独立于 Rails 的纯 Ruby 抽象。输入是 CLI 回显，输出是结构化事实和诊断。具体语法归所属业务模块维护：当前接入 Cisco N9K 的 `vxlan/cisco_nxos`、H3C 无线控制器的 `wireless/h3c`，以及多厂商配置基线 `baseline`。
+
+## 对象职责
+
+| 对象 | 职责 |
+| --- | --- |
+| `Parser` | 统一 `.parse(text, complete: false)` 接口和参数校验；具体策略实现 `parse_output` |
+| `ConfigurationParser` | 共用配置节点状态标记、来源捕获和嵌套路径管理；配置语法由具体策略处理 |
+| `Cursor` | 保存原文，顺序读取、窥视、回退，独立记录访问状态和逐行解析状态 |
+| `Line` | 不可变的源行，保留原始文本；构造时计算并缓存缩进和匹配文本 |
+| `Block` | 配置树节点，保存父子层次、源行范围和完整配置块原文 |
+| `Capture` | 已提取数据的不可变快照，将结果路径关联到来源配置块 |
+| `Document` | 把通用块树与可覆写的逐行分类策略组合；设备平台声明自身边界 |
+| `Input` | 按调用方选择编码、换行、NUL 和最大字节数规则 |
+| `Values` | 严格转换十进制整数、MAC、主机地址和 IPv4 前缀；范围由解析器传入 |
+| `Records` | 按调用方的身份键分析重复项，提供首条保留与无歧义投影 |
+| `Immutable` | 复制并冻结纯数据，与调用方的可变对象隔离 |
+| `Result` | 单个清单的 `status / records / issues` |
+| `ResultSet` | 同一回显产生的多个清单，各自保留 `Result` 和完整性 |
+| `CommandCatalog` | 一次声明命令、解析器与结果维度，校验并生成不可变索引 |
+| `Profile` | 组合命令与解析器，按型号覆盖策略，共享命令只解析一次 |
+| `Registry` | 由业务模块声明支持的平台和别名，选择对应 `Profile` |
+
+公共库不导入具体厂商，也不维护任何命令正则、设备会话或数据库投影。业务模块按职责复用公共抽象；VXLAN、Wireless 使用命令注册表，Baseline 直接从配置文本进入 `ConfigurationParser`。
+
+`Profile#queries(names)` 生成冻结的命令到维度计划，保留选择顺序并合并共享命令，支持同一维度的多条脚本。
+Result 的记录和诊断是防御性复制后的不可变数据；通过 `with(...)` 替换，不能原地修改。
+具体兼容边界见 [模块架构](https://github.com/gatework/motor/blob/main/backend/vendor/ARCHITECTURE.md)。
+
+```text
+vendor/
+  ctx_parser/lib/ctx_parser/
+    parser.rb
+    cursor.rb
+    line.rb
+    block.rb
+    capture.rb
+    document.rb
+    configuration_parser.rb
+    input.rb
+    values.rb
+    records.rb
+    immutable.rb
+    result.rb
+    result_set.rb
+    command_catalog.rb
+    profile.rb
+    registry.rb
+  vxlan/lib/vxlan/
+    parser_registry.rb
+    cisco_nxos/
+      profile.rb
+      parser.rb
+      configuration.rb                    # 特性、模板与网段事实归约
+      evpn_l2route.rb
+      parsers/show_*.rb                    # 12 条 NX-OS 命令
+  wireless/lib/wireless/
+    parser_registry.rb
+    fields.rb                           # 无线领域共用的值转换
+    h3c/
+      profile.rb
+      parser.rb
+      command_output.rb                   # 配置与运行命令共用输入边界
+      configuration.rb                    # 实体身份、归属与认证类型
+      verbose_parser.rb
+      session_parser.rb
+      authentication_parser.rb
+      parsers/display_*.rb                 # 8 条 H3C 命令
+  baseline/lib/baseline/
+    document.rb                           # Baseline 自身的 banner 和提示行分类
+    facts.rb                              # 跨命令的事实归约，不依赖解析游标
+    parsers/*.rb                          # 各平台的管理基线规则
+```
+
+```mermaid
+classDiagram
+    CtxParser <|-- NxosParser
+    CtxParser <|-- H3cParser
+    NxosParser <|-- ShowIpOspfNeighbors
+    H3cParser <|-- DisplayCurrentConfiguration
+    H3cParser <|-- VerboseParser
+    VerboseParser <|-- DisplayWlanApAllVerbose
+    VerboseParser <|-- SessionParser
+    CtxParserProfile <|-- NxosProfile
+    CtxParserProfile <|-- H3cProfile
+    Registry --> CtxParserProfile : selects
+    CtxParserProfile --> CtxParser : composes
+    CtxParser --> Result : returns
+    CtxParser <|-- ConfigurationParser
+    CtxParser --> Cursor : owns per parse
+    Cursor --> Line : reads and tracks
+    Cursor --> Capture : records
+    Capture --> Block : source
+    Block --> Block : children
+    Document --> Cursor : owns
+    Document --> Block : builds
+    BaselineDocument --|> Document : line classification
+    BaselineParser --|> ConfigurationParser : analyze and capture
+    BaselineParser --> BaselineFacts : normalized observations
+    ShowRunningConfig --|> ConfigurationParser
+    DisplayCurrentConfiguration --|> ConfigurationParser
+    ConfigurationParser --> Capture : records scopes
+    DisplayWlanApAllVerbose --> ResultSet : returns AP and radio results
+    ResultSet --> Result : contains
+```
+
+## 调用
+
+安装对应 gem 后，Ruby 脚本可以直接 require 对应命令文件；模块间依赖由 RubyGems/Bundler 解析，模块内部继续使用 `require_relative`。
+
+```ruby
+require "vxlan/cisco_nxos/parsers/show_ip_ospf_neighbors"
+
+result = Vxlan::CiscoNxos::Parsers::ShowIpOspfNeighbors.parse(cli_output, complete: true)
+result.status
+result.records
+result.issues
+```
+
+按实际设备平台和型号选择策略：
+
+```ruby
+require "vxlan/parser_registry"
+require "wireless/parser_registry"
+
+nxos = Vxlan::ParserRegistry.fetch(:cisco_nxos, model: "N9K-C93180YC-FX")
+result = nxos.parse(:ospf_neighbors, ospf_output, complete: true)
+
+h3c = Wireless::ParserRegistry.fetch(:h3c_wireless, model: controller_model)
+results = h3c.parse_many(%i[access_points radios], ap_output, complete: true)
+results.fetch(:access_points).records
+results.fetch(:radios).records
+
+# 直接调用共享命令时，返回 ResultSet。
+parsed = Wireless::H3c::Parsers::DisplayWlanApAllVerbose.parse(ap_output, complete: true)
+parsed.fetch(:access_points).complete?
+parsed.fetch(:radios).issues
+```
+
+`h3c_wireless` 是 `h3c` 的显式别名。未知平台或维度抛出 `ArgumentError`；一份回显不能通过 `parse_many` 解释为多条不同命令。
+
+共享回显的视图逐个投影：缺失视图返回 `failed / missing_parser_view`，投影异常返回
+`failed / parser_projection_failed`，非 `Result` 返回值标记 `invalid_parser_result`；其他有效视图保留。
+命令选择、输入校验和解析器执行本身的异常仍沿原调用契约抛出，由领域采集器在该命令边界隔离。
+公共解析层不执行网络操作；三个领域共用的命令执行边界见 [`ctx_driver`](https://github.com/gatework/ctx_driver)。
+
+`complete` 默认 `false`，仅在调用方确认完整接收时传 `true`。它不保证解析结果完整：未知行、计数矛盾、身份冲突或空表证据不足仍会降低状态。NX-OS 和 H3C 保留各自的编码、空表、去重和失败策略，例如 NX-OS 剔除所有冲突身份，H3C 保留首条并标记不完整。具体策略不会把未知回显当作完整空清单。
+
+业务适配器将结果转换成原有 `Vxlan::Observation`、`Wireless::Observation`，补充维度和采集证据。LLDP 解析器只提取回显中的端点，AP 名称由无线适配器补入。配置中的秘密只保留必要的存在标记。
+
+## 有状态的配置分析
+
+配置策略使用同一个游标和配置块模型。`Cursor` 不包含厂商命令；`Block.read` 使用游标逐行建立缩进树，厂商策略声明注释和显式边界，再解释每个节点。块树构建与领域外子树的忽略使用显式栈，避免深层缩进耗尽 Ruby 调用栈。Cisco N9K 使用缩进及 `end`，H3C 使用缩进及 `#`、`return`。完整块包含未知子语句、空行和注释，保留 LF、CRLF、CR 和末行没有换行的原貌；显式结束行独立保留在游标中，不包含在前一个块内。
+
+`Line#text` 返回缓存的冻结字符串，`Line#indent` 返回缓存的缩进宽度；`raw` 和 `Data` 成员仍为 `index / raw`。需要编辑匹配文本时先 `dup`，不要修改源行。缓存只属于当前文档，不跨解析调用共享。
+
+需要追踪来源时，保留解析器实例：
+
+```ruby
+profile = Vxlan::ParserRegistry.fetch(:cisco_nxos, model: "N9K-C93180YC-FX")
+parser = profile.parser_for(:configuration).new
+result = parser.parse(cli_output, complete: true)
+
+cursor = parser.cursor
+cursor.position                 # 下一行的零基索引；构建块树后位于 EOF
+cursor.state(0)                  # :parsed / :ignored / :unsupported / :invalid / :pending
+cursor.visited?(0)               # 读过不代表解析成功
+cursor.unparsed_content         # 未处理、未知或无效行的原文
+parser.blocks                   # 根配置块；children 可查看嵌套上下文
+
+capture = cursor.captures_for([:interfaces, "Vlan110"]).first
+capture.data                    # 此块处理完成时的结构化数据快照
+capture.line_range              # 面向用户的一基行号范围
+capture.content                 # 此接口的完整原始配置，包括尚未识别的子命令
+capture.complete?               # 块内每行均已解析或明确忽略；不表示传输完整
+```
+
+捕获路径相对于 `result.records.first`，可用 `result.records.first.dig(*capture.path)` 对照最终结果。H3C 的组、AP、模板、型号和 Radio 块也保留来源，例如 `[:service_templates, 0]`。同一结果可有多个来源；捕获按源文档顺序返回，各自保存处理该块时的数据，后面的配置覆盖值不会改写前面的快照。重复或冲突的配置保留原文及无效状态，捕获信息用于追踪解析过程，最终可用数据仍以 `Result` 为准。
+
+同一次事实归约关联多条来源时，使用 `cursor.capture_many(blocks, data:, path:)`。
+该调用先校验所有来源属于当前游标，再复制并深度冻结一份值与路径供各 Capture 引用；返回冻结的 Capture 数组。
+调用方数据不会被修改或冻结，下一次捕获仍产生独立快照。`captures_for(path)` 使用不可变路径索引并缓存排序结果，
+新增捕获或 `reset!` 会使对应缓存失效；`complete?` 仍实时读取行状态，不因来源查询缓存而过时。
+
+游标也可独立用于新策略：
+
+```ruby
+cursor = CtxParser::Cursor.new(cli_output)
+line = cursor.peek              # 不前进、不标记访问
+line = cursor.read              # 前进并标记访问，语义状态仍为 :pending
+cursor.mark(line.index, state: :parsed) # 仅在成功解释后标记
+cursor.step_back                # 只回退位置
+cursor.unread                   # 回退并把对应行恢复为 :pending
+cursor.defer                    # 当前上一行恢复待解析，位置不变
+cursor.rewind                   # 回到开头，保留访问、解析状态和捕获
+cursor.reset!                   # 清空全部分析状态和捕获，重新开始
+```
+
+`read_pending` 从当前位置查找下一条 `:pending` 行，也不会自动标成成功。空行和注释由块构建器标为 `:ignored`；领域外配置由具体策略明确忽略，未知相关语句标为 `:unsupported`，无效值标为 `:invalid`。读取原文、解释语法和保存结构化结果因此各有明确职责。
+
+每次 `parse` 都重新建立游标和块树，包括失败调用；前一次保留的游标不会被下一次调用改写。单个解析器实例供一次顺序分析使用，并发调用应各用一个实例，`Profile` 已按此方式创建策略。
+
+原始配置可能含密钥。原文只通过 `cursor.content`、`line.raw`、`block.content`、`capture.content` 显式读取；这些对象及解析器的 `inspect`、`as_json` 仅输出元数据。`Capture#data` 是脱离可变结果的冻结快照。`Result#to_h` 仍只有 `status / records / issues`，现有采集与库存序列化不携带游标或原文。
+
+## 多业务共用的纯能力
+
+VXLAN、Wireless 和 Baseline 使用同一套输入与结构能力；各模块继续维护自己的 Profile、设备语法和业务结果规则。
+
+```ruby
+CtxParser::Input.text(raw, encoding: :utf8, newlines: :lf)
+CtxParser::Values.integer("4094", min: 1, max: 4094)
+CtxParser::Values.mac("aabb.ccdd.eeff") # => "aa:bb:cc:dd:ee:ff"
+
+rows = CtxParser::Records.new(records, identity: [ :name ])
+rows.first_occurrences
+rows.unambiguous
+rows.duplicate_identity_count
+
+snapshot = CtxParser::Immutable.copy({ "facts" => [ "ssh" ] })
+```
+
+`Wireless::Fields` 继续提供无线领域的兼容入口和单位转换；通用输入边界、数字、MAC、IP 与去重委托给 `ctx_parser`。`Records` 分析身份，但不决定如何处置重复行：无线保留首条并诊断，NX-OS 剔除同身份的所有记录。Baseline 共用 `Document` 块树与不可变数据复制，banner、无效回显标记和事实规则仍由 Baseline 定义。
+
+## 新厂商、型号和格式
+
+新增厂商时，在所属业务模块下建立平台目录、具体命令类和 `Profile`，加入该模块的 `ParserRegistry`。无需修改公共库或其他厂商的解析代码。
+
+每个平台通过普通 Ruby 数据声明一份 `CATALOG`，命令字符串只出现一次。相同回显的多个视图放在同一条声明中：
+
+```ruby
+CATALOG = CtxParser::CommandCatalog.new([
+  { dimensions: %i[access_points radios], command: "display wlan ap all verbose",
+    parser: Parsers::DisplayWlanApAllVerbose },
+  { dimensions: [ :clients ], command: "display wlan client verbose",
+    parser: Parsers::DisplayWlanClientVerbose }
+])
+COMMANDS = CATALOG.commands
+PARSERS = CATALOG.parsers
+```
+
+`CommandCatalog` 在构造时拒绝空声明、重复命令或维度、含控制字符的命令，以及非 `Parser` 子类。目录复制并冻结声明数据，不冻结解析器类或调用方的原始数组。由此派生的 `COMMANDS`（维度到命令）和 `PARSERS`（命令到策略）保持原有查询接口；已有自定义 Profile 仍可使用这两个映射。
+
+具有共同语法的命令可复用平台基类；特有字段、表头、身份与总数规则留在对应命令中。会话、命令执行和证据持久化由采集器负责；`CommandCatalog` 不执行 I/O，也不引入动态类名查找或自动注册。
+
+型号差异用平台 `Profile::MODEL_PARSERS` 声明，形状为 `{ "规范化型号" => { "命令文本" => 专用解析器类 } }`。型号键使用去除首尾空格的小写完整型号，按精确名称匹配；专用解析器可继承已有命令类，仅覆盖有差异的方法。Profile 初始化时校验并复制所选型号的覆盖表：只允许覆盖已声明命令，策略必须继承 `Parser`；修改原表不会改变已创建的 Profile。未覆盖命令和无专用策略的型号使用该平台的公共格式，未知语法仍会产生不完整结果。采集器传入现有 `Motor::Device#model`，AP LLDP 使用 AP 自身型号。
+
+当前 N9K 和 H3C 无线控制器使用仓库已有回显样本的格式。新增型号或固件差异规则，需要脱敏样本及完整、截断、未知字段回归。型号覆盖机制已用测试策略验证，生产映射中没有虚构的型号或固件规则。
+
+## 验证
+
+```sh
+RAILS_ENV=test bundle exec rspec spec/vendor/ctx_parser spec/vendor/vxlan spec/vendor/wireless spec/vendor/baseline
+RAILS_ENV=test bundle exec rails zeitwerk:check
+bundle exec rubocop vendor/ctx_parser vendor/vxlan vendor/wireless vendor/baseline
+```
+
+测试包含无 Rails 的独立加载、型号选择、共享回显解析、输入完整性、旧接口兼容、替身会话和测试数据库投影。真实设备联调另行验证。
+
+纯 Ruby 性能样本覆盖 10,000 个合成接口块（20,001 行）、1,000 条同事实来源及1,000个路径查询。
+分别报告耗时和分配对象数，每次验证事实输出、来源顺序及值快照。构造输入不计入耗时；
+比较不同实现时使用相同 Ruby、脚本与空闲环境，通过 `-I` 选择对应版本的 `baseline/lib`：
+
+```sh
+bundle exec ruby -I vendor/baseline/lib vendor/ctx_parser/benchmark/configuration.rb
+```
+
+该样本用于观察公共配置树与行匹配的成本，不代表设备采集、数据库同步或真实网络吞吐。

data/docs/release.md

@@ -0,0 +1,13 @@
+# Release
+
+1. Update `lib/ctx_parser/version.rb` and `CHANGELOG.md`; run `bundle exec rake` and `bundle exec rake build`.
+2. Run `ruby script/verify_package.rb pkg/ctx_parser-VERSION.gem`. This installs and loads the built gem outside Bundler and the checkout.
+3. Commit and push `main`; wait for both Linux and macOS CI jobs.
+4. Push the matching `vVERSION` tag. The Release workflow repeats CI, then publishes its exact Linux artifact to RubyGems and GitHub with `SHA256SUMS`.
+5. Verify the workflow, registry version, tag commit, and downloaded checksums. A local build is not publication evidence.
+
+Configure `RUBYGEMS_API_KEY` as an encrypted secret in the GitHub `release` environment, with noninteractive gem-push permission. Alternatively configure [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) for `gatework/ctx_parser`, `release.yml`, environment `release`, and omit that secret. Never commit credentials.
+
+A failed publish is not permission to overwrite an existing version. Rerun the failed publish job to retain the original CI artifact. The script verifies an existing RubyGems version before proceeding and rejects different bytes or yanked versions. `workflow_dispatch` is restricted to version tags by the publish validation.
+
+Raw device `*.log`, local secrets, and build outputs are ignored. Package files use an explicit gemspec allowlist; review both the Git index and gem contents before publishing. Tests and examples must use synthetic or sanitized evidence.

data/examples/offline.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "ctx_parser"
+
+# 示例仅实现小型语法；厂商语法应放入对应领域 gem。
+class ExampleStatusParser < CtxParser::Parser
+  private
+
+  # 保留未知行，并遵循调用方声明的传输完整性。
+  def parse_output(text, complete:)
+    records = []
+    issues = []
+    text.each_line.with_index(1) do |line, number|
+      next if line.strip.empty?
+
+      match = /\A([A-Za-z0-9\/]+) (up|down)\z/.match(line.strip)
+      if match
+        records << { name: match[1], state: match[2].to_sym }
+      else
+        issues << { code: :unrecognized_row, line: number }
+      end
+    end
+    status = complete && issues.empty? && !records.empty? ? :complete : :partial
+    CtxParser::Result.new(status: status, records: records, issues: issues)
+  end
+end
+
+result = ExampleStatusParser.parse("Eth1/1 up\nEth1/2 down\n", complete: true)
+puts "Parse status: #{result.status}"
+result.records.each { |row| puts "#{row[:name]}: #{row[:state]}" }

data/lib/ctx_parser/banner.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CtxParser
+  # 消费带分隔符的 CLI 横幅，不将其正文解释为配置。
+  class Banner
+    # 跟踪横幅分隔符，避免内嵌文本被当作配置。
+    def consume(text)
+      if @delimiter
+        @delimiter = nil if text.include?(@delimiter)
+        return true
+      end
+      match = /\A(?:banner\s+\S+|header\s+\S+(?:\s+information)?)\s+(.+)\z/.match(text)
+      return false unless match
+
+      delimiter = match[1].start_with?("^") ? match[1][0, 2] : match[1][0]
+      @delimiter = delimiter unless match[1].delete_prefix(delimiter).include?(delimiter)
+      true
+    end
+
+    # 判断横幅是否仍缺少闭合分隔符。
+    def open? = !@delimiter.nil?
+  end
+end