TODO.sh - Convert TODO Comments to GitHub Issues

Overview

The todo.sh script automatically extracts TODO/FIXME/XXX/HACK comments from Swift files and creates corresponding GitHub issues. It includes duplicate detection and tracking to prevent creating multiple issues for the same TODO.

Quick Start

bash

# Preview what issues would be created (RECOMMENDED FIRST)
./todo.sh --dry-run

# Create issues for all unprocessed TODOs
./todo.sh

# Use custom labels
./todo.sh --label tech-debt

# Verbose output for debugging
./todo.sh --dry-run --verbose

Current Status

TODOs in Codebase: 47 TODO comments across 40 Swift files

Example TODOs Found:

AlertView.swift:62 - CHECK HISTORY OF THIS COMMIT

AppSources/VIEWS/JOURNAL/SettingsSheetView.swift:194 - NEED TO FIND STATUS VIEW IN CODEBASE

CHAT/MessageCardContainer.swift:236 - YES, YES, YES, YES - THIS IS THE UI I WANT, NEED TO KEEP AND INTEGRATE

CoreUIViews/FlippableCard.swift:119 - THIS MUST BE USED

CreateHome/JournalDescriptionView.swift:457 - THIS NEEDS PRIORITY ONE ATTENTION

Features

✅ Implemented

[x] Extracts TODO/FIXME/XXX/HACK comments from Swift files

[x] Creates one GitHub issue per TODO comment

[x] Hash-based duplicate detection

[x] Local tracking file (.todo-tracker.json) to prevent re-creating issues

[x] GitHub API duplicate checking via gh CLI

[x] Dry-run mode for previewing issues before creation

[x] Custom label support (default: todo, auto-generated)

[x] Verbose mode for debugging

[x] Direct links to code in issue body

[x] Rate limiting (1 second between issue creations)

[x] Comprehensive error handling

[x] Prerequisite validation (gh CLI, git repo, authentication)

Issue Format

Each created issue includes:

markdown

### TODO Comment

**File:** `path/to/file.swift`
**Line:** 123
**Hash:** `abc123...` (for duplicate detection)

// TODO: The actual TODO comment from the code

code

---

📍 [View in code](../../blob/main/path/to/file.swift#L123)

*Auto-generated from TODO comment by todo.sh*

Usage Examples

Basic Usage

bash

# 1. First, preview what will be created
./todo.sh --dry-run

# 2. Review the output, then create issues
./todo.sh

# 3. View created issues on GitHub
gh issue list --label todo

Custom Labels

bash

# Replace default labels with custom ones
./todo.sh --label tech-debt

# Add multiple labels
./todo.sh --label todo --label priority-high --label needs-review

Debugging

bash

# See detailed processing information
./todo.sh --dry-run --verbose

# Check tracking file
cat .todo-tracker.json | jq .

How It Works

1. TODO Detection

The script uses git grep to find TODO patterns:

bash

git grep -n -E "(TODO|FIXME|XXX|HACK)[\s:(\[]" -- "*.swift"

Supported Formats:

// TODO: Description

//TODO Description (no space)

// FIXME: Problem

// XXX: Critical issue

// HACK: Temporary solution

2. Duplicate Prevention

Two-layer approach:

1. Local tracking - Checks .todo-tracker.json for previously processed TODOs 2. GitHub API check - Queries GitHub for existing open issues with the same hash

Hash Generation: md5(filepath:line_number:todo_text_first_50_chars)

This ensures:

TODOs that haven't changed won't create duplicate issues

You can run the script multiple times safely

Works across different machines (via GitHub API check)

3. Issue Creation

Uses the GitHub CLI (gh) to create issues:

bash

gh issue create \
  --title "TODO: Description" \
  --body "..." \
  --label "todo" \
  --label "auto-generated"

Files

todo.sh - Main script (14KB)

.todo-tracker.json - Local tracking file (gitignored)

TODO_SH_USAGE.md - This documentation

Tracking File Format

.todo-tracker.json stores processed TODOs:

json

{
  "todos": [
    {
      "hash": "abc123...",
      "issue_number": "42",
      "file": "/path/to/file.swift",
      "line": "123",
      "created_at": "2025-04-28T10:30:00Z"
    }
  ]
}

Note: This file is in .gitignore to prevent merge conflicts and allow per-developer tracking.

Prerequisites

Required

1. GitHub CLI (gh) - Install here

bash

# macOS
   brew install gh
   
   # Authenticate
   gh auth login

2. Git repository - Must be run from within a git repository

3. GitHub authentication - gh auth status should show you're logged in

Optional

jq - For pretty-printing the tracking file (not required for script operation)

Edge Cases & Limitations

Multi-line TODOs

Currently, each TODO line creates a separate issue:

swift

// TODO: This is part 1
//       This is part 2  <- Creates a second issue

Workaround: Write TODOs on a single line, or manually consolidate issues after creation.

TODO Text Extraction

Some edge cases in text extraction:

swift

// TODO: coordinates: (0.0, 0.0) // TODO: Add real coordinates

This creates an issue with the full line. Consider editing the title manually on GitHub if needed.

Line Number Changes

If a TODO moves to a different line (e.g., after adding code above it), the hash changes and a new issue will be created. The old issue remains open.

Recommendation: Close the old issue manually and reference the new one, or avoid running the script frequently during active development.

Troubleshooting

"GitHub CLI is not authenticated"

bash

gh auth login

Follow the prompts to authenticate.

"Cannot detect GitHub repository"

Make sure you're in a directory with a GitHub remote:

bash

git remote -v

"sed: RE error: parentheses not balanced"

This was fixed by switching to perl for text extraction. If you see this error, make sure you're using the latest version of todo.sh.

No TODOs Found

bash

# Manually check for TODOs
git grep -E "(TODO|FIXME|XXX|HACK)" -- "*.swift"

If you see TODOs but the script doesn't find them, they may not match the expected pattern. Ensure they have a space or colon after the keyword.

Integration with GitHub

View All TODO Issues

bash

gh issue list --label todo

Close a TODO Issue

bash

gh issue close <issue-number> --comment "Resolved in commit abc123"

Search TODO Issues

bash

gh issue list --label todo --search "in:title SPECIFIC_TEXT"

Future Enhancements

Potential additions (not currently implemented):

[ ] --close-resolved flag to automatically close issues when TODOs are removed

[ ] Multi-line TODO consolidation

[ ] TODO metadata parsing (author, date, priority)

[ ] GitHub Actions workflow for automated TODO tracking on push

[ ] Support for other file types (Kotlin, TypeScript, etc.)

[ ] Project board integration

[ ] Assignee support based on git blame

Best Practices

1. Run with --dry-run first - Always preview before creating issues 2. Clean up old TODOs - Remove resolved TODOs from code promptly 3. Write descriptive TODOs - The TODO text becomes the issue title 4. Use consistent format - Stick to // TODO: Description for best results 5. Review created issues - After running, check GitHub and refine issue descriptions 6. Don't run too frequently - Run when you want to create tracking issues, not after every code change

Example Workflow

bash

# 1. Write TODOs in your code
# // TODO: Implement user profile caching
# // FIXME: Handle edge case when user has no email

# 2. Preview what issues would be created
./todo.sh --dry-run | less

# 3. Create the issues
./todo.sh

# 4. View created issues
gh issue list --label todo

# 5. Work on TODOs and close issues as you complete them
# (TODO comments should be removed from code when work is done)

# 6. Close issues when complete
gh issue close 42 --comment "Implemented in commit abc123"

Support

For issues with the script: 1. Check this documentation 2. Run with --verbose flag for detailed output 3. Check prerequisite installation (gh CLI, git, authentication) 4. Review existing GitHub issues for similar problems

---

Created: April 28, 2026 Version: 1.0 Author: Generated by GitHub Copilot for theunpartyunppp project