chore(rules_check): add multi file lint rule checking (#7399)

Co-authored-by: Naoki Ikeguchi <me@s6n.jp>

Author: ryan-m-walker

Cargo.lock

@@ -1207,21 +1207,47 @@ The documentation needs to adhere to the following rules:
 
   You should usually prefer to show a concise but complete sample snippet instead.
 
+- **Multi-file snippets**
+
+  For rules that analyze relationships between multiple files (e.g., import cycles, cross-file dependencies), you can use the `file=<path>` property to create an in-memory file system for testing.
+
+  Files are organized by documentation section (Markdown headings), where all files in a section are collected before any tests run. This ensures each test has access to the complete file system regardless of definition order.
+
+  ````rust
+  /// ### Invalid
+  ///
+  /// **`foo.js`**
+  /// ```js,expect_diagnostic,file=foo.js
+  /// import { bar } from "./bar.js";
+  /// export function foo() {
+  ///     return bar();
+  /// }
+  /// ```
+  ///
+  /// **`bar.js`**
+  /// ```js,expect_diagnostic,file=bar.js
+  /// import { foo } from "./foo.js";
+  /// export function bar() {
+  ///     return foo();
+  /// }
+  /// ```
+  ````
+
 - **Ordering of code block properties**
 
-  In addition to the language, a code block can be tagged with a few additional properties like `expect_diagnostic`, `options`, `full_options`, `use_options` and/or `ignore`.
+  In addition to the language, a code block can be tagged with a few additional properties like `expect_diagnostic`, `options`, `full_options`, `use_options`, `ignore` and/or `file=<path>`.
 
   The parser does not care about the order, but for consistency, modifiers should always be ordered as follows:
 
   ````rust
-  /// ```<language>[,expect_diagnostic][,(options|full_options|use_options)][,ignore]
+  /// ```<language>[,expect_diagnostic][,(options|full_options|use_options)][,ignore][,file=path]
   /// ```
   ````
 
   e.g.
 
   ````rust
-  /// ```tsx,expect_diagnostic,use_options,ignore
+  /// ```tsx,expect_diagnostic,use_options,ignore,file=foobar.tsx
   /// ```
   ````
 

crates/biome_analyze/CONTRIBUTING.md

@@ -35,8 +35,8 @@ declare_lint_rule! {
     /// ### Invalid
     ///
     /// **`foobar.js`**
-    /// ```js
-    /// import { baz } from "./baz.js";
+    /// ```js,expect_diagnostic,file=foobar.js
+    ///  import { baz } from "./baz.js";
     ///
     /// export function foo() {
     ///     baz();
@@ -48,7 +48,7 @@ declare_lint_rule! {
     /// ```
     ///
     /// **`baz.js`**
-    /// ```js
+    /// ```js,expect_diagnostic,file=baz.js
     /// import { bar } from "./foobar.js";
     ///
     /// export function baz() {
@@ -59,7 +59,7 @@ declare_lint_rule! {
     /// ### Valid
     ///
     /// **`foo.js`**
-    /// ```js
+    /// ```js,file=foo.js
     /// import { baz } from "./baz.js";
     ///
     /// export function foo() {
@@ -68,14 +68,14 @@ declare_lint_rule! {
     /// ```
     ///
     /// **`bar.js`**
-    /// ```js
+    /// ```js,file=bar.js
     /// export function bar() {
     ///     console.log("foobar");
     /// }
     /// ```
     ///
     /// **`baz.js`**
-    /// ```js
+    /// ```js,file=baz.js
     /// import { bar } from "./bar.js";
     ///
     /// export function baz() {
@@ -84,7 +84,7 @@ declare_lint_rule! {
     /// ```
     ///
     /// **`types.ts`**
-    /// ```ts
+    /// ```ts,file=types.ts
     /// import type { bar } from "./qux.ts";
     ///
     /// export type Foo = {
@@ -93,7 +93,7 @@ declare_lint_rule! {
     /// ```
     ///
     /// **`qux.ts`**
-    /// ```ts
+    /// ```ts,file=qux.ts
     /// import type { Foo } from "./types.ts";
     ///
     /// export function bar(foo: Foo) {

crates/biome_js_analyze/src/lint/nursery/no_import_cycles.rs

@@ -26,8 +26,11 @@ biome_json_analyze    = { workspace = true }
 biome_json_factory    = { workspace = true }
 biome_json_parser     = { workspace = true }
 biome_json_syntax     = { workspace = true }
+biome_module_graph    = { workspace = true }
+biome_project_layout  = { workspace = true }
 biome_rowan           = { workspace = true }
 biome_service         = { workspace = true }
+biome_test_utils      = { workspace = true }
 camino                = { workspace = true }
 pulldown-cmark        = "0.13.0"
 

xtask/rules_check/Cargo.toml

@@ -12,24 +12,28 @@ use biome_css_parser::CssParserOptions;
 use biome_css_syntax::CssLanguage;
 use biome_deserialize::json::deserialize_from_json_ast;
 use biome_diagnostics::{DiagnosticExt, PrintDiagnostic, Severity};
-use biome_fs::BiomePath;
+use biome_fs::{BiomePath, MemoryFileSystem};
 use biome_graphql_syntax::GraphqlLanguage;
 use biome_js_analyze::JsAnalyzerServices;
 use biome_js_parser::JsParserOptions;
 use biome_js_syntax::{EmbeddingKind, JsFileSource, JsLanguage, TextSize};
 use biome_json_factory::make;
 use biome_json_parser::JsonParserOptions;
 use biome_json_syntax::{AnyJsonValue, JsonLanguage, JsonObjectValue};
+use biome_module_graph::ModuleGraph;
+use biome_project_layout::ProjectLayout;
 use biome_rowan::AstNode;
 use biome_service::projects::{ProjectKey, Projects};
 use biome_service::settings::ServiceLanguage;
 use biome_service::workspace::DocumentFileSource;
+use biome_test_utils::get_added_paths;
 use camino::Utf8PathBuf;
-use pulldown_cmark::{CodeBlockKind, Event, Parser, Tag, TagEnd};
-use std::collections::BTreeMap;
+use pulldown_cmark::{CodeBlockKind, Event, HeadingLevel, Parser, Tag, TagEnd};
+use std::collections::{BTreeMap, HashMap};
 use std::fmt::{Display, Formatter, Write};
 use std::slice;
 use std::str::FromStr;
+use std::sync::Arc;
 
 #[derive(Debug)]
 struct Errors(String);
@@ -169,6 +173,9 @@ struct CodeBlockTest {
     /// Whether to use the last code block that was marked with
     /// `options` as the configuration settings for this code block.
     use_options: bool,
+
+    /// The given file path in the testing in memory file system if provided.
+    file_path: Option<String>,
 }
 
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
@@ -207,9 +214,26 @@ impl FromStr for CodeBlockTest {
             ignore: false,
             options: OptionsParsingMode::NoOptions,
             use_options: false,
+            file_path: None,
         };
 
         for token in tokens {
+            // Handle file=path attribute to create multi-file test scenarios
+            if let Some(file) = token.strip_prefix("file=") {
+                if file.is_empty() {
+                    bail!("The 'file' attribute must be followed by a file path");
+                }
+
+                // Normalize to absolute paths for consistent module resolution
+                let path = file
+                    .trim_start_matches("./")
+                    .trim_start_matches("../")
+                    .trim();
+                test.file_path = Some(format!("/{}", path));
+
+                continue;
+            }
+
             match token {
                 // Other attributes
                 "expect_diagnostic" => test.expect_diagnostic = true,
@@ -348,8 +372,12 @@ fn assert_lint(
     test: &CodeBlockTest,
     code: &str,
     config: &Option<Configuration>,
+    test_files: &HashMap<String, String>,
 ) -> anyhow::Result<()> {
-    let file_path = format!("code-block.{}", test.tag);
+    let file_path = test
+        .file_path
+        .clone()
+        .unwrap_or_else(|| format!("code-block.{}", test.tag));
 
     if test.ignore {
         return Ok(());
@@ -419,8 +447,13 @@ fn assert_lint(
                     test,
                 );
 
-                let services =
-                    JsAnalyzerServices::from((Default::default(), Default::default(), file_source));
+                let module_graph = get_test_module_graph(test_files);
+
+                let services = JsAnalyzerServices::from((
+                    Arc::new(module_graph),
+                    Default::default(),
+                    file_source,
+                ));
 
                 biome_js_analyze::analyze(&root, filter, &options, &[], services, |signal| {
                     if let Some(mut diag) = signal.diagnostic() {
@@ -811,6 +844,8 @@ fn parse_documentation(
 ) -> anyhow::Result<()> {
     let parser = Parser::new(rule_metadata.docs);
 
+    let mut test_runner = TestRunner::new(group, rule_metadata.name);
+
     // Track the last configuration options block that was encountered
     let mut last_options: Option<Configuration> = None;
 
@@ -831,7 +866,17 @@ fn parse_documentation(
                         last_options =
                             parse_rule_options(group, &rule_metadata, category, &test, &block)?;
                     } else {
-                        assert_lint(group, rule_metadata.name, &test, &block, &last_options)?;
+                        if let Some(file_path) = &test.file_path {
+                            test_runner
+                                .file_system
+                                .insert(file_path.clone(), block.clone());
+                        }
+
+                        test_runner.pending_tests.push(PendingTest {
+                            test,
+                            block,
+                            options_snapshot: last_options.clone(),
+                        });
                     }
                 }
             }
@@ -845,10 +890,106 @@ fn parse_documentation(
                     }
                 }
             }
+            Event::Start(Tag::Heading { level, .. }) => {
+                // Major headings delineate testable sections. When we encounter a new section,
+                // run all tests from the previous section with the complete file system.
+                if matches!(
+                    level,
+                    HeadingLevel::H1 | HeadingLevel::H2 | HeadingLevel::H3 | HeadingLevel::H4
+                ) {
+                    test_runner.run_pending_tests()?;
+                }
+            }
             // We don't care other events
             _ => {}
         }
     }
 
+    test_runner.run_pending_tests()?;
+
     Ok(())
 }
+
+struct PendingTest {
+    /// The test definition
+    test: CodeBlockTest,
+    /// The code block content for the test
+    block: String,
+    /// The last encountered configuration options block seen before this test was collected.
+    /// We take a copy of the options because one document may contain multiple options blocks.
+    options_snapshot: Option<Configuration>,
+}
+
+/// The test runner collects code block tests into batches grouped by documentation sections
+/// (delineated by markdown headings). It gathers all context required for each test,
+/// including options and in-memory files that may be referenced by the code blocks.
+struct TestRunner {
+    group: &'static str,
+    rule_name: &'static str,
+
+    /// Code block tests for the current documentation section.
+    /// Tests are deferred and run as a batch when the section ends.
+    pub pending_tests: Vec<PendingTest>,
+
+    /// In-memory file system for code blocks annotated with `file=path`.
+    /// All files are collected before running tests, ensuring each test
+    /// has access to the complete file system regardless of definition order.
+    /// This is essential for multi-file rules like import cycle detection.
+    pub file_system: HashMap<String, String>,
+}
+
+impl TestRunner {
+    pub fn new(group: &'static str, rule_name: &'static str) -> Self {
+        Self {
+            group,
+            rule_name,
+            pending_tests: Vec::new(),
+            file_system: HashMap::new(),
+        }
+    }
+
+    /// Runs all pending tests with the current file system, then resets state for the next section.
+    pub fn run_pending_tests(&mut self) -> anyhow::Result<()> {
+        for test in &self.pending_tests {
+            assert_lint(
+                self.group,
+                self.rule_name,
+                &test.test,
+                &test.block,
+                &test.options_snapshot,
+                &self.file_system,
+            )?;
+        }
+
+        self.pending_tests.clear();
+        self.file_system.clear();
+
+        Ok(())
+    }
+}
+
+/// Creates an in-memory module graph for the given files.
+/// Returns an empty module graph if no files are provided.
+fn get_test_module_graph(files: &HashMap<String, String>) -> ModuleGraph {
+    let module_graph = ModuleGraph::default();
+
+    if files.is_empty() {
+        return module_graph;
+    }
+
+    let fs = MemoryFileSystem::default();
+    let layout = ProjectLayout::default();
+
+    let mut added_paths = Vec::with_capacity(files.len());
+
+    for (path, src) in files.iter() {
+        let path_buf = Utf8PathBuf::from(path);
+        added_paths.push(BiomePath::new(&path_buf));
+        fs.insert(path_buf, src.as_bytes().to_vec());
+    }
+
+    let added_paths = get_added_paths(&fs, &added_paths);
+    module_graph.update_graph_for_js_paths(&fs, &layout, &added_paths, &[]);
+
+    module_graph
+}