import { execFile } from "node:child_process"; import { promisify, stripVTControlCharacters } from "node:util"; import { truncateHead } from "@earendil-works/pi-coding-agent"; const execute = promisify(execFile); // Parse a string, just like `nu -c`: no temporary filename changes import resolution. // `ast` does not execute the source or merge its local declarations into this scope. const ANALYZE = "ast --json --minify $env.PI_NU_HELP_SOURCE | insert commands { scope commands | select decl_id name } | to json -r"; type Span = { start: number; end: number }; export type DiagnosticHelp = { command: string; text: string; truncated: boolean; }; function isRecord(value: unknown): value is Record { return value !== null && typeof value === "object" && !Array.isArray(value); } function isSpan(value: unknown): value is Span { return ( isRecord(value) && typeof value["start"] === "number" && typeof value["end"] === "number" && Number.isSafeInteger(value["start"]) && Number.isSafeInteger(value["end"]) && value["start"] >= 0 && value["start"] < value["end"] ); } function contains(outer: Span, inner: Span): boolean { return outer.start <= inner.start && outer.end >= inner.end; } // Nested blocks are represented by IDs, not their bodies. Do not assign an // error inside an argument expression to its enclosing command instead. function insideExpression( values: unknown[], span: Span, extra: boolean, ): boolean { const pending = [...values]; let visited = 0; while (pending.length) { if (++visited > 4096) return true; const value: unknown = pending.pop(); if (Array.isArray(value)) pending.push(...value); else if (isRecord(value)) { if ( "expr" in value && isSpan(value["span"]) && contains(value["span"], span) && !( extra && value["expr"] === "Garbage" && value["span"].start === span.start && value["span"].end === span.end ) ) return true; pending.push(...Object.values(value)); } } return false; } /** Bounded native-parser analysis; original runtime statements are not replayed. */ export async function diagnosticHelp( binary: string, command: string, cwd: string, signal?: AbortSignal, timeoutMs = 1000, ): Promise { try { if ( signal?.aborted || !Number.isFinite(timeoutMs) || timeoutMs <= 0 || command.length > 16_384 || Buffer.byteLength(command) > 16_384 ) return; const deadline = AbortSignal.timeout(Math.ceil(Math.min(timeoutMs, 1000))); const combined = signal ? AbortSignal.any([signal, deadline]) : deadline; const run = async (source: string, env: NodeJS.ProcessEnv) => ( await execute( binary, ["--no-config-file", "--no-history", "-c", source], { cwd, env, signal: combined, encoding: "utf8", maxBuffer: 128 * 1024, windowsHide: true, }, ) ).stdout; const analysis = await run(ANALYZE, { ...process.env, PI_NU_HELP_SOURCE: command, }); combined.throwIfAborted(); const parsed: unknown = JSON.parse(analysis); if ( !isRecord(parsed) || typeof parsed["block"] !== "string" || typeof parsed["error"] !== "string" || !parsed["error"].trim() ) return; const block: unknown = JSON.parse(parsed["block"]); const error: unknown = JSON.parse(parsed["error"]); if ( !isRecord(block) || !isSpan(block["span"]) || block["span"].end - block["span"].start !== Buffer.byteLength(command) || !isRecord(error) || Object.keys(error).length !== 1 ) return; const extra = "ExtraPositional" in error; const details = extra ? error["ExtraPositional"] : error["UnknownFlag"]; if (!Array.isArray(details) || typeof details[0] !== "string") return; const span = details[extra ? 1 : 2]; if (!isSpan(span) || !contains(block["span"], span)) return; const pipelines = block["pipelines"]; const commands = parsed["commands"]; if ( !Array.isArray(pipelines) || pipelines.length > 1024 || !Array.isArray(commands) || commands.length > 1024 ) return; const targets: string[] = []; for (const pipeline of pipelines) { if ( !isRecord(pipeline) || !Array.isArray(pipeline["elements"]) || pipeline["elements"].length > 1024 ) return; for (const element of pipeline["elements"]) { if (!isRecord(element)) continue; const expression = element["expr"]; if ( !isRecord(expression) || !isSpan(expression["span"]) || !contains(expression["span"], span) ) continue; const expr = expression["expr"]; const call = isRecord(expr) ? expr["Call"] : undefined; if ( !isRecord(call) || !isSpan(call["head"]) || !contains(expression["span"], call["head"]) || span.start < call["head"].end || typeof call["decl_id"] !== "number" || !Array.isArray(call["arguments"]) || insideExpression(call["arguments"], span, extra) ) continue; // Redirection targets are sibling expressions, not call arguments. // Their errors must never use the direct-argument Garbage exception. if (insideExpression([element["redirection"]], span, false)) continue; // IDs refer to this same Nu process. New custom/shadowing declarations // are absent from the permanent catalog; aliases retain their target ID. const declaration: unknown = commands.find( (value) => isRecord(value) && value["decl_id"] === call["decl_id"], ); if ( isRecord(declaration) && typeof declaration["name"] === "string" && (extra || declaration["name"] === details[0]) ) targets.push(declaration["name"]); } } if (targets.length !== 1) return; const target = targets[0]; if (!target) return; combined.throwIfAborted(); const help = await run("help $env.PI_NU_HELP_TARGET", { ...process.env, PI_NU_HELP_TARGET: target, }); const truncated = truncateHead(stripVTControlCharacters(help), { maxBytes: 8192, maxLines: 200, }); if (combined.aborted || !truncated.content.trim()) return; return { command: target, text: truncated.content, truncated: truncated.truncated, }; } catch { // Parser/version/lookup failures must not replace the original command result. return; } }