Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
9.0 KB
Raw Blame
/**
 * Shared, pure ZIP entry-name allocation (folder-zip export). Used by BOTH the
 * renderer walk (which allocates names before sending them, so overlong results
 * are visible skips) and the main-process streaming writer (which re-allocates
 * defensively before writing headers). Pure TS, no Electron/DOM: safe to import
 * from either bundle.
 *
 * The allocation is PATH-AWARE, not name-aware. A ZIP entry name is a path,
 * and every extractor materializes each path component as a real directory.
 * A file named `report` and a directory `Report/` therefore collide on a
 * case-insensitive filesystem (macOS, Windows) even though their full names
 * differ — full-name de-duplication alone silently lets one overwrite the
 * other. The allocator reserves case-folded path PREFIXES next to complete
 * names (R3-M5), and resolves the file/directory conflict deterministically.
 */
import { MAX_ZIP_ENTRY_NAME_BYTES } from './zipLimits.js'

/** A ZIP name field is a 16-bit byte count: names must stay strictly under it. */
export { MAX_ZIP_ENTRY_NAME_BYTES }

export interface FinalizedEntryName {
  /** The name to commit (unchanged, or carrying a ` (n)` collision suffix). */
  name: string
  /** The case-folded key that owns the name in the caller's set. */
  folded: string
}

export const foldEntryName = (name: string): string => name.toLowerCase()

/**
 * True when the FINALIZED name's UTF-8 encoding fits the 16-bit ZIP name
 * fields. Runs on the post-suffix name (R1-M2): a near-limit name whose
 * collision suffix pushes it past the bound must be rejected here, not
 * truncated by the writer.
 */
export function entryNameFitsZipFields(name: string): boolean {
  let bytes = 0
  for (const character of name) {
    if (character.charCodeAt(0) < 0x80) bytes += 1
    else if (character.charCodeAt(0) < 0x800) bytes += 2
    else bytes += character.codePointAt(0)! > 0xffff ? 4 : 3
  }
  return bytes > 0 && bytes < MAX_ZIP_ENTRY_NAME_BYTES
}

/**
 * Splits a base name into stem and extension for ` (n)` suffixing. A LEADING
 * dot is a dotfile, not an extension: `.env` has no extension, so it becomes
 * `.env (2)` rather than `. (2)env`.
 */
function splitBaseName(base: string): { stem: string; extension: string } {
  const dot = base.lastIndexOf('.')
  return dot > 0
    ? { stem: base.slice(0, dot), extension: base.slice(dot) }
    : { stem: base, extension: '' }
}

/** `report.txt` + 2 -> `report (2).txt`. */
function suffixBaseName(base: string, counter: number): string {
  const { stem, extension } = splitBaseName(base)
  return `${stem} (${counter})${extension}`
}

/**
 * `Report` + 2 -> `Report (2)`. A DIRECTORY keeps its whole name: `Report.Data`
 * is a folder called "Report.Data", and `Report (2).Data` would read like a
 * file with an extension.
 */
function suffixDirectoryName(segment: string, counter: number): string {
  return `${segment} (${counter})`
}

/**
 * A name the allocator WOULD commit, computed without reserving anything.
 *
 * The two-phase shape (plan, then commit) is what lets a caller reject an
 * entry — an unusable name, an over-budget entry — without leaving the
 * allocator's reservations behind. A rejected append must leave the job's
 * state exactly as it was (R3-M2).
 */
export interface PlannedEntryName extends FinalizedEntryName {
  /**
   * False when no committed name could carry this entry: the name does not
   * fit the 16-bit ZIP name fields. Such a plan claims nothing.
   */
  fits: boolean
  /** The directory prefixes this plan would claim, as folded -> written. */
  directories: Array<[string, string]>
}

/**
 * Allocates collision-free ZIP entry names for ONE archive.
 *
 * Two namespaces are reserved, and they are mutually exclusive by
 * construction:
 *
 * - complete entry names (`fileNames`) — the full path of every committed file;
 * - directory prefixes (`directories`) — the path of every directory the
 *   committed files imply, mapped to the path actually written.
 *
 * A path may be reserved as a file OR as a directory, never both: allocating a
 * file whose folded path is already a directory renames the FILE, and
 * allocating a directory whose folded path is already a file renames the
 * DIRECTORY segment. That keeps every archive valid on a case-insensitive
 * extractor, in either insertion order.
 */
export class ZipEntryNameAllocator {
  /** Folded full path of every committed file. */
  private readonly fileNames = new Set<string>()
  /** Folded directory prefix -> the directory path actually written. */
  private readonly directories = new Map<string, string>()

  /**
   * Allocates the name to commit for `candidate` and RESERVES it. The returned
   * name differs from the candidate only where a collision forced it.
   */
  allocate(candidate: string): FinalizedEntryName {
    const plan = this.plan(candidate)
    this.commit(plan)
    return { name: plan.name, folded: plan.folded }
  }

  /**
   * Reserves a DIRECTORY path the archive will imply, without claiming a file
   * name for it.
   *
   * Reserving the directories first makes the file/directory resolution
   * independent of the order the entries arrive in: a file whose path would
   * collide with a directory is always the one that gets renamed, whichever
   * order the walk discovered them (R3-M5).
   */
  reserveDirectory(path: string): void {
    const segments = path.split('/')
    const resolved = this.resolveDirectoryPath(segments, new Map())
    for (const [folded, actual] of resolved.claimed) this.directories.set(folded, actual)
  }

  /**
   * Computes the name `candidate` would receive WITHOUT reserving it. The
   * caller commits the plan only once it has accepted the entry.
   */
  plan(candidate: string): PlannedEntryName {
    const segments = candidate.split('/')
    const fileSegment = segments.pop() ?? ''
    const { directoryPath, claimed } = this.resolveDirectoryPath(segments, new Map())

    const fullPath = directoryPath === '' ? fileSegment : `${directoryPath}/${fileSegment}`
    let name = fullPath
    let counter = 1
    while (this.isTaken(foldEntryName(name), claimed)) {
      counter += 1
      name = this.suffixPath(fullPath, counter)
    }
    const fits = entryNameFitsZipFields(name)
    return {
      name,
      folded: foldEntryName(name),
      fits,
      directories: fits ? [...claimed.entries()] : [],
    }
  }

  /**
   * Resolves the directory path a file's segments imply, and the directory
   * prefixes that resolution would claim.
   */
  private resolveDirectoryPath(
    segments: string[],
    claimed: Map<string, string>
  ): { directoryPath: string; claimed: Map<string, string> } {
    let directoryPath = ''
    for (const segment of segments) {
      directoryPath = directoryPath === '' ? segment : `${directoryPath}/${segment}`
      const foldedPrefix = foldEntryName(directoryPath)
      const known = this.directories.get(foldedPrefix) ?? claimed.get(foldedPrefix)
      if (known !== undefined) {
        // The directory was already written under another source directory:
        // reuse the committed path so every file below it stays together.
        directoryPath = known
        continue
      }
      // The prefix is free unless a FILE already owns that exact path: on a
      // case-insensitive extractor a file and a directory cannot share it.
      const resolved = this.fileNames.has(foldedPrefix)
        ? this.allocateDirectorySegment(directoryPath, segment, claimed)
        : directoryPath
      claimed.set(foldEntryName(resolved), resolved)
      directoryPath = resolved
    }
    return { directoryPath, claimed }
  }

  /** Reserves a planned name. A plan that does not fit claims nothing. */
  commit(plan: PlannedEntryName): void {
    if (!plan.fits) return
    for (const [folded, path] of plan.directories) this.directories.set(folded, path)
    this.fileNames.add(plan.folded)
  }

  /** True when the folded path is already owned by a file OR by a directory. */
  private isTaken(folded: string, claimed: ReadonlyMap<string, string>): boolean {
    return this.fileNames.has(folded) || this.directories.has(folded) || claimed.has(folded)
  }

  /** `a/b.txt` + 2 -> `a/b (2).txt`. */
  private suffixPath(fullPath: string, counter: number): string {
    const slash = fullPath.lastIndexOf('/')
    const directory = slash >= 0 ? fullPath.slice(0, slash + 1) : ''
    const base = slash >= 0 ? fullPath.slice(slash + 1) : fullPath
    return `${directory}${suffixBaseName(base, counter)}`
  }

  /**
   * Renames the LAST segment of `directoryPath` so the directory no longer
   * collides with a committed file of the same (case-folded) path.
   */
  private allocateDirectorySegment(
    directoryPath: string,
    segment: string,
    claimed: ReadonlyMap<string, string>
  ): string {
    const parent = directoryPath.slice(0, directoryPath.length - segment.length)
    let counter = 1
    for (;;) {
      counter += 1
      const candidate = `${parent}${suffixDirectoryName(segment, counter)}`
      const folded = foldEntryName(candidate)
      if (!this.fileNames.has(folded) && !this.directories.has(folded) && !claimed.has(folded)) {
        return candidate
      }
    }
  }
}