Merge pull request #12 from stacklok/doc

Add doc.go for cel and env packages

Author: JAORMX

cel/doc.go

@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package cel provides a generic CEL expression engine for compiling and evaluating
+expressions against arbitrary data contexts.
+
+The engine provides lazy-initialized, thread-safe environment caching, expression
+compilation with structured parse and type-check error reporting, boolean and
+generic value evaluation helpers, and built-in safeguards against denial-of-service
+via configurable expression length and runtime cost limits.
+
+# Basic Usage
+
+Create an engine with variable declarations, compile an expression, and evaluate it:
+
+	engine := cel.NewEngine(
+	    celgo.Variable("claims", celgo.MapType(celgo.StringType, celgo.DynType)),
+	)
+
+	expr, err := engine.Compile(`claims["sub"] == "user123"`)
+	if err != nil {
+	    // handle compilation error
+	}
+
+	ctx := map[string]any{"claims": map[string]any{"sub": "user123"}}
+	result, err := expr.EvaluateBool(ctx)
+	// result == true
+
+# Expression Validation
+
+Use Check to validate an expression without creating a compiled program. This is
+useful for validating configuration at startup:
+
+	err := engine.Check(`claims["sub"] == "user123"`)
+	if err != nil {
+	    // expression is invalid
+	}
+
+# Error Handling
+
+Compilation errors are returned as structured types with location information:
+
+	expr, err := engine.Compile(`claims["sub"`)
+	var parseErr *cel.ParseError
+	if errors.As(err, &parseErr) {
+	    fmt.Println(parseErr.Source)  // the original expression
+	    fmt.Println(parseErr.Errors) // line/column/message details
+	}
+
+	expr, err = engine.Compile(`undefined_var == "test"`)
+	var checkErr *cel.CheckError
+	if errors.As(err, &checkErr) {
+	    fmt.Println(checkErr.AsJSON()) // structured JSON error details
+	}
+
+# DoS Protection
+
+The engine includes configurable safeguards against denial-of-service:
+
+	engine := cel.NewEngine(opts...).
+	    WithMaxExpressionLength(5000). // reject overly long expressions
+	    WithCostLimit(500000)          // limit runtime evaluation cost
+
+# Concurrency
+
+The Engine and CompiledExpression types are safe for concurrent use. A compiled
+expression can be evaluated from multiple goroutines simultaneously.
+*/
+package cel

cel/engine.go

@@ -1,8 +1,6 @@
 // SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-// Package cel provides a generic CEL expression engine for evaluating
-// expressions against arbitrary data contexts.
 package cel
 
 import (

env/doc.go

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package env provides an interface-based abstraction for environment variable
+access, enabling dependency injection and testing isolation.
+
+# Basic Usage
+
+Use OSReader to read environment variables via the standard os package:
+
+	reader := &env.OSReader{}
+	value := reader.Getenv("MY_VAR")
+
+# Testing
+
+The Reader interface allows injecting a mock in tests to avoid relying on
+real environment variables. A generated mock is available in the mocks
+sub-package:
+
+	ctrl := gomock.NewController(t)
+	mock := mocks.NewMockReader(ctrl)
+	mock.EXPECT().Getenv("MY_VAR").Return("test-value")
+
+	result := myFunc(mock)
+
+# Design
+
+This package follows the interface-based dependency injection pattern used
+throughout toolhive-core. Production code accepts an env.Reader, while tests
+substitute the generated mock.
+*/
+package env

env/env.go

@@ -1,8 +1,6 @@
 // SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-// Package env provides abstractions for environment variable access
-// to enable dependency injection and testing isolation.
 package env
 
 //go:generate mockgen -source=env.go -destination=mocks/mock_reader.go -package=mocks Reader