Cleaned up documentation and removed stubs and TODOs throughout the application

sources/doc.go

@@ -1,10 +1,12 @@
-// Package sources defines feedkit's input-source abstraction.
+// Package sources defines feedkit's input-source abstractions and source
+// registry.
 //
-// A source ingests upstream input and emits one or more event.Event values.
-//
-// feedkit supports two source modes:
-//   - PollSource: scheduler invokes Poll on a cadence.
-//   - StreamSource: source runs continuously and pushes events as input arrives.
+// External API surface:
+//   - Input: common source identity surface
+//   - PollSource: polling source interface
+//   - StreamSource: streaming source interface
+//   - Registry / NewRegistry: source driver registry and builders
+//   - HTTPSource / NewHTTPSource: reusable HTTP polling helper
 //
 // Source drivers are domain-specific and registered into Registry by driver name.
 // Registry can then build configured sources from config.SourceConfig.
@@ -12,6 +14,12 @@
 // A single source may emit 0..N events per poll or stream iteration, and those
 // events may span multiple event kinds.
 //
+// Optional helpers from helpers.go:
+//   - DefaultEventID: default event ID policy for source implementations
+//   - SingleEvent: construct and validate a one-element event slice
+//   - ValidateExpectedKinds: compare configured expected kinds against source
+//     advertised kinds when metadata is available
+//
 // HTTP-backed polling sources can share NewHTTPSource for generic HTTP config
 // parsing and conditional GET behavior. The helper understands:
 //   - params.url

sources/http.go

@@ -5,7 +5,6 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/http"
-	"strconv"
 	"strings"
 	"sync"
 
@@ -60,9 +59,13 @@ func NewHTTPSource(driver string, cfg config.SourceConfig, accept string) (*HTTP
 		return nil, fmt.Errorf("%s %q: params.user_agent is required", driver, cfg.Name)
 	}
 
-	conditional, err := parseConditionalParam(cfg)
-	if err != nil {
-		return nil, err
+	conditional := true
+	if _, exists := cfg.Params["conditional"]; exists {
+		var ok bool
+		conditional, ok = cfg.ParamBool("conditional")
+		if !ok {
+			return nil, fmt.Errorf("source %q: params.conditional must be a boolean", cfg.Name)
+		}
 	}
 
 	return &HTTPSource{
@@ -121,27 +124,3 @@ func (s *HTTPSource) FetchJSONIfChanged(ctx context.Context) (json.RawMessage, b
 	}
 	return json.RawMessage(body), true, nil
 }
-
-func parseConditionalParam(cfg config.SourceConfig) (bool, error) {
-	raw, ok := cfg.Params["conditional"]
-	if !ok || raw == nil {
-		return true, nil
-	}
-
-	switch v := raw.(type) {
-	case bool:
-		return v, nil
-	case string:
-		s := strings.TrimSpace(v)
-		if s == "" {
-			return false, fmt.Errorf("source %q: params.conditional must be a boolean", cfg.Name)
-		}
-		parsed, err := strconv.ParseBool(s)
-		if err != nil {
-			return false, fmt.Errorf("source %q: params.conditional must be a boolean", cfg.Name)
-		}
-		return parsed, nil
-	default:
-		return false, fmt.Errorf("source %q: params.conditional must be a boolean", cfg.Name)
-	}
-}

sources/http_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 
 	"gitea.maximumdirect.net/ejr/feedkit/config"
@@ -39,6 +40,27 @@ func TestNewHTTPSourceRejectsInvalidConditional(t *testing.T) {
 	if err == nil {
 		t.Fatalf("NewHTTPSource() error = nil, want error")
 	}
+	if !strings.Contains(err.Error(), "params.conditional must be a boolean") {
+		t.Fatalf("NewHTTPSource() error = %q, want params.conditional must be a boolean", err)
+	}
+}
+
+func TestNewHTTPSourceConditionalCanBeExplicitlyFalse(t *testing.T) {
+	src, err := NewHTTPSource("test_driver", config.SourceConfig{
+		Name:   "test-source",
+		Driver: "test_driver",
+		Params: map[string]any{
+			"url":         "https://example.invalid",
+			"user_agent":  "test-agent",
+			"conditional": false,
+		},
+	}, "application/json")
+	if err != nil {
+		t.Fatalf("NewHTTPSource() error = %v", err)
+	}
+	if src.Conditional {
+		t.Fatalf("Conditional = true, want false")
+	}
 }
 
 func TestHTTPSourceFetchJSONIfChanged(t *testing.T) {