~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
110 lines · 4.4 KB Raw History
// 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`);