tool-schema 0.1.0

package/dist/index.cjs

@@ -0,0 +1,596 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  lintToolSchema: () => lintToolSchema,
+  toTool: () => toTool,
+  toToolSchema: () => toToolSchema
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/util.ts
+var Warnings = class {
+  list = [];
+  lossy = false;
+  add(path, code, message, lossy = true) {
+    this.list.push({ path, code, message });
+    if (lossy) this.lossy = true;
+  }
+};
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function clone(value) {
+  return structuredClone(value);
+}
+function typesOf(schema) {
+  if (typeof schema.type === "string") return [schema.type];
+  if (Array.isArray(schema.type)) return schema.type.filter((t) => typeof t === "string");
+  return [];
+}
+function isObjectSchema(schema) {
+  const types = typesOf(schema);
+  if (types.includes("object")) return true;
+  if (types.length > 0) return false;
+  return isPlainObject(schema.properties) || schema.additionalProperties !== void 0;
+}
+function makeNullable(schema) {
+  if (typeof schema.type === "string") {
+    if (schema.type === "null") return schema;
+    return { ...schema, type: [schema.type, "null"] };
+  }
+  if (Array.isArray(schema.type)) {
+    if (schema.type.includes("null")) return schema;
+    return { ...schema, type: [...schema.type, "null"] };
+  }
+  if (Array.isArray(schema.anyOf)) {
+    if (schema.anyOf.some((b) => typesOf(b).includes("null"))) return schema;
+    return { ...schema, anyOf: [...schema.anyOf, { type: "null" }] };
+  }
+  return { anyOf: [schema, { type: "null" }] };
+}
+function dereference(root, warnings) {
+  const defs = {
+    ...isPlainObject(root.definitions) ? root.definitions : {},
+    ...isPlainObject(root.$defs) ? root.$defs : {}
+  };
+  const resolve = (ref) => {
+    const m = /^#\/(?:\$defs|definitions)\/(.+)$/.exec(ref);
+    if (!m) return void 0;
+    const key = decodeURIComponent(m[1].replace(/~1/g, "/").replace(/~0/g, "~"));
+    return defs[key];
+  };
+  const walk = (node, path, seen) => {
+    if (!isPlainObject(node)) return node;
+    if (typeof node.$ref === "string") {
+      const ref = node.$ref;
+      const target = resolve(ref);
+      if (!target) return node;
+      if (seen.has(ref)) {
+        warnings.add(path, "recursive-ref", `Recursive $ref '${ref}' cannot be inlined; replaced with an open schema.`);
+        return {};
+      }
+      const { $ref: _drop, ...rest } = node;
+      void _drop;
+      warnings.add(path, "inlined-ref", `Inlined $ref '${ref}'.`, false);
+      const merged = { ...clone(target), ...rest };
+      return walk(merged, path, /* @__PURE__ */ new Set([...seen, ref]));
+    }
+    return mapChildren(node, path, (child, childPath) => walk(child, childPath, seen));
+  };
+  const out = walk(clone(root), "#", /* @__PURE__ */ new Set());
+  delete out.$defs;
+  delete out.definitions;
+  return out;
+}
+function mapChildren(node, path, fn) {
+  const out = { ...node };
+  if (isPlainObject(out.properties)) {
+    const props = {};
+    for (const [k, v] of Object.entries(out.properties)) {
+      props[k] = fn(v, `${path}/properties/${k}`);
+    }
+    out.properties = props;
+  }
+  if (Array.isArray(out.items)) {
+    out.items = out.items.map((it, i) => fn(it, `${path}/items/${i}`));
+  } else if (isPlainObject(out.items)) {
+    out.items = fn(out.items, `${path}/items`);
+  }
+  if (isPlainObject(out.additionalProperties)) {
+    out.additionalProperties = fn(out.additionalProperties, `${path}/additionalProperties`);
+  }
+  for (const key of ["anyOf", "oneOf", "allOf"]) {
+    const arr = out[key];
+    if (Array.isArray(arr)) {
+      out[key] = arr.map((b, i) => fn(b, `${path}/${key}/${i}`));
+    }
+  }
+  if (isPlainObject(out.not)) out.not = fn(out.not, `${path}/not`);
+  for (const key of ["if", "then", "else"]) {
+    if (isPlainObject(out[key])) out[key] = fn(out[key], `${path}/${key}`);
+  }
+  if (isPlainObject(out.patternProperties)) {
+    const pp = {};
+    for (const [k, v] of Object.entries(out.patternProperties)) {
+      pp[k] = fn(v, `${path}/patternProperties/${k}`);
+    }
+    out.patternProperties = pp;
+  }
+  for (const key of ["$defs", "definitions", "dependentSchemas"]) {
+    const map = out[key];
+    if (isPlainObject(map)) {
+      const next = {};
+      for (const [k, v] of Object.entries(map)) {
+        next[k] = fn(v, `${path}/${key}/${k}`);
+      }
+      out[key] = next;
+    }
+  }
+  return out;
+}
+function ensureObjectRoot(schema, warnings, target) {
+  if (isObjectSchema(schema)) {
+    if (typesOf(schema).length === 0) return { type: "object", ...schema };
+    return schema;
+  }
+  warnings.add(
+    "#",
+    "root-not-object",
+    `${target} requires the root schema to be an object; wrapped the schema under a 'value' property.`
+  );
+  return {
+    type: "object",
+    properties: { value: schema },
+    required: ["value"]
+  };
+}
+
+// src/targets/openai.ts
+var FORMAT_WHITELIST = /* @__PURE__ */ new Set([
+  "date-time",
+  "time",
+  "date",
+  "duration",
+  "email",
+  "hostname",
+  "ipv4",
+  "ipv6",
+  "uuid"
+]);
+var UNSUPPORTED = [
+  "not",
+  "if",
+  "then",
+  "else",
+  "dependentRequired",
+  "dependentSchemas",
+  "patternProperties",
+  "unevaluatedProperties"
+];
+var MAX_PROPERTIES = 5e3;
+var MAX_DEPTH = 10;
+var MAX_ENUM_VALUES = 1e3;
+function toOpenAI(input) {
+  const warnings = new Warnings();
+  const schema = ensureObjectRoot(clone(input), warnings, "OpenAI");
+  return { schema, warnings: warnings.list, lossy: warnings.lossy };
+}
+function toOpenAIStrict(input) {
+  const warnings = new Warnings();
+  const transform = (node, path) => {
+    if (!isPlainObject(node)) return node;
+    let s = { ...node };
+    if (Array.isArray(s.allOf)) {
+      s = mergeAllOf(s, path, warnings);
+    }
+    for (const kw of UNSUPPORTED) {
+      if (kw in s) {
+        delete s[kw];
+        warnings.add(path, "stripped-keyword", `'${kw}' is not supported in OpenAI strict mode; removed.`);
+      }
+    }
+    if (typeof s.format === "string" && !FORMAT_WHITELIST.has(s.format)) {
+      warnings.add(
+        `${path}/format`,
+        "unsupported-format",
+        `format '${s.format}' is not in OpenAI's whitelist; removed.`
+      );
+      delete s.format;
+    }
+    s = mapChildren(s, path, transform);
+    if (isObjectSchema(s) && isPlainObject(s.properties)) {
+      const props = s.properties;
+      const originalRequired = new Set(Array.isArray(s.required) ? s.required : []);
+      const nextProps = {};
+      for (const key of Object.keys(props)) {
+        let child = props[key];
+        if (!originalRequired.has(key)) {
+          child = makeNullable(child);
+          warnings.add(
+            `${path}/properties/${key}`,
+            "forced-required",
+            `Optional property '${key}' was made required and nullable for OpenAI strict mode.`
+          );
+        }
+        nextProps[key] = child;
+      }
+      s.properties = nextProps;
+      s.required = Object.keys(nextProps);
+      if (s.additionalProperties !== false) {
+        warnings.add(
+          path,
+          "forced-additional-properties",
+          "Set 'additionalProperties: false' as required by strict mode.",
+          false
+        );
+      }
+      s.additionalProperties = false;
+    } else if (isObjectSchema(s)) {
+      if (s.additionalProperties !== false) {
+        warnings.add(
+          path,
+          "forced-additional-properties",
+          "Set 'additionalProperties: false' on a property-less object.",
+          false
+        );
+      }
+      s.additionalProperties = false;
+    }
+    return s;
+  };
+  const schema = ensureObjectRoot(transform(clone(input), "#"), warnings, "OpenAI strict mode");
+  checkLimits(schema, warnings);
+  return { schema, warnings: warnings.list, lossy: warnings.lossy };
+}
+function mergeAllOf(node, path, warnings) {
+  const parts = node.allOf;
+  const { allOf: _drop, ...base } = node;
+  void _drop;
+  const merged = { ...base };
+  const props = isPlainObject(merged.properties) ? { ...merged.properties } : {};
+  const required = new Set(Array.isArray(merged.required) ? merged.required : []);
+  for (const part of parts) {
+    if (!isPlainObject(part)) continue;
+    if (isPlainObject(part.properties)) {
+      Object.assign(props, part.properties);
+    }
+    if (Array.isArray(part.required)) {
+      for (const r of part.required) required.add(r);
+    }
+    if (part.type && !merged.type) merged.type = part.type;
+  }
+  if (Object.keys(props).length > 0) merged.properties = props;
+  if (required.size > 0) merged.required = [...required];
+  if (!merged.type && (merged.properties || isObjectSchema(merged))) merged.type = "object";
+  warnings.add(path, "merged-allof", "Merged 'allOf' subschemas into the parent (unsupported in strict mode).");
+  return merged;
+}
+function checkLimits(schema, warnings) {
+  let propertyCount = 0;
+  let maxDepth = 0;
+  const visit = (node, depth) => {
+    if (!isPlainObject(node)) return;
+    maxDepth = Math.max(maxDepth, depth);
+    if (isPlainObject(node.properties)) {
+      const keys = Object.keys(node.properties);
+      propertyCount += keys.length;
+    }
+    if (Array.isArray(node.enum) && node.enum.length > MAX_ENUM_VALUES) {
+      warnings.add(
+        "#",
+        "limit-exceeded",
+        `An enum has ${node.enum.length} values; OpenAI allows at most ${MAX_ENUM_VALUES}.`,
+        false
+      );
+    }
+    const children = collectChildren(node);
+    for (const c of children) visit(c, depth + 1);
+  };
+  visit(schema, 0);
+  if (propertyCount > MAX_PROPERTIES) {
+    warnings.add(
+      "#",
+      "limit-exceeded",
+      `Schema has ${propertyCount} object properties; OpenAI allows at most ${MAX_PROPERTIES}.`,
+      false
+    );
+  }
+  if (maxDepth > MAX_DEPTH) {
+    warnings.add(
+      "#",
+      "limit-exceeded",
+      `Schema nests ${maxDepth} levels deep; OpenAI allows at most ${MAX_DEPTH}.`,
+      false
+    );
+  }
+}
+function collectChildren(node) {
+  const out = [];
+  if (isPlainObject(node.properties)) out.push(...Object.values(node.properties));
+  if (Array.isArray(node.items)) out.push(...node.items);
+  else if (isPlainObject(node.items)) out.push(node.items);
+  for (const key of ["anyOf", "oneOf", "allOf"]) {
+    const arr = node[key];
+    if (Array.isArray(arr)) out.push(...arr);
+  }
+  if (isPlainObject(node.$defs)) out.push(...Object.values(node.$defs));
+  return out.filter(isPlainObject);
+}
+
+// src/targets/anthropic.ts
+function toAnthropic(input) {
+  const warnings = new Warnings();
+  const schema = ensureObjectRoot(clone(input), warnings, "Anthropic");
+  return { schema, warnings: warnings.list, lossy: warnings.lossy };
+}
+
+// src/targets/gemini.ts
+var STRIP = [
+  "$schema",
+  "$id",
+  "$anchor",
+  "$ref",
+  "oneOf",
+  "allOf",
+  "not",
+  "if",
+  "then",
+  "else",
+  "additionalProperties",
+  "patternProperties",
+  "unevaluatedProperties",
+  "const",
+  "dependentRequired",
+  "dependentSchemas",
+  "multipleOf",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "uniqueItems",
+  "contentEncoding",
+  "contentMediaType",
+  "$defs",
+  "definitions"
+];
+var TYPE_UPPER = {
+  string: "STRING",
+  number: "NUMBER",
+  integer: "INTEGER",
+  boolean: "BOOLEAN",
+  array: "ARRAY",
+  object: "OBJECT",
+  null: "NULL"
+};
+function toGemini(input, options = {}) {
+  const warnings = new Warnings();
+  const dereferenced = dereference(clone(input), warnings);
+  const transform = (node, path) => {
+    if (!isPlainObject(node)) return node;
+    let s = { ...node };
+    for (const kw of STRIP) {
+      if (kw in s) {
+        delete s[kw];
+        warnings.add(path, "stripped-keyword", `'${kw}' is not supported by Gemini (route A); removed.`);
+      }
+    }
+    s = collapseNullableUnion(s, path, warnings);
+    s = mapChildren(s, path, transform);
+    s = collapseAnyOf(s, path, warnings);
+    coerceEnum(s, path, warnings);
+    return s;
+  };
+  let schema = ensureObjectRoot(transform(dereferenced, "#"), warnings, "Gemini");
+  if (options.uppercaseTypes) schema = uppercaseTypes(schema);
+  return { schema, warnings: warnings.list, lossy: warnings.lossy };
+}
+function uppercaseTypes(node) {
+  if (!isPlainObject(node)) return node;
+  const out = { ...node };
+  if (typeof out.type === "string") {
+    out.type = TYPE_UPPER[out.type] ?? out.type;
+  } else if (Array.isArray(out.type)) {
+    out.type = out.type.map((t) => TYPE_UPPER[t] ?? t);
+  }
+  return mapChildren(out, "#", (child) => uppercaseTypes(child));
+}
+function toGeminiJsonSchema(input) {
+  const warnings = new Warnings();
+  const schema = ensureObjectRoot(clone(input), warnings, "Gemini (parametersJsonSchema)");
+  return { schema, warnings: warnings.list, lossy: warnings.lossy };
+}
+function collapseNullableUnion(node, path, warnings) {
+  if (!Array.isArray(node.type)) return node;
+  const nonNull = node.type.filter((t) => t !== "null");
+  const hadNull = node.type.includes("null");
+  const out = { ...node };
+  if (nonNull.length === 0) {
+    out.type = "string";
+  } else {
+    out.type = nonNull[0];
+    if (nonNull.length > 1) {
+      warnings.add(
+        path,
+        "union-types",
+        `Gemini cannot express a union of types [${nonNull.join(", ")}]; kept '${nonNull[0]}'.`
+      );
+    }
+  }
+  if (hadNull) {
+    out.nullable = true;
+    warnings.add(path, "collapsed-nullable", "Converted nullable type union into 'nullable: true'.", false);
+  }
+  return out;
+}
+function collapseAnyOf(node, path, warnings) {
+  if (!Array.isArray(node.anyOf)) return node;
+  const branches = node.anyOf;
+  const nonNull = branches.filter((b) => !(typesOf(b).length === 1 && typesOf(b)[0] === "null"));
+  const hadNull = nonNull.length !== branches.length;
+  const out = { ...node };
+  if (hadNull) {
+    out.nullable = true;
+    warnings.add(path, "collapsed-nullable", "Converted an anyOf null branch into 'nullable: true'.", false);
+  }
+  if (nonNull.length === 0) {
+    delete out.anyOf;
+    if (!out.type) out.type = "string";
+  } else if (nonNull.length === 1) {
+    delete out.anyOf;
+    const branch = nonNull[0];
+    for (const [k, v] of Object.entries(branch)) {
+      if (k === "description" && out.description) continue;
+      out[k] = v;
+    }
+  } else {
+    out.anyOf = nonNull;
+  }
+  return out;
+}
+function coerceEnum(node, path, warnings) {
+  if (!Array.isArray(node.enum)) return;
+  const allStrings = node.enum.every((v) => typeof v === "string");
+  if (!allStrings) {
+    node.enum = node.enum.map((v) => String(v));
+    warnings.add(`${path}/enum`, "enum-coerced", "Gemini enum values must be strings; coerced non string values.");
+  }
+  if (!node.type) node.type = "string";
+}
+
+// src/targets/mcp.ts
+function toMcp(input) {
+  const warnings = new Warnings();
+  const schema = ensureObjectRoot(clone(input), warnings, "MCP");
+  return { schema, warnings: warnings.list, lossy: warnings.lossy };
+}
+
+// src/transform.ts
+var EMPTY_OBJECT_SCHEMA = { type: "object", properties: {} };
+function toToolSchema(schema, options = {}) {
+  const target = options.target ?? "openai";
+  switch (target) {
+    case "openai":
+      return toOpenAI(schema);
+    case "openai-strict":
+      return toOpenAIStrict(schema);
+    case "anthropic":
+      return toAnthropic(schema);
+    case "gemini":
+      return toGemini(schema, { uppercaseTypes: options.geminiUppercaseTypes });
+    case "gemini-jsonschema":
+      return toGeminiJsonSchema(schema);
+    case "mcp":
+      return toMcp(schema);
+    default:
+      throw new Error(`Unknown target: ${String(target)}`);
+  }
+}
+function toTool(def, options = {}) {
+  const target = options.target ?? "openai";
+  const result = toToolSchema(def.schema ?? EMPTY_OBJECT_SCHEMA, options);
+  const warnings = [...result.warnings];
+  validateName(def.name, target, warnings);
+  const tool = buildTool(def, result.schema, target, options);
+  return { tool, warnings, lossy: result.lossy };
+}
+function lintToolSchema(schema, options = {}) {
+  const { warnings } = toToolSchema(schema, options);
+  return { ok: warnings.length === 0, issues: warnings };
+}
+function buildTool(def, schema, target, options) {
+  const { name, description } = def;
+  switch (target) {
+    case "openai":
+    case "openai-strict": {
+      const strict = target === "openai-strict";
+      if (options.openaiResponses) {
+        return {
+          type: "function",
+          name,
+          ...description ? { description } : {},
+          parameters: schema,
+          ...strict ? { strict: true } : {}
+        };
+      }
+      return {
+        type: "function",
+        function: {
+          name,
+          ...description ? { description } : {},
+          parameters: schema,
+          ...strict ? { strict: true } : {}
+        }
+      };
+    }
+    case "anthropic":
+      return {
+        name,
+        ...description ? { description } : {},
+        input_schema: schema,
+        ...options.anthropicStrict ? { strict: true } : {}
+      };
+    case "gemini":
+      return {
+        name,
+        ...description ? { description } : {},
+        parameters: schema
+      };
+    case "gemini-jsonschema":
+      return {
+        name,
+        ...description ? { description } : {},
+        parametersJsonSchema: schema
+      };
+    case "mcp":
+      return {
+        name,
+        ...description ? { description } : {},
+        inputSchema: schema,
+        ...def.annotations ? { annotations: def.annotations } : {}
+      };
+    default:
+      throw new Error(`Unknown target: ${String(target)}`);
+  }
+}
+var NAME_RULES = {
+  openai: { pattern: /^[a-zA-Z0-9_-]{1,64}$/, label: "OpenAI (letters, digits, _ and -, max 64)" },
+  "openai-strict": { pattern: /^[a-zA-Z0-9_-]{1,64}$/, label: "OpenAI (letters, digits, _ and -, max 64)" },
+  anthropic: { pattern: /^[a-zA-Z0-9_-]{1,64}$/, label: "Anthropic (letters, digits, _ and -, max 64)" },
+  gemini: { pattern: /^[a-zA-Z0-9_:.-]{1,128}$/, label: "Gemini (letters, digits, _ : . -, max 128)" },
+  "gemini-jsonschema": { pattern: /^[a-zA-Z0-9_:.-]{1,128}$/, label: "Gemini (letters, digits, _ : . -, max 128)" },
+  mcp: { pattern: /^[a-zA-Z0-9_-]{1,128}$/, label: "MCP (letters, digits, _ and -)" }
+};
+function validateName(name, target, warnings) {
+  const rule = NAME_RULES[target];
+  if (!rule.pattern.test(name)) {
+    warnings.push({
+      path: "#/name",
+      code: "invalid-name",
+      message: `Tool name '${name}' does not match the ${rule.label} naming rule.`
+    });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  lintToolSchema,
+  toTool,
+  toToolSchema
+});
+//# sourceMappingURL=index.cjs.map