feat(tailwindcss-patch): add migration report schema metadata

Author: sonofmagic

.changeset/mean-rats-fold.md

@@ -0,0 +1,9 @@
+---
+"tailwindcss-patch": patch
+---
+
+Add migration report schema metadata and restore compatibility validation.
+
+- include `reportKind`, `schemaVersion`, `generatedAt`, and `tool` metadata in `tw-patch migrate` reports
+- validate `reportKind` and `schemaVersion` in `tw-patch restore` for safer report compatibility checks
+- keep backward compatibility with legacy reports that do not include envelope metadata

packages/tailwindcss-patch/MIGRATION.md

@@ -89,6 +89,8 @@ Migration mapping:
 - Optional `--backup-dir` can persist per-file pre-migration snapshots for manual recovery or auditing.
 - `--include` / `--exclude` patterns can narrow workspace migration scope, and `--report-file` can persist machine-readable migration reports.
 - `tw-patch restore` can restore config files from a migration report (`backupFile` entries) with optional `--dry-run`, `--strict`, and `--json`.
+- Migration reports now include envelope metadata: `reportKind`, `schemaVersion`, `generatedAt`, and `tool` (`name` / `version`).
+- `tw-patch restore` validates report metadata when present, rejects unknown kinds/newer schema versions, and keeps legacy metadata-free reports backward compatible.
 - 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

@@ -77,6 +77,8 @@ CLI 会通过 `@tailwindcss-mangle/config` 加载 `tailwindcss-patch.config.ts`
 
 迁移写入默认采用“事务式”策略：如果后续文件写入失败，会自动回滚此前已经写入的迁移文件，避免留下半迁移状态。若需要显式保留原始文件快照，可配合 `--backup-dir`；若需要审计产物，可配合 `--report-file`。
 
+迁移报告现在会携带元数据：`reportKind`、`schemaVersion`、`generatedAt` 和 `tool`（`name` / `version`），便于恢复阶段做兼容性校验。
+
 ### `restore` 常用参数
 
 | 参数                   | 说明                                                         |
@@ -87,6 +89,8 @@ CLI 会通过 `@tailwindcss-mangle/config` 加载 `tailwindcss-patch.config.ts`
 | `--strict`             | 报告中的备份文件缺失时直接报错退出。                         |
 | `--json`               | 输出 JSON 格式的恢复结果。                                   |
 
+`tw-patch restore` 在报告包含元数据时会执行 schema 校验。若 `reportKind` 不匹配或 `schemaVersion` 高于当前支持版本，会拒绝恢复；不包含该元数据的历史报告仍保持兼容。
+
 ### `tokens` 常用参数
 
 | 参数                                   | 说明                                                        |

packages/tailwindcss-patch/README.md

@@ -134,6 +134,8 @@ The CLI loads `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. Le
 
 When writing files, migration uses a transactional strategy by default: if a later file write fails, already written migration files are rolled back to avoid partial updates. Use `--backup-dir` if you want explicit backup snapshots for audit/manual recovery. Use `--report-file` to keep a machine-readable migration artifact.
 
+Migration reports now include envelope metadata: `reportKind`, `schemaVersion`, `generatedAt`, and `tool` (`name` / `version`). This metadata helps restore tooling validate report compatibility.
+
 ### Restore options
 
 | Flag                  | Description                                                       |
@@ -144,6 +146,8 @@ When writing files, migration uses a transactional strategy by default: if a lat
 | `--strict`            | Fail when any backup file in the report is missing.               |
 | `--json`              | Print restore summary as JSON.                                    |
 
+`tw-patch restore` validates report schema metadata when available. Reports with unsupported `reportKind` or newer `schemaVersion` are rejected to avoid unsafe restores. Legacy reports without metadata are still supported.
+
 ### Token report options
 
 | Flag                                   | Description                                                                               |

packages/tailwindcss-patch/src/cli/migrate-config.ts

@@ -5,6 +5,7 @@ import generate from '@babel/generator'
 import * as t from '@babel/types'
 import fs from 'fs-extra'
 import path from 'pathe'
+import { pkgName, pkgVersion } from '../constants'
 
 export const DEFAULT_CONFIG_FILENAMES = [
   'tailwindcss-patch.config.ts',
@@ -30,6 +31,8 @@ const DEFAULT_WORKSPACE_IGNORED_DIRS = new Set([
   'tmp',
 ])
 const DEFAULT_WORKSPACE_MAX_DEPTH = 6
+const MIGRATION_REPORT_KIND = 'tw-patch-migrate-report'
+const MIGRATION_REPORT_SCHEMA_VERSION = 1
 
 const ROOT_LEGACY_KEYS = ['cwd', 'overwrite', 'tailwind', 'features', 'output', 'applyPatches'] as const
 
@@ -51,6 +54,13 @@ export interface ConfigFileMigrationEntry {
 }
 
 export interface ConfigFileMigrationReport {
+  reportKind: typeof MIGRATION_REPORT_KIND
+  schemaVersion: typeof MIGRATION_REPORT_SCHEMA_VERSION
+  generatedAt: string
+  tool: {
+    name: string
+    version: string
+  }
   cwd: string
   dryRun: boolean
   rollbackOnError: boolean
@@ -86,6 +96,7 @@ export interface RestoreConfigFilesOptions {
 export interface RestoreConfigFilesResult {
   cwd: string
   reportFile: string
+  reportSchemaVersion?: number
   dryRun: boolean
   strict: boolean
   scannedEntries: number
@@ -620,6 +631,13 @@ export async function migrateConfigFiles(options: MigrateConfigFilesOptions): Pr
   }
 
   return {
+    reportKind: MIGRATION_REPORT_KIND,
+    schemaVersion: MIGRATION_REPORT_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    tool: {
+      name: pkgName,
+      version: pkgVersion,
+    },
     cwd,
     dryRun,
     rollbackOnError,
@@ -640,7 +658,22 @@ export async function restoreConfigFiles(options: RestoreConfigFilesOptions): Pr
   const strict = options.strict ?? false
   const reportFile = path.resolve(cwd, options.reportFile)
 
-  const report = await fs.readJSON(reportFile) as { entries?: Array<{ file?: string, backupFile?: string }> }
+  const report = await fs.readJSON(reportFile) as {
+    reportKind?: string
+    schemaVersion?: number
+    entries?: Array<{ file?: string, backupFile?: string }>
+  }
+  if (report.reportKind !== undefined && report.reportKind !== MIGRATION_REPORT_KIND) {
+    throw new Error(`Unsupported report kind "${report.reportKind}" in ${reportFile}.`)
+  }
+  if (
+    report.schemaVersion !== undefined
+    && (!Number.isInteger(report.schemaVersion) || report.schemaVersion > MIGRATION_REPORT_SCHEMA_VERSION)
+  ) {
+    throw new Error(
+      `Unsupported report schema version "${String(report.schemaVersion)}" in ${reportFile}. Current supported version is ${MIGRATION_REPORT_SCHEMA_VERSION}.`,
+    )
+  }
   const entries = Array.isArray(report.entries) ? report.entries : []
 
   let scannedEntries = 0
@@ -685,6 +718,7 @@ export async function restoreConfigFiles(options: RestoreConfigFilesOptions): Pr
   return {
     cwd,
     reportFile,
+    ...(report.schemaVersion === undefined ? {} : { reportSchemaVersion: report.schemaVersion }),
     dryRun,
     strict,
     scannedEntries,

packages/tailwindcss-patch/test/cli.migrate-config.test.ts

@@ -102,6 +102,10 @@ describe('migrateConfigFiles', () => {
         dryRun: true,
       })
 
+      expect(report.reportKind).toBe('tw-patch-migrate-report')
+      expect(report.schemaVersion).toBe(1)
+      expect(report.generatedAt).toBeTypeOf('string')
+      expect(report.tool.name).toBe('tailwindcss-patch')
       expect(report.scannedFiles).toBe(1)
       expect(report.changedFiles).toBe(1)
       expect(report.writtenFiles).toBe(0)
@@ -300,6 +304,7 @@ describe('restoreConfigFiles', () => {
         reportFile: '.tw-patch/migrate-report.json',
       })
 
+      expect(result.reportSchemaVersion).toBeUndefined()
       expect(result.restoredFiles).toBe(1)
       expect(result.missingBackups).toBe(0)
       const restored = await fs.readFile(target, 'utf8')
@@ -360,4 +365,43 @@ describe('restoreConfigFiles', () => {
       await fs.remove(cwd)
     }
   })
+
+  it('throws on unsupported report schema versions', async () => {
+    const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'tw-patch-restore-schema-'))
+    const reportPath = path.resolve(cwd, '.tw-patch/migrate-report.json')
+    try {
+      await fs.outputJSON(reportPath, {
+        reportKind: 'tw-patch-migrate-report',
+        schemaVersion: 999,
+        entries: [],
+      }, { spaces: 2 })
+
+      await expect(restoreConfigFiles({
+        cwd,
+        reportFile: '.tw-patch/migrate-report.json',
+      })).rejects.toThrow('Unsupported report schema version')
+    }
+    finally {
+      await fs.remove(cwd)
+    }
+  })
+
+  it('throws on unsupported report kind', async () => {
+    const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'tw-patch-restore-kind-'))
+    const reportPath = path.resolve(cwd, '.tw-patch/migrate-report.json')
+    try {
+      await fs.outputJSON(reportPath, {
+        reportKind: 'unknown-report',
+        entries: [],
+      }, { spaces: 2 })
+
+      await expect(restoreConfigFiles({
+        cwd,
+        reportFile: '.tw-patch/migrate-report.json',
+      })).rejects.toThrow('Unsupported report kind')
+    }
+    finally {
+      await fs.remove(cwd)
+    }
+  })
 })