@erclx/canon 4.114.0 → 4.116.0

package/src/teach/components/paragraph.tsx

@@ -4,9 +4,26 @@ import type { Child, Element } from '@/teach/html/jsx-runtime'
 export interface ParagraphProps {
   /** The lesson's dek, read back by `extractLessonMeta` in `@/teach/nav`. */
   readonly lede?: boolean
+  /** Reference numbers, each linking to the `Refs` item carrying that id. */
+  readonly cites?: readonly number[]
   readonly children: Child
 }
 
-export function Paragraph({ lede, children }: ParagraphProps): Element {
-  return lede ? <p class="lede">{children}</p> : <p>{children}</p>
+export function Paragraph({ lede, cites, children }: ParagraphProps): Element {
+  const markers = (cites ?? []).map((cite) => (
+    <sup class="cite">
+      <a href={`#r${cite}`}>{cite}</a>
+    </sup>
+  ))
+  return lede ? (
+    <p class="lede">
+      {children}
+      {markers}
+    </p>
+  ) : (
+    <p>
+      {children}
+      {markers}
+    </p>
+  )
 }

package/src/teach/components/refs.tsx

@@ -0,0 +1,28 @@
+/** @jsxImportSource ../html */
+import type { Element } from '@/teach/html/jsx-runtime'
+
+export interface Reference {
+  readonly title: string
+  readonly url?: string
+  readonly note?: string
+}
+
+export interface RefsProps {
+  readonly items: readonly Reference[]
+}
+
+/**
+ * Numbers each item from 1 so its `id` matches the `#r<n>` a cited
+ * `Paragraph` links to. The caller has already checked every `url` parses as
+ * http or https, since attribute escaping does not stop a `javascript:` href.
+ */
+export function Refs({ items }: RefsProps): Element {
+  const rendered = items.map(({ title, url, note }, index) => (
+    <li id={`r${index + 1}`}>
+      <cite>{title}</cite>
+      {note === undefined ? null : `. ${note}`}
+      {url === undefined ? null : [' ', <a href={url}>{new URL(url).host}</a>]}
+    </li>
+  ))
+  return <ol class="refs">{rendered}</ol>
+}

package/src/teach/cross-references.ts

@@ -0,0 +1,78 @@
+export interface LessonReferencesLinked {
+  readonly html: string
+  /** Four-digit numbers naming no lesson, each once, in first-seen order. */
+  readonly unresolved: readonly string[]
+}
+
+/**
+ * A mention a learner would read as pointing at another lesson. The whitespace
+ * is captured rather than normalized, since a prettier-wrapped lesson can break
+ * a mention across a line.
+ */
+const MENTION = /\b(lesson|Lesson)(\s+)(\d{4})\b/g
+
+/**
+ * A link nav wrote on an earlier run, and the only kind it may rewrite. The
+ * close tag allows whitespace before its `>`, which is how prettier wraps it.
+ */
+const OWNED_LINK = /<a\s[^>]*\bdata-lesson-ref\b[^>]*>([\s\S]*?)<\/a\s*>/g
+
+/**
+ * A comment, a raw-text element taken whole so a `<` inside a script never
+ * reads as a tag, any other tag, or the text between tags.
+ */
+const TOKEN =
+  /<!--[\s\S]*?-->|<(script|style)\b[\s\S]*?<\/\1\s*>|<\/?[a-zA-Z][^>]*>|[^<]+|</g
+
+const TAG_NAME = /^<(\/?)([a-zA-Z][a-zA-Z0-9-]*)/
+
+/**
+ * Elements whose text stays plain. A link inside a quiz `label` navigates on
+ * the click meant to pick an option, and one inside `summary` fights the
+ * toggle.
+ */
+const SKIPPED = new Set(['a', 'code', 'pre', 'label', 'summary'])
+
+/**
+ * Links every "lesson NNNN" mention in a lesson's authored region to the
+ * sibling file carrying that number, and reports the numbers naming no lesson.
+ * A link carrying `data-lesson-ref` is nav's own, so it is unwrapped and
+ * resolved again from its text, which re-points it after a slug rename and
+ * drops it once its target is gone. An author's own `<a>` is never touched.
+ */
+export function linkLessonReferences(
+  html: string,
+  targets: ReadonlyMap<string, string>,
+  current: string,
+): LessonReferencesLinked {
+  const unresolved: string[] = []
+  let depth = 0
+
+  const linkText = (text: string): string =>
+    text.replace(MENTION, (mention, word, space, number: string) => {
+      const target = targets.get(number)
+      if (target === current) return mention
+      if (target === undefined) {
+        if (!unresolved.includes(number)) unresolved.push(number)
+        return mention
+      }
+      return `<a href="${target}" data-lesson-ref>${word}${space}${number}</a>`
+    })
+
+  const unwrapped = html.replace(OWNED_LINK, (_link, text: string) => text)
+
+  const rewritten = unwrapped.replace(TOKEN, (token) => {
+    if (!token.startsWith('<') || token === '<') {
+      return depth === 0 ? linkText(token) : token
+    }
+
+    const tag = TAG_NAME.exec(token)
+    if (tag === null || !SKIPPED.has(tag[2].toLowerCase())) return token
+
+    if (tag[1] === '/') depth = Math.max(0, depth - 1)
+    else if (!token.endsWith('/>')) depth += 1
+    return token
+  })
+
+  return { html: rewritten, unresolved }
+}

package/src/teach/lesson.ts

@@ -13,7 +13,7 @@ import {
 const LESSON_WIDTH = 4
 
 /** The ordinal a lesson filename opens with, which fixes its read order. */
-const LESSON_NUMBER = /^(\d{4})-/
+export const LESSON_NUMBER = /^(\d{4})-/
 
 const LESSON_SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/
 

package/src/teach/nav.ts

@@ -1,19 +1,23 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { readFile, writeFile } from 'node:fs/promises'
-import { join, relative } from 'node:path'
+import { readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join, posix, relative } from 'node:path'
 import {
   TEACH_SIDEBAR_BREAKPOINT,
   TEACH_STYLESHEET_COMPONENTS,
 } from '@/design/components'
 import { buildDesignCss } from '@/design/css'
 import { FAVICON_COLORS, faviconLink, renderFavicon } from '@/design/favicon'
+import { stripFrontmatter } from '@/frontmatter'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { PROJECT_ROOT } from '@/project-root'
+import { linkLessonReferences } from '@/teach/cross-references'
 import { TEACH_FONT_FACES } from '@/teach/fonts'
+import { LESSON_NUMBER } from '@/teach/lesson'
 import {
   listWorkspaces,
   readWorkspace,
   TEACH_ASSETS,
+  TEACH_GLOSSARY,
   TEACH_LESSONS,
   TEACH_MISSION,
   TEACH_REFERENCE,
@@ -695,6 +699,8 @@ function pageHead(
   title: string,
   cssHref: string | undefined,
   embeddedCss: string | undefined,
+  page: 'index' | 'lesson' = 'index',
+  extraHead = '',
 ): string {
   const style =
     embeddedCss === undefined
@@ -706,10 +712,10 @@ function pageHead(
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escapeHtml(title)}</title>
+${extraHead}<title>${escapeHtml(title)}</title>
 ${teachFavicon()}
 ${style}
-${headScript('index')}
+${headScript(page)}
 </head>
 `
 }
@@ -1015,13 +1021,15 @@ async function readLessonMetas(
  * on disk: the mission, the lessons already written, the reference pages, and
  * the glossary. A workspace with no `index.html` yet gets one the same way a
  * workspace that already had one gets its rewrite, since both read the same
- * sources.
+ * sources. A reference row links the rendered sibling, or the markdown itself
+ * on a Bun that cannot render one, so no row points at a file never written.
  */
 async function renderContentsPage(
   root: string,
   workspaces: readonly WorkspaceSummary[],
   detail: WorkspaceDetail,
   metas: readonly LessonMeta[],
+  canRenderMarkdown: boolean,
 ): Promise<string> {
   const missionPath = join(root, detail.path, TEACH_MISSION)
   const description = existsSync(missionPath)
@@ -1076,9 +1084,10 @@ async function renderContentsPage(
       detail.referenceFiles.map(async (file, index) => {
         const title = await readTitle(
           join(root, detail.path, TEACH_REFERENCE, file),
-          basenameTitle(file),
+          referenceFallbackTitle(file),
         )
-        return `<li><a href="${TEACH_REFERENCE}/${file}"><span class="num">R${index + 1}</span><b>${escapeHtml(title)}</b></a></li>`
+        const target = canRenderMarkdown ? renderedReferenceName(file) : file
+        return `<li><a href="${TEACH_REFERENCE}/${target}"><span class="num">R${index + 1}</span><b>${escapeHtml(title)}</b></a></li>`
       }),
     )
   ).join('')
@@ -1117,6 +1126,157 @@ ${renderScripts(false, true)}
 `
 }
 
+/**
+ * Marks a reference page as nav's own output, which is the one test nav applies
+ * before deleting a page whose markdown source is gone. A hand-written HTML
+ * file beside the reference pages carries none and is never touched.
+ */
+const REFERENCE_GENERATOR = '<meta name="generator" content="canon teach nav">'
+
+/** A formatter closes the tag as `/>`, which still marks the page as generated. */
+const REFERENCE_GENERATOR_PATTERN =
+  /<meta name="generator" content="canon teach nav"\s*\/?>/
+
+function renderedReferenceName(file: string): string {
+  return file.replace(/\.md$/, '.html')
+}
+
+function referenceFallbackTitle(file: string): string {
+  return titleCase(file.replace(/\.md$/, ''))
+}
+
+/**
+ * A relative href landing on another reference page's markdown is retargeted
+ * to its rendered sibling, and one landing on the workspace glossary goes to
+ * the glossary the contents page renders under `#gloss`, dropping any fragment
+ * since the entries there carry no per-term anchor. The resources page has no
+ * rendered form, so a blanket suffix swap would break a link to it.
+ */
+function retargetReferenceLinks(
+  html: string,
+  referenceFiles: ReadonlySet<string>,
+): string {
+  return html.replace(
+    /href="([^"#?:]+)\.md([#?][^"]*)?"/g,
+    (match, stem: string, suffix: string | undefined) => {
+      const target = posix.normalize(posix.join(TEACH_REFERENCE, `${stem}.md`))
+      if (target === TEACH_GLOSSARY) return 'href="../index.html#gloss"'
+
+      const [folder, file, ...rest] = target.split('/')
+      if (folder !== TEACH_REFERENCE || rest.length > 0) return match
+      if (!referenceFiles.has(file)) return match
+      return `href="${stem}.html${suffix ?? ''}"`
+    },
+  )
+}
+
+/**
+ * One reference page as a styled page carrying the workspace chrome. The
+ * markdown beside it stays the durable, promotable half, and this file is
+ * regenerated from it on every run. Raw HTML in the markdown is escaped rather
+ * than passed through, since a reference page is plain markdown by contract.
+ */
+async function renderReferencePage(
+  root: string,
+  workspaces: readonly WorkspaceSummary[],
+  detail: WorkspaceDetail,
+  metas: readonly LessonMeta[],
+  file: string,
+): Promise<string> {
+  const source = await readFile(
+    join(root, detail.path, TEACH_REFERENCE, file),
+    'utf8',
+  )
+  const title =
+    readField(parseFrontmatter(source), 'title') ?? referenceFallbackTitle(file)
+
+  const rendered = retargetReferenceLinks(
+    Bun.markdown.html(stripFrontmatter(source), {
+      noHtmlBlocks: true,
+      noHtmlSpans: true,
+    }),
+    new Set(detail.referenceFiles),
+  )
+  const body = /<h1[\s>]/.test(rendered)
+    ? rendered
+    : `<h1>${escapeHtml(title)}</h1>\n${rendered}`
+
+  const teachPrefix = '../../'
+  const workspacePrefix = '../'
+
+  const header = renderHeader(
+    [
+      {
+        label: 'Workspaces',
+        href: `${teachPrefix}index.html`,
+        jump: {
+          ariaLabel: 'Switch workspace',
+          entries: workspaceJumpEntries(workspaces, teachPrefix, detail.slug),
+        },
+      },
+      {
+        label: workspaceLabel(detail),
+        href: `${workspacePrefix}index.html`,
+        jump: {
+          ariaLabel: 'Jump to a lesson',
+          entries: lessonJumpEntries(metas, workspacePrefix, undefined),
+        },
+      },
+      { label: title },
+    ],
+    {
+      heading: workspaceLabel(detail),
+      switcher: workspaceJumpEntries(workspaces, teachPrefix, detail.slug),
+      meta: `${metas.length} lesson${metas.length === 1 ? '' : 's'}`,
+      items: metas.map((meta, index) => ({
+        ordinal: String(index + 1).padStart(2, '0'),
+        label: meta.title,
+        href: `${workspacePrefix}${TEACH_LESSONS}/${meta.file}`,
+        at: false,
+      })),
+      foot: workspaceFoot(detail),
+    },
+  )
+
+  // The sidebar opens as on a lesson, since this page lists no lessons itself.
+  return `${pageHead(title, `${workspacePrefix}${TEACH_ASSETS}/${TEACH_STYLESHEET}`, undefined, 'lesson', `${REFERENCE_GENERATOR}\n`)}<body>
+${header}
+<main class="ref">
+${body.trim()}
+</main>
+${PANE_CLOSE}
+${renderScripts(false, false)}
+</body>
+</html>
+`
+}
+
+/**
+ * Deletes a generated reference page whose markdown source is gone, so a
+ * renamed or removed page leaves nothing no contents row reaches.
+ */
+async function removeOrphanReferencePages(
+  root: string,
+  detail: WorkspaceDetail,
+): Promise<void> {
+  const dir = join(root, detail.path, TEACH_REFERENCE)
+  if (!existsSync(dir)) return
+
+  const sources = new Set(detail.referenceFiles.map(renderedReferenceName))
+  const orphans = (await readdir(dir)).filter(
+    (file) => file.endsWith('.html') && !sources.has(file),
+  )
+
+  await Promise.all(
+    orphans.map(async (file) => {
+      const path = join(dir, file)
+      if (REFERENCE_GENERATOR_PATTERN.test(await readFile(path, 'utf8'))) {
+        await rm(path)
+      }
+    }),
+  )
+}
+
 const REGIONS = ['style', 'header', 'footnav', 'scripts'] as const
 type Region = (typeof REGIONS)[number]
 
@@ -1148,6 +1308,7 @@ function spliceRegion(
 interface LessonRewritten {
   readonly ok: true
   readonly file: string
+  readonly unresolved: readonly string[]
 }
 
 interface LessonRefused {
@@ -1176,15 +1337,57 @@ const FOOTNAV_OPEN = '<!-- canon:teach:footnav -->'
  * alone, which keeps a second run byte-identical.
  */
 function wrapMain(html: string): string {
+  const bounds = authoredBounds(html)
+  if (bounds === undefined) return html
+
+  const body = html.slice(bounds.start, bounds.end)
+  if (/<main[\s>]/.test(body)) return html
+
+  return `${html.slice(0, bounds.start)}\n<main>\n${body.trim()}\n</main>\n${html.slice(bounds.end)}`
+}
+
+function authoredBounds(
+  html: string,
+): { readonly start: number; readonly end: number } | undefined {
   const start = html.indexOf(HEADER_CLOSE)
   const end = html.indexOf(FOOTNAV_OPEN, start)
-  if (start === -1 || end === -1) return html
+  if (start === -1 || end === -1) return undefined
+  return { start: start + HEADER_CLOSE.length, end }
+}
 
-  const bodyStart = start + HEADER_CLOSE.length
-  const body = html.slice(bodyStart, end)
-  if (/<main[\s>]/.test(body)) return html
+/** Each lesson number to the file carrying it, the first in filename order. */
+function lessonTargets(
+  lessonFiles: readonly string[],
+): ReadonlyMap<string, string> {
+  const targets = new Map<string, string>()
+  for (const file of [...lessonFiles].sort()) {
+    const number = LESSON_NUMBER.exec(file)?.[1]
+    if (number !== undefined && !targets.has(number)) targets.set(number, file)
+  }
+  return targets
+}
+
+/**
+ * Links the "lesson NNNN" mentions in the authored region, the one rewrite nav
+ * makes between the header and footnav markers besides the `<main>` wrap.
+ */
+function linkAuthoredRegion(
+  html: string,
+  targets: ReadonlyMap<string, string>,
+  file: string,
+): { readonly html: string; readonly unresolved: readonly string[] } {
+  const bounds = authoredBounds(html)
+  if (bounds === undefined) return { html, unresolved: [] }
 
-  return `${html.slice(0, bodyStart)}\n<main>\n${body.trim()}\n</main>\n${html.slice(end)}`
+  const linked = linkLessonReferences(
+    html.slice(bounds.start, bounds.end),
+    targets,
+    file,
+  )
+  return {
+    html: `${html.slice(0, bounds.start)}${linked.html}${html.slice(bounds.end)}`,
+    unresolved: linked.unresolved,
+  }
 }
 
 /**
@@ -1201,6 +1404,7 @@ async function rewriteLesson(
   metas: readonly LessonMeta[],
   workspaces: readonly WorkspaceSummary[],
   css: string,
+  targets: ReadonlyMap<string, string>,
 ): Promise<LessonRewritten | LessonRefused> {
   const file = metas[index].file
   const path = join(root, detail.path, TEACH_LESSONS, file)
@@ -1281,8 +1485,9 @@ async function rewriteLesson(
     html = spliced
   }
 
-  await writeFile(path, wrapMain(html))
-  return { ok: true, file }
+  const linked = linkAuthoredRegion(wrapMain(html), targets, file)
+  await writeFile(path, linked.html)
+  return { ok: true, file, unresolved: linked.unresolved }
 }
 
 export interface LessonSkipped {
@@ -1296,8 +1501,31 @@ export interface NavGenerated {
   readonly root: string
   readonly contents: readonly string[]
   readonly lessons: number
-  /** A lesson file missing a chrome marker, refused rather than rewritten. */
+  /** Reference pages rendered to their `.html` sibling. */
+  readonly reference: number
+  /**
+   * A lesson file missing a chrome marker, refused rather than rewritten, or a
+   * reference page left unrendered on a Bun carrying no markdown renderer.
+   */
   readonly skipped: readonly LessonSkipped[]
+  /**
+   * A "lesson NNNN" mention naming no lesson in its workspace, one per distinct
+   * number per lesson. The lesson still rewrote, so it counts in `lessons`.
+   */
+  readonly unresolved: readonly LessonReferenceUnresolved[]
+}
+
+export interface LessonReferenceUnresolved {
+  /** Relative to the root, the way a `skipped` entry is. */
+  readonly file: string
+  readonly lesson: string
+}
+
+const MARKDOWN_RENDERER = 'Bun.markdown'
+
+/** An older Bun carries no `Bun.markdown`, and calling it there throws. */
+function hasMarkdownRenderer(): boolean {
+  return typeof Bun.markdown?.html === 'function'
 }
 
 export type NavOutcome = NavGenerated | TeachRefused
@@ -1342,7 +1570,10 @@ export async function generateNav(
 
   const contents: string[] = []
   const skipped: LessonSkipped[] = []
+  const unresolved: LessonReferenceUnresolved[] = []
   let lessons = 0
+  let reference = 0
+  const canRenderMarkdown = hasMarkdownRenderer()
 
   for (const slug of targetSlugs) {
     const found = await readWorkspace(root, slug)
@@ -1357,11 +1588,33 @@ export async function generateNav(
     const contentsPath = join(root, detail.path, 'index.html')
     await writeFile(
       contentsPath,
-      await renderContentsPage(root, listed.workspaces, detail, metas),
+      await renderContentsPage(
+        root,
+        listed.workspaces,
+        detail,
+        metas,
+        canRenderMarkdown,
+      ),
     )
     contents.push(relative(root, contentsPath))
 
+    for (const file of detail.referenceFiles) {
+      const source = join(detail.path, TEACH_REFERENCE, file)
+      if (!canRenderMarkdown) {
+        skipped.push({ file: source, missing: MARKDOWN_RENDERER })
+        continue
+      }
+
+      await writeFile(
+        join(root, detail.path, TEACH_REFERENCE, renderedReferenceName(file)),
+        await renderReferencePage(root, listed.workspaces, detail, metas, file),
+      )
+      reference += 1
+    }
+    await removeOrphanReferencePages(root, detail)
+
     const css = stripImports(await readFile(cssPath, 'utf8'))
+    const targets = lessonTargets(detail.lessonFiles)
 
     for (let index = 0; index < metas.length; index += 1) {
       const outcome = await rewriteLesson(
@@ -1371,10 +1624,17 @@ export async function generateNav(
         metas,
         listed.workspaces,
         css,
+        targets,
       )
 
       if (outcome.ok) {
         lessons += 1
+        for (const lesson of outcome.unresolved) {
+          unresolved.push({
+            file: join(detail.path, TEACH_LESSONS, outcome.file),
+            lesson,
+          })
+        }
       } else {
         skipped.push({
           file: join(detail.path, TEACH_LESSONS, outcome.file),
@@ -1389,6 +1649,8 @@ export async function generateNav(
     root: relative(root, rootPath),
     contents,
     lessons,
+    reference,
     skipped,
+    unresolved,
   }
 }