Files
reverse-engineering-anything/src/application/analysisView/evidenceFileSource.ts
T
gensokyo-devandEntrpi 37827af591 feat(artifacts): compare inventories from Evidence sources (#7869)
* feat(artifacts): compare artifacts by Evidence reference and from the CLI

compare_artifacts made agents send back the complete inventory Evidence
that REA already retains, and the CLI had no artifact comparison.

Each side of compare_artifacts now takes exactly one of: complete inline
Evidence (unchanged), {kind: "retained-evidence", evidence_id}, or
{kind: "evidence-file", path, evidence_id?}. The two references are the
sources inspect_analysis_view accepts; both tools now compose one
definition in evidenceReference.ts. A summary still resolves to its exact
retained parent, and every source form gives the same comparison Evidence.
An unresolvable retained reference is refused with a typed missing
reference error.

The application layer owns source resolution and the comparison Evidence,
so MCP and the new `rea compare-artifacts` command share one workflow.
readEvidenceFileSource reports bundle-selection refusals at the caller's
own field path.

* refactor(artifacts): resolve compare_artifacts sides like compare_functions

compare_functions, compare_wasm_interfaces and the JavaScript application
comparisons name each side with evidenceInputSchema and resolve it with
resolvePairedEvidenceRequest. compare_artifacts reached the same result
for inline and retained sides through its own dispatch.

evidenceSourceInputSchema now extends evidenceInputSchema with the
Evidence-file reference, and resolvePairedEvidenceSources sends inline and
retained sides to the same resolveEvidenceInput and file sides to the
shared Evidence file reader. compare_artifacts uses both, so the forms it
shares with compare_functions are parsed and resolved by one owner. The
advertised input schema is unchanged.

* docs(cli): point rea compare to compare-artifacts for inventory contents

rea compare (compare_bundles) compares records by Evidence identity and
explicit pairs and never reads artifact contents, so two build
inventories stay unresolved there. Its help and the CLI guide now name
compare-artifacts for that comparison.

* fix(artifacts): resolve summary parents within Evidence source bundles

* perf(evidence): reuse file-owned immutable authentication proofs

* test(evidence): inject failures at both authentication boundaries

---------

Co-authored-by: Entrpi <entrpi@proton.me>
2026-10-29 03:12:03 +08:00

190 lines
6.6 KiB
TypeScript

import { requireAuthenticationHeadroom } from "../JsonAuthenticationHeadroom.js";
import { authenticateEvidenceBundleValue } from "../EvidenceBundleFiles.js";
import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
AnalysisCancelledError,
AnalysisInputError,
} from "../../domain/analysisErrorCore.js";
import { INSPECT_ANALYSIS_VIEW_OPERATION } from "../../domain/analysisView/analysisViewErrors.js";
import { err, ok, type Result } from "../../domain/result.js";
import type { Evidence } from "../../domain/evidence.js";
import { safeParseImmutableEvidence } from "../../domain/evidenceValidation.js";
import { EvidenceFileError } from "../../domain/evidenceErrors.js";
import { projectInputIssues } from "../../domain/inputIssueProjection.js";
import { readJsonFile } from "../JsonFiles.js";
/** The request cancellation and the scope retaining descriptors whose close failed. */
export interface EvidenceFileReadOptions {
readonly signal?: AbortSignal;
readonly resources?: ArtifactResourceScope;
}
/** Caller context and related-record resolution for this admitted file. */
export interface EvidenceFileSourceContext {
readonly operation: string;
readonly path: readonly (string | number)[];
readonly resolveSelected?: EvidenceFileRecordResolver;
}
/** Resolve related facts while the authenticated file records are in scope. */
export type EvidenceFileRecordResolver = (
selected: Evidence,
lookup: (evidenceId: string) => Evidence | undefined,
) => Result<Evidence, AnalysisError>;
const ANALYSIS_VIEW_SOURCE: EvidenceFileSourceContext = {
operation: INSPECT_ANALYSIS_VIEW_OPERATION,
path: ["source"],
};
const selectionError = (
site: EvidenceFileSourceContext,
message: string,
): AnalysisInputError =>
new AnalysisInputError(site.operation, { userMessage: message }, [
{
path: [...site.path, "evidence_id"],
reason: "invalid_value",
message,
},
]);
/** Listed identities stay bounded so a large bundle cannot grow the error itself. */
const RECORD_REFERENCE_PREVIEW_BYTES = 2048;
/** Select the one record a source names from an authenticated bundle. */
const selectBundleRecord = (
records: readonly Evidence[],
path: string,
evidenceId: string | undefined,
site: EvidenceFileSourceContext,
): Result<Evidence, AnalysisError> => {
if (evidenceId !== undefined) {
const selected = records.find(
(record) => record.evidence_id === evidenceId,
);
return selected === undefined
? err(
selectionError(
site,
`Evidence bundle ${path} holds no record ${evidenceId}. It holds ${listRecordIds(records)}.`,
),
)
: ok(selected);
}
const only = records[0];
if (only === undefined)
return err(
selectionError(site, `Evidence bundle ${path} holds no records.`),
);
if (records.length > 1)
return err(
selectionError(
site,
`Evidence bundle ${path} holds ${String(records.length)} records; select one with ${[...site.path, "evidence_id"].join(".")}. It holds ${listRecordIds(records)}.`,
),
);
return ok(only);
};
const listRecordIds = (records: readonly Evidence[]): string => {
const labels: string[] = [];
let bytes = 0;
for (const record of records) {
const separator = labels.length === 0 ? "" : ", ";
const remaining = RECORD_REFERENCE_PREVIEW_BYTES - bytes;
let label = `${record.evidence_id} (operation omitted)`;
// UTF-8/JSON cannot use fewer bytes than the source UTF-16 code units.
// Reject a label before copying it when even that lower bound cannot fit.
if (record.operation.length <= remaining) {
const complete = `${record.evidence_id} (${record.operation})`;
if (
Buffer.byteLength(JSON.stringify(separator + complete), "utf8") <=
remaining
)
label = complete;
}
const encodedBytes = Buffer.byteLength(
JSON.stringify(separator + label),
"utf8",
);
if (encodedBytes > remaining) break;
labels.push(label);
bytes += encodedBytes;
}
const omitted = records.length - labels.length;
const listed = labels.join(", ");
return omitted > 0 ? `${listed} and ${String(omitted)} more` : listed;
};
/** Read one Evidence record or select from an authenticated bundle without rereading the file. */
export const readEvidenceFileSource = async (
path: string,
options: EvidenceFileReadOptions = {},
evidenceId?: string,
site: EvidenceFileSourceContext = ANALYSIS_VIEW_SOURCE,
): Promise<Result<Evidence, AnalysisError>> => {
const { signal, resources } = options;
const { operation } = site;
const resolveSelected =
site.resolveSelected ?? ((selected: Evidence) => ok(selected));
if (signal?.aborted)
return err(new AnalysisCancelledError(operation, { cause: signal.reason }));
const loaded = await readJsonFile(path, signal, resources, operation);
if (!loaded.ok) return loaded;
if (signal?.aborted)
return err(new AnalysisCancelledError(operation, { cause: signal.reason }));
const value = loaded.value;
if (
typeof value === "object" &&
value !== null &&
!Array.isArray(value) &&
Object.hasOwn(value, "records")
) {
const bundle = authenticateEvidenceBundleValue(value, path, {
operation,
immutable: true,
});
if (!bundle.ok) return bundle;
const selected = selectBundleRecord(
bundle.value.records,
path,
evidenceId,
site,
);
return selected.ok
? resolveSelected(selected.value, (id) =>
bundle.value.records.find((record) => record.evidence_id === id),
)
: selected;
}
const headroom = requireAuthenticationHeadroom(value, {
operation,
path,
description: "Insufficient heap headroom to authenticate the Evidence file",
});
if (!headroom.ok) return headroom;
const parsed = safeParseImmutableEvidence(value);
if (!parsed.ok)
return err(
new EvidenceFileError("read", "wrong-kind", {
path,
cause: parsed.error,
contentIssues: projectInputIssues(parsed.error.issues, value),
userMessage:
"The selected file does not contain valid Evidence. Repair or recreate the file and try again.",
}),
);
if (evidenceId !== undefined && parsed.value.evidence_id !== evidenceId)
return err(
selectionError(
site,
`Evidence file ${path} holds ${parsed.value.evidence_id}, not selected record ${evidenceId}.`,
),
);
return resolveSelected(parsed.value, (id) =>
parsed.value.evidence_id === id ? parsed.value : undefined,
);
};