@olwiba/dx 0.0.27 → 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

@@ -2402,13 +2402,14 @@ function checkEnv({
   const findings = [];
   let okCount = 0;
   for (const key of exampleKeys) {
+    const exampleDeclaresValue = exampleEnv.keys.get(key) === true;
+    const isOptional = optionalSet.has(key) || !exampleDeclaresValue;
     if (!actualEnv.keys.has(key)) {
-      if (!optionalSet.has(key)) findings.push({ kind: "missing", key });
+      if (!isOptional) findings.push({ kind: "missing", key });
       continue;
     }
     const hasValue = actualEnv.keys.get(key) === true;
-    const exampleHasValue = exampleEnv.keys.get(key) === true;
-    if (!hasValue && exampleHasValue && !optionalSet.has(key)) {
+    if (!hasValue && !isOptional) {
       findings.push({ kind: "empty", key });
       continue;
     }
@@ -2486,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);
@@ -2512,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() {
@@ -2772,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/dist/env-check.js

@@ -41,13 +41,14 @@ function checkEnv({
   const findings = [];
   let okCount = 0;
   for (const key of exampleKeys) {
+    const exampleDeclaresValue = exampleEnv.keys.get(key) === true;
+    const isOptional = optionalSet.has(key) || !exampleDeclaresValue;
     if (!actualEnv.keys.has(key)) {
-      if (!optionalSet.has(key)) findings.push({ kind: "missing", key });
+      if (!isOptional) findings.push({ kind: "missing", key });
       continue;
     }
     const hasValue = actualEnv.keys.get(key) === true;
-    const exampleHasValue = exampleEnv.keys.get(key) === true;
-    if (!hasValue && exampleHasValue && !optionalSet.has(key)) {
+    if (!hasValue && !isOptional) {
       findings.push({ kind: "empty", key });
       continue;
     }

package/dist/env-check.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/env-check.ts"],"names":[],"mappings":";AAyCO,SAAS,SAAS,MAAA,EAA2B;AAClD,EAAA,MAAM,IAAA,uBAAW,GAAA,EAAqB;AACtC,EAAA,MAAM,aAAuB,EAAC;AAC9B,EAAA,MAAM,YAAmD,EAAC;AAE1D,EAAA,MAAA,CAAO,MAAM,OAAO,CAAA,CAAE,OAAA,CAAQ,CAAC,KAAK,KAAA,KAAU;AAC5C,IAAA,MAAM,IAAA,GAAO,IAAI,IAAA,EAAK;AACtB,IAAA,IAAI,IAAA,KAAS,EAAA,IAAM,IAAA,CAAK,UAAA,CAAW,GAAG,CAAA,EAAG;AAGzC,IAAA,MAAM,aAAA,GAAgB,IAAA,CAAK,OAAA,CAAQ,YAAA,EAAc,EAAE,CAAA;AACnD,IAAA,MAAM,EAAA,GAAK,aAAA,CAAc,OAAA,CAAQ,GAAG,CAAA;AAEpC,IAAA,IAAI,MAAM,CAAA,EAAG;AAGX,MAAA,SAAA,CAAU,IAAA,CAAK,EAAE,IAAA,EAAM,KAAA,GAAQ,CAAA,EAAG,IAAA,EAAM,aAAA,CAAc,KAAA,CAAM,CAAA,EAAG,EAAE,CAAA,EAAG,CAAA;AACpE,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,MAAM,aAAA,CAAc,KAAA,CAAM,CAAA,EAAG,EAAE,EAAE,IAAA,EAAK;AAC5C,IAAA,MAAM,QAAQ,aAAA,CAAc,KAAA,CAAM,EAAA,GAAK,CAAC,EAAE,IAAA,EAAK;AAE/C,IAAA,IAAI,KAAK,GAAA,CAAI,GAAG,CAAA,EAAG,UAAA,CAAW,KAAK,GAAG,CAAA;AAEtC,IAAA,IAAA,CAAK,IAAI,GAAA,EAAK,KAAA,KAAU,MAAM,KAAA,KAAU,IAAA,IAAQ,UAAU,IAAI,CAAA;AAAA,EAChE,CAAC,CAAA;AAED,EAAA,OAAO,EAAE,IAAA,EAAM,UAAA,EAAY,SAAA,EAAU;AACvC;AAUA,SAAS,mBAAA,CAAoB,YAAoB,SAAA,EAAyC;AACxF,EAAA,MAAM,SAAA,GAAY,CAAC,GAAA,KAAgB,GAAA,CAAI,QAAQ,aAAA,EAAe,EAAE,EAAE,WAAA,EAAY;AAC9E,EAAA,MAAM,MAAA,GAAS,UAAU,UAAU,CAAA;AAEnC,EAAA,OAAO,SAAA,CAAU,IAAA,CAAK,CAAC,KAAA,KAAU;AAC/B,IAAA,MAAM,SAAA,GAAY,UAAU,KAAK,CAAA;AACjC,IAAA,IAAI,SAAA,KAAc,QAAQ,OAAO,IAAA;AAEjC,IAAA,OACE,SAAA,CAAU,UAAU,CAAA,KACnB,MAAA,CAAO,SAAS,SAAS,CAAA,IAAK,MAAA,CAAO,UAAA,CAAW,SAAS,CAAA,CAAA;AAAA,EAE9D,CAAC,CAAA;AACH;AAEO,SAAS,QAAA,CAAS;AAAA,EACvB,OAAA;AAAA,EACA,MAAA;AAAA;AAAA,EAEA,WAAW;AACb,CAAA,EAImB;AACjB,EAAA,MAAM,UAAA,GAAa,SAAS,OAAO,CAAA;AACnC,EAAA,MAAM,SAAA,GAAY,SAAS,MAAM,CAAA;AACjC,EAAA,MAAM,WAAA,GAAc,IAAI,GAAA,CAAI,QAAQ,CAAA;AAEpC,EAAA,MAAM,cAAc,CAAC,GAAG,UAAA,CAAW,IAAA,CAAK,MAAM,CAAA;AAC9C,EAAA,MAAM,WAAyB,EAAC;AAChC,EAAA,IAAI,OAAA,GAAU,CAAA;AAEd,EAAA,KAAA,MAAW,OAAO,WAAA,EAAa;AAC7B,IAAA,IAAI,CAAC,SAAA,CAAU,IAAA,CAAK,GAAA,CAAI,GAAG,CAAA,EAAG;AAC5B,MAAA,IAAI,CAAC,WAAA,CAAY,GAAA,CAAI,GAAG,CAAA,EAAG,QAAA,CAAS,IAAA,CAAK,EAAE,IAAA,EAAM,SAAA,EAAW,GAAA,EAAK,CAAA;AACjE,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,QAAA,GAAW,SAAA,CAAU,IAAA,CAAK,GAAA,CAAI,GAAG,CAAA,KAAM,IAAA;AAC7C,IAAA,MAAM,eAAA,GAAkB,UAAA,CAAW,IAAA,CAAK,GAAA,CAAI,GAAG,CAAA,KAAM,IAAA;AAIrD,IAAA,IAAI,CAAC,QAAA,IAAY,eAAA,IAAmB,CAAC,WAAA,CAAY,GAAA,CAAI,GAAG,CAAA,EAAG;AACzD,MAAA,QAAA,CAAS,IAAA,CAAK,EAAE,IAAA,EAAM,OAAA,EAAS,KAAK,CAAA;AACpC,MAAA;AAAA,IACF;AAEA,IAAA,OAAA,IAAW,CAAA;AAAA,EACb;AAEA,EAAA,KAAA,MAAW,GAAA,IAAO,SAAA,CAAU,IAAA,CAAK,IAAA,EAAK,EAAG;AACvC,IAAA,IAAI,UAAA,CAAW,IAAA,CAAK,GAAA,CAAI,GAAG,CAAA,EAAG;AAE9B,IAAA,MAAM,SAAA,GAAY,mBAAA,CAAoB,GAAA,EAAK,WAAW,CAAA;AACtD,IAAA,QAAA,CAAS,IAAA,CAAK,SAAA,GAAY,EAAE,IAAA,EAAM,SAAA,EAAW,GAAA,EAAK,SAAA,EAAU,GAAI,EAAE,IAAA,EAAM,SAAA,EAAW,GAAA,EAAK,CAAA;AAAA,EAC1F;AAEA,EAAA,KAAA,MAAW,GAAA,IAAO,UAAU,UAAA,EAAY,QAAA,CAAS,KAAK,EAAE,IAAA,EAAM,WAAA,EAAa,GAAA,EAAK,CAAA;AAChF,EAAA,KAAA,MAAW,IAAA,IAAQ,SAAA,CAAU,SAAA,EAAW,QAAA,CAAS,IAAA,CAAK,EAAE,IAAA,EAAM,WAAA,EAAa,GAAG,IAAA,EAAM,CAAA;AAEpF,EAAA,OAAO;AAAA,IACL,QAAA;AAAA,IACA,OAAA;AAAA,IACA,YAAA,EAAc,WAAW,IAAA,CAAK,IAAA;AAAA,IAC9B,WAAA,EAAa,UAAU,IAAA,CAAK;AAAA,GAC9B;AACF;AAEA,IAAM,KAAA,GAA8B;AAAA,EAClC,SAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA,WAAA;AAAA,EACA,WAAA;AAAA,EACA;AACF,CAAA;AAEA,IAAM,MAAA,GAA6C;AAAA,EACjD,OAAA,EAAS,+CAAA;AAAA,EACT,OAAA,EAAS,SAAA;AAAA,EACT,KAAA,EAAO,mBAAA;AAAA,EACP,SAAA,EAAW,gBAAA;AAAA,EACX,SAAA,EAAW,oBAAA;AAAA,EACX,OAAA,EAAS;AACX,CAAA;AAGO,SAAS,gBAAgB,MAAA,EAAgC;AAC9D,EAAA,MAAM,QAAkB,EAAC;AACzB,EAAA,KAAA,CAAM,IAAA;AAAA,IACJ,CAAA,EAAA,EAAK,OAAO,WAAW,CAAA,sBAAA,EAAyB,OAAO,YAAY,CAAA,iBAAA,EAAoB,OAAO,OAAO,CAAA,QAAA;AAAA,GACvG;AAEA,EAAA,IAAI,MAAA,CAAO,QAAA,CAAS,MAAA,KAAW,CAAA,EAAG;AAChC,IAAA,KAAA,CAAM,KAAK,gDAA2C,CAAA;AACtD,IAAA,OAAO,KAAA,CAAM,KAAK,IAAI,CAAA;AAAA,EACxB;AAEA,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,MAAM,KAAA,GAAQ,OAAO,QAAA,CAAS,MAAA,CAAO,CAAC,OAAA,KAAY,OAAA,CAAQ,SAAS,IAAI,CAAA;AACvE,IAAA,IAAI,KAAA,CAAM,WAAW,CAAA,EAAG;AAExB,IAAA,KAAA,CAAM,IAAA,CAAK;AAAA,EAAK,MAAA,CAAO,IAAI,CAAC,CAAA,CAAA,CAAG,CAAA;AAC/B,IAAA,KAAA,MAAW,WAAW,KAAA,EAAO;AAC3B,MAAA,IAAI,OAAA,CAAQ,SAAS,SAAA,EAAW;AAC9B,QAAA,KAAA,CAAM,KAAK,CAAA,SAAA,EAAO,OAAA,CAAQ,GAAG,CAAA,uBAAA,EAAqB,OAAA,CAAQ,SAAS,CAAA,CAAA,CAAG,CAAA;AAAA,MACxE,CAAA,MAAA,IAAW,OAAA,CAAQ,IAAA,KAAS,WAAA,EAAa;AACvC,QAAA,KAAA,CAAM,KAAK,CAAA,cAAA,EAAY,OAAA,CAAQ,IAAI,CAAA,EAAA,EAAK,OAAA,CAAQ,IAAI,CAAA,MAAA,CAAG,CAAA;AAAA,MACzD,CAAA,MAAO;AACL,QAAA,KAAA,CAAM,IAAA,CAAK,CAAA,SAAA,EAAO,OAAA,CAAQ,GAAG,CAAA,CAAE,CAAA;AAAA,MACjC;AAAA,IACF;AAAA,EACF;AAGA,EAAA,MAAM,OAAA,GAAU,OAAO,QAAA,CAAS,MAAA,CAAO,CAAC,OAAA,KAAY,OAAA,CAAQ,IAAA,KAAS,SAAS,CAAA,CAAE,MAAA;AAChF,EAAA,IAAI,UAAU,CAAA,EAAG;AACf,IAAA,KAAA,CAAM,IAAA;AAAA,MACJ;AAAA,EAAK,OAAO,CAAA;AAAA,4DAAA;AAAA,KAEd;AAAA,EACF;AAEA,EAAA,KAAA,CAAM,IAAA,CAAK;AAAA,YAAA,EAAY,MAAA,CAAO,QAAA,CAAS,MAAM,CAAA,YAAA,CAAc,CAAA;AAC3D,EAAA,OAAO,KAAA,CAAM,KAAK,IAAI,CAAA;AACxB","file":"env-check.js","sourcesContent":["/**\n * Compares a real environment against the example that documents it.\n *\n * Pure string comparison, deliberately. The input is a file full of live\n * credentials, so it is never sent anywhere, never written to disk, and never\n * echoed back — the report names keys and says nothing about values.\n *\n * `.env.example` is the schema. Every repository already has one, which is what\n * makes this usable outside the repositories that have a typed schema, and\n * those are exactly the ones where environments have been rotting unnoticed.\n */\n\nexport type EnvFinding =\n  | { kind: 'missing'; key: string }\n  | { kind: 'unknown'; key: string }\n  | { kind: 'renamed'; key: string; looksLike: string }\n  | { kind: 'empty'; key: string }\n  | { kind: 'malformed'; line: number; text: string }\n  | { kind: 'duplicate'; key: string };\n\nexport interface EnvCheckResult {\n  findings: EnvFinding[];\n  /** Keys present in both, non-empty. Counted, never listed. */\n  okCount: number;\n  exampleCount: number;\n  actualCount: number;\n}\n\ninterface ParsedEnv {\n  /** Key to whether it has a non-empty value. Values themselves are discarded. */\n  keys: Map<string, boolean>;\n  duplicates: string[];\n  malformed: Array<{ line: number; text: string }>;\n}\n\n/**\n * Reads keys and discards values immediately.\n *\n * The value never leaves this function, so nothing downstream can leak one by\n * accident — including a future change to the report format.\n */\nexport function parseEnv(source: string): ParsedEnv {\n  const keys = new Map<string, boolean>();\n  const duplicates: string[] = [];\n  const malformed: Array<{ line: number; text: string }> = [];\n\n  source.split(/\\r?\\n/).forEach((raw, index) => {\n    const line = raw.trim();\n    if (line === '' || line.startsWith('#')) return;\n\n    // `export FOO=bar` is valid in a shell-sourced file.\n    const withoutExport = line.replace(/^export\\s+/, '');\n    const eq = withoutExport.indexOf('=');\n\n    if (eq <= 0) {\n      // Reported by line number without the text where it could hold a value:\n      // a line missing its `=` may still be a pasted secret.\n      malformed.push({ line: index + 1, text: withoutExport.slice(0, 24) });\n      return;\n    }\n\n    const key = withoutExport.slice(0, eq).trim();\n    const value = withoutExport.slice(eq + 1).trim();\n\n    if (keys.has(key)) duplicates.push(key);\n    // A later assignment wins in most loaders, so the last one decides.\n    keys.set(key, value !== '' && value !== '\"\"' && value !== \"''\");\n  });\n\n  return { keys, duplicates, malformed };\n}\n\n/**\n * Whether an unrecognised key looks like a renamed version of a known one.\n *\n * This is the finding that matters. A stale key reads as configured — someone\n * scanning the file sees the name they expect in all but a prefix and stops\n * looking — so reporting it as a generic unknown would not tell anyone that the\n * setting it was meant to carry is unset.\n */\nfunction findRenameCandidate(unknownKey: string, knownKeys: string[]): string | undefined {\n  const normalise = (key: string) => key.replace(/[^A-Z0-9]/gi, '').toUpperCase();\n  const target = normalise(unknownKey);\n\n  return knownKeys.find((known) => {\n    const candidate = normalise(known);\n    if (candidate === target) return true;\n    // A prefix or suffix on an otherwise identical name: VITE_FOO against FOO.\n    return (\n      candidate.length >= 6 &&\n      (target.endsWith(candidate) || target.startsWith(candidate))\n    );\n  });\n}\n\nexport function checkEnv({\n  example,\n  actual,\n  /** Keys allowed to be absent, e.g. optional credentials. */\n  optional = [],\n}: {\n  example: string;\n  actual: string;\n  optional?: string[];\n}): EnvCheckResult {\n  const exampleEnv = parseEnv(example);\n  const actualEnv = parseEnv(actual);\n  const optionalSet = new Set(optional);\n\n  const exampleKeys = [...exampleEnv.keys.keys()];\n  const findings: EnvFinding[] = [];\n  let okCount = 0;\n\n  for (const key of exampleKeys) {\n    if (!actualEnv.keys.has(key)) {\n      if (!optionalSet.has(key)) findings.push({ kind: 'missing', key });\n      continue;\n    }\n\n    const hasValue = actualEnv.keys.get(key) === true;\n    const exampleHasValue = exampleEnv.keys.get(key) === true;\n\n    // Blank where the example shows a value: the example is demonstrating that\n    // something belongs there. Blank in both is a deliberate opt-out.\n    if (!hasValue && exampleHasValue && !optionalSet.has(key)) {\n      findings.push({ kind: 'empty', key });\n      continue;\n    }\n\n    okCount += 1;\n  }\n\n  for (const key of actualEnv.keys.keys()) {\n    if (exampleEnv.keys.has(key)) continue;\n\n    const looksLike = findRenameCandidate(key, exampleKeys);\n    findings.push(looksLike ? { kind: 'renamed', key, looksLike } : { kind: 'unknown', key });\n  }\n\n  for (const key of actualEnv.duplicates) findings.push({ kind: 'duplicate', key });\n  for (const line of actualEnv.malformed) findings.push({ kind: 'malformed', ...line });\n\n  return {\n    findings,\n    okCount,\n    exampleCount: exampleEnv.keys.size,\n    actualCount: actualEnv.keys.size,\n  };\n}\n\nconst ORDER: EnvFinding['kind'][] = [\n  'renamed',\n  'missing',\n  'empty',\n  'malformed',\n  'duplicate',\n  'unknown',\n];\n\nconst LABELS: Record<EnvFinding['kind'], string> = {\n  renamed: 'Renamed — set under a name nothing reads',\n  missing: 'Missing',\n  empty: 'Present but empty',\n  malformed: 'Malformed line',\n  duplicate: 'Set more than once',\n  unknown: 'Unknown — not in the example',\n};\n\n/** Formats a report. Contains key names and counts only, never a value. */\nexport function formatEnvReport(result: EnvCheckResult): string {\n  const lines: string[] = [];\n  lines.push(\n    `  ${result.actualCount} keys checked against ${result.exampleCount} in the example, ${result.okCount} correct`,\n  );\n\n  if (result.findings.length === 0) {\n    lines.push('\\nPASS — environment matches the example.');\n    return lines.join('\\n');\n  }\n\n  for (const kind of ORDER) {\n    const group = result.findings.filter((finding) => finding.kind === kind);\n    if (group.length === 0) continue;\n\n    lines.push(`\\n${LABELS[kind]}:`);\n    for (const finding of group) {\n      if (finding.kind === 'renamed') {\n        lines.push(`  ✗ ${finding.key}  →  did you mean ${finding.looksLike}?`);\n      } else if (finding.kind === 'malformed') {\n        lines.push(`  ✗ line ${finding.line}: ${finding.text}…`);\n      } else {\n        lines.push(`  ✗ ${finding.key}`);\n      }\n    }\n  }\n\n  // Renames are called out because they are the ones that read as configured.\n  const renamed = result.findings.filter((finding) => finding.kind === 'renamed').length;\n  if (renamed > 0) {\n    lines.push(\n      `\\n${renamed} key(s) look renamed. The setting they were meant to carry is unset,` +\n        '\\nwhich usually means a default is in force that nobody chose.',\n    );\n  }\n\n  lines.push(`\\nFAIL — ${result.findings.length} finding(s).`);\n  return lines.join('\\n');\n}\n"]}
+{"version":3,"sources":["../src/env-check.ts"],"names":[],"mappings":"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","file":"env-check.js","sourcesContent":["/**\n * Compares a real environment against the example that documents it.\n *\n * Pure string comparison, deliberately. The input is a file full of live\n * credentials, so it is never sent anywhere, never written to disk, and never\n * echoed back — the report names keys and says nothing about values.\n *\n * `.env.example` is the schema. Every repository already has one, which is what\n * makes this usable outside the repositories that have a typed schema, and\n * those are exactly the ones where environments have been rotting unnoticed.\n */\n\nexport type EnvFinding =\n  | { kind: 'missing'; key: string }\n  | { kind: 'unknown'; key: string }\n  | { kind: 'renamed'; key: string; looksLike: string }\n  | { kind: 'empty'; key: string }\n  | { kind: 'malformed'; line: number; text: string }\n  | { kind: 'duplicate'; key: string };\n\nexport interface EnvCheckResult {\n  findings: EnvFinding[];\n  /** Keys present in both, non-empty. Counted, never listed. */\n  okCount: number;\n  exampleCount: number;\n  actualCount: number;\n}\n\ninterface ParsedEnv {\n  /** Key to whether it has a non-empty value. Values themselves are discarded. */\n  keys: Map<string, boolean>;\n  duplicates: string[];\n  malformed: Array<{ line: number; text: string }>;\n}\n\n/**\n * Reads keys and discards values immediately.\n *\n * The value never leaves this function, so nothing downstream can leak one by\n * accident — including a future change to the report format.\n */\nexport function parseEnv(source: string): ParsedEnv {\n  const keys = new Map<string, boolean>();\n  const duplicates: string[] = [];\n  const malformed: Array<{ line: number; text: string }> = [];\n\n  source.split(/\\r?\\n/).forEach((raw, index) => {\n    const line = raw.trim();\n    if (line === '' || line.startsWith('#')) return;\n\n    // `export FOO=bar` is valid in a shell-sourced file.\n    const withoutExport = line.replace(/^export\\s+/, '');\n    const eq = withoutExport.indexOf('=');\n\n    if (eq <= 0) {\n      // Reported by line number without the text where it could hold a value:\n      // a line missing its `=` may still be a pasted secret.\n      malformed.push({ line: index + 1, text: withoutExport.slice(0, 24) });\n      return;\n    }\n\n    const key = withoutExport.slice(0, eq).trim();\n    const value = withoutExport.slice(eq + 1).trim();\n\n    if (keys.has(key)) duplicates.push(key);\n    // A later assignment wins in most loaders, so the last one decides.\n    keys.set(key, value !== '' && value !== '\"\"' && value !== \"''\");\n  });\n\n  return { keys, duplicates, malformed };\n}\n\n/**\n * Whether an unrecognised key looks like a renamed version of a known one.\n *\n * This is the finding that matters. A stale key reads as configured — someone\n * scanning the file sees the name they expect in all but a prefix and stops\n * looking — so reporting it as a generic unknown would not tell anyone that the\n * setting it was meant to carry is unset.\n */\nfunction findRenameCandidate(unknownKey: string, knownKeys: string[]): string | undefined {\n  const normalise = (key: string) => key.replace(/[^A-Z0-9]/gi, '').toUpperCase();\n  const target = normalise(unknownKey);\n\n  return knownKeys.find((known) => {\n    const candidate = normalise(known);\n    if (candidate === target) return true;\n    // A prefix or suffix on an otherwise identical name: VITE_FOO against FOO.\n    return (\n      candidate.length >= 6 &&\n      (target.endsWith(candidate) || target.startsWith(candidate))\n    );\n  });\n}\n\nexport function checkEnv({\n  example,\n  actual,\n  /** Keys allowed to be absent, e.g. optional credentials. */\n  optional = [],\n}: {\n  example: string;\n  actual: string;\n  optional?: string[];\n}): EnvCheckResult {\n  const exampleEnv = parseEnv(example);\n  const actualEnv = parseEnv(actual);\n  const optionalSet = new Set(optional);\n\n  const exampleKeys = [...exampleEnv.keys.keys()];\n  const findings: EnvFinding[] = [];\n  let okCount = 0;\n\n  for (const key of exampleKeys) {\n    // A blank in the example is the example saying this slot is optional — it\n    // is showing the name without claiming a value belongs there. Absent then\n    // means the same as blank, and reporting it drowns the real findings in\n    // unset credentials for services this deployment does not use.\n    const exampleDeclaresValue = exampleEnv.keys.get(key) === true;\n    const isOptional = optionalSet.has(key) || !exampleDeclaresValue;\n\n    if (!actualEnv.keys.has(key)) {\n      if (!isOptional) findings.push({ kind: 'missing', key });\n      continue;\n    }\n\n    const hasValue = actualEnv.keys.get(key) === true;\n\n    // Blank where the example shows a value: the example is demonstrating that\n    // something belongs there. Blank in both is a deliberate opt-out.\n    if (!hasValue && !isOptional) {\n      findings.push({ kind: 'empty', key });\n      continue;\n    }\n\n    okCount += 1;\n  }\n\n  for (const key of actualEnv.keys.keys()) {\n    if (exampleEnv.keys.has(key)) continue;\n\n    const looksLike = findRenameCandidate(key, exampleKeys);\n    findings.push(looksLike ? { kind: 'renamed', key, looksLike } : { kind: 'unknown', key });\n  }\n\n  for (const key of actualEnv.duplicates) findings.push({ kind: 'duplicate', key });\n  for (const line of actualEnv.malformed) findings.push({ kind: 'malformed', ...line });\n\n  return {\n    findings,\n    okCount,\n    exampleCount: exampleEnv.keys.size,\n    actualCount: actualEnv.keys.size,\n  };\n}\n\nconst ORDER: EnvFinding['kind'][] = [\n  'renamed',\n  'missing',\n  'empty',\n  'malformed',\n  'duplicate',\n  'unknown',\n];\n\nconst LABELS: Record<EnvFinding['kind'], string> = {\n  renamed: 'Renamed — set under a name nothing reads',\n  missing: 'Missing',\n  empty: 'Present but empty',\n  malformed: 'Malformed line',\n  duplicate: 'Set more than once',\n  unknown: 'Unknown — not in the example',\n};\n\n/** Formats a report. Contains key names and counts only, never a value. */\nexport function formatEnvReport(result: EnvCheckResult): string {\n  const lines: string[] = [];\n  lines.push(\n    `  ${result.actualCount} keys checked against ${result.exampleCount} in the example, ${result.okCount} correct`,\n  );\n\n  if (result.findings.length === 0) {\n    lines.push('\\nPASS — environment matches the example.');\n    return lines.join('\\n');\n  }\n\n  for (const kind of ORDER) {\n    const group = result.findings.filter((finding) => finding.kind === kind);\n    if (group.length === 0) continue;\n\n    lines.push(`\\n${LABELS[kind]}:`);\n    for (const finding of group) {\n      if (finding.kind === 'renamed') {\n        lines.push(`  ✗ ${finding.key}  →  did you mean ${finding.looksLike}?`);\n      } else if (finding.kind === 'malformed') {\n        lines.push(`  ✗ line ${finding.line}: ${finding.text}…`);\n      } else {\n        lines.push(`  ✗ ${finding.key}`);\n      }\n    }\n  }\n\n  // Renames are called out because they are the ones that read as configured.\n  const renamed = result.findings.filter((finding) => finding.kind === 'renamed').length;\n  if (renamed > 0) {\n    lines.push(\n      `\\n${renamed} key(s) look renamed. The setting they were meant to carry is unset,` +\n        '\\nwhich usually means a default is in force that nobody chose.',\n    );\n  }\n\n  lines.push(`\\nFAIL — ${result.findings.length} finding(s).`);\n  return lines.join('\\n');\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olwiba/dx",
-  "version": "0.0.27",
+  "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",