# Development

Module: `forge.lthn.ai/core/go-netops`

## Prerequisites

| Tool       | Version   | Notes                             |
|------------|-----------|-----------------------------------|
| Go         | 1.25+     | Module uses `go 1.25.5`          |
| core/go    | local     | `replace` directive in go.mod     |

The `go.mod` contains a `replace` directive pointing at `../go` for the
`forge.lthn.ai/core/go` dependency. Ensure the `core/go` repository is
checked out alongside this one (the standard workspace layout handles this).

## Build and Test

```bash
# Run all tests
go test ./...

# Race detector (required before commit)
go test -race ./...

# Verbose output
go test -v ./...

# Single test
go test -v -run TestResolveConfig ./unifi/

# Coverage
go test -cover ./...

# Vet
go vet ./...
```

## Test Patterns

Tests use `net/http/httptest` to mock the UniFi controller API. The mock
server returns minimal JSON responses (`{"meta":{"rc":"ok"}, "data": []}`)
sufficient for the unpoller SDK to initialise without error.

### Config Tests

Config tests isolate the environment by:

- Clearing all `UNIFI_*` and `CORE_CONFIG_UNIFI_*` environment variables
- Using `t.Setenv` for scoped variable injection
- Using `t.TempDir()` as `HOME` to avoid polluting real config

### What Is Tested

| Area            | Coverage | Notes                                      |
|-----------------|----------|--------------------------------------------|
| Client creation | Yes      | `New`, insecure true/false, invalid URL    |
| Config resolve  | Yes      | Defaults, env vars, flags, priority order  |
| NewFromConfig   | Yes      | Success path, missing credentials          |
| SaveConfig      | Yes      | Round-trip save and re-resolve             |

### What Is Not Tested

The query methods (`GetClients`, `GetDevices`, `GetDeviceList`, `GetNetworks`,
`GetRoutes`, `GetSites`) require a live or fully-mocked UniFi controller and
are not covered by unit tests. Current coverage is **39%**.

## Coverage

```
ok  forge.lthn.ai/core/go-netops/unifi  coverage: 39.0% of statements
```

Coverage is concentrated on the config resolution and client construction paths.
The query methods delegate to the unpoller SDK and would require integration
tests against a real or emulated controller to cover meaningfully.

## Coding Standards

- **Language:** UK English throughout (comments, docs, commit messages)
- **Formatting:** `gofmt` (enforced by Go toolchain)
- **Linting:** `go vet ./...` must pass before commit
- **Race detector:** `go test -race ./...` must pass before commit
- **Commit convention:** [Conventional Commits](https://www.conventionalcommits.org/)
  ```
  type(scope): description
  ```
  Examples: `feat(unifi): add VLAN filtering`, `fix(config): handle empty API key`
- **Co-Author:** All commits include:
  ```
  Co-Authored-By: Virgil <virgil@lethean.io>
  ```

## Dependencies

| Module                          | Role                         |
|---------------------------------|------------------------------|
| `forge.lthn.ai/core/go`        | Framework (config, logging)  |
| `github.com/unpoller/unifi/v5` | UniFi controller SDK         |
| `github.com/stretchr/testify`  | Test assertions              |

## Licence

EUPL-1.2