Files
reverse-engineering-anything/src/domain/analysisErrorCleanup.test.ts
T
gensokyo-devandgensokyo-dev 13725d2986 refactor(errors): list distinct resources in providerCleanupErrorFromFailures
Parts of one cleanup composite can share a resource, such as a common
runtime root. Callers deduplicated the list by hand before composing;
normalize it once in the owner so they can use it directly.

Refs #11859

Co-Authored-By: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2026-11-21 19:34:01 +01:00

664 lines
22 KiB
TypeScript

import { unknownTarget } from "./targetIdentity.js";
import { expect, it } from "vitest";
import {
AnalysisCancelledError,
AnalysisCapabilityUnavailableError,
AnalysisInputError,
AnalysisOutputError,
AnalysisResourceConstraintError,
AnalysisTimeoutError,
} from "./analysisErrorCore.js";
import {
analysisErrorWithCleanupFailure,
providerCleanupErrorFromFailures,
withInheritedCleanupOwnership,
} from "./analysisErrorCleanup.js";
import {
projectAnalysisError,
projectAnalysisErrorWithoutCapturedOutput,
} from "./analysisErrorProjection.js";
import {
analysisErrorCategory,
analysisErrorRemediationAction,
analysisErrorUserMessage,
} from "./analysisErrorPresentation.js";
import { ProviderCleanupError } from "./providerCleanupError.js";
import { createEvidence } from "./evidence.js";
import { ArtifactOperationError } from "./artifactOperationError.js";
import { releaseOwnedCleanup } from "../../tests/support/cleanupRelease.js";
it.each([false, true])(
"keeps each owner's capture without text-based deduplication (matching: %s)",
(matching) => {
const primary = new AnalysisTimeoutError("inspect", 1234, {
capturedOutput: {
stdout: "primary-capture-sentinel",
stderr: "",
truncated: false,
},
});
const cleanup = new ProviderCleanupError(
"fixture",
["owned-worker"],
{},
{
capturedOutput: {
stdout: matching
? "primary-capture-sentinel"
: "cleanup-capture-sentinel",
stderr: "",
truncated: true,
},
},
);
const composed = analysisErrorWithCleanupFailure(
primary,
cleanup,
"inspect",
);
const projected = projectAnalysisError(composed);
expect(projected.details?.captured_output).toEqual(primary.capturedOutput);
expect(projected.details?.diagnostics).toMatchObject({
primary_error: {
code: "provider_timeout",
details: { timeout_ms: 1234 },
},
cleanup_error: { details: { captured_output: cleanup.capturedOutput } },
});
expect(
JSON.stringify(projected).split("primary-capture-sentinel"),
).toHaveLength(matching ? 3 : 2);
if (!matching)
expect(
JSON.stringify(projected).split("cleanup-capture-sentinel"),
).toHaveLength(2);
expect(
projectAnalysisErrorWithoutCapturedOutput(primary).details,
).not.toHaveProperty("captured_output");
expect(projectAnalysisError(primary).details?.captured_output).toEqual(
primary.capturedOutput,
);
},
);
it("keeps dependency-owned resources empty after the final owner releases", () => {
const file = new ProviderCleanupError("fixture", ["file-owner"], {});
const trace = new ProviderCleanupError("fixture", ["trace-owner"], {});
const composed = analysisErrorWithCleanupFailure(
file,
trace,
).bindCleanupDependencies([file, trace]);
expect(new Set(composed.cleanupResources)).toEqual(
new Set(["file-owner", "trace-owner"]),
);
releaseOwnedCleanup(file);
expect(composed.cleanupResources).toEqual(["trace-owner"]);
releaseOwnedCleanup(trace);
expect(composed.cleanupIncomplete).toBe(false);
expect(composed.cleanupResources).toEqual([]);
expect(new Set(composed.cleanup?.resources)).toEqual(
new Set(["file-owner", "trace-owner"]),
);
});
it("reads completion through nested compositions from the releasing owner only", () => {
const owner = new ProviderCleanupError("fixture", ["owned-worker"], {});
const inner = new ProviderCleanupError(
"fixture",
["owned-worker"],
{},
).bindCleanupDependencies([owner]);
const outer = new ProviderCleanupError(
"fixture",
["owned-worker"],
{},
).bindCleanupDependencies([inner]);
// Cleanup state is not writable state of an error value.
expect(Reflect.set(outer, "cleanupIncomplete", false)).toBe(false);
expect(outer.cleanupIncomplete).toBe(true);
releaseOwnedCleanup(owner);
expect(outer.cleanupIncomplete).toBe(false);
expect(inner.cleanupIncomplete).toBe(false);
// Completion is monotonic: a later binding cannot reopen it.
outer.bindCleanupDependencies([
new ProviderCleanupError("fixture", ["later"], {}),
]);
expect(outer.cleanupIncomplete).toBe(false);
});
it("keeps completion when a dependency is bound after release without an intermediate read", () => {
const owner = new ProviderCleanupError("fixture", ["owned-worker"], {});
const outer = new ProviderCleanupError(
"fixture",
["owned-worker"],
{},
).bindCleanupDependencies([owner]);
releaseOwnedCleanup(owner);
outer.bindCleanupDependencies([
new ProviderCleanupError("fixture", ["later"], {}),
]);
expect(outer.cleanupIncomplete).toBe(false);
});
it("keeps primary diagnostics separate from historical cleanup diagnostics with the same keys", () => {
const primary = new AnalysisInputError("inspect", {
diagnostics: {
primary_error: "source observation",
cleanup_error: "another source observation",
},
});
const cleanup = new ProviderCleanupError("fixture", ["owned-input"], {});
const composed = analysisErrorWithCleanupFailure(
primary,
cleanup,
).bindCleanupDependencies([primary, cleanup]);
releaseOwnedCleanup(cleanup);
const projected = projectAnalysisError(composed);
expect(projected.details?.diagnostics).toEqual(primary.diagnostics);
expect(projected.details?.cleanup_history).toMatchObject({
primary_error: projectAnalysisError(primary),
cleanup_error: { code: "cleanup_incomplete" },
});
expect(composed.cleanupPrimary).toBe(primary);
expect(Object.hasOwn(composed, "cleanupPrimary")).toBe(false);
});
it.each([
new ArtifactOperationError(
"inspect_asset_catalog",
"integrity",
undefined,
"Asset catalog changed during inspection: Contents/Resources/Assets.car",
),
new AnalysisInputError("inspect", { diagnostics: { input: "original" } }, [
{
path: ["path"],
reason: "out_of_range",
message: "fixed input allowance",
},
]),
new AnalysisCancelledError("inspect", { cause: "caller reason" }),
new AnalysisTimeoutError("inspect", 1234),
new AnalysisResourceConstraintError(
"inspect",
"file-size",
"fixed input allowance",
{ maximum_input_bytes: 123 },
{ retryable: false, remediationAction: "Select a smaller suitable input." },
),
new AnalysisOutputError("inspect", "invalid output", {
capturedOutput: {
stdout: "original output",
stderr: "original warning",
truncated: true,
},
partialObservation: createEvidence(
unknownTarget("not-observed"),
{ id: "fixture", name: "Fixture", version: null },
{
operation: "inspect",
parameters: {},
result: { original_fact: true },
confidence: "observed",
locations: [],
limitations: [],
},
),
}),
])("restores the typed $_tag primary after confirmed cleanup", (primary) => {
const original = projectAnalysisError(primary);
const cleanup = new ProviderCleanupError(
"fixture",
["owned-input"],
{ reason: "close denied" },
{
operation: "inspect",
cleanup: { reason: "close denied", resources: ["owned-input"] },
},
);
const composed = analysisErrorWithCleanupFailure(
primary,
cleanup,
"inspect",
).bindCleanupDependencies([primary, cleanup]);
expect(composed.cleanup?.reason).toBe("close denied");
expect(composed.cleanup?.reason).not.toBe(
projectAnalysisError(cleanup).message,
);
const pending = projectAnalysisError(composed);
expect(pending.code).toBe("cleanup_incomplete");
expect(pending.category).toBe(original.category);
expect(analysisErrorCategory(composed)).toBe(original.category);
const { diagnostics: _diagnostics, ...semanticDetails } =
original.details ?? {};
expect(pending.details).toMatchObject({
...semanticDetails,
cleanup: "incomplete",
execution_failure: original.code,
resources: ["owned-input"],
});
releaseOwnedCleanup(cleanup);
const projected = projectAnalysisError(composed);
expect(projected).toMatchObject(original);
expect(projected.details?.cleanup_history).toMatchObject({
primary_error: { code: original.code, message: original.message },
cleanup_error: { code: "cleanup_incomplete" },
});
expect(projected.details?.cleanup_history).not.toHaveProperty(
"primary_error.details.partial_observation",
);
expect(projected.details?.cleanup_history).not.toHaveProperty(
"primary_error.details.captured_output",
);
expect(projected.details).not.toHaveProperty("cleanup", "incomplete");
expect(projected.details).not.toHaveProperty("resources");
expect(analysisErrorCategory(composed)).toBe(original.category);
expect(analysisErrorUserMessage(composed)).toBe(original.message);
expect(analysisErrorRemediationAction(composed)).toBe(
original.remediation.action,
);
expect(composed.cause).toBeInstanceOf(AggregateError);
expect((composed.cause as AggregateError).errors[0]).toBe(primary);
});
it.each(["inner", "outer"] as const)(
"waits for both nested cleanup owners when %s resolves first",
(first) => {
const primary = new AnalysisInputError("inspect", undefined, [
{ path: ["path"], reason: "missing_argument" },
]);
const innerCleanup = new ProviderCleanupError("fixture", ["input"], {});
const outerCleanup = new ProviderCleanupError("fixture", ["workspace"], {});
const inner = analysisErrorWithCleanupFailure(
primary,
innerCleanup,
).bindCleanupDependencies([primary, innerCleanup]);
const outer = analysisErrorWithCleanupFailure(
inner,
outerCleanup,
).bindCleanupDependencies([inner, outerCleanup]);
const released = first === "inner" ? innerCleanup : outerCleanup;
const pending = first === "inner" ? outerCleanup : innerCleanup;
expect(projectAnalysisError(outer)).toMatchObject({
code: "cleanup_incomplete",
category: "invalid_input",
details: {
operation: "inspect",
issues: primary.issues,
execution_failure: "invalid_request",
},
});
releaseOwnedCleanup(released);
expect(outer.cleanupIncomplete).toBe(true);
expect(projectAnalysisError(outer).code).toBe("cleanup_incomplete");
expect(projectAnalysisError(outer).category).toBe("invalid_input");
releaseOwnedCleanup(pending);
expect(outer.cleanupIncomplete).toBe(false);
expect(projectAnalysisError(outer)).toMatchObject(
projectAnalysisError(primary),
);
},
);
it("preserves recovery and secondary failures owned by an intermediate cleanup", () => {
const primary = new AnalysisInputError("inspect");
const inner = analysisErrorWithCleanupFailure(
primary,
new ProviderCleanupError("fixture", ["input"], {}),
);
inner.retainSourcePublication({
kind: "omitted",
reason: "primary-authentication-failed",
source_closure: "not-established",
});
inner.retainSecondaryFailure(new AnalysisInputError("source"));
const outer = analysisErrorWithCleanupFailure(
inner,
new ProviderCleanupError("fixture", ["workspace"], {}),
);
expect(projectAnalysisError(outer)).toMatchObject({
details: {
completed_observation_omitted: {
reason: "primary-authentication-failed",
source_closure: "not-established",
},
secondary_failures: [{ code: "invalid_request" }],
},
});
});
it("prefers the outer publication source over the nested primary observation", () => {
const provider = { id: "fixture", name: "Fixture", version: null };
const source = createEvidence(unknownTarget("not-observed"), provider, {
operation: "source",
parameters: {},
result: "source",
});
const nested = createEvidence(unknownTarget("not-observed"), provider, {
operation: "nested",
parameters: {},
result: "nested",
});
const primary = new AnalysisCancelledError("inspect", {
partialObservation: nested,
});
const composed = analysisErrorWithCleanupFailure(
primary,
new ProviderCleanupError("fixture", ["input"], {}),
);
composed.partialObservation = source;
composed.retainSourcePublication({
kind: "omitted",
reason: "primary-authentication-failed",
source_closure: "not-established",
});
expect(projectAnalysisError(composed).details?.partial_observation).toEqual(
source,
);
});
it("does not infer cleanup success when a composition has no live owner binding", () => {
const primary = new AnalysisInputError("inspect");
const cleanup = new ProviderCleanupError("fixture", ["input"], {});
const composed = analysisErrorWithCleanupFailure(primary, cleanup);
releaseOwnedCleanup(cleanup);
expect(projectAnalysisError(composed).code).toBe("cleanup_incomplete");
expect(projectAnalysisError(composed).category).toBe("invalid_input");
expect(composed.cleanupIncomplete).toBe(true);
});
it("keeps the physical failure primary when later cleanup observes cancellation", () => {
const physical = Object.assign(new Error("selected file read EIO"), {
code: "EIO",
});
const primary = new ArtifactOperationError(
"inspect_asset_catalog",
"io",
undefined,
physical.message,
{ cause: physical },
);
const reason = { request: "cancel after read failure" };
const cleanup = new ProviderCleanupError(
"fixture",
["owned-input"],
{},
{
cause: new AnalysisCancelledError("inspect", { cause: reason }),
},
);
const composed = analysisErrorWithCleanupFailure(
primary,
cleanup,
"inspect",
).bindCleanupDependencies([primary, cleanup]);
expect(projectAnalysisError(composed)).toMatchObject({
code: "cleanup_incomplete",
category: "execution_failure",
details: {
operation: "inspect_asset_catalog",
reason: "io",
detail: physical.message,
execution_failure: "artifact_operation_failed",
},
});
expect(composed.cleanupPrimary?.cause).toBe(physical);
releaseOwnedCleanup(cleanup);
expect(projectAnalysisError(composed)).toMatchObject(
projectAnalysisError(primary),
);
});
it("retains an observation attached to the composite after the primary failed", () => {
const primary = new AnalysisInputError("inspect");
const cleanup = new ProviderCleanupError("fixture", ["input"], {});
const composed = analysisErrorWithCleanupFailure(
primary,
cleanup,
).bindCleanupDependencies([primary, cleanup]);
const observation = createEvidence(
unknownTarget("not-observed"),
{ id: "fixture", name: "Fixture", version: null },
{
operation: "inspect",
parameters: {},
result: { late_fact: true },
confidence: "observed",
locations: [],
limitations: [],
},
);
composed.retainPartialObservation(observation);
releaseOwnedCleanup(composed);
expect(projectAnalysisError(composed).code).toBe("cleanup_incomplete");
releaseOwnedCleanup(cleanup);
expect(projectAnalysisError(composed)).toMatchObject({
code: "invalid_request",
details: { partial_observation: observation },
});
});
it("retains an owner's finalization report independently of pending primary semantics", () => {
const report = {
owned_process_group: { state: "not_required" as const, reason: null },
terminal_renderer: { state: "not_required" as const, reason: null },
temporary_root: { state: "cleaned" as const, reason: null },
};
class ReportedCleanup extends ProviderCleanupError {
override readonly cleanupReport = report;
}
const primary = new AnalysisInputError("inspect", undefined, [
{ path: ["path"], reason: "missing_argument" },
]);
const finalized = new ReportedCleanup(
"fixture",
["input"],
{},
{
cleanupPrimary: primary,
},
);
const later = new ProviderCleanupError("fixture", ["workspace"], {});
const outer = analysisErrorWithCleanupFailure(
finalized,
later,
).bindCleanupDependencies([finalized, later]);
const assertReport = (error: typeof outer) => {
expect(projectAnalysisError(error)).toMatchObject({
category: "invalid_input",
details: {
operation: "inspect",
issues: primary.issues,
cleanup_report: report,
},
});
};
assertReport(finalized);
assertReport(outer);
expect(outer.cleanupIncomplete).toBe(true);
releaseOwnedCleanup(later);
assertReport(outer);
expect(outer.cleanupIncomplete).toBe(true);
releaseOwnedCleanup(finalized);
assertReport(outer);
expect(outer.cleanupIncomplete).toBe(false);
});
it.each(["primary", "cleanup", "default", "cleanup-continuing"] as const)(
"preserves the explicit %s remediation owner through cleanup projection",
(owner) => {
const primaryAction =
"Inspect the selected compiler before retrying this request.";
const cleanupAction =
"Release the recorded cleanup resource before retrying.";
const primary = new AnalysisTimeoutError(
"inspect",
123,
owner === "default" ? {} : { remediationAction: primaryAction },
);
const cleanup = new AnalysisCapabilityUnavailableError(
"process-ownership",
"close",
"retained cleanup",
{
cleanup: { reason: "close failed", resources: ["owned resource"] },
...(owner === "cleanup" ? { remediationAction: cleanupAction } : {}),
...(owner === "cleanup-continuing"
? { continuingCallerGuidance: { remediationAction: cleanupAction } }
: {}),
},
);
const composed = analysisErrorWithCleanupFailure(
primary,
cleanup,
"inspect",
);
const expected =
owner === "cleanup"
? cleanupAction
: owner === "default"
? "This analysis is unavailable for the current target. Choose another analysis or target."
: primaryAction;
expect(projectAnalysisError(composed).remediation.action).toBe(
owner === "cleanup-continuing" ? cleanupAction : expected,
);
expect(
projectAnalysisError(composed, "invocation").remediation.action,
).toBe(expected);
expect(composed.cleanupPrimary).toBe(primary);
expect(composed.cleanupResources).toEqual(["owned resource"]);
expect(projectAnalysisError(composed).code).toBe("cleanup_incomplete");
},
);
it("composes cleanup failures that complete only after every part releases", () => {
const first = new ProviderCleanupError(
"fixture",
["first-handle"],
{ reason: "first" },
{ operation: "fixture_close" },
);
const second = new ProviderCleanupError(
"fixture",
["second-handle"],
{ reason: "second" },
{ operation: "fixture_close" },
);
const untyped = new Error("untyped close failure");
const composite = providerCleanupErrorFromFailures(
"fixture-provider",
[first, second],
"Fixture cleanup remains incomplete",
{
operation: "fixture_close",
causes: [first, untyped, second],
message: "Fixture cleanup failed",
},
);
expect(composite).toBeInstanceOf(ProviderCleanupError);
expect(composite).toMatchObject({
providerId: "fixture-provider",
operation: "fixture_close",
cleanupIncomplete: true,
cleanupResources: ["first-handle", "second-handle"],
diagnostics: { reason: "Fixture cleanup remains incomplete" },
});
expect(composite.cause).toBeInstanceOf(AggregateError);
expect((composite.cause as AggregateError).errors).toEqual([
first,
untyped,
second,
]);
expect((composite.cause as AggregateError).message).toBe(
"Fixture cleanup failed",
);
releaseOwnedCleanup(first);
expect(composite.cleanupIncomplete).toBe(true);
releaseOwnedCleanup(second);
expect(composite.cleanupIncomplete).toBe(false);
});
it("lists a resource shared by several parts once", () => {
const parts = ["first", "second"].map(
(reason) =>
new ProviderCleanupError(
"fixture",
["shared-handle", `${reason}-handle`],
{ reason },
{ operation: "fixture_close" },
),
);
const composite = providerCleanupErrorFromFailures(
"fixture-provider",
parts,
"Fixture cleanup remains incomplete",
{ operation: "fixture_close" },
);
expect(composite.cleanupResources).toEqual([
"shared-handle",
"first-handle",
"second-handle",
]);
releaseOwnedCleanup(parts[0]!);
expect(composite.cleanupResources).toEqual([
"shared-handle",
"second-handle",
]);
});
it("defaults the aggregate cause to the owned failures", () => {
const only = new ProviderCleanupError(
"fixture",
["only-handle"],
{ reason: "only" },
{ operation: "fixture_close" },
);
const composite = providerCleanupErrorFromFailures(
"fixture-provider",
[only],
"Fixture cleanup remains incomplete",
{ operation: "fixture_close" },
);
expect((composite.cause as AggregateError).errors).toEqual([only]);
expect((composite.cause as AggregateError).message).toBe("");
});
it("follows an existing owner's release via withInheritedCleanupOwnership", () => {
const owner = new ProviderCleanupError("fixture", ["owned-handle"], {});
const cleanup = { reason: owner.message, resources: owner.cleanupResources };
const wrapper = withInheritedCleanupOwnership(
new AnalysisCapabilityUnavailableError("fixture", "open", "wrapped", {
cleanup,
}),
owner,
);
expect(wrapper.cleanupIncomplete).toBe(true);
expect(wrapper.cleanupResources).toEqual(["owned-handle"]);
releaseOwnedCleanup(owner);
expect(wrapper.cleanupIncomplete).toBe(false);
expect(wrapper.cleanupResources).toEqual([]);
const unownedCleanup = new AnalysisCapabilityUnavailableError(
"fixture",
"open",
"wrapped",
{
cleanup,
},
);
const retainedUnknown = withInheritedCleanupOwnership(unownedCleanup, owner);
expect(retainedUnknown.cleanupIncomplete).toBe(true);
const cleanOwner = new AnalysisInputError("open", undefined, []);
const cleanWrapper = withInheritedCleanupOwnership(
new AnalysisInputError("open", undefined, []),
cleanOwner,
);
expect(cleanWrapper.hasCleanupOwner).toBe(false);
expect(cleanWrapper.cleanupIncomplete).toBe(false);
});