chore: enforce TODO issue links in CI and update existing TODOs

This change introduces a new GitHub Actions workflow that enforces all TODO
comments must reference a GitHub issue (e.g., TODO(#123): description).
Plain TODOs without issue links will now fail CI.

All existing TODOs in the codebase have been updated with links to their
corresponding GitHub issues:
- #493: Parallel resolution in Dotprompt.render()
- #494: pending:true support for section helper in Go
- #495: Empty response body behavior clarification
- #496: Error handling for None resolver returns
- #497: Python 3.12+ type syntax upgrade
- #498: Schema caching in Dotprompt
- #499: model_dump for config serialization
- #500: Pagination implementation in Go DirStore
- #501: Register helpers support in Go
- #502: Options/local variables support in handlebarrz
- #503: Smoke test improvements

The TODO format requirement has been added to the coding guidelines.

Fixes #493, #494, #495, #496, #497, #498, #499, #500, #501, #502, #503

Author: yesudeep

.github/workflows/todo-check.yml

@@ -0,0 +1,109 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+name: TODO Check
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  check-todos:
+    name: Check TODOs have issue links
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check for TODOs without issue links
+        run: |
+          #!/bin/bash
+          set -euo pipefail
+
+          echo "🔍 Checking for TODOs without issue links..."
+          echo ""
+
+          # Define patterns for valid TODOs with issue links
+          # Valid formats:
+          #   // TODO(#123): description
+          #   // TODO(https://github.com/org/repo/issues/123): description
+          #   # TODO(#123): description
+          #   # TODO(https://...): description
+
+          # Find all TODO comments that DON'T have an issue reference
+          # Pattern explanation:
+          # - Match TODO comments without parentheses containing # or http
+          # - Exclude: TODO(#123), TODO(https://...)
+
+          INVALID_TODOS=$(grep -rn \
+            --include="*.py" \
+            --include="*.ts" \
+            --include="*.js" \
+            --include="*.go" \
+            --include="*.rs" \
+            --include="*.java" \
+            --include="*.kt" \
+            --include="*.sh" \
+            --include="*.yaml" \
+            --include="*.yml" \
+            -E '(#|//)\s*TODO[^(]|TODO\(\s*\)|TODO\([^#h][^)]*\)' \
+            --exclude-dir=node_modules \
+            --exclude-dir=.git \
+            --exclude-dir=target \
+            --exclude-dir=dist \
+            --exclude-dir=build \
+            --exclude-dir=.cache \
+            --exclude-dir=bazel-* \
+            --exclude-dir=vendor \
+            --exclude-dir=site \
+            --exclude-dir=.venv \
+            --exclude-dir=venv \
+            --exclude-dir=__pycache__ \
+            . 2>/dev/null || true)
+
+          # Filter out documentation examples (in .md files showing TODO syntax)
+          INVALID_TODOS=$(echo "$INVALID_TODOS" | grep -v "\.md:" || true)
+          # Filter out this workflow file itself
+          INVALID_TODOS=$(echo "$INVALID_TODOS" | grep -v "todo-check.yml" || true)
+
+          if [ -n "$INVALID_TODOS" ]; then
+            echo "❌ Found TODOs without issue links:"
+            echo ""
+            echo "$INVALID_TODOS"
+            echo ""
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo ""
+            echo "📝 TODOs must reference a GitHub issue. Valid formats:"
+            echo ""
+            echo "   Python/Bash/YAML:"
+            echo "     # TODO(#123): description"
+            echo "     # TODO(https://github.com/google/dotprompt/issues/123): description"
+            echo ""
+            echo "   JavaScript/TypeScript/Java/Rust/Go:"
+            echo "     // TODO(#123): description"
+            echo "     // TODO(https://github.com/google/dotprompt/issues/123): description"
+            echo ""
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo ""
+            echo "💡 To create an issue for your TODO:"
+            echo "   gh issue create --title 'Your TODO title' --body 'Description'"
+            echo ""
+            exit 1
+          fi
+
+          echo "✅ All TODOs have proper issue links!"

docs/contributing/coding_guidelines.md

@@ -15,6 +15,30 @@ for Generative AI. The codebase supports **Go**, **Python**, **JavaScript/TypeSc
   unless there is a compelling, documented reason.
 * **Check Licenses**: Run `./scripts/check_license` to ensure all files have proper
   license headers.
+* **TODO Format**: All TODOs must reference a GitHub issue. Plain `TODO:` comments
+  without issue links are not allowed and will fail CI.
+
+### TODO Format
+
+TODOs must include an issue reference in parentheses:
+
+```python
+# Python/Bash/YAML
+# TODO(#123): description of work to be done
+# TODO(https://github.com/google/dotprompt/issues/123): full URL also works
+```
+
+```typescript
+// JavaScript/TypeScript/Java/Rust/Go
+// TODO(#123): description of work to be done
+// TODO(https://github.com/google/dotprompt/issues/123): full URL also works
+```
+
+**Why?** Issue-linked TODOs ensure:
+- Work is tracked and not forgotten
+- Context is preserved for future developers
+- Progress can be measured
+- TODOs can be prioritized alongside other work
 
 ***
 

go/dotprompt/dirstore.go

@@ -142,7 +142,7 @@ func (ds *DirStore) List(options ListPromptsOptions) (ListPromptsResult[PromptRe
 	result := ListPromptsResult[PromptRef]{
 		Items: prompts,
 	}
-	// TODO: meaningful cursor/limit implementation
+	// TODO(#500): meaningful cursor/limit implementation
 	// For now returns all as simple implementation
 
 	if options.Limit > 0 && len(result.Items) > options.Limit {

go/dotprompt/dotprompt.go

@@ -159,7 +159,7 @@ func (dp *Dotprompt) DefinePartial(name string, source string, tpl *raymond.Temp
 	return nil
 }
 
-// TODO: Add register helpers
+// TODO(#501): Add register helpers
 func (dp *Dotprompt) RegisterHelpers(tpl *raymond.Template) error {
 	if dp.Helpers != nil {
 		for key, helper := range dp.Helpers {

go/dotprompt/helper.go

@@ -34,7 +34,7 @@ var templateHelpers = map[string]any{
 	"unlessEquals": UnlessEquals,
 }
 
-// TODO: Add pending: true for section helper
+// TODO(#494): Add pending: true for section helper
 // JSON serializes the given data to a JSON string with optional indentation.
 // Panics on serialization errors to match JavaScript's JSON.stringify fail-fast behavior.
 func JSON(serializable any, options *raymond.Options) raymond.SafeString {

go/dotprompt/parse_test.go

@@ -420,7 +420,7 @@ func TestExtractFrontmatterAndBody(t *testing.T) {
 	})
 
 	t.Run("should return empty strings when there is no frontmatter marker", func(t *testing.T) {
-		// TODO: May be change this behavior to return a matching body when
+		// TODO(#495): May be change this behavior to return a matching body when
 		// there is no frontmatter marker and we have a body. This may need to
 		// be done across all the runtimes.
 		inputStr := "Hello World"

js/src/dotprompt.ts

@@ -298,7 +298,7 @@ export class Dotprompt {
     out = outWithoutTemplate as PromptMetadata<ModelConfig>;
 
     out = removeUndefinedFields(out);
-    // TODO: Can this be done concurrently?
+    // TODO(#493): Can this be done concurrently?
     out = await this.resolveTools(out);
     out = await this.renderPicoschema(out);
 

js/src/parse.test.ts

@@ -856,7 +856,7 @@ Template content`;
   });
 
   it('should handle document with empty frontmatter', () => {
-    // TODO: Check whether this is the correct behavior.
+    // TODO(#495): Check whether this is the correct behavior.
     const source = '---\n\n---\nJust template content';
     const result = parseDocument(source);
     expect(result).toMatchObject({

python/dotpromptz/src/dotpromptz/dotprompt.py

@@ -379,7 +379,7 @@ async def _resolve_metadata(
             delattr(out, 'template')
 
         out = remove_undefined_fields(out)
-        # TODO: can this be done concurrently?
+        # TODO(#493): can this be done concurrently?
         out = await self._resolve_tools(out)
         out = await self._render_picoschema(out)
         return out
@@ -417,10 +417,10 @@ async def _process_output_schema(schema_to_process: Any) -> None:
 
         async with anyio.create_task_group() as tg:
             if needs_input_processing and meta.input is not None:
-                # TODO: use meta.input.model_dump(exclude_none=True)?
+                # TODO(#499): use meta.input.model_dump(exclude_none=True)?
                 tg.start_soon(_process_input_schema, meta.input.schema)
             if needs_output_processing and meta.output is not None:
-                # TODO: use meta.output.model_dump(exclude_none=True)?
+                # TODO(#499): use meta.output.model_dump(exclude_none=True)?
                 tg.start_soon(_process_output_schema, meta.output.schema)
 
         return new_meta
@@ -440,7 +440,7 @@ async def _wrapped_schema_resolver(self, name: str) -> JsonSchema | None:
         if self._schema_resolver is None:
             return None
 
-        # TODO: Should we cache the resolved schema in self._schemas?
+        # TODO(#498): Should we cache the resolved schema in self._schemas?
         return await resolve_json_schema(name, self._schema_resolver)
 
     async def _resolve_tools(self, metadata: PromptMetadata[ModelConfigT]) -> PromptMetadata[ModelConfigT]:

python/dotpromptz/src/dotpromptz/parse.py

@@ -274,7 +274,7 @@ def parse_document(source: str) -> ParsedPrompt[T]:
                 template=body.strip(),
             )
     except Exception as e:
-        # TODO: Should this be an error?
+        # TODO(#496): Should this be an error?
         print(f'Dotprompt: Error parsing YAML frontmatter: {e}')
         # Return a basic ParsedPrompt with just the template
         return ParsedPrompt(