pmat 3.16.0

#![allow(deprecated)]
//! CLI Documentation Enforcement Tests (EXTREME TDD - RED Phase)
//!
//! TICKET: PMAT-7001
//! Phase: RED (All tests should FAIL)
//! Status: 🔴 Tests written but not implemented
//!
//! This test suite verifies that all CLI commands have complete, accurate,
//! and non-generic documentation. Tests use assert_cmd to validate actual
//! CLI behavior.
//!
//! ## Test Categories:
//! 1. Help text existence
//! 2. Flag documentation completeness
//! 3. Description quality (non-generic)
//! 4. Examples presence
//! 5. Documentation drift detection

use assert_cmd::Command;
use predicates::prelude::*;

// ============================================================================
// Category 1: Help Text Existence
// ============================================================================

/// RED: All commands must have --help that returns success
///
/// Verifies that every PMAT command has a working --help flag that
/// displays usage information.
#[test]
#[ignore] // Remove #[ignore] when implementing
fn red_test_all_commands_have_help() {
    let commands = vec![
        // Analyze commands
        "analyze complexity",
        "analyze satd",
        "analyze dead-code",
        "analyze churn",
        "analyze deep-context",
        // Maintain commands
        "maintain health",
        "maintain roadmap",
        // Scaffold commands
        "scaffold agent",
        // Hooks commands
        "hooks install",
        "hooks verify",
        "hooks refresh",
    ];

    for cmd in commands {
        Command::cargo_bin("pmat")
            .unwrap()
            .args(cmd.split_whitespace())
            .arg("--help")
            .assert()
            .success()
            .stdout(predicate::str::contains("Usage:"));
    }
}

/// RED: Help text must include basic structure
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_help_has_basic_structure() {
    let output = Command::cargo_bin("pmat")
        .unwrap()
        .args(["maintain", "roadmap", "--help"])
        .assert()
        .success()
        .get_output()
        .stdout
        .clone();

    let help = String::from_utf8(output).unwrap();

    assert!(help.contains("Usage:"), "Missing Usage section");
    assert!(
        help.contains("Options:") || help.contains("FLAGS:"),
        "Missing Options/FLAGS section"
    );
}

// ============================================================================
// Category 2: Flag Documentation Completeness
// ============================================================================

/// RED: maintain roadmap must document ALL flags
///
/// From PMAT-6012, maintain roadmap has these flags:
/// - --validate
/// - --health
/// - --fix
/// - --generate-tickets (added in PMAT-6012)
/// - --dry-run
/// - --format
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_maintain_roadmap_flags_complete() {
    let output = Command::cargo_bin("pmat")
        .unwrap()
        .args(["maintain", "roadmap", "--help"])
        .assert()
        .success()
        .get_output()
        .stdout
        .clone();

    let help = String::from_utf8(output).unwrap();

    // All flags from code must appear in help
    assert!(
        help.contains("--validate"),
        "Missing --validate flag documentation"
    );
    assert!(
        help.contains("--health"),
        "Missing --health flag documentation"
    );
    assert!(help.contains("--fix"), "Missing --fix flag documentation");
    assert!(
        help.contains("--generate-tickets"),
        "Missing --generate-tickets flag documentation (PMAT-6012)"
    );
    assert!(
        help.contains("--dry-run"),
        "Missing --dry-run flag documentation"
    );
    assert!(
        help.contains("--format"),
        "Missing --format flag documentation"
    );
}

/// RED: scaffold agent must document ALL flags
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_scaffold_agent_flags_complete() {
    let output = Command::cargo_bin("pmat")
        .unwrap()
        .args(["scaffold", "agent", "--help"])
        .assert()
        .success()
        .get_output()
        .stdout
        .clone();

    let help = String::from_utf8(output).unwrap();

    assert!(
        help.contains("--template") || help.contains("-t"),
        "Missing --template flag"
    );
    assert!(
        help.contains("--quality-level") || help.contains("--quality"),
        "Missing --quality-level flag"
    );
    assert!(
        help.contains("--output") || help.contains("-o"),
        "Missing --output flag"
    );
    assert!(
        help.contains("--features") || help.contains("-f"),
        "Missing --features flag"
    );
}

/// RED: maintain health must document ALL flags
///
/// From PMAT-6010, health has parallel check flags
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_maintain_health_flags_complete() {
    let output = Command::cargo_bin("pmat")
        .unwrap()
        .args(["maintain", "health", "--help"])
        .assert()
        .success()
        .get_output()
        .stdout
        .clone();

    let help = String::from_utf8(output).unwrap();

    assert!(help.contains("--quick"), "Missing --quick flag");
    assert!(help.contains("--all"), "Missing --all flag");
    assert!(help.contains("--check-build"), "Missing --check-build flag");
    assert!(help.contains("--check-tests"), "Missing --check-tests flag");
    assert!(
        help.contains("--check-coverage"),
        "Missing --check-coverage flag"
    );
    assert!(
        help.contains("--check-complexity"),
        "Missing --check-complexity flag"
    );
    assert!(help.contains("--check-satd"), "Missing --check-satd flag");
}

// ============================================================================
// Category 3: Description Quality (Non-Generic)
// ============================================================================

/// RED: Help text must have DESCRIPTIVE text, not just flag names
///
/// Bad:  "--validate    Validate"
/// Good: "--validate    Validate roadmap structure and ticket consistency"
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_help_has_descriptive_text() {
    let output = Command::cargo_bin("pmat")
        .unwrap()
        .args(["maintain", "roadmap", "--help"])
        .assert()
        .success()
        .get_output()
        .stdout
        .clone();

    let help = String::from_utf8(output).unwrap();

    // Each flag should have description >10 chars
    // (more than just repeating the flag name)

    // Check for meaningful --validate description
    assert!(
        help.contains("Validate roadmap structure")
            || help.contains("Check roadmap consistency")
            || help.contains("Verify roadmap and tickets"),
        "Missing descriptive text for --validate"
    );

    // Check for meaningful --generate-tickets description
    assert!(
        help.contains("missing ticket files")
            || help.contains("Create ticket files from roadmap")
            || help.contains("Auto-generate"),
        "Missing descriptive text for --generate-tickets"
    );
}

/// RED: No generic descriptions allowed
///
/// Forbidden patterns:
/// - "The X parameter"
/// - "Input value"
/// - "Output value"
/// - Just the parameter name repeated
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_no_generic_descriptions_cli() {
    let commands = vec!["scaffold agent", "maintain roadmap", "maintain health"];

    for cmd in commands {
        let output = Command::cargo_bin("pmat")
            .unwrap()
            .args(cmd.split_whitespace())
            .arg("--help")
            .assert()
            .success()
            .get_output()
            .stdout
            .clone();

        let help = String::from_utf8(output).unwrap();

        // Generic patterns that should NOT appear
        let forbidden = vec![
            "The name parameter",
            "The template parameter",
            "The output parameter",
            "Input value",
            "Output value",
        ];

        for pattern in &forbidden {
            assert!(
                !help.contains(pattern),
                "Command '{}' contains forbidden generic pattern: '{}'",
                cmd,
                pattern
            );
        }
    }
}

// ============================================================================
// Category 4: Examples Presence
// ============================================================================

/// RED: Help must include EXAMPLES section
///
/// Users learn best from examples. Every command should show
/// at least one example of common usage.
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_help_includes_examples() {
    let commands = vec![
        "scaffold agent",
        "maintain roadmap",
        "maintain health",
        "analyze complexity",
    ];

    for cmd in commands {
        let output = Command::cargo_bin("pmat")
            .unwrap()
            .args(cmd.split_whitespace())
            .arg("--help")
            .assert()
            .success()
            .get_output()
            .stdout
            .clone();

        let help = String::from_utf8(output).unwrap();

        assert!(
            help.contains("EXAMPLE")
                || help.contains("Example")
                || help.contains("example")
                || help.contains("EXAMPLES")
                || help.contains("Examples"),
            "Command '{}' missing examples section",
            cmd
        );
    }
}

/// RED: Examples should show actual command syntax
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_examples_show_command_syntax() {
    let output = Command::cargo_bin("pmat")
        .unwrap()
        .args(["scaffold", "agent", "--help"])
        .assert()
        .success()
        .get_output()
        .stdout
        .clone();

    let help = String::from_utf8(output).unwrap();

    // Example should show actual pmat command
    assert!(
        help.contains("pmat scaffold") || help.contains("$ pmat scaffold"),
        "Examples should show actual 'pmat scaffold' commands"
    );
}

// ============================================================================
// Category 5: Documentation Drift Detection
// ============================================================================

/// RED: All flags in code must appear in help
///
/// This test would extract flags from clap definitions and verify
/// they all appear in --help output. This prevents documentation drift
/// where code adds flags but help text isn't updated.
///
/// Note: This test requires helper functions to parse clap definitions
/// from Rust source code using the syn crate. This is deferred to Phase 3
/// (REFACTOR) as it requires complex AST parsing.
///
/// **Status**: Deferred to Phase 3 - requires syn crate integration
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_no_undocumented_flags() {
    // TODO: Phase 3 - Implement automated drift detection
    // Requires:
    // 1. Parse clap definitions from source using syn crate
    // 2. Extract flags from parsed AST
    // 3. Compare with --help output
    //
    // For now, other tests manually verify major commands
    unimplemented!("Automated drift detection deferred to Phase 3 (REFACTOR)");
}

/// RED: Required vs optional should be clear
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_required_vs_optional_clear() {
    let output = Command::cargo_bin("pmat")
        .unwrap()
        .args(["scaffold", "agent", "--help"])
        .assert()
        .success()
        .get_output()
        .stdout
        .clone();

    let help = String::from_utf8(output).unwrap();

    // Should indicate which arguments are required
    // Common patterns: [required], <required>, or prose description
    assert!(
        help.contains("[required]") ||
        help.contains("<") || // angle brackets often mean required
        help.contains("Required:") ||
        help.contains("Arguments:"), // clap typically shows this
        "Help should clearly indicate required vs optional arguments"
    );
}

// ============================================================================
// Category 6: Command-Specific Validations
// ============================================================================

/// RED: hooks commands must be documented
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_hooks_commands_documented() {
    let hook_commands = vec!["hooks install", "hooks verify", "hooks refresh"];

    for cmd in hook_commands {
        Command::cargo_bin("pmat")
            .unwrap()
            .args(cmd.split_whitespace())
            .arg("--help")
            .assert()
            .success()
            .stdout(predicate::str::contains("Usage:"));
    }
}

/// RED: analyze commands must be documented
#[test]
#[ignore = "requires docs validation setup"]
fn red_test_analyze_commands_documented() {
    let analyze_commands = vec![
        "analyze complexity",
        "analyze satd",
        "analyze dead-code",
        "analyze churn",
        "analyze deep-context",
    ];

    for cmd in analyze_commands {
        Command::cargo_bin("pmat")
            .unwrap()
            .args(cmd.split_whitespace())
            .arg("--help")
            .assert()
            .success()
            .stdout(predicate::str::contains("Usage:"));
    }
}

// ============================================================================
// Helper Functions (To be implemented in Phase 2)
// ============================================================================

// These functions will be implemented when we move to GREEN phase

/// Extract all flags from help text
#[allow(dead_code)]
fn extract_flags_from_help(_command: &str) -> Vec<String> {
    // TODO: Parse --help output and extract flag names
    // This will use regex or parsing to find all --flag-name entries
    unimplemented!("Will implement in Phase 2")
}

/// Extract all flags from clap command definitions
#[allow(dead_code)]
fn extract_flags_from_clap_definitions(_command: &str) -> Vec<String> {
    // TODO: Parse clap #[arg(long)] definitions from source
    // This might use syn crate to parse Rust code
    unimplemented!("Will implement in Phase 2")
}

/// Check if description is generic/placeholder
#[allow(dead_code)]
fn is_generic_description(_desc: &str) -> bool {
    // TODO: Implement generic description detection
    // Check for patterns like "The X parameter", length, etc.
    unimplemented!("Will implement in Phase 2")
}

// ============================================================================
// Test Documentation
// ============================================================================

// Expected Failures:
//
// PHASE 1 (RED) - All tests should FAIL because:
// 1. Some commands missing --help text
// 2. Some flags not documented in help
// 3. Some descriptions are generic
// 4. Some commands missing examples
// 5. Documentation drift exists (code vs help mismatch)
//
// PHASE 2 (GREEN) - After implementation:
// 1. All commands will have complete help
// 2. All flags will be documented
// 3. All descriptions will be descriptive
// 4. All commands will have examples
// 5. Automated drift detection will catch mismatches
//
// PHASE 3 (REFACTOR) - After optimization:
// 1. Helper functions will be optimized
// 2. Tests will run faster (<1 second total)
// 3. Integration with quality gates complete