Runner
runner
Subprocess runner that targets the audited project's venv.
When auditing an external project, tools (ruff, mypy, pytest, etc.) must execute in that project's virtual environment, not axm-audit's own.
ProcessVerdict
Bases: Enum
Centralized interpretation of a subprocess exit.
One source of truth for what a returncode means to a scored rule, so individual rules no longer re-derive returncode semantics (which is how an env-failure could silently score a green 100).
Members
CLEAN: the tool ran and found nothing (rc == 0).
ISSUES: the tool ran and reported findings via an expected
non-zero exit (e.g. ruff rc=1 with JSON findings).
ENV_FAILURE: the tool did not actually complete the check
(rc in :data:_ENV_FAILURE_RETURNCODES, or a timeout).
A scored rule MUST fail loud on this verdict, never green.
Source code in packages/axm-audit/src/axm_audit/core/runner.py
find_venv(project_path)
Locate the nearest .venv directory for a project.
Checks project_path first, then walks up the directory tree to
support uv monorepo workspaces where the shared .venv lives
at the workspace root rather than inside the individual package.
The search is bounded to :data:_MAX_VENV_SEARCH_DEPTH levels to
avoid accidentally picking up an unrelated .venv higher in the
file system.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_path
|
Path
|
Root of the project being audited. |
required |
Returns:
| Type | Description |
|---|---|
Path | None
|
The |
Path | None
|
environment exists in the project or any of its ancestors |
Path | None
|
(within the bounded depth). |
Source code in packages/axm-audit/src/axm_audit/core/runner.py
interpret_process(result)
Classify a finished subprocess into a :class:ProcessVerdict.
This is the single home of the env-failure returncode set
(:data:_ENV_FAILURE_RETURNCODES). Both the lint and type rules
route their env-failure decision through here, removing the
historical mypy-vs-lint asymmetry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
result
|
CompletedProcess[str]
|
The completed (or synthetic-on-timeout) subprocess. |
required |
Returns:
| Type | Description |
|---|---|
ProcessVerdict
|
|
ProcessVerdict
|
returncode is in the env-failure set; otherwise |
ProcessVerdict
|
(an expected non-zero exit carrying findings). |
Source code in packages/axm-audit/src/axm_audit/core/runner.py
run_in_project(cmd, project_path, *, timeout=_DEFAULT_TIMEOUT, with_packages=None, extra_pythonpath=(), capture_output=False, text=False, check=False)
Run a command in the target project's environment.
A declared session runtime takes priority and never invokes uv or installs runtime packages; missing instruments fail in that interpreter. Without a contract, retains the legacy environment discovery described below.
Locates the nearest .venv/ — either in project_path itself
or in an ancestor directory (for uv monorepo workspace members).
Detached worktrees reuse the source checkout environment with candidate
sources first, without uv synchronization or dependency mutation. Ordinary
projects use uv run --no-sync --directory. Runtime packages are overlaid
without synchronising the target venv or writing its lock. Worktrees use
the source checkout venv and preserve the candidate source overlay.
When runtime packages are requested without a
project environment, uses an isolated uv environment; otherwise falls back
to the command directly with cwd set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cmd
|
list[str]
|
Command and arguments to run. |
required |
project_path
|
Path
|
Root of the project being audited. |
required |
timeout
|
int
|
Maximum seconds to wait before killing the subprocess. Defaults to 300 (5 minutes). |
_DEFAULT_TIMEOUT
|
with_packages
|
list[str] | None
|
Optional packages to inject at runtime via
|
None
|
extra_pythonpath
|
Sequence[Path]
|
Directories prepended to the child's |
()
|
capture_output
|
bool
|
Capture stdout/stderr (piped). Preserves the prior
|
False
|
text
|
bool
|
Decode output as text. Preserves the prior contract. |
False
|
check
|
bool
|
Raise |
False
|
Returns:
| Type | Description |
|---|---|
CompletedProcess[str]
|
CompletedProcess result. On timeout, returns a synthetic result |
CompletedProcess[str]
|
with |
Note
The child is launched in its own process group / session
(start_new_session on POSIX, CREATE_NEW_PROCESS_GROUP on
Windows). On timeout the whole group is killed, so a wrapper
such as uv and every process it forked (the inner python,
worker threads, …) are reaped together instead of being orphaned.
Source code in packages/axm-audit/src/axm_audit/core/runner.py
| Python | |
|---|---|
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 | |