How podhmo/go-scan works
Project Type and Purpose
• This is an open-source, monorepo Go library/CLI tool (“go-scan”) for fast, shallow static analysis of Go code.
• It provides a core Scanner API plus supporting packages (AST walker, import resolution, caching), and ships with two advanced sub-libraries (minigo: mini-interpreter; symgo: symbolic evaluator).
• It’s consumed by other tools (e.g., code generators, API docs), and includes a CLI entrypoint, a testing harness, and many example commands.
High-Level Architecture / Main Components
A. Presentation Layer
• CLI / “main.go”
• Examples / “examples/…” (demonstrate usage)
• Docs / “docs/…” (human documentation)
B. Core Library Layer
• goscan.Scanner
– Scanner configuration & API (“WithGoModuleResolver”, “Scan”)
• astwalk
– Shallow AST traversal on go/ast
• scanner
– Tokenizes packages, builds shallow TypeInfo, FunctionInfo, ConstInfo
• importmanager, locator, modulewalker
– Resolve imports, go.mod, go.work, module cache, GOROOT
• cache
– Symbol location caching
• scantest
– Testing helpers and golden-file framework
C. Advanced Sub-Libraries (Consumers of Core)
• minigo
– Mini-Go interpreter (uses goscan to load definitions)
– ffibridge for Go-native interop
– Built-in stdlib package stubs
• symgo
– Symbolic execution engine
– Evaluator, intrinsics, object model
D. Infrastructure Layer
• File system (source files)
• Go toolchain (go/ast, go/parser)
• Module cache / go.mod / go.work
• Persistence (JSON cache file)
Relationships and Data Flow
• CLI (main.go) → configures → goscan.Scanner
• Scanner
1. reads file paths / import paths
2. uses locator/modulewalker to find source
3. parses Go AST
4. walks AST (astwalk) to extract types, funcs, consts
5. on-demand resolves cross-package references via importmanager
6. optionally reads/writes cache
7. returns shallow package models to caller
• minigo, symgo
• Depend on Scanner (import “github.com/podhmo/go-scan”)
• Call Scanner.Scan to obtain type definitions
• Execute or symbolically evaluate code based on those definitions
• scantest
• Wraps Scanner.Scan in test harness
• Compares output to “.golden” files
Architectural Patterns & Principles
• Layered design: Presentation → Core API → Utility packages → Infrastructure
• Lazy loading / on-demand resolution (minimizes work)
• Shallow scanning: avoids heavy type-checking, uses go/ast only
• Extensibility: ExternalTypeOverrides, plug-in sub-libraries (minigo, symgo)
• Testable: scantest golden tests, unit tests per package