rea-agents 2.0.0 → 2.1.0

package/dist/domain/managedMemberComparisonMatch.js

@@ -0,0 +1,356 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { parseEvidence } from "./evidence.js";
+import { managedMemberInspectionSchema, } from "./managedArtifact.js";
+export const sha256 = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("Managed comparison canonicalization failed");
+    return createHash("sha256").update(serialized).digest("hex");
+};
+const keyMethod = (item) => ({
+    item,
+    exactKey: item.signature.parse_status === "decoded" &&
+        item.body.status === "present" &&
+        item.body.normalized_il_sha256 !== null
+        ? stableKey([
+            "method-exact",
+            item.signature.raw_sha256,
+            item.body.normalized_il_sha256,
+        ])
+        : null,
+    structuralKey: item.body.status === "present"
+        ? stableKey([
+            "method-structural",
+            item.signature.kind,
+            item.signature.calling_convention,
+            item.signature.generic_parameter_count,
+            item.signature.parameter_count,
+            item.signature.return_type,
+            item.signature.parameter_types,
+            item.body.status,
+            item.body.header_format,
+            item.body.il_size,
+            item.body.max_stack,
+            item.body.init_locals,
+            item.body.opcode_counts,
+            item.body.anchors.map(({ opcode, operand_kind }) => [
+                opcode,
+                operand_kind,
+            ]),
+            item.body.exception_regions.map((region) => [
+                region.flags,
+                region.try_length,
+                region.handler_length,
+                region.class_token === null ? null : "type-token",
+                region.filter_offset === null ? null : "filter",
+            ]),
+        ])
+        : null,
+});
+const keyField = (item) => ({
+    item,
+    exactKey: item.signature.parse_status === "decoded"
+        ? stableKey(["field-exact", item.signature.raw_sha256])
+        : null,
+    structuralKey: stableKey([
+        "field-structural",
+        item.signature.kind,
+        item.signature.field_type,
+        item.flags,
+    ]),
+});
+const stableKey = (value) => sha256(value);
+const matchMethods = (left, right, maxCandidates) => matchByKeys({
+    left,
+    right,
+    maxCandidates,
+    exactBasis: "exact-il-signature",
+    fallbackBases: ["structural-method-shape"],
+});
+const matchFields = (left, right, maxCandidates) => matchByKeys({
+    left,
+    right,
+    maxCandidates,
+    exactBasis: "field-signature",
+    fallbackBases: [],
+});
+const matchByKeys = ({ left, right, maxCandidates, exactBasis, fallbackBases, }) => {
+    const usedLeft = new Set();
+    const usedRight = new Set();
+    const pairs = [];
+    const ambiguous = [];
+    let omittedCandidates = 0;
+    const rounds = [
+        { basis: exactBasis, key: ({ exactKey }) => exactKey },
+        ...fallbackBases.map((basis) => ({
+            basis,
+            key: ({ structuralKey }) => structuralKey,
+        })),
+    ];
+    for (const round of rounds) {
+        const leftGroups = groupBy(left.filter((item) => !usedLeft.has(item)), round.key);
+        const rightGroups = groupBy(right.filter((item) => !usedRight.has(item)), round.key);
+        for (const [key, leftItems] of leftGroups) {
+            const rightItems = rightGroups.get(key);
+            if (rightItems === undefined)
+                continue;
+            if (leftItems.length === 1 && rightItems.length === 1) {
+                const [leftItem] = leftItems;
+                const [rightItem] = rightItems;
+                if (leftItem === undefined || rightItem === undefined)
+                    continue;
+                usedLeft.add(leftItem);
+                usedRight.add(rightItem);
+                pairs.push({
+                    left: leftItem,
+                    right: rightItem,
+                    basis: round.basis,
+                    confidence: round.basis === "exact-il-signature" ||
+                        round.basis === "field-signature"
+                        ? "exact"
+                        : "high",
+                });
+            }
+            else {
+                for (const item of leftItems)
+                    usedLeft.add(item);
+                for (const item of rightItems)
+                    usedRight.add(item);
+                omittedCandidates += Math.max(0, leftItems.length + rightItems.length - maxCandidates * 2);
+                ambiguous.push({
+                    left: leftItems.slice(0, maxCandidates),
+                    right: rightItems.slice(0, maxCandidates),
+                    basis: round.basis,
+                });
+            }
+        }
+    }
+    return {
+        pairs,
+        ambiguous,
+        leftOnly: left.filter((item) => !usedLeft.has(item)),
+        rightOnly: right.filter((item) => !usedRight.has(item)),
+        omittedCandidates,
+    };
+};
+const groupBy = (items, keyOf) => {
+    const grouped = new Map();
+    for (const item of items) {
+        const key = keyOf(item);
+        if (key === null)
+            continue;
+        const bucket = grouped.get(key) ?? [];
+        bucket.push(item);
+        grouped.set(key, bucket);
+    }
+    return grouped;
+};
+const changedMethodDimensions = (left, right) => {
+    const dimensions = [];
+    if (left.signature.raw_sha256 !== right.signature.raw_sha256)
+        dimensions.push("signature");
+    if (left.body.normalized_il_sha256 !== right.body.normalized_il_sha256)
+        dimensions.push("cil");
+    if (canonicalize(left.body.opcode_counts) !==
+        canonicalize(right.body.opcode_counts))
+        dimensions.push("opcode-shape");
+    if (callShape(left.body.anchors) !== callShape(right.body.anchors))
+        dimensions.push("call-shape");
+    if (fieldShape(left.body.anchors) !== fieldShape(right.body.anchors))
+        dimensions.push("field-shape");
+    if (canonicalize(left.body.exception_regions) !==
+        canonicalize(right.body.exception_regions))
+        dimensions.push("exception-shape");
+    if (left.body.status !== right.body.status)
+        dimensions.push("availability");
+    return dimensions;
+};
+const callShape = (anchors) => JSON.stringify(anchors
+    .filter(({ operand_kind }) => operand_kind === "method")
+    .map(({ opcode, operand_kind }) => [opcode, operand_kind]));
+const fieldShape = (anchors) => JSON.stringify(anchors
+    .filter(({ operand_kind }) => operand_kind === "field")
+    .map(({ opcode, operand_kind }) => [opcode, operand_kind]));
+const methodIdentity = (item) => ({
+    token: item.token,
+    declaring_type: item.declaring_type,
+    name: item.name,
+    signature_sha256: item.signature.raw_sha256,
+    normalized_il_sha256: item.body.normalized_il_sha256,
+});
+const fieldIdentity = (item) => ({
+    token: item.token,
+    declaring_type: item.declaring_type,
+    name: item.name,
+    signature_sha256: item.signature.raw_sha256,
+});
+const methodOnlyItem = (item, context, left) => {
+    const absenceObserved = left ? context.rightComplete : context.leftComplete;
+    return {
+        item_id: `mmc_method_${sha256({ token: item.token, side: left ? "left" : "right" })}`,
+        status: absenceObserved ? (left ? "removed" : "added") : "unknown",
+        left: left ? methodIdentity(item) : null,
+        right: left ? null : methodIdentity(item),
+        match: {
+            status: "unmatched",
+            basis: "none",
+            confidence: "unknown",
+            candidate_left_tokens: [],
+            candidate_right_tokens: [],
+        },
+        dimensions: ["availability"],
+        evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+        limitations: absenceObserved
+            ? []
+            : [
+                `unknown-within-unobserved-page: The ${left ? "right" : "left"} method page is incomplete, so absence was not observed.`,
+            ],
+    };
+};
+const fieldOnlyItem = (item, context, left) => {
+    const absenceObserved = left ? context.rightComplete : context.leftComplete;
+    return {
+        item_id: `mmc_field_${sha256({ token: item.token, side: left ? "left" : "right" })}`,
+        status: absenceObserved ? (left ? "removed" : "added") : "unknown",
+        left: left ? fieldIdentity(item) : null,
+        right: left ? null : fieldIdentity(item),
+        match: {
+            status: "unmatched",
+            basis: "none",
+            confidence: "unknown",
+            candidate_left_tokens: [],
+            candidate_right_tokens: [],
+        },
+        evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+        limitations: absenceObserved
+            ? []
+            : [
+                `unknown-within-unobserved-page: The ${left ? "right" : "left"} field page is incomplete, so absence was not observed.`,
+            ],
+    };
+};
+export const buildMethodItems = (matches, context) => {
+    const items = [];
+    for (const pair of matches.pairs) {
+        const dimensions = changedMethodDimensions(pair.left.item, pair.right.item);
+        items.push({
+            item_id: `mmc_method_${sha256({
+                left: pair.left.item.token,
+                right: pair.right.item.token,
+                basis: pair.basis,
+            })}`,
+            status: dimensions.length === 0 ? "unchanged" : "changed",
+            left: methodIdentity(pair.left.item),
+            right: methodIdentity(pair.right.item),
+            match: {
+                status: "matched",
+                basis: pair.basis,
+                confidence: pair.confidence,
+                candidate_left_tokens: [],
+                candidate_right_tokens: [],
+            },
+            dimensions,
+            evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+            limitations: [],
+        });
+    }
+    for (const ambiguous of matches.ambiguous) {
+        items.push({
+            item_id: `mmc_method_${sha256({
+                left: ambiguous.left.map(({ item }) => item.token),
+                right: ambiguous.right.map(({ item }) => item.token),
+                basis: ambiguous.basis,
+            })}`,
+            status: "unknown",
+            left: null,
+            right: null,
+            match: {
+                status: "ambiguous",
+                basis: ambiguous.basis,
+                confidence: "unknown",
+                candidate_left_tokens: ambiguous.left.map(({ item }) => item.token),
+                candidate_right_tokens: ambiguous.right.map(({ item }) => item.token),
+            },
+            dimensions: ["availability"],
+            evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+            limitations: [
+                "Multiple managed methods share the same non-name identity key; REA did not guess a token remap.",
+            ],
+        });
+    }
+    for (const item of matches.leftOnly)
+        items.push(methodOnlyItem(item.item, context, true));
+    for (const item of matches.rightOnly)
+        items.push(methodOnlyItem(item.item, context, false));
+    return limitItems(items, context.limits.max_method_matches);
+};
+export const buildFieldItems = (matches, context) => {
+    const items = [];
+    for (const pair of matches.pairs) {
+        const changed = pair.left.item.signature.raw_sha256 !==
+            pair.right.item.signature.raw_sha256 ||
+            pair.left.item.flags !== pair.right.item.flags;
+        items.push({
+            item_id: `mmc_field_${sha256({
+                left: pair.left.item.token,
+                right: pair.right.item.token,
+            })}`,
+            status: changed ? "changed" : "unchanged",
+            left: fieldIdentity(pair.left.item),
+            right: fieldIdentity(pair.right.item),
+            match: {
+                status: "matched",
+                basis: pair.basis,
+                confidence: pair.confidence,
+                candidate_left_tokens: [],
+                candidate_right_tokens: [],
+            },
+            evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+            limitations: [],
+        });
+    }
+    for (const ambiguous of matches.ambiguous)
+        items.push({
+            item_id: `mmc_field_${sha256({
+                left: ambiguous.left.map(({ item }) => item.token),
+                right: ambiguous.right.map(({ item }) => item.token),
+            })}`,
+            status: "unknown",
+            left: null,
+            right: null,
+            match: {
+                status: "ambiguous",
+                basis: ambiguous.basis,
+                confidence: "unknown",
+                candidate_left_tokens: ambiguous.left.map(({ item }) => item.token),
+                candidate_right_tokens: ambiguous.right.map(({ item }) => item.token),
+            },
+            evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
+            limitations: [
+                "Multiple managed fields share the same signature; REA did not guess a token remap from names.",
+            ],
+        });
+    for (const item of matches.leftOnly)
+        items.push(fieldOnlyItem(item.item, context, true));
+    for (const item of matches.rightOnly)
+        items.push(fieldOnlyItem(item.item, context, false));
+    return limitItems(items, context.limits.max_field_matches);
+};
+const limitItems = (items, limit) => ({
+    items: items.slice(0, limit),
+    omitted: Math.max(0, items.length - limit),
+});
+export const keyMembers = (left, right, maxCandidates) => ({
+    methodMatches: matchMethods(left.result.methods.items.map(keyMethod), right.result.methods.items.map(keyMethod), maxCandidates),
+    fieldMatches: matchFields(left.result.fields.items.map(keyField), right.result.fields.items.map(keyField), maxCandidates),
+});
+export const parseManagedMemberEvidence = (evidence) => {
+    const parsed = parseEvidence(evidence);
+    if (parsed.operation !== "inspect_managed_members")
+        throw new TypeError("Evidence operation is not inspect_managed_members");
+    return {
+        evidenceId: parsed.evidence_id,
+        result: managedMemberInspectionSchema.parse(parsed.normalized_result),
+    };
+};