diff --git a/AGENTS.md b/AGENTS.md index 4cf4c50..d3045de 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,7 +46,7 @@ The site's suite takes under a minute. While iterating, build and run one file: | To add | Do | |---|---| -| A catalog problem, a probe, a stress program, a corpus or prover regression, a language | in core ([core/AGENTS.md](core/AGENTS.md#adding-things)), then move the `core` pointer here; a problem's area comes from `defaultAreaFor` in `src/core/catalog.ts` | +| A catalog problem, a probe, a stress program, a corpus or prover regression, a language, a library routine | in core (a library routine in pplus-library, core's submodule `library/`) ([core/AGENTS.md](core/AGENTS.md#adding-things)), then move the `core` pointer here; a problem's area comes from `defaultAreaFor` in `src/core/catalog.ts` | | A command | a task in `pixi.toml` and a row in the README's Commands table | | A Quarto shortcode | a function in the table `quarto/_extensions/pplus/pplus.lua` returns, a row in `SHORTCODES` (`src/quarto/shortcodes.ts`) and in `scripts/check-pages.mjs`, a sample in the gallery (`src/ui/quarto.ts`) and a use in `quarto/example/`; a rendered view is a case of `renderStatic` (`src/quarto/render.ts`); a view of the machine is a name in `HW_NAMES` (`src/quarto/machine.ts`), `HW_VIEWS` in `pplus.lua` and `HW_VIEWS` in `scripts/check-pages.mjs` | diff --git a/README.md b/README.md index 7302c80..46f38df 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Programming+ takes a procedure **from an idea to Mojo to the machine**, built fo - **Developer**: Mojo only. The checker's advice as you type, every step and every value in one Run view, a fuzzer that lists what it tried, and the real Mojo compiler's verdict. - **Hardware**: the code beside a board you arrange: registers, memory, the stack, cache lines, the caches, virtual memory, the pipeline and the out-of-order core, with Mojo and its x86-64 as tabs, linked line by line. -A catalog of worked problems comes with it, each opening in every area it has something to show in, and any view can be shared as a link or embedded in a page. With Quarto, a page can also run a program kept beside it while the page renders, and show the run, a stepper, the flowchart, the proof and the rest without an iframe, down to the machine itself (registers, caches, the pipeline, the core, stepped). The **With Quarto** page (`#/quarto`) is a gallery of every shortcode. +A library of verified routines (statistics, numerics, sequence alignment, molecular simulation; `#/library`) comes with it, each one usable by name with `USE` and open to step through, and so does a catalog of worked problems, each opening in every area it has something to show in, and any view can be shared as a link or embedded in a page. With Quarto, a page can also run a program kept beside it while the page renders, and show the run, a stepper, the flowchart, the proof and the rest without an iframe, down to the machine itself (registers, caches, the pipeline, the core, stepped). The **With Quarto** page (`#/quarto`) is a gallery of every shortcode. It is a static single-page app: TypeScript compiled by `tsc`, no bundler, no framework, no runtime dependencies. This repository is the site; what programs mean (the languages, the translators, the Mojo checker and interpreter, the prover, the fuzzer, the machine model, and the stored answers of the real tools) is **pplus-core**, a project of its own, kept here as the git submodule `core/` and imported as `#core/...` ([core/README.md](core/README.md)). Everything it says about Mojo is pinned to **Mojo 1.1.0** and checked against the real compiler on [Compiler Explorer](https://godbolt.org). @@ -58,12 +58,13 @@ Every command is a pixi task (`pixi task list` shows them with their description ``` AGENTS.md rules for changing the site (read first) index.html, styles.css the page (with the import map that points #core/ at core/dist/) and the app's stylesheet -core/ pplus-core, a git submodule: languages, translators, prover, corpus (core/README.md) +core/ pplus-core, a git submodule: languages, translators, prover, corpus, and the library + (pplus-library, its own submodule core/library) (core/README.md) src/ main.ts the hash router core/ the app's state and its URL codec, the session (a core Workspace with storage, versions, compiles and the helper), the catalog with areas, the areas, saved versions, preferences - ui/ the shell (one per area), the home page, the "With Quarto" gallery, the editor, the embeds, the views + ui/ the shell (one per area), the home page, the library, the "With Quarto" gallery, the editor, the embeds, the views ui/hw/ the Hardware area's machine board, over the course's x86-64 views (from core) quarto/ the Quarto extension's rendered views: a program run and drawn by the views, as HTML (render.ts), the small document they draw into outside a browser (dom.ts), the shortcode list (shortcodes.ts) diff --git a/core b/core index c5157fc..477dffe 160000 --- a/core +++ b/core @@ -1 +1 @@ -Subproject commit c5157fcad520c8460f930531611ad51a5c121602 +Subproject commit 477dffe02cc220fae75727d3bc0d2598c6d710d0 diff --git a/docs/app.md b/docs/app.md index 9ebc3b7..7eb4839 100644 --- a/docs/app.md +++ b/docs/app.md @@ -82,6 +82,10 @@ A student can save the state of their work under a name and come back to any sav - **A problem that changed under saved edits** shows a banner with **See the new version**: your edits become the version "My edits, before the problem changed" and the problem opens as it is now. - **Between browsers:** Share → Download writes the state and, with a checkbox (on by default), its versions; Open… puts them in the right list and never overwrites a version that has the same id. A share link carries only the current state. +### The library + +**Library** (`#/library`, `src/ui/library.ts`) lists every routine of pplus-library, as core's registry holds it (`#core/library/registry.js`, generated from the submodule `core/library`), grouped by module, each with a count of how its checks ended. A routine's page (`#/library/md.LennardJones`) shows the routine's pseudo, its cases with the results the pseudo gives, every check with its detail (cases, prover, fuzzer, generated Mojo, each reference implementation per way of running it, the proof), each reference's source with its note and tolerance, the Dafny proof, and the sources of the method. **Open in the Bridge** opens the routine as a problem with the id `lib:.` (`src/core/library.ts`): its pseudo in the pseudo pane and its first case as the call, so it can be stepped through, which a program that only USEs it never does (a run steps over library routines; core's [docs/library.md](../core/docs/library.md)). Edits are saved per routine, like a problem's. + ### With Quarto `#/quarto` (`src/ui/quarto.ts`, linked from the nav, the footer, and a section of the home page that shows one shortcode beside the stepper it makes) is a gallery of the Quarto extension's shortcodes ([quarto/README.md](../quarto/README.md)). Each card shows what an author writes (the shortcode, and every program file it names, in tabs) and what the reader gets, drawn when the card scrolls into view by the same code `quarto render` runs: `renderStatic` for the rendered views and the machine, this app's own `#/embed/...` route in an iframe for the live ones. The cards can be filtered by kind (rendered with the page, the machine, live, text); one machine card has a menu of every `pplus-hw-` and draws the one chosen. `#/quarto#` scrolls to a card, `#/quarto#setup` to the set-up steps. The page loads the extension's `pplus.css` and `pplus.js` from the site (`scripts/assemble.sh` copies the extension into `site/`), so the steppers and "make it live" behave exactly as on a Quarto page. The shortcodes, their options and the sample programs come from `src/quarto/shortcodes.ts` and `galleryFiles()`; `tests/quarto-gallery.test.mjs` renders every sample and holds each program in it to its header lines. diff --git a/quarto/example/programs/mean.tex b/quarto/example/programs/mean.tex index 7af3554..1cc6fb5 100644 --- a/quarto/example/programs/mean.tex +++ b/quarto/example/programs/mean.tex @@ -1,3 +1,3 @@ % CALL: X_BAR(3, [1.0, 2.0, 6.0]) -% EXPECT: X_BAR returned 3 +% EXPECT: X_BAR returned 3.0 \bar{x} = \frac{1}{n} \sum_{i=0}^{n-1} x_i diff --git a/src/core/library.ts b/src/core/library.ts new file mode 100644 index 0000000..68349db --- /dev/null +++ b/src/core/library.ts @@ -0,0 +1,54 @@ +/** + * The library (pplus-library, through core's registry) as the site shows it: a routine opened in the Bridge, and + * a summary of what its checks found. DOM-free; src/ui/library.ts draws it. + * + * A library routine opens like a catalog problem, under the id `lib:.` (#/bridge/p/lib:md.LennardJones): + * its pseudo in the pseudo pane and its first case as the call, so it can be stepped through line by line, which + * a program that only calls it never does. + */ +import { libraryModules, libraryRoutine, type LibraryRoutine } from '#core/library/registry.js'; +import type { LibraryCheck } from '#core/library/types.js'; +import { emptyState, type PlayState } from './state.js'; + +export const LIBRARY_PREFIX = 'lib:'; + +export function isLibraryId(id: string): boolean { return id.startsWith(LIBRARY_PREFIX); } + +/** The state a library routine opens in: its pseudo, and its first case as the call. */ +export function stateForLibraryRoutine(r: LibraryRoutine): PlayState { + const s = emptyState(); + s.problem = `${LIBRARY_PREFIX}${r.id}`; + s.title = `${r.id}, from the library`; + s.sources = { pseudo: r.source }; + s.lang = 'pseudo'; + s.call = r.cases[0]?.call ?? null; + s.view = 'trace'; + return s; +} + +/** The state for a `lib:` problem id, or null when the library has no such routine. */ +export function libraryState(id: string): PlayState | null { + if (!isLibraryId(id)) return null; + const r = libraryRoutine(id.slice(LIBRARY_PREFIX.length)); + return r ? stateForLibraryRoutine(r) : null; +} + +/** Every check of a routine, named as the page lists them: its own checks, each reference's runs, the proof. */ +export function checksOf(r: LibraryRoutine): Array<{ name: string; check: LibraryCheck }> { + const out: Array<{ name: string; check: LibraryCheck }> = []; + const LABEL: Record = { structure: 'One routine per file', pseudo: 'Cases run', prover: 'Prover', fuzz: 'Fuzzer', mojo: 'Generated Mojo' }; + for (const k of ['structure', 'pseudo', 'prover', 'fuzz', 'mojo']) if (r.checks[k]) out.push({ name: LABEL[k], check: r.checks[k] }); + for (const ref of r.references) for (const [how, c] of Object.entries(ref.checks)) out.push({ name: `${ref.lang} ${ref.level}, ${how}`, check: c }); + if (r.proof) out.push({ name: `Proof (${r.proof.lang})`, check: r.proof.check }); + return out; +} + +/** How many checks of a routine ended each way. */ +export function tally(r: LibraryRoutine): Record { + const t: Record = { pass: 0, fail: 0, open: 0, skipped: 0, unverified: 0 }; + for (const { check } of checksOf(r)) t[check.status]++; + return t; +} + +export { libraryModules, libraryRoutine }; +export type { LibraryRoutine }; diff --git a/src/core/state.ts b/src/core/state.ts index 81d1710..be24269 100644 --- a/src/core/state.ts +++ b/src/core/state.ts @@ -215,6 +215,7 @@ export function applyEmbedParams(state: PlayState, params: URLSearchParams, area export type Route = | { kind: 'home' } | { kind: 'quarto'; anchor?: string } + | { kind: 'library'; id?: string } | { kind: 'problem'; area: AreaId; id: string } | { kind: 'shared'; area: AreaId; blob: string } | { kind: 'embed'; view: ViewId | LangId; blob?: string; problem?: string; params: URLSearchParams }; @@ -227,6 +228,7 @@ export function parseRoute(hash: string): Route { const params = new URLSearchParams(query); if (!parts.length) return { kind: 'home' }; if (parts.length === 1 && /^quarto(#[\w-]*)?$/.test(parts[0])) { const a = parts[0].split('#')[1]; return a ? { kind: 'quarto', anchor: a } : { kind: 'quarto' }; } + if (parts[0] === 'library') return parts[1] ? { kind: 'library', id: decodeURIComponent(parts[1]) } : { kind: 'library' }; if (isAreaId(parts[0]) && parts[1] === 'p' && parts[2]) return { kind: 'problem', area: parts[0], id: decodeURIComponent(parts[2]) }; if (isAreaId(parts[0]) && parts[1] === 's' && parts[2]) return { kind: 'shared', area: parts[0], blob: parts[2] }; if (parts[0] === 'embed' && parts[1]) { @@ -241,6 +243,7 @@ export function routeFor(r: Route): string { switch (r.kind) { case 'home': return '#/'; case 'quarto': return r.anchor ? `#/quarto#${r.anchor}` : '#/quarto'; + case 'library': return r.id ? `#/library/${encodeURIComponent(r.id)}` : '#/library'; case 'problem': return `#/${r.area}/p/${encodeURIComponent(r.id)}`; case 'shared': return `#/${r.area}/s/${r.blob}`; case 'embed': { diff --git a/src/main.ts b/src/main.ts index c662dc7..471aced 100644 --- a/src/main.ts +++ b/src/main.ts @@ -9,6 +9,8 @@ import { problemById, stateForProblem } from './core/catalog.js'; import { parseRoute, decodeState, loadLocal, migrateLocal, type PlayState, embedStorageId, clearLocal, editedFrom, applyEmbedParams, resolveSaved } from './core/state.js'; import { homeView } from './ui/home.js'; import { quartoView } from './ui/quarto.js'; +import { libraryView } from './ui/library.js'; +import { libraryState } from './core/library.js'; import { forceTheme, watchTheme } from './ui/theme.js'; import { AREAS, isAreaId, paneForArea, type AreaId } from './core/areas.js'; @@ -19,12 +21,12 @@ let shell: Shell | null = null; async function stateForRoute(): Promise<{ area: AreaId; state: PlayState; original?: PlayState; stale?: boolean; embed?: { view: any; params: URLSearchParams; original: PlayState; storageId: string | null } } | null> { const r = parseRoute(location.hash); - if (r.kind === 'home' || r.kind === 'quarto') return null; + if (r.kind === 'home' || r.kind === 'quarto' || r.kind === 'library') return null; if (r.kind === 'problem') { const p = problemById(r.id); - if (!p) return null; - const original = stateForProblem(p); - const { state, stale } = resolveSaved(original, loadLocal(p.id)); + const original = p ? stateForProblem(p) : libraryState(r.id); + if (!original) return null; + const { state, stale } = resolveSaved(original, loadLocal(r.id)); state.lang = paneForArea(AREAS[r.area], state, true); return { area: r.area, state, original, stale }; } @@ -78,6 +80,7 @@ async function render(): Promise { add(app, el('div', { class: 'home' }, el('h1', {}, 'That link did not open'), el('p', {}, String(e?.message || e)), el('a', { href: '#/' }, 'Back to the problems'))); return; } + if (!resolved && route.kind === 'library') { add(app, libraryView(route.id)); document.title = `${route.id ? `${route.id} · ` : ''}Library · Programming+`; window.scrollTo(0, 0); return; } if (!resolved && route.kind === 'quarto') { add(app, quartoView()); document.title = 'With Quarto · Programming+'; if (route.anchor) scrollToAnchor(); else window.scrollTo(0, 0); return; } if (!resolved) { add(app, homeView()); document.title = 'Programming+'; scrollToAnchor(); return; } const embedded = resolved.embed; diff --git a/src/ui/library.ts b/src/ui/library.ts new file mode 100644 index 0000000..7e32a6c --- /dev/null +++ b/src/ui/library.ts @@ -0,0 +1,117 @@ +/** + * 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; +} diff --git a/src/ui/nav.ts b/src/ui/nav.ts index ddab80b..d1b706e 100644 --- a/src/ui/nav.ts +++ b/src/ui/nav.ts @@ -10,11 +10,11 @@ export function startFor(area: AreaId): string { return (area === 'bridge' ? PROBLEMS.find((p) => p.id === 'count-base') : PROBLEMS.find((p) => p.area === area))?.id ?? PROBLEMS[0].id; } -export function siteNav(active: 'home' | 'problems' | 'reference' | 'quarto' | AreaId): HTMLElement { +export function siteNav(active: 'home' | 'problems' | 'reference' | 'quarto' | 'library' | AreaId): HTMLElement { const themeBtn = el('button', { type: 'button', class: 'btn btn-quiet icon-btn', title: 'Switch between light and dark', onClick: () => { cycleTheme(); themeBtn.textContent = effectiveTheme() === 'dark' ? '\u2600' : '\u263e'; } }, effectiveTheme() === 'dark' ? '\u2600' : '\u263e'); const link = (href: string, label: string, id: typeof active, title?: string) => el('a', { href, class: active === id ? 'on' : '', title: title ?? '' }, label); const nav = el('nav', { class: 'home-nav' }, el('a', { class: 'brand', href: '#/' }, el('span', { class: 'brand-mark' }, 'P+'), 'Programming+'), el('span', { class: 'spacer' })); add(nav, ...AREA_ORDER.map((id) => link(routeFor({ kind: 'problem', area: id, id: startFor(id) }), AREAS[id].name, id, AREAS[id].tagline)), - link('#/#problems', 'Problems', 'problems'), link('#/#reference', 'Reference', 'reference'), link('#/quarto', 'With Quarto', 'quarto', 'Put Programming+ in a Quarto page: a gallery of the shortcodes'), themeBtn); + link('#/#problems', 'Problems', 'problems'), link('#/library', 'Library', 'library', 'Routines verified once, used by name with USE'), link('#/#reference', 'Reference', 'reference'), link('#/quarto', 'With Quarto', 'quarto', 'Put Programming+ in a Quarto page: a gallery of the shortcodes'), themeBtn); return nav; } diff --git a/src/ui/quarto.ts b/src/ui/quarto.ts index 4f98160..464eda0 100644 --- a/src/ui/quarto.ts +++ b/src/ui/quarto.ts @@ -75,7 +75,7 @@ export function galleryFiles(): Record { 'binary-search.pseudo': head([`CALL: ${bs.call}`, 'EXPECT: CONTAINS_SORTED returned TRUE']) + (bs.sources.pseudo ?? '').trim() + '\n', 'match-off-by-one.pseudo': head([`CALL: ${mob.call}`, 'STOPS: index']) + (mob.sources.pseudo ?? '').trim() + '\n', 'five-bugs.pseudo': head([`CALL: ${fb.call}`, 'ERRORS: 2']) + (fb.sources.pseudo ?? '').trim() + '\n', - 'mean.tex': '% CALL: X_BAR(3, [1.0, 2.0, 6.0])\n% EXPECT: X_BAR returned 3\n\\bar{x} = \\frac{1}{n} \\sum_{i=0}^{n-1} x_i\n', + 'mean.tex': '% CALL: X_BAR(3, [1.0, 2.0, 6.0])\n% EXPECT: X_BAR returned 3.0\n\\bar{x} = \\frac{1}{n} \\sum_{i=0}^{n-1} x_i\n', 'two-pointers.asm': (tp.sources.asm ?? '').trim() + '\n', 'two-pointers.setup': (tp.setup ?? '').trim() + '\n', 'lifecycle.mojo': LIFECYCLE, diff --git a/src/ui/shell.ts b/src/ui/shell.ts index e93dcda..a3eff3d 100644 --- a/src/ui/shell.ts +++ b/src/ui/shell.ts @@ -755,6 +755,7 @@ export class Shell { group.appendChild(el('option', { value: p.id, selected: p.id === s.problem }, p.title)); } if (!s.problem) select.insertBefore(el('option', { value: '', selected: true }, s.title || 'shared program'), select.firstChild); + else if (!PROBLEMS.some((p) => p.id === s.problem)) select.insertBefore(el('option', { value: s.problem, selected: true }, s.title || s.problem), select.firstChild); if (this.embed) { // in a host page: the example's title, not a menu that would navigate the frame away const open = el('a', { class: 'brand', href: '#', target: '_blank', rel: 'noopener', title: 'Open this example, as it is now, in Programming+' }, el('span', { class: 'brand-mark' }, 'P+'), 'Programming+ ↗'); diff --git a/styles.css b/styles.css index c45491f..eeae1f2 100644 --- a/styles.css +++ b/styles.css @@ -4237,3 +4237,30 @@ button.asm-src:hover { .qg-kinds, .quarto-teaser { grid-template-columns: 1fr; } .qg-hero h1 { font-size: 32px; } } + +/* ------------------------------------------------------------------ */ +/* The library (#/library) */ +/* ------------------------------------------------------------------ */ +.lib-hero { padding: 32px 0 8px; } +.lib-hero h1 { margin: 6px 0 10px; } +.lib-use { margin-left: 12px; color: var(--ink-2); } +.lib-module { margin: 28px 0; } +.lib-mod-name { font-size: .8em; color: var(--ink-2); } +.lib-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 12px; margin-top: 12px; } +.lib-card { display: block; padding: 14px 16px; border: 1px solid var(--line); border-radius: var(--r-lg); color: inherit; text-decoration: none; } +.lib-card:hover { border-color: var(--accent); } +.lib-card-name { font-weight: 600; margin-bottom: 4px; } +.lib-card p { margin: 0 0 10px; font-size: .92em; } +.lib-chips { display: inline-flex; flex-wrap: wrap; gap: 6px; } +.lib-chip { display: inline-block; padding: 1px 8px; border-radius: 999px; font-size: .78em; border: 1px solid var(--line); white-space: nowrap; } +.lib-pass { background: var(--ok-bg); color: var(--ok); } +.lib-open { background: var(--warn-bg); color: var(--warn); } +.lib-unverified, .lib-skipped { background: transparent; color: var(--ink-2); } +.lib-fail { background: var(--err-bg); color: var(--err); } +.lib-sec { margin: 26px 0; } +.lib-table { width: 100%; border-collapse: collapse; font-size: .92em; } +.lib-table th, .lib-table td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--line); vertical-align: top; } +.lib-ref { margin: 10px 0; border: 1px solid var(--line); border-radius: var(--r); padding: 8px 12px; } +.lib-ref summary { cursor: pointer; } +.lib pre.pplus-code { font-family: var(--mono); font-size: .88em; line-height: 1.5; overflow-x: auto; padding: 10px 12px; border: 1px solid var(--line); border-radius: var(--r); } +.lib .pplus-lno { display: inline-block; width: 2.6em; color: var(--ink-2); user-select: none; } diff --git a/tests/library.test.mjs b/tests/library.test.mjs new file mode 100644 index 0000000..f420a53 --- /dev/null +++ b/tests/library.test.mjs @@ -0,0 +1,57 @@ +// The library page (#/library, src/ui/library.ts) and a library routine opened in the Bridge (src/core/library.ts): +// every routine of core's registry is listed with its checks, and opens as a problem that runs. +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { installDocument } from '../dist/quarto/dom.js'; + +installDocument(); +const { parseRoute, routeFor } = await import('../dist/core/state.js'); +const { libraryModules, libraryState, checksOf, tally, LIBRARY_PREFIX } = await import('../dist/core/library.js'); +const { Session } = await import('../dist/core/session.js'); + +test('routes: #/library and #/library/, and a routine opens under the problem id lib:', () => { + assert.deepEqual(parseRoute('#/library'), { kind: 'library' }); + assert.deepEqual(parseRoute('#/library/md.LennardJones'), { kind: 'library', id: 'md.LennardJones' }); + assert.equal(routeFor({ kind: 'library', id: 'md.LennardJones' }), '#/library/md.LennardJones'); + assert.deepEqual(parseRoute('#/bridge/p/lib:md.LennardJones'), { kind: 'problem', area: 'bridge', id: 'lib:md.LennardJones' }); + assert.equal(libraryState('lib:md.NoSuch'), null); + assert.equal(libraryState('count-base'), null); +}); + +test('every routine opens in the Bridge with its pseudo and its first case, and runs to that case\'s result', () => { + let n = 0; + for (const m of libraryModules()) for (const r of m.routines) { + n++; + const st = libraryState(`${LIBRARY_PREFIX}${r.id}`); + assert.equal(st.sources.pseudo, r.source); + assert.equal(st.call, r.cases[0].call); + const session = new Session(st, { area: 'bridge' }); + const tr = session.trace('pseudo'); + assert.equal(tr.error, null, `${r.id}: ${tr.error?.message}`); + assert.equal(tr.output.at(-1), `${r.name} returned ${r.cases[0].result}`, r.id); + // stepping into the routine is the point of opening it: its own lines are in the run + assert.ok(tr.steps.some((s) => s.line > 1 && s.kind !== 'call'), `${r.id}: the run shows none of the routine's lines`); + } + assert.ok(n >= 16); +}); + +test('the page lists every routine with its checks, and each routine\'s page shows its source, cases, references and checks', async () => { + const { libraryView } = await import('../dist/ui/library.js'); + const index = libraryView(); + const text = index.textContent; + for (const m of libraryModules()) { + assert.ok(text.includes(m.title), m.title); + for (const r of m.routines) assert.ok(text.includes(r.name), r.id); + } + const r = libraryModules().find((m) => m.name === 'md').routines.find((x) => x.name === 'LennardJones'); + const page = libraryView(r.id); + const t = page.textContent; + assert.ok(t.includes('Open in the Bridge')); + assert.ok(t.includes(`USE ${r.id}`)); + for (const c of r.cases) assert.ok(t.includes(c.call) && t.includes(c.result), c.call); + for (const ref of r.references) assert.ok(t.includes(`${ref.lang} · ${ref.level}`), `${ref.lang}/${ref.level}`); + assert.equal(page.querySelectorAll('.lib-chip').length >= checksOf(r).length, true); + assert.ok(libraryView('md.NoSuch').textContent.includes('No such routine')); + const t2 = tally(r); + assert.equal(t2.fail, 0); +});