@hgdc/docs 0.0.0-stage → 0.1.1

package/src/build/public-files.ts

@@ -0,0 +1,35 @@
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { extname, join, relative } from "node:path"
+
+const IGNORED_DIRS = new Set(["node_modules", "dist", ".hgdc-docs", ".git", ".github", ".vercel"])
+
+/** Dossiers d'images publiés tels quels ; `public/` est servi à la racine du site. */
+export const ASSET_DIRS = ["images", "img", "logo", "assets", "static"]
+const MEDIA = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg", ".ico", ".mp4", ".webm", ".woff2"])
+
+/**
+ * Fichiers statiques publiés, et seulement ceux-là : le logo et le favicon déclarés dans
+ * docs.json, les médias des dossiers d'images (`images/`, `logo/`…), et tout `public/`.
+ * Un `.txt` ou un `.pdf` oublié ailleurs dans le dépôt n'est jamais mis en ligne.
+ */
+export function publicFiles(contentDir: string, declared: ReadonlyArray<string>): Array<{ from: string; to: string }> {
+  const files: Array<{ from: string; to: string }> = []
+  const walk = (dir: string, onlyMedia: boolean, base: string) => {
+    if (!existsSync(dir)) return
+    for (const name of readdirSync(dir)) {
+      if (name.startsWith(".") || IGNORED_DIRS.has(name)) continue
+      const path = join(dir, name)
+      if (statSync(path).isDirectory()) walk(path, onlyMedia, base)
+      else if (!onlyMedia || MEDIA.has(extname(name).toLowerCase()))
+        files.push({ from: path, to: relative(base, path) })
+    }
+  }
+  for (const folder of ASSET_DIRS) walk(join(contentDir, folder), true, contentDir)
+  walk(join(contentDir, "public"), false, join(contentDir, "public"))
+  for (const asset of declared) {
+    const from = join(contentDir, asset.replace(/^\/+/, ""))
+    if (relative(contentDir, from).startsWith("..") || !existsSync(from)) continue
+    files.push({ from, to: relative(contentDir, from) })
+  }
+  return files
+}

package/src/components/Accordion.astro

@@ -0,0 +1,12 @@
+---
+interface Props {
+  title: string
+  defaultOpen?: boolean
+}
+const { title, defaultOpen = false } = Astro.props
+---
+
+<details class="hgdc-accordion" open={defaultOpen}>
+  <summary>{title}</summary>
+  <div class="hgdc-accordion__body"><slot /></div>
+</details>

package/src/components/AccordionGroup.astro

@@ -0,0 +1,4 @@
+---
+---
+
+<div class="hgdc-accordion-group"><slot /></div>

package/src/components/Card.astro

@@ -0,0 +1,15 @@
+---
+interface Props {
+  title: string
+  href?: string
+  /** Accepté pour la compatibilité Mintlify, ignoré : les icônes de Mintlify sont propriétaires. */
+  icon?: string
+}
+const { title, href } = Astro.props
+const Tag = href ? "a" : "div"
+---
+
+<Tag class:list={["hgdc-card", { "hgdc-card--link": href }]} href={href}>
+  <span class="hgdc-card__title">{title}</span>
+  <div class="hgdc-card__body"><slot /></div>
+</Tag>

package/src/components/CardGroup.astro

@@ -0,0 +1,8 @@
+---
+interface Props {
+  cols?: number
+}
+const { cols = 2 } = Astro.props
+---
+
+<div class="hgdc-card-group not-content" style={`--hgdc-cols:${Math.min(Math.max(cols, 1), 4)}`}><slot /></div>

package/src/components/Check.astro

@@ -0,0 +1,10 @@
+---
+import { Aside } from "@astrojs/starlight/components"
+
+interface Props {
+  title?: string
+}
+const { title } = Astro.props
+---
+
+<Aside type="tip" title={title}><slot /></Aside>

package/src/components/CodeGroup.astro

@@ -0,0 +1,4 @@
+---
+---
+
+<div class="hgdc-code-group"><slot /></div>

package/src/components/Columns.astro

@@ -0,0 +1,8 @@
+---
+interface Props {
+  cols?: number
+}
+const { cols = 2 } = Astro.props
+---
+
+<div class="hgdc-card-group not-content" style={`--hgdc-cols:${Math.min(Math.max(cols, 1), 4)}`}><slot /></div>

package/src/components/Danger.astro

@@ -0,0 +1,10 @@
+---
+import { Aside } from "@astrojs/starlight/components"
+
+interface Props {
+  title?: string
+}
+const { title } = Astro.props
+---
+
+<Aside type="danger" title={title}><slot /></Aside>

package/src/components/Frame.astro

@@ -0,0 +1,11 @@
+---
+interface Props {
+  caption?: string
+}
+const { caption } = Astro.props
+---
+
+<figure class="hgdc-frame">
+  <slot />
+  {caption && <figcaption>{caption}</figcaption>}
+</figure>

package/src/components/Info.astro

@@ -0,0 +1,10 @@
+---
+import { Aside } from "@astrojs/starlight/components"
+
+interface Props {
+  title?: string
+}
+const { title = "Info" } = Astro.props
+---
+
+<Aside type="note" title={title}><slot /></Aside>

package/src/components/Note.astro

@@ -0,0 +1,10 @@
+---
+import { Aside } from "@astrojs/starlight/components"
+
+interface Props {
+  title?: string
+}
+const { title } = Astro.props
+---
+
+<Aside type="note" title={title}><slot /></Aside>

package/src/components/Step.astro

@@ -0,0 +1,11 @@
+---
+interface Props {
+  title: string
+}
+const { title } = Astro.props
+---
+
+<li class="hgdc-step">
+  <p class="hgdc-step__title">{title}</p>
+  <div class="hgdc-step__body"><slot /></div>
+</li>

package/src/components/Steps.astro

@@ -0,0 +1,4 @@
+---
+---
+
+<ol class="hgdc-steps"><slot /></ol>

package/src/components/Tab.astro

@@ -0,0 +1,9 @@
+---
+import { TabItem } from "@astrojs/starlight/components"
+
+interface Props {
+  title: string
+}
+---
+
+<TabItem label={Astro.props.title}><slot /></TabItem>

package/src/components/Tabs.astro

@@ -0,0 +1,9 @@
+---
+import { Tabs } from "@astrojs/starlight/components"
+
+interface Props {
+  syncKey?: string
+}
+---
+
+<Tabs syncKey={Astro.props.syncKey}><slot /></Tabs>

package/src/components/Tip.astro

@@ -0,0 +1,10 @@
+---
+import { Aside } from "@astrojs/starlight/components"
+
+interface Props {
+  title?: string
+}
+const { title } = Astro.props
+---
+
+<Aside type="tip" title={title}><slot /></Aside>

package/src/components/Warning.astro

@@ -0,0 +1,10 @@
+---
+import { Aside } from "@astrojs/starlight/components"
+
+interface Props {
+  title?: string
+}
+const { title } = Astro.props
+---
+
+<Aside type="caution" title={title}><slot /></Aside>

package/src/core/answer-markdown.ts

@@ -0,0 +1,109 @@
+/**
+ * Markdown restreint des réponses de l'assistant → arbre de nœuds, rendu ensuite en DOM
+ * avec `textContent` seulement : aucun HTML de la réponse n'est jamais interprété. Une
+ * réponse du modèle reste une donnée non fiable, même quand elle cite la doc.
+ */
+export type Inline =
+  | { type: "text"; value: string }
+  | { type: "strong" | "em"; children: Array<Inline> }
+  | { type: "code"; value: string }
+  | { type: "link"; href: string; children: Array<Inline> }
+  | { type: "ref"; n: number }
+
+export type Block =
+  | { type: "paragraph"; children: Array<Inline> }
+  | { type: "heading"; children: Array<Inline> }
+  | { type: "list"; ordered: boolean; items: Array<Array<Inline>> }
+  | { type: "code"; language: string | null; value: string }
+
+/**
+ * Liens permis : chemins du site, ancres, et adresses des origines données (le site de la
+ * doc). Un lien vers ailleurs, même en https, devient du texte : une page injectée ne peut
+ * pas faire afficher un lien de hameçonnage par l'assistant.
+ */
+export function safeHref(href: string, origins: ReadonlyArray<string> = []): string | null {
+  const value = href.trim()
+  if (value.startsWith("#")) return value
+  if (value.startsWith("/") && !value.startsWith("//") && !value.startsWith("/\\")) return value
+  try {
+    const url = new URL(value)
+    const web = url.protocol === "https:" || url.protocol === "http:"
+    return web && origins.includes(url.origin) ? url.toString() : null
+  } catch {
+    return null
+  }
+}
+
+const INLINE = /(`[^`]+`)|(\*\*[^*]+\*\*)|(\*[^*\s][^*]*\*|_[^_\s][^_]*_)|(\[\^(\d+)\])|(\[([^\]]+)\]\(([^)\s]+)\))/
+
+export function parseInline(source: string, origins: ReadonlyArray<string> = []): Array<Inline> {
+  const out: Array<Inline> = []
+  let rest = source
+  while (rest) {
+    const match = INLINE.exec(rest)
+    if (!match) {
+      out.push({ type: "text", value: rest })
+      break
+    }
+    if (match.index > 0) out.push({ type: "text", value: rest.slice(0, match.index) })
+    const [whole, code, strong, em, ref, refN, link, linkText, linkHref] = match
+    if (code) out.push({ type: "code", value: code.slice(1, -1) })
+    else if (strong) out.push({ type: "strong", children: parseInline(strong.slice(2, -2), origins) })
+    else if (em) out.push({ type: "em", children: parseInline(em.slice(1, -1), origins) })
+    else if (ref && refN) out.push({ type: "ref", n: Number(refN) })
+    else if (link && linkText && linkHref) {
+      const href = safeHref(linkHref, origins)
+      out.push(
+        href ? { type: "link", href, children: parseInline(linkText, origins) } : { type: "text", value: linkText },
+      )
+    }
+    rest = rest.slice(match.index + whole.length)
+  }
+  return out
+}
+
+const LIST = /^\s*(?:([-*])|(\d+)[.)])\s+(.*)$/
+
+export function parseMarkdown(source: string, origins: ReadonlyArray<string> = []): Array<Block> {
+  const blocks: Array<Block> = []
+  const lines = source.replace(/\r\n?/g, "\n").split("\n")
+  let paragraph: Array<string> = []
+  const flush = () => {
+    if (paragraph.length) blocks.push({ type: "paragraph", children: parseInline(paragraph.join(" "), origins) })
+    paragraph = []
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    const fence = /^\s*```\s*([\w+-]*)\s*$/.exec(line)
+    if (fence) {
+      flush()
+      const body: Array<string> = []
+      while (++i < lines.length && !/^\s*```\s*$/.test(lines[i]!)) body.push(lines[i]!)
+      blocks.push({ type: "code", language: fence[1] || null, value: body.join("\n") })
+      continue
+    }
+    const heading = /^#{1,6}\s+(.*)$/.exec(line)
+    if (heading) {
+      flush()
+      blocks.push({ type: "heading", children: parseInline(heading[1]!, origins) })
+      continue
+    }
+    const item = LIST.exec(line)
+    if (item) {
+      flush()
+      const ordered = Boolean(item[2])
+      const previous = blocks.at(-1)
+      const list =
+        previous?.type === "list" && previous.ordered === ordered && lines[i - 1]?.trim() !== ""
+          ? previous
+          : (blocks[blocks.push({ type: "list", ordered, items: [] }) - 1] as Extract<Block, { type: "list" }>)
+      list.items.push(parseInline(item[3]!, origins))
+      continue
+    }
+    if (line.trim() === "") flush()
+    else paragraph.push(line.trim())
+  }
+  flush()
+  return blocks
+}

package/src/core/assistant-api.ts

@@ -0,0 +1,65 @@
+import { z } from "zod"
+
+/**
+ * Contrat de `POST /api/v1/ask` entre le widget du site et la console. Une seule source,
+ * importée des deux côtés : un champ ajouté ici est vu par le build et par l'API.
+ */
+export const MAX_QUESTION = 1000
+export const MAX_PREVIOUS = 3
+
+export const askRequestSchema = z.object({
+  project: z.string().regex(/^[a-z0-9]{8,64}$/),
+  question: z.string().trim().min(2).max(MAX_QUESTION),
+  /** Chemin de la page ouverte : l'assistant la privilégie dans sa recherche. */
+  page: z.string().startsWith("/").max(512).optional(),
+  /**
+   * Échanges précédents, par leur identifiant (`id` des réponses) : le serveur relit ce qu'il a
+   * lui-même répondu. Un visiteur ne peut pas glisser une fausse réponse de l'assistant.
+   */
+  previous: z
+    .array(z.string().regex(/^[a-z0-9]{8,64}$/))
+    .max(MAX_PREVIOUS)
+    .optional(),
+})
+
+export type AskRequest = z.infer<typeof askRequestSchema>
+
+export const sourceSchema = z.object({
+  n: z.number().int().positive(),
+  title: z.string(),
+  section: z.string().nullable(),
+  url: z.string(),
+})
+
+export type AnswerSource = z.infer<typeof sourceSchema>
+
+export const askResponseSchema = z.object({
+  id: z.string(),
+  /** `no_answer` : rien dans la doc ne répond, l'assistant le dit au lieu d'inventer. */
+  status: z.enum(["answered", "no_answer"]),
+  /** Markdown restreint ; `[^n]` renvoie à la source `n`. */
+  answer: z.string(),
+  sources: z.array(sourceSchema),
+})
+
+export type AskResponse = z.infer<typeof askResponseSchema>
+
+export const ASK_ERRORS = {
+  invalid_request: "La question n'a pas pu être lue.",
+  project_not_found: "Cette documentation n'a pas d'assistant.",
+  assistant_disabled: "L'assistant est désactivé pour cette documentation.",
+  origin_not_allowed: "Cet assistant ne répond que depuis son site de documentation.",
+  rate_limited: "Trop de questions d'un coup. Réessaie dans une minute.",
+  quota_exceeded: "L'assistant a atteint sa limite de questions pour ce mois.",
+  not_indexed: "La documentation n'est pas encore indexée. Réessaie après la prochaine publication.",
+  unavailable: "L'assistant ne répond pas pour l'instant. Réessaie dans un moment.",
+} as const
+
+export type AskErrorCode = keyof typeof ASK_ERRORS
+
+export const askErrorSchema = z.object({
+  error: z.object({
+    code: z.enum(Object.keys(ASK_ERRORS) as [AskErrorCode, ...Array<AskErrorCode>]),
+    message: z.string(),
+  }),
+})

package/src/core/chunk.ts

@@ -0,0 +1,134 @@
+import GithubSlugger from "github-slugger"
+
+/**
+ * Découpe une page en passages pour la recherche de l'assistant : une section par titre
+ * (`##` à `######`), coupée en paragraphes si elle dépasse `MAX_CHARS`. Chaque passage
+ * garde l'ancre de son titre, calculée comme les identifiants de Starlight (github-slugger),
+ * pour que la source citée ouvre la bonne section.
+ */
+export const MAX_CHARS = 1600
+const MIN_CHARS = 120
+
+export type Chunk = {
+  /** Fil des titres, page comprise : « Publier › Avec Host ». */
+  heading: string
+  anchor: string | null
+  text: string
+}
+
+type Section = { trail: Array<string>; anchor: string | null; lines: Array<string> }
+
+/** Au-delà, une ligne n'est pas un titre : la borne garde l'analyse linéaire. */
+const MAX_HEADING_LINE = 500
+
+/**
+ * Titre ATX (`## Titre`, fermeture `##` facultative), lu caractère par caractère : pas
+ * d'expression régulière à quantificateurs chevauchants, donc pas de retour arrière
+ * explosif sur une ligne piégée (« ## a » suivi de milliers d'espaces).
+ */
+export function parseHeading(line: string): { level: number; text: string } | null {
+  if (line.length > MAX_HEADING_LINE || !line.startsWith("#")) return null
+  let level = 0
+  while (line[level] === "#") level++
+  if (level > 6 || (line[level] !== " " && line[level] !== "\t")) return null
+  let text = line.slice(level).trim()
+  let end = text.length
+  while (end > 0 && text[end - 1] === "#") end--
+  if (end < text.length && (end === 0 || text[end - 1] === " " || text[end - 1] === "\t"))
+    text = text.slice(0, end).trim()
+  return text ? { level, text } : null
+}
+const FENCE = /^\s*(```|~~~)/
+
+export function chunkPage(title: string, markdown: string): Array<Chunk> {
+  const slugger = new GithubSlugger()
+  const sections: Array<Section> = [{ trail: [], anchor: null, lines: [] }]
+  const stack: Array<{ level: number; text: string }> = []
+  let fence: string | null = null
+
+  for (const line of markdown.replace(/\r\n?/g, "\n").split("\n")) {
+    const fenceMatch = FENCE.exec(line)
+    if (fenceMatch) fence = fence === null ? fenceMatch[1]! : fence === fenceMatch[1] ? null : fence
+    const heading = fence === null && !fenceMatch ? parseHeading(line) : null
+    if (!heading) {
+      sections.at(-1)!.lines.push(line)
+      continue
+    }
+    const level = heading.level
+    const text = stripInline(heading.text)
+    if (level === 1) continue // le titre de la page, déjà porté par `title`
+    while (stack.length && stack.at(-1)!.level >= level) stack.pop()
+    stack.push({ level, text })
+    sections.push({ trail: stack.map((s) => s.text), anchor: slugger.slug(text), lines: [] })
+  }
+
+  const chunks: Array<Chunk> = []
+  for (const section of sections) {
+    const body = section.lines.join("\n").trim()
+    if (!body) continue
+    const heading = [title, ...section.trail].join(" › ")
+    for (const part of splitBody(body)) chunks.push({ heading, anchor: section.anchor, text: part })
+  }
+  return mergeSmall(chunks)
+}
+
+/** Paragraphes regroupés jusqu'à `MAX_CHARS`, sans couper un bloc de code. */
+function splitBody(body: string): Array<string> {
+  if (body.length <= MAX_CHARS) return [body]
+  const blocks: Array<string> = []
+  let current: Array<string> = []
+  let fence = false
+  for (const line of body.split("\n")) {
+    if (FENCE.test(line)) fence = !fence
+    if (!fence && line.trim() === "" && current.length) {
+      blocks.push(current.join("\n"))
+      current = []
+      continue
+    }
+    current.push(line)
+  }
+  if (current.length) blocks.push(current.join("\n"))
+
+  const parts: Array<string> = []
+  let buffer = ""
+  for (const block of blocks) {
+    if (buffer && buffer.length + block.length + 2 > MAX_CHARS) {
+      parts.push(buffer)
+      buffer = ""
+    }
+    buffer = buffer ? `${buffer}\n\n${block}` : block
+    while (buffer.length > MAX_CHARS * 2) {
+      parts.push(buffer.slice(0, MAX_CHARS))
+      buffer = buffer.slice(MAX_CHARS)
+    }
+  }
+  if (buffer) parts.push(buffer)
+  return parts
+}
+
+/** Un passage très court rejoint le suivant de la même section : seul, il ne répond à rien. */
+function mergeSmall(chunks: Array<Chunk>): Array<Chunk> {
+  const merged: Array<Chunk> = []
+  for (const chunk of chunks) {
+    const previous = merged.at(-1)
+    if (previous && previous.text.length < MIN_CHARS && previous.anchor === chunk.anchor) {
+      previous.text = `${previous.text}\n\n${chunk.text}`
+      continue
+    }
+    merged.push({ ...chunk })
+  }
+  return merged
+}
+
+function stripInline(text: string): string {
+  return text
+    .replace(/`([^`]*)`/g, "$1")
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/[*_]/g, "")
+    .trim()
+}
+
+/** Texte envoyé au modèle d'embeddings : le contexte du titre aide à retrouver un passage court. */
+export function embeddingText(chunk: Chunk): string {
+  return `${chunk.heading}\n\n${chunk.text}`
+}