Module: vvaharness/util
Role. Plumbing shared across stages: environment checks, token/metrics accounting, JSON extraction, prompts, progress, and the error log.
Size. 9 files · ~1,784 LOC.
The toolbox every other part reuses: it checks your environment is ready (used by
doctor/setup), counts tokens and cost, safely pulls JSON out of chatty model responses,
renders progress, and records non-fatal errors. Nothing here is security analysis itself — it's
the infrastructure that keeps runs observable and robust.
Explain-it-simply. The shared toolbox — batteries, tape, and gauges the rest of the machine relies on.
Data-flow (this module)
Technical details
environment.py (~565 LOC) is the readiness engine (python_check, credential_checks,
detect_gateway, recommend_profile). tokens.py is the process-wide token counter; metrics.py
builds ScanMetrics. json_extract.py robustly extracts JSON from prose (extract_json,
_balanced_span). prompts.py holds shared prompt blocks for S4/S6/S8. status.py and
scan_progress.py provide the spinner/structured events and per-file [progress] view.
errlog.py is the structured error log with per-stage counts.
File map (quick scan)
| File | LOC | Purpose |
|---|---|---|
util/__init__.py |
29 | — |
util/environment.py |
565 | Environment readiness engine shared by vvaharness setup and |
util/errlog.py |
140 | Structured error log shared across pipeline stages. |
util/json_extract.py |
166 | Pull a JSON object/array out of a model response that may have prose around it. |
util/metrics.py |
140 | Build ScanMetrics from pipeline state. Kept out of the orchestrator so the main |
util/prompts.py |
136 | Shared prompt blocks used by s4 (researchers), s6 (verifiers), and s8 (chain analysis). |
util/scan_progress.py |
318 | vvaharness.util.scan_progress — per-file scan observability. |
util/status.py |
183 | Per-stage status reporting for the scan pipeline. |
util/tokens.py |
107 | Process-wide token accounting shared by every model backend (cli + sdk). |
Files & functions, explained
Every class and function below has a one-line plain-English note — readable whether you write code or not. _name marks an internal helper.
util/__init__.py
29 LOC. Utility / support module.
No top-level classes or functions (package init / constants).
util/environment.py
565 LOC. Environment readiness engine shared by vvaharness setup and
Classes
- Check — Represents the “Check” data/behaviour used in this file.
Functions
- _is_set() — (internal helper) checks / decides the set value.
- _looks_like_jwt() — (internal helper) Provides the “looks like jwt” logic.
- python_check() — Provides the “python check” logic.
- tool_check() — Provides the “tool check” logic.
- _claude_code_login_present() — (internal helper) Provides the “claude code login present” logic.
- agent_checks() — Provides the “agent checks” logic.
- dep_checks() — Provides the “dep checks” logic.
- credential_checks() — Provides the “credential checks” logic.
- _gateway_check() — (internal helper) checks / decides the check value.
- detect_gateway() — Looks up / reads the gateway value.
- detect_ca_cert() — Looks up / reads the ca cert step.
- recommend_profile() — Provides the “recommend profile” logic.
- dotenv_check() — Provides the “dotenv check” logic.
- config_check() — Provides the “config check” logic.
- remediation_inputs_check() — Provides the “fix inputs check” logic.
- _backend_credential_ok() — (internal helper) Provides the “backend credential ok” logic.
- _remediate_checks() — (internal helper) runs the checks value.
- _validate_checks() — (internal helper) checks / decides the checks value.
- tls_check() — Provides the “secure connection check” logic.
- run_checks() — Runs the checks value.
- summarize() — Provides the “summarize” logic.
util/errlog.py
140 LOC. Structured error log shared across pipeline stages.
Functions
- configure() — Sets up / maintains the configure value.
- current_path() — Provides the “current path” logic.
- counts_by_stage() — Provides the “counts by pipeline step” logic.
- log() — Provides the “log” logic.
util/json_extract.py
166 LOC. Pull a JSON object/array out of a model response that may have prose around it.
Functions
- _repair_invalid_escapes() — (internal helper) reads and cleans up the invalid escapes step.
- _balanced_span() — (internal helper) reads and cleans up the span value.
- extract_json() — Reads and cleans up the data file value.
util/metrics.py
140 LOC. Build ScanMetrics from pipeline state. Kept out of the orchestrator so the main
Functions
- now_iso() — Provides the “now iso” logic.
- build() — Builds / writes the build value.
- _loc() — (internal helper) Provides the “lines of code” logic.
util/prompts.py
136 LOC. Shared prompt blocks used by s4 (researchers), s6 (verifiers), and s8 (chain analysis).
No top-level classes or functions (package init / constants).
util/scan_progress.py
318 LOC. vvaharness.util.scan_progress — per-file scan observability.
Classes
- ChunkProgress — Represents the “ChunkProgress” data/behaviour used in this file.
- ScanProgress — Represents the “ScanProgress” data/behaviour used in this file.
- from_cfg() — Provides the “from code control-flow” logic.
- stage_started() — Builds / writes the started value.
- stage_done() — Builds / writes the done value.
- stage_note() — Builds / writes the note value.
- discovered() — Looks up / reads the discovered value.
- queued() — Provides the “queued” logic.
- scanning() — Runs the scanning value.
- scanned() — Runs the scanned value.
- print_summary() — Provides the “print summary” logic.
- _emit() — (internal helper) builds / writes the emit value.
util/status.py
183 LOC. Per-stage status reporting for the scan pipeline.
Classes
- _Spinner — (internal) Represents the “Spinner” data/behaviour used in this file.
- start() — Provides the “start” logic.
- _run() — (internal helper) runs the run value.
- stop() — Provides the “stop” logic.
Functions
- _is_tty() — (internal helper) checks / decides the tty value.
- json_logs_enabled() — Provides the “data file logs enabled” logic.
- emit_event() — Builds / writes the event value.
- stage() — Builds / writes the pipeline step value.
util/tokens.py
107 LOC. Process-wide token accounting shared by every model backend (cli + sdk).
Classes
- _TokenCounter — (internal) Represents the “TokenCounter” data/behaviour used in this file.
- phase() — Provides the “phase” logic.
- add() — Adds detail to the add value.
- reset() — Sets up / maintains the reset value.
- snapshot() — Provides the “snapshot” logic.
Functions
- _bucket() — (internal helper) Provides the “bucket” logic.
See also: HLD · LLD · Data Flow · module index.