harnery 0.35.0 → 0.36.0

package/dist/core/storage/inventory.js

@@ -0,0 +1,666 @@
+import { lstat as defaultLstat, opendir as defaultOpendir, realpath as defaultRealpath, } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { HARNERY_STORAGE_INVENTORY_SCHEMA, } from "./contract.js";
+import { inspectStructuredLogRetention } from "./log-retention.js";
+const MAX_CONCURRENCY = 16;
+/**
+ * Inventory registered storage with metadata-only, depth-first traversal.
+ * The complete `.harnery` root is scanned once; outside it, only explicit
+ * registered filesystem roots are visited.
+ */
+export async function inventoryStorage(catalog, options = {}) {
+    const coordStorageRoot = resolve(catalog.context.coord_root, ".harnery");
+    const capturedAt = (options.now ?? (() => new Date()))();
+    const state = {
+        catalog,
+        coordStorageRoot,
+        families: new Map(catalog.families.map((family) => [
+            family.id,
+            {
+                family,
+                roots: family.resolved_roots.map((root, index) => ({
+                    root,
+                    index,
+                    base_present: false,
+                    matched: false,
+                    totals: emptyTotals(),
+                    reasons: new Set(),
+                })),
+                totals: emptyTotals(),
+                reasons: new Set(),
+            },
+        ])),
+        totals: emptyTotals(),
+        coordinationRootTotals: emptyTotals(),
+        externalRootTotals: emptyTotals(),
+        issues: new Map(),
+        allocatedBytes: options.allocatedBytes ?? allocatedBytes,
+        fs: {
+            lstat: options.fs?.lstat ?? defaultLstat,
+            opendir: options.fs?.opendir ?? defaultOpendir,
+            realpath: options.fs?.realpath ?? defaultRealpath,
+        },
+    };
+    await inspectRegisteredRoots(state);
+    await scanBoundary(state, coordStorageRoot, true);
+    for (const boundary of externalBoundaries(state)) {
+        await scanBoundary(state, boundary, false);
+    }
+    return {
+        schema: HARNERY_STORAGE_INVENTORY_SCHEMA,
+        captured_at: capturedAt.toISOString(),
+        privacy: { content_read: false, path_mode: "aggregate-labels" },
+        scan: {
+            mode: "streaming-lstat",
+            max_concurrency: MAX_CONCURRENCY,
+            project_filesystem_scope: ".harnery-and-registered-external-roots",
+        },
+        filter: {},
+        filesystem_totals: observedTotals(state.totals),
+        scope_totals: {
+            coordination_root: observedTotals(state.coordinationRootTotals),
+            registered_external_roots: observedTotals(state.externalRootTotals),
+        },
+        families: [...state.families.values()]
+            .map((family) => familyInventory(catalog, family, capturedAt))
+            .sort((left, right) => left.family_id.localeCompare(right.family_id)),
+        issues: issueRows(state.issues),
+    };
+}
+export function filterStorageInventory(report, filter) {
+    return {
+        ...report,
+        filter: {
+            ...(filter.family_id ? { family_id: filter.family_id } : {}),
+            ...(filter.storage_class ? { storage_class: filter.storage_class } : {}),
+        },
+        families: report.families.filter((family) => (!filter.family_id || family.family_id === filter.family_id) &&
+            (!filter.storage_class || family.storage_class === filter.storage_class)),
+    };
+}
+function emptyTotals() {
+    return {
+        regular_files: 0,
+        logical_bytes: 0,
+        allocated_bytes: 0,
+        allocated_available: true,
+        allocated_identities: new Set(),
+    };
+}
+async function inspectRegisteredRoots(state) {
+    for (const family of state.families.values()) {
+        if (family.family.provider.inventory === "delegated") {
+            family.reasons.add("delegated_inventory_unavailable");
+            for (const root of family.roots)
+                root.reasons.add("delegated_inventory_unavailable");
+            continue;
+        }
+        for (const root of family.roots) {
+            let metadata;
+            try {
+                metadata = await state.fs.lstat(root.root.path);
+            }
+            catch (error) {
+                if (isMissing(error))
+                    root.reasons.add("root_dormant");
+                else
+                    root.reasons.add("unreadable_path");
+                continue;
+            }
+            if (metadata.isSymbolicLink()) {
+                root.reasons.add("symlink_rejected");
+                continue;
+            }
+            const expectedDirectory = root.root.kind === "directory";
+            if ((expectedDirectory && !metadata.isDirectory()) ||
+                (!expectedDirectory && !metadata.isFile())) {
+                root.reasons.add("wrong_root_type");
+                continue;
+            }
+            root.base_present = true;
+        }
+    }
+}
+function externalBoundaries(state) {
+    const boundaries = new Set();
+    for (const family of state.families.values()) {
+        if (family.family.provider.inventory !== "filesystem")
+            continue;
+        for (const { root } of family.roots) {
+            if (!within(state.coordStorageRoot, root.path))
+                boundaries.add(resolve(root.path));
+        }
+    }
+    const ordered = [...boundaries].sort((left, right) => left.length - right.length || left.localeCompare(right));
+    const collapsed = [];
+    for (const boundary of ordered) {
+        if (!collapsed.some((parent) => within(parent, boundary)))
+            collapsed.push(boundary);
+    }
+    return collapsed;
+}
+async function scanBoundary(state, boundary, completeCoordinationRoot) {
+    let metadata;
+    try {
+        metadata = await state.fs.lstat(boundary);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            recordIssue(state, "unreadable_path");
+        return;
+    }
+    if (metadata.isSymbolicLink()) {
+        recordBoundaryIssue(state, boundary, "symlink_rejected", completeCoordinationRoot);
+        return;
+    }
+    if (!metadata.isFile() && !metadata.isDirectory()) {
+        recordBoundaryIssue(state, boundary, "special_file_rejected", completeCoordinationRoot);
+        return;
+    }
+    let safeRoot;
+    try {
+        safeRoot = await state.fs.realpath(boundary);
+    }
+    catch {
+        recordBoundaryIssue(state, boundary, "unreadable_path", completeCoordinationRoot);
+        return;
+    }
+    let targetMetadata;
+    try {
+        targetMetadata = await state.fs.lstat(safeRoot);
+    }
+    catch {
+        recordBoundaryIssue(state, boundary, "unreadable_path", completeCoordinationRoot);
+        return;
+    }
+    if (!sameIdentity(metadata, targetMetadata) ||
+        metadata.isDirectory() !== targetMetadata.isDirectory() ||
+        metadata.isFile() !== targetMetadata.isFile()) {
+        recordBoundaryIssue(state, boundary, "symlink_rejected", completeCoordinationRoot);
+        return;
+    }
+    if (metadata.isFile()) {
+        await recordRegularFile(state, safeRoot, boundary, metadata, completeCoordinationRoot, safeRoot);
+        return;
+    }
+    await scanDirectoryTree(state, safeRoot, boundary, metadata, completeCoordinationRoot);
+}
+async function scanDirectoryTree(state, safeRoot, logicalRoot, rootMetadata, completeCoordinationRoot) {
+    const queue = [
+        {
+            physical: safeRoot,
+            logical: logicalRoot,
+            expectedIdentity: fileIdentity(rootMetadata),
+        },
+    ];
+    for (let index = 0; index < queue.length; index += 1) {
+        const current = queue[index];
+        const children = await scanDirectory(state, current.physical, current.logical, current.expectedIdentity, safeRoot, completeCoordinationRoot);
+        queue.push(...children);
+    }
+}
+async function scanDirectory(state, directoryPath, logicalDirectoryPath, expectedIdentity, safeRoot, completeCoordinationRoot) {
+    let metadata;
+    try {
+        metadata = await state.fs.lstat(directoryPath);
+    }
+    catch {
+        recordPathIssue(state, logicalDirectoryPath, "unreadable_path", completeCoordinationRoot);
+        return [];
+    }
+    if (metadata.isSymbolicLink()) {
+        recordPathIssue(state, logicalDirectoryPath, "symlink_rejected", completeCoordinationRoot);
+        return [];
+    }
+    if (expectedIdentity && !matchesIdentity(metadata, expectedIdentity)) {
+        recordPathIssue(state, logicalDirectoryPath, "symlink_rejected", completeCoordinationRoot);
+        return [];
+    }
+    if (!metadata.isDirectory()) {
+        recordPathIssue(state, logicalDirectoryPath, "wrong_root_type", completeCoordinationRoot);
+        return [];
+    }
+    let canonical;
+    try {
+        canonical = await state.fs.realpath(directoryPath);
+    }
+    catch {
+        recordPathIssue(state, logicalDirectoryPath, "unreadable_path", completeCoordinationRoot);
+        return [];
+    }
+    if (!within(safeRoot, canonical)) {
+        recordPathIssue(state, logicalDirectoryPath, "symlink_rejected", completeCoordinationRoot);
+        return [];
+    }
+    let canonicalMetadata;
+    try {
+        canonicalMetadata = await state.fs.lstat(canonical);
+    }
+    catch {
+        recordPathIssue(state, logicalDirectoryPath, "unreadable_path", completeCoordinationRoot);
+        return [];
+    }
+    if (!canonicalMetadata.isDirectory() || !sameIdentity(metadata, canonicalMetadata)) {
+        recordPathIssue(state, logicalDirectoryPath, "symlink_rejected", completeCoordinationRoot);
+        return [];
+    }
+    let directory;
+    try {
+        directory = await state.fs.opendir(canonical);
+    }
+    catch {
+        recordPathIssue(state, logicalDirectoryPath, "unreadable_path", completeCoordinationRoot);
+        return [];
+    }
+    try {
+        const [revalidatedPath, revalidatedCanonical] = await Promise.all([
+            state.fs.lstat(directoryPath),
+            state.fs.lstat(canonical),
+        ]);
+        if (revalidatedPath.isSymbolicLink() ||
+            !sameIdentity(metadata, revalidatedPath) ||
+            !sameIdentity(metadata, revalidatedCanonical)) {
+            await closeRejectedDirectory(directory);
+            recordPathIssue(state, logicalDirectoryPath, "symlink_rejected", completeCoordinationRoot);
+            return [];
+        }
+    }
+    catch {
+        await closeRejectedDirectory(directory);
+        recordPathIssue(state, logicalDirectoryPath, "unreadable_path", completeCoordinationRoot);
+        return [];
+    }
+    const childDirectories = [];
+    let batch = [];
+    for await (const entry of directory) {
+        batch.push({
+            physical: join(canonical, entry.name),
+            logical: join(logicalDirectoryPath, entry.name),
+        });
+        if (batch.length === MAX_CONCURRENCY) {
+            childDirectories.push(...(await scanEntryBatch(state, batch, safeRoot, completeCoordinationRoot)));
+            batch = [];
+        }
+    }
+    if (batch.length > 0) {
+        childDirectories.push(...(await scanEntryBatch(state, batch, safeRoot, completeCoordinationRoot)));
+    }
+    return childDirectories;
+}
+async function scanEntryBatch(state, paths, safeRoot, completeCoordinationRoot) {
+    const children = await Promise.all(paths.map((path) => scanEntry(state, path, safeRoot, completeCoordinationRoot)));
+    return children.filter((path) => path !== undefined);
+}
+async function scanEntry(state, path, safeRoot, completeCoordinationRoot) {
+    let child;
+    try {
+        child = await state.fs.lstat(path.physical);
+    }
+    catch {
+        recordPathIssue(state, path.logical, "unreadable_path", completeCoordinationRoot);
+        return undefined;
+    }
+    if (child.isSymbolicLink()) {
+        if (!allowsSymbolicLinkSkip(state, path.logical)) {
+            recordPathIssue(state, path.logical, "symlink_rejected", completeCoordinationRoot);
+        }
+    }
+    else if (child.isDirectory()) {
+        return { ...path, expectedIdentity: fileIdentity(child) };
+    }
+    else if (child.isFile()) {
+        await recordRegularFile(state, path.physical, path.logical, child, completeCoordinationRoot, safeRoot);
+    }
+    else {
+        recordPathIssue(state, path.logical, "special_file_rejected", completeCoordinationRoot);
+    }
+    return undefined;
+}
+async function closeRejectedDirectory(directory) {
+    try {
+        await directory.close();
+    }
+    catch {
+        // Rejection remains fail-closed even when the platform already closed it.
+    }
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function fileIdentity(stats) {
+    return { dev: stats.dev, ino: stats.ino };
+}
+function matchesIdentity(stats, identity) {
+    return stats.dev === identity.dev && stats.ino === identity.ino;
+}
+async function recordRegularFile(state, physicalPath, logicalPath, metadata, completeCoordinationRoot, safeRoot) {
+    let canonical;
+    let canonicalMetadata;
+    try {
+        canonical = await state.fs.realpath(physicalPath);
+        canonicalMetadata = await state.fs.lstat(canonical);
+    }
+    catch {
+        recordPathIssue(state, logicalPath, "unreadable_path", completeCoordinationRoot);
+        return;
+    }
+    if (!within(safeRoot, canonical) || !sameIdentity(metadata, canonicalMetadata)) {
+        recordPathIssue(state, logicalPath, "symlink_rejected", completeCoordinationRoot);
+        return;
+    }
+    const matches = filesystemMatches(state, logicalPath);
+    if (!completeCoordinationRoot && matches.length === 0)
+        return;
+    const hardLinkAmbiguous = metadata.nlink > 1 && !allowsHardLink(state, logicalPath);
+    if (hardLinkAmbiguous)
+        recordIssue(state, "hard_link_ambiguous");
+    const allocatedCandidate = state.allocatedBytes(metadata);
+    const allocated = allocatedCandidate !== undefined &&
+        Number.isSafeInteger(allocatedCandidate) &&
+        allocatedCandidate >= 0
+        ? allocatedCandidate
+        : undefined;
+    const allocationIdentity = metadata.nlink > 1 ? fileIdentity(metadata) : undefined;
+    addFile(state.totals, metadata.size, allocated, allocationIdentity);
+    addFile(completeCoordinationRoot ? state.coordinationRootTotals : state.externalRootTotals, metadata.size, allocated, allocationIdentity);
+    if (allocated === undefined)
+        recordIssue(state, "allocated_bytes_unavailable");
+    if (matches.length === 0) {
+        const exclusion = state.catalog.exclusions.some(({ root }) => rootMatches(root, logicalPath));
+        recordIssue(state, exclusion ? "host_exclusion" : "unregistered_path");
+        return;
+    }
+    if (matches.length > 1) {
+        recordIssue(state, "overlapping_registration");
+        for (const match of matches)
+            match.reasons.add("overlapping_registration");
+        return;
+    }
+    const family = matches[0];
+    const roots = family.roots.filter(({ root }) => rootMatches(root, logicalPath));
+    if (roots.length !== 1) {
+        recordIssue(state, "overlapping_registration");
+        family.reasons.add("overlapping_registration");
+        return;
+    }
+    addFile(family.totals, metadata.size, allocated, allocationIdentity);
+    family.roots[roots[0].index].matched = true;
+    addFile(family.roots[roots[0].index].totals, metadata.size, allocated, allocationIdentity);
+    if (hardLinkAmbiguous) {
+        family.reasons.add("hard_link_ambiguous");
+        family.roots[roots[0].index].reasons.add("hard_link_ambiguous");
+    }
+    if (allocated === undefined) {
+        family.reasons.add("allocated_bytes_unavailable");
+        family.roots[roots[0].index].reasons.add("allocated_bytes_unavailable");
+    }
+}
+function recordPathIssue(state, path, reason, completeCoordinationRoot) {
+    const matches = filesystemMatches(state, path);
+    if (!completeCoordinationRoot && matches.length === 0)
+        return;
+    recordIssue(state, reason);
+    if (matches.length === 0 && completeCoordinationRoot)
+        recordIssue(state, "unregistered_path");
+    for (const family of matches) {
+        family.reasons.add(reason);
+        for (const root of family.roots.filter(({ root }) => rootMatches(root, path))) {
+            root.reasons.add(reason);
+        }
+    }
+}
+function recordBoundaryIssue(state, path, reason, completeCoordinationRoot) {
+    const resolved = resolve(path);
+    const matches = [...state.families.values()].filter((family) => family.family.provider.inventory === "filesystem" &&
+        family.roots.some(({ root }) => resolve(root.path) === resolved));
+    recordIssue(state, reason);
+    if (matches.length === 0 && completeCoordinationRoot)
+        recordIssue(state, "unregistered_path");
+    for (const family of matches) {
+        family.reasons.add(reason);
+        for (const root of family.roots.filter(({ root }) => resolve(root.path) === resolved)) {
+            root.reasons.add(reason);
+        }
+    }
+}
+function filesystemMatches(state, path) {
+    return state.catalog
+        .familiesForPath(path)
+        .filter((family) => family.provider.inventory === "filesystem")
+        .map((family) => state.families.get(family.id));
+}
+function addFile(totals, logicalBytes, allocated, allocationIdentity) {
+    totals.regular_files += 1;
+    totals.logical_bytes += logicalBytes;
+    if (allocated === undefined || !Number.isSafeInteger(allocated) || allocated < 0) {
+        totals.allocated_available = false;
+    }
+    else {
+        const key = allocationIdentity
+            ? `${allocationIdentity.dev}:${allocationIdentity.ino}`
+            : undefined;
+        if (key === undefined || !totals.allocated_identities.has(key)) {
+            if (key !== undefined)
+                totals.allocated_identities.add(key);
+            totals.allocated_bytes += allocated;
+        }
+    }
+}
+function allowsSymbolicLinkSkip(state, path) {
+    return matchingRoot(state, path)?.root.link_handling?.symbolic_links === "skip";
+}
+function allowsHardLink(state, path) {
+    return matchingRoot(state, path)?.root.link_handling?.hard_links === "allow";
+}
+function matchingRoot(state, path) {
+    const families = filesystemMatches(state, path);
+    if (families.length !== 1)
+        return undefined;
+    const roots = families[0].roots.filter(({ root }) => rootMatches(root, path));
+    if (roots.length !== 1)
+        return undefined;
+    return roots[0];
+}
+function allocatedBytes(stats) {
+    if (typeof stats.blocks !== "number" || !Number.isSafeInteger(stats.blocks))
+        return undefined;
+    const bytes = stats.blocks * 512;
+    return Number.isSafeInteger(bytes) ? bytes : undefined;
+}
+function recordIssue(state, reason) {
+    state.issues.set(reason, (state.issues.get(reason) ?? 0) + 1);
+}
+function familyInventory(catalog, accumulator, capturedAt) {
+    const delegated = accumulator.family.provider.inventory === "delegated";
+    const roots = accumulator.roots.map((root) => rootInventory(catalog, accumulator, root));
+    const rootStates = new Set(roots.map(({ state }) => state));
+    const reasons = new Set(accumulator.reasons);
+    for (const root of roots)
+        for (const reason of root.reason_codes)
+            reasons.add(reason);
+    let state;
+    if (delegated)
+        state = "delegated";
+    else if (rootStates.has("unavailable") && rootStates.size === 1)
+        state = "unavailable";
+    else if (rootStates.has("unavailable") || rootStates.has("partial"))
+        state = "partial";
+    else if (rootStates.has("present") && rootStates.has("dormant"))
+        state = "partial";
+    else if (rootStates.has("present"))
+        state = "present";
+    else
+        state = "dormant";
+    if (state === "dormant" || rootStates.has("dormant"))
+        reasons.add("root_dormant");
+    return {
+        family_id: accumulator.family.id,
+        source: accumulator.family.source,
+        storage_class: accumulator.family.storage_class,
+        policy_version: accumulator.family.policy.policy_version,
+        provider_id: accumulator.family.provider.provider_id,
+        inventory: accumulator.family.provider.inventory,
+        maintenance: maintenance(accumulator.family, state, reasons),
+        state,
+        reason_codes: [...reasons].sort(),
+        totals: delegated
+            ? unavailableTotals("delegated_inventory_unavailable")
+            : observedTotals(accumulator.totals),
+        roots,
+        ...(isLogFamily(accumulator.family)
+            ? { log_storage: logStorageStatus(accumulator.family, capturedAt) }
+            : {}),
+    };
+}
+function logStorageStatus(family, now) {
+    const inspection = inspectStructuredLogRetention(family, now);
+    const effective = family.effective_log_retention;
+    return {
+        effective_policy: effective
+            ? {
+                state: effective.state,
+                max_bytes: effective.max_bytes,
+                max_age_days: effective.max_age_days,
+                max_age_ms: effective.max_age_ms,
+                fingerprint: effective.effective_policy_fingerprint,
+                provenance: effective.provenance,
+                diagnostics: effective.diagnostics,
+            }
+            : null,
+        usage: inspection.usage,
+        pressure: inspection.pressure,
+        retention: inspection.retention,
+    };
+}
+function isLogFamily(family) {
+    return family.storage_class === "operational-log" || family.storage_class === "debug-log";
+}
+function rootInventory(catalog, family, root) {
+    const delegated = family.family.provider.inventory === "delegated";
+    const reasons = new Set(root.reasons);
+    let state;
+    if (delegated)
+        state = "delegated";
+    else if (reasons.has("unreadable_path") || reasons.has("wrong_root_type"))
+        state = "unavailable";
+    else if (reasons.has("symlink_rejected"))
+        state = "unavailable";
+    else if (root.matched || (root.base_present && root.root.match === "subtree"))
+        state = "present";
+    else if (root.base_present && root.root.match === "exact" && root.root.kind === "directory") {
+        state = "present";
+    }
+    else {
+        state = "dormant";
+        reasons.add("root_dormant");
+    }
+    return {
+        root_index: root.index,
+        root_label: rootLabel(catalog, family.family.id, root),
+        ownership: root.root.ownership ?? "harnery",
+        state,
+        reason_codes: [...reasons].sort(),
+        totals: delegated
+            ? unavailableTotals("delegated_inventory_unavailable")
+            : observedTotals(root.totals),
+    };
+}
+function rootLabel(catalog, familyId, root) {
+    const rel = relative(catalog.context.coord_root, root.root.path);
+    if (rel === "")
+        return ".";
+    if (!rel.startsWith("..") && !isAbsolute(rel))
+        return rel.split(sep).join("/");
+    return `<external:${familyId}:${root.index + 1}>`;
+}
+function maintenance(family, state, reasons) {
+    if (family.provider.maintenance === "delegated") {
+        return { state: "delegated", reason_code: "maintenance_delegated" };
+    }
+    if (family.provider.maintenance === "none") {
+        return { state: "ineligible", reason_code: "maintenance_not_registered" };
+    }
+    if (family.policy.retention.status !== "active") {
+        return { state: "ineligible", reason_code: "maintenance_policy_inactive" };
+    }
+    if (state !== "present" || reasons.has("allocated_bytes_unavailable")) {
+        return { state: "ineligible", reason_code: "provider_unavailable" };
+    }
+    if ([...reasons].some((reason) => [
+        "host_exclusion",
+        "hard_link_ambiguous",
+        "overlapping_registration",
+        "special_file_rejected",
+        "symlink_rejected",
+        "unreadable_path",
+        "unregistered_path",
+        "wrong_root_type",
+    ].includes(reason))) {
+        return { state: "ineligible", reason_code: "provider_unavailable" };
+    }
+    return { state: "eligible" };
+}
+function observedTotals(totals) {
+    return {
+        regular_files: observed("files", totals.regular_files),
+        logical_bytes: observed("bytes", totals.logical_bytes),
+        allocated_bytes: totals.allocated_available
+            ? observed("bytes", totals.allocated_bytes)
+            : unavailable("bytes", "allocated_bytes_unavailable"),
+    };
+}
+function unavailableTotals(reason) {
+    return {
+        regular_files: unavailable("files", reason),
+        logical_bytes: unavailable("bytes", reason),
+        allocated_bytes: unavailable("bytes", reason),
+    };
+}
+function observed(unit, value) {
+    return { state: "observed", unit, value };
+}
+function unavailable(unit, reason_code) {
+    return { state: "unavailable", unit, reason_code };
+}
+function issueRows(issues) {
+    return [...issues.entries()]
+        .map(([reason_code, count]) => ({ reason_code, count, maintenance_eligible: false }))
+        .sort((left, right) => left.reason_code.localeCompare(right.reason_code));
+}
+function rootMatches(root, candidate) {
+    const path = resolve(candidate);
+    if (root.match === "exact")
+        return resolve(root.path) === path;
+    const remainder = relative(root.path, path).split(sep).join("/");
+    if (remainder === "" || remainder.startsWith("..") || isAbsolute(remainder))
+        return false;
+    if (root.match === "subtree")
+        return true;
+    return root.include.some((pattern) => globRegex(pattern).test(remainder));
+}
+function globRegex(pattern) {
+    let source = "^";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        if (character === "*") {
+            if (pattern[index + 1] === "*") {
+                source += ".*";
+                index += 1;
+            }
+            else
+                source += "[^/]*";
+        }
+        else if (character === "?")
+            source += "[^/]";
+        else
+            source += character.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+    }
+    return new RegExp(`${source}$`);
+}
+function within(root, candidate) {
+    const remainder = relative(resolve(root), resolve(candidate));
+    return remainder === "" || (!remainder.startsWith("..") && !isAbsolute(remainder));
+}
+function isMissing(error) {
+    return error?.code === "ENOENT";
+}