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

package/src/cache/store.ts

@@ -0,0 +1,1440 @@
+import type { NormalizedCacheOptions } from '../options/types'
+import type {
+  CacheClearOptions,
+  CacheClearResult,
+  CacheContextDescriptor,
+  CacheIndexEntry,
+  CacheIndexFileV2,
+  CacheReadMeta,
+  CacheReadResult,
+} from './types'
+import process from 'node:process'
+import fs from 'fs-extra'
+import logger from '../logger'
+import { explainContextMismatch } from './context'
+import { CACHE_SCHEMA_VERSION } from './types'
+
+interface ParsedCacheFileV2 {
+  kind: 'v2'
+  data: CacheIndexFileV2
+}
+
+interface ParsedCacheFileLegacy {
+  kind: 'legacy'
+  data: string[]
+}
+
+interface ParsedCacheFileEmpty {
+  kind: 'empty'
+}
+
+interface ParsedCacheFileInvalid {
+  kind: 'invalid'
+}
+
+type ParsedCacheFile = ParsedCacheFileV2 | ParsedCacheFileLegacy | ParsedCacheFileEmpty | ParsedCacheFileInvalid
+
+function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && typeof (error as NodeJS.ErrnoException).code === 'string'
+}
+
+function isAccessDenied(error: unknown): error is NodeJS.ErrnoException {
+  return isErrnoException(error)
+    && Boolean(error.code && ['EPERM', 'EBUSY', 'EACCES'].includes(error.code))
+}
+
+function toStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return []
+  }
+
+  return value.filter((item): item is string => typeof item === 'string')
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined
+  }
+  return value as Record<string, unknown>
+}
+
+function toReadMeta(meta: CacheReadMeta): CacheReadMeta {
+  return {
+    ...meta,
+    details: [...meta.details],
+  }
+}
+
+function cloneEntry(entry: CacheIndexEntry): CacheIndexEntry {
+  return {
+    context: {
+      ...entry.context,
+    },
+    values: [...entry.values],
+    updatedAt: entry.updatedAt,
+  }
+}
+
+export class CacheStore {
+  private readonly driver: NormalizedCacheOptions['driver']
+  private readonly lockPath: string
+  private memoryCache: Set<string> | null = null
+  private memoryIndex: CacheIndexFileV2 | null = null
+  private lastReadMeta: CacheReadMeta = {
+    hit: false,
+    reason: 'context-not-found',
+    details: [],
+  }
+
+  constructor(
+    private readonly options: NormalizedCacheOptions,
+    private readonly context?: CacheContextDescriptor,
+  ) {
+    this.driver = options.driver ?? 'file'
+    this.lockPath = `${this.options.path}.lock`
+  }
+
+  private isContextAware() {
+    return this.context !== undefined
+  }
+
+  private createEmptyIndex(): CacheIndexFileV2 {
+    return {
+      schemaVersion: CACHE_SCHEMA_VERSION,
+      updatedAt: new Date().toISOString(),
+      contexts: {},
+    }
+  }
+
+  private async ensureDir() {
+    await fs.ensureDir(this.options.dir)
+  }
+
+  private ensureDirSync() {
+    fs.ensureDirSync(this.options.dir)
+  }
+
+  private createTempPath() {
+    const uniqueSuffix = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+    return `${this.options.path}.${uniqueSuffix}.tmp`
+  }
+
+  private async replaceCacheFile(tempPath: string): Promise<boolean> {
+    try {
+      await fs.rename(tempPath, this.options.path)
+      return true
+    }
+    catch (error) {
+      if (isErrnoException(error) && (error.code === 'EEXIST' || error.code === 'EPERM')) {
+        try {
+          await fs.remove(this.options.path)
+        }
+        catch (removeError) {
+          if (isAccessDenied(removeError)) {
+            logger.debug('Tailwind class cache locked or read-only, skipping update.', removeError)
+            return false
+          }
+
+          if (!isErrnoException(removeError) || removeError.code !== 'ENOENT') {
+            throw removeError
+          }
+        }
+
+        await fs.rename(tempPath, this.options.path)
+        return true
+      }
+
+      throw error
+    }
+  }
+
+  private replaceCacheFileSync(tempPath: string): boolean {
+    try {
+      fs.renameSync(tempPath, this.options.path)
+      return true
+    }
+    catch (error) {
+      if (isErrnoException(error) && (error.code === 'EEXIST' || error.code === 'EPERM')) {
+        try {
+          fs.removeSync(this.options.path)
+        }
+        catch (removeError) {
+          if (isAccessDenied(removeError)) {
+            logger.debug('Tailwind class cache locked or read-only, skipping update.', removeError)
+            return false
+          }
+
+          if (!isErrnoException(removeError) || removeError.code !== 'ENOENT') {
+            throw removeError
+          }
+        }
+
+        fs.renameSync(tempPath, this.options.path)
+        return true
+      }
+
+      throw error
+    }
+  }
+
+  private async cleanupTempFile(tempPath: string) {
+    try {
+      await fs.remove(tempPath)
+    }
+    catch {}
+  }
+
+  private cleanupTempFileSync(tempPath: string) {
+    try {
+      fs.removeSync(tempPath)
+    }
+    catch {}
+  }
+
+  private async delay(ms: number) {
+    await new Promise(resolve => setTimeout(resolve, ms))
+  }
+
+  private async acquireLock(): Promise<boolean> {
+    await fs.ensureDir(this.options.dir)
+    const maxAttempts = 40
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        await fs.writeFile(this.lockPath, `${process.pid}\n${Date.now()}`, { flag: 'wx' })
+        return true
+      }
+      catch (error) {
+        if (!isErrnoException(error) || error.code !== 'EEXIST') {
+          logger.debug('Unable to acquire cache lock.', error)
+          return false
+        }
+
+        try {
+          const stat = await fs.stat(this.lockPath)
+          if (Date.now() - stat.mtimeMs > 30_000) {
+            await fs.remove(this.lockPath)
+            continue
+          }
+        }
+        catch {}
+
+        await this.delay(25)
+      }
+    }
+
+    logger.debug('Timed out while waiting for cache lock; skipping cache mutation.')
+    return false
+  }
+
+  private releaseLockSyncOrAsync(sync: true): void
+  private releaseLockSyncOrAsync(sync: false): Promise<void>
+  private releaseLockSyncOrAsync(sync: boolean): void | Promise<void> {
+    if (sync) {
+      try {
+        fs.removeSync(this.lockPath)
+      }
+      catch {}
+      return
+    }
+
+    return fs.remove(this.lockPath).catch(() => undefined)
+  }
+
+  private acquireLockSync(): boolean {
+    fs.ensureDirSync(this.options.dir)
+    const maxAttempts = 40
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        fs.writeFileSync(this.lockPath, `${process.pid}\n${Date.now()}`, { flag: 'wx' })
+        return true
+      }
+      catch (error) {
+        if (!isErrnoException(error) || error.code !== 'EEXIST') {
+          logger.debug('Unable to acquire cache lock.', error)
+          return false
+        }
+
+        try {
+          const stat = fs.statSync(this.lockPath)
+          if (Date.now() - stat.mtimeMs > 30_000) {
+            fs.removeSync(this.lockPath)
+            continue
+          }
+        }
+        catch {}
+
+        const start = Date.now()
+        while (Date.now() - start < 25) {
+          // busy-wait sleep for sync lock retries
+        }
+      }
+    }
+
+    logger.debug('Timed out while waiting for cache lock; skipping cache mutation.')
+    return false
+  }
+
+  private async withFileLock<T>(fn: () => Promise<T>): Promise<T | undefined> {
+    const locked = await this.acquireLock()
+    if (!locked) {
+      return undefined
+    }
+
+    try {
+      return await fn()
+    }
+    finally {
+      await this.releaseLockSyncOrAsync(false)
+    }
+  }
+
+  private withFileLockSync<T>(fn: () => T): T | undefined {
+    const locked = this.acquireLockSync()
+    if (!locked) {
+      return undefined
+    }
+
+    try {
+      return fn()
+    }
+    finally {
+      this.releaseLockSyncOrAsync(true)
+    }
+  }
+
+  private normalizeContextEntry(value: unknown): CacheIndexEntry | undefined {
+    const record = asObject(value)
+    if (!record) {
+      return undefined
+    }
+
+    const values = toStringArray(record['values'])
+    if (values.length === 0) {
+      return undefined
+    }
+
+    const contextRecord = asObject(record['context'])
+    if (!contextRecord) {
+      return undefined
+    }
+
+    const {
+      fingerprintVersion,
+      projectRootRealpath,
+      processCwdRealpath,
+      cacheCwdRealpath,
+      tailwindConfigPath,
+      tailwindConfigMtimeMs,
+      tailwindPackageRootRealpath,
+      tailwindPackageVersion,
+      patcherVersion,
+      majorVersion,
+      optionsHash,
+    } = contextRecord
+
+    if (
+      fingerprintVersion !== 1
+      || typeof projectRootRealpath !== 'string'
+      || typeof processCwdRealpath !== 'string'
+      || typeof cacheCwdRealpath !== 'string'
+      || typeof tailwindPackageRootRealpath !== 'string'
+      || typeof tailwindPackageVersion !== 'string'
+      || typeof patcherVersion !== 'string'
+      || (majorVersion !== 2 && majorVersion !== 3 && majorVersion !== 4)
+      || typeof optionsHash !== 'string'
+    ) {
+      return undefined
+    }
+
+    const normalized: CacheIndexEntry = {
+      context: {
+        fingerprintVersion,
+        projectRootRealpath,
+        processCwdRealpath,
+        cacheCwdRealpath,
+        ...(typeof tailwindConfigPath === 'string' ? { tailwindConfigPath } : {}),
+        ...(typeof tailwindConfigMtimeMs === 'number' ? { tailwindConfigMtimeMs } : {}),
+        tailwindPackageRootRealpath,
+        tailwindPackageVersion,
+        patcherVersion,
+        majorVersion,
+        optionsHash,
+      },
+      values,
+      updatedAt: typeof record['updatedAt'] === 'string' ? record['updatedAt'] : new Date(0).toISOString(),
+    }
+
+    return normalized
+  }
+
+  private normalizeIndexFile(payload: unknown): ParsedCacheFile {
+    if (Array.isArray(payload)) {
+      return {
+        kind: 'legacy',
+        data: toStringArray(payload),
+      }
+    }
+
+    const record = asObject(payload)
+    if (!record) {
+      return { kind: 'invalid' }
+    }
+
+    if (record['schemaVersion'] !== CACHE_SCHEMA_VERSION) {
+      return { kind: 'invalid' }
+    }
+
+    const contextsRecord = asObject(record['contexts'])
+    if (!contextsRecord) {
+      return { kind: 'invalid' }
+    }
+
+    const contexts: CacheIndexFileV2['contexts'] = {}
+
+    for (const [fingerprint, value] of Object.entries(contextsRecord)) {
+      if (typeof fingerprint !== 'string' || !fingerprint) {
+        continue
+      }
+      const entry = this.normalizeContextEntry(value)
+      if (!entry) {
+        continue
+      }
+      contexts[fingerprint] = entry
+    }
+
+    return {
+      kind: 'v2',
+      data: {
+        schemaVersion: CACHE_SCHEMA_VERSION,
+        updatedAt: typeof record['updatedAt'] === 'string' ? record['updatedAt'] : new Date(0).toISOString(),
+        contexts,
+      },
+    }
+  }
+
+  private async readParsedCacheFile(cleanupInvalid: boolean): Promise<ParsedCacheFile> {
+    try {
+      if (!(await fs.pathExists(this.options.path))) {
+        return { kind: 'empty' }
+      }
+
+      const payload = await fs.readJSON(this.options.path)
+      const normalized = this.normalizeIndexFile(payload)
+      if (normalized.kind !== 'invalid') {
+        return normalized
+      }
+
+      if (cleanupInvalid) {
+        logger.warn('Unable to read Tailwind class cache index, removing invalid file.')
+        await fs.remove(this.options.path)
+      }
+      return { kind: 'invalid' }
+    }
+    catch (error) {
+      if (isErrnoException(error) && error.code === 'ENOENT') {
+        return { kind: 'empty' }
+      }
+
+      logger.warn('Unable to read Tailwind class cache index, removing invalid file.', error)
+      if (cleanupInvalid) {
+        try {
+          await fs.remove(this.options.path)
+        }
+        catch (cleanupError) {
+          logger.error('Failed to clean up invalid cache file', cleanupError)
+        }
+      }
+
+      return { kind: 'invalid' }
+    }
+  }
+
+  private readParsedCacheFileSync(cleanupInvalid: boolean): ParsedCacheFile {
+    try {
+      if (!fs.pathExistsSync(this.options.path)) {
+        return { kind: 'empty' }
+      }
+
+      const payload = fs.readJSONSync(this.options.path)
+      const normalized = this.normalizeIndexFile(payload)
+      if (normalized.kind !== 'invalid') {
+        return normalized
+      }
+
+      if (cleanupInvalid) {
+        logger.warn('Unable to read Tailwind class cache index, removing invalid file.')
+        fs.removeSync(this.options.path)
+      }
+      return { kind: 'invalid' }
+    }
+    catch (error) {
+      if (isErrnoException(error) && error.code === 'ENOENT') {
+        return { kind: 'empty' }
+      }
+
+      logger.warn('Unable to read Tailwind class cache index, removing invalid file.', error)
+      if (cleanupInvalid) {
+        try {
+          fs.removeSync(this.options.path)
+        }
+        catch (cleanupError) {
+          logger.error('Failed to clean up invalid cache file', cleanupError)
+        }
+      }
+
+      return { kind: 'invalid' }
+    }
+  }
+
+  private findProjectMatch(index: CacheIndexFileV2) {
+    if (!this.context) {
+      return undefined
+    }
+
+    const current = this.context.metadata.projectRootRealpath
+    return Object.entries(index.contexts).find(([, entry]) => entry.context.projectRootRealpath === current)
+  }
+
+  private async writeIndexFile(index: CacheIndexFileV2): Promise<string | undefined> {
+    const tempPath = this.createTempPath()
+
+    try {
+      await this.ensureDir()
+      await fs.writeJSON(tempPath, index)
+      const replaced = await this.replaceCacheFile(tempPath)
+      if (replaced) {
+        return this.options.path
+      }
+
+      await this.cleanupTempFile(tempPath)
+      return undefined
+    }
+    catch (error) {
+      await this.cleanupTempFile(tempPath)
+      logger.error('Unable to persist Tailwind class cache', error)
+      return undefined
+    }
+  }
+
+  private writeIndexFileSync(index: CacheIndexFileV2): string | undefined {
+    const tempPath = this.createTempPath()
+
+    try {
+      this.ensureDirSync()
+      fs.writeJSONSync(tempPath, index)
+      const replaced = this.replaceCacheFileSync(tempPath)
+      if (replaced) {
+        return this.options.path
+      }
+
+      this.cleanupTempFileSync(tempPath)
+      return undefined
+    }
+    catch (error) {
+      this.cleanupTempFileSync(tempPath)
+      logger.error('Unable to persist Tailwind class cache', error)
+      return undefined
+    }
+  }
+
+  async write(data: Set<string>): Promise<string | undefined> {
+    if (!this.options.enabled) {
+      return undefined
+    }
+
+    if (this.driver === 'noop') {
+      return undefined
+    }
+
+    if (this.driver === 'memory') {
+      if (!this.isContextAware()) {
+        this.memoryCache = new Set(data)
+        return 'memory'
+      }
+
+      const index = this.memoryIndex ?? this.createEmptyIndex()
+      if (!this.context) {
+        return 'memory'
+      }
+      index.contexts[this.context.fingerprint] = {
+        context: {
+          ...this.context.metadata,
+        },
+        values: Array.from(data),
+        updatedAt: new Date().toISOString(),
+      }
+      index.updatedAt = new Date().toISOString()
+      this.memoryIndex = index
+      return 'memory'
+    }
+
+    if (!this.isContextAware()) {
+      const tempPath = this.createTempPath()
+      try {
+        await this.ensureDir()
+        await fs.writeJSON(tempPath, Array.from(data))
+        const replaced = await this.replaceCacheFile(tempPath)
+        if (replaced) {
+          return this.options.path
+        }
+
+        await this.cleanupTempFile(tempPath)
+        return undefined
+      }
+      catch (error) {
+        await this.cleanupTempFile(tempPath)
+        logger.error('Unable to persist Tailwind class cache', error)
+        return undefined
+      }
+    }
+
+    const result = await this.withFileLock(async () => {
+      const parsed = await this.readParsedCacheFile(false)
+      const index = parsed.kind === 'v2' ? parsed.data : this.createEmptyIndex()
+
+      if (this.context) {
+        index.contexts[this.context.fingerprint] = {
+          context: {
+            ...this.context.metadata,
+          },
+          values: Array.from(data),
+          updatedAt: new Date().toISOString(),
+        }
+      }
+
+      index.updatedAt = new Date().toISOString()
+      return this.writeIndexFile(index)
+    })
+
+    return result
+  }
+
+  writeSync(data: Set<string>): string | undefined {
+    if (!this.options.enabled) {
+      return undefined
+    }
+
+    if (this.driver === 'noop') {
+      return undefined
+    }
+
+    if (this.driver === 'memory') {
+      if (!this.isContextAware()) {
+        this.memoryCache = new Set(data)
+        return 'memory'
+      }
+
+      const index = this.memoryIndex ?? this.createEmptyIndex()
+      if (!this.context) {
+        return 'memory'
+      }
+      index.contexts[this.context.fingerprint] = {
+        context: {
+          ...this.context.metadata,
+        },
+        values: Array.from(data),
+        updatedAt: new Date().toISOString(),
+      }
+      index.updatedAt = new Date().toISOString()
+      this.memoryIndex = index
+      return 'memory'
+    }
+
+    if (!this.isContextAware()) {
+      const tempPath = this.createTempPath()
+      try {
+        this.ensureDirSync()
+        fs.writeJSONSync(tempPath, Array.from(data))
+        const replaced = this.replaceCacheFileSync(tempPath)
+        if (replaced) {
+          return this.options.path
+        }
+
+        this.cleanupTempFileSync(tempPath)
+        return undefined
+      }
+      catch (error) {
+        this.cleanupTempFileSync(tempPath)
+        logger.error('Unable to persist Tailwind class cache', error)
+        return undefined
+      }
+    }
+
+    const result = this.withFileLockSync(() => {
+      const parsed = this.readParsedCacheFileSync(false)
+      const index = parsed.kind === 'v2' ? parsed.data : this.createEmptyIndex()
+
+      if (this.context) {
+        index.contexts[this.context.fingerprint] = {
+          context: {
+            ...this.context.metadata,
+          },
+          values: Array.from(data),
+          updatedAt: new Date().toISOString(),
+        }
+      }
+
+      index.updatedAt = new Date().toISOString()
+      return this.writeIndexFileSync(index)
+    })
+
+    return result
+  }
+
+  async readWithMeta(): Promise<CacheReadResult> {
+    if (!this.options.enabled) {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'cache-disabled',
+          details: ['cache disabled'],
+        },
+      }
+    }
+
+    if (this.driver === 'noop') {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'noop-driver',
+          details: ['cache driver is noop'],
+        },
+      }
+    }
+
+    if (this.driver === 'memory') {
+      if (!this.isContextAware()) {
+        const cache = new Set(this.memoryCache ?? [])
+        return {
+          data: cache,
+          meta: {
+            hit: cache.size > 0,
+            reason: cache.size > 0 ? 'hit' : 'context-not-found',
+            details: cache.size > 0 ? ['memory cache hit'] : ['memory cache miss'],
+          },
+        }
+      }
+
+      const index = this.memoryIndex
+      if (!index || !this.context) {
+        return {
+          data: new Set(),
+          meta: {
+            hit: false,
+            reason: 'context-not-found',
+            ...(this.context?.fingerprint === undefined ? {} : { fingerprint: this.context.fingerprint }),
+            schemaVersion: CACHE_SCHEMA_VERSION,
+            details: ['no in-memory cache index for current context'],
+          },
+        }
+      }
+
+      const entry = index.contexts[this.context.fingerprint]
+      if (entry) {
+        return {
+          data: new Set(entry.values),
+          meta: {
+            hit: true,
+            reason: 'hit',
+            fingerprint: this.context.fingerprint,
+            schemaVersion: CACHE_SCHEMA_VERSION,
+            details: ['memory cache hit'],
+          },
+        }
+      }
+
+      const projectMatch = this.findProjectMatch(index)
+      if (projectMatch && this.context) {
+        const [, matchedEntry] = projectMatch
+        return {
+          data: new Set(),
+          meta: {
+            hit: false,
+            reason: 'context-mismatch',
+            fingerprint: this.context.fingerprint,
+            schemaVersion: CACHE_SCHEMA_VERSION,
+            details: explainContextMismatch(this.context.metadata, matchedEntry.context),
+          },
+        }
+      }
+
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'context-not-found',
+          fingerprint: this.context.fingerprint,
+          schemaVersion: CACHE_SCHEMA_VERSION,
+          details: ['context fingerprint not found in memory cache index'],
+        },
+      }
+    }
+
+    const parsed = await this.readParsedCacheFile(true)
+
+    if (parsed.kind === 'empty') {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'file-missing',
+          details: ['cache file not found'],
+        },
+      }
+    }
+
+    if (parsed.kind === 'invalid') {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'invalid-schema',
+          details: ['cache schema invalid and has been reset'],
+        },
+      }
+    }
+
+    if (!this.isContextAware()) {
+      if (parsed.kind === 'legacy') {
+        return {
+          data: new Set(parsed.data),
+          meta: {
+            hit: parsed.data.length > 0,
+            reason: parsed.data.length > 0 ? 'hit' : 'context-not-found',
+            details: ['legacy cache format'],
+          },
+        }
+      }
+
+      const union = Object.values(parsed.data.contexts).flatMap(entry => entry.values)
+      return {
+        data: new Set(union),
+        meta: {
+          hit: union.length > 0,
+          reason: union.length > 0 ? 'hit' : 'context-not-found',
+          schemaVersion: parsed.data.schemaVersion,
+          details: ['context-less read merged all cache entries'],
+        },
+      }
+    }
+
+    if (parsed.kind === 'legacy') {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'legacy-schema',
+          ...(this.context?.fingerprint === undefined ? {} : { fingerprint: this.context.fingerprint }),
+          details: ['legacy cache schema detected; rebuilding cache with context fingerprint'],
+        },
+      }
+    }
+
+    if (!this.context) {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'context-not-found',
+          details: ['cache context missing'],
+        },
+      }
+    }
+
+    const entry = parsed.data.contexts[this.context.fingerprint]
+    if (entry) {
+      const mismatchReasons = explainContextMismatch(this.context.metadata, entry.context)
+      if (mismatchReasons.length === 0) {
+        return {
+          data: new Set(entry.values),
+          meta: {
+            hit: true,
+            reason: 'hit',
+            fingerprint: this.context.fingerprint,
+            schemaVersion: parsed.data.schemaVersion,
+            details: [`context fingerprint ${this.context.fingerprint.slice(0, 12)} matched`],
+          },
+        }
+      }
+
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'context-mismatch',
+          fingerprint: this.context.fingerprint,
+          schemaVersion: parsed.data.schemaVersion,
+          details: mismatchReasons,
+        },
+      }
+    }
+
+    const projectMatch = this.findProjectMatch(parsed.data)
+    if (projectMatch) {
+      const [matchedFingerprint, matchedEntry] = projectMatch
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'context-mismatch',
+          fingerprint: this.context.fingerprint,
+          schemaVersion: parsed.data.schemaVersion,
+          details: [
+            `nearest context fingerprint: ${matchedFingerprint.slice(0, 12)}`,
+            ...explainContextMismatch(this.context.metadata, matchedEntry.context),
+          ],
+        },
+      }
+    }
+
+    return {
+      data: new Set(),
+      meta: {
+        hit: false,
+        reason: 'context-not-found',
+        fingerprint: this.context.fingerprint,
+        schemaVersion: parsed.data.schemaVersion,
+        details: ['context fingerprint not found in cache index'],
+      },
+    }
+  }
+
+  readWithMetaSync(): CacheReadResult {
+    if (!this.options.enabled) {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'cache-disabled',
+          details: ['cache disabled'],
+        },
+      }
+    }
+
+    if (this.driver === 'noop') {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'noop-driver',
+          details: ['cache driver is noop'],
+        },
+      }
+    }
+
+    if (this.driver === 'memory') {
+      if (!this.isContextAware()) {
+        const cache = new Set(this.memoryCache ?? [])
+        return {
+          data: cache,
+          meta: {
+            hit: cache.size > 0,
+            reason: cache.size > 0 ? 'hit' : 'context-not-found',
+            details: cache.size > 0 ? ['memory cache hit'] : ['memory cache miss'],
+          },
+        }
+      }
+
+      const index = this.memoryIndex
+      if (!index || !this.context) {
+        return {
+          data: new Set(),
+          meta: {
+            hit: false,
+            reason: 'context-not-found',
+            ...(this.context?.fingerprint === undefined ? {} : { fingerprint: this.context.fingerprint }),
+            schemaVersion: CACHE_SCHEMA_VERSION,
+            details: ['no in-memory cache index for current context'],
+          },
+        }
+      }
+
+      const entry = index.contexts[this.context.fingerprint]
+      if (entry) {
+        return {
+          data: new Set(entry.values),
+          meta: {
+            hit: true,
+            reason: 'hit',
+            fingerprint: this.context.fingerprint,
+            schemaVersion: CACHE_SCHEMA_VERSION,
+            details: ['memory cache hit'],
+          },
+        }
+      }
+
+      const projectMatch = this.findProjectMatch(index)
+      if (projectMatch && this.context) {
+        const [, matchedEntry] = projectMatch
+        return {
+          data: new Set(),
+          meta: {
+            hit: false,
+            reason: 'context-mismatch',
+            fingerprint: this.context.fingerprint,
+            schemaVersion: CACHE_SCHEMA_VERSION,
+            details: explainContextMismatch(this.context.metadata, matchedEntry.context),
+          },
+        }
+      }
+
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'context-not-found',
+          fingerprint: this.context.fingerprint,
+          schemaVersion: CACHE_SCHEMA_VERSION,
+          details: ['context fingerprint not found in memory cache index'],
+        },
+      }
+    }
+
+    const parsed = this.readParsedCacheFileSync(true)
+
+    if (parsed.kind === 'empty') {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'file-missing',
+          details: ['cache file not found'],
+        },
+      }
+    }
+
+    if (parsed.kind === 'invalid') {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'invalid-schema',
+          details: ['cache schema invalid and has been reset'],
+        },
+      }
+    }
+
+    if (!this.isContextAware()) {
+      if (parsed.kind === 'legacy') {
+        return {
+          data: new Set(parsed.data),
+          meta: {
+            hit: parsed.data.length > 0,
+            reason: parsed.data.length > 0 ? 'hit' : 'context-not-found',
+            details: ['legacy cache format'],
+          },
+        }
+      }
+
+      const union = Object.values(parsed.data.contexts).flatMap(entry => entry.values)
+      return {
+        data: new Set(union),
+        meta: {
+          hit: union.length > 0,
+          reason: union.length > 0 ? 'hit' : 'context-not-found',
+          schemaVersion: parsed.data.schemaVersion,
+          details: ['context-less read merged all cache entries'],
+        },
+      }
+    }
+
+    if (parsed.kind === 'legacy') {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'legacy-schema',
+          ...(this.context?.fingerprint === undefined ? {} : { fingerprint: this.context.fingerprint }),
+          details: ['legacy cache schema detected; rebuilding cache with context fingerprint'],
+        },
+      }
+    }
+
+    if (!this.context) {
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'context-not-found',
+          details: ['cache context missing'],
+        },
+      }
+    }
+
+    const entry = parsed.data.contexts[this.context.fingerprint]
+    if (entry) {
+      const mismatchReasons = explainContextMismatch(this.context.metadata, entry.context)
+      if (mismatchReasons.length === 0) {
+        return {
+          data: new Set(entry.values),
+          meta: {
+            hit: true,
+            reason: 'hit',
+            fingerprint: this.context.fingerprint,
+            schemaVersion: parsed.data.schemaVersion,
+            details: [`context fingerprint ${this.context.fingerprint.slice(0, 12)} matched`],
+          },
+        }
+      }
+
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'context-mismatch',
+          fingerprint: this.context.fingerprint,
+          schemaVersion: parsed.data.schemaVersion,
+          details: mismatchReasons,
+        },
+      }
+    }
+
+    const projectMatch = this.findProjectMatch(parsed.data)
+    if (projectMatch) {
+      const [matchedFingerprint, matchedEntry] = projectMatch
+      return {
+        data: new Set(),
+        meta: {
+          hit: false,
+          reason: 'context-mismatch',
+          fingerprint: this.context.fingerprint,
+          schemaVersion: parsed.data.schemaVersion,
+          details: [
+            `nearest context fingerprint: ${matchedFingerprint.slice(0, 12)}`,
+            ...explainContextMismatch(this.context.metadata, matchedEntry.context),
+          ],
+        },
+      }
+    }
+
+    return {
+      data: new Set(),
+      meta: {
+        hit: false,
+        reason: 'context-not-found',
+        fingerprint: this.context.fingerprint,
+        schemaVersion: parsed.data.schemaVersion,
+        details: ['context fingerprint not found in cache index'],
+      },
+    }
+  }
+
+  async read(): Promise<Set<string>> {
+    const result = await this.readWithMeta()
+    this.lastReadMeta = toReadMeta(result.meta)
+    return new Set(result.data)
+  }
+
+  readSync(): Set<string> {
+    const result = this.readWithMetaSync()
+    this.lastReadMeta = toReadMeta(result.meta)
+    return new Set(result.data)
+  }
+
+  getLastReadMeta(): CacheReadMeta {
+    return toReadMeta(this.lastReadMeta)
+  }
+
+  private countEntriesFromParsed(parsed: ParsedCacheFile): { contexts: number, entries: number } {
+    if (parsed.kind === 'legacy') {
+      return {
+        contexts: parsed.data.length ? 1 : 0,
+        entries: parsed.data.length,
+      }
+    }
+
+    if (parsed.kind === 'v2') {
+      const values = Object.values(parsed.data.contexts)
+      return {
+        contexts: values.length,
+        entries: values.reduce((acc, item) => acc + item.values.length, 0),
+      }
+    }
+
+    return {
+      contexts: 0,
+      entries: 0,
+    }
+  }
+
+  async clear(options?: CacheClearOptions): Promise<CacheClearResult> {
+    const scope = options?.scope ?? 'current'
+
+    if (!this.options.enabled || this.driver === 'noop') {
+      return {
+        scope,
+        filesRemoved: 0,
+        entriesRemoved: 0,
+        contextsRemoved: 0,
+      }
+    }
+
+    if (this.driver === 'memory') {
+      if (!this.isContextAware() || scope === 'all') {
+        const entriesRemoved = this.memoryCache?.size ?? (this.memoryIndex ? this.countEntriesFromParsed({ kind: 'v2', data: this.memoryIndex }).entries : 0)
+        const contextsRemoved = this.memoryIndex ? Object.keys(this.memoryIndex.contexts).length : (this.memoryCache?.size ? 1 : 0)
+        this.memoryCache = null
+        this.memoryIndex = null
+        return {
+          scope,
+          filesRemoved: 0,
+          entriesRemoved,
+          contextsRemoved,
+        }
+      }
+
+      if (!this.context || !this.memoryIndex) {
+        return {
+          scope,
+          filesRemoved: 0,
+          entriesRemoved: 0,
+          contextsRemoved: 0,
+        }
+      }
+
+      const entry = this.memoryIndex.contexts[this.context.fingerprint]
+      if (!entry) {
+        return {
+          scope,
+          filesRemoved: 0,
+          entriesRemoved: 0,
+          contextsRemoved: 0,
+        }
+      }
+
+      const entriesRemoved = entry.values.length
+      delete this.memoryIndex.contexts[this.context.fingerprint]
+      return {
+        scope,
+        filesRemoved: 0,
+        entriesRemoved,
+        contextsRemoved: 1,
+      }
+    }
+
+    const result = await this.withFileLock(async () => {
+      const parsed = await this.readParsedCacheFile(false)
+      if (parsed.kind === 'empty') {
+        return {
+          scope,
+          filesRemoved: 0,
+          entriesRemoved: 0,
+          contextsRemoved: 0,
+        }
+      }
+
+      if (!this.isContextAware() || scope === 'all') {
+        const counts = this.countEntriesFromParsed(parsed)
+        await fs.remove(this.options.path)
+        return {
+          scope,
+          filesRemoved: 1,
+          entriesRemoved: counts.entries,
+          contextsRemoved: counts.contexts,
+        }
+      }
+
+      if (parsed.kind !== 'v2' || !this.context) {
+        const counts = this.countEntriesFromParsed(parsed)
+        await fs.remove(this.options.path)
+        return {
+          scope,
+          filesRemoved: 1,
+          entriesRemoved: counts.entries,
+          contextsRemoved: counts.contexts,
+        }
+      }
+
+      const entry = parsed.data.contexts[this.context.fingerprint]
+      if (!entry) {
+        return {
+          scope,
+          filesRemoved: 0,
+          entriesRemoved: 0,
+          contextsRemoved: 0,
+        }
+      }
+
+      const entriesRemoved = entry.values.length
+      delete parsed.data.contexts[this.context.fingerprint]
+      const remain = Object.keys(parsed.data.contexts).length
+      if (remain === 0) {
+        await fs.remove(this.options.path)
+        return {
+          scope,
+          filesRemoved: 1,
+          entriesRemoved,
+          contextsRemoved: 1,
+        }
+      }
+
+      parsed.data.updatedAt = new Date().toISOString()
+      await this.writeIndexFile(parsed.data)
+      return {
+        scope,
+        filesRemoved: 0,
+        entriesRemoved,
+        contextsRemoved: 1,
+      }
+    })
+
+    return result ?? {
+      scope,
+      filesRemoved: 0,
+      entriesRemoved: 0,
+      contextsRemoved: 0,
+    }
+  }
+
+  clearSync(options?: CacheClearOptions): CacheClearResult {
+    const scope = options?.scope ?? 'current'
+
+    if (!this.options.enabled || this.driver === 'noop') {
+      return {
+        scope,
+        filesRemoved: 0,
+        entriesRemoved: 0,
+        contextsRemoved: 0,
+      }
+    }
+
+    if (this.driver === 'memory') {
+      if (!this.isContextAware() || scope === 'all') {
+        const entriesRemoved = this.memoryCache?.size ?? (this.memoryIndex ? this.countEntriesFromParsed({ kind: 'v2', data: this.memoryIndex }).entries : 0)
+        const contextsRemoved = this.memoryIndex ? Object.keys(this.memoryIndex.contexts).length : (this.memoryCache?.size ? 1 : 0)
+        this.memoryCache = null
+        this.memoryIndex = null
+        return {
+          scope,
+          filesRemoved: 0,
+          entriesRemoved,
+          contextsRemoved,
+        }
+      }
+
+      if (!this.context || !this.memoryIndex) {
+        return {
+          scope,
+          filesRemoved: 0,
+          entriesRemoved: 0,
+          contextsRemoved: 0,
+        }
+      }
+
+      const entry = this.memoryIndex.contexts[this.context.fingerprint]
+      if (!entry) {
+        return {
+          scope,
+          filesRemoved: 0,
+          entriesRemoved: 0,
+          contextsRemoved: 0,
+        }
+      }
+
+      const entriesRemoved = entry.values.length
+      delete this.memoryIndex.contexts[this.context.fingerprint]
+      return {
+        scope,
+        filesRemoved: 0,
+        entriesRemoved,
+        contextsRemoved: 1,
+      }
+    }
+
+    const result = this.withFileLockSync(() => {
+      const parsed = this.readParsedCacheFileSync(false)
+      if (parsed.kind === 'empty') {
+        return {
+          scope,
+          filesRemoved: 0,
+          entriesRemoved: 0,
+          contextsRemoved: 0,
+        }
+      }
+
+      if (!this.isContextAware() || scope === 'all') {
+        const counts = this.countEntriesFromParsed(parsed)
+        fs.removeSync(this.options.path)
+        return {
+          scope,
+          filesRemoved: 1,
+          entriesRemoved: counts.entries,
+          contextsRemoved: counts.contexts,
+        }
+      }
+
+      if (parsed.kind !== 'v2' || !this.context) {
+        const counts = this.countEntriesFromParsed(parsed)
+        fs.removeSync(this.options.path)
+        return {
+          scope,
+          filesRemoved: 1,
+          entriesRemoved: counts.entries,
+          contextsRemoved: counts.contexts,
+        }
+      }
+
+      const entry = parsed.data.contexts[this.context.fingerprint]
+      if (!entry) {
+        return {
+          scope,
+          filesRemoved: 0,
+          entriesRemoved: 0,
+          contextsRemoved: 0,
+        }
+      }
+
+      const entriesRemoved = entry.values.length
+      delete parsed.data.contexts[this.context.fingerprint]
+      const remain = Object.keys(parsed.data.contexts).length
+      if (remain === 0) {
+        fs.removeSync(this.options.path)
+        return {
+          scope,
+          filesRemoved: 1,
+          entriesRemoved,
+          contextsRemoved: 1,
+        }
+      }
+
+      parsed.data.updatedAt = new Date().toISOString()
+      this.writeIndexFileSync(parsed.data)
+      return {
+        scope,
+        filesRemoved: 0,
+        entriesRemoved,
+        contextsRemoved: 1,
+      }
+    })
+
+    return result ?? {
+      scope,
+      filesRemoved: 0,
+      entriesRemoved: 0,
+      contextsRemoved: 0,
+    }
+  }
+
+  readIndexSnapshot(): CacheIndexFileV2 | undefined {
+    if (this.driver === 'memory') {
+      return this.memoryIndex
+        ? {
+            ...this.memoryIndex,
+            contexts: Object.fromEntries(Object.entries(this.memoryIndex.contexts).map(([key, value]) => [key, cloneEntry(value)])),
+          }
+        : undefined
+    }
+
+    const parsed = this.readParsedCacheFileSync(false)
+    if (parsed.kind !== 'v2') {
+      return undefined
+    }
+
+    return {
+      ...parsed.data,
+      contexts: Object.fromEntries(Object.entries(parsed.data.contexts).map(([key, value]) => [key, cloneEntry(value)])),
+    }
+  }
+}