feat(application): add cross-layer graph workflows
This commit is contained in:
@@ -39,6 +39,13 @@ export const JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER = {
|
||||
version: "1",
|
||||
} as const;
|
||||
|
||||
/** Provider identity for graph-native feature tracing and version comparison. */
|
||||
export const JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER = {
|
||||
id: "rea-javascript-application-workflows",
|
||||
name: "REA JavaScript application workflows",
|
||||
version: "1",
|
||||
} as const;
|
||||
|
||||
/** Provider identity for deterministic cross-artifact comparisons. */
|
||||
export const ARTIFACT_COMPARISON_PROVIDER = {
|
||||
id: "rea-artifact-comparison",
|
||||
|
||||
@@ -0,0 +1,141 @@
|
||||
import {
|
||||
JAVASCRIPT_APPLICATION_PROVIDER,
|
||||
JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER,
|
||||
} from "./InvestigationProviders.js";
|
||||
import { parseEvidence, type Evidence } from "../domain/evidence.js";
|
||||
import {
|
||||
analyzeJavaScriptApplicationInputSchema,
|
||||
javascriptApplicationAnalysisResultSchema,
|
||||
type JavaScriptApplicationAnalysisResult,
|
||||
} from "../domain/javascriptApplicationAnalysis.js";
|
||||
import type { JavaScriptApplicationGraph } from "../domain/javascriptApplicationGraph.js";
|
||||
import { javascriptRuntimeReconciliationResultSchema } from "../domain/javascriptRuntimeReconciliationSchemas.js";
|
||||
|
||||
/** Supported immutable source for an application-level graph workflow. */
|
||||
export interface ApplicationGraphEvidenceSource {
|
||||
readonly evidence: Evidence;
|
||||
readonly graph: JavaScriptApplicationGraph;
|
||||
readonly kind: "static-application" | "static-runtime-reconciliation";
|
||||
readonly rootArtifactSha256: string;
|
||||
}
|
||||
|
||||
/** Parse and authenticate one REA-produced JavaScript Application Graph Evidence. */
|
||||
export const parseApplicationGraphEvidence = (
|
||||
input: unknown,
|
||||
): ApplicationGraphEvidenceSource => {
|
||||
const evidence = parseEvidence(input);
|
||||
if (
|
||||
evidence.operation === "analyze_javascript_application" &&
|
||||
evidence.predicate_type === "rea.javascript-application-analysis/v1" &&
|
||||
providerMatches(evidence, JAVASCRIPT_APPLICATION_PROVIDER)
|
||||
)
|
||||
return staticApplicationSource(evidence);
|
||||
if (
|
||||
evidence.operation === "reconcile_javascript_runtime" &&
|
||||
evidence.predicate_type === "rea.javascript-runtime-reconciliation/v1" &&
|
||||
providerMatches(evidence, JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER)
|
||||
)
|
||||
return staticRuntimeSource(evidence);
|
||||
throw new TypeError(
|
||||
"Application workflow requires authenticated analyze_javascript_application or reconcile_javascript_runtime Evidence",
|
||||
);
|
||||
};
|
||||
|
||||
const staticApplicationSource = (
|
||||
evidence: Evidence,
|
||||
): ApplicationGraphEvidenceSource => {
|
||||
if (
|
||||
evidence.authority !== "shipped-artifact" ||
|
||||
evidence.confidence !== "derived"
|
||||
)
|
||||
throw new TypeError(
|
||||
"JavaScript application Evidence authority or confidence is invalid",
|
||||
);
|
||||
const result = javascriptApplicationAnalysisResultSchema.parse(
|
||||
evidence.normalized_result,
|
||||
);
|
||||
analyzeJavaScriptApplicationInputSchema.parse({
|
||||
input_path: result.input_path,
|
||||
...evidence.parameters,
|
||||
});
|
||||
assertApplicationSubject(evidence, result);
|
||||
return {
|
||||
evidence,
|
||||
graph: result.graph,
|
||||
kind: "static-application",
|
||||
rootArtifactSha256: result.root_artifact_sha256,
|
||||
};
|
||||
};
|
||||
|
||||
const staticRuntimeSource = (
|
||||
evidence: Evidence,
|
||||
): ApplicationGraphEvidenceSource => {
|
||||
if (
|
||||
evidence.authority !== "analyst-inference" ||
|
||||
evidence.confidence !== "inferred"
|
||||
)
|
||||
throw new TypeError(
|
||||
"JavaScript runtime reconciliation Evidence authority or confidence is invalid",
|
||||
);
|
||||
const result = javascriptRuntimeReconciliationResultSchema.parse(
|
||||
evidence.normalized_result,
|
||||
);
|
||||
if (
|
||||
result.evidence_links.some(
|
||||
(evidenceId) => !evidence.evidence_links.includes(evidenceId),
|
||||
)
|
||||
)
|
||||
throw new TypeError(
|
||||
"Runtime reconciliation result references Evidence outside its envelope",
|
||||
);
|
||||
const applicationLayer = result.static_layers.find(
|
||||
({ role }) => role === "application",
|
||||
);
|
||||
if (applicationLayer === undefined)
|
||||
throw new TypeError("Runtime reconciliation application layer is missing");
|
||||
return {
|
||||
evidence,
|
||||
graph: result.graph,
|
||||
kind: "static-runtime-reconciliation",
|
||||
rootArtifactSha256: applicationLayer.root_artifact_sha256,
|
||||
};
|
||||
};
|
||||
|
||||
const assertApplicationSubject = (
|
||||
evidence: Evidence,
|
||||
result: JavaScriptApplicationAnalysisResult,
|
||||
): void => {
|
||||
if (
|
||||
evidence.subject === null ||
|
||||
evidence.subject.digest.sha256 !== result.root_artifact_sha256 ||
|
||||
evidence.subject.format !== result.format
|
||||
)
|
||||
throw new TypeError(
|
||||
"JavaScript application Evidence subject does not match its result",
|
||||
);
|
||||
};
|
||||
|
||||
const providerMatches = (
|
||||
evidence: Evidence,
|
||||
provider: {
|
||||
readonly id: string;
|
||||
readonly name: string;
|
||||
readonly version: string;
|
||||
},
|
||||
): boolean =>
|
||||
evidence.provider.id === provider.id &&
|
||||
evidence.provider.name === provider.name &&
|
||||
evidence.provider.version === provider.version;
|
||||
|
||||
/** Parse unique, artifact-bound Evidence that may extend a native handoff. */
|
||||
export const parseNativeApplicationEvidence = (
|
||||
inputs: readonly unknown[],
|
||||
): Evidence[] => {
|
||||
const parsed = inputs.map((input) => parseEvidence(input));
|
||||
if (parsed.some(({ subject }) => subject === null))
|
||||
throw new TypeError("Native handoff Evidence requires an artifact subject");
|
||||
const ids = parsed.map(({ evidence_id: id }) => id);
|
||||
if (new Set(ids).size !== ids.length)
|
||||
throw new TypeError("Native handoff Evidence must be unique");
|
||||
return parsed;
|
||||
};
|
||||
@@ -0,0 +1,45 @@
|
||||
import {
|
||||
createEvidence,
|
||||
type Evidence,
|
||||
type EvidenceObservation,
|
||||
} from "../domain/evidence.js";
|
||||
import type { ApplicationVersionComparisonResult } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
|
||||
import type { ApplicationFeatureTraceResult } from "../domain/javascriptFeatureTraceSchemas.js";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER } from "./InvestigationProviders.js";
|
||||
|
||||
/** Create derived Evidence for one bounded application-graph feature trace. */
|
||||
export const createApplicationFeatureTraceEvidence = (
|
||||
parameters: EvidenceObservation["parameters"],
|
||||
result: ApplicationFeatureTraceResult,
|
||||
): Evidence =>
|
||||
createEvidence(undefined, JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER, {
|
||||
predicateType: "rea.application-feature-trace/v1",
|
||||
operation: "trace_application_feature",
|
||||
parameters,
|
||||
result: jsonValueSchema.parse(result),
|
||||
rawResult: null,
|
||||
confidence: "inferred",
|
||||
authority: "analyst-inference",
|
||||
environment: null,
|
||||
limitations: result.limitations,
|
||||
evidenceLinks: result.evidence_links,
|
||||
});
|
||||
|
||||
/** Create derived Evidence for one tiered application version comparison. */
|
||||
export const createApplicationVersionComparisonEvidence = (
|
||||
parameters: EvidenceObservation["parameters"],
|
||||
result: ApplicationVersionComparisonResult,
|
||||
): Evidence =>
|
||||
createEvidence(undefined, JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER, {
|
||||
predicateType: "rea.application-version-comparison/v1",
|
||||
operation: "compare_application_versions",
|
||||
parameters,
|
||||
result: jsonValueSchema.parse(result),
|
||||
rawResult: null,
|
||||
confidence: "inferred",
|
||||
authority: "analyst-inference",
|
||||
environment: null,
|
||||
limitations: result.limitations,
|
||||
evidenceLinks: result.evidence_links,
|
||||
});
|
||||
@@ -0,0 +1,121 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
AnalysisInputError,
|
||||
AnalysisProtocolError,
|
||||
type AnalysisError,
|
||||
} from "../domain/errors.js";
|
||||
import type { Evidence } from "../domain/evidence.js";
|
||||
import { compareJavaScriptApplicationVersions } from "../domain/javascriptApplicationVersionComparison.js";
|
||||
import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
|
||||
import { traceApplicationFeature } from "../domain/javascriptFeatureTrace.js";
|
||||
import { traceApplicationFeatureInputSchema } from "../domain/javascriptFeatureTraceSchemas.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import {
|
||||
parseApplicationGraphEvidence,
|
||||
parseNativeApplicationEvidence,
|
||||
} from "./JavaScriptApplicationEvidenceGraph.js";
|
||||
import {
|
||||
createApplicationFeatureTraceEvidence,
|
||||
createApplicationVersionComparisonEvidence,
|
||||
} from "./JavaScriptApplicationWorkflowEvidence.js";
|
||||
|
||||
/** Authenticate Evidence and derive one bounded cross-layer feature trace. */
|
||||
export const traceApplicationFeatureEvidence = (
|
||||
rawInput: unknown,
|
||||
): Result<Evidence, AnalysisError> => {
|
||||
const operation = "trace_application_feature";
|
||||
const parsed = traceApplicationFeatureInputSchema.safeParse(rawInput);
|
||||
if (!parsed.success) return err(new AnalysisInputError(operation));
|
||||
try {
|
||||
const source = parseApplicationGraphEvidence(parsed.data.application);
|
||||
const nativeEvidence = parseNativeApplicationEvidence(
|
||||
parsed.data.native_observations,
|
||||
);
|
||||
const result = traceApplicationFeature({
|
||||
sourceEvidenceId: source.evidence.evidence_id,
|
||||
graph: source.graph,
|
||||
nativeEvidence,
|
||||
seed: parsed.data.seed,
|
||||
direction: parsed.data.direction,
|
||||
limits: parsed.data.limits,
|
||||
});
|
||||
return ok(
|
||||
createApplicationFeatureTraceEvidence(
|
||||
{
|
||||
application_evidence_id: source.evidence.evidence_id,
|
||||
native_evidence_ids: nativeEvidence.map(({ evidence_id: id }) => id),
|
||||
seed: parsed.data.seed,
|
||||
direction: parsed.data.direction,
|
||||
limits: parsed.data.limits,
|
||||
},
|
||||
result,
|
||||
),
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
return workflowFailure(operation, cause);
|
||||
}
|
||||
};
|
||||
|
||||
/** Authenticate both graphs and derive a tiered cross-version change graph. */
|
||||
export const compareApplicationVersionsEvidence = (
|
||||
rawInput: unknown,
|
||||
): Result<Evidence, AnalysisError> => {
|
||||
const operation = "compare_application_versions";
|
||||
const parsed = compareApplicationVersionsInputSchema.safeParse(rawInput);
|
||||
if (!parsed.success) return err(new AnalysisInputError(operation));
|
||||
try {
|
||||
const left = parseApplicationGraphEvidence(parsed.data.left);
|
||||
const right = parseApplicationGraphEvidence(parsed.data.right);
|
||||
const leftNative = parseNativeApplicationEvidence(
|
||||
parsed.data.left_native_observations,
|
||||
);
|
||||
const rightNative = parseNativeApplicationEvidence(
|
||||
parsed.data.right_native_observations,
|
||||
);
|
||||
const result = compareJavaScriptApplicationVersions({
|
||||
left: {
|
||||
evidenceId: left.evidence.evidence_id,
|
||||
rootArtifactSha256: left.rootArtifactSha256,
|
||||
graph: left.graph,
|
||||
},
|
||||
right: {
|
||||
evidenceId: right.evidence.evidence_id,
|
||||
rootArtifactSha256: right.rootArtifactSha256,
|
||||
graph: right.graph,
|
||||
},
|
||||
leftNativeEvidence: leftNative,
|
||||
rightNativeEvidence: rightNative,
|
||||
limits: parsed.data.limits,
|
||||
});
|
||||
return ok(
|
||||
createApplicationVersionComparisonEvidence(
|
||||
{
|
||||
left_evidence_id: left.evidence.evidence_id,
|
||||
right_evidence_id: right.evidence.evidence_id,
|
||||
left_native_evidence_ids: leftNative.map(({ evidence_id: id }) => id),
|
||||
right_native_evidence_ids: rightNative.map(
|
||||
({ evidence_id: id }) => id,
|
||||
),
|
||||
limits: parsed.data.limits,
|
||||
},
|
||||
result,
|
||||
),
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
return workflowFailure(operation, cause);
|
||||
}
|
||||
};
|
||||
|
||||
const workflowFailure = (
|
||||
operation: string,
|
||||
cause: unknown,
|
||||
): Result<never, AnalysisError> =>
|
||||
err(
|
||||
cause instanceof z.ZodError || cause instanceof TypeError
|
||||
? new AnalysisInputError(operation)
|
||||
: new AnalysisProtocolError(
|
||||
"JavaScript application workflow produced an invalid result",
|
||||
{ cause },
|
||||
),
|
||||
);
|
||||
@@ -34,6 +34,7 @@ import { registerPolicyCommands } from "./cliPolicyCommands.js";
|
||||
import { registerBrowserCommands } from "./cliBrowserCommands.js";
|
||||
import { registerAdvancedBrowserCommands } from "./cliBrowserAdvancedCommands.js";
|
||||
import { registerElectronCommands } from "./cliElectronCommands.js";
|
||||
import { registerApplicationCommands } from "./cliApplicationCommands.js";
|
||||
import { CLI_COMMANDS } from "./cliCommandNames.js";
|
||||
import {
|
||||
analysisProviderSelectorSchema,
|
||||
@@ -89,6 +90,7 @@ export const createCli = (): ReturnType<typeof Cli.create> => {
|
||||
registerBrowserCommands(cli, logger);
|
||||
registerAdvancedBrowserCommands(cli, logger);
|
||||
registerElectronCommands(cli, logger);
|
||||
registerApplicationCommands(cli, logger);
|
||||
return cli;
|
||||
};
|
||||
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
import { Cli, z } from "incur";
|
||||
|
||||
import {
|
||||
compareApplicationVersionsEvidence,
|
||||
traceApplicationFeatureEvidence,
|
||||
} from "./application/JavaScriptApplicationWorkflowService.js";
|
||||
import { CLI_COMMANDS } from "./cliCommandNames.js";
|
||||
import { parseCliJsonInput } from "./cliJsonInput.js";
|
||||
import { logCliCommand } from "./cliLogging.js";
|
||||
import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
|
||||
import type { JsonValue } from "./domain/jsonValue.js";
|
||||
import type { Logger } from "./logger.js";
|
||||
|
||||
/** Register CLI equivalents of provider-neutral application graph workflows. */
|
||||
export const registerApplicationCommands = (
|
||||
cli: ReturnType<typeof Cli.create>,
|
||||
logger: Logger,
|
||||
): void => {
|
||||
registerJsonCommand(
|
||||
cli,
|
||||
logger,
|
||||
CLI_COMMANDS.traceApplicationFeature,
|
||||
"Trace a typed seed through authenticated application Evidence JSON",
|
||||
traceApplicationFeatureEvidence,
|
||||
);
|
||||
registerJsonCommand(
|
||||
cli,
|
||||
logger,
|
||||
CLI_COMMANDS.compareApplicationVersions,
|
||||
"Compare two authenticated JavaScript Application Graph versions",
|
||||
compareApplicationVersionsEvidence,
|
||||
);
|
||||
};
|
||||
|
||||
const registerJsonCommand = (
|
||||
cli: ReturnType<typeof Cli.create>,
|
||||
logger: Logger,
|
||||
name: string,
|
||||
description: string,
|
||||
workflow: (
|
||||
input: unknown,
|
||||
) =>
|
||||
| { readonly ok: true; readonly value: JsonValue }
|
||||
| { readonly ok: false; readonly error: Error },
|
||||
): void => {
|
||||
cli.command(name, {
|
||||
description,
|
||||
args: z.object({
|
||||
inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
|
||||
}),
|
||||
run: ({ args }) =>
|
||||
logCliCommand(logger, name, async () => {
|
||||
const input = await parseCliJsonInput(args.inputJson, name);
|
||||
if (!input.ok) return input.error;
|
||||
const result = workflow(input.value);
|
||||
return result.ok
|
||||
? result.value
|
||||
: {
|
||||
error: "Application workflow failed",
|
||||
...projectAnalysisError(
|
||||
result.error instanceof AnalysisInputError
|
||||
? result.error
|
||||
: new AnalysisInputError(name),
|
||||
),
|
||||
};
|
||||
}),
|
||||
});
|
||||
};
|
||||
@@ -40,6 +40,8 @@ export const CLI_COMMANDS = Object.freeze({
|
||||
inspectElectronPage: "inspect-electron-page",
|
||||
analyzeJavaScriptApplication: "analyze-javascript-application",
|
||||
reconcileJavaScriptRuntime: "reconcile-javascript-runtime",
|
||||
traceApplicationFeature: "trace-application-feature",
|
||||
compareApplicationVersions: "compare-application-versions",
|
||||
});
|
||||
|
||||
/** Ordered primary CLI inventory; aliases are intentionally excluded. */
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
import { readFile, stat } from "node:fs/promises";
|
||||
|
||||
import { Cli, z } from "incur";
|
||||
|
||||
import {
|
||||
@@ -21,8 +19,7 @@ import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
|
||||
import type { JsonValue } from "./domain/jsonValue.js";
|
||||
import type { Logger } from "./logger.js";
|
||||
import { CLI_COMMANDS } from "./cliCommandNames.js";
|
||||
|
||||
const MAX_RECONCILIATION_INPUT_BYTES = 64 * 1_024 * 1_024;
|
||||
import { parseCliJsonInput } from "./cliJsonInput.js";
|
||||
|
||||
const scopeOptions = {
|
||||
allowedFileRoots: z
|
||||
@@ -61,7 +58,10 @@ const registerJavaScriptRuntimeReconciliationCommand = (
|
||||
logger,
|
||||
CLI_COMMANDS.reconcileJavaScriptRuntime,
|
||||
async () => {
|
||||
const input = await parseJsonInput(args.inputJson);
|
||||
const input = await parseCliJsonInput(
|
||||
args.inputJson,
|
||||
"reconcile_javascript_runtime",
|
||||
);
|
||||
if (!input.ok) return input.error;
|
||||
const result = reconcileJavaScriptRuntimeEvidence(input.value);
|
||||
return result.ok ? result.value : cliError(result.error);
|
||||
@@ -266,60 +266,6 @@ const electronContext = async () => {
|
||||
const inputError = (operation: string): JsonValue =>
|
||||
cliError(new AnalysisInputError(operation));
|
||||
|
||||
const parseJson = (value: string): unknown => {
|
||||
try {
|
||||
return JSON.parse(value);
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
};
|
||||
|
||||
const parseJsonInput = async (
|
||||
value: string,
|
||||
): Promise<
|
||||
| { readonly ok: true; readonly value: unknown }
|
||||
| { readonly ok: false; readonly error: JsonValue }
|
||||
> => {
|
||||
const inline = parseJson(value);
|
||||
if (inline !== undefined) return { ok: true, value: inline };
|
||||
if (["{", "["].includes(value.trimStart()[0] ?? ""))
|
||||
return {
|
||||
ok: false,
|
||||
error: inputError("reconcile_javascript_runtime"),
|
||||
};
|
||||
try {
|
||||
const metadata = await stat(value);
|
||||
if (!metadata.isFile()) return jsonFileError(value, "not-file");
|
||||
if (metadata.size > MAX_RECONCILIATION_INPUT_BYTES)
|
||||
return jsonFileError(value, "too-large");
|
||||
const bytes = await readFile(value);
|
||||
if (bytes.byteLength > MAX_RECONCILIATION_INPUT_BYTES)
|
||||
return jsonFileError(value, "too-large");
|
||||
const parsed = parseJson(bytes.toString("utf8"));
|
||||
return parsed === undefined
|
||||
? jsonFileError(value, "invalid-json")
|
||||
: { ok: true, value: parsed };
|
||||
} catch {
|
||||
return jsonFileError(value, "read-failed");
|
||||
}
|
||||
};
|
||||
|
||||
const jsonFileError = (
|
||||
path: string,
|
||||
reason: "not-file" | "too-large" | "invalid-json" | "read-failed",
|
||||
) => ({
|
||||
ok: false as const,
|
||||
error: {
|
||||
error: "Electron analysis failed",
|
||||
...projectAnalysisError(
|
||||
new AnalysisInputError("reconcile_javascript_runtime"),
|
||||
),
|
||||
input_path: path,
|
||||
input_reason: reason,
|
||||
maximum_input_bytes: MAX_RECONCILIATION_INPUT_BYTES,
|
||||
},
|
||||
});
|
||||
|
||||
const cliError = (
|
||||
error: Parameters<typeof projectAnalysisError>[0],
|
||||
): JsonValue => ({
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
import { readFile, stat } from "node:fs/promises";
|
||||
|
||||
import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
|
||||
import type { JsonValue } from "./domain/jsonValue.js";
|
||||
|
||||
const MAX_JSON_INPUT_BYTES = 64 * 1_024 * 1_024;
|
||||
|
||||
/** Parse bounded inline JSON or one bounded local JSON file for a CLI workflow. */
|
||||
export const parseCliJsonInput = async (
|
||||
value: string,
|
||||
operation: string,
|
||||
): Promise<
|
||||
| { readonly ok: true; readonly value: unknown }
|
||||
| { readonly ok: false; readonly error: JsonValue }
|
||||
> => {
|
||||
const inline = parseJson(value);
|
||||
if (inline !== undefined) return { ok: true, value: inline };
|
||||
if (["{", "["].includes(value.trimStart()[0] ?? ""))
|
||||
return { ok: false, error: inputError(operation) };
|
||||
try {
|
||||
const metadata = await stat(value);
|
||||
if (!metadata.isFile()) return jsonFileError(value, operation, "not-file");
|
||||
if (metadata.size > MAX_JSON_INPUT_BYTES)
|
||||
return jsonFileError(value, operation, "too-large");
|
||||
const bytes = await readFile(value);
|
||||
if (bytes.byteLength > MAX_JSON_INPUT_BYTES)
|
||||
return jsonFileError(value, operation, "too-large");
|
||||
const parsed = parseJson(bytes.toString("utf8"));
|
||||
return parsed === undefined
|
||||
? jsonFileError(value, operation, "invalid-json")
|
||||
: { ok: true, value: parsed };
|
||||
} catch {
|
||||
return jsonFileError(value, operation, "read-failed");
|
||||
}
|
||||
};
|
||||
|
||||
const parseJson = (value: string): unknown => {
|
||||
try {
|
||||
return JSON.parse(value);
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
};
|
||||
|
||||
const inputError = (operation: string): JsonValue => ({
|
||||
error: "Application workflow failed",
|
||||
...projectAnalysisError(new AnalysisInputError(operation)),
|
||||
});
|
||||
|
||||
const jsonFileError = (
|
||||
path: string,
|
||||
operation: string,
|
||||
reason: "not-file" | "too-large" | "invalid-json" | "read-failed",
|
||||
) => ({
|
||||
ok: false as const,
|
||||
error: {
|
||||
error: "Application workflow failed",
|
||||
...projectAnalysisError(new AnalysisInputError(operation)),
|
||||
input_path: path,
|
||||
input_reason: reason,
|
||||
maximum_input_bytes: MAX_JSON_INPUT_BYTES,
|
||||
},
|
||||
});
|
||||
@@ -0,0 +1,65 @@
|
||||
import {
|
||||
applicationVersionComparisonResultSchema,
|
||||
compareApplicationVersionsInputSchema,
|
||||
} from "../domain/javascriptApplicationVersionComparisonSchemas.js";
|
||||
import {
|
||||
applicationFeatureTraceResultSchema,
|
||||
traceApplicationFeatureInputSchema,
|
||||
} from "../domain/javascriptFeatureTraceSchemas.js";
|
||||
import { evidenceEnvelopeSchema } from "../domain/evidence.js";
|
||||
import type { ToolContract } from "./toolContracts.js";
|
||||
import {
|
||||
JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
|
||||
JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
|
||||
} from "./javascriptApplicationWorkflowExamples.js";
|
||||
|
||||
const traceOutputSchema = evidenceEnvelopeSchema
|
||||
.omit({ normalized_result: true })
|
||||
.extend({ normalized_result: applicationFeatureTraceResultSchema });
|
||||
const comparisonOutputSchema = evidenceEnvelopeSchema
|
||||
.omit({ normalized_result: true })
|
||||
.extend({ normalized_result: applicationVersionComparisonResultSchema });
|
||||
|
||||
/** Provider-neutral graph workflow contracts shared by MCP and CLI adapters. */
|
||||
export const APPLICATION_TOOL_CONTRACTS = [
|
||||
{
|
||||
name: "trace_application_feature",
|
||||
description:
|
||||
"Trace a typed literal seed through an authenticated JavaScript Application Graph with explicit direction, depth, node, edge, and path bounds. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
|
||||
kind: "application",
|
||||
inputSchema: traceApplicationFeatureInputSchema,
|
||||
outputSchema: traceOutputSchema,
|
||||
annotations: {
|
||||
readOnlyHint: true,
|
||||
destructiveHint: false,
|
||||
idempotentHint: true,
|
||||
openWorldHint: false,
|
||||
},
|
||||
examples: [
|
||||
{
|
||||
title: "Trace one module seed through a retained application graph",
|
||||
input: JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
name: "compare_application_versions",
|
||||
description:
|
||||
"Compare two authenticated JavaScript Application Graph versions using unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus a bounded changed_from graph without fuzzy or module-ordinal pairing.",
|
||||
kind: "application",
|
||||
inputSchema: compareApplicationVersionsInputSchema,
|
||||
outputSchema: comparisonOutputSchema,
|
||||
annotations: {
|
||||
readOnlyHint: true,
|
||||
destructiveHint: false,
|
||||
idempotentHint: true,
|
||||
openWorldHint: false,
|
||||
},
|
||||
examples: [
|
||||
{
|
||||
title: "Compare authenticated static and reconciled application graphs",
|
||||
input: JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
|
||||
},
|
||||
],
|
||||
},
|
||||
] as const satisfies readonly ToolContract[];
|
||||
@@ -0,0 +1,64 @@
|
||||
import { createEvidence } from "../domain/evidence.js";
|
||||
import { reconcileJavaScriptRuntime } from "../domain/javascriptRuntimeReconciliation.js";
|
||||
import {
|
||||
JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
|
||||
JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE,
|
||||
} from "./javascriptRuntimeReconciliationExample.js";
|
||||
|
||||
const reconciliation = reconcileJavaScriptRuntime(
|
||||
JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE,
|
||||
);
|
||||
const reconciliationEvidence = createEvidence(
|
||||
undefined,
|
||||
{
|
||||
id: "rea-javascript-runtime-reconciliation",
|
||||
name: "REA JavaScript runtime reconciliation",
|
||||
version: "1",
|
||||
},
|
||||
{
|
||||
predicateType: "rea.javascript-runtime-reconciliation/v1",
|
||||
operation: "reconcile_javascript_runtime",
|
||||
parameters: {
|
||||
static_layers:
|
||||
JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE.static_layers.map(
|
||||
({ role, analysis }) => ({
|
||||
role,
|
||||
evidence_id: analysis.evidence_id,
|
||||
runtime_mappings: [],
|
||||
}),
|
||||
),
|
||||
runtime_evidence_ids:
|
||||
JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE.runtime_observations.map(
|
||||
({ evidence_id: id }) => id,
|
||||
),
|
||||
limits: {
|
||||
max_runtime_entities: 10_000,
|
||||
max_reconciliation_items: 20_000,
|
||||
max_static_load_states: 20_000,
|
||||
},
|
||||
},
|
||||
result: reconciliation,
|
||||
confidence: "inferred",
|
||||
authority: "analyst-inference",
|
||||
limitations: reconciliation.limitations,
|
||||
evidenceLinks: reconciliation.evidence_links,
|
||||
},
|
||||
);
|
||||
|
||||
/** Valid public trace request without proprietary artifacts. */
|
||||
export const JAVASCRIPT_FEATURE_TRACE_EXAMPLE = {
|
||||
application: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
|
||||
seed: {
|
||||
kind: "module" as const,
|
||||
value: "renderer.js",
|
||||
match: "exact" as const,
|
||||
case_sensitive: false,
|
||||
},
|
||||
direction: "both" as const,
|
||||
};
|
||||
|
||||
/** Valid static/runtime graph pair demonstrating comparison authority. */
|
||||
export const JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE = {
|
||||
left: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
|
||||
right: reconciliationEvidence,
|
||||
};
|
||||
@@ -132,6 +132,9 @@ const staticEvidence = createEvidence(
|
||||
},
|
||||
);
|
||||
|
||||
/** Minimal valid static application Evidence for graph workflow examples. */
|
||||
export const JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE = staticEvidence;
|
||||
|
||||
const runtimeEvidence = createEvidence(
|
||||
undefined,
|
||||
{
|
||||
|
||||
@@ -114,9 +114,13 @@ export const PROMPT_CONTRACTS = [
|
||||
},
|
||||
steps: [
|
||||
{
|
||||
tools: ["binary_session", "open_binary"],
|
||||
tools: [
|
||||
"binary_session",
|
||||
"open_binary",
|
||||
"analyze_javascript_application",
|
||||
],
|
||||
instruction:
|
||||
"Inspect provider availability and effects first. Open target_path only when no matching target is active.",
|
||||
"Inspect provider availability and effects first. For an approved JavaScript/Electron artifact, reconstruct its application graph without execution; otherwise open target_path only when no matching target is active.",
|
||||
},
|
||||
{
|
||||
tools: ["list_documents", "set_current_document", "binary_overview"],
|
||||
@@ -128,6 +132,11 @@ export const PROMPT_CONTRACTS = [
|
||||
instruction:
|
||||
"Search in literal mode first, follow every continuation needed for the stated scope, and resolve selected procedures to canonical addresses.",
|
||||
},
|
||||
{
|
||||
tools: ["trace_application_feature"],
|
||||
instruction:
|
||||
"When authenticated application-graph Evidence exists, trace a typed literal route, API, channel, module, string, or native export through a bounded cross-layer subgraph before native localization.",
|
||||
},
|
||||
{
|
||||
tools: [
|
||||
"analyze_function",
|
||||
@@ -179,6 +188,15 @@ export const PROMPT_CONTRACTS = [
|
||||
instruction:
|
||||
"Inventory each target independently before extraction. Follow nodes, occurrences, and edges to completion and retain every Evidence page for each manifest.",
|
||||
},
|
||||
{
|
||||
tools: [
|
||||
"analyze_javascript_application",
|
||||
"reconcile_javascript_runtime",
|
||||
"compare_application_versions",
|
||||
],
|
||||
instruction:
|
||||
"For JavaScript/Electron versions, reconstruct each approved artifact independently, optionally reconcile separately retained passive runtime Evidence, then compare authenticated graphs with unique-only identity tiers. Keep ambiguous and incomplete matches unknown.",
|
||||
},
|
||||
{
|
||||
tools: ["export_evidence_bundle", "compare_artifacts"],
|
||||
instruction:
|
||||
|
||||
@@ -24,6 +24,7 @@ export type ToolKind =
|
||||
| "artifact-provider"
|
||||
| "browser-provider"
|
||||
| "electron-provider"
|
||||
| "application"
|
||||
| "session";
|
||||
|
||||
/** Single source of truth for a public MCP tool. */
|
||||
|
||||
@@ -28,6 +28,7 @@ import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";
|
||||
import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";
|
||||
import { BROWSER_TOOL_CONTRACTS } from "./browserToolContracts.js";
|
||||
import { ELECTRON_TOOL_CONTRACTS } from "./electronToolContracts.js";
|
||||
import { APPLICATION_TOOL_CONTRACTS } from "./applicationToolContracts.js";
|
||||
import {
|
||||
closeBinaryInputSchema,
|
||||
openBinaryInputSchema,
|
||||
@@ -526,5 +527,6 @@ export const TOOL_CONTRACTS = [
|
||||
...ARTIFACT_TOOL_CONTRACTS,
|
||||
...BROWSER_TOOL_CONTRACTS,
|
||||
...ELECTRON_TOOL_CONTRACTS,
|
||||
...APPLICATION_TOOL_CONTRACTS,
|
||||
...SESSION_TOOL_CONTRACTS,
|
||||
] as const;
|
||||
|
||||
@@ -0,0 +1,324 @@
|
||||
import {
|
||||
compareCodePoints,
|
||||
createJavaScriptApplicationEdge,
|
||||
createJavaScriptApplicationGraph,
|
||||
createJavaScriptApplicationNode,
|
||||
type ApplicationEdge,
|
||||
type ApplicationGraphEvidence,
|
||||
type ApplicationNode,
|
||||
type JavaScriptApplicationGraph,
|
||||
} from "./javascriptApplicationGraph.js";
|
||||
import type {
|
||||
ApplicationVersionComparisonItem,
|
||||
CompareApplicationVersionsInput,
|
||||
} from "./javascriptApplicationVersionComparisonSchemas.js";
|
||||
|
||||
interface ChangeGraphInput {
|
||||
readonly left: JavaScriptApplicationGraph;
|
||||
readonly right: JavaScriptApplicationGraph;
|
||||
readonly leftEvidenceId: string;
|
||||
readonly rightEvidenceId: string;
|
||||
readonly items: readonly ApplicationVersionComparisonItem[];
|
||||
readonly omittedComparisonItems: number;
|
||||
readonly limits: CompareApplicationVersionsInput["limits"];
|
||||
}
|
||||
|
||||
/** Bounded cross-version graph and exact projection omission counts. */
|
||||
export interface ApplicationChangeGraphProjection {
|
||||
readonly graph: JavaScriptApplicationGraph;
|
||||
readonly omittedNodes: number;
|
||||
readonly omittedEdges: number;
|
||||
readonly omittedObservations: number;
|
||||
}
|
||||
|
||||
/** Merge compared nodes and add inferred right-to-left changed_from edges. */
|
||||
export const buildJavaScriptApplicationChangeGraph = (
|
||||
input: ChangeGraphInput,
|
||||
): ApplicationChangeGraphProjection => {
|
||||
const allNodes = nodeCandidates(input);
|
||||
const preferredRoots = uniqueSorted([
|
||||
...input.right.root_node_ids,
|
||||
...input.left.root_node_ids,
|
||||
]).filter((nodeId) => allNodes.has(nodeId));
|
||||
const orderedNodeIds = uniqueSorted([
|
||||
...preferredRoots,
|
||||
...input.items.flatMap(({ left_node_id: left, right_node_id: right }) => [
|
||||
...(right === null ? [] : [right]),
|
||||
...(left === null ? [] : [left]),
|
||||
]),
|
||||
]);
|
||||
const retainedIds = orderedNodeIds.slice(0, input.limits.max_graph_nodes);
|
||||
const retained = new Set(retainedIds);
|
||||
const merged = mergeNodes(
|
||||
retainedIds.flatMap((nodeId) => allNodes.get(nodeId) ?? []),
|
||||
);
|
||||
const sourceEdges = uniqueEdges([
|
||||
...input.left.edges,
|
||||
...input.right.edges,
|
||||
]).filter(
|
||||
({ source_node_id: source, target_node_id: target }) =>
|
||||
retained.has(source) && retained.has(target),
|
||||
);
|
||||
const comparisonEdges = input.items.flatMap((item) =>
|
||||
changedFromEdge(item, input, retained),
|
||||
);
|
||||
const candidateEdges = uniqueEdges([...sourceEdges, ...comparisonEdges]);
|
||||
const edges = candidateEdges.slice(0, input.limits.max_graph_edges);
|
||||
const omittedNodes = Math.max(0, orderedNodeIds.length - retainedIds.length);
|
||||
const omittedEdges = Math.max(0, candidateEdges.length - edges.length);
|
||||
const graphOmissions =
|
||||
omittedNodes + omittedEdges + merged.omittedObservations;
|
||||
const rootNodeIds = preferredRoots
|
||||
.filter((nodeId) => retained.has(nodeId))
|
||||
.slice(0, 1_000);
|
||||
const fallbackRoot = merged.nodes[0]?.node_id;
|
||||
const graph = createJavaScriptApplicationGraph({
|
||||
schema: "JavaScriptApplicationGraph",
|
||||
schema_version: 1,
|
||||
root_node_ids:
|
||||
rootNodeIds.length > 0
|
||||
? rootNodeIds
|
||||
: fallbackRoot === undefined
|
||||
? []
|
||||
: [fallbackRoot],
|
||||
nodes: merged.nodes,
|
||||
edges,
|
||||
coverage: changeGraphCoverage(input, graphOmissions),
|
||||
limitations: uniqueSorted([
|
||||
...input.left.limitations.map((value) => `Left: ${value}`),
|
||||
...input.right.limitations.map((value) => `Right: ${value}`),
|
||||
"changed_from edges are cross-version inferences and never promote structural or semantic matches to exact identity.",
|
||||
"The change graph contains compared entities and their retained relationships; it is not an executable application.",
|
||||
...(graphOmissions === 0
|
||||
? []
|
||||
: ["The change graph omitted content at explicit caller bounds."]),
|
||||
]),
|
||||
});
|
||||
return {
|
||||
graph,
|
||||
omittedNodes,
|
||||
omittedEdges,
|
||||
omittedObservations: merged.omittedObservations,
|
||||
};
|
||||
};
|
||||
|
||||
const nodeCandidates = (
|
||||
input: ChangeGraphInput,
|
||||
): Map<string, ApplicationNode[]> => {
|
||||
const required = new Set([
|
||||
...input.left.root_node_ids,
|
||||
...input.right.root_node_ids,
|
||||
...input.items.flatMap(({ left_node_id: left, right_node_id: right }) => [
|
||||
...(left === null ? [] : [left]),
|
||||
...(right === null ? [] : [right]),
|
||||
]),
|
||||
]);
|
||||
const output = new Map<string, ApplicationNode[]>();
|
||||
for (const node of [...input.left.nodes, ...input.right.nodes])
|
||||
if (required.has(node.node_id))
|
||||
output.set(node.node_id, [...(output.get(node.node_id) ?? []), node]);
|
||||
return output;
|
||||
};
|
||||
|
||||
const changedFromEdge = (
|
||||
item: ApplicationVersionComparisonItem,
|
||||
input: ChangeGraphInput,
|
||||
retained: ReadonlySet<string>,
|
||||
): ApplicationEdge[] => {
|
||||
const left = item.left_node_id;
|
||||
const right = item.right_node_id;
|
||||
if (
|
||||
item.match.status !== "matched" ||
|
||||
item.status === "unchanged" ||
|
||||
left === null ||
|
||||
right === null ||
|
||||
left === right ||
|
||||
!retained.has(left) ||
|
||||
!retained.has(right)
|
||||
)
|
||||
return [];
|
||||
const evidence = comparisonEvidence(item, input);
|
||||
return [
|
||||
createJavaScriptApplicationEdge({
|
||||
source_node_id: right,
|
||||
target_node_id: left,
|
||||
relation: "changed_from",
|
||||
properties: {
|
||||
comparison_item_id: item.item_id,
|
||||
status: item.status,
|
||||
match_basis: item.match.basis,
|
||||
match_confidence: item.match.confidence,
|
||||
dimensions: item.dimensions,
|
||||
},
|
||||
evidence,
|
||||
}),
|
||||
];
|
||||
};
|
||||
|
||||
const comparisonEvidence = (
|
||||
item: ApplicationVersionComparisonItem,
|
||||
input: ChangeGraphInput,
|
||||
): ApplicationGraphEvidence => {
|
||||
const right = input.right.nodes.find(
|
||||
({ node_id: id }) => id === item.right_node_id,
|
||||
);
|
||||
const left = input.left.nodes.find(
|
||||
({ node_id: id }) => id === item.left_node_id,
|
||||
);
|
||||
const source =
|
||||
right?.observations[0]?.evidence ?? left?.observations[0]?.evidence;
|
||||
const complete =
|
||||
input.left.coverage.status === "complete" &&
|
||||
input.right.coverage.status === "complete" &&
|
||||
input.omittedComparisonItems === 0;
|
||||
return {
|
||||
authority: "cross-version-comparison",
|
||||
state: "inferred",
|
||||
confidence: item.match.confidence === "medium" ? "medium" : "high",
|
||||
artifact: source?.artifact ?? {
|
||||
available: false,
|
||||
reason: "unresolved",
|
||||
detail: "Compared node has no artifact-backed observation.",
|
||||
},
|
||||
location: source?.location ?? {
|
||||
available: false,
|
||||
reason: "unresolved",
|
||||
detail: "Compared node has no actionable source location.",
|
||||
},
|
||||
extractor: {
|
||||
name: "rea-application-version-comparison",
|
||||
version: "1",
|
||||
operation: "compare_application_versions",
|
||||
executable_sha256: null,
|
||||
},
|
||||
coverage: complete
|
||||
? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
|
||||
: {
|
||||
status: "partial",
|
||||
truncated: input.omittedComparisonItems > 0,
|
||||
omitted_count:
|
||||
input.omittedComparisonItems > 0
|
||||
? input.omittedComparisonItems
|
||||
: (source?.coverage.omitted_count ?? null),
|
||||
limits:
|
||||
input.omittedComparisonItems > 0
|
||||
? [
|
||||
{
|
||||
name: "max-comparison-items",
|
||||
value: input.limits.max_comparison_items,
|
||||
unit: "items",
|
||||
},
|
||||
]
|
||||
: [],
|
||||
},
|
||||
limitations: [
|
||||
"Cross-version pairing is inferred from the stated match basis; changed_from does not prove runtime reachability.",
|
||||
...item.limitations,
|
||||
],
|
||||
evidence_ids: [input.leftEvidenceId, input.rightEvidenceId],
|
||||
};
|
||||
};
|
||||
|
||||
const changeGraphCoverage = (
|
||||
input: ChangeGraphInput,
|
||||
graphOmissions: number,
|
||||
): JavaScriptApplicationGraph["coverage"] => {
|
||||
const outputOmissions = graphOmissions + input.omittedComparisonItems;
|
||||
if (outputOmissions > 0)
|
||||
return {
|
||||
status: "partial",
|
||||
truncated: true,
|
||||
omitted_count: outputOmissions,
|
||||
limits: [
|
||||
{
|
||||
name: "max-comparison-items",
|
||||
value: input.limits.max_comparison_items,
|
||||
unit: "items",
|
||||
},
|
||||
{
|
||||
name: "max-graph-nodes",
|
||||
value: input.limits.max_graph_nodes,
|
||||
unit: "items",
|
||||
},
|
||||
{
|
||||
name: "max-graph-edges",
|
||||
value: input.limits.max_graph_edges,
|
||||
unit: "items",
|
||||
},
|
||||
],
|
||||
};
|
||||
if (
|
||||
input.left.coverage.status === "complete" &&
|
||||
input.right.coverage.status === "complete"
|
||||
)
|
||||
return {
|
||||
status: "complete",
|
||||
truncated: false,
|
||||
omitted_count: 0,
|
||||
limits: [],
|
||||
};
|
||||
const counts = [
|
||||
input.left.coverage.omitted_count,
|
||||
input.right.coverage.omitted_count,
|
||||
];
|
||||
return {
|
||||
status: "partial",
|
||||
truncated: false,
|
||||
omitted_count: counts.every((value) => value !== null)
|
||||
? counts.reduce<number>((total, value) => total + (value ?? 0), 0)
|
||||
: null,
|
||||
limits: [],
|
||||
};
|
||||
};
|
||||
|
||||
const mergeNodes = (
|
||||
nodes: readonly ApplicationNode[],
|
||||
): {
|
||||
readonly nodes: ApplicationNode[];
|
||||
readonly omittedObservations: number;
|
||||
} => {
|
||||
const groups = new Map<string, ApplicationNode[]>();
|
||||
for (const node of nodes)
|
||||
groups.set(node.node_id, [...(groups.get(node.node_id) ?? []), node]);
|
||||
let omittedObservations = 0;
|
||||
const merged = [...groups.values()].map((group) => {
|
||||
const first = group[0];
|
||||
if (first === undefined)
|
||||
throw new TypeError("Empty change-graph node group");
|
||||
const observations = [
|
||||
...new Map(
|
||||
group
|
||||
.flatMap(({ observations: values }) => values)
|
||||
.map((observation) => [observation.observation_id, observation]),
|
||||
).values(),
|
||||
].sort((left, right) =>
|
||||
compareCodePoints(left.observation_id, right.observation_id),
|
||||
);
|
||||
omittedObservations += Math.max(0, observations.length - 64);
|
||||
return createJavaScriptApplicationNode({
|
||||
kind: first.kind,
|
||||
identity: first.identity,
|
||||
observations: observations
|
||||
.slice(0, 64)
|
||||
.map(
|
||||
({ observation_id: _id, identifier_strategy: _strategy, ...value }) =>
|
||||
value,
|
||||
),
|
||||
});
|
||||
});
|
||||
return {
|
||||
nodes: merged.sort((left, right) =>
|
||||
compareCodePoints(left.node_id, right.node_id),
|
||||
),
|
||||
omittedObservations,
|
||||
};
|
||||
};
|
||||
|
||||
const uniqueEdges = (edges: readonly ApplicationEdge[]): ApplicationEdge[] =>
|
||||
[...new Map(edges.map((edge) => [edge.edge_id, edge])).values()].sort(
|
||||
(left, right) => compareCodePoints(left.edge_id, right.edge_id),
|
||||
);
|
||||
|
||||
const uniqueSorted = <Value extends string>(
|
||||
values: readonly Value[],
|
||||
): Value[] => [...new Set(values)].sort(compareCodePoints);
|
||||
@@ -24,6 +24,7 @@ const applicationEvidenceAuthoritySchema = z.enum([
|
||||
"static-relationship-inference",
|
||||
"passive-cdp-runtime",
|
||||
"cross-layer-reconciliation",
|
||||
"cross-version-comparison",
|
||||
"controlled-replay",
|
||||
"native-analysis-provider",
|
||||
"historical-reference",
|
||||
@@ -269,6 +270,15 @@ const checkAuthorityState = (
|
||||
path: ["state"],
|
||||
message: "Cross-layer reconciliation authority must remain inferred",
|
||||
});
|
||||
if (
|
||||
evidence.authority === "cross-version-comparison" &&
|
||||
evidence.state !== "inferred"
|
||||
)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["state"],
|
||||
message: "Cross-version comparison authority must remain inferred",
|
||||
});
|
||||
if (
|
||||
evidence.authority === "unknown" &&
|
||||
!["unknown", "unavailable"].includes(evidence.state)
|
||||
|
||||
@@ -0,0 +1,187 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import canonicalize from "canonicalize";
|
||||
|
||||
import type { Evidence } from "./evidence.js";
|
||||
import { buildJavaScriptApplicationChangeGraph } from "./javascriptApplicationChangeGraph.js";
|
||||
import {
|
||||
applicationVersionComparisonResultSchema,
|
||||
type ApplicationVersionComparisonResult,
|
||||
type CompareApplicationVersionsInput,
|
||||
} from "./javascriptApplicationVersionComparisonSchemas.js";
|
||||
import type { JavaScriptApplicationGraph } from "./javascriptApplicationGraph.js";
|
||||
import { compareCodePoints } from "./javascriptApplicationGraph.js";
|
||||
import { classifyJavaScriptApplicationVersions } from "./javascriptApplicationVersionItems.js";
|
||||
import { matchJavaScriptApplicationVersions } from "./javascriptApplicationVersionKeys.js";
|
||||
|
||||
/** Pure inputs after application-layer Evidence authentication. */
|
||||
export interface ApplicationVersionComparisonProjectionInput {
|
||||
readonly left: {
|
||||
readonly evidenceId: string;
|
||||
readonly rootArtifactSha256: string;
|
||||
readonly graph: JavaScriptApplicationGraph;
|
||||
};
|
||||
readonly right: {
|
||||
readonly evidenceId: string;
|
||||
readonly rootArtifactSha256: string;
|
||||
readonly graph: JavaScriptApplicationGraph;
|
||||
};
|
||||
readonly leftNativeEvidence: readonly Evidence[];
|
||||
readonly rightNativeEvidence: readonly Evidence[];
|
||||
readonly limits: CompareApplicationVersionsInput["limits"];
|
||||
}
|
||||
|
||||
/** Compare application entities with ordered unique-only identity tiers. */
|
||||
export const compareJavaScriptApplicationVersions = (
|
||||
input: ApplicationVersionComparisonProjectionInput,
|
||||
): ApplicationVersionComparisonResult => {
|
||||
const matching = matchJavaScriptApplicationVersions(
|
||||
input.left.graph.nodes,
|
||||
input.right.graph.nodes,
|
||||
);
|
||||
const projection = classifyJavaScriptApplicationVersions(matching, {
|
||||
leftGraph: input.left.graph,
|
||||
rightGraph: input.right.graph,
|
||||
leftEvidenceId: input.left.evidenceId,
|
||||
rightEvidenceId: input.right.evidenceId,
|
||||
leftNativeEvidence: input.leftNativeEvidence,
|
||||
rightNativeEvidence: input.rightNativeEvidence,
|
||||
maxCandidates: input.limits.max_candidate_nodes,
|
||||
});
|
||||
const items = projection.items.slice(0, input.limits.max_comparison_items);
|
||||
const omittedComparisonItems = projection.items.length - items.length;
|
||||
const changeGraph = buildJavaScriptApplicationChangeGraph({
|
||||
left: input.left.graph,
|
||||
right: input.right.graph,
|
||||
leftEvidenceId: input.left.evidenceId,
|
||||
rightEvidenceId: input.right.evidenceId,
|
||||
items,
|
||||
omittedComparisonItems,
|
||||
limits: input.limits,
|
||||
});
|
||||
const evidenceLinks = uniqueSorted(
|
||||
projection.items.flatMap(({ evidence_links: links }) => links),
|
||||
);
|
||||
const omissions = {
|
||||
omitted_comparison_items: omittedComparisonItems,
|
||||
omitted_candidate_references: projection.omittedCandidateReferences,
|
||||
omitted_graph_nodes: changeGraph.omittedNodes,
|
||||
omitted_graph_edges: changeGraph.omittedEdges,
|
||||
omitted_graph_observations: changeGraph.omittedObservations,
|
||||
};
|
||||
const semantic = {
|
||||
schema_version: 1 as const,
|
||||
left: {
|
||||
evidence_id: input.left.evidenceId,
|
||||
graph_id: input.left.graph.graph_id,
|
||||
root_artifact_sha256: input.left.rootArtifactSha256,
|
||||
},
|
||||
right: {
|
||||
evidence_id: input.right.evidenceId,
|
||||
graph_id: input.right.graph.graph_id,
|
||||
root_artifact_sha256: input.right.rootArtifactSha256,
|
||||
},
|
||||
summary: summary(projection.items),
|
||||
matching: matchingSummary(projection.items),
|
||||
items,
|
||||
graph: changeGraph.graph,
|
||||
coverage: {
|
||||
status: comparisonCoverageStatus(input, omissions),
|
||||
left_graph_status: input.left.graph.coverage.status,
|
||||
right_graph_status: input.right.graph.coverage.status,
|
||||
...omissions,
|
||||
},
|
||||
evidence_links: evidenceLinks,
|
||||
limitations: comparisonLimitations(input, omissions),
|
||||
};
|
||||
return applicationVersionComparisonResultSchema.parse({
|
||||
...semantic,
|
||||
comparison_id: `javc_${digestCanonical(semantic)}`,
|
||||
});
|
||||
};
|
||||
|
||||
const summary = (
|
||||
items: readonly ApplicationVersionComparisonResult["items"][number][],
|
||||
): ApplicationVersionComparisonResult["summary"] => ({
|
||||
unchanged: countStatus(items, "unchanged"),
|
||||
added: countStatus(items, "added"),
|
||||
removed: countStatus(items, "removed"),
|
||||
changed: countStatus(items, "changed"),
|
||||
unknown: countStatus(items, "unknown"),
|
||||
});
|
||||
|
||||
const countStatus = (
|
||||
items: readonly ApplicationVersionComparisonResult["items"][number][],
|
||||
status: ApplicationVersionComparisonResult["items"][number]["status"],
|
||||
): number => items.filter((item) => item.status === status).length;
|
||||
|
||||
const matchingSummary = (
|
||||
items: readonly ApplicationVersionComparisonResult["items"][number][],
|
||||
): ApplicationVersionComparisonResult["matching"] => ({
|
||||
exact_node_identity: countBasis(items, "exact-node-identity"),
|
||||
exact_content_digest: countBasis(items, "exact-content-digest"),
|
||||
exact_module_source_digest: countBasis(items, "exact-module-source-digest"),
|
||||
source_map_identity: countBasis(items, "source-map-identity"),
|
||||
structural_fingerprint: countBasis(items, "structural-fingerprint"),
|
||||
semantic_key: countBasis(items, "semantic-key"),
|
||||
ambiguous: items.filter(({ match }) => match.status === "ambiguous").length,
|
||||
unmatched: items.filter(({ match }) => match.status === "unmatched").length,
|
||||
});
|
||||
|
||||
const countBasis = (
|
||||
items: readonly ApplicationVersionComparisonResult["items"][number][],
|
||||
basis: ApplicationVersionComparisonResult["items"][number]["match"]["basis"],
|
||||
): number => items.filter(({ match }) => match.basis === basis).length;
|
||||
|
||||
type ComparisonOmissions = ApplicationVersionComparisonResult["coverage"];
|
||||
|
||||
const comparisonCoverageStatus = (
|
||||
input: ApplicationVersionComparisonProjectionInput,
|
||||
omissions: Omit<
|
||||
ComparisonOmissions,
|
||||
"status" | "left_graph_status" | "right_graph_status"
|
||||
>,
|
||||
): ApplicationVersionComparisonResult["coverage"]["status"] =>
|
||||
Object.values(omissions).some((value) => value > 0)
|
||||
? "truncated"
|
||||
: input.left.graph.coverage.status === "complete" &&
|
||||
input.right.graph.coverage.status === "complete"
|
||||
? "complete-within-inputs"
|
||||
: "partial";
|
||||
|
||||
const comparisonLimitations = (
|
||||
input: ApplicationVersionComparisonProjectionInput,
|
||||
omissions: Omit<
|
||||
ComparisonOmissions,
|
||||
"status" | "left_graph_status" | "right_graph_status"
|
||||
>,
|
||||
): string[] =>
|
||||
uniqueSorted([
|
||||
"Application comparison never uses bundler module ordinals as persistent identity and performs no fuzzy pairing.",
|
||||
"Exact digest equality proves byte identity only; source-map, structural-fingerprint, and semantic-key matches retain inferred confidence.",
|
||||
"Minified names and chunk locations are not assumed stable across versions.",
|
||||
"The comparison reads retained graphs and Evidence only; it does not execute either application.",
|
||||
"Native Evidence is linked only by exact subject digest; provider snapshot reuse remains target/provider/profile exact.",
|
||||
...(input.left.graph.coverage.status === "complete" &&
|
||||
input.right.graph.coverage.status === "complete"
|
||||
? []
|
||||
: [
|
||||
"At least one source graph is incomplete; unmatched entities on the opposite side remain unknown rather than added or removed.",
|
||||
]),
|
||||
...(Object.values(omissions).some((value) => value > 0)
|
||||
? ["Comparison output was truncated at explicit caller limits."]
|
||||
: []),
|
||||
]);
|
||||
|
||||
const digestCanonical = (value: unknown): string => {
|
||||
const encoded = canonicalize(value);
|
||||
if (encoded === undefined)
|
||||
throw new TypeError(
|
||||
"Application version comparison could not canonicalize data",
|
||||
);
|
||||
return createHash("sha256").update(encoded).digest("hex");
|
||||
};
|
||||
|
||||
const uniqueSorted = <Value extends string>(
|
||||
values: readonly Value[],
|
||||
): Value[] => [...new Set(values)].sort(compareCodePoints);
|
||||
@@ -0,0 +1,161 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import { evidenceSchema } from "./evidence.js";
|
||||
import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
|
||||
import { JAVASCRIPT_APPLICATION_NODE_KINDS } from "./javascriptApplicationGraphSchemas.js";
|
||||
|
||||
const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
|
||||
const nodeIdSchema = z.string().regex(/^jag_node_[a-f0-9]{64}$/u);
|
||||
const boundedTextSchema = z.string().min(1).max(4_096);
|
||||
|
||||
const comparisonLimitsSchema = z.strictObject({
|
||||
max_comparison_items: z.number().int().min(1).max(50_000).default(20_000),
|
||||
max_candidate_nodes: z.number().int().min(1).max(1_000).default(100),
|
||||
max_graph_nodes: z.number().int().min(1).max(100_000).default(20_000),
|
||||
max_graph_edges: z.number().int().min(1).max(200_000).default(40_000),
|
||||
});
|
||||
|
||||
/** Two authenticated application versions and deterministic output bounds. */
|
||||
export const compareApplicationVersionsInputSchema = z
|
||||
.strictObject({
|
||||
left: evidenceSchema,
|
||||
right: evidenceSchema,
|
||||
left_native_observations: z.array(evidenceSchema).max(64).default([]),
|
||||
right_native_observations: z.array(evidenceSchema).max(64).default([]),
|
||||
limits: comparisonLimitsSchema.default({
|
||||
max_comparison_items: 20_000,
|
||||
max_candidate_nodes: 100,
|
||||
max_graph_nodes: 20_000,
|
||||
max_graph_edges: 40_000,
|
||||
}),
|
||||
unknown_registry_approved: z.literal(true).optional(),
|
||||
})
|
||||
.superRefine((input, context) => {
|
||||
if (input.left.evidence_id === input.right.evidence_id)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["right"],
|
||||
message: "Application version Evidence must be distinct",
|
||||
});
|
||||
for (const side of [
|
||||
"left_native_observations",
|
||||
"right_native_observations",
|
||||
] as const) {
|
||||
const ids = input[side].map(({ evidence_id: id }) => id);
|
||||
if (new Set(ids).size !== ids.length)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: [side],
|
||||
message: "Native observations must be unique on each side",
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
const applicationVersionMatchBasisSchema = z.enum([
|
||||
"exact-node-identity",
|
||||
"exact-content-digest",
|
||||
"exact-module-source-digest",
|
||||
"source-map-identity",
|
||||
"structural-fingerprint",
|
||||
"semantic-key",
|
||||
"none",
|
||||
]);
|
||||
|
||||
const comparisonItemSchema = z.strictObject({
|
||||
item_id: z.string().regex(/^javc_item_[a-f0-9]{64}$/u),
|
||||
status: z.enum(["unchanged", "added", "removed", "changed", "unknown"]),
|
||||
node_kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
|
||||
left_node_id: nodeIdSchema.nullable(),
|
||||
right_node_id: nodeIdSchema.nullable(),
|
||||
match: z.strictObject({
|
||||
status: z.enum(["matched", "unmatched", "ambiguous"]),
|
||||
basis: applicationVersionMatchBasisSchema,
|
||||
confidence: z.enum(["exact", "high", "medium", "unknown"]),
|
||||
candidate_left_node_ids: z.array(nodeIdSchema).max(1_000),
|
||||
candidate_right_node_ids: z.array(nodeIdSchema).max(1_000),
|
||||
}),
|
||||
dimensions: z
|
||||
.array(
|
||||
z.enum([
|
||||
"content",
|
||||
"location",
|
||||
"properties",
|
||||
"relationships",
|
||||
"availability",
|
||||
"coverage",
|
||||
]),
|
||||
)
|
||||
.max(6),
|
||||
evidence_links: z.array(evidenceIdSchema).min(2).max(130),
|
||||
limitations: z.array(boundedTextSchema).max(100),
|
||||
});
|
||||
|
||||
/** Tiered module/entity matching plus a bounded cross-version change graph. */
|
||||
export const applicationVersionComparisonResultSchema = z.strictObject({
|
||||
schema_version: z.literal(1),
|
||||
comparison_id: z.string().regex(/^javc_[a-f0-9]{64}$/u),
|
||||
left: z.strictObject({
|
||||
evidence_id: evidenceIdSchema,
|
||||
graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
|
||||
root_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
|
||||
}),
|
||||
right: z.strictObject({
|
||||
evidence_id: evidenceIdSchema,
|
||||
graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
|
||||
root_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
|
||||
}),
|
||||
summary: z.strictObject({
|
||||
unchanged: z.number().int().min(0),
|
||||
added: z.number().int().min(0),
|
||||
removed: z.number().int().min(0),
|
||||
changed: z.number().int().min(0),
|
||||
unknown: z.number().int().min(0),
|
||||
}),
|
||||
matching: z.strictObject({
|
||||
exact_node_identity: z.number().int().min(0),
|
||||
exact_content_digest: z.number().int().min(0),
|
||||
exact_module_source_digest: z.number().int().min(0),
|
||||
source_map_identity: z.number().int().min(0),
|
||||
structural_fingerprint: z.number().int().min(0),
|
||||
semantic_key: z.number().int().min(0),
|
||||
ambiguous: z.number().int().min(0),
|
||||
unmatched: z.number().int().min(0),
|
||||
}),
|
||||
items: z.array(comparisonItemSchema).max(50_000),
|
||||
graph: javascriptApplicationGraphSchema,
|
||||
coverage: z.strictObject({
|
||||
status: z.enum(["complete-within-inputs", "partial", "truncated"]),
|
||||
left_graph_status: z.enum([
|
||||
"complete",
|
||||
"partial",
|
||||
"unknown",
|
||||
"unavailable",
|
||||
]),
|
||||
right_graph_status: z.enum([
|
||||
"complete",
|
||||
"partial",
|
||||
"unknown",
|
||||
"unavailable",
|
||||
]),
|
||||
omitted_comparison_items: z.number().int().min(0),
|
||||
omitted_candidate_references: z.number().int().min(0),
|
||||
omitted_graph_nodes: z.number().int().min(0),
|
||||
omitted_graph_edges: z.number().int().min(0),
|
||||
omitted_graph_observations: z.number().int().min(0),
|
||||
}),
|
||||
evidence_links: z.array(evidenceIdSchema).min(2).max(130),
|
||||
limitations: z.array(boundedTextSchema).max(1_000),
|
||||
});
|
||||
|
||||
export type CompareApplicationVersionsInput = z.infer<
|
||||
typeof compareApplicationVersionsInputSchema
|
||||
>;
|
||||
export type ApplicationVersionComparisonItem = z.infer<
|
||||
typeof comparisonItemSchema
|
||||
>;
|
||||
export type ApplicationVersionComparisonResult = z.infer<
|
||||
typeof applicationVersionComparisonResultSchema
|
||||
>;
|
||||
export type ApplicationVersionMatchBasis = z.infer<
|
||||
typeof applicationVersionMatchBasisSchema
|
||||
>;
|
||||
@@ -0,0 +1,371 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import canonicalize from "canonicalize";
|
||||
|
||||
import type { Evidence } from "./evidence.js";
|
||||
import {
|
||||
compareCodePoints,
|
||||
type ApplicationEdge,
|
||||
type ApplicationNode,
|
||||
type JavaScriptApplicationGraph,
|
||||
} from "./javascriptApplicationGraph.js";
|
||||
import type {
|
||||
ApplicationVersionComparisonItem,
|
||||
CompareApplicationVersionsInput,
|
||||
} from "./javascriptApplicationVersionComparisonSchemas.js";
|
||||
import type {
|
||||
ApplicationVersionMatchingProjection,
|
||||
ApplicationVersionNodePair,
|
||||
} from "./javascriptApplicationVersionKeys.js";
|
||||
|
||||
/** All classified entities before the caller's item bound is applied. */
|
||||
export interface ApplicationVersionItemProjection {
|
||||
readonly items: ApplicationVersionComparisonItem[];
|
||||
readonly omittedCandidateReferences: number;
|
||||
}
|
||||
|
||||
interface ItemContext {
|
||||
readonly leftGraph: JavaScriptApplicationGraph;
|
||||
readonly rightGraph: JavaScriptApplicationGraph;
|
||||
readonly leftEvidenceId: string;
|
||||
readonly rightEvidenceId: string;
|
||||
readonly leftNativeEvidence: readonly Evidence[];
|
||||
readonly rightNativeEvidence: readonly Evidence[];
|
||||
readonly pairByLeft: ReadonlyMap<string, string>;
|
||||
readonly pairByRight: ReadonlyMap<string, string>;
|
||||
readonly maxCandidates: number;
|
||||
}
|
||||
|
||||
/** Classify matched, unmatched, and ambiguous nodes without inventing absence. */
|
||||
export const classifyJavaScriptApplicationVersions = (
|
||||
matching: ApplicationVersionMatchingProjection,
|
||||
context: Omit<ItemContext, "pairByLeft" | "pairByRight" | "maxCandidates"> & {
|
||||
readonly maxCandidates: CompareApplicationVersionsInput["limits"]["max_candidate_nodes"];
|
||||
},
|
||||
): ApplicationVersionItemProjection => {
|
||||
const pairByLeft = new Map(
|
||||
matching.pairs.map(({ left, right }) => [
|
||||
left.node_id,
|
||||
`pair:${left.node_id}:${right.node_id}`,
|
||||
]),
|
||||
);
|
||||
const pairByRight = new Map(
|
||||
matching.pairs.map(({ left, right }) => [
|
||||
right.node_id,
|
||||
`pair:${left.node_id}:${right.node_id}`,
|
||||
]),
|
||||
);
|
||||
const fullContext: ItemContext = { ...context, pairByLeft, pairByRight };
|
||||
let omittedCandidateReferences = 0;
|
||||
const leftItems = matching.unmatchedLeft.map((node) => {
|
||||
const candidates = matching.candidatesForLeft.get(node.node_id) ?? [];
|
||||
omittedCandidateReferences += Math.max(
|
||||
0,
|
||||
candidates.length - context.maxCandidates,
|
||||
);
|
||||
return unmatchedItem(
|
||||
node,
|
||||
"left",
|
||||
candidates.slice(0, context.maxCandidates),
|
||||
fullContext,
|
||||
);
|
||||
});
|
||||
const rightItems = matching.unmatchedRight.map((node) => {
|
||||
const candidates = matching.candidatesForRight.get(node.node_id) ?? [];
|
||||
omittedCandidateReferences += Math.max(
|
||||
0,
|
||||
candidates.length - context.maxCandidates,
|
||||
);
|
||||
return unmatchedItem(
|
||||
node,
|
||||
"right",
|
||||
candidates.slice(0, context.maxCandidates),
|
||||
fullContext,
|
||||
);
|
||||
});
|
||||
return {
|
||||
items: [
|
||||
...matching.pairs.map((pair) => matchedItem(pair, fullContext)),
|
||||
...leftItems,
|
||||
...rightItems,
|
||||
].sort((left, right) => compareCodePoints(left.item_id, right.item_id)),
|
||||
omittedCandidateReferences,
|
||||
};
|
||||
};
|
||||
|
||||
const matchedItem = (
|
||||
pair: ApplicationVersionNodePair,
|
||||
context: ItemContext,
|
||||
): ApplicationVersionComparisonItem => {
|
||||
const dimensions = changedDimensions(pair, context);
|
||||
const complete = graphsComplete(context);
|
||||
const observedChange = dimensions.some((dimension) =>
|
||||
["content", "location", "properties"].includes(dimension),
|
||||
);
|
||||
const status: ApplicationVersionComparisonItem["status"] =
|
||||
observedChange || (complete && dimensions.length > 0)
|
||||
? "changed"
|
||||
: complete
|
||||
? "unchanged"
|
||||
: "unknown";
|
||||
const finalDimensions =
|
||||
status === "unknown" && !dimensions.includes("coverage")
|
||||
? [...dimensions, "coverage" as const]
|
||||
: dimensions;
|
||||
const semantic = {
|
||||
status,
|
||||
node_kind: pair.left.kind,
|
||||
left_node_id: pair.left.node_id,
|
||||
right_node_id: pair.right.node_id,
|
||||
match: {
|
||||
status: "matched" as const,
|
||||
basis: pair.basis,
|
||||
confidence: pair.confidence,
|
||||
candidate_left_node_ids: [],
|
||||
candidate_right_node_ids: [],
|
||||
},
|
||||
dimensions: finalDimensions,
|
||||
evidence_links: itemEvidenceLinks(pair.left, pair.right, context),
|
||||
limitations: pairLimitations(pair, status),
|
||||
};
|
||||
return itemWithId(semantic);
|
||||
};
|
||||
|
||||
const unmatchedItem = (
|
||||
node: ApplicationNode,
|
||||
side: "left" | "right",
|
||||
candidates: readonly string[],
|
||||
context: ItemContext,
|
||||
): ApplicationVersionComparisonItem => {
|
||||
const ambiguous = candidates.length > 0;
|
||||
const oppositeComplete =
|
||||
(side === "left" ? context.rightGraph : context.leftGraph).coverage
|
||||
.status === "complete";
|
||||
const status: ApplicationVersionComparisonItem["status"] = ambiguous
|
||||
? "unknown"
|
||||
: oppositeComplete
|
||||
? side === "left"
|
||||
? "removed"
|
||||
: "added"
|
||||
: "unknown";
|
||||
const semantic = {
|
||||
status,
|
||||
node_kind: node.kind,
|
||||
left_node_id: side === "left" ? node.node_id : null,
|
||||
right_node_id: side === "right" ? node.node_id : null,
|
||||
match: {
|
||||
status: ambiguous ? ("ambiguous" as const) : ("unmatched" as const),
|
||||
basis: "none" as const,
|
||||
confidence: "unknown" as const,
|
||||
candidate_left_node_ids: side === "right" ? [...candidates] : [],
|
||||
candidate_right_node_ids: side === "left" ? [...candidates] : [],
|
||||
},
|
||||
dimensions: [
|
||||
"availability" as const,
|
||||
...(status === "unknown" && !ambiguous ? (["coverage"] as const) : []),
|
||||
],
|
||||
evidence_links: itemEvidenceLinks(
|
||||
side === "left" ? node : undefined,
|
||||
side === "right" ? node : undefined,
|
||||
context,
|
||||
),
|
||||
limitations: [
|
||||
...(ambiguous
|
||||
? [
|
||||
"Multiple nodes share the same permitted match key; no cross-version pair was selected.",
|
||||
]
|
||||
: []),
|
||||
...(status === "unknown" && !ambiguous
|
||||
? [
|
||||
"The opposite graph is incomplete, so an unmatched node cannot be classified as added or removed.",
|
||||
]
|
||||
: []),
|
||||
],
|
||||
};
|
||||
return itemWithId(semantic);
|
||||
};
|
||||
|
||||
const changedDimensions = (
|
||||
pair: ApplicationVersionNodePair,
|
||||
context: ItemContext,
|
||||
): ApplicationVersionComparisonItem["dimensions"] => {
|
||||
const dimensions: ApplicationVersionComparisonItem["dimensions"] = [];
|
||||
const leftContent = contentIdentity(pair.left);
|
||||
const rightContent = contentIdentity(pair.right);
|
||||
if (
|
||||
leftContent !== null &&
|
||||
rightContent !== null &&
|
||||
leftContent !== rightContent
|
||||
)
|
||||
dimensions.push("content");
|
||||
if (canonical(locations(pair.left)) !== canonical(locations(pair.right)))
|
||||
dimensions.push("location");
|
||||
if (canonical(properties(pair.left)) !== canonical(properties(pair.right)))
|
||||
dimensions.push("properties");
|
||||
if (
|
||||
relationshipSignature(pair.left, "left", context) !==
|
||||
relationshipSignature(pair.right, "right", context)
|
||||
)
|
||||
dimensions.push("relationships");
|
||||
return dimensions;
|
||||
};
|
||||
|
||||
const contentIdentity = (node: ApplicationNode): string | null => {
|
||||
if (node.identity.strategy === "content-digest")
|
||||
return `content:${node.identity.sha256}`;
|
||||
if (node.kind === "javascript-module")
|
||||
return stringProperty(node, "source_sha256");
|
||||
if (
|
||||
node.kind === "source-module" &&
|
||||
node.identity.strategy === "source-map-original"
|
||||
)
|
||||
return node.identity.source_sha256;
|
||||
return null;
|
||||
};
|
||||
|
||||
const locations = (node: ApplicationNode) =>
|
||||
node.observations
|
||||
.map(({ evidence }) =>
|
||||
evidence.location.available ? evidence.location.value : evidence.location,
|
||||
)
|
||||
.sort((left, right) =>
|
||||
compareCodePoints(canonical(left), canonical(right)),
|
||||
);
|
||||
|
||||
const properties = (node: ApplicationNode) =>
|
||||
node.observations
|
||||
.map(({ label, properties: values }) => ({ label, properties: values }))
|
||||
.sort((left, right) =>
|
||||
compareCodePoints(canonical(left), canonical(right)),
|
||||
);
|
||||
|
||||
const relationshipSignature = (
|
||||
node: ApplicationNode,
|
||||
side: "left" | "right",
|
||||
context: ItemContext,
|
||||
): string => {
|
||||
const graph = side === "left" ? context.leftGraph : context.rightGraph;
|
||||
const paired = side === "left" ? context.pairByLeft : context.pairByRight;
|
||||
const nodeById = new Map(graph.nodes.map((value) => [value.node_id, value]));
|
||||
const signatures = graph.edges.flatMap((edge) => {
|
||||
if (edge.source_node_id === node.node_id)
|
||||
return [
|
||||
edgeSignature(
|
||||
"out",
|
||||
edge.relation,
|
||||
edge.target_node_id,
|
||||
paired,
|
||||
nodeById,
|
||||
),
|
||||
];
|
||||
if (edge.target_node_id === node.node_id)
|
||||
return [
|
||||
edgeSignature(
|
||||
"in",
|
||||
edge.relation,
|
||||
edge.source_node_id,
|
||||
paired,
|
||||
nodeById,
|
||||
),
|
||||
];
|
||||
return [];
|
||||
});
|
||||
return canonical(signatures.sort(compareCodePoints));
|
||||
};
|
||||
|
||||
const edgeSignature = (
|
||||
direction: "in" | "out",
|
||||
relation: ApplicationEdge["relation"],
|
||||
neighborId: string,
|
||||
paired: ReadonlyMap<string, string>,
|
||||
nodeById: ReadonlyMap<string, ApplicationNode>,
|
||||
): string => {
|
||||
const mapped = paired.get(neighborId);
|
||||
const neighbor = nodeById.get(neighborId);
|
||||
return `${direction}\0${relation}\0${mapped ?? `unmatched:${neighbor?.kind ?? "unknown"}`}`;
|
||||
};
|
||||
|
||||
const itemEvidenceLinks = (
|
||||
left: ApplicationNode | undefined,
|
||||
right: ApplicationNode | undefined,
|
||||
context: ItemContext,
|
||||
): string[] =>
|
||||
[
|
||||
...new Set([
|
||||
context.leftEvidenceId,
|
||||
context.rightEvidenceId,
|
||||
...nativeLinks(left, context.leftNativeEvidence),
|
||||
...nativeLinks(right, context.rightNativeEvidence),
|
||||
]),
|
||||
].sort(compareCodePoints);
|
||||
|
||||
const nativeLinks = (
|
||||
node: ApplicationNode | undefined,
|
||||
evidence: readonly Evidence[],
|
||||
): string[] => {
|
||||
const digest =
|
||||
node === undefined
|
||||
? null
|
||||
: contentIdentity(node)?.replace(/^content:/u, "");
|
||||
return digest === null
|
||||
? []
|
||||
: evidence
|
||||
.filter(({ subject }) => subject?.digest.sha256 === digest)
|
||||
.map(({ evidence_id: id }) => id);
|
||||
};
|
||||
|
||||
const pairLimitations = (
|
||||
pair: ApplicationVersionNodePair,
|
||||
status: ApplicationVersionComparisonItem["status"],
|
||||
): string[] => [
|
||||
...(pair.basis === "structural-fingerprint"
|
||||
? [
|
||||
"Structural fingerprint equality is rename-resistant inference; it is not byte identity or proof of semantic equivalence.",
|
||||
]
|
||||
: []),
|
||||
...(pair.basis === "source-map-identity"
|
||||
? [
|
||||
"Source-map original names identify a candidate source lineage; changed or unavailable source content remains explicit.",
|
||||
]
|
||||
: []),
|
||||
...(pair.basis === "semantic-key"
|
||||
? [
|
||||
"Semantic-key pairing is a deterministic inference and is never promoted to exact identity.",
|
||||
]
|
||||
: []),
|
||||
...(status === "unknown"
|
||||
? ["Incomplete graph coverage prevents a complete node-level conclusion."]
|
||||
: []),
|
||||
];
|
||||
|
||||
const itemWithId = (
|
||||
semantic: Omit<ApplicationVersionComparisonItem, "item_id">,
|
||||
): ApplicationVersionComparisonItem => ({
|
||||
...semantic,
|
||||
item_id: `javc_item_${digestCanonical(semantic)}`,
|
||||
});
|
||||
|
||||
const stringProperty = (node: ApplicationNode, key: string): string | null => {
|
||||
const values = [
|
||||
...new Set(
|
||||
node.observations
|
||||
.map(({ properties: values }) => values[key])
|
||||
.filter((value): value is string => typeof value === "string"),
|
||||
),
|
||||
];
|
||||
return values.length === 1 ? (values[0] ?? null) : null;
|
||||
};
|
||||
|
||||
const graphsComplete = (context: ItemContext): boolean =>
|
||||
context.leftGraph.coverage.status === "complete" &&
|
||||
context.rightGraph.coverage.status === "complete";
|
||||
|
||||
const canonical = (value: unknown): string => {
|
||||
const encoded = canonicalize(value);
|
||||
if (encoded === undefined)
|
||||
throw new TypeError("Application version item could not canonicalize data");
|
||||
return encoded;
|
||||
};
|
||||
|
||||
const digestCanonical = (value: unknown): string =>
|
||||
createHash("sha256").update(canonical(value)).digest("hex");
|
||||
@@ -0,0 +1,273 @@
|
||||
import type { ApplicationNode } from "./javascriptApplicationGraph.js";
|
||||
import { compareCodePoints } from "./javascriptApplicationGraph.js";
|
||||
import type { ApplicationVersionMatchBasis } from "./javascriptApplicationVersionComparisonSchemas.js";
|
||||
import type { JsonValue } from "./jsonValue.js";
|
||||
|
||||
/** One deterministic one-to-one match between two graph versions. */
|
||||
export interface ApplicationVersionNodePair {
|
||||
readonly left: ApplicationNode;
|
||||
readonly right: ApplicationNode;
|
||||
readonly basis: Exclude<ApplicationVersionMatchBasis, "none">;
|
||||
readonly confidence: "exact" | "high" | "medium";
|
||||
}
|
||||
|
||||
/** Matched nodes plus ambiguity candidates that were never forced into pairs. */
|
||||
export interface ApplicationVersionMatchingProjection {
|
||||
readonly pairs: ApplicationVersionNodePair[];
|
||||
readonly unmatchedLeft: ApplicationNode[];
|
||||
readonly unmatchedRight: ApplicationNode[];
|
||||
readonly candidatesForLeft: ReadonlyMap<string, readonly string[]>;
|
||||
readonly candidatesForRight: ReadonlyMap<string, readonly string[]>;
|
||||
}
|
||||
|
||||
interface MatchTier {
|
||||
readonly basis: ApplicationVersionNodePair["basis"];
|
||||
readonly confidence: ApplicationVersionNodePair["confidence"];
|
||||
readonly key: (node: ApplicationNode) => string | null;
|
||||
}
|
||||
|
||||
const matchTiers = (): readonly MatchTier[] => [
|
||||
{ basis: "exact-content-digest", confidence: "exact", key: contentDigestKey },
|
||||
{
|
||||
basis: "exact-module-source-digest",
|
||||
confidence: "exact",
|
||||
key: moduleSourceDigestKey,
|
||||
},
|
||||
{ basis: "exact-node-identity", confidence: "exact", key: nodeIdentityKey },
|
||||
{ basis: "source-map-identity", confidence: "high", key: sourceMapKey },
|
||||
{
|
||||
basis: "structural-fingerprint",
|
||||
confidence: "medium",
|
||||
key: structuralFingerprintKey,
|
||||
},
|
||||
{ basis: "semantic-key", confidence: "medium", key: semanticKey },
|
||||
];
|
||||
|
||||
/** Apply ordered, unique-only matching tiers without fuzzy pairing. */
|
||||
export const matchJavaScriptApplicationVersions = (
|
||||
leftNodes: readonly ApplicationNode[],
|
||||
rightNodes: readonly ApplicationNode[],
|
||||
): ApplicationVersionMatchingProjection => {
|
||||
const left = new Map(leftNodes.map((node) => [node.node_id, node]));
|
||||
const right = new Map(rightNodes.map((node) => [node.node_id, node]));
|
||||
const leftCandidates = new Map<string, Set<string>>();
|
||||
const rightCandidates = new Map<string, Set<string>>();
|
||||
const pairs: ApplicationVersionNodePair[] = [];
|
||||
for (const tier of matchTiers())
|
||||
applyTier(left, right, pairs, leftCandidates, rightCandidates, tier);
|
||||
const remainingLeft = sortedNodes(left.values());
|
||||
const remainingRight = sortedNodes(right.values());
|
||||
const leftIds = new Set(remainingLeft.map(({ node_id: id }) => id));
|
||||
const rightIds = new Set(remainingRight.map(({ node_id: id }) => id));
|
||||
return {
|
||||
pairs: pairs.sort((a, b) =>
|
||||
compareCodePoints(
|
||||
`${a.left.node_id}\0${a.right.node_id}`,
|
||||
`${b.left.node_id}\0${b.right.node_id}`,
|
||||
),
|
||||
),
|
||||
unmatchedLeft: remainingLeft,
|
||||
unmatchedRight: remainingRight,
|
||||
candidatesForLeft: filteredCandidates(leftCandidates, rightIds),
|
||||
candidatesForRight: filteredCandidates(rightCandidates, leftIds),
|
||||
};
|
||||
};
|
||||
|
||||
const applyTier = (
|
||||
left: Map<string, ApplicationNode>,
|
||||
right: Map<string, ApplicationNode>,
|
||||
pairs: ApplicationVersionNodePair[],
|
||||
leftCandidates: Map<string, Set<string>>,
|
||||
rightCandidates: Map<string, Set<string>>,
|
||||
tier: MatchTier,
|
||||
): void => {
|
||||
const leftByKey = nodesByKey(left.values(), tier.key);
|
||||
const rightByKey = nodesByKey(right.values(), tier.key);
|
||||
for (const key of [...leftByKey.keys()].sort(compareCodePoints)) {
|
||||
const leftGroup = leftByKey.get(key) ?? [];
|
||||
const rightGroup = rightByKey.get(key) ?? [];
|
||||
if (rightGroup.length === 0) continue;
|
||||
recordCandidates(leftGroup, rightGroup, leftCandidates, rightCandidates);
|
||||
if (leftGroup.length !== 1 || rightGroup.length !== 1) continue;
|
||||
const leftNode = leftGroup[0];
|
||||
const rightNode = rightGroup[0];
|
||||
if (leftNode === undefined || rightNode === undefined) continue;
|
||||
pairs.push({ left: leftNode, right: rightNode, ...tier });
|
||||
left.delete(leftNode.node_id);
|
||||
right.delete(rightNode.node_id);
|
||||
}
|
||||
};
|
||||
|
||||
const nodesByKey = (
|
||||
nodes: Iterable<ApplicationNode>,
|
||||
keyFor: (node: ApplicationNode) => string | null,
|
||||
): Map<string, ApplicationNode[]> => {
|
||||
const output = new Map<string, ApplicationNode[]>();
|
||||
for (const node of nodes) {
|
||||
const key = keyFor(node);
|
||||
if (key === null) continue;
|
||||
output.set(key, [...(output.get(key) ?? []), node]);
|
||||
}
|
||||
return output;
|
||||
};
|
||||
|
||||
const recordCandidates = (
|
||||
left: readonly ApplicationNode[],
|
||||
right: readonly ApplicationNode[],
|
||||
leftCandidates: Map<string, Set<string>>,
|
||||
rightCandidates: Map<string, Set<string>>,
|
||||
): void => {
|
||||
for (const leftNode of left) {
|
||||
const candidates =
|
||||
leftCandidates.get(leftNode.node_id) ?? new Set<string>();
|
||||
for (const rightNode of right) candidates.add(rightNode.node_id);
|
||||
leftCandidates.set(leftNode.node_id, candidates);
|
||||
}
|
||||
for (const rightNode of right) {
|
||||
const candidates =
|
||||
rightCandidates.get(rightNode.node_id) ?? new Set<string>();
|
||||
for (const leftNode of left) candidates.add(leftNode.node_id);
|
||||
rightCandidates.set(rightNode.node_id, candidates);
|
||||
}
|
||||
};
|
||||
|
||||
const filteredCandidates = (
|
||||
candidates: ReadonlyMap<string, ReadonlySet<string>>,
|
||||
retained: ReadonlySet<string>,
|
||||
): ReadonlyMap<string, readonly string[]> =>
|
||||
new Map(
|
||||
[...candidates.entries()].flatMap(([nodeId, values]) => {
|
||||
const filtered = [...values]
|
||||
.filter((value) => retained.has(value))
|
||||
.sort(compareCodePoints);
|
||||
return filtered.length === 0 ? [] : [[nodeId, filtered] as const];
|
||||
}),
|
||||
);
|
||||
|
||||
const nodeIdentityKey = (node: ApplicationNode): string =>
|
||||
`node\0${node.kind}\0${node.node_id}`;
|
||||
|
||||
const contentDigestKey = (node: ApplicationNode): string | null =>
|
||||
node.identity.strategy === "content-digest"
|
||||
? `content\0${node.kind}\0${node.identity.sha256}`
|
||||
: null;
|
||||
|
||||
const moduleSourceDigestKey = (node: ApplicationNode): string | null => {
|
||||
if (node.kind !== "javascript-module") return null;
|
||||
const value = uniqueStringProperty(node, "source_sha256");
|
||||
return value === null ? null : `module-source\0${node.kind}\0${value}`;
|
||||
};
|
||||
|
||||
const sourceMapKey = (node: ApplicationNode): string | null =>
|
||||
node.kind === "source-module" &&
|
||||
node.identity.strategy === "source-map-original"
|
||||
? `source-map\0${node.identity.original_source}`
|
||||
: null;
|
||||
|
||||
const structuralFingerprintKey = (node: ApplicationNode): string | null => {
|
||||
if (node.kind !== "javascript-module") return null;
|
||||
const digest = uniqueStringProperty(node, "structural_fingerprint_sha256");
|
||||
const algorithm = uniqueStringProperty(
|
||||
node,
|
||||
"structural_fingerprint_algorithm",
|
||||
);
|
||||
const status = uniqueStringProperty(node, "structural_fingerprint_status");
|
||||
return digest === null || algorithm === null || status !== "complete"
|
||||
? null
|
||||
: `structural\0${node.kind}\0${algorithm}\0${digest}`;
|
||||
};
|
||||
|
||||
const semanticKey = (node: ApplicationNode): string | null => {
|
||||
if (
|
||||
[
|
||||
"javascript-module",
|
||||
"javascript-chunk",
|
||||
"runtime-script-instance",
|
||||
"unknown",
|
||||
].includes(node.kind)
|
||||
)
|
||||
return null;
|
||||
const properties = firstProperties(node);
|
||||
const value = semanticValue(node, properties);
|
||||
return value === null ? null : `semantic\0${node.kind}\0${value}`;
|
||||
};
|
||||
|
||||
const semanticValue = (
|
||||
node: ApplicationNode,
|
||||
properties: Readonly<Record<string, JsonValue>>,
|
||||
): string | null => {
|
||||
if (node.kind === "endpoint")
|
||||
return joined(properties.endpoint_kind, properties.value);
|
||||
if (node.kind === "storage")
|
||||
return joined(
|
||||
properties.storage_kind,
|
||||
properties.name ?? properties.mechanism,
|
||||
);
|
||||
if (node.kind === "ipc-channel")
|
||||
return properties.resolution === "dynamic"
|
||||
? null
|
||||
: (stringValue(properties.channel) ?? firstLabel(node));
|
||||
if (node.kind === "context-bridge-api")
|
||||
return firstLabel(node) ?? stringValue(properties.api_name);
|
||||
if (node.kind === "native-export")
|
||||
return (
|
||||
joined(
|
||||
properties.specifier,
|
||||
stringList(properties.requested_members).join(","),
|
||||
) ?? firstLabel(node)
|
||||
);
|
||||
if (
|
||||
[
|
||||
"electron-main",
|
||||
"electron-preload",
|
||||
"electron-renderer",
|
||||
"electron-utility",
|
||||
].includes(node.kind)
|
||||
)
|
||||
return joined(properties.declared_path, properties.resolved_path);
|
||||
if (node.kind === "package") return stringValue(properties.name);
|
||||
return canonicalPath(node) ?? stringValue(properties.path);
|
||||
};
|
||||
|
||||
const canonicalPath = (node: ApplicationNode): string | null =>
|
||||
node.identity.strategy === "canonical-path" ? node.identity.path : null;
|
||||
|
||||
const firstProperties = (node: ApplicationNode) =>
|
||||
node.observations[0]?.properties ?? {};
|
||||
|
||||
const firstLabel = (node: ApplicationNode): string | null =>
|
||||
node.observations.find(({ label }) => label !== null)?.label ?? null;
|
||||
|
||||
const uniqueStringProperty = (
|
||||
node: ApplicationNode,
|
||||
name: string,
|
||||
): string | null => {
|
||||
const values = [
|
||||
...new Set(
|
||||
node.observations
|
||||
.map(({ properties }) => properties[name])
|
||||
.filter((value): value is string => typeof value === "string"),
|
||||
),
|
||||
];
|
||||
return values.length === 1 ? (values[0] ?? null) : null;
|
||||
};
|
||||
|
||||
const joined = (...values: readonly unknown[]): string | null => {
|
||||
const strings = values.map(stringValue);
|
||||
return strings.some((value) => value === null) ? null : strings.join("\0");
|
||||
};
|
||||
|
||||
const stringValue = (value: unknown): string | null =>
|
||||
typeof value === "string" && value !== "" ? value : null;
|
||||
|
||||
const stringList = (value: unknown): string[] =>
|
||||
Array.isArray(value)
|
||||
? value
|
||||
.filter((item): item is string => typeof item === "string")
|
||||
.sort(compareCodePoints)
|
||||
: [];
|
||||
|
||||
const sortedNodes = (nodes: Iterable<ApplicationNode>): ApplicationNode[] =>
|
||||
[...nodes].sort((left, right) =>
|
||||
compareCodePoints(left.node_id, right.node_id),
|
||||
);
|
||||
@@ -0,0 +1,191 @@
|
||||
import type { ApplicationNode } from "./javascriptApplicationGraph.js";
|
||||
import { compareCodePoints } from "./javascriptApplicationGraph.js";
|
||||
import type { ApplicationFeatureSeed } from "./javascriptFeatureTraceSchemas.js";
|
||||
import type { JsonValue } from "./jsonValue.js";
|
||||
|
||||
/** One explicit field that matched a feature seed. */
|
||||
export interface ApplicationFeatureSeedMatch {
|
||||
readonly node_id: string;
|
||||
readonly kind: ApplicationNode["kind"];
|
||||
readonly basis: "node-id" | "label" | "identity" | "property";
|
||||
readonly field: string;
|
||||
}
|
||||
|
||||
interface CandidateField {
|
||||
readonly basis: ApplicationFeatureSeedMatch["basis"];
|
||||
readonly field: string;
|
||||
readonly value: string;
|
||||
}
|
||||
|
||||
/** Locate every graph node matching a typed literal seed without regex execution. */
|
||||
export const findApplicationFeatureSeeds = (
|
||||
nodes: readonly ApplicationNode[],
|
||||
seed: ApplicationFeatureSeed,
|
||||
): ApplicationFeatureSeedMatch[] =>
|
||||
nodes
|
||||
.flatMap((node) => seedMatch(node, seed))
|
||||
.sort((left, right) =>
|
||||
compareCodePoints(
|
||||
`${left.node_id}\0${left.basis}\0${left.field}`,
|
||||
`${right.node_id}\0${right.basis}\0${right.field}`,
|
||||
),
|
||||
);
|
||||
|
||||
const seedMatch = (
|
||||
node: ApplicationNode,
|
||||
seed: ApplicationFeatureSeed,
|
||||
): ApplicationFeatureSeedMatch[] => {
|
||||
if (seed.kind === "node-id")
|
||||
return node.node_id === seed.value
|
||||
? [
|
||||
{
|
||||
node_id: node.node_id,
|
||||
kind: node.kind,
|
||||
basis: "node-id",
|
||||
field: "node_id",
|
||||
},
|
||||
]
|
||||
: [];
|
||||
if (!kindMatches(node, seed.kind)) return [];
|
||||
const mode = seed.match ?? (seed.kind === "string" ? "contains" : "exact");
|
||||
const query = normalized(seed.value, seed.case_sensitive);
|
||||
const match = candidateFields(node, seed.kind).find((candidate) => {
|
||||
const value = normalized(candidate.value, seed.case_sensitive);
|
||||
return mode === "exact" ? value === query : value.includes(query);
|
||||
});
|
||||
return match === undefined
|
||||
? []
|
||||
: [
|
||||
{
|
||||
node_id: node.node_id,
|
||||
kind: node.kind,
|
||||
basis: match.basis,
|
||||
field: match.field,
|
||||
},
|
||||
];
|
||||
};
|
||||
|
||||
const kindMatches = (
|
||||
node: ApplicationNode,
|
||||
kind: Exclude<ApplicationFeatureSeed["kind"], "node-id">,
|
||||
): boolean => {
|
||||
if (kind === "string") return true;
|
||||
if (kind === "route")
|
||||
return (
|
||||
node.kind === "endpoint" &&
|
||||
node.observations.some(
|
||||
({ properties }) => properties.endpoint_kind === "route",
|
||||
)
|
||||
);
|
||||
if (kind === "api") return node.kind === "context-bridge-api";
|
||||
if (kind === "channel") return node.kind === "ipc-channel";
|
||||
if (kind === "module")
|
||||
return ["javascript-asset", "javascript-module", "source-module"].includes(
|
||||
node.kind,
|
||||
);
|
||||
return node.kind === "native-export";
|
||||
};
|
||||
|
||||
const candidateFields = (
|
||||
node: ApplicationNode,
|
||||
seedKind: Exclude<ApplicationFeatureSeed["kind"], "node-id">,
|
||||
): CandidateField[] => {
|
||||
const fields: CandidateField[] = [
|
||||
...identityFields(node),
|
||||
...node.observations.flatMap((observation, index) => [
|
||||
...(observation.label === null
|
||||
? []
|
||||
: [
|
||||
{
|
||||
basis: "label" as const,
|
||||
field: `observations[${String(index)}].label`,
|
||||
value: observation.label,
|
||||
},
|
||||
]),
|
||||
...propertyFields(
|
||||
observation.properties,
|
||||
`observations[${String(index)}].properties`,
|
||||
),
|
||||
]),
|
||||
];
|
||||
if (seedKind === "string") return fields;
|
||||
const names = relevantFields[seedKind];
|
||||
return fields.filter(({ field }) =>
|
||||
names.some((name) => field === "identity" || field.endsWith(name)),
|
||||
);
|
||||
};
|
||||
|
||||
const relevantFields = {
|
||||
route: [".label", ".value", ".path"],
|
||||
api: [".label", ".api_name", ".key", ".methods", ".members"],
|
||||
channel: [".label", ".channel", ".key"],
|
||||
module: [
|
||||
".label",
|
||||
".module_key",
|
||||
".path",
|
||||
".source",
|
||||
".original_source",
|
||||
".exports",
|
||||
],
|
||||
"native-export": [".label", ".key", ".requested_members", ".members"],
|
||||
} as const;
|
||||
|
||||
const identityFields = (node: ApplicationNode): CandidateField[] => {
|
||||
const identity = node.identity;
|
||||
if (identity.strategy === "content-digest")
|
||||
return [{ basis: "identity", field: "identity", value: identity.sha256 }];
|
||||
if (identity.strategy === "source-map-original")
|
||||
return [
|
||||
{
|
||||
basis: "identity",
|
||||
field: "identity.original_source",
|
||||
value: identity.original_source,
|
||||
},
|
||||
];
|
||||
if (identity.strategy === "canonical-path")
|
||||
return [
|
||||
{ basis: "identity", field: "identity.path", value: identity.path },
|
||||
];
|
||||
if (identity.strategy === "artifact-local-key")
|
||||
return [{ basis: "identity", field: "identity.key", value: identity.key }];
|
||||
if (identity.strategy === "runtime-instance")
|
||||
return [
|
||||
{
|
||||
basis: "identity",
|
||||
field: "identity.runtime_key",
|
||||
value: identity.runtime_key,
|
||||
},
|
||||
];
|
||||
return [];
|
||||
};
|
||||
|
||||
const propertyFields = (
|
||||
value: Readonly<Record<string, JsonValue>>,
|
||||
prefix: string,
|
||||
): CandidateField[] => {
|
||||
const output: CandidateField[] = [];
|
||||
const visit = (current: JsonValue, path: string, depth: number): void => {
|
||||
if (output.length >= 512 || depth > 6) return;
|
||||
if (typeof current === "string") {
|
||||
output.push({ basis: "property", field: path, value: current });
|
||||
return;
|
||||
}
|
||||
if (Array.isArray(current)) {
|
||||
for (const [index, item] of current.entries())
|
||||
visit(item, `${path}[${String(index)}]`, depth + 1);
|
||||
return;
|
||||
}
|
||||
if (current !== null && typeof current === "object")
|
||||
for (const key of Object.keys(current).sort(compareCodePoints))
|
||||
visit(current[key] ?? null, `${path}.${key}`, depth + 1);
|
||||
};
|
||||
visit(value, prefix, 0);
|
||||
return output;
|
||||
};
|
||||
|
||||
const normalized = (value: string, caseSensitive: boolean): string => {
|
||||
const normalizedValue = value.normalize("NFKC");
|
||||
return caseSensitive
|
||||
? normalizedValue
|
||||
: normalizedValue.toLocaleLowerCase("en-US");
|
||||
};
|
||||
@@ -0,0 +1,349 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import canonicalize from "canonicalize";
|
||||
|
||||
import type { Evidence } from "./evidence.js";
|
||||
import {
|
||||
compareCodePoints,
|
||||
createJavaScriptApplicationGraph,
|
||||
type ApplicationEdge,
|
||||
type ApplicationNode,
|
||||
type JavaScriptApplicationGraph,
|
||||
} from "./javascriptApplicationGraph.js";
|
||||
import {
|
||||
applicationFeatureTraceResultSchema,
|
||||
type ApplicationFeatureTraceResult,
|
||||
type TraceApplicationFeatureInput,
|
||||
} from "./javascriptFeatureTraceSchemas.js";
|
||||
import {
|
||||
findApplicationFeatureSeeds,
|
||||
type ApplicationFeatureSeedMatch,
|
||||
} from "./javascriptFeatureSeed.js";
|
||||
import {
|
||||
traverseApplicationFeature,
|
||||
type ApplicationFeatureTraversal,
|
||||
} from "./javascriptFeatureTraversal.js";
|
||||
import { buildJavaScriptNativeHandoffs } from "./javascriptNativeHandoff.js";
|
||||
|
||||
/** Pure, authenticated inputs projected by the application service. */
|
||||
export interface ApplicationFeatureTraceProjectionInput {
|
||||
readonly sourceEvidenceId: string;
|
||||
readonly graph: JavaScriptApplicationGraph;
|
||||
readonly nativeEvidence: readonly Evidence[];
|
||||
readonly seed: TraceApplicationFeatureInput["seed"];
|
||||
readonly direction: TraceApplicationFeatureInput["direction"];
|
||||
readonly limits: TraceApplicationFeatureInput["limits"];
|
||||
}
|
||||
|
||||
/** Trace a literal feature through a bounded, authority-preserving JAG. */
|
||||
export const traceApplicationFeature = (
|
||||
input: ApplicationFeatureTraceProjectionInput,
|
||||
): ApplicationFeatureTraceResult => {
|
||||
const allSeedMatches = findApplicationFeatureSeeds(
|
||||
input.graph.nodes,
|
||||
input.seed,
|
||||
);
|
||||
const seedMatches = allSeedMatches.slice(0, input.limits.max_seed_matches);
|
||||
if (seedMatches.length === 0) return noMatchResult(input);
|
||||
const traversal = traverseApplicationFeature(
|
||||
input.graph,
|
||||
seedMatches.map(({ node_id: id }) => id),
|
||||
input.direction,
|
||||
input.limits,
|
||||
);
|
||||
const graph = traceGraph(
|
||||
input,
|
||||
seedMatches,
|
||||
traversal,
|
||||
allSeedMatches.length,
|
||||
);
|
||||
const allPaths = terminalPaths(traversal, seedMatches);
|
||||
const paths = allPaths.slice(0, input.limits.max_paths);
|
||||
const nativeHandoffs = buildJavaScriptNativeHandoffs(
|
||||
traversal.nodes,
|
||||
traversal.edges,
|
||||
input.nativeEvidence,
|
||||
);
|
||||
const evidenceLinks = uniqueSorted([
|
||||
input.sourceEvidenceId,
|
||||
...nativeHandoffs.flatMap(({ evidence_ids: ids }) => ids),
|
||||
]);
|
||||
const omissions = traceOmissions(
|
||||
input,
|
||||
traversal,
|
||||
allSeedMatches.length,
|
||||
allPaths.length,
|
||||
);
|
||||
const semantic = {
|
||||
schema_version: 1 as const,
|
||||
source_evidence_id: input.sourceEvidenceId,
|
||||
source_graph_id: input.graph.graph_id,
|
||||
seed: input.seed,
|
||||
direction: input.direction,
|
||||
seed_matches: seedMatches,
|
||||
graph,
|
||||
paths,
|
||||
native_handoffs: nativeHandoffs,
|
||||
summary: {
|
||||
matched_seeds: seedMatches.length,
|
||||
traced_nodes: traversal.nodes.length,
|
||||
traced_edges: traversal.edges.length,
|
||||
terminal_paths: paths.length,
|
||||
native_handoffs: nativeHandoffs.length,
|
||||
...factSummary(traversal.nodes, traversal.edges),
|
||||
},
|
||||
coverage: {
|
||||
status: traceCoverageStatus(input.graph, omissions),
|
||||
source_graph_status: input.graph.coverage.status,
|
||||
scanned_nodes: input.graph.nodes.length,
|
||||
total_seed_matches: allSeedMatches.length,
|
||||
...omissions,
|
||||
frontier_node_ids: traversal.frontierNodeIds,
|
||||
},
|
||||
evidence_links: evidenceLinks,
|
||||
limitations: traceLimitations(input.graph, omissions),
|
||||
};
|
||||
return applicationFeatureTraceResultSchema.parse({
|
||||
...semantic,
|
||||
trace_id: `jatr_${digestCanonical(semantic)}`,
|
||||
});
|
||||
};
|
||||
|
||||
const noMatchResult = (
|
||||
input: ApplicationFeatureTraceProjectionInput,
|
||||
): ApplicationFeatureTraceResult => {
|
||||
const semantic = {
|
||||
schema_version: 1 as const,
|
||||
source_evidence_id: input.sourceEvidenceId,
|
||||
source_graph_id: input.graph.graph_id,
|
||||
seed: input.seed,
|
||||
direction: input.direction,
|
||||
seed_matches: [],
|
||||
graph: null,
|
||||
paths: [],
|
||||
native_handoffs: [],
|
||||
summary: {
|
||||
matched_seeds: 0,
|
||||
traced_nodes: 0,
|
||||
traced_edges: 0,
|
||||
terminal_paths: 0,
|
||||
native_handoffs: 0,
|
||||
observed_facts: 0,
|
||||
inferred_facts: 0,
|
||||
unknown_facts: 0,
|
||||
unavailable_facts: 0,
|
||||
},
|
||||
coverage: {
|
||||
status: "no-match" as const,
|
||||
source_graph_status: input.graph.coverage.status,
|
||||
scanned_nodes: input.graph.nodes.length,
|
||||
total_seed_matches: 0,
|
||||
omitted_seed_matches: 0,
|
||||
omitted_nodes: 0,
|
||||
omitted_edges: 0,
|
||||
omitted_paths: 0,
|
||||
frontier_node_ids: [],
|
||||
},
|
||||
evidence_links: [input.sourceEvidenceId],
|
||||
limitations: uniqueSorted([
|
||||
"No graph entity matched the literal seed; this is not evidence that the feature is absent.",
|
||||
...sourceCoverageLimitations(input.graph),
|
||||
]),
|
||||
};
|
||||
return applicationFeatureTraceResultSchema.parse({
|
||||
...semantic,
|
||||
trace_id: `jatr_${digestCanonical(semantic)}`,
|
||||
});
|
||||
};
|
||||
|
||||
const traceGraph = (
|
||||
input: ApplicationFeatureTraceProjectionInput,
|
||||
seedMatches: readonly ApplicationFeatureSeedMatch[],
|
||||
traversal: ApplicationFeatureTraversal,
|
||||
totalSeedMatches: number,
|
||||
): JavaScriptApplicationGraph => {
|
||||
const omitted =
|
||||
traversal.omittedNodeCount +
|
||||
traversal.omittedEdgeCount +
|
||||
(totalSeedMatches - seedMatches.length);
|
||||
return createJavaScriptApplicationGraph({
|
||||
schema: "JavaScriptApplicationGraph",
|
||||
schema_version: 1,
|
||||
root_node_ids: uniqueSorted(seedMatches.map(({ node_id: id }) => id)),
|
||||
nodes: traversal.nodes,
|
||||
edges: traversal.edges,
|
||||
coverage: traceGraphCoverage(input.graph, input.limits, omitted),
|
||||
limitations: uniqueSorted([
|
||||
...input.graph.limitations,
|
||||
"Trace edges retain their source authority; graph connectivity does not prove runtime execution or reachability.",
|
||||
...(omitted === 0
|
||||
? []
|
||||
: ["Trace output stopped at explicit caller bounds."]),
|
||||
]),
|
||||
});
|
||||
};
|
||||
|
||||
const traceGraphCoverage = (
|
||||
source: JavaScriptApplicationGraph,
|
||||
limits: TraceApplicationFeatureInput["limits"],
|
||||
omitted: number,
|
||||
): JavaScriptApplicationGraph["coverage"] => {
|
||||
if (omitted > 0)
|
||||
return {
|
||||
status: "partial",
|
||||
truncated: true,
|
||||
omitted_count: omitted,
|
||||
limits: [
|
||||
{
|
||||
name: "max-seed-matches",
|
||||
value: limits.max_seed_matches,
|
||||
unit: "items",
|
||||
},
|
||||
{ name: "max-depth", value: limits.max_depth, unit: "depth" },
|
||||
{ name: "max-nodes", value: limits.max_nodes, unit: "items" },
|
||||
{ name: "max-edges", value: limits.max_edges, unit: "items" },
|
||||
],
|
||||
};
|
||||
return source.coverage.status === "complete"
|
||||
? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
|
||||
: {
|
||||
status: source.coverage.status,
|
||||
truncated: source.coverage.truncated,
|
||||
omitted_count: source.coverage.omitted_count,
|
||||
limits: source.coverage.limits,
|
||||
};
|
||||
};
|
||||
|
||||
const terminalPaths = (
|
||||
traversal: ApplicationFeatureTraversal,
|
||||
seeds: readonly ApplicationFeatureSeedMatch[],
|
||||
): ApplicationFeatureTraceResult["paths"] => {
|
||||
const seedIds = new Set(seeds.map(({ node_id: id }) => id));
|
||||
const edgeById = new Map(traversal.edges.map((edge) => [edge.edge_id, edge]));
|
||||
return traversal.nodes
|
||||
.filter(
|
||||
(node) =>
|
||||
isTerminal(node) &&
|
||||
(!seedIds.has(node.node_id) || traversal.nodes.length === 1),
|
||||
)
|
||||
.map((node) => pathTo(node, traversal.predecessors, edgeById))
|
||||
.filter((path): path is NonNullable<typeof path> => path !== null)
|
||||
.sort((left, right) => compareCodePoints(left.path_id, right.path_id));
|
||||
};
|
||||
|
||||
const pathTo = (
|
||||
node: ApplicationNode,
|
||||
predecessors: ApplicationFeatureTraversal["predecessors"],
|
||||
edgeById: ReadonlyMap<string, ApplicationEdge>,
|
||||
): ApplicationFeatureTraceResult["paths"][number] | null => {
|
||||
const nodeIds = [node.node_id];
|
||||
const edgeIds: string[] = [];
|
||||
let current = node.node_id;
|
||||
while (predecessors.has(current)) {
|
||||
const predecessor = predecessors.get(current);
|
||||
if (predecessor === undefined) break;
|
||||
nodeIds.push(predecessor.previousNodeId);
|
||||
edgeIds.push(predecessor.edgeId);
|
||||
current = predecessor.previousNodeId;
|
||||
}
|
||||
nodeIds.reverse();
|
||||
edgeIds.reverse();
|
||||
const edges = edgeIds
|
||||
.map((edgeId) => edgeById.get(edgeId))
|
||||
.filter((edge): edge is ApplicationEdge => edge !== undefined);
|
||||
if (edges.length !== edgeIds.length) return null;
|
||||
const semantic = {
|
||||
start_node_id: nodeIds[0] ?? node.node_id,
|
||||
end_node_id: node.node_id,
|
||||
end_kind: node.kind,
|
||||
node_ids: nodeIds,
|
||||
edge_ids: edgeIds,
|
||||
authorities: uniqueSorted(edges.map(({ evidence }) => evidence.authority)),
|
||||
contains_inference: edges.some(
|
||||
({ evidence }) => evidence.state === "inferred",
|
||||
),
|
||||
};
|
||||
return { ...semantic, path_id: `jatp_${digestCanonical(semantic)}` };
|
||||
};
|
||||
|
||||
const isTerminal = (node: ApplicationNode): boolean =>
|
||||
["endpoint", "storage", "native-addon", "native-export", "unknown"].includes(
|
||||
node.kind,
|
||||
);
|
||||
|
||||
const factSummary = (
|
||||
nodes: readonly ApplicationNode[],
|
||||
edges: readonly ApplicationEdge[],
|
||||
) => {
|
||||
const states = [
|
||||
...nodes.flatMap(({ observations }) =>
|
||||
observations.map(({ evidence }) => evidence.state),
|
||||
),
|
||||
...edges.map(({ evidence }) => evidence.state),
|
||||
];
|
||||
return {
|
||||
observed_facts: states.filter((state) => state === "observed").length,
|
||||
inferred_facts: states.filter((state) => state === "inferred").length,
|
||||
unknown_facts: states.filter((state) => state === "unknown").length,
|
||||
unavailable_facts: states.filter((state) => state === "unavailable").length,
|
||||
};
|
||||
};
|
||||
|
||||
const traceOmissions = (
|
||||
input: ApplicationFeatureTraceProjectionInput,
|
||||
traversal: ApplicationFeatureTraversal,
|
||||
seedMatches: number,
|
||||
paths: number,
|
||||
) => ({
|
||||
omitted_seed_matches: Math.max(
|
||||
0,
|
||||
seedMatches - input.limits.max_seed_matches,
|
||||
),
|
||||
omitted_nodes: traversal.omittedNodeCount,
|
||||
omitted_edges: traversal.omittedEdgeCount,
|
||||
omitted_paths: Math.max(0, paths - input.limits.max_paths),
|
||||
});
|
||||
|
||||
const traceCoverageStatus = (
|
||||
graph: JavaScriptApplicationGraph,
|
||||
omissions: ReturnType<typeof traceOmissions>,
|
||||
): ApplicationFeatureTraceResult["coverage"]["status"] =>
|
||||
Object.values(omissions).some((value) => value > 0)
|
||||
? "truncated"
|
||||
: graph.coverage.status === "complete"
|
||||
? "complete-within-source"
|
||||
: "partial";
|
||||
|
||||
const traceLimitations = (
|
||||
graph: JavaScriptApplicationGraph,
|
||||
omissions: ReturnType<typeof traceOmissions>,
|
||||
): string[] =>
|
||||
uniqueSorted([
|
||||
"A trace reports graph relationships, not proof that code executed or that a feature is reachable in every state.",
|
||||
"Static, native, passive-runtime, inferred, and unknown facts retain their original authority in the returned graph.",
|
||||
"Native handoffs never open a binary or invoke a provider automatically; snapshot reuse remains provider/profile/target exact.",
|
||||
...sourceCoverageLimitations(graph),
|
||||
...(Object.values(omissions).some((value) => value > 0)
|
||||
? ["Trace results were truncated at explicit caller limits."]
|
||||
: []),
|
||||
]);
|
||||
|
||||
const sourceCoverageLimitations = (
|
||||
graph: JavaScriptApplicationGraph,
|
||||
): string[] =>
|
||||
graph.coverage.status === "complete"
|
||||
? []
|
||||
: [
|
||||
"The source application graph is incomplete; unmatched seeds and frontiers remain unknown.",
|
||||
];
|
||||
|
||||
const digestCanonical = (value: unknown): string => {
|
||||
const encoded = canonicalize(value);
|
||||
if (encoded === undefined)
|
||||
throw new TypeError("Feature trace could not canonicalize data");
|
||||
return createHash("sha256").update(encoded).digest("hex");
|
||||
};
|
||||
|
||||
const uniqueSorted = <Value extends string>(
|
||||
values: readonly Value[],
|
||||
): Value[] => [...new Set(values)].sort(compareCodePoints);
|
||||
@@ -0,0 +1,157 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import { evidenceSchema, providerSchema } from "./evidence.js";
|
||||
import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
|
||||
|
||||
const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
|
||||
const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
|
||||
const nodeIdSchema = z.string().regex(/^jag_node_[a-f0-9]{64}$/u);
|
||||
const edgeIdSchema = z.string().regex(/^jag_edge_[a-f0-9]{64}$/u);
|
||||
const boundedTextSchema = z.string().min(1).max(4_096);
|
||||
|
||||
/** Literal starting point for one bounded application trace. */
|
||||
const applicationFeatureSeedSchema = z.strictObject({
|
||||
kind: z.enum([
|
||||
"node-id",
|
||||
"route",
|
||||
"string",
|
||||
"api",
|
||||
"channel",
|
||||
"module",
|
||||
"native-export",
|
||||
]),
|
||||
value: boundedTextSchema,
|
||||
match: z.enum(["exact", "contains"]).nullable().default(null),
|
||||
case_sensitive: z.boolean().default(false),
|
||||
});
|
||||
|
||||
const featureTraceLimitsSchema = z.strictObject({
|
||||
max_seed_matches: z.number().int().min(1).max(1_000).default(25),
|
||||
max_depth: z.number().int().min(0).max(64).default(12),
|
||||
max_nodes: z.number().int().min(1).max(50_000).default(2_000),
|
||||
max_edges: z.number().int().min(1).max(100_000).default(4_000),
|
||||
max_paths: z.number().int().min(1).max(1_000).default(100),
|
||||
});
|
||||
|
||||
/** Evidence-backed application graph and explicit trace bounds. */
|
||||
export const traceApplicationFeatureInputSchema = z
|
||||
.strictObject({
|
||||
application: evidenceSchema,
|
||||
native_observations: z.array(evidenceSchema).max(64).default([]),
|
||||
seed: applicationFeatureSeedSchema,
|
||||
direction: z.enum(["outgoing", "incoming", "both"]).default("both"),
|
||||
limits: featureTraceLimitsSchema.default({
|
||||
max_seed_matches: 25,
|
||||
max_depth: 12,
|
||||
max_nodes: 2_000,
|
||||
max_edges: 4_000,
|
||||
max_paths: 100,
|
||||
}),
|
||||
})
|
||||
.superRefine((input, context) => {
|
||||
const ids = input.native_observations.map(({ evidence_id: id }) => id);
|
||||
if (new Set(ids).size !== ids.length)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["native_observations"],
|
||||
message: "Native observations must be unique",
|
||||
});
|
||||
});
|
||||
|
||||
const seedMatchSchema = z.strictObject({
|
||||
node_id: nodeIdSchema,
|
||||
kind: z.string().min(1).max(128),
|
||||
basis: z.enum(["node-id", "label", "identity", "property"]),
|
||||
field: z.string().min(1).max(256),
|
||||
});
|
||||
|
||||
const tracePathSchema = z.strictObject({
|
||||
path_id: z.string().regex(/^jatp_[a-f0-9]{64}$/u),
|
||||
start_node_id: nodeIdSchema,
|
||||
end_node_id: nodeIdSchema,
|
||||
end_kind: z.string().min(1).max(128),
|
||||
node_ids: z.array(nodeIdSchema).min(1).max(65),
|
||||
edge_ids: z.array(edgeIdSchema).max(64),
|
||||
authorities: z.array(z.string().min(1).max(128)).max(16),
|
||||
contains_inference: z.boolean(),
|
||||
});
|
||||
|
||||
const nativeHandoffSchema = z.strictObject({
|
||||
native_node_id: nodeIdSchema,
|
||||
artifact_sha256: digestSchema,
|
||||
artifact_path: z.string().min(1).max(4_096).nullable(),
|
||||
export_node_ids: z.array(nodeIdSchema).max(1_000),
|
||||
requested_exports: z.array(boundedTextSchema).max(1_000),
|
||||
status: z.enum(["evidence-linked", "requires-provider-analysis"]),
|
||||
providers: z.array(providerSchema).max(64),
|
||||
evidence_ids: z.array(evidenceIdSchema).max(64),
|
||||
recommended_tools: z
|
||||
.array(
|
||||
z.enum([
|
||||
"open_binary",
|
||||
"binary_overview",
|
||||
"search_procedures",
|
||||
"analyze_function",
|
||||
"xrefs",
|
||||
]),
|
||||
)
|
||||
.max(5),
|
||||
});
|
||||
|
||||
/** Evidence-preserving bounded subgraph and native-analysis frontiers. */
|
||||
export const applicationFeatureTraceResultSchema = z.strictObject({
|
||||
schema_version: z.literal(1),
|
||||
trace_id: z.string().regex(/^jatr_[a-f0-9]{64}$/u),
|
||||
source_evidence_id: evidenceIdSchema,
|
||||
source_graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
|
||||
seed: applicationFeatureSeedSchema,
|
||||
direction: z.enum(["outgoing", "incoming", "both"]),
|
||||
seed_matches: z.array(seedMatchSchema).max(1_000),
|
||||
graph: javascriptApplicationGraphSchema.nullable(),
|
||||
paths: z.array(tracePathSchema).max(1_000),
|
||||
native_handoffs: z.array(nativeHandoffSchema).max(10_000),
|
||||
summary: z.strictObject({
|
||||
matched_seeds: z.number().int().min(0),
|
||||
traced_nodes: z.number().int().min(0),
|
||||
traced_edges: z.number().int().min(0),
|
||||
terminal_paths: z.number().int().min(0),
|
||||
native_handoffs: z.number().int().min(0),
|
||||
observed_facts: z.number().int().min(0),
|
||||
inferred_facts: z.number().int().min(0),
|
||||
unknown_facts: z.number().int().min(0),
|
||||
unavailable_facts: z.number().int().min(0),
|
||||
}),
|
||||
coverage: z.strictObject({
|
||||
status: z.enum([
|
||||
"complete-within-source",
|
||||
"partial",
|
||||
"truncated",
|
||||
"no-match",
|
||||
]),
|
||||
source_graph_status: z.enum([
|
||||
"complete",
|
||||
"partial",
|
||||
"unknown",
|
||||
"unavailable",
|
||||
]),
|
||||
scanned_nodes: z.number().int().min(0),
|
||||
total_seed_matches: z.number().int().min(0),
|
||||
omitted_seed_matches: z.number().int().min(0),
|
||||
omitted_nodes: z.number().int().min(0),
|
||||
omitted_edges: z.number().int().min(0),
|
||||
omitted_paths: z.number().int().min(0),
|
||||
frontier_node_ids: z.array(nodeIdSchema).max(50_000),
|
||||
}),
|
||||
evidence_links: z.array(evidenceIdSchema).min(1).max(65),
|
||||
limitations: z.array(boundedTextSchema).max(1_000),
|
||||
});
|
||||
|
||||
export type TraceApplicationFeatureInput = z.infer<
|
||||
typeof traceApplicationFeatureInputSchema
|
||||
>;
|
||||
export type ApplicationFeatureSeed = z.infer<
|
||||
typeof applicationFeatureSeedSchema
|
||||
>;
|
||||
export type ApplicationFeatureTraceResult = z.infer<
|
||||
typeof applicationFeatureTraceResultSchema
|
||||
>;
|
||||
@@ -0,0 +1,143 @@
|
||||
import {
|
||||
compareCodePoints,
|
||||
type ApplicationEdge,
|
||||
type ApplicationNode,
|
||||
type JavaScriptApplicationGraph,
|
||||
} from "./javascriptApplicationGraph.js";
|
||||
import type { TraceApplicationFeatureInput } from "./javascriptFeatureTraceSchemas.js";
|
||||
|
||||
interface AdjacencyEntry {
|
||||
readonly edge: ApplicationEdge;
|
||||
readonly nextNodeId: string;
|
||||
}
|
||||
|
||||
interface Predecessor {
|
||||
readonly previousNodeId: string;
|
||||
readonly edgeId: string;
|
||||
}
|
||||
|
||||
/** Bounded graph projection plus the first deterministic path to each node. */
|
||||
export interface ApplicationFeatureTraversal {
|
||||
readonly nodes: ApplicationNode[];
|
||||
readonly edges: ApplicationEdge[];
|
||||
readonly depths: ReadonlyMap<string, number>;
|
||||
readonly predecessors: ReadonlyMap<string, Predecessor>;
|
||||
readonly frontierNodeIds: string[];
|
||||
readonly omittedNodeCount: number;
|
||||
readonly omittedEdgeCount: number;
|
||||
}
|
||||
|
||||
/** Traverse a JAG without treating edge inference as observed reachability. */
|
||||
export const traverseApplicationFeature = (
|
||||
graph: JavaScriptApplicationGraph,
|
||||
seedNodeIds: readonly string[],
|
||||
direction: TraceApplicationFeatureInput["direction"],
|
||||
limits: TraceApplicationFeatureInput["limits"],
|
||||
): ApplicationFeatureTraversal => {
|
||||
const nodeById = new Map(graph.nodes.map((node) => [node.node_id, node]));
|
||||
const adjacency = buildAdjacency(graph.edges, direction);
|
||||
const visited = new Set(seedNodeIds);
|
||||
const retainedEdges = new Map<string, ApplicationEdge>();
|
||||
const omittedNodes = new Set<string>();
|
||||
const omittedEdges = new Set<string>();
|
||||
const frontier = new Set<string>();
|
||||
const depths = new Map(seedNodeIds.map((nodeId) => [nodeId, 0]));
|
||||
const predecessors = new Map<string, Predecessor>();
|
||||
const queue = [...seedNodeIds];
|
||||
for (let offset = 0; offset < queue.length; offset += 1) {
|
||||
const current = queue[offset];
|
||||
if (current === undefined) continue;
|
||||
const depth = depths.get(current) ?? 0;
|
||||
for (const entry of adjacency.get(current) ?? []) {
|
||||
if (depth >= limits.max_depth) {
|
||||
recordOmission(entry, current, omittedNodes, omittedEdges, frontier);
|
||||
continue;
|
||||
}
|
||||
if (!visited.has(entry.nextNodeId) && visited.size >= limits.max_nodes) {
|
||||
recordOmission(entry, current, omittedNodes, omittedEdges, frontier);
|
||||
continue;
|
||||
}
|
||||
if (
|
||||
!retainedEdges.has(entry.edge.edge_id) &&
|
||||
retainedEdges.size >= limits.max_edges
|
||||
) {
|
||||
omittedEdges.add(entry.edge.edge_id);
|
||||
frontier.add(current);
|
||||
frontier.add(entry.nextNodeId);
|
||||
continue;
|
||||
}
|
||||
retainedEdges.set(entry.edge.edge_id, entry.edge);
|
||||
if (visited.has(entry.nextNodeId)) continue;
|
||||
if (!nodeById.has(entry.nextNodeId)) continue;
|
||||
visited.add(entry.nextNodeId);
|
||||
depths.set(entry.nextNodeId, depth + 1);
|
||||
predecessors.set(entry.nextNodeId, {
|
||||
previousNodeId: current,
|
||||
edgeId: entry.edge.edge_id,
|
||||
});
|
||||
queue.push(entry.nextNodeId);
|
||||
}
|
||||
}
|
||||
return {
|
||||
nodes: [...visited]
|
||||
.map((nodeId) => nodeById.get(nodeId))
|
||||
.filter((node): node is ApplicationNode => node !== undefined)
|
||||
.sort((left, right) => compareCodePoints(left.node_id, right.node_id)),
|
||||
edges: [...retainedEdges.values()].sort((left, right) =>
|
||||
compareCodePoints(left.edge_id, right.edge_id),
|
||||
),
|
||||
depths,
|
||||
predecessors,
|
||||
frontierNodeIds: [...frontier].sort(compareCodePoints),
|
||||
omittedNodeCount: omittedNodes.size,
|
||||
omittedEdgeCount: omittedEdges.size,
|
||||
};
|
||||
};
|
||||
|
||||
const buildAdjacency = (
|
||||
edges: readonly ApplicationEdge[],
|
||||
direction: TraceApplicationFeatureInput["direction"],
|
||||
): ReadonlyMap<string, AdjacencyEntry[]> => {
|
||||
const adjacency = new Map<string, AdjacencyEntry[]>();
|
||||
for (const edge of edges) {
|
||||
if (direction !== "incoming")
|
||||
addAdjacency(adjacency, edge.source_node_id, {
|
||||
edge,
|
||||
nextNodeId: edge.target_node_id,
|
||||
});
|
||||
if (direction !== "outgoing")
|
||||
addAdjacency(adjacency, edge.target_node_id, {
|
||||
edge,
|
||||
nextNodeId: edge.source_node_id,
|
||||
});
|
||||
}
|
||||
for (const entries of adjacency.values())
|
||||
entries.sort((left, right) =>
|
||||
compareCodePoints(
|
||||
`${left.edge.edge_id}\0${left.nextNodeId}`,
|
||||
`${right.edge.edge_id}\0${right.nextNodeId}`,
|
||||
),
|
||||
);
|
||||
return adjacency;
|
||||
};
|
||||
|
||||
const addAdjacency = (
|
||||
adjacency: Map<string, AdjacencyEntry[]>,
|
||||
nodeId: string,
|
||||
entry: AdjacencyEntry,
|
||||
): void => {
|
||||
adjacency.set(nodeId, [...(adjacency.get(nodeId) ?? []), entry]);
|
||||
};
|
||||
|
||||
const recordOmission = (
|
||||
entry: AdjacencyEntry,
|
||||
current: string,
|
||||
omittedNodes: Set<string>,
|
||||
omittedEdges: Set<string>,
|
||||
frontier: Set<string>,
|
||||
): void => {
|
||||
omittedNodes.add(entry.nextNodeId);
|
||||
omittedEdges.add(entry.edge.edge_id);
|
||||
frontier.add(current);
|
||||
frontier.add(entry.nextNodeId);
|
||||
};
|
||||
@@ -0,0 +1,132 @@
|
||||
import type { Evidence } from "./evidence.js";
|
||||
import {
|
||||
compareCodePoints,
|
||||
type ApplicationEdge,
|
||||
type ApplicationNode,
|
||||
} from "./javascriptApplicationGraph.js";
|
||||
import type { ApplicationFeatureTraceResult } from "./javascriptFeatureTraceSchemas.js";
|
||||
|
||||
type NativeHandoff = ApplicationFeatureTraceResult["native_handoffs"][number];
|
||||
|
||||
/** Build provider-neutral addon targets and link exact-subject native Evidence. */
|
||||
export const buildJavaScriptNativeHandoffs = (
|
||||
nodes: readonly ApplicationNode[],
|
||||
edges: readonly ApplicationEdge[],
|
||||
nativeEvidence: readonly Evidence[],
|
||||
): NativeHandoff[] => {
|
||||
const nodeById = new Map(nodes.map((node) => [node.node_id, node]));
|
||||
return nodes
|
||||
.filter(({ kind }) => kind === "native-addon")
|
||||
.flatMap((node) => {
|
||||
const digest = artifactDigest(node);
|
||||
if (digest === null) return [];
|
||||
const linked = nativeEvidence.filter(
|
||||
({ subject }) => subject?.digest.sha256 === digest,
|
||||
);
|
||||
const exportNodes = nativeExportNodes(node, edges, nodeById);
|
||||
return [
|
||||
{
|
||||
native_node_id: node.node_id,
|
||||
artifact_sha256: digest,
|
||||
artifact_path: artifactPath(node),
|
||||
export_node_ids: exportNodes.map(({ node_id: id }) => id),
|
||||
requested_exports: requestedExports(exportNodes),
|
||||
status:
|
||||
linked.length === 0
|
||||
? ("requires-provider-analysis" as const)
|
||||
: ("evidence-linked" as const),
|
||||
providers: uniqueProviders(linked),
|
||||
evidence_ids: linked
|
||||
.map(({ evidence_id: id }) => id)
|
||||
.sort(compareCodePoints),
|
||||
recommended_tools: [
|
||||
"open_binary" as const,
|
||||
"binary_overview" as const,
|
||||
"search_procedures" as const,
|
||||
"analyze_function" as const,
|
||||
"xrefs" as const,
|
||||
],
|
||||
},
|
||||
];
|
||||
})
|
||||
.sort((left, right) =>
|
||||
compareCodePoints(left.native_node_id, right.native_node_id),
|
||||
);
|
||||
};
|
||||
|
||||
const artifactDigest = (node: ApplicationNode): string | null => {
|
||||
if (node.identity.strategy === "content-digest") return node.identity.sha256;
|
||||
const observation = node.observations.find(
|
||||
({ evidence }) => evidence.artifact.available,
|
||||
);
|
||||
return observation?.evidence.artifact.available === true
|
||||
? observation.evidence.artifact.sha256
|
||||
: null;
|
||||
};
|
||||
|
||||
const artifactPath = (node: ApplicationNode): string | null => {
|
||||
for (const { evidence } of node.observations)
|
||||
if (
|
||||
evidence.location.available &&
|
||||
evidence.location.value.kind === "artifact-path"
|
||||
)
|
||||
return evidence.location.value.path;
|
||||
return null;
|
||||
};
|
||||
|
||||
const nativeExportNodes = (
|
||||
addon: ApplicationNode,
|
||||
edges: readonly ApplicationEdge[],
|
||||
nodeById: ReadonlyMap<string, ApplicationNode>,
|
||||
): ApplicationNode[] => {
|
||||
const ids = edges.flatMap((edge) => {
|
||||
if (
|
||||
edge.source_node_id === addon.node_id &&
|
||||
["contains", "exposes"].includes(edge.relation)
|
||||
)
|
||||
return [edge.target_node_id];
|
||||
if (
|
||||
edge.target_node_id === addon.node_id &&
|
||||
["imports", "loads"].includes(edge.relation)
|
||||
)
|
||||
return [edge.source_node_id];
|
||||
return [];
|
||||
});
|
||||
return [...new Set(ids)]
|
||||
.map((id) => nodeById.get(id))
|
||||
.filter((node): node is ApplicationNode => node?.kind === "native-export")
|
||||
.sort((left, right) => compareCodePoints(left.node_id, right.node_id));
|
||||
};
|
||||
|
||||
const requestedExports = (nodes: readonly ApplicationNode[]): string[] => {
|
||||
const values = nodes.flatMap((node) =>
|
||||
node.observations.flatMap((observation) => [
|
||||
...(observation.label === null ? [] : [observation.label]),
|
||||
...stringArray(observation.properties.requested_members),
|
||||
...stringArray(observation.properties.members),
|
||||
]),
|
||||
);
|
||||
return [...new Set(values)].sort(compareCodePoints).slice(0, 1_000);
|
||||
};
|
||||
|
||||
const stringArray = (value: unknown): string[] =>
|
||||
Array.isArray(value)
|
||||
? value.filter((item): item is string => typeof item === "string")
|
||||
: [];
|
||||
|
||||
const uniqueProviders = (
|
||||
evidence: readonly Evidence[],
|
||||
): NativeHandoff["providers"] =>
|
||||
[
|
||||
...new Map(
|
||||
evidence.map(({ provider }) => [
|
||||
`${provider.id}\0${provider.name}\0${provider.version ?? ""}`,
|
||||
provider,
|
||||
]),
|
||||
).values(),
|
||||
].sort((left, right) =>
|
||||
compareCodePoints(
|
||||
`${left.id}\0${left.name}\0${left.version ?? ""}`,
|
||||
`${right.id}\0${right.name}\0${right.version ?? ""}`,
|
||||
),
|
||||
);
|
||||
@@ -5,5 +5,5 @@ export const PACKAGE_METADATA = {
|
||||
serverSdkVersion: "2.0.0-beta.4",
|
||||
clientSdkVersion: "2.0.0-beta.4",
|
||||
coreSdkVersion: "2.0.0-beta.4",
|
||||
skillVersion: "16",
|
||||
skillVersion: "17",
|
||||
} as const;
|
||||
|
||||
@@ -19,6 +19,7 @@ import type { BrowserObservationPort } from "../application/BrowserObservationPo
|
||||
import { registerBrowserTools } from "./registerBrowserTools.js";
|
||||
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
|
||||
import { registerElectronTools } from "./registerElectronTools.js";
|
||||
import { registerApplicationTools } from "./registerApplicationTools.js";
|
||||
|
||||
export interface CreateServerOptions {
|
||||
readonly logger?: Logger;
|
||||
@@ -113,6 +114,17 @@ export const createServer = (
|
||||
server.sendResourceListChanged();
|
||||
return recorded;
|
||||
};
|
||||
const recordEvidenceWithUnknown =
|
||||
session === undefined
|
||||
? undefined
|
||||
: (
|
||||
evidence: Parameters<typeof session.recordEvidenceWithUnknown>[0],
|
||||
input: Parameters<typeof session.recordEvidenceWithUnknown>[1],
|
||||
) => {
|
||||
const recorded = session.recordEvidenceWithUnknown(evidence, input);
|
||||
if (recorded.ok) server.sendResourceListChanged();
|
||||
return recorded;
|
||||
};
|
||||
registerOfficialTools(server, analysis, {
|
||||
logger: toolLogger,
|
||||
activeTarget,
|
||||
@@ -158,6 +170,11 @@ export const createServer = (
|
||||
permissionAuthority: options.permissionAuthority,
|
||||
recordEvidence,
|
||||
});
|
||||
registerApplicationTools(server, {
|
||||
logger: toolLogger,
|
||||
recordEvidence,
|
||||
recordEvidenceWithUnknown,
|
||||
});
|
||||
registerGuidedPrompts(server, analysis, session);
|
||||
if (session !== undefined) {
|
||||
registerEvidenceResources(server, session);
|
||||
|
||||
@@ -0,0 +1,131 @@
|
||||
import type { McpServer } from "@modelcontextprotocol/server";
|
||||
|
||||
import type { BinarySessionPort } from "../application/BinarySession.js";
|
||||
import {
|
||||
compareApplicationVersionsEvidence,
|
||||
traceApplicationFeatureEvidence,
|
||||
} from "../application/JavaScriptApplicationWorkflowService.js";
|
||||
import { APPLICATION_TOOL_CONTRACTS } from "../contracts/applicationToolContracts.js";
|
||||
import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
|
||||
import { applicationVersionComparisonResultSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
|
||||
import { traceApplicationFeatureInputSchema } from "../domain/javascriptFeatureTraceSchemas.js";
|
||||
import type { Evidence } from "../domain/evidence.js";
|
||||
import type { Logger } from "../logger.js";
|
||||
import { logToolExecution } from "./toolLogging.js";
|
||||
import { toCallToolResult } from "./toolResult.js";
|
||||
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
|
||||
|
||||
interface ApplicationToolRegistration {
|
||||
readonly logger: Logger;
|
||||
readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
|
||||
readonly recordEvidenceWithUnknown:
|
||||
| BinarySessionPort["recordEvidenceWithUnknown"]
|
||||
| undefined;
|
||||
}
|
||||
|
||||
/** Register provider-neutral JavaScript application graph workflows. */
|
||||
export const registerApplicationTools = (
|
||||
server: McpServer,
|
||||
options: ApplicationToolRegistration,
|
||||
): void => {
|
||||
const [traceContract, compareContract] = APPLICATION_TOOL_CONTRACTS;
|
||||
server.registerTool(
|
||||
traceContract.name,
|
||||
toolRegistrationOptions(traceContract),
|
||||
async (input) => {
|
||||
const parsed = traceApplicationFeatureInputSchema.parse(input);
|
||||
const result = await logToolExecution(
|
||||
options.logger,
|
||||
traceContract.name,
|
||||
() => Promise.resolve(traceApplicationFeatureEvidence(parsed)),
|
||||
);
|
||||
if (!result.ok) return toCallToolResult(result, traceContract);
|
||||
const sources = [parsed.application, ...parsed.native_observations];
|
||||
const recorded = recordSources(options.recordEvidence, sources);
|
||||
if (!recorded.ok) return toCallToolResult(recorded, traceContract);
|
||||
return recordResult(options, traceContract, result.value);
|
||||
},
|
||||
);
|
||||
server.registerTool(
|
||||
compareContract.name,
|
||||
toolRegistrationOptions(compareContract),
|
||||
async (input) => {
|
||||
const parsed = compareApplicationVersionsInputSchema.parse(input);
|
||||
const result = await logToolExecution(
|
||||
options.logger,
|
||||
compareContract.name,
|
||||
() => Promise.resolve(compareApplicationVersionsEvidence(parsed)),
|
||||
);
|
||||
if (!result.ok) return toCallToolResult(result, compareContract);
|
||||
const sources = [
|
||||
parsed.left,
|
||||
parsed.right,
|
||||
...parsed.left_native_observations,
|
||||
...parsed.right_native_observations,
|
||||
];
|
||||
const recorded = recordSources(options.recordEvidence, sources);
|
||||
if (!recorded.ok) return toCallToolResult(recorded, compareContract);
|
||||
const comparison = applicationVersionComparisonResultSchema.parse(
|
||||
result.value.normalized_result,
|
||||
);
|
||||
const unknown = comparison.summary.unknown > 0;
|
||||
return recordResult(
|
||||
options,
|
||||
compareContract,
|
||||
result.value,
|
||||
parsed.unknown_registry_approved === true && unknown,
|
||||
);
|
||||
},
|
||||
);
|
||||
};
|
||||
|
||||
const recordSources = (
|
||||
recordEvidence: ApplicationToolRegistration["recordEvidence"],
|
||||
sources: readonly Evidence[],
|
||||
) => {
|
||||
for (const source of sources) {
|
||||
const recorded = recordEvidence?.(source);
|
||||
if (recorded !== undefined && !recorded.ok) return recorded;
|
||||
}
|
||||
return { ok: true as const, value: null };
|
||||
};
|
||||
|
||||
const recordResult = (
|
||||
options: ApplicationToolRegistration,
|
||||
contract: (typeof APPLICATION_TOOL_CONTRACTS)[number],
|
||||
evidence: Evidence,
|
||||
recordUnknown = false,
|
||||
) => {
|
||||
const recorded = recordUnknown
|
||||
? options.recordEvidenceWithUnknown?.(evidence, {
|
||||
approved: true,
|
||||
question:
|
||||
"Which application entities remain unmatched or ambiguous across these versions?",
|
||||
severity: "medium",
|
||||
domain: "application-version-comparison",
|
||||
supporting_evidence_ids: [evidence.evidence_id],
|
||||
contradicting_evidence_ids: [],
|
||||
required_authority: "shipped-artifact",
|
||||
required_confidence: "observed",
|
||||
required_environment: null,
|
||||
recommended_probes: [
|
||||
{
|
||||
operation: "analyze_javascript_application",
|
||||
rationale:
|
||||
"Repeat static reconstruction with complete artifacts and source maps when available.",
|
||||
},
|
||||
{
|
||||
operation: "reconcile_javascript_runtime",
|
||||
rationale:
|
||||
"Add approved passive runtime Evidence without promoting it to static fact.",
|
||||
},
|
||||
],
|
||||
relationships: [],
|
||||
})
|
||||
: options.recordEvidence?.(evidence);
|
||||
if (recorded !== undefined && !recorded.ok)
|
||||
return toCallToolResult(recorded, contract);
|
||||
return toCallToolResult({ ok: true, value: evidence }, contract, {
|
||||
evidenceResourcesAvailable: recorded !== undefined,
|
||||
});
|
||||
};
|
||||
Reference in New Issue
Block a user