@struktoai/mirage-core/dist/utils/glob_walk.d.ts

A Unified Virtual Filesystem For AI Agents

import type { FollowOperands, SessionAccess } from '../view/types.ts';
import { type FileStat, PathSpec, type ReaddirFn, type StatFn } from '../types.ts';
/**
 * Opt in by assigning a debug sink, as Python's module logger is off until
 * configured: a glob that lists nothing is routine, and stdout may carry data.
 */
export declare const logger: {
    debug?: (message: string) => void;
};
export declare const GLOB_CHARS: string[];
/**
 * A glob resolver, bound to the readdir and stat it walks with: the
 * expansion of each operand, in order. Mirrors Python's `ResolveGlobFn`.
 */
export type ResolveGlobFn = (paths: readonly PathSpec[]) => Promise<PathSpec[]>;
/**
 * Whether a glob names a date range a windowed lister can move to.
 *
 * The kit's `patternKinds` table holds one of these per kind: a glob it
 * answers true for reaches the lister and bypasses the index, and any other
 * glob is filtered out of the ordinary cached listing.
 */
export declare function hasGlobSpan(pattern: string): boolean;
/**
 * Whether a glob starts with literal text a query can narrow on.
 *
 * The `patternKinds` twin of `hasGlobSpan` for a backend whose window is a
 * row cap rather than a date range: the literal prefix becomes a prefix match
 * in the query, so the cap covers the region the line named instead of the
 * head of the table.
 */
export declare function hasGlobPrefix(pattern: string): boolean;
/**
 * The literal text a glob starts with, before its first metacharacter.
 *
 * A quoted glob character travels under a private mark and stands for that
 * character literally, so the marks are restored here: `'*'ab*` asks for
 * names starting with a real star.
 */
export declare function globPrefix(pattern: string | null | undefined): string;
/**
 * The literal prefix a glob puts on the stem of a leaf name.
 *
 * A leaf is a stem plus one of the renderer's suffixes, so a literal that has
 * run into a suffix says nothing about the stem and the part that ran in is
 * dropped: `12*.md` narrows to `12`, and `doc-1.m*` narrows to `doc-1` rather
 * than asking for stems that start `doc-1.m`. Only a tail that spells the head
 * of a suffix is dropped, which is what keeps a stem that contains a dot:
 * `acct.2026*` narrows to `acct.2026`, where cutting at the first dot would
 * narrow to `acct` and let the rows nobody asked for eat the window.
 */
export declare function globStemPrefix(pattern: string | null | undefined, suffixes: string[]): string;
/**
 * The half-open range of dates a date-prefixed glob asks for.
 *
 * The literal prefix before the first metacharacter is read as a year, a
 * month or a day, so `2026-*` spans a year and `2026-01-05*` one day. This is
 * what lets a windowed listing honour a glob instead of filtering its own
 * window: the backend moves the window to the span the line named. Dates are
 * floating `YYYY-MM-DD`, since a caller bucketing in a named time zone has to
 * build its own instants from them; UTC instants would shift the window by
 * the offset.
 */
export declare function globSpan(pattern: string | null | undefined): [string, string] | null;
/**
 * The half-open range of dates a literal year, month or day names.
 *
 * The reading `globSpan` applies to a glob's literal prefix, for a caller
 * that cuts the prefix first; separators trailing the literal are ignored.
 */
export declare function literalSpan(literal: string): [string, string] | null;
export declare function hasGlob(segment: string, access?: SessionAccess): boolean;
export declare function markGlobs(text: string): string;
export declare function unmarkGlobs(text: string): string;
/**
 * Mark the glob characters a backslash quotes in raw word text.
 *
 * Read the way bash reads an unquoted word: `\*` is a quoted star and
 * `\\*` is a literal backslash followed by a live star. The backslash is
 * left in place for the quote-removal pass that follows, which drops it
 * and leaves the mark behind.
 */
export declare function markEscapedGlobs(text: string): string;
/**
 * A marked segment as the pattern fnmatch has to see.
 *
 * fnmatch has no escape character, so a quoted glob character is handed
 * over as its own one-character class, exactly what `escapeGlob` builds
 * for text that is literal throughout. Extended operators retain their
 * marks until matching: turning a quoted `@` into `[@]` inside `[a"@"]`
 * would create a nested bracket expression; unquoting it could create a group.
 */
export declare function globPattern(segment: string): string;
/**
 * The word after quote removal, once glob resolution is over.
 *
 * The marks come off here, and a word still carrying a pattern is frozen
 * as its literal: that pattern outlived its marks (an unmatched glob,
 * `set -f`, a backend that could not resolve it), and reading the
 * unmarked text as a pattern again would let a quoted metacharacter
 * match -- `rm '/data/*'?.txt` would be back to reaching every name the
 * live `?` alone would. A word that carried no marks is returned
 * untouched.
 */
export declare function literalWord(item: string | PathSpec): string | PathSpec;
/**
 * Encode text so the glob matcher reads every character literally.
 *
 * fnmatch has no escape character, so each special is wrapped in its own
 * one-character class: `*` becomes `[*]`. A `]` needs no treatment: outside
 * a class it is already literal, and no class can open because every `[`
 * gets wrapped. Extended operators retain the quote marks in `globPattern`.
 */
export declare function escapeGlob(text: string): string;
export declare function isWordShaped(p: PathSpec): boolean;
/** Path components under the active shell's pattern grammar. */
export declare function globParts(pattern: string, access?: SessionAccess): string[];
export declare function spellMatch(raw: string, virtual: string, walked: number, access?: SessionAccess): string;
export type TargetStat = (virtual: string) => Promise<FileStat | null>;
export declare function resolveGlobWith<A, I>(readdir: (accessor: A, path: PathSpec, index?: I) => Promise<string[]>, accessor: A, paths: readonly PathSpec[], index: I | undefined, limit?: number, stat?: (accessor: A, path: PathSpec, index?: I) => Promise<FileStat>, targetStat?: TargetStat, access?: SessionAccess, follow?: FollowOperands, signal?: AbortSignal | null): Promise<PathSpec[]>;
/**
 * Whether one directory entry answers a pathname-expansion segment.
 * `fnmatch` plus bash's leading-dot rule: a name starting with `.` is
 * matched only by a pattern that also starts with `.` (so `*`, `?h` and
 * `[.]h` pass over `.h`), unless the session has `shopt -s dotglob`.
 * Pathname expansion's rule alone; `find -name` and `case` match through
 * `fnmatch` directly.
 */
export declare function globNameMatches(name: string, pattern: string, access?: SessionAccess): boolean;
/**
 * Expand a glob PathSpec segment-by-segment via readdir.
 *
 * Mirrors bash globbing: every path component containing a glob character is
 * matched against the entries of its (already expanded) parent directory, so
 * a mid-path pattern (a `Demo_*` directory segment followed by `page.md`)
 * never reaches the backend as a literal `*` path segment. An intermediate
 * match that cannot be listed (a file, or a vanished entry) is skipped,
 * matching bash's directories-only descent for non-final components.
 */
export declare function expandPattern<A, I>(readdir: (accessor: A, path: PathSpec, index?: I) => Promise<string[]>, accessor: A, path: PathSpec, index?: I, access?: SessionAccess, signal?: AbortSignal | null): Promise<PathSpec[]>;
/**
 * A resolver of glob operands over `readdir`, path-first: `stat` is what lets
 * a trailing slash keep directories only, `targetStat` what a link it matched
 * points at, `follow` the line's operand resolution a typed word's matches
 * take, and `resolved` is told what each resolution answers, in order: the
 * operands a command's reads are warmed ahead of. Mirrors Python's
 * `make_resolve_glob`.
 */
export declare function makeResolveGlob(readdir: ReaddirFn, limit?: number, stat?: StatFn, targetStat?: TargetStat, access?: SessionAccess, follow?: FollowOperands, resolved?: (found: PathSpec[]) => void): ResolveGlobFn;
//# sourceMappingURL=glob_walk.d.ts.map