@hgdc/docs 0.0.0-stage → 0.1.1

package/src/core/config.ts

@@ -0,0 +1,153 @@
+import { z } from "zod"
+
+/**
+ * `docs.json` : configuration d'un site HGDC Docs, à la racine du dépôt du client.
+ *
+ * Sous-ensemble du `docs.json` de Mintlify (name, colors, logo, favicon, navigation en
+ * onglets, groupes et versions) pour qu'une doc Mintlify se reprenne sans réécriture,
+ * plus trois champs HGDC : `project`, `assistant` et `language`. Les champs Mintlify que
+ * nous ne gérons pas sont acceptés et ignorés, jamais refusés.
+ */
+
+const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i
+/** Chemin de page relatif au dossier de la doc, sans extension : `guides/publier`. */
+const PAGE = /^(?!\/)(?!.*\.\.)[a-z0-9][a-z0-9/_-]*$/i
+/** Identifiant d'un projet de la console (id Convex). */
+const PROJECT_ID_PATTERN = /^[a-z0-9]{8,64}$/
+
+const hex = z.string().regex(HEX, "couleur attendue au format #rrggbb")
+
+export type NavPageRef = string
+export type NavGroupInput = { group: string; pages: Array<NavPageRef | NavGroupInput>; expanded?: boolean }
+
+const pageRef = z.string().regex(PAGE, "chemin de page attendu, sans extension ni « / » initial (ex. guides/publier)")
+
+const navGroup: z.ZodType<NavGroupInput> = z.lazy(() =>
+  z.object({
+    group: z.string().min(1),
+    pages: z.array(z.union([pageRef, navGroup])).min(1, "un groupe contient au moins une page"),
+    expanded: z.boolean().optional(),
+  }),
+)
+
+const groupsOrPages = {
+  groups: z.array(navGroup).optional(),
+  pages: z.array(z.union([pageRef, navGroup])).optional(),
+}
+
+const navTab = z.object({ tab: z.string().min(1), ...groupsOrPages })
+const navVersion = z.object({
+  version: z.string().min(1).max(32),
+  default: z.boolean().optional(),
+  tabs: z.array(navTab).optional(),
+  ...groupsOrPages,
+})
+
+const navigation = z.object({
+  versions: z.array(navVersion).optional(),
+  tabs: z.array(navTab).optional(),
+  ...groupsOrPages,
+})
+
+const logo = z.union([
+  z.string(),
+  z.object({ light: z.string(), dark: z.string().optional(), href: z.string().optional() }),
+])
+
+export const docsConfigSchema = z.object({
+  $schema: z.string().optional(),
+  name: z.string().min(1).max(80),
+  description: z.string().max(300).optional(),
+  /** Identifiant du projet dans la console : relie la publication à l'assistant et à l'index. */
+  project: z
+    .string()
+    .regex(PROJECT_ID_PATTERN, "identifiant de projet attendu, copié depuis la console docs.hgdc.ch")
+    .optional(),
+  language: z.enum(["fr", "en", "de", "it"]).default("fr"),
+  colors: z.object({ primary: hex, light: hex.optional(), dark: hex.optional() }).optional(),
+  logo: logo.optional(),
+  favicon: z.string().optional(),
+  navigation,
+  navbar: z
+    .object({
+      links: z
+        .array(z.object({ label: z.string(), href: z.url() }))
+        .max(5)
+        .optional(),
+      primary: z.object({ label: z.string(), href: z.url() }).optional(),
+    })
+    .optional(),
+  footer: z.object({ socials: z.record(z.string(), z.url()).optional() }).optional(),
+  assistant: z
+    .object({
+      enabled: z.boolean().default(true),
+      /** Adresse de l'API de l'assistant ; par défaut celle de HGDC Docs. */
+      endpoint: z.url().optional(),
+    })
+    .optional(),
+})
+
+export type DocsConfigInput = z.input<typeof docsConfigSchema>
+export type DocsConfig = z.output<typeof docsConfigSchema>
+
+export type ConfigResult = { ok: true; config: DocsConfig } | { ok: false; errors: Array<string> }
+
+/** Lit et valide un `docs.json`. Les erreurs disent où corriger, en français. */
+export function parseDocsConfig(raw: string): ConfigResult {
+  let json: unknown
+  try {
+    json = JSON.parse(raw)
+  } catch (error) {
+    return { ok: false, errors: [`docs.json n'est pas un JSON valide : ${(error as Error).message}`] }
+  }
+  const parsed = docsConfigSchema.safeParse(json)
+  if (!parsed.success) {
+    return {
+      ok: false,
+      errors: parsed.error.issues.map((issue) => `${issue.path.join(".") || "(racine)"} : ${issue.message}`),
+    }
+  }
+  const structural = checkNavigation(parsed.data)
+  return structural.length ? { ok: false, errors: structural } : { ok: true, config: parsed.data }
+}
+
+/**
+ * Projet annoncé par HGDC Host au build (`HGDC_DOCS_PROJECT`, doc activée en un clic) : il
+ * remplit `project` quand docs.json n'en a pas, et doit concorder quand les deux existent.
+ */
+export function withHostProject(config: DocsConfig, fromHost: string | undefined): ConfigResult {
+  const project = fromHost?.trim()
+  if (!project) return { ok: true, config }
+  if (!PROJECT_ID_PATTERN.test(project))
+    return { ok: false, errors: [`HGDC_DOCS_PROJECT : identifiant de projet invalide (${project.slice(0, 64)})`] }
+  if (config.project && config.project !== project)
+    return {
+      ok: false,
+      errors: [
+        `project : docs.json porte ${config.project}, HGDC Host annonce ${project}. Retire « project » de docs.json ou recopie celui de la console.`,
+      ],
+    }
+  return { ok: true, config: { ...config, project } }
+}
+
+function checkNavigation(config: DocsConfig): Array<string> {
+  const errors: Array<string> = []
+  const nav = config.navigation
+  const shapes = [nav.versions, nav.tabs, nav.groups, nav.pages].filter(Boolean).length
+  if (shapes !== 1) errors.push("navigation : utiliser une seule forme parmi versions, tabs, groups ou pages")
+  const versions = nav.versions ?? []
+  if (versions.filter((v) => v.default).length > 1) errors.push("navigation.versions : une seule version par défaut")
+  const ids = versions.map((v) => slugifySegment(v.version))
+  if (new Set(ids).size !== ids.length) errors.push("navigation.versions : deux versions ont le même nom")
+  return errors
+}
+
+/** Segment d'URL stable à partir d'un libellé (« Version 2.x » → « version-2-x »). */
+export function slugifySegment(label: string): string {
+  return label
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}

package/src/core/corpus.ts

@@ -0,0 +1,42 @@
+import { z } from "zod"
+
+/**
+ * Corpus publié avec chaque build, à `/_hgdc/corpus.json` : le contenu exact du site en
+ * Markdown, page par page. La console le lit après une publication pour indexer
+ * l'assistant ; rien d'autre que ce qui est public n'entre dans l'index.
+ */
+export const CORPUS_PATH = "/_hgdc/corpus.json"
+export const CORPUS_FORMAT = 1
+export const MAX_PAGES = 2000
+export const MAX_PAGE_CHARS = 200_000
+
+/**
+ * Chemin d'une page du site : commence par un seul « / », sans « // », sans « \ » ni
+ * caractère de contrôle. Sinon `new URL(chemin, site)` sortirait du site (« //evil.example »).
+ */
+export function isSitePath(path: string): boolean {
+  // oxlint-disable-next-line no-control-regex -- on refuse justement ces caractères
+  return path.startsWith("/") && !path.includes("//") && !/[\\\u0000-\u001f]/.test(path)
+}
+
+export const corpusPageSchema = z.object({
+  path: z.string().max(512).refine(isSitePath, "chemin du site attendu (/guides/publier/)"),
+  title: z.string().max(300),
+  description: z.string().max(1000).nullable(),
+  version: z.string().max(32).nullable(),
+  markdown: z.string().max(MAX_PAGE_CHARS),
+})
+
+export const corpusSchema = z.object({
+  format: z.literal(CORPUS_FORMAT),
+  project: z.string().nullable(),
+  name: z.string().max(80),
+  language: z.string().max(8),
+  builtAt: z.iso.datetime(),
+  theme: z.object({ primary: z.string().nullable(), logo: z.string().nullable() }),
+  versions: z.array(z.object({ id: z.string().nullable(), label: z.string().nullable(), isDefault: z.boolean() })),
+  pages: z.array(corpusPageSchema).max(MAX_PAGES),
+})
+
+export type CorpusPage = z.infer<typeof corpusPageSchema>
+export type Corpus = z.infer<typeof corpusSchema>

package/src/core/json-schema.ts

@@ -0,0 +1,12 @@
+import { z } from "zod"
+
+import { docsConfigSchema } from "./config.ts"
+
+/** JSON Schema de docs.json, pour l'autocomplétion des éditeurs (`"$schema"`). */
+export function docsJsonSchema(): Record<string, unknown> {
+  return {
+    ...z.toJSONSchema(docsConfigSchema, { io: "input", unrepresentable: "any" }),
+    $id: "https://docs.hgdc.ch/docs.schema.json",
+    title: "docs.json de HGDC Docs",
+  }
+}

package/src/core/llms.ts

@@ -0,0 +1,95 @@
+import type { NavItem, NavTree } from "./navigation.ts"
+import { pagesOf as pagesIn, pageToPath } from "./navigation.ts"
+
+/**
+ * `llms.txt` et `llms-full.txt` au format de llmstxt.org : un H1, un résumé en citation,
+ * puis une section H2 par onglet (ou groupe), chaque page liée à sa version Markdown.
+ * Les versions autres que celle par défaut vont sous « Optional », que l'agent peut sauter.
+ */
+export type LlmsPage = { page: string; title: string; description: string | null; markdown: string }
+
+export type LlmsInput = {
+  name: string
+  description: string | null
+  site: string | null
+  tree: NavTree
+  pages: ReadonlyMap<string, LlmsPage>
+}
+
+/** `/guides/publier/` → `/guides/publier.md`, `/` → `/index.md`. */
+export function markdownPath(path: string): string {
+  const trimmed = path.replace(/\/+$/, "")
+  return trimmed ? `${trimmed}.md` : "/index.md"
+}
+
+function url(site: string | null, path: string): string {
+  return site ? new URL(path, site).toString() : path
+}
+
+function link(input: LlmsInput, page: string): string | null {
+  const data = input.pages.get(page)
+  if (!data) return null
+  const target = url(input.site, markdownPath(pageToPath(page)))
+  return `- [${data.title}](${target})${data.description ? `: ${data.description}` : ""}`
+}
+
+function sectionLines(input: LlmsInput, heading: string, items: Array<NavItem>): Array<string> {
+  const lines: Array<string> = []
+  const loose: Array<string> = []
+  const groups: Array<[string, Array<string>]> = []
+  const walk = (list: Array<NavItem>, prefix: string | null, into: Array<string>) => {
+    for (const item of list) {
+      if (item.type === "page") {
+        const line = link(input, item.page)
+        if (line) into.push(line)
+      } else {
+        const label = prefix ? `${prefix} › ${item.label}` : item.label
+        const bucket: Array<string> = []
+        groups.push([label, bucket])
+        walk(item.items, label, bucket)
+      }
+    }
+  }
+  walk(items, null, loose)
+  if (loose.length) lines.push(`## ${heading}`, "", ...loose, "")
+  for (const [label, bucket] of groups) {
+    if (!bucket.length) continue
+    lines.push(`## ${heading === "Documentation" ? label : `${heading} · ${label}`}`, "", ...bucket, "")
+  }
+  return lines
+}
+
+export function llmsTxt(input: LlmsInput): string {
+  const lines = [`# ${input.name}`, ""]
+  if (input.description) lines.push(`> ${input.description}`, "")
+  lines.push(
+    "Chaque page existe en Markdown à la même adresse suivie de `.md`. `llms-full.txt` contient toute la documentation en un seul fichier.",
+    "",
+  )
+  const optional: Array<string> = []
+  for (const version of input.tree.versions) {
+    for (const tab of version.tabs) {
+      if (version.isDefault) {
+        lines.push(...sectionLines(input, tab.label ?? "Documentation", tab.items))
+        continue
+      }
+      // Anciennes versions : une liste plate sous « Optional », libellée par version.
+      for (const page of pagesIn(tab.items)) {
+        const line = link(input, page)
+        if (line) optional.push(line.replace("- [", `- [${version.label} · `))
+      }
+    }
+  }
+  if (optional.length) lines.push("## Optional", "", ...optional, "")
+  return `${lines.join("\n").trim()}\n`
+}
+
+export function llmsFullTxt(input: LlmsInput, order: Array<string>): string {
+  const parts = [`# ${input.name}`, input.description ? `\n> ${input.description}` : ""]
+  for (const page of order) {
+    const data = input.pages.get(page)
+    if (!data) continue
+    parts.push(`\n---\n\nSource : ${url(input.site, pageToPath(page))}\n\n# ${data.title}\n\n${data.markdown.trim()}`)
+  }
+  return `${parts.join("\n").trim()}\n`
+}

package/src/core/navigation.ts

@@ -0,0 +1,88 @@
+import { slugifySegment, type DocsConfig, type NavGroupInput } from "./config.ts"
+
+/**
+ * Navigation normalisée : toujours versions → onglets → éléments, quelle que soit la forme
+ * écrite dans `docs.json` (pages seules, groupes, onglets ou versions, comme Mintlify).
+ */
+export type NavItem =
+  | { type: "page"; page: string }
+  | { type: "group"; label: string; expanded: boolean; items: Array<NavItem> }
+
+export type NavTab = { id: string; label: string | null; items: Array<NavItem> }
+export type NavVersion = { id: string | null; label: string | null; isDefault: boolean; tabs: Array<NavTab> }
+export type NavTree = { versions: Array<NavVersion> }
+
+type Container = { groups?: Array<NavGroupInput>; pages?: Array<string | NavGroupInput> }
+
+function items(container: Container): Array<NavItem> {
+  if (container.groups) return container.groups.map(group)
+  return (container.pages ?? []).map(entry)
+}
+
+function entry(value: string | NavGroupInput): NavItem {
+  return typeof value === "string" ? { type: "page", page: value } : group(value)
+}
+
+function group(value: NavGroupInput): NavItem {
+  return { type: "group", label: value.group, expanded: value.expanded ?? true, items: value.pages.map(entry) }
+}
+
+function tabs(container: Container & { tabs?: Array<Container & { tab: string }> }): Array<NavTab> {
+  if (container.tabs)
+    return container.tabs.map((tab) => ({ id: slugifySegment(tab.tab), label: tab.tab, items: items(tab) }))
+  return [{ id: "main", label: null, items: items(container) }]
+}
+
+export function normalizeNavigation(config: DocsConfig): NavTree {
+  const nav = config.navigation
+  if (nav.versions) {
+    const hasDefault = nav.versions.some((v) => v.default)
+    return {
+      versions: nav.versions.map((version, index) => ({
+        id: slugifySegment(version.version),
+        label: version.version,
+        isDefault: version.default ?? (!hasDefault && index === 0),
+        tabs: tabs(version),
+      })),
+    }
+  }
+  return { versions: [{ id: null, label: null, isDefault: true, tabs: tabs(nav) }] }
+}
+
+export function pagesOf(list: Array<NavItem>): Array<string> {
+  return list.flatMap((item) => (item.type === "page" ? [item.page] : pagesOf(item.items)))
+}
+
+export function allPages(tree: NavTree): Array<string> {
+  return tree.versions.flatMap((version) => version.tabs.flatMap((tab) => pagesOf(tab.items)))
+}
+
+export type PageLocation = { version: NavVersion; tab: NavTab }
+
+/** Version et onglet qui contiennent une page ; la première occurrence l'emporte. */
+export function locatePage(tree: NavTree, page: string): PageLocation | null {
+  for (const version of tree.versions)
+    for (const tab of version.tabs) if (pagesOf(tab.items).includes(page)) return { version, tab }
+  return null
+}
+
+export function defaultVersion(tree: NavTree): NavVersion {
+  return tree.versions.find((v) => v.isDefault) ?? tree.versions[0]!
+}
+
+/** Page « index » à la racine du site, « guides/index » sur `/guides/`. */
+export function pageToSlug(page: string): string {
+  const lower = page.toLowerCase()
+  if (lower === "index") return ""
+  return lower.endsWith("/index") ? lower.slice(0, -"/index".length) : lower
+}
+
+export function pageToPath(page: string): string {
+  const slug = pageToSlug(page)
+  return slug ? `/${slug}/` : "/"
+}
+
+/** Pages citées dans la navigation mais absentes du dossier : erreur de build lisible. */
+export function missingPages(tree: NavTree, existing: ReadonlySet<string>): Array<string> {
+  return [...new Set(allPages(tree))].filter((page) => !existing.has(pageToSlug(page)))
+}

package/src/core/theme.ts

@@ -0,0 +1,111 @@
+/**
+ * Couleur du client → variables d'accent de Starlight, en clair et en sombre.
+ *
+ * On garde la teinte et la saturation de la couleur donnée, et on ajuste seulement sa
+ * luminosité (OKLCH) jusqu'au contraste exigé : un lien reste lisible à 4,5:1 sur le fond,
+ * quelle que soit la couleur choisie par le client.
+ */
+export type Oklch = { l: number; c: number; h: number }
+export type AccentPalette = { low: string; accent: string; high: string; onAccent: string }
+export type Theme = { light: AccentPalette; dark: AccentPalette }
+
+/** Accent violet de la DA HGDC (`--brand-accent` du kit), si le client n'en donne pas. */
+export const HGDC_ACCENT = "#7c3aed"
+
+const LIGHT_BG = "#ffffff"
+const DARK_BG = "#0f0f10"
+
+export function themeFor(primary: string = HGDC_ACCENT, dark?: string): Theme {
+  const base = hexToOklch(primary)
+  const darkBase = dark ? hexToOklch(dark) : base
+  return {
+    light: palette(base, LIGHT_BG, { low: 0.955, high: 0.36 }),
+    dark: palette(darkBase, DARK_BG, { low: 0.27, high: 0.9 }),
+  }
+}
+
+function palette(base: Oklch, background: string, tones: { low: number; high: number }): AccentPalette {
+  const accent = withContrast(base, background, 4.5)
+  const low = oklchToHex({ l: tones.low, c: Math.min(base.c, 0.06), h: base.h })
+  const high = withContrast({ ...base, l: tones.high }, low, 7)
+  const onAccent = contrast("#ffffff", accent) >= contrast("#000000", accent) ? "#ffffff" : "#000000"
+  return { low, accent, high, onAccent }
+}
+
+/** Couleur la plus proche de `color`, en luminosité seulement, qui atteint `ratio` sur `background`. */
+export function withContrast(color: Oklch, background: string, ratio: number): string {
+  const towardsDark = luminance(background) > 0.5
+  let l = color.l
+  for (let i = 0; i < 100; i++) {
+    const hex = oklchToHex({ ...color, l })
+    if (contrast(hex, background) >= ratio) return hex
+    l = towardsDark ? l - 0.01 : l + 0.01
+    if (l <= 0 || l >= 1) break
+  }
+  return towardsDark ? "#000000" : "#ffffff"
+}
+
+export function themeCss(theme: Theme): string {
+  const vars = (p: AccentPalette) =>
+    `--sl-color-accent-low:${p.low};--sl-color-accent:${p.accent};--sl-color-accent-high:${p.high};--hgdc-on-accent:${p.onAccent};`
+  return `:root{${vars(theme.dark)}}:root[data-theme="light"]{${vars(theme.light)}}`
+}
+
+// --- Conversions sRGB ↔ OKLCH (Björn Ottosson) et contraste WCAG 2 ---
+
+export function hexToRgb(hex: string): [number, number, number] {
+  const value = hex.replace("#", "")
+  const full =
+    value.length === 3
+      ? value
+          .split("")
+          .map((c) => c + c)
+          .join("")
+      : value
+  const n = Number.parseInt(full, 16)
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
+}
+
+const toLinear = (c: number) => {
+  const v = c / 255
+  return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4
+}
+const fromLinear = (v: number) => {
+  const c = v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055
+  return Math.round(Math.min(1, Math.max(0, c)) * 255)
+}
+
+export function hexToOklch(hex: string): Oklch {
+  const [r, g, b] = hexToRgb(hex).map(toLinear) as [number, number, number]
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b)
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b)
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b)
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s
+  return { l: L, c: Math.hypot(A, B), h: ((Math.atan2(B, A) * 180) / Math.PI + 360) % 360 }
+}
+
+export function oklchToHex({ l: L, c, h }: Oklch): string {
+  const A = c * Math.cos((h * Math.PI) / 180)
+  const B = c * Math.sin((h * Math.PI) / 180)
+  const l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3
+  const m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3
+  const s = (L - 0.0894841775 * A - 1.291485548 * B) ** 3
+  const rgb = [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ].map(fromLinear)
+  return `#${rgb.map((v) => v.toString(16).padStart(2, "0")).join("")}`
+}
+
+export function luminance(hex: string): number {
+  const [r, g, b] = hexToRgb(hex).map(toLinear) as [number, number, number]
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+export function contrast(a: string, b: string): number {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x) as [number, number]
+  return (hi + 0.05) / (lo + 0.05)
+}