Files
reverse-engineering-anything/src/domain/apiContract/parseApiContract.test.ts
T
morlutoandCursor Agent 654feeef9c fix(api-contract): retain partial OpenAPI evidence (#9908)
* fix(api-contract): retain partial OpenAPI evidence

* docs(api-contract): describe partial OpenAPI Evidence on interruption

Early failures still keep the file snapshot hash. Cancellation or the
retained-facts limit after a row now returns authenticated Evidence, and
the guide explains how to reuse that partial inventory.

* fix(api-contract): count finished paths and keep earlier diagnostics

A path counts only after its item is read, so a path refused before
traversal does not increase path_entries_examined. A paths diagnostic
that exhausts the retained-facts allowance still keeps diagnostics
already stored, including invalid info.

* test(api-contract): keep invalid info when paths exhaust the allowance

The paths diagnostic can fail after invalid info is already stored. The
partial report must still carry that diagnostic and count no path entries.

* docs(api-contract): name every retained row and the view source

The hash remains only when no operation, reference, or diagnostic row was
kept. Partial Evidence is reread through inspect_analysis_view's source
and view, not as separate Evidence fields.

* test(api-contract): verify interrupted inventory evidence

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
2026-11-11 17:27:00 +08:00

435 lines
14 KiB
TypeScript

import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { expect, it } from "vitest";
import {
API_CONTRACT_FACT_BYTES,
apiContractSchema,
type ApiContractArtifact,
} from "./apiContract.js";
import { parseApiContractSteps } from "./parseApiContract.js";
import { AnalysisCancelledError } from "../analysisErrorCore.js";
const artifact: ApiContractArtifact = {
path: "/contract.json",
sha256: "a".repeat(64),
bytes: 1,
};
const document = (paths: unknown, openapi = "3.0.4") => ({
openapi,
info: { title: "Owned API", version: "1" },
paths,
});
const parse = (value: unknown, source = artifact) => {
const steps = parseApiContractSteps(value, source);
for (;;) {
const step = steps.next();
if (step.done) return step.value;
}
};
const report = (value: unknown, source = artifact) => {
const result = parse(value, source);
if (!result.ok) throw result.error;
return apiContractSchema.parse(result.value);
};
it("reads a real published Petstore document without embedding its schemas", () => {
const bytes = readFileSync(
new URL(
"../../../tests/fixtures/openapi/petstore.json.txt",
import.meta.url,
),
);
const sha256 = createHash("sha256").update(bytes).digest("hex");
expect(sha256).toBe(
"00441c05add60f28da55eb4563d3fb6bbda364ba8eb7b381e2e2c98613005c82",
);
const value = report(JSON.parse(bytes.toString("utf8")), {
...artifact,
sha256,
bytes: bytes.length,
});
expect(value.openapi).toBe("3.0.4");
expect(value.info).toEqual({
title: "Swagger Petstore - OpenAPI 3.0",
version: "1.0.27",
});
expect(value.summary).toEqual({
operation_slots: 19,
declared: 19,
unknown: 0,
unresolved_path_items: 0,
diagnostics: 0,
});
expect(value.source_coverage).toMatchObject({
status: "complete-within-scope",
path_entries_examined: 13,
reference_resolution: "not-attempted",
schema_validation: "not-performed",
});
expect(
value.operations.find((row) => row.declared_id === "getPetById"),
).toMatchObject({
method: "GET",
path: "/pet/{petId}",
source_pointer: "/paths/~1pet~1{petId}/get",
state: "declared",
});
expect(value).not.toHaveProperty("components");
expect(value).not.toHaveProperty("servers");
});
it.each(["3.0.4", "3.1.2", "3.2.1"])(
"accepts the explicit %s minor family",
(version) => {
expect(
report(document({ "/x": { get: {} } }, version)).summary.declared,
).toBe(1);
},
);
it.each(["2.0", "3.3.0", "3.2", "3.01.0", "3.0.01", "3.2.0-beta.1"])(
"refuses an unsupported version %s explicitly",
(version) => {
const value = parse(document({}, version));
expect(value.ok).toBe(false);
if (!value.ok)
expect(value.error._tag).toBe("AnalysisUnsupportedTargetError");
},
);
it.each([null, [], {}, { openapi: 3 }])(
"rejects a malformed root %#",
(value) => {
const parsed = parse(value);
expect(parsed.ok).toBe(false);
if (!parsed.ok) expect(parsed.error._tag).toBe("AnalysisInputError");
},
);
it("keeps source-scoped identities separate from exact method/path keys and declared IDs", () => {
const input = document({
"/a/~b": { get: { operationId: "same" } },
"/b": { get: { operationId: "same" } },
});
const first = report(input);
const copied = report(input, { ...artifact, path: "/copy.json" });
const revised = report(input, { ...artifact, sha256: "b".repeat(64) });
expect(first.operations[0]?.source_pointer).toBe("/paths/~1a~1~0b/get");
expect(copied.operations).toEqual(first.operations);
expect(revised.operations.map((row) => row.operation_key)).toEqual(
first.operations.map((row) => row.operation_key),
);
expect(revised.operations[0]?.operation_id).not.toBe(
first.operations[0]?.operation_id,
);
expect(new Set(first.operations.map((row) => row.operation_id)).size).toBe(2);
expect(first.operations.every((row) => row.declared_id === "same")).toBe(
true,
);
});
it("preserves unresolved local, cyclic and remote Path Items without following them", () => {
const input = document({
"/inline": { $ref: "#/paths/~1inline", get: { operationId: "inline" } },
"/local": { $ref: "./sibling.json#/paths/~1other" },
"/remote": { $ref: "http://127.0.0.1:9/reference.json" },
});
const value = report(input);
expect(value.path_item_references.map((row) => row.reference)).toEqual([
"#/paths/~1inline",
"./sibling.json#/paths/~1other",
"http://127.0.0.1:9/reference.json",
]);
expect(value.operations).toHaveLength(1);
expect(value.operations[0]).toMatchObject({
state: "unknown",
reason: "unresolved-path-item-reference",
});
expect(value.source_coverage.status).toBe("partial");
expect(value.summary).toMatchObject({
declared: 0,
unknown: 1,
unresolved_path_items: 3,
});
});
it("keeps usable siblings, malformed slots and missing values distinct", () => {
const input = document({
"/ok": { get: { operationId: "" }, post: { operationId: 0 } },
"/broken": { get: null },
"/bad-ref": { $ref: false, get: {} },
"/bad-item": 0,
invalid: { get: {} },
"x-doc": { get: {} },
});
const value = report(input);
expect(value.summary).toEqual({
operation_slots: 4,
declared: 2,
unknown: 2,
unresolved_path_items: 1,
diagnostics: 5,
});
expect(value.operations[0]?.declared_id).toBe("");
expect(value.operations[1]).toMatchObject({
declared_id: null,
state: "declared",
});
expect(value.operations[2]).toMatchObject({
state: "unknown",
reason: "malformed-operation",
});
expect(value.path_item_references[0]).toMatchObject({
state: "malformed",
reference: null,
});
expect(value.source_coverage.status).toBe("partial");
expect(value.diagnostics.map((row) => row.code)).toEqual([
"invalid-operation-id",
"invalid-operation",
"invalid-path-reference",
"invalid-path-item",
"invalid-path-key",
]);
});
it("excludes structured transport userinfo while preserving ordinary reference text", () => {
const value = report(
document({
"/absolute": {
$ref: "https://name:credential@example.test/schema.json?token=caller-text#part",
},
"/relative": {
$ref: "//name:credential@example.test/schema.json?ordinary=kept",
},
"/file": { $ref: "./ordinary@name.json#/components/schemas/password" },
}),
);
expect(
value.path_item_references.map(({ reference, credential_redacted }) => ({
reference,
credential_redacted,
})),
).toEqual([
{
reference: "https://example.test/schema.json?token=caller-text#part",
credential_redacted: true,
},
{
reference: "//example.test/schema.json?ordinary=kept",
credential_redacted: true,
},
{
reference: "./ordinary@name.json#/components/schemas/password",
credential_redacted: false,
},
]);
expect(JSON.stringify(value)).not.toContain("name:credential");
});
it("keeps an ambiguous credential spelling unknown without normalizing its reference identity", () => {
const value = report(
document({
"/ambiguous": {
$ref: "https:\\\\name:credential@example.test/schema.json",
},
}),
);
expect(value.path_item_references[0]).toMatchObject({
reference: null,
credential_redacted: true,
state: "unresolved",
});
expect(value.source_coverage.status).toBe("partial");
});
it("reports absent and malformed paths without calling them a complete empty API", () => {
const value = document(undefined);
delete (value as { paths?: unknown }).paths;
expect(report(value).source_coverage).toMatchObject({
status: "partial",
paths_state: "absent",
});
expect(
report({ ...value, openapi: "3.1.2", webhooks: { name: { post: {} } } })
.source_coverage,
).toMatchObject({
status: "complete-within-scope",
paths_state: "absent",
scope: "inline-path-operations",
});
expect(report(document(null)).source_coverage).toMatchObject({
status: "partial",
paths_state: "malformed",
});
});
it("handles 3.2 QUERY and case-sensitive additional methods, diagnosing invalid fixed-method duplicates", () => {
const value = report(
document(
{
"/x": {
query: {},
post: {},
additionalOperations: {
COPY: {},
post: {},
POST: {},
"bad method": {},
},
},
},
"3.2.1",
),
);
expect(value.operations.map((row) => row.method)).toEqual([
"QUERY",
"POST",
"COPY",
"post",
]);
expect(value.operations[2]?.source_pointer).toBe(
"/paths/~1x/additionalOperations/COPY",
);
expect(value.diagnostics.map((row) => row.code)).toEqual([
"invalid-additional-method",
"invalid-additional-method",
]);
expect(value.source_coverage.status).toBe("partial");
const older = report(
document(
{ "/x": { query: {}, additionalOperations: { COPY: {} }, GET: {} } },
"3.1.2",
),
);
expect(older.operations).toEqual([]);
expect(older.diagnostics.map((row) => row.code)).toEqual(
Array(3).fill("unknown-path-item-field"),
);
});
it("bounds expanded identities and source pointers before building a giant row", () => {
const result = parse(
document({
"/retained": { get: {} },
[`/${"a".repeat(1_100_000)}`]: { get: {} },
}),
);
expect(result.ok).toBe(false);
if (result.ok) throw new Error("Expected a retained-facts refusal");
expect(result.error._tag).toBe("AnalysisResourceConstraintError");
const partial = apiContractSchema.parse(result.error.partialObservation);
expect(partial.operations.map((row) => row.path)).toEqual(["/retained"]);
expect(partial.source_coverage).toMatchObject({
status: "partial",
path_entries_examined: 1,
});
});
it("keeps the invalid-info diagnostic when the paths diagnostic exhausts the allowance", () => {
const retainedBeforePaths =
"3.0.4".length * 12 +
4096 +
artifact.path.length * 12 +
1024 +
"/info".length * 12;
const title = "t".repeat(
Math.floor((API_CONTRACT_FACT_BYTES - retainedBeforePaths) / 12),
);
const result = parse({ openapi: "3.0.4", info: { title } });
expect(result.ok).toBe(false);
if (result.ok) throw new Error("Expected a retained-facts refusal");
const partial = apiContractSchema.parse(result.error.partialObservation);
expect(partial.diagnostics.map(({ code }) => code)).toEqual(["invalid-info"]);
expect(partial.info).toEqual({ title, version: null });
expect(partial.source_coverage.path_entries_examined).toBe(0);
});
it("retains an interpreted path when cancellation interrupts traversal", () => {
const input = document({
"/first": { get: { operationId: "first" } },
"/second": { get: { operationId: "second" } },
});
const steps = parseApiContractSteps(input, artifact);
for (let checkpoint = 0; checkpoint < 3; checkpoint++)
expect(steps.next().done).toBe(false);
const cancellation = new AnalysisCancelledError("inspect_api_contract");
const stopped = steps.throw(cancellation);
if (!stopped.done || stopped.value.ok)
throw new Error("Expected cancellation");
expect(stopped.value.error).toBe(cancellation);
const partial = apiContractSchema.parse(cancellation.partialObservation);
const complete = report(input);
expect(partial.operations).toEqual(complete.operations.slice(0, 1));
expect(partial.summary.operation_slots).toBe(1);
expect(partial.source_coverage).toMatchObject({
status: "partial",
path_entries_examined: 1,
});
expect(complete.source_coverage.status).toBe("complete-within-scope");
});
it("does not count a partially traversed Path Item as examined on cancellation", () => {
const input = document({
"/first": { get: {} },
"/second": {
post: {},
...Object.fromEntries(
Array.from({ length: 128 }, (_, index) => [`x-${index}`, "metadata"]),
),
},
});
const complete = report(input);
expect(complete.source_coverage.path_entries_examined).toBe(2);
let reachedCompletion = false;
let observedMidPathCancellation = false;
let observedCompletedFirstPath = false;
for (let checkpoint = 1; checkpoint <= 256; checkpoint++) {
const steps = parseApiContractSteps(input, artifact);
let done = false;
for (let advance = 0; advance < checkpoint; advance++) {
const next = steps.next();
if (next.done) {
expect(next.value).toEqual({ ok: true, value: complete });
done = true;
break;
}
}
if (done) {
reachedCompletion = true;
break;
}
const reason = { stage: "path-traversal", checkpoint };
const cancellation = new AnalysisCancelledError("inspect_api_contract", {
cause: reason,
});
const stopped = steps.throw(cancellation);
if (!stopped.done || stopped.value.ok)
throw new Error("Expected cancellation");
expect(stopped.value.error).toBe(cancellation);
expect(stopped.value.error.cause).toBe(reason);
if (cancellation.partialObservation === undefined) continue;
const partial = apiContractSchema.parse(cancellation.partialObservation);
expect(partial.artifact).toEqual(complete.artifact);
expect(partial.contract_id).toBe(complete.contract_id);
expect(partial.info).toEqual(complete.info);
expect(partial.operations).toEqual(
complete.operations.slice(0, partial.operations.length),
);
expect(partial.summary.operation_slots).toBe(partial.operations.length);
expect(partial.source_coverage.status).toBe("partial");
// Every actual yield precedes completion of the second (last) Path Item.
expect(partial.source_coverage.path_entries_examined).toBeLessThan(2);
expect(partial.source_coverage.path_entries_examined).toBeLessThanOrEqual(
partial.operations.length,
);
if (partial.source_coverage.path_entries_examined === 1) {
if (partial.operations.length === 1) observedCompletedFirstPath = true;
if (partial.operations.length === 2) observedMidPathCancellation = true;
}
}
expect(reachedCompletion).toBe(true);
expect(observedCompletedFirstPath).toBe(true);
expect(observedMidPathCancellation).toBe(true);
});