marker: report which comparisons could not be decided

[jonyoder]

Closes #44.

Evaluate returns a bare bool, so a caller cannot distinguish "this marker is false" from "this marker could not be decided". This adds two methods that recover the difference, and leaves Evaluate bit-for-bit unchanged.

func (m Marker) EvaluateUndecidable(env Environment, extraList []string) (bool, []Undecidable)
func (m Marker) Variables() []string

What counts as undecidable

Exactly two things, both of which currently answer false indistinguishably from a real false:

• ~= or === reaching the generic string-operator table, which has no semantics for them. pypa/packaging raises UndefinedComparison here; this package returns false as a documented divergence, because there was no channel to report it on. Note it cannot happen when either operand is version-typed and both sides parse as PEP 440 versions, since the specifier path answers first and answers correctly.
• An environment variable resolving to "". EnvironmentFromTarget legitimately cannot know platform_release or platform_version for a declared target and leaves them empty, and comparing "" against anything is meaningless. A literal "" written by the marker author is not reported.

What is deliberately not undecidable

Ordered comparisons on string operands. < and > returning false, and <=/>= collapsing to equality, is faithful to packaging, whose _operators table is literally {"<": lambda: False, "<=": eq, ">=": eq, ">": lambda: False} and where sys_platform >= "darwin" evaluates False. Verified against 26.3 and asserted in TestEvaluateUndecidable_Decidable so a future reader does not "fix" it.

Why Variables ships alongside

EvaluateUndecidable cannot cover the case where the caller invented a value. A declared interpreter of 3.13 forces some PythonFullVersion, and the answer then depends on the invention: python_full_version >= "3.13.2" is false at 3.13.0 and true at 3.13.99, with nothing empty and no operator undefined. Only the caller knows which fields it fabricated; it just needs to ask which variables a marker touches. TestInventedPatchLevelIsDecidableButArbitrary pins that distinction explicitly.

Without these two methods the only available workaround is a substring scan of Marker.String() for the operators and variable names, which has false positives on quoted literals (sys_platform == "platform_version" matches) and a token list for every consumer to hand-maintain against this library.

Behaviour and scope

Short-circuiting limits reporting to comparisons actually reached, which is what a caller wants: an and already decided false by its first operand needs no further explanation. TestEvaluateUndecidable_ShortCircuitLimitsReporting covers both orderings.

Evaluate becomes a one-line wrapper, and a nil collector makes the reporting path free on that route. The pre-existing marker tests pin that its behaviour is unchanged.

gofmt clean, go vet ./... clean, full module suite green.

Found while designing declared-environment filtering for Posit Package Manager's air-gapped PyPI mirror, where a dependency edge dropped because a marker could not be evaluated means a missing package and no fallback.

🤖 Generated with Claude Code