diff --git a/docs/getting-started/cli.md b/docs/getting-started/cli.md index 2f8dc5323c..f9c684b61c 100644 --- a/docs/getting-started/cli.md +++ b/docs/getting-started/cli.md @@ -945,6 +945,11 @@ not read artifact contents: the inventories of two builds are unresolved records, or one opaque change when you pair them. Use `compare-artifacts`, described at the end of this section, to compare their contents. +If a selected file looks like an analysis snapshot, comparison reports the +wrong artifact kind. To compare its Evidence, restore the snapshot with its +matching target, provider and analysis profile, then export a standalone +Evidence bundle from that session. + `--record_pairs` accepts an inline JSON array or the path to a local JSON file containing that array, matching MCP `compare_bundles.record_pairs`. For a file, use `rea compare left.json right.json --record_pairs pairs.json --json`. diff --git a/src/application/EvidenceBundleFiles.ts b/src/application/EvidenceBundleFiles.ts index a45c40a5bf..468999a176 100644 --- a/src/application/EvidenceBundleFiles.ts +++ b/src/application/EvidenceBundleFiles.ts @@ -5,6 +5,7 @@ import { analysisErrorWithCleanupDependencies } from "../domain/analysisErrorCle import { requireAuthenticationHeadroom } from "./JsonAuthenticationHeadroom.js"; import { absoluteCallerPath } from "../filesystem/callerPath.js"; import { resemblesAnalysisSnapshot } from "../domain/analysisSnapshot.js"; +import { isRecord } from "../kernel/isRecord.js"; import { describeValidationFailure } from "../domain/validationFailure.js"; import { @@ -149,22 +150,29 @@ export const authenticateEvidenceBundleValue = ( }), ); if ( - operation === "import_evidence_bundle" && - typeof value === "object" && - value !== null && + isRecord(value) && !Object.hasOwn(value, "records") && resemblesAnalysisSnapshot(value) - ) + ) { + const importing = operation === "import_evidence_bundle"; + const explanation = + "This JSON appears to be an analysis snapshot rather than an Evidence bundle. Its snapshot content has not been validated."; return err( new EvidenceFileError("read", "wrong-kind", { path: absoluteCallerPath(path), cause: failure.cause, detectedKind: "analysis-snapshot", - related: { operations: ["open_binary", "export_evidence_bundle"] }, - userMessage: - "This JSON appears to be an analysis snapshot rather than an Evidence bundle. Its snapshot content has not been validated. To restore it, use a matching target, provider and analysis profile: call open_binary with snapshot_path set to this file to load the snapshot, and close_binary with snapshot_path to save updated state. Alternatively, supply a bundle from export_evidence_bundle.", + related: { + operations: importing + ? ["open_binary", "export_evidence_bundle"] + : ["export_evidence_bundle"], + }, + userMessage: importing + ? `${explanation} To restore it, use a matching target, provider and analysis profile: call open_binary with snapshot_path set to this file to load the snapshot, and close_binary with snapshot_path to save updated state. Alternatively, supply a bundle from export_evidence_bundle.` + : `${explanation} Supply a standalone Evidence bundle from export_evidence_bundle for this input.`, }), ); + } return err( new EvidenceIntegrityError("Evidence bundle validation failed", { cause: failure.cause, diff --git a/tests/boundary/cli/bundleComparisonCli.test.ts b/tests/boundary/cli/bundleComparisonCli.test.ts index 35f9f3099d..a0a9f1a0c6 100644 --- a/tests/boundary/cli/bundleComparisonCli.test.ts +++ b/tests/boundary/cli/bundleComparisonCli.test.ts @@ -170,6 +170,68 @@ cliTest( }, ); +cliTest( + "identifies an analysis snapshot on either side of a bundle comparison", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-compare-snapshot-kind-"); + const bundlePath = join(root, "bundle.json"); + const snapshotPath = join(root, "snapshot.json"); + const malformedPath = join(root, "malformed.json"); + const snapshot = { + target: {}, + binding: {}, + evidence_bundle: {}, + entries: [], + workflow_entries: [], + }; + await Promise.all([ + writeFile(bundlePath, serializeEvidenceBundle(createEvidenceBundle([]))), + writeFile(snapshotPath, JSON.stringify(snapshot)), + writeFile(malformedPath, JSON.stringify({ ...snapshot, records: [] })), + ]); + + const call = await cli.sharedMcpCall?.(); + if (call === undefined) throw new Error("Expected shared MCP session"); + const wrongKind = { + code: "invalid_request", + remediation: { + action: expect.stringContaining("standalone Evidence bundle"), + }, + details: { + operation: "read", + reason: "wrong-kind", + detected_kind: "analysis-snapshot", + path: snapshotPath, + related_operations: ["export_evidence_bundle"], + }, + }; + const compareCli = (left: string, right: string) => + cli.run({ arguments: ["compare", left, right, "--json"] }); + const compareMcp = (left: string, right: string) => + call("compare_bundles", { + left_bundle_path: left, + right_bundle_path: right, + }); + for (const [left, right] of [ + [snapshotPath, bundlePath], + [bundlePath, snapshotPath], + ] as const) { + const compared = await compareCli(left, right); + expect(compared.exitCode).toBe(1); + expect(compared.json).toMatchObject(wrongKind); + expect( + parseMcpToolError(await compareMcp(left, right)).error, + ).toMatchObject(wrongKind); + } + + const malformed = await compareCli(bundlePath, malformedPath); + expect(malformed.exitCode).toBe(1); + expect(malformed.json).toMatchObject({ + code: "evidence_integrity_mismatch", + }); + }, +); + cliTest( "rejects relative bundle paths over stdio MCP while CLI resolves them from its cwd", async ({ cli }) => {