Build, test, deploy / site (push) Successful in 7m38s
In a container running the tests on two processors, the Quarto gallery's proved example was rendered with the warning that time ran out: the generated inputs that cross-check a proof had been cut short by the 3-second clock, with every claim already proved. core 941af6b counts that only where a claim is still open. The tests that hold what a proof finds give it time to spare, and the browser-side request builder takes prove-seconds as the Lua filter does.
152 lines
13 KiB
TypeScript
152 lines
13 KiB
TypeScript
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
|
|
// SPDX-License-Identifier: Apache-2.0
|
|
/**
|
|
* The shortcodes of the Quarto extension (quarto/_extensions/pplus/pplus.lua), as data: what each is called, what
|
|
* it shows, and the options it reads. The app's "With Quarto" gallery (src/ui/quarto.ts) is written from this,
|
|
* scripts/check-pages.mjs reads it to know a shortcode when it sees one, and tests/quarto.test.mjs holds it to the
|
|
* names pplus.lua returns. DOM-free.
|
|
*/
|
|
import type { LangId } from '#core/common/types.js';
|
|
import type { StaticView, RenderRequest } from './render.js';
|
|
import { listingText } from './program.js';
|
|
import { emptyState, type PlayState } from '../core/state.js';
|
|
import { boardView } from '../core/hardware.js';
|
|
import { HW_NAMES } from './machine.js';
|
|
|
|
export type ShortcodeKind = 'rendered' | 'machine' | 'live' | 'text';
|
|
|
|
export interface ShortcodeDef {
|
|
name: string;
|
|
kind: ShortcodeKind;
|
|
/** rendered: the view render.ts draws; live: the embed view (or `any`, chosen by view=). */
|
|
view?: StaticView | 'playground' | 'any';
|
|
/** machine: the board view it shows (its pplus-hw-<name>), or none for the whole board. */
|
|
hw?: string;
|
|
title: string;
|
|
summary: string;
|
|
/** The options it reads besides the shared ones (SHARED_OPTIONS). */
|
|
options: string[];
|
|
}
|
|
|
|
/** Read by every shortcode that names program files. */
|
|
export const SHARED_OPTIONS = ['lingo', 'matho', 'pseudo', 'speco', 'mojo', 'asm', 'setup', 'lang', 'call', 'input', 'machine', 't', 'title', 'caption', 'collapse', 'area'] as const;
|
|
|
|
/** Read by every rendered view (the machine's too). */
|
|
export const RENDERED_OPTIONS = ['code', 'numbers', 'live', 'height', 'column'] as const;
|
|
|
|
export const SHORTCODES: ShortcodeDef[] = [
|
|
{ name: 'pplus-run', kind: 'rendered', view: 'run', title: 'Run it', summary: 'What the program prints and returns, checked against its EXPECT lines. A Mojo file runs on the real compiler when the machine that renders has one.', options: ['compiler'] },
|
|
{ name: 'pplus-steps', kind: 'rendered', view: 'steps', title: 'Step through it', summary: 'The listing beside a stepper: every step, the line it ran, what it wrote, the values after it, and what was printed so far. The run is in the page; a small script moves through it.', options: ['follow', 'max'] },
|
|
{ name: 'pplus-table', kind: 'rendered', view: 'table', title: 'Table of values', summary: 'The table you would draw by hand: a column per step that changed something, a row per name.', options: [] },
|
|
{ name: 'pplus-flow', kind: 'rendered', view: 'flow', title: 'Flowchart', summary: 'The routine as a flowchart, laid out from its structure; each box shaded by how often its line ran, each arrow labeled with how often it was taken.', options: [] },
|
|
{ name: 'pplus-dataflow', kind: 'rendered', view: 'data', title: 'Data flow', summary: 'Which names feed which: the parameters on the left, what leaves on the right, an arrow for each assignment.', options: [] },
|
|
{ name: 'pplus-lifetimes', kind: 'rendered', view: 'life', title: 'Lifetimes', summary: 'Each Mojo value from the step it is made to the step it is destroyed or moved out of, with every copy and move on the way.', options: [] },
|
|
{ name: 'pplus-proof', kind: 'rendered', view: 'proof', title: 'Proof', summary: 'Every claim the specification makes (ENSURE, INVARIANT, a .speco file woven in): proved, broken by a run, or open.', options: [] },
|
|
{ name: 'pplus-tests', kind: 'rendered', view: 'tests', title: 'Generated tests', summary: 'The fuzzer\'s report for each routine: what each input must do, how the inputs were made, every failure shrunk to the smallest input, every case run.', options: [] },
|
|
{ name: 'pplus-check', kind: 'rendered', view: 'check', title: 'The checker', summary: 'What Programming+ finds in each file before anything runs, on the file\'s own lines, with a link to the guide.', options: [] },
|
|
{ name: 'pplus-translate', kind: 'rendered', view: 'translate', title: 'Every notation', summary: 'One file in, the procedure in every notation out: lingo, matho, pseudo, speco, and Mojo generated from the pseudo (and labeled so). As tabs, columns, or the app\'s panes.', options: ['to', 'layout'] },
|
|
{ name: 'pplus-machine', kind: 'rendered', view: 'machine', title: 'The machine', summary: 'An x86-64 run on the model machine: instructions, cycles on an in-order and an out-of-order core, cache misses, branches, and what bounds it.', options: [] },
|
|
{ name: 'pplus-view', kind: 'rendered', view: undefined, title: 'Any view by name', summary: 'Any of the rendered views, chosen with view= (run, steps, table, flow, data, life, proof, tests, check, translate, machine).', options: ['view'] },
|
|
{ name: 'pplus-hw', kind: 'machine', view: 'hw', title: 'The machine board', summary: 'The Hardware area\'s board over an x86-64 run: the listing beside the cards of a preset (registers and memory, caches, pipeline, the whole chip) or the views you name, every one drawn at every step, with a stepper.', options: ['preset', 'views', 'listing', 'stepper', 'max'] },
|
|
...Object.entries(HW_NAMES).map(([name, id]): ShortcodeDef => {
|
|
const v = boardView(id)!;
|
|
return { name: `pplus-hw-${name}`, kind: 'machine', view: 'hw', hw: name, title: v.label, summary: v.blurb, options: ['listing', 'stepper', 'max'] };
|
|
}),
|
|
{ name: 'pplus-playground', kind: 'live', view: 'playground', title: 'The whole playground', summary: 'The app in the page: every pane, the stepper, every inspect tab and the dock. The reader\'s edits are kept in their browser; Reset brings the page\'s version back.', options: ['panel', 'build', 'dock', 'docktab', 'editor', 'side', 'dockheight', 'theme', 'ro', 'height', 'problem', 'state'] },
|
|
{ name: 'pplus-embed', kind: 'live', view: 'any', title: 'One live view', summary: 'One view of the app with the code it reads: trace, table, flow, data, life, problems, proof, tests, compiler, asm, or one pane.', options: ['view', 'panel', 'build', 'theme', 'ro', 'showcall', 'split', 'height', 'problem', 'state'] },
|
|
{ name: 'pplus', kind: 'live', view: 'any', title: 'The original shortcode', summary: 'A live embed, a listing, or both (show=). Pages written for it keep working.', options: ['view', 'show', 'mode', 'text', 'panel', 'build', 'theme', 'ro', 'showcall', 'split', 'height', 'problem', 'state'] },
|
|
{ name: 'pplus-listing', kind: 'text', title: 'Listings', summary: 'The files as highlighted code blocks, without their header lines; a .tex file typeset as equations.', options: ['numbers', 'math', 'link', 'text'] },
|
|
{ name: 'pplus-tabs', kind: 'text', title: 'Tabs', summary: 'The files as a tabset, one tab per notation.', options: ['numbers', 'math'] },
|
|
{ name: 'pplus-link', kind: 'text', title: 'A link', summary: 'A link that opens the program in the app.', options: ['view', 'text'] },
|
|
];
|
|
|
|
export const SHORTCODE_NAMES: readonly string[] = SHORTCODES.map((s) => s.name);
|
|
|
|
export const OPTION_DOCS: Record<string, string> = {
|
|
lingo: 'a lingo file beside the page', matho: 'a LaTeX (.tex) file of equations', pseudo: 'a pseudo file', speco: 'a speco file (the specification)',
|
|
mojo: 'a Mojo file', asm: 'an x86-64 listing', setup: 'the x86-64 setup block: registers and memory',
|
|
lang: 'the pane that runs (default: the first of lingo, matho, pseudo, mojo, asm given)',
|
|
call: 'the call to run (default: the file\'s // CALL: line)', input: 'lines INPUT reads, separated by |', machine: 'the x86-64 machine model preset',
|
|
t: 'the step the stepper starts on', title: 'a title over the view', caption: 'a sentence under it', collapse: '1 folds it into a block the reader opens',
|
|
area: 'bridge, dev or hw: where "open in the playground" goes',
|
|
code: '1 prints the program above the view', numbers: '1 numbers the listing\'s lines', live: 'click adds "make it live", which puts the live view in its place',
|
|
height: 'the live frame\'s height in px (auto: fits its content)', compiler: 'auto (the real mojo when on the PATH), on, or off',
|
|
follow: 'the variables to show, comma-separated', max: 'the most steps kept (default 400; a longer machine run is sampled)', to: 'the notations to show, comma-separated',
|
|
layout: 'tabs (default), columns, or grid',
|
|
preset: 'the board\'s arrangement: regs (default), caches, pipeline or chip', views: 'the machine views to show, comma-separated (registers, memory, cache, pipeline, chip...)',
|
|
listing: '0 leaves out the x86-64 listing', column: 'Quarto\'s column for the figure: body, page (pplus-hw\'s default), screen...', stepper: '0 draws only step t, without a stepper', view: 'which view', panel: 'the tab the playground opens on', build: 'O0 (as written) or default (as mojo build does)',
|
|
dock: 'open or closed', docktab: 'the dock\'s tab', editor: 'the editor column\'s share of the width', side: 'the variables panel\'s share', dockheight: 'the editors\' share of the height',
|
|
theme: 'light or dark (default: follow the page)', ro: '1: read-only, nothing saved', showcall: '0 hides the run box', split: 'the code\'s share of the frame',
|
|
problem: 'a catalog problem instead of files', state: 'a state from the playground\'s Share dialog', show: 'embed, listing or both', mode: 'link: only a link', text: 'the link\'s text', math: '0 prints a .tex file as code', link: '1 adds a link to the app',
|
|
};
|
|
|
|
/** The shortcode as a page writes it. */
|
|
export function shortcodeText(name: string, attrs: Record<string, string>): string {
|
|
const parts = Object.entries(attrs).map(([k, v]) => `${k}="${v.replace(/"/g, '"')}"`);
|
|
return `{{< ${name}${parts.length ? ' ' + parts.join(' ') : ''} >}}`;
|
|
}
|
|
|
|
/**
|
|
* A title from a state (which anyone can write into a link) as a shortcode argument the Share dialog hands to a page
|
|
* author: one line, at most 120 characters, a double quote as `"` (pplus.lua reads it back), and none of the
|
|
* characters that could end the shortcode or start markup in the page it is pasted into (`<`, `>`, `{`, `}`).
|
|
*/
|
|
export function shortcodeTitle(title: string): string {
|
|
return title.replace(/[<>{}]/g, '').replace(/\s+/g, ' ').trim().slice(0, 120).replace(/"/g, '"');
|
|
}
|
|
|
|
const PANES: LangId[] = ['lingo', 'matho', 'pseudo', 'speco', 'mojo', 'asm'];
|
|
const list = (s: string | undefined) => (s ? s.split(/[\s,]+/).filter(Boolean) : undefined);
|
|
|
|
/**
|
|
* What a rendered shortcode asks render.ts for, given its options and the files beside the page (by name): the
|
|
* same request pplus.lua builds, for the gallery to draw what a page would get.
|
|
*/
|
|
export function requestFor(view: StaticView, attrs: Record<string, string>, files: Record<string, string>): RenderRequest {
|
|
const req: RenderRequest = { view, files: {} };
|
|
for (const p of PANES) if (attrs[p] && files[attrs[p]] !== undefined) req.files[p] = files[attrs[p]];
|
|
if (attrs.lang) req.lang = attrs.lang as LangId;
|
|
if (attrs.call) req.call = attrs.call;
|
|
if (attrs.input) req.input = attrs.input.split('|');
|
|
if (attrs.setup && files[attrs.setup] !== undefined) req.setup = files[attrs.setup];
|
|
if (attrs.machine) req.machine = attrs.machine;
|
|
if (attrs.t && Number.isFinite(Number(attrs.t))) req.t = Number(attrs.t);
|
|
if (attrs.title) req.title = attrs.title;
|
|
if (attrs.max && Number.isFinite(Number(attrs.max))) req.max = Number(attrs.max);
|
|
if (Number(attrs['prove-seconds']) > 0) req.proveSeconds = Number(attrs['prove-seconds']);
|
|
if (attrs.views) req.hw = list(attrs.views);
|
|
if (attrs.preset) req.preset = attrs.preset;
|
|
if (attrs.listing === '0') req.listing = false;
|
|
if (attrs.stepper === '0') req.stepper = false;
|
|
req.follow = list(attrs.follow);
|
|
req.to = list(attrs.to) as LangId[] | undefined;
|
|
return req;
|
|
}
|
|
|
|
/** The state a live shortcode puts in its iframe's URL: the same one pplus.lua writes. */
|
|
export function liveStateFor(attrs: Record<string, string>, files: Record<string, string>): PlayState {
|
|
const s = emptyState();
|
|
let first: LangId | null = null;
|
|
let call: string | undefined; let input: string[] | undefined;
|
|
for (const p of PANES) {
|
|
const text = attrs[p] ? files[attrs[p]] : undefined;
|
|
if (text === undefined) continue;
|
|
s.sources[p] = listingText(text, p);
|
|
first ??= p;
|
|
for (const line of text.split('\n')) {
|
|
const m = /^\s*(?:\/\/|%|#)\s*(CALL|INPUT):\s?(.*)$/.exec(line);
|
|
if (m?.[1] === 'CALL') call ??= m[2].trim();
|
|
if (m?.[1] === 'INPUT') (input ??= []).push(m[2]);
|
|
}
|
|
}
|
|
s.lang = (attrs.lang as LangId) || first || 'pseudo';
|
|
s.view = 'trace';
|
|
if (attrs.setup && files[attrs.setup] !== undefined) s.setup = files[attrs.setup];
|
|
const c = attrs.call ?? call;
|
|
if (c) s.call = c;
|
|
if (attrs.input) s.input = attrs.input.split('|').join('\n'); else if (input) s.input = input.join('\n');
|
|
if (attrs.title) s.title = attrs.title;
|
|
if (attrs.t) s.t = Number(attrs.t);
|
|
return s;
|
|
}
|