fix: address review feedback (concurrency, empty layers, helpers, docs)

Author: Chetnapadhi

docs/custom-scanners.md

@@ -17,7 +17,7 @@ type Scanner interface {
 | `Text` | `string` | Normalized text after decoding/normalization. |
 | `RawText` | `string` | Original text before normalization. |
 | `URL` | `string` | Source URL when available. |
-| `Mode` | `idpishield.Mode` | Current scan mode (`fast`, `balanced`, `deep`). |
+| `Mode` | `idpishield.Mode` | Current scan mode (`fast`, `balanced`, `deep`, `strict`). |
 | `IsOutputScan` | `bool` | True when called from `AssessOutput()`. |
 | `CurrentScore` | `int` | Score accumulated by built-ins before your scanner runs. |
 
@@ -31,6 +31,9 @@ type Scanner interface {
 | `PatternID` | `string` | Optional pattern ID for audit trails. |
 | `Metadata` | `map[string]string` | Optional metadata for debugging. |
 
+`ScanContext.Mode` controls analysis pipeline depth (including `strict` full-pipeline execution).
+This is different from `Config.StrictMode`, which only changes blocking thresholds.
+
 ## Writing Your First Scanner
 1. Define a scanner struct that implements `Name()` and `Scan()`.
 2. In `Scan()`, inspect `ctx.Text` using helper utilities.

idpishield.go

@@ -616,24 +616,26 @@ func (s *Shield) WithScanners(names ...string) *Shield {
 		return s
 	}
 
-	s.mu.Lock()
-	defer s.mu.Unlock()
+	s.mu.RLock()
+	baseCfg := s.baseCfg
+	registry := cloneScannerRegistry(s.scannerRegistry)
+	s.mu.RUnlock()
 
 	selected := make([]Scanner, 0, len(names))
 	for _, name := range names {
 		key := strings.ToLower(strings.TrimSpace(name))
 		if key == "" {
 			continue
 		}
-		scanner, ok := s.scannerRegistry[key]
+		scanner, ok := registry[key]
 		if !ok || scanner == nil {
 			continue
 		}
 		selected = append(selected, scanner)
 	}
 
-	baseExtras := append([]Scanner(nil), s.baseCfg.ExtraScanners...)
-	cfg := s.baseCfg
+	baseExtras := append([]Scanner(nil), baseCfg.ExtraScanners...)
+	cfg := baseCfg
 	cfg.ExtraScanners = mergeScannersByName(baseExtras, selected)
 
 	resolvedCfg, err := engine.ResolveConfig(toEngineCfg(cfg))
@@ -644,8 +646,11 @@ func (s *Shield) WithScanners(names ...string) *Shield {
 		return s
 	}
 
-	s.engine = engine.New(resolvedCfg)
-	return s
+	return &Shield{
+		engine:          engine.New(resolvedCfg),
+		baseCfg:         cfg,
+		scannerRegistry: registry,
+	}
 }
 
 // --- Functions ---
@@ -687,7 +692,11 @@ func Helpers() ScanHelpers { return ScanHelpers{} }
 func (h ScanHelpers) ContainsAny(text string, phrases []string) bool {
 	lower := strings.ToLower(text)
 	for _, phrase := range phrases {
-		if strings.Contains(lower, strings.ToLower(strings.TrimSpace(phrase))) {
+		trimmed := strings.ToLower(strings.TrimSpace(phrase))
+		if trimmed == "" {
+			continue
+		}
+		if strings.Contains(lower, trimmed) {
 			return true
 		}
 	}
@@ -808,6 +817,17 @@ func snapshotGlobalScannerRegistry() map[string]Scanner {
 	return out
 }
 
+func cloneScannerRegistry(in map[string]Scanner) map[string]Scanner {
+	if len(in) == 0 {
+		return map[string]Scanner{}
+	}
+	out := make(map[string]Scanner, len(in))
+	for k, v := range in {
+		out[k] = v
+	}
+	return out
+}
+
 func mergeScannersByName(base []Scanner, extras []Scanner) []Scanner {
 	out := make([]Scanner, 0, len(base)+len(extras))
 	seen := make(map[string]struct{}, len(base)+len(extras))
@@ -911,12 +931,12 @@ func (a *engineScannerAdapter) Scan(ctx engine.ExternalScanContext) engine.Exter
 	}
 
 	publicResult := a.scanner.Scan(publicCtx)
-	metadata := make(map[string]string, len(publicResult.Metadata))
-	for k, v := range publicResult.Metadata {
-		metadata[k] = v
-	}
-	if len(metadata) == 0 {
-		metadata = nil
+	var metadata map[string]string
+	if len(publicResult.Metadata) > 0 {
+		metadata = make(map[string]string, len(publicResult.Metadata))
+		for k, v := range publicResult.Metadata {
+			metadata[k] = v
+		}
 	}
 
 	return engine.ExternalScanResult{

internal/engine/engine.go

@@ -142,7 +142,10 @@ func (e *Engine) AssessContext(ctx context.Context, text, sourceURL string) Risk
 	result := buildResultWithSignalsWithDebiasAndBan(matches, analysisText, normSignals, e.banListCfg, e.cfg.DebiasTriggers != nil && *e.cfg.DebiasTriggers, e.cfg.StrictMode, e.cfg.BlockThreshold)
 
 	if len(e.customScanners) > 0 {
-		result.Layers = append(result.Layers, heuristicLayerResult(result))
+		heuristics := heuristicLayerResult(result)
+		if !isEmptyLayerResult(heuristics) {
+			result.Layers = append(result.Layers, heuristics)
+		}
 		fullPipeline := e.cfg.Mode == ModeStrict
 		customCtx := internalScanContext{
 			Text:         analysisText,

internal/engine/output_engine.go

@@ -80,14 +80,17 @@ func assessOutput(text, originalPrompt string, cfg Config, customScanners ...Lay
 
 	if len(customScanners) > 0 {
 		layers = make([]LayerResult, 0, 1+len(scannerLayerExecutionOrder))
-		layers = append(layers, LayerResult{
+		heuristics := LayerResult{
 			Layer:       ScannerLayerHeuristics,
 			Score:       score,
 			ScannersRun: 1,
 			Matched:     score > 0,
 			Categories:  append([]string(nil), categories...),
 			Patterns:    append([]string(nil), patterns...),
-		})
+		}
+		if !isEmptyLayerResult(heuristics) {
+			layers = append(layers, heuristics)
+		}
 
 		fullPipeline := cfg.Mode == ModeStrict
 		customCtx := internalScanContext{

shield_test.go

@@ -504,6 +504,32 @@ func TestGlobalRegisterScanner_AvailableToNewShield(t *testing.T) {
 	}
 }
 
+func TestWithScanners_ReturnsCloneWithoutMutatingOriginal(t *testing.T) {
+	shield := mustNewShield(t, Config{Mode: ModeBalanced})
+	shield.RegisterScanner(&apiKeywordScanner{
+		name:     "clone-only-risk",
+		trigger:  "clone-trigger",
+		score:    9,
+		category: "clone-only",
+		reason:   "clone scanner matched",
+	})
+
+	cloned := shield.WithScanners("clone-only-risk")
+	if cloned == shield {
+		t.Fatal("expected WithScanners to return a cloned shield instance")
+	}
+
+	original := shield.Assess("contains clone-trigger", "")
+	if containsString(original.Categories, "clone-only") {
+		t.Fatalf("original shield should not be mutated, got categories=%v", original.Categories)
+	}
+
+	updated := cloned.Assess("contains clone-trigger", "")
+	if !containsString(updated.Categories, "clone-only") {
+		t.Fatalf("cloned shield should include selected scanner, got categories=%v", updated.Categories)
+	}
+}
+
 func containsString(values []string, needle string) bool {
 	for _, value := range values {
 		if value == needle {