fastws-cli 0.0.32__tar.gz → 0.0.34__tar.gz

{fastws_cli-0.0.32 → fastws_cli-0.0.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastws-cli
-Version: 0.0.32
+Version: 0.0.34
 Summary: Fast workspace tools for multi-repo management
 Author: Jeremy Howard
 License-Expression: Apache-2.0
@@ -200,14 +200,15 @@ ws-build --project solveit  # only this package and its transitive workspace dep
 
 ### `cargo develop`
 
-Rebuild a mixed Rust/Python project's extension and replace it in the editable source package:
+Build a mixed Rust/Python project's extension and opted-in binaries, keep them with its Python package as one build, and install that build in the editable source package and the venv:
 
 ```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.
 
@@ -221,7 +222,13 @@ Set `native-binaries = true` under `[tool.fastws]` to build and install the bina
 
 Set `post-develop-module = "package.generator"` under `[tool.fastws]` to run a generator after installing the native extension and binaries, before copying wheel data. It runs with the current Python in a fresh process from the project root, including when Cargo reuses its build. A failure stops `cargo develop` or `ws-sync`. Use it for generated files that need the rebuilt extension's metadata.
 
-On Unix, each Cargo build that fastws runs holds a shared `flock` on `/tmp/aai-ws-timing.lock`. A speed test that takes that lock exclusively then never times code while a build runs. A build waits up to 5 minutes for such a timing to finish, then goes ahead without the lock. Python code takes the same lock with `fastws.cargo.timing_lock`: `with timing_lock(exclusive=True):` around a timing, and `with timing_lock():` around a test run. An exclusive hold that has waited 30 seconds prints the processes that have the lock's file open. It raises `TimeoutError` after 5 minutes. Windows builds and tests run without this timing coordination.
+`cargo develop` keeps each build it installs in `~/.cache/fastws/builds/<project>/<id>/`, read-only. Files are copied first, then hashed, and hard-linked to blobs named by those captured bytes' sha256. The build id hashes these artifacts and the current digests of inputs listed by Cargo's dep-info. Input digests are observations at capture time, not proof of what the compiler read. The record's `started` gives the build's start time; `edited` flags inputs **possibly modified since build started**, by mtime, including inputs of a first build or newly discovered dependencies. Identical inputs and artifacts reuse their first capture's record.
+
+The installed extension and binaries are symbolic links through `<project>/installed`, which `cargo develop` points at the new build in one step. `fastws.store.builds(root)` gives the newest build records, with input changes since the preceding build, and `fastws.store.resolve(root, id)` resolves a build-id prefix. Each develop deletes builds that are neither installed, among the project's last 20, nor from the last 2 days, then old unlinked blobs.
+
+On Unix, cooperating `cargo develop` runs take a per-project lock through compilation, capture, installation, the post-develop generator and wheel data. Store readers and capture/install operations hold shared store access; collection takes it exclusively. Ordinary Cargo commands do not take the project lock: agents must not run competing raw Cargo builds against that project during develop. Windows installs copies and does not take these locks.
+
+On Unix, every rustc call holds a shared `flock` on `/tmp/aai-ws-timing.lock`, through the rustc wrapper that sync writes (see `ws-sync`). A speed test that takes that lock exclusively stays apart from participating builds and test runs. A timing also holds `/tmp/aai-ws-timing.gate` while it waits for the lock and holds it, and a shared hold passes that file first, so new rustc calls and test runs wait behind the timing. Both shared and exclusive acquisition fail after 5 minutes; work never proceeds unlocked. Python code takes the same lock with `fastws.timelock.timing_lock`: `with timing_lock(exclusive=True):` around a timing, and `with timing_lock():` around a test run. Shared-inside-shared in one thread reuses its hold; each thread otherwise takes its own hold. Any nesting involving exclusive raises `RuntimeError` immediately. An exclusive hold that has waited 30 seconds prints the processes that have the lock's file open. Windows builds and tests run without this timing coordination.
 
 Use `fastws.build_backend` as the build backend of a mixed project, and include `fastws-cli>=0.0.29` alongside `maturin>=1.13,<2.0` in `[build-system].requires`. Its editable builds install only Python metadata and the source path, and compile no Rust. `ws-sync` then runs `cargo develop` to build and install the extension, the binaries and the wheel data files. After standalone `uv sync`, run `cargo develop` yourself.
 
@@ -245,8 +252,51 @@ cargo wait
 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` while holding the timing lock shared, as builds 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.
+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 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. Each binary gets its own `timeout`, 30 seconds by default, excluding compilation. A binary still running when its `timeout` ends is killed and counts as a failed binary, with its suite's `timed_out` set. 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.
+
+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'))
+```
+
+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:
@@ -266,9 +316,13 @@ Existing globs, entries for missing directories, and entries for checkouts that
 
 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.
 
+Sync also defaults `[term] quiet = true` in that file to suppress routine Cargo output and warnings. An explicit `quiet = false` is preserved.
+
 Do not commit a `Cargo.lock` generated under these patches. Its source-less local entries cannot be resolved on another machine.
 
-When `sccache` is installed, sync also configures it as Cargo's `rustc-wrapper`, allowing unchanged compilation units to be reused across the workspace's otherwise-independent Cargo target directories. An existing wrapper is always preserved. If neither a wrapper nor `sccache` is present, sync warns with the install command (`cargo install sccache --locked`) and continues; rerun `ws-sync` after installing to enable it.
+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 `_`.
 

{fastws_cli-0.0.32 → fastws_cli-0.0.34}/README.md

@@ -172,14 +172,15 @@ ws-build --project solveit  # only this package and its transitive workspace dep
 
 ### `cargo develop`
 
-Rebuild a mixed Rust/Python project's extension and replace it in the editable source package:
+Build a mixed Rust/Python project's extension and opted-in binaries, keep them with its Python package as one build, and install that build in the editable source package and the venv:
 
 ```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.
 
@@ -193,7 +194,13 @@ Set `native-binaries = true` under `[tool.fastws]` to build and install the bina
 
 Set `post-develop-module = "package.generator"` under `[tool.fastws]` to run a generator after installing the native extension and binaries, before copying wheel data. It runs with the current Python in a fresh process from the project root, including when Cargo reuses its build. A failure stops `cargo develop` or `ws-sync`. Use it for generated files that need the rebuilt extension's metadata.
 
-On Unix, each Cargo build that fastws runs holds a shared `flock` on `/tmp/aai-ws-timing.lock`. A speed test that takes that lock exclusively then never times code while a build runs. A build waits up to 5 minutes for such a timing to finish, then goes ahead without the lock. Python code takes the same lock with `fastws.cargo.timing_lock`: `with timing_lock(exclusive=True):` around a timing, and `with timing_lock():` around a test run. An exclusive hold that has waited 30 seconds prints the processes that have the lock's file open. It raises `TimeoutError` after 5 minutes. Windows builds and tests run without this timing coordination.
+`cargo develop` keeps each build it installs in `~/.cache/fastws/builds/<project>/<id>/`, read-only. Files are copied first, then hashed, and hard-linked to blobs named by those captured bytes' sha256. The build id hashes these artifacts and the current digests of inputs listed by Cargo's dep-info. Input digests are observations at capture time, not proof of what the compiler read. The record's `started` gives the build's start time; `edited` flags inputs **possibly modified since build started**, by mtime, including inputs of a first build or newly discovered dependencies. Identical inputs and artifacts reuse their first capture's record.
+
+The installed extension and binaries are symbolic links through `<project>/installed`, which `cargo develop` points at the new build in one step. `fastws.store.builds(root)` gives the newest build records, with input changes since the preceding build, and `fastws.store.resolve(root, id)` resolves a build-id prefix. Each develop deletes builds that are neither installed, among the project's last 20, nor from the last 2 days, then old unlinked blobs.
+
+On Unix, cooperating `cargo develop` runs take a per-project lock through compilation, capture, installation, the post-develop generator and wheel data. Store readers and capture/install operations hold shared store access; collection takes it exclusively. Ordinary Cargo commands do not take the project lock: agents must not run competing raw Cargo builds against that project during develop. Windows installs copies and does not take these locks.
+
+On Unix, every rustc call holds a shared `flock` on `/tmp/aai-ws-timing.lock`, through the rustc wrapper that sync writes (see `ws-sync`). A speed test that takes that lock exclusively stays apart from participating builds and test runs. A timing also holds `/tmp/aai-ws-timing.gate` while it waits for the lock and holds it, and a shared hold passes that file first, so new rustc calls and test runs wait behind the timing. Both shared and exclusive acquisition fail after 5 minutes; work never proceeds unlocked. Python code takes the same lock with `fastws.timelock.timing_lock`: `with timing_lock(exclusive=True):` around a timing, and `with timing_lock():` around a test run. Shared-inside-shared in one thread reuses its hold; each thread otherwise takes its own hold. Any nesting involving exclusive raises `RuntimeError` immediately. An exclusive hold that has waited 30 seconds prints the processes that have the lock's file open. Windows builds and tests run without this timing coordination.
 
 Use `fastws.build_backend` as the build backend of a mixed project, and include `fastws-cli>=0.0.29` alongside `maturin>=1.13,<2.0` in `[build-system].requires`. Its editable builds install only Python metadata and the source path, and compile no Rust. `ws-sync` then runs `cargo develop` to build and install the extension, the binaries and the wheel data files. After standalone `uv sync`, run `cargo develop` yourself.
 
@@ -217,8 +224,51 @@ cargo wait
 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` while holding the timing lock shared, as builds 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.
+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 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. Each binary gets its own `timeout`, 30 seconds by default, excluding compilation. A binary still running when its `timeout` ends is killed and counts as a failed binary, with its suite's `timed_out` set. 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.
+
+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'))
+```
+
+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:
@@ -238,9 +288,13 @@ Existing globs, entries for missing directories, and entries for checkouts that
 
 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.
 
+Sync also defaults `[term] quiet = true` in that file to suppress routine Cargo output and warnings. An explicit `quiet = false` is preserved.
+
 Do not commit a `Cargo.lock` generated under these patches. Its source-less local entries cannot be resolved on another machine.
 
-When `sccache` is installed, sync also configures it as Cargo's `rustc-wrapper`, allowing unchanged compilation units to be reused across the workspace's otherwise-independent Cargo target directories. An existing wrapper is always preserved. If neither a wrapper nor `sccache` is present, sync warns with the install command (`cargo install sccache --locked`) and continues; rerun `ws-sync` after installing to enable it.
+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 `_`.
 

{fastws_cli-0.0.32 → fastws_cli-0.0.34}/fastws/__init__.py

@@ -1,4 +1,6 @@
-__version__ = "0.0.32"
+__version__ = "0.0.34"
+
+
 
 
 

fastws_cli-0.0.34/fastws/_toml.py

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

fastws_cli-0.0.34/fastws/cargo.py

@@ -0,0 +1,292 @@
+r"Build, test and install Cargo artifacts for mixed Rust/Python projects."
+import json, os, re, shutil, signal, subprocess, sys, sysconfig, time
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import NamedTuple
+from . import store
+from .procs import bounded
+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 run_tests(
+    root, # A Cargo package or workspace (expands `~`)
+    *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')`
+    env:dict=None, # Environment variables to set for the run, such as `{'BASEDPL_COSTS': '1'}`
+    timeout:float=30 # Seconds that each native test binary may run after building; None: no limit
+)->Results:
+    "Build native tests once, with no time limit, then run Cargo's reported executables directly from their package directories. Source edits after building cannot trigger another build; results describe the compiled build, not the latest working tree. `timeout` bounds each binary on its own, excluding compilation. A binary that runs out of time is killed and reported as a failed binary whose suite is `timed_out`. An omitted profile uses 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."
+    root, env = Path(root).expanduser().resolve(), {'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)
+    if not has_profile: args += ('--profile', _dev_profile(root))
+    code, text, found, rest = _run(root, ('test', '--no-run', *args), env)
+    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')]
+    suites, code, start = [], 0, time.monotonic()
+    for m in artifacts:
+        package = Path(m['manifest_path']).parent
+        name = Path(m['target']['src_path']).relative_to(package).as_posix()
+        if 'test' not in m['target']['kind']: name = 'unittests ' + name
+        try: p, late = bounded([m['executable'], *test_args], timeout, merge=True, cwd=package, env=os.environ | env | {'CARGO_MANIFEST_DIR': str(package)}), False
+        except TimeoutError as e: p, late = subprocess.CompletedProcess(m['executable'], -signal.SIGKILL, f'{e}\n'), True
+        suites.append(Suite.read(name, p.stdout.splitlines(), p.returncode, late))
+        text += f'     Running {name} ({m["executable"]})\n' + p.stdout
+        if p.returncode:
+            code = p.returncode
+            if '--no-fail-fast' not in args: 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')]