Refactor DFB Linter Distribution to Use Project Virtual Environments

[dgutson]

Background

The Deviation From Baseline (DFB) tool is used to execute a predefined set of linters on a project and compare the results against a version-controlled baseline.

The baseline contains the list of accepted (whitelisted) warnings and errors. The expected behavior is:

• If the number of existing issues decreases, the pipeline should pass.
• If new issues are introduced (i.e., the baseline deviation increases), the pipeline should fail.
• The baseline can be intentionally updated when changes are accepted.

This allows projects to continuously improve code quality without being blocked by historical issues.

Current Problem

Historically, DFB executed linters installed directly on the host environment. Whenever one of the linters was upgraded, many pipelines started failing because the newer linter version produced different diagnostics.

To make the execution reproducible, DFB was changed to execute linters from a Docker image containing pinned versions of every tool.

While this solved the version consistency problem, it also have the following issue:

• The linters execute from the Docker/global Python environment instead of the target project's virtual environment.
• As a result, Python-aware linters cannot correctly resolve project dependencies.
• This leads to false positives such as:
  • Missing imports
  • Unresolved dependencies
  • Incorrect type information
  • Invalid package resolution

Essentially, the linters analyze the project using the wrong Python environment.

Proposed Solution

Replace the Docker-based linter installation model with a Python package distribution model.

Create a DFB package that:

• Declares pinned versions of every supported linter as dependencies.
• Provides the DFB CLI responsible for orchestrating linter execution and baseline comparison.
• Can be installed as a development dependency in any Python project.

Each project would simply add DFB as a dev dependency regardless of its package manager:

• uv
• poetry
• pip / requirements.txt
• other compatible Python package managers

Because DFB and all linters would be installed inside the project's own virtual environment:

• Every linter would resolve the project's actual dependencies.
• Diagnostics would accurately reflect the project state.
• Linter versions would remain reproducible across all projects.
• Docker would no longer be required solely for version pinning.

Expected Workflow

1. Project installs DFB as a development dependency.
2. DFB installs all required linters with fixed versions.
3. The project executes dfb.
4. DFB runs each configured linter within the project's virtual environment.
5. Results are compared against the stored baseline.
6. The pipeline:

• passes if issues stay the same or decrease,
• fails only when new issues are introduced.

Benefits

• Reproducible linter versions across all projects.
• Correct dependency resolution by executing inside the project's virtual environment.
• Support for any Python dependency management tool (uv, poetry, pip, etc.).
• Elimination of false positives caused by the global Python environment.
• Simpler installation and maintenance by distributing DFB as a standard Python package instead of a Docker image.
• Better developer experience while preserving DFB's baseline-based quality gate.