unused_code: handle git grep no-matches and untracked (#203)

* unused_code: handle git grep no-matches and untracked; detect pytest fixtures incl. param usage; fail CI on unexpected git errors; aggregate all unused functions per file; silence coverage show_contexts warning; fix jira_utils config precedence for tests

* tests(unused_code): use bytes for FakeCompleted stdout/stderr to match subprocess.CompletedProcess and avoid AttributeError in _git_grep

* fix(unused_code): normalize _git_grep behavior; formatting after pre-commit

* fix(unused_code): parse git grep -n output with split(':', 2) to isolate line content; ensure commented-line checks work reliably

* tests(unused_code): add commented-usage test; fix mock to use text stdout/stderr; fix formatting\nfix(unused_code): add -I to git grep to ignore binaries

* feat(jira_utils): prefer config values when present, fallback to CLI/env for url/token to avoid unintended failures

* feat(unused_code): detect supported git grep regex flag (-P or -G) once and cache; use detected flag for portability

* fix(unused_code): tighten call-site regex with word boundary; add portable patterns for -P/-G; keep comment filtering correct

* feat(unused_code): aggregate processing errors instead of exiting on first; show summary\ntests(unused_code): use posix path in mock grep output and align with new call pattern

* feat(unused_code): enhance git grep reliability and cross-platform compatibility

- Replace manual _GREP_FLAG with thread-safe @lru_cache decorator for grep flag detection
- Add whitespace handling (\s*) to call-site regex patterns for better match accuracy
- Update fixture-parameter search to use [[:space:]]+ for POSIX compatibility with -G flag
- Add -e option to git grep for safer handling of patterns starting with dash
- Fix git grep output parsing using rsplit() for Windows path compatibility (handles drive letters)
- Add graceful handling of malformed git grep output with proper validation
- Implement pre-flight grep flag detection with clear error messaging
- Add deterministic output sorting for consistent CI/testing behavior
- Optimize grep flag detection to discard stdout/stderr in probe commands
- Add comprehensive tests for Windows path parsing and malformed output handling

These improvements address CodeRabbit AI feedback for better portability, reliability,
and maintainability across different platforms and edge cases.

* Add AI files to gitignore

* fix(unused_code): improve git grep output parsing and regex portability

- Use split() instead of rsplit() for proper git grep format parsing (path:line:content)
- Replace \s* with [[:space:]]* for better POSIX regex compatibility
- Fixes incorrect parsing when file paths contain colons

* refactor(jira_utils): simplify config precedence logic for url and token

Remove conditional branching based on config_file_path presence and use
consistent fallback pattern for both url and token configuration values.
This maintains the same functional behavior while improving code clarity.

* fix(unused_code): filter documentation patterns to prevent false positives

- Add _is_documentation_pattern() function to distinguish between actual function calls and documentation references
- Prevent false positives where functions are incorrectly marked as "used" when only referenced in docstrings, parameter descriptions, or type annotations
- Improve accuracy of unused code detection by filtering out common documentation patterns like "param_name (type): description"
- Add comprehensive test suite covering various documentation formats and edge cases
- Enhance _build_call_pattern documentation to clarify false positive mitigation

* refactor(unused_code): add unused_code_ prefix to test functions

- Rename all functions in unused_code_file_for_test.py to start with "unused_code_" prefix
- Update test references in test_doc_header_false_positives.py to use new function names
- Update documentation patterns and function calls to match new naming convention
- Ensures compliance with requirement that test functions must start with "unused_code_"
- Fix unused variable warnings in test files

* fix: used function as arg

* fix(unused_code): functions in docs

* fix: do not count imports as using the function

Author: myakove

.gitignore

@@ -159,3 +159,11 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
+
+# AI
+.cursor/
+CLAUDE.md
+.agent-os/
+.cursorrules
+.claude/
+GEMINI.md

18

@@ -151,6 +151,7 @@ def process_jira_command_line_config_file(
     config_dict = get_util_config(util_name="pyutils-jira", config_file_path=config_file_path)
     url = url or config_dict.get("url", "")
     token = token or config_dict.get("token", "")
+
     if not (url and token):
         LOGGER.error("Jira url and token are required.")
         sys.exit(1)

apps/jira_utils/jira_information.py

@@ -4,11 +4,42 @@ Helper to identify unused code in a pytest repository. It should be run from ins
 
 ## Usage
 
+### Basic Usage
+
 ```bash
+# Analyze all Python files in the current directory (must be a git repository)
 pyutils-unusedcode
+
+# Show help with all available options
 pyutils-unusedcode --help
 ```
 
+### Analyze Specific Files or Directories
+
+```bash
+# Analyze a single Python file
+pyutils-unusedcode --file-path /path/to/your/file.py
+pyutils-unusedcode -f /path/to/your/file.py
+
+# Analyze all Python files in a specific directory recursively
+pyutils-unusedcode --directory /path/to/your/project
+pyutils-unusedcode -d /path/to/your/project
+```
+
+**Note:** When using `--file-path` or `--directory`, the tool will analyze files from any git repository, not just the current working directory.
+
+## Command-Line Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--file-path` | `-f` | Analyze a single Python file for unused functions. Must be an existing .py file. |
+| `--directory` | `-d` | Analyze all Python files in a directory recursively for unused functions. Must be an existing directory. |
+| `--exclude-files` | | Comma-separated list of files to exclude from analysis. |
+| `--exclude-function-prefixes` | | Comma-separated list of function prefixes to exclude from analysis. |
+| `--config-file-path` | | Path to custom config file (default: `~/.config/python-utility-scripts/config.yaml`). |
+| `--verbose` | `-v` | Enable verbose logging for debugging. |
+| `--help` | | Show help message with all available options. |
+
 ## Config file
 
 To skip unused code check on specific files or functions of a repository, a config file with the list of names of such files and function prefixes should be added to