@writedocs/generator 0.1.0 → 0.2.1

package/src/lib/config-schema.ts

@@ -0,0 +1,1004 @@
+// O schema do writedocs.json, e nada alem disso.
+//
+// Este arquivo era as primeiras 875 linhas do config.ts (que continua
+// reexportando tudo daqui, entao nada que importa de './config.js' mudou). A
+// separacao existe por um motivo concreto: o config.ts importa node:fs,
+// node:path e gray-matter no topo pras funcoes que leem o disco, e o
+// package.json passou a exportar './config-schema' pra que a plataforma
+// (writedocs-application) possa importar o schema DE VERDADE - o mesmo que o
+// build usa - em vez de manter uma copia que diverge em algumas semanas. Um
+// Worker da Cloudflare nao consegue importar um modulo que traz node:fs junto.
+//
+// Por isso a unica dependencia aqui e o zod. Nada neste arquivo pode passar a
+// tocar o sistema de arquivos: se precisar de fs/path, o lugar e o config.ts.
+//
+// ESTE arquivo e a fonte de verdade, mas NAO e o que o pacote publica: o script
+// `prepare` (package.json) transpila ele pra ./config-schema.js, e e o `.js` que
+// o `exports` e o bin/writedocs.js apontam. Sem isso o `writedocs validate`
+// quebra pra quem instala o pacote - o Node recusa type stripping sob
+// node_modules. Editou aqui, rode `npm run build:schema` (ou qualquer
+// `npm install`) antes de testar o caminho da CLI ou da plataforma.
+//
+// (`zod` e nao `astro/zod`: as duas especificacoes resolvem pra mesma instalacao
+// - node_modules/zod 4.4.3, que e o que astro@7.2.2 tambem pede via `^4.3.6` -
+// entao a troca nao muda comportamento nenhum, so tira o astro do caminho de
+// quem importa isto de fora do gerador.)
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------
+// Pages & groups - the leaf content any container ultimately bottoms out
+// at. A group can nest other groups arbitrarily deep, and can optionally
+// link its own label to a page (`page`) independent of expanding or
+// collapsing its children - see NavTree.astro for how that renders.
+// ---------------------------------------------------------------------
+
+const navPageSchema = z.string();
+
+// A group ordinarily lists its own children by hand (`pages`), but can
+// instead auto-generate them from an OpenAPI spec via `openapi: { src,
+// path }` - resolved by loadDocsConfig() (via expandOpenApiInNavigation()
+// below, reading the manifest generate-api-pages.js writes for this exact
+// group) into a real `{ group, pages }` node - one sub-group per tag -
+// before anything else in this file ever sees it, so
+// resolveSections()/flattenNav()/buildNavTree()/etc. only ever need to
+// understand the ordinary pages-array shape. `.strict()` on both variants
+// is load-bearing (see withChildren()'s own comment on this pattern
+// below): without it, a group written with both `pages` and `openapi` at
+// once would silently have one dropped instead of rejected.
+const navGroupPagesSchema: z.ZodType<{ group: string; page?: string; pages: NavItem[] }> = 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();
+
+export type GroupNavItem =
+  | { group: string; page?: string; pages: NavItem[] }
+  | { group: string; openapi: { src: string; path: string } };
+
+const navGroupSchema: z.ZodType<GroupNavItem> = z.union([navGroupPagesSchema, navGroupOpenApiSchema]);
+
+// A bare external link sitting directly in a `pages` array, alongside
+// page slugs and groups - e.g. a "Support" link to an external help
+// desk shown right in the sidebar, rather than only reachable via
+// navigation.global.dropdowns. Discriminated from navGroupSchema by
+// its required `label`/`href` keys (vs `group`/`pages`/`openapi`), so a
+// plain (non-strict at the union level) schema is enough for Zod to pick
+// the right branch; `.strict()` here still catches a typo'd extra key.
+const navLinkSchema = z.object({ label: z.string(), href: z.string() }).strict();
+
+const navItemSchema: z.ZodType<NavItem> = z.lazy(() =>
+  z.union([navPageSchema, navGroupSchema, navLinkSchema])
+);
+
+export type NavItem = string | GroupNavItem | { label: string; href: string };
+
+// ---------------------------------------------------------------------
+// Containers: tabs, versions, languages, dropdowns, products.
+//
+// This schema is modeled directly on Mintlify's writedocs.json
+// (https://mintlify.com/writedocs.json / mintlify.com/docs/organize/navigation):
+// all five container kinds are structurally identical except for their
+// own identifying field. Each owns *exactly one* of {pages, tabs,
+// versions, languages, dropdowns, products} as its content, or is a bare
+// external `href` link with no content of its own. That symmetry is what
+// lets any of them nest inside any other - a tab can contain versions, a
+// version can contain languages, a language can contain tabs, and so on,
+// bottoming out at a `pages` array. `withChildren()` is the single place
+// that shape is defined, instead of hand-writing the union five times.
+// ---------------------------------------------------------------------
+
+export type NavChildren =
+  | { pages: NavItem[] }
+  | { tabs: TabItem[] }
+  | { versions: VersionItem[] }
+  | { languages: LanguageItem[] }
+  | { dropdowns: DropdownItem[] }
+  | { products: ProductItem[] }
+  | { href: string };
+
+export type TabItem = { tab: string; icon?: string } & NavChildren;
+export type VersionItem = { version: string; label?: string; tag?: string; default?: boolean } & NavChildren;
+export type LanguageItem = { language: string; label?: string } & NavChildren;
+export type DropdownItem = { dropdown: string; icon?: string } & NavChildren;
+export type ProductItem = { product: string; icon?: string; description?: string } & NavChildren;
+
+// `.strict()` on every variant is load-bearing, not decoration: Zod
+// objects silently strip unrecognized keys by default, so without it a
+// node written with two children fields at once (e.g. both `pages` and
+// `versions`) would just have the second one dropped instead of
+// rejected - defeating the entire "exactly one child kind per level"
+// rule this schema exists to enforce (mirroring Mintlify's own "a tab
+// cannot contain both anchors and groups at the same level").
+function withChildren<Base extends z.ZodRawShape>(base: 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(),
+  ]);
+}
+
+// Each of these five is defined via z.lazy() because withChildren()
+// references all five by name (mutual recursion) - safe because none of
+// them are actually *called* until a real writedocs.json is parsed, by which
+// point every const below has been assigned. The same pattern already
+// used for navItemSchema/navGroupSchema above.
+const tabSchema: z.ZodType<TabItem> = z.lazy(() =>
+  withChildren({ tab: z.string(), icon: z.string().optional() })
+);
+
+const versionSchema: z.ZodType<VersionItem> = z.lazy(() =>
+  withChildren({
+    version: z.string(),
+    label: z.string().optional(),
+    tag: z.string().optional(),
+    default: z.boolean().optional(),
+  })
+);
+
+const languageSchema: z.ZodType<LanguageItem> = z.lazy(() =>
+  withChildren({ language: z.string(), label: z.string().optional() })
+);
+
+const dropdownSchema: z.ZodType<DropdownItem> = z.lazy(() =>
+  withChildren({ dropdown: z.string(), icon: z.string().optional() })
+);
+
+const productSchema: z.ZodType<ProductItem> = z.lazy(() =>
+  withChildren({ product: z.string(), icon: z.string().optional(), description: z.string().optional() })
+);
+
+// ---------------------------------------------------------------------
+// Root navigation: a flat array (shorthand for one implicit section - the
+// common case) or an object choosing exactly one primary organizational
+// pattern, per Mintlify's convention ("choose one primary organizational
+// pattern at the root level of your navigation").
+//
+// `global.dropdowns` is the one exception to "exactly one pattern": it's
+// not a primary pattern, it's a persistent set of topbar dropdown
+// triggers that render on every page regardless of which tab/version/
+// language/product is active - equivalent to Mintlify's
+// `navigation.global.anchors`. This replaces the earlier `{tabs,
+// dropdowns}` shape (both present at once), which doesn't generalize
+// once versions/languages/products are also root-level choices.
+// ---------------------------------------------------------------------
+
+export type NavigationConfig =
+  | NavItem[]
+  | { global?: { dropdowns: DropdownItem[] }; tabs: TabItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; versions: VersionItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; languages: LanguageItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; dropdowns: DropdownItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; products: ProductItem[] };
+
+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(),
+]) as z.ZodType<NavigationConfig>;
+
+const DEFAULT_PRIMARY = '#6366f1';
+
+// A logo is either one path used for both color modes, or a
+// { light, dark, label } object - each image shown only while that mode
+// is active (see BaseLayout.astro's .wd-logo-light/.wd-logo-dark CSS).
+// The topbar shows *only* the image by default - no site name text next
+// to it, since a real logo asset usually already is a wordmark. `label`
+// is the opt-in way to add text back next to the image (e.g. a product
+// name alongside a symbol-only mark); it only exists on the object form,
+// since a single shared image path is just as easy to bake the label
+// into directly.
+//
+// `light`/`dark` are themselves optional (unlike the string form, which
+// is inherently "both"): a site with no logo *images* at all can still
+// set `styles.logo: { label: "..." }` to override the topbar's fallback
+// text without providing any image - see BaseLayout.astro's
+// hasLogoImage/logoLabel/brandLabel derivation, where an object with
+// only `label` set already resolves correctly (brandLabel = logoLabel,
+// same as if an image were also present) without needing any change
+// there; only this schema needed loosening; light/dark were previously
+// both required whenever the object form was used at all.
+//
+// Standalone const (rather than inlined into stylesSchema.logo below) so
+// footer.logo further down can share the exact same union instead of an
+// independently-written copy - see footerSchema's own comment on why a
+// footer logo needs this at all.
+const logoSchema = z.union([
+  z.string(),
+  z.object({ light: z.string().optional(), dark: z.string().optional(), label: z.string().optional() }).strict(),
+]);
+
+// Same {light, dark}-with-fallback shape applies to `colors.dark`: any
+// of primary/text left unset there falls back to the light-mode value
+// already given above, so a site only has to specify what actually
+// differs in dark mode. There used to be a `background`/`dark.background`
+// pair here too, doing effectively the same job as `background.colors`
+// further down (see that field's own comment) - two writedocs.json fields
+// both named "background" that visually looked interchangeable but
+// weren't quite (one drove --wd-background site-wide, the other only
+// the <body> canvas), which was confusing to author against and easy to
+// half-configure by setting only one. Removed in favor of `background`
+// alone being the single place to set any background color - see that
+// field's comment for what it now covers.
+// One side of `styles.navbar` (light or dark) - either a bare background
+// color (the original shape) or `{ background, accent? }` once a site
+// wants its own accent color (the active-tab fill / hover underline)
+// inside the navbar specifically, independent of the sitewide
+// `styles.colors.primary`. Deliberately does NOT carry a text/icon color
+// field at all - see `navbar`'s own comment below (stylesSchema) for why
+// that's resolved automatically instead of being configurable. Kept as a
+// standalone const rather than inlined so `light`/`dark` share the exact
+// same union rather than two independently-written (and possibly
+// drifting) copies of it.
+const navbarColorValueSchema = z.union([
+  z.string(),
+  z
+    .object({
+      background: z.string(),
+      accent: z.string().optional(),
+    })
+    .strict(),
+]);
+
+// One font declaration - almost exactly Mintlify's own `fonts` shape (see
+// docs/dev/docs/site-config.mdx's own "Fonts" section for the research this
+// was based on): a bare Google Fonts family name (`family` alone - Google
+// Fonts loads it automatically, see googleFontsHref() below), or a local/
+// externally-hosted font file (`source` + `format` together; `source` is
+// either a project-relative path like the other five asset-fallback fields
+// this schema already has - see collectConfiguredAssetPaths() - or a full
+// https:// URL to an externally-hosted font). `weight` does two things at
+// once, both driven by BaseLayout.astro: it narrows which file actually
+// loads (folded into the Google Fonts URL's `:wght@` axis, or the
+// generated `@font-face` rule's own `font-weight` descriptor for a
+// `source` font - see googleFontsHref()/fontFaceRule() below), *and* it's
+// applied as a real CSS `font-weight` on h1-h6 (for `heading`) or `body`
+// (for `body`) - see BaseLayout's own `wdFontWeightHeading`/
+// `wdFontWeightBody`. Both halves matter: loading only the 400-weight file
+// while leaving h1-h6 at the browser's UA-default `font-weight: bold`
+// faux-bolds that file back to looking bold anyway, with no visible
+// change from configuring a lighter weight at all - the bug this second
+// half fixes (caught from real user-reported behavior, not anticipated
+// up front). Left unset anywhere in `styles.fonts` renders no font-weight
+// rule at all, keeping today's plain browser-default bold headings/normal
+// body text unchanged for a site that hasn't touched this field.
+const fontVariantSchema = z
+  .object({
+    family: z.string(),
+    weight: z.number().optional(),
+    source: z.string().optional(),
+    format: z.enum(['woff', 'woff2']).optional(),
+  })
+  .strict();
+
+export type FontVariant = z.infer<typeof fontVariantSchema>;
+
+// The top-level shape adds `heading`/`body`: each independently optional,
+// each falling back to the top-level family/weight/source/format when
+// unset (see resolveFonts() below) - so a site can set one font for
+// everything (`fonts.family` alone), or split headings and body text
+// without needing to repeat itself for whichever side isn't changing.
+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();
+
+export type FontsConfig = z.infer<typeof fontsSchema>;
+
+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 } });
+
+// `href` is always required - a link with nowhere to go isn't a link.
+// `label`/`icon` are each individually optional, but not both at once
+// (enforced by the .refine() below, same shape as scriptEntrySchema's own
+// exactly-one-of check above) - a link needs *something* visible to render,
+// whichever of the two, and can have both (icon rendered to the left of the
+// label - see TopBar.astro/SiteFooter.astro, the two renderers of this
+// shape). An icon-only link (no label) is the common case for something
+// like a bare GitHub mark in the topbar; label-only (no icon) is every
+// plain text link this already supported before `icon` existed - both
+// still need to keep working unchanged, hence neither field being outright
+// required on its own.
+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.',
+  });
+
+// One column of the footer (BaseLayout.astro's <footer class="wd-footer">) -
+// an optional heading (e.g. "Resources", "Community") plus a list of links,
+// reusing the exact same {label, icon, href} shape as topbar.links above (a
+// footer link is the same thing rendered in a different place, no reason
+// for a second, identical-but-differently-named schema). `title` is
+// optional so a single-column footer with no heading (just a bare list of
+// links) is valid too.
+const footerColumnSchema = z
+  .object({
+    title: z.string().optional(),
+    links: z.array(topbarLinkSchema).default([]),
+  })
+  .strict();
+
+// Off by default (empty `columns`, same convention as `topbar` above - a
+// footer with nothing configured just doesn't render at all, see
+// BaseLayout.astro's `hasFooterContent` check) rather than `.optional()`
+// like contextMenu: unlike that field, an empty/default footer has no
+// build-output or routing implications to gate, it's purely visual, so
+// there's no reason to distinguish "unset" from "set to nothing" the way
+// contextMenu needs to.
+// Same {light, dark, label} union as `styles.logo` (via the shared
+// logoSchema above) - unset by default, in which case the footer just
+// shows the sitewide `styles.logo` (BaseLayout.astro's existing
+// logoLight/logoDark/logoLabel, already threaded into SiteFooter as-is).
+// Set here, it replaces that entirely rather than filling in only the
+// missing side of it - a footer.logo with only `dark` set shows *just*
+// the dark-mode image, not styles.logo's light image plus this dark one -
+// the same all-or-nothing-relative-to-styles.logo resolution BaseLayout.astro
+// already applies.
+const footerSchema = z
+  .object({
+    columns: z.array(footerColumnSchema).default([]),
+    logo: logoSchema.optional(),
+  })
+  .strict()
+  .default({ columns: [] });
+
+export type FooterColumn = z.infer<typeof footerColumnSchema>;
+export type FooterConfig = z.infer<typeof footerSchema>;
+
+// Shared by both writedocs.json's top-level `seo` (site-wide defaults) and a
+// page's own frontmatter `seo` (per-page overrides) - see
+// content.config.ts's docsSchema, which imports this exact schema rather
+// than redeclaring the same shape a second time. mergeSeo() below is what
+// actually combines the two, field by field, at render time.
+export 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();
+
+export type SeoFields = z.infer<typeof seoFieldsSchema>;
+
+/** Field-by-field merge of a page's own `seo` frontmatter over writedocs.json's
+ *  site-wide `seo` defaults - a page only overrides the specific fields it
+ *  sets, falling back to the site default for everything else, rather than
+ *  a page's (possibly partial) `seo` object replacing the site's wholesale. */
+export function mergeSeo(site: SeoFields, page?: SeoFields): SeoFields {
+  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,
+  };
+}
+
+// Controls for the OpenAPI API playground's "Try it" modal - separate
+// from a group's own `openapi: { src, path }` field (which spec to use,
+// and where) since this is about how a *request* it sends behaves, not
+// about the spec itself.
+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 });
+
+// The "Copy page" dropdown shown next to a page's title - copy the raw
+// Markdown to the clipboard, open the raw Markdown in a new tab, or
+// deep-link into an AI assistant with a prompt pointing at it. Opt-in:
+// undefined (the field simply absent from writedocs.json) means the feature
+// is off entirely - no menu rendered, no .md routes generated at build
+// time either (see [...slug].md.ts) - rather than defaulting to on,
+// since it changes both the UI and the build output. Once a site does
+// write a `contextMenu` key (even `{}`), copying/viewing-as-Markdown are
+// always included (they need nothing but the page's own content); only
+// `openIn` (the AI-assistant deep-links, which need an absolute URL to
+// point the assistant at) is independently configurable.
+const contextMenuSchema = z
+  .object({
+    openIn: z.array(z.enum(['chatgpt', 'claude', 'perplexity'])).default(['chatgpt', 'claude', 'perplexity']),
+  })
+  .strict();
+
+export type ContextMenuConfig = z.infer<typeof contextMenuSchema>;
+
+// One entry in writedocs.json's `redirects` array - wired almost directly into
+// Astro's own `redirects` config option (astro.config.mjs), which is what
+// actually generates the redirect pages. `permanent` is deliberately not
+// part of this schema: with no server/adapter (this project always builds
+// `output: 'static'` with none installed), Astro's own docs say a static
+// redirect "does not support status codes" at all - it's always a client-
+// side `<meta http-equiv="refresh">` page, full stop. Accepting a
+// `permanent` field here that silently did nothing would be worse than
+// not offering it.
+const redirectSchema = z
+  .object({
+    source: z.string(),
+    destination: z.string(),
+  })
+  .strict();
+
+export type RedirectConfig = z.infer<typeof redirectSchema>;
+
+// A site-wide banner rendered above the topbar on every page (except
+// `mode: blank`, which drops all site chrome including this - see
+// BaseLayout.astro). Optional/undefined by default, same convention as
+// `contextMenu` above - a site with no banner configured gets no banner
+// markup at all, not an empty one.
+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();
+
+export type BannerConfig = z.infer<typeof bannerSchema>;
+
+// Content for the custom 404 page (src/pages/404.astro) - Astro's own
+// file-based convention (a static build emits this as 404.html at the
+// site root; most static hosts pick it up automatically for unmatched
+// routes). Both fields are optional with hardcoded fallbacks in 404.astro
+// itself, so a site doesn't have to set either to get a reasonably
+// branded 404 page (still rendered inside the normal BaseLayout/topbar
+// chrome, just with placeholder content).
+const notFoundSchema = z
+  .object({
+    title: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .strict()
+  .default({});
+
+export type NotFoundConfig = z.infer<typeof notFoundSchema>;
+
+// One <script> tag to inject - exactly one of `src` (an external/local
+// file, rendered as `<script src="...">`) or `content` (inline JS,
+// rendered via `<script is:inline set:html="...">`) has to be set, not
+// both and not neither - enforced by the `.refine()` below rather than
+// leaving both optional and silently rendering an empty tag if a site
+// author gets this wrong.
+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.',
+  });
+
+export type ScriptEntry = z.infer<typeof scriptEntrySchema>;
+
+// Raw third-party script injection - analytics snippets, chat widgets,
+// anything that needs a real <script> tag writedocs.json's own structured
+// fields (styles, integrations-style config, ...) don't have a dedicated
+// slot for yet. `head` renders right before </head>; `body` renders right
+// before </body> (after everything else has already loaded/hydrated -
+// see BaseLayout.astro), matching where a third-party script's own
+// install instructions usually say to put it.
+const scriptsSchema = z
+  .object({
+    head: z.array(scriptEntrySchema).default([]),
+    body: z.array(scriptEntrySchema).default([]),
+  })
+  .strict()
+  .default({ head: [], body: [] });
+
+export type ScriptsConfig = z.infer<typeof scriptsSchema>;
+
+// writedocs.json's `integrations` - a curated, high-value subset of analytics
+// providers, each getting its own minimal config object (just the id(s)
+// it actually needs) rather than requiring a site author to hand-write
+// the provider's own install snippet through the generic `scripts` field
+// above. This is deliberately its own thing, not built as sugar over
+// `scripts` the way the roadmap once implied it might be - most of these
+// providers' real snippets need `defer`/`async`/`data-*` attributes
+// ScriptEntry's plain `{ src?, content? }` shape has no way to express,
+// so BaseLayout.astro renders each provider with its own bespoke markup
+// instead of generating a ScriptEntry array to feed through the generic
+// renderer. Every snippet shape below was sourced from that provider's
+// own current official docs (fetched directly, not recalled from
+// training data) while building this feature - see
+// docs/dev/docs/integrations.mdx for links and dates.
+//
+// Every provider field is optional and independent - a site can turn on
+// any subset (including all of them at once, for a migration period) or
+// none. No "the" analytics field; a site picks whichever provider(s) it
+// actually uses.
+
+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();
+
+// AI chat over the site's own docs content, via a third-party provider
+// (DocsBot, currently the only one wired up) rather than a self-hosted
+// RAG pipeline - see the roadmap's own "AI chat over docs content" line
+// in docs/dev/docs/roadmap.mdx, which this fulfills via integration
+// rather than by building the retrieval/generation stack in-house.
+// Deliberately named `askAi` here, not `docsbot` - this is the
+// writedocs.json-facing, provider-neutral name for the feature (matching
+// the "Ask AI" label this kind of button/widget is conventionally
+// given in docs sites generally), independent of which vendor happens
+// to sit behind it today. `id` matches DocsBot's own embed config
+// field name exactly (`DocsBotAI.init({ id: 'teamId/botId' })`) - it's
+// a single opaque "teamId/botId" string DocsBot treats as one value,
+// not two separate ids, so this schema doesn't split it either.
+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({});
+
+export type IntegrationsConfig = z.infer<typeof integrationsSchema>;
+
+export 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,
+});
+
+export type DocsConfig = z.infer<typeof docsConfigSchema>;
+
+// ---------------------------------------------------------------------
+// Ponto de entrada unico de validacao
+//
+// Existe pra que o gerador (`writedocs validate` e o `loadDocsConfig` que o
+// build usa) e a plataforma validem pelo MESMO codigo, com as MESMAS palavras -
+// o criterio de aceite do WD-066 e do WD-062. Se cada lado formatasse os erros
+// por conta propria, o cliente veria a plataforma aceitar um writedocs.json que
+// o build depois recusa, que e exatamente a classe de bug que a E11 existe pra
+// impedir.
+//
+// Recebe TEXTO CRU, e faz o JSON.parse por conta propria, por tres motivos:
+//   1. um JSON sintaticamente quebrado passa a ser um resultado de validacao
+//      como qualquer outro, em vez de uma excecao solta do runtime;
+//   2. linha/coluna so existem no texto - e o WD-063 precisa reportar linha;
+//   3. do lado da plataforma, importProjectConfig ja tem os bytes crus em maos
+//      antes de parsear, entao encaixa sem ginastica nenhuma.
+//
+// IMPORTANTE, e deliberado: as mensagens aqui sao as do Zod, VERBATIM. Melhorar
+// a linguagem delas e o WD-063, que precisa deste comportamento como ponto de
+// partida pra medir a melhora. Nada aqui reescreve, traduz ou embeleza mensagem.
+// ---------------------------------------------------------------------
+
+/** Um problema encontrado na configuracao. `path` e o caminho do campo em
+ *  notacao de ponto (`navigation.tabs.0.label`), ou `(root)` quando o problema e
+ *  do documento inteiro - o mesmo texto que a mensagem de erro do build ja
+ *  imprime hoje. `line`/`column` so vem quando da pra saber (hoje: erro de JSON;
+ *  no WD-063, tambem para erros de schema). */
+export type ValidationIssue = {
+  path: string;
+  message: string;
+  /** Codigo do Zod (`invalid_type`, `unrecognized_keys`, ...) ou `invalid_json`. */
+  code?: string;
+  line?: number;
+  column?: number;
+};
+
+/** Sucesso carrega os dados ja validados (com os defaults do schema aplicados);
+ *  falha carrega os problemas e diz de que tipo ela foi. `parseError` so aparece
+ *  quando o JSON nao pode nem ser parseado, e existe para o chamador que quiser
+ *  relancar exatamente o erro original (e o que o loadDocsConfig faz, pra nao
+ *  mudar uma virgula do que o `writedocs build` ja imprime hoje). */
+export type ValidationResult =
+  | { ok: true; data: DocsConfig; issues: ValidationIssue[] }
+  | {
+      ok: false;
+      data: null;
+      kind: 'invalid_json' | 'schema';
+      issues: ValidationIssue[];
+      parseError?: SyntaxError;
+    };
+
+/** "at position 22 (line 1 column 23)" -> { line: 1, column: 23 }.
+ *  O formato da mensagem de erro do JSON.parse e do V8, nao do padrao, entao
+ *  isto e melhor-esforco: se a mensagem nao trouxer posicao, devolve null e o
+ *  problema simplesmente fica sem linha. */
+function positionFromJsonError(message: string, rawText: string): { line: number; column: number } | null {
+  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;
+}
+
+/** O corpo da mensagem de erro, uma linha por problema - exatamente o formato
+ *  que o `writedocs build` imprime desde sempre (`  - campo: mensagem`). Fica
+ *  aqui, e nao em cada chamador, pra que CLI e plataforma nao possam divergir. */
+export function formatValidationIssues(issues: ValidationIssue[]): string {
+  return issues.map((i) => `  - ${i.path}: ${i.message}`).join('\n');
+}
+
+export function validateDocsConfig(rawText: string): ValidationResult {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(rawText);
+  } catch (err) {
+    const parseError = err as SyntaxError;
+    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: [] };
+}