aiden-shared-calculations-unified 1.0.83 → 1.0.84

package/README.MD

@@ -1,155 +0,0 @@
----
-
-# Quantum Test Harness for Computation System
-
-## Overview
-
-The Quantum Test Harness is a **dynamic, dependency-aware testing framework** for running, validating, and profiling the entire computation system.
-
-The new architecture is built around a `run-suite.js` orchestrator. It automatically builds a dependency graph of all calculations, ensuring they are tested in the correct order. This "ground-up" approach allows for robust, efficient, and realistic testing that mimics the production environment.
-
-The harness still tests calculations **without modifying their source code**. It:
-
-*   Builds a dependency graph of all calculations.
-*   Dynamically generates mock data for a consistent "universe" of users and tickers.
-*   Executes calculations in the correct order, passing the results of one test as dependencies to the next.
-*   Monitors performance and validates output against each calculation's `getSchema()`.
-*   Generates rich, interactive HTML reports for each calculation run.
-
----
-
-## Core Concepts
-
-The harness is built on **four main components**:
-
-### 1. Test Suite Orchestrator (`run-suite.js`)
-
-The main CLI entry point for running automated test suites. Responsibilities:
-
-*   Scans all calculation files and builds a computation graph.
-*   Topologically sorts the graph to determine the correct execution order.
-*   Parses CLI commands (`--all`, `--target`, `--product`) to decide which tests to run.
-*   Manages a results cache to efficiently pass outputs as dependencies.
-
-### 2. Test Worker (`test-worker.js`)
-
-Executes the test for a single calculation. Responsibilities:
-
-*   Receives a calculation to test from the orchestrator, along with its pre-computed dependencies.
-*   Generates fresh, temporal mock data for the specific test.
-*   Instantiates the calculation and wraps it in the Quantum Monitor.
-*   Executes `process()` and `getResult()`.
-*   Triggers the report generation.
-
-### 3. Dynamic Data Generation (`data-generator.js`)
-
-Generates **temporal mock data**:
-
-1.  The orchestrator creates a consistent "universe" (tickers and userIds) for the entire test run.
-2.  The test worker generates "today" and optional "yesterday" data snapshots using this universe, ensuring data is consistent and comparable across tests.
-
-### 4. Instrumentation & Validation (`test-harness.js`)
-
-Provides:
-
-*   **Instrumentation**: Wraps the calculation instance in a Proxy via `createQuantumRecorder`. Logs performance, memory, and errors without changing the calculation logic.
-*   **Validation**:
-    *   **Schema Check**: Uses Ajv to validate `getResult()` against `getSchema()`.
-    *   **Sanity Check**: Flags "valid but empty" results like `0`, `null`, `[]`, or `{}` as warnings.
-
----
-
-## Usage: Automated Test Suite
-
-To run automated, dependency-aware test suites, use the `run-suite.js` orchestrator. This is the recommended method for all testing.
-
-### Prerequisites
-
-Graphviz is required to render data-flow diagrams. Ensure `dot` is available in your PATH.
-
-| OS      | Installation                    |
-| ------- | ------------------------------- |
-| macOS   | `brew install graphviz`         |
-| Windows | `choco install graphviz`        |
-| Linux   | `sudo apt-get install graphviz` |
-
----
-
-### Commands
-
-#### 1. Run ALL Computations
-
-Tests every non-legacy computation, ordered by complexity (dependency-free calculations first).
-
-```bash
-node run-suite.js --all
-```
-
-#### 2. Run a Specific Target
-
-Tests a single computation and all of its dependencies in the correct order.
-
-```bash
-# Syntax
-node run-suite.js --target [computation-name]
-
-# Example (note: uses the name, not the file path)
-node run-suite.js --target asset-pnl-status
-```
-
-#### 3. Run a Full Product Line
-
-Tests all computations belonging to a specific product category (defined in `getMetadata`) and all of their dependencies.
-
-```bash
-# Syntax
-node run-suite.js --product [product-name]
-
-# Example
-node run-suite.js --product gem
-```
-
----
-
-### Output
-
-Running a test produces:
-
-*   **Console Output**: Live logs of the orchestration and test progress.
-*   **Test Reports**: Generated for each executed calculation at `test_reports/[CalculationName]/`:
-    *   `timeline.html` – Interactive performance report.
-    *   `dataflow.svg` – Diagram of the calculation's data flow.
-    *   `computation_result.json` – Raw JSON output from `getResult()`.
-    *   `report.json` – Full metrics collected by the harness.
-
----
-
-## Adding a New Calculation
-
-The process remains the same.
-
-1.  **Create Your File**: `calculations/my_product/my-new-calc.js`
-2.  **Implement the Class**: Must include `constructor()`, `process()`, and `getResult()`.
-3.  **Add `getDependencies()`**: Define the other calculations this one depends on.
-4.  **Add `getMetadata()`**: Defines the contract for the harness.
-5.  **Add `getSchema()`**: Enables automatic output validation.
-6.  **Run the Test**: Use the `run-suite.js` commands.
-
-```bash
-# Test your new calculation and its dependencies
-node run-suite.js --target my-new-calc
-```
-
----
-
-## Troubleshooting
-
-| Issue                                            | Solution                                                                                                                            |
-| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Graphviz rendering failed                        | Ensure Graphviz is installed and `dot` is in your system's PATH.                                                                    |
-| `SchemaValidation` errors in `report.json`       | The calculation's output does not match its `getSchema()`. Check `computation_result.json` to see the actual output and fix the logic. |
-| `SanityCheck` warnings in `report.json`          | The output is valid according to the schema but is empty (`null`, `0`, `[]`, `{}`). This may be expected, but it's worth verifying.    |
-| `Error: Unknown computation dependency: [name]`  | A calculation lists a dependency in `getDependencies()` that doesn't exist or has a typo. Check the name for errors.                  |
-| `Error: Circular dependency detected!`           | Two or more calculations depend on each other, creating an impossible loop. Review the `getDependencies()` lists for the involved calculations. |
-
----