Finalize import discovery documentation and audits

internal/engine/glob.go

@@ -31,6 +31,8 @@ func selectGlobImportCandidates(access *filesystemAccess, basePath string, spec
 	for index, segment := range segments {
 		last := index == len(segments)-1
 		literal, patterned := globLiteralSegment(segment)
+		// nextByPath is the set union of candidates reached from each matching
+		// parent at this segment; final exclusions below are set difference.
 		nextByPath := make(map[string]selectedImportCandidate)
 		for _, parent := range candidates {
 			if !patterned {

internal/engine/import_selection.go

@@ -97,6 +97,9 @@ func selectDirectoryImportCandidates(access *filesystemAccess, basePath string,
 	}
 	discovered := make([]selectedImportCandidate, 0)
 	seenCandidates := make(map[string]struct{})
+	// Each root is traversed once. Filename patterns are tested together for
+	// every discovered file, and seenCandidates forms their set union across
+	// overlapping roots. Exclusions are applied once below as set difference.
 	for _, root := range roots {
 		missing, isDirectory, diagnostic := validateNamedImportTarget(access, root, false, true)
 		if diagnostic != nil {
@@ -121,6 +124,8 @@ func selectDirectoryImportCandidates(access *filesystemAccess, basePath string,
 			continue
 		}
 		stack := []importDirectoryFrame{{directory: root, depth: 0, entries: entries, identity: rootTarget.identity}}
+		// Active-path cycle detection removes each directory when its frame is
+		// popped, so a later non-active alias remains a separate traversal.
 		activeDirectories := map[string]struct{}{rootTarget.identity: {}}
 		for len(stack) != 0 {
 			frameIndex := len(stack) - 1

internal/engine/source_version.go

@@ -59,15 +59,18 @@ func sourceInfosWithVersionEvidence(sources []SourceInfo, evidence []*sourceVers
 		return result
 	}
 	sensitivity := newDiffSensitivity(secrets, nil)
+	sourceIndexes := make(map[string]int, len(result))
+	for index := range result {
+		if _, found := sourceIndexes[result[index].ID]; !found {
+			sourceIndexes[result[index].ID] = index
+		}
+	}
 	for _, item := range evidence {
 		if item == nil || item.sourceID == "" {
 			continue
 		}
-		for index := range result {
-			if result[index].ID == item.sourceID {
-				result[index].VersionCheck = sourceVersionCheckForEvidence(item, sensitivity, conservative)
-				break
-			}
+		if index, found := sourceIndexes[item.sourceID]; found {
+			result[index].VersionCheck = sourceVersionCheckForEvidence(item, sensitivity, conservative)
 		}
 	}
 	return result