@struktoai/mirage-core/dist/core/github/tree.d.ts

A Unified Virtual Filesystem For AI Agents

import type { GitHubAccessor } from '../../accessor/github.ts';
import { DirListing, FileStat } from '../../types.ts';
import type { GitHubTreeItem } from './client.ts';
import { type GitHubTransport } from './client.ts';
import { type TreeEntry } from './tree_entry.ts';
export declare function buildTreeMap(tree: GitHubTreeItem[]): Record<string, TreeEntry>;
/**
 * The row for one tree row, the same from every route: a file's carries its
 * blob sha as its fingerprint, and every row its sha.
 *
 * Mirrors Python's `row_of`.
 */
export declare function rowOf(entry: TreeEntry, name: string): FileStat;
/**
 * Each folder's rows, keyed by its repo-relative path ('' the root). The
 * repository root always has a listing, even when the tree is empty, so an
 * empty repository lists as empty rather than missing.
 *
 * Mirrors Python's `tree_rows`.
 */
export declare function treeRows(tree: Record<string, TreeEntry>): Map<string, FileStat[]>;
/**
 * The listing of the folder `rel` out of the whole tree, with every folder
 * below it as seeds, all at `version`.
 *
 * Mirrors Python's `tree_listing`.
 *
 * Throws:
 *   NotADirectoryError: a file is at `rel`.
 *   FileNotFoundError: nothing is.
 */
export declare function treeListing(tree: Record<string, TreeEntry>, rel: string, version: string | null, virtual: string): DirListing;
/**
 * Replace the accessor's tree with one response.
 */
export declare function reseatTree(accessor: GitHubAccessor, tree: Record<string, TreeEntry>, truncated: boolean): void;
/**
 * Fetch the ref's recursive tree and reseat the accessor on it.
 *
 * Mirrors Python's `refresh_tree`.
 *
 * Returns:
 *   { tree, version } | null: the tree, keyed by repo-relative path, and the
 *   head it was read at, taken from this response rather than the accessor a
 *   concurrent refresh may have reseated since; null when GitHub truncated
 *   it, which then names only some paths.
 */
export declare function refreshTree(accessor: GitHubAccessor): Promise<{
    tree: Record<string, TreeEntry>;
    version: string | null;
} | null>;
/**
 * Look one path up in its parent directory's listing, with one request.
 *
 * Asks `git/trees/{ref}:{parent}`, whose rows are exactly the recursive
 * tree's for that directory: the same sha, and a symlink's own length rather
 * than its target's, which the contents API reports instead. The expression
 * is encoded as a single segment: Octokit reads an unencoded `:src` in a
 * path as a template placeholder and drops it, which asked for the root
 * tree instead, and a `/` in the parent or the ref would split the segment.
 *
 * Mirrors Python's `point_row`.
 *
 * Args:
 *   accessor (GitHubAccessor): the mount's accessor.
 *   rel (string): the path as the mount sees it.
 *
 * Returns:
 *   { entry, truncated } | null: the row (null when the listing has no such
 *   name) and whether GitHub truncated the listing, or null when the parent
 *   could not be seen and the whole tree has to answer.
 */
export declare function pointRow(accessor: GitHubAccessor, rel: string): Promise<{
    entry: TreeEntry | null;
    truncated: boolean;
} | null>;
/**
 * Fetch the recursive tree of `ref`, and the head it answered at.
 *
 * A tree asked by a branch, a tag or a commit sha names the commit it
 * resolved to as its top-level `sha` (measured against GitHub, 2026-09-30),
 * so the rows and the version come from one response.
 *
 * Returns:
 *   { tree, truncated, sha }: the rows, GitHub's `truncated` flag, and the
 *   head commit sha, or null when the response names none.
 */
export declare function fetchTree(transport: GitHubTransport, owner: string, repo: string, ref: string): Promise<{
    tree: GitHubTreeItem[];
    truncated: boolean;
    sha: string | null;
}>;
/**
 * Ask which commit `ref` resolves to, with one shallow request: the shallow
 * tree of the root answers the same top-level `sha` as the recursive one, at
 * a fraction of the size.
 *
 * Returns:
 *   string | null: the head commit sha, or null when the response names none.
 */
export declare function fetchHead(transport: GitHubTransport, owner: string, repo: string, ref: string): Promise<string | null>;
export declare function headOf(data: {
    sha?: unknown;
}): string | null;
export declare function dropSubmodules(tree: GitHubTreeItem[]): GitHubTreeItem[];
/**
 * Fetch one directory's tree (non-recursive), and whether GitHub cut it.
 *
 * Args:
 *   treeSha (string): a raw tree sha, ref, or `{ref}:{dir}` expression.
 *
 * Returns:
 *   { tree, truncated }: the rows, submodule gitlinks excluded, and
 *   GitHub's `truncated` flag.
 *
 * Throws:
 *   GitHubApiError: the response carries no tree, which must not read as
 *   an empty directory.
 */
export declare function fetchDirPage(transport: GitHubTransport, owner: string, repo: string, treeSha: string): Promise<{
    tree: GitHubTreeItem[];
    truncated: boolean;
}>;
/**
 * Fetch a single directory's whole tree (non-recursive).
 *
 * Used as fallback when the recursive tree was truncated, where the listing
 * is cached as complete, so a directory GitHub cut short is refused rather
 * than returned: a name past the cut would otherwise read as absent, which a
 * `read: fresh` probe or a drift check takes as gone.
 *
 * Mirrors Python's `fetch_dir_tree`.
 *
 * Throws:
 *   GitHubApiError: GitHub truncated the listing, or sent no tree.
 */
export declare function fetchDirTree(transport: GitHubTransport, owner: string, repo: string, treeSha: string): Promise<GitHubTreeItem[]>;
//# sourceMappingURL=tree.d.ts.map