@contractspec/bundle.library 3.8.2 → 3.8.5

package/dist/application/mcp/docsMcp.data.js

@@ -0,0 +1,148 @@
+// @bun
+// src/application/mcp/docsMcp.data.ts
+import { defaultDocRegistry } from "@contractspec/lib.contracts-spec/docs";
+var DEFAULT_LIMIT = 20;
+var MAX_LIMIT = 100;
+function normalizeText(value) {
+  return value?.trim().toLowerCase() ?? "";
+}
+function normalizeRoute(route) {
+  const decoded = decodeURIComponent(route).trim();
+  if (!decoded)
+    return "/";
+  return decoded.startsWith("/") ? decoded : `/${decoded}`;
+}
+function normalizeTags(value) {
+  const tags = Array.isArray(value) ? value : value ? [value] : [];
+  return tags.map((tag) => normalizeText(tag)).filter(Boolean);
+}
+function clampLimit(limit) {
+  if (!limit || Number.isNaN(limit))
+    return DEFAULT_LIMIT;
+  return Math.min(Math.max(limit, 1), MAX_LIMIT);
+}
+function clampOffset(offset) {
+  if (!offset || Number.isNaN(offset))
+    return 0;
+  return Math.max(offset, 0);
+}
+function toDocSummary({ block, route }) {
+  return {
+    id: block.id,
+    title: block.title,
+    summary: block.summary ?? "",
+    route,
+    visibility: block.visibility ?? "public",
+    kind: block.kind ?? "reference",
+    version: block.version ?? "1.0.0",
+    tags: block.tags ?? []
+  };
+}
+function scoreDoc(route, query) {
+  if (!query)
+    return 1;
+  const tokens = query.split(/\s+/).filter(Boolean);
+  const title = normalizeText(route.block.title);
+  const id = normalizeText(route.block.id);
+  const summary = normalizeText(route.block.summary);
+  const body = normalizeText(route.block.body);
+  const path = normalizeText(route.route);
+  const tags = (route.block.tags ?? []).map((tag) => normalizeText(tag));
+  const haystack = [title, id, summary, body, path, ...tags].join(" ");
+  if (tokens.some((token) => !haystack.includes(token)))
+    return 0;
+  let score = 0;
+  for (const token of tokens) {
+    if (id.includes(token))
+      score += 8;
+    if (title.includes(token))
+      score += 7;
+    if (tags.some((tag) => tag.includes(token)))
+      score += 5;
+    if (summary.includes(token))
+      score += 4;
+    if (path.includes(token))
+      score += 3;
+    if (body.includes(token))
+      score += 2;
+  }
+  return score;
+}
+function searchDocs(routes, args) {
+  const query = normalizeText(typeof args.query === "string" ? args.query : undefined);
+  const tags = normalizeTags(args.tag);
+  const visibility = normalizeText(typeof args.visibility === "string" ? args.visibility : undefined);
+  const kind = normalizeText(typeof args.kind === "string" ? args.kind : undefined);
+  const limit = clampLimit(typeof args.limit === "number" ? args.limit : undefined);
+  const offset = clampOffset(typeof args.offset === "number" ? args.offset : undefined);
+  const ranked = routes.map((route) => ({
+    doc: toDocSummary(route),
+    score: scoreDoc(route, query)
+  })).filter(({ doc, score }) => {
+    const matchesQuery = query ? score > 0 : true;
+    const matchesTags = tags.length ? tags.every((tag) => doc.tags.some((docTag) => normalizeText(docTag).includes(tag))) : true;
+    const matchesVisibility = visibility ? normalizeText(doc.visibility) === visibility : true;
+    const matchesKind = kind ? normalizeText(doc.kind) === kind : true;
+    return matchesQuery && matchesTags && matchesVisibility && matchesKind;
+  }).sort((left, right) => {
+    if (right.score !== left.score)
+      return right.score - left.score;
+    return left.doc.title.localeCompare(right.doc.title);
+  });
+  const docs = ranked.slice(offset, offset + limit).map(({ doc }) => doc);
+  const nextOffset = offset + docs.length < ranked.length ? offset + docs.length : undefined;
+  return {
+    docs,
+    items: docs,
+    total: ranked.length,
+    ...nextOffset != null ? { nextOffset } : {}
+  };
+}
+function getDocById(id) {
+  const normalizedId = decodeURIComponent(id);
+  const found = defaultDocRegistry.get(normalizedId);
+  if (!found)
+    return;
+  return {
+    doc: toDocSummary(found),
+    content: String(found.block.body ?? "")
+  };
+}
+function getDocByRoute(routes, routePath) {
+  const normalizedPath = normalizeRoute(routePath);
+  const found = routes.find((route) => normalizeRoute(route.route) === normalizedPath);
+  if (!found)
+    return;
+  return {
+    doc: toDocSummary(found),
+    content: String(found.block.body ?? "")
+  };
+}
+function listDocFacets(routes) {
+  const tags = new Map;
+  const kinds = new Map;
+  const visibilities = new Map;
+  for (const route of routes) {
+    const kind = route.block.kind ?? "reference";
+    const visibility = route.block.visibility ?? "public";
+    kinds.set(kind, (kinds.get(kind) ?? 0) + 1);
+    visibilities.set(visibility, (visibilities.get(visibility) ?? 0) + 1);
+    for (const tag of route.block.tags ?? []) {
+      tags.set(tag, (tags.get(tag) ?? 0) + 1);
+    }
+  }
+  const toEntries = (values, key) => [...values.entries()].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).map(([value, count]) => ({ [key]: value, count }));
+  return {
+    totalDocs: routes.length,
+    tags: toEntries(tags, "tag"),
+    kinds: toEntries(kinds, "kind"),
+    visibilities: toEntries(visibilities, "visibility")
+  };
+}
+export {
+  toDocSummary,
+  searchDocs,
+  listDocFacets,
+  getDocByRoute,
+  getDocById
+};