test: fuzz schema generation for union inputs + docs fixup

.github/workflows/ci.yaml

@@ -440,7 +440,9 @@ jobs:
   fuzz-go:
     name: Fuzz Go
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    # test:fuzz auto-discovers every Fuzz* target and runs each for FUZZTIME
+    # (30s default), so this scales as targets are added.
+    timeout-minutes: 15
     env:
       CGO_ENABLED: "1"
     steps:
@@ -449,14 +451,8 @@ jobs:
         with:
           version: 2026.4.27
           cache_key_prefix: mise-ci-${{ github.job }}
-      - name: Fuzz schema type resolution
-        run: go test ./pkg/schema/ -run='^$' -fuzz=FuzzResolveSchemaType -fuzztime=30s
-      - name: Fuzz JSON schema generation
-        run: go test ./pkg/schema/ -run='^$' -fuzz=FuzzJSONSchema -fuzztime=30s
-      - name: Fuzz Python parser
-        run: go test ./pkg/schema/python/ -run='^$' -fuzz=FuzzParsePredictor -fuzztime=30s
-      - name: Fuzz type annotation parsing
-        run: go test ./pkg/schema/python/ -run='^$' -fuzz=FuzzParseTypeAnnotation -fuzztime=30s
+      - name: Fuzz all targets (auto-discovered)
+        run: mise run test:fuzz
 
   test-rust:
     name: Test Rust

docs/python.md

@@ -38,6 +38,7 @@ This document defines the API of the `cog` Python module, which is used to defin
   - [`cog.Secret`](#cogsecret)
   - [Wrapper types](#wrapper-types)
     - [`Optional`](#optional)
+    - [`Union`](#union)
     - [`list`](#list)
     - [`dict`](#dict)
     - [`cog.Opaque`](#cogopaque)
@@ -805,7 +806,8 @@ Fields in a `BaseModel` output support these types:
 The following type patterns are **not** supported:
 
 - **Nested generics**: `list[list[str]]`, `list[Optional[str]]`, `Optional[list[str]]` are not supported.
-- **Union types beyond Optional**: `str | int`, `Union[str, int, None]` — only `Optional[T]` (i.e. `T | None`) is supported.
+- **Output union types beyond Optional**: union _return_ types and `BaseModel` union fields are not supported. Input unions of JSON-native types (`str | int`, `str | float | None`, etc.) _are_ supported — see [`Union`](#union).
+- **Input unions of non-JSON-native types**: input unions involving `Path`, `File`, `Secret`, custom coders, or `BaseModel` (e.g. `Path | str`) are not supported and fail at build time.
 - **`Optional` as a top-level return type**: `-> Optional[str]` is not allowed. Use a `BaseModel` with optional fields instead.
 - **Nested `BaseModel` fields**: A `BaseModel` field typed as another `BaseModel` is not supported in Cog's type system for schema generation.
 - **Tuple, Set, or other collection types**: Only `list` and `dict` are supported as collection types.

mise.toml

@@ -53,6 +53,7 @@ ruff = "0.14.13"
 ty = "0.0.10"
 "npm:prettier" = "3.6.2"
 "npm:markdownlint-cli2" = "0.22.0"
+"aqua:jqlang/jq" = "1.8.1"
 "go:golang.org/x/tools/cmd/goimports" = "latest"
 zig = "0.15.2"
 
@@ -325,21 +326,35 @@ depends = ["build:coglet:wheel"]
 run = "nox -s coglet"
 
 [tasks."test:fuzz"]
-description = "Run Go fuzz tests (FUZZTIME=30s per target by default)"
-run = """
+description = "Run all Go fuzz tests (auto-discovered; FUZZTIME=30s per target by default)"
+run = '''
 #!/usr/bin/env bash
-set -e
+set -euo pipefail
 FUZZTIME="${FUZZTIME:-30s}"
-echo "Fuzzing schema type resolution ($FUZZTIME)..."
-go test ./pkg/schema/ -run='^$' -fuzz=FuzzResolveSchemaType -fuzztime="$FUZZTIME"
-echo "Fuzzing JSON schema generation ($FUZZTIME)..."
-go test ./pkg/schema/ -run='^$' -fuzz=FuzzJSONSchema -fuzztime="$FUZZTIME"
-echo "Fuzzing Python parser ($FUZZTIME)..."
-go test ./pkg/schema/python/ -run='^$' -fuzz=FuzzParsePredictor -fuzztime="$FUZZTIME"
-echo "Fuzzing type annotation parsing ($FUZZTIME)..."
-go test ./pkg/schema/python/ -run='^$' -fuzz=FuzzParseTypeAnnotation -fuzztime="$FUZZTIME"
-echo "All fuzz targets passed."
-"""
+
+# Auto-discover every Fuzz* target and the package it lives in, so new fuzz
+# tests are picked up automatically without editing this task. go test only
+# fuzzes one target per invocation, so we still loop and run them one at a time.
+# jq emits "<package> <target>" per line; package and target names never
+# contain spaces, so `read pkg target` splits them cleanly.
+count=0
+while read -r pkg target; do
+  [ -z "$pkg" ] && continue
+  echo "Fuzzing $target in $pkg ($FUZZTIME)..."
+  go test "$pkg" -run="^$" -fuzz="^${target}$" -fuzztime="$FUZZTIME"
+  count=$((count + 1))
+done < <(
+  go test -list "^Fuzz" -json ./... 2>/dev/null \
+    | jq -r 'select(.Action=="output" and (.Output|test("^Fuzz"))) | .Package + " " + (.Output | rtrimstr("\n"))'
+)
+
+if [ "$count" -eq 0 ]; then
+  echo "No fuzz targets found." >&2
+  exit 1
+fi
+
+echo "All $count fuzz targets passed."
+'''
 
 [tasks."test:integration"]
 description = "Run integration tests (skips slow tests by default, set SHORT=0 for full suite)"