@ganju/utils 0.0.12 → 0.0.14

package/dist/constants.js

@@ -815,7 +815,7 @@ const RESOURCE_SEARCH_COMMON_TERM_MIN = 5;
 const RESOURCE_SEARCH_RERANK_CANDIDATES = 30;
 const RESOURCE_SEARCH_RERANK_MODEL = '@cf/baai/bge-reranker-base';
 const RESOURCE_HANDLER_SLEEP_AFTER = '10m';
-const DOCS_URL = 'https://docs.ganju.ai';
+const DOCS_URL = 'https://ganju.ai/docs/';
 const BASE64_DATA_URI_RE = /data:image\/[a-zA-Z0-9+\-.]+;base64,[A-Za-z0-9+/=\s]+/g;
 const RAW_BASE64_BLOB_RE = /[A-Za-z0-9+/]{512,}={0,2}/g;
 const CHUNK_SEPARATORS = [

package/dist/toolLint.d.ts

@@ -15,7 +15,7 @@ export type ToolLintRule = (typeof TOOL_LINT_RULES)[number];
 export interface ToolLintFinding {
     rule: ToolLintRule;
     tool?: string;
-    other?: string;
+    alike?: string[];
     paths?: string[];
     count?: number;
     limit?: number;

package/dist/toolLint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolLint.d.ts","sourceRoot":"","sources":["../src/toolLint.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAED,eAAO,MAAM,eAAe,+JAQlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IAGnB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAI9B,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IAGxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAKnD,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAuHtC;;;GAGG;AACH,eAAO,MAAM,SAAS,GACpB,OAAO,YAAY,EAAE,EACrB,UAAS,eAAoB,KAC5B,eAAe,EA4EjB,CAAC"}
+{"version":3,"file":"toolLint.d.ts","sourceRoot":"","sources":["../src/toolLint.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAED,eAAO,MAAM,eAAe,+JAQlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IAGnB,IAAI,CAAC,EAAE,MAAM,CAAC;IAGd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAI9B,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IAGxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAKnD,eAAO,MAAM,mBAAmB,KAAK,CAAC;AA2JtC;;;GAGG;AACH,eAAO,MAAM,SAAS,GACpB,OAAO,YAAY,EAAE,EACrB,UAAS,eAAoB,KAC5B,eAAe,EA8FjB,CAAC"}

package/dist/toolLint.js

@@ -29,18 +29,26 @@ exports.TOOL_LINT_MIN_DESCRIPTION_LENGTH = 40;
 // start choosing among them badly. A channel turn hard-caps its list at 40
 // (CHANNEL_MAX_TOOLS); this warns well before that.
 exports.TOOL_LINT_MAX_TOOLS = 25;
-// Two descriptions sharing at least this much of their vocabulary (Jaccard,
-// over content words) read as the same tool to a model.
+// Two descriptions sharing at least this much of their vocabulary read as the
+// same tool to a model. Words are weighted by how rare they are among the
+// server's tools (see descriptionWeights), so tools written from one template
+// — "Use when someone asks about X" — are told apart by their X.
 const DESCRIPTION_OVERLAP = 0.6;
 // Too few content words and two unrelated descriptions can share most of them.
 const MIN_OVERLAP_WORDS = 5;
 // Lowercased, accents off, so "Úsala cuando" and "usala cuando" are one text.
-const fold = (text) => text.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '');
+const fold = (text) => text
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '');
 // Wording that tells a model WHEN to call a tool rather than only what it does
 // — English, Spanish and Portuguese, the languages descriptions here are
 // written in. Loose on purpose: a false "says when" costs nothing, a false
-// "doesn't" nags someone whose description is fine.
-const USAGE_GUIDANCE = /\b(use|uses|using|call|calls|when|whenever|before|after|instead|only if|if the user|if you|for questions|usa|usala|usalo|usar|llama|llamala|llamar|cuando|antes de|despues de|en lugar de|si el usuario|quando|use-a|utilize|chame)\b/;
+// "doesn't" nags someone whose description is fine. But not so loose that
+// words about how a tool works count: "uses the Stripe API" and "makes an API
+// call" say nothing about when to reach for it, so "call" counts only as an
+// instruction ("call this…", "call it…").
+const USAGE_GUIDANCE = /\b(use|call (?:this|it)|when|whenever|before|after|instead|only if|if the user|if you|for questions|usa|usala|usalo|usar|llama|llamala|llamar|cuando|antes de|despues de|en lugar de|si el usuario|quando|use-a|utilize|chame)\b/;
 const STOPWORDS = new Set([
     'the',
     'and',
@@ -82,31 +90,51 @@ const STOPWORDS = new Set([
 const contentWords = (text) => new Set(fold(text)
     .split(/[^a-z0-9]+/)
     .filter(word => word.length >= 3 && !STOPWORDS.has(word)));
+// A proxied tool is named `<server prefix>__<remote name>`. The prefix says
+// which connection it came from, not what it does, so `search_repositories`
+// and `github__search_repositories` are the same tool to a model. Kept here
+// rather than imported from constants (MCP_PROXY_TOOL_NAME_SEP), since this
+// file imports nothing.
+const PROXY_NAME_SEP = '__';
+const withoutProxyPrefix = (name) => {
+    const at = name.lastIndexOf(PROXY_NAME_SEP);
+    const bare = at === -1 ? name : name.slice(at + PROXY_NAME_SEP.length);
+    return bare || name;
+};
 // `lookupOrder`, `lookup-order` and `order_lookup` name the same thing.
-const nameTokens = (name) => name
+const nameTokens = (name) => withoutProxyPrefix(name)
     .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
     .toLowerCase()
     .split(/[^a-z0-9]+/)
     .filter(Boolean)
     .sort()
     .join(' ');
-const jaccard = (a, b) => {
+// How much each word says about which tool a description belongs to: a word
+// in every description (the template, the domain) next to nothing, a word in
+// one of them a lot. Smoothed, so with two tools a shared word still counts.
+const descriptionWeights = (descriptions) => {
+    const frequency = new Map();
+    for (const words of descriptions) {
+        for (const word of words) {
+            frequency.set(word, (frequency.get(word) ?? 0) + 1);
+        }
+    }
+    const total = descriptions.length;
+    return word => Math.log(1 + total / (frequency.get(word) ?? 1));
+};
+// Jaccard, with each word counted by its weight.
+const weightedJaccard = (a, b, weight) => {
     let shared = 0;
-    for (const word of a)
+    let union = 0;
+    for (const word of a) {
+        union += weight(word);
         if (b.has(word))
-            shared++;
-    const union = a.size + b.size - shared;
-    return union === 0 ? 0 : shared / union;
-};
-const overlaps = (a, b) => {
-    if (nameTokens(a.name) === nameTokens(b.name))
-        return true;
-    const aWords = contentWords(a.description ?? '');
-    const bWords = contentWords(b.description ?? '');
-    if (aWords.size < MIN_OVERLAP_WORDS || bWords.size < MIN_OVERLAP_WORDS) {
-        return false;
+            shared += weight(word);
     }
-    return jaccard(aWords, bWords) >= DESCRIPTION_OVERLAP;
+    for (const word of b)
+        if (!a.has(word))
+            union += weight(word);
+    return union === 0 ? 0 : shared / union;
 };
 const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 // Every property the model may fill in that doesn't say what it is for, down
@@ -140,6 +168,19 @@ const quoted = (name) => `"${name}"`;
 const lintTools = (tools, options = {}) => {
     const others = options.others ?? [];
     const findings = [];
+    const everyTool = [...tools, ...others];
+    const wordsOf = new Map(everyTool.map(tool => [tool, contentWords(tool.description ?? '')]));
+    const weight = descriptionWeights([...wordsOf.values()]);
+    const overlaps = (a, b) => {
+        if (nameTokens(a.name) === nameTokens(b.name))
+            return true;
+        const aWords = wordsOf.get(a);
+        const bWords = wordsOf.get(b);
+        if (aWords.size < MIN_OVERLAP_WORDS || bWords.size < MIN_OVERLAP_WORDS) {
+            return false;
+        }
+        return weightedJaccard(aWords, bWords, weight) >= DESCRIPTION_OVERLAP;
+    };
     tools.forEach((tool, index) => {
         const description = (tool.description ?? '').trim();
         if (!description) {
@@ -184,16 +225,18 @@ const lintTools = (tools, options = {}) => {
                 message: `${quoted(tool.name)} has input properties with no description: ${paths.join(', ')}. A model has to guess what to pass.`
             });
         }
-        // Each pair once: against the tools after this one, then the rest of the
-        // server.
-        for (const other of [...tools.slice(index + 1), ...others]) {
-            if (other.name === tool.name || !overlaps(tool, other))
-                continue;
+        // Each pair once — against the tools after this one, then the rest of the
+        // server — and one finding per tool, so twenty look-alikes are nineteen
+        // lines rather than a hundred and ninety.
+        const alike = [...tools.slice(index + 1), ...others]
+            .filter(other => other.name !== tool.name && overlaps(tool, other))
+            .map(other => other.name);
+        if (alike.length > 0) {
             findings.push({
                 rule: 'overlapping-tools',
                 tool: tool.name,
-                other: other.name,
-                message: `${quoted(tool.name)} and ${quoted(other.name)} look alike in name or description, so a model may call one for the other. Make each description say what sets it apart.`
+                alike,
+                message: `${quoted(tool.name)} looks like ${alike.map(quoted).join(', ')} in name or description, so a model may call one for another. Make each description say what sets it apart.`
             });
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganju/utils",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Shared constants, schemas and helpers for Ganju",
   "license": "Apache-2.0",
   "author": "MontoyaAndres <andresmontoyafcb@gmail.com>",

package/src/constants.ts

@@ -967,7 +967,7 @@ const RESOURCE_SEARCH_RERANK_MODEL = '@cf/baai/bge-reranker-base';
 
 const RESOURCE_HANDLER_SLEEP_AFTER = '10m';
 
-const DOCS_URL = 'https://docs.ganju.ai';
+const DOCS_URL = 'https://ganju.ai/docs/';
 
 const BASE64_DATA_URI_RE =
   /data:image\/[a-zA-Z0-9+\-.]+;base64,[A-Za-z0-9+/=\s]+/g;

package/src/toolLint.ts

@@ -43,8 +43,9 @@ export interface ToolLintFinding {
   // The tool the finding is about. Absent only for `too-many-tools`, which is
   // about the server as a whole.
   tool?: string;
-  // `overlapping-tools`: the tool it is confused with.
-  other?: string;
+  // `overlapping-tools`: the tools it may be confused with. Each look-alike
+  // pair is reported once, on the first of the two.
+  alike?: string[];
   // `undescribed-input`: the properties with no description, as dotted paths.
   paths?: string[];
   // `too-many-tools`: how many are enabled, and the number past which it warns.
@@ -74,22 +75,30 @@ export const TOOL_LINT_MIN_DESCRIPTION_LENGTH = 40;
 // (CHANNEL_MAX_TOOLS); this warns well before that.
 export const TOOL_LINT_MAX_TOOLS = 25;
 
-// Two descriptions sharing at least this much of their vocabulary (Jaccard,
-// over content words) read as the same tool to a model.
+// Two descriptions sharing at least this much of their vocabulary read as the
+// same tool to a model. Words are weighted by how rare they are among the
+// server's tools (see descriptionWeights), so tools written from one template
+// — "Use when someone asks about X" — are told apart by their X.
 const DESCRIPTION_OVERLAP = 0.6;
 // Too few content words and two unrelated descriptions can share most of them.
 const MIN_OVERLAP_WORDS = 5;
 
 // Lowercased, accents off, so "Úsala cuando" and "usala cuando" are one text.
 const fold = (text: string): string =>
-  text.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '');
+  text
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '');
 
 // Wording that tells a model WHEN to call a tool rather than only what it does
 // — English, Spanish and Portuguese, the languages descriptions here are
 // written in. Loose on purpose: a false "says when" costs nothing, a false
-// "doesn't" nags someone whose description is fine.
+// "doesn't" nags someone whose description is fine. But not so loose that
+// words about how a tool works count: "uses the Stripe API" and "makes an API
+// call" say nothing about when to reach for it, so "call" counts only as an
+// instruction ("call this…", "call it…").
 const USAGE_GUIDANCE =
-  /\b(use|uses|using|call|calls|when|whenever|before|after|instead|only if|if the user|if you|for questions|usa|usala|usalo|usar|llama|llamala|llamar|cuando|antes de|despues de|en lugar de|si el usuario|quando|use-a|utilize|chame)\b/;
+  /\b(use|call (?:this|it)|when|whenever|before|after|instead|only if|if the user|if you|for questions|usa|usala|usalo|usar|llama|llamala|llamar|cuando|antes de|despues de|en lugar de|si el usuario|quando|use-a|utilize|chame)\b/;
 
 const STOPWORDS = new Set([
   'the',
@@ -137,9 +146,22 @@ const contentWords = (text: string): Set<string> =>
       .filter(word => word.length >= 3 && !STOPWORDS.has(word))
   );
 
+// A proxied tool is named `<server prefix>__<remote name>`. The prefix says
+// which connection it came from, not what it does, so `search_repositories`
+// and `github__search_repositories` are the same tool to a model. Kept here
+// rather than imported from constants (MCP_PROXY_TOOL_NAME_SEP), since this
+// file imports nothing.
+const PROXY_NAME_SEP = '__';
+
+const withoutProxyPrefix = (name: string): string => {
+  const at = name.lastIndexOf(PROXY_NAME_SEP);
+  const bare = at === -1 ? name : name.slice(at + PROXY_NAME_SEP.length);
+  return bare || name;
+};
+
 // `lookupOrder`, `lookup-order` and `order_lookup` name the same thing.
 const nameTokens = (name: string): string =>
-  name
+  withoutProxyPrefix(name)
     .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
     .toLowerCase()
     .split(/[^a-z0-9]+/)
@@ -147,21 +169,36 @@ const nameTokens = (name: string): string =>
     .sort()
     .join(' ');
 
-const jaccard = (a: Set<string>, b: Set<string>): number => {
-  let shared = 0;
-  for (const word of a) if (b.has(word)) shared++;
-  const union = a.size + b.size - shared;
-  return union === 0 ? 0 : shared / union;
+// How much each word says about which tool a description belongs to: a word
+// in every description (the template, the domain) next to nothing, a word in
+// one of them a lot. Smoothed, so with two tools a shared word still counts.
+const descriptionWeights = (
+  descriptions: Set<string>[]
+): ((word: string) => number) => {
+  const frequency = new Map<string, number>();
+  for (const words of descriptions) {
+    for (const word of words) {
+      frequency.set(word, (frequency.get(word) ?? 0) + 1);
+    }
+  }
+  const total = descriptions.length;
+  return word => Math.log(1 + total / (frequency.get(word) ?? 1));
 };
 
-const overlaps = (a: LintableTool, b: LintableTool): boolean => {
-  if (nameTokens(a.name) === nameTokens(b.name)) return true;
-  const aWords = contentWords(a.description ?? '');
-  const bWords = contentWords(b.description ?? '');
-  if (aWords.size < MIN_OVERLAP_WORDS || bWords.size < MIN_OVERLAP_WORDS) {
-    return false;
+// Jaccard, with each word counted by its weight.
+const weightedJaccard = (
+  a: Set<string>,
+  b: Set<string>,
+  weight: (word: string) => number
+): number => {
+  let shared = 0;
+  let union = 0;
+  for (const word of a) {
+    union += weight(word);
+    if (b.has(word)) shared += weight(word);
   }
-  return jaccard(aWords, bWords) >= DESCRIPTION_OVERLAP;
+  for (const word of b) if (!a.has(word)) union += weight(word);
+  return union === 0 ? 0 : shared / union;
 };
 
 const isObject = (value: unknown): value is Record<string, unknown> =>
@@ -202,6 +239,21 @@ export const lintTools = (
   const others = options.others ?? [];
   const findings: ToolLintFinding[] = [];
 
+  const everyTool = [...tools, ...others];
+  const wordsOf = new Map(
+    everyTool.map(tool => [tool, contentWords(tool.description ?? '')])
+  );
+  const weight = descriptionWeights([...wordsOf.values()]);
+  const overlaps = (a: LintableTool, b: LintableTool): boolean => {
+    if (nameTokens(a.name) === nameTokens(b.name)) return true;
+    const aWords = wordsOf.get(a)!;
+    const bWords = wordsOf.get(b)!;
+    if (aWords.size < MIN_OVERLAP_WORDS || bWords.size < MIN_OVERLAP_WORDS) {
+      return false;
+    }
+    return weightedJaccard(aWords, bWords, weight) >= DESCRIPTION_OVERLAP;
+  };
+
   tools.forEach((tool, index) => {
     const description = (tool.description ?? '').trim();
 
@@ -250,15 +302,18 @@ export const lintTools = (
       });
     }
 
-    // Each pair once: against the tools after this one, then the rest of the
-    // server.
-    for (const other of [...tools.slice(index + 1), ...others]) {
-      if (other.name === tool.name || !overlaps(tool, other)) continue;
+    // Each pair once — against the tools after this one, then the rest of the
+    // server — and one finding per tool, so twenty look-alikes are nineteen
+    // lines rather than a hundred and ninety.
+    const alike = [...tools.slice(index + 1), ...others]
+      .filter(other => other.name !== tool.name && overlaps(tool, other))
+      .map(other => other.name);
+    if (alike.length > 0) {
       findings.push({
         rule: 'overlapping-tools',
         tool: tool.name,
-        other: other.name,
-        message: `${quoted(tool.name)} and ${quoted(other.name)} look alike in name or description, so a model may call one for the other. Make each description say what sets it apart.`
+        alike,
+        message: `${quoted(tool.name)} looks like ${alike.map(quoted).join(', ')} in name or description, so a model may call one for another. Make each description say what sets it apart.`
       });
     }
   });