# orca.coverage

> A module of morca's API.

A pipeline's coverage: one number for how much of it is done, shown on the home page's table, its page's Progress card and in their JSON.

- A **daily or monthly** pipeline's is its partitions done of those in its
  range so far: from its first partition through the last one that has
  ended on the schedule's clock (UTC without a schedule), the range a fill
  works through (`orca.fill.range_keys`). Today's day (this month) is
  still going, so it's in neither number, nor is one that ended less than
  the pipeline's `fill_lag` ago.
- A **keyed** pipeline's is its keys done of the keys orca knows: those
  `<binary> keys` last printed, as `orca.keys` keeps them (the scheduler's
  sensor and the pipeline's page read them; the home page never runs the
  binary).

**Done** is what the calendar and a backfill count as done
(`orca.scheduler.DONE_SQL`): every mapped step of the pipeline succeeded
for the key in a run of its current code; with no mapped step, a run of
its current code over the key succeeded. A step `skipped` because one
before it failed isn't done, nor is a key done only by older code (the
Fill line, which counts any code's, can be higher). Running, queued,
failed and never-run keys are all not done.

A pipeline with nothing to count has no coverage (None, shown as "—"):
a dated one with no first partition, or whose first hasn't ended yet, and
a keyed one whose keys haven't been read, or are none.

**Cost**: one query, `DONE_SQL` over the range's keys, which looks each
key's steps up by the `steps_partition` index, so it grows with the range,
not with the runs: 7 ms for 1,492 days over 30,000 runs (10 ms with no
mapped step). A keyed pipeline's adds the read of its row of `orca.keys`.
Nothing is cached: the UI holds no state.

## Structs

### `Coverage`

```mojo
struct Coverage
```

Implements: `Copyable`, `Movable`

Fields:

- `done: Int`
- `total: Int`: At least 1: with none there's no coverage.
- `unit: String`: `day`, `month` or `key`.

#### `pct`

```mojo
def pct(self) -> Int
```

Percent done, rounded down: 100 only when all are.

#### `pct1`

```mojo
def pct1(self) -> Float64
```

Percent done to a tenth, rounded down.

#### `units`

```mojo
def units(self) -> String
```

#### `text`

```mojo
def text(self) -> String
```

`1141 / 1407 days done (81%)`.

#### `json`

```mojo
def json(self) -> String
```

`{"done": 1141, "total": 1407, "pct": 81.0, "unit": "day"}`.

## Functions

### `coverage_json`

```mojo
def coverage_json(c: Optional[Coverage]) -> String
```

### `coverage`

```mojo
def coverage(mut db: State, name: String, kind: String, start: String, tz: String, fill_lag: String = "") -> Optional[Coverage]
```

`name`'s coverage now (see the module), or None if it has nothing to count. `fill_lag` is as registered (empty for none).