Skip to main content

thunderstore_engine/
models.rs

1#![deny(missing_docs)]
2
3use crate::error::Error;
4use crate::intern::{
5  InternKey, StringInterner, intern_option, intern_vec, resolve_option, resolve_vec,
6};
7use crate::query::search::SearchIndex;
8use serde::{Deserialize, Serialize};
9use std::collections::BTreeSet;
10use std::collections::HashMap;
11use std::collections::HashSet;
12use std::sync::OnceLock;
13use time::OffsetDateTime;
14
15/// An in-memory index of every package (and all of their versions) in a
16/// Thunderstore community.
17///
18/// This is the crate's central read model. Obtain one from
19/// [`ThunderstoreClient::get_manifest`](crate::client::ThunderstoreClient::get_manifest)
20/// or [`refresh_index`](crate::client::ThunderstoreClient::refresh_index), then
21/// query it for packages, versions, and download URLs.
22///
23/// Packages are addressed by a numeric index in the range `0..len()`. To look up
24/// a package by its `Owner-Name` identifier, build a map once with
25/// [`build_name_index`](PackageIndex::build_name_index), or use
26/// [`get_package_by_full_name`](PackageIndex::get_package_by_full_name). To pull a
27/// single field without materializing a whole [`Package`], use the `resolve_*_at`
28/// accessors.
29///
30/// A `PackageIndex` is built from a `Vec<Package>` (via [`From`]) — for example
31/// the JSON returned by the Thunderstore API — and is what the client persists to
32/// and loads from its on-disk cache.
33#[derive(Debug, Clone)]
34pub struct PackageIndex {
35  pub(crate) interner: StringInterner,
36  pub(crate) names: Vec<Option<InternKey>>,
37  pub(crate) full_names: Vec<Option<InternKey>>,
38  pub(crate) owners: Vec<Option<InternKey>>,
39  pub(crate) package_urls: Vec<Option<InternKey>>,
40  pub(crate) dates_created: Vec<OffsetDateTime>,
41  pub(crate) dates_updated: Vec<OffsetDateTime>,
42  pub(crate) uuid4s: Vec<Option<InternKey>>,
43  pub(crate) rating_scores: Vec<Option<u32>>,
44  pub(crate) is_pinned: Vec<Option<bool>>,
45  pub(crate) is_deprecated: Vec<Option<bool>>,
46  pub(crate) has_nsfw_content: Vec<Option<bool>>,
47  pub(crate) categories: Vec<Vec<InternKey>>,
48  pub(crate) version_ranges: Vec<(usize, usize)>,
49  pub(crate) versions: VersionTable,
50  pub(crate) search: OnceLock<SearchIndex>,
51}
52
53/// Struct-of-Arrays representation of version data with interned strings.
54///
55/// Separates frequently accessed "hot" data from rarely accessed "cold" metadata
56/// for better cache performance and memory efficiency. String values are stored as
57/// interned keys that reference the index's string interner.
58#[derive(Debug, Clone)]
59pub(crate) struct VersionTable {
60  pub package_indices: Vec<usize>,
61  pub names: Vec<Option<InternKey>>,
62  pub full_names: Vec<Option<InternKey>>,
63  pub version_numbers: Vec<Option<InternKey>>,
64  pub download_urls: Vec<Option<InternKey>>,
65  pub dependencies: Vec<Vec<InternKey>>,
66  pub dates_created: Vec<OffsetDateTime>,
67  pub descriptions: Vec<Option<InternKey>>,
68  pub icons: Vec<Option<InternKey>>,
69  pub downloads: Vec<Option<u32>>,
70  pub website_urls: Vec<Option<InternKey>>,
71  pub is_active: Vec<Option<bool>>,
72  pub uuid4s: Vec<Option<InternKey>>,
73  pub file_sizes: Vec<Option<u64>>,
74}
75
76/// The on-disk cache format version. `bincode` is not self-describing, so this
77/// leading tag lets a build reject a cache written by an incompatible layout
78/// (rather than silently misdecoding it) — bump it on any change to the
79/// serialized field layout.
80///
81/// Version 2 switched the cache from the `bincode` serde bridge to `bincode`'s
82/// native `Encode`/`Decode` (so container allocation is bounded by the decode
83/// limit) and stores timestamps as `i128` Unix-nanosecond values.
84#[cfg(feature = "io")]
85pub(crate) const CACHE_FORMAT_VERSION: u32 = 2;
86
87/// On-disk (`bincode`) representation of a [`PackageIndex`].
88///
89/// This structure converts the runtime PackageIndex into a format that can be
90/// efficiently serialized and deserialized. The string interner is converted to a simple
91/// vector of strings (the string table), and all interned keys become u32 indices into
92/// this table.
93///
94/// This separation allows for optimal serialization performance while maintaining the
95/// memory efficiency benefits of string interning at runtime.
96///
97/// This is the on-disk cache encoding written and read by [`crate::client`]
98/// (`zstd` + `bincode`). Each field parallels the same-named field of
99/// [`PackageIndex`], with interned keys stored as `u32` indices into
100/// `string_table`.
101///
102/// Encoded and decoded with `bincode`'s native `Encode`/`Decode` (not the serde
103/// bridge) so the decode limit bounds container allocation, and timestamps are
104/// stored as `i128` Unix nanoseconds (see [`encode_dates`]/[`decode_dates`])
105/// because `time::OffsetDateTime` is not a native `bincode` type.
106#[cfg(feature = "io")]
107#[derive(bincode::Encode, bincode::Decode, Debug, Clone)]
108pub(crate) struct SerializedPackageIndex {
109  /// Cache-format tag; must equal [`CACHE_FORMAT_VERSION`]. Kept first so it is
110  /// the first value decoded from the stream.
111  pub format_version: u32,
112  pub string_table: Vec<String>,
113  pub names: Vec<Option<u32>>,
114  pub full_names: Vec<Option<u32>>,
115  pub owners: Vec<Option<u32>>,
116  pub package_urls: Vec<Option<u32>>,
117  /// Package creation/update times as `i128` Unix nanoseconds.
118  pub dates_created: Vec<i128>,
119  pub dates_updated: Vec<i128>,
120  pub uuid4s: Vec<Option<u32>>,
121  pub rating_scores: Vec<Option<u32>>,
122  pub is_pinned: Vec<Option<bool>>,
123  pub is_deprecated: Vec<Option<bool>>,
124  pub has_nsfw_content: Vec<Option<bool>>,
125  pub categories: Vec<Vec<u32>>,
126  pub version_ranges: Vec<(usize, usize)>,
127  pub versions: SerializedVersionTable,
128}
129
130/// Serializable representation of interned version data.
131///
132/// Contains version information with string values represented as u32 indices into
133/// the parent manifest's string table. This allows efficient serialization while
134/// maintaining the benefits of string interning.
135#[cfg(feature = "io")]
136#[derive(bincode::Encode, bincode::Decode, Debug, Clone)]
137pub(crate) struct SerializedVersionTable {
138  pub package_indices: Vec<usize>,
139  pub names: Vec<Option<u32>>,
140  pub full_names: Vec<Option<u32>>,
141  pub version_numbers: Vec<Option<u32>>,
142  pub download_urls: Vec<Option<u32>>,
143  pub dependencies: Vec<Vec<u32>>,
144  /// Version creation times as `i128` Unix nanoseconds.
145  pub dates_created: Vec<i128>,
146  pub descriptions: Vec<Option<u32>>,
147  pub icons: Vec<Option<u32>>,
148  pub downloads: Vec<Option<u32>>,
149  pub website_urls: Vec<Option<u32>>,
150  pub is_active: Vec<Option<bool>>,
151  pub uuid4s: Vec<Option<u32>>,
152  pub file_sizes: Vec<Option<u64>>,
153}
154
155impl PackageIndex {
156  /// Returns the number of packages in the index.
157  pub fn len(&self) -> usize {
158    self.names.len()
159  }
160
161  /// The folded search text best-match browsing compares, built on first use
162  /// and kept for the life of the index.
163  pub(crate) fn search_index(&self) -> &SearchIndex {
164    self.search.get_or_init(|| SearchIndex::new(self))
165  }
166
167  /// Builds what a [`BestMatch`](crate::query::SortKey::BestMatch) search
168  /// reads, which otherwise happens on the first such search. Call it on a
169  /// background thread after loading so the first keystroke stays fast. Later
170  /// calls return at once.
171  ///
172  /// ```
173  /// use std::sync::Arc;
174  /// use thunderstore_engine::models::PackageIndex;
175  ///
176  /// let index = Arc::new(PackageIndex::from(Vec::new()));
177  /// let preparing = Arc::clone(&index);
178  ///
179  /// std::thread::spawn(move || preparing.prepare_search()).join().unwrap();
180  /// ```
181  pub fn prepare_search(&self) {
182    self.search_index();
183  }
184
185  /// Returns true if the index contains no packages.
186  #[allow(dead_code)]
187  pub fn is_empty(&self) -> bool {
188    self.names.is_empty()
189  }
190
191  /// Returns the short package name at `idx`, or `None` if `idx` is out of range
192  /// or the name is not set.
193  pub fn resolve_name_at(&self, idx: usize) -> Option<String> {
194    resolve_option(&self.interner, *self.names.get(idx)?)
195  }
196
197  /// Returns the full package name (`Owner-Name`) at `idx`, or `None` if `idx` is
198  /// out of range or the name is not set.
199  pub fn resolve_full_name_at(&self, idx: usize) -> Option<String> {
200    resolve_option(&self.interner, *self.full_names.get(idx)?)
201  }
202
203  /// The indices of every package whose name or `Owner-Name` full name contains
204  /// `term`, case-insensitively.
205  ///
206  /// Returns indices rather than references so a caller can resolve only the
207  /// fields it needs from the interned index. An empty `term` matches every
208  /// package, so clearing a search box shows the full list rather than nothing.
209  pub fn search(&self, term: &str) -> Vec<usize> {
210    let needle = term.to_lowercase();
211
212    (0..self.len())
213      .filter(|&idx| {
214        if let Some(name) = self.resolve_name_at(idx)
215          && name.to_lowercase().contains(&needle)
216        {
217          return true;
218        }
219
220        self
221          .resolve_full_name_at(idx)
222          .is_some_and(|full_name| full_name.to_lowercase().contains(&needle))
223      })
224      .collect()
225  }
226
227  /// Returns the owner of the package at `idx`, or `None` if `idx` is out of
228  /// range or the owner is not set.
229  pub fn resolve_owner_at(&self, idx: usize) -> Option<String> {
230    resolve_option(&self.interner, *self.owners.get(idx)?)
231  }
232
233  /// Borrows the short package name at `idx`, or `None` if `idx` is out of range
234  /// or the name is not set.
235  ///
236  /// Unlike [`resolve_name_at`](Self::resolve_name_at), this borrows from the
237  /// index's interner and performs no allocation.
238  pub fn name_at(&self, idx: usize) -> Option<&str> {
239    self
240      .names
241      .get(idx)
242      .copied()
243      .flatten()
244      .map(|k| self.interner.resolve(&k))
245  }
246
247  /// Borrows the full package name (`Owner-Name`) at `idx`, or `None` if `idx` is
248  /// out of range or the name is not set.
249  ///
250  /// Unlike [`resolve_full_name_at`](Self::resolve_full_name_at), this borrows
251  /// from the index's interner and performs no allocation.
252  pub fn full_name_at(&self, idx: usize) -> Option<&str> {
253    self
254      .full_names
255      .get(idx)
256      .copied()
257      .flatten()
258      .map(|k| self.interner.resolve(&k))
259  }
260
261  /// Borrows the owner of the package at `idx`, or `None` if `idx` is out of
262  /// range or the owner is not set.
263  ///
264  /// Unlike [`resolve_owner_at`](Self::resolve_owner_at), this borrows from the
265  /// index's interner and performs no allocation.
266  pub fn owner_at(&self, idx: usize) -> Option<&str> {
267    self
268      .owners
269      .get(idx)
270      .copied()
271      .flatten()
272      .map(|k| self.interner.resolve(&k))
273  }
274
275  /// Looks up a package by its full name (`Owner-Name`) and materializes it,
276  /// returning `None` if no package matches.
277  #[allow(dead_code)]
278  pub fn get_package_by_full_name(&self, full_name: &str) -> Option<Package> {
279    let idx = self.find_index_by_full_name(full_name)?;
280
281    self.get_package_at(idx)
282  }
283
284  /// Returns the index of the package with the given full name (`Owner-Name`),
285  /// or `None` if no package matches.
286  #[allow(dead_code)]
287  pub fn find_index_by_full_name(&self, full_name: &str) -> Option<usize> {
288    self.full_names.iter().position(|key| {
289      key
290        .map(|k| self.interner.resolve(&k) == full_name)
291        .unwrap_or(false)
292    })
293  }
294
295  /// Materializes a full [`Package`], including all of its versions, from the
296  /// package at `idx`, or `None` if `idx` is out of range.
297  #[allow(dead_code)]
298  pub fn get_package_at(&self, idx: usize) -> Option<Package> {
299    let (version_start, version_end) = *self.version_ranges.get(idx)?;
300    let mut versions = Vec::with_capacity(version_end - version_start);
301
302    for ver_idx in version_start..version_end {
303      versions.push(Version {
304        name: resolve_option(&self.interner, self.versions.names[ver_idx]),
305        full_name: resolve_option(&self.interner, self.versions.full_names[ver_idx]),
306        description: resolve_option(&self.interner, self.versions.descriptions[ver_idx]),
307        icon: resolve_option(&self.interner, self.versions.icons[ver_idx]),
308        version_number: resolve_option(&self.interner, self.versions.version_numbers[ver_idx]),
309        dependencies: resolve_vec(&self.interner, &self.versions.dependencies[ver_idx]),
310        download_url: resolve_option(&self.interner, self.versions.download_urls[ver_idx]),
311        downloads: self.versions.downloads[ver_idx],
312        date_created: self.versions.dates_created[ver_idx],
313        website_url: resolve_option(&self.interner, self.versions.website_urls[ver_idx]),
314        is_active: self.versions.is_active[ver_idx],
315        uuid4: resolve_option(&self.interner, self.versions.uuid4s[ver_idx]),
316        file_size: self.versions.file_sizes[ver_idx],
317      });
318    }
319
320    Some(Package {
321      name: resolve_option(&self.interner, self.names[idx]),
322      full_name: resolve_option(&self.interner, self.full_names[idx]),
323      owner: resolve_option(&self.interner, self.owners[idx]),
324      package_url: resolve_option(&self.interner, self.package_urls[idx]),
325      date_created: self.dates_created[idx],
326      date_updated: self.dates_updated[idx],
327      uuid4: resolve_option(&self.interner, self.uuid4s[idx]),
328      rating_score: self.rating_scores[idx],
329      is_pinned: self.is_pinned[idx],
330      is_deprecated: self.is_deprecated[idx],
331      has_nsfw_content: self.has_nsfw_content[idx],
332      categories: resolve_vec(&self.interner, &self.categories[idx]),
333      versions,
334    })
335  }
336
337  /// Returns the index of the latest version of the package at `idx`, chosen by
338  /// most recent creation date, or `None` if `idx` is out of range or the
339  /// package has no versions.
340  ///
341  /// The returned value is an index into the internal (crate-private) version
342  /// table, so this is `pub(crate)`: exposing it publicly would hand callers an
343  /// opaque `usize` that no public accessor consumes and that is trivially
344  /// confused with a package index.
345  pub(crate) fn get_latest_version_at(&self, idx: usize) -> Option<usize> {
346    let (ver_start, ver_end) = *self.version_ranges.get(idx)?;
347
348    if ver_start >= ver_end {
349      return None;
350    }
351
352    (ver_start..ver_end).max_by_key(|&ver_idx| self.versions.dates_created[ver_idx])
353  }
354
355  /// Returns the index of the package at `idx`'s version `version_number`.
356  pub(crate) fn get_version_at(&self, idx: usize, version_number: &str) -> Option<usize> {
357    let (ver_start, ver_end) = *self.version_ranges.get(idx)?;
358
359    (ver_start..ver_end).find(|&ver_idx| {
360      self.versions.version_numbers[ver_idx].map(|key| self.interner.resolve(&key))
361        == Some(version_number)
362    })
363  }
364
365  /// Borrows the version number of the package at `idx`'s latest version, as
366  /// [`get_latest_version_at`](Self::get_latest_version_at) chooses it.
367  pub(crate) fn latest_version_number_at(&self, idx: usize) -> Option<&str> {
368    let ver_idx = self.get_latest_version_at(idx)?;
369    let key = self.versions.version_numbers[ver_idx]?;
370
371    Some(self.interner.resolve(&key))
372  }
373
374  /// Builds a map from each package's full name (`Owner-Name`) to its index,
375  /// for repeated by-name lookups.
376  pub fn build_name_index(&self) -> HashMap<String, usize> {
377    self
378      .full_names
379      .iter()
380      .enumerate()
381      .filter_map(|(idx, key)| {
382        let name = resolve_option(&self.interner, *key)?;
383        Some((name, idx))
384      })
385      .collect()
386  }
387
388  /// Checks the index for internal consistency.
389  ///
390  /// Returns `Ok(())` if the index is well-formed, otherwise an
391  /// [`Error::Cache`] describing the first problem found. The client runs this
392  /// automatically when loading a cached index, so a corrupt or truncated cache
393  /// surfaces as a recoverable error rather than a later panic.
394  pub fn validate(&self) -> crate::Result<()> {
395    self.validate_lengths()?;
396    self.validate_version_ranges()?;
397    self.validate_version_ownership()?;
398    self.validate_unique_full_names()?;
399
400    Ok(())
401  }
402
403  /// Checks that every parallel struct-of-arrays vector has the length its group
404  /// requires: package-level vectors match the package count, version-level
405  /// vectors match the version count.
406  fn validate_lengths(&self) -> crate::Result<()> {
407    let pkg_count = self.names.len();
408
409    check_len("full_names", self.full_names.len(), pkg_count)?;
410    check_len("owners", self.owners.len(), pkg_count)?;
411    check_len("package_urls", self.package_urls.len(), pkg_count)?;
412    check_len("dates_created", self.dates_created.len(), pkg_count)?;
413    check_len("dates_updated", self.dates_updated.len(), pkg_count)?;
414    check_len("uuid4s", self.uuid4s.len(), pkg_count)?;
415    check_len("rating_scores", self.rating_scores.len(), pkg_count)?;
416    check_len("is_pinned", self.is_pinned.len(), pkg_count)?;
417    check_len("is_deprecated", self.is_deprecated.len(), pkg_count)?;
418    check_len("has_nsfw_content", self.has_nsfw_content.len(), pkg_count)?;
419    check_len("categories", self.categories.len(), pkg_count)?;
420    check_len("version_ranges", self.version_ranges.len(), pkg_count)?;
421
422    let version_count = self.versions.package_indices.len();
423
424    check_len("versions.names", self.versions.names.len(), version_count)?;
425    check_len(
426      "versions.full_names",
427      self.versions.full_names.len(),
428      version_count,
429    )?;
430    check_len(
431      "versions.version_numbers",
432      self.versions.version_numbers.len(),
433      version_count,
434    )?;
435    check_len(
436      "versions.download_urls",
437      self.versions.download_urls.len(),
438      version_count,
439    )?;
440    check_len(
441      "versions.dependencies",
442      self.versions.dependencies.len(),
443      version_count,
444    )?;
445    check_len(
446      "versions.dates_created",
447      self.versions.dates_created.len(),
448      version_count,
449    )?;
450    check_len(
451      "versions.descriptions",
452      self.versions.descriptions.len(),
453      version_count,
454    )?;
455    check_len("versions.icons", self.versions.icons.len(), version_count)?;
456    check_len(
457      "versions.downloads",
458      self.versions.downloads.len(),
459      version_count,
460    )?;
461    check_len(
462      "versions.website_urls",
463      self.versions.website_urls.len(),
464      version_count,
465    )?;
466    check_len(
467      "versions.is_active",
468      self.versions.is_active.len(),
469      version_count,
470    )?;
471    check_len("versions.uuid4s", self.versions.uuid4s.len(), version_count)?;
472    check_len(
473      "versions.file_sizes",
474      self.versions.file_sizes.len(),
475      version_count,
476    )?;
477
478    Ok(())
479  }
480
481  /// Checks that every version range is ordered and in-bounds, and that every
482  /// version's recorded `package_index` refers to a real package. Must run before
483  /// [`validate_version_ownership`](Self::validate_version_ownership), which
484  /// slices `package_indices` by these ranges.
485  fn validate_version_ranges(&self) -> crate::Result<()> {
486    let pkg_count = self.names.len();
487    let version_count = self.versions.package_indices.len();
488
489    for (idx, (start, end)) in self.version_ranges.iter().enumerate() {
490      if start > end {
491        return Err(Error::Cache(format!(
492          "Invalid version range at package {}: {} > {}",
493          idx, start, end
494        )));
495      }
496
497      if *end > version_count {
498        return Err(Error::Cache(format!(
499          "Version range at package {} ends at {} but only {} versions exist",
500          idx, end, version_count
501        )));
502      }
503    }
504
505    for (i, &pkg_idx) in self.versions.package_indices.iter().enumerate() {
506      if pkg_idx >= pkg_count {
507        return Err(Error::Cache(format!(
508          "version {} references package index {} but only {} packages exist",
509          i, pkg_idx, pkg_count
510        )));
511      }
512    }
513
514    Ok(())
515  }
516
517  /// Checks that every version is owned by exactly one package: its slot falls
518  /// inside exactly one package's contiguous range, and that package's recorded
519  /// `package_indices` entry agrees. This rejects a corrupt cache whose ranges are
520  /// individually in-bounds but overlap, leave gaps, or disagree with
521  /// `package_indices` — which would otherwise attach the wrong versions (and
522  /// wrong download URLs) to a package.
523  fn validate_version_ownership(&self) -> crate::Result<()> {
524    let version_count = self.versions.package_indices.len();
525
526    let mut owner_of: Vec<Option<usize>> = vec![None; version_count];
527
528    for (pkg_idx, range) in self.version_ranges.iter().enumerate() {
529      let (start, end) = *range;
530
531      for (offset, &owner_pkg) in self.versions.package_indices[start..end].iter().enumerate() {
532        let ver_idx = start + offset;
533
534        if owner_of[ver_idx].is_some() {
535          return Err(Error::Cache(format!(
536            "version {} is claimed by multiple packages (overlapping version ranges)",
537            ver_idx
538          )));
539        }
540
541        owner_of[ver_idx] = Some(pkg_idx);
542
543        if owner_pkg != pkg_idx {
544          return Err(Error::Cache(format!(
545            "version {} lies in package {}'s range but records package_index {}",
546            ver_idx, pkg_idx, owner_pkg
547          )));
548        }
549      }
550    }
551
552    for (ver_idx, owner) in owner_of.iter().enumerate() {
553      if owner.is_none() {
554        return Err(Error::Cache(format!(
555          "version {} is not covered by any package's version range",
556          ver_idx
557        )));
558      }
559    }
560
561    Ok(())
562  }
563
564  /// Checks that no full name repeats. Thunderstore guarantees full names are
565  /// unique, so a well-formed index never repeats one. Reject a corrupt or crafted
566  /// cache that does: otherwise `find_index_by_full_name` (first match) and
567  /// `build_name_index` (last match) could resolve the same name to different
568  /// packages, and the inspected package would differ from the installed one.
569  fn validate_unique_full_names(&self) -> crate::Result<()> {
570    let mut seen_full_names: HashSet<&str> = HashSet::new();
571
572    for key in self.full_names.iter().flatten() {
573      let full_name = self.interner.resolve(key);
574
575      if !seen_full_names.insert(full_name) {
576        return Err(Error::Cache(format!(
577          "duplicate full name {:?} appears in multiple packages",
578          full_name
579        )));
580      }
581    }
582
583    Ok(())
584  }
585}
586
587/// Errors with a `{field} length {actual} != {expected}` message when a parallel
588/// struct-of-arrays vector's length does not match the count its group requires.
589fn check_len(field: &str, actual: usize, expected: usize) -> crate::Result<()> {
590  if actual != expected {
591    return Err(Error::Cache(format!(
592      "{field} length {actual} != {expected}"
593    )));
594  }
595
596  Ok(())
597}
598
599/// Represents a mod package from the Thunderstore API.
600///
601/// This struct contains information about a mod package, including its metadata
602/// and all available versions.
603///
604/// `#[non_exhaustive]`: fields may be added as the Thunderstore API grows, so
605/// downstream code cannot construct or exhaustively destructure this directly.
606#[derive(Serialize, Deserialize, Clone)]
607#[non_exhaustive]
608pub struct Package {
609  /// The short name of the package
610  pub name: Option<String>,
611  /// The full name of the package, typically in format "Owner-Name"
612  pub full_name: Option<String>,
613  /// The username of the package owner
614  pub owner: Option<String>,
615  /// The URL to the package's page on Thunderstore
616  pub package_url: Option<String>,
617  /// When the package was first published
618  #[serde(with = "time::serde::rfc3339")]
619  pub date_created: time::OffsetDateTime,
620  /// When the package was last updated
621  #[serde(with = "time::serde::rfc3339")]
622  pub date_updated: time::OffsetDateTime,
623  /// Unique identifier for the package
624  pub uuid4: Option<String>,
625  /// User rating score for the package
626  pub rating_score: Option<u32>,
627  /// Whether the package is pinned by Thunderstore
628  pub is_pinned: Option<bool>,
629  /// Whether the package is marked as deprecated
630  pub is_deprecated: Option<bool>,
631  /// Whether the package contains NSFW content
632  pub has_nsfw_content: Option<bool>,
633  /// List of categories the package belongs to
634  pub categories: Vec<String>,
635  /// All available versions of the package
636  pub versions: Vec<Version>,
637}
638
639/// Represents a specific version of a mod package.
640///
641/// This struct contains information about one version of a package,
642/// including its version number, dependencies, and download information.
643///
644/// `#[non_exhaustive]`: fields may be added as the Thunderstore API grows, so
645/// downstream code cannot construct or exhaustively destructure this directly.
646#[derive(Serialize, Deserialize, Debug, Clone)]
647#[non_exhaustive]
648pub struct Version {
649  /// The name of this version
650  pub name: Option<String>,
651  /// The full name of this version
652  pub full_name: Option<String>,
653  /// The description of this version
654  pub description: Option<String>,
655  /// URL to the icon for this version
656  pub icon: Option<String>,
657  /// The version number (e.g., "1.0.0")
658  pub version_number: Option<String>,
659  /// List of dependencies required by this version
660  pub dependencies: Vec<String>,
661  /// URL to download this version
662  pub download_url: Option<String>,
663  /// Number of times this version has been downloaded
664  pub downloads: Option<u32>,
665  /// When this version was published
666  #[serde(with = "time::serde::rfc3339")]
667  pub date_created: time::OffsetDateTime,
668  /// URL to the website for this version
669  pub website_url: Option<String>,
670  /// Whether this version is active
671  pub is_active: Option<bool>,
672  /// Unique identifier for this version
673  pub uuid4: Option<String>,
674  /// Size of the download file in bytes
675  pub file_size: Option<u64>,
676}
677
678impl Package {
679  /// The most recently created version, or `None` for a package with no
680  /// versions.
681  ///
682  /// Ordering is by `date_created`, not by version number, so a republished
683  /// older version wins over a higher version string. This matches how
684  /// Thunderstore itself presents "latest".
685  pub fn latest_version(&self) -> Option<&Version> {
686    self.versions.iter().max_by_key(|v| v.date_created)
687  }
688
689  /// The `Owner-PackageName-1.0.0.zip` filename and download URL for the latest
690  /// version, or `None` if the package has no version or that version carries no
691  /// download URL.
692  ///
693  /// The filename is the archive name the download layer writes to disk, so it
694  /// must stay in the `Owner-Name-Version.zip` shape
695  /// [`crate::extract::parse_package_filename`] reads back.
696  #[cfg(test)]
697  pub fn zip_and_url(&self) -> Option<(String, String)> {
698    let pkg = self.latest_version()?;
699    let url: String = pkg.download_url.clone()?;
700    let version_number = pkg.version_number.as_ref()?;
701    let package_name = &self.full_name.as_ref()?;
702    let zip_name = format!("{}-{}.zip", package_name, version_number);
703
704    Some((zip_name, url))
705  }
706}
707
708/// Shows only the most relevant fields: the full name, and the latest version's
709/// dependencies and download URL.
710impl std::fmt::Debug for Package {
711  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
712    f.debug_struct("Package")
713      .field("full_name", &self.full_name)
714      .field(
715        "dependencies",
716        &self.latest_version().map(|v| &v.dependencies),
717      )
718      .field(
719        "download_url",
720        &self.latest_version().map(|v| &v.download_url),
721      )
722      .finish()
723  }
724}
725
726/// The outcome of [`DependencyGraph::resolve_report`]: the packages that
727/// resolved to a download, plus the names that did not.
728///
729/// `#[non_exhaustive]`: fields may be added as resolution reporting grows, so
730/// downstream code cannot construct or exhaustively destructure this directly.
731#[derive(Debug, Clone, Default)]
732#[non_exhaustive]
733pub struct Resolution {
734  /// Map of `Owner-Name-Version.zip` filename to download URL for every package
735  /// (requested or dependency) that resolved to a version in the index.
736  pub urls: HashMap<String, String>,
737  /// The `Owner-Name` identifiers that were requested (directly or as a
738  /// dependency) but not present in the index, sorted and deduplicated. A pin
739  /// to a version the package does not publish, or conflicting pins, are listed
740  /// as `Owner-Name-Version` instead. A non-empty list means the resulting
741  /// install is incomplete.
742  pub unresolved: Vec<String>,
743}
744
745/// Represents a graph of package dependencies to be resolved and installed.
746///
747/// This structure helps determine which packages need to be installed,
748/// including any dependencies they require.
749#[derive(Debug, Deserialize, Serialize)]
750pub struct DependencyGraph {
751  /// The list of package names that the user wants to install
752  install_packages: Vec<String>,
753  /// Versions to hold packages at, without requesting them
754  #[serde(default, skip_serializing_if = "Vec::is_empty")]
755  pins: Vec<String>,
756}
757
758impl DependencyGraph {
759  /// Creates a graph seeded with the packages a caller asked for.
760  ///
761  /// Names are `Owner-Name`, or `Owner-Name-Version` to install exactly that
762  /// version. Nothing is validated here, so an unknown name surfaces only at
763  /// resolution time.
764  pub fn new(install_packages: Vec<String>) -> Self {
765    Self {
766      install_packages,
767      pins: Vec::new(),
768    }
769  }
770
771  /// Holds packages at `Owner-Name-Version` if resolution reaches them.
772  /// Entries without a version are ignored.
773  pub fn pins(mut self, pins: impl IntoIterator<Item = String>) -> Self {
774    self.pins.extend(pins);
775
776    self
777  }
778
779  /// Resolves all dependencies for the requested packages against the package index.
780  ///
781  /// This method:
782  /// 1. Starts with the user-requested packages
783  /// 2. For each package, adds its dependencies to the list to process
784  /// 3. Continues until all dependencies are resolved
785  ///
786  /// Returns a map of archive filename to download URL covering the requested
787  /// packages and their full transitive closure, ready to hand to
788  /// [`crate::client::ThunderstoreClient::download_files`].
789  ///
790  /// # Limitations
791  ///
792  /// The version suffix of a dependency string (e.g. the `1.2.3` in
793  /// `Owner-Mod-1.2.3`) is discarded, so every package resolves to its *latest*
794  /// available version unless a requested `Owner-Name-Version` or a
795  /// [`pins`](Self::pins) entry names one. There is no version-constraint
796  /// solving: a package whose manifest depends on an older version of another
797  /// still receives the latest one.
798  ///
799  /// A requested package or dependency that is absent from `index` is silently
800  /// skipped here; use [`resolve_report`](Self::resolve_report) to learn which
801  /// names failed to resolve so an incomplete install can be surfaced rather than
802  /// treated as success.
803  pub fn resolve(&self, index: &PackageIndex) -> HashMap<String, String> {
804    self.resolve_report(index).urls
805  }
806
807  /// Resolves the install set like [`resolve`](Self::resolve), but also reports
808  /// every requested package or transitive dependency that could not be resolved
809  /// to a download — either absent from `index`, or present but with no
810  /// downloadable version.
811  ///
812  /// A non-empty [`Resolution::unresolved`] means the returned URL map is
813  /// incomplete: those names were moderated/removed, misspelled, live in a
814  /// different community, or have no downloadable version, and installing only
815  /// what resolved would leave a broken mod. Callers that must fail (or warn) on a
816  /// missing dependency should use this instead of [`resolve`](Self::resolve),
817  /// which discards the report.
818  pub fn resolve_report(&self, index: &PackageIndex) -> Resolution {
819    let name_index = index.build_name_index();
820    let mut sorted_set: BTreeSet<String> = self.install_packages.iter().cloned().collect();
821    let mut install_indices = Vec::new();
822    let mut seen: HashSet<usize> = HashSet::new();
823    let mut unresolved: Vec<String> = Vec::new();
824
825    let mut pins: HashMap<&str, BTreeSet<&str>> = HashMap::new();
826
827    for full_name in self.install_packages.iter().chain(&self.pins) {
828      if let Some((name, version)) = crate::util::split_version(full_name) {
829        pins.entry(name).or_default().insert(version);
830      }
831    }
832
833    tracing::debug!("Starting with mod list of: {:#?}", sorted_set);
834
835    while !sorted_set.is_empty() {
836      let Some(item) = sorted_set.pop_first() else {
837        continue;
838      };
839
840      let item = crate::util::full_name_prefix(&item).to_string();
841
842      let Some(&pkg_idx) = name_index.get(&item) else {
843        tracing::warn!(
844          "requested package {:?} was not found in the index; the install will be incomplete",
845          item
846        );
847        unresolved.push(item);
848
849        continue;
850      };
851
852      // Skip packages already processed so a dependency cycle (A->B->A or a
853      // self-dependency) terminates instead of re-inserting deps forever.
854      if !seen.insert(pkg_idx) {
855        continue;
856      }
857
858      let chosen_ver_idx = match pins.get(item.as_str()) {
859        None => index.get_latest_version_at(pkg_idx),
860        Some(versions) if versions.len() > 1 => {
861          tracing::warn!(
862            "package {:?} is pinned to more than one version ({:?}); the install will be incomplete",
863            item,
864            versions
865          );
866          unresolved.extend(versions.iter().map(|version| format!("{item}-{version}")));
867
868          continue;
869        }
870        Some(versions) => {
871          let version = versions.first().copied().unwrap_or_default();
872
873          match index.get_version_at(pkg_idx, version) {
874            Some(ver_idx) => Some(ver_idx),
875            None => {
876              tracing::warn!(
877                "package {:?} has no version {:?}; the install will be incomplete",
878                item,
879                version
880              );
881              unresolved.push(format!("{item}-{version}"));
882
883              continue;
884            }
885          }
886        }
887      };
888
889      if let Some(chosen_ver_idx) = chosen_ver_idx {
890        let deps = resolve_vec(
891          &index.interner,
892          &index.versions.dependencies[chosen_ver_idx],
893        );
894
895        for dep in deps {
896          tracing::debug!(
897            "Found dependency of {:#?} for {:#?} mod",
898            dep,
899            index.resolve_name_at(pkg_idx).unwrap_or_default(),
900          );
901          sorted_set.insert(dep);
902        }
903      }
904
905      install_indices.push((pkg_idx, chosen_ver_idx));
906    }
907
908    let mut urls = HashMap::new();
909
910    for &(idx, chosen_ver_idx) in &install_indices {
911      if let Some((zip_name, url)) = Self::package_zip_and_url(index, idx, chosen_ver_idx) {
912        urls.insert(zip_name, url);
913      } else if let Some(name) = index
914        .resolve_full_name_at(idx)
915        .or_else(|| index.resolve_name_at(idx))
916      {
917        // Found in the index but with no downloadable version (no versions, or a
918        // version lacking a URL/version number): it is part of the desired set yet
919        // yields no download, so report it rather than dropping it silently.
920        tracing::warn!(
921          "package {:?} has no downloadable version; the install will be incomplete",
922          name
923        );
924        unresolved.push(name);
925      }
926    }
927
928    unresolved.sort();
929    unresolved.dedup();
930
931    Resolution { urls, unresolved }
932  }
933
934  /// Resolves one package index to its `(zip_filename, download_url)`, or `None`
935  /// when the package has no version that can be downloaded — it has no versions,
936  /// or its chosen version is missing a download URL or version number.
937  fn package_zip_and_url(
938    index: &PackageIndex,
939    idx: usize,
940    ver_idx: Option<usize>,
941  ) -> Option<(String, String)> {
942    let chosen_ver_idx = ver_idx?;
943    let url = resolve_option(
944      &index.interner,
945      index.versions.download_urls[chosen_ver_idx],
946    )?;
947    let version_number = resolve_option(
948      &index.interner,
949      index.versions.version_numbers[chosen_ver_idx],
950    )?;
951    let package_name = index.resolve_full_name_at(idx)?;
952    let zip_name = format!("{}-{}.zip", package_name, version_number);
953
954    Some((zip_name, url))
955  }
956}
957
958impl From<Vec<Package>> for PackageIndex {
959  fn from(packages: Vec<Package>) -> Self {
960    let num_packages = packages.len();
961    let total_versions: usize = packages.iter().map(|p| p.versions.len()).sum();
962
963    let mut interner = StringInterner::default();
964
965    let mut names = Vec::with_capacity(num_packages);
966    let mut full_names = Vec::with_capacity(num_packages);
967    let mut owners = Vec::with_capacity(num_packages);
968    let mut package_urls = Vec::with_capacity(num_packages);
969    let mut dates_created = Vec::with_capacity(num_packages);
970    let mut dates_updated = Vec::with_capacity(num_packages);
971    let mut uuid4s = Vec::with_capacity(num_packages);
972    let mut rating_scores = Vec::with_capacity(num_packages);
973    let mut is_pinned = Vec::with_capacity(num_packages);
974    let mut is_deprecated = Vec::with_capacity(num_packages);
975    let mut has_nsfw_content = Vec::with_capacity(num_packages);
976    let mut categories = Vec::with_capacity(num_packages);
977    let mut version_ranges = Vec::with_capacity(num_packages);
978
979    let mut package_indices = Vec::with_capacity(total_versions);
980    let mut version_names = Vec::with_capacity(total_versions);
981    let mut version_full_names = Vec::with_capacity(total_versions);
982    let mut version_numbers = Vec::with_capacity(total_versions);
983    let mut download_urls = Vec::with_capacity(total_versions);
984    let mut dependencies = Vec::with_capacity(total_versions);
985    let mut version_dates_created = Vec::with_capacity(total_versions);
986    let mut descriptions = Vec::with_capacity(total_versions);
987    let mut icons = Vec::with_capacity(total_versions);
988    let mut downloads = Vec::with_capacity(total_versions);
989    let mut website_urls = Vec::with_capacity(total_versions);
990    let mut is_active = Vec::with_capacity(total_versions);
991    let mut version_uuid4s = Vec::with_capacity(total_versions);
992    let mut file_sizes = Vec::with_capacity(total_versions);
993
994    let mut version_offset = 0;
995
996    for (pkg_idx, package) in packages.into_iter().enumerate() {
997      names.push(intern_option(&mut interner, package.name.as_deref()));
998      full_names.push(intern_option(&mut interner, package.full_name.as_deref()));
999      owners.push(intern_option(&mut interner, package.owner.as_deref()));
1000      package_urls.push(intern_option(&mut interner, package.package_url.as_deref()));
1001      dates_created.push(package.date_created);
1002      dates_updated.push(package.date_updated);
1003      uuid4s.push(intern_option(&mut interner, package.uuid4.as_deref()));
1004      rating_scores.push(package.rating_score);
1005      is_pinned.push(package.is_pinned);
1006      is_deprecated.push(package.is_deprecated);
1007      has_nsfw_content.push(package.has_nsfw_content);
1008      categories.push(intern_vec(&mut interner, &package.categories));
1009
1010      let version_count = package.versions.len();
1011      version_ranges.push((version_offset, version_offset + version_count));
1012
1013      for version in package.versions {
1014        package_indices.push(pkg_idx);
1015        version_names.push(intern_option(&mut interner, version.name.as_deref()));
1016        version_full_names.push(intern_option(&mut interner, version.full_name.as_deref()));
1017        version_numbers.push(intern_option(
1018          &mut interner,
1019          version.version_number.as_deref(),
1020        ));
1021        download_urls.push(intern_option(
1022          &mut interner,
1023          version.download_url.as_deref(),
1024        ));
1025        dependencies.push(intern_vec(&mut interner, &version.dependencies));
1026        version_dates_created.push(version.date_created);
1027        descriptions.push(intern_option(&mut interner, version.description.as_deref()));
1028        icons.push(intern_option(&mut interner, version.icon.as_deref()));
1029        downloads.push(version.downloads);
1030        website_urls.push(intern_option(&mut interner, version.website_url.as_deref()));
1031        is_active.push(version.is_active);
1032        version_uuid4s.push(intern_option(&mut interner, version.uuid4.as_deref()));
1033        file_sizes.push(version.file_size);
1034      }
1035
1036      version_offset += version_count;
1037    }
1038
1039    PackageIndex {
1040      interner,
1041      names,
1042      full_names,
1043      owners,
1044      package_urls,
1045      dates_created,
1046      dates_updated,
1047      uuid4s,
1048      rating_scores,
1049      is_pinned,
1050      is_deprecated,
1051      has_nsfw_content,
1052      categories,
1053      version_ranges,
1054      versions: VersionTable {
1055        package_indices,
1056        names: version_names,
1057        full_names: version_full_names,
1058        version_numbers,
1059        download_urls,
1060        dependencies,
1061        dates_created: version_dates_created,
1062        descriptions,
1063        icons,
1064        downloads,
1065        website_urls,
1066        is_active,
1067        uuid4s: version_uuid4s,
1068        file_sizes,
1069      },
1070      search: OnceLock::new(),
1071    }
1072  }
1073}
1074
1075/// Narrows an [`InternKey`] to the `u32` index the cache wire format stores.
1076///
1077/// `_interner` is unused and kept only so this mirrors the shape of its
1078/// resolving counterpart.
1079///
1080/// # Panics
1081///
1082/// Panics if the index exceeds `u32::MAX`, which needs roughly four billion
1083/// distinct interned strings. A silent truncation here would corrupt the string
1084/// table in release builds, so this fails loudly instead.
1085#[cfg(feature = "io")]
1086fn key_to_index(_interner: &StringInterner, key: InternKey) -> u32 {
1087  let index = key.to_index();
1088
1089  // The wire format stores keys as `u32`. A checked cast turns the (practically
1090  // unreachable, ~4 billion strings) overflow into a loud panic rather than a
1091  // silent truncation that would corrupt the string table in release builds.
1092  u32::try_from(index)
1093    .unwrap_or_else(|_| panic!("intern key index {index} exceeds u32 range and would truncate"))
1094}
1095
1096/// Converts a `u32` string-table index from a deserialized cache back into an
1097/// [`InternKey`], validating it against the rebuilt interner.
1098///
1099/// Returns an [`Error`] (rather than panicking) when the index is out of range
1100/// for the string table or otherwise not representable as a key, so a corrupt or
1101/// truncated cache file surfaces as a recoverable error.
1102#[cfg(feature = "io")]
1103fn decode_key(index: u32, table_len: usize) -> Result<InternKey, Error> {
1104  if index as usize >= table_len {
1105    return Err(Error::Cache(format!(
1106      "interned string index {} out of range (string table length {})",
1107      index, table_len
1108    )));
1109  }
1110
1111  InternKey::from_index(index as usize)
1112    .ok_or_else(|| Error::Cache(format!("invalid interned key index {}", index)))
1113}
1114
1115/// Encodes runtime timestamps to the cache's `i128` Unix-nanosecond wire form.
1116///
1117/// `time::OffsetDateTime` is not a native `bincode` type, so the cache stores each
1118/// timestamp as its absolute instant in nanoseconds since the Unix epoch. The
1119/// offset is not preserved, which is lossless for equality/ordering (both compare
1120/// the instant) and matches the UTC timestamps the Thunderstore API returns.
1121#[cfg(feature = "io")]
1122fn encode_dates(dates: &[OffsetDateTime]) -> Vec<i128> {
1123  dates.iter().map(|d| d.unix_timestamp_nanos()).collect()
1124}
1125
1126/// Decodes the cache's `i128` Unix-nanosecond timestamps back to `OffsetDateTime`
1127/// (as UTC), returning an [`Error`] rather than panicking if a crafted cache holds
1128/// an out-of-range value.
1129#[cfg(feature = "io")]
1130fn decode_dates(nanos: &[i128]) -> Result<Vec<OffsetDateTime>, Error> {
1131  nanos
1132    .iter()
1133    .map(|&n| {
1134      OffsetDateTime::from_unix_timestamp_nanos(n)
1135        .map_err(|e| Error::Cache(format!("invalid cached timestamp {}: {}", n, e)))
1136    })
1137    .collect()
1138}
1139
1140#[cfg(feature = "io")]
1141impl From<&PackageIndex> for SerializedPackageIndex {
1142  fn from(manifest: &PackageIndex) -> Self {
1143    let interner = &manifest.interner;
1144    let string_table: Vec<String> = interner.strings().map(|s| s.to_string()).collect();
1145
1146    // Symmetric with the `opt`/`nested` decode closures in `TryFrom`: fold the
1147    // otherwise ~14 identical key-column mappings to `u32` indices into one place.
1148    let opt = |keys: &[Option<InternKey>]| -> Vec<Option<u32>> {
1149      keys
1150        .iter()
1151        .map(|k| k.map(|key| key_to_index(interner, key)))
1152        .collect()
1153    };
1154
1155    let nested = |lists: &[Vec<InternKey>]| -> Vec<Vec<u32>> {
1156      lists
1157        .iter()
1158        .map(|keys| keys.iter().map(|k| key_to_index(interner, *k)).collect())
1159        .collect()
1160    };
1161
1162    SerializedPackageIndex {
1163      format_version: CACHE_FORMAT_VERSION,
1164      string_table,
1165      names: opt(&manifest.names),
1166      full_names: opt(&manifest.full_names),
1167      owners: opt(&manifest.owners),
1168      package_urls: opt(&manifest.package_urls),
1169      dates_created: encode_dates(&manifest.dates_created),
1170      dates_updated: encode_dates(&manifest.dates_updated),
1171      uuid4s: opt(&manifest.uuid4s),
1172      rating_scores: manifest.rating_scores.clone(),
1173      is_pinned: manifest.is_pinned.clone(),
1174      is_deprecated: manifest.is_deprecated.clone(),
1175      has_nsfw_content: manifest.has_nsfw_content.clone(),
1176      categories: nested(&manifest.categories),
1177      version_ranges: manifest.version_ranges.clone(),
1178      versions: SerializedVersionTable {
1179        package_indices: manifest.versions.package_indices.clone(),
1180        names: opt(&manifest.versions.names),
1181        full_names: opt(&manifest.versions.full_names),
1182        version_numbers: opt(&manifest.versions.version_numbers),
1183        download_urls: opt(&manifest.versions.download_urls),
1184        dependencies: nested(&manifest.versions.dependencies),
1185        dates_created: encode_dates(&manifest.versions.dates_created),
1186        descriptions: opt(&manifest.versions.descriptions),
1187        icons: opt(&manifest.versions.icons),
1188        downloads: manifest.versions.downloads.clone(),
1189        website_urls: opt(&manifest.versions.website_urls),
1190        is_active: manifest.versions.is_active.clone(),
1191        uuid4s: opt(&manifest.versions.uuid4s),
1192        file_sizes: manifest.versions.file_sizes.clone(),
1193      },
1194    }
1195  }
1196}
1197
1198#[cfg(feature = "io")]
1199impl TryFrom<SerializedPackageIndex> for PackageIndex {
1200  type Error = Error;
1201
1202  /// Rebuilds the runtime index from its serialized form, validating every
1203  /// string-table index and the structural invariants (via [`PackageIndex::validate`])
1204  /// so a corrupt or malicious cache yields an [`Error`] instead of a panic.
1205  fn try_from(manifest: SerializedPackageIndex) -> Result<Self, Self::Error> {
1206    if manifest.format_version != CACHE_FORMAT_VERSION {
1207      return Err(Error::UnsupportedCacheVersion {
1208        found: manifest.format_version,
1209        expected: CACHE_FORMAT_VERSION,
1210      });
1211    }
1212
1213    let mut interner = StringInterner::default();
1214
1215    for s in &manifest.string_table {
1216      interner.get_or_intern(s);
1217    }
1218
1219    let table_len = manifest.string_table.len();
1220
1221    // The decode below relies on each string-table index mapping 1:1 to an
1222    // interner key (index `i` -> key `i`). `get_or_intern` deduplicates, so a
1223    // table with duplicate (or otherwise non-unique) entries yields a smaller
1224    // interner; an index that passes `decode_key`'s range check would then
1225    // dangle past the interner and panic later in `resolve`. Reject such a
1226    // table here so a corrupt or malicious cache surfaces as a recoverable
1227    // error rather than a panic.
1228    if interner.len() != table_len {
1229      return Err(Error::Cache(
1230        "cache string table contains duplicate or unresolvable entries".to_string(),
1231      ));
1232    }
1233
1234    let opt = |v: &[Option<u32>]| -> Result<Vec<Option<InternKey>>, Error> {
1235      v.iter()
1236        .map(|idx| idx.map(|i| decode_key(i, table_len)).transpose())
1237        .collect()
1238    };
1239
1240    let nested = |v: &[Vec<u32>]| -> Result<Vec<Vec<InternKey>>, Error> {
1241      v.iter()
1242        .map(|indices| indices.iter().map(|&i| decode_key(i, table_len)).collect())
1243        .collect()
1244    };
1245
1246    let names = opt(&manifest.names)?;
1247    let full_names = opt(&manifest.full_names)?;
1248    let owners = opt(&manifest.owners)?;
1249    let package_urls = opt(&manifest.package_urls)?;
1250    let uuid4s = opt(&manifest.uuid4s)?;
1251    let categories = nested(&manifest.categories)?;
1252
1253    let version_names = opt(&manifest.versions.names)?;
1254    let version_full_names = opt(&manifest.versions.full_names)?;
1255    let version_numbers = opt(&manifest.versions.version_numbers)?;
1256    let download_urls = opt(&manifest.versions.download_urls)?;
1257    let dependencies = nested(&manifest.versions.dependencies)?;
1258    let descriptions = opt(&manifest.versions.descriptions)?;
1259    let icons = opt(&manifest.versions.icons)?;
1260    let website_urls = opt(&manifest.versions.website_urls)?;
1261    let version_uuid4s = opt(&manifest.versions.uuid4s)?;
1262
1263    let dates_created = decode_dates(&manifest.dates_created)?;
1264    let dates_updated = decode_dates(&manifest.dates_updated)?;
1265    let version_dates_created = decode_dates(&manifest.versions.dates_created)?;
1266
1267    let result = PackageIndex {
1268      interner,
1269      names,
1270      full_names,
1271      owners,
1272      package_urls,
1273      dates_created,
1274      dates_updated,
1275      uuid4s,
1276      rating_scores: manifest.rating_scores,
1277      is_pinned: manifest.is_pinned,
1278      is_deprecated: manifest.is_deprecated,
1279      has_nsfw_content: manifest.has_nsfw_content,
1280      categories,
1281      version_ranges: manifest.version_ranges,
1282      versions: VersionTable {
1283        package_indices: manifest.versions.package_indices,
1284        names: version_names,
1285        full_names: version_full_names,
1286        version_numbers,
1287        download_urls,
1288        dependencies,
1289        dates_created: version_dates_created,
1290        descriptions,
1291        icons,
1292        downloads: manifest.versions.downloads,
1293        website_urls,
1294        is_active: manifest.versions.is_active,
1295        uuid4s: version_uuid4s,
1296        file_sizes: manifest.versions.file_sizes,
1297      },
1298      search: OnceLock::new(),
1299    };
1300
1301    result.validate()?;
1302
1303    Ok(result)
1304  }
1305}
1306
1307#[cfg(test)]
1308mod tests {
1309  use super::*;
1310  use time::OffsetDateTime;
1311
1312  fn create_test_package(name: &str, owner: &str, version: &str) -> Package {
1313    let full_name = format!("{}-{}", owner, name);
1314    Package {
1315      name: Some(name.to_string()),
1316      full_name: Some(full_name.clone()),
1317      owner: Some(owner.to_string()),
1318      package_url: Some(format!("https://example.com/{}", name)),
1319      date_created: OffsetDateTime::now_utc(),
1320      date_updated: OffsetDateTime::now_utc(),
1321      uuid4: Some("test-uuid".to_string()),
1322      rating_score: Some(5),
1323      is_pinned: Some(false),
1324      is_deprecated: Some(false),
1325      has_nsfw_content: Some(false),
1326      categories: vec!["category1".to_string()],
1327      versions: vec![Version {
1328        name: Some(name.to_string()),
1329        full_name: Some(full_name.clone()),
1330        description: Some("Test description".to_string()),
1331        icon: Some("icon.png".to_string()),
1332        version_number: Some(version.to_string()),
1333        dependencies: vec![],
1334        download_url: Some(format!("https://example.com/{}/download", name)),
1335        downloads: Some(100),
1336        date_created: OffsetDateTime::now_utc(),
1337        website_url: Some("https://example.com".to_string()),
1338        is_active: Some(true),
1339        uuid4: Some("test-version-uuid".to_string()),
1340        file_size: Some(1024),
1341      }],
1342    }
1343  }
1344
1345  fn create_test_package_with_dependencies(
1346    name: &str,
1347    owner: &str,
1348    version: &str,
1349    dependencies: Vec<String>,
1350  ) -> Package {
1351    let mut pkg = create_test_package(name, owner, version);
1352
1353    if let Some(latest_version) = pkg.versions.first_mut() {
1354      latest_version.dependencies = dependencies;
1355    }
1356
1357    pkg
1358  }
1359
1360  #[test]
1361  fn test_latest_version() {
1362    let mut pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1363
1364    let older_version = Version {
1365      name: Some("TestMod".to_string()),
1366      full_name: Some("TestOwner-TestMod".to_string()),
1367      description: Some("Older version".to_string()),
1368      icon: Some("icon.png".to_string()),
1369      version_number: Some("0.9.0".to_string()),
1370      dependencies: vec![],
1371      download_url: Some("https://example.com/TestMod/download-old".to_string()),
1372      downloads: Some(50),
1373      date_created: OffsetDateTime::now_utc().saturating_sub(time::Duration::days(30)),
1374      website_url: Some("https://example.com".to_string()),
1375      is_active: Some(true),
1376      uuid4: Some("old-version-uuid".to_string()),
1377      file_size: Some(512),
1378    };
1379    pkg.versions.push(older_version);
1380
1381    let newer_version = Version {
1382      name: Some("TestMod".to_string()),
1383      full_name: Some("TestOwner-TestMod".to_string()),
1384      description: Some("Newer version".to_string()),
1385      icon: Some("icon.png".to_string()),
1386      version_number: Some("1.1.0".to_string()),
1387      dependencies: vec![],
1388      download_url: Some("https://example.com/TestMod/download-new".to_string()),
1389      downloads: Some(150),
1390      date_created: OffsetDateTime::now_utc().saturating_add(time::Duration::days(30)),
1391      website_url: Some("https://example.com".to_string()),
1392      is_active: Some(true),
1393      uuid4: Some("new-version-uuid".to_string()),
1394      file_size: Some(2048),
1395    };
1396    pkg.versions.push(newer_version);
1397
1398    let latest = pkg.latest_version().unwrap();
1399    assert_eq!(latest.version_number, Some("1.1.0".to_string()));
1400    assert_eq!(latest.description, Some("Newer version".to_string()));
1401  }
1402
1403  #[test]
1404  fn test_zip_and_url() {
1405    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1406    let (filename, url) = pkg.zip_and_url().unwrap();
1407
1408    assert_eq!(filename, "TestOwner-TestMod-1.0.0.zip");
1409    assert_eq!(url, "https://example.com/TestMod/download");
1410  }
1411
1412  #[test]
1413  fn test_zip_and_url_missing_data() {
1414    let mut pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1415
1416    if let Some(version) = pkg.versions.first_mut() {
1417      version.version_number = None;
1418    }
1419
1420    assert!(pkg.zip_and_url().is_none());
1421
1422    let mut pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1423
1424    if let Some(version) = pkg.versions.first_mut() {
1425      version.download_url = None;
1426    }
1427
1428    assert!(pkg.zip_and_url().is_none());
1429
1430    let mut pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1431    pkg.full_name = None;
1432
1433    assert!(pkg.zip_and_url().is_none());
1434  }
1435
1436  #[test]
1437  fn test_package_debug() {
1438    let pkg = create_test_package("ModTest", "OwnerTest", "1.2.3");
1439    let debug_output = format!("{:?}", pkg);
1440
1441    assert!(debug_output.contains("Package"));
1442    assert!(debug_output.contains("full_name: Some(\"OwnerTest-ModTest\")"));
1443    assert!(debug_output.contains("dependencies: Some([])"));
1444    assert!(
1445      debug_output.contains("download_url: Some(Some(\"https://example.com/ModTest/download\"))")
1446    );
1447
1448    let mut pkg_with_deps = create_test_package_with_dependencies(
1449      "ModWithDeps",
1450      "OwnerTest",
1451      "2.0.0",
1452      vec!["Dep1-Mod1".to_string(), "Dep2-Mod2".to_string()],
1453    );
1454    let debug_with_deps = format!("{:?}", pkg_with_deps);
1455
1456    assert!(debug_with_deps.contains("dependencies: Some([\"Dep1-Mod1\", \"Dep2-Mod2\"])"));
1457
1458    pkg_with_deps.full_name = None;
1459    let debug_missing_name = format!("{:?}", pkg_with_deps);
1460    assert!(debug_missing_name.contains("full_name: None"));
1461
1462    let mut pkg_no_version = create_test_package("NoVersion", "TestOwner", "1.0.0");
1463    pkg_no_version.versions.clear();
1464    let debug_no_version = format!("{:?}", pkg_no_version);
1465
1466    assert!(debug_no_version.contains("dependencies: None"));
1467    assert!(debug_no_version.contains("download_url: None"));
1468  }
1469
1470  #[test]
1471  fn test_package_index_basic_operations() {
1472    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1473    let packages = vec![pkg];
1474    let interned: PackageIndex = packages.into();
1475
1476    assert_eq!(interned.len(), 1);
1477
1478    assert!(!interned.is_empty());
1479
1480    assert_eq!(interned.resolve_name_at(0), Some("TestMod".to_string()));
1481
1482    assert_eq!(
1483      interned.resolve_full_name_at(0),
1484      Some("TestOwner-TestMod".to_string())
1485    );
1486
1487    assert_eq!(interned.resolve_owner_at(0), Some("TestOwner".to_string()));
1488  }
1489
1490  #[test]
1491  fn search_matches_name_and_full_name_case_insensitively() {
1492    let packages = vec![
1493      create_test_package("CoolMod", "Author", "1.0.0"),
1494      create_test_package("OtherThing", "Someone", "1.0.0"),
1495    ];
1496    let index: PackageIndex = packages.into();
1497
1498    // Matches on the short name, ignoring case.
1499    assert_eq!(index.search("coolmod"), vec![0]);
1500    assert_eq!(index.search("COOLMOD"), vec![0]);
1501    // Matches on the owner-qualified full name too.
1502    assert_eq!(index.search("author-cool"), vec![0]);
1503    // A substring anywhere counts.
1504    assert_eq!(index.search("oolMo"), vec![0]);
1505    // No match is an empty result, not an error.
1506    assert!(index.search("nothing-like-this").is_empty());
1507    // An empty term matches everything, so clearing a search box shows the full
1508    // list rather than nothing.
1509    assert_eq!(index.search(""), vec![0, 1]);
1510  }
1511
1512  #[test]
1513  fn test_package_index_borrowing_accessors() {
1514    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1515    let packages = vec![pkg];
1516    let interned: PackageIndex = packages.into();
1517
1518    // The borrowing accessors return the same values as their allocating
1519    // counterparts, and yield None for an out-of-range index.
1520    assert_eq!(interned.name_at(0), Some("TestMod"));
1521
1522    assert_eq!(interned.full_name_at(0), Some("TestOwner-TestMod"));
1523
1524    assert_eq!(interned.owner_at(0), Some("TestOwner"));
1525
1526    assert_eq!(interned.name_at(1), None);
1527
1528    assert_eq!(interned.full_name_at(1), None);
1529
1530    assert_eq!(interned.owner_at(1), None);
1531  }
1532
1533  #[test]
1534  fn test_package_index_get_package_by_full_name() {
1535    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1536    let packages = vec![pkg];
1537    let interned: PackageIndex = packages.into();
1538
1539    let found = interned.get_package_by_full_name("TestOwner-TestMod");
1540
1541    assert!(found.is_some());
1542
1543    let package = found.unwrap();
1544
1545    assert_eq!(package.name, Some("TestMod".to_string()));
1546
1547    assert_eq!(package.owner, Some("TestOwner".to_string()));
1548
1549    assert_eq!(package.versions.len(), 1);
1550  }
1551
1552  #[test]
1553  fn test_package_index_find_index_by_full_name() {
1554    let pkg1 = create_test_package("ModA", "Owner1", "1.0.0");
1555    let pkg2 = create_test_package("ModB", "Owner2", "2.0.0");
1556    let packages = vec![pkg1, pkg2];
1557    let interned: PackageIndex = packages.into();
1558
1559    assert_eq!(interned.find_index_by_full_name("Owner1-ModA"), Some(0));
1560
1561    assert_eq!(interned.find_index_by_full_name("Owner2-ModB"), Some(1));
1562
1563    assert_eq!(interned.find_index_by_full_name("NonExistent"), None);
1564  }
1565
1566  #[test]
1567  fn test_package_index_get_package_at() {
1568    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1569    let packages = vec![pkg];
1570    let interned: PackageIndex = packages.into();
1571
1572    let package = interned.get_package_at(0).unwrap();
1573
1574    assert_eq!(package.name, Some("TestMod".to_string()));
1575
1576    assert_eq!(package.full_name, Some("TestOwner-TestMod".to_string()));
1577
1578    assert_eq!(package.owner, Some("TestOwner".to_string()));
1579
1580    assert_eq!(package.versions.len(), 1);
1581
1582    assert_eq!(
1583      package.versions[0].version_number,
1584      Some("1.0.0".to_string())
1585    );
1586  }
1587
1588  #[test]
1589  fn test_package_index_get_latest_version_at() {
1590    let mut pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1591
1592    let older_version = Version {
1593      name: Some("TestMod".to_string()),
1594      full_name: Some("TestOwner-TestMod".to_string()),
1595      description: Some("Older version".to_string()),
1596      icon: Some("icon.png".to_string()),
1597      version_number: Some("0.9.0".to_string()),
1598      dependencies: vec![],
1599      download_url: Some("https://example.com/TestMod/download-old".to_string()),
1600      downloads: Some(50),
1601      date_created: OffsetDateTime::now_utc().saturating_sub(time::Duration::days(30)),
1602      website_url: Some("https://example.com".to_string()),
1603      is_active: Some(true),
1604      uuid4: Some("old-version-uuid".to_string()),
1605      file_size: Some(512),
1606    };
1607    pkg.versions.insert(0, older_version);
1608
1609    let packages = vec![pkg];
1610    let interned: PackageIndex = packages.into();
1611
1612    let latest_idx = interned.get_latest_version_at(0);
1613
1614    assert!(latest_idx.is_some());
1615
1616    let version_idx = latest_idx.unwrap();
1617    let version_number = interned.versions.version_numbers[version_idx]
1618      .map(|key| interned.interner.resolve(&key).to_string());
1619
1620    assert_eq!(version_number, Some("1.0.0".to_string()));
1621  }
1622
1623  #[test]
1624  fn test_package_index_get_latest_version_at_empty_range() {
1625    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1626    let packages = vec![pkg];
1627    let mut interned: PackageIndex = packages.into();
1628
1629    interned.version_ranges[0] = (0, 0);
1630
1631    let latest = interned.get_latest_version_at(0);
1632
1633    assert!(latest.is_none());
1634  }
1635
1636  #[test]
1637  fn test_package_index_build_name_index() {
1638    let pkg1 = create_test_package("ModA", "Owner1", "1.0.0");
1639    let pkg2 = create_test_package("ModB", "Owner2", "2.0.0");
1640    let packages = vec![pkg1, pkg2];
1641    let interned: PackageIndex = packages.into();
1642
1643    let index = interned.build_name_index();
1644
1645    assert_eq!(index.len(), 2);
1646
1647    assert_eq!(index.get("Owner1-ModA"), Some(&0));
1648
1649    assert_eq!(index.get("Owner2-ModB"), Some(&1));
1650  }
1651
1652  #[test]
1653  fn test_package_index_validate_valid() {
1654    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1655    let packages = vec![pkg];
1656    let interned: PackageIndex = packages.into();
1657
1658    let result = interned.validate();
1659
1660    assert!(result.is_ok());
1661  }
1662
1663  #[test]
1664  fn validate_split_methods_are_individually_callable() {
1665    let interned: PackageIndex = vec![create_test_package("ModA", "Owner1", "1.0.0")].into();
1666
1667    // All four checks pass on a well-formed index.
1668    assert!(interned.validate_lengths().is_ok());
1669    assert!(interned.validate_version_ranges().is_ok());
1670    assert!(interned.validate_version_ownership().is_ok());
1671    assert!(interned.validate_unique_full_names().is_ok());
1672
1673    // A parallel-vector length mismatch is caught specifically by validate_lengths.
1674    let mut broken: PackageIndex = vec![create_test_package("ModA", "Owner1", "1.0.0")].into();
1675    broken.owners.pop();
1676    assert!(broken.validate_lengths().is_err());
1677
1678    // A repeated full name is caught specifically by validate_unique_full_names.
1679    let dup: PackageIndex = vec![
1680      create_test_package("ModA", "Owner1", "1.0.0"),
1681      create_test_package("ModA", "Owner1", "2.0.0"),
1682    ]
1683    .into();
1684    assert!(dup.validate_unique_full_names().is_err());
1685  }
1686
1687  #[test]
1688  #[cfg(feature = "io")]
1689  fn encode_decode_dates_roundtrips_and_rejects_out_of_range() {
1690    let dates = vec![
1691      OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
1692      OffsetDateTime::from_unix_timestamp(0).unwrap(),
1693    ];
1694
1695    let encoded = encode_dates(&dates);
1696    let decoded = decode_dates(&encoded).unwrap();
1697
1698    assert_eq!(decoded, dates);
1699
1700    // An i128 nanosecond value beyond the representable range is a recoverable
1701    // error, not a panic.
1702    let err = decode_dates(&[i128::MAX]).unwrap_err();
1703
1704    assert!(matches!(err, Error::Cache(_)));
1705  }
1706
1707  #[test]
1708  fn from_packages_populates_core_fields() {
1709    let interned: PackageIndex = vec![create_test_package("ModA", "Owner1", "1.0.0")].into();
1710
1711    assert_eq!(interned.len(), 1);
1712    assert_eq!(
1713      interned.resolve_full_name_at(0),
1714      Some("Owner1-ModA".to_string())
1715    );
1716
1717    // A single package with one version yields one range covering that version,
1718    // and the version records package index 0 as its owner.
1719    assert_eq!(interned.version_ranges, vec![(0, 1)]);
1720    assert_eq!(interned.versions.package_indices, vec![0]);
1721  }
1722
1723  #[test]
1724  fn test_package_index_validate_mismatched_full_names_length() {
1725    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1726    let packages = vec![pkg];
1727    let mut interned: PackageIndex = packages.into();
1728
1729    interned.full_names.pop();
1730
1731    let result = interned.validate();
1732
1733    assert!(result.is_err());
1734
1735    assert!(
1736      result
1737        .unwrap_err()
1738        .to_string()
1739        .contains("full_names length")
1740    );
1741  }
1742
1743  #[test]
1744  fn test_package_index_validate_mismatched_owners_length() {
1745    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1746    let packages = vec![pkg];
1747    let mut interned: PackageIndex = packages.into();
1748
1749    interned.owners.pop();
1750
1751    let result = interned.validate();
1752
1753    assert!(result.is_err());
1754
1755    assert!(result.unwrap_err().to_string().contains("owners length"));
1756  }
1757
1758  #[test]
1759  fn test_package_index_validate_mismatched_package_urls_length() {
1760    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1761    let packages = vec![pkg];
1762    let mut interned: PackageIndex = packages.into();
1763
1764    interned.package_urls.pop();
1765
1766    let result = interned.validate();
1767
1768    assert!(result.is_err());
1769
1770    assert!(
1771      result
1772        .unwrap_err()
1773        .to_string()
1774        .contains("package_urls length")
1775    );
1776  }
1777
1778  #[test]
1779  fn test_package_index_validate_mismatched_dates_created_length() {
1780    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1781    let packages = vec![pkg];
1782    let mut interned: PackageIndex = packages.into();
1783
1784    interned.dates_created.pop();
1785
1786    let result = interned.validate();
1787
1788    assert!(result.is_err());
1789
1790    assert!(
1791      result
1792        .unwrap_err()
1793        .to_string()
1794        .contains("dates_created length")
1795    );
1796  }
1797
1798  #[test]
1799  fn test_package_index_validate_mismatched_dates_updated_length() {
1800    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1801    let packages = vec![pkg];
1802    let mut interned: PackageIndex = packages.into();
1803
1804    interned.dates_updated.pop();
1805
1806    let result = interned.validate();
1807
1808    assert!(result.is_err());
1809
1810    assert!(
1811      result
1812        .unwrap_err()
1813        .to_string()
1814        .contains("dates_updated length")
1815    );
1816  }
1817
1818  #[test]
1819  fn test_package_index_validate_mismatched_uuid4s_length() {
1820    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1821    let packages = vec![pkg];
1822    let mut interned: PackageIndex = packages.into();
1823
1824    interned.uuid4s.pop();
1825
1826    let result = interned.validate();
1827
1828    assert!(result.is_err());
1829
1830    assert!(result.unwrap_err().to_string().contains("uuid4s length"));
1831  }
1832
1833  #[test]
1834  fn test_package_index_validate_mismatched_rating_scores_length() {
1835    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1836    let packages = vec![pkg];
1837    let mut interned: PackageIndex = packages.into();
1838
1839    interned.rating_scores.pop();
1840
1841    let result = interned.validate();
1842
1843    assert!(result.is_err());
1844
1845    assert!(
1846      result
1847        .unwrap_err()
1848        .to_string()
1849        .contains("rating_scores length")
1850    );
1851  }
1852
1853  #[test]
1854  fn test_package_index_validate_mismatched_is_pinned_length() {
1855    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1856    let packages = vec![pkg];
1857    let mut interned: PackageIndex = packages.into();
1858
1859    interned.is_pinned.pop();
1860
1861    let result = interned.validate();
1862
1863    assert!(result.is_err());
1864
1865    assert!(result.unwrap_err().to_string().contains("is_pinned length"));
1866  }
1867
1868  #[test]
1869  fn test_package_index_validate_mismatched_is_deprecated_length() {
1870    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1871    let packages = vec![pkg];
1872    let mut interned: PackageIndex = packages.into();
1873
1874    interned.is_deprecated.pop();
1875
1876    let result = interned.validate();
1877
1878    assert!(result.is_err());
1879
1880    assert!(
1881      result
1882        .unwrap_err()
1883        .to_string()
1884        .contains("is_deprecated length")
1885    );
1886  }
1887
1888  #[test]
1889  fn test_package_index_validate_mismatched_has_nsfw_content_length() {
1890    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1891    let packages = vec![pkg];
1892    let mut interned: PackageIndex = packages.into();
1893
1894    interned.has_nsfw_content.pop();
1895
1896    let result = interned.validate();
1897
1898    assert!(result.is_err());
1899
1900    assert!(
1901      result
1902        .unwrap_err()
1903        .to_string()
1904        .contains("has_nsfw_content length")
1905    );
1906  }
1907
1908  #[test]
1909  fn test_package_index_validate_mismatched_categories_length() {
1910    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1911    let packages = vec![pkg];
1912    let mut interned: PackageIndex = packages.into();
1913
1914    interned.categories.pop();
1915
1916    let result = interned.validate();
1917
1918    assert!(result.is_err());
1919
1920    assert!(
1921      result
1922        .unwrap_err()
1923        .to_string()
1924        .contains("categories length")
1925    );
1926  }
1927
1928  #[test]
1929  fn test_package_index_validate_mismatched_version_ranges_length() {
1930    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1931    let packages = vec![pkg];
1932    let mut interned: PackageIndex = packages.into();
1933
1934    interned.version_ranges.pop();
1935
1936    let result = interned.validate();
1937
1938    assert!(result.is_err());
1939
1940    assert!(
1941      result
1942        .unwrap_err()
1943        .to_string()
1944        .contains("version_ranges length")
1945    );
1946  }
1947
1948  #[test]
1949  fn test_package_index_validate_mismatched_version_numbers_length() {
1950    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1951    let packages = vec![pkg];
1952    let mut interned: PackageIndex = packages.into();
1953
1954    interned.versions.version_numbers.pop();
1955
1956    let result = interned.validate();
1957
1958    assert!(result.is_err());
1959
1960    assert!(
1961      result
1962        .unwrap_err()
1963        .to_string()
1964        .contains("version_numbers length")
1965    );
1966  }
1967
1968  #[test]
1969  fn test_package_index_validate_mismatched_version_download_urls_length() {
1970    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1971    let packages = vec![pkg];
1972    let mut interned: PackageIndex = packages.into();
1973
1974    interned.versions.download_urls.pop();
1975
1976    let result = interned.validate();
1977
1978    assert!(result.is_err());
1979
1980    assert!(
1981      result
1982        .unwrap_err()
1983        .to_string()
1984        .contains("download_urls length")
1985    );
1986  }
1987
1988  #[test]
1989  fn test_package_index_validate_mismatched_version_dependencies_length() {
1990    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
1991    let packages = vec![pkg];
1992    let mut interned: PackageIndex = packages.into();
1993
1994    interned.versions.dependencies.pop();
1995
1996    let result = interned.validate();
1997
1998    assert!(result.is_err());
1999
2000    assert!(
2001      result
2002        .unwrap_err()
2003        .to_string()
2004        .contains("dependencies length")
2005    );
2006  }
2007
2008  #[test]
2009  fn test_package_index_validate_mismatched_version_dates_created_length() {
2010    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2011    let packages = vec![pkg];
2012    let mut interned: PackageIndex = packages.into();
2013
2014    interned.versions.dates_created.pop();
2015
2016    let result = interned.validate();
2017
2018    assert!(result.is_err());
2019
2020    assert!(
2021      result
2022        .unwrap_err()
2023        .to_string()
2024        .contains("dates_created length")
2025    );
2026  }
2027
2028  #[test]
2029  fn test_package_index_validate_mismatched_version_descriptions_length() {
2030    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2031    let packages = vec![pkg];
2032    let mut interned: PackageIndex = packages.into();
2033
2034    interned.versions.descriptions.pop();
2035
2036    let result = interned.validate();
2037
2038    assert!(result.is_err());
2039
2040    assert!(
2041      result
2042        .unwrap_err()
2043        .to_string()
2044        .contains("descriptions length")
2045    );
2046  }
2047
2048  #[test]
2049  fn test_package_index_validate_mismatched_version_icons_length() {
2050    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2051    let packages = vec![pkg];
2052    let mut interned: PackageIndex = packages.into();
2053
2054    interned.versions.icons.pop();
2055
2056    let result = interned.validate();
2057
2058    assert!(result.is_err());
2059
2060    assert!(result.unwrap_err().to_string().contains("icons length"));
2061  }
2062
2063  #[test]
2064  fn test_package_index_validate_mismatched_version_downloads_length() {
2065    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2066    let packages = vec![pkg];
2067    let mut interned: PackageIndex = packages.into();
2068
2069    interned.versions.downloads.pop();
2070
2071    let result = interned.validate();
2072
2073    assert!(result.is_err());
2074
2075    assert!(result.unwrap_err().to_string().contains("downloads length"));
2076  }
2077
2078  #[test]
2079  fn test_package_index_validate_mismatched_version_website_urls_length() {
2080    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2081    let packages = vec![pkg];
2082    let mut interned: PackageIndex = packages.into();
2083
2084    interned.versions.website_urls.pop();
2085
2086    let result = interned.validate();
2087
2088    assert!(result.is_err());
2089
2090    assert!(
2091      result
2092        .unwrap_err()
2093        .to_string()
2094        .contains("website_urls length")
2095    );
2096  }
2097
2098  #[test]
2099  fn test_package_index_validate_mismatched_version_is_active_length() {
2100    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2101    let packages = vec![pkg];
2102    let mut interned: PackageIndex = packages.into();
2103
2104    interned.versions.is_active.pop();
2105
2106    let result = interned.validate();
2107
2108    assert!(result.is_err());
2109
2110    assert!(result.unwrap_err().to_string().contains("is_active length"));
2111  }
2112
2113  #[test]
2114  fn test_package_index_validate_mismatched_version_uuid4s_length() {
2115    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2116    let packages = vec![pkg];
2117    let mut interned: PackageIndex = packages.into();
2118
2119    interned.versions.uuid4s.pop();
2120
2121    let result = interned.validate();
2122
2123    assert!(result.is_err());
2124
2125    assert!(result.unwrap_err().to_string().contains("uuid4s length"));
2126  }
2127
2128  #[test]
2129  fn test_package_index_validate_mismatched_version_file_sizes_length() {
2130    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2131    let packages = vec![pkg];
2132    let mut interned: PackageIndex = packages.into();
2133
2134    interned.versions.file_sizes.pop();
2135
2136    let result = interned.validate();
2137
2138    assert!(result.is_err());
2139
2140    assert!(
2141      result
2142        .unwrap_err()
2143        .to_string()
2144        .contains("file_sizes length")
2145    );
2146  }
2147
2148  #[test]
2149  fn test_package_index_validate_invalid_version_range() {
2150    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2151    let packages = vec![pkg];
2152    let mut interned: PackageIndex = packages.into();
2153
2154    interned.version_ranges[0] = (5, 3);
2155
2156    let result = interned.validate();
2157
2158    assert!(result.is_err());
2159
2160    assert!(
2161      result
2162        .unwrap_err()
2163        .to_string()
2164        .contains("Invalid version range")
2165    );
2166  }
2167
2168  #[test]
2169  fn test_package_index_validate_version_range_out_of_bounds() {
2170    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2171    let packages = vec![pkg];
2172    let mut interned: PackageIndex = packages.into();
2173
2174    interned.version_ranges[0] = (0, 999);
2175
2176    let result = interned.validate();
2177
2178    assert!(result.is_err());
2179
2180    assert!(result.unwrap_err().to_string().contains("ends at"));
2181  }
2182
2183  #[test]
2184  #[cfg(feature = "io")]
2185  fn test_package_index_serialization_round_trip() {
2186    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2187    let packages = vec![pkg.clone()];
2188    let interned: PackageIndex = packages.into();
2189
2190    let serializable: SerializedPackageIndex = (&interned).into();
2191
2192    let binary = bincode::encode_to_vec(&serializable, bincode::config::standard()).unwrap();
2193
2194    let (deserialized, _): (SerializedPackageIndex, usize) =
2195      bincode::decode_from_slice(&binary, bincode::config::standard()).unwrap();
2196
2197    let recovered: PackageIndex = deserialized.try_into().unwrap();
2198
2199    assert_eq!(recovered.len(), 1);
2200
2201    assert_eq!(recovered.resolve_name_at(0), Some("TestMod".to_string()));
2202
2203    assert_eq!(
2204      recovered.resolve_full_name_at(0),
2205      Some("TestOwner-TestMod".to_string())
2206    );
2207
2208    let recovered_pkg = recovered.get_package_at(0).unwrap();
2209
2210    assert_eq!(recovered_pkg.name, pkg.name);
2211
2212    assert_eq!(recovered_pkg.full_name, pkg.full_name);
2213
2214    assert_eq!(recovered_pkg.versions.len(), pkg.versions.len());
2215  }
2216
2217  #[test]
2218  #[cfg(feature = "io")]
2219  fn test_version_name_and_full_name_are_version_level_not_package_level() {
2220    // Real Thunderstore data: a version's full_name carries the version suffix,
2221    // distinct from the package's own full_name.
2222    let mut pkg = create_test_package("CoolMod", "Author", "1.0.0");
2223    pkg.name = Some("CoolMod".to_string());
2224    pkg.full_name = Some("Author-CoolMod".to_string());
2225    pkg.versions[0].name = Some("Author-CoolMod".to_string());
2226    pkg.versions[0].full_name = Some("Author-CoolMod-1.0.0".to_string());
2227
2228    let interned: PackageIndex = vec![pkg].into();
2229
2230    // Materialized directly, the version keeps its own name/full_name rather than
2231    // inheriting the package's.
2232    let materialized = interned.get_package_at(0).unwrap();
2233
2234    assert_eq!(materialized.full_name, Some("Author-CoolMod".to_string()));
2235
2236    assert_eq!(
2237      materialized.versions[0].full_name,
2238      Some("Author-CoolMod-1.0.0".to_string())
2239    );
2240
2241    assert_eq!(
2242      materialized.versions[0].name,
2243      Some("Author-CoolMod".to_string())
2244    );
2245
2246    // The distinction also survives a serialize -> deserialize round trip.
2247    let serializable: SerializedPackageIndex = (&interned).into();
2248
2249    let binary = bincode::encode_to_vec(&serializable, bincode::config::standard()).unwrap();
2250
2251    let (deserialized, _): (SerializedPackageIndex, usize) =
2252      bincode::decode_from_slice(&binary, bincode::config::standard()).unwrap();
2253
2254    let recovered: PackageIndex = deserialized.try_into().unwrap();
2255    let recovered_pkg = recovered.get_package_at(0).unwrap();
2256
2257    assert_eq!(recovered_pkg.full_name, Some("Author-CoolMod".to_string()));
2258
2259    assert_eq!(
2260      recovered_pkg.versions[0].full_name,
2261      Some("Author-CoolMod-1.0.0".to_string())
2262    );
2263  }
2264
2265  #[test]
2266  fn test_resolve_report_lists_unresolved_packages() {
2267    let interned: PackageIndex = vec![create_test_package("ModA", "Owner1", "1.0.0")].into();
2268
2269    let graph = DependencyGraph::new(vec!["Owner1-ModA".to_string(), "Ghost-Missing".to_string()]);
2270
2271    let report = graph.resolve_report(&interned);
2272
2273    // The present package resolves; the missing one is reported rather than
2274    // silently dropped.
2275    assert_eq!(report.urls.len(), 1);
2276    assert_eq!(report.unresolved, vec!["Ghost-Missing".to_string()]);
2277
2278    // The convenience `resolve` still returns just the URL map.
2279    assert_eq!(graph.resolve(&interned).len(), 1);
2280  }
2281
2282  #[test]
2283  fn test_resolve_report_flags_package_with_no_downloadable_version() {
2284    let mut pkg = create_test_package("ModA", "Owner1", "1.0.0");
2285
2286    // Present in the index, but with nothing downloadable.
2287    pkg.versions.clear();
2288
2289    let interned: PackageIndex = vec![pkg].into();
2290
2291    let graph = DependencyGraph::new(vec!["Owner1-ModA".to_string()]);
2292    let report = graph.resolve_report(&interned);
2293
2294    // It yields no URL, and rather than being silently dropped it is reported so
2295    // an empty `unresolved` can be trusted to mean a complete install.
2296    assert!(report.urls.is_empty());
2297    assert_eq!(report.unresolved, vec!["Owner1-ModA".to_string()]);
2298  }
2299
2300  #[test]
2301  #[cfg(feature = "io")]
2302  fn test_duplicate_string_table_returns_error_not_panic() {
2303    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2304    let interned: PackageIndex = vec![pkg].into();
2305    let mut serializable: SerializedPackageIndex = (&interned).into();
2306
2307    // Push a duplicate string into the table and repoint a package name at its
2308    // (now out-of-real-range) index. The index passes `decode_key`'s range check
2309    // but dangles past the deduplicated interner; without the duplicate-table
2310    // guard this would panic later in `resolve` instead of erroring here.
2311    let dup = serializable.string_table[0].clone();
2312
2313    serializable.string_table.push(dup);
2314
2315    let last_index = serializable.string_table.len() as u32 - 1;
2316
2317    serializable.names[0] = Some(last_index);
2318
2319    let result = PackageIndex::try_from(serializable);
2320
2321    assert!(result.is_err());
2322  }
2323
2324  #[test]
2325  #[cfg(feature = "io")]
2326  fn test_corrupt_cache_index_returns_error_not_panic() {
2327    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2328    let interned: PackageIndex = vec![pkg].into();
2329    let mut serializable: SerializedPackageIndex = (&interned).into();
2330
2331    // Point a package name at a string-table index that does not exist; a
2332    // corrupt cache must surface as an error rather than panicking.
2333    let bad_index = serializable.string_table.len() as u32 + 5;
2334    serializable.names[0] = Some(bad_index);
2335
2336    let result = PackageIndex::try_from(serializable);
2337
2338    assert!(result.is_err());
2339  }
2340
2341  #[test]
2342  fn test_package_index_dependency_graph_resolve() {
2343    let pkg1 = create_test_package("ModA", "Owner1", "1.0.0");
2344    let pkg2 = create_test_package_with_dependencies(
2345      "ModB",
2346      "Owner2",
2347      "2.0.0",
2348      vec!["Owner3-ModC".to_string()],
2349    );
2350    let pkg3 = create_test_package_with_dependencies(
2351      "ModC",
2352      "Owner3",
2353      "1.5.0",
2354      vec!["Owner4-ModD".to_string()],
2355    );
2356    let pkg4 = create_test_package("ModD", "Owner4", "0.9.0");
2357
2358    let packages = vec![pkg1, pkg2, pkg3, pkg4];
2359    let interned: PackageIndex = packages.into();
2360
2361    let dg1 = DependencyGraph::new(vec!["Owner1-ModA".to_string()]);
2362    let result1 = dg1.resolve(&interned);
2363
2364    assert_eq!(result1.len(), 1);
2365
2366    assert!(result1.contains_key("Owner1-ModA-1.0.0.zip"));
2367
2368    let dg2 = DependencyGraph::new(vec!["Owner2-ModB".to_string()]);
2369    let result2 = dg2.resolve(&interned);
2370
2371    assert_eq!(result2.len(), 3);
2372
2373    assert!(result2.contains_key("Owner2-ModB-2.0.0.zip"));
2374
2375    assert!(result2.contains_key("Owner3-ModC-1.5.0.zip"));
2376
2377    assert!(result2.contains_key("Owner4-ModD-0.9.0.zip"));
2378  }
2379
2380  #[test]
2381  fn test_package_index_dependency_graph_resolve_with_missing_dependency() {
2382    let pkg1 = create_test_package("ModA", "Owner1", "1.0.0");
2383    let pkg2 = create_test_package_with_dependencies(
2384      "ModB",
2385      "Owner2",
2386      "2.0.0",
2387      vec!["Owner3-NonExistent".to_string()],
2388    );
2389
2390    let packages = vec![pkg1, pkg2];
2391    let interned: PackageIndex = packages.into();
2392
2393    let dg = DependencyGraph::new(vec!["Owner2-ModB".to_string()]);
2394    let result = dg.resolve(&interned);
2395
2396    assert_eq!(result.len(), 1);
2397
2398    assert!(result.contains_key("Owner2-ModB-2.0.0.zip"));
2399  }
2400
2401  #[test]
2402  fn test_package_index_dependency_graph_resolve_with_version_suffix() {
2403    let pkg1 = create_test_package("ModA", "Owner1", "1.0.0");
2404
2405    let packages = vec![pkg1];
2406    let interned: PackageIndex = packages.into();
2407
2408    let dg = DependencyGraph::new(vec!["Owner1-ModA-1.0.0".to_string()]);
2409    let result = dg.resolve(&interned);
2410
2411    assert_eq!(result.len(), 1);
2412
2413    assert!(result.contains_key("Owner1-ModA-1.0.0.zip"));
2414  }
2415
2416  /// A package whose versions are published in slice order (last is latest).
2417  fn create_test_package_with_versions(
2418    name: &str,
2419    owner: &str,
2420    versions: &[(&str, &[&str])],
2421  ) -> Package {
2422    let mut pkg = create_test_package(name, owner, versions[0].0);
2423    let template = pkg.versions[0].clone();
2424    let start =
2425      OffsetDateTime::now_utc().saturating_sub(time::Duration::days(versions.len() as i64));
2426
2427    pkg.versions = versions
2428      .iter()
2429      .enumerate()
2430      .map(|(day, (version, deps))| Version {
2431        version_number: Some(version.to_string()),
2432        dependencies: deps.iter().map(|d| d.to_string()).collect(),
2433        download_url: Some(format!("https://example.com/{name}/{version}")),
2434        date_created: start.saturating_add(time::Duration::days(day as i64)),
2435        ..template.clone()
2436      })
2437      .collect();
2438
2439    pkg
2440  }
2441
2442  fn pinning_index() -> PackageIndex {
2443    vec![
2444      create_test_package_with_versions(
2445        "ModA",
2446        "Owner1",
2447        &[
2448          ("1.0.0", &["Owner4-ModD-0.9.0"]),
2449          ("2.0.0", &["Owner3-ModC-1.5.0"]),
2450        ],
2451      ),
2452      create_test_package_with_dependencies(
2453        "ModB",
2454        "Owner2",
2455        "1.0.0",
2456        vec!["Owner1-ModA-1.0.0".to_string()],
2457      ),
2458      create_test_package("ModC", "Owner3", "1.5.0"),
2459      create_test_package("ModD", "Owner4", "0.9.0"),
2460    ]
2461    .into()
2462  }
2463
2464  fn sorted_keys(urls: &HashMap<String, String>) -> Vec<&str> {
2465    let mut keys: Vec<&str> = urls.keys().map(String::as_str).collect();
2466
2467    keys.sort();
2468
2469    keys
2470  }
2471
2472  #[test]
2473  fn test_resolve_pinned_version_uses_that_version_and_its_dependencies() {
2474    let report =
2475      DependencyGraph::new(vec!["Owner1-ModA-1.0.0".to_string()]).resolve_report(&pinning_index());
2476
2477    assert!(report.unresolved.is_empty());
2478    assert_eq!(
2479      sorted_keys(&report.urls),
2480      ["Owner1-ModA-1.0.0.zip", "Owner4-ModD-0.9.0.zip"]
2481    );
2482    assert_eq!(
2483      report.urls["Owner1-ModA-1.0.0.zip"],
2484      "https://example.com/ModA/1.0.0"
2485    );
2486  }
2487
2488  #[test]
2489  fn test_resolve_bare_name_still_resolves_latest() {
2490    let report =
2491      DependencyGraph::new(vec!["Owner1-ModA".to_string()]).resolve_report(&pinning_index());
2492
2493    assert!(report.unresolved.is_empty());
2494    assert_eq!(
2495      sorted_keys(&report.urls),
2496      ["Owner1-ModA-2.0.0.zip", "Owner3-ModC-1.5.0.zip"]
2497    );
2498  }
2499
2500  #[test]
2501  fn test_resolve_missing_pinned_version_is_unresolved_not_latest() {
2502    let report =
2503      DependencyGraph::new(vec!["Owner1-ModA-9.9.9".to_string()]).resolve_report(&pinning_index());
2504
2505    assert!(report.urls.is_empty());
2506    assert_eq!(report.unresolved, vec!["Owner1-ModA-9.9.9".to_string()]);
2507  }
2508
2509  #[test]
2510  fn test_resolve_dependency_string_version_is_not_a_pin() {
2511    let report =
2512      DependencyGraph::new(vec!["Owner2-ModB".to_string()]).resolve_report(&pinning_index());
2513
2514    assert!(report.unresolved.is_empty());
2515    assert_eq!(
2516      sorted_keys(&report.urls),
2517      [
2518        "Owner1-ModA-2.0.0.zip",
2519        "Owner2-ModB-1.0.0.zip",
2520        "Owner3-ModC-1.5.0.zip"
2521      ]
2522    );
2523  }
2524
2525  #[test]
2526  fn test_resolve_pin_on_a_dependency_wins_over_latest() {
2527    let requested = DependencyGraph::new(vec![
2528      "Owner2-ModB".to_string(),
2529      "Owner1-ModA-1.0.0".to_string(),
2530    ])
2531    .resolve_report(&pinning_index());
2532    let pinned_only = DependencyGraph::new(vec!["Owner2-ModB".to_string()])
2533      .pins(["Owner1-ModA-1.0.0".to_string()])
2534      .resolve_report(&pinning_index());
2535
2536    for report in [requested, pinned_only] {
2537      assert!(report.unresolved.is_empty());
2538      assert_eq!(
2539        sorted_keys(&report.urls),
2540        [
2541          "Owner1-ModA-1.0.0.zip",
2542          "Owner2-ModB-1.0.0.zip",
2543          "Owner4-ModD-0.9.0.zip"
2544        ]
2545      );
2546    }
2547  }
2548
2549  #[test]
2550  fn test_resolve_pin_wins_over_a_bare_request_for_the_same_package() {
2551    let report = DependencyGraph::new(vec![
2552      "Owner1-ModA".to_string(),
2553      "Owner1-ModA-1.0.0".to_string(),
2554    ])
2555    .resolve_report(&pinning_index());
2556
2557    assert!(report.unresolved.is_empty());
2558    assert_eq!(
2559      sorted_keys(&report.urls),
2560      ["Owner1-ModA-1.0.0.zip", "Owner4-ModD-0.9.0.zip"]
2561    );
2562  }
2563
2564  #[test]
2565  fn test_resolve_conflicting_pins_leave_the_package_unresolved() {
2566    let report = DependencyGraph::new(vec![
2567      "Owner2-ModB".to_string(),
2568      "Owner1-ModA-2.0.0".to_string(),
2569    ])
2570    .pins(["Owner1-ModA-1.0.0".to_string()])
2571    .resolve_report(&pinning_index());
2572
2573    assert_eq!(
2574      report.unresolved,
2575      vec![
2576        "Owner1-ModA-1.0.0".to_string(),
2577        "Owner1-ModA-2.0.0".to_string()
2578      ]
2579    );
2580    assert_eq!(sorted_keys(&report.urls), ["Owner2-ModB-1.0.0.zip"]);
2581  }
2582
2583  #[test]
2584  fn test_resolve_ignores_unversioned_and_unreached_pins() {
2585    let report = DependencyGraph::new(vec!["Owner3-ModC".to_string()])
2586      .pins(["Owner1-ModA".to_string(), "Owner1-ModA-9.9.9".to_string()])
2587      .resolve_report(&pinning_index());
2588
2589    assert!(report.unresolved.is_empty());
2590    assert_eq!(sorted_keys(&report.urls), ["Owner3-ModC-1.5.0.zip"]);
2591  }
2592
2593  #[test]
2594  #[cfg(feature = "io")]
2595  fn test_cache_rejects_unsupported_format_version() {
2596    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2597    let interned: PackageIndex = vec![pkg].into();
2598    let mut serializable: SerializedPackageIndex = (&interned).into();
2599
2600    // A cache written by a future/incompatible format must be rejected as a
2601    // recoverable error (so the client re-fetches) rather than misdecoded.
2602    serializable.format_version = CACHE_FORMAT_VERSION + 1;
2603
2604    let result = PackageIndex::try_from(serializable);
2605
2606    assert!(matches!(result, Err(Error::UnsupportedCacheVersion { .. })));
2607  }
2608
2609  #[test]
2610  #[cfg(feature = "io")]
2611  fn test_cache_current_format_version_round_trips() {
2612    let pkg = create_test_package("TestMod", "TestOwner", "1.0.0");
2613    let interned: PackageIndex = vec![pkg].into();
2614    let serializable: SerializedPackageIndex = (&interned).into();
2615
2616    assert_eq!(serializable.format_version, CACHE_FORMAT_VERSION);
2617    assert!(PackageIndex::try_from(serializable).is_ok());
2618  }
2619
2620  #[test]
2621  fn test_validate_rejects_version_owned_by_wrong_package() {
2622    let pkg1 = create_test_package("ModA", "Owner1", "1.0.0");
2623    let pkg2 = create_test_package("ModB", "Owner2", "2.0.0");
2624    let mut interned: PackageIndex = vec![pkg1, pkg2].into();
2625
2626    // Version 0 sits in package 0's range but claims to belong to package 1.
2627    interned.versions.package_indices[0] = 1;
2628
2629    let result = interned.validate();
2630
2631    assert!(result.is_err());
2632
2633    assert!(result.unwrap_err().to_string().contains("package_index"));
2634  }
2635
2636  #[test]
2637  fn test_validate_rejects_overlapping_version_ranges() {
2638    let pkg1 = create_test_package("ModA", "Owner1", "1.0.0");
2639    let pkg2 = create_test_package("ModB", "Owner2", "2.0.0");
2640    let mut interned: PackageIndex = vec![pkg1, pkg2].into();
2641
2642    // Point both packages at the same version, leaving version 1 uncovered.
2643    interned.version_ranges[1] = (0, 1);
2644
2645    let result = interned.validate();
2646
2647    assert!(result.is_err());
2648
2649    assert!(result.unwrap_err().to_string().contains("overlapping"));
2650  }
2651
2652  #[test]
2653  fn test_package_index_validate_rejects_duplicate_full_names() {
2654    // Two packages sharing a full name: Thunderstore guarantees uniqueness, so a
2655    // cache with a duplicate is corrupt. Rejecting it keeps
2656    // `find_index_by_full_name` (first match) and `build_name_index` (last match)
2657    // from resolving the same name to different packages.
2658    let pkg1 = create_test_package("TestMod", "TestOwner", "1.0.0");
2659    let pkg2 = create_test_package("TestMod", "TestOwner", "2.0.0");
2660    let interned: PackageIndex = vec![pkg1, pkg2].into();
2661
2662    let result = interned.validate();
2663
2664    assert!(result.is_err());
2665
2666    assert!(
2667      result
2668        .unwrap_err()
2669        .to_string()
2670        .contains("duplicate full name")
2671    );
2672  }
2673
2674  #[test]
2675  fn test_package_index_dependency_graph_resolve_handles_cycles() {
2676    // ModA <-> ModB depend on each other, and ModC depends on itself. Without a
2677    // visited set, resolve() would re-insert these deps forever and never return.
2678    let pkg_a = create_test_package_with_dependencies(
2679      "ModA",
2680      "Owner1",
2681      "1.0.0",
2682      vec!["Owner2-ModB".to_string()],
2683    );
2684    let pkg_b = create_test_package_with_dependencies(
2685      "ModB",
2686      "Owner2",
2687      "2.0.0",
2688      vec!["Owner1-ModA".to_string()],
2689    );
2690    let pkg_c = create_test_package_with_dependencies(
2691      "ModC",
2692      "Owner3",
2693      "3.0.0",
2694      vec!["Owner3-ModC".to_string()],
2695    );
2696
2697    let packages = vec![pkg_a, pkg_b, pkg_c];
2698    let interned: PackageIndex = packages.into();
2699
2700    let dg = DependencyGraph::new(vec!["Owner1-ModA".to_string(), "Owner3-ModC".to_string()]);
2701    let result = dg.resolve(&interned);
2702
2703    assert_eq!(result.len(), 3);
2704
2705    assert!(result.contains_key("Owner1-ModA-1.0.0.zip"));
2706
2707    assert!(result.contains_key("Owner2-ModB-2.0.0.zip"));
2708
2709    assert!(result.contains_key("Owner3-ModC-3.0.0.zip"));
2710  }
2711}