unbash-walker API Reference

// All unbash-walker exports are re-exported from pi-steering:
import {
  parse,
  extractAllCommandsFromAST,
  expandWrapperCommands,
  walk,
  cwdTracker,
  envTracker,
  resolveWord,
  getBasename,
  getCommandArgs,
  getCommandName,
  formatCommand,
} from "pi-steering";

import {
  parse,
  extractAllCommandsFromAST,
  expandWrapperCommands,
  walk,
  cwdTracker,
  getBasename,
  getCommandArgs,
} from "pi-steering";

const raw = "cd /home/me/repo && sudo sh -c 'git push --force'";
const script = parse(raw);

const refs = extractAllCommandsFromAST(script, raw);
const { commands } = expandWrapperCommands(refs);
const state = walk(script, { cwd: "/tmp" }, { cwd: cwdTracker }, commands);

for (const cmd of commands) {
  const name = getBasename(cmd);
  const args = getCommandArgs(cmd);
  const cwd = state.get(cmd)?.cwd ?? "/tmp";
  console.log(`${cwd} :: ${name} ${args.join(" ")}`);
}

import { parse } from "pi-steering";

const script = parse("git commit -m 'fix: typo'");

function extractAllCommandsFromAST(
  script: Script,
  source: string,
): CommandRef[]

function expandWrapperCommands(
  commands: CommandRef[],
): ExpansionResult

// ExpansionResult shape:
type ExpansionResult = {
  commands: CommandRef[];
  expandedWrappers: Set<CommandRef>;
}

import { WRAPPER_COMMANDS } from "pi-steering";

// Inspect the registry
console.log(Object.keys(WRAPPER_COMMANDS));

function walk<T extends Record<string, unknown>>(
  script: Script,
  initialState: Partial<T>,
  trackers: { readonly [K in keyof T]: Tracker<T[K]> },
  refs?: readonly CommandRef[],
): WalkResult<T>

import { cwdTracker } from "pi-steering";

const state = walk(script, { cwd: process.cwd() }, {
  env: envTracker,
  cwd: cwdTracker,
}, refs);

import { envTracker } from "pi-steering";

const state = walk(script, {}, { env: envTracker }, refs);
const envAtCmd = state.get(cmd)?.env; // ReadonlyMap<string, string>

function resolveWord(word: Word, env: EnvState): string | undefined

import { resolveWord } from "pi-steering";
import type { EnvState } from "pi-steering";

const env: EnvState = new Map([["HOME", "/home/me"], ["WS", "/home/me/work"]]);

// Resolves fully
resolveWord(wordNode, env); // "/home/me/work/pkg" if word is "$WS/pkg"

// Returns undefined — command substitution is intractable
resolveWord(cmdSubstWord, env); // undefined

import { formatCommand } from "pi-steering";

const display = formatCommand(cmd, { maxLength: 80 });

type CommandRef = {
  /** The unbash AST Command node. */
  node: Command;

  /** Original bash source string — position offsets in node refer to this. */
  source: string;

  /**
   * Group ID. Commands in the same && / || / | chain share a group.
   * Different groups are separated by semicolons or blank lines.
   */
  group: number;

  /**
   * The operator connecting this command to the next.
   * Undefined for the last command in a group.
   */
  joiner?: "|" | "&&" | "||" | ";";
};

interface Tracker<T> {
  /**
   * Starting value for this dimension.
   * walk() callers override this via initialState[name].
   */
  initial: T;

  /**
   * Sentinel emitted when a modifier returns undefined (unresolvable state).
   * For string trackers this is typically the string "unknown".
   */
  unknown: T;

  /**
   * Modifiers keyed by command basename.
   * An array value applies multiple modifiers left-to-right on the same ref.
   */
  modifiers: Record<string, Modifier<T> | Modifier<T>[]>;

  /**
   * How subshell boundaries affect this dimension.
   * Defaults to "isolated".
   */
  subshellSemantics?: "isolated" | "global";
}

type Modifier<T, TAll extends Record<string, unknown> = Record<string, unknown>> =
  | {
      /** Updates the threaded value — propagates to all subsequent sibling commands. */
      scope: "sequential";
      apply(args: readonly Word[], current: T, allState: Readonly<TAll>): T | undefined;
    }
  | {
      /** Updates only the snapshot for this command — threaded value unchanged. */
      scope: "per-command";
      apply(args: readonly Word[], current: T, allState: Readonly<TAll>): T | undefined;
    };

import type { Modifier, EnvState } from "pi-steering";

const myModifier: Modifier<string, { env: EnvState }> = {
  scope: "sequential",
  apply(args: readonly Word[], current: string, allState: Readonly<{ env: EnvState }>) {
    const expanded = allState.env.get("MY_VAR");
    if (!expanded) return undefined; // unresolvable — emit "unknown"
    return expanded;
  },
};