feat(resources): implement resource management system - Add canonical format for binary resources - Add verification functionality - Delete deprecated resource-tests module - Update panic registry documentation

Author: avrabe

.cargo/config.toml

@@ -1,2 +1,13 @@
 [alias]
-xtask = "run --package xtask --quiet --" 
+xtask = "run --package xtask --quiet --" 
+
+[build]
+# Configure rustflags for different build operations
+
+# For coverage builds, define a "coverage" cfg to conditionally disable problematic modules
+[target.'cfg(all())']
+rustflags = ["--cfg=coverage"]
+
+# For llvm-cov, define a "coverage" flag to disable problematic modules
+[target.'cfg(llvm_coverage)']
+rustflags = ["--cfg=coverage"] 

.github/workflows/publish.yml

@@ -105,14 +105,34 @@ jobs:
       # Run coverage separately to handle errors better
       - name: Generate code coverage
         run: |
-          # Generate coverage data using the new full approach
-          just coverage-full || {
+          # Generate coverage using the robust xtask command
+          cargo xtask robust-coverage --exclude wrt-host --html || {
             echo "::warning::Failed to generate coverage data. Creating placeholder..."
             mkdir -p target/coverage/html
             echo "<h1>Coverage Report Not Available</h1>" > target/coverage/html/index.html
-            mkdir -p docs/source
+            
             cp docs/source/_generated_coverage_summary.rst.template docs/source/_generated_coverage_summary.rst || true
           }
+          
+          # Create a minimum viable coverage report if it doesn't exist
+          if [ ! -d "target/coverage/html" ]; then
+            echo "::warning::Creating minimal coverage report directory..."
+            mkdir -p target/coverage/html
+            echo "<h1>Coverage Report Not Available</h1><p>The coverage report could not be generated due to build errors.</p>" > target/coverage/html/index.html
+          fi
+          
+          # Ensure coverage summary exists for documentation
+          if [ ! -f "docs/source/_generated_coverage_summary.rst" ]; then
+            echo "::warning::Creating coverage summary placeholder..."
+            mkdir -p docs/source
+            cp docs/source/_generated_coverage_summary.rst.template docs/source/_generated_coverage_summary.rst 2>/dev/null || {
+              echo ".. container:: coverage-summary" > docs/source/_generated_coverage_summary.rst
+              echo "" >> docs/source/_generated_coverage_summary.rst
+              echo "   **Code Coverage:** 0.00% (0/0 lines)" >> docs/source/_generated_coverage_summary.rst
+              echo "" >> docs/source/_generated_coverage_summary.rst
+              echo "   \`Full HTML Report <../_static/coverage/index.html>\`_" >> docs/source/_generated_coverage_summary.rst
+            }
+          fi
 
       - name: Determine version
         id: determine-version

Cargo.lock

@@ -136,10 +136,19 @@ def patched_process_doc(self, env, docname, document):
     dict(directive="safety", title="Safety", prefix="SAFETY_", color="#FF5D73", style="node"),
     dict(directive="qual", title="Qualification", prefix="QUAL_", color="#9370DB", style="node"),
     dict(directive="constraint", title="Constraint", prefix="CNST_", color="#4682B4", style="node"),
+    dict(directive="panic", title="Panic", prefix="WRTQ-", color="#E74C3C", style="node"),
 ]
 
 # Add option specs to register additional options for directives
-needs_extra_options = ['rationale', 'verification', 'mitigation', 'implementation']
+needs_extra_options = [
+    'rationale', 
+    'verification', 
+    'mitigation', 
+    'implementation', 
+    'safety_impact',
+    'status',
+    'handling_strategy'
+]
 
 # Allow all sphinx-needs options for all directives
 needs_allow_unsafe_options = True
@@ -152,8 +161,21 @@ def patched_process_doc(self, env, docname, document):
     'safety_template': '**Hazard**: {{content}}\n\n**Mitigation**: {{mitigation}}',
     'qualification_template': '**Status**: {{status}}\n\n**Implementation**: {{implementation}}',
     'constraint_template': '**Constraint**: {{content}}\n\n**Rationale**: {{rationale}}\n\n**Verification**: {{verification}}',
+    'panic_template': '**Panic Condition**: {{content}}\n\n**Safety Impact**: {{safety_impact}}\n\n**Status**: {{status}}\n\n**Handling Strategy**: {{handling_strategy}}',
 }
 
+# Tags for filtering and displaying panic entries
+needs_tags = [
+    dict(name="panic", description="Panic documentation entry", bgcolor="#E74C3C"),
+    dict(name="low", description="Low safety impact", bgcolor="#2ECC71"),
+    dict(name="medium", description="Medium safety impact", bgcolor="#F39C12"),
+    dict(name="high", description="High safety impact", bgcolor="#E74C3C"),
+]
+
+# Configure needs roles for referencing 
+needs_role_need_template = "{title} ({id})"
+needs_role_need_max_title_length = 30
+
 needs_id_length = 7
 needs_title_optional = True
 needs_file_pattern = '**/*.rst'

docs/source/conf.py

@@ -31,7 +31,7 @@ All functions that may panic should include a "Panics" section in their document
     /// 
     /// Safety impact: [LOW|MEDIUM|HIGH] - [Brief explanation of the safety implication]
     /// 
-    /// Tracking: WRTQ-XXX (qualification requirement tracking ID)
+    /// Tracking: WRTQ-XXX (qualification requirement tracking ID).
 
 Safety Impact Levels
 ~~~~~~~~~~~~~~~~~~~
@@ -59,23 +59,32 @@ Implementation Approach
 Panic Registry
 -------------
 
-We maintain a centralized panic registry in ``docs/source/development/panic_registry.csv`` that includes:
+We maintain panic documentation in two formats:
 
-- File path
-- Function name
-- Line number
-- Panic condition
-- Safety impact
-- Tracking ID
-- Resolution status (Todo, In Progress, Resolved)
-- Handling strategy (when determined)
+1. A CSV file at ``docs/source/development/panic_registry.csv`` that is easy to read and maintain
+2. A structured RST file using sphinx-needs at ``docs/source/development/panic_registry.rst`` for qualification documentation
+
+The registry is automatically updated by the ``xtask update-panic-registry`` command, which scans the codebase for documented panics and updates both formats.
+
+CSV Registry
+~~~~~~~~~~~
+
+The CSV registry includes the following information:
 
 .. csv-table:: Panic Registry
    :file: panic_registry.csv
    :header-rows: 1
    :widths: 20, 15, 5, 20, 5, 10, 10, 15
 
-The registry is automatically updated by the ``xtask update-panic-registry`` command, which scans the codebase for documented panics.
+Sphinx-Needs Registry
+~~~~~~~~~~~~~~~~~~~~
+
+For qualification purposes, all panic points are also available in a structured format using sphinx-needs in the :doc:`panic_registry` document. This allows:
+
+- Cross-referencing of panic points in documentation
+- Filtering and searching by safety impact level
+- Integration with qualification traceability matrices
+- Status tracking and reporting
 
 Common Panic Scenarios
 ---------------------
@@ -158,7 +167,4 @@ Responsible Teams
 Example Code
 -----------
 
-Below is an example demonstrating proper panic documentation:
-
-.. include:: examples/panic_doc_example.rs
-   :code: rust 
+Below is an example demonstrating proper panic documentation: 

docs/source/development/panic_documentation.rst

@@ -1,15 +1,11 @@
 File Path,Function Name,Line Number,Panic Condition,Safety Impact,Tracking ID,Resolution Status,Handling Strategy,Last Updated
-wrt/src/execution.rs,f32_nearest,389,This function will panic if the provided value is not an F32 value.,,,Todo,,2025-04-25
-wrt/src/execution.rs,f64_nearest,423,This function will panic if the provided value is not an F64 value.,,,Todo,,2025-04-25
-xtask/src/check_panics.rs,run,87,println!("///"); println!("/// This function will panic if [describe condition]"); println!("///");,[LOW|MEDIUM|HIGH]");,[WRTQ-XXX]");,Todo,,2025-04-25
-xtask/src/update_panic_registry.rs,run,133,,,,Todo,,2025-04-25
-xtask/src/update_panic_registry.rs,run,173,,,,Todo,,2025-04-25
-xtask/src/update_panic_registry.rs,run,180,,,,Todo,,2025-04-25
-wrt-sync/src/mutex.rs,new,53,This function does not panic.,,,Todo,,2025-04-25
-wrt-types/src/safe_memory.rs,new,55,This function will panic if the initial integrity verification fails. This can happen if memory corruption is detected during initialization.,,,Todo,,2025-04-25
-wrt-types/src/bounded.rs,push,194,This function does not panic.,,,Todo,Return Result instead of panic,2025-04-25
-wrt-decoder/src/module.rs,encode,214,This function will panic if it attempts to access the last element of an empty custom_sections vector, which can happen if the implementation tries to process a custom section before any custom sections have been added to the module.,,,Todo,,2025-04-25
-wrt-runtime/src/memory.rs,buffer,229,In `no_std` environments, this method will panic if the read lock for the metrics cannot be acquired. This would typically only happen in case of a deadlock or if the lock is poisoned due to a panic in another thread holding the lock.,,,Todo,,2025-04-25
-wrt-runtime/src/memory.rs,peak_memory,249,In `no_std` environments, this method will panic if the read lock for the metrics cannot be acquired. This would typically only happen in case of a deadlock or if the lock is poisoned due to a panic in another thread holding the lock.,,,Todo,,2025-04-25
-wrt-runtime/src/memory.rs,access_count,269,In `no_std` environments, this method will panic if the write lock for the metrics cannot be acquired. This would typically only happen in case of a deadlock or if the lock is poisoned due to a panic in another thread holding the lock.,,,Todo,,2025-04-25
-wrt-runtime/src/memory.rs,increment_access_count,288,In `no_std` environments, this method will panic if the write lock for the metrics cannot be acquired. This would typically only happen in case of a deadlock or if the lock is poisoned due to a panic in another thread holding the lock.,,,Todo,,2025-04-25
+wrt/src/execution.rs,f32_nearest,389,This function will panic if the provided value is not an F32 value.,[LOW|MEDIUM|HIGH] - [Brief explanation of the safety implication],WRTQ-XXX (qualification requirement tracking ID).,Todo,,2025-04-25
+wrt/src/execution.rs,f64_nearest,425,This function will panic if the provided value is not an F64 value.,[LOW|MEDIUM|HIGH] - [Brief explanation of the safety implication],WRTQ-XXX (qualification requirement tracking ID).,Todo,,2025-04-25
+wrt-sync/src/mutex.rs,new,53,This function does not panic.,[LOW|MEDIUM|HIGH] - [Brief explanation of the safety implication],WRTQ-XXX (qualification requirement tracking ID).,Todo,,2025-04-25
+wrt-types/src/safe_memory.rs,new,50,This function will panic if the initial integrity verification fails. This can happen if memory corruption is detected during initialization.,[LOW|MEDIUM|HIGH] - [Brief explanation of the safety implication],WRTQ-XXX (qualification requirement tracking ID).,Todo,,2025-04-25
+wrt-types/src/bounded.rs,push,196,This function does not panic.,[LOW|MEDIUM|HIGH] - [Brief explanation of the safety implication],WRTQ-XXX (qualification requirement tracking ID).,Todo,Return Result instead of panic,2025-04-25
+wrt-decoder/src/module.rs,encode,214,This function will panic if it attempts to access the last element of an empty custom_sections vector, which can happen if the implementation tries to process a custom section before any custom sections have been added to the module.,[LOW|MEDIUM|HIGH] - [Brief explanation of the safety implication],WRTQ-XXX (qualification requirement tracking ID).,WRTQ-XXX (qualification requirement tracking ID).,WRTQ-XXX (qualification requirement tracking ID).,2025-04-25
+wrt-runtime/src/memory.rs,buffer,229,In `no_std` environments, this method will panic if the read lock for the metrics cannot be acquired. This would typically only happen in case of a deadlock or if the lock is poisoned due to a panic in another thread holding the lock.,[LOW|MEDIUM|HIGH] - [Brief explanation of the safety implication],WRTQ-XXX (qualification requirement tracking ID).,WRTQ-XXX (qualification requirement tracking ID).,WRTQ-XXX (qualification requirement tracking ID).,2025-04-25
+wrt-runtime/src/memory.rs,peak_memory,251,In `no_std` environments, this method will panic if the read lock for the metrics cannot be acquired. This would typically only happen in case of a deadlock or if the lock is poisoned due to a panic in another thread holding the lock.,[LOW|MEDIUM|HIGH] - [Brief explanation of the safety implication],WRTQ-XXX (qualification requirement tracking ID).,WRTQ-XXX (qualification requirement tracking ID).,WRTQ-XXX (qualification requirement tracking ID).,2025-04-25
+wrt-runtime/src/memory.rs,access_count,273,In `no_std` environments, this method will panic if the write lock for the metrics cannot be acquired. This would typically only happen in case of a deadlock or if the lock is poisoned due to a panic in another thread holding the lock.,[LOW|MEDIUM|HIGH] - [Brief explanation of the safety implication],WRTQ-XXX (qualification requirement tracking ID).,WRTQ-XXX (qualification requirement tracking ID).,WRTQ-XXX (qualification requirement tracking ID).,2025-04-25
+wrt-runtime/src/memory.rs,increment_access_count,294,In `no_std` environments, this method will panic if the write lock for the metrics cannot be acquired. This would typically only happen in case of a deadlock or if the lock is poisoned due to a panic in another thread holding the lock.,[LOW|MEDIUM|HIGH] - [Brief explanation of the safety implication],WRTQ-XXX (qualification requirement tracking ID).,WRTQ-XXX (qualification requirement tracking ID).,WRTQ-XXX (qualification requirement tracking ID).,2025-04-25

docs/source/development/panic_registry.csv

@@ -0,0 +1,129 @@
+# Panic Registry Implementation Proposal
+
+## Overview
+
+This document proposes an enhanced approach to tracking panics in the WRT codebase by:
+
+1. Maintaining the existing CSV-based panic registry for easy reading and editing
+2. Adding a new RST-based representation using sphinx-needs for qualification documentation
+3. Implementing validation to ensure all panic documentation includes safety impact and tracking information
+
+## Implementation Details
+
+### 1. Enhanced `update_panic_registry.rs`
+
+The existing `xtask update-panic-registry` command has been extended to:
+
+- Continue to generate the CSV file as before
+- Additionally generate an RST file with sphinx-needs directives
+- Parse safety impact levels and categorize them (LOW/MEDIUM/HIGH)
+- Automatically create WRTQ-XXX tracking IDs for entries without them
+
+### 2. sphinx-needs Configuration
+
+The `docs/source/conf.py` file has been updated with:
+
+- A new `panic` directive type with `WRTQ-` prefix
+- Additional option specs for panic-specific fields (safety_impact, status, handling_strategy)
+- Tags for filtering panic entries by safety impact level (low, medium, high)
+- A custom template for displaying panic entries
+
+### 3. Documentation Updates
+
+The panic documentation guidelines have been updated to:
+
+- Explain both CSV and RST formats
+- Provide guidance on how to use the sphinx-needs representation
+- Maintain the existing CSV table for backward compatibility
+
+### 4. Validation Enhancements
+
+The `check_panics` command has been enhanced to:
+
+- Check for undocumented panics as before
+- Additionally validate that panic documentation includes required fields:
+  - Safety impact: [LOW|MEDIUM|HIGH] - [Brief explanation]
+  - Tracking: WRTQ-XXX (qualification tracking ID)
+- Generate appropriate documentation templates when run with `--fix`
+
+## Benefits
+
+This approach provides several advantages:
+
+1. **Dual Representation**: Maintains the simple CSV format while adding structured qualification documentation
+2. **Integration with Qualification**: Enables cross-referencing panic points in qualification documentation
+3. **Automated Validation**: Ensures consistent documentation of safety impact and tracking IDs
+4. **Improved Reporting**: Enables filtering and searching panic entries by various attributes
+5. **Traceability**: Links panic points to qualification requirements through the WRTQ-XXX IDs
+
+## Usage
+
+For developers:
+
+1. Document panics in Rust code following the established format
+2. Run `xtask check-panics --fix` to add templates for undocumented panics
+3. Run `xtask update-panic-registry` to update both CSV and RST files
+
+For documentation readers:
+
+1. CSV format remains available for quick reference
+2. RST format provides enhanced filtering and cross-referencing capabilities
+3. Sphinx-needs features enable integration with qualification matrices
+
+## Example of Generated RST Content
+
+```rst
+.. _panic-registry:
+
+Panic Registry
+==============
+
+This document contains all documented panic conditions in the WRT codebase.
+Each panic is tracked as a qualification requirement using sphinx-needs.
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+Summary
+-------
+
+* Total panic points: 14
+* Status:
+  * Todo: 14
+  * In Progress: 0
+  * Resolved: 0
+
+The original CSV version of this registry is maintained at:
+`docs/source/development/panic_registry.csv`_
+
+.. csv-table:: Panic Registry CSV
+   :file: panic_registry.csv
+   :header-rows: 1
+   :widths: 20, 15, 5, 20, 5, 10, 10, 15
+
+Panic Details
+------------
+
+.. qual:: f32_nearest
+   :id: WRTQ-0001
+   :status: Todo
+   :implementation: 
+   :tags: panic, medium
+
+   **File:** wrt/src/execution.rs
+   **Line:** 389
+   **Function:** f32_nearest
+   **Safety Impact:** MEDIUM - Incorrect numerical results
+   **Last Updated:** 2025-04-25
+
+   This function will panic if the provided value is not an F32 value.
+```
+
+## Next Steps
+
+1. Run the updated `xtask update-panic-registry` command to generate the initial RST file
+2. Update qualification documentation to reference panic points using sphinx-needs
+3. Begin filling in missing safety impact assessments and tracking IDs
+
+This implementation enables the WRT project to maintain better traceability between panic points and qualification requirements, while keeping the existing CSV format for ease of maintenance. 

docs/source/development/panic_registry_proposal.md

@@ -22,6 +22,7 @@ This section contains all qualification-related documents for the WebAssembly Ru
    technical_report
    qualification_report
    internal_procedures
+   panic_registry
 
 Overview
 --------