chore: integrate canonical Evidence changes for MCP error delivery

This commit is contained in:
N0zoM1z0
2026-10-09 12:43:17 +00:00
643 changed files with 12727 additions and 10243 deletions
+65 -7
View File
@@ -1,6 +1,7 @@
import { constants } from "node:fs";
import { access, realpath, stat } from "node:fs/promises";
import { isAbsolute, join } from "node:path";
import { delimiter, isAbsolute, join, resolve } from "node:path";
import { systemWindowsNativeAuthority } from "../windows/WindowsNativeLoader.js";
import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
import type { AndroidOperation } from "../domain/android/androidAnalysis.js";
import type { JsonValue } from "../domain/jsonValue.js";
@@ -116,7 +117,7 @@ const readJadxConfiguration = async (
): Promise<JadxConfiguration> => {
requireSupportedHost();
const jar = await resolveJar(environment);
const java = resolveJava(environment);
const java = await resolveJava(environment, signal);
await requireJavaHomeExecutable(environment.JAVA_HOME, java);
const jvmArguments = resolveJvmArguments(environment);
await inspectJavaRuntime(java, environment, signal);
@@ -169,9 +170,26 @@ const requireEngineArchive = async (
const requireSupportedHost = (): void => {
if (process.platform === "linux" || process.platform === "darwin") return;
if (process.platform === "win32" && process.arch === "x64") {
const loaded = systemWindowsNativeAuthority();
if (loaded.available && loaded.authority.inspection.protocolStdin === true)
return;
throw configurationFailure(
"runtime_missing",
loaded.available
? "The bundled Windows native artifact lacks owned protocol stdin; use a matching current Windows x64 REA package."
: loaded.reason,
{
platform: process.platform,
architecture: process.arch,
phase: "process-ownership",
owned_protocol_stdin: false,
},
);
}
throw configurationFailure(
"unsupported_host",
`Android JADX subprocess ownership is unsupported on ${process.platform}; use Linux or macOS. The metadata bridge has real-provider verification on macOS arm64.`,
`Android JADX subprocess ownership is unsupported on ${process.platform}/${process.arch}; use Linux, macOS, or Windows x64 with its bundled native controls.`,
{ platform: process.platform },
);
};
@@ -206,12 +224,52 @@ const resolveJar = async (
}
};
const resolveJava = (
const resolveJava = async (
environment: Readonly<Record<string, string | undefined>>,
): string => {
if (environment.JAVA_HOME === undefined) return "java";
signal?: AbortSignal,
): Promise<string> => {
const executable = process.platform === "win32" ? "java.exe" : "java";
if (environment.JAVA_HOME === undefined) {
if (process.platform !== "win32") return executable;
const path =
Object.entries(environment).find(
([key]) => key.toLowerCase() === "path",
)?.[1] ?? "";
for (const directory of [process.cwd(), ...path.split(delimiter)]) {
signal?.throwIfAborted();
// Windows PATH commonly quotes individual entries containing spaces.
const selected =
directory.startsWith('"') && directory.endsWith('"')
? directory.slice(1, -1)
: directory;
const candidate = resolve(selected, executable);
try {
await access(candidate, constants.R_OK | constants.X_OK);
if ((await stat(candidate)).isFile()) return await realpath(candidate);
} catch (cause: unknown) {
if (
typeof cause === "object" &&
cause !== null &&
"code" in cause &&
(cause.code === "ENOENT" || cause.code === "ENOTDIR")
)
continue;
throw configurationFailure(
"runtime_missing",
`Cannot inspect selected Java executable ${candidate}: ${errorText(cause)}`,
{ java_executable: candidate },
cause,
);
}
}
throw configurationFailure(
"runtime_missing",
"Cannot find java.exe on the selected Windows PATH. Select a full JDK with JAVA_HOME or PATH, then verify it with java --list-modules. REA does not install Java.",
{ java_executable: executable },
);
}
if (isAbsolute(environment.JAVA_HOME))
return join(environment.JAVA_HOME, "bin", "java");
return join(environment.JAVA_HOME, "bin", executable);
throw configurationFailure(
"open_options_invalid",
"JAVA_HOME must select an existing JDK by absolute path; omit it to use java on PATH.",
+18 -3
View File
@@ -5,6 +5,7 @@ import {
type Transport,
} from "@modelcontextprotocol/client";
import { randomUUID } from "node:crypto";
import { finished } from "node:stream/promises";
import type {
OwnedProviderProcessSpawnOptions,
SpawnedOwnedProviderProcess,
@@ -19,7 +20,7 @@ import { ProviderCleanupError } from "../domain/providerCleanupError.js";
const MAX_FRAME_BYTES = 8 * 1024 * 1024;
const MAX_OPERATION_BYTES = 32 * 1024 * 1024;
/** Injectable process acquisition seam; the production launcher owns a POSIX group. */
/** Injectable acquisition seam; production owns a POSIX group or Windows job. */
export type JadxLauncher = (
options: OwnedProviderProcessSpawnOptions,
) => Promise<SpawnedOwnedProviderProcess>;
@@ -100,7 +101,10 @@ export class JadxMcpTransport implements Transport {
/** Verifies owned process exit before declaring the transport closed. */
close(): Promise<void> {
this.#closePromise ??= this.#stop();
this.#closePromise ??= this.#stop().catch((cause: unknown) => {
this.#closePromise = undefined;
throw cause;
});
return this.#closePromise;
}
@@ -136,8 +140,19 @@ export class JadxMcpTransport implements Transport {
process?.stderr?.off("data", this.#countStderr);
process?.off("error", this.#error);
process?.off("exit", this.#exit);
process?.stdin?.off("error", this.#error);
const input = process?.stdin;
// A job termination can complete an in-flight pipe write asynchronously.
// Observe its errors until the owned Writable has finished closing.
const inputClosed =
input === undefined || input === null
? undefined
: finished(input, { readable: false, cleanup: true }).catch(
() => undefined,
);
const stopped = await this.#supervisor?.stop();
input?.destroy();
await inputClosed;
input?.off("error", this.#error);
this.onclose?.();
if (stopped?.status === "incomplete")
throw new ProviderCleanupError("jadx", [this.runId], {
+67 -51
View File
@@ -14,6 +14,7 @@ import {
} from "../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type { AndroidRequest } from "../domain/android/androidAnalysis.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import { err, ok, type Result } from "../domain/result.js";
@@ -103,18 +104,23 @@ const executionError = (context: {
});
};
const cleanup = async <Value>(
session: JadxSession | undefined,
root: PrivateRuntimeRoot | undefined,
previous: Result<Value, AnalysisError>,
): Promise<Result<Value, AnalysisError>> => {
interface PendingCleanup {
session: JadxSession | undefined;
root: PrivateRuntimeRoot | undefined;
readonly previousError: AnalysisError | undefined;
}
const cleanup = async (
resources: PendingCleanup,
): Promise<Result<void, AnalysisError>> => {
const { session, root, previousError } = resources;
const diagnostics = {
previous_error: previous.ok
? null
: { tag: previous.error._tag, message: previous.error.message },
previous_error:
previousError === undefined ? null : projectAnalysisError(previousError),
};
try {
await session?.close();
resources.session = undefined;
} catch (cause) {
// Retain an uncertain workspace until the caller can resolve process ownership.
return err(
@@ -132,12 +138,13 @@ const cleanup = async <Value>(
? (cause.diagnostics ?? null)
: null,
},
{ cause },
{ cause: previousError ?? cause },
),
);
}
try {
await root?.close();
resources.root = undefined;
} catch (cause) {
return err(
new ProviderCleanupError(
@@ -147,11 +154,11 @@ const cleanup = async <Value>(
...diagnostics,
reason: cause instanceof Error ? cause.message : String(cause),
},
{ cause },
{ cause: previousError ?? cause },
),
);
}
return previous;
return ok(undefined);
};
interface RetainedSession {
@@ -166,15 +173,13 @@ interface RetainedSession {
/** One serialized, immutable APK session per REA instance, retired on idle or shutdown. */
export class JadxProvider implements AndroidAnalysisPort {
#tail: Promise<void> = Promise.resolve();
#cleanupFailure: AnalysisError | undefined;
#pendingCleanup: PendingCleanup | undefined;
#retained: RetainedSession | undefined;
#idle: NodeJS.Timeout | undefined;
readonly #shutdown = new AbortController();
#closePromise: Promise<void> | undefined;
constructor(
readonly environment: Readonly<
Record<string, string | undefined>
> = process.env,
readonly environment: Readonly<Record<string, string | undefined>>,
readonly launcher?: JadxLauncher,
) {}
@@ -209,11 +214,12 @@ export class JadxProvider implements AndroidAnalysisPort {
try {
if (signal.aborted)
return err(new AnalysisCancelledError(request.operation));
if (this.#cleanupFailure !== undefined) return err(this.#cleanupFailure);
clearTimeout(this.#idle);
if (this.#pendingCleanup !== undefined) {
const retired = await this.#retire();
if (!retired.ok) return retired;
}
const outcome = await this.#execute(target, request, { signal });
if (!outcome.ok && outcome.error.cleanupIncomplete)
this.#cleanupFailure = outcome.error;
if (outcome.ok) this.#scheduleIdle();
return outcome;
} finally {
@@ -225,29 +231,38 @@ export class JadxProvider implements AndroidAnalysisPort {
close(): Promise<void> {
this.#shutdown.abort();
clearTimeout(this.#idle);
this.#closePromise ??= this.#tail.then(() => this.#retire());
this.#closePromise ??= this.#tail
.then(async () => {
const retired = await this.#retire();
if (!retired.ok) throw retired.error;
})
.catch((cause: unknown) => {
this.#closePromise = undefined;
throw cause;
});
return this.#closePromise;
}
async #retire(): Promise<void> {
if (this.#cleanupFailure !== undefined) throw this.#cleanupFailure;
const retained = this.#retained;
this.#retained = undefined;
const result = await cleanup(
retained?.session,
retained?.root,
ok(undefined),
);
if (!result.ok) {
this.#cleanupFailure = result.error;
throw result.error;
async #retire(): Promise<Result<void, AnalysisError>> {
if (this.#pendingCleanup === undefined && this.#retained !== undefined) {
this.#pendingCleanup = {
session: this.#retained.session,
root: this.#retained.root,
previousError: undefined,
};
this.#retained = undefined;
}
if (this.#pendingCleanup === undefined) return ok(undefined);
const result = await cleanup(this.#pendingCleanup);
if (result.ok) this.#pendingCleanup = undefined;
return result;
}
#scheduleIdle(): void {
this.#idle = setTimeout(() => {
const retirement = this.#tail.then(() => this.#retire());
this.#tail = retirement.catch(() => undefined);
this.#tail = this.#tail.then(async () => {
await this.#retire();
});
}, 60_000);
this.#idle.unref();
}
@@ -264,7 +279,6 @@ export class JadxProvider implements AndroidAnalysisPort {
: AbortSignal.any([options.signal, timeout]);
let root: PrivateRuntimeRoot | undefined;
let session: JadxSession | undefined;
let outcome: Outcome;
try {
if (target.format !== "apk")
throw new AnalysisCapabilityUnavailableError(
@@ -305,8 +319,10 @@ export class JadxProvider implements AndroidAnalysisPort {
this.environment.JAVA_HOME,
],
});
if (this.#retained !== undefined && this.#retained.key !== key)
await this.#retire();
if (this.#retained !== undefined && this.#retained.key !== key) {
const retired = await this.#retire();
if (!retired.ok) return retired;
}
let retained = this.#retained;
if (retained === undefined) {
root = await PrivateRuntimeRoot.create({ prefix: "rea-android-" });
@@ -359,7 +375,7 @@ export class JadxProvider implements AndroidAnalysisPort {
root = retained.root;
session = retained.session;
const { snapshot } = retained;
outcome = ok(
const outcome = ok(
await session.execute({
request,
target,
@@ -373,20 +389,20 @@ export class JadxProvider implements AndroidAnalysisPort {
this.#retained = retained;
return outcome;
} catch (cause) {
outcome = err(
executionError({
cause,
request,
timeout,
signal: options?.signal,
session,
}),
);
const previousError = executionError({
cause,
request,
timeout,
signal: options?.signal,
session,
});
// Admission can fail before selecting an existing session for execution.
root ??= this.#retained?.root;
session ??= this.#retained?.session;
this.#retained = undefined;
this.#pendingCleanup = { session, root, previousError };
const retired = await this.#retire();
return retired.ok ? err(previousError) : retired;
}
// An existing session also needs retirement when admission fails before selection.
root ??= this.#retained?.root;
session ??= this.#retained?.session;
this.#retained = undefined;
return cleanup(session, root, outcome);
}
}
@@ -9,9 +9,7 @@ import {
type AnalysisOperationPort,
} from "./AnalysisProvider.js";
import {
AnalysisCapabilityUnavailableError,
AnalysisCancelledError,
AnalysisOutputError,
AnalysisProtocolError,
} from "../domain/analysisErrorCore.js";
import { err, ok } from "../domain/result.js";
@@ -94,111 +92,6 @@ describe("analysis context queries: navigation", () => {
});
});
describe("analysis context queries: headless document resolution", () => {
it("resolves a sole headless document when current-document selection is unavailable", async () => {
const calls: string[] = [];
const analysis: AnalysisOperationPort = {
execute: (operation) => {
calls.push(operation);
if (operation === "current_document")
return Promise.resolve(
err(
new AnalysisCapabilityUnavailableError(
"ghidra",
operation,
"headless sessions have no cursor-selected document",
),
),
);
if (operation === "list_documents")
return Promise.resolve(
ok(createAnalysisExecution(["fixture"], provider)),
);
if (operation === "resolve_containing_procedure")
return Promise.resolve(
ok(
createAnalysisExecution(
{
query_address: "0x401000",
found: false,
procedure: null,
reason: "not_in_procedure",
},
provider,
),
),
);
return Promise.resolve(
err(
new AnalysisCapabilityUnavailableError(
"ghidra",
operation,
"unsupported",
),
),
);
},
};
await expect(
inspectAddressContext(analysis, { address: "0x401000" }),
).resolves.toMatchObject({
ok: true,
value: {
document: "fixture",
name: { state: "unavailable" },
procedure: { state: "available" },
comment: { state: "unavailable" },
inline_comment: { state: "unavailable" },
bookmarks: { state: "unavailable" },
},
});
expect(calls.slice(0, 2)).toEqual(["current_document", "list_documents"]);
});
it("does not use list-documents fallback for non-capability document errors", async () => {
const failure = new AnalysisProtocolError(
"current-document response malformed",
);
const calls: string[] = [];
const analysis: AnalysisOperationPort = {
execute: (operation) => {
calls.push(operation);
return Promise.resolve(err(failure));
},
};
await expect(
inspectAddressContext(analysis, { address: "0x401000" }),
).resolves.toEqual(err(failure));
expect(calls).toEqual(["current_document"]);
});
it("requires exactly one listed document for a headless fallback", async () => {
const analysis: AnalysisOperationPort = {
execute: (operation) =>
Promise.resolve(
operation === "current_document"
? err(
new AnalysisCapabilityUnavailableError(
"ghidra",
operation,
"no selected document",
),
)
: ok(createAnalysisExecution(["one", "two"], provider)),
),
};
await expect(
inspectAddressContext(analysis, { address: "0x401000" }),
).resolves.toMatchObject({
ok: false,
error: expect.any(AnalysisOutputError),
});
});
});
describe("analysis context queries: address facets", () => {
it("keeps unsupported address facets local and filters bookmarks", async () => {
const bookmarkInputs: Readonly<Record<string, unknown>>[] = [];
+3 -11
View File
@@ -102,13 +102,12 @@ export interface AnalysisClient extends AnalysisOperationPort {
requestActivitySnapshots?(): readonly ProviderRequestActivitySnapshot[];
/** Current operational health for the active provider bridge. */
operationHealthSnapshot?(): ProviderOperationHealth | undefined;
/** Close with a typed result when the provider can verify cleanup. */
closeWithOutcome?(
/** Close owned resources and retain failed cleanup for a later retry. */
close(
options?: Pick<ExecutionOptions, "progress"> & {
readonly retainDocument?: boolean;
},
): Promise<Result<null, AnalysisError>>;
close(): Promise<void>;
}
/** Per-client identity allocated before any provider side effect starts. */
@@ -116,22 +115,15 @@ export interface AnalysisClientContext {
readonly runId: string;
}
export type AnalysisClientFactory = (
target: BinaryTarget,
profile?: AnalysisProfileCommitment,
context?: AnalysisClientContext,
) => AnalysisClient;
export interface ProviderIdentity {
readonly id: string;
readonly name: string;
readonly version: string | null;
}
/** Profile plus opaque compatibility output resolved before provider startup. */
/** Typed analysis profile resolved before provider startup; null means unresolved. */
export interface AnalysisProfileResolution {
readonly profile: AnalysisProfileCommitment | null;
readonly compatibility: Readonly<Record<string, JsonValue>>;
}
/** Cancellation context for side-effect-free provider profile resolution. */
+3 -12
View File
@@ -100,11 +100,7 @@ const browserParameters = (
result: BrowserEvidenceResult,
): EvidenceObservation["parameters"] => {
if (!("cdp_endpoint" in input)) {
if (
"before_scenario" in input &&
input.before_scenario !== undefined &&
input.after_scenario !== undefined
)
if ("before_scenario" in input)
return {
comparison_kind: "browser_scenario",
before_browser: input.before_scenario.browser,
@@ -112,15 +108,10 @@ const browserParameters = (
before_start_origin: input.before_scenario.scenario.start_origin,
after_start_origin: input.after_scenario.scenario.start_origin,
normalization_sha256: commitBrowserScenarioNormalization(
input.normalization ?? { rules: [] },
input.normalization,
).sha256,
};
if (
input.before !== undefined &&
input.after !== undefined &&
"inspection" in input.before &&
"inspection" in input.after
)
if ("inspection" in input.before && "inspection" in input.after)
return {
before_target_id: input.before.inspection.target.target_id,
before_capture_ended_at:
+2 -22
View File
@@ -2,38 +2,18 @@ import { canonicalDigest } from "../domain/comparisonSemantics.js";
import type { ProviderIdentity } from "./AnalysisProvider.js";
import type { BrowserScenario } from "../domain/browserScenario.js";
import type { BrowserScenarioCapture } from "../domain/browserScenarioCapture.js";
import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
import {
createEvidence,
type Evidence,
type EvidenceObservation,
} from "../domain/evidence.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
const browserScenarioParameters = (
scenario: BrowserScenario,
): EvidenceObservation["parameters"] => ({
...jsonObjectSchema.parse(scenario),
scenario_sha256: canonicalDigest(scenario, "Browser scenario"),
browser_mode: scenario.browser.mode,
...(scenario.browser.mode === "launch"
? { browser_headless: scenario.browser.headless }
: {}),
start_url: sanitizeBrowserUrl(scenario.start_url.url),
environment: scenario.environment,
actions: scenario.actions.map(({ step_id, action }) => ({
step_id,
action,
})),
action_timeouts_ms: scenario.actions.map((item) =>
"timeout_ms" in item ? (item.timeout_ms ?? null) : null,
),
secret_declarations: scenario.secrets.map(
({ secret_id, environment_variable }) => ({
secret_id,
environment_variable,
}),
),
capture: scenario.capture,
});
/** Create Evidence without retaining resolved scenario secret values. */
+27 -273
View File
@@ -1,6 +1,5 @@
import { describe, expect, it } from "vitest";
import { toolAvailability } from "../contracts/toolOutputSchemaPrimitives.js";
import { buildCapabilityInventory } from "./CapabilityInventory.js";
it("reports module syntax and native resolution availability separately", () => {
@@ -40,10 +39,6 @@ const enabledPolicy: Parameters<typeof buildCapabilityInventory>[1] = {
v8InspectorObservationEnabled: true,
};
const availableAndroidAvailability: NonNullable<
Parameters<typeof buildCapabilityInventory>[1]["androidAnalysisAvailability"]
> = { status: "available", code: null, reason: null, diagnostics: {} };
const status = (
options: {
readonly open?: boolean;
@@ -90,49 +85,7 @@ const entry = (
return found;
};
describe("capability inventory: provider status", () => {
it("reports firmware inspection and extraction prerequisites independently", () => {
const policy = {
processCaptureEnabled: true,
firmwareInspectionEnabled: true,
};
expect(entry("inspect_firmware_regions", status(), policy)).toMatchObject({
available: true,
surface: "firmware-provider",
});
expect(entry("extract_firmware", status(), policy)).toMatchObject({
available: false,
reason: "provider_missing",
remediation: expect.stringContaining("REA_UNBLOB_COMMAND"),
});
expect(
entry("extract_firmware", status(), {
processCaptureEnabled: true,
firmwareExtractionEnabled: true,
}),
).toMatchObject({ available: true });
});
it("keeps Android APK operations target-free and reports their explicit engine prerequisite", () => {
expect(
entry("inspect_android_package", status(), {
processCaptureEnabled: true,
androidAnalysisAvailability: availableAndroidAvailability,
}),
).toMatchObject({
available: true,
surface: "android-provider",
reason: "available",
});
expect(
entry("inspect_android_package", status(), {
processCaptureEnabled: true,
}),
).toMatchObject({
available: false,
reason: "provider_missing",
remediation: expect.stringContaining("REA_JADX_MCP_JAR"),
});
});
describe("capability failure reasons", () => {
it.each([
{
label: "requires a target",
@@ -216,212 +169,9 @@ describe("capability inventory: provider status", () => {
if (remediation === null) expect(availability.remediation).toBeNull();
else expect(availability.remediation).toContain(remediation);
});
it("keeps configured workflows callable and reports only real host or provider limits", () => {
const inventory = buildCapabilityInventory(status(), {
...enabledPolicy,
processCaptureEnabled: false,
browserObservationEnabled: false,
browserScenarioEnabled: false,
electronObservationEnabled: false,
electronAutomationEnabled: false,
v8InspectorObservationEnabled: false,
});
const byName = new Map(inventory.map((item) => [item.name, item]));
expect(byName.get("capture_process_scenario")).toMatchObject({
available: false,
reason: "unsupported_host",
});
expect(byName.get("inspect_web_page")).toMatchObject({
available: false,
reason: "provider_missing",
});
});
});
describe("capability inventory: active-target operations", () => {
const ACTIVE_TARGET_TOOLS = [
"inspect_macho",
"inspect_signature",
"list_architectures",
"demangle_swift",
"inspect_artifact",
"extract_artifact",
] as const;
const declared = (
names: readonly string[],
availability: {
readonly available: boolean;
readonly reason: string | null;
} = {
available: true,
reason: null,
},
) => names.map((operation) => ({ operation, ...availability }));
const reasons = (
sessionStatus: ReturnType<typeof status>,
names: readonly string[],
policy = enabledPolicy,
) =>
Object.fromEntries(
names.map((name) => [name, entry(name, sessionStatus, policy).reason]),
);
it("requires an open target even when the provider declares the operation", () => {
const closed = status({ capabilities: declared(ACTIVE_TARGET_TOOLS) });
for (const name of ACTIVE_TARGET_TOOLS)
expect(entry(name, closed)).toMatchObject({
available: false,
reason: "target_required",
remediation: expect.stringContaining("open_binary"),
});
});
it("keeps explicit-path operations available without a target", () => {
const explicitPath = [
"inspect_managed_artifact",
"inspect_binary_layout",
"inspect_recorded_crash",
"inspect_evm_interface",
];
expect(
reasons(status(), explicitPath, {
...enabledPolicy,
binaryLayoutEnabled: true,
recordedCrashEnabled: true,
evmInterfaceEnabled: true,
}),
).toEqual(
Object.fromEntries(explicitPath.map((name) => [name, "available"])),
);
});
it("reserves Mach-O operations for an open Mach-O executable", () => {
const capabilities = declared(ACTIVE_TARGET_TOOLS);
const machO = status({
open: true,
kind: "executable",
format: "mach-o",
capabilities,
});
const zip = status({
open: true,
kind: "archive",
format: "zip",
capabilities,
});
const elf = status({
open: true,
kind: "executable",
format: "elf",
capabilities,
});
expect(reasons(machO, ACTIVE_TARGET_TOOLS)).toEqual(
Object.fromEntries(
ACTIVE_TARGET_TOOLS.map((name) => [name, "available"]),
),
);
for (const target of [zip, elf])
expect(reasons(target, ACTIVE_TARGET_TOOLS)).toEqual({
inspect_macho: "target_unsupported",
inspect_signature: "available",
list_architectures: "target_unsupported",
demangle_swift: "available",
inspect_artifact: "available",
extract_artifact: "available",
});
expect(entry("inspect_macho", zip).remediation).toContain("Mach-O");
});
it("reports an unsupported host before asking for a target", () => {
const capabilities = declared(["inspect_macho"], {
available: false,
reason: "Native macOS utilities require macOS.",
}).map((capability) => ({
...capability,
availability_code: "unsupported_host" as const,
}));
for (const sessionStatus of [
status({ capabilities }),
status({ open: true, kind: "archive", format: "zip", capabilities }),
])
expect(entry("inspect_macho", sessionStatus)).toMatchObject({
reason: "unsupported_host",
remediation: "Native macOS utilities require macOS.",
});
const composed = capabilities.map((capability) => ({
...capability,
operation: "inspect_native_dispatch_metadata",
}));
expect(
entry(
"inspect_native_dispatch_metadata",
status({ capabilities: composed }),
).reason,
).toBe("target_required");
});
});
describe("capability inventory: caller guidance", () => {
it("gives every unavailable public tool an actionable remediation", () => {
const inventory = buildCapabilityInventory(status(), {
...enabledPolicy,
processCaptureEnabled: false,
browserObservationEnabled: false,
electronObservationEnabled: false,
v8InspectorObservationEnabled: false,
});
for (const availability of inventory)
if (!availability.available) {
expect(availability.reason).not.toBe("available");
expect(availability.remediation).toEqual(expect.any(String));
expect(availability.remediation?.length).toBeGreaterThan(0);
}
});
it("keeps the public availability schema consistent with generated states", () => {
const inventory = buildCapabilityInventory(status(), enabledPolicy);
const unavailable = inventory.find(({ available }) => !available);
expect(unavailable).toBeDefined();
expect(toolAvailability.safeParse(unavailable).success).toBe(true);
expect(
toolAvailability.safeParse({ ...unavailable, available: true }).success,
).toBe(false);
expect(
toolAvailability.safeParse({
...unavailable,
available: false,
reason: "available",
}).success,
).toBe(false);
});
it("does not require interactive elicitation for process capture", () => {
const withoutElicitation = buildCapabilityInventory(
status(),
enabledPolicy,
).find(({ name }) => name === "capture_process_scenario");
const withElicitation = buildCapabilityInventory(status(), enabledPolicy, {
elicitation_form: true,
elicitation_url: false,
roots: false,
sampling: false,
}).find(({ name }) => name === "capture_process_scenario");
expect(withoutElicitation?.client_requirements).toEqual({
required: [],
optional: [],
missing_required: [],
missing_optional: [],
});
expect(withElicitation?.client_requirements).toEqual({
required: [],
optional: [],
missing_required: [],
missing_optional: [],
});
});
describe("partial navigation availability", () => {
it("allows explicit documents when the provider has no current-document getter", () => {
const capabilities = [
"current_document",
@@ -510,28 +260,32 @@ describe("capability inventory: caller guidance", () => {
});
});
describe("optional JavaScript recovery availability", () => {
it("keeps optional recovery target-free and does not disable other static workflows", () => {
expect(entry("recover_javascript_sources", status())).toMatchObject({
available: false,
reason: "provider_missing",
remediation: expect.stringContaining("REA_WAKARU_COMMAND"),
});
it("reports host denial before target mismatch but keeps composed workflow prerequisites", () => {
const capability = {
operation: "inspect_macho",
available: false,
availability_code: "unsupported_host" as const,
reason: "Native macOS utilities require macOS.",
};
for (const target of [
{},
{ open: true, kind: "archive" as const, format: "zip" },
]) {
expect(
entry("recover_javascript_sources", status(), {
processCaptureEnabled: true,
javascriptRecoveryEnabled: true,
}),
entry("inspect_macho", status({ ...target, capabilities: [capability] })),
).toMatchObject({
available: true,
surface: "application",
reason: "unsupported_host",
remediation: capability.reason,
});
expect(entry("analyze_javascript_application", status())).toMatchObject({
available: true,
});
expect(entry("inspect_analysis_view", status())).toMatchObject({
available: true,
surface: "application",
});
});
}
expect(
entry(
"inspect_native_dispatch_metadata",
status({
capabilities: [
{ ...capability, operation: "inspect_native_dispatch_metadata" },
],
}),
).reason,
).toBe("target_required");
});
+1 -1
View File
@@ -352,7 +352,7 @@ const workflowAvailabilityFor = ({
: "provider_missing",
remediation:
policy.androidAnalysisAvailability?.reason ??
"Set REA_JADX_MCP_JAR to a caller-supplied jadx-headless-mcp 0.7.1 JAR and provide a full JDK on Linux or macOS.",
"Set REA_JADX_MCP_JAR to a caller-supplied jadx-headless-mcp 0.7.1 JAR and provide a full JDK on Linux, macOS, or Windows x64 with its matching bundled native controls.",
};
const browser = browserProviderAvailability(name, kind, policy);
if (browser !== null) return browser;
@@ -1,97 +0,0 @@
import { describe, expect, it } from "vitest";
import { parse as parseToml } from "smol-toml";
import {
clientConfigurationServersKey,
parseClientConfiguration,
serializeClientConfiguration,
} from "./ClientConfigurationDocument.js";
describe("JSON client configuration BOM handling", () => {
const format = "json" as const;
const serversKey = clientConfigurationServersKey(format);
it("reports malformed BOM-prefixed JSON at the original offset", () => {
const text = `\uFEFF{\r\n "${serversKey}": {"rea": @}\r\n}`;
expect(() => parseClientConfiguration(text, format)).toThrow(
new SyntaxError(
`Invalid JSON/JSONC at offset ${text.indexOf("@")}: InvalidSymbol`,
),
);
});
it.each([
["\uFEFF\uFEFF{}", 1],
[" \uFEFF{}", 1],
['{"setting":\uFEFFtrue}', 11],
['\uFEFF{"setting":\uFEFFtrue}', 12],
] as const)("rejects a nonleading BOM in %j", (text, offset) => {
expect(() => parseClientConfiguration(text, format)).toThrow(
new SyntaxError(`Invalid JSON/JSONC at offset ${offset}: InvalidSymbol`),
);
});
});
describe("TOML client configuration BOM handling", () => {
it.each(["", "\uFEFF"])("parses a document with prefix %j", (bom) => {
const text = '[mcp_servers.rea]\ncommand = "rea"\n';
expect(parseClientConfiguration(`${bom}${text}`, "toml").servers).toEqual({
rea: { command: "rea" },
});
});
});
describe("Codex TOML serialization", () => {
const unrelated = [
"# Keep this explanation.",
'notify = ["a", "b"]',
"literal = 'C:\\demo\\path'",
"",
].join("\n");
const rea = { command: "npx", args: ["-y", "rea-agents@6.1.0", "mcp"] };
const registered = `${unrelated}\n[mcp_servers.rea]\ncommand = "npx"\nargs = ["-y", "rea-agents@6.1.0", "mcp"]\n`;
const documentOf = (text: string): Record<string, unknown> =>
parseClientConfiguration(text, "toml").document;
const serialize = (document: Record<string, unknown>, original: string) =>
serializeClientConfiguration(document, "toml", original, [
["mcp_servers", "rea"],
]);
it("adds REA's table without rewriting comments or unrelated values", () => {
const document = { ...documentOf(unrelated), mcp_servers: { rea } };
const written = serialize(document, unrelated);
expect(written.startsWith(unrelated)).toBe(true);
expect(parseToml(written)).toEqual(document);
});
it("removes REA's table and leaves the rest of the file byte for byte", () => {
const document = { ...documentOf(registered), mcp_servers: {} };
expect(serialize(document, registered)).toBe(unrelated);
});
it("leaves a root disabled_mcp_servers list, which Codex does not read", () => {
const original = `# Codex ignores this list.\ndisabled_mcp_servers = ["rea"]\n`;
const document = { ...documentOf(original), mcp_servers: { rea } };
const written = serialize(document, original);
expect(written.startsWith(original)).toBe(true);
expect(parseToml(written)).toEqual(document);
});
it("rewrites the document when an edit would not hold the requested values", () => {
const document = {
...documentOf(unrelated),
notify: ["changed"],
mcp_servers: { rea },
};
const written = serialize(document, unrelated);
expect(written).not.toContain("# Keep this explanation.");
expect(parseToml(written)).toEqual(document);
});
});
@@ -1,52 +0,0 @@
import { expect, it } from "vitest";
import { PRODUCT_IDENTITY } from "../identity.js";
import {
isOwnedClientRegistrationCommand,
npxRegistrationCommand,
} from "./ClientRegistrationIdentity.js";
import { setupRegistrationCommand } from "./SetupHost.js";
it("uses a Windows executable for npm-run setup and preserves POSIX launchers", () => {
expect(setupRegistrationCommand("win32", true)).toEqual([
"cmd.exe",
"/d",
"/c",
"npx",
"-y",
PRODUCT_IDENTITY.registrationPackageSpecifier,
"mcp",
]);
for (const platform of ["linux", "darwin"] as const)
expect(setupRegistrationCommand(platform, true)).toEqual([
"npx",
"-y",
PRODUCT_IDENTITY.registrationPackageSpecifier,
"mcp",
]);
});
it.each(
[
npxRegistrationCommand("win32"),
["cmd", "/c", "npx", "-y", "rea-agents@5.0.0", "mcp"],
["npx", "-y", "rea-agents@5.0.0", "mcp"],
].map((command) => ({ command })),
)("recognizes owned current and legacy launchers: $command", ({ command }) => {
expect(isOwnedClientRegistrationCommand(command)).toBe(true);
});
it.each(
[
["cmd.exe", "/d", "/c", "node", "custom.js", "mcp"],
["cmd.exe", "/k", "npx", "-y", "rea-agents@5.0.0", "mcp"],
["cmd.exe", "/c", "npx -y rea-agents@5.0.0 mcp"],
["cmd.exe", "/c", "npx", "-y", "another-package", "mcp"],
["cmd.exe", "/c", "npx", "-y", "rea-agents@5.0.0", "mcp", "&", "other"],
["cmd.exe", "/c", "npx", "-y", "rea-agents@5.0.0 & other", "mcp"],
].map((command) => ({ command })),
)(
"does not claim custom shell commands as REA-owned: $command",
({ command }) => {
expect(isOwnedClientRegistrationCommand(command)).toBe(false);
},
);
+2 -11
View File
@@ -1,5 +1,4 @@
import type { ExecutableFormatHint } from "../domain/dosCom.js";
import { parseConfig } from "../config.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { EnhancedTools } from "./EnhancedTools.js";
import { executeFunctionAnalysisEvidence } from "./FunctionAnalysisEvidence.js";
@@ -132,7 +131,7 @@ export const runProviderAnalysis = async (
/** Execute managed metadata inspection in an isolated managed-only session. */
export const runManagedProviderExecution = async (
dependencies: DirectAnalysisDependencies,
dependencies: Pick<DirectAnalysisDependencies, "createManagedBinarySession">,
path: string,
tool: ManagedToolName,
signal?: AbortSignal,
@@ -189,18 +188,10 @@ const runAnalysis = async (
readonly signal: AbortSignal;
readonly providerId?: AnalysisProviderSelector;
readonly formatHint?: ExecutableFormatHint;
/**
* Environment the configuration is read from. Defaults to the process
* environment so existing callers are unchanged, but a caller may supply
* one — which is what lets the MCP path's injected environment reach this
* code, and what makes configuration-driven behaviour testable without
* mutating `process.env`.
*/
readonly environment?: Readonly<Record<string, string | undefined>>;
},
): Promise<JsonValue> => {
const { logger, signal, snapshotPath } = options;
const config = parseConfig(options.environment ?? process.env);
const config = dependencies.readConfiguration();
if (!config.ok) return cliError(config.error);
const session = dependencies.createBinarySession(config.value, logger);
return withSessionCleanup(
@@ -1,9 +1,11 @@
import type { AppConfig } from "../config.js";
import type { AppConfig, parseConfig } from "../config.js";
import type { Logger } from "../logger.js";
import type { BinarySession } from "./binary/BinarySession.js";
/** Existing one-shot session factories supplied by the production boundary. */
/** Configuration and one-shot session factories supplied by the production boundary. */
export interface DirectAnalysisDependencies {
/** Read the caller-selected configuration without consulting ambient state. */
readonly readConfiguration: () => ReturnType<typeof parseConfig>;
readonly createBinarySession: (
config: AppConfig,
logger: Logger,
+15 -10
View File
@@ -1,4 +1,3 @@
import { parseConfig } from "../config.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { jsonObjectSchema, type JsonValue } from "../domain/jsonValue.js";
import { createServerIdentity } from "../serverIdentity.js";
@@ -6,11 +5,13 @@ import { silentLogger, type Logger } from "../logger.js";
import type { DirectAnalysisDependencies } from "./DirectAnalysisDependencies.js";
const runSessionStatus = async (
dependencies: Pick<DirectAnalysisDependencies, "createBinarySession">,
dependencies: Pick<
DirectAnalysisDependencies,
"createBinarySession" | "readConfiguration"
>,
logger: Logger = silentLogger,
environment: Readonly<Record<string, string | undefined>> = process.env,
): Promise<JsonValue> => {
const config = parseConfig(environment);
const config = dependencies.readConfiguration();
if (!config.ok) return { error: projectAnalysisError(config.error) };
const session = dependencies.createBinarySession(config.value, logger);
try {
@@ -27,14 +28,18 @@ const runSessionStatus = async (
/** List binary-session provider candidates and auxiliary operation availability. */
export const runProviderStatus = (
dependencies: Pick<DirectAnalysisDependencies, "createBinarySession">,
dependencies: Pick<
DirectAnalysisDependencies,
"createBinarySession" | "readConfiguration"
>,
logger: Logger = silentLogger,
environment: Readonly<Record<string, string | undefined>> = process.env,
) => runSessionStatus(dependencies, logger, environment);
) => runSessionStatus(dependencies, logger);
/** List binary-session operation descriptors; this is not the full MCP catalog. */
export const runCapabilityStatus = (
dependencies: Pick<DirectAnalysisDependencies, "createBinarySession">,
dependencies: Pick<
DirectAnalysisDependencies,
"createBinarySession" | "readConfiguration"
>,
logger: Logger = silentLogger,
environment: Readonly<Record<string, string | undefined>> = process.env,
) => runSessionStatus(dependencies, logger, environment);
) => runSessionStatus(dependencies, logger);
+1
View File
@@ -7,6 +7,7 @@ export const createDoctorHostFixture = (
overrides: Partial<DoctorHost> = {},
): DoctorHost => ({
platform: "darwin",
homeDirectory: "/fixture/home",
architecture: "x64",
nodeVersion: "24.18.0",
macosVersion: () => Promise.resolve("14.0"),
+10 -27
View File
@@ -1,7 +1,7 @@
import { constants } from "node:fs";
import { access, readFile, readdir } from "node:fs/promises";
import { homedir } from "node:os";
import { delimiter, join } from "node:path";
import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
import { join } from "node:path";
import { analysisErrorRemediationAction } from "../domain/analysisErrorPresentation.js";
import { parseBinaryTarget } from "./BinaryTargetResolver.js";
@@ -76,7 +76,7 @@ export interface DoctorHost {
readonly platform: NodeJS.Platform;
readonly architecture: NodeJS.Architecture;
readonly nodeVersion: string;
readonly homeDirectory?: string;
readonly homeDirectory: string;
readonly configuredHopperPath?: string;
readonly configuredIlspyCmdPath?: string;
macosVersion(): Promise<string | undefined>;
@@ -287,21 +287,6 @@ const installationState = (
): DoctorIdentity["installations"]["state"] =>
paths.length === 0 ? "unknown" : paths.length === 1 ? "single" : "multiple";
const homeFromEnvironment = (
environment: NodeJS.ProcessEnv,
platform: NodeJS.Platform,
): string => {
const selected =
platform === "win32"
? (environment.USERPROFILE ??
(environment.HOMEDRIVE !== undefined &&
environment.HOMEPATH !== undefined
? `${environment.HOMEDRIVE}${environment.HOMEPATH}`
: environment.HOME))
: (environment.HOME ?? environment.USERPROFILE);
return selected ?? homedir();
};
/** Optional outer-adapter diagnostics composed without reversing dependencies. */
export interface SystemDoctorHostOptions {
readonly platform?: NodeJS.Platform;
@@ -322,7 +307,7 @@ export const systemDoctorHost = (
const architecture = options.architecture ?? process.arch;
const environment = options.environment ?? process.env;
const hostExecFileOutput = options.execFileOutput ?? execFileOutput;
const homeDirectory = homeFromEnvironment(environment, platform);
const homeDirectory = homeDirectoryFromEnvironment(environment, platform);
const commandEnvironment = { env: environment };
return {
platform,
@@ -451,8 +436,8 @@ export const systemDoctorHost = (
};
const readMacosVersion = async (
run: typeof execFileOutput = execFileOutput,
options: { readonly env: NodeJS.ProcessEnv } = { env: process.env },
run: typeof execFileOutput,
options: { readonly env: NodeJS.ProcessEnv },
): Promise<string | undefined> => {
try {
return (await run("sw_vers", ["-productVersion"], options)).stdout.trim();
@@ -465,9 +450,9 @@ const readMacosVersion = async (
const executableAvailable = async (
path: string,
platform: NodeJS.Platform = process.platform,
run: typeof execFileOutput = execFileOutput,
options: { readonly env: NodeJS.ProcessEnv } = { env: process.env },
platform: NodeJS.Platform,
run: typeof execFileOutput,
options: { readonly env: NodeJS.ProcessEnv },
): Promise<boolean> => {
try {
await access(path, constants.X_OK);
@@ -490,9 +475,7 @@ const uncomposedLinuxDemoRuntimeCheck = (): Promise<DoctorCheck> =>
remediation: "Run rea doctor through the production CLI adapter.",
});
const manualHopperPaths = async (
home: string = homedir(),
): Promise<readonly string[]> => {
const manualHopperPaths = async (home: string): Promise<readonly string[]> => {
const paths: string[] = [];
for (const root of ["/Applications", join(home, "Applications")]) {
try {
+1 -3
View File
@@ -1,5 +1,3 @@
import { homedir } from "node:os";
import {
SUPPORTED_NODE_VERSION_PROSE,
supportsNodeVersion,
@@ -126,7 +124,7 @@ const findHopper = async (host: DoctorHost): Promise<string | undefined> => {
? [
DEFAULT_HOPPER,
SYSTEM_LINUX_HOPPER,
linuxHopperLauncherPath(host.homeDirectory ?? homedir()),
linuxHopperLauncherPath(host.homeDirectory),
...(await host.manualHopperPaths()),
]
: [host.configuredHopperPath];
@@ -1,8 +1,6 @@
import { describe, expect, it } from "vitest";
import { evidenceInputSchema } from "../contracts/evidenceInputContracts.js";
import { JAVASCRIPT_FEATURE_TRACE_EXAMPLE } from "../contracts/javascript/javascriptApplicationWorkflowExamples.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { EvidenceLedger } from "./investigation/EvidenceLedger.js";
import { resolveEvidenceInput } from "./EvidenceInputResolver.js";
const evidence = JAVASCRIPT_FEATURE_TRACE_EXAMPLE.application;
@@ -12,24 +10,6 @@ const reference = {
};
describe("exact Evidence input resolution", () => {
it("uses the session's detached canonical record without modifying it", () => {
const ledger = new EvidenceLedger();
expect(ledger.record(evidence).ok).toBe(true);
const result = resolveEvidenceInput(reference, (id) => ledger.get(id));
if (!result.ok) throw result.error;
expect(result.value).toEqual(evidence);
result.value.limitations.push("caller-owned change");
expect(ledger.get(evidence.evidence_id)).toEqual(evidence);
});
it("leaves portable inline inputs independent of session lookup", () => {
expect(
resolveEvidenceInput(evidence, () => {
throw new Error("unexpected lookup");
}),
).toEqual({ ok: true, value: evidence });
});
it("reports a missing reference and an available recovery", () => {
for (const lookup of [undefined, () => undefined]) {
const result = resolveEvidenceInput(reference, lookup);
@@ -64,17 +44,4 @@ describe("exact Evidence input resolution", () => {
},
});
});
it("parses only complete inline records or strict exact references", () => {
expect(evidenceInputSchema.safeParse(reference).success).toBe(true);
expect(evidenceInputSchema.safeParse(evidence).success).toBe(true);
for (const invalid of [
{ evidence_id: evidence.evidence_id },
{ ...reference, kind: "another-session" },
{ ...reference, evidence_id: "ev_short" },
{ ...reference, session_id: "foreign" },
{ ...reference, normalized_result: {} },
])
expect(evidenceInputSchema.safeParse(invalid).success).toBe(false);
});
});
+12 -5
View File
@@ -177,7 +177,7 @@ export const readLinuxDistribution = async (): Promise<
/** Download, verify, install, and read back the official Hopper Linux package. */
export const installLinuxHopper = async (
host: LinuxHopperInstallHost = systemLinuxHopperInstallHost(),
host: LinuxHopperInstallHost = systemLinuxHopperInstallHost(process.env),
options: {
readonly signal?: AbortSignal;
readonly releases?: Readonly<
@@ -225,7 +225,10 @@ export const installLinuxHopper = async (
export const linuxHopperLauncherPath = (home: string): string =>
join(home, ".local/share/rea/hopper/bin/Hopper");
const systemLinuxHopperInstallHost = (): LinuxHopperInstallHost => ({
/** Compose package-manager and linker checks from the selected caller environment. */
export const systemLinuxHopperInstallHost = (
environment: Readonly<NodeJS.ProcessEnv>,
): LinuxHopperInstallHost => ({
distribution: readLinuxDistribution,
async download(url, options) {
const response = await fetch(url, {
@@ -239,11 +242,12 @@ const systemLinuxHopperInstallHost = (): LinuxHopperInstallHost => ({
},
createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-")),
writeArchive: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
installPackage: installSystemPackage,
installPackage: (family, archive) =>
installSystemPackage(family, archive, environment),
async launcherStatus(path) {
try {
await access(path);
const linked = await execFileOutput("ldd", [path]);
const linked = await execFileOutput("ldd", [path], { env: environment });
if (!linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`))
return "runtime_dependencies";
return (await linuxHopperBinarySupported(path))
@@ -284,6 +288,7 @@ export const linuxSharedLibrariesAvailable = (output: string): boolean =>
const installSystemPackage = async (
family: LinuxPackageFamily,
archive: string,
environment: Readonly<NodeJS.ProcessEnv>,
): Promise<boolean> => {
try {
for (const command of linuxPackageManagerCommands(
@@ -291,7 +296,9 @@ const installSystemPackage = async (
archive,
process.getuid?.() === 0,
))
await execFileAsync(command.executable, command.args);
await execFileAsync(command.executable, command.args, {
env: environment,
});
return true;
} catch (cause: unknown) {
// Package-manager failure is reported by the false return.
+49 -28
View File
@@ -9,11 +9,12 @@ import {
rm,
writeFile,
} from "node:fs/promises";
import { homedir, tmpdir } from "node:os";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { promisify } from "node:util";
import { z } from "zod";
import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
const execFileAsync = promisify(execFile);
const RELEASES_URL =
@@ -77,7 +78,10 @@ export interface MacHopperInstallHost {
/** Download, verify, and install Hopper into the current user's Applications directory. */
export const installMacHopper = async (
options: { readonly replaceExisting?: boolean } = {},
host: MacHopperInstallHost = systemMacHopperInstallHost(),
host: MacHopperInstallHost = systemMacHopperInstallHost(
homeDirectoryFromEnvironment(process.env, process.platform),
process.env,
),
): Promise<MacHopperInstallResult> => {
let temporary: string | undefined;
let mounted = false;
@@ -133,23 +137,35 @@ export const installMacHopper = async (
}
};
const systemMacHopperInstallHost = (): MacHopperInstallHost => ({
/** Compose installer paths and subprocesses from one selected caller context. */
export const systemMacHopperInstallHost = (
homeDirectory: string,
environment: Readonly<NodeJS.ProcessEnv>,
): MacHopperInstallHost => ({
download: downloadPackage,
createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-mac-")),
createMountDirectory: (path) => mkdir(path),
writePackage: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
async mount(packagePath, mountPath) {
return commandSucceeds("hdiutil", [
"attach",
"-readonly",
"-nobrowse",
"-mountpoint",
mountPath,
packagePath,
]);
return commandSucceeds(
"hdiutil",
[
"attach",
"-readonly",
"-nobrowse",
"-mountpoint",
mountPath,
packagePath,
],
environment,
);
},
async unmount(mountPath) {
await commandSucceeds("hdiutil", ["detach", mountPath, "-force"]);
await commandSucceeds(
"hdiutil",
["detach", mountPath, "-force"],
environment,
);
},
async appBundle(mountPath) {
const entries = await readdir(mountPath, { withFileTypes: true });
@@ -160,21 +176,24 @@ const systemMacHopperInstallHost = (): MacHopperInstallHost => ({
},
async validBundle(appPath) {
if (
!(await commandSucceeds("codesign", [
"--verify",
"--deep",
"--strict",
appPath,
]))
!(await commandSucceeds(
"codesign",
["--verify", "--deep", "--strict", appPath],
environment,
))
)
return false;
try {
const identifier = (
await execFileAsync("/usr/libexec/PlistBuddy", [
"-c",
"Print :CFBundleIdentifier",
join(appPath, "Contents/Info.plist"),
])
await execFileAsync(
"/usr/libexec/PlistBuddy",
[
"-c",
"Print :CFBundleIdentifier",
join(appPath, "Contents/Info.plist"),
],
{ env: environment },
)
).stdout.trim();
return identifier === BUNDLE_IDENTIFIER;
} catch (cause: unknown) {
@@ -196,10 +215,10 @@ const systemMacHopperInstallHost = (): MacHopperInstallHost => ({
async installBundle(source, destination, stage, replaceExisting) {
const previous = `${stage}-previous`;
try {
await mkdir(join(homedir(), "Applications"), { recursive: true });
await mkdir(join(homeDirectory, "Applications"), { recursive: true });
await rm(stage, { recursive: true, force: true });
await rm(previous, { recursive: true, force: true });
await execFileAsync("ditto", [source, stage]);
await execFileAsync("ditto", [source, stage], { env: environment });
await access(join(stage, "Contents/MacOS/hopper"));
if (replaceExisting) await rename(destination, previous);
await rename(stage, destination);
@@ -231,10 +250,11 @@ const systemMacHopperInstallHost = (): MacHopperInstallHost => ({
}
},
async openApplication(path) {
await execFileAsync("open", [path]);
await execFileAsync("open", [path], { env: environment });
},
cleanup: (path) => rm(path, { recursive: true, force: true }),
destination: () => join(homedir(), "Applications/Hopper Disassembler.app"),
destination: () =>
join(homeDirectory, "Applications/Hopper Disassembler.app"),
});
const downloadPackage = async (url: string) => {
@@ -260,9 +280,10 @@ const integrityMatches = (
const commandSucceeds = async (
command: string,
args: readonly string[],
environment: Readonly<NodeJS.ProcessEnv>,
): Promise<boolean> => {
try {
await execFileAsync(command, args);
await execFileAsync(command, args, { env: environment });
return true;
} catch (cause: unknown) {
// best-effort cleanup: optional command probing; failure means unavailable.
-51
View File
@@ -1,51 +0,0 @@
import { describe, expect, it } from "vitest";
import { createProgressReporter } from "./ProgressReporter.js";
describe("progress reporter", () => {
it("preserves monotonic order, rate bounds intermediate updates, and always emits terminal state", async () => {
let now = 0;
const observed: unknown[] = [];
const reporter = createProgressReporter(
(update) => {
observed.push(update);
return Promise.resolve();
},
{ minimumIntervalMs: 100, now: () => now },
);
await reporter.report({
phase: "scan",
completed: 0,
total: 3,
message: "start",
});
now = 10;
await reporter.report({
phase: "scan",
completed: 1,
total: 3,
message: "one",
});
now = 20;
await reporter.report({
phase: "scan",
completed: 3,
total: 3,
message: "done",
terminal: true,
});
expect(observed).toEqual([
expect.objectContaining({ sequence: 1, completed: 0 }),
expect.objectContaining({ sequence: 2, completed: 3, terminal: true }),
]);
await expect(
reporter.report({
phase: "scan",
completed: 2,
total: 3,
message: "back",
}),
).rejects.toThrow(/backwards/u);
});
});
-17
View File
@@ -12,23 +12,6 @@ export const firstProcedureAddress = (input: unknown): string => {
return first.address;
};
/** Reject two target paths that resolve to the same binary content. */
export const requireDistinctTargetHashes = (
firstHash: unknown,
secondHash: unknown,
): void => {
if (
typeof firstHash !== "string" ||
typeof secondHash !== "string" ||
firstHash.length === 0 ||
secondHash.length === 0
) {
throw new TypeError("Target hashes must be non-empty strings");
}
if (firstHash === secondHash)
throw new TypeError("Real-Hopper verification requires distinct binaries");
};
/** Reject empty and success-shaped embedded decompilation failures. */
export const requirePseudocode = (
input: unknown,
+1 -1
View File
@@ -253,7 +253,7 @@ describe("setup workflow action selection", () => {
expect(result.status).toBe("ready");
expect(host.configuredCommands).toEqual([
setupRegistrationCommand("win32"),
setupRegistrationCommand("win32", false),
]);
expect(setupRegistrationCommand("win32", false)).toEqual([
process.execPath,
-26
View File
@@ -1,26 +0,0 @@
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { detectClients } from "./SetupHost.js";
describe("setup client discovery", () => {
let temporaryHome: string | undefined;
afterEach(async () => {
if (temporaryHome !== undefined)
await rm(temporaryHome, { recursive: true, force: true });
temporaryHome = undefined;
});
it("detects an existing config even when the marker directory is absent", async () => {
temporaryHome = await mkdtemp(join(tmpdir(), "rea-setup-discovery-"));
await writeFile(join(temporaryHome, ".claude.json"), "{}\n");
expect(
(await detectClients(temporaryHome)).map(({ name }) => name),
).toContain("claude_code");
});
});
+8 -7
View File
@@ -12,10 +12,13 @@ import type { LinuxDistribution } from "./LinuxHopper.js";
import { PRODUCT_IDENTITY, SDK_IDENTITY } from "../identity.js";
import { CATALOG_IDENTITY } from "../catalogIdentity.js";
import type { ClientRegistrationStatus } from "./ClientRegistrationStatus.js";
import { setupRegistrationCommand } from "./SetupHost.js";
/** Recording setup host for service-level planning and recovery tests. */
export class FakeSetupHost implements SetupHost {
readonly platform: NodeJS.Platform;
readonly homeDirectory = "/fixture/home";
readonly registrationCommand: readonly string[];
nodeVersion = "24.18.0";
version: string | undefined = "14.5";
distribution: LinuxDistribution | undefined;
@@ -45,26 +48,24 @@ export class FakeSetupHost implements SetupHost {
constructor(platform: NodeJS.Platform = "darwin") {
this.platform = platform;
this.registrationCommand = setupRegistrationCommand(platform, false);
}
macosVersion = (): Promise<string | undefined> =>
Promise.resolve(this.version);
linuxDistribution = (): Promise<LinuxDistribution | undefined> =>
Promise.resolve(this.distribution);
hopperPath = (): Promise<string | undefined> => Promise.resolve(this.hopper);
initialSetupState = async (scope?: DoctorScope) => ({
...(this.hopper === undefined ? {} : { hopperPath: this.hopper }),
providerEnvironment: await this.providerEnvironment(),
doctor: await this.doctor(scope),
});
providerEnvironment = (): Promise<SetupProviderEnvironment> =>
Promise.resolve({
providerEnvironment: {
...(this.hopper === undefined
? {}
: { HOPPER_LAUNCHER_PATH: this.hopper }),
...(this.ghidra === undefined ? {} : { GHIDRA_INSTALL_DIR: this.ghidra }),
...(this.javaHome === undefined ? {} : { JAVA_HOME: this.javaHome }),
});
},
doctor: await this.doctor(scope),
});
installHopper = (
replaceExisting: boolean,
): Promise<SetupHopperInstallResult> => {
@@ -5,12 +5,6 @@ import { FakeSetupHost, options } from "./Setup.fixture.js";
it("uses the shared initial host snapshot for setup planning", async () => {
const host = new FakeSetupHost();
host.hopperPath = () => {
throw new Error("setup snapshot should provide the Hopper path");
};
host.providerEnvironment = () => {
throw new Error("setup snapshot should provide provider settings");
};
host.initialSetupState = async (scope) => ({
hopperPath: "/snapshot/Hopper",
providerEnvironment: { HOPPER_LAUNCHER_PATH: "/snapshot/Hopper" },
+7 -19
View File
@@ -21,8 +21,6 @@ import { discoverSetupState, planSetupActions } from "./SetupPlan.js";
import {
filterClientsNeedingConfigure,
hostRemediation,
initialProviderEnvironment,
setupRegistrationCommand,
systemSetupHost,
} from "./SetupHost.js";
@@ -45,25 +43,15 @@ export const runSetup = async (
);
const unsupported = await hostRemediation(host, false);
if (unsupported !== undefined) return fail(unsupported);
const initialState = await host.initialSetupState?.(options.readinessScope);
let hopperPath =
initialState === undefined
? await host.hopperPath()
: initialState.hopperPath;
let providerEnvironment =
initialState === undefined
? await initialProviderEnvironment(host, hopperPath)
: initialState.providerEnvironment;
const initialState = await host.initialSetupState(options.readinessScope);
let { hopperPath, providerEnvironment } = initialState;
const discovery = await discoverSetupState({
host,
providerEnvironment,
forceHopperInstall: options.installHopper,
proposeHopper:
options.proposeHopper ?? (confirm !== undefined && !options.structured),
doctorScope: options.readinessScope,
...(initialState === undefined
? {}
: { initialDoctor: initialState.doctor }),
initialDoctor: initialState.doctor,
});
clientStates = discovery.clientStates;
const clientSelectionAllowed =
@@ -91,7 +79,7 @@ export const runSetup = async (
discovery,
host,
providerEnvironment,
command: setupRegistrationCommand(host.platform),
command: host.registrationCommand,
clientIds: [],
installSkill: offerSkillAction,
});
@@ -143,7 +131,7 @@ export const runSetup = async (
discovery: planDiscovery,
host,
providerEnvironment,
command: setupRegistrationCommand(host.platform),
command: host.registrationCommand,
clientIds: selectedClientIds,
installSkill,
});
@@ -241,7 +229,7 @@ export const runSetup = async (
host,
detectedClients: selectedClients,
providerEnvironment,
command: setupRegistrationCommand(host.platform),
command: host.registrationCommand,
clients,
appliedActions,
...(options.onProgress === undefined
@@ -333,7 +321,7 @@ const installHopperAction = async (input: {
input.host,
input.selectedClients,
providerEnvironment,
setupRegistrationCommand(input.host.platform),
input.host.registrationCommand,
),
};
};
+29 -30
View File
@@ -1,5 +1,4 @@
import { access } from "node:fs/promises";
import { homedir } from "node:os";
import { resolve } from "node:path";
import { PRODUCT_IDENTITY } from "../identity.js";
@@ -9,8 +8,12 @@ import {
supportsNodeVersion,
} from "../domain/runtimeVersion.js";
import { runDoctor, systemDoctorHost, type DoctorHost } from "./Doctor.js";
import { installLinuxHopper, readLinuxDistribution } from "./LinuxHopper.js";
import { installMacHopper } from "./MacHopper.js";
import {
installLinuxHopper,
readLinuxDistribution,
systemLinuxHopperInstallHost,
} from "./LinuxHopper.js";
import { installMacHopper, systemMacHopperInstallHost } from "./MacHopper.js";
import { supportedClients, type SetupClient } from "./SupportedClients.js";
import {
canonicalSkillNeedsInstall,
@@ -33,7 +36,7 @@ import type { DoctorScope } from "./Doctor.js";
/** Resolve the executable and arguments used in a managed MCP registration. */
export const setupRegistrationCommand = (
platform: NodeJS.Platform,
useNpmRunner: boolean = process.env.npm_command === "exec",
useNpmRunner: boolean,
): readonly string[] =>
useNpmRunner
? npxRegistrationCommand(platform)
@@ -59,14 +62,6 @@ export const filterClientsNeedingConfigure = async (
return detectedClients.filter((_, index) => needs[index]);
};
export const initialProviderEnvironment = async (
host: SetupHost,
hopperPath: string | undefined,
): Promise<SetupProviderEnvironment> => ({
...(await host.providerEnvironment?.()),
...(hopperPath === undefined ? {} : { HOPPER_LAUNCHER_PATH: hopperPath }),
});
export const hostRemediation = async (
host: SetupHost,
installHopper: boolean,
@@ -88,15 +83,22 @@ export const hostRemediation = async (
/** Production setup effects for Hopper, agent configuration, and the canonical skill directory. */
export const systemSetupHost = (
doctorHost: DoctorHost = systemDoctorHost(),
selectedDoctorHost: DoctorHost | undefined = undefined,
environment: Readonly<NodeJS.ProcessEnv> = process.env,
): SetupHost => {
const doctorHost = selectedDoctorHost ?? systemDoctorHost({ environment });
const platform = doctorHost.platform;
const { homeDirectory } = doctorHost;
return {
platform,
homeDirectory,
registrationCommand: setupRegistrationCommand(
platform,
environment.npm_command === "exec",
),
nodeVersion: process.versions.node,
macosVersion: () => doctorHost.macosVersion(),
linuxDistribution: readLinuxDistribution,
hopperPath: async () => (await runDoctor(undefined, doctorHost)).hopperPath,
initialSetupState: async (
scope?: DoctorScope,
): Promise<SetupInitialState> => {
@@ -116,25 +118,20 @@ export const systemSetupHost = (
doctor: diagnosis,
};
},
providerEnvironment: async () => {
const diagnosis = await runDoctor(undefined, doctorHost);
return {
...providerRegistrationEnvironment(diagnosis.providerInspections ?? []),
...(diagnosis.hopperPath === undefined
? {}
: { HOPPER_LAUNCHER_PATH: diagnosis.hopperPath }),
};
},
installHopper: async (replaceExisting) => {
const result =
platform === "linux"
? await installLinuxHopper()
: await installMacHopper({ replaceExisting });
? await installLinuxHopper(systemLinuxHopperInstallHost(environment))
: await installMacHopper(
{ replaceExisting },
systemMacHopperInstallHost(homeDirectory, environment),
);
if (result.status === "installed") return result;
return setupInstallFailure(result.reason);
},
detectedClients: () => detectClients(homedir()),
supportedClients: () => Promise.resolve(supportedClients(homedir())),
detectedClients: () => detectClients(homeDirectory, platform, environment),
supportedClients: () =>
Promise.resolve(supportedClients(homeDirectory, platform, environment)),
configureClient: (client, providerEnvironment, command) =>
client.format === "unsupported"
? Promise.resolve({ status: "skipped" })
@@ -146,8 +143,8 @@ export const systemSetupHost = (
(aligned) => !aligned,
),
inspectClientConfiguration: inspectClientConfiguration,
skillNeedsInstall: () => canonicalSkillNeedsInstall(homedir()),
installSkill: () => installCanonicalSkill(homedir()),
skillNeedsInstall: () => canonicalSkillNeedsInstall(homeDirectory),
installSkill: () => installCanonicalSkill(homeDirectory),
doctor: (scope) => runDoctor(undefined, doctorHost, scope),
};
};
@@ -155,9 +152,11 @@ export const systemSetupHost = (
/** Detect supported agents from their config files or stable installation markers. */
export const detectClients = async (
home: string,
platform: NodeJS.Platform = process.platform,
environment: Readonly<NodeJS.ProcessEnv> = process.env,
): Promise<readonly SetupClient[]> => {
const detected: SetupClient[] = [];
for (const candidate of supportedClients(home)) {
for (const candidate of supportedClients(home, platform, environment)) {
const [hasConfig, hasMarker] = await Promise.all([
exists(candidate.configPath),
candidate.markerPath === undefined ? false : exists(candidate.markerPath),
+19 -15
View File
@@ -1,4 +1,3 @@
import { homedir } from "node:os";
import { join } from "node:path";
import { PRODUCT_IDENTITY } from "../identity.js";
@@ -15,7 +14,6 @@ import type {
SetupProviderEnvironment,
} from "./SetupTypes.js";
import type { SetupClient } from "./SupportedClients.js";
import type { DoctorScope } from "./Doctor.js";
import type { DoctorReport } from "./Doctor.js";
/** Read-only setup facts shared by client selection and preflight. */
@@ -36,11 +34,9 @@ export const discoverSetupState = async (input: {
readonly providerEnvironment: SetupProviderEnvironment;
readonly forceHopperInstall: boolean;
readonly proposeHopper: boolean;
readonly doctorScope: DoctorScope | undefined;
readonly initialDoctor?: DoctorReport;
readonly initialDoctor: DoctorReport;
}): Promise<SetupDiscovery> => {
const initialDoctor =
input.initialDoctor ?? (await input.host.doctor(input.doctorScope));
const { initialDoctor } = input;
const linuxHopperRepairNeeded = initialDoctor.checks.some(
({ name, ok, detail }) =>
!ok &&
@@ -62,7 +58,7 @@ export const discoverSetupState = async (input: {
(Object.keys(input.providerEnvironment).length === 0 ||
linuxHopperRepairNeeded));
const [clients, detectedClients, skillNeedsInstall] = await Promise.all([
input.host.supportedClients?.() ?? input.host.detectedClients(),
input.host.supportedClients(),
input.host.detectedClients(),
input.host.skillNeedsInstall(),
]);
@@ -148,12 +144,11 @@ export const planSetupActions = async (input: {
const inspections = await Promise.all(
selectedClients.map(async (client) => ({
client,
inspection:
(await input.host.inspectClientConfiguration?.(
client,
input.providerEnvironment,
input.command,
)) ?? ({ status: "update" } as const),
inspection: await input.host.inspectClientConfiguration(
client,
input.providerEnvironment,
input.command,
),
})),
);
const invalid = inspections.find(
@@ -191,6 +186,7 @@ export const planSetupActions = async (input: {
return {
plannedActions: setupPlan({
platform: input.host.platform,
homeDirectory: input.host.homeDirectory,
installHopper: input.discovery.installHopper,
installSkill: input.installSkill,
clients: clientPlans,
@@ -210,6 +206,7 @@ export const planSetupActions = async (input: {
/** Describe every selected setup mutation before user approval. */
const setupPlan = (input: {
readonly platform: NodeJS.Platform;
readonly homeDirectory: string;
readonly installHopper: boolean;
readonly installSkill: boolean;
readonly clients: readonly {
@@ -229,7 +226,10 @@ const setupPlan = (input: {
label: "Hopper deep-analysis provider",
target:
input.platform === "darwin"
? join(homedir(), "Applications/Hopper Disassembler.app")
? join(
input.homeDirectory,
"Applications/Hopper Disassembler.app",
)
: "system package manager",
detail:
input.platform === "linux"
@@ -271,7 +271,11 @@ const setupPlan = (input: {
id: "install_skill",
kind: "install_skill" as const,
label: "REA reverse-engineering skill",
target: join(homedir(), ".agents/skills", PRODUCT_IDENTITY.skillName),
target: join(
input.homeDirectory,
".agents/skills",
PRODUCT_IDENTITY.skillName,
),
detail:
"Install or update the bundled REA reverse-engineering skill and on-demand references.",
external: false,
+5 -5
View File
@@ -41,15 +41,15 @@ export type ClientConfigurationInspection =
/** Effects required by the idempotent, non-blocking setup workflow. */
export interface SetupHost {
readonly platform: NodeJS.Platform;
readonly homeDirectory: string;
readonly registrationCommand: readonly string[];
readonly nodeVersion: string;
macosVersion(): Promise<string | undefined>;
linuxDistribution(): Promise<LinuxDistribution | undefined>;
hopperPath(): Promise<string | undefined>;
initialSetupState?(scope?: DoctorScope): Promise<SetupInitialState>;
initialSetupState(scope?: DoctorScope): Promise<SetupInitialState>;
installHopper(replaceExisting: boolean): Promise<SetupHopperInstallResult>;
providerEnvironment?(): Promise<SetupProviderEnvironment>;
detectedClients(): Promise<readonly SetupClient[]>;
supportedClients?(): Promise<readonly SetupClient[]>;
supportedClients(): Promise<readonly SetupClient[]>;
configureClient(
client: SetupClient,
providerEnvironment: SetupProviderEnvironment,
@@ -60,7 +60,7 @@ export interface SetupHost {
providerEnvironment: SetupProviderEnvironment,
command: readonly string[],
): Promise<boolean>;
inspectClientConfiguration?(
inspectClientConfiguration(
client: SetupClient,
providerEnvironment: SetupProviderEnvironment,
command: readonly string[],
+24 -17
View File
@@ -8,7 +8,7 @@ import {
} from "./ClientConfigurationDocument.js";
import { copyFile, lstat, readFile, realpath, rm } from "node:fs/promises";
import { constants as fsConstants } from "node:fs";
import { homedir } from "node:os";
import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
import { join } from "node:path";
import writeFileAtomic from "write-file-atomic";
@@ -161,23 +161,30 @@ const removeAll = async (
/** Create uninstall effects contained to detected client configs and REA-owned paths. */
export const systemUninstallHost = (
home = homedir(),
selectedHome: string | undefined = undefined,
fileSystem: UninstallFileSystem = systemFileSystem,
): UninstallHost => ({
clients: () => Promise.resolve(supportedClients(home)),
inspectClient: async (client) => {
const read = await readClientConfiguration(client, fileSystem);
return read.kind === "item" && read.item.status === "failed"
? read.item
: undefined;
},
removeClient: (client) => removeClient(client, fileSystem),
removeSkill: () => removeManagedSkills(home, fileSystem),
purgeData: async () => [
await removeManagedPath(join(home, ".rea/cache"), "cache", fileSystem),
await removeManagedPath(join(home, ".rea/state"), "state", fileSystem),
],
});
environment: Readonly<NodeJS.ProcessEnv> = process.env,
platform: NodeJS.Platform = process.platform,
): UninstallHost => {
const home =
selectedHome ?? homeDirectoryFromEnvironment(environment, platform);
return {
clients: () =>
Promise.resolve(supportedClients(home, platform, environment)),
inspectClient: async (client) => {
const read = await readClientConfiguration(client, fileSystem);
return read.kind === "item" && read.item.status === "failed"
? read.item
: undefined;
},
removeClient: (client) => removeClient(client, fileSystem),
removeSkill: () => removeManagedSkills(home, fileSystem),
purgeData: async () => [
await removeManagedPath(join(home, ".rea/cache"), "cache", fileSystem),
await removeManagedPath(join(home, ".rea/state"), "state", fileSystem),
],
};
};
type ClientConfigurationRead =
| { readonly kind: "item"; readonly item: UninstallItem }
+7 -3
View File
@@ -51,9 +51,12 @@ const setupPlanSchema = z.object({
export const existingMaintenanceScope = async (
home: string,
entryPoint: string,
environment: Readonly<NodeJS.ProcessEnv>,
): Promise<MaintenanceScope> => {
const registrations = await readClientRegistrationStatuses(home, entryPoint);
const supported = supportedClients(home);
const registrations = await readClientRegistrationStatuses(home, entryPoint, {
environment,
});
const supported = supportedClients(home, process.platform, environment);
const clients: string[] = [];
for (const registration of registrations) {
if (
@@ -96,10 +99,11 @@ export const existingMaintenanceScope = async (
export const planIntegrationMaintenance = async (
home: string,
entryPoint: string,
environment: Readonly<NodeJS.ProcessEnv>,
execute: (command: readonly string[]) => Promise<Result<string, string>>,
): Promise<IntegrationMaintenance> => {
try {
const scope = await existingMaintenanceScope(home, entryPoint);
const scope = await existingMaintenanceScope(home, entryPoint, environment);
if (scope.clients.length === 0 && !scope.skill)
return { status: "current", plannedActions: [] };
const command = [
+27 -14
View File
@@ -1,5 +1,5 @@
import { realpath } from "node:fs/promises";
import { homedir } from "node:os";
import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
import { basename, dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import spawn from "cross-spawn";
@@ -26,6 +26,7 @@ export interface NpmInstallationHost {
/** Run an updater subprocess with complete diagnostics and isolated machine output. */
export const runUpdateCommand = (
command: readonly string[],
selectedEnvironment: Readonly<NodeJS.ProcessEnv>,
output: UpdateOutput = "structured",
): Promise<Result<string, string>> =>
new Promise((resolveResult) => {
@@ -34,7 +35,7 @@ export const runUpdateCommand = (
resolveResult(err("No executable supplied."));
return;
}
const environment = { ...process.env };
const environment = { ...selectedEnvironment };
// A fresh installed entry point must not inherit npx's invocation identity.
delete environment.npm_command;
const child = spawn(executable, args, {
@@ -72,8 +73,9 @@ export const runUpdateCommand = (
const requireCommandOutput = async (
command: readonly string[],
environment: Readonly<NodeJS.ProcessEnv>,
): Promise<string> => {
const result = await runUpdateCommand(command);
const result = await runUpdateCommand(command, environment);
if (!result.ok) throw new Error(result.error);
return result.value;
};
@@ -174,35 +176,46 @@ export const npmReleaseLookup = (
/** Create npm, registry, verification, and read-only maintenance effects. */
export const systemUpdateHost = (
packageRoot = fileURLToPath(new URL("../..", import.meta.url)),
home = homedir(),
home: string | undefined = undefined,
environment: Readonly<NodeJS.ProcessEnv> = process.env,
): UpdateHost => ({
installation: () =>
detectNpmInstallation(packageRoot, {
canonicalPath: realpath,
globalRoot: () => requireCommandOutput(["npm", "root", "--global"]),
globalPrefix: () => requireCommandOutput(["npm", "prefix", "--global"]),
globalRoot: () =>
requireCommandOutput(["npm", "root", "--global"], environment),
globalPrefix: () =>
requireCommandOutput(["npm", "prefix", "--global"], environment),
}),
latestVersion: async (installation) =>
npmReleaseLookup(
await runUpdateCommand(npmLatestVersionCommand(installation)),
await runUpdateCommand(
npmLatestVersionCommand(installation),
environment,
),
),
installVersion: async (installation, version, output) => {
const result = await runUpdateCommand(
updateInstallCommand(installation, version),
environment,
output,
);
return result.ok ? ok(undefined) : result;
},
installedVersion: (installation) =>
runUpdateCommand([
process.execPath,
join(installation.packageRoot, "scripts", "rea.mjs"),
"--version",
]),
runUpdateCommand(
[
process.execPath,
join(installation.packageRoot, "scripts", "rea.mjs"),
"--version",
],
environment,
),
planMaintenance: (installation) =>
planIntegrationMaintenance(
home,
home ?? homeDirectoryFromEnvironment(environment, process.platform),
join(installation.packageRoot, "scripts", "rea.mjs"),
runUpdateCommand,
environment,
(command) => runUpdateCommand(command, environment),
),
});
+3 -51
View File
@@ -51,6 +51,8 @@ it("rejects source text changed across the artifact port while retaining the ori
});
it("rejects sparse resolver arrays rather than relabeling literal imports as computed unknowns", async () => {
const artifacts = webModuleArtifactsFixture('import "./dep.js";');
const resolutions: WebModuleResolution[] = [];
resolutions.length = 1;
const service = new WebModuleTraceService(
{ load: () => Promise.resolve(ok(artifacts)) },
{
@@ -58,7 +60,7 @@ it("rejects sparse resolver arrays rather than relabeling literal imports as com
Promise.resolve(
ok({
engine: { id: "fixture", version: "1" },
resolutions: new Array<WebModuleResolution>(1),
resolutions,
diagnostics: [],
rawResult: {},
}),
@@ -70,40 +72,6 @@ it("rejects sparse resolver arrays rather than relabeling literal imports as com
if (!result.ok) expect(result.error._tag).toBe("AnalysisOutputError");
});
describe("selected module trace workflow", () => {
it("composes selected source, derived resolution and explicit computed/execution unknowns", async () => {
const artifacts = webModuleArtifactsFixture();
const service = new WebModuleTraceService(
{ load: () => Promise.resolve(ok(artifacts)) },
webModuleResolverFixture,
);
const response = await service.trace(args);
if (!response.ok) throw response.error;
const result = webModuleTraceResultSchema.parse(
response.value.normalized_result,
);
expect(result.importer).toEqual({
url: artifacts.manifest.scripts[0]?.url,
basis: "reported-source-url",
});
expect(result.manifest.capture_completeness).toEqual(
artifacts.manifest.capture_completeness,
);
expect(result.imports[0]?.resolution).toEqual({
state: "resolved",
url: "https://app.test/dep.js",
});
expect(result.imports[1]?.resolution).toEqual({
state: "unknown",
reason: "computed-specifier",
});
expect(result.imports.every((item) => item.execution === "unknown")).toBe(
true,
);
expect(response.value.subject).toMatchObject({
local_path: artifacts.sourceFile.path,
digest: { sha256: artifacts.sourceFile.sha256 },
});
});
it.each([
{ ...args, manifest_path: "relative.json" },
{
@@ -133,22 +101,6 @@ describe("selected module trace workflow", () => {
});
},
);
it("handles computed-only sources without acquiring the optional engine", async () => {
const artifacts = webModuleArtifactsFixture("import(name)");
const service = new WebModuleTraceService(
{ load: () => Promise.resolve(ok(artifacts)) },
{
resolve: () => {
throw new Error("engine must not start");
},
},
);
const result = await service.trace(args);
if (!result.ok) throw result.error;
expect(
webModuleTraceResultSchema.parse(result.value.normalized_result).engine,
).toBeNull();
});
it("rejects incomplete resolution rather than fabricating unknown values", async () => {
const artifacts = webModuleArtifactsFixture();
const service = new WebModuleTraceService(
@@ -12,28 +12,6 @@ import type { WebSourceMapPort } from "./WebSourceLocationPorts.js";
const service = (data = webSourceLocationFixture(), port = decoder) =>
new WebSourceLocationService({ load: () => Promise.resolve(ok(data)) }, port);
it("joins byte identity and historical capture context while keeping selected authenticity/execution unknown", async () => {
const data = webSourceLocationFixture();
data.manifest.source_evidence_id = `ev_${"a".repeat(64)}`;
const response = await service(data).trace(args);
if (!response.ok) throw response.error;
const result = webSourceLocationResultSchema.parse(
response.value.normalized_result,
);
expect(result).toMatchObject({
source: { sha256: data.sourceFile.sha256 },
source_map: {
association: "caller-selected",
sha256: data.sourceMap.file.sha256,
},
matches: [{ state: "mapped", content: { text: "original" } }],
execution: "unknown",
source_authenticity: "unknown",
});
expect(response.value.raw_result).toEqual({
source_map_text: data.sourceMap.text,
});
});
it.each([
{ ...args, manifest_path: "relative.json" },
{ ...args, script_index: -1 },
@@ -115,18 +93,6 @@ it.each(["digest", "url", "point"])(
expect(response.error._tag).toBe("AnalysisOutputError");
},
);
it("rejects a generated point outside retained text before decoding", async () => {
const response = await service(undefined, {
trace: () => {
throw new Error("must not decode");
},
}).trace({ ...args, generated_position: { line: 2, column: 0 } });
if (response.ok) throw new Error("expected invalid point");
expect(projectAnalysisError(response.error)).toMatchObject({
code: "invalid_request",
details: { issues: [{ message: expect.stringContaining("outside") }] },
});
});
it("honors cancellation both before acquisition and across decoder completion", async () => {
const first = new AbortController();
first.abort();
+1 -1
View File
@@ -76,7 +76,7 @@ export const workflowSnapshotRecord = (
evidence: Evidence,
operation: AnalysisOperation,
): WorkflowSnapshotRecordInput | undefined => {
if (!("analysis_profile" in evidence)) return undefined;
if (evidence.analysis_profile === null) return undefined;
return {
operation,
parameters: evidence.parameters,
@@ -1,10 +1,14 @@
import { expect, it } from "vitest";
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import { err } from "../../domain/result.js";
import type { AnalysisClient } from "../AnalysisProvider.js";
import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
import {
analysisErrorWithCleanupFailure,
closeAnalysisClient,
} from "./AnalysisClientCleanup.js";
const clientClosingWith = (cause: unknown): AnalysisClient => ({
execute: () => Promise.resolve(err(new ProviderCleanupError("x", [], {}))),
@@ -43,3 +47,31 @@ it("still reports an untyped close rejection as the provider client", async () =
details: { resources: ["provider-client"] },
});
});
it("preserves the original explanation and collected output alongside cleanup uncertainty", () => {
const primary = new ProviderAdapterError("fixture", "capture", {
userMessage: "Select the running target process and retry the capture.",
capturedOutput: {
stdout: "partial observation",
stderr: "native reason",
truncated: false,
},
});
const cleanup = new ProviderCleanupError("fixture", ["owned-process"], {
reason: "Process termination was not confirmed",
});
const combined = analysisErrorWithCleanupFailure(primary, cleanup);
expect(projectAnalysisError(combined)).toMatchObject({
code: "cleanup_incomplete",
message: primary.userMessage,
details: {
resources: ["owned-process"],
captured_output: primary.capturedOutput,
diagnostics: {
primary_error: projectAnalysisError(primary),
cleanup_error: projectAnalysisError(cleanup),
},
},
});
expect(combined.cause).toBe(primary);
});
@@ -1,7 +1,7 @@
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
import { err, ok, type Result } from "../../domain/result.js";
import { err, type Result } from "../../domain/result.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import type { AnalysisClient, ExecutionOptions } from "../AnalysisProvider.js";
@@ -14,10 +14,7 @@ export const closeAnalysisClient = async (
} = {},
): Promise<Result<null, AnalysisError>> => {
try {
if (client.closeWithOutcome !== undefined)
return await client.closeWithOutcome(options);
await client.close();
return ok(null);
return await client.close(options);
} catch (cause: unknown) {
// A typed cleanup failure already names its leftover resources.
if (cause instanceof AnalysisError && cause.cleanupIncomplete)
@@ -45,6 +42,13 @@ export const analysisErrorWithCleanupFailure = (
operation,
{
cause: primary,
userMessage: projectAnalysisError(primary).message,
...(primary.capturedOutput === undefined
? {}
: { capturedOutput: primary.capturedOutput }),
...(primary.partialObservation === undefined
? {}
: { partialObservation: primary.partialObservation }),
cleanup: {
reason: projected.message,
resources: cleanup.cleanupResources,
@@ -19,7 +19,6 @@ export interface AnalysisProviderCandidateEvaluation {
readonly candidate: AnalysisProviderCandidate;
readonly status: AnalysisProviderCandidateStatus;
readonly profile?: AnalysisProfileCommitment;
readonly compatibility?: Readonly<Record<string, JsonValue>>;
readonly profileError?: AnalysisError;
}
@@ -87,7 +86,6 @@ export const evaluateAnalysisProviderCandidate = async (
),
);
const profile = analysisProfileSchema.parse(resolved.value.profile);
const compatibility = jsonObjectSchema.parse(resolved.value.compatibility);
const identity = candidate.identity();
if (
profile.provider.id !== identity.id ||
@@ -102,7 +100,7 @@ export const evaluateAnalysisProviderCandidate = async (
"Resolved analysis profile has mismatched provider identity",
),
);
return ok({ candidate, status, profile, compatibility });
return ok({ candidate, status, profile });
} catch (cause: unknown) {
void cause;
return ok(
@@ -308,7 +308,6 @@ const candidate = (
{ id, name: identity.name, version: "1" },
{ fixture: id },
),
compatibility: {},
}),
);
},
@@ -325,7 +324,7 @@ const candidate = (
),
),
),
close: () => Promise.resolve(),
close: () => Promise.resolve(ok(null)),
};
},
};
@@ -49,7 +49,6 @@ export interface AnalysisProviderBinding {
readonly identity: ProviderIdentity & { readonly version: string };
readonly selectionSource: "request" | "environment" | "auto-single-candidate";
readonly profile: AnalysisProfileCommitment;
readonly compatibility: Readonly<Record<string, JsonValue>>;
}
/** Complete result used for both a bound and intentionally unbound target. */
@@ -247,10 +246,7 @@ export class AnalysisProviderRegistry {
if (evaluated.profileError !== undefined)
return err(evaluated.profileError);
const statuses = replaceCandidate(baseline, evaluated.status);
if (
evaluated.profile === undefined ||
evaluated.compatibility === undefined
)
if (evaluated.profile === undefined)
return err(selectionError("provider_unavailable", providerId, statuses));
return ok(
selectedResult(
@@ -259,7 +255,6 @@ export class AnalysisProviderRegistry {
{
...evaluated,
profile: evaluated.profile,
compatibility: evaluated.compatibility,
},
statuses,
),
@@ -312,10 +307,7 @@ export class AnalysisProviderRegistry {
evaluation,
): evaluation is AnalysisProviderCandidateEvaluation & {
readonly profile: AnalysisProfileCommitment;
readonly compatibility: Readonly<Record<string, JsonValue>>;
} =>
evaluation.profile !== undefined &&
evaluation.compatibility !== undefined,
} => evaluation.profile !== undefined,
);
if (usable.length === 0)
return ok({
@@ -363,7 +355,6 @@ const selectedResult = (
source: AnalysisProviderBinding["selectionSource"],
evaluated: AnalysisProviderCandidateEvaluation & {
readonly profile: AnalysisProfileCommitment;
readonly compatibility: Readonly<Record<string, JsonValue>>;
},
statuses: readonly AnalysisProviderCandidateStatus[],
): AnalysisProviderSelection => {
@@ -379,7 +370,6 @@ const selectedResult = (
identity: structuredClone(evaluated.profile.provider),
selectionSource: source,
profile: structuredClone(evaluated.profile),
compatibility: structuredClone(evaluated.compatibility),
},
candidates: replaceCandidate(statuses, selectedStatus),
};
@@ -72,6 +72,7 @@ it("exports independent nested query, workflow and Evidence payloads", () => {
}),
createEvidence(target, REA_WORKFLOW_PROVIDER, {
operation: "analyze_function",
confidence: "derived",
parameters,
result,
rawResult: result,
@@ -91,7 +92,7 @@ it("exports independent nested query, workflow and Evidence payloads", () => {
execution.result,
execution.raw_result,
]),
...(exported.value.workflow_entries ?? []).flatMap(({ execution }) => [
...exported.value.workflow_entries.flatMap(({ execution }) => [
execution.result,
execution.raw_result,
]),
@@ -186,6 +187,7 @@ describe("analysis snapshot cache capacity", () => {
});
const evidence = createEvidence(target, REA_WORKFLOW_PROVIDER, {
operation: workflowInput.operation,
confidence: "derived",
parameters: workflowInput.parameters,
result: execution.result,
rawResult: execution.rawResult,
@@ -124,7 +124,7 @@ export class AnalysisSnapshotCache {
if (!this.#entries.has(entry.query_id)) imported += 1;
this.#entries.set(entry.query_id, structuredClone(entry));
}
for (const entry of snapshot.workflow_entries ?? []) {
for (const entry of snapshot.workflow_entries) {
if (!this.#workflowEntries.has(entry.query_id) && !this.#hasCapacity())
continue;
this.#workflowEntries.set(entry.query_id, structuredClone(entry));
@@ -156,7 +156,7 @@ export class AnalysisSnapshotCache {
target: snapshotTargetIdentity,
binding,
entries,
...(workflows.length === 0 ? {} : { workflow_entries: workflows }),
workflow_entries: workflows,
evidence_bundle: evidenceBundle,
}),
);
+6 -15
View File
@@ -60,7 +60,6 @@ interface SessionBinding {
readonly target: BinaryTarget;
readonly client: AnalysisClient;
readonly profile: AnalysisProfileCommitment | null;
readonly compatibility: Readonly<Record<string, JsonValue>>;
readonly route: SessionProviderRoute;
readonly runId: string;
}
@@ -105,13 +104,13 @@ export class BinarySession
/** Identify the provider producing evidence for this session. */
providerIdentity(operation?: AnalysisOperation): ProviderIdentity {
const route = this.#currentRoute();
let selected = route.identity;
let selected = route.binding?.identity ?? route.identity;
if (operation !== undefined) {
const exact = route.capabilities?.get(operation)?.provider;
const exact = route.capabilities.get(operation)?.provider;
if (exact !== undefined) selected = exact;
else if (ENHANCED_OPERATIONS.has(operation)) {
const providers = new Map<string, ProviderIdentity>();
for (const descriptor of route.capabilities?.values() ?? [])
for (const descriptor of route.capabilities.values())
if (
descriptor.available &&
OFFICIAL_OPERATIONS.has(descriptor.operation)
@@ -157,11 +156,6 @@ export class BinarySession
return structuredClone(profile);
}
/** Return opaque adapter metadata retained for legacy open_binary output. */
openCompatibility(): Readonly<Record<string, JsonValue>> {
return structuredClone(this.#active?.compatibility ?? {});
}
/** Observe runtime provider-health changes that affect discovery metadata. */
onAvailabilityChanged(listener: () => void | Promise<void>): () => void {
this.#availabilityListeners.add(listener);
@@ -241,7 +235,7 @@ export class BinarySession
const resolved = await resolve();
if (!resolved.ok) return resolved;
const { target, route, sameTarget } = resolved.value;
const { profile, compatibility } = route;
const { profile } = route;
if (isAborted(options.signal))
return err(new AnalysisCancelledError("open_binary"));
const activeProfile = this.#active?.profile;
@@ -310,7 +304,6 @@ export class BinarySession
target,
client,
profile,
compatibility: structuredClone(compatibility),
route,
runId,
};
@@ -370,9 +363,8 @@ export class BinarySession
return closed.ok
? ok({
...written.value,
entries: snapshot.value.entries.length,
primitive_entries: snapshot.value.entries.length,
workflow_entries: snapshot.value.workflow_entries?.length ?? 0,
workflow_entries: snapshot.value.workflow_entries.length,
evidence_records: snapshot.value.evidence_bundle.records.length,
})
: closed;
@@ -584,7 +576,7 @@ export class BinarySession
parameters: arguments_,
execution: profiled.value,
});
} else if (profiled.ok && capability?.effects.mutatesArtifact === true) {
} else if (profiled.ok && capability.effects.mutatesArtifact) {
this.invalidateSnapshot();
}
return profiled;
@@ -699,7 +691,6 @@ export class BinarySession
target: previous.target,
client,
profile: previous.profile,
compatibility: previous.compatibility,
route: previous.route,
runId,
};
@@ -9,12 +9,10 @@ import { SessionProviderRouter } from "./SessionProviderRouter.js";
* disjoint auxiliary operation families.
*/
export const composeBinarySession = (
registry: AnalysisProviderRegistry | SessionProviderRouter,
registry: AnalysisProviderRegistry,
auxiliaryProviders: readonly AnalysisProvider[] = [],
): BinarySession =>
new BinarySession(
registry instanceof SessionProviderRouter
? registry
: SessionProviderRouter.selectable(registry, auxiliaryProviders),
SessionProviderRouter.selectable(registry, auxiliaryProviders),
new InvestigationRecords(),
);
@@ -25,7 +25,7 @@ interface ActiveExecutionBinding {
export interface PreparedSessionExecution {
readonly active: ActiveExecutionBinding;
readonly capability: CapabilityDescriptor | undefined;
readonly capability: CapabilityDescriptor;
readonly profile: AnalysisProfileCommitment | undefined;
readonly cacheable: boolean;
readonly cached: AnalysisExecution | undefined;
@@ -59,11 +59,8 @@ export const prepareSessionExecution = (
lookupSnapshot,
} = input;
if (active === undefined) return err(new NoBinaryOpenError());
const capability = active.route.capabilities?.get(operation);
if (
active.route.capabilities !== undefined &&
capability?.available !== true
) {
const capability = active.route.capabilities.get(operation);
if (capability?.available !== true) {
const selectionError = unboundOperationError(operation, active.route);
if (selectionError !== undefined) return err(selectionError);
return err(
@@ -76,8 +73,7 @@ export const prepareSessionExecution = (
}
const profile =
active.profile !== null &&
(capability === undefined ||
capability.provider.id === active.profile.provider.id)
capability.provider.id === active.profile.provider.id
? active.profile
: undefined;
const cacheable =
+1 -3
View File
@@ -21,8 +21,7 @@ import type {
export interface SavedAnalysisSnapshot {
readonly path: string;
readonly bytes: number;
readonly entries: number;
/** Eligible primitive query bindings; also reported by the legacy entries field. */
/** Eligible primitive query bindings. */
readonly primitive_entries: number;
/** Eligible composed workflow bindings, separate from primitive queries. */
readonly workflow_entries: number;
@@ -68,7 +67,6 @@ export interface BinarySessionPort
recordWorkflowSnapshot(
input: WorkflowSnapshotRecordInput,
): Result<null, EvidenceIntegrityError>;
openCompatibility(): Readonly<Record<string, JsonValue>>;
onAvailabilityChanged?(listener: () => void | Promise<void>): () => void;
onAnalysisSnapshotChanged?(listener: () => void | Promise<void>): () => void;
}
@@ -42,7 +42,7 @@ export interface WorkflowSnapshotRecordInput {
>[0]["execution"];
}
/** Binary snapshot owner and compatibility facade for composed investigation records. */
/** Own binary snapshots and coordinate the composed investigation records. */
export abstract class BinarySessionRecords {
readonly #records: InvestigationRecords;
readonly #snapshot = new AnalysisSnapshotCache();
@@ -36,10 +36,7 @@ export const binarySessionStatus = ({
requestActivitySnapshots,
providerOperationHealth,
}: BinarySessionStatusInput): JsonValue => {
const configuredProvider = router.configuredIdentity();
const provider = providerSummary(configuredProvider);
const providers = router.providerIdentities(route).map(providerSummary);
const capabilities = [...(route.capabilities?.values() ?? [])]
const capabilities = [...route.capabilities.values()]
.filter(({ operation }) => operation !== "inventory_artifact")
.sort((left, right) => left.operation.localeCompare(right.operation))
.map((descriptor) => {
@@ -75,8 +72,6 @@ export const binarySessionStatus = ({
.map(capabilityStatus),
}));
const common = {
provider,
providers,
capabilities,
analysis_provider_binding: analysisProviderBinding,
analysis_provider_candidates: analysisProviderCandidates,
+4 -29
View File
@@ -5,15 +5,14 @@ import type { AnalysisProfileCommitment } from "../../domain/analysisProfile.js"
import type {
AnalysisClient,
AnalysisClientContext,
AnalysisProfileResolutionOptions,
AnalysisProvider,
CapabilityDescriptor,
ProviderIdentity,
} from "../AnalysisProvider.js";
import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
/** Synthetic compatibility identity for a deterministic provider set. */
export const compositeProviderIdentity = (
/** Synthetic identity for a deterministic provider set. */
const compositeProviderIdentity = (
identities: readonly ProviderIdentity[],
): ProviderIdentity => ({
id: `composite:${identities
@@ -29,19 +28,10 @@ export class CompositeProvider implements AnalysisProvider {
readonly #identity: ProviderIdentity;
readonly #capabilities: readonly CapabilityDescriptor[];
readonly #providerByOperation: ReadonlyMap<string, AnalysisProvider>;
readonly #profileProvider: AnalysisProvider | undefined;
constructor(readonly providers: readonly AnalysisProvider[]) {
if (providers.length === 0)
throw new RangeError("CompositeProvider requires at least one provider");
const profileProviders = providers.filter(
({ resolveAnalysisProfile }) => resolveAnalysisProfile !== undefined,
);
if (profileProviders.length > 1)
throw new TypeError(
"CompositeProvider supports at most one target-bound analysis profile",
);
this.#profileProvider = profileProviders[0];
this.#identity = Object.freeze(
compositeProviderIdentity(
providers.map((provider) => provider.identity()),
@@ -77,16 +67,6 @@ export class CompositeProvider implements AnalysisProvider {
return this.#capabilities;
}
resolveAnalysisProfile(
target: BinaryTarget,
options?: AnalysisProfileResolutionOptions,
) {
const resolve = this.#profileProvider?.resolveAnalysisProfile;
return resolve === undefined
? Promise.resolve(ok({ profile: null, compatibility: {} }))
: resolve.call(this.#profileProvider, target, options);
}
createClient(
target: BinaryTarget,
profile?: AnalysisProfileCommitment,
@@ -104,9 +84,7 @@ export class CompositeProvider implements AnalysisProvider {
clients.set(provider, created);
return created;
};
const closeWithOutcome: NonNullable<
AnalysisClient["closeWithOutcome"]
> = async (options) => {
const close: AnalysisClient["close"] = async (options) => {
const outcomes = await Promise.all(
[...clients.entries()].map(([provider, client]) =>
closeAnalysisClient(client, provider.identity().id, options),
@@ -164,10 +142,7 @@ export class CompositeProvider implements AnalysisProvider {
}
return undefined;
},
closeWithOutcome,
close: async () => {
await closeWithOutcome();
},
close,
};
}
}
@@ -7,7 +7,7 @@ import type {
} from "../AnalysisProvider.js";
import { LazyAnalysisProvider } from "./LazyAnalysisProvider.js";
import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
import { err } from "../../domain/result.js";
import { err, ok as resultOk } from "../../domain/result.js";
const identity: ProviderIdentity = {
id: "test-provider",
@@ -24,7 +24,7 @@ const providerWithClient = (
onCreate();
return {
execute: async (operation) => err(new AnalysisCancelledError(operation)),
close: async () => undefined,
close: async () => resultOk(null),
};
},
});
@@ -4,7 +4,7 @@ import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import type { ProviderOperationHealth } from "../../domain/providerOperationHealth.js";
import { err } from "../../domain/result.js";
import { err, ok } from "../../domain/result.js";
import { ABORTED, waitForAbortable } from "./AbortablePromise.js";
import type {
AnalysisClient,
@@ -120,12 +120,12 @@ class LazyAnalysisClient implements AnalysisClient {
return this.#client?.operationHealthSnapshot?.();
}
async close(): Promise<void> {
close: AnalysisClient["close"] = async (options) => {
this.#closed = true;
if (this.#loading === undefined) return;
if (this.#loading === undefined) return ok(null);
const client = await this.#loading;
await client.close();
}
return client.close(options);
};
async #load(operation: string): Promise<AnalysisClient> {
if (this.#closed)
+29 -221
View File
@@ -1,24 +1,13 @@
import type { AnalysisProviderSelector } from "../../contracts/providerSelection.js";
import {
analysisProfileSchema,
type AnalysisProfileCommitment,
} from "../../domain/analysisProfile.js";
import type { AnalysisProfileCommitment } from "../../domain/analysisProfile.js";
import type { BinaryTarget } from "../../domain/binaryTarget.js";
import {
AnalysisCancelledError,
AnalysisCapabilityUnavailableError,
} from "../../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
import { ProviderSelectionError } from "../../domain/providerSelectionError.js";
import { type AnalysisError } from "../../domain/analysisErrorBase.js";
import { jsonObjectSchema, type JsonValue } from "../../domain/jsonValue.js";
import { err, ok, type Result } from "../../domain/result.js";
import type {
AnalysisClient,
AnalysisClientContext,
AnalysisClientFactory,
AnalysisProfileResolution,
AnalysisProfileResolutionOptions,
AnalysisProvider,
CapabilityDescriptor,
ProviderIdentity,
@@ -29,18 +18,13 @@ import {
type AnalysisProviderCandidateStatus,
type AnalysisProviderSelection,
} from "./AnalysisProviderRegistry.js";
import { ABORTED, waitForAbortable } from "./AbortablePromise.js";
import {
CompositeProvider,
compositeProviderIdentity,
} from "./CompositeProvider.js";
import { CompositeProvider } from "./CompositeProvider.js";
/** Immutable operation routes and binding metadata for one target transition. */
export interface SessionProviderRoute {
readonly identity: ProviderIdentity;
readonly capabilities: ReadonlyMap<string, CapabilityDescriptor> | undefined;
readonly capabilities: ReadonlyMap<string, CapabilityDescriptor>;
readonly profile: AnalysisProfileCommitment | null;
readonly compatibility: Readonly<Record<string, JsonValue>>;
readonly binding: AnalysisProviderBinding | null;
readonly selection: AnalysisProviderSelection | undefined;
createClient(
@@ -49,69 +33,14 @@ export interface SessionProviderRoute {
): AnalysisClient;
}
interface SingleProviderRuntime {
readonly kind: "single";
readonly provider: AnalysisProvider | AnalysisClientFactory;
readonly identity: ProviderIdentity;
readonly capabilities: ReadonlyMap<string, CapabilityDescriptor> | undefined;
readonly resolveProfile: (
target: BinaryTarget,
options?: AnalysisProfileResolutionOptions,
) => Promise<Result<AnalysisProfileResolution, AnalysisError>>;
}
interface SelectableProviderRuntime {
readonly kind: "selectable";
readonly registry: AnalysisProviderRegistry;
readonly auxiliaryProviders: readonly AnalysisProvider[];
readonly identity: ProviderIdentity;
readonly initialRoute: SessionProviderRoute;
}
/** Resolve either the compatibility single-provider seam or a selectable set. */
/** Resolve one registry-selected deep provider and disjoint auxiliary families. */
export class SessionProviderRouter {
private constructor(
private readonly runtime: SingleProviderRuntime | SelectableProviderRuntime,
private readonly registry: AnalysisProviderRegistry,
private readonly auxiliaryProviders: readonly AnalysisProvider[],
private readonly route: SessionProviderRoute,
) {}
/** Create routing for an embedding backed by one fixed provider or factory. */
static single(
provider: AnalysisProvider | AnalysisClientFactory,
options: {
readonly resolveAnalysisProfile?: (
target: BinaryTarget,
resolutionOptions?: AnalysisProfileResolutionOptions,
) => Promise<Result<AnalysisProfileResolution, AnalysisError>>;
} = {},
): SessionProviderRouter {
const identity =
typeof provider === "function"
? { id: "unidentified", name: "Unidentified provider", version: null }
: provider.identity();
const capabilities =
typeof provider === "function"
? undefined
: capabilityMap(provider.capabilities());
const resolveProfile =
options.resolveAnalysisProfile ??
(typeof provider === "function" ||
provider.resolveAnalysisProfile === undefined
? () => Promise.resolve(ok({ profile: null, compatibility: {} }))
: (
target: BinaryTarget,
resolutionOptions?: AnalysisProfileResolutionOptions,
) =>
provider.resolveAnalysisProfile?.(target, resolutionOptions) ??
Promise.resolve(ok({ profile: null, compatibility: {} })));
return new SessionProviderRouter({
kind: "single",
provider,
identity,
capabilities,
resolveProfile,
});
}
/** Create selection-aware routing while keeping auxiliary families disjoint. */
static selectable(
registry: AnalysisProviderRegistry,
@@ -129,56 +58,16 @@ export class SessionProviderRouter {
`Deep and auxiliary providers both declare operation ${operation}`,
);
const initialRoute = selectableRoute(auxiliaryProviders, undefined);
return new SessionProviderRouter({
kind: "selectable",
return new SessionProviderRouter(
registry,
auxiliaryProviders: [...auxiliaryProviders],
identity:
identities.length === 0
? emptyProviderIdentity()
: compositeProviderIdentity(identities),
[...auxiliaryProviders],
initialRoute,
});
}
/** Compatibility identity covering every configured provider. */
configuredIdentity(): ProviderIdentity {
return structuredClone(this.runtime.identity);
}
/** Provider identities exposed through the flat 1.x compatibility field. */
providerIdentities(route: SessionProviderRoute): readonly ProviderIdentity[] {
if (this.runtime.kind === "single") {
if (route.capabilities === undefined) return [route.identity];
return uniqueProviderIdentities(
[...route.capabilities.values()].map(({ provider }) => provider),
);
}
const selected = route.binding?.identity;
return uniqueProviderIdentities([
...this.runtime.auxiliaryProviders.map((provider) => provider.identity()),
...this.runtime.registry
.identities()
.map((identity) =>
identity.id === selected?.id ? selected : identity,
),
]);
);
}
/** Target-free routes and discovery metadata. */
initialRoute(): SessionProviderRoute {
if (this.runtime.kind === "selectable") return this.runtime.initialRoute;
const runtime = this.runtime;
return {
identity: structuredClone(runtime.identity),
capabilities: runtime.capabilities,
profile: null,
compatibility: {},
binding: null,
selection: undefined,
createClient: (target, context) =>
createSingleProviderClient(runtime, target, undefined, context),
};
return this.route;
}
/** Resolve target routes before any provider client is created. */
@@ -188,64 +77,21 @@ export class SessionProviderRouter {
signal?: AbortSignal,
): Promise<Result<SessionProviderRoute, AnalysisError>> {
const resolutionOptions = signal === undefined ? undefined : { signal };
if (this.runtime.kind === "selectable") {
const selected = await this.runtime.registry.select(
target,
providerId,
resolutionOptions,
);
return selected.ok
? ok(selectableRoute(this.runtime.auxiliaryProviders, selected.value))
: selected;
}
const runtime = this.runtime;
if (
providerId !== undefined &&
providerId !== "auto" &&
providerId !== runtime.identity.id
)
return err(
new ProviderSelectionError({
reason: "unknown_provider",
requestedProviderId: providerId,
candidateIds: [runtime.identity.id],
}),
);
const resolved = await waitForAbortable(
runtime.resolveProfile(target, resolutionOptions),
signal,
const selected = await this.registry.select(
target,
providerId,
resolutionOptions,
);
if (resolved === ABORTED)
return err(new AnalysisCancelledError("open_binary"));
if (!resolved.ok) return resolved;
const normalized = normalizeProfileResolution(
resolved.value,
runtime.identity.id,
);
if (!normalized.ok) return normalized;
return ok({
identity: structuredClone(runtime.identity),
capabilities: runtime.capabilities,
profile: normalized.value.profile,
compatibility: normalized.value.compatibility,
binding: null,
selection: undefined,
createClient: (openedTarget, context) =>
createSingleProviderClient(
runtime,
openedTarget,
normalized.value.profile ?? undefined,
context,
),
});
return selected.ok
? ok(selectableRoute(this.auxiliaryProviders, selected.value))
: selected;
}
/** Candidate status authoritative for the active or target-free route. */
candidateStatuses(
route: SessionProviderRoute,
): readonly AnalysisProviderCandidateStatus[] {
if (this.runtime.kind === "single") return [];
return route.selection?.candidates ?? this.runtime.registry.candidates();
return route.selection?.candidates ?? this.registry.candidates();
}
/** Produce exact candidate rejections for an intentionally unbound route. */
@@ -254,15 +100,12 @@ export class SessionProviderRouter {
route: SessionProviderRoute,
): ProviderSelectionError | undefined {
if (
this.runtime.kind !== "selectable" ||
route.binding !== null ||
route.selection === undefined
route.selection === undefined ||
!this.registry.declaredOperations().includes(operation)
)
return undefined;
return this.runtime.registry.unboundOperationError(
operation,
route.selection,
);
return this.registry.unboundOperationError(operation, route.selection);
}
}
@@ -276,14 +119,17 @@ const selectableRoute = (
...(binding === null ? [] : [binding.provider]),
];
const provider =
providers.length === 0 ? undefined : new CompositeProvider(providers);
binding === null && providers.length === 1
? providers[0]
: providers.length === 0
? undefined
: new CompositeProvider(providers);
const identity = provider?.identity() ?? emptyProviderIdentity();
const capabilities = capabilityMap(provider?.capabilities() ?? []);
return {
identity,
capabilities,
profile: binding?.profile ?? null,
compatibility: structuredClone(binding?.compatibility ?? {}),
binding,
selection,
createClient: (target, context) =>
@@ -292,16 +138,6 @@ const selectableRoute = (
};
};
const createSingleProviderClient = (
runtime: SingleProviderRuntime,
target: BinaryTarget,
profile: AnalysisProfileCommitment | undefined,
context: AnalysisClientContext,
): AnalysisClient =>
typeof runtime.provider === "function"
? runtime.provider(target, profile, context)
: runtime.provider.createClient(target, profile, context);
const emptyClient = (identity: ProviderIdentity): AnalysisClient => ({
execute: (operation) =>
operation === "health"
@@ -324,7 +160,7 @@ const emptyClient = (identity: ProviderIdentity): AnalysisClient => ({
),
),
),
close: () => Promise.resolve(),
close: () => Promise.resolve(ok(null)),
});
const emptyProviderIdentity = (): ProviderIdentity => ({
@@ -338,13 +174,6 @@ const capabilityMap = (
): ReadonlyMap<string, CapabilityDescriptor> =>
new Map(capabilities.map((descriptor) => [descriptor.operation, descriptor]));
const uniqueProviderIdentities = (
identities: readonly ProviderIdentity[],
): readonly ProviderIdentity[] =>
[...new Map(identities.map((identity) => [identity.id, identity])).values()]
.sort((left, right) => left.id.localeCompare(right.id))
.map((identity) => structuredClone(identity));
const assertDisjoint = (
providers: readonly AnalysisProvider[],
): ReadonlySet<string> => {
@@ -370,24 +199,3 @@ const assertUniqueProviderIds = (
ids.add(identity.id);
}
};
const normalizeProfileResolution = (
resolution: AnalysisProfileResolution,
providerId: string,
): Result<AnalysisProfileResolution, ProviderAdapterError> => {
try {
return ok({
profile:
resolution.profile === null
? null
: analysisProfileSchema.parse(resolution.profile),
compatibility: jsonObjectSchema.parse(resolution.compatibility),
});
} catch (cause: unknown) {
return err(
new ProviderAdapterError(providerId, "resolve_analysis_profile", {
cause,
}),
);
}
};
@@ -4,26 +4,9 @@ import {
binaryLayoutFixture,
BINARY_LAYOUT_TEST_PROVIDER,
} from "../../../tests/fixtures/binaryDiagnostics/layout.js";
import { parseEvidence } from "../../domain/evidence.js";
import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
import { err, ok } from "../../domain/result.js";
it("binds original bytes, inline observations, unknowns and producing identity", async () => {
const fixture = binaryLayoutFixture();
const service = new BinaryLayoutService({
identity: BINARY_LAYOUT_TEST_PROVIDER,
inspect: () => Promise.resolve(ok(fixture)),
});
const result = await service.inspect({ path: fixture.artifact.path });
if (!result.ok) throw result.error;
const evidence = parseEvidence(result.value);
expect(evidence.normalized_result).toEqual(fixture);
expect(evidence.raw_result).toEqual(fixture);
expect(evidence.subject?.digest.sha256).toBe(fixture.artifact.sha256);
expect(evidence.provider).toEqual(BINARY_LAYOUT_TEST_PROVIDER);
expect(evidence.confidence).toBe("observed");
});
it.each([
{ path: "relative.elf" },
{ path: "/selected.elf", approval: true },
@@ -9,22 +9,6 @@ import { parseEvidence } from "../../domain/evidence.js";
import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
import { err, ok } from "../../domain/result.js";
it("binds original bytes, inline observations, unknowns and producing identity", async () => {
const fixture = recordedCrashFixture();
const service = new RecordedCrashService({
identity: RECORDED_CRASH_TEST_PROVIDER,
inspect: () => Promise.resolve(ok(fixture)),
});
const result = await service.inspect({ path: fixture.artifact.path });
if (!result.ok) throw result.error;
const evidence = parseEvidence(result.value);
expect(evidence.normalized_result).toEqual(fixture);
expect(evidence.raw_result).toEqual(fixture);
expect(evidence.subject?.digest.sha256).toBe(fixture.artifact.sha256);
expect(evidence.provider).toEqual(RECORDED_CRASH_TEST_PROVIDER);
expect(evidence.confidence).toBe("observed");
});
it("labels an envelope containing debugger-derived maps as derived", async () => {
const fixture = recordedCrashFixture();
fixture.debugger = recordedCrashDebuggerFixture();
@@ -5,25 +5,8 @@ import {
evmInterfaceFixture,
} from "../../../tests/fixtures/evm/interface.js";
import { err, ok } from "../../domain/result.js";
import { parseEvidence } from "../../domain/evidence.js";
import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
it("returns full inline inferred Evidence and unmodified upstream representation", async () => {
const value = evmInterfaceFixture();
const service = new EvmInterfaceService({
inspect: () => Promise.resolve(ok(evmInterfaceExecution(value))),
});
const result = await service.inspect({
path: value.artifact.path,
encoding: "hex",
});
if (!result.ok) throw result.error;
const evidence = parseEvidence(result.value);
expect(evidence.normalized_result).toEqual(value);
expect(evidence.raw_result).toEqual({ functions: [] });
expect(evidence.confidence).toBe("inferred");
expect(evidence.subject?.digest.sha256).toBe(value.artifact.sha256);
});
it.each([
{ path: "relative.hex", encoding: "hex" },
{ path: "/selected", encoding: "auto" },
@@ -6,14 +6,14 @@ import type {
ElectronActiveObservationInput,
ElectronActiveObservationResult,
} from "../../domain/javascript/electronActiveObservation.js";
import { jsonValueSchema } from "../../domain/jsonValue.js";
import { jsonObjectSchema, jsonValueSchema } from "../../domain/jsonValue.js";
type CanonicalElectronActiveObservationInput =
ElectronActiveObservationInput & {
readonly application_root: string;
};
/** Create Evidence without retaining arbitrary runtime argument values. */
/** Commit the selected Electron experiment and its observed result. */
export const createElectronActiveEvidence = (
input: CanonicalElectronActiveObservationInput,
result: ElectronActiveObservationResult,
@@ -38,22 +38,12 @@ export const createElectronActiveEvidence = (
],
});
const scenarioProjection = (
input: CanonicalElectronActiveObservationInput,
): EvidenceObservation["parameters"] => ({
executable_path: input.executable_path,
application_path: input.application_path,
application_root: input.application_root,
args: [...input.args],
actions: input.actions.map(({ step_id, kind }) => ({ step_id, kind })),
});
const parameters = (
input: CanonicalElectronActiveObservationInput,
): EvidenceObservation["parameters"] => ({
...scenarioProjection(input),
scenario_sha256: canonicalDigest(
scenarioProjection(input),
"Browser scenario",
),
});
): EvidenceObservation["parameters"] => {
const scenario = jsonObjectSchema.parse(input);
return {
...scenario,
scenario_sha256: canonicalDigest(scenario, "Electron scenario"),
};
};
@@ -106,6 +106,8 @@ it("keeps exact values for empty literals without synthetic application labels",
it.each([
{ version: 3, sources: [""], names: [], mappings: "AAAA" },
{ version: 3, sourceRoot: null, sources: [""], names: [], mappings: "AAAA" },
{ version: 3, sourceRoot: "", sources: [""], names: [], mappings: "AAAA" },
{
version: 3,
sections: [
@@ -126,7 +128,9 @@ it.each([
identity.strategy === "source-map-original"
? identity.original_source
: null,
sources: observations.map(({ properties }) => properties.source),
sources: observations.map(
({ source_map_reference }) => source_map_reference?.source_name,
),
}));
expect(originals).toEqual([{ originalSource: "", sources: [""] }]);
});
@@ -267,3 +271,75 @@ it("selects an empty context-bridge API with an exact empty seed", async () => {
});
expect(matches.map(({ node_id: nodeId }) => apis.get(nodeId))).toEqual([""]);
});
it("pairs indexed source-map leaves by raw source name and root", async () => {
const map = (value: number) =>
JSON.stringify({
version: 3,
sections: ["one", "two"].map((name, line) => ({
offset: { line, column: 0 },
map: {
version: 3,
sourceRoot: `../${name}`,
sources: ["same.js"],
sourcesContent: [`export const value = ${String(value)};`],
names: [],
mappings: "AAAA",
},
})),
});
const left = await analyzeSource("//# sourceMappingURL=app.js.map", {
"app.js.map": map(1),
});
const right = await analyzeSource("//# sourceMappingURL=app.js.map", {
"app.js.map": map(2),
});
const matching = matchJavaScriptApplicationVersions(
left.graph.nodes,
right.graph.nodes,
);
const originals = matching.pairs.filter(
({ left: node }) => node.kind === "source-module",
);
expect(originals).toHaveLength(2);
for (const pair of originals) {
expect(pair).toMatchObject({
basis: "source-map-identity",
confidence: "high",
});
expect(pair.left.identity).toMatchObject({
original_source: "same.js",
source_root: expect.any(String),
});
if (pair.left.identity.strategy !== "source-map-original")
throw new Error("Expected source identity");
expect(pair.right.identity).toMatchObject({
source_root: pair.left.identity.source_root,
});
}
});
it("reports malformed source roots without manufacturing an original path", async () => {
const output = await analyzeSource("//# sourceMappingURL=app.js.map", {
"app.js.map": JSON.stringify({
version: 3,
sourceRoot: 42,
sources: ["a.js"],
names: [],
mappings: "AAAA",
}),
});
expect(
output.graph.nodes.filter(({ kind }) => kind === "source-module"),
).toEqual([]);
expect(
output.graph.nodes.flatMap(({ observations }) => observations),
).toContainEqual(
expect.objectContaining({
properties: expect.objectContaining({
limitation: "Source map sourceRoot must be a string or null.",
}),
evidence: expect.objectContaining({ state: "unavailable" }),
}),
);
});
@@ -1,5 +1,4 @@
import {
createEvidence,
createImmutableEvidenceSteps,
type Evidence,
type EvidenceObservation,
@@ -9,25 +8,12 @@ import type {
JavaScriptApplicationAnalysisResult,
} from "../../domain/javascript/javascriptApplicationAnalysis.js";
import { JAVASCRIPT_APPLICATION_PROVIDER } from "../InvestigationProviders.js";
import {
freezeJsonSnapshot,
freezeOwnedJsonSnapshotSteps,
} from "../../domain/immutableJson.js";
import { freezeOwnedJsonSnapshotSteps } from "../../domain/immutableJson.js";
import { rememberOwnedApplicationGraphEvidence } from "./JavaScriptApplicationEvidenceGraph.js";
import { completeJavaScriptAnalysisSteps } from "./JavaScriptAnalysisControl.js";
import { jsonValueValidationSteps } from "../../domain/jsonValue.js";
import type { ProgressReporter } from "../ProgressReporter.js";
/** Transfer an already validated, application-owned result into immutable analysis Evidence. */
export const createOwnedJavaScriptApplicationEvidence = (
input: AnalyzeJavaScriptApplicationInput,
result: JavaScriptApplicationAnalysisResult,
): Evidence =>
rememberOwnedApplicationGraphEvidence(
createJavaScriptApplicationEvidence(input, freezeJsonSnapshot(result)),
result,
);
/** Create owned analysis Evidence while allowing request cancellation during sealing and hashing. */
export const createOwnedJavaScriptApplicationEvidenceCooperatively = async (
input: AnalyzeJavaScriptApplicationInput,
@@ -78,17 +64,6 @@ const reportEvidencePhase = (
progress?.report({ phase, completed: 0, total: 1, message }) ??
Promise.resolve();
/** Create Evidence for one deterministic local JavaScript application graph. */
export const createJavaScriptApplicationEvidence = (
input: AnalyzeJavaScriptApplicationInput,
result: JavaScriptApplicationAnalysisResult,
): Evidence =>
createEvidence(
applicationSubject(result),
JAVASCRIPT_APPLICATION_PROVIDER,
applicationObservation(input, result),
);
const applicationSubject = (result: JavaScriptApplicationAnalysisResult) => ({
path: result.input_path,
sha256: result.root_artifact_sha256,
@@ -1,47 +0,0 @@
import { describe, expect, it } from "vitest";
import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE } from "../../contracts/javascript/javascriptRuntimeReconciliationExample.js";
import { parseEvidence } from "../../domain/evidence.js";
import {
analyzeJavaScriptApplicationInputSchema,
javascriptApplicationAnalysisResultSchema,
} from "../../domain/javascript/javascriptApplicationAnalysis.js";
import {
createJavaScriptApplicationEvidence,
createOwnedJavaScriptApplicationEvidence,
} from "./JavaScriptApplicationEvidence.js";
import {
parseApplicationGraphEvidence,
rememberOwnedApplicationGraphEvidence,
} from "./JavaScriptApplicationEvidenceGraph.js";
describe("owned application graph Evidence", () => {
it("reuses the exact authenticated graph and preserves ordinary wire identity", () => {
const result = javascriptApplicationAnalysisResultSchema.parse(
JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE.normalized_result,
);
const input = analyzeJavaScriptApplicationInputSchema.parse({
input_path: result.input_path,
...JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE.parameters,
});
const ordinary = createJavaScriptApplicationEvidence(input, result);
const owned = createOwnedJavaScriptApplicationEvidence(input, result);
expect(owned.evidence_id).toBe(ordinary.evidence_id);
expect(JSON.stringify(owned)).toBe(JSON.stringify(ordinary));
const parsed = parseApplicationGraphEvidence(owned);
expect(parsed.evidence).toBe(owned);
expect(parsed.graph).toBe(result.graph);
expect(parsed.semanticGraph).toBe(result.semantic_graph);
expect(Object.isFrozen(parsed.graph.nodes)).toBe(true);
expect(parseApplicationGraphEvidence(owned)).toBe(parsed);
const wire: unknown = JSON.parse(JSON.stringify(owned));
expect(parseApplicationGraphEvidence(wire)).toEqual(parsed);
expect(parseApplicationGraphEvidence(wire).graph).not.toBe(parsed.graph);
expect(() =>
rememberOwnedApplicationGraphEvidence(ordinary, result),
).toThrow("exact validated immutable result");
const tampered = { ...owned, normalized_result: {} };
expect(() => parseEvidence(Object.freeze(tampered))).toThrow();
expect(() => parseApplicationGraphEvidence(tampered)).toThrow();
});
});
@@ -1,6 +1,7 @@
import { createHash } from "node:crypto";
import { setImmediate } from "node:timers/promises";
import { resolveJavaScriptSourceMapReference } from "../../domain/javascript/javascriptSourceMapPaths.js";
import { analyzeParsedJavaScriptStaticSource } from "../../domain/javascript/javascriptStaticAnalysis.js";
import {
analyzeParsedJavaScriptSemantics,
@@ -331,7 +332,12 @@ const collectSourceMapOriginals = (
file,
"Source map sourcesContent must contain one string or null entry per source.",
);
const root = typeof map.sourceRoot === "string" ? map.sourceRoot : "";
if (map.sourceRoot != null && typeof map.sourceRoot !== "string")
return invalidSourceMap(
file,
"Source map sourceRoot must be a string or null.",
);
const root = typeof map.sourceRoot === "string" ? map.sourceRoot : null;
for (const [index, raw] of names.entries()) {
if (typeof raw !== "string")
return invalidSourceMap(
@@ -341,7 +347,7 @@ const collectSourceMapOriginals = (
const rawContent = Array.isArray(contents) ? contents[index] : undefined;
const content = typeof rawContent === "string" ? rawContent : null;
sources.push({
source: resolveSourceName(root, raw),
reference: resolveJavaScriptSourceMapReference(raw, root, file.path),
content,
content_sha256: content === null ? null : sha256(content),
});
@@ -419,9 +425,6 @@ const pointForOffset = (
return { line: lines.length, column: lines.at(-1)?.length ?? 0 };
};
const resolveSourceName = (root: string, source: string): string =>
`${root}${root !== "" && !root.endsWith("/") ? "/" : ""}${source}`;
const optionalString = (value: unknown): string | null =>
typeof value === "string" && value.length > 0 ? value : null;
@@ -1,3 +1,4 @@
import type { JavaScriptSourceMapReference } from "../../domain/javascript/javascriptSourceMapPaths.js";
import type {
JavaScriptSourceRange,
JavaScriptStaticAnalysis,
@@ -44,7 +45,7 @@ export interface JavaScriptHtmlScriptObservation {
/** One original source declared by a local source map. */
export interface JavaScriptSourceMapOriginal {
readonly source: string;
readonly reference: JavaScriptSourceMapReference;
readonly content: string | null;
readonly content_sha256: string | null;
}
@@ -124,16 +124,16 @@ export const addJavaScriptSourceMapOriginals = (
strategy: "source-map-original",
stability: "source-map-exact",
source_map_sha256: mapFile.sha256,
original_source: original.source,
original_source: original.reference.source_name,
source_root: original.reference.source_root,
source_sha256: original.content_sha256,
},
observations: [
{
label: original.source,
label: original.reference.source_name || null,
source_map_reference: original.reference,
properties: {
source: original.source,
content_available: original.content !== null,
source_sha256: original.content_sha256,
},
evidence: artifactObservationEvidence({
sha256: mapFile.sha256,
@@ -150,7 +150,10 @@ export const addJavaScriptSourceMapOriginals = (
source_node_id: mapNode.node_id,
target_node_id: node.node_id,
relation: "contains",
properties: { original_source: original.source },
properties: {
original_source: original.reference.source_name,
source_root: original.reference.source_root,
},
evidence: artifactObservationEvidence({
sha256: mapFile.sha256,
path: mapFile.path,
@@ -1,10 +1,7 @@
import { describe, expect, it } from "vitest";
import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
import { err, ok } from "../../domain/result.js";
import type {
JavaScriptRecoveryInput,
JavaScriptRecoveryResult,
} from "../../domain/javascript/javascriptRecovery.js";
import type { JavaScriptRecoveryResult } from "../../domain/javascript/javascriptRecovery.js";
import { createAnalysisExecution } from "../AnalysisProvider.js";
import { JavaScriptRecoveryService } from "./JavaScriptRecoveryService.js";
@@ -47,31 +44,6 @@ const providerIdentity = {
const input = { path: artifact.path, output_directory: "/tmp/output" };
describe("JavaScript recovery workflow", () => {
it("passes normalized requests to a typed port and returns derived Evidence", async () => {
const received: JavaScriptRecoveryInput[] = [];
const service = new JavaScriptRecoveryService({
recover: async (request) => {
received.push(request);
return ok(
createAnalysisExecution(recoveryResult(), providerIdentity, {
subject: { ...artifact, format: "javascript" },
limitations: ["Not executed"],
}),
);
},
});
const result = await service.recover(input);
if (!result.ok) throw result.error;
expect(received).toEqual([
{ ...input, extraction_mode: "structural", rewrite_level: "standard" },
]);
expect(result.value).toMatchObject({
operation: "recover_javascript_sources",
confidence: "derived",
authority: "shipped-artifact",
provider: providerIdentity,
});
});
it("preserves a missing provider reason", async () => {
const failure = new AnalysisCapabilityUnavailableError(
"fixture-recovery",
@@ -0,0 +1,46 @@
import { expect, it } from "vitest";
import { BrowserObservationError } from "../../domain/browserObservationError.js";
import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
import { err } from "../../domain/result.js";
import type { JavaScriptRuntimeObservationPort } from "./JavaScriptRuntimeObservationPort.js";
import { observeJavaScriptRuntime } from "./JavaScriptRuntimeObservationService.js";
it("preserves failed Inspector cleanup when cancellation occurs during observation", async () => {
const controller = new AbortController();
const failure = new BrowserObservationError(
"observe_javascript_runtime",
"cleanup_failed",
{
cause: new AnalysisCancelledError("observe_javascript_runtime"),
},
);
const provider: JavaScriptRuntimeObservationPort = {
identity: () => ({
id: "test-inspector",
name: "Test Inspector",
version: "1",
}),
listTargets: async () => err(failure),
observe: async () => {
controller.abort();
return err(failure);
},
};
const result = await observeJavaScriptRuntime(
provider,
{
inspector_endpoint: "http://127.0.0.1:9229",
target_id: "target",
observation_ms: 0,
},
{ signal: controller.signal },
);
expect(result.ok).toBe(false);
if (result.ok) throw new Error("Expected failed cleanup");
expect(result.error).toBe(failure);
expect(result.error.cleanupIncomplete).toBe(true);
expect(result.error.cleanupResources).toEqual(["browser_transport"]);
expect(result.error.userCategory).toBe("cancelled");
});
@@ -43,18 +43,17 @@ export const observeJavaScriptRuntime = async (
const ready = requireProvider(provider, "observe_javascript_runtime");
if (!ready.ok) return ready;
const result = await ready.value.observe(input, options);
if (!result.ok) return result;
if (options.signal?.aborted === true)
return err(new AnalysisCancelledError("observe_javascript_runtime"));
return result.ok
? ok(
createJavaScriptRuntimeObservationEvidence(
"observe_javascript_runtime",
input,
result.value,
ready.value.identity(),
),
)
: result;
return ok(
createJavaScriptRuntimeObservationEvidence(
"observe_javascript_runtime",
input,
result.value,
ready.value.identity(),
),
);
};
const requireProvider = (
@@ -147,7 +147,9 @@ it("retains resource-limit reasons at nested object property slots", () => {
expect.objectContaining({
family: "object-flow",
reason: "resource-limit",
detail: expect.stringMatching(/Unknown value at property:value/u),
detail: expect.stringMatching(
/Unknown value at property:\/nested\/value/u,
),
}),
);
});
@@ -625,3 +627,242 @@ it("only records node loss when the budget rejects a new identity", () => {
expect(blocked).toBeNull();
expect(state.fileNodesDropped).toBe(true);
});
it("keeps full static property identities distinct through backward provenance", () => {
const graph = graphFor(`
const root = { a: { id: 'left' }, b: { id: 'right' }, 'a.id': 'dotted', '': { 'a/b~c': 'escaped' } };
const left = root.a.id;
const right = root['b']['id'];
const missing = root.id;
const dotted = root['a.id'];
const escaped = root['']['a/b~c'];
`);
const slots = graph.nodes.filter(({ kind }) => kind === "property-slot");
for (const [pointer, literal] of [
["/a/id", "left"],
["/b/id", "right"],
["/a.id", "dotted"],
["//a~1b~0c", "escaped"],
["/id", null],
]) {
const slot = slots.find(
({ properties }) => properties.property_pointer === pointer,
);
if (slot === undefined) throw new Error(`Missing slot ${pointer}`);
expect(slot.properties.presence).toBe(
literal === null ? "absent" : "present",
);
const trace = queryJavaScriptSemanticGraph(graph, {
seed: { kind: "semantic-node", node_id: slot.node_id },
direction: "backward-provenance",
allowed_relations: ["defines"],
});
expect(
trace.nodes
.filter(({ kind }) => kind === "literal")
.map(({ properties }) => properties.value),
).toEqual(literal === null ? [] : [literal]);
const reads = graph.relations.filter(
({ source_node_id, relation }) =>
source_node_id === slot.node_id && relation === "reads-property",
);
expect(reads).toHaveLength(1);
expect(reads[0]?.resolution).toBe(
literal === null ? "candidate" : "resolved",
);
}
});
it("targets nested writes and destructuring without inventing leaf-level root slots", () => {
const graph = graphFor(`
const root = { left: { id: 'before' }, right: { id: 'untouched' } };
root.left.id = produce();
const { right: { id: selected } } = root;
const [first, missing] = [1, , 3];
`);
const rootSlots = graph.nodes.filter(
({ kind, properties }) =>
kind === "property-slot" && properties.name === "id",
);
expect(
rootSlots.map(({ properties }) => properties.property_pointer).sort(),
).toEqual(["/left/id", "/right/id"]);
const left = rootSlots.find(
({ properties }) => properties.property_pointer === "/left/id",
);
const right = rootSlots.find(
({ properties }) => properties.property_pointer === "/right/id",
);
expect(left?.properties.presence).toBe("unknown-coverage");
const write = graph.nodes.find(
({ kind, properties }) =>
kind === "expression" && properties.operation_kind === "write",
);
expect(graph.relations).toContainEqual(
expect.objectContaining({
source_node_id: write?.node_id,
target_node_id: left?.node_id,
relation: "writes-property",
resolution: "resolved",
}),
);
const selected = graph.nodes.find(
({ kind, label }) => kind === "binding" && label === "selected",
);
expect(graph.relations).toContainEqual(
expect.objectContaining({
source_node_id: right?.node_id,
target_node_id: selected?.node_id,
relation: "destructures",
resolution: "resolved",
}),
);
});
it("keeps dynamic intermediate receivers unresolved instead of selecting a static leaf", () => {
const graph = graphFor(`
const root = { id: 'root', a: { id: 'nested' } };
const selected = root[key].id;
`);
expect(
graph.relations.filter(({ relation }) => relation === "reads-property"),
).toEqual([]);
expect(graph.unknowns).toContainEqual(
expect.objectContaining({
family: "object-flow",
relation_kinds: ["reads-property"],
}),
);
const selected = graph.nodes.find(
({ kind, label }) => kind === "binding" && label === "selected",
);
if (selected === undefined) throw new Error("Missing selected binding");
const trace = queryJavaScriptSemanticGraph(graph, {
seed: { kind: "semantic-node", node_id: selected.node_id },
direction: "backward-provenance",
allowed_relations: ["defines"],
});
expect(trace.nodes.filter(({ kind }) => kind === "literal")).toEqual([]);
});
it.each([
{
initializer: "{}",
path: "missing.id",
pointer: "/missing/id",
resolved: false,
},
{
initializer: "{ a: null }",
path: "a.id",
pointer: "/a/id",
resolved: false,
},
{ initializer: "{ a: 1 }", path: "a.id", pointer: "/a/id", resolved: false },
{ initializer: "{ a: {} }", path: "a.id", pointer: "/a/id", resolved: true },
{ initializer: "{ a: [] }", path: "a[0]", pointer: "/a/0", resolved: true },
])(
"admits a write only through a retained container receiver: $initializer.$path",
({ initializer, path, pointer, resolved }) => {
const graph = graphFor(
`const root = ${initializer}; root.${path} = produce();`,
);
const write = graph.nodes.find(
({ kind, properties }) =>
kind === "expression" && properties.operation_kind === "write",
);
const slot = graph.nodes.find(
({ kind, properties }) =>
kind === "property-slot" && properties.property_pointer === pointer,
);
if (write === undefined || slot === undefined)
throw new Error("Expected write and target slot");
expect(graph.relations).toContainEqual(
expect.objectContaining({
source_node_id: write.node_id,
target_node_id: slot.node_id,
relation: "writes-property",
resolution: resolved ? "resolved" : "candidate",
}),
);
const trace = queryJavaScriptSemanticGraph(graph, {
seed: { kind: "semantic-node", node_id: write.node_id },
direction: "forward-influence",
allowed_relations: ["writes-property"],
});
expect(trace.nodes.some(({ node_id }) => node_id === slot.node_id)).toBe(
resolved,
);
if (!resolved)
expect(graph.unknowns).toContainEqual(
expect.objectContaining({
node_id: slot.node_id,
relation_kinds: ["writes-property"],
detail: expect.stringContaining(
"receiver is unresolved or not a retained container",
),
}),
);
},
);
it("retains array length presence without inventing an exact length", () => {
const graph = graphFor("const root = [, 1]; const length = root.length;");
const slot = graph.nodes.find(
({ kind, properties }) =>
kind === "property-slot" && properties.property_pointer === "/length",
);
expect(slot?.properties).toMatchObject({
name: "length",
presence: "present",
value_status: "unknown",
});
const trace = queryJavaScriptSemanticGraph(graph, {
seed: { kind: "property", name: "length" },
direction: "forward-influence",
allowed_relations: ["reads-property"],
});
expect(trace.seed_node_ids).toEqual([slot?.node_id]);
expect(trace.relations).toContainEqual(
expect.objectContaining({
source_node_id: slot?.node_id,
relation: "reads-property",
resolution: "resolved",
}),
);
expect(
graph.relations.some(
({ target_node_id, relation }) =>
target_node_id === slot?.node_id && relation === "defines",
),
).toBe(false);
});
it.each(["{}", "unknownRoot", "{ a: null }"])(
"preserves the requested deep leaf name after a blocked prefix: %s",
(initializer) => {
const graph = graphFor(
`const root = ${initializer}; const selected = root.a.b.c;`,
);
const slot = graph.nodes.find(
({ kind, properties }) =>
kind === "property-slot" && properties.property_pointer === "/a/b/c",
);
expect(slot).toMatchObject({
label: "c",
properties: {
name: "c",
property_path: ["a", "b", "c"],
presence: "unknown-coverage",
value_status: "unknown",
},
});
const trace = queryJavaScriptSemanticGraph(graph, {
seed: { kind: "property", name: "c" },
direction: "backward-provenance",
allowed_relations: ["defines"],
});
expect(trace.seed_node_ids).toEqual([slot?.node_id]);
expect(trace.nodes.filter(({ kind }) => kind === "literal")).toEqual([]);
},
);
@@ -1,3 +1,12 @@
import {
semanticSlotAtPath,
semanticContainer,
semanticPropertyPointer,
} from "../../domain/javascript/javascriptSemanticSlots.js";
import type {
JavaScriptSemanticSlotPresence,
JavaScriptSemanticValue,
} from "../../domain/javascript/javascriptSemanticValueTypes.js";
import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.js";
import type { JavaScriptSemanticGraphNode } from "../../domain/javascript/javascriptSemanticGraph.js";
import type { JavaScriptSemanticObjectOperation } from "../../domain/javascript/javascriptSemanticIr.js";
@@ -14,56 +23,115 @@ import { semanticPropertySlot } from "./JavaScriptSemanticGraphValueProjection.j
export const projectSemanticObjects = (
context: SemanticFlowProjectionContext,
): void => {
const values = new Map(
context.ir.bindings.map((binding) => [binding.bindingId, binding.value]),
);
for (const operation of context.ir.objectOperations) {
const occurrence = addObjectOccurrence(context, operation);
const slot =
operation.objectBindingId === null || operation.propertyName === null
? null
: semanticPropertySlot(
context,
operation.objectBindingId,
operation.propertyName,
);
if (operation.kind === "read")
addSemanticGraphRelation(context.state, {
source: slot,
target: occurrence,
relation: "reads-property",
resolution:
operation.resolution === "complete" ? "resolved" : "candidate",
});
else if (operation.kind === "write")
addSemanticGraphRelation(context.state, {
source: occurrence,
target: slot,
relation: "writes-property",
resolution:
operation.resolution === "complete" ? "resolved" : "candidate",
});
else if (operation.kind === "destructure")
addSemanticGraphRelation(context.state, {
source: slot,
const target = objectTarget(context, values, operation);
const ends = objectRelationEnds(context, operation, occurrence, target);
const resolved =
operation.resolution === "complete" &&
(operation.kind === "write"
? target.receiverResolved
: target.presence === "present");
addSemanticGraphRelation(context.state, {
...ends,
relation: OBJECT_RELATIONS[operation.kind],
resolution: resolved ? "resolved" : "candidate",
});
if (!resolved)
addObjectUnknown(context, operation, target.slot ?? occurrence, target);
}
};
const OBJECT_RELATIONS = {
read: "reads-property",
write: "writes-property",
destructure: "destructures",
spread: "spreads",
} as const;
interface ObjectTarget {
readonly objectNode: JavaScriptSemanticGraphNode | null | undefined;
readonly slot: JavaScriptSemanticGraphNode | null;
readonly presence: JavaScriptSemanticSlotPresence;
readonly receiverResolved: boolean;
}
const objectTarget = (
context: SemanticFlowProjectionContext,
values: ReadonlyMap<string, JavaScriptSemanticValue>,
operation: JavaScriptSemanticObjectOperation,
): ObjectTarget => {
const binding =
operation.objectBindingId === null
? undefined
: context.bindingNodes.get(operation.objectBindingId);
const value =
operation.objectBindingId === null
? undefined
: values.get(operation.objectBindingId);
if (
operation.objectBindingId === null ||
operation.propertyPath === null ||
value === undefined
)
return {
objectNode: binding,
slot: null,
presence: "unknown-coverage",
receiverResolved: false,
};
const fact = semanticSlotAtPath(value, operation.propertyPath);
if (operation.propertyPath.length === 0)
return {
objectNode: binding,
slot: null,
presence: fact.presence,
receiverResolved: semanticContainer(value) !== null,
};
const slot = semanticPropertySlot(
context,
operation.objectBindingId,
operation.propertyPath,
fact,
);
const receiver = semanticSlotAtPath(
value,
operation.propertyPath.slice(0, -1),
);
return {
objectNode: slot,
slot,
presence: fact.presence,
receiverResolved:
receiver.presence === "present" &&
semanticContainer(receiver.value) !== null,
};
};
const objectRelationEnds = (
context: SemanticFlowProjectionContext,
operation: JavaScriptSemanticObjectOperation,
occurrence: JavaScriptSemanticGraphNode | null,
target: ObjectTarget,
) => {
switch (operation.kind) {
case "read":
return { source: target.slot, target: occurrence };
case "write":
return { source: occurrence, target: target.slot };
case "destructure":
return {
source: target.slot,
target:
operation.targetBindingId === null
? undefined
: context.bindingNodes.get(operation.targetBindingId),
relation: "destructures",
resolution:
operation.resolution === "complete" ? "resolved" : "candidate",
});
else
addSemanticGraphRelation(context.state, {
source:
operation.objectBindingId === null
? undefined
: context.bindingNodes.get(operation.objectBindingId),
target: occurrence,
relation: "spreads",
resolution:
operation.resolution === "complete" ? "resolved" : "candidate",
});
if (operation.resolution !== "complete")
addObjectUnknown(context, operation, slot ?? occurrence);
};
case "spread":
return { source: target.objectNode, target: occurrence };
}
};
@@ -76,9 +144,9 @@ const addObjectOccurrence = (
roleKey: operation.objectOperationId,
location: operation.location,
label:
operation.propertyName === null
operation.propertyPath === null
? operation.kind
: `${operation.kind}:${operation.propertyName}`,
: `${operation.kind}:${semanticPropertyPointer(operation.propertyPath)}`,
functionNodeId:
operation.ownerCallableId === null
? null
@@ -86,7 +154,8 @@ const addObjectOccurrence = (
null),
properties: {
operation_kind: operation.kind,
property_name: operation.propertyName,
property_path:
operation.propertyPath === null ? null : [...operation.propertyPath],
},
});
@@ -94,15 +163,9 @@ const addObjectUnknown = (
context: SemanticFlowProjectionContext,
operation: JavaScriptSemanticObjectOperation,
node: JavaScriptSemanticGraphNode | null,
target: Pick<ObjectTarget, "presence" | "receiverResolved">,
): void => {
const relation =
operation.kind === "read"
? "reads-property"
: operation.kind === "write"
? "writes-property"
: operation.kind === "spread"
? "spreads"
: "destructures";
const relation = OBJECT_RELATIONS[operation.kind];
addSemanticGraphUnknown(
context.state,
createJavaScriptSemanticGraphUnknown({
@@ -110,7 +173,7 @@ const addObjectUnknown = (
family: "object-flow",
relation_kinds: [relation],
reason: "ambiguous-target",
detail: `Static ${operation.kind} object identity is partial.`,
detail: `Static ${operation.kind} property ${operation.propertyPath === null ? "path is unresolved" : semanticPropertyPointer(operation.propertyPath)} has ${target.presence} presence; its receiver is ${target.receiverResolved ? "a retained container" : "unresolved or not a retained container"}; object identity is ${operation.resolution}.`,
candidate_node_ids: [],
evidence: unknownSemanticEvidence(context.file, operation.location),
}),
@@ -1,259 +0,0 @@
import { expect, it } from "vitest";
import { compareCodePoints } from "../../domain/canonicalOrdering.js";
import type { JavaScriptArtifactFile } from "../../domain/javascript/javascriptArtifactFiles.js";
import { analyzeJavaScriptSemantics } from "../../domain/javascript/javascriptSemanticAnalysis.js";
import type { JavaScriptSemanticGraphNode } from "../../domain/javascript/javascriptSemanticGraph.js";
import type { JavaScriptSemanticIr } from "../../domain/javascript/javascriptSemanticIr.js";
import type { JavaScriptSourceRange } from "../../domain/javascript/javascriptStaticAnalysisTypes.js";
import {
constructSemanticGraphNode,
createSemanticGraphProjectionState,
} from "./JavaScriptSemanticGraphConstruction.js";
import {
createSemanticCallableOwnerLookup,
createSemanticNodeRangeLookup,
createSemanticCallSiteLookup,
} from "./JavaScriptSemanticGraphProjection.js";
import { sourceRangesEqual } from "../../domain/javascript/javascriptStaticAnalysisHelpers.js";
const fixtureFile: JavaScriptArtifactFile = {
path: "app.js",
container_sha256: "a".repeat(64),
sha256: "b".repeat(64),
bytes: 0,
inventory_artifact_id: "fixture-app",
kind: "javascript",
unpacked: false,
text: { included: true, value: "" },
};
const nodesFor = (ir: JavaScriptSemanticIr) => {
const state = createSemanticGraphProjectionState({ nodes: [] });
return new Map(
ir.callables.map((callable) => [
callable.callableId,
constructSemanticGraphNode(
fixtureFile,
{
kind: "function",
roleKey: callable.callableId,
label: callable.name,
location: callable.location,
functionNodeId: null,
},
state,
),
]),
);
};
// Reference behavior before the optimization, including stable ties and
// fallback when the most deeply nested callable has no retained graph node.
const previousOwner = (
location: JavaScriptSourceRange | null,
ir: JavaScriptSemanticIr,
nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
) => {
if (location === null) return undefined;
const compare = (
left: JavaScriptSourceRange["start"],
right: JavaScriptSourceRange["start"],
) => left.line - right.line || left.column - right.column;
const key = (range: JavaScriptSourceRange) =>
`${String(range.start.line).padStart(12, "0")}:${String(range.start.column).padStart(12, "0")}`;
return ir.callables
.filter(
(callable) =>
compare(callable.location.start, location.start) <= 0 &&
compare(callable.location.end, location.end) >= 0,
)
.sort((left, right) =>
compareCodePoints(key(right.location), key(left.location)),
)
.map((callable) => nodes.get(callable.callableId))
.find((node) => node !== undefined);
};
const rangesFor = (ir: JavaScriptSemanticIr) => [
null,
...ir.callables.map((callable) => callable.location),
...ir.bindings.flatMap((binding) =>
binding.definitions.map((definition) => definition.location),
),
...ir.references.map((reference) => reference.location),
{ start: { line: 999, column: 0 }, end: { line: 999, column: 1 } },
];
it("matches the prior owner selection across nested functions, arrows and methods", () => {
const ir = analyzeJavaScriptSemantics(`
const outside = 1;
function outer(parameter) {
function inner(value) { return value + parameter; }
const callback = argument => inner(argument);
return callback(outside);
}
class Example { method(value) { return () => outer(value); } }
`);
const nodes = nodesFor(ir);
const lookup = createSemanticCallableOwnerLookup(ir, nodes);
for (const range of rangesFor(ir))
expect(lookup(range)).toBe(previousOwner(range, ir, nodes));
});
it("reads retained node membership at query time and keeps file indexes independent", () => {
const ir = analyzeJavaScriptSemantics(
"function outer() { function inner() { return 1; } return inner(); }",
);
const inner = ir.callables.find((callable) => callable.name === "inner");
if (inner === undefined) throw new Error("Missing inner fixture callable");
const nodes = nodesFor(ir);
const otherNodes = nodesFor(ir);
const lookup = createSemanticCallableOwnerLookup(ir, nodes);
const otherLookup = createSemanticCallableOwnerLookup(ir, otherNodes);
const before = lookup(inner.location);
expect(before?.label).toBe("inner");
nodes.delete(inner.callableId);
expect(lookup(inner.location)?.label).toBe("outer");
expect(otherLookup(inner.location)?.label).toBe("inner");
if (before === undefined) throw new Error("Missing retained fixture node");
nodes.set(inner.callableId, before);
expect(lookup(inner.location)).toBe(before);
});
it("preserves stable ties and non-nested overlapping ranges", () => {
const original = analyzeJavaScriptSemantics(
"function first() { return 1; } function second() { return 2; } function third() { return 3; }",
);
const range = (start: number, end: number): JavaScriptSourceRange => ({
start: { line: 1, column: start },
end: { line: 1, column: end },
});
const ir = {
...original,
callables: original.callables.map((callable, index) => ({
...callable,
location: index === 0 ? range(0, 90) : range(20, index === 1 ? 60 : 80),
})),
};
const nodes = nodesFor(ir);
const lookup = createSemanticCallableOwnerLookup(ir, nodes);
for (const query of [
range(25, 30),
range(25, 70),
range(0, 80),
range(80, 90),
range(91, 92),
])
expect(lookup(query)).toBe(previousOwner(query, ir, nodes));
});
it("matches the prior result across a compiled-style collection of sibling callables", () => {
const ir = analyzeJavaScriptSemantics(
Array.from(
{ length: 300 },
(_, index) =>
`function f${String(index)}(value) { return value + ${String(index)}; }`,
).join(""),
);
const nodes = nodesFor(ir);
const lookup = createSemanticCallableOwnerLookup(ir, nodes);
for (const range of rangesFor(ir))
expect(lookup(range)).toBe(previousOwner(range, ir, nodes));
});
it("returns contained nodes in original order, including repeated and overlapping entries", () => {
const ir = analyzeJavaScriptSemantics(`
function outer(value) { function inner() { return value; } return inner(); }
const sibling = () => outer(1);
`);
const nodes = [...nodesFor(ir).values()].reverse();
const repeated = nodes[0];
if (repeated === undefined) throw new Error("Missing range fixture node");
nodes.push(
repeated,
constructSemanticGraphNode(
fixtureFile,
{
kind: "module",
roleKey: "module",
location: null,
label: "module",
functionNodeId: null,
},
createSemanticGraphProjectionState({ nodes: [] }),
),
);
const lookup = createSemanticNodeRangeLookup(nodes);
const compare = (
left: JavaScriptSourceRange["start"],
right: JavaScriptSourceRange["start"],
) => left.line - right.line || left.column - right.column;
for (const range of rangesFor(ir)) {
if (range === null) continue;
const expected = nodes.filter(
({ identity }) =>
identity.source_range !== null &&
compare(range.start, identity.source_range.start) <= 0 &&
compare(range.end, identity.source_range.end) >= 0,
);
expect(lookup(range)).toEqual(expected);
}
expect(
createSemanticNodeRangeLookup([])(
repeated.identity.source_range ?? {
start: { line: 1, column: 0 },
end: { line: 1, column: 1 },
},
),
).toEqual([]);
});
it("keeps first-call matching and current retained membership for exact locations", () => {
const original = analyzeJavaScriptSemantics(
"function target(value) { return value; } target(1); target(2);",
);
const first = original.callSites[0];
const node = [...nodesFor(original).values()][0];
if (first === undefined || node === undefined)
throw new Error("Missing call fixture");
const duplicate = { ...first, callSiteId: `${first.callSiteId}:duplicate` };
const ir = {
...original,
callSites: [first, duplicate, ...original.callSites.slice(1)],
};
const nodes = new Map(
ir.callSites.map((call) => [
call.callSiteId,
constructSemanticGraphNode(
fixtureFile,
{
kind: "call-site",
roleKey: call.callSiteId,
location: call.location,
label: call.callSiteId,
functionNodeId: null,
},
createSemanticGraphProjectionState({ nodes: [] }),
),
]),
);
const lookup = createSemanticCallSiteLookup(ir, nodes);
const previous = (range: JavaScriptSourceRange) => {
const call = ir.callSites.find((candidate) =>
sourceRangesEqual(candidate.location, range),
);
return call === undefined ? undefined : nodes.get(call.callSiteId);
};
for (const call of ir.callSites)
expect(lookup(call.location)).toBe(previous(call.location));
nodes.delete(first.callSiteId);
expect(lookup(first.location)).toBeUndefined();
expect(nodes.has(duplicate.callSiteId)).toBe(true);
nodes.set(first.callSiteId, node);
expect(lookup(first.location)).toBe(node);
expect(
lookup({ start: { line: 99, column: 0 }, end: { line: 99, column: 1 } }),
).toBeUndefined();
});
@@ -1,4 +1,8 @@
import type { JsonValue } from "../../domain/jsonValue.js";
import {
semanticContainer,
semanticPropertyPointer,
type JavaScriptSemanticSlot,
} from "../../domain/javascript/javascriptSemanticSlots.js";
import type {
JavaScriptSemanticBinding,
JavaScriptSemanticValue,
@@ -24,7 +28,7 @@ export const projectSemanticValues = (
binding,
value: binding.value,
target: bindingNode,
role: "binding",
path: [],
});
}
};
@@ -34,11 +38,13 @@ interface ValueProjectionInput {
readonly binding: JavaScriptSemanticBinding;
readonly value: JavaScriptSemanticValue;
readonly target: ReturnType<typeof semanticPropertySlot>;
readonly role: string;
readonly path: readonly string[];
}
const projectValue = (input: ValueProjectionInput): void => {
const { context, binding, value, target, role } = input;
const { context, binding, value, target, path } = input;
const role =
path.length === 0 ? "binding" : `property:${semanticPropertyPointer(path)}`;
if (target === null) return;
if (value.status === "literal") {
const literal = addLiteralNode(context, binding, value.value, role);
@@ -58,31 +64,33 @@ const projectValue = (input: ValueProjectionInput): void => {
resolution: "candidate",
});
}
else if (value.status === "object")
for (const property of value.properties) {
else if (value.status === "object" || value.status === "array") {
const container = semanticContainer(value);
for (const property of container.slots) {
const propertyPath = [...path, property.name];
const slot = semanticPropertySlot(
context,
binding.bindingId,
property.name,
propertyPath,
property,
);
if (property.presence === "absent") continue;
addSemanticGraphRelation(context.state, {
source: target,
target: slot,
relation: "writes-property",
resolution:
value.unknownProperties || property.presence === "unknown-coverage"
? "candidate"
: "resolved",
});
projectValue({
context,
binding,
value: property.value,
target: slot,
role: `property:${property.name}`,
resolution: property.presence === "present" ? "resolved" : "candidate",
});
if (property.presence === "present")
projectValue({
context,
binding,
value: property.value,
target: slot,
path: propertyPath,
});
}
else if (value.status === "unknown" && value.resourceLimit !== undefined) {
} else if (value.status === "unknown" && value.resourceLimit !== undefined) {
const location = binding.definitions[0]?.location ?? null;
const evidence = observedSemanticEvidence(context.file, location);
const isPropertyValue = role.startsWith("property:");
@@ -123,21 +131,27 @@ const addLiteralNode = (
properties: { value },
});
/** Create one canonical property slot for a binding/property identity. */
/** Create one canonical slot for a root binding and exact static property path. */
export const semanticPropertySlot = (
context: SemanticFlowProjectionContext,
objectBindingId: string,
name: string,
path: readonly string[],
fact: JavaScriptSemanticSlot,
) =>
retainSemanticGraphNode(context.state, context.file, {
kind: "property-slot",
roleKey: `property:${objectBindingId}:${name}`,
roleKey: `property:${JSON.stringify([objectBindingId, path])}`,
location: null,
label: name,
label: fact.name,
functionNodeId:
context.bindingNodes.get(objectBindingId)?.function_node_id ?? null,
properties: {
name,
name: fact.name,
property_path: [...path],
property_pointer: semanticPropertyPointer(path),
object_binding_id: objectBindingId,
} satisfies Readonly<Record<string, JsonValue>>,
presence: fact.presence,
value_status: fact.value.status,
value_coverage: semanticContainer(fact.value)?.coverage ?? null,
},
});
@@ -0,0 +1,90 @@
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import {
captureProcessScenarioFile,
projectProcessCliError,
} from "./ProcessCli.js";
const roots: string[] = [];
afterEach(async () => {
await Promise.all(
roots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
);
});
const fixture = async (): Promise<string> => {
const root = await mkdtemp(join(tmpdir(), "rea-process-cli-diagnostics-"));
roots.push(root);
return root;
};
describe("process CLI input diagnostics", () => {
it("preserves local diagnostics for unexpected process failures", () => {
const projected = projectProcessCliError(
new Error("SECRET internal failure /private/path"),
);
expect(projected).toEqual({
error: "Process command failed",
category: "execution_failure",
message:
"Process command could not complete: SECRET internal failure /private/path",
});
expect(JSON.stringify(projected)).not.toContain("stack");
});
it("projects missing, malformed JSON, and invalid scenario files", async () => {
const root = await fixture();
const malformed = join(root, "malformed.json");
const invalid = join(root, "invalid.json");
const invalidUtf8 = join(root, "invalid-utf8.json");
await writeFile(malformed, "not-json");
await writeFile(invalid, "{}");
await writeFile(
invalidUtf8,
Buffer.concat([
Buffer.from('{"executable":"'),
Buffer.from([0xff]),
Buffer.from('"}'),
]),
);
expect(
await captureProcessScenarioFile(join(root, "missing.json")),
).toEqual({
error: "Process command failed",
category: "invalid_input",
message: expect.stringContaining(
`Process input file could not be read: ${join(root, "missing.json")} (ENOENT`,
),
});
expect(await captureProcessScenarioFile(malformed)).toEqual({
error: "Process command failed",
category: "invalid_input",
message: expect.stringContaining(
`Process input file is not valid UTF-8 JSON: ${malformed}`,
),
});
expect(await captureProcessScenarioFile(invalidUtf8)).toEqual({
error: "Process command failed",
category: "invalid_input",
message: expect.stringContaining(
`Process input file is not valid UTF-8 JSON: ${invalidUtf8}`,
),
});
expect(await captureProcessScenarioFile(invalid)).toEqual({
error: "Process command failed",
code: "invalid_request",
category: "invalid_input",
message: "Analysis input is invalid. Check the arguments and try again.",
retryable: true,
remediation: { action: "Correct the listed arguments and retry." },
details: expect.objectContaining({
operation: "capture_process_scenario",
issues: expect.arrayContaining([
expect.objectContaining({ path: ["executable"] }),
]),
}),
});
});
});
+4 -7
View File
@@ -175,10 +175,9 @@ const readJson = async (path: string): Promise<unknown> => {
try {
bytes = await readFile(path);
} catch (cause: unknown) {
void cause;
throw new ProcessCliFailure(
"invalid_input",
"Process input file could not be read. Check that the path exists and is readable.",
`Process input file could not be read: ${path} (${describeValidationFailure(cause)}). Check the reported filesystem constraint and retry.`,
);
}
try {
@@ -189,10 +188,9 @@ const readJson = async (path: string): Promise<unknown> => {
const parsed: unknown = JSON.parse(text);
return parsed;
} catch (cause: unknown) {
void cause;
throw new ProcessCliFailure(
"invalid_input",
"Process input file is not valid JSON. Repair the file, then try again.",
`Process input file is not valid UTF-8 JSON: ${path} (${describeValidationFailure(cause)}). Repair the file, then try again.`,
);
}
};
@@ -211,7 +209,7 @@ const cliAnalysisError = (error: AnalysisError): ProcessCliErrorOutput => ({
...projectAnalysisError(error),
});
/** Project any process CLI failure without exposing its cause. */
/** Preserve typed failures and local diagnostics at the process CLI boundary. */
export const projectProcessCliError = (
cause: unknown,
): ProcessCliErrorOutput => {
@@ -225,7 +223,6 @@ export const projectProcessCliError = (
return {
error: "Process command failed",
category: "execution_failure",
message:
"Process command could not complete. Check the input files and run `rea doctor`, then try again.",
message: `Process command could not complete: ${describeValidationFailure(cause)}`,
};
};
+16 -6
View File
@@ -1,3 +1,4 @@
import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
import {
createAnalysisExecution,
type AnalysisClient,
@@ -30,7 +31,7 @@ import { ArtifactOperationError } from "../domain/artifactOperationError.js";
import { type AnalysisError } from "../domain/analysisErrorBase.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { interfaceBuilderLimitsSchema } from "../domain/apple/interfaceBuilderGraph.js";
import { err, ok } from "../domain/result.js";
import { err, ok, type Result } from "../domain/result.js";
import { ArtifactReaderFailure } from "./ArtifactReader.js";
import {
ARTIFACT_PROVIDER_IDENTITY as IDENTITY,
@@ -44,8 +45,13 @@ import { resolveArtifactIntegrityPolicy } from "./inventory/policy.js";
export class ArtifactProvider implements AnalysisProvider {
readonly #capabilities: readonly CapabilityDescriptor[];
readonly #platform: NodeJS.Platform;
private readonly environment: Readonly<NodeJS.ProcessEnv>;
constructor(platform: NodeJS.Platform = process.platform) {
constructor(
environment: Readonly<NodeJS.ProcessEnv>,
platform: NodeJS.Platform = process.platform,
) {
this.environment = snapshotEnvironment(environment, platform);
this.#capabilities = artifactCapabilities(platform);
this.#platform = platform;
}
@@ -59,13 +65,14 @@ export class ArtifactProvider implements AnalysisProvider {
}
createClient(target: BinaryTarget): AnalysisClient {
return new ArtifactClient(target, this.#platform);
return new ArtifactClient(target, this.environment, this.#platform);
}
}
class ArtifactClient implements AnalysisClient {
constructor(
private readonly target: BinaryTarget,
private readonly environment: Readonly<NodeJS.ProcessEnv>,
private readonly platform: NodeJS.Platform,
) {}
@@ -178,6 +185,7 @@ class ArtifactClient implements AnalysisClient {
inputPath: this.target.sourcePath ?? this.target.path,
inputFormat: this.target.format,
outputRoot: parsed.output_root,
environment: this.environment,
},
options?.signal,
);
@@ -217,8 +225,8 @@ class ArtifactClient implements AnalysisClient {
}
}
close(): Promise<void> {
return Promise.resolve();
close(): Promise<Result<null, AnalysisError>> {
return Promise.resolve(ok(null));
}
/** The active target's kind is outside this operation's supported targets. */
@@ -248,6 +256,7 @@ class ArtifactClient implements AnalysisClient {
"inspect_asset_catalog requires an active .app bundle target",
);
const result = await analyzeAppleAssetCatalogs({
environment: this.environment,
bundlePath,
targetSha256: this.target.sha256,
page: parameters,
@@ -353,6 +362,7 @@ class ArtifactClient implements AnalysisClient {
options?: ExecutionOptions,
) {
return inventoryArtifact(this.target.sourcePath ?? this.target.path, {
environment: this.environment,
...(options?.signal === undefined ? {} : { signal: options.signal }),
integrity: resolveArtifactIntegrityPolicy({
mode: parsed.integrity_policy,
@@ -393,7 +403,7 @@ const subjectFor = (
path: string,
manifest: {
readonly root_sha256: string;
readonly root_format: import("../domain/artifactGraph.js").ArtifactNode["format"];
readonly root_format: import("../domain/artifactGraph.js").ArtifactInventoryResult["manifest"]["root_format"];
},
) => ({
path,
+3 -1
View File
@@ -3,6 +3,8 @@ import { lstat, open, opendir, realpath } from "node:fs/promises";
import { isAbsolute, join, relative, sep } from "node:path";
import type { Readable } from "node:stream";
import { compareCodePoints } from "../domain/canonicalOrdering.js";
import {
ArtifactReaderFailure,
type ArtifactEntry,
@@ -47,7 +49,7 @@ export class DirectoryArtifactReader implements ArtifactReader {
await withDirectoryIoContext("inspect directory", directory, () =>
assertContainedDirectory(root, directory),
);
children.sort((left, right) => left.localeCompare(right, "en"));
children.sort(compareCodePoints);
const directories: string[] = [];
for (const name of children) {
abortIfNeeded(signal);
@@ -23,7 +23,7 @@ describe("Mach-O slice reader with system lipo", () => {
it.skipIf(process.platform !== "darwin")(
"checks real /bin/ls lipo CPU symbols and ptrauth capabilities against the FAT table",
async () => {
const reader = new MachOSliceArtifactReader("/bin/ls");
const reader = new MachOSliceArtifactReader("/bin/ls", {});
const entries = [];
for await (const entry of reader.entries()) entries.push(entry);
expect(entries.map(({ path }) => path)).toEqual([
+4 -1
View File
@@ -27,7 +27,10 @@ export class MachOSliceArtifactReader implements ArtifactReader {
constructor(
private readonly path: string,
private readonly runner: NativeCommandRunner = new XcrunCommandRunner(),
environment: Readonly<NodeJS.ProcessEnv>,
private readonly runner: NativeCommandRunner = new XcrunCommandRunner(
environment,
),
) {}
async *entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry> {
+16 -8
View File
@@ -21,6 +21,8 @@ const DETACH_TIMEOUT_MS = 120_000;
* briefly, and a volume can report busy just after it was read.
*/
const DETACH_SETTLE_DELAYS_MS = [250, 500, 1000] as const;
const delay = (milliseconds: number): Promise<void> =>
new Promise((resolve) => setTimeout(resolve, milliseconds));
const attachOutputSchema = z.object({
"system-entities": z.array(
z.object({
@@ -53,15 +55,17 @@ export interface NativeDmgHost {
delay?(milliseconds: number): Promise<void>;
}
const systemHost: NativeDmgHost = {
delay: (milliseconds) =>
new Promise((resolve) => setTimeout(resolve, milliseconds)),
const createSystemHost = (
environment: Readonly<NodeJS.ProcessEnv>,
): NativeDmgHost => ({
delay,
async run(arguments_, signal, options) {
try {
const { stdout, stderr } = await execFileOutput(
"/usr/bin/hdiutil",
[...arguments_],
{
env: environment,
...(options === undefined ? {} : { timeout: options.timeoutMs }),
...(signal === undefined ? {} : { signal }),
},
@@ -85,7 +89,7 @@ const systemHost: NativeDmgHost = {
);
}
},
};
});
/** Read-only macOS DMG adapter that owns attachment and reverse-order detach. */
export class NativeDmgArtifactReader implements ArtifactReader {
@@ -103,15 +107,19 @@ export class NativeDmgArtifactReader implements ArtifactReader {
/** Verify and attach one image beneath an exclusively owned temporary root. */
static async create(
path: string,
environment: Readonly<NodeJS.ProcessEnv>,
signal?: AbortSignal,
host: NativeDmgHost = systemHost,
host?: NativeDmgHost,
): Promise<NativeDmgArtifactReader> {
if (process.platform !== "darwin" && host === systemHost)
if (process.platform !== "darwin" && host === undefined)
throw new ArtifactReaderFailure(
"unavailable",
"Native DMG traversal is available only on macOS",
);
const reader = new NativeDmgArtifactReader(path, host);
const reader = new NativeDmgArtifactReader(
path,
host ?? createSystemHost(environment),
);
await reader.attach(signal);
return reader;
}
@@ -152,7 +160,7 @@ export class NativeDmgArtifactReader implements ArtifactReader {
// Only a device that stays attached through every recheck is a failure.
for (const delayMs of DETACH_SETTLE_DELAYS_MS) {
if (remainingDevices.length === 0) break;
await (this.host.delay ?? systemHost.delay)?.(delayMs);
await (this.host.delay ?? delay)(delayMs);
const stillAttached: string[] = [];
for (const device of remainingDevices) {
if (!(await this.#isAttached(device))) continue;
@@ -54,6 +54,7 @@ describe("Apple asset catalog application workflow", () => {
await mkdir(join(bundle, "Contents", "Resources"), { recursive: true });
await writeFile(join(bundle, "Contents", "Resources", "icon.icns"), "");
const result = await analyzeAppleAssetCatalogs({
environment: {},
bundlePath: bundle,
targetSha256: "a".repeat(64),
runAssetUtil: () => {
@@ -80,6 +81,7 @@ describe("Apple asset catalog application workflow", () => {
await writeFile(join(bundle, "outside.car"), "catalog");
await symlink("../../outside.car", join(resources, "Assets.car"));
const rejected = await analyzeAppleAssetCatalogs({
environment: {},
bundlePath: bundle,
targetSha256: "a".repeat(64),
runAssetUtil: () => Promise.resolve("[]"),
@@ -100,6 +102,7 @@ describe("Apple asset catalog application workflow", () => {
await writeFile(join(resources, "Assets.car"), "catalog");
await symlink("../Assets.car", join(resources, "Nested", "Assets.car"));
const result = await analyzeAppleAssetCatalogs({
environment: {},
bundlePath: bundle,
targetSha256: "a".repeat(64),
runAssetUtil: () => Promise.resolve("[]"),
@@ -29,6 +29,7 @@ const RESOURCE_KEY_FIELDS = new Set([
export const analyzeAppleAssetCatalogs = async (input: {
readonly bundlePath: string;
readonly targetSha256: string;
readonly environment: Readonly<NodeJS.ProcessEnv>;
readonly page?: unknown;
readonly signal?: AbortSignal;
readonly runAssetUtil?: (
@@ -60,7 +61,9 @@ export const analyzeAppleAssetCatalogs = async (input: {
const inspected = await inspectAssetCatalogEntry({
reader,
entry,
runAssetUtil: input.runAssetUtil ?? runAssetUtil,
runAssetUtil:
input.runAssetUtil ??
((path, signal) => runAssetUtil(path, input.environment, signal)),
...(input.signal === undefined ? {} : { signal: input.signal }),
});
totalMetadataBytes += inspected.metadataBytes;
@@ -222,11 +225,13 @@ export const collectInterfaceBuilderResourceKeys = (
const runAssetUtil = async (
path: string,
environment: Readonly<NodeJS.ProcessEnv>,
signal?: AbortSignal,
): Promise<string> => {
try {
return (
await execFileOutput(ASSETUTIL, ["--info", path], {
env: environment,
timeout: 60_000,
maxBuffer: MAX_CATALOG_BYTES,
...(signal === undefined ? {} : { signal }),
@@ -32,6 +32,7 @@ export interface ArtifactExtractionInput {
readonly inputPath: string;
readonly inputFormat: BinaryTarget["format"];
readonly outputRoot: string;
readonly environment: Readonly<NodeJS.ProcessEnv>;
}
/** Extract every regular inventory occurrence into an exclusively owned absent root. */
@@ -45,6 +46,7 @@ export const extractArtifact = async (
await requireExtractableFormat(sourcePath, input);
const snapshot = await scanArtifactInventory(sourcePath, {
signal,
environment: input.environment,
});
const selectedOccurrences = snapshot.occurrences.filter(
(occurrence) =>
@@ -286,14 +288,17 @@ const requireExtractableFormat = async (
const createReader = async (
path: string,
input: Pick<ArtifactExtractionInput, "inputPath" | "inputFormat">,
input: Pick<
ArtifactExtractionInput,
"inputPath" | "inputFormat" | "environment"
>,
): Promise<ArtifactReader> => {
const format = input.inputFormat;
if (await requireExtractableFormat(path, input))
return new DirectoryArtifactReader(path);
if (format === "asar") return new AsarArtifactReader(path);
if (isZipFormat(format)) return new ZipArtifactReader(path, format);
return new MachOSliceArtifactReader(path);
return new MachOSliceArtifactReader(path, input.environment);
};
const preflight = (entry: ArtifactEntry): void => {
@@ -1,3 +1,4 @@
import { compareCodePoints } from "../../domain/canonicalOrdering.js";
import { canonicalDigest } from "../../domain/comparisonSemantics.js";
import {
artifactEdgeId,
@@ -11,7 +12,10 @@ import type {
ArtifactNode,
ArtifactOccurrence,
} from "../../domain/artifactGraph.js";
import { zipPackageFormatForPath } from "../../domain/zipPackageFormat.js";
import {
hasZipSignature,
zipPackageFormatForPath,
} from "../../domain/zipPackageFormat.js";
import { mzWindowsHeaderOffset, parseDosMzHeader } from "../../domain/dosMz.js";
/** Mutable internal occurrence used until root-bound IDs are known. */
@@ -21,6 +25,8 @@ export interface MutableOccurrence {
parent_occurrence_id: string | null;
logical_path: string;
entry_kind: ArtifactOccurrence["entry_kind"];
artifact_kind: ArtifactOccurrence["artifact_kind"];
artifact_format: ArtifactOccurrence["artifact_format"];
declared_size: number | null;
compressed_size: number | null;
executable: boolean;
@@ -51,6 +57,16 @@ export const createOccurrence = (
parent_occurrence_id: parent,
logical_path: path,
entry_kind: entry.kind,
artifact_kind:
entry.kind === "directory"
? path.toLowerCase().endsWith(".framework")
? "framework"
: "container"
: classifyArtifactPath(path).kind,
artifact_format:
entry.kind === "directory"
? "directory"
: classifyArtifactPath(path).format,
declared_size: entry.declaredSize,
compressed_size: entry.compressedSize,
executable: entry.executable,
@@ -63,16 +79,8 @@ export const createOccurrence = (
limitations: [...entry.limitations],
});
/** Preserve collation order and break distinct-name ties by UTF-16 code units. */
export const compareDirectoryChildNames = (
left: string,
right: string,
): number => {
const collated = left.localeCompare(right);
if (collated !== 0) return collated;
if (left < right) return -1;
return left > right ? 1 : 0;
};
/** Compare exact child names independently of host locale and traversal order. */
export const compareDirectoryChildNames = compareCodePoints;
export const materializeDirectoryNodes = (
occurrences: MutableOccurrence[],
@@ -103,28 +111,21 @@ export const materializeDirectoryNodes = (
const node = createArtifactNode({
sha256: canonicalDigest({ kind: "directory", children }, "Artifact"),
size: 0,
kind: directory.logical_path.toLowerCase().endsWith(".framework")
? "framework"
: "container",
format: "directory",
executable: false,
contentState: "virtual",
});
const existing = nodes.get(node.artifact_id);
nodes.set(
node.artifact_id,
existing?.kind === "framework" ? existing : node,
);
nodes.set(node.artifact_id, node);
directory.artifact_id = node.artifact_id;
directory.hash_status = "verified";
}
};
export const createRootNode = (input: {
readonly path: string;
readonly format: ArtifactNode["format"];
readonly directory: boolean;
readonly digest: { readonly sha256: string; readonly bytes: number } | null;
readonly digest: {
readonly sha256: string;
readonly bytes: number;
readonly prefix: Buffer;
} | null;
readonly occurrences: readonly MutableOccurrence[];
}): ArtifactNode =>
createArtifactNode({
@@ -133,65 +134,70 @@ export const createRootNode = (input: {
canonicalDigest(
{
kind: "directory-root",
children: input.occurrences.map(({ logical_path, artifact_id }) => ({
logical_path,
artifact_id,
})),
children: input.occurrences
.map(({ logical_path, artifact_id }) => ({
logical_path,
artifact_id,
}))
.sort((left, right) =>
compareDirectoryChildNames(left.logical_path, right.logical_path),
),
},
"Artifact",
),
size: input.digest?.bytes ?? 0,
kind:
input.directory ||
["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(
input.format,
)
? "container"
: input.format === "dos-mz"
? "executable"
: classifyArtifactPath(input.path).kind,
format: input.format,
executable: false,
format:
input.digest === null
? "directory"
: classifyArtifactBytes(input.digest.prefix, input.digest.bytes),
contentState: "materialized",
});
export const createArtifactNode = (input: {
readonly sha256: string;
readonly size: number;
readonly kind: ArtifactNode["kind"];
readonly format: ArtifactNode["format"];
readonly executable: boolean;
readonly contentState: ArtifactNode["content_state"];
readonly limitations?: readonly string[];
}): ArtifactNode => ({
artifact_id: artifactIdForContent(input.sha256),
kind: input.kind,
format: input.format,
sha256: input.sha256,
size: input.size,
media_type: null,
architecture: null,
executable: input.executable,
content_state: input.contentState,
limitations: [...(input.limitations ?? [])],
limitations: [],
});
export const rootOccurrenceFor = (
node: ArtifactNode,
declaredSize: number,
metadata: {
readonly size: number;
readonly executable: boolean;
readonly format: ArtifactOccurrence["artifact_format"];
readonly path: string;
},
): MutableOccurrence => ({
occurrence_id: occurrenceIdForLocation({
rootArtifactId: node.artifact_id,
logicalPath: ".",
entryKind: node.format === "directory" ? "directory" : "file",
entryKind: metadata.format === "directory" ? "directory" : "file",
}),
artifact_id: node.artifact_id,
parent_occurrence_id: null,
logical_path: ".",
entry_kind: node.format === "directory" ? "directory" : "file",
declared_size: declaredSize,
entry_kind: metadata.format === "directory" ? "directory" : "file",
artifact_kind:
metadata.format === "directory" ||
["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(
metadata.format,
)
? "container"
: artifactRoleForFormat(metadata.path, metadata.format).kind,
artifact_format: metadata.format,
declared_size: metadata.size,
compressed_size: null,
executable: node.executable,
executable: metadata.executable,
encrypted: false,
hash_status: "verified",
source_location: null,
@@ -284,7 +290,10 @@ export const nearestParent = (
export const classifyArtifactPath = (
path: string,
): Pick<ArtifactNode, "kind" | "format"> => {
): {
readonly kind: ArtifactOccurrence["artifact_kind"];
readonly format: ArtifactOccurrence["artifact_format"];
} => {
const lower = path.toLowerCase();
if (lower.endsWith(".map"))
return { kind: "source-map", format: "source-map" };
@@ -312,29 +321,49 @@ export const classifyArtifactContent = (
path: string,
prefix: Buffer,
fileSize = prefix.length,
): Pick<ArtifactNode, "kind" | "format"> => {
): {
readonly kind: ArtifactOccurrence["artifact_kind"];
readonly format: ArtifactOccurrence["artifact_format"];
} => {
return artifactRoleForFormat(path, classifyArtifactBytes(prefix, fileSize));
};
const artifactRoleForFormat = (
path: string,
format: ArtifactOccurrence["artifact_format"],
): ReturnType<typeof classifyArtifactPath> => {
const byPath = classifyArtifactPath(path);
if (format === "file" || format === byPath.format) return byPath;
if (format === "unknown") return { kind: "unknown", format };
if (format === "zip")
return {
kind: "container",
format: zipPackageFormatForPath(path) ?? format,
};
if (format === "plist") return { kind: "plist", format };
return {
kind: ["native-addon", "dynamic-library"].includes(byPath.kind)
? byPath.kind
: ("executable" as const),
format,
};
};
/** Classify storage bytes independently of path names, roles, and permissions. */
export const classifyArtifactBytes = (
prefix: Buffer,
fileSize = prefix.length,
): ArtifactNode["format"] => {
if (hasZipSignature(prefix)) return "zip";
if (prefix.subarray(0, 8).equals(Buffer.from("bplist00"))) return "plist";
if (prefix.length >= 4) {
const magic = prefix.readUInt32BE(0);
if ([0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
return {
kind: byPath.kind === "native-addon" ? "native-addon" : "executable",
format: "mach-o-universal",
};
return "mach-o-universal";
if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic))
return {
kind: ["native-addon", "dynamic-library"].includes(byPath.kind)
? byPath.kind
: "executable",
format: "mach-o",
};
return "mach-o";
if (prefix.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
return {
kind: ["native-addon", "dynamic-library"].includes(byPath.kind)
? byPath.kind
: "executable",
format: "elf",
};
return "elf";
}
if (prefix.length >= 2 && prefix[0] === 0x4d && prefix[1] === 0x5a) {
if (
@@ -342,7 +371,7 @@ export const classifyArtifactContent = (
fileSize < prefix.length ||
prefix.length < Math.min(fileSize, 64)
)
return { kind: "unknown", format: "unknown" };
return "unknown";
const windowsOffset = mzWindowsHeaderOffset(prefix);
if (windowsOffset !== null) {
if (
@@ -352,17 +381,11 @@ export const classifyArtifactContent = (
.subarray(windowsOffset, windowsOffset + 4)
.equals(Buffer.from([0x50, 0x45, 0, 0]))
)
return {
kind: byPath.kind === "native-addon" ? "native-addon" : "executable",
format: "pe",
};
} else if (parseDosMzHeader(prefix, fileSize).ok) {
return { kind: "executable", format: "dos-mz" };
}
// Missing bounded evidence and malformed MZ bytes both remain unclassified.
return { kind: "unknown", format: "unknown" };
return "pe";
} else if (parseDosMzHeader(prefix, fileSize).ok) return "dos-mz";
return "unknown";
}
return byPath;
return "file";
};
const relationFor = (path: string): ArtifactEdge["relation"] => {
+1 -6
View File
@@ -7,7 +7,6 @@ import {
import { abortIfNeeded } from "../ArtifactHash.js";
import { scanCanonicalArtifactInventory } from "./scanCanonical.js";
import type {
ArtifactIntegrityPolicy,
ArtifactInventoryOptions,
ArtifactInventorySnapshot,
} from "./types.js";
@@ -15,7 +14,6 @@ import type {
export { scanCanonicalArtifactInventory } from "./scanCanonical.js";
export type {
ArtifactIntegrityPolicy,
ArtifactInventoryOptions,
ArtifactInventorySnapshot,
} from "./types.js";
@@ -23,10 +21,7 @@ export type {
/** Inventory one local artifact and return every graph collection inline. */
export const inventoryArtifact = async (
inputPath: string,
options: {
readonly signal?: AbortSignal;
readonly integrity?: ArtifactIntegrityPolicy;
} = {},
options: ArtifactInventoryOptions = {},
): Promise<ArtifactInventoryResult> => {
const snapshot = await scanArtifactInventory(inputPath, options);
return artifactInventoryResultSchema.parse(snapshot);
@@ -0,0 +1,132 @@
import { chmod, mkdir, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { TextReader, Uint8ArrayWriter, ZipWriter } from "@zip.js/zip.js";
import { describe, expect, it } from "vitest";
import { inventoryArtifact } from "./ArtifactInventory.js";
import { compareArtifacts } from "../../domain/artifactComparison.js";
import { createEvidence } from "../../domain/evidence.js";
import { jsonValueSchema } from "../../domain/jsonValue.js";
import { createTestTempDirectory } from "../../../tests/fixtures/temporaryDirectory.js";
const names = ["main.js", "payload.bin", "addon.node"];
const observeArchive = async (order: readonly string[]) => {
const directory = await createTestTempDirectory("rea-occurrence-identity-");
const path = join(directory, "fixture.zip");
const writer = new ZipWriter(new Uint8ArrayWriter());
for (const name of order)
await writer.add(name, new TextReader("same content\n"), {
lastModDate: new Date("2020-01-01T00:00:00Z"),
executable: name === "addon.node",
});
await writeFile(path, await writer.close());
const inventory = await inventoryArtifact(path);
const evidence = createEvidence(
{ path, sha256: inventory.manifest.root_sha256, format: "zip" },
{ id: "rea-artifact-graph", name: "artifact inventory", version: "1" },
{
operation: "inventory_artifact",
parameters: {},
result: jsonValueSchema.parse(inventory),
confidence: "observed",
authority: "shipped-artifact",
},
);
return { inventory, evidence };
};
describe("content identity and occurrence facts", () => {
it("retains all roles and permissions for identical bytes in either archive order", async () => {
const left = await observeArchive(names);
const right = await observeArchive([...names].reverse());
const childNodes = (inventory: typeof left.inventory) =>
inventory.nodes.filter(
(node) => node.artifact_id !== inventory.manifest.root_artifact_id,
);
expect(childNodes(left.inventory)).toEqual(childNodes(right.inventory));
expect(childNodes(left.inventory)).toHaveLength(1);
expect(childNodes(left.inventory)[0]).toMatchObject({ format: "file" });
expect(childNodes(left.inventory)[0]).not.toHaveProperty("kind");
expect(childNodes(left.inventory)[0]).not.toHaveProperty("executable");
const occurrences = left.inventory.occurrences.filter(
(item) => item.logical_path !== ".",
);
expect(new Set(occurrences.map((item) => item.artifact_id)).size).toBe(1);
expect(
occurrences.map(
({ logical_path, artifact_kind, artifact_format, executable }) => ({
logical_path,
artifact_kind,
artifact_format,
executable,
}),
),
).toEqual([
{
logical_path: "addon.node",
artifact_kind: "native-addon",
artifact_format: "file",
executable: true,
},
{
logical_path: "main.js",
artifact_kind: "javascript",
artifact_format: "javascript-bundle",
executable: false,
},
{
logical_path: "payload.bin",
artifact_kind: "resource",
artifact_format: "file",
executable: false,
},
]);
expect(
compareArtifacts(left.evidence, right.evidence).changes.map(
(item) => item.logical_path,
),
).toEqual(["."]);
});
it("keeps framework and ordinary directory roles separate for identical trees", async () => {
const root = await createTestTempDirectory("rea-directory-roles-");
for (const name of ["Widget.framework", "resources"])
await mkdir(join(root, name));
const inventory = await inventoryArtifact(root);
const entries = inventory.occurrences.filter(
(item) => item.logical_path !== ".",
);
expect(entries[0]?.artifact_id).toBe(entries[1]?.artifact_id);
expect(entries.map((item) => item.artifact_kind).sort()).toEqual([
"container",
"framework",
]);
expect(
inventory.nodes.filter((node) => node.content_state === "virtual"),
).toHaveLength(1);
});
it("reports only an occurrence permission change for identical content", async () => {
const root = await createTestTempDirectory("rea-permission-identity-");
const path = join(root, "payload.bin");
await writeFile(path, "same content\n", { mode: 0o600 });
const before = await inventoryArtifact(root);
await chmod(path, 0o700);
const after = await inventoryArtifact(root);
expect(before.nodes).toEqual(after.nodes);
expect(before.manifest.root_artifact_id).toBe(
after.manifest.root_artifact_id,
);
const oldFile = before.occurrences.find(
(item) => item.logical_path === "payload.bin",
);
const newFile = after.occurrences.find(
(item) => item.logical_path === "payload.bin",
);
expect(oldFile?.artifact_id).toBe(newFile?.artifact_id);
expect(oldFile?.executable).toBe(false);
expect(newFile?.executable).toBe(true);
});
});
+3 -3
View File
@@ -2,7 +2,7 @@ import { open } from "node:fs/promises";
import { classifyArtifactContent } from "./ArtifactGraphConstruction.js";
import { ARTIFACT_CLASSIFICATION_PREFIX_BYTES } from "../ArtifactHash.js";
import type { ArtifactNode } from "../../domain/artifactGraph.js";
import type { ArtifactOccurrence } from "../../domain/artifactGraph.js";
import {
hasZipSignature,
zipPackageFormatForPath,
@@ -10,7 +10,7 @@ import {
const classifyContainerExtension = (
path: string,
): ArtifactNode["format"] | undefined => {
): ArtifactOccurrence["artifact_format"] | undefined => {
const lower = path.toLowerCase();
const zipPackage = zipPackageFormatForPath(lower);
if (zipPackage !== undefined) return zipPackage;
@@ -22,7 +22,7 @@ const classifyContainerExtension = (
export const classifyRoot = async (
path: string,
directory: boolean,
): Promise<ArtifactNode["format"]> => {
): Promise<ArtifactOccurrence["artifact_format"]> => {
if (directory) return "directory";
const extensionFormat = classifyContainerExtension(path);
if (extensionFormat !== undefined) return extensionFormat;
+6 -5
View File
@@ -4,11 +4,12 @@ import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";
import { NativeDmgArtifactReader } from "../NativeDmgArtifactReader.js";
import { ZipArtifactReader } from "../ZipArtifactReader.js";
import type { ArtifactNode } from "../../domain/artifactGraph.js";
import type { ArtifactOccurrence } from "../../domain/artifactGraph.js";
export const createReader = async (
path: string,
format: ArtifactNode["format"],
format: ArtifactOccurrence["artifact_format"],
environment: Readonly<NodeJS.ProcessEnv>,
signal?: AbortSignal,
): Promise<ArtifactReader | undefined> => {
switch (format) {
@@ -24,18 +25,18 @@ export const createReader = async (
return new AsarArtifactReader(path);
case "mach-o-universal":
return process.platform === "darwin"
? new MachOSliceArtifactReader(path)
? new MachOSliceArtifactReader(path, environment)
: undefined;
case "dmg":
if (process.platform !== "darwin") return undefined;
return NativeDmgArtifactReader.create(path, signal);
return NativeDmgArtifactReader.create(path, environment, signal);
default:
return undefined;
}
};
export const inventoryLimitations = (
format: ArtifactNode["format"],
format: ArtifactOccurrence["artifact_format"],
reader: ArtifactReader | undefined,
): string[] => {
if (reader !== undefined) return [];
+28 -12
View File
@@ -1,3 +1,5 @@
import { compareCodePoints } from "../../domain/canonicalOrdering.js";
import { createReadStream } from "node:fs";
import { lstat } from "node:fs/promises";
import type { Stats } from "node:fs";
@@ -10,6 +12,7 @@ import {
artifactInventoryResultSchema,
type ArtifactInventoryResult,
type ArtifactNode,
type ArtifactOccurrence,
type IntegrityContradiction,
} from "../../domain/artifactGraph.js";
import {
@@ -49,7 +52,12 @@ export const scanCanonicalArtifactInventory = async (
const rootDigest = metadata.isDirectory()
? null
: await hashReadable(createReadStream(path), options.signal);
const reader = await createReader(path, rootFormat, options.signal);
const reader = await createReader(
path,
rootFormat,
options.environment ?? {},
options.signal,
);
try {
const { nodes, occurrences, pendingContradictions } = await scanReader(
@@ -76,7 +84,7 @@ export const scanCanonicalArtifactInventory = async (
interface SnapshotBuildInput {
readonly path: string;
readonly metadata: Stats;
readonly rootFormat: ArtifactNode["format"];
readonly rootFormat: ArtifactOccurrence["artifact_format"];
readonly rootDigest: HashResult | null;
readonly reader: ArtifactReader | undefined;
readonly signal: AbortSignal | undefined;
@@ -91,15 +99,17 @@ const buildInventorySnapshot = async (
const { path, metadata, rootFormat, rootDigest, reader, signal } = input;
materializeDirectoryNodes(input.occurrences, input.nodes);
const rootNode = createRootNode({
path,
format: rootFormat,
directory: metadata.isDirectory(),
digest: rootDigest,
occurrences: input.occurrences,
});
input.nodes.set(rootNode.artifact_id, rootNode);
rekeyOccurrences(rootNode.artifact_id, input.occurrences);
const rootOccurrence = rootOccurrenceFor(rootNode, metadata.size);
const rootOccurrence = rootOccurrenceFor(rootNode, {
size: metadata.size,
executable: (metadata.mode & 0o111) !== 0,
format: rootFormat,
path,
});
for (const occurrence of input.occurrences)
if (occurrence.parent_occurrence_id === null)
occurrence.parent_occurrence_id = rootOccurrence.occurrence_id;
@@ -125,7 +135,10 @@ const buildInventorySnapshot = async (
);
const orderedNodes = sortNodes([...input.nodes.values()]);
const orderedOccurrences = sortOccurrences(input.occurrences);
const orderedEdges = sortEdges(edges);
const orderedEdges = sortEdges(edges).map((edge, ordinal) => ({
...edge,
ordinal,
}));
await verifyRootDigest(path, rootDigest, signal);
@@ -137,6 +150,7 @@ const buildInventorySnapshot = async (
});
const manifest = buildManifest({
rootNode,
rootFormat,
graphSha256,
orderedNodes,
orderedOccurrences,
@@ -212,27 +226,29 @@ const verifyRootDigest = async (
const sortNodes = (nodes: ArtifactNode[]): ArtifactNode[] =>
nodes.sort((left, right) =>
left.artifact_id.localeCompare(right.artifact_id),
compareCodePoints(left.artifact_id, right.artifact_id),
);
const sortOccurrences = (
occurrences: MutableOccurrence[],
): MutableOccurrence[] =>
occurrences.sort((left, right) =>
left.logical_path.localeCompare(right.logical_path, "en"),
compareCodePoints(left.logical_path, right.logical_path),
);
const sortEdges = <T extends { edge_id: string }>(edges: T[]): T[] =>
edges.sort((left, right) => left.edge_id.localeCompare(right.edge_id));
edges.sort((left, right) => compareCodePoints(left.edge_id, right.edge_id));
const buildManifest = ({
rootNode,
rootFormat,
graphSha256,
orderedNodes,
orderedOccurrences,
orderedEdges,
}: {
readonly rootNode: ArtifactNode;
readonly rootFormat: ArtifactOccurrence["artifact_format"];
readonly graphSha256: string;
readonly orderedNodes: readonly ArtifactNode[];
readonly orderedOccurrences: readonly unknown[];
@@ -242,7 +258,7 @@ const buildManifest = ({
manifest_id: artifactManifestId(rootNode.artifact_id, graphSha256),
root_artifact_id: rootNode.artifact_id,
root_sha256: rootNode.sha256,
root_format: rootNode.format,
root_format: rootFormat,
graph_sha256: graphSha256,
node_count: orderedNodes.length,
occurrence_count: orderedOccurrences.length,
@@ -250,7 +266,7 @@ const buildManifest = ({
});
const buildLimitations = (
rootFormat: ArtifactNode["format"],
rootFormat: ArtifactOccurrence["artifact_format"],
reader: ArtifactReader | undefined,
integrityContradictions: readonly IntegrityContradiction[],
): string[] => [
+16 -10
View File
@@ -13,6 +13,7 @@ import { AsarArtifactReader } from "../AsarArtifactReader.js";
import type { ArtifactNode } from "../../domain/artifactGraph.js";
import {
classifyArtifactContent,
classifyArtifactBytes,
createArtifactNode,
createOccurrence,
nearestParent,
@@ -130,7 +131,11 @@ const visitArtifactEntries = async (
);
const occurrence = createOccurrence(entry, logicalPath, null);
let digested:
| { readonly node: ArtifactNode; readonly mismatched: boolean }
| {
readonly node: ArtifactNode;
readonly mismatched: boolean;
readonly classification: ReturnType<typeof classifyArtifactContent>;
}
| undefined;
try {
digested = await digestArtifactEntry(
@@ -147,6 +152,8 @@ const visitArtifactEntries = async (
if (digested !== undefined) {
context.nodes.set(digested.node.artifact_id, digested.node);
occurrence.artifact_id = digested.node.artifact_id;
occurrence.artifact_kind = digested.classification.kind;
occurrence.artifact_format = digested.classification.format;
occurrence.hash_status = digested.mismatched
? "mismatched"
: "verified";
@@ -187,7 +194,12 @@ const digestArtifactEntry = async (
entry: ArtifactEntry,
logicalPath: string,
): Promise<
{ readonly node: ArtifactNode; readonly mismatched: boolean } | undefined
| {
readonly node: ArtifactNode;
readonly mismatched: boolean;
readonly classification: ReturnType<typeof classifyArtifactContent>;
}
| undefined
> => {
if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)
return undefined;
@@ -226,17 +238,11 @@ const digestArtifactEntry = async (
node: createArtifactNode({
sha256: digest.sha256,
size: digest.bytes,
kind: classified.kind,
format: classified.format,
executable: entry.executable,
format: classifyArtifactBytes(digest.prefix, digest.bytes),
contentState: "embedded",
limitations: mismatched
? [
"Observed content contradicts declared integrity metadata and is untrusted.",
]
: [],
}),
mismatched,
classification: classified,
};
};
+1
View File
@@ -11,6 +11,7 @@ export const STRICT_INTEGRITY_POLICY: ArtifactIntegrityPolicy = {
export interface ArtifactInventoryOptions {
readonly signal?: AbortSignal | undefined;
readonly integrity?: ArtifactIntegrityPolicy | undefined;
readonly environment?: Readonly<NodeJS.ProcessEnv> | undefined;
}
export type { ArtifactInventorySnapshot } from "../../domain/artifactInventorySnapshot.js";
-2
View File
@@ -64,8 +64,6 @@ import { discoverWebMcp } from "./CdpWebMcpDiscovery.js";
import { captureCdpScreenshot } from "./CdpScreenshot.js";
import { comparePngScreenshots } from "./PngVisualDiff.js";
/** Public identity committed by passive browser observations. */
export { CDP_BROWSER_PROVIDER_IDENTITY } from "./providerIdentities.js";
import { CDP_BROWSER_PROVIDER_IDENTITY } from "./providerIdentities.js";
const IDENTITY = CDP_BROWSER_PROVIDER_IDENTITY;
const CLEANUP_DOMAINS = ["Network", "Debugger", "Runtime", "Page"] as const;
+3 -10
View File
@@ -7,6 +7,7 @@ import {
numberValue,
recordValue,
recordsValue,
scriptMetadataValues,
cdpStringValue,
type UnknownRecord,
} from "./CdpCaptureValues.js";
@@ -84,15 +85,7 @@ export const handleScriptParsed = (
rawUrl,
url: sanitized.url,
origin: sanitized.origin,
hash: cdpStringValue(params.hash) ?? "",
length: Math.max(
0,
Math.min(
Number.MAX_SAFE_INTEGER,
Math.trunc(numberValue(params.length) ?? 0),
),
),
isModule: params.isModule === true,
...scriptMetadataValues(params),
language: cdpStringValue(params.scriptLanguage) ?? null,
executionContextKey: executionContextKey(params.executionContextId),
};
@@ -135,7 +128,7 @@ const scriptMetadataStringBytes = (script: {
readonly rawUrl: string;
readonly url: string;
readonly origin: string | null;
readonly hash: string;
readonly hash: string | null;
readonly language: string | null;
readonly executionContextKey: string | null;
}): number =>
+3 -3
View File
@@ -5,9 +5,9 @@ export interface CapturedScript {
readonly rawUrl: string;
readonly url: string;
readonly origin: string | null;
readonly hash: string;
readonly length: number;
readonly isModule: boolean;
readonly hash: string | null;
readonly length: number | null;
readonly isModule: boolean | null;
readonly language: string | null;
readonly sourceMapUrl: string | null;
readonly sourceMapRawUrl: string | null;
+33
View File
@@ -26,6 +26,25 @@ export const cdpStringValue = (value: unknown): string | undefined =>
export const numberValue = (value: unknown): number | undefined =>
typeof value === "number" && Number.isFinite(value) ? value : undefined;
/** Preserve partial script declarations; omitted or invalid fields remain unknown. */
export const scriptMetadataValues = (
value: UnknownRecord | undefined,
): {
readonly hash: string | null;
readonly length: number | null;
readonly isModule: boolean | null;
} => {
const length = numberValue(value?.length);
return {
hash: cdpStringValue(value?.hash) ?? null,
length:
length !== undefined && Number.isSafeInteger(length) && length >= 0
? length
: null,
isModule: typeof value?.isModule === "boolean" ? value.isModule : null,
};
};
export const requiredRecord = (value: unknown): UnknownRecord => {
const record = recordValue(value);
if (record === undefined)
@@ -33,6 +52,20 @@ export const requiredRecord = (value: unknown): UnknownRecord => {
return record;
};
/** Require producer source text; an absent source is distinct from an empty script. */
export const requiredScriptSource = (
value: unknown,
operation: BrowserObservationOperation,
): string => {
const source = cdpStringValue(recordValue(value)?.scriptSource);
if (source === undefined)
throw new BrowserObservationError(operation, "protocol_error", {
detail:
"Debugger.getScriptSource returned malformed source text: scriptSource must be a string.",
});
return source;
};
export const isHttpUrl = (value: string | undefined): boolean => {
if (value === undefined) return false;
try {
-2
View File
@@ -29,8 +29,6 @@ import {
import { inspectCdpElectronPage } from "./CdpElectronInspection.js";
import { authorizedElectronFile } from "./ElectronFileScope.js";
/** Public identity committed by passive Electron observations. */
export { CDP_ELECTRON_PROVIDER_IDENTITY } from "./providerIdentities.js";
import { CDP_ELECTRON_PROVIDER_IDENTITY } from "./providerIdentities.js";
const IDENTITY = CDP_ELECTRON_PROVIDER_IDENTITY;
+5 -11
View File
@@ -3,15 +3,16 @@ import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
import {
numberValue,
recordValue,
scriptMetadataValues,
cdpStringValue,
} from "./CdpCaptureValues.js";
export interface ElectronScriptDraft {
readonly scriptId: string;
readonly rawUrl: string;
readonly hash: string;
readonly length: number;
readonly isModule: boolean;
readonly hash: string | null;
readonly length: number | null;
readonly isModule: boolean | null;
readonly language: string | null;
readonly executionContextKey: string | null;
}
@@ -52,9 +53,7 @@ export const ingestElectronScriptEvent = (input: {
input.scripts.push({
scriptId,
rawUrl,
hash: cdpStringValue(value?.hash) ?? "",
length: nonnegativeInteger(value?.length),
isModule: value?.isModule === true,
...scriptMetadataValues(value),
language: cdpStringValue(value?.scriptLanguage) ?? null,
executionContextKey: executionContextKey(value?.executionContextId),
});
@@ -72,11 +71,6 @@ const retainExecutionContext = (
frames.set(contextKey, frameId);
};
const nonnegativeInteger = (value: unknown): number => {
const number = numberValue(value);
return number === undefined ? 0 : Math.max(0, Math.trunc(number));
};
const executionContextKey = (value: unknown): string | null => {
const identifier = numberValue(value);
return identifier !== undefined && Number.isSafeInteger(identifier)
+3 -3
View File
@@ -6,7 +6,7 @@ import { canonicalDigest } from "../domain/comparisonSemantics.js";
import { createWebTextArtifact } from "../domain/webContentArtifact.js";
import type { CdpConnection } from "./CdpConnection.js";
import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
import { requiredRecord, cdpStringValue } from "./CdpCaptureValues.js";
import { requiredScriptSource } from "./CdpCaptureValues.js";
import type { ElectronScriptDraft } from "./CdpElectronScriptEvents.js";
import { authorizedElectronFile } from "./ElectronFileScope.js";
@@ -86,15 +86,15 @@ const captureScriptSource = async (
reason: "source capture was not selected",
},
};
const result = requiredRecord(
const text = requiredScriptSource(
await input.connection.send(
"Debugger.getScriptSource",
{ scriptId: script.scriptId },
input.sessionId,
input.signal,
),
"inspect_electron_page",
);
const text = cdpStringValue(result.scriptSource) ?? "";
return {
source: {
included: true,
+3 -4
View File
@@ -7,10 +7,9 @@ import type { CapturedResource } from "./CdpCaptureDocuments.js";
import type { CdpCaptureEvents } from "./CdpCaptureEvents.js";
import type { CapturedScript } from "./CdpCaptureEventTypes.js";
import {
requiredRecord,
requiredScriptSource,
sourceExcluded,
sourceResult,
cdpStringValue,
} from "./CdpCaptureValues.js";
import type { CaptureContext } from "./CdpPageCapture.js";
import type { WebSourceMapRequest } from "./WebSourceMapFetcher.js";
@@ -107,15 +106,15 @@ const captureScriptSource = async (
state: ScriptDraftState,
): Promise<WebPageInspection["scripts"]["items"][number]["source"]> => {
const { context } = state;
const result = requiredRecord(
const content = requiredScriptSource(
await context.connection.send(
"Debugger.getScriptSource",
{ scriptId: script.scriptId },
context.sessionId,
context.signal,
),
context.operation,
);
const content = cdpStringValue(result.scriptSource) ?? "";
return sourceResult(content);
};
@@ -29,19 +29,6 @@ import type {
} from "./BrowserScenarioSessionPort.js";
const OPERATION = "capture_browser_scenario" as const;
let defaultFactory: Promise<BrowserScenarioSessionFactory> | undefined;
const lazyPlaywrightFactory: BrowserScenarioSessionFactory = {
async open(scenario, options) {
defaultFactory ??= import("./PlaywrightScenarioSession.js").then(
({ PlaywrightScenarioSessionFactory }) =>
new PlaywrightScenarioSessionFactory(),
);
return (await defaultFactory).open(scenario, options);
},
};
export { PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY } from "./providerIdentities.js";
import { PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY } from "./providerIdentities.js";
type SnapshotKind = BrowserScenario["capture"]["after_each_step"][number];
@@ -310,9 +297,7 @@ const runScenario = async (
/** Controlled Playwright/CDP scenario driver with exact process ownership. */
export class PlaywrightBrowserScenarioProvider implements BrowserScenarioCapturePort {
constructor(
private readonly factory: BrowserScenarioSessionFactory = lazyPlaywrightFactory,
) {}
constructor(private readonly factory: BrowserScenarioSessionFactory) {}
identity(): ProviderIdentity {
return PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY;
@@ -9,17 +9,39 @@ import {
import { createElectronActiveObservationFixtureResult } from "../domain/javascript/electronActiveObservation.fixture.js";
import { runElectronActions } from "./PlaywrightElectronActiveActions.js";
it("keeps legacy Electron results explicit about unavailable retention data", () => {
const { retention: _retention, ...legacyResult } =
createElectronActiveObservationFixtureResult("/opt/app");
const parsed = electronActiveObservationResultSchema.parse({
...legacyResult,
ipc: { ...legacyResult.ipc, dropped: undefined },
timeline: { ...legacyResult.timeline, dropped: undefined },
});
expect(parsed.retention).toBeNull();
expect(parsed.ipc.dropped).toBeNull();
expect(parsed.timeline.dropped).toBeNull();
it("requires observed Electron retention and coverage instead of repairing old results", () => {
const result = createElectronActiveObservationFixtureResult("/opt/app");
for (const field of ["retention", "timeline", "coverage"] as const) {
expect(
electronActiveObservationResultSchema.safeParse({
...result,
[field]: undefined,
}).success,
).toBe(false);
}
for (const section of ["ipc", "timeline"] as const) {
expect(
electronActiveObservationResultSchema.safeParse({
...result,
[section]: { ...result[section], dropped: undefined },
}).success,
).toBe(false);
}
expect(
electronActiveObservationResultSchema.safeParse({
...result,
retention: null,
}).success,
).toBe(false);
expect(
electronActiveObservationResultSchema.safeParse({
...result,
ipc: {
...result.ipc,
events: [{ ...result.ipc.events[0], source: undefined }],
},
}).success,
).toBe(false);
});
it("parses window, renderer, and deep-link actions for agents", () => {
@@ -246,7 +268,7 @@ it("accepts complete Electron input and observation strings", () => {
title: longText,
},
],
ipc: { events: [event], observed: 1 },
ipc: { events: [event], observed: 1, dropped: 0 },
timeline: {
events: [
{
@@ -258,6 +280,7 @@ it("accepts complete Electron input and observation strings", () => {
},
],
observed: 1,
dropped: 0,
},
limitations: [longText],
});
+8 -61
View File
@@ -3,71 +3,16 @@ import { z } from "zod";
import type { ExecutionOptions } from "../application/AnalysisProvider.js";
import { BrowserObservationError } from "../domain/browserObservationError.js";
import type {
ElectronActiveObservationInput,
ElectronActiveObservationResult,
import {
electronActiveTimelineEventSchema,
type ElectronActiveObservationInput,
type ElectronActiveObservationResult,
} from "../domain/javascript/electronActiveObservation.js";
const OPERATION = "capture_electron_scenario" as const;
const hookEventSchema = z.strictObject({
sequence: z.number().int().min(1),
correlation_id: z.string().nullable(),
kind: z.enum([
"main-handler-invocation",
"main-event-invocation",
"utility-process-fork",
"utility-process-message",
"ipc-main-to-renderer",
"ipc-utility-to-main",
"ipc-renderer-send",
"ipc-renderer-invoke",
"ipc-renderer-post-message",
"app-lifecycle",
"window-lifecycle",
"web-contents-lifecycle",
"navigation",
"shell-attempt",
"process-lifecycle",
"permission",
"popup-attempt",
"download",
"protocol",
"preload",
"native-addon",
"updater",
"error",
]),
event: z.string().nullable(),
phase: z.enum(["attempted", "completed", "blocked", "failed", "observed"]),
channel: z.string().nullable(),
direction: z
.enum([
"renderer-to-main",
"main-to-renderer",
"main-to-utility",
"utility-to-main",
])
.nullable(),
sender: z.string().nullable(),
receiver: z.string().nullable(),
frame: z.string().nullable(),
target: z.string().nullable(),
argument_shapes: z.array(z.string()),
result_shape: z.string().nullable(),
process_type: z.string().nullable(),
source: z.string(),
capture_method: z.enum(["api-wrapper", "event-emitter", "process-hook"]),
artifact_path: z.string().nullable(),
artifact_sha256: z
.string()
.regex(/^[a-f0-9]{64}$/u)
.nullable(),
error: z.boolean(),
});
const hookSnapshotSchema = z.strictObject({
events: z.array(hookEventSchema),
events: z.array(electronActiveTimelineEventSchema),
retention_budget_bytes: z.number().int().min(0),
estimated_retained_bytes: z.number().int().min(0),
event_serialized_byte_upper_bound: z.number().int().min(0),
@@ -113,7 +58,9 @@ type ElectronAction = ElectronActiveObservationInput["actions"][number];
type ElectronActions = ElectronActiveObservationResult["actions"];
export type ElectronHookSnapshot = z.infer<typeof hookSnapshotSchema>;
export type ElectronHookEvent = z.infer<typeof hookEventSchema>;
export type ElectronHookEvent = z.infer<
typeof electronActiveTimelineEventSchema
>;
export type ElectronMetrics = z.infer<typeof metricSchema>[];
type ElectronWindowMetadata = z.infer<typeof windowMetadataSchema>;
@@ -0,0 +1,35 @@
import { afterEach, expect, it, vi } from "vitest";
import { electronActiveObservationInputSchema } from "../domain/javascript/electronActiveObservation.js";
import { PlaywrightElectronActiveProvider } from "./PlaywrightElectronActiveProvider.js";
afterEach(() => vi.unstubAllEnvs());
it("passes the selected environment and ownership token to Electron launch", async () => {
vi.stubEnv("LANG", "ambient-language");
let launchedEnvironment: unknown;
const provider = new PlaywrightElectronActiveProvider(
{
LANG: "selected-language",
PATH: "/selected/bin",
REA_PRIVATE_VALUE: "not-a-launch-setting",
},
async (options) => {
launchedEnvironment = options?.env;
throw new Error("launch boundary reached");
},
);
const result = await provider.capture(
electronActiveObservationInputSchema.parse({
executable_path: process.execPath,
application_path: process.execPath,
}),
);
expect(result.ok).toBe(false);
expect(launchedEnvironment).toEqual({
LANG: "selected-language",
PATH: "/selected/bin",
REA_PROCESS_RUN_ID: expect.any(String),
});
});

Some files were not shown because too many files have changed in this diff Show More