impulso-audit

Impulso Codebase Audit

Full-scope audit of a Bayesian Vector Autoregressive (VAR) and structural VAR library. Run against a local checkout.

Workflow

Execute phases 1–7 in order. Each phase gathers findings. Phase 8 compiles the report.

Phase 1: Repository Discovery

Understand the repo before auditing. Read these files (skip missing ones):

pyproject.toml
setup.cfg / setup.py (if present)
.github/workflows/*.yml
.pre-commit-config.yaml
uv.lock (first 50 lines)
Makefile / justfile (if present)

Record:

• Python version constraints (requires-python)
• Dependency list and version pins
• Dev/test dependency groups
• Build backend (hatchling, setuptools, etc.)
• uv workspace configuration if any
• Linter/formatter config (ruff, mypy, ty, etc.)

Phase 2: Code Standards Audit

Read references/code-standards.md for the full checklist, then scan the source tree.

For each .py file under the main package directory:

1. Sample files proportionally — read ALL files in small packages (<30 files), or ~40% in larger ones, prioritising core modules (spec, data, fitted, identified, priors, samplers, results).
2. Check against each item in the checklist, including the Probabilistic Programming / Domain-Specific and Protocols and Extensibility sections.
3. Record concrete findings with file paths and line numbers where possible.

Phase 3: Pydantic Usage Audit

Read references/pydantic-checklist.md for the full checklist, then audit all Pydantic models.

1. Use the Grep tool to find all BaseModel subclasses: pattern class \w+\(BaseModel\) in src/impulso/.
2. For each model, check against the checklist items: model_config consistency, Field constraints, validator patterns, serialization, arbitrary_types_allowed usage, v2 feature adoption, and performance.
3. Pay special attention to:
   • Whether a shared base model class would reduce model_config duplication
   • Whether arbitrary_types_allowed is justified for each model
   • Whether model_construct() is used in internal code paths that build models from already-validated data
   • Whether @computed_field could replace any manual @property definitions
4. Record concrete findings with file paths and line numbers.