@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/sync/scanners/b2.js

@@ -1,57 +1,241 @@
 import { FileAction } from "../../types/file.js";
-class B2Folder {
-  type = "b2";
-  bucket;
-  prefix;
-  /**
-   * Creates a new B2Folder for the given bucket and optional prefix.
-   * @param bucket - The B2 bucket to scan.
-   * @param prefix - Optional key prefix to restrict the scan scope.
-   */
-  constructor(bucket, prefix = "") {
-    this.bucket = bucket;
-    this.prefix = prefix;
-  }
-  /** Lists all file versions in the bucket, groups by name, and yields the latest visible version. */
-  async *scan() {
-    const grouped = /* @__PURE__ */ new Map();
-    let startFileName;
-    let startFileId;
-    while (true) {
-      const listing = await this.bucket.listFileVersions({
-        ...this.prefix !== "" ? { prefix: this.prefix } : {},
-        ...startFileName !== void 0 ? { startFileName } : {},
-        ...startFileId !== void 0 ? { startFileId } : {}
-      });
-      for (const fv of listing.files) {
-        const existing = grouped.get(fv.fileName);
-        if (existing) {
-          existing.push(fv);
-        } else {
-          grouped.set(fv.fileName, [fv]);
-        }
-      }
-      if (!listing.nextFileName) break;
-      startFileName = listing.nextFileName;
-      startFileId = listing.nextFileId;
-    }
-    const sorted = [...grouped.entries()].sort((a, b) => a[0].localeCompare(b[0]));
-    for (const [fileName, versions] of sorted) {
-      versions.sort((a, b) => b.uploadTimestamp - a.uploadTimestamp);
-      const selected = versions[0];
-      if (!selected || selected.action === FileAction.Hide) continue;
-      const relativePath = this.prefix !== "" ? fileName.slice(this.prefix.length) : fileName;
-      yield {
-        relativePath,
-        modTimeMillis: selected.uploadTimestamp,
-        size: selected.contentLength,
-        selectedVersion: selected,
-        allVersions: versions
-      };
-    }
-  }
-}
-export {
-  B2Folder
+import { validateSyncFilters } from "../regexp-safety.js";
+import { emitScannerSkip, regexpInputTooLongSkip } from "../scan-events.js";
+import { literalPrefixForSyncFilters, pathPassesSyncFilters, pathSkippedByRegExpInputLimit } from "../filters.js";
+import { compareCodeUnits, compareSyncRelativePaths } from "../path-order.js";
+import { assertScanEntryLimit, scanEntryLimit } from "../scan-limit.js";
+import { sanitizeErrorReason } from "../../util/error-reason.js";
+import { isAbortError } from "../local-sha1.js";
+import { selectB2ComparableSha1, syncSha1StateOf } from "../sha1-metadata.js";
+import { assertSyncPathAllowed } from "../path-safety.js";
+import { asRawB2KeyPrefix, b2KeyToRelativePathUnderPrefix, localFilesystemCanonicalSyncPath, localFilesystemSyncPathIsUnsafe } from "../prefix.js";
+//#region src/sync/scanners/b2.ts
+var MAX_EMPTY_B2_SCAN_PAGES = 100;
+/**
+* Scans a B2 bucket (optionally filtered by a raw B2 key prefix) and yields
+* {@link B2SyncPath} entries sorted by `compareSyncRelativePaths(relativePath)`. Hidden files are excluded.
+* Raw B2 file names are used only as an internal tie-breaker after collision handling.
+* All versions for the listed prefix are fetched, grouped, and sorted before
+* yielding; exclude filters are applied client-side and do not reduce that
+* B2 listing memory footprint.
+* SDK-reserved temporary names fail the scan because syncing them could corrupt
+* in-progress transfers.
+*/
+var B2Folder = class {
+	type = "b2";
+	appliesScanFilters = true;
+	appliesScanSorting = true;
+	/** Raw B2 key prefix this folder scans, preserving caller-provided separators verbatim. */
+	rawPrefix;
+	bucket;
+	/**
+	* Creates a new B2Folder for the given bucket and optional prefix.
+	* @param bucket - The B2 bucket to scan.
+	* @param prefix - Optional raw B2 key prefix to restrict the scan scope.
+	* Backslashes are preserved as raw B2 key characters; pass `/` explicitly for slash prefixes.
+	*/
+	constructor(bucket, prefix = "") {
+		this.bucket = bucket;
+		this.rawPrefix = asRawB2KeyPrefix(prefix);
+	}
+	/**
+	* Lists all file versions in the bucket, groups by name, and yields the latest visible version.
+	* @param options - Optional scan controls.
+	*/
+	async *scan(options = {}) {
+		validateSyncFilters(options);
+		const maxScanEntries = scanEntryLimit(options);
+		const grouped = /* @__PURE__ */ new Map();
+		const listPrefix = this.listPrefixFor(options);
+		let listedVersions = 0;
+		let startFileName;
+		let startFileId;
+		let emptyPageCount = 0;
+		while (true) {
+			if (scanIsAborted(options)) return;
+			let listing;
+			try {
+				listing = await this.bucket.listFileVersions({
+					...listPrefix !== "" ? { prefix: listPrefix } : {},
+					...startFileName !== void 0 ? { startFileName } : {},
+					...startFileId !== void 0 ? { startFileId } : {},
+					...options.signal !== void 0 ? { signal: options.signal } : {}
+				});
+			} catch (err) {
+				if (scanIsAborted(options) || isAbortError(err)) return;
+				throw emitScanError(options, "failed to scan B2 file versions", err);
+			}
+			if (scanIsAborted(options)) return;
+			if (listing.files.length === 0) {
+				emptyPageCount++;
+				if (emptyPageCount > MAX_EMPTY_B2_SCAN_PAGES) throw emitScanError(options, "failed to scan B2 file versions", /* @__PURE__ */ new Error("B2 pagination returned too many empty pages"));
+			} else emptyPageCount = 0;
+			for (const fv of listing.files) {
+				if (scanIsAborted(options)) return;
+				assertScanEntryLimit(listedVersions + 1, maxScanEntries);
+				listedVersions++;
+				if (this.rawPrefix !== "" && !fv.fileName.startsWith(this.rawPrefix)) {
+					this.emitSkip(options, fv.fileName, fv.fileName, "outside-prefix", `listed object is outside configured B2 prefix ${JSON.stringify(this.rawPrefix)}`);
+					continue;
+				}
+				if (options.requireLocalSafePaths === true && fv.fileName.includes("\\")) {
+					this.emitSkip(options, fv.fileName, fv.fileName, "local-unsafe-name", "object name contains a backslash that is unsafe for local filesystem destinations");
+					continue;
+				}
+				const relativePath = this.tryToRelativePath(fv.fileName);
+				if (relativePath === null) {
+					this.emitSkip(options, fv.fileName, fv.fileName, "unsafe-name", "object name cannot be represented as a safe sync relative path");
+					continue;
+				}
+				if (!pathPassesSyncFilters(relativePath, options)) {
+					if (pathSkippedByRegExpInputLimit(relativePath, options)) emitScannerSkip(options, {
+						...regexpInputTooLongSkip(relativePath),
+						b2FileName: fv.fileName
+					});
+					continue;
+				}
+				const existing = grouped.get(fv.fileName);
+				if (existing) existing.versions.push(fv);
+				else grouped.set(fv.fileName, {
+					relativePath,
+					versions: [fv]
+				});
+			}
+			if (!listing.nextFileName) break;
+			if (listing.nextFileName === startFileName && (listing.nextFileId ?? void 0) === startFileId) throw emitScanError(options, "failed to scan B2 file versions", /* @__PURE__ */ new Error("B2 pagination did not advance"));
+			startFileName = listing.nextFileName;
+			startFileId = listing.nextFileId ?? void 0;
+		}
+		const visible = this.visibleCandidates(grouped, options);
+		const withoutRelativeCollisions = this.rejectRelativePathCollisions(visible, options);
+		const sorted = (options.requireLocalSafePaths === true ? this.rejectLocalPathCollisions(withoutRelativeCollisions, options) : withoutRelativeCollisions).sort((a, b) => compareSyncRelativePaths(a.relativePath, b.relativePath) || compareCodeUnits(a.fileName, b.fileName));
+		for (const { relativePath, versions, selectedVersion } of sorted) {
+			if (scanIsAborted(options)) return;
+			assertSyncPathAllowed(relativePath);
+			const contentSha1 = selectB2ComparableSha1(selectedVersion);
+			yield {
+				relativePath,
+				modTimeMillis: selectedVersion.uploadTimestamp,
+				size: selectedVersion.contentLength,
+				contentSha1,
+				contentSha1State: syncSha1StateOf({ contentSha1 }),
+				selectedVersion,
+				allVersions: versions
+			};
+		}
+	}
+	tryToRelativePath(fileName) {
+		try {
+			return b2KeyToRelativePathUnderPrefix(this.rawPrefix, fileName);
+		} catch {
+			return null;
+		}
+	}
+	listPrefixFor(filters) {
+		const filterPrefix = literalPrefixForSyncFilters(filters);
+		if (filterPrefix === "") return this.rawPrefix;
+		if (this.rawPrefix !== "" && !this.rawPrefix.endsWith("/")) return this.rawPrefix;
+		return `${this.rawPrefix}${rawPrefixBeforeNormalizedSeparator(filterPrefix)}`;
+	}
+	visibleCandidates(grouped, filters) {
+		const visible = [];
+		for (const [fileName, entry] of grouped) {
+			entry.versions.sort((a, b) => b.uploadTimestamp - a.uploadTimestamp);
+			const selected = entry.versions[0];
+			if (!selected || selected.action === FileAction.Hide) continue;
+			if (filters?.requireLocalSafePaths === true && localFilesystemSyncPathIsUnsafe(entry.relativePath)) {
+				this.emitSkip(filters, entry.relativePath, fileName, "local-unsafe-name", "object name is unsafe for a local filesystem destination");
+				continue;
+			}
+			visible.push({
+				fileName,
+				relativePath: entry.relativePath,
+				versions: entry.versions,
+				selectedVersion: selected
+			});
+		}
+		return visible;
+	}
+	rejectRelativePathCollisions(candidates, filters) {
+		const accepted = [];
+		const owners = /* @__PURE__ */ new Map();
+		const collidedRelativePaths = /* @__PURE__ */ new Set();
+		for (const candidate of candidates) {
+			if (collidedRelativePaths.has(candidate.relativePath)) {
+				this.emitSkip(filters, candidate.relativePath, candidate.fileName, "relative-path-collision", "object normalizes to a relative path already rejected because of another raw B2 key");
+				continue;
+			}
+			const owner = owners.get(candidate.relativePath);
+			if (owner !== void 0 && owner.fileName !== candidate.fileName) {
+				owners.delete(candidate.relativePath);
+				removeAcceptedCandidate(accepted, owner);
+				collidedRelativePaths.add(candidate.relativePath);
+				this.emitSkip(filters, candidate.relativePath, owner.fileName, "relative-path-collision", `object normalizes to the same relative path as ${JSON.stringify(candidate.fileName)}`);
+				this.emitSkip(filters, candidate.relativePath, candidate.fileName, "relative-path-collision", `object normalizes to the same relative path as ${JSON.stringify(owner.fileName)}`);
+				continue;
+			}
+			owners.set(candidate.relativePath, candidate);
+			accepted.push(candidate);
+		}
+		return accepted;
+	}
+	rejectLocalPathCollisions(candidates, filters) {
+		const accepted = [];
+		const owners = /* @__PURE__ */ new Map();
+		const collidedLocalPaths = /* @__PURE__ */ new Set();
+		for (const candidate of candidates) {
+			const canonicalPath = localFilesystemCanonicalSyncPath(candidate.relativePath);
+			if (collidedLocalPaths.has(canonicalPath)) {
+				this.emitSkip(filters, candidate.relativePath, candidate.fileName, "local-path-collision", "object collides with another object on case-insensitive or Unicode-normalizing filesystems");
+				continue;
+			}
+			const owner = owners.get(canonicalPath);
+			if (owner !== void 0) {
+				owners.delete(canonicalPath);
+				removeAcceptedCandidate(accepted, owner);
+				collidedLocalPaths.add(canonicalPath);
+				this.emitSkip(filters, owner.relativePath, owner.fileName, "local-path-collision", `object collides with ${JSON.stringify(candidate.fileName)} on local filesystems`);
+				this.emitSkip(filters, candidate.relativePath, candidate.fileName, "local-path-collision", `object collides with ${JSON.stringify(owner.fileName)} on local filesystems`);
+				continue;
+			}
+			owners.set(canonicalPath, candidate);
+			accepted.push(candidate);
+		}
+		return accepted;
+	}
+	emitSkip(filters, path, b2FileName, reason, message) {
+		emitScannerSkip(filters, {
+			type: "skip",
+			path,
+			size: 0,
+			message: `Skipped B2 object ${JSON.stringify(b2FileName)}: ${message}`,
+			reason,
+			b2FileName
+		});
+	}
 };
-//# sourceMappingURL=b2.js.map
+function rawPrefixBeforeNormalizedSeparator(filterPrefix) {
+	const separatorIndex = filterPrefix.indexOf("/");
+	return separatorIndex === -1 ? filterPrefix : filterPrefix.slice(0, separatorIndex);
+}
+function emitScanError(options, message, err) {
+	const event = {
+		type: "error",
+		path: "",
+		size: 0,
+		message: `${message}: ${sanitizeErrorReason(err)}`
+	};
+	options.onError?.(event);
+	return new Error(event.message);
+}
+function removeAcceptedCandidate(candidates, target) {
+	const index = candidates.indexOf(target);
+	if (index !== -1) candidates.splice(index, 1);
+}
+function scanIsAborted(filters) {
+	return filters?.signal?.aborted === true;
+}
+//#endregion
+export { B2Folder };
+
+//# sourceMappingURL=b2.js.map

package/dist/sync/scanners/b2.js.map

@@ -1 +1 @@
-{"version":3,"file":"b2.js","sources":["../../../src/sync/scanners/b2.ts"],"sourcesContent":["import type { Bucket } from '../../bucket.ts'\nimport { FileAction, type FileVersion } from '../../types/file.ts'\nimport type { B2SyncPath, SyncFolder } from '../types.ts'\n\n/**\n * Scans a B2 bucket (optionally filtered by prefix) and yields {@link B2SyncPath} entries\n * sorted by file name. Hidden files are excluded. All versions are fetched and grouped.\n */\nexport class B2Folder implements SyncFolder {\n  readonly type = 'b2' as const\n  private readonly bucket: Bucket\n  private readonly prefix: string\n\n  /**\n   * Creates a new B2Folder for the given bucket and optional prefix.\n   * @param bucket - The B2 bucket to scan.\n   * @param prefix - Optional key prefix to restrict the scan scope.\n   */\n  constructor(bucket: Bucket, prefix = '') {\n    this.bucket = bucket\n    this.prefix = prefix\n  }\n\n  /** Lists all file versions in the bucket, groups by name, and yields the latest visible version. */\n  async *scan(): AsyncGenerator<B2SyncPath> {\n    const grouped = new Map<string, FileVersion[]>()\n\n    let startFileName: string | undefined\n    let startFileId: string | undefined\n\n    while (true) {\n      const listing = await this.bucket.listFileVersions({\n        ...(this.prefix !== '' ? { prefix: this.prefix } : {}),\n        ...(startFileName !== undefined ? { startFileName } : {}),\n        ...(startFileId !== undefined\n          ? { startFileId: startFileId as import('../../types/ids.ts').FileId }\n          : {}),\n      })\n\n      for (const fv of listing.files) {\n        const existing = grouped.get(fv.fileName)\n        if (existing) {\n          existing.push(fv)\n        } else {\n          grouped.set(fv.fileName, [fv])\n        }\n      }\n\n      if (!listing.nextFileName) break\n      startFileName = listing.nextFileName\n      startFileId = listing.nextFileId as string | undefined\n    }\n\n    const sorted = [...grouped.entries()].sort((a, b) => a[0].localeCompare(b[0]))\n\n    for (const [fileName, versions] of sorted) {\n      versions.sort((a, b) => b.uploadTimestamp - a.uploadTimestamp)\n      const selected = versions[0]\n      if (!selected || selected.action === FileAction.Hide) continue\n\n      const relativePath = this.prefix !== '' ? fileName.slice(this.prefix.length) : fileName\n\n      yield {\n        relativePath,\n        modTimeMillis: selected.uploadTimestamp,\n        size: selected.contentLength,\n        selectedVersion: selected,\n        allVersions: versions,\n      }\n    }\n  }\n}\n"],"names":[],"mappings":";AAQO,MAAM,SAA+B;AAAA,EACjC,OAAO;AAAA,EACC;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOjB,YAAY,QAAgB,SAAS,IAAI;AACvC,SAAK,SAAS;AACd,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA,EAGA,OAAO,OAAmC;AACxC,UAAM,8BAAc,IAAA;AAEpB,QAAI;AACJ,QAAI;AAEJ,WAAO,MAAM;AACX,YAAM,UAAU,MAAM,KAAK,OAAO,iBAAiB;AAAA,QACjD,GAAI,KAAK,WAAW,KAAK,EAAE,QAAQ,KAAK,OAAA,IAAW,CAAA;AAAA,QACnD,GAAI,kBAAkB,SAAY,EAAE,cAAA,IAAkB,CAAA;AAAA,QACtD,GAAI,gBAAgB,SAChB,EAAE,gBACF,CAAA;AAAA,MAAC,CACN;AAED,iBAAW,MAAM,QAAQ,OAAO;AAC9B,cAAM,WAAW,QAAQ,IAAI,GAAG,QAAQ;AACxC,YAAI,UAAU;AACZ,mBAAS,KAAK,EAAE;AAAA,QAClB,OAAO;AACL,kBAAQ,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC;AAAA,QAC/B;AAAA,MACF;AAEA,UAAI,CAAC,QAAQ,aAAc;AAC3B,sBAAgB,QAAQ;AACxB,oBAAc,QAAQ;AAAA,IACxB;AAEA,UAAM,SAAS,CAAC,GAAG,QAAQ,QAAA,CAAS,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;AAE7E,eAAW,CAAC,UAAU,QAAQ,KAAK,QAAQ;AACzC,eAAS,KAAK,CAAC,GAAG,MAAM,EAAE,kBAAkB,EAAE,eAAe;AAC7D,YAAM,WAAW,SAAS,CAAC;AAC3B,UAAI,CAAC,YAAY,SAAS,WAAW,WAAW,KAAM;AAEtD,YAAM,eAAe,KAAK,WAAW,KAAK,SAAS,MAAM,KAAK,OAAO,MAAM,IAAI;AAE/E,YAAM;AAAA,QACJ;AAAA,QACA,eAAe,SAAS;AAAA,QACxB,MAAM,SAAS;AAAA,QACf,iBAAiB;AAAA,QACjB,aAAa;AAAA,MAAA;AAAA,IAEjB;AAAA,EACF;AACF;"}
+{"version":3,"file":"b2.js","names":[],"sources":["../../../src/sync/scanners/b2.ts"],"sourcesContent":["import type { Bucket } from '../../bucket.ts'\nimport { FileAction, type FileVersion } from '../../types/file.ts'\nimport type { FileId } from '../../types/ids.ts'\nimport { sanitizeErrorReason } from '../../util/error-reason.ts'\nimport {\n  literalPrefixForSyncFilters,\n  pathPassesSyncFilters,\n  pathSkippedByRegExpInputLimit,\n} from '../filters.ts'\nimport { isAbortError } from '../local-sha1.ts'\nimport { compareCodeUnits, compareSyncRelativePaths } from '../path-order.ts'\nimport { assertSyncPathAllowed } from '../paths.ts'\nimport {\n  asRawB2KeyPrefix,\n  b2KeyToRelativePathUnderPrefix,\n  localFilesystemCanonicalSyncPath,\n  localFilesystemSyncPathIsUnsafe,\n} from '../prefix.ts'\nimport { validateSyncFilters } from '../regexp-safety.ts'\nimport { emitScannerSkip, regexpInputTooLongSkip } from '../scan-events.ts'\nimport { assertScanEntryLimit, scanEntryLimit } from '../scan-limit.ts'\nimport { selectB2ComparableSha1, syncSha1StateOf } from '../sha1-metadata.ts'\nimport type {\n  B2SyncPath,\n  SyncErrorEvent,\n  SyncFolder,\n  SyncScanOptions,\n  SyncSkipReason,\n} from '../types.ts'\n\nconst MAX_EMPTY_B2_SCAN_PAGES = 100\n\ninterface B2ScanEntry {\n  relativePath: string\n  versions: FileVersion[]\n}\n\ninterface VisibleB2ScanEntry extends B2ScanEntry {\n  fileName: string\n  selectedVersion: FileVersion\n}\n\n/**\n * Scans a B2 bucket (optionally filtered by a raw B2 key prefix) and yields\n * {@link B2SyncPath} entries sorted by `compareSyncRelativePaths(relativePath)`. Hidden files are excluded.\n * Raw B2 file names are used only as an internal tie-breaker after collision handling.\n * All versions for the listed prefix are fetched, grouped, and sorted before\n * yielding; exclude filters are applied client-side and do not reduce that\n * B2 listing memory footprint.\n * SDK-reserved temporary names fail the scan because syncing them could corrupt\n * in-progress transfers.\n */\nexport class B2Folder implements SyncFolder {\n  readonly type = 'b2' as const\n  readonly appliesScanFilters = true as const\n  readonly appliesScanSorting = true as const\n  /** Raw B2 key prefix this folder scans, preserving caller-provided separators verbatim. */\n  readonly rawPrefix: string\n  private readonly bucket: Bucket\n\n  /**\n   * Creates a new B2Folder for the given bucket and optional prefix.\n   * @param bucket - The B2 bucket to scan.\n   * @param prefix - Optional raw B2 key prefix to restrict the scan scope.\n   * Backslashes are preserved as raw B2 key characters; pass `/` explicitly for slash prefixes.\n   */\n  constructor(bucket: Bucket, prefix = '') {\n    this.bucket = bucket\n    this.rawPrefix = asRawB2KeyPrefix(prefix)\n  }\n\n  /**\n   * Lists all file versions in the bucket, groups by name, and yields the latest visible version.\n   * @param options - Optional scan controls.\n   */\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: pagination, grouping, and filtering stay in one async iterator.\n  async *scan(options: SyncScanOptions = {}): AsyncGenerator<B2SyncPath> {\n    validateSyncFilters(options)\n    const maxScanEntries = scanEntryLimit(options)\n    const grouped = new Map<string, B2ScanEntry>()\n    const listPrefix = this.listPrefixFor(options)\n\n    let listedVersions = 0\n    let startFileName: string | undefined\n    let startFileId: FileId | undefined\n    let emptyPageCount = 0\n\n    while (true) {\n      if (scanIsAborted(options)) return\n\n      let listing: Awaited<ReturnType<Bucket['listFileVersions']>>\n      try {\n        listing = await this.bucket.listFileVersions({\n          ...(listPrefix !== '' ? { prefix: listPrefix } : {}),\n          ...(startFileName !== undefined ? { startFileName } : {}),\n          ...(startFileId !== undefined ? { startFileId } : {}),\n          ...(options.signal !== undefined ? { signal: options.signal } : {}),\n        })\n      } catch (err) {\n        if (scanIsAborted(options) || isAbortError(err)) return\n        throw emitScanError(options, 'failed to scan B2 file versions', err)\n      }\n      if (scanIsAborted(options)) return\n\n      if (listing.files.length === 0) {\n        emptyPageCount++\n        if (emptyPageCount > MAX_EMPTY_B2_SCAN_PAGES) {\n          throw emitScanError(\n            options,\n            'failed to scan B2 file versions',\n            new Error('B2 pagination returned too many empty pages'),\n          )\n        }\n      } else {\n        emptyPageCount = 0\n      }\n\n      for (const fv of listing.files) {\n        if (scanIsAborted(options)) return\n        assertScanEntryLimit(listedVersions + 1, maxScanEntries)\n        listedVersions++\n\n        // Real B2 honors the prefix in listFileVersions, but custom\n        // transports and the simulator can over-return. Guard before\n        // stripping the raw prefix so relativePath is never corrupted.\n        if (this.rawPrefix !== '' && !fv.fileName.startsWith(this.rawPrefix)) {\n          this.emitSkip(\n            options,\n            fv.fileName,\n            fv.fileName,\n            'outside-prefix',\n            `listed object is outside configured B2 prefix ${JSON.stringify(this.rawPrefix)}`,\n          )\n          continue\n        }\n\n        if (options.requireLocalSafePaths === true && fv.fileName.includes('\\\\')) {\n          this.emitSkip(\n            options,\n            fv.fileName,\n            fv.fileName,\n            'local-unsafe-name',\n            'object name contains a backslash that is unsafe for local filesystem destinations',\n          )\n          continue\n        }\n\n        const relativePath = this.tryToRelativePath(fv.fileName)\n        if (relativePath === null) {\n          this.emitSkip(\n            options,\n            fv.fileName,\n            fv.fileName,\n            'unsafe-name',\n            'object name cannot be represented as a safe sync relative path',\n          )\n          continue\n        }\n\n        if (!pathPassesSyncFilters(relativePath, options)) {\n          if (pathSkippedByRegExpInputLimit(relativePath, options)) {\n            emitScannerSkip(options, {\n              ...regexpInputTooLongSkip(relativePath),\n              b2FileName: fv.fileName,\n            })\n          }\n          continue\n        }\n\n        const existing = grouped.get(fv.fileName)\n        if (existing) {\n          existing.versions.push(fv)\n        } else {\n          grouped.set(fv.fileName, { relativePath, versions: [fv] })\n        }\n      }\n\n      if (!listing.nextFileName) break\n      if (\n        listing.nextFileName === startFileName &&\n        (listing.nextFileId ?? undefined) === startFileId\n      ) {\n        throw emitScanError(\n          options,\n          'failed to scan B2 file versions',\n          new Error('B2 pagination did not advance'),\n        )\n      }\n      startFileName = listing.nextFileName\n      startFileId = listing.nextFileId ?? undefined\n    }\n\n    const visible = this.visibleCandidates(grouped, options)\n    const withoutRelativeCollisions = this.rejectRelativePathCollisions(visible, options)\n    const safeCandidates =\n      options.requireLocalSafePaths === true\n        ? this.rejectLocalPathCollisions(withoutRelativeCollisions, options)\n        : withoutRelativeCollisions\n    const sorted = safeCandidates.sort(\n      (a, b) =>\n        compareSyncRelativePaths(a.relativePath, b.relativePath) ||\n        compareCodeUnits(a.fileName, b.fileName),\n    )\n\n    for (const { relativePath, versions, selectedVersion } of sorted) {\n      if (scanIsAborted(options)) return\n      // Reserved SDK temp names are a hard safety failure, not an ordinary filter.\n      assertSyncPathAllowed(relativePath)\n      const contentSha1 = selectB2ComparableSha1(selectedVersion)\n      yield {\n        relativePath,\n        modTimeMillis: selectedVersion.uploadTimestamp,\n        size: selectedVersion.contentLength,\n        contentSha1,\n        contentSha1State: syncSha1StateOf({ contentSha1 }),\n        selectedVersion,\n        allVersions: versions,\n      }\n    }\n  }\n\n  private tryToRelativePath(fileName: string): string | null {\n    try {\n      return b2KeyToRelativePathUnderPrefix(this.rawPrefix, fileName)\n    } catch {\n      return null\n    }\n  }\n\n  private listPrefixFor(filters: SyncScanOptions | undefined): string {\n    const filterPrefix = literalPrefixForSyncFilters(filters)\n    if (filterPrefix === '') return this.rawPrefix\n    if (this.rawPrefix !== '' && !this.rawPrefix.endsWith('/')) return this.rawPrefix\n    return `${this.rawPrefix}${rawPrefixBeforeNormalizedSeparator(filterPrefix)}`\n  }\n\n  private visibleCandidates(\n    grouped: Map<string, B2ScanEntry>,\n    filters: SyncScanOptions | undefined,\n  ): VisibleB2ScanEntry[] {\n    const visible: VisibleB2ScanEntry[] = []\n\n    for (const [fileName, entry] of grouped) {\n      entry.versions.sort((a, b) => b.uploadTimestamp - a.uploadTimestamp)\n      const selected = entry.versions[0]\n      if (!selected || selected.action === FileAction.Hide) continue\n\n      if (\n        filters?.requireLocalSafePaths === true &&\n        localFilesystemSyncPathIsUnsafe(entry.relativePath)\n      ) {\n        this.emitSkip(\n          filters,\n          entry.relativePath,\n          fileName,\n          'local-unsafe-name',\n          'object name is unsafe for a local filesystem destination',\n        )\n        continue\n      }\n\n      visible.push({\n        fileName,\n        relativePath: entry.relativePath,\n        versions: entry.versions,\n        selectedVersion: selected,\n      })\n    }\n\n    return visible\n  }\n\n  private rejectRelativePathCollisions(\n    candidates: VisibleB2ScanEntry[],\n    filters: SyncScanOptions | undefined,\n  ): VisibleB2ScanEntry[] {\n    const accepted: VisibleB2ScanEntry[] = []\n    const owners = new Map<string, VisibleB2ScanEntry>()\n    const collidedRelativePaths = new Set<string>()\n\n    for (const candidate of candidates) {\n      if (collidedRelativePaths.has(candidate.relativePath)) {\n        this.emitSkip(\n          filters,\n          candidate.relativePath,\n          candidate.fileName,\n          'relative-path-collision',\n          'object normalizes to a relative path already rejected because of another raw B2 key',\n        )\n        continue\n      }\n\n      const owner = owners.get(candidate.relativePath)\n      if (owner !== undefined && owner.fileName !== candidate.fileName) {\n        owners.delete(candidate.relativePath)\n        removeAcceptedCandidate(accepted, owner)\n        collidedRelativePaths.add(candidate.relativePath)\n        this.emitSkip(\n          filters,\n          candidate.relativePath,\n          owner.fileName,\n          'relative-path-collision',\n          `object normalizes to the same relative path as ${JSON.stringify(candidate.fileName)}`,\n        )\n        this.emitSkip(\n          filters,\n          candidate.relativePath,\n          candidate.fileName,\n          'relative-path-collision',\n          `object normalizes to the same relative path as ${JSON.stringify(owner.fileName)}`,\n        )\n        continue\n      }\n\n      owners.set(candidate.relativePath, candidate)\n      accepted.push(candidate)\n    }\n\n    return accepted\n  }\n\n  private rejectLocalPathCollisions(\n    candidates: VisibleB2ScanEntry[],\n    filters: SyncScanOptions | undefined,\n  ): VisibleB2ScanEntry[] {\n    const accepted: VisibleB2ScanEntry[] = []\n    const owners = new Map<string, VisibleB2ScanEntry>()\n    const collidedLocalPaths = new Set<string>()\n\n    for (const candidate of candidates) {\n      const canonicalPath = localFilesystemCanonicalSyncPath(candidate.relativePath)\n      if (collidedLocalPaths.has(canonicalPath)) {\n        this.emitSkip(\n          filters,\n          candidate.relativePath,\n          candidate.fileName,\n          'local-path-collision',\n          'object collides with another object on case-insensitive or Unicode-normalizing filesystems',\n        )\n        continue\n      }\n\n      const owner = owners.get(canonicalPath)\n      if (owner !== undefined) {\n        owners.delete(canonicalPath)\n        removeAcceptedCandidate(accepted, owner)\n        collidedLocalPaths.add(canonicalPath)\n        this.emitSkip(\n          filters,\n          owner.relativePath,\n          owner.fileName,\n          'local-path-collision',\n          `object collides with ${JSON.stringify(candidate.fileName)} on local filesystems`,\n        )\n        this.emitSkip(\n          filters,\n          candidate.relativePath,\n          candidate.fileName,\n          'local-path-collision',\n          `object collides with ${JSON.stringify(owner.fileName)} on local filesystems`,\n        )\n        continue\n      }\n\n      owners.set(canonicalPath, candidate)\n      accepted.push(candidate)\n    }\n\n    return accepted\n  }\n\n  private emitSkip(\n    filters: SyncScanOptions | undefined,\n    path: string,\n    b2FileName: string,\n    reason: SyncSkipReason,\n    message: string,\n  ): void {\n    emitScannerSkip(filters, {\n      type: 'skip',\n      path,\n      size: 0,\n      message: `Skipped B2 object ${JSON.stringify(b2FileName)}: ${message}`,\n      reason,\n      b2FileName,\n    })\n  }\n}\n\nfunction rawPrefixBeforeNormalizedSeparator(filterPrefix: string): string {\n  const separatorIndex = filterPrefix.indexOf('/')\n  return separatorIndex === -1 ? filterPrefix : filterPrefix.slice(0, separatorIndex)\n}\n\nfunction emitScanError(options: SyncScanOptions, message: string, err: unknown): Error {\n  const event: SyncErrorEvent = {\n    type: 'error',\n    path: '',\n    size: 0,\n    message: `${message}: ${sanitizeErrorReason(err)}`,\n  }\n  options.onError?.(event)\n  return new Error(event.message)\n}\n\nfunction removeAcceptedCandidate(\n  candidates: VisibleB2ScanEntry[],\n  target: VisibleB2ScanEntry,\n): void {\n  const index = candidates.indexOf(target)\n  if (index !== -1) candidates.splice(index, 1)\n}\n\nfunction scanIsAborted(filters: SyncScanOptions | undefined): boolean {\n  return filters?.signal?.aborted === true\n}\n"],"mappings":";;;;;;;;;;;;AA8BA,IAAM,0BAA0B;;;;;;;;;;;AAsBhC,IAAa,WAAb,MAA4C;CAC1C,OAAgB;CAChB,qBAA8B;CAC9B,qBAA8B;;CAE9B;CACA;;;;;;;CAQA,YAAY,QAAgB,SAAS,IAAI;EACvC,KAAK,SAAS;EACd,KAAK,YAAY,iBAAiB,MAAM;CAC1C;;;;;CAOA,OAAO,KAAK,UAA2B,CAAC,GAA+B;EACrE,oBAAoB,OAAO;EAC3B,MAAM,iBAAiB,eAAe,OAAO;EAC7C,MAAM,0BAAU,IAAI,IAAyB;EAC7C,MAAM,aAAa,KAAK,cAAc,OAAO;EAE7C,IAAI,iBAAiB;EACrB,IAAI;EACJ,IAAI;EACJ,IAAI,iBAAiB;EAErB,OAAO,MAAM;GACX,IAAI,cAAc,OAAO,GAAG;GAE5B,IAAI;GACJ,IAAI;IACF,UAAU,MAAM,KAAK,OAAO,iBAAiB;KAC3C,GAAI,eAAe,KAAK,EAAE,QAAQ,WAAW,IAAI,CAAC;KAClD,GAAI,kBAAkB,KAAA,IAAY,EAAE,cAAc,IAAI,CAAC;KACvD,GAAI,gBAAgB,KAAA,IAAY,EAAE,YAAY,IAAI,CAAC;KACnD,GAAI,QAAQ,WAAW,KAAA,IAAY,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;IACnE,CAAC;GACH,SAAS,KAAK;IACZ,IAAI,cAAc,OAAO,KAAK,aAAa,GAAG,GAAG;IACjD,MAAM,cAAc,SAAS,mCAAmC,GAAG;GACrE;GACA,IAAI,cAAc,OAAO,GAAG;GAE5B,IAAI,QAAQ,MAAM,WAAW,GAAG;IAC9B;IACA,IAAI,iBAAiB,yBACnB,MAAM,cACJ,SACA,mDACA,IAAI,MAAM,6CAA6C,CACzD;GAEJ,OACE,iBAAiB;GAGnB,KAAK,MAAM,MAAM,QAAQ,OAAO;IAC9B,IAAI,cAAc,OAAO,GAAG;IAC5B,qBAAqB,iBAAiB,GAAG,cAAc;IACvD;IAKA,IAAI,KAAK,cAAc,MAAM,CAAC,GAAG,SAAS,WAAW,KAAK,SAAS,GAAG;KACpE,KAAK,SACH,SACA,GAAG,UACH,GAAG,UACH,kBACA,iDAAiD,KAAK,UAAU,KAAK,SAAS,GAChF;KACA;IACF;IAEA,IAAI,QAAQ,0BAA0B,QAAQ,GAAG,SAAS,SAAS,IAAI,GAAG;KACxE,KAAK,SACH,SACA,GAAG,UACH,GAAG,UACH,qBACA,mFACF;KACA;IACF;IAEA,MAAM,eAAe,KAAK,kBAAkB,GAAG,QAAQ;IACvD,IAAI,iBAAiB,MAAM;KACzB,KAAK,SACH,SACA,GAAG,UACH,GAAG,UACH,eACA,gEACF;KACA;IACF;IAEA,IAAI,CAAC,sBAAsB,cAAc,OAAO,GAAG;KACjD,IAAI,8BAA8B,cAAc,OAAO,GACrD,gBAAgB,SAAS;MACvB,GAAG,uBAAuB,YAAY;MACtC,YAAY,GAAG;KACjB,CAAC;KAEH;IACF;IAEA,MAAM,WAAW,QAAQ,IAAI,GAAG,QAAQ;IACxC,IAAI,UACF,SAAS,SAAS,KAAK,EAAE;SAEzB,QAAQ,IAAI,GAAG,UAAU;KAAE;KAAc,UAAU,CAAC,EAAE;IAAE,CAAC;GAE7D;GAEA,IAAI,CAAC,QAAQ,cAAc;GAC3B,IACE,QAAQ,iBAAiB,kBACxB,QAAQ,cAAc,KAAA,OAAe,aAEtC,MAAM,cACJ,SACA,mDACA,IAAI,MAAM,+BAA+B,CAC3C;GAEF,gBAAgB,QAAQ;GACxB,cAAc,QAAQ,cAAc,KAAA;EACtC;EAEA,MAAM,UAAU,KAAK,kBAAkB,SAAS,OAAO;EACvD,MAAM,4BAA4B,KAAK,6BAA6B,SAAS,OAAO;EAKpF,MAAM,UAHJ,QAAQ,0BAA0B,OAC9B,KAAK,0BAA0B,2BAA2B,OAAO,IACjE,0BAAA,CACwB,MAC3B,GAAG,MACF,yBAAyB,EAAE,cAAc,EAAE,YAAY,KACvD,iBAAiB,EAAE,UAAU,EAAE,QAAQ,CAC3C;EAEA,KAAK,MAAM,EAAE,cAAc,UAAU,qBAAqB,QAAQ;GAChE,IAAI,cAAc,OAAO,GAAG;GAE5B,sBAAsB,YAAY;GAClC,MAAM,cAAc,uBAAuB,eAAe;GAC1D,MAAM;IACJ;IACA,eAAe,gBAAgB;IAC/B,MAAM,gBAAgB;IACtB;IACA,kBAAkB,gBAAgB,EAAE,YAAY,CAAC;IACjD;IACA,aAAa;GACf;EACF;CACF;CAEA,kBAA0B,UAAiC;EACzD,IAAI;GACF,OAAO,+BAA+B,KAAK,WAAW,QAAQ;EAChE,QAAQ;GACN,OAAO;EACT;CACF;CAEA,cAAsB,SAA8C;EAClE,MAAM,eAAe,4BAA4B,OAAO;EACxD,IAAI,iBAAiB,IAAI,OAAO,KAAK;EACrC,IAAI,KAAK,cAAc,MAAM,CAAC,KAAK,UAAU,SAAS,GAAG,GAAG,OAAO,KAAK;EACxE,OAAO,GAAG,KAAK,YAAY,mCAAmC,YAAY;CAC5E;CAEA,kBACE,SACA,SACsB;EACtB,MAAM,UAAgC,CAAC;EAEvC,KAAK,MAAM,CAAC,UAAU,UAAU,SAAS;GACvC,MAAM,SAAS,MAAM,GAAG,MAAM,EAAE,kBAAkB,EAAE,eAAe;GACnE,MAAM,WAAW,MAAM,SAAS;GAChC,IAAI,CAAC,YAAY,SAAS,WAAW,WAAW,MAAM;GAEtD,IACE,SAAS,0BAA0B,QACnC,gCAAgC,MAAM,YAAY,GAClD;IACA,KAAK,SACH,SACA,MAAM,cACN,UACA,qBACA,0DACF;IACA;GACF;GAEA,QAAQ,KAAK;IACX;IACA,cAAc,MAAM;IACpB,UAAU,MAAM;IAChB,iBAAiB;GACnB,CAAC;EACH;EAEA,OAAO;CACT;CAEA,6BACE,YACA,SACsB;EACtB,MAAM,WAAiC,CAAC;EACxC,MAAM,yBAAS,IAAI,IAAgC;EACnD,MAAM,wCAAwB,IAAI,IAAY;EAE9C,KAAK,MAAM,aAAa,YAAY;GAClC,IAAI,sBAAsB,IAAI,UAAU,YAAY,GAAG;IACrD,KAAK,SACH,SACA,UAAU,cACV,UAAU,UACV,2BACA,qFACF;IACA;GACF;GAEA,MAAM,QAAQ,OAAO,IAAI,UAAU,YAAY;GAC/C,IAAI,UAAU,KAAA,KAAa,MAAM,aAAa,UAAU,UAAU;IAChE,OAAO,OAAO,UAAU,YAAY;IACpC,wBAAwB,UAAU,KAAK;IACvC,sBAAsB,IAAI,UAAU,YAAY;IAChD,KAAK,SACH,SACA,UAAU,cACV,MAAM,UACN,2BACA,kDAAkD,KAAK,UAAU,UAAU,QAAQ,GACrF;IACA,KAAK,SACH,SACA,UAAU,cACV,UAAU,UACV,2BACA,kDAAkD,KAAK,UAAU,MAAM,QAAQ,GACjF;IACA;GACF;GAEA,OAAO,IAAI,UAAU,cAAc,SAAS;GAC5C,SAAS,KAAK,SAAS;EACzB;EAEA,OAAO;CACT;CAEA,0BACE,YACA,SACsB;EACtB,MAAM,WAAiC,CAAC;EACxC,MAAM,yBAAS,IAAI,IAAgC;EACnD,MAAM,qCAAqB,IAAI,IAAY;EAE3C,KAAK,MAAM,aAAa,YAAY;GAClC,MAAM,gBAAgB,iCAAiC,UAAU,YAAY;GAC7E,IAAI,mBAAmB,IAAI,aAAa,GAAG;IACzC,KAAK,SACH,SACA,UAAU,cACV,UAAU,UACV,wBACA,4FACF;IACA;GACF;GAEA,MAAM,QAAQ,OAAO,IAAI,aAAa;GACtC,IAAI,UAAU,KAAA,GAAW;IACvB,OAAO,OAAO,aAAa;IAC3B,wBAAwB,UAAU,KAAK;IACvC,mBAAmB,IAAI,aAAa;IACpC,KAAK,SACH,SACA,MAAM,cACN,MAAM,UACN,wBACA,wBAAwB,KAAK,UAAU,UAAU,QAAQ,EAAE,sBAC7D;IACA,KAAK,SACH,SACA,UAAU,cACV,UAAU,UACV,wBACA,wBAAwB,KAAK,UAAU,MAAM,QAAQ,EAAE,sBACzD;IACA;GACF;GAEA,OAAO,IAAI,eAAe,SAAS;GACnC,SAAS,KAAK,SAAS;EACzB;EAEA,OAAO;CACT;CAEA,SACE,SACA,MACA,YACA,QACA,SACM;EACN,gBAAgB,SAAS;GACvB,MAAM;GACN;GACA,MAAM;GACN,SAAS,qBAAqB,KAAK,UAAU,UAAU,EAAE,IAAI;GAC7D;GACA;EACF,CAAC;CACH;AACF;AAEA,SAAS,mCAAmC,cAA8B;CACxE,MAAM,iBAAiB,aAAa,QAAQ,GAAG;CAC/C,OAAO,mBAAmB,KAAK,eAAe,aAAa,MAAM,GAAG,cAAc;AACpF;AAEA,SAAS,cAAc,SAA0B,SAAiB,KAAqB;CACrF,MAAM,QAAwB;EAC5B,MAAM;EACN,MAAM;EACN,MAAM;EACN,SAAS,GAAG,QAAQ,IAAI,oBAAoB,GAAG;CACjD;CACA,QAAQ,UAAU,KAAK;CACvB,OAAO,IAAI,MAAM,MAAM,OAAO;AAChC;AAEA,SAAS,wBACP,YACA,QACM;CACN,MAAM,QAAQ,WAAW,QAAQ,MAAM;CACvC,IAAI,UAAU,IAAI,WAAW,OAAO,OAAO,CAAC;AAC9C;AAEA,SAAS,cAAc,SAA+C;CACpE,OAAO,SAAS,QAAQ,YAAY;AACtC"}

package/dist/sync/scanners/local.cjs

@@ -1,58 +1,217 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const promises = require("node:fs/promises");
-const node_path = require("node:path");
-class LocalFolder {
-  type = "local";
-  /** Absolute path to the local root directory. */
-  root;
-  /**
-   * Creates a new LocalFolder for the given root directory.
-   * @param root - Absolute path to the local directory to scan.
-   */
-  constructor(root) {
-    this.root = root;
-  }
-  /** Recursively walks the directory and yields files sorted by relative path. */
-  async *scan() {
-    const collected = [];
-    await this.walk(this.root, collected);
-    collected.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
-    for (const entry of collected) {
-      yield entry;
-    }
-  }
-  /**
-   * Recursively collects files from {@link dir} into {@link out}.
-   * @param dir - Absolute path of the directory to scan.
-   * @param out - Accumulator array that receives discovered file entries.
-   */
-  async walk(dir, out) {
-    let entries;
-    try {
-      entries = await promises.readdir(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const fullPath = node_path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        await this.walk(fullPath, out);
-      } else if (entry.isFile()) {
-        try {
-          const s = await promises.stat(fullPath);
-          const rel = node_path.relative(this.root, fullPath).split(node_path.sep).join("/");
-          out.push({
-            relativePath: rel,
-            absolutePath: fullPath,
-            modTimeMillis: Math.floor(s.mtimeMs),
-            size: s.size
-          });
-        } catch {
-        }
-      }
-    }
-  }
+const require_regexp_safety = require("../regexp-safety.cjs");
+const require_scan_events = require("../scan-events.cjs");
+const require_filters = require("../filters.cjs");
+const require_path_order = require("../path-order.cjs");
+const require_scan_limit = require("../scan-limit.cjs");
+const require_local_file_identity = require("../local-file-identity.cjs");
+const require_path_safety = require("../path-safety.cjs");
+const require_download_staging = require("../download-staging.cjs");
+const require_filesystem_errors = require("../filesystem-errors.cjs");
+const require_local_filesystem_root = require("../local-filesystem-root.cjs");
+//#region src/sync/scanners/local.ts
+/**
+* Scans a local directory tree and yields {@link LocalSyncPath} entries sorted by relative path.
+* A root directory read failure aborts the scan with an error diagnostic. Per-entry file or
+* directory failures are reported through `onError` and the scan continues over readable siblings.
+* SDK-managed partial download file names are skipped so unfinished internal
+* temp files are not synchronized.
+* The current implementation collects matching entries before sorting, so memory usage is
+* proportional to the number of matched files.
+*/
+var LocalFolder = class {
+	type = "local";
+	appliesScanFilters = true;
+	appliesScanSorting = true;
+	/** Resolved absolute path to the local root directory. */
+	root;
+	/**
+	* Creates a new LocalFolder for the given root directory.
+	* @param root - Absolute or relative path to the local directory to scan.
+	*/
+	constructor(root) {
+		this.root = resolvePathAtConstruction(root);
+		require_local_filesystem_root.registerLocalFilesystemRoot(this);
+	}
+	/**
+	* Recursively walks the directory and yields files in sync path order.
+	* @param options - Optional scan controls.
+	*/
+	async *scan(options = {}) {
+		require_regexp_safety.validateSyncFilters(options);
+		const nodeDeps = await loadLocalNodeDeps();
+		const root = nodeDeps.resolve(this.root);
+		const collected = [];
+		await this.walk(root, root, collected, options, require_scan_limit.scanEntryLimit(options), nodeDeps);
+		collected.sort((a, b) => require_path_order.compareSyncRelativePaths(a.relativePath, b.relativePath));
+		for (const entry of collected) {
+			throwIfScanAborted(options);
+			yield entry;
+		}
+	}
+	/**
+	* Recursively collects files from {@link dir} into {@link out}.
+	* @param root - Resolved scan root used for relative path calculation.
+	* @param dir - Absolute path of the directory to scan.
+	* @param out - Accumulator array that receives discovered file entries.
+	* @param options - Optional scan controls.
+	* @param maxScanEntries - Maximum number of entries to retain before failing.
+	* @param nodeDeps - Lazy-loaded Node filesystem and path helpers.
+	*/
+	async walk(root, dir, out, options, maxScanEntries, nodeDeps) {
+		throwIfScanAborted(options);
+		let entries;
+		try {
+			entries = await nodeDeps.readdir(dir, { withFileTypes: true });
+		} catch (err) {
+			const error = this.emitScanError(options, relativePathFromRoot(root, dir, nodeDeps), "directory", err);
+			if (dir === root) throw error;
+			return;
+		}
+		for (const entry of entries) {
+			throwIfScanAborted(options);
+			const fullPath = nodeDeps.join(dir, entry.name);
+			const rel = relativePathFromRoot(root, fullPath, nodeDeps);
+			if (require_download_staging.isDownloadStagingDirectorySegment(rel) && entry.isDirectory() && require_download_staging.isDownloadStagingDirectorySegment(entry.name) && await require_download_staging.isManagedDownloadStagingRoot(fullPath)) continue;
+			if (rel.includes("\\")) {
+				require_scan_events.emitScannerSkip(options, {
+					type: "skip",
+					path: rel,
+					size: 0,
+					reason: "unsafe-name",
+					message: `Skipped local path ${JSON.stringify(rel)}: backslashes are not safe sync path characters`
+				});
+				continue;
+			}
+			if (require_path_safety.isReservedSyncTempFileName(entry.name)) {
+				require_scan_events.emitScannerSkip(options, {
+					type: "skip",
+					path: rel,
+					size: 0,
+					reason: "stale-download-partial",
+					message: `Skipped local path ${JSON.stringify(rel)}: reserved SDK partial download file`
+				});
+				continue;
+			}
+			if (entry.isDirectory()) {
+				if (require_filters.directoryMayContainSyncPaths(rel, options)) await this.walk(root, fullPath, out, options, maxScanEntries, nodeDeps);
+			} else if (entry.isFile()) {
+				if (!require_filters.pathPassesSyncFilters(rel, options)) {
+					if (require_filters.pathSkippedByRegExpInputLimit(rel, options)) require_scan_events.emitScannerSkip(options, require_scan_events.regexpInputTooLongSkip(rel));
+					continue;
+				}
+				let s;
+				try {
+					s = await nodeDeps.lstat(fullPath);
+					/* v8 ignore start -- lstat race after a Dirent file result is not deterministic */
+					if (!s.isFile()) {
+						this.emitScanError(options, rel, "file", /* @__PURE__ */ new Error("not a regular file"));
+						continue;
+					}
+				} catch (err) {
+					/* v8 ignore next -- stat TOCTOU failures are not deterministic to trigger */
+					this.emitScanError(options, relativePathFromRoot(root, fullPath, nodeDeps), "file", err);
+					continue;
+				}
+				require_scan_limit.assertScanEntryLimit(out.length + 1, maxScanEntries);
+				out.push({
+					relativePath: rel,
+					absolutePath: fullPath,
+					modTimeMillis: Math.floor(s.mtimeMs),
+					size: s.size,
+					fileIdentity: require_local_file_identity.localFileIdentityFromStats(s)
+				});
+			}
+		}
+	}
+	emitScanError(options, path, kind, err) {
+		const event = {
+			type: "error",
+			path,
+			size: 0,
+			message: `failed to scan local ${kind}: ${require_filesystem_errors.localFilesystemErrorReason(err)}`
+		};
+		options.onError?.(event);
+		return new Error(event.message);
+	}
+};
+async function loadLocalNodeDeps() {
+	const [fsPromises, path] = await Promise.all([import("node:fs/promises"), import("node:path")]);
+	return {
+		readdir: fsPromises.readdir,
+		lstat: fsPromises.lstat,
+		join: path.join,
+		relative: path.relative,
+		resolve: path.resolve,
+		sep: path.sep
+	};
 }
+function resolvePathAtConstruction(root) {
+	const processLike = globalThis.process;
+	if (typeof processLike?.cwd !== "function") return root;
+	const cwd = processLike.cwd();
+	if (processLike.platform === "win32") return resolveWindowsPath(cwd, root);
+	return resolvePosixPath(cwd, root);
+}
+function resolvePosixPath(cwd, root) {
+	const resolved = normalizePathSegments((root.startsWith("/") ? root : `${cwd}/${root}`).split("/"), "/");
+	return resolved === "" ? "/" : `/${resolved}`;
+}
+function resolveWindowsPath(cwd, root) {
+	const normalizedRoot = root.replaceAll("/", "\\");
+	const normalizedCwd = cwd.replaceAll("/", "\\");
+	const drive = /^[A-Za-z]:/.exec(normalizedCwd)?.[0] ?? "";
+	const cwdUnc = splitUncPath(normalizedCwd);
+	if (/^\\\\/.test(normalizedRoot)) return normalizeUncPath(normalizedRoot);
+	if (/^[A-Za-z]:\\/.test(normalizedRoot)) return joinWindowsRoot(normalizedRoot.slice(0, 2), normalizePathSegments(normalizedRoot.slice(3).split("\\"), "\\"));
+	if (/^[A-Za-z]:/.test(normalizedRoot)) throw new Error("LocalFolder root must not be a drive-relative Windows path");
+	if (normalizedRoot.startsWith("\\")) {
+		const rest = normalizePathSegments(normalizedRoot.slice(1).split("\\"), "\\");
+		return joinWindowsRoot(cwdUnc?.prefix ?? drive, rest);
+	}
+	if (cwdUnc !== void 0) {
+		const resolved = normalizePathSegments([...cwdUnc.rest, ...normalizedRoot.split("\\")], "\\");
+		return joinWindowsRoot(cwdUnc.prefix, resolved);
+	}
+	const base = /^[A-Za-z]:\\/.test(normalizedCwd) ? normalizedCwd : `${drive}\\`;
+	const prefix = /^[A-Za-z]:/.exec(base)?.[0] ?? drive;
+	return joinWindowsRoot(prefix, normalizePathSegments([...base.slice(prefix.length).replace(/^\\/, "").split("\\"), ...normalizedRoot.split("\\")], "\\"));
+}
+function normalizeUncPath(path) {
+	const unc = splitUncPath(path);
+	if (unc === void 0) return path;
+	return joinWindowsRoot(unc.prefix, normalizePathSegments(unc.rest, "\\"));
+}
+function splitUncPath(path) {
+	if (!path.startsWith("\\\\")) return void 0;
+	const [server, share, ...rest] = path.split("\\").filter((part) => part !== "");
+	if (server === void 0 || share === void 0) return void 0;
+	return {
+		prefix: `\\\\${server}\\${share}`,
+		rest
+	};
+}
+function joinWindowsRoot(prefix, rest) {
+	return rest === "" ? `${prefix}\\` : `${prefix}\\${rest}`;
+}
+function normalizePathSegments(segments, separator) {
+	const out = [];
+	for (const segment of segments) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			out.pop();
+			continue;
+		}
+		out.push(segment);
+	}
+	return out.join(separator);
+}
+function relativePathFromRoot(root, path, nodeDeps) {
+	return nodeDeps.relative(root, path).split(nodeDeps.sep).join("/");
+}
+function throwIfScanAborted(options) {
+	if (options.signal?.aborted === true) throw options.signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+//#endregion
 exports.LocalFolder = LocalFolder;
-//# sourceMappingURL=local.cjs.map
+
+//# sourceMappingURL=local.cjs.map