Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,25 @@ jobs:
env:
RUST_BACKTRACE: 1

# Doctests. `--lib` above does NOT run them, and no other job did either:
# before this step, `grep -rn -- '--doc' .github/workflows/` returned
# nothing, so every `///` example in the workspace was unverified. The
# `Documentation` job runs `cargo doc`, which builds the pages and does
# not compile the examples in them.
#
# This matters because the examples are the first code a new contributor
# copies. Measured on the tree that added this step: 21 passed, 0 failed.
#
# It is a thin gate today and the number says why: 193 of the workspace's
# examples are fenced ```rust,ignore``` and are skipped, so this compiles
# 21 of 214. Converting the ignores that only need to type-check to
# ```no_run``` is the follow-up that gives this step its teeth; the step
# has to exist first or there is nothing to convert them into.
- name: Doctests
run: cargo test --workspace --exclude horus_py --doc
env:
RUST_BACKTRACE: 1

# The resolver's crates.io/PyPI tests carry #[ignore] so a contributor
# without network access gets a green suite and a failure means the
# resolver is wrong rather than the network. CI does have access, so it
Expand Down Expand Up @@ -360,6 +379,19 @@ jobs:
# also the right call — docs should describe the crate as it ships,
# i.e. with its default features on.
cargo doc --workspace --no-deps --exclude horus_manager
# Again with horus_core's internals visible.
#
# Ten of its eleven modules are `#[doc(hidden)]` by default, and
# rustdoc does not resolve links inside a hidden module — so the run
# above holds `-D warnings` over roughly a quarter of the crate and
# silently skips the rest. Four broken links had accumulated behind
# that gap, including a `[`HorusError::OutOfRange`]` naming a variant
# the error refactor deleted, and two pointing at private items.
#
# `internal-docs` is docs-only: it gates nothing but the
# `#[doc(hidden)]` attributes, so this compiles no extra code. The
# published documentation is still what the first command renders.
cargo doc -p horus_core --no-deps --features internal-docs
env:
RUSTDOCFLAGS: ${{ (github.ref == 'refs/heads/main' || github.base_ref == 'main') && '-D warnings' || '' }}

Expand Down
17 changes: 10 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -757,13 +757,16 @@ repository; `:850` notes that neither substitutes for the other.
and line 794 sits inside the `cli-integration` job (`:309`) which is in the
aggregator's needs list (`:1374`).

The exception is `readme_contract.rs`'s `the_readme_quick_start_compiles`,
which is `#[ignore]`d with the reason "run in the docs-contract job"
(`readme_contract.rs:146`). Nothing runs it: no workflow mentions
`readme_contract`, `docs-contract.yml`'s cargo invocations name only the
`docs_*` targets, and `integration-tests.yml:794` passes no
`--include-ignored`. If you change the README's Quick Start, compile it
yourself:
`readme_contract.rs`'s `the_readme_quick_start_compiles` is `#[ignore]`d
with the reason "run in the docs-contract job" (`readme_contract.rs:146`),
and that job does now run it — `docs-contract.yml` invokes
`cargo test -p horus_manager --test readme_contract -- --include-ignored`.

This paragraph previously said the opposite ("Nothing runs it: no workflow
mentions `readme_contract`") and told you to compile the Quick Start by hand.
That was true when it was written and stopped being true when the invocation
was added; the prose was not updated with it. You can still run it locally,
but CI will catch a broken Quick Start without you:

```bash
cargo test -p horus_manager --test readme_contract -- --include-ignored
Expand Down
22 changes: 14 additions & 8 deletions docs/TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -544,8 +544,8 @@ coverage, and gates nothing.
| `cli_runtime_integration` (18 ignored), `launch_and_workflow` (5), `real_project_ipc` (3) | `horus_core/tests/` | need a debug build of `-p horus --examples` plus `horus_manager` that no job produces (`integration-tests.yml:160-166`) |
| `transient_subscribers_permanently_flip_a_topic_to_a_lossy_backend` | `participant_count_leak.rs:62` | `#[ignore]`d with the reason "documents an open defect" |
| `naive_protocol_tears_proving_the_model_can_detect_it` | `loom_pod_broadcast.rs:225` | deliberately excluded (`integration-tests.yml:186`); it is supposed to fail, so running it in CI would be wrong — but nothing checks that it *still* fails |
| `docs_parity` | `horus_manager/tests/docs_parity.rs` | all three of its tests are `#[ignore]`d with the reason "needs a horus-docs checkout; wired into the docs-contract workflow" (`:193,:259,:336`). `grep -rn docs_parity .github/` returns nothing. The suite that exists to catch *undocumented* new surface never runs |
| `readme_contract`'s `#[ignore]`d test | `readme_contract.rs:146` | reason: "slow: builds a scratch crate; run in the docs-contract job". That job does not name the target. The other 10 tests in the file do run, via `integration-tests.yml:794` |
| `docs_parity` | `horus_manager/tests/docs_parity.rs` | all three tests are `#[ignore]`d with the reason "needs a horus-docs checkout; wired into the docs-contract workflow" (`:193,:259,:336`) — and it **is** wired: `docs-contract.yml` runs `cargo test -p horus_manager --test docs_parity -- --ignored --nocapture`. This row previously read "`grep -rn docs_parity .github/` returns nothing … never runs", which was true when written and was falsified by the commit that added the invocation |
| `readme_contract`'s `#[ignore]`d test | `readme_contract.rs:146` | reason: "slow: builds a scratch crate; run in the docs-contract job". That job **does** name the target now (`docs-contract.yml`, `--include-ignored`); this row previously said it did not. The other 10 tests in the file also run, via `integration-tests.yml:794` |
| `cpp_toolchain_contract`'s `#[ignore]`d test | `cpp_toolchain_contract.rs:464` | reason: "slow: cross-compiles horus_cpp; run with `--ignored`". Nothing does. The other 19 run |
| `.config/nextest.toml` | repo root config | a fully worked per-test timeout guard (60 s × 3 hard kill at `:50`, `test-threads = 1` at `:66`, `retries = 0` at `:70`, `leak-timeout = "500ms"` at `:77`, a `ci` profile with JUnit output at `:83-101` and a `soak` profile at `:103-110`) that no workflow uses — `grep -rn nextest .github/` returns nothing, and no markdown mentions it |
| `horus_manager/tests/web_e2e/` | Puppeteer suite, `package.json:5-7` | referenced only by `.github/dependabot.yml:105`, whose own comment records that no CI workflow runs the suite and that puppeteer is `hasInstallScript: true`, so the dependency graph is exercised exclusively on workstations |
Expand All @@ -554,12 +554,18 @@ coverage, and gates nothing.
| `tests/docker/run_all.sh` | repo `tests/docker/` | `docker-distro-tests.yml:43-61` builds the five Dockerfiles and runs the image `CMD` and `test_user_workflow.sh` directly; `run_all.sh` is unreferenced. `acceptance_linux_macos.sh` and `acceptance_windows.ps1` beside it *are* used, by `cross-platform-parity.yml` and `distribution.yml` |
| `horus_core`'s doctests | 13 blocks tagged ```` ```rust ```` and one ```` ```no_run ```` in `horus_core/src` | see below |

Three of these are worse than merely unrun, and the distinction matters when you
are deciding what to fix first: `docs_parity`, `readme_contract` and
`cpp_toolchain_contract` carry `#[ignore]` *reason strings asserting they are
wired*. A reader of the source has no way to discover otherwise short of
grepping the workflows. If you add an `#[ignore]` with a reason naming a
workflow, add the invocation in the same commit.
`cpp_toolchain_contract` carries an `#[ignore]` *reason string asserting it is
wired* while nothing runs it, and a reader of the source has no way to discover
that short of grepping the workflows. If you add an `#[ignore]` whose reason
names a workflow, add the invocation in the same commit.

`docs_parity` and `readme_contract` used to be listed here for the same fault
and have since been wired up — which exposed the mirror-image hazard this table
now demonstrates twice over. **A table asserting that something is unrun is
itself untested prose, and it rots in the direction that wastes a newcomer's
time**: it sends them to hand-run a suite CI already covers, and it teaches them
to distrust the workflows. Re-derive the rows against
`grep -rn '<target>' .github/` before relying on any of them.

**On `nextest.toml`.** Its stated premise has partly expired: it says at `:8`
that "None of the jobs in `.github/workflows/ci.yml` set `timeout-minutes`", and
Expand Down
3 changes: 3 additions & 0 deletions horus_core/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,9 @@ horus-tf = { git = "https://github.com/softmata/horus-tf.git", rev = "d525dfcf58
workspace = true

[features]
# Render the crate-internal modules in rustdoc. Docs-only: it gates nothing
# but `#[doc(hidden)]`, so it changes no code and no dependency.
internal-docs = []
default = ["macros", "telemetry", "blackbox"]
macros = ["horus_macros"]

Expand Down
14 changes: 11 additions & 3 deletions horus_core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,9 +111,17 @@ caught it (`rt_allocator.rs:21-26`, `rt_alloc_guard_installed.rs:35-38`).
## How to read the internals

`--document-private-items` is **not** enough on its own. It disables rustdoc's
private-stripping pass, not its hidden-stripping pass, so the eleven hidden
modules stay stripped. You need nightly and `--document-hidden-items`, which is
unstable and refuses to run without `-Z unstable-options`:
private-stripping pass, not its hidden-stripping pass, so the hidden modules
stay stripped. Use the `internal-docs` feature, which lifts the
`#[doc(hidden)]` attributes and works on stable:

```sh
cargo doc -p horus_core --no-deps --document-private-items \
--features internal-docs --open
```

The nightly form below still works and needs no feature, but it requires a
nightly toolchain and an unstable flag, which is why the feature exists:

```sh
RUSTDOCFLAGS="-Z unstable-options --document-hidden-items" \
Expand Down
8 changes: 5 additions & 3 deletions horus_core/src/core/log_buffer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -614,9 +614,11 @@ pub fn publish_log(entry: LogEntry) {
///
/// Returns a join handle. Drop or join to stop the drain thread.
pub fn start_log_file_drain() -> Option<std::thread::JoinHandle<()>> {
let enabled = std::env::var("HORUS_LOG_FILE")
.map(|v| v == "true" || v == "1")
.unwrap_or(false);
// `env_flag`, not a local truth table. This site accepted only "true" and
// "1", so `HORUS_LOG_FILE=yes` turned logging off while `HORUS_SIM_MODE=yes`
// turned simulation on — the same framework disagreeing with itself about
// one word. See `horus_sys::env` for the vocabulary.
let enabled = horus_sys::env::env_flag("HORUS_LOG_FILE").unwrap_or(false);
if !enabled {
return None;
}
Expand Down
10 changes: 7 additions & 3 deletions horus_core/src/drivers/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -96,9 +96,13 @@ pub fn load_from<P: AsRef<Path>>(path: P) -> HorusResult<Vec<(String, Box<dyn No
// to force real hardware got inert `SimStubNode`s instead — actuators never
// commanded, sensors never read, and nothing said so. Parse the value, the
// way HORUS_NET_ENABLED already does.
let sim_mode = std::env::var("HORUS_SIM_MODE")
.map(|v| !(v.is_empty() || v == "0" || v.eq_ignore_ascii_case("false")))
.unwrap_or(false);
// Through `env_flag` now. The shape below was already the fix for
// `=false` turning simulation ON, but it still treated every value it did
// not recognise as an opt-in — so `HORUS_SIM_MODE=no` swapped every driver
// for an inert `SimStubNode`, and `=maybe` would have too. An unrecognised
// value now leaves the default (off) in force, which is the safe direction
// for a flag that disconnects the robot from its hardware.
let sim_mode = horus_sys::env::env_flag("HORUS_SIM_MODE").unwrap_or(false);

let selective_targets: Option<Vec<String>> = if sim_mode {
std::env::var("HORUS_SIM_TARGETS")
Expand Down
2 changes: 1 addition & 1 deletion horus_core/src/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -850,7 +850,7 @@ macro_rules! horus_internal {

/// Convenience type alias for Results using HorusError.
///
/// **Prefer the short aliases [`Result`] and [`Error`] in all new code.**
/// **Prefer the short aliases [`Result`] and [`Error`](type@Error) in all new code.**
/// `HorusResult` and `HorusError` are the canonical names but verbose —
/// the aliases exist specifically so you can write `Result<()>` and `Error`
/// without the `Horus` prefix everywhere.
Expand Down
44 changes: 32 additions & 12 deletions horus_core/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -15,25 +15,45 @@
//! **Note:** This is an internal crate. Users should depend on `horus` and
//! import from `horus::prelude::*`.

// Public modules — accessible cross-crate but hidden from user docs.
// Users should go through `horus::prelude`, not import from `horus_core` directly.
#[doc(hidden)]
// Public modules — accessible cross-crate, hidden from user docs by default.
// Users should go through `horus::prelude`, not import from `horus_core`
// directly, and the crate note above says so.
//
// The hiding is `cfg_attr`'d rather than unconditional so a MAINTAINER can lift
// it on stable:
//
// cargo doc -p horus_core --no-deps --document-private-items \
// --features internal-docs --open
//
// Before this was a feature, the only way to read the internals was the nightly
// incantation in horus_core/README.md — `-Z unstable-options
// --document-hidden-items` — because `--document-private-items` disables
// rustdoc's private-stripping pass and not its hidden-stripping pass. That put
// the API browser for a 112k-line crate behind an unstable flag, so on stable
// `cargo doc --open` showed one module (`terminal`), zero structs and an empty
// search index.
//
// CI documents WITH the feature (ci.yml, Documentation job) precisely so
// `-D warnings` sees these modules: while they were unconditionally hidden,
// rustdoc never resolved their links and four broken ones had accumulated,
// including a `HorusError::OutOfRange` the error refactor had deleted.
#[cfg_attr(not(feature = "internal-docs"), doc(hidden))]
pub mod actions;
#[doc(hidden)]
#[cfg_attr(not(feature = "internal-docs"), doc(hidden))]
pub mod communication;
#[doc(hidden)]
#[cfg_attr(not(feature = "internal-docs"), doc(hidden))]
pub mod core;
#[doc(hidden)]
#[cfg_attr(not(feature = "internal-docs"), doc(hidden))]
pub mod drivers;
#[doc(hidden)]
#[cfg_attr(not(feature = "internal-docs"), doc(hidden))]
pub mod error;
#[doc(hidden)]
#[cfg_attr(not(feature = "internal-docs"), doc(hidden))]
pub mod memory;
#[doc(hidden)]
#[cfg_attr(not(feature = "internal-docs"), doc(hidden))]
pub mod params;
#[doc(hidden)]
#[cfg_attr(not(feature = "internal-docs"), doc(hidden))]
pub mod scheduling;
#[doc(hidden)]
#[cfg_attr(not(feature = "internal-docs"), doc(hidden))]
pub mod services;
/// Non-panicking console output.
///
Expand All @@ -42,7 +62,7 @@ pub mod services;
/// operator pipes `horus run` into `head`. Anything printing from a node, a
/// background thread, or a safety path should use these instead.
pub mod terminal;
#[doc(hidden)]
#[cfg_attr(not(feature = "internal-docs"), doc(hidden))]
pub mod types;
pub(crate) mod utils;

Expand Down
7 changes: 6 additions & 1 deletion horus_core/src/memory/depth_image.rs
Original file line number Diff line number Diff line change
Expand Up @@ -134,10 +134,15 @@ impl DepthImage {
///
/// # Errors
///
/// - [`HorusError::OutOfRange`] — for U16 images, if the converted
/// - [`HorusError::InvalidInput`] — for U16 images, if the converted
/// millimeter value does not fit in `u16` (e.g., value > 65.535m at
/// default scale 1.0). Callers must handle this instead of silently
/// storing the saturated `u16::MAX`.
///
/// The link used to name `HorusError::OutOfRange`, which the error refactor
/// folded into `InvalidInput(ValidationError::…)` (see error.rs:399). The
/// broken link survived because this module was `#[doc(hidden)]`, so
/// rustdoc never resolved it.
pub fn set_depth(&mut self, x: u32, y: u32, value: f32) -> HorusResult<&mut Self> {
if x >= self.width() || y >= self.height() {
return Ok(self);
Expand Down
2 changes: 1 addition & 1 deletion horus_core/src/memory/tensor_handle.rs
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ impl TensorHandle {
/// and dtype.
///
/// This is the ergonomic constructor for creating a tensor to fill in and
/// publish: the data lives in the [`global_pool`](crate::communication::topic::pool_registry::global_pool)
/// publish: the data lives in the process-wide tensor pool (`global_pool`)
/// and the device is inferred from that pool's backend (CPU by default). For
/// an explicit pool or device, use [`alloc`](Self::alloc).
///
Expand Down
15 changes: 10 additions & 5 deletions horus_core/src/params.rs
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,21 @@ impl ParamMetadata {
}
}

/// Callback type for parameter change notification.
/// Called with (key, old_value, new_value). Return Err to reject the change.
pub type ParamChangeCallback =
Arc<dyn Fn(&str, Option<&Value>, &Value) -> Result<(), String> + Send + Sync>;

/// Runtime parameter store for dynamic configuration.
///
/// Provides a typed key-value store with validation, persistence, and
/// concurrent access support.
///
/// The whole of this block — description and doctest — used to sit on
/// `ParamChangeCallback` below, a type alias, because a new item was inserted
/// between the comment and the struct it belonged to. `RuntimeParams` itself
/// rendered undocumented while a callback alias carried its example.
///
/// # Example
///
/// ```rust
Expand All @@ -69,11 +79,6 @@ impl ParamMetadata {
/// let speed: f64 = params.get("max_speed").unwrap();
/// assert_eq!(speed, 1.5);
/// ```
/// Callback type for parameter change notification.
/// Called with (key, old_value, new_value). Return Err to reject the change.
pub type ParamChangeCallback =
Arc<dyn Fn(&str, Option<&Value>, &Value) -> Result<(), String> + Send + Sync>;

pub struct RuntimeParams {
/// Parameter storage - BTreeMap maintains sorted order
params: Arc<RwLock<BTreeMap<String, Value>>>,
Expand Down
Loading
Loading