@olwiba/dx 0.0.28 → 0.0.29

package/README.md

@@ -1,8 +1,8 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Olwiba/olwibaDX/master/public/olwibaDX--light.gif" />
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Olwiba/olwibaDX/master/public/olwibaDX.gif" />
-    <img src="https://raw.githubusercontent.com/Olwiba/olwibaDX/master/public/olwibaDX.gif" alt="olwibaDX" style="width: 100%;" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Olwiba/olwibaDX/master/.github/assets/olwibaDX--light.gif" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Olwiba/olwibaDX/master/.github/assets/olwibaDX.gif" />
+    <img src="https://raw.githubusercontent.com/Olwiba/olwibaDX/master/.github/assets/olwibaDX.gif" alt="olwibaDX" style="width: 100%;" />
   </picture>
 </p>
 
@@ -78,7 +78,7 @@ Render an animated ASCII GIF from any text. This is what produced the README ban
 bunx @olwiba/dx ascii-gif \
   --text "olwibaDX" \
   --accent "DX" \
-  --out ./public/olwibaDX.gif
+  --out ./.github/assets/olwibaDX.gif
 ```
 
 ### Asset Generator

package/dist/cli.js

@@ -2487,6 +2487,143 @@ var init_env_check = __esm({
   }
 });
 
+// src/docs-check.ts
+var docs_check_exports = {};
+__export(docs_check_exports, {
+  checkDocs: () => checkDocs,
+  formatDocsReport: () => formatDocsReport
+});
+function withoutCode(source) {
+  return source.replace(/^[ \t]*(`{3,}|~{3,})[\s\S]*?^[ \t]*\1[ \t]*$/gm, "").replace(/`[^`\n]*`/g, "");
+}
+function optOutIsExplained(source) {
+  const match = source.match(/api-reference:\s*none\b([\s\S]{0,400})/);
+  if (!match) return false;
+  const tail = match[1] ?? "";
+  const end = tail.indexOf("*/");
+  const within = end === -1 ? tail : tail.slice(0, end);
+  const words = within.replace(/^[\s—\-–:,.]+/, "").replace(/^\s*\*/gm, "").trim();
+  return words.split(/\s+/).filter(Boolean).length >= 3;
+}
+function extractPropsExpressions(source) {
+  const found = [];
+  const marker = "props=";
+  let index = source.indexOf(marker);
+  while (index !== -1) {
+    let cursor = index + marker.length;
+    if (source[cursor] !== "{") {
+      index = source.indexOf(marker, cursor);
+      continue;
+    }
+    let depth = 0;
+    const start = cursor;
+    for (; cursor < source.length; cursor += 1) {
+      if (source[cursor] === "{") depth += 1;
+      else if (source[cursor] === "}") {
+        depth -= 1;
+        if (depth === 0) break;
+      }
+    }
+    found.push(source.slice(start + 1, cursor));
+    index = source.indexOf(marker, cursor);
+  }
+  return found;
+}
+function propsFailure(source) {
+  for (const expression of extractPropsExpressions(source)) {
+    let value;
+    try {
+      value = new Function(`return (${expression});`)();
+    } catch (error) {
+      return error instanceof Error ? error.message : String(error);
+    }
+    if (!Array.isArray(value)) return "props is not an array";
+    for (const entry of value) {
+      if (typeof entry?.name !== "string" || typeof entry?.type !== "string") {
+        return `a prop entry is missing name or type: ${JSON.stringify(entry)}`;
+      }
+    }
+  }
+  return null;
+}
+function checkDocs(pages) {
+  const findings = [];
+  let okCount = 0;
+  let exemptCount = 0;
+  let skippedCount = 0;
+  for (const page of pages) {
+    const rendered = withoutCode(page.source);
+    const hasPreview = PREVIEW.test(rendered);
+    const hasReference = API_REFERENCE.test(rendered);
+    const optedOut = OPT_OUT.test(rendered);
+    const broken = hasReference ? propsFailure(page.source) : null;
+    if (broken) {
+      findings.push({ kind: "broken-props", file: page.file, reason: broken });
+      continue;
+    }
+    if (optedOut && hasReference) {
+      findings.push({ kind: "redundant-opt-out", file: page.file });
+      continue;
+    }
+    if (!hasPreview) {
+      skippedCount += 1;
+      continue;
+    }
+    if (optedOut) {
+      if (optOutIsExplained(rendered)) exemptCount += 1;
+      else findings.push({ kind: "unexplained-opt-out", file: page.file });
+      continue;
+    }
+    if (hasReference) okCount += 1;
+    else findings.push({ kind: "missing", file: page.file });
+  }
+  return { findings, okCount, exemptCount, skippedCount };
+}
+function formatDocsReport(result) {
+  const lines = [];
+  for (const finding of result.findings) {
+    if (finding.kind === "missing") {
+      lines.push(
+        `  ${finding.file}`,
+        "    Shows a preview but has no <APIReference>. Add one, or opt out with",
+        "    {/* api-reference: none \u2014 why */} if there is no public API here."
+      );
+    } else if (finding.kind === "broken-props") {
+      lines.push(
+        `  ${finding.file}`,
+        `    Its <APIReference> props are not valid JavaScript, so the page will not render.`,
+        `    ${finding.reason}`
+      );
+    } else if (finding.kind === "unexplained-opt-out") {
+      lines.push(
+        `  ${finding.file}`,
+        "    Opts out of the API reference without a reason. Write one after the marker."
+      );
+    } else {
+      lines.push(
+        `  ${finding.file}`,
+        "    Opts out of the API reference and then has one. Remove the stale marker."
+      );
+    }
+  }
+  const tally = `${result.okCount} documented, ${result.exemptCount} exempt, ${result.skippedCount} without a preview`;
+  if (result.findings.length === 0) {
+    return `All documentation pages that show a component document it (${tally}).`;
+  }
+  return `${result.findings.length} documentation page(s) need attention:
+${lines.join("\n")}
+
+${tally}`;
+}
+var OPT_OUT, PREVIEW, API_REFERENCE;
+var init_docs_check = __esm({
+  "src/docs-check.ts"() {
+    OPT_OUT = /api-reference:\s*none\b/;
+    PREVIEW = /<(Sandbox|ComponentPreview)\b/;
+    API_REFERENCE = /<APIReference\b/;
+  }
+});
+
 // src/skills.ts
 function isSafeSkillSlug(slug) {
   return slug !== "." && slug !== ".." && /^[A-Za-z0-9._-]+$/.test(slug);
@@ -2513,9 +2650,11 @@ if (command === "skills" && subcommand === "install") {
   await runGenerateAssets();
 } else if (command === "env-check" || command === "env") {
   process.exitCode = await runEnvCheck();
+} else if (command === "docs-check") {
+  process.exitCode = await runDocsCheck();
 } else {
   process.stdout.write(
-    "Usage:\n  dx skills install [--source <url>] [--target claude|amp] [--all] [--name a,b,c]\n  dx worktree cleanup [repo-name-or-path] [--repos-root <path>] [--remote <name>] [--dry-run] [--force] [--no-fetch]\n  dx ascii-gif --text <text> --out <file.gif>\n  dx generate-assets --name <app> --icon <lucide-icon> --color <#hex> [--out <dir>] [--og-component <svg-or-image-path>]\n"
+    "Usage:\n  dx skills install [--source <url>] [--target claude|amp] [--all] [--name a,b,c]\n  dx worktree cleanup [repo-name-or-path] [--repos-root <path>] [--remote <name>] [--dry-run] [--force] [--no-fetch]\n  dx ascii-gif --text <text> --out <file.gif>\n  dx generate-assets --name <app> --icon <lucide-icon> --color <#hex> [--out <dir>] [--og-component <svg-or-image-path>]\n  dx env-check [--example <.env.example>] [--file <.env>] [--optional a,b,c]\n  dx docs-check [--dir <content/docs>]\n"
   );
 }
 async function runSkillsInstall() {
@@ -2773,6 +2912,38 @@ async function runEnvCheck() {
   process.stdout.write(`${formatEnvReport2(result)}${BREAK}`);
   return result.findings.length > 0 ? 1 : 0;
 }
+async function runDocsCheck() {
+  const { readFileSync: readFileSync3, existsSync: existsSync2, readdirSync: readdirSync2 } = await import('fs');
+  const { join: join4, relative: relative2, sep: sep2 } = await import('path');
+  const { checkDocs: checkDocs2, formatDocsReport: formatDocsReport2 } = await Promise.resolve().then(() => (init_docs_check(), docs_check_exports));
+  const flags = parseFlags(process.argv.slice(3));
+  const dir = flags.dir ?? join4("content", "docs");
+  if (!existsSync2(dir)) {
+    process.stderr.write(
+      `No documentation directory at ${dir}.${BREAK}Pass --dir if this project keeps its pages elsewhere.` + BREAK
+    );
+    return 1;
+  }
+  const files = [];
+  const walk = (current) => {
+    for (const entry of readdirSync2(current, { withFileTypes: true })) {
+      const full = join4(current, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith(".mdx")) files.push(full);
+    }
+  };
+  walk(dir);
+  const result = checkDocs2(
+    files.sort().map((file) => ({
+      // Reported the same way on every platform, so a Windows run and a CI run
+      // produce comparable output.
+      file: relative2(process.cwd(), file).split(sep2).join("/"),
+      source: readFileSync3(file, "utf8")
+    }))
+  );
+  process.stdout.write(`${formatDocsReport2(result)}${BREAK}`);
+  return result.findings.length > 0 ? 1 : 0;
+}
 async function readAllStdin() {
   const chunks = [];
   for await (const chunk of stdin) chunks.push(Buffer.from(chunk));

package/dist/docs-check.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Checks that every documentation page showing a component also documents it.
+ *
+ * A docs page that renders a preview is making a promise: this is a component
+ * you can use. The properties table is the other half of that promise, and it
+ * is the half that goes missing, because a page reads as finished long before
+ * anyone writes the props down. Fourteen marketing pages and an `ErrorPage`
+ * page that said in prose "takes no props" — it has seven — shipped that way
+ * and nobody noticed until someone opened one on a phone.
+ *
+ * So the rule is mechanical: a preview implies an `<APIReference>`. Pages that
+ * genuinely have no public surface to document opt out in the file, in a
+ * comment that has to carry a reason.
+ */
+type DocsFinding = {
+    kind: 'missing';
+    file: string;
+}
+/** Opted out without saying why, which is how an opt-out becomes a habit. */
+ | {
+    kind: 'unexplained-opt-out';
+    file: string;
+}
+/** Opted out and then documented it anyway — the comment is stale. */
+ | {
+    kind: 'redundant-opt-out';
+    file: string;
+}
+/** The props array is not valid JavaScript, so the page cannot render. */
+ | {
+    kind: 'broken-props';
+    file: string;
+    reason: string;
+};
+interface DocsCheckResult {
+    findings: DocsFinding[];
+    /** Pages with a preview and a reference. Counted, not listed. */
+    okCount: number;
+    /** Pages with a preview and an explained opt-out. */
+    exemptCount: number;
+    /** Pages with no preview, which this says nothing about. */
+    skippedCount: number;
+}
+interface DocsPage {
+    /** Path as it should be reported — repository-relative, forward slashes. */
+    file: string;
+    source: string;
+}
+declare function checkDocs(pages: DocsPage[]): DocsCheckResult;
+declare function formatDocsReport(result: DocsCheckResult): string;
+
+export { type DocsCheckResult, type DocsFinding, type DocsPage, checkDocs, formatDocsReport };

package/dist/docs-check.js

@@ -0,0 +1,130 @@
+// src/docs-check.ts
+var OPT_OUT = /api-reference:\s*none\b/;
+var PREVIEW = /<(Sandbox|ComponentPreview)\b/;
+var API_REFERENCE = /<APIReference\b/;
+function withoutCode(source) {
+  return source.replace(/^[ \t]*(`{3,}|~{3,})[\s\S]*?^[ \t]*\1[ \t]*$/gm, "").replace(/`[^`\n]*`/g, "");
+}
+function optOutIsExplained(source) {
+  const match = source.match(/api-reference:\s*none\b([\s\S]{0,400})/);
+  if (!match) return false;
+  const tail = match[1] ?? "";
+  const end = tail.indexOf("*/");
+  const within = end === -1 ? tail : tail.slice(0, end);
+  const words = within.replace(/^[\s—\-–:,.]+/, "").replace(/^\s*\*/gm, "").trim();
+  return words.split(/\s+/).filter(Boolean).length >= 3;
+}
+function extractPropsExpressions(source) {
+  const found = [];
+  const marker = "props=";
+  let index = source.indexOf(marker);
+  while (index !== -1) {
+    let cursor = index + marker.length;
+    if (source[cursor] !== "{") {
+      index = source.indexOf(marker, cursor);
+      continue;
+    }
+    let depth = 0;
+    const start = cursor;
+    for (; cursor < source.length; cursor += 1) {
+      if (source[cursor] === "{") depth += 1;
+      else if (source[cursor] === "}") {
+        depth -= 1;
+        if (depth === 0) break;
+      }
+    }
+    found.push(source.slice(start + 1, cursor));
+    index = source.indexOf(marker, cursor);
+  }
+  return found;
+}
+function propsFailure(source) {
+  for (const expression of extractPropsExpressions(source)) {
+    let value;
+    try {
+      value = new Function(`return (${expression});`)();
+    } catch (error) {
+      return error instanceof Error ? error.message : String(error);
+    }
+    if (!Array.isArray(value)) return "props is not an array";
+    for (const entry of value) {
+      if (typeof entry?.name !== "string" || typeof entry?.type !== "string") {
+        return `a prop entry is missing name or type: ${JSON.stringify(entry)}`;
+      }
+    }
+  }
+  return null;
+}
+function checkDocs(pages) {
+  const findings = [];
+  let okCount = 0;
+  let exemptCount = 0;
+  let skippedCount = 0;
+  for (const page of pages) {
+    const rendered = withoutCode(page.source);
+    const hasPreview = PREVIEW.test(rendered);
+    const hasReference = API_REFERENCE.test(rendered);
+    const optedOut = OPT_OUT.test(rendered);
+    const broken = hasReference ? propsFailure(page.source) : null;
+    if (broken) {
+      findings.push({ kind: "broken-props", file: page.file, reason: broken });
+      continue;
+    }
+    if (optedOut && hasReference) {
+      findings.push({ kind: "redundant-opt-out", file: page.file });
+      continue;
+    }
+    if (!hasPreview) {
+      skippedCount += 1;
+      continue;
+    }
+    if (optedOut) {
+      if (optOutIsExplained(rendered)) exemptCount += 1;
+      else findings.push({ kind: "unexplained-opt-out", file: page.file });
+      continue;
+    }
+    if (hasReference) okCount += 1;
+    else findings.push({ kind: "missing", file: page.file });
+  }
+  return { findings, okCount, exemptCount, skippedCount };
+}
+function formatDocsReport(result) {
+  const lines = [];
+  for (const finding of result.findings) {
+    if (finding.kind === "missing") {
+      lines.push(
+        `  ${finding.file}`,
+        "    Shows a preview but has no <APIReference>. Add one, or opt out with",
+        "    {/* api-reference: none \u2014 why */} if there is no public API here."
+      );
+    } else if (finding.kind === "broken-props") {
+      lines.push(
+        `  ${finding.file}`,
+        `    Its <APIReference> props are not valid JavaScript, so the page will not render.`,
+        `    ${finding.reason}`
+      );
+    } else if (finding.kind === "unexplained-opt-out") {
+      lines.push(
+        `  ${finding.file}`,
+        "    Opts out of the API reference without a reason. Write one after the marker."
+      );
+    } else {
+      lines.push(
+        `  ${finding.file}`,
+        "    Opts out of the API reference and then has one. Remove the stale marker."
+      );
+    }
+  }
+  const tally = `${result.okCount} documented, ${result.exemptCount} exempt, ${result.skippedCount} without a preview`;
+  if (result.findings.length === 0) {
+    return `All documentation pages that show a component document it (${tally}).`;
+  }
+  return `${result.findings.length} documentation page(s) need attention:
+${lines.join("\n")}
+
+${tally}`;
+}
+
+export { checkDocs, formatDocsReport };
+//# sourceMappingURL=docs-check.js.map
+//# sourceMappingURL=docs-check.js.map

package/dist/docs-check.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/docs-check.ts"],"names":[],"mappings":"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","file":"docs-check.js","sourcesContent":["/**\n * Checks that every documentation page showing a component also documents it.\n *\n * A docs page that renders a preview is making a promise: this is a component\n * you can use. The properties table is the other half of that promise, and it\n * is the half that goes missing, because a page reads as finished long before\n * anyone writes the props down. Fourteen marketing pages and an `ErrorPage`\n * page that said in prose \"takes no props\" — it has seven — shipped that way\n * and nobody noticed until someone opened one on a phone.\n *\n * So the rule is mechanical: a preview implies an `<APIReference>`. Pages that\n * genuinely have no public surface to document opt out in the file, in a\n * comment that has to carry a reason.\n */\n\n/** Marks a page as having nothing to document, and says why. */\nconst OPT_OUT = /api-reference:\\s*none\\b/;\n\n/** What counts as showing a component off. */\nconst PREVIEW = /<(Sandbox|ComponentPreview)\\b/;\n\nconst API_REFERENCE = /<APIReference\\b/;\n\n/**\n * Drops fenced and inline code before looking for markers.\n *\n * A page that quotes `<Sandbox>` in a table, or shows what the opt-out comment\n * looks like inside a fence, is describing the markers rather than using them —\n * nothing is rendered and nothing is claimed. Matching the raw source made the\n * checker's own documentation page its first false positive, which is the sort\n * of rule that gets switched off rather than fixed.\n *\n * Fences go first so an unpaired backtick inside one cannot swallow the rest of\n * the file.\n */\nfunction withoutCode(source: string): string {\n  return source.replace(/^[ \\t]*(`{3,}|~{3,})[\\s\\S]*?^[ \\t]*\\1[ \\t]*$/gm, '').replace(/`[^`\\n]*`/g, '');\n}\n\nexport type DocsFinding =\n  | { kind: 'missing'; file: string }\n  /** Opted out without saying why, which is how an opt-out becomes a habit. */\n  | { kind: 'unexplained-opt-out'; file: string }\n  /** Opted out and then documented it anyway — the comment is stale. */\n  | { kind: 'redundant-opt-out'; file: string }\n  /** The props array is not valid JavaScript, so the page cannot render. */\n  | { kind: 'broken-props'; file: string; reason: string };\n\nexport interface DocsCheckResult {\n  findings: DocsFinding[];\n  /** Pages with a preview and a reference. Counted, not listed. */\n  okCount: number;\n  /** Pages with a preview and an explained opt-out. */\n  exemptCount: number;\n  /** Pages with no preview, which this says nothing about. */\n  skippedCount: number;\n}\n\nexport interface DocsPage {\n  /** Path as it should be reported — repository-relative, forward slashes. */\n  file: string;\n  source: string;\n}\n\n/**\n * An opt-out needs a reason after the marker, on the same line or the ones\n * following it inside the same comment. `api-reference: none` on its own is\n * rejected: the point of the escape hatch is that using it is a decision\n * somebody wrote down.\n */\nfunction optOutIsExplained(source: string): boolean {\n  const match = source.match(/api-reference:\\s*none\\b([\\s\\S]{0,400})/);\n  if (!match) return false;\n\n  const tail = match[1] ?? '';\n  // Stop at the end of the comment the marker sits in, so prose further down\n  // the page cannot pass for a justification.\n  const end = tail.indexOf('*/');\n  const within = end === -1 ? tail : tail.slice(0, end);\n\n  // Strip the punctuation an author uses to introduce the reason, plus the\n  // comment gutter, and see whether any words are left.\n  const words = within\n    .replace(/^[\\s—\\-–:,.]+/, '')\n    .replace(/^\\s*\\*/gm, '')\n    .trim();\n\n  return words.split(/\\s+/).filter(Boolean).length >= 3;\n}\n\n/**\n * Every balanced `{...}` following a `props=` attribute.\n *\n * Matched by counting braces rather than by regex: the prop tables contain\n * object literals, so the first `}` is nowhere near the end of the attribute.\n */\nfunction extractPropsExpressions(source: string): string[] {\n  const found: string[] = [];\n  const marker = 'props=';\n  let index = source.indexOf(marker);\n\n  while (index !== -1) {\n    let cursor = index + marker.length;\n    if (source[cursor] !== '{') {\n      index = source.indexOf(marker, cursor);\n      continue;\n    }\n\n    let depth = 0;\n    const start = cursor;\n    for (; cursor < source.length; cursor += 1) {\n      if (source[cursor] === '{') depth += 1;\n      else if (source[cursor] === '}') {\n        depth -= 1;\n        if (depth === 0) break;\n      }\n    }\n\n    found.push(source.slice(start + 1, cursor));\n    index = source.indexOf(marker, cursor);\n  }\n\n  return found;\n}\n\n/**\n * Confirms the prop table is JavaScript that runs.\n *\n * MDX does not evaluate a page's expressions until something renders it, so a\n * mis-escaped quote inside a description is invisible to every build step and\n * only shows up as a blank page. Evaluating the array here is the cheapest way\n * to find that out — the source being run is the repository's own.\n */\nfunction propsFailure(source: string): string | null {\n  for (const expression of extractPropsExpressions(source)) {\n    let value: unknown;\n    try {\n      value = new Function(`return (${expression});`)();\n    } catch (error) {\n      return error instanceof Error ? error.message : String(error);\n    }\n\n    if (!Array.isArray(value)) return 'props is not an array';\n\n    for (const entry of value as Array<Record<string, unknown>>) {\n      if (typeof entry?.name !== 'string' || typeof entry?.type !== 'string') {\n        return `a prop entry is missing name or type: ${JSON.stringify(entry)}`;\n      }\n    }\n  }\n\n  return null;\n}\n\nexport function checkDocs(pages: DocsPage[]): DocsCheckResult {\n  const findings: DocsFinding[] = [];\n  let okCount = 0;\n  let exemptCount = 0;\n  let skippedCount = 0;\n\n  for (const page of pages) {\n    // Markers are looked for in what the page renders, not in what it quotes.\n    const rendered = withoutCode(page.source);\n    const hasPreview = PREVIEW.test(rendered);\n    const hasReference = API_REFERENCE.test(rendered);\n    const optedOut = OPT_OUT.test(rendered);\n\n    // Checked before anything else: a page whose table cannot run has a worse\n    // problem than a page that has no table. Read from the raw source: a props\n    // table is an expression MDX evaluates, and stripping inline code would\n    // change it.\n    const broken = hasReference ? propsFailure(page.source) : null;\n    if (broken) {\n      findings.push({ kind: 'broken-props', file: page.file, reason: broken });\n      continue;\n    }\n\n    if (optedOut && hasReference) {\n      findings.push({ kind: 'redundant-opt-out', file: page.file });\n      continue;\n    }\n\n    if (!hasPreview) {\n      // Index pages, guides, concept pages. Nothing is being shown off, so\n      // there is nothing this can reasonably demand.\n      skippedCount += 1;\n      continue;\n    }\n\n    if (optedOut) {\n      if (optOutIsExplained(rendered)) exemptCount += 1;\n      else findings.push({ kind: 'unexplained-opt-out', file: page.file });\n      continue;\n    }\n\n    if (hasReference) okCount += 1;\n    else findings.push({ kind: 'missing', file: page.file });\n  }\n\n  return { findings, okCount, exemptCount, skippedCount };\n}\n\nexport function formatDocsReport(result: DocsCheckResult): string {\n  const lines: string[] = [];\n\n  for (const finding of result.findings) {\n    if (finding.kind === 'missing') {\n      lines.push(\n        `  ${finding.file}`,\n        '    Shows a preview but has no <APIReference>. Add one, or opt out with',\n        '    {/* api-reference: none — why */} if there is no public API here.',\n      );\n    } else if (finding.kind === 'broken-props') {\n      lines.push(\n        `  ${finding.file}`,\n        `    Its <APIReference> props are not valid JavaScript, so the page will not render.`,\n        `    ${finding.reason}`,\n      );\n    } else if (finding.kind === 'unexplained-opt-out') {\n      lines.push(\n        `  ${finding.file}`,\n        '    Opts out of the API reference without a reason. Write one after the marker.',\n      );\n    } else {\n      lines.push(\n        `  ${finding.file}`,\n        '    Opts out of the API reference and then has one. Remove the stale marker.',\n      );\n    }\n  }\n\n  const tally =\n    `${result.okCount} documented, ${result.exemptCount} exempt, ` +\n    `${result.skippedCount} without a preview`;\n\n  if (result.findings.length === 0) {\n    return `All documentation pages that show a component document it (${tally}).`;\n  }\n\n  return (\n    `${result.findings.length} documentation page(s) need attention:\\n` +\n    `${lines.join('\\n')}\\n\\n${tally}`\n  );\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olwiba/dx",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -52,16 +52,46 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "bun test",
-    "tsc": "tsc --noEmit"
+    "tsc": "tsc --noEmit",
+    "web:build": "fumadocs-mdx && vite build",
+    "web:dev": "fumadocs-mdx && vite dev",
+    "start": "bun run server.ts",
+    "types:check": "fumadocs-mdx && tsc --noEmit && tsc --noEmit -p tsconfig.site.json",
+    "presets:generate": "bun scripts/generate-env-presets.ts",
+    "docs:check": "bun src/cli.ts docs-check",
+    "env:check": "bun src/cli.ts env-check",
+    "showcase:build": "bun scripts/build-showcase.ts"
   },
   "devDependencies": {
+    "@olwiba/cn": "0.1.41",
+    "@olwiba/docs": "0.1.47",
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/react-router": "1.154.8",
+    "@tanstack/react-start": "1.154.8",
+    "@types/mdx": "^2.0.13",
     "@types/node": "^22.5.4",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^4.6.0",
     "eslint": "^9.39.5",
+    "fumadocs-core": "^16.4.7",
+    "fumadocs-mdx": "^14.2.6",
+    "fumadocs-ui": "^16.4.7",
+    "lucide-react": "^0.562.0",
     "lucide-static": "^0.488.0",
+    "next-themes": "^0.4.6",
     "puppeteer-core": "^25.9.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "rehype-pretty-code": "^0.14.0",
     "sharp": "^0.35.0",
+    "shiki": "^3.0.0",
+    "tailwindcss": "^4.1.18",
     "tsup": "^8.4.0",
-    "typescript": "^5.7.2"
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.7.2",
+    "vite": "^7.3.1",
+    "vite-tsconfig-paths": "^5.1.4"
   },
   "peerDependencies": {
     "@typescript-eslint/eslint-plugin": ">=8.0.0",