feat(tailwindcss-patch): publish validate result json schema

Author: sonofmagic

.changeset/metal-horses-work.md

@@ -0,0 +1,9 @@
+---
+"tailwindcss-patch": patch
+---
+
+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
+- export `VALIDATE_FAILURE_REASONS` and align schema tests with public validate constants

packages/tailwindcss-patch/MIGRATION.md

@@ -94,7 +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`).
-- 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`.
+- 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.
 
 ## 4. Cache handling

packages/tailwindcss-patch/README-cn.md

@@ -110,9 +110,10 @@ CLI 会通过 `@tailwindcss-mangle/config` 加载 `tailwindcss-patch.config.ts`
 
 JSON Schema 通过子路径发布：
 `tailwindcss-patch/migration-report.schema.json`、
-`tailwindcss-patch/restore-result.schema.json`。
+`tailwindcss-patch/restore-result.schema.json`、
+`tailwindcss-patch/validate-result.schema.json`。
 编程场景也可直接从包入口导入报告相关导出：
-`migrateConfigFiles`、`restoreConfigFiles`、`MIGRATION_REPORT_KIND`、`MIGRATION_REPORT_SCHEMA_VERSION`、`ConfigFileMigrationReport`。
+`migrateConfigFiles`、`restoreConfigFiles`、`MIGRATION_REPORT_KIND`、`MIGRATION_REPORT_SCHEMA_VERSION`、`ConfigFileMigrationReport`、`VALIDATE_EXIT_CODES`。
 
 ### `tokens` 常用参数
 

packages/tailwindcss-patch/README.md

@@ -167,9 +167,10 @@ On failure, validate uses dedicated exit codes for CI:
 
 Schemas are published at package subpaths:
 `tailwindcss-patch/migration-report.schema.json`,
-`tailwindcss-patch/restore-result.schema.json`.
+`tailwindcss-patch/restore-result.schema.json`,
+`tailwindcss-patch/validate-result.schema.json`.
 Programmatic consumers can also import report helpers/types from package entry:
-`migrateConfigFiles`, `restoreConfigFiles`, `MIGRATION_REPORT_KIND`, `MIGRATION_REPORT_SCHEMA_VERSION`, `ConfigFileMigrationReport`.
+`migrateConfigFiles`, `restoreConfigFiles`, `MIGRATION_REPORT_KIND`, `MIGRATION_REPORT_SCHEMA_VERSION`, `ConfigFileMigrationReport`, `VALIDATE_EXIT_CODES`.
 
 ### Token report options
 

packages/tailwindcss-patch/package.json

@@ -26,7 +26,8 @@
       "require": "./src/index.ts"
     },
     "./migration-report.schema.json": "./schema/migration-report.schema.json",
-    "./restore-result.schema.json": "./schema/restore-result.schema.json"
+    "./restore-result.schema.json": "./schema/restore-result.schema.json",
+    "./validate-result.schema.json": "./schema/validate-result.schema.json"
   },
   "main": "./src/index.ts",
   "module": "./src/index.ts",
@@ -63,7 +64,8 @@
         "require": "./dist/index.js"
       },
       "./migration-report.schema.json": "./schema/migration-report.schema.json",
-      "./restore-result.schema.json": "./schema/restore-result.schema.json"
+      "./restore-result.schema.json": "./schema/restore-result.schema.json",
+      "./validate-result.schema.json": "./schema/validate-result.schema.json"
     },
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",

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

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mangle.icebreaker.top/schemas/tailwindcss-patch/validate-result.schema.json",
+  "title": "tailwindcss-patch validate result",
+  "description": "Schema for JSON output from `tw-patch validate --json`.",
+  "oneOf": [
+    {
+      "$ref": "./restore-result.schema.json"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "failure": {
+      "type": "object",
+      "required": [
+        "ok",
+        "reason",
+        "exitCode",
+        "message"
+      ],
+      "properties": {
+        "ok": {
+          "type": "boolean",
+          "const": false
+        },
+        "reason": {
+          "type": "string",
+          "enum": [
+            "report-incompatible",
+            "missing-backups",
+            "io-error",
+            "unknown-error"
+          ]
+        },
+        "exitCode": {
+          "type": "integer",
+          "enum": [
+            21,
+            22,
+            23,
+            24
+          ]
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -39,7 +39,14 @@ export const VALIDATE_EXIT_CODES = {
   UNKNOWN_ERROR: 24,
 } as const
 
-export type ValidateFailureReason = 'report-incompatible' | 'missing-backups' | 'io-error' | 'unknown-error'
+export const VALIDATE_FAILURE_REASONS = [
+  'report-incompatible',
+  'missing-backups',
+  'io-error',
+  'unknown-error',
+] as const
+
+export type ValidateFailureReason = (typeof VALIDATE_FAILURE_REASONS)[number]
 
 export interface ValidateFailureSummary {
   reason: ValidateFailureReason

packages/tailwindcss-patch/src/index.ts

@@ -15,6 +15,7 @@ export {
   type ValidateFailureSummary,
   ValidateCommandError,
   VALIDATE_EXIT_CODES,
+  VALIDATE_FAILURE_REASONS,
   tailwindcssPatchCommands,
 } from './cli/commands'
 export {

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

@@ -4,6 +4,8 @@ import { describe, expect, it } from 'vitest'
 import {
   MIGRATION_REPORT_KIND,
   MIGRATION_REPORT_SCHEMA_VERSION,
+  VALIDATE_EXIT_CODES,
+  VALIDATE_FAILURE_REASONS,
   migrateConfigFiles,
   restoreConfigFiles,
 } from '../src'
@@ -47,3 +49,21 @@ describe('restore result json schema', () => {
     expect(schema.properties.reportSchemaVersion.minimum).toBe(MIGRATION_REPORT_SCHEMA_VERSION)
   })
 })
+
+describe('validate result json schema', () => {
+  it('ships a validate-result schema aligned with validate failure contracts', async () => {
+    const schemaPath = path.resolve(process.cwd(), 'schema/validate-result.schema.json')
+    const schema = await fs.readJSON(schemaPath) as Record<string, any>
+
+    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.failure.properties.reason.enum).toEqual([...VALIDATE_FAILURE_REASONS])
+    expect(schema.$defs.failure.properties.exitCode.enum).toEqual([
+      VALIDATE_EXIT_CODES.REPORT_INCOMPATIBLE,
+      VALIDATE_EXIT_CODES.MISSING_BACKUPS,
+      VALIDATE_EXIT_CODES.IO_ERROR,
+      VALIDATE_EXIT_CODES.UNKNOWN_ERROR,
+    ])
+  })
+})