vim-ale/_skills/installer/references/CLASSIFICATION.md

Classification Reference

When to flag classification issues, what the webi classifier does automatically, and what needs manual annotation.

---

What the classifier handles automatically

The webi classifier (internal/classify/classify.go) parses asset filenames using regex patterns and produces canonical os, arch, libc, and ext values. It handles the vast majority of packages with no configuration needed.

OS recognition

Filenames containing these terms are classified automatically:

• darwin, macos, osx, apple → macos in legacy cache
• linux → linux
• windows, win, win32, win64 → windows
• freebsd, openbsd, netbsd, dragonfly → respective values
• .deb, .rpm, .snap → linux (but dropped from legacy cache)
• .dmg, .app.zip → macos

Arch recognition

Filenames containing these terms are classified automatically:

• x86_64, amd64, 64bit, x64 → amd64
• aarch64, arm64 → arm64
• armv7, armv7l, armhf, gnueabihf → armv7l
• armv6, armv6l → armv6l
• i386, i686, 386, x86 → x86
• universal, universal2 → amd64 (fat binary; arm64 falls back to this)

Format recognition

• .tar.gz, .tar.xz, .tar.zst, .tar.bz2, .zip, .7z → compressed archive
• .pkg, .msi, .dmg → platform installer
• .exe → either bare binary or GUI installer (see below)
• No extension in filename → bare binary (ext = exe in cache)

Automatically dropped

These asset types are recognised and excluded without any configuration:

• Checksums: *.sha256, *.sha512, *.md5, *.sha256sum
• Signatures: *.asc, *.sig, *.cosign, *.sbom
• Source archives: files with source, src in the name but no OS
• Package formats not supported by the Node installer: .deb, .rpm, .snap, .AppImage, .apk

---

When you need to add configuration

Variant assets

A variant is a secondary build that serves the same OS/arch as a baseline build but requires different hardware or runtime support. The Node.js installer can't choose between variants — it only knows OS, arch, and libc. Variants must be tagged and then excluded at export time.

Common variants and how to identify them:

Variant	Filename pattern	Notes
CUDA (GPU)	*-cuda*, *cuda12*	NVIDIA GPU support
ROCm (GPU)	*-rocm*	AMD GPU support
Vulkan	*-vulkan*	Cross-vendor GPU
AppImage	*.AppImage	Linux sandboxed app
.NET fxdependent	*-fxdependent*	Requires .NET runtime
Windows installer	*Setup.exe, *Install.exe	GUI installer, not the binary

Rule: if there are multiple assets for the same OS/arch combination and they serve the same users differently, they need variant tags. The baseline (most widely compatible) build should be kept; variants should be tagged and excluded.

Example: ollama publishes for linux/amd64:

• ollama-linux-amd64.tar.zst — baseline (CPU + any GPU auto-detected)
• ollama-linux-amd64-rocm.tar.zst — ROCm variant
• ollama-linux-amd64-jetpack6.tar.zst — NVIDIA Jetson variant

Only the baseline is useful via webi. The ROCm and Jetpack builds should be tagged as variants and excluded.

---

Windows .exe: bare binary vs GUI installer

.exe assets are ambiguous — they could be:

1. A bare binary (the tool itself, run from command line)
2. A GUI installer (runs a setup wizard, not useful for webi)

How to tell:

• GUI installer: filename contains Setup, Install, Installer, inno, nsis
• GUI installer: the tool also has a .zip or .tar.gz for Windows
• Bare binary: filename matches the tool name with minimal decoration

When you see both, the .zip/archive build is what webi uses. The .exe installer should be tagged as a variant (installer) so it's excluded.

When there's only a .exe (no archive), it's probably the bare binary. Test by downloading and running it — a bare binary runs immediately.

---

Packages with no OS/arch in filenames

Some packages (rare) release with minimal filename decoration. Examples:

• tool-v1.2.3.tar.gz — no OS, no arch
• tool.tar.gz — version not even in filename

These are usually source archives (not compiled binaries) and should be dropped entirely from the release list. If they are compiled binaries for a specific OS, the releases.js config needs an asset_filter key to match the right file, plus OS/arch metadata added.

---

Non-standard OS naming in filenames

A few upstreams use unusual OS names:

• sunos — should map to solaris (the webi classifier does this)
• osx or macosx — recognised as macos
• apple-darwin (Rust triplet) — recognised as macos

If a package uses a genuinely unknown OS string, the classifier will produce os = "" for that asset. Those entries are dropped from the legacy cache.

---

Asset filter configuration

If GitHub releases for a package include multiple builds that would otherwise collide (e.g. extended vs non-extended for hugo, or specific project builds in a monorepo), add to the package's releases.conf:

# Only include assets containing "extended" in the name
asset_filter = extended

# Exclude assets containing "legacy" in the name
asset_exclude = legacy

These filters run before classification.

---

Quick checklist when inspecting a new package

1. Look at the latest 2–3 releases on GitHub. Note all asset filenames.
2. Find the "standard" builds — the ones a normal user would download for their OS. Usually there are ≤4 per OS (amd64, arm64, x86, armv7l).
3. Check for extras:
   • Are there GPU-specific builds for the same OS/arch? → variant
   • Are there .exe installer files alongside a .zip? → variant
   • Are there .deb/.rpm/.AppImage? → auto-dropped, no action needed
   • Does the Windows build have no archive and only a bare .exe? → fine
4. Check OS/arch naming — does the filename use standard terms, or something unusual that might confuse the classifier?
5. Check format changes — do old releases use a different archive type or directory layout than recent ones? The install script may need to handle both.

---

Canonical vocabulary reference

All cache output must use exactly these values.

OS: macos, linux, windows, freebsd, openbsd, netbsd, dragonfly, aix, illumos, plan9, solaris

Arch:

• amd64 (not x86_64)
• arm64 (not aarch64)
• armv7l (not armv7 — the l stands for little-endian; uname -m reports armv7l)
• armv6l (not armv6)
• x86 (not i386, i686, 386)
• mipsle (not mipsel)
• mips64le (not mips64el)
• Other: arm, ppc64le, ppc64, loong64, riscv64, s390x, mips, mips64

Libc: none (static/Go/Zig — never empty), gnu, musl, msvc

Ext: tar.gz, tar.xz, zip, exe, 7z, pkg, msi (no leading dot; exe for bare binaries with no file extension)