~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
192 lines · 8.0 KB Raw History
// 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
      }
    })
  }
}