Card-script param declarations (batch 1: framework classes)

[MostCromulent]

Batch 1 of the per-class card-script parameter declarations proposed in #10984 (comment).

Summary

This batch covers the framework/base classes rather than individual effects. These classes hold the parameters shared across nearly every ability — costs, conditions, activation/target restrictions, descriptions, Defined, sub-ability keys, and AI hints — so their params are all optional and together form the base set that every effect inherits. Effect classes (later batches) will declare their own params on top of this base and additionally mark which are required.

Each class now exposes a public static final String[] OPTIONAL_PARAMS listing the params it reads, making the parameters a class consumes self-documenting.

How the params were chosen

The list for each class was produced programmatically, not hand-picked: a regex scanner reads each class's source for the literal forms a param read takes — getParam/hasParam/getParamOrDefault calls, the defined-resolution helpers (getCards, getDefinedPlayersOrTargeted, …), map lookups, and positional helpers like addToCombat — and each class declares exactly that set. The same matcher backs the drift test, so the lists are mechanically reproducible rather than a one-off snapshot.

Claude then adversarially reviewed the scanner's rules and its output against the source: this is what caught false positives — e.g. defined-values like "Self" and "Targeted" being mistaken for param names — and tightened the rules. SpellAbilityAi is the one hand-curated list: as a cross-cutting reader it touches params owned by many effects, so it declares only its own AI* knobs.

The drift test

CardScriptParamDeclarationTest fails if a class reads a param it doesn't declare, or declares one that appears nowhere in its source — so the declarations can't silently fall out of sync with the code. It is opt-in per class, so later batches can land a few classes at a time.

---

🤖 Generated with Claude Code

[tool4ever]

getParamOrDefaultBoolean doesn't exist?

[tool4ever]

Destination is effect specific?

[tool4ever]

I'd still like to see additionalAbilityKeys unioned here less manually

[tool4ever]

would like to see the Hash* fields queried instead if possible

[tool4ever]

sometimes, like with CumulativeUpkeep they are only used internally as helper

so for this case if it'd show up in a script it'd actually be wrong

conceptually I'm not sure yet if we need a third category for params that are technically still implemented but very exotic/deprecated instead 🤔

[tool4ever]

In general direction seems good.

So the deciding question is whether these params need to be queryable from the engine at runtime, or only validated in a build check. The first justifies the interface; the second is solved by discovery alone, independent of declaration form.

I want runtime so the Card Workshop can eventually also make partial use of these. 💡

For now I'd still like to see the scope more clearly defined:

1. I guess we're looking at covering syntax for a pretty good amount of our standard.
   Is there anything we can't detect easily which can at least be noted as "skipped" - consider options for confidence interval + statistics available?

2. We'll also have some simpler semantics checks (e.g. unused SVar)
   Is this one still easier with Python so we'll have a clean responsibility split - or would it now only be responsible for the PR commenting part?

3. What parts of 1+2 run via the normal test suite and what only gets included when CI?
   Should we support different failure modes (Warning vs. Error) depending on
   a) execution context
   b) type of logic error
   c) type of script

4. Before doing more batches devise strategy with the fields in CardScriptParser

• Imo they should be refactored together to avoid redundancy
• This might mean MVP of these two PR first

5. if the parent PR tests more of the syntax via Java does it get much slower? Should it be limited only to /upcoming?

6. Is there still a use case for keeping the corpus discovery approach? E.g. it might be too messy to also manually define each Params accepted values (+ we're far from being consistent in including "Defined" or "Valid" in their names)
   And sometimes only "True" is valid and others like CombatDamage are actually tri-state...

---

So the future order could be this:

1. Java test: IHasForgeParams alignment
2. Java test: check for valid API
3. Java test: Linter
4. Python via CI: compare with Scryfall
5. Github workflow: post findings from 3.+4. as comments

Might actually be worth a markdown file explaining these workflow steps 🤔