refactor: decompose mapping.go's three highest-complexity functions

.uf/dewey/learnings/crapload-decompose-pr2b-20260716T100551-yvonne-devlin.md

@@ -0,0 +1,10 @@
+---
+tag: crapload-decompose-pr2b
+author: yvonne-devlin
+category: pattern
+created_at: 2026-07-16T10:05:51Z
+identity: crapload-decompose-pr2b-20260716T100551-yvonne-devlin
+tier: draft
+---
+
+When decomposing complex AST-walking functions in Go (like matchContainerUnwrap at complexity 50), the key insight is identifying the phases: setup (collect initial state), process (iterate and transform), and match (check result). Each phase can be extracted as a separate function. However, the process phase often retains high complexity even after extraction because nested ast.Inspect closures, multi-iteration convergence loops, and transformation call detection involve inherent branching. traceForwardDataFlow landed at complexity 32 despite the design estimating ~12. The parent function (matchContainerUnwrap) still dropped from 50 to 8 because the complexity was moved, not eliminated. For future decomposition work on AST-heavy functions, expect the extracted "core loop" to retain ~60-70% of the original complexity — the wins come from isolating concerns, not from reducing total branch count.

.uf/dewey/learnings/crapload-decompose-pr2b-20260716T100559-yvonne-devlin.md

@@ -0,0 +1,10 @@
+---
+tag: crapload-decompose-pr2b
+author: yvonne-devlin
+category: pattern
+created_at: 2026-07-16T10:05:59Z
+identity: crapload-decompose-pr2b-20260716T100559-yvonne-devlin
+tier: draft
+---
+
+The parseAndTypeCheck test helper pattern in internal/quality/container_unwrap_internal_test.go is highly effective for testing Go AST manipulation functions. It takes a Go source string, parses it, and type-checks it with Importer:nil (intentionally ignoring import resolution errors). This enables testing functions that operate on types.Object, types.Info, and ast.File without loading real packages. For functions that also need *packages.Package (like traceForwardDataFlow which needs Syntax for file iteration), construct a minimal struct: packages.Package{Syntax: []*ast.File{file}, TypesInfo: info, Fset: fset}. The parseAndTypeCheckWithFset variant was added in Phase 2b to return the fset needed for this pattern. One gotcha: for isByteLikeParam and isPointerDestParam tests, it's simpler to construct types.Type values directly using the go/types constructors (types.NewSlice, types.NewPointer, types.NewInterfaceType) rather than parsing Go source — the classifiers only need type metadata, not full AST context.

AGENTS.md

@@ -484,6 +484,7 @@ Formatters: gofmt, goimports.
 
 ## Recent Changes
 
+- crapload-decompose-pr2b: Decomposed three highest-complexity functions in `internal/quality/mapping.go`: `matchContainerUnwrap` (50→8), `isTransformationCall` (26→5), `matchAssertionToEffect` (25→5). Extracted 7+ helpers: `isByteLikeParam`, `isPointerDestParam`, `resolveCallSignature`, `findParamIndex` (from isTransformationCall); `matchDirect`, `matchIndirectRoot` (from matchAssertionToEffect); `collectTrackedVars`, `traceForwardDataFlow`, `matchTrackedInExpr` (from matchContainerUnwrap). Added 25 new unit tests using synthetic AST via `parseAndTypeCheck`. Filled 3 test gaps in `isTransformationCall` (io.Reader, empty interface, mixed ordering). `TestSC003_MappingAccuracy` ratchet (85.0%) passes unchanged. Phase 2b of issue #166.
 - extract-violation-helper: Extracted `isNewFunctionViolation` helper in `internal/crap/compare.go` to centralize the new-function violation check (CRAP threshold OR GazeCRAP threshold exceeded) that was duplicated at three sites: `buildComparisonSummary` (counting), `WriteComparisonJSON` (JSON status), and `writeComparisonNewFunctions` (text output). All three call sites now use the helper. Added `TestIsNewFunctionViolation` table-driven test with 6 cases covering the full truth table. No behavioral change — pure DRY extraction. Closes #179.
 - universal-taxonomy: Generalized the side effect taxonomy for multi-language support (Issue #96). Added 10 new universal `SideEffectType` constants for language-neutral effects: `ErrorSignal` (P0), `GeneratorYield`, `ContainerMutation`, `StreamOutput` (P1), `AsyncGeneratorYield`, `MetaprogrammingMutation`, `DescriptorEffect`, `ResourceManagement`, `ImportSideEffect`, `MonkeyPatch` (P2). Added 11 language-neutral aliases for Go-specific types (e.g., `AsyncTaskSpawn = GoroutineSpawn`, `FFICall = CgoCall`). Added `Detail map[string]any` field to `taxonomy.SideEffect` for opaque language-specific metadata passthrough from external analyzers. Added `ValidTypes` set and `IsKnownType` function to `internal/taxonomy/types.go` for programmatic type validation (replaces hardcoded `isKnownP4` switch in adapter). Added `Detail` field to `protocol.AnalyzedSideEffect` and wired passthrough in adapter's `convertAnalysisResults`. Updated JSON Schema enum with all new types and `detail` property. Updated `docs/protocol.md` with comprehensive 48-type reference table, bumped protocol version to 1.1.0. Updated `docs/porting/` guides with expanded type counts and tier tables. Total canonical types: 48 (38 existing + 10 new).
 - analyze-multi-package: Added multi-package support to `gaze analyze` and `gaze quality`. Both commands now accept multiple package patterns including `./...` wildcards. Changed Cobra constraints from `ExactArgs(1)` to `MinimumNArgs(1)`, added `loader.ResolvePackagePaths` and `loader.IsMainPkg` as exported utilities in `internal/loader/loader.go`, consolidated 3 duplicate copies each of `resolvePackagePaths`/`resolvePatterns` and `isMainPkg`/`isMainPackage` from `internal/crap/contract.go`, `internal/aireport/runner_steps.go`, and `cmd/gaze/main.go`. Updated `runAnalyze` and `runQuality` to resolve patterns then iterate per package. Added defense-in-depth warning to `loader.Load` when `len(pkgs) > 1`. Updated `runClassify` to accept pre-loaded module packages (avoids repeated `LoadModule` calls). Added `mergeSummaries` for quality report aggregation. Removed "Single package loading" known limitation from README. Closes #107.