feat(examples)#1225: non existent path in comment

Author: augustin-v

examples/supplementary/nonexistent_path_in_comment/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "nonexistent_path_in_comment"
+version = "0.1.0"
+authors = ["Augustin Villetard"]
+description = "Lint for nonexistent paths in comments"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+clippy_utils = { git = "https://github.com/rust-lang/rust-clippy", rev = "19e305bb57a7595f2a8d81f521c0dd8bf854e739" }
+dylint_linting = "3.5.1"
+regex = { workspace = true }
+once_cell = { workspace = true }
+
+[dev-dependencies]
+dylint_testing = "3.5.1"
+
+[package.metadata.rust-analyzer]
+rustc_private = true

examples/supplementary/nonexistent_path_in_comment/README.md

@@ -0,0 +1,31 @@
+# Nonexistent Path in Comment Lint
+
+### What it does
+
+This lint checks comments in the code for file path references and verifies that the referenced files actually do exist. It processes both line comments (using `//`) and block comments (`/* ... */`) by using regex to extract potential file paths. When the lint finds a file path that does not exist on the filesystem it emits a warning.
+
+### Why is this bad?
+
+References to nonexistent files in comments can be misleading:  
+- They clutter the code with outdated or inaccurate references.  
+- They may cause confusion among developers who are trying to trace implementation details or documentation.  
+
+### Known problems
+- Can only check for absolute path or path relative to commented file.
+- [This example from the issue](https://github.com/trailofbits/dylint/issues/1225#issue-2315607396) would get flaged even if it did exist, as this lint doesn't check for project root.
+
+### Example
+
+The lint issues a warning when a comment refers to a file that does not exist:
+
+```
+// See ../nonexistent/path/file.rs for further details
+fn main() {}
+```
+
+Use this approach instead, referring to a file that exists:
+
+```
+// See ../existing/file.rs for actual implementation details
+fn main() {}
+```

examples/supplementary/nonexistent_path_in_comment/src/lib.rs

@@ -0,0 +1,120 @@
+#![feature(rustc_private)]
+#![feature(let_chains)]
+#![warn(unused_extern_crates)]
+
+extern crate rustc_span;
+
+use clippy_utils::diagnostics::span_lint_and_help;
+use once_cell::sync::Lazy;
+use regex::Regex;
+use rustc_lint::{LateContext, LateLintPass};
+use rustc_span::{Span, SyntaxContext};
+use std::path::Path;
+
+dylint_linting::declare_late_lint! {
+    /// ### What it does
+    /// Checks for file paths in comments that don't exist in the filesystem.
+    ///
+    /// ### Why is this bad?
+    /// References to nonexistent files in comments can be misleading and may indicate outdated
+    /// documentation or typos.
+    ///
+    /// ### Example
+    /// ```
+    /// // See ../nonexistent/path/file.rs for implementation details
+    /// fn main() {}
+    /// ```
+    /// Use instead:
+    /// ```
+    /// // See ../actual/path/file.rs for implementation details
+    /// fn main() {}
+    /// ```
+    pub NONEXISTENT_PATH_IN_COMMENT,
+    Warn,
+    "reports file paths in comments that do not exist"
+}
+
+static LINE_COMMENT: Lazy<Regex> = Lazy::new(|| Regex::new("(^|[^/])(//([^/].*))").unwrap());
+static BLOCK_COMMENT: Lazy<Regex> = Lazy::new(|| Regex::new(r"/\*(([^*]|\*[^/])*)\*/").unwrap());
+static PATH_REGEX: Lazy<Regex> =
+    Lazy::new(|| Regex::new(r"((?:\.\./|/|[\w/-]+/)+[\w-]+(?:\.[\w-]+)+)").unwrap());
+
+impl<'tcx> LateLintPass<'tcx> for NonexistentPathInComment {
+    fn check_crate(&mut self, cx: &LateContext<'tcx>) {
+        let source_map = cx.tcx.sess.source_map();
+
+        for file in source_map.files().iter() {
+            if let Ok(content) = file.src.as_ref().ok_or("err") {
+                let file_start = file.start_pos;
+
+                for cap in LINE_COMMENT.captures_iter(content) {
+                    if let Some(comment_text) = cap.get(3) {
+                        check_comment(
+                            cx,
+                            Span::new(
+                                file_start + rustc_span::BytePos(comment_text.start() as u32),
+                                file_start + rustc_span::BytePos(comment_text.end() as u32),
+                                SyntaxContext::root(),
+                                None,
+                            ),
+                            comment_text.as_str(),
+                            &file.name,
+                        );
+                    }
+                }
+
+                for cap in BLOCK_COMMENT.captures_iter(content) {
+                    if let Some(comment_text) = cap.get(1) {
+                        check_comment(
+                            cx,
+                            Span::new(
+                                file_start + rustc_span::BytePos(comment_text.start() as u32),
+                                file_start + rustc_span::BytePos(comment_text.end() as u32),
+                                SyntaxContext::root(),
+                                None,
+                            ),
+                            comment_text.as_str(),
+                            &file.name,
+                        );
+                    }
+                }
+            }
+        }
+    }
+}
+
+fn check_comment(
+    cx: &LateContext<'_>,
+    span: Span,
+    comment_text: &str,
+    filename: &rustc_span::FileName,
+) {
+    let base_dir = match filename {
+        rustc_span::FileName::Real(real_filename) => Path::new(real_filename.local_path().unwrap())
+            .parent()
+            .unwrap()
+            .to_path_buf(),
+        _ => return,
+    };
+
+    for captures in PATH_REGEX.captures_iter(comment_text) {
+        let path_str = &captures[1];
+        let full_path = base_dir.join(path_str);
+
+        if !full_path.exists() {
+            span_lint_and_help(
+                cx,
+                NONEXISTENT_PATH_IN_COMMENT,
+                span,
+                format!("referenced path does not exist: {}", path_str),
+                None,
+                "verify the path is correct or remove the reference",
+            );
+        }
+    }
+}
+
+#[test]
+fn ui() {
+    dylint_testing::ui_test(env!("CARGO_PKG_NAME"), "ui");
+}

examples/supplementary/nonexistent_path_in_comment/ui/main.rs

@@ -0,0 +1,11 @@
+// This path does not exist
+// See ../nonexistent/path/file.rs
+
+// This path should exist
+// See ../src/lib.rs
+
+/* This is a block comment with a nonexistent path
+   See ../another/nonexistent/path/file.go
+*/
+
+fn main() {}

examples/supplementary/nonexistent_path_in_comment/ui/main.stderr

@@ -0,0 +1,22 @@
+warning: referenced path does not exist: ../nonexistent/path/file.rs
+  --> $DIR/main.rs:2:3
+   |
+LL | // See ../nonexistent/path/file.rs
+   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: verify the path is correct or remove the reference
+   = note: `#[warn(nonexistent_path_in_comment)]` on by default
+
+warning: referenced path does not exist: ../another/nonexistent/path/file.go
+  --> $DIR/main.rs:7:3
+   |
+LL |   /* This is a block comment with a nonexistent path
+   |  ___^
+LL | |    See ../another/nonexistent/path/file.go
+LL | | */
+   | |_^
+   |
+   = help: verify the path is correct or remove the reference
+
+warning: 2 warnings emitted
+