/**
 * One element of a resolved command chain, carrying how it was composed rather than how its text reads.
 * A `structural` step is nmr's own composition, held as argv; an `opaque` step is a command nmr does not parse.
 *
 * A structural step's argv leads with the file to spawn, so the runner has one to hand `spawn` without a shell.
 *
 * `shouldDeclineArguments` travels from the composite element that composed the step to the one reader that acts on it,
 * the binding of the invocation's trailing arguments. Every stage between the two -- the devBin substitution,
 * the chain rendering, the replay assembly, the runner -- passes it through and asks nothing of it.
 *
 * `shouldWithholdInput` is read by the runner alone, which gives the step's child the null device as stdin rather
 * than nmr's own. Like `shouldDeclineArguments`, it is set only where it holds and leaves the rendered chain unchanged.
 */
export type Step = {
    kind: 'opaque';
    command: string;
} | {
    kind: 'structural';
    argv: readonly [string, ...(readonly string[])];
    shouldDeclineArguments?: boolean;
    shouldWithholdInput?: boolean;
};
/** What a structural step asks of the nmr process it spawns. */
export interface NmrStepTarget {
    command: string;
    /** Whether the command is fanned out to other scopes, where a `-R` or `-F` sends it. */
    isDelegate: boolean;
    /** Whether the command runs against the root registry, where a `-w` anchors it. */
    isWorkspaceRoot: boolean;
}
/**
 * How a `package.json` entry names the command it is declared under: as its whole value, or alongside other
 * steps. `sole` covers an entry carrying trailing arguments, which declare no step of their own.
 */
export type SelfReference = 'chained' | 'sole';
/**
 * Composes the structural step that re-invokes nmr for one composite element.
 *
 * The element tokenizes on whitespace, so it may carry nmr's own flags but cannot carry a space-bearing token.
 * `-w` is prepended as its own token, so the child selects the root registry on its own.
 *
 * `shouldDeclineArguments` is set only where it holds, so a step that takes the trailing arguments renders and compares
 * exactly as it did before any element declared anything.
 */
export declare function composeNmrStep(element: string, workspaceRoot: boolean, shouldDeclineArguments?: boolean): Step;
/**
 * Returns the text of the first opaque step that reaches nmr through a shell, or `undefined` when none does.
 *
 * Recognizes nmr in command position: at the start of the step, after `&&`, `||`, `;`, `|`, or a newline, past
 * any leading environment assignments, and behind a launcher such as `npx` or `pnpm exec`. A separator inside
 * quotes opens no position, so a command merely naming nmr in an argument is not a crossing.
 *
 * Partial by construction, and partial in stated ways rather than arbitrary ones: a value-taking flag standing
 * immediately before the program name hides it (`npx -p foo nmr`), and a launcher outside `LAUNCHERS` goes
 * unreported. What it finds is the boundary below which nmr cannot tell its own processes from the tools it
 * runs.
 */
export declare function findNmrCrossing(steps: readonly Step[]): string | undefined;
/**
 * Returns the first token of a composite element that falls outside the grammar, or `undefined` when the
 * element is a command name optionally preceded by nmr's own flags. A token the shell would not read
 * literally is one the rendering would quote whole, turning the element into a command nobody wrote.
 */
export declare function findUnexpressibleToken(element: string): string | undefined;
/**
 * Returns the command a structural step's nmr process runs, whether the step hands that command to other
 * scopes rather than running it where it stands, and whether it anchors the command at the monorepo root.
 * Reports nothing for a step that names no nmr command.
 *
 * The inverse of `composeNmrStep`, and beside it because the two share one grammar: an element may lead with
 * nmr's own flags, and the command is the first token that is not one.
 */
export declare function readNmrStep(step: Step): NmrStepTarget | undefined;
/**
 * Reports whether a `package.json` entry re-invokes the command it is declared under, and whether it declares
 * anything besides. Reports nothing for an entry that names another command, or none.
 *
 * Honouring such an entry would spawn a shell running the same command in the same directory, reaching the
 * same entry again without bound, so resolution discards it however it reads. `chained` is what separates an
 * entry that thereby loses steps from one that declares nothing to lose.
 *
 * A segment that delegates carries the command to other scopes rather than back to this one. `-w` re-enters
 * only from the root, a package's entry reaching the root's registry and `package.json` instead of its own.
 *
 * Partial in the same ways `findNmrCrossing` is, and for the same reason: what goes unrecognized re-enters
 * without bound, which hangs rather than passing quietly.
 */
export declare function readSelfReference(options: {
    anchoredAtRoot: boolean;
    commandName: string;
    script: string;
}): SelfReference | undefined;
/**
 * Renders a step list as the `&&` chain a shell runs.
 *
 * The sole producer of a chain string: the check-result cache keys on that string, so a change to the rendering
 * invalidates every recorded pass by construction rather than by anyone remembering to.
 */
export declare function renderChain(steps: readonly Step[]): string;