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

package/dist/tree-change/identity.js

@@ -0,0 +1,152 @@
+/**
+ * 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 { lstatSync } from 'node:fs';
+import path from 'node:path';
+import { requireConfirmedAbsent } from '../errors/confirmed-absent.js';
+import { isPathAbsentError } from '../errors/errno-table.js';
+import { classifyFsFault, everywhere, isFsFaultError } from '../errors/fs-fault.js';
+import { edgeBigintStatSync } from '../link-following.js';
+import { canonicalPath } from '../path-containment.js';
+import { safePath, toForwardSlash, toNfc } from '../path-core.js';
+import { normalizePath } from '../path-utils.js';
+import { identityOf, identityOracleOver, insideBy, sameBy } from './identity-compare.js';
+/** Run `work` for `entry`; a filesystem refusal is rethrown classified on `side`, anything else as it was. */
+function guarded(entry, side, work) {
+    try {
+        return work();
+    }
+    catch (error) {
+        throw classifyFsFault(error, { side, action: 'examine the entry', path: entry });
+    }
+}
+/** The fold of `real` (an absolute path): its real parent, a `/`, its base name, NFC then lower-cased. */
+function foldedRealPath(entry, side, real) {
+    return guarded(entry, side, () => ({
+        foldedRealPath: toNfc(`${toForwardSlash(normalizePath(path.dirname(real), path.dirname(real)))}/${path.basename(real)}`).toLowerCase(),
+    }));
+}
+/**
+ * `stat(entry)` for an entry that may be absent: `undefined` when nothing is there — believed only when
+ * the parent's listing agrees — and a classified fault when the OS refuses.
+ */
+function examine(entry, side, follows) {
+    const ctx = { side, action: 'examine the entry', path: entry };
+    try {
+        return follows ? edgeBigintStatSync(entry) : lstatSync(entry, { bigint: true });
+    }
+    catch (error) {
+        if (!isPathAbsentError(error))
+            throw classifyFsFault(error, ctx);
+        // A `stat` follows a link (a dangling one is absent); an `lstat` sees the link itself.
+        requireConfirmedAbsent(entry, error, { action: ctx.action, path: entry }, { follows, sideOf: everywhere(side) });
+        return undefined;
+    }
+}
+/**
+ * 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 function entryIdentities(entry, side) {
+    const own = examine(entry, side, false);
+    if (own === undefined)
+        return [];
+    const identities = [identityOf(own, () => foldedRealPath(entry, side, entry))];
+    if (!own.isSymbolicLink())
+        return identities;
+    // Every entry identified here is one the verb itself names (a destination it writes or removes):
+    // the operator's own path, its own link the edge the kernel answers.
+    const target = examine(entry, side, true);
+    if (target !== undefined) {
+        identities.push(identityOf(target, () => foldedRealPath(entry, side, guarded(entry, side, () => normalizePath(entry, entry)))));
+    }
+    return identities;
+}
+/**
+ * The identities of `entry`, or `undefined` when the OS refuses to examine it. The
+ * side is irrelevant here: a refusal becomes `unknown` and never surfaces.
+ */
+function identitiesOrUndecided(entry) {
+    try {
+        return entryIdentities(entry, 'destination');
+    }
+    catch (error) {
+        if (isFsFaultError(error))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Where `entry` physically is — its own place (its real parent directory, then its name) and, for a
+ * link, its target's — or `undefined` when the OS refuses to resolve it. `entry` need not exist: it
+ * is resolved from its deepest existing ancestor.
+ */
+function physicalSpellings(entry) {
+    try {
+        return [safePath.join(canonicalPath(path.dirname(entry), path.dirname(entry)), path.basename(entry)), canonicalPath(entry, entry)];
+    }
+    catch (error) {
+        // A refusal is `unknown` to the caller, exactly as an entry it cannot examine is; a defect stays loud.
+        if (isFsFaultError(classifyFsFault(error, { side: 'destination', action: 'resolve the entry', path: entry })))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * 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 function sameEntry(a, b) {
+    return sameBy(identitiesOrUndecided, a, b);
+}
+/**
+ * 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 function isInsideByIdentity(child, ancestor) {
+    return insideBy(identitiesOrUndecided, child, ancestor, physicalSpellings);
+}
+/**
+ * {@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 function identityOracle() {
+    return identityOracleOver((entry) => entryIdentities(entry, 'destination'), physicalSpellings);
+}
+//# sourceMappingURL=identity.js.map

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

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

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

@@ -0,0 +1,24 @@
+/** The plan/apply tree-change primitive: entry identity, the readable-tree proof and the copy, the planner, the applier and the file helpers. */
+export { entryIdentities, isInsideByIdentity, sameEntry } from './identity.js';
+export type { EntryContainment, EntrySameness, Identity } from './identity-compare.js';
+export { COPY_LINK_ESCAPES_SOURCE_CODE, CopyLinkEscapesSourceError, DIRECTORY_WALK_REVISITED_CODE, DirectoryWalkRevisitedError, FollowedWalk, } from './followed-walk.js';
+export { proveTreeReadable, readRegularFile } from './readable-tree.js';
+export type { ProveTreeReadableOptions } from './readable-tree.js';
+export { copyRegularFile, copyTree } from './copy-tree.js';
+export type { CopyRegularFileOptions, CopyTreeOptions } from './copy-tree.js';
+export type { CopyOnto } from './copy-decisions.js';
+export type { LinkPolicy, TreeWalkOptions } from './tree-walk.js';
+export { refuseEscapingLinks, treeChain, treeContainment } from './link-containment.js';
+export type { LinkContainmentCheck } from './link-containment.js';
+export { isLinkChainRefusedError } from './host-chain.js';
+export { HOST_PATH_FLAVOR, isWithinUnder, untrustedLinkRefusal, untrustedTextRefusal, win32FoldedName } from './link-chain.js';
+export { planTreeChanges, TREE_DEST_HOLDS_SOURCE_CODE, TREE_DEST_NOT_OWNED_CODE, TREE_DEST_OCCUPIED_CODE, TREE_DESTS_OVERLAP_CODE, TREE_SOURCE_HOLDS_DEST_CODE, } from './plan.js';
+export type { EntryKind, FileContents, Ownership, OwnershipVerdict, PlannedAction, PlannedChange, TreeChange, TreeFill, TreePlan } from './plan.js';
+export { applyTreePlan, applyTreePlanOrLeftover, TREE_CLEANUP_INCOMPLETE_CODE } from './apply.js';
+export { TREE_ROLLBACK_INCOMPLETE_CODE, TreeRollbackIncompleteError } from './rollback-error.js';
+export type { TreeRollbackStranded } from './rollback-error.js';
+export type { ApplyOptions, ApplyOutcome, ApplyResult, TreeChangeWarning } from './apply.js';
+export type { TempDirOutcome } from './files.js';
+export { disposeTempDir, disposeTempDirAfterFailure, disposeTempDirSync, makeDirectoryUnder, renameFileAtomic, replaceFile, TEMP_DIR_OUTSIDE_TMPDIR_CODE, withTempDir, writeFileUnder } from './files.js';
+export { isParkedTreeEntry, isTreeChangeResidue } from './staging-names.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tree-change/index.ts"],"names":[],"mappings":"AAAA,iJAAiJ;AACjJ,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/E,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,EAC3B,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACxE,YAAY,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC3D,YAAY,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxF,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC/H,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpJ,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAClG,OAAO,EAAE,6BAA6B,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AACjG,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC7F,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE,4BAA4B,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC1M,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/tree-change/index.js

@@ -0,0 +1,14 @@
+/** The plan/apply tree-change primitive: entry identity, the readable-tree proof and the copy, the planner, the applier and the file helpers. */
+export { entryIdentities, isInsideByIdentity, sameEntry } from './identity.js';
+export { COPY_LINK_ESCAPES_SOURCE_CODE, CopyLinkEscapesSourceError, DIRECTORY_WALK_REVISITED_CODE, DirectoryWalkRevisitedError, FollowedWalk, } from './followed-walk.js';
+export { proveTreeReadable, readRegularFile } from './readable-tree.js';
+export { copyRegularFile, copyTree } from './copy-tree.js';
+export { refuseEscapingLinks, treeChain, treeContainment } from './link-containment.js';
+export { isLinkChainRefusedError } from './host-chain.js';
+export { HOST_PATH_FLAVOR, isWithinUnder, untrustedLinkRefusal, untrustedTextRefusal, win32FoldedName } from './link-chain.js';
+export { planTreeChanges, TREE_DEST_HOLDS_SOURCE_CODE, TREE_DEST_NOT_OWNED_CODE, TREE_DEST_OCCUPIED_CODE, TREE_DESTS_OVERLAP_CODE, TREE_SOURCE_HOLDS_DEST_CODE, } from './plan.js';
+export { applyTreePlan, applyTreePlanOrLeftover, TREE_CLEANUP_INCOMPLETE_CODE } from './apply.js';
+export { TREE_ROLLBACK_INCOMPLETE_CODE, TreeRollbackIncompleteError } from './rollback-error.js';
+export { disposeTempDir, disposeTempDirAfterFailure, disposeTempDirSync, makeDirectoryUnder, renameFileAtomic, replaceFile, TEMP_DIR_OUTSIDE_TMPDIR_CODE, withTempDir, writeFileUnder } from './files.js';
+export { isParkedTreeEntry, isTreeChangeResidue } from './staging-names.js';
+//# sourceMappingURL=index.js.map

package/dist/tree-change/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tree-change/index.ts"],"names":[],"mappings":"AAAA,iJAAiJ;AACjJ,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,EAC3B,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAExE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAI3D,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExF,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC/H,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAClG,OAAO,EAAE,6BAA6B,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAIjG,OAAO,EAAE,cAAc,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE,4BAA4B,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC1M,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,180 @@
+/**
+ * The ONE resolver of a symbolic-link chain: where a path leads, walked hop by hop from what
+ * `lstat` and `readlink` say alone, so nothing is handed to the kernel until the whole chain has
+ * been read as text and shown to be local.
+ *
+ * That order is the point. A Windows kernel asked to resolve a path through a link to
+ * `\\host\share` opens an SMB session and offers the operator's NTLM credentials to that host
+ * before any answer comes back — so a `realpath` or a `stat` that follows links is a SECOND lock,
+ * asked only once this walk has proved the chain local, never the first.
+ *
+ * Pure: the caller supplies the path {@link PathFlavor} and the probe, so a test runs Windows
+ * semantics on any host. The flavor decides two things the kernel decides:
+ *
+ * - what separates a link text's components, and what makes it absolute or a network path
+ *   (`\\host\share`, `\\?\UNC\…`, `\\.\…`, `//host/share` under win32; on POSIX a backslash is a
+ *   character of a name and `//x` is the local root);
+ * - what `..` means. POSIX resolves a link before the `..` after it, physically (the parent of
+ *   where the link LED). Windows joins a relative link text onto the link's directory and collapses
+ *   every `..` lexically before reparsing — `x\..\y` is `y` whether `x` exists, is a file or a link —
+ *   so under win32 each splice is collapsed by string first, and every component it leaves is examined.
+ *
+ * Running out of hops ({@link MAX_LINK_HOPS}) is a refusal, never an answer: a chain the walk did
+ * not finish reading is a chain the kernel would finish for it. A CYCLE is different, and is told
+ * apart exactly: the walk meets the same link with the same text left to read, so every text in
+ * the cycle has been read and is local, and the kernel can only answer `ELOOP` — it resolves to
+ * nothing, as a dangling link does, in every lane.
+ *
+ * An untrusted tree ({@link ChainRule.outside} `refuse`) may be read on either host — a clone made
+ * here is installed there — so its every link text is also held to the OTHER flavor's rules
+ * ({@link untrustedTextRefusal}): a text that is absolute, drive-relative or a network path on
+ * either kernel is refused on both.
+ */
+/** What stands at a place, a link there NOT followed. */
+export type PlaceKind = 'directory' | 'file' | 'link' | 'absent';
+/** Whose path rules a link's text is read by. Bound from `process.platform` at the edge ({@link HOST_PATH_FLAVOR}). */
+export type PathFlavor = 'posix' | 'win32';
+/** The flavor of the host VAT runs on — the edge where a pure caller's flavor is bound. */
+export declare const HOST_PATH_FLAVOR: PathFlavor;
+/**
+ * How many links one resolution follows before it refuses. Windows' limit — 63 reparse points in
+ * one path — is the larger of the two kernels' (Linux's `MAXSYMLINKS` is 40), so no chain a kernel
+ * would still follow is ever cut short and answered.
+ */
+export declare const MAX_LINK_HOPS = 63;
+/** Why a chain is refused before the kernel is asked anything, with the link whose text decided it. */
+export type ChainRefusal = 
+/** A network or device path, at any hop: never handed to the kernel, in any lane. */
+{
+    readonly why: 'network';
+    readonly link: string;
+    readonly text: string;
+}
+/** An absolute local text, in a tree whose links may not leave it ({@link ChainRule.outside} `refuse`). */
+ | {
+    readonly why: 'absolute';
+    readonly link: string;
+    readonly text: string;
+}
+/** A drive-relative text (`C:x`): it names a place relative to a per-drive working directory no walk can know. */
+ | {
+    readonly why: 'drive-relative';
+    readonly link: string;
+    readonly text: string;
+}
+/** A text holding a NUL, or a component ending in a dot or a space, in a tree whose links may not leave it: not the text a kernel resolves. */
+ | {
+    readonly why: 'unportable';
+    readonly link: string;
+    readonly text: string;
+}
+/** A step above the tree's root, in a tree whose links may not leave it. */
+ | {
+    readonly why: 'climbs-out';
+    readonly link: string;
+    readonly text: string;
+}
+/** More than {@link MAX_LINK_HOPS} links that are not a cycle: a chain longer than either kernel follows. */
+ | {
+    readonly why: 'hop-limit';
+    readonly link: string;
+};
+/** Where a chain leads, as far as text can tell. */
+export type LinkChain = 
+/** A local path, every link on the way read: the kernel may now be asked about it. */
+{
+    readonly kind: 'resolved';
+    readonly path: string;
+    readonly final: 'directory' | 'file';
+}
+/**
+ * It leads to nothing: a component is absent or a file stands where a directory must
+ * (`absent`), or the chain comes back to a link it already read with the same text left
+ * (`cycle` — what the kernel answers `ELOOP` for).
+ */
+ | {
+    readonly kind: 'nothing';
+    readonly at: string;
+    readonly cause: 'absent' | 'cycle';
+}
+/** It may not be resolved at all. */
+ | {
+    readonly kind: 'refused';
+    readonly refusal: ChainRefusal;
+};
+/** The tree a chain is resolved in, and what it may do outside it. */
+export interface ChainRule {
+    readonly flavor: PathFlavor;
+    /** The tree's root, canonical (its own components are real directories). */
+    readonly root: string;
+    /**
+     * - `refuse`: an untrusted tree (a clone, an archive, a tree an install copies) — an absolute or
+     *   drive-relative text, or any step above the root, is refused, and nothing outside is probed.
+     * - `follow`: the user's own tree — an absolute local text is followed and walked by the same
+     *   rules, so a later hop's network text is still caught; where the chain ends is the caller's call.
+     */
+    readonly outside: 'refuse' | 'follow';
+}
+/** What the walk may ask the filesystem: never anything that follows a link. */
+export interface ChainProbe {
+    /** What stands at `path`, a link there NOT followed (`lstat`). */
+    readonly kindAt: (path: string) => PlaceKind;
+    /** The text of the link at `path` (`readlink`). */
+    readonly textAt: (path: string) => string;
+}
+declare const CLIMBS_OUT = "climbs-out";
+/**
+ * The root a NAMED path hangs from — `/`, a drive's `C:/`, a share's `//host/share/` — for a walk
+ * of the user's own path, which may lead anywhere local.
+ *
+ * @param path - Absolute, forward- or back-slashed
+ * @param flavor - Whose rules
+ * @throws TypeError for a path that is not absolute under `flavor`
+ */
+export declare function namedPathRoot(path: string, flavor: PathFlavor): string;
+/**
+ * Why a link text in an UNTRUSTED tree is refused by its text alone, under EITHER flavor — the rule
+ * a chain in a `refuse` tree is held to at every hop, and the one a caller that has only the text
+ * (a git clone reading link blobs before checkout) asks directly.
+ *
+ * A text is also `unportable` when it holds a NUL (the OS cuts the text short there, so the walk
+ * would judge bytes no kernel sees) or a component ending in a dot or a space (Win32 strips those,
+ * so `.. ` would climb where the walk read a name) — the win32 rule held on every host.
+ *
+ * @param text - A link's text, verbatim
+ * @returns why either kernel would not read it as a relative text inside the tree; `undefined` for one it would
+ */
+export declare function untrustedTextRefusal(text: string): UntrustedTextRefusal | undefined;
+/** Why an untrusted link's text alone is refused ({@link untrustedTextRefusal}). */
+type UntrustedTextRefusal = 'network' | 'absolute' | 'drive-relative' | 'unportable';
+/**
+ * Why a committed link — `linkPath` (its `/`-separated place in the tree) whose text is `text` — is
+ * refused by its text alone, before it exists on disk: {@link untrustedTextRefusal}, or `climbs-out`
+ * when, joined onto the link's directory and split by EITHER flavor's separators, its `..`s rise above
+ * the tree's root — the same collapse the walk applies under win32.
+ *
+ * @returns The refusal, or `undefined` for a text that stays inside by its text alone
+ */
+export declare function untrustedLinkRefusal(linkPath: string, text: string): UntrustedTextRefusal | typeof CLIMBS_OUT | undefined;
+/**
+ * A name folded as Windows compares names: each character upcased on its own (an ordinal, simple
+ * case fold — never `toLowerCase`, never a mapping that changes a character's length, like `ß` → `SS`).
+ */
+export declare function win32FoldedName(name: string): string;
+/**
+ * Whether `path` is `root` or below it, both forward-slashed — case-blind under win32 by the
+ * ordinal fold Windows compares names with ({@link win32FoldedName}).
+ */
+export declare function isWithinUnder(path: string, root: string, flavor: PathFlavor): boolean;
+/**
+ * Where `start` leads, every link on the way read by its text before anything follows it.
+ *
+ * @param start - An absolute path, in `rule.flavor`'s spelling (forward or back slashes)
+ * @param rule - The flavor, the tree, and what the chain may do outside it
+ * @param probe - `lstat` and `readlink`, and nothing that follows a link
+ * @returns The local path the kernel may now be asked about, nothing, or the refusal
+ * @throws whatever `probe` throws: a probe the OS refused is the caller's to classify
+ */
+export declare function walkLinkChain(start: string, rule: ChainRule, probe: ChainProbe): LinkChain;
+export {};
+//# sourceMappingURL=link-chain.d.ts.map

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

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