Module: vvaharness/util

docs / modules / util

← all docs

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.


flowchart LR IN["Input\nPipeline events · model usage"] --> ACT["Action\nBucket token/cost accounting and run environment checks"] ACT --> VAL["Validation\nShared credential/backend readiness checks (same engine `setup` & `doctor` use)"] VAL --> OUT["Output\nMetrics · token counts · errors.jsonl · progress"]

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)

flowchart LR ENV[environment.py] --> DOC[doctor / setup] MODELCALL[model backends] --> TOK[tokens.py] MODELCALL --> JX[json_extract.py] STAGES[stages] --> ST[status.py + scan_progress.py] STAGES --> ERR[errlog.py → errors.jsonl] MET[metrics.py] --> RPT[ScanMetrics]

Technical details

flowchart LR IN["Input\nPipeline events · model usage"] --> ACT["Action\nBucket token/cost accounting and run environment checks"] ACT --> VAL["Validation\nShared credential/backend readiness checks (same engine `setup` & `doctor` use)"] VAL --> OUT["Output\nMetrics · token counts · errors.jsonl · progress"]

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.