@orkestrel/test 0.0.1 → 0.0.2

package/dist/src/server/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/server/helpers.ts","../../../src/server/factories.ts"],"sourcesContent":["import type { InventoryOptions } from './types.js'\nimport { lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs'\nimport { isAbsolute, relative, resolve, sep } from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\n/**\n * Resolves a target that stays below a root directory.\n *\n * @param root - The absolute root directory.\n * @param target - The relative or absolute target to resolve.\n * @returns The absolute target, or `undefined` when the target escapes the root.\n */\nexport function resolveContained(root: string, target: string): string | undefined {\n\tconst candidate = resolve(root, target)\n\tconst contained = relative(root, candidate)\n\tif (contained === '..' || contained.startsWith(`..${sep}`) || isAbsolute(contained)) {\n\t\treturn undefined\n\t}\n\treturn candidate\n}\n\n/**\n * Reads files from selected directories below a root directory.\n *\n * @param root - The root directory as a path or file URL.\n * @param directories - The directories to visit below the root.\n * @param options - Optional file extension and exact-path exclusions.\n * @returns File contents keyed by sorted root-relative paths.\n * @remarks An absent extension filter includes every file. Exclusions match full root-relative keys.\n */\nexport function readInventory(\n\troot: URL | string,\n\tdirectories: readonly string[],\n\toptions?: InventoryOptions,\n): Readonly<Record<string, string>> {\n\tconst supplied = resolve(typeof root === 'string' ? root : fileURLToPath(root))\n\tconst rootStatus = lstatSync(supplied)\n\tif (rootStatus.isSymbolicLink()) throw new Error('Root is a symbolic link')\n\tif (!rootStatus.isDirectory()) throw new Error('Root is not a directory')\n\n\tconst base = realpathSync.native(supplied)\n\tif (directories.length === 0) return Object.fromEntries([])\n\n\tconst excluded = new Set(options?.exclude)\n\tconst pending: string[] = []\n\tconst queued = new Set<string>()\n\tconst contents = new Map<string, string>()\n\n\tfor (const directory of directories) {\n\t\tconst candidate = resolveContained(base, directory)\n\t\tif (candidate === undefined) {\n\t\t\tthrow new Error(`Directory outside root: ${directory}`)\n\t\t}\n\n\t\tconst status = lstatSync(candidate)\n\t\tif (status.isSymbolicLink()) throw new Error(`Directory is a symbolic link: ${directory}`)\n\t\tif (!status.isDirectory()) throw new Error(`Not a directory: ${directory}`)\n\n\t\tconst physical = realpathSync.native(candidate)\n\t\tconst resolved = resolveContained(base, relative(base, physical))\n\t\tif (resolved === undefined) {\n\t\t\tthrow new Error(`Directory outside root: ${directory}`)\n\t\t}\n\n\t\tconst key = relative(base, resolved).split(sep).join('/')\n\t\tif (excluded.has(key) || queued.has(physical)) continue\n\t\tqueued.add(physical)\n\t\tpending.push(physical)\n\t}\n\n\twhile (pending.length > 0) {\n\t\tconst directory = pending.pop()\n\t\tif (directory === undefined) continue\n\n\t\tfor (const entry of readdirSync(directory, { withFileTypes: true })) {\n\t\t\tconst path = resolve(directory, entry.name)\n\t\t\tconst status = lstatSync(path)\n\t\t\tif (status.isSymbolicLink()) continue\n\n\t\t\tconst key = relative(base, path).split(sep).join('/')\n\t\t\tif (excluded.has(key)) continue\n\n\t\t\tif (status.isDirectory()) {\n\t\t\t\tconst physical = realpathSync.native(path)\n\t\t\t\tconst resolved = resolveContained(base, relative(base, physical))\n\t\t\t\tif (resolved === undefined || queued.has(physical)) {\n\t\t\t\t\tcontinue\n\t\t\t\t}\n\t\t\t\tqueued.add(physical)\n\t\t\t\tpending.push(physical)\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\tif (\n\t\t\t\t!status.isFile() ||\n\t\t\t\t(options?.extensions !== undefined &&\n\t\t\t\t\t!options.extensions.some((extension) => entry.name.endsWith(extension)))\n\t\t\t) {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tcontents.set(key, readFileSync(path, 'utf8'))\n\t\t}\n\t}\n\n\treturn Object.fromEntries(\n\t\tArray.from(contents).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)),\n\t)\n}\n","import type { ScratchInterface, ScratchOptions } from './types.js'\nimport {\n\tlstatSync,\n\tmkdirSync,\n\tmkdtempSync,\n\treadFileSync,\n\trmSync,\n\tstatSync,\n\twriteFileSync,\n} from 'node:fs'\nimport { tmpdir } from 'node:os'\nimport { dirname, resolve } from 'node:path'\nimport { resolveContained } from './helpers.js'\n\n/**\n * Allocates an owned temporary directory with contained file operations.\n *\n * @param options - Optional directory prefix and initial files.\n * @returns The scratch directory and its file operations.\n * @remarks The prefix defaults to `orkestrel-test-`. Seed keys use root-relative paths.\n */\nexport function createScratch(options?: ScratchOptions): ScratchInterface {\n\tconst temporary = resolve(tmpdir())\n\tconst prefix = resolve(temporary, options?.prefix ?? 'orkestrel-test-')\n\tif (dirname(prefix) !== temporary)\n\t\tthrow new Error('Scratch prefix must stay within the temporary directory')\n\n\tconst path = mkdtempSync(prefix)\n\tconst allocation = statSync(path)\n\tconst outside = 'Path outside scratch directory'\n\ttry {\n\t\tfor (const [target, text] of Object.entries(options?.files ?? {})) {\n\t\t\tconst candidate = resolveContained(path, target)\n\t\t\tif (candidate === undefined) throw new Error(`${outside}: ${target}`)\n\n\t\t\tmkdirSync(dirname(candidate), { recursive: true })\n\t\t\twriteFileSync(candidate, text)\n\t\t}\n\t} catch (error) {\n\t\trmSync(path, { force: true, recursive: true })\n\t\tthrow error\n\t}\n\n\tconst scratch: ScratchInterface = {\n\t\tpath,\n\t\twrite(target, text) {\n\t\t\tconst candidate = resolveContained(path, target)\n\t\t\tif (candidate === undefined) throw new Error(`${outside}: ${target}`)\n\n\t\t\tconst rootStatus = lstatSync(path, { throwIfNoEntry: false })\n\t\t\tif (rootStatus === undefined) throw new Error('Scratch directory does not exist')\n\t\t\tif (rootStatus.isSymbolicLink()) throw new Error('Scratch directory is a symbolic link')\n\t\t\tif (!rootStatus.isDirectory()) throw new Error('Scratch path is not a directory')\n\n\t\t\tmkdirSync(dirname(candidate), { recursive: true })\n\t\t\twriteFileSync(candidate, text)\n\t\t},\n\t\tread(target) {\n\t\t\tconst candidate = resolveContained(path, target)\n\t\t\tif (candidate === undefined) throw new Error(`${outside}: ${target}`)\n\t\t\tif (!scratch.exists(target)) return undefined\n\t\t\tconst status = statSync(candidate, { throwIfNoEntry: false })\n\t\t\tif (status === undefined) return undefined\n\t\t\tif (status.isDirectory()) {\n\t\t\t\tthrow new Error(`Scratch path is a directory: ${target}`)\n\t\t\t}\n\t\t\treturn readFileSync(candidate, 'utf8')\n\t\t},\n\t\texists(target) {\n\t\t\tconst candidate = resolveContained(path, target)\n\t\t\tif (candidate === undefined) throw new Error(`${outside}: ${target}`)\n\n\t\t\tconst rootStatus = lstatSync(path, { throwIfNoEntry: false })\n\t\t\tif (rootStatus === undefined) return false\n\t\t\tif (rootStatus.isSymbolicLink()) throw new Error('Scratch directory is a symbolic link')\n\t\t\tif (!rootStatus.isDirectory()) throw new Error('Scratch path is not a directory')\n\n\t\t\treturn lstatSync(candidate, { throwIfNoEntry: false }) !== undefined\n\t\t},\n\t\tdestroy() {\n\t\t\tconst status = lstatSync(path, { throwIfNoEntry: false })\n\t\t\tif (\n\t\t\t\tstatus === undefined ||\n\t\t\t\tstatus.dev !== allocation.dev ||\n\t\t\t\tstatus.ino !== allocation.ino ||\n\t\t\t\tstatus.birthtimeMs !== allocation.birthtimeMs\n\t\t\t)\n\t\t\t\treturn\n\t\t\trmSync(path, { force: true, recursive: true })\n\t\t},\n\t}\n\treturn scratch\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/server/helpers.ts","../../../src/server/factories.ts"],"sourcesContent":["import type { InventoryOptions, ScratchIdentity } from './types.js'\nimport { lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs'\nimport { isAbsolute, relative, resolve, sep } from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\n/**\n * Resolves a target that stays below a root directory.\n *\n * @param root - The absolute root directory.\n * @param target - The relative or absolute target to resolve.\n * @returns The absolute target, or `undefined` when the target escapes the root.\n */\nexport function resolveContained(root: string, target: string): string | undefined {\n\tconst candidate = resolve(root, target)\n\tconst contained = relative(root, candidate)\n\t// Cross-drive containment is unproven because POSIX `relative` never returns an absolute path;\n\t// a Windows gate would drive this branch.\n\tif (contained === '..' || contained.startsWith(`..${sep}`) || isAbsolute(contained)) {\n\t\treturn undefined\n\t}\n\treturn candidate\n}\n\n/**\n * Reports whether two directory identities name the same allocation.\n *\n * @param current - The identity read from the path now.\n * @param allocation - The identity recorded when the directory was allocated.\n * @returns Whether the device, the index node, and the creation time all match.\n * @remarks All three fields are compared because none of them alone identifies an allocation. A\n * device is shared by every directory on one filesystem, an index node is reused once its directory\n * is removed, and a creation time repeats within the host's timestamp resolution.\n */\nexport function matchesIdentity(current: ScratchIdentity, allocation: ScratchIdentity): boolean {\n\treturn (\n\t\tcurrent.device === allocation.device &&\n\t\tcurrent.inode === allocation.inode &&\n\t\tcurrent.birth === allocation.birth\n\t)\n}\n\n/**\n * Reports whether a root-relative key matches an exclusion.\n *\n * @param key - The root-relative key to test.\n * @param exclusions - The normalized root-relative exclusion keys.\n * @returns Whether an exclusion names the key or one of its ancestors.\n */\nexport function isExcluded(key: string, exclusions: readonly string[]): boolean {\n\treturn exclusions.some((rule) => rule === '' || key === rule || key.startsWith(`${rule}/`))\n}\n\n/**\n * Reads files from selected targets below a root directory.\n *\n * @param root - The root directory as a path or file URL.\n * @param targets - The files to read directly and directories to visit below the root.\n * @param options - Optional file extension and path exclusions.\n * @returns File contents keyed by sorted root-relative paths.\n * @throws When the root or a named target is a symbolic link, is not a supported entry, or resolves\n * outside the root.\n * @remarks A named file is included regardless of the extension filter. An absent extension filter\n * includes every walked file. An exclusion matches whole root-relative key segments and covers every\n * key below it, and it applies to a named target and a walked entry alike.\n */\nexport function readInventory(\n\troot: URL | string,\n\ttargets: readonly string[],\n\toptions?: InventoryOptions,\n): Readonly<Record<string, string>> {\n\tconst supplied = resolve(typeof root === 'string' ? root : fileURLToPath(root))\n\tconst rootStatus = lstatSync(supplied)\n\tif (rootStatus.isSymbolicLink()) throw new Error('Root is a symbolic link')\n\tif (!rootStatus.isDirectory()) throw new Error('Root is not a directory')\n\n\tconst base = realpathSync.native(supplied)\n\tif (targets.length === 0) return Object.fromEntries([])\n\n\tconst exclusions = (options?.exclude ?? []).map((rule) => {\n\t\tconst unprefixed = rule.startsWith('./') ? rule.slice(2) : rule\n\t\tconst collapsed = unprefixed.replace(/\\/+/g, '/')\n\t\tconst untrailed = collapsed.endsWith('/') ? collapsed.slice(0, -1) : collapsed\n\t\treturn untrailed === '.' ? '' : untrailed\n\t})\n\tconst pending: string[] = []\n\tconst queued = new Set<string>()\n\tconst contents = new Map<string, string>()\n\n\tfor (const target of targets) {\n\t\tconst candidate = resolveContained(base, target)\n\t\tif (candidate === undefined) {\n\t\t\tthrow new Error(`Target outside root: ${target}`)\n\t\t}\n\n\t\tconst status = lstatSync(candidate)\n\t\tif (status.isSymbolicLink()) throw new Error(`Target is a symbolic link: ${target}`)\n\t\tif (!status.isDirectory() && !status.isFile()) {\n\t\t\tthrow new Error(`Target is not a file or directory: ${target}`)\n\t\t}\n\n\t\tconst physical = realpathSync.native(candidate)\n\t\tconst resolved = resolveContained(base, relative(base, physical))\n\t\tif (resolved === undefined) {\n\t\t\tthrow new Error(`Target outside root: ${target}`)\n\t\t}\n\n\t\tconst key = relative(base, resolved).split(sep).join('/')\n\t\tif (isExcluded(key, exclusions)) continue\n\t\tif (status.isFile()) {\n\t\t\tcontents.set(key, readFileSync(physical, 'utf8'))\n\t\t\tcontinue\n\t\t}\n\t\tif (queued.has(physical)) continue\n\t\tqueued.add(physical)\n\t\tpending.push(physical)\n\t}\n\n\twhile (pending.length > 0) {\n\t\tconst directory = pending.pop()\n\t\tif (directory === undefined) continue\n\n\t\tfor (const entry of readdirSync(directory, { withFileTypes: true })) {\n\t\t\tconst path = resolve(directory, entry.name)\n\t\t\tconst status = lstatSync(path)\n\t\t\tif (status.isSymbolicLink()) continue\n\n\t\t\tconst key = relative(base, path).split(sep).join('/')\n\t\t\tif (isExcluded(key, exclusions)) continue\n\n\t\t\tif (status.isDirectory()) {\n\t\t\t\tconst physical = realpathSync.native(path)\n\t\t\t\tconst resolved = resolveContained(base, relative(base, physical))\n\t\t\t\t// Walk containment is unproven because POSIX CI skips links before `realpath`;\n\t\t\t\t// a host that resolves a walked directory outside `base` would drive this branch.\n\t\t\t\tif (resolved === undefined || queued.has(physical)) {\n\t\t\t\t\tcontinue\n\t\t\t\t}\n\t\t\t\tqueued.add(physical)\n\t\t\t\tpending.push(physical)\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\tif (\n\t\t\t\t!status.isFile() ||\n\t\t\t\t(options?.extensions !== undefined &&\n\t\t\t\t\t!options.extensions.some((extension) => entry.name.endsWith(extension)))\n\t\t\t) {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tcontents.set(key, readFileSync(path, 'utf8'))\n\t\t}\n\t}\n\n\treturn Object.fromEntries(\n\t\tArray.from(contents).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)),\n\t)\n}\n","import type { ScratchIdentity, ScratchInterface, ScratchOptions } from './types.js'\nimport {\n\tlstatSync,\n\tmkdirSync,\n\tmkdtempSync,\n\treadFileSync,\n\treaddirSync,\n\trmSync,\n\tstatSync,\n\tsymlinkSync,\n\twriteFileSync,\n} from 'node:fs'\nimport { tmpdir } from 'node:os'\nimport { dirname, resolve, sep } from 'node:path'\nimport { matchesIdentity, resolveContained } from './helpers.js'\n\n/**\n * Allocates an owned temporary directory with contained file operations.\n *\n * @param options - Optional parent directory, name prefix, and initial files.\n * @returns The scratch directory and its file operations.\n * @throws When the parent is missing, a symbolic link, or not a directory; when the prefix contains\n * `/` or `\\`; or when allocation or seeding fails.\n * @remarks The parent defaults to the host temporary directory. The prefix defaults to\n * `orkestrel-test-`. Seed keys use root-relative paths.\n */\nexport function createScratch(options?: ScratchOptions): ScratchInterface {\n\tconst parent = resolve(options?.parent ?? tmpdir())\n\tconst parentStatus = lstatSync(parent, { throwIfNoEntry: false })\n\tif (parentStatus === undefined) throw new Error('Scratch parent does not exist')\n\tif (parentStatus.isSymbolicLink()) throw new Error('Scratch parent is a symbolic link')\n\tif (!parentStatus.isDirectory()) throw new Error('Scratch parent is not a directory')\n\n\tconst prefix = options?.prefix ?? 'orkestrel-test-'\n\tif (prefix.includes('/') || prefix.includes('\\\\')) {\n\t\tthrow new Error('Scratch prefix must be a name fragment')\n\t}\n\n\tconst path = mkdtempSync(`${parent}${sep}${prefix}`)\n\tconst allocated = statSync(path)\n\tconst allocation: ScratchIdentity = {\n\t\tbirth: allocated.birthtimeMs,\n\t\tdevice: allocated.dev,\n\t\tinode: allocated.ino,\n\t}\n\tconst outside = 'Path outside scratch directory'\n\ttry {\n\t\tfor (const [target, text] of Object.entries(options?.files ?? {})) {\n\t\t\tconst candidate = resolveContained(path, target)\n\t\t\tif (candidate === undefined) throw new Error(`${outside}: ${target}`)\n\n\t\t\tmkdirSync(dirname(candidate), { recursive: true })\n\t\t\twriteFileSync(candidate, text)\n\t\t}\n\t} catch (error) {\n\t\trmSync(path, { force: true, recursive: true })\n\t\tthrow error\n\t}\n\n\tconst scratch: ScratchInterface = {\n\t\tpath,\n\t\twrite(target, text) {\n\t\t\tconst candidate = resolveContained(path, target)\n\t\t\tif (candidate === undefined) throw new Error(`${outside}: ${target}`)\n\n\t\t\tif (!scratch.has('.')) throw new Error('Scratch directory does not exist')\n\n\t\t\tmkdirSync(dirname(candidate), { recursive: true })\n\t\t\twriteFileSync(candidate, text)\n\t\t},\n\t\tread(target) {\n\t\t\tconst candidate = resolveContained(path, target)\n\t\t\tif (candidate === undefined) throw new Error(`${outside}: ${target}`)\n\t\t\tif (!scratch.has(target)) return undefined\n\t\t\tconst status = statSync(candidate, { throwIfNoEntry: false })\n\t\t\tif (status === undefined) return undefined\n\t\t\tif (status.isDirectory()) {\n\t\t\t\tthrow new Error(`Scratch path is a directory: ${target}`)\n\t\t\t}\n\t\t\treturn readFileSync(candidate, 'utf8')\n\t\t},\n\t\thas(target) {\n\t\t\tconst candidate = resolveContained(path, target)\n\t\t\tif (candidate === undefined) throw new Error(`${outside}: ${target}`)\n\n\t\t\tconst rootStatus = lstatSync(path, { throwIfNoEntry: false })\n\t\t\tif (rootStatus === undefined) return false\n\t\t\tif (rootStatus.isSymbolicLink()) throw new Error('Scratch directory is a symbolic link')\n\t\t\tif (!rootStatus.isDirectory()) throw new Error('Scratch path is not a directory')\n\n\t\t\treturn lstatSync(candidate, { throwIfNoEntry: false }) !== undefined\n\t\t},\n\t\tnames(target = '.') {\n\t\t\tconst candidate = resolveContained(path, target)\n\t\t\tif (candidate === undefined) throw new Error(`${outside}: ${target}`)\n\t\t\tif (!scratch.has('.')) throw new Error('Scratch directory does not exist')\n\n\t\t\tconst status = statSync(candidate, { throwIfNoEntry: false })\n\t\t\tif (status === undefined) throw new Error(`Scratch path does not exist: ${target}`)\n\t\t\tif (!status.isDirectory()) throw new Error(`Scratch path is not a directory: ${target}`)\n\t\t\treturn readdirSync(candidate).sort()\n\t\t},\n\t\tensure(target) {\n\t\t\tconst candidate = resolveContained(path, target)\n\t\t\tif (candidate === undefined) throw new Error(`${outside}: ${target}`)\n\t\t\tif (!scratch.has('.')) throw new Error('Scratch directory does not exist')\n\n\t\t\tconst status = statSync(candidate, { throwIfNoEntry: false })\n\t\t\tif (status !== undefined && !status.isDirectory()) {\n\t\t\t\tthrow new Error(`Scratch path is not a directory: ${target}`)\n\t\t\t}\n\t\t\tif (status === undefined) mkdirSync(candidate, { recursive: true })\n\t\t\treturn candidate\n\t\t},\n\t\tlink(target, source) {\n\t\t\tconst candidate = resolveContained(path, target)\n\t\t\tif (candidate === undefined) throw new Error(`${outside}: ${target}`)\n\t\t\tif (!scratch.has('.')) throw new Error('Scratch directory does not exist')\n\n\t\t\tmkdirSync(dirname(candidate), { recursive: true })\n\t\t\tsymlinkSync(source, candidate)\n\t\t},\n\t\tdestroy() {\n\t\t\tconst status = lstatSync(path, { throwIfNoEntry: false })\n\t\t\tif (status === undefined) return\n\t\t\tconst identity: ScratchIdentity = {\n\t\t\t\tbirth: status.birthtimeMs,\n\t\t\t\tdevice: status.dev,\n\t\t\t\tinode: status.ino,\n\t\t\t}\n\t\t\tif (!matchesIdentity(identity, allocation)) return\n\t\t\trmSync(path, { force: true, recursive: true })\n\t\t},\n\t}\n\treturn scratch\n}\n"],"mappings":"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"}

package/dist/src/server/index.d.cts

@@ -1,9 +1,12 @@
 /**
  * Allocates an owned temporary directory with contained file operations.
  *
- * @param options - Optional directory prefix and initial files.
+ * @param options - Optional parent directory, name prefix, and initial files.
  * @returns The scratch directory and its file operations.
- * @remarks The prefix defaults to `orkestrel-test-`. Seed keys use root-relative paths.
+ * @throws When the parent is missing, a symbolic link, or not a directory; when the prefix contains
+ * `/` or `\`; or when allocation or seeding fails.
+ * @remarks The parent defaults to the host temporary directory. The prefix defaults to
+ * `orkestrel-test-`. Seed keys use root-relative paths.
  */
 export declare function createScratch(options?: ScratchOptions): ScratchInterface;
 
@@ -11,20 +14,48 @@ export declare function createScratch(options?: ScratchOptions): ScratchInterfac
 export declare interface InventoryOptions {
     /** The file extensions to include, each written with its leading dot. */
     readonly extensions?: readonly string[];
-    /** The root-relative path keys to exclude. A directory key also excludes its descendants. */
+    /**
+     * The root-relative path keys to exclude. A key excludes itself and every key below it, matched
+     * on whole segments, so `excluded` drops `excluded/file.ts` and keeps `excluded-other/file.ts`.
+     */
     readonly exclude?: readonly string[];
 }
 
 /**
- * Reads files from selected directories below a root directory.
+ * Reports whether a root-relative key matches an exclusion.
+ *
+ * @param key - The root-relative key to test.
+ * @param exclusions - The normalized root-relative exclusion keys.
+ * @returns Whether an exclusion names the key or one of its ancestors.
+ */
+export declare function isExcluded(key: string, exclusions: readonly string[]): boolean;
+
+/**
+ * Reports whether two directory identities name the same allocation.
+ *
+ * @param current - The identity read from the path now.
+ * @param allocation - The identity recorded when the directory was allocated.
+ * @returns Whether the device, the index node, and the creation time all match.
+ * @remarks All three fields are compared because none of them alone identifies an allocation. A
+ * device is shared by every directory on one filesystem, an index node is reused once its directory
+ * is removed, and a creation time repeats within the host's timestamp resolution.
+ */
+export declare function matchesIdentity(current: ScratchIdentity, allocation: ScratchIdentity): boolean;
+
+/**
+ * Reads files from selected targets below a root directory.
  *
  * @param root - The root directory as a path or file URL.
- * @param directories - The directories to visit below the root.
- * @param options - Optional file extension and exact-path exclusions.
+ * @param targets - The files to read directly and directories to visit below the root.
+ * @param options - Optional file extension and path exclusions.
  * @returns File contents keyed by sorted root-relative paths.
- * @remarks An absent extension filter includes every file. Exclusions match full root-relative keys.
+ * @throws When the root or a named target is a symbolic link, is not a supported entry, or resolves
+ * outside the root.
+ * @remarks A named file is included regardless of the extension filter. An absent extension filter
+ * includes every walked file. An exclusion matches whole root-relative key segments and covers every
+ * key below it, and it applies to a named target and a walked entry alike.
  */
-export declare function readInventory(root: URL | string, directories: readonly string[], options?: InventoryOptions): Readonly<Record<string, string>>;
+export declare function readInventory(root: URL | string, targets: readonly string[], options?: InventoryOptions): Readonly<Record<string, string>>;
 
 /**
  * Resolves a target that stays below a root directory.
@@ -35,6 +66,16 @@ export declare function readInventory(root: URL | string, directories: readonly
  */
 export declare function resolveContained(root: string, target: string): string | undefined;
 
+/** The fields that together identify one allocated directory on its host. */
+export declare interface ScratchIdentity {
+    /** The identifier of the device holding the directory. */
+    readonly device: number;
+    /** The number of the directory's index node on that device. */
+    readonly inode: number;
+    /** The directory's creation time in milliseconds. */
+    readonly birth: number;
+}
+
 /** A temporary directory a test owns, writes into, reads back, and removes when it is done. */
 export declare interface ScratchInterface {
     /** The absolute path of the allocated directory. */
@@ -44,6 +85,8 @@ export declare interface ScratchInterface {
      *
      * @param target - A relative or absolute file path contained by the scratch directory.
      * @param text - The file contents.
+     * @throws When the target escapes the scratch directory, the scratch root is missing, a symbolic
+     * link, or a file, or the host refuses to write the file.
      */
     write(target: string, text: string): void;
     /**
@@ -58,22 +101,70 @@ export declare interface ScratchInterface {
      */
     read(target: string): string | undefined;
     /**
-     * Reports whether a path exists.
+     * Reports whether a path exists without following its final symbolic link.
      *
      * @param target - A relative or absolute path contained by the scratch directory.
      * @returns True when the entry exists, including a symbolic link whose target is missing.
      * @throws When the path escapes the scratch directory or its root is a symbolic link or file.
      */
-    exists(target: string): boolean;
-    /** Removes the directory and everything in it. */
+    has(target: string): boolean;
+    /**
+     * Lists the names directly inside a directory in sorted order.
+     *
+     * @param target - A relative or absolute directory path contained by the scratch directory. The
+     * scratch root is used when omitted.
+     * @returns The sorted entry names, without their parent paths.
+     * @throws When the path escapes the scratch directory, the target is missing or is not a
+     * directory, or the scratch root is a symbolic link or file.
+     */
+    names(target?: string): readonly string[];
+    /**
+     * Creates a directory and every missing parent.
+     *
+     * @param target - A relative or absolute directory path contained by the scratch directory.
+     * @returns The absolute path of the directory.
+     * @throws When the path escapes the scratch directory, the target exists and is not a directory,
+     * or the scratch root is missing, a symbolic link, or a file.
+     */
+    ensure(target: string): string;
+    /**
+     * Creates a symbolic link at a contained path, creating its missing parent directories.
+     *
+     * @param target - The relative or absolute contained path where the link is created. Unlike
+     * `node:fs`'s `symlinkSync(target, path)` vocabulary, this interface consistently calls the
+     * contained path the target.
+     * @param source - The link text naming the pointed-at path. It may name a path outside the scratch
+     * directory and is not containment-checked.
+     * @throws When the target escapes the scratch directory, the scratch root is missing, a symbolic
+     * link, or a file, or the host refuses to create the link.
+     */
+    link(target: string, source: string): void;
+    /**
+     * Removes the allocated directory and everything in it when its identity still matches.
+     *
+     * @throws When the host refuses to inspect or remove the matching allocation.
+     */
     destroy(): void;
 }
 
 /** Options for allocating a scratch directory. */
 export declare interface ScratchOptions {
-    /** The leading text of the generated directory name. */
+    /**
+     * The existing directory in which to create the allocation. Defaults to the host temporary
+     * directory. Allocation throws when this path is missing, a symbolic link, or not a directory.
+     */
+    readonly parent?: string;
+    /**
+     * The name fragment that starts the generated directory name. Allocation throws when this value
+     * contains `/` or `\`. Both are refused on every host, so the rule does not vary by host. A
+     * fragment carrying no separator is one path segment and cannot steer the allocation, so
+     * `release-0..2-` allocates.
+     */
     readonly prefix?: string;
-    /** Files to write on allocation, keyed by path below the scratch directory. */
+    /**
+     * Files to write on allocation, keyed by path below the scratch directory. Allocation removes its
+     * directory and rethrows when a key escapes or the host refuses a write.
+     */
     readonly files?: Readonly<Record<string, string>>;
 }
 

package/dist/src/server/index.d.ts

@@ -1,9 +1,12 @@
 /**
  * Allocates an owned temporary directory with contained file operations.
  *
- * @param options - Optional directory prefix and initial files.
+ * @param options - Optional parent directory, name prefix, and initial files.
  * @returns The scratch directory and its file operations.
- * @remarks The prefix defaults to `orkestrel-test-`. Seed keys use root-relative paths.
+ * @throws When the parent is missing, a symbolic link, or not a directory; when the prefix contains
+ * `/` or `\`; or when allocation or seeding fails.
+ * @remarks The parent defaults to the host temporary directory. The prefix defaults to
+ * `orkestrel-test-`. Seed keys use root-relative paths.
  */
 export declare function createScratch(options?: ScratchOptions): ScratchInterface;
 
@@ -11,20 +14,48 @@ export declare function createScratch(options?: ScratchOptions): ScratchInterfac
 export declare interface InventoryOptions {
     /** The file extensions to include, each written with its leading dot. */
     readonly extensions?: readonly string[];
-    /** The root-relative path keys to exclude. A directory key also excludes its descendants. */
+    /**
+     * The root-relative path keys to exclude. A key excludes itself and every key below it, matched
+     * on whole segments, so `excluded` drops `excluded/file.ts` and keeps `excluded-other/file.ts`.
+     */
     readonly exclude?: readonly string[];
 }
 
 /**
- * Reads files from selected directories below a root directory.
+ * Reports whether a root-relative key matches an exclusion.
+ *
+ * @param key - The root-relative key to test.
+ * @param exclusions - The normalized root-relative exclusion keys.
+ * @returns Whether an exclusion names the key or one of its ancestors.
+ */
+export declare function isExcluded(key: string, exclusions: readonly string[]): boolean;
+
+/**
+ * Reports whether two directory identities name the same allocation.
+ *
+ * @param current - The identity read from the path now.
+ * @param allocation - The identity recorded when the directory was allocated.
+ * @returns Whether the device, the index node, and the creation time all match.
+ * @remarks All three fields are compared because none of them alone identifies an allocation. A
+ * device is shared by every directory on one filesystem, an index node is reused once its directory
+ * is removed, and a creation time repeats within the host's timestamp resolution.
+ */
+export declare function matchesIdentity(current: ScratchIdentity, allocation: ScratchIdentity): boolean;
+
+/**
+ * Reads files from selected targets below a root directory.
  *
  * @param root - The root directory as a path or file URL.
- * @param directories - The directories to visit below the root.
- * @param options - Optional file extension and exact-path exclusions.
+ * @param targets - The files to read directly and directories to visit below the root.
+ * @param options - Optional file extension and path exclusions.
  * @returns File contents keyed by sorted root-relative paths.
- * @remarks An absent extension filter includes every file. Exclusions match full root-relative keys.
+ * @throws When the root or a named target is a symbolic link, is not a supported entry, or resolves
+ * outside the root.
+ * @remarks A named file is included regardless of the extension filter. An absent extension filter
+ * includes every walked file. An exclusion matches whole root-relative key segments and covers every
+ * key below it, and it applies to a named target and a walked entry alike.
  */
-export declare function readInventory(root: URL | string, directories: readonly string[], options?: InventoryOptions): Readonly<Record<string, string>>;
+export declare function readInventory(root: URL | string, targets: readonly string[], options?: InventoryOptions): Readonly<Record<string, string>>;
 
 /**
  * Resolves a target that stays below a root directory.
@@ -35,6 +66,16 @@ export declare function readInventory(root: URL | string, directories: readonly
  */
 export declare function resolveContained(root: string, target: string): string | undefined;
 
+/** The fields that together identify one allocated directory on its host. */
+export declare interface ScratchIdentity {
+    /** The identifier of the device holding the directory. */
+    readonly device: number;
+    /** The number of the directory's index node on that device. */
+    readonly inode: number;
+    /** The directory's creation time in milliseconds. */
+    readonly birth: number;
+}
+
 /** A temporary directory a test owns, writes into, reads back, and removes when it is done. */
 export declare interface ScratchInterface {
     /** The absolute path of the allocated directory. */
@@ -44,6 +85,8 @@ export declare interface ScratchInterface {
      *
      * @param target - A relative or absolute file path contained by the scratch directory.
      * @param text - The file contents.
+     * @throws When the target escapes the scratch directory, the scratch root is missing, a symbolic
+     * link, or a file, or the host refuses to write the file.
      */
     write(target: string, text: string): void;
     /**
@@ -58,22 +101,70 @@ export declare interface ScratchInterface {
      */
     read(target: string): string | undefined;
     /**
-     * Reports whether a path exists.
+     * Reports whether a path exists without following its final symbolic link.
      *
      * @param target - A relative or absolute path contained by the scratch directory.
      * @returns True when the entry exists, including a symbolic link whose target is missing.
      * @throws When the path escapes the scratch directory or its root is a symbolic link or file.
      */
-    exists(target: string): boolean;
-    /** Removes the directory and everything in it. */
+    has(target: string): boolean;
+    /**
+     * Lists the names directly inside a directory in sorted order.
+     *
+     * @param target - A relative or absolute directory path contained by the scratch directory. The
+     * scratch root is used when omitted.
+     * @returns The sorted entry names, without their parent paths.
+     * @throws When the path escapes the scratch directory, the target is missing or is not a
+     * directory, or the scratch root is a symbolic link or file.
+     */
+    names(target?: string): readonly string[];
+    /**
+     * Creates a directory and every missing parent.
+     *
+     * @param target - A relative or absolute directory path contained by the scratch directory.
+     * @returns The absolute path of the directory.
+     * @throws When the path escapes the scratch directory, the target exists and is not a directory,
+     * or the scratch root is missing, a symbolic link, or a file.
+     */
+    ensure(target: string): string;
+    /**
+     * Creates a symbolic link at a contained path, creating its missing parent directories.
+     *
+     * @param target - The relative or absolute contained path where the link is created. Unlike
+     * `node:fs`'s `symlinkSync(target, path)` vocabulary, this interface consistently calls the
+     * contained path the target.
+     * @param source - The link text naming the pointed-at path. It may name a path outside the scratch
+     * directory and is not containment-checked.
+     * @throws When the target escapes the scratch directory, the scratch root is missing, a symbolic
+     * link, or a file, or the host refuses to create the link.
+     */
+    link(target: string, source: string): void;
+    /**
+     * Removes the allocated directory and everything in it when its identity still matches.
+     *
+     * @throws When the host refuses to inspect or remove the matching allocation.
+     */
     destroy(): void;
 }
 
 /** Options for allocating a scratch directory. */
 export declare interface ScratchOptions {
-    /** The leading text of the generated directory name. */
+    /**
+     * The existing directory in which to create the allocation. Defaults to the host temporary
+     * directory. Allocation throws when this path is missing, a symbolic link, or not a directory.
+     */
+    readonly parent?: string;
+    /**
+     * The name fragment that starts the generated directory name. Allocation throws when this value
+     * contains `/` or `\`. Both are refused on every host, so the rule does not vary by host. A
+     * fragment carrying no separator is one path segment and cannot steer the allocation, so
+     * `release-0..2-` allocates.
+     */
     readonly prefix?: string;
-    /** Files to write on allocation, keyed by path below the scratch directory. */
+    /**
+     * Files to write on allocation, keyed by path below the scratch directory. Allocation removes its
+     * directory and rethrows when a key escapes or the host refuses a write.
+     */
     readonly files?: Readonly<Record<string, string>>;
 }
 

package/dist/src/server/index.js

@@ -1,4 +1,4 @@
-import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
@@ -17,36 +17,72 @@ function resolveContained(root, target) {
 	return candidate;
 }
 /**
-* Reads files from selected directories below a root directory.
+* Reports whether two directory identities name the same allocation.
+*
+* @param current - The identity read from the path now.
+* @param allocation - The identity recorded when the directory was allocated.
+* @returns Whether the device, the index node, and the creation time all match.
+* @remarks All three fields are compared because none of them alone identifies an allocation. A
+* device is shared by every directory on one filesystem, an index node is reused once its directory
+* is removed, and a creation time repeats within the host's timestamp resolution.
+*/
+function matchesIdentity(current, allocation) {
+	return current.device === allocation.device && current.inode === allocation.inode && current.birth === allocation.birth;
+}
+/**
+* Reports whether a root-relative key matches an exclusion.
+*
+* @param key - The root-relative key to test.
+* @param exclusions - The normalized root-relative exclusion keys.
+* @returns Whether an exclusion names the key or one of its ancestors.
+*/
+function isExcluded(key, exclusions) {
+	return exclusions.some((rule) => rule === "" || key === rule || key.startsWith(`${rule}/`));
+}
+/**
+* Reads files from selected targets below a root directory.
 *
 * @param root - The root directory as a path or file URL.
-* @param directories - The directories to visit below the root.
-* @param options - Optional file extension and exact-path exclusions.
+* @param targets - The files to read directly and directories to visit below the root.
+* @param options - Optional file extension and path exclusions.
 * @returns File contents keyed by sorted root-relative paths.
-* @remarks An absent extension filter includes every file. Exclusions match full root-relative keys.
+* @throws When the root or a named target is a symbolic link, is not a supported entry, or resolves
+* outside the root.
+* @remarks A named file is included regardless of the extension filter. An absent extension filter
+* includes every walked file. An exclusion matches whole root-relative key segments and covers every
+* key below it, and it applies to a named target and a walked entry alike.
 */
-function readInventory(root, directories, options) {
+function readInventory(root, targets, options) {
 	const supplied = resolve(typeof root === "string" ? root : fileURLToPath(root));
 	const rootStatus = lstatSync(supplied);
 	if (rootStatus.isSymbolicLink()) throw new Error("Root is a symbolic link");
 	if (!rootStatus.isDirectory()) throw new Error("Root is not a directory");
 	const base = realpathSync.native(supplied);
-	if (directories.length === 0) return Object.fromEntries([]);
-	const excluded = new Set(options?.exclude);
+	if (targets.length === 0) return Object.fromEntries([]);
+	const exclusions = (options?.exclude ?? []).map((rule) => {
+		const collapsed = (rule.startsWith("./") ? rule.slice(2) : rule).replace(/\/+/g, "/");
+		const untrailed = collapsed.endsWith("/") ? collapsed.slice(0, -1) : collapsed;
+		return untrailed === "." ? "" : untrailed;
+	});
 	const pending = [];
 	const queued = /* @__PURE__ */ new Set();
 	const contents = /* @__PURE__ */ new Map();
-	for (const directory of directories) {
-		const candidate = resolveContained(base, directory);
-		if (candidate === void 0) throw new Error(`Directory outside root: ${directory}`);
+	for (const target of targets) {
+		const candidate = resolveContained(base, target);
+		if (candidate === void 0) throw new Error(`Target outside root: ${target}`);
 		const status = lstatSync(candidate);
-		if (status.isSymbolicLink()) throw new Error(`Directory is a symbolic link: ${directory}`);
-		if (!status.isDirectory()) throw new Error(`Not a directory: ${directory}`);
+		if (status.isSymbolicLink()) throw new Error(`Target is a symbolic link: ${target}`);
+		if (!status.isDirectory() && !status.isFile()) throw new Error(`Target is not a file or directory: ${target}`);
 		const physical = realpathSync.native(candidate);
 		const resolved = resolveContained(base, relative(base, physical));
-		if (resolved === void 0) throw new Error(`Directory outside root: ${directory}`);
+		if (resolved === void 0) throw new Error(`Target outside root: ${target}`);
 		const key = relative(base, resolved).split(sep).join("/");
-		if (excluded.has(key) || queued.has(physical)) continue;
+		if (isExcluded(key, exclusions)) continue;
+		if (status.isFile()) {
+			contents.set(key, readFileSync(physical, "utf8"));
+			continue;
+		}
+		if (queued.has(physical)) continue;
 		queued.add(physical);
 		pending.push(physical);
 	}
@@ -58,7 +94,7 @@ function readInventory(root, directories, options) {
 			const status = lstatSync(path);
 			if (status.isSymbolicLink()) continue;
 			const key = relative(base, path).split(sep).join("/");
-			if (excluded.has(key)) continue;
+			if (isExcluded(key, exclusions)) continue;
 			if (status.isDirectory()) {
 				const physical = realpathSync.native(path);
 				if (resolveContained(base, relative(base, physical)) === void 0 || queued.has(physical)) continue;
@@ -77,16 +113,28 @@ function readInventory(root, directories, options) {
 /**
 * Allocates an owned temporary directory with contained file operations.
 *
-* @param options - Optional directory prefix and initial files.
+* @param options - Optional parent directory, name prefix, and initial files.
 * @returns The scratch directory and its file operations.
-* @remarks The prefix defaults to `orkestrel-test-`. Seed keys use root-relative paths.
+* @throws When the parent is missing, a symbolic link, or not a directory; when the prefix contains
+* `/` or `\`; or when allocation or seeding fails.
+* @remarks The parent defaults to the host temporary directory. The prefix defaults to
+* `orkestrel-test-`. Seed keys use root-relative paths.
 */
 function createScratch(options) {
-	const temporary = resolve(tmpdir());
-	const prefix = resolve(temporary, options?.prefix ?? "orkestrel-test-");
-	if (dirname(prefix) !== temporary) throw new Error("Scratch prefix must stay within the temporary directory");
-	const path = mkdtempSync(prefix);
-	const allocation = statSync(path);
+	const parent = resolve(options?.parent ?? tmpdir());
+	const parentStatus = lstatSync(parent, { throwIfNoEntry: false });
+	if (parentStatus === void 0) throw new Error("Scratch parent does not exist");
+	if (parentStatus.isSymbolicLink()) throw new Error("Scratch parent is a symbolic link");
+	if (!parentStatus.isDirectory()) throw new Error("Scratch parent is not a directory");
+	const prefix = options?.prefix ?? "orkestrel-test-";
+	if (prefix.includes("/") || prefix.includes("\\")) throw new Error("Scratch prefix must be a name fragment");
+	const path = mkdtempSync(`${parent}${sep}${prefix}`);
+	const allocated = statSync(path);
+	const allocation = {
+		birth: allocated.birthtimeMs,
+		device: allocated.dev,
+		inode: allocated.ino
+	};
 	const outside = "Path outside scratch directory";
 	try {
 		for (const [target, text] of Object.entries(options?.files ?? {})) {
@@ -107,23 +155,20 @@ function createScratch(options) {
 		write(target, text) {
 			const candidate = resolveContained(path, target);
 			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
-			const rootStatus = lstatSync(path, { throwIfNoEntry: false });
-			if (rootStatus === void 0) throw new Error("Scratch directory does not exist");
-			if (rootStatus.isSymbolicLink()) throw new Error("Scratch directory is a symbolic link");
-			if (!rootStatus.isDirectory()) throw new Error("Scratch path is not a directory");
+			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
 			mkdirSync(dirname(candidate), { recursive: true });
 			writeFileSync(candidate, text);
 		},
 		read(target) {
 			const candidate = resolveContained(path, target);
 			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
-			if (!scratch.exists(target)) return void 0;
+			if (!scratch.has(target)) return void 0;
 			const status = statSync(candidate, { throwIfNoEntry: false });
 			if (status === void 0) return void 0;
 			if (status.isDirectory()) throw new Error(`Scratch path is a directory: ${target}`);
 			return readFileSync(candidate, "utf8");
 		},
-		exists(target) {
+		has(target) {
 			const candidate = resolveContained(path, target);
 			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
 			const rootStatus = lstatSync(path, { throwIfNoEntry: false });
@@ -132,9 +177,39 @@ function createScratch(options) {
 			if (!rootStatus.isDirectory()) throw new Error("Scratch path is not a directory");
 			return lstatSync(candidate, { throwIfNoEntry: false }) !== void 0;
 		},
+		names(target = ".") {
+			const candidate = resolveContained(path, target);
+			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
+			const status = statSync(candidate, { throwIfNoEntry: false });
+			if (status === void 0) throw new Error(`Scratch path does not exist: ${target}`);
+			if (!status.isDirectory()) throw new Error(`Scratch path is not a directory: ${target}`);
+			return readdirSync(candidate).sort();
+		},
+		ensure(target) {
+			const candidate = resolveContained(path, target);
+			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
+			const status = statSync(candidate, { throwIfNoEntry: false });
+			if (status !== void 0 && !status.isDirectory()) throw new Error(`Scratch path is not a directory: ${target}`);
+			if (status === void 0) mkdirSync(candidate, { recursive: true });
+			return candidate;
+		},
+		link(target, source) {
+			const candidate = resolveContained(path, target);
+			if (candidate === void 0) throw new Error(`${outside}: ${target}`);
+			if (!scratch.has(".")) throw new Error("Scratch directory does not exist");
+			mkdirSync(dirname(candidate), { recursive: true });
+			symlinkSync(source, candidate);
+		},
 		destroy() {
 			const status = lstatSync(path, { throwIfNoEntry: false });
-			if (status === void 0 || status.dev !== allocation.dev || status.ino !== allocation.ino || status.birthtimeMs !== allocation.birthtimeMs) return;
+			if (status === void 0) return;
+			if (!matchesIdentity({
+				birth: status.birthtimeMs,
+				device: status.dev,
+				inode: status.ino
+			}, allocation)) return;
 			rmSync(path, {
 				force: true,
 				recursive: true
@@ -144,6 +219,6 @@ function createScratch(options) {
 	return scratch;
 }
 //#endregion
-export { createScratch, readInventory, resolveContained };
+export { createScratch, isExcluded, matchesIdentity, readInventory, resolveContained };
 
 //# sourceMappingURL=index.js.map