@typeship-ax/cli 0.22.0 → 0.23.1

package/src/search.ts

@@ -0,0 +1,434 @@
+/**
+ * Operation search shared by the generated CLI (`docs search`) and MCP
+ * server (`search_docs`). Generated by Typeship — https://typeship.dev
+ *
+ * Agents describe a task ("assign issue", "list calls"), not an operation
+ * name, so ranking works on stems, weighs rare words over common ones
+ * (IDF), and reads the verb of the query against what each operation does:
+ * its HTTP method and whether its path names one item or a collection, or
+ * its GraphQL root field. GraphQL mutations are also indexed by their input
+ * fields, so "assign issue" finds issueUpdate through assigneeId.
+ * Deterministic and dependency-free.
+ */
+
+/** The parts of an operation search reads. The CLI and MCP operation
+ * specs both satisfy it. */
+export interface SearchableOperation {
+  tool: string;
+  resource?: string;
+  method?: string;
+  httpMethod: string;
+  path: string;
+  summary?: string;
+  description?: string;
+  paginated?: boolean;
+  deprecated?: boolean;
+  graphql?: { kind: string; field?: string };
+  params: readonly { name: string; enum?: readonly string[]; description?: string }[];
+  inputSchema?: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+}
+
+/** Reference matches per search page. */
+export const SEARCH_PAGE_SIZE = 10;
+
+type Action = "list" | "get" | "create" | "update" | "delete" | "search";
+
+/** Query verbs and the operation kinds they ask for, best first. */
+const VERBS: Record<string, Action[]> = {
+  list: ["list"], all: ["list"], browse: ["list"], enumerate: ["list"],
+  search: ["search", "list"], find: ["search", "list", "get"], query: ["search", "list"], lookup: ["get", "search"],
+  get: ["get", "list"], release: ["delete"], fetch: ["get", "list"], retrieve: ["get", "list"], read: ["get", "list"], show: ["get", "list"],
+  view: ["get", "list"], check: ["get"], describe: ["get"], inspect: ["get"], status: ["get"],
+  create: ["create"], add: ["create", "update"], new: ["create"], make: ["create"], send: ["create"], post: ["create"],
+  submit: ["create"], open: ["create"], start: ["create", "update"], upload: ["create", "update"], generate: ["create"],
+  buy: ["create"], purchase: ["create"], place: ["create"], invite: ["create"], write: ["create", "update"],
+  publish: ["create", "update"], register: ["create"],
+  update: ["update"], change: ["update"], edit: ["update"], modify: ["update"], set: ["update", "create"],
+  assign: ["update", "create"], rename: ["update"], move: ["update"], close: ["update", "delete"], reopen: ["update"],
+  mark: ["update"], archive: ["delete", "update"], unarchive: ["update"], enable: ["update"], disable: ["update"],
+  pause: ["update"], resume: ["update"], replace: ["update"], patch: ["update"], merge: ["update", "create"],
+  save: ["create", "update"], follow: ["create", "update"], unfollow: ["delete", "update"], comment: ["create"], reply: ["create"], request: ["create"], hang: ["update", "delete"],
+  delete: ["delete"], remove: ["delete", "update"], destroy: ["delete"], erase: ["delete"], drop: ["delete"],
+  revoke: ["delete"], cancel: ["delete", "update"], unassign: ["update", "delete"], clear: ["delete"],
+};
+
+/** Words that name the caller: "who am I", "my issues", "me". */
+const IDENTITY_WORDS = new Set(["who", "whoami", "me", "my", "mine", "myself", "self"]);
+const IDENTITY_TERMS = ["me", "self", "whoami", "authenticated"];
+
+/** An operation about the caller: GET /user, /me/…, a viewer or me root
+ * field, users_get_authenticated. */
+function isIdentityOperation(op: SearchableOperation): boolean {
+  if (op.graphql?.field) return /^(viewer|me|currentUser|whoami)$/.test(op.graphql.field);
+  const nameWords = words([op.tool, op.method ?? ""].join(" "));
+  if (nameWords.some((w) => w === "me" || w === "whoami" || w === "authenticated" || w === "self")) return true;
+  return /^(\/v\d+)?\/(me|user|self|whoami)(\/|$)/i.test(op.path) || /\/(users\/)?me(\/|$)/i.test(op.path);
+}
+
+/** Words that narrow a request rather than name the operation. */
+const QUALIFIERS = new Set(["yesterday", "today", "tomorrow", "recent", "recently", "latest", "last", "week", "month", "year", "daily"]);
+
+/** A few everyday words for what APIs call something else. */
+const SYNONYMS: Record<string, string[]> = {
+  now: ["current"], sms: ["message"], mms: ["message"], text: ["message"], document: ["file"], kyc: ["identity", "verification"],
+};
+
+const STOPWORDS = new Set([
+  "a", "an", "the", "to", "of", "for", "in", "on", "at", "from", "by", "with", "and", "or", "is", "are", "am", "be",
+  "do", "does", "it", "its", "this", "that", "these", "those", "into", "onto", "up", "how", "what", "which", "can",
+  "please", "via", "using", "some", "any", "there", "i", "you", "your", "we", "our",
+]);
+
+/** Field weights: a word in the operation's name says most about it. */
+const W_NAME = 10, W_SUMMARY = 6, W_PATH = 4, W_PARAM = 3, W_ENUM = 2, W_DESCRIPTION = 1.5, W_OUTPUT = 1;
+
+/** A light English stemmer: plurals, -ing/-ed, a few derivational
+ * suffixes, a trailing e. It only has to map a word and its common
+ * variants to one stem ("assignee", "assigned", "assigns" to "assign";
+ * "moderate", "moderations" to "moder"). */
+export function stem(word: string): string {
+  let w = word.toLowerCase();
+  if (w.length <= 3) return w;
+  if (w.endsWith("ies") && w.length > 4) w = w.slice(0, -3) + "y";
+  else if (/(sses|xes|ches|shes|zes)$/.test(w)) w = w.slice(0, -2);
+  else if (w.endsWith("s") && !/(ss|us|is)$/.test(w)) w = w.slice(0, -1);
+  let stripped = false;
+  if (w.endsWith("ly") && w.length >= 6) w = w.slice(0, -2);
+  for (const [suffix, min] of [["ing", 4], ["ed", 3]] as const) {
+    if (w.endsWith(suffix) && w.length - suffix.length >= min) {
+      w = w.slice(0, -suffix.length);
+      stripped = true;
+      break;
+    }
+  }
+  if (stripped) {
+    if (/(at|bl|iz)$/.test(w)) w += "e";
+    else if (/([^aeioulsz])\1$/.test(w)) w = w.slice(0, -1);
+  }
+  for (const [suffix, min] of [["ations", 4], ["ation", 4], ["ments", 4], ["ment", 4], ["ption", 4], ["ions", 4], ["ion", 4], ["ers", 4], ["er", 4], ["ee", 4], ["ate", 4]] as const) {
+    if (w.endsWith(suffix) && w.length - suffix.length >= min) {
+      w = w.slice(0, -suffix.length);
+      break;
+    }
+  }
+  if (w.endsWith("e") && w.length >= 5) w = w.slice(0, -1);
+  return w;
+}
+
+/** Lowercase words of two or more characters, with snake, kebab, camel and
+ * letter-digit seams split so "createAccount" and "accounts_create" share
+ * words. */
+function words(text: string): string[] {
+  return text.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([a-zA-Z])([0-9])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 2);
+}
+
+function stems(text: string): string[] {
+  return words(text).filter((w) => !STOPWORDS.has(w)).map(stem);
+}
+
+interface IndexedOperation {
+  /** stem -> best field weight, and the sum of the others. */
+  weights: Map<string, { best: number; rest: number }>;
+  /** Distinct stems of the operation's name, less its action word. */
+  nameStems: string[];
+  action: Action;
+  identity: boolean;
+  /** The summary's stems, for a query that is the summary. */
+  summary: string;
+  /** The stem of the name's verb ("add" in issue_add_label), if any. */
+  actionStem: string | null;
+  deprecated: boolean;
+}
+
+interface SearchIndex {
+  docs: IndexedOperation[];
+  /** Document frequency of each stem. */
+  df: Map<string, number>;
+  vocabulary: string[];
+}
+
+// A server keeps one operation list, and a hosted one filters the same
+// operation objects per request: cache by both.
+const INDEXES = new WeakMap<readonly SearchableOperation[], SearchIndex>();
+const INDEXED = new WeakMap<SearchableOperation, IndexedOperation>();
+
+const READ_ACTIONS: readonly Action[] = ["list", "get", "search"];
+const WRITE_ACTIONS: readonly Action[] = ["create", "update", "delete"];
+
+/** The first of `words` (in order) that names an allowed action. */
+function actionIn(candidates: string[], allowed: readonly Action[]): { action: Action; word: string } | undefined {
+  for (const word of candidates) {
+    const action = VERBS[word]?.[0];
+    if (action && allowed.includes(action)) return { action, word };
+  }
+  return undefined;
+}
+
+/** What an operation does, and the word of its name that says so: its
+ * name's verb when it has one, else its HTTP method and whether the path
+ * ends at one item or a collection. A read never creates, updates or
+ * deletes, whatever its name ("query comment" is a read of a comment). */
+function operationAction(op: SearchableOperation): { action: Action; word: string | null } {
+  const collection = (): Action => {
+    const segments = op.path.replace(/\.[a-z]+$/i, "").split("/").filter(Boolean);
+    const last = segments.at(-1) ?? "";
+    if (last.startsWith("{") || last.startsWith(":")) return "get";
+    return op.paginated ? "list" : "get";
+  };
+  if (op.graphql?.field) {
+    // issueUpdate, createIssue: the verb may sit at either end.
+    const fieldWords = words(op.graphql.field);
+    const read = op.graphql.kind !== "mutation";
+    const found = actionIn([...fieldWords].reverse(), read ? READ_ACTIONS : WRITE_ACTIONS);
+    if (found) return found;
+    return { action: read ? (op.paginated || /s$/.test(op.graphql.field) ? "list" : "get") : "update", word: null };
+  }
+  const verb = op.httpMethod.toUpperCase();
+  const read = verb === "GET" || verb === "HEAD";
+  const found = actionIn(words(op.method ?? ""), read ? READ_ACTIONS : [...WRITE_ACTIONS, "search"]);
+  if (found) return found;
+  if (verb === "DELETE") return { action: "delete", word: null };
+  if (verb === "PUT" || verb === "PATCH") return { action: "update", word: null };
+  if (verb === "POST") return { action: "create", word: null };
+  return { action: collection(), word: null };
+}
+
+/** Literal path words: no parameters, versions or date segments. */
+function pathWords(path: string): string {
+  return path.replace(/\.[a-z]+$/i, "").split("/").filter((s) => s && !/^[{:]/.test(s) && !/^v\d+$/i.test(s) && !/^\d/.test(s)).join(" ");
+}
+
+/** Property names and enum values of a schema, one level into objects,
+ * and one more for object-typed properties (a GraphQL input object). */
+function schemaWords(schema: unknown, depth: number, names: string[], enums: string[]): void {
+  if (!schema || typeof schema !== "object" || depth < 0) return;
+  const node = schema as Record<string, unknown>;
+  if (Array.isArray(node.enum)) for (const value of node.enum) if (typeof value === "string") enums.push(value);
+  for (const key of ["anyOf", "oneOf", "allOf"]) {
+    if (Array.isArray(node[key])) for (const part of node[key] as unknown[]) schemaWords(part, depth, names, enums);
+  }
+  if (node.items) schemaWords(node.items, depth, names, enums);
+  const properties = node.properties as Record<string, unknown> | undefined;
+  if (properties && typeof properties === "object") {
+    for (const [name, child] of Object.entries(properties)) {
+      names.push(name);
+      schemaWords(child, depth - 1, names, enums);
+    }
+  }
+}
+
+function outputWords(schema: unknown, depth: number, out: string[]): void {
+  if (!schema || typeof schema !== "object" || depth < 0) return;
+  const node = schema as Record<string, unknown>;
+  if (typeof node.description === "string") out.push(node.description.slice(0, 200));
+  if (node.items) outputWords(node.items, depth, out);
+  for (const key of ["anyOf", "oneOf", "allOf"]) {
+    if (Array.isArray(node[key])) for (const part of node[key] as unknown[]) outputWords(part, depth, out);
+  }
+  const properties = node.properties as Record<string, unknown> | undefined;
+  if (properties && typeof properties === "object") {
+    for (const [name, child] of Object.entries(properties)) {
+      out.push(name);
+      outputWords(child, depth - 1, out);
+    }
+  }
+}
+
+function firstSentence(text: string): string {
+  return /^(.{1,200}?[.!?])(\s|$)/s.exec(text.trim())?.[1] ?? "";
+}
+
+function indexOperation(op: SearchableOperation): IndexedOperation {
+  const weights = new Map<string, { best: number; rest: number }>();
+  const add = (text: string, weight: number) => {
+    for (const s of new Set(stems(text))) {
+      const entry = weights.get(s);
+      if (!entry) weights.set(s, { best: weight, rest: 0 });
+      else if (weight > entry.best) { entry.rest += entry.best; entry.best = weight; }
+      else entry.rest += weight;
+    }
+  };
+  // GraphQL tools are named query_<field> / mutation_<field>; the prefix is
+  // the kind, not a word a task would use.
+  const name = op.graphql?.field
+    ? [op.graphql.field]
+    : [op.tool, op.resource ?? "", op.method ?? ""];
+  add(name.join(" "), W_NAME);
+  // Without a summary, the description's first sentence plays its part.
+  const summary = op.summary?.trim() || firstSentence(op.description ?? "");
+  add(summary, W_SUMMARY);
+  add(pathWords(op.path), W_PATH);
+  const paramNames: string[] = [];
+  const enumValues: string[] = [];
+  const paramText: string[] = [];
+  for (const param of op.params) {
+    paramNames.push(param.name);
+    if (param.enum) enumValues.push(...param.enum);
+    if (param.description) paramText.push(param.description.split("\n")[0]!.slice(0, 200));
+  }
+  const properties = (op.inputSchema?.properties ?? {}) as Record<string, unknown>;
+  for (const child of Object.values(properties)) schemaWords(child, 1, paramNames, enumValues);
+  add(paramNames.join(" "), W_PARAM);
+  add(enumValues.join(" "), W_ENUM);
+  add(op.description ?? "", W_DESCRIPTION);
+  add(paramText.join(" "), W_OUTPUT);
+  const output: string[] = [];
+  outputWords(op.outputSchema, 2, output);
+  add(output.join(" "), W_OUTPUT);
+  const { action, word } = operationAction(op);
+  const actionStem = word === null ? null : stem(word);
+  const nameStems = [...new Set(stems(name.join(" ")))].filter((s) => s !== actionStem);
+  return { weights, nameStems, action, actionStem, identity: isIdentityOperation(op), summary: stems(summary).join(" "), deprecated: op.deprecated === true || /^deprecated\b/i.test(op.summary ?? "") };
+}
+
+function indexFor(ops: readonly SearchableOperation[]): SearchIndex {
+  const cached = INDEXES.get(ops);
+  if (cached) return cached;
+  const docs = ops.map((op) => {
+    let doc = INDEXED.get(op);
+    if (!doc) INDEXED.set(op, doc = indexOperation(op));
+    return doc;
+  });
+  const df = new Map<string, number>();
+  for (const doc of docs) for (const s of doc.weights.keys()) df.set(s, (df.get(s) ?? 0) + 1);
+  const index = { docs, df, vocabulary: [...df.keys()] };
+  INDEXES.set(ops, index);
+  return index;
+}
+
+/** A query stem's matches in the vocabulary: itself, and longer or
+ * shorter forms sharing a long prefix ("transcrib" and "transcript"),
+ * which count for less. */
+function variants(term: string, index: SearchIndex): Map<string, number> {
+  const out = new Map<string, number>();
+  if (index.df.has(term)) out.set(term, 1);
+  if (term.length < 5) return out;
+  for (const word of index.vocabulary) {
+    if (word === term || word.length < 5) continue;
+    let common = 0;
+    while (common < word.length && common < term.length && word[common] === term[common]) common++;
+    if (common >= 6 && Math.max(word.length, term.length) - common <= 3) out.set(word, 0.6);
+  }
+  return out;
+}
+
+interface QueryTerm {
+  /** Vocabulary stem -> match strength. */
+  matches: Map<string, number>;
+  /** How much the term counts: the task's object most, its verb and
+   * qualifiers ("yesterday") least. */
+  weight: number;
+  /** The query's verb: the operation kinds it asks for, best first. */
+  verb: Action[] | null;
+  /** The first noun, usually the object of the task. */
+  primary: boolean;
+  stem: string;
+}
+
+function parseQuery(query: string, index: SearchIndex): { terms: QueryTerm[]; verb: Action[] | null } {
+  const raw = words(query);
+  let verb: Action[] | null = null;
+  let identity = false;
+  const terms: QueryTerm[] = [];
+  const seen = new Set<string>();
+  for (const word of raw) {
+    if (IDENTITY_WORDS.has(word)) { identity = true; continue; }
+    if (STOPWORDS.has(word)) continue;
+    const s = stem(word);
+    if (seen.has(s)) continue;
+    seen.add(s);
+    const actions = VERBS[word] ?? VERBS[s] ?? null;
+    const isVerb = actions !== null && actions.length > 0 && verb === null;
+    if (isVerb) verb = actions;
+    const matches = variants(s, index);
+    for (const synonym of SYNONYMS[word] ?? []) for (const [v, strength] of variants(stem(synonym), index)) matches.set(v, Math.max(matches.get(v) ?? 0, strength * 0.8));
+    // The verb is scored against what the operation does, so its word
+    // counts for little; the first noun is usually the object of the task.
+    const qualifier = QUALIFIERS.has(word);
+    const primary = !isVerb && !qualifier && !terms.some((t) => t.primary);
+    const weight = isVerb || qualifier ? 0.3 : primary ? 1.3 : 1;
+    terms.push({ matches, weight, verb: isVerb ? actions : null, primary, stem: s });
+  }
+  if (identity) {
+    const matches = new Map<string, number>();
+    for (const t of IDENTITY_TERMS) for (const [s, strength] of variants(stem(t), index)) matches.set(s, Math.max(matches.get(s) ?? 0, strength));
+    terms.push({ matches, weight: 0.8, verb: null, primary: false, stem: "@me" });
+  }
+  return { terms, verb };
+}
+
+export interface RankedOperation<T> {
+  op: T;
+  score: number;
+}
+
+/**
+ * Operations for a free-text query, best first. Weak matches (under a
+ * fifth of the best score, or matching only the query's verb) are left
+ * out, and deprecated operations follow every current one.
+ */
+export function rankOperations<T extends SearchableOperation>(ops: readonly T[], query: string): RankedOperation<T>[] {
+  const index = indexFor(ops);
+  const { terms, verb } = parseQuery(query, index);
+  if (terms.length === 0) return [];
+  const idf = (s: string) => Math.log(1 + index.docs.length / (index.df.get(s) ?? index.docs.length));
+  const nonVerbTerms = terms.filter((t) => t.verb === null).length;
+  const primary = terms.find((t) => t.primary);
+  const verbStem = terms.find((t) => t.verb !== null)?.stem ?? null;
+  const identityTerm = terms.find((t) => t.stem === "@me");
+  const identityIdf = Math.log(1 + index.docs.length / Math.max(1, index.docs.filter((d) => d.identity).length));
+  const scored: { op: T; score: number; deprecated: boolean }[] = [];
+  const phrase = words(query).filter((w) => !STOPWORDS.has(w)).map(stem).join(" ");
+  index.docs.forEach((doc, position) => {
+    let score = 0;
+    let matchedNonVerb = 0;
+    let primaryInName = false;
+    let verbInName = false;
+    const covered = new Set<string>();
+    for (const term of terms) {
+      let best = term === identityTerm && doc.identity ? W_NAME * identityIdf : 0;
+      for (const [s, strength] of term.matches) {
+        const entry = doc.weights.get(s);
+        if (!entry) continue;
+        const value = (entry.best + 0.1 * Math.min(entry.rest, 10)) * strength * idf(s);
+        if (value > best) best = value;
+        if (doc.nameStems.includes(s)) {
+          covered.add(s);
+          if (term === primary) primaryInName = true;
+          // The query's verb as a noun of the name: upload_url for "upload".
+          if (term.verb !== null) verbInName = true;
+        }
+      }
+      if (best > 0 && term.verb === null) matchedNonVerb++;
+      score += best * term.weight;
+    }
+    if (score === 0) return;
+    if (nonVerbTerms > 0 && matchedNonVerb === 0) return;
+    // How much of the operation's name the query accounts for: call_list
+    // for "list calls" over sip_auth_calls_credential_list_mapping_delete.
+    const coverage = doc.nameStems.length === 0 ? 1 : covered.size / doc.nameStems.length;
+    score *= 0.6 + 0.8 * coverage;
+    // The query's verb against what the operation does.
+    if (verb) {
+      const rank = verb.indexOf(doc.action);
+      score *= rank === 0 ? 1.5 : rank > 0 ? 1.2 : doc.action === "search" && verb.includes("list") ? 1.2 : verbInName ? 1 : 0.55;
+      // The very word: issue_add_label for "add", over a generic create.
+      if (verbStem !== null && doc.actionStem === verbStem) score *= 1.2;
+    }
+    // Every query word matched: a stronger signal than any single word.
+    if (matchedNonVerb === nonVerbTerms && nonVerbTerms > 1) score *= 1.2;
+    if (phrase.includes(" ") && doc.nameStems.join(" ").includes(phrase)) score *= 1.2;
+    if (phrase.includes(" ") && doc.summary.includes(phrase)) score *= 1.3;
+    // The operation is named for the task's object: issue_update, not
+    // workflow_state_update, for "change issue state".
+    if (primaryInName) score *= 1.3;
+    scored.push({ op: ops[position]!, score, deprecated: doc.deprecated });
+  });
+  if (scored.length === 0) return [];
+  const top = Math.max(...scored.map((s) => s.score));
+  return scored
+    .filter((s) => s.score >= top * 0.2)
+    .sort((a, b) => Number(a.deprecated) - Number(b.deprecated) || b.score - a.score || a.op.tool.localeCompare(b.op.tool))
+    .map(({ op, score }) => ({ op, score: Math.round(score * 100) / 100 }));
+}