@vibe-agent-toolkit/utils 0.2.0-rc.11 → 0.2.0-rc.12

package/dist/tree-change/followed-walk.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The two refusals that bound a walk which FOLLOWS links: a link back into the
+ * walk ({@link FollowedWalk}, {@link DirectoryWalkRevisitedError}) and, for a walk
+ * contained to a root, a link out of it ({@link CopyLinkEscapesSourceError}).
+ * `proveTreeReadable` and `copyTree` under `links: 'follow-contained'` hold both;
+ * every other following walk holds a {@link FollowedWalk}.
+ */
+import { type FsSide } from '../errors/fs-fault.js';
+import { VatError } from '../errors/vat-error.js';
+/** The `VatError` code of a {@link DirectoryWalkRevisitedError}. */
+export declare const DIRECTORY_WALK_REVISITED_CODE = "DIRECTORY_WALK_REVISITED";
+/** Thrown when a following walk is led back into a directory it has already entered. */
+export declare class DirectoryWalkRevisitedError extends VatError {
+    constructor(dir: string, enteredAs: string);
+}
+/**
+ * The directories a FOLLOWING walk has entered, by realpath, so a link that
+ * leads back into the walk is refused instead of recursed until
+ * `ENAMETOOLONG`.
+ *
+ * A walk that follows links (`direntKindFollowing`) has no cycle guard by
+ * construction: `scripts/loop -> .` makes a copy create `dest/loop/loop/…`,
+ * writing every file at every level first, and a hashing walk do the same in
+ * memory. Every following walk holds one of these and calls {@link enter}
+ * on every directory it recurses into — the root included. A REVISIT is
+ * refused, not just a cycle: two links to one directory make the walk's
+ * output ambiguous (which spelling is the file's path?), and a refusal that
+ * names both spellings is the answer the author can act on.
+ */
+export declare class FollowedWalk {
+    #private;
+    /**
+     * @param side - The side of the verb the walked tree is on: a refused realpath in {@link enter} is a fault there
+     * @param within - The tree the walk is in (the operator's own input): every link beneath it is read before the kernel resolves it
+     */
+    constructor(side: FsSide, within: string);
+    /**
+     * Record that the walk is entering `dir`. Synchronous on purpose — one
+     * realpath per directory entered is nothing beside the listing itself, and
+     * the sync and async walkers then share one guard.
+     *
+     * @param dir - A directory the walk is about to list, in any spelling
+     * @throws {DirectoryWalkRevisitedError} When its realpath was entered before
+     * @throws FsFaultError on the walk's side (origin `content`) when the OS refuses to resolve it
+     */
+    enter(dir: string): void;
+}
+/** The `VatError` code of a {@link CopyLinkEscapesSourceError}. */
+export declare const COPY_LINK_ESCAPES_SOURCE_CODE = "COPY_LINK_ESCAPES_SOURCE";
+/** Thrown when a link inside a tree walked with `links: 'follow-contained'` points outside it. */
+export declare class CopyLinkEscapesSourceError extends VatError {
+    constructor(link: string, src: string);
+}
+//# sourceMappingURL=followed-walk.d.ts.map

package/dist/tree-change/followed-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"followed-walk.d.ts","sourceRoot":"","sources":["../../src/tree-change/followed-walk.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIlD,oEAAoE;AACpE,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE,wFAAwF;AACxF,qBAAa,2BAA4B,SAAQ,QAAQ;gBAC3C,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM3C;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;;IAKvB;;;OAGG;gBACS,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAKxC;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAczB;AAED,mEAAmE;AACnE,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE,kGAAkG;AAClG,qBAAa,0BAA2B,SAAQ,QAAQ;gBAC1C,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAQtC"}

package/dist/tree-change/followed-walk.js

@@ -0,0 +1,81 @@
+/**
+ * The two refusals that bound a walk which FOLLOWS links: a link back into the
+ * walk ({@link FollowedWalk}, {@link DirectoryWalkRevisitedError}) and, for a walk
+ * contained to a root, a link out of it ({@link CopyLinkEscapesSourceError}).
+ * `proveTreeReadable` and `copyTree` under `links: 'follow-contained'` hold both;
+ * every other following walk holds a {@link FollowedWalk}.
+ */
+import { classifyFsFault } from '../errors/fs-fault.js';
+import { VatError } from '../errors/vat-error.js';
+import { toForwardSlash } from '../path-core.js';
+import { normalizePath } from '../path-utils.js';
+/** The `VatError` code of a {@link DirectoryWalkRevisitedError}. */
+export const DIRECTORY_WALK_REVISITED_CODE = 'DIRECTORY_WALK_REVISITED';
+/** Thrown when a following walk is led back into a directory it has already entered. */
+export class DirectoryWalkRevisitedError extends VatError {
+    constructor(dir, enteredAs) {
+        super(DIRECTORY_WALK_REVISITED_CODE, `Refusing to enter ${dir}: it is the directory already walked as ${enteredAs} — a symlink leads the walk back into itself.`);
+    }
+}
+/**
+ * The directories a FOLLOWING walk has entered, by realpath, so a link that
+ * leads back into the walk is refused instead of recursed until
+ * `ENAMETOOLONG`.
+ *
+ * A walk that follows links (`direntKindFollowing`) has no cycle guard by
+ * construction: `scripts/loop -> .` makes a copy create `dest/loop/loop/…`,
+ * writing every file at every level first, and a hashing walk do the same in
+ * memory. Every following walk holds one of these and calls {@link enter}
+ * on every directory it recurses into — the root included. A REVISIT is
+ * refused, not just a cycle: two links to one directory make the walk's
+ * output ambiguous (which spelling is the file's path?), and a refusal that
+ * names both spellings is the answer the author can act on.
+ */
+export class FollowedWalk {
+    #entered = new Map();
+    #side;
+    #within;
+    /**
+     * @param side - The side of the verb the walked tree is on: a refused realpath in {@link enter} is a fault there
+     * @param within - The tree the walk is in (the operator's own input): every link beneath it is read before the kernel resolves it
+     */
+    constructor(side, within) {
+        this.#side = side;
+        this.#within = within;
+    }
+    /**
+     * Record that the walk is entering `dir`. Synchronous on purpose — one
+     * realpath per directory entered is nothing beside the listing itself, and
+     * the sync and async walkers then share one guard.
+     *
+     * @param dir - A directory the walk is about to list, in any spelling
+     * @throws {DirectoryWalkRevisitedError} When its realpath was entered before
+     * @throws FsFaultError on the walk's side (origin `content`) when the OS refuses to resolve it
+     */
+    enter(dir) {
+        const real = toForwardSlash(this.#realpath(dir));
+        const before = this.#entered.get(real);
+        if (before !== undefined)
+            throw new DirectoryWalkRevisitedError(dir, before);
+        this.#entered.set(real, dir);
+    }
+    #realpath(dir) {
+        try {
+            return normalizePath(dir, this.#within);
+        }
+        catch (error) {
+            throw classifyFsFault(error, { side: this.#side, origin: 'content', action: `resolve ${dir}`, path: dir });
+        }
+    }
+}
+/** The `VatError` code of a {@link CopyLinkEscapesSourceError}. */
+export const COPY_LINK_ESCAPES_SOURCE_CODE = 'COPY_LINK_ESCAPES_SOURCE';
+/** Thrown when a link inside a tree walked with `links: 'follow-contained'` points outside it. */
+export class CopyLinkEscapesSourceError extends VatError {
+    constructor(link, src) {
+        super(COPY_LINK_ESCAPES_SOURCE_CODE, `Refusing to copy ${link}: it is a symlink to a path outside ${src}. ` +
+            'A copy follows links, so this would ship content the source tree does not own — ' +
+            'replace the link with the files, or point it inside the tree.');
+    }
+}
+//# sourceMappingURL=followed-walk.js.map

package/dist/tree-change/followed-walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"followed-walk.js","sourceRoot":"","sources":["../../src/tree-change/followed-walk.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAe,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,oEAAoE;AACpE,MAAM,CAAC,MAAM,6BAA6B,GAAG,0BAA0B,CAAC;AAExE,wFAAwF;AACxF,MAAM,OAAO,2BAA4B,SAAQ,QAAQ;IACvD,YAAY,GAAW,EAAE,SAAiB;QACxC,KAAK,CACH,6BAA6B,EAC7B,qBAAqB,GAAG,2CAA2C,SAAS,+CAA+C,CAC5H,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,YAAY;IACd,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,KAAK,CAAS;IACd,OAAO,CAAS;IAEzB;;;OAGG;IACH,YAAY,IAAY,EAAE,MAAc;QACtC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAW;QACf,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,IAAI,2BAA2B,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7E,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,SAAS,CAAC,GAAW;QACnB,IAAI,CAAC;YACH,OAAO,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,eAAe,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;QAC7G,CAAC;IACH,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,CAAC,MAAM,6BAA6B,GAAG,0BAA0B,CAAC;AAExE,kGAAkG;AAClG,MAAM,OAAO,0BAA2B,SAAQ,QAAQ;IACtD,YAAY,IAAY,EAAE,GAAW;QACnC,KAAK,CACH,6BAA6B,EAC7B,oBAAoB,IAAI,uCAAuC,GAAG,IAAI;YACpE,kFAAkF;YAClF,+DAA+D,CAClE,CAAC;IACJ,CAAC;CACF"}

package/dist/tree-change/host-chain.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The link-chain resolver ({@link walkLinkChain}) bound to this host's filesystem: `lstat` and
+ * `readlink`, and nothing that follows a link. Every call VAT makes that FOLLOWS a link — a
+ * `stat`, a `realpath` — reads the chain here first (`link-following.ts`, `assertLocalChain`), so
+ * no lane — a write lane, a read lane, an untrusted tree or the user's own — hands the kernel a
+ * chain whose every text has not been read.
+ */
+import { VatError } from '../errors/vat-error.js';
+import { type ChainRefusal, type ChainRule, type LinkChain, type PlaceKind } from './link-chain.js';
+/**
+ * What stands at `path`, a link there not followed. A probe the OS refuses is thrown raw, for the
+ * caller to classify.
+ *
+ * ⚠️ "Not followed" is `lstat`'s word, and on Windows libuv keeps it only for what it calls a
+ * symbolic link: a junction to a volume (`\??\Volume{…}\`) and a reparse point of another tag
+ * (cloud files, dedup, WCI) are retried as a link-FOLLOWING `stat` and reported as the directory
+ * or file they lead to. Their targets are local — the kernel refuses a remote mount point — so no
+ * credential leaves the host, but the walk reads such a place as a plain directory where the
+ * kernel reparses it.
+ */
+export declare function hostPlaceKind(path: string): PlaceKind;
+/**
+ * Where `path` leads on this host's filesystem, under `rule` ({@link walkLinkChain}).
+ *
+ * @param path - Absolute, or relative to cwd; either separator
+ * @param rule - The flavor (bound from the host at the edge), the tree, and what the chain may do outside it
+ * @throws The raw errno of an `lstat` or `readlink` the OS refused, for the caller to classify
+ */
+export declare function walkHostChain(path: string, rule: ChainRule): LinkChain;
+/**
+ * A path VAT would not resolve: a link on the way to it leads to a network path, or the chain is
+ * longer than any kernel follows. A read lane records it as that one target's fault
+ * (`linkResolutionFault`); a lane that stops classifies it on its own side, like any refusal
+ * (`classifyFsFault`), so a destination's refused chain reads as the destination's.
+ */
+export declare class LinkChainRefusedError extends VatError {
+    /** The path whose resolution was asked. */
+    readonly path: string;
+    /** Why, with the link whose text decided it. */
+    readonly refusal: ChainRefusal;
+    constructor(path: string, refusal: ChainRefusal);
+}
+/** Whether `error` is a {@link LinkChainRefusedError}, by its code (a `dist` copy never `instanceof`-matches a `src` one). */
+export declare function isLinkChainRefusedError(error: unknown): error is VatError & {
+    readonly path: string;
+    readonly refusal: ChainRefusal;
+};
+//# sourceMappingURL=host-chain.d.ts.map

package/dist/tree-change/host-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-chain.d.ts","sourceRoot":"","sources":["../../src/tree-change/host-chain.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAc,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,EAAmB,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAiB,KAAK,SAAS,EAAiB,MAAM,iBAAiB,CAAC;AAEnJ;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CASrD;AAKD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS,CAEtE;AAkBD;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;gBACnB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY;CAKhD;AAED,8HAA8H;AAC9H,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAErI"}

package/dist/tree-change/host-chain.js

@@ -0,0 +1,85 @@
+/**
+ * The link-chain resolver ({@link walkLinkChain}) bound to this host's filesystem: `lstat` and
+ * `readlink`, and nothing that follows a link. Every call VAT makes that FOLLOWS a link — a
+ * `stat`, a `realpath` — reads the chain here first (`link-following.ts`, `assertLocalChain`), so
+ * no lane — a write lane, a read lane, an untrusted tree or the user's own — hands the kernel a
+ * chain whose every text has not been read.
+ */
+import { lstatSync, readlinkSync } from 'node:fs';
+import { isPathAbsentError, LINK_CHAIN_REFUSED_CODE } from '../errors/errno-table.js';
+import { isVatError, VatError } from '../errors/vat-error.js';
+import { safePath, toForwardSlash } from '../path-core.js';
+import { MAX_LINK_HOPS, walkLinkChain } from './link-chain.js';
+/**
+ * What stands at `path`, a link there not followed. A probe the OS refuses is thrown raw, for the
+ * caller to classify.
+ *
+ * ⚠️ "Not followed" is `lstat`'s word, and on Windows libuv keeps it only for what it calls a
+ * symbolic link: a junction to a volume (`\??\Volume{…}\`) and a reparse point of another tag
+ * (cloud files, dedup, WCI) are retried as a link-FOLLOWING `stat` and reported as the directory
+ * or file they lead to. Their targets are local — the kernel refuses a remote mount point — so no
+ * credential leaves the host, but the walk reads such a place as a plain directory where the
+ * kernel reparses it.
+ */
+export function hostPlaceKind(path) {
+    try {
+        const stats = lstatSync(path);
+        if (stats.isSymbolicLink())
+            return 'link';
+        return stats.isDirectory() ? 'directory' : 'file';
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return 'absent';
+        throw error;
+    }
+}
+/** The probe of this host's filesystem: `lstat` and `readlink` alone. */
+const HOST_PROBE = { kindAt: hostPlaceKind, textAt: (path) => readlinkSync(path) };
+/**
+ * Where `path` leads on this host's filesystem, under `rule` ({@link walkLinkChain}).
+ *
+ * @param path - Absolute, or relative to cwd; either separator
+ * @param rule - The flavor (bound from the host at the edge), the tree, and what the chain may do outside it
+ * @throws The raw errno of an `lstat` or `readlink` the OS refused, for the caller to classify
+ */
+export function walkHostChain(path, rule) {
+    return walkLinkChain(toForwardSlash(safePath.resolve(path)), rule, HOST_PROBE);
+}
+/** How each refusal reads, after "the symbolic link <link> ". */
+function refusalClause(refusal) {
+    switch (refusal.why) {
+        case 'network':
+            return `leads to ${refusal.text}, a network or device path, which VAT never asks the OS to follow (a Windows host would offer the operator's credentials to it)`;
+        case 'hop-limit':
+            return `starts a chain of more than ${MAX_LINK_HOPS.toString()} symbolic links that is not a cycle, so where it ends was never read`;
+        case 'unportable':
+            return `has a text no kernel resolves as written (${JSON.stringify(refusal.text)}: a NUL, or a name ending in a dot or a space)`;
+        case 'absolute':
+        case 'drive-relative':
+        case 'climbs-out':
+            return `leads outside the tree it is in (${refusal.text})`;
+    }
+}
+/**
+ * A path VAT would not resolve: a link on the way to it leads to a network path, or the chain is
+ * longer than any kernel follows. A read lane records it as that one target's fault
+ * (`linkResolutionFault`); a lane that stops classifies it on its own side, like any refusal
+ * (`classifyFsFault`), so a destination's refused chain reads as the destination's.
+ */
+export class LinkChainRefusedError extends VatError {
+    /** The path whose resolution was asked. */
+    path;
+    /** Why, with the link whose text decided it. */
+    refusal;
+    constructor(path, refusal) {
+        super(LINK_CHAIN_REFUSED_CODE, `Refusing to resolve ${path}: the symbolic link ${refusal.link} ${refusalClause(refusal)} — replace the link with the files it names.`);
+        this.path = path;
+        this.refusal = refusal;
+    }
+}
+/** Whether `error` is a {@link LinkChainRefusedError}, by its code (a `dist` copy never `instanceof`-matches a `src` one). */
+export function isLinkChainRefusedError(error) {
+    return isVatError(error, LINK_CHAIN_REFUSED_CODE) && 'refusal' in error;
+}
+//# sourceMappingURL=host-chain.js.map

package/dist/tree-change/host-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-chain.js","sourceRoot":"","sources":["../../src/tree-change/host-chain.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAElD,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,EAAsE,aAAa,EAAkB,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEnJ;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,KAAK,CAAC,cAAc,EAAE;YAAE,OAAO,MAAM,CAAC;QAC1C,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC;IACpD,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO,QAAQ,CAAC;QAC9C,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,GAAe,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;AAE/F;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,IAAe;IACzD,OAAO,aAAa,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;AACjF,CAAC;AAED,iEAAiE;AACjE,SAAS,aAAa,CAAC,OAAqB;IAC1C,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,YAAY,OAAO,CAAC,IAAI,iIAAiI,CAAC;QACnK,KAAK,WAAW;YACd,OAAO,+BAA+B,aAAa,CAAC,QAAQ,EAAE,sEAAsE,CAAC;QACvI,KAAK,YAAY;YACf,OAAO,6CAA6C,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,gDAAgD,CAAC;QACnI,KAAK,UAAU,CAAC;QAChB,KAAK,gBAAgB,CAAC;QACtB,KAAK,YAAY;YACf,OAAO,oCAAoC,OAAO,CAAC,IAAI,GAAG,CAAC;IAC/D,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,qBAAsB,SAAQ,QAAQ;IACjD,2CAA2C;IAClC,IAAI,CAAS;IACtB,gDAAgD;IACvC,OAAO,CAAe;IAC/B,YAAY,IAAY,EAAE,OAAqB;QAC7C,KAAK,CAAC,uBAAuB,EAAE,uBAAuB,IAAI,uBAAuB,OAAO,CAAC,IAAI,IAAI,aAAa,CAAC,OAAO,CAAC,8CAA8C,CAAC,CAAC;QACvK,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,8HAA8H;AAC9H,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,UAAU,CAAC,KAAK,EAAE,uBAAuB,CAAC,IAAI,SAAS,IAAI,KAAK,CAAC;AAC1E,CAAC"}

package/dist/tree-change/identity-compare.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Deciding sameness and containment from entry identities already read off the filesystem.
+ * Pure: the examination is handed in, so the decision is the same whoever asked the OS.
+ */
+/** One way an entry answers to being identified: a filesystem id, or a folded real path when the filesystem reports none. */
+export type Identity = {
+    readonly id: string;
+} | {
+    readonly foldedRealPath: string;
+};
+/** Whether two entries are one. `unknown` means it could not be decided: treat it as `same` when deciding whether to delete. */
+export type EntrySameness = 'same' | 'different' | 'unknown';
+/** Whether an entry lies strictly under another. `unknown` means it could not be decided. */
+export type EntryContainment = 'inside' | 'outside' | 'unknown';
+/** What one round of identity questions needs: each entry's identities, or `undefined` when the OS refuses to examine it. */
+export type Examiner = (entry: string) => readonly Identity[] | undefined;
+export declare function sameBy(examine: Examiner, a: string, b: string): EntrySameness;
+/**
+ * Where an entry physically is: every spelling of it with no link left in its directories (its own
+ * place, and — for a link — its target's), or `undefined` when the OS refuses to resolve it.
+ */
+export type PhysicalSpellings = (entry: string) => readonly string[] | undefined;
+/**
+ * Whether `child` lies strictly under `ancestor`: some directory above it IS the ancestor. Walked
+ * along the spelling given AND along every physical spelling of the child — a directory of the given
+ * spelling that is a link to somewhere BELOW the ancestor is neither the ancestor nor a link to it,
+ * and the directories between its target and the ancestor are only on the physical way up.
+ */
+export declare function insideBy(examine: Examiner, child: string, ancestor: string, physical: PhysicalSpellings): EntryContainment;
+/**
+ * The identity a `stat` answers with: the filesystem's own id when it reports both a device and an
+ * inode, else the fold — which is only computed then, since it costs a `realpath`.
+ *
+ * @param stats - The `dev` and `ino` of a `bigint` stat
+ * @param fold - The folded real path, for a filesystem that reports no inode
+ */
+export declare function identityOf(stats: {
+    readonly dev: bigint;
+    readonly ino: bigint;
+}, fold: () => Identity): Identity;
+/** Sameness and containment over one memo, and the one throwing examination of an entry they share. */
+export interface IdentityOracle {
+    /** The entry's identities, read once: a refusal is remembered and thrown again. */
+    readonly identities: (entry: string) => readonly Identity[];
+    /** Whether the OS refuses to examine `entry` (the remembered answer of {@link IdentityOracle.identities}). */
+    readonly refuses: (entry: string) => boolean;
+    readonly sameEntry: (a: string, b: string) => EntrySameness;
+    readonly isInside: (child: string, ancestor: string) => EntryContainment;
+}
+/**
+ * Identity questions that examine each entry ONCE: every answer is built from the same
+ * observation of each entry. One plan's decisions asked the filesystem again and again,
+ * so a refusal seen by one (subsumption: `unknown`) and not by the next (the overlap
+ * check: `inside`) made the planner refuse its own plan.
+ *
+ * @param read - The examination: an entry's identities, or a thrown classified fault when the OS
+ *   refuses. Anything else it throws is a defect and is never remembered as a refusal.
+ * @param physical - Where an entry physically is, for containment (see {@link insideBy})
+ */
+export declare function identityOracleOver(read: (entry: string) => readonly Identity[], physical: PhysicalSpellings): IdentityOracle;
+//# sourceMappingURL=identity-compare.d.ts.map

package/dist/tree-change/identity-compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-compare.d.ts","sourceRoot":"","sources":["../../src/tree-change/identity-compare.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,6HAA6H;AAC7H,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAErF,gIAAgI;AAChI,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAE7D,6FAA6F;AAC7F,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAkBhE,6HAA6H;AAC7H,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,QAAQ,EAAE,GAAG,SAAS,CAAC;AAE1E,wBAAgB,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,aAAa,CAI7E;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;AAgBjF;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,gBAAgB,CAO1H;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,QAAQ,GAAG,QAAQ,CAEhH;AAED,uGAAuG;AACvG,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,QAAQ,EAAE,CAAC;IAC5D,8GAA8G;IAC9G,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,aAAa,CAAC;IAC5D,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,gBAAgB,CAAC;CAC1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,QAAQ,EAAE,EAAE,QAAQ,EAAE,iBAAiB,GAAG,cAAc,CA8B5H"}

package/dist/tree-change/identity-compare.js

@@ -0,0 +1,115 @@
+/**
+ * Deciding sameness and containment from entry identities already read off the filesystem.
+ * Pure: the examination is handed in, so the decision is the same whoever asked the OS.
+ */
+import path from 'node:path';
+import { isFsFaultError } from '../errors/fs-fault.js';
+function hasFold(identities) {
+    return identities.some((identity) => 'foldedRealPath' in identity);
+}
+/** One entry when both are filesystem ids and equal, or both are folds and equal; an id never equals a fold. */
+function sameIdentity(left, right) {
+    if ('id' in left && 'id' in right)
+        return left.id === right.id;
+    return 'foldedRealPath' in left && 'foldedRealPath' in right && left.foldedRealPath === right.foldedRealPath;
+}
+function compare(left, right) {
+    if (left.length === 0 || right.length === 0)
+        return 'different';
+    if (left.some((l) => right.some((r) => sameIdentity(l, r))))
+        return 'same';
+    return hasFold(left) || hasFold(right) ? 'unknown' : 'different';
+}
+export function sameBy(examine, a, b) {
+    const left = examine(a);
+    const right = examine(b);
+    return left === undefined || right === undefined ? 'unknown' : compare(left, right);
+}
+/** Whether some directory above `start`, spelled as given, is the wanted entry. */
+function ancestorAbove(examine, start, wanted) {
+    let undecided = false;
+    let current = start;
+    for (let parent = path.dirname(current); parent !== current; parent = path.dirname(current)) {
+        const found = examine(parent);
+        const verdict = found === undefined ? 'unknown' : compare(found, wanted);
+        if (verdict === 'same')
+            return 'inside';
+        if (verdict === 'unknown')
+            undecided = true;
+        current = parent;
+    }
+    return undecided ? 'unknown' : 'outside';
+}
+/**
+ * Whether `child` lies strictly under `ancestor`: some directory above it IS the ancestor. Walked
+ * along the spelling given AND along every physical spelling of the child — a directory of the given
+ * spelling that is a link to somewhere BELOW the ancestor is neither the ancestor nor a link to it,
+ * and the directories between its target and the ancestor are only on the physical way up.
+ */
+export function insideBy(examine, child, ancestor, physical) {
+    const wanted = examine(ancestor);
+    if (wanted === undefined)
+        return 'unknown';
+    const resolved = physical(child);
+    const verdicts = new Set([...new Set([child, ...(resolved ?? [])])].map((start) => ancestorAbove(examine, start, wanted)));
+    if (verdicts.has('inside'))
+        return 'inside';
+    return resolved === undefined || verdicts.has('unknown') ? 'unknown' : 'outside';
+}
+/**
+ * The identity a `stat` answers with: the filesystem's own id when it reports both a device and an
+ * inode, else the fold — which is only computed then, since it costs a `realpath`.
+ *
+ * @param stats - The `dev` and `ino` of a `bigint` stat
+ * @param fold - The folded real path, for a filesystem that reports no inode
+ */
+export function identityOf(stats, fold) {
+    return stats.dev !== 0n && stats.ino !== 0n ? { id: `${stats.dev}:${stats.ino}` } : fold();
+}
+/**
+ * Identity questions that examine each entry ONCE: every answer is built from the same
+ * observation of each entry. One plan's decisions asked the filesystem again and again,
+ * so a refusal seen by one (subsumption: `unknown`) and not by the next (the overlap
+ * check: `inside`) made the planner refuse its own plan.
+ *
+ * @param read - The examination: an entry's identities, or a thrown classified fault when the OS
+ *   refuses. Anything else it throws is a defect and is never remembered as a refusal.
+ * @param physical - Where an entry physically is, for containment (see {@link insideBy})
+ */
+export function identityOracleOver(read, physical) {
+    const memo = new Map();
+    const identities = (entry) => {
+        let seen = memo.get(entry);
+        if (seen === undefined) {
+            try {
+                seen = { ok: read(entry) };
+            }
+            catch (error) {
+                if (!isFsFaultError(error))
+                    throw error;
+                seen = { refused: error };
+            }
+            memo.set(entry, seen);
+        }
+        if ('refused' in seen)
+            throw seen.refused;
+        return seen.ok;
+    };
+    const undecided = (entry) => {
+        try {
+            return identities(entry);
+        }
+        catch (error) {
+            if (isFsFaultError(error))
+                return undefined;
+            throw error;
+        }
+    };
+    return {
+        identities,
+        refuses: (entry) => undecided(entry) === undefined,
+        sameEntry: (a, b) => sameBy(undecided, a, b),
+        isInside: (child, ancestor) => insideBy(undecided, child, ancestor, physical),
+    };
+}
+//# sourceMappingURL=identity-compare.js.map

package/dist/tree-change/identity-compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-compare.js","sourceRoot":"","sources":["../../src/tree-change/identity-compare.ts"],"names":[],"mappings":"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"}

package/dist/tree-change/identity.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Entry identity: are two names ONE entry on disk?
+ *
+ * Two changes to a tree can alias without sharing a spelling — `plugins/Old` and
+ * `plugins/old` on APFS or NTFS, a link and its target, two links to one target.
+ * Comparing names cannot see it, and acting on a wrong "different" deletes what the
+ * user just installed. So identity is asked of the filesystem:
+ *
+ * - `dev` and `ino` both nonzero → the id `${dev}:${ino}`, from a `bigint` `lstat` of
+ *   the entry, plus a `stat` of a link's target. A link answers to BOTH: removing it
+ *   removes only the link, but it aliases its target.
+ * - Otherwise (a filesystem that reports `ino` 0) → a folded real path: the real
+ *   parent, a `/`, the base name, NFC then lower-cased. The fold can only err toward
+ *   "same", which keeps what it is asked to remove.
+ *
+ * An entry the OS refuses to examine is `unknown`, never `different`: the caller
+ * keeps. {@link entryIdentities} throws the refusal as an `FsFaultError` on the side
+ * the CALLER names, so whatever surfaces it reports a classified fault, not a raw errno.
+ */
+import { type FsSide } from '../errors/fs-fault.js';
+import { type EntryContainment, type EntrySameness, type Identity, type IdentityOracle } from './identity-compare.js';
+/**
+ * Every identity `entry` answers to: `[]` when nothing is there; its own (`lstat`) for
+ * anything; plus its target's (`stat`) when it is a link that resolves.
+ *
+ * @param entry - Absolute path to identify
+ * @param side - The side of the verb that named `entry`; every fault (the `lstat`, the `stat`, the real path of a fold) is raised on it
+ * @throws FsFaultError on `side` when the OS refuses to examine `entry`
+ */
+export declare function entryIdentities(entry: string, side: FsSide): readonly Identity[];
+/**
+ * Whether `a` and `b` are one entry. Any shared identity is `same`; identities on
+ * both sides with a filesystem id each and none shared is `different`; a folded path
+ * on either side that does not match is `unknown`; an entry the OS refuses to
+ * examine is `unknown`; an absent entry is `different` (nothing there can alias).
+ *
+ * @param a - Absolute path
+ * @param b - Absolute path
+ */
+export declare function sameEntry(a: string, b: string): EntrySameness;
+/**
+ * Whether `child` lies strictly under `ancestor`, judged by identity: some directory
+ * on the way up from `child` — along its spelling as given, and along where it
+ * physically is — is the same entry as `ancestor`. So a linked or case-aliased
+ * spelling of the ancestor is found, and so is a directory of `child`'s spelling that
+ * is a link to somewhere BELOW the ancestor. `child` need not exist.
+ * `unknown` when no ancestor proved `same` and one could not be examined.
+ *
+ * ⚠️ On a filesystem that reports `ino` 0 the answer for an existing `ancestor` is
+ * `unknown`, never `outside`: a fold cannot prove two names apart. A caller that
+ * refuses on `inside` must not refuse on `unknown`, or every copy there is refused.
+ *
+ * @param child - Absolute path
+ * @param ancestor - Absolute path
+ */
+export declare function isInsideByIdentity(child: string, ancestor: string): EntryContainment;
+/**
+ * {@link sameEntry} and {@link isInsideByIdentity} over one memo: each entry is examined once
+ * (`entryIdentities(entry, 'destination')`), so every answer of a plan is built from one observation.
+ */
+export declare function identityOracle(): IdentityOracle;
+//# sourceMappingURL=identity.d.ts.map

package/dist/tree-change/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/tree-change/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,EAA+C,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAMjG,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAc,KAAK,cAAc,EAAwC,MAAM,uBAAuB,CAAC;AAkCxK;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,QAAQ,EAAE,CAYhF;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,aAAa,CAE7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAEpF;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAE/C"}