import { type HttpOptions } from "./http.js";
/** A note a listing needs to make about ITSELF — an accepted-but-unexpected
 *  split name, say. Distinct from a failure: the run continues, but silently
 *  continuing would hide why fewer units appeared than expected. */
export type Note = (msg: string) => void;
/** One listed file: where it is, and how big it is.
 *
 *  The SIZE is carried because the panel is otherwise dishonest. Corpus
 *  progress used to be measured against a total that GREW as each file was
 *  opened, so the bar ran to 100% at the end of every file and then fell back
 *  when the next one was added — 100%, 50%, 100%, 66%… Both listing APIs
 *  already return the size, so the denominator can simply be known before the
 *  first byte is read. */
export interface Listed {
    path: string;
    /** Bytes, or 0 when the source did not say. */
    size: number;
}
/** Files under `path` in a Hugging Face dataset repo's main branch, filtered to
 *  an extension. Returns repo-relative paths (e.g. "smolsent/ha_en.jsonl"),
 *  sorted, so a run's unit order is stable across machines. */
export declare function hfTree(dataset: string, path: string, ext: RegExp, label: string, opts: HttpOptions): Promise<Listed[]>;
/** A dataset's Parquet shards on Hugging Face's auto-converted
 *  `refs/convert/parquet` branch, restricted to `config` and to `splits`.
 *
 *  The converted branch is used rather than `main` because a dataset's own
 *  Parquet may be written as ONE giant row-group (SODA's is 1,191,582 rows),
 *  and a column chunk is per-group, so reading any part of it materialises all
 *  of it. The converted branch is uniformly 10,000-row groups.
 *
 *  Paths look like "<config>/<split>/0000.parquet". The BRANCH name is a single
 *  path SEGMENT here, so its "/" is percent-encoded — unlike a dataset id,
 *  whose "/" must not be. */
export declare function hfConvertedParquet(dataset: string, config: string, splits: string[], label: string, opts: HttpOptions, note?: Note): Promise<Listed[]>;
/** File NAMES (not paths) in one directory of a GitHub repo, filtered to an
 *  extension and sorted. Used for corpora served from GitHub raw rather than
 *  Hugging Face — where the HF mirrors are loading-script repos with no data
 *  files, the official GitHub copy is the one carrying the licence notice. */
export declare function githubContents(repo: string, dir: string, ext: RegExp, label: string, opts: HttpOptions): Promise<Listed[]>;
/** Every file in a local directory matching `ext`, sorted. A missing directory
 *  is an empty list, not an error: LOCAL_PATH is an offline convenience and a
 *  stage with no local copy simply reports that and moves on. */
export declare function localFiles(dir: string, ext: RegExp): Listed[];
/** The FIRST file in a local directory matching any of `exts`, in directory
 *  order (deliberately NOT sorted — this mirrors the single-file stages, which
 *  take whichever copy the filesystem hands back first). Null when none match
 *  or the directory is absent. */
export declare function localFind(dir: string, ...exts: RegExp[]): string | null;