feat(tailwindcss-patch): stabilize validate json contract

Author: sonofmagic

.changeset/metal-horses-work.md

@@ -5,5 +5,5 @@
 Publish schema for validate JSON output.
 
 - add `tailwindcss-patch/validate-result.schema.json` for `tw-patch validate --json`
-- include failure payload contract (`reason`, `exitCode`, `message`) alongside success shape reference
+- include success/failure payload contracts (`ok: true` success and `ok: false` failure with `reason`, `exitCode`, `message`)
 - export `VALIDATE_FAILURE_REASONS` and align schema tests with public validate constants

packages/tailwindcss-patch/MIGRATION.md

@@ -94,6 +94,7 @@ Migration mapping:
 - `tw-patch restore --json` now exposes report metadata fields (`reportKind`, `reportSchemaVersion`) when available for easier diagnostics.
 - `tw-patch validate` can validate migration report compatibility in dry-run mode without restoring files.
 - `tw-patch validate` now uses dedicated failure exit codes for CI diagnostics (`21`/`22`/`23`/`24`).
+- `tw-patch validate --json` now emits a stable discriminated payload (`ok: true` success / `ok: false` failure with `reason` + `exitCode`), covered by `tailwindcss-patch/validate-result.schema.json`.
 - Migration report tooling now has public exports from package entry (`migrateConfigFiles`, `restoreConfigFiles`, report constants/types) and published JSON schema subpaths: `tailwindcss-patch/migration-report.schema.json`, `tailwindcss-patch/restore-result.schema.json`, `tailwindcss-patch/validate-result.schema.json`.
 - Commands resolve configuration from `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. Existing configuration files continue to work without changes.
 

packages/tailwindcss-patch/README-cn.md

@@ -107,6 +107,8 @@ CLI 会通过 `@tailwindcss-mangle/config` 加载 `tailwindcss-patch.config.ts`
 `tw-patch validate` 会以 dry-run 模式执行迁移报告校验，不写回任何恢复文件，同时校验报告 schema 与备份引用状态。
 校验失败时提供分层退出码，便于 CI 判定：
 `21` 报告不兼容，`22` 严格模式下备份缺失，`23` I/O 错误，`24` 未知错误。
+使用 `--json` 时会输出稳定结构：
+成功 => `{ ok: true, ...restoreFields }`，失败 => `{ ok: false, reason, exitCode, message }`。
 
 JSON Schema 通过子路径发布：
 `tailwindcss-patch/migration-report.schema.json`、
@@ -115,6 +117,27 @@ JSON Schema 通过子路径发布：
 编程场景也可直接从包入口导入报告相关导出：
 `migrateConfigFiles`、`restoreConfigFiles`、`MIGRATION_REPORT_KIND`、`MIGRATION_REPORT_SCHEMA_VERSION`、`ConfigFileMigrationReport`、`VALIDATE_EXIT_CODES`。
 
+### CI 推荐流程
+
+```bash
+# 1) 先检查 workspace 中是否还有待迁移配置
+pnpm dlx tw-patch migrate --workspace --check --report-file .tw-patch/migrate-report.json
+
+# 2) 再校验报告兼容性与备份引用，并保存 JSON 结果
+set +e
+pnpm dlx tw-patch validate --report-file .tw-patch/migrate-report.json --strict --json > .tw-patch/validate-result.json
+status=$?
+set -e
+
+case "$status" in
+  0)  echo "validate ok" ;;
+  21) echo "报告 schema/kind 不兼容"; exit 1 ;;
+  22) echo "--strict 下存在缺失备份"; exit 1 ;;
+  23) echo "读取报告或备份时发生 I/O 错误"; exit 1 ;;
+  *)  echo "未知校验错误"; exit "$status" ;;
+esac
+```
+
 ### `tokens` 常用参数
 
 | 参数                                   | 说明                                                        |

packages/tailwindcss-patch/README.md

@@ -164,6 +164,8 @@ With `--json`, restore output includes `reportKind` / `reportSchemaVersion` when
 `tw-patch validate` performs migration report compatibility checks without writing restored files. It runs report schema validation and scans backup references in dry-run mode.
 On failure, validate uses dedicated exit codes for CI:
 `21` report incompatibility, `22` strict missing backups, `23` I/O errors, `24` unknown errors.
+With `--json`, validate emits a stable payload:
+success => `{ ok: true, ...restoreFields }`, failure => `{ ok: false, reason, exitCode, message }`.
 
 Schemas are published at package subpaths:
 `tailwindcss-patch/migration-report.schema.json`,
@@ -172,6 +174,27 @@ Schemas are published at package subpaths:
 Programmatic consumers can also import report helpers/types from package entry:
 `migrateConfigFiles`, `restoreConfigFiles`, `MIGRATION_REPORT_KIND`, `MIGRATION_REPORT_SCHEMA_VERSION`, `ConfigFileMigrationReport`, `VALIDATE_EXIT_CODES`.
 
+### CI recipe
+
+```bash
+# 1) fail fast when workspace configs still need migration
+pnpm dlx tw-patch migrate --workspace --check --report-file .tw-patch/migrate-report.json
+
+# 2) validate report schema/backup references and keep machine-readable output
+set +e
+pnpm dlx tw-patch validate --report-file .tw-patch/migrate-report.json --strict --json > .tw-patch/validate-result.json
+status=$?
+set -e
+
+case "$status" in
+  0)  echo "validate ok" ;;
+  21) echo "report schema/kind incompatible"; exit 1 ;;
+  22) echo "missing backups under --strict"; exit 1 ;;
+  23) echo "I/O failure while reading report/backups"; exit 1 ;;
+  *)  echo "unknown validate failure"; exit "$status" ;;
+esac
+```
+
 ### Token report options
 
 | Flag                                   | Description                                                                               |

packages/tailwindcss-patch/schema/restore-result.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://mangle.icebreaker.top/schemas/tailwindcss-patch/restore-result.schema.json",
-  "title": "tailwindcss-patch restore/validate result",
-  "description": "Schema for JSON output from `tw-patch restore --json` and `tw-patch validate --json`.",
+  "title": "tailwindcss-patch restore result",
+  "description": "Schema for JSON output from `tw-patch restore --json`.",
   "type": "object",
   "required": [
     "cwd",

packages/tailwindcss-patch/schema/validate-result.schema.json

@@ -5,13 +5,82 @@
   "description": "Schema for JSON output from `tw-patch validate --json`.",
   "oneOf": [
     {
-      "$ref": "./restore-result.schema.json"
+      "$ref": "#/$defs/success"
     },
     {
       "$ref": "#/$defs/failure"
     }
   ],
   "$defs": {
+    "success": {
+      "type": "object",
+      "required": [
+        "ok",
+        "cwd",
+        "reportFile",
+        "dryRun",
+        "strict",
+        "scannedEntries",
+        "restorableEntries",
+        "restoredFiles",
+        "missingBackups",
+        "skippedEntries",
+        "restored"
+      ],
+      "properties": {
+        "ok": {
+          "type": "boolean",
+          "const": true
+        },
+        "cwd": {
+          "type": "string"
+        },
+        "reportFile": {
+          "type": "string"
+        },
+        "reportKind": {
+          "type": "string",
+          "const": "tw-patch-migrate-report"
+        },
+        "reportSchemaVersion": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "dryRun": {
+          "type": "boolean"
+        },
+        "strict": {
+          "type": "boolean"
+        },
+        "scannedEntries": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "restorableEntries": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "restoredFiles": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "missingBackups": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "skippedEntries": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "restored": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "failure": {
       "type": "object",
       "required": [

packages/tailwindcss-patch/src/cli/commands.ts

@@ -54,6 +54,17 @@ export interface ValidateFailureSummary {
   message: string
 }
 
+export interface ValidateJsonSuccessPayload extends RestoreConfigFilesResult {
+  ok: true
+}
+
+export interface ValidateJsonFailurePayload {
+  ok: false
+  reason: ValidateFailureReason
+  exitCode: number
+  message: string
+}
+
 const IO_ERROR_CODES = new Set(['ENOENT', 'EACCES', 'EPERM', 'EISDIR', 'ENOTDIR', 'EMFILE', 'ENFILE'])
 
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
@@ -754,7 +765,11 @@ async function validateCommandDefaultHandler(ctx: TailwindcssPatchCommandContext
     })
 
     if (args.json) {
-      logger.log(JSON.stringify(result, null, 2))
+      const payload: ValidateJsonSuccessPayload = {
+        ok: true,
+        ...result,
+      }
+      logger.log(JSON.stringify(payload, null, 2))
       return result
     }
 
@@ -772,12 +787,13 @@ async function validateCommandDefaultHandler(ctx: TailwindcssPatchCommandContext
   catch (error) {
     const summary = classifyValidateError(error)
     if (args.json) {
-      logger.log(JSON.stringify({
+      const payload: ValidateJsonFailurePayload = {
         ok: false,
         reason: summary.reason,
         exitCode: summary.exitCode,
         message: summary.message,
-      }, null, 2))
+      }
+      logger.log(JSON.stringify(payload, null, 2))
     }
     else {
       logger.error(`Validation failed [${summary.reason}] (exit ${summary.exitCode}): ${summary.message}`)

packages/tailwindcss-patch/src/index.ts

@@ -13,6 +13,8 @@ export {
   type TailwindcssPatchCommandOptions,
   type ValidateFailureReason,
   type ValidateFailureSummary,
+  type ValidateJsonFailurePayload,
+  type ValidateJsonSuccessPayload,
   ValidateCommandError,
   VALIDATE_EXIT_CODES,
   VALIDATE_FAILURE_REASONS,

packages/tailwindcss-patch/test/cli.mount.test.ts

@@ -529,6 +529,7 @@ describe('mountTailwindcssPatchCommands', () => {
       strict: false,
     })
     expect(logger.log).toHaveBeenCalledWith(JSON.stringify({
+      ok: true,
       cwd: '/tmp/project',
       reportFile: '/tmp/project/.tw-patch/migrate-report.json',
       reportKind: 'tw-patch-migrate-report',

packages/tailwindcss-patch/test/migration-report.schema.test.ts

@@ -57,7 +57,10 @@ describe('validate result json schema', () => {
 
     expect(schema.$schema).toContain('json-schema.org')
     expect(schema.oneOf).toHaveLength(2)
-    expect(schema.oneOf[0].$ref).toContain('restore-result.schema.json')
+    expect(schema.$defs.success.required).toEqual(
+      expect.arrayContaining(['ok', 'reportFile', 'dryRun', 'restored']),
+    )
+    expect(schema.$defs.success.properties.ok.const).toBe(true)
     expect(schema.$defs.failure.properties.reason.enum).toEqual([...VALIDATE_FAILURE_REASONS])
     expect(schema.$defs.failure.properties.exitCode.enum).toEqual([
       VALIDATE_EXIT_CODES.REPORT_INCOMPATIBLE,