A2: alpha acceptance checklist and cargo xtask demo-project
docs/alpha-checklist.md turns the six alpha workflows into manual steps for Windows and macOS (action, expected result, a box per platform, about 40 minutes each) and says how to report a failure. cargo xtask demo-project DIR creates the offline demo the steps run against: a small PHP shop (classes, an interface, a function, one deliberate error), a history by three authors from 2024 to 2026 with a merged branch and a tag, the branch feature/discounts that conflicts with main, and a bare origin.git holding a remote-only branch and one commit the project has not fetched yet. Tested against real git. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
83aeec68c0
commit
13c42ccc40
6 changed files with 1071 additions and 2 deletions
189
docs/alpha-checklist.md
Normal file
189
docs/alpha-checklist.md
Normal file
|
|
@ -0,0 +1,189 @@
|
|||
# Alpha acceptance checklist
|
||||
|
||||
> **Status:** C7 A2, written against main `da58c83` (M0–M4) · **Last updated:** 2026-10-31
|
||||
|
||||
The alpha gate ([`roadmap.md`](roadmap.md) › Alpha gate) asks for six workflows to work end to end. This checklist turns them into steps you do by hand, once on Windows and once on macOS. Each step names the action, then what you should see. Plan on 30–45 minutes per platform.
|
||||
|
||||
Everything runs offline against a demo project made by `cargo xtask demo-project`, with one exception: the first time Lutra opens a PHP project on a machine, it downloads Phpactor (about 4 MB). Do that once while you're online (step 0.4).
|
||||
|
||||
**Ticking:** each row has a `[ ]` for Windows and one for macOS. Write `x` for a pass, or the step number in your failure report for a fail.
|
||||
|
||||
**Keys:** `Mod` is Ctrl on Windows and Cmd on macOS. `Alt` is Option on macOS. Every command is also in the menu (☰ top left, or `Alt+M`) and in the palette (`Mod+Shift+P`), so if a shortcut does nothing, try the menu before you call it a failure, and note both results.
|
||||
|
||||
## 0. Before you start (about 5 min)
|
||||
|
||||
**`DEMO`** means the folder you create here: `C:\lutra-demo` on Windows, `~/lutra-demo` on macOS. On Windows, keep the path short: git fails on paths near 260 characters.
|
||||
|
||||
| # | Action | Expected | Win | Mac |
|
||||
|---|---|---|---|---|
|
||||
| 0.1 | Windows: use the installed **Lutra (Test)** (check that `%LOCALAPPDATA%\Programs\Lutra Test\version.txt` names the commit you want to test). macOS: build Lutra as [`macos.md`](macos.md) describes. | Lutra starts and shows an empty window with the otter slogan. Quit it again (`Mod+Q`). | [ ] | [ ] |
|
||||
| 0.2 | Make `lutra` callable in your shell. Windows PowerShell: `Set-Alias lutra "$env:LOCALAPPDATA\Programs\Lutra Test\lutra.exe"`. macOS: `alias lutra=<repo>/target/release/lutra` (the folder your build wrote to). | `lutra --help` prints the usage. | [ ] | [ ] |
|
||||
| 0.3 | In the repository: `cargo xtask demo-project C:\lutra-demo` (Windows) or `cargo xtask demo-project ~/lutra-demo` (macOS). | It prints `demo-project: ready` and two paths: `DEMO/shop` (the project) and `DEMO/origin.git` (its "remote"). | [ ] | [ ] |
|
||||
| 0.4 | Online: start Lutra, File › Open Folder… (`Mod+O`), choose `DEMO/shop`. | The tree shows `public`, `src`, `var` (greyed: ignored by Git), `.gitignore`, `composer.json`, `README.md`. The status bar shows `main` bottom right. The first time on this machine, toasts say the Phpactor download started and finished. | [ ] | [ ] |
|
||||
|
||||
PHP 8.2 or newer must be installed (`php -v`). Without it, steps 3.x fail with a "PHP not found" warning; that's a setup problem, not a Lutra failure.
|
||||
|
||||
## 1. Project, editor, save, recovery (about 10 min)
|
||||
|
||||
| # | Action | Expected | Win | Mac |
|
||||
|---|---|---|---|---|
|
||||
| 1.1 | Expand `src` › `Service` in the tree, click `Checkout.php`, then `PriceCalculator.php`. | Each opens in a tab with PHP highlighting; the second tab is active. Clicking the first tab switches back. | [ ] | [ ] |
|
||||
| 1.2 | `Mod+1` twice. | The project tree hides and comes back. | [ ] | [ ] |
|
||||
| 1.3 | In `README.md`, add a line `Edited by hand.` and press `Mod+S`. | A dot marks the tab as modified while you type; it disappears on save. The tab and the tree entry turn the "modified" colour, and a coloured bar appears in the narrow gutter beside the new line. | [ ] | [ ] |
|
||||
| 1.4 | Type another line in `README.md`, then press `Mod+W` at once. | A question offers Save / Don't Save / Cancel. Cancel keeps the tab; Save closes it and keeps the text. | [ ] | [ ] |
|
||||
| 1.5 | In `README.md`, add a space at the end of the new line, then click another tab. | The first tab's modified dot goes away (autosave on tab switch). | [ ] | [ ] |
|
||||
| 1.6 | Palette: `Mod+Shift+P`, type `save all`, Enter. | The palette lists "Save All" with its shortcut, runs it and closes. Arrow keys move, Escape closes. | [ ] | [ ] |
|
||||
| 1.7 | ☰ (top left) or `Alt+M`. | A menu with groups File, Edit, View, Go, Git, Navigate, Refactor, Tools, Help. Arrow keys move, Escape closes. | [ ] | [ ] |
|
||||
| 1.8 | Settings: `Mod+,`. Type `font` in the search field, set "Editor font size" to 18. | The editor text grows at once; there's no OK button. "Reset to default" sets it back to 14. | [ ] | [ ] |
|
||||
| 1.9 | Settings › Appearance › Theme: Light, then Dark, then System. | The whole window, editor and terminal switch at once, with no reload; System follows the OS setting. | [ ] | [ ] |
|
||||
| 1.10 | Settings › PHP: look at "PHP executable" and "Phpactor PHAR"; Settings › Git: "Git executable". | Each is a text field with "Browse…"; while empty it says "Detected automatically". "Browse…" opens the native file picker; Cancel there changes nothing. | [ ] | [ ] |
|
||||
| 1.11 | In "PHP executable", type a path with a space at the start, such as ` php`, and press Enter. | It is refused under the field with a message about spaces; the stored value doesn't change. Escape closes the dialog. | [ ] | [ ] |
|
||||
| 1.12 | **Crash recovery, preparation.** Settings › Editor: turn off "Autosave when leaving the window" and set "Autosave after idle (seconds)" to 0. | Both apply at once. | [ ] | [ ] |
|
||||
| 1.13 | Type `Unsaved line` into `composer.json` without saving, wait 3 seconds, then kill Lutra hard. Windows: `taskkill /F /IM lutra-desktop.exe`. macOS: `pkill -9 lutra-desktop`. (This ends every running Lutra.) | The window disappears at once, without a question. | [ ] | [ ] |
|
||||
| 1.14 | Start Lutra again and open `DEMO/shop`. | A dialog "Unsaved changes found" lists `composer.json`. "Restore All" opens it as a modified tab with `Unsaved line` in it. | [ ] | [ ] |
|
||||
| 1.15 | Remove `Unsaved line`, save. In Settings › Editor, reset both autosave settings to their defaults. | `composer.json` is no longer modified (no colour in the tree). | [ ] | [ ] |
|
||||
|
||||
## 2. Navigation (about 5 min)
|
||||
|
||||
| # | Action | Expected | Win | Mac |
|
||||
|---|---|---|---|---|
|
||||
| 2.1 | Go to File: `Mod+P`, type `pricecalc`. | `src/Service/PriceCalculator.php` is the first row, with the matched letters marked. Enter opens it. | [ ] | [ ] |
|
||||
| 2.2 | Go to Class: `Mod+Alt+C`, type `repo`. | `ProductRepository` (interface) and `InMemoryProductRepository`, with their namespace. Tab switches between the File, Class and Symbol modes and keeps the text. | [ ] | [ ] |
|
||||
| 2.3 | Go to Symbol: `Mod+T`, type `Checkout::total`, Enter. | `Checkout.php` opens with the cursor on `total`. Typing `format` instead lists the function `format_price`. | [ ] | [ ] |
|
||||
| 2.4 | Structure: with `Checkout.php` active, `Mod+2`. | A tree: `Checkout` with `__construct`, `$products`, `$calculator`, `total`, `preview`. Clicking `preview` puts the cursor on it. `Mod+2` again hides it. | [ ] | [ ] |
|
||||
| 2.5 | Find in Files: `Mod+Alt+F`, type `VAT_RATE`, Enter. | The Find tab at the bottom: 2 matches in 1 file, each with line number and the match marked. Enter or a click on a match opens the file there. | [ ] | [ ] |
|
||||
| 2.6 | Search for `ignored by`. | "No matches": the log file in the ignored `var/` folder isn't searched. | [ ] | [ ] |
|
||||
| 2.7 | Turn on Regex and search `gross\w*\(`. | Matches in `PriceCalculator.php` and `Checkout.php`. An invalid regex such as `(` shows an error under the field, not a toast. | [ ] | [ ] |
|
||||
|
||||
## 3. Code assistance (about 7 min)
|
||||
|
||||
Wait until the language server is ready: the status bar shows indexing progress for a few seconds after opening the project.
|
||||
|
||||
| # | Action | Expected | Win | Mac |
|
||||
|---|---|---|---|---|
|
||||
| 3.1 | Open `src/Service/Checkout.php`. | Within a few seconds `grossPrice` on line 51 gets a red wavy underline (the demo's deliberate error). Hovering it shows `Method "grossPrice" does not exist on class "Demo\Shop\Service\PriceCalculator"`. | [ ] | [ ] |
|
||||
| 3.2 | Problems: `Mod+Alt+P`. | The Problems tab lists that error under `Checkout.php`, with line 51. Enter or a click jumps to it. | [ ] | [ ] |
|
||||
| 3.3 | Change `grossPrice` to `gross` on line 51. | The underline and the Problems entry disappear within a few seconds. | [ ] | [ ] |
|
||||
| 3.4 | On line 42, delete the `;` after `format_price($sum)` and save. | An error is reported on that line (on Windows from `php -l`, after the save). Put the `;` back and save; it goes away. | [ ] | [ ] |
|
||||
| 3.5 | Completion: on a new line in `preview()`, type `$this->calculator->`. | A list opens with `gross` and `grossFor`, with kind icons. Enter inserts the chosen one. `Ctrl+Space` opens the list on demand. Undo the line. | [ ] | [ ] |
|
||||
| 3.6 | Hover: rest the mouse on `PriceCalculator` in the constructor. Then put the cursor on it and press `Mod+I`. | A tooltip with the class's doc comment, "Turns net prices into gross prices.", both ways. | [ ] | [ ] |
|
||||
| 3.7 | Signature help: on a new line, type `format_price(1.5, `. | A tooltip shows `format_price(float $amount, string $currency = 'EUR', int $decimals = 2)` with `$currency` marked. Escape closes it; `Mod+Shift+Space` brings it back. Undo the line. | [ ] | [ ] |
|
||||
| 3.8 | Definition: cursor on `findBySku` (line 33), `F12`. Then `Mod`+click on `PriceCalculator` in the constructor. | The first opens `ProductRepository.php` (or a picker that includes it) at `findBySku`; the second opens `PriceCalculator.php`. | [ ] | [ ] |
|
||||
| 3.9 | References: in `src/Model/Product.php`, cursor on the class name `Product`, `Shift+F12`. | A References tab lists the uses in `ProductRepository.php`, `InMemoryProductRepository.php`, `PriceCalculator.php` and `public/index.php`, each with its line. A click opens the use. | [ ] | [ ] |
|
||||
| 3.10 | Rename: in `ProductRepository.php`, cursor on `findBySku`, `F2`, type `findProduct`, Enter. | A field shows "Changes N uses in M files" before you confirm. Afterwards a toast reports the rename; the interface, `InMemoryProductRepository.php` and `Checkout.php` all say `findProduct`, and no new error appears in Problems. Keep the change (it is committed in 5.4). | [ ] | [ ] |
|
||||
|
||||
## 4. Terminal (about 3 min)
|
||||
|
||||
| # | Action | Expected | Win | Mac |
|
||||
|---|---|---|---|---|
|
||||
| 4.1 | `Mod+Shift+T`. | A Terminal tab "Local" opens at the bottom with your shell (PowerShell on Windows, your login shell on macOS) in `DEMO/shop`, focused. | [ ] | [ ] |
|
||||
| 4.2 | Run `php public/index.php`. | It prints `19.88 EUR`. | [ ] | [ ] |
|
||||
| 4.3 | Run `git log --oneline -3`. | The three newest commits, in colour. | [ ] | [ ] |
|
||||
| 4.4 | Windows: `ping -t 127.0.0.1`; macOS: `ping 127.0.0.1`. Then `Ctrl+C`. | Ping runs until `Ctrl+C` stops it (the key goes to the shell, not to Lutra). | [ ] | [ ] |
|
||||
| 4.5 | Select some output, `Mod+Shift+C`, then paste into the editor. | The selected text is pasted. | [ ] | [ ] |
|
||||
| 4.6 | The `+` button in the Terminal tab; then close "Local (2)" with its ×. | A second terminal "Local (2)" starts; closing it leaves "Local". | [ ] | [ ] |
|
||||
| 4.7 | Switch between the Find, Problems and Terminal tabs; the terminal keeps its screen. Then switch theme (1.9) once. | The terminal output is still there and takes the new colours. | [ ] | [ ] |
|
||||
|
||||
## 5. Git (about 15 min)
|
||||
|
||||
Before this section: `DEMO/shop` has the changes from 1.3, 3.3 and 3.10. The demo's `origin` holds one commit ("Start a changelog") that `shop` hasn't fetched yet; the branch `feature/discounts` conflicts with `main` in `PriceCalculator.php`.
|
||||
|
||||
| # | Action | Expected | Win | Mac |
|
||||
|---|---|---|---|---|
|
||||
| 5.1 | In the terminal: `echo note > notes.txt`. | `notes.txt` appears in the tree in the "untracked" colour. | [ ] | [ ] |
|
||||
| 5.2 | Open `README.md`, Git › Show Diff (`Mod+Alt+Shift+D`). Then Git › Next Change (`Alt+Shift+]`) and Previous Change (`Alt+Shift+[`). | A "Diff: README.md" tab shows the committed version left and your copy right, with the new lines highlighted. Next/Previous move the cursor between changed chunks, wrapping. Typing on the right edits the file. | [ ] | [ ] |
|
||||
| 5.3 | Changes: `Mod+Alt+Shift+G`. | The Changes tab: Changes with `Checkout.php`, `InMemoryProductRepository.php`, `ProductRepository.php`, `README.md`; Untracked with `notes.txt`. Double-click on a file opens its diff. | [ ] | [ ] |
|
||||
| 5.4 | Tick the checkbox of the Changes group (or select a row and press Space), leave `notes.txt` untracked. `Mod+Alt+Shift+M`, type `Rename findBySku and fix the preview`, `Mod+Enter`. | The files move to Staged, then the commit runs; a toast says "Committed <hash>: Rename findBySku…". The gutter bars and file colours go away; only `notes.txt` is left. | [ ] | [ ] |
|
||||
| 5.4b | In the Changes tab, right-click `notes.txt` › Add to .gitignore. | A toast "Added to .gitignore: notes.txt"; `notes.txt` leaves Untracked and turns the ignored colour in the tree; `.gitignore` shows as changed. | [ ] | [ ] |
|
||||
| 5.5 | Amend: tick "Amend" with an empty message box. Edit the text to `Rename findBySku to findProduct and fix the preview`, Commit. | The box fills with the last commit's message when you tick Amend. The commit is replaced (the log in 5.6 shows only the new text). | [ ] | [ ] |
|
||||
| 5.6 | Git › Log. | The Log tab draws a graph: `feature/customer` branching off and merged back, `feature/discounts` branching off, badges for `HEAD`, `main`, `origin/main`, `v0.1.0`, `origin/release/1.0`. Authors Ada Lindqvist, Ben Okafor, Cleo Marchetti, dated 2024–2026. Selecting a commit shows its message and files on the right; double-clicking a file opens its diff at that commit (read-only). | [ ] | [ ] |
|
||||
| 5.7 | Type `price` in the message filter; then clear it. | Only commits whose message contains "price" are listed (without a graph), then all again. | [ ] | [ ] |
|
||||
| 5.8 | Right-click `src/Service/PriceCalculator.php` in the tree › Show History. | The Log shows "History of src/Service/PriceCalculator.php": "Round gross prices to cents" and "Add price calculator and price formatting". The chip's × clears it. | [ ] | [ ] |
|
||||
| 5.9 | Open `PriceCalculator.php`, Git › Annotate with Git Blame. | A gutter with date and author per run of lines: Ben Okafor (2026-08-14) on the `round(...)` line, Cleo Marchetti (2025-06-02) on most others; newer lines have a stronger bar. Hovering an annotation shows the commit; a click selects it in the Log. Running the command again hides the gutter. | [ ] | [ ] |
|
||||
| 5.10 | Git › Fetch. | A toast says the fetch is done; the status bar shows `↑1 ↓1` (your commit, the changelog commit). | [ ] | [ ] |
|
||||
| 5.11 | Git › Pull. | A toast says the pull is done; `CHANGELOG.md` appears in the tree; the status bar shows `↑2` (your commit and the merge of the pull). | [ ] | [ ] |
|
||||
| 5.12 | Git › Push. | A toast says the push is done; the arrows disappear. In the terminal, `git --git-dir ../origin.git log --oneline -1` shows the pull's merge commit. | [ ] | [ ] |
|
||||
| 5.13 | Click `main` in the status bar. | The branch popup: Local `feature/customer`, `feature/discounts`, `main` (checked, "current", upstream `origin/main`); Remote `origin/main`, `origin/release/1.0`. Typing filters. | [ ] | [ ] |
|
||||
| 5.14 | Choose `origin/release/1.0`. | A toast; the status bar says `release/1.0`; `CHANGELOG.md` and `public/` vanish from the tree; open tabs of changed files reload. | [ ] | [ ] |
|
||||
| 5.15 | Git › New Branch…, name `try/scratch`, "Check out" on, Create. Then switch back to `main` with the popup. | The status bar shows `try/scratch`, then `main` again, with `CHANGELOG.md` back. | [ ] | [ ] |
|
||||
| 5.16 | Change a line in `src/Model/Product.php`, save. Git › Stash Changes…, message `wip product`, Stash. | A toast; `Product.php` is back to its committed text (an open tab reloads). | [ ] | [ ] |
|
||||
| 5.17 | Git › Stashes… | `stash@{0}` "wip product" on `main` with its date. Pop brings the change back and removes the entry. Then undo the change in `Product.php` and save. | [ ] | [ ] |
|
||||
| 5.18 | Git › Merge…, choose `feature/discounts`. | A toast reports conflicts; a list shows `src/Service/PriceCalculator.php` as conflicted; `src/Service/DiscountPolicy.php` appears in the tree. | [ ] | [ ] |
|
||||
| 5.19 | Git › Abort Merge…, confirm. | The merge is undone: `DiscountPolicy.php` is gone, no conflict colour, `main` as before. | [ ] | [ ] |
|
||||
| 5.20 | Git › Merge… `feature/discounts` again, then "Resolve…" on `PriceCalculator.php`. | Three editors: current branch (left), result (middle), merged branch (right), "1 of 1 conflicts open" (or more). | [ ] | [ ] |
|
||||
| 5.21 | "Accept all left". Then, in the middle editor, change `gross(float $net)` to `gross(float $net, float $discount = 0.0)` and `round($net *` to `round(max(0.0, $net - $discount) *`. "Apply and mark resolved". | Apply is enabled once no chunk is open; afterwards the file is saved and the list says no conflicts are left, offering "Commit…". | [ ] | [ ] |
|
||||
| 5.22 | "Commit…". Keep the prefilled message, Commit. Then `php public/index.php` in the terminal. | The message box already holds `Merge branch 'feature/discounts'` (git's prepared message). The commit succeeds; the Log shows the merge with two parents; the script still prints `19.88 EUR`. | [ ] | [ ] |
|
||||
| 5.23 | Git › Manage Remotes… Add a remote `backup` with the URL of `DEMO/origin.git`; then Remove it (confirm in the row). | `origin` is listed with its URL; `backup` appears and disappears again. | [ ] | [ ] |
|
||||
| 5.24 | Git › Clone Repository…, URL `DEMO/origin.git` (the full path), "Browse…" and choose `DEMO`. | The folder field becomes `DEMO/origin`. Clone shows progress, then the clone opens as the project (tree with `src`, `public`, `CHANGELOG.md`; branch `main`). | [ ] | [ ] |
|
||||
| 5.25 | File › Open Folder… `DEMO/shop`. | The demo project is back, with the Git state from 5.22. | [ ] | [ ] |
|
||||
|
||||
## 6. CLI, control channel, MCP (about 5 min)
|
||||
|
||||
Lutra runs normally (started from its icon or the start menu), with `DEMO/shop` open.
|
||||
|
||||
| # | Action | Expected | Win | Mac |
|
||||
|---|---|---|---|---|
|
||||
| 6.1 | In a terminal outside Lutra: `lutra C:\lutra-demo\shop\src\Service\Checkout.php:30` (macOS: `lutra ~/lutra-demo/shop/src/Service/Checkout.php:30`). | Lutra comes to the front with `Checkout.php` open and the cursor on line 30, centred. The command exits at once. | [ ] | [ ] |
|
||||
| 6.2 | `lutra --wait DEMO/shop/README.md` (the real path, as in 6.1). | The command waits. Close the `README.md` tab in Lutra (`Mod+W`); the command returns. Exit code 0 (`$LASTEXITCODE` in PowerShell, `echo $?` on macOS). | [ ] | [ ] |
|
||||
| 6.3 | `lutra DEMO/origin.git/HEAD` (a file outside the project). | Refused with "… is outside the project", exit code 1. | [ ] | [ ] |
|
||||
| 6.4 | Quit Lutra. `lutra DEMO/shop`. | Lutra starts by itself with the demo project. | [ ] | [ ] |
|
||||
| 6.5 | **MCP.** With Lutra still running, run the block below for your platform in a terminal outside Lutra. | Two JSON lines come back: the first with `"serverInfo"`, the second with `"isError":false`. In Lutra the Go to File popup opens with `checkout` typed. | [ ] | [ ] |
|
||||
| 6.6 | **Control channel.** Quit Lutra. Start it with a control port: Windows `& "$env:LOCALAPPDATA\Programs\Lutra Test\lutra-desktop.exe" --control 7979 C:\lutra-demo\shop`; macOS `<repo>/target/release/lutra-desktop --control 7979 ~/lutra-demo/shop`. Then send a request with the block below. | A line `{"id":1,"result":{"pong":true,...}}`, then the palette opens in Lutra. Quit this instance afterwards: it uses its own data folder, so it doesn't show your normal settings. | [ ] | [ ] |
|
||||
| 6.7 | Optional, if Claude Code is installed: `claude mcp add lutra -- lutra mcp`, then ask Claude "which files are open in Lutra?". | Claude lists the open tabs through Lutra's MCP tools. | [ ] | [ ] |
|
||||
|
||||
MCP check (6.5), Windows PowerShell:
|
||||
|
||||
```powershell
|
||||
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"checklist","version":"1"}}}',
|
||||
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"execute_command","arguments":{"command":"goto.fileOpen","params":{"query":"checkout"}}}}' | lutra mcp
|
||||
```
|
||||
|
||||
macOS:
|
||||
|
||||
```sh
|
||||
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"checklist","version":"1"}}}' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"execute_command","arguments":{"command":"goto.fileOpen","params":{"query":"checkout"}}}}' | lutra mcp
|
||||
```
|
||||
|
||||
Control channel (6.6), Windows PowerShell:
|
||||
|
||||
```powershell
|
||||
$c = New-Object System.Net.Sockets.TcpClient('127.0.0.1', 7979)
|
||||
$w = New-Object System.IO.StreamWriter($c.GetStream()); $r = New-Object System.IO.StreamReader($c.GetStream())
|
||||
$w.WriteLine('{"id":1,"method":"app.ping","params":{}}'); $w.Flush(); $r.ReadLine()
|
||||
$w.WriteLine('{"id":2,"method":"engine.execute","params":{"command":"palette.open"}}'); $w.Flush(); $r.ReadLine()
|
||||
$c.Close()
|
||||
```
|
||||
|
||||
macOS:
|
||||
|
||||
```sh
|
||||
printf '%s\n' '{"id":1,"method":"app.ping","params":{}}' '{"id":2,"method":"engine.execute","params":{"command":"palette.open"}}' | nc -w 2 127.0.0.1 7979
|
||||
```
|
||||
|
||||
## Reporting a failure
|
||||
|
||||
Don't fix or retry around it; write it down and carry on with the next step that doesn't depend on it. One note per failure, in the PM chat (Larissa), like this:
|
||||
|
||||
```
|
||||
Step 5.11 · macOS 15.1 (M2) · build <commit from version.txt or `git rev-parse --short HEAD`>
|
||||
Did: Git › Pull
|
||||
Expected: toast, CHANGELOG.md in the tree, ↑2
|
||||
Got: error toast "…" (exact text), no CHANGELOG.md
|
||||
Repeatable: yes / once / not tried
|
||||
Attached: screenshot
|
||||
```
|
||||
|
||||
Useful extras when you have them:
|
||||
|
||||
- a screenshot of the whole window;
|
||||
- for language-server steps (3.x): whether Tools › Restart PHP Language Server makes it work;
|
||||
- for Git steps: `git status` and `git log --oneline --graph -5` from the terminal;
|
||||
- a crash: the terminal output if you started Lutra from a terminal.
|
||||
|
||||
When everything is ticked on both platforms, say so in the chat with the build commit; the PM records the alpha gate.
|
||||
|
||||
## Revision history
|
||||
|
||||
| Date | Change | Summary |
|
||||
|---|---|---|
|
||||
| 2026-10-31 | new | A2: the six alpha workflows as manual steps, the demo project (`cargo xtask demo-project`), failure reports |
|
||||
|
|
@ -21,7 +21,7 @@ crates/syntax (L1) tree-sitter parsing (PHP first), outlines, highlight t
|
|||
crates/text (L0) rope buffer, positions, UTF-8/UTF-16 conversion, edits
|
||||
crates/proc (L0) child processes that die with Lutra (job objects, process groups)
|
||||
crates/testkit (—) test helpers and fixtures, tests only
|
||||
xtask (—) ci, layers, assets, cleanroom, dev, fixtures, lints-selftest, ui-licences
|
||||
xtask (—) ci, layers, assets, cleanroom, dev, fixtures, demo-project, lints-selftest, ui-licences
|
||||
```
|
||||
|
||||
Each crate declares its layer in its manifest:
|
||||
|
|
|
|||
|
|
@ -18,6 +18,7 @@ cargo xtask dev -- --control 7979 . # with the JSON control channel
|
|||
cargo xtask ci # the full quality gate, run before every commit
|
||||
cargo xtask fixtures # create Symfony and Laravel reference projects in target/fixtures/
|
||||
cargo xtask mac-report # gate, build and an app self-check, written to target/mac-report/report.md
|
||||
cargo xtask demo-project ../lutra-demo # offline demo project for docs/alpha-checklist.md
|
||||
```
|
||||
|
||||
`mac-report` is made for checking a machine the developers cannot reach (the Mac, see [`macos.md`](macos.md)) but runs everywhere. Every step has a timeout; `--skip-gate` leaves out the gate, `--port` picks the control port (default 7971).
|
||||
|
|
@ -60,6 +61,7 @@ No inline comments. Doc comment blocks above modules, functions, types and field
|
|||
|
||||
| Date | Change | Summary |
|
||||
|---|---|---|
|
||||
| 2026-10-31 | minor | A2: `cargo xtask demo-project` |
|
||||
| 2026-10-31 | minor | A1: `cargo xtask mac-report`, link to the macOS setup |
|
||||
| 2026-10-27 | minor | F3: data directories, build directories inside the repository, parallel builds, deleting `ui/node_modules` |
|
||||
| 2026-10-27 | minor | Unfocused `--control` windows and the screenshot focus check (F2) |
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[package]
|
||||
name = "xtask"
|
||||
description = "Project automation: ci, layers, assets, cleanroom, dev, fixtures, mac-report"
|
||||
description = "Project automation: ci, layers, assets, cleanroom, dev, fixtures, demo-project, mac-report"
|
||||
version.workspace = true
|
||||
edition.workspace = true
|
||||
rust-version.workspace = true
|
||||
|
|
|
|||
875
xtask/src/demo.rs
Normal file
875
xtask/src/demo.rs
Normal file
|
|
@ -0,0 +1,875 @@
|
|||
//! `cargo xtask demo-project <dir>`: an offline demo for the alpha checklist
|
||||
//! (`docs/alpha-checklist.md`).
|
||||
//!
|
||||
//! It creates, inside `<dir>`:
|
||||
//! - `shop/`, a small PHP project (classes, an interface, a function, one
|
||||
//! deliberate error for diagnostics) with a Git history by three authors
|
||||
//! over three years, a merged branch, a tag, and the branch
|
||||
//! `feature/discounts`, which conflicts with `main` in
|
||||
//! `src/Service/PriceCalculator.php`;
|
||||
//! - `origin.git/`, a bare repository that is `shop`'s `origin`. It holds the
|
||||
//! branch `release/1.0` (only remote in `shop`) and one commit on `main`
|
||||
//! that `shop` does not know yet, so a fetch shows one incoming commit.
|
||||
//!
|
||||
//! Nothing touches the network or the user's Git configuration; the
|
||||
//! repository sets its own committer identity and turns commit signing off.
|
||||
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::process::Command;
|
||||
|
||||
use crate::util::TaskResult;
|
||||
|
||||
/// A person in the demo history: name, e-mail address.
|
||||
type Author = (&'static str, &'static str);
|
||||
|
||||
/// Author of the skeleton, the customer branch and the entry point.
|
||||
const ADA: Author = ("Ada Lindqvist", "ada@example.com");
|
||||
/// Author of the repository and the rounding change.
|
||||
const BEN: Author = ("Ben Okafor", "ben@example.com");
|
||||
/// Author of the price calculator, the discounts branch and the remote commit.
|
||||
const CLEO: Author = ("Cleo Marchetti", "cleo@example.com");
|
||||
|
||||
/// The identity the demo repository commits with, so the checklist's commits
|
||||
/// work on a machine without a global Git identity.
|
||||
const TESTER: Author = ("Lutra Tester", "tester@example.com");
|
||||
|
||||
/// Variables that would point git at another repository.
|
||||
const GIT_REDIRECTS: &[&str] = &[
|
||||
"GIT_DIR",
|
||||
"GIT_WORK_TREE",
|
||||
"GIT_INDEX_FILE",
|
||||
"GIT_OBJECT_DIRECTORY",
|
||||
"GIT_ALTERNATE_OBJECT_DIRECTORIES",
|
||||
"GIT_COMMON_DIR",
|
||||
"GIT_NAMESPACE",
|
||||
];
|
||||
|
||||
/// Folder length (bytes) above which a failure on Windows gets a hint about
|
||||
/// short paths: a push into the bare repository writes through a quarantine
|
||||
/// folder whose object paths pass 260 characters from about 150 on.
|
||||
const LONG_PATH_HINT: usize = 100;
|
||||
|
||||
/// Paths of the generated demo.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Demo {
|
||||
/// The PHP project and its work tree.
|
||||
pub shop: PathBuf,
|
||||
/// The bare repository configured as `origin`.
|
||||
pub origin: PathBuf,
|
||||
}
|
||||
|
||||
/// Runs `cargo xtask demo-project <dir>`.
|
||||
///
|
||||
/// # Errors
|
||||
/// Fails without a directory argument, when the directory exists and is not
|
||||
/// empty, when git is missing, or when a git call fails.
|
||||
pub fn run(args: &[String]) -> TaskResult {
|
||||
let Some(dir) = args.first() else {
|
||||
return Err("usage: cargo xtask demo-project <dir>".into());
|
||||
};
|
||||
let dir = std::path::absolute(dir).map_err(|e| format!("cannot resolve `{dir}`: {e}"))?;
|
||||
let demo = create(&dir).map_err(|e| {
|
||||
if cfg!(windows) && dir.as_os_str().len() > LONG_PATH_HINT {
|
||||
format!(
|
||||
"{e}\n(git on Windows fails on paths near 260 characters; use a short folder such as C:\\lutra-demo)"
|
||||
)
|
||||
} else {
|
||||
e
|
||||
}
|
||||
})?;
|
||||
println!("demo-project: ready");
|
||||
println!(" project: {}", demo.shop.display());
|
||||
println!(" origin: {}", demo.origin.display());
|
||||
println!("open the project in Lutra and follow docs/alpha-checklist.md");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Creates the demo in `dir`, which must be missing or empty.
|
||||
///
|
||||
/// # Errors
|
||||
/// Fails when `dir` is not empty, a file cannot be written, git is missing or
|
||||
/// a git call fails.
|
||||
pub fn create(dir: &Path) -> TaskResult<Demo> {
|
||||
if dir.exists() {
|
||||
let mut entries = std::fs::read_dir(dir).map_err(|e| format!("{}: {e}", dir.display()))?;
|
||||
if entries.next().is_some() {
|
||||
return Err(format!(
|
||||
"{} is not empty; pass a new or empty folder",
|
||||
dir.display()
|
||||
));
|
||||
}
|
||||
}
|
||||
Command::new("git")
|
||||
.arg("--version")
|
||||
.output()
|
||||
.map_err(|e| format!("git is not on the PATH: {e}"))?;
|
||||
let shop = dir.join("shop");
|
||||
let origin = dir.join("origin.git");
|
||||
std::fs::create_dir_all(&shop).map_err(|e| format!("{}: {e}", shop.display()))?;
|
||||
|
||||
git(&shop, &["init", "-q", "-b", "main"], None)?;
|
||||
for (key, value) in [
|
||||
("user.name", TESTER.0),
|
||||
("user.email", TESTER.1),
|
||||
("commit.gpgsign", "false"),
|
||||
("tag.gpgsign", "false"),
|
||||
] {
|
||||
git(&shop, &["config", key, value], None)?;
|
||||
}
|
||||
|
||||
write_files(
|
||||
&shop,
|
||||
&[
|
||||
("composer.json", COMPOSER_JSON),
|
||||
(".gitignore", GITIGNORE),
|
||||
("README.md", README_V1),
|
||||
("src/Model/Product.php", PRODUCT),
|
||||
],
|
||||
)?;
|
||||
commit(
|
||||
&shop,
|
||||
"Initial project skeleton",
|
||||
ADA,
|
||||
Some("2024-03-12T09:14:00+01:00"),
|
||||
)?;
|
||||
write_files(
|
||||
&shop,
|
||||
&[
|
||||
("src/Repository/ProductRepository.php", PRODUCT_REPOSITORY),
|
||||
(
|
||||
"src/Repository/InMemoryProductRepository.php",
|
||||
IN_MEMORY_REPOSITORY,
|
||||
),
|
||||
],
|
||||
)?;
|
||||
commit(
|
||||
&shop,
|
||||
"Add product repository",
|
||||
BEN,
|
||||
Some("2024-09-30T16:40:00+02:00"),
|
||||
)?;
|
||||
write_files(
|
||||
&shop,
|
||||
&[
|
||||
("src/Service/PriceCalculator.php", PRICE_CALCULATOR_BASE),
|
||||
("src/functions.php", FUNCTIONS),
|
||||
],
|
||||
)?;
|
||||
commit(
|
||||
&shop,
|
||||
"Add price calculator and price formatting",
|
||||
CLEO,
|
||||
Some("2025-06-02T11:05:00+02:00"),
|
||||
)?;
|
||||
|
||||
git(&shop, &["switch", "-q", "-c", "feature/customer"], None)?;
|
||||
write_files(&shop, &[("src/Model/Customer.php", CUSTOMER)])?;
|
||||
commit(
|
||||
&shop,
|
||||
"Add customer model",
|
||||
ADA,
|
||||
Some("2025-10-01T10:00:00+02:00"),
|
||||
)?;
|
||||
write_files(&shop, &[("src/Service/Checkout.php", CHECKOUT)])?;
|
||||
commit(
|
||||
&shop,
|
||||
"Add checkout service",
|
||||
ADA,
|
||||
Some("2025-10-02T14:30:00+02:00"),
|
||||
)?;
|
||||
git(&shop, &["switch", "-q", "main"], None)?;
|
||||
write_files(&shop, &[("README.md", README_V2)])?;
|
||||
commit(
|
||||
&shop,
|
||||
"Document the project layout",
|
||||
BEN,
|
||||
Some("2025-10-05T08:45:00+02:00"),
|
||||
)?;
|
||||
git(
|
||||
&shop,
|
||||
&[
|
||||
"merge",
|
||||
"-q",
|
||||
"--no-ff",
|
||||
"-m",
|
||||
"Merge branch 'feature/customer'",
|
||||
"feature/customer",
|
||||
],
|
||||
Some((ADA, Some("2025-11-20T17:20:00+01:00"))),
|
||||
)?;
|
||||
git(&shop, &["tag", "v0.1.0"], None)?;
|
||||
git(&shop, &["branch", "release/1.0"], None)?;
|
||||
|
||||
git(&shop, &["switch", "-q", "-c", "feature/discounts"], None)?;
|
||||
write_files(
|
||||
&shop,
|
||||
&[("src/Service/DiscountPolicy.php", DISCOUNT_POLICY)],
|
||||
)?;
|
||||
commit(
|
||||
&shop,
|
||||
"Add discount policy",
|
||||
CLEO,
|
||||
Some("2026-09-03T09:30:00+02:00"),
|
||||
)?;
|
||||
write_files(
|
||||
&shop,
|
||||
&[(
|
||||
"src/Service/PriceCalculator.php",
|
||||
PRICE_CALCULATOR_DISCOUNTS,
|
||||
)],
|
||||
)?;
|
||||
commit(
|
||||
&shop,
|
||||
"Support discounts in gross prices",
|
||||
CLEO,
|
||||
Some("2026-09-05T15:10:00+02:00"),
|
||||
)?;
|
||||
|
||||
git(&shop, &["switch", "-q", "main"], None)?;
|
||||
write_files(
|
||||
&shop,
|
||||
&[("src/Service/PriceCalculator.php", PRICE_CALCULATOR_ROUNDED)],
|
||||
)?;
|
||||
commit(
|
||||
&shop,
|
||||
"Round gross prices to cents",
|
||||
BEN,
|
||||
Some("2026-08-14T13:00:00+02:00"),
|
||||
)?;
|
||||
write_files(&shop, &[("public/index.php", INDEX)])?;
|
||||
commit(&shop, "Add a command-line entry point", ADA, None)?;
|
||||
|
||||
let origin_url = origin.to_string_lossy().replace('\\', "/");
|
||||
git(
|
||||
dir,
|
||||
&["init", "-q", "--bare", "-b", "main", "origin.git"],
|
||||
None,
|
||||
)?;
|
||||
git(&shop, &["remote", "add", "origin", &origin_url], None)?;
|
||||
git(&shop, &["push", "-q", "-u", "origin", "main"], None)?;
|
||||
git(
|
||||
&shop,
|
||||
&["push", "-q", "origin", "v0.1.0", "release/1.0"],
|
||||
None,
|
||||
)?;
|
||||
git(&shop, &["branch", "-q", "-D", "release/1.0"], None)?;
|
||||
|
||||
git(&shop, &["switch", "-q", "-c", "teammate"], None)?;
|
||||
write_files(&shop, &[("CHANGELOG.md", CHANGELOG)])?;
|
||||
commit(&shop, "Start a changelog", CLEO, None)?;
|
||||
git(&shop, &["push", "-q", "origin", "teammate:main"], None)?;
|
||||
git(&shop, &["switch", "-q", "main"], None)?;
|
||||
git(&shop, &["branch", "-q", "-D", "teammate"], None)?;
|
||||
git(
|
||||
&shop,
|
||||
&["update-ref", "refs/remotes/origin/main", "refs/heads/main"],
|
||||
None,
|
||||
)?;
|
||||
|
||||
write_files(&shop, &[("var/log/app.log", APP_LOG)])?;
|
||||
Ok(Demo { shop, origin })
|
||||
}
|
||||
|
||||
/// Writes `files` (relative path, contents) below `root`, creating folders.
|
||||
///
|
||||
/// # Errors
|
||||
/// Fails when a folder or file cannot be written.
|
||||
fn write_files(root: &Path, files: &[(&str, &str)]) -> TaskResult {
|
||||
for (rel, text) in files {
|
||||
let path = root.join(rel);
|
||||
if let Some(parent) = path.parent() {
|
||||
std::fs::create_dir_all(parent).map_err(|e| format!("{}: {e}", parent.display()))?;
|
||||
}
|
||||
std::fs::write(&path, text).map_err(|e| format!("{}: {e}", path.display()))?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Stages everything and commits it as `author` at `date` (ISO 8601; `None`
|
||||
/// is now). The committer is the author, so log and blame show one person.
|
||||
///
|
||||
/// # Errors
|
||||
/// Fails when git fails.
|
||||
fn commit(repo: &Path, message: &str, author: Author, date: Option<&str>) -> TaskResult {
|
||||
git(repo, &["add", "-A"], None)?;
|
||||
git(
|
||||
repo,
|
||||
&["commit", "-q", "--no-verify", "-m", message],
|
||||
Some((author, date)),
|
||||
)
|
||||
.map(|_| ())
|
||||
}
|
||||
|
||||
/// Runs git in `dir` with the redirecting variables removed and, with `who`,
|
||||
/// the author and committer set to that person and date.
|
||||
///
|
||||
/// # Errors
|
||||
/// Fails when git cannot start or exits unsuccessfully; the message holds
|
||||
/// git's error output.
|
||||
fn git(dir: &Path, args: &[&str], who: Option<(Author, Option<&str>)>) -> TaskResult<String> {
|
||||
let mut command = Command::new("git");
|
||||
command
|
||||
.args(["-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false"])
|
||||
.args(args)
|
||||
.current_dir(dir);
|
||||
for name in GIT_REDIRECTS {
|
||||
command.env_remove(name);
|
||||
}
|
||||
if let Some(((name, email), date)) = who {
|
||||
command
|
||||
.env("GIT_AUTHOR_NAME", name)
|
||||
.env("GIT_AUTHOR_EMAIL", email)
|
||||
.env("GIT_COMMITTER_NAME", name)
|
||||
.env("GIT_COMMITTER_EMAIL", email);
|
||||
if let Some(date) = date {
|
||||
command
|
||||
.env("GIT_AUTHOR_DATE", date)
|
||||
.env("GIT_COMMITTER_DATE", date);
|
||||
}
|
||||
}
|
||||
let output = command
|
||||
.output()
|
||||
.map_err(|e| format!("cannot start git: {e}"))?;
|
||||
if !output.status.success() {
|
||||
return Err(format!(
|
||||
"`git {}` failed in {}: {}",
|
||||
args.join(" "),
|
||||
dir.display(),
|
||||
String::from_utf8_lossy(&output.stderr).trim()
|
||||
));
|
||||
}
|
||||
Ok(String::from_utf8_lossy(&output.stdout).into_owned())
|
||||
}
|
||||
|
||||
/// `composer.json` with a PSR-4 autoload, so the language server finds the
|
||||
/// classes by namespace.
|
||||
const COMPOSER_JSON: &str = r#"{
|
||||
"name": "lutra/demo-shop",
|
||||
"description": "A small shop for the Lutra alpha checklist",
|
||||
"type": "project",
|
||||
"license": "MIT",
|
||||
"require": {
|
||||
"php": ">=8.2"
|
||||
},
|
||||
"autoload": {
|
||||
"psr-4": {
|
||||
"Demo\\Shop\\": "src/"
|
||||
},
|
||||
"files": [
|
||||
"src/functions.php"
|
||||
]
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
/// Ignores `var/` (the log file shows the ignored colour) and `vendor/`.
|
||||
const GITIGNORE: &str = "/var/\n/vendor/\n";
|
||||
|
||||
/// The first README.
|
||||
const README_V1: &str = "# Demo shop\n\nA small PHP project for trying Lutra.\n";
|
||||
|
||||
/// The README after "Document the project layout".
|
||||
const README_V2: &str = "# Demo shop
|
||||
|
||||
A small PHP project for trying Lutra.
|
||||
|
||||
## Layout
|
||||
|
||||
- `src/Model`: products and customers
|
||||
- `src/Repository`: where products come from
|
||||
- `src/Service`: prices and the checkout
|
||||
- `public/index.php`: run it with `php public/index.php`
|
||||
";
|
||||
|
||||
/// The commit on `origin/main` that the local `main` does not have yet.
|
||||
const CHANGELOG: &str = "# Changelog
|
||||
|
||||
## Unreleased
|
||||
|
||||
- Prices are rounded to cents.
|
||||
- `php public/index.php` prints a sample total.
|
||||
";
|
||||
|
||||
/// An ignored file.
|
||||
const APP_LOG: &str = "[2026-10-30 09:00:00] demo.INFO: ignored by .gitignore\n";
|
||||
|
||||
/// The product model.
|
||||
const PRODUCT: &str = r#"<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Demo\Shop\Model;
|
||||
|
||||
/**
|
||||
* A product in the catalogue, priced net of VAT.
|
||||
*/
|
||||
final class Product
|
||||
{
|
||||
public function __construct(
|
||||
public readonly string $sku,
|
||||
public readonly string $name,
|
||||
public readonly float $netPrice,
|
||||
) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a copy of the product with another net price.
|
||||
*/
|
||||
public function withNetPrice(float $netPrice): self
|
||||
{
|
||||
return new self($this->sku, $this->name, $netPrice);
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
/// The customer model.
|
||||
const CUSTOMER: &str = r#"<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Demo\Shop\Model;
|
||||
|
||||
/**
|
||||
* A customer; business customers pay net prices.
|
||||
*/
|
||||
final class Customer
|
||||
{
|
||||
public function __construct(
|
||||
public readonly string $email,
|
||||
public readonly string $name,
|
||||
public readonly bool $isBusiness = false,
|
||||
) {
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
/// The repository interface.
|
||||
const PRODUCT_REPOSITORY: &str = r#"<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Demo\Shop\Repository;
|
||||
|
||||
use Demo\Shop\Model\Product;
|
||||
|
||||
/**
|
||||
* Where products come from.
|
||||
*/
|
||||
interface ProductRepository
|
||||
{
|
||||
/**
|
||||
* Finds a product by its SKU, or null when there is none.
|
||||
*/
|
||||
public function findBySku(string $sku): ?Product;
|
||||
|
||||
/**
|
||||
* Returns every product.
|
||||
*
|
||||
* @return list<Product>
|
||||
*/
|
||||
public function all(): array;
|
||||
|
||||
/**
|
||||
* Adds a product or replaces the one with the same SKU.
|
||||
*/
|
||||
public function save(Product $product): void;
|
||||
}
|
||||
"#;
|
||||
|
||||
/// The in-memory implementation of the repository.
|
||||
const IN_MEMORY_REPOSITORY: &str = r#"<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Demo\Shop\Repository;
|
||||
|
||||
use Demo\Shop\Model\Product;
|
||||
|
||||
/**
|
||||
* Keeps products in an array, by SKU.
|
||||
*/
|
||||
final class InMemoryProductRepository implements ProductRepository
|
||||
{
|
||||
/** @var array<string, Product> */
|
||||
private array $items = [];
|
||||
|
||||
/**
|
||||
* @param list<Product> $products
|
||||
*/
|
||||
public function __construct(array $products = [])
|
||||
{
|
||||
foreach ($products as $product) {
|
||||
$this->save($product);
|
||||
}
|
||||
}
|
||||
|
||||
public function findBySku(string $sku): ?Product
|
||||
{
|
||||
return $this->items[$sku] ?? null;
|
||||
}
|
||||
|
||||
public function all(): array
|
||||
{
|
||||
return array_values($this->items);
|
||||
}
|
||||
|
||||
public function save(Product $product): void
|
||||
{
|
||||
$this->items[$product->sku] = $product;
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
/// The price calculator as first committed (the merge base of the conflict).
|
||||
const PRICE_CALCULATOR_BASE: &str = r#"<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Demo\Shop\Service;
|
||||
|
||||
use Demo\Shop\Model\Product;
|
||||
|
||||
/**
|
||||
* Turns net prices into gross prices.
|
||||
*/
|
||||
final class PriceCalculator
|
||||
{
|
||||
private const VAT_RATE = 0.19;
|
||||
|
||||
/**
|
||||
* Returns the gross price for a net price.
|
||||
*
|
||||
* @param float $net the net price in euros
|
||||
*/
|
||||
public function gross(float $net): float
|
||||
{
|
||||
return $net * (1 + self::VAT_RATE);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the gross price of a product.
|
||||
*/
|
||||
public function grossFor(Product $product): float
|
||||
{
|
||||
return $this->gross($product->netPrice);
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
/// The price calculator on `main`: rounds to cents.
|
||||
const PRICE_CALCULATOR_ROUNDED: &str = r#"<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Demo\Shop\Service;
|
||||
|
||||
use Demo\Shop\Model\Product;
|
||||
|
||||
/**
|
||||
* Turns net prices into gross prices.
|
||||
*/
|
||||
final class PriceCalculator
|
||||
{
|
||||
private const VAT_RATE = 0.19;
|
||||
|
||||
/**
|
||||
* Returns the gross price for a net price, rounded to cents.
|
||||
*
|
||||
* @param float $net the net price in euros
|
||||
*/
|
||||
public function gross(float $net): float
|
||||
{
|
||||
return round($net * (1 + self::VAT_RATE), 2);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the gross price of a product.
|
||||
*/
|
||||
public function grossFor(Product $product): float
|
||||
{
|
||||
return $this->gross($product->netPrice);
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
/// The price calculator on `feature/discounts`: takes a discount. Changes the
|
||||
/// same lines as `main`, so merging the branch conflicts.
|
||||
const PRICE_CALCULATOR_DISCOUNTS: &str = r#"<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Demo\Shop\Service;
|
||||
|
||||
use Demo\Shop\Model\Product;
|
||||
|
||||
/**
|
||||
* Turns net prices into gross prices.
|
||||
*/
|
||||
final class PriceCalculator
|
||||
{
|
||||
private const VAT_RATE = 0.19;
|
||||
|
||||
/**
|
||||
* Returns the gross price for a net price after a discount.
|
||||
*
|
||||
* @param float $net the net price in euros
|
||||
* @param float $discount the net discount in euros
|
||||
*/
|
||||
public function gross(float $net, float $discount = 0.0): float
|
||||
{
|
||||
return max(0.0, $net - $discount) * (1 + self::VAT_RATE);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the gross price of a product.
|
||||
*/
|
||||
public function grossFor(Product $product): float
|
||||
{
|
||||
return $this->gross($product->netPrice);
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
/// The discount policy, only on `feature/discounts`.
|
||||
const DISCOUNT_POLICY: &str = r#"<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Demo\Shop\Service;
|
||||
|
||||
use Demo\Shop\Model\Customer;
|
||||
|
||||
/**
|
||||
* Business customers get five percent off.
|
||||
*/
|
||||
final class DiscountPolicy
|
||||
{
|
||||
public function discountFor(Customer $customer, float $net): float
|
||||
{
|
||||
return $customer->isBusiness ? $net * 0.05 : 0.0;
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
/// The price formatting function, for signature help.
|
||||
const FUNCTIONS: &str = r#"<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Demo\Shop;
|
||||
|
||||
/**
|
||||
* Formats an amount of money for display, such as "12.50 EUR".
|
||||
*
|
||||
* @param float $amount the amount
|
||||
* @param string $currency the ISO 4217 currency code
|
||||
* @param int $decimals the number of decimals
|
||||
*/
|
||||
function format_price(float $amount, string $currency = 'EUR', int $decimals = 2): string
|
||||
{
|
||||
return number_format($amount, $decimals, '.', '') . ' ' . $currency;
|
||||
}
|
||||
"#;
|
||||
|
||||
/// The checkout service, with the deliberate error in `preview()`.
|
||||
const CHECKOUT: &str = r#"<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Demo\Shop\Service;
|
||||
|
||||
use Demo\Shop\Model\Customer;
|
||||
use Demo\Shop\Repository\ProductRepository;
|
||||
|
||||
use function Demo\Shop\format_price;
|
||||
|
||||
/**
|
||||
* Adds up a customer's basket.
|
||||
*/
|
||||
final class Checkout
|
||||
{
|
||||
public function __construct(
|
||||
private readonly ProductRepository $products,
|
||||
private readonly PriceCalculator $calculator,
|
||||
) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the formatted total for the given SKUs; unknown SKUs are
|
||||
* skipped.
|
||||
*
|
||||
* @param list<string> $skus
|
||||
*/
|
||||
public function total(Customer $customer, array $skus): string
|
||||
{
|
||||
$sum = 0.0;
|
||||
foreach ($skus as $sku) {
|
||||
$product = $this->products->findBySku($sku);
|
||||
if ($product === null) {
|
||||
continue;
|
||||
}
|
||||
$sum += $customer->isBusiness
|
||||
? $product->netPrice
|
||||
: $this->calculator->grossFor($product);
|
||||
}
|
||||
|
||||
return format_price($sum);
|
||||
}
|
||||
|
||||
/**
|
||||
* Deliberate error for the alpha checklist: PriceCalculator has no
|
||||
* method grossPrice(), so the language server reports it.
|
||||
*/
|
||||
public function preview(float $net): string
|
||||
{
|
||||
return format_price($this->calculator->grossPrice($net));
|
||||
}
|
||||
}
|
||||
"#;
|
||||
|
||||
/// The entry point for the terminal step; prints `19.88 EUR`.
|
||||
const INDEX: &str = r#"<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
use Demo\Shop\Model\Customer;
|
||||
use Demo\Shop\Model\Product;
|
||||
use Demo\Shop\Repository\InMemoryProductRepository;
|
||||
use Demo\Shop\Service\Checkout;
|
||||
use Demo\Shop\Service\PriceCalculator;
|
||||
|
||||
spl_autoload_register(static function (string $class): void {
|
||||
$prefix = 'Demo\\Shop\\';
|
||||
if (str_starts_with($class, $prefix)) {
|
||||
require __DIR__ . '/../src/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';
|
||||
}
|
||||
});
|
||||
require __DIR__ . '/../src/functions.php';
|
||||
|
||||
$products = new InMemoryProductRepository([
|
||||
new Product('TEA-01', 'Green tea', 4.20),
|
||||
new Product('MUG-02', 'Otter mug', 12.50),
|
||||
]);
|
||||
$checkout = new Checkout($products, new PriceCalculator());
|
||||
|
||||
echo $checkout->total(new Customer('ada@example.com', 'Ada'), ['TEA-01', 'MUG-02']), PHP_EOL;
|
||||
"#;
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
/// A fresh, unique folder under the system temp directory.
|
||||
fn temp_dir(name: &str) -> PathBuf {
|
||||
let nanos = std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.map(|d| d.as_nanos())
|
||||
.unwrap_or(0);
|
||||
std::env::temp_dir().join(format!("lutra-demo-{name}-{}-{nanos}", std::process::id()))
|
||||
}
|
||||
|
||||
/// Whether git can be started; the test skips without it.
|
||||
fn has_git() -> bool {
|
||||
Command::new("git").arg("--version").output().is_ok()
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn creates_history_branches_remote_and_a_conflict() {
|
||||
if !has_git() {
|
||||
eprintln!("skipped: git is not installed");
|
||||
return;
|
||||
}
|
||||
let dir = temp_dir("full");
|
||||
let demo = create(&dir).unwrap();
|
||||
let shop = &demo.shop;
|
||||
|
||||
assert!(shop.join("src/Service/Checkout.php").is_file());
|
||||
assert!(demo.origin.join("HEAD").is_file());
|
||||
assert_eq!(git(shop, &["status", "--porcelain"], None).unwrap(), "");
|
||||
assert_eq!(
|
||||
git(shop, &["branch", "--show-current"], None)
|
||||
.unwrap()
|
||||
.trim(),
|
||||
"main"
|
||||
);
|
||||
|
||||
let mut authors: Vec<String> = git(shop, &["log", "--all", "--format=%an"], None)
|
||||
.unwrap()
|
||||
.lines()
|
||||
.map(str::to_string)
|
||||
.collect();
|
||||
authors.sort();
|
||||
authors.dedup();
|
||||
assert_eq!(authors, ["Ada Lindqvist", "Ben Okafor", "Cleo Marchetti"]);
|
||||
let years = git(shop, &["log", "--format=%ad", "--date=format:%Y"], None).unwrap();
|
||||
assert!(years.contains("2024") && years.contains("2025") && years.contains("2026"));
|
||||
|
||||
let refs = git(shop, &["for-each-ref", "--format=%(refname:short)"], None).unwrap();
|
||||
for name in [
|
||||
"main",
|
||||
"feature/customer",
|
||||
"feature/discounts",
|
||||
"origin/main",
|
||||
"origin/release/1.0",
|
||||
"v0.1.0",
|
||||
] {
|
||||
assert!(refs.lines().any(|r| r == name), "{name} missing in {refs}");
|
||||
}
|
||||
assert!(!refs.lines().any(|r| r == "release/1.0" || r == "teammate"));
|
||||
assert_eq!(
|
||||
git(
|
||||
shop,
|
||||
&["rev-parse", "--abbrev-ref", "main@{upstream}"],
|
||||
None
|
||||
)
|
||||
.unwrap()
|
||||
.trim(),
|
||||
"origin/main"
|
||||
);
|
||||
|
||||
assert_eq!(
|
||||
git(shop, &["check-ignore", "var/log/app.log"], None)
|
||||
.unwrap()
|
||||
.trim(),
|
||||
"var/log/app.log"
|
||||
);
|
||||
|
||||
git(shop, &["fetch", "-q", "origin"], None).unwrap();
|
||||
assert_eq!(
|
||||
git(shop, &["rev-list", "--count", "main..origin/main"], None)
|
||||
.unwrap()
|
||||
.trim(),
|
||||
"1"
|
||||
);
|
||||
|
||||
assert!(git(shop, &["merge", "--no-edit", "feature/discounts"], None).is_err());
|
||||
assert_eq!(
|
||||
git(shop, &["diff", "--name-only", "--diff-filter=U"], None)
|
||||
.unwrap()
|
||||
.trim(),
|
||||
"src/Service/PriceCalculator.php"
|
||||
);
|
||||
assert!(shop.join("src/Service/DiscountPolicy.php").is_file());
|
||||
|
||||
std::fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn refuses_a_folder_that_is_not_empty() {
|
||||
let dir = temp_dir("busy");
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
std::fs::write(dir.join("keep.txt"), "mine").unwrap();
|
||||
let err = create(&dir).unwrap_err();
|
||||
assert!(err.contains("not empty"), "{err}");
|
||||
assert_eq!(
|
||||
std::fs::read_to_string(dir.join("keep.txt")).unwrap(),
|
||||
"mine"
|
||||
);
|
||||
std::fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn needs_a_folder_argument() {
|
||||
assert!(run(&[]).unwrap_err().contains("usage"));
|
||||
}
|
||||
}
|
||||
|
|
@ -5,6 +5,7 @@
|
|||
|
||||
mod assets;
|
||||
mod cleanroom;
|
||||
mod demo;
|
||||
mod layers;
|
||||
mod licences;
|
||||
mod lints;
|
||||
|
|
@ -27,6 +28,7 @@ commands:
|
|||
lints-selftest prove that shipped unwrap() fails clippy and test unwrap() passes
|
||||
dev [-- ARGS] run the desktop app in development mode, ARGS go to the app
|
||||
fixtures create Symfony and Laravel reference projects in target/fixtures/
|
||||
demo-project DIR create the offline demo for docs/alpha-checklist.md in DIR
|
||||
",
|
||||
"mac-report [--skip-gate] [--port PORT] [--out DIR]
|
||||
check this machine end to end and write one report file
|
||||
|
|
@ -57,6 +59,7 @@ fn main() -> ExitCode {
|
|||
tasks::dev(&app_args)
|
||||
}
|
||||
"fixtures" => tasks::fixtures(),
|
||||
"demo-project" => demo::run(rest),
|
||||
"mac-report" => macreport::parse(rest).and_then(|o| macreport::mac_report(&o)),
|
||||
"help" | "--help" | "-h" => {
|
||||
println!("{USAGE}");
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue