diff --git a/.dsh-version.json b/.dsh-version.json index 3d10108..069c761 100644 --- a/.dsh-version.json +++ b/.dsh-version.json @@ -491,6 +491,28 @@ ], "vendoredPatches": 2 }, + "dsh-rust-dev": { + "version": "0.1.0-alpha.1", + "rows": [ + "rust-dev" + ], + "rowOverrides": [], + "role": "Rust development as a surface: six tools over the machine's own cargo, rustc and rustup - `rust_status` (the four facts that fail independently: toolchain, components, installed targets, the workspace, plus which notable crates it declares - eframe, egui, wgpu, tokio, tracing, serde, clap, tauri, bevy), `cargo_check` (diagnostics PARSED from `--message-format=json`, with rustc codes, file:line:column and one mistake repeated at forty call sites collapsed to one item with a count), `cargo_test` (the summary, the failing names, the first failure's captured output), `cargo_build` (the artefact path from cargo's own `compiler-artifact` events and its real size, and a binary run only when `run: true` is asked for), `rust_deps` (duplicate crate versions with their dependents, the most-depended-on crates, and the `-e features` chain that enabled one crate) and `rust_backtrace` (demangled symbols, frames classed as the caller's own / a dependency / the runtime, and which frame is the first in your code - the v0 mangling is refused rather than invented) - plus four bundled skills (workspaces, diagnostics, debugging, and egui/eframe/wgpu apps) whose every ```rust example a check compiles as a whole src/lib.rs. Every cargo call runs `--offline` unless the caller passes `fetch: true`; nothing installs a toolchain, a component or a crate; and a build is never presented as read-only, because build.rs and proc macros RUN. Host-only: one row, no route, no browser half. Zero npm dependencies, nothing bundled, no bundled engine. See packages/dsh-rust-dev/README.md.", + "uses": [ + "@deepseek-ai/dsh-tools (the registry the six tools are registered into)", + "@deepseek-ai/dsh-skill (ctx.skills, resolved lazily; the four bundled skills are also copied into $DSH_HOME/skills by both installers)", + "the machine's own `cargo`, `rustc` and `rustup` - the user's programs, never bundled" + ], + "requires": [ + "a Rust toolchain on PATH for the driven answers (`rust_status` reports its absence as an ANSWER naming rustup, not as a failure)", + "a Cargo.toml at or above the directory inspected, for the workspace facts", + "`rustup component add clippy` (or `rustfmt`, or `rust-analyzer`) for the components that are missing - this row prints that command and never runs it", + "for a resolve that the lockfile and the local cache cannot answer, an explicit `fetch: true` on that one call" + ], + "vendors": [ + "NOTHING is vendored, downloaded or installed: the toolchain is the user's own, and this package ships the JSON parsers, the demangler, the argv and the triage order" + ] + }, "dsh-screenshot": { "version": "0.1.0-alpha.1", "rows": [ diff --git a/.gitignore b/.gitignore index 6990098..1709ecc 100644 --- a/.gitignore +++ b/.gitignore @@ -52,6 +52,13 @@ id_ed25519* # zero npm dependencies); if you ever need a committed one, force-add it. .npmrc +# A FIXTURE CRATE's build tree. `packages/dsh-rust-dev/checks/fixtures/*` holds +# small cargo projects that the package's own check drives; the check points +# CARGO_TARGET_DIR at a temp directory so nothing lands here, and this rule is the +# belt for the run somebody does by hand. Scoped to the fixtures on purpose: this +# repository ships no Rust of its own. +packages/dsh-rust-dev/checks/fixtures/**/target/ + # The PROTOTYPING LAB (`dsh-proto-lab`) is a workshop, not an exhibit: `lab_new` # generates runs into `/lab/` for the agent to try things in, and a # repository that accumulated every sketch anyone ever generated would stop being diff --git a/AGENTS.md b/AGENTS.md index 629604a..3f9f383 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -142,16 +142,25 @@ for its behaviour, `SECURITY.md` before touching credentials or the launcher, an that teach the tool surface, the method layer and the ethics layer, and a Research tab that also edits the document — host half plus UI, no socket, no vendored engine), + `dsh-rust-dev` (Rust as a surface: six tools over the machine's own `cargo`, + `rustc` and `rustup` — `rust_status` reports the four facts that fail + independently, `cargo_check` parses `--message-format=json` into codes and + `file:line:column` with duplicates collapsed, `cargo_test` / `cargo_build` / + `rust_deps` / `rust_backtrace` answer the rest, and four skills teach the triage + order including egui/eframe/wgpu apps; every cargo call is `--offline` unless + `fetch: true`, nothing is installed, and a build is never called read-only + because `build.rs` runs — host-only, zero npm dependencies), `dsh-browser`, `dsh-themes`, `dsh-cmdbar`, `dsh-modal`, `dsh-skills`, `dsh-ui-state`, `dsh-open-in-app`. - A package may carry its OWN checks under `packages//checks/`, run with `npm run check` in that folder. They travel with the package (which is what makes them useful outside this repository) and they are ADDITIONAL to - `scripts/checks/`, never a replacement for it: today ten packages ship their own - (`dsh-supercollider` with four checks, `dsh-research` with seven, plus - `dsh-diagrams`, `dsh-frontend-craft`, `dsh-proto-lab`, `dsh-ocr`, `dsh-wsl`, - `dsh-docker`, `dsh-ollama` and `dsh-image-upscale`), and the pack-wide checks - still own the routes, the bundle and the manifest. + `scripts/checks/`, never a replacement for it: today eleven packages ship their + own (`dsh-supercollider` with four checks, `dsh-research` with seven, + `dsh-rust-dev` with two, plus `dsh-diagrams`, `dsh-frontend-craft`, + `dsh-proto-lab`, `dsh-ocr`, `dsh-wsl`, `dsh-docker`, `dsh-ollama` and + `dsh-image-upscale`), and the pack-wide checks still own the routes, the bundle + and the manifest. - `scripts/` — the launcher (`run-web.*`), and four folders: `console/` (the shared console layer), `setup/` (install and uninstall, which a fresh machine runs once), `tools/` (maintainer-only: the fork re-sync for the client bundles this pack vendors) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index e637352..6203bbf 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -60,6 +60,7 @@ disable/replace a core row **in its own layer** — a later layer wins per row. | `dsh-diagrams` | `diagrams` | Mermaid + TikZ + the vendored **Diagram Design** kit (204 examples, 44 documented types) and the seven `diagram_*` tools, validated on the host | | `dsh-shaders` | `shaders` | GLSL that **compiles for real**: seven `shader_*` tools over a disposable headless browser (ANGLE/SwiftShader, argv-only, `MAP * ~NOTFOUND`), a rung ladder that is always stated (`v1-static` → `v2-compiled` → `v3-drawn` → `v4-measured`), diagnostics mapped onto the author's own line numbers, five dialects kept apart (es100, es300, shadertoy, shader-skills, and desktop GLSL, which is **refused** rather than faked), emit for web / `.frag` / ISF / FFGL-scaffold / Shadertoy, a Shaders tab with a live WebGL preview and `@param` sliders, five skills whose every example a check compiles, and three vendored corpora (106 Radiant pages with 79 extracted fragments, shader-skills' 20 modules + 11 templates + 11 pieces, and a 48-link curated index) that each re-derive offline | | `dsh-frontend-craft` | `frontend-craft` | front-end design craft: Impeccable's Apache-2.0 corpus (24 commands, 41 references) vendored at a pinned commit, its 61-rule detector built to a 4.5 MB WebAssembly module shipped in the package, `fe_context` / `fe_detect` / `fe_direction` / `fe_render` / `fe_artifact`, and a **Frontend** tab of findings, artifacts, directions and rendered previews. No network, no install, no engine download | +| `dsh-rust-dev` | `rust-dev` | Rust as a surface: `rust_status` (toolchain / components / targets / workspace — the four facts that fail independently), `cargo_check` (diagnostics parsed from `--message-format=json`, codes and `file:line:col`, duplicates collapsed), `cargo_test`, `cargo_build` (artefact path and size), `rust_deps` (duplicate versions, feature chains), `rust_backtrace` (demangled frames classed into your code / a dependency / the runtime), and four skills including egui/eframe/wgpu. `--offline` by default, nothing installed, a build is never presented as read-only. Host-only | | `dsh-pdf` | `pdf` | PDF reader tab + `pdf_info` / `pdf_read` / `pdf_find` / `pdf_render` / `pdf_scan` over vendored pdf.js | | `dsh-research` | `research` | research as a folder the agent fills and the right bar shows: a run is `RUN.json` + a `passport.json` that records the user's instructions and every gate answer **verbatim**, three `rs_*` tools, four routes, and the Research tab where a **person** — never the model — answers the two frame gates (`g1-rq`, `g2-intake`). No socket, no child process, no vendored engine | | `dsh-ocr` | `ocr` | the pack's OCR owner: one tool, `ocr`, over `tesseract` from PATH or the OCR engine Windows itself ships (`lib/win-ocr.ps1` + `Windows.Media.Ocr`, which rasterizes a PDF page through `Windows.Data.Pdf`). Host-only — no client, no route | diff --git a/README.md b/README.md index 5884a22..4ab3f4e 100644 --- a/README.md +++ b/README.md @@ -56,36 +56,37 @@ way and what it touches. The exact versions are in | Package | What it adds | |---|---| -| [`dsh-audio`](packages/dsh-audio/README.md) | a waveform surface: WAV/AIFF/FLAC, one track per channel, dBFS, selection and playback | -| [`dsh-browser`](packages/dsh-browser/README.md) | the **Browser** tab, replacing the shipped iframe one: the page is rendered on the host in a disposable engine behind an https-only egress gate (screenshot, post-script text, measured styles) for the tab and for `browser_render` / `browser_query` / `browser_text` — **built and shipped, but turned OFF**: the master layer disables the row, so a profile loads no tab, no routes, no tools and no client bundle | -| [`dsh-cmdbar`](packages/dsh-cmdbar/README.md) | the **command bar**: the agent's own commands in a bottom dock (a read-only transcript of the conversation's log — the terminals were removed in alpha.12; the panel follows whichever conversation is on screen) | -| [`dsh-diagrams`](packages/dsh-diagrams/README.md) | Mermaid, TikZ **and the Diagram Design kit** as tabs *and* seven agent tools — the kit's 204 examples and 44 documented types are vendored at a pinned commit, browsable on the index page, insertable in one call, and every write (a self-contained HTML document included) is validated before it is stored | -| [`dsh-docker`](packages/dsh-docker/README.md) | **Docker (or Podman) as a surface**: nine `docker_*` tools over the machine's own CLI — state, containers, images, inspect, logs, pull, run, lifecycle and a `docker_start` that launches **Docker Desktop** (or a `podman machine`) and waits for its **daemon** — plus a Docker tab listing containers and images with start/stop/remove, pull and run. argv-only, no shell, every removal confirmed by repeating the target, and no spelling for `exec`, `system prune` or `--privileged`. A Docker Desktop that is closed is the normal state on Windows 11: the answer says so and offers the button | -| [`dsh-editor`](packages/dsh-editor/README.md) | text and code tabs (vendored CodeMirror 6), with a Markdown preview and Save/Create | -| [`dsh-frontend-craft`](packages/dsh-frontend-craft/README.md) | front-end design craft: **Impeccable's** Apache-2.0 corpus vendored at a pinned commit — 24 commands, 41 references, the craft floor, the four visitor modes and the native platform references — plus its **61-rule detector built to WebAssembly inside the package**, so there is no `npx impeccable`, no engine download and no network. Five `fe_*` tools (`fe_context`, `fe_detect`, `fe_direction`, `fe_artifact`, and `fe_render`, which renders a workspace HTML file or a loopback dev-server URL in the machine's own headless Chrome/Edge and measures contrast, tap targets, overflow, line length, type size, heading order and missing alt), an 18-world local direction deck so the roll always carries a challenger the agent did not write, and a **Frontend** tab with findings, artifacts, the direction round and the rendered picture. The detector's findings match the upstream CLI **186/186** on its own fixtures | -| [`dsh-gittree`](packages/dsh-gittree/README.md) | **read-only** History tab: the workspace's commits as a graph rail (lanes, merges, PR chips), and the files each one touched | -| [`dsh-image`](packages/dsh-image/README.md) | an image viewer that fits, zooms, pans, and reads the source pixel under the pointer | -| [`dsh-image-upscale`](packages/dsh-image-upscale/README.md) | the agent can make a small image **big without making it worse**: four `upscale_*` tools over **Real-ESRGAN** (`realesr-general-x4v3` by default) run through the Python and torch **this machine already has** — `upscale_info` says whether CUDA is there and which models are on disk, `upscale_image` writes a NEW file (never the original) with the model, device, ms and bytes in the answer, `upscale_batch` takes a manifest and is a dry run by DEFAULT (existing outputs skipped, not replaced), and `upscale_fetch_weights` downloads one 4.7 MB model only after `confirm` repeats its name. Zero npm dependencies, no engine bundled, and a four-line `torchvision.transforms.functional_tensor` shim so a `realesrgan` that is broken against torchvision 0.17+ still runs | -| [`dsh-media`](packages/dsh-media/README.md) | media the agent can work with: `media_probe` / `media_run` / `media_frames` over a **pinned, SHA-256-verified** ffmpeg copy, plus the routes the video tab streams through | -| [`dsh-modal`](packages/dsh-modal/README.md) | the shared dialog surface (`modals`) the pack's controls use | -| [`dsh-ocr`](packages/dsh-ocr/README.md) | the agent can read a **picture**: one `ocr` tool over `tesseract` from PATH or — on Windows, with **nothing installed at all** — the OCR engine Windows ships, which rasterizes a PDF page itself. Names the engine, the language and the page count, refuses a language this host has no data for with the list of what it CAN read, and says every answer is a transcription | -| [`dsh-ollama`](packages/dsh-ollama/README.md) | **Ollama as a measured surface**: five `ollama_*` tools over the machine's own daemon — status (the models on disk, what is **loaded** right now, and `ollama serve` when nothing answers), **one bounded inference** with the token counts and nanosecond durations Ollama reports and nothing in the pack used to read, a **benchmark that refuses fewer than 3 runs** and reports a median with spread (cold vs warm stated at the *first token*, because a cold load never lowers tok/s), A/B and `num_ctx` sweeps, models with pull/delete confirmed by repeating the tag, embeddings with cosine similarity — plus **three skills** (the REST API, the metric arithmetic, the Python client) whose examples a check parses, and a **loopback fence** that refuses a daemon on another machine before any request. A daemon that is down is an answer, not a failure | -| [`dsh-open-in-app`](packages/dsh-open-in-app/README.md) | *Open In…* patched to open the OS file browser directly | -| [`dsh-pdf`](packages/dsh-pdf/README.md) | PDF as a surface the agent can read and **scan**, plus a reader tab with thumbnails and bookmarks | -| [`dsh-proto-lab`](packages/dsh-proto-lab/README.md) | a **prototyping lab** the agent fills: five `lab_*` tools write a run into the workspace's own `/lab///` — p5.js sketches a browser opens, and openFrameworks projects that are three real C++ files (`src/main.cpp`, `src/ofApp.h`, `src/ofApp.cpp`) built with your own projectGenerator and `make`. A **runtime registry** makes a third language one module and one line (Processing in Rust, Cinder), a committed example library sits beside each skill and is driven by the checks, and verification is an explicit ladder — structure, parse, compile, render, measure — whose answer always names the tier that was actually reached. The lab itself is **gitignored**: the bundle ships the generator and the examples, never the runs | -| [`dsh-research`](packages/dsh-research/README.md) | research as a **folder you keep**: your instruction and every gate answer recorded **in your own words**, nine `rs_*` tools over an append-only claim and source ledger — `rs_write` refuses until *you* confirm the question, and a claim's quote is checked against its source. Numbers are data (`p = .000` refused), a **method record**'s screening counts cannot increase, and a **disclosure record** must be *complete* — authors, ethics, funding, conflicts, data, AI use — before the submission folder prints it beside the title page, never in the manuscript a reviewer sees. `rs_verify action=calibrate` **measures the reader**, and the tab is rendered and measured in a real browser. Eight skills, an editable tab, no socket, no child process, nothing vendored | -| [`dsh-rightbar`](packages/dsh-rightbar/README.md) | the pack's own right bar: tab strip, docking panel and the `sidebarRight` registry (a fork of the shipped bar) | -| [`dsh-rightbar-files`](packages/dsh-rightbar-files/README.md) | the Files tab type on top of that bar | -| [`dsh-screenshot`](packages/dsh-screenshot/README.md) | **screenshots worth publishing**: four tools over three surfaces and one placement pass — `shot_url` renders a page in a disposable headless Chrome/Edge (a loopback dev server, a workspace `.html`, or a public site **only** with `remote: true`, because every other name resolves to `NOTFOUND`), at a named viewport with `dpr`, `dark`, `fullPage` or `clip: ".card"`, and reports the file's **real** size from its own IHDR; `shot_window` / `shot_screen` capture a **real application window** or the display on Windows through Win32 `PrintWindow` with a screen fallback that names itself and the window's own DPI as the scale; `shot_place` writes `-[-dark].png` plus a manifest and returns the README ``/`` block with alt text required. **No git and no credential**, no bundled engine, no dependency — and **three skills** (`screenshot-surfaces`, `readme-media`, `app-tour`) | -| [`dsh-shaders`](packages/dsh-shaders/README.md) | **GLSL that compiles for real**: seven `shader_*` tools drive the browser this machine already has — argv-only, throwaway profile, every name resolved to `NOTFOUND` — and every answer names the rung it **actually reached** (`v1-static` → `v2-compiled` → `v3-drawn` → `v4-measured`), with each diagnostic mapped back onto *your* line numbers and the active uniforms read out of the linked program. Five dialects are kept apart because they are not interchangeable, and **desktop GLSL is refused rather than faked** (ANGLE cannot compile it). `shader_target` emits a standalone web page, a `.frag`+`.vert` pair, **ISF** (which Resolume reads), a FreeFrameGL C++ **scaffold** — never a build, FFGL is a C++ ABI — or Shadertoy names. The corpus is 3.1 MB of pinned MIT shaders: **106 Radiant pages with 79 extracted fragment sources**, **20 reusable GLSL modules, 11 templates, 11 finished pieces and 14 written references** from `shader-skills`, and a 48-link curated index; every byte re-derives **offline** (`vendor/*/build.mjs --check`). A **Shaders** tab draws the live WebGL preview with one slider per `@param`, five skills teach the language and the triage order, and the checks compile **every fragment in both corpora** and draw every finished piece | -| [`dsh-skills`](packages/dsh-skills/README.md) | the **Skills browser**: a header button left of the zoom control opens every skill this conversation loads, with its markdown and inline editing | -| [`dsh-sql-server`](packages/dsh-sql-server/README.md) | **SQL Server as a surface**: seven `sql_*` tools over a container this row owns (the 2022 image, port 1433, a named volume) or the `sqlcmd` already on your PATH, keeping apart the **four facts that fail independently** — a *server*, a *client*, a *listening port*, and the machine-wide **ODBC driver** an application connects with, which no container can supply. `sql_server action=start` waits until the server **answers a `SELECT 1`**, not until the container says running; `sql_driver` changes your machine only when `confirm: "install"` repeats the request; and `sql_script` streams a multi-gigabyte dump through `sqlcmd -i` (stdin silently dropped rows) with BOM-aware code pages for SSMS's UTF-16 and an optional filter that drops the dump's own `CREATE DATABASE` header naming another machine's paths. Two skills, host-only, zero npm dependencies, no bundled engine | -| [`dsh-supercollider`](packages/dsh-supercollider/README.md) | SuperCollider the agent can **play**: ten `sc_*` tools over one long-lived `sclang` session (a warm round trip is ~31 ms, and what the agent defines is still there next call) and a hand-written OSC client to `scsynth`, the installed `.schelp` reference indexed for `sc_help`, the `.scd` file workflow, and **five skills** that teach the language, SynthDefs and live coding — every code example in them compiled by a check. Zero npm dependencies and nothing bundled — it finds the machine's own SuperCollider — and its own UI is one small console tab, with `.scd` files opening in the editor | -| [`dsh-themes`](packages/dsh-themes/README.md) | header controls (themes incl. Nord/Monokai/Hacker/Cyber, screenshot, page zoom), the Markdown paper, VN branding, and the shipped account-menu Feedback row hidden | -| [`dsh-ui-state`](packages/dsh-ui-state/README.md) | the pack's own UI state (zoom, theme, dock, column widths) remembered host-side | -| [`dsh-video`](packages/dsh-video/README.md) | a player tab that streams and seeks any video container, with an ffprobe facts panel, chapter jumps and a one-click remux when the browser cannot decode it | -| [`dsh-vn-master`](packages/dsh-vn-master/README.md) | the browser-free master, installed **last** - the slot pack-wide patches and row restatements go in (it enables the Browser tab on the web profile, and removes the feedback surface) | -| [`dsh-wsl`](packages/dsh-wsl/README.md) | the **POSIX half of this pack, testable on Windows**: `wsl_status` (the launcher's table decoded from UTF-16, the default distribution marked, and with `probe` whether a distribution can actually run a check), `wsl_run` (one **argv array** in a distribution — no shell string — with a deadline, a tree kill, a 1 MB cap per stream and the exit code in the answer) and `wsl_path` (`C:\…` ⇄ `/mnt/c/…`). It exists so `run-web.sh`, `install.sh` and the `sh` branches of the checks run on the machine that writes them; the launcher's default on a Docker machine is `docker-desktop-data`, so the tools name the distribution they used | +| [`dsh-audio`](packages/dsh-audio/README.md) | A waveform surface for WAV, AIFF and FLAC: one track per channel, dBFS, selection and playback. It also draws the Media panel, which lists every audio, image, video and GIF file in the workspace. No microphone, no device list, no output routing. | +| [`dsh-browser`](packages/dsh-browser/README.md) | The Browser tab, replacing the shipped iframe one: a page rendered on the host in a disposable engine behind an https-only egress gate. It answers with a screenshot, post-script text and measured styles, for the tab and for three `browser_*` tools. Built and shipped but turned OFF, because the master layer disables the row. | +| [`dsh-cmdbar`](packages/dsh-cmdbar/README.md) | The command bar: the agent's own commands in a bottom dock, as a read-only transcript of the conversation log. It follows whichever conversation is on screen. | +| [`dsh-diagrams`](packages/dsh-diagrams/README.md) | Mermaid, TikZ and the Diagram Design kit as tabs and as seven `diagram_*` tools. The kit 204 examples and 44 documented types are vendored at a pinned commit and browsable on the index page. Every write, including a self-contained HTML document, is validated before it is stored. | +| [`dsh-docker`](packages/dsh-docker/README.md) | Docker or Podman as a surface: nine `docker_*` tools over the machine's own CLI, argv-only, with every removal confirmed by repeating the target. `docker_start` launches Docker Desktop or a podman machine and waits for the **daemon**. A Docker tab lists containers and images with their logs, and there is no `exec`, no `system prune` and no free-form `run`. | +| [`dsh-editor`](packages/dsh-editor/README.md) | Text and code tabs over a vendored CodeMirror 6, with save/create and a Markdown preview. Every extension is mapped through a guard, so an older engine opens the document unhighlighted instead of killing the tab. It also backs the `.scd`, diagram-source and research-document editors. | +| [`dsh-frontend-craft`](packages/dsh-frontend-craft/README.md) | Front-end design craft: Impeccable's Apache-2.0 corpus vendored at a pinned commit, plus its 61-rule detector built to WebAssembly inside the package. Five `fe_*` tools include `fe_render`, which renders a page in headless Chrome or Edge and measures contrast, tap targets and overflow. There is no `npx impeccable`, no engine download and no network. A Frontend tab shows findings, artifacts and the direction round. | +| [`dsh-gittree`](packages/dsh-gittree/README.md) | A read-only History tab: the workspace commits as a graph rail with lanes, merges and PR chips. Each commit lists the files it touched. It never runs a write. | +| [`dsh-image`](packages/dsh-image/README.md) | An image viewer that fits, zooms and pans, and reads the source pixel under the pointer. It opens from the Files tab and the Media panel. | +| [`dsh-image-upscale`](packages/dsh-image-upscale/README.md) | Four `upscale_*` tools over Real-ESRGAN, through the Python and torch this machine already has. It writes a NEW file and never the original, a manifest batch is a dry run by default, and the weight fetch refuses without `confirm`. Host-only, with no engine bundled. | +| [`dsh-media`](packages/dsh-media/README.md) | The pack ffmpeg owner: `media_probe`, `media_run` and `media_frames` over a pinned, SHA-256-verified ffmpeg copy. It also serves the Range routes the video tab streams through. No other package ships ffmpeg. | +| [`dsh-modal`](packages/dsh-modal/README.md) | The shared dialog surface (`modals` service) every control in the pack draws through. One dismissal and one focus model, instead of one per panel. | +| [`dsh-ocr`](packages/dsh-ocr/README.md) | One `ocr` tool over `tesseract` from PATH or, on Windows with nothing installed, the OCR engine Windows itself ships. It names the engine, the language and the page count, and refuses a missing language with the list of what it can read. Every answer is stated to be a transcription. | +| [`dsh-ollama`](packages/dsh-ollama/README.md) | Five `ollama_*` tools over the machine's own daemon: status that names `ollama serve` when nothing answers, one bounded inference with the daemon's own token counts and durations, and a benchmark that refuses fewer than 3 runs and reports a median with spread. Pull and delete require the tag repeated back, and embeddings report cosine similarity. A loopback fence refuses a daemon on another machine before any request. | +| [`dsh-open-in-app`](packages/dsh-open-in-app/README.md) | The file-manager half of *Open In…*, patched to open the OS file browser directly. `explorer.exe` on Windows, `open` on macOS, `xdg-open` elsewhere, WSL-aware. | +| [`dsh-pdf`](packages/dsh-pdf/README.md) | PDF as a surface the agent can read: `pdf_info`, `pdf_read`, `pdf_find`, `pdf_render` and `pdf_scan` over vendored pdf.js. A reader tab adds thumbnails and bookmarks. A scanned page is reported as a scan rather than returned empty. | +| [`dsh-proto-lab`](packages/dsh-proto-lab/README.md) | A prototyping lab the agent fills: five `lab_*` tools write a run into the workspace own `lab///`. p5.js sketches open in a browser, and openFrameworks runs are three real C++ files built with your own projectGenerator and `make`. A runtime registry makes a third language one module and one line, and verification is a ladder that names the tier it reached. | +| [`dsh-research`](packages/dsh-research/README.md) | Research as a folder you keep: `RUN.json` plus a `passport.json` that records your instruction and every gate answer in your own words. Nine `rs_*` tools work over an append-only claim and source ledger, where numbers are data and a method record screening counts cannot increase. A disclosure record must be complete before the submission folder prints it, and two frame gates are answered by a person. Eight skills teach the tool surface, the method layer and the ethics layer. | +| [`dsh-rightbar`](packages/dsh-rightbar/README.md) | The right bar: tab strip, docking panel, expand button, Start page, and the `sidebarRight` service every tab type registers into. It is a generated fork of the shipped bar, so its layer disables the original rows. | +| [`dsh-rightbar-files`](packages/dsh-rightbar-files/README.md) | The Files tab type on that bar: a fork of the shipped file tree with open, rename and delete. It hands a file to the editor, image, audio or video tab that owns it. | +| [`dsh-rust-dev`](packages/dsh-rust-dev/README.md) | Rust as a surface: six tools over the machine's own `cargo`, `rustc` and `rustup`. `rust_status` reports the four facts that fail independently, `cargo_check` parses `--message-format=json` into codes and `file:line:column` with duplicates collapsed, and `rust_deps` answers duplicate versions and feature chains. `rust_backtrace` classes frames into your code, a dependency or the runtime. Four skills cover workspaces, diagnostics, debugging and egui/eframe/wgpu apps, and every cargo call is `--offline` unless `fetch: true`. | +| [`dsh-screenshot`](packages/dsh-screenshot/README.md) | Screenshots worth publishing: `shot_url` renders a page in a disposable headless Chrome or Edge with every other name resolved to `NOTFOUND`, at a named viewport with dpr, dark, full page or an element clip. `shot_window` and `shot_screen` capture a real application window or the display on Windows, and say so in one sentence elsewhere. `shot_place` writes a deterministic file plus a manifest and returns the README `` block with alt text required. No git, no credential, no bundled engine, three skills. | +| [`dsh-shaders`](packages/dsh-shaders/README.md) | GLSL that compiles for real: seven `shader_*` tools drive the machine's own browser, and every answer names the rung it actually reached (`v1-static` to `v4-measured`). Five dialects are kept apart because they are not interchangeable, and desktop GLSL is refused rather than faked. `shader_target` emits a web page, a `.frag` pair, ISF, an FFGL scaffold or Shadertoy names. A Shaders tab draws the live preview with one slider per `@param`. | +| [`dsh-skills`](packages/dsh-skills/README.md) | The Skills browser: a header button opens every skill this conversation loads, with its markdown and inline editing. It reads the same registry the agent does, so what you see is what is in effect. | +| [`dsh-sql-server`](packages/dsh-sql-server/README.md) | Seven `sql_*` tools over a container this row owns or the `sqlcmd` already on PATH. It keeps apart the four facts that fail independently: a server, a client, a listening port and the machine-wide ODBC driver. `sql_server start` waits until the server answers a statement, and `sql_script` loads a dump with BOM-aware code pages. | +| [`dsh-supercollider`](packages/dsh-supercollider/README.md) | SuperCollider the agent can play: eleven `sc_*` tools over one warm `sclang` session (about 31 ms a call, with state kept) and a hand-written OSC client to `scsynth`. The installed `.schelp` reference is indexed for `sc_help`, and the `.scd` workflow opens in the editor. Five skills teach the language, SynthDefs and live coding, and every example in them is compiled by a check. | +| [`dsh-themes`](packages/dsh-themes/README.md) | Header controls for themes (Nord, Monokai, Hacker, Cyber), screenshot and page zoom, plus the Markdown paper and the pack branding. It also hides the shipped account-menu Feedback row. | +| [`dsh-ui-state`](packages/dsh-ui-state/README.md) | The pack's own UI state, remembered host-side: zoom, theme, dock and column widths. It outlives the process, so a restart keeps the layout you left. | +| [`dsh-video`](packages/dsh-video/README.md) | A player tab that streams and seeks any container the browser can decode. An ffprobe facts panel names codec, size and frame rate, and one click remuxes when the browser cannot decode it. | +| [`dsh-vn-master`](packages/dsh-vn-master/README.md) | The pack's final layer: it installs last, so its row decisions win. It disables the four feedback/telemetry rows and the pack's own `browser` row, which is built and shipped deliberately off. Pack-wide row patches belong here. | +| [`dsh-wsl`](packages/dsh-wsl/README.md) | The POSIX half of this pack, testable on Windows: `wsl_status`, `wsl_run` and `wsl_path` over the machine's own WSL. `wsl_run` takes one argv array, never a shell string, with a deadline, a tree kill and a 1 MB cap per stream. The distribution is always named, because a Docker Desktop machine defaults to `docker-desktop-data`. | The pack used to ship its own Files panel (`dsh-files`, earlier `dsh-focus`); that was retired when the harness grew a real right Sidebar, and the installer prunes diff --git a/assets/vncode-banner5.png b/assets/vncode-banner5.png index 99596bf..750bf53 100644 Binary files a/assets/vncode-banner5.png and b/assets/vncode-banner5.png differ diff --git a/package.json b/package.json index 5a55e6f..5a1b2c7 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "vncode", - "version": "0.1.3", + "version": "0.1.4", "private": true, "description": "Personal plugin pack for DeepSeek Harness (Windows/MacOS/Linux). Installs into the raw web/CLI profile only (npx @deepseek-ai/dsh web).", "license": "AGPL-3.0-only", diff --git a/packages/dsh-rust-dev/README.md b/packages/dsh-rust-dev/README.md new file mode 100644 index 0000000..2ed78be --- /dev/null +++ b/packages/dsh-rust-dev/README.md @@ -0,0 +1,107 @@ +# dsh-rust-dev + +Rust development as a surface: six tools over **the machine's own** `cargo`, +`rustc` and `rustup`, and four skills that teach the triage order. + +Host-only — one row (`rust-dev`), no route, no browser half, **zero npm +dependencies**, nothing bundled, nothing downloaded. `cargo`, `rustc` and `rustup` +are your programs; this package ships the parsers, the argv, and the judgement. + +## Why it earns a row + +You can already run `cargo` in a terminal. What a terminal cannot do is hand a +reader the **shape** of the failure: + +- **volume** — a failing workspace build is thousands of lines. `cargo_check` + returns the 6 distinct errors behind 1,100 lines, with their codes and + `file:line:column`, and collapses one mistake repeated at forty call sites into + one item with `seen x40`; +- **assembly** — "why is this crate compiled twice", "which feature pulled it + in", "what is this binary made of" are three `cargo` invocations and a graph + walk each. `rust_deps` answers them in one call; +- **judgement** — panic vs `Result`, `#[expect]` vs `#[allow]`, MSRV, when a + backtrace is useless because the panic was caught. That is skill text; +- **your apps** — egui/eframe/wgpu have their own failure modes (a debug build of + eframe is dramatically slower, the artefact lands under `target//`, the + GPU driver is the runtime's business). `rust-ui-apps` covers them. + +## The four facts that fail independently + +"Rust is broken here" is almost never one thing, so `rust_status` reports four +separately — the same shape `dsh-sql-server` uses for server/client/port/driver: + +| Fact | Fails when | +|---|---| +| **toolchain** | no `cargo`, or a `rustup` default you did not expect | +| **components** | `clippy` / `rustfmt` / `rust-analyzer` were never added | +| **targets** | a cross-compile to a triple nobody installed | +| **workspace** | no `Cargo.toml`, or a `rust-version` above the installed toolchain | + +`rust_status` also names the notable crates the workspace declares (`eframe`, +`egui`, `wgpu`, `tokio`, `tracing`, `serde`, `clap`, `tauri`, `bevy`) because they +change the advice. It builds nothing: every fact comes from a version probe, +`rustup component list`, or `cargo metadata --no-deps`. + +## Tools + +| Tool | Answer | +|---|---| +| `rust_status` | the four facts, the workspace members, MSRV vs installed, lockfile, notable crates. Read-only | +| `cargo_check` | `cargo check` / `cargo clippy` with `--message-format=json`, **parsed**: counts, distinct items, rustc codes, `file:line:col`, duplicates collapsed | +| `cargo_test` | the summary, the failing test names, the first failure's captured output; `filter` reproduces one test | +| `cargo_build` | success, artefact **path** and real size, warnings, elapsed; `run: true` executes it with an argv array | +| `rust_deps` | duplicate crate versions with their dependents, the most-depended-on crates, and the feature chain (`-e features -i`) for one crate | +| `rust_backtrace` | demangled symbols, frames classed as **yours / dependency / runtime**, and which frame is the first in your code | + +Every answer names the command line it ran, whether it was offline, and what it +could not see. + +## Skills + +| Skill | Teaches | +|---|---| +| `rust-workspaces` | members and inheritance, `-p` vs `--workspace`, profiles and what `lto`/`codegen-units` trade, `target/` layout, `--locked`/`--offline`, feature unification, Cargo.lock discipline | +| `rust-diagnostics` | how a diagnostic is structured, the codes you meet weekly (`E0308`, `E0499`, `E0502`, `E0382`, `E0597`, …), clippy's named lints, lint levels, MSRV | +| `rust-debugging` | panic vs `Result`, reading a backtrace, caught panics, `dbg!`/`tracing`/`RUST_LOG`, isolating one test, release-only failures | +| `rust-ui-apps` | egui/eframe/wgpu: `App::update`, immediate mode, `Renderer::Wgpu` vs Glow, the dev-profile slowness and its fix, where the binary lands, cross-compiling, per-OS runtime needs | + +Every ```rust example in them compiles as a whole `src/lib.rs` in a crate with no +dependencies — `checks/check-rust-examples.mjs` proves it on every run. Examples +tagged ```rust,ignore are the ones that genuinely need egui/eframe/wgpu; they are +capped at six and only allowed in `rust-ui-apps`. + +## The rules this row does not bend + +- **`cargo` executes code.** `build.rs` and dependency proc macros run on your + machine during `cargo check`, so no tool here presents a build as a read-only + inspection. `rust_status` tells you whether a build script exists; the skills + tell you what that means. +- **No network the plugin starts.** Every cargo call runs **`--offline`** unless + the caller passes `fetch: true` for that one call, and the answer says which it + used. +- **Nothing is installed.** No `rustup toolchain install`, no `cargo install`, no + `cargo publish`. A missing component is a command printed for you to run. +- **argv only, never a shell**, with a deadline and a **tree kill** (`taskkill + /T` on Windows), because `cargo build` spawns `rustc` children that would + otherwise keep writing into `target/` after the parent died. +- **A byte ceiling, reported.** An answer that quietly dropped half the + diagnostics would be worse than a timeout. + +## What it is not + +Not a toolchain installer. Not a registry client. Not a language server — +`rust_status` reports whether `rust-analyzer` is installed and never drives it; +the pack owns leaves, not containers. Not a replacement for your shell. + +## Checking it + +```sh +node checks/check-rust-node.mjs # the row, the parsers, and the tools driven +node checks/check-rust-examples.mjs # every ```rust example compiled +``` + +`check-rust-node.mjs` runs against **captured** cargo output in +`checks/fixtures/` — a crate that does not compile, one whose test fails, and one +that panics at run time — and the fixture crates are committed beside the +captures, so the input is reproducible rather than described. The driven section +needs `cargo` and **skips loudly** without it. diff --git a/packages/dsh-rust-dev/checks/check-rust-examples.mjs b/packages/dsh-rust-dev/checks/check-rust-examples.mjs new file mode 100644 index 0000000..03aa719 --- /dev/null +++ b/packages/dsh-rust-dev/checks/check-rust-examples.mjs @@ -0,0 +1,196 @@ +#!/usr/bin/env node +// packages/dsh-rust-dev/checks/check-rust-examples.mjs - every fenced example +// in the shipped skills, compiled. +// +// The rule the four skills are written to: a ```rust fence is the ENTIRE +// contents of a `src/lib.rs` in a crate with NO dependencies, compiled offline +// with `cargo check`. So an example cannot drift into something that used to +// compile - if it is tagged ```rust, it compiles here or this check fails. +// +// A fence tagged ```rust,ignore is an illustration that genuinely needs egui, +// eframe or wgpu, which are not vendored (this package ships no crates). Those +// are counted, capped, and checked for shape - braces balanced, quotes balanced - +// and the cap exists so "ignore" cannot quietly become the normal case. Only +// `rust-ui-apps` may use it, because that is the only skill about APIs this +// repository cannot compile without adding a dependency. +// +// ```toml and ```sh fences are read, not run: a toml fragment is not a whole +// manifest, and running a shell command out of a document is not a check. +// +// Without cargo this can still count and shape-check every fence, and it SKIPS +// LOUDLY on the compile half rather than passing silently. +// +// Run: node packages/dsh-rust-dev/checks/check-rust-examples.mjs + +import { spawnSync } from 'node:child_process' +import fs from 'node:fs' +import os from 'node:os' +import path from 'node:path' +import { fileURLToPath } from 'node:url' + +const here = path.dirname(fileURLToPath(import.meta.url)) +const pkg = path.resolve(here, '..') +const failures = [] +const notes = [] +const fail = (message) => failures.push(message) + +const SKILLS = ['rust-workspaces', 'rust-diagnostics', 'rust-debugging', 'rust-ui-apps'] +const IGNORE_BUDGET = 6 +const IGNORE_ALLOWED_IN = new Set(['rust-ui-apps']) + +/** + * Every fenced block in one document. + * + * @param text - the markdown. + * @returns `[{ info, body, line }]` where `info` is the fence's info string. + */ +export function fencesOf(text) { + const lines = String(text).replace(/\r\n?/g, '\n').split('\n') + const fences = [] + let open = null + for (let index = 0; index < lines.length; index += 1) { + const line = lines[index] + const fence = /^```(.*)$/.exec(line) + if (open === null) { + if (fence !== null) open = { info: fence[1].trim(), line: index + 1, body: [] } + continue + } + if (fence !== null && fence[1].trim() === '') { + fences.push({ info: open.info, line: open.line, body: open.body.join('\n') }) + open = null + continue + } + open.body.push(line) + } + if (open !== null) fences.push({ info: open.info, line: open.line, body: open.body.join('\n'), unclosed: true }) + return fences +} + +/** A language from an info string: `rust,ignore` -> `{ lang: 'rust', ignore: true }`. */ +function classify(info) { + const parts = String(info ?? '').split(',').map((part) => part.trim()).filter(Boolean) + const lang = (parts[0] ?? '').toLowerCase() + return { lang, ignore: parts.slice(1).some((part) => part === 'ignore' || part === 'no-run' || part === 'norun') } +} + +/** Balanced braces, brackets and quotes: the only shape test an uncompiled example can have. */ +function shapeOf(body) { + const counts = { '{': 0, '}': 0, '[': 0, ']': 0, '(': 0, ')': 0 } + let quotes = 0 + let inLineComment = false + for (const line of body.split('\n')) { + inLineComment = false + for (let index = 0; index < line.length; index += 1) { + const char = line[index] + if (inLineComment) break + if (char === '/' && line[index + 1] === '/') { + inLineComment = true + break + } + if (char === '"' && line[index - 1] !== '\\') quotes += 1 + if (Object.prototype.hasOwnProperty.call(counts, char)) counts[char] += 1 + } + } + const balanced = counts['{'] === counts['}'] && counts['['] === counts[']'] && counts['('] === counts[')'] && quotes % 2 === 0 + return { balanced, counts, quotes } +} + +// --------------------------------------------------------------------------- +// Read and classify every fence +// --------------------------------------------------------------------------- +const all = [] +for (const skill of SKILLS) { + const file = path.join(pkg, 'skills', skill, 'SKILL.md') + if (!fs.existsSync(file)) { + fail('skill file is missing: ' + file) + continue + } + for (const fence of fencesOf(fs.readFileSync(file, 'utf8'))) { + const { lang, ignore } = classify(fence.info) + all.push({ skill, lang, ignore, body: fence.body, line: fence.line, unclosed: fence.unclosed === true }) + } +} + +for (const fence of all) { + if (fence.unclosed) fail(fence.skill + ': unclosed code fence at line ' + fence.line) + if (fence.body.trim() === '') fail(fence.skill + ': empty ' + (fence.lang || '(unlabelled)') + ' fence at line ' + fence.line) + if (fence.lang === '') fail(fence.skill + ': a fence at line ' + fence.line + ' has no language') +} + +const rust = all.filter((fence) => fence.lang === 'rust' && !fence.ignore) +const ignored = all.filter((fence) => fence.lang === 'rust' && fence.ignore) +const toml = all.filter((fence) => fence.lang === 'toml') +const shell = all.filter((fence) => fence.lang === 'sh' || fence.lang === 'bash') + +// --------------------------------------------------------------------------- +// The ignore budget +// --------------------------------------------------------------------------- +if (ignored.length > IGNORE_BUDGET) { + fail('rust,ignore fences: ' + ignored.length + ' is over the budget of ' + IGNORE_BUDGET + ' - an example that does not compile is the exception, not the rule') +} +for (const fence of ignored) { + if (!IGNORE_ALLOWED_IN.has(fence.skill)) { + fail(fence.skill + ': a rust,ignore fence at line ' + fence.line + ' - only rust-ui-apps may skip compilation') + } + const shape = shapeOf(fence.body) + if (!shape.balanced) { + fail(fence.skill + ': rust,ignore fence at line ' + fence.line + ' is not shape-balanced ' + JSON.stringify(shape.counts) + ' quotes=' + shape.quotes) + } + if (fence.body.trim().length < 80) { + fail(fence.skill + ': rust,ignore fence at line ' + fence.line + ' is too small to be an illustration') + } +} + +// --------------------------------------------------------------------------- +// Compile every plain ```rust fence as a whole src/lib.rs +// --------------------------------------------------------------------------- +const cargo = spawnSync('cargo', ['--version'], { encoding: 'utf8' }) +const hasCargo = cargo.status === 0 +if (!hasCargo) { + notes.push('no cargo on this host - ' + rust.length + ' ```rust example(s) were NOT compiled (counted and shape-checked only)') +} else if (rust.length > 0) { + const work = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-rust-dev-examples-')) + fs.mkdirSync(path.join(work, 'src'), { recursive: true }) + fs.writeFileSync( + path.join(work, 'Cargo.toml'), + ['[package]', 'name = "dsh-rust-dev-example"', 'version = "0.0.0"', 'edition = "2021"', 'publish = false', '', '[workspace]', ''].join('\n'), + ) + // One shared target dir: the crates are std-only, so the second compile is warm. + const env = { ...process.env, CARGO_TARGET_DIR: path.join(work, 'target') } + let compiled = 0 + for (const fence of rust) { + fs.writeFileSync(path.join(work, 'src/lib.rs'), fence.body + '\n') + const run = spawnSync('cargo', ['check', '--offline', '--quiet', '--message-format=short'], { + cwd: work, + encoding: 'utf8', + env, + timeout: 120_000, + }) + if (run.status === 0) { + compiled += 1 + continue + } + const why = String(run.stderr ?? '') + .split('\n') + .map((line) => line.trim()) + .filter((line) => line.startsWith('error') || line.includes('-->')) + .slice(0, 4) + .join(' | ') + fail(fence.skill + ': ```rust at line ' + fence.line + ' does not compile as a src/lib.rs: ' + (why || 'exit ' + run.status)) + } + notes.push(compiled + '/' + rust.length + ' ```rust example(s) compiled') + fs.rmSync(work, { recursive: true, force: true }) +} + +// --------------------------------------------------------------------------- +console.log('check-rust-examples: the four skills, their fences and their examples') +console.log( + ' fences: ' + all.length + ' total - ' + rust.length + ' rust, ' + ignored.length + ' rust,ignore, ' + toml.length + ' toml, ' + shell.length + ' shell', +) +for (const note of notes) console.log(' - ' + note) +if (failures.length) { + console.log(`\ncheck-rust-examples: ${failures.length} problem(s).`) + for (const message of failures) console.log(' - ' + message) + process.exit(1) +} +console.log('\ncheck-rust-examples: OK') diff --git a/packages/dsh-rust-dev/checks/check-rust-node.mjs b/packages/dsh-rust-dev/checks/check-rust-node.mjs new file mode 100644 index 0000000..7bd0731 --- /dev/null +++ b/packages/dsh-rust-dev/checks/check-rust-node.mjs @@ -0,0 +1,263 @@ +#!/usr/bin/env node +// packages/dsh-rust-dev/checks/check-rust-node.mjs - the row's own contract. +// +// What this proves: +// +// 1. THE SURFACE. Six tools, four skills, one row, and the version in +// `lib/index.js` still matches `package.json` (the manifest check reads both). +// 2. THE PARSERS, against output CAPTURED from a real cargo on this machine: +// `cargo check --message-format=json` from a crate that does not compile, +// `cargo test` from one whose test fails, and a real panic backtrace from one +// that panics at run time. The fixture crates are committed beside the +// captures, so the input is reproducible rather than described. +// 3. THE RULES THAT ARE EASY TO LOSE. A cargo summary line (`aborting due to 3 +// previous errors`) is NOT counted as a fourth error; a diagnostic repeated +// at several call sites is collapsed to one item with a count; a relative +// frame path from `cargo run` is still recognised as the caller's own code; +// the v0 mangling is passed through rather than invented. +// 4. THE TOOLS, DRIVEN, on a host that has cargo: `rust_status`, `cargo_check`, +// `cargo_test` and `rust_backtrace` run against the fixture crates. Without +// cargo that section SKIPS LOUDLY and exits 0 - a check that cannot run on +// this host says so, it does not pretend. +// +// Run: node packages/dsh-rust-dev/checks/check-rust-node.mjs + +import fs from 'node:fs' +import os from 'node:os' +import path from 'node:path' +import { fileURLToPath, pathToFileURL } from 'node:url' + +const here = path.dirname(fileURLToPath(import.meta.url)) +const pkg = path.resolve(here, '..') +const lib = await import(pathToFileURL(path.join(pkg, 'lib/index.js')).href) +const toolsMod = await import(pathToFileURL(path.join(pkg, 'lib/tools.js')).href) +const diag = await import(pathToFileURL(path.join(pkg, 'lib/diagnostics.js')).href) +const meta = await import(pathToFileURL(path.join(pkg, 'lib/metadata.js')).href) +const bt = await import(pathToFileURL(path.join(pkg, 'lib/backtrace.js')).href) +const probe = await import(pathToFileURL(path.join(pkg, 'lib/probe.js')).href) + +const failures = [] +const notes = [] +const fail = (message) => failures.push(message) +function check(name, actual, expected) { + const same = JSON.stringify(actual) === JSON.stringify(expected) + if (!same) fail(name + ': expected ' + JSON.stringify(expected) + ', got ' + JSON.stringify(actual)) + return same +} +function ok(name, condition) { + if (!condition) fail(name) + return condition +} + +const read = (relative) => fs.readFileSync(path.join(here, relative), 'utf8') +const captured = (name) => read(path.join('fixtures', 'captured', name)) + +// A target dir OUTSIDE the tree: a fixture crate must never grow a target/ inside +// the repository, and the check would otherwise be writing build output. +process.env.CARGO_TARGET_DIR = path.join(os.tmpdir(), 'dsh-rust-dev-check-target') + +// --------------------------------------------------------------------------- +// 1. The surface +// --------------------------------------------------------------------------- +const pkgJson = JSON.parse(fs.readFileSync(path.join(pkg, 'package.json'), 'utf8')) +check('the version in lib/index.js matches package.json', lib.PLUGIN_VERSION, pkgJson.version) +check('the row is named for the package', lib.name, pkgJson.name) +check('six tools are declared', lib.CAPABILITIES.tools.length, 6) +check('four skills are declared', lib.CAPABILITIES.skills.length, 4) +for (const file of lib.SKILL_FILES) { + const full = path.join(pkg, 'skills', path.basename(path.dirname(file.file)), 'SKILL.md') + ok('skill file exists: ' + file.name, fs.existsSync(full)) +} +const deps = lib.createDeps({ logger: { info() {}, warn() {} } }, { cwd: pkg }) +const tools = toolsMod.buildTools(deps) +check('buildTools returns six', tools.length, 6) +const names = tools.map((tool) => tool.name) +check('the tool names are the declared ones', names, lib.CAPABILITIES.tools) +for (const tool of tools) { + ok(tool.name + ' has a description of some length', typeof tool.description === 'string' && tool.description.length > 80) + ok(tool.name + ' declares an object schema', tool.parameters && tool.parameters.type === 'object') + ok(tool.name + ' is executable', typeof tool.execute === 'function') + ok(tool.name + ' renders text', typeof tool.output?.render === 'function') +} +ok('the activation line points at rust_status rather than claiming a state', lib.activationLine().includes('rust_status')) + +// --------------------------------------------------------------------------- +// 2. Diagnostics, from a real failed build +// --------------------------------------------------------------------------- +const brokenRoot = path.join(here, 'fixtures', 'broken-crate') +const checkStream = diag.parseJsonStream(captured('cargo-check.jsonl')) +check('the captured build failed', checkStream.finished?.success, false) +const summary = diag.summarizeDiagnostics(checkStream.messages, { limit: 20 }) +check('three type errors, not four (the cargo summary is not an error)', summary.counts.error, 3) +check('three distinct sites', summary.distinct.errors, 3) +check('the code is E0308 everywhere', Object.keys(summary.byCode), ['E0308']) +check('every item carries a location', summary.items.map((item) => item.file.replace(/\\/g, '/')), [ + 'src/lib.rs', + 'src/lib.rs', + 'src/lib.rs', +]) +check('and a line', summary.items.map((item) => item.line), [6, 12, 13]) +ok('the code carries its one-line meaning', summary.items.every((item) => item.hint === 'mismatched types')) +ok('the cargo summary is kept as prose, not as an item', summary.spanless.some((line) => /aborting|For more information|E0308/.test(line))) + +// A diagnostic reported twice at the SAME site collapses to one item with a count. +const doubled = [checkStream.messages[0], checkStream.messages[0]] +const deduped = diag.summarizeDiagnostics(doubled, { limit: 20 }) +check('a repeated site is one item', deduped.distinct.errors, 1) +check('with a repeat count', deduped.items[0].repeat, 2) +check('and the message count still says two', deduped.counts.error, 2) + +// `--message-format=json` interleaves build-script output; one stray line must not +// cost the diagnostics. +const withNoise = diag.parseJsonStream('warning: something a build script printed\n' + captured('cargo-check.jsonl')) +check('noise is counted, diagnostics survive', diag.summarizeDiagnostics(withNoise.messages).counts.error, 3) +check('the noise itself is reported', withNoise.noise.length, 1) + +// --------------------------------------------------------------------------- +// 3. Tests, from a real failing run +// --------------------------------------------------------------------------- +const testSummary = toolsMod.parseTestOutput(captured('cargo-test.txt')) +check('one test passed', testSummary.passed, 1) +check('one failed', testSummary.failed, 1) +check('one was ignored', testSummary.ignored, 1) +check('the failing test is named', testSummary.failing, ['tests::fails']) +ok('the first failure output is the captured stdout', testSummary.firstFailure.includes('the fixture prints this line before failing')) +ok('and the assertion message', testSummary.firstFailure.includes('the fixture asserts the wrong sum on purpose')) + +// --------------------------------------------------------------------------- +// 4. Backtraces, from a real panic +// --------------------------------------------------------------------------- +// The fixture ran FROM ITS OWN CRATE DIRECTORY, which is how `cargo run` presents +// frames: `.\src\main.rs`, relative. A parser that only understood absolute paths +// would classify the caller's own frame as unknown. +const panicRoot = path.join(here, 'fixtures', 'panic-crate') +const parsedBt = bt.parseBacktrace(captured('backtrace.txt'), { root: panicRoot, cwd: panicRoot }) +ok('the panic line was found', parsedBt.panic.includes('panicked at')) +ok('it names the message', captured('backtrace.txt').includes('the fixture panics here on purpose')) +ok('frames were parsed', parsedBt.frames.length > 0) +const verdict = bt.verdictOf(parsedBt) +check('the panic is in the workspace', verdict.kind, 'workspace') +ok('the first own frame is the fixture', verdict.frame.file.replace(/\\/g, '/').endsWith('src/main.rs')) +ok('std frames are the runtime', parsedBt.frames.filter((frame) => frame.kind === 'std').length > 0) +// The same panic captured with RUST_BACKTRACE=full carries addresses and deeper frames. +const fullBt = bt.parseBacktrace(captured('backtrace-full.txt'), { root: panicRoot, cwd: panicRoot }) +ok('the full capture parses too', fullBt.frames.length >= parsedBt.frames.length) +check('and still lands in the workspace', bt.verdictOf(fullBt).kind, 'workspace') + +// The legacy mangling is a length-prefixed path; decode it exactly. +check('legacy mangling decodes', bt.demangle('_ZN4core3fmt5write17h1234567890abcdefE'), 'core::fmt::write') +check('a nested path decodes', bt.demangle('_ZN12dsh_rust_dev4tool8run_sync17habcdef0123456789E'), 'dsh_rust_dev::tool::run_sync') +check('an unmangled name is left alone', bt.demangle('std::panicking::panic_handler'), 'std::panicking::panic_handler') +check('the v0 mangling is NOT invented', bt.demangle('_RNvNtNtCs1234_4core3fmt5write'), '_RNvNtNtCs1234_4core3fmt5write') +check('a `.llvm.` suffix is stripped before decoding', bt.demangle('_ZN4core3fmt5write17h1234567890abcdefE.llvm.9F2A1B'), 'core::fmt::write') +check('a truncated symbol is refused rather than half-decoded', bt.demangle('_ZN4core3fmt5write17h1234567890abcde'), '_ZN4core3fmt5write17h1234567890abcde') + +// --------------------------------------------------------------------------- +// 5. The dependency graph +// --------------------------------------------------------------------------- +const metadata = JSON.parse(captured('cargo-metadata-nodeps.json')) +const graph = meta.graphOf(metadata) +check('the fixture crate is the whole graph', meta.graphSize(graph).packages, 1) +check('no duplicate versions in a one-crate graph', meta.duplicateVersions(graph), []) + +// The duplicate logic is a pure function over the metadata SHAPE, so it is tested +// with a shape rather than a captured graph: two versions of one crate, each with +// a known dependent. (A real duplicate needs two registry versions on disk.) +const shape = { + workspace_members: ['app 0.1.0 (path+file:///w/app)'], + packages: [ + { id: 'app', name: 'app', version: '0.1.0', source: null, manifest_path: '/w/app/Cargo.toml' }, + { id: 'old', name: 'serde_json', version: '0.9.0', source: 'registry+https://github.com/rust-lang/crates.io-index', manifest_path: '/r/old/Cargo.toml' }, + { id: 'new', name: 'serde_json', version: '1.0.0', source: 'registry+https://github.com/rust-lang/crates.io-index', manifest_path: '/r/new/Cargo.toml' }, + { id: 't1', name: 'old_dep', version: '0.1.0', source: 'registry+x', manifest_path: '/r/t1/Cargo.toml' }, + ], + resolve: { + nodes: [ + { id: 'app', deps: [{ name: 'serde_json', pkg: 'new' }, { name: 'old_dep', pkg: 't1' }] }, + { id: 'old', deps: [] }, + { id: 'new', deps: [] }, + { id: 't1', deps: [{ name: 'serde_json', pkg: 'old' }] }, + ], + }, +} +const shapeGraph = meta.graphOf(shape) +const duplicates = meta.duplicateVersions(shapeGraph) +check('two versions of one crate are found', duplicates.length, 1) +check('the crate is named', duplicates[0].name, 'serde_json') +check('both versions are listed, oldest first', duplicates[0].versions.map((entry) => entry.version), ['0.9.0', '1.0.0']) +check('each version names who uses it', duplicates[0].versions.map((entry) => entry.usedBy), [['old_dep'], ['app']]) +const heaviest = meta.mostDependedOn(shapeGraph, 5) +ok('the most-depended-on crate is reported', heaviest.some((entry) => entry.name === 'serde_json')) +check('semver ordering is numeric, not lexical', ['1.0.0', '0.9.0'].sort(meta.compareVersions), ['0.9.0', '1.0.0']) + +// Feature chains are cargo tree text: the lines ARE the answer, and the features +// are derived from them. +const chain = meta.featureChain(['serde_json v1.0.0', '├── serde feature "std"', '│ └── serde feature "alloc"', '└── serde_json feature "default"'].join('\n')) +check('features are deduplicated and sorted', chain.features, ['alloc', 'default', 'std']) +check('the lines are kept', chain.lines.length, 4) + +// --------------------------------------------------------------------------- +// 6. Skills on disk +// --------------------------------------------------------------------------- +for (const entry of lib.SKILL_FILES) { + const file = path.join(pkg, 'skills', path.basename(path.dirname(entry.file)), 'SKILL.md') + const text = fs.readFileSync(file, 'utf8') + const { meta: front, content } = lib.parseSkillFile(text) + ok(entry.name + ': has a name in frontmatter', typeof front.name === 'string' && front.name.length > 0) + ok(entry.name + ': has a description', typeof front.description === 'string' && front.description.length > 40) + ok(entry.name + ': has a body', content.length > 400) + ok(entry.name + ': is small enough to load', content.length < 40_000) +} + +// --------------------------------------------------------------------------- +// 7. The tools, driven (skipped loudly without cargo) +// --------------------------------------------------------------------------- +const hasCargo = probe.whichSync('cargo', process.env) !== '' +if (!hasCargo) { + notes.push('no cargo on this host - the driven section (rust_status, cargo_check, cargo_test, rust_backtrace) was SKIPPED') +} else { + const record = { log: { info() {}, warn() {} } } + const live = toolsMod.buildTools(lib.createDeps(record, { cwd: brokenRoot })) + + const statusAnswer = await live[0].execute({ cwd: brokenRoot }) + ok('rust_status finds the fixture workspace', statusAnswer.view.workspace.root !== null) + check('rust_status sees one member', statusAnswer.view.workspace.members, 1) + ok('rust_status reports the toolchain when there is one', statusAnswer.view.toolchain.version !== '') + ok('rust_status says where it looked', statusAnswer.text.includes('WORKSPACE')) + + const checkAnswer = await live[1].execute({ cwd: brokenRoot }) + check('cargo_check reports the three errors', checkAnswer.view.errors, 3) + check('cargo_check is not ok', checkAnswer.view.ok, false) + ok('cargo_check names the code', Object.keys(checkAnswer.view.byCode).includes('E0308')) + ok('cargo_check ran offline by default', checkAnswer.view.offline === true) + ok('cargo_check names the command it ran', checkAnswer.text.includes('cargo check --message-format=json --offline')) + ok('cargo_check says where', checkAnswer.text.includes('src/lib.rs:6:21')) + + const testAnswer = await live[2].execute({ cwd: path.join(here, 'fixtures', 'failing-test-crate') }) + check('cargo_test reports the failure', testAnswer.view.failed, 1) + check('cargo_test names the failing test', testAnswer.view.failing, ['tests::fails']) + ok('cargo_test shows the captured output', testAnswer.text.includes('the fixture prints this line before failing')) + + const btAnswer = await live[5].execute({ text: captured('backtrace.txt'), root: panicRoot }) + check('rust_backtrace lands in the workspace', btAnswer.view.verdict, 'workspace') + ok('rust_backtrace names the first own frame', btAnswer.text.includes('YOUR CODE')) + + // A backtrace with no frames must say so rather than inventing a location. + const emptyBt = await live[5].execute({ text: 'thread \'main\' panicked at src/main.rs:1:1:\nboom\n', root: panicRoot }) + check('no frames is an answer, not a crash', emptyBt.view.code, 'NO_FRAMES') + ok('and it names the variable that enables one', emptyBt.text.includes('RUST_BACKTRACE')) + + // A non-workspace path is a refusal, not a wrong answer. + const nowhere = await live[0].execute({ cwd: os.tmpdir() }) + ok('rust_status on a non-cargo directory says so', nowhere.view.workspace.root === null || nowhere.view.workspace.error !== undefined) +} + +// --------------------------------------------------------------------------- +console.log('check-rust-node: the row, its parsers (captured from real cargo) and its tools') +for (const note of notes) console.log(' - ' + note) +if (failures.length) { + console.log(`\ncheck-rust-node: ${failures.length} problem(s).`) + for (const message of failures) console.log(' - ' + message) + process.exit(1) +} +console.log('\ncheck-rust-node: OK') diff --git a/packages/dsh-rust-dev/checks/fixtures/broken-crate/Cargo.lock b/packages/dsh-rust-dev/checks/fixtures/broken-crate/Cargo.lock new file mode 100644 index 0000000..02b546c --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/broken-crate/Cargo.lock @@ -0,0 +1,7 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "dsh-rust-dev-fixture-broken" +version = "0.0.0" diff --git a/packages/dsh-rust-dev/checks/fixtures/broken-crate/Cargo.toml b/packages/dsh-rust-dev/checks/fixtures/broken-crate/Cargo.toml new file mode 100644 index 0000000..1e6f6c0 --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/broken-crate/Cargo.toml @@ -0,0 +1,11 @@ +# A crate that does not compile, on purpose: it is the INPUT the diagnostics +# fixtures were captured from. Nothing builds it in CI; `check-rust-node.mjs` +# drives it only on a host that has cargo, and skips loudly elsewhere. +[package] +name = "dsh-rust-dev-fixture-broken" +version = "0.0.0" +edition = "2021" +publish = false + +# Its own workspace, so no parent workspace can absorb it. +[workspace] diff --git a/packages/dsh-rust-dev/checks/fixtures/broken-crate/src/lib.rs b/packages/dsh-rust-dev/checks/fixtures/broken-crate/src/lib.rs new file mode 100644 index 0000000..099ba45 --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/broken-crate/src/lib.rs @@ -0,0 +1,29 @@ +//! Deliberately broken: a type error, a borrow error, and a failing test. +//! This file is fixture INPUT, not shipped behaviour. + +/// Two distinct mistakes in one function: a mismatched type and a moved value. +pub fn mismatched() -> u32 { + let text: u32 = "not a number"; + text +} + +/// The same mistake at several call sites, so deduplication has something to collapse. +pub fn repeated() -> u32 { + let a: u32 = "one"; + let b: u32 = "two"; + a + b +} + +#[cfg(test)] +mod tests { + #[test] + fn this_one_fails() { + println!("about to fail on purpose"); + assert_eq!(2 + 2, 5, "arithmetic is not what this fixture assumes"); + } + + #[test] + fn this_one_passes() { + assert_eq!(2 + 2, 4); + } +} diff --git a/packages/dsh-rust-dev/checks/fixtures/captured/backtrace-full.txt b/packages/dsh-rust-dev/checks/fixtures/captured/backtrace-full.txt new file mode 100644 index 0000000..a22bad0 --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/captured/backtrace-full.txt @@ -0,0 +1,67 @@ + +thread 'main' (26148) panicked at src\main.rs:5:9: +the fixture panics here on purpose +stack backtrace: + 0: 0x7ff6e3957c39 - std::backtrace_rs::backtrace::win64::trace + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\..\..\backtrace\src\backtrace\win64.rs:85 + 1: 0x7ff6e3957c39 - std::backtrace_rs::backtrace::trace_unsynchronized + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\..\..\backtrace\src\backtrace\mod.rs:66 + 2: 0x7ff6e3957c39 - std::sys::backtrace::_print_fmt + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\sys\backtrace.rs:74 + 3: 0x7ff6e3957c39 - std::sys::backtrace::impl$0::print::impl$0::fmt + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\sys\backtrace.rs:44 + 4: 0x7ff6e3962d7e - core::fmt::write + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\core\src\fmt\mod.rs:0 + 5: 0x7ff6e395aa54 - core::io::write::default_write_fmt + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\core\src\io\write.rs:402 + 6: 0x7ff6e395aa54 - core::io::write::Write::write_fmt + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\core\src\io\write.rs:335 + 7: 0x7ff6e3952465 - std::sys::backtrace::BacktraceLock::print + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\sys\backtrace.rs:47 + 8: 0x7ff6e3952465 - std::panicking::default_hook::closure$0 + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\panicking.rs:292 + 9: 0x7ff6e395488a - std::panicking::default_hook + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\panicking.rs:319 + 10: 0x7ff6e3954a93 - std::panicking::panic_with_hook + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\panicking.rs:815 + 11: 0x7ff6e3952574 - std::panicking::panic_handler::closure$0 + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\panicking.rs:681 + 12: 0x7ff6e395173f - std::sys::backtrace::__rust_end_short_backtrace + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\sys\backtrace.rs:182 + 13: 0x7ff6e3952a3e - std::panicking::panic_handler + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\panicking.rs:679 + 14: 0x7ff6e396723d - core::panicking::panic_fmt + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\core\src\panicking.rs:80 + 15: 0x7ff6e39511b5 - dsh_rust_dev_fixture_panic::inner + at C:\Users\luisarandas\Desktop\github\dsh-plugins\packages\dsh-rust-dev\checks\fixtures\panic-crate\src\main.rs:5 + 16: 0x7ff6e39511c0 - dsh_rust_dev_fixture_panic::inner + at C:\Users\luisarandas\Desktop\github\dsh-plugins\packages\dsh-rust-dev\checks\fixtures\panic-crate\src\main.rs:7 + 17: 0x7ff6e39511c0 - dsh_rust_dev_fixture_panic::inner + at C:\Users\luisarandas\Desktop\github\dsh-plugins\packages\dsh-rust-dev\checks\fixtures\panic-crate\src\main.rs:7 + 18: 0x7ff6e395111e - dsh_rust_dev_fixture_panic::main + at C:\Users\luisarandas\Desktop\github\dsh-plugins\packages\dsh-rust-dev\checks\fixtures\panic-crate\src\main.rs:11 + 19: 0x7ff6e39510db - core::ops::function::FnOnce::call_once > + at C:\Users\luisarandas\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\core\src\ops\function.rs:250 + 20: 0x7ff6e395109e - std::sys::backtrace::__rust_begin_short_backtrace > + at C:\Users\luisarandas\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\std\src\sys\backtrace.rs:166 + 21: 0x7ff6e3951071 - std::rt::lang_start::closure$0 > + at C:\Users\luisarandas\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\std\src\rt.rs:206 + 22: 0x7ff6e3954020 - std::rt::lang_start_internal::closure$0 + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\rt.rs:175 + 23: 0x7ff6e3954020 - std::panicking::catch_unwind::do_call + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\panicking.rs:576 + 24: 0x7ff6e3954020 - std::panicking::catch_unwind + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\panicking.rs:544 + 25: 0x7ff6e3954020 - std::panic::catch_unwind + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\panic.rs:359 + 26: 0x7ff6e3954020 - std::rt::lang_start_internal + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\rt.rs:171 + 27: 0x7ff6e395105a - std::rt::lang_start > + at C:\Users\luisarandas\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\std\src\rt.rs:205 + 28: 0x7ff6e39511f9 - main + 29: 0x7ff6e39656f0 - invoke_main + at D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl:78 + 30: 0x7ff6e39656f0 - __scrt_common_main_seh + at D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl:288 + 31: 0x7ffcf0a3dda7 - BaseThreadInitThunk + 32: 0x7ffcf0eb9c5c - RtlUserThreadStart diff --git a/packages/dsh-rust-dev/checks/fixtures/captured/backtrace.txt b/packages/dsh-rust-dev/checks/fixtures/captured/backtrace.txt new file mode 100644 index 0000000..7c13594 --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/captured/backtrace.txt @@ -0,0 +1,19 @@ + +thread 'main' (17396) panicked at src\main.rs:5:9: +the fixture panics here on purpose +stack backtrace: + 0: std::panicking::panic_handler + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\std\src\panicking.rs:679 + 1: core::panicking::panic_fmt + at /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library\core\src\panicking.rs:80 + 2: dsh_rust_dev_fixture_panic::inner + at .\src\main.rs:5 + 3: dsh_rust_dev_fixture_panic::inner + at .\src\main.rs:7 + 4: dsh_rust_dev_fixture_panic::inner + at .\src\main.rs:7 + 5: dsh_rust_dev_fixture_panic::main + at .\src\main.rs:11 + 6: core::ops::function::FnOnce::call_once > + at C:\Users\luisarandas\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\core\src\ops\function.rs:250 +note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace. diff --git a/packages/dsh-rust-dev/checks/fixtures/captured/cargo-check.jsonl b/packages/dsh-rust-dev/checks/fixtures/captured/cargo-check.jsonl new file mode 100644 index 0000000..fea6d25 --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/captured/cargo-check.jsonl @@ -0,0 +1,5 @@ +{"reason":"compiler-message","package_id":"path+file:///C:/Users/luisarandas/Desktop/github/dsh-plugins/packages/dsh-rust-dev/checks/fixtures/broken-crate#dsh-rust-dev-fixture-broken@0.0.0","manifest_path":"C:\\Users\\luisarandas\\Desktop\\github\\dsh-plugins\\packages\\dsh-rust-dev\\checks\\fixtures\\broken-crate\\Cargo.toml","target":{"kind":["lib"],"crate_types":["lib"],"name":"dsh_rust_dev_fixture_broken","src_path":"C:\\Users\\luisarandas\\Desktop\\github\\dsh-plugins\\packages\\dsh-rust-dev\\checks\\fixtures\\broken-crate\\src\\lib.rs","edition":"2021","doc":true,"doctest":true,"test":true},"message":{"rendered":"error[E0308]: mismatched types\n --> src\\lib.rs:6:21\n |\n6 | let text: u32 = \"not a number\";\n | --- ^^^^^^^^^^^^^^ expected `u32`, found `&str`\n | |\n | expected due to this\n\n","$message_type":"diagnostic","children":[],"level":"error","message":"mismatched types","spans":[{"byte_end":274,"byte_start":260,"column_end":35,"column_start":21,"expansion":null,"file_name":"src\\lib.rs","is_primary":true,"label":"expected `u32`, found `&str`","line_end":6,"line_start":6,"suggested_replacement":null,"suggestion_applicability":null,"text":[{"highlight_end":35,"highlight_start":21,"text":" let text: u32 = \"not a number\";"}]},{"byte_end":257,"byte_start":254,"column_end":18,"column_start":15,"expansion":null,"file_name":"src\\lib.rs","is_primary":false,"label":"expected due to this","line_end":6,"line_start":6,"suggested_replacement":null,"suggestion_applicability":null,"text":[{"highlight_end":18,"highlight_start":15,"text":" let text: u32 = \"not a number\";"}]}],"code":{"code":"E0308","explanation":"Expected type did not match the received type.\n\nErroneous code examples:\n\n```compile_fail,E0308\nfn plus_one(x: i32) -> i32 {\n x + 1\n}\n\nplus_one(\"Not a number\");\n// ^^^^^^^^^^^^^^ expected `i32`, found `&str`\n\nif \"Not a bool\" {\n// ^^^^^^^^^^^^ expected `bool`, found `&str`\n}\n\nlet x: f32 = \"Not a float\";\n// --- ^^^^^^^^^^^^^ expected `f32`, found `&str`\n// |\n// expected due to this\n```\n\nThis error occurs when an expression was used in a place where the compiler\nexpected an expression of a different type. It can occur in several cases, the\nmost common being when calling a function and passing an argument which has a\ndifferent type than the matching type in the function declaration.\n"}}} +{"reason":"compiler-message","package_id":"path+file:///C:/Users/luisarandas/Desktop/github/dsh-plugins/packages/dsh-rust-dev/checks/fixtures/broken-crate#dsh-rust-dev-fixture-broken@0.0.0","manifest_path":"C:\\Users\\luisarandas\\Desktop\\github\\dsh-plugins\\packages\\dsh-rust-dev\\checks\\fixtures\\broken-crate\\Cargo.toml","target":{"kind":["lib"],"crate_types":["lib"],"name":"dsh_rust_dev_fixture_broken","src_path":"C:\\Users\\luisarandas\\Desktop\\github\\dsh-plugins\\packages\\dsh-rust-dev\\checks\\fixtures\\broken-crate\\src\\lib.rs","edition":"2021","doc":true,"doctest":true,"test":true},"message":{"rendered":"error[E0308]: mismatched types\n --> src\\lib.rs:12:18\n |\n12 | let a: u32 = \"one\";\n | --- ^^^^^ expected `u32`, found `&str`\n | |\n | expected due to this\n\n","$message_type":"diagnostic","children":[],"level":"error","message":"mismatched types","spans":[{"byte_end":425,"byte_start":420,"column_end":23,"column_start":18,"expansion":null,"file_name":"src\\lib.rs","is_primary":true,"label":"expected `u32`, found `&str`","line_end":12,"line_start":12,"suggested_replacement":null,"suggestion_applicability":null,"text":[{"highlight_end":23,"highlight_start":18,"text":" let a: u32 = \"one\";"}]},{"byte_end":417,"byte_start":414,"column_end":15,"column_start":12,"expansion":null,"file_name":"src\\lib.rs","is_primary":false,"label":"expected due to this","line_end":12,"line_start":12,"suggested_replacement":null,"suggestion_applicability":null,"text":[{"highlight_end":15,"highlight_start":12,"text":" let a: u32 = \"one\";"}]}],"code":{"code":"E0308","explanation":"Expected type did not match the received type.\n\nErroneous code examples:\n\n```compile_fail,E0308\nfn plus_one(x: i32) -> i32 {\n x + 1\n}\n\nplus_one(\"Not a number\");\n// ^^^^^^^^^^^^^^ expected `i32`, found `&str`\n\nif \"Not a bool\" {\n// ^^^^^^^^^^^^ expected `bool`, found `&str`\n}\n\nlet x: f32 = \"Not a float\";\n// --- ^^^^^^^^^^^^^ expected `f32`, found `&str`\n// |\n// expected due to this\n```\n\nThis error occurs when an expression was used in a place where the compiler\nexpected an expression of a different type. It can occur in several cases, the\nmost common being when calling a function and passing an argument which has a\ndifferent type than the matching type in the function declaration.\n"}}} +{"reason":"compiler-message","package_id":"path+file:///C:/Users/luisarandas/Desktop/github/dsh-plugins/packages/dsh-rust-dev/checks/fixtures/broken-crate#dsh-rust-dev-fixture-broken@0.0.0","manifest_path":"C:\\Users\\luisarandas\\Desktop\\github\\dsh-plugins\\packages\\dsh-rust-dev\\checks\\fixtures\\broken-crate\\Cargo.toml","target":{"kind":["lib"],"crate_types":["lib"],"name":"dsh_rust_dev_fixture_broken","src_path":"C:\\Users\\luisarandas\\Desktop\\github\\dsh-plugins\\packages\\dsh-rust-dev\\checks\\fixtures\\broken-crate\\src\\lib.rs","edition":"2021","doc":true,"doctest":true,"test":true},"message":{"rendered":"error[E0308]: mismatched types\n --> src\\lib.rs:13:18\n |\n13 | let b: u32 = \"two\";\n | --- ^^^^^ expected `u32`, found `&str`\n | |\n | expected due to this\n\n","$message_type":"diagnostic","children":[],"level":"error","message":"mismatched types","spans":[{"byte_end":449,"byte_start":444,"column_end":23,"column_start":18,"expansion":null,"file_name":"src\\lib.rs","is_primary":true,"label":"expected `u32`, found `&str`","line_end":13,"line_start":13,"suggested_replacement":null,"suggestion_applicability":null,"text":[{"highlight_end":23,"highlight_start":18,"text":" let b: u32 = \"two\";"}]},{"byte_end":441,"byte_start":438,"column_end":15,"column_start":12,"expansion":null,"file_name":"src\\lib.rs","is_primary":false,"label":"expected due to this","line_end":13,"line_start":13,"suggested_replacement":null,"suggestion_applicability":null,"text":[{"highlight_end":15,"highlight_start":12,"text":" let b: u32 = \"two\";"}]}],"code":{"code":"E0308","explanation":"Expected type did not match the received type.\n\nErroneous code examples:\n\n```compile_fail,E0308\nfn plus_one(x: i32) -> i32 {\n x + 1\n}\n\nplus_one(\"Not a number\");\n// ^^^^^^^^^^^^^^ expected `i32`, found `&str`\n\nif \"Not a bool\" {\n// ^^^^^^^^^^^^ expected `bool`, found `&str`\n}\n\nlet x: f32 = \"Not a float\";\n// --- ^^^^^^^^^^^^^ expected `f32`, found `&str`\n// |\n// expected due to this\n```\n\nThis error occurs when an expression was used in a place where the compiler\nexpected an expression of a different type. It can occur in several cases, the\nmost common being when calling a function and passing an argument which has a\ndifferent type than the matching type in the function declaration.\n"}}} +{"reason":"compiler-message","package_id":"path+file:///C:/Users/luisarandas/Desktop/github/dsh-plugins/packages/dsh-rust-dev/checks/fixtures/broken-crate#dsh-rust-dev-fixture-broken@0.0.0","manifest_path":"C:\\Users\\luisarandas\\Desktop\\github\\dsh-plugins\\packages\\dsh-rust-dev\\checks\\fixtures\\broken-crate\\Cargo.toml","target":{"kind":["lib"],"crate_types":["lib"],"name":"dsh_rust_dev_fixture_broken","src_path":"C:\\Users\\luisarandas\\Desktop\\github\\dsh-plugins\\packages\\dsh-rust-dev\\checks\\fixtures\\broken-crate\\src\\lib.rs","edition":"2021","doc":true,"doctest":true,"test":true},"message":{"rendered":"For more information about this error, try `rustc --explain E0308`.\n","$message_type":"diagnostic","children":[],"level":"failure-note","message":"For more information about this error, try `rustc --explain E0308`.","spans":[],"code":null}} +{"reason":"build-finished","success":false} diff --git a/packages/dsh-rust-dev/checks/fixtures/captured/cargo-metadata-nodeps.json b/packages/dsh-rust-dev/checks/fixtures/captured/cargo-metadata-nodeps.json new file mode 100644 index 0000000..335f23f --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/captured/cargo-metadata-nodeps.json @@ -0,0 +1 @@ +{"packages":[{"name":"dsh-rust-dev-fixture-broken","version":"0.0.0","id":"path+file:///C:/Users/luisarandas/Desktop/github/dsh-plugins/packages/dsh-rust-dev/checks/fixtures/broken-crate#dsh-rust-dev-fixture-broken@0.0.0","license":null,"license_file":null,"description":null,"source":null,"dependencies":[],"targets":[{"kind":["lib"],"crate_types":["lib"],"name":"dsh_rust_dev_fixture_broken","src_path":"C:\\Users\\luisarandas\\Desktop\\github\\dsh-plugins\\packages\\dsh-rust-dev\\checks\\fixtures\\broken-crate\\src\\lib.rs","edition":"2021","doc":true,"doctest":true,"test":true}],"features":{},"manifest_path":"C:\\Users\\luisarandas\\Desktop\\github\\dsh-plugins\\packages\\dsh-rust-dev\\checks\\fixtures\\broken-crate\\Cargo.toml","metadata":null,"publish":[],"authors":[],"categories":[],"keywords":[],"readme":null,"repository":null,"homepage":null,"documentation":null,"edition":"2021","links":null,"default_run":null,"rust_version":null}],"workspace_members":["path+file:///C:/Users/luisarandas/Desktop/github/dsh-plugins/packages/dsh-rust-dev/checks/fixtures/broken-crate#dsh-rust-dev-fixture-broken@0.0.0"],"workspace_default_members":["path+file:///C:/Users/luisarandas/Desktop/github/dsh-plugins/packages/dsh-rust-dev/checks/fixtures/broken-crate#dsh-rust-dev-fixture-broken@0.0.0"],"resolve":null,"target_directory":"C:\\Users\\LUISAR~1\\AppData\\Local\\Temp\\rustfix-414e9483e0d14f18af56a3dd95c02566\\target-meta","build_directory":"C:\\Users\\LUISAR~1\\AppData\\Local\\Temp\\rustfix-414e9483e0d14f18af56a3dd95c02566\\target-meta","version":1,"workspace_root":"C:\\Users\\luisarandas\\Desktop\\github\\dsh-plugins\\packages\\dsh-rust-dev\\checks\\fixtures\\broken-crate","metadata":null} diff --git a/packages/dsh-rust-dev/checks/fixtures/captured/cargo-test.txt b/packages/dsh-rust-dev/checks/fixtures/captured/cargo-test.txt new file mode 100644 index 0000000..eaf7460 --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/captured/cargo-test.txt @@ -0,0 +1,27 @@ + Compiling dsh-rust-dev-fixture-tests v0.0.0 (C:\Users\luisarandas\Desktop\github\dsh-plugins\packages\dsh-rust-dev\checks\fixtures\failing-test-crate) + Finished `test` profile [unoptimized + debuginfo] target(s) in 0.31s + Running unittests src\lib.rs (C:\Users\LUISAR~1\AppData\Local\Temp\rustfix-414e9483e0d14f18af56a3dd95c02566\target-tests\debug\deps\dsh_rust_dev_fixture_tests-69dd7b7520b1a2d3.exe) + +running 3 tests +test tests::ignored_one ... ignored +test tests::passes ... ok +test tests::fails ... FAILED + +failures: + +---- tests::fails stdout ---- +the fixture prints this line before failing + +thread 'tests::fails' (13632) panicked at src\lib.rs:19:9: +assertion `left == right` failed: the fixture asserts the wrong sum on purpose + left: 4 + right: 5 +note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace + + +failures: + tests::fails + +test result: FAILED. 1 passed; 1 failed; 1 ignored; 0 measured; 0 filtered out; finished in 0.00s + +error: test failed, to rerun pass `--lib` diff --git a/packages/dsh-rust-dev/checks/fixtures/failing-test-crate/Cargo.lock b/packages/dsh-rust-dev/checks/fixtures/failing-test-crate/Cargo.lock new file mode 100644 index 0000000..4edab7d --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/failing-test-crate/Cargo.lock @@ -0,0 +1,7 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "dsh-rust-dev-fixture-tests" +version = "0.0.0" diff --git a/packages/dsh-rust-dev/checks/fixtures/failing-test-crate/Cargo.toml b/packages/dsh-rust-dev/checks/fixtures/failing-test-crate/Cargo.toml new file mode 100644 index 0000000..d24ba47 --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/failing-test-crate/Cargo.toml @@ -0,0 +1,9 @@ +# Compiles cleanly and has a failing test: the INPUT the cargo-test fixture was +# captured from. Separate from broken-crate, which does not compile at all. +[package] +name = "dsh-rust-dev-fixture-tests" +version = "0.0.0" +edition = "2021" +publish = false + +[workspace] diff --git a/packages/dsh-rust-dev/checks/fixtures/failing-test-crate/src/lib.rs b/packages/dsh-rust-dev/checks/fixtures/failing-test-crate/src/lib.rs new file mode 100644 index 0000000..727adba --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/failing-test-crate/src/lib.rs @@ -0,0 +1,27 @@ +//! Compiles, and one test fails on purpose: fixture INPUT, not shipped behaviour. + +pub fn add(a: u32, b: u32) -> u32 { + a + b +} + +#[cfg(test)] +mod tests { + use super::add; + + #[test] + fn passes() { + assert_eq!(add(2, 2), 4); + } + + #[test] + fn fails() { + println!("the fixture prints this line before failing"); + assert_eq!(add(2, 2), 5, "the fixture asserts the wrong sum on purpose"); + } + + #[test] + #[ignore] + fn ignored_one() { + panic!("never runs"); + } +} diff --git a/packages/dsh-rust-dev/checks/fixtures/panic-crate/Cargo.lock b/packages/dsh-rust-dev/checks/fixtures/panic-crate/Cargo.lock new file mode 100644 index 0000000..13168a7 --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/panic-crate/Cargo.lock @@ -0,0 +1,7 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "dsh-rust-dev-fixture-panic" +version = "0.0.0" diff --git a/packages/dsh-rust-dev/checks/fixtures/panic-crate/Cargo.toml b/packages/dsh-rust-dev/checks/fixtures/panic-crate/Cargo.toml new file mode 100644 index 0000000..da8fe8a --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/panic-crate/Cargo.toml @@ -0,0 +1,8 @@ +# A crate that builds and then panics, so a real backtrace can be captured. +[package] +name = "dsh-rust-dev-fixture-panic" +version = "0.0.0" +edition = "2021" +publish = false + +[workspace] diff --git a/packages/dsh-rust-dev/checks/fixtures/panic-crate/src/main.rs b/packages/dsh-rust-dev/checks/fixtures/panic-crate/src/main.rs new file mode 100644 index 0000000..1ff638f --- /dev/null +++ b/packages/dsh-rust-dev/checks/fixtures/panic-crate/src/main.rs @@ -0,0 +1,12 @@ +//! Builds cleanly and panics at runtime, on purpose: the backtrace fixture's INPUT. + +pub fn inner(depth: u32) -> u32 { + if depth == 0 { + panic!("the fixture panics here on purpose"); + } + inner(depth - 1) +} + +fn main() { + println!("{}", inner(2)); +} diff --git a/packages/dsh-rust-dev/cordis.patch.yml b/packages/dsh-rust-dev/cordis.patch.yml new file mode 100644 index 0000000..a699f14 --- /dev/null +++ b/packages/dsh-rust-dev/cordis.patch.yml @@ -0,0 +1,31 @@ +# dsh-rust-dev bundle layer (alpha). +# +# One row ('rust-dev') owns the whole plugin: its Node half registers SIX tools +# over the machine's own Rust toolchain - `rust_status` (the four facts that fail +# independently: toolchain, components, installed targets, the workspace), +# `cargo_check` (diagnostics parsed from `--message-format=json`, with codes and +# file:line:column, duplicates collapsed), `cargo_test` (the summary, the failing +# names, the first failure's captured output), `cargo_build` (the artifact path +# and its real size, and a binary run only when asked), `rust_deps` (duplicate +# crate versions, the weight, and the feature chain that enabled one crate) and +# `rust_backtrace` (demangled frames, classed into your code, a dependency or the +# runtime) - plus four bundled skills: workspaces, diagnostics, debugging, and +# egui/eframe/wgpu apps. +# +# Host-only: the answer is prose and numbers, so there is no route to serve and no +# browser half to load - the package declares no dsh.client, and the boot graph +# gains one row. Like dsh-sql-server and dsh-ollama, not like dsh-docker. +# +# Nothing shipped is patched and no core row is disabled: core DSH has no Rust +# surface, and its `bash` / `pwsh` tools can run `cargo` but cannot tell a reader +# which of six distinct diagnostics is behind eleven hundred lines, that a crate +# is compiled twice, or which backtrace frames are the caller's own. +# +# Nothing for scripts/sync-vendored.ps1 either: no engine is vendored, forked or +# downloaded. `cargo`, `rustc` and `rustup` are the user's own programs on PATH; +# this package ships the parsers, the argv, and the triage order. Every cargo call +# is `--offline` until the caller passes `fetch: true`, so the row starts no +# network egress of its own. +- insert: + - id: rust-dev + name: 'dsh-rust-dev' diff --git a/packages/dsh-rust-dev/lib/backtrace.js b/packages/dsh-rust-dev/lib/backtrace.js new file mode 100644 index 0000000..2572570 --- /dev/null +++ b/packages/dsh-rust-dev/lib/backtrace.js @@ -0,0 +1,180 @@ +/** + * dsh-rust-dev — a Rust backtrace, read properly. + * + * Two things make a raw backtrace useless to a reader: + * + * 1. **Mangled names.** `_ZN4core3ptr13drop_in_place17h3f2a…E` is a name only a + * linker loves. The legacy mangling is a length-prefixed path, so it can be + * decoded exactly - no external `rustfilt` needed. The v0 mangling (`_R…`) + * is a different grammar and is NOT decoded here; saying so is better than + * producing a plausible wrong name. + * 2. **Depth.** A panic in `main` still emits sixty frames of `std`. What a + * reader needs is which frames are THEIR crate, which are a dependency, and + * which are the runtime - so frames are classified by path, and the answer + * names the first frame in the workspace. + * + * No network, no symbol server, no `addr2line`: the paths are already in the text + * when debug info is present, and when it is not, the answer says that instead of + * guessing. + */ + +/** Decode the LEGACY Rust mangling (`_ZN…E`). Returns the input unchanged when it is not that. */ +export function demangle(symbol) { + let text = String(symbol ?? '').trim() + if (text === '') return text + // A trailing `.llvm.123456` is a thin-LTO suffix, not part of the name. + const llvm = /\.llvm\.[0-9a-fA-F]+$/.exec(text) + if (llvm !== null) text = text.slice(0, llvm.index) + if (!text.startsWith('_ZN')) { + // v0 mangling is a different grammar: refuse to invent a name for it. + return text + } + if (!text.endsWith('E')) return text + const body = text.slice(3, -1) + const segments = [] + let index = 0 + while (index < body.length) { + const digits = /^[0-9]+/.exec(body.slice(index)) + if (digits === null) return text + const length = Number.parseInt(digits[0], 10) + const start = index + digits[0].length + const segment = body.slice(start, start + length) + if (segment.length !== length) return text + segments.push(segment) + index = start + length + } + if (segments.length === 0) return text + // The last segment is `h<16 hex>`: a disambiguating hash, never a path element. + const last = segments[segments.length - 1] + if (/^h[0-9a-f]{16}$/.test(last)) segments.pop() + const cleaned = segments.map((segment) => segment.replace(/^_+/, '').replace(/^<(.+)>$/, '$1')).filter((segment) => segment !== '') + return cleaned.length === 0 ? text : cleaned.join('::') +} + +/** Is this `_R…` (the v0 mangling this module deliberately does not decode)? */ +export function isV0(symbol) { + return /^_R[A-Za-z0-9_]*$/.test(String(symbol ?? '').trim()) +} + +/** + * Resolve a frame's path against the directory the process ran in. + * + * Cargo prints crate-relative frames (`.\src\main.rs`) when it can, so a frame is + * only classifiable after it is made absolute. The `cwd` here is the workspace + * root when the caller ran cargo there, which is the normal case. + */ +export function resolveFramePath(file, cwd) { + const raw = String(file ?? '').replace(/\\/g, '/') + if (raw === '') return '' + const isAbsolute = /^[A-Za-z]:\//.test(raw) || raw.startsWith('/') + if (isAbsolute) return raw + const base = String(cwd ?? '').replace(/\\/g, '/').replace(/\/$/, '') + if (base === '') return raw.replace(/^\.\//, '') + return base + '/' + raw.replace(/^\.\//, '') +} + +/** + * Which part of the system a frame belongs to. + * + * The distinction that matters: `workspace` frames are the caller's code and the + * only ones they can change; `dependency` frames are a crate they did not write; + * `std` frames are the runtime's own unwind machinery. + */ +export function classifyFrame(file, root, cwd) { + const normalized = resolveFramePath(file, cwd) + if (normalized === '') return 'unknown' + const base = root === null || root === undefined ? '' : String(root).replace(/\\/g, '/').replace(/\/$/, '') + '/' + if (base !== '' && normalized.toLowerCase().startsWith(base.toLowerCase())) return 'workspace' + if (/\/\.cargo\/registry\/src\//.test(normalized) || /\/registry\/src\//.test(normalized)) return 'dependency' + if (/\/rustc\/[0-9a-f]+\//.test(normalized) || /\/rustlib\/src\/rust\/library\//.test(normalized) || /\/library\/(std|core|alloc)\//.test(normalized)) return 'std' + return 'unknown' +} + +/** + * Parse a captured backtrace. + * + * A Rust backtrace is a list of ` 12: symbol` lines, each optionally followed by + * ` at path:line:col`. Anything before the first numbered frame is the + * panic message; a `note: run with RUST_BACKTRACE=1` line means there are no + * frames to read at all. + * + * @param text - the captured stderr (or a file's contents). + * @param options - `{ root }`, the workspace root used to classify frames. + * @returns `{ panic, note, frames, truncated, v0Count }`. + */ +export function parseBacktrace(text, options = {}) { + const lines = String(text ?? '').replace(/\r\n?/g, '\n').split('\n') + const frames = [] + let panic = '' + let note = '' + let v0Count = 0 + let current = null + const framePattern = /^\s*(\d+):\s+(.+?)\s*$/ + // `path:line:col`, and also `path:line` - Rust prints the short form when it has + // no column (a `cargo run` frame is exactly that: `at .\src\main.rs:5`). + const atPattern = /^\s+at\s+(.+?)(?::(\d+))(?::(\d+))?\s*$/ + const bareAt = /^\s+at\s+(.+?)\s*$/ + for (const line of lines) { + if (line.startsWith('thread ') && line.includes('panicked at')) { + panic = line.trim() + continue + } + if (note === '' && /^note: run with `RUST_BACKTRACE=/.test(line.trim())) { + note = line.trim() + continue + } + const frame = framePattern.exec(line) + if (frame !== null) { + const symbol = frame[2] + if (isV0(symbol)) v0Count += 1 + current = { index: Number(frame[1]), symbol, name: demangle(symbol), file: '', line: 0, column: 0, kind: 'unknown' } + frames.push(current) + continue + } + if (current === null) continue + const at = atPattern.exec(line) + if (at !== null) { + current.file = at[1] + current.line = Number(at[2]) + current.column = at[3] === undefined ? 0 : Number(at[3]) + current.kind = classifyFrame(at[1], options.root, options.cwd ?? options.root) + continue + } + const pathOnly = bareAt.exec(line) + if (pathOnly !== null) { + current.file = pathOnly[1] + current.kind = classifyFrame(pathOnly[1], options.root, options.cwd ?? options.root) + } + } + return { panic, note, frames, truncated: false, v0Count } +} + +/** + * The sentence a reader needs: where it broke, and whose code that is. + * + * @param parsed - the result of `parseBacktrace`. + * @returns `{ kind, frame, text }` where `kind` is `workspace` | `dependency` | + * `runtime` | `no-frames`. + */ +export function verdictOf(parsed) { + const first = parsed.frames.find((frame) => frame.kind === 'workspace') + if (first !== undefined) { + return { kind: 'workspace', frame: first, text: 'the first frame in YOUR code is ' + frameLabel(first) } + } + const dependency = parsed.frames.find((frame) => frame.kind === 'dependency') + if (dependency !== undefined) { + return { kind: 'dependency', frame: dependency, text: 'no frame in your workspace: the panic surfaces from ' + frameLabel(dependency) + ', which is a dependency' } + } + if (parsed.frames.length === 0) { + const why = parsed.note !== '' ? ' the backtrace was not enabled for that run' : ' the binary carries no debug info, or the panic was caught before it printed' + return { kind: 'no-frames', frame: null, text: 'no frames to read:' + why + '.' } + } + return { kind: 'runtime', frame: parsed.frames[0], text: 'every frame is the runtime or unknown: ' + frameLabel(parsed.frames[0]) } +} + +/** `crate::module::fn (file:line)` - the label a reader can act on. */ +export function frameLabel(frame) { + if (frame === null || frame === undefined) return '' + const where = frame.file === '' ? '' : ' (' + frame.file + (frame.line > 0 ? ':' + frame.line : '') + ')' + return (frame.name || frame.symbol) + where +} diff --git a/packages/dsh-rust-dev/lib/cli.js b/packages/dsh-rust-dev/lib/cli.js new file mode 100644 index 0000000..31bca25 --- /dev/null +++ b/packages/dsh-rust-dev/lib/cli.js @@ -0,0 +1,123 @@ +/** + * dsh-rust-dev — one bounded child process, argv only. + * + * Every process this row starts goes through here, for four reasons that are + * rules rather than preferences: + * + * 1. **argv, never a shell.** A crate name, a path or a `--` argument that + * arrived from a model must not be re-parsed by cmd.exe or sh. + * 2. **A deadline.** `cargo` compiles dependencies, and a compile can take + * minutes or hang on a build script. A call with no deadline is a call that + * owns the harness' event loop. + * 3. **A byte ceiling.** A failing workspace build is megabytes of compiler + * output; the cap is what keeps one bad call from filling the context. + * 4. **A tree kill.** `cargo build` spawns rustc children. Killing the parent + * alone leaves them writing into `target/`, so on a timeout the whole tree + * goes - `taskkill /T` on Windows, a process-group kill elsewhere. + * + * Truncation is REPORTED, never silent: an answer that quietly dropped half the + * diagnostics would be worse than a timeout. + */ + +import { spawn } from 'node:child_process' + +/** Kill a child and everything it started. */ +export function killTree(child) { + if (child === null || child === undefined || child.exitCode !== null || child.signalCode !== null) return + if (process.platform === 'win32' && Number.isInteger(child.pid)) { + try { + spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }) + return + } catch (error) { + /* fall through to kill() */ + } + } + try { + child.kill('SIGKILL') + } catch (error) { + /* already gone */ + } +} + +/** + * Run one argv array and collect its output. + * + * @param argv - the program and its arguments, one element each; never a string. + * @param options - `{ cwd, timeoutMs, maxBytes, env }`. + * @returns `{ status, stdout, stderr, timedOut, truncated, error, elapsedMs }`; + * `status` is null when the program could not start at all. + */ +export function runArgv(argv, options = {}) { + const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 60_000 + const maxBytes = Number.isFinite(options.maxBytes) && options.maxBytes > 0 ? options.maxBytes : 2_000_000 + const startedAt = Date.now() + return new Promise((resolve) => { + let settled = false + let timedOut = false + let truncated = false + let stdout = '' + let stderr = '' + const finish = (result) => { + if (settled) return + settled = true + resolve({ timedOut, truncated, elapsedMs: Date.now() - startedAt, ...result }) + } + let child + try { + child = spawn(argv[0], argv.slice(1), { + cwd: options.cwd, + stdio: ['ignore', 'pipe', 'pipe'], + windowsHide: true, + env: options.env ?? process.env, + }) + } catch (error) { + finish({ status: null, stdout: '', stderr: '', error: error && error.message ? String(error.message) : String(error) }) + return + } + const timer = setTimeout(() => { + timedOut = true + killTree(child) + }, timeoutMs) + const take = (current, chunk) => { + if (current.length >= maxBytes) { + truncated = true + return current + } + const room = maxBytes - current.length + if (chunk.length > room) { + truncated = true + return current + chunk.slice(0, room) + } + return current + chunk + } + child.stdout?.setEncoding('utf8') + child.stderr?.setEncoding('utf8') + child.stdout?.on('data', (chunk) => { + stdout = take(stdout, chunk) + }) + child.stderr?.on('data', (chunk) => { + stderr = take(stderr, chunk) + }) + child.on('error', (error) => { + clearTimeout(timer) + finish({ status: null, stdout, stderr, error: error && error.message ? String(error.message) : String(error) }) + }) + child.on('close', (code) => { + clearTimeout(timer) + finish({ status: code, stdout, stderr }) + }) + }) +} + +/** + * The first line of a program's `--version`, which is all a version probe needs. + * + * @param argv - the program and its version flag. + * @returns the line, or `''` when the program is missing or printed nothing. + */ +export async function versionLine(argv, options = {}) { + const result = await runArgv(argv, { timeoutMs: 15_000, maxBytes: 64_000, ...options }) + if (result.status === null) return '' + const text = String(result.stdout || result.stderr || '').trim() + return text.split('\n')[0].trim() +} diff --git a/packages/dsh-rust-dev/lib/diagnostics.js b/packages/dsh-rust-dev/lib/diagnostics.js new file mode 100644 index 0000000..7830529 --- /dev/null +++ b/packages/dsh-rust-dev/lib/diagnostics.js @@ -0,0 +1,174 @@ +/** + * dsh-rust-dev — `cargo --message-format=json`, parsed rather than grepped. + * + * The human output is prose for a person at a terminal: wrapped, coloured, and + * re-flowed whenever rustc changes its renderer. The JSON stream is the stable + * contract, and it carries the two things a reader actually needs - the + * diagnostic CODE (`E0308`) and the primary SPAN as file/line/column - so this + * module never regexes a rendered message. + * + * Deduplication matters as much as parsing: one type error in a widely used + * function is reported once per call site, and a list of forty identical + * `E0308`s hides the four distinct mistakes inside it. Items are keyed by + * code + message + primary location, and a repeat is counted, not repeated. + */ + +/** A one-line meaning for the codes a Rust developer meets weekly. */ +export const CODE_HINTS = { + E0308: 'mismatched types', + E0277: 'a trait bound is not satisfied', + E0382: 'use of a moved value', + E0502: 'cannot borrow as mutable: also borrowed as immutable', + E0499: 'two mutable borrows at once', + E0505: 'cannot move out: borrowed', + E0597: 'a borrowed value does not live long enough', + E0515: 'returning a reference to a local', + E0061: 'wrong number of arguments', + E0432: 'unresolved import', + E0433: 'failed to resolve: a path that does not exist', + E0412: 'a type name is not in scope', + E0658: 'an unstable feature was used', + E0603: 'a private item was used', + E0133: 'unsafe operation outside an unsafe block', + E0004: 'non-exhaustive match', + E0015: 'a non-const call in a const context', + E0463: 'a crate is not available for this target', + E0464: 'a crate resolved to conflicting candidates', +} + +/** + * Parse the stdout of a `--message-format=json` invocation. + * + * Cargo interleaves `compiler-artifact`, `compiler-message`, `build-script-executed` + * and a final `build-finished`. Lines that are not JSON are counted and dropped - + * a build script is allowed to print anything, and one stray line must not lose + * the diagnostics. + * + * @param stdout - the child's stdout. + * @returns `{ events, messages, artifacts, finished, noise }`. + */ +export function parseJsonStream(stdout) { + const events = [] + const noise = [] + for (const line of String(stdout ?? '').split('\n')) { + const trimmed = line.trim() + if (trimmed === '' || trimmed[0] !== '{') { + if (trimmed !== '') noise.push(trimmed) + continue + } + try { + events.push(JSON.parse(trimmed)) + } catch (error) { + noise.push(trimmed) + } + } + const messages = events.filter((event) => event && event.reason === 'compiler-message' && event.message) + const artifacts = events.filter((event) => event && event.reason === 'compiler-artifact') + const finished = events.find((event) => event && event.reason === 'build-finished') ?? null + return { events, messages, artifacts, finished, noise } +} + +/** The primary span of a diagnostic, falling back to its first span. */ +export function primarySpan(message) { + const spans = Array.isArray(message.spans) ? message.spans : [] + return spans.find((span) => span && span.is_primary) ?? spans[0] ?? null +} + +/** + * Turn compiler messages into a list a caller can act on. + * + * `level` follows rustc: `error`, `warning`, `note`, `help`. Only messages that + * carry a span are listed as items; a spanless `error: could not compile` is a + * summary, and it is counted separately so it does not pretend to be a location. + * + * @param messages - `compiler-message` events. + * @param options - `{ limit }`, the number of items to return (counts are always total). + */ +export function summarizeDiagnostics(messages, options = {}) { + const limit = Number.isFinite(options.limit) && options.limit > 0 ? options.limit : 20 + const items = new Map() + const counts = { error: 0, warning: 0, note: 0, help: 0, other: 0 } + const spanless = [] + for (const event of messages) { + const message = event.message + const level = String(message.level ?? 'other') + const text = String(message.message ?? '').split('\n')[0].trim() + // Cargo's own summary lines are `error`-level and spanless: `aborting due to 3 + // previous errors` and `could not compile …`. Counting them as errors makes a + // 3-error build report 4, which is exactly the kind of number a reader stops + // trusting. They are kept as prose, never as counts. + const isSummary = /^aborting due to\b/.test(text) || /^could not compile\b/.test(text) + if (!isSummary) { + if (Object.prototype.hasOwnProperty.call(counts, level)) counts[level] += 1 + else counts.other += 1 + } + // `failure-note` and the summaries arrive spanless; keep the text. + if (level !== 'error' && level !== 'warning') { + if (level === 'failure-note' || level === 'error: internal compiler error') spanless.push(text) + continue + } + if (isSummary) { + spanless.push(text) + continue + } + const code = message.code && typeof message.code.code === 'string' ? message.code.code : '' + const span = primarySpan(message) + if (span === null || !span.file_name) { + spanless.push((code ? code + ': ' : '') + text) + continue + } + const key = [level, code, text, span.file_name, span.line_start, span.column_start].join('\u0000') + const existing = items.get(key) + if (existing !== undefined) { + existing.repeat += 1 + continue + } + items.set(key, { + level, + code, + hint: CODE_HINTS[code] ?? '', + message: text, + file: String(span.file_name), + line: Number(span.line_start ?? 0), + column: Number(span.column_start ?? 0), + repeat: 1, + }) + } + const ordered = [...items.values()].sort((a, b) => { + if (a.level !== b.level) return a.level === 'error' ? -1 : 1 + if (a.file !== b.file) return a.file < b.file ? -1 : 1 + return a.line - b.line + }) + const errorItems = ordered.filter((entry) => entry.level === 'error') + const warningItems = ordered.filter((entry) => entry.level === 'warning') + const byCode = {} + for (const entry of ordered) { + if (entry.code === '') continue + byCode[entry.code] = (byCode[entry.code] ?? 0) + 1 + } + return { + counts, + // `errors`/`warnings` are the MESSAGE counts; the arrays are deduplicated items. + distinct: { errors: errorItems.length, warnings: warningItems.length }, + byCode, + items: ordered.slice(0, limit), + shownErrors: errorItems.slice(0, limit), + shownWarnings: warningItems.slice(0, limit), + hidden: Math.max(0, ordered.length - limit), + spanless: spanless.slice(0, 5), + } +} + +/** The first `path:line:col` a diagnostic names, for one-line summaries. */ +export function firstLocation(summary) { + const item = summary.items[0] + return item === undefined ? '' : item.file + ':' + item.line + ':' + item.column +} + +/** A compact `file:line` for a frame or an item, with the workspace prefix trimmed. */ +export function shortPath(file, root) { + const normalized = String(file).replace(/\\/g, '/') + if (!root) return normalized + const base = String(root).replace(/\\/g, '/').replace(/\/$/, '') + '/' + return normalized.startsWith(base) ? normalized.slice(base.length) : normalized +} diff --git a/packages/dsh-rust-dev/lib/index.js b/packages/dsh-rust-dev/lib/index.js new file mode 100644 index 0000000..d4db123 --- /dev/null +++ b/packages/dsh-rust-dev/lib/index.js @@ -0,0 +1,183 @@ +/** + * dsh-rust-dev — Node half. + * + * One row, six tools, no browser surface and no route. "What does this workspace + * need, and why did it break" is a host question whose answer is prose and + * numbers, so there is nothing for the right bar to draw - the same shape as + * `dsh-sql-server` and `dsh-ollama`, not like `dsh-docker`. + * + * WHY IT EXISTS: every harness can already RUN `cargo`. What none of them can do + * is hand a reader the SHAPE of the failure - six distinct diagnostics instead of + * eleven hundred lines, the four facts that fail independently on a Rust machine, + * the crate that is compiled twice, or which frames of a backtrace are the + * caller's own. That is what this row is for, and it is why the skills ship with + * it: the tools answer, the skills teach the triage order. + * + * WHAT IT IS NOT: not a toolchain installer (no `rustup toolchain install`, no + * `cargo install` - it prints the command), not a registry client (every cargo + * call is `--offline` until the caller passes `fetch: true`), not a language + * server (rust-analyzer is reported by `rust_status`, never driven), and not a + * replacement for the harness's own shell. + * + * Zero npm dependencies, nothing bundled, no network egress of its own: cargo, + * rustc and rustup are the user's own programs. + */ + +import { readFileSync } from 'node:fs' +import path from 'node:path' +import { fileURLToPath } from 'node:url' + +import { buildTools, LIMITS } from './tools.js' + +export const name = 'dsh-rust-dev' +export const inject = ['tools'] + +/** Kept in step with package.json. */ +export const PLUGIN_VERSION = '0.1.0-alpha.1' + +/** The four skills, as files beside this module. */ +export const SKILL_FILES = [ + { name: 'rust-workspaces', file: '../skills/rust-workspaces/SKILL.md' }, + { name: 'rust-diagnostics', file: '../skills/rust-diagnostics/SKILL.md' }, + { name: 'rust-debugging', file: '../skills/rust-debugging/SKILL.md' }, + { name: 'rust-ui-apps', file: '../skills/rust-ui-apps/SKILL.md' }, +] + +/** What this row offers, for the README and the package check. */ +export const CAPABILITIES = { + tools: ['rust_status', 'cargo_check', 'cargo_test', 'cargo_build', 'rust_deps', 'rust_backtrace'], + skills: SKILL_FILES.map((entry) => entry.name), + limits: { ...LIMITS }, + notBuilt: [ + 'installing a toolchain, a component or a crate', + 'fetching from the registry unless the caller passes fetch: true', + 'driving rust-analyzer as a language server', + 'cargo publish / any registry write', + 'a UI tab (host-only row)', + ], +} + +/** + * The row's dependencies, one per boot. + * + * `cwd` and `runner` are injectable so the package check can drive the tools in a + * fixture workspace without chdir, and `log` is injectable so a check can assert + * what the activation line said. + * + * @param ctx - the plugin context (inject: tools). + * @param options - `{ cwd, env, log }`. + */ +export function createDeps(ctx, options = {}) { + return { + ctx, + cwd: options.cwd ?? process.cwd(), + env: options.env ?? process.env, + log: options.log ?? { + warn: (text) => ctx.logger?.warn?.('[dsh-rust-dev] ' + text), + info: (text) => ctx.logger?.info?.('[dsh-rust-dev] ' + text), + }, + } +} + +/** + * The one activation line. + * + * It probes NOTHING: a `cargo --version` per harness start is a child process + * nobody asked for, and a machine without a toolchain would print the same line + * either way. `rust_status` is the tool that asks. + */ +export function activationLine() { + return ( + 'active: six rust_* / cargo_* tools over this machine\'s own cargo, rustc and rustup, plus four skills; ' + + 'nothing is built, fetched or installed until a tool is called - ask `rust_status` first' + ) +} + +// --------------------------------------------------------------------------- +// Skills +// --------------------------------------------------------------------------- +/** Split one skill document into its frontmatter and its body. */ +export function parseSkillFile(text) { + const normalized = String(text).replace(/\r\n?/g, '\n') + const match = /^---\n([\s\S]*?)\n---\n?/.exec(normalized) + if (!match) return { meta: {}, content: normalized.trim() } + const meta = {} + for (const line of match[1].split('\n')) { + const entry = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(line) + if (!entry) continue + let value = entry[2].trim() + if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1) + meta[entry[1]] = value + } + return { meta, content: normalized.slice(match[0].length).trim() } +} + +/** Register the bundled skills; a missing registry skips the skills, never the tools. */ +export function registerSkills(ctx, log) { + const skills = typeof ctx.get === 'function' ? ctx.get('skills') : undefined + if (skills === null || skills === undefined || typeof skills.register !== 'function') { + log.warn('skill registry unavailable - the four bundled rust skills were not registered') + return 0 + } + let count = 0 + for (const entry of SKILL_FILES) { + try { + const file = fileURLToPath(new URL(entry.file, import.meta.url)) + const { meta, content } = parseSkillFile(readFileSync(file, 'utf8')) + if (content.length === 0) { + log.warn('skill file is empty: ' + entry.file) + continue + } + const skillName = typeof meta.name === 'string' && meta.name.length > 0 ? meta.name : entry.name + ctx.effect( + () => + skills.register({ + name: skillName, + description: typeof meta.description === 'string' ? meta.description : '', + whenToUse: typeof meta.whenToUse === 'string' ? meta.whenToUse : undefined, + content, + provider: 'dsh-rust-dev', + source: 'bundled', + path: file, + resourceBase: { kind: 'directory', path: path.dirname(file) }, + }), + 'dsh-rust-dev: skill ' + skillName, + ) + count += 1 + } catch (err) { + log.warn('could not register skill ' + entry.name + ': ' + (err && err.message ? err.message : String(err))) + } + } + return count +} + +// --------------------------------------------------------------------------- +// Activation +// --------------------------------------------------------------------------- +/** + * Activate the row. + * + * @param ctx - cordis context (inject: tools). + */ +export function apply(ctx) { + const deps = createDeps(ctx) + deps.log.info(activationLine()) + const skillCount = registerSkills(ctx, deps.log) + deps.log.info('registered ' + skillCount + ' bundled skill(s)') + for (const tool of buildTools(deps)) { + ctx.effect(() => ctx.tools.register(tool), 'dsh-rust-dev: tool ' + tool.name) + } +} + +/** Exported for the tracked checks: the parts of this row worth driving directly. */ +export const __internals = { + buildTools, + createDeps, + registerSkills, + parseSkillFile, + activationLine, + CAPABILITIES, + PLUGIN_VERSION, + SKILL_FILES, + LIMITS, +} diff --git a/packages/dsh-rust-dev/lib/metadata.js b/packages/dsh-rust-dev/lib/metadata.js new file mode 100644 index 0000000..33bed29 --- /dev/null +++ b/packages/dsh-rust-dev/lib/metadata.js @@ -0,0 +1,163 @@ +/** + * dsh-rust-dev — the dependency graph, from `cargo metadata`. + * + * Three questions this row exists to answer, none of which a person asks of a + * terminal happily: + * + * 1. **Which crate is compiled twice?** Two semver-incompatible versions of + * `syn` are legal, common, and invisible until you look - and they cost + * compile time and binary size while making a trait mismatch between the + * two copies impossible to read. + * 2. **What pulls the heavy thing in?** `rust_deps` reports the most-depended-on + * crates, so "why is openssl in my tree" starts from a name. + * 3. **Which feature enabled this?** Features unify across the whole graph, so + * a crate you never mentioned can arrive with `default` features on. The + * chain is `cargo tree -e features -i `, which is a separate call. + * + * `cargo metadata` (WITH dependencies) needs a resolve, and a resolve needs the + * registry. It therefore runs `--offline`: when the lockfile and the on-disk + * cache can answer, they do; when they cannot, the caller is told to fetch + * explicitly rather than having a download started on their behalf. + */ + +/** + * Read the resolved graph out of `cargo metadata` output. + * + * @param metadata - the parsed JSON document (with `resolve`). + * @returns a compact model: packages by id, edges, workspace set. + */ +export function graphOf(metadata) { + const packages = new Map() + for (const entry of metadata.packages ?? []) { + packages.set(entry.id, { + id: entry.id, + name: String(entry.name ?? ''), + version: String(entry.version ?? ''), + source: entry.source === null || entry.source === undefined ? 'workspace' : String(entry.source), + manifestPath: String(entry.manifest_path ?? ''), + }) + } + const nodes = Array.isArray(metadata.resolve?.nodes) ? metadata.resolve.nodes : [] + const edges = new Map() + const reverse = new Map() + for (const node of nodes) { + const from = packages.get(node.id) + if (from === undefined) continue + const targets = [] + for (const dep of node.deps ?? []) { + const to = packages.get(dep.pkg) + if (to === undefined) continue + targets.push(to.id) + const list = reverse.get(to.id) ?? [] + list.push({ id: from.id, name: from.name }) + reverse.set(to.id, list) + } + edges.set(node.id, targets) + } + const members = new Set(metadata.workspace_members ?? []) + return { packages, nodes, edges, reverse, members } +} + +/** + * Crates present at more than one version, with who depends on each copy. + * + * A duplicate is only worth reporting for a real dependency: two workspace + * members of the same name cannot happen, and a path dependency beside a + * registry one is a different (and rarer) story that the `source` field tells. + */ +export function duplicateVersions(graph) { + const byName = new Map() + for (const entry of graph.packages.values()) { + if (entry.source === 'workspace') continue + const list = byName.get(entry.name) ?? [] + list.push(entry) + byName.set(entry.name, list) + } + const result = [] + for (const [name, entries] of byName) { + const versions = [...new Set(entries.map((entry) => entry.version))] + if (versions.length < 2) continue + result.push({ + name, + versions: versions.sort(compareVersions).map((version) => { + const copies = entries.filter((entry) => entry.version === version) + const users = new Set() + for (const copy of copies) { + for (const user of graph.reverse.get(copy.id) ?? []) users.add(user.name) + } + return { version, usedBy: [...users].sort() } + }), + }) + } + return result.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) +} + +/** Sort two semver strings by their numeric parts, never lexically. */ +export function compareVersions(a, b) { + const parse = (value) => String(value).split(/[.\-+]/).slice(0, 3).map((part) => Number.parseInt(part, 10) || 0) + const [a1, a2, a3] = parse(a) + const [b1, b2, b3] = parse(b) + return a1 - b1 || a2 - b2 || a3 - b3 +} + +/** + * The crates the most other crates depend on - where the weight is. + * + * Counted over REGISTRY crates only: a workspace member appears once in the + * reverse index per dependent and would dominate for no useful reason. + */ +export function mostDependedOn(graph, limit = 10) { + const counts = [] + for (const entry of graph.packages.values()) { + if (entry.source === 'workspace') continue + const users = graph.reverse.get(entry.id) ?? [] + if (users.length === 0) continue + counts.push({ name: entry.name, version: entry.version, dependents: users.length, sample: users.slice(0, 3).map((user) => user.name) }) + } + return counts.sort((a, b) => b.dependents - a.dependents || (a.name < b.name ? -1 : 1)).slice(0, limit) +} + +/** The workspace members' direct dependencies, by name, with the requirement. */ +export function declaredDependencies(metadata) { + const members = new Set(metadata.workspace_members ?? []) + const declared = new Map() + for (const entry of metadata.packages ?? []) { + if (!members.has(entry.id)) continue + for (const dep of entry.dependencies ?? []) { + const name = String(dep.name ?? '') + if (name === '' || declared.has(name)) continue + declared.set(name, { name, req: String(dep.req ?? ''), kind: String(dep.kind ?? 'normal'), optional: dep.optional === true }) + } + } + return declared +} + +/** How many packages, edges and workspace members the resolve holds. */ +export function graphSize(graph) { + let edgeCount = 0 + for (const targets of graph.edges.values()) edgeCount += targets.length + return { packages: graph.packages.size, edges: edgeCount, members: graph.members.size } +} + +/** + * Parse the bounded text of `cargo tree -e features -i `. + * + * The tree is indentation and `──` glyphs; what matters is the chain of crate + * names and the `feature "x"` / `feature "x" implies y` lines under each. Rather + * than a full parser, the lines are kept verbatim (they are already the answer) + * and the count of distinct features is derived. + * + * @param text - the child's stdout. + * @returns `{ lines, features, truncatedLines }`. + */ +export function featureChain(text, maxLines = 40) { + const lines = String(text ?? '') + .split('\n') + .map((line) => line.replace(/\s+$/, '')) + .filter((line) => line !== '') + const features = new Set() + for (const line of lines) { + for (const match of line.matchAll(/feature "([^"]+)"/g)) features.add(match[1]) + } + return { lines: lines.slice(0, maxLines), features: [...features].sort(), truncatedLines: Math.max(0, lines.length - maxLines) } +} diff --git a/packages/dsh-rust-dev/lib/probe.js b/packages/dsh-rust-dev/lib/probe.js new file mode 100644 index 0000000..ded3ed1 --- /dev/null +++ b/packages/dsh-rust-dev/lib/probe.js @@ -0,0 +1,210 @@ +/** + * dsh-rust-dev — the four facts that fail independently. + * + * "Rust is broken on this machine" is almost never one thing. It is one of: + * + * - the TOOLCHAIN: no `cargo`, or a `rustup` default that is not the one you + * think (a project pinning a toolchain file silently switches it); + * - the COMPONENTS: `clippy` or `rustfmt` were never added, so the answer rests + * on a tool that is not there; + * - the TARGETS: a cross-compile to a triple nobody added fails at link time + * with an error that names the linker, not the missing target; + * - the WORKSPACE: no `Cargo.toml` here, or one whose `rust-version` is above + * the installed toolchain. + * + * They fail independently, so they are reported independently - the shape + * `dsh-sql-server` uses for server/client/port/driver, for the same reason. + * + * Nothing here builds. Every fact comes from a version probe, `rustup component + * list`, or `cargo metadata --no-deps`, which reads manifests only: no registry, + * no network, no compilation. + */ + +import fs from 'node:fs' +import path from 'node:path' + +import { runArgv, versionLine } from './cli.js' + +/** Crates worth naming when a workspace declares them, because they change the advice. */ +export const NOTABLE = { + eframe: 'an eframe app (egui desktop shell)', + egui: 'egui immediate-mode UI', + wgpu: 'wgpu: a GPU backend you own', + winit: 'winit: the window/event loop under an egui app', + tokio: 'tokio async runtime', + tracing: 'tracing: structured spans rather than println!', + serde: 'serde: derive-heavy, a big compile-time cost', + clap: 'clap: a CLI', + tauri: 'Tauri: a webview app, not egui', + bevy: 'bevy: an ECS game/app engine', + criterion: 'criterion benchmarks', +} + +/** Walk up from `start` looking for a directory that holds a `Cargo.toml`. */ +export function findManifest(start) { + let current = path.resolve(start) + for (;;) { + const candidate = path.join(current, 'Cargo.toml') + if (fs.existsSync(candidate)) return { root: current, manifest: candidate } + const parent = path.dirname(current) + if (parent === current) return null + current = parent + } +} + +/** Is a program on PATH? No shell, no `where`/`which` child: PATHEXT is the rule on Windows. */ +export function whichSync(name, env = process.env) { + const pathValue = env.PATH ?? env.Path ?? '' + const segments = pathValue.split(path.delimiter).filter((entry) => entry !== '') + const exts = process.platform === 'win32' ? (env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean).map((ext) => ext.toLowerCase()) : [''] + for (const segment of segments) { + for (const ext of exts) { + const candidate = path.join(segment, name + ext) + try { + const stat = fs.statSync(candidate) + if (stat.isFile()) return candidate + } catch (error) { + /* not here */ + } + } + } + return '' +} + +/** `rustc --version --verbose`, as `{ version, host, commit, raw }`. */ +export async function rustcFacts(deps) { + const result = await runArgv(['rustc', '--version', '--verbose'], { timeoutMs: 15_000, maxBytes: 64_000 }) + if (result.status === null) return { present: false, path: whichSync('rustc', deps.env) } + const text = String(result.stdout ?? '') + const pick = (name) => { + const match = new RegExp('^' + name + ':\\s*(.+)$', 'm').exec(text) + return match ? match[1].trim() : '' + } + return { + present: true, + path: whichSync('rustc', deps.env), + version: pick('release'), + host: pick('host'), + commit: pick('commit-hash'), + raw: text.trim(), + } +} + +/** + * The installed components and targets, from rustup. + * + * `rustup` is asked rather than guessed from the filesystem: a component can be + * installed for one toolchain and missing for another, and only rustup knows + * which toolchain is the default. + */ +export async function rustupFacts(deps) { + const components = await runArgv(['rustup', 'component', 'list', '--installed'], { timeoutMs: 20_000, maxBytes: 200_000 }) + const targets = await runArgv(['rustup', 'target', 'list', '--installed'], { timeoutMs: 20_000, maxBytes: 200_000 }) + const show = await runArgv(['rustup', 'show', 'active-toolchain'], { timeoutMs: 20_000, maxBytes: 64_000 }) + const lines = (result) => + String(result.stdout ?? '') + .split('\n') + .map((line) => line.trim()) + .filter((line) => line !== '' && !line.startsWith('info:')) + if (components.status === null) { + return { present: whichSync('rustup', deps.env) !== '', components: [], targets: [], toolchain: '' } + } + return { + present: true, + components: lines(components), + targets: lines(targets), + toolchain: String(show.stdout ?? '').trim().split('\n')[0] ?? '', + } +} + +/** The components the advice depends on, and the command that adds each. */ +export const COMPONENTS = [ + { name: 'clippy', add: 'rustup component add clippy', why: 'cargo_check want:"clippy"' }, + { name: 'rustfmt', add: 'rustup component add rustfmt', why: 'formatting, and `cargo fmt --check` in CI' }, + { name: 'rust-analyzer', add: 'rustup component add rust-analyzer', why: 'the editor/agent language server (this row does not drive it)' }, +] + +/** + * The workspace, from `cargo metadata --no-deps`. + * + * `--no-deps` is the point: it reads the manifests and stops. A resolve would + * want the registry, and a workspace on a machine with no network would then + * report "no workspace" for a workspace that is right there. + */ +export async function workspaceFacts(cwd, deps) { + const found = findManifest(cwd) + if (found === null) { + return { found: false, cwd } + } + const lock = path.join(found.root, 'Cargo.lock') + const base = { + found: true, + root: found.root, + manifest: found.manifest, + lockfile: fs.existsSync(lock), + fromCwd: path.resolve(cwd) !== found.root, + } + const result = await runArgv(['cargo', 'metadata', '--no-deps', '--format-version', '1', '--offline'], { + cwd: found.root, + timeoutMs: 60_000, + maxBytes: 8_000_000, + }) + if (result.status === null) { + return { ...base, error: 'cargo is not on PATH, so the manifests were not read' } + } + if (result.status !== 0) { + const why = String(result.stderr ?? '').trim().split('\n').slice(0, 3).join(' ') + return { ...base, error: 'cargo metadata failed: ' + (why || 'exit ' + result.status) } + } + let data + try { + data = JSON.parse(String(result.stdout ?? '')) + } catch (error) { + return { ...base, error: 'cargo metadata printed something that is not JSON' } + } + const members = new Set(data.workspace_members ?? []) + const packages = Array.isArray(data.packages) ? data.packages.filter((entry) => members.has(entry.id)) : [] + const declared = new Map() + for (const entry of packages) { + for (const dep of entry.dependencies ?? []) { + const name = String(dep.name ?? '') + if (name === '') continue + if (declared.has(name)) continue + declared.set(name, { name, req: String(dep.req ?? ''), kind: dep.kind ?? null }) + } + } + const notable = Object.keys(NOTABLE) + .filter((name) => declared.has(name)) + .map((name) => ({ name, req: declared.get(name).req, what: NOTABLE[name] })) + const editions = [...new Set(packages.map((entry) => entry.edition ?? '').filter(Boolean))] + const rustVersions = [...new Set(packages.map((entry) => entry.rust_version ?? '').filter(Boolean))] + return { + ...base, + error: null, + memberCount: packages.length, + members: packages.map((entry) => ({ name: entry.name, version: entry.version, kind: entry.targets?.[0]?.kind?.[0] ?? '' })), + editions, + rustVersions, + targetDirectory: String(data.target_directory ?? ''), + notable, + isWorkspace: packages.length > 1, + } +} + +/** + * Compare a declared `rust-version` with the installed `rustc`. + * + * @returns `{ declared, installed, satisfied }`, with `satisfied` null when it + * cannot be decided (no declared floor, or an unparseable version). + */ +export function msrvCheck(workspace, rustc) { + const declared = workspace.rustVersions?.[0] ?? '' + const installed = rustc.version ?? '' + if (declared === '' || installed === '') return { declared, installed, satisfied: null } + const parse = (value) => String(value).split(/[.\-+ ]/).slice(0, 3).map((part) => Number.parseInt(part, 10)) + const [major, minor] = parse(declared) + const [haveMajor, haveMinor] = parse(installed) + if (!Number.isFinite(major) || !Number.isFinite(haveMajor)) return { declared, installed, satisfied: null } + const satisfied = haveMajor > major || (haveMajor === major && (haveMinor ?? 0) >= (minor ?? 0)) + return { declared, installed, satisfied } +} diff --git a/packages/dsh-rust-dev/lib/tools.js b/packages/dsh-rust-dev/lib/tools.js new file mode 100644 index 0000000..7729970 --- /dev/null +++ b/packages/dsh-rust-dev/lib/tools.js @@ -0,0 +1,884 @@ +/** + * dsh-rust-dev — the six tools, and the prose that is the product. + * + * The rule this file follows: an answer is written for the reader that has to + * decide what to do NEXT, and it carries its conditions with its numbers. So + * every answer names the command line it ran, whether it was offline, and what it + * could not see. + * + * - `rust_status` reports the four facts separately, because they fail + * separately (see probe.js), and never builds anything; + * - `cargo_check` deduplicates diagnostics (one mistake repeated at forty call + * sites is ONE mistake), names the code, and returns a bounded list; + * - `cargo_test` returns the summary, the failing names, and the first + * failure's captured output - the part everyone scrolls for; + * - `cargo_build` reports the artifact's real path and size, and only runs the + * binary when asked; + * - `rust_deps` answers duplicate versions and feature chains; + * - `rust_backtrace` says whose code the panic is in. + */ + +import fs from 'node:fs' +import path from 'node:path' + +import { runArgv } from './cli.js' +import { parseBacktrace, verdictOf, frameLabel } from './backtrace.js' +import { firstLocation, parseJsonStream, shortPath, summarizeDiagnostics } from './diagnostics.js' +import { + declaredDependencies, + duplicateVersions, + featureChain, + graphOf, + graphSize, + mostDependedOn, +} from './metadata.js' +import { COMPONENTS, msrvCheck, rustcFacts, rustupFacts, workspaceFacts } from './probe.js' + +/** The output shape every tool returns. */ +const OUTPUT = { + schema: { + type: 'object', + properties: { text: { type: 'string' }, view: { type: 'object' } }, + required: ['text', 'view'], + }, + render: (_args, value) => [{ type: 'text', text: value.text }], + presentationMeta: (_args, value) => value.view, +} + +/** A card for the transcript. */ +function present(title) { + return { + presentCall: () => ({ card: 'generic', title: title, kind: 'other' }), + presentResult: (_args, result) => ({ card: 'generic', title: title, content: result && result.text ? result.text : '' }), + } +} + +/** A refusal: a sentence, and a view a caller can branch on. */ +function refusal(code, message, extra) { + return { text: message, view: { ok: false, code: code, ...(extra ?? {}) } } +} + +/** The same refusal for any thrown failure. */ +function failureOf(error) { + return refusal('FAILED', error && error.message ? String(error.message) : String(error)) +} + +/** Defaults and ceilings, in one place, so every answer can state them. */ +export const LIMITS = { + statusTimeoutMs: 30_000, + checkTimeoutMs: 300_000, + maxCheckTimeoutMs: 900_000, + testTimeoutMs: 300_000, + buildTimeoutMs: 600_000, + metadataTimeoutMs: 120_000, + runTimeoutMs: 60_000, + maxBytes: 4_000_000, + diagnostics: 20, +} + +/** Clamp a requested timeout into the row's ceiling. */ +function timeoutOf(args, fallback, ceiling) { + const asked = Number.isFinite(args?.timeoutMs) && args.timeoutMs > 0 ? args.timeoutMs : fallback + return Math.min(asked, ceiling) +} + +/** The directory this call runs in. */ +function cwdOf(deps, args) { + const raw = typeof args?.cwd === 'string' && args.cwd.trim() !== '' ? args.cwd.trim() : deps.cwd + return path.resolve(raw) +} + +/** `--offline` unless the caller explicitly asked for the network. */ +function offlineArgs(args) { + return args?.fetch === true ? [] : ['--offline'] +} + +/** Human bytes. */ +function bytesOf(count) { + if (!Number.isFinite(count) || count < 0) return '' + if (count < 1024) return count + ' B' + if (count < 1024 * 1024) return (count / 1024).toFixed(1) + ' KB' + return (count / (1024 * 1024)).toFixed(1) + ' MB' +} + +/** A fixed-width table. */ +function table(headers, rows) { + if (rows.length === 0) return headers.join(' ') + const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => String(row[index] ?? '').length))) + const line = (row) => headers.map((header, index) => String(row[index] ?? '').padEnd(widths[index])).join(' ').replace(/\s+$/, '') + return [line(headers), ...rows.map(line)].join('\n') +} + +/** The command line, as it would be pasted. */ +export function commandLine(argv) { + return argv.map((part) => (/[\s"]/.test(part) ? JSON.stringify(part) : part)).join(' ') +} + +// --------------------------------------------------------------------------- +// The four facts +// --------------------------------------------------------------------------- +/** + * Gather the four facts plus the workspace, without building. + * + * @returns `{ rustc, rustup, workspace, msrv, missing }`. + */ +export async function gatherFacts(deps, cwd) { + const [rustc, rustup] = await Promise.all([rustcFacts(deps), rustupFacts(deps)]) + const workspace = await workspaceFacts(cwd, deps) + const msrv = workspace.found && workspace.error === null ? msrvCheck(workspace, rustc) : { declared: '', installed: '', satisfied: null } + const missing = COMPONENTS.filter((entry) => rustup.present && !rustup.components.some((line) => line === entry.name || line.startsWith(entry.name + ' '))) + return { rustc, rustup, workspace, msrv, missing } +} + +/** The four facts as prose. */ +export function factsText(facts, cwd) { + const lines = [] + const rustc = facts.rustc + lines.push('TOOLCHAIN') + if (!rustc.present) { + lines.push(' rustc: not on PATH - there is no Rust toolchain here.') + lines.push(' Nothing was built and nothing was installed. Install one with rustup: https://rustup.rs') + lines.push(' (`rustup toolchain install stable`)') + return lines.join('\n') + } + lines.push(' rustc ' + (rustc.version || 'version unknown') + (rustc.host ? ' host ' + rustc.host : '')) + lines.push(' path ' + (rustc.path || 'not resolved')) + if (facts.rustup.present) { + lines.push(' rustup ' + (facts.rustup.toolchain || 'active toolchain not reported')) + } else { + lines.push(' rustup not found: components and targets cannot be reported (a distro-installed rustc is fine for building, and has no `rustup component add`)') + } + lines.push('') + lines.push('COMPONENTS') + if (!facts.rustup.present) { + lines.push(' unknown (no rustup) - clippy and rustfmt may still be installed by the distribution') + } else { + lines.push(' installed: ' + (facts.rustup.components.length === 0 ? '(none reported)' : facts.rustup.components.join(', '))) + for (const entry of facts.missing) { + lines.push(' MISSING ' + entry.name + ' -> ' + entry.add + ' (' + entry.why + ')') + } + } + lines.push('') + lines.push('TARGETS') + if (!facts.rustup.present) lines.push(' unknown (no rustup)') + else lines.push(' installed: ' + (facts.rustup.targets.length === 0 ? '(none reported)' : facts.rustup.targets.join(', '))) + lines.push('') + lines.push('WORKSPACE') + if (!facts.workspace.found) { + lines.push(' no Cargo.toml at or above ' + cwd + ' - this is not a cargo project.') + } else if (facts.workspace.error !== null) { + lines.push(' ' + facts.workspace.error) + lines.push(' root: ' + facts.workspace.root) + } else { + const workspace = facts.workspace + lines.push(' root ' + workspace.root + (workspace.fromCwd ? ' (found above ' + cwd + ')' : '')) + lines.push(' members ' + workspace.memberCount + (workspace.isWorkspace ? ' (a workspace)' : ' (a single package)') + ' editions ' + (workspace.editions.join(', ') || 'unknown')) + lines.push(' lock ' + (workspace.lockfile ? 'Cargo.lock present' : 'no Cargo.lock (a library does not need one)')) + if (facts.msrv.declared !== '') { + const verdict = facts.msrv.satisfied === null ? 'cannot compare' : facts.msrv.satisfied ? 'satisfied' : 'NOT satisfied - the toolchain is older than the floor' + lines.push(' msrv rust-version ' + facts.msrv.declared + ' vs installed ' + facts.msrv.installed + ' -> ' + verdict) + } + const notable = workspace.notable ?? [] + if (notable.length > 0) { + lines.push(' notable ' + notable.map((entry) => entry.name + ' ' + entry.req).join(' · ')) + for (const entry of notable) { + if (entry.what) lines.push(' ' + entry.name + ': ' + entry.what) + } + } + if (workspace.members.length > 1) { + const names = workspace.members.slice(0, 12).map((entry) => entry.name) + lines.push(' crates ' + names.join(', ') + (workspace.members.length > 12 ? ', … (' + workspace.members.length + ' total)' : '')) + } + } + return lines.join('\n') +} + +// --------------------------------------------------------------------------- +// Build the tools +// --------------------------------------------------------------------------- +/** Build the tools. @param deps - `{ cwd, runner, env, log }`. */ +export function buildTools(deps) { + /** `rust_status`: the four facts, read-only. */ + const status = { + name: 'rust_status', + description: [ + 'Report the four facts that fail independently on a Rust machine: the TOOLCHAIN (rustc/cargo versions, rup default, host triple), the COMPONENTS (clippy, rustfmt, rust-analyzer - with the exact `rustup component add` for any that are missing), the installed TARGETS, and the WORKSPACE at `cwd` (members, editions, MSRV against the installed toolchain, lockfile, and which notable crates it declares: eframe, egui, wgpu, tokio, tracing, serde, clap, tauri, bevy).', + 'Call this FIRST on a Rust question. It builds nothing, fetches nothing and reads manifests only (`cargo metadata --no-deps --offline`), so it is cheap and safe. A machine with no toolchain is an ANSWER here, not a failure - it names rustup and stops.', + 'Read-only.', + ].join('\n'), + parameters: { + type: 'object', + additionalProperties: false, + properties: { cwd: { type: 'string', description: 'Directory to inspect (default: the workspace root this session runs in).' } }, + }, + output: OUTPUT, + ...present('Rust status'), + async execute(args) { + try { + const cwd = cwdOf(deps, args) + const facts = await gatherFacts(deps, cwd) + const view = { + ok: facts.rustc.present, + code: facts.rustc.present ? null : 'NO_TOOLCHAIN', + toolchain: { version: facts.rustc.version, host: facts.rustc.host, path: facts.rustc.path, rustup: facts.rustup.toolchain }, + components: facts.rustup.components, + missingComponents: facts.missing.map((entry) => ({ name: entry.name, add: entry.add })), + targets: facts.rustup.targets, + workspace: facts.workspace.found + ? { + root: facts.workspace.root, + members: facts.workspace.memberCount, + editions: facts.workspace.editions, + lockfile: facts.workspace.lockfile, + notable: facts.workspace.notable, + error: facts.workspace.error, + } + : { root: null, error: 'no Cargo.toml' }, + msrv: facts.msrv, + } + return { text: factsText(facts, cwd), view } + } catch (error) { + return failureOf(error) + } + }, + } + + /** `cargo_check`: diagnostics, parsed and deduplicated. */ + const check = { + name: 'cargo_check', + description: [ + 'Run `cargo check` (or `cargo clippy`) with `--message-format=json` and return the diagnostics as DATA: counts of errors and warnings, the distinct items with their rustc CODE (E0308 …), their file:line:column, a one-line meaning for the common codes, and how many times each one repeats. The JSON stream is parsed - never the rendered text, which is prose that changes.', + 'Duplicates are collapsed: one type error repeated at forty call sites is listed ONCE with `seen x40`, because a list of forty identical errors hides the four distinct mistakes inside it.', + 'Runs `--offline` by default. Pass `fetch: true` only when a dependency genuinely has to be downloaded - this row does not start network egress on its own. NOTE: `cargo check` RUNS `build.rs` and dependency proc macros on this machine, so it is not a read-only inspection of untrusted code.', + ].join('\n'), + parameters: { + type: 'object', + additionalProperties: false, + properties: { + cwd: { type: 'string', description: 'Directory to run in (default: the workspace root this session runs in).' }, + want: { type: 'string', enum: ['check', 'clippy'], description: 'check (rustc diagnostics) or clippy (lints, which have names rather than codes). Default check.' }, + package: { type: 'string', description: 'Limit to one workspace member (-p).' }, + features: { type: 'array', items: { type: 'string' }, description: 'Features to enable (--features).' }, + allTargets: { type: 'boolean', description: 'Check tests, benches and examples too (--all-targets).' }, + limit: { type: 'integer', minimum: 1, maximum: 100, description: 'How many distinct items to return (default 20; counts are always total).' }, + fetch: { type: 'boolean', description: 'Allow the network (drops --offline). Default false.' }, + timeoutMs: { type: 'integer', minimum: 1000, maximum: 900000, description: 'Deadline in ms (default 300000, ceiling 900000).' }, + }, + }, + output: OUTPUT, + ...present('cargo check'), + async execute(args) { + try { + const cwd = cwdOf(deps, args) + const workspace = await workspaceFacts(cwd, deps) + if (!workspace.found) return refusal('NO_WORKSPACE', 'No Cargo.toml at or above ' + cwd + '. Point `cwd` at a cargo project (or a member of one).') + if (workspace.error !== null) return refusal('NO_WORKSPACE', workspace.error) + const want = args?.want === 'clippy' ? 'clippy' : 'check' + const argv = ['cargo', want, '--message-format=json', ...offlineArgs(args)] + if (args?.allTargets === true) argv.push('--all-targets') + if (typeof args?.package === 'string' && args.package !== '') argv.push('-p', args.package) + if (Array.isArray(args?.features) && args.features.length > 0) argv.push('--features', args.features.join(',')) + const timeoutMs = timeoutOf(args, LIMITS.checkTimeoutMs, LIMITS.maxCheckTimeoutMs) + const result = await runArgv(argv, { cwd: workspace.root, timeoutMs, maxBytes: LIMITS.maxBytes }) + const command = commandLine(argv) + if (result.status === null) { + return refusal('NO_CARGO', 'Could not start `cargo` (' + (result.error || 'not on PATH') + '). `rust_status` says whether a toolchain exists here.', { command }) + } + if (result.timedOut) { + return refusal('TIMEOUT', '`' + command + '` was still running after ' + Math.round(timeoutMs / 1000) + ' s and was killed (the process tree too). A cold build of a large graph is the usual cause: run it once outside, or raise `timeoutMs`.', { command, timeoutMs }) + } + const parsed = parseJsonStream(result.stdout) + const summary = summarizeDiagnostics(parsed.messages, { limit: Number.isFinite(args?.limit) ? args.limit : LIMITS.diagnostics }) + const success = parsed.finished !== null ? parsed.finished.success === true : result.status === 0 + // A cargo-level failure (bad flag, missing clippy, unresolvable manifest) has no + // compiler diagnostics at all; the stderr head is then the whole answer. + const stderrHead = String(result.stderr ?? '').trim().split('\n').slice(0, 4).join('\n') + const noCompilerOutput = summary.counts.error === 0 && summary.items.length === 0 + const lines = [] + lines.push('$ ' + command) + lines.push('in ' + workspace.root + (args?.fetch === true ? ' (network allowed by fetch: true)' : ' (offline)')) + lines.push('') + if (noCompilerOutput && !success) { + lines.push('cargo failed before the compiler produced diagnostics' + (result.truncated ? ' (output truncated)' : '') + ':') + lines.push('') + lines.push(stderrHead || '(no stderr)') + if (want === 'clippy' && /no such command|not installed|component/i.test(stderrHead)) { + lines.push('') + lines.push('clippy is probably not installed: `rustup component add clippy`') + } + return { text: lines.join('\n'), view: { ok: false, code: 'CARGO_FAILED', command, exit: result.status, stderr: stderrHead } } + } + lines.push( + success + ? 'RESULT clean' + (summary.counts.warning > 0 ? ' (with ' + summary.counts.warning + ' warning' + (summary.counts.warning === 1 ? '' : 's') + ')' : '') + : 'RESULT ' + summary.counts.error + ' error' + (summary.counts.error === 1 ? '' : 's') + ', ' + summary.counts.warning + ' warning' + (summary.counts.warning === 1 ? '' : 's'), + ) + lines.push(' ' + summary.distinct.errors + ' distinct error site' + (summary.distinct.errors === 1 ? '' : 's') + ', ' + summary.distinct.warnings + ' distinct warning site' + (summary.distinct.warnings === 1 ? '' : 's') + ' (duplicates collapsed)') + if (result.truncated) lines.push(' OUTPUT WAS TRUNCATED at ' + bytesOf(LIMITS.maxBytes) + '; later diagnostics are missing - re-run with `package` to narrow it') + const codes = Object.entries(summary.byCode).sort((a, b) => b[1] - a[1]) + if (codes.length > 0) lines.push(' codes: ' + codes.map(([code, count]) => code + ' x' + count).join(', ')) + if (summary.items.length > 0) { + lines.push('') + for (const item of summary.items) { + const where = shortPath(item.file, workspace.root) + ':' + item.line + ':' + item.column + const repeat = item.repeat > 1 ? ' (seen x' + item.repeat + ')' : '' + lines.push(' ' + item.level + (item.code ? '[' + item.code + ']' : '') + ' ' + where + repeat) + lines.push(' ' + item.message + (item.hint ? ' — ' + item.hint : '')) + } + if (summary.hidden > 0) lines.push(' … ' + summary.hidden + ' more distinct site(s) not shown') + } + if (summary.spanless.length > 0) { + lines.push('') + lines.push('cargo said: ' + summary.spanless.join(' | ')) + } + lines.push('') + lines.push('elapsed ' + (result.elapsedMs / 1000).toFixed(1) + ' s, exit ' + result.status) + return { + text: lines.join('\n'), + view: { + ok: success, + code: success ? null : 'CHECK_FAILED', + command, + offline: args?.fetch !== true, + errors: summary.counts.error, + warnings: summary.counts.warning, + distinct: summary.distinct, + byCode: summary.byCode, + items: summary.items, + hidden: summary.hidden, + truncated: result.truncated, + elapsedMs: result.elapsedMs, + firstLocation: firstLocation(summary), + }, + } + } catch (error) { + return failureOf(error) + } + }, + } + + /** `cargo_test`: the summary, the failing names, the first failure's output. */ + const test = { + name: 'cargo_test', + description: [ + 'Run `cargo test` and return what a reader scrolls for: the summary (passed/failed/ignored), the NAMES of the failing tests, and the captured stdout of the FIRST failure (`--nocapture` on request shows all of it).', + 'The libtest text is parsed here because cargo does not emit tests as JSON on stable; the numbers are read from the `test result:` lines, which are stable.', + '`filter` narrows to tests whose name contains it (`cargo test name`), which is the fastest way to reproduce ONE failure. Runs `--offline` by default, and compiling still runs `build.rs` and proc macros.', + ].join('\n'), + parameters: { + type: 'object', + additionalProperties: false, + properties: { + cwd: { type: 'string', description: 'Directory to run in (default: the workspace root this session runs in).' }, + filter: { type: 'string', description: 'Only tests whose name contains this (passed to cargo test as the filter).' }, + package: { type: 'string', description: 'Limit to one workspace member (-p).' }, + release: { type: 'boolean', description: 'Test the release profile (--release). Use when a failure only happens there.' }, + nocapture: { type: 'boolean', description: 'Do not capture test output (-- --nocapture).' }, + fetch: { type: 'boolean', description: 'Allow the network (drops --offline). Default false.' }, + timeoutMs: { type: 'integer', minimum: 1000, maximum: 900000, description: 'Deadline in ms (default 300000, ceiling 900000).' }, + }, + }, + output: OUTPUT, + ...present('cargo test'), + async execute(args) { + try { + const cwd = cwdOf(deps, args) + const workspace = await workspaceFacts(cwd, deps) + if (!workspace.found) return refusal('NO_WORKSPACE', 'No Cargo.toml at or above ' + cwd + '.') + if (workspace.error !== null) return refusal('NO_WORKSPACE', workspace.error) + const argv = ['cargo', 'test', ...offlineArgs(args)] + if (args?.release === true) argv.push('--release') + if (typeof args?.package === 'string' && args.package !== '') argv.push('-p', args.package) + const filter = typeof args?.filter === 'string' ? args.filter : '' + if (filter !== '') argv.push(filter) + if (args?.nocapture === true) argv.push('--', '--nocapture') + const timeoutMs = timeoutOf(args, LIMITS.testTimeoutMs, LIMITS.maxCheckTimeoutMs) + const result = await runArgv(argv, { cwd: workspace.root, timeoutMs, maxBytes: LIMITS.maxBytes }) + const command = commandLine(argv) + if (result.status === null) return refusal('NO_CARGO', 'Could not start `cargo` (' + (result.error || 'not on PATH') + ').', { command }) + if (result.timedOut) return refusal('TIMEOUT', '`' + command + '` was killed after ' + Math.round(timeoutMs / 1000) + ' s; a test that hangs (or a cold build) is the usual cause.', { command }) + const summary = parseTestOutput(String(result.stdout ?? '') + '\n' + String(result.stderr ?? '')) + const ok = result.status === 0 + const lines = [] + lines.push('$ ' + command) + lines.push('in ' + workspace.root + (args?.fetch === true ? ' (network allowed)' : ' (offline)')) + lines.push('') + lines.push(ok ? 'RESULT all tests passed' : 'RESULT ' + summary.failed + ' failed, ' + summary.passed + ' passed, ' + summary.ignored + ' ignored') + if (summary.suites.length > 0) { + lines.push('') + for (const suite of summary.suites) { + lines.push(' ' + (suite.name || 'tests') + ': ' + suite.passed + ' passed, ' + suite.failed + ' failed, ' + suite.ignored + ' ignored') + } + } + if (summary.failing.length > 0) { + lines.push('') + lines.push('FAILED') + for (const name of summary.failing) lines.push(' ' + name) + } + if (summary.firstFailure !== '') { + lines.push('') + lines.push('FIRST FAILURE OUTPUT') + lines.push(summary.firstFailure) + } + if (!ok && summary.failing.length === 0 && summary.suites.length === 0) { + const head = String(result.stderr ?? '').trim().split('\n').slice(0, 6).join('\n') + lines.push('') + lines.push('cargo failed before any test ran:') + lines.push(head || '(no output)') + } + lines.push('') + lines.push('elapsed ' + (result.elapsedMs / 1000).toFixed(1) + ' s, exit ' + result.status) + return { + text: lines.join('\n'), + view: { + ok, + code: ok ? null : 'TESTS_FAILED', + command, + offline: args?.fetch !== true, + passed: summary.passed, + failed: summary.failed, + ignored: summary.ignored, + failing: summary.failing, + elapsedMs: result.elapsedMs, + }, + } + } catch (error) { + return failureOf(error) + } + }, + } + + /** `cargo_build`: the artifact, its real size, and optionally a run. */ + const build = { + name: 'cargo_build', + description: [ + 'Run `cargo build` (dev or `--release`) and report what came out: success, the artifact PATH, its real size on disk, the warning count, and how long it took. The executable is read from cargo\'s own `compiler-artifact` events (`executable`), not guessed from a path convention.', + 'With `run: true` it then executes that binary with `args` as an ARGV ARRAY, under its own deadline, and returns stdout, stderr and the exit code. That is the ONE call in this row that runs the caller\'s code, and the answer says so.', + 'Runs `--offline` by default. A build runs `build.rs` and dependency proc macros on this machine.', + ].join('\n'), + parameters: { + type: 'object', + additionalProperties: false, + properties: { + cwd: { type: 'string', description: 'Directory to run in (default: the workspace root this session runs in).' }, + release: { type: 'boolean', description: 'Build the release profile (--release).' }, + package: { type: 'string', description: 'Limit to one workspace member (-p).' }, + bin: { type: 'string', description: 'Which binary to report/run when the package makes several.' }, + run: { type: 'boolean', description: 'Execute the built binary afterwards. Default false.' }, + args: { type: 'array', items: { type: 'string' }, description: 'Arguments for the binary when run: true (argv, never a shell string).' }, + fetch: { type: 'boolean', description: 'Allow the network (drops --offline). Default false.' }, + timeoutMs: { type: 'integer', minimum: 1000, maximum: 900000, description: 'Build deadline in ms (default 600000, ceiling 900000).' }, + }, + }, + output: OUTPUT, + ...present('cargo build'), + async execute(args) { + try { + const cwd = cwdOf(deps, args) + const workspace = await workspaceFacts(cwd, deps) + if (!workspace.found) return refusal('NO_WORKSPACE', 'No Cargo.toml at or above ' + cwd + '.') + if (workspace.error !== null) return refusal('NO_WORKSPACE', workspace.error) + const argv = ['cargo', 'build', '--message-format=json', ...offlineArgs(args)] + if (args?.release === true) argv.push('--release') + if (typeof args?.package === 'string' && args.package !== '') argv.push('-p', args.package) + if (typeof args?.bin === 'string' && args.bin !== '') argv.push('--bin', args.bin) + const timeoutMs = timeoutOf(args, LIMITS.buildTimeoutMs, LIMITS.maxCheckTimeoutMs) + const result = await runArgv(argv, { cwd: workspace.root, timeoutMs, maxBytes: LIMITS.maxBytes }) + const command = commandLine(argv) + if (result.status === null) return refusal('NO_CARGO', 'Could not start `cargo` (' + (result.error || 'not on PATH') + ').', { command }) + if (result.timedOut) return refusal('TIMEOUT', '`' + command + '` was killed after ' + Math.round(timeoutMs / 1000) + ' s (process tree included).', { command }) + const parsed = parseJsonStream(result.stdout) + const summary = summarizeDiagnostics(parsed.messages, { limit: LIMITS.diagnostics }) + const executables = [] + for (const artifact of parsed.artifacts) { + if (typeof artifact.executable !== 'string' || artifact.executable === '') continue + if (executables.includes(artifact.executable)) continue + executables.push(artifact.executable) + } + let size = 0 + for (const file of executables) { + try { + size += fs.statSync(file).size + } catch (error) { + /* reported below as unknown */ + } + } + const ok = parsed.finished !== null ? parsed.finished.success === true : result.status === 0 + const lines = [] + lines.push('$ ' + command) + lines.push('in ' + workspace.root + (args?.fetch === true ? ' (network allowed)' : ' (offline)')) + lines.push('') + if (!ok) { + lines.push('RESULT build FAILED' + (summary.counts.error > 0 ? ' - ' + summary.counts.error + ' error(s)' : '')) + const head = String(result.stderr ?? '').trim().split('\n').slice(0, 6).join('\n') + if (head !== '') { + lines.push('') + lines.push(head) + } + if (summary.items.length > 0) { + lines.push('') + for (const item of summary.items.slice(0, 8)) { + lines.push(' ' + item.level + (item.code ? '[' + item.code + ']' : '') + ' ' + shortPath(item.file, workspace.root) + ':' + item.line + ':' + item.column + ' ' + item.message) + } + } + return { text: lines.join('\n'), view: { ok: false, code: 'BUILD_FAILED', command, errors: summary.counts.error, warnings: summary.counts.warning } } + } + lines.push('RESULT built' + (args?.release === true ? ' (release)' : ' (dev)') + ' - ' + summary.counts.warning + ' warning' + (summary.counts.warning === 1 ? '' : 's') + ', ' + (result.elapsedMs / 1000).toFixed(1) + ' s') + if (executables.length === 0) { + lines.push('') + lines.push('No executable was produced: this looks like a library crate. Use `cargo_test`, or build a `--bin`.') + } else { + lines.push('') + for (const file of executables) { + let bytes = 0 + try { + bytes = fs.statSync(file).size + } catch (error) { + /* unknown */ + } + lines.push(' ' + file + ' (' + (bytes > 0 ? bytesOf(bytes) : 'size unknown') + ')') + } + if (executables.length > 1) lines.push(' (' + executables.length + ' binaries; pass `bin` to choose one for `run`)') + } + let runResult = null + if (args?.run === true) { + if (executables.length === 0) { + lines.push('') + lines.push('`run: true` was asked for, but there is no executable to run.') + } else if (executables.length > 1 && (typeof args?.bin !== 'string' || args.bin === '')) { + lines.push('') + lines.push('`run: true` was asked for, but this build produced ' + executables.length + ' binaries. Pass `bin` to name the one to run; nothing was executed.') + } else { + const target = executables[0] + const runArgvArray = [target, ...(Array.isArray(args?.args) ? args.args.map(String) : [])] + const ran = await runArgv(runArgvArray, { cwd: workspace.root, timeoutMs: LIMITS.runTimeoutMs, maxBytes: 400_000 }) + runResult = { + command: commandLine(runArgvArray), + exit: ran.status, + stdout: String(ran.stdout ?? ''), + stderr: String(ran.stderr ?? ''), + timedOut: ran.timedOut, + elapsedMs: ran.elapsedMs, + } + lines.push('') + lines.push('RAN ' + runResult.command + ' (this executes your code)') + if (ran.timedOut) lines.push(' killed after ' + Math.round(LIMITS.runTimeoutMs / 1000) + ' s') + lines.push(' exit ' + ran.status + ', ' + (ran.elapsedMs / 1000).toFixed(2) + ' s') + const out = runResult.stdout.trim() + const err = runResult.stderr.trim() + if (out !== '') { + lines.push('') + lines.push('stdout:') + lines.push(out.split('\n').slice(0, 60).join('\n')) + } + if (err !== '') { + lines.push('') + lines.push('stderr:') + lines.push(err.split('\n').slice(0, 60).join('\n')) + if (/panicked at/.test(err)) lines.push('') + if (/panicked at/.test(err)) lines.push('A panic was printed: `rust_backtrace` reads it properly (whose code the frames are in).') + } + if (out === '' && err === '') lines.push(' (no output)') + } + } + return { + text: lines.join('\n'), + view: { + ok: true, + code: null, + command, + release: args?.release === true, + warnings: summary.counts.warning, + executables, + bytes: size, + elapsedMs: result.elapsedMs, + run: runResult, + }, + } + } catch (error) { + return failureOf(error) + } + }, + } + + /** `rust_deps`: duplicates, weight, features. */ + const depsTool = { + name: 'rust_deps', + description: [ + 'Answer the three dependency questions a cargo workspace hides: WHICH CRATE IS COMPILED AT MORE THAN ONE VERSION (with who depends on each copy), WHAT THE WEIGHT IS (the crates the most other crates depend on), and - for one crate with `crate` - WHICH FEATURE CHAIN ENABLED IT (`cargo tree -e features -i`), because features unify across the whole graph and a crate you never named can arrive with defaults on.', + 'Reads `cargo metadata` (the resolved graph) and `cargo tree`; it does not load a crate, and it builds nothing.', + 'Runs `--offline` by default: a resolve needs the registry, so when the lockfile and the local cache cannot answer, the refusal says to pass `fetch: true` rather than downloading quietly.', + ].join('\n'), + parameters: { + type: 'object', + additionalProperties: false, + properties: { + cwd: { type: 'string', description: 'Directory to run in (default: the workspace root this session runs in).' }, + crate: { type: 'string', description: 'Show the feature chain for this crate (cargo tree -e features -i).' }, + duplicatesOnly: { type: 'boolean', description: 'Only the duplicate-version section.' }, + limit: { type: 'integer', minimum: 1, maximum: 50, description: 'How many entries per section (default 10).' }, + fetch: { type: 'boolean', description: 'Allow the network (drops --offline). Default false.' }, + }, + }, + output: OUTPUT, + ...present('Cargo dependencies'), + async execute(args) { + try { + const cwd = cwdOf(deps, args) + const workspace = await workspaceFacts(cwd, deps) + if (!workspace.found) return refusal('NO_WORKSPACE', 'No Cargo.toml at or above ' + cwd + '.') + if (workspace.error !== null) return refusal('NO_WORKSPACE', workspace.error) + const argv = ['cargo', 'metadata', '--format-version', '1', ...offlineArgs(args)] + const result = await runArgv(argv, { cwd: workspace.root, timeoutMs: LIMITS.metadataTimeoutMs, maxBytes: LIMITS.maxBytes }) + const command = commandLine(argv) + if (result.status !== 0) { + const stderr = String(result.stderr ?? '').trim() + const offlineFailure = /offline|network|registry|failed to (load|download|fetch)/i.test(stderr) + return refusal( + 'NO_RESOLVE', + '`' + command + '` failed' + (offlineFailure ? ' because the resolve needs the registry and this call was offline' : '') + ':\n' + stderr.split('\n').slice(0, 6).join('\n') + (offlineFailure ? '\n\nPass `fetch: true` to allow the download for this call - this row does not start network egress on its own.' : ''), + { command }, + ) + } + let metadata + try { + metadata = JSON.parse(String(result.stdout ?? '')) + } catch (error) { + return refusal('BAD_METADATA', '`cargo metadata` printed something that is not JSON.') + } + const graph = graphOf(metadata) + const size = graphSize(graph) + const duplicates = duplicateVersions(graph) + const heaviest = mostDependedOn(graph, Number.isFinite(args?.limit) ? args.limit : 10) + const declared = declaredDependencies(metadata) + const lines = [] + lines.push('$ ' + command) + lines.push('in ' + workspace.root + ' (' + (args?.fetch === true ? 'network allowed' : 'offline') + ')') + lines.push('') + lines.push('GRAPH ' + size.packages + ' packages, ' + size.edges + ' edges, ' + size.members + ' workspace member(s)') + lines.push(' ' + declared.size + ' direct dependencies declared by the members') + if (args?.duplicatesOnly !== true) { + lines.push('') + lines.push('MOST DEPENDED ON') + if (heaviest.length === 0) lines.push(' (nothing beyond the workspace members)') + for (const entry of heaviest) { + lines.push(' ' + entry.name + ' ' + entry.version + ' <- ' + entry.dependents + ' dependent(s)' + (entry.sample.length > 0 ? ' e.g. ' + entry.sample.join(', ') : '')) + } + } + lines.push('') + lines.push('DUPLICATE VERSIONS') + if (duplicates.length === 0) { + lines.push(' none: every crate appears at exactly one version') + } else { + for (const entry of duplicates) { + lines.push(' ' + entry.name + ' ' + entry.versions.map((version) => version.version).join(' + ')) + for (const version of entry.versions) { + lines.push(' ' + version.version + ' used by: ' + (version.usedBy.length === 0 ? '(nothing - unreachable?)' : version.usedBy.join(', '))) + } + } + lines.push('') + lines.push(' Two versions of one crate are legal and costly: both are compiled, and a type from one is not the type from the other.') + } + let features = null + if (typeof args?.crate === 'string' && args.crate !== '') { + const treeArgv = ['cargo', 'tree', '-e', 'features', '-i', args.crate, ...offlineArgs(args)] + const tree = await runArgv(treeArgv, { cwd: workspace.root, timeoutMs: 60_000, maxBytes: 500_000 }) + lines.push('') + lines.push('FEATURES for ' + args.crate + ' ($ ' + commandLine(treeArgv) + ')') + if (tree.status !== 0) { + const why = String(tree.stderr ?? '').trim().split('\n').slice(0, 3).join('\n') + lines.push(' could not read the feature chain: ' + (why || 'exit ' + tree.status)) + lines.push(' (a crate name that is not in the graph, or an offline resolve that needs the registry)') + } else { + features = featureChain(String(tree.stdout ?? ''), 40) + if (features.features.length > 0) lines.push(' features in play: ' + features.features.join(', ')) + lines.push('') + for (const line of features.lines) lines.push(' ' + line) + if (features.truncatedLines > 0) lines.push(' … ' + features.truncatedLines + ' more line(s)') + } + } + return { + text: lines.join('\n'), + view: { + ok: true, + code: null, + command, + offline: args?.fetch !== true, + graph: size, + duplicates, + heaviest, + features: features === null ? null : features.features, + }, + } + } catch (error) { + return failureOf(error) + } + }, + } + + /** `rust_backtrace`: whose code the panic is in. */ + const backtrace = { + name: 'rust_backtrace', + description: [ + 'Read a Rust panic or backtrace and say WHOSE CODE it is in. Symbols are demangled (the legacy `_ZN…E` mangling, decoded exactly - no external rustfilt), frames are classified by path into YOUR workspace, a DEPENDENCY (from the registry) or the RUNTIME, and the answer names the first frame in your code, or says plainly that the panic surfaces from a dependency.', + 'Takes the capture as `text`, or reads it from `file`. Enable it with RUST_BACKTRACE=1 (or `full` for every frame) - if the capture has no frames, the answer says so and names that variable rather than inventing a location.', + 'The v0 mangling (`_R…`) is a different grammar and is NOT decoded: those symbols are reported as-is with a count, because a plausible wrong name is worse than an honest one.', + ].join('\n'), + parameters: { + type: 'object', + additionalProperties: false, + properties: { + text: { type: 'string', description: 'The captured stderr / panic text.' }, + file: { type: 'string', description: 'Read the capture from this file instead.' }, + root: { type: 'string', description: 'Workspace root used to tell YOUR frames from dependencies (default: the workspace found from cwd).' }, + limit: { type: 'integer', minimum: 1, maximum: 200, description: 'How many frames to show (default 40).' }, + cwd: { type: 'string', description: 'Directory the workspace is found from.' }, + }, + }, + output: OUTPUT, + ...present('Rust backtrace'), + async execute(args) { + try { + let text = typeof args?.text === 'string' ? args.text : '' + if (text === '' && typeof args?.file === 'string' && args.file !== '') { + const file = path.resolve(args.file) + const stat = fs.statSync(file) + if (stat.size > 4_000_000) return refusal('TOO_LARGE', file + ' is ' + bytesOf(stat.size) + '; read a slice of it and pass `text`.') + text = fs.readFileSync(file, 'utf8') + } + if (text.trim() === '') return refusal('NO_INPUT', 'Nothing to read: pass `text` (the captured panic) or `file`.') + let root = typeof args?.root === 'string' && args.root !== '' ? path.resolve(args.root) : '' + if (root === '') { + const workspace = await workspaceFacts(cwdOf(deps, args), deps) + root = workspace.found ? workspace.root : '' + } + const parsed = parseBacktrace(text, { root, cwd: root }) + const verdict = verdictOf(parsed) + const limit = Number.isFinite(args?.limit) ? args.limit : 40 + const byKind = { workspace: [], dependency: [], std: [], unknown: [] } + for (const frame of parsed.frames) (byKind[frame.kind] ?? byKind.unknown).push(frame) + const lines = [] + if (parsed.panic !== '') { + lines.push('PANIC') + lines.push(' ' + parsed.panic) + lines.push('') + } + lines.push('VERDICT') + lines.push(' ' + verdict.text) + if (root !== '') lines.push(' (workspace root used for classification: ' + root + ')') + lines.push('') + lines.push('FRAMES ' + parsed.frames.length + ' total - ' + byKind.workspace.length + ' yours, ' + byKind.dependency.length + ' dependency, ' + byKind.std.length + ' runtime, ' + byKind.unknown.length + ' unknown') + const show = (title, frames) => { + if (frames.length === 0) return + lines.push('') + lines.push(title) + for (const frame of frames.slice(0, limit)) { + lines.push(' ' + String(frame.index).padStart(3, ' ') + ' ' + frameLabel(frame) + (frame.symbol !== frame.name ? ' [' + frame.symbol + ']' : '')) + } + if (frames.length > limit) lines.push(' … ' + (frames.length - limit) + ' more') + } + show('YOUR CODE', byKind.workspace) + show('DEPENDENCIES', byKind.dependency) + if (byKind.workspace.length === 0 && byKind.dependency.length === 0 && byKind.unknown.length > 0) show('UNCLASSIFIED', byKind.unknown) + if (parsed.note !== '') { + lines.push('') + lines.push('NOTE ' + parsed.note) + } + if (parsed.v0Count > 0) { + lines.push('') + lines.push('NOTE ' + parsed.v0Count + ' symbol(s) use the v0 mangling (`_R…`), which this row does not decode; they are shown raw. `cargo install rustfilt` + `rustfilt ` decodes them.') + } + if (parsed.frames.length === 0) { + lines.push('') + lines.push('No frames were present. A backtrace needs RUST_BACKTRACE=1 (or `full`) in the environment of the process that panicked, and debug info (`debug = true` or the default dev profile) in the binary.') + } + return { + text: lines.join('\n'), + view: { + ok: parsed.frames.length > 0, + code: parsed.frames.length === 0 ? 'NO_FRAMES' : null, + verdict: verdict.kind, + panic: parsed.panic, + frames: { total: parsed.frames.length, workspace: byKind.workspace.length, dependency: byKind.dependency.length, std: byKind.std.length }, + firstOwnFrame: verdict.kind === 'workspace' ? { name: verdict.frame.name, file: verdict.frame.file, line: verdict.frame.line } : null, + v0Symbols: parsed.v0Count, + }, + } + } catch (error) { + return failureOf(error) + } + }, + } + + return [status, check, test, build, depsTool, backtrace] +} + +/** + * Parse libtest's human output. + * + * cargo does not emit test results as JSON on stable, so the text is read - but + * only its STABLE lines: `test result: . N passed; N failed; N ignored`, + * `test ... FAILED`, and the `---- stdout ----` blocks. + * + * @param text - stdout and stderr together. + * @returns `{ passed, failed, ignored, suites, failing, firstFailure }`. + */ +export function parseTestOutput(text) { + const lines = String(text ?? '').replace(/\r\n?/g, '\n').split('\n') + let passed = 0 + let failed = 0 + let ignored = 0 + const suites = [] + const failing = [] + let currentSuite = '' + const blocks = new Map() + let collecting = null + for (const line of lines) { + const running = /^\s*Running\s+(.+?)(?:\s+\(|$)/.exec(line) + if (running !== null) { + currentSuite = running[1].trim() + continue + } + const result = /^test result:\s*(\w+)\.\s*(\d+) passed;\s*(\d+) failed;\s*(\d+) ignored/.exec(line) + if (result !== null) { + const p = Number(result[2]) + const f = Number(result[3]) + const i = Number(result[4]) + passed += p + failed += f + ignored += i + suites.push({ name: currentSuite, passed: p, failed: f, ignored: i }) + collecting = null + continue + } + const failedName = /^test (.+?) \.\.\. FAILED$/.exec(line) + if (failedName !== null) { + failing.push(failedName[1]) + continue + } + const header = /^---- (.+?) stdout ----$/.exec(line) + if (header !== null) { + collecting = header[1] + blocks.set(collecting, []) + continue + } + if (collecting !== null) { + if (/^failures:$/.test(line) || /^test result:/.test(line)) { + collecting = null + continue + } + blocks.get(collecting).push(line) + } + } + let firstFailure = '' + if (failing.length > 0 && blocks.has(failing[0])) { + firstFailure = blocks + .get(failing[0]) + .join('\n') + .trim() + .split('\n') + .slice(0, 40) + .join('\n') + } + return { passed, failed, ignored, suites, failing, firstFailure } +} diff --git a/packages/dsh-rust-dev/package.json b/packages/dsh-rust-dev/package.json new file mode 100644 index 0000000..9b477fb --- /dev/null +++ b/packages/dsh-rust-dev/package.json @@ -0,0 +1,29 @@ +{ + "name": "dsh-rust-dev", + "version": "0.1.0-alpha.1", + "description": "Rust development as a surface: six tools over the machine's own toolchain - `rust_status` (the four facts that fail independently: toolchain, components, installed targets, the workspace), `cargo_check` (diagnostics parsed from `--message-format=json`, with codes and file:line:col), `cargo_test`, `cargo_build` (artifact path and real size), `rust_deps` (duplicate crate versions, features and the chain that enabled them) and `rust_backtrace` (demangled frames, separated into your workspace and dependencies) - plus four skills (workspaces, diagnostics, debugging, and egui/eframe/wgpu apps). Every cargo call is `--offline` by default, every answer names the command it ran, and nothing installs a toolchain or a crate. Host-only: one row, no route, no browser half, zero npm dependencies.", + "type": "module", + "main": "lib/index.js", + "exports": { + ".": "./lib/index.js", + "./package.json": "./package.json" + }, + "files": [ + "lib", + "skills", + "checks", + "cordis.patch.yml" + ], + "scripts": { + "check": "node checks/check-rust-node.mjs && node checks/check-rust-examples.mjs" + }, + "engines": { + "node": ">=22" + }, + "dsh": { + "bundle": { + "patch": "./cordis.patch.yml" + } + }, + "license": "AGPL-3.0-only" +} diff --git a/packages/dsh-rust-dev/skills/rust-debugging/SKILL.md b/packages/dsh-rust-dev/skills/rust-debugging/SKILL.md new file mode 100644 index 0000000..79b8531 --- /dev/null +++ b/packages/dsh-rust-dev/skills/rust-debugging/SKILL.md @@ -0,0 +1,369 @@ +--- +name: rust-debugging +description: The triage order for a Rust program that misbehaves - panic versus Result versus unwrap, RUST_BACKTRACE=1 versus full, how to read a backtrace (std at the bottom, your frames near the top, __rust_begin_short_backtrace as the boundary), why a panic in a thread can vanish, dbg! versus println! versus tracing with RUST_LOG, isolating a failure into one #[test] with --nocapture, reproducing with --release when it only fails there (overflow checks, debug assertions, different optimizations), and when reading a macro expansion is the only way to see what is real. +whenToUse: Use when a Rust program panics, returns an error nobody explained, prints nothing where output was expected, only fails in a release build, only fails in a test, or when a backtrace needs to be turned into a file and a line before anything is changed. +--- + +# Debugging a Rust program + +Rust fails loudly and in a small number of shapes. Knowing which shape you are in +is most of the work: a panic, a `Result` nobody checked, a test that was filtered +out, or an optimized build where the thing you were watching was compiled away. + +## A panic is a report, not a crash + +A panic unwinds by default: it walks back through the stack, runs destructors, +prints a message to **stderr**, and the main thread exits with status **101**. The +message is the whole diagnosis unless a backtrace was asked for. + +| spelling | what it does | when to use | +|---|---|---| +| `x.unwrap()` | panics with the `Debug` of the error | a fixture, a test, an example - never a request | +| `x.expect("loading the config")` | panics with YOUR words plus the `Debug` of the error | a real invariant, where the message names what was being done | +| `?` | returns the error to the caller | anything a caller could handle | +| `panic!("...")` | unwinds on purpose | an impossible state, not an expected failure | +| `todo!()` / `unimplemented!()` | panics with a marker | a branch you have not written yet | + +The difference between `unwrap` and `expect` is not style: a bare +`called `Result::unwrap()` on an `Err` value: ...` says nothing about which of +twelve unwraps fired, and the backtrace is what you will need to find out. + +```sh +RUST_BACKTRACE=1 cargo run +``` + +`RUST_BACKTRACE=0` (or unset) prints the one-line panic plus a note. `1` prints a +resolved stack. `full` prints every frame including std's, with addresses - longer +and noisier, and sometimes the only version that shows a frame that `1` dropped. + +In a release build the default has no debug info, so `1` prints frames **without +file and line**. `debug = 1` fixes that without the size of a full debug build: + +```toml +[profile.release] +debug = 1 # line tables only: readable backtraces, a small binary +``` + +## Reading a backtrace + +```text +thread 'main' panicked at src/parse.rs:9:37: +called `Result::unwrap()` on an `Err` value: ParseIntError { kind: PosOverflow } +note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace +``` + +```text + 0: rust_begin_unwind + at /rustc/06e4d1a1c9ff.../library/std/src/panicking.rs:645:5 + 1: core::panicking::panic_fmt + 2: core::result::unwrap_failed + 3: app_cli::parse_port + at ./src/parse.rs:9:37 + 4: app_cli::main + at ./src/main.rs:4:5 + 5: core::ops::function::FnOnce::call_once + 6: std::sys::backtrace::__rust_begin_short_backtrace + 7: std::rt::lang_start::{{closure}} + 8: main + 9: __libc_start_main +``` + +Read it bottom-up if you like, but the positions are the point: + +1. **Frame 0 is innermost** - the panic itself. Frames are printed from the + panic outward toward `main`. +2. **Your frames are the ones with `./src/...`**, and they sit just above the + boundary. `app_cli::parse_port` and `app_cli::main` are the code to look at. +3. **`__rust_begin_short_backtrace` is the boundary.** Below it is std's runtime + (`std::rt::lang_start`, the C `main`, `__libc_start_main`): machinery you never + wrote and cannot fix. Above it, in a `full` backtrace, + `__rust_end_short_backtrace` marks the other end, just under the panic + plumbing. Everything between the two markers is the short backtrace - the part + that is yours. +4. **The `at` line tells you whose code it is:** + +| path in the frame | what it is | +|---|---| +| `./src/parse.rs` | your crate | +| `/rustc//library/std/src/...` | the standard library, built with the toolchain | +| `~/.cargo/registry/src/.../-/...` | a dependency | +| `~/.cargo/git/checkouts/...` | a git dependency | + +A frame with no `at` line was inlined, or its crate was built without debug info. + +`rust_backtrace` does this reading for you: it demangles the symbols (both the +legacy `_ZN...` mangling and the newer `_R...` v0), attaches `file:line` where the +toolchain recorded it, and separates **your workspace frames** from dependency +frames - which is the distinction that decides whether the bug is in your call or +in somebody else's library. + +## A panic in a thread can vanish + +`std::thread::spawn` returns a `JoinHandle`, and the panic inside the thread is +captured and delivered to whoever **joins**. If nobody joins, the process exits +with the main thread's status - which is `0` - and the only evidence is the panic +message printed on stderr by the panicking thread. + +```rust +#![allow(dead_code)] + +// A panic in a worker thread does NOT fail the process. `join` is what turns it into +// a value you can report; without a join, the exit status is main's, and the message +// on stderr may be the only trace of the failure. +pub fn double_first(items: Vec) -> Result { + let handle = std::thread::spawn(move || { + let first = items.first().copied().expect("the list is empty"); + first * 2 + }); + handle.join().map_err(panic_message) +} + +fn panic_message(payload: Box) -> String { + if let Some(text) = payload.downcast_ref::<&str>() { + (*text).to_owned() + } else if let Some(text) = payload.downcast_ref::() { + text.clone() + } else { + "non-string panic payload".to_owned() + } +} +``` + +The payload is `Box` and it is **either** a `&'static str` (a +`panic!("literal")`) **or** a `String` (a `panic!("formatted {}", x)`), which is +why a downcast has to try both. + +`catch_unwind` is the same boundary for code that cannot afford to die: + +```rust +#![allow(dead_code)] + +use std::panic::{catch_unwind, AssertUnwindSafe}; + +// The other boundary: an unwind becomes a `Result`, so one bad input does not take +// the process with it. `AssertUnwindSafe` is a promise that a half-updated value is +// acceptable after the unwind - a promise, not a check. +pub fn guarded(input: &str) -> Result { + catch_unwind(AssertUnwindSafe(|| { + input.parse::().expect("not a number") + })) + .map_err(|payload| { + payload + .downcast_ref::() + .cloned() + .or_else(|| payload.downcast_ref::<&str>().map(|text| (*text).to_owned())) + .unwrap_or_else(|| "non-string panic payload".to_owned()) + }) +} +``` + +Both mechanisms are gone under `panic = "abort"`: there is no unwind to catch, and +a panicking thread aborts the process. If a build has `panic = "abort"`, a +vanishing thread cannot be recovered, only logged. + +## `dbg!` versus `println!` versus `tracing` + +| tool | goes to | prints | returns | use it for | +|---|---|---|---|---| +| `println!` | stdout | what you formatted | `()` | a program's actual output | +| `eprintln!` | stderr | what you formatted | `()` | a diagnostic that must not corrupt stdout | +| `dbg!` | stderr | `file:line:col`, the expression, the value | **the value** | a temporary look inside an expression | +| `tracing` / `log` | whatever the subscriber chose | a level, a target, structured fields, spans | `()` | anything you want to keep | + +```rust +#![allow(dead_code)] + +// `dbg!` writes to stderr, prints `file:line:col` and the expression, and RETURNS +// the value - so it fits inside an expression instead of beside it. +pub fn scale(values: &[i32]) -> Vec { + let factor = dbg!(values.len().max(1) as i32); + values.iter().map(|value| dbg!(value * factor)).collect() +} +``` + +`dbg!` is the right tool for ten minutes and the wrong one for a codebase: it +cannot be turned off, it has no level, and it serializes every value it touches. +Remove it before finishing - `grep -rn 'dbg!' src/` is the whole check. + +`tracing` is the one that survives into production. The important difference from +`println!` is not the levels: it is that a `tracing` event can carry typed FIELDS +and live inside a SPAN, so a log line says which request it came from. + +```toml +[dependencies] +tracing = "0.1" +tracing-subscriber = { version = "0.3", features = ["env-filter"] } +``` + +```sh +RUST_LOG=debug cargo run +RUST_LOG=info,my_crate=trace,h2=off cargo run +``` + +`RUST_LOG` is read by the `EnvFilter` the program installs, not by `tracing` +itself - a binary that never calls `tracing_subscriber::fmt().with_env_filter(..)` +ignores the variable entirely, and `println!` ignores it always. + +## Isolate the failure into one test + +A failing test is the cheapest reproduction there is: no UI, no arguments, no +services. Three flags do most of the work. + +```sh +cargo test parse_port -- --nocapture +cargo test parse_port -- --exact --nocapture +cargo test --lib -- --test-threads=1 +``` + +- the filter is a substring of the test PATH, so `cargo test parse` runs every + test whose module or name contains `parse`; +- `--nocapture` keeps the test's stdout/stderr instead of hiding it under the + harness - without it a `println!` inside a passing region never appears; +- `--test-threads=1` is for a test that shares a resource (a port, a file, an env + var) and fails only when run beside its siblings. + +```rust +#![allow(dead_code)] + +pub fn parse_port(text: &str) -> Result { + text.trim() + .parse::() + .map_err(|err| format!("{text:?} is not a port: {err}")) +} + +#[cfg(test)] +mod tests { + use super::parse_port; + + #[test] + fn rejects_a_value_too_large_for_u16() { + assert!(parse_port("70000").is_err()); + } + + #[test] + fn accepts_a_normal_port() { + let port = parse_port("8080").expect("8080 is a port"); + assert_eq!(port, 8080); + } +} +``` + +Write the failing case FIRST, at the smallest input that still fails, and run it +until it fails for the reason you think it does. A test that fails for a different +reason is not a reproduction. + +## It only fails in `--release` + +Three real differences, and one fake one: + +| difference | dev | release | +|---|---|---| +| `overflow-checks` | on - `u8 + 1` at 255 **panics** | off - it **wraps** silently | +| `debug-assertions` | on - `debug_assert!` runs | off - compiled out entirely | +| optimization | none | inlining and reordering, which can expose UB or change its symptoms | +| `debug = false` | full debug info | frames without `file:line` unless `debug = 1` | + +```rust +#![allow(dead_code)] + +// The same expression, two profiles: `+` panics on overflow in dev and wraps in +// release, because `overflow-checks` follows the profile. `wrapping_add` says which +// one you meant. +pub fn add_one(value: u8) -> u8 { + value.wrapping_add(1) +} + +// `debug_assert!` is compiled OUT of a release build, so a check that only exists +// there cannot catch a release bug. +pub fn checked_percent(part: u32, whole: u32) -> u32 { + debug_assert!(whole > 0, "whole must be non-zero"); + if whole == 0 { + return 0; + } + part.saturating_mul(100) / whole +} + +pub fn profile_is_debug() -> bool { + cfg!(debug_assertions) +} +``` + +To decide which of the three it is: rebuild with the checks turned back ON in +release. If the bug becomes a panic with a line number, it was checked arithmetic +or a debug assertion; if it stays a wrong answer, you are looking at +optimization-exposed undefined behaviour (`unsafe`, a stale `static mut`, a +transmute, an out-of-bounds raw pointer) - and then the tool is not a print +statement but `cargo miri` on nightly, which is a different investigation. + +```sh +cargo run --release +cargo test --release +CARGO_PROFILE_RELEASE_OVERFLOW_CHECKS=true cargo run --release +``` + +## When only the expansion shows what is real + +A macro error points at the invocation AND at the macro's own body, but never at +the code you would have written. `#[derive(Serialize)]` generating a failing impl +is the classic: the error names a type in a function you never wrote. + +```rust +#![allow(dead_code)] + +// A `macro_rules!` error points at the CALL SITE and then at the macro's own body, +// which is why an error inside a big macro is hard to read: the tokens that failed +// were never written on that line. +macro_rules! sum_of { + ($($value:expr),+ $(,)?) => {{ + let mut total = 0_i64; + $( total += $value as i64; )+ + total + }}; +} + +pub fn totals() -> (i64, i64) { + (sum_of!(1, 2, 3), sum_of!(4, 5,)) +} +``` + +Four ways to see the generated code, cheapest first: + +1. **`dbg!` inside the macro** (or a `compile_error!` in the arm you think fired) - + no tooling, one rebuild. +2. **`cargo expand`** - the readable one. It is a separate binary the plugin does + NOT install, so this is a command to hand the person: `cargo install + cargo-expand`, then `cargo expand --lib path::to::module`. +3. **`-Zunpretty=expanded`** on a nightly toolchain: + `cargo +nightly rustc --lib -- -Zunpretty=expanded`. +4. **The `--pretty=expanded`-style diff** is what a `cargo expand` section in a + pull request is for: paste the expansion when the fix is "the macro did + something surprising", because the next reader needs to see the tokens too. + +## What the tools answer + +- `cargo_test` returns the libtest summary, the failing test NAMES and the first + failure's captured output - which is the `--nocapture` text you would otherwise + have to re-run to see. +- `rust_backtrace` takes the panic output and returns demangled frames with + `file:line`, workspace frames separated from dependency frames. Paste the raw + backtrace; do not trim it, because the boundary frame is near the bottom. +- `cargo_build` with `run: true` executes the built binary and reports its exit + code and output - the only one of the six that can observe a panic in a real + run. On a host with no display, a GUI binary started this way fails with a + windowing error rather than running. + +## What not to do + +- Do not add `println!` to a library that a test or a server uses; use `dbg!` + during the investigation and remove it, or `tracing` for anything that stays. +- Do not read a backtrace from the top and stop at the first frame. The first + frames are the panic machinery; the code is the first frame that names your + crate. +- Do not call `.unwrap()` to "see the error" in code that will ship. It converts a + recoverable failure into a process exit, and it discards the context that + `.expect("what I was doing")` would have written. +- Do not debug a release-only bug in a debug build. Reproduce it where it happens + first. +- Do not spawn a thread and drop its `JoinHandle` if its failure matters. That is + how a failure becomes a missing log line. +- Do not chase a macro error by reading the macro. Expand it. diff --git a/packages/dsh-rust-dev/skills/rust-diagnostics/SKILL.md b/packages/dsh-rust-dev/skills/rust-diagnostics/SKILL.md new file mode 100644 index 0000000..c215fed --- /dev/null +++ b/packages/dsh-rust-dev/skills/rust-diagnostics/SKILL.md @@ -0,0 +1,328 @@ +--- +name: rust-diagnostics +description: Reading what rustc and clippy actually say - how a diagnostic is structured (level, code like E0308, the primary span, help/note/suggestion), the fifteen error codes a Rust developer meets weekly and the first fix for each, why clippy lints have names instead of codes, lint levels and why `#[expect]` beats `#[allow]`, `-D warnings` in CI, MSRV (`rust-version`) and how a newer lint breaks an older toolchain, and why the FIRST error is the one to read. +whenToUse: Use when a build or check has errors and the next move is not obvious, when quoting a diagnostic to a person, when deciding whether to fix or suppress a warning, when a `-D warnings` CI run fails on a lint that looks harmless, or when a toolchain bump starts failing on code that did not change. +--- + +# Reading a Rust diagnostic + +A diagnostic is a structured report, not a text blob: it has a level, usually a +code, spans with byte-precise locations, and often a machine-applicable +suggestion. Reading it in the right order is the difference between one fix and +a dozen guesses. + +## The shape of one + +```text +error[E0308]: mismatched types + --> src/parse.rs:7:18 + | +7 | let port: u16 = "8080"; + | --- ^^^^^^ expected `u16`, found `&str` + | | + | expected due to this + | +help: parse it instead + | +7 | let port: u16 = "8080".parse().unwrap(); + | +++++++++++++++++++++++ +``` + +| part | what it is | +|---|---| +| `error` | the level: `error`, `warning`, `note`, `help`. Only `error` fails a build | +| `[E0308]` | the code. Stable, documented, and searchable offline with `rustc --explain E0308` | +| `mismatched types` | the message. It names the two types in the spans, not here | +| `--> src/parse.rs:7:18` | file, line, column (1-based) of the PRIMARY span | +| `^^^^^^` | the primary span: where the error is | +| `---` | a secondary span: where the expectation comes from | +| `help:` / `note:` | the explanation and, when it carries a `+`/`-` diff, a suggestion `cargo fix` can apply | +| `warning: unused ...` | a level with no code. A lint name appears in the message instead: `unused_variables` | + +Read it in this order: **code and message**, then the primary span, then any +`help`. The `--` / `^^` alignment is decoration; the `file:line:col` above it is +the fact, and it is what to quote. + +## The fifteen codes you meet weekly + +| code | the message | usual cause | first fix | +|---|---|---|---| +| `E0308` | mismatched types | `&str` where `String` is wanted, a missing `.parse()`, an integer of the wrong width | make the types agree, or convert once, explicitly | +| `E0277` | the trait bound is not satisfied | the type does not implement a needed trait (`Display`, `Clone`, `Send`, `Default`) | `#[derive]` it, implement it, or change the bound | +| `E0382` | use of moved value | a non-`Copy` value was moved, then used again | borrow it, clone it, or restructure so it is owned once | +| `E0499` | two mutable borrows at once | a `get_mut` in a loop, two `&mut` into one collection | `split_at_mut`, indices, or end the first borrow | +| `E0502` | mutable borrow while an immutable one is live | reading and mutating one collection in a single expression | compute the read first, then mutate | +| `E0505` | cannot move out because it is borrowed | moving a value a reference still points at | drop or end the borrow first, or clone | +| `E0507` | cannot move out of borrowed content | `*x` where `x: &T`, moving a field out of `&self` | `mem::take`, `mem::replace`, or borrow | +| `E0515` | cannot return a reference to a local | returning `&local` or a slice of a temporary | return the owned value | +| `E0597` | does not live long enough | a borrow outlives the value it points at | bind the value outside the borrow, or take ownership | +| `E0716` | temporary value dropped while borrowed | a temporary produced inside a chain dies at the end of the statement | bind the temporary to a `let` | +| `E0433` | failed to resolve: undeclared crate or module | a missing `use`, a feature not enabled, a dependency not declared | add the `use`, the feature, or the dependency | +| `E0425` | cannot find value in this scope | a typo, or an item behind `cfg` that is not on | check the name and the `cfg` | +| `E0061` | wrong number of arguments | the signature changed under you | the `help:` line prints the signature to copy | +| `E0596` | cannot borrow as mutable | the binding is not `mut`, or the value is behind `&` | `let mut` / `&mut`; interior mutability only if it is really needed | +| `E0658` | unstable feature | code written against nightly, compiled on stable | remove it, or pin nightly on purpose in `rust-toolchain.toml` | + +Two of those deserve a sentence each, because their names are misleading: + +- **`E0597` is a lifetime error but not usually a lifetime problem.** It says a + borrow outlives its value; the fix is almost always to give the value a home + (`let owned = ...;` then use `&owned`), not to add a lifetime parameter. +- **`E0716` looks like a lifetime error too**, and it is the same fix: bind the + temporary. `let name = format!(...); let slice = name.trim();` compiles where + `let slice = format!(...).trim();` does not. + +## Clippy is a different vocabulary + +rustc reports language errors with codes. Clippy reports SUSPICIOUS BUT VALID +code with NAMED LINTS - there is no `E` number for a Clippy lint. + +```text +warning: this loop could be written as an iterator chain + --> src/lib.rs:12:5 + | +12 | / for value in values { +13 | | out.push(value * 2); +14 | | } + | |_____^ help: consider using an iterator: `...` + | + = note: `#[warn(clippy::manual_map)]` implied by `#[warn(clippy::all)]` +``` + +The note names the lint and the group that enabled it (`clippy::all` by +default). Lint groups are not severity levels: `correctness` and `suspicious` +are warn-by-default, `style`, `complexity` and `perf` are in `all`, and +`pedantic`, `nursery` and `restriction` are opt-in. + +```sh +cargo clippy --all-targets --all-features -- -D warnings +cargo clippy --fix --all-targets --allow-dirty +``` + +`--fix` applies the machine-applicable suggestions only. A lint with `help: +consider ...` and no diff is a judgement call, not a rewrite, and Clippy will not +make it for you. + +## Lint levels, and why `expect` beats `allow` + +| attribute | effect | +|---|---| +| `#[allow(lint)]` | silence it here and in nested items | +| `#[warn(lint)]` | the default for most lints | +| `#[deny(lint)]` | make it an error here | +| `#[forbid(lint)]` | make it an error and refuse any inner `allow` for it | + +Levels are set per item, per module or per crate (`#![allow(...)]` at the top of +a file), and the innermost one wins. `#[allow]` on an expression works for many +lints; on a statement it covers the whole statement. + +**`#[expect(lint, reason = "...")]` is the better spelling when you mean "this +is deliberate and should stop being true someday"** (Rust 1.81+). It silences +the lint AND warns with `unfulfilled_lint_expectations` when the lint stops +firing - so the day the code is fixed, the suppression is reported instead of +rotting in place. `#[allow]` can never tell you that it became dead. + +```rust +#![allow(dead_code)] + +// A suppression a reader can audit: the lint is named, and the reason is beside it. +// (Rust 1.81's `#[expect(unused_variables, reason = "...")]` is the better spelling: +// it fails the build when the lint STOPS firing, so a dead suppression cannot survive.) +#[allow(unused_variables)] +pub fn on_event(kind: &str, payload: &[u8]) -> usize { + payload.len() +} +``` + +Prefer suppressing at the smallest scope that works. A crate-wide `allow` hides +a real bug in the next function; an item-level one names its target. + +## `-D warnings` in CI, and the `[lints]` table + +A warning is not a failure unless you make it one. Three ways, in order of +preference: + +```toml +[lints.rust] +unsafe_code = "forbid" + +[lints.clippy] +pedantic = "warn" +needless_return = "allow" +``` + +That table (Rust 1.74+) is checked in, applies to every invocation, and needs no +shell. The environment form is `RUSTFLAGS="-D warnings"`, which applies to every +crate including dependencies - useful for your own tree, hostile to a dependency +that emits a warning on a newer compiler. `#![deny(warnings)]` in a source file +is the worst option: it makes your crate fail on a warning added by a future +compiler you have not tried yet. + +## MSRV, and the lint that breaks an older toolchain + +`rust-version = "1.78"` in `[package]` is a promise cargo enforces: a build with +an older toolchain stops immediately with a message naming the requirement, +instead of failing somewhere inside a dependency with a parse error. + +The trap is that clippy GROWS. A lint added in 1.83 fires on code that was clean +at 1.78, so a `-D warnings` job on the newer toolchain fails while `cargo check` +on the MSRV still passes. Three honest answers: + +1. run `cargo check` on the MSRV toolchain and clippy only on stable, and say so + in the CI file; +2. suppress the new lint by name at the smallest scope, with a reason; +3. raise `rust-version`, and say why in the same commit. + +```sh +rustup toolchain install 1.78 +cargo +1.78 check --all-targets +cargo +1.78 test --lib +``` + +A toolchain file makes the intent explicit rather than conventional: + +```toml +# rust-toolchain.toml at the workspace root +[toolchain] +channel = "1.78.0" +components = ["rustfmt", "clippy"] +``` + +## Read the first error first + +rustc reports many errors per run, and most of them are consequences. One +unresolved import produces a dozen `E0308`s: a type that failed to resolve +becomes `{unknown}`, and every use of it mismatches. Fixing the first error +often deletes the rest. + +The practical order: + +1. the first `error` in **cargo's** order, which is the member order and then the + source order - not alphabetical; +2. if the first error is `E0433`/`E0425` (a name that does not exist), fix that + before reading any type error after it; +3. re-run. Do not queue up twelve fixes from one run. + +`--message-format=short` compresses to one line per diagnostic, which is how to +count them; the plugin's `cargo_check` does that in JSON and returns counts by +level plus the codes, so a repeated code is visible without reading 400 lines. + +```sh +cargo check --workspace --all-targets --message-format=short +cargo check --workspace 2>&1 | grep -c '^error' +``` + +## The fixed pattern, for the borrow errors + +The four errors that cost the most time are all about borrowing, and each has a +small canonical fix. + +```rust +#![allow(dead_code)] + +// E0502 - mutable borrow while an immutable one is live. The immutable borrow ends +// at its last use, so computing the value first is the whole fix. +pub fn bump_first_even(items: &mut Vec) { + let first = items.first().copied().unwrap_or_default(); + if first % 2 == 0 { + items.push(first + 2); + } +} +``` + +```rust +#![allow(dead_code)] + +// E0499 - two `&mut` into one Vec. `split_at_mut` produces two DISJOINT mutable +// borrows from one, which is what the borrow checker can actually prove is safe. +pub fn swap_halves(values: &mut [i32]) { + let mid = values.len() / 2; + let (left, right) = values.split_at_mut(mid); + for (a, b) in left.iter_mut().zip(right.iter_mut()) { + std::mem::swap(a, b); + } +} +``` + +```rust +#![allow(dead_code)] + +// E0515 / E0597 - a reference cannot outlive its value. Return the value, and let +// the caller borrow it: an owned String has no lifetime to get wrong. +pub fn shout(text: &str) -> String { + let mut owned = text.to_uppercase(); + owned.push('!'); + owned +} + +pub fn first_word(text: &str) -> &str { + text.split_whitespace().next().unwrap_or("") +} +``` + +```rust +#![allow(dead_code)] + +// E0507 - cannot move out of a shared reference. `mem::take` leaves a default +// value behind and hands the old one away, which is the move the compiler wanted. +#[derive(Default)] +pub struct Config { + pub name: String, + pub retries: u8, +} + +impl Config { + pub fn take_name(&mut self) -> String { + std::mem::take(&mut self.name) + } +} + +pub fn describe(config: &Config) -> String { + format!("{} ({} retries)", config.name, config.retries) +} +``` + +```rust +#![allow(dead_code)] + +// E0277 - the trait bound. `format!` needs Display; Debug is not enough. Either +// implement the trait the code asks for, or derive the one it needs. +#[derive(Debug)] +pub struct Port(u16); + +impl std::fmt::Display for Port { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "tcp/{}", self.0) + } +} + +pub fn announce(port: Port) -> String { + format!("listening on {port}") +} +``` + +## What the tools answer + +- `cargo_check` returns counts by level, the diagnostic CODES, `file:line:col` and + the top N diagnostics - so a run of twelve `E0308` after one `E0433` is visible + as exactly that, without reading the whole log. +- `cargo_build` returns the warning count of a successful build, which is the + number to drive to zero before turning on `-D warnings`. +- `rust_status` tells you whether the component a message assumes (clippy, + rustfmt) is even installed, and which toolchain is in use - a diagnostic that + quotes a lint you cannot reproduce is usually a different toolchain. + +## What not to do + +- Do not fix the last error in a run first. It is usually a consequence. +- Do not quote a diagnostic without its code and its `file:line:col`; that is + what makes it searchable and reproducible. +- Do not reach for `#[allow]` before reading the `help:`. The compiler's + suggestion is right more often than the first instinct to silence it. +- Do not add `#![deny(warnings)]` to a crate. Adding a lint in a later compiler + is not a semver-compatible change to your code. +- Do not paste a `help:` diff into someone else's file by hand: `cargo fix` and + `cargo clippy --fix` apply the machine-applicable ones, and refuse the ones + that are judgements. +- Do not treat a `-D warnings` failure on a newer toolchain as a code bug before + checking whether the lint is simply new. diff --git a/packages/dsh-rust-dev/skills/rust-ui-apps/SKILL.md b/packages/dsh-rust-dev/skills/rust-ui-apps/SKILL.md new file mode 100644 index 0000000..a11c6ac --- /dev/null +++ b/packages/dsh-rust-dev/skills/rust-ui-apps/SKILL.md @@ -0,0 +1,398 @@ +--- +name: rust-ui-apps +description: Desktop applications with egui, eframe and wgpu - the App trait and run_native, Context being cheap to clone while Ui is per-frame, immediate-mode consequences (state lives in your struct), update() and request_repaint, CentralPanel/SidePanel/Window, Renderer::Wgpu versus Glow and wgpu::Backends::PRIMARY versus SECONDARY, the dev-build slowness that bites every egui app and the profile fix for it, where the binary lands, cross-compiling with --target, and the per-OS runtime dependency shape where the GPU driver is the runtime's business and not cargo's. +whenToUse: Use when building or debugging a Rust GUI with egui/eframe/wgpu, when the window is blank or does not repaint, when the app feels slow in a debug build, when choosing a renderer or a wgpu backend, when cross-compiling a GUI, or when a binary that builds fine fails to start on another machine. +--- + +# Desktop UIs with egui, eframe and wgpu + +egui is **immediate mode**: every frame, the UI is rebuilt from your state by +running your code again. There are no widget objects to keep, no signals to +connect, and no retained tree to invalidate. The consequences of that one fact are +almost everything below. + +## The frame is the unit + +`eframe` owns the window and the event loop. It calls one method on one struct, and +the whole contract is its signature: +`fn update(&mut self, ctx: &egui::Context, frame: &mut eframe::Frame)`. + +- **`&mut self`** is your whole application state. A widget cannot remember + anything, so a checkbox's value is your `bool` field and a text field's contents + are your `String`. +- **`ctx`** is the `egui::Context`: the shared runtime. It is cheap to **clone** + (an `Arc` behind it), it is `Send + Sync`, and a clone can wake the UI from a + worker thread. +- **`frame`** is eframe's per-frame handle: window information, storage, and - with + the wgpu renderer - the `RenderState` that owns the device. + +A `Ui` is a region of ONE frame. It is created by a panel or a window, handed to +your closure, and dropped when the closure returns. Storing a `Ui` in your struct +does not work; storing the values you read from it is the whole pattern. + +## The smallest real app + +```rust,ignore +use eframe::egui; + +struct Counter { + clicks: u32, +} + +impl eframe::App for Counter { + fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) { + egui::CentralPanel::default().show(ctx, |ui| { + ui.heading("Counter"); + if ui.button(format!("clicked {} times", self.clicks)).clicked() { + self.clicks += 1; + } + }); + } +} + +fn main() -> eframe::Result { + let options = eframe::NativeOptions { + viewport: egui::ViewportBuilder::default().with_inner_size([420.0, 180.0]), + ..Default::default() + }; + // The closure returns a Result: `Ok(Box::new(app))`, or an error to abort startup. + eframe::run_native( + "counter", + options, + Box::new(|_cc| Ok(Box::new(Counter { clicks: 0 }))), + ) +} +``` + +Four details in that shape that are worth knowing rather than discovering: + +1. **`run_native` returns `eframe::Result`**, which is `Result<(), eframe::Error>`. + `fn main() -> eframe::Result` is the idiomatic signature; `?` works inside it. +2. **The app closure returns a `Result`** because creation can fail: `Ok(Box::new(app))`. + The `CreationContext` argument (`cc` above) carries the `egui_ctx` and the + persistence `Storage`, which is where a settings load belongs. +3. **`NativeOptions` is `..Default::default()`-constructed.** Everything you do not + name keeps eframe's default, and that default is a working window. +4. **The window size is a `ViewportBuilder`**, not a tuple on `NativeOptions` + (`with_inner_size`, `with_title`, `with_min_inner_size`, `with_resizable`). + +## State lives in your struct, not in widgets + +Panels claim space in the order they are added, and `CentralPanel` takes whatever +is left - which is why it goes LAST. `Window` is the one surface that is not a +panel: it floats above them, can be dragged and resized, and its visibility is +usually bound to a `bool` in your struct. + +```rust,ignore +use eframe::egui; + +struct Tool { + name: String, + progress: f32, + show_help: bool, +} + +impl eframe::App for Tool { + fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) { + egui::SidePanel::left("side").show(ctx, |ui| { + ui.label("Tool"); + ui.separator(); + ui.checkbox(&mut self.show_help, "Help"); + }); + egui::TopBottomPanel::bottom("status").show(ctx, |ui| { + ui.label(format!("{:.0}%", self.progress * 100.0)); + }); + egui::CentralPanel::default().show(ctx, |ui| { + ui.text_edit_singleline(&mut self.name); + ui.add(egui::ProgressBar::new(self.progress)); + if ui.button("Advance").clicked() { + self.progress = (self.progress + 0.1).min(1.0); + } + }); + // A `Window` floats; `.open` binds its visibility to a field of YOUR struct, + // which is the only place UI state can live. + if self.show_help { + egui::Window::new("Help").open(&mut self.show_help).show(ctx, |ui| { + ui.label("A window is not a widget and keeps no state of its own."); + }); + } + // An animation needs a reason to draw the next frame. Without this, a pane + // repaints only on input, and a progress bar stops moving. + if self.progress > 0.0 && self.progress < 1.0 { + ctx.request_repaint_after(std::time::Duration::from_millis(16)); + } + } +} +``` + +The widget vocabulary that covers most applications: `ui.label`, `ui.heading`, +`ui.button`, `ui.checkbox`, `ui.radio_value`, `ui.text_edit_singleline`, +`ui.text_edit_multiline`, `ui.add(egui::Slider::new(&mut x, 0.0..=1.0))`, +`ui.add(egui::ProgressBar::new(f))`, `ui.separator`, `ui.horizontal`, +`ui.vertical`, `egui::ScrollArea::vertical()`, `egui::Grid::new("form")`, +`egui::CollapsingHeader::new("advanced")`. + +**Repainting is opt-in for animations and automatic for input.** eframe redraws +when something happens (a mouse move, a key, a resize); it does not redraw because +your state changed behind its back. `ctx.request_repaint()` asks for the next +frame immediately, `ctx.request_repaint_after(d)` asks for one after a delay - +which is what a poll should use instead of a busy loop. + +## A worker thread must wake the UI + +`Context` is `Send + Sync`, so a background thread can hold a clone and call +`request_repaint` when it has something to show. That is the whole integration +pattern: channel out, `request_repaint` in. + +```rust,ignore +use eframe::egui; +use std::sync::mpsc::{channel, Receiver}; + +struct Loader { + pending: Option>, + result: String, +} + +impl eframe::App for Loader { + fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) { + if let Some(rx) = &self.pending { + if let Ok(text) = rx.try_recv() { + self.result = text; + self.pending = None; + } + } + egui::CentralPanel::default().show(ctx, |ui| { + if ui.button("Load").clicked() && self.pending.is_none() { + let (tx, rx) = channel::(); + // `Context` is cheap to clone: the clone shares the one runtime behind + // it, and it is `Send`, so a worker thread can wake the UI with it. + let ctx = ctx.clone(); + std::thread::spawn(move || { + let text = "loaded".to_owned(); + let _ = tx.send(text); + ctx.request_repaint(); + }); + self.pending = Some(rx); + } + ui.label(&self.result); + }); + } +} +``` + +The alternative - blocking inside `update` - freezes the window, because `update` +runs on the event loop thread. There is no separate render thread to hide it. + +## Choosing the renderer: Glow or Wgpu + +eframe draws through one of two backends, chosen by Cargo features and then by a +field: + +```toml +[dependencies] +# `wgpu` pulls the wgpu renderer; `glow` is eframe's default. Enabling both is +# normal: the choice is made at startup, not at compile time. +eframe = { version = "0.29", features = ["wgpu", "default_fonts"] } +egui = "0.29" +wgpu = "23" +``` + +| | `Renderer::Glow` | `Renderer::Wgpu` | +|---|---|---| +| underlying API | OpenGL (via glow) | Vulkan, Metal, DX12 (and GL/WebGPU as secondary) | +| weight | smaller, fewer moving parts | a larger dependency tree and a larger binary | +| drivers | needs a working GL driver; often fine on old hardware and inside VMs with software GL | needs a Vulkan/Metal/DX12 driver; enumerates adapters | +| what it unlocks | egui's own drawing | custom `wgpu` render passes, compute shaders, your own 3D pipeline | +| typical failure | a black window where GL is missing | "no adapter found" where nothing accelerated is present | + +`egui_wgpu`'s configuration defaults to **`wgpu::Backends::PRIMARY`**, which is +Vulkan + Metal + DX12; `SECONDARY` (GL, DX11) is the fallback set. This matters +because the backend is a property of the wgpu setup, and in eframe 0.29 that lives +under `wgpu_options.wgpu_setup` (`WgpuSetup::CreateNew(..)`), not in the +long-standing `supported_backends` field - a name worth checking against the +version in your lock file rather than assuming. + +```rust,ignore +fn native_options() -> eframe::NativeOptions { + // Take the defaults and change ONLY the backend set: this is the field that + // decides which drivers get asked for an adapter. + let mut wgpu = eframe::egui_wgpu::WgpuConfiguration::default(); + if let eframe::egui_wgpu::WgpuSetup::CreateNew(setup) = &mut wgpu.wgpu_setup { + setup.instance_descriptor.backends = wgpu::Backends::PRIMARY; + } + eframe::NativeOptions { + renderer: eframe::Renderer::Wgpu, + wgpu_options: wgpu, + ..Default::default() + } +} +``` + +Under that layer, the wgpu shape is always the same three steps - `Instance` → +`request_adapter` → `request_device` - and each can fail for a reason that is +about the MACHINE, not your code: no driver, a headless session, a VM without +acceleration. wgpu also reads an environment override for the backend +(`WGPU_BACKEND=vulkan|dx12|metal|gl`), which is the first thing to try when a user +reports a window that will not open. + +When a custom pass needs the device eframe is already using, ask `frame` for it +rather than creating a second `Device`: + +```rust,ignore +impl eframe::App for GpuPane { + fn update(&mut self, ctx: &egui::Context, frame: &mut eframe::Frame) { + // `wgpu_render_state` is `Some` only when the pane was started with + // `Renderer::Wgpu`. It hands out the SAME device and queue eframe draws with. + if let Some(state) = frame.wgpu_render_state() { + let device: &wgpu::Device = &state.device; + let queue: &wgpu::Queue = &state.queue; + let format: wgpu::TextureFormat = state.target_format; + let _ = (device, queue, format); + } + egui::CentralPanel::default().show(ctx, |ui| ui.label("gpu pane")); + } +} + +struct GpuPane; +``` + +## The dev-build trap, and it is the one that bites + +A debug build of an egui app is **dramatically slower than the release build** - +often several times slower, and sluggish enough to read as "egui is slow". The +cause is not egui: at `opt-level = 0` the tessellator, the layout pass and the +widget code are compiled without any of the optimizations they depend on for +smoothness. + +The fix is one profile stanza, and it is the reason this section exists: + +```toml +# Optimize your DEPENDENCIES, keep your own crate debuggable. This is the fix for +# "egui is slow in debug" and it works for any CPU-heavy dependency tree. +[profile.dev.package."*"] +opt-level = 2 + +# Optional: a middle ground for your own code (better runtime, still steppable). +[profile.dev] +opt-level = 1 +``` + +`[profile.dev.package."*"]` applies to dependencies only, so your breakpoints and +line numbers in `src/` are untouched while egui, winit and the font stack are +optimized. The alternative - `[profile.dev] opt-level = 1` for everything - is +simpler and less effective; the two can be combined. + +A release profile for a GUI usually wants the binary smaller rather than faster +still, because the frame cost is dominated by drawing: + +```toml +[profile.release] +lto = "thin" +codegen-units = 1 +strip = "symbols" +``` + +`strip = "symbols"` and readable release backtraces are a trade: keep `debug = 1` +while investigating, and strip at the point of shipping. + +## Where the binary lands + +| command | artefact | +|---|---| +| `cargo build` | `target/debug/` (`.exe` on Windows) | +| `cargo build --release` | `target/release/` | +| `cargo build --release --target ` | `target//release/` - **even when the triple is the host's own** | +| `cargo run --release` | builds, then runs the release artefact | + +```sh +cargo run --release +cargo build --release +ls -lh target/release/my-app +``` + +On macOS eframe produces a bare Mach-O binary, not a `.app` bundle; a bundle needs +a packager (`cargo-bundle` and similar), which this plugin does not install. On +Windows the `.exe` needs the MSVC runtime unless the CRT is linked statically. + +## Cross-compiling + +Cross-compiling a GUI is harder than cross-compiling a library, because the +windowing and GPU stacks need the target's system libraries and a linker. + +```sh +rustup target add x86_64-unknown-linux-gnu +cargo build --release --target x86_64-unknown-linux-gnu +``` + +That works only when a linker and the target's development libraries exist on the +build host. The honest rule: + +- **Linux → Linux of another architecture**: possible with a cross toolchain and + the target's X11/Wayland/GL packages (or `cross`, which runs the build in a + container). +- **Windows → Linux**: needs a Linux linker and the Linux headers; a container is + the practical route. +- **Anything → macOS**: needs the macOS SDK, which cannot be redistributed. Build + macOS artefacts on macOS. +- **Anything → Windows**: `x86_64-pc-windows-msvc` from Linux is possible with + `cargo-xwin`, but the MSVC CRT's licence is the reason it is awkward. + +The linker is named per target through the environment: + +```sh +CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER=x86_64-linux-gnu-gcc \ + cargo build --release --target x86_64-unknown-linux-gnu +``` + +## Runtime dependencies per OS + +| OS | what the app needs at RUN time | who supplies it | +|---|---|---| +| Linux | X11 or Wayland client libraries (`libxkbcommon`, `libwayland-client`, `libX11`), plus GL (`libGL`) for Glow or the Vulkan loader for Wgpu | the distribution; the eframe `x11` / `wayland` features decide which are used | +| Windows | nothing beyond the system DLLs; a DX12 or Vulkan driver for Wgpu | the OS, plus the GPU vendor's driver | +| macOS | nothing; Metal ships with the OS | the OS | + +Two facts that explain most "it works on my machine" GUI reports: + +1. **On Linux those libraries are loaded at RUNTIME**, by `dlopen` in winit, not + linked at build time. So the build succeeds on a machine with the headers + installed and the binary fails to start on one without the libraries, with an + error naming the `.so` it could not open. A `.deb`/AppImage lists them; a bare + binary does not. +2. **The GPU driver is the runtime's business, not cargo's.** No crate can install + a driver, and no `cargo` command can prove that the machine has one that works. + "No adapter found", a black window, or a crash inside `dlopen` of `libvulkan.so` + are environment facts; the answers are a driver install, a different + `WGPU_BACKEND`, or the Glow renderer as a fallback. + +## What the tools answer + +- `rust_status` reports the **targets** that are installed, which is what decides + whether `--target …` can even start, and the notable crates the workspace + declares (eframe, wgpu, winit), which tells you which renderer stack is in play. +- `cargo_build` reports the artefact PATH and its real size, plus elapsed time - + the answer to "did the release binary land in `target//release` or in + `target/release`". +- `cargo_build` with `run: true` executes the binary: on a host with a display that + proves the app starts, and on a headless one it fails with a windowing error, + which is a fact about the host rather than about the build. +- `cargo_test` is for the logic behind the UI: put state transitions in plain + functions and test those, because a GUI event loop is a poor test harness and + this plugin ships no headless UI driver. + +## What not to do + +- Do not store a `Ui` or a widget in your struct. Store the value; rebuild the + widget. +- Do not block inside `update`. Spawn, send the result over a channel, and + `request_repaint` when it arrives. +- Do not add `CentralPanel` before the side panels: it consumes the remaining + space, so the order is `SidePanel` / `TopBottomPanel` first, `CentralPanel` last. +- Do not animate with a sleep or a busy loop in `update`; use + `request_repaint_after`. +- Do not judge egui's performance from a debug build. Apply the + `[profile.dev.package."*"]` stanza first, then measure. +- Do not promise a cross-compiled GUI binary for an OS you did not build on. Test + on the target, or say the binary is untested there. +- Do not read a "no adapter" error as a code bug. Check `WGPU_BACKEND`, the + driver, and whether the session has a GPU at all. diff --git a/packages/dsh-rust-dev/skills/rust-workspaces/SKILL.md b/packages/dsh-rust-dev/skills/rust-workspaces/SKILL.md new file mode 100644 index 0000000..81c51c3 --- /dev/null +++ b/packages/dsh-rust-dev/skills/rust-workspaces/SKILL.md @@ -0,0 +1,358 @@ +--- +name: rust-workspaces +description: Cargo mechanics for a real workspace - [workspace] members and default-members, workspace inheritance (`workspace = true`), `-p` vs `--workspace`, the dev/release/test profiles and what opt-level / lto / codegen-units / debug actually trade, the target/ layout and --target-dir, --locked / --frozen / --offline, why build.rs and proc macros RUN during `cargo check` so a check is not a read-only inspection, feature unification and why two paths can enable different features of one crate, and Cargo.lock discipline (commit it for binaries, not for libraries). +whenToUse: Use before running any cargo command on a workspace, when a build picks a different profile or artefact than expected, when two crates disagree about one dependency's features, when a check fails with no network, when deciding what to commit of Cargo.lock, or before claiming that `cargo check` proved anything about a tree you did not write. +--- + +# Cargo workspaces + +Cargo is three things in one binary: a resolver (what versions, what features), a +build driver (which profile, which target, which artefact) and the owner of the +directory everything lands in. Most confusing cargo answers come from the second +and third, not from rustc. + +## The layout, and what each file owns + +```text +repo/ + Cargo.toml # [workspace] - members, resolver, the shared profile table + Cargo.lock # ONE lock, at the workspace root, shared by every member + crates/ + core/ cli/ ui/ # each with its own Cargo.toml + target/ # ONE target dir, workspace-wide +``` + +```toml +[workspace] +resolver = "2" +members = ["crates/*"] +default-members = ["crates/cli"] +exclude = ["examples/scratch"] +``` + +- **`members`** takes paths and globs. Everything it names is one `cargo build` + away; every member shares the root `Cargo.lock` and the root `target/`. +- **`default-members`** is what a bare `cargo build` / `cargo test` at the root + selects. Without it, the default is every member - which is why a workspace + with a slow integration crate builds it every time. `-p` still reaches the + others. +- **`resolver = "2"`** is required on a virtual workspace root (a root with no + `[package]`) and is the default inside an edition-2021 package. It stops + dev-dependencies, build-dependencies and normal dependencies from unifying + their features, and stops a target-specific dependency from enabling a feature + on a platform that is not being built. `resolver = "3"` is the edition-2024 + line and needs Rust 1.84 or newer. +- **`exclude`** keeps a directory out of the glob, which is what you want for a + scratch crate that does not compile. + +A member is one `Cargo.toml` with `[package]`, and it may be both a member and a +dependency of a sibling by path: + +```toml +[package] +name = "app-cli" +version.workspace = true +edition.workspace = true + +[dependencies] +app-core = { path = "../core" } +serde = { workspace = true } +``` + +## Inventory, then inheritance + +Inheritance exists so one version, one edition and one `rust-version` are written +once. The workspace root holds the values; members opt in: + +```toml +[workspace.package] +version = "0.4.0" +edition = "2021" +rust-version = "1.78" +license = "AGPL-3.0-only" + +[workspace.dependencies] +serde = { version = "1", features = ["derive"] } +tokio = { version = "1", features = ["rt-multi-thread", "macros"] } +``` + +```toml +[dependencies] +serde.workspace = true +tokio = { workspace = true, features = ["fs"] } +``` + +`workspace = true` inherits the version and the feature list and lets the member +ADD features - features are additive, so `features = ["fs"]` here and +`features = ["time"]` in another member means the final build of `tokio` has +both. There is no way to subtract a feature from a sibling's request; only +`default-features = false` on the declaration the workspace root writes can keep +a default set out of the graph. + +A member cannot override an inherited key in the same table. `version = "0.4.0"` +and `version.workspace = true` in one `[package]` is an error, not a preference. + +## `-p` versus `--workspace` + +| invocation | selects | +|---|---| +| `cargo build` | `default-members`, or every member when that is unset | +| `cargo build -p app-core` | that package, plus whatever it depends on | +| `cargo build -p app-core -p app-cli` | both, and their shared dependencies ONCE | +| `cargo build --workspace` | every member | +| `cargo build --workspace --exclude app-ui` | every member but one (`--exclude` requires `--workspace`) | + +`-p` takes the package NAME from its `Cargo.toml`, not the directory name - +`crates/core/` with `name = "app-core"` is `-p app-core`. `--all` is a deprecated +alias for `--workspace`; do not write new commands with it. + +Building several members in one invocation is not just convenience: the +dependencies compile once and the lock is resolved once, so +`cargo check --workspace` is usually faster than three `-p` checks in a row. + +```sh +cargo check --workspace --all-targets --offline +cargo check -p app-core --all-targets +cargo build --release --locked --offline +cargo tree -e features -i serde +cargo metadata --format-version 1 > metadata.json +``` + +## Profiles: what each key trades + +Two profiles exist without any configuration - `dev` and `release` - and `test` +and `bench` inherit from them. The defaults that explain most surprises: + +| key | `dev` | `release` | what it trades | +|---|---|---|---| +| `opt-level` | 0 | 3 | speed of the built code against compile time and debuggability | +| `debug` | `true` (full) | `false` | line tables and variable info; `false` makes a release backtrace nearly useless | +| `debug-assertions` | `true` | `false` | `debug_assert!` and some std internal checks | +| `overflow-checks` | `true` | `false` | **arithmetic on integers panics in dev and WRAPS in release** | +| `incremental` | `true` | `false` | rebuild speed against a small code-quality cost | +| `codegen-units` | 256 | 16 | parallelism of codegen against inlining; `1` is the slowest and best-optimised | +| `lto` | `false` | `false` | link-time inlining across crates; `"thin"` is the usual upgrade, `true`/`"fat"` the slow one | +| `panic` | `unwind` | `unwind` | `"abort"` shrinks the binary and removes `catch_unwind` | +| `strip` | `"none"` | `"none"` | symbol removal; `"symbols"` shrinks a release binary and erases a backtrace | + +```toml +[profile.release] +lto = "thin" +codegen-units = 1 +panic = "abort" +strip = "symbols" + +[profile.dev] +# Keeps rebuilds incremental while making the hot dependency paths bearable. +opt-level = 1 +``` + +Two facts that follow and that people hit weekly: + +1. **`overflow-checks` is a behaviour difference, not a debugging aid.** A bug + that only appears with `--release` is very often a wrap that panicked in dev. + `[profile.release] overflow-checks = true` is how you find out. +2. **`debug = false` in release is why a release backtrace has addresses and no + line numbers.** `[profile.release] debug = 1` gives line tables without the + full variable payload. + +`[profile.dev.package."*"]` applies a profile to DEPENDENCIES only, which is the +cheapest way to make a slow debug build usable without losing your own +breakpoints - the reason GUI builds need it is in `rust-ui-apps`. + +## `target/`, and where the artefact actually lands + +```text +target/ + CACHEDIR.TAG # tells backup tools to skip this tree + debug/ # dev profile, host triple + release/ # release profile, host triple + /debug/ # ONLY when --target was passed, even if it is the host triple + /release/ + doc/ # cargo doc + package/ # cargo package + tmp/ # the scratch dir build scripts get as OUT_DIR's neighbour +``` + +`--target ` moves the output under `target//` **even when the +triple is the host's own**, which is the classic "my binary vanished" report: the +build succeeded and wrote somewhere else. The plugin's `cargo_build` reports the +path it actually used for this reason. + +- `CARGO_TARGET_DIR` and `--target-dir ` relocate the whole tree. One shared + directory across checkouts saves gigabytes; it also means two toolchains write + into the same fingerprints, so a `rust-toolchain.toml` bump invalidates it + wholesale. +- Different feature sets share a directory without colliding, because features + are part of the fingerprint. Do not assume "the same target dir" means "the + same build". + +## `--locked`, `--frozen`, `--offline` + +| flag | lock file | network | +|---|---|---| +| `--locked` | must already be correct; cargo ERRORS instead of updating it | unchanged | +| `--offline` | may be updated, from what is already cached | refused; a missing crate is an error | +| `--frozen` | `--locked` | `--offline` | + +`--frozen` is exactly `--locked` plus `--offline`, and it is the flag for a CI +job or a check that must be reproducible: it fails rather than silently resolving +a version nobody reviewed. + +`CARGO_NET_OFFLINE=true` is the environment form of `--offline`, which is what +this plugin sets for every cargo call unless a tool is given `fetch: true`. That +is deliberate: a check that reaches the network is a check that fails on a plane, +on a locked-down runner, and on a machine whose registry credentials expired - +three failures that say nothing about the code. + +The consequence to plan for: a crate that was never fetched cannot be checked +offline, and neither can a `build.rs` that downloads anything. The error names +the crate; the fix is a fetch, not a code change. + +## `build.rs` and proc macros RUN during `cargo check` + +This is the part that makes "just check it" unsafe on a tree you do not trust. + +- A **build script** (`build.rs`) is compiled and EXECUTED before the crate is + type-checked, because rustc needs its output: `cargo:rustc-link-lib`, + `cargo:rustc-cfg`, generated source in `OUT_DIR`. It runs with your user's + privileges, in your checkout, with the network available unless you refuse it. +- A **proc macro** is a separate crate compiled to a host library and LOADED INTO + THE COMPILER PROCESS. `#[derive(Serialize)]` is arbitrary code running inside + rustc, in the same process, on the same machine. + +So `cargo check` on an unfamiliar dependency tree executes its build scripts and +its proc macros. It is a build with the backend skipped, not a read-only +inspection. The plugin never fetches or installs a crate, and every call is +offline for the same reason: the fewer new trees a check pulls in, the less of +this happens. + +Two more consequences worth knowing: + +- `cargo check` does **not link the final binary**. A missing system library + (`-lssl`, a missing `.so`, a linker error) can pass `check` and fail `build`. + "Check is green" means the types are right, not that the crate links. +- `cargo check --all-targets` additionally compiles tests, benches and examples + of the members selected. Without it, a broken `#[cfg(test)]` module is + invisible. + +## Feature unification + +Features are **additive** and cargo **unions** them per build. One crate in the +graph gets the union of every feature any dependent asked for. + +```rust +#![allow(dead_code)] + +// A feature can only ADD. This is the shape a compile-time flag selects, written as a +// trait so it compiles in one file: `cfg(feature = "fast")` would pick one impl at +// compile time, and nothing a second dependent does can take that impl away. +pub trait Parser { + fn parse(&self, input: &str) -> Vec; +} + +pub struct Strict; +pub struct Lenient; + +impl Parser for Strict { + fn parse(&self, input: &str) -> Vec { + input.split(',').map(|part| part.trim().parse().expect("not a number")).collect() + } +} + +impl Parser for Lenient { + fn parse(&self, input: &str) -> Vec { + input.split(',').filter_map(|part| part.trim().parse().ok()).collect() + } +} + +pub fn total(parser: &dyn Parser, input: &str) -> u32 { + parser.parse(input).iter().sum() +} +``` + +A `cfg(feature = "fast")` in a real crate picks ONE of those impls at compile +time, and additivity is what that means for a build: if `app-cli` asks for `fast` +and `app-core` never mentions it, the single `parse` that exists in that build is +the fast one, for both. `unexpected_cfgs` (a warning since Rust 1.80) is what +reports a `cfg` on a feature the crate never declared, which is how a typo like +`cfg(feature = "Fast")` becomes visible instead of silently false. + +Why two paths can enable different features of one crate: + +- `app-cli` asks for `serde/derive`; `app-core` asks for `serde` with defaults. + The final `serde` has `derive` **and** the defaults, for both. +- A feature enabled by a dev-dependency can leak into a normal build **under + resolver v1**. Under v2 it does not. +- `default-features = false` at ONE call site does not remove the defaults if + another call site asks for them. Only the declaring table can do that, and it + must do it everywhere or not at all. + +```toml +[dependencies] +# Name a feature after the dependency it pulls, so `features = ["serde"]` cannot +# be confused with a feature that merely happens to be spelled the same. +serde = { version = "1", optional = true } +config = { version = "0.14", default-features = false, features = ["toml"] } + +[features] +default = [] +serde = ["dep:serde"] +# The `?` is a WEAK dependency: `config/extra` is only enabled if something else +# already enabled `config`, so this feature cannot drag it in on its own. +extra = ["config?/extra"] +``` + +`cargo tree -e features -i serde` answers "who enabled this and through what", +which is the question the plugin's `rust_deps` answers for a whole workspace - +including duplicate VERSIONS of one crate, which no feature query will show. + +## `Cargo.lock` discipline + +| what you are building | commit `Cargo.lock` | +|---|---| +| a binary, an application, a CLI, a GUI | **yes** - the lock IS the release | +| a library published to a registry | no - the consumer resolves it | +| a workspace containing a binary | yes, for the whole workspace | + +- A lock file is per workspace, not per crate, and it pins every transitive + version. Committing it is what makes `--locked` meaningful. +- `cargo update -p serde --precise 1.0.203` moves ONE package; `cargo update` at + the root moves everything the semver ranges allow. +- The lock format has versions. A lock written by a newer cargo (version 4, Rust + 1.78+) makes an older toolchain refuse the tree with a message about the lock + version. A workspace that supports an MSRV should generate the lock with that + MSRV's toolchain, or state the floor. +- `cargo metadata --format-version 1` is a read-only dump of the resolved graph - + packages, versions, features, targets, manifest paths. It is the input the + plugin's dependency tools parse, and it needs no build. + +## What the six tools answer + +| question | tool | what it does NOT tell you | +|---|---|---| +| is there a toolchain, the right components and targets? | `rust_status` | whether the code compiles | +| what are the errors, by code and by file:line? | `cargo_check` | whether it links, or whether a test passes | +| did the tests pass, and which failed? | `cargo_test` | whether the binary works outside the test harness | +| what was built, how big, how long? | `cargo_build` | whether the app behaves correctly once running | +| which crates, which versions, which features brought them? | `rust_deps` | whether those versions are the ones you meant | +| what does this mangled symbol mean? | `rust_backtrace` | why the panic happened | + +`rust_status` is four independent facts - toolchain, components, installed +targets, the workspace - because they fail independently: a missing `rust-src` +does not mean the compiler is absent, and a `Cargo.toml` with a typo parses as +"no workspace here" rather than as an error. + +## What not to do + +- Do not read a `cargo check` pass as "it builds". It did not link. +- Do not run `cargo check` on an untrusted tree expecting a read-only act. Build + scripts and proc macros execute. +- Do not add `--offline` and expect a first-time build of a new crate to work; + the crate has to be in the cargo cache already. +- Do not move the lock file, edit it by hand, or delete it "to fix a conflict". + Re-resolve with `cargo update -p`, and commit the result. +- Do not assume `--target ` writes to `target/release/`. It writes + to `target//release/`. +- Do not compare builds made at different `opt-level` or `debug` settings and + call the difference a performance change in your code.