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

package/src/patching/patch-runner.ts

@@ -0,0 +1,46 @@
+import type { PackageInfo } from 'local-pkg'
+import type { NormalizedTailwindCssPatchOptions } from '../options/types'
+import { applyExposeContextPatch } from './operations/export-context'
+import { applyExtendLengthUnitsPatchV3, applyExtendLengthUnitsPatchV4 } from './operations/extend-length-units'
+
+export interface PatchRunnerContext {
+  packageInfo: PackageInfo
+  options: NormalizedTailwindCssPatchOptions
+  majorVersion: 2 | 3 | 4
+}
+
+export interface PatchRunnerResult {
+  exposeContext?: ReturnType<typeof applyExposeContextPatch>
+  extendLengthUnits?: ReturnType<typeof applyExtendLengthUnitsPatchV3> | ReturnType<typeof applyExtendLengthUnitsPatchV4>
+}
+
+export function applyTailwindPatches(context: PatchRunnerContext): PatchRunnerResult {
+  const { packageInfo, options, majorVersion } = context
+  const results: PatchRunnerResult = {}
+
+  if (options.features.exposeContext.enabled && (majorVersion === 2 || majorVersion === 3)) {
+    results.exposeContext = applyExposeContextPatch({
+      rootDir: packageInfo.rootPath,
+      refProperty: options.features.exposeContext.refProperty,
+      overwrite: options.overwrite,
+      majorVersion,
+    })
+  }
+
+  if (options.features.extendLengthUnits?.enabled) {
+    if (majorVersion === 3) {
+      results.extendLengthUnits = applyExtendLengthUnitsPatchV3(
+        packageInfo.rootPath,
+        options.features.extendLengthUnits,
+      )
+    }
+    else if (majorVersion === 4) {
+      results.extendLengthUnits = applyExtendLengthUnitsPatchV4(
+        packageInfo.rootPath,
+        options.features.extendLengthUnits,
+      )
+    }
+  }
+
+  return results
+}

package/src/patching/status.ts

@@ -0,0 +1,262 @@
+import type { PackageInfo } from 'local-pkg'
+import type {
+  NormalizedExtendLengthUnitsOptions,
+  NormalizedTailwindCssPatchOptions,
+} from '../options/types'
+import type { PatchStatusEntry, PatchStatusReport } from '../types'
+import * as t from '@babel/types'
+import fs from 'fs-extra'
+import path from 'pathe'
+
+import { parse, traverse } from '../babel'
+import { transformPostcssPluginV2, transformProcessTailwindFeaturesReturnContextV2 } from './operations/export-context/postcss-v2'
+import { transformPostcssPlugin, transformProcessTailwindFeaturesReturnContext } from './operations/export-context/postcss-v3'
+import { applyExtendLengthUnitsPatchV4 } from './operations/extend-length-units'
+
+interface PatchStatusContext {
+  packageInfo: PackageInfo
+  options: NormalizedTailwindCssPatchOptions
+  majorVersion: 2 | 3 | 4
+}
+
+function inspectLengthUnitsArray(
+  content: string,
+  variableName: string,
+  units: string[],
+) {
+  const ast = parse(content)
+  let found = false
+  let missingUnits: string[] = []
+
+  traverse(ast, {
+    Identifier(path) {
+      if (
+        path.node.name === variableName
+        && t.isVariableDeclarator(path.parent)
+        && t.isArrayExpression(path.parent.init)
+      ) {
+        found = true
+        const existing = new Set(
+          path.parent.init.elements
+            .map(element => (t.isStringLiteral(element) ? element.value : undefined))
+            .filter(Boolean) as string[],
+        )
+        missingUnits = units.filter(unit => !existing.has(unit))
+        path.stop()
+      }
+    },
+  })
+
+  return {
+    found,
+    missingUnits,
+  }
+}
+
+function checkExposeContextPatch(context: PatchStatusContext): PatchStatusEntry {
+  const { packageInfo, options, majorVersion } = context
+  const refProperty = options.features.exposeContext.refProperty
+
+  if (!options.features.exposeContext.enabled) {
+    return {
+      name: 'exposeContext',
+      status: 'skipped',
+      reason: 'exposeContext feature disabled',
+      files: [],
+    }
+  }
+
+  if (majorVersion === 4) {
+    return {
+      name: 'exposeContext',
+      status: 'unsupported',
+      reason: 'Context export patch is only required for Tailwind v2/v3',
+      files: [],
+    }
+  }
+
+  const checks: Array<{ relative: string, exists: boolean, patched: boolean }> = []
+
+  function inspectFile(
+    relative: string,
+    transform: (content: string) => { hasPatched: boolean },
+  ) {
+    const filePath = path.resolve(packageInfo.rootPath, relative)
+    if (!fs.existsSync(filePath)) {
+      checks.push({ relative, exists: false, patched: false })
+      return
+    }
+    const content = fs.readFileSync(filePath, 'utf8')
+    const { hasPatched } = transform(content)
+    checks.push({
+      relative,
+      exists: true,
+      patched: hasPatched,
+    })
+  }
+
+  if (majorVersion === 3) {
+    inspectFile('lib/processTailwindFeatures.js', transformProcessTailwindFeaturesReturnContext)
+    const pluginCandidates = ['lib/plugin.js', 'lib/index.js']
+    const pluginRelative = pluginCandidates.find(candidate => fs.existsSync(path.resolve(packageInfo.rootPath, candidate)))
+    if (pluginRelative) {
+      inspectFile(pluginRelative, content => transformPostcssPlugin(content, { refProperty }))
+    }
+    else {
+      checks.push({ relative: 'lib/plugin.js', exists: false, patched: false })
+    }
+  }
+  else {
+    inspectFile('lib/jit/processTailwindFeatures.js', transformProcessTailwindFeaturesReturnContextV2)
+    inspectFile('lib/jit/index.js', content => transformPostcssPluginV2(content, { refProperty }))
+  }
+
+  const files = checks.filter(check => check.exists).map(check => check.relative)
+  const missingFiles = checks.filter(check => !check.exists)
+  const unpatchedFiles = checks.filter(check => check.exists && !check.patched)
+
+  const reasons: string[] = []
+  if (missingFiles.length) {
+    reasons.push(`missing files: ${missingFiles.map(item => item.relative).join(', ')}`)
+  }
+  if (unpatchedFiles.length) {
+    reasons.push(`unpatched files: ${unpatchedFiles.map(item => item.relative).join(', ')}`)
+  }
+
+  return {
+    name: 'exposeContext',
+    status: reasons.length ? 'not-applied' : 'applied',
+    ...(reasons.length ? { reason: reasons.join('; ') } : {}),
+    files,
+  }
+}
+
+function checkExtendLengthUnitsV3(rootDir: string, options: NormalizedExtendLengthUnitsOptions): PatchStatusEntry {
+  const lengthUnitsFilePath = options.lengthUnitsFilePath ?? 'lib/util/dataTypes.js'
+  const variableName = options.variableName ?? 'lengthUnits'
+  const target = path.resolve(rootDir, lengthUnitsFilePath)
+  const files = fs.existsSync(target) ? [path.relative(rootDir, target)] : []
+
+  if (!fs.existsSync(target)) {
+    return {
+      name: 'extendLengthUnits',
+      status: 'not-applied',
+      reason: `missing ${lengthUnitsFilePath}`,
+      files,
+    }
+  }
+
+  const content = fs.readFileSync(target, 'utf8')
+  const { found, missingUnits } = inspectLengthUnitsArray(content, variableName, options.units)
+
+  if (!found) {
+    return {
+      name: 'extendLengthUnits',
+      status: 'not-applied',
+      reason: `could not locate ${variableName} array in ${lengthUnitsFilePath}`,
+      files,
+    }
+  }
+
+  if (missingUnits.length) {
+    return {
+      name: 'extendLengthUnits',
+      status: 'not-applied',
+      reason: `missing units: ${missingUnits.join(', ')}`,
+      files,
+    }
+  }
+
+  return {
+    name: 'extendLengthUnits',
+    status: 'applied',
+    files,
+  }
+}
+
+function checkExtendLengthUnitsV4(rootDir: string, options: NormalizedExtendLengthUnitsOptions): PatchStatusEntry {
+  const distDir = path.resolve(rootDir, 'dist')
+  if (!fs.existsSync(distDir)) {
+    return {
+      name: 'extendLengthUnits',
+      status: 'not-applied',
+      reason: 'dist directory not found for Tailwind v4 package',
+      files: [],
+    }
+  }
+
+  const result = applyExtendLengthUnitsPatchV4(rootDir, {
+    ...options,
+    enabled: true,
+    overwrite: false,
+  })
+
+  if (result.files.length === 0) {
+    return {
+      name: 'extendLengthUnits',
+      status: 'not-applied',
+      reason: 'no bundle chunks matched the length unit pattern',
+      files: [],
+    }
+  }
+
+  const files = result.files.map(file => path.relative(rootDir, file.file))
+  const pending = result.files.filter(file => !file.hasPatched)
+  if (pending.length) {
+    return {
+      name: 'extendLengthUnits',
+      status: 'not-applied',
+      reason: `missing units in ${pending.length} bundle${pending.length > 1 ? 's' : ''}`,
+      files: pending.map(file => path.relative(rootDir, file.file)),
+    }
+  }
+
+  return {
+    name: 'extendLengthUnits',
+    status: 'applied',
+    files,
+  }
+}
+
+function checkExtendLengthUnitsPatch(context: PatchStatusContext): PatchStatusEntry {
+  const { packageInfo, options, majorVersion } = context
+
+  if (!options.features.extendLengthUnits) {
+    return {
+      name: 'extendLengthUnits',
+      status: 'skipped',
+      reason: 'extendLengthUnits feature disabled',
+      files: [],
+    }
+  }
+
+  if (majorVersion === 2) {
+    return {
+      name: 'extendLengthUnits',
+      status: 'unsupported',
+      reason: 'length unit extension is only applied for Tailwind v3/v4',
+      files: [],
+    }
+  }
+
+  if (majorVersion === 3) {
+    return checkExtendLengthUnitsV3(packageInfo.rootPath, options.features.extendLengthUnits)
+  }
+
+  return checkExtendLengthUnitsV4(packageInfo.rootPath, options.features.extendLengthUnits)
+}
+
+export function getPatchStatusReport(context: PatchStatusContext): PatchStatusReport {
+  return {
+    package: {
+      name: context.packageInfo.name ?? context.packageInfo.packageJson?.name,
+      version: context.packageInfo.version,
+      root: context.packageInfo.rootPath,
+    },
+    majorVersion: context.majorVersion,
+    entries: [
+      checkExposeContextPatch(context),
+      checkExtendLengthUnitsPatch(context),
+    ],
+  }
+}

package/src/runtime/class-collector.ts

@@ -0,0 +1,105 @@
+import type { NormalizedTailwindCssPatchOptions } from '../options/types'
+import type { TailwindcssRuntimeContext } from '../types'
+import process from 'node:process'
+import fs from 'fs-extra'
+import path from 'pathe'
+import { extractValidCandidates } from '../extraction/candidate-extractor'
+import { isObject } from '../utils'
+
+export function collectClassesFromContexts(
+  contexts: TailwindcssRuntimeContext[],
+  filter: (className: string) => boolean,
+) {
+  const set = new Set<string>()
+  for (const context of contexts) {
+    if (!isObject(context) || !context.classCache) {
+      continue
+    }
+
+    for (const key of context.classCache.keys()) {
+      const className = key.toString()
+      if (filter(className)) {
+        set.add(className)
+      }
+    }
+  }
+  return set
+}
+
+export async function collectClassesFromTailwindV4(
+  options: NormalizedTailwindCssPatchOptions,
+) {
+  const set = new Set<string>()
+  const v4Options = options.tailwind.v4
+  if (!v4Options) {
+    return set
+  }
+
+  const toAbsolute = (value: string | undefined) => {
+    if (!value) {
+      return undefined
+    }
+    return path.isAbsolute(value) ? value : path.resolve(options.projectRoot, value)
+  }
+  const resolvedConfiguredBase = toAbsolute(v4Options.configuredBase)
+  const resolvedDefaultBase = toAbsolute(v4Options.base) ?? process.cwd()
+  const resolveSources = (base: string) => {
+    if (!v4Options.sources?.length) {
+      return undefined
+    }
+
+    return v4Options.sources.map(source => ({
+      base: source.base ?? base,
+      pattern: source.pattern,
+      negated: source.negated,
+    }))
+  }
+
+  if (v4Options.cssEntries.length > 0) {
+    for (const entry of v4Options.cssEntries) {
+      const filePath = path.isAbsolute(entry) ? entry : path.resolve(options.projectRoot, entry)
+      if (!(await fs.pathExists(filePath))) {
+        continue
+      }
+      const css = await fs.readFile(filePath, 'utf8')
+      const entryDir = path.dirname(filePath)
+      const designSystemBases = resolvedConfiguredBase && resolvedConfiguredBase !== entryDir
+        ? [entryDir, resolvedConfiguredBase]
+        : [entryDir]
+      const sourcesBase = resolvedConfiguredBase ?? entryDir
+      const sources = resolveSources(sourcesBase)
+      const firstBase = designSystemBases[0] ?? entryDir
+      const extractOptions = {
+        cwd: options.projectRoot,
+        base: firstBase,
+        baseFallbacks: designSystemBases.slice(1),
+        css,
+        ...(sources === undefined ? {} : { sources }),
+      }
+      const candidates = await extractValidCandidates(extractOptions)
+      for (const candidate of candidates) {
+        if (options.filter(candidate)) {
+          set.add(candidate)
+        }
+      }
+    }
+  }
+  else {
+    const baseForCss = resolvedConfiguredBase ?? resolvedDefaultBase
+    const sources = resolveSources(baseForCss)
+    const extractOptions = {
+      cwd: options.projectRoot,
+      base: baseForCss,
+      ...(v4Options.css === undefined ? {} : { css: v4Options.css }),
+      ...(sources === undefined ? {} : { sources }),
+    }
+    const candidates = await extractValidCandidates(extractOptions)
+    for (const candidate of candidates) {
+      if (options.filter(candidate)) {
+        set.add(candidate)
+      }
+    }
+  }
+
+  return set
+}

package/src/runtime/collector.ts

@@ -0,0 +1,148 @@
+import type { PackageInfo } from 'local-pkg'
+import type { NormalizedTailwindCssPatchOptions } from '../config'
+import type { PatchStatusReport, TailwindcssRuntimeContext } from '../types'
+import type { applyTailwindPatches } from '../install/patch-runner'
+import { collectClassesFromContexts, collectClassesFromTailwindV4 } from '../install/class-collector'
+import { loadRuntimeContexts } from '../install/context-registry'
+import { applyTailwindPatches as runPatch } from '../install/patch-runner'
+import { runTailwindBuild } from '../install/process-tailwindcss'
+import { getPatchStatusReport } from '../install/status'
+
+export type TailwindMajorVersion = 2 | 3 | 4
+export type PatchResult = ReturnType<typeof applyTailwindPatches>
+
+export interface TailwindCollector {
+  patch(): Promise<PatchResult>
+  getPatchStatus(): Promise<PatchStatusReport>
+  collectClassSet(): Promise<Set<string>>
+  getContexts(): TailwindcssRuntimeContext[]
+  getPatchSnapshot(): string
+  runTailwindBuildIfNeeded?(): Promise<void>
+}
+
+function resolveTailwindExecutionOptions(
+  normalized: NormalizedTailwindCssPatchOptions,
+  majorVersion: 2 | 3,
+) {
+  const base = normalized.tailwind
+  if (majorVersion === 2 && base.v2) {
+    return {
+      cwd: base.v2.cwd ?? base.cwd ?? normalized.projectRoot,
+      config: base.v2.config ?? base.config,
+      postcssPlugin: base.v2.postcssPlugin ?? base.postcssPlugin,
+    }
+  }
+
+  if (majorVersion === 3 && base.v3) {
+    return {
+      cwd: base.v3.cwd ?? base.cwd ?? normalized.projectRoot,
+      config: base.v3.config ?? base.config,
+      postcssPlugin: base.v3.postcssPlugin ?? base.postcssPlugin,
+    }
+  }
+
+  return {
+    cwd: base.cwd ?? normalized.projectRoot,
+    config: base.config,
+    postcssPlugin: base.postcssPlugin,
+  }
+}
+
+abstract class BaseCollector implements TailwindCollector {
+  constructor(
+    protected readonly packageInfo: PackageInfo,
+    protected readonly options: NormalizedTailwindCssPatchOptions,
+    protected readonly majorVersion: TailwindMajorVersion,
+  ) {}
+
+  async patch() {
+    return runPatch({
+      packageInfo: this.packageInfo,
+      options: this.options,
+      majorVersion: this.majorVersion,
+    })
+  }
+
+  async getPatchStatus() {
+    return getPatchStatusReport({
+      packageInfo: this.packageInfo,
+      options: this.options,
+      majorVersion: this.majorVersion,
+    })
+  }
+
+  getContexts() {
+    return loadRuntimeContexts(
+      this.packageInfo,
+      this.majorVersion,
+      this.options.features.exposeContext.refProperty,
+    )
+  }
+
+  abstract collectClassSet(): Promise<Set<string>>
+  abstract getPatchSnapshot(): string
+}
+
+export class RuntimeCollector extends BaseCollector {
+  private inFlightBuild: Promise<void> | undefined
+
+  constructor(
+    packageInfo: PackageInfo,
+    options: NormalizedTailwindCssPatchOptions,
+    majorVersion: 2 | 3,
+    private readonly snapshotFactory: () => string,
+  ) {
+    super(packageInfo, options, majorVersion)
+  }
+
+  async collectClassSet() {
+    const contexts = this.getContexts()
+    return collectClassesFromContexts(contexts, this.options.filter)
+  }
+
+  getPatchSnapshot() {
+    return this.snapshotFactory()
+  }
+
+  async runTailwindBuildIfNeeded() {
+    if (this.inFlightBuild) {
+      return this.inFlightBuild
+    }
+
+    const executionOptions = resolveTailwindExecutionOptions(this.options, this.majorVersion as 2 | 3)
+    const buildOptions = {
+      cwd: executionOptions.cwd,
+      majorVersion: this.majorVersion as 2 | 3,
+      ...(executionOptions.config === undefined ? {} : { config: executionOptions.config }),
+      ...(executionOptions.postcssPlugin === undefined ? {} : { postcssPlugin: executionOptions.postcssPlugin }),
+    }
+    this.inFlightBuild = runTailwindBuild(buildOptions).then(() => undefined)
+    try {
+      await this.inFlightBuild
+    }
+    finally {
+      this.inFlightBuild = undefined
+    }
+  }
+}
+
+export class TailwindV4Collector extends BaseCollector {
+  constructor(
+    packageInfo: PackageInfo,
+    options: NormalizedTailwindCssPatchOptions,
+    snapshotFactory: () => string,
+  ) {
+    super(packageInfo, options, 4)
+    this.snapshotFactory = snapshotFactory
+  }
+
+  private readonly snapshotFactory: () => string
+
+  async collectClassSet() {
+    return collectClassesFromTailwindV4(this.options)
+  }
+
+  getPatchSnapshot() {
+    return this.snapshotFactory()
+  }
+}

package/src/runtime/context-registry.ts

@@ -0,0 +1,65 @@
+import type { PackageInfo } from 'local-pkg'
+import type { TailwindcssRuntimeContext } from '../types'
+import { createRequire } from 'node:module'
+import fs from 'fs-extra'
+import path from 'pathe'
+
+const require = createRequire(import.meta.url)
+
+function resolveRuntimeEntry(packageInfo: PackageInfo, majorVersion: 2 | 3): string | undefined {
+  const root = packageInfo.rootPath
+
+  if (majorVersion === 2) {
+    const jitIndex = path.join(root, 'lib/jit/index.js')
+    if (fs.existsSync(jitIndex)) {
+      return jitIndex
+    }
+  }
+  else if (majorVersion === 3) {
+    const plugin = path.join(root, 'lib/plugin.js')
+    const index = path.join(root, 'lib/index.js')
+    if (fs.existsSync(plugin)) {
+      return plugin
+    }
+    if (fs.existsSync(index)) {
+      return index
+    }
+  }
+
+  return undefined
+}
+
+export function loadRuntimeContexts(
+  packageInfo: PackageInfo,
+  majorVersion: 2 | 3 | 4,
+  refProperty: string,
+): TailwindcssRuntimeContext[] {
+  if (majorVersion === 4) {
+    return []
+  }
+
+  const entry = resolveRuntimeEntry(packageInfo, majorVersion)
+  if (!entry) {
+    return []
+  }
+
+  const moduleExports = require(entry) as Record<string, any>
+  if (!moduleExports) {
+    return []
+  }
+
+  const ref = moduleExports[refProperty]
+  if (!ref) {
+    return []
+  }
+
+  if (Array.isArray(ref)) {
+    return ref as TailwindcssRuntimeContext[]
+  }
+
+  if (typeof ref === 'object' && Array.isArray(ref.value)) {
+    return ref.value as TailwindcssRuntimeContext[]
+  }
+
+  return []
+}