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

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

@@ -0,0 +1,105 @@
+/**
+ * The rule for a tree whose links are KEPT: none of them may lead outside it.
+ *
+ * A copy that preserves links carries each link's text verbatim, so a link out of the tree
+ * arrives pointing at whatever stands at that path beside the COPY — the installing user's own
+ * files — and every reader of the copy that follows links reads them as the tree's content. So a
+ * tree that came from somewhere VAT does not own (a cloned repository, a directory an operator
+ * installs from) is checked here before anything reads it.
+ */
+import { type FsSide } from '../errors/fs-fault.js';
+import { type LinkChain, type PathFlavor } from './link-chain.js';
+/** What {@link refuseEscapingLinks} checks, and how its refusal names it. */
+export interface LinkContainmentCheck {
+    /** The tree no link may lead out of. */
+    readonly root: string;
+    /** Where in it to look; the whole of `root` when omitted. */
+    readonly subtree?: string;
+    /** A directory under `root` that is never entered (a clone's `.git`). */
+    readonly skip?: string;
+    /**
+     * Whether the tree is read where it stands, or will be RELOCATED (an install copies it, each
+     * link's text verbatim).
+     *
+     * - `in-place`: a link is judged by where it leads NOW. Its chain is read first, link by link,
+     *   by the one resolver ({@link treeChain}), so nothing is resolved until every text on the way
+     *   is: a network, absolute or drive-relative text anywhere on the way, a climb above the root,
+     *   or a chain no kernel finishes, is refused. Then its real path must be inside. One that leads
+     *   to nothing (a dangle, a cycle) reads nothing, so it is not refused.
+     * - `relocated`: where a link leads now proves nothing about where its text leads once the tree
+     *   is somewhere else, so the text itself is walked ({@link linkTextRefusal}): relative, never
+     *   above the root, through no other link, and ending at something that exists. Then the chain
+     *   from it is read as in place, and only then is the kernel asked ({@link kernelRefusal}).
+     */
+    readonly placement: 'in-place' | 'relocated';
+    /** Which side the tree is on: every probe of it the OS refuses — a listing, an `lstat`, a `readlink`, a link's target — is that side's fault. */
+    readonly side: FsSide;
+    /** Whose kernel reads the tree: bound from `process.platform` at the edge (`HOST_PATH_FLAVOR`). */
+    readonly flavor: PathFlavor;
+    /** What the tree is, for the refusal: `the cloned repository`. */
+    readonly tree: string;
+    /** What a link must stay inside, for the refusal: `the clone`. */
+    readonly within: string;
+    /** What keeping the link would do, for the refusal — a sentence without its full stop. */
+    readonly consequence: string;
+}
+/**
+ * Where `candidate` stands relative to `root`, on real paths. The root itself counts as inside
+ * (`isUnderRoot` calls a root `outside` itself, which is right for a sink and wrong here).
+ *
+ * @param root - The tree
+ * @param candidate - A path in any spelling, existing or not
+ */
+export declare function treeContainment(root: string, candidate: string): 'inside' | 'outside' | 'absent';
+/**
+ * Where `path` leads in an UNTRUSTED tree, read link by link by the one resolver — `lstat` and
+ * `readlink` alone — before anything resolves it: an absolute, drive-relative or network text on
+ * the way (under either flavor: the tree may be read on the other host), a climb above `root`,
+ * or a chain longer than the hop limit that is not a cycle, is refused; a cycle leads to
+ * nothing, as a dangling link does; nothing outside `root` is probed.
+ *
+ * @param root - The tree, spelled as `path` spells it (its own components are never probed)
+ * @param path - A path below it (a link, or a subpath the operator named)
+ * @param flavor - Whose kernel will resolve it: bound from the host at the edge
+ * @throws The raw errno of an `lstat` or `readlink` the OS refused, for the caller to classify
+ */
+export declare function treeChain(root: string, path: string, flavor: PathFlavor): LinkChain;
+/**
+ * The last lock on a link of a tree that will be relocated: the KERNEL's resolution of it, at
+ * the source, must exist and be inside the tree. Asked only once the chain from the link has been
+ * read and shown local ({@link treeChain}). The walk of the text ({@link linkTextRefusal}) shows
+ * the text stays inside wherever the tree goes; this shows the walk's reading of the text is the
+ * kernel's. A probe that failed because the link resolves to nothing
+ * (`isUnresolvableLinkError`: it dangles, it is part of a cycle, Windows cannot follow its reparse
+ * data) is a refusal of the link on every host: nothing can be shown about where it leads. Every
+ * other failure — the OS declining (`EACCES`, `EPERM`), running short (`EMFILE`), held (`EBUSY`) or
+ * unable to look (`EIO`, `ETIMEDOUT`, Windows' ambiguous `UNKNOWN`) — says nothing about the link:
+ * a fault on the tree, thrown classified by the one write-lane catch body
+ * (`assertUnresolvableLink`, on the side the caller names in `check.side`, found as content).
+ *
+ * Exported apart from the walk so the lock can be shown to hold ALONE: with a correct walk, a
+ * link the kernel resolves outside never reaches it from a real tree.
+ *
+ * @param root - The tree, as its canonical path
+ * @param link - The link, spelled by its real directory
+ * @param text - The link's own text, for the refusal
+ * @returns Why the link is refused, after "is a symbolic link ", or `undefined` when the kernel agrees
+ * @throws FsFaultError on `check.side` for a probe that failed for any other reason; an error that carries no errno as it was
+ */
+export declare function kernelRefusal(check: LinkContainmentCheck, root: string, link: string, text: string): string | undefined;
+/**
+ * Refuse a tree holding a symbolic link that may not be kept: one leading outside it, and — for a
+ * tree that will be relocated — one whose text cannot be shown to stay inside wherever the tree
+ * goes ({@link LinkContainmentCheck.placement}). Every directory is walked at its REAL path, once: a
+ * link that stays inside is followed to the directory it names, so a link into a sibling cannot
+ * smuggle out a second hop, a link cycle ends, and a directory first reached through an alias still
+ * has its own links judged where they live.
+ *
+ * @param check - The tree, where in it to look, and how the refusal names it
+ * @throws VatError `COPY_LINK_ESCAPES_SOURCE` — the tree's own link, so the input's refusal —
+ *   naming the first link found leading out; FsFaultError on `check.side`, found as content, for
+ *   every probe of the tree the OS refused (a listing, an `lstat`, a `readlink`, a relocated link's
+ *   target)
+ */
+export declare function refuseEscapingLinks(check: LinkContainmentCheck): void;
+//# sourceMappingURL=link-containment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"link-containment.d.ts","sourceRoot":"","sources":["../../src/tree-change/link-containment.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAA0B,KAAK,MAAM,EAAmB,MAAM,uBAAuB,CAAC;AAQ7F,OAAO,EAAqB,KAAK,SAAS,EAAiB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGpG,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,WAAW,CAAC;IAC7C,iJAAiJ;IACjJ,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mGAAmG;IACnG,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAGhG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CAEnF;AAyCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAavH;AAqCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAgBrE"}

package/dist/tree-change/link-containment.js

@@ -0,0 +1,196 @@
+/**
+ * The rule for a tree whose links are KEPT: none of them may lead outside it.
+ *
+ * A copy that preserves links carries each link's text verbatim, so a link out of the tree
+ * arrives pointing at whatever stands at that path beside the COPY — the installing user's own
+ * files — and every reader of the copy that follows links reads them as the tree's content. So a
+ * tree that came from somewhere VAT does not own (a cloned repository, a directory an operator
+ * installs from) is checked here before anything reads it.
+ */
+import { readdirSync, readlinkSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fsFaultOf } from '../errors/errno-table.js';
+import { assertUnresolvableLink, withFsFaultSync } from '../errors/fs-fault.js';
+import { VatError } from '../errors/vat-error.js';
+import { requireFollowedStatSync } from '../link-following.js';
+import { canonicalPath, isUnderRoot } from '../path-containment.js';
+import { safePath, toForwardSlash } from '../path-core.js';
+import { COPY_LINK_ESCAPES_SOURCE_CODE } from './followed-walk.js';
+import { hostPlaceKind, walkHostChain } from './host-chain.js';
+import { MAX_LINK_HOPS } from './link-chain.js';
+import { linkTextRefusal } from './link-walk.js';
+/**
+ * Where `candidate` stands relative to `root`, on real paths. The root itself counts as inside
+ * (`isUnderRoot` calls a root `outside` itself, which is right for a sink and wrong here).
+ *
+ * @param root - The tree
+ * @param candidate - A path in any spelling, existing or not
+ */
+export function treeContainment(root, candidate) {
+    if (canonicalPath(candidate, root) === canonicalPath(root, root))
+        return 'inside';
+    return isUnderRoot(root, candidate);
+}
+/**
+ * Where `path` leads in an UNTRUSTED tree, read link by link by the one resolver — `lstat` and
+ * `readlink` alone — before anything resolves it: an absolute, drive-relative or network text on
+ * the way (under either flavor: the tree may be read on the other host), a climb above `root`,
+ * or a chain longer than the hop limit that is not a cycle, is refused; a cycle leads to
+ * nothing, as a dangling link does; nothing outside `root` is probed.
+ *
+ * @param root - The tree, spelled as `path` spells it (its own components are never probed)
+ * @param path - A path below it (a link, or a subpath the operator named)
+ * @param flavor - Whose kernel will resolve it: bound from the host at the edge
+ * @throws The raw errno of an `lstat` or `readlink` the OS refused, for the caller to classify
+ */
+export function treeChain(root, path, flavor) {
+    return walkHostChain(path, { flavor, root: safePath.resolve(root), outside: 'refuse' });
+}
+/** The refusal of the link at `link`, named relative to the tree as the filesystem spells it. */
+function linkRefusal(check, link, what) {
+    return new VatError(COPY_LINK_ESCAPES_SOURCE_CODE, `Refusing ${check.tree}: ${safePath.relative(canonicalPath(check.root, check.root), link)} is a symbolic link ${what}. ` +
+        `${check.consequence} — replace the link with the files, or point it inside with a relative target.`);
+}
+/** How a refused chain reads, after "is a symbolic link "; `text` is the link's own. */
+function describedChainRefusal(check, text, refusal) {
+    switch (refusal.why) {
+        case 'network':
+        case 'absolute':
+        case 'drive-relative':
+            return `whose target leads through an absolute path (${refusal.text}), which names a place outside ${check.within}`;
+        case 'climbs-out':
+            return `to a path outside ${check.within} (${text})`;
+        case 'hop-limit':
+            return `whose target starts a chain of more than ${MAX_LINK_HOPS.toString()} symbolic links that is not a cycle, so where it ends cannot be shown`;
+        case 'unportable':
+            return `whose target names a component no Windows host can spell (${refusal.text}): a NUL, or a name ending in a dot or a space that Windows strips`;
+    }
+}
+/** How each refusal of a link's text reads, after "is a symbolic link ". */
+function describedRefusal(check, text, refusal) {
+    switch (refusal.why) {
+        case 'absolute':
+            return `with an absolute target (${text}), which would still point there once ${check.within} is copied`;
+        case 'climbs-out':
+            return `to a path outside ${check.within} (${text})`;
+        case 'through-link':
+            return `whose target passes through another symbolic link (${refusal.at}), so where ${text} leads depends on where ${check.within} is copied`;
+        case 'dangling':
+            return `to nothing (${refusal.at} does not exist), so where it would lead once ${check.within} is copied cannot be shown`;
+    }
+}
+/**
+ * The last lock on a link of a tree that will be relocated: the KERNEL's resolution of it, at
+ * the source, must exist and be inside the tree. Asked only once the chain from the link has been
+ * read and shown local ({@link treeChain}). The walk of the text ({@link linkTextRefusal}) shows
+ * the text stays inside wherever the tree goes; this shows the walk's reading of the text is the
+ * kernel's. A probe that failed because the link resolves to nothing
+ * (`isUnresolvableLinkError`: it dangles, it is part of a cycle, Windows cannot follow its reparse
+ * data) is a refusal of the link on every host: nothing can be shown about where it leads. Every
+ * other failure — the OS declining (`EACCES`, `EPERM`), running short (`EMFILE`), held (`EBUSY`) or
+ * unable to look (`EIO`, `ETIMEDOUT`, Windows' ambiguous `UNKNOWN`) — says nothing about the link:
+ * a fault on the tree, thrown classified by the one write-lane catch body
+ * (`assertUnresolvableLink`, on the side the caller names in `check.side`, found as content).
+ *
+ * Exported apart from the walk so the lock can be shown to hold ALONE: with a correct walk, a
+ * link the kernel resolves outside never reaches it from a real tree.
+ *
+ * @param root - The tree, as its canonical path
+ * @param link - The link, spelled by its real directory
+ * @param text - The link's own text, for the refusal
+ * @returns Why the link is refused, after "is a symbolic link ", or `undefined` when the kernel agrees
+ * @throws FsFaultError on `check.side` for a probe that failed for any other reason; an error that carries no errno as it was
+ */
+export function kernelRefusal(check, root, link, text) {
+    try {
+        // Followed to the end, as a reader of the link would: this fails where the kernel finds nothing.
+        requireFollowedStatSync(link, root);
+    }
+    catch (error) {
+        const fault = fsFaultOf(error);
+        if (fault === undefined)
+            throw error;
+        // The action names the link: a refusal on its chain names the place refused, which may be its target.
+        assertUnresolvableLink(error, { side: check.side, origin: 'content', action: `resolve the symbolic link ${link}`, path: link });
+        return `to nothing (${text} does not resolve: ${fault.errno}), so where it would lead once ${check.within} is copied cannot be shown`;
+    }
+    // It resolves, so its canonical path is its real one.
+    return treeContainment(root, link) === 'inside' ? undefined : `to a path outside ${check.within} (${text} resolves outside it)`;
+}
+/**
+ * Judge the link at `link` under `check.placement` — spelled by its REAL directory, so its text is
+ * read from where the link is, never from an alias of that directory, which reads a climbing text
+ * as staying inside.
+ *
+ * Either way the CHAIN is read first ({@link treeChain}) and the kernel last, so nothing the text
+ * names is resolved until every text on the way has been read. Relocated, the text is walked
+ * through no link before that ({@link linkTextRefusal}) and the kernel is asked after it
+ * ({@link kernelRefusal}); in place, the kernel's real path must be inside.
+ */
+function judgeLink(check, root, link) {
+    const text = readlinkSync(link);
+    if (check.placement === 'relocated') {
+        const below = safePath.relative(root, dirname(link));
+        const textRefusal = linkTextRefusal(below === '' ? [] : toForwardSlash(below).split('/'), text, (place) => hostPlaceKind(safePath.join(root, ...place)), check.flavor);
+        if (textRefusal !== undefined)
+            return { refusal: describedRefusal(check, text, textRefusal) };
+    }
+    const chain = treeChain(root, link, check.flavor);
+    if (chain.kind === 'refused')
+        return { refusal: describedChainRefusal(check, text, chain.refusal) };
+    if (check.placement === 'relocated') {
+        // Every text on the way was read and is local: the kernel may now be asked, as the last lock.
+        const refusal = kernelRefusal(check, root, link, text);
+        if (refusal !== undefined)
+            return { refusal };
+    }
+    else if (chain.kind === 'nothing') {
+        // A dangle or a cycle, every text read: in place it reads nothing.
+        return { enter: undefined };
+    }
+    else if (treeContainment(root, link) === 'outside') {
+        return { refusal: `to a path outside ${check.within}` };
+    }
+    return { enter: chain.kind === 'resolved' && chain.final === 'directory' ? canonicalPath(link, root) : undefined };
+}
+/**
+ * Refuse a tree holding a symbolic link that may not be kept: one leading outside it, and — for a
+ * tree that will be relocated — one whose text cannot be shown to stay inside wherever the tree
+ * goes ({@link LinkContainmentCheck.placement}). Every directory is walked at its REAL path, once: a
+ * link that stays inside is followed to the directory it names, so a link into a sibling cannot
+ * smuggle out a second hop, a link cycle ends, and a directory first reached through an alias still
+ * has its own links judged where they live.
+ *
+ * @param check - The tree, where in it to look, and how the refusal names it
+ * @throws VatError `COPY_LINK_ESCAPES_SOURCE` — the tree's own link, so the input's refusal —
+ *   naming the first link found leading out; FsFaultError on `check.side`, found as content, for
+ *   every probe of the tree the OS refused (a listing, an `lstat`, a `readlink`, a relocated link's
+ *   target)
+ */
+export function refuseEscapingLinks(check) {
+    withFsFaultSync({ side: check.side, origin: 'content', action: `examine the links of ${check.tree}`, path: check.subtree ?? check.root }, () => {
+        const skipped = check.skip === undefined ? undefined : canonicalPath(check.skip, check.root);
+        const visited = new Set();
+        const root = canonicalPath(check.root, check.root);
+        const pending = [canonicalPath(check.subtree ?? check.root, check.root)];
+        for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
+            if (dir === skipped || visited.has(dir))
+                continue;
+            visited.add(dir);
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                const entryPath = safePath.join(dir, entry.name);
+                const next = entry.isSymbolicLink() ? enterOrThrow(check, root, entryPath) : entry.isDirectory() && entryPath;
+                if (typeof next === 'string')
+                    pending.push(next);
+            }
+        }
+    });
+}
+/** The directory a kept link leads to, for the walk to enter; throws the link's refusal. */
+function enterOrThrow(check, root, link) {
+    const verdict = judgeLink(check, root, link);
+    if ('refusal' in verdict)
+        throw linkRefusal(check, link, verdict.refusal);
+    return verdict.enter;
+}
+//# sourceMappingURL=link-containment.js.map

package/dist/tree-change/link-containment.js.map

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

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

@@ -0,0 +1,49 @@
+/**
+ * Where a symbolic link's text leads, decided by WALKING it — the rule for a link in a tree that
+ * will be RELOCATED (an install copies the tree, each link's text verbatim). Pure: the caller says
+ * what stands at each place.
+ *
+ * A lexical resolve cancels `x/..` without asking what `x` is, so `l -> up/../../../secret` beside
+ * `up -> ../..` reads as inside the tree while the kernel follows `up` first and lands three
+ * levels above it. And where such a link dangles at the source, its real path proves nothing: it
+ * resolves once the tree is copied somewhere those levels exist. So nothing is assumed:
+ *
+ * - the text is relative — an absolute one points at the same place wherever the copy lands;
+ * - walked one segment at a time from the link's own directory, the place never rises above the
+ *   tree's root — not even to come back in by the tree's own name, which the copy may not keep;
+ * - no component the walk passes THROUGH is a link: a link may point at something, never through
+ *   another link, whose own text decides where the rest of the walk goes;
+ * - the place it ends at exists. A link that dangles is refused, because nothing can be proved
+ *   about where it lands after the copy.
+ *
+ * The walk is a MODEL of the kernel's resolution, and a model can be wrong (it once split a text
+ * on a backslash the POSIX kernel reads as part of a name). So its caller holds two more locks
+ * beside it — the one link-chain resolver (`link-chain.ts`), which reads the chain from the link to
+ * its end before anything follows it, and then the kernel's own resolution of the link at the
+ * source — and a link is kept only when all three agree.
+ */
+import type { PathFlavor, PlaceKind } from './link-chain.js';
+/** Why a link's text is refused, with the place (root-relative, `/`-joined) the walk stopped at. */
+export type LinkTextRefusal = {
+    readonly why: 'absolute';
+} | {
+    readonly why: 'climbs-out';
+} | {
+    readonly why: 'through-link';
+    readonly at: string;
+} | {
+    readonly why: 'dangling';
+    readonly at: string;
+};
+/**
+ * Walk a link's text from the directory the link is in.
+ *
+ * @param linkDir - The link's REAL directory, as segments below the tree's root (`[]`: the root itself)
+ * @param text - The link's text, verbatim
+ * @param kindAt - What stands at a place below the root, never following a link there
+ * @param flavor - Whose kernel resolves the link: its separators split the text
+ * @returns `undefined` when the text leads to something that exists inside the tree, by a walk
+ *   that passes through no link; otherwise why it is refused
+ */
+export declare function linkTextRefusal(linkDir: readonly string[], text: string, kindAt: (place: readonly string[]) => PlaceKind, flavor: PathFlavor): LinkTextRefusal | undefined;
+//# sourceMappingURL=link-walk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"link-walk.d.ts","sourceRoot":"","sources":["../../src/tree-change/link-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE7D,oGAAoG;AACpG,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAgBtD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,eAAe,GAAG,SAAS,CAiB1K"}

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

@@ -0,0 +1,69 @@
+/**
+ * Where a symbolic link's text leads, decided by WALKING it — the rule for a link in a tree that
+ * will be RELOCATED (an install copies the tree, each link's text verbatim). Pure: the caller says
+ * what stands at each place.
+ *
+ * A lexical resolve cancels `x/..` without asking what `x` is, so `l -> up/../../../secret` beside
+ * `up -> ../..` reads as inside the tree while the kernel follows `up` first and lands three
+ * levels above it. And where such a link dangles at the source, its real path proves nothing: it
+ * resolves once the tree is copied somewhere those levels exist. So nothing is assumed:
+ *
+ * - the text is relative — an absolute one points at the same place wherever the copy lands;
+ * - walked one segment at a time from the link's own directory, the place never rises above the
+ *   tree's root — not even to come back in by the tree's own name, which the copy may not keep;
+ * - no component the walk passes THROUGH is a link: a link may point at something, never through
+ *   another link, whose own text decides where the rest of the walk goes;
+ * - the place it ends at exists. A link that dangles is refused, because nothing can be proved
+ *   about where it lands after the copy.
+ *
+ * The walk is a MODEL of the kernel's resolution, and a model can be wrong (it once split a text
+ * on a backslash the POSIX kernel reads as part of a name). So its caller holds two more locks
+ * beside it — the one link-chain resolver (`link-chain.ts`), which reads the chain from the link to
+ * its end before anything follows it, and then the kernel's own resolution of the link at the
+ * source — and a link is kept only when all three agree.
+ */
+/**
+ * What separates the components of a link's text is the answer of the kernel that resolves it,
+ * not VAT's. On POSIX only `/` does — a backslash is an ordinary character of a name, so `a\b` is
+ * one component, and reading it as two would count a `..` the kernel never takes.
+ */
+const SEPARATOR = { posix: /\//, win32: /[/\\]/ };
+/** A POSIX root, a UNC root or a drive prefix: absolute, or drive-relative, on some host. */
+const ABSOLUTE = /^([/\\]|[A-Za-z]:)/;
+/** The components of a link's text, as `flavor` splits it: `.` and empty ones dropped. */
+function segmentsOf(text, flavor) {
+    return text.split(SEPARATOR[flavor]).filter((segment) => segment !== '' && segment !== '.');
+}
+/**
+ * Walk a link's text from the directory the link is in.
+ *
+ * @param linkDir - The link's REAL directory, as segments below the tree's root (`[]`: the root itself)
+ * @param text - The link's text, verbatim
+ * @param kindAt - What stands at a place below the root, never following a link there
+ * @param flavor - Whose kernel resolves the link: its separators split the text
+ * @returns `undefined` when the text leads to something that exists inside the tree, by a walk
+ *   that passes through no link; otherwise why it is refused
+ */
+export function linkTextRefusal(linkDir, text, kindAt, flavor) {
+    if (ABSOLUTE.test(text))
+        return { why: 'absolute' };
+    const segments = segmentsOf(text, flavor);
+    const place = [...linkDir];
+    for (const [index, segment] of segments.entries()) {
+        if (segment === '..') {
+            // Every place the walk stands at is a real directory of the tree, so its parent is `place` less one.
+            if (place.pop() === undefined)
+                return { why: 'climbs-out' };
+            continue;
+        }
+        place.push(segment);
+        const kind = kindAt(place);
+        const last = index === segments.length - 1;
+        if (kind === 'absent' || (!last && kind === 'file'))
+            return { why: 'dangling', at: place.join('/') };
+        if (!last && kind === 'link')
+            return { why: 'through-link', at: place.join('/') };
+    }
+    return undefined;
+}
+//# sourceMappingURL=link-walk.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"link-walk.js","sourceRoot":"","sources":["../../src/tree-change/link-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAWH;;;;GAIG;AACH,MAAM,SAAS,GAAyC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACxF,6FAA6F;AAC7F,MAAM,QAAQ,GAAG,oBAAoB,CAAC;AAEtC,0FAA0F;AAC1F,SAAS,UAAU,CAAC,IAAY,EAAE,MAAkB;IAClD,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,CAAC,CAAC;AAC9F,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,OAA0B,EAAE,IAAY,EAAE,MAA+C,EAAE,MAAkB;IAC3I,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC;IACpD,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;IAC3B,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QAClD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,qGAAqG;YACrG,IAAI,KAAK,CAAC,GAAG,EAAE,KAAK,SAAS;gBAAE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC;YAC5D,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3B,MAAM,IAAI,GAAG,KAAK,KAAK,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,KAAK,MAAM,CAAC;YAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACrG,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACpF,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}