Move the engine core into core/, a project of its own (pplus-core)
What programs mean (the languages, translators, Mojo checker and
interpreter, prover, fuzzer, machine model, catalog problems and the Mojo
corpus with godbolt's stored answers) was mixed into the site's tree, so a
change to the prover and a change to a button went through the same gate
and the same docs. This moves all of it under core/, laid out as its own
repository, ready to be extracted with its history and pinned here as a
git submodule.
- core/: src/{engines,services,sync,mojo,exercises,curriculum,common},
mojo/, syntax/mojo.xml, its tests (with Workspace and workForProblem in
place of the site's Session), scripts (corpus pipeline, play, the
exercise and probe starters, engines export/diff), and its docs
(engines, trust, mojo-corpus, exercises, coverage). Its own pixi.toml,
package.json, README, AGENTS.md and CI workflow.
- core/tests/boundary.test.mjs: library modules use no DOM, import no
page widget, and import nothing outside src/.
- core/scripts/cli.mjs: pixi run cli check|run|prove|fuzz|translate.
- core/scripts/dafny.py: Dafny 4.11.0 pinned by version and SHA-256 per
platform, fetched into .tools/ (pixi run dafny-fetch, pixi run dafny).
- The site imports core only as #core/<path>.js: an import map in
index.html, "imports" in package.json for node, core's declarations for
tsc. The site's TypeScript builds core first (npm run build).
- assemble.sh, the Quarto engine copy, the render cache key, check-pages,
quarto-export and quarto-css read core/dist and core/mojo; quarto-css
copies core's syntax/mojo.xml into the extension.
- Site tests that covered engines moved to core; the rest keep Session.
- README, AGENTS.md, docs/app.md, docs/deploy.md and the CI workflow
describe the split (checkout with submodules; core's tests and corpus
status run against the pinned commit).
Gate: site 110 pass; core 307 pass; corpus status --strict passes.
Manual check: the assembled site opens Bridge (count-base-proved),
Developer and Hardware (count-base) with the editor, the stepper and the
board, and no module errors.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
This commit is contained in:
1567 files changed
+3670
-981
No files matched your search
+23
-23
@@ -32,7 +32,7 @@ Every area is an IDE-style workspace: the language panes as tabs over one editor
|
||||
|
||||
### The Hardware area
|
||||
|
||||
Two panes, and nothing shown twice. On the left the code (the Mojo and x86-64 tabs over one editor) and the stepper under it. On the right the **board** (`src/ui/hw/board.ts`), a set of cards in a two-column grid (twelve tracks, a half card spanning six): the course's own x86-64 views (`src/engines/asm86/views.js` and `hwviews.js`, the widgets the course pages use, with the course's stylesheets from `styles/course/`), mounted over the x86-64 pane's run and moved by the stepper, and the app's own views as cards too: Setup, Output, Problems, the Compiler, the Run view (for the Mojo pane), the counters, and the cache lines. The area has no inspect panel and no dock (`workspace: 'board'` in `AREAS`); Compile & run and a click on a diagnostic bring their card into view, adding it if the board does not show it.
|
||||
Two panes, and nothing shown twice. On the left the code (the Mojo and x86-64 tabs over one editor) and the stepper under it. On the right the **board** (`src/ui/hw/board.ts`), a set of cards in a two-column grid (twelve tracks, a half card spanning six): the course's own x86-64 views (`core/src/engines/asm86/views.js` and `hwviews.js`, the widgets the course pages use, with the course's stylesheets from `styles/course/`), mounted over the x86-64 pane's run and moved by the stepper, and the app's own views as cards too: Setup, Output, Problems, the Compiler, the Run view (for the Mojo pane), the counters, and the cache lines. The area has no inspect panel and no dock (`workspace: 'board'` in `AREAS`); Compile & run and a click on a diagnostic bring their card into view, adding it if the board does not show it.
|
||||
|
||||
**Arranging it.** Presets along the top set out cards that make sense to see at once. **+ Add a view** opens every card by group (Program, Registers and memory, Memory system, Time, The chip); click one to put it on the board or take it off. Drag a card by its title to move it (or use ↑ ↓), ↔ widens it to the whole row or narrows it to share one, × takes it off. The arrangement is kept per area (`layout.hw.board`, a list of `{ id, wide? }`, cleaned by `normalizeBoard`), and the preset buttons show which preset it is, if any. Every change is a pure function in `src/core/hardware.ts` (`moveItem`, `addItem`, `removeItem`, `toggleWide`, `presetOf`).
|
||||
|
||||
@@ -49,7 +49,7 @@ The presets:
|
||||
- **Mojo and the compiler**: the Run view of the Mojo pane, the real compiler's answer and listing (with Open in Hardware), the output and the problems.
|
||||
- **Counters** (a card in any arrangement): the run as totals in the style of `perf stat`, and for code sent from the Compiler view what each Mojo line cost.
|
||||
|
||||
**Mojo and x86-64.** The two are tabs over the one editor, never split side by side. x86-64 sent from the Compiler view ends each instruction with `; mojo line N`, godbolt's own line table (`forSimulator` in `src/mojo/att.ts`); through it, clicking a line in either pane marks the matching lines in the other tab, lit when that tab is selected (`asmMojoLines` and `relateAsmMojo` in `src/core/hardware.ts`). A short note in the pane head says so; for x86-64 written by hand, which has no such table, it says the lines are not linked. The Mojo there carries its generated label and godbolt badge, as everywhere. Compiling needs the network; without a listing the area works on hand-written x86-64 alone.
|
||||
**Mojo and x86-64.** The two are tabs over the one editor, never split side by side. x86-64 sent from the Compiler view ends each instruction with `; mojo line N`, godbolt's own line table (`forSimulator` in `core/src/mojo/att.ts`); through it, clicking a line in either pane marks the matching lines in the other tab, lit when that tab is selected (`asmMojoLines` and `relateAsmMojo` in `src/core/hardware.ts`). A short note in the pane head says so; for x86-64 written by hand, which has no such table, it says the lines are not linked. The Mojo there carries its generated label and godbolt badge, as everywhere. Compiling needs the network; without a listing the area works on hand-written x86-64 alone.
|
||||
|
||||
The board's **machine** switch (also in the Setup card): `teaching` (caches small enough that misses happen on small data), `realistic` (shaped like a desktop core: 64-byte lines, an L3, a next-line prefetcher), or `ideal`; and **virtual memory** turns on paging with a TLB. The state stores it as one string (`machine: 'teaching+paging'`; `parseMachine` and `machineSpec` in `src/core/hardware.ts`), and the run hands it to the hardware model through the trace, so the board's views and the counters always describe the same machine. With virtual memory on, a line is the physical one and the access keeps the address the program wrote.
|
||||
|
||||
@@ -64,13 +64,13 @@ Two independent badges sit beside any Mojo the site shows (pane head, Compiler v
|
||||
|
||||
### Best practices (the helper)
|
||||
|
||||
`src/mojo/practices.ts` (DOM-free) turns the gap between the translator's literal Mojo and the Mojo a person would write into things to learn from. It is **off by default in both the Bridge and the Developer area**: each area has its own switch (the toolbar's "Best practices" button), remembered in this browser (`pplus.practices.bridge`, `pplus.practices.dev`; `src/core/prefs.ts`), never in `PlayState` or a link. While a switch is off the rules never run (a spy test holds it to that) and nothing about them is shown. The translator never imports the helper, so the Bridge's Mojo is the same literal translation either way (a grep gate and a snapshot test keep it so).
|
||||
`core/src/mojo/practices.ts` (DOM-free) turns the gap between the translator's literal Mojo and the Mojo a person would write into things to learn from. It is **off by default in both the Bridge and the Developer area**: each area has its own switch (the toolbar's "Best practices" button), remembered in this browser (`pplus.practices.bridge`, `pplus.practices.dev`; `src/core/prefs.ts`), never in `PlayState` or a link. While a switch is off the rules never run (a spy test holds it to that) and nothing about them is shown. The translator never imports the helper, so the Bridge's Mojo is the same literal translation either way (a grep gate and a snapshot test keep it so).
|
||||
|
||||
A rule is `{ id, title, why, docUrl, example, apis, detect }`. The starting rules: declare-then-assign → `var n = …`; `x = x + 1` → `x += 1`; an index loop that only reads codepoints → `for cp in t.codepoint_slices()`; `raises` on a function that cannot raise; a never-changed number that sizes a loop → `comptime`; argument conventions (`imm` written out is the default; `mut` on an argument never changed); `reserve` before a loop that appends a known number of times; `name^` for a last use handed to a `var` argument; `.copy()` for a list copy that says so. (The plan said `read`; Mojo 1.1.0 renamed it `imm`, so the helper says `imm`.)
|
||||
|
||||
- **Bridge:** the Best practices dock tab lists each finding with the Mojo line, the pseudo line it came from (the hub's line map), the reason, before and after, the manual link, and, where true, how to write the pseudo so the translator writes the better form. Clicking one lights both lines. The Mojo is read-only, so rewrites are shown, not applied. **Show idiomatic version** (in the Mojo tab, off until chosen) shows a copy with the safe rewrites applied, only if it passes the checker no worse than the literal one and the interpreter prints exactly what the literal one prints; it keeps the generated label ("Generated from pseudo, with N best-practice rewrites").
|
||||
- **Developer:** findings are `note` diagnostics with origin "best practices" (never an error or a warning, so they never look like the compiler) in Problems and the gutter, each with a one-click fix where the rewrite is safe. A rule that cannot promise a safe rewrite (`comptime`) explains and leaves the editing to the student.
|
||||
- **Tests** (`tests/practices.test.mjs`): every rule's example passes the checker, runs, and prints the same before and after, and the rule's fix turns one into the other; every method a rewrite names is in the harvested index; a false-positive gate runs the rules over Modular's own tested programs in `mojo/corpus/manual/` against a reviewed allowlist; each exercise's findings are pinned by a snapshot; applying every fix to each exercise's generated Mojo and each `mojo/local/` program keeps it checking and printing the same.
|
||||
- **Tests** (`core/tests/practices.test.mjs`): every rule's example passes the checker, runs, and prints the same before and after, and the rule's fix turns one into the other; every method a rewrite names is in the harvested index; a false-positive gate runs the rules over Modular's own tested programs in `core/mojo/corpus/manual/` against a reviewed allowlist; each exercise's findings are pinned by a snapshot; applying every fix to each exercise's generated Mojo and each `core/mojo/local/` program keeps it checking and printing the same.
|
||||
|
||||
### Saved versions
|
||||
|
||||
@@ -116,14 +116,14 @@ The **Share** button in the app produces the app link, a ready-to-paste `<iframe
|
||||
- **Table of values**: the table a student draws by hand, drawn by the machine: a column per step that changed something, a row per name, the new value in the cell, blank for unchanged; click a step to jump the stepper there; copy as text.
|
||||
- **Flowchart**: laid out from the structure of the pseudo (so loops loop and branches branch), each box shaded by how often its line ran in the last run, each loop labeled with its passes, each arrow out of a decision with how often it was taken; a box that never ran is dashed. Click a box to reveal its line; download as SVG.
|
||||
- **Data flow**: inputs on the left, `RETURN` and `OUTPUT` on the right, one arrow per assignment that reads the one and writes the other, labeled with its line, dashed when a condition only decides whether it happens.
|
||||
- **matho pane**: equations as a source language, written in LaTeX (`src/services/matho.ts`). One `FUNCTION` per equation; `\sum` and `\prod` become accumulator loops, subscripts become positions (with the 1-based shift when the sum starts at 1), `\begin{cases}` becomes `IF`/`ELSEIF`, Greek letters become names, references to earlier equations become calls hoisted out of loops when their arguments do not change. Every decision is a note on the equation's line; integrals, infinity, limits and derivatives are refused with the finite procedure to write instead. The trace steps the pseudo with the marker on the equation each step came from.
|
||||
- **matho pane**: equations as a source language, written in LaTeX (`core/src/services/matho.ts`). One `FUNCTION` per equation; `\sum` and `\prod` become accumulator loops, subscripts become positions (with the 1-based shift when the sum starts at 1), `\begin{cases}` becomes `IF`/`ELSEIF`, Greek letters become names, references to earlier equations become calls hoisted out of loops when their arguments do not change. Every decision is a note on the equation's line; integrals, infinity, limits and derivatives are refused with the finite procedure to write instead. The trace steps the pseudo with the marker on the equation each step came from.
|
||||
- **Numerics**: `SUM_OF MEAN_OF VARIANCE_OF STDEV_OF MEDIAN_OF DOT NORM_OF FILL CHOOSE RANDN FLOOR CEIL LOG10 SIN COS TAN ATAN2 PI()`, and `PARALLEL FOR`, a loop whose passes may run at once, checked at run time: two passes touching one location stop the run with a data race that names the location and the passes.
|
||||
|
||||
- **Mojo for every exercise with pseudo**: each has its Mojo in `mojo/local/`, so the Developer and Hardware areas always have something to show for it; `tests/mojo.test.mjs` runs each Mojo program in the interpreter and checks it prints what the exercise expects.
|
||||
- **Mojo for every exercise with pseudo**: each has its Mojo in `core/mojo/local/`, so the Developer and Hardware areas always have something to show for it; `core/tests/mojo.test.mjs` runs each Mojo program in the interpreter and checks it prints what the exercise expects.
|
||||
- **Panes**: the area's own (see the table above), dimmed when empty (a dimmed tab opens an empty pane to write in), as tabs over one editor (CodeMirror: search and replace with Ctrl+F, go to line with Ctrl+G, bracket matching, undo and redo; Tab indents, Ctrl+/ comments). The editor is never split: in the Bridge a short note in the pane head says the other tabs update as you type (lingo and matho update the pseudo, and the pseudo the Mojo made from it), and clicking a line marks the lines it became in the next tab down; Hardware does the same between Mojo and x86-64. Drag the dividers to resize (double-click resets); the widths, the dock tab, and what is folded are remembered in the share link.
|
||||
- **The side column** is the inspect panel. Its tabs are offered only when they mean something for the pane (Prove for the pseudo family) and dimmed, with the reason, when the run has nothing for them yet.
|
||||
- **The Run view** (the first tab, in the Bridge and the Developer area; `src/core/runview.ts`, drawn by `src/ui/views/run.ts`) is the whole run read top to bottom, one row per step: its number, its line, what ran (indented by call depth, with what it printed), and a column for each variable you **follow**, holding its value after that step: in color where the step wrote it (with the position, `[5, 6]`, when it wrote one element), faded where it carries over, underlined where the step reads it, hatched where it is not in scope. The lifecycle of the value a variable names (Mojo: made ●, copied ⧉, moved in ⇢, moved out ⇥, destroyed ✕) is marked in the same cell; events of values no column names are noted beside the step. Above the rows, the followed variables as they stand at the stepper's position, with a ruler for a string or list and a grid for a table, the element just written and the one about to be read marked. **+ variables** opens a picker of every variable in the run, by routine; until you choose, it follows the variables of the routine that does the most work. The choice is kept per area (`layout.follow`). "Only steps that change something" hides the rest. Click a row to step there; the stepper keeps its row in view. It replaces the Variables panel, the trace table, the table of values and the Lifetimes tab, which each showed part of this.
|
||||
- **The Tests tab** is a fuzzer that shows its work (`src/core/fuzz.ts`, drawn by `src/ui/views/tests.ts`). For each routine (the pseudo's, with the speco woven in; or each Mojo function other than `main`) it lists **what each input must do** (finish within the step limit; raise no runtime error, or for Mojo no abort and no uncaught raise; keep every REQUIRE, ENSURE, INVARIANT, DECREASES and ASSERT, with inputs that break a REQUIRE skipped rather than failed; give the same answer when run again), **how the inputs were made** (each parameter's generator, with the values it tries first, and each strategy with how many inputs it made: edge cases in combination, every DNA string up to three letters for a routine that reads one, seeded random values, and mutations of the inputs that reached a line nothing earlier had reached, as a coverage-guided fuzzer does), each **failure** with the case that found it and every step of shrinking it to the smallest input that still fails the same way (**Step through this input** puts that call in the call box and shows the run), the **lines reached** by how many inputs (a line no input reached is flagged), the **answers** given and how often, and **every case** run with its strategy, input, outcome, answer or error, and steps, filterable by outcome and strategy. The seed and the number of inputs (100 to 3,000) are chosen at the top; the same seed always makes the same inputs. `tests/fuzz.test.mjs` runs it on every exercise.
|
||||
- **The Tests tab** is a fuzzer that shows its work (`core/src/common/fuzz.ts`, drawn by `src/ui/views/tests.ts`). For each routine (the pseudo's, with the speco woven in; or each Mojo function other than `main`) it lists **what each input must do** (finish within the step limit; raise no runtime error, or for Mojo no abort and no uncaught raise; keep every REQUIRE, ENSURE, INVARIANT, DECREASES and ASSERT, with inputs that break a REQUIRE skipped rather than failed; give the same answer when run again), **how the inputs were made** (each parameter's generator, with the values it tries first, and each strategy with how many inputs it made: edge cases in combination, every DNA string up to three letters for a routine that reads one, seeded random values, and mutations of the inputs that reached a line nothing earlier had reached, as a coverage-guided fuzzer does), each **failure** with the case that found it and every step of shrinking it to the smallest input that still fails the same way (**Step through this input** puts that call in the call box and shows the run), the **lines reached** by how many inputs (a line no input reached is flagged), the **answers** given and how often, and **every case** run with its strategy, input, outcome, answer or error, and steps, filterable by outcome and strategy. The seed and the number of inputs (100 to 3,000) are chosen at the top; the same seed always makes the same inputs. `core/tests/fuzz.test.mjs` runs it on every exercise.
|
||||
- **Views that follow the run**: the **Flowchart** shades by the run so far and marks the box that runs next; the **Data flow** lights up the names the next line reads and the name the last line wrote.
|
||||
- **Step colors**: every step in the Run view and the "next" box is colored by what it does (writes a value, decides, loop control, enters a routine, returns, input or output, a value destroyed, raises or fails); the legend is in the inspect panel's tab row.
|
||||
- **The stepper** is docked under the editor, at the editor column's width, as part of it: first, back, step, last, play and the slider; the loop-pass jumps, run to breakpoint, predict mode, only writes, speed and CSV; the loops in flight (or the machine's counts); and what runs next. It stays visible when the dock is folded.
|
||||
@@ -135,9 +135,9 @@ The **Share** button in the app produces the app link, a ready-to-paste `<iframe
|
||||
|
||||
## Translation between languages
|
||||
|
||||
Pseudo is the hub: every other notation translates to or from it, so four languages need six translators (the restructure plan, section 2.3). The translators are DOM-free functions of text under `src/sync/`; `src/sync/types.ts` has their shapes and the line maps that say which input line each output line came from.
|
||||
Pseudo is the hub: every other notation translates to or from it, so four languages need six translators (the restructure plan, section 2.3). The translators are DOM-free functions of text under `core/src/sync/`; `core/src/sync/types.ts` has their shapes and the line maps that say which input line each output line came from.
|
||||
|
||||
**pseudo → Mojo** (`src/sync/pseudo-to-mojo.ts`) is one way only, and its output is always labeled generated: the first line is `# Generated by Programming+ from pseudo. Not reviewed for Mojo best practices.` (`src/sync/header.ts`). It is an app-owned port of the Mojo half of the course engine's `translate.js`, and it is deliberately literal: `var n: Int` then `n = …`, `total = total + 1`, an index loop over codepoints. Idiomatic rewrites belong to the optional best-practices helper, so a student can see the difference.
|
||||
**pseudo → Mojo** (`core/src/sync/pseudo-to-mojo.ts`) is one way only, and its output is always labeled generated: the first line is `# Generated by Programming+ from pseudo. Not reviewed for Mojo best practices.` (`core/src/sync/header.ts`). It is an app-owned port of the Mojo half of the course engine's `translate.js`, and it is deliberately literal: `var n: Int` then `n = …`, `total = total + 1`, an index loop over codepoints. Idiomatic rewrites belong to the optional best-practices helper, so a student can see the difference.
|
||||
|
||||
- `def main()` is written from the pseudo's own lines, then from the call being run: `COUNT_BASE('A', "GATTACA")` becomes `print(count_base("A", "GATTACA"))`, with `TRUE` as `True`, a character as a one-letter `String`, and an integer given to a `FLOAT` parameter as `1.0`.
|
||||
- `raises` is inferred (a dictionary read, `input()`, `atol`, a failed `ASSERT`, or a call to a routine that raises, transitively). Imports (`Set`, `sort`, the math functions) come from the harvested standard-library index, and only for names the translation uses.
|
||||
@@ -145,27 +145,27 @@ Pseudo is the hub: every other notation translates to or from it, so four langua
|
||||
- It never invents Mojo. A line with no faithful spelling (a loop condition that would need such a loop, a built-in the standard library lacks) becomes `raise Error("not translated: pseudo line N")` and a `translate-gap` warning on the pseudo line; the program stops there instead of printing a plausible wrong answer. The pseudo's own mistakes (`unsupported`) are reported, not translated.
|
||||
- Two behaviors differ by design, and a literal translation keeps Mojo's: dividing a `FLOAT` by zero stops the notation but gives `nan` in Mojo, and `PARALLEL FOR` runs its passes in order with no race detector. Translation notes (`translate-divide`, `translate-each-order`, and so on) say so on the line.
|
||||
|
||||
`tests/sync-mojo.test.mjs` holds the translation to the pseudo: for every exercise with pseudo and every program in `tests/corpus/`, the generated Mojo has no checker errors, runs in the interpreter, and prints what the pseudo prints (compared by value, not text: `TRUE` and `True`, `3` and `3.0`, a map's keys in any order). Programs it cannot hold to that are listed in the test with a reason (the interpreter declines `chr`, `ord`, random numbers and the math functions; the checker is right about the two programs that read an unset variable), and `AGREE_AT_LEAST` is a floor that can only rise. A snapshot of the generated Mojo for every exercise is in `tests/snapshots/sync-mojo/`; when a change to the translator is wanted, run the test with `UPDATE_SNAPSHOTS=1` and review the diff.
|
||||
`core/tests/sync-mojo.test.mjs` holds the translation to the pseudo: for every exercise with pseudo and every program in `core/tests/corpus/`, the generated Mojo has no checker errors, runs in the interpreter, and prints what the pseudo prints (compared by value, not text: `TRUE` and `True`, `3` and `3.0`, a map's keys in any order). Programs it cannot hold to that are listed in the test with a reason (the interpreter declines `chr`, `ord`, random numbers and the math functions; the checker is right about the two programs that read an unset variable), and `AGREE_AT_LEAST` is a floor that can only rise. A snapshot of the generated Mojo for every exercise is in `core/tests/snapshots/sync-mojo/`; when a change to the translator is wanted, run the test with `UPDATE_SNAPSHOTS=1` and review the diff.
|
||||
|
||||
**pseudo → lingo** (`src/sync/pseudo-to-lingo.ts`) writes the English that the lingo reader (`readSteps` in the course engine's `english.js`) understands, so the lingo pane can follow the pseudo pane. The grammar belongs to the reader, and the translator is held to it: before returning, it reads its own output back and checks that the same routines come out with the same kinds of input. If English cannot say something the way the reader needs it, the result is `unsupported` with a warning on the pseudo line, and the pane keeps its last good text instead of showing English that does not read.
|
||||
**pseudo → lingo** (`core/src/sync/pseudo-to-lingo.ts`) writes the English that the lingo reader (`readSteps` in the course engine's `english.js`) understands, so the lingo pane can follow the pseudo pane. The grammar belongs to the reader, and the translator is held to it: before returning, it reads its own output back and checks that the same routines come out with the same kinds of input. If English cannot say something the way the reader needs it, the result is `unsupported` with a warning on the pseudo line, and the pane keeps its last good text instead of showing English that does not read.
|
||||
|
||||
- Names follow the reader's slots: a single letter or a Capitalized word. A name that is neither (`CURRENT_MAX`) has no English form yet.
|
||||
- Each input is first written tersely, letting the steps show what it is. If the reader would take an input as something else, the translator adds a sentence saying what each input is ("L is a list of whole numbers.") and reads again.
|
||||
- A name first set inside a block is given its value before the block, because English names are scoped by block.
|
||||
- Left unsupported on purpose, each with its reason on the line: steps outside a routine (every English step belongs to a routine), records, `BYREF`, `REPEAT`, `PARALLEL FOR`, `DEFINE`, `CONSTANT`, a fixed-length `ARRAY`, maps keyed by a character, and `IN` over a String.
|
||||
|
||||
`tests/sync-lingo.test.mjs` holds it to that for every exercise, every corpus program, and the single-construct fixtures in `tests/helpers/sync-programs.mjs`: the English reads; lowering it back to pseudo gives a program with the same output and the same kind of stop; and writing English again from that pseudo gives the same text (comments aside). `SUPPORTED_AT_LEAST` is a floor that can only rise.
|
||||
`core/tests/sync-lingo.test.mjs` holds it to that for every exercise, every corpus program, and the single-construct fixtures in `core/tests/helpers/sync-programs.mjs`: the English reads; lowering it back to pseudo gives a program with the same output and the same kind of stop; and writing English again from that pseudo gives the same text (comments aside). `SUPPORTED_AT_LEAST` is a floor that can only rise.
|
||||
|
||||
**pseudo → matho** (`src/sync/pseudo-to-matho.ts`) writes the equations, in LaTeX, for the programs that are equations, and refuses the rest. It recognizes the shapes the matho reader lowers: a `FUNCTION` that returns one value; an accumulator loop (`Total <- 0` then `Total <- Total + …`, or `1` and `*`) as `\sum` or `\prod`, with the bounds the reader uses (`FOR I <- 0 TO N` is `i=0` to `n-1`; a 1-based loop is `i=1` to `n`, and `X[I - 1]` is `x_i`); `FOR EACH` over an input list as a sum over a set; an `IF`/`ELSEIF` chain whose every branch returns as `\begin{cases}`; a call of an earlier function as a reference to its equation; and `SQRT`, `ABS`, `FLOOR`, `CEIL`, `CHOOSE`, `SIN`/`COS`/`TAN`/`EXP`/`LOG`/`LOG10`/`LOG2`, `MIN`, `MAX`, `PI()`, `DOT` and `NORM_OF`. Names given to values before the `RETURN` (the reader's hoisted calls, a temporary) are substituted where they are used.
|
||||
**pseudo → matho** (`core/src/sync/pseudo-to-matho.ts`) writes the equations, in LaTeX, for the programs that are equations, and refuses the rest. It recognizes the shapes the matho reader lowers: a `FUNCTION` that returns one value; an accumulator loop (`Total <- 0` then `Total <- Total + …`, or `1` and `*`) as `\sum` or `\prod`, with the bounds the reader uses (`FOR I <- 0 TO N` is `i=0` to `n-1`; a 1-based loop is `i=1` to `n`, and `X[I - 1]` is `x_i`); `FOR EACH` over an input list as a sum over a set; an `IF`/`ELSEIF` chain whose every branch returns as `\begin{cases}`; a call of an earlier function as a reference to its equation; and `SQRT`, `ABS`, `FLOOR`, `CEIL`, `CHOOSE`, `SIN`/`COS`/`TAN`/`EXP`/`LOG`/`LOG10`/`LOG2`, `MIN`, `MAX`, `PI()`, `DOT` and `NORM_OF`. Names given to values before the `RETURN` (the reader's hoisted calls, a temporary) are substituted where they are used.
|
||||
|
||||
- Everything else is `unsupported` with the construct and its line: "matho has no form for a WHILE loop (line 4)". An equation has a value, so output, input, text, a yes-or-no answer, a procedure, a record, steps outside a function, and a loop that does more than add up are all refused.
|
||||
- Names. The reader makes `\bar{x}` into `X_BAR` and `\sigma` into `SIGMA`, so the pseudo has lost the student's spelling. The `NameMap` hint (`hints.names`, keyed by the upper-case pseudo name) carries it back; without one, `SIGMA` is `\sigma`, `X_BAR` is `\bar{x}`, a single letter is lower case, and a longer name is `\text{...}`. A hint is checked like everything else, and one that does not lower back to the function is refused.
|
||||
- It never writes an equation that reads as something else. The LaTeX is lowered again by the matho reader and held to the pseudo: the same function names, inputs of the same kind, and the same values on three sets of sample inputs (stopping the same way where the pseudo stops). A program that fails is refused.
|
||||
- Comments are not carried across. The lowering writes each equation as a comment above its function, and carrying that back would put a stale copy of the equation above the new one.
|
||||
|
||||
`tests/sync-matho.test.mjs` holds it to three checks on every equation set in `tests/helpers/sync-programs.mjs` (the sets `tests/matho.test.mjs` works by hand): the LaTeX reads, the pseudo it lowers to behaves like the original, and writing it again from that pseudo gives the same LaTeX. Two sets are listed as gaps with their reasons (a matrix row written `y_i`, and a second factorial whose counter the reader names `K2`); `SUPPORTED_AT_LEAST` is a floor that can only rise. Programs from the exercises and the corpus are accepted or refused the same way, with a located reason.
|
||||
`core/tests/sync-matho.test.mjs` holds it to three checks on every equation set in `core/tests/helpers/sync-programs.mjs` (the sets `core/tests/matho.test.mjs` works by hand): the LaTeX reads, the pseudo it lowers to behaves like the original, and writing it again from that pseudo gives the same LaTeX. Two sets are listed as gaps with their reasons (a matrix row written `y_i`, and a second factorial whose counter the reader names `K2`); `SUPPORTED_AT_LEAST` is a floor that can only rise. Programs from the exercises and the corpus are accepted or refused the same way, with a located reason.
|
||||
|
||||
**The hub** (`src/sync/hub.ts`, tests in `tests/sync-hub.test.mjs`) puts the translators together. It is pure: a function of the texts it is given, with no DOM and no `localStorage`. `Session.setSource` hands an edit in a linked pane (lingo, matho, pseudo, speco) to it and applies the result in one change event; Mojo and x86-64 are stored as typed.
|
||||
**The hub** (`core/src/sync/hub.ts`, tests in `core/tests/sync-hub.test.mjs`) puts the translators together. It is pure: a function of the texts it is given, with no DOM and no `localStorage`. `Session.setSource` hands an edit in a linked pane (lingo, matho, pseudo, speco) to it and applies the result in one change event; Mojo and x86-64 are stored as typed.
|
||||
|
||||
1. **The pane you edit is the authority** (`state.sync.authority`). The edit produces a new pseudo, directly or by lowering, and the other linked panes are regenerated from it. The pane that was edited is never rewritten, so typing never fights the cursor.
|
||||
2. **Contracts ride along.** Lingo and matho cannot say contracts, so an edit in either weaves the speco into the pseudo it produced, and the speco is re-derived from that pseudo (`reconcileSpec`, which keeps claims about a routine or loop that is gone). An edit in speco replaces the pseudo's contracts with its own (`weave` in replace mode), and lingo and matho, which ignore contracts, follow.
|
||||
@@ -177,7 +177,7 @@ Pseudo is the hub: every other notation translates to or from it, so four langua
|
||||
|
||||
`state.sync` (`{ authority, stale, names }`) is part of the saved state and the share link. It is bookkeeping, not an edit: a state whose texts are the problem's own is unedited whatever `sync` says. `names` is the student's spelling of equation names (`\overline{x}`), so a trip through pseudo restores it.
|
||||
|
||||
**Coverage.** `tests/sync-coverage.test.mjs` runs all three translators over every exercise, corpus program and fixture and writes [sync-coverage.md](sync-coverage.md): how many each says completely, and, for every program it cannot say, what it has no form for. Each translator has a floor in the test.
|
||||
**Coverage.** `core/tests/sync-coverage.test.mjs` runs all three translators over every exercise, corpus program and fixture and writes [sync-coverage.md](../core/docs/sync-coverage.md): how many each says completely, and, for every program it cannot say, what it has no form for. Each translator has a floor in the test.
|
||||
|
||||
## Mojo
|
||||
|
||||
@@ -185,13 +185,13 @@ The distinction that shapes it: [Mojo Quest](https://quest.mojolang.org) teaches
|
||||
|
||||
Everything is pinned to **Mojo 1.1.0** and checked against the real compiler on [Compiler Explorer](https://godbolt.org) (`mojo_1_1_0`). Programming+ ships no compiler and never claims a program compiles without asking one.
|
||||
|
||||
**The Mojo pane** is edited like the pseudo: highlighting built from the compiler's own token table (docstrings across lines, the ownership words `imm`/`mut`/`out`/`deinit`/`var`/`ref`, the transfer `^`, and the words 1.1.0 removed, such as `fn`, underlined), the VS Code extension's indentation rule, Ctrl+/ for comments, and hover text for the ownership vocabulary. Before compiling, Programming+'s own checker (`src/mojo/`) reports what it is certain the compiler would: code at file scope, an empty body, an untyped parameter, a method without self, no `main`, an implicit declaration, an unknown name (with the compiler's import hint), removed syntax such as `fn`, each in the compiler's own words. `tests/mojo-check.test.mjs` scores it against godbolt: it may never report an error on a program the compiler accepts, or one the compiler did not make. Code it cannot read yet gets a note, not an error.
|
||||
**The Mojo pane** is edited like the pseudo: highlighting built from the compiler's own token table (docstrings across lines, the ownership words `imm`/`mut`/`out`/`deinit`/`var`/`ref`, the transfer `^`, and the words 1.1.0 removed, such as `fn`, underlined), the VS Code extension's indentation rule, Ctrl+/ for comments, and hover text for the ownership vocabulary. Before compiling, Programming+'s own checker (`core/src/mojo/`) reports what it is certain the compiler would: code at file scope, an empty body, an untyped parameter, a method without self, no `main`, an implicit declaration, an unknown name (with the compiler's import hint), removed syntax such as `fn`, each in the compiler's own words. `core/tests/mojo-check.test.mjs` scores it against godbolt: it may never report an error on a program the compiler accepts, or one the compiler did not make. Code it cannot read yet gets a note, not an error.
|
||||
|
||||
**Compile & run** (Ctrl+Enter on the Mojo pane) sends the program to godbolt.org in one request: the compiler's answer, the program's output (the input box feeds `input()`), and the listing. The **Compiler** view shows them. The compiler's messages land on their lines with its fix-its as one-click fixes (an implicit copy offers "transferring the value with '^'" or "copy it explicitly with '.copy()'"). The listing is grouped by function, your own first, in Intel syntax translated from godbolt's AT&T (or the original). **Send to x86-64 pane** puts one function, and the functions of yours it calls, on the model machine with its arguments' registers ready and the listing's read-only strings placed in memory; each call into the standard library becomes a stub that stops the run where the real program would enter the library, and says so. `docs/asm-coverage.md` is the census of every instruction compiled Mojo uses against what the machine models (everything but 256-bit AVX2), and `tests/asm-coverage.test.mjs` keeps it that way. Build "as written" (`-O0`, the default, which keeps every function you wrote) or "optimized" (what `mojo build` does: small functions fold into their callers). An edit after compiling marks the answer stale rather than showing it on the wrong lines. **Step through** runs the Mojo pane in Programming+'s own interpreter (`src/mojo/interp.ts`): line by line, with the variables it follows, what each line reads and writes, loop passes, breakpoints, and each value's lifetime, in the Run view. `tests/mojo-run.test.mjs` holds it to godbolt: on every program godbolt ran, it prints exactly what that run printed, or declines and says why.
|
||||
**Compile & run** (Ctrl+Enter on the Mojo pane) sends the program to godbolt.org in one request: the compiler's answer, the program's output (the input box feeds `input()`), and the listing. The **Compiler** view shows them. The compiler's messages land on their lines with its fix-its as one-click fixes (an implicit copy offers "transferring the value with '^'" or "copy it explicitly with '.copy()'"). The listing is grouped by function, your own first, in Intel syntax translated from godbolt's AT&T (or the original). **Send to x86-64 pane** puts one function, and the functions of yours it calls, on the model machine with its arguments' registers ready and the listing's read-only strings placed in memory; each call into the standard library becomes a stub that stops the run where the real program would enter the library, and says so. `core/docs/asm-coverage.md` is the census of every instruction compiled Mojo uses against what the machine models (everything but 256-bit AVX2), and `core/tests/asm-coverage.test.mjs` keeps it that way. Build "as written" (`-O0`, the default, which keeps every function you wrote) or "optimized" (what `mojo build` does: small functions fold into their callers). An edit after compiling marks the answer stale rather than showing it on the wrong lines. **Step through** runs the Mojo pane in Programming+'s own interpreter (`core/src/mojo/interp.ts`): line by line, with the variables it follows, what each line reads and writes, loop passes, breakpoints, and each value's lifetime, in the Run view. `core/tests/mojo-run.test.mjs` holds it to godbolt: on every program godbolt ran, it prints exactly what that run printed, or declines and says why.
|
||||
|
||||
**An exercise's Mojo** is a program in `mojo/local/`, named by the exercise's `mojoProgram`. `corpus.py verify` checks it on godbolt, and the pane's badge says "verified on Mojo 1.1.0" only when godbolt's answer passed the program's own expectation.
|
||||
**An exercise's Mojo** is a program in `core/mojo/local/`, named by the exercise's `mojoProgram`. `corpus.py verify` checks it on godbolt, and the pane's badge says "verified on Mojo 1.1.0" only when godbolt's answer passed the program's own expectation.
|
||||
|
||||
**The corpus** behind all of this (the compiler's own words, Modular's tested programs, our probes, and godbolt's stored answers) is described in [mojo-corpus.md](mojo-corpus.md).
|
||||
**The corpus** behind all of this (the compiler's own words, Modular's tested programs, our probes, and godbolt's stored answers) is described in [mojo-corpus.md](../core/docs/mojo-corpus.md).
|
||||
|
||||
## speco
|
||||
|
||||
@@ -208,16 +208,16 @@ SPEC COUNT_BASE(B, T)
|
||||
|
||||
**Where speco is going.** The next stage lets the same claims live as comments on the pseudo and the Mojo a student already has (`# @requires`, `# @ensures`, `# @invariant` on the line they govern), so a specification never has to be a separate document. Checking is two-layered and honest about which layer answered: every claim is evaluated on every step of the interpreter's run and on the generated inputs (a runtime check: "held on 300 inputs", or the smallest input that broke it), and the claims the prover can read are handed to it, so an obligation shows as *proved*, *tested*, or *broken*, never conflated.
|
||||
|
||||
**Speco and pseudo are two views of one set of contracts** (`src/services/speco.ts`), and neither loses a claim:
|
||||
**Speco and pseudo are two views of one set of contracts** (`core/src/services/speco.ts`), and neither loses a claim:
|
||||
|
||||
- `extractSpec(pseudo)` reads the contracts out of the pseudo as a speco document.
|
||||
- `weave(pseudo, spec)` inserts a speco's claims, never duplicating what is there. This is what the proof view uses. `weave(pseudo, spec, { replace: true })` is the other mode, for when the speco is the authority: for each `SPEC` unit it first removes the routine's `REQUIRE`/`ENSURE`/`DECREASES` and the `INVARIANT`/`DECREASES` of every loop the unit selects, then inserts the speco's. Routines and loops the speco does not name are left alone.
|
||||
- `reconcileSpec(pseudo, previous)` is the speco that follows the pseudo when the pseudo is edited: what the pseudo says, plus every claim the previous speco made about a routine or loop the pseudo no longer has. Those stay, under a `// kept:` comment that says why, with a warning on their line; they return to the routine or loop when it comes back, even before the pseudo has written them. A contract deleted in the pseudo, from a spec that was not waiting, is deleted from the speco too.
|
||||
|
||||
These laws are tested in `tests/sync-speco.test.mjs`, for `count-base-proved`, `match-proved`, and every corpus program with contracts: `extract(weave(P, extract(P))) === extract(P)`; weaving twice changes nothing; a speco woven into the same pseudo with its contracts removed, then extracted, comes back (and the contracts written are the original's, up to spelling); and reconciling is a fixed point. Holding the laws found one bug, now fixed: a symbol just inside a bracket, `(∀ K …)`, was lowered to `( FORALL K …)`, so the text drifted by a space on every round trip.
|
||||
These laws are tested in `core/tests/sync-speco.test.mjs`, for `count-base-proved`, `match-proved`, and every corpus program with contracts: `extract(weave(P, extract(P))) === extract(P)`; weaving twice changes nothing; a speco woven into the same pseudo with its contracts removed, then extracted, comes back (and the contracts written are the original's, up to spelling); and reconciling is a fixed point. Holding the laws found one bug, now fixed: a symbol just inside a bracket, `(∀ K …)`, was lowered to `( FORALL K …)`, so the text drifted by a space on every round trip.
|
||||
|
||||
## Known limits
|
||||
|
||||
- The engines live in this repository ([engines.md](engines.md)). The prover is sound and incomplete: it proves only what follows on every path it examined, and `tests/prover-soundness.test.mjs` holds it to that; English is still lowered to pseudo through text, and the parser, checker and interpreter are still JavaScript without tests of their own beyond the app's.
|
||||
- The engines live in pplus-core, the `core/` submodule ([engines.md](../core/docs/engines.md)). The prover is sound and incomplete: it proves only what follows on every path it examined, and `core/tests/prover-soundness.test.mjs` holds it to that; English is still lowered to pseudo through text, and the parser, checker and interpreter are still JavaScript without tests of their own beyond the app's.
|
||||
- The assembly pane takes the course's Intel-syntax subset; directives and `[rip + label]` are not supported yet.
|
||||
- Student work persists in the browser only.
|
||||
Reference in new issue
Block a user