@typeship-ax/mcp 0.21.0 → 0.22.0

package/src/arguments.ts

@@ -0,0 +1,242 @@
+/**
+ * Argument checks shared by the generated CLI and MCP server: coerce a value
+ * toward its schema where the intent is unambiguous, and report every
+ * problem, nested ones included, with the dotted path of the argument it
+ * belongs to. Generated by Typeship — https://typeship.dev
+ * No external dependencies.
+ */
+
+import { dateKindOf, relativeDate } from "./dates.js";
+
+export interface ArgumentIssue {
+  code: "UNKNOWN_ARGUMENT" | "INVALID_ARGUMENT" | "MISSING_ARGUMENT";
+  argument: string;
+  message: string;
+}
+
+export const normalizeName = (name: string): string => name.toLowerCase().replace(/[^a-z0-9]/g, "");
+
+function editDistance(a: string, b: string): number {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0]!;
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = prev[j]!;
+      prev[j] = Math.min(prev[j]! + 1, prev[j - 1]! + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+      diag = tmp;
+    }
+  }
+  return prev[b.length]!;
+}
+
+/** The closest accepted name: same letters ignoring case/punctuation first,
+ * then a small edit distance. Undefined when nothing is close. */
+export function closestName(name: string, known: string[]): string | undefined {
+  const exact = known.filter((k) => normalizeName(k) === normalizeName(name));
+  if (exact.length === 1) return exact[0];
+  if (exact.length > 1) return undefined;
+  let best: { name: string; d: number } | undefined;
+  for (const k of known) {
+    const d = editDistance(name.toLowerCase(), k.toLowerCase());
+    if (d <= Math.max(1, Math.floor(k.length / 4)) && (best === undefined || d < best.d)) best = { name: k, d };
+  }
+  return best?.name;
+}
+
+function schemaTypes(schema: Record<string, unknown>): string[] {
+  const t = schema.type;
+  if (typeof t === "string") return [t];
+  if (Array.isArray(t)) return t.filter((x): x is string => typeof x === "string");
+  return [];
+}
+
+/**
+ * Coerce one value toward its schema when the intent is unambiguous: the
+ * strings agents produce for booleans and numbers, a JSON string for an
+ * object or array, a scalar for a one-element array, an enum member in the
+ * wrong case. Returns the value to send, or a message when it can't be made
+ * to fit. Untyped schemas (unions, anything) pass through. The first
+ * problem only; checkValue reports every nested one.
+ */
+export function coerceValue(value: unknown, schema: Record<string, unknown>): { value: unknown } | { error: string } {
+  const issues: ArgumentIssue[] = [];
+  const out = checkValue(value, schema, "", issues);
+  return issues.length > 0 ? { error: issues[0]!.message } : { value: out };
+}
+
+/** Coerce one scalar-level value (type and enum) without looking inside it. */
+function coerceShallow(value: unknown, schema: Record<string, unknown>): { value: unknown } | { error: string } {
+  if (value === null || value === undefined) return { value };
+  // Date-shaped arguments take relative forms (-P7D, 7 days ago, today),
+  // resolved here so the API sees an absolute value.
+  const dateKind = dateKindOf(schema.format);
+  if (dateKind && typeof value === "string") {
+    const resolved = relativeDate(value, dateKind);
+    if (resolved && "error" in resolved) return { error: resolved.error };
+    if (resolved) value = resolved.value;
+  }
+  const types = schemaTypes(schema);
+  const enumValues = Array.isArray(schema.enum) ? schema.enum : undefined;
+  const accepts = (t: string) => types.length === 0 || types.includes(t);
+  const kind = Array.isArray(value) ? "array" : typeof value;
+
+  let out: unknown = value;
+  if (types.length > 0) {
+    if (kind === "boolean" && !accepts("boolean")) {
+      if (accepts("string")) out = String(value);
+      else return { error: "expected " + types.join(" or ") + ", got boolean" };
+    } else if (kind === "number" && !accepts("number") && !accepts("integer")) {
+      if (accepts("string")) out = String(value);
+      else if (accepts("array")) out = [value];
+      else return { error: "expected " + types.join(" or ") + ", got number" };
+    } else if (kind === "number" && accepts("integer") && !accepts("number") && !Number.isInteger(value)) {
+      return { error: "expected an integer, got " + String(value) };
+    } else if (kind === "string" && !accepts("string")) {
+      const s = (value as string).trim();
+      if (accepts("boolean") && /^(true|false|yes|no|1|0)$/i.test(s)) out = /^(true|yes|1)$/i.test(s);
+      else if ((accepts("integer") || accepts("number")) && s !== "" && !Number.isNaN(Number(s))) {
+        const n = Number(s);
+        if (accepts("integer") && !accepts("number") && !Number.isInteger(n)) return { error: "expected an integer, got \"" + s + "\"" };
+        out = n;
+      } else if ((accepts("object") || accepts("array")) && /^[[{]/.test(s)) {
+        try {
+          const parsed: unknown = JSON.parse(s);
+          const parsedKind = Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed;
+          if (!accepts(parsedKind)) return { error: "expected " + types.join(" or ") + ", got a JSON " + parsedKind + " in a string" };
+          out = parsed;
+        } catch {
+          return { error: "expected " + types.join(" or ") + ", got a string that is not valid JSON" };
+        }
+      } else if (accepts("array")) {
+        out = [value];
+      } else {
+        return { error: "expected " + types.join(" or ") + ", got string" };
+      }
+    } else if (kind === "object" && !accepts("object")) {
+      if (accepts("array")) out = [value];
+      else return { error: "expected " + types.join(" or ") + ", got object" };
+    } else if (kind === "array" && !accepts("array")) {
+      return { error: "expected " + types.join(" or ") + ", got array" };
+    }
+  }
+
+  if (enumValues && typeof out === "string" && !enumValues.includes(out)) {
+    const match = enumValues.filter((e) => typeof e === "string" && e.toLowerCase() === (out as string).toLowerCase());
+    if (match.length === 1) out = match[0];
+    else return { error: "must be one of " + enumValues.map((e) => JSON.stringify(e)).join(", ") + ", got " + JSON.stringify(out) };
+  }
+  return { value: out };
+}
+
+/** A nullable single-variant union (`anyOf: [X, {type: "null"}]`, the shape
+ * nullable GraphQL enums and objects take) validates as X; any other union
+ * passes through unchecked. */
+function nullableVariant(schema: Record<string, unknown>): Record<string, unknown> | undefined {
+  const variants = schema.anyOf ?? schema.oneOf;
+  if (!Array.isArray(variants) || variants.length !== 2 || schema.type !== undefined) return undefined;
+  const isNull = (v: unknown) => Boolean(v) && typeof v === "object" && (v as Record<string, unknown>).type === "null";
+  const others = variants.filter((v) => !isNull(v));
+  if (others.length !== 1 || !others[0] || typeof others[0] !== "object") return undefined;
+  return others[0] as Record<string, unknown>;
+}
+
+const MAX_CHECK_DEPTH = 16;
+
+/**
+ * Check one argument value against its schema, the way prepareCall checks
+ * top-level arguments, and return the value to send. Recurses into array
+ * items and object properties: types and enums are coerced where the intent
+ * is clear, required properties must be present, strings must match their
+ * pattern, and keys an object declares closed (`additionalProperties:
+ * false`, as every GraphQL input type is) must be known. Every problem is
+ * pushed to issues with its dotted path (input.priority, items[0].name).
+ */
+export function checkValue(
+  value: unknown,
+  schema: Record<string, unknown>,
+  path: string,
+  issues: ArgumentIssue[],
+  options: { skipPattern?: boolean; depth?: number } = {},
+): unknown {
+  const depth = options.depth ?? 0;
+  const at = (suffix: string) => path === "" ? suffix : path + ": " + suffix;
+  if (value === null || value === undefined) return value;
+  const variant = nullableVariant(schema);
+  if (variant) return checkValue(value, variant, path, issues, options);
+
+  const shallow = coerceShallow(value, schema);
+  if ("error" in shallow) {
+    issues.push({ code: "INVALID_ARGUMENT", argument: path, message: at(shallow.error) });
+    return value;
+  }
+  let out = shallow.value;
+  if (depth >= MAX_CHECK_DEPTH) return out;
+
+  if (typeof out === "string" && typeof schema.pattern === "string" && !options.skipPattern) {
+    let pattern: RegExp | undefined;
+    try { pattern = new RegExp(schema.pattern, "u"); } catch {
+      try { pattern = new RegExp(schema.pattern); } catch { /* not an ECMAScript pattern: never false-alarm */ }
+    }
+    if (pattern && !pattern.test(out)) {
+      issues.push({ code: "INVALID_ARGUMENT", argument: path, message: at("must match the pattern " + schema.pattern + ", got " + JSON.stringify(out)) });
+    }
+  }
+
+  // Array items: check each against the items schema when it has one.
+  if (Array.isArray(out) && schema.items && typeof schema.items === "object" && !Array.isArray(schema.items)) {
+    const itemSchema = schema.items as Record<string, unknown>;
+    out = out.map((item, i) => checkValue(item, itemSchema, path + "[" + i + "]", issues, { depth: depth + 1 }));
+  }
+
+  // Object properties: the same checks one level down, keyed by dotted path.
+  if (out && typeof out === "object" && !Array.isArray(out) && schema.properties && typeof schema.properties === "object") {
+    const properties = schema.properties as Record<string, Record<string, unknown>>;
+    const known = Object.keys(properties);
+    const closed = schema.additionalProperties === false;
+    const input = out as Record<string, unknown>;
+    const next: Record<string, unknown> = {};
+    const child = (key: string) => path === "" ? key : path + "." + key;
+    for (const [key, entry] of Object.entries(input)) {
+      if (entry === undefined) continue;
+      let name = key;
+      if (properties[key] === undefined && closed) {
+        const close = closestName(key, known);
+        if (close !== undefined && normalizeName(close) === normalizeName(key) && input[close] === undefined) {
+          name = close;
+        } else {
+          const accepted = known.length <= 20 ? " Accepted: " + known.join(", ") + "." : "";
+          issues.push({
+            code: "UNKNOWN_ARGUMENT",
+            argument: child(key),
+            message: "Unknown property \"" + child(key) + "\"" + (close !== undefined ? "; did you mean \"" + child(close) + "\"?" : ".") + accepted,
+          });
+          continue;
+        }
+      }
+      const propSchema = properties[name];
+      next[name] = propSchema && typeof propSchema === "object"
+        ? checkValue(entry, propSchema, child(name), issues, { depth: depth + 1, skipPattern: typeof entry === "string" && isMeReference(name, entry) })
+        : entry;
+    }
+    for (const name of Array.isArray(schema.required) ? schema.required as string[] : []) {
+      if (next[name] === undefined && properties[name] !== undefined) {
+        const description = properties[name]!.description;
+        issues.push({ code: "MISSING_ARGUMENT", argument: child(name), message: "Missing required property \"" + child(name) + "\"" + (description ? ": " + String(description).split("\n")[0] : ".") });
+      }
+    }
+    out = next;
+  }
+  return out;
+}
+
+export function userShapedReference(name: string): boolean {
+  const normalized = name.toLowerCase().replace(/[^a-z0-9]/g, "").replace(/ids?$/, "");
+  return ["user", "assignee", "owner", "member", "actor", "creator", "account", "profile", "subscriber"].includes(normalized);
+}
+
+/** "me" given for a user-shaped argument or property, resolved to the
+ * caller's ID through the identity tool. */
+export function isMeReference(name: string, value: string): boolean {
+  return value.trim().toLowerCase() === "me" && userShapedReference(name);
+}