refuse to publish empty READMEs

Author: giacomocavalieri

CHANGELOG.md

@@ -74,7 +74,8 @@
   README generated by the `gleam new` command.
   ([Giacomo Cavalieri](https://github.com/giacomocavalieri))
 
-- The build tool will now refuse to publish any package that has no README.
+- The build tool will now refuse to publish any package that has no README, or
+  an empty README.
   ([Giacomo Cavalieri](https://github.com/giacomocavalieri))
 
 ### Language server

compiler-cli/src/publish.rs

@@ -8,7 +8,7 @@ use gleam_core::{
     build::{Codegen, Compile, Mode, Options, Package, Target},
     config::{GleamVersion, PackageConfig, SpdxLicense},
     docs::{Dependency, DependencyKind, DocContext},
-    error::{SmallVersion, wrap},
+    error::{InvalidReadmeReason, SmallVersion, wrap},
     hex,
     manifest::ManifestPackageSource,
     paths::{self, ProjectPaths},
@@ -31,7 +31,7 @@ pub fn command(paths: &ProjectPaths, replace: bool, i_am_sure: bool) -> Result<(
         && check_for_version_zero(&config)?
         && check_repo_url(&config, i_am_sure)?;
 
-    check_for_default_readme(&config, paths)?;
+    check_for_invalid_readme(&config, paths)?;
 
     if !should_publish {
         println!("Not publishing.");
@@ -132,33 +132,43 @@ HTML documentation will work:
     Ok(())
 }
 
-fn check_for_default_readme(config: &PackageConfig, paths: &ProjectPaths) -> Result<(), Error> {
-    let default_readme = default_readme(config.name.as_str());
+fn check_for_invalid_readme(config: &PackageConfig, paths: &ProjectPaths) -> Result<(), Error> {
+    let normalise = |string: String| {
+        string
+            .trim()
+            .replace("\r\n", "")
+            .replace("\n", "")
+            .replace("\t", "")
+            .replace(" ", "")
+    };
+
     let project_readme = match fs::read(paths.readme()) {
         Err(Error::FileIo {
             err: Some(message), ..
         }) if message.contains("No such file or directory") => {
-            return Err(Error::CannotPublishWithNoReadme);
+            return Err(Error::CannotPublishWithInvalidReadme {
+                reason: InvalidReadmeReason::Missing,
+            });
         }
         Err(error) => return Err(error),
         Ok(project_readme) => project_readme,
     };
 
-    // We consider the two READMEs equal modulo whitespace, otherwise it would
-    // be pretty trivial to trick this check by just formatting the default
-    // README differently.
-    let normalise = |string: String| {
-        string
-            .replace("\r\n", "")
-            .replace("\n", "")
-            .replace("\t", "")
-            .replace(" ", "")
-    };
-    if normalise(project_readme) == normalise(default_readme) {
-        Err(Error::CannotPublishWithDefaultReadme)
-    } else {
-        Ok(())
+    let normalised_project_readme = normalise(project_readme);
+    if normalised_project_readme.is_empty() {
+        return Err(Error::CannotPublishWithInvalidReadme {
+            reason: InvalidReadmeReason::Empty,
+        });
     }
+
+    let default_readme = default_readme(config.name.as_str());
+    if normalised_project_readme == normalise(default_readme) {
+        return Err(Error::CannotPublishWithInvalidReadme {
+            reason: InvalidReadmeReason::Default,
+        });
+    }
+
+    Ok(())
 }
 
 fn check_for_name_squatting(package: &Package) -> Result<(), Error> {

compiler-core/src/error.rs

@@ -312,11 +312,8 @@ file_names.iter().map(|x| x.as_str()).join(", "))]
     #[error("The modules {unfinished:?} are empty and so cannot be published")]
     CannotPublishEmptyModules { unfinished: Vec<EcoString> },
 
-    #[error("Publishing a package with the default README is not permitted")]
-    CannotPublishWithDefaultReadme,
-
-    #[error("Publishing a package with no README is not permitted")]
-    CannotPublishWithNoReadme,
+    #[error("Publishing packages with an invalid README is not permitted")]
+    CannotPublishWithInvalidReadme { reason: InvalidReadmeReason },
 
     #[error("Publishing packages to reserve names is not permitted")]
     HexPackageSquatting,
@@ -352,6 +349,13 @@ file_names.iter().map(|x| x.as_str()).join(", "))]
     CannotAddSelfAsDependency { name: EcoString },
 }
 
+#[derive(Debug, Eq, PartialEq, Clone, Copy)]
+pub enum InvalidReadmeReason {
+    Missing,
+    Empty,
+    Default,
+}
+
 // A wrapper that ignores the inner value for equality:
 #[derive(Debug, Clone)]
 pub struct NeverEqual<T>(pub T);
@@ -868,7 +872,9 @@ package deletion or account suspension.
                 }]
             }
 
-            Error::CannotPublishWithDefaultReadme => {
+            Error::CannotPublishWithInvalidReadme {
+                reason: InvalidReadmeReason::Default,
+            } => {
                 let text =
                     "You appear to be attempting to publish a package with the default README
 generated by the `gleam new` command. That is meant as a placeholder and a
@@ -887,7 +893,9 @@ published package should have its own carefully written README.
                 }]
             }
 
-            Error::CannotPublishWithNoReadme => {
+            Error::CannotPublishWithInvalidReadme {
+                reason: InvalidReadmeReason::Missing,
+            } => {
                 let text = "You appear to be attempting to publish a package with no README.
 All published packages should have one.
 "
@@ -902,6 +910,25 @@ All published packages should have one.
                 }]
             }
 
+            Error::CannotPublishWithInvalidReadme {
+                reason: InvalidReadmeReason::Empty,
+            } => {
+                let text = "You appear to be attempting to publish a package with an empty README.
+All published packages should have a non empty README.
+"
+                .into();
+
+                vec![Diagnostic {
+                    title: "Cannot publish with empty README".into(),
+                    text,
+                    level: Level::Error,
+                    location: None,
+                    hint: Some(
+                        "Update your project's README to describe it before publishing".into(),
+                    ),
+                }]
+            }
+
             Error::CannotPublishWithDefaultMain { package_name } => {
                 let text = wrap_format!(
                     "Packages with the default main function cannot be published

test/multi_namespace/README.md

@@ -0,0 +1,3 @@
+# Multi namespace project
+
+should not be published!

test/publishing_empty_readme/.gitignore

@@ -0,0 +1,3 @@
+*.beam
+*.ez
+build

test/publishing_empty_readme/README.md

@@ -0,0 +1,7 @@
+name = "empty_readme"
+version = "1.0.0"
+description = "Test project for empty readme"
+licences = ["Apache-2.0"]
+
+[dependencies]
+gleam_stdlib = ">= 0.44.0 and < 2.0.0"

test/publishing_empty_readme/gleam.toml

@@ -0,0 +1,9 @@
+# This file was generated by Gleam
+# You typically do not need to edit this file
+
+packages = [
+  { name = "gleam_stdlib", version = "0.62.1", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "0080706D3A5A9A36C40C68481D1D231D243AF602E6D2A2BE67BA8F8F4DFF45EC" },
+]
+
+[requirements]
+gleam_stdlib = { version = ">= 0.44.0 and < 2.0.0" }

test/publishing_empty_readme/manifest.toml

@@ -0,0 +1,21 @@
+import gleam/io
+
+/// This tests that a project with an empty readme doesn't get published.
+///
+pub fn main() -> Nil {
+  greeting()
+  first_line()
+  second_line()
+}
+
+fn greeting() {
+  io.println("Hello from empty_readme!")
+}
+
+fn first_line() {
+  io.println("Here we have some additional code so that this is not mistaken")
+}
+
+fn second_line() {
+  io.println("for a default main project, that would be rejected as well!")
+}

test/publishing_empty_readme/src/empty_readme.gleam

@@ -0,0 +1,23 @@
+#!/bin/sh
+
+set -eu
+
+GLEAM_COMMAND=${GLEAM_COMMAND:-"cargo run --quiet --"}
+
+g() {
+  echo "Running: $GLEAM_COMMAND $@"
+  $GLEAM_COMMAND "$@"
+}
+
+echo Resetting the build directory to get to a known state
+rm -fr build
+
+echo Running publish should not publish anything
+if yes "n" | g publish; then
+  echo "Expected publish to fail, but it succeeded"
+  exit 1
+fi
+
+echo
+echo Success! 💖
+echo