Add Support for Current Ticket in Branch

- Add parsing of the current git branch (fails gracefully) to extract a
  prefixed ticket ID from the branch name
- Add output to the CLI to make user aware of unfinished TODOs for their
  current branch

Author: medley56

.devcontainer/CLAUDE.md

@@ -30,6 +30,34 @@ repos:
         args: ['-j', 'MYJIRA,PROJECT,TEAM']
 ```
 
+### Recommended Configurations
+
+#### For Maximum TODO Visibility (Recommended)
+Get both violations AND branch-specific TODOs, check all files:
+
+```yaml
+repos:
+  - repo: https://github.com/lasp/prevent-dangling-todos
+    hooks:
+      - id: prevent-dangling-todos
+        args: ['-j', 'MYJIRA', '-v']
+        always_run: true  # Check all files for branch-specific TODOs
+        verbose: true     # Always show output
+```
+
+#### For Non-Blocking Alerts with Branch Tracking
+Alert about TODOs without blocking commits:
+
+```yaml
+repos:
+  - repo: https://github.com/lasp/prevent-dangling-todos
+    hooks:
+      - id: prevent-dangling-todos
+        args: ['-j', 'MYJIRA', '--succeed-always', '-v']
+        always_run: true  # Check all files for branch-specific TODOs
+        verbose: true     # Always show output even when hook succeeds
+```
+
 ### Custom Comment Types
 
 Check only specific comment types:
@@ -64,20 +92,60 @@ repos:
         args: ['-j', 'MYJIRA', '-q']
 ```
 
-**Verbose Mode**: Shows configuration, violations, file status summary, and help text
+**Verbose Mode**: Shows configuration, violations, file status summary, help text, and branch-specific TODOs
+```yaml
+repos:
+  - repo: https://github.com/lasp/prevent-dangling-todos
+    hooks:
+      - id: prevent-dangling-todos
+        args: ['-j', 'MYJIRA', '-v']
+```
+
+### Branch-Specific TODO Tracking
+
+The tool automatically detects your current git branch and extracts ticket IDs that match your configured Jira prefixes. When TODOs reference the current branch's ticket, they are displayed separately as informational warnings (yellow ⚠️) rather than violations (red ❌).
+
+#### Checking All Files (Including Untouched)
+
+By default, pre-commit only runs on modified files. To catch branch-specific TODOs in files that haven't been changed, configure the hook to **always run**:
+
+#### Complete Branch Tracking Configuration
+
+For full branch-specific TODO tracking, use both verbose and always_run:
+
 ```yaml
 repos:
   - repo: https://github.com/lasp/prevent-dangling-todos
     hooks:
       - id: prevent-dangling-todos
         args: ['-j', 'MYJIRA', '-v']
+        always_run: true
+        verbose: true  # Ensure output is always shown
 ```
 
+**Example branch detection:**
+- Branch: `feature/MYJIRA-123-user-auth`
+- Detected ticket: `MYJIRA-123`
+- TODOs with `MYJIRA-123` will be shown as warnings, not violations
+
+**Note:** Branch detection messages are only shown in verbose mode or when there are issues detecting the branch.
+
 ### Alert Without Blocking
 
 Alert developers to dangling TODOs without blocking commits. When using `--succeed-always`, the hook will always return exit code 0 (success), but by default pre-commit hides output from successful hooks. To ensure TODO violations are still visible, you should configure verbose output:
 
-**Recommended: Always show output (persistent configuration)**
+**Recommended: Always show output with branch tracking**
+```yaml
+repos:
+  - repo: https://github.com/lasp/prevent-dangling-todos
+    hooks:
+      - id: prevent-dangling-todos
+        args: ['-j', 'MYJIRA', '--succeed-always', '-v']
+        always_run: true  # Check all files for branch-specific TODOs
+        verbose: true  # Always show output, even when hook succeeds
+```
+
+**Alternative: Basic alert without branch tracking**
 ```yaml
 repos:
   - repo: https://github.com/lasp/prevent-dangling-todos
@@ -87,7 +155,7 @@ repos:
         verbose: true  # Always show output, even when hook succeeds
 ```
 
-**Alternative: Show output only when needed (runtime flag)**
+**Runtime flag approach (minimal configuration)**
 ```yaml
 repos:
   - repo: https://github.com/lasp/prevent-dangling-todos
@@ -167,6 +235,11 @@ TODO, FIXME, XXX, HACK, BUG, REVIEW, OPTIMIZE, REFACTOR
 ```
 ❌ file.py:15: # TODO: Missing Jira reference
 ❌ file.py:23: # FIXME: Another comment without ticket
+
+
+⚠️  Unresolved TODOs for current branch ticket MYJIRA-123:
+⚠️  auth.py:10: # TODO MYJIRA-123: Complete OAuth implementation
+⚠️  auth.py:25: # FIXME MYJIRA-123: Handle token refresh edge case
 ```
 
 **Quiet Mode**: No output (silent)
@@ -178,12 +251,18 @@ TODO, FIXME, XXX, HACK, BUG, REVIEW, OPTIMIZE, REFACTOR
 ❌ file.py:15: # TODO: Missing Jira reference
 ❌ file.py:23: # FIXME: Another comment without ticket
 
+⚠️  Unresolved TODOs for current branch ticket MYJIRA-123:
+⚠️  auth.py:10: # TODO MYJIRA-123: Complete OAuth implementation
+⚠️  auth.py:25: # FIXME MYJIRA-123: Handle token refresh edge case
+
 ✅ clean_file.py
 ❌ file.py
 
 💡 Please add Jira issue references to work comments like:
    // TODO MYJIRA-123: Implement user authentication
    # FIXME MYJIRA-124: Handle edge case for empty input
+
+Note: No ticket ID detected in current branch 'main'
 ```
 
 ## Troubleshooting
@@ -202,7 +281,17 @@ TODO, FIXME, XXX, HACK, BUG, REVIEW, OPTIMIZE, REFACTOR
    - Check that your comment format matches: `# TODO JIRA-123: Description`
    - Ensure the Jira prefix matches your configuration
 
-4. **False positives**
+4. **Branch-specific TODOs not appearing**
+   - **Solution**: Use `verbose: true` in your config
+   - Use `always_run: true` to check all files, not just modified ones
+   - Ensure your branch name contains a valid ticket ID (e.g., `feature/MYJIRA-123-description`)
+
+5. **Branch detection not working**
+   - Ensure you're in a git repository with a valid branch
+   - Check that your branch name includes a ticket ID matching your Jira prefixes
+   - Branch detection messages appear in verbose mode or when there are detection issues
+
+6. **False positives**
    - Use `-c/--comment-prefix` to check only specific comment types
    - Consider using `-q/--quiet` mode for silent operation in CI/CD pipelines
    - Use `-v/--verbose` mode when you need detailed information about what files are being checked

README.md

@@ -2,8 +2,10 @@
 
 import argparse
 import os
+import re
+import subprocess
 import sys
-from typing import List, Optional
+from typing import List, Optional, Tuple
 
 from prevent_dangling_todos.prevent_todos import TodoChecker
 
@@ -134,6 +136,62 @@ def _parse_comma_separated(value: Optional[str]) -> Optional[List[str]]:
     return parsed if parsed else None
 
 
+def _get_current_git_branch() -> Tuple[Optional[str], Optional[str]]:
+    """
+    Get the current git branch name.
+
+    Returns
+    -------
+    tuple of (Optional[str], Optional[str])
+        (branch_name, error_message) - Returns (None, error_msg) if detection fails
+    """
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            branch = result.stdout.strip()
+            if branch:
+                return branch, None
+            return None, "Unable to detect current git branch"
+        return None, "Unable to detect current git branch"
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return None, "Unable to detect current git branch"
+
+
+def _extract_ticket_id(branch_name: str, jira_prefixes: List[str]) -> Optional[str]:
+    """
+    Extract a ticket ID from a branch name if it matches any of the Jira prefixes.
+
+    Parameters
+    ----------
+    branch_name : str
+        The git branch name
+    jira_prefixes : list of str
+        List of valid Jira project prefixes
+
+    Returns
+    -------
+    str or None
+        The ticket ID (e.g., "LIBSDC-123") if found, otherwise None
+    """
+    if not branch_name or not jira_prefixes:
+        return None
+
+    # Build a pattern to match any of the Jira prefixes followed by a dash and numbers
+    # This will match patterns like LIBSDC-123 anywhere in the branch name
+    for prefix in jira_prefixes:
+        pattern = rf"{re.escape(prefix)}-\d+"
+        match = re.search(pattern, branch_name)
+        if match:
+            return match.group(0)
+
+    return None
+
+
 def main(argv: Optional[List[str]] = None) -> None:
     """
     Main entry point for the script.
@@ -198,17 +256,35 @@ def main(argv: Optional[List[str]] = None) -> None:
             file=sys.stderr,
         )
 
+    # Detect current git branch and extract ticket ID
+    branch_name, branch_error = _get_current_git_branch()
+    current_ticket_id = None
+    branch_detection_msg = None
+
+    if branch_error:
+        branch_detection_msg = f"Note: {branch_error}"
+    elif branch_name:
+        current_ticket_id = _extract_ticket_id(branch_name, final_jira_prefixes)
+        if not current_ticket_id:
+            branch_detection_msg = f"Note: No ticket ID detected in current branch '{branch_name}'"
+
     # Initialize checker with configuration
     checker = TodoChecker(
         jira_prefixes=final_jira_prefixes,
         quiet=args.quiet,
         verbose=args.verbose,
         comment_prefixes=final_comment_prefixes,
         succeed_always=final_succeed_always,
+        current_ticket_id=current_ticket_id,
     )
 
     # Check files and exit with appropriate code
     exit_code = checker.check_files(args.files)
+
+    # Show branch detection message if needed (not in quiet mode)
+    if branch_detection_msg and not args.quiet:
+        print(f"\n{branch_detection_msg}")
+
     sys.exit(exit_code)
 
 

prevent_dangling_todos/cli.py

@@ -45,6 +45,7 @@ def __init__(
         quiet: bool = False,
         verbose: bool = False,
         succeed_always: bool = False,
+        current_ticket_id: Optional[str] = None,
     ):
         """
         Initialize the TodoChecker.
@@ -61,6 +62,9 @@ def __init__(
             If True, show detailed output including config, violations, file status, and help. Default is False.
         succeed_always : bool, optional
             If True, always exit with code 0 even when violations are found. Default is False.
+        current_ticket_id : str, optional
+            The ticket ID for the current branch (e.g., "LIBSDC-123"). If provided, TODOs
+            matching this ticket will be tracked separately for informational output.
         """
         # Always store as list internally
         if isinstance(jira_prefixes, str):
@@ -72,6 +76,8 @@ def __init__(
         self.verbose = verbose
         self.succeed_always = succeed_always
         self.exit_code = 0
+        self.current_ticket_id = current_ticket_id
+        self.ticket_todos: list[tuple] = []  # Track TODOs for the current ticket
 
         # Comment prefixes that should require Jira references
         if comment_prefixes is None:
@@ -140,6 +146,9 @@ def check_file(self, file_path: str) -> List[Tuple[int, str]]:
                         # Check if it also contains a Jira reference
                         if not self.jira_pattern.search(line):
                             violations.append((line_num, line.rstrip()))
+                        # If we have a current ticket, check if this TODO is for it
+                        elif self.current_ticket_id and self.current_ticket_id in line:
+                            self.ticket_todos.append((file_path, line_num, line.rstrip()))
         except Exception as e:
             print(f"⚠️  Warning: Could not read {file_path}: {e}", file=sys.stderr)
 
@@ -187,13 +196,20 @@ def check_files(self, file_paths: List[str]) -> int:
                 for line_num, line_content in violations:
                     print(f"❌ {file_path}:{line_num}: {line_content}")
 
+        # Show ticket-specific TODOs with yellow warning (not in quiet mode)
+        if self.ticket_todos and not self.quiet:
+            print("")  # Blank line before ticket TODOs
+            print(f"⚠️  Unresolved TODOs for current branch ticket {self.current_ticket_id}:")
+            for file_path, line_num, line_content in self.ticket_todos:
+                print(f"⚠️  {file_path}:{line_num}: {line_content}")
+
         # Verbose mode: Show file status summary and help text
         if self.verbose:
             print("")  # Blank line before summary
             for file_path, is_clean in file_statuses:
                 status_icon = "✅" if is_clean else "❌"
                 print(f"{status_icon} {file_path}")
-            
+
             # Show help text only if violations were found
             if self.exit_code == 1:
                 print("")