@erclx/canon 4.115.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

@@ -10,7 +10,9 @@ 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,
@@ -1306,6 +1308,7 @@ function spliceRegion(
 interface LessonRewritten {
   readonly ok: true
   readonly file: string
+  readonly unresolved: readonly string[]
 }
 
 interface LessonRefused {
@@ -1334,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,
+  }
 }
 
 /**
@@ -1359,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)
@@ -1439,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 {
@@ -1461,6 +1508,17 @@ export interface NavGenerated {
    * 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'
@@ -1512,6 +1570,7 @@ export async function generateNav(
 
   const contents: string[] = []
   const skipped: LessonSkipped[] = []
+  const unresolved: LessonReferenceUnresolved[] = []
   let lessons = 0
   let reference = 0
   const canRenderMarkdown = hasMarkdownRenderer()
@@ -1555,6 +1614,7 @@ export async function generateNav(
     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(
@@ -1564,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),
@@ -1584,5 +1651,6 @@ export async function generateNav(
     lessons,
     reference,
     skipped,
+    unresolved,
   }
 }

package/src/teach/render.ts

@@ -1,6 +1,7 @@
 import { Heading } from '@/teach/components/heading'
 import { List } from '@/teach/components/list'
 import { Paragraph } from '@/teach/components/paragraph'
+import { type Reference, Refs } from '@/teach/components/refs'
 import { render } from '@/teach/html/jsx-runtime'
 import type { TeachRefused } from '@/teach/workspace'
 
@@ -10,12 +11,14 @@ export type LessonBlock =
       readonly type: 'paragraph'
       readonly text: string
       readonly lede?: boolean
+      readonly cites?: readonly number[]
     }
   | {
       readonly type: 'list'
       readonly items: readonly string[]
       readonly ordered?: boolean
     }
+  | { readonly type: 'refs'; readonly items: readonly Reference[] }
   | { readonly type: 'raw'; readonly html: string }
 
 export interface RenderRendered {
@@ -25,7 +28,9 @@ export interface RenderRendered {
 
 export type RenderOutcome = RenderRendered | TeachRefused
 
-const BLOCK_TYPES = ['heading', 'paragraph', 'list', 'raw'] as const
+const BLOCK_TYPES = ['heading', 'paragraph', 'list', 'refs', 'raw'] as const
+
+const LINK_PROTOCOLS = new Set(['http:', 'https:'])
 
 function isBlockType(value: unknown): value is LessonBlock['type'] {
   return (BLOCK_TYPES as readonly string[]).includes(value as string)
@@ -48,10 +53,46 @@ function isStringArray(value: unknown): value is readonly string[] {
   return Array.isArray(value) && value.every(isString)
 }
 
+function isCiteArray(value: unknown): value is readonly number[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((cite) => Number.isInteger(cite) && cite > 0)
+  )
+}
+
+function isLinkUrl(value: string): boolean {
+  if (!URL.canParse(value)) return false
+  return LINK_PROTOCOLS.has(new URL(value).protocol)
+}
+
+function readReference(item: unknown, position: number): Reference | string {
+  if (typeof item !== 'object' || item === null) {
+    return `reference ${position} is not an object`
+  }
+  const { title, url, note } = item as Record<string, unknown>
+  if (!isString(title) || title === '') {
+    return `reference ${position} needs a non-empty string title`
+  }
+  if (note !== undefined && !isString(note)) {
+    return `reference ${position} note must be a string`
+  }
+  if (url !== undefined && !(isString(url) && isLinkUrl(url))) {
+    return `reference ${position} url must be an http or https URL`
+  }
+  return { title, url, note }
+}
+
+interface RenderedBlock {
+  readonly html: string
+  readonly cites?: readonly number[]
+  readonly referenceCount?: number
+}
+
 function renderBlock(
   block: unknown,
   index: number,
-): { readonly html: string } | TeachRefused {
+): RenderedBlock | TeachRefused {
   if (typeof block !== 'object' || block === null || !('type' in block)) {
     return badBlock(index, 'not an object carrying a type')
   }
@@ -83,8 +124,24 @@ function renderBlock(
       if (fields.lede !== undefined && typeof fields.lede !== 'boolean') {
         return badBlock(index, 'paragraph lede must be a boolean')
       }
+      if (fields.cites !== undefined && !isCiteArray(fields.cites)) {
+        return badBlock(
+          index,
+          'paragraph cites must be a non-empty array of positive integers',
+        )
+      }
+      if (fields.lede === true && fields.cites !== undefined) {
+        return badBlock(index, 'a lede paragraph cannot carry cites')
+      }
       return {
-        html: render(Paragraph({ lede: fields.lede, children: fields.text })),
+        html: render(
+          Paragraph({
+            lede: fields.lede,
+            cites: fields.cites,
+            children: fields.text,
+          }),
+        ),
+        cites: fields.cites,
       }
     }
     case 'list': {
@@ -98,6 +155,21 @@ function renderBlock(
         html: render(List({ ordered: fields.ordered, items: fields.items })),
       }
     }
+    case 'refs': {
+      if (!Array.isArray(fields.items) || fields.items.length === 0) {
+        return badBlock(index, 'refs needs a non-empty items array')
+      }
+      const items: Reference[] = []
+      for (const [position, item] of fields.items.entries()) {
+        const reference = readReference(item, position + 1)
+        if (isString(reference)) return badBlock(index, reference)
+        items.push(reference)
+      }
+      return {
+        html: render(Refs({ items })),
+        referenceCount: items.length,
+      }
+    }
     case 'raw': {
       if (!isString(fields.html)) {
         return badBlock(index, 'raw needs a string html')
@@ -112,15 +184,31 @@ function renderBlock(
  * `lesson.test.tsx` composes as JSX, so a real lesson and the component test
  * share one rendering mechanism. Every block past the first refusal
  * goes unread, matching how a malformed JSON parse refuses the whole call.
+ * Citations resolve across blocks once every block has rendered, so a marker
+ * with no reference refuses rather than leaving a dead anchor.
  */
 export function renderLessonBody(blocks: readonly unknown[]): RenderOutcome {
-  const rendered: string[] = []
+  const rendered: RenderedBlock[] = []
+  let referenceCount = 0
 
   for (const [index, block] of blocks.entries()) {
     const result = renderBlock(block, index)
     if ('ok' in result) return result
-    rendered.push(result.html)
+    if (result.referenceCount !== undefined) {
+      if (referenceCount > 0) {
+        return badBlock(index, 'a lesson carries one refs block')
+      }
+      referenceCount = result.referenceCount
+    }
+    rendered.push(result)
+  }
+
+  for (const [index, block] of rendered.entries()) {
+    const dangling = block.cites?.find((cite) => cite > referenceCount)
+    if (dangling !== undefined) {
+      return badBlock(index, `cite ${dangling} resolves to no reference`)
+    }
   }
 
-  return { ok: true, html: rendered.join('\n') }
+  return { ok: true, html: rendered.map((block) => block.html).join('\n') }
 }