wdl-modules 0.3.2

//! `module.json` manifest parsing and validation.

use std::collections::BTreeMap;
use std::path::Path;
use std::path::PathBuf;

use serde::Deserialize;
use serde::Deserializer;
use serde::Serialize;
use thiserror::Error;
use url::Url;

use crate::DEFAULT_ENTRYPOINT_FILENAME;
use crate::DEFAULT_README_FILENAME;
use crate::dependency::DependencyName;
use crate::dependency::DependencyNameError;
use crate::dependency::DependencySource;
use crate::dependency::DependencySourceError;
use crate::license::LicenseError;
use crate::license::LicenseExpression;
use crate::relative_path::RelativePath;
use crate::relative_path::RelativePathError;

/// An error parsing a [`Manifest`].
///
/// Parsing is strict per the spec; trailing commas, comments, BOM, and
/// duplicate object keys at any nesting depth are all rejected.
#[derive(Debug, Error)]
pub enum ManifestError {
    /// The bytes did not parse as JSON.
    #[error("invalid `module.json` JSON")]
    InvalidJson(#[from] serde_json::Error),

    /// The `name` field is empty.
    #[error("`name` cannot be empty")]
    EmptyName,

    /// The `entrypoint` path failed relative-path validation.
    #[error("`entrypoint` is invalid")]
    InvalidEntrypoint(#[source] RelativePathError),

    /// The `readme` path failed relative-path validation.
    #[error("`readme` is invalid")]
    InvalidReadme(#[source] RelativePathError),

    /// An `exclude` entry failed relative-path validation.
    #[error("`exclude` entry `{pattern}` is invalid")]
    InvalidExclude {
        /// The offending pattern as written in the manifest.
        pattern: String,
        /// The underlying validation error.
        #[source]
        source: RelativePathError,
    },

    /// The `readme` field was set to the literal `true`. The schema only
    /// accepts a string, the literal `false`, or absence; `true` is
    /// rejected with a dedicated message because it is a common authoring
    /// mistake (mirroring `false` to mean "enable the default readme").
    #[error("`readme` cannot be set to `true`; omit the field to use the default `README.md`")]
    ReadmeTrue,

    /// A dependency key is not a valid WDL identifier.
    #[error("`dependencies` key `{name}` is not a valid WDL identifier")]
    InvalidDependencyName {
        /// The offending dependency key.
        name: String,
        /// Why the key is not a valid dependency name.
        #[source]
        source: DependencyNameError,
    },

    /// Two dependency keys resolve to the same dependency (either
    /// identical or equivalent after hyphen-to-underscore normalization).
    #[error("duplicate `dependencies` key: `{0}` and `{1}` resolve to the same dependency")]
    DuplicateDependencyName(String, String),

    /// A `tools[].ids` entry is not a valid CURIE.
    #[error("tool identifier `{0}` is not a valid CURIE of the form `prefix:reference`")]
    InvalidToolId(String),

    /// A dependency declaration is invalid.
    #[error(transparent)]
    DependencySource(#[from] DependencySourceError),

    /// The `license` field is not a valid SPDX expression.
    #[error(transparent)]
    License(#[from] LicenseError),

    /// An I/O error occurred reading the manifest from disk.
    #[error("failed to read `{path}`")]
    Io {
        /// The path that failed to read.
        path: PathBuf,
        /// The underlying I/O error.
        #[source]
        source: std::io::Error,
    },
}

/// The `readme` field of a manifest.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Readme {
    /// The `readme` field was omitted; engines look for `README.md`.
    Default,
    /// The `readme` field is a relative path to a markdown file.
    Path(RelativePath),
    /// The `readme` field is the literal `false`; no readme is associated
    /// with the module.
    Disabled,
}

/// A `tools[]` entry.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct Tool {
    /// The tool name.
    pub name: String,
    /// The tool version.
    pub version: String,
    /// The tool's SPDX license identifier.
    pub license: LicenseExpression,
    /// URL for the tool's homepage, documentation, repository, or
    /// canonical project page.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub url: Option<Url>,
    /// External identifiers for the tool, each a [CURIE](https://www.w3.org/TR/curie/)
    /// of the form `prefix:reference` (e.g. `doi:10.21105/joss.04704`,
    /// `biotools:csvkit`). Validated at parse time.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub ids: Vec<String>,
    /// Unknown fields, preserved for round-trip and inspection by
    /// downstream linters.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, serde_json::Value>,
}

/// A parsed `module.json`.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Manifest {
    /// The module's display name. Not used for dependency resolution.
    pub name: String,
    /// The module's SPDX license expression.
    pub license: LicenseExpression,
    /// The author descriptions.
    pub authors: Vec<String>,
    /// A brief description of the module.
    pub description: Option<String>,
    /// The canonical Git URL for the module's source repository.
    pub repository: Option<Url>,
    /// A URL for the module's documentation or landing page.
    pub homepage: Option<Url>,
    /// The path to the module's entrypoint WDL file, relative to the
    /// module root. Defaults to [`DEFAULT_ENTRYPOINT_FILENAME`] if absent.
    pub entrypoint: Option<RelativePath>,
    /// The module's readme.
    pub readme: Readme,
    /// Gitignore-style glob patterns identifying files within the module
    /// that consumers may not reach via symbolic import. Each entry is a
    /// validated [`RelativePath`]; absolute paths, `..` segments, and
    /// other invalid forms are rejected at parse time. Has no effect on
    /// content hashing, signing, validation, or quoted within-module
    /// imports.
    pub exclude: Vec<RelativePath>,
    /// The upstream tools wrapped by the module.
    pub tools: Vec<Tool>,
    /// The module's dependencies, keyed by consumer-chosen name.
    pub dependencies: BTreeMap<DependencyName, DependencySource>,
    /// Unknown top-level fields. The spec requires implementations to
    /// ignore unrecognized fields; capturing them here lets downstream
    /// linters surface typos without a re-parse.
    pub extra: serde_json::Map<String, serde_json::Value>,
}

impl Manifest {
    /// Parses a `module.json` from raw bytes.
    pub fn parse(bytes: &[u8]) -> Result<Self, ManifestError> {
        let raw: ManifestFields = crate::strict_json::from_slice(bytes)?;
        raw.try_into()
    }

    /// Returns the entrypoint filename, falling back to
    /// [`DEFAULT_ENTRYPOINT_FILENAME`] when
    /// [`entrypoint`](Self::entrypoint) is unset.
    pub fn entrypoint_filename(&self) -> &Path {
        self.entrypoint
            .as_ref()
            .map(RelativePath::as_path)
            .unwrap_or(Path::new(DEFAULT_ENTRYPOINT_FILENAME))
    }

    /// Returns the readme filename, falling back to
    /// [`DEFAULT_README_FILENAME`] when [`readme`](Self::readme) is
    /// [`Readme::Default`], or `None` when it is [`Readme::Disabled`].
    pub fn readme_filename(&self) -> Option<&Path> {
        match &self.readme {
            Readme::Default => Some(Path::new(DEFAULT_README_FILENAME)),
            Readme::Path(path) => Some(path.as_path()),
            Readme::Disabled => None,
        }
    }
}

/// Flat field set of a manifest, deserialized straight from JSON before
/// post-deserialization validation projects it onto [`Manifest`].
#[derive(Debug, Deserialize)]
struct ManifestFields {
    /// The module's display name.
    name: String,
    /// The module's SPDX license.
    license: String,
    /// The author descriptions.
    #[serde(default)]
    authors: Vec<String>,
    /// A brief description of the module.
    #[serde(default)]
    description: Option<String>,
    /// The canonical Git URL for the module's source repository.
    #[serde(default)]
    repository: Option<Url>,
    /// A URL for the module's documentation or landing page.
    #[serde(default)]
    homepage: Option<Url>,
    /// The path to the module's entrypoint WDL file.
    #[serde(default)]
    entrypoint: Option<PathBuf>,
    /// The `readme` field, accepting a string, `false`, or absence.
    #[serde(default, deserialize_with = "deserialize_readme")]
    readme: ReadmeFields,
    /// Gitignore-style glob patterns identifying files outside the public
    /// import surface.
    #[serde(default)]
    exclude: Vec<String>,
    /// The upstream tools.
    #[serde(default)]
    tools: Vec<Tool>,
    /// The module's dependencies.
    #[serde(default)]
    dependencies: BTreeMap<String, DependencySource>,
    /// Unknown top-level fields.
    #[serde(flatten)]
    extra: serde_json::Map<String, serde_json::Value>,
}

/// The `readme` field's JSON shape; one of a string, `false`, or absent.
/// The values `null` and `true` are rejected at parse time.
#[derive(Debug, Default)]
enum ReadmeFields {
    /// A relative path to a readme file.
    Path(PathBuf),
    /// The literal `false`, disabling the readme.
    Bool(bool),
    /// The field was absent.
    #[default]
    Default,
}

/// Returns true when `s` is a CURIE of the form `prefix:reference`,
/// where the prefix matches `[A-Za-z_][A-Za-z0-9._-]*` and the reference
/// is non-empty. Mirrors the pattern in the module manifest JSON schema.
fn is_curie(s: &str) -> bool {
    let Some((prefix, reference)) = s.split_once(':') else {
        return false;
    };
    if reference.is_empty() {
        return false;
    }
    let mut chars = prefix.chars();
    match chars.next() {
        Some(c) if c.is_ascii_alphabetic() || c == '_' => {}
        _ => return false,
    }
    chars.all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-'))
}

/// Deserializes the `readme` field, accepting `false` or a string path.
fn deserialize_readme<'de, D>(deserializer: D) -> Result<ReadmeFields, D::Error>
where
    D: Deserializer<'de>,
{
    let value = serde_json::Value::deserialize(deserializer)?;
    match value {
        serde_json::Value::String(s) => Ok(ReadmeFields::Path(PathBuf::from(s))),
        serde_json::Value::Bool(b) => Ok(ReadmeFields::Bool(b)),
        serde_json::Value::Null => Err(serde::de::Error::custom("`readme` cannot be null")),
        other => Err(serde::de::Error::custom(format!(
            "`readme` must be a string or `false`; got {other}"
        ))),
    }
}

impl TryFrom<ManifestFields> for Manifest {
    type Error = ManifestError;

    fn try_from(fields: ManifestFields) -> Result<Self, Self::Error> {
        if fields.name.is_empty() {
            return Err(ManifestError::EmptyName);
        }

        let license = fields.license.parse::<LicenseExpression>()?;

        let entrypoint = fields
            .entrypoint
            .as_deref()
            .map(RelativePath::try_from)
            .transpose()
            .map_err(ManifestError::InvalidEntrypoint)?;

        let readme = match fields.readme {
            ReadmeFields::Default => Readme::Default,
            ReadmeFields::Path(p) => Readme::Path(
                RelativePath::try_from(p.as_path()).map_err(ManifestError::InvalidReadme)?,
            ),
            ReadmeFields::Bool(false) => Readme::Disabled,
            ReadmeFields::Bool(true) => return Err(ManifestError::ReadmeTrue),
        };

        let mut deps: BTreeMap<DependencyName, DependencySource> = BTreeMap::new();
        for (key, value) in fields.dependencies {
            let name = key
                .parse()
                .map_err(|source| ManifestError::InvalidDependencyName {
                    name: key.clone(),
                    source,
                })?;
            if let Some((existing, _)) = deps.get_key_value(&name) {
                return Err(ManifestError::DuplicateDependencyName(
                    existing.manifest().to_string(),
                    name.manifest().to_string(),
                ));
            }
            deps.insert(name, value);
        }

        let exclude = fields
            .exclude
            .into_iter()
            .map(|pattern| {
                pattern
                    .parse::<RelativePath>()
                    .map_err(|source| ManifestError::InvalidExclude { pattern, source })
            })
            .collect::<Result<Vec<_>, _>>()?;

        for tool in &fields.tools {
            for id in &tool.ids {
                if !is_curie(id) {
                    return Err(ManifestError::InvalidToolId(id.clone()));
                }
            }
        }

        Ok(Self {
            name: fields.name,
            license,
            authors: fields.authors,
            description: fields.description,
            repository: fields.repository,
            homepage: fields.homepage,
            entrypoint,
            readme,
            exclude,
            tools: fields.tools,
            dependencies: deps,
            extra: fields.extra,
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn parse(s: &str) -> Result<Manifest, ManifestError> {
        Manifest::parse(s.as_bytes())
    }

    #[test]
    fn parses_minimal_manifest() {
        let m = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT"
            }"#,
        )
        .unwrap();
        assert_eq!(m.name, "spellbook");
        assert_eq!(m.license.as_str(), "MIT");
        assert!(m.authors.is_empty());
        assert!(matches!(m.readme, Readme::Default));
        assert_eq!(m.entrypoint_filename(), Path::new("index.wdl"));
    }

    #[test]
    fn parses_full_example() {
        let m = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT OR Apache-2.0",
                "authors": ["Jane Doe <jane.doe@example.com>"],
                "description": "spellbook wrapper",
                "repository": "https://github.com/openwdl/spellbook",
                "homepage": "https://example.com",
                "tools": [
                    {
                        "name": "spellcheck",
                        "version": "2.0.1",
                        "license": "MIT",
                        "url": "https://example.com/sc",
                        "ids": ["doi:10.21105/joss.04704", "biotools:csvkit"]
                    }
                ],
                "dependencies": {
                    "common": {
                        "git": "https://github.com/openwdl/common",
                        "version": "^1.0.0"
                    },
                    "local_utils": { "path": "../utils" }
                }
            }"#,
        )
        .unwrap();
        assert_eq!(m.tools.len(), 1);
        assert_eq!(
            m.tools[0].url.as_ref().unwrap().as_str(),
            "https://example.com/sc"
        );
        assert_eq!(
            m.tools[0].ids,
            ["doi:10.21105/joss.04704", "biotools:csvkit"]
        );
        assert_eq!(m.dependencies.len(), 2);
    }

    #[test]
    fn rejects_non_curie_tool_id() {
        let err = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "tools": [
                    {
                        "name": "spellcheck",
                        "version": "2.0.1",
                        "license": "MIT",
                        "ids": ["not a curie"]
                    }
                ]
            }"#,
        )
        .unwrap_err();
        assert!(
            matches!(&err, ManifestError::InvalidToolId(id) if id == "not a curie"),
            "expected `InvalidToolId`, got: {err}"
        );
    }

    #[test]
    fn accepts_various_curie_prefixes() {
        assert!(is_curie("doi:10.21105/joss.04704"));
        assert!(is_curie("biotools:csvkit"));
        assert!(is_curie("_local:x"));
        assert!(is_curie("a.b-c_d:ref"));
        assert!(!is_curie("nocolon"));
        assert!(!is_curie(":noprefix"));
        assert!(!is_curie("prefix:"));
        assert!(!is_curie("1bad:ref"));
    }

    #[test]
    fn parses_readme_disabled() {
        let m = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "readme": false
            }"#,
        )
        .unwrap();
        assert!(matches!(m.readme, Readme::Disabled));
    }

    #[test]
    fn parses_readme_path() {
        let m = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "readme": "docs/README.md"
            }"#,
        )
        .unwrap();
        assert!(matches!(m.readme, Readme::Path(_)));
    }

    #[test]
    fn resolves_default_readme_filename() -> Result<(), ManifestError> {
        let manifest = parse(r#"{"name":"spellbook","license":"MIT"}"#)?;
        assert_eq!(
            manifest.readme_filename(),
            Some(Path::new(crate::DEFAULT_README_FILENAME))
        );
        Ok(())
    }

    #[test]
    fn resolves_custom_readme_filename() -> Result<(), ManifestError> {
        let manifest = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "readme": "docs/guide.md"
            }"#,
        )?;
        assert_eq!(manifest.readme_filename(), Some(Path::new("docs/guide.md")));
        Ok(())
    }

    #[test]
    fn disabled_readme_has_no_filename() -> Result<(), ManifestError> {
        let manifest = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "readme": false
            }"#,
        )?;
        assert_eq!(manifest.readme_filename(), None);
        Ok(())
    }

    #[test]
    fn captures_unknown_top_level_fields() {
        let m = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "extra_field": 42,
                "metadata": {"key": "value"}
            }"#,
        )
        .unwrap();
        assert!(m.extra.contains_key("extra_field"));
        assert!(m.extra.contains_key("metadata"));
    }

    #[test]
    fn rejects_empty_name() {
        let err = parse(r#"{ "name": "", "license": "MIT" }"#).unwrap_err();
        assert!(matches!(err, ManifestError::EmptyName));
    }

    #[test]
    fn rejects_invalid_license() {
        let err = parse(r#"{ "name": "spellbook", "license": "MIT-2.0" }"#).unwrap_err();
        assert!(matches!(err, ManifestError::License(_)));
    }

    #[test]
    fn rejects_absolute_entrypoint() {
        let err = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "entrypoint": "/abs/path.wdl"
            }"#,
        )
        .unwrap_err();
        assert!(matches!(err, ManifestError::InvalidEntrypoint(_)));
    }

    #[test]
    fn rejects_readme_true() {
        let err = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "readme": true
            }"#,
        )
        .unwrap_err();
        assert!(matches!(err, ManifestError::ReadmeTrue));
    }

    #[test]
    fn rejects_readme_null() {
        let err = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "readme": null
            }"#,
        )
        .unwrap_err();
        assert!(matches!(err, ManifestError::InvalidJson(_)));
    }

    #[test]
    fn parses_exclude_field() {
        let m = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "exclude": ["internal/**", "scratch/*.wdl"]
            }"#,
        )
        .unwrap();
        assert_eq!(
            m.exclude
                .iter()
                .map(RelativePath::as_str)
                .collect::<Vec<_>>(),
            vec!["internal/**", "scratch/*.wdl"]
        );
    }

    #[test]
    fn rejects_invalid_exclude_entry() {
        let err = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "exclude": ["internal/**", "/abs/path"]
            }"#,
        )
        .unwrap_err();
        match err {
            ManifestError::InvalidExclude { pattern, .. } => {
                assert_eq!(pattern, "/abs/path");
            }
            other => panic!("expected `InvalidExclude` variant; got {other:?}"),
        }
    }

    #[test]
    fn rejects_parent_dir_in_readme() {
        let err = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "readme": "../escape.md"
            }"#,
        )
        .unwrap_err();
        assert!(matches!(err, ManifestError::InvalidReadme(_)));
    }

    fn assert_duplicate_key_error(err: ManifestError) {
        let inner = match err {
            ManifestError::InvalidJson(e) => e.to_string(),
            other => panic!("expected `InvalidJson` variant; got {other:?}"),
        };
        assert!(
            inner.contains("duplicate object key"),
            "wrong inner message: {inner}"
        );
    }

    #[test]
    fn rejects_duplicate_top_level_keys() {
        assert_duplicate_key_error(
            parse(
                r#"{
                    "name": "spellbook",
                    "name": "duplicate",
                    "license": "MIT"
                }"#,
            )
            .unwrap_err(),
        );
    }

    #[test]
    fn rejects_duplicate_nested_keys() {
        assert_duplicate_key_error(
            parse(
                r#"{
                    "name": "spellbook",
                    "license": "MIT",
                    "tools": [
                        {"name": "x", "name": "y", "version": "1", "license": "MIT"}
                    ]
                }"#,
            )
            .unwrap_err(),
        );
    }

    #[test]
    fn accepts_hyphenated_dep_key() {
        let m = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "dependencies": { "my-dep": {"path": "../local"} }
            }"#,
        )
        .unwrap();
        let key: DependencyName = "my-dep".parse().unwrap();
        assert!(m.dependencies.contains_key(&key));
        assert_eq!(key.manifest(), "my-dep");
        assert_eq!(key.identifier(), "my_dep");
    }

    #[test]
    fn rejects_exact_duplicate_dep_keys() {
        let err = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "dependencies": {
                    "dep": {"path": "../a"},
                    "dep": {"path": "../b"}
                }
            }"#,
        )
        .unwrap_err();
        assert!(
            matches!(err, ManifestError::InvalidJson(_)),
            "exact duplicate JSON keys should be rejected by strict JSON parsing, got: {err}"
        );
    }

    #[test]
    fn rejects_duplicate_hyphen_underscore_dep_keys() {
        let err = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "dependencies": {
                    "spell-book": {"path": "../a"},
                    "spell_book": {"path": "../b"}
                }
            }"#,
        )
        .unwrap_err();
        assert!(
            matches!(err, ManifestError::DuplicateDependencyName(..)),
            "expected `DuplicateDependencyName`, got: {err}"
        );
    }

    #[test]
    fn rejects_non_identifier_dep_key() {
        let err = parse(
            r#"{
                "name": "spellbook",
                "license": "MIT",
                "dependencies": { "1bad": {"path": "../local"} }
            }"#,
        )
        .unwrap_err();
        assert!(matches!(err, ManifestError::InvalidDependencyName { .. }));
    }
}