@writedocs/generator 0.1.0 → 0.2.1

package/src/lib/config-schema.js

@@ -0,0 +1,485 @@
+import { z } from "zod";
+const navPageSchema = z.string();
+const navGroupPagesSchema = z.lazy(
+  () => z.object({
+    group: z.string(),
+    page: z.string().optional(),
+    pages: z.array(navItemSchema)
+  }).strict()
+);
+const navGroupOpenApiSchema = z.object({
+  group: z.string(),
+  openapi: z.object({
+    // Path to an OpenAPI 3.x spec, relative to the content directory
+    // (alongside writedocs.json) - same convention the old top-level
+    // `openapi` field used. See generate-api-pages.js (the pre-Astro
+    // build/dev step that actually parses this and writes the
+    // manifest/operation JSON this group's pages are expanded from).
+    src: z.string(),
+    // Base URL path every page generated from this spec is namespaced
+    // under, e.g. "/api" -> pages served at /api/<tag>/<operation>/.
+    // Also doubles as this spec's own unique key under
+    // writedocsTempDir()'s openapi/<path>/ directory (manifest.json + operations/*.json),
+    // so two openapi groups in the same writedocs.json must use different
+    // `path` values - generate-api-pages.js throws a clear error if
+    // they collide.
+    path: z.string()
+  }).strict()
+}).strict();
+const navGroupSchema = z.union([navGroupPagesSchema, navGroupOpenApiSchema]);
+const navLinkSchema = z.object({ label: z.string(), href: z.string() }).strict();
+const navItemSchema = z.lazy(
+  () => z.union([navPageSchema, navGroupSchema, navLinkSchema])
+);
+function withChildren(base) {
+  return z.union([
+    z.object({ ...base, pages: z.array(navItemSchema) }).strict(),
+    z.object({ ...base, tabs: z.array(tabSchema).min(1) }).strict(),
+    z.object({ ...base, versions: z.array(versionSchema).min(1) }).strict(),
+    z.object({ ...base, languages: z.array(languageSchema).min(1) }).strict(),
+    z.object({ ...base, dropdowns: z.array(dropdownSchema).min(1) }).strict(),
+    z.object({ ...base, products: z.array(productSchema).min(1) }).strict(),
+    z.object({ ...base, href: z.string() }).strict()
+  ]);
+}
+const tabSchema = z.lazy(
+  () => withChildren({ tab: z.string(), icon: z.string().optional() })
+);
+const versionSchema = z.lazy(
+  () => withChildren({
+    version: z.string(),
+    label: z.string().optional(),
+    tag: z.string().optional(),
+    default: z.boolean().optional()
+  })
+);
+const languageSchema = z.lazy(
+  () => withChildren({ language: z.string(), label: z.string().optional() })
+);
+const dropdownSchema = z.lazy(
+  () => withChildren({ dropdown: z.string(), icon: z.string().optional() })
+);
+const productSchema = z.lazy(
+  () => withChildren({ product: z.string(), icon: z.string().optional(), description: z.string().optional() })
+);
+const globalSchema = z.object({ dropdowns: z.array(dropdownSchema).min(1) });
+const navigationSchema = z.union([
+  z.array(navItemSchema),
+  z.object({ global: globalSchema.optional(), tabs: z.array(tabSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), versions: z.array(versionSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), languages: z.array(languageSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), dropdowns: z.array(dropdownSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), products: z.array(productSchema).min(1) }).strict()
+]);
+const DEFAULT_PRIMARY = "#6366f1";
+const logoSchema = z.union([
+  z.string(),
+  z.object({ light: z.string().optional(), dark: z.string().optional(), label: z.string().optional() }).strict()
+]);
+const navbarColorValueSchema = z.union([
+  z.string(),
+  z.object({
+    background: z.string(),
+    accent: z.string().optional()
+  }).strict()
+]);
+const fontVariantSchema = z.object({
+  family: z.string(),
+  weight: z.number().optional(),
+  source: z.string().optional(),
+  format: z.enum(["woff", "woff2"]).optional()
+}).strict();
+const fontsSchema = z.object({
+  family: z.string(),
+  weight: z.number().optional(),
+  source: z.string().optional(),
+  format: z.enum(["woff", "woff2"]).optional(),
+  heading: fontVariantSchema.optional(),
+  body: fontVariantSchema.optional()
+}).strict();
+const stylesSchema = z.object({
+  colors: z.object({
+    primary: z.string().default(DEFAULT_PRIMARY),
+    text: z.string().optional(),
+    dark: z.object({
+      primary: z.string().optional(),
+      text: z.string().optional()
+    }).optional()
+  }).default({ primary: DEFAULT_PRIMARY }),
+  logo: logoSchema.optional(),
+  favicon: z.string().optional(),
+  // No default value here (unlike `colors.primary`'s DEFAULT_PRIMARY) -
+  // resolveFonts() below is where "Inter" actually gets applied as the
+  // site-wide default whenever this field is left unset entirely, so
+  // that fallback lives in one place alongside the rest of the
+  // resolution logic rather than being duplicated as a schema default
+  // *and* a resolver fallback.
+  fonts: fontsSchema.optional(),
+  // The Shiki theme *name* (not a full theme object/JSON - see
+  // https://shiki.style/themes for the built-in list) each fenced
+  // (```) MDX code block, and the API playground's request/response
+  // snippets, use in light/dark mode - read out of writedocs.json by both
+  // astro.config.mjs (Shiki's dual-theme markdown config) and
+  // ApiReferencePanel.astro (its own separate <Code/> usages, which
+  // don't inherit markdown.shikiConfig) via resolveCodeblockTheme()
+  // below, the single source of truth for the 'github-light'/
+  // 'github-dark' fallback. Left per-key optional (not defaulted in
+  // the schema itself) so a site can override just one side (e.g.
+  // only `dark`) and still get the ordinary default for the other.
+  codeblocks: z.object({
+    light: z.string().optional(),
+    dark: z.string().optional(),
+    // Maps a fenced (```) block's own language tag to whichever real
+    // Shiki grammar actually highlights it, before that tag ever
+    // reaches Shiki - see resolveCodeblockLangAlias() below for the
+    // one built-in entry (mdx -> jsx) this ships with by default and
+    // why. A site can add its own entries for any other language tag
+    // that either doesn't tokenize well under its own grammar, or
+    // that a site wants to write under a shorter/friendlier fence tag
+    // than Shiki's own bundled id (e.g. `groovy: 'java'` for a close-
+    // enough approximation Shiki doesn't ship a dedicated grammar for
+    // at all) - merged with, not replacing, the built-in default, so
+    // adding one of a site's own doesn't require re-declaring mdx.
+    langAlias: z.record(z.string(), z.string()).optional()
+  }).strict().optional(),
+  // The topbar's own background, independent of `background` below (the
+  // page's) - a site may want its navbar to stand out (a dark or
+  // brand-colored bar over a light page) rather than blend into the
+  // page, which is the default when this is left unset. Same {light,
+  // dark} shape (and same per-key-optional, not defaulted here) as
+  // `codeblocks` right above, rather than nested under `colors` - it's a
+  // topbar-specific override, not a third general-purpose page color, so
+  // it reads more like "one more themed surface" alongside codeblocks
+  // than a sibling of primary/text. BaseLayout.astro's own
+  // lightNavbarBg/darkNavbarBg resolution is what falls each side back
+  // to the page background when unset.
+  //
+  // Each side (`light`/`dark`) is either a bare string - just the
+  // background color, exactly the original shape, kept for backwards
+  // compatibility - or `{ background, accent? }`, for when a site also
+  // wants the navbar's own active-tab-fill/hover-underline color to
+  // differ from the sitewide `styles.colors.primary` (`accent`'s only
+  // job - see BaseLayout.astro's lightNavbarAccent). Deliberately no
+  // text/icon color field here at all: BaseLayout.astro always resolves
+  // the navbar's plain text/icon color itself, picking black or white by
+  // contrast against whatever `background` resolves to
+  // (contrastTextColor() below) the moment this field is configured at
+  // all (string or object) - never a value read from writedocs.json. A
+  // manually-set text color is a legibility footgun a site author can
+  // get wrong (or drift out of sync after later changing `background`
+  // without remembering to update it too) in a way "compute it
+  // correctly, every time" simply can't - there's no legitimate reason
+  // to want *illegible* navbar text, unlike `accent`, which is a real
+  // aesthetic choice. Real bug this fixes: a site setting `navbar.light`
+  // to the same value as `colors.primary` (a plausible thing to reach
+  // for - "brand-colored navbar") made every topbar label/icon/link
+  // render in the default near-black text color against that same
+  // saturated background, all but unreadable - and an earlier version of
+  // this feature that let a writedocs.json-supplied color double as the text
+  // color reintroduced the identical bug one level down, just requiring
+  // one more (still guessable-wrong) field to trigger it.
+  navbar: z.object({
+    light: navbarColorValueSchema.optional(),
+    dark: navbarColorValueSchema.optional()
+  }).strict().optional(),
+  // The single place to configure any background color: `colors` is a
+  // solid color (falls back to '#ffffff'/'#0b1120' when unset - see
+  // BaseLayout.astro's lightBackground/darkBackground resolution), and
+  // `images` layers an image on top of it (or is the whole background
+  // by itself, if `colors` is left at its default). This one pair now
+  // drives everything background-related site-wide - --wd-background
+  // (dropdowns/modals/kbd chips/footer/topbar-fallback/etc., see every
+  // `var(--wd-background)` call site) *and* the <body> canvas behind the
+  // main/toc columns - rather than the two being independently
+  // configurable fields that happened to look alike but didn't affect
+  // the same things (see this schema's own comment on `colors.dark`
+  // above for why that split was removed). Both are per-mode optional,
+  // same "only specify what differs" pattern as codeblocks/navbar above.
+  // The topbar and footer still get their own explicit opaque
+  // background (topbar.css/footer.css) specifically so an `images`
+  // background doesn't show through them; see those files' own
+  // comments. The sidebar column has no background of its own (base.css)
+  // and lets it show through, same as the main/toc columns.
+  background: z.object({
+    colors: z.object({
+      light: z.string().optional(),
+      dark: z.string().optional()
+    }).strict().optional(),
+    images: z.object({
+      light: z.string().optional(),
+      dark: z.string().optional()
+    }).strict().optional()
+  }).strict().optional()
+}).default({ colors: { primary: DEFAULT_PRIMARY } });
+const topbarLinkSchema = z.object({
+  label: z.string().optional(),
+  href: z.string(),
+  // Same string shape as every other writedocs.json `icon` field (a plain
+  // Lucide name, or the explicit "collection:icon-name" form for
+  // anything else - see resolveIcon()/AppIcon.astro) - not documented
+  // again here since that convention is already established elsewhere
+  // in this file (tabs/switchers/socials all take the identical shape).
+  icon: z.string().optional()
+}).strict().refine((link) => Boolean(link.label) || Boolean(link.icon), {
+  message: 'Each topbar.links/footer column link needs a "label", an "icon", or both - a link with neither has nothing to render.'
+});
+const footerColumnSchema = z.object({
+  title: z.string().optional(),
+  links: z.array(topbarLinkSchema).default([])
+}).strict();
+const footerSchema = z.object({
+  columns: z.array(footerColumnSchema).default([]),
+  logo: logoSchema.optional()
+}).strict().default({ columns: [] });
+const seoFieldsSchema = z.object({
+  // Open Graph / Twitter card image - a relative path (resolved against
+  // `domain` below into an absolute URL, since most social crawlers
+  // require one) or an already-absolute https:// URL.
+  ogImage: z.string().optional(),
+  // og:type - "website" for most pages, "article" for blog-post-shaped
+  // content, etc. Defaults to "website" if never set anywhere.
+  ogType: z.string().optional(),
+  twitterCard: z.enum(["summary", "summary_large_image"]).optional(),
+  keywords: z.array(z.string()).optional(),
+  // Renders <meta name="robots" content="noindex, nofollow" /> and
+  // (see astro.config.mjs's sitemap `filter`) excludes the page from
+  // sitemap.xml entirely - both driven off this one flag, since listing
+  // a page in the sitemap while also telling crawlers not to index it
+  // would be self-contradictory.
+  noindex: z.boolean().optional()
+}).strict();
+function mergeSeo(site, page) {
+  if (!page) return site;
+  return {
+    ogImage: page.ogImage ?? site.ogImage,
+    ogType: page.ogType ?? site.ogType,
+    twitterCard: page.twitterCard ?? site.twitterCard,
+    keywords: page.keywords ?? site.keywords,
+    noindex: page.noindex ?? site.noindex
+  };
+}
+const apiSchema = z.object({
+  // Whether the Try-it modal's Send button routes its request through
+  // writedocs' own CORS proxy (https://proxy.writechoice.io/) rather
+  // than calling the API directly from the browser. Almost no
+  // real-world API sends back Access-Control-Allow-Origin headers
+  // permitting an arbitrary docs site's origin, so a direct browser
+  // fetch() from the Try-it modal fails for most real APIs without
+  // this - see PROXY_BASE_URL in ApiReferencePanel.astro for the
+  // actual request-forwarding logic. Defaults to enabled; a site can
+  // set this to `false` to always call the API directly instead (the
+  // API is already CORS-permissive, same-origin in some deployments,
+  // or the site owner doesn't want requests routed through a third
+  // party at all).
+  proxy: z.boolean().default(true)
+}).strict().default({ proxy: true });
+const contextMenuSchema = z.object({
+  openIn: z.array(z.enum(["chatgpt", "claude", "perplexity"])).default(["chatgpt", "claude", "perplexity"])
+}).strict();
+const redirectSchema = z.object({
+  source: z.string(),
+  destination: z.string()
+}).strict();
+const bannerSchema = z.object({
+  content: z.string(),
+  // Persisted via localStorage once dismissed (see BaseLayout.astro's
+  // initBanner()) - a static site has no server-side session to track
+  // this against, so "dismissed" only ever means "dismissed in this
+  // browser". A banner without `dismissible` reappears on every visit,
+  // appropriate for something that should stay visible until the site
+  // author removes it from writedocs.json themselves (e.g. "this version is
+  // deprecated"), not something a reader can permanently clear.
+  dismissible: z.boolean().default(false),
+  type: z.enum(["info", "warning", "critical"]).default("info")
+}).strict();
+const notFoundSchema = z.object({
+  title: z.string().optional(),
+  description: z.string().optional()
+}).strict().default({});
+const scriptEntrySchema = z.object({
+  src: z.string().optional(),
+  content: z.string().optional()
+}).strict().refine((v) => v.src ? !v.content : !!v.content, {
+  message: 'Each scripts.head/scripts.body entry needs exactly one of "src" or "content", not both or neither.'
+});
+const scriptsSchema = z.object({
+  head: z.array(scriptEntrySchema).default([]),
+  body: z.array(scriptEntrySchema).default([])
+}).strict().default({ head: [], body: [] });
+const ga4IntegrationSchema = z.object({
+  // A GA4 "Measurement ID", always shaped like "G-XXXXXXXXXX" - not
+  // validated against that shape here, since Google could change the
+  // prefix/length without this schema needing to track it.
+  measurementId: z.string()
+}).strict();
+const googleTagManagerIntegrationSchema = z.object({
+  // A GTM container id, shaped like "GTM-XXXXXXX".
+  containerId: z.string()
+}).strict();
+const plausibleIntegrationSchema = z.object({
+  domain: z.string(),
+  // Plausible's own hosted script URL by default - override for a
+  // self-hosted instance, a reverse-proxy path (Plausible's own
+  // documented way to dodge ad-blockers), or one of Plausible's
+  // documented script *extensions* (e.g.
+  // "https://plausible.io/js/script.hash.outbound-links.js").
+  src: z.string().default("https://plausible.io/js/script.js")
+}).strict();
+const fathomIntegrationSchema = z.object({
+  // Fathom's own short "Site ID", not a full URL or measurement id.
+  siteId: z.string()
+}).strict();
+const posthogIntegrationSchema = z.object({
+  // PostHog calls this a "project API key" (starts with "phc_") in its
+  // own docs - `apiKey` here rather than that exact name, matching this
+  // schema's own plainer naming convention for the equivalent id on
+  // every other provider above.
+  apiKey: z.string(),
+  // PostHog is region-sharded (US/EU) with no single universal default
+  // - "https://us.i.posthog.com" is PostHog's own default for a new
+  // project, but a site on their EU cloud (or a self-hosted instance)
+  // must override this to the host shown in their own project
+  // settings, or events silently go nowhere.
+  apiHost: z.string().default("https://us.i.posthog.com")
+}).strict();
+const umamiIntegrationSchema = z.object({
+  websiteId: z.string(),
+  // Unlike Plausible/PostHog, Umami has no single hosted default that
+  // works for most users - it's commonly self-hosted, and even Umami
+  // Cloud users get a per-region script URL. Defaults to Umami Cloud's
+  // own documented script URL, which only happens to be correct for a
+  // Cloud user on that specific region; anyone self-hosting (the more
+  // common case for this particular provider) must override it to
+  // their own instance's own /script.js path.
+  src: z.string().default("https://cloud.umami.is/script.js")
+}).strict();
+const askAiIntegrationSchema = z.object({
+  id: z.string()
+}).strict();
+const integrationsSchema = z.object({
+  ga4: ga4IntegrationSchema.optional(),
+  googleTagManager: googleTagManagerIntegrationSchema.optional(),
+  plausible: plausibleIntegrationSchema.optional(),
+  fathom: fathomIntegrationSchema.optional(),
+  posthog: posthogIntegrationSchema.optional(),
+  umami: umamiIntegrationSchema.optional(),
+  askAi: askAiIntegrationSchema.optional()
+}).strict().default({});
+const docsConfigSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  styles: stylesSchema,
+  navigation: navigationSchema,
+  // Platform name -> profile/page URL (e.g. `{ "github": "https://
+  // github.com/...", "twitter": "https://twitter.com/..." }`), free-form
+  // rather than an enum of known platforms - the key doubles as the icon
+  // reference BaseLayout.astro's footer resolves via resolveIcon() below
+  // (bare `"github"` -> `lucide:github`; use an explicit
+  // `"simple-icons:whatever"` key instead when the bare lucide name isn't
+  // right for a given platform). Rendered as a row of icon links in the
+  // footer - see hasFooterContent/`.wd-footer-socials` in BaseLayout.astro.
+  socials: z.record(z.string(), z.string()).default({}),
+  topbar: z.object({ links: z.array(topbarLinkSchema).default([]) }).default({ links: [] }),
+  // Columns of links below the page content - see footerSchema/
+  // footerColumnSchema above. Renders alongside `socials` above (as a row
+  // of icon links) in the same <footer> - see BaseLayout.astro.
+  footer: footerSchema,
+  api: apiSchema,
+  // The site's own deployed domain, e.g. "docs.example.com" or
+  // "https://docs.example.com" (the scheme is optional - resolveSiteUrl()
+  // below normalizes either form to a full https:// origin). Powers three
+  // things that all need an absolute origin to work: sitemap.xml
+  // generation (astro.config.mjs only registers @astrojs/sitemap when this
+  // is set - a sitemap of relative URLs isn't meaningful), the canonical
+  // <link> and og:url/twitter meta tags (BaseLayout.astro), and resolving
+  // a relative `seo.ogImage` into an absolute URL for social crawlers.
+  // Left optional and simply skipped (with a log message, not an error) at
+  // every one of those call sites when unset - most fixtures/local builds
+  // have no real deployed domain yet.
+  domain: z.string().optional(),
+  // Site-wide meta tag defaults - see seoFieldsSchema above. A page's own
+  // frontmatter `seo` (content.config.ts's docsSchema) overrides these
+  // field by field via mergeSeo(), rather than needing to repeat every
+  // field on every page.
+  seo: seoFieldsSchema.default({}),
+  // The "Copy page" dropdown - see contextMenuSchema above. Absent by
+  // default (no menu, no .md routes).
+  contextMenu: contextMenuSchema.optional(),
+  // See redirectSchema above. Wired directly into Astro's own `redirects`
+  // config option in astro.config.mjs.
+  redirects: z.array(redirectSchema).default([]),
+  // Site-wide `[[key]]` substitution values, applied to page prose text
+  // at build time (see the remarkSubstituteVariables plugin wired into
+  // astro.config.mjs) - e.g. `{ "productName": "Acme" }` lets every page
+  // write `[[productName]]` once instead of hardcoding it everywhere.
+  // Double square brackets, not the more familiar `{{key}}` - MDX
+  // reserves single curly braces for embedded JS expressions, so
+  // `{{productName}}` in an .mdx file parses as a JS object-literal
+  // expression (`{productName}`, shorthand syntax) rather than literal
+  // text, and throws `ReferenceError: productName is not defined` at
+  // render time - see remarkSubstituteVariables' own comment in
+  // mdx-substitute-variables.js for the full explanation. Deliberately a
+  // flat string map, not typed values - this is text substitution into
+  // prose, not a templating language.
+  variables: z.record(z.string(), z.string()).default({}),
+  // See bannerSchema above. Absent by default (no banner rendered).
+  banner: bannerSchema.optional(),
+  // See notFoundSchema above.
+  notFound: notFoundSchema,
+  // See scriptsSchema above.
+  scripts: scriptsSchema,
+  // See integrationsSchema above.
+  integrations: integrationsSchema
+});
+function positionFromJsonError(message, rawText) {
+  const comLinha = message.match(/line (\d+) column (\d+)/);
+  if (comLinha) return { line: Number(comLinha[1]), column: Number(comLinha[2]) };
+  const comPosicao = message.match(/position (\d+)/);
+  if (comPosicao) {
+    const pos = Math.min(Number(comPosicao[1]), rawText.length);
+    const antes = rawText.slice(0, pos);
+    const line = antes.split("\n").length;
+    return { line, column: pos - antes.lastIndexOf("\n") };
+  }
+  return null;
+}
+function formatValidationIssues(issues) {
+  return issues.map((i) => `  - ${i.path}: ${i.message}`).join("\n");
+}
+function validateDocsConfig(rawText) {
+  let raw;
+  try {
+    raw = JSON.parse(rawText);
+  } catch (err) {
+    const parseError = err;
+    const posicao = positionFromJsonError(parseError.message, rawText);
+    return {
+      ok: false,
+      data: null,
+      kind: "invalid_json",
+      parseError,
+      issues: [{ path: "(root)", message: parseError.message, code: "invalid_json", ...posicao ?? {} }]
+    };
+  }
+  const result = docsConfigSchema.safeParse(raw);
+  if (!result.success) {
+    return {
+      ok: false,
+      data: null,
+      kind: "schema",
+      issues: result.error.issues.map((i) => ({
+        path: i.path.join(".") || "(root)",
+        message: i.message,
+        code: i.code
+      }))
+    };
+  }
+  return { ok: true, data: result.data, issues: [] };
+}
+export {
+  docsConfigSchema,
+  formatValidationIssues,
+  mergeSeo,
+  seoFieldsSchema,
+  validateDocsConfig
+};