Files
rea/src/domain/artifactComparison.ts
T
0ecf3f2438 perf(mcp): keep Playwright and type-only imports off MCP startup (#1691)
* fix(build): emit no runtime imports for type-only bindings

Under verbatimModuleSyntax, an import whose specifiers all carry inline
`type` modifiers compiles to `import {} from "..."`, a side-effect import
that still resolves and evaluates the module. 78 compiled modules carried
one, including `import {} from "playwright-core"` in the browser scenario
session, which loaded Playwright's module graph at MCP startup.

Use top-level `import type` for these bindings and enable oxlint's
typescript/no-import-type-side-effects rule so the pattern cannot return.

Refs #1685

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* perf(mcp): load Playwright when a scenario launches, not at startup

The browser scenario and Electron active providers are constructed before
the stdio server serves, and both bound Playwright's launchers at module
load. Resolve `chromium` and `_electron` from playwright-core when a
capture opens instead, as the web module resolver already does.

MCP startup now resolves 1,312 modules (4,902 resolutions) instead of
1,598 (6,076) before reading the first request, and no longer loads
playwright-core. Provider construction, the tool catalog, and capability
inventory are unchanged.

A boundary test spawns the stdio server, initializes, lists tools, and
asserts playwright-core and isomorphic-git were not resolved; the CLI
probe now exercises the real launch path to prove detection.

Closes #1685

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 21:04:05 -07:00

475 lines
15 KiB
TypeScript

import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
import { z } from "zod";
import type {
ArtifactInventoryResult,
ArtifactNode,
ArtifactOccurrence,
} from "./artifactGraph.js";
import { evidenceSchema } from "./evidence.js";
import {
parseArtifactInventoryEvidence,
type InventorySet,
} from "./artifactInventoryEvidence.js";
import { prefixedDigestSchema } from "./../domain/digests.js";
import { canonicalJson } from "./comparisonSemantics.js";
import { ZIP_NON_ENTRY_TAIL_LIMITATION } from "./zipPackageFormat.js";
const evidenceIdSchema = prefixedDigestSchema("ev");
const comparisonStatusSchema = z.enum([
"unchanged",
"added",
"removed",
"changed",
"truncated",
"unknown",
"contradiction",
]);
const changeKindSchema = z.enum([
"added",
"removed",
"changed",
"unknown",
"contradiction",
]);
const comparisonDimensionSchema = z.enum([
"content",
"kind",
"format",
"size",
"executable",
"relations",
"metadata",
"availability",
"integrity",
]);
/** Strict Evidence-backed input for deterministic artifact comparison. */
export const artifactComparisonInputSchema = z.strictObject({
left: evidenceSchema,
right: evidenceSchema,
});
/** One path-classified artifact change with citations to both observations. */
const artifactChangeSchema = z.object({
classification: changeKindSchema,
logical_path: z.string().min(1),
dimensions: z.array(comparisonDimensionSchema).min(1),
left_occurrence_id: z
.string()
.regex(/^occ_[a-f0-9]{64}$/u)
.nullable(),
right_occurrence_id: z
.string()
.regex(/^occ_[a-f0-9]{64}$/u)
.nullable(),
left_artifact_id: z
.string()
.regex(/^art_[a-f0-9]{64}$/u)
.nullable(),
right_artifact_id: z
.string()
.regex(/^art_[a-f0-9]{64}$/u)
.nullable(),
evidence_links: z.array(evidenceIdSchema).min(2),
});
/** Deterministic artifact comparison with every change returned inline. */
export const artifactComparisonResultSchema = z.object({
status: comparisonStatusSchema,
left_manifest_id: prefixedDigestSchema("agm"),
right_manifest_id: prefixedDigestSchema("agm"),
summary: z.object({
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),
contradiction: z.number().int().min(0).default(0),
}),
changes: z.array(artifactChangeSchema),
limitations: z.array(z.string()),
});
export type ArtifactComparisonResult = z.infer<
typeof artifactComparisonResultSchema
>;
type ArtifactChange = z.infer<typeof artifactChangeSchema>;
/** Compare complete inventory evidence without treating missing evidence as equality. */
export const compareArtifacts = (
leftEvidence: unknown,
rightEvidence: unknown,
): ArtifactComparisonResult => {
const left = parseArtifactInventoryEvidence(leftEvidence);
const right = parseArtifactInventoryEvidence(rightEvidence);
const leftComplete = left.inventory.complete;
const rightComplete = right.inventory.complete;
const leftCovered =
leftComplete && !hasCoverageLimitation(left.inventory.limitations);
const rightCovered =
rightComplete && !hasCoverageLimitation(right.inventory.limitations);
const limitations = [
...left.inventory.limitations.map((item) => `Left: ${item}`),
...right.inventory.limitations.map((item) => `Right: ${item}`),
...(leftComplete ? [] : ["Left artifact inventory is incomplete."]),
...(rightComplete ? [] : ["Right artifact inventory is incomplete."]),
];
const changes = compareOccurrences(
left.inventory,
right.inventory,
[
...left.evidence.map(({ evidence_id: id }) => id),
...right.evidence.map(({ evidence_id: id }) => id),
],
leftCovered && rightCovered,
);
const rootChange = rootHashChange(left.inventory, right.inventory, changes, [
...left.evidence.map(({ evidence_id: id }) => id),
...right.evidence.map(({ evidence_id: id }) => id),
]);
if (rootChange !== null) changes.push(rootChange);
const summary = summarize(
left.inventory,
right.inventory,
changes,
leftCovered && rightCovered,
);
return artifactComparisonResultSchema.parse({
status:
!leftComplete || !rightComplete
? "truncated"
: changes.some(
({ classification }) => classification === "contradiction",
)
? "contradiction"
: !leftCovered || !rightCovered
? "unknown"
: changes.some(({ classification }) => classification === "unknown")
? "unknown"
: changes.length === 0
? "unchanged"
: "changed",
left_manifest_id: left.inventory.manifest.manifest_id,
right_manifest_id: right.inventory.manifest.manifest_id,
summary,
changes,
limitations: [...new Set(limitations)].sort(compareUnicodeCodePoints),
});
};
const compareOccurrences = (
left: InventorySet,
right: InventorySet,
evidenceLinks: readonly string[],
complete: boolean,
): ArtifactChange[] => {
const leftByPath = new Map(
left.occurrences.map((item) => [item.logical_path, item]),
);
const rightByPath = new Map(
right.occurrences.map((item) => [item.logical_path, item]),
);
const leftNodes = new Map(left.nodes.map((item) => [item.artifact_id, item]));
const rightNodes = new Map(
right.nodes.map((item) => [item.artifact_id, item]),
);
const leftRelations = relationsByPath(left);
const rightRelations = relationsByPath(right);
const paths = [
...new Set([...leftByPath.keys(), ...rightByPath.keys()]),
].sort(compareUnicodeCodePoints);
const output: ArtifactChange[] = [];
for (const path of paths) {
const leftOccurrence = leftByPath.get(path);
const rightOccurrence = rightByPath.get(path);
const change = classifyPath({
path,
leftOccurrence,
rightOccurrence,
leftNode: nodeFor(leftOccurrence, leftNodes),
rightNode: nodeFor(rightOccurrence, rightNodes),
leftRelations: leftRelations.get(path) ?? [],
rightRelations: rightRelations.get(path) ?? [],
complete,
evidenceLinks,
});
if (change !== null) output.push(change);
}
return output;
};
interface ClassifyPathInput {
readonly path: string;
readonly leftOccurrence: ArtifactOccurrence | undefined;
readonly rightOccurrence: ArtifactOccurrence | undefined;
readonly leftNode: ArtifactNode | undefined;
readonly rightNode: ArtifactNode | undefined;
readonly leftRelations: readonly RelationProjection[];
readonly rightRelations: readonly RelationProjection[];
readonly complete: boolean;
readonly evidenceLinks: readonly string[];
}
const buildArtifactChangeBase = (input: ClassifyPathInput) => ({
logical_path: input.path,
left_occurrence_id: input.leftOccurrence?.occurrence_id ?? null,
right_occurrence_id: input.rightOccurrence?.occurrence_id ?? null,
left_artifact_id: input.leftOccurrence?.artifact_id ?? null,
right_artifact_id: input.rightOccurrence?.artifact_id ?? null,
evidence_links: [...input.evidenceLinks],
});
const classifyPresence = (input: ClassifyPathInput): ArtifactChange | null => {
if (input.leftOccurrence === undefined)
return {
...buildArtifactChangeBase(input),
classification: input.complete ? "added" : "unknown",
dimensions: [input.complete ? "content" : "availability"],
};
if (input.rightOccurrence === undefined)
return {
...buildArtifactChangeBase(input),
classification: input.complete ? "removed" : "unknown",
dimensions: [input.complete ? "content" : "availability"],
};
return null;
};
const classifyIntegrity = (
input: ClassifyPathInput,
base: ReturnType<typeof buildArtifactChangeBase>,
): ArtifactChange | null => {
if (
input.leftOccurrence?.hash_status === "mismatched" ||
input.rightOccurrence?.hash_status === "mismatched"
)
return {
...base,
classification: "contradiction",
dimensions: ["integrity"],
};
return null;
};
const classifyAvailability = (
input: ClassifyPathInput,
base: ReturnType<typeof buildArtifactChangeBase>,
): ArtifactChange | null => {
if (
input.leftOccurrence?.hash_status !== "verified" ||
input.rightOccurrence?.hash_status !== "verified" ||
input.leftNode === undefined ||
input.rightNode === undefined
)
return { ...base, classification: "unknown", dimensions: ["availability"] };
return null;
};
const classifyPath = (input: ClassifyPathInput): ArtifactChange | null => {
const presence = classifyPresence(input);
if (presence !== null) return presence;
const base = buildArtifactChangeBase(input);
const integrity = classifyIntegrity(input, base);
if (integrity !== null) return integrity;
const availability = classifyAvailability(input, base);
if (availability !== null) return availability;
const dimensions = changedDimensions(input);
return dimensions.length === 0
? null
: { ...base, classification: "changed", dimensions };
};
const changedDimensions = (input: {
readonly leftNode: ArtifactNode | undefined;
readonly rightNode: ArtifactNode | undefined;
readonly leftOccurrence: ArtifactOccurrence | undefined;
readonly rightOccurrence: ArtifactOccurrence | undefined;
readonly leftRelations: readonly RelationProjection[];
readonly rightRelations: readonly RelationProjection[];
}): z.infer<typeof comparisonDimensionSchema>[] => {
const left = input.leftNode;
const right = input.rightNode;
if (left === undefined || right === undefined) return ["availability"];
const checks: readonly [
z.infer<typeof comparisonDimensionSchema>,
boolean,
][] = [
["content", left.sha256 !== right.sha256],
[
"kind",
input.leftOccurrence?.artifact_kind !==
input.rightOccurrence?.artifact_kind,
],
[
"format",
left.format !== right.format ||
input.leftOccurrence?.artifact_format !==
input.rightOccurrence?.artifact_format,
],
["size", left.size !== right.size],
[
"executable",
input.leftOccurrence?.executable !== input.rightOccurrence?.executable,
],
[
"relations",
JSON.stringify(input.leftRelations) !==
JSON.stringify(input.rightRelations),
],
["metadata", metadataChanged(input, left, right)],
];
return checks
.filter(([, changed]) => changed)
.map(([dimension]) => dimension);
};
const metadataChanged = (
input: {
readonly leftOccurrence: ArtifactOccurrence | undefined;
readonly rightOccurrence: ArtifactOccurrence | undefined;
},
left: ArtifactNode,
right: ArtifactNode,
): boolean =>
left.media_type !== right.media_type ||
left.architecture !== right.architecture ||
left.content_state !== right.content_state ||
input.leftOccurrence?.entry_kind !== input.rightOccurrence?.entry_kind ||
input.leftOccurrence?.encrypted !== input.rightOccurrence?.encrypted ||
JSON.stringify(left.limitations) !== JSON.stringify(right.limitations) ||
JSON.stringify(input.leftOccurrence?.limitations) !==
JSON.stringify(input.rightOccurrence?.limitations);
const nodeFor = (
occurrence: ArtifactOccurrence | undefined,
nodes: ReadonlyMap<string, ArtifactNode>,
): ArtifactNode | undefined =>
occurrence?.artifact_id === null || occurrence?.artifact_id === undefined
? undefined
: nodes.get(occurrence.artifact_id);
const relationsByPath = (
inventory: InventorySet,
): ReadonlyMap<string, readonly RelationProjection[]> => {
const output = new Map<string, RelationProjection[]>();
const occurrences = new Map(
inventory.occurrences.map((item) => [item.occurrence_id, item]),
);
for (const edge of inventory.edges) {
const occurrence = occurrences.get(edge.occurrence_id);
// An incomplete inventory can omit the occurrence that names the child.
if (occurrence?.artifact_id === null || occurrence === undefined) continue;
const path = occurrence.logical_path;
const values = output.get(path);
const projection: RelationProjection = {
parent_logical_path:
occurrence.parent_occurrence_id === null
? null
: (occurrences.get(occurrence.parent_occurrence_id)?.logical_path ??
null),
child_artifact_id: occurrence.artifact_id,
relation: edge.relation,
logical_path: occurrence.logical_path,
producer: edge.producer,
};
if (values === undefined) output.set(path, [projection]);
else values.push(projection);
}
for (const values of output.values())
values.sort((left, right) =>
compareUnicodeCodePoints(canonicalJson(left), canonicalJson(right)),
);
return output;
};
interface RelationProjection {
/** Logical parent is stable across graph-root ID changes. */
readonly parent_logical_path: string | null;
readonly child_artifact_id: string;
readonly relation: ArtifactInventoryResult["edges"][number]["relation"];
readonly logical_path: string | null;
/** Producer is semantic provenance; edge ordinal is presentation order. */
readonly producer: ArtifactInventoryResult["edges"][number]["producer"];
}
const summarize = (
left: InventorySet,
right: InventorySet,
changes: readonly ArtifactChange[],
covered: boolean,
) => {
const counts = {
added: 0,
removed: 0,
changed: 0,
unknown: 0,
contradiction: 0,
};
for (const change of changes) counts[change.classification] += 1;
return {
unchanged: covered
? Math.max(
0,
left.occurrences.length -
counts.removed -
counts.changed -
counts.contradiction -
counts.unknown,
)
: 0,
...counts,
unknown: covered
? counts.unknown
: Math.max(
counts.unknown,
Math.max(
left.manifest.occurrence_count,
right.manifest.occurrence_count,
) -
counts.added -
counts.removed -
counts.changed -
counts.contradiction,
),
};
};
const hasCoverageLimitation = (limitations: readonly string[]): boolean =>
limitations.some(
(limitation) =>
limitation !== ZIP_NON_ENTRY_TAIL_LIMITATION &&
!/integrity contradiction\(s\) were recorded/u.test(limitation),
);
const rootHashChange = (
left: InventorySet,
right: InventorySet,
changes: readonly ArtifactChange[],
evidenceLinks: readonly string[],
): ArtifactChange | null => {
if (left.manifest.root_sha256 === right.manifest.root_sha256) return null;
if (
changes.some(
(change) =>
change.logical_path === "." && change.dimensions.includes("content"),
)
)
return null;
const leftRoot = left.occurrences.find(
(occurrence) => occurrence.logical_path === ".",
);
const rightRoot = right.occurrences.find(
(occurrence) => occurrence.logical_path === ".",
);
return {
classification: "changed",
logical_path: ".",
dimensions: ["content"],
left_occurrence_id: leftRoot?.occurrence_id ?? null,
right_occurrence_id: rightRoot?.occurrence_id ?? null,
left_artifact_id: leftRoot?.artifact_id ?? null,
right_artifact_id: rightRoot?.artifact_id ?? null,
evidence_links: [...evidenceLinks],
};
};