add feature flag --test-rust-blocks

Author: x0rw

builder/build_cli.py

@@ -29,6 +29,7 @@ def build_docs(
     debug: bool,
     offline: bool,
     spec_lock_consistency_check: bool,
+    test_rust_blocks: bool,
 ) -> Path:
     """
     Builds the Sphinx documentation with the specified options.
@@ -72,6 +73,8 @@ def build_docs(
         conf_opt_values.append("offline=1")
     if debug:  
         conf_opt_values.append("debug=1")
+    if test_rust_blocks:  
+        conf_opt_values.append("test_rust_blocks=1")
 
     # Only add the --define argument if there are options to define
     if conf_opt_values:
@@ -151,6 +154,14 @@ def main(root):
         help="build in offline mode",
         action="store_true",
     )
+
+    parser.add_argument(
+        "--test-rust-blocks",
+        help="Test extracted rust code blocks using rustc",
+        default=False,
+        action="store_true"
+    )
+
     group = parser.add_mutually_exclusive_group()
     parser.add_argument(
         "--ignore-spec-lock-diff",
@@ -192,6 +203,6 @@ def main(root):
         update_spec_lockfile(SPEC_CHECKSUM_URL, root / "src" / SPEC_LOCKFILE)
 
     rendered = build_docs(
-        root, "xml" if args.xml else "html", args.clear, args.serve, args.debug, args.offline, not args.ignore_spec_lock_diff, 
+        root, "xml" if args.xml else "html", args.clear, args.serve, args.debug, args.offline, not args.ignore_spec_lock_diff, args.test_rust_blocks
     )
 

exts/coding_guidelines/__init__.py

@@ -48,6 +48,13 @@ def on_build_finished(app, exception):
 def setup(app):
 
     app.add_domain(CodingGuidelinesDomain)
+
+    app.add_config_value(
+        name='test_rust_blocks',
+        default=False,
+        rebuild='env'
+    )
+
     app.add_config_value(
         name = "offline", 
         default=False, 
@@ -79,12 +86,14 @@ def setup(app):
         logger.setLevel(logging.INFO)
         common.disable_tqdm = True  
 
-    app.connect('env-check-consistency', guidelines_checks.validate_required_fields)
-    app.connect('env-check-consistency', fls_checks.check_fls)
-    app.connect('build-finished', write_guidelines_ids.build_finished)
-    app.connect('build-finished', fls_linking.build_finished)
-    app.connect('build-finished', on_build_finished)
-    
+    # Ignore builds while testing code blocks
+    if not app.config.test_rust_blocks:
+        app.connect('env-check-consistency', guidelines_checks.validate_required_fields)
+        app.connect('env-check-consistency', fls_checks.check_fls)
+        app.connect('build-finished', write_guidelines_ids.build_finished)
+        app.connect('build-finished', fls_linking.build_finished)
+        app.connect('build-finished', on_build_finished)
+        
     return {
         'version': '0.1',
         'parallel_read_safe': True,

exts/rust-code-runner/__init__.py

@@ -1,9 +1,10 @@
-
 from . import rust_examples_aggregate 
 from . import rustc 
 import os
+
 def setup(app):
-    app.output_rust_file = "exts/rust-code-runner/generated.rs"
+
+    app.output_rust_file = "build/rust-code-blocks/generated.rs"
     if os.path.isfile(app.output_rust_file):
         with open(app.output_rust_file, 'w'):
             pass  
@@ -12,7 +13,9 @@ def setup(app):
     # and it also makes this extension indepandant from `needs`.
     #
     app.connect('source-read', rust_examples_aggregate.preprocess_rst_for_rust_code)
-    app.connect('build-finished', rustc.check_rust_test_errors)
+
+    if app.config.test_rust_blocks:
+        app.connect('build-finished', rustc.check_rust_test_errors)
     return {
         'version': '0.1',
         'parallel_read_safe': False,

exts/rust-code-runner/generated.rs

@@ -1,43 +1,3 @@
-// ==== Code Block 1 ====
-#[test]
-fn test_block_coding_guidelines_concurrency_1() {
-            test ga
-}
-
-// ==== Code Block 2 ====
-#[test]
-fn test_block_coding_guidelines_concurrency_2() {
-            test ga
-}
-
-// ==== Code Block 3 ====
-#[test]
-fn test_block_coding_guidelines_concurrency_3() {
-       .. compliant_example::
-          :id: compl_ex_yp7aQuEi3Sag 
-          :status: draft
-}
-
-// ==== Code Block 4 ====
-#[test]
-fn test_block_coding_guidelines_concurrency_4() {
-            test ga
-}
-
-// ==== Code Block 5 ====
-#[test]
-fn test_block_coding_guidelines_concurrency_5() {
-       .. compliant_example::
-          :id: compl_ex_gqeLAg0YBu9P 
-          :status: draft
-}
-
-// ==== Code Block 6 ====
-#[test]
-fn test_block_coding_guidelines_concurrency_6() {
-            test ga
-}
-
 // ==== Code Block 1 ====
 #[test]
 fn test_block_coding_guidelines_expressions_1() {
@@ -87,9 +47,6 @@ fn test_block_coding_guidelines_macros_4() {
 // ==== Code Block 5 ====
 #[test]
 fn test_block_coding_guidelines_macros_5() {
-            // HIDDEN START
-            use std::vec::*;
-            // HIDDEN END 
             macro_rules! increment_and_double {
                 ($x:expr) => {
                     {
@@ -99,7 +56,6 @@ fn test_block_coding_guidelines_macros_5() {
                 };
             }
             let mut num = 5;
-            let vv = Vec![];
             let result = increment_and_double!(num);
             println!("Result: {}, Num: {}", result, num);
             // Result: 12, Num: 6
@@ -109,7 +65,7 @@ fn test_block_coding_guidelines_macros_5() {
 #[test]
 fn test_block_coding_guidelines_macros_6() {
             fn increment_and_double(x: &mut i32) -> i32 {
-                *x += 1; // mutation is explicit 
+                *x += 1; // mutation is explicit
                 *x * 2
             }
             let mut num = 5;
@@ -186,9 +142,7 @@ fn test_block_coding_guidelines_macros_14() {
 #[test]
 fn test_block_coding_guidelines_macros_15() {
             #[tokio::main]  // non-compliant
-            async fn maind() {
-            //dd
-            }
+            async fn main() {
 }
 
 // ==== Code Block 16 ====
@@ -210,10 +164,43 @@ fn test_block_coding_guidelines_macros_17() {
 // ==== Code Block 18 ====
 #[test]
 fn test_block_coding_guidelines_macros_18() {
-            // HIDDEN START
-            use std::fs;
-            use std::io::{self, Read};
-            // HIDDEN END 
+            fn example_function() {
+                // Compliant implementation
+            }
+}
+
+// ==== Code Block 19 ====
+#[test]
+fn test_block_coding_guidelines_macros_19() {
+            #[macro_export]
+            macro_rules! vec {
+                ( $( $x:expr ),* ) => {
+                    {
+                        let mut temp_vec = Vec::new(); // non-global path
+                        $(
+                            temp_vec.push($x);
+                        )*
+                        temp_vec
+                    }
+                };
+            }
+}
+
+// ==== Code Block 20 ====
+#[test]
+fn test_block_coding_guidelines_macros_20() {
+            #[macro_export]
+            macro_rules! vec {
+                ( $( $x:expr ),* ) => {
+                    {
+                        let mut temp_vec = ::std::vec::Vec::new(); // global path
+                        $(
+                            temp_vec.push($x);
+                        )*
+                        temp_vec
+                    }
+                };
+            }
 }
 
 // ==== Code Block 1 ====

exts/rust-code-runner/rust_examples_aggregate.py

@@ -60,9 +60,9 @@ def replacer(match):
         prefix = match.group(1)  
         code_content = match.group(2)
         cleaned_code, hidden_code = strip_hidden(code_content)
-        print("============")
-        print(hidden_code)
-        print("============")
+        # print("============")
+        # print(hidden_code)
+        # print("============")
         return prefix + cleaned_code 
 
     modified_text = code_block_re.sub(replacer, source_text)
@@ -76,12 +76,11 @@ def preprocess_rst_for_rust_code(app, docname, source):
     modified_content = remove_hidden_blocks_from_document(original_content)
     source[0] = modified_content
 
-    print(f"Original content length: {len(original_content)}")
-    print(f"Extracted {len(code_blocks)} code blocks")
+    # print(f"Original content length: {len(original_content)}")
+    # print(f"Extracted {len(code_blocks)} code blocks")
 
-    output_path = "exts/rust-code-runner/generated.rs"
     safe_docname = docname.replace("/", "_").replace("-", "_")
-    with open(output_path, "a", encoding="utf-8") as f:
+    with open(app.output_rust_file, "a", encoding="utf-8") as f:
         for i, block in enumerate(code_blocks, start=1):
             f.write(f"// ==== Code Block {i} ====\n")
             f.write("#[test]\n")

exts/rust-code-runner/rustc.py

@@ -31,54 +31,56 @@ def print_code_snippet(file_path, line_num, context=3):
         print(f"Could not read file {file_path}: {e}")
 
 
-def parse_rustc_json(stderr: str, file):
+def parse_rustc_json(stderr: str, file_path):
     """
-    Parses the JSON diagnostics output from `rustc`.
-
-    This function takes the standard error output (in JSON format) from the Rust compiler (`rustc`)
-    and processes it, possibly filtering or reporting diagnostics relevant to the specified file.
+    Parses rustc's JSON output and prints only the first error with a single snippet.
 
     Args:
-        stderr (str): The JSON-formatted stderr output from `rustc`.
-        file: The file object or path that the diagnostics should relate to.
+        stderr (str): JSON-formatted stderr output from rustc.
+        file_path: Path to the Rust file.
 
     Returns:
-        Any
+        None
     """
     for line in stderr.splitlines():
         line = line.strip()
         if not line:
             continue
+
         try:
-            obj = json.loads(line)
+            diagnostic = json.loads(line)
         except json.JSONDecodeError:
             continue
-        if obj.get("$message_type") != "diagnostic":
+
+        if diagnostic.get("$message_type") != "diagnostic":
             continue
 
-        level = obj.get("level")
-        msg = obj.get("message")
-        spans = obj.get("spans", [])
+        if diagnostic.get("level") != "error":
+            continue  # skip warnings and notes
 
-        line_num = None
-        for span in spans:
-            if span.get("is_primary"):
-                line_num = span.get("line_start")
-                break
-
-        if line_num is not None:
-            print(f"{level}: line {line_num}: {msg}")
-            diag_f = print_code_snippet(file, line_num) 
-            if level == "error":
-                print("=========================")
-                print(f" {diag_f}")
-                print("=========================\n\n")
-        else:
-            print(f"{level}: {msg}")
+        message = diagnostic.get("message", "")
+        spans = diagnostic.get("spans", [])
 
+        # Try to find a span in the current file
+        for span in spans:
+            if span["file_name"] == file_path:
+                line_num = span["line_start"]
+                label = span.get("label", "")
+                print(f"error: line {line_num}: {message}")
+                if label:
+                    print(f"--> {label}")
+                print("=" * 25)
+                snippet = print_code_snippet(file_path, line_num, context=3)
+                print(snippet)
+                print("=" * 25)
+                return  # we return because we only print the first error--in json format there can be multiple error messages for 1 error-- if you want to see them comment this line.
+
+        # If no span in the file, still print the error
+        print(f"error: {message}")
+        return
 
 def check_rust_test_errors(app, exception):
-   """
+    """
     Sphinx 'build-finished' event handler that compiles the generated Rust file in test mode.
 
     This function is connected to the Sphinx build lifecycle and is executed after the build finishes.
@@ -89,13 +91,13 @@ def check_rust_test_errors(app, exception):
         app: The Sphinx application object. Must have an `output_rust_file` attribute containing
              the path to the generated Rust source file.
         exception: Exception raised during the build process, or None if the build completed successfully.
-
     """
     rs_path = app.output_rust_file
     # Run the Rust compiler in test mode with JSON error output format.
     # capturing stdout and stderr as text.
     result = subprocess.run(
-        ["rustc", "--test", "--edition=2024", "--error-format=json", rs_path],
+        ["rustc", "--test", "--edition=2024", "--error-format=json", "--emit=metadata", rs_path],
+        # --emit=metadata or else rustc will produce a binary ./generated
         capture_output=True,
         text=True
     )