[wic,v3,08/10] tests: ignore E402 in the test tree for the sys.path bootstrap

The unit tests that follow run against a plain checkout that has not
been installed. To do that, each test module prepends the in-tree src/
directory to sys.path and only then imports wic:

    _SRC = Path(__file__).resolve().parent.parent.parent / "src"
    if str(_SRC) not in sys.path:
        sys.path.insert(0, str(_SRC))

    from wic.bb.utils import mkdirhier

That bootstrap necessarily runs before the wic imports, which trips
ruff's E402 (module-level import not at top of file). The ordering is
required, not accidental: the import would fail without the sys.path
adjustment ahead of it.

Rather than scatter per-line noqa comments through every test module,
this commit relaxes E402 for the test tree once, via a
[tool.ruff.lint.per-file-ignores] entry scoped to tests/**. It is the
only rule relaxed for tests/; the suite is otherwise held to a clean
bar by --lint-tests.

tests/docs/linting.md gains a section describing this single exception
and why it exists.

AI-Generated: codex/claude-opus 4.7 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v3:
- no change in this revision.
changes in v2:
- v1 submitted the entire test suite as a single commit; v2 breaks
  the work into a reviewable series, and this patch is one step of it.
---
 pyproject.toml        |  8 ++++++++
 tests/docs/linting.md | 20 ++++++++++++++++++++
 2 files changed, 28 insertions(+)

On Wed, 2026-07-01 at 03:40 -0400, Trevor Woerner via
lists.yoctoproject.org wrote:
> The unit tests that follow run against a plain checkout that has not
> been installed. To do that, each test module prepends the in-tree src/
> directory to sys.path and only then imports wic:
> 
>     _SRC = Path(__file__).resolve().parent.parent.parent / "src"
>     if str(_SRC) not in sys.path:
>         sys.path.insert(0, str(_SRC))
> 
>     from wic.bb.utils import mkdirhier
> 
> That bootstrap necessarily runs before the wic imports, which trips
> ruff's E402 (module-level import not at top of file). The ordering is
> required, not accidental: the import would fail without the sys.path
> adjustment ahead of it.
> 
> Rather than scatter per-line noqa comments through every test module,
> this commit relaxes E402 for the test tree once, via a
> [tool.ruff.lint.per-file-ignores] entry scoped to tests/**. It is the
> only rule relaxed for tests/; the suite is otherwise held to a clean
> bar by --lint-tests.
> 
> tests/docs/linting.md gains a section describing this single exception
> and why it exists.
> 
> AI-Generated: codex/claude-opus 4.7 (xhigh)
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
> changes in v3:
> - no change in this revision.
> changes in v2:
> - v1 submitted the entire test suite as a single commit; v2 breaks
>   the work into a reviewable series, and this patch is one step of it.
> ---
>  pyproject.toml        |  8 ++++++++
>  tests/docs/linting.md | 20 ++++++++++++++++++++
>  2 files changed, 28 insertions(+)
> 
> diff --git a/pyproject.toml b/pyproject.toml
> index 656adcd4930a..fb42fe6dd135 100644
> --- a/pyproject.toml
> +++ b/pyproject.toml
> @@ -58,3 +58,11 @@ tmp_path_retention_count  = 1
>  # not yet ruff-clean and is left out until its findings are fixed (see
>  # tests/docs/linting.md). --lint-src can still be run to preview the
>  # source findings, but it is reported, not enforced.
> +
> +[tool.ruff.lint.per-file-ignores]
> +# Test modules prepend the in-tree src/ directory to sys.path before
> +# importing wic, so the suite runs against a checkout that has not been
> +# installed. That bootstrap necessarily runs before the wic imports,
> +# which trips E402 (module-level import not at top of file). The
> +# ordering is deliberate; ignore E402 for the test tree only.
> +"tests/**" = ["E402"]

LTGM.

> diff --git a/tests/docs/linting.md b/tests/docs/linting.md
> index 71b4de21c100..1c1bfcc06f82 100644
> --- a/tests/docs/linting.md
> +++ b/tests/docs/linting.md
> @@ -4,6 +4,7 @@
>  
>  - [Running the linter](#running-the-linter)
>  - [tests/ must be clean](#tests-must-be-clean)
> +- [The one intentional exception in tests/](#the-one-intentional-exception-in-tests)
>  - [src/ is not linted yet](#src-is-not-linted-yet)
>  
>  The test suite is linted with [ruff](https://docs.astral.sh/ruff/). It
> @@ -28,6 +29,25 @@ Our own test code is held to a clean bar: `tests/run-tests.sh
>  --lint-tests` reports nothing. If you add a test that trips a rule, fix
>  the test before the change lands.
>  
> +## The one intentional exception in tests/
> +
> +Test modules prepend the in-tree `src/` directory to `sys.path` before
> +importing `wic`, so the suite runs against a plain checkout that has not
> +been installed:
> +
> +```python
> +_SRC = Path(__file__).resolve().parent.parent.parent / "src"
> +if str(_SRC) not in sys.path:
> +    sys.path.insert(0, str(_SRC))
> +
> +from wic.bb.utils import mkdirhier
> +```
> +
> +That bootstrap necessarily runs before the `wic` imports, which trips
> +`E402` (module-level import not at top of file). The ordering is
> +required, so `E402` is ignored for the test tree via `per-file-ignores`
> +in `pyproject.toml`. This is the only rule relaxed for `tests/`.
> +
>  ## src/ is not linted yet
>  
>  `--lint-src` runs ruff over the wic source, but the source is **not**

Argh! Claude! No!

This is well documented by the comment in pyproject.toml, it doesn't
need detailed explanation in a documentation file.

Best regards,