fix: throw clear errors when constant instantiation is performed through YAML directly

[DanySK]

No description provided.

[Copilot]

Pull request overview

Improves YAML loading feedback by failing fast with a clearer error when a constant is mistakenly declared as a direct scalar under variables (instead of using the supported variable/constant syntax).

Changes:

• Add an explicit IllegalArgumentException for scalar (Number/String/Boolean) variable entries during constant evaluation.
• Provide an in-message pointer to the YAML spec and a suggested workaround snippet.

[Copilot]

The exception message links to .../reference/yaml/index.html#variable, but the docs in this repo reference the variables section as /reference/yaml/#variables (e.g., site/content/howtos/simulation/variables/_index.md:10). Please update the URL/anchor so the guidance doesn’t send users to a dead/incorrect page.

Suggested change

	> https://alchemistsimulator.github.io/reference/yaml/index.html#variable
	> https://alchemistsimulator.github.io/reference/yaml/#variables

[Copilot]

The suggested workaround snippet uses formula: > $root, but visitDependentVariable treats String formulas as JSR-223 code (not string literals). If $root is a YAML String, following this advice will likely evaluate as an identifier and fail unless it’s quoted as a language literal. Consider tailoring the message by type (e.g., numeric/list constants can use a non-string formula, while string constants need explicit quoting guidance).

Suggested change

	fun unsupportedConstantInstantiation(): Nothing = throw IllegalArgumentException(
	"""
	Constant creation failed: '$name' with value '$root'.
	Direct constant instantiation from YAML is not supported, please consult the Alchemist YAML spec at:
	> https://alchemistsimulator.github.io/reference/yaml/index.html#variable
	Likely workaround:
	```yaml
	$name:
	formula: >
	$root
	```
	""".trimIndent(),
	)
	fun formulaLiteral(value: Any?): String = when (value) {
	is String -> "\"" + value.replace("\\", "\\\\").replace("\"", "\\\"") + "\""
	else -> value.toString()
	}
	fun unsupportedConstantInstantiation(): Nothing {
	val suggestedFormula = formulaLiteral(root)
	throw IllegalArgumentException(
	"""
	Constant creation failed: '$name' with value '$root'.
	Direct constant instantiation from YAML is not supported, please consult the Alchemist YAML spec at:
	> https://alchemistsimulator.github.io/reference/yaml/index.html#variable
	Likely workaround:
	```yaml
	$name:
	formula: >
	$suggestedFormula
	```
	""".trimIndent(),
	)
	}

[Copilot]

This change introduces a new hard failure for scalar entries under variables (Number/String/Boolean). There are existing YAML-loading regression tests for variables/constants (e.g., alchemist-loading/src/test/kotlin/it/unibo/alchemist/test/TestKtVariable.kt); please add a regression test that loads a YAML with variables: { someConst: 3 } (and/or a scalar string/boolean) and asserts that the thrown exception is the new, user-friendly one.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud