Files
reverse-engineering-anything/src/domain/apiContract/parseApiContract.ts
T
morluto b51ed4c3ec refactor(kernel): migrate the remaining SHA-256 hex digests to sha256Hex and move isRecord into src/kernel (#11571)
* refactor(kernel): migrate the remaining one-shot SHA-256 hex digests to sha256Hex

* refactor(kernel): move isRecord into src/kernel and replace its inline copies (#11574)

* fix(scripts): import isRecord from src/kernel in the managed manifest parser
2026-11-15 20:53:36 -05:00

484 lines
16 KiB
TypeScript

import { Budget } from "../budget.js";
import { escapeJsonPointerToken } from "../jsonPointer.js";
import {
AnalysisCancelledError,
AnalysisInputError,
AnalysisResourceConstraintError,
AnalysisUnsupportedTargetError,
} from "../analysisErrorCore.js";
import type { AnalysisError } from "../analysisErrorBase.js";
import { digestCanonicalValue } from "../canonicalDigest.js";
import { err, ok, type Result } from "../result.js";
import { parseRecordedTransportUrl } from "../recordedTransportUrl.js";
import {
API_CONTRACT_FACT_BYTES,
API_CONTRACT_OPERATION,
type ApiContract,
type ApiContractArtifact,
type ApiContractDiagnostic,
type ApiContractOperation,
} from "./apiContract.js";
import { isRecord } from "../../kernel/isRecord.js";
const methods = [
"get",
"put",
"post",
"delete",
"options",
"head",
"patch",
"trace",
] as const;
const modernMethods = [...methods, "query"];
const reservedAdditionalMethods = new Set(
modernMethods.map((method) => method.toUpperCase()),
);
const pathMetadata = new Set([
"$ref",
"summary",
"description",
"servers",
"parameters",
]);
// HTTP methods are case-sensitive tokens; additionalOperations preserves that spelling.
const httpToken = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
const record = (value: unknown): Record<string, unknown> | undefined =>
isRecord(value) ? (value as Record<string, unknown>) : undefined;
const identity = (prefix: string, facts: unknown) =>
`${prefix}_${digestCanonicalValue(facts)}`;
interface OperationSlot {
readonly path: string;
readonly method: string;
readonly pointer: string;
readonly hasReference: boolean;
}
/** Own compact declarations and account for repeated path/pointer serialization before allocation. */
class ContractInventory {
readonly operations: ApiContract["operations"] = [];
readonly references: ApiContract["path_item_references"] = [];
readonly diagnostics: ApiContractDiagnostic[] = [];
readonly #retainedBytes = new Budget(API_CONTRACT_FACT_BYTES);
constructor(readonly artifact: ApiContractArtifact) {}
reserve(bytes: number): Result<void, AnalysisError> {
// Includes object/index overhead and repeated escaped Evidence delivery, not just source bytes.
return this.#retainedBytes.tryCharge(bytes)
? ok(undefined)
: err(
new AnalysisResourceConstraintError(
API_CONTRACT_OPERATION,
"memory",
"API contract declarations exceed the retained-facts representation allowance.",
{ representation_bytes: API_CONTRACT_FACT_BYTES },
{
retryable: false,
remediationAction:
"Select a smaller complete API document; paging the reply does not increase the parser's retained-facts allowance.",
},
),
);
}
diagnostic(
code: ApiContractDiagnostic["code"],
pointer: string,
message: string,
): Result<void, AnalysisError> {
const admitted = this.reserve(1024 + pointer.length * 12);
if (!admitted.ok) return admitted;
this.diagnostics.push({
diagnostic_id: identity("api_contract_diagnostic", [
this.artifact.sha256,
pointer,
code,
]),
source_pointer: pointer,
code,
message,
});
return ok(undefined);
}
reference(
path: string,
pointer: string,
value: unknown,
): Result<void, AnalysisError> {
const admitted = this.reserve(
1024 +
path.length * 12 +
(typeof value === "string" ? value.length * 12 : 0),
);
if (!admitted.ok) return admitted;
const credentials =
typeof value === "string"
? parseRecordedTransportUrl(value).credentials
: null;
const reference =
typeof value !== "string" || credentials === "ambiguous"
? null
: credentials === null
? value
: value.slice(0, credentials.start) + value.slice(credentials.end);
this.references.push({
reference_id: identity("api_path_reference", [
this.artifact.sha256,
pointer,
]),
path,
source_pointer: pointer,
reference,
credential_redacted: credentials !== null,
state: typeof value === "string" ? "unresolved" : "malformed",
});
return typeof value === "string"
? ok(undefined)
: this.diagnostic(
"invalid-path-reference",
pointer,
"Path Item $ref must be a string; reference resolution was not attempted.",
);
}
operation(value: unknown, slot: OperationSlot): Result<void, AnalysisError> {
const object = record(value);
const declaredId =
typeof object?.operationId === "string" ? object.operationId : null;
const admitted = this.reserve(
1536 +
slot.path.length * 32 +
slot.method.length * 24 +
(declaredId?.length ?? 0) * 12,
);
if (!admitted.ok) return admitted;
const reason: ApiContractOperation["reason"] =
object === undefined
? "malformed-operation"
: slot.hasReference
? "unresolved-path-item-reference"
: null;
this.operations.push({
operation_id: identity("api_operation", [
this.artifact.sha256,
slot.pointer,
]),
operation_key: identity("api_operation_key", [slot.path, slot.method]),
method: slot.method,
path: slot.path,
declared_id: declaredId,
source_pointer: slot.pointer,
state: reason === null ? "declared" : "unknown",
reason,
});
if (object === undefined)
return this.diagnostic(
"invalid-operation",
slot.pointer,
"The method's value is not an Operation Object.",
);
if (Object.hasOwn(object, "operationId") && declaredId === null)
return this.diagnostic(
"invalid-operation-id",
`${slot.pointer}/operationId`,
"operationId is present but is not a string; its identity remains unavailable.",
);
return ok(undefined);
}
}
const infoFacts = (
root: Record<string, unknown>,
inventory: ContractInventory,
): Result<ApiContract["info"], AnalysisError> => {
const info = record(root.info);
const title = typeof info?.title === "string" ? info.title : null;
const version = typeof info?.version === "string" ? info.version : null;
const admitted = inventory.reserve(
4096 +
inventory.artifact.path.length * 12 +
(title?.length ?? 0) * 12 +
(version?.length ?? 0) * 12,
);
if (!admitted.ok) return admitted;
if (info === undefined || title === null || version === null) {
const diagnosed = inventory.diagnostic(
"invalid-info",
"/info",
"Info title/version are not both present strings; usable metadata and operation slots are retained without claiming a valid OpenAPI document.",
);
if (!diagnosed.ok) return diagnosed;
}
return ok({ title, version });
};
function* additionalOperations(
value: unknown,
context: {
inventory: ContractInventory;
path: string;
pointer: string;
hasReference: boolean;
},
): Generator<void, Result<void, AnalysisError>> {
const { inventory, path, pointer, hasReference } = context;
const operations = record(value);
if (operations === undefined)
return inventory.diagnostic(
"invalid-additional-operations",
pointer,
"additionalOperations must be an object mapping HTTP method tokens to Operation Objects.",
);
let examined = 0;
for (const method in operations) {
if (!Object.hasOwn(operations, method)) continue;
if (examined++ % 128 === 0) yield;
const admitted = inventory.reserve(512 + method.length * 24);
if (!admitted.ok) return admitted;
const source = `${pointer}/${escapeJsonPointerToken(method)}`;
const reserved = reservedAdditionalMethods.has(method);
const added =
!httpToken.test(method) || reserved
? inventory.diagnostic(
"invalid-additional-method",
source,
"The additional HTTP method is not a token or duplicates a fixed method; it is not treated as a valid operation.",
)
: inventory.operation(operations[method], {
path,
method,
pointer: source,
hasReference,
});
if (!added.ok) return added;
}
return ok(undefined);
}
function* pathItem(
value: unknown,
context: {
inventory: ContractInventory;
path: string;
pointer: string;
modern: boolean;
},
): Generator<void, Result<void, AnalysisError>> {
const { inventory, path, pointer, modern } = context;
const item = record(value);
if (item === undefined)
return inventory.diagnostic(
"invalid-path-item",
pointer,
"Path Item must be an object; its operations are unknown.",
);
const hasReference = Object.hasOwn(item, "$ref");
if (hasReference) {
const added = inventory.reference(path, `${pointer}/$ref`, item.$ref);
if (!added.ok) return added;
}
const fixedMethods: readonly string[] = modern ? modernMethods : methods;
let examined = 0;
for (const key in item) {
if (!Object.hasOwn(item, key)) continue;
if (examined++ % 128 === 0) yield;
if (fixedMethods.includes(key)) {
const added = inventory.operation(item[key], {
path,
method: key.toUpperCase(),
pointer: `${pointer}/${key}`,
hasReference,
});
if (!added.ok) return added;
} else if (key === "additionalOperations" && modern) {
const added = yield* additionalOperations(item[key], {
inventory,
path,
pointer: `${pointer}/${key}`,
hasReference,
});
if (!added.ok) return added;
} else if (!pathMetadata.has(key) && !key.startsWith("x-")) {
const admitted = inventory.reserve(512 + key.length * 24);
if (!admitted.ok) return admitted;
const diagnosed = inventory.diagnostic(
"unknown-path-item-field",
`${pointer}/${escapeJsonPointerToken(key)}`,
"This field is not an operation or a recognized Path Item field in the selected OpenAPI minor version.",
);
if (!diagnosed.ok) return diagnosed;
}
}
return ok(undefined);
}
interface ContractReportContext {
readonly openapi: string;
readonly info: ApiContract["info"];
readonly pathsState: ApiContract["source_coverage"]["paths_state"];
examined: number;
}
const contractReport = (
inventory: ContractInventory,
context: ContractReportContext,
incomplete = false,
): ApiContract => {
const artifact = inventory.artifact;
let declared = 0;
for (const operation of inventory.operations)
if (operation.state === "declared") declared++;
return {
contract_id: `api_contract_${artifact.sha256}`,
format: "openapi-json",
openapi: context.openapi,
artifact,
info: context.info,
operations: inventory.operations,
path_item_references: inventory.references,
diagnostics: inventory.diagnostics,
summary: {
operation_slots: inventory.operations.length,
declared,
unknown: inventory.operations.length - declared,
unresolved_path_items: inventory.references.length,
diagnostics: inventory.diagnostics.length,
},
source_coverage: {
scope: "inline-path-operations",
status:
incomplete ||
inventory.references.length > 0 ||
inventory.diagnostics.length > 0
? "partial"
: "complete-within-scope",
paths_state: context.pathsState,
path_entries_examined: context.examined,
reference_resolution: "not-attempted",
schema_validation: "not-performed",
duplicate_json_members: "last-value-wins",
},
limitations: [
...(incomplete
? [
"Traversal stopped before the inventory was complete. Row counts describe retained facts; path_entries_examined counts fully traversed entries, excluding an interrupted entry whose rows may be retained.",
]
: []),
"Operations are document declarations, not evidence of runtime implementation, reachability or authorization.",
"Only inline operations under paths are inventoried; callbacks, webhooks, components, servers, parameters, schemas, request/response contracts and security are not analyzed.",
"No reference is resolved, including local fragments. A Path Item reference makes its effective operations unknown; adjacent inline slots are preserved without merging referenced definitions.",
"Transport userinfo credentials are excluded from reference URIs. credential_redacted marks the exclusion; an ambiguous credential span leaves the displayed reference unknown. Other reference text is preserved.",
"This is a structural inventory, not full OpenAPI schema validation. operationId values are preserved without assuming uniqueness; operation_key matches exact method/path spelling, not semantic equivalence across APIs.",
"Source JSON members use last-value-wins parsing. Original bytes remain in the caller-selected artifact, identified by SHA-256; this Evidence does not embed the complete source document.",
],
};
};
function* collectPaths(
sourcePaths: Record<string, unknown>,
inventory: ContractInventory,
context: ContractReportContext,
modern: boolean,
): Generator<void, Result<void, AnalysisError>> {
for (const path in sourcePaths) {
if (!Object.hasOwn(sourcePaths, path) || path.startsWith("x-")) continue;
yield;
// Reserve expanded pointer/path strings before escaping or building a row.
const admitted = inventory.reserve(512 + path.length * 16);
if (!admitted.ok) return admitted;
const pointer = `/paths/${escapeJsonPointerToken(path)}`;
const read = path.startsWith("/")
? yield* pathItem(sourcePaths[path], { inventory, path, pointer, modern })
: inventory.diagnostic(
"invalid-path-key",
pointer,
"A Paths entry must start with /; it was not interpreted as an endpoint.",
);
if (!read.ok) return read;
context.examined++;
}
return ok(undefined);
}
/** Enumerate declarations only; never resolve references, servers, callbacks or runtime expressions. */
export function* parseApiContractSteps(
value: unknown,
artifact: ApiContractArtifact,
): Generator<void, Result<ApiContract, AnalysisError>> {
const root = record(value);
if (root === undefined || typeof root.openapi !== "string")
return err(
new AnalysisInputError(API_CONTRACT_OPERATION, undefined, [
{
path: ["path"],
reason: "invalid_format",
message:
"Expected an OpenAPI JSON object with an openapi version string.",
},
]),
);
const version = /^3\.([012])\.(?:0|[1-9][0-9]*)$/u.exec(root.openapi);
if (version === null)
return err(
new AnalysisUnsupportedTargetError(
API_CONTRACT_OPERATION,
artifact.path,
"Only OpenAPI 3.0, 3.1 and 3.2 JSON documents are supported.",
),
);
const inventory = new ContractInventory(artifact);
const versionAdmitted = inventory.reserve(root.openapi.length * 12);
if (!versionAdmitted.ok) return versionAdmitted;
const info = infoFacts(root, inventory);
if (!info.ok) return info;
const paths = record(root.paths);
const pathsState =
paths !== undefined
? "object"
: Object.hasOwn(root, "paths")
? "malformed"
: "absent";
const context: ContractReportContext = {
openapi: root.openapi,
info: info.value,
pathsState,
examined: 0,
};
const interrupted = (error: AnalysisError) => {
const retainedRows =
inventory.operations.length +
inventory.references.length +
inventory.diagnostics.length;
if (retainedRows > 0)
error.retainPartialObservation(contractReport(inventory, context, true));
return err(error);
};
if (
pathsState === "malformed" ||
(pathsState === "absent" && version[1] === "0")
) {
const diagnosed = inventory.diagnostic(
"invalid-paths",
"/paths",
"paths must be an object and is required for OpenAPI 3.0; a missing or malformed inventory is not proof of zero operations.",
);
if (!diagnosed.ok) return interrupted(diagnosed.error);
}
try {
const read = yield* collectPaths(
paths ?? {},
inventory,
context,
version[1] === "2",
);
if (!read.ok) return interrupted(read.error);
} catch (cause: unknown) {
if (cause instanceof AnalysisCancelledError) return interrupted(cause);
throw cause;
}
return ok(contractReport(inventory, context));
}