Fix issue #79: Implement documentation
All checks were successful
Test / test (push) Successful in 2s

This commit is contained in:
Gitea OpenCode Agent
2026-10-15 19:07:09 +00:00
parent a8a1e0ca41
commit 788f69efd3
27 changed files with 1731 additions and 70 deletions

328
tests/docs.test.js Normal file
View File

@@ -0,0 +1,328 @@
// Tests for the documentation under /docs (Syndria98/dragonroll#79): the markdown pages are the
// documentation, so what has to stay right is (1) the pages are well formed — a title, a slug, a
// numbered group, translations for the group's label, and no link pointing at a page that does not
// exist, (2) the page about an integration really documents what that integration offers, which is
// checked against the sources that define it: the slash commands of discord-bot/src/commands.js and
// the commands the Obsidian plugin registers, and (3) the routes: /docs and /docs/<slug> render the
// documentation and every other address still opens the window app.
//
// `frontend/app/services/DocsMarkdown.js` is the pure part of the docs (headings, slugs, titles) and
// is loaded straight from source, the way the other tests load the frontend services; it imports
// nothing, so the repository root's no-dependencies rule holds. `Docs.js` itself is not loaded: it
// reads the markdown through `import.meta.glob`, which only Vite can answer.
//
// Run with `npm test` from the repository root, or `node --test tests/`.
const { test } = require("node:test");
const assert = require("node:assert/strict");
const fs = require("node:fs");
const path = require("node:path");
const vm = require("node:vm");
function readRepoFile(...parts) {
return fs.readFileSync(path.join(__dirname, "..", ...parts), "utf8");
}
function loadDocsMarkdown() {
const source = readRepoFile("frontend", "app", "services", "DocsMarkdown.js");
return vm.compileFunction(source.replace("export {", "return {") , [], {
parsingContext: vm.createContext({}),
})();
}
const docs = loadDocsMarkdown();
// The documentation pages, as the folder layout defines them.
const docsRoot = path.join(__dirname, "..", "frontend", "app", "content", "docs");
const docPages = fs.readdirSync(docsRoot, { withFileTypes: true })
.filter((entry) => entry.isDirectory())
.sort((left, right) => left.name.localeCompare(right.name))
.flatMap((group) => fs.readdirSync(path.join(docsRoot, group.name))
.filter((file) => file.endsWith(".md"))
.sort()
.map((file) => ({
group: group.name.replace(/^\d+-/, ""),
slug: file.replace(/^\d+-/, "").replace(/\.md$/, ""),
markdown: fs.readFileSync(path.join(docsRoot, group.name, file), "utf8"),
}))
);
const slugs = new Set(docPages.map((page) => page.slug));
const groups = [...new Set(docPages.map((page) => page.group))];
const pageAbout = (slug) => docPages.find((page) => page.slug === slug);
// --- The heading helpers the sidebar and the anchors are built from ---
test("a heading's slug comes out of its words, whatever form they arrive in", () => {
assert.equal(docs.Slugify("Link a world"), "link-a-world");
assert.equal(docs.Slugify(" Auto-sync, and one actor "), "auto-sync-and-one-actor");
assert.equal(docs.Slugify("Dragonroll: Force Sync!"), "dragonroll-force-sync");
});
test("the anchor built from a heading's markdown is the one built from its HTML", () => {
// The sidebar slugs the markdown source and the renderer slugs what marked produced, so the two
// have to land on the same anchor for a sidebar link to land on its section.
const pairs = [
["**Link** a `world`", "<strong>Link</strong> a <code>world</code>"],
["Commands & characters", "Commands &amp; characters"],
["[Foundry](/docs/foundry) worlds", '<a href="/docs/foundry">Foundry</a> worlds'],
["It's here", "It&#39;s here"],
];
for (const [markdown, html] of pairs) {
assert.equal(docs.Slugify(markdown), docs.Slugify(html), `slug of ${markdown}`);
}
});
test("repeated headings get distinct anchors, in the order they are written", () => {
const slug = docs.CreateHeadingSlugger();
assert.equal(slug("Setup"), "setup");
assert.equal(slug("setup"), "setup-1");
assert.equal(slug("Setup"), "setup-2");
});
test("the headings of a page are listed in order, with their anchors", () => {
const headings = docs.HeadingsFromMarkdown([
"# Connecting a service",
"",
"## How a connection works",
"text",
"### What it allows",
"```sh",
"# not a heading",
"```",
"## Next",
].join("\n"));
// The service is loaded from another realm, so the values are copied out before being compared.
assert.deepEqual(
JSON.parse(JSON.stringify(headings.map(({ depth, text, slug }) => ({ depth, text, slug })))),
[
{ depth: 1, text: "Connecting a service", slug: "connecting-a-service" },
{ depth: 2, text: "How a connection works", slug: "how-a-connection-works" },
{ depth: 3, text: "What it allows", slug: "what-it-allows" },
{ depth: 2, text: "Next", slug: "next" },
]
);
});
test("a page takes its title from its first heading", () => {
assert.equal(docs.TitleFromMarkdown("# Your first campaign\n\n## Signing in"), "Your first campaign");
assert.equal(docs.TitleFromMarkdown("no heading here"), "");
});
// --- The pages themselves ---
test("the documentation has pages, in numbered groups", () => {
assert.ok(docPages.length >= 5, `expected several documentation pages, found ${docPages.length}`);
for (const page of docPages) {
const folder = `${page.group}`;
assert.ok(folder.length > 0, `${page.slug} sits in an oddly named folder`);
assert.match(page.slug, /^[a-z0-9]+(-[a-z0-9]+)*$/, `${page.slug} is not a url-friendly slug`);
}
});
test("every page has a title, and no two pages share a slug", () => {
const seen = new Set();
for (const page of docPages) {
const title = docs.TitleFromMarkdown(page.markdown);
assert.ok(title, `${page.slug} has no heading to title it`);
assert.ok(!seen.has(page.slug), `${page.slug} is published twice`);
seen.add(page.slug);
}
assert.equal(seen.size, docPages.length);
});
test("every page has sections, which is what the sidebar lists beside it", () => {
for (const page of docPages) {
const sections = docs.HeadingsFromMarkdown(page.markdown).filter((heading) => heading.depth > 1);
assert.ok(sections.length, `${page.slug} has no section headings to list`);
}
});
test("every group has a sidebar label in every locale", () => {
const labels = ["en", "es", "ca"].map((locale) =>
JSON.parse(readRepoFile("frontend", "i18n", "locales", locale, "docs.json"))
);
assert.ok(labels.every((label) => label.groups), "each docs.json namespace needs a `groups` object");
for (const group of groups) {
for (const label of labels) {
const text = label.groups[group];
assert.ok(text, `the "${group}" group has no label in its docs.json`);
assert.notEqual(text, group, `the "${group}" label is untranslated`);
}
}
});
test("the pages only link to pages that are published", () => {
for (const page of docPages) {
for (const link of page.markdown.matchAll(/\]\((\/docs\/?[a-z0-9-]*)\)/g)) {
const target = link[1].replace("/docs/", "");
if (!target) continue; // /docs itself
assert.ok(slugs.has(target), `${page.slug} links to ${link[1]}, which is not published`);
}
}
});
test("the three integrations each have their own page", () => {
for (const slug of ["discord", "foundry", "obsidian"]) {
assert.ok(pageAbout(slug), `${slug} has no documentation page`);
}
assert.ok(pageAbout("connecting-a-service"), "the shared way of connecting a service is undocumented");
});
// --- The integrations pages describe what the integrations actually offer ---
// discord-bot/src/commands.js builds the slash commands with discord.js, which the repository root
// does not install: the builder is stubbed by one that records the names it is given.
function loadSlashCommands() {
const registered = [];
class Builder {
constructor() {
this.name = "";
this.parent = null;
this.children = [];
this.optionNames = [];
}
setName(name) { this.name = name; return this; }
setDescription() { return this; }
setContexts() { return this; }
setRequired() { return this; }
setMaxLength() { return this; }
setAutocomplete() { return this; }
addChoices() { return this; }
addStringOption(configure) { configure(new Builder()); return this; }
addBooleanOption(configure) { configure(new Builder()); return this; }
addSubcommand(configure) {
const sub = new Builder();
sub.parent = this;
configure(sub);
this.children.push(sub);
return this;
}
}
class SlashCommandBuilder extends Builder {
constructor() {
super();
registered.push(this);
}
}
const moduleStub = { exports: {} };
vm.compileFunction(readRepoFile("discord-bot", "src", "commands.js"), ["require", "module", "exports"])(
(id) => {
if (id === "discord.js") return { InteractionContextType: { Guild: 0 }, SlashCommandBuilder };
throw new Error(`require("${id}") is not stubbed`);
},
moduleStub,
moduleStub.exports
);
const names = [];
for (const command of registered) {
names.push(command.name);
for (const sub of command.children) names.push(`${command.name} ${sub.name}`);
}
return names;
}
test("the Discord page lists every command the bot declares", () => {
const about = pageAbout("discord");
const commands = loadSlashCommands();
// Sanity check on the stub before it is trusted to list anything.
assert.ok(commands.includes("characters"), `expected the bot's commands, got ${commands.join(", ")}`);
assert.ok(commands.includes("dragonroll connect"));
for (const command of commands) {
assert.ok(
about.markdown.includes("`/" + command),
`the Discord page does not document /${command}`
);
}
});
// The Obsidian plugin registers each command palette entry with `this.addCommand({ id, name, … })`.
function loadObsidianCommands() {
const source = readRepoFile("obsidian-plugin", "main.js");
const commands = [...source.matchAll(
/this\.addCommand\(\{\s*id:\s*["']([^"']+)["'],\s*name:\s*["']([^"']+)["']/g
)].map((match) => ({ id: match[1], name: match[2] }));
// Sanity check on the extraction before it is trusted to list anything.
assert.ok(commands.length >= 2, `expected the plugin's commands, got ${commands.length}`);
return commands;
}
test("the Obsidian page lists the commands the plugin registers", () => {
const about = pageAbout("obsidian");
for (const command of loadObsidianCommands()) {
assert.ok(
about.markdown.includes(`**${command.name}**`),
`the Obsidian page does not document "${command.name}" (${command.id})`
);
}
});
test("the Foundry page covers what the world and the campaign do with each other", () => {
const about = pageAbout("foundry").markdown;
for (const topic of ["Auto-sync", "Force Sync", "item directory", "Pairing Status"]) {
assert.ok(about.includes(topic), `the Foundry page never mentions ${topic}`);
}
});
// --- The routes ---
test("the app renders whichever page the address asks for", () => {
const root = readRepoFile("frontend", "app", "app.vue");
assert.match(root, /<NuxtPage\s*\/?>/, "app.vue has to render the matched page");
assert.doesNotMatch(root, /CreateWindow/, "the window app boots from AppShell, not from app.vue");
});
test("the documentation has a route of its own, and the app keeps the rest", () => {
const pages = path.join("frontend", "app", "pages");
const docsRoutes = ["docs/index.vue", "docs/[slug].vue"];
for (const route of docsRoutes) {
assert.match(
readRepoFile(pages, route),
/<DocsView\s*\/?>/,
`${route} has to render the documentation`
);
}
for (const route of ["index.vue", "[...all].vue"]) {
assert.match(
readRepoFile(pages, route),
/<AppShell\s*\/?>/,
`${route} has to open the window app`
);
}
// The catch-all is what keeps /link/authorize, and every path a service already links to, alive.
const shell = readRepoFile("frontend", "app", "components", "views", "AppShell.vue");
assert.ok(shell.includes("/link/authorize"), "the service link screen has to stay reachable");
assert.ok(shell.includes("/discord/authorize"), "the legacy Discord link has to stay reachable");
});
test("the main menu points at the documentation", () => {
const menu = readRepoFile("frontend", "app", "components", "windows", "MainMenuWindow.vue");
assert.match(menu, /href="\/docs"/, "the main menu has to link to /docs");
assert.match(menu, /main-menu\.documentation/);
for (const locale of ["en", "es", "ca"]) {
const strings = JSON.parse(readRepoFile("frontend", "i18n", "locales", locale, "main-menu.json"));
assert.ok(strings.documentation, `${locale} has no label for the documentation link`);
}
});