@norskvideo/ctl-dev-kit 0.2.54 → 0.2.56

package/docs/guide-stubs.ts

@@ -0,0 +1,304 @@
+#!/usr/bin/env bun
+// Recorded guides: the placeholder a docs site builds against when a guide's
+// capture has not run, and the gate that refuses to publish one.
+//
+// A site's recorded guides (the Playwright doc-guide output under a gitignored
+// `docs/generated/`) reach the site as SYMLINKS under its content dir --
+// `website/src/content/docs/guides/<slug> -> ../../../../../docs/generated/<slug>`
+// -- and adding a guide means adding one. The symlinks are the one declaration
+// of which guides exist: there is no list restated here and no name glob (the
+// `zero-to-hero-*` glob this once carried skipped a Manager slug, and the site
+// failed to build for a guide the gate was never even asked about). Each
+// symlink also names the tree it stubs into, so one module serves every site:
+// norsk-ctl's, the Manager's, and each product's.
+//
+//   stub <content-dir>...       write a placeholder index.md for every declared
+//                               guide whose target is missing, creating the
+//                               tree, never touching a file that exists -- so
+//                               `docs:site` builds on a checkout with no captures.
+//   list <content-dir>...       the stub file each declared guide would get
+//                               (absolute, each once), writing nothing; a
+//                               Makefile takes its prerequisites from this.
+//   check [--allow-stub <name>[,<name>]] [--allow-missing <dir>[,<dir>]]
+//         [--content <content-dir>]... <generated-dir>...
+//                               exit 1 naming each placeholder it would publish.
+//                               A generated dir given directly must be populated
+//                               (an unpopulated tree is not a passing one; the
+//                               release run's captures were not restored).
+//                               --content names a site's content dir instead:
+//                               its symlink targets are the guides, and a site
+//                               that declares none has nothing to refuse -- a
+//                               product site publishes from committed prose and
+//                               must stay green with no captures anywhere.
+//                               --allow-stub names guides whose stub is a
+//                               `::warning::` rather than a refusal (the cloud
+//                               guides, captured weekly while the site publishes
+//                               nightly); --allow-missing names generated dirs
+//                               that may not exist yet.
+//   summary [--content <dir>]... <generated-dir>...
+//                               a Markdown table for the job summary: each
+//                               guide, live capture or stub, and what it was
+//                               captured against (the page's front matter).
+//
+// Why the gate: a placeholder is right for a local build and wrong for a
+// deploy. A publish that runs without the captures restored would REPLACE the
+// live guides with placeholders, and nothing else would notice -- the build is
+// green, the links resolve, the pages are just empty. The sentence `stub`
+// writes is what `check` refuses, and both live here so they cannot drift.
+import { existsSync, mkdirSync, readdirSync, readFileSync, readlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+
+/** The sentence a placeholder carries, and the one `check` refuses. */
+export const GUIDE_STUB_MARKER = "Content for this guide is recorded by the doc-guide run";
+
+/** Generated directories that are not recorded guides: `cli docgen` writes
+ *  cli-reference as help-all.md, so it has no index.md to stub or to be a
+ *  stub of. */
+export const NOT_A_GUIDE = new Set(["cli-reference"]);
+
+/** A guide a site declares: the symlink's name, and the index.md its target
+ *  implies. */
+export interface DeclaredGuide {
+  name: string;
+  /** Absolute path of the symlink. */
+  link: string;
+  /** Absolute path of the target's index.md -- which may not exist. */
+  stub: string;
+}
+
+export interface GuideFile {
+  path: string;
+  /** The guide directory's name -- what `--allow-stub` matches. */
+  name: string;
+  text: string;
+}
+
+function isGeneratedTarget(target: string): boolean {
+  return target.split("/").includes("generated");
+}
+
+/** The guides a site declares: every symlink under each content dir that
+ *  points into a `generated` tree. A content dir that does not exist yet is
+ *  skipped. Resolved as path arithmetic, not realpath: on a fresh checkout the
+ *  target's parents do not exist. */
+export function declaredGuides(contentDirs: readonly string[]): DeclaredGuide[] {
+  const out: DeclaredGuide[] = [];
+  for (const contentDir of contentDirs) {
+    const dir = resolve(contentDir);
+    if (!existsSync(dir)) continue;
+    const entries = readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isSymbolicLink() && !NOT_A_GUIDE.has(e.name))
+      .map((e) => e.name)
+      .sort();
+    for (const name of entries) {
+      const link = join(dir, name);
+      const target = readlinkSync(link);
+      if (!isGeneratedTarget(target)) continue;
+      out.push({ name, link, stub: resolve(dirname(link), target, "index.md") });
+    }
+  }
+  return out;
+}
+
+/** The same stub reached through two sites' symlinks is one file. */
+function uniqueByStub(guides: DeclaredGuide[]): DeclaredGuide[] {
+  const seen = new Set<string>();
+  return guides.filter((g) => !seen.has(g.stub) && seen.add(g.stub));
+}
+
+export function listGuideStubs(contentDirs: readonly string[]): string[] {
+  return uniqueByStub(declaredGuides(contentDirs)).map((g) => g.stub);
+}
+
+export function stubText(name: string): string {
+  return `---\ntitle: ${name}\n---\n\n${GUIDE_STUB_MARKER}. Run \`bun run docs:guides\` locally to populate it.\n`;
+}
+
+/** Write a placeholder for every declared guide whose index.md is missing.
+ *  A file that exists -- a real capture, or an earlier placeholder -- is never
+ *  rewritten. */
+export function stubGuides(contentDirs: readonly string[]): { written: string[]; existing: string[] } {
+  const written: string[] = [];
+  const existing: string[] = [];
+  for (const guide of uniqueByStub(declaredGuides(contentDirs))) {
+    if (existsSync(guide.stub)) {
+      existing.push(guide.stub);
+      continue;
+    }
+    mkdirSync(dirname(guide.stub), { recursive: true });
+    writeFileSync(guide.stub, stubText(guide.name));
+    written.push(guide.stub);
+  }
+  return { written, existing };
+}
+
+export function stubbedGuides(files: readonly { path: string; text: string }[]): string[] {
+  if (files.length === 0) throw new Error("no guides found -- docs/generated was never populated");
+  return files.filter((f) => f.text.includes(GUIDE_STUB_MARKER)).map((f) => f.path);
+}
+
+/** What a rendered page says it was captured against (the doc-guide renderer
+ *  writes the block; the values are quoted strings). */
+export function capturedAgainst(text: string): { norsk?: string; norskMgr?: string; when?: string } {
+  const head = text.split(/^---$/m)[1] ?? "";
+  const block = /^capturedAgainst:\n((?:[ ]{2}\w+: "[^"\n]*"\n)+)/m.exec(head)?.[1] ?? "";
+  const out: Record<string, string> = {};
+  for (const m of block.matchAll(/^[ ]{2}(\w+): "([^"\n]*)"$/gm)) out[m[1]] = m[2];
+  return out;
+}
+
+/** The job-summary table: one row per guide. */
+export function summaryTable(files: readonly GuideFile[]): string {
+  const rows = files.map((f) => {
+    if (f.text.includes(GUIDE_STUB_MARKER)) return `| \`${f.path}\` | **stub** | — |`;
+    const a = capturedAgainst(f.text);
+    const against = [a.norskMgr && `norsk-mgr ${a.norskMgr}`, a.norsk && `Norsk Manager ${a.norsk}`]
+      .filter(Boolean)
+      .join(", ");
+    return `| \`${f.path}\` | live capture | ${a.when ? `${a.when}${against ? ` — ${against}` : ""}` : "(no capturedAgainst)"} |`;
+  });
+  return ["| guide | content | captured |", "| --- | --- | --- |", ...rows].join("\n");
+}
+
+/** A guide directory without its index.md is as unpublishable as a stub. */
+function readGuide(path: string, name: string, file: string): GuideFile {
+  try {
+    return { path, name, text: readFileSync(file, "utf8") };
+  } catch {
+    return { path, name, text: GUIDE_STUB_MARKER };
+  }
+}
+
+export class GuideTreeMissing extends Error {}
+
+export interface ReadGuidesOptions {
+  /** Generated dirs that may not exist yet: a warning, not a refusal. */
+  allowMissing?: ReadonlySet<string>;
+  warn?: (message: string) => void;
+}
+
+/** Every guide under each generated dir. A dir that does not exist is a
+ *  restore failure (GuideTreeMissing) unless it is allowed missing: for a
+ *  section whose captures come from a run that may not have happened yet,
+ *  refusing would take the whole site down with it. */
+export function readGuides(dirs: readonly string[], opts: ReadGuidesOptions = {}): GuideFile[] {
+  const allowMissing = opts.allowMissing ?? new Set();
+  const warn = opts.warn ?? ((m) => console.error(m));
+  const files: GuideFile[] = [];
+  for (const dir of dirs) {
+    let names: string[] = [];
+    try {
+      names = readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !NOT_A_GUIDE.has(e.name))
+        .map((e) => e.name)
+        .sort();
+    } catch {
+      if (allowMissing.has(resolve(dir))) {
+        warn(`::warning::guide check: ${dir} has never been captured -- its pages will be stubs`);
+        continue;
+      }
+      throw new GuideTreeMissing(`${dir} does not exist -- the release run's captures were not restored`);
+    }
+    // Paths are reported under the package's name so two roots' guides cannot
+    // be confused (norsk-ctl's and norsk-mgr's roots are both called
+    // docs/generated; the package dir two levels up tells them apart).
+    const label = dirs.length > 1 ? `${basename(resolve(dir, "../.."))}/${basename(dir)}/` : "";
+    for (const name of names) files.push(readGuide(`${label}${name}/index.md`, name, join(dir, name, "index.md")));
+  }
+  return files;
+}
+
+/** The guides a site declares, read from their symlink targets. Reported
+ *  relative to the working directory, which is where the workflow runs. */
+export function readDeclaredGuides(contentDirs: readonly string[], cwd = process.cwd()): GuideFile[] {
+  return uniqueByStub(declaredGuides(contentDirs)).map((g) => readGuide(relative(cwd, g.stub), g.name, g.stub));
+}
+
+function usage(): never {
+  console.error(
+    [
+      "usage: guide-stubs.ts stub <content-dir>...",
+      "       guide-stubs.ts list <content-dir>...",
+      "       guide-stubs.ts check [--allow-stub <name>[,<name>]] [--allow-missing <dir>[,<dir>]] [--content <dir>]... <generated-dir>...",
+      "       guide-stubs.ts summary [--content <dir>]... <generated-dir>...",
+    ].join("\n"),
+  );
+  process.exit(2);
+}
+
+if (import.meta.main) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const allowStub = new Set<string>();
+  const allowMissing = new Set<string>();
+  const contentDirs: string[] = [];
+  const dirs: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i] as string;
+    if (arg === "--allow-stub") {
+      for (const n of (rest[++i] ?? "").split(",")) if (n) allowStub.add(n);
+    } else if (arg === "--allow-missing") {
+      for (const d of (rest[++i] ?? "").split(",")) if (d) allowMissing.add(resolve(d));
+    } else if (arg === "--content") {
+      contentDirs.push(rest[++i] ?? usage());
+    } else if (arg.startsWith("-")) usage();
+    else dirs.push(arg);
+  }
+
+  if (cmd === "stub" || cmd === "list") {
+    if (contentDirs.length > 0 || dirs.length === 0) usage();
+    if (cmd === "list") {
+      for (const f of listGuideStubs(dirs)) console.log(f);
+    } else {
+      for (const f of stubGuides(dirs).written) console.log(`stubbed ${f}`);
+    }
+    process.exit(0);
+  }
+  if ((cmd !== "check" && cmd !== "summary") || (dirs.length === 0 && contentDirs.length === 0)) usage();
+
+  let files: GuideFile[];
+  try {
+    files = [...readGuides(dirs, { allowMissing }), ...readDeclaredGuides(contentDirs)];
+  } catch (e) {
+    if (!(e instanceof GuideTreeMissing)) throw e;
+    console.error(`::error::guide check: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (cmd === "summary") {
+    console.log(summaryTable(files));
+    process.exit(0);
+  }
+
+  if (files.length === 0 && dirs.length === 0) {
+    console.log(`guide check: no recorded guides are declared by ${contentDirs.join(", ")}; nothing to refuse.`);
+    process.exit(0);
+  }
+
+  let stubs: string[];
+  try {
+    stubs = stubbedGuides(files);
+  } catch (e) {
+    console.error(`::error::guide check: ${(e as Error).message}`);
+    process.exit(1);
+  }
+
+  // A tolerated stub is a warning; a tree of nothing but tolerated stubs is
+  // still an unpopulated tree.
+  const tolerated = files.filter((f) => stubs.includes(f.path) && allowStub.has(f.name)).map((f) => f.path);
+  const refused = stubs.filter((s) => !tolerated.includes(s));
+  for (const s of tolerated) {
+    console.error(
+      `::warning::guide check: ${s} is a placeholder -- publishing without it (no capture yet, or none saved)`,
+    );
+  }
+  if (refused.length > 0) {
+    console.error(`::error::guide check: ${refused.length} guide(s) are placeholders, refusing to publish:`);
+    for (const s of refused) console.error(`  ${s}`);
+    process.exit(1);
+  }
+  if (tolerated.length === files.length) {
+    console.error("::error::guide check: every guide is a placeholder -- docs/generated was never populated");
+    process.exit(1);
+  }
+  console.log(`guide check: ${files.length} guide(s), ${tolerated.length} tolerated stub(s), the rest real.`);
+}

package/docs/journeys.ts

@@ -0,0 +1,217 @@
+#!/usr/bin/env bun
+// The journey-table lint (documentation plan, October 2026, "Who we write for").
+// Each product's docs/personas.md carries one table saying where each of the
+// four readers starts, which pages they read in order, and where they are
+// handed off — ctl's manual for the Administrator and the Integrator. The
+// table is the product's statement of its journeys; this checks that it exists,
+// covers every persona once, keeps each route to five pages, names only pages
+// that exist, and always ends in a hand-off. A site path `/docs/x/` resolves to
+// website/src/content/docs/x.{md,mdx} or x/index.{md,mdx}; a bare `name.md`
+// resolves under docs/; an https link is a hand-off and is not resolved.
+//
+// Usage: bun journeys.ts [--root <dir>] [--personas docs/personas.md]
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const PERSONAS = ["Evaluator", "Builder", "Integrator", "Administrator"] as const;
+export const MAX_PAGES = 5;
+
+export interface JourneyRow {
+  persona: string;
+  startsAt: string[];
+  next: string[];
+  handsOffTo: string;
+  /** 1-based line of the row in the personas file. */
+  line: number;
+}
+
+export interface JourneyTable {
+  rows: JourneyRow[];
+  /** 1-based line of the header row. */
+  line: number;
+}
+
+export interface JourneyFinding {
+  file: string;
+  line: number;
+  message: string;
+}
+
+const CELL_PATH = /`([^`]+)`|\]\(([^)]+)\)|(^|\s)(\/docs\/\S*|\S+\.mdx?)(?=\s|,|$)/g;
+
+/** Every path-like reference in a table cell: backticked, a markdown link
+ *  target, or a bare `/docs/...` or `*.md` token. */
+export function cellPaths(cell: string): string[] {
+  const out: string[] = [];
+  for (const m of cell.matchAll(CELL_PATH)) {
+    const p = (m[1] ?? m[2] ?? m[4] ?? "").trim();
+    if (p) out.push(p);
+  }
+  return out;
+}
+
+/** A persona cell may be bold or a link to its section; the name is the text. */
+function plainText(cell: string): string {
+  return cell
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replace(/[*_`]/g, "")
+    .trim();
+}
+
+function splitRow(line: string): string[] {
+  return line
+    .trim()
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split("|")
+    .map((c) => c.trim());
+}
+
+export function parseJourneyTable(markdown: string): JourneyTable | undefined {
+  const lines = markdown.split("\n");
+  for (let i = 0; i < lines.length - 1; i++) {
+    const line = lines[i] ?? "";
+    if (!line.trim().startsWith("|")) continue;
+    const header = splitRow(line).map((c) => c.toLowerCase());
+    const col = (want: string) => header.findIndex((h) => h.startsWith(want));
+    const persona = col("persona");
+    const startsAt = col("starts at");
+    const then = col("then");
+    const handsOff = col("hands off");
+    if (persona < 0 || startsAt < 0 || then < 0 || handsOff < 0) continue;
+    if (!/^\s*\|?\s*:?-+/.test(lines[i + 1] ?? "")) continue;
+    const rows: JourneyRow[] = [];
+    for (let j = i + 2; j < lines.length; j++) {
+      const row = lines[j] ?? "";
+      if (!row.trim().startsWith("|")) break;
+      const cells = splitRow(row);
+      rows.push({
+        persona: plainText(cells[persona] ?? ""),
+        startsAt: cellPaths(cells[startsAt] ?? ""),
+        next: cellPaths(cells[then] ?? ""),
+        handsOffTo: cells[handsOff] ?? "",
+        line: j + 1,
+      });
+    }
+    return { rows, line: i + 1 };
+  }
+  return undefined;
+}
+
+const SITE_DOCS = "website/src/content/docs";
+
+function hasReaders(root: string): boolean {
+  return (
+    existsSync(join(root, SITE_DOCS)) ||
+    existsSync(join(root, "website", "astro.config.mjs")) ||
+    existsSync(join(root, "docs", "quickstart.md"))
+  );
+}
+
+/** Where a route's page lives in the repo, or undefined for a link that is a
+ *  hand-off rather than a page (https, mailto). */
+export function candidatePaths(ref: string): string[] | undefined {
+  const bare = ref.replace(/[#?].*$/, "");
+  if (/^[a-z]+:/i.test(bare)) return undefined;
+  if (bare.startsWith("/docs/") || bare === "/docs") {
+    const rel = bare.replace(/^\/docs\/?/, "").replace(/\/$/, "");
+    const base = rel === "" ? "index" : rel;
+    return [
+      `${SITE_DOCS}/${base}.mdx`,
+      `${SITE_DOCS}/${base}.md`,
+      `${SITE_DOCS}/${base}/index.mdx`,
+      `${SITE_DOCS}/${base}/index.md`,
+    ];
+  }
+  if (bare.startsWith("docs/")) return [bare];
+  return [`docs/${bare}`, bare];
+}
+
+export function checkJourneys(root: string, personasFile = "docs/personas.md"): JourneyFinding[] {
+  const file = join(root, personasFile);
+  if (!existsSync(file)) {
+    // A repo with no site and no quickstart has no readers to route: a
+    // backend-only turnkey ships a handover to one customer and is not asked
+    // for four journeys. Anything with a Start here page is.
+    if (!hasReaders(root)) return [];
+    return [
+      {
+        file: personasFile,
+        line: 1,
+        message: "missing; every product keeps its persona mapping and journey table here (conventions/personas.md).",
+      },
+    ];
+  }
+  const table = parseJourneyTable(readFileSync(file, "utf8"));
+  if (!table) {
+    return [
+      {
+        file: personasFile,
+        line: 1,
+        message:
+          'no journey table: expected a table with columns Persona | Starts at | Then, in order | Hands off to (documentation plan, "Who we write for").',
+      },
+    ];
+  }
+  const findings: JourneyFinding[] = [];
+  const seen = new Map<string, number>();
+  for (const row of table.rows) {
+    seen.set(row.persona, (seen.get(row.persona) ?? 0) + 1);
+    const pages = [...row.startsAt, ...row.next];
+    if (pages.length > MAX_PAGES) {
+      findings.push({
+        file: personasFile,
+        line: row.line,
+        message: `${row.persona}: ${pages.length} pages on the route; the limit is ${MAX_PAGES}. A sixth page is in the wrong section or should not exist.`,
+      });
+    }
+    for (const ref of pages) {
+      const candidates = candidatePaths(ref);
+      if (!candidates) continue;
+      if (!candidates.some((c) => existsSync(join(root, c)))) {
+        findings.push({
+          file: personasFile,
+          line: row.line,
+          message: `${row.persona}: ${ref} is not a page in this repo (looked for ${candidates.join(", ")}).`,
+        });
+      }
+    }
+    if (!/\S/.test(row.handsOffTo) || cellPaths(row.handsOffTo).length === 0) {
+      findings.push({
+        file: personasFile,
+        line: row.line,
+        message: `${row.persona}: no hand-off. Every route ends in a link: the next section, or norsk-ctl's manual.`,
+      });
+    }
+  }
+  for (const persona of PERSONAS) {
+    const n = seen.get(persona) ?? 0;
+    if (n === 0)
+      findings.push({ file: personasFile, line: table.line, message: `${persona} has no row in the journey table.` });
+    else if (n > 1)
+      findings.push({
+        file: personasFile,
+        line: table.line,
+        message: `${persona} has ${n} rows in the journey table; one route each.`,
+      });
+  }
+  return findings;
+}
+
+if (import.meta.main) {
+  const argv = process.argv.slice(2);
+  let root = process.cwd();
+  let personas = "docs/personas.md";
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--root") root = argv[++i] ?? root;
+    else if (argv[i] === "--personas") personas = argv[++i] ?? personas;
+  }
+  const findings = checkJourneys(root, personas);
+  if (findings.length === 0) {
+    console.log("journeys: OK");
+  } else {
+    console.error(`journeys: ${findings.length} finding${findings.length === 1 ? "" : "s"}`);
+    for (const f of findings) console.error(`  - ${f.file}:${f.line}: ${f.message}`);
+    process.exit(1);
+  }
+}