Files
reverse-engineering-anything/src/domain/browserObservationError.ts
T
morluto 5f718ce30e refactor(kernel): give error-message, byte-hex and SHA-256 hex helpers one owner in a new src/kernel layer (#11542)
* refactor(kernel): give error-to-message text one owner in a new src/kernel layer

* fix(kernel): keep the regex worker's own error text inside its isolated source

* refactor(kernel): exclude copies that run in another realm from the error-message guard by name

The regex worker's source string and the page.evaluate fetch in PlaywrightScenarioRequest cannot import errorMessage. The guard now names them, so the counted baseline does not invite a later slice to rewrite them.

* refactor(kernel): migrate the long tail of inline error-message copies to errorMessage (#11552)

Every provider and adapter folder with six or fewer copies now calls errorMessage from src/kernel. Local helpers whose whole body was the copy (failureMessage, gdbErrorMessage, message, describe, reasonOf, recoveryFailureMessage and four local errorMessage definitions) are removed and their call sites call the owner.

Refs #11548

* refactor(kernel): give byte-to-hex formatting one owner in src/kernel (#11560)

byteToHex returns the two lowercase hexadecimal digits of one byte. All eight inline copies (native, contracts, domain firmware and desktop, pcap) call it, keeping their own 0x, % or \x notation, and a counted guard with an empty baseline keeps new copies out.

Refs #11548

* refactor(kernel): give one-shot SHA-256 hex digests one owner in src/kernel (#11562)

sha256Hex digests one in-memory value. A counted guard records the one-shot createHash("sha256").update(x).digest("hex") chains (115 in 101 files) and the first slice migrates domain, contracts and process (35 copies), removing local wrappers (sha256, sha256Text, hash) and the exported sha256Text. Incremental and streamed hashing is not counted.

Refs #11548

* refactor(kernel): migrate the application layer's inline error-message copies to errorMessage (#11563)

All 69 copies in src/application call errorMessage from src/kernel. Local helpers whose whole body was the copy (errorDetail, causeReason and five local errorMessage definitions) are removed and their call sites call the owner.

Refs #11548

* refactor(kernel): migrate the native provider's inline error-message copies to errorMessage (#11567)

All 49 copies in src/native call errorMessage from src/kernel. The local errorReason helpers in LldbCallTracer and LldbRetainedObservations, whose whole body was the copy, are removed and their call sites call the owner.

Refs #11548

* refactor(kernel): migrate the remaining inline error-message copies to errorMessage (#11569)
2026-11-16 07:05:30 +08:00

110 lines
4.9 KiB
TypeScript

import type {
BrowserObservationFailureReason,
BrowserObservationOperation,
} from "./browserObservationErrors.js";
import {
AnalysisError,
type AnalysisCleanupObservation,
type AnalysisErrorOptions,
} from "./analysisErrorBase.js";
import { AnalysisCancelledError } from "./analysisErrorCore.js";
import { errorMessage } from "../kernel/errorMessage.js";
/** Describe browser cleanup failure without discarding its resource evidence. */
export const browserCleanupObservation = (
cause: unknown,
): AnalysisCleanupObservation =>
cause instanceof AnalysisError && cause.cleanup !== undefined
? cause.cleanup
: {
reason: errorMessage(cause),
resources:
cause instanceof AnalysisError && cause.cleanupResources.length > 0
? cause.cleanupResources
: ["browser_transport"],
};
/** A bounded passive browser observation failed at its CDP boundary. */
export class BrowserObservationError extends AnalysisError {
readonly _tag = "BrowserObservationError";
override readonly userCategory: "cancelled" | undefined;
override readonly userMessage: string | undefined;
/** Producer-supplied explanation; undefined selects the operation default. */
readonly detail: string | undefined;
readonly remediationAction: string | undefined;
constructor(
readonly operation: BrowserObservationOperation,
readonly reason: BrowserObservationFailureReason,
options?: AnalysisErrorOptions & {
readonly detail?: string;
readonly remediationAction?: string;
},
) {
super(`Browser observation ${operation} failed: ${reason}`, options);
this.detail = options?.detail;
this.userMessage =
options?.detail ?? observationFailureMessage(operation, reason);
this.remediationAction = options?.remediationAction;
this.markCleanupIncomplete(
this.cleanup !== undefined || reason === "cleanup_failed",
);
this.setCleanupResources(
this.cleanup?.resources ??
(reason === "cleanup_failed" ? ["browser_transport"] : []),
);
this.userCategory =
reason === "cancelled" ||
options?.cause instanceof AnalysisCancelledError ||
(options?.cause instanceof AnalysisError &&
options.cause.userCategory === "cancelled")
? "cancelled"
: undefined;
}
/**
* Attribute this failure to the caller's operation without discarding
* producer facts; the original cause keeps the primary failure chain intact.
*/
forOperation(
operation: BrowserObservationOperation,
): BrowserObservationError {
if (operation === this.operation) return this;
return new BrowserObservationError(operation, this.reason, {
cause: this.cause,
...(this.detail === undefined ? {} : { detail: this.detail }),
...(this.remediationAction === undefined
? {}
: { remediationAction: this.remediationAction }),
cleanupPrimary: this.cleanupPrimary,
diagnostics: this.diagnostics,
capturedOutput: this.capturedOutput,
cleanup: this.cleanup,
partialObservation: this.partialObservation,
});
}
}
const observationFailureMessage = (
operation: BrowserObservationOperation,
reason: BrowserObservationFailureReason,
): string | undefined => {
if (reason === "cancelled")
return `${operation} was cancelled. Collected observations and cleanup status are reported when available.`;
if (reason === "timeout")
return `${operation} exceeded its execution deadline. Review the target's responsiveness and retained observations before retrying.`;
if (reason === "endpoint_unreachable")
return `${operation} could not reach the selected loopback debugging endpoint. Verify that the target process is running with debugging enabled and that the endpoint's port matches it, then retry.`;
if (reason === "target_not_found")
return `${operation} could not find the selected target at the debugging endpoint. Refresh target discovery for that endpoint and retry with a returned target ID.`;
if (reason === "target_session_detached")
return `${operation} lost its debugging session while the target may still exist. Refresh target discovery and attach to the selected target again.`;
if (reason === "target_changed")
return `${operation} could not retain a stable document because the target changed during observation. Retry after navigation settles; refresh target discovery if the selected page was replaced.`;
if (reason === "service_worker_blocked")
return `${operation} refused the selected page because it is controlled by or has a registered service worker while the service-worker policy is block. Set environment.service_workers to allow to permit observation, or remove the service worker registration through the browser.`;
if (reason === "disconnected")
return `${operation} lost its debugging connection. Verify that the target process is still running, refresh target discovery, and retry the observation.`;
return undefined;
};