jsreach

type Analyzer struct {
	// Runner is the underlying esbuild driver. Defaults to
	// NewRunner(Logger) when nil.
	Runner Runner
	Logger *zap.Logger
	// CacheDir overrides the default per-project result cache
	// location. Empty means "use the OS user cache directory under
	// bomly/analyzers/jsreach".
	CacheDir string
	// CacheTTL overrides the default 24h cache lifetime. Zero means
	// use the default.
	CacheTTL time.Duration
	// DisableCache turns off the on-disk result cache entirely.
	// Useful in CI smoke runs where freshness matters more than
	// speed.
	DisableCache bool
}

type Runner interface {
	// Name returns a stable identifier (e.g. "library") used in
	// telemetry and Reason fields.
	Name() string
	// Version returns the underlying tool version. The result cache
	// folds it into its key so toolchain upgrades invalidate prior
	// entries automatically. Empty string is acceptable; the cache
	// treats it like any other distinct value.
	Version() string
	// Run walks projectDir and returns the bare-specifier import set
	// found across every entry-reachable source file. projectDir must
	// contain a package.json.
	Run(ctx context.Context, projectDir string) (RunnerResult, error)
}

type RunnerResult struct {
	// ImportedPackages is the set of bare specifiers (e.g. "react",
	// "@scope/pkg") imported anywhere in the project's reachable source
	// tree. Subpath imports ("@scope/pkg/util") are normalized to the
	// owning package name.
	ImportedPackages map[string]struct{}
	// EntryPoints is the list of files the runner started its walk
	// from (mostly for logging / debug output).
	EntryPoints []string
	// SourceFiles is the count of project source files the runner
	// visited (for telemetry).
	SourceFiles int
	// DynamicImportsDetected is true when the runner observed
	// dynamic-import constructs in app source it cannot follow
	// statically (e.g. `require(variable)`, `import(variable)`,
	// `await import(name)`). When true, the analyzer's "unreachable"
	// verdicts are necessarily incomplete and the per-vuln
	// Reachability.DynamicImportsDetected flag is set.
	DynamicImportsDetected bool
}