# plesty check

Validate a project against the Plesty compliance standard. Runs a suite of static analysis
and runtime gates organised into two enforcement tiers.

```bash
plesty check [--standard LEVEL]
```

## Options

| Option | Default | Description |
|---|---|---|
| `--standard` | `quantum` | Compliance level: `pixel`, `nebula`, or `quantum` |

## Enforcement tiers

Gates are divided into two tiers depending on whether they require network access or a clean
install environment:

- **`[SDK]`** — enforced locally by `plesty check`; pure static analysis, no network.
  The pre-push git hook installed by `plesty init` runs these gates automatically before
  every push.
- **`[SDK+CI]`** — enforced locally and repeated by CI in a clean environment as the
  authoritative final gate.

## Compliance levels

### Pixel

Metadata and code hygiene only — fast check suitable for pre-commit hooks.

| Gate | Tier | What is checked |
|---|---|---|
| Metadata & Namespace | `[SDK]` | `pyproject.toml` has required fields; package name matches `plesty-<module>`; `plesty/<module>/` directory exists |
| Code Hygiene | `[SDK]` | `ruff` lint (E, F, W, D rules); `ruff format --check`; `mypy` type checking |

### Nebula

All Pixel gates plus the remaining `[SDK]` gates. This is the standard enforced by the
pre-push hook.

| Gate | Tier | What is checked |
|---|---|---|
| API Interface Matching | `[SDK]` | Classes that import from `plesty.lib.*` must inherit from the imported base class (e.g. `BaseDeviceSyncModel`) |
| Data Layer Compliance | `[SDK]` | All public methods have explicit return type annotations; no class redefines a plesty-lib schema model (`ResultDocument`, `DeviceStatus`, `TelemetryEvent`, `ConfigParameter`, `FuncMeta`, `Plan`, …) |
| Documentation Completeness | `[SDK]` | `docs/index.md` (or `index.rst`) exists; `CHANGELOG.md` exists and has been updated since the last git tag |
| Dependency Coexistence | `[SDK]` | No exact pins (`==x.y.z`) in `pyproject.toml`; use `>=x.y,<x+1` |

### Quantum

Everything in Nebula plus the `[SDK+CI]` gates, run locally for full verification before a
release. This is the default `plesty check` standard.

| Gate | Tier | What is checked |
|---|---|---|
| Automated Test Coverage | `[SDK+CI]` | `pytest --cov` with a minimum threshold of **80%** |
| Semantic Versioning | `[SDK+CI]` | Reminder to tag a new release when commits exist since the last tag; API-level diff against the published PyPI release runs in CI |
| Licensing Compliance | `[SDK+CI]` | `LICENSE` and `COPYING` files present; `license` field declared in `pyproject.toml` |
| Vulnerability Audit | `[SDK+CI]` | No known CVEs in declared dependencies; queries the OSV database via `pip-audit` |
| Docs Build | `[SDK+CI]` | Full Sphinx build must complete with zero errors and zero warnings |

### Module-type gates

Quantum additionally runs gates scoped to the `module_type` declared in `[tool.plesty]`;
they report N/A for every other module type.

| Gate | Applies to | What is checked |
|---|---|---|
| d1 — Device API Pipeline | `module_type = "device"` | The eight `DevicePipeline` mock gate tests (`plesty.lib.test.device_pipeline`) are present in `tests/` and pass without hardware |
| d2 — Device Status Contract | `module_type = "device"` | Overrides of `status()` are annotated to return `DeviceStatus` and overrides of `device_state()` to return `str` — consumers can rely on the plesty-lib telemetry schema |
| e1 — Experiment Contract | `module_type = "experiment"` | The five `ExperimentPipeline` contract gate tests (`plesty.lib.test.experiment_pipeline`) are present in `tests/` and pass: public `Experiment` subclass, deterministic `build_plan()`, resolvable step ops, JSON-serializable plan, async lifecycle hooks |
| e2 — Experiment Persistence | `module_type = "experiment"` | No ad-hoc persistence in the module package (`np.save`/`np.savez`, `pickle.dump`, `h5py.File`/`open` with write mode) — results are persisted via `plesty.lib.data.save_result`/`ResultDocument` |

## Examples

```bash
# Default quantum check in the current directory
plesty check

# Quick pixel check (metadata + code hygiene only)
plesty check --standard pixel

# Full quantum check on a project in another directory
plesty --project-dir ../plesty-power-meter check --standard quantum
```