Files
reverse-engineering-anything/src/domain/apiContract/parseApiContract.ts
T
morluto 64c119df47 refactor(domain): charge remaining fixed allowances through Budget (#11319)
* refactor(domain): charge the Interface Builder, NativeAOT, managed and runtime budgets through Budget

* test(browser): show a refused runtime retention charge leaves the room intact

* refactor(domain): charge the remaining fixed allowances through Budget (#11383)

* refactor(domain): charge CUDA metadata and SQLite reply budgets through Budget

CudaMetadataBudget (visits, section reads, temporary index) and the SQLite
OutputBudget kept hand-written allowances whose field names escaped the
budget-arithmetic guard; the SQLite reply budget also charged each part
before checking it. Both now charge Budget, which refuses an oversized
charge without changing the remainder.

The guard now also counts, inside any hand-written ...Budget class, a field
that is adjusted by hand and compared with < or >, whatever its name.
Unchecked tallies (a yield counter, a reservation ledger) stay uncounted.
Firmware arena cursors are write offsets, not allowances: they are renamed
#arenaWriteOffset and leave the guard's scope. Baseline 17 -> 15.

* refactor(domain): move cache, re-priced, checkpointed and ledger retention onto Budget

Budget gains chargeEvicting (evict the oldest cache entries until a charge
fits) and restore (refund everything charged since a used mark, never
re-charging). With them:

- the Bun metadata range cache evicts through chargeEvicting and charges
  physical reads through a second Budget;
- Playwright scenario events refund an event's old cost and try-charge its
  re-priced cost, and admission charges with tryCharge;
- WebNetworkProjectionAccumulator keeps one shared allowance plus retained
  and temporary shares whose checkpoints restore by refunding;
- EvidenceLedger commits its admitted delta (charge, or refund when a
  replacement shrinks) and clears with restore(0);
- the web bundle worker charges an admitted result, and on the completed-
  snapshot path retains facts only when they still fit;
- the Pyc nested code walk charges steps and retained references.

budget-arithmetic 15 -> 4 (JavaScriptAnalysisWorker only).

* build(verify): declare the budget-arithmetic guard's counter for typed tests
2026-11-16 03:08:28 +08:00

485 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";
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 =>
typeof value === "object" && value !== null && !Array.isArray(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));
}