chore: integrate canonical Evidence changes for MCP error delivery
This commit is contained in:
@@ -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.",
|
||||
|
||||
@@ -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
@@ -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>>[] = [];
|
||||
|
||||
@@ -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. */
|
||||
|
||||
@@ -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,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. */
|
||||
|
||||
@@ -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");
|
||||
});
|
||||
|
||||
@@ -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);
|
||||
},
|
||||
);
|
||||
@@ -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,
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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
@@ -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,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);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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,
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
@@ -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" },
|
||||
|
||||
@@ -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,
|
||||
),
|
||||
};
|
||||
};
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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[],
|
||||
|
||||
@@ -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 }
|
||||
|
||||
@@ -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 = [
|
||||
|
||||
@@ -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),
|
||||
),
|
||||
});
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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,
|
||||
}),
|
||||
);
|
||||
|
||||
@@ -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 =
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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"] }),
|
||||
]),
|
||||
}),
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -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)}`,
|
||||
};
|
||||
};
|
||||
|
||||
@@ -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,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([
|
||||
|
||||
@@ -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> {
|
||||
|
||||
@@ -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"] => {
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
|
||||
@@ -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 [];
|
||||
|
||||
@@ -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[] => [
|
||||
|
||||
@@ -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,
|
||||
};
|
||||
};
|
||||
|
||||
|
||||
@@ -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";
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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 =>
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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],
|
||||
});
|
||||
|
||||
@@ -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
Reference in New Issue
Block a user