fix(packages): stop a non-numeric version taking down registry lookup

[Harshit-Vashisth]

Summary

PackageRecipe.validate() accepts any non-empty version string. The registry
then ordered those versions with:

sorted(versions.keys(), key=lambda v: [int(x) for x in v.split('.')])

which raises ValueError for anything that is not dotted integers.

That is not a hypothetical. It is most of what upstream embedded projects
actually publish:

Version	Result on master
v2.9.3	ValueError: invalid literal for int() with base 10: 'v2'
3.6.0-rc1	ValueError: invalid literal for int() with base 10: '0-rc1'
1.3.1+patch2	ValueError
main	ValueError

The leading v is littlefs's and FreeRTOS's own tag format — the recipe example
in docs/book/book.md §12.2 uses tag: V10.5.1.

The blast radius is wider than the one odd package. The same key was
duplicated in three methods, and two of them scan more than the package you
asked for:

• get(name) with no version scans every version of that package, so one such
  recipe breaks that package's resolution entirely;

• list_packages() scans every package, and PackageResolver._collect()
  builds its error message from it:

  raise ResolveError(
      f"Package '{name}' not found in registry. "
      f"Available: {[r.name for r in self.registry.list_packages()]}"
  )

  So a single unusual recipe anywhere in the registry turns an ordinary
  "you typo'd a package name" error into a ValueError traceback from inside
  the error handler.

Reproduced against master:

recipe with a 'v' prefix registered fine: dict_keys(['v2.9.3'])
  get(name)              -> ValueError: invalid literal for int() with base 10: 'v2'
  list_packages()        -> ValueError: invalid literal for int() with base 10: 'v2'
  list_all_versions()    -> ValueError: invalid literal for int() with base 10: 'v2'

Approach

Replace the three duplicated lambdas with one version_sort_key():

Rule	Effect
A leading v/V is ignored	v2.9.3 ranks with 2.9.3
All-digit components compare numerically	1.10.0 > 1.9.0 — the existing test still passes
Any other component compares as text, ranked below any numeric one	1.x < 1.0
A - or + suffix ranks below the same version without one	3.6.0-rc1 < 3.6.0

The property that matters is that the order is total and never raises: one
unusual recipe must not decide whether lookup works for the packages around it.

Deliberately not a full PEP 440 / semver implementation. That means either a
new dependency or a great deal more code, to implement a comparison the recipe
format does not specify. This defines the rules the registry actually needs,
documents them, and stops there.

Testing

tests/ebuild/test_package_registry.py goes from 1 case to 12, covering
v-prefixes, pre-release tags, build metadata, date-stamped versions, an
entirely non-numeric version, the empty string, one odd version sitting among
good ones, and a totality check over the key itself.

Per TESTING.md, the eleven behavioural cases were run against the unfixed
registry.py:

9 failed, 2 passed

The nine failures are all ValueError. The two that pass are the pre-existing
numeric-ordering test and 2024.06, which happens to parse as integers — noted
rather than dressed up as regression coverage.

With the fix: 12 passed.

Every ordering claim in the docs table was executed, not asserted:

1.x        vs 1.0        -> <
v2.9.3     vs 2.9.3      -> =
1.10.0     vs 1.9.0      -> >
3.6.0-rc1  vs 3.6.0      -> <

Lint, exactly as CI invokes them, on both changed files:

ruff check --select=E,F,W --ignore=E501   ->  All checks passed!
mypy --ignore-missing-imports             ->  Success: no issues found

Documentation

docs/book/book.md §12.5 gains a "Version ordering" subsection stating the
rules above, since "a request without a version resolves to the highest
version" was previously the only description and it did not say what "highest"
meant.

Considerations and limitations

CI on this PR will be red, for reasons that predate it. master currently
fails to import:

• ebuild/build/dispatch.py has a duplicated else: from a merge, so the
  module does not parse — SyntaxError: invalid syntax at line 133. fix: prevent false success for unsupported system backend #65 and fix: restore the package import and reconcile the merged backend behaviour #66
  address this.
• ebuild/build/ninja_backend.py calls self._object_path(...), which no
  longer exists — AttributeError.

I measured the effect of this branch on that: with
tests/{unit,ebuild}/test_dispatch.py excluded (they cannot be collected at
all), master is 26 failed / 162 passed, and with this branch applied it is
26 failed / 162 passed — diff of the two FAILED lists is empty. Nothing
introduced, nothing masked.

tests/ebuild/test_package_registry.py imports only
ebuild.packages.{registry,recipe}, which do not pull in the broken modules, so
these 12 tests run and pass on master today.

Other notes:

• The empty string is included in the parametrised test because _register()
  reaches it even though validate() rejects it — the ordering must be total
  for whatever is in the dict, not only for what the loader lets through.
• version_sort_key is exported (no leading underscore) because the resolver
  and any future constraint solver will need the same ordering, and a second
  copy is how this bug got into three places to begin with.
• Not addressed here: the registry stores versions in a plain dict keyed by the
  exact string, so 2.9.3 and v2.9.3 remain two distinct entries even though
  they now compare equal. Normalising keys would change get(name, version)
  lookup semantics, which is a larger decision than this fix.

[srpatcha]

Verified — total ordering is the right shape for this

A registry lookup that crashes on one unusual recipe takes down every package around it, so making the ordering total rather than making the parser stricter is the correct instinct. version is documented as free-form, and a resolver has no business rejecting main as a version when the recipe format allows it.

The four rules are each doing work:

Rule	Why it matters
Leading v/V ignored	Recipes copy tags verbatim; v2.9.3 and 2.9.3 are the same release
All-digit components numeric	1.10.0 > 1.9.0 — the one everybody gets wrong with a plain string sort
Non-numeric ranks below numeric	Keeps main from outranking every real release
-/+ suffix ranks below the bare version	3.6.0-rc1 < 3.6.0, which is what semver means and what a user expects

Splitting on the first - or + together is right: build metadata and a pre-release tag both need to lose to the plain version, and treating them separately invites a case where 1.0+build outranks 1.0.

Documenting it in docs/book/book.md alongside the code is what stops the next person re-deriving a different order in a second place.

Merge order

Currently red, but not because of anything here — origin/master has a SyntaxError in ebuild/build/dispatch.py that makes the suite uncollectable (2 errors during collection). Merged on top of #66, which repairs that: 217 passed. Needs #66 first, then this goes in unchanged.

Verification

Merged onto origin/master + #66 locally; pytest 217 passed.