docs: backfill exported docstrings to clear 80% coverage gate (closes #619)

ci_cd_sanity_tests/cmd/ri-exchange/main.go

@@ -13,6 +13,9 @@
 	"github.com/LeanerCloud/CUDly/pkg/exchange"
 )
 
+// Output is the JSON-serialised result written to disk after a quote or
+// exchange execution; it captures inputs, the AWS quote, and any error so the
+// CI step can archive the artefact and surface a human-readable summary.
 type Output struct {
 	Quote            any      `json:"quote"`
 	Mode             string   `json:"mode"`

ci_cd_sanity_tests/pkg/sanity/aws/aws.go

@@ -1,3 +1,5 @@
+// Package aws implements read-only AWS sanity checks used in CI/CD to verify
+// that deploy credentials have sufficient IAM permissions before a real deploy.
 package aws
 
 import (
@@ -14,6 +16,8 @@
 	"github.com/LeanerCloud/CUDly/ci_cd_sanity_tests/pkg/sanity/report"
 )
 
+// Options controls which AWS region to target and optional safety assertions
+// applied during the sanity run.
 type Options struct {
 	Region          string
 	ExpectedAccount string // optional safety check
@@ -78,6 +82,10 @@
 	return map[string]string{"db_instances_seen": fmt.Sprintf("%d", len(out.DBInstances))}, nil
 }
 
+// Run executes all AWS sanity checks in sequence and returns a Report
+// summarising each result. It returns an error only for fatal setup failures
+// (credential load, SDK init); individual check failures are captured inside
+// the Report so callers can surface them all rather than stopping at the first.
 func Run(ctx context.Context, opts Options) (*report.Report, error) {
 	if opts.Region == "" {
 		opts.Region = "us-east-1"

ci_cd_sanity_tests/pkg/sanity/report/report.go

@@ -1,3 +1,4 @@
+// Package report defines the structured output types for CI/CD sanity-test runs.
 package report
 
 import (
@@ -6,6 +7,7 @@
 	"time"
 )
 
+// Status is the outcome of a single sanity check.
 type Status string
 
 const (
@@ -14,6 +16,8 @@
 	StatusSkip Status = "SKIP"
 )
 
+// CheckResult records the outcome of one named sanity check, including timing
+// and optional key/value details for post-hoc debugging.
 type CheckResult struct {
 	StartedAt time.Time         `json:"started_at"`
 	EndedAt   time.Time         `json:"ended_at"`
@@ -23,6 +27,8 @@
 	Message   string            `json:"message,omitempty"`
 }
 
+// Report aggregates the results of a full sanity-test run against a single cloud
+// provider and is serialised to JSON for upload to the CI artefact store.
 type Report struct {
 	RunID     string        `json:"run_id"`
 	Cloud     string        `json:"cloud"`
@@ -32,10 +38,14 @@
 	Results   []CheckResult `json:"results"`
 }
 
+// Add appends a single check result to the report. Not safe for concurrent
+// use; callers running checks in goroutines must serialise Add calls.
 func (r *Report) Add(res CheckResult) {
 	r.Results = append(r.Results, res)
 }
 
+// HasFailures reports whether any recorded check ended in StatusFail. Skips
+// and passes do not count as failures.
 func (r *Report) HasFailures() bool {
 	for _, rr := range r.Results {
 		if rr.Status == StatusFail {
@@ -45,6 +55,8 @@
 	return false
 }
 
+// WriteJSON serialises the report to path with indented JSON and 0600
+// permissions so it can be uploaded as a CI artefact.
 func (r *Report) WriteJSON(path string) error {
 	b, err := json.MarshalIndent(r, "", "  ")
 	if err != nil {

cmd/lambda/clear-rate-limit/main.go

@@ -19,6 +19,9 @@ func getDomain() string {
 	return defaultDomain
 }
 
+// Response is the Lambda function's return value, reporting how many
+// forgot_password rate-limit rows were deleted and how many rate-limit
+// rows (across all endpoints) remain in the table.
 type Response struct {
 	Message        string `json:"message"`
 	DeletedCount   int    `json:"deleted_count"`

internal/api/types.go

@@ -237,34 +237,46 @@ type LoginRequest struct {
 	MFACode  string `json:"mfa_code,omitempty"`
 }
 
+// LoginResponse carries the JWT token and user summary returned after a successful login.
 type LoginResponse struct {
 	Token     string    `json:"token"`
 	ExpiresAt string    `json:"expires_at"`
 	User      *UserInfo `json:"user"`
 	CSRFToken string    `json:"csrf_token,omitempty"`
 }
 
+// UserInfo is a lightweight projection of the authenticated user included in login
+// and session responses; it carries only the fields needed for client-side routing
+// and display, without exposing credential hashes or internal audit fields.
 type UserInfo struct {
 	ID         string   `json:"id"`
 	Email      string   `json:"email"`
 	Groups     []string `json:"groups,omitempty"`
 	MFAEnabled bool     `json:"mfa_enabled"`
 }
 
+// SetupAdminRequest is the one-time bootstrap payload used to create the first
+// administrator account when the system has no users yet.
 type SetupAdminRequest struct {
 	Email    string `json:"email"`
 	Password string `json:"password"` //nolint:gosec // G117: intentional credential field in request/response struct -- value is supplied by the authenticated caller or returned once at creation; not re-stored downstream
 }
 
+// PasswordResetRequest initiates a password-reset flow by sending a reset link
+// to the provided email address if it matches an existing account.
 type PasswordResetRequest struct {
 	Email string `json:"email"`
 }
 
+// PasswordResetConfirm completes a password-reset flow by pairing the one-time
+// token (delivered by email) with the user's chosen new password.
 type PasswordResetConfirm struct {
 	Token       string `json:"token"`
 	NewPassword string `json:"new_password"`
 }
 
+// Session holds the minimal identity claims extracted from a validated JWT and
+// attached to the request context by the authentication middleware.
 type Session struct {
 	UserID string `json:"user_id"`
 	Email  string `json:"email"`
@@ -276,6 +288,10 @@ type Session struct {
 	UserAPIKeyID string `json:"-"`
 }
 
+// User is the full user record returned by the admin user-management endpoints.
+// It mirrors UserInfo's identity fields and adds CreatedAt/UpdatedAt audit
+// timestamps; it is never embedded in the public-facing login or session
+// responses, which use the slimmer UserInfo / CurrentUserResponse types instead.
 type User struct {
 	ID         string   `json:"id"`
 	Email      string   `json:"email"`

providers/azure/services/compute/client.go

@@ -170,6 +170,8 @@ type AzureRetailPriceItem struct {
 	Type            string  `json:"type"`
 }
 
+// AzureRetailPrice is the paginated response envelope returned by the Azure
+// Retail Prices API; NextPageLink is non-empty when additional pages exist.
 type AzureRetailPrice struct {
 	Items        []AzureRetailPriceItem `json:"Items"`
 	NextPageLink string                 `json:"NextPageLink"`