import { posix } from "node:path"; import { logicalPathNfc } from "../domain/artifactIdentity.js"; import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js"; import { ArtifactReaderFailure } from "./ArtifactReader.js"; const DRIVE_OR_UNC = /^(?:[A-Za-z]:|\\|\/\/)/u; /** * English Unicode case folding used only to describe logical names a * case-insensitive destination might collapse. It is not a filesystem case table. */ const ENGLISH_UNICODE_CASE_NOTE = "This comparison is not a filesystem observation."; /** Inventory limitation when logical names collide under English Unicode case folding. */ export const ENGLISH_UNICODE_CASE_INVENTORY_LIMITATION = `Logical archive names collide under English (en-US) Unicode case folding; a case-insensitive destination cannot store both spellings. ${ENGLISH_UNICODE_CASE_NOTE}`; /** User-facing prefix for a destination that cannot keep two logical spellings. */ export const DESTINATION_CASE_COLLISION_PREFIX = "Destination filesystem cannot store both "; /** Normalize an untrusted logical archive path without touching filesystem. */ export const normalizeArtifactPath = (input: string): string => { if ( input.includes("\0") || input.includes("\\") || input.startsWith("/") || DRIVE_OR_UNC.test(input) ) throw new ArtifactReaderFailure( "path", `Artifact path is absolute or unsafe: ${JSON.stringify(input)}`, ); const normalized = logicalPathNfc(input).replace(/\/+$/u, ""); const parts = normalized.split("/"); if ( normalized.length === 0 || parts.some((part) => part === "" || part === "." || part === "..") || posix.normalize(normalized) !== normalized ) throw new ArtifactReaderFailure( "path", `Artifact path is not normalized: ${JSON.stringify(input)}`, ); return normalized; }; /** Reject exact and same-spelling prefix collisions. Case-distinct names stay distinct. */ export class ArtifactPathRegistry { readonly #root: PathTrieNode = { kind: undefined, children: new Map() }; add(path: string, kind: "file" | "directory" | "symlink" | "slice"): void { const parts = path.split("/"); let node = this.#root; for (const [index, part] of parts.entries()) { if (node.kind !== undefined && node.kind !== "directory") throw new ArtifactReaderFailure( "path", `Artifact prefix conflict: ${path}`, ); let child = node.children.get(part); if (child === undefined) { child = { kind: undefined, children: new Map() }; node.children.set(part, child); } node = child; if (index === parts.length - 1) { if (node.kind !== undefined) throw new ArtifactReaderFailure( "path", `Artifact path collision: ${path}`, ); if (kind !== "directory" && node.children.size > 0) throw new ArtifactReaderFailure( "path", `Artifact prefix conflict: ${path}`, ); } } node.kind = kind; } } interface PathTrieNode { kind: "file" | "directory" | "symlink" | "slice" | undefined; readonly children: Map; } interface CaseNode { readonly bySpelling: Map; readonly spellingsByFold: Map; readonly terminals: string[]; } const emptyCaseNode = (): CaseNode => ({ bySpelling: new Map(), spellingsByFold: new Map(), terminals: [], }); const englishCaseFold = (part: string): string => part.toLocaleLowerCase("en-US"); /** * Record English (en-US) Unicode case collisions on each affected occurrence. * Returns the inventory limitation when any logical names collide. */ export const annotateEnglishUnicodeCaseCollisions = ( occurrences: readonly { readonly logical_path: string; limitations: string[]; }[], ): string | undefined => { const collisions = englishUnicodeCaseCollisions( occurrences.map(({ logical_path }) => logical_path), ); if (collisions.size === 0) return undefined; for (const occurrence of occurrences) for (const collision of collisions.get(occurrence.logical_path) ?? []) occurrence.limitations.push( caseCollisionLimitation(occurrence.logical_path, collision), ); return ENGLISH_UNICODE_CASE_INVENTORY_LIMITATION; }; /** One logical path segment whose spelling folds to another sibling's. */ interface CaseCollision { /** Logical path through the colliding segment. */ readonly prefix: string; /** First other sibling spelling, as a logical path, in code-point order. */ readonly other: string; /** Count of further sibling spellings, each its own occurrence. */ readonly additional: number; } const caseCollisionLimitation = ( path: string, { prefix, other, additional }: CaseCollision, ): string => { const others = additional === 0 ? other : `${other} and ${String(additional)} other spelling${additional === 1 ? "" : "s"}`; const subject = prefix === path ? `Logical path ${path} collides` : `Logical path ${path} is under ${prefix}, which collides`; return `${subject} under English (en-US) Unicode case folding with ${others}; a case-insensitive destination cannot store both. ${ENGLISH_UNICODE_CASE_NOTE}`; }; /** * Name the directory-listing spelling that differs from the requested segment * only by English (en-US) Unicode case. Exact matches are the same logical name. */ export const destinationCaseCollisionMessage = ( requestedPath: string, existingNames: readonly string[], ): string | undefined => { const slash = requestedPath.lastIndexOf("/"); const segment = slash < 0 ? requestedPath : requestedPath.slice(slash + 1); if (existingNames.includes(segment)) return undefined; const folded = englishCaseFold(segment); const existing = existingNames .filter((name) => englishCaseFold(name) === folded) .sort(compareUnicodeCodePoints)[0]; if (existing === undefined) return undefined; const parent = slash < 0 ? "" : requestedPath.slice(0, slash + 1); return `${DESTINATION_CASE_COLLISION_PREFIX}${requestedPath} and ${parent}${existing}; inventory retains both logical names.`; }; const englishUnicodeCaseCollisions = ( paths: readonly string[], ): ReadonlyMap => { const root = emptyCaseNode(); for (const path of paths) { if (path.length === 0 || path === ".") continue; let node = root; for (const part of path.split("/")) { let child = node.bySpelling.get(part); if (child === undefined) { const folded = englishCaseFold(part); const spellings = node.spellingsByFold.get(folded); if (spellings === undefined) node.spellingsByFold.set(folded, [part]); else spellings.push(part); child = emptyCaseNode(); node.bySpelling.set(part, child); } node = child; } node.terminals.push(path); } // A collision is recorded once, at the segment where spellings diverge, and // shared down the subtree. Pairing every descendant of one spelling with // every descendant of another grew quadratically with the subtree sizes. // The walk is iterative because a ZIP name can hold more components than // the call stack allows. const collisions = new Map(); const pending: { readonly node: CaseNode; readonly prefix: string | undefined; readonly chain: CollisionChain | undefined; }[] = [{ node: root, prefix: undefined, chain: undefined }]; for (let item = pending.pop(); item !== undefined; item = pending.pop()) { const { node, prefix, chain } = item; if (chain !== undefined) for (const path of node.terminals) collisions.set(path, collisionsAlong(chain)); for (const spellings of node.spellingsByFold.values()) spellings.sort(compareUnicodeCodePoints); for (const [spelling, child] of node.bySpelling) { const childPrefix = prefix === undefined ? spelling : `${prefix}/${spelling}`; const spellings = node.spellingsByFold.get(englishCaseFold(spelling)) ?? []; const other = spellings[0] === spelling ? spellings[1] : spellings[0]; pending.push({ node: child, prefix: childPrefix, chain: other === undefined ? chain : { collision: { prefix: childPrefix, other: prefix === undefined ? other : `${prefix}/${other}`, additional: spellings.length - 2, }, parent: chain, }, }); } } return collisions; }; /** Collisions on one path, linked from the deepest segment to the root. */ interface CollisionChain { readonly collision: CaseCollision; readonly parent: CollisionChain | undefined; } const collisionsAlong = (chain: CollisionChain): CaseCollision[] => { const collisions: CaseCollision[] = []; let link: CollisionChain | undefined = chain; while (link !== undefined) { collisions.push(link.collision); link = link.parent; } return collisions.reverse(); };