Files
reverse-engineering-anything/src/cli/help.ts
T
Matt Van Hornandgensokyo-dev e9c72dbd1f feat(elf): inspect dynamic dependencies and required symbol versions
Add offline ELF dependency, search-path, symbol-version and import inspection with retained Evidence summaries and pages. Bound GNU-hash work and preserve cancellation, stable identity and caller-selected parameters across CLI/MCP.

Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning)
Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2026-11-17 08:19:52 +00:00

230 lines
8.6 KiB
TypeScript

import { z } from "zod";
import { declaredOptionType, optionFlagName } from "./optionFields.js";
/**
* REA's help text. The layout is the one the CLI has always printed: a
* `name — description` title, a usage line, aligned argument and option rows
* with type placeholders and shown defaults, an optional hint, then the global
* options the entry accepts.
*/
/** A named entry in a command list. */
export interface HelpCommandRow {
readonly name: string;
readonly description?: string | undefined;
}
/** The global options block of an entry that accepts them. */
export interface GlobalOptionsHelp {
/** The `--format` values this entry accepts, in display order. */
readonly formats: readonly string[];
/** Global options REA defines beyond the standard ones, such as `--timings`. */
readonly custom?: z.ZodObject | undefined;
/**
* The root page also lists the integration commands and the flags that
* apply only before a command (`--mcp`, `--update`, `--version`).
*/
readonly root?:
| { readonly integrations: readonly HelpCommandRow[] }
| undefined;
}
export interface CommandHelp {
readonly description?: string | undefined;
/** Printed as `name@version` in the title. */
readonly version?: string | undefined;
/** Positionals, in argv order. */
readonly args?: z.ZodObject | undefined;
readonly options?: z.ZodObject | undefined;
/** Short alias by option key, such as `{ help: "h" }`. */
readonly alias?: Readonly<Record<string, string>> | undefined;
/** A paragraph printed after the options. */
readonly hint?: string | undefined;
/** Omitted for an entry that accepts only its own options. */
readonly globalOptions?: GlobalOptionsHelp | undefined;
}
interface Row {
readonly label: string;
readonly description: string;
}
/** Two-column rows with the descriptions aligned after the longest label. */
const alignedRows = (rows: readonly Row[]): string[] => {
const width = Math.max(...rows.map((row) => row.label.length));
return rows.map(
(row) =>
` ${row.label}${" ".repeat(width - row.label.length)} ${row.description}`,
);
};
/** The placeholder shown after a value-taking flag. */
const typeName = (field: z.ZodType): string => {
const type = declaredOptionType(field);
if (type instanceof z.ZodString) return "string";
if (type instanceof z.ZodNumber) return "number";
if (type instanceof z.ZodBoolean) return "boolean";
if (type instanceof z.ZodArray) return "array";
if (type instanceof z.ZodEnum)
return type.options.map((value) => String(value)).join("|");
if (
type instanceof z.ZodUnion &&
type.options.every((option) => option instanceof z.ZodLiteral)
)
return type.options.map((option) => String(option.value)).join("|");
return "value";
};
/** A shown default; empty arrays and a `false` boolean default are not shown. */
const shownDefault = (field: z.ZodType, type: string): unknown => {
const metadata = field.meta();
const value =
metadata !== undefined && Object.hasOwn(metadata, "default")
? metadata.default
: field instanceof z.ZodDefault
? (field.def.defaultValue as unknown)
: field instanceof z.ZodOptional
? shownDefault(field.unwrap() as z.ZodType, type)
: undefined;
if (Array.isArray(value) && value.length === 0) return undefined;
if (type === "boolean" && value === false) return undefined;
return value;
};
const fieldDescription = (field: z.ZodType, type = typeName(field)): string => {
const defaultValue = shownDefault(field, type);
const description = field.description ?? "";
return defaultValue === undefined
? description
: `${description} (default: ${String(defaultValue)})`;
};
const optionRows = (
options: z.ZodObject,
alias: Readonly<Record<string, string>> | undefined,
): Row[] =>
Object.entries(options.shape as Readonly<Record<string, z.ZodType>>).map(
([key, field]) => {
const type = typeName(field);
const short = alias?.[key];
const value = type === "boolean" ? "" : ` <${type}>`;
const label = `--${optionFlagName(key)}${short === undefined ? "" : `, -${short}`}${value}`;
return { label, description: fieldDescription(field, type) };
},
);
/** A command list's rows, in the order given. */
const commandRows = (commands: readonly HelpCommandRow[]): string[] => {
const width = Math.max(...commands.map((command) => command.name.length));
return commands.map((command) =>
command.description === undefined || command.description === ""
? ` ${command.name}`
: ` ${command.name}${" ".repeat(width - command.name.length)} ${command.description}`,
);
};
/** `<required>`, `[optional]` and `<variadic...>` placeholders, in argv order. */
const synopsis = (name: string, args: z.ZodObject | undefined): string =>
[
name,
...Object.entries(
(args?.shape ?? {}) as Readonly<Record<string, z.ZodType>>,
).map(([key, field]) => {
const type = typeName(field);
const label =
(type.includes("|") ? type : key) + (type === "array" ? "..." : "");
return field._zod.optout === "optional" ? `[${label}]` : `<${label}>`;
}),
].join(" ");
/** The global options an entry accepts, sorted by flag. */
const globalOptionRows = ({ formats, root }: GlobalOptionsHelp): Row[] =>
[
{
label: "--filter-output <keys>",
description: "Filter output by key paths (e.g. foo,bar.baz,a[0,3])",
},
{ label: `--format <${formats.join("|")}>`, description: "Output format" },
{ label: "--help", description: "Show help" },
{
label: "--llms, --llms-full",
description: "Print LLM-readable manifest",
},
{ label: "--schema", description: "Show JSON Schema for command" },
{
label: "--token-count",
description: "Print token count of output (instead of output)",
},
{ label: "--token-limit <n>", description: "Limit output to n tokens" },
{
label: "--token-offset <n>",
description: "Skip first n tokens of output",
},
{ label: "--full-output", description: "Show full output envelope" },
...(root === undefined
? []
: [
{ label: "--mcp", description: "Start as MCP stdio server" },
{ label: "--update", description: "Update to latest version" },
{ label: "--version", description: "Show version" },
]),
].sort((left, right) => left.label.localeCompare(right.label));
/** Integrations, custom global options and global options, in that order. */
const globalOptionsLines = (help: GlobalOptionsHelp | undefined): string[] => {
if (help === undefined) return [];
const lines: string[] = [];
if (help.root !== undefined)
lines.push("", "Integrations:", ...commandRows(help.root.integrations));
const custom =
help.custom === undefined ? [] : optionRows(help.custom, undefined);
if (custom.length > 0)
lines.push("", "Custom Global Options:", ...alignedRows(custom));
lines.push("", "Global Options:", ...alignedRows(globalOptionRows(help)));
return lines;
};
const title = (name: string, help: CommandHelp): string => {
const heading = help.version === undefined ? name : `${name}@${help.version}`;
return help.description === undefined
? heading
: `${heading} — ${help.description}`;
};
/** Render one command's help, without a trailing newline. */
export const formatCommandHelp = (name: string, help: CommandHelp): string => {
const lines = [
title(name, help),
"",
`Usage: ${synopsis(name, help.args)}${help.options === undefined ? "" : " [options]"}`,
];
const args = Object.entries(
(help.args?.shape ?? {}) as Readonly<Record<string, z.ZodType>>,
).map(([key, field]) => ({
label: key,
description: fieldDescription(field),
}));
if (args.length > 0) lines.push("", "Arguments:", ...alignedRows(args));
const options =
help.options === undefined ? [] : optionRows(help.options, help.alias);
if (options.length > 0) lines.push("", "Options:", ...alignedRows(options));
if (help.hint !== undefined) lines.push("", help.hint);
lines.push(...globalOptionsLines(help.globalOptions));
return lines.join("\n");
};
/** Render a page that lists commands (the root or a group), without a trailing newline. */
export const formatCommandListHelp = (
name: string,
help: Pick<CommandHelp, "description" | "version" | "globalOptions"> & {
readonly commands: readonly HelpCommandRow[];
},
): string => {
const lines = [title(name, help), "", `Usage: ${name} <command>`];
if (help.commands.length > 0)
lines.push("", "Commands:", ...commandRows(help.commands));
lines.push(...globalOptionsLines(help.globalOptions));
return lines.join("\n");
};