proc

Documentation

Overview

Package proc centralizes the timeouts for the external toolchain processes the frontends shell out to (python3, java, rustc, cargo, clang, mvn/gradle). A wedged or hung toolchain must never hang a CI scan indefinitely — the scan has to make progress or fail, not block a pipeline forever. Every subprocess is therefore run under a context deadline; on timeout the process is killed and the frontend surfaces the error (a failed conversion / coverage failure), exactly like any other toolchain error.

Index

• func BuildContext() (context.Context, context.CancelFunc)
• func BuildTimeout() time.Duration
• func FileExists(p string) bool
• func ParseContext() (context.Context, context.CancelFunc)
• func ParseTimeout() time.Duration
• func RunBatchScript(label, scriptName, exe, scriptPath string, files []string, ...)
• func SetTimeouts(parse, build time.Duration)
• func WriteEmbeddedScript(pattern string, content []byte) (string, func(), error)

Functions

func BuildContext

func BuildContext() (context.Context, context.CancelFunc)

BuildContext returns a context with the build timeout and its cancel func.

func BuildTimeout

func BuildTimeout() time.Duration

BuildTimeout is the deadline for a whole-project build subprocess, which only runs opt-in via -allow-build (default 600s; override with -build-timeout).

func FileExists

func FileExists(p string) bool

FileExists reports whether p names an existing regular file (not a directory) — the check the build-integrated frontends (Java, Rust) share for deciding whether a project manifest or wrapper (pom.xml, Cargo.toml, mvnw) is present before invoking its build tool.

func ParseContext

func ParseContext() (context.Context, context.CancelFunc)

ParseContext returns a context with the parse timeout and its cancel func. The caller MUST defer the cancel to release resources.

func ParseTimeout

func ParseTimeout() time.Duration

ParseTimeout is the deadline for a per-file parse/dump subprocess (default 120s; override with -parse-timeout).

func RunBatchScript

func RunBatchScript(label, scriptName, exe, scriptPath string, files []string, perFile func(i int, doc any, err error))

RunBatchScript runs one `<exe> <scriptPath> --batch <files...>` helper invocation (see WriteEmbeddedScript) under the parse deadline and decodes its stdout as one JSON document per file, in argv order (numbers preserved as json.Number). perFile is called exactly once per file index with the decoded document or a non-nil error: a process-level failure marks every file in the batch, while a per-file decode failure or an {"error": ...} document marks only that file — mirroring the frontends' old file-at-a-time error semantics. label prefixes error messages ("py_converter"); scriptName names the embedded helper in them ("pyast.py"). Shared by the interpreter frontends (Python, Ruby), whose batch parses differ only in these labels and in what they do with each document.

func SetTimeouts

func SetTimeouts(parse, build time.Duration)

SetTimeouts overrides the parse and/or build subprocess deadlines (the CLI's -parse-timeout / -build-timeout flags). A non-positive value leaves that deadline unchanged. Call it once, before any conversion starts — it is a process-wide setting, not synchronized against concurrent scans.

func WriteEmbeddedScript

func WriteEmbeddedScript(pattern string, content []byte) (string, func(), error)

WriteEmbeddedScript materializes an embedded helper script (e.g. the Python ast dumper, the Ruby Ripper dumper) into a temp file named after pattern (e.g. "godzilla-pyast-*.py") and returns its path plus a cleanup func the caller must invoke when done. Shared by the frontends that shell out to an interpreter with an embedded helper.