@gajae-code/ai 0.1.1

package/src/utils/schema/dereference.ts

@@ -0,0 +1,98 @@
+/**
+ * Inline `$ref` / `$defs` in a JSON Schema so every consumer sees
+ * the full definition without needing a resolver.
+ *
+ * Handles:
+ * - Local `$ref` pointers (`#/$defs/Foo`, `#/definitions/Foo`)
+ * - Nested `$defs` / `definitions` blocks
+ * - Circular references (breaks the cycle by emitting `{}`)
+ *
+ * After dereferencing, `$defs` and `definitions` are stripped from the root.
+ */
+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 [, defsKey, name] = match;
+	const defs = root[defsKey!];
+	if (!isJsonObject(defs)) return undefined;
+
+	const resolved = defs[name!];
+	return isJsonObject(resolved) ? resolved : undefined;
+}
+
+/**
+ * Recursively dereference a JSON Schema node, inlining all local `$ref` pointers.
+ */
+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));
+
+	const ref = node.$ref;
+	if (typeof ref === "string") {
+		// Break circular references
+		if (visiting.has(ref)) 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);
+
+		// 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;
+			}
+		}
+		if (!hasSiblings || !isJsonObject(inlined)) return inlined;
+		const merged: JsonObject = { ...inlined, ...node };
+		delete merged.$ref;
+		return merged;
+	}
+
+	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;
+		}
+	}
+	return result;
+}
+
+/**
+ * Dereference all local `$ref` pointers in a JSON Schema, inlining definitions
+ * from `$defs` / `definitions`. The `$defs` block is stripped from the output.
+ *
+ * Non-local refs (e.g. `http://...`) are left untouched.
+ * Circular references are broken with `{}`.
+ *
+ * @returns A new schema object with all local refs inlined, or the input unchanged
+ *          if it's not an object or has no `$defs`/`definitions`.
+ */
+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;
+
+	return dereferenceNode(schema, schema, new Set());
+}

package/src/utils/schema/draft.ts

@@ -0,0 +1,341 @@
+import { areJsonValuesEqual } from "./equality";
+import { epochNext, once } from "./stamps";
+import { isJsonObject, type JsonObject } from "./types";
+
+export const JSON_SCHEMA_DRAFT_2020_12_URI = "https://json-schema.org/draft/2020-12/schema";
+
+/** Draft-07 schema URIs we recognise as needing an upgrade. The trailing `#` is the canonical form in the JSON Schema spec, but providers (and Zod) emit both. */
+const DRAFT_07_SCHEMA_URIS: Record<string, true> = {
+	"http://json-schema.org/draft-07/schema#": true,
+	"https://json-schema.org/draft-07/schema#": true,
+	"http://json-schema.org/draft-07/schema": true,
+	"https://json-schema.org/draft-07/schema": true,
+};
+
+/**
+ * Keys whose values are property-name → schema maps. We recurse into each map
+ * 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 };
+/**
+ * Keys whose values are JSON-Schema *values*, not nested schemas. The upgrade
+ * walker must NOT descend into these — `type: ["string","null"]` is not a
+ * schema, and recursing would corrupt `enum`/`const`/`default` payloads.
+ */
+const NON_SCHEMA_VALUE_KEYS: Record<string, true> = {
+	const: true,
+	default: true,
+	enum: true,
+	example: true,
+	examples: true,
+	required: true,
+	dependentRequired: true,
+	type: true,
+};
+
+/** 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;
+}
+
+/** 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];
+	if (isJsonObject(existing)) return existing;
+	const next: JsonObject = {};
+	target[key] = next;
+	return next;
+}
+
+/** Recursively upgrade every entry of a schema-map (e.g. `properties`) and merge into `target[key]`. */
+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);
+	}
+}
+/** 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;
+		return;
+	}
+	mergeSchemaMap(target, key, value, cache);
+}
+
+/**
+ * Intersect two schemas. Used when draft-07 `dependencies` map keys collide
+ * with each other or with existing `dependentSchemas` entries.
+ * - `true`/undefined is the identity (matches anything).
+ * - `false` is the absorbing element (matches nothing).
+ * - Equal schemas collapse. Otherwise wrap in `allOf` so both still apply.
+ */
+function combineSchemas(left: unknown, right: unknown): unknown {
+	if (left === undefined || left === true) return right;
+	if (right === undefined || right === true) return left;
+	if (left === false || right === false) return false;
+	if (areJsonValuesEqual(left, right)) return left;
+	return { allOf: [left, right] };
+}
+
+/** Union two arrays of JSON values, deduping by deep equality. Used to merge `dependentRequired` arrays. */
+function mergeArrayValues(left: unknown[], right: unknown[]): unknown[] {
+	const merged = [...left];
+	for (const value of right) {
+		if (!merged.some(existing => areJsonValuesEqual(existing, value))) {
+			merged.push(value);
+		}
+	}
+	return merged;
+}
+
+/**
+ * Merge converted tuple items into an existing `prefixItems` array. When the
+ * same index already has a schema (e.g. from a prior recursive pass via the
+ * cache), intersect the two so both constraints survive.
+ */
+function mergePrefixItems(existing: unknown, convertedItems: unknown[]): unknown[] {
+	if (!Array.isArray(existing)) return convertedItems;
+	const merged = [...existing];
+	for (let index = 0; index < convertedItems.length; index += 1) {
+		merged[index] = index in merged ? combineSchemas(merged[index], convertedItems[index]) : convertedItems[index];
+	}
+	return merged;
+}
+
+/** 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];
+	if (existing === undefined) {
+		dependentRequired[key] = deps;
+		return;
+	}
+	if (Array.isArray(existing)) {
+		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);
+}
+
+/**
+ * Convert draft-07's `dependencies` keyword (which mixes array deps and schema
+ * deps under one key) into the draft 2020-12 split:
+ *   - array value → `dependentRequired`
+ *   - schema value → `dependentSchemas`
+ */
+function convertDependencies(source: JsonObject, target: JsonObject, cache: WeakMap<object, unknown>): void {
+	const dependencies = source.dependencies;
+	if (!isJsonObject(dependencies)) return;
+	for (const key in dependencies) {
+		const dependency = dependencies[key];
+		const converted = upgradeJsonSchemaTo202012Impl(dependency, cache);
+		if (Array.isArray(converted)) {
+			mergeDependentRequired(target, key, converted);
+		} else {
+			mergeDependentSchema(target, key, converted);
+		}
+	}
+}
+
+/** True if `type` is `"null"` or an array that includes `"null"`. */
+function hasNullType(type: unknown): boolean {
+	return type === "null" || (Array.isArray(type) && type.includes("null"));
+}
+
+/** 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));
+}
+
+/**
+ * Mutate `schema` in place to accept `null`. Strategy depends on existing shape:
+ *   - scalar type → expand to `[type, "null"]`.
+ *   - type array → append `"null"` if missing.
+ *   - existing `anyOf` → append `{type:"null"}` branch if missing.
+ *   - otherwise → wrap the whole schema in `anyOf:[schema, {type:"null"}]`.
+ * Returns the resulting object (which may be a new wrapper).
+ */
+function makeNullable(schema: JsonObject): JsonObject {
+	const type = schema.type;
+	if (typeof type === "string") {
+		if (type !== "null") schema.type = [type, "null"];
+		return schema;
+	}
+	if (Array.isArray(type)) {
+		if (!type.includes("null")) schema.type = [...type, "null"];
+		return schema;
+	}
+	if (Array.isArray(schema.anyOf)) {
+		if (!hasNullVariant(schema.anyOf)) schema.anyOf = [...schema.anyOf, { type: "null" }];
+		return schema;
+	}
+	return { anyOf: [schema, { type: "null" }] };
+}
+
+/** True if any entry in a schema-map needs upgrading. Shortcut used during pre-check to skip the full clone when nothing has changed. */
+function schemaMapNeedsDraft202012Upgrade(value: unknown, epoch: number): boolean {
+	if (!isJsonObject(value)) return false;
+	for (const k in value) {
+		if (schemaNeedsDraft202012UpgradeImpl(value[k], epoch)) return true;
+	}
+	return false;
+}
+
+/**
+ * Cheap pre-check: walk the schema looking for any keyword/value that the
+ * upgrade pass would have to rewrite. Lets the public entrypoint short-circuit
+ * and return the input identity-unchanged when there is nothing to do.
+ *
+ * Uses `once(value, epoch)` to break cycles without allocating a per-call set.
+ */
+function schemaNeedsDraft202012UpgradeImpl(value: unknown, epoch: number): boolean {
+	if (Array.isArray(value)) {
+		if (!once(value, epoch)) return false;
+		return value.some(entry => schemaNeedsDraft202012UpgradeImpl(entry, epoch));
+	}
+	if (!isJsonObject(value)) return false;
+	if (!once(value, epoch)) return false;
+
+	for (const key in value) {
+		const entry = value[key];
+		if (key === "$schema") {
+			if (typeof entry === "string" && entry in DRAFT_07_SCHEMA_URIS) return true;
+			continue;
+		}
+		if (key === "definitions" || key === "dependencies" || key === "additionalItems" || key === "nullable") {
+			return true;
+		}
+		if (key === "$ref") {
+			if (typeof entry === "string" && entry.startsWith("#/definitions/")) return true;
+			continue;
+		}
+		if (key === "items" && Array.isArray(entry)) return true;
+		if (key === "$defs" || key in SCHEMA_MAP_KEYS) {
+			if (schemaMapNeedsDraft202012Upgrade(entry, epoch)) return true;
+			continue;
+		}
+		if (key in NON_SCHEMA_VALUE_KEYS) continue;
+		if (schemaNeedsDraft202012UpgradeImpl(entry, epoch)) return true;
+	}
+
+	return false;
+}
+
+/**
+ * Recursive upgrade core. The `cache` WeakMap keys input objects to their
+ * converted output so shared subgraphs are converted once and cycles terminate
+ * — we insert the empty result into the cache *before* recursing so back-edges
+ * resolve to a (later-populated) reference rather than infinite-looping.
+ */
+function upgradeJsonSchemaTo202012Impl(value: unknown, cache: WeakMap<object, unknown>): unknown {
+	if (Array.isArray(value)) {
+		const cached = cache.get(value);
+		if (cached !== undefined) return cached;
+		const result: unknown[] = [];
+		cache.set(value, result);
+		for (const entry of value) {
+			result.push(upgradeJsonSchemaTo202012Impl(entry, cache));
+		}
+		return result;
+	}
+	if (!isJsonObject(value)) return value;
+
+	const cached = cache.get(value);
+	if (cached !== undefined) return cached;
+
+	const result: JsonObject = {};
+	// Seed cache before recursion so back-edges in cyclic graphs resolve.
+	cache.set(value, result);
+	for (const key in value) {
+		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.
+		if (key === "definitions" || key === "$defs") {
+			if (isJsonObject(entry)) mergeSchemaMap(result, "$defs", entry, cache);
+			continue;
+		}
+		// Recurse into each entry; the map shape itself is preserved.
+		if (key in SCHEMA_MAP_KEYS) {
+			copySchemaMap(result, key, entry, cache);
+			continue;
+		}
+		// JSON-Schema *value* keywords — copy verbatim.
+		if (key in NON_SCHEMA_VALUE_KEYS) {
+			result[key] = entry;
+			continue;
+		}
+		// Draft-07-only keywords with no draft 2020-12 spelling — drop entirely.
+		// `items` arrays are handled below via `prefixItems` conversion.
+		if (key === "dependencies" || key === "additionalItems" || key === "nullable") {
+			continue;
+		}
+		// 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;
+			continue;
+		}
+		// `#/definitions/Foo` → `#/$defs/Foo`.
+		if (key === "$ref" && typeof entry === "string") {
+			result.$ref = convertRef(entry);
+			continue;
+		}
+		// Array-valued `items` is the draft-07 tuple form — handled after the loop.
+		if (key === "items" && Array.isArray(entry)) {
+			continue;
+		}
+		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[];
+		result.prefixItems = mergePrefixItems(result.prefixItems, convertedItems);
+		if (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.
+			delete result.items;
+		}
+	}
+
+	convertDependencies(value, result, cache);
+
+	// 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) {
+		const nullable = makeNullable(result);
+		if (nullable !== result) cache.set(value, nullable);
+		return nullable;
+	}
+
+	return result;
+}
+
+/** Pre-check entrypoint. Exposed so callers can decide whether to take the upgrade path at all. */
+export function schemaNeedsDraft202012Upgrade(schema: unknown): boolean {
+	return schemaNeedsDraft202012UpgradeImpl(schema, epochNext());
+}
+
+/**
+ * Upgrade legacy JSON Schema shapes to the draft 2020-12 form emitted by Zod.
+ *
+ * This keeps extension/MCP/TypeBox schemas compatible with providers whose tool
+ * validators reject draft-07 tuple and dependency keywords.
+ */
+// `WeakMap` is intentional: this cache is per-call and seeded *before* recursion
+// (see `cache.set(value, result)` in `upgradeJsonSchemaTo202012Impl`) so cyclic
+// graphs resolve to a knot-tied reference. A symbol stamp would either cache
+// across calls (unsafe under input mutation) or require an epoch indirection.
+export function upgradeJsonSchemaTo202012(schema: unknown): unknown {
+	if (!schemaNeedsDraft202012Upgrade(schema)) return schema;
+	return upgradeJsonSchemaTo202012Impl(schema, new WeakMap<object, unknown>());
+}

package/src/utils/schema/equality.ts

@@ -0,0 +1,97 @@
+import type { JsonObject } from "./types";
+import { isJsonObject } from "./types";
+
+export function areJsonValuesEqual(left: unknown, right: unknown): boolean {
+	if (Object.is(left, right)) {
+		return true;
+	}
+	if (Array.isArray(left) || Array.isArray(right)) {
+		if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) {
+			return false;
+		}
+		for (let i = 0; i < left.length; i += 1) {
+			if (!areJsonValuesEqual(left[i], right[i])) {
+				return false;
+			}
+		}
+		return true;
+	}
+	if (!isJsonObject(left) || !isJsonObject(right)) {
+		return false;
+	}
+	let rightLen = 0;
+	for (const _ in right) rightLen++;
+	let leftLen = 0;
+	for (const key in left) {
+		leftLen++;
+		if (!(key in right) || !areJsonValuesEqual(left[key], right[key])) return false;
+	}
+	return leftLen === rightLen;
+}
+
+export function mergeCompatibleEnumSchemas(existing: unknown, incoming: unknown): JsonObject | null {
+	if (!isJsonObject(existing) || !isJsonObject(incoming)) {
+		return null;
+	}
+	const existingEnum = Array.isArray(existing.enum) ? existing.enum : null;
+	const incomingEnum = Array.isArray(incoming.enum) ? incoming.enum : null;
+	if (!existingEnum || !incomingEnum) {
+		return null;
+	}
+	if (!areJsonValuesEqual(existing.type, incoming.type)) {
+		return null;
+	}
+	let existingNonEnumCount = 0;
+	for (const key in existing) {
+		if (key !== "enum") existingNonEnumCount++;
+	}
+	let incomingNonEnumCount = 0;
+	for (const key in incoming) {
+		if (key !== "enum") incomingNonEnumCount++;
+	}
+	if (existingNonEnumCount !== incomingNonEnumCount) {
+		return null;
+	}
+	for (const key in existing) {
+		if (key === "enum") continue;
+		if (!(key in incoming) || !areJsonValuesEqual(existing[key], incoming[key])) {
+			return null;
+		}
+	}
+
+	const mergedEnum = [...existingEnum];
+	for (const enumValue of incomingEnum) {
+		if (!mergedEnum.some(existingValue => areJsonValuesEqual(existingValue, enumValue))) {
+			mergedEnum.push(enumValue);
+		}
+	}
+	return {
+		...existing,
+		enum: mergedEnum,
+	};
+}
+
+function getAnyOfVariants(schema: unknown): unknown[] {
+	if (isJsonObject(schema) && Array.isArray(schema.anyOf)) {
+		return schema.anyOf;
+	}
+	return [schema];
+}
+
+export function mergePropertySchemas(existing: unknown, incoming: unknown): unknown {
+	if (areJsonValuesEqual(existing, incoming)) {
+		return existing;
+	}
+	const mergedEnumSchema = mergeCompatibleEnumSchemas(existing, incoming);
+	if (mergedEnumSchema !== null) {
+		return mergedEnumSchema;
+	}
+
+	const mergedAnyOf = [...getAnyOfVariants(existing)];
+	for (const variant of getAnyOfVariants(incoming)) {
+		if (!mergedAnyOf.some(existingVariant => areJsonValuesEqual(existingVariant, variant))) {
+			mergedAnyOf.push(variant);
+		}
+	}
+	return mergedAnyOf.length === 1 ? mergedAnyOf[0] : { anyOf: mergedAnyOf };
+}