feat: add Market Breadth family with CrossSection input (#153)

## What

Adds a new indicator input type and family for **market-breadth** analysis — indicators that aggregate the state of an entire universe of symbols at each tick, rather than a single instrument's price. This is the last open input-type on the expansion roadmap (S10) and unblocks the remaining breadth indicators (McClellan, TRIN, High-Low Index, ...).

## Core

- **`CrossSection` input type** (`crates/wickra-core/src/cross_section.rs`) — one tick carrying the per-symbol state of the whole universe as a `Vec<Member>` + `timestamp`. Each `Member` precomputes a signed `change` (sign classifies advancing / declining / unchanged), a `volume`, and `new_high` / `new_low` extreme flags, so the breadth indicators stay stateless per tick. Both `Member` and `CrossSection` are `#[non_exhaustive]` for additive field growth. `CrossSection::new` validates the universe (non-empty, finite changes, finite non-negative volumes); `new_unchecked` skips validation for hot paths. `advancers()` / `decliners()` count by sign.
- **`Error::InvalidCrossSection`** variant for the validation failures.
- **`AdvanceDecline`** (`advance_decline.rs`) — the Advance/Decline Line: the running cumulative sum of net advancing-minus-declining issues. `Input = CrossSection`, `Output = f64`, ready after the first tick.
- New **"Market Breadth"** `FAMILIES` group; indicator count **314 → 315**, family count nineteen → twenty.

## Bindings

All custom (CrossSection is non-scalar, so no macros apply). The universe crosses each boundary as parallel arrays (`change`, `volume`, `new_high`, `new_low`):
- **Python / Node** expose `update` + `batch` (one array group per tick). Node satisfies the completeness contract (`update`/`batch`/`reset`/`isReady`/`warmupPeriod`).
- **WASM** exposes only `update` (the universe is ragged across ticks, matching the other multi-input wasm indicators) with numeric high/low flags.
- Python `map_err` gains the new error arm; `__init__.py` gets a `# Market Breadth` section in both the import and `__all__` blocks. `index.d.ts` / `index.js` regenerated.

## Tests / Fuzz

- Dedicated **streaming-vs-batch + reference-value + ragged-rejection** tests in Python (`test_new_indicators.py`) and Node (`indicators.test.js`) — kept out of the scalar/candle parametrize lists.
- Rust unit tests cover every reject branch (empty / non-finite change / negative & non-finite volume) and every indicator branch.
- New fuzz target `indicator_update_crosssection` drives `AdvanceDecline` over bounded ragged universes built with `new_unchecked`.

## Verify

- `cargo fmt --all` clean
- `cargo test -p wickra-core --lib` → 2593 passed; `--doc` → 298 passed
- `cargo clippy --workspace --all-targets --all-features -- -D warnings` clean
- `cd bindings/node && npm run build && npm test` → 398 passed
- `maturin develop --release` + `pytest bindings/python/tests` → all passed
- counter check: mod-count 315 == lib-block 315
This commit is contained in:
kingchenc
2026-06-03 04:11:10 +02:00
committed by GitHub
parent 72ec65bbde
commit 53941b7b07
18 changed files with 881 additions and 66 deletions
+94
View File
@@ -11168,6 +11168,100 @@ impl CalendarSpreadNode {
}
}
// ---------- Market Breadth (CrossSection input) ----------
//
// A breadth tick is the per-symbol state of the whole universe, passed as four
// equal-length parallel arrays (`change`, `volume`, `newHigh`, `newLow`).
// `batch` takes one such group of arrays per tick.
fn build_cross_section(
change: &[f64],
volume: &[f64],
new_high: &[bool],
new_low: &[bool],
) -> napi::Result<wc::CrossSection> {
if change.len() != volume.len()
|| change.len() != new_high.len()
|| change.len() != new_low.len()
{
return Err(NapiError::from_reason(
"change, volume, newHigh and newLow must be equal length".to_string(),
));
}
let members = (0..change.len())
.map(|i| wc::Member::new(change[i], volume[i], new_high[i], new_low[i]))
.collect();
wc::CrossSection::new(members, 0).map_err(map_err)
}
#[napi(js_name = "AdvanceDecline")]
pub struct AdvanceDeclineNode {
inner: wc::AdvanceDecline,
}
impl Default for AdvanceDeclineNode {
fn default() -> Self {
Self::new()
}
}
#[napi]
impl AdvanceDeclineNode {
#[napi(constructor)]
pub fn new() -> Self {
Self {
inner: wc::AdvanceDecline::new(),
}
}
#[napi]
pub fn update(
&mut self,
change: Vec<f64>,
volume: Vec<f64>,
new_high: Vec<bool>,
new_low: Vec<bool>,
) -> napi::Result<Option<f64>> {
Ok(self
.inner
.update(build_cross_section(&change, &volume, &new_high, &new_low)?))
}
#[napi]
pub fn batch(
&mut self,
change: Vec<Vec<f64>>,
volume: Vec<Vec<f64>>,
new_high: Vec<Vec<bool>>,
new_low: Vec<Vec<bool>>,
) -> napi::Result<Vec<f64>> {
if change.len() != volume.len()
|| change.len() != new_high.len()
|| change.len() != new_low.len()
{
return Err(NapiError::from_reason(
"change, volume, newHigh and newLow must have the same number of ticks".to_string(),
));
}
let mut out = Vec::with_capacity(change.len());
for i in 0..change.len() {
let section = build_cross_section(&change[i], &volume[i], &new_high[i], &new_low[i])?;
out.push(self.inner.update(section).unwrap_or(f64::NAN));
}
Ok(out)
}
#[napi]
pub fn reset(&mut self) {
self.inner.reset();
}
#[napi(js_name = "isReady")]
pub fn is_ready(&self) -> bool {
self.inner.is_ready()
}
#[napi(js_name = "warmupPeriod")]
pub fn warmup_period(&self) -> u32 {
self.inner.warmup_period() as u32
}
}
// ============================== Family 15: Risk / Performance ==============================
// Risk metrics with fallible `new` (most need `period >= 2`), so each wrapper