Add the ability to filter by key product areas or Drivers

Author: dacharyc

AGENTS.md

@@ -46,7 +46,8 @@ audit-cli/
 │   ├── config/               # Configuration management
 │   │   ├── config.go         # Config loading from file/env/args
 │   │   ├── config_test.go    # Config tests
-│   │   └── url_mapping.go    # URL-to-source-file mapping via Snooty Data API
+│   │   ├── url_mapping.go    # URL-to-source-file mapping via Snooty Data API
+│   │   └── url_mapping_test.go # URL mapping tests
 │   ├── language/             # Programming language utilities
 │   │   ├── language.go       # Language normalization, extensions, products
 │   │   └── language_test.go  # Language tests

README.md

@@ -1565,6 +1565,35 @@ rank,url
 - `--format, -f <format>` - Output format: `text` (default), `json`, or `csv`
 - `--output, -o <file>` - Output file path (default: stdout)
 - `--details` - Show detailed per-product breakdown (for CSV output, includes per-product columns)
+- `--filter <filter>` - Filter pages by product area (can be specified multiple times)
+- `--list-drivers` - List all available driver filter options from the Snooty Data API
+
+**Filtering:**
+
+Use the `--filter` flag to focus on specific product areas. Multiple filters can be specified to include pages matching any filter.
+
+Available filters:
+- `search` - Pages with "atlas-search" or "search" in URL (excludes vector-search)
+- `vector-search` - Pages with "vector-search" in URL
+- `drivers` - All MongoDB driver documentation pages
+- `driver:<name>` - Specific driver by project name (e.g., `driver:pymongo`, `driver:node`)
+- `mongosh` - MongoDB Shell documentation pages
+
+```bash
+# Filter to only Atlas Search pages
+./audit-cli report testable-code analytics.csv --filter search
+
+# Filter to only PyMongo driver pages
+./audit-cli report testable-code analytics.csv --filter driver:pymongo
+
+# Filter to multiple areas (pages matching any filter are included)
+./audit-cli report testable-code analytics.csv --filter drivers --filter mongosh
+
+# List all available driver filter options
+./audit-cli report testable-code --list-drivers
+```
+
+The `--list-drivers` flag queries the Snooty Data API to show all available driver project names that can be used with the `driver:<name>` filter. Results are cached for 24 hours.
 
 **Testable Products:**
 

commands/report/testable-code/testable_code.go

@@ -38,6 +38,8 @@ package testablecode
 import (
 	"fmt"
 	"os"
+	"sort"
+	"strings"
 
 	"github.com/grove-platform/audit-cli/internal/config"
 	"github.com/spf13/cobra"
@@ -48,6 +50,8 @@ func NewTestableCodeCommand() *cobra.Command {
 	var outputFormat string
 	var showDetails bool
 	var outputFile string
+	var filters []string
+	var listDrivers bool
 
 	cmd := &cobra.Command{
 		Use:   "testable-code <csv-file> [monorepo-path]",
@@ -74,12 +78,35 @@ Example CSV format:
 Testable products (have test infrastructure):
   - C#, Go, Java (Sync), Node.js, Python, MongoDB Shell
 
+Filters (use --filter to focus on specific product areas):
+  - search: Pages with "atlas-search" or "search" in URL (excludes vector-search)
+  - vector-search: Pages with "vector-search" in URL
+  - drivers: All MongoDB driver documentation pages
+  - driver:<name>: Specific driver. Testable values include:
+      csharp, golang, java, node, pymongo
+    For the full list of options, use the --list-drivers flag.
+  - mongosh: MongoDB Shell documentation pages
+
+Multiple filters can be specified to include pages matching any filter.
+
+Use --list-drivers to see available Driver filter options
+
 Output formats:
   - text: Human-readable report with summary and detailed sections
   - json: Machine-readable JSON output
   - csv: Comma-separated values (summary by default, use --details for per-product breakdown)`,
-		Args: cobra.RangeArgs(1, 2),
+		Args: cobra.RangeArgs(0, 2),
 		RunE: func(cmd *cobra.Command, args []string) error {
+			// Handle --list-drivers flag
+			if listDrivers {
+				return runListDrivers()
+			}
+
+			// Require CSV file if not listing drivers
+			if len(args) < 1 {
+				return fmt.Errorf("requires at least 1 arg(s), only received 0")
+			}
+
 			csvPath := args[0]
 
 			// Get monorepo path
@@ -92,19 +119,76 @@ Output formats:
 				return err
 			}
 
-			return runTestableCode(csvPath, monorepoPath, outputFormat, showDetails, outputFile)
+			return runTestableCode(csvPath, monorepoPath, outputFormat, showDetails, outputFile, filters)
 		},
 	}
 
 	cmd.Flags().StringVarP(&outputFormat, "format", "f", "text", "Output format: text, json, or csv")
 	cmd.Flags().BoolVar(&showDetails, "details", false, "Show detailed per-product breakdown (for csv: one row per product per page)")
 	cmd.Flags().StringVarP(&outputFile, "output", "o", "", "Output file path (default: stdout)")
+	cmd.Flags().StringSliceVar(&filters, "filter", nil, "Filter pages by product area (search, vector-search, drivers, driver:<name>, mongosh)")
+	cmd.Flags().BoolVar(&listDrivers, "list-drivers", false, "List all drivers from the Snooty Data API")
 
 	return cmd
 }
 
+// runListDrivers lists all drivers from the Snooty Data API.
+func runListDrivers() error {
+	// Use the version that doesn't require a monorepo path
+	urlMapping, err := config.GetURLMappingWithoutMonorepo()
+	if err != nil {
+		return fmt.Errorf("failed to get URL mapping: %w", err)
+	}
+
+	driverSlugs := urlMapping.GetDriverSlugs()
+	if len(driverSlugs) == 0 {
+		fmt.Println("No drivers found in the Snooty Data API.")
+		return nil
+	}
+
+	// Build a list of driver info and sort by project name (the filter value)
+	type driverInfo struct {
+		projectName string
+		slug        string
+		hasTestInfra bool
+	}
+	drivers := make([]driverInfo, 0, len(driverSlugs))
+	for _, slug := range driverSlugs {
+		projectName := urlMapping.URLSlugToProject[slug]
+		drivers = append(drivers, driverInfo{
+			projectName:  projectName,
+			slug:         slug,
+			hasTestInfra: TestableDrivers[projectName],
+		})
+	}
+	// Sort alphabetically by project name
+	sort.Slice(drivers, func(i, j int) bool {
+		return drivers[i].projectName < drivers[j].projectName
+	})
+
+	fmt.Println("Available driver filters:")
+	fmt.Println("=========================")
+	fmt.Println()
+	fmt.Println("Use --filter driver:<name> with any of these values:")
+	fmt.Println()
+	for _, d := range drivers {
+		testableMarker := ""
+		if d.hasTestInfra {
+			testableMarker = " (has test infrastructure)"
+		}
+		fmt.Printf("  --filter driver:%-20s  (URL slug: %s)%s\n", d.projectName, d.slug, testableMarker)
+	}
+	fmt.Println()
+	fmt.Println("Drivers with test infrastructure:")
+	fmt.Printf("  %s\n", strings.Join(getTestableDriverNames(), ", "))
+	fmt.Println()
+	fmt.Println("Note: mongodb-shell is not a driver. Use --filter mongosh instead.")
+
+	return nil
+}
+
 // runTestableCode is the main entry point for the testable-code command.
-func runTestableCode(csvPath, monorepoPath, outputFormat string, showDetails bool, outputFile string) error {
+func runTestableCode(csvPath, monorepoPath, outputFormat string, showDetails bool, outputFile string, filters []string) error {
 	// Parse CSV file
 	entries, err := ParseCSV(csvPath)
 	if err != nil {
@@ -113,19 +197,34 @@ func runTestableCode(csvPath, monorepoPath, outputFormat string, showDetails boo
 
 	fmt.Fprintf(os.Stderr, "Parsed %d pages from CSV\n", len(entries))
 
+	// Get URL mapping early - needed for driver filters
+	urlMapping, err := config.GetURLMapping(monorepoPath)
+	if err != nil {
+		return fmt.Errorf("failed to get URL mapping: %w", err)
+	}
+
+	// Validate filters before applying
+	if err := validateFilters(filters); err != nil {
+		return err
+	}
+
+	// Apply URL filters if specified
+	if len(filters) > 0 {
+		originalCount := len(entries)
+		entries = filterEntries(entries, filters, urlMapping)
+		fmt.Fprintf(os.Stderr, "Filtered to %d pages matching filter(s): %v\n", len(entries), filters)
+		if len(entries) == 0 {
+			fmt.Fprintf(os.Stderr, "Warning: No pages matched the specified filter(s). Original count: %d\n", originalCount)
+		}
+	}
+
 	// Load product mappings from rstspec.toml
 	fmt.Fprintf(os.Stderr, "Loading product mappings from rstspec.toml...\n")
 	mappings, err := LoadProductMappings()
 	if err != nil {
 		return fmt.Errorf("failed to load product mappings: %w", err)
 	}
 
-	// Get URL mapping
-	urlMapping, err := config.GetURLMapping(monorepoPath)
-	if err != nil {
-		return fmt.Errorf("failed to get URL mapping: %w", err)
-	}
-
 	// Analyze each page
 	var reports []PageReport
 	for i, entry := range entries {
@@ -172,3 +271,100 @@ func runTestableCode(csvPath, monorepoPath, outputFormat string, showDetails boo
 	}
 }
 
+// filterEntries filters page entries based on the specified filters.
+// Returns entries that match any of the specified filters.
+func filterEntries(entries []PageEntry, filters []string, urlMapping *config.URLMapping) []PageEntry {
+	var filtered []PageEntry
+	for _, entry := range entries {
+		if matchesAnyFilter(entry.URL, filters, urlMapping) {
+			filtered = append(filtered, entry)
+		}
+	}
+	return filtered
+}
+
+// matchesAnyFilter checks if a URL matches any of the specified filters.
+func matchesAnyFilter(url string, filters []string, urlMapping *config.URLMapping) bool {
+	for _, filter := range filters {
+		if matchesFilter(url, filter, urlMapping) {
+			return true
+		}
+	}
+	return false
+}
+
+// validateFilters validates that all specified filters are valid.
+// Returns an error if any filter is invalid.
+func validateFilters(filters []string) error {
+	for _, filter := range filters {
+		filterLower := strings.ToLower(filter)
+
+		// Check for driver:<name> pattern - any driver name is valid
+		if strings.HasPrefix(filterLower, "driver:") {
+			driverName := strings.TrimPrefix(filterLower, "driver:")
+			// mongodb-shell should use mongosh filter since it's not a driver
+			if driverName == "mongodb-shell" {
+				return fmt.Errorf("invalid filter %q: mongodb-shell is not a driver, use --filter mongosh instead", filter)
+			}
+			// Any other driver name is valid - will just return no results if not found
+			continue
+		}
+
+		// Check known filters
+		switch filterLower {
+		case "search", "vector-search", "drivers", "mongosh":
+			// Valid filters
+		default:
+			return fmt.Errorf("unknown filter %q.\nValid filters: search, vector-search, drivers, driver:<name>, mongosh\nUse --list-drivers to see available driver names", filter)
+		}
+	}
+	return nil
+}
+
+// getTestableDriverNames returns a sorted list of driver names with test infrastructure.
+func getTestableDriverNames() []string {
+	var names []string
+	for name := range TestableDrivers {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
+
+// matchesFilter checks if a URL matches a specific filter.
+// Matching is case-insensitive.
+//
+// Supported filters:
+//   - "search": matches URLs containing "atlas-search" or "search" but NOT "vector-search"
+//   - "vector-search": matches URLs containing "vector-search"
+//   - "drivers": matches all driver documentation URLs (excludes mongodb-shell)
+//   - "driver:<name>": matches a specific driver by project name (e.g., driver:pymongo)
+//   - "mongosh": matches MongoDB Shell documentation URLs
+func matchesFilter(url string, filter string, urlMapping *config.URLMapping) bool {
+	urlLower := strings.ToLower(url)
+	filterLower := strings.ToLower(filter)
+
+	// Check for driver:<name> pattern
+	if strings.HasPrefix(filterLower, "driver:") {
+		driverName := strings.TrimPrefix(filterLower, "driver:")
+		return urlMapping.IsSpecificDriverURL(url, driverName)
+	}
+
+	switch filterLower {
+	case "search":
+		// Match "atlas-search" or "search" but exclude "vector-search"
+		if strings.Contains(urlLower, "vector-search") {
+			return false
+		}
+		return strings.Contains(urlLower, "atlas-search") || strings.Contains(urlLower, "search")
+	case "vector-search":
+		return strings.Contains(urlLower, "vector-search")
+	case "drivers":
+		return urlMapping.IsDriverURL(url)
+	case "mongosh":
+		return urlMapping.IsMongoshURL(url)
+	default:
+		// This shouldn't happen if validateFilters was called first
+		return false
+	}
+}