@williamthorsen/toolbelt.filesystem 0.8.3 → 0.9.0

package/dist/esm/4-release/reconcileFileFromFile.d.ts

@@ -5,7 +5,7 @@ import { type FileReconciliation, type ReconcileFileOptions } from './reconcileF
  * Everything past the read is `reconcileFile`: The comparison, the conflict policy, the created parent directories,
  * and the outcome vocabulary are its. A source that cannot be read reports `failed`, and a missing source is not
  * distinguished from an unreadable one. The reason names `sourcePath` and the cause; the path is interpolated
- * because a read-stage failure carries none of its own (`EISDIR: illegal operation on a directory, read`) and the
+ * because a read-stage failure has none of its own (`EISDIR: illegal operation on a directory, read`) and the
  * result's `filePath` is the destination.
  *
  * The source is read even under `isDryRun`, because the outcome depends on comparing its content, so a dry run can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.filesystem",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Filesystem utilities",
   "keywords": [
     "config-cascade",
@@ -40,11 +40,19 @@
     }
   },
   "files": [
+    ".readyup/kits/*.js",
+    ".readyup/manifest.json",
     "dist/*",
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@williamthorsen/toolbelt.errors": "0.7.0"
+    "@williamthorsen/toolbelt.errors": "0.8.0"
+  },
+  "devDependencies": {
+    "@williamthorsen/toolbelt.adoption": "0.1.0",
+    "@williamthorsen/toolbelt.testing": "0.6.0",
+    "esbuild": "0.28.2",
+    "readyup": "0.36.0"
   },
   "engines": {
     "node": ">=24.0.0"

package/dist/esm/3-candidate/createTempTree.d.ts

@@ -1,85 +0,0 @@
-/**
- * Creates a throwaway directory tree and returns a handle that removes it on disposal. Each key of `entries` is a
- * path relative to the tree root: One ending in `/` becomes a directory, and any other becomes a file holding the
- * mapped contents, given as text or as the bytes themselves. A key resolving outside the root is rejected, and a
- * call that throws leaves nothing on disk.
- *
- * The handle writes into the tree after it is built, through `mkdir`, `symlink`, `write`, `writeAll`, and
- * `writeJson`. Each creates the parent directories that it needs and takes its entry path through the containment
- * check applied by `resolve`; `symlink`'s target is the exception, stored verbatim. Every one but `writeAll`,
- * which takes a map, returns the absolute path that it wrote. It reads the tree back through `exists`, `list`,
- * `listFiles`, `read`, and `readJson`, and removes an entry through `rm`.
- *
- * `prefix` names the directory, so a tree outliving a crashed run still shows what made it.
- *
- * @example
- * using tree = createTempTree({ '.git/': '', 'src/main.ts': 'export {};\n' });
- * tree.resolve('src/main.ts'); // '/private/var/folders/…/toolbelt-a1b2c3/src/main.ts'
- *
- * @category Filesystem
- * @experimental
- * @stage candidate
- */
-export declare function createTempTree(entries: Record<string, string | Uint8Array>, options?: CreateTempTreeOptions): TempTree;
-export interface CreateTempTreeOptions {
-    /** Leading text of the generated directory's name, to which a random suffix is appended. Defaults to `toolbelt-`. */
-    prefix?: string;
-}
-export interface TempTree extends Disposable {
-    /** Realpath of the tree root, resolved because `os.tmpdir()` is a symlink on macOS. */
-    readonly dir: string;
-    /** Reports whether a tree-relative path exists, following a symlink, so a dangling one yields `false`. */
-    exists(entryPath: string): boolean;
-    /** Lists the names directly inside a tree-relative directory, sorted, defaulting to the tree root. */
-    list(entryPath?: string): string[];
-    /**
-     * Lists every file below a tree-relative directory, at any depth, as `/`-separated paths relative to it, sorted,
-     * defaulting to the tree root. A symlink below that directory is neither listed nor descended, so every path in
-     * the result names a file held inside the tree. The directory given as the argument is the exception, followed as
-     * `list`, `read`, and `exists` follow theirs: One naming a link out of the tree lists the target's files. A path
-     * that does not exist yields an empty array, where `list` throws; one that exists as a file raises `ENOTDIR`, as
-     * `list` does.
-     */
-    listFiles(entryPath?: string): string[];
-    /** Creates the directory at a tree-relative path, along with its parents, leaving an existing one as it is. */
-    mkdir(entryPath: string): string;
-    /** Reads the file at a tree-relative path as UTF-8 text. */
-    read(entryPath: string): string;
-    /**
-     * Reads the file at a tree-relative path as JSON. The result is `unknown`, for the caller to narrow; contents
-     * that do not parse raise an error naming the entry, which the parse error alone does not.
-     */
-    readJson(entryPath: string): unknown;
-    /**
-     * Resolves `segments` against the tree root, throwing when the result falls outside it. An absolute segment
-     * landing inside the root is returned. The containment test is lexical, so it does not follow a symlink within
-     * the tree that points out of it.
-     */
-    resolve(...segments: string[]): string;
-    /** Removes a tree-relative entry, along with its contents where it is a directory, and a missing one silently. */
-    rm(entryPath: string): void;
-    /**
-     * Links a tree-relative path to `targetPath`, taking the link first and so inverting `fs.symlinkSync`. The target
-     * is stored verbatim and is not containment-checked, being a string held by the link rather than a location to
-     * which the tree writes: It may be absolute or relative, name something outside the tree, or dangle. A relative one
-     * resolves against the link's own directory, as POSIX resolves it. An occupied link path raises `EEXIST`.
-     *
-     * The link type is the one portability difference. An absolute directory target is linked as a junction, which
-     * Windows creates without the elevation needed by a directory symlink; a relative directory target is linked as a
-     * directory, which needs that elevation; every other target, a missing one included, is linked as a file.
-     */
-    symlink(linkPath: string, targetPath: string): string;
-    /** Writes `contents` at a tree-relative path, replacing an existing file. */
-    write(entryPath: string, contents: string | Uint8Array): string;
-    /**
-     * Writes a map of entries in the shape taken by the constructor, so a fixture built in one call there can be
-     * added to in one call here. Unlike the constructor, a failure part-way leaves the entries already written in
-     * place, there being no whole tree to discard.
-     */
-    writeAll(entries: Record<string, string | Uint8Array>): void;
-    /**
-     * Writes `value` at a tree-relative path as two-space-indented JSON ending in a newline. A value with no JSON
-     * representation -- `undefined`, a function, a symbol -- is refused rather than written.
-     */
-    writeJson(entryPath: string, value: unknown): string;
-}

package/dist/esm/3-candidate/createTempTree.js

@@ -1,148 +0,0 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-export function createTempTree(entries, options = {}) {
-    const { prefix = 'toolbelt-' } = options;
-    assertNamesDirectChild(prefix);
-    const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
-    try {
-        writeAll(entries);
-    }
-    catch (error) {
-        fs.rmSync(dir, { force: true, recursive: true });
-        throw error;
-    }
-    function exists(entryPath) {
-        return fs.existsSync(resolveWithinTree(dir, [entryPath]));
-    }
-    function list(entryPath = '') {
-        return fs.readdirSync(resolveWithinTree(dir, [entryPath])).toSorted();
-    }
-    function listFiles(entryPath = '') {
-        const rootPath = resolveWithinTree(dir, [entryPath]);
-        if (!fs.existsSync(rootPath))
-            return [];
-        return listFilesBelow(rootPath, '').toSorted();
-    }
-    function mkdir(entryPath) {
-        const absolutePath = resolveWithinTree(dir, [entryPath]);
-        fs.mkdirSync(absolutePath, { recursive: true });
-        return absolutePath;
-    }
-    function read(entryPath) {
-        return fs.readFileSync(resolveWithinTree(dir, [entryPath]), 'utf8');
-    }
-    function readJson(entryPath) {
-        const contents = read(entryPath);
-        try {
-            return JSON.parse(contents);
-        }
-        catch (error) {
-            throw new Error(`Entry "${entryPath}" is not readable as JSON`, { cause: error });
-        }
-    }
-    function resolve(...segments) {
-        return resolveWithinTree(dir, segments);
-    }
-    function rm(entryPath) {
-        fs.rmSync(resolveWithinTree(dir, [entryPath]), { force: true, recursive: true });
-    }
-    function symlink(linkPath, targetPath) {
-        const absoluteLink = resolveWithinTree(dir, [linkPath]);
-        fs.mkdirSync(path.dirname(absoluteLink), { recursive: true });
-        fs.symlinkSync(targetPath, absoluteLink, chooseLinkType(absoluteLink, targetPath));
-        return absoluteLink;
-    }
-    function write(entryPath, contents) {
-        const absolutePath = resolveWithinTree(dir, [entryPath]);
-        fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
-        fs.writeFileSync(absolutePath, contents);
-        return absolutePath;
-    }
-    function writeAll(newEntries) {
-        for (const [entry, contents] of Object.entries(newEntries)) {
-            if (entry.endsWith('/')) {
-                mkdir(entry);
-            }
-            else {
-                write(entry, contents);
-            }
-        }
-    }
-    function writeJson(entryPath, value) {
-        const json = JSON.stringify(value, null, 2);
-        if (json === undefined) {
-            throw new Error(`Value of type "${typeof value}" for "${entryPath}" has no JSON representation`);
-        }
-        return write(entryPath, `${json}\n`);
-    }
-    return {
-        dir,
-        exists,
-        list,
-        listFiles,
-        mkdir,
-        read,
-        readJson,
-        resolve,
-        rm,
-        symlink,
-        write,
-        writeAll,
-        writeJson,
-        [Symbol.dispose]() {
-            try {
-                fs.rmSync(dir, { force: true, recursive: true });
-            }
-            catch {
-                restoreDirectoryPermissions(dir);
-                fs.rmSync(dir, { force: true, recursive: true });
-            }
-        },
-    };
-}
-function assertNamesDirectChild(prefix) {
-    if (prefix.includes('/') || prefix.includes('\\')) {
-        throw new Error(`Temporary-directory prefix "${prefix}" contains a path separator`);
-    }
-    if (['', '.', '..'].includes(prefix)) {
-        throw new Error(`Temporary-directory prefix "${prefix}" names no new directory`);
-    }
-}
-function chooseLinkType(absoluteLinkPath, targetPath) {
-    const resolvedTarget = path.resolve(path.dirname(absoluteLinkPath), targetPath);
-    if (fs.statSync(resolvedTarget, { throwIfNoEntry: false })?.isDirectory() !== true) {
-        return 'file';
-    }
-    return path.isAbsolute(targetPath) ? 'junction' : 'dir';
-}
-function listFilesBelow(dir, prefix) {
-    const paths = [];
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-        const relativePath = `${prefix}${entry.name}`;
-        if (entry.isFile()) {
-            paths.push(relativePath);
-        }
-        else if (entry.isDirectory()) {
-            paths.push(...listFilesBelow(path.join(dir, entry.name), `${relativePath}/`));
-        }
-    }
-    return paths;
-}
-function restoreDirectoryPermissions(dir) {
-    fs.chmodSync(dir, 0o700);
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-        if (entry.isDirectory()) {
-            restoreDirectoryPermissions(path.join(dir, entry.name));
-        }
-    }
-}
-function resolveWithinTree(dir, segments) {
-    const target = path.resolve(dir, ...segments);
-    if (target !== dir && !target.startsWith(dir + path.sep)) {
-        throw new Error(`Path "${target}" falls outside the temporary tree at "${dir}"`);
-    }
-    return target;
-}