Package io.github.jspinak.brobot.runner.json.validation.crossref

package io.github.jspinak.brobot.runner.json.validation.crossref
Cross-reference validation for configuration integrity.

This package contains validators that ensure all references within configurations point to valid targets. It prevents broken references that would cause runtime failures and maintains referential integrity across the entire configuration.

Validators

Reference Types

State References

  • Transition source and target states
  • Initial state declarations
  • State image associations
  • Hidden state references

Function References

  • Function calls in DSL
  • Button action functions
  • Transition action functions
  • Parameter type references

Image References

  • StateImage pattern files
  • ObjectCollection images
  • Dynamic image references

Validation Examples

State Reference Validation


 // Valid: state exists
 {
   "transition": {
     "from": "loginPage",    // Must exist in states
     "to": "dashboardPage"   // Must exist in states
   }
 }

 // Invalid: state doesn't exist
 {
   "transition": {
     "from": "loginPage",
     "to": "unknownPage"  // ERROR: State not found
   }
 }

Function Reference Validation


 // Valid: function defined
 {
   "button": {
     "action": "loginUser",  // Function exists
     "parameters": {
       "username": "admin"
     }
   }
 }

 // Invalid: undefined function
 {
   "button": {
     "action": "doSomething"  // ERROR: Function not found
   }
 }

Circular Reference Detection


 // Detects circular dependencies
 validator.detectCircularReferences(configuration);

 // Example circular reference
 State A -> includes -> State B
 State B -> includes -> State C
 State C -> includes -> State A  // ERROR: Circular

Reference Resolution

The validation process includes:

  1. Build reference index from definitions
  2. Scan configuration for references
  3. Resolve each reference to its target
  4. Report unresolved references
  5. Detect circular dependencies

Error Reporting


 ValidationError error = new ValidationError(
     ValidationSeverity.ERROR,
     "State 'unknownState' referenced in transition " +
     "at $.transitions[2].to does not exist",
     "$.transitions[2].to"
 );

 // Suggestions included
 error.setSuggestion("Did you mean 'knownState'?");

Performance Optimization

  • Build reference index once
  • Use maps for O(1) lookups
  • Cache validation results
  • Validate incrementally when possible

Best Practices

  • Validate references before business rules
  • Include path to broken reference
  • Suggest similar valid references
  • Group related reference errors
  • Support case-insensitive matching option
Since:
1.0
See Also: