/** * The library (#/library, #/library/.): every routine of pplus-library, what each check of it found, * and the routine itself: its pseudo, its cases, its reference implementations at each level, its proof and its * sources. "Open in the Bridge" opens the routine as a problem, so it can be stepped through line by line; a * program that only USEs it steps over it. */ import { el, add } from './dom.js'; import { siteNav } from './nav.js'; import { routeFor } from '../core/state.js'; import { libraryModules, libraryRoutine, checksOf, tally, LIBRARY_PREFIX, type LibraryRoutine } from '../core/library.js'; import { highlighted } from '../quarto/render.js'; import type { LibraryCheck } from '#core/library/types.js'; const WORD: Record = { pass: 'pass', fail: 'fail', open: 'open', skipped: 'skipped', unverified: 'unverified' }; const MEANS: Record = { pass: 'checked, and it agrees', fail: 'checked, and it does not agree', open: 'the prover could not finish every obligation: nothing is wrong, and nothing more is proved', skipped: 'the tool is not available where the check ran, or it declines a construct', unverified: 'no stored answer for this exact text yet', }; function chip(c: LibraryCheck, label?: string): HTMLElement { return el('span', { class: `lib-chip lib-${c.status}`, title: `${WORD[c.status]}: ${MEANS[c.status]}. ${c.detail}` }, label ? `${label}: ${WORD[c.status]}` : WORD[c.status]); } function summaryChips(r: LibraryRoutine): HTMLElement { const t = tally(r); const parts = el('span', { class: 'lib-chips' }); for (const k of ['pass', 'open', 'unverified', 'skipped', 'fail'] as const) if (t[k]) add(parts, el('span', { class: `lib-chip lib-${k}`, title: MEANS[k] }, `${t[k]} ${WORD[k]}`)); return parts; } function code(text: string, lang: 'pseudo' | 'mojo' | null): HTMLElement { return lang ? highlighted(text.replace(/\n$/, ''), lang, { numbers: true }) : el('pre', { class: 'pplus-code' }, text.replace(/\n$/, '')); } function indexView(root: HTMLElement): void { const mods = libraryModules(); const count = mods.reduce((n, m) => n + m.routines.length, 0); add(root, el('section', { class: 'lib-hero' }, el('p', { class: 'hero-kicker' }, 'Library'), el('h1', {}, 'Routines verified once, used by name'), el('p', { class: 'lede' }, `${count} routines in ${mods.length} modules, each written once in pseudo and checked at every level: its cases run, the prover checks its contracts, the fuzzer tries to break it, the Mojo made from it prints the same, every reference implementation (Python, C, Mojo, at more than one level) agrees with it, and where it says something, a Dafny proof verifies the method over exact numbers.`), el('p', {}, 'A program brings routines in with ', el('code', {}, 'USE md'), ' (the whole module) or ', el('code', {}, 'USE md.MinimumImage'), ' (one routine), and calls them like its own. A run steps over them; open one here to step through it.'))); for (const m of mods) { add(root, el('section', { class: 'lib-module', id: `module-${m.name}` }, el('h2', {}, m.title, ' ', el('code', { class: 'lib-mod-name' }, m.name)), el('p', { class: 'muted' }, m.summary), el('div', { class: 'lib-grid' }, ...m.routines.map((r) => el('a', { class: 'lib-card', href: routeFor({ kind: 'library', id: r.id }) }, el('div', { class: 'lib-card-name' }, r.name), el('p', {}, r.summary), summaryChips(r)))))); } } function routineView(root: HTMLElement, r: LibraryRoutine): void { const mod = libraryModules().find((m) => m.name === r.module); add(root, el('section', { class: 'lib-hero' }, el('p', { class: 'hero-kicker' }, el('a', { href: '#/library' }, 'Library'), ' / ', el('a', { href: `#/library#module-${r.module}` }, mod?.title ?? r.module)), el('h1', {}, r.name), el('p', { class: 'lede' }, r.summary), el('div', { class: 'hero-actions' }, el('a', { class: 'btn btn-primary', href: routeFor({ kind: 'problem', area: 'bridge', id: `${LIBRARY_PREFIX}${r.id}` }) }, 'Open in the Bridge, to step through it'), el('span', { class: 'lib-use' }, 'Use it: ', el('code', {}, `USE ${r.id}`))))); add(root, el('section', { class: 'lib-sec' }, el('h2', {}, 'The routine'), code(r.source, 'pseudo'))); if (r.cases.length) { add(root, el('section', { class: 'lib-sec' }, el('h2', {}, 'Cases'), el('p', { class: 'muted' }, 'What the pseudo gives. Every reference implementation is held to these results.'), el('table', { class: 'lib-table' }, el('thead', {}, el('tr', {}, el('th', {}, 'Call'), el('th', {}, 'Result'))), el('tbody', {}, ...r.cases.map((c) => el('tr', {}, el('td', {}, el('code', {}, c.call)), el('td', {}, el('code', {}, c.result ?? '(not run yet)')))))))); } add(root, el('section', { class: 'lib-sec' }, el('h2', {}, 'What each check found'), el('table', { class: 'lib-table' }, el('thead', {}, el('tr', {}, el('th', {}, 'Check'), el('th', {}, 'Result'), el('th', {}, 'Detail'))), el('tbody', {}, ...checksOf(r).map(({ name, check }) => el('tr', {}, el('td', {}, name), el('td', {}, chip(check)), el('td', { class: 'small' }, check.detail))))))); if (r.references.length) { const sec = el('section', { class: 'lib-sec' }, el('h2', {}, 'Reference implementations'), el('p', { class: 'muted' }, 'The same routine in other languages, at different levels of care or optimization. Each is the function alone; the checks run it with a main that prints every case.')); for (const ref of r.references) { const tol = ref.rel !== undefined || ref.abs !== undefined ? `held to the pseudo within ${[ref.rel !== undefined ? `relative ${ref.rel}` : '', ref.abs !== undefined ? `absolute ${ref.abs}` : ''].filter(Boolean).join(' and ')}` : 'held to the pseudo exactly'; add(sec, el('details', { class: 'lib-ref' }, el('summary', {}, el('strong', {}, `${ref.lang} · ${ref.level}`), ' ', el('span', { class: 'lib-chips' }, ...Object.entries(ref.checks).map(([how, c]) => chip(c, how)))), el('p', {}, ref.note, ' ', el('span', { class: 'muted' }, `(${tol})`)), code(ref.source, ref.lang === 'mojo' ? 'mojo' : null))); } add(root, sec); } if (r.proof) { add(root, el('section', { class: 'lib-sec' }, el('h2', {}, 'Proof'), el('p', {}, r.proof.note, ' ', chip(r.proof.check, r.proof.lang)), el('details', { class: 'lib-ref' }, el('summary', {}, el('strong', {}, r.proof.file)), code(r.proof.source, null)))); } if (r.sources.length) { add(root, el('section', { class: 'lib-sec' }, el('h2', {}, 'Where the method comes from'), el('ul', {}, ...r.sources.map((s) => el('li', {}, s.url ? el('a', { href: s.url, target: '_blank', rel: 'noopener' }, s.title) : s.title))))); } } export function libraryView(id?: string): HTMLElement { const root = el('div', { class: 'home lib' }); add(root, siteNav('library')); const r = id ? libraryRoutine(id) : undefined; if (id && !r) add(root, el('section', { class: 'lib-hero' }, el('h1', {}, 'No such routine'), el('p', {}, `The library has no routine called ${id}. `, el('a', { href: '#/library' }, 'See every routine'), '.'))); else if (r) routineView(root, r); else indexView(root); add(root, el('footer', { class: 'home-foot' }, el('a', { href: '#/' }, 'Programming+'), ' · ', el('a', { href: '#/library' }, 'Library'), el('p', { class: 'small' }, 'The library is pplus-library, pinned in pplus-core as the submodule library/. Its STATUS.md lists every check of every routine.'))); return root; }