Files
reverse-engineering-anything/src/process/classifyProviderOutcome.ts
T
morluto 1f7884b5b9 refactor(process): classify owned command outcomes through one owner (#10628)
* fix(pcap): report a refused tool launch as an unavailable tool

When a capture read's tool launch was refused with EPERM, pcap reported it
as unreadable tool output (AnalysisProtocolError) instead of an unavailable
tool. Pcap also never told "not executable" apart from "missing".

Add classifyLaunchFailure in src/process as the one owner of which spawn
errnos mean missing (ENOENT, ENOTDIR) and which mean present but not
executable (EACCES, EPERM, ENOEXEC, EISDIR). Pcap, apktool and gdb used three
different errno lists; all three now use it.

* refactor(process): classify owned command outcomes through one owner

Add ProviderOutcome, read once from the supervisor's facts, and classifyProviderOutcome, the one mapping from an outcome to a typed error. Migrate pcap and the shared artifact producer command failure (TShark, sigrok). Add the rea/provider-failure-classifier lint rule with a shrink-only baseline of per-site (cause: unknown) => AnalysisError functions.

* refactor(process): classify Java and adb launch refusals with the shared owner (#10598)

The Ghidra and JADX Java probes and adb's version probe now take
missing-versus-not-executable from classifyLaunchFailure instead of their
own errno checks. ELOOP and ENAMETOOLONG join the owner's missing set, so
adb keeps its existing classification and both Java probes now treat a
non-directory path component as a missing runtime.

* fix(pcap): preserve command launch attribution

* test(pcap): expect an unknown failing stage when a limited capture tool exits unsuccessfully

* refactor(process): classify owned command outcomes through one owner

Add ProviderOutcome, read once from the supervisor's facts, and classifyProviderOutcome, the one mapping from an outcome to a typed error. Migrate pcap and the shared artifact producer command failure (TShark, sigrok). Add the rea/provider-failure-classifier lint rule with a shrink-only baseline of per-site (cause: unknown) => AnalysisError functions.

* test(lint): cover baselined files in the provider-failure classifier rule

* fix(pcap): attribute a limited capture's exit through the prlimit wrapper

* fix(process): identify the refused executable for every launcher shape

Name the executable on errnos Node throws synchronously from spawn
(ENOEXEC, ENOTDIR, ...) and read the Windows native launcher's
executable-launch constraint, so pcap attributes those refusals to the
selected tool or limiter instead of an unknown stage.

* test(pcap): prove synchronous launch naming with ENOTDIR on every POSIX host

* refactor(process): build classified cancellations with cancelledBy and the carried caller reason

* chore(lint): count runOwned's close-failure mapper from main in the classifier baseline
2026-11-15 13:45:46 +08:00

129 lines
4.5 KiB
TypeScript

import type {
AnalysisCapturedOutput,
AnalysisError,
AnalysisErrorOptions,
} from "../domain/analysisErrorBase.js";
import {
AnalysisResourceConstraintError,
AnalysisTimeoutError,
cancelledBy,
carriedReason,
type ResourceConstraintRecovery,
} from "../domain/analysisErrorCore.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { ProviderOutcome } from "./ProviderOutcome.js";
import type { ProviderProcessSnapshot } from "./ProviderProcess.js";
/** Outcomes whose meaning depends on the provider's own dialect. */
export type ProviderDialectOutcome = Extract<
ProviderOutcome,
{ readonly kind: "launch-refused" | "exited" | "protocol" }
>;
type ReportedLimits = Readonly<Record<string, JsonValue>> | null;
/** What one provider command needs to turn its outcome into a typed error. */
export interface ProviderOutcomeContext {
readonly operation: string;
/** The provider's redacted projection of retained output. */
readonly capturedOutput: (
snapshot: ProviderProcessSnapshot,
) => AnalysisCapturedOutput;
/** Options every classified error carries, such as retained cleanup. */
readonly details?: AnalysisErrorOptions;
readonly timeout: {
readonly ms: number;
/** Which deadline elapsed, when the generic timeout text is not enough. */
readonly userMessage?: string;
/** The setting or action that changes that deadline. */
readonly remediationAction?: string;
};
readonly outputLimit: {
readonly limits: ReportedLimits;
readonly recovery: ResourceConstraintRecovery;
};
/** The enforced process-tree memory limit, when one was requested. */
readonly memoryLimitBytes?: number | undefined;
/** Reported limits and recovery for an inherited CPU or file-size signal. */
readonly resourceSignal?: (signal: "SIGXCPU" | "SIGXFSZ") => {
readonly limits: ReportedLimits;
readonly recovery: ResourceConstraintRecovery;
};
/** Provider-specific meaning of a launch refusal, an exit, or a stream failure. */
readonly dialect: (
outcome: ProviderDialectOutcome,
details: AnalysisErrorOptions,
) => AnalysisError;
}
/**
* The one mapping from an owned command's physical outcome to a typed error.
* Owner-observed facts are classified here; only the provider's dialect
* decides what an exit or a launch refusal means for that provider.
*/
export const classifyProviderOutcome = (
outcome: ProviderOutcome,
context: ProviderOutcomeContext,
): AnalysisError => {
const { operation } = context;
const details: AnalysisErrorOptions = {
...context.details,
cause: outcome.cause,
...(outcome.output === undefined
? {}
: { capturedOutput: context.capturedOutput(outcome.output.snapshot) }),
};
switch (outcome.kind) {
case "cancelled": {
// The caller's abort reason is the cancellation's cause; the outcome's
// own cause is the supervisor failure that observed it.
const { cause: _observed, ...cancellationDetails } = details;
return cancelledBy(
operation,
carriedReason(outcome.reason),
cancellationDetails,
);
}
case "timeout":
return new AnalysisTimeoutError(operation, context.timeout.ms, {
...details,
...(context.timeout.userMessage === undefined
? {}
: { userMessage: context.timeout.userMessage }),
...(context.timeout.remediationAction === undefined
? {}
: { remediationAction: context.timeout.remediationAction }),
});
case "output-limit":
return new AnalysisResourceConstraintError(
operation,
"memory",
outcome.message,
context.outputLimit.limits,
{ ...details, ...context.outputLimit.recovery },
);
case "memory-limit":
return new AnalysisResourceConstraintError(
operation,
"memory",
"The owned process tree reached its enforced committed-memory limit.",
{ process_memory_limit_bytes: context.memoryLimitBytes ?? null },
details,
);
case "resource-signal": {
const reported = context.resourceSignal?.(outcome.signal);
return new AnalysisResourceConstraintError(
operation,
outcome.signal === "SIGXFSZ" ? "file-size" : "cpu",
`Producer terminated with ${outcome.signal}; the signal's exact cause is not independently established.`,
reported?.limits ?? null,
{ ...details, ...reported?.recovery },
);
}
case "launch-refused":
case "exited":
case "protocol":
return context.dialect(outcome, details);
}
};