chadtmiller.com/monolith
An atproto PDS
0
0
// The pages' links, written to read in the repository, made the site's:
// a link to a file the site makes a page of goes to that page, any other
// to the file in the repository. A link to a file or heading that is not
// there fails the build, so a renamed page or section is caught where it
// is linked. In the specification, which names its pages as code
// (`LIMITS.md`) rather than linking them, each such name is made a link.
// A method named as code (`createSession`, or its NSID) links to its entry
// in the methods reference, the first time in each section, so a page that
// names it often is not a page of links. And a link to a page of the site
// that reads as the file's name reads as the page's title instead: what
// the reader sees in the sidebar and at the top of the page.
import { existsSync, readFileSync, statSync } from 'node:fs'
import { join, posix } from 'node:path'
import { methodNamed, pageAt, pages, REPO, root, title, url } from './content.mjs'
const text = (node) => (node.value ?? '') + (node.children ?? []).map(text).join('')
const titles = new Map()
/** The title of the site's page made from `source`. */
function titleOf(source) {
if (!titles.has(source)) titles.set(source, title(readFileSync(join(root, source), 'utf8'), source))
return titles.get(source)
}
const walk = (node, visit, parent) => {
visit(node, parent)
for (const child of node.children ?? []) walk(child, visit, node)
}
/** A heading's anchor, as GitHub and the site make it. */
const slug = (s) =>
s
.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
.trim()
.toLowerCase()
.replace(/[^\p{L}\p{N}_\- ]/gu, '')
.replaceAll(' ', '-')
const anchorsOf = new Map()
/** The anchors of a Markdown file's headings, outside its code blocks. */
function anchors(path) {
if (!anchorsOf.has(path)) {
const seen = new Map()
const out = new Set()
let fenced = false
for (const line of readFileSync(join(root, path), 'utf8').split('\n')) {
if (line.startsWith('```')) fenced = !fenced
const m = !fenced && line.match(/^#{1,6}\s+(.*)/)
if (!m) continue
const s = slug(m[1])
const n = seen.get(s) ?? 0
seen.set(s, n + 1)
out.add(n ? `${s}-${n}` : s)
}
anchorsOf.set(path, out)
}
return anchorsOf.get(path)
}
/** The repository file a relative link written in `source` names, or null for any other link. */
const targetOf = (source, link) => {
if (/^[a-z]+:|^\//.test(link)) return null
const path = link.split('#')[0]
return path ? posix.normalize(posix.join(posix.dirname(source), path)).replace(/\/$/, '') : source
}
/** Where a link written in `source` lands: a page of the site, or a file in the repository. */
function resolve(source, link) {
const target = targetOf(source, link)
if (target === null) return link
const [path, anchor] = link.split('#')
if (!existsSync(join(root, target))) throw new Error(`${source}: a link to ${path}, which is not there`)
if (anchor && target.endsWith('.md') && !anchors(target).has(anchor))
throw new Error(`${source}: a link to #${anchor}, no heading of ${target}`)
const hash = anchor ? `#${anchor}` : ''
const page = pages().find((p) => p.source === target)
if (page) return url(page.slug) + hash
const away = upstream(target)
if (away) return away.url + hash
const kind = statSync(join(root, target)).isDirectory() ? 'tree' : 'blob'
return `${REPO}/${kind}/main/${target}${hash}`
}
/** The MCP revision `spec/mcp/` holds, as its schema names it. */
const MCP_REVISION = readFileSync(join(root, 'spec/mcp/schema.ts'), 'utf8').match(
/LATEST_PROTOCOL_VERSION = "([^"]+)"/,
)[1]
/** A vendored page's title: its MDX header's, or its frontmatter's, or its first heading's. */
const vendoredTitle = (path) => {
const t = readFileSync(join(root, path), 'utf8')
return (t.match(/^\s*title:\s*'([^']+)'/m) ?? t.match(/^title:\s*(.+)$/m) ?? t.match(/^# (.+)$/m))?.[1].trim()
}
/**
* Where a spec the repository keeps a copy of is published, and how to name
* it: atproto's on atproto.com, the RFCs on rfc-editor.org, the draft on the
* IETF's datatracker, MCP's on modelcontextprotocol.io. The copies are the
* spec's to build from; the reader of the site is better served by the
* published page. Null for a file published nowhere else.
*/
function upstream(target) {
let m
if ((m = target.match(/^spec\/atproto\/([\w-]+)\.md$/)))
return { url: `https://atproto.com/specs/${m[1]}`, text: `atproto's ${vendoredTitle(target)} spec` }
if ((m = target.match(/^spec\/rfc\/rfc(\d+)\.txt$/)))
return { url: `https://www.rfc-editor.org/rfc/rfc${m[1]}`, text: `RFC ${m[1]}` }
if (target === 'spec/rfc/draft-client-id-metadata-document.txt')
return {
url: 'https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/',
text: 'the client ID metadata document draft',
}
if ((m = target.match(/^spec\/mcp\/(?:legacy\/([\d-]+)\/)?([\w/-]*?)(?:\/index)?(?:\.md)?\/?$/))) {
if (target.endsWith('LICENSE') || target.endsWith('.json') || target.endsWith('.ts')) return null
const page = m[2] ? `/${m[2]}` : ''
const file = statSync(join(root, target)).isDirectory() ? join(target, 'index.md') : target
const name = existsSync(join(root, file)) ? vendoredTitle(file) : null
return {
url: `https://modelcontextprotocol.io/specification/${m[1] ?? MCP_REVISION}${page}`,
text: name ? `MCP's ${name} spec${m[1] ? ` (${m[1]})` : ''}` : null,
}
}
return null
}
/**
* A link's words, when they are only the name of the file it goes to: the
* title of the site's page made from it, or the name of the published spec
* it is a copy of.
*/
function titleFor(source, link, words) {
const target = targetOf(source, link)
if (target === null) return null
const path = link.split('#')[0]
if (![path, target, posix.basename(target)].includes(words.trim())) return null
if (pages().some((p) => p.source === target && !p.generated)) return titleOf(target)
return upstream(target)?.text ?? null
}
export function remarkLinks() {
return (tree, file) => {
const page = pageAt(file.path)
if (!page) throw new Error(`${file.path}: no page of the site`)
const spec = page.source.startsWith('spec/')
const methodsPage = url('reference/methods')
let linked = new Set()
walk(tree, (node, parent) => {
if (node.type === 'heading') linked = new Set()
// The spec heads a table's column of what each row is "Is"; a reader
// of the site looks for "Description".
if (node.type === 'table') {
const head = node.children[0]?.children ?? []
for (const cell of head)
if (cell.children.length === 1 && cell.children[0].type === 'text' && cell.children[0].value === 'Is')
cell.children[0].value = 'Description'
}
if (node.type === 'link') {
const named = titleFor(page.source, node.url, text(node))
if (named) node.children = [{ type: 'text', value: named }]
node.url = resolve(page.source, node.url)
} else if (node.type === 'definition') node.url = resolve(page.source, node.url)
else if (
spec &&
node.type === 'inlineCode' &&
parent?.type !== 'link' &&
/^[\w./-]+(\.md|\.txt|\/)$/.test(node.value) &&
existsSync(join(root, posix.join(posix.dirname(page.source), node.value)))
) {
const named = titleFor(page.source, node.value, node.value)
const shown = named ? { type: 'text', value: named } : { ...node }
node.type = 'link'
node.url = resolve(page.source, node.value)
node.children = [shown]
delete node.value
} else if (
node.type === 'inlineCode' &&
parent?.type !== 'link' &&
parent?.type !== 'heading' &&
page.source !== 'spec/.methods.md'
) {
const id = methodNamed(node.value, page.source)
if (!id || linked.has(id)) return
linked.add(id)
node.children = [{ ...node }]
node.type = 'link'
node.url = `${methodsPage}#${slug(id)}`
delete node.value
}
})
}
}