Rule File Language Extension

A comprehensive VS Code extension providing advanced syntax highlighting, intelligent navigation, sophisticated language features, multi-level syntax validation, and bidirectional Python integration for rule files (.rul). Features include precision column alignment validation, comprehensive duplicate detection, context-aware invalid syntax detection, and seamless cross-language navigation between .rul and Python files.

Features

🎨 Syntax Highlighting

• Parameter headers (PARAM_NAME?) - Highlighted in blue/cyan
• Variable headers (VAR_NAME:) - Highlighted in purple/magenta
• Keywords, operators, numbers, strings
• Boolean values (True, False) - Distinctive colors for true vs false values
• Wildcard operators - Distinctive colors for each operator type:
  • * (any/wildcard) - Highlighted as keyword operator
  • ~ (undefined) - Highlighted as keyword operator
  • ? (don't care) - Highlighted as keyword operator
• Comments (both # line comments and /* */ block comments)
• Special values (NULL, NA, *)
• List structures with proper bracket highlighting
• Complex expressions (100*int(MULTIPLIER)) - Recognized as single values
• Nested objects ({'config':[{0:0}]}) - Properly highlighted and structured

🧭 Navigation Features

• Go to Definition (F12) - Jump between parameter and variable headers
• Find All References (Shift+F12) - Find all usages of identifiers across .rul and Python files ✨
• Rename Symbol (F2) - Rename parameters/variables across the file
• Enhanced hover tooltips - Show usage statistics, dependencies, and Python reference counts ✨
  • Dependency tracking: Hovering over a variable shows all parameters used in its table definition
  • Example: Hovering over VAR_A: displays its dependencies like PARAM_X?, PARAM_Y?
• Cross-file navigation - Find definitions and references across multiple rule files in workspace
• Bidirectional Python integration - Navigate seamlessly between .rul and Python files ✨

🔗 Python Integration

Bidirectional Cross-Language Navigation - Navigate seamlessly between Python and .rul files:

Python → .rul (Go to Definition)

• Smart Navigation: Ctrl+Click on rules.VARIABLE_NAME jumps to .rul file definition
• Multi-Format Support: Finds variables in table headers, assignments, and requirements
• Workspace-Wide: Searches all .rul files in your workspace

.rul → Python (Find References) ✨ NEW

• Reverse Cross-Reference: Right-click on any variable in .rul files and see Python usage
• Enhanced Find All References: Shows both .rul and Python references in one view
• Python Pattern Detection: Finds rules.VARIABLE_NAME and rule_mgr.attributes['VARIABLE_NAME']
• Smart Hover Tooltips: Shows Python reference counts when hovering over variables

Usage Examples:

Python to .rul Navigation:

# example.py
from rule_mgr.attributes import rules

def process_config():
    value = rules.CONFIG_PARAM     # Ctrl+Click → jumps to CONFIG_PARAM: in .rul file
    if rules.FEATURE_FLAG:         # Ctrl+Click → jumps to FEATURE_FLAG: definition
        return rules.MAX_VALUE     # Navigation works for all rule variables

Reverse Navigation (.rul to Python):

# config.rul
VAR_A:  VAR_B:  VAR_C:   VAR_D:   VAR_E:  TARGET_VAR:     PARAM_SEL?
------------------------------------------------------------------------
False   False   False    False    False   True            ['TARGET_VAR']

Right-click on TARGET_VAR: → "Find All References" shows:

• ✅ All .rul file references (headers, assignments, usage)
• ✅ All Python file references (rules.TARGET_VAR, rule_mgr.attributes['TARGET_VAR'])

Enhanced Hover Information:

TARGET_VAR:    # Hover shows: "• 3 parameter usage(s) • 1 variable assignment(s) • 12 Python reference(s)"

Supported Python Patterns:

• rules.VARIABLE_NAME - Direct rule access
• rule_mgr.attributes['VARIABLE_NAME'] - Dictionary-style access (single quotes)
• rule_mgr.attributes["VARIABLE_NAME"] - Dictionary-style access (double quotes)

Note: This feature provides additional .rul file definitions alongside VS Code's built-in Python navigation.

🔍 Advanced Syntax Validation

The extension provides three levels of intelligent syntax checking:

1. Column Alignment Validation

Super-sensitive alignment detection that catches even single-character misalignments:

• ✅ Detects column shifts and spacing inconsistencies
• ✅ Handles complex expressions as single values
• ✅ Ignores formatting symbols in alignment calculations
• ⚙️ Configurable: Adjust tolerance levels or disable entirely

2. Duplicate Detection

Comprehensive duplicate variable/header detection across all formats:

• Parameter duplicates: Multiple VARIABLE? definitions
• Assignment duplicates: Multiple VARIABLE: assignments
• Assignment operator duplicates: Multiple VARIABLE = value statements
• Cross-format duplicates: Mixed usage of ?, :, and = for same variable
• ⚙️ Configurable: Enable/disable duplicate checking

# Duplicate detection examples
PARAM_A?    PARAM_B?    PARAM_C?
PARAM_A?    PARAM_D?    PARAM_C?    # ❌ PARAM_A and PARAM_C duplicated

VAR_X:      value1
VAR_X:      value2              # ❌ VAR_X duplicated

VAR_LIMIT = 85
VAR_LIMIT = 90                  # ❌ VAR_LIMIT duplicated with = operator

3. Invalid Syntax Detection

Context-aware detection of undefined identifiers with smart exclusions:

• Standalone identifiers: Variables referenced but never defined
• Table headers: Column headers without parameter definitions
• Smart filtering: Excludes table cell values and assignment expressions
• Table structure awareness: Understands table context to prevent false positives
• ⚙️ Configurable: Enable/disable missing identifier checking

# Invalid syntax examples
UNKNOWN_VAR                 # ❌ Standalone undefined identifier
PARAM_Y?      PARAM_Z?   
UNKNOWN_ID    42            # ❌ PARAM_Y defined but UNKNOWN_ID not

# Smart exclusions (these are NOT flagged)
VAR_X: SOME_VALUE           # ✅ Part of assignment, not flagged
DATA_ROW CELL_VALUE         # ✅ Part of table data, not flagged

🎯 Column Alignment Features

• Zero-tolerance alignment checking - Detects misalignments as small as one character
• Smart value detection - Recognizes complex patterns:
  • Mathematical expressions: 40e-6, 100*int(FUNCTION)
  • Quoted arrays: ['OPTION_A'], ['MODE_A', 'MODE_B']
  • Nested objects: {'mapping':[{0:0}]}
  • Function calls: int(MULTIPLIER_VALUE)
• Formatting symbol exclusion - Ignores standalone symbols like *, -, ], } when checking alignment
• Error-level reporting - Column misalignments reported as errors for immediate attention

✨ Code Snippets

Type these prefixes and press Tab to expand:

• param → Parameter header template
• var → Variable header template
• section → Header section with parameter and variable
• bool → Boolean assignment
• row → Table row with tab-separated values
• comment → Comment block
• region → Collapsible region markers

User Configuration

Customize the extension behavior through VS Code settings (Ctrl+, → Extensions → Rule File Language):

Alignment Validation Settings

{
  "rulefile.validation.enableColumnAlignment": true,
  "rulefile.validation.alignmentTolerance": 0
}

• enableColumnAlignment: Enable/disable column alignment checking
• alignmentTolerance: Number of characters tolerance for alignment (0 = zero tolerance)

Duplicate Detection Settings

{
  "rulefile.validation.enableDuplicateDetection": true
}

• enableDuplicateDetection: Enable/disable detection of duplicate variable/parameter definitions

Invalid Syntax Detection Settings

{
  "rulefile.validation.enableInvalidSyntaxDetection": true
}

• enableInvalidSyntaxDetection: Enable/disable detection of undefined identifiers and missing indicators (standalone variables not defined as parameters)

Python Cross-Reference Settings ✨ NEW

{
  "rulefile.python.enableCrossReference": true,
  "rulefile.python.enableReverseReference": true
}

• enableCrossReference: Enable/disable Python → .rul "Go to Definition" functionality (Ctrl+Click on rules.VARIABLE_NAME)
• enableReverseReference: Enable/disable .rul → Python "Find References" functionality and Python reference counts in hover tooltips

Configuration Tips:

• Settings take effect immediately after changing (no restart required)
• You can disable Python integration entirely by setting both options to false
• Individual control: Keep cross-reference but disable reverse lookup, or vice versa
• Useful for large workspaces where Python file scanning might impact performance

Note: All validation features are enabled by default except duplicate detection. Python cross-reference features are enabled by default. To disable any feature, set the corresponding setting to false in your VS Code settings.

Testing Configuration Changes

To verify your configuration changes are working:

1. Python → .rul Navigation:

   • Disable: Set "rulefile.python.enableCrossReference": false
   • Test: Ctrl+Click on rules.VARIABLE_NAME in Python files should not navigate to .rul files

2. Reverse References (.rul → Python):

   • Disable: Set "rulefile.python.enableReverseReference": false
   • Test: Right-click "Find All References" in .rul files should only show .rul references
   • Test: Hover tooltips should not show Python reference counts

3. Both Features:

   • Disable all Python integration: Set both settings to false
   • Extension will function as a pure .rul file language support tool

Usage Examples

Parameter and Variable Headers

# Parameter definition (highlighted in blue)
PARAM_A?    PARAM_B?    PARAM_C?

# Variable assignments (highlighted in purple)  
VAR_X:        VAR_Y:             VAR_Z:
value1        ['OPTION_A']       ['1.0','1.1']
value2        ['OPTION_B']       ['1.2'...'1.5']

Complex Value Recognition

# Mathematical expressions recognized as single values
VAR_CALC    100*int(MULTIPLIER)    0

# Nested objects and arrays
VAR_CONFIG:    {'mapping':[{0:0}]}    ['OPTION_X']

# Function calls and scientific notation
VAR_NUMERIC:      40e-6    int(COMPUTE_VAL)

Navigation

• Click on PARAM_A? and press F12 to jump to all PARAM_A: assignments
• Right-click any identifier and select "Find All References" to see all usages in .rul AND Python files ✨
• Press F2 on any header to rename it across the entire file
• From Python files: Ctrl+Click on rules.VARIABLE_NAME to jump to .rul definition

Hover Information

Hover over any identifier to see:

• Number of parameter usages
• Number of variable assignments
• Number of standalone references
• Dependencies list - When hovering over a variable (e.g., PACK_QUAL:), see all parameters it depends on
• Number of Python references ✨ NEW

Example:

VAR_A:  VAR_B:  PARAM_X?
------------------------
True    False   ['OPTION']

Hovering over VAR_A: shows:

• Variable: VAR_A:
• Found 1 parameter usage(s) for this variable
• Dependencies:
  • PARAM_X
  • VAR_B (if used in the same table)

Installation

1. Download the .vsix file
2. In VS Code, press Ctrl+Shift+P and run "Extensions: Install from VSIX..."
3. Select the downloaded file
4. Reload VS Code

File Association

The extension automatically activates for files with these extensions:

• .rul

Language Configuration

The extension provides:

• Auto-indentation with 2-space tabs
• Bracket matching for [], {}, (), <>
• Comment toggling with Ctrl+/
• Region folding with #region / #endregion

Contributing

Found a bug or have a feature request? Please open an issue on the GitHub repository.

License

This extension is licensed under the MIT License.

Enjoy enhanced rule file editing with intelligent language support!