Files
reverse-engineering-anything/src/native/NativeCommandAnalysisError.ts
T
morluto d4a7c17b38 feat(errors): project fixed native and producer input allowances as typed refusals (#11623)
* feat(errors): project fixed native and producer input allowances as typed refusals

fixedNativeAllowance wrote its allowance and value only into the remediation
sentence, and fixedProducerInputAllowance put the byte count into the
allowance name. Both now build fixedAllowanceOptions with limit and unit, so
the native command output capture, PE resource metadata, Ghidra
installation-properties and artifact analysis input refusals project
details.refusal {kind: fixed_ceiling, allowance_kind, limit, unit}. The
fixed-ceiling remediation renders the value from those facts for every
ceiling that carries them.

Refs #10508

* test(errors): check the rendered allowance value, not its sentence
2026-11-16 08:39:18 +08:00

242 lines
8.6 KiB
TypeScript

import type { ArtifactResourceScope } from "../resources/index.js";
import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";
import {
ProcessOwnershipInspectionCancelled,
ProcessOwnershipIdentityBatchFailure,
} from "../process/ProcessInspectionCancellation.js";
import {
retainProcessInspectionCleanup,
processInspectionCancellationError,
} from "../providers/OwnedCommandCleanup.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import {
AnalysisCapabilityUnavailableError,
AnalysisResourceConstraintError,
AnalysisTimeoutError,
type AnalysisTimeoutRecovery,
cancelledBy,
carriedReason,
} from "../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { NATIVE_MACOS_PROVIDER_IDENTITY as IDENTITY } from "./NativeMacosProviderIdentity.js";
import {
DEFAULT_NATIVE_COMMAND_TIMEOUT_MS,
fixedNativeAllowance,
nativeDeadlineRecovery,
} from "../domain/native/nativeDeadlines.js";
import {
NATIVE_FAILURE_DIAGNOSTIC_BYTES,
type NativeCommandFailure,
} from "../providers/NativeCommandRunner.js";
import { NATIVE_COMMAND_OUTPUT_BUDGET_BYTES } from "../domain/native/nativeCommandOutput.js";
/** Operation-owned text for a command deadline or unavailable requirement. */
export interface NativeCommandFailurePresentation {
readonly unavailableMessage?: string;
readonly timeoutRecovery?: AnalysisTimeoutRecovery;
}
/** Translate the command owner's facts once, preserving capture and cleanup authority. */
export const translateNativeCommandFailure = (
operation: string,
failure: NativeCommandFailure,
resources: ArtifactResourceScope,
timeoutMs = DEFAULT_NATIVE_COMMAND_TIMEOUT_MS,
presentation: NativeCommandFailurePresentation = {},
): AnalysisError => {
const cleanupOwners = [
...failure.cleanupFailures,
...(failure.cleanupOwner === undefined
? []
: [
{
owner: failure.cleanupOwner,
marker: failure.cleanupMarker,
reason:
failure.cleanupFailure ??
"native command cleanup remains incomplete",
resources: failure.cleanupResources,
},
]),
];
const markers = cleanupOwners.flatMap(({ marker }) =>
marker === undefined ? [] : [marker],
);
const bindCleanup = (error: AnalysisError): AnalysisError =>
cleanupOwners.length === 0 ||
cleanupOwners.some(({ marker }) => marker === undefined)
? error
: error.bindCleanupDependencies([...new Set(markers)]);
const preparation = failure.preparationFailure;
if (preparation !== undefined) {
const darwin =
preparation instanceof DarwinProcessOwnershipInspectionError
? preparation
: undefined;
const compiler = darwin?.compilerOutcome;
const options = {
cause: failure,
...(darwin?.capturedOutput === undefined
? {}
: { capturedOutput: darwin?.capturedOutput }),
diagnostics: {
phase: "process-preparation",
tool: failure.tool,
reason: failure.reason,
detail: preparation.message,
...(compiler === undefined
? {}
: {
compiler_outcome: {
outcome: compiler.outcome,
code: compiler.code,
signal: compiler.signal,
...(compiler.timeoutMs === undefined
? {}
: { timeout_ms: compiler.timeoutMs }),
},
}),
},
};
const cancelled = processInspectionCancellationError(
preparation,
operation,
);
const cancellationPrimary =
preparation instanceof ProcessOwnershipInspectionCancelled ||
(preparation instanceof ProcessOwnershipIdentityBatchFailure &&
preparation.origin === "cancelled") ||
(darwin !== undefined && failure.reason === "cancelled");
const error =
failure.reason === "timeout"
? new AnalysisTimeoutError(operation, timeoutMs, {
...options,
...(presentation.timeoutRecovery ??
nativeDeadlineRecovery({
timeoutMs,
parameter: "native_command_timeout_ms",
defaultMs: DEFAULT_NATIVE_COMMAND_TIMEOUT_MS,
phase: "macOS native command deadline",
unchanged: `The ${String(NATIVE_COMMAND_OUTPUT_BUDGET_BYTES)}-byte command output allowance and the ${String(NATIVE_FAILURE_DIAGNOSTIC_BYTES)}-byte failure-diagnostic excerpt have no runtime override.`,
})),
})
: cancellationPrimary && cancelled !== undefined
? cancelled
: // The ownership helper's compiler deadline is a retryable timeout
// with its own setting, not a provider failure.
darwin?.compileTimeout !== undefined
? new AnalysisTimeoutError(
operation,
darwin.compileTimeout.timeoutMs,
{
...options,
userMessage: darwin.compileTimeout.userMessage,
remediationAction: darwin.compileTimeout.remediationAction,
limit: darwin.compileTimeout.limit,
},
)
: new ProviderAdapterError(IDENTITY.id, operation, options);
return retainProcessInspectionCleanup(
preparation,
bindCleanup(error),
resources,
operation,
);
}
const capturedOutput =
failure.capture === null
? undefined
: {
stdout: failure.capture.stdout,
stderr: failure.capture.stderr,
truncated: failure.capture.truncated,
stdout_bytes: failure.capture.stdoutBytes,
stderr_bytes: failure.capture.stderrBytes,
exit_code: failure.capture.exitCode,
signal: failure.capture.signal,
};
const cleanup =
failure.cleanupFailure === null
? undefined
: {
reason: failure.cleanupFailure,
resources: [...failure.cleanupResources],
};
const errorOptionsWithoutCause = {
...(capturedOutput === undefined ? {} : { capturedOutput }),
...(cleanup === undefined ? {} : { cleanup }),
};
const errorOptions = { cause: failure, ...errorOptionsWithoutCause };
if (failure.reason === "unavailable") {
const reason =
presentation.unavailableMessage ??
`${failure.tool} is unavailable through xcrun.`;
return bindCleanup(
new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, reason, {
...errorOptions,
userMessage: reason,
}),
);
}
if (failure.reason === "cancelled")
return bindCleanup(
cancelledBy(
operation,
carriedReason(
failure.cancellation === undefined
? failure
: failure.cancellation.reason,
),
{
...errorOptionsWithoutCause,
},
),
);
if (failure.reason === "timeout")
return bindCleanup(
new AnalysisTimeoutError(operation, timeoutMs, {
...errorOptions,
...(presentation.timeoutRecovery ??
nativeDeadlineRecovery({
timeoutMs,
parameter: "native_command_timeout_ms",
defaultMs: DEFAULT_NATIVE_COMMAND_TIMEOUT_MS,
phase: "macOS native command deadline",
unchanged: `The ${String(NATIVE_COMMAND_OUTPUT_BUDGET_BYTES)}-byte command output allowance and the ${String(NATIVE_FAILURE_DIAGNOSTIC_BYTES)}-byte failure-diagnostic excerpt have no runtime override.`,
})),
}),
);
if (failure.reason === "output-limit")
return bindCleanup(
new AnalysisResourceConstraintError(
operation,
"memory",
`Native command output exceeded ${String(NATIVE_COMMAND_OUTPUT_BUDGET_BYTES)} bytes. Complete output is required for analysis. This release has no runtime override. native_command_timeout_ms does not raise this allowance.`,
{ max_output_bytes: NATIVE_COMMAND_OUTPUT_BUDGET_BYTES },
{
...errorOptions,
...fixedNativeAllowance(
"The native command output capture allowance",
"capture",
NATIVE_COMMAND_OUTPUT_BUDGET_BYTES,
"bytes",
),
},
),
);
return bindCleanup(
new ProviderAdapterError(IDENTITY.id, operation, {
...errorOptions,
diagnostics: {
tool: failure.tool,
reason: failure.reason,
exit_code: failure.capture?.exitCode ?? failure.exitCode,
signal: failure.capture?.signal ?? null,
stdout_bytes: failure.capture?.stdoutBytes ?? 0,
stderr_bytes: failure.capture?.stderrBytes ?? 0,
...(failure.detail === null ? {} : { detail: failure.detail }),
},
}),
);
};