lux_lib/project/

project_toml.rs

//! Structs and utilities for `lux.toml`

use crate::fs;
use crate::git::shorthand::RemoteGitUrlShorthand;
use crate::git::{GitRef, GitSource};
use crate::hash::HasIntegrity;
use crate::lockfile::OptState;
use crate::lockfile::PinnedState;
use crate::lua_rockspec::DeploySpec;
use crate::lua_rockspec::LocalLuaRockspec;
use crate::lua_rockspec::LocalRockSource;
use crate::lua_rockspec::LuaRockspecError;
use crate::lua_rockspec::RemoteLuaRockspec;
use crate::lua_rockspec::RockSourceSpec;
use crate::lua_version::LuaVersion;
use crate::operations::RunCommand;
use crate::package::PackageNameList;
use crate::package::SpecRev;
use crate::project::TomlDeError;
use crate::rockspec::lua_dependency::LuaDependencySpec;
use crate::ROCKSPEC_FUEL_LIMIT;
use std::io;
use std::path::Path;
use std::{collections::HashMap, path::PathBuf};

use crate::{
    build::autodetect_modules,
    config::Config,
    lua_rockspec::{
        BuildSpec, BuildSpecInternal, BuildSpecInternalError, BuildType, DisplayAsLuaKV,
        DisplayLuaKV, ExternalDependencies, ExternalDependencySpec, LuaTableKey, LuaVersionError,
        ModuleSpec, ModuleSpecInternal, PartialLuaRockspec, PerPlatform, PlatformIdentifier,
        PlatformSupport, PlatformValidationError, RemoteRockSource, RockDescription,
        RockSourceError, RockspecFormat, TestSpec, TestSpecDecodeError, TestSpecInternal,
    },
    package::{
        BuildDependencies, Dependencies, PackageName, PackageReq, PackageVersion, PackageVersionReq,
    },
    rockspec::{LuaVersionCompatibility, Rockspec},
};
use itertools::Itertools;
use miette::Diagnostic;
use nonempty::NonEmpty;

use crate::package::wally::PackageReq as WallyPackageReq;
use serde::de;
use serde::{Deserialize, Deserializer};
use ssri::Integrity;
use thiserror::Error;

use super::gen::GenerateSourceError;
use super::gen::RockSourceTemplate;
use super::r#gen::GenerateVersionError;
use super::r#gen::PackageVersionTemplate;
use super::ProjectRoot;

pub const PROJECT_TOML: &str = "lux.toml";

#[derive(Deserialize)]
#[serde(untagged)]
#[allow(clippy::large_enum_variant)] // This is ok because it's just a Deserialize helper
enum DependencyEntry {
    Simple(PackageVersionReq),
    Detailed(DependencyTableEntry),
}

#[derive(Debug, Deserialize)]
struct DependencyTableEntry {
    #[serde(default)]
    version: Option<PackageVersionReq>,
    #[serde(default)]
    opt: Option<bool>,
    #[serde(default)]
    pin: Option<bool>,
    #[serde(default)]
    git: Option<RemoteGitUrlShorthand>,
    #[serde(default)]
    path: Option<PathBuf>,
    #[serde(default)]
    rev: Option<String>,
    #[serde(default)]
    wally: Option<WallyPackageReq>,
}

fn parse_map_to_dependency_vec_opt<'de, D>(
    deserializer: D,
) -> Result<Option<Vec<LuaDependencySpec>>, D::Error>
where
    D: Deserializer<'de>,
{
    let packages: Option<HashMap<PackageName, DependencyEntry>> =
        Option::deserialize(deserializer)?;

    match packages {
        None => Ok(None),
        Some(packages) => Ok(Some(
            packages
                .into_iter()
                .map(|(name, spec)| match spec {
                    DependencyEntry::Simple(version_req) => {
                        Ok(PackageReq { name, version_req }.into())
                    }
                    DependencyEntry::Detailed(entry) => {
                        let DependencyTableEntry {
                            version,
                            opt,
                            pin,
                            git,
                            path,
                            rev,
                            wally,
                        } = entry;

                        let (version_req, source) = if let Some(wally) = wally {
                            if version.is_some() || git.is_some() || rev.is_some() || path.is_some() {
                                return Err(de::Error::custom(format!(
                                    "dependency '{}' specifies 'wally', which cannot be combined with 'version', 'git', 'rev', or 'path'",
                                    name
                                )));
                            }
                            (
                                PackageVersionReq::SemVer(wally.version_req().clone()),
                                Some(RockSourceSpec::Wally(wally)),
                            )
                        } else {
                            let version = version.ok_or_else(|| {
                                de::Error::custom(format!(
                                    "dependency '{name}' is missing a 'version' or 'wally' field"
                                ))
                            })?;
                            let source = match (git, rev, path) {
                                (None, None, None) => Ok(None),
                                (None, Some(_), None) => Err(de::Error::custom(format!(
                                    "dependency {} specifies a 'rev', but missing a 'git' field",
                                    name
                                ))),
                                (Some(git), Some(rev), None) => {
                                    Ok(Some(RockSourceSpec::Git(GitSource {
                                        url: git.into(),
                                        git_ref: Some(GitRef::Tag(rev)),
                                    })))
                                }
                                (Some(git), None, None) => Ok(Some(RockSourceSpec::Git(GitSource {
                                    url: git.into(),
                                    git_ref: Some(GitRef::Tag(
                                        version
                                            .clone()
                                            .to_string()
                                            .trim_start_matches("=")
                                            .to_string(),
                                    )),
                                }))),
                                (None, None, Some(path)) => Ok(Some(RockSourceSpec::File(path))),
                                (_, _, Some(_)) => Err(de::Error::custom(format!(
                                    "dependency '{}' specifies a 'path', which cannot be combined with 'git' or 'rev'",
                                    name
                                ))),
                            }?;
                            (version, source)
                        };

                        Ok(LuaDependencySpec {
                            package_req: PackageReq { name, version_req },
                            opt: OptState::from(opt.unwrap_or(false)),
                            pin: PinnedState::from(pin.unwrap_or(false)),
                            source,
                        })
                    }
                })
                .try_collect()?,
        )),
    }
}

#[derive(Debug, Error, Diagnostic)]
pub enum ProjectTomlError {
    #[error("error generating rockspec source")]
    #[diagnostic(forward(0))]
    GenerateSource(#[from] GenerateSourceError),
    #[error("error generating rockspec version")]
    #[diagnostic(forward(0))]
    GenerateVersion(#[from] GenerateVersionError),
    #[error("generated rockspec exceeds computational limit of {ROCKSPEC_FUEL_LIMIT} steps")]
    #[diagnostic(help(
        r#"the rockspec may be too complex or contain too many dependencies.
        Try reducing the number of dependencies or simplifying build instructions."#
    ))]
    FuelLimitExceeded,
    #[error(
        r#"generated invalid Lua from TOML:
{0}
"#
    )]
    #[diagnostic(help("this is a bug in Lux. please report it."))]
    GeneratedInvalidLua(String),
}

#[derive(Debug, Error, Diagnostic)]
pub enum LocalProjectTomlValidationError {
    #[error("no lua version provided")]
    #[diagnostic(help(
        r#"add a `lua` field to your lux.toml, for example:

  lua = ">=5.1""#
    ))]
    NoLuaVersion,
    #[error("could not decode the test spec")]
    #[diagnostic(forward(0))]
    TestSpecError(#[from] TestSpecDecodeError),
    #[error("could not decode the build spec")]
    #[diagnostic(forward(0))]
    BuildSpecInternal(#[from] BuildSpecInternalError),
    #[error(transparent)]
    #[diagnostic(transparent)]
    PlatformValidation(#[from] PlatformValidationError),
    #[error("{}copy_directories cannot contain a rockspec name", ._0.as_ref().map(|p| format!("{p}: ")).unwrap_or_default())]
    CopyDirectoriesContainRockspecName(Option<String>),
    #[error("could not decode the source spec")]
    #[diagnostic(forward(0))]
    RockSource(#[from] RockSourceError),
    #[error("duplicate dependencies: {0}")]
    #[diagnostic(help("remove the duplicate entries from the [dependencies] table."))]
    DuplicateDependencies(PackageNameList),
    #[error("duplicate test dependencies: {0}")]
    #[diagnostic(help("remove the duplicate entries from the [test_dependencies] table."))]
    DuplicateTestDependencies(PackageNameList),
    #[error("duplicate build dependencies: {0}")]
    #[diagnostic(help("remove the duplicate entries from the [build_dependencies] table."))]
    DuplicateBuildDependencies(PackageNameList),
    #[error(
        r#"dependencies field cannot contain 'lua'.
        Please provide the version in the top-level 'lua' field

        Example:

        ```toml
        package = "my-package"
        lua = ">=5.1"

        [dependencies]
        # do not add Lua here!
        ```
        "#
    )]
    DependenciesContainLua,
    #[error("error generating rockspec source")]
    #[diagnostic(forward(0))]
    GenerateSource(#[from] GenerateSourceError),
    #[error("error generating rockspec version")]
    #[diagnostic(forward(0))]
    GenerateVersion(#[from] GenerateVersionError),
}

#[derive(Debug, Error, Diagnostic)]
pub enum RemoteProjectTomlValidationError {
    #[error("error generating rockspec source")]
    #[diagnostic(forward(0))]
    GenerateSource(#[from] GenerateSourceError),
    #[error("error generating rockspec version")]
    #[diagnostic(forward(0))]
    GenerateVersion(#[from] GenerateVersionError),
    #[error(transparent)]
    #[diagnostic(transparent)]
    LocalProjectTomlValidationError(#[from] LocalProjectTomlValidationError),
}

/// The `lux.toml` file for a project.
/// The only required fields are `package` and `build`, which are required to build a project using `lux build`.
/// The rest of the fields are optional, but are required to build a rockspec.
#[derive(Clone, Debug, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct PartialProjectToml {
    /// The name of the rock. Lux converts it to lower case when publishing.
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"package = "my-lua-project""#))
    )]
    pub(crate) package: PackageName,
    /// The package version. If unset, Lux derives it from the current SemVer
    /// git tag (optional `v` prefix), falling back to "dev".
    ///
    /// Versions like `1.0` are corrected to `1.0.0`.
    /// Non-SemVer versions (e.g. `1.0-rc1` instead of `1.0.0-rc1`) are treated
    /// as Dev versions and cannot be compared with SemVer versions.
    #[serde(default, rename = "version")]
    #[cfg_attr(feature = "schema", schemars(with = "String"))]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"version = "1.0.0""#))
    )]
    pub(crate) version_template: PackageVersionTemplate,
    /// How to build the project. See the build backend fields below.
    ///
    /// Rocks with C sources require a C compiler. Lux does not bundle one.
    #[serde(default)]
    pub(crate) build: BuildSpecInternal,
    /// The LuaRocks rockspec format version to write to the generated rockspec ("1.0", "2.0", or "3.0").
    /// Default: "3.0".
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"rockspec_format = "3.0""#))
    )]
    pub(crate) rockspec_format: Option<RockspecFormat>,
    /// How to run the project with `lx run`.
    #[serde(default)]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"
[run]
args = ["src/main.lua"]
"#))
    )]
    pub(crate) run: Option<RunSpec>,
    /// The Lua version requirement, e.g. ">= 5.1". Required to build a rockspec.
    /// Set to "luau" to build and run the project with Luau.
    #[serde(default)]
    #[cfg_attr(feature = "schema", schemars(with = "Option<String>"))]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"lua = ">=5.1""#))
    )]
    pub(crate) lua: Option<PackageVersionReq>,
    /// Metadata published to LuaRocks.
    #[serde(default)]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"
[description]
summary = "A one-line description of the package"
detailed = """
A longer description of the package
that often spans multiple lines.
"""
license = "GPLv2"
homepage = "https://lumen-oss.github.io"
issues_url = "https://github.com/lumen-oss/lux/issues"
maintainer = "neorocks org"
labels = ["neovim", "tls", "https"]
"#))
    )]
    pub(crate) description: Option<RockDescription>,
    /// Platforms this rock supports, mapping platform identifiers to `true` or
    /// `false` (e.g. `linux = true`).
    #[serde(default)]
    #[cfg_attr(
        feature = "schema",
        schemars(with = "Option<std::collections::BTreeMap<String, bool>>")
    )]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"
[supported_platforms]
linux = true
windows = false
"#))
    )]
    pub(crate) supported_platforms: Option<HashMap<PlatformIdentifier, bool>>,
    /// Runtime Lua dependencies, mapping package names to a version requirement
    /// (e.g. `foo = "1.0"`) or to a detailed table with `version`, `opt`, `pin`,
    /// `git`, `rev`, and `path` keys.
    ///
    /// Version requirements support the operators `==`, `~=`, `<`, `>`, `<=`,
    /// `>=`, and `~>`. `~> 2` means `>= 2, < 3`. An operator is optional;
    /// without one, the requirement is treated as `==`. Version requirements
    /// are mandatory.
    ///
    /// Dependencies are declared under `lua`, `[dependencies]`,
    /// `[build_dependencies]`, `[test_dependencies]`, and
    /// `[external_dependencies]`.
    ///
    /// Git dependencies support the `github:` (default), `gitlab:`,
    /// `codeberg:`, and `sourcehut:` shorthands, as well as full HTTPS and SSH
    /// URLs. If `rev` is unset, `version` is used as the commit SHA or tag.
    /// Lux searches the repository root for a `lux.toml` or `.rockspec` to
    /// determine the build specification, defaulting to `builtin` if none is
    /// found. Rocks with git dependencies cannot be published to LuaRocks. Git
    /// dependencies that require a custom LuaRocks build backend are not
    /// supported.
    #[serde(default, deserialize_with = "parse_map_to_dependency_vec_opt")]
    #[cfg_attr(
        feature = "schema",
        schemars(
            with = "Option<std::collections::BTreeMap<String, crate::schema::DependencyEntry>>"
        )
    )]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"
[dependencies]
luafilesystem = "1.0.0"

[dependencies.argparse]
version = "0.7"
opt = true

[dependencies.foo]
version = "09511782201302ade916d4b250d01a6c61b56844"
git = "github:lunarmodules/foo"

[dependencies.bar]
path = "../bar"
version = "1.0.0"
"#))
    )]
    pub(crate) dependencies: Option<Vec<LuaDependencySpec>>,
    /// Dependencies needed at build time. Same syntax as `dependencies`.
    #[serde(default, deserialize_with = "parse_map_to_dependency_vec_opt")]
    #[cfg_attr(
        feature = "schema",
        schemars(
            with = "Option<std::collections::BTreeMap<String, crate::schema::DependencyEntry>>"
        )
    )]
    pub(crate) build_dependencies: Option<Vec<LuaDependencySpec>>,
    /// System (C/FFI) dependencies, discovered via pkg-config. Each entry may
    /// set `header` and/or `library`.
    #[serde(default)]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"
[external_dependencies.OPENSSL]
header = "openssl/ssl.h"
library = "ssl"
"#))
    )]
    pub(crate) external_dependencies: Option<HashMap<String, ExternalDependencySpec>>,
    /// Dependencies needed when running `lx test`. Same syntax as `dependencies`.
    #[serde(default, deserialize_with = "parse_map_to_dependency_vec_opt")]
    #[cfg_attr(
        feature = "schema",
        schemars(
            with = "Option<std::collections::BTreeMap<String, crate::schema::DependencyEntry>>"
        )
    )]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"
[test_dependencies]
busted = ">=2.0.0"
nlua = "~>0.3"
"#))
    )]
    pub(crate) test_dependencies: Option<Vec<LuaDependencySpec>>,
    /// Templates for generating the source URL of a release.
    ///
    /// Variable substitutions:
    /// - `$(PACKAGE)`: package name
    /// - `$(VERSION)`: package version (from the git tag if not declared)
    /// - `$(REF)`: git tag or revision (priority: SemVer tag, tag, commit SHA)
    /// - `$(<VAR_NAME>)`: any environment variable
    #[serde(default, rename = "source")]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"
[source]
url = "https://host.com/owner/$(PACKAGE)/archive/refs/tags/$(REF).zip"
dev = "git+https://host.com/owner/$(PACKAGE).git"
"#))
    )]
    pub(crate) source_template: RockSourceTemplate,
    /// How to run the test suite with `lx test`.
    ///
    /// The `busted` backend is used when a `.busted` file exists and no backend
    /// is specified. `busted-nlua` is used when a `.busted` file exists or
    /// `busted` and `nlua` are `test_dependencies`. The `busted-nlua` backend is
    /// currently broken on macOS and Windows. Luau projects default to `tiniest`.
    #[serde(default)]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"
[test]
type = "busted"
flags = []
"#))
    )]
    pub(crate) test: Option<TestSpecInternal>,
    /// Additional install and deployment options.
    #[serde(default)]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"
[deploy]
wrap_bin_scripts = false
"#))
    )]
    pub(crate) deploy: Option<DeploySpec>,
    /// Lux-specific project settings, ignored when generating a rockspec.
    #[serde(default)]
    #[cfg_attr(
        feature = "schema",
        schemars(extend("x-lux-toml-example" = r#"
[project]
root_dir = ".."
"#))
    )]
    pub(crate) project: ProjectSpec,

    /// Used to bind the TOML to the directory containing the `lux.toml`.
    #[serde(skip, default = "PathBuf::new")]
    lux_toml_dir: PathBuf,
}

impl HasIntegrity for PartialProjectToml {
    async fn hash(&self) -> io::Result<Integrity> {
        let toml_file = self.lux_toml_dir.join(PROJECT_TOML);
        let content = fs::sync::read_to_string(&toml_file).map_err(io::Error::other)?;
        Ok(Integrity::from(&content))
    }
}

impl PartialProjectToml {
    pub(crate) fn new(
        name: &str,
        str: &str,
        lux_toml_dir: ProjectRoot,
    ) -> Result<Self, TomlDeError> {
        let mut this: Self = super::parse_toml(name, str)?;
        this.lux_toml_dir = lux_toml_dir.to_path_buf();
        this.project.root = match this.project.root_dir {
            Some(ref root_dir) => {
                let relative_project_root = lux_toml_dir.join(root_dir);
                let project_root =
                    std::fs::canonicalize(&relative_project_root).unwrap_or(relative_project_root);
                ProjectRoot(project_root)
            }
            None => lux_toml_dir,
        };
        Ok(this)
    }

    /// This project's Lua version requirement, if any
    pub fn lua(&self) -> Option<&PackageVersionReq> {
        self.lua.as_ref()
    }

    /// Convert the `PartialProjectToml` struct into a `LocalProjectToml` struct, making
    /// it ready to be used for building a project.
    pub fn into_local(&self) -> Result<LocalProjectToml, LocalProjectTomlValidationError> {
        let project_toml = self.clone();

        // Disallow `lua` to be part of the `dependencies` field
        if project_toml
            .dependencies
            .as_ref()
            .is_some_and(|deps| deps.iter().any(|dep| dep.name() == &"lua".into()))
        {
            return Err(LocalProjectTomlValidationError::DependenciesContainLua);
        }

        let get_duplicates = |dependencies: &Option<Vec<LuaDependencySpec>>| {
            dependencies
                .iter()
                .flat_map(|deps| {
                    deps.iter()
                        .map(|dep| dep.package_req().name())
                        .duplicates()
                        .cloned()
                })
                .collect_vec()
        };
        let duplicate_dependencies = get_duplicates(&self.dependencies);
        if !duplicate_dependencies.is_empty() {
            return Err(LocalProjectTomlValidationError::DuplicateDependencies(
                PackageNameList::new(duplicate_dependencies),
            ));
        }
        let duplicate_test_dependencies = get_duplicates(&self.test_dependencies);
        if !duplicate_test_dependencies.is_empty() {
            return Err(LocalProjectTomlValidationError::DuplicateTestDependencies(
                PackageNameList::new(duplicate_test_dependencies),
            ));
        }
        let duplicate_build_dependencies = get_duplicates(&self.build_dependencies);
        if !duplicate_build_dependencies.is_empty() {
            return Err(LocalProjectTomlValidationError::DuplicateBuildDependencies(
                PackageNameList::new(duplicate_build_dependencies),
            ));
        }

        let validated = LocalProjectToml {
            internal: project_toml.clone(),

            package: project_toml.package,
            version: project_toml
                .version_template
                .try_generate(&self.lux_toml_dir, None)
                .unwrap_or(PackageVersion::default_dev_version()),
            lua: project_toml
                .lua
                .ok_or(LocalProjectTomlValidationError::NoLuaVersion)?,
            description: project_toml.description.unwrap_or_default(),
            run: project_toml.run.map(PerPlatform::new),
            supported_platforms: PlatformSupport::parse(
                &project_toml
                    .supported_platforms
                    .unwrap_or_default()
                    .into_iter()
                    .map(|(platform, supported)| {
                        if supported {
                            format!("{platform}")
                        } else {
                            format!("!{platform}")
                        }
                    })
                    .collect_vec(),
            )?,
            // Merge dependencies internally with lua version
            // so the output of `dependencies()` is consistent
            dependencies: PerPlatform::new(
                project_toml
                    .dependencies
                    .unwrap_or_default()
                    .into_iter()
                    .map(|dep| self.resolve_lua_dependency_spec(dep))
                    .collect_vec(),
            ),
            test_dependencies: PerPlatform::new(
                project_toml
                    .test_dependencies
                    .unwrap_or_default()
                    .into_iter()
                    .map(|dep| self.resolve_lua_dependency_spec(dep))
                    .collect_vec(),
            ),
            build_dependencies: PerPlatform::new(
                project_toml
                    .build_dependencies
                    .unwrap_or_default()
                    .into_iter()
                    .map(|dep| self.resolve_lua_dependency_spec(dep))
                    .collect_vec(),
            ),
            external_dependencies: PerPlatform::new(
                project_toml.external_dependencies.unwrap_or_default(),
            ),
            test: PerPlatform::new(TestSpec::try_from(
                project_toml.test.clone().unwrap_or_default(),
            )?),
            build: PerPlatform::new(BuildSpec::from_internal_spec(project_toml.build.clone())?),
            deploy: PerPlatform::new(project_toml.deploy.clone().unwrap_or_default()),
            rockspec_format: project_toml.rockspec_format.clone(),

            source: PerPlatform::new(RemoteRockSource {
                local: LocalRockSource::default(),
                source_spec: RockSourceSpec::File(self.project.root.to_path_buf()),
            }),
        };

        let rockspec_file_name = format!("{}-{}.rockspec", validated.package, validated.version);

        if validated
            .build
            .default
            .copy_directories
            .contains(&PathBuf::from(&rockspec_file_name))
        {
            return Err(LocalProjectTomlValidationError::CopyDirectoriesContainRockspecName(None));
        }

        for (platform, build_override) in &validated.build.per_platform {
            if build_override
                .copy_directories
                .contains(&PathBuf::from(&rockspec_file_name))
            {
                return Err(
                    LocalProjectTomlValidationError::CopyDirectoriesContainRockspecName(Some(
                        platform.to_string(),
                    )),
                );
            }
        }

        Ok(validated)
    }

    /// Convert the `PartialProjectToml` struct into a `RemoteProjectToml` struct, making
    /// it ready to be serialized into a rockspec.
    /// A source must be provided for the rockspec to be valid.
    pub fn into_remote(
        &self,
        specrev: Option<SpecRev>,
    ) -> Result<RemoteProjectToml, RemoteProjectTomlValidationError> {
        self.into_remote_with_version(None, specrev)
    }

    /// Like [`Self::into_remote`] but generates the rockspec for a specified
    /// target version.
    pub fn into_remote_with_version(
        &self,
        version: Option<PackageVersion>,
        specrev: Option<SpecRev>,
    ) -> Result<RemoteProjectToml, RemoteProjectTomlValidationError> {
        let version = match version {
            Some(version) => version,
            None => self
                .version_template
                .try_generate(&self.lux_toml_dir, specrev)?,
        };
        let source =
            self.source_template
                .try_generate(&self.lux_toml_dir, &self.package, &version)?;
        let source = PerPlatform::new(RemoteRockSource::try_from(source).map_err(|err| {
            RemoteProjectTomlValidationError::LocalProjectTomlValidationError(
                LocalProjectTomlValidationError::RockSource(err),
            )
        })?);
        let mut local = self.into_local()?;
        local.version = version;

        let validated = RemoteProjectToml { source, local };

        Ok(validated)
    }

    // In the not-yet-validated struct, we create getters only
    // for the non-optional fields.
    pub fn package(&self) -> &PackageName {
        &self.package
    }

    /// Returns the current package version, which may be generated from a template
    pub fn version(&self) -> Result<PackageVersion, GenerateVersionError> {
        self.version_template.try_generate(&self.lux_toml_dir, None)
    }

    /// Merge the `ProjectToml` struct with an unvalidated `LuaRockspec`.
    /// The final merged struct can then be validated.
    pub fn merge(self, other: PartialLuaRockspec) -> Self {
        PartialProjectToml {
            package: other.package.unwrap_or(self.package),
            version_template: self.version_template,
            lua: other
                .dependencies
                .as_ref()
                .and_then(|deps| {
                    deps.iter()
                        .find(|dep| dep.name() == &"lua".into())
                        .and_then(|dep| {
                            if dep.version_req().is_any() {
                                None
                            } else {
                                Some(dep.version_req().clone())
                            }
                        })
                })
                .or(self.lua),
            build: other.build.unwrap_or(self.build),
            run: self.run,
            description: other.description.or(self.description),
            supported_platforms: other
                .supported_platforms
                .map(|platform_support| platform_support.platforms().clone())
                .or(self.supported_platforms),
            dependencies: other
                .dependencies
                .map(|deps| {
                    deps.into_iter()
                        .filter(|dep| dep.name() != &"lua".into())
                        .collect()
                })
                .or(self.dependencies),
            build_dependencies: other.build_dependencies.or(self.build_dependencies),
            test_dependencies: other.test_dependencies.or(self.test_dependencies),
            external_dependencies: other.external_dependencies.or(self.external_dependencies),
            source_template: self.source_template,
            test: other.test.or(self.test),
            deploy: other.deploy.or(self.deploy),
            rockspec_format: other.rockspec_format.or(self.rockspec_format),

            // Keep the project root the same, as it is not part of the lua rockspec
            project: self.project,
            lux_toml_dir: self.lux_toml_dir.clone(),
        }
    }

    fn resolve_lua_dependency_spec(&self, dep: LuaDependencySpec) -> LuaDependencySpec {
        match &dep.source {
            Some(RockSourceSpec::File(path)) if path.is_dir() => dep,
            Some(RockSourceSpec::File(path)) => LuaDependencySpec {
                source: Some(RockSourceSpec::File(self.lux_toml_dir.join(path))),
                ..dep
            },
            _ => dep,
        }
    }
}

// This is automatically implemented for `RemoteProjectToml`,
// but we also add a special implementation for `ProjectToml` (as providing a lua version
// is required even by the non-validated struct).
impl LuaVersionCompatibility for PartialProjectToml {
    fn validate_lua_version(&self, version: &LuaVersion) -> Result<(), LuaVersionError> {
        if self.supports_lua_version(version) {
            Ok(())
        } else {
            Err(LuaVersionError::LuaVersionUnsupported(
                version.clone(),
                self.package().to_owned(),
                self.version_template
                    .try_generate(&self.lux_toml_dir, None)
                    .unwrap_or(PackageVersion::default_dev_version()),
            ))
        }
    }

    fn validate_lua_version_from_config(&self, config: &Config) -> Result<(), LuaVersionError> {
        let _ = self.lua_version_matches(config)?;
        Ok(())
    }

    fn lua_version_matches(&self, config: &Config) -> Result<LuaVersion, LuaVersionError> {
        let version = LuaVersion::from(config)?.clone();
        if self.supports_lua_version(&version) {
            Ok(version)
        } else {
            Err(LuaVersionError::LuaVersionUnsupported(
                version,
                self.package.clone(),
                self.version_template
                    .try_generate(&self.lux_toml_dir, None)
                    .unwrap_or(PackageVersion::default_dev_version()),
            ))
        }
    }

    fn supports_lua_version(&self, lua_version: &LuaVersion) -> bool {
        self.lua.as_ref().is_none_or(|lua| {
            if lua.is_luau() {
                return matches!(lua_version, LuaVersion::Luau);
            }
            lua.matches(&lua_version.as_version())
        })
    }

    fn lua_version(&self) -> Option<LuaVersion> {
        if self.lua.as_ref().is_some_and(|lua| lua.is_luau()) {
            return Some(LuaVersion::Luau);
        }
        for (possibility, version) in [
            ("5.5.0", LuaVersion::Lua55),
            ("5.4.0", LuaVersion::Lua54),
            ("5.3.0", LuaVersion::Lua53),
            ("5.2.0", LuaVersion::Lua52),
            ("5.1.0", LuaVersion::Lua51),
        ] {
            let possibility = unsafe { possibility.parse().unwrap_unchecked() };
            if self
                .lua
                .as_ref()
                .is_none_or(|lua| lua.matches(&possibility))
            {
                return Some(version);
            }
        }
        None
    }
}

/// Lux-specific project configuration.
///
/// This is not part of the rockspec format and is ignored when generating a rockspec.
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub(crate) struct ProjectSpec {
    /// The project root directory, relative to the directory containing the `lux.toml`.
    /// Useful for multi-project workspaces, where the build files
    /// (e.g. the cargo workspace `Cargo.toml`) do not live next to the `lux.toml`.
    root_dir: Option<PathBuf>,
    /// The project root directory, resolved from `root_dir` when deserializing.
    #[serde(skip, default = "ProjectRoot::new")]
    pub(crate) root: ProjectRoot,
}

impl Default for ProjectSpec {
    fn default() -> Self {
        Self {
            root_dir: None,
            root: ProjectRoot::new(),
        }
    }
}

// TODO(vhyrro): Move this struct into a different directory.
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct RunSpec {
    /// The command to execute when running the project
    pub(crate) command: Option<RunCommand>,
    /// Arguments to pass to the command
    #[cfg_attr(feature = "schema", schemars(with = "Option<Vec<String>>"))]
    pub(crate) args: Option<NonEmpty<String>>,
}

/// The `lux.toml` file, after being properly deserialized.
/// This struct may be used to build a local version of a project.
/// To build a rockspec, use `RemoteProjectToml`.
#[derive(Debug)]
pub struct LocalProjectToml {
    package: PackageName,
    version: PackageVersion,
    lua: PackageVersionReq,
    rockspec_format: Option<RockspecFormat>,
    run: Option<PerPlatform<RunSpec>>,
    description: RockDescription,
    supported_platforms: PlatformSupport,
    dependencies: PerPlatform<Vec<LuaDependencySpec>>,
    build_dependencies: PerPlatform<Vec<LuaDependencySpec>>,
    external_dependencies: PerPlatform<HashMap<String, ExternalDependencySpec>>,
    test_dependencies: PerPlatform<Vec<LuaDependencySpec>>,
    test: PerPlatform<TestSpec>,
    build: PerPlatform<BuildSpec>,
    deploy: PerPlatform<DeploySpec>,

    // Used for simpler serialization
    internal: PartialProjectToml,

    /// A source pointing to the current project's root.
    source: PerPlatform<RemoteRockSource>,
}

impl LocalProjectToml {
    pub fn run(&self) -> Option<&PerPlatform<RunSpec>> {
        self.run.as_ref()
    }

    /// Convert this project TOML to a Lua rockspec.
    /// Fails if there is no valid project root or if there are off-spec dependencies.
    pub fn to_lua_rockspec(&self) -> Result<LocalLuaRockspec, LuaRockspecError> {
        if let Some(dep) = self
            .dependencies()
            .per_platform
            .values()
            .filter_map(|deps| deps.iter().find(|dep| dep.source().is_some()))
            .collect_vec()
            .first()
        {
            return Err(LuaRockspecError::OffSpecDependency(dep.name().clone()));
        }
        if let Some(dep) = self
            .build_dependencies()
            .per_platform
            .values()
            .filter_map(|deps| deps.iter().find(|dep| dep.source().is_some()))
            .collect_vec()
            .first()
        {
            return Err(LuaRockspecError::OffSpecBuildDependency(dep.name().clone()));
        }
        if let Some(dep) = self
            .test_dependencies()
            .per_platform
            .values()
            .filter_map(|deps| deps.iter().find(|dep| dep.source().is_some()))
            .collect_vec()
            .first()
        {
            return Err(LuaRockspecError::OffSpecTestDependency(dep.name().clone()));
        }
        LocalLuaRockspec::new(
            &self.to_lua_remote_rockspec_string()?,
            ProjectRoot(self.internal.lux_toml_dir.clone()),
        )
    }

    /// Renders the rockspec for local builds, using the rockspec's own version
    /// and its source pointing at the project root.
    pub fn to_local_rockspec(&self) -> Result<RemoteLuaRockspec, LuaRockspecError> {
        Ok(LocalLuaRockspec::from_project_toml(self).into_remote_with_source(self.source.clone()))
    }

    fn render_rockspec(
        &self,
        version: &PackageVersion,
        source: Option<DisplayLuaKV>,
    ) -> Result<String, ProjectTomlError> {
        let starter = format!(
            r#"
rockspec_format = "{}"
package = "{}"
version = "{}""#,
            self.rockspec_format
                .as_ref()
                .unwrap_or(&RockspecFormat::default()),
            self.package,
            version
        );

        let mut template = Vec::new();

        if self.description != RockDescription::default() {
            template.push(self.description.display_lua());
        }

        if self.supported_platforms != PlatformSupport::default() {
            template.push(self.supported_platforms.display_lua());
        }

        {
            let mut dependencies = self.internal.dependencies.clone().unwrap_or_default();
            if !self.lua.is_luau() {
                dependencies.insert(
                    0,
                    PackageReq {
                        name: "lua".into(),
                        version_req: self.lua.clone(),
                    }
                    .into(),
                );
            }
            template.push(Dependencies(&dependencies).display_lua());
        }

        let mut build_dependencies = self
            .internal
            .build_dependencies
            .as_ref()
            .cloned()
            .unwrap_or_default();

        let build_backend_dependency = self
            .internal
            .build
            .build_type
            .as_ref()
            .and_then(|build_type| build_type.luarocks_build_backend());

        if let Some(build_backend_dependency) = build_backend_dependency {
            build_dependencies.push(build_backend_dependency);
        }

        if !build_dependencies.is_empty() {
            template.push(BuildDependencies(&build_dependencies).display_lua());
        }

        match self.internal.external_dependencies {
            Some(ref external_dependencies) if !external_dependencies.is_empty() => {
                template.push(ExternalDependencies(external_dependencies).display_lua());
            }
            _ => {}
        }

        if let Some(source) = source {
            template.push(source);
        }

        template.push(
            build_spec_with_autodetected_modules(&self.internal.build, &self.internal.lux_toml_dir)
                .display_lua(),
        );

        let unformatted_code = std::iter::once(starter)
            .chain(template.into_iter().map(|kv| kv.to_string()))
            .join("\n\n");
        let result = match stylua_lib::format_code(
            &unformatted_code,
            stylua_lib::Config::default(),
            None,
            stylua_lib::OutputVerification::Full,
        ) {
            Ok(formatted_code) => formatted_code,
            Err(_) => unformatted_code,
        };
        validate_generated_lua(&result)?;
        Ok(result)
    }
}

impl Rockspec for LocalProjectToml {
    type Error = ProjectTomlError;

    fn package(&self) -> &PackageName {
        &self.package
    }

    fn version(&self) -> &PackageVersion {
        &self.version
    }

    fn description(&self) -> &RockDescription {
        &self.description
    }

    fn supported_platforms(&self) -> &PlatformSupport {
        &self.supported_platforms
    }

    fn lua(&self) -> &PackageVersionReq {
        &self.lua
    }

    fn dependencies(&self) -> &PerPlatform<Vec<LuaDependencySpec>> {
        &self.dependencies
    }

    fn build_dependencies(&self) -> &PerPlatform<Vec<LuaDependencySpec>> {
        &self.build_dependencies
    }

    fn external_dependencies(&self) -> &PerPlatform<HashMap<String, ExternalDependencySpec>> {
        &self.external_dependencies
    }

    fn test_dependencies(&self) -> &PerPlatform<Vec<LuaDependencySpec>> {
        &self.test_dependencies
    }

    fn build(&self) -> &PerPlatform<BuildSpec> {
        &self.build
    }

    fn test(&self) -> &PerPlatform<TestSpec> {
        &self.test
    }

    fn build_mut(&mut self) -> &mut PerPlatform<BuildSpec> {
        &mut self.build
    }

    fn test_mut(&mut self) -> &mut PerPlatform<TestSpec> {
        &mut self.test
    }

    fn format(&self) -> &Option<RockspecFormat> {
        &self.rockspec_format
    }

    fn source(&self) -> &PerPlatform<RemoteRockSource> {
        &self.source
    }

    fn source_mut(&mut self) -> &mut PerPlatform<RemoteRockSource> {
        &mut self.source
    }

    fn deploy(&self) -> &PerPlatform<DeploySpec> {
        &self.deploy
    }

    fn deploy_mut(&mut self) -> &mut PerPlatform<DeploySpec> {
        &mut self.deploy
    }

    fn to_lua_remote_rockspec_string(&self) -> Result<String, Self::Error> {
        let lux_toml_dir = &self.internal.lux_toml_dir;
        let version = self
            .internal
            .version_template
            .try_generate(lux_toml_dir, None)?;
        let source =
            self.internal
                .source_template
                .try_generate(lux_toml_dir, &self.package, &version)?;
        self.render_rockspec(&version, Some(source.display_lua()))
    }
}

/// Creates a [`BuildSpecInternal`] with auto-detected modules (e.g. *.luau sources)
/// that LuaRocks does not auto-detect, so that LuaRocks can install them.
fn build_spec_with_autodetected_modules(
    spec: &BuildSpecInternal,
    project_root: &Path,
) -> BuildSpecInternal {
    let builtin_capable = spec
        .build_type
        .as_ref()
        .is_none_or(|build_type| matches!(build_type, BuildType::Builtin | BuildType::None));
    if !builtin_capable {
        return spec.clone();
    }
    let detected = match autodetect_modules(project_root, Default::default()) {
        Ok(modules) => modules
            .into_iter()
            .filter_map(|(module, spec)| match spec {
                ModuleSpec::SourcePath(path)
                    if path.extension().is_some_and(|ext| ext == "luau") =>
                {
                    Some((module, path))
                }
                _ => None,
            })
            .collect_vec(),
        Err(_) => return spec.clone(),
    };
    if detected.is_empty() {
        spec.clone()
    } else {
        let mut new_spec = spec.clone();
        let modules = new_spec.builtin_spec.get_or_insert_with(Default::default);
        for (module, path) in detected {
            modules
                .entry(LuaTableKey::StringKey(module.to_string()))
                .or_insert(ModuleSpecInternal::SourcePath(path));
        }
        new_spec
    }
}

fn validate_generated_lua(lua_str: &str) -> Result<(), ProjectTomlError> {
    let mut lua = ottavino::Lua::core();
    lua.try_enter(|ctx| {
        let closure = ottavino::Closure::load(ctx, None, lua_str.as_bytes())?;
        let executor = ottavino::Executor::start(ctx, closure.into(), ());
        if !executor.step(ctx, &mut ottavino::Fuel::with(ROCKSPEC_FUEL_LIMIT))? {
            return Ok(Err(ProjectTomlError::FuelLimitExceeded));
        }
        Ok(Ok(()))
    })
    .map_err(|err| ProjectTomlError::GeneratedInvalidLua(err.to_string()))?
}

#[derive(Error, Debug, Diagnostic)]
#[non_exhaustive]
#[error(transparent)]
pub enum ProjectTomlIntegrityError {
    LuaRockspecError(#[from] LuaRockspecError),
    IoError(#[from] io::Error),
    #[error(transparent)]
    #[diagnostic(transparent)]
    Fs(#[from] fs::FsError),
}

impl HasIntegrity for LocalProjectToml {
    async fn hash(&self) -> io::Result<Integrity> {
        match self.to_lua_rockspec() {
            Ok(lua_rockspec) => lua_rockspec.hash().await,
            Err(_) => self.internal.hash().await,
        }
    }
}

/// The `lux.toml`, after being validated and prepared for upload
#[derive(Debug)]
pub struct RemoteProjectToml {
    local: LocalProjectToml,
    source: PerPlatform<RemoteRockSource>,
}

impl RemoteProjectToml {
    pub fn to_lua_rockspec(&self) -> Result<RemoteLuaRockspec, LuaRockspecError> {
        RemoteLuaRockspec::new(&self.to_lua_remote_rockspec_string()?)
    }
}

impl Rockspec for RemoteProjectToml {
    type Error = ProjectTomlError;

    fn package(&self) -> &PackageName {
        self.local.package()
    }

    fn version(&self) -> &PackageVersion {
        self.local.version()
    }

    fn description(&self) -> &RockDescription {
        self.local.description()
    }

    fn supported_platforms(&self) -> &PlatformSupport {
        self.local.supported_platforms()
    }

    fn lua(&self) -> &PackageVersionReq {
        self.local.lua()
    }

    fn dependencies(&self) -> &PerPlatform<Vec<LuaDependencySpec>> {
        self.local.dependencies()
    }

    fn build_dependencies(&self) -> &PerPlatform<Vec<LuaDependencySpec>> {
        self.local.build_dependencies()
    }

    fn external_dependencies(&self) -> &PerPlatform<HashMap<String, ExternalDependencySpec>> {
        self.local.external_dependencies()
    }

    fn test_dependencies(&self) -> &PerPlatform<Vec<LuaDependencySpec>> {
        self.local.test_dependencies()
    }

    fn build(&self) -> &PerPlatform<BuildSpec> {
        self.local.build()
    }

    fn test(&self) -> &PerPlatform<TestSpec> {
        self.local.test()
    }

    fn build_mut(&mut self) -> &mut PerPlatform<BuildSpec> {
        self.local.build_mut()
    }

    fn test_mut(&mut self) -> &mut PerPlatform<TestSpec> {
        self.local.test_mut()
    }

    fn format(&self) -> &Option<RockspecFormat> {
        self.local.format()
    }

    fn source(&self) -> &PerPlatform<RemoteRockSource> {
        &self.source
    }

    fn source_mut(&mut self) -> &mut PerPlatform<RemoteRockSource> {
        &mut self.source
    }

    fn deploy(&self) -> &PerPlatform<DeploySpec> {
        self.local.deploy()
    }

    fn deploy_mut(&mut self) -> &mut PerPlatform<DeploySpec> {
        self.local.deploy_mut()
    }

    fn to_lua_remote_rockspec_string(&self) -> Result<String, Self::Error> {
        let lux_toml_dir = &self.local.internal.lux_toml_dir;
        let starter = format!(
            r#"
rockspec_format = "{}"
package = "{}"
version = "{}""#,
            self.local
                .rockspec_format
                .as_ref()
                .unwrap_or(&RockspecFormat::default()),
            self.local.package,
            self.version()
        );

        let mut template = Vec::new();

        if self.local.description != RockDescription::default() {
            template.push(self.local.description.display_lua());
        }

        if self.local.supported_platforms != PlatformSupport::default() {
            template.push(self.local.supported_platforms.display_lua());
        }

        {
            let mut dependencies = self.local.internal.dependencies.clone().unwrap_or_default();
            if !self.local.lua.is_luau() {
                dependencies.insert(
                    0,
                    PackageReq {
                        name: "lua".into(),
                        version_req: self.local.lua.clone(),
                    }
                    .into(),
                );
            }
            template.push(Dependencies(&dependencies).display_lua());
        }

        let mut build_dependencies = self
            .local
            .internal
            .build_dependencies
            .as_ref()
            .cloned()
            .unwrap_or_default();

        let build_backend_dependency = self
            .local
            .internal
            .build
            .build_type
            .as_ref()
            .and_then(|build_type| build_type.luarocks_build_backend());

        if let Some(build_backend_dependency) = build_backend_dependency {
            build_dependencies.push(build_backend_dependency);
        }

        if !build_dependencies.is_empty() {
            template.push(BuildDependencies(&build_dependencies).display_lua());
        }

        match self.local.internal.external_dependencies {
            Some(ref external_dependencies) if !external_dependencies.is_empty() => {
                template.push(ExternalDependencies(external_dependencies).display_lua());
            }
            _ => {}
        }

        let source = self.local.internal.source_template.try_generate(
            lux_toml_dir,
            &self.local.internal.package,
            self.version(),
        )?;
        template.push(source.display_lua());

        if let Some(ref deploy) = self.local.internal.deploy {
            template.push(deploy.display_lua());
        }

        template.push(
            build_spec_with_autodetected_modules(&self.local.internal.build, lux_toml_dir)
                .display_lua(),
        );

        let unformatted_code = std::iter::once(starter)
            .chain(template.into_iter().map(|kv| kv.to_string()))
            .join("\n\n");
        let result = match stylua_lib::format_code(
            &unformatted_code,
            stylua_lib::Config::default(),
            None,
            stylua_lib::OutputVerification::Full,
        ) {
            Ok(formatted_code) => formatted_code,
            Err(_) => unformatted_code,
        };
        validate_generated_lua(&result)?;
        Ok(result)
    }
}

impl HasIntegrity for RemoteProjectToml {
    async fn hash(&self) -> io::Result<Integrity> {
        self.to_lua_rockspec()
            .map_err(|err| {
                io::Error::other(format!(
                    "unable to convert remote project to Lua rockspec:\n{}",
                    err
                ))
            })?
            .hash()
            .await
    }
}

#[cfg(test)]
mod tests {
    use std::path::PathBuf;

    use assert_fs::prelude::{PathChild, PathCopy, PathCreateDir};
    use git2::Repository;
    use url::Url;

    use crate::{
        git::{url::RemoteGitUrl, GitRef, GitSource},
        lua_rockspec::{PartialLuaRockspec, PerPlatform, RemoteLuaRockspec, RockSourceSpec},
        project::{Project, ProjectRoot, PROJECT_TOML},
        rockspec::{lua_dependency::LuaDependencySpec, Rockspec},
    };

    use super::PartialProjectToml;

    #[test]
    fn project_toml_parsing() {
        let project_toml = r#"
        package = "my-package"
        version = "1.0.0"
        lua = "5.3"

        rockspec_format = "1.0"

        [source]
        url = "https://example.com"

        [dependencies]
        foo = "1.0"
        bar = ">=2.0"

        [run]
        args = ["--foo", "--bar"]

        [build]
        type = "builtin"
        "#;

        let project =
            PartialProjectToml::new(PROJECT_TOML, project_toml, ProjectRoot::default()).unwrap();
        let _ = project.into_remote(None).unwrap();

        let project_toml = r#"
        package = "my-package"
        version = "1.0.0"
        lua = "5.1"

        [description]
        summary = "A summary"
        detailed = "A detailed description"
        license = "MIT"
        homepage = "https://example.com"
        issues_url = "https://example.com/issues"
        maintainer = "John Doe"
        labels = ["label1", "label2"]

        [supported_platforms]
        linux = true
        windows = false

        [dependencies]
        foo = "1.0"
        bar = ">=2.0"

        [build_dependencies]
        baz = "1.0"

        [external_dependencies.foo]
        header = "foo.h"

        [external_dependencies.bar]
        library = "libbar.so"

        [test_dependencies]
        busted = "69.420"

        [source]
        url = "https://example.com"
        hash = "sha256-di00mD8txN7rjaVpvxzNbnQsAh6H16zUtJZapH7U4HU="
        file = "my-package-1.0.0.tar.gz"
        dir = "my-package-1.0.0"

        [test]
        type = "command"
        script = "test.lua"
        flags = [ "foo", "bar" ]

        [run]
        command = "my-command"
        args = ["--foo", "--bar"]

        [build]
        type = "builtin"
        "#;

        let project =
            PartialProjectToml::new(PROJECT_TOML, project_toml, ProjectRoot::default()).unwrap();
        let _ = project.into_remote(None).unwrap();
    }

    #[test]
    fn compare_project_toml_with_rockspec() {
        let project_toml = r#"
        package = "my-package"
        version = "1.0.0"
        lua = "5.1"

        # For testing, specify a custom rockspec format
        # (defaults to 3.0)
        rockspec_format = "1.0"

        [description]
        summary = "A summary"
        detailed = "A detailed description"
        license = "MIT"
        homepage = "https://example.com"
        issues_url = "https://example.com/issues"
        maintainer = "John Doe"
        labels = ["label1", "label2"]

        [supported_platforms]
        linux = true
        windows = false

        [dependencies]
        foo = "1.0"
        bar = ">=2.0"

        [build_dependencies]
        baz = "1.0"

        [external_dependencies.foo]
        header = "foo.h"

        [external_dependencies.bar]
        library = "libbar.so"

        [test_dependencies]
        busted = "1.0"

        [source]
        url = "https://example.com"
        file = "my-package-1.0.0.tar.gz"
        dir = "my-package-1.0.0"

        [test]
        type = "command"
        script = "test.lua"
        flags = [ "foo", "bar" ]

        [run]
        command = "my-command"
        args = ["--foo", "--bar"]

        [deploy]
        wrap_bin_scripts = false

        [build]
        type = "builtin"

        [build.install.lua]
        "foo.bar" = "src/bar.lua"

        [build.install.lib]
        "foo.baz" = "src/baz.c"

        [build.install.bin]
        "bla" = "src/bla"

        [build.install.conf]
        "cfg.conf" = "resources/config.conf"
        "#;

        let expected_rockspec = r#"
            rockspec_format = "1.0"
            package = "my-package"
            version = "1.0.0"

            source = {
                url = "https://example.com",
                file = "my-package-1.0.0.tar.gz",
                dir = "my-package-1.0.0",
            }

            description = {
                summary = "A summary",
                detailed = "A detailed description",
                license = "MIT",
                homepage = "https://example.com",
                issues_url = "https://example.com/issues",
                maintainer = "John Doe",
                labels = {"label1", "label2"},
            }

            supported_platforms = {"linux", "!windows"}

            dependencies = {
                "lua ==5.1",
                "foo ==1.0",
                "bar >=2.0",
            }

            build_dependencies = {
                "baz ==1.0",
            }

            external_dependencies = {
                foo = { header = "foo.h" },
                bar = { library = "libbar.so" },
            }

            source = {
                url = "https://example.com",
                hash = "sha256-di00mD8txN7rjaVpvxzNbnQsAh6H16zUtJZapH7U4HU=",
                file = "my-package-1.0.0.tar.gz",
                dir = "my-package-1.0.0",
            }

            test = {
                type = "command",
                script = "test.lua",
                flags = {"foo", "bar"},
            }

            deploy = {
                wrap_bin_scripts = false,
            }

            build = {
                type = "builtin",
                install = {
                    lua = {
                        ["foo.bar"] = "src/bar.lua",
                    },
                    lib = {
                        ["foo.baz"] = "src/baz.c",
                    },
                    bin = {
                        bla = "src/bla",
                    },
                    conf = {
                        ["cfg.conf"] = "resources/config.conf",
                    },
                },
            }
        "#;

        let expected_rockspec = RemoteLuaRockspec::new(expected_rockspec).unwrap();

        let project_toml =
            PartialProjectToml::new(PROJECT_TOML, project_toml, ProjectRoot::default()).unwrap();
        let rockspec = project_toml
            .into_remote(None)
            .unwrap()
            .to_lua_rockspec()
            .unwrap();

        let sorted_package_reqs = |v: &PerPlatform<Vec<LuaDependencySpec>>| {
            let mut v = v.current_platform().clone();
            v.sort_by(|a, b| a.name().cmp(b.name()));
            v
        };

        assert_eq!(rockspec.package(), expected_rockspec.package());
        assert_eq!(rockspec.version(), expected_rockspec.version());
        assert_eq!(rockspec.description(), expected_rockspec.description());
        assert_eq!(
            rockspec.supported_platforms(),
            expected_rockspec.supported_platforms()
        );
        assert_eq!(
            sorted_package_reqs(rockspec.dependencies()),
            sorted_package_reqs(expected_rockspec.dependencies())
        );
        assert_eq!(
            sorted_package_reqs(rockspec.build_dependencies()),
            sorted_package_reqs(expected_rockspec.build_dependencies())
        );
        assert_eq!(
            rockspec.external_dependencies(),
            expected_rockspec.external_dependencies()
        );
        assert_eq!(rockspec.source(), expected_rockspec.source());
        assert_eq!(rockspec.build(), expected_rockspec.build());
        assert_eq!(rockspec.format(), expected_rockspec.format());
    }

    #[test]
    fn merge_project_toml_with_partial_rockspec() {
        let project_toml = r#"
        package = "my-package"
        version = "1.0.0"
        lua = "5.1"

        # For testing, specify a custom rockspec format
        # (defaults to 3.0)
        rockspec_format = "1.0"

        [description]
        summary = "A summary"
        detailed = "A detailed description"
        license = "MIT"
        homepage = "https://example.com"
        issues_url = "https://example.com/issues"
        maintainer = "John Doe"
        labels = ["label1", "label2"]

        [supported_platforms]
        linux = true
        windows = false

        [dependencies]
        foo = "1.0"
        bar = ">=2.0"

        [build_dependencies]
        baz = "1.0"

        [external_dependencies.foo]
        header = "foo.h"

        [external_dependencies.bar]
        library = "libbar.so"

        [test_dependencies]
        busted = "1.0"

        [source]
        url = "https://example.com"
        file = "my-package-1.0.0.tar.gz"
        dir = "my-package-1.0.0"

        [test]
        type = "command"
        script = "test.lua"
        flags = [ "foo", "bar" ]

        [run]
        command = "my-command"
        args = [ "--foo", "--bar" ]

        [build]
        type = "builtin"
        "#;

        let mergable_rockspec_content = r#"
            rockspec_format = "1.0"
            package = "my-package-overwritten"

            description = {
                summary = "A summary overwritten",
                detailed = "A detailed description overwritten",
                license = "GPL-2.0",
                homepage = "https://example.com/overwritten",
                issues_url = "https://example.com/issues/overwritten",
                maintainer = "John Doe Overwritten",
                labels = {"over", "written"},
            }

            -- Inverted supported platforms
            supported_platforms = {"!linux", "windows"}

            dependencies = {
                "lua 5.1",
                "foo >1.0",
                "bar <=2.0",
            }

            build_dependencies = {
                "baz >1.0",
            }

            external_dependencies = {
                foo = { header = "overwritten.h" },
                bar = { library = "overwritten.so" },
            }

            test = {
                type = "command",
                script = "overwritten.lua",
                flags = {"over", "written"},
            }

            build = {
                type = "builtin",
            }
        "#;

        let remote_rockspec_content = format!(
            r#"{}
            version = "1.0.0"
            source = {{
                url = "https://example.com",
                file = "my-package-1.0.0.tar.gz",
                dir = "my-package-1.0.0",
            }}
        "#,
            mergable_rockspec_content
        );

        let project_toml =
            PartialProjectToml::new(PROJECT_TOML, project_toml, ProjectRoot::default()).unwrap();
        let partial_rockspec = PartialLuaRockspec::new(mergable_rockspec_content).unwrap();
        let expected_rockspec = RemoteLuaRockspec::new(&remote_rockspec_content).unwrap();

        let merged = project_toml
            .merge(partial_rockspec)
            .into_remote(None)
            .unwrap();

        let sorted_package_reqs = |v: &PerPlatform<Vec<LuaDependencySpec>>| {
            let mut v = v.current_platform().clone();
            v.sort_by(|a, b| a.name().cmp(b.name()));
            v
        };

        assert_eq!(merged.package(), expected_rockspec.package());
        assert_eq!(merged.version(), expected_rockspec.version());
        assert_eq!(merged.description(), expected_rockspec.description());
        assert_eq!(
            merged.supported_platforms(),
            expected_rockspec.supported_platforms()
        );
        assert_eq!(
            sorted_package_reqs(merged.dependencies()),
            sorted_package_reqs(expected_rockspec.dependencies())
        );
        assert_eq!(
            sorted_package_reqs(merged.build_dependencies()),
            sorted_package_reqs(expected_rockspec.build_dependencies())
        );
        assert_eq!(
            merged.external_dependencies(),
            expected_rockspec.external_dependencies()
        );
        assert_eq!(merged.source(), expected_rockspec.source());
        assert_eq!(merged.build(), expected_rockspec.build());
        assert_eq!(merged.format(), expected_rockspec.format());
        // Ensure that the run command is retained after merge.
        assert!(merged.local.run().is_some());
    }

    #[test]
    fn wally_dependency_parsing() {
        let project_toml = r#"
        package = "my-package"
        version = "1.0.0"
        lua = "5.1"

        [dependencies.roact]
        wally = "jsdotperf/roact@^1.4.0"

        [build]
        type = "builtin"
        "#;

        let project =
            PartialProjectToml::new(PROJECT_TOML, project_toml, ProjectRoot::default()).unwrap();
        let deps = project.dependencies.unwrap();
        assert_eq!(deps.len(), 1);
        assert_eq!(deps[0].name().to_string(), "roact");
        assert!(matches!(
            deps[0].source(),
            Some(RockSourceSpec::Wally(req)) if req.name().to_string() == "jsdotperf/roact"
        ));
    }

    #[test]
    fn wally_dependency_conflicts_with_version() {
        let project_toml = r#"
        package = "my-package"
        version = "1.0.0"
        lua = "5.1"

        [dependencies.roact]
        wally = "jsdotperf/roact@^1.4.0"
        version = "1.4.0"

        [build]
        type = "builtin"
        "#;

        PartialProjectToml::new(PROJECT_TOML, project_toml, ProjectRoot::default()).unwrap_err();
    }

    #[test]
    fn project_toml_with_lua_in_dependencies() {
        let project_toml = r#"
        package = "my-package"
        version = "1.0.0"
        # lua = ">5.1"

        [dependencies]
        lua = "5.1" # disallowed

        [build]
        type = "builtin"
        "#;

        PartialProjectToml::new(PROJECT_TOML, project_toml, ProjectRoot::default())
            .unwrap()
            .into_local()
            .unwrap_err();
    }

    #[test]
    fn project_toml_with_invalid_run_command() {
        for command in ["lua", "lua5.1", "lua5.2", "lua5.3", "lua5.4", "luajit"] {
            let project_toml = format!(
                r#"
                package = "my-package"
                version = "1.0.0"
                lua = "5.1"

                [build]
                type = "builtin"

                [run]
                command = "{command}"
                "#,
            );

            PartialProjectToml::new(PROJECT_TOML, &project_toml, ProjectRoot::default())
                .unwrap_err();
        }
    }

    #[test]
    fn project_root_dir_override_and_rockspec_generation() {
        let project_toml = r#"
        package = "my-package"
        version = "1.0.0"
        lua = "5.1"

        [project]
        root_dir = ".."

        [source]
        url = "https://example.com"

        [build]
        type = "builtin"
        "#;

        let workspace_root = assert_fs::TempDir::new().unwrap();
        let lux_toml_dir = workspace_root.child("proj");
        lux_toml_dir.create_dir_all().unwrap();
        std::fs::write(lux_toml_dir.join(PROJECT_TOML), project_toml).unwrap();

        let project = PartialProjectToml::new(
            PROJECT_TOML,
            project_toml,
            ProjectRoot(lux_toml_dir.to_path_buf()),
        )
        .unwrap();
        let local = project.into_local().unwrap();
        let RockSourceSpec::File(root_dir) = &local.source().current_platform().source_spec else {
            panic!("expected a file source");
        };
        assert_eq!(
            root_dir,
            &std::fs::canonicalize(workspace_root.path()).unwrap()
        );

        // The `[project]` table must be ignored when generating a rockspec.
        let rockspec = local.to_lua_rockspec().unwrap();
        assert!(!rockspec
            .to_lua_remote_rockspec_string()
            .unwrap()
            .contains("root_dir"));
    }

    #[test]
    fn generate_non_deterministic_git_source() {
        let rockspec_content = r#"
            package = "test-package"
            version = "1.0.0"
            lua = ">=5.1"

            [source]
            url = "git+https://exaple.com/repo.git"

            [build]
            type = "builtin"
        "#;

        PartialProjectToml::new(PROJECT_TOML, rockspec_content, ProjectRoot::default())
            .unwrap()
            .into_remote(None)
            .unwrap_err();
    }

    #[test]
    fn generate_deterministic_git_source() {
        let rockspec_content = r#"
            package = "test-package"
            version = "1.0.0"
            lua = ">=5.1"

            [source]
            url = "git+https://exaple.com/owner/repo.git"
            tag = "v0.1.0"

            [build]
            type = "builtin"
        "#;

        PartialProjectToml::new(PROJECT_TOML, rockspec_content, ProjectRoot::default())
            .unwrap()
            .into_remote(None)
            .unwrap();
    }

    #[test]
    fn generate_git_source_with_branch() {
        let rockspec_content = r#"
            package = "test-package"
            version = "1.0.0"
            lua = ">=5.1"

            [source]
            url = "git+https://example.com/owner/repo.git"
            branch = "main"

            [build]
            type = "builtin"
        "#;

        let toml = PartialProjectToml::new(PROJECT_TOML, rockspec_content, ProjectRoot::default())
            .unwrap()
            .into_remote(None)
            .unwrap();

        let lua = toml.to_lua_remote_rockspec_string().unwrap();
        assert!(lua.contains("branch = \"main\""));
        assert!(!lua.contains("tag = "));
    }

    fn init_git_repo(path: &std::path::Path) -> Repository {
        let repo = Repository::init(path).unwrap();
        {
            let tree_id = repo.index().unwrap().write_tree().unwrap();
            let tree = repo.find_tree(tree_id).unwrap();
            let sig = git2::Signature::now("name", "email").unwrap();
            repo.commit(Some("HEAD"), &sig, &sig, "initial", &tree, &[])
                .unwrap();
        }
        repo
    }

    fn init_sample_project_repo(temp_dir: &assert_fs::TempDir) -> Repository {
        let sample_project = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .join("resources/test/sample-projects/source-template/");
        temp_dir.copy_from(&sample_project, &["**"]).unwrap();
        init_git_repo(temp_dir.path())
    }

    fn create_tag(repo: &Repository, name: &str) {
        let sig = git2::Signature::now("name", "email").unwrap();
        let id = repo.head().unwrap().target().unwrap();
        let obj = repo.find_object(id, None).unwrap();
        repo.tag(name, &obj, &sig, "msg", true).unwrap();
    }

    #[test]
    fn test_git_project_generate_dev_source() {
        let project_root = assert_fs::TempDir::new().unwrap();
        init_sample_project_repo(&project_root);
        let project = Project::from_exact(&project_root).unwrap().unwrap();
        let remote_project_toml = project.toml().into_remote(None).unwrap();
        let source = remote_project_toml.source.current_platform();
        let source_spec = &source.source_spec;
        assert!(matches!(source_spec, &RockSourceSpec::Git { .. }));
        if let RockSourceSpec::Git(GitSource { url, git_ref }) = source_spec {
            let expected_url: RemoteGitUrl =
                "https://github.com/lumen-oss/lux.git".parse().unwrap();
            assert_eq!(url, &expected_url);
            assert!(git_ref.is_some());
        }
        assert_eq!(source.unpack_dir, Some("lux-dev".into()));
    }

    #[test]
    fn test_git_project_generate_non_semver_tag_source() {
        let project_root = assert_fs::TempDir::new().unwrap();
        let repo = init_sample_project_repo(&project_root);
        let tag_name = "bla";
        create_tag(&repo, tag_name);
        let project = Project::from_exact(&project_root).unwrap().unwrap();
        let remote_project_toml = project.toml().into_remote(None).unwrap();
        let source = remote_project_toml.source.current_platform();
        let source_spec = &source.source_spec;
        assert!(matches!(source_spec, &RockSourceSpec::Git { .. }));
        if let RockSourceSpec::Git(GitSource { url, git_ref }) = source_spec {
            let expected_url: RemoteGitUrl =
                "https://github.com/lumen-oss/lux.git".parse().unwrap();
            assert_eq!(url, &expected_url);
            assert_eq!(git_ref, &Some(GitRef::Tag(tag_name.to_string())));
        }
        assert_eq!(source.unpack_dir, Some("lux-dev".into()));
    }

    #[test]
    fn test_git_project_generate_release_source_tag_with_v_prefix() {
        let project_root = assert_fs::TempDir::new().unwrap();
        let repo = init_sample_project_repo(&project_root);
        let tag_name = "v1.0.0";
        create_tag(&repo, "bla");
        create_tag(&repo, tag_name);
        let project = Project::from_exact(&project_root).unwrap().unwrap();
        let remote_project_toml = project.toml().into_remote(None).unwrap();
        let source = remote_project_toml.source.current_platform();
        let source_spec = &source.source_spec;
        assert!(matches!(source_spec, &RockSourceSpec::Url { .. }));
        if let RockSourceSpec::Url(url) = source_spec {
            let expected_url: Url = "https://github.com/lumen-oss/lux/archive/refs/tags/v1.0.0.zip"
                .parse()
                .unwrap();
            assert_eq!(url, &expected_url);
        }
        assert_eq!(source.unpack_dir, Some("lux-1.0.0".into()));
    }

    #[test]
    fn test_git_project_generate_release_source_tag_without_v_prefix() {
        let project_root = assert_fs::TempDir::new().unwrap();
        let repo = init_sample_project_repo(&project_root);
        create_tag(&repo, "bla");
        let tag_name = "1.0.0";
        create_tag(&repo, tag_name);
        let project = Project::from_exact(&project_root).unwrap().unwrap();
        let remote_project_toml = project.toml().into_remote(None).unwrap();
        let source = remote_project_toml.source.current_platform();
        let source_spec = &source.source_spec;
        assert!(matches!(source_spec, &RockSourceSpec::Url { .. }));
        if let RockSourceSpec::Url(url) = source_spec {
            let expected_url: Url = "https://github.com/lumen-oss/lux/archive/refs/tags/1.0.0.zip"
                .parse()
                .unwrap();
            assert_eq!(url, &expected_url);
        }
        assert_eq!(source.unpack_dir, Some("lux-1.0.0".into()));
    }

    #[test]
    fn test_git_project_in_subdirectory() {
        let temp_dir = assert_fs::TempDir::new().unwrap();
        let sample_project = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .join("resources/test/sample-projects/source-template/");
        let project_dir = temp_dir.child("lux");
        project_dir.create_dir_all().unwrap();
        project_dir.copy_from(&sample_project, &["**"]).unwrap();
        let repo = init_git_repo(temp_dir.path());
        create_tag(&repo, "bla");
        let tag_name = "1.0.0";
        create_tag(&repo, tag_name);
        let project = Project::from_exact(&project_dir).unwrap().unwrap();
        let remote_project_toml = project.toml().into_remote(None).unwrap();
        let source = remote_project_toml.source.current_platform();
        let source_spec = &source.source_spec;
        assert!(matches!(source_spec, &RockSourceSpec::Url { .. }));
        if let RockSourceSpec::Url(url) = source_spec {
            let expected_url: Url = "https://github.com/lumen-oss/lux/archive/refs/tags/1.0.0.zip"
                .parse()
                .unwrap();
            assert_eq!(url, &expected_url);
        }
        assert_eq!(source.unpack_dir, Some("lux-1.0.0".into()));
    }

    #[test]
    fn test_git_project_in_subdirectory_generate_dev_source() {
        let temp_dir = assert_fs::TempDir::new().unwrap();
        let sample_project = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .join("resources/test/sample-projects/source-template/");
        let project_dir = temp_dir.child("lux");
        project_dir.create_dir_all().unwrap();
        project_dir.copy_from(&sample_project, &["**"]).unwrap();
        init_git_repo(temp_dir.path());

        let project = Project::from_exact(&project_dir).unwrap().unwrap();
        let remote_project_toml = project.toml().into_remote(None).unwrap();
        let RockSourceSpec::Git(GitSource { git_ref, .. }) =
            &remote_project_toml.source.current_platform().source_spec
        else {
            panic!("expected a git source");
        };
        assert!(git_ref.is_some());
    }
}