refactor: merge v2 modular architecture into internal package (#17)

* refactor: merge v2 modular architecture into internal package

This refactoring applies the successful pattern from gormreuse/zerologlintctx:
create v2 with ideal architecture, then merge v2→v1.

Key changes:
- Add internal/check: check context module for checker implementations
- Add internal/checker.go: unified checker interfaces (GoStmtChecker, CallChecker)
- Add internal/checkers: individual checker implementations
  - goroutine.go: go statement checker
  - callarg.go: errgroup/waitgroup/conc/spawner checkers
  - gotask.go: gotask library checker
- Add internal/scope: context scope detection
- Reorganize directives:
  - internal/directives/* → internal/directive/* (singular)
  - Simplified carrier, ignore, spawner modules
- Merge internal/deriver: deriver matcher with OR/AND semantics
- Simplify internal/runner.go: use new checker interfaces
- Consolidate internal/ssa: merge builder and tracer

Package structure after merge:
- internal/check/       - check context for patterns
- internal/checkers/    - individual checker implementations
- internal/deriver/     - derive function matcher
- internal/directive/   - ignore, spawner, carrier directives
- internal/funcspec/    - function specification parsing
- internal/scope/       - context scope detection
- internal/ssa/         - SSA program and tracer

Removed:
- internal/directives/  - replaced by internal/directive
- internal/ssa/helpers.go - merged into tracer.go

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: consolidate duplicate functions and remove dead code

- Remove dead code packages: internal/context, internal/patterns
- Simplify internal/registry (remove unused Patterns field)
- Simplify internal/apis.go (remove patterns-related code)
- Rename internal/check to internal/probe for clarity
- Move internal/spawnerlabel to internal/checkers/spawnerlabel
- Consolidate duplicate isContextOrCarrierType functions:
  - Add carrier.IsCarrierType() as the canonical implementation
  - Remove duplicates from probe, scope, and ssa packages
- Clean up internal/typeutil (remove 5 unused exported functions)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: add comprehensive package documentation

- Add doc.go files to all internal packages with:
  - ASCII architecture diagrams
  - Code examples
  - API documentation
- Fix redundant import aliases (internal "...")
- Exclude doc.go files from gci formatter in golangci-lint

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: remove unused functions to improve coverage

Remove dead code functions that are never called:
- probe.Context.Report, FuncOf
- probe.Context.FuncLitOfIdentBefore
- scope.Scope.CtxName
- ssa.Program.EnclosingFunc, findEnclosingFunc
- spawner.FindFuncArgs

Coverage improved from 84.1% to 85.8%

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor(ignore): remove unused AllCheckerNames function

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* refactor(ignore): remove unused Entry getter methods

Entry fields are only accessed internally within the package.
External code uses high-level APIs (ShouldIgnore, GetUnusedIgnores).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* refactor(callarg): remove unused variadic support code

- Remove Variadic field from CallArgEntry (never set to true)
- Remove checkVariadic, formatOrdinals functions (dead code)
- Move ordinal function to gotask.go (only user)

Coverage improved: 86.1% → 87.7%

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* test: improve coverage for gotask and spawner checkers

Coverage improvements:
- carrier.matchPkg: 28.6% → 100%
- gotask.callbackCallsDeriver: 50.0% → 83.3%
- callarg.checkFuncArg: 58.3% → 75.0%
- gotask.identIsDeriverCall: 60.0% → 100%

Bug fix:
- Add *ast.ParenExpr case to findConstructorCall to handle (*taskPtr).DoAsync()

New test cases:
- carrier_test.go: unit tests for matchPkg and Parse functions
- gotask/advanced.go: callback variable patterns, derived context variable tests
- gotask/evil.go: pointer dereference limitation documentation
- spawner/spawner.go: factory function patterns

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: mpyw

.golangci.yaml

@@ -34,3 +34,6 @@ formatters:
         - default
         - prefix(github.com/mpyw/goroutinectx)
       custom-order: true
+  exclusions:
+    paths:
+      - "doc\\.go$"

analyzer.go

@@ -13,13 +13,14 @@ import (
 	"golang.org/x/tools/go/ast/inspector"
 
 	"github.com/mpyw/goroutinectx/internal"
-	"github.com/mpyw/goroutinectx/internal/directives/carrier"
-	"github.com/mpyw/goroutinectx/internal/directives/deriver"
-	"github.com/mpyw/goroutinectx/internal/directives/ignore"
-	"github.com/mpyw/goroutinectx/internal/directives/spawner"
+	"github.com/mpyw/goroutinectx/internal/checkers"
+	"github.com/mpyw/goroutinectx/internal/checkers/spawnerlabel"
+	"github.com/mpyw/goroutinectx/internal/deriver"
+	"github.com/mpyw/goroutinectx/internal/directive/carrier"
+	"github.com/mpyw/goroutinectx/internal/directive/ignore"
+	"github.com/mpyw/goroutinectx/internal/directive/spawner"
 	"github.com/mpyw/goroutinectx/internal/registry"
-	"github.com/mpyw/goroutinectx/internal/spawnerlabel"
-	internalssa "github.com/mpyw/goroutinectx/internal/ssa"
+	"github.com/mpyw/goroutinectx/internal/ssa"
 )
 
 // Flags for the analyzer.
@@ -60,7 +61,7 @@ func init() {
 var Analyzer = &analysis.Analyzer{
 	Name:     "goroutinectx",
 	Doc:      "checks that context.Context is properly propagated to downstream calls",
-	Requires: []*analysis.Analyzer{inspect.Analyzer, internalssa.BuildSSAAnalyzer},
+	Requires: []*analysis.Analyzer{inspect.Analyzer, ssa.BuildSSAAnalyzer},
 	Run:      run,
 	Flags:    flag.FlagSet{},
 }
@@ -88,22 +89,22 @@ func run(pass *analysis.Pass) (any, error) {
 	// Build enabled checkers map
 	enabled := buildEnabledCheckers(spawners)
 
-	// Build registry
-	reg := buildRegistry()
-
 	// Build SSA program
-	ssaProg := internalssa.Build(pass)
+	ssaProg := ssa.Build(pass)
 
-	// Spawner map (nil if disabled)
-	var spawnerMap *spawner.Map
-	if enableSpawner {
-		spawnerMap = spawners
+	// Build derivers matcher
+	var derivers *deriver.Matcher
+	if goroutineDeriver != "" {
+		derivers = deriver.NewMatcher(goroutineDeriver)
 	}
 
-	// Create and run unified checker
+	// Build checkers
+	goStmtCheckers, callCheckers := buildCheckers(derivers, spawners)
+
+	// Create and run runner
 	runner := internal.NewRunner(
-		reg,
-		spawnerMap,
+		goStmtCheckers,
+		callCheckers,
 		ssaProg,
 		carriers,
 		ignoreMaps,
@@ -113,6 +114,14 @@ func run(pass *analysis.Pass) (any, error) {
 
 	// Run spawnerlabel checker if enabled
 	if enableSpawnerlabel {
+		reg := registry.New()
+
+		// Register APIs for spawnerlabel detection
+		internal.RegisterErrgroupAPIs(reg)
+		internal.RegisterWaitgroupAPIs(reg)
+		internal.RegisterConcAPIs(reg)
+		internal.RegisterGotaskAPIs(reg)
+
 		spawnerlabelChecker := spawnerlabel.New(spawners, reg, ssaProg)
 		spawnerlabelChecker.Check(pass, ignoreMaps, skipFiles)
 	}
@@ -124,15 +133,12 @@ func run(pass *analysis.Pass) (any, error) {
 }
 
 // buildSkipFiles creates a set of filenames to skip.
-// Generated files are always skipped.
-// Test files can be skipped via the driver's built-in -test flag.
 func buildSkipFiles(pass *analysis.Pass) map[string]bool {
 	skipFiles := make(map[string]bool)
 
 	for _, file := range pass.Files {
 		filename := pass.Fset.Position(file.Pos()).Filename
 
-		// Always skip generated files
 		if ast.IsGenerated(file) {
 			skipFiles[filename] = true
 		}
@@ -156,34 +162,44 @@ func buildIgnoreMaps(pass *analysis.Pass, skipFiles map[string]bool) map[string]
 	return ignoreMaps
 }
 
-// buildRegistry creates and populates the API registry.
-func buildRegistry() *registry.Registry {
-	reg := registry.New()
+// buildCheckers creates the checker instances.
+func buildCheckers(derivers *deriver.Matcher, spawners *spawner.Map) ([]internal.GoStmtChecker, []internal.CallChecker) {
+	var goStmtCheckers []internal.GoStmtChecker
+	var callCheckers []internal.CallChecker
 
-	// Create derivers matcher once if configured
-	var derivers *deriver.Matcher
-	if goroutineDeriver != "" {
-		derivers = deriver.NewMatcher(goroutineDeriver)
+	// Goroutine checkers
+	if enableGoroutine {
+		goStmtCheckers = append(goStmtCheckers, &checkers.Goroutine{Derivers: derivers})
 	}
 
-	// Register patterns (pass derivers for deriver checking)
-	if enableGoroutine {
-		internal.RegisterGoroutinePatterns(reg, derivers)
+	if derivers != nil {
+		goStmtCheckers = append(goStmtCheckers, &checkers.GoroutineDerive{Derivers: derivers})
 	}
+
+	// Call checkers
 	if enableErrgroup {
-		internal.RegisterErrgroupAPIs(reg, derivers)
+		callCheckers = append(callCheckers, checkers.NewErrgroupChecker(derivers))
 	}
+
 	if enableWaitgroup {
-		internal.RegisterWaitgroupAPIs(reg, derivers)
+		callCheckers = append(callCheckers, checkers.NewWaitgroupChecker(derivers))
 	}
+
 	if enableConc {
-		internal.RegisterConcAPIs(reg, derivers)
+		callCheckers = append(callCheckers, checkers.NewConcChecker(derivers))
 	}
-	if enableGotask {
-		internal.RegisterGotaskAPIs(reg, derivers)
+
+	if enableSpawner && spawners.Len() > 0 {
+		callCheckers = append(callCheckers, checkers.NewSpawnerChecker(spawners, derivers))
+	}
+
+	if enableGotask && derivers != nil {
+		if gotaskChecker := checkers.NewGotaskChecker(derivers); gotaskChecker != nil {
+			callCheckers = append(callCheckers, gotaskChecker)
+		}
 	}
 
-	return reg
+	return goStmtCheckers, callCheckers
 }
 
 // buildEnabledCheckers creates a map of which checkers are enabled.