simple-dynamsoft-mcp 7.6.1 → 7.7.1

package/src/server/resource-index/shared-docs.js

@@ -0,0 +1,161 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { resolveSiteLinks } from "./docs-loader.js";
+
+// DBR's public API is built on shared Capture Vision (DCV) modules such as
+// CaptureVisionRouter, whose reference pages live only in the DCV docs. DBR's
+// own docs and navigation sidebars link to exactly the DCV pages DBR relies on,
+// so those links are the dependency map: only linked pages are indexed under
+// DBR, never the whole DCV corpus.
+
+const DCV_CURRENT_DOCS_PREFIX = "https://www.dynamsoft.com/capture-vision/docs/";
+
+// Sidebar include `sidelist-programming/programming-<segment>.html` scopes its
+// links to one DBR platform; other includes apply to the whole edition.
+const SIDEBAR_PLATFORM_BY_SEGMENT = {
+  javascript: "web",
+  android: "android",
+  oc: "ios",
+  ios: "ios",
+  flutter: "flutter",
+  maui: "maui",
+  "react-native": "react-native",
+  cpp: "cpp",
+  dotnet: "dotnet",
+  java: "java",
+  python: "python",
+  nodejs: "nodejs"
+};
+
+function normalizeDocUrl(url) {
+  // Some DBR links contain `//` inside the path (e.g. `api-reference//core/`).
+  let normalized = String(url || "").split("#")[0].split("?")[0].replace(/([^:])\/{2,}/g, "$1/");
+  if (!normalized) return "";
+  if (normalized.endsWith("/")) return `${normalized}index.html`;
+  const lastSegment = normalized.slice(normalized.lastIndexOf("/") + 1);
+  if (!lastSegment.includes(".")) normalized = `${normalized}.html`;
+  return normalized;
+}
+
+function extractDcvLinks(text) {
+  const links = new Set();
+  const pattern = /https:\/\/www\.dynamsoft\.com\/capture-vision\/docs\/[^\s)"'<>\]`]+/g;
+  for (const match of String(text || "").matchAll(pattern)) {
+    const normalized = normalizeDocUrl(match[0]);
+    if (normalized.startsWith(DCV_CURRENT_DOCS_PREFIX)) links.add(normalized);
+  }
+  return links;
+}
+
+function listIncludeFiles(dir) {
+  const files = [];
+  if (!existsSync(dir)) return files;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listIncludeFiles(fullPath));
+    } else if (/\.(html|md)$/i.test(entry.name)) {
+      files.push({ path: fullPath, name: entry.name });
+    }
+  }
+  return files;
+}
+
+function sidebarPlatform(fileName) {
+  const match = String(fileName).match(/^programming-(.+)\.html$/i);
+  return match ? SIDEBAR_PLATFORM_BY_SEGMENT[match[1].toLowerCase()] || "" : "";
+}
+
+// url -> Set of DBR platforms whose docs link to it ("*" = whole edition).
+function buildDcvLinkMap({ dbrArticles, dbrRoot, siteVars }) {
+  const linkMap = new Map();
+  const addLinks = (links, platform) => {
+    for (const url of links) {
+      if (!linkMap.has(url)) linkMap.set(url, new Set());
+      linkMap.get(url).add(platform);
+    }
+  };
+
+  for (const article of dbrArticles || []) {
+    addLinks(extractDcvLinks(article.content), article.platform || "*");
+  }
+  for (const file of listIncludeFiles(join(dbrRoot || "", "_includes"))) {
+    const text = resolveSiteLinks(readFileSync(file.path, "utf8"), siteVars);
+    addLinks(extractDcvLinks(text), sidebarPlatform(file.name) || "*");
+  }
+  return linkMap;
+}
+
+function parseVersionParts(version) {
+  return String(version || "").split(".").map((part) => Number.parseInt(part, 10));
+}
+
+// DBR and DCV ship in lockstep: 11.6.3200 pairs with 3.6.3200. Edition pages
+// must match minor and build; core reference pages are edition-neutral and
+// only need the same minor.
+function isCompatibleSharedVersion(dbrVersion, dcvVersion, { requireBuild }) {
+  const [, dbrMinor, dbrBuild] = parseVersionParts(dbrVersion);
+  const [, dcvMinor, dcvBuild] = parseVersionParts(dcvVersion);
+  if (!Number.isFinite(dbrMinor) || dbrMinor !== dcvMinor) return false;
+  if (requireBuild && dbrBuild !== dcvBuild) return false;
+  return true;
+}
+
+/**
+ * Select DCV pages linked from one DBR edition.
+ *
+ * @param {object} options
+ * @param {Array} options.dbrArticles DBR edition articles (with platform).
+ * @param {string} options.dbrRoot DBR docs repo root (for `_includes`).
+ * @param {Map} options.siteVars DBR repo `{{ site.* }}` variables.
+ * @param {string} options.dbrVersion DBR edition version.
+ * @param {Array<{articles: Array, version: string, editionSpecific: boolean, slugPrefix: string}>} options.sources
+ * @param {Function} [options.onSkip] Called with details when a source is version-incompatible.
+ * @returns {Array} Articles with `slugPrefix` (doc:// namespace), `platform`, `platforms`, `sourceVersion`.
+ */
+function selectSharedDcvDocs({ dbrArticles, dbrRoot, siteVars, dbrVersion, sources, onSkip }) {
+  const linkMap = buildDcvLinkMap({ dbrArticles, dbrRoot, siteVars });
+  const editionPlatforms = [...new Set((dbrArticles || []).map((article) => article.platform).filter(Boolean))].sort();
+  const selected = [];
+
+  for (const source of sources) {
+    if (!isCompatibleSharedVersion(dbrVersion, source.version, { requireBuild: source.editionSpecific })) {
+      onSkip?.({ dbrVersion, dcvVersion: source.version, slugPrefix: source.slugPrefix });
+      continue;
+    }
+    for (const article of source.articles || []) {
+      const linkedFrom = linkMap.get(normalizeDocUrl(article.url));
+      if (!linkedFrom) continue;
+
+      let platforms;
+      if (source.editionSpecific) {
+        // An edition page belongs to one platform (its programming/<lang>/ dir).
+        if (!editionPlatforms.includes(article.platform) && editionPlatforms.length > 0) continue;
+        platforms = [article.platform];
+      } else {
+        platforms = linkedFrom.has("*")
+          ? editionPlatforms
+          : [...linkedFrom].filter((platform) => editionPlatforms.includes(platform)).sort();
+      }
+      if (platforms.length === 0) continue;
+
+      selected.push({
+        ...article,
+        slugPrefix: source.slugPrefix,
+        platform: platforms.length === 1 ? platforms[0] : (source.defaultPlatform || platforms[0]),
+        platforms,
+        sourceVersion: source.version
+      });
+    }
+  }
+
+  return selected;
+}
+
+export {
+  buildDcvLinkMap,
+  extractDcvLinks,
+  isCompatibleSharedVersion,
+  normalizeDocUrl,
+  selectSharedDcvDocs
+};

package/src/server/resource-index.js

@@ -17,6 +17,8 @@ import {
 } from "./normalizers.js";
 import { DOCS_CONFIG } from "./resource-index/config.js";
 import { loadMarkdownDocs } from "./resource-index/docs-loader.js";
+import { selectSharedDcvDocs } from "./resource-index/shared-docs.js";
+import { logEvent } from "../observability/logging.js";
 import {
   registryPath,
   DOC_ROOTS,
@@ -149,40 +151,47 @@ let dcvMobileDocs = [];
 let dcvServerDocs = [];
 let dwtDocs = { articles: [] };
 let ddvDocs = { articles: [] };
+let dbrSharedDocs = { web: [], mobile: [], server: [] };
+
+function loadDbrDocs(key, edition, platformResolver) {
+  const loaded = loadMarkdownDocs({
+    rootDir: DOC_ROOTS[key],
+    urlBase: DOCS_CONFIG[key].urlBase,
+    excludeDirs: DOCS_CONFIG[key].excludeDirs,
+    excludeFiles: DOCS_CONFIG[key].excludeFiles
+  });
+  return { articles: withEditionScope(loaded.articles, edition, platformResolver), siteVars: loaded.siteVars };
+}
+
+function selectDbrSharedDocs(key, edition, dbr, dcvEditionDocs) {
+  const dbrVersion = LATEST_VERSIONS.dbr[edition];
+  return selectSharedDcvDocs({
+    dbrArticles: dbr.articles,
+    dbrRoot: DOC_ROOTS[key],
+    siteVars: dbr.siteVars,
+    dbrVersion,
+    sources: [
+      { articles: dcvEditionDocs, version: LATEST_VERSIONS.dcv[edition], editionSpecific: true, slugPrefix: "dcv", defaultPlatform: edition },
+      { articles: dcvCoreDocs, version: LATEST_VERSIONS.dcv.core, editionSpecific: false, slugPrefix: "dcv-core", defaultPlatform: edition }
+    ],
+    onSkip: ({ dcvVersion, slugPrefix }) => logEvent("data", "shared_docs_version_mismatch", {
+      edition,
+      dbr_version: dbrVersion,
+      dcv_version: dcvVersion,
+      source: slugPrefix
+    }, { level: "warn" })
+  });
+}
 
 function loadDocumentationSets() {
-  dbrWebDocs = withEditionScope(
-    loadMarkdownDocs({
-      rootDir: DOC_ROOTS.dbrWeb,
-      urlBase: DOCS_CONFIG.dbrWeb.urlBase,
-      excludeDirs: DOCS_CONFIG.dbrWeb.excludeDirs,
-      excludeFiles: DOCS_CONFIG.dbrWeb.excludeFiles
-    }).articles,
-    "web",
-    () => "web"
-  );
+  const dbrWeb = loadDbrDocs("dbrWeb", "web", () => "web");
+  dbrWebDocs = dbrWeb.articles;
 
-  dbrMobileDocs = withEditionScope(
-    loadMarkdownDocs({
-      rootDir: DOC_ROOTS.dbrMobile,
-      urlBase: DOCS_CONFIG.dbrMobile.urlBase,
-      excludeDirs: DOCS_CONFIG.dbrMobile.excludeDirs,
-      excludeFiles: DOCS_CONFIG.dbrMobile.excludeFiles
-    }).articles,
-    "mobile",
-    inferDbrMobilePlatform
-  );
+  const dbrMobile = loadDbrDocs("dbrMobile", "mobile", inferDbrMobilePlatform);
+  dbrMobileDocs = dbrMobile.articles;
 
-  dbrServerDocs = withEditionScope(
-    loadMarkdownDocs({
-      rootDir: DOC_ROOTS.dbrServer,
-      urlBase: DOCS_CONFIG.dbrServer.urlBase,
-      excludeDirs: DOCS_CONFIG.dbrServer.excludeDirs,
-      excludeFiles: DOCS_CONFIG.dbrServer.excludeFiles
-    }).articles,
-    "server",
-    inferDbrServerPlatform
-  );
+  const dbrServer = loadDbrDocs("dbrServer", "server", inferDbrServerPlatform);
+  dbrServerDocs = dbrServer.articles;
 
   dcvCoreDocs = withEditionScope(
     loadMarkdownDocs({
@@ -252,6 +261,7 @@ function loadDocumentationSets() {
 
   dwtDocs = loadMarkdownDocs({
     rootDir: DOC_ROOTS.dwtArticles,
+    siteRoot: DOC_ROOTS.dwt,
     urlBase: DOCS_CONFIG.dwt.urlBase,
     includeDirNames: DOCS_CONFIG.dwt.includeDirNames
   });
@@ -262,6 +272,12 @@ function loadDocumentationSets() {
     excludeDirs: DOCS_CONFIG.ddv.excludeDirs,
     excludeFiles: DOCS_CONFIG.ddv.excludeFiles
   });
+
+  dbrSharedDocs = {
+    web: selectDbrSharedDocs("dbrWeb", "web", dbrWeb, dcvWebDocs),
+    mobile: selectDbrSharedDocs("dbrMobile", "mobile", dbrMobile, dcvMobileDocs),
+    server: selectDbrSharedDocs("dbrServer", "server", dbrServer, dcvServerDocs)
+  };
 }
 
 const dbrServerSdk = registry.sdks["dbr-server"];
@@ -339,6 +355,7 @@ function buildIndexData() {
     dbrWebDocs,
     dbrMobileDocs,
     dbrServerDocs,
+    dbrSharedDocs,
     dwtDocs,
     ddvDocs,
     discoverDcvWebSamples,
@@ -380,6 +397,7 @@ function buildResourceIndex() {
     dbrWebDocs,
     dbrMobileDocs,
     dbrServerDocs,
+    dbrSharedDocs,
     dwtDocs,
     ddvDocs,
     discoverDcvMobileSamples,
@@ -444,6 +462,8 @@ function editionMatches(normalizedEdition, entryEdition) {
 function platformMatches(normalizedPlatform, entry) {
   if (!normalizedPlatform) return true;
   if (normalizedPlatform === entry.platform) return true;
+  // Shared pages (e.g. Capture Vision core reference) serve several platforms.
+  if (Array.isArray(entry.platforms) && entry.platforms.includes(normalizedPlatform)) return true;
   if (normalizedPlatform === "web") return entry.platform === "web";
   if (isWebFrameworkPlatform(normalizedPlatform)) {
     const aliases = WEB_FRAMEWORK_TAG_ALIASES[normalizedPlatform] || [normalizedPlatform];
@@ -514,13 +534,12 @@ function buildResourceLookupCandidates(uri) {
   const parts = String(rest || "").split("/").filter(Boolean);
   if (parts.length < 5) return candidates;
 
-  const head = parts.slice(0, 4);
-  const slugRaw = parts.slice(4).join("/");
-  const decodedOnce = safeDecodeURIComponent(slugRaw);
-  const decodedTwice = safeDecodeURIComponent(decodedOnce);
-
-  for (const slug of [decodedOnce, decodedTwice]) {
-    const canonical = `${scheme}://${head.join("/")}/${encodeURIComponent(slug)}`;
+  // Doc slugs are source paths; accept them with or without per-segment
+  // percent-encoding (clients differ in how they echo URIs back).
+  const head = parts.slice(0, 4).join("/");
+  const slugSegments = parts.slice(4).map((segment) => safeDecodeURIComponent(segment));
+  for (const slug of [slugSegments.join("/"), slugSegments.map((segment) => encodeURIComponent(segment)).join("/")]) {
+    const canonical = `${scheme}://${head}/${slug}`;
     if (!candidates.includes(canonical)) {
       candidates.push(canonical);
     }
@@ -562,6 +581,7 @@ function getRagSignatureData() {
     dbrWebDocCount: dbrWebDocs.length,
     dbrMobileDocCount: dbrMobileDocs.length,
     dbrServerDocCount: dbrServerDocs.length,
+    dbrSharedDocCount: dbrSharedDocs.web.length + dbrSharedDocs.mobile.length + dbrSharedDocs.server.length,
     dwtDocCount: dwtDocs.articles.length,
     ddvDocCount: ddvDocs.articles.length,
     versions: LATEST_VERSIONS,

package/src/server/tools/register-index-tools.js

@@ -34,7 +34,10 @@ export function registerIndexTools({
     const sampleId = entry.type === "sample" ? getSampleIdFromUri(entry.uri) : "";
     const sampleHint = sampleId ? ` | sample_id: ${sampleId}` : "";
     const scoreLabel = formatScoreLabel(entry);
-    let desc = `${entry.type.toUpperCase()} | ${scopeLabel} | ${versionLabel}${scoreLabel} - ${entry.summary}${sampleHint}`;
+    const sharedLabel = entry.type === "doc" && Array.isArray(entry.tags) && entry.tags.includes("shared")
+      ? ` | shared Capture Vision API used by DBR (DCV v${entry.sourceVersion || "n/a"})`
+      : "";
+    let desc = `${entry.type.toUpperCase()} | ${scopeLabel} | ${versionLabel}${sharedLabel}${scoreLabel} - ${entry.summary}${sampleHint}`;
     if (entry.matchedSnippet) {
       const snippet = String(entry.matchedSnippet).replace(/\s+/g, " ").slice(0, 220);
       desc += ` — "${snippet}"`;