@agentskit/doc-bridge 0.1.0-alpha.2 → 0.1.0-alpha.3

package/dist/index.d.ts

@@ -272,6 +272,8 @@ declare const KnowledgeEntrySchema: z.ZodObject<{
     title: z.ZodString;
     path: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    /** Flattened body excerpt for full-text search (not for display). */
+    body: z.ZodOptional<z.ZodString>;
     links: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
@@ -280,6 +282,7 @@ declare const KnowledgeEntrySchema: z.ZodObject<{
     id: string;
     title: string;
     description?: string | undefined;
+    body?: string | undefined;
     links?: string[] | undefined;
     tags?: string[] | undefined;
 }, {
@@ -288,6 +291,7 @@ declare const KnowledgeEntrySchema: z.ZodObject<{
     id: string;
     title: string;
     description?: string | undefined;
+    body?: string | undefined;
     links?: string[] | undefined;
     tags?: string[] | undefined;
 }>;
@@ -328,6 +332,8 @@ declare const DocBridgeIndexV1Schema: z.ZodObject<{
         title: z.ZodString;
         path: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
+        /** Flattened body excerpt for full-text search (not for display). */
+        body: z.ZodOptional<z.ZodString>;
         links: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
@@ -336,6 +342,7 @@ declare const DocBridgeIndexV1Schema: z.ZodObject<{
         id: string;
         title: string;
         description?: string | undefined;
+        body?: string | undefined;
         links?: string[] | undefined;
         tags?: string[] | undefined;
     }, {
@@ -344,6 +351,7 @@ declare const DocBridgeIndexV1Schema: z.ZodObject<{
         id: string;
         title: string;
         description?: string | undefined;
+        body?: string | undefined;
         links?: string[] | undefined;
         tags?: string[] | undefined;
     }>, "many">;
@@ -550,6 +558,7 @@ declare const DocBridgeIndexV1Schema: z.ZodObject<{
         id: string;
         title: string;
         description?: string | undefined;
+        body?: string | undefined;
         links?: string[] | undefined;
         tags?: string[] | undefined;
     }[];
@@ -623,6 +632,7 @@ declare const DocBridgeIndexV1Schema: z.ZodObject<{
         id: string;
         title: string;
         description?: string | undefined;
+        body?: string | undefined;
         links?: string[] | undefined;
         tags?: string[] | undefined;
     }[];
@@ -952,7 +962,11 @@ declare const DocBridgeIndexV1JsonSchema: {
                     };
                     readonly description: {
                         readonly type: "string";
-                        readonly maxLength: 1024;
+                        readonly maxLength: 2048;
+                    };
+                    readonly body: {
+                        readonly type: "string";
+                        readonly maxLength: 8000;
                     };
                     readonly links: JsonSchema;
                     readonly tags: JsonSchema;
@@ -1170,7 +1184,11 @@ declare const DocBridgeJsonSchemas: {
                         };
                         readonly description: {
                             readonly type: "string";
-                            readonly maxLength: 1024;
+                            readonly maxLength: 2048;
+                        };
+                        readonly body: {
+                            readonly type: "string";
+                            readonly maxLength: 8000;
                         };
                         readonly links: JsonSchema;
                         readonly tags: JsonSchema;
@@ -1517,7 +1535,7 @@ declare const chunksFromMarkdown: (property: string, raw: string, sourceUrl: str
 declare const loadFederatedChunks: (root: string, config: DocBridgeConfigV1, options?: FederatedRetrieverOptions) => Promise<DocBridgeRetrievedChunk[]>;
 declare const retrieveHybridChunks: (root: string, config: DocBridgeConfigV1, index: DocBridgeIndexV1, query: string, options?: FederatedRetrieverOptions) => Promise<DocBridgeRetrievedChunk[]>;
 
-declare const PACKAGE_VERSION = "0.1.0-alpha.2";
+declare const PACKAGE_VERSION = "0.1.0-alpha.3";
 
 type FrontmatterValue = string | boolean | readonly string[];
 type FrontmatterData = Record<string, FrontmatterValue>;

package/dist/index.js

@@ -423,7 +423,9 @@ var KnowledgeEntrySchema = z3.object({
   type: z3.string().min(1).max(128),
   title: z3.string().min(1).max(256),
   path: z3.string().min(1).max(512),
-  description: z3.string().max(1024).optional(),
+  description: z3.string().max(2048).optional(),
+  /** Flattened body excerpt for full-text search (not for display). */
+  body: z3.string().max(8e3).optional(),
   links: z3.array(z3.string().min(1).max(512)).max(64).optional(),
   tags: z3.array(z3.string().min(1).max(64)).max(32).optional()
 }).strict();
@@ -628,7 +630,8 @@ var DocBridgeIndexV1JsonSchema = {
           type: { type: "string", minLength: 1, maxLength: 128 },
           title: { type: "string", minLength: 1, maxLength: 256 },
           path: { type: "string", minLength: 1, maxLength: 512 },
-          description: { type: "string", maxLength: 1024 },
+          description: { type: "string", maxLength: 2048 },
+          body: { type: "string", maxLength: 8e3 },
           links: stringArray(64),
           tags: stringArray(32)
         }
@@ -821,7 +824,7 @@ var firstHeading = (markdown) => {
   }
   return void 0;
 };
-var firstParagraph = (markdown) => {
+var firstParagraph = (markdown, maxLen = 400) => {
   const { body } = parseFrontmatter(markdown);
   const lines = body.split("\n");
   const buf = [];
@@ -833,11 +836,27 @@ var firstParagraph = (markdown) => {
     }
     if (t.startsWith("#")) continue;
     if (t.startsWith("---")) continue;
+    if (t.startsWith("```")) break;
+    if (t.startsWith("|") || t.startsWith("- [") || t.startsWith("* [")) {
+      if (buf.length) break;
+      continue;
+    }
     buf.push(t);
-    if (buf.join(" ").length > 40) break;
-  }
-  const text = buf.join(" ").trim();
-  return text || void 0;
+    if (buf.join(" ").length >= maxLen) break;
+  }
+  let text = buf.join(" ").replace(/\s+/g, " ").trim();
+  if (!text) return void 0;
+  if (text.length <= maxLen) return text;
+  const sliced = text.slice(0, maxLen);
+  const sentenceEnd = Math.max(sliced.lastIndexOf(". "), sliced.lastIndexOf("! "), sliced.lastIndexOf("? "));
+  if (sentenceEnd > maxLen * 0.4) return sliced.slice(0, sentenceEnd + 1).trim();
+  const wordEnd = sliced.lastIndexOf(" ");
+  return (wordEnd > 0 ? sliced.slice(0, wordEnd) : sliced).trim();
+};
+var extractSearchBody = (markdown, maxLen = 6e3) => {
+  const { body } = parseFrontmatter(markdown);
+  const text = body.replace(/```[\s\S]*?```/g, " ").replace(/!\[[^\]]*\]\([^)]+\)/g, " ").replace(/\[[^\]]*\]\([^)]+\)/g, " ").replace(/^#+\s+/gm, "").replace(/[|>*_`#]/g, " ").replace(/\s+/g, " ").trim();
+  return text.length > maxLen ? text.slice(0, maxLen) : text;
 };
 var slugFromPath = (relPath) => {
   const base = relPath.replace(/\.mdx?$/, "");
@@ -895,7 +914,9 @@ var scanAgentCorpus = (root, config) => {
     const { data: frontmatter } = parseFrontmatter(raw);
     const id = frontmatterString(frontmatter, "id") ?? frontmatterString(frontmatter, "package") ?? slugFromPath(relToCorpus);
     const title = firstHeading(raw) ?? id;
-    const description = firstParagraph(raw);
+    const purpose = frontmatterString(frontmatter, "purpose");
+    const description = purpose ?? firstParagraph(raw, 400);
+    const body = extractSearchBody(raw);
     return {
       id,
       type: "agent-doc",
@@ -904,7 +925,8 @@ var scanAgentCorpus = (root, config) => {
       absPath: abs,
       relPath,
       frontmatter,
-      ...description ? { description } : {}
+      ...description ? { description } : {},
+      ...body ? { body } : {}
     };
   });
 };
@@ -1037,11 +1059,19 @@ var resolveHumanDoc = (packageId, override, fmHuman, humanDocs = {}) => {
     packageId,
     packageId.replace(/^@[^/]+\//, ""),
     packageId.replace(/^os-/, ""),
-    packageId.replace(/-pattern$/, "")
+    packageId.replace(/-pattern$/, ""),
+    `packages/${packageId}`,
+    `reference/packages/${packageId}`,
+    `packages/${packageId}/index`
   ];
   for (const alias of aliases) {
     if (humanDocs[alias]) return humanDocs[alias];
   }
+  for (const [key, url] of Object.entries(humanDocs)) {
+    if (key === packageId || key.endsWith(`/${packageId}`) || key.endsWith(`/${packageId}/index`) || key.endsWith(`-${packageId}`)) {
+      return url;
+    }
+  }
   return void 0;
 };
 var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root = process.cwd()) => {
@@ -1127,7 +1157,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "0.1.0-alpha.2";
+var PACKAGE_VERSION = "0.1.0-alpha.3";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -1800,19 +1830,58 @@ import { relative, resolve as resolve4 } from "path";
 import { z as z5, ZodError } from "zod";
 
 // src/query/search.ts
-var tokenize = (value) => value.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2);
+var tokenize = (value) => value.toLowerCase().split(/[^a-z0-9@/_-]+/).filter((t) => t.length >= 2);
+var PACKAGE_INTENT = /\b(package|module|pkg|edit|change|where|owns?|ownership|handoff|start)\b/i;
+var scoreHay = (tokens, hay, weight = 1) => {
+  let score = 0;
+  for (const token of tokens) {
+    if (!hay.includes(token)) continue;
+    score += token.length * weight;
+    if (new RegExp(`(?:^|[^a-z0-9])${token}(?:[^a-z0-9]|$)`).test(hay)) {
+      score += token.length;
+    }
+  }
+  return score;
+};
+var identityBoost = (id, path, tokens, term) => {
+  const idLower = id.toLowerCase();
+  const termLower = term.toLowerCase().trim();
+  const base = path.split("/").pop()?.replace(/\.mdx?$/i, "").toLowerCase() ?? "";
+  let boost = 0;
+  if (idLower === termLower || base === termLower) boost += 200;
+  if (tokens.length === 1 && (idLower === tokens[0] || base === tokens[0])) boost += 200;
+  for (const token of tokens) {
+    if (idLower === token) boost += 120;
+    else if (idLower.startsWith(`${token}-`) || idLower.endsWith(`-${token}`)) boost += 40;
+    else if (idLower.includes(token) && idLower.length <= token.length + 4) boost += 30;
+    if (base === token) boost += 100;
+  }
+  if (tokens.includes(idLower)) boost += Math.max(0, 40 - idLower.length);
+  return boost;
+};
+var preferOwnership = (term) => PACKAGE_INTENT.test(term) || /^(where|how).*(edit|change|package|module)/i.test(term);
 var searchIndex = (index, term, limit = 20) => {
   const tokens = tokenize(term);
   if (!tokens.length) return [];
-  const matches = [];
-  for (const entry of index.knowledge) {
-    const hay = `${entry.id} ${entry.title} ${entry.description ?? ""} ${entry.path}`.toLowerCase();
-    let score = 0;
-    for (const token of tokens) {
-      if (hay.includes(token)) score += token.length;
+  const wantOwnership = preferOwnership(term);
+  const byPath = /* @__PURE__ */ new Map();
+  const consider = (match) => {
+    const key = match.path;
+    const existing = byPath.get(key);
+    if (!existing) {
+      byPath.set(key, match);
+      return;
     }
+    const prefer = match.score > existing.score || match.score === existing.score && match.type === "ownership" && existing.type !== "ownership" || wantOwnership && match.type === "ownership" && existing.type !== "ownership" && match.score >= existing.score - 20;
+    if (prefer) byPath.set(key, match);
+  };
+  for (const entry of index.knowledge) {
+    const body = entry.body ?? "";
+    const hay = `${entry.id} ${entry.title} ${entry.description ?? ""} ${entry.path} ${body}`.toLowerCase();
+    let score = scoreHay(tokens, hay, 1);
+    score += identityBoost(entry.id, entry.path, tokens, term);
     if (score > 0) {
-      matches.push({
+      consider({
         type: "knowledge",
         id: entry.id,
         path: entry.path,
@@ -1822,22 +1891,31 @@ var searchIndex = (index, term, limit = 20) => {
     }
   }
   for (const [id, owner] of Object.entries(index.lookup?.ownership ?? {})) {
-    const hay = `${id} ${owner.path} ${owner.purpose ?? ""} ${owner.group ?? ""}`.toLowerCase();
-    let score = 0;
-    for (const token of tokens) {
-      if (hay.includes(token)) score += token.length * 2;
-    }
+    const path = owner.agentDoc ?? owner.path;
+    const hay = `${id} ${owner.path} ${owner.purpose ?? ""} ${owner.group ?? ""} ${owner.agentDoc ?? ""} ${owner.humanDoc ?? ""}`.toLowerCase();
+    let score = scoreHay(tokens, hay, 2);
+    score += identityBoost(id, path, tokens, term);
+    if (wantOwnership) score += 25;
+    score += 15;
     if (score > 0) {
-      matches.push({
+      consider({
         type: "ownership",
         id,
-        path: owner.agentDoc ?? owner.path,
+        path,
         ...owner.purpose ? { summary: owner.purpose } : {},
         score
       });
     }
   }
-  return matches.sort((a, b) => b.score - a.score).slice(0, limit);
+  return [...byPath.values()].sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    const aExact = tokens.includes(a.id.toLowerCase()) ? 1 : 0;
+    const bExact = tokens.includes(b.id.toLowerCase()) ? 1 : 0;
+    if (bExact !== aExact) return bExact - aExact;
+    if (a.type === "ownership" && b.type !== "ownership") return -1;
+    if (b.type === "ownership" && a.type !== "ownership") return 1;
+    return a.id.localeCompare(b.id);
+  }).slice(0, limit);
 };
 
 // src/retriever/doc-bridge-retriever.ts
@@ -2315,10 +2393,14 @@ var defaultFetchText = async (url) => {
   return res.text();
 };
 var sourceText = async (root, source, fetchText) => {
-  if (/^https?:\/\//.test(source)) return fetchText(source);
-  const path = resolve5(root, source);
-  if (!existsSync9(path)) throw new Error(`Federation source not found: ${source}`);
-  return readFileSync13(path, "utf8");
+  try {
+    if (/^https?:\/\//.test(source)) return await fetchText(source);
+    const path = resolve5(root, source);
+    if (!existsSync9(path)) return null;
+    return readFileSync13(path, "utf8");
+  } catch {
+    return null;
+  }
 };
 var sameOrigin = (base, target) => {
   if (!/^https?:\/\//.test(base) || !/^https?:\/\//.test(target)) return true;
@@ -2357,22 +2439,28 @@ var chunksFromMarkdown = (property, raw, sourceUrl) => {
 var loadFederatedChunks = async (root, config, options = {}) => {
   const fetchText = options.fetchText ?? defaultFetchText;
   const chunks = [];
+  const warnings = [];
   for (const source of config.federation?.sources ?? []) {
     if (source.includeInRetriever === false || !source.llmsTxt) continue;
     const llms = await sourceText(root, source.llmsTxt, fetchText);
+    if (!llms) {
+      warnings.push(`federation source skipped (unavailable): ${source.id} \u2192 ${source.llmsTxt}`);
+      continue;
+    }
     chunks.push(...chunksFromMarkdown(source.id, llms, source.llmsTxt));
     const links = parseLlmsTxtLinks(llms);
     for (const link of links) {
       const url = !/^https?:\/\//.test(link.url) && source.rawBaseUrl ? `${source.rawBaseUrl.replace(/\/$/, "")}/${link.url.replace(/^\//, "")}` : link.url;
       if (!/\.(md|txt)(?:$|\?)/.test(url)) continue;
       if (!sameOrigin(source.llmsTxt, url)) continue;
-      try {
-        const raw = await sourceText(root, url, fetchText);
-        chunks.push(...chunksFromMarkdown(source.id, raw, url));
-      } catch {
-      }
+      const raw = await sourceText(root, url, fetchText);
+      if (raw) chunks.push(...chunksFromMarkdown(source.id, raw, url));
     }
   }
+  if (warnings.length && process.stderr.isTTY) {
+    for (const w of warnings) process.stderr.write(`${w}
+`);
+  }
   return chunks;
 };
 var retrieveHybridChunks = async (root, config, index, query, options = {}) => {