# Nova Adapters

## Overview

Adapters translate the engine-agnostic Target Stack IR to engine-specific formats. The Terraform adapter is the primary adapter (IR → HCL). Policy adapters translate security tool output into normalized `PolicyCheckResult` records that the confidence signal consumes in an engine-agnostic way.

## Existing Adapters

| Adapter | Path | Input | Output | Purpose |
| --- | --- | --- | --- | --- |
| Terraform adapter | `adapters/terraform/adapter.py` | Stack instance JSON | Terraform HCL (`main.tf`, `terraform.tf`, `providers.tf`) | Compiles IR to Terraform |
| Checkov adapter | `adapters/terraform/policy/checkov_adapter.py` | Checkov JSON | `PolicyCheckResult` records | Translates Checkov results |
| Wiz adapter | `adapters/wiz/wiz_adapter.py` | Wiz API issues JSON | `PolicyCheckResult` records | Translates Wiz security findings |
| Kyverno adapter | `adapters/kyverno/kyverno_adapter.py` | Kyverno PolicyReport JSON | `PolicyCheckResult` records | K8s-native policy translation |
| kyverno-json engine | `adapters/kyverno-json/kyverno_json_engine.py` | Any JSON/YAML payload | `PolicyCheckResult` records | **v1.25 primary policy engine** (swappable via `PolicyEngine` protocol) |

## Policy Engine Protocol (v1.25)

The `core/policy_engine.py` module defines the **swap boundary** between
Nova and its policy engines. A `PolicyEngine` Python Protocol (PEP 544)
with three members (`name`, `is_configured()`, `evaluate()`) is the
contract; a `PolicyEngineRegistry` selects the active engine from
`config.json`'s `policy.engine` key. The confidence signal and pipeline
never import an engine directly — they go through the registry.

**Implementations:**
- `KyvernoJsonEngine` (`adapters/kyverno-json/`) — shells to the `kj`
  CLI; the v1.25 default.
- `NullEngine` (`core/policy_engine.py`) — fallback when the `policy`
  key is absent (emits `SKIPPED`).
- Future: `OpaEngine` — implements the same protocol, shells to
  `opa eval`. The OPA-equivalent surface is documented in
  `.ciagent/RESEARCH.md` §4.2.

**How to add a new engine:**
1. Create `adapters/<name>/<name>_engine.py` implementing the
   `PolicyEngine` protocol (`name`, `is_configured()`, `evaluate()`).
2. `evaluate()` returns `list[dict]` where each dict conforms to
   `schemas/policy_check_result.schema.json`.
3. Register the engine in `core/policy_engine.py`'s `_autoload_*`
   function (or call `register(name, factory)` at startup).
4. Set `config.json.policy.engine` to the engine's `name`.
5. Add the engine to the `engine` enum in
   `schemas/policy_check_result.schema.json` if it needs a distinct
   enum value (v1.25 reuses `"kyverno"` — see D-116).

## How to Write an Adapter

### Terraform Adapter Extension

1. Add a stack type → Terraform type mapping to `TYPE_MAP`.
2. Add non-identity input mappings to `INPUT_MAP`.
3. Add non-identity output mappings to `OUTPUT_MAP`.
4. Add a specialized `_emit_resource` branch if the resource needs nested blocks (e.g. inline policies, rule sets).

### Policy Adapter Pattern

1. Define `SEVERITY_MAP` and `RESULT_MAP` dicts that translate the engine's native severity/result vocabulary to the `PolicyCheckResult` enums.
2. Implement `_to_pcr(raw_record, contract_id)` → `PolicyCheckResult` dict.
3. Implement `adapt(input_path, contract_id)` → list of `PolicyCheckResult` dicts.
4. Implement `is_configured()` → bool (env var check) so the platform can skip the adapter when credentials are absent.

## How to Wire an Adapter

- **Terraform adapter** — invoked by `scripts/run_platform.sh` Step 3 (`terraform-plan`).
- **Checkov adapter** — invoked by `scripts/run_platform.sh` Step 5 (`checkov`).
- **Wiz / Kyverno adapters** — optional Steps 5b/5c, run only when the relevant env vars are set.
- All policy adapters output records that are validated against `schemas/policy_check_result.schema.json`.

## Dependencies

- `jsonschema`, `pyyaml` — used by all adapters for loading and validating inputs.
- `boto3` — used by the Wiz adapter for AWS API access.
- `checkov` — used by the Checkov adapter to run policy scans.
- No external deps for the Terraform adapter (pure Python).

## How to Test Adapters

- `tests/test_adapter.py` — Terraform adapter (`TYPE_MAP`, resource emission, refs, outputs).
- `tests/test_checkov_adapter.py` — Checkov adapter.
- `tests/test_wiz_adapter.py` — Wiz adapter.
- `tests/test_kyverno_adapter.py` — Kyverno adapter.
- All adapter tests load fixtures from `tests/fixtures/` and use `moto` for AWS mocking.

## Where to Write Tests

- `tests/test_<adapter_name>.py` paired with `tests/fixtures/<adapter>_fixture.json`.

## Adding a New Adapter

1. Create `adapters/<name>/<name>_adapter.py`.
2. Implement `adapt()` and (for policy adapters) `is_configured()`.
3. Add the adapter's engine name to the `engine` enum in `schemas/policy_check_result.schema.json` if it is a policy adapter.
4. Write a test (`tests/test_<name>_adapter.py`) plus a fixture (`tests/fixtures/<name>_fixture.json`).
5. Add it to `scripts/run_platform.sh` if it is invoked at runtime.
6. Update this README.