@wular/pnext 0.0.24 → 0.1.1

package/src/css/postcss.ts

@@ -2,8 +2,17 @@
 // on the CSS worker thread (./worker.ts) rather than the event loop:
 // Tailwind v4's postcss plugin is synchronous CPU work — its oxide scan and
 // compile starved every concurrent request while it ran in-process.
+import { createHash } from 'node:crypto'
 import { createRequire } from 'node:module'
-import { existsSync, readFileSync } from 'node:fs'
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
 import { writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -30,10 +39,64 @@ interface PostcssProcessor {
 interface LoadedPostcss {
   processor: PostcssProcessor
   sources: string
+  partitionedTailwindScan: boolean
 }
 
 type PostcssPluginFactory = (options?: unknown) => unknown
 
+interface TailwindSource {
+  base: string
+  pattern: string
+  negated: boolean
+}
+
+interface TailwindScanner {
+  scan(): string[]
+  scanFiles(input: TailwindChangedContent[]): string[]
+  getCandidatesWithPositions(input: TailwindChangedContent): TailwindCandidatePosition[]
+  files: string[]
+  scannedFiles: string[]
+  globs: TailwindGlob[]
+  normalizedSources: TailwindGlob[]
+}
+
+interface TailwindChangedContent {
+  file?: string
+  content?: string
+  extension: string
+}
+
+interface TailwindCandidatePosition {
+  candidate: string
+  position: number
+}
+
+interface TailwindGlob {
+  base: string
+  pattern: string
+}
+
+type TailwindScannerConstructor = new (options: { sources?: TailwindSource[] }) => TailwindScanner
+
+interface TailwindScanRegistration {
+  root: string
+  cacheDir: string
+  versions: string
+}
+
+const tailwindScannerPatch = Symbol.for('pnext.tailwind-scanner-v1')
+const tailwindCandidateSchema = 1
+
+interface TailwindOxideModule {
+  Scanner: TailwindScannerConstructor
+  [tailwindScannerPatch]?: {
+    registrations: TailwindScanRegistration[]
+    Scanner: TailwindScannerConstructor
+  }
+}
+
+const warnedTailwindScannerVersions = new Set<string>()
+
 interface PostcssConfig {
   plugins?: Record<string, unknown> | unknown[]
 }
@@ -78,10 +141,10 @@ export async function runPostcss(
   const css = await readText(cssFile)
   // The scan directives go last so they don't shift the line numbers plugins
   // report against the real source; `@source` is order-independent to Tailwind.
-  const result = await loaded.processor.process(css + keptExclusions(loaded.sources, css, from), {
-    from,
-    to: cssFile,
-  })
+  const result = await loaded.processor.process(
+    css + keptExclusions(loaded.sources, css, from, loaded.partitionedTailwindScan),
+    { from, to: cssFile },
+  )
   await writeFile(cssFile, result.css)
 }
 
@@ -91,7 +154,11 @@ async function createPostcssProcessor(root: string, options: PostcssOptions) {
   const loaded = (await import(pathToFileURL(configFile).href)) as
     PostcssConfig | { default: PostcssConfig }
   const config = 'default' in loaded && loaded.default ? loaded.default : loaded
-  const plugins = postcssPlugins(root, config as PostcssConfig, options)
+  const { plugins, partitionedTailwindScan } = postcssPlugins(
+    root,
+    config as PostcssConfig,
+    options,
+  )
   if (plugins.length === 0) return undefined
   const appRequire = createRequire(path.join(root, 'package.json'))
   const postcss = interopDefault(resolvePostcss(appRequire)) as (
@@ -103,6 +170,7 @@ async function createPostcssProcessor(root: string, options: PostcssOptions) {
   return {
     processor: postcss(plugins),
     sources: tailwind ? scanExclusions(root, appRequire, options) : '',
+    partitionedTailwindScan,
   }
 }
 
@@ -120,23 +188,27 @@ async function createPostcssProcessor(root: string, options: PostcssOptions) {
  * stylesheet compiled with or without utilities minted out of pnext's own emitted JS.
  */
 /**
- * An appended `@source not <dir>` silences every explicit `@source` glob the stylesheet points
- * under that dir - Tailwind gives `not` precedence - so an app opting INTO scanning a package
- * (`@source '../../node_modules/x/dist/...'`) lost those utilities entirely. Keep only the
- * exclusions that no explicit `@source` in this stylesheet reaches into.
+ * The patched scanner partitions explicit dependency sources before applying broad exclusions, so
+ * it needs the complete exclusion set. The native fallback cannot do that: remove any broad
+ * exclusion that would otherwise override an explicit `@source` and silently drop its utilities.
  */
-export function keptExclusions(exclusions: string, css: string, fromFile: string): string {
-  if (!exclusions) return exclusions
+export function keptExclusions(
+  exclusions: string,
+  css: string,
+  fromFile: string,
+  partitionedTailwindScan = false,
+): string {
+  if (!exclusions || partitionedTailwindScan) return exclusions
   const dir = path.dirname(fromFile)
-  const globs = [...css.matchAll(/@source\s+(?!not\s)['"]([^'"]+)['"]/g)].map(m =>
-    path.resolve(dir, m[1]!.replace(/[*{[].*$/, '')),
+  const globs = [...css.matchAll(/@source\s+(?!not\s)['"]([^'"]+)['"]/g)].map(match =>
+    path.resolve(dir, match[1]!.replace(/[*{[].*$/, '')),
   )
   if (globs.length === 0) return exclusions
   const kept = exclusions
     .split('\n')
     .filter(line => {
-      const m = /@source not "([^"]+)"/.exec(line)
-      return !m || !globs.some(glob => glob === m[1] || glob.startsWith(m[1] + '/'))
+      const match = /@source not "([^"]+)"/.exec(line)
+      return !match || !globs.some(glob => glob === match[1] || glob.startsWith(match[1] + '/'))
     })
     .join('\n')
   return kept.includes('@source not') ? kept : ''
@@ -188,6 +260,7 @@ function postcssPlugins(root: string, config: PostcssConfig, options: PostcssOpt
   const entries = pluginEntries(config)
 
   const plugins: unknown[] = []
+  let partitionedTailwindScan = false
   for (const [specifier, pluginOptions] of entries) {
     if (pluginOptions === false) continue
     if (typeof specifier !== 'string') {
@@ -195,13 +268,373 @@ function postcssPlugins(root: string, config: PostcssConfig, options: PostcssOpt
       if (specifier) plugins.push(specifier)
       continue
     }
+    const patchedScanner =
+      specifier === '@tailwindcss/postcss'
+        ? configureTailwindScanner(appRequire, root, options)
+        : undefined
     const factory = interopDefault(appRequire(specifier) as unknown)
+    if (patchedScanner) {
+      assertTailwindScannerPatch(appRequire, patchedScanner)
+      partitionedTailwindScan = true
+    }
     const resolvedOptions = pluginOptionsFor(root, specifier, pluginOptions, options)
     plugins.push(
       typeof factory === 'function' ? (factory as PostcssPluginFactory)(resolvedOptions) : factory,
     )
   }
-  return plugins
+  return { plugins, partitionedTailwindScan }
+}
+
+function configureTailwindScanner(
+  appRequire: NodeJS.Require,
+  root: string,
+  options: PostcssOptions,
+) {
+  const pluginPackage = appRequire.resolve('@tailwindcss/postcss/package.json')
+  const pluginRequire = createRequire(pluginPackage)
+  const oxide = pluginRequire('@tailwindcss/oxide') as TailwindOxideModule
+  const versions = ['@tailwindcss/postcss', 'tailwindcss', '@tailwindcss/oxide'].map(name => ({
+    name,
+    version: packageVersionText(pluginRequire, name),
+    tuple: packageVersion(pluginRequire, name),
+  }))
+  // The monkey-patch and source partitioning contract are covered against Tailwind 4.3.x.
+  if (!versions.every(({ tuple: [major, minor] }) => major === 4 && minor === 3)) {
+    const label = versions.map(({ name, version }) => `${name}@${version}`).join(', ')
+    if (!warnedTailwindScannerVersions.has(label)) {
+      warnedTailwindScannerVersions.add(label)
+      console.warn(`PNext: unsupported Tailwind scanner versions (${label}); using native Scanner.`)
+    }
+    return undefined
+  }
+  const registration = {
+    root: path.resolve(root),
+    cacheDir: path.join(
+      path.resolve(root, options.outDir ?? '.pnext'),
+      'cache/tailwind/candidates/v1',
+    ),
+    versions: ['@tailwindcss/postcss', 'tailwindcss', '@tailwindcss/oxide', 'postcss']
+      .map(name => `${name}@${packageVersionText(pluginRequire, name)}`)
+      .join('\0'),
+  }
+  const installed = oxide[tailwindScannerPatch]
+  if (installed) {
+    if (oxide.Scanner !== installed.Scanner) throw tailwindScannerPatchError()
+    const index = installed.registrations.findIndex(item => item.root === registration.root)
+    if (index === -1) installed.registrations.push(registration)
+    else installed.registrations[index] = registration
+    return installed.Scanner
+  }
+
+  const NativeScanner = oxide.Scanner
+  const registrations = [registration]
+  class PnextTailwindScanner implements TailwindScanner {
+    private readonly scanners: {
+      scanner: TailwindScanner
+      inventory: TailwindScanner
+      sources: TailwindSource[]
+    }[]
+    private readonly registration?: TailwindScanRegistration
+
+    constructor({ sources = [] }: { sources?: TailwindSource[] }) {
+      this.registration = tailwindRegistration(registrations, sources)
+      this.scanners = partitionTailwindSources(sources).map(partition => ({
+        scanner: new NativeScanner({ sources: partition }),
+        inventory: new NativeScanner({ sources: partition }),
+        sources: partition,
+      }))
+    }
+
+    scan() {
+      return sortedUnique(
+        this.scanners.flatMap(({ scanner, inventory, sources }) =>
+          this.registration
+            ? cachedTailwindCandidates(inventory, sources, this.registration, () =>
+                new NativeScanner({ sources }).scan(),
+              )
+            : scanner.scan(),
+        ),
+      )
+    }
+
+    scanFiles(input: TailwindChangedContent[]) {
+      return sortedUnique(this.scanners.flatMap(({ scanner }) => scanner.scanFiles(input)))
+    }
+
+    getCandidatesWithPositions(input: TailwindChangedContent) {
+      return this.scanners.flatMap(({ scanner }) => scanner.getCandidatesWithPositions(input))
+    }
+
+    get files() {
+      return sortedUnique(this.scanners.flatMap(({ inventory }) => inventory.files))
+    }
+
+    get scannedFiles() {
+      return sortedUnique(this.scanners.flatMap(({ scanner }) => scanner.scannedFiles))
+    }
+
+    get globs() {
+      return uniqueTailwindGlobs(this.scanners.flatMap(({ scanner }) => scanner.globs))
+    }
+
+    get normalizedSources() {
+      return uniqueTailwindGlobs(this.scanners.flatMap(({ scanner }) => scanner.normalizedSources))
+    }
+  }
+
+  oxide.Scanner = PnextTailwindScanner
+  oxide[tailwindScannerPatch] = { registrations, Scanner: PnextTailwindScanner }
+  return PnextTailwindScanner
+}
+
+function assertTailwindScannerPatch(
+  appRequire: NodeJS.Require,
+  expected: TailwindScannerConstructor,
+) {
+  const pluginPackage = appRequire.resolve('@tailwindcss/postcss/package.json')
+  const oxide = createRequire(pluginPackage)('@tailwindcss/oxide') as TailwindOxideModule
+  if (oxide.Scanner !== expected || oxide[tailwindScannerPatch]?.Scanner !== expected) {
+    throw tailwindScannerPatchError()
+  }
+}
+
+function tailwindScannerPatchError() {
+  return new Error(
+    'PNext could not install its Tailwind Scanner integration. The loaded @tailwindcss/postcss module does not observe the patched @tailwindcss/oxide Scanner; refusing to drop explicit @source utilities.',
+  )
+}
+
+function partitionTailwindSources(sources: TailwindSource[]): TailwindSource[][] {
+  const broadExclusions = sources.filter(source => source.negated && !/[*?{[]/.test(source.pattern))
+  const dependencySources = sources.filter(
+    source =>
+      !source.negated &&
+      broadExclusions.some(exclusion => isInside(sourcePrefix(exclusion), sourcePrefix(source))),
+  )
+  if (dependencySources.length === 0) return [sources]
+  const dependencySet = new Set(dependencySources)
+  const appSources = sources.filter(source => !dependencySet.has(source))
+  return [appSources].concat(
+    dependencySources.map(source =>
+      [
+        source,
+        ...sources.filter(
+          exclusion =>
+            exclusion.negated &&
+            !broadExclusions.includes(exclusion) &&
+            pathsOverlap(sourcePrefix(source), sourcePrefix(exclusion)),
+        ),
+      ].map(resolveTailwindSource),
+    ),
+  )
+}
+
+function resolveTailwindSource(source: TailwindSource): TailwindSource {
+  const globAt = source.pattern.search(/[*?{[]/)
+  const literal = (globAt === -1 ? source.pattern : source.pattern.slice(0, globAt)).replace(
+    /[\\/]$/,
+    '',
+  )
+  const absolutePattern = path.resolve(source.base, source.pattern)
+  let absolute = path.resolve(source.base, literal || '.')
+  while (!existsSync(absolute)) {
+    const parent = path.dirname(absolute)
+    if (parent === absolute) return source
+    absolute = parent
+  }
+  try {
+    const stat = statSync(absolute)
+    if (globAt === -1 && stat.isFile()) {
+      return {
+        ...source,
+        base: realpathSync.native(path.dirname(absolute)),
+        pattern: path.basename(absolute),
+      }
+    }
+    return {
+      ...source,
+      base: realpathSync.native(absolute),
+      pattern:
+        globAt === -1 ? '**/*' : path.relative(absolute, absolutePattern).split(path.sep).join('/'),
+    }
+  } catch {
+    return source
+  }
+}
+
+function sourcePrefix(source: TailwindSource) {
+  const prefix = source.pattern.replace(/[*?{[].*$/, '').replace(/[\\/]$/, '') || '.'
+  return path.resolve(source.base, prefix)
+}
+
+function pathsOverlap(left: string, right: string) {
+  return isInside(left, right) || isInside(right, left)
+}
+
+function isInside(parent: string, child: string) {
+  const relative = path.relative(parent, child)
+  return (
+    relative === '' ||
+    (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))
+  )
+}
+
+function tailwindRegistration(
+  registrations: TailwindScanRegistration[],
+  sources: TailwindSource[],
+) {
+  return [...registrations]
+    .sort((left, right) => right.root.length - left.root.length)
+    .find(item => sources.some(source => isInside(item.root, path.resolve(source.base))))
+}
+
+function cachedTailwindCandidates(
+  inventory: TailwindScanner,
+  sources: TailwindSource[],
+  registration: TailwindScanRegistration,
+  scan: () => string[],
+) {
+  let cache: { file: string; fingerprint: string; files: number }
+  try {
+    cache = tailwindCacheIdentity(inventory, sources, registration)
+  } catch {
+    return scan()
+  }
+  const stored = readJson<{
+    schema?: number
+    fingerprint?: string
+    candidates?: unknown
+  }>(cache.file)
+  if (
+    stored?.schema === tailwindCandidateSchema &&
+    stored.fingerprint === cache.fingerprint &&
+    Array.isArray(stored.candidates) &&
+    stored.candidates.every(candidate => typeof candidate === 'string')
+  ) {
+    return stored.candidates
+  }
+
+  const candidates = scan()
+  try {
+    mkdirSync(registration.cacheDir, { recursive: true })
+    atomicJsonWrite(cache.file, {
+      schema: tailwindCandidateSchema,
+      fingerprint: cache.fingerprint,
+      candidates,
+      files: cache.files,
+    })
+  } catch {
+    // Cache writes are optional; the fresh Oxide result remains correct.
+  }
+  return candidates
+}
+
+function tailwindCacheIdentity(
+  scanner: TailwindScanner,
+  sources: TailwindSource[],
+  registration: TailwindScanRegistration,
+) {
+  const identities = sources.map(tailwindSourceIdentity)
+  const sourceKey = createHash('sha256')
+    .update(String(tailwindCandidateSchema))
+    .update('\0')
+    .update(registration.versions)
+    .update('\0')
+    .update(JSON.stringify(identities))
+    .digest('hex')
+  const files = scanner.files.map(file => path.resolve(file)).sort()
+  const fingerprint = createHash('sha256').update(sourceKey)
+  for (const file of files) {
+    fingerprint.update('\0').update(file).update('\0').update(readFileSync(file))
+  }
+  return {
+    file: path.join(registration.cacheDir, `${sourceKey}.json`),
+    fingerprint: fingerprint.digest('hex'),
+    files: files.length,
+  }
+}
+
+function tailwindSourceIdentity(source: TailwindSource) {
+  const prefix = sourcePrefix(source)
+  const real = realExistingPath(prefix)
+  const packageFile = nearestPackageJson(real)
+  let packageIdentity: { name?: string; version?: string } | undefined
+  if (packageFile) {
+    const pkg = readJson<{ name?: string; version?: string }>(packageFile)
+    if (pkg) {
+      packageIdentity = { name: pkg.name, version: pkg.version }
+    }
+  }
+  return { ...source, base: path.resolve(source.base), real, package: packageIdentity }
+}
+
+function realExistingPath(input: string) {
+  let current = input
+  while (!existsSync(current)) {
+    const parent = path.dirname(current)
+    if (parent === current) return input
+    current = parent
+  }
+  try {
+    const stat = statSync(current)
+    return realpathSync.native(stat.isFile() ? path.dirname(current) : current)
+  } catch {
+    return current
+  }
+}
+
+function nearestPackageJson(input: string) {
+  let current = input
+  while (true) {
+    const file = path.join(current, 'package.json')
+    if (existsSync(file)) return file
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return undefined
+}
+
+function atomicJsonWrite(file: string, value: unknown) {
+  const temporary = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`
+  writeFileSync(temporary, JSON.stringify(value))
+  renameSync(temporary, file)
+}
+
+function readJson<T>(file: string): T | undefined {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as T
+  } catch {
+    return undefined
+  }
+}
+
+function sortedUnique(values: string[]) {
+  return [...new Set(values)].sort()
+}
+
+function uniqueTailwindGlobs(globs: TailwindGlob[]) {
+  const seen = new Set<string>()
+  return globs.filter(glob => {
+    const key = `${glob.base}\0${glob.pattern}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
+function packageVersionText(req: NodeJS.Require, name: string) {
+  try {
+    return (
+      (
+        JSON.parse(readFileSync(req.resolve(`${name}/package.json`), 'utf8')) as {
+          version?: string
+        }
+      ).version ?? 'unknown'
+    )
+  } catch {
+    return 'unknown'
+  }
 }
 
 function pluginOptionsFor(

package/src/dev/client-actions.ts

@@ -20,6 +20,8 @@ export interface ClientActionBundler {
   isClientActionModule: (file: string) => boolean
   /** Generate the client fetch-stub source for an action module file. */
   stubSource: (file: string) => Promise<string>
+  /** Read a client-layer source and replace an undiscovered action module with its RPC stub. */
+  loadClientSource: (file: string, root: string) => Promise<{ source: string; stubSource?: string }>
 }
 
 let bundler: ClientActionBundler | undefined