Add check for unlinked manual files

Author: saecki

src/check.rs

@@ -6,7 +6,6 @@ use typst::{
     WorldExt,
 };
 
-use crate::check::readme::check_readme;
 use crate::world::SystemWorld;
 
 pub mod authors;
@@ -30,8 +29,6 @@ pub async fn all_checks(
 
     let (manifest, worlds) = manifest::check(&package_dir, &mut diags, package_spec).await?;
 
-    files::check(&mut diags, &package_dir, &manifest);
-
     compile::check(&mut diags, &worlds.package);
     if let Some(template_world) = worlds.template {
         let mut template_diags = Diagnostics::default();
@@ -43,8 +40,10 @@ pub async fn all_checks(
         diags.extend(template_diags, template_dir);
     }
 
-    let res = check_readme(&worlds.package, &mut diags).await;
-    diags.maybe_emit(res);
+    let res = readme::check(&worlds.package, &mut diags).await;
+    let readme = diags.maybe_emit(res);
+
+    files::check(&mut diags, &package_dir, &manifest, &readme);
 
     kebab_case::check(&mut diags, &worlds.package);
 

src/check/diagnostics.rs

@@ -36,9 +36,13 @@ pub struct Diagnostics {
 }
 
 impl Diagnostics {
-    pub fn maybe_emit<T>(&mut self, maybe_err: Result<T>) {
-        if let Err(e) = maybe_err {
-            self.emit(e)
+    pub fn maybe_emit<T>(&mut self, maybe_err: Result<T>) -> Option<T> {
+        match maybe_err {
+            Ok(v) => Some(v),
+            Err(e) => {
+                self.emit(e);
+                None
+            }
         }
     }
 

src/check/files.rs

@@ -5,9 +5,15 @@ use codespan_reporting::diagnostic::{Diagnostic, Label};
 
 use crate::check::manifest::Manifest;
 use crate::check::path::PackagePath;
+use crate::check::readme::Readme;
 use crate::check::Diagnostics;
 
-pub fn check(diags: &mut Diagnostics, package_dir: &Path, manifest: &Manifest) {
+pub fn check(
+    diags: &mut Diagnostics,
+    package_dir: &Path,
+    manifest: &Manifest,
+    readme: &Option<Readme>,
+) {
     let exclude = &manifest.package.exclude;
     let thumbnail_path = manifest.thumbnail();
 
@@ -43,6 +49,7 @@ pub fn check(diags: &mut Diagnostics, package_dir: &Path, manifest: &Manifest) {
         forbid_font_files(diags, file_path);
         exclude_large_files(diags, file_path, excluded, metadata.len());
         exclude_examples_and_tests(diags, file_path, excluded);
+        link_manuals(diags, readme, file_path, excluded);
     }
 }
 
@@ -110,10 +117,7 @@ fn exclude_large_files(
 }
 
 fn check_wasm_file_size(diags: &mut Diagnostics, path: PackagePath<&Path>, original_size: u64) {
-    let Some(file_name) = path.full().file_name() else {
-        return;
-    };
-    let out = std::env::temp_dir().join(file_name);
+    let out = std::env::temp_dir().join(path.file_name());
 
     let wasm_opt_result = wasm_opt::OptimizationOptions::new_optimize_for_size()
         // Explicitely enable and disable features to best match what wasmi supports
@@ -194,3 +198,33 @@ fn forbid_font_files(diags: &mut Diagnostics, path: PackagePath<&Path>) {
             ),
     );
 }
+
+fn link_manuals(
+    diags: &mut Diagnostics,
+    readme: &Option<Readme>,
+    path: PackagePath<&Path>,
+    excluded: bool,
+) {
+    let Some(readme) = readme.as_ref() else {
+        return;
+    };
+
+    let name = path.file_name().to_string_lossy().to_lowercase();
+
+    const MANUAL_FILES: [&str; 4] = ["manual.pdf", "doc.pdf", "docs.pdf", "documentation.pdf"];
+    if MANUAL_FILES.contains(&name.as_str())
+        && readme.linked_files.iter().all(|l| l.full() != path.full())
+    {
+        let note =
+            excluded.then(|| "It should also be added to `exclude` in your `typst.toml`.".into());
+
+        diags.emit(Diagnostic::warning()
+            .with_label(Label::primary(path.file_id(), 0..0))
+            .with_code("files/manual/unlinked")
+            .with_message(
+                "This file seems to be a manual/documentation, but isn't linked in the readme. \
+                 It will be inacessible on Typst Universe.",
+            )
+            .with_notes_iter(note));
+    }
+}

src/check/readme.rs

@@ -19,20 +19,23 @@ use crate::{
     world::SystemWorld,
 };
 
-pub async fn check_readme(
-    world: &SystemWorld,
-    diags: &mut Diagnostics,
-) -> crate::check::Result<()> {
+#[derive(Default)]
+pub struct Readme {
+    pub text: String,
+    pub linked_files: Vec<PackagePath>,
+}
+
+pub async fn check(world: &SystemWorld, diags: &mut Diagnostics) -> crate::check::Result<Readme> {
     // check syntax, versions and kebab-case
     // warn on unsupported gfm features
-    let readme = tokio::fs::read_to_string(world.root().join("README.md"))
+    let text = tokio::fs::read_to_string(world.root().join("README.md"))
         .await
         .error("io/readme", "Failed to read README.md")?;
 
     let arena = comrak::Arena::new();
     let md_ast = comrak::parse_document(
         &arena,
-        &readme,
+        &text,
         &comrak::Options {
             // Try to be faithful to the Universe parser
             extension: comrak::options::Extension {
@@ -52,6 +55,11 @@ pub async fn check_readme(
         },
     );
 
+    let mut readme = Readme {
+        text,
+        linked_files: Vec::new(),
+    };
+
     for node in md_ast.descendants() {
         let md_node = &*node.data.borrow();
         match &md_node.value {
@@ -87,7 +95,7 @@ pub async fn check_readme(
             }
             // Check if all links are valid.
             MdNode::Link(link) => {
-                check_readme_link_url(world, diags, &readme, md_node.sourcepos, &link.url);
+                check_readme_link_url(world, diags, &mut readme, md_node.sourcepos, &link.url);
             }
             // Check all image URLs are valid and alt text is specified.
             MdNode::Image(link) => {
@@ -100,19 +108,19 @@ pub async fn check_readme(
                 }
                 check_image_alternative_description(diags, &readme, md_node.sourcepos, &alt);
 
-                check_readme_link_url(world, diags, &readme, md_node.sourcepos, &link.url);
+                check_readme_link_url(world, diags, &mut readme, md_node.sourcepos, &link.url);
             }
             MdNode::HtmlBlock(html) => {
-                check_readme_html(world, diags, &readme, md_node.sourcepos, &html.literal);
+                check_readme_html(world, diags, &mut readme, md_node.sourcepos, &html.literal);
             }
             MdNode::HtmlInline(html) => {
-                check_readme_html(world, diags, &readme, md_node.sourcepos, html);
+                check_readme_html(world, diags, &mut readme, md_node.sourcepos, html);
             }
             _ => (),
         }
     }
 
-    Ok(())
+    Ok(readme)
 }
 
 fn check_readme_code_block(
@@ -176,7 +184,7 @@ fn check_readme_code_block(
 fn check_readme_html(
     world: &SystemWorld,
     diags: &mut Diagnostics,
-    readme: &str,
+    readme: &mut Readme,
     sourcepos: Sourcepos,
     html: &str,
 ) {
@@ -203,7 +211,7 @@ fn check_readme_html(
 fn check_html_elems(
     world: &SystemWorld,
     diags: &mut Diagnostics,
-    readme: &str,
+    readme: &mut Readme,
     sourcepos: Sourcepos,
     node: &markup5ever_rcdom::Node,
 ) {
@@ -243,7 +251,7 @@ fn check_html_elems(
 fn check_readme_link_url(
     world: &SystemWorld,
     diags: &mut Diagnostics,
-    readme: &str,
+    readme: &mut Readme,
     sourcepos: Sourcepos,
     url_text: &str,
 ) {
@@ -310,11 +318,13 @@ fn check_readme_link_url(
                 )]),
         );
     }
+
+    readme.linked_files.push(path);
 }
 
 const DEFAULT_BRANCHES: [&str; 2] = ["main", "master"];
 
-fn check_repo_file_url(diags: &mut Diagnostics, readme: &str, sourcepos: Sourcepos, url: &str) {
+fn check_repo_file_url(diags: &mut Diagnostics, readme: &Readme, sourcepos: Sourcepos, url: &str) {
     static GITHUB_URL: LazyLock<Regex> = LazyLock::new(|| {
         Regex::new(r"https://github.com/([^/]+)/([^/]+)/(?:blob|tree)/([^/]+)/(.+)").unwrap()
     });
@@ -390,7 +400,7 @@ fn check_repo_file_url(diags: &mut Diagnostics, readme: &str, sourcepos: Sourcep
 
 fn check_image_alternative_description(
     diags: &mut Diagnostics,
-    readme: &str,
+    readme: &Readme,
     sourcepos: Sourcepos,
     alt: &str,
 ) {
@@ -430,7 +440,7 @@ fn check_image_alternative_description(
     }
 }
 
-fn sourcepos_to_range(s: &str, pos: Sourcepos) -> Range<usize> {
+fn sourcepos_to_range(readme: &Readme, pos: Sourcepos) -> Range<usize> {
     fn byte_offset(s: &str, pos: LineColumn) -> usize {
         // `LineColumn` uses 1-indexed line numbers.
         let line_offset = s
@@ -443,9 +453,9 @@ fn sourcepos_to_range(s: &str, pos: Sourcepos) -> Range<usize> {
     }
 
     // `LineColumn::column` is 1-indexed.
-    let start = byte_offset(s, pos.start) - 1;
+    let start = byte_offset(&readme.text, pos.start) - 1;
     // `Sourcepos::end` is end-inclusive (byte-wise), and thus `offset + 1 - 1`.
-    let end = byte_offset(s, pos.end);
+    let end = byte_offset(&readme.text, pos.end);
 
     start..end
 }