@struktoai/mirage-core/dist/view/namespace_view.d.ts

A Unified Virtual Filesystem For AI Agents

import { FileStat, type PathSpec, type Visibility } from '../types.ts';
import type { LinkView, NamespaceLinks } from './types.ts';
/**
 * The child segments of `parent` that some allowed path runs through.
 *
 * The one session filter both namespace enumerations share, because both
 * owe a segment to a deeper thing rather than to an entry of its own: a
 * mount prefix and a link path each synthesize every directory above it,
 * and the segment is visible exactly when at least one of the things that
 * synthesized it is.
 *
 * The full path is what gets tested, never the segment. A hide is
 * subtree-closed on all three of its planes (an exact entry contains its
 * subtree, a component pattern matches any segment, an anchored one is
 * tested against every ancestor), so testing the deeper path is strictly
 * stronger: a segment can only be withheld by this, never granted.
 * Testing the segment instead is what leaked the name of a namespace-only
 * ancestor whose only mount or link the session hides, a directory that
 * answers ENOENT to every verb applied to it.
 */
export declare function visibleChildSegments(vis: Visibility | null, paths: Iterable<string>, parent: string): string[];
/**
 * Immediate child segments of mounts strictly under `parent`.
 *
 * Session-filtered by `visibleChildSegments`: a child name appears only
 * when some mount whose prefix runs through it is visible to the current
 * session, so a scoped session never learns an ungranted mount's name
 * from a listing. Hidden names (leading dot) are included; presentation
 * filtering is the consumer's job, exactly as for backend entries.
 */
export declare function childMountNames(vis: Visibility | null, prefixes: readonly string[], parent: string): string[];
/**
 * Every child segment the namespace owes `parent`: mounts + links.
 *
 * The one union both consumers derive from: the dispatcher merges these
 * names into its readdir and the `childMounts` fact offers them to
 * listing commands, so the shell and the ops surface cannot disagree
 * about what a directory holds.
 */
export declare function namespaceNames(vis: Visibility | null, prefixes: readonly string[], links: NamespaceLinks | null, parent: string): string[];
/**
 * Merge namespace structure into a backend readdir listing.
 *
 * Child mounts and symlinks are namespace state no backend can see, so
 * a listing that stops at one backend misses both. Merged names are
 * appended as virtual paths (the shape RAM-style backends already
 * emit); deduplication is by final path segment because backends
 * disagree on entry shape (bare names, trailing-slash names, full
 * paths).
 */
export declare function mergeReaddir(vis: Visibility | null, entries: readonly string[], prefixes: readonly string[], links: NamespaceLinks | null, parent: string): string[];
/**
 * A listing for a directory that exists only as namespace structure.
 *
 * `/data/x` exists when a mount sits at `/data/x/y` or a link lives
 * directly under it, even though the `/data` backend holds nothing at
 * `/x`. Null when the namespace knows nothing there either, so a caller
 * re-throws the backend's miss.
 */
export declare function namespaceListing(vis: Visibility | null, prefixes: readonly string[], links: NamespaceLinks | null, parent: string): string[] | null;
/**
 * A directory stat for a path that exists only as namespace structure.
 *
 * The listing and the stat must agree: a directory `readdir` can serve
 * (because a mount or a link sits below it) must stat as a directory,
 * or `os.walk` and `Path.is_dir` break on it.
 */
export declare function namespaceStat(vis: Visibility | null, prefixes: readonly string[], links: NamespaceLinks | null, path: string): FileStat | null;
/**
 * Whether a hide or a path rule judges anything a command's operands
 * reach, so a native walk that classifies the raw tree gives way to the
 * checked one.
 *
 * Per operand, not per session: a hidden `.env` under `/repo` must not
 * force `find` on `/s3` off its native op. The hides are the running
 * session's and the rules the running command's gate; `prefix` is the
 * mount root, judged in place of a glob operand. Mirrors Python's
 * paths_scoped.
 */
export declare function pathsScoped(paths: readonly PathSpec[], prefix?: string): boolean;
/**
 * stat(2) over a table whose stat is lstat(2): a link answers for what it
 * leads to.
 *
 * What a walker that follows links (`find -L`, `du -L`, `grep -R`) asks of
 * each entry: a link to a directory is a directory to walk and a link to a
 * file is that file, under the link's own name. A dangling link stays the
 * link, which is what GNU reports when the target cannot be statted, and a
 * chain that loops throws ELOOP. `path` is the entry as `stat` takes it;
 * without `links` the walk follows none and `stat` answers alone. Mirrors
 * Python's followed_stat.
 */
export declare function followedStat<P extends string | PathSpec>(stat: (path: P) => Promise<FileStat>, links: LinkView | null | undefined, path: P): Promise<FileStat>;
//# sourceMappingURL=namespace_view.d.ts.map