PuduLangDocgen.pudu

Pudu86 lines3.3 KB

Copy pathGitHub ↗

1/** @Docgen.Model.Module — shared documentation values across publishing phases */2module PuduLangDocgen34/** @Docgen.Model.Severity — diagnostic impact carried through every publishing phase */5export type Severity = Information | Warning | Error67/** @Docgen.Model.Diagnostic — actionable finding with stable source provenance */8export type Diagnostic = { code: Str, severity: Severity, path: Str, line: Int, message: Str }910/** @Docgen.Model.Meta — metadata value read from configuration and front matter */11export type Meta = Text(Str) | Whole(Int) | Flag(Bool) | Items(Array[Meta]) | Fields(Array[(Str, Meta)]) | Nothing1213/** @Docgen.Model.Source — named text entering the document pipeline */14export type Source = { path: Str, text: Str }1516/** @Docgen.Model.Resource — opaque bytes copied to the published site */17export type Resource = { path: Str, content: Bytes }1819/** @Docgen.Model.Heading — stable fragment and displayed section title */20export type Heading = { id: Str, title: Str, level: Int }2122/** @Docgen.Model.Link — resolved local destination retained for build validation */23export type Link = { target: Str, line: Int }2425/** @Docgen.Model.Reference — unique identity with a checked browser destination */26export type Reference = { uid: Str, name: Str, fullName: Str, href: Str, kind: Str }2728/** @Docgen.Model.TocItem — nested navigation with an optional destination */29export type TocItem = { title: Str, href: Str, uid: Str, expanded: Bool, children: Array[TocItem] }3031/** @Docgen.Model.Page — rendered content with navigable identity and metadata */32export type Page = {33  path: Str,34  source: Str,35  kind: Str,36  title: Str,37  uid: Str,38  summary: Str,39  body: Str,40  headings: Array[Heading],41  links: Array[Link],42  meta: Array[(Str, Meta)]43}4445/** @Docgen.Model.Artifact — complete text ready for confined output publication */46export type Artifact = { path: Str, content: Str }4748/** @Docgen.Model.Plan — validated text and binary output without effects */49export type Plan = { artifacts: Array[Artifact], resources: Array[Resource], diagnostics: Array[Diagnostic] }5051/** @Docgen.Model.Report — published paths and nonfatal diagnostics */52export type Report = { written: Array[Str], unchanged: Array[Str], removed: Array[Str], diagnostics: Array[Diagnostic] }5354/// A diagnostic of the given severity at a one-based source line.55export fn diagnostic(severity: Severity, code: Str, path: Str, line: Int, message: Str) -> Diagnostic {56  Diagnostic{code: code, severity: severity, path: path, line: line, message: message}57}5859/// A fatal diagnostic at a one-based source line.60export fn error(code: Str, path: Str, line: Int, message: Str) -> Diagnostic {61  diagnostic(Error, code, path, line, message)62}6364/// A warning at a one-based source line.65export fn warning(code: Str, path: Str, line: Int, message: Str) -> Diagnostic {66  diagnostic(Warning, code, path, line, message)67}6869/// Whether any diagnostic is fatal.70export fn failed(diagnostics: &Array[Diagnostic]) -> Bool {71  for held in *diagnostics {72    if held.severity == Error { return true }73  }74  false75}7677/// A diagnostic rendered as `path:line: severity CODE: message`.78export fn describe(held: &Diagnostic) -> Str {79  let label = match held.severity {80    case Information => "info"81    case Warning => "warning"82    case Error => "error"83  }84  held.path + ":" + show(held.line) + ": " + label + " " + held.code + ": " + held.message85}86