@lupinum/ginko-content 0.1.1 → 0.1.3

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
-import { readFile, readdir, stat } from 'node:fs/promises';
+import { stat, readFile, readdir } from 'node:fs/promises';
 import { join, extname, relative } from 'node:path';
 
 const ignoredDirs = /* @__PURE__ */ new Set([
@@ -27,78 +27,124 @@ const sourceExtensions = /* @__PURE__ */ new Set([
   ".yml",
   ".yaml"
 ]);
-const stalePackageNames = ["@nuxt/content", "better-sqlite3", "@standard-schema/spec"];
-const sourceChecks = [
-  {
-    pattern: /from\s+['"]@nuxt\/content(?:\/[^'"]*)?['"]|import\s*\([^)]*['"]@nuxt\/content(?:\/[^'"]*)?['"][^)]*\)/,
-    message: "Direct Nuxt Content import found.",
-    suggestion: "Import Ginko helpers from @lupinum/ginko-content/config, /client, or /server."
-  },
-  {
-    pattern: /['"]@nuxt\/content['"]/,
-    message: "Nuxt Content module or package reference found.",
-    suggestion: "Remove @nuxt/content from Nuxt modules and use @lupinum/ginko-content."
-  },
-  {
-    pattern: /\bqueryCollectionItemSurroundings\s*\(/,
-    message: "Nuxt Content v3 surround helper found.",
-    suggestion: "Use useContentNeighbors(handle, { by: { route } }) in route page components."
-  },
-  {
-    pattern: /\bqueryCollectionSearchSections\s*\(/,
-    message: "Nuxt Content v3 search sections helper found.",
-    suggestion: "Use useContentSearchData(collection) for UI search data."
-  },
-  {
-    pattern: /\bqueryCollectionNavigation\s*\(/,
-    message: "Nuxt Content v3 navigation helper found.",
-    suggestion: "Use useContentTree(handle) for layout navigation."
-  },
-  {
-    pattern: /\bqueryCollection\s*\(/,
-    message: "Removed collection query helper found.",
-    suggestion: "Use one(handle, options), many(handle, options), paginate(handle, options), or the matching useContent* composable."
-  },
-  {
-    pattern: /\buseContentList\s*\(/,
-    message: "Removed content list composable found.",
-    suggestion: "Use useContentMany(handle, options) or many(handle, options)."
-  },
-  {
-    pattern: /\buseContentNavigation\s*\(/,
-    message: "Removed content navigation composable found.",
-    suggestion: "Use useContentTree(handle) for layout navigation."
-  },
-  {
-    pattern: /\bcontent\.(database|preview|build)\b/,
-    message: "Nuxt Content v3 runtime config key found.",
-    suggestion: "Remove content.database/content.preview/content.build and configure Ginko runtime options instead."
-  },
-  {
-    pattern: /\.editor\s*\(/,
-    message: "Nuxt Studio Zod .editor(...) helper found.",
-    suggestion: "Remove .editor(...) from runtime Zod schemas or move editor metadata outside the schema."
-  },
-  {
-    pattern: /<ContentRenderer\b[^>]*:value\s*=\s*["'][^"']*\.body["']/,
-    message: "ContentRenderer is receiving a document body.",
-    suggestion: "Pass the full content document to ContentRenderer, not document.body."
-  },
-  {
-    pattern: /<NuxtLink\b[^>]*:to\s*=\s*["'][^"']+\.path["']/,
-    message: "NuxtLink may be using raw query .path.",
-    suggestion: "Use useContentMany(handle, options) for route-safe list items, or link route-page payloads with their explicit path field."
-  },
-  {
-    pattern: /<NuxtLink\b[^>]*:to\s*=\s*["'][^"']+\._path["']/,
-    message: "NuxtLink is using raw content _path.",
-    suggestion: "Use useContentMany(handle, options) for list pages and bind the route-safe item.path field."
-  }
-];
-const lockfileNames = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"];
-const localeCodePattern = /^[a-z]{2}(?:-[A-Z]{2})?$/;
 const toRelativePath = (rootDir, file) => relative(rootDir, file) || ".";
+async function collectFiles(dir, rootDir, files = []) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!ignoredDirs.has(entry.name)) {
+        await collectFiles(absolutePath, rootDir, files);
+      }
+      continue;
+    }
+    if (entry.isFile() && sourceExtensions.has(extname(entry.name))) {
+      files.push(absolutePath);
+    }
+  }
+  return files;
+}
+async function collectOutputFiles(dir, rootDir, files = []) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== "_nuxt") {
+        await collectOutputFiles(absolutePath, rootDir, files);
+      }
+      continue;
+    }
+    if (entry.isFile() && [".html", ".json", ".xml"].includes(extname(entry.name))) {
+      files.push(absolutePath);
+    }
+  }
+  return files;
+}
+async function readTextIfPresent(path) {
+  if (!existsSync(path)) {
+    return "";
+  }
+  const fileStat = await stat(path);
+  if (!fileStat.isFile()) {
+    return "";
+  }
+  return readFile(path, "utf8");
+}
+async function readPackageJson(rootDir) {
+  const path = join(rootDir, "package.json");
+  if (!existsSync(path)) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function hasDependency(packageJson, packageName) {
+  if (!packageJson) {
+    return false;
+  }
+  return ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"].some((blockName) => {
+    const block = packageJson[blockName];
+    return !!block && typeof block === "object" && packageName in block;
+  });
+}
+
 const countSitemapUrls = (text) => (text.match(/<url>/g) || []).length;
+async function readGeneratedSitemaps(rootDir) {
+  const outputPublicDir = join(rootDir, ".output/public");
+  if (!existsSync(outputPublicDir)) {
+    return [];
+  }
+  const sitemapPaths = [
+    join(outputPublicDir, "sitemap.xml"),
+    join(outputPublicDir, "sitemap_index.xml")
+  ];
+  const sitemapDir = join(outputPublicDir, "__sitemap__");
+  if (existsSync(sitemapDir)) {
+    const entries = await readdir(sitemapDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(".xml")) {
+        sitemapPaths.push(join(sitemapDir, entry.name));
+      }
+    }
+  }
+  const sitemapFiles = [];
+  for (const sitemapPath of sitemapPaths) {
+    if (!existsSync(sitemapPath)) {
+      continue;
+    }
+    const fileStat = await stat(sitemapPath);
+    if (fileStat.isFile()) {
+      sitemapFiles.push({
+        file: toRelativePath(rootDir, sitemapPath),
+        text: await readFile(sitemapPath, "utf8")
+      });
+    }
+  }
+  return sitemapFiles;
+}
+async function inspectSitemap(rootDir) {
+  const sitemapFiles = await readGeneratedSitemaps(rootDir);
+  const sitemapTexts = sitemapFiles.map((file) => file.text);
+  if (!sitemapTexts.length) {
+    return [];
+  }
+  const urlCount = sitemapTexts.reduce((total, text) => total + countSitemapUrls(text), 0);
+  const hasSitemapIndex = sitemapTexts.some((text) => /<sitemapindex\b/.test(text));
+  if (urlCount > 0 || hasSitemapIndex) {
+    return [];
+  }
+  return [{
+    severity: "error",
+    file: ".output/public/sitemap.xml",
+    message: "Generated sitemap contains no <url> entries.",
+    suggestion: "Enable content.sitemap, configure site.url, and verify public route collections are sitemap-backed."
+  }];
+}
+
+const localeCodePattern = /^[a-z]{2}(?:-[A-Z]{2})?$/;
 function findMatchingBrace(text, start) {
   let depth = 0;
   let quote;
@@ -156,191 +202,90 @@ function findMatchingBrace(text, start) {
   }
   return text.length - 1;
 }
-function findCollectionDefinitions(text) {
-  const definitions = [];
+function findAuthoredCollectionDefinitions(text) {
+  const definitions = /* @__PURE__ */ new Map();
   const callPattern = /\bdefineCollection\s*\(/g;
   for (const match of text.matchAll(callPattern)) {
     const callStart = match.index || 0;
     const argsStart = callStart + match[0].length;
     const args = text.slice(argsStart);
-    const namedMatch = args.match(/^\s*(['"])([^'"]+)\1\s*,\s*\{/);
-    if (namedMatch) {
-      const bodyStart = argsStart + namedMatch[0].lastIndexOf("{");
-      const bodyEnd = findMatchingBrace(text, bodyStart);
-      definitions.push({
-        name: namedMatch[2],
-        block: text.slice(bodyStart, bodyEnd + 1)
-      });
+    const objectMatch = args.match(/^\s*\{/);
+    if (!objectMatch) {
       continue;
     }
-    const objectMatch = args.match(/^\s*\{/);
-    const propertyMatch = text.slice(0, callStart).match(/([a-z_$][\w$]*)\s*:\s*$/i);
-    if (objectMatch && propertyMatch) {
-      const bodyStart = argsStart + objectMatch[0].lastIndexOf("{");
-      const bodyEnd = findMatchingBrace(text, bodyStart);
-      definitions.push({
-        name: propertyMatch[1],
-        block: text.slice(bodyStart, bodyEnd + 1)
+    const bodyStart = argsStart + objectMatch[0].lastIndexOf("{");
+    const bodyEnd = findMatchingBrace(text, bodyStart);
+    const block = text.slice(bodyStart, bodyEnd + 1);
+    const prefix = text.slice(0, callStart);
+    const propertyMatch = prefix.match(/([a-z_$][\w$]*)\s*:\s*$/i);
+    if (propertyMatch) {
+      definitions.set(propertyMatch[1], {
+        key: propertyMatch[1],
+        block
       });
-    }
-  }
-  return definitions;
-}
-async function collectFiles(dir, rootDir, files = []) {
-  const entries = await readdir(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    const absolutePath = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (!ignoredDirs.has(entry.name)) {
-        await collectFiles(absolutePath, rootDir, files);
-      }
       continue;
     }
-    if (entry.isFile() && sourceExtensions.has(extname(entry.name))) {
-      files.push(absolutePath);
+    const variableMatch = prefix.match(/(?:^|[\s;])(?:export\s+)?(?:const|let|var)\s+([a-z_$][\w$]*)\s*=\s*$/i);
+    if (variableMatch) {
+      definitions.set(variableMatch[1], { block });
     }
   }
-  return files;
+  return definitions;
 }
-function packageDependencyFindings(rootDir, packageJson) {
-  const dependencyBlocks = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
-  const findings = [];
-  for (const blockName of dependencyBlocks) {
-    const block = packageJson[blockName];
-    if (!block || typeof block !== "object") {
-      continue;
-    }
-    for (const packageName of stalePackageNames) {
-      if (packageName in block) {
-        findings.push({
-          severity: "error",
-          file: toRelativePath(rootDir, join(rootDir, "package.json")),
-          message: `Direct dependency "${packageName}" found in ${blockName}.`,
-          suggestion: packageName === "@nuxt/content" ? "Remove @nuxt/content and install @lupinum/ginko-content." : `Remove ${packageName} unless the app imports it directly. If it is only transitive, keep it out of package.json.`
+function findCollectionDefinitions(text) {
+  const authoredCollections = findAuthoredCollectionDefinitions(text);
+  const definitions = /* @__PURE__ */ new Map();
+  for (const block of findObjectPropertyBlocks(text, "collections")) {
+    for (const match of block.matchAll(/([a-z_$][\w$]*)\s*:\s*([a-z_$][\w$]*)\b/g)) {
+      const [, key, identifier] = match;
+      const authored = authoredCollections.get(identifier);
+      if (authored) {
+        definitions.set(key, {
+          name: key,
+          block: authored.block
         });
       }
     }
-  }
-  return findings;
-}
-async function inspectPackageJson(rootDir) {
-  const path = join(rootDir, "package.json");
-  if (!existsSync(path)) {
-    return [];
-  }
-  try {
-    const packageJson = JSON.parse(await readFile(path, "utf8"));
-    return packageDependencyFindings(rootDir, packageJson);
-  } catch {
-    return [{
-      severity: "error",
-      file: "package.json",
-      message: "package.json could not be parsed.",
-      suggestion: "Fix package.json before running ginko-content doctor again."
-    }];
-  }
-}
-async function inspectSourceFiles(rootDir) {
-  const files = await collectFiles(rootDir, rootDir);
-  const findings = [];
-  for (const file of files) {
-    if (lockfileNames.includes(file.split("/").pop() || "")) {
-      continue;
-    }
-    const text = await readFile(file, "utf8");
-    for (const check of sourceChecks) {
-      if (check.pattern.test(text)) {
-        findings.push({
-          severity: "error",
-          file: toRelativePath(rootDir, file),
-          message: check.message,
-          suggestion: check.suggestion
+    for (const match of block.matchAll(/(?:^|[,{]\s*)([a-z_$][\w$]*)\s*(?=,|\})/g)) {
+      const key = match[1];
+      const authored = authoredCollections.get(key);
+      if (authored) {
+        definitions.set(key, {
+          name: key,
+          block: authored.block
         });
       }
     }
   }
-  return findings;
-}
-async function inspectLockfiles(rootDir) {
-  const findings = [];
-  for (const lockfileName of lockfileNames) {
-    const path = join(rootDir, lockfileName);
-    if (!existsSync(path)) {
-      continue;
-    }
-    const text = await readFile(path, "utf8");
-    const presentPackages = stalePackageNames.filter((packageName) => text.includes(packageName));
-    if (presentPackages.length) {
-      findings.push({
-        severity: "info",
-        file: lockfileName,
-        message: `Lockfile still mentions ${presentPackages.join(", ")}.`,
-        suggestion: `Run "pnpm why ${presentPackages.join(" ")}" and only act if one is still a direct app dependency.`
+  for (const authored of authoredCollections.values()) {
+    if (authored.key) {
+      definitions.set(authored.key, {
+        name: authored.key,
+        block: authored.block
       });
     }
   }
-  return findings;
+  return [...definitions.values()];
 }
-async function readGeneratedSitemaps(rootDir) {
-  const outputPublicDir = join(rootDir, ".output/public");
-  if (!existsSync(outputPublicDir)) {
-    return [];
-  }
-  const sitemapPaths = [
-    join(outputPublicDir, "sitemap.xml"),
-    join(outputPublicDir, "sitemap_index.xml")
-  ];
-  const sitemapDir = join(outputPublicDir, "__sitemap__");
-  if (existsSync(sitemapDir)) {
-    const entries = await readdir(sitemapDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith(".xml")) {
-        sitemapPaths.push(join(sitemapDir, entry.name));
-      }
-    }
-  }
-  const sitemapFiles = [];
-  for (const sitemapPath of sitemapPaths) {
-    if (!existsSync(sitemapPath)) {
+function findObjectPropertyBlocks(text, property) {
+  const blocks = [];
+  const pattern = new RegExp(`\\b${property}\\s*:\\s*\\{`, "g");
+  for (const match of text.matchAll(pattern)) {
+    const bodyStart = text.indexOf("{", match.index);
+    if (bodyStart === -1) {
       continue;
     }
-    const fileStat = await stat(sitemapPath);
-    if (fileStat.isFile()) {
-      sitemapFiles.push({
-        file: toRelativePath(rootDir, sitemapPath),
-        text: await readFile(sitemapPath, "utf8")
-      });
-    }
+    const bodyEnd = findMatchingBrace(text, bodyStart);
+    blocks.push(text.slice(bodyStart, bodyEnd + 1));
   }
-  return sitemapFiles;
+  return blocks;
 }
-async function inspectSitemap(rootDir) {
-  const sitemapFiles = await readGeneratedSitemaps(rootDir);
-  const sitemapTexts = sitemapFiles.map((file) => file.text);
-  if (!sitemapTexts.length) {
-    return [];
-  }
-  const urlCount = sitemapTexts.reduce((total, text) => total + countSitemapUrls(text), 0);
-  const hasSitemapIndex = sitemapTexts.some((text) => /<sitemapindex\b/.test(text));
-  if (urlCount > 0 || hasSitemapIndex) {
+function extractStringArrayProperty(block, property) {
+  const match = block.match(new RegExp(`\\b${property}\\s*:\\s*\\[([\\s\\S]*?)\\]`));
+  if (!match) {
     return [];
   }
-  return [{
-    severity: "error",
-    file: ".output/public/sitemap.xml",
-    message: "Generated sitemap contains no <url> entries.",
-    suggestion: "Enable content.sitemap, configure site.url, and verify public route collections are sitemap-backed."
-  }];
-}
-async function readTextIfPresent(path) {
-  if (!existsSync(path)) {
-    return "";
-  }
-  const fileStat = await stat(path);
-  if (!fileStat.isFile()) {
-    return "";
-  }
-  return readFile(path, "utf8");
+  return [...match[1].matchAll(/['"]([^'"]+)['"]/g)].map((item) => item[1]);
 }
 function extractLocaleCodesFromConfig(text) {
   const locales = /* @__PURE__ */ new Set();
@@ -366,26 +311,7 @@ function extractLocaleCodesFromConfig(text) {
   }
   return [...locales];
 }
-async function readPackageJson(rootDir) {
-  const path = join(rootDir, "package.json");
-  if (!existsSync(path)) {
-    return void 0;
-  }
-  try {
-    return JSON.parse(await readFile(path, "utf8"));
-  } catch {
-    return void 0;
-  }
-}
-function hasDependency(packageJson, packageName) {
-  if (!packageJson) {
-    return false;
-  }
-  return ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"].some((blockName) => {
-    const block = packageJson[blockName];
-    return !!block && typeof block === "object" && packageName in block;
-  });
-}
+
 async function detectI18n(rootDir) {
   const nuxtConfigPath = join(rootDir, "nuxt.config.ts");
   const contentConfigPath = join(rootDir, "content.config.ts");
@@ -510,7 +436,7 @@ async function inspectI18nSourceSmells(rootDir, locales) {
         severity: "error",
         file: relativeFile,
         message: "Hardcoded locale route branch found.",
-        suggestion: "Use @nuxtjs/i18n route helpers, useContentTree(handle), or useContentMany(handle, options) item paths instead of branching on locale codes."
+        suggestion: "Use @nuxtjs/i18n route helpers, useContentNavigation('docs'), or useContentMany('docs', options) item paths instead of branching on locale codes."
       });
     }
     if (/<(?:NuxtLink|U[A-Za-z]+)\b[^>]*:to\s*=\s*["'][^"']+\._path["']/.test(text)) {
@@ -518,7 +444,7 @@ async function inspectI18nSourceSmells(rootDir, locales) {
         severity: "error",
         file: relativeFile,
         message: "UI link is bound to raw content _path.",
-        suggestion: "Use useContentMany(handle, options) for localized list pages and bind item.path."
+        suggestion: "Use useContentMany('docs', options) for localized list pages and bind item.path."
       });
     }
   }
@@ -562,22 +488,6 @@ async function inspectI18nDuplicateContentGroups(rootDir, locales) {
   }
   return findings;
 }
-async function collectOutputFiles(dir, rootDir, files = []) {
-  const entries = await readdir(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    const absolutePath = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (entry.name !== "_nuxt") {
-        await collectOutputFiles(absolutePath, rootDir, files);
-      }
-      continue;
-    }
-    if (entry.isFile() && [".html", ".json", ".xml"].includes(extname(entry.name))) {
-      files.push(absolutePath);
-    }
-  }
-  return files;
-}
 async function inspectRepeatedLocalePrefixes(rootDir, locales) {
   const outputPublicDir = join(rootDir, ".output/public");
   if (!existsSync(outputPublicDir)) {
@@ -698,22 +608,189 @@ async function inspectI18n(rootDir) {
     ...await inspectI18nSearchIndex(rootDir, detected.locales)
   ];
 }
-async function runDoctor(options = {}) {
-  const rootDir = options.rootDir || process.cwd();
-  const findings = [
+
+const stalePackageNames = ["@nuxt/content", "better-sqlite3", "@standard-schema/spec"];
+const lockfileNames = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"];
+
+function packageDependencyFindings(rootDir, packageJson) {
+  const dependencyBlocks = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+  const findings = [];
+  for (const blockName of dependencyBlocks) {
+    const block = packageJson[blockName];
+    if (!block || typeof block !== "object") {
+      continue;
+    }
+    for (const packageName of stalePackageNames) {
+      if (packageName in block) {
+        findings.push({
+          severity: "error",
+          file: toRelativePath(rootDir, join(rootDir, "package.json")),
+          message: `Direct dependency "${packageName}" found in ${blockName}.`,
+          suggestion: packageName === "@nuxt/content" ? "Remove @nuxt/content and install @lupinum/ginko-content." : `Remove ${packageName} unless the app imports it directly. If it is only transitive, keep it out of package.json.`
+        });
+      }
+    }
+  }
+  return findings;
+}
+async function inspectPackageJson(rootDir) {
+  const path = join(rootDir, "package.json");
+  if (!existsSync(path)) {
+    return [];
+  }
+  try {
+    const packageJson = JSON.parse(await readFile(path, "utf8"));
+    return packageDependencyFindings(rootDir, packageJson);
+  } catch {
+    return [{
+      severity: "error",
+      file: "package.json",
+      message: "package.json could not be parsed.",
+      suggestion: "Fix package.json before running ginko-content doctor again."
+    }];
+  }
+}
+async function inspectLockfiles(rootDir) {
+  const findings = [];
+  for (const lockfileName of lockfileNames) {
+    const path = join(rootDir, lockfileName);
+    if (!existsSync(path)) {
+      continue;
+    }
+    const text = await readFile(path, "utf8");
+    const presentPackages = stalePackageNames.filter((packageName) => text.includes(packageName));
+    if (presentPackages.length) {
+      findings.push({
+        severity: "info",
+        file: lockfileName,
+        message: `Lockfile still mentions ${presentPackages.join(", ")}.`,
+        suggestion: `Run "pnpm why ${presentPackages.join(" ")}" and only act if one is still a direct app dependency.`
+      });
+    }
+  }
+  return findings;
+}
+async function inspectDependencies(rootDir) {
+  return [
     ...await inspectPackageJson(rootDir),
-    ...await inspectSourceFiles(rootDir),
-    ...await inspectLockfiles(rootDir),
-    ...await inspectSitemap(rootDir),
-    ...options.i18n ? await inspectI18n(rootDir) : []
-  ].sort((a, b) => `${a.severity}:${a.file}:${a.message}`.localeCompare(`${b.severity}:${b.file}:${b.message}`));
-  const exitCode = findings.some((finding) => finding.severity === "error") ? 1 : 0;
-  return {
-    rootDir,
-    findings,
-    exitCode
-  };
+    ...await inspectLockfiles(rootDir)
+  ];
+}
+
+async function inspectSourceChecks(rootDir, checks) {
+  const files = await collectFiles(rootDir, rootDir);
+  const findings = [];
+  for (const file of files) {
+    if (lockfileNames.includes(file.split("/").pop() || "")) {
+      continue;
+    }
+    const text = await readFile(file, "utf8");
+    for (const check of checks) {
+      if (check.pattern.test(text)) {
+        findings.push({
+          severity: "error",
+          file: toRelativePath(rootDir, file),
+          message: check.message,
+          suggestion: check.suggestion
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+async function inspectPublicApiUsage(rootDir) {
+  return inspectSourceChecks(rootDir, [
+    {
+      pattern: /from\s+['"]@nuxt\/content(?:\/[^'"]*)?['"]|import\s*\([^)]*['"]@nuxt\/content(?:\/[^'"]*)?['"][^)]*\)/,
+      message: "Direct Nuxt Content import found.",
+      suggestion: "Import Ginko helpers from @lupinum/ginko-content/config, /client, or /server."
+    },
+    {
+      pattern: /['"]@nuxt\/content['"]/,
+      message: "Nuxt Content module or package reference found.",
+      suggestion: "Remove @nuxt/content from Nuxt modules and use @lupinum/ginko-content."
+    },
+    {
+      pattern: /\bqueryCollectionItemSurroundings\s*\(/,
+      message: "Nuxt Content v3 surround helper found.",
+      suggestion: "Use useContentPage('docs', { surround: true }) in route page components."
+    },
+    {
+      pattern: /\bqueryCollectionSearchSections\s*\(/,
+      message: "Nuxt Content v3 search sections helper found.",
+      suggestion: "Use useContentSearchData('docs') for UI search data."
+    },
+    {
+      pattern: /\bqueryCollectionNavigation\s*\(/,
+      message: "Nuxt Content v3 navigation helper found.",
+      suggestion: "Use useContentNavigation('docs') for layout navigation."
+    },
+    {
+      pattern: /\bqueryCollection\s*\(/,
+      message: "Removed collection query helper found.",
+      suggestion: "Use one('docs', options), many('docs', options), paginate('docs', options), or the matching useContent* composable."
+    },
+    {
+      pattern: /\buseContentList\s*\(/,
+      message: "Removed content list composable found.",
+      suggestion: "Use useContentMany('docs', options) or many('docs', options)."
+    },
+    {
+      pattern: /\bcontent\.(database|preview|build)\b/,
+      message: "Nuxt Content v3 runtime config key found.",
+      suggestion: "Remove content.database/content.preview/content.build and configure Ginko runtime options instead."
+    },
+    {
+      pattern: /\.editor\s*\(/,
+      message: "Nuxt Studio Zod .editor(...) helper found.",
+      suggestion: "Remove .editor(...) from runtime Zod schemas or move editor metadata outside the schema."
+    }
+  ]);
+}
+
+async function inspectRenderingUsage(rootDir) {
+  return inspectSourceChecks(rootDir, [
+    {
+      pattern: /<ContentRenderer\b[^>]*:value\s*=\s*["'][^"']*\.body["']/,
+      message: "ContentRenderer is receiving a document body.",
+      suggestion: "Pass the full content document to ContentRenderer, not document.body."
+    },
+    {
+      pattern: /<NuxtLink\b[^>]*:to\s*=\s*["'][^"']+\._path["']/,
+      message: "NuxtLink is using raw content _path.",
+      suggestion: "Use useContentMany('docs', options) for list pages and bind the route-safe item.path field."
+    }
+  ]);
 }
+
+async function inspectSearchCollections(rootDir) {
+  const contentConfig = await readTextIfPresent(join(rootDir, "content.config.ts"));
+  const nuxtConfig = await readTextIfPresent(join(rootDir, "nuxt.config.ts"));
+  if (!contentConfig || !nuxtConfig) {
+    return [];
+  }
+  const dataCollections = new Set(
+    findCollectionDefinitions(contentConfig).filter((collection) => /\btype\s*:\s*['"]data['"]/.test(collection.block)).map((collection) => collection.name)
+  );
+  if (!dataCollections.size) {
+    return [];
+  }
+  const configuredCollections = new Set(
+    findObjectPropertyBlocks(nuxtConfig, "search").flatMap((block) => extractStringArrayProperty(block, "collections"))
+  );
+  const dataSearchCollections = [...configuredCollections].filter((collection) => dataCollections.has(collection));
+  if (!dataSearchCollections.length) {
+    return [];
+  }
+  return [{
+    severity: "info",
+    file: "nuxt.config.ts",
+    message: `Data-only collections listed in content.search.collections: ${dataSearchCollections.join(", ")}.`,
+    suggestion: "Remove data-only collections from the static public search index, make them route-backed pages, or use provider-backed search with route-safe results."
+  }];
+}
+
 function formatDoctorResult(result) {
   const errors = result.findings.filter((finding) => finding.severity === "error");
   const infos = result.findings.filter((finding) => finding.severity === "info");
@@ -739,6 +816,24 @@ function formatDoctorResult(result) {
 `;
 }
 
+async function runDoctor(options = {}) {
+  const rootDir = options.rootDir || process.cwd();
+  const findings = [
+    ...await inspectDependencies(rootDir),
+    ...await inspectPublicApiUsage(rootDir),
+    ...await inspectRenderingUsage(rootDir),
+    ...await inspectSearchCollections(rootDir),
+    ...await inspectSitemap(rootDir),
+    ...options.i18n ? await inspectI18n(rootDir) : []
+  ].sort((a, b) => `${a.severity}:${a.file}:${a.message}`.localeCompare(`${b.severity}:${b.file}:${b.message}`));
+  const exitCode = findings.some((finding) => finding.severity === "error") ? 1 : 0;
+  return {
+    rootDir,
+    findings,
+    exitCode
+  };
+}
+
 const [, , command, ...args] = process.argv;
 if (!command || command === "--help" || command === "-h") {
   console.log([