znippy-common/src/plugins/native/skeletons.rs
//! Skeleton package handlers — dummy implementations for additional ecosystems.
//!
//! Each handler here is a *stub*: a static [`HandlerSpec`] (so it shows up in
//! `znippy handlers` and is selectable with `--format <name>`) plus a filename
//! `extract_metadata` (package name + best-effort version, zero decompression
//! cost) that writes the `name` / `version` columns. Real per-ecosystem parsing (manifest
//! files inside the archive, signatures, dep graphs) is left as a TODO for
//! whoever promotes the stub to a full handler.
//!
//! To promote a skeleton: give it its own spec + `extract_metadata` with real
//! parsing, and any ecosystem-specific subcommands in `spec().commands` +
//! `run_command`.
//!
//! `type_id` registry continues from the native handlers (1=cargo, 2=python,
//! 3=maven, 6=npm, 11=gem, 14=conda — npm is `plugins::npm_native`, gem is
//! `plugins::gem_native`, conda is `plugins::conda_native`, NONE a skeleton). See
//! `.nornir/plugins-design.md` §f3 for the authoritative table, including the
//! tier-B ids that live in their own crates (25=media, 40=skidbladnir,
//! 41=rust-toolchain, 42=git).
//!
//! A promoted handler stays **here**, in `znippy-common/src/plugins/native/`, for as
//! long as it needs nothing but `std`, `arrow` and this crate. Needing a
//! third-party parser, a decompressor, a network fetch, its own crate-type or
//! its own release cadence is what makes it a `znippy-plugin-*` crate instead —
//! rule **P-5**.
use crate::plugin::{file_name, ArchiveTypePlugin, Col, ExtensionRow, ExtensionValue, Claim, HandlerSpec};
use std::collections::HashMap;
/// Best-effort `(name, version?)` split from a package filename.
///
/// Strips the first matching extension, then splits at the last `-`/`_`/`@`
/// that is immediately followed by a digit (the conventional version start).
/// Falls back to `(stem, None)` for formats without an embedded version
/// (e.g. raw ELF binaries).
fn parse_coords(path: &str, extensions: &[&str]) -> (String, Option<String>) {
let filename = file_name(path);
let stem = extensions
.iter()
.find_map(|ext| filename.strip_suffix(ext))
.unwrap_or(filename);
let mut split_pos = None;
for (i, c) in stem.char_indices() {
if matches!(c, '-' | '_' | '@') {
if let Some(next) = stem[i + 1..].chars().next() {
if next.is_ascii_digit() {
split_pos = Some(i);
}
}
}
}
match split_pos {
Some(pos) => (stem[..pos].to_string(), Some(stem[pos + 1..].to_string())),
None => (stem.to_string(), None),
}
}
/// Stamp out a skeleton handler that parses `name` + best-effort `version`
/// from the filename (the shared `coords` command prints them).
macro_rules! skeleton_handler {
(
struct: $struct:ident,
name: $name:literal,
type_id: $tid:literal,
aliases: [$($alias:literal),* $(,)?],
ecosystem: $eco:literal,
extensions: [$($ext:literal),* $(,)?],
description: $desc:literal $(,)?
) => {
#[doc = concat!("Skeleton handler for the ", $eco, " ecosystem (stub).")]
pub struct $struct;
impl ArchiveTypePlugin for $struct {
fn spec(&self) -> &HandlerSpec {
static SPEC: HandlerSpec = HandlerSpec {
name: $name,
aliases: &[$($alias),*],
type_id: $tid,
ecosystem: $eco,
extensions: &[$($ext),*],
claim: Claim::Extensions,
description: concat!($desc, " (skeleton — filename-only)"),
fields: SKELETON_FIELDS,
commands: &[],
};
&SPEC
}
fn extract_metadata(&self, path: &str, _data: &[u8]) -> Option<ExtensionRow> {
skeleton_row(path, self.spec().extensions)
}
}
};
}
/// The two columns every skeleton writes.
const SKELETON_FIELDS: &[(&str, Col)] = &[("name", Col::Utf8), ("version", Col::Utf8)];
fn skeleton_row(path: &str, extensions: &[&str]) -> Option<ExtensionRow> {
let (name, version) = parse_coords(path, extensions);
let mut fields = HashMap::new();
fields.insert("name".into(), ExtensionValue::Str(name));
fields.insert("version".into(), ExtensionValue::OptStr(version));
Some(ExtensionRow { fields })
}
skeleton_handler! {
struct: GoPlugin,
name: "go",
type_id: 4,
aliases: ["golang"],
ecosystem: "Go / Go modules (proxy.golang.org)",
extensions: [".zip", ".mod", ".info"],
description: "Go module zips published to the module proxy",
}
skeleton_handler! {
struct: NugetPlugin,
name: "nuget",
type_id: 5,
aliases: ["dotnet", ".net"],
ecosystem: ".NET / NuGet (nuget.org)",
extensions: [".nupkg", ".snupkg"],
description: ".NET NuGet packages (zip with a .nuspec manifest)",
}
// npm (type_id 6) is a REAL handler now — see `plugins::npm_native::NpmPlugin`
// (authoritative name+version from package.json). It is intentionally absent from
// the skeleton list below; `register` folds in `NpmPlugin` from `npm_native`.
// elf (type_id 7) is a REAL handler now — see the `znippy-plugin-elf` crate
// (`NativeElfPlugin`). It reads every fact from the BINARY: header, PT_INTERP,
// DT_NEEDED with symbol versions, build-id, ISA level, the .nordisk.buildthing
// receipt, .note.package and .dep-v0 — which is exactly what the skeleton here
// could not do, because it parsed the FILE NAME.
//
// It had to be DELETED rather than left beside the real handler: `find_handler`
// takes the first match in `builtin_handlers()` order and that vector is sorted
// by type_id, so a skeleton sharing the name `elf` would win over any handler
// with a higher id and `--format elf` would silently seal an archive with a
// handler that extracts nothing. That is the docker/media `image` collision
// recorded below, and it is why the real handler took id 7 instead of a fresh
// one. See `.nornir/elf-design.md` §3. It also leaves tier A: it needs an ELF
// parser and an inflate, so rule P-5 puts it in its own crate.
// rpm (type_id 8) is a REAL handler now — see `plugins::rpm_native::RpmPlugin`
// (authoritative NEVRA incl. epoch from the header tag table). It is intentionally
// absent from the skeleton list below; `builtin_handlers` folds in `RpmPlugin`.
// deb (type_id 9) is a REAL handler now — see `plugins::deb_native::DebPlugin`
// (authoritative control fields from the control tarball: ar → control.tar.* →
// control). Intentionally absent from the skeleton list; `builtin_handlers` folds
// in `DebPlugin`.
skeleton_handler! {
struct: FlatpakPlugin,
name: "flatpak",
type_id: 10,
aliases: ["flatpakref"],
ecosystem: "Flatpak bundles (Flathub)",
extensions: [".flatpak", ".flatpakref"],
description: "Flatpak single-file application bundles (OSTree)",
}
// gem (type_id 11) is a REAL handler now — see `plugins::gem_native::GemPlugin`
// (authoritative name/version/platform from metadata.gz). It is intentionally
// absent from the skeleton list; `builtin_handlers` folds in `GemPlugin`.
// `image` was an alias here and is NOT any more. It collided with the REAL media
// handler (`znippy-plugin-media`, type_id 25), which advertises `image` for a
// picture. `find_handler` takes the first match in `builtin_handlers()` order —
// `sort_by_key(type_id)` — so docker (12) won over media (25) and `--format
// image` over a photo tree silently sealed the archive with `pkg_type = 12`, a
// skeleton that extracts nothing, while `znippy handlers` listed the alias under
// media. media's `image` was unreachable and docker's was a lie about the
// content; the collision is now asserted against in
// `znippy-cli::handlers::tests::every_name_and_alias_in_the_register_is_unique`.
// `oci` and `container` say "container image" with no ambiguity at all, so
// nothing is lost here.
skeleton_handler! {
struct: DockerPlugin,
name: "docker",
type_id: 12,
aliases: ["oci", "container"],
ecosystem: "OCI / Docker container images",
extensions: [".oci", ".docker"],
description: "OCI image layouts / docker save tarballs (manifest + layers)",
}
skeleton_handler! {
struct: HelmPlugin,
name: "helm",
type_id: 13,
aliases: ["chart", "k8s"],
ecosystem: "Helm charts (Kubernetes / Artifact Hub)",
extensions: [".tgz"],
description: "Helm chart archives (Chart.yaml + templates)",
}
// conda (type_id 14) is a REAL handler now — see
// `plugins::conda_native::CondaPlugin` (authoritative name/version/build/subdir
// from info/index.json for .tar.bz2). It is intentionally absent from the
// skeleton list; `builtin_handlers` folds in `CondaPlugin`.
skeleton_handler! {
struct: SnapPlugin,
name: "snap",
type_id: 15,
aliases: ["snapcraft", "snapd"],
ecosystem: "Snap packages (Snapcraft / Snap Store)",
extensions: [".snap"],
description: "Snap application packages (squashfs image)",
}
skeleton_handler! {
struct: AppImagePlugin,
name: "appimage",
type_id: 16,
aliases: ["appdir"],
ecosystem: "AppImage portable Linux applications",
extensions: [".AppImage", ".appimage"],
description: "AppImage self-mounting application bundles (ELF + squashfs)",
}
skeleton_handler! {
struct: ComposerPlugin,
name: "composer",
type_id: 17,
aliases: ["php", "packagist"],
ecosystem: "PHP / Composer (Packagist)",
extensions: [".zip", ".phar"],
description: "Composer/PHP packages (zip with composer.json, or PHAR)",
}
skeleton_handler! {
struct: HexPlugin,
name: "hex",
type_id: 18,
aliases: ["elixir", "erlang", "mix"],
ecosystem: "Erlang / Elixir (hex.pm)",
extensions: [".tar"],
description: "Hex packages (tar of metadata + contents.tar.gz)",
}
skeleton_handler! {
struct: CabalPlugin,
name: "cabal",
type_id: 19,
aliases: ["haskell", "hackage"],
ecosystem: "Haskell / Cabal (Hackage)",
extensions: [".tar.gz"],
description: "Cabal source packages (sdist tarball with a .cabal file)",
}
skeleton_handler! {
struct: SwiftPlugin,
name: "swift",
type_id: 20,
aliases: ["swiftpm", "spm"],
ecosystem: "Swift / Swift Package Manager",
extensions: [".zip"],
description: "Swift package archives (Package.swift + sources)",
}
skeleton_handler! {
struct: ParquetPlugin,
name: "parquet",
type_id: 21,
aliases: ["geoparquet", "pq"],
ecosystem: "Apache Parquet / GeoParquet columnar data",
extensions: [".parquet", ".geoparquet"],
description: "Parquet column files (GeoParquet adds a geo metadata key)",
}
skeleton_handler! {
struct: DatasetPlugin,
name: "dataset",
type_id: 22,
aliases: ["hf", "huggingface", "hub"],
ecosystem: "ML datasets (Hugging Face Hub / Croissant)",
extensions: [".dataset", ".hf"],
description: "Versioned ML dataset bundles (data shards + dataset card)",
}
skeleton_handler! {
struct: ArrowPlugin,
name: "arrow",
type_id: 23,
aliases: ["ipc", "feather"],
ecosystem: "Apache Arrow IPC / Feather",
extensions: [".arrow", ".feather", ".ipc"],
description: "Arrow IPC record-batch files (zero-copy columnar)",
}
skeleton_handler! {
struct: GeoJsonPlugin,
name: "geojson",
type_id: 24,
aliases: ["geo", "gis", "shapefile"],
ecosystem: "GIS vector data (GeoJSON / Shapefile / GeoPackage)",
extensions: [".geojson", ".gpkg", ".shp", ".fgb"],
description: "Geospatial vector datasets (features + CRS)",
}
/// Every skeleton handler, in `type_id` order. The register in `znippy-cli`
/// folds these in alongside the native handlers.
pub fn skeleton_handlers() -> Vec<Box<dyn ArchiveTypePlugin>> {
vec![
Box::new(GoPlugin),
Box::new(NugetPlugin),
Box::new(FlatpakPlugin),
Box::new(DockerPlugin),
Box::new(HelmPlugin),
Box::new(SnapPlugin),
Box::new(AppImagePlugin),
Box::new(ComposerPlugin),
Box::new(HexPlugin),
Box::new(CabalPlugin),
Box::new(SwiftPlugin),
Box::new(ParquetPlugin),
Box::new(DatasetPlugin),
Box::new(ArrowPlugin),
Box::new(GeoJsonPlugin),
]
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parse_coords_splits_name_and_version() {
assert_eq!(
parse_coords("foo/bar-1.2.3.nupkg", &[".nupkg"]),
("bar".to_string(), Some("1.2.3".to_string()))
);
assert_eq!(
parse_coords("lodash-4.17.21.tgz", &[".tgz"]),
("lodash".to_string(), Some("4.17.21".to_string()))
);
}
#[test]
fn parse_coords_handles_no_version() {
assert_eq!(
parse_coords("/usr/bin/ls.elf", &[".elf"]),
("ls".to_string(), None)
);
}
#[test]
fn skeletons_have_unique_sequential_type_ids() {
let mut ids: Vec<i8> = skeleton_handlers().iter().map(|h| h.type_id()).collect();
let mut sorted = ids.clone();
sorted.sort();
sorted.dedup();
assert_eq!(ids.len(), sorted.len(), "type_ids must be unique");
ids.sort();
assert_eq!(*ids.first().unwrap(), 4, "skeletons start at type_id 4");
assert_eq!(*ids.last().unwrap(), 24);
}
#[test]
fn every_skeleton_matches_and_extracts() {
for h in skeleton_handlers() {
let m = h.meta();
assert!(!m.extensions.is_empty(), "{} has no extensions", m.name);
let sample = format!("pkg-1.0{}", m.extensions[0]);
assert!(h.matches_path(&sample), "{} should match {}", m.name, sample);
let row = h.extract_metadata(&sample, &[]).expect("row");
assert!(row.fields.contains_key("name"));
}
}
}