Improve the manifest contract

Adds more fields and makes the semver contracts more accurate

Author: jneem

core/stdlib/std.ncl

@@ -2801,59 +2801,132 @@
   },
 
   package =
-    let
+    let rec
     # https://semver.org is kind enough to supply this "official" semver regex.
-    semver_re = m%"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"% in let
-    # An expression representing a range of semver versions, like `<1.2`.
-    # Unlike semver itself, semver range expressions don't seem to have an official standard.
-    semver_main_range_re = m%"(~|=|\^|<|>|<=|>=)?(0|[1-9]\d*)(\.(0|[1-9]\d*))?(\.(0|[1-9]\d*))?"% in let
-    # For requirements with non-empty prereleases, we support exactly two flavors: 0.1.2-pre3 or =0.1.2-pre3.
-    # We could also support inequalities, but we should avoid ^ and ~ because prereleases have no guaranteed
-    # compatibility semantics.
-    semver_prerelease_range_re = m%"=?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-((0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*)"% in let semver_range_re = "(%{semver_main_range_re})|(%{semver_prerelease_range_re})" in
-    let semver_req_re = m%"^(%{semver_range_re}(,\s*%{semver_range_re})*)$"% in
-    {
+    semver_re_unanchored = m%"(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?"%,
+    semver_re = "^%{semver_re_unanchored}$",
+    # Just the major.minor.patch part, with minor and patch being optional.
+    partial_semver_re_unanchored = m%"(0|[1-9]\d*)(\.(0|[1-9]\d*))?(\.(0|[1-9]\d*))?"%,
+    partial_semver_re = "^%{partial_semver_re_unanchored}$",
+    # An exact version constraint. This one is required to have minor and patch versions, and it's allowed to have a prerelease.
+    semver_equals_req_re = m%"^=(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?$"%,
+    semver_req_re = "(%{partial_semver_re})|(%{semver_equals_req_re})",
+    in {
       is_semver_req
         : String -> Bool
         | doc m%"
-        Returns true if a string is a valid semantic version requirement.
+        Returns true if a string is a valid version requirement in Nickel.
+
+        See the `SemverReq` contract for more details.
       "%
         = std.string.is_match semver_req_re,
       is_semver
         : String -> Bool
         | doc m%"
-        Returns true if a string is a valid semantic version identifier.
+        Returns true if a string is a valid semantic version.
+
+        # Examples
+
+        ```nickel multiline
+        std.package.is_semver "1.2.0-pre1"
+        # => true
+
+        std.package.is_semver "1.foo"
+        # => false
+        ```
       "%
         = std.string.is_match semver_re,
+      is_semver_prefix
+        : String -> Bool
+        | doc m%"
+        Returns true if a string is a valid semantic version prefix,
+        containing a major version and then optional minor and patch versions.
+
+        # Examples
+
+        ```nickel multiline
+        std.package.is_semver_prefix "1.2"
+        # => true
+
+        std.package.is_semver_prefix "1.foo"
+        # => false
+        ```
+      "%
+        = std.string.is_match partial_semver_re,
       Semver
         | doc m%"
         A contract for semantic version ("semver") identifiers.
 
         # Examples
 
-        ```nickel
+        ```nickel multiline
         "1.2.0-pre1" | std.package.Semver
-        => "1.2.0-pre1"
+        # => "1.2.0-pre1"
 
         "1.foo" | std.package.Semver
-        => error: contract broken by a value
+        # => error: contract broken by a value
         ```
       "%
         = std.contract.from_predicate is_semver,
+      SemverPrefix
+        | doc m%"
+        A contract for semantic version ("semver") prefixes,
+        containing a major version and then optional minor and patch versions.
+
+        # Examples
+
+        ```nickel multiline
+        "1.2" | std.package.SemverPrefix
+        # => "1.2"
+
+        "1.foo" | std.package.SemverPrefix
+        # => error: contract broken by a value
+        ```
+      "%
+        = std.contract.from_predicate is_semver_prefix,
       SemverReq
         | doc m%"
         A contract for semantic version ("semver") requirements.
 
+        Nickel supports two kinds of requirements: semver-compatible
+        requirements and exact version requirements. Semver-compatible
+        requirements take the form "major.minor.patch", where minor and patch
+        are optional. Their semantics are:
+
+        - "1.2.3" will match all versions having major version 1, minor version 2,
+          and patch version at least 3.
+        - "1.2" will match all versions having major version 1 and minor version
+          at least 2.
+        - "1" will match all versions having major version 1.
+        - a semver-compatible requirement will never match a prerelease version.
+
+        Exact version requirements take the form "=major.minor.patch-pre", where
+        the prerelease tag is optional, but major, minor, and patch are all required.
+
         # Examples
 
-        ```nickel
-        "^1.2" | std.package.SemverReq
-        => "^1.2"
+        ```nickel multiline
+        "1.2" | SemverReq
+        # => "1.2"
 
-        ">=1.2, <1.4" | std.package.SemverReq
-        => ">=1.2, <1.4"
+        "=1.2" | SemverReq
+        # => error: contract broken by a value
+
+        "1.2.0" | SemverReq
+        # => "1.2.0"
+
+        "=1.2.0" | SemverReq
+        # => "=1.2.0"
+
+        "1.2.0-pre1" | SemverReq
+        # => error: contract broken by a value
+
+        "=1.2.0-pre1" | SemverReq
+        # => "=1.2.0-pre1"
+        ```
       "%
         = std.contract.from_predicate is_semver_req,
+      # TODO: bikeshedding opportunity: which fields should be optional?
       Manifest = {
         name
           | String
@@ -2870,12 +2943,40 @@
 
         nickel_version
           | String
-          # TODO: this is too strict, as it requires a full major.minor.patch. We should also allow major.minor
-          | Semver
+          | SemverPrefix
           | doc m%"
           The minimal nickel version required for this package.
         "%,
 
+        authors
+          | Array String
+          | doc m%"
+          The authors of this package.
+        "%,
+
+        description
+          | String
+          | doc m%"
+          A description of this package.
+        "%,
+
+        keywords
+          | Array String
+          | optional
+          | doc m%"
+          A list of keywords to help people find this package.
+        "%,
+
+        # TODO: maybe restrict this to be a valid SPDX 2.3 license expression?
+        # We can also allow arbitrary strings, but only accept index packages
+        # with clear licenses
+        license
+          | String
+          | optional
+          | doc m%"
+          The name of the license that this package is available under.
+        "%,
+
         dependencies
           | {
             _ : [|

package/src/manifest.rs

@@ -378,7 +378,7 @@ mod tests {
     #[test]
     fn manifest() {
         let manifest = ManifestFile::from_contents(
-            r#"{name = "foo", version = "1.0.0", nickel_version = "1.8.0"}"#.as_bytes(),
+            r#"{name = "foo", version = "1.0.0", nickel_version = "1.8.0", authors = [], description = "hi"}"#.as_bytes(),
         )
         .unwrap();
         assert_eq!(

package/tests/integration/inputs/git/branch-leaf/package.ncl

@@ -1,6 +1,8 @@
 {
   name = "branch-leaf",
+  description = "A package with no dependencies, available at a git branch",
   version = "0.1.0",
+  authors = ["Joe"],
   nickel_version = "1.9.0",
   dependencies = {},
 } | std.package.Manifest

package/tests/integration/inputs/git/leaf/package.ncl

@@ -1,6 +1,8 @@
 {
   name = "leaf",
+  description = "A package with no dependencies",
   version = "0.1.0",
   nickel_version = "1.9.0",
+  authors = ["Joe"],
   dependencies = {},
 } | std.package.Manifest

package/tests/integration/inputs/git/tag-leaf/package.ncl

@@ -1,6 +1,8 @@
 {
   name = "leaf",
+  description = "A package with no dependencies, available at a git tag",
   version = "0.1.0",
+  authors = ["Joe"],
   nickel_version = "1.9.0",
   dependencies = {},
 } | std.package.Manifest

package/tests/integration/inputs/git/with-subdirs/leaf-subdir/package.ncl

@@ -1,6 +1,8 @@
 {
   name = "leaf-subdir",
+  description = "A package in a subdirectory of a git repo",
   version = "0.1.0",
+  authors = ["Joe"],
   nickel_version = "1.9.0",
   dependencies = {},
 } | std.package.Manifest

package/tests/integration/inputs/git/with-subdirs/package.ncl

@@ -1,6 +1,8 @@
 {
   name = "with-subdirs",
+  description = "A package in a git repo with other packages in subdirectories",
   version = "0.1.0",
+  authors = ["Joe"],
   nickel_version = "1.9.0",
   dependencies = {},
 } | std.package.Manifest

package/tests/integration/inputs/git/with-subdirs/subdir-with-path-dep/package.ncl

@@ -1,6 +1,8 @@
 {
   name = "subdir-with-path-dep",
+  description = "A package in a subdir of a git repo, depending on packages in other directories",
   version = "0.1.0",
+  authors = ["Joe"],
   nickel_version = "1.9.0",
   dependencies = {
     leaf = 'Path "../leaf-subdir",

package/tests/integration/inputs/path/git-branch-and-tag-dep/package.ncl

@@ -1,6 +1,8 @@
 {
-  name = "single-git-dep",
+  name = "branch-and-tag-git-dep",
+  description = "A package depending on a git branch and a git tag",
   version = "0.1.0",
+  authors = ["Joe"],
   nickel_version = "1.9.0",
   dependencies = {
     branch = 'Git { url = "https://example.com/branch-leaf", ref = 'Branch "cành" },

package/tests/integration/inputs/path/git-path-dep/package.ncl

@@ -1,6 +1,8 @@
 {
   name = "git-path-dep",
+  description = "A package whose deps live in subdirs of a git repo",
   version = "0.1.0",
+  authors = ["Joe"],
   nickel_version = "1.9.0",
   dependencies = {
     git-root = 'Git { url = "https://example.com/with-subdirs" },

package/tests/integration/inputs/path/leaf/package.ncl

@@ -1,6 +1,8 @@
 {
   name = "leaf",
+  description = "A package with no dependencies",
   version = "0.1.0",
   nickel_version = "1.9.0",
+  authors = ["Joe"],
   dependencies = {},
 } | std.package.Manifest

package/tests/integration/inputs/path/single-git-dep/package.ncl

@@ -1,6 +1,8 @@
 {
   name = "single-git-dep",
+  description = "A package with a git dependency",
   version = "0.1.0",
+  authors = ["Joe"],
   nickel_version = "1.9.0",
   dependencies = {
     leaf = 'Git { url = "https://example.com/leaf" }

package/tests/integration/inputs/path/single-path-dep/package.ncl

@@ -1,6 +1,8 @@
 {
   name = "single-path-dep",
+  description = "A package with a single path dependency",
   version = "0.1.0",
+  authors = ["Joe"],
   nickel_version = "1.9.0",
   dependencies = {
     leaf = 'Path "../leaf"