create-yss-spec 3.3.8 → 3.4.3

package/template/scripts/verify-openapi-draft-validation-record

@@ -1,144 +1,25 @@
 #!/usr/bin/env node
-import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
-import { parseAllDocuments, parseDocument } from "./vendor/yaml.mjs";
-import { validateJsonSchema } from "./lib/json-schema.mjs";
+import { validateOpenApiDraftValidationRecord } from "./lib/openapi-draft-validation.mjs";
 
 const templateRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const schemaPath = path.join(templateRoot, "docs/process/schemas/openapi-draft-validation-record.schema.json");
-const methods = new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
-
-function ensure(condition, message) {
-  if (!condition) throw new TypeError(message);
-}
-
-function resolveSafe(root, reference) {
-  ensure(typeof reference === "string" && reference.length > 0, "引用不能为空");
-  ensure(!path.isAbsolute(reference) && !reference.includes("\\") && !reference.split("/").includes(".."), `引用必须位于项目内: ${reference}`);
-  const target = path.resolve(root, reference);
-  ensure(target === root || target.startsWith(`${root}${path.sep}`), `引用越出项目根: ${reference}`);
-  ensure(existsSync(target), `引用不可读取: ${reference}`);
-  ensure(!lstatSync(target).isSymbolicLink(), `引用不能是 symlink: ${reference}`);
-  return target;
-}
-
-function parseOne(file, label) {
-  const source = readFileSync(file, "utf8");
-  const documents = parseAllDocuments(source, { uniqueKeys: true, maxAliasCount: 0 });
-  ensure(documents.length === 1, `${label} 必须是单一 YAML document`);
-  ensure(!documents[0].errors.length, `${label} YAML 无效: ${documents[0].errors[0]?.message}`);
-  return documents[0].toJS({ maxAliasCount: 0 });
-}
-
-function pointer(value, fragment, reference) {
-  if (!fragment || fragment === "#") return value;
-  ensure(fragment.startsWith("#/"), `仅支持 JSON Pointer fragment: ${reference}`);
-  return fragment.slice(2).split("/").reduce((current, part) => {
-    const key = decodeURIComponent(part).replaceAll("~1", "/").replaceAll("~0", "~");
-    ensure(current && Object.hasOwn(current, key), `$ref 无法解析: ${reference}`);
-    return current[key];
-  }, value);
-}
-
-function verifyReferences(rootDocument, draftFile) {
-  const apiRoot = realpathSync(path.dirname(draftFile));
-  const cache = new Map([[realpathSync(draftFile), rootDocument]]);
-  const active = new Set();
-
-  function load(reference, ownerFile) {
-    ensure(!/^[a-z][a-z0-9+.-]*:/i.test(reference) && !path.isAbsolute(reference), `$ref 禁止远程或绝对路径: ${reference}`);
-    const [filePart, fragment = ""] = reference.split("#", 2);
-    const targetFile = filePart ? path.resolve(path.dirname(ownerFile), filePart) : ownerFile;
-    ensure(existsSync(targetFile), `$ref 文件不存在: ${reference}`);
-    const realTarget = realpathSync(targetFile);
-    ensure(realTarget === apiRoot || realTarget.startsWith(`${apiRoot}${path.sep}`), `$ref 越出 feature API 目录: ${reference}`);
-    if (!cache.has(realTarget)) cache.set(realTarget, parseOne(realTarget, `$ref ${reference}`));
-    return { value: pointer(cache.get(realTarget), fragment ? `#${fragment}` : "", reference), file: realTarget };
-  }
-
-  function walk(value, ownerFile) {
-    if (!value || typeof value !== "object") return;
-    if (typeof value.$ref === "string") {
-      const key = `${ownerFile}|${value.$ref}`;
-      if (active.has(key)) return;
-      active.add(key);
-      const resolved = load(value.$ref, ownerFile);
-      walk(resolved.value, resolved.file);
-      active.delete(key);
-    }
-    for (const child of Object.values(value)) walk(child, ownerFile);
-  }
-  walk(rootDocument, realpathSync(draftFile));
-  return (reference, ownerFile = realpathSync(draftFile)) => load(reference, ownerFile);
-}
-
-function verifyOperations(document, resolveReference) {
-  const operationIds = new Set();
-  for (const [route, pathItem] of Object.entries(document.paths ?? {})) {
-    if (!pathItem || typeof pathItem !== "object") continue;
-    const placeholders = [...route.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]);
-    for (const [method, operation] of Object.entries(pathItem)) {
-      if (!methods.has(method) || !operation || typeof operation !== "object") continue;
-      ensure(typeof operation.operationId === "string" && operation.operationId.length > 0, `${method.toUpperCase()} ${route} 缺少 operationId`);
-      ensure(!operationIds.has(operation.operationId), `operationId 重复: ${operation.operationId}`);
-      operationIds.add(operation.operationId);
-      const parameters = [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])].map((item) =>
-        typeof item?.$ref === "string" ? resolveReference(item.$ref).value : item
-      );
-      for (const name of placeholders) {
-        const parameter = parameters.find((item) => item?.in === "path" && item?.name === name);
-        ensure(parameter && parameter.required === true, `${method.toUpperCase()} ${route} 缺少 required path parameter: ${name}`);
-      }
-    }
-  }
-}
 
 try {
   const { values, positionals } = parseArgs({
     options: { "allow-template": { type: "boolean" }, root: { type: "string", default: templateRoot } },
     allowPositionals: true,
-    strict: true
+    strict: true,
   });
-  ensure(positionals.length === 1, "用法: scripts/verify-openapi-draft-validation-record [--allow-template] [--root <project>] <record.yaml>");
-  const root = path.resolve(values.root);
-  const recordFile = path.resolve(positionals[0]);
-  const recordDocument = parseDocument(readFileSync(recordFile, "utf8"), { uniqueKeys: true, maxAliasCount: 0 });
-  ensure(!recordDocument.errors.length, `validation record YAML 无效: ${recordDocument.errors[0]?.message}`);
-  const record = recordDocument.toJS({ maxAliasCount: 0 });
-  validateJsonSchema(record, schemaPath, { cwd: templateRoot, label: "OpenAPI Draft validation record schema" });
-
-  if (values["allow-template"]) {
-    ensure(record.template === true, "--allow-template 只接受模板记录");
-    process.stdout.write("OpenAPI Draft validation record 模板验证通过\n");
-    process.exit(0);
-  }
-
-  ensure(record.template === false, "正式 validation record 必须设置 template: false");
-  ensure(record.status === "passed", "正式 validation record 必须达到 status: passed");
-  ensure(record.toolchain.exit_code === 0, "Redocly lint 必须以退出码 0 完成");
-  ensure(Object.values(record.checks).every((result) => result === "passed"), "所有结构与 lint checks 必须为 passed");
-  ensure(record.toolchain.command === `pnpm exec redocly lint ${record.draft.ref}`, "lint command 必须精确指向当前 Draft");
-
-  const draftFile = resolveSafe(root, record.draft.ref);
-  const lockfile = resolveSafe(root, record.toolchain.lockfile_ref);
-  resolveSafe(root, record.toolchain.evidence_ref);
-  const draftBytes = readFileSync(draftFile);
-  const actualDigest = `sha256:${createHash("sha256").update(draftBytes).digest("hex")}`;
-  ensure(actualDigest === record.draft.sha256, `Draft SHA-256 不匹配: record=${record.draft.sha256}, actual=${actualDigest}`);
-  const lock = readFileSync(lockfile, "utf8");
-  const version = record.toolchain.version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const lockedPackage = new RegExp(`['\"]?@redocly/cli@${version}(?:['\":\\s(]|$)`).test(lock)
-    || new RegExp(`['\"]?@redocly/cli['\"]?:[\\s\\S]{0,240}?\\n\\s+version:\\s*['\"]?${version}(?:\\(|['\"\\s]|$)`).test(lock);
-  ensure(lockedPackage, "pnpm lockfile 未绑定记录中的 @redocly/cli 版本");
-
-  const draft = parseOne(draftFile, "OpenAPI Draft");
-  ensure(draft?.openapi === "3.1.0" && record.draft.oas_version === draft.openapi, "OpenAPI Draft 必须为 OAS 3.1.0");
-  const resolveReference = verifyReferences(draft, draftFile);
-  verifyOperations(draft, resolveReference);
-  process.stdout.write(`OpenAPI Draft validation record 验证通过: ${record.draft.sha256}\n`);
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-openapi-draft-validation-record [--allow-template] [--root <project>] <record.yaml>");
+  const result = validateOpenApiDraftValidationRecord(path.resolve(positionals[0]), {
+    root: path.resolve(values.root),
+    allowTemplate: values["allow-template"] === true,
+  });
+  process.stdout.write(result.template
+    ? "OpenAPI Draft validation record 模板验证通过\n"
+    : `OpenAPI Draft validation record 验证通过: ${result.record.draft.sha256}\n`);
 } catch (error) {
   process.stderr.write(`OpenAPI Draft validation record 验证失败: ${error.message}\n`);
   process.exitCode = 1;

package/template/scripts/verify-scaffold-architecture-decisions

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { platformProfile } from "./lib/backend-platform.mjs";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
@@ -35,6 +36,10 @@ try {
     if (ids.has(decision.decision_id) || projects.has(decision.project_id)) throw new TypeError("decision_id 与 project_id 必须唯一");
     ids.add(decision.decision_id);
     projects.set(decision.project_id, decision);
+    if (decision.platform_configuration) {
+      const profile = platformProfile(decision.platform_profile, undefined, decision.platform_configuration.spring_boot_version);
+      if (decision.platform_configuration.profile_id !== profile.id || decision.platform_configuration.spring_boot_version !== profile.spring_boot_version || decision.platform_configuration.java_version !== profile.java_version) throw new TypeError("platform_configuration 与平台选择不一致");
+    } else if (decision.platform_profile !== "spring-boot-2.7-jdk8") throw new TypeError("新平台缺少 platform_configuration");
     const confirmed = ["user-confirmed", "lifecycle-approved", "consumed"].includes(decision.status);
     const confirmation = decision.user_confirmation;
     if (confirmed && (!decision.confirmed_architecture || Object.values(confirmation).some((item) => item === null || item === ""))) throw new TypeError(`${decision.project_id} 已确认状态必须提供完整用户确认引用`);

package/template/scripts/verify-strategic-context-import

@@ -1,15 +1,19 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "./vendor/yaml.mjs";
 import { parseContextContract } from "./lib/context-contract.mjs";
-import { validateVisualBaseline } from "../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs";
+import { validateHandoffUiBaseline } from "./lib/ui-baseline.mjs";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const schemaPath = path.join(repoRoot, "docs/process/schemas/strategic-design-handoff.schema.json");
+const schemaPaths = new Map([
+  [3, "docs/process/schemas/strategic-design-handoff-v3.schema.json"],
+  [4, "docs/process/schemas/strategic-design-handoff-v4.schema.json"],
+  [5, "docs/process/schemas/strategic-design-handoff-v5.schema.json"],
+]);
 const pythonValidator = String.raw`
 import json, sys
 from jsonschema import Draft202012Validator
@@ -33,19 +37,13 @@ try {
   if (positionals.length !== 1 || !values.reconciliation) throw new TypeError("用法: scripts/verify-strategic-context-import --root <target-repo> --reconciliation <record> <handoff.yaml|json>");
   const root = path.resolve(values.root);
   const handoff = parseFile(path.resolve(positionals[0]));
-  if ([1, 2].includes(handoff.schema_version)) throw new TypeError(`migration-required: Strategic Design Handoff v${handoff.schema_version} 是只读历史资产；在途 UI 交接必须升级 v3 并携带 Visual Baseline`);
+  if ([1, 2].includes(handoff.schema_version)) throw new TypeError(`migration-required: Strategic Design Handoff v${handoff.schema_version} 是只读历史资产；修改或重新交付必须升级 Handoff v5 并重新批准`);
+  const schemaRef = schemaPaths.get(handoff.schema_version);
+  if (!schemaRef) throw new TypeError(`migration-required: 未知 Strategic Design Handoff schema_version ${String(handoff.schema_version)}；支持历史 v3/v4 与当前 v5`);
+  const schemaPath = path.join(repoRoot, schemaRef);
   const schemaResult = spawnSync("python3", ["-c", pythonValidator, schemaPath], { encoding: "utf8", input: JSON.stringify(handoff) });
   if (schemaResult.status !== 0) throw new TypeError(`${schemaResult.stdout}${schemaResult.stderr}`.trim());
-  const baselineRef = handoff.source.visual_baseline_ref;
-  const bundleRoot = path.resolve(root, baselineRef.persisted_ref);
-  const manifestPath = path.resolve(bundleRoot, baselineRef.manifest_ref);
-  if (!manifestPath.startsWith(`${bundleRoot}${path.sep}`) || !existsSync(manifestPath)) throw new TypeError("Strategic Design Handoff 的 Visual Baseline manifest 不可读或越界");
-  const baseline = parseFile(manifestPath);
-  const baselineResult = await validateVisualBaseline(baseline, { bundleRoot });
-  if (baselineResult.errors.length) throw new TypeError(`Visual Baseline 无效: ${baselineResult.errors.join("; ")}`);
-  if (baseline.baseline_id !== baselineRef.baseline_id || baseline.version !== baselineRef.version || baseline.bundle.digest !== baselineRef.digest) throw new TypeError("Strategic Design Handoff 的 Visual Baseline 身份、版本或 digest 不一致");
-  const actualCaseIds = baseline.cases.map((item) => item.case_id).sort();
-  if (JSON.stringify(actualCaseIds) !== JSON.stringify([...baselineRef.case_ids].sort())) throw new TypeError("Strategic Design Handoff 的 Visual Baseline case_ids 不一致");
+  await validateHandoffUiBaseline(root, handoff);
   const reconciliationResult = spawnSync(process.execPath, [path.join(repoRoot, "scripts/verify-context-reconciliation"), "--root", root, path.resolve(values.reconciliation)], { cwd: repoRoot, encoding: "utf8" });
   if (reconciliationResult.status !== 0) throw new TypeError(reconciliationResult.stderr.trim());
   const target = parseContextContract({ root });

package/template/scripts/verify-user-decision

@@ -1,16 +1,21 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
-import { decisionIO, verifyUserDecisionFile } from "./lib/user-decision.mjs";
+import { decisionIO, verifyUserDecisionFile, assertUserDecisionRequirement } from "./lib/user-decision.mjs";
 try {
-  const { positionals, values } = parseArgs({ allowPositionals: true, options: { root: { type: "string" }, requirements: { type: "string" } } });
+  const { positionals, values } = parseArgs({ allowPositionals: true, options: { root: { type: "string" }, requirements: { type: "string" }, continuation: { type: 'boolean' } } });
   if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-user-decision [--root <repo>] [--requirements <当前事项.json>] <record.yaml>");
   const options = values.root ? { root: values.root } : {};
   const io = decisionIO(options);
   const record = io.document(positionals[0]);
+  if (values.continuation) {
+    assertUserDecisionRequirement(record, options);
+    process.stdout.write('已有授权与当前延续范围校验通过\n');
+  } else {
   // No requirements means verify every requested item for approval; partial approvals need explicit current requirements.
   options.expected = values.requirements ? io.document(values.requirements) : record.request.items.map((item) => ({ boundary: item.boundary, subject_ref: item.subject.ref, scope: item.scope }));
   verifyUserDecisionFile(positionals[0], options);
   process.stdout.write("用户决定及当前批准范围校验通过\n");
+  }
 } catch (error) {
   process.stderr.write(`用户决定校验失败: ${error.message}\n`);
   process.exitCode = 1;