randomparity / randomparity/kdive

just type and prek fail on macOS: ty resolves the host platform, not the target

Open Beginner friendly
#2,073 0 comments 0 reactions 0 assignees View on GitHub
area:build-install effort:S priority:P2 status:needs-triage type:bug
Dominant language
Python
Stars
0
Forks
0
Avg merge
1h 26m
Merged PRs (30d)
311

Description

## Symptom

`just type` fails on a macOS development host with 2 diagnostics, in files the developer
did not touch:

```
error[unresolved-attribute]: Module `os` has no member `pipe2`
--> src/kdive/jobs/capture_operations/launcher.py:1083:33
error[unresolved-attribute]: Module `socket` has no member `SO_PEERCRED`
--> src/kdive/processes/lifecycle/systemd_worker_control.py:127:52
Found 2 diagnostics
error: recipe `type` failed on line 84 with exit code 1
```

Both symbols exist on Linux and not on Darwin. `ty` reports each one as
`info: Python 3.14 was assumed when resolving the ... attribute`, citing
`pyproject.toml:12` — so it honours the pinned Python version and then resolves the
*host* platform, which `pyproject.toml` never pins.

## Reproduced

Darwin 25.6.0 (arm64), `ty 0.0.62`, on clean `origin/main` at `e376828c9`, 2026-08-25.
Identical 2 diagnostics with and without any local change, so it is not branch-specific.
Linux CI is green, because there the host platform already is `linux`.

## Blast radius

This is not only `just type`. `prek run` invokes the same recipe through the `ty` hook, so
**every** hook run on macOS reports `ty check ... Failed`, and `just install-hooks` —
which runs `prek install` and then `prek run -a` — fails. `just setup` chains
`install-hooks`, so first-time setup does not complete on a macOS host.

The result is a guardrail a macOS developer cannot run, which is the condition under which
people start passing `SKIP=ty`. The `[[tool.ty.overrides]]` block at `pyproject.toml:83-104`
already exists to keep `just type` consistent across environments "no `SKIP=ty` ritual"; this
is the same goal, for the platform axis rather than the installed-C-extension axis.

## Cause

`pyproject.toml` pins `requires-python = "==3.14.*"` but declares no target platform, so `ty`
falls back to the platform it runs on. The code under test targets Linux only: every CI job
in `ci.yml` is `ubuntu-latest`, there are no `sys.platform` guards anywhere in `src/`, and
neither `README.md` nor `AGENTS.md` claims macOS as a runtime target. macOS is a development
host, not a deployment target, so resolving against Darwin's stdlib asks the wrong question.

## Proposed fix

Pin the platform `ty` resolves against:

```toml
[tool.ty.environment]
python-platform = "linux"
```

**Verified.** With that stanza appended to `pyproject.toml`, `just type` on this macOS host
prints `All checks passed!`. The probe was reverted; nothing is committed.

This does not weaken the CI gate. On `ubuntu-latest` the resolved platform is already
`linux`, so the check is unchanged there; the stanza only makes every host ask the same
question CI asks. Note that `python-platform = "all"` is the wrong choice here — it would
report both symbols as unresolved on every host, which is correct for a portable library and
wrong for a Linux-only product.

## Acceptance criteria

- [ ] `just type` exits 0 on a macOS host and on Linux, with no diagnostics on clean `main`.
- [ ] `prek run -a` reports the `ty` hook as passed on a macOS host.
- [ ] `just install-hooks` completes on a macOS host, so `just setup` does.
- [ ] The target platform is pinned in `pyproject.toml`, not worked around per host and not
suppressed at either call site.
- [ ] The stanza carries a comment saying why it is pinned, in the style of the neighbouring
`[[tool.ty.overrides]]` block.
- [ ] CI's `lint · type · test` stays green, and the two named lines still type-check rather
than being silenced.

## Out of scope

- #1810 — the test suite dying at conftest import on macOS (`fallocate`). Different symbol,
different mechanism, already filed. This issue does not fix or depend on it.

## Provenance

Found while running the guardrails for the review of #2071 on a macOS host.

Contributor guide

Open the contributing guide

Research direction

Start in pyproject.toml, especially the existing [[tool.ty.overrides]] block at lines 83-104 and the requires-python setting near line 12. Pin ty's target platform to Linux with the requested explanatory comment, then run just type and prek run -a on macOS; verify just install-hooks completes and CI's lint, type, and test jobs remain green.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Bug
Difficulty
1/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
92/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.