Bugfix/error message dsl validator (#223)

* Improve logging reverse debug errors that were incorrect

* Add changelog

* Improve upgrading docs

* Add more clarity to upgrading

CHANGELOG.md

@@ -6,6 +6,7 @@
 ### Changed
 
 ### Fixed
+- The DSL Validator was returning an invalid debug message when using an invalid name ([luke-hill])
 
 ## [5.0.3] - 2024-06-19
 ### Changed

UPGRADING.md

@@ -10,7 +10,7 @@ checks from being performed during the build metaprogram phase of suite executio
 An additional piece of work to further amplify the gems logging has been done, so no additional work from the user
 is required to make these changes function or be diagnosable (Should something go wrong).
 
-NB: `no` as a filename was erroneously banned in the early `5.0.x` versions
+NB: `no` as a DSL item name was erroneously banned in the early `5.0.x` versions
 
 ## Shadow Root
 
@@ -37,6 +37,15 @@ revert back to the default Capybara logic. The usage of this method on `SitePris
 
 An initial attempt to start banning invalid DSL names has been introduced through a `DSLValidator` module.
 
+Initial Validation will see DSL names banned that ...
+- Do not start with a lower case letter (Should be using Ruby formats for snake_case)
+- Start with `no_` or `_`. These will confuse some of the meta-programmed matchers
+- End with `_` or `?`. The ending with a `_` is a stylistic preference but ending in a `?` will yield a ruby error 
+- Match any of the following names which conflict with other DSL's
+  - `attributes` (This is a reserved testing word - both RSpec and Minitest need this)
+  - `html` / `title` (These are reserved Capybara DSL words)
+  - `element` / `elements` / `section` / `sections` / `iframe` (These are reserved SitePrism DSL words)
+
 For `4.x` this will be disabled by default. We may look to switch this to a default on/toggleable state further down
 the road, but for now this is experimental.
 

lib/site_prism/dsl/validator.rb

@@ -42,7 +42,7 @@ def characters_invalid?(name)
       def blacklisted?(name)
         return false unless blacklisted_names.include?(name)
 
-        log_failure(name, 'name (blacklisted entry)')
+        log_failure(name, "name (#{name} is a blacklisted entry)")
       end
 
       def regex_permission
@@ -77,16 +77,16 @@ def blacklisted_names
       end
 
       def log_failure(name, type)
-        self.dsl_name_error = "DSL item: #{name} is invalid. Issue: #{type}"
+        self.dsl_name_error = "DSL item: '#{name}' is invalid. Issue: #{type}"
         SitePrism.logger.debug(debug_error(type))
       end
 
       def debug_error(type)
         case type
         when 'prefix';       then "Invalid Prefixes: #{prefix_blacklist.join(', ')}."
         when 'suffix';       then "Invalid Suffixes: #{suffix_blacklist.join(', ')}"
-        when 'character(s)'; then "Invalid DSL Names: #{blacklisted_names.join(', ')}"
-        else                      "DSL Charset REGEX: #{regex_permission.inspect}"
+        when 'character(s)'; then "DSL Charset REGEX: #{regex_permission.inspect}"
+        else                      "Invalid DSL Names: #{blacklisted_names.join(', ')}"
         end
       end
     end