tailwindcss-patch 9.0.0-alpha.1 → 9.0.0-alpha.2

package/src/commands/migrate-config.ts

@@ -0,0 +1,104 @@
+import type { MigrationWrittenEntry } from './migration-file-executor'
+import type {
+  ConfigFileMigrationReport,
+  MigrateConfigFilesOptions,
+  RestoreConfigFilesOptions,
+  RestoreConfigFilesResult,
+} from './migration-types'
+import path from 'pathe'
+import { pkgName, pkgVersion } from '../constants'
+import {
+  buildMigrationReport,
+  collectMigrationExecutionResult,
+  createMigrationAggregationState,
+} from './migration-aggregation'
+import { executeMigrationFile, restoreConfigEntries } from './migration-file-executor'
+
+import { loadMigrationReportForRestore } from './migration-report-loader'
+import { resolveMigrationTargetFiles } from './migration-target-resolver'
+
+export { MIGRATION_REPORT_KIND, MIGRATION_REPORT_SCHEMA_VERSION } from './migration-report'
+export { migrateConfigSource } from './migration-source'
+export type { ConfigSourceMigrationResult } from './migration-source'
+export { DEFAULT_CONFIG_FILENAMES } from './migration-target-files'
+export type {
+  ConfigFileMigrationEntry,
+  ConfigFileMigrationReport,
+  MigrateConfigFilesOptions,
+  RestoreConfigFilesOptions,
+  RestoreConfigFilesResult,
+} from './migration-types'
+
+export async function migrateConfigFiles(options: MigrateConfigFilesOptions): Promise<ConfigFileMigrationReport> {
+  const cwd = path.resolve(options.cwd)
+  const dryRun = options.dryRun ?? false
+  const rollbackOnError = options.rollbackOnError ?? true
+  const backupDirectory = options.backupDir ? path.resolve(cwd, options.backupDir) : undefined
+  const targetFiles = await resolveMigrationTargetFiles({
+    cwd,
+    files: options.files,
+    workspace: options.workspace,
+    maxDepth: options.maxDepth,
+    include: options.include,
+    exclude: options.exclude,
+  })
+  const aggregation = createMigrationAggregationState()
+  const wroteEntries: MigrationWrittenEntry[] = []
+
+  for (const file of targetFiles) {
+    const result = await executeMigrationFile({
+      cwd,
+      file,
+      dryRun,
+      rollbackOnError,
+      wroteEntries,
+      ...(backupDirectory ? { backupDirectory } : {}),
+    })
+    collectMigrationExecutionResult(aggregation, result)
+  }
+
+  return buildMigrationReport(aggregation, {
+    cwd,
+    dryRun,
+    rollbackOnError,
+    ...(backupDirectory ? { backupDirectory } : {}),
+    toolName: pkgName,
+    toolVersion: pkgVersion,
+  })
+}
+
+export async function restoreConfigFiles(options: RestoreConfigFilesOptions): Promise<RestoreConfigFilesResult> {
+  const cwd = path.resolve(options.cwd)
+  const dryRun = options.dryRun ?? false
+  const strict = options.strict ?? false
+  const reportFile = path.resolve(cwd, options.reportFile)
+
+  const report = await loadMigrationReportForRestore(reportFile)
+  const {
+    scannedEntries,
+    restorableEntries,
+    restoredFiles,
+    missingBackups,
+    skippedEntries,
+    restored,
+  } = await restoreConfigEntries(report.entries, dryRun)
+
+  if (strict && missingBackups > 0) {
+    throw new Error(`Restore failed: ${missingBackups} backup file(s) missing in report ${reportFile}.`)
+  }
+
+  return {
+    cwd,
+    reportFile,
+    ...(report.reportKind === undefined ? {} : { reportKind: report.reportKind }),
+    ...(report.schemaVersion === undefined ? {} : { reportSchemaVersion: report.schemaVersion }),
+    dryRun,
+    strict,
+    scannedEntries,
+    restorableEntries,
+    restoredFiles,
+    missingBackups,
+    skippedEntries,
+    restored,
+  }
+}

package/src/commands/migrate-handler.ts

@@ -0,0 +1,67 @@
+import type { TailwindcssPatchCommandContext } from './types'
+
+import logger from '../logger'
+import { migrateConfigFiles } from './migrate-config'
+import { resolveMigrateCommandArgs } from './migration-args'
+import {
+  createMigrationCheckFailureError,
+  logMigrationEntries,
+  logMigrationReportAsJson,
+  logMigrationSummary,
+  logNoMigrationConfigFilesWarning,
+  writeMigrationReportFile,
+} from './migration-output'
+
+export async function migrateCommandDefaultHandler(ctx: TailwindcssPatchCommandContext<'migrate'>) {
+  const { args } = ctx
+  const {
+    include,
+    exclude,
+    maxDepth,
+    checkMode,
+    dryRun,
+    hasInvalidMaxDepth,
+  } = resolveMigrateCommandArgs(args)
+
+  if (args.workspace && hasInvalidMaxDepth) {
+    logger.warn(`Invalid --max-depth value "${String(args.maxDepth)}", fallback to default depth.`)
+  }
+  const report = await migrateConfigFiles({
+    cwd: ctx.cwd,
+    dryRun,
+    ...(args.config ? { files: [args.config] } : {}),
+    ...(args.workspace ? { workspace: true } : {}),
+    ...(args.workspace && maxDepth !== undefined ? { maxDepth } : {}),
+    ...(args.backupDir ? { backupDir: args.backupDir } : {}),
+    ...(include ? { include } : {}),
+    ...(exclude ? { exclude } : {}),
+  })
+
+  if (args.reportFile) {
+    await writeMigrationReportFile(ctx.cwd, args.reportFile, report)
+  }
+
+  if (args.json) {
+    logMigrationReportAsJson(report)
+    if (checkMode && report.changedFiles > 0) {
+      throw createMigrationCheckFailureError(report.changedFiles)
+    }
+    if (report.scannedFiles === 0) {
+      logNoMigrationConfigFilesWarning()
+    }
+    return report
+  }
+
+  if (report.scannedFiles === 0) {
+    logNoMigrationConfigFilesWarning()
+    return report
+  }
+
+  logMigrationEntries(report, dryRun)
+  logMigrationSummary(report)
+
+  if (checkMode && report.changedFiles > 0) {
+    throw createMigrationCheckFailureError(report.changedFiles)
+  }
+  return report
+}

package/src/commands/migration-aggregation.ts

@@ -0,0 +1,100 @@
+import type { ExecuteMigrationFileResult } from './migration-file-executor'
+import type { ConfigFileMigrationEntry, ConfigFileMigrationReport } from './migration-types'
+import {
+  MIGRATION_REPORT_KIND,
+  MIGRATION_REPORT_SCHEMA_VERSION,
+} from './migration-report'
+
+export interface MigrationAggregationState {
+  scannedFiles: number
+  changedFiles: number
+  writtenFiles: number
+  backupsWritten: number
+  unchangedFiles: number
+  missingFiles: number
+  entries: ConfigFileMigrationEntry[]
+}
+
+export interface BuildMigrationReportContext {
+  cwd: string
+  dryRun: boolean
+  rollbackOnError: boolean
+  backupDirectory?: string
+  toolName: string
+  toolVersion: string
+  generatedAt?: string
+}
+
+export function createMigrationAggregationState(): MigrationAggregationState {
+  return {
+    scannedFiles: 0,
+    changedFiles: 0,
+    writtenFiles: 0,
+    backupsWritten: 0,
+    unchangedFiles: 0,
+    missingFiles: 0,
+    entries: [],
+  }
+}
+
+export function collectMigrationExecutionResult(
+  state: MigrationAggregationState,
+  result: ExecuteMigrationFileResult,
+) {
+  if (result.missing) {
+    state.missingFiles += 1
+    return
+  }
+
+  state.scannedFiles += 1
+  state.entries.push(result.entry)
+
+  if (result.changed) {
+    state.changedFiles += 1
+    if (result.wrote) {
+      state.writtenFiles += 1
+    }
+    if (result.backupWritten) {
+      state.backupsWritten += 1
+    }
+  }
+  else {
+    state.unchangedFiles += 1
+  }
+}
+
+export function buildMigrationReport(
+  state: MigrationAggregationState,
+  context: BuildMigrationReportContext,
+): ConfigFileMigrationReport {
+  const {
+    cwd,
+    dryRun,
+    rollbackOnError,
+    backupDirectory,
+    toolName,
+    toolVersion,
+    generatedAt = new Date().toISOString(),
+  } = context
+
+  return {
+    reportKind: MIGRATION_REPORT_KIND,
+    schemaVersion: MIGRATION_REPORT_SCHEMA_VERSION,
+    generatedAt,
+    tool: {
+      name: toolName,
+      version: toolVersion,
+    },
+    cwd,
+    dryRun,
+    rollbackOnError,
+    ...(backupDirectory ? { backupDirectory } : {}),
+    scannedFiles: state.scannedFiles,
+    changedFiles: state.changedFiles,
+    writtenFiles: state.writtenFiles,
+    backupsWritten: state.backupsWritten,
+    unchangedFiles: state.unchangedFiles,
+    missingFiles: state.missingFiles,
+    entries: state.entries,
+  }
+}

package/src/commands/migration-args.ts

@@ -0,0 +1,85 @@
+import type { TailwindcssPatchCommandArgMap } from './types'
+
+export interface ResolvedMigrateCommandArgs {
+  include: string[] | undefined
+  exclude: string[] | undefined
+  maxDepth: number | undefined
+  checkMode: boolean
+  dryRun: boolean
+  hasInvalidMaxDepth: boolean
+}
+
+export interface ResolvedRestoreCommandArgs {
+  reportFile: string
+  dryRun: boolean
+  strict: boolean
+}
+
+export interface ResolvedValidateCommandArgs {
+  reportFile: string
+  strict: boolean
+}
+
+export function normalizePatternArgs(value?: string | string[]) {
+  if (!value) {
+    return undefined
+  }
+  const raw = Array.isArray(value) ? value : [value]
+  const values = raw
+    .flatMap(item => item.split(','))
+    .map(item => item.trim())
+    .filter(Boolean)
+  return values.length > 0 ? values : undefined
+}
+
+function parseMaxDepth(value: TailwindcssPatchCommandArgMap['migrate']['maxDepth']) {
+  if (value === undefined) {
+    return {
+      maxDepth: undefined,
+      hasInvalidMaxDepth: false,
+    }
+  }
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return {
+      maxDepth: undefined,
+      hasInvalidMaxDepth: true,
+    }
+  }
+  return {
+    maxDepth: Math.floor(parsed),
+    hasInvalidMaxDepth: false,
+  }
+}
+
+export function resolveMigrateCommandArgs(args: TailwindcssPatchCommandArgMap['migrate']): ResolvedMigrateCommandArgs {
+  const include = normalizePatternArgs(args.include)
+  const exclude = normalizePatternArgs(args.exclude)
+  const { maxDepth, hasInvalidMaxDepth } = parseMaxDepth(args.maxDepth)
+  const checkMode = args.check ?? false
+  const dryRun = args.dryRun ?? checkMode
+
+  return {
+    include,
+    exclude,
+    maxDepth,
+    checkMode,
+    dryRun,
+    hasInvalidMaxDepth,
+  }
+}
+
+export function resolveRestoreCommandArgs(args: TailwindcssPatchCommandArgMap['restore']): ResolvedRestoreCommandArgs {
+  return {
+    reportFile: args.reportFile ?? '.tw-patch/migrate-report.json',
+    dryRun: args.dryRun ?? false,
+    strict: args.strict ?? false,
+  }
+}
+
+export function resolveValidateCommandArgs(args: TailwindcssPatchCommandArgMap['validate']): ResolvedValidateCommandArgs {
+  return {
+    reportFile: args.reportFile ?? '.tw-patch/migrate-report.json',
+    strict: args.strict ?? false,
+  }
+}

package/src/commands/migration-file-executor.ts

@@ -0,0 +1,189 @@
+import type { ConfigFileMigrationEntry } from './migration-types'
+import fs from 'fs-extra'
+
+import path from 'pathe'
+import { migrateConfigSource } from './migration-source'
+import { resolveBackupRelativePath } from './migration-target-files'
+
+export type MigrationExecutionEntry = ConfigFileMigrationEntry
+
+export interface MigrationWrittenEntry {
+  file: string
+  source: string
+  entry: MigrationExecutionEntry
+}
+
+export interface ExecuteMigrationFileOptions {
+  cwd: string
+  file: string
+  dryRun: boolean
+  rollbackOnError: boolean
+  backupDirectory?: string
+  wroteEntries: MigrationWrittenEntry[]
+}
+
+export type ExecuteMigrationFileResult
+  = | {
+    missing: true
+    changed: false
+    wrote: false
+    backupWritten: false
+  }
+  | {
+    missing: false
+    changed: boolean
+    wrote: boolean
+    backupWritten: boolean
+    entry: MigrationExecutionEntry
+  }
+
+export async function rollbackWrittenEntries(wroteEntries: MigrationWrittenEntry[]) {
+  let rollbackCount = 0
+  for (const written of [...wroteEntries].reverse()) {
+    try {
+      await fs.writeFile(written.file, written.source, 'utf8')
+      written.entry.written = false
+      written.entry.rolledBack = true
+      rollbackCount += 1
+    }
+    catch {
+      // Continue best-effort rollback to avoid leaving even more partial state.
+    }
+  }
+  return rollbackCount
+}
+
+export async function executeMigrationFile(options: ExecuteMigrationFileOptions): Promise<ExecuteMigrationFileResult> {
+  const {
+    cwd,
+    file,
+    dryRun,
+    rollbackOnError,
+    backupDirectory,
+    wroteEntries,
+  } = options
+
+  const exists = await fs.pathExists(file)
+  if (!exists) {
+    return {
+      missing: true,
+      changed: false,
+      wrote: false,
+      backupWritten: false,
+    }
+  }
+
+  const source = await fs.readFile(file, 'utf8')
+  const migrated = migrateConfigSource(source)
+  const entry: MigrationExecutionEntry = {
+    file,
+    changed: migrated.changed,
+    written: false,
+    rolledBack: false,
+    changes: migrated.changes,
+  }
+
+  if (!migrated.changed || dryRun) {
+    return {
+      missing: false,
+      changed: migrated.changed,
+      wrote: false,
+      backupWritten: false,
+      entry,
+    }
+  }
+
+  let backupWritten = false
+  try {
+    if (backupDirectory) {
+      const backupRelativePath = resolveBackupRelativePath(cwd, file)
+      const backupFile = path.resolve(backupDirectory, backupRelativePath)
+      await fs.ensureDir(path.dirname(backupFile))
+      await fs.writeFile(backupFile, source, 'utf8')
+      entry.backupFile = backupFile
+      backupWritten = true
+    }
+
+    await fs.writeFile(file, migrated.code, 'utf8')
+    entry.written = true
+    wroteEntries.push({ file, source, entry })
+
+    return {
+      missing: false,
+      changed: true,
+      wrote: true,
+      backupWritten,
+      entry,
+    }
+  }
+  catch (error) {
+    const rollbackCount = rollbackOnError && wroteEntries.length > 0
+      ? await rollbackWrittenEntries(wroteEntries)
+      : 0
+    const reason = error instanceof Error ? error.message : String(error)
+    const rollbackHint = rollbackOnError && rollbackCount > 0
+      ? ` Rolled back ${rollbackCount} previously written file(s).`
+      : ''
+    throw new Error(`Failed to write migrated config "${file}": ${reason}.${rollbackHint}`)
+  }
+}
+
+export interface RestoreReportEntry {
+  file?: string
+  backupFile?: string
+}
+
+export interface RestoreEntriesResult {
+  scannedEntries: number
+  restorableEntries: number
+  restoredFiles: number
+  missingBackups: number
+  skippedEntries: number
+  restored: string[]
+}
+
+export async function restoreConfigEntries(entries: RestoreReportEntry[], dryRun: boolean): Promise<RestoreEntriesResult> {
+  let scannedEntries = 0
+  let restorableEntries = 0
+  let restoredFiles = 0
+  let missingBackups = 0
+  let skippedEntries = 0
+  const restored: string[] = []
+
+  for (const entry of entries) {
+    scannedEntries += 1
+    const targetFile = entry.file ? path.resolve(entry.file) : undefined
+    const backupFile = entry.backupFile ? path.resolve(entry.backupFile) : undefined
+
+    if (!targetFile || !backupFile) {
+      skippedEntries += 1
+      continue
+    }
+
+    restorableEntries += 1
+
+    const backupExists = await fs.pathExists(backupFile)
+    if (!backupExists) {
+      missingBackups += 1
+      continue
+    }
+
+    if (!dryRun) {
+      const backupContent = await fs.readFile(backupFile, 'utf8')
+      await fs.ensureDir(path.dirname(targetFile))
+      await fs.writeFile(targetFile, backupContent, 'utf8')
+    }
+
+    restoredFiles += 1
+    restored.push(targetFile)
+  }
+
+  return {
+    scannedEntries,
+    restorableEntries,
+    restoredFiles,
+    missingBackups,
+    skippedEntries,
+    restored,
+  }
+}

package/src/commands/migration-output.ts

@@ -0,0 +1,115 @@
+import type { ConfigFileMigrationReport, RestoreConfigFilesResult } from './migration-types'
+import type { ValidateFailureSummary, ValidateJsonFailurePayload, ValidateJsonSuccessPayload } from './validate'
+
+import process from 'node:process'
+import fs from 'fs-extra'
+import path from 'pathe'
+import logger from '../logger'
+
+function formatPathForLog(file: string) {
+  return file.replace(process.cwd(), '.')
+}
+
+export function createMigrationCheckFailureError(changedFiles: number) {
+  return new Error(`Migration check failed: ${changedFiles} file(s) still need migration.`)
+}
+
+export async function writeMigrationReportFile(
+  cwd: string,
+  reportFile: string,
+  report: ConfigFileMigrationReport,
+) {
+  const reportPath = path.resolve(cwd, reportFile)
+  await fs.ensureDir(path.dirname(reportPath))
+  await fs.writeJSON(reportPath, report, { spaces: 2 })
+  logger.info(`Migration report written: ${formatPathForLog(reportPath)}`)
+}
+
+export function logMigrationReportAsJson(report: ConfigFileMigrationReport) {
+  logger.log(JSON.stringify(report, null, 2))
+}
+
+export function logNoMigrationConfigFilesWarning() {
+  logger.warn('No config files found for migration.')
+}
+
+export function logMigrationEntries(report: ConfigFileMigrationReport, dryRun: boolean) {
+  for (const entry of report.entries) {
+    const fileLabel = formatPathForLog(entry.file)
+    if (!entry.changed) {
+      logger.info(`No changes: ${fileLabel}`)
+      continue
+    }
+    if (dryRun) {
+      logger.info(`[dry-run] ${fileLabel}`)
+    }
+    else {
+      logger.success(`Migrated: ${fileLabel}`)
+    }
+    for (const change of entry.changes) {
+      logger.info(`  - ${change}`)
+    }
+    if (entry.backupFile) {
+      logger.info(`  - backup: ${formatPathForLog(entry.backupFile)}`)
+    }
+  }
+}
+
+export function logMigrationSummary(report: ConfigFileMigrationReport) {
+  logger.info(
+    `Migration summary: scanned=${report.scannedFiles}, changed=${report.changedFiles}, written=${report.writtenFiles}, backups=${report.backupsWritten}, missing=${report.missingFiles}, unchanged=${report.unchangedFiles}`,
+  )
+}
+
+export function logRestoreResultAsJson(result: RestoreConfigFilesResult) {
+  logger.log(JSON.stringify(result, null, 2))
+}
+
+export function logRestoreSummary(result: RestoreConfigFilesResult) {
+  logger.info(
+    `Restore summary: scanned=${result.scannedEntries}, restorable=${result.restorableEntries}, restored=${result.restoredFiles}, missingBackups=${result.missingBackups}, skipped=${result.skippedEntries}`,
+  )
+  if (result.restored.length > 0) {
+    const preview = result.restored.slice(0, 5)
+    for (const file of preview) {
+      logger.info(`  - ${formatPathForLog(file)}`)
+    }
+    if (result.restored.length > preview.length) {
+      logger.info(`  ...and ${result.restored.length - preview.length} more`)
+    }
+  }
+}
+
+export function logValidateSuccessAsJson(result: RestoreConfigFilesResult) {
+  const payload: ValidateJsonSuccessPayload = {
+    ok: true,
+    ...result,
+  }
+  logger.log(JSON.stringify(payload, null, 2))
+}
+
+export function logValidateSuccessSummary(result: RestoreConfigFilesResult) {
+  logger.success(
+    `Migration report validated: scanned=${result.scannedEntries}, restorable=${result.restorableEntries}, missingBackups=${result.missingBackups}, skipped=${result.skippedEntries}`,
+  )
+
+  if (result.reportKind || result.reportSchemaVersion !== undefined) {
+    const kind = result.reportKind ?? 'unknown'
+    const schema = result.reportSchemaVersion === undefined ? 'unknown' : String(result.reportSchemaVersion)
+    logger.info(`  metadata: kind=${kind}, schema=${schema}`)
+  }
+}
+
+export function logValidateFailureAsJson(summary: ValidateFailureSummary) {
+  const payload: ValidateJsonFailurePayload = {
+    ok: false,
+    reason: summary.reason,
+    exitCode: summary.exitCode,
+    message: summary.message,
+  }
+  logger.log(JSON.stringify(payload, null, 2))
+}
+
+export function logValidateFailureSummary(summary: ValidateFailureSummary) {
+  logger.error(`Validation failed [${summary.reason}] (exit ${summary.exitCode}): ${summary.message}`)
+}

package/src/commands/migration-report-loader.ts

@@ -0,0 +1,26 @@
+import type { RestoreReportEntry } from './migration-file-executor'
+
+import fs from 'fs-extra'
+import { assertMigrationReportCompatibility } from './migration-report'
+
+export interface LoadedMigrationReportForRestore {
+  reportKind?: string
+  schemaVersion?: number
+  entries: RestoreReportEntry[]
+}
+
+export async function loadMigrationReportForRestore(reportFile: string): Promise<LoadedMigrationReportForRestore> {
+  const report = await fs.readJSON(reportFile) as {
+    reportKind?: string
+    schemaVersion?: number
+    entries?: RestoreReportEntry[]
+  }
+
+  assertMigrationReportCompatibility(report, reportFile)
+
+  return {
+    ...(report.reportKind === undefined ? {} : { reportKind: report.reportKind }),
+    ...(report.schemaVersion === undefined ? {} : { schemaVersion: report.schemaVersion }),
+    entries: Array.isArray(report.entries) ? report.entries : [],
+  }
+}

package/src/commands/migration-report.ts

@@ -0,0 +1,21 @@
+export const MIGRATION_REPORT_KIND = 'tw-patch-migrate-report'
+export const MIGRATION_REPORT_SCHEMA_VERSION = 1
+
+export interface MigrationReportInput {
+  reportKind?: string
+  schemaVersion?: number
+}
+
+export function assertMigrationReportCompatibility(report: MigrationReportInput, reportFile: 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}.`,
+    )
+  }
+}