chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.3.1 Latest 5 packages
0
0
// The docs: README.md and the pages in docs/, as docs/_style.md asks. Each
// page has its front matter (title, section, order unique in its section,
// summary) and no `#` heading; every relative link reaches a file, and its
// anchor a heading there (GitHub's slugs); and prose, outside code, has no
// semicolon or em dash. Files in docs/ starting with `_` are not pages.
//
// node harness/docs.mjs `just lint`
//
// Prints each problem as `file:line: what`, failing if any.
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { dirname, join, relative, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const docs = join(root, 'docs');
const sections = { HUD: [1, 99], Operations: [100, 299], Reference: [300, 999] };
const pages = readdirSync(docs)
.filter((f) => f.endsWith('.md') && !f.startsWith('_'))
.map((f) => join(docs, f));
const files = [join(root, 'README.md'), ...pages];
const problems = [];
const say = (file, line, what) => problems.push(`${relative(root, file)}:${line}: ${what}`);
// The lines of a file, each marked as code (front matter, fenced blocks) or not.
const parse = (file) => {
const lines = readFileSync(file, 'utf8').split('\n');
let fence = null;
let front = lines[0] === '---';
return lines.map((text, i) => {
if (front) {
if (i > 0 && text === '---') front = false;
return { text, code: true, front: true };
}
const open = text.match(/^\s*(`{3,}|~{3,})/);
if (fence) {
if (open && open[1][0] === fence[0] && open[1].length >= fence.length) fence = null;
return { text, code: true };
}
if (open) {
fence = open[1];
return { text, code: true };
}
return { text, code: false };
});
};
// GitHub's anchor for a heading: lowercased, punctuation dropped, spaces to
// `-`, a repeat suffixed -1, -2….
const anchors = new Map();
const anchorsOf = (file) => {
if (anchors.has(file)) return anchors.get(file);
const seen = new Map();
const set = new Set();
for (const { text, code } of parse(file)) {
const h = !code && text.match(/^#{1,6}\s+(.*?)\s*#*\s*$/);
if (!h) continue;
const base = h[1]
.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
.toLowerCase()
.replace(/[^\p{L}\p{N}\s_-]/gu, '')
.replace(/\s/g, '-');
const n = seen.get(base) ?? 0;
seen.set(base, n + 1);
set.add(n ? `${base}-${n}` : base);
}
anchors.set(file, set);
return set;
};
const orders = new Map();
for (const file of files) {
const lines = parse(file);
if (file !== files[0]) {
const front = Object.fromEntries(
lines.filter((l) => l.front && l.text !== '---').map((l) => {
const [key, ...rest] = l.text.split(':');
return [key.trim(), rest.join(':').trim().replace(/^"(.*)"$/, '$1')];
}),
);
for (const key of ['title', 'section', 'order', 'summary']) if (!front[key]) say(file, 1, `front matter has no ${key}`);
const range = sections[front.section];
const order = Number(front.order);
if (front.section && !range) say(file, 1, `section ${front.section} is none of ${Object.keys(sections).join(', ')}`);
else if (range && !(order >= range[0] && order <= range[1])) say(file, 1, `order ${front.order} is outside ${front.section}'s ${range[0]}-${range[1]}`);
else if (orders.has(order)) say(file, 1, `order ${order} is ${relative(root, orders.get(order))}'s too`);
else orders.set(order, file);
}
lines.forEach(({ text, code }, i) => {
if (code) return;
if (file !== files[0] && /^#\s/.test(text)) say(file, i + 1, 'a page has no `#` heading: its title is in front matter');
const prose = text.replace(/`[^`]*`/g, '');
for (const [, target] of prose.matchAll(/\]\(([^)\s]+)\)/g)) {
if (/^[a-z]+:/.test(target)) continue;
const [path, anchor] = target.split('#');
const to = path ? resolve(dirname(file), path) : file;
if (!existsSync(to)) say(file, i + 1, `${target}: no such file`);
else if (anchor !== undefined && to.endsWith('.md') && !anchorsOf(to).has(anchor)) say(file, i + 1, `${target}: no such heading`);
}
const words = prose.replace(/\]\([^)]*\)/g, ']').replace(/<[^>]+>/g, '').replace(/&[a-z]+;|&#\d+;/g, '');
if (words.includes(';')) say(file, i + 1, 'a semicolon in prose');
if (/—|\s--\s/.test(words)) say(file, i + 1, 'an em dash in prose');
});
}
for (const p of problems) console.log(p);
if (problems.length) process.exit(1);
console.log(`docs: README.md and ${pages.length} pages, their links and punctuation as docs/_style.md asks`);