Fix overlapping CLI watch rebuilds

Author: michaelglass

integrations/cli/index.test.ts

@@ -409,6 +409,87 @@ describe.each([
     },
   )
 
+  test(
+    'watch mode keeps the newest CSS when a rebuild is already running',
+    {
+      fs: {
+        'package.json': json`{}`,
+        'pnpm-workspace.yaml': yaml` packages:
+            - project-a `,
+        'project-a/package.json': json`
+          {
+            "dependencies": {
+              "tailwindcss": "workspace:^",
+              "@tailwindcss/cli": "workspace:^"
+            }
+          }
+        `,
+        'project-a/index.html': html`<div class="from-a from-b"></div>`,
+        'project-a/src/index.css': css`@import 'tailwindcss/utilities';`,
+        'project-a/plugin-a.mjs': js`
+          import fs from 'node:fs/promises'
+
+          await fs.writeFile(new URL('./a-started', import.meta.url), 'started')
+          while (!(await fs.stat(new URL('./release-a', import.meta.url)).catch(() => null))) {
+            await new Promise((resolve) => setTimeout(resolve, 5))
+          }
+          await fs.appendFile(new URL('./build-order', import.meta.url), 'A')
+
+          export default function ({ addUtilities }) {
+            addUtilities({ '.from-a': { color: 'red' } })
+          }
+        `,
+        'project-a/plugin-b.mjs': js`
+          import fs from 'node:fs/promises'
+
+          await fs.appendFile(new URL('./build-order', import.meta.url), 'B')
+
+          export default function ({ addUtilities }) {
+            addUtilities({ '.from-b': { color: 'green' } })
+          }
+        `,
+      },
+    },
+    async ({ root, fs, spawn, expect }) => {
+      let process = await spawn(`${command} --input src/index.css --output dist/out.css --watch`, {
+        cwd: path.join(root, 'project-a'),
+      })
+      await process.onStderr((message) => message.includes('Done in'))
+
+      await fs.write(
+        'project-a/src/index.css',
+        css`
+          @import 'tailwindcss/utilities';
+          @plugin '../plugin-a.mjs';
+        `,
+      )
+      await retryAssertion(async () => {
+        expect(await fs.read('project-a/a-started')).toBe('started')
+      })
+
+      await fs.write(
+        'project-a/src/index.css',
+        css`
+          @import 'tailwindcss/utilities';
+          @plugin '../plugin-b.mjs';
+        `,
+      )
+
+      // Allow the native watcher to collect the newer edit while A is paused,
+      // then release A deterministically.
+      await new Promise((resolve) => setTimeout(resolve, 100))
+      await fs.write('project-a/release-a', 'release')
+
+      await process.onStderr((message) => message.includes('Done in'))
+      await process.onStderr((message) => message.includes('Done in'))
+
+      expect(await fs.read('project-a/build-order')).toBe('AB')
+      await fs.expectFileToContain('project-a/dist/out.css', [candidate`from-b`])
+      await fs.expectFileNotToContain('project-a/dist/out.css', [candidate`from-a`])
+    },
+    { skip: kind !== 'CLI' },
+  )
+
   test(
     "watch mode with unknown @source paths shouldn't crash on Windows",
     {

packages/@tailwindcss-cli/src/commands/build/index.test.ts

@@ -0,0 +1,126 @@
+import { expect, it } from 'vitest'
+import { serializeBatches } from '../../utils/serial-batches'
+import { createWatchers, filterChangedFiles } from './index'
+
+type WatchEvent = { type: 'create' | 'update' | 'delete'; path: string }
+type WatchCallback = (error: Error | null, events: WatchEvent[]) => Promise<void>
+
+function fakeWatcher() {
+  let callbacks: WatchCallback[] = []
+  return {
+    callbacks,
+    watcher: {
+      async subscribe(_directory: string, callback: WatchCallback) {
+        callbacks.push(callback)
+        return { unsubscribe() {} }
+      },
+    },
+  }
+}
+
+function nextTask() {
+  return new Promise((resolve) => setTimeout(resolve, 0))
+}
+
+it('removes duplicate output and map events from a coalesced batch', () => {
+  expect(
+    filterChangedFiles(
+      ['output.css', 'source.html', 'output.css', 'output.css.map'],
+      'output.css',
+      'output.css.map',
+    ),
+  ).toEqual(['source.html'])
+})
+
+it('uses one rebuild queue across watcher generations', async () => {
+  let releaseFirst!: () => void
+  let firstCanFinish = new Promise<void>((resolve) => (releaseFirst = resolve))
+  let calls: string[][] = []
+  let queue = serializeBatches<string>(async (files) => {
+    calls.push(files)
+    if (calls.length === 1) await firstCanFinish
+  })
+  let first = fakeWatcher()
+  let second = fakeWatcher()
+
+  let oldGeneration = await createWatchers(['/old'], async () => {}, queue, first.watcher)
+  await first.callbacks[0](null, [{ type: 'delete', path: 'old-change' }])
+  await nextTask()
+  expect(calls).toEqual([['old-change']])
+
+  let newGeneration = await createWatchers(['/new'], async () => {}, queue, second.watcher)
+  await second.callbacks[0](null, [{ type: 'delete', path: 'new-change' }])
+  await nextTask()
+  expect(calls).toEqual([['old-change']])
+
+  releaseFirst()
+  await queue.close()
+  expect(calls).toEqual([['old-change'], ['new-change']])
+
+  await Promise.all([oldGeneration.cleanup(), newGeneration.cleanup()])
+})
+
+it('buffers watcher events until the initial build finishes', async () => {
+  let finishInitialBuild!: () => void
+  let initialBuild = new Promise<void>((resolve) => (finishInitialBuild = resolve))
+  let calls: string[][] = []
+  let queue = serializeBatches<string>(async (files) => {
+    calls.push(files)
+  }, initialBuild)
+  let fake = fakeWatcher()
+  let generation = await createWatchers(['/watch'], async () => {}, queue, fake.watcher)
+
+  await fake.callbacks[0](null, [{ type: 'delete', path: 'early-change' }])
+  await nextTask()
+  expect(calls).toEqual([])
+
+  finishInitialBuild()
+  await queue.close()
+  expect(calls).toEqual([['early-change']])
+  await generation.cleanup()
+})
+
+it('flushes a collected event when shutdown cancels its debounce timer', async () => {
+  let calls: string[][] = []
+  let queue = serializeBatches<string>(async (files) => {
+    calls.push(files)
+  })
+  let fake = fakeWatcher()
+  let generation = await createWatchers(['/watch'], async () => {}, queue, fake.watcher)
+
+  await fake.callbacks[0](null, [{ type: 'delete', path: 'last-change' }])
+  await generation.cleanup()
+  await queue.close()
+
+  expect(calls).toEqual([['last-change']])
+})
+
+it('waits for an entered watcher callback before shutdown flushes changes', async () => {
+  let releaseLstat!: () => void
+  let lstatCanFinish = new Promise<void>((resolve) => (releaseLstat = resolve))
+  let calls: string[][] = []
+  let queue = serializeBatches<string>(async (files) => {
+    calls.push(files)
+  })
+  let fake = fakeWatcher()
+  let generation = await createWatchers(
+    ['/watch'],
+    async () => {},
+    queue,
+    fake.watcher,
+    async () => {
+      await lstatCanFinish
+      return { isFile: () => true, isSymbolicLink: () => false }
+    },
+  )
+
+  let callback = fake.callbacks[0](null, [{ type: 'update', path: 'delayed-change' }])
+  let cleanup = generation.cleanup()
+  await nextTask()
+  expect(calls).toEqual([])
+
+  releaseLstat()
+  await Promise.all([callback, cleanup])
+  await queue.close()
+  expect(calls).toEqual([['delayed-change']])
+})