Files
reverse-engineering-anything/src/resources/StableArtifactFailure.ts
T
Matt Van Hornandgensokyo-dev a88c0a5554 feat(artifacts): inspect Android boot image components
Inventory Android boot and vendor_boot images through shared artifact workflows. Preserve parser failure kinds and bounded stored-component extraction.

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

207 lines
7.1 KiB
TypeScript

import type { StableArtifactSnapshot } from "./readStableArtifact.js";
import type {
AnalysisError,
AnalysisErrorOptions,
} from "../domain/analysisErrorBase.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { ArtifactReaderFailure } from "./ArtifactReader.js";
import {
artifactFileCancellationCause,
bindArtifactFileCleanup,
type ArtifactFilePrimaryFacts,
} from "./ArtifactFileOperation.js";
import { completedStableArtifactObservation } from "./StableArtifactObservation.js";
import { isSelectedRegularFileError } from "../filesystem/RegularFile.js";
import {
AnalysisAccessDeniedError,
AnalysisArtifactChangedError,
AnalysisInputError,
AnalysisUnsupportedTargetError,
cancelledBy,
carriedReason,
} from "../domain/analysisErrorCore.js";
/**
* A reader's integrity failure as a selected-artifact change, keeping the
* check it named. `options` replaces the default cause (the failure itself),
* for example with a cleanup wrapper around it.
*/
export const readerIntegrityFailure = (
operation: string,
path: string,
failure: ArtifactReaderFailure,
options: AnalysisErrorOptions = {},
): AnalysisArtifactChangedError =>
new AnalysisArtifactChangedError(operation, path, failure.message, {
cause: failure,
...options,
integrityCheck: failure.integrityCheck,
});
/** Preserve ownership classification for stable-file identity and cancellation. */
export const projectOwnedArtifactIdentityFailure = (
facts: ArtifactFilePrimaryFacts,
operation: string,
path: string,
): AnalysisError | undefined => {
const { cause, origin } = facts;
if (
origin !== "owned-or-classified" ||
!(cause instanceof ArtifactReaderFailure)
)
return undefined;
if (cause.reason === "integrity")
return readerIntegrityFailure(operation, path, cause);
if (cause.reason === "cancelled")
return cancelledBy(
operation,
carriedReason(artifactFileCancellationCause(cause)),
);
return undefined;
};
/** The request field that selected a file: a name, or a path into the request. */
export type RequestField = string | readonly (string | number)[];
/** Keep a selected parser refusal's established path and structured input projection. */
export const projectOwnedArtifactInputFailure = (
{ cause, origin }: ArtifactFilePrimaryFacts,
operation: string,
path: string,
field: RequestField = "path",
): AnalysisError | undefined => {
if (
origin !== "owned-or-classified" ||
!(cause instanceof ArtifactReaderFailure)
)
return undefined;
if (cause.reason === "unsupported")
return new AnalysisUnsupportedTargetError(operation, path, cause.message, {
cause,
});
if (
cause.reason === "malformed" ||
cause.reason === "truncated" ||
cause.reason === "format" ||
cause.reason === "path"
)
return stableArtifactInputFailure(cause, operation, field);
return undefined;
};
const requestFieldPath = (field: RequestField): (string | number)[] =>
typeof field === "string" ? [field] : [...field];
/** Project filesystem errors that identify a refused or unreadable selected file. */
export const projectSelectedArtifactFileFailure = (
cause: unknown,
operation: string,
path: string,
description: string,
field: RequestField = "path",
options: AnalysisErrorOptions = {},
): AnalysisError | undefined => {
if (!(cause instanceof Error) || !("code" in cause)) return undefined;
if (cause.code === "EACCES" || cause.code === "EPERM")
return new AnalysisAccessDeniedError(operation, path, cause.code, {
...options,
cause,
});
if (isSelectedRegularFileError(cause))
return new AnalysisInputError(operation, { ...options, cause }, [
{
path: requestFieldPath(field),
reason: "invalid_value",
message: `Selected ${description} could not be read (${String(cause.code)}): ${path}.`,
},
]);
return undefined;
};
/** Explain the selected image read budget and its fixed upper bound. */
export const imageFileSizeRemediation = (
selectedBytes: number,
maximumBytes: number,
): string =>
selectedBytes >= maximumBytes
? `The image exceeds the ${String(maximumBytes)}-byte input ceiling this operation accepts. This release has no runtime override. Select a smaller artifact.`
: `Raise max_file_bytes above ${String(selectedBytes)} bytes or select a smaller artifact; the limit is the caller-selected input read budget.`;
/** Name an observed regular-file retry that admission will validate again. */
export const regularFileSymlinkRecovery = (resolvedPath: string): string =>
`Retry with the resolved regular file path ${resolvedPath}. The selected symlink is not admitted; the retry will validate the target again.`;
/** Offer the verified regular-file target after a selected symlink is rejected. */
export const stableArtifactInputRecovery = (cause: ArtifactReaderFailure) =>
cause.reason === "path" && cause.resolvedPath !== undefined
? {
remediationAction: regularFileSymlinkRecovery(cause.resolvedPath),
conformsToInputContract: true,
}
: {};
/** Report a rejected artifact path or format with its source-provided recovery. */
export const stableArtifactInputFailure = (
cause: ArtifactReaderFailure,
operation: string,
field: RequestField = "path",
options: AnalysisErrorOptions = {},
): AnalysisInputError =>
new AnalysisInputError(
operation,
{ ...options, cause, ...stableArtifactInputRecovery(cause) },
[
{
path: requestFieldPath(field),
reason: "invalid_format",
message: cause.message,
},
],
);
const artifactCleanupFailure = (
cause: unknown,
providerId: string,
operation: string,
): ProviderCleanupError | undefined => {
if (!(cause instanceof ArtifactReaderFailure) || cause.cleanup === undefined)
return undefined;
return new ProviderCleanupError(
providerId,
cause.cleanup.resources,
{ reason: cause.cleanup.reason },
{ cause, operation },
);
};
/** Project descriptor cleanup while keeping its exact leases bound to the error. */
export const projectArtifactCloseFailure = (
cause: unknown,
providerId: string,
operation: string,
): unknown => {
const error = artifactCleanupFailure(cause, providerId, operation);
if (error === undefined) return cause;
bindArtifactFileCleanup(cause, error);
return error;
};
/** Preserve completed physical identity and exact cleanup ownership around a provider's primary failure. */
export const projectStableArtifactFailure = (
cause: unknown,
primary: AnalysisError,
path: string,
providerId: string,
operation: string,
snapshot?: StableArtifactSnapshot,
): AnalysisError => {
const observation = completedStableArtifactObservation(cause, path, snapshot);
if (observation !== undefined) primary.retainPartialObservation(observation);
const cleanup = artifactCleanupFailure(cause, providerId, operation);
if (cleanup === undefined) return primary;
const error = analysisErrorWithCleanupFailure(primary, cleanup, operation);
bindArtifactFileCleanup(cause, error);
return error;
};