fix: Documenting index logic better

Author: yhakbar

internal/discovery/discovery_test.go

@@ -125,6 +125,7 @@ func TestCandidacyClassifier_ClassifyComponent(t *testing.T) {
 		filterStrings []string
 		expectStatus  filter.ClassificationStatus
 		expectReason  filter.CandidacyReason
+		expectIndex   int
 	}{
 		{
 			name:          "no filters - include by default",
@@ -133,6 +134,7 @@ func TestCandidacyClassifier_ClassifyComponent(t *testing.T) {
 			workingDir:    "/project",
 			expectStatus:  filter.StatusDiscovered,
 			expectReason:  filter.CandidacyReasonNone,
+			expectIndex:   -1,
 		},
 		{
 			name:          "matching path filter",
@@ -141,6 +143,7 @@ func TestCandidacyClassifier_ClassifyComponent(t *testing.T) {
 			workingDir:    "/project",
 			expectStatus:  filter.StatusDiscovered,
 			expectReason:  filter.CandidacyReasonNone,
+			expectIndex:   -1,
 		},
 		{
 			name:          "non-matching path filter - exclude by default",
@@ -149,6 +152,7 @@ func TestCandidacyClassifier_ClassifyComponent(t *testing.T) {
 			workingDir:    "/project",
 			expectStatus:  filter.StatusExcluded,
 			expectReason:  filter.CandidacyReasonNone,
+			expectIndex:   -1,
 		},
 		{
 			name:          "negated filter only - exclude component",
@@ -157,6 +161,7 @@ func TestCandidacyClassifier_ClassifyComponent(t *testing.T) {
 			workingDir:    "/project",
 			expectStatus:  filter.StatusExcluded,
 			expectReason:  filter.CandidacyReasonNone,
+			expectIndex:   -1,
 		},
 		{
 			name:          "negated filter only - include other",
@@ -165,6 +170,7 @@ func TestCandidacyClassifier_ClassifyComponent(t *testing.T) {
 			workingDir:    "/project",
 			expectStatus:  filter.StatusDiscovered,
 			expectReason:  filter.CandidacyReasonNone,
+			expectIndex:   -1,
 		},
 		{
 			name:          "graph expression target - candidate",
@@ -173,6 +179,7 @@ func TestCandidacyClassifier_ClassifyComponent(t *testing.T) {
 			workingDir:    "/project",
 			expectStatus:  filter.StatusCandidate,
 			expectReason:  filter.CandidacyReasonGraphTarget,
+			expectIndex:   0,
 		},
 		{
 			name:          "parse required filter - candidate",
@@ -181,6 +188,7 @@ func TestCandidacyClassifier_ClassifyComponent(t *testing.T) {
 			workingDir:    "/project",
 			expectStatus:  filter.StatusCandidate,
 			expectReason:  filter.CandidacyReasonRequiresParse,
+			expectIndex:   -1,
 		},
 	}
 
@@ -203,10 +211,11 @@ func TestCandidacyClassifier_ClassifyComponent(t *testing.T) {
 			})
 
 			ctx := filter.ClassificationContext{}
-			status, reason, _ := classifier.Classify(c, ctx)
+			status, reason, index := classifier.Classify(c, ctx)
 
 			assert.Equal(t, tt.expectStatus, status, "status mismatch")
 			assert.Equal(t, tt.expectReason, reason, "reason mismatch")
+			assert.Equal(t, tt.expectIndex, index, "index mismatch")
 		})
 	}
 }

internal/discovery/doc.go

@@ -12,9 +12,24 @@
 // This dual-channel approach enables lazy evaluation. Components are only parsed or
 // graph-traversed when necessary for filter evaluation.
 //
+// # Constructors
+//
+// The package provides several constructors for different use cases:
+//
+//   - [NewDiscovery]: Creates a Discovery with sensible defaults including CPU-aware worker
+//     count (scales with runtime.NumCPU, min 4, max 8) and pre-initialized [component.DiscoveryContext].
+//     This is the recommended constructor for most use cases.
+//
+//   - [NewForDiscoveryCommand]: Creates a Discovery configured for discovery commands (find/list)
+//     with parse error suppression and cycle breaking enabled.
+//
+//   - [NewForHCLCommand]: Creates a Discovery for HCL commands (validate/format).
+//
+//   - [NewForStackGenerate]: Creates a Discovery for stack generate commands.
+//
 // # Classification Rules
 //
-// The [CandidacyClassifier] analyzes all filter expressions upfront and classifies
+// The [filter.Classifier] analyzes all filter expressions upfront and classifies
 // each component into one of three statuses:
 //
 //   - [StatusDiscovered]: Matches a positive filter (path, attribute, or git expression)
@@ -29,7 +44,7 @@
 // The discovery process executes in the following phases:
 //
 //  1. Filesystem + Worktree Discovery (concurrent)
-//     - [PhaseFilesystem]: Walk directories recursively, classify components via [CandidacyClassifier]
+//     - [PhaseFilesystem]: Walk directories recursively, classify components via [filter.Classifier]
 //     - [PhaseWorktree]: For Git filters [ref...ref], discover components in temporary worktrees
 //     and detect added/removed/modified components via SHA256 comparison
 //
@@ -51,7 +66,7 @@
 //
 //  5. Final Phase
 //     - [PhaseFinal]: Merge all discovered, deduplicate by path, apply final filter evaluation
-//     - Cycle detection and removal if configured via WithBreakCycles
+//     - Cycle detection and removal if configured via [Discovery.WithBreakCycles]
 //
 // # Filter Expressions
 //
@@ -63,11 +78,34 @@
 //   - Git expressions: [main...develop] (changes between refs)
 //   - Negated expressions: !./internal (exclusion)
 //
+// # Configuration Methods
+//
+// Discovery uses a fluent builder pattern. Available configuration methods include:
+//
+//   - [Discovery.WithFilters]: Set filter queries for component selection
+//   - [Discovery.WithRelationships]: Enable relationship discovery for execution ordering
+//   - [Discovery.WithMaxDependencyDepth]: Set maximum dependency traversal depth (default 1000)
+//   - [Discovery.WithNumWorkers]: Set concurrent worker count (default 4, max 8)
+//   - [Discovery.WithBreakCycles]: Enable cycle detection and removal
+//   - [Discovery.WithNoHidden]: Exclude hidden directories from discovery
+//   - [Discovery.WithRequiresParse]: Force parsing of all Terragrunt configurations
+//   - [Discovery.WithSuppressParseErrors]: Continue discovery despite parse errors
+//   - [Discovery.WithParseExclude]: Parse exclude configurations
+//   - [Discovery.WithParseIncludes]: Parse include configurations
+//   - [Discovery.WithReadFiles]: Parse for file reading information
+//   - [Discovery.WithDiscoveryContext]: Set the discovery context
+//   - [Discovery.WithWorktrees]: Set worktrees for Git-based filters
+//   - [Discovery.WithConfigFilenames]: Set custom config filenames to discover
+//   - [Discovery.WithParserOptions]: Set custom HCL parser options
+//   - [Discovery.WithGitRoot]: Set git root for dependent discovery boundary
+//   - [Discovery.WithGraphTarget]: Set graph target for pruning results
+//   - [Discovery.WithReport]: Set report for recording excluded dependencies
+//   - [Discovery.WithOptions]: Ingest runner options for parser and graph settings
+//
 // # Example Usage
 //
-//	d := discovery.New(workingDir).
+//	d := NewDiscovery(workingDir).
 //		WithFilters(filters).
-//		WithDiscoveryContext(discoveryContext).
 //		WithRelationships().
 //		WithMaxDependencyDepth(10)
 //

internal/filter/classifier.go

@@ -193,15 +193,19 @@ func (c *Classifier) analyzeExpression(expr Expression, filterIndex int) {
 // Classify determines whether a component should be discovered, is a candidate,
 // or should be excluded based on the analyzed filters.
 //
+// Returns the classification status, the reason for candidacy (if applicable),
+// and the index of the matching graph expression (-1 if not a graph target match).
+//
 // Classification algorithm:
 //  1. Check if component ONLY matches negated filters -> EXCLUDED
-//  2. Check if component matches any positive filesystem filter -> DISCOVERED
-//  3. Check if component matches any graph expression target -> CANDIDATE (GraphTarget)
-//  4. Check if parse expressions exist and component not yet classified -> CANDIDATE (RequiresParse)
-//  5. Check if dependent filters exist (component might be a dependent) -> CANDIDATE (PotentialDependent)
-//  6. If negated expressions exist and component doesn't match any -> DISCOVERED (negation acts as inclusion)
-//  7. If positive filters exist but no match -> EXCLUDED (exclude-by-default)
-//  8. If no positive filters exist -> DISCOVERED (include-by-default)
+//  2. Check if parse expressions exist and parse data unavailable -> CANDIDATE (RequiresParse)
+//  3. Check if component matches any positive filesystem filter -> DISCOVERED
+//  4. Check if component matches any git expression -> DISCOVERED
+//  5. Check if component matches any graph expression target -> CANDIDATE (GraphTarget, returns index)
+//  6. Check if dependent filters exist and parse data unavailable -> CANDIDATE (PotentialDependent)
+//  7. If negated expressions exist and component doesn't match any -> DISCOVERED (negation acts as inclusion)
+//  8. If positive filters exist but no match -> EXCLUDED (exclude-by-default)
+//  9. If no positive filters exist -> DISCOVERED (include-by-default)
 func (c *Classifier) Classify(comp component.Component, ctx ClassificationContext) (ClassificationStatus, CandidacyReason, int) {
 	hasNegativeMatch := c.matchesAnyNegated(comp)
 	hasPositiveMatch := c.matchesAnyPositive(comp, ctx)