vxlan 0.4.0 → 0.4.2

data/lib/vxlan/cli/review.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
-require "optparse"
-require "json"
-require "digest"
+require "ctx_cli/command"
+require "ctx_cli/review"
+require "yaml"
+require "ipaddr"
+require "ctx_runner/evidence"
 require_relative "report"
 
 module Vxlan
@@ -16,87 +18,54 @@ module Vxlan
 
       # 返回零只代表建议生成完成，不代表问题已修复或候选配置已获批准。
       def run(argv)
-        options = {}
-        parser = OptionParser.new do |p|
-          p.banner = "用法：vxlan review --batch DIR [--output DIR]（离线生成建议，不执行配置）"
+        command = CtxCli::Command.new(banner: "用法：vxlan review --batch DIR [--output DIR]（离线生成建议，不执行配置）", out: @out) do |p, options|
           p.on("--fabric-policy FILE", "显式 Fabric/Leaf/Border/Spine 清单 YAML") { |value| options[:fabric_policy] = value }
           p.on("--batch DIR", "已采集批次，含 evidence/*.json") { |value| options[:batch] = value }
           p.on("--[no-]scripts", "可选导出配置建议，默认仅诊断") { |value| options[:scripts] = value }
           p.on("--output DIR", "私有输出根目录，默认批次内 reviews") { |value| options[:output] = value }
           p.on("-h", "--help", "查看帮助") { options[:help] = true }
         end
-        rest = parser.parse(argv.dup)
-        return @out.puts(parser) || 0 if options[:help]
-        raise ArgumentError, "需要批次目录" unless rest.empty? && options[:batch]
-        batch = File.expand_path(options[:batch])
-        paths = Dir[File.join(batch, "evidence", "*.json")].sort
-        raise ArgumentError, "无设备报告" if paths.empty?
-        # 先校验所有输入，损坏文件不会留下看似完成的部分建议批次。
-        documents = paths.map do |path|
-          body = File.read(path)
-          document = JSON.parse(body)
-          validate(document)
-          [ path, body, document, Recommendations.new(document).call ]
+        CtxCli::Review.new(command: command, directory: "evidence", adapter: self, out: @out, error: @error).run(argv)
+      end
+
+      # 领域结构、建议和身份冲突必须在创建输出目录前全部校验。
+      def prepare(documents, options)
+        documents.each do |entry|
+          validate(entry[2])
+          entry << Recommendations.new(entry[2]).call
         end
         hosts = documents.map { |entry| entry[2]["device"]["host"] }
         names = documents.map { |entry| CLI::Report.device_basename(entry[2].fetch("device")) }
         raise ArgumentError, "设备身份或输出名称重复" unless hosts.uniq == hosts && names.uniq == names
-        policy = options[:fabric_policy] && YAML.safe_load(File.read(options[:fabric_policy]), aliases: false)
+        policy = options[:fabric_policy] && YAML.safe_load(CtxCli::Input.read(path: options[:fabric_policy]), aliases: false)
         Vxlan::Fabric::Scope.new(policy) if policy
+        policy
+      end
+
+      # 公共入口完成预检后才调用发布；领域报告格式保持独立。
+      def publish(documents, options, batch:, context:)
         report = CLI::Report.new(options[:output] || File.join(batch, "reviews"), scripts: options[:scripts] == true)
-        report.build_review(documents, policy: policy)
-        @out.puts "建议已生成：#{report.directory}/summary.txt；#{documents.size} 台；未执行设备变更。"
-        0
-      rescue Psych::Exception, OptionParser::ParseError, ArgumentError, TypeError, KeyError, JSON::ParserError, SystemCallError, IOError => error
-        @error.puts "建议生成失败（#{error.class.name}）；请检查输入结构、目录权限和 --help；未执行设备变更。"
-        2
+        report.build_review(documents, policy: context)
+        "建议已生成：#{report.directory}/summary.txt；#{documents.size} 台；未执行设备变更。"
       end
 
       private
 
-      # 仅接受宿主保存的设备快照边界；缺少快照的失败采集仍可生成补采任务。
+      # 先校验公共证据外壳，再验证领域记录。
       def validate(document)
-        raise ArgumentError, "无设备身份" unless document.is_a?(Hash) && document["device"].is_a?(Hash) && %w[name host].all? { |key| document["device"][key].is_a?(String) }
-        host = document["device"]["host"]
-        raise ArgumentError, "目标地址须为规范主机地址" unless !host.include?("/") && IPAddr.new(host).to_s == host
-        snapshot = document["snapshot"]
-        raise ArgumentError, "无快照字段" unless document.key?("snapshot")
-        return if snapshot.nil?
-        raise ArgumentError, "快照结构错误" unless snapshot.is_a?(Hash) && snapshot["dimensions"].is_a?(Hash)
-        if snapshot.key?("target") && (!snapshot["target"].is_a?(Hash) || snapshot["target"]["host"] != host)
-          raise ArgumentError, "设备身份与采集目标不一致"
-        end
-        snapshot["dimensions"].each do |dimension, observation|
-          unless observation.is_a?(Hash) && %w[complete partial failed unsupported not_requested].include?(observation["status"]) && observation["records"].is_a?(Array) && observation["records"].all? { |record| record.is_a?(Hash) }
-            raise ArgumentError, "观测结构错误"
-          end
-          array_of_hashes(observation.fetch("issues", []))
-          observation["records"].each { |record| validate_record(record, dimension) }
-        end
-      end
-
-      # 校验规则读取的容器类型，错误消息不包含配置正文。
-      def array_of_hashes(value)
-        raise ArgumentError, "列表结构错误" unless value.is_a?(Array) && value.all? { |entry| entry.is_a?(Hash) }
-        value
-      end
-
-      # 映射值必须仍是记录，不能将损坏结构解释成空事实。
-      def hash_of_hashes(value)
-        raise ArgumentError, "映射结构错误" unless value.is_a?(Hash) && value.values.all? { |entry| entry.is_a?(Hash) }
-        value
+        CtxRunner::Evidence.validate(document) { |record, dimension| validate_record(record, dimension) }
       end
 
       # 在输出目录创建前验证所有会参与建议生成的嵌套字段。
       def validate_record(record, dimension)
         return unless dimension == "configuration"
-        array_of_hashes(record.fetch("review_findings", []))
+        CtxRunner::Evidence.array(record.fetch("review_findings", []))
         nve = record.fetch("nve", {})
         raise ArgumentError, "NVE/VLAN 结构错误" unless nve.is_a?(Hash) && record.fetch("vlan_vnis", {}).is_a?(Hash)
-        hash_of_hashes(nve.fetch("members", {}))
-        hash_of_hashes(record.fetch("vrfs", {}))
-        hash_of_hashes(record.fetch("evpn", {})).each_value { |entry| array_of_hashes(entry.fetch("route_targets", [])) }
-        hash_of_hashes(record.fetch("interfaces", {})).each_value do |interface|
+        CtxRunner::Evidence.map(nve.fetch("members", {}))
+        CtxRunner::Evidence.map(record.fetch("vrfs", {}))
+        CtxRunner::Evidence.map(record.fetch("evpn", {})).each_value { |entry| CtxRunner::Evidence.array(entry.fetch("route_targets", [])) }
+        CtxRunner::Evidence.map(record.fetch("interfaces", {})).each_value do |interface|
           addresses, bindings = interface.fetch("addresses", []), interface.fetch("acl_bindings", {})
           unless addresses.is_a?(Array) && addresses.all? { |address| address.is_a?(String) && address.include?("/") } && bindings.is_a?(Hash) && bindings.all? { |direction, name| %w[in out].include?(direction) && name.is_a?(String) }
             raise ArgumentError, "接口结构错误"
@@ -106,7 +75,7 @@ module Vxlan
         acls = record.fetch("acls", {})
         raise ArgumentError, "ACL 结构错误" unless acls.is_a?(Hash)
         acls.each_value do |entries|
-          array_of_hashes(entries).each do |entry|
+          CtxRunner::Evidence.array(entries).each do |entry|
             unless entry["sequence"].is_a?(Integer) && %w[permit deny remark].include?(entry["action"]) && entry["expression"].is_a?(String)
               raise ArgumentError, "ACL 规则结构错误"
             end

data/lib/vxlan/cli.rb

@@ -1,46 +1,42 @@
 # frozen_string_literal: true
 
 require "vxlan/version"
+require "ctx_cli/router"
 
 module Vxlan
   # 命令入口按需加载采集或解析实现；核心库无需加载 CLI。
   module CLI
     # 由调用方拥有退出行为，库入口只返回退出码。
     def self.run(argv, env: ENV, out: $stdout, error: $stderr, input: $stdin, **collect_options)
-      arguments = argv.dup
-      command = arguments.shift
-      case command
-      when nil, "--help", "--help-all", "-h"
-        return usage(out) if arguments.empty?
-      when "--version", "-v"
-        return out.puts(Vxlan::VERSION) || 0 if arguments.empty?
-      when "collect"
-        begin
-          require_relative "cli/collect"
-        rescue LoadError
-          error.puts "collect 需要含共享清单筛选的当前 net-connector；请安装项目依赖。"
-          return 2
+      commands = {
+        "collect" => ->(arguments) do
+          begin
+            require_relative "cli/collect"
+          rescue LoadError
+            error.puts "collect 需要含共享清单筛选的当前 net-connector；请安装项目依赖。"
+            next 2
+          end
+          Collect.new(env: env, out: out, error: error, input: input, **collect_options).run(arguments)
+        end,
+        "apply" => ->(arguments) do
+          require_relative "cli/apply"
+          Apply.new(env: env, out: out, error: error, input: input, connector_factory: collect_options[:connector_factory], discovery: collect_options.fetch(:discovery, {})).run(arguments)
+        end,
+        "review" => ->(arguments) do
+          require_relative "cli/review"
+          Review.new(out: out, error: error).run(arguments)
+        end,
+        "parse" => ->(arguments) do
+          require_relative "cli/parse"
+          Parse.new(out: out, error: error, input: input, command: collect_options.fetch(:command, "vxlan parse")).run(arguments)
         end
-        return Collect.new(env: env, out: out, error: error, input: input, **collect_options).run(arguments)
-      when "apply"
-        require_relative "cli/apply"
-        return Apply.new(env: env, out: out, error: error, input: input, connector_factory: collect_options[:connector_factory], discovery: collect_options.fetch(:discovery, {})).run(arguments)
-      when "review"
-        require_relative "cli/review"
-        return Review.new(out: out, error: error).run(arguments)
-      when "parse"
-        require_relative "cli/parse"
-        return Parse.new(out: out, error: error, input: input, command: collect_options.fetch(:command, "vxlan parse")).run(arguments)
-      end
-      error.puts "未知命令或多余参数；使用 vxlan --help 查看用法"
-      2
+      }
+      CtxCli::Router.new(name: "vxlan", version: Vxlan::VERSION, usage: USAGE,
+        commands: commands, out: out, error: error).run(argv)
     end
 
     # 全局帮助不读取配置、环境文件或设备清单。
-    def self.usage(out)
-      out.puts "用法：vxlan collect [选项]  只读采集与报告\n      vxlan parse [选项]    离线文件或 stdin 解析\n      vxlan review --batch DIR  离线修复建议\n      vxlan apply --plan FILE --item ID  交互确认后下发\n      vxlan --version\n使用 vxlan collect --help 、vxlan parse --help 或 vxlan review --help 查看参数；--help-all 查看完整约定，--examples 查看范例。"
-      0
-    end
-    private_class_method :usage
+    USAGE = "用法：vxlan collect [选项]  只读采集与报告\n      vxlan parse [选项]    离线文件或 stdin 解析\n      vxlan review --batch DIR  离线修复建议\n      vxlan apply --plan FILE --item ID  交互确认后下发\n      vxlan --version\n使用 vxlan collect --help 、vxlan parse --help 或 vxlan review --help 查看参数；--help-all 查看完整约定，--examples 查看范例。".freeze
+    private_constant :USAGE
   end
 end

data/lib/vxlan/collection_plan.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "observation"
+require "ctx_parser/result"
 
 module Vxlan
   # 配置证据约束运行查询：明确未启用的功能才允许空回显或省略查询。

data/lib/vxlan/fabric/review.rb

@@ -192,7 +192,7 @@ module Vxlan
           name = row[:svi]&.dig("acl_bindings", direction)
           entries = name && row[:config].fetch("acls", {})[name]
           policy = policies.dig(row[:host], name)
-          { acl: name, defined: !entries.nil?, entries: entries, policy_verified: !policy.nil?, address_groups: policy&.address_groups, digest: policy && ChangePlan.fingerprint(policy.to_h) }
+          { acl: name, defined: !entries.nil?, entries: entries, policy_verified: !policy.nil?, address_groups: policy&.address_groups, digest: policy && CtxRunner::Fingerprint.call(policy.to_h) }
         end
         code = different_binding ? "fabric_acl_binding" : "fabric_acl_content"
         finding(fabric, vni, code, "#{direction} 方向 ACL 挂载/有序规则不一致", evidence)

data/lib/vxlan/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vxlan
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Gatework contributors
@@ -9,20 +9,34 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ctx_cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: ctx_runner
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: ctx_parser
   requirement: !ruby/object:Gem::Requirement
@@ -193,9 +207,11 @@ files:
 - docs/superpowers/plans/2026-10-19-evidence-contracts.md
 - docs/superpowers/plans/2026-10-19-vxlan-examples.md
 - docs/superpowers/plans/2026-10-20-fabric-consistency.md
+- docs/superpowers/plans/2026-10-22-ctx-cli.md
 - docs/superpowers/specs/2026-10-19-command-line-design.md
 - docs/superpowers/specs/2026-10-19-connector-integration-design.md
 - docs/superpowers/specs/2026-10-19-evidence-contracts.md
+- docs/superpowers/specs/2026-10-22-ctx-cli-design.md
 - examples/README.md
 - examples/collect.rb
 - examples/offline.rb