🔍 feat(maniphest): Enhance task search with free-text and flexible filtering

[Timpan4]

Fixes #107

⚠️ BREAKING CHANGES

This PR introduces breaking changes to the phabfive maniphest search command syntax to enable free-text search functionality.

Migration Guide

OLD SYNTAX (before this change):

phabfive maniphest search "My Project"  # Search by project/tag
phabfive maniphest search "Backend*" --updated-after=7

NEW SYNTAX (current):

# Free-text search (new primary use case)
phabfive maniphest search "Let's Encrypt"
phabfive maniphest search "API error" --status="in:Open"

# Project/tag filtering (moved to --tag option)
phabfive maniphest search --tag "My Project"
phabfive maniphest search --tag "Backend*" --updated-after=7

# Combined search
phabfive maniphest search "OpenStack" --tag "System-Board"
phabfive maniphest search "database" --tag "Backend" --updated-after=7

Quick Migration:

• Replace: phabfive maniphest search "ProjectName"
• With: phabfive maniphest search --tag "ProjectName"
• All existing project patterns (wildcards, AND/OR logic) work unchanged
• with --tag

Changes

Core Functionality

Free-Text Search

• New text search capability: Search for text within task titles and
  descriptions - Primary positional argument: [<text_query>] is now
  optional and used for free-text search - API integration: Uses
  Phabricator's query constraint for searching - Case-insensitive:
• Searches are case-insensitive by default

Tag-Based Project Filtering

• New --tag option: Project/workboard filtering moved to explicit
  flag - Backward compatible patterns: All wildcard (*, prefix*,
  *suffix) and AND/OR logic (ProjectA+ProjectB, ProjectA,ProjectB) patterns preserved
• • Parameter renamed: Internal project parameter renamed to tag
• or clarity

Validation

• Required filters: At least one filter must be provided (text
  query, --tag, date filters, column filters, priority filters, or status filters)
• Helpful error messages: Clear guidance when no search criteria specified
• • Prevents accidents: Avoids accidentally querying entire task
• tabase

Command-Line Interface

• Updated help text: New examples showing both free-text and
  tag-based search - Comprehensive documentation: 70+ lines of
  examples and usage patterns - Clear migration path: Examples section
• includes migration guidance

Examples

Basic Usage

# Free-text search across all projects
phabfive maniphest search "Let's Encrypt"
phabfive maniphest search "kubernetes migration"
phabfive maniphest search "API timeout error"

# Tag-only search (project filtering)
phabfive maniphest search --tag "My Project"
phabfive maniphest search --tag "Backend*"
phabfive maniphest search --tag "*2024"

# Combined search (text + tag)
phabfive maniphest search "security" --tag "Backend"
phabfive maniphest search "OpenStack" --tag "Infrastructure"

Advanced Filtering

# Text search with date filters
phabfive maniphest search "migration" --updated-after=7
phabfive maniphest search "error" --created-after=30

# Text search with status/priority filters
phabfive maniphest search "bug" --status="in:Open"
phabfive maniphest search "urgent" --priority="in:High"

# Tag search with complex patterns (AND/OR logic still works!)
phabfive maniphest search --tag "Backend+Sprint 42"
phabfive maniphest search --tag "ProjectA,ProjectB,ProjectC"

# Combined with all filter types
phabfive maniphest search "performance" \
  --tag "Backend*" \
  --column="in:In Progress" \
  --updated-after=14 \
  --show-history

Validation Examples

# ERROR: No filters provided
phabfive maniphest search
# Output: ERROR - No search criteria specified. Please provide at least one of...

# OK: At least one filter provided
phabfive maniphest search --updated-after=7
phabfive maniphest search --tag "My Project"
phabfive maniphest search "search text"

Technical Details

API Changes

• maniphest.py:

  • Changed task_search() signature: project → text_query + tag
  • Added validation logic (25 lines)
  • Integrated query constraint for free-text search
  • Updated all project resolution logic to use tag parameter

• cli.py:

  • Updated argument parsing for optional <text_query>
  • Added --tag=PATTERN option
  • Updated help text with 15+ examples

Backward Compatibility

• Breaking: Old syntax phabfive maniphest search "Project" no
  longer works - Preserved: All wildcard patterns and AND/OR logic
  work identically with --tag - Migration required: Scripts must
• update to new syntax

Performance Considerations

• Validation prevents full scans: Requiring at least one filter
  prevents expensive queries - Efficient API usage: Text search uses
  Phabricator's built-in indexing - Combined filters: Multiple
• constraints reduce result set size

Documentation Updates

Comprehensive Documentation

• docs/maniphest-cli.md:

  • New "Free-Text Search" section
  • Updated "Basic Search" → "Basic Project Filtering"
  • Updated 50+ examples throughout
  • Updated "Wildcard Project Matching" section
  • Added "Combining Filters" section
  • Updated all real-world workflow examples

• README.md:

  • Updated quick start examples

• CHANGELOG.md:

  • Prominent breaking change notice
  • Migration guide
  • Rationale and validation details

Test Coverage

• tests/test_maniphest.py:
  • Added test placeholders for new functionality
  • Documents expected behavior for:
    • Text-only search
    • Tag-only search
    • Combined text + tag search
    • Validation behavior
    • AND/OR pattern compatibility

Benefits

1. Highly Requested Feature: Free-text search was the Added travis #1 requested
   feature (issue Support text query for maniphest search #107) 2. More Natural Search: Primary use case is now
   searching by content, not just projects 3. Flexible Filtering:
   Combine text search with project tags and other filters 4. Prevents
   Accidents: Validation ensures users don't accidentally query all tasks
2. Clear Migration Path: Comprehensive examples and documentation ease transition
3. 6. Backward Compatible Logic: All project pattern features
4. ldcards, AND/OR) work unchanged

Rationale

This breaking change enables a highly-requested feature (free-text
search in task titles/descriptions) while maintaining all existing
project filtering capabilities. The positional argument is better suited
for the more common use case (searching by text) rather than the less
common case (filtering by project). Project filtering is now more
explicit with the --tag flag.

---

Sample Output

Free-Text Search

$ phabfive maniphest search "Let's Encrypt" --updated-after=7
INFO - No tag specified, searching across all projects
INFO - Free-text search: 'Let's Encrypt'

- Link: http://phorge.domain.tld/T123
  Task:
    Name: "Update Let's Encrypt certificates"
    Status: Open
    Priority: High
    ...

Tag-Based Search

$ phabfive maniphest search --tag "Backend*" --updated-after=7
INFO - Tag pattern 'Backend*' resolved to 3 project(s)

- Link: http://phorge.domain.tld/T456
  Task:
    Name: "Refactor backend API"
    Status: In Progress
    ...

Combined Search

$ phabfive maniphest search "database" --tag "Infrastructure" 
--column="in:In Progress" INFO - Free-text search: 'database'
INFO - Searching 1 project(s)

- Link: http://phorge.domain.tld/T789
  Task:
    Name: "Database migration for new schema"
    Status: Open
    ...