@zebradil/docs-kit 0.0.0-stage → 0.11.0

package/schema/site.schema.json

@@ -0,0 +1,563 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Zebradil/docs-kit/schema/site.schema.json",
+  "title": "docs-kit site.yaml",
+  "description": "Content contract for a consuming project's docs/site.yaml: everything the docs site needs that is not a docs page.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "tagline", "repo", "install", "features"],
+  "properties": {
+    "name": {
+      "description": "Project name as shown in the site title and landing hero. Usually the binary or repository name.",
+      "type": "string",
+      "minLength": 1
+    },
+    "tagline": {
+      "description": "One sentence under the name on the landing hero and in the site meta description: what the project is and for whom.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160
+    },
+    "headline": {
+      "description": "Landing hero title. Defaults to 'name'.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "eyebrow": {
+      "description": "Short label above the landing hero title, e.g. the project category.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 60
+    },
+    "description": {
+      "description": "Paragraph under the landing hero title, one to three sentences; renders `inline code`. Defaults to 'tagline'.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 400
+    },
+    "theme": {
+      "description": "Design theme, one of the CSS token files shipped in packages/docs-kit/themes/<name>.css. Changes look only, never layout.",
+      "enum": ["default", "mono", "porridge", "sieve", "vortex"],
+      "default": "default"
+    },
+    "logo": {
+      "description": "Project logo shown next to the site title. Paths are relative to the docs directory and start with './', e.g. './src/assets/logo.svg'. For a favicon, put 'favicon.svg' in the docs directory's public/ folder; 'favicon.ico' and 'apple-touch-icon.png' there are linked too.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["light"],
+      "properties": {
+        "light": {
+          "description": "Logo for the light color scheme, and for both schemes when 'dark' is omitted.",
+          "type": "string",
+          "pattern": "^\\./"
+        },
+        "dark": {
+          "description": "Logo for the dark color scheme.",
+          "type": "string",
+          "pattern": "^\\./"
+        }
+      }
+    },
+    "art": {
+      "description": "Illustration in the hero, beside the title. When set, the flow panel moves to a section below the hero. Path relative to the docs directory, starting with './'. The SVG is inlined, so its own <style> can animate it and follow the color scheme with :root[data-theme='light'] selectors; it is hidden from screen readers.",
+      "type": "string",
+      "pattern": "^\\./.+\\.svg$"
+    },
+    "repo": {
+      "description": "Repository URL, used for the GitHub link and 'edit this page' links.",
+      "type": "string",
+      "pattern": "^https://"
+    },
+    "domain": {
+      "description": "Custom domain the GitHub Pages site is served at, such as 'example.dev'. The site is then built for the domain root instead of https://<owner>.github.io/<repo>/.",
+      "type": "string",
+      "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$"
+    },
+    "analytics": {
+      "description": "Web analytics script loaded, deferred, on every page. Fits any tracker configured through data attributes, such as Umami, GoatCounter, Plausible or the Cloudflare Web Analytics beacon.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["script"],
+      "properties": {
+        "script": {
+          "description": "URL of the tracker script.",
+          "type": "string",
+          "pattern": "^https://"
+        },
+        "attributes": {
+          "description": "Attributes of the script tag, such as data-website-id for Umami. Only data-* attributes, so the tag cannot carry inline event handlers.",
+          "type": "object",
+          "propertyNames": { "pattern": "^data-[a-z0-9-]+$" },
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "install": {
+      "description": "Install methods in order of preference. The first one is shown on the landing hero with a copy button; all are listed below it.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["label", "code"],
+        "properties": {
+          "label": {
+            "description": "Short method name, e.g. 'Nix', 'Cargo', 'Go', 'Homebrew'.",
+            "type": "string",
+            "minLength": 1
+          },
+          "code": {
+            "description": "Shell command that installs or runs the project, copied verbatim.",
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "features": {
+      "description": "Landing page feature grid: 3 to 6 short selling points, each grounded in what the code actually does.",
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 6,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["title", "body"],
+        "properties": {
+          "title": {
+            "description": "A few words.",
+            "type": "string",
+            "minLength": 1
+          },
+          "body": {
+            "description": "One or two sentences.",
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "flow": {
+      "description": "Panel beside the landing hero showing how the project fits with other systems: one row per connection.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["steps"],
+      "properties": {
+        "title": {
+          "description": "Panel heading. Defaults to 'How it fits'.",
+          "type": "string",
+          "minLength": 1
+        },
+        "highlight": {
+          "description": "Node name drawn filled, usually the project itself.",
+          "type": "string",
+          "minLength": 1
+        },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 5,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["from", "to", "label"],
+            "properties": {
+              "from": {
+                "description": "Left node.",
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 24
+              },
+              "to": {
+                "description": "Right node.",
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 24
+              },
+              "label": {
+                "description": "What travels between them, a few words.",
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 40
+              },
+              "arrow": {
+                "description": "Arrow direction between from and to.",
+                "enum": ["forward", "back", "both"],
+                "default": "forward"
+              }
+            }
+          }
+        },
+        "note": {
+          "description": "One sentence under the rows; renders `inline code`.",
+          "type": "string",
+          "minLength": 1
+        },
+        "art": {
+          "description": "Illustration drawn in place of the rows, which stay for screen readers. Path relative to the docs directory, starting with './'. The SVG is inlined, so its own <style> can animate it and follow the color scheme with :root[data-theme='light'] selectors; it is hidden from screen readers.",
+          "type": "string",
+          "pattern": "^\\./.+\\.svg$"
+        }
+      }
+    },
+    "diff": {
+      "description": "Landing section showing a change and what it changes in each target, as diffs: one tab per target. For projects whose output is reviewed as a diff; omit otherwise.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tabs"],
+      "properties": {
+        "title": {
+          "description": "Section heading. Defaults to 'What a change looks like'.",
+          "type": "string",
+          "minLength": 1
+        },
+        "intro": {
+          "description": "One or two sentences under the heading; renders `inline code`.",
+          "type": "string",
+          "minLength": 1
+        },
+        "change": {
+          "description": "The edit a user makes, shown beside the tabs.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["files"],
+          "properties": {
+            "label": {
+              "description": "Label above the files. Defaults to 'The change'.",
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 40
+            },
+            "files": {
+              "type": "array",
+              "maxItems": 4,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["path", "diff"],
+                "properties": {
+                  "path": {
+                    "description": "File path, shown as the title; its extension picks the syntax highlighting.",
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "diff": {
+                    "description": "Unified diff lines: '+' added, '-' removed, ' ' context, '@@' hunk headers. No file headers.",
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              },
+              "minItems": 1
+            }
+          }
+        },
+        "label": {
+          "description": "Label above the tabs. Defaults to 'What it changes'.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 40
+        },
+        "tabs": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 6,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["label", "files"],
+            "properties": {
+              "label": {
+                "description": "Target name, e.g. an environment.",
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 24
+              },
+              "files": {
+                "type": "array",
+                "maxItems": 4,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["path", "diff"],
+                  "properties": {
+                    "path": {
+                      "description": "File path, shown as the title; its extension picks the syntax highlighting.",
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "diff": {
+                      "description": "Unified diff lines: '+' added, '-' removed, ' ' context, '@@' hunk headers. No file headers.",
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                },
+                "description": "Changed files; empty shows \"No changes\"."
+              }
+            }
+          }
+        }
+      }
+    },
+    "tree": {
+      "description": "Landing section showing an inheritance tree: one tab per node with an `id`, numbering the nodes it inherits from. For projects with layered configuration; omit otherwise.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["root"],
+      "properties": {
+        "title": {
+          "description": "Section heading. Defaults to 'How settings inherit'.",
+          "type": "string",
+          "minLength": 1
+        },
+        "intro": {
+          "description": "One or two sentences beside the tree; renders `inline code`.",
+          "type": "string",
+          "minLength": 1
+        },
+        "root": {
+          "$ref": "#/$defs/treeNode"
+        }
+      }
+    },
+    "cascade": {
+      "description": "Landing panel showing one request falling through ordered tiers of backends, with one tab per scenario. For projects that route or fall back between backends; omit otherwise.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tiers", "scenarios"],
+      "properties": {
+        "title": {
+          "description": "Panel heading. Defaults to 'How a request falls through'.",
+          "type": "string",
+          "minLength": 1
+        },
+        "request": {
+          "description": "The request entering the panel, e.g. 'GET /<hash>.narinfo'; shown as code.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "hub": {
+          "description": "The project's own row between the request and the tiers.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name"],
+          "properties": {
+            "name": { "description": "Usually the project name.", "type": "string", "minLength": 1, "maxLength": 24 },
+            "body": { "description": "What it does with the request, one short sentence.", "type": "string", "minLength": 1, "maxLength": 120 }
+          }
+        },
+        "tiers": {
+          "description": "Tiers in the order a request tries them.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 4,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "backends"],
+            "properties": {
+              "name": { "description": "Tier name.", "type": "string", "minLength": 1, "maxLength": 24 },
+              "label": { "description": "Small label above the name, e.g. 'tier 1 · sequential'.", "type": "string", "minLength": 1, "maxLength": 40 },
+              "backends": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 4,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["id", "name"],
+                  "properties": {
+                    "id": { "description": "Key that scenarios use to set this backend's state.", "type": "string", "pattern": "^[a-z0-9-]+$" },
+                    "name": { "description": "Shown as code, usually a URL.", "type": "string", "minLength": 1, "maxLength": 48 }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "scenarios": {
+          "description": "One tab each. A backend a scenario does not mention is shown as not asked.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 4,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["label", "states"],
+            "properties": {
+              "label": { "description": "Tab label, a few words.", "type": "string", "minLength": 1, "maxLength": 24 },
+              "note": { "description": "One or two sentences under the tiers; renders `inline code`.", "type": "string", "minLength": 1 },
+              "states": {
+                "description": "Backend id to its state in this scenario.",
+                "type": "object",
+                "additionalProperties": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["state"],
+                  "properties": {
+                    "state": { "description": "hit: answered; miss: answered without the item; down: skipped as unreachable; idle: not asked.", "enum": ["hit", "miss", "down", "idle"] },
+                    "text": { "description": "Why, a few words.", "type": "string", "minLength": 1, "maxLength": 48 }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "components": {
+      "description": "Landing section listing the parts the project ships: commands, modules, packages.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["items"],
+      "properties": {
+        "title": {
+          "description": "Section heading. Defaults to 'Components'.",
+          "type": "string",
+          "minLength": 1
+        },
+        "intro": {
+          "description": "One or two sentences beside the list; renders `inline code`.",
+          "type": "string",
+          "minLength": 1
+        },
+        "items": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 12,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "body"],
+            "properties": {
+              "name": {
+                "description": "Name as users type it, shown as code.",
+                "type": "string",
+                "minLength": 1
+              },
+              "body": {
+                "description": "One short sentence; renders `inline code`.",
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      }
+    },
+    "links": {
+      "description": "Extra links shown on the landing page, e.g. docs.rs, pkg.go.dev, changelog. Library API docs are linked, never copied.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["label", "href"],
+        "properties": {
+          "label": { "description": "Link text.", "type": "string", "minLength": 1 },
+          "href": { "description": "Absolute URL.", "type": "string", "pattern": "^https?://" }
+        }
+      }
+    },
+    "versions": {
+      "description": "Publishes the docs of past releases next to the default branch's, which stay at the site root. Each selected minor version is served at <site>/vX.Y/ from its newest patch tag (vX.Y.Z), with a version switcher in the header that marks the newest release. A release's pages, src/assets and public/ come from its tag; site.yaml and the kit come from the default branch, so every version gets the current theme. Pre-releases and tags without the docs directory's src/content/docs are skipped.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "minors": {
+          "description": "Publishes the newest this many minor versions.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 20,
+          "default": 3
+        },
+        "majors": {
+          "description": "Publishes the newest minor version of each of the newest this many major versions. Below 1.0 every minor version counts as a major one, since semver lets it break.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 20,
+          "default": 3
+        },
+        "pin": {
+          "description": "Minor versions published whatever 'minors' and 'majors' select, e.g. a long-term support line.",
+          "type": "array",
+          "items": { "type": "string", "pattern": "^v\\d+\\.\\d+$" }
+        }
+      }
+    },
+    "reference": {
+      "description": "How refgen produces the generated pages under reference/. Omit when the project has no CLI.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "cli": {
+          "description": "CLI reference generated by walking '<bin> --help' and every subcommand.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["bin"],
+          "dependentRequired": { "build": ["path"] },
+          "properties": {
+            "bin": {
+              "description": "Command name as users type it; used for page titles and file names.",
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9._-]*$"
+            },
+            "build": {
+              "description": "Shell command, run from the repository root, that builds the binary, e.g. 'cargo build --release', 'go build -o bin/x .' or 'nix build'. Requires 'path'.",
+              "type": "string",
+              "minLength": 1
+            },
+            "path": {
+              "description": "Path to the built binary relative to the repository root, e.g. 'target/release/kasha' or 'result/bin/kasha'. When omitted, 'bin' is looked up on PATH.",
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "treeNode": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "description": "Node name, e.g. a directory; shown as code.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 40
+        },
+        "file": {
+          "description": "File the node contributes, shown beside the name.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 40
+        },
+        "note": {
+          "description": "A few words on what this level sets; renders `inline code`.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "id": {
+          "description": "Makes the node a tab: the label of a leaf that inherits from every node above it.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 24
+        },
+        "children": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 6,
+          "items": {
+            "$ref": "#/$defs/treeNode"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/validate.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Validates site.yaml files against the content contract.
+// Usage: node schema/validate.mjs <site.yaml>...
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { parse } from 'yaml';
+
+const schema = JSON.parse(readFileSync(new URL('./site.schema.json', import.meta.url), 'utf8'));
+const check = new Ajv2020({ allErrors: true }).compile(schema);
+
+/** Returns a list of human-readable errors; empty when the site config is valid. */
+export function validateSite(site) {
+  if (check(site)) return [...cascadeErrors(site.cascade), ...treeErrors(site.tree)];
+  return check.errors.map((e) => {
+    const where = e.instancePath || '(root)';
+    if (e.keyword === 'enum') return `${where} must be one of: ${e.params.allowedValues.join(', ')}`;
+    if (e.keyword === 'additionalProperties') return `${where} has unknown field '${e.params.additionalProperty}'`;
+    return `${where} ${e.message}`;
+  });
+}
+
+/** Scenario states must name backends the cascade's tiers declare, each declared once. */
+function cascadeErrors(cascade) {
+  if (!cascade) return [];
+  const ids = cascade.tiers.flatMap((t) => t.backends.map((b) => b.id));
+  const errors = [...new Set(ids.filter((id, i) => ids.indexOf(id) !== i))].map((id) => `/cascade/tiers declares backend '${id}' more than once`);
+  cascade.scenarios.forEach((s, i) => {
+    for (const id of Object.keys(s.states)) {
+      if (!ids.includes(id)) errors.push(`/cascade/scenarios/${i}/states names unknown backend '${id}'`);
+    }
+  });
+  return errors;
+}
+
+/** A tree needs at least one node with an `id`, since each one is a tab, and the ids must be unique. */
+function treeErrors(tree) {
+  if (!tree) return [];
+  const ids = [];
+  const walk = (node) => {
+    if (node.id) ids.push(node.id);
+    node.children?.forEach(walk);
+  };
+  walk(tree.root);
+  if (!ids.length) return ['/tree has no node with an id'];
+  return [...new Set(ids.filter((id, i) => ids.indexOf(id) !== i))].map((id) => `/tree declares id '${id}' more than once`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const files = process.argv.slice(2);
+  if (!files.length) {
+    console.error('usage: validate.mjs <site.yaml>...');
+    process.exit(2);
+  }
+  let failed = false;
+  for (const file of files) {
+    const errors = validateSite(parse(readFileSync(file, 'utf8')));
+    for (const err of errors) console.error(`${file}: ${err}`);
+    if (errors.length) failed = true;
+    else console.log(`${file}: ok`);
+  }
+  process.exit(failed ? 1 : 0);
+}