create-dox 0.3.4 → 0.5.0

package/dist/{chunk-YY5QPPAG.js → chunk-23YWNWTH.js}

@@ -19,9 +19,9 @@ function shouldInclude(path) {
   }
   return true;
 }
-async function downloadTemplate(targetDir) {
+async function downloadTemplate(targetDir, siteName) {
   console.log("");
-  console.log("  \u23F3 Downloading Dox template...");
+  console.log(`  \u23F3 Creating ${siteName?.trim() || "your docs site"}...`);
   const response = await fetch(TARBALL_URL);
   if (!response.ok) {
     throw new Error(`Failed to download template: ${response.status} ${response.statusText}`);
@@ -135,6 +135,11 @@ function buildStarterDocsJson({
   i18nLocales
 }) {
   const config = {};
+  config.theme = "sharp";
+  config.fonts = {
+    body: { family: "Plus Jakarta Sans", weight: ["400", "500", "600", "700"] },
+    heading: { family: "Outfit", weight: ["600", "700"] }
+  };
   if (enableAiChat) {
     config.ai = { chat: true };
   }
@@ -201,20 +206,15 @@ function updateSiteConfig(targetDir, projectName, description, brandPreset, repo
     /const brandPreset:\s*BrandPresetKey\s*=\s*'[^']*'/,
     `const brandPreset: BrandPresetKey = '${brandPreset}'`
   );
-  if (repoUrl) {
-    source = source.replace(
-      /repoUrl:\s*'[^']*'/,
-      `repoUrl: '${repoUrl}'`
-    );
-    source = source.replace(
-      /\{\s*label:\s*'GitHub',\s*href:\s*'[^']*'\s*\}/,
-      `{ label: 'GitHub', href: '${repoUrl}' }`
-    );
-    source = source.replace(
-      /\{\s*label:\s*'Support',\s*href:\s*'[^']*'\s*\}/,
-      `{ label: 'Support', href: '${repoUrl}/issues/new' }`
-    );
-  }
+  source = source.replace(/repoUrl:\s*'[^']*'/, `repoUrl: '${repoUrl}'`);
+  source = source.replace(
+    /\{\s*label:\s*'GitHub',\s*href:\s*'[^']*'\s*\}/,
+    `{ label: 'GitHub', href: '${repoUrl}' }`
+  );
+  source = source.replace(
+    /\{\s*label:\s*'Support',\s*href:\s*'[^']*'\s*\}/,
+    `{ label: 'Support', href: '${repoUrl ? `${repoUrl}/issues/new` : ""}' }`
+  );
   writeFileSync(siteFile, source, "utf8");
 }
 function patchApiReferenceGuard(targetDir) {
@@ -366,7 +366,7 @@ async function scaffold(options) {
   }
   mkdirSync2(targetDir, { recursive: true });
   const slug = slugify(projectName);
-  await downloadTemplate(targetDir);
+  await downloadTemplate(targetDir, projectName);
   writeStarterContent(targetDir, projectName, slug, enableAiChat, repoUrl, i18nLocales);
   updateSiteConfig(targetDir, projectName, description, brandPreset, repoUrl);
   patchApiReferenceGuard(targetDir);

package/dist/{chunk-QB4U3KFX.js → chunk-GVYVHLAP.js}

@@ -3,7 +3,7 @@ import {
   initGit,
   installDeps,
   scaffold
-} from "./chunk-YY5QPPAG.js";
+} from "./chunk-23YWNWTH.js";
 
 // src/migrate/index.ts
 import { mkdirSync as mkdirSync2, copyFileSync as copyFileSync2, readFileSync as readFileSync3, writeFileSync, existsSync as existsSync3, mkdtempSync, rmSync } from "fs";

package/dist/index.js

@@ -2,13 +2,13 @@
 import {
   migrateDocs,
   parseGitHubUrl
-} from "./chunk-QB4U3KFX.js";
+} from "./chunk-GVYVHLAP.js";
 import {
   logo,
   scaffold,
   slugify,
   success
-} from "./chunk-YY5QPPAG.js";
+} from "./chunk-23YWNWTH.js";
 
 // src/index.ts
 import { existsSync as existsSync3, readdirSync as readdirSync2 } from "fs";
@@ -99,7 +99,9 @@ async function gatherAnswers(dirArg, useDefaults) {
 // src/check.ts
 import { existsSync, readFileSync as readFileSync2, readdirSync, statSync } from "fs";
 import { join as join2, extname, relative } from "path";
+import { execFileSync } from "child_process";
 import matter from "gray-matter";
+import { parse as parseYaml } from "yaml";
 
 // src/docs-json.ts
 import { readFileSync, writeFileSync } from "fs";
@@ -115,14 +117,62 @@ function writeDocsJson(projectDir, config) {
 }
 
 // src/check.ts
+function gitLocal(projectDir, args2) {
+  try {
+    const out = execFileSync("git", args2, { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return { ok: true, out: out.trim() };
+  } catch {
+    return { ok: false, out: "" };
+  }
+}
+function checkDrift(projectDir, file, data, issues) {
+  const sources = data.sources;
+  const verifiedCommit = data.verifiedCommit;
+  if (!Array.isArray(sources) || sources.length === 0 || typeof verifiedCommit !== "string" || !verifiedCommit.trim()) {
+    return;
+  }
+  const commit = verifiedCommit.trim();
+  if (!gitLocal(projectDir, ["cat-file", "-e", `${commit}^{commit}`]).ok) {
+    issues.push({
+      severity: "warning",
+      message: `Cannot verify freshness: verifiedCommit "${commit.slice(0, 8)}" is not in git history \u2014 run with a full clone (fetch-depth: 0).`,
+      file
+    });
+    return;
+  }
+  for (const src of sources) {
+    if (typeof src !== "string" || !src.trim()) continue;
+    const colon = src.indexOf(":");
+    let filePath = src;
+    if (colon > 0) {
+      const alias = src.slice(0, colon);
+      if (alias !== "." && alias !== "self") {
+        issues.push({
+          severity: "warning",
+          message: `Cross-repo source "${src}" \u2014 drift check skipped (needs the referenced repo; see multi-repo setup).`,
+          file
+        });
+        continue;
+      }
+      filePath = src.slice(colon + 1);
+    }
+    filePath = filePath.replace(/^\.\//, "").replace(/#.*$/, "");
+    const changed = gitLocal(projectDir, ["log", "--format=%H", `${commit}..HEAD`, "--", filePath]).out;
+    if (changed) {
+      const n = changed.split("\n").filter(Boolean).length;
+      issues.push({
+        severity: "warning",
+        message: `Drift: source "${src}" changed in ${n} commit(s) since it was verified \u2014 this page may be stale.`,
+        file
+      });
+    }
+  }
+}
 function collectNavPageIds(groups, seen, duplicates) {
   for (const page of groups) {
     if (typeof page === "string") {
-      if (seen.has(page)) {
-        duplicates.add(page);
-      } else {
-        seen.add(page);
-      }
+      if (seen.has(page)) duplicates.add(page);
+      else seen.add(page);
     } else if (page.pages) {
       collectNavPageIds(page.pages, seen, duplicates);
     }
@@ -139,11 +189,8 @@ function scanMdx(dir, results) {
     const fullPath = join2(dir, entry);
     try {
       const stat = statSync(fullPath);
-      if (stat.isDirectory()) {
-        scanMdx(fullPath, results);
-      } else if (extname(entry).toLowerCase() === ".mdx") {
-        results.push(fullPath);
-      }
+      if (stat.isDirectory()) scanMdx(fullPath, results);
+      else if (extname(entry).toLowerCase() === ".mdx") results.push(fullPath);
     } catch {
     }
   }
@@ -159,7 +206,80 @@ function addOrphanToNav(projectDir, pageId) {
     writeDocsJson(projectDir, config);
   }
 }
-async function runCheck(projectDir, fix) {
+function slugify2(text) {
+  return text.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-");
+}
+function extractHeadingAnchors(content) {
+  const anchors = /* @__PURE__ */ new Set();
+  for (const line of content.split("\n")) {
+    const m = /^#{1,6}\s+(.+?)\s*#*\s*$/.exec(line);
+    if (m) anchors.add(slugify2(m[1]));
+  }
+  return anchors;
+}
+function extractLinks(content) {
+  const links = [];
+  const lines = content.split("\n");
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*(```|~~~)/.test(lines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const line = lines[i].replace(/`[^`]*`/g, "");
+    for (const m of line.matchAll(/\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
+      links.push({ target: m[1], line: i + 1 });
+    }
+    for (const m of line.matchAll(/href=["']([^"']+)["']/g)) {
+      links.push({ target: m[1], line: i + 1 });
+    }
+  }
+  return links;
+}
+function pageIdToPath(pageId) {
+  return pageId === "introduction" ? "/" : `/${pageId}`;
+}
+function validateOpenApi(projectDir, source, issues) {
+  const specPath = join2(projectDir, source);
+  if (!existsSync(specPath)) {
+    issues.push({ severity: "error", message: `API reference points at "${source}" but the file does not exist`, file: source });
+    return;
+  }
+  let spec;
+  try {
+    const raw = readFileSync2(specPath, "utf8");
+    spec = source.endsWith(".json") ? JSON.parse(raw) : parseYaml(raw);
+  } catch (err) {
+    issues.push({ severity: "error", message: `OpenAPI spec is not valid ${source.endsWith(".json") ? "JSON" : "YAML"}: ${err.message}`, file: source });
+    return;
+  }
+  const s = spec;
+  if (typeof s?.openapi !== "string" && typeof s?.swagger !== "string") {
+    issues.push({ severity: "error", message: 'OpenAPI spec is missing the "openapi" (or "swagger") version field', file: source });
+  }
+  if (typeof s?.info !== "object" || s.info === null) {
+    issues.push({ severity: "error", message: 'OpenAPI spec is missing the "info" object', file: source });
+  }
+  const paths = s?.paths;
+  if (typeof paths !== "object" || paths === null) {
+    issues.push({ severity: "error", message: 'OpenAPI spec is missing the "paths" object', file: source });
+  } else {
+    const methods = /* @__PURE__ */ new Set(["get", "post", "put", "patch", "delete", "options", "head", "trace"]);
+    for (const [p, ops] of Object.entries(paths)) {
+      if (typeof ops !== "object" || ops === null) {
+        issues.push({ severity: "error", message: `OpenAPI path "${p}" is not an object`, file: source });
+        continue;
+      }
+      const hasOp = Object.keys(ops).some((k) => methods.has(k.toLowerCase()));
+      if (!hasOp) {
+        issues.push({ severity: "warning", message: `OpenAPI path "${p}" has no operations`, file: source });
+      }
+    }
+  }
+}
+async function runCheck(projectDir, options) {
+  const { fix, ci } = options;
   if (!existsSync(join2(projectDir, "docs.json"))) {
     console.error(`
   \u274C Not a Dox project: docs.json not found in ${projectDir}
@@ -172,7 +292,11 @@ async function runCheck(projectDir, fix) {
   const navPageIds = /* @__PURE__ */ new Set();
   const duplicates = /* @__PURE__ */ new Set();
   for (const tab of config.tabs) {
-    if (tab.href || tab.api) continue;
+    if (tab.href) {
+      if (tab.href.startsWith("/")) navPageIds.add(tab.href.slice(1) || "introduction");
+      continue;
+    }
+    if (tab.api) continue;
     if (!tab.groups || tab.groups.length === 0) {
       issues.push({ severity: "error", message: `Tab "${tab.tab}" has no groups and no href \u2014 it will render empty` });
       continue;
@@ -183,21 +307,17 @@ async function runCheck(projectDir, fix) {
     issues.push({ severity: "error", message: `[duplicate] "${dup}" appears more than once in docs.json` });
   }
   for (const pageId of navPageIds) {
-    const candidates = [
-      join2(contentDir, `${pageId}.mdx`),
-      join2(contentDir, `${pageId}/index.mdx`)
-    ];
+    const candidates = [join2(contentDir, `${pageId}.mdx`), join2(contentDir, `${pageId}/index.mdx`)];
     if (!candidates.some((c) => existsSync(c))) {
-      issues.push({
-        severity: "error",
-        message: `"${pageId}" is in docs.json but has no MDX file`,
-        file: `src/content/${pageId}.mdx`
-      });
+      issues.push({ severity: "error", message: `"${pageId}" is in docs.json but has no MDX file`, file: `src/content/${pageId}.mdx` });
     }
   }
   const allFiles = [];
   if (existsSync(contentDir)) scanMdx(contentDir, allFiles);
   const fixedOrphans = [];
+  const validPaths = /* @__PURE__ */ new Set(["/"]);
+  const anchorsByPath = /* @__PURE__ */ new Map();
+  const linksByFile = [];
   for (const filePath of allFiles) {
     const rel = filePath.slice(contentDir.length + 1).replace(/\.mdx$/, "").replace(/\\/g, "/");
     const pageId = rel.endsWith("/index") ? rel.slice(0, -6) : rel;
@@ -206,37 +326,70 @@ async function runCheck(projectDir, fix) {
         addOrphanToNav(projectDir, pageId);
         fixedOrphans.push(pageId);
       } else {
-        issues.push({
-          severity: "warning",
-          message: `"${pageId}" is not in docs.json nav (orphan)`,
-          file: relative(projectDir, filePath)
-        });
+        issues.push({ severity: "warning", message: `"${pageId}" is not in docs.json nav (orphan)`, file: relative(projectDir, filePath) });
       }
     }
     let data = {};
     let content = "";
+    let lineOffset = 0;
     try {
       const raw = readFileSync2(filePath, "utf8");
       const parsed = matter(raw);
       data = parsed.data;
       content = parsed.content;
+      lineOffset = raw.slice(0, raw.indexOf(content)).split("\n").length - 1;
     } catch {
       issues.push({ severity: "error", message: `Could not parse frontmatter`, file: relative(projectDir, filePath) });
       continue;
     }
     const rel2 = relative(projectDir, filePath);
-    if (!data.title) {
-      issues.push({ severity: "warning", message: `Missing "title" in frontmatter`, file: rel2 });
-    }
-    if (!data.description) {
-      issues.push({ severity: "warning", message: `Missing "description" in frontmatter`, file: rel2 });
-    }
-    if (content.trim().length < 50) {
-      issues.push({ severity: "warning", message: `Very short body (${content.trim().length} chars) \u2014 page may be empty`, file: rel2 });
+    if (!data.title) issues.push({ severity: "warning", message: `Missing "title" in frontmatter`, file: rel2 });
+    if (!data.description) issues.push({ severity: "warning", message: `Missing "description" in frontmatter`, file: rel2 });
+    if (content.trim().length < 50) issues.push({ severity: "warning", message: `Very short body (${content.trim().length} chars) \u2014 page may be empty`, file: rel2 });
+    if (options.drift) checkDrift(projectDir, rel2, data, issues);
+    const path = pageIdToPath(pageId);
+    const anchors = extractHeadingAnchors(content);
+    validPaths.add(path);
+    anchorsByPath.set(path, anchors);
+    linksByFile.push({ file: rel2, path, anchors, links: extractLinks(content), offset: lineOffset });
+  }
+  for (const { file, anchors, links, offset } of linksByFile) {
+    for (const { target, line: contentLine } of links) {
+      const line = contentLine + offset;
+      if (/^(https?:|mailto:|tel:)/i.test(target)) continue;
+      if (target.startsWith("#")) {
+        const anchor2 = target.slice(1);
+        if (anchor2 && !anchors.has(anchor2)) {
+          issues.push({ severity: "warning", message: `Broken anchor: "${target}" not found on this page`, file, line });
+        }
+        continue;
+      }
+      if (!target.startsWith("/")) continue;
+      const [beforeHash, anchor] = target.split("#");
+      let path = beforeHash.split("?")[0];
+      if (path.length > 1) path = path.replace(/\/$/, "");
+      if (path.startsWith("/api") || path.startsWith("/_next") || /\.[a-z0-9]+$/i.test(path)) continue;
+      if (!validPaths.has(path)) {
+        issues.push({ severity: "error", message: `Broken link: "${target}" \u2014 no page at "${path}"`, file, line });
+      } else if (anchor && !anchorsByPath.get(path)?.has(anchor)) {
+        issues.push({ severity: "warning", message: `Broken anchor: "${target}" \u2014 no heading "#${anchor}" on that page`, file, line });
+      }
     }
   }
+  for (const tab of config.tabs) {
+    if (tab.api?.source) validateOpenApi(projectDir, tab.api.source, issues);
+  }
   const errors = issues.filter((i) => i.severity === "error");
   const warnings = issues.filter((i) => i.severity === "warning");
+  if (ci) {
+    for (const issue of issues) {
+      const loc = issue.file ? `file=${issue.file}${issue.line ? `,line=${issue.line}` : ""}` : "";
+      console.log(`::${issue.severity} ${loc}::${issue.message}`);
+    }
+    console.log(`
+dox check: ${errors.length} error(s), ${warnings.length} warning(s)`);
+    return errors.length > 0 ? 1 : 0;
+  }
   console.log(`
   Linting ${projectDir}...
 `);
@@ -250,7 +403,7 @@ async function runCheck(projectDir, fix) {
     console.log("  ERRORS:");
     for (const issue of errors) {
       console.log(`    ${issue.message}`);
-      if (issue.file) console.log(`    \u2192 ${issue.file}`);
+      if (issue.file) console.log(`    \u2192 ${issue.file}${issue.line ? `:${issue.line}` : ""}`);
     }
     console.log("");
   }
@@ -258,7 +411,7 @@ async function runCheck(projectDir, fix) {
     console.log("  WARNINGS:");
     for (const issue of warnings) {
       console.log(`    ${issue.message}`);
-      if (issue.file) console.log(`    \u2192 ${issue.file}`);
+      if (issue.file) console.log(`    \u2192 ${issue.file}${issue.line ? `:${issue.line}` : ""}`);
     }
     console.log("");
   }
@@ -601,8 +754,12 @@ async function runScaffoldCommand() {
 }
 async function runCheckCommand() {
   const projectDir = resolve2(positional[1] ?? ".");
-  const fix = flags.includes("--fix");
-  const exitCode = await runCheck(projectDir, fix);
+  const exitCode = await runCheck(projectDir, {
+    fix: flags.includes("--fix"),
+    ci: flags.includes("--ci"),
+    external: flags.includes("--external"),
+    drift: flags.includes("--drift")
+  });
   process.exit(exitCode);
 }
 async function runTranslateSubcommand() {

package/dist/migrate/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   migrateDocs
-} from "../chunk-QB4U3KFX.js";
-import "../chunk-YY5QPPAG.js";
+} from "../chunk-GVYVHLAP.js";
+import "../chunk-23YWNWTH.js";
 export {
   migrateDocs
 };

package/dist/scaffold.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   scaffold
-} from "./chunk-YY5QPPAG.js";
+} from "./chunk-23YWNWTH.js";
 export {
   scaffold
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dox",
-  "version": "0.3.4",
+  "version": "0.5.0",
   "description": "Scaffold a new Dox documentation project",
   "type": "module",
   "engines": {
@@ -28,7 +28,8 @@
     "@inquirer/prompts": "^7.0.0",
     "gray-matter": "^4.0.3",
     "p-limit": "^6.1.0",
-    "tar": "^6.2.0"
+    "tar": "^6.2.0",
+    "yaml": "^2.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",