fastws-cli 0.0.33__tar.gz → 0.0.35__tar.gz

{fastws_cli-0.0.33 → fastws_cli-0.0.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastws-cli
-Version: 0.0.33
+Version: 0.0.35
 Summary: Fast workspace tools for multi-repo management
 Author: Jeremy Howard
 License-Expression: Apache-2.0
@@ -205,9 +205,10 @@ Build a mixed Rust/Python project's extension and opted-in binaries, keep them w
 ```bash
 cargo develop
 cargo develop --path /path/to/project
+cargo develop --profile quick
 ```
 
-Run from the project root, or give its directory with `--path`. The command reads `python-source`, `module-name`, `manifest-path` and features from `[tool.maturin]`. It always builds with Cargo's `test` profile, matching bare `cargo test`. The project must produce a `cdylib` and set `python-source`. To use release settings without command-line flags, add `[profile.test]` with `inherits = "release"` to `Cargo.toml`. Keep incremental compilation enabled for the local crate in that profile.
+Run from the project root, or give its directory with `--path`. The command reads `python-source`, `module-name`, `manifest-path` and features from `[tool.maturin]`. `[tool.fastws] dev-profile = "quick"` selects a project's default for both `cargo develop` and `fastws.cargo.run_tests`. Without that setting they use `test`. An explicit `--profile NAME` overrides the project default. The project must produce a `cdylib` and set `python-source`. Define the selected profile in `Cargo.toml` and keep incremental compilation enabled for the local crate.
 
 Make the initial editable installation through `ws-sync` or maturin. Repeat that installation when package metadata or entry points change. Running Python processes keep the extension they loaded.
 
@@ -253,21 +254,54 @@ cargo wait --path /path/to/workspace
 
 Use it when another process's unfinished edits stop the workspace compiling, such as a second agent working in the same tree. Each check runs `cargo check --all-targets`, whose rustc calls hold the timing lock shared, as every build's do. After a failed check, `cargo wait` prints Cargo's first error line. It checks again once a source file of a local package changes and then stays unchanged for 2 seconds. Local packages are the workspace's members and its path dependencies, such as a sibling crate that `ws-sync` patches in. When a check passes, it prints `compiles` and exits. After `--patience` seconds, 1800 by default, it prints the last check's errors and exits with status 1.
 
-### Rust tests from Python
+### Rust builds and tests from Python
 
-`fastws.cargo.run_tests` builds native tests once with Cargo, without a time limit, then runs the executables that Cargo reports directly from their package directories. Its `timeout` defaults to 30 seconds shared across the test binaries, excluding compilation. Source edits between building and running do not trigger another build: the results describe the compiled build, not necessarily the latest working tree. It supports directly runnable native tests, not cross-target runners.
+`fastws.cargo.run_tests` builds native tests once with Cargo, without a time limit, then runs the executables that Cargo reports directly from their package directories. Each binary gets its own `timeout`, 30 seconds by default, excluding compilation. Outside `FASTWS_JOB`, a timed-out binary is reported as a failed suite with `timed_out` set. Inside a marked job, its timeout raises so the job owner can clean up descendants. Source edits between building and running do not trigger another build: the results describe the compiled build, not necessarily the latest working tree. It supports directly runnable native tests, not cross-target runners.
 
-Pass Cargo build/selection options positionally, and test filters and harness options in `test_args`. A failed binary stops the run unless `--no-fail-fast` is given. Results contain compiler diagnostics and each binary's outcomes and captured failures.
+Where a root has `.config/nextest.toml`, `cargo nextest run` runs the built tests instead: each test in its own process, every binary at once, with the config's slow-test timeouts and groups. `profiles` lists the nextest profiles to run one after another, `('default',)` unless given. `timeout` bounds each profile's run, and each binary's results come from nextest's JUnit report, which lists no ignored tests. `--profile NAME` passes to nextest as `--cargo-profile NAME`, and `test_args` follow `--`.
+
+`root` can also be a list of roots, which build one after another. Roots without nextest then run their binaries in turn. Each profile then runs at the same time in every root whose config defines it: tests in different roots share a phase, and no phase starts before the previous one ends. Suite names start with the root's directory name, and with several profiles also with the profile, as in `app timed: tests/speed.rs`. A failure ends the run after its profile unless `--no-fail-fast` is given.
+
+The default profile is `[tool.fastws].dev-profile`, or `test` when unset. Explicit `--profile NAME`, `--profile=NAME`, `--release` and `-r` override it. Pass Cargo build/selection options positionally, and test filters and harness options in `test_args`. A failed binary stops the run unless `--no-fail-fast` is given. Results contain compiler diagnostics and each binary's outcomes and captured failures.
 
 ```python
 from fastws.cargo import run_tests
 
 native = run_tests('.', '--no-fail-fast')
 focused = run_tests('.', '--test', 'core', test_args=('test_name', '--nocapture'))
+phased = run_tests(['app', 'lib'], profiles=('untimed', 'timed'))
 ```
 
 Doctests are deliberately not run; keep executable examples in ordinary Rust tests. `run_tests` accepts `env` overrides and `timeout=None` to disable its watchdog. It takes no timing lock around the run: rustc's wrapper owns its shared holds, and tests that time own their exclusive holds.
 
+`fastws.cargo.check` runs any Cargo subcommand, `check --all-targets` by default, and returns the same `Results` without test suites. A failing run is a result, not an exception. Each `Diagnostic` in its `diagnostics` holds the message's path, line, column, level and text, and its error code or lint as `code`, such as `E0308` or `clippy::too_many_lines`. The summary lists errors first. `env` sets environment variables for the run, as for `run_tests`. A subcommand that rejects `--message-format`, such as `cargo llvm-lines`, runs with `diagnostics=False`: its result holds the exit status and output, with no diagnostics.
+
+```python
+from fastws.cargo import check
+
+lints = check('.', 'clippy', '--all-targets', '--', '-W', 'clippy::too_many_lines', env={'CLIPPY_CONF_DIR': 'review'})
+errors = [d for d in lints.diagnostics if d.level == 'error']
+sizes = check('.', 'llvm-lines', '--lib', diagnostics=False).text
+```
+
+### Integration snapshots
+
+`fastws.integrate` builds several repos together while people or agents keep editing them. `integrate` snapshots each repo's working tree as a commit (untracked files included, ignored files not), checks each commit out as a detached worktree under one root, and writes the root's Cargo config. `HEAD` and the index of each live repo don't change. The config is the workspace's, with the patches for crates under the root pointing at the root's worktrees, so a build there reads the snapshots and every other local crate from the workspace. Keep the root outside the workspace, where `ws-sync` and uv don't treat its worktrees as members.
+
+`errors` checks each snapshot in turn and keeps the errors in that repo's own files. A repo's check also reports its dependencies' errors, under paths outside the repo, and each dependency's own check already covers those. `owners` reads each owner's path globs from the bullets under a Markdown file's `Files` heading, one ``- Owner: `glob` `glob` `` line each, in order. `by_owner` groups each repo's compiler messages by owner, then by file, and the first owner whose globs match a path owns it. It prefixes each path with its repo's name, so a path into a sibling repo, such as `../rustymath/src/x.rs` from basedpl's check, groups as `rustymath/src/x.rs`. `run_tests` with `--no-fail-fast` runs every test binary, each within its own `timeout`, so a slow or crashing binary doesn't stop the others. `code_count` counts the Rust code lines in a sequence of lines, leaving out blanks and comments. `code_lines` applies it to each Rust file under a directory. `exhash`'s `Journal.stat(count=code_count)` counts the code lines that edits add and remove. `record` writes a run's messages, each repo's test `Results` with each failure's output, and any sizes, as a Markdown record, and returns each owner's message count.
+
+```python
+from fastws.cargo import run_tests
+from fastws.integrate import by_owner, code_lines, errors, integrate, owners, record
+
+root = '~/git/integration'
+commits = integrate({'basedpl': '~/aai-ws/basedpl', 'rustymath': '~/aai-ws/rustymath'}, root)
+errs = errors(root, ['rustymath', 'basedpl'])
+groups = by_owner(errs, owners('~/aai-ws/basedpl/meta/owners.md'))
+tests = {r: run_tests(f'{root}/{r}', '--no-fail-fast') for r in errs if not errs[r]}
+sizes = {r: code_lines(f'{root}/{r}/src') for r in errs}
+counts = record(f'{root}/run8.md', 'Run 8', commits, groups, tests=tests, sizes=sizes)
+```
 ### `ws-sync`
 
 Syncing proceeds in this order:
@@ -285,7 +319,7 @@ Fastws maintains `tool.uv.workspace.exclude`. It excludes unlisted top-level dir
 
 Existing globs, entries for missing directories, and entries for checkouts that are still not Python projects are retained. Use `exclude = [...]` under `[tool.fastws]` to specify exclusions the scan cannot infer, such as keeping a valid project out of the workspace. Adding members preserves hand-written `[tool.uv.sources]` entries, including path and Git sources.
 
-Each sync regenerates Cargo overrides in the workspace's `.cargo/config.toml`. `[patch.crates-io]` gets an entry for each local crate, including nested Cargo workspace members, except a crate marked `publish = false`, which never comes from crates.io. Git dependencies that name local crates get entries under the matching URL. Builds under the workspace root use these local checkouts. Entries pointing outside the root and other configuration sections are preserved.
+Each sync regenerates Cargo overrides in the workspace's `.cargo/config.toml`. `[patch.crates-io]` gets an entry for each local crate, including nested Cargo workspace members, that some local manifest requires from crates.io: by version alone, without `path`, `git` or `workspace`, in any dependency table or `[workspace.dependencies]`. Git dependencies that name local crates get entries under the matching URL. Builds under the workspace root use these local checkouts. Entries pointing outside the root and other configuration sections are preserved.
 
 Sync also defaults `[term] quiet = true` in that file to suppress routine Cargo output and warnings. An explicit `quiet = false` is preserved.
 
@@ -293,6 +327,8 @@ Do not commit a `Cargo.lock` generated under these patches. Its source-less loca
 
 Sync writes `.cargo/rustc-lock` and makes it Cargo's `rustc-wrapper`. The script runs each rustc call holding the timing lock shared (see `cargo develop` above). Inside the lock it runs the wrapper that the config named before sync first wrote the script, where another tool set one, and otherwise `sccache` when it's installed, so unchanged compilation units are reused across the workspace's otherwise-independent Cargo target directories. Later syncs keep that inner wrapper. The script costs about 9 ms a rustc call, mostly the Python interpreter's start. If `sccache` isn't installed, sync warns with the install command (`cargo install sccache --locked`) and continues; rerun `ws-sync` after installing to enable it. On Windows, where the lock does nothing, the config keeps another tool's wrapper, or else names `sccache`.
 
+For an isolated build workspace, `fastws.core.cargo_setup(root)` regenerates these Cargo patches and the same compiler wrapper without pulling, syncing Python or building.
+
 Fastws discovers JavaScript packages directly under the workspace root. It reads each package's `workspaces` list for declared nested packages. These lists accept paths and globs. Fastws ignores undeclared nested packages. Lockfiles do not affect discovery. `[tool.fastws].exclude` matches paths relative to the workspace root. Fastws skips `node_modules` and directories whose names start with `.` or `_`.
 
 Each sync updates `workspaces` in the root `package.json`. It creates the file when needed. It preserves external paths, globs, and unrelated settings. It reports added and removed packages.

{fastws_cli-0.0.33 → fastws_cli-0.0.35}/README.md

@@ -177,9 +177,10 @@ Build a mixed Rust/Python project's extension and opted-in binaries, keep them w
 ```bash
 cargo develop
 cargo develop --path /path/to/project
+cargo develop --profile quick
 ```
 
-Run from the project root, or give its directory with `--path`. The command reads `python-source`, `module-name`, `manifest-path` and features from `[tool.maturin]`. It always builds with Cargo's `test` profile, matching bare `cargo test`. The project must produce a `cdylib` and set `python-source`. To use release settings without command-line flags, add `[profile.test]` with `inherits = "release"` to `Cargo.toml`. Keep incremental compilation enabled for the local crate in that profile.
+Run from the project root, or give its directory with `--path`. The command reads `python-source`, `module-name`, `manifest-path` and features from `[tool.maturin]`. `[tool.fastws] dev-profile = "quick"` selects a project's default for both `cargo develop` and `fastws.cargo.run_tests`. Without that setting they use `test`. An explicit `--profile NAME` overrides the project default. The project must produce a `cdylib` and set `python-source`. Define the selected profile in `Cargo.toml` and keep incremental compilation enabled for the local crate.
 
 Make the initial editable installation through `ws-sync` or maturin. Repeat that installation when package metadata or entry points change. Running Python processes keep the extension they loaded.
 
@@ -225,21 +226,54 @@ cargo wait --path /path/to/workspace
 
 Use it when another process's unfinished edits stop the workspace compiling, such as a second agent working in the same tree. Each check runs `cargo check --all-targets`, whose rustc calls hold the timing lock shared, as every build's do. After a failed check, `cargo wait` prints Cargo's first error line. It checks again once a source file of a local package changes and then stays unchanged for 2 seconds. Local packages are the workspace's members and its path dependencies, such as a sibling crate that `ws-sync` patches in. When a check passes, it prints `compiles` and exits. After `--patience` seconds, 1800 by default, it prints the last check's errors and exits with status 1.
 
-### Rust tests from Python
+### Rust builds and tests from Python
 
-`fastws.cargo.run_tests` builds native tests once with Cargo, without a time limit, then runs the executables that Cargo reports directly from their package directories. Its `timeout` defaults to 30 seconds shared across the test binaries, excluding compilation. Source edits between building and running do not trigger another build: the results describe the compiled build, not necessarily the latest working tree. It supports directly runnable native tests, not cross-target runners.
+`fastws.cargo.run_tests` builds native tests once with Cargo, without a time limit, then runs the executables that Cargo reports directly from their package directories. Each binary gets its own `timeout`, 30 seconds by default, excluding compilation. Outside `FASTWS_JOB`, a timed-out binary is reported as a failed suite with `timed_out` set. Inside a marked job, its timeout raises so the job owner can clean up descendants. Source edits between building and running do not trigger another build: the results describe the compiled build, not necessarily the latest working tree. It supports directly runnable native tests, not cross-target runners.
 
-Pass Cargo build/selection options positionally, and test filters and harness options in `test_args`. A failed binary stops the run unless `--no-fail-fast` is given. Results contain compiler diagnostics and each binary's outcomes and captured failures.
+Where a root has `.config/nextest.toml`, `cargo nextest run` runs the built tests instead: each test in its own process, every binary at once, with the config's slow-test timeouts and groups. `profiles` lists the nextest profiles to run one after another, `('default',)` unless given. `timeout` bounds each profile's run, and each binary's results come from nextest's JUnit report, which lists no ignored tests. `--profile NAME` passes to nextest as `--cargo-profile NAME`, and `test_args` follow `--`.
+
+`root` can also be a list of roots, which build one after another. Roots without nextest then run their binaries in turn. Each profile then runs at the same time in every root whose config defines it: tests in different roots share a phase, and no phase starts before the previous one ends. Suite names start with the root's directory name, and with several profiles also with the profile, as in `app timed: tests/speed.rs`. A failure ends the run after its profile unless `--no-fail-fast` is given.
+
+The default profile is `[tool.fastws].dev-profile`, or `test` when unset. Explicit `--profile NAME`, `--profile=NAME`, `--release` and `-r` override it. Pass Cargo build/selection options positionally, and test filters and harness options in `test_args`. A failed binary stops the run unless `--no-fail-fast` is given. Results contain compiler diagnostics and each binary's outcomes and captured failures.
 
 ```python
 from fastws.cargo import run_tests
 
 native = run_tests('.', '--no-fail-fast')
 focused = run_tests('.', '--test', 'core', test_args=('test_name', '--nocapture'))
+phased = run_tests(['app', 'lib'], profiles=('untimed', 'timed'))
 ```
 
 Doctests are deliberately not run; keep executable examples in ordinary Rust tests. `run_tests` accepts `env` overrides and `timeout=None` to disable its watchdog. It takes no timing lock around the run: rustc's wrapper owns its shared holds, and tests that time own their exclusive holds.
 
+`fastws.cargo.check` runs any Cargo subcommand, `check --all-targets` by default, and returns the same `Results` without test suites. A failing run is a result, not an exception. Each `Diagnostic` in its `diagnostics` holds the message's path, line, column, level and text, and its error code or lint as `code`, such as `E0308` or `clippy::too_many_lines`. The summary lists errors first. `env` sets environment variables for the run, as for `run_tests`. A subcommand that rejects `--message-format`, such as `cargo llvm-lines`, runs with `diagnostics=False`: its result holds the exit status and output, with no diagnostics.
+
+```python
+from fastws.cargo import check
+
+lints = check('.', 'clippy', '--all-targets', '--', '-W', 'clippy::too_many_lines', env={'CLIPPY_CONF_DIR': 'review'})
+errors = [d for d in lints.diagnostics if d.level == 'error']
+sizes = check('.', 'llvm-lines', '--lib', diagnostics=False).text
+```
+
+### Integration snapshots
+
+`fastws.integrate` builds several repos together while people or agents keep editing them. `integrate` snapshots each repo's working tree as a commit (untracked files included, ignored files not), checks each commit out as a detached worktree under one root, and writes the root's Cargo config. `HEAD` and the index of each live repo don't change. The config is the workspace's, with the patches for crates under the root pointing at the root's worktrees, so a build there reads the snapshots and every other local crate from the workspace. Keep the root outside the workspace, where `ws-sync` and uv don't treat its worktrees as members.
+
+`errors` checks each snapshot in turn and keeps the errors in that repo's own files. A repo's check also reports its dependencies' errors, under paths outside the repo, and each dependency's own check already covers those. `owners` reads each owner's path globs from the bullets under a Markdown file's `Files` heading, one ``- Owner: `glob` `glob` `` line each, in order. `by_owner` groups each repo's compiler messages by owner, then by file, and the first owner whose globs match a path owns it. It prefixes each path with its repo's name, so a path into a sibling repo, such as `../rustymath/src/x.rs` from basedpl's check, groups as `rustymath/src/x.rs`. `run_tests` with `--no-fail-fast` runs every test binary, each within its own `timeout`, so a slow or crashing binary doesn't stop the others. `code_count` counts the Rust code lines in a sequence of lines, leaving out blanks and comments. `code_lines` applies it to each Rust file under a directory. `exhash`'s `Journal.stat(count=code_count)` counts the code lines that edits add and remove. `record` writes a run's messages, each repo's test `Results` with each failure's output, and any sizes, as a Markdown record, and returns each owner's message count.
+
+```python
+from fastws.cargo import run_tests
+from fastws.integrate import by_owner, code_lines, errors, integrate, owners, record
+
+root = '~/git/integration'
+commits = integrate({'basedpl': '~/aai-ws/basedpl', 'rustymath': '~/aai-ws/rustymath'}, root)
+errs = errors(root, ['rustymath', 'basedpl'])
+groups = by_owner(errs, owners('~/aai-ws/basedpl/meta/owners.md'))
+tests = {r: run_tests(f'{root}/{r}', '--no-fail-fast') for r in errs if not errs[r]}
+sizes = {r: code_lines(f'{root}/{r}/src') for r in errs}
+counts = record(f'{root}/run8.md', 'Run 8', commits, groups, tests=tests, sizes=sizes)
+```
 ### `ws-sync`
 
 Syncing proceeds in this order:
@@ -257,7 +291,7 @@ Fastws maintains `tool.uv.workspace.exclude`. It excludes unlisted top-level dir
 
 Existing globs, entries for missing directories, and entries for checkouts that are still not Python projects are retained. Use `exclude = [...]` under `[tool.fastws]` to specify exclusions the scan cannot infer, such as keeping a valid project out of the workspace. Adding members preserves hand-written `[tool.uv.sources]` entries, including path and Git sources.
 
-Each sync regenerates Cargo overrides in the workspace's `.cargo/config.toml`. `[patch.crates-io]` gets an entry for each local crate, including nested Cargo workspace members, except a crate marked `publish = false`, which never comes from crates.io. Git dependencies that name local crates get entries under the matching URL. Builds under the workspace root use these local checkouts. Entries pointing outside the root and other configuration sections are preserved.
+Each sync regenerates Cargo overrides in the workspace's `.cargo/config.toml`. `[patch.crates-io]` gets an entry for each local crate, including nested Cargo workspace members, that some local manifest requires from crates.io: by version alone, without `path`, `git` or `workspace`, in any dependency table or `[workspace.dependencies]`. Git dependencies that name local crates get entries under the matching URL. Builds under the workspace root use these local checkouts. Entries pointing outside the root and other configuration sections are preserved.
 
 Sync also defaults `[term] quiet = true` in that file to suppress routine Cargo output and warnings. An explicit `quiet = false` is preserved.
 
@@ -265,6 +299,8 @@ Do not commit a `Cargo.lock` generated under these patches. Its source-less loca
 
 Sync writes `.cargo/rustc-lock` and makes it Cargo's `rustc-wrapper`. The script runs each rustc call holding the timing lock shared (see `cargo develop` above). Inside the lock it runs the wrapper that the config named before sync first wrote the script, where another tool set one, and otherwise `sccache` when it's installed, so unchanged compilation units are reused across the workspace's otherwise-independent Cargo target directories. Later syncs keep that inner wrapper. The script costs about 9 ms a rustc call, mostly the Python interpreter's start. If `sccache` isn't installed, sync warns with the install command (`cargo install sccache --locked`) and continues; rerun `ws-sync` after installing to enable it. On Windows, where the lock does nothing, the config keeps another tool's wrapper, or else names `sccache`.
 
+For an isolated build workspace, `fastws.core.cargo_setup(root)` regenerates these Cargo patches and the same compiler wrapper without pulling, syncing Python or building.
+
 Fastws discovers JavaScript packages directly under the workspace root. It reads each package's `workspaces` list for declared nested packages. These lists accept paths and globs. Fastws ignores undeclared nested packages. Lockfiles do not affect discovery. `[tool.fastws].exclude` matches paths relative to the workspace root. Fastws skips `node_modules` and directories whose names start with `.` or `_`.
 
 Each sync updates `workspaces` in the root `package.json`. It creates the file when needed. It preserves external paths, globs, and unrelated settings. It reports added and removed packages.

{fastws_cli-0.0.33 → fastws_cli-0.0.35}/fastws/__init__.py

@@ -1,4 +1,6 @@
-__version__ = "0.0.33"
+__version__ = "0.0.35"
+
+
 
 
 

fastws_cli-0.0.35/fastws/_toml.py

@@ -0,0 +1,4 @@
+__all__ = ['tomllib']
+
+try: import tomllib
+except ModuleNotFoundError: import tomli as tomllib

fastws_cli-0.0.35/fastws/cargo.py

@@ -0,0 +1,377 @@
+r"Build, test and install Cargo artifacts for mixed Rust/Python projects."
+import json, os, re, shutil, signal, subprocess, sys, sysconfig, tempfile, time
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import NamedTuple
+from xml.etree import ElementTree
+from . import store
+from .procs import bounded, JOB_ENV
+from ._toml import tomllib
+
+
+class ConfigError(ValueError):
+    "A project's `pyproject.toml` lacks a setting that a command needs."
+
+
+def settings(root):
+    "Read the project's tool configuration."
+    return tomllib.loads((Path(root).expanduser()/'pyproject.toml').read_text()).get('tool', {})
+
+
+def _dev_profile(root):
+    return settings(root).get('fastws', {}).get('dev-profile', 'test') if (root/'pyproject.toml').exists() else 'test'
+
+
+def cargo(root, *args):
+    "Run Cargo in the project and return its standard output. A failure raises `CalledProcessError`, holding Cargo's standard error."
+    return subprocess.run(['cargo', *args], cwd=Path(root).expanduser(), capture_output=True, text=True, check=True).stdout
+
+
+def members(root):
+    "The manifests of the workspace's member packages."
+    return {Path(p['manifest_path']) for p in json.loads(cargo(root, 'metadata', '--no-deps', '--format-version', '1'))['packages']}
+
+
+_TEST = re.compile(r'^test (.+) \.\.\. (ok|FAILED|ignored)')
+_FAILURE = re.compile(r'^---- (.+) std(?:out|err) ----$')
+
+
+class Diagnostic(NamedTuple):
+    "A compiler message at its primary span, read from Cargo's JSON messages."
+    path:str; line:int; col:int; level:str; message:str
+    code:str|None=None # The error code or lint, such as `E0308` or `clippy::too_many_lines`
+    def __str__(self): return f'{self.level}{f"[{self.code}]" if self.code else ""}: {self.path}:{self.line}: {self.message}'
+
+
+def _run(root, args, env=None, diagnostics=True):
+    "Run the Cargo subcommand and options `args` in `root`, with the environment variables `env` set: its exit status, its output, each `Diagnostic` once, and Cargo's other JSON messages, such as artifacts. With `diagnostics`, Cargo writes JSON messages and the output renders each compiler message short; without, the output is as Cargo printed it."
+    flags = ('--message-format=json-diagnostic-short',) if diagnostics else ()
+    p = bounded(['cargo', args[0], *flags, *args[1:]], seconds=None, merge=True, cwd=root, env=os.environ | (env or {}))
+    if not diagnostics: return p.returncode, p.stdout, [], []
+    text, found, rest = [], [], []
+    for line in p.stdout.splitlines(keepends=True):
+        if not line.startswith('{'): text.append(line); continue
+        m = json.loads(line)
+        if m['reason'] != 'compiler-message': rest.append(m); continue
+        msg = m['message']
+        text.append(msg['rendered'])
+        if s := next((s for s in msg['spans'] if s['is_primary']), None):
+            found.append(Diagnostic(s['file_name'], s['line_start'], s['column_start'], msg['level'], msg['message'], (msg['code'] or {}).get('code')))
+    return p.returncode, ''.join(text), list(dict.fromkeys(found)), rest
+
+
+def _lines(text, n=20, tail=False):
+    "Up to `n` lines of `text` (None: all), indented, from its end if `tail`, with a count of the lines left out."
+    lines = text.splitlines()
+    if n is None or len(lines) <= n: return [f'    {l}' for l in lines]
+    shown = [f'    {l}' for l in (lines[-n:] if tail else lines[:n])]
+    more = f'    … {len(lines)-n} more lines'
+    return [more, *shown] if tail else [*shown, more]
+
+
+@dataclass
+class Suite:
+    "What one native test binary printed."
+    name:str # The target source, such as `tests/core.rs` or `unittests src/lib.rs`
+    output:str # Everything the binary printed, standard output and standard error merged
+    tests:dict # Each test's outcome: `ok`, `FAILED` or `ignored`
+    failures:dict # Each failing test's captured output
+    summary:str # libtest's `test result:` line, empty for a binary that crashed or has its own harness
+    failed:bool # Did the binary exit unsuccessfully?
+    timed_out:bool=False # Was the binary killed for running out of time?
+
+    @classmethod
+    def read(cls, name, lines, returncode, timed_out=False):
+        "Read one binary's lines and exit status, and whether it was killed for running out of time."
+        failures, current, in_failures = {}, None, False
+        for line in lines:
+            if line in ('successes:', 'failures:'): current, in_failures = None, line == 'failures:'
+            elif in_failures and (m := _FAILURE.match(line)): current = failures.setdefault(m[1], [])
+            elif current is not None: current.append(line)
+        return cls(name, '\n'.join(lines), {m[1]: m[2] for l in lines if (m := _TEST.match(l))},
+                   {k: '\n'.join(v).strip('\n') for k,v in failures.items()},
+                   next((l for l in lines if l.startswith('test result: ')), ''), bool(returncode), timed_out)
+
+    def __str__(self):
+        n = Counter(self.tests.values())
+        status = ', '.join(f'{n[o]} {w}' for o,w in [('ok', 'passed'), ('FAILED', 'failed'), ('ignored', 'ignored')] if n[o])
+        if self.failed and not n['FAILED']:
+            end = 'ran out of time' if self.timed_out else 'failed'
+            status = f'{status}, then {end}' if status else end
+        time = f' in {m[1]}' if (m := re.search(r'finished in (\S+)$', self.summary)) else ''
+        return f'{self.name}: {status or "ok"}{time}'
+
+
+@dataclass
+class Results:
+    "A Cargo run's outcome, its compiler messages and, for tests, each native test binary's results. It displays as a summary: the outcome, the compiler messages with errors first, each binary that ran tests, and each failure's output."
+    command:str # The Cargo subcommand, such as `test` or `clippy`
+    returncode:int
+    text:str # The build's messages and each binary's merged standard output and standard error
+    diagnostics:list # Each `Diagnostic` from the build, before the first binary ran
+    suites:list=field(default_factory=list) # Each test binary's `Suite`, in execution order
+    seconds:float=0 # Wall time spent executing native test binaries, excluding compilation
+
+    @property
+    def ok(self): return self.returncode == 0
+
+    def summary(self, lines:int|None=20):
+        "The outcome, compiler messages, each binary's result and each failure's output, with up to `lines` lines of each output (None: all)"
+        res = [f'cargo {self.command} passed' if self.ok else f'cargo {self.command} failed with exit status {self.returncode}']
+        diags = sorted(self.diagnostics, key=lambda d: d.level != 'error')
+        res += [str(d) for d in diags[:lines]]
+        if lines is not None and len(diags) > lines: res.append(f'{len(diags)-lines} more compiler messages in `diagnostics`')
+        ran = [s for s in self.suites if s.tests or not s.summary]
+        for s in ran:
+            res.append(str(s))
+            for t,out in s.failures.items(): res += [f'  FAILED {t}', *_lines(out, lines)]
+            if s.failed and not s.failures: res += _lines(s.output, lines, tail=True)
+        if idle := len(self.suites) - len(ran): res.append(f'{idle} test binaries ran no tests')
+        if not (self.ok or self.suites or diags): res += _lines(self.text, lines, tail=True)
+        return '\n'.join(res)
+    __repr__ = summary
+
+
+def check(
+    root, # A Cargo package or workspace (expands `~`)
+    *args, # The Cargo subcommand and its options, such as `'clippy', '--all-targets', '--', '-W', 'clippy::pedantic'`; none: `check --all-targets`
+    env:dict=None, # Environment variables to set for the run, such as `{'CLIPPY_CONF_DIR': '/path/to/review'}`
+    diagnostics:bool=True, # Ask Cargo for JSON compiler messages? False runs a subcommand that rejects `--message-format`, such as `llvm-lines`, with no diagnostics
+)->Results:
+    "Run a Cargo subcommand and return its `Results`, with each compiler message as a `Diagnostic`. A failing run is a result, not an exception."
+    args = args or ('check', '--all-targets')
+    return Results(args[0], *_run(Path(root).expanduser(), args, env, diagnostics)[:3])
+
+
+def _bounded(cmd, timeout, **kwargs):
+    "`bounded(cmd, timeout, merge=True, **kwargs)`, and whether it ran out of time. Outside `FASTWS_JOB`, a timeout gives a killed process's result; inside a marked job, it raises so the job's owner can clean up descendants."
+    try: return bounded(cmd, timeout, merge=True, **kwargs), False
+    except TimeoutError as e:
+        if os.environ.get(JOB_ENV): raise
+        return subprocess.CompletedProcess(cmd, -signal.SIGKILL, f'{e}\n'), True
+
+
+def _suite_name(m):
+    "The `Suite` name of the test binary that Cargo artifact `m` describes: its target's source, prefixed `unittests ` unless it's an integration test."
+    name = Path(m['target']['src_path']).relative_to(Path(m['manifest_path']).parent).as_posix()
+    return name if 'test' in m['target']['kind'] else 'unittests ' + name
+
+
+def _binary_id(m, packages):
+    "nextest's id for the test binary that Cargo artifact `m` describes, such as `app`, `app::more` or `app::bin/app`. `packages` maps package ids to names."
+    pkg, kind, name = packages[m['package_id']], m['target']['kind'][0], m['target']['name']
+    if kind == 'test': return f'{pkg}::{name}'
+    return f'{pkg}::{kind}/{name}' if kind in ('bin', 'example', 'bench') else pkg
+
+
+def _junit(path, names):
+    "Each binary's `Suite` from nextest's JUnit report at `path`. `names` maps nextest's binary ids to suite names. Ignored tests don't appear."
+    suites = []
+    for ts in ElementTree.parse(path).getroot().iter('testsuite'):
+        tests, failures, late = {}, {}, False
+        for tc in ts.iter('testcase'):
+            t, bad = tc.get('name'), next(iter(tc.findall('failure') + tc.findall('error')), None)
+            tests[t] = 'ok' if bad is None else 'FAILED'
+            if bad is None: continue
+            failures[t] = '\n'.join(s for s in (tc.findtext('system-out', '').strip('\n'), tc.findtext('system-err', '').strip('\n') or bad.text or '') if s)
+            late |= 'timeout' in bad.get('type', '')
+        suites.append(Suite(names.get(ts.get('name'), ts.get('name')), '\n\n'.join(failures.values()), tests, failures, '', bool(failures), late))
+    return suites
+
+
+def _nextest(root, args, test_args, env, timeout, artifacts, profile='default'):
+    "Run the built tests with `cargo nextest run --profile profile` under `timeout` as a whole: its exit status, its output, each binary's `Suite` and the run's seconds. Cargo's `--profile` in `args` becomes nextest's `--cargo-profile`."
+    packages = {p['id']: p['name'] for p in json.loads(cargo(root, 'metadata', '--format-version', '1', '--no-deps'))['packages']}
+    names = {_binary_id(m, packages): _suite_name(m) for m in artifacts}
+    args = [re.sub(r'^--profile(?==|$)', '--cargo-profile', a) for a in map(str, args)]
+    with tempfile.TemporaryDirectory() as d:
+        report, tool = Path(d)/'junit.xml', Path(d)/'fastws.toml'
+        tool.write_text(f'[profile.{profile}.junit]\npath = {json.dumps(str(report))}\n')
+        cmd = ['cargo', 'nextest', 'run', '--tool-config-file', f'fastws:{tool}', '--profile', profile, '--show-progress=none', '--color=never', *args, *(('--', *test_args) if test_args else ())]
+        start = time.monotonic()
+        p, late = _bounded(cmd, timeout, cwd=root, env=os.environ | env)
+        suites = _junit(report, names) if report.exists() else [Suite('nextest', p.stdout, {}, {}, '', True, late)]
+    return p.returncode, p.stdout, suites, time.monotonic() - start
+
+
+def _libtest(root, args, test_args, env, timeout, artifacts):
+    "Run each built test binary in turn from its package directory under `timeout`: the first failing exit status, the output and each binary's `Suite`. Without `--no-fail-fast` in `args`, the first failing binary ends the run."
+    code, text, suites = 0, '', []
+    for m in artifacts:
+        package, name = Path(m['manifest_path']).parent, _suite_name(m)
+        p, late = _bounded([m['executable'], *test_args], timeout, cwd=package, env=os.environ | env | {'CARGO_MANIFEST_DIR': str(package)})
+        suites.append(Suite.read(name, p.stdout.splitlines(), p.returncode, late))
+        text += f'     Running {name} ({m["executable"]})\n' + p.stdout
+        if p.returncode:
+            code = code or p.returncode
+            if '--no-fail-fast' not in args: break
+    return code, text, suites
+
+
+def _nextest_profiles(root):
+    "The nextest profiles that `root`'s `.config/nextest.toml` defines, `default` included, or None without that file."
+    config = root/'.config/nextest.toml'
+    return {'default', *tomllib.loads(config.read_text()).get('profile', {})} if config.exists() else None
+
+
+def run_tests(
+    root, # A Cargo package or workspace (expands `~`), or a list of them
+    *args, # Cargo build/selection options, such as `'--test', 'core'` or `'--profile', 'checked'`; `--no-fail-fast` runs every binary
+    test_args=(), # Arguments passed directly to each test binary, such as `('name', '--nocapture')`; nextest gets them after `--`
+    env:dict=None, # Environment variables to set for the run, such as `{'BASEDPL_COSTS': '1'}`
+    timeout:float=30, # Seconds that each native test binary, or each nextest run of one profile in one root, may take after building; None: no limit
+    profiles:tuple=('default',) # The nextest profiles to run in turn, each at once in every root whose `.config/nextest.toml` defines it
+)->Results:
+    "Build native tests once per root, with no time limit, then run Cargo's reported executables directly from their package directories. Where a root has `.config/nextest.toml`, `cargo nextest run` runs them instead, each test in its own process, once for each of `profiles` that its config defines, and each binary's results come from nextest's JUnit report. Several roots build in turn. Roots without nextest then run in turn, and each profile then runs in every root that defines it at once. Without `--no-fail-fast`, a failure ends the run after its binary, or after its profile. With several roots, each suite's name starts with its root's directory name, and with several profiles, with the profile. Source edits after building cannot trigger another build; results describe the compiled build, not the latest working tree. `timeout` bounds each binary, or each root's run of a profile, excluding compilation. Outside `FASTWS_JOB`, a run that runs out of time is reported as a failed suite with `timed_out` set. Inside a marked job, the timeout raises so its owner can clean up descendants. An omitted Cargo profile uses each root's tool.fastws.dev-profile, or test. Doctests are not run. This takes no timing lock: rustc's wrapper and tests that time own their holds."
+    roots = [Path(r).expanduser().resolve() for r in (root if isinstance(root, (list, tuple)) else [root])]
+    env = {'CARGO_TERM_QUIET': 'false', 'CARGO_TERM_COLOR': 'never'} | (env or {})
+    has_profile = any(a in ('-r', '--release', '--profile') or isinstance(a, str) and a.startswith('--profile=') for a in args)
+    text, found, built = '', [], []
+    for r in roots:
+        rargs = args if has_profile else (*args, '--profile', _dev_profile(r))
+        code, out, diags, rest = _run(r, ('test', '--no-run', *rargs), env)
+        text, found = text + out, found + diags
+        if code: return Results('test', code, text, found)
+        artifacts = [m for m in rest if m['reason'] == 'compiler-artifact' and m['profile']['test'] and m.get('executable')]
+        built.append((r, rargs, artifacts, _nextest_profiles(r)))
+    def named(r, p, suites):
+        "`suites`, freshly read, renamed for root `r` and profile `p` where several roots or profiles ran"
+        t = ' '.join(x for x in (r.name if len(roots) > 1 else '', p if p and len(profiles) > 1 else '') if x)
+        for s in suites: s.name = f'{t}: {s.name}' if t else s.name
+        return t, suites
+    fail_fast, code, suites, start = '--no-fail-fast' not in args, 0, [], time.monotonic()
+    for r, rargs, artifacts, defined in built:
+        if defined is not None: continue
+        c, out, ss = _libtest(r, rargs, test_args, env, timeout, artifacts)
+        text, suites, code = text + out, suites + named(r, None, ss)[1], code or c
+        if code and fail_fast: return Results('test', code, text, found, suites, time.monotonic() - start)
+    for p in profiles:
+        jobs = [(r, rargs, artifacts) for r, rargs, artifacts, defined in built if p in (defined or ())]
+        with ThreadPoolExecutor(max(len(jobs), 1)) as ex: runs = list(ex.map(lambda j: _nextest(j[0], j[1], test_args, env, timeout, j[2], p), jobs))
+        for (r, _, _), (c, out, ss, _) in zip(jobs, runs):
+            t, ss = named(r, p, ss)
+            text, suites, code = text + (f'     Nextest profile {p} in {r}\n' if t else '') + out, suites + ss, code or c
+        if code and fail_fast: break
+    return Results('test', code, text, found, suites, time.monotonic() - start)
+
+
+def sources(root):
+    "The manifests, and the target directories or files, of the local packages that the workspace builds: its members and its path dependencies."
+    res = set()
+    for p in json.loads(cargo(root, 'metadata', '--format-version', '1'))['packages']:
+        if p['source'] is not None: continue
+        manifest = Path(p['manifest_path'])
+        res.add(manifest)
+        for t in p['targets']:
+            src = Path(t['src_path'])
+            res.add(src if src.parent == manifest.parent else src.parent)
+    return res
+
+
+def _maturin_flags(target, env):
+    "Maturin's macOS linker flags without replacing existing compiler flags."
+    target = target or env.get('CARGO_BUILD_TARGET')
+    if not (target.endswith('-apple-darwin') if target else sys.platform == 'darwin'): return [], None
+    link_args = ['link-arg=-undefined', 'link-arg=dynamic_lookup']
+    if 'CARGO_ENCODED_RUSTFLAGS' in env:
+        flags = env['CARGO_ENCODED_RUSTFLAGS'].split('\x1f') if env['CARGO_ENCODED_RUSTFLAGS'] else []
+    elif 'RUSTFLAGS' in env: flags = env['RUSTFLAGS'].split()
+    else:
+        flags = [arg for flag in link_args for arg in ('-C', flag)]
+        return ['--config', 'build.rustflags=' + json.dumps(flags)], None
+    for flag in link_args:
+        if flag not in flags and '-C'+flag not in flags: flags += ['-C', flag]
+    return [], dict(env, CARGO_ENCODED_RUSTFLAGS='\x1f'.join(flags))
+
+
+def build(
+    root, # The project directory, whose `tool.maturin` gives the defaults (expands `~`)
+    *,
+    library=True, # Build the library target?
+    binaries=False, # Build the binary targets?
+    profile=None, # Cargo profile; None: `tool.maturin.profile`, or Cargo's default
+    target=None, # Target triple; None: the host
+    features=None, # Features to enable, as a list or a string; None: `tool.maturin.features`
+    all_features=False, # Enable every feature? `tool.maturin`'s `all-features` also turns this on
+    no_default_features=False, # Leave out the default features? `tool.maturin`'s `no-default-features` also turns this on
+    for_maturin=False, # Use the macOS linker flags that maturin's own wheel build uses?
+):
+    "Build with Cargo and return the compiler artifacts of the workspace's packages."
+    root = Path(root).expanduser()
+    cfg = settings(root)['maturin']
+    cmd = ['build', '--manifest-path', str((root/'Cargo.toml').resolve()), '--message-format=json-diagnostic-short']
+    if library: cmd.append('--lib')
+    if binaries: cmd.append('--bins')
+    if profile := profile or cfg.get('profile'): cmd += ['--profile', profile]
+    if target: cmd += ['--target', target]
+    if features := features or cfg.get('features'):
+        cmd += ['--features', features if isinstance(features, str) else ','.join(features)]
+    for flag, active in [('all-features', all_features), ('no-default-features', no_default_features)]:
+        if active or cfg.get(flag): cmd.append('--' + flag)
+    extra, env = _maturin_flags(target, os.environ) if for_maturin else ([], None)
+    result = subprocess.run(['cargo', *cmd, *extra], cwd=root, stdout=subprocess.PIPE, text=True, env=env)
+    messages = [json.loads(line) for line in result.stdout.splitlines()]
+    for m in messages:
+        if m.get('reason') != 'compiler-message': continue
+        name = tomllib.loads(Path(m['manifest_path']).read_text())['package']['name']
+        for line in m['message']['rendered'].splitlines(): print(f'[{name}] {line}', file=sys.stderr)
+    result.check_returncode()
+    workspace = members(root)
+    return [m for m in messages if m.get('reason') == 'compiler-artifact' and Path(m['manifest_path']) in workspace]
+
+
+def replace(source, destination):
+    "Replace an installed artifact without changing the file held by running processes."
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    tmp = destination.with_name(f'{destination.name}.{os.getpid()}.tmp')
+    shutil.copy2(source, tmp)
+    os.replace(tmp, destination)
+    return destination
+
+
+def develop(root, *, profile=None):
+    "Serialize this project's cooperating develop runs through build, artifact capture, installation, generator and wheel data. An omitted profile uses tool.fastws.dev-profile, or test. Raw Cargo commands do not take this lock."
+    root = Path(root).expanduser()
+    with store.building(root) as started:
+        tool = settings(root)
+        cfg = tool['maturin']
+        if 'python-source' not in cfg: raise ConfigError(r'cargo develop requires tool.maturin.python-source')
+        binaries = tool.get('fastws', {}).get('native-binaries', False)
+        artifacts = build(root, binaries=binaries, profile=profile or _dev_profile(root))
+        artifact, = [m for m in artifacts if 'cdylib' in m['target']['crate_types']]
+        lib, = [Path(f) for f in artifact['filenames'] if Path(f).suffix in ('.dylib', '.so', '.dll')]
+        module = cfg.get('module-name', artifact['target']['name'])
+        src = root/cfg['python-source']
+        ext = src/Path(*module.split('.'))
+        ext = ext.with_name(ext.name + sysconfig.get_config_var('EXT_SUFFIX'))
+        env = Path(os.environ.get('VIRTUAL_ENV', sys.prefix))
+        scripts = env/('Scripts' if os.name == 'nt' else 'bin')
+        exes = [Path(m['executable']) for m in artifacts if binaries and m.get('executable')]
+        package = src/module.split('.')[0]
+        files = {f'python/{f.relative_to(src)}': f for f in package.rglob('*') if f.is_file() and f != ext and '__pycache__' not in f.parts}
+        files |= {f'python/{ext.relative_to(src)}': lib} | {f'bin/{e.name}': e for e in exes}
+        with store.access():
+            kept = store.keep(root, files, dict.fromkeys(f for a in [lib, *exes] for f in store.dep_files(a)), started)
+            store.install(root, kept, {ext: f'python/{ext.relative_to(src)}'} | {scripts/e.name: f'bin/{e.name}' for e in exes})
+        store.collect()
+        if generator := tool.get('fastws', {}).get('post-develop-module'):
+            subprocess.run([sys.executable, '-m', generator], cwd=root, check=True)
+        # Editable builds through `build_backend` don't install the wheel's data files, which a wheel install puts under the prefix.
+        if 'data' in cfg:
+            data = root/cfg['data']/'data'
+            for f in data.rglob('*'):
+                if f.is_file(): replace(f, env/f.relative_to(data))
+
+
+def stage_binaries(root, profile=None, target=None, features=None, all_features=False, no_default_features=False):
+    "Stage Python-free Cargo binaries for a maturin wheel build."
+    root = Path(root).expanduser()
+    cfg = settings(root)['maturin']
+    if 'data' not in cfg: raise ConfigError(r'staging native binaries requires tool.maturin.data')
+    dest = root/cfg['data']/'scripts'
+    artifacts = build(root, library=False, binaries=True, profile=profile, target=target, features=features,
+        all_features=all_features, no_default_features=no_default_features, for_maturin=True)
+    if dest.exists(): shutil.rmtree(dest)
+    return [replace(m['executable'], dest/Path(m['executable']).name) for m in artifacts if m.get('executable')]