verity 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56eba3ab988df08937ded0d1a64257aef3e6b0377e89c205cb1142555cfe6022
-  data.tar.gz: 767c78b325581dbb233805be573efcf77a1ef6842d1ecb79c23e1036f0d18dd5
+  metadata.gz: a15c5874d4b9d45175c6bab46f6c1e6c0f78d7a2b7f3dcd284072d876a397352
+  data.tar.gz: ededfcef6a549ead85cd11da04dde4edb8b449a35e36d45cb454c6824aec3136
 SHA512:
-  metadata.gz: 9d1afd58fb7e9eead47231b4c08ef719fcdbba846ed760fbc84238baceaca870c76bb160e678f1a3ff81c3ed40ed4fcc2460f7709bbe7fda911008b1704f26b3
-  data.tar.gz: 99325207bf1dbf549b2ee760d5e2528f8b2ae23e98930c3fe67123c18cf577fb3e8b572ef42ebcb8784f4acf13239516e6b45d2e5c9c468d68be5c6c893f4a83
+  metadata.gz: 4a0d0c8b8d0ab9d0f58f23afad6d7febcdd152280659477490db2063a208fcf8fdeb2c1527811770c1a688b6a31adc9eb24101cb7dcc38f53b5c09ffb28d0932
+  data.tar.gz: 92a4ed02eca7e52548c92203fa697fe326879a6d68c7d2411c776a968b93c2fb585d0e3ed95b54f3d6b5070644ff50a2dfb0862632cd4f6bc2d3bf8a98bb6017

data/README.md

@@ -47,7 +47,7 @@ verity -w cpus              # one worker per CPU (Etc.nprocessors)
 verity --workers 2 verity/  # combine with positional args
 ```
 
-Exit status is **0** if every claimed test passes, **1** otherwise (`exit` in `bin/verity` mirrors that). **2** is used for invalid CLI options or an invalid `--reporter` / `-r` value.
+Exit status is **0** if every claimed test passes, **1** otherwise (`exit` in `bin/verity` mirrors that). **2** is used for invalid CLI options — an unknown flag, a bad `--order` value, or a `path:LINE` filter pointing at a missing file — and for an `ArgumentError` raised during the run (e.g. a `:memory:` manifest combined with `--workers > 1`).
 
 ```bash
 verity --reporter dots
@@ -59,7 +59,60 @@ There is no `--version` flag. The current version is available programmatically
 
 Built-in names are the same as for `Verity.build_reporter` (case-insensitive): `colored`, `colored_dots`, `documentation`, `doc`, `dots`, `null`, `none`, `silent`. Custom reporters: `path/to/file.rb:ClassName` (class must `include Verity::Reporter`); the file is `load`ed, then `ClassName.new` is called with no arguments.
 
-`ColoredDotsReporter` (the default) prints green **.** / red **F** / yellow **E** when stdout is a TTY. Set `NO_COLOR` in the environment to disable; set `FORCE_COLOR` or `VERITY_FORCE_COLOR` to `"1"`, `"true"`, or `"yes"` (case-insensitive) to force color when not a TTY.
+`ColoredDotsReporter` (the default) prints green **.** / red **F** / yellow **E** / cyan **S** (skip) when stdout is a TTY. Set `NO_COLOR` in the environment to disable; set `FORCE_COLOR` or `VERITY_FORCE_COLOR` to `"1"`, `"true"`, or `"yes"` (case-insensitive) to force color when not a TTY.
+
+## Execution model
+
+### Parallel runs: the manifest as a work queue
+
+With `worker_count > 1`, the coordinator process syncs all runnable tests into the SQLite manifest, forks the workers, and each worker pulls one test at a time by atomically claiming a `pending` row (marking it `running`). When the queue is drained the worker exits; the coordinator then reclaims any rows left `running` (a crashed worker), replays every recorded result through the reporter, and emits the parallel summary.
+
+```mermaid
+flowchart TB
+    subgraph coord["Coordinator (parent process)"]
+        A["Verity.run"] --> B["sync_manifest!<br/>migrate, replace_tests"]
+        B --> C["fork N workers"]
+        C --> F["wait for all workers"]
+        F --> G["reclaim_abandoned_running!"]
+        G --> H["replay results,<br/>report skipped tests"]
+        H --> I["on_parallel_complete<br/>(counts, problem_rows)"]
+    end
+
+    DB[("SQLite manifest<br/>pending, running, results")]
+
+    subgraph wk["Each forked worker (run_manifest)"]
+        W["claim_next(worker_id)"] --> X{"row claimed?"}
+        X -->|yes| R["run test"]
+        R --> Rec["record pass / fail / error"]
+        Rec --> W
+        X -->|"no: queue empty"| Ex["exit"]
+    end
+
+    B --> DB
+    C --> wk
+    W <--> DB
+    Rec --> DB
+    G --> DB
+```
+
+When resource resolvers are registered, a worker that finds only tests conflicting with currently-running resources gets `:blocked` from the claim and retries after a short sleep instead of exiting.
+
+### A test's outcome
+
+Every executed test resolves to exactly one status. A clean run is `:pass`; a failed assertion (`AssertionError`) is `:fail`; a timeout or any other raised exception is `:error`. Tests tagged `:skip` are never enqueued — they are reported as `:skip` without running.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Skipped: tagged :skip (test or enclosing group)
+    [*] --> Running: enqueued and claimed
+    Running --> Passed: body completes
+    Running --> Failed: AssertionError
+    Running --> Errored: Timeout or other StandardError
+    Skipped --> [*]
+    Passed --> [*]
+    Failed --> [*]
+    Errored --> [*]
+```
 
 ## Configuration
 
@@ -89,7 +142,7 @@ Implement {Verity::Reporter} and assign it on configuration. `Verity.run` and `R
 
 | Class | Purpose |
 |-------|---------|
-| `ColoredDotsReporter` | Default — green/red/yellow dots with ANSI color (TTY-aware) |
+| `ColoredDotsReporter` | Default — green/red/yellow/cyan dots with ANSI color (TTY-aware) |
 | `DotsReporter` | Plain `.` / `F` / `E` dots, no color |
 | `DocumentationReporter` | Prints group titles and test descriptions (outline style) |
 | `NullReporter` | Discards all output (used internally for parallel child workers) |
@@ -106,7 +159,7 @@ class MyReporter
   end
 
   def on_test_complete(result:, worker_id:)
-    # See Verity::Runner::Result: :test, :status (:pass | :fail | :error), :error
+    # See Verity::Runner::Result: :test, :status (:pass | :fail | :error | :skip), :error
   end
 
   def on_run_finish(summary:, worker_id:)
@@ -132,7 +185,7 @@ For a one-off run without changing global config, pass `Verity::Runner.new(repor
 | Reader | Stores |
 |--------|--------|
 | `run_starts` | `[{ total:, worker_id: }, ...]` |
-| `test_completes` | `[{ status:, worker_id: }, ...]` |
+| `test_completes` | `[{ status:, error:, worker_id: }, ...]` |
 | `run_finishes` | `[{ summary:, worker_id: }, ...]` |
 | `parallel_finishes` | `[{ counts:, problem_rows: }, ...]` |
 
@@ -173,9 +226,24 @@ The group stack is cleared before each discovery file is loaded so a stray unclo
 - **`tags: [:skip]`** — The example is **not** enqueued in the manifest and does **not** run. It still appears in **`Verity::Registry.all`**. The summary line includes **`N skipped`** when `N > 0`. String `"skip"` in tags is treated the same (normalized with `to_sym`). A **`group`** may use **`tags: [:skip]`**; that applies to all nested tests (see **Grouping**).
 - **`tags: [:focus]`** — If **any** non-skipped registered test has **`:focus`** (including via an enclosing **`group`**), **only** tests that have **`:focus`** in their effective tags are runnable (manifest + direct **`Runner#run`**). If every non-skipped test is focused, the filter does nothing (same as “all focused”). **`Skip` wins:** a test with both **`skip`** and **`focus`** is skipped. When focus narrows the suite, the summary ends with **`(focus)`**.
 
+How the runnable set is computed: each test's **effective tags** are its enclosing group tags (outer first) plus its own. Skip is evaluated **before** focus — which is why skip wins over focus.
+
+```mermaid
+flowchart TD
+    A["All registered tests"] --> B["effective_tags =<br/>inherited group tags + own tags"]
+    B --> C{"includes :skip?"}
+    C -->|yes| S["excluded<br/>(reported as skipped)"]
+    C -->|no| D["candidate"]
+    D --> E{"any candidate<br/>has :focus?"}
+    E -->|yes| Fy["keep only :focus candidates"]
+    E -->|no| Fn["keep all candidates"]
+    Fy --> RUN["runnable"]
+    Fn --> RUN
+```
+
 ## `Verity::Test` fields
 
-Each registered test is a `Data.define` struct with 11 fields:
+Each registered test is a `Data.define` struct with 12 fields:
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -190,6 +258,7 @@ Each registered test is a `Data.define` struct with 11 fields:
 | `fn` | `Proc` | The test body block |
 | `group_path` | `Array<String>` | Nested `group` titles at registration time (outer first) |
 | `inherited_group_tags` | `Array<Symbol>` | Tags accumulated from enclosing `group` blocks (outer first) |
+| `group_scopes` | `Array<GroupScope>` | Source locations of enclosing `group` blocks (`GroupScope` = `title`, `file`, `line`; outer first), used by `path:LINE` filtering |
 
 ## Repository layout (this project)
 

data/bin/verity

@@ -69,7 +69,7 @@ begin
       c.location_filters = filters unless filters.empty?
     end
   end
-rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+rescue OptionParser::InvalidOption, OptionParser::MissingArgument, ArgumentError => e
   warn "verity: #{e.message}"
   exit 2
 end

data/lib/verity/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Verity
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verity
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Tad Thorley