go-netops/docs/development.md

# Development

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

## Prerequisites

| Tool       | Version   | Notes                             |
|------------|-----------|-----------------------------------|
| Go         | 1.26+     | Module uses `go 1.26.0`          |

Dependencies are resolved from the Forge registry (`forge.lthn.ai`).

## 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 client-discovery methods (`GetClients`, `GetDevices`, `GetDeviceList`,
`GetSites`) delegate to the unpoller SDK and would require integration tests
against a real or emulated controller to cover meaningfully.

`GetNetworks`, `GetRoutes`, and `RouteTypeName` are covered by unit tests
using httptest mocks and direct assertions.

## 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