Reserved Keyword Validation

Cade reserves a fixed set of identifiers for its built-in vocabulary — block types, built-in functions, scope prefixes, and so on. Using a reserved name for a device, variable, or block can produce errors or warnings depending on the pragma mode. Two CLI commands help: cade validate checks for conflicts, and cade migrate can rename offenders automatically.

Keyword Categories

Every reserved identifier falls into one category. The category determines both its default severity and the kind of rename the migration tool will suggest.

Category	Examples	Typical severity
`block_type`	`device`, `event`, `variable`, `mode`	Error (strict conflict)
`sub_type`	`button`, `solenoid`, `score`, `timer`	Error when used as a block qualifier
`builtin_function`	`clamp`, `abs`, `min`, `max`	Error in variable or function names
`special_value`	`true`, `false`, `null`	Error
`scope_identifier`	`self`, `parent`, `global`	Error as a block name
`source_identifier`	`device`, `event`, `variable`	Contextual
`path_prefix`	`hw`, `sw`, `io`	Warning by default
`future_keyword`	Names reserved for planned features	Warning — may become an error in a future release

Pragma Modes

The pragma block (or the --pragma-mode flag) controls how strictly reserved names are enforced.

Mode	Strict keywords	Contextual keywords	Future keywords
`strict`	Error	Error	Error
`normal` (default)	Error	Warning	Warning
`relaxed`	Warning	Allow	Allow

Strict keywords cause an immediate parse or runtime conflict.
Contextual keywords only conflict in specific positions (for example, score is fine as a variable but not as a device name).
Future keywords are allowed today but are reserved for planned features — using them now risks a future break.

`cade validate --check-reserved-words`

Reserved word validation is opt-in, so existing configs that happen to collide with a reserved name keep working until you enable the check.

cade validate --check-reserved-words                       # Run the checks
cade validate --check-reserved-words --strict              # All reserved words become errors
cade validate --check-reserved-words --pragma-mode=relaxed # Only strict keywords warn
cade validate --strict                                     # Shortcut: implies --check-reserved-words

Flag	Default	Effect
`--check-reserved-words`	off	Run the reserved word stage.
`--strict`	off	Enable strict mode; also enables `--check-reserved-words`.
`--pragma-mode`	`normal`	Override the pragma mode (`strict`, `normal`, or `relaxed`).
`--ignore-pragma`	off	Skip the pragma block. Also skips reserved word checks.

Reserved word findings appear in all output formats (text, json, yaml), each tagged with its category and a list of suggested renames.

`cade migrate --reserved-words`

Use migrate to rewrite conflicting identifiers. Run it without --auto-fix first to preview the changes.

# Preview conflicts
cade migrate --reserved-words config.cade

# Rewrite in place (backs up each file as <file>.cade.bak)
cade migrate --reserved-words --auto-fix config.cade

# Scan a directory
cade migrate --reserved-words -d ./configs/

# Recursive scan
cade migrate --reserved-words -d ./configs/ -r

# Choose which severity tier to migrate
cade migrate --reserved-words --pragma-mode=strict config.cade

Preview output:

Reserved Word Conflicts: 3 found in 2 files

config.cade:12:3  device "score"  [block_type]
  Suggestions: my_score, game_score, custom_score

config.cade:18:1  variable "clamp"  [builtin_function]
  Suggestions: clamp_val, clamp_count

modes.cade:5:3  device "self"  [scope_identifier]
  Suggestions: my_self, this_device

With --auto-fix, the first suggestion from the suggestion engine replaces each conflicting name. A summary lists every rename applied, and each modified file is backed up as <file>.cade.bak before writing.

Exit codes:

Code	Meaning
`0`	No conflicts found, or `--auto-fix` completed cleanly
`1`	Conflicts found (preview) or error during fix

Flag	Default	Effect
`--auto-fix`	off	Rewrite files using suggestions (preview only when omitted).
`--format`	`text`	Output format — `text` or `json`.
`-d <dir>`	—	Directory of `.cade` files to scan.
`-r`	off	Recurse into subdirectories.
`--pragma-mode`	`normal`	Which severity tier gets migrated.

Suggestion Patterns

The migration tool picks a rename strategy based on where the name is used:

Context	Typical rename
Block name	Prefix with `my_`, `game_`, or `custom_`
Variable name	Suffix with `_val`, `_count`, or `_total`
Function name	Prefix with `calc_` or `compute_`