Initial migration

.github/CODEOWNERS

@@ -0,0 +1 @@
+@fossas/analysis

Cargo.toml

@@ -1,8 +1,21 @@
 [package]
-name = "template-rust"
-version = "0.1.0"
+name = "locator"
+version = "1.0.0"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
+getset = "0.1.2"
+lazy_static = "1.4.0"
+regex = "1.6.0"
+serde = { version = "1.0.140", features = ["derive"] }
+strum = { version = "0.24.1", features = ["derive"] }
+thiserror = "1.0.31"
+typed-builder = "0.10.0"
+
+[dev-dependencies]
+assert_matches = "1.5.0"
+itertools = "0.10.5"
+proptest = "1.0.0"
+serde_json = "1.0.95"

README.md

@@ -1,28 +1,31 @@
-# template-rust
-
-Template repository for a Rust project.
-
-TODOs for a new project:
-- [ ] Change the license if MPL2 is not appropriate for the project. Make sure to do this before adding any code.
-- [ ] Set [CODEOWNERS] to the team that owns the repository.
-- [ ] Create an API user in [FOSSA] and store it as a secret named `FOSSA_API_KEY`.
-  - Consider naming it with the pattern `ci-{REPO_NAME}`. For example, `ci-template-rust`.
-- [ ] Update repository permissions as appropriate. Generally, the CODEOWNER team is set as admin.
-- [ ] Update branch protection rules as appropriate.
-- [ ] Update repository features and settings. Recommended defaults:
-  - [ ] Turn off all features (Wikis, Issues, Sponsorships, Discussions, Projects); FOSSA uses other systems for these.
-  - [ ] Only allow squash merging.
-  - [ ] Always suggest updating PR branches.
-  - [ ] Allow auto-merge.
-  - [ ] Automatically delete head branches.
-
-Then just edit the included Rust project, or remove it and `cargo init` your project, and get going!
-
-[codeowners]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
-[fossa]: https://app.fossa.com
-
-# recommendations
-
-- Prefer [cross compilation](./docs/dev/reference/cross-compile.md) over running workflows in distinct runners when possible.
-- If publishing a Linux binary, consider providing two: one that [statically links libc](./docs/dev/reference/static-binary.md), and one that doesn't.
-- If publishing a macOS binary, consider providing two: one for [Intel and one for M-series CPUs](./docs/dev/reference/macos-arch.md).
+# locator
+
+This library provides the ability to parse and format "Locator" strings.
+FOSSA uses locators to indicate specific libraries at specific versions.
+
+For more detail, FOSSA employees can reference the
+[Fetchers & Locators doc](https://go/fetchers-doc).
+
+# Format
+
+Locators are in the following basic format:
+
+```
+{fetcher}+{package}${version}
+```
+
+There is some nuance to this. For more details, see the library documentation.
+
+## Example
+
+Some example locators:
+```
+// The FOSSA CLI on GitHub, referencing the tag 'v3.8.24'.
+git+github.com/fossas/fossa-cli$v3.8.24
+
+// The 'lodash' library on NPM, referencing the version '4.17.21'.
+npm+lodash$4.17.21
+
+// The 'lodash' library on NPM without specifying a version.
+npm+lodash
+```

src/error.rs

@@ -0,0 +1,84 @@
+use thiserror::Error;
+
+/// Records all errors reported by this library.
+#[derive(Error, Clone, PartialEq, Eq, Debug)]
+#[non_exhaustive]
+pub enum Error {
+    /// Errors encountered while parsing a [`Locator`](crate::Locator).
+    #[error(transparent)]
+    Parse(#[from] ParseError),
+}
+
+/// Errors encountered when parsing a [`Locator`](crate::Locator) from a string.
+#[derive(Error, Clone, PartialEq, Eq, Debug)]
+#[non_exhaustive]
+pub enum ParseError {
+    /// The input did not match the required syntax.
+    #[error("input did not match required syntax: {input}")]
+    Syntax {
+        /// The input originally provided to the parser.
+        input: String,
+    },
+
+    /// The "named" field was missing from the input.
+    #[error("field '{field}' missing from input: {input}")]
+    Field {
+        /// The input originally provided to the parser.
+        input: String,
+
+        /// The field that was missing.
+        field: String,
+    },
+
+    /// An unsupported value for the "fetcher" field was provided.
+    /// Often this means that it is simply missing from this package.
+    #[error("invalid fetcher '{fetcher}' in input '{input}'")]
+    Fetcher {
+        /// The input originally provided to the parser.
+        input: String,
+
+        /// The fetcher that was attempted to parse.
+        fetcher: String,
+
+        /// The error returned by the parser.
+        #[source]
+        error: strum::ParseError,
+    },
+
+    /// An unsupported value for the "project" field was provided.
+    #[error("invalid project '{project}' in input '{input}'")]
+    Project {
+        /// The input originally provided to the parser.
+        input: String,
+
+        /// The project that was attempted to parse.
+        project: String,
+
+        /// The error returned by the parser.
+        #[source]
+        error: ProjectParseError,
+    },
+}
+
+/// Errors encountered when parsing the project field
+/// when parsing a [`Locator`](crate::Locator) from a string.
+#[derive(Error, Clone, PartialEq, Eq, Debug)]
+#[non_exhaustive]
+pub enum ProjectParseError {
+    /// An unsupported value for the "project" field was provided.
+    #[error("project did not match required syntax: {project}")]
+    Project {
+        /// The project input.
+        project: String,
+    },
+
+    /// The "named" field was missing from the input.
+    #[error("field '{field}' missing from input: {project}")]
+    Field {
+        /// The input originally provided to the parser.
+        project: String,
+
+        /// The field that was missing.
+        field: String,
+    },
+}

src/fetcher.rs

@@ -0,0 +1,134 @@
+use std::str::FromStr;
+
+use serde::{Deserialize, Serialize};
+use strum::{AsRefStr, Display, EnumIter, EnumString};
+
+/// [`Locator`](crate::Locator) is closely tied with the concept of Core's "fetchers",
+/// which are asynchronous jobs tasked with downloading the code
+/// referred to by a [`Locator`](crate::Locator) so that Core or some other service
+/// may analyze it.
+///
+/// For more information on the background of `Locator` and fetchers generally,
+/// refer to [Fetchers and Locators](https://go/fetchers-doc).
+#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug, Display, EnumString, EnumIter, AsRefStr)]
+#[non_exhaustive]
+pub enum Fetcher {
+    /// Archive locators are FOSSA specific.
+    #[strum(serialize = "archive")]
+    Archive,
+
+    /// Interacts with Bower.
+    #[strum(serialize = "bower")]
+    Bower,
+
+    /// Interacts with Carthage.
+    #[strum(serialize = "cart")]
+    Cart,
+
+    /// Interacts with Cargo.
+    #[strum(serialize = "cargo")]
+    Cargo,
+
+    /// Interacts with Composer.
+    #[strum(serialize = "comp")]
+    Comp,
+
+    /// Interacts with Conan.
+    #[strum(serialize = "conan")]
+    Conan,
+
+    /// Interacts with Conda.
+    #[strum(serialize = "conda")]
+    Conda,
+
+    /// Interacts with CPAN.
+    #[strum(serialize = "cpan")]
+    Cpan,
+
+    /// Interacts with CRAN.
+    #[strum(serialize = "cran")]
+    Cran,
+
+    /// The `custom` fetcher describes first party projects in FOSSA.
+    ///
+    /// These projects aren't really _fetched_;
+    /// they're stored in FOSSA's database.
+    #[strum(serialize = "custom")]
+    Custom,
+
+    /// Interacts with RubyGems.
+    #[strum(serialize = "gem")]
+    Gem,
+
+    /// Interacts with git VCS hosts.
+    #[strum(serialize = "git")]
+    Git,
+
+    /// Resolves 'git' dependencies in the same manner as Go modules.
+    #[strum(serialize = "go")]
+    Go,
+
+    /// Interacts with Hackage.
+    #[strum(serialize = "hackage")]
+    Hackage,
+
+    /// Interacts with Hex.
+    #[strum(serialize = "hex")]
+    Hex,
+
+    /// Interacts with Maven.
+    #[strum(serialize = "mvn")]
+    Maven,
+
+    /// Interacts with NPM.
+    #[strum(serialize = "npm")]
+    Npm,
+
+    /// Interacts with Nuget.
+    #[strum(serialize = "nuget")]
+    Nuget,
+
+    /// Interacts with PyPI.
+    #[strum(serialize = "pip")]
+    Pip,
+
+    /// Interacts with CocoaPods.
+    #[strum(serialize = "pod")]
+    Pod,
+
+    /// Interacts with Dart's package manager.
+    #[strum(serialize = "pub")]
+    Pub,
+
+    /// Interact with Swift's package manager.
+    #[strum(serialize = "swift")]
+    Swift,
+
+    /// Specifies an arbitrary URL,
+    /// which is downloaded and treated like an `Archive` variant.
+    #[strum(serialize = "url")]
+    Url,
+
+    /// A user-specified package.
+    #[strum(serialize = "user")]
+    User,
+}
+
+impl<'de> Deserialize<'de> for Fetcher {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let raw = String::deserialize(deserializer)?;
+        Fetcher::from_str(&raw).map_err(serde::de::Error::custom)
+    }
+}
+
+impl Serialize for Fetcher {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        self.to_string().serialize(serializer)
+    }
+}