@gajae-code/ai 0.15.6 → 0.16.0

package/src/utils/schema/dereference.ts

@@ -11,69 +11,190 @@
  */
 import { isJsonObject, type JsonObject } from "./types";
 
-/**
- * Resolve a JSON-pointer-style `$ref` against the root schema's `$defs`
- * or `definitions` block. Returns `undefined` for external or unresolvable refs.
- */
-function resolveLocalRef(ref: string, root: JsonObject): JsonObject | undefined {
-	// Only handle local refs: #/$defs/Name or #/definitions/Name
-	const match = /^#\/(\$defs|definitions)\/(.+)$/.exec(ref);
-	if (!match) return undefined;
+const JSON_SCHEMA_LITERAL_PAYLOAD_KEYS = new Set(["default", "const", "enum", "examples"]);
+const JSON_SCHEMA_MAP_KEYS = new Set([
+	"properties",
+	"patternProperties",
+	"dependencies",
+	"dependentSchemas",
+	"$defs",
+	"definitions",
+]);
+
+function setOwnKey(target: JsonObject, key: string, value: unknown): void {
+	if (key === "__proto__") {
+		Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+		return;
+	}
+	target[key] = value;
+}
+
+type DereferenceState = {
+	unresolvedRef: boolean;
+};
+
+/** Resolve any local JSON Pointer, including escaped names and boolean schemas. */
+function resolveLocalRef(ref: string, root: JsonObject): unknown | undefined {
+	if (!ref.startsWith("#")) return undefined;
+	let pointer: string;
+	try {
+		pointer = decodeURIComponent(ref.slice(1));
+	} catch {
+		return undefined;
+	}
+	if (pointer === "") return root;
+	if (!pointer.startsWith("/")) return undefined;
 
-	const [, defsKey, name] = match;
-	const defs = root[defsKey!];
-	if (!isJsonObject(defs)) return undefined;
+	let current: unknown = root;
+	for (const encodedSegment of pointer.slice(1).split("/")) {
+		const segment = encodedSegment.replaceAll("~1", "/").replaceAll("~0", "~");
+		if (Array.isArray(current)) {
+			if (!/^(0|[1-9]\d*)$/.test(segment) || !Object.hasOwn(current, segment)) return undefined;
+			current = current[Number(segment)];
+		} else if (isJsonObject(current)) {
+			if (!Object.hasOwn(current, segment)) return undefined;
+			current = current[segment];
+		} else {
+			return undefined;
+		}
+	}
+	return current;
+}
 
-	const resolved = defs[name!];
-	return isJsonObject(resolved) ? resolved : undefined;
+/** Find definition maps anywhere in a schema graph, excluding literal instance data. */
+function hasDefinitionMapDeep(value: unknown, seen: Set<object>, inSchemaMap = false): boolean {
+	if (Array.isArray(value)) {
+		if (seen.has(value)) return false;
+		seen.add(value);
+		return value.some(entry => hasDefinitionMapDeep(entry, seen, false));
+	}
+	if (!isJsonObject(value) || seen.has(value)) return false;
+	seen.add(value);
+	for (const key in value) {
+		if (!Object.hasOwn(value, key)) continue;
+		if (!inSchemaMap && (key === "$defs" || key === "definitions")) return true;
+		if (!inSchemaMap && JSON_SCHEMA_LITERAL_PAYLOAD_KEYS.has(key)) continue;
+		const childInSchemaMap = !inSchemaMap && JSON_SCHEMA_MAP_KEYS.has(key);
+		if (hasDefinitionMapDeep(value[key], seen, childInSchemaMap)) return true;
+	}
+	return false;
+}
+
+function dereferenceSchemaMap(
+	schemaMap: JsonObject,
+	root: JsonObject,
+	visitingRefs: Set<string>,
+	visitingNodes: Set<object>,
+	state: DereferenceState,
+): JsonObject {
+	const result: JsonObject = {};
+	for (const key in schemaMap) {
+		if (!Object.hasOwn(schemaMap, key)) continue;
+		setOwnKey(result, key, dereferenceNode(schemaMap[key], root, visitingRefs, visitingNodes, state));
+	}
+	return result;
 }
 
 /**
  * Recursively dereference a JSON Schema node, inlining all local `$ref` pointers.
+ * Object and array path tracking preserves the existing `{}` cycle boundary.
  */
-function dereferenceNode(node: unknown, root: JsonObject, visiting: Set<string>): unknown {
-	if (!isJsonObject(node)) return node;
-	if (Array.isArray(node)) return node.map(item => dereferenceNode(item, root, visiting));
+function dereferenceNode(
+	node: unknown,
+	root: JsonObject,
+	visitingRefs: Set<string>,
+	visitingNodes: Set<object>,
+	state: DereferenceState,
+	inSchemaMap = false,
+): unknown {
+	if (!node || typeof node !== "object") return node;
+	if (visitingNodes.has(node)) return {};
+	visitingNodes.add(node);
+
+	if (Array.isArray(node)) {
+		const result = node.map(item => dereferenceNode(item, root, visitingRefs, visitingNodes, state));
+		visitingNodes.delete(node);
+		return result;
+	}
 
-	const ref = node.$ref;
+	const schemaNode = node as JsonObject;
+	const ref = Object.hasOwn(schemaNode, "$ref") ? schemaNode.$ref : undefined;
 	if (typeof ref === "string") {
-		// Break circular references
-		if (visiting.has(ref)) return {};
+		if (visitingRefs.has(ref)) {
+			visitingNodes.delete(node);
+			return {};
+		}
 		const resolved = resolveLocalRef(ref, root);
-		if (!resolved) return node; // External ref — leave as-is
-		visiting.add(ref);
-		const inlined = dereferenceNode(resolved, root, visiting);
-		visiting.delete(ref);
+		if (resolved !== undefined) {
+			visitingRefs.add(ref);
+			const inlined = dereferenceNode(resolved, root, visitingRefs, visitingNodes, state);
+			visitingRefs.delete(ref);
 
-		// Merge sibling keywords (e.g. description, default) from the
-		// referencing node. In draft 2020-12 these are valid alongside $ref.
-		let hasSiblings = false;
-		for (const k in node) {
-			if (k !== "$ref") {
-				hasSiblings = true;
-				break;
+			// Merge sibling keywords (e.g. description, default) from the
+			// referencing node. In draft 2020-12 these are valid alongside `$ref`.
+			let hasSiblings = false;
+			for (const key in schemaNode) {
+				if (Object.hasOwn(schemaNode, key) && key !== "$ref") {
+					hasSiblings = true;
+					break;
+				}
+			}
+			if (inlined === false) {
+				visitingNodes.delete(node);
+				return false;
+			}
+			if (!hasSiblings || (!isJsonObject(inlined) && inlined !== true)) {
+				visitingNodes.delete(node);
+				return inlined;
 			}
+			const merged: JsonObject = {};
+			if (isJsonObject(inlined)) {
+				for (const key in inlined) {
+					if (Object.hasOwn(inlined, key)) setOwnKey(merged, key, inlined[key]);
+				}
+			}
+			for (const key in schemaNode) {
+				if (!Object.hasOwn(schemaNode, key) || key === "$ref") continue;
+				const siblingValue = schemaNode[key];
+				const sibling =
+					!inSchemaMap && JSON_SCHEMA_LITERAL_PAYLOAD_KEYS.has(key)
+						? schemaNode[key]
+						: !inSchemaMap && JSON_SCHEMA_MAP_KEYS.has(key) && isJsonObject(siblingValue)
+							? dereferenceSchemaMap(siblingValue, root, visitingRefs, visitingNodes, state)
+							: dereferenceNode(siblingValue, root, visitingRefs, visitingNodes, state);
+				setOwnKey(merged, key, sibling);
+			}
+			if (!state.unresolvedRef) {
+				delete merged.$defs;
+				delete merged.definitions;
+			}
+			visitingNodes.delete(node);
+			return merged;
 		}
-		if (!hasSiblings || !isJsonObject(inlined)) return inlined;
-		const merged: JsonObject = { ...inlined, ...node };
-		delete merged.$ref;
-		return merged;
+		state.unresolvedRef = true;
 	}
 
 	const result: JsonObject = {};
-	for (const key in node) {
-		const value = node[key];
-		// Skip $defs/definitions — they get inlined into consumers
-		if (key === "$defs" || key === "definitions") continue;
-
-		if (Array.isArray(value)) {
-			result[key] = value.map(item => dereferenceNode(item, root, visiting));
-		} else if (isJsonObject(value)) {
-			result[key] = dereferenceNode(value, root, visiting);
-		} else {
-			result[key] = value;
+	for (const key in schemaNode) {
+		if (!Object.hasOwn(schemaNode, key)) continue;
+		const value = schemaNode[key];
+		// Literal instance data is not schema-shaped, even when it contains an
+		// object that happens to use schema-looking keys or a local `$ref`.
+		if (!inSchemaMap && JSON_SCHEMA_LITERAL_PAYLOAD_KEYS.has(key)) {
+			setOwnKey(result, key, value);
+			continue;
+		}
+		if (!inSchemaMap && JSON_SCHEMA_MAP_KEYS.has(key) && isJsonObject(value)) {
+			setOwnKey(result, key, dereferenceSchemaMap(value, root, visitingRefs, visitingNodes, state));
+			continue;
 		}
+		setOwnKey(result, key, dereferenceNode(value, root, visitingRefs, visitingNodes, state));
+	}
+	if (!state.unresolvedRef) {
+		delete result.$defs;
+		delete result.definitions;
 	}
+	visitingNodes.delete(node);
 	return result;
 }
 
@@ -90,9 +211,8 @@ function dereferenceNode(node: unknown, root: JsonObject, visiting: Set<string>)
 export function dereferenceJsonSchema(schema: unknown): unknown {
 	if (!isJsonObject(schema)) return schema;
 
-	// Fast path: nothing to dereference
-	const hasDefs = schema.$defs !== undefined || schema.definitions !== undefined;
-	if (!hasDefs) return schema;
+	// Fast path: nothing to dereference anywhere in the schema graph
+	if (!hasDefinitionMapDeep(schema, new Set())) return schema;
 
-	return dereferenceNode(schema, schema, new Set());
+	return dereferenceNode(schema, schema, new Set(), new Set(), { unresolvedRef: false });
 }

package/src/utils/schema/draft.ts

@@ -17,7 +17,7 @@ const DRAFT_07_SCHEMA_URIS: Record<string, true> = {
  * entry rather than the map object itself so legacy `definitions`-style refs
  * inside property schemas get rewritten.
  */
-const SCHEMA_MAP_KEYS: Record<string, true> = { properties: true, patternProperties: true, dependentSchemas: true };
+const SCHEMA_MAP_KEYS = new Set(["properties", "patternProperties", "dependentSchemas"]);
 /**
  * Keys whose values are JSON-Schema *values*, not nested schemas. The upgrade
  * walker must NOT descend into these — `type: ["string","null"]` is not a
@@ -34,6 +34,14 @@ const NON_SCHEMA_VALUE_KEYS: Record<string, true> = {
 	type: true,
 };
 
+function setOwnKey(target: JsonObject, key: string, value: unknown): void {
+	if (key === "__proto__") {
+		Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+		return;
+	}
+	target[key] = value;
+}
+
 /** Rewrite draft-07's `#/definitions/Foo` ref form to draft 2020-12's `#/$defs/Foo`. External refs (`http://…`) pass through. */
 function convertRef(value: string): string {
 	return value.startsWith("#/definitions/") ? `#/$defs/${value.slice("#/definitions/".length)}` : value;
@@ -41,10 +49,10 @@ function convertRef(value: string): string {
 
 /** Get-or-create a child object map on `target[key]`. Used to lazily build up `$defs`/`dependentRequired`/`dependentSchemas` during conversion. */
 function getObjectMap(target: JsonObject, key: string): JsonObject {
-	const existing = target[key];
+	const existing = Object.hasOwn(target, key) ? target[key] : undefined;
 	if (isJsonObject(existing)) return existing;
 	const next: JsonObject = {};
-	target[key] = next;
+	setOwnKey(target, key, next);
 	return next;
 }
 
@@ -52,13 +60,14 @@ function getObjectMap(target: JsonObject, key: string): JsonObject {
 function mergeSchemaMap(target: JsonObject, key: string, value: JsonObject, cache: WeakMap<object, unknown>): void {
 	const map = getObjectMap(target, key);
 	for (const name in value) {
-		map[name] = upgradeJsonSchemaTo202012Impl(value[name], cache);
+		if (!Object.hasOwn(value, name)) continue;
+		setOwnKey(map, name, upgradeJsonSchemaTo202012Impl(value[name], cache));
 	}
 }
 /** Copy a schema-map field with upgrade; non-object values are passed through verbatim. */
 function copySchemaMap(target: JsonObject, key: string, value: unknown, cache: WeakMap<object, unknown>): void {
 	if (!isJsonObject(value)) {
-		target[key] = value;
+		setOwnKey(target, key, value);
 		return;
 	}
 	mergeSchemaMap(target, key, value, cache);
@@ -107,20 +116,21 @@ function mergePrefixItems(existing: unknown, convertedItems: unknown[]): unknown
 /** Record `key → deps` in `dependentRequired`, unioning with any existing array. */
 function mergeDependentRequired(target: JsonObject, key: string, deps: unknown[]): void {
 	const dependentRequired = getObjectMap(target, "dependentRequired");
-	const existing = dependentRequired[key];
+	const existing = Object.hasOwn(dependentRequired, key) ? dependentRequired[key] : undefined;
 	if (existing === undefined) {
-		dependentRequired[key] = deps;
+		setOwnKey(dependentRequired, key, deps);
 		return;
 	}
 	if (Array.isArray(existing)) {
-		dependentRequired[key] = mergeArrayValues(existing, deps);
+		setOwnKey(dependentRequired, key, mergeArrayValues(existing, deps));
 	}
 }
 
 /** Record `key → schema` in `dependentSchemas`, intersecting with any existing entry. */
 function mergeDependentSchema(target: JsonObject, key: string, schema: unknown): void {
 	const dependentSchemas = getObjectMap(target, "dependentSchemas");
-	dependentSchemas[key] = combineSchemas(dependentSchemas[key], schema);
+	const existing = Object.hasOwn(dependentSchemas, key) ? dependentSchemas[key] : undefined;
+	setOwnKey(dependentSchemas, key, combineSchemas(existing, schema));
 }
 
 /**
@@ -130,9 +140,10 @@ function mergeDependentSchema(target: JsonObject, key: string, schema: unknown):
  *   - schema value → `dependentSchemas`
  */
 function convertDependencies(source: JsonObject, target: JsonObject, cache: WeakMap<object, unknown>): void {
-	const dependencies = source.dependencies;
+	const dependencies = Object.hasOwn(source, "dependencies") ? source.dependencies : undefined;
 	if (!isJsonObject(dependencies)) return;
 	for (const key in dependencies) {
+		if (!Object.hasOwn(dependencies, key)) continue;
 		const dependency = dependencies[key];
 		const converted = upgradeJsonSchemaTo202012Impl(dependency, cache);
 		if (Array.isArray(converted)) {
@@ -150,7 +161,9 @@ function hasNullType(type: unknown): boolean {
 
 /** True if any variant in `anyOf` declares (only) a null type. Used to avoid double-adding `{type:"null"}`. */
 function hasNullVariant(variants: unknown[]): boolean {
-	return variants.some(variant => isJsonObject(variant) && hasNullType(variant.type));
+	return variants.some(
+		variant => isJsonObject(variant) && Object.hasOwn(variant, "type") && hasNullType(variant.type),
+	);
 }
 
 /**
@@ -182,6 +195,7 @@ function makeNullable(schema: JsonObject): JsonObject {
 function schemaMapNeedsDraft202012Upgrade(value: unknown, epoch: number): boolean {
 	if (!isJsonObject(value)) return false;
 	for (const k in value) {
+		if (!Object.hasOwn(value, k)) continue;
 		if (schemaNeedsDraft202012UpgradeImpl(value[k], epoch)) return true;
 	}
 	return false;
@@ -203,9 +217,10 @@ function schemaNeedsDraft202012UpgradeImpl(value: unknown, epoch: number): boole
 	if (!once(value, epoch)) return false;
 
 	for (const key in value) {
+		if (!Object.hasOwn(value, key)) continue;
 		const entry = value[key];
 		if (key === "$schema") {
-			if (typeof entry === "string" && entry in DRAFT_07_SCHEMA_URIS) return true;
+			if (typeof entry === "string" && Object.hasOwn(DRAFT_07_SCHEMA_URIS, entry)) return true;
 			continue;
 		}
 		if (key === "definitions" || key === "dependencies" || key === "additionalItems" || key === "nullable") {
@@ -216,11 +231,11 @@ function schemaNeedsDraft202012UpgradeImpl(value: unknown, epoch: number): boole
 			continue;
 		}
 		if (key === "items" && Array.isArray(entry)) return true;
-		if (key === "$defs" || key in SCHEMA_MAP_KEYS) {
+		if (key === "$defs" || SCHEMA_MAP_KEYS.has(key)) {
 			if (schemaMapNeedsDraft202012Upgrade(entry, epoch)) return true;
 			continue;
 		}
-		if (key in NON_SCHEMA_VALUE_KEYS) continue;
+		if (Object.hasOwn(NON_SCHEMA_VALUE_KEYS, key)) continue;
 		if (schemaNeedsDraft202012UpgradeImpl(entry, epoch)) return true;
 	}
 
@@ -253,6 +268,7 @@ function upgradeJsonSchemaTo202012Impl(value: unknown, cache: WeakMap<object, un
 	// Seed cache before recursion so back-edges in cyclic graphs resolve.
 	cache.set(value, result);
 	for (const key in value) {
+		if (!Object.hasOwn(value, key)) continue;
 		const entry = value[key];
 		// `definitions` is the draft-07 name; merge under the canonical `$defs`.
 		// `$defs` may appear pre-upgraded — still walk entries to upgrade their bodies.
@@ -261,13 +277,13 @@ function upgradeJsonSchemaTo202012Impl(value: unknown, cache: WeakMap<object, un
 			continue;
 		}
 		// Recurse into each entry; the map shape itself is preserved.
-		if (key in SCHEMA_MAP_KEYS) {
+		if (SCHEMA_MAP_KEYS.has(key)) {
 			copySchemaMap(result, key, entry, cache);
 			continue;
 		}
 		// JSON-Schema *value* keywords — copy verbatim.
-		if (key in NON_SCHEMA_VALUE_KEYS) {
-			result[key] = entry;
+		if (Object.hasOwn(NON_SCHEMA_VALUE_KEYS, key)) {
+			setOwnKey(result, key, entry);
 			continue;
 		}
 		// Draft-07-only keywords with no draft 2020-12 spelling — drop entirely.
@@ -278,7 +294,9 @@ function upgradeJsonSchemaTo202012Impl(value: unknown, cache: WeakMap<object, un
 		// Rewrite `$schema` URI to the 2020-12 form; non-draft-07 URIs pass through.
 		if (key === "$schema") {
 			result.$schema =
-				typeof entry === "string" && entry in DRAFT_07_SCHEMA_URIS ? JSON_SCHEMA_DRAFT_2020_12_URI : entry;
+				typeof entry === "string" && Object.hasOwn(DRAFT_07_SCHEMA_URIS, entry)
+					? JSON_SCHEMA_DRAFT_2020_12_URI
+					: entry;
 			continue;
 		}
 		// `#/definitions/Foo` → `#/$defs/Foo`.
@@ -290,15 +308,20 @@ function upgradeJsonSchemaTo202012Impl(value: unknown, cache: WeakMap<object, un
 		if (key === "items" && Array.isArray(entry)) {
 			continue;
 		}
-		result[key] = upgradeJsonSchemaTo202012Impl(entry, cache);
+		setOwnKey(result, key, upgradeJsonSchemaTo202012Impl(entry, cache));
 	}
 
 	// Draft-07 tuple form: `items: [a, b]` (+ optional `additionalItems`) becomes
 	// draft 2020-12 `prefixItems: [a, b]` (+ optional `items` for the rest).
-	if (Array.isArray(value.items)) {
-		const convertedItems = upgradeJsonSchemaTo202012Impl(value.items, cache) as unknown[];
+	const tupleItems = Object.hasOwn(value, "items") && Array.isArray(value.items) ? value.items : undefined;
+	if (tupleItems !== undefined) {
+		const convertedItems = upgradeJsonSchemaTo202012Impl(tupleItems, cache) as unknown[];
 		result.prefixItems = mergePrefixItems(result.prefixItems, convertedItems);
-		if (value.additionalItems !== undefined && value.additionalItems !== true) {
+		if (
+			Object.hasOwn(value, "additionalItems") &&
+			value.additionalItems !== undefined &&
+			value.additionalItems !== true
+		) {
 			result.items = upgradeJsonSchemaTo202012Impl(value.additionalItems, cache);
 		} else {
 			// `additionalItems: true` (or absent) in draft-07 == no `items` in 2020-12.
@@ -311,7 +334,7 @@ function upgradeJsonSchemaTo202012Impl(value: unknown, cache: WeakMap<object, un
 	// OpenAPI 3.0 `nullable: true` → 2020-12 nullability. `makeNullable` may
 	// return a fresh wrapper object, in which case update the cache so callers
 	// referring to the same input see the wrapper instead of the inner result.
-	if (value.nullable === true) {
+	if (Object.hasOwn(value, "nullable") && value.nullable === true) {
 		const nullable = makeNullable(result);
 		if (nullable !== result) cache.set(value, nullable);
 		return nullable;

package/src/utils/schema/normalize.d.ts

@@ -25,11 +25,6 @@ export interface NormalizeSchemaOptions {
 }
 /** Copy all keys from a schema except the specified combiner key. */
 export declare function copySchemaWithout(schema: JsonObject, combiner: string): JsonObject;
-/**
- * Recursively strip any remaining anyOf/oneOf that same-type or mixed-type
- * collapse can handle. This is needed because object-combiner merging can
- * create new anyOf in merged subtrees after child normalization already ran.
- */
 export declare function stripResidualCombiners(value: unknown, epoch?: number): unknown;
 export declare function normalizeSchema(value: unknown, options: NormalizeSchemaOptions): unknown;
 export declare function normalizeSchemaForGoogle(value: unknown): unknown;