create-yss-spec 2.1.5 → 2.1.6

package/template/scripts/verify-openapi-json-handoff-scenarios

@@ -1,270 +1,3 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "digest"
-require "json"
-require "tmpdir"
-require "yaml"
-
-# This validates the YAML-to-JSON handoff contract rather than invoking
-# Redocly or any frontend generator. These fixtures prove that a JSON
-# derivative preserves the frozen OpenAPI semantics and can be handed to an
-# implementation repository as unchanged bytes.
-module OpenapiJsonHandoff
-  module_function
-
-  def validate!(source_yaml:, source_json:, materialized_json:, handoff:, **_unused)
-    validate_source_paths!(handoff)
-    assert!(handoff.fetch("freeze_status") == "approved", "OpenAPI Freeze 未批准")
-    assert!(handoff.fetch("export_status") == "exported", "JSON 导出未完成")
-    assert!(!handoff.fetch("freeze_record").to_s.empty?, "缺少 OpenAPI Freeze 记录")
-    assert!(!handoff.fetch("export_record").to_s.empty?, "缺少 OpenAPI JSON 派生记录")
-
-    yaml_documents = YAML.load_stream(File.binread(source_yaml).force_encoding("UTF-8"))
-    assert!(yaml_documents.length == 1, "YAML 必须是单一 document")
-    assert!(yaml_documents.first.is_a?(Hash) && yaml_documents.first["openapi"] == "3.1.0", "YAML 必须是 OAS 3.1")
-
-    json_document = JSON.parse(File.binread(source_json))
-    assert!(json_document["openapi"] == "3.1.0", "JSON 必须是 OAS 3.1")
-    validate_operation_contract!(yaml_documents.first, json_document)
-    validate_json_refs!(json_document)
-    assert!(Digest::SHA256.file(source_yaml).hexdigest == handoff.fetch("yaml_sha256"), "YAML SHA-256 不匹配")
-    assert!(Digest::SHA256.file(source_json).hexdigest == handoff.fetch("json_sha256"), "JSON SHA-256 不匹配")
-    assert!(Digest::SHA256.file(materialized_json).hexdigest == handoff.fetch("json_sha256"), "前端物化 JSON 与导出记录不一致")
-
-    bundle_command = handoff.fetch("bundle_command")
-    %w[pnpm\ exec\ redocly\ bundle --ext\ json --component-renaming-conflicts-severity=error].each do |marker|
-      assert!(bundle_command.include?(marker), "bundle 命令缺少 #{marker}")
-    end
-    assert!(bundle_command.include?(handoff.fetch("source_yaml")), "bundle 命令未使用冻结 YAML")
-    assert!(bundle_command.include?(handoff.fetch("source_json")), "bundle 命令未写入记录的 JSON")
-    assert!(!bundle_command.match?(/(?:\bmvn\b|smart[ _-]?doc)/i), "bundle 命令包含已移除的 Maven OpenAPI 链路")
-
-  end
-
-  def validate_operation_contract!(yaml_document, json_document)
-    yaml_operations = operation_contracts(yaml_document)
-    json_operations = operation_contracts(json_document)
-    assert!(!yaml_operations.empty?, "YAML 缺少可生成客户端的操作")
-    assert!(yaml_operations == json_operations, "JSON 未保留 YAML 的路径、方法、operationId、请求或响应契约")
-    ids = yaml_operations.values.map { |contract| contract.fetch("operationId") }
-    assert!(ids.all? { |operation_id| operation_id.is_a?(String) && !operation_id.empty? }, "operationId 必须为非空字符串")
-    assert!(ids.uniq.length == ids.length, "operationId 必须唯一")
-  end
-
-  def operation_contracts(document)
-    methods = %w[get put post delete options head patch trace]
-    paths = document.fetch("paths", {})
-    paths.each_with_object({}) do |(path, path_item), operations|
-      next unless path_item.is_a?(Hash)
-
-      path_item.each do |method, operation|
-        next unless methods.include?(method.to_s.downcase) && operation.is_a?(Hash)
-
-        operations["#{method.to_s.upcase} #{path}"] = {
-          "operationId" => operation["operationId"],
-          "parameters" => operation.fetch("parameters", []),
-          "requestBody" => operation["requestBody"],
-          "responses" => operation.fetch("responses", {})
-        }
-      end
-    end
-  end
-
-  def validate_json_refs!(document)
-    refs = []
-    collect_refs(document, refs)
-    refs.each do |ref|
-      assert!(ref.start_with?("#/"), "JSON 不得包含外部或远程 $ref: #{ref}")
-      resolve_json_pointer!(document, ref)
-    end
-  end
-
-  def collect_refs(value, refs)
-    case value
-    when Hash
-      refs << value["$ref"] if value["$ref"].is_a?(String)
-      value.each_value { |child| collect_refs(child, refs) }
-    when Array
-      value.each { |child| collect_refs(child, refs) }
-    end
-  end
-
-  def resolve_json_pointer!(document, ref)
-    ref.delete_prefix("#/").split("/").reduce(document) do |node, segment|
-      key = segment.gsub("~1", "/").gsub("~0", "~")
-      assert!(node.is_a?(Hash) && node.key?(key), "JSON $ref 无法解析: #{ref}")
-      node.fetch(key)
-    end
-  end
-
-  def validate_source_paths!(handoff)
-    yaml_path = handoff.fetch("source_yaml")
-    json_path = handoff.fetch("source_json")
-    match = %r{\Adocs/\.scratch/([^/]+)/api/([^/]+)\.yaml\z}.match(yaml_path)
-    assert!(!match.nil? && match[1] == match[2], "冻结 YAML 路径不符合 feature 约定")
-    assert!(json_path == "docs/.scratch/#{match[1]}/api/#{match[2]}.json", "JSON 必须与冻结 YAML 同 feature 同目录")
-  end
-
-  def assert!(condition, message)
-    raise ArgumentError, message unless condition
-  end
-end
-
-def build_context(root)
-  feature = "order"
-  api_dir = File.join(root, "docs", ".scratch", feature, "api")
-  frontend_dir = File.join(root, "frontend", "openapi")
-  Dir.mkdir(File.join(root, "docs"))
-  Dir.mkdir(File.join(root, "docs", ".scratch"))
-  Dir.mkdir(File.join(root, "docs", ".scratch", feature))
-  Dir.mkdir(api_dir)
-  Dir.mkdir(File.join(root, "frontend"))
-  Dir.mkdir(frontend_dir)
-
-  source_yaml = File.join(api_dir, "#{feature}.yaml")
-  source_json = File.join(api_dir, "#{feature}.json")
-  materialized_json = File.join(frontend_dir, "openapi.json")
-  File.write(source_yaml, <<~YAML)
-    openapi: 3.1.0
-    info:
-      title: Order API
-      version: 1.0.0
-    paths:
-      /api/v1/orders/{orderId}:
-        get:
-          operationId: getOrder
-          parameters:
-            - name: orderId
-              in: path
-              required: true
-              schema:
-                type: string
-          responses:
-            '200':
-              description: success
-              content:
-                application/json:
-                  schema:
-                    $ref: '#/components/schemas/Order'
-    components:
-      schemas:
-        Order:
-          type: object
-          required: [id]
-          properties:
-            id:
-              type: string
-  YAML
-  json_document = {
-    "openapi" => "3.1.0",
-    "info" => { "title" => "Order API", "version" => "1.0.0" },
-    "paths" => {
-      "/api/v1/orders/{orderId}" => {
-        "get" => {
-          "operationId" => "getOrder",
-          "parameters" => [{ "name" => "orderId", "in" => "path", "required" => true, "schema" => { "type" => "string" } }],
-          "responses" => {
-            "200" => {
-              "description" => "success",
-              "content" => { "application/json" => { "schema" => { "$ref" => "#/components/schemas/Order" } } }
-            }
-          }
-        }
-      }
-    },
-    "components" => {
-      "schemas" => {
-        "Order" => {
-          "type" => "object",
-          "required" => ["id"],
-          "properties" => { "id" => { "type" => "string" } }
-        }
-      }
-    }
-  }
-  File.write(source_json, JSON.generate(json_document))
-  File.binwrite(materialized_json, File.binread(source_json))
-
-  source_yaml_path = "docs/.scratch/#{feature}/api/#{feature}.yaml"
-  source_json_path = "docs/.scratch/#{feature}/api/#{feature}.json"
-  handoff = {
-    "freeze_status" => "approved",
-    "export_status" => "exported",
-    "freeze_record" => "docs/.scratch/#{feature}/api/#{feature}-freeze.md",
-    "export_record" => "docs/.scratch/#{feature}/api/#{feature}-json-export.md",
-    "source_yaml" => source_yaml_path,
-    "source_json" => source_json_path,
-    "yaml_sha256" => Digest::SHA256.file(source_yaml).hexdigest,
-    "json_sha256" => Digest::SHA256.file(source_json).hexdigest,
-    "bundle_command" => "pnpm exec redocly bundle #{source_yaml_path} --output #{source_json_path} --ext json --component-renaming-conflicts-severity=error"
-  }
-  {
-    source_yaml: source_yaml,
-    source_json: source_json,
-    materialized_json: materialized_json,
-    handoff: handoff
-  }
-end
-
-def expect_rejected(label)
-  yield
-  raise "负向场景未被阻断: #{label}"
-rescue ArgumentError
-  true
-end
-
-Dir.mktmpdir("openapi-handoff-") do |root|
-  context = build_context(root)
-  OpenapiJsonHandoff.validate!(**context)
-
-  expect_rejected("Draft 不能导出") do
-    OpenapiJsonHandoff.validate!(**context.merge(handoff: context.fetch(:handoff).merge("freeze_status" => "draft")))
-  end
-
-  expect_rejected("Maven 链路不能作为导出命令") do
-    OpenapiJsonHandoff.validate!(**context.merge(handoff: context.fetch(:handoff).merge("bundle_command" => "mvn package")))
-  end
-
-  expect_rejected("运行时 URL 不能替代治理 JSON") do
-    OpenapiJsonHandoff.validate!(**context.merge(handoff: context.fetch(:handoff).merge("source_json" => "https://example.invalid/openapi.json")))
-  end
-
-  original_json = File.binread(context.fetch(:source_json))
-
-  changed_operation = JSON.parse(original_json)
-  changed_operation.fetch("paths").fetch("/api/v1/orders/{orderId}").fetch("get")["operationId"] = "getOtherOrder"
-  File.write(context.fetch(:source_json), JSON.generate(changed_operation))
-  expect_rejected("JSON 必须保留冻结 YAML 的 operationId") do
-    OpenapiJsonHandoff.validate!(**context.merge(handoff: context.fetch(:handoff).merge("json_sha256" => Digest::SHA256.file(context.fetch(:source_json)).hexdigest)))
-  end
-
-  invalid_ref = JSON.parse(original_json)
-  invalid_ref.fetch("paths").fetch("/api/v1/orders/{orderId}").fetch("get").fetch("responses").fetch("200").fetch("content").fetch("application/json").fetch("schema")["$ref"] = "#/components/schemas/Missing"
-  File.write(context.fetch(:source_json), JSON.generate(invalid_ref))
-  expect_rejected("JSON $ref 必须可解析") do
-    OpenapiJsonHandoff.validate!(**context.merge(handoff: context.fetch(:handoff).merge("json_sha256" => Digest::SHA256.file(context.fetch(:source_json)).hexdigest)))
-  end
-
-  changed_response = JSON.parse(original_json)
-  changed_response.fetch("paths").fetch("/api/v1/orders/{orderId}").fetch("get").fetch("responses").fetch("200").fetch("content").fetch("application/json").fetch("schema")["$ref"] = "#/components/schemas/ChangedOrder"
-  changed_response.fetch("components").fetch("schemas")["ChangedOrder"] = { "type" => "string" }
-  File.write(context.fetch(:source_json), JSON.generate(changed_response))
-  expect_rejected("JSON 必须保留冻结 YAML 的请求和响应契约") do
-    OpenapiJsonHandoff.validate!(**context.merge(handoff: context.fetch(:handoff).merge("json_sha256" => Digest::SHA256.file(context.fetch(:source_json)).hexdigest)))
-  end
-
-  File.binwrite(context.fetch(:source_json), original_json)
-  File.write(context.fetch(:materialized_json), "{\"openapi\":\"3.1.0\",\"paths\":{\"/tampered\":{}}}")
-  expect_rejected("前端 JSON 被手改") do
-    OpenapiJsonHandoff.validate!(**context)
-  end
-
-  File.binwrite(context.fetch(:materialized_json), original_json)
-  File.write(context.fetch(:source_json), "{\"openapi\":\"3.1.0\",\"paths\":{\"/tampered-source\":{}}}")
-  expect_rejected("治理 JSON 被手改") do
-    OpenapiJsonHandoff.validate!(**context)
-  end
-end
-
-puts "OpenAPI YAML-first JSON handoff scenarios passed"
+#!/usr/bin/env node
+import { runScenario } from "./lib/scenario-checks.mjs";
+try { runScenario("openapiJson"); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }

package/template/scripts/verify-openapi-yaml-first-scenarios

@@ -1,120 +1,3 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "json"
-require "pathname"
-require "yaml"
-
-ROOT = Pathname.new(__dir__).join("..").realpath
-PROJECTION_ROOTS = %w[
-  .agents/skills
-  .claude/skills
-  .codex/skills
-  .hermes/skills
-  .pi/skills
-  .qoder/skills
-  .trae/skills
-].freeze
-
-failures = []
-
-template_path = ROOT.join("docs/templates/openapi-spec-template.yaml")
-documents = YAML.load_stream(template_path.read)
-failures << "OpenAPI YAML 模板必须是单一 YAML document" unless documents.length == 1
-document = documents.first
-unless document.is_a?(Hash) && document["openapi"] == "3.1.0"
-  failures << "OpenAPI YAML 模板必须是 OAS 3.1 文档"
-end
-%w[pipeline stage status owner].each do |field|
-  failures << "OpenAPI YAML 模板不得把生命周期元数据写入根字段: #{field}" if document.is_a?(Hash) && document.key?(field)
-end
-
-PROJECTION_ROOTS.each do |root|
-  failures << "已移除的 yss-openapi 仍存在: #{root}/yss-openapi" if ROOT.join(root, "yss-openapi").exist?
-end
-
-lock = JSON.parse(ROOT.join("skills-lock.json").read)
-if lock.dig("skills", "shared", "yss-openapi")
-  failures << "skills-lock.json 仍登记 yss-openapi"
-end
-
-public_skills = JSON.parse(ROOT.join("yss-public-skills.json").read)
-if public_skills.fetch("skills").include?("yss-openapi")
-  failures << "yss-public-skills.json 仍公开 yss-openapi"
-end
-
-router = ROOT.join(".agents/skills/yss-router/references/router-contract.yaml").read
-removed_skill_pattern = /(?<![a-z0-9-])yss-openapi(?![a-z0-9-])/
-failures << "Router 仍路由到 yss-openapi" if router.match?(removed_skill_pattern)
-failures << "Router 脚手架合同仍允许旧 OpenAPI 基线" if router.include?("smart_doc_baseline")
-unless router.include?("api-integration:\n    when_regeneration: [yss-openapi-governance]")
-  failures << "Router 未将客户端重新生成路由到 yss-openapi-governance"
-end
-
-lifecycle_contract = ROOT.join(".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml").read
-failures << "Lifecycle 脚手架合同仍允许旧 OpenAPI 基线" if lifecycle_contract.include?("smart_doc_baseline")
-lifecycle_skill = ROOT.join(".agents/skills/yss-product-lifecycle/SKILL.md").read
-failures << "Lifecycle 说明仍保留旧 OpenAPI 基线" if lifecycle_skill.match?(/smart[ -]?doc/i)
-implementation_routing_template = ROOT.join("docs/templates/implementation-routing-template.md").read
-failures << "实现路由模板仍保留旧 OpenAPI 基线" if implementation_routing_template.match?(/smart[ -]?doc/i)
-
-scaffold_pom = ROOT.join(".agents/skills/yss-ddd-scaffold-generator/assets/templates/pom/bootstrap-pom.xml.template").read
-failures << "后端脚手架仍包含 smart-doc Maven 插件" if scaffold_pom.include?("smart-doc-maven-plugin")
-failures << "后端脚手架仍保留 smart-doc 配置模板" if ROOT.join(".agents/skills/yss-ddd-scaffold-generator/assets/templates/config/smart-doc.json.template").exist?
-
-scaffold_generator = ROOT.join(".agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.py").read
-failures << "后端脚手架生成器仍生成 smart-doc 配置" if scaffold_generator.include?("smart-doc.json") || scaffold_generator.include?("smart-doc-maven-plugin")
-
-governance = ROOT.join(".agents/skills/yss-openapi-governance/SKILL.md").read
-%w[YAML-first 唯一权威 redocly\ bundle --ext\ json operationId].each do |marker|
-  failures << "OpenAPI Governance 缺少 YAML-first JSON 派生规则: #{marker}" unless governance.include?(marker)
-end
-failures << "OpenAPI Governance 仍依赖 smart-doc" if governance.include?("smart-doc")
-%w[pnpm\ generate:api orval.config unsafeDisableValidation].each do |marker|
-  failures << "OpenAPI Governance 越界到前端代码生成或 Orval 配置: #{marker}" if governance.include?(marker)
-end
-
-api_integration = ROOT.join(".agents/skills/yss-api-integration/SKILL.md").read
-%w[冻结的\ OpenAPI\ YAML redocly\ bundle 原样物化 既有前端代码生成流程].each do |marker|
-  failures << "API Integration 缺少冻结 JSON 的下游交接规则: #{marker}" unless api_integration.include?(marker)
-end
-failures << "API Integration 仍引用 yss-openapi" if api_integration.match?(removed_skill_pattern)
-%w[docs/.scratch/<feature>/api/<feature>.json SHA-256 受控交接].each do |marker|
-  failures << "API Integration 未绑定治理 JSON 派生物: #{marker}" unless api_integration.include?(marker)
-end
-%w[orval.config unsafeDisableValidation].each do |marker|
-  failures << "API Integration 越界要求修改或核验 Orval 配置: #{marker}" if api_integration.include?(marker)
-end
-
-frontend_scaffold = ROOT.join(".agents/skills/yss-frontend-scaffold-generator/SKILL.md").read
-failures << "前端脚手架仍接受任意 openapi_source" if frontend_scaffold.include?("openapi_source")
-%w[OpenAPI\ Freeze\ 记录 OpenAPI\ JSON\ 派生记录 SHA-256 openapi/openapi.json 既有前端代码生成流程].each do |marker|
-  failures << "前端脚手架未绑定冻结 JSON 交接: #{marker}" unless frontend_scaffold.include?(marker)
-end
-%w[配置并读取实际\ `orval.config.*` unsafeDisableValidation].each do |marker|
-  failures << "前端脚手架越界修改或核验既有 Orval 配置: #{marker}" if frontend_scaffold.include?(marker)
-end
-
-export_record = ROOT.join("docs/api/templates/openapi-json-export-record-template.md")
-failures << "缺少 OpenAPI JSON 派生记录模板" unless export_record.file?
-if export_record.file?
-  export_record_text = export_record.read
-  %w[Orval\ 输入路径 orval.config unsafeDisableValidation pnpm\ generate:api].each do |marker|
-    failures << "JSON 派生记录越界记录前端 Orval 配置或执行: #{marker}" if export_record_text.include?(marker)
-  end
-end
-
-freeze_record = ROOT.join("docs/api/templates/openapi-freeze-record-template.md")
-%w[orval.config unsafeDisableValidation].each do |marker|
-  failures << "OpenAPI Freeze 记录越界规定 Orval 配置: #{marker}" if freeze_record.read.include?(marker)
-end
-
-draft_checklist = ROOT.join("docs/api/templates/openapi-draft-review-checklist.md")
-failures << "Draft 评审清单越界要求 Orval 输入路径" if draft_checklist.read.include?("Orval 输入路径")
-
-unless failures.empty?
-  warn failures.join("\n")
-  exit 1
-end
-
-puts "OpenAPI YAML-first 场景验证通过"
+#!/usr/bin/env node
+import { runScenario } from "./lib/scenario-checks.mjs";
+try { runScenario("openapiYaml"); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }