docs: Update README and configuration for enhanced command options and output formats

feat: Add agent output format for report generation and implement test pattern rule for CDD compliance
refactor: Standardize configuration file naming and improve logging in pattern engine

Author: Jeshua ben Joseph

README.md

@@ -37,29 +37,56 @@ cargo add rust-guardian
 # Check entire project
 rust-guardian check
 
-# Check specific path
-rust-guardian check src/
-
-# Output JSON for CI/CD
-rust-guardian check --format json --severity error
-
-# Watch for changes during development  
-rust-guardian watch
-
-# Validate configuration
-rust-guardian validate-config guardian.yaml
-
-# Use custom .guardianignore file
-rust-guardian check --guardianignore .custom-ignore
-
-# Ignore all .guardianignore files
-rust-guardian check --no-ignore
-
-# Add temporary exclusions
-rust-guardian check --exclude "**/*.tmp" --exclude "staging/"
-
-# Explain a specific rule
-rust-guardian explain todo_comments
+# Check specific paths
+rust-guardian check src/ lib.rs
+
+# Output formats
+rust-guardian check --format json              # JSON for tooling
+rust-guardian check --format agent             # Agent-friendly: [line:path] violation
+rust-guardian check --format junit             # JUnit XML for CI/CD  
+rust-guardian check --format sarif             # SARIF for security tools
+rust-guardian check --format github            # GitHub Actions format
+
+# Filter by severity
+rust-guardian check --severity error           # Only errors
+rust-guardian check --severity warning         # Warnings and errors
+rust-guardian check --severity info            # All violations
+
+# Performance and caching
+rust-guardian check --cache                    # Enable caching
+rust-guardian check --cache-file /tmp/cache    # Custom cache location
+rust-guardian check --no-parallel              # Disable parallel processing
+rust-guardian check --max-violations 50        # Limit output
+
+# File filtering
+rust-guardian check --exclude "**/*.tmp"       # Additional exclude patterns
+rust-guardian check --exclude "legacy/" --exclude "vendor/"
+rust-guardian check --guardianignore .custom   # Custom ignore file
+rust-guardian check --no-ignore                # Ignore all .guardianignore files
+
+# Configuration and debugging
+rust-guardian check -c custom.yaml             # Custom config file
+rust-guardian check --verbose                  # Enable debug logging
+rust-guardian check --no-color                 # Disable colors
+rust-guardian check --fail-fast                # Stop on first error
+
+# Watch mode for development
+rust-guardian watch src/                       # Watch directory for changes
+rust-guardian watch --debounce 500             # Custom debounce ms
+
+# Configuration management
+rust-guardian validate-config                  # Validate guardian.yaml
+rust-guardian validate-config custom.yaml     # Validate custom config
+
+# Rule management
+rust-guardian rules                            # List all rules
+rust-guardian rules --enabled-only            # Only show enabled rules
+rust-guardian rules --category placeholders   # Filter by category
+rust-guardian explain todo_comments           # Explain specific rule
+
+# Cache management
+rust-guardian cache stats                     # Show cache statistics
+rust-guardian cache clear                     # Clear cache
 ```
 
 ### Library Usage
@@ -345,15 +372,28 @@ Colored terminal output with context:
 ```
 ❌ Code Quality Violations Found
 
-src/api/handlers.rs:45:12
-  → todo_comments: Placeholder comment detected: TODO
-  │ 
-45│     // TODO: Implement error handling
-  │            ^^^^
+📁 src/api/handlers.rs
+  45:12:todo_comments [error] Placeholder comment detected: TODO
+    │ // TODO: Implement error handling
 
 📊 Summary: 1 error, 2 warnings in 156 files (1.2s)
 ```
 
+### Agent Format
+Simplified format for automated processing and agent consumption:
+
+```
+[45:src/api/handlers.rs]
+Placeholder comment detected: TODO
+
+[102:src/lib.rs]  
+Traditional tests violate CDD - consciousness architecture should be self-validating
+
+[67:src/models.rs]
+Function returns Ok(()) with no meaningful implementation
+
+```
+
 ### JSON
 Machine-readable format for tooling:
 

guardian.yaml

@@ -116,6 +116,22 @@ patterns:
         message: "Magic number found: {match} - consider using a named constant"
         enabled: false
 
+# Test pattern violations for CDD compliance
+test_patterns:
+  severity: error
+  enabled: true
+  rules:
+    - id: no_traditional_tests
+      type: regex
+      pattern: '(mod\s+tests?\s*\{|#\[test\]|#\[cfg\(test\)\])'
+      message: "Traditional tests violate CDD principles - use integration tests instead: {match}"
+      severity: error
+      case_sensitive: true
+      exclude_if:
+        file_patterns:
+          - "**/integration_tests/**"
+          - "**/tests/**"
+
 # Reporting configuration for CI
 reporting:
   show_context_lines: 2

src/main.rs

@@ -161,6 +161,7 @@ enum OutputFormatArg {
     Junit,
     Sarif,
     Github,
+    Agent,
 }
 
 impl From<OutputFormatArg> for OutputFormat {
@@ -171,6 +172,7 @@ impl From<OutputFormatArg> for OutputFormat {
             OutputFormatArg::Junit => OutputFormat::Junit,
             OutputFormatArg::Sarif => OutputFormat::Sarif,
             OutputFormatArg::Github => OutputFormat::GitHub,
+            OutputFormatArg::Agent => OutputFormat::Agent,
         }
     }
 }
@@ -280,9 +282,9 @@ async fn run_check(
     } else {
         // Try to find default config file
         let default_configs = [
-            "rust_guardian.yaml",
-            "rust_guardian.yml",
-            ".rust_guardian.yaml",
+            "guardian.yaml",
+            "guardian.yml",
+            ".guardian.yaml",
         ];
         let mut config = None;
 
@@ -526,10 +528,10 @@ fn is_config_change(event: &notify::Event) -> Option<PathBuf> {
         // Check for common config file names
         if matches!(
             file_name,
-            "rust_guardian.yaml"
-                | "rust_guardian.yml"
-                | ".rust_guardian.yaml"
-                | ".rust_guardian.yml"
+            "guardian.yaml"
+                | "guardian.yml"
+                | ".guardian.yaml"
+                | ".guardian.yml"
         ) {
             return Some(path.clone());
         }
@@ -564,9 +566,9 @@ async fn run_watch_analysis_with_config(
     } else {
         // Try to find default config file
         let default_configs = [
-            "rust_guardian.yaml",
-            "rust_guardian.yml",
-            ".rust_guardian.yaml",
+            "guardian.yaml",
+            "guardian.yml",
+            ".guardian.yaml",
         ];
         let mut config = None;
 
@@ -665,7 +667,7 @@ async fn run_watch_analysis_with_config(
 }
 
 fn run_validate_config(config_path: Option<PathBuf>) -> GuardianResult<i32> {
-    let config_path = config_path.unwrap_or_else(|| PathBuf::from("rust_guardian.yaml"));
+    let config_path = config_path.unwrap_or_else(|| PathBuf::from("guardian.yaml"));
 
     println!("Validating configuration: {}", config_path.display());
 
@@ -815,7 +817,22 @@ fn run_list_rules(
     let config = if let Some(path) = config_path {
         GuardianConfig::load_from_file(path)?
     } else {
-        GuardianConfig::default()
+        // Try to find default config file
+        let default_configs = [
+            "guardian.yaml",
+            "guardian.yml", 
+            ".guardian.yaml",
+        ];
+        let mut config = None;
+
+        for config_name in &default_configs {
+            if Path::new(config_name).exists() {
+                config = Some(GuardianConfig::load_from_file(config_name)?);
+                break;
+            }
+        }
+
+        config.unwrap_or_else(GuardianConfig::default)
     };
 
     println!("📋 Available Rules\n");

src/patterns/mod.rs

@@ -104,8 +104,12 @@ impl PatternEngine {
         rule: &PatternRule,
         effective_severity: Severity,
     ) -> GuardianResult<()> {
+        tracing::debug!("Adding rule '{}' of type {:?} with pattern '{}' and severity {:?}", 
+                       rule.id, rule.rule_type, rule.pattern, effective_severity);
+        
         match rule.rule_type {
             RuleType::Regex => {
+                tracing::debug!("Compiling regex pattern '{}' for rule '{}'", rule.pattern, rule.id);
                 let regex = if rule.case_sensitive {
                     Regex::new(&rule.pattern)
                 } else {
@@ -261,9 +265,14 @@ impl PatternEngine {
         let file_path = file_path.as_ref();
         let mut matches = Vec::new();
 
+        tracing::debug!("Analyzing file '{}' with {} regex patterns and {} AST patterns", 
+                       file_path.display(), self.regex_patterns.len(), self.ast_patterns.len());
+
         // Apply regex patterns
         for pattern in self.regex_patterns.values() {
+            tracing::debug!("Processing regex pattern '{}'", pattern.rule_id);
             let pattern_matches = self.apply_regex_pattern(pattern, file_path, content)?;
+            tracing::debug!("Pattern '{}' found {} matches", pattern.rule_id, pattern_matches.len());
             matches.extend(pattern_matches);
         }
 
@@ -285,10 +294,15 @@ impl PatternEngine {
         file_path: &Path,
         content: &str,
     ) -> GuardianResult<Vec<PatternMatch>> {
+        tracing::debug!("Applying regex pattern '{}' to file '{}'", pattern.rule_id, file_path.display());
+        tracing::debug!("Pattern regex: '{}'", pattern.regex.as_str());
+        tracing::debug!("Content length: {} characters", content.len());
+        
         let mut matches = Vec::new();
 
         // Find all matches in the content
         for regex_match in pattern.regex.find_iter(content) {
+            tracing::debug!("Found regex match: '{}' at offset {}", regex_match.as_str(), regex_match.start());
             let matched_text = regex_match.as_str().to_string();
             let (line_num, col_num, context) =
                 self.get_match_location(content, regex_match.start());
@@ -301,6 +315,7 @@ impl PatternEngine {
                 content,
                 regex_match.start(),
             ) {
+                tracing::debug!("Match '{}' excluded by conditions", matched_text);
                 continue;
             }
 
@@ -1014,13 +1029,16 @@ impl PatternEngine {
         &self,
         conditions: Option<&ExcludeConditions>,
         file_path: &Path,
-        _matched_text: &str,
+        matched_text: &str,
         _content: &str,
         _offset: usize,
     ) -> bool {
         if let Some(conditions) = conditions {
+            tracing::debug!("Checking exclude conditions for match '{}' in file '{}'", matched_text, file_path.display());
+            
             // Check if in test files
             if conditions.in_tests && self.is_test_file(file_path) {
+                tracing::debug!("Match excluded: in_tests=true and file is test file");
                 return true;
             }
 
@@ -1029,13 +1047,17 @@ impl PatternEngine {
                 for pattern in patterns {
                     if let Ok(glob_pattern) = glob::Pattern::new(pattern) {
                         if glob_pattern.matches_path(file_path) {
+                            tracing::debug!("Match excluded: file matches pattern '{}'", pattern);
                             return true;
                         }
                     }
                 }
             }
 
             // Additional condition checks can be added here when AST context is available
+            tracing::debug!("Match not excluded by any conditions");
+        } else {
+            tracing::debug!("No exclude conditions to check");
         }
 
         false
@@ -1842,4 +1864,59 @@ mod tests {
             .unwrap();
         assert_eq!(matches.len(), 0);
     }
+
+    #[test]
+    fn test_custom_test_pattern_matching() {
+        let mut engine = PatternEngine::new();
+        
+        // Create the test pattern rule as it appears in config
+        let test_pattern_rule = PatternRule {
+            id: "no_traditional_tests".to_string(),
+            rule_type: crate::config::RuleType::Regex,
+            pattern: r"(^\s*mod\s+tests?\s*\{|#\[test\]|#\[cfg\(test\)\])".to_string(),
+            message: "Traditional tests violate CDD principles - use integration tests instead: {match}".to_string(),
+            severity: Some(crate::domain::violations::Severity::Error),
+            enabled: true,
+            case_sensitive: true,
+            exclude_if: Some(crate::config::ExcludeConditions {
+                attribute: None,
+                in_tests: false,
+                file_patterns: Some(vec![
+                    "**/integration_tests/**".to_string(),
+                    "**/tests/**".to_string()
+                ]),
+            }),
+        };
+
+        engine.add_rule(&test_pattern_rule, crate::domain::violations::Severity::Error).unwrap();
+
+        let test_content = r#"//! Test file
+pub fn some_function() -> String {
+    "Hello, World!".to_string()
+}
+
+#[test]
+fn test_some_function() {
+    assert_eq!(some_function(), "Hello, World!");
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn another_test() {
+        assert_eq!(some_function().len(), 13);
+    }
+}"#;
+
+        let matches = engine.analyze_file(Path::new("test_file.rs"), test_content).unwrap();
+        println!("Found {} matches in test content", matches.len());
+        for (i, m) in matches.iter().enumerate() {
+            println!("Match {}: {} at {}:{}", i, m.matched_text, m.line_number.unwrap_or(0), m.column_number.unwrap_or(0));
+        }
+        
+        // Should find at least the #[test] and #[cfg(test)] patterns
+        assert!(!matches.is_empty(), "Should find test patterns in content");
+    }
 }