refactor(javascript): bind JavaScript source analysis in composition (#11467)

This commit is contained in:
morluto authored and GitHub committed 2026-11-16 05:16:56 +08:00
1 parent 24406aa018
commit 64e6caeca2
22 files changed
+102 -34

No files matched your search

@@ -1,10 +1,13 @@
import { analyzeJavaScriptApplication } from "../../dist/application/javascript/JavaScriptApplicationService.js";
import { javascriptSourceAnalysis } from "../../dist/composition/javascriptSourceAnalysis.js";
import { withVerifierArtifactScope } from "./verifier-artifact-scope.mjs";
/** Analyze one JavaScript application and close its caller-owned resources. */
export const analyzeJavaScriptApplicationWithOwnedScope = (input) =>
withVerifierArtifactScope(async (scope) => {
const result = await analyzeJavaScriptApplication(input, scope);
const result = await analyzeJavaScriptApplication(input, scope, {
sourceAnalysis: javascriptSourceAnalysis,
});
if (!result.ok) throw result.error;
return result.value;
});
+1 -2
View File
@@ -21,7 +21,6 @@
"android -> native": 1,
"apktool -> artifacts": 2,
"artifacts -> dotnet": 3,
"artifacts -> javascript": 1,
"artifacts -> native": 1,
"browser -> artifacts": 6,
"captures -> pcap": 2,
@@ -35,7 +34,7 @@
"native -> artifacts": 5
},
"entry": {
"application -> artifacts": 9,
"application -> artifacts": 7,
"application -> browser": 2,
"application -> desktop": 41,
"application -> frida": 2,
+1
View File
@@ -324,6 +324,7 @@ export const ENTRY_FILES = Object.freeze(
javascript: [
"analysis/JavaScriptAnalysisTransfer.ts",
"analysis/JavaScriptAnalysisWorkerServer.ts",
"analysis/JavaScriptSourceAnalysis.ts",
"recovery/WakaruCommand.ts",
"recovery/WakaruProvider.ts",
"recovery/WakaruProviderIdentity.ts",
@@ -29,6 +29,7 @@ import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.
import { err, ok, type Result } from "../../domain/result.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import type { ExecutionOptions } from "../../ports/AnalysisProvider.js";
import type { JavaScriptSourceAnalysisFactory } from "../../ports/javascript/JavaScriptSourceAnalysisFactory.js";
import { createOwnedJavaScriptApplicationEvidenceCooperatively } from "./JavaScriptApplicationEvidence.js";
import {
assertJavaScriptAnalysisActive,
@@ -45,6 +46,8 @@ const OPERATION = "analyze_javascript_application" as const;
/** Execution options plus the composition root's environment for admission settings. */
export interface JavaScriptApplicationOptions extends ExecutionOptions {
/** Composition-bound source analyzer; application never constructs one. */
readonly sourceAnalysis: JavaScriptSourceAnalysisFactory;
readonly settings?: AnalysisSettingsReader;
readonly environment?: Readonly<Record<string, string | undefined>>;
}
@@ -53,7 +56,7 @@ export interface JavaScriptApplicationOptions extends ExecutionOptions {
export const analyzeJavaScriptApplication = async (
rawInput: unknown,
scope: ArtifactResourceScope,
options: JavaScriptApplicationOptions = {},
options: JavaScriptApplicationOptions,
): Promise<Result<Evidence, AnalysisError>> => {
const parsed = analyzeJavaScriptApplicationInputSchema.safeParse(rawInput);
if (!parsed.success)
@@ -67,7 +70,7 @@ export const analyzeJavaScriptApplication = async (
export const analyzeJavaScriptApplicationValidated = async (
input: z.output<typeof analyzeJavaScriptApplicationInputSchema>,
scope: ArtifactResourceScope,
options: JavaScriptApplicationOptions = {},
options: JavaScriptApplicationOptions,
): Promise<Result<Evidence, AnalysisError>> => {
// An invalid setting is refused before analysis, never replaced by the default.
const asarHeaderAdmission = parseAsarHeaderAdmission(
@@ -110,6 +113,7 @@ export const analyzeJavaScriptApplicationValidated = async (
reconstructed = await reconstructJavaScriptArtifact(
input,
scope,
options.sourceAnalysis,
options.signal,
options.progress,
acceptedAdmission,
@@ -44,7 +44,7 @@ import {
isSkippedJavaScriptAnalysis,
javascriptArtifactAnalysisScopes,
} from "./JavaScriptArtifactAnalysisTypes.js";
import { createJavaScriptSourceAnalysis } from "../../artifacts/javascript/JavaScriptSourceAnalysis.js";
import type { JavaScriptSourceAnalysisFactory } from "../../ports/javascript/JavaScriptSourceAnalysisFactory.js";
import { JAVASCRIPT_ANALYSIS_RESOURCE_DEFAULTS } from "../../domain/javascript/javascriptAnalysisResourceControls.js";
import { createOwnedJavaScriptApplicationEvidenceCooperatively } from "./JavaScriptApplicationEvidence.js";
import { readJavaScriptArtifactFiles } from "../../artifacts/javascript/JavaScriptArtifactFiles.js";
@@ -90,6 +90,7 @@ export interface JavaScriptArtifactReconstructionResult {
export const reconstructJavaScriptArtifact = async (
input: AnalyzeJavaScriptApplicationInput,
scope: ArtifactResourceScope,
sourceAnalysis: JavaScriptSourceAnalysisFactory,
signal?: AbortSignal,
progress?: ProgressReporter,
asarHeaderAdmission: AsarHeaderAdmission = DEFAULT_ASAR_HEADER_ADMISSION,
@@ -212,9 +213,10 @@ export const reconstructJavaScriptArtifact = async (
files,
sourceLimits,
scope,
sourceAnalysis,
signal,
);
const worker = await createJavaScriptSourceAnalysis(
const worker = await sourceAnalysis(
sourceLimits,
files.files.filter(
(file) => file.kind === "javascript" && file.text.included,
@@ -10,7 +10,7 @@ import { translateArtifactFailure } from "../../artifacts/ArtifactOperationFailu
import type { JavaScriptArtifactFileSet } from "../../domain/javascript/javascriptArtifactFiles.js";
import type { JavaScriptSourceAnalysisLimits } from "../../domain/javascript/javascriptSourceAnalysis.js";
import type { ArtifactResourceScope } from "../../resources/index.js";
import { createJavaScriptSourceAnalysis } from "../../artifacts/javascript/JavaScriptSourceAnalysis.js";
import type { JavaScriptSourceAnalysisFactory } from "../../ports/javascript/JavaScriptSourceAnalysisFactory.js";
import { createJavaScriptPackageTypeLookup } from "./JavaScriptArtifactAnalysis.js";
import { JavaScriptJsonDocuments } from "./JavaScriptJsonDocuments.js";
import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
@@ -29,6 +29,7 @@ export const discoverJavaScriptPreloadPaths = async (
fileSet: JavaScriptArtifactFileSet,
limits: JavaScriptSourceAnalysisLimits,
scope: ArtifactResourceScope,
sourceAnalysis: JavaScriptSourceAnalysisFactory,
signal?: AbortSignal,
): Promise<JavaScriptPreloadDiscovery> => {
const paths = new Set<string>();
@@ -52,7 +53,7 @@ export const discoverJavaScriptPreloadPaths = async (
(file) => file.kind === "javascript" && file.text.included,
);
const files = new Map(fileSet.files.map((file) => [file.path, file]));
const worker = await createJavaScriptSourceAnalysis(limits, sources.length, {
const worker = await sourceAnalysis(limits, sources.length, {
scope,
});
let outcome: { kind: "completed" } | { kind: "failed"; cause: unknown } = {
+6 -2
View File
@@ -116,8 +116,11 @@ export const runCliJavaScriptApplicationAnalysis = async (
},
host: CliJavaScriptAnalysisHost = processJavaScriptAnalysis,
): Promise<JsonValue> => {
const { analyzeJavaScriptApplication } =
await import("../application/javascript/JavaScriptApplicationService.js");
const [{ analyzeJavaScriptApplication }, { javascriptSourceAnalysis }] =
await Promise.all([
import("../application/javascript/JavaScriptApplicationService.js"),
import("../composition/javascriptSourceAnalysis.js"),
]);
const progress = createProgressReporter(
async (update) => {
writeCliProgressLine(update);
@@ -126,6 +129,7 @@ export const runCliJavaScriptApplicationAnalysis = async (
);
const resources = host.scope();
const result = await analyzeJavaScriptApplication(input, resources, {
sourceAnalysis: javascriptSourceAnalysis,
environment,
progress,
...(signal === undefined ? {} : { signal }),
@@ -0,0 +1,6 @@
import { createJavaScriptSourceAnalysis } from "../javascript/analysis/JavaScriptSourceAnalysis.js";
import type { JavaScriptSourceAnalysisFactory } from "../ports/javascript/JavaScriptSourceAnalysisFactory.js";
/** Bind JavaScript artifact analysis to the provider's isolated worker. */
export const javascriptSourceAnalysis: JavaScriptSourceAnalysisFactory =
createJavaScriptSourceAnalysis;
@@ -30,7 +30,7 @@ afterEach(() => {
cleanup.denied = false;
cleanup.onRemoval = undefined;
});
import { createJavaScriptSourceAnalysis } from "../../artifacts/javascript/JavaScriptSourceAnalysis.js";
import { createJavaScriptSourceAnalysis } from "./JavaScriptSourceAnalysis.js";
import { spawnOwnedProviderProcess } from "../../process/ProviderProcess.js";
import type { JavaScriptArtifactFile } from "../../domain/javascript/javascriptArtifactFiles.js";
@@ -4,7 +4,7 @@ import type {
JavaScriptSourceAnalysisLimits,
JavaScriptSourceAnalysisPort,
} from "../../domain/javascript/javascriptSourceAnalysis.js";
import { JavaScriptAnalysisWorker } from "../../javascript/analysis/JavaScriptAnalysisWorker.js";
import { JavaScriptAnalysisWorker } from "./JavaScriptAnalysisWorker.js";
import type { spawnOwnedProviderProcess } from "../../process/ProviderProcess.js";
import { WorkerCleanupRegistry } from "../../process/OwnedWorkerRuntime.js";
import { ArtifactResourceScope } from "../../resources/index.js";
@@ -0,0 +1,17 @@
import type {
JavaScriptSourceAnalysisLimits,
JavaScriptSourceAnalysisPort,
} from "../../domain/javascript/javascriptSourceAnalysis.js";
import type { ArtifactResourceScope } from "../../resources/index.js";
/**
* Acquire a bounded JavaScript source analyzer for one artifact analysis.
* Composition binds the provider's worker; application never constructs it.
* The analyzer is inert until its first source and may reuse a healthy worker
* parked on `scope`, which owns that worker until the scope closes.
*/
export type JavaScriptSourceAnalysisFactory = (
limits: JavaScriptSourceAnalysisLimits,
sourceCount: number,
acquisition: { readonly scope: ArtifactResourceScope },
) => Promise<JavaScriptSourceAnalysisPort>;
+2
View File
@@ -15,6 +15,7 @@ import {
listElectronTargets,
} from "../application/javascript/ElectronObservationService.js";
import { analyzeJavaScriptApplicationValidated } from "../application/javascript/JavaScriptApplicationService.js";
import { javascriptSourceAnalysis } from "../composition/javascriptSourceAnalysis.js";
import type { ArtifactResourceScope } from "../resources/index.js";
import { reconcileJavaScriptRuntimeEvidence } from "../application/javascript/JavaScriptRuntimeReconciliationService.js";
import { recordEvidenceSources } from "../application/investigation/recordEvidenceSources.js";
@@ -112,6 +113,7 @@ export const registerElectronTools = (
request,
options.artifactResources,
{
sourceAnalysis: javascriptSourceAnalysis,
signal,
progress,
environment: options.environment,
@@ -17,7 +17,7 @@ import {
readJavaScriptArtifactFiles,
} from "../../../support/javascriptApplicationScope.js";
import { createJavaScriptArtifactReader } from "../../../../src/artifacts/javascript/JavaScriptArtifactReader.js";
import { createJavaScriptSourceAnalysis } from "../../../../src/artifacts/javascript/JavaScriptSourceAnalysis.js";
import { createJavaScriptSourceAnalysis } from "../../../../src/javascript/analysis/JavaScriptSourceAnalysis.js";
import { analyzeAndAdoptJavaScriptArtifactFiles } from "../../../../src/application/javascript/JavaScriptArtifactAnalysis.js";
import { createJavaScriptSemanticGraphProjection } from "../../../../src/application/javascript/JavaScriptSemanticGraphBuilder.js";
import { immutableArtifactGraph } from "../../../fixtures/javascriptArtifactGraph.js";
@@ -37,7 +37,7 @@ import {
} from "../../../../src/javascript/analysis/JavaScriptAnalysisTransfer.js";
import { javaScriptWorkerStaticAnalysisSchema } from "../../../../src/javascript/analysis/JavaScriptAnalysisWorkerSchemas.js";
import { createJavaScriptArtifactReader } from "../../../../src/artifacts/javascript/JavaScriptArtifactReader.js";
import { createJavaScriptSourceAnalysis } from "../../../../src/artifacts/javascript/JavaScriptSourceAnalysis.js";
import { createJavaScriptSourceAnalysis } from "../../../../src/javascript/analysis/JavaScriptSourceAnalysis.js";
import {
scanCanonicalArtifactInventory,
withArtifactResourceScope,
@@ -1,5 +1,6 @@
import { mkdir, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { javascriptSourceAnalysis } from "../../../src/composition/javascriptSourceAnalysis.js";
import { createPackage } from "@electron/asar";
import { expect, it, onTestFinished, vi } from "vitest";
@@ -44,9 +45,11 @@ it("retains a failed nested reader through blocked work and scope cleanup", asyn
const input = analyzeJavaScriptApplicationInputSchema.parse({
input_path: bundle,
});
const firstFailure = await reconstructJavaScriptArtifact(input, scope).catch(
(cause: unknown) => cause,
);
const firstFailure = await reconstructJavaScriptArtifact(
input,
scope,
javascriptSourceAnalysis,
).catch((cause: unknown) => cause);
expect(firstFailure).toBeInstanceOf(ArtifactReaderFailure);
expect(firstFailure).toMatchObject({
cleanup: {
@@ -59,9 +62,11 @@ it("retains a failed nested reader through blocked work and scope cleanup", asyn
expect(retainedReader).toBeDefined();
expect(retainedReader).not.toBe(closedReaders[0]);
const blockedWork = await reconstructJavaScriptArtifact(input, scope).catch(
(cause: unknown) => cause,
);
const blockedWork = await reconstructJavaScriptArtifact(
input,
scope,
javascriptSourceAnalysis,
).catch((cause: unknown) => cause);
expect(blockedWork).toMatchObject({
reason: "unavailable",
cleanup: {
@@ -1,5 +1,6 @@
import { setImmediate } from "node:timers";
import { mkdir, open, realpath, symlink, writeFile } from "node:fs/promises";
import { javascriptSourceAnalysis } from "../../../src/composition/javascriptSourceAnalysis.js";
import { basename, join } from "node:path";
import { expect, it, onTestFinished, vi } from "vitest";
import { z } from "zod";
@@ -57,6 +58,7 @@ it.each(["worker-phase", "final-cleanup", "no-cancellation"] as const)(
{ input_path: root, format: "directory" },
scope,
{
sourceAnalysis: javascriptSourceAnalysis,
signal: controller.signal,
progress: {
async report(event) {
@@ -130,6 +132,7 @@ it("retains worker cleanup when progress reporting fails during analysis", async
{ input_path: root, format: "directory" },
scope,
{
sourceAnalysis: javascriptSourceAnalysis,
progress: {
async report(event) {
if (
@@ -185,7 +188,10 @@ it.each(["during cleanup", "on the next control turn"] as const)(
const result = await analyzeOwnedApplication(
{ input_path: selected, format: "directory" },
scope,
{ signal: controller.signal },
{
sourceAnalysis: javascriptSourceAnalysis,
signal: controller.signal,
},
);
if (result.ok) throw new Error("Cancelled handoff must not succeed");
expect(result.error.cause).toBe(reason);
@@ -598,6 +604,7 @@ it("keeps the exact retained descriptor owner through application failure transl
const result = await analyzeOwnedApplication(
{ input_path: root, format: "directory" },
scope,
{ sourceAnalysis: javascriptSourceAnalysis },
);
if (result.ok) throw new Error("Expected retained cleanup to block analysis");
expect(result.error.cleanupIncomplete).toBe(true);
@@ -12,13 +12,7 @@ import { analyzeParsedJavaScriptStaticSource } from "../../fixtures/javascriptSt
import { parseJavaScriptSource } from "../../../src/domain/javascript/javascriptSourceParser.js";
import { ok, err } from "../../../src/domain/result.js";
import { discoverJavaScriptPreloadPaths } from "../../../src/application/javascript/JavaScriptPreloadDiscovery.js";
const acquire = vi.hoisted(() => vi.fn());
vi.mock(
"../../../src/artifacts/javascript/JavaScriptSourceAnalysis.js",
() => ({
createJavaScriptSourceAnalysis: acquire,
}),
);
const acquire = vi.fn();
const file = (
path: string,
text: string,
@@ -82,6 +76,7 @@ it("resolves an exact preload before its declaring source regardless of inventor
fixture(),
limits,
new ArtifactResourceScope(),
acquire,
);
expect(result).toEqual({
paths: new Set(["a".repeat(64) + ":preload.js"]),
@@ -113,6 +108,7 @@ it("keeps discovering after one source exceeds its worker limit", async () => {
{ ...files, files: [file("big.js", ""), ...files.files] },
limits,
new ArtifactResourceScope(),
acquire,
);
// The gap stays reported even if source analysis later reads big.js.
expect(result).toEqual({
@@ -141,6 +137,7 @@ it("does not turn an invalid ESM require declaration into a preload identity", a
{ ...files, files: [...files.files.slice(0, 2), source] },
limits,
new ArtifactResourceScope(),
acquire,
)
).paths,
).toEqual(new Set());
@@ -160,6 +157,7 @@ it("does not transfer preload identity across containers", async () => {
},
limits,
new ArtifactResourceScope(),
acquire,
)
).paths,
).toEqual(new Set());
@@ -176,6 +174,7 @@ it("skips discovery when package scope cannot change a .js loader", async () =>
},
limits,
new ArtifactResourceScope(),
acquire,
);
expect(acquire).not.toHaveBeenCalled();
});
@@ -193,7 +192,13 @@ it("retains a failed close and the original cancellation until scope cleanup ret
acquire.mockResolvedValue({ analyze: failingAnalyze, close });
const scope = new ArtifactResourceScope();
await expect(
discoverJavaScriptPreloadPaths(fixture(), limits, scope, controller.signal),
discoverJavaScriptPreloadPaths(
fixture(),
limits,
scope,
acquire,
controller.signal,
),
).rejects.toMatchObject({
cleanupIncomplete: true,
cause: expect.objectContaining({
@@ -7,7 +7,7 @@ import { expect, it } from "vitest";
import { withVerifierCleanup } from "../../../scripts/lib/verifier-cleanup.mjs";
import { phaseGate } from "../../support/lifecycleHarness.js";
import { JavaScriptAnalysisWorker } from "../../../src/javascript/analysis/JavaScriptAnalysisWorker.js";
import { createJavaScriptSourceAnalysis } from "../../../src/artifacts/javascript/JavaScriptSourceAnalysis.js";
import { createJavaScriptSourceAnalysis } from "../../../src/javascript/analysis/JavaScriptSourceAnalysis.js";
import { ArtifactResourceScope } from "../../../src/resources/ArtifactResourceScope.js";
import { cleanupOwnedProcessGroup } from "../../../src/process/ProcessOwnership.js";
import { ProcessOwnershipEvidenceOwner } from "../../../src/process/ProcessOwnershipEvidence.js";
@@ -1,5 +1,6 @@
import { writeFile } from "node:fs/promises";
import { join } from "node:path";
import { javascriptSourceAnalysis } from "../../../src/composition/javascriptSourceAnalysis.js";
import { expect, it } from "vitest";
@@ -18,6 +19,7 @@ const analyzeFixture = async (source: string, addonPath = "addon.node") => {
const result = await analyzeJavaScriptApplication(
{ input_path: fixture, format: "directory" },
scope,
{ sourceAnalysis: javascriptSourceAnalysis },
);
if (!result.ok) throw result.error;
return javascriptApplicationAnalysisResultSchema.parse(
+1 -1
View File
@@ -4,7 +4,7 @@ import {
createJavaScriptSemanticGraphProjection,
type JavaScriptSemanticGraphProjection,
} from "../../src/application/javascript/JavaScriptSemanticGraphBuilder.js";
import { createJavaScriptSourceAnalysis } from "../../src/artifacts/javascript/JavaScriptSourceAnalysis.js";
import { createJavaScriptSourceAnalysis } from "../../src/javascript/analysis/JavaScriptSourceAnalysis.js";
import type { ArtifactResourceScope } from "../../src/resources/ArtifactResourceScope.js";
import type { JavaScriptArtifactFileSet } from "../../src/domain/javascript/javascriptArtifactFiles.js";
import { withArtifactResourceScope } from "./artifactInventory.js";
@@ -1,5 +1,6 @@
import type { FileHandle } from "node:fs/promises";
import { open, realpath, writeFile } from "node:fs/promises";
import { javascriptSourceAnalysis } from "../../src/composition/javascriptSourceAnalysis.js";
import { join } from "node:path";
import { expect, it, onTestFinished, vi } from "vitest";
import { analyzeJavaScriptApplication } from "../../src/application/javascript/JavaScriptApplicationService.js";
@@ -105,6 +106,7 @@ it.each(
{ input_path: root, source_paths: ["main.js"] },
scope,
{
sourceAnalysis: javascriptSourceAnalysis,
signal: controller.signal,
progress: {
report: async (update) => {
+10 -2
View File
@@ -6,6 +6,7 @@ import {
import { reconstructJavaScriptArtifact as reconstructOwned } from "../../src/application/javascript/JavaScriptArtifactReconstruction.js";
import { analyzeJavaScriptApplicationInputSchema } from "../../src/domain/javascript/javascriptApplicationAnalysis.js";
import type { ProgressReporter } from "../../src/ports/ProgressReporter.js";
import { javascriptSourceAnalysis } from "../../src/composition/javascriptSourceAnalysis.js";
import { readJavaScriptArtifactFiles as readOwned } from "../../src/artifacts/javascript/JavaScriptArtifactFiles.js";
import type { ArtifactReader } from "../../src/resources/ArtifactReader.js";
import type { ArtifactInventorySnapshot } from "../../src/domain/artifactInventorySnapshot.js";
@@ -24,8 +25,14 @@ export const readJavaScriptArtifactFiles = (
/** Run a JavaScript analysis with an awaited, test-owned artifact scope. */
export const analyzeJavaScriptApplication = (
input: unknown,
options: JavaScriptApplicationOptions = {},
) => withArtifactResourceScope((scope) => analyzeOwned(input, scope, options));
options: Omit<JavaScriptApplicationOptions, "sourceAnalysis"> = {},
) =>
withArtifactResourceScope((scope) =>
analyzeOwned(input, scope, {
sourceAnalysis: javascriptSourceAnalysis,
...options,
}),
);
/** Reconstruct a fixture with an awaited, test-owned artifact scope. */
export const reconstructJavaScriptArtifact = (
@@ -37,6 +44,7 @@ export const reconstructJavaScriptArtifact = (
reconstructOwned(
analyzeJavaScriptApplicationInputSchema.parse(rawInput),
scope,
javascriptSourceAnalysis,
signal,
progress,
),