merge: integrate main and retain per-slice FAT alignment

This commit is contained in:
64579525
2026-10-13 16:21:36 +08:00
74 changed files with 2682 additions and 566 deletions
+6 -2
View File
@@ -78,7 +78,9 @@ export const readJsonObjectFile = (
value === null ||
Array.isArray(value)
)
throw new TypeError("JSON document root must be an object");
return err(
invalidJson(operation, "JSON document root must be an object"),
);
for (const members of scans)
for (const [key, member] of members) {
if (!Object.hasOwn(value, key)) continue;
@@ -177,7 +179,9 @@ export const readJsonObjectFile = (
signal === undefined ? {} : { signal },
);
if (!rootObject)
throw new TypeError("JSON document root must be an object");
return err(
invalidJson(operation, "JSON document root must be an object"),
);
const digest = hash.digest("hex");
if (previousDigest !== undefined && digest !== previousDigest)
throw new RegularFileChangedError(path);
+1 -1
View File
@@ -23,7 +23,7 @@ export const createProgressReporter = (
} = {},
): ProgressReporter => {
const minimumIntervalMs = options.minimumIntervalMs ?? 100;
const now = options.now ?? Date.now;
const now = options.now ?? (() => performance.now());
let lastCompleted = -1;
let lastSentAt = Number.NEGATIVE_INFINITY;
let sequence = 0;
@@ -104,7 +104,11 @@ const resolveInternalSpecifier = (
]);
// Retain present runtime files first; substitute only a missing counterpart.
// Counterparts cover explicit filenames, not directory/index resolution.
candidates.push(...typescriptEmittedSourceCandidates(fromPath, normalized));
candidates.push(
...typescriptEmittedSourceCandidates(fromPath, normalized).map(
({ path }) => path,
),
);
const match = lookupPath.resolveCandidates(candidates);
return match === undefined
? { to: normalized, resolution: "unresolved" }
@@ -8,6 +8,11 @@ const EMITTED_SUFFIXES: ReadonlyArray<
[".jsx", [".tsx", ".d.ts"]],
];
export interface TypeScriptEmittedSourceCandidate {
readonly path: string;
readonly kind: "implementation" | "declaration";
}
/**
* Return TypeScript source counterparts for an explicit emitted filename.
* Callers retain exact runtime-file precedence and must not use these for
@@ -16,7 +21,7 @@ const EMITTED_SUFFIXES: ReadonlyArray<
export const typescriptEmittedSourceCandidates = (
sourcePath: string,
candidate: string,
): readonly string[] => {
): readonly TypeScriptEmittedSourceCandidate[] => {
if (!/\.(?:ts|tsx|mts|cts)$/u.test(sourcePath)) return [];
const emitted = EMITTED_SUFFIXES.find(([suffix]) =>
candidate.endsWith(suffix),
@@ -25,5 +30,8 @@ export const typescriptEmittedSourceCandidates = (
// Strip the matched suffix by length. posix.extname would miss dotfile
// names such as ".js", whose whole basename is the emitted suffix itself.
const stem = candidate.slice(0, candidate.length - emitted[0].length);
return emitted[1].map((suffix) => `${stem}${suffix}`);
return emitted[1].map((suffix) => ({
path: `${stem}${suffix}`,
kind: suffix.startsWith(".d.") ? "declaration" : "implementation",
}));
};
+1
View File
@@ -22,6 +22,7 @@ export interface WebModuleArtifacts extends SelectedWebScriptArtifacts {
/** Read selected local artifacts without refetching website assets. */
export interface WebModuleArtifactPort {
close?(): Promise<void>;
load(
input: WebModuleTraceInput,
options?: ExecutionOptions,
+8 -1
View File
@@ -1,3 +1,4 @@
import { closeOwnedWebResources } from "./closeOwnedWebResources.js";
import { isAbsolute } from "node:path";
import { z } from "zod";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
@@ -70,7 +71,13 @@ export class WebModuleTraceService {
) {}
close(): Promise<void> {
return this.resolver.close?.() ?? Promise.resolve();
return closeOwnedWebResources(
[
this.artifacts.close?.bind(this.artifacts),
this.resolver.close?.bind(this.resolver),
],
"Web module trace cleanup failed",
);
}
async trace(
+2
View File
@@ -12,4 +12,6 @@ export interface WebNetworkCapturePort {
input: InspectWebNetworkCaptureInput,
options?: ExecutionOptions,
): Promise<Result<WebNetworkCapture, AnalysisError>>;
/** Retry retained reader/runtime cleanup when the owning service shuts down. */
close?(): Promise<void>;
}
@@ -27,6 +27,11 @@ const OPERATION = "inspect_web_network_capture";
export class WebNetworkCaptureService {
constructor(readonly port: WebNetworkCapturePort) {}
/** Release resources retained by the selected capture adapter. */
close(): Promise<void> {
return this.port.close?.() ?? Promise.resolve();
}
/** Return selected complete records inline, without inventing live browser attribution. */
async inspect(
rawInput: unknown,
+1
View File
@@ -8,6 +8,7 @@ import type { ExecutionOptions } from "./AnalysisProvider.js";
/** Read the caller-selected capture export and verify the selected source identity. */
export interface WebScriptArtifactPort {
close?(): Promise<void>;
load(
input: SelectedWebScriptInput,
options?: ExecutionOptions,
@@ -20,6 +20,7 @@ export interface WebSourceLocationArtifacts extends SelectedWebScriptArtifacts {
/** Replaceable artifact acquisition boundary for a caller-selected pairing. */
export interface WebSourceLocationArtifactPort {
close?(): Promise<void>;
load(
input: WebSourceLocationInput,
options?: ExecutionOptions,
+9 -1
View File
@@ -1,3 +1,4 @@
import { closeOwnedWebResources } from "./closeOwnedWebResources.js";
import { createHash } from "node:crypto";
import { isAbsolute } from "node:path";
import { z } from "zod";
@@ -71,7 +72,13 @@ export class WebSourceLocationService {
) {}
close(): Promise<void> {
return this.decoder.close?.() ?? Promise.resolve();
return closeOwnedWebResources(
[
this.artifacts.close?.bind(this.artifacts),
this.decoder.close?.bind(this.decoder),
],
"Web source-location cleanup failed",
);
}
/** Shared CLI/MCP workflow preserves raw declarations and every equal-position match. */
@@ -174,6 +181,7 @@ export class WebSourceLocationService {
);
}
}
const invalidOutput = (message: string): Result<never, AnalysisError> =>
err(new AnalysisOutputError(OPERATION, message));
const invalid = (
@@ -12,6 +12,7 @@ import type { Result } from "../../domain/result.js";
/** Stable read and PE decoding boundary, independent of an active disassembler session. */
export interface PeResourcesPort {
readonly identity: ProviderIdentity;
close?(): Promise<void>;
inspect(
input: InspectPeResourcesInput,
options?: ExecutionOptions,
@@ -21,6 +21,10 @@ import { err, ok, type Result } from "../../domain/result.js";
export class PeResourcesService {
constructor(readonly provider: PeResourcesPort) {}
close(): Promise<void> {
return this.provider.close?.() ?? Promise.resolve();
}
async inspect(
rawInput: unknown,
options?: ExecutionOptions,
+15
View File
@@ -0,0 +1,15 @@
/** Attempt every web workflow cleanup owner and report all failures. */
export const closeOwnedWebResources = async (
close: readonly ((() => Promise<void>) | undefined)[],
message: string,
): Promise<void> => {
const results = await Promise.allSettled(
close.flatMap((owner) =>
owner === undefined ? [] : [Promise.resolve().then(owner)],
),
);
const failures = results.flatMap((result) =>
result.status === "rejected" ? [result.reason] : [],
);
if (failures.length > 0) throw new AggregateError(failures, message);
};
+1
View File
@@ -12,6 +12,7 @@ import type { Result } from "../../domain/result.js";
/** Replaceable offline build-information reader with no target-execution authority. */
export interface GoBinaryPort {
readonly identity: ProviderIdentity;
close?(): Promise<void>;
inspect(
input: InspectGoBinaryInput,
options?: ExecutionOptions,
+4
View File
@@ -34,6 +34,10 @@ const architectureForSubject = (architecture: string) => {
export class GoBinaryService {
constructor(readonly provider: GoBinaryPort) {}
close(): Promise<void> {
return this.provider.close?.() ?? Promise.resolve();
}
/** Inspect one explicitly selected file without acquiring a binary session. */
async inspect(
rawInput: unknown,
@@ -1,6 +1,6 @@
import { createHash } from "node:crypto";
import { moduleKindForJavaScriptReference } from "./JavaScriptArtifactPathResolution.js";
import { moduleResolutionModeForJavaScriptReference } from "../../domain/javascript/javascriptModuleResolutionMode.js";
import { setImmediate } from "node:timers/promises";
import { resolveJavaScriptSourceMapReferences } from "../../domain/javascript/javascriptSourceMapPaths.js";
@@ -384,7 +384,10 @@ function* analyzeArtifactFileSteps<
analysis.parse_status === "complete" || analysis.parse_status === "partial"
? yield* analyzeParsedJavaScriptSemanticsSteps(
parsed,
moduleKindForJavaScriptReference(file.path, "static-import"),
moduleResolutionModeForJavaScriptReference(
file.path,
"static-import",
),
)
: null;
const projected =
@@ -66,6 +66,7 @@ export interface AstEdgeInput {
/** Inferred static relationship edge values. */
export interface InferenceEdgeInput extends AstEdgeInput {
readonly limitations?: readonly string[];
readonly relation:
| "imports"
| "loads"
@@ -162,6 +163,9 @@ export const addStaticInferenceEdge = (
range: input.range,
operation: "map-static-relationship",
coverage: input.coverage,
...(input.limitations === undefined
? {}
: { limitations: input.limitations }),
}),
});
};
@@ -347,7 +351,7 @@ export const resolveArtifactPath = (
specifier: string,
sourcePath: string,
files: ReadonlyMap<string, JavaScriptArtifactFile>,
moduleKind?: "import" | "require",
moduleKind?: "import" | "require" | "compiler-dependent",
): string | null =>
resolveArtifactPathByContext({
declaredPath: specifier,
@@ -12,7 +12,6 @@ import {
javascriptAnalysisCoverage,
linkElectronRoleToAsset,
moduleLookupKey,
resolveArtifactPath,
selfReferenceOmissions,
sourceNodeFor,
type JavaScriptArtifactGraphContext,
@@ -23,9 +22,11 @@ import {
staticInferenceEvidence,
} from "./JavaScriptArtifactGraphEvidence.js";
import {
moduleKindForJavaScriptReference,
artifactPathResolutionProperties,
resolveArtifactPathByContext,
type ArtifactPathResolution,
} from "./JavaScriptArtifactPathResolution.js";
import { moduleResolutionModeForJavaScriptReference } from "../../domain/javascript/javascriptModuleResolutionMode.js";
type StaticReference = JavaScriptStaticAnalysis["references"][number];
type StaticEndpoint = JavaScriptStaticAnalysis["endpoints"][number];
@@ -41,9 +42,12 @@ interface FindingInput<Value> {
}
interface ResolvedReference {
readonly path: string;
readonly file: JavaScriptArtifactFile;
readonly path: string | null;
readonly file: JavaScriptArtifactFile | null;
readonly node: ApplicationNode;
readonly limitations: readonly string[];
readonly resolutionStatus?: string;
readonly resolution?: ArtifactPathResolution;
}
/** Project imports, workers, roles, endpoints, storage, and source-map links. */
@@ -90,7 +94,7 @@ const addReference = (
const resolved =
input.value.specifier === null
? null
: resolveReference(context, input.file.path, input.value);
: resolveReference(context, input.file.path, input.value, input.coverage);
if (input.value.kind === "worker" || input.value.kind === "service-worker") {
const worker = context.accumulator.addNode({
kind: input.value.kind === "worker" ? "worker" : "service-worker",
@@ -126,7 +130,7 @@ const addReference = (
relation: "loads",
properties: { kind: input.value.kind },
});
if (resolved !== null)
if (resolved !== null && resolved.path !== null)
addStaticInferenceEdge(context, {
source: worker,
target: resolved.node,
@@ -135,6 +139,7 @@ const addReference = (
coverage: input.coverage,
relation: "maps_to",
properties: { resolved_path: resolved.path },
limitations: resolved.limitations,
});
return;
}
@@ -154,13 +159,25 @@ const addReference = (
file: input.file,
range: input.value.location,
coverage: input.coverage,
relation: resolved?.file.kind === "native-addon" ? "loads" : "imports",
relation: resolved?.file?.kind === "native-addon" ? "loads" : "imports",
properties: {
kind: input.value.kind,
specifier: input.value.specifier,
expression: input.value.expression,
resolution_mode:
input.value.kind === "static-import" ||
input.value.kind === "dynamic-import" ||
input.value.kind === "require"
? moduleResolutionModeForJavaScriptReference(
input.file.path,
input.value.kind,
)
: null,
resolved_path: resolved?.path ?? null,
resolution_status: resolved?.resolutionStatus ?? null,
...artifactPathResolutionProperties(resolved?.resolution),
},
...(resolved === null ? {} : { limitations: resolved.limitations }),
});
};
@@ -373,6 +390,7 @@ const resolveReference = (
context: JavaScriptArtifactGraphContext,
sourcePath: string,
reference: StaticReference,
coverage: JavaScriptArtifactGraphCoverage,
): ResolvedReference | null => {
const specifier = reference.specifier;
if (specifier === null) return null;
@@ -392,30 +410,70 @@ const resolveReference = (
const file = context.filesByPath.get(sourcePath);
return file === undefined
? null
: { path: `${sourcePath}#module:${specifier}`, file, node: module };
: {
path: `${sourcePath}#module:${specifier}`,
file,
node: module,
limitations: [],
};
}
// Worker scripts are URLs relative to the script, not module specifiers.
const path = isWorker
const resolution = isWorker
? resolveArtifactPathByContext({
declaredPath: specifier,
sourcePath,
context: "url-reference",
files: context.filesByPath,
}).resolved_path
: resolveArtifactPath(
specifier,
})
: resolveArtifactPathByContext({
declaredPath: specifier,
sourcePath,
context.filesByPath,
reference.kind === "require" ||
reference.kind === "static-import" ||
reference.kind === "dynamic-import"
? moduleKindForJavaScriptReference(sourcePath, reference.kind)
: undefined,
);
if (path === null) return null;
context: "module-specifier",
files: context.filesByPath,
...("require" === reference.kind ||
"static-import" === reference.kind ||
"dynamic-import" === reference.kind
? {
moduleKind: moduleResolutionModeForJavaScriptReference(
sourcePath,
reference.kind,
),
}
: {}),
});
const path = resolution.resolved_path;
if (path === null) {
if (isWorker) return null;
const source = context.filesByPath.get(sourcePath);
return source === undefined
? null
: {
path: null,
file: null,
node: unresolvedReferenceNode(
context,
source,
reference,
coverage,
resolution,
),
limitations: resolution.limitations,
resolutionStatus: resolution.resolution_status,
resolution,
};
}
const file = context.filesByPath.get(path);
const node = context.fileNodes.get(path);
return file === undefined || node === undefined ? null : { path, file, node };
return file === undefined || node === undefined
? null
: {
path,
file,
node,
limitations: resolution.limitations,
resolutionStatus: resolution.resolution_status,
resolution,
};
};
const resolveBundlerChunkReference = (
@@ -453,7 +511,7 @@ const resolveBundlerChunkReference = (
const node = unique[0];
return node === undefined
? null
: { path: `${sourcePath}#chunk:${key}`, file, node };
: { path: `${sourcePath}#chunk:${key}`, file, node, limitations: [] };
};
const unresolvedReferenceNode = (
@@ -461,6 +519,7 @@ const unresolvedReferenceNode = (
file: JavaScriptArtifactFile,
reference: StaticReference,
coverage: JavaScriptArtifactGraphCoverage,
resolution?: ArtifactPathResolution,
): ApplicationNode =>
context.accumulator.addNode({
kind: "javascript-module",
@@ -477,6 +536,10 @@ const unresolvedReferenceNode = (
specifier: reference.specifier,
expression: reference.expression,
resolution: "unresolved",
...(resolution === undefined
? {}
: { resolution_status: resolution.resolution_status }),
...artifactPathResolutionProperties(resolution),
},
evidence: staticInferenceEvidence({
sha256: file.sha256,
@@ -487,6 +550,7 @@ const unresolvedReferenceNode = (
confidence: "low",
limitations: [
"The static reference could not be resolved within the inventoried artifact.",
...(resolution?.limitations ?? []),
],
}),
},
@@ -1890,21 +1890,40 @@ describe("TypeScript NodeNext emitted-extension resolution", () => {
).toMatchObject({ resolution_status: "resolved", resolved_path: target });
},
);
});
describe("TypeScript declaration fallback ownership", () => {
const container = "container";
it.each([
["./dep.js", "src/dep.d.ts"],
["./cfg.mjs", "src/cfg.d.mts"],
["./legacy.cjs", "src/legacy.d.cts"],
] as const)(
"resolves %s to a declaration counterpart",
"retains %s as compile-time evidence without inventing a runtime target",
(specifier, target) => {
const files = fileMap([
file("src/main.ts", container),
file(target, container, "export const value = 1;"),
]);
for (const moduleKind of ["import", "require"] as const) {
expect(
resolve({
declaredPath: specifier,
sourcePath: "src/main.ts",
context: "module-specifier",
moduleKind,
files,
}),
).toMatchObject({
resolution_status: "unavailable",
resolved_path: null,
candidate_path: target,
});
}
expect(
resolve({
declaredPath: specifier,
declaredPath: "./" + target.slice(4),
sourcePath: "src/main.ts",
context: "module-specifier",
moduleKind: "import",
@@ -19,8 +19,13 @@ import {
classifyPackageImportTargetString,
lookupExactPackageImport,
} from "../../domain/javascript/javascriptPackageImportAliases.js";
import { typescriptEmittedSourceCandidates } from "../TypeScriptEmittedSourceCandidates.js";
import {
typescriptEmittedSourceCandidates,
type TypeScriptEmittedSourceCandidate,
} from "../TypeScriptEmittedSourceCandidates.js";
import { isRelativeJavaScriptModuleSpecifier } from "../../domain/javascript/javascriptModuleSpecifier.js";
import type { JavaScriptModuleResolutionMode } from "../../domain/javascript/javascriptModuleResolutionMode.js";
import type { JsonValue } from "../../domain/jsonValue.js";
type ArtifactPathResolutionContext =
| "package-entrypoint"
@@ -39,6 +44,16 @@ interface ArtifactPathResolutionBase {
readonly declared_path: string;
readonly resolution_context: ArtifactPathResolutionContext;
readonly limitations: readonly string[];
readonly conditional_resolutions?: readonly ConditionalModuleResolution[];
readonly candidate_path?: string;
}
export interface ConditionalModuleResolution {
readonly mode: "import" | "require";
readonly resolution_status: UnresolvedArtifactPathStatus | "resolved";
readonly resolved_path: string | null;
readonly candidate_path?: string;
readonly limitations: readonly string[];
}
/** Explicit outcome of artifact-confined path resolution. */
@@ -62,26 +77,13 @@ export interface ResolveArtifactPathInput {
readonly files: ReadonlyMap<string, JavaScriptArtifactFile>;
readonly htmlBaseHref?: string | null;
/** Import/require semantics; runtime resource paths omit this provenance. */
readonly moduleKind?: "import" | "require";
readonly moduleKind?: JavaScriptModuleResolutionMode;
}
/** Loader selected by a source-level JavaScript module reference. */
export const moduleKindForJavaScriptReference = (
sourcePath: string,
referenceKind: "static-import" | "dynamic-import" | "require",
resolutionMode?: "import" | "require",
): "import" | "require" =>
resolutionMode ??
(referenceKind === "require" ||
(referenceKind === "static-import" &&
posix.extname(sourcePath).toLowerCase() === ".cts")
? "require"
: "import");
/** Preserve an explicitly retained loader mode on graph relationships. */
export const moduleResolutionModeProperties = (
mode: "import" | "require" | undefined,
): Readonly<Record<string, "import" | "require">> =>
mode: JavaScriptModuleResolutionMode | undefined,
): Readonly<Record<string, JavaScriptModuleResolutionMode>> =>
mode === undefined ? {} : { resolution_mode: mode };
const EXTENSIONS = [
@@ -110,43 +112,116 @@ interface PackageFileTarget {
readonly url: URL;
}
type CandidateResolution =
| {
readonly resolvedPath: string;
readonly status: "resolved";
readonly limitations: readonly string[];
}
type CandidateResolution = {
readonly limitations: readonly string[];
readonly candidatePath?: string;
readonly conditionalResolutions?: readonly ConditionalModuleResolution[];
} & (
| { readonly resolvedPath: string; readonly status: "resolved" }
| {
readonly resolvedPath: null;
readonly status: UnresolvedArtifactPathStatus;
readonly limitations: readonly string[];
/** A truthy package main failed, so Node must not try ancestor packages. */
readonly stopsAncestorLookup?: true;
};
}
);
/** Resolve one declaration while preserving its original input identity. */
export const resolveArtifactPathByContext = (
input: ResolveArtifactPathInput,
): ArtifactPathResolution => {
const resolution = resolvePath(input);
const facts = {
declared_path: input.declaredPath,
resolution_context: input.context,
limitations: resolution.limitations,
...(resolution.candidatePath === undefined
? {}
: { candidate_path: resolution.candidatePath }),
...(resolution.conditionalResolutions === undefined
? {}
: { conditional_resolutions: resolution.conditionalResolutions }),
};
return resolution.status === "resolved"
? {
declared_path: input.declaredPath,
resolution_context: input.context,
...facts,
resolved_path: resolution.resolvedPath,
resolution_status: resolution.status,
limitations: resolution.limitations,
}
: {
declared_path: input.declaredPath,
resolution_context: input.context,
resolved_path: null,
resolution_status: resolution.status,
limitations: resolution.limitations,
};
: { ...facts, resolved_path: null, resolution_status: resolution.status };
};
/** Project retained conditional identities without flattening them into display text. */
export const artifactPathResolutionProperties = (
resolution: ArtifactPathResolution | undefined,
): Readonly<Record<string, JsonValue>> => ({
...(resolution?.candidate_path === undefined
? {}
: { candidate_path: resolution.candidate_path }),
...(resolution?.conditional_resolutions === undefined
? {}
: {
conditional_resolutions: resolution.conditional_resolutions.map(
(branch) => ({
mode: branch.mode,
resolution_status: branch.resolution_status,
resolved_path: branch.resolved_path,
limitations: [...branch.limitations],
...(branch.candidate_path === undefined
? {}
: { candidate_path: branch.candidate_path }),
}),
),
}),
});
const conditionalResolution = (
mode: "import" | "require",
result: CandidateResolution,
): ConditionalModuleResolution => ({
mode,
resolution_status: result.status,
resolved_path: result.resolvedPath,
limitations: result.limitations,
...(result.candidatePath === undefined
? {}
: { candidate_path: result.candidatePath }),
});
const resolvePath = (input: ResolveArtifactPathInput): CandidateResolution => {
if (input.moduleKind === "compiler-dependent") {
const imported = resolvePath({ ...input, moduleKind: "import" });
const required = resolvePath({ ...input, moduleKind: "require" });
const sameOutcome =
imported.status === required.status &&
imported.resolvedPath === required.resolvedPath &&
imported.candidatePath === required.candidatePath;
const limitation =
"Static TypeScript loader mode is compiler-dependent without retained compiler options. " +
(sameOutcome
? "Node import and require resolution agree on this outcome."
: "Node import and require resolution disagree; neither branch is an established target.");
return sameOutcome
? {
...imported,
limitations: [
...new Set([
...imported.limitations,
...required.limitations,
limitation,
]),
],
}
: {
resolvedPath: null,
status: "unavailable",
limitations: [limitation],
conditionalResolutions: [
conditionalResolution("import", imported),
conditionalResolution("require", required),
],
};
}
// Package import keys are literal lookup identities, not artifact paths.
// The selected target is admitted separately by resolveExportTarget.
if (
@@ -176,12 +251,47 @@ const resolvePath = (input: ResolveArtifactPathInput): CandidateResolution => {
: [];
if (isModuleUrlPath && input.moduleKind === "import")
return (
resolveFileCandidates(input, [confined, ...emittedSourceCandidates]) ??
notFoundCandidate()
resolveRuntimeSourceCandidates(
input,
confined,
emittedSourceCandidates,
) ?? notFoundCandidate()
);
return resolveCandidate(input, confined, new Set(), emittedSourceCandidates);
};
const resolveRuntimeSourceCandidates = (
input: ResolveArtifactPathInput,
exactPath: string,
sourceCandidates: readonly TypeScriptEmittedSourceCandidate[],
): CandidateResolution | null => {
const source = input.files.get(input.sourcePath);
const exactCandidate: TypeScriptEmittedSourceCandidate = {
path: exactPath,
kind: "implementation",
};
for (const candidate of [exactCandidate, ...sourceCandidates]) {
const target = input.files.get(candidate.path);
if (
target === undefined ||
(source !== undefined &&
target.container_sha256 !== source.container_sha256)
)
continue;
return candidate.kind === "declaration"
? {
resolvedPath: null,
status: "unavailable",
candidatePath: candidate.path,
limitations: [
"Only a TypeScript declaration fallback was found; it does not establish the requested runtime module.",
],
}
: { resolvedPath: candidate.path, status: "resolved", limitations: [] };
}
return null;
};
const rejectDeclaration = (declared: string): CandidateResolution | null => {
if (declared.length === 0)
return unresolvedCandidate("rejected", ["The declared path is empty."]);
@@ -849,12 +959,10 @@ const resolveCandidate = (
input: ResolveArtifactPathInput,
candidate: string,
packageChain: ReadonlySet<string>,
emittedSourceCandidates: readonly string[] = [],
emittedSourceCandidates: readonly TypeScriptEmittedSourceCandidate[] = [],
): CandidateResolution =>
resolveFileCandidates(input, [
...fileCandidates(candidate, input.moduleKind),
...emittedSourceCandidates,
]) ??
resolveFileCandidates(input, fileCandidates(candidate, input.moduleKind)) ??
resolveRuntimeSourceCandidates(input, candidate, emittedSourceCandidates) ??
resolveDirectory(
input,
candidate,
@@ -940,11 +1048,26 @@ const resolveFileCandidates = (
(source === undefined ||
target.container_sha256 === source.container_sha256)
)
return { resolvedPath: path, status: "resolved", limitations: [] };
return isRuntimeDeclarationPath(input, path)
? {
resolvedPath: null,
status: "unavailable",
candidatePath: path,
limitations: [
`The TypeScript declaration ${path} is compile-time evidence and cannot identify a runtime module implementation.`,
],
}
: { resolvedPath: path, status: "resolved", limitations: [] };
}
return null;
};
const isRuntimeDeclarationPath = (
input: ResolveArtifactPathInput,
path: string,
): boolean =>
input.moduleKind !== undefined && /\.d\.(?:ts|mts|cts)$/iu.test(path);
const NODE_MODULE_EXTENSIONS = [".js", ".json", ".node"] as const;
const fileCandidates = (
@@ -18,6 +18,7 @@ import type {
JavaScriptModuleOrigin,
JavaScriptSemanticModuleLink,
} from "../../domain/javascript/javascriptSemanticIr.js";
import { moduleResolutionModeForJavaScriptReference } from "../../domain/javascript/javascriptModuleResolutionMode.js";
import type { JavaScriptArtifactFile } from "../../domain/javascript/javascriptArtifactFiles.js";
import {
addAstContainsEdge,
@@ -30,7 +31,7 @@ import {
staticInferenceEvidence,
} from "./JavaScriptArtifactGraphEvidence.js";
import {
moduleKindForJavaScriptReference,
artifactPathResolutionProperties,
moduleResolutionModeProperties,
resolveArtifactPathByContext,
type ArtifactPathResolution,
@@ -54,6 +55,7 @@ interface RelationshipInput {
type ResolvedModuleTarget = {
readonly node: ApplicationNode;
readonly limitations: readonly string[];
readonly resolution?: ArtifactPathResolution;
} & (
| {
readonly path: string;
@@ -287,7 +289,7 @@ const resolveModuleTarget = (
sourcePath: input.file.path,
context: "module-specifier",
files: input.context.filesByPath,
moduleKind: moduleKindForJavaScriptReference(
moduleKind: moduleResolutionModeForJavaScriptReference(
input.file.path,
input.link.kind === "require" || input.link.kind === "commonjs-export"
? "require"
@@ -297,15 +299,12 @@ const resolveModuleTarget = (
});
if (resolution.resolution_status !== "resolved")
return {
node: unresolvedModuleNode(
input,
specifier,
resolution.resolution_status,
),
node: unresolvedModuleNode(input, specifier, resolution),
path: null,
file: null,
status: resolution.resolution_status,
limitations: resolution.limitations,
resolution,
};
const path = resolution.resolved_path;
const file = input.context.filesByPath.get(path);
@@ -322,20 +321,24 @@ const resolveModuleTarget = (
file,
status: "resolved",
limitations: resolution.limitations,
resolution,
};
};
const unresolvedModuleNode = (
input: RelationshipInput,
specifier: string,
status: Exclude<ResolvedModuleTarget["status"], "resolved">,
resolution: Extract<
ArtifactPathResolution,
{ resolution_status: Exclude<ResolvedModuleTarget["status"], "resolved"> }
>,
): ApplicationNode =>
input.context.accumulator.addNode({
kind: "javascript-module",
identity: artifactLocalIdentity(
input.file.sha256,
"unresolved-semantic-module",
`${status}:${specifier}`,
`${resolution.resolution_status}:${specifier}`,
),
observations: [
{
@@ -343,7 +346,8 @@ const unresolvedModuleNode = (
properties: {
semantic_role: "module-reference",
declared_specifier: specifier,
resolution_status: status,
resolution_status: resolution.resolution_status,
...artifactPathResolutionProperties(resolution),
},
evidence: staticInferenceEvidence({
sha256: input.file.sha256,
@@ -364,6 +368,9 @@ const moduleOriginForExport = (
): JavaScriptModuleOrigin | null => {
if (link.specifier !== null)
return {
...(link.resolutionMode === undefined
? {}
: { resolutionMode: link.resolutionMode }),
specifier: link.specifier,
importedPath: link.importedName === null ? [] : [link.importedName],
};
@@ -393,6 +400,7 @@ const relationshipProperties = (
exported_name: link.exportedName,
resolved_path: target?.path ?? null,
resolution_status: target?.status ?? null,
...artifactPathResolutionProperties(target?.resolution),
target_file_kind: target?.file?.kind ?? null,
target_json_status:
target?.file?.kind === "json" || target?.file?.kind === "package-json"
@@ -441,6 +449,7 @@ const moduleFormat = (
const extension = posix.extname(path).toLowerCase();
if (extension === ".mjs" || extension === ".mts") return "esm";
if (extension === ".cjs" || extension === ".cts") return "commonjs";
if (extension === ".ts" || extension === ".tsx") return "unknown";
const esm = ir.moduleLinks.some(({ kind }) =>
["import", "export", "re-export"].includes(kind),
);
+4
View File
@@ -57,6 +57,10 @@ export class ArtifactResourceScope {
#draining: Promise<void> | undefined;
#closed = false;
get hasPending(): boolean {
return this.#pending.size > 0;
}
/** Admit a resource operation while the scope remains open. */
async run<T>(operation: () => Promise<T>): Promise<T> {
while (true) {
+10 -2
View File
@@ -38,6 +38,13 @@ const afterValidation = async <T>(
}
};
const assertReadActive = (signal: AbortSignal | undefined): void => {
if (signal?.aborted)
throw new ArtifactReaderFailure("cancelled", "Artifact read cancelled", {
cause: signal.reason,
});
};
/** Read one bounded regular file and reject replacement or in-place changes. */
export const readStableArtifact = async (
path: string,
@@ -46,7 +53,7 @@ export const readStableArtifact = async (
fileSystem: StableArtifactFileSystem = FILE_SYSTEM,
resourceScope?: ArtifactResourceScope,
): Promise<{ readonly bytes: Buffer; readonly sha256: string }> => {
signal?.throwIfAborted();
assertReadActive(signal);
const before = await fileSystem.lstat(path);
if (!before.isFile() || before.isSymbolicLink())
throw new ArtifactReaderFailure(
@@ -84,7 +91,7 @@ export const readStableArtifact = async (
autoClose: false,
highWaterMark: 65536,
})) {
signal?.throwIfAborted();
assertReadActive(signal);
const value: unknown = chunk;
if (!Buffer.isBuffer(value))
throw new ArtifactReaderFailure(
@@ -120,6 +127,7 @@ export const readStableArtifact = async (
"integrity",
`Artifact changed during read: ${path}`,
);
assertReadActive(signal);
const bytes = Buffer.concat(chunks, count);
return { bytes, sha256: createHash("sha256").update(bytes).digest("hex") };
} catch (cause: unknown) {
+31 -1
View File
@@ -1,6 +1,7 @@
import { lstat, realpath } from "node:fs/promises";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
import { normalizeArtifactPath } from "../../artifacts/ArtifactPaths.js";
import type { WebScriptArtifactPort } from "../../application/WebScriptArtifactPort.js";
@@ -19,10 +20,36 @@ import {
/** Read one digest-verified captured source under the manifest's current location. */
export class LocalWebScriptArtifacts implements WebScriptArtifactPort {
constructor(readonly operation: WebArtifactReadContext["operation"]) {}
constructor(
readonly operation: WebArtifactReadContext["operation"],
readonly resources = new ArtifactResourceScope(),
) {}
close(): Promise<void> {
return this.resources.close();
}
/** Read the selected source; relocated exports retain their reported original root. */
async load(input: SelectedWebScriptInput, options?: ExecutionOptions) {
try {
return await this.resources.run(() => this.#load(input, options));
} catch (cause: unknown) {
return err(
webArtifactReadError(
cause,
{
operation: this.operation,
field: ["manifest_path"],
targetPath: input.manifest_path,
callerSelected: true,
},
options?.signal,
),
);
}
}
async #load(input: SelectedWebScriptInput, options?: ExecutionOptions) {
let field: readonly (string | number)[] = ["manifest_path"];
let targetPath = input.manifest_path;
let callerSelected = true;
@@ -31,6 +58,7 @@ export class LocalWebScriptArtifacts implements WebScriptArtifactPort {
input.manifest_path,
32 * 1024 * 1024,
options?.signal,
this.resources,
);
const manifest = webScriptExportManifestSchema.parse(manifestBytes.value);
field = ["script_index"];
@@ -65,6 +93,8 @@ export class LocalWebScriptArtifacts implements WebScriptArtifactPort {
sourcePath,
16 * 1024 * 1024,
options?.signal,
undefined,
this.resources,
);
await assertContained(root, sourcePath);
if (
+34 -2
View File
@@ -1,5 +1,6 @@
import { z } from "zod";
import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
@@ -9,6 +10,8 @@ import {
} from "../../domain/analysisErrorCore.js";
import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
import { safeParseJson } from "../../domain/safeJson.js";
/** The selected artifact and input field owning a reader failure. */
@@ -42,8 +45,15 @@ export const readWebArtifactJson = async (
path: string,
maximumBytes: number,
signal?: AbortSignal,
resourceScope?: ArtifactResourceScope,
) => {
const data = await readStableArtifact(path, maximumBytes, signal);
const data = await readStableArtifact(
path,
maximumBytes,
signal,
undefined,
resourceScope,
);
const value = safeParseJson(decodeWebArtifact(data.bytes));
if (!value.ok) throw new WebArtifactFormatFailure(value.error);
return { ...data, value: value.value };
@@ -55,8 +65,30 @@ export const webArtifactReadError = (
context: WebArtifactReadContext,
signal?: AbortSignal,
): AnalysisError => {
if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined) {
const primary =
signal?.aborted === true
? new AnalysisCancelledError(context.operation, { cause })
: new ArtifactOperationError(
context.operation,
cause.reason,
cause.details,
cause.message,
{ cause },
);
return analysisErrorWithCleanupFailure(
primary,
new ProviderCleanupError(
"captured-web-artifacts",
cause.cleanup.resources,
{ reason: cause.cleanup.reason },
{ cause, operation: context.operation },
),
context.operation,
);
}
if (signal?.aborted === true)
return new AnalysisCancelledError(context.operation);
return new AnalysisCancelledError(context.operation, { cause });
const selection = context.callerSelected
? selectedFileError(cause, context)
: undefined;
@@ -1,6 +1,7 @@
import type { WebSourceLocationArtifactPort } from "../../application/WebSourceLocationPorts.js";
import type { WebScriptArtifactPort } from "../../application/WebScriptArtifactPort.js";
import type { ExecutionOptions } from "../../application/AnalysisProvider.js";
import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
import {
WEB_SOURCE_MAP_LIMITS,
@@ -12,14 +13,64 @@ import { decodeWebArtifact, webArtifactReadError } from "./WebArtifactReads.js";
/** Read one verified capture source and the caller-selected map, without fetching. */
export class LocalWebSourceLocationArtifacts implements WebSourceLocationArtifactPort {
readonly scripts: WebScriptArtifactPort;
readonly #resources: ArtifactResourceScope;
constructor(
readonly scripts: WebScriptArtifactPort = new LocalWebScriptArtifacts(
"trace_web_source_location",
),
) {}
scripts?: WebScriptArtifactPort,
resources = scripts instanceof LocalWebScriptArtifacts
? scripts.resources
: new ArtifactResourceScope(),
) {
this.#resources = resources;
this.scripts =
scripts ??
new LocalWebScriptArtifacts("trace_web_source_location", resources);
}
async close(): Promise<void> {
const closeScript =
this.scripts instanceof LocalWebScriptArtifacts &&
this.scripts.resources === this.#resources
? undefined
: this.scripts.close?.bind(this.scripts);
const results = await Promise.allSettled([
Promise.resolve().then(() => this.#resources.close()),
...(closeScript === undefined
? []
: [Promise.resolve().then(closeScript)]),
]);
const failures = results.flatMap((result) =>
result.status === "rejected" ? [result.reason] : [],
);
if (failures.length > 0)
throw new AggregateError(
failures,
"Web source-location artifact cleanup failed",
);
}
/** Preserve actual map identity separately from the selected deployment URL. */
async load(input: WebSourceLocationInput, options?: ExecutionOptions) {
try {
return await this.#resources.run(() => this.#load(input, options));
} catch (cause: unknown) {
return err(
webArtifactReadError(
cause,
{
operation: "trace_web_source_location",
field: ["source_map", "path"],
targetPath: input.source_map.path,
callerSelected: true,
},
options?.signal,
),
);
}
}
async #load(input: WebSourceLocationInput, options?: ExecutionOptions) {
const loaded = await this.scripts.load(input, options);
if (!loaded.ok) return loaded;
try {
@@ -27,6 +78,8 @@ export class LocalWebSourceLocationArtifacts implements WebSourceLocationArtifac
input.source_map.path,
WEB_SOURCE_MAP_LIMITS.mapBytes,
options?.signal,
undefined,
this.#resources,
);
return ok({
...loaded.value,
@@ -17,6 +17,7 @@ import { z } from "zod";
import type { ExecutionOptions } from "../../application/AnalysisProvider.js";
import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
AnalysisCapabilityUnavailableError,
@@ -26,6 +27,7 @@ import {
} from "../../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
import { err, ok, type Result } from "../../domain/result.js";
import {
WEB_NETWORK_CAPTURE_LIMITS,
@@ -60,18 +62,52 @@ const replySchema = z.discriminatedUnion("ok", [
/** One owned snapshot/process/root lifecycle for replaceable historical format decoders. */
export class HistoricalCaptureDecoder {
readonly #resources: ArtifactResourceScope;
constructor(
readonly adapters: readonly HistoricalCaptureFormatAdapter[],
readonly environment: Readonly<NodeJS.ProcessEnv>,
readonly createRuntime: () => Promise<
Pick<PrivateRuntimeRoot, "path" | "close">
> = () => PrivateRuntimeRoot.create({ prefix: "rea-web-capture-" }),
) {}
resources = new ArtifactResourceScope(),
) {
this.#resources = resources;
}
/** Retry retained readers and private roots at service shutdown. */
close(): Promise<void> {
return this.#resources.close();
}
/** Snapshot the selected artifact, decode it offline, and release private credentials and processes. */
async inspect(
input: InspectWebNetworkCaptureInput,
options?: ExecutionOptions,
): Promise<Result<WebNetworkCapture, AnalysisError>> {
try {
return await this.#resources.run(() =>
this.inspectAdmitted(input, options),
);
} catch (cause: unknown) {
const error = historicalCaptureFailure(
input,
cause,
"capture-read",
options,
);
return err(
redactExplicitFailure(
this.withReaderCleanup(error, cause),
input.sensitive_values,
),
);
}
}
private async inspectAdmitted(
input: InspectWebNetworkCaptureInput,
options?: ExecutionOptions,
): Promise<Result<WebNetworkCapture, AnalysisError>> {
let runtime: Pick<PrivateRuntimeRoot, "path" | "close"> | undefined;
let result: Result<WebNetworkCapture, AnalysisError>;
@@ -90,6 +126,8 @@ export class HistoricalCaptureDecoder {
input.capture_path,
WEB_NETWORK_CAPTURE_LIMITS.inputBytes,
options?.signal,
undefined,
this.#resources,
);
phase = "decoder";
runtime = await this.createRuntime();
@@ -139,9 +177,16 @@ export class HistoricalCaptureDecoder {
replyPath,
WEB_NETWORK_CAPTURE_LIMITS.outputBytes,
options?.signal,
undefined,
this.#resources,
);
reply = replySchema.parse(JSON.parse(replyFile.bytes.toString("utf8")));
} catch (cause: unknown) {
if (
cause instanceof ArtifactReaderFailure &&
cause.cleanup !== undefined
)
throw cause;
if (options?.signal?.aborted)
throw new AnalysisCancelledError(OPERATION);
throw new AnalysisOutputError(
@@ -230,17 +275,21 @@ export class HistoricalCaptureDecoder {
result = ok({ ...reply.value, ...common, format: input.format });
}
} catch (cause: unknown) {
const error = historicalCaptureFailure(input, cause, phase, options);
result = err(
redactExplicitFailure(
historicalCaptureFailure(input, cause, phase, options),
this.withReaderCleanup(error, cause),
input.sensitive_values,
),
);
}
if (runtime !== undefined) {
try {
await runtime.close();
} catch (cause: unknown) {
const cleanup = await this.#resources.release({
kind: "private-runtime-root",
resource: runtime.path,
root: runtime,
});
if (cleanup.kind === "failed") {
return err(
redactExplicitFailure(
new ProviderCleanupError(
@@ -251,9 +300,12 @@ export class HistoricalCaptureDecoder {
previous_error: result.ok
? null
: projectAnalysisError(result.error),
reason: cause instanceof Error ? cause.message : String(cause),
reason:
cleanup.cause instanceof Error
? cleanup.cause.message
: String(cleanup.cause),
},
{ operation: OPERATION },
{ operation: OPERATION, cause: cleanup.cause },
),
input.sensitive_values,
),
@@ -264,6 +316,34 @@ export class HistoricalCaptureDecoder {
? err(new AnalysisCancelledError(OPERATION))
: result;
}
private withReaderCleanup(
primary: AnalysisError,
cause: unknown,
): AnalysisError {
if (
!(cause instanceof ArtifactReaderFailure) ||
cause.cleanup === undefined
)
return primary;
if (cause.reason === "unavailable")
return new ProviderCleanupError(
"web-network-capture",
cause.cleanup.resources,
{ reason: cause.cleanup.reason },
{ operation: OPERATION, cause },
);
const cleanup = new ProviderCleanupError(
"web-network-capture",
cause.cleanup.resources,
{
reason: cause.cleanup.reason,
previous_error: projectAnalysisError(primary),
},
{ operation: OPERATION, cause },
);
return analysisErrorWithCleanupFailure(primary, cleanup, OPERATION);
}
}
/** The Node capture decoder runs on this executable; only Node.js enforces its V8 heap flags. */
+56 -4
View File
@@ -4,6 +4,7 @@ import type {
} from "../../application/WebModulePorts.js";
import type { WebScriptArtifactPort } from "../../application/WebScriptArtifactPort.js";
import type { ExecutionOptions } from "../../application/AnalysisProvider.js";
import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import { jsonObjectSchema } from "../../domain/jsonValue.js";
import { err, ok } from "../../domain/result.js";
import type { WebModuleTraceInput } from "../../domain/webModuleTrace.js";
@@ -15,14 +16,64 @@ import {
/** Add an explicitly selected import map to a verified captured-script source. */
export class LocalWebModuleArtifacts implements WebModuleArtifactPort {
readonly scripts: WebScriptArtifactPort;
readonly #resources: ArtifactResourceScope;
constructor(
readonly scripts: WebScriptArtifactPort = new LocalWebScriptArtifacts(
"trace_web_module_imports",
),
) {}
scripts?: WebScriptArtifactPort,
resources = scripts instanceof LocalWebScriptArtifacts
? scripts.resources
: new ArtifactResourceScope(),
) {
this.#resources = resources;
this.scripts =
scripts ??
new LocalWebScriptArtifacts("trace_web_module_imports", resources);
}
async close(): Promise<void> {
const closeScript =
this.scripts instanceof LocalWebScriptArtifacts &&
this.scripts.resources === this.#resources
? undefined
: this.scripts.close?.bind(this.scripts);
const results = await Promise.allSettled([
Promise.resolve().then(() => this.#resources.close()),
...(closeScript === undefined
? []
: [Promise.resolve().then(closeScript)]),
]);
const failures = results.flatMap((result) =>
result.status === "rejected" ? [result.reason] : [],
);
if (failures.length > 0)
throw new AggregateError(failures, "Web module artifact cleanup failed");
}
/** Read selected source and optional map without website requests. */
async load(input: WebModuleTraceInput, options?: ExecutionOptions) {
try {
return await this.#resources.run(() => this.#load(input, options));
} catch (cause: unknown) {
return err(
webArtifactReadError(
cause,
{
operation: "trace_web_module_imports",
field:
input.import_map === undefined
? ["manifest_path"]
: ["import_map", "path"],
targetPath: input.import_map?.path ?? input.manifest_path,
callerSelected: input.import_map !== undefined,
},
options?.signal,
),
);
}
}
async #load(input: WebModuleTraceInput, options?: ExecutionOptions) {
const loaded = await this.scripts.load(input, options);
if (!loaded.ok) return loaded;
if (input.import_map === undefined)
@@ -33,6 +84,7 @@ export class LocalWebModuleArtifacts implements WebModuleArtifactPort {
selected.path,
4 * 1024 * 1024,
options?.signal,
this.#resources,
);
const importMap: WebModuleArtifacts["importMap"] = {
file: {
+24 -15
View File
@@ -7,11 +7,12 @@ import {
} from "../composition/binaryDiagnostics.js";
import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type { Logger } from "pino";
import type { CliInstance } from "./types.js";
import { withCommandCancellation } from "./commandCancellation.js";
import { inspectPeResourcesInputSchema } from "../domain/native/peResources.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
/** Inspect operator-selected files through the same shared workflow as MCP. */
export const registerBinaryDiagnosticsCommands = (
@@ -19,7 +20,6 @@ export const registerBinaryDiagnosticsCommands = (
logger: Logger,
environment: Readonly<NodeJS.ProcessEnv>,
): void => {
const pe = createPeResourcesService();
cli.command(CLI_COMMANDS.inspectPeResources, {
description:
"Inspect PE resource identities, payload ranges, hashes and icon-group relationships",
@@ -29,19 +29,28 @@ export const registerBinaryDiagnosticsCommands = (
maxEntries: inspectPeResourcesInputSchema.shape.max_entries,
}),
run: ({ args, options }) =>
withCommandCancellation((signal) =>
logCliCommand(logger, CLI_COMMANDS.inspectPeResources, async () => {
const result = await pe.inspect(
{
path: resolve(args.path),
max_file_bytes: options.maxFileBytes,
max_entries: options.maxEntries,
},
{ signal },
);
return result.ok ? result.value : projectAnalysisError(result.error);
}),
),
withCommandCancellation(async (signal) => {
const pe = createPeResourcesService();
return await logCliCommand(
logger,
CLI_COMMANDS.inspectPeResources,
async () =>
finishAnalysisCommand(
() =>
pe.inspect(
{
path: resolve(args.path),
max_file_bytes: options.maxFileBytes,
max_entries: options.maxEntries,
},
{ signal },
),
pe,
"rea-pe-resources",
"inspect_pe_resources",
),
);
}),
});
const service = createBinaryLayoutService(environment);
cli.command(CLI_COMMANDS.inspectBinaryLayout, {
+22 -43
View File
@@ -1,9 +1,6 @@
import { inspectPacketFieldsInputSchema } from "../domain/captures/packetFields.js";
import { z } from "incur";
import type { PacketCaptureService } from "../application/captures/PacketCaptureService.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { resolve } from "node:path";
import { createPacketCaptureService } from "../composition/captures.js";
import {
@@ -13,10 +10,10 @@ import {
} from "../domain/captures/packetCapture.js";
import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type { Logger } from "pino";
import type { CliInstance } from "./types.js";
import { withCommandCancellation } from "./commandCancellation.js";
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
export const registerCaptureCommands = (
cli: CliInstance,
logger: Logger,
@@ -26,32 +23,6 @@ export const registerCaptureCommands = (
"inspect" | "inspectFields" | "close"
> = createPacketCaptureService(environment),
): void => {
const finish = async (
result: Awaited<ReturnType<PacketCaptureService["inspect"]>>,
operation: string,
) => {
// A one-shot command must retry retained cleanup before discarding its owner.
try {
await service.close();
} catch (cause) {
const cleanup =
cause instanceof AnalysisError
? cause
: new ProviderCleanupError(
"tshark-capture",
[],
{ reason: String(cause) },
{ cause, operation: operation },
);
if (result.ok) cleanup.retainPartialObservation(result.value);
return projectAnalysisError(
result.ok
? cleanup
: analysisErrorWithCleanupFailure(result.error, cleanup, operation),
);
}
return result.ok ? result.value : projectAnalysisError(result.error);
};
cli.command(CLI_COMMANDS.inspectPacketFields, {
description: "Search installed TShark protocol and field definitions",
options: z
@@ -80,11 +51,14 @@ export const registerCaptureCommands = (
run: ({ options: { all, ...options } }) =>
withCommandCancellation((signal) =>
logCliCommand(logger, CLI_COMMANDS.inspectPacketFields, async () =>
finish(
await service.inspectFields(
{ ...options, ...(all ? { limit: null } : {}) },
{ signal },
),
finishAnalysisCommand(
() =>
service.inspectFields(
{ ...options, ...(all ? { limit: null } : {}) },
{ signal },
),
service,
"tshark-capture",
"inspect_packet_fields",
),
),
@@ -125,15 +99,20 @@ export const registerCaptureCommands = (
run: ({ args, options: { all_matches, ...options } }) =>
withCommandCancellation((signal) =>
logCliCommand(logger, CLI_COMMANDS.inspectPacketCapture, async () => {
const result = await service.inspect(
{
...options,
...(all_matches ? { match_limit: null } : {}),
path: resolve(args.path),
},
{ signal },
return finishAnalysisCommand(
() =>
service.inspect(
{
...options,
...(all_matches ? { match_limit: null } : {}),
path: resolve(args.path),
},
{ signal },
),
service,
"tshark-capture",
"inspect_packet_capture",
);
return finish(result, "inspect_packet_capture");
}),
),
});
+69
View File
@@ -0,0 +1,69 @@
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import {
AnalysisError,
type AnalysisPartialObservation,
} from "../domain/analysisErrorBase.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import type { Result } from "../domain/result.js";
/** Finish a one-shot CLI operation without discarding its primary result on close failure. */
export const finishAnalysisCommand = async <
Value extends AnalysisPartialObservation,
>(
run: () => Promise<Result<Value, AnalysisError>>,
service: { close(): Promise<void> },
providerId: string,
canonicalOperation: string,
fallbackResource?: string,
): Promise<Value | ReturnType<typeof projectAnalysisError>> => {
let result: Result<Value, AnalysisError>;
try {
result = await run();
} catch (cause) {
result = {
ok: false,
error:
cause instanceof AnalysisError
? cause
: new ProviderAdapterError(providerId, canonicalOperation, { cause }),
};
}
try {
await service.close();
} catch (cause) {
let cleanup: AnalysisError;
if (cause instanceof AnalysisError) cleanup = cause;
else {
const observation =
cause instanceof ArtifactReaderFailure
? ArtifactReaderFailure.cleanupObservation(
cause,
fallbackResource ?? `${canonicalOperation} resources`,
)
: {
reason: cause instanceof Error ? cause.message : String(cause),
resources: [],
};
cleanup = new ProviderCleanupError(
providerId,
observation.resources,
{ reason: observation.reason },
{ cause, operation: canonicalOperation },
);
}
if (result.ok) cleanup.retainPartialObservation(result.value);
return projectAnalysisError(
result.ok
? cleanup
: analysisErrorWithCleanupFailure(
result.error,
cleanup,
canonicalOperation,
),
);
}
return result.ok ? result.value : projectAnalysisError(result.error);
};
+15 -11
View File
@@ -3,14 +3,13 @@ import { resolve } from "node:path";
import { createGoBinaryService } from "../composition/go.js";
import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type { Logger } from "pino";
import type { CliInstance } from "./types.js";
import { withCommandCancellation } from "./commandCancellation.js";
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
/** Resolve caller paths and inspect static build metadata through the shared workflow. */
export const registerGoCommands = (cli: CliInstance, logger: Logger): void => {
const service = createGoBinaryService();
cli.command(CLI_COMMANDS.inspectGoBinary, {
description:
"Inspect embedded Go compiler, modules and build settings without target execution",
@@ -18,14 +17,19 @@ export const registerGoCommands = (cli: CliInstance, logger: Logger): void => {
path: z.string().describe("Local ELF, PE or thin Mach-O image"),
}),
run: ({ args }) =>
withCommandCancellation((signal) =>
logCliCommand(logger, CLI_COMMANDS.inspectGoBinary, async () => {
const result = await service.inspect(
{ path: resolve(args.path) },
{ signal },
);
return result.ok ? result.value : projectAnalysisError(result.error);
}),
),
withCommandCancellation(async (signal) => {
const service = createGoBinaryService();
return await logCliCommand(
logger,
CLI_COMMANDS.inspectGoBinary,
async () =>
finishAnalysisCommand(
() => service.inspect({ path: resolve(args.path) }, { signal }),
service,
"go-build-info",
"inspect_go_binary",
),
);
}),
});
};
+22 -43
View File
@@ -1,9 +1,6 @@
import { inspectSignalDecodersInputSchema } from "../domain/signals/signalDecoders.js";
import { z } from "incur";
import type { SignalRecordingService } from "../application/signals/SignalRecordingService.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { resolve } from "node:path";
import { createSignalRecordingService } from "../composition/signals.js";
import {
@@ -13,10 +10,10 @@ import {
} from "../domain/signals/signalRecording.js";
import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type { Logger } from "pino";
import type { CliInstance } from "./types.js";
import { withCommandCancellation } from "./commandCancellation.js";
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
export const registerSignalCommands = (
cli: CliInstance,
logger: Logger,
@@ -26,32 +23,6 @@ export const registerSignalCommands = (
"decode" | "inspectDecoders" | "close"
> = createSignalRecordingService(environment),
): void => {
const finish = async (
result: Awaited<ReturnType<SignalRecordingService["decode"]>>,
operation: string,
) => {
// A one-shot command must retry retained cleanup before discarding its owner.
try {
await service.close();
} catch (cause) {
const cleanup =
cause instanceof AnalysisError
? cause
: new ProviderCleanupError(
"sigrok-recording",
[],
{ reason: String(cause) },
{ cause, operation: operation },
);
if (result.ok) cleanup.retainPartialObservation(result.value);
return projectAnalysisError(
result.ok
? cleanup
: analysisErrorWithCleanupFailure(result.error, cleanup, operation),
);
}
return result.ok ? result.value : projectAnalysisError(result.error);
};
cli.command(CLI_COMMANDS.inspectSignalDecoders, {
description: "Search installed sigrok decoders or selected decoder help",
options: z
@@ -82,11 +53,14 @@ export const registerSignalCommands = (
run: ({ options: { all, ...options } }) =>
withCommandCancellation((signal) =>
logCliCommand(logger, CLI_COMMANDS.inspectSignalDecoders, async () =>
finish(
await service.inspectDecoders(
{ ...options, ...(all ? { limit: null } : {}) },
{ signal },
),
finishAnalysisCommand(
() =>
service.inspectDecoders(
{ ...options, ...(all ? { limit: null } : {}) },
{ signal },
),
service,
"sigrok-recording",
"inspect_signal_decoders",
),
),
@@ -127,15 +101,20 @@ export const registerSignalCommands = (
run: ({ args, options: { all_lines, ...options } }) =>
withCommandCancellation((signal) =>
logCliCommand(logger, CLI_COMMANDS.decodeSignalRecording, async () => {
const result = await service.decode(
{
...options,
...(all_lines ? { line_limit: null } : {}),
path: resolve(args.path),
},
{ signal },
return finishAnalysisCommand(
() =>
service.decode(
{
...options,
...(all_lines ? { line_limit: null } : {}),
path: resolve(args.path),
},
{ signal },
),
service,
"sigrok-recording",
"decode_signal_recording",
);
return finish(result, "decode_signal_recording");
}),
),
});
+18 -14
View File
@@ -3,10 +3,10 @@ import { WEB_NETWORK_CAPTURE_FORMATS } from "../domain/webNetworkCapture.js";
import { createWebNetworkCaptureService } from "../composition/webNetworkCaptures.js";
import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type { Logger } from "pino";
import type { CliInstance } from "./types.js";
import { withCommandCancellation } from "./commandCancellation.js";
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
/** Expose offline historical capture inspection with the same selection contract as MCP. */
export const registerWebNetworkCaptureCommands = (
@@ -42,20 +42,24 @@ export const registerWebNetworkCaptureCommands = (
logger,
CLI_COMMANDS.inspectWebNetworkCapture,
async () => {
const result = await service.inspect(
{
capture_path: args.capturePath,
format: args.format,
sensitive_values: options.sensitiveValue,
...(options.record === undefined
? {}
: { record_ordinals: options.record }),
},
{ signal },
return finishAnalysisCommand(
() =>
service.inspect(
{
capture_path: args.capturePath,
format: args.format,
sensitive_values: options.sensitiveValue,
...(options.record === undefined
? {}
: { record_ordinals: options.record }),
},
{ signal },
),
service,
"web-network-capture",
"inspect_web_network_capture",
"Web network capture resources",
);
return result.ok
? result.value
: projectAnalysisError(result.error);
},
),
),
@@ -1,4 +1,4 @@
import { moduleKindForJavaScriptReference } from "../application/javascript/JavaScriptArtifactPathResolution.js";
import { moduleResolutionModeForJavaScriptReference } from "../domain/javascript/javascriptModuleResolutionMode.js";
import { parseJavaScriptSource } from "../domain/javascript/javascriptSourceParser.js";
import { analyzeParsedJavaScriptStaticSourceSteps } from "../domain/javascript/javascriptStaticAnalysis.js";
import {
@@ -56,7 +56,7 @@ const analyze: JavaScriptSourceWorkerAnalyzer = async (
const ir = await completeJavaScriptAnalysisSteps(
analyzeParsedJavaScriptSemanticsSteps(
parsed,
moduleKindForJavaScriptReference(file.path, "static-import"),
moduleResolutionModeForJavaScriptReference(file.path, "static-import"),
),
);
parsed = null;
@@ -0,0 +1,23 @@
import { posix } from "node:path";
/** Loader evidence retained for a source-level module reference. */
export type JavaScriptModuleResolutionMode =
| "import"
| "require"
| "compiler-dependent";
/** Derive source mode only when syntax or an explicit source format owns it. */
export const moduleResolutionModeForJavaScriptReference = (
sourcePath: string,
referenceKind: "static-import" | "dynamic-import" | "require",
explicitMode?: JavaScriptModuleResolutionMode,
): JavaScriptModuleResolutionMode => {
if (explicitMode !== undefined) return explicitMode;
if (referenceKind === "require") return "require";
if (referenceKind === "dynamic-import") return "import";
const extension = posix.extname(sourcePath).toLowerCase();
if (extension === ".cts") return "require";
if (extension === ".mts") return "import";
if (extension === ".ts" || extension === ".tsx") return "compiler-dependent";
return "import";
};
@@ -68,6 +68,7 @@ import {
import { isJavaScriptRpcClientFactory } from "./javascriptRpcEndpoints.js";
import { createSemanticModuleInterop } from "./javascriptModuleInterop.js";
import { SemanticPropertyPathCoverage } from "./javascriptSemanticPropertyPaths.js";
import type { JavaScriptModuleResolutionMode } from "./javascriptModuleResolutionMode.js";
interface BindPatternInput {
readonly pattern: t.Node;
@@ -138,7 +139,7 @@ export function* indexJavaScriptBindingsSteps(
/** Recover semantics from an already parsed JavaScript artifact. */
export const analyzeParsedJavaScriptSemantics = (
file: ParsedJavaScriptSource,
staticImportResolutionMode: "import" | "require" = "import",
staticImportResolutionMode: JavaScriptModuleResolutionMode = "import",
): JavaScriptSemanticIr =>
completeSemanticSteps(
analyzeParsedJavaScriptSemanticsSteps(file, staticImportResolutionMode),
@@ -152,7 +153,7 @@ export const analyzeParsedJavaScriptSemantics = (
*/
export function* analyzeParsedJavaScriptSemanticsSteps(
file: ParsedJavaScriptSource,
staticImportResolutionMode: "import" | "require" = "import",
staticImportResolutionMode: JavaScriptModuleResolutionMode = "import",
): Generator<void, JavaScriptSemanticIr> {
const state = createState(file.program, staticImportResolutionMode);
yield* collectDefinitionsSteps(file.program, state);
@@ -539,7 +540,7 @@ const bindingOrigin = (
const createState = (
program: t.Program,
staticImportResolutionMode: "import" | "require" = "import",
staticImportResolutionMode: JavaScriptModuleResolutionMode = "import",
): JavaScriptSemanticAnalysisState => {
const root: JavaScriptSemanticScopeState = {
scopeId: semanticScopeId("program", program),
@@ -1216,8 +1217,11 @@ const addBinding = (input: AddBindingInput): void => {
if (directOrigin !== undefined)
binding.directOrigins.push(
directOrigin.resolutionMode === undefined &&
state.staticImportResolutionMode === "require"
? { ...directOrigin, resolutionMode: "require" }
state.staticImportResolutionMode !== "import"
? {
...directOrigin,
resolutionMode: state.staticImportResolutionMode,
}
: directOrigin,
);
binding.runtimeImport ||= runtimeImport === true;
@@ -4,15 +4,19 @@ import type {
JavaScriptSemanticCoverage,
JavaScriptSemanticReturnCoverage,
} from "./javascriptSemanticCoverage.js";
import type { JavaScriptModuleResolutionMode } from "./javascriptModuleResolutionMode.js";
/** One exact module origin followed through imports, requires, or aliases. */
export interface JavaScriptModuleOrigin {
readonly resolutionMode?: "import" | "require";
readonly resolutionMode?: JavaScriptModuleResolutionMode;
readonly specifier: string;
readonly importedPath: readonly string[];
}
/** Fail-closed provenance classification for one binding. */
/**
* Fail-closed module-alias provenance for one binding, not transitive data flow.
* Locally constructed values may contain or derive from imported values.
*/
export type JavaScriptBindingProvenance =
| {
readonly status: "module";
@@ -393,7 +397,7 @@ export interface JavaScriptSemanticFrontier {
/** Static import/export relationship retained for cross-file composition. */
export interface JavaScriptSemanticModuleLink {
readonly resolutionMode?: "import" | "require";
readonly resolutionMode?: JavaScriptModuleResolutionMode;
readonly kind:
| "import"
| "type-import"
@@ -533,7 +533,20 @@ const addModuleLink = (
},
referenceNode: t.Node,
): void => {
const collected = { ...link, callableId: link.callableId ?? null };
const resolutionMode =
link.resolutionMode ??
(link.kind === "import" ||
link.kind === "re-export" ||
link.kind === "type-import"
? state.staticImportResolutionMode
: link.kind === "require"
? "require"
: undefined);
const collected = {
...link,
...(resolutionMode === undefined ? {} : { resolutionMode }),
callableId: link.callableId ?? null,
};
state.moduleLinks.push(collected);
if (link.localName !== null) {
const binding = resolveSemanticBindingState(
@@ -0,0 +1,94 @@
import { describe, expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
import {
onlyBinding,
topLevelBinding,
} from "./javascriptSemanticAnalysis.fixture.js";
describe("JavaScript semantic binding provenance", () => {
it("keeps opaque expression results unknown instead of declaring them local", () => {
const ir = analyzeJavaScriptSemantics(`
const called = loadFeature();
const constructed = new Feature();
const tagged = tag\`feature\`;
const dynamicRequired = require(specifier);
const sequence = (0, loadFeature());
const assignment = (slot = loadFeature());
async function readLater(parameter = require("fallback")) {
const awaited = await loadFeature();
return awaited;
}
try { loadFeature(); } catch (caught) { void caught; }
function* yieldLater() {
const yielded = yield loadFeature();
return yielded;
}
`);
for (const name of [
"called",
"constructed",
"tagged",
"dynamicRequired",
"sequence",
"assignment",
"awaited",
"yielded",
"parameter",
"caught",
]) {
expect(onlyBinding(ir, name).provenance).toMatchObject({
status: "unknown",
origins: [],
});
}
});
it("recognizes explicit local values and preserves exact module aliases", () => {
const ir = analyzeJavaScriptSemantics(`
const object = { value: 1 };
const array = [1, 2];
const template = \`feature\`;
const primitive = -1 + 2;
const derived = loadFeature() + 1;
const derivedText = \`value: \${loadFeature()}\`;
let uninitialized;
const callable = () => 1;
const Constructed = class {};
const imported = require("feature");
const alias = imported;
const sequence = (0, require("sequence-feature"));
const assignment = (slot = require("assignment-feature"));
`);
for (const name of [
"object",
"array",
"template",
"primitive",
"derived",
"derivedText",
"uninitialized",
"callable",
"Constructed",
])
expect(topLevelBinding(ir, name).provenance).toMatchObject({
status: "local",
origins: [],
});
expect(topLevelBinding(ir, "alias").provenance).toMatchObject({
status: "module",
origins: [{ specifier: "feature" }],
});
expect(topLevelBinding(ir, "sequence").provenance).toMatchObject({
status: "module",
origins: [{ specifier: "sequence-feature" }],
});
expect(topLevelBinding(ir, "assignment").provenance).toMatchObject({
status: "module",
origins: [{ specifier: "assignment-feature" }],
});
});
});
@@ -123,9 +123,7 @@ export const resolveSemanticModuleCallables = (
: undefined;
return {
...link,
...(resolutionMode === "import" || resolutionMode === "require"
? { resolutionMode }
: {}),
...(resolutionMode !== undefined ? { resolutionMode } : {}),
callableId: resolved.length === 1 ? (resolved[0] ?? null) : null,
};
});
@@ -12,6 +12,7 @@ import type {
JavaScriptSemanticCallable,
JavaScriptSemanticScope,
} from "./javascriptSemanticIr.js";
import type { JavaScriptModuleResolutionMode } from "./javascriptModuleResolutionMode.js";
/** Internal initializer plus a destructuring/member projection. */
interface JavaScriptSemanticInitializer {
@@ -63,7 +64,7 @@ export interface JavaScriptSemanticScopeState {
/** Shared state for semantic collection and evaluation. */
export interface JavaScriptSemanticAnalysisState {
/** Effective loader for static imports in this source artifact. */
readonly staticImportResolutionMode: "import" | "require";
readonly staticImportResolutionMode: JavaScriptModuleResolutionMode;
readonly parentsByNode: WeakMap<t.Node, t.Node>;
readonly scopes: JavaScriptSemanticScopeState[];
readonly scopesById: Map<string, JavaScriptSemanticScopeState>;
@@ -817,6 +817,13 @@ const provenanceForBindingValue = (
binding: JavaScriptSemanticBindingState,
context: EvaluationContext,
): JavaScriptBindingProvenance => {
if (binding.kind === "parameter" || binding.kind === "catch")
return semanticUnresolvedProvenance(
"unknown",
binding.kind === "parameter"
? "Parameter provenance depends on caller arguments."
: "Catch binding provenance depends on the thrown value.",
);
if (binding.directOrigins.length > 0)
return semanticOriginsProvenance(binding.directOrigins);
if (binding.initializers.length === 0) return semanticLocalProvenance();
@@ -890,6 +897,14 @@ const provenanceForExpression = (
const required = semanticRequireOrigin(node, context.state);
if (required !== undefined)
return semanticOriginsProvenance([required.origin]);
if (t.isSequenceExpression(node)) {
const finalExpression = node.expressions.at(-1);
return finalExpression === undefined
? semanticUnresolvedProvenance("unknown", "Empty sequence expression.")
: provenanceForExpression(finalExpression, nestedContext(context));
}
if (t.isAssignmentExpression(node) && node.operator === "=")
return provenanceForExpression(node.right, nestedContext(context));
if (t.isIdentifier(node)) {
const binding = resolveSemanticBindingState(context.state, node, node.name);
return binding === undefined
@@ -961,9 +976,25 @@ const provenanceForExpression = (
"Conditional provenance is unresolved.",
);
}
return semanticLocalProvenance();
if (isLocallyCreatedValue(node)) return semanticLocalProvenance();
return semanticUnresolvedProvenance(
"unknown",
`Unsupported ${node.type} provenance.`,
);
};
const isLocallyCreatedValue = (node: t.Node): boolean =>
readExactJavaScriptLiteral(node).found ||
t.isObjectExpression(node) ||
t.isArrayExpression(node) ||
t.isFunctionExpression(node) ||
t.isArrowFunctionExpression(node) ||
t.isClassExpression(node) ||
t.isTemplateLiteral(node) ||
t.isUnaryExpression(node) ||
t.isBinaryExpression(node) ||
t.isUpdateExpression(node);
const mergeValues = (
values: readonly JavaScriptSemanticValue[],
): JavaScriptSemanticValue => {
@@ -1,3 +1,4 @@
import type { ProcessTraceSpecification } from "./processTraceSpecification.js";
import { compareProcessCaptures } from "./processComparison.js";
import { parseProcessCapture } from "./processCaptureParsing.js";
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js";
@@ -112,3 +113,56 @@ export const compareUnverifiedProcessCaptures = (
parseProcessCapture(right),
options,
);
/** One journal and its matching declared trace, shared by domain and adapter checks. */
export const processTraceCaptureFixture = () => {
const capture = {
...EMPTY_PROCESS_CAPTURE_EXAMPLE,
event_journal: [
{ capture_order: 0, collection: "filesystem_checkpoints", index: 0 },
{ capture_order: 1, collection: "lifecycle", index: 0 },
{ capture_order: 2, collection: "lifecycle", index: 1 },
{ capture_order: 3, collection: "filesystem_checkpoints", index: 1 },
],
} as const;
const [before, after] = capture.filesystem_checkpoints;
if (before === undefined || after === undefined)
throw new Error(
"Trace fixture requires before and after filesystem checkpoints",
);
const traceSpecification: ProcessTraceSpecification = {
events: [
{
id: "before",
source: "filesystem",
exact: before,
cardinality: { kind: "required" },
},
{
id: "exit",
source: "lifecycle",
exact: { event: "exit", ...capture.exit },
cardinality: { kind: "required" },
},
{
id: "settlement",
source: "lifecycle",
exact: { event: "settlement", ...capture.settlement },
cardinality: { kind: "required" },
},
{
id: "after",
source: "filesystem",
exact: after,
cardinality: { kind: "required" },
},
],
language: {
kind: "finite_traces",
variants: [
{ id: "normal", trace: ["before", "exit", "settlement", "after"] },
],
},
};
return { capture, traceSpecification };
};
@@ -1,72 +1,13 @@
import { describe, expect, it } from "vitest";
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js";
import { accountFullyObservedProcessCapture } from "./processCapture.fixture.js";
import {
processTraceCaptureFixture,
accountFullyObservedProcessCapture,
} from "./processCapture.fixture.js";
import { compareProcessCaptures } from "./processComparison.js";
import { parseProcessCapture } from "./processCaptureParsing.js";
import type { ProcessTraceSpecification } from "./processTraceSpecification.js";
const beforeCheckpoint = {
name: "before",
at_ms: 0,
files: [],
effects: [],
truncated: false,
};
const afterCheckpoint = {
name: "after_settlement",
at_ms: 50,
files: [],
effects: [],
truncated: false,
};
const capture = {
...EMPTY_PROCESS_CAPTURE_EXAMPLE,
event_journal: [
{ capture_order: 0, collection: "filesystem_checkpoints", index: 0 },
{ capture_order: 1, collection: "lifecycle", index: 0 },
{ capture_order: 2, collection: "lifecycle", index: 1 },
{ capture_order: 3, collection: "filesystem_checkpoints", index: 1 },
],
} as const;
const traceSpecification: ProcessTraceSpecification = {
events: [
{
id: "before",
source: "filesystem",
exact: beforeCheckpoint,
cardinality: { kind: "required" },
},
{
id: "exit",
source: "lifecycle",
exact: { event: "exit", ...capture.exit },
cardinality: { kind: "required" },
},
{
id: "settlement",
source: "lifecycle",
exact: { event: "settlement", ...capture.settlement },
cardinality: { kind: "required" },
},
{
id: "after",
source: "filesystem",
exact: afterCheckpoint,
cardinality: { kind: "required" },
},
],
language: {
kind: "finite_traces",
variants: [
{
id: "normal",
trace: ["before", "exit", "settlement", "after"],
},
],
},
};
const { capture, traceSpecification } = processTraceCaptureFixture();
describe("declared trace comparison nonconformance", () => {
it("does not call identical captures changed when both violate the language", () => {
+38 -19
View File
@@ -39,6 +39,9 @@ export const evmInterfaceFailure = (
limiter = "/usr/bin/prlimit",
fileFailure?: EvmFileSizeFailureEvidence,
): AnalysisError => {
const cleanup =
cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined;
const cleanupOptions = cleanup === undefined ? {} : { cleanup };
if (cause instanceof AnalysisError) return cause;
if (cause instanceof OwnedCommandFailure) {
const outputOptions =
@@ -64,12 +67,15 @@ export const evmInterfaceFailure = (
{ operation: "inspect_evm_interface", cause },
);
if (cause.reason === "cancelled")
return new AnalysisCancelledError("inspect_evm_interface", outputOptions);
return new AnalysisCancelledError("inspect_evm_interface", {
...outputOptions,
...cleanupOptions,
});
if (cause.reason === "timeout")
return new AnalysisTimeoutError(
"inspect_evm_interface",
EVM_INTERFACE_LIMITS.timeoutMs,
outputOptions,
{ ...outputOptions, ...cleanupOptions },
);
if (cause.reason === "output-limit")
return new AnalysisOutputError(
@@ -122,25 +128,33 @@ export const evmInterfaceFailure = (
}
if (cause instanceof ArtifactReaderFailure) {
if (cause.reason === "cancelled")
return new AnalysisCancelledError("inspect_evm_interface");
return new AnalysisCancelledError("inspect_evm_interface", {
cause,
...cleanupOptions,
});
if (cause.reason === "integrity")
return new AnalysisArtifactChangedError(
"inspect_evm_interface",
path,
cause.message,
{ cause },
{ cause, ...cleanupOptions },
);
if (
phase === "artifact-read" &&
["limit", "path", "format"].includes(cause.reason)
)
return new AnalysisInputError("inspect_evm_interface", { cause }, [
{
path: ["path"],
reason: cause.reason === "limit" ? "out_of_range" : "invalid_format",
message: cause.message,
},
]);
return new AnalysisInputError(
"inspect_evm_interface",
{ cause, ...cleanupOptions },
[
{
path: ["path"],
reason:
cause.reason === "limit" ? "out_of_range" : "invalid_format",
message: cause.message,
},
],
);
}
if (phase === "artifact-read" && cause instanceof Error && "code" in cause) {
if (cause.code === "EACCES" || cause.code === "EPERM")
@@ -148,22 +162,27 @@ export const evmInterfaceFailure = (
"inspect_evm_interface",
path,
cause.code,
{ cause },
{ cause, ...cleanupOptions },
);
if (cause.code === "ENOENT" || cause.code === "ENOTDIR")
return new AnalysisInputError("inspect_evm_interface", { cause }, [
{
path: ["path"],
reason: "invalid_value",
message: `Selected bytecode carrier could not be read (${String(cause.code)}): ${path}.`,
},
]);
return new AnalysisInputError(
"inspect_evm_interface",
{ cause, ...cleanupOptions },
[
{
path: ["path"],
reason: "invalid_value",
message: `Selected bytecode carrier could not be read (${String(cause.code)}): ${path}.`,
},
],
);
}
return new ProviderAdapterError(
EVMOLE_PROVIDER_IDENTITY.id,
"inspect_evm_interface",
{
cause,
...cleanupOptions,
diagnostics: {
phase,
path,
+96 -20
View File
@@ -13,6 +13,8 @@ import type {
EvmInterfacePort,
} from "../application/evm/EvmInterfacePort.js";
import { readStableArtifact } from "../artifacts/readStableArtifact.js";
import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import { OwnedCommandFailure } from "../process/OwnedCommand.js";
import type {
AnalysisError,
@@ -78,6 +80,7 @@ type Launcher = NonNullable<Parameters<typeof runOwnedCommand>[2]>["launcher"];
/** Run unchanged EVMole/WASM in an owned worker; no target, chain or network execution. */
export class EvmoleInterfaceProvider implements EvmInterfacePort {
readonly #resources = new ArtifactResourceScope();
#tail: Promise<void> = Promise.resolve();
#closing = false;
#closePromise: Promise<void> | undefined;
@@ -102,9 +105,14 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort {
options?: ExecutionOptions,
): Promise<Result<EvmInterfaceExecution, AnalysisError>> {
if (this.#closing) return Promise.resolve(err(this.#closedError()));
const operation = this.#tail.then(() =>
this.#closing ? err(this.#closedError()) : this.#inspect(input, options),
);
const operation = this.#tail.then(async () => {
if (this.#closing) return err(this.#closedError());
try {
return await this.#resources.run(() => this.#inspect(input, options));
} catch (cause: unknown) {
return err(evmInterfaceFailure(cause, "artifact-read", input.path));
}
});
this.#tail = operation.then(
() => undefined,
() => undefined,
@@ -180,6 +188,8 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort {
input.path,
EVM_INTERFACE_LIMITS.inputBytes,
options?.signal,
undefined,
this.#resources,
);
phase = "worker";
root = await this.createRuntime();
@@ -243,15 +253,27 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort {
replyPath,
EVM_INTERFACE_LIMITS.outputBytes,
options?.signal,
undefined,
this.#resources,
);
reply = replySchema.parse(JSON.parse(file.bytes.toString("utf8")));
} catch (cause: unknown) {
const cleanup =
cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined;
if (options?.signal?.aborted)
throw new AnalysisCancelledError(OPERATION, { capturedOutput });
throw new AnalysisCancelledError(OPERATION, {
cause,
capturedOutput,
...(cleanup === undefined ? {} : { cleanup }),
});
throw new AnalysisOutputError(
OPERATION,
`Owned interface worker reply failed for ${input.path}: ${cause instanceof Error ? cause.message : String(cause)}`,
{ cause, capturedOutput },
{
cause,
capturedOutput,
...(cleanup === undefined ? {} : { cleanup }),
},
);
}
if (!reply.ok) {
@@ -355,6 +377,7 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort {
if (cause instanceof OwnedCommandFailure)
processOwner = cause.cleanupOwner;
let fileFailure: EvmFileSizeFailureEvidence | undefined;
let markerCleanupFailure: ArtifactReaderFailure | undefined;
if (
cause instanceof OwnedCommandFailure &&
cause.snapshot?.exitCode === EVM_FILE_SIZE_FAILURE_EXIT &&
@@ -365,6 +388,9 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort {
const marker = await readStableArtifact(
join(root.path, "resource.failure"),
1,
undefined,
undefined,
this.#resources,
);
if (!marker.bytes.equals(Buffer.from("F")))
throw new Error(
@@ -372,6 +398,14 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort {
);
fileFailure = { verified: true, failure: null };
} catch (markerFailure: unknown) {
if (
markerFailure instanceof ArtifactReaderFailure &&
markerFailure.cleanup !== undefined
)
markerCleanupFailure = ArtifactReaderFailure.withCleanup(
cause,
markerFailure.cleanup,
);
fileFailure = {
verified: false,
failure:
@@ -382,23 +416,36 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort {
}
}
result = err(
options?.signal?.aborted &&
(cause === options.signal.reason ||
(cause instanceof Error && cause.name === "AbortError"))
? new AnalysisCancelledError(
OPERATION,
retainedOutput === undefined
? undefined
: { capturedOutput: retainedOutput },
)
: evmInterfaceFailure(
cause,
phase,
markerCleanupFailure !== undefined
? evmInterfaceFailure(
markerCleanupFailure,
"artifact-read",
input.path,
workerLimits,
limiter,
fileFailure,
),
)
: options?.signal?.aborted &&
(cause === options.signal.reason ||
(cause instanceof Error && cause.name === "AbortError"))
? new AnalysisCancelledError(OPERATION, {
cause,
...(retainedOutput === undefined
? {}
: { capturedOutput: retainedOutput }),
...(cause instanceof ArtifactReaderFailure &&
cause.cleanup !== undefined
? { cleanup: cause.cleanup }
: {}),
})
: evmInterfaceFailure(
cause,
phase,
input.path,
workerLimits,
limiter,
fileFailure,
),
);
}
if (processOwner !== undefined) {
@@ -447,8 +494,37 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort {
this.#closing = true;
this.#closePromise ??= this.#tail
.then(async () => {
const failure = await this.#retire();
if (failure !== undefined) throw failure;
const outcomes = await Promise.allSettled([
this.#retire(),
this.#resources.close(),
]);
const failures = outcomes.flatMap((outcome) =>
outcome.status === "rejected"
? [outcome.reason]
: outcome.value === undefined
? []
: [outcome.value],
);
if (failures.length > 0) {
const resources = failures.flatMap((failure) =>
failure instanceof ProviderCleanupError
? failure.cleanupResources
: failure instanceof ArtifactReaderFailure &&
failure.cleanup !== undefined
? failure.cleanup.resources
: ["artifact-resources"],
);
throw new ProviderCleanupError(
EVMOLE_PROVIDER_IDENTITY.id,
[...new Set(resources)],
{
failures: failures.map((failure) =>
failure instanceof Error ? failure.message : String(failure),
),
},
{ operation: OPERATION, cause: new AggregateError(failures) },
);
}
})
.catch((cause: unknown) => {
this.#closePromise = undefined;
+41 -12
View File
@@ -1,5 +1,7 @@
import { readStableArtifact } from "../artifacts/readStableArtifact.js";
import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import type { ExecutionOptions } from "../application/AnalysisProvider.js";
import type { GoBinaryPort } from "../application/go/GoBinaryPort.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
@@ -18,6 +20,7 @@ import {
type InspectGoBinaryInput,
} from "../domain/go/goBinary.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { err, ok, type Result } from "../domain/result.js";
import {
readGoBinaryImage,
@@ -36,13 +39,19 @@ const OPERATION = "inspect_go_binary";
const INPUT_BYTES = 256 * 1024 * 1024;
const OUTPUT_BYTES = 8 * 1024 * 1024;
const failureFor = (
const failureForPrimary = (
cause: unknown,
path: string,
signal?: AbortSignal,
): AnalysisError => {
if (cause instanceof AnalysisError) return cause;
if (signal?.aborted) return new AnalysisCancelledError(OPERATION);
if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity")
return new AnalysisArtifactChangedError(OPERATION, path, cause.message, {
cause,
});
if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled")
return new AnalysisCancelledError(OPERATION, { cause });
if (signal?.aborted) return new AnalysisCancelledError(OPERATION, { cause });
if (cause instanceof GoBinaryResourceFailure)
return new AnalysisResourceConstraintError(
OPERATION,
@@ -64,12 +73,6 @@ const failureFor = (
},
]);
if (cause instanceof ArtifactReaderFailure) {
if (cause.reason === "integrity")
return new AnalysisArtifactChangedError(OPERATION, path, cause.message, {
cause,
});
if (cause.reason === "cancelled")
return new AnalysisCancelledError(OPERATION);
if (cause.reason === "limit")
return new AnalysisResourceConstraintError(
OPERATION,
@@ -110,6 +113,23 @@ const failureFor = (
});
};
const failureFor = (
cause: unknown,
path: string,
signal?: AbortSignal,
): AnalysisError => {
const primary = failureForPrimary(cause, path, signal);
if (!(cause instanceof ArtifactReaderFailure) || cause.cleanup === undefined)
return primary;
const cleanup = new ProviderCleanupError(
GO_BINARY_PROVIDER_IDENTITY.id,
cause.cleanup.resources,
{ reason: cause.cleanup.reason },
{ operation: OPERATION, cause },
);
return analysisErrorWithCleanupFailure(primary, cleanup, OPERATION);
};
const outputLimit = (path: string) =>
new AnalysisResourceConstraintError(
OPERATION,
@@ -121,6 +141,11 @@ const outputLimit = (path: string) =>
/** Stable in-process metadata inspection without subprocesses, temporary files or Go installation. */
export class GoBinaryProvider implements GoBinaryPort {
readonly identity = GO_BINARY_PROVIDER_IDENTITY;
readonly #resources = new ArtifactResourceScope();
close(): Promise<void> {
return this.#resources.close();
}
/** Read complete compiler/module metadata while preserving original byte identity and source ranges. */
async inspect(
@@ -128,10 +153,14 @@ export class GoBinaryProvider implements GoBinaryPort {
options?: ExecutionOptions,
): Promise<Result<GoBinary, AnalysisError>> {
try {
const snapshot = await readStableArtifact(
input.path,
INPUT_BYTES,
options?.signal,
const snapshot = await this.#resources.run(() =>
readStableArtifact(
input.path,
INPUT_BYTES,
options?.signal,
undefined,
this.#resources,
),
);
options?.signal?.throwIfAborted();
const image = readGoBinaryImage(snapshot.bytes);
+9 -3
View File
@@ -40,6 +40,7 @@ interface Layout {
readonly cpu: number;
readonly offset: number;
readonly size: number;
readonly alignmentExponent?: number;
}
/**
@@ -57,12 +58,12 @@ const largeUniversalTarget = async (
const bytes = Buffer.alloc(total);
bytes.writeUInt32BE(0xcafebabe, 0);
bytes.writeUInt32BE(layout.length, 4);
layout.forEach(({ cpu, offset, size }, index) => {
layout.forEach(({ cpu, offset, size, alignmentExponent = 14 }, index) => {
const entry = 8 + index * 20;
bytes.writeUInt32BE(cpu, entry);
bytes.writeUInt32BE(offset, entry + 8);
bytes.writeUInt32BE(size, entry + 12);
bytes.writeUInt32BE(12, entry + 16);
bytes.writeUInt32BE(alignmentExponent, entry + 16);
bytes.fill(0x11 * (index + 1), offset, offset + size);
thinMach(0xfeedfacf, cpu).copy(bytes, offset);
});
@@ -122,7 +123,12 @@ describe("IDA workspace input thinning", () => {
async () => {
const { bytes, target } = await largeUniversalTarget(
[
{ cpu: 0x01000007, offset: 4096, size: 8480 },
{
cpu: 0x01000007,
offset: 4096,
size: 8480,
alignmentExponent: 12,
},
{ cpu: 0x0100000c, offset: 16384, size: 33464 },
{ cpu: 0x00000007, offset: 65536, size: 33464 },
],
@@ -475,7 +475,9 @@ const origin = z
.strictObject({
specifier: z.string(),
importedPath: strings,
resolutionMode: z.enum(["import", "require"]).optional(),
resolutionMode: z
.enum(["import", "require", "compiler-dependent"])
.optional(),
})
.transform(({ resolutionMode, ...rest }) => ({
...rest,
@@ -530,7 +532,9 @@ const coverage = z
});
const moduleLink = z
.strictObject({
resolutionMode: z.enum(["import", "require"]).optional(),
resolutionMode: z
.enum(["import", "require", "compiler-dependent"])
.optional(),
kind: z.enum([
"import",
"type-import",
+10 -2
View File
@@ -9,7 +9,11 @@ import type {
import { SafeOutputTree } from "../../artifacts/SafeOutputTree.js";
import { SafeOutputTreeCreationFailure } from "../../artifacts/SafeOutputTreeCreationFailure.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
import {
AnalysisCancelledError,
AnalysisOutputError,
} from "../../domain/analysisErrorCore.js";
import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
import {
javascriptRecoveryResultSchema,
type JavaScriptRecoveryInput,
@@ -144,7 +148,11 @@ export class WakaruProvider implements JavaScriptRecoveryPort {
failed = { cause };
}
if (failed !== undefined) {
const failure = failed.cause;
const failure =
failed.cause instanceof ArtifactReaderFailure &&
failed.cause.reason === "cancelled"
? new AnalysisCancelledError(OPERATION, { cause: failed.cause })
: failed.cause;
const residuals: string[] = [];
const cleanupFailures: { resource: string; reason: string }[] = [];
const cleanupOwner =
+47 -14
View File
@@ -1,5 +1,7 @@
import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
import type { PeResourcesPort } from "../../application/binaryDiagnostics/PeResourcesPort.js";
import type { ExecutionOptions } from "../../application/AnalysisProvider.js";
import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
@@ -12,19 +14,29 @@ import {
} from "../../domain/analysisErrorCore.js";
import type { InspectPeResourcesInput } from "../../domain/native/peResources.js";
import { err, ok } from "../../domain/result.js";
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import { PE_RESOURCES_PROVIDER } from "../../application/InvestigationProviders.js";
import { parsePeResources } from "./PeResourceParser.js";
/** Portable parser over one bounded, identity-checked regular file. */
export class PeResourcesProvider implements PeResourcesPort {
readonly identity = PE_RESOURCES_PROVIDER;
readonly #resources = new ArtifactResourceScope();
close(): Promise<void> {
return this.#resources.close();
}
async inspect(input: InspectPeResourcesInput, options?: ExecutionOptions) {
try {
const snapshot = await readStableArtifact(
input.path,
input.max_file_bytes,
options?.signal,
const snapshot = await this.#resources.run(() =>
readStableArtifact(
input.path,
input.max_file_bytes,
options?.signal,
undefined,
this.#resources,
),
);
return ok(
await parsePeResources(
@@ -44,12 +56,21 @@ export class PeResourcesProvider implements PeResourcesPort {
}
}
const peResourcesFailure = (
const peResourcesFailurePrimary = (
cause: unknown,
input: InspectPeResourcesInput,
signal: AbortSignal | undefined,
) => {
const operation = "inspect_pe_resources";
if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity")
return new AnalysisArtifactChangedError(
operation,
input.path,
cause.message,
{ cause },
);
if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled")
return new AnalysisCancelledError(operation, { cause });
if (signal?.aborted) return new AnalysisCancelledError(operation, { cause });
if (cause instanceof ArtifactReaderFailure) {
@@ -64,13 +85,6 @@ const peResourcesFailure = (
},
{ cause },
);
if (cause.reason === "integrity")
return new AnalysisArtifactChangedError(
operation,
input.path,
cause.message,
{ cause },
);
if (cause.reason === "path" || cause.reason === "format")
return new AnalysisInputError(operation, { cause }, [
{
@@ -79,8 +93,6 @@ const peResourcesFailure = (
message: cause.message,
},
]);
if (cause.reason === "cancelled")
return new AnalysisCancelledError(operation, { cause });
}
if (cause instanceof Error && "code" in cause) {
@@ -106,3 +118,24 @@ const peResourcesFailure = (
{ cause },
);
};
const peResourcesFailure = (
cause: unknown,
input: InspectPeResourcesInput,
signal: AbortSignal | undefined,
) => {
const primary = peResourcesFailurePrimary(cause, input, signal);
if (!(cause instanceof ArtifactReaderFailure) || cause.cleanup === undefined)
return primary;
const cleanup = new ProviderCleanupError(
PE_RESOURCES_PROVIDER.id,
cause.cleanup.resources,
{ reason: cause.cleanup.reason },
{ operation: "inspect_pe_resources", cause },
);
return analysisErrorWithCleanupFailure(
primary,
cleanup,
"inspect_pe_resources",
);
};
+19 -13
View File
@@ -17,6 +17,7 @@ import {
type RecordedCrash,
} from "../../domain/native/recordedCrash.js";
import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
capturedPwntoolsOutput,
@@ -46,6 +47,7 @@ const replySchema = z.discriminatedUnion("ok", [
export const inspectPwndbgCore = async ({
environment,
rootPath,
resources,
diagnostics,
options,
runCommand,
@@ -53,6 +55,7 @@ export const inspectPwndbgCore = async ({
}: {
readonly environment: Readonly<NodeJS.ProcessEnv>;
readonly rootPath: string;
readonly resources: ArtifactResourceScope;
readonly diagnostics: AnalysisCapturedOutput;
readonly options: ExecutionOptions | undefined;
readonly runCommand: PwntoolsCommand;
@@ -178,11 +181,14 @@ export const inspectPwndbgCore = async ({
replyPath,
PWNTOOLS_LIMITS.outputBytes,
options?.signal,
undefined,
resources,
);
reply = replySchema.parse(JSON.parse(raw.bytes.toString("utf8")));
} catch (cause: unknown) {
if (options?.signal?.aborted)
throw new AnalysisCancelledError(OPERATION, {
cause,
capturedOutput: recordedCrashStageOutput(diagnostics, output),
});
throw new AnalysisOutputError(
@@ -226,22 +232,22 @@ export const inspectPwndbgCore = async ({
return { ...reply.value, diagnostics: output };
} catch (cause: unknown) {
if (cause instanceof AnalysisError && cause.cleanupIncomplete) throw cause;
if (
const primary =
options?.signal?.aborted &&
(cause === options.signal.reason ||
(cause instanceof Error && cause.name === "AbortError"))
)
throw new AnalysisCancelledError(OPERATION, {
capturedOutput: recordedCrashStageOutput(diagnostics, output),
});
throw pwntoolsDecoderFailure(
cause,
"debugger",
gdb,
environment.REA_PWNTOOLS_PYTHON ?? "",
await readPwntoolsFailureEvidence(cause, stage),
failureContext,
);
? new AnalysisCancelledError(OPERATION, {
capturedOutput: recordedCrashStageOutput(diagnostics, output),
})
: pwntoolsDecoderFailure(
cause,
"debugger",
gdb,
environment.REA_PWNTOOLS_PYTHON ?? "",
await readPwntoolsFailureEvidence(cause, stage, resources),
failureContext,
);
throw primary;
}
};
+106 -19
View File
@@ -16,6 +16,8 @@ import type {
AnalysisPartialObservation,
} from "../../domain/analysisErrorBase.js";
import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
AnalysisCancelledError,
@@ -78,6 +80,7 @@ export interface PwntoolsDecoderProfile<
readonly payload: Payload;
readonly snapshot: { readonly bytes: Buffer; readonly sha256: string };
readonly rootPath: string;
readonly resources: ArtifactResourceScope;
readonly diagnostics: AnalysisCapturedOutput;
readonly options: ExecutionOptions | undefined;
readonly runCommand: PwntoolsCommand;
@@ -96,6 +99,7 @@ export class PwntoolsDecoder<
symbol,
"admitted" | "cancelled"
>();
readonly #resources = new ArtifactResourceScope();
#closing = false;
#closePromise: Promise<void> | undefined;
#pendingCleanup:
@@ -244,6 +248,8 @@ export class PwntoolsDecoder<
input.path,
PWNTOOLS_LIMITS.inputBytes,
options?.signal,
undefined,
this.#resources,
);
phase = "decoder";
root = await this.createRuntime();
@@ -298,11 +304,16 @@ export class PwntoolsDecoder<
replyPath,
PWNTOOLS_LIMITS.outputBytes,
options?.signal,
undefined,
this.#resources,
);
reply = replySchema.parse(JSON.parse(file.bytes.toString("utf8")));
} catch (cause: unknown) {
if (options?.signal?.aborted)
throw new AnalysisCancelledError(OPERATION, { capturedOutput });
throw new AnalysisCancelledError(OPERATION, {
cause,
capturedOutput,
});
throw new AnalysisOutputError(
OPERATION,
`Owned pwntools decoder reply failed for ${input.path}: ${cause instanceof z.ZodError ? cause.issues[0]?.message + " at " + (cause.issues[0]?.path.map(String).join(".") ?? "root") : cause instanceof Error ? cause.message : String(cause)}`,
@@ -369,6 +380,7 @@ export class PwntoolsDecoder<
payload: reply.value,
snapshot,
rootPath: root.path,
resources: this.#resources,
diagnostics: capturedOutput,
options,
runCommand: (spawn, classifyFailure) =>
@@ -385,12 +397,18 @@ export class PwntoolsDecoder<
}
return err(cause);
}
const evidence = await readPwntoolsFailureEvidence(cause, root?.path);
result = err(
const evidence = await readPwntoolsFailureEvidence(
cause,
root?.path,
this.#resources,
);
const primary =
options?.signal?.aborted &&
(cause === options.signal.reason ||
(cause instanceof Error && cause.name === "AbortError"))
? new AnalysisCancelledError(OPERATION)
(cause === options.signal.reason ||
(cause instanceof Error && cause.name === "AbortError") ||
(cause instanceof ArtifactReaderFailure &&
cause.cleanup !== undefined))
? new AnalysisCancelledError(OPERATION, { cause })
: pwntoolsDecoderFailure(
cause,
phase,
@@ -398,8 +416,8 @@ export class PwntoolsDecoder<
executablePath,
evidence,
context,
),
);
);
result = err(primary);
}
if (this.#pendingCleanup !== undefined) {
this.#pendingCleanup.failure = result.ok ? undefined : result.error;
@@ -483,7 +501,39 @@ export class PwntoolsDecoder<
this.#closing = true;
this.#closePromise ??= this.#tail
.then(async () => {
const failure = await this.#retire();
let failure: AnalysisError | undefined;
try {
failure = await this.#retire();
} catch (cause: unknown) {
failure = new ProviderCleanupError(
this.identity.id,
[this.#pendingCleanup?.root?.path ?? "pwntools decoder"],
{ reason: cause instanceof Error ? cause.message : String(cause) },
{ operation: this.profile.operation, cause },
);
}
try {
await this.#resources.close();
} catch (cause: unknown) {
const observation = ArtifactReaderFailure.cleanupObservation(
cause,
"pwntools artifact read",
);
const resourceFailure = new ProviderCleanupError(
this.identity.id,
observation.resources,
{ reason: observation.reason },
{ operation: this.profile.operation, cause },
);
failure =
failure === undefined
? resourceFailure
: analysisErrorWithCleanupFailure(
failure,
resourceFailure,
this.profile.operation,
);
}
if (failure !== undefined) throw failure;
})
.catch((cause: unknown) => {
@@ -502,8 +552,8 @@ export class PwntoolsDecoder<
}
async #completeCleanup(
retire: () => Promise<ProviderCleanupError | undefined>,
): Promise<ProviderCleanupError | undefined> {
retire: () => Promise<AnalysisError | undefined>,
): Promise<AnalysisError | undefined> {
const failure = await retire();
return failure !== undefined && this.#closing ? retire() : failure;
}
@@ -548,18 +598,46 @@ export class PwntoolsDecoder<
return undefined;
}
async #retire(): Promise<ProviderCleanupError | undefined> {
const failure = await this.#retireProcess();
if (failure !== undefined) return failure;
async #retire(): Promise<AnalysisError | undefined> {
let failure: AnalysisError | undefined;
try {
await this.#resources.retryCleanup();
} catch (cause: unknown) {
const observation = ArtifactReaderFailure.cleanupObservation(
cause,
"pwntools artifact read",
);
failure = new ProviderCleanupError(
this.identity.id,
observation.resources,
{ reason: observation.reason },
{
operation: this.profile.operation,
cause,
...(this.#pendingCleanup?.observation === undefined
? {}
: { partialObservation: this.#pendingCleanup.observation }),
},
);
}
const processFailure = await this.#retireProcess();
if (processFailure !== undefined) {
return failure === undefined
? processFailure
: analysisErrorWithCleanupFailure(
failure,
processFailure,
this.profile.operation,
);
}
const pending = this.#pendingCleanup;
if (pending === undefined) return undefined;
if (pending.root !== undefined) {
if (pending?.root !== undefined) {
const root = pending.root;
try {
await root.close();
pending.root = undefined;
} catch (cause: unknown) {
return new ProviderCleanupError(
const rootFailure = new ProviderCleanupError(
this.identity.id,
[root.path],
{
@@ -580,9 +658,18 @@ export class PwntoolsDecoder<
: { partialObservation: pending.observation }),
},
);
failure =
failure === undefined
? rootFailure
: analysisErrorWithCleanupFailure(
failure,
rootFailure,
this.profile.operation,
);
}
}
this.#pendingCleanup = undefined;
return undefined;
if (!this.#resources.hasPending && pending?.root === undefined)
this.#pendingCleanup = undefined;
return failure;
}
}
@@ -48,6 +48,7 @@ export class PwntoolsRecordedCrashProvider
payload,
snapshot,
rootPath,
resources,
diagnostics,
options,
runCommand,
@@ -120,6 +121,7 @@ export class PwntoolsRecordedCrashProvider
const context = await inspectPwndbgCore({
environment,
rootPath,
resources,
diagnostics,
options,
runCommand,
@@ -7,6 +7,7 @@ import {
} from "./PwntoolsRelease.js";
import { z } from "zod";
import { PWNTOOLS_LIMITS } from "./PwntoolsRelease.js";
import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
/** Actual limits reported by the owned bridge after lowering inherited soft limits. */
export const pwntoolsResourceLimitsSchema = z.strictObject({
@@ -42,6 +43,7 @@ export interface PwntoolsFailureEvidence {
export const readPwntoolsFailureEvidence = async (
cause: unknown,
rootPath?: string,
resources?: ArtifactResourceScope,
): Promise<PwntoolsFailureEvidence> => {
let limitReport: PwntoolsLimitReport | undefined;
let marker: PwntoolsFailureEvidence["marker"];
@@ -56,6 +58,9 @@ export const readPwntoolsFailureEvidence = async (
const reported = await readStableArtifact(
join(rootPath, "resource.failure"),
1,
undefined,
undefined,
resources,
);
const expected =
cause.snapshot.exitCode === PWNTOOLS_MEMORY_FAILURE_EXIT ? "M" : "F";
@@ -90,6 +95,9 @@ export const readPwntoolsFailureEvidence = async (
const reported = await readStableArtifact(
join(rootPath, "limits.json"),
4096,
undefined,
undefined,
resources,
);
limitReport = {
limits: pwntoolsResourceLimitsSchema.parse(
+20 -3
View File
@@ -9,6 +9,7 @@ import { wasmArtifactModule } from "../composition/wasm.js";
import { registerWasmTools } from "./registerWasmTools.js";
import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
import { createPeResourcesService } from "../composition/binaryDiagnostics.js";
import type { PeResourcesService } from "../application/binaryDiagnostics/PeResourcesService.js";
import { registerPeResourcesTool } from "./registerPeResourcesTool.js";
import type { EvmInterfaceService } from "../application/evm/EvmInterfaceService.js";
import { evmInterfaceModule } from "../composition/evm.js";
@@ -280,6 +281,10 @@ export const createServer = (
options.webSourceLocation ?? createWebSourceLocationService(environment);
const webModuleTrace =
options.webModuleTrace ?? createWebModuleTraceService(environment);
const goBinary = options.goBinary ?? createGoBinaryService();
const peResources = createPeResourcesService();
const webNetworkCapture =
options.webNetworkCapture ?? createWebNetworkCaptureService(environment);
const javascriptRecovery =
options.javascriptRecovery ?? createJavaScriptRecoveryProvider(environment);
const artifactResources = new ArtifactResourceScope();
@@ -345,6 +350,9 @@ export const createServer = (
recordedCrash.close(),
webSourceLocation.close(),
webModuleTrace.close(),
goBinary.close(),
peResources.close(),
webNetworkCapture.close(),
javascriptRecovery.close?.() ?? Promise.resolve(),
artifactResources.close(),
firmwareAnalysis.close(),
@@ -388,6 +396,9 @@ export const createServer = (
recordEvidenceWithUnknown,
withAdmittedAnalysis: analysisAdmission,
artifactResources,
goBinary,
peResources,
webNetworkCapture,
};
registerBinaryAnalysisTools(toolContext);
registerFridaTools(
@@ -517,6 +528,9 @@ const registerConfiguredAnalysisTools = (
evidenceById,
recordEvidence,
withAdmittedAnalysis,
goBinary,
peResources,
webNetworkCapture,
}: ServerToolContext,
android: AndroidAnalysisPort,
wasmArtifact: Pick<WasmArtifactService, "inspect" | "close">,
@@ -556,14 +570,14 @@ const registerConfiguredAnalysisTools = (
);
registerPeResourcesTool(
server,
createPeResourcesService(),
peResources,
toolLogger,
recordEvidence,
withAdmittedAnalysis,
);
registerGoTools(
server,
options.goBinary ?? createGoBinaryService(),
goBinary,
toolLogger,
recordEvidence,
withAdmittedAnalysis,
@@ -628,7 +642,7 @@ const registerConfiguredAnalysisTools = (
);
registerWebNetworkCaptureTool(
server,
options.webNetworkCapture ?? createWebNetworkCaptureService(environment),
webNetworkCapture,
toolLogger,
recordEvidence,
withAdmittedAnalysis,
@@ -673,6 +687,9 @@ const createSessionRecorders = (
});
interface ServerToolContext extends ReturnType<typeof createSessionRecorders> {
readonly goBinary: GoBinaryService;
readonly peResources: PeResourcesService;
readonly webNetworkCapture: WebNetworkCaptureService;
readonly artifactResources: ArtifactResourceScope;
readonly server: EvidenceMcpServer;
readonly session: BinarySessionPort | undefined;
+196 -45
View File
@@ -1,6 +1,6 @@
import { access, chmod, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { expect, it } from "vitest";
import { expect, it, vi } from "vitest";
import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js";
import { WabtArtifactProvider } from "./WabtArtifactProvider.js";
import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
@@ -9,6 +9,33 @@ import { spawnOwnedProviderProcess } from "../process/ProviderProcess.js";
import { OwnedCommandFailure } from "../process/OwnedCommand.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
const fileCloseFailure = vi.hoisted(() => ({
selectedPath: "",
attempts: 0,
failFirst: false,
}));
vi.mock("node:fs/promises", async (importOriginal) => {
const fs = await importOriginal<typeof import("node:fs/promises")>();
return {
...fs,
open: async (...args: Parameters<typeof fs.open>) => {
const handle = await fs.open(...args);
if (String(args[0]) !== fileCloseFailure.selectedPath) return handle;
const close = handle.close.bind(handle);
handle.close = async () => {
fileCloseFailure.attempts += 1;
if (fileCloseFailure.failFirst) {
fileCloseFailure.failFirst = false;
throw new Error("injected WABT input close failure");
}
return close();
};
return handle;
},
};
});
const failureTags: Readonly<Record<string, string>> = {
invalid: "AnalysisInputError",
timeout: "AnalysisTimeoutError",
@@ -20,6 +47,82 @@ const failureTags: Readonly<Record<string, string>> = {
"wat-warning": "AnalysisOutputError",
};
const assertCleanupRecovery = async (options: {
readonly provider: WabtArtifactProvider;
readonly result: Awaited<ReturnType<WabtArtifactProvider["inspect"]>>;
readonly path: string;
readonly runtimePath: string;
readonly cleanupAttempts: () => number;
readonly runtimeCreations: () => number;
}): Promise<void> => {
expect(options.result).toMatchObject({
error: {
cleanupIncomplete: true,
cleanupResources: [options.runtimePath],
partialObservation: { normalized_result: { validation: "valid" } },
},
});
await expect(access(options.runtimePath)).resolves.toBeUndefined();
const blocked = await options.provider.inspect({
path: options.path,
glue_paths: [],
candidate_paths: [],
});
expect(blocked).toMatchObject({
ok: false,
error: {
cleanupIncomplete: true,
cleanupResources: [options.runtimePath],
},
});
expect(options.cleanupAttempts()).toBe(2);
expect(options.runtimeCreations()).toBe(1);
await options.provider.close();
expect(options.cleanupAttempts()).toBe(3);
await expect(access(options.runtimePath)).rejects.toMatchObject({
code: "ENOENT",
});
};
const assertModeOutcome = (
mode: string,
result: Awaited<ReturnType<WabtArtifactProvider["inspect"]>>,
path: string,
): void => {
if (mode === "success")
expect(result).toMatchObject({
ok: true,
value: {
result: {
artifact: { path, bytes: 76 },
validation: "valid",
runtime_execution: "not-performed",
},
},
});
else
expect(result).toMatchObject({
ok: false,
error: { _tag: failureTags[mode] },
});
if (mode === "invalid")
expect(result).toMatchObject({
error: { capturedOutput: { stderr: "module.wasm: invalid bytes\n" } },
});
if (mode === "malformed-wat" || mode === "wat-warning")
expect(result).toMatchObject({
error: {
capturedOutput: {
stdout:
mode === "malformed-wat"
? "unexpected decoder output\n"
: '(module (@custom "test" "payload"))\n',
stderr: mode === "wat-warning" ? "decoder warning\n" : "",
},
},
});
};
it("returns actionable unavailable without creating a workspace when tools are absent", async () => {
const provider = new WabtArtifactProvider({}, undefined, () => {
throw new Error("Must not allocate");
@@ -39,6 +142,88 @@ it("returns actionable unavailable without creating a workspace when tools are a
});
});
it("retries a retained input descriptor before admitting the next WABT operation", async () => {
const root = await createTestTempDirectory("rea-wabt-read-cleanup-");
const path = join(root, "selected.wasm");
await writeFile(path, Buffer.alloc(76, 1));
for (const tool of ["wasm-validate", "wasm-objdump", "wasm2wat"])
await writeFile(join(root, tool), "source-owned executable seam", {
mode: 0o700,
});
const dump = await readFile(
new URL("../../tests/fixtures/wasm/objdump.txt", import.meta.url),
"utf8",
);
const provider = new WabtArtifactProvider(
{ REA_WABT_BIN_DIRECTORY: root },
async (input) => {
const version = input.arguments[0] === "--version";
const stdout = version
? "1.0.42\n"
: input.command.includes("wasm-objdump")
? dump
: input.command.includes("wasm2wat")
? '(module (@custom "test" "payload"))\n'
: "";
const launched = await spawnOwnedProviderProcess({
...input,
command: process.execPath,
arguments: [
"-e",
`process.stdout.write(${JSON.stringify(stdout)}); process.exit(0);`,
],
expectedCommand: null,
});
return launched;
},
);
fileCloseFailure.selectedPath = path;
fileCloseFailure.attempts = 0;
fileCloseFailure.failFirst = true;
try {
const first = await provider.inspect({
path,
candidate_paths: [],
glue_paths: [],
});
expect(first).toMatchObject({
ok: false,
error: {
cleanupIncomplete: true,
cleanupResources: [path],
cause: { message: "injected WABT input close failure" },
},
});
expect(fileCloseFailure.attempts).toBe(1);
const retried = await provider.inspect({
path,
candidate_paths: [],
glue_paths: [],
});
expect(retried.ok).toBe(true);
expect(fileCloseFailure.attempts).toBeGreaterThan(1);
fileCloseFailure.failFirst = true;
const closeRetry = await provider.inspect({
path,
candidate_paths: [],
glue_paths: [],
});
expect(closeRetry).toMatchObject({
ok: false,
error: { cleanupIncomplete: true, cleanupResources: [path] },
});
const beforeClose = fileCloseFailure.attempts;
await provider.close();
expect(fileCloseFailure.attempts).toBeGreaterThan(beforeClose);
} finally {
fileCloseFailure.selectedPath = "";
fileCloseFailure.failFirst = false;
await provider.close();
}
});
it.each([false, true])(
"reports an unavailable private runtime root with retryable=%s without a misleading WABT remediation",
async (retryable) => {
@@ -110,6 +295,7 @@ it.each([
"utf8",
);
let runtimePath = "";
let runtimeCreations = 0;
let acquiredPid: number | undefined;
let cleanupAttempts = 0;
const controller = new AbortController();
@@ -168,6 +354,7 @@ it.each([
return launched;
},
async () => {
runtimeCreations += 1;
const root = await PrivateRuntimeRoot.create({
prefix: "rea-wabt-owned-test-",
});
@@ -186,53 +373,17 @@ it.each([
{ path, glue_paths: [], candidate_paths: [] },
{ signal: controller.signal },
);
if (mode === "success")
expect(result).toMatchObject({
ok: true,
value: {
result: {
artifact: { path, bytes: 76 },
validation: "valid",
runtime_execution: "not-performed",
},
},
});
else
expect(result).toMatchObject({
ok: false,
error: { _tag: failureTags[mode] },
});
if (mode === "invalid")
expect(result).toMatchObject({
error: { capturedOutput: { stderr: "module.wasm: invalid bytes\n" } },
});
assertModeOutcome(mode, result, path);
if (mode === "cleanup") {
expect(result).toMatchObject({
error: {
cleanupIncomplete: true,
cleanupResources: [runtimePath],
partialObservation: { normalized_result: { validation: "valid" } },
},
await assertCleanupRecovery({
provider,
result,
path,
runtimePath,
cleanupAttempts: () => cleanupAttempts,
runtimeCreations: () => runtimeCreations,
});
await expect(access(runtimePath)).resolves.toBeUndefined();
await expect(provider.close()).rejects.toMatchObject({
cleanupIncomplete: true,
});
await expect(access(runtimePath)).resolves.toBeUndefined();
await provider.close();
}
if (mode === "malformed-wat" || mode === "wat-warning")
expect(result).toMatchObject({
error: {
capturedOutput: {
stdout:
mode === "malformed-wat"
? "unexpected decoder output\n"
: '(module (@custom "test" "payload"))\n',
stderr: mode === "wat-warning" ? "decoder warning\n" : "",
},
},
});
await expect(access(runtimePath)).rejects.toMatchObject({ code: "ENOENT" });
expect(await readFile(path)).toEqual(bytes);
if (acquiredPid !== undefined) {
+68 -26
View File
@@ -9,6 +9,8 @@ import type {
WasmArtifactPort,
} from "../application/wasm/WasmArtifactPort.js";
import { readStableArtifact } from "../artifacts/readStableArtifact.js";
import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import type {
AnalysisError,
AnalysisCapturedOutput,
@@ -16,6 +18,7 @@ import type {
import {
AnalysisCancelledError,
AnalysisArtifactChangedError,
AnalysisCapabilityUnavailableError,
AnalysisInputError,
AnalysisOutputError,
} from "../domain/analysisErrorCore.js";
@@ -41,9 +44,7 @@ const digest = (text: string) =>
createHash("sha256").update(text).digest("hex");
/** Run caller-supplied WABT against private copies of exactly selected bytes. */
export class WabtArtifactProvider implements WasmArtifactPort {
readonly #pendingRoots = new Set<
Pick<PrivateRuntimeRoot, "path" | "close">
>();
readonly #resources = new ArtifactResourceScope();
constructor(
readonly environment: Readonly<NodeJS.ProcessEnv> = process.env,
readonly launcher?: Launcher,
@@ -53,29 +54,51 @@ export class WabtArtifactProvider implements WasmArtifactPort {
) {}
/** Retry retained cleanup without discarding roots that still cannot be removed. */
async close(): Promise<void> {
const failures: { path: string; reason: string }[] = [];
for (const root of this.#pendingRoots) {
try {
await root.close();
this.#pendingRoots.delete(root);
} catch (cause: unknown) {
failures.push({
path: root.path,
reason: cause instanceof Error ? cause.message : String(cause),
});
}
}
if (failures.length > 0)
try {
await this.#resources.close();
} catch (cause: unknown) {
const cleanup =
cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined;
throw new ProviderCleanupError(
WABT_PROVIDER_IDENTITY.id,
failures.map(({ path }) => path),
{ failures },
{ operation: OPERATION },
cleanup?.resources ?? ["artifact-resources"],
{
reason:
cleanup?.reason ??
(cause instanceof Error ? cause.message : String(cause)),
},
{ operation: OPERATION, cause },
);
}
}
async inspect(
input: InspectWasmArtifactInput,
options?: ExecutionOptions,
): Promise<Result<WasmArtifactExecution, AnalysisError>> {
try {
return await this.#resources.run(() => this.#inspect(input, options));
} catch (cause: unknown) {
if (
cause instanceof ArtifactReaderFailure &&
cause.reason === "unavailable" &&
cause.cleanup === undefined
)
return err(this.#closedError());
return err(wabtFailure(cause, "artifact", input.path));
}
}
#closedError(): AnalysisCapabilityUnavailableError {
return new AnalysisCapabilityUnavailableError(
WABT_PROVIDER_IDENTITY.id,
OPERATION,
"Provider is closing",
);
}
async #inspect(
input: InspectWasmArtifactInput,
options?: ExecutionOptions,
): Promise<Result<WasmArtifactExecution, AnalysisError>> {
let root: Pick<PrivateRuntimeRoot, "path" | "close"> | undefined;
let phase: "configuration" | "artifact" | "producer" = "configuration";
@@ -83,7 +106,6 @@ export class WabtArtifactProvider implements WasmArtifactPort {
let capturedOutput: AnalysisCapturedOutput | undefined;
try {
if (options?.signal?.aborted) throw new AnalysisCancelledError(OPERATION);
await this.close();
const directory = this.environment.REA_WABT_BIN_DIRECTORY ?? "";
if (!isAbsolute(directory))
throw new Error(
@@ -108,6 +130,8 @@ export class WabtArtifactProvider implements WasmArtifactPort {
path,
WABT_LIMITS.toolBytes,
options?.signal,
undefined,
this.#resources,
);
commands.push({
tool,
@@ -130,17 +154,24 @@ export class WabtArtifactProvider implements WasmArtifactPort {
snapshotPath,
WABT_LIMITS.inputBytes,
options?.signal,
undefined,
this.#resources,
);
if (bytes.sha256 !== snapshotHash)
throw new Error("Private WASM snapshot bytes changed.");
} catch (cause: unknown) {
const cleanup =
cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined;
if (options?.signal?.aborted)
throw new AnalysisCancelledError(OPERATION);
throw new AnalysisCancelledError(OPERATION, {
cause,
...(cleanup === undefined ? {} : { cleanup }),
});
throw new AnalysisArtifactChangedError(
OPERATION,
input.path,
"Private WASM snapshot no longer matches selected byte identity.",
{ cause },
{ cause, ...(cleanup === undefined ? {} : { cleanup }) },
);
}
};
@@ -175,6 +206,8 @@ export class WabtArtifactProvider implements WasmArtifactPort {
command.path,
WABT_LIMITS.toolBytes,
options?.signal,
undefined,
this.#resources,
);
if (current.sha256 !== command.sha256)
throw new AnalysisOutputError(
@@ -200,6 +233,8 @@ export class WabtArtifactProvider implements WasmArtifactPort {
input.path,
WABT_LIMITS.inputBytes,
options?.signal,
undefined,
this.#resources,
);
const artifact = {
path: input.path,
@@ -215,6 +250,8 @@ export class WabtArtifactProvider implements WasmArtifactPort {
path,
WABT_LIMITS.inputBytes,
options?.signal,
undefined,
this.#resources,
);
candidates.push({
path,
@@ -228,6 +265,8 @@ export class WabtArtifactProvider implements WasmArtifactPort {
path,
WABT_LIMITS.inputBytes,
options?.signal,
undefined,
this.#resources,
);
const source = new TextDecoder("utf-8", { fatal: true }).decode(
bytes.bytes,
@@ -395,10 +434,13 @@ export class WabtArtifactProvider implements WasmArtifactPort {
);
}
if (root !== undefined) {
try {
await root.close();
} catch (cause: unknown) {
this.#pendingRoots.add(root);
const cleanup = await this.#resources.release({
kind: "private-runtime-root",
resource: root.path,
root,
});
if (cleanup.kind === "failed") {
const cause = cleanup.cause;
const partialObservation = result.ok
? createEvidence(
result.value.subject ?? undefined,
+20 -7
View File
@@ -20,12 +20,19 @@ export const wabtFailure = (
path: string,
): AnalysisError => {
if (cause instanceof AnalysisError) return cause;
const artifactCleanup =
cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined;
const cleanupOptions =
artifactCleanup === undefined ? {} : { cleanup: artifactCleanup };
const reason = cause instanceof Error ? cause.message : String(cause);
if (
(cause instanceof ArtifactReaderFailure && cause.reason === "cancelled") ||
(cause instanceof Error && cause.name === "AbortError")
)
return new AnalysisCancelledError("inspect_wasm_artifact", { cause });
return new AnalysisCancelledError("inspect_wasm_artifact", {
cause,
...cleanupOptions,
});
if (cause instanceof OwnedCommandFailure) {
const capturedOutput =
cause.snapshot === null
@@ -85,6 +92,7 @@ export const wabtFailure = (
reason,
{
cause,
...cleanupOptions,
userMessage: `${reason} Supply WABT 1.0.42 via absolute REA_WABT_BIN_DIRECTORY; REA does not install tools.`,
},
);
@@ -97,7 +105,7 @@ export const wabtFailure = (
"inspect_wasm_artifact",
path,
reason,
{ cause },
{ cause, ...cleanupOptions },
);
if (
phase === "artifact" &&
@@ -109,11 +117,16 @@ export const wabtFailure = (
"inspect_wasm_artifact",
path,
cause.code,
{ cause },
{ cause, ...cleanupOptions },
);
if (phase === "artifact")
return new AnalysisInputError("inspect_wasm_artifact", { cause }, [
{ path: ["path"], reason: "invalid_value", message: reason },
]);
return new AnalysisOutputError("inspect_wasm_artifact", reason, { cause });
return new AnalysisInputError(
"inspect_wasm_artifact",
{ cause, ...cleanupOptions },
[{ path: ["path"], reason: "invalid_value", message: reason }],
);
return new AnalysisOutputError("inspect_wasm_artifact", reason, {
cause,
...cleanupOptions,
});
};