Tracking: tools/check style-check roadmap

[itsgrimetime]

Following #2670 (tools/check with jobj-flags + assert-macros), collecting
proposed checks and tooling so we can agree on shape before implementing each.
Comments on scope/shape welcome before any PR.

Tooling

• --fix mode — apply fixes locally (not CI). jobj-flags is byte-safe;
  assert-macros is best-effort (dev builds + verifies, @todos stragglers).
  Dry-run diff by default. (suggested by @ribbanya)
• Generalize the flag check to config-driven (function name, parameter index) → flag set, resolving raw literals (incl. composite masks, via bit-shift
  decomposition like tools/flags) to the named flags. Subsumes jobj-flags.

Proposed checks

• Arbitrary JObj flags — any raw literal in HSD_JObj*Flags* resolvable to
  named JOBJ_* flags (generalizes the current 0x10→JOBJ_HIDDEN check).
• Fighter motion-state flags in Fighter_ChangeMotionState calls — raw
  literals → named flags.
• Extern data that should be literal (floats, strings, …). ⚠️ needs a rule
  to distinguish de-inlining anti-patterns from legit cross-TU pool-sharing
  externs (e.g. zako matches ftcoattack100 #2666 extern f32 ftCo_804D90D0), or it false-positives.
• Named identifier where a literal belongs (the use-site side of the above);
  same contextual caveat.

References

• tools/flags — decomposes a literal into its bit-shifted flag set.

Open questions for maintainers

• Which checks should be blocking CI vs advisory?
• Preferred config format for (function, param) → flagset?
• For the extern/literal pair: how do we reliably separate anti-pattern from
  intentional cross-TU externs?

[ribbanya]

• Generalize the flag check to config-driven (function name, parameter index) → flag set, resolving raw literals (incl. composite masks, via bit-shift
  decomposition like tools/flags) to the named flags. Subsumes jobj-flags.

Not config, just reusing the same code for multiple flag sets.

• Extern data that should be literal (floats, strings, …). ⚠️ needs a rule
  to distinguish de-inlining anti-patterns from legit cross-TU pool-sharing
  externs (e.g. zako matches ftcoattack100 #2666 extern f32 ftCo_804D90D0), or it false-positives.

This isn't necessary. If an extern is supposed to exist, it will be in a header, not a source file. If you want to check headers anyway, you could check for the /* 123456 */ addressing pattern. "Cross-TU pool-sharing externs" are either bad splits or need to be manually declared in the header of the TU in which the data is defined.

• Preferred config format for (function, param) → flagset?

Just Python, maybe dataclasses.

[itsgrimetime]

Makes sense — I'll take the flag checks as reused Python over dataclass-defined flag sets (not a config format), keep them syntactic (function name + parameter index), and drop the extern-should-be-literal check. That last one checks out: there are 0 data externs in .c files (they're all in headers already), and ~615 legit /* addr */ extern declarations in headers, so an address-comment check would be almost entirely false positives.

A few things to pin down before I generalize tools/check:

1. Flag sets — hand-written or parsed from the headers? i.e. just the values we use (JOBJ_HIDDEN = 1 << 4) written as dataclasses, vs parsing jobj.h's #define JOBJ_* (1 << n) so they stay in sync automatically. The latter is more work but self-maintaining.
2. Composite masks: should a raw 0x30 be decomposed to JOBJ_SKELETON | JOBJ_HIDDEN and flagged, or do we only flag single-flag literals?
3. Flag reads (x->flags & 0x10): worth a check? There's nothing in-tree to catch right now (the reads are all named already), and it's the one form that needs type info rather than a function-name match.
4. Confirming the extern check is dropped (reading "isn't necessary" as: don't build it).

For the first pass I'm planning these flag-call families: HSD_JObjSetFlagsAll/HSD_JObjClearFlagsAll (JObj flags — already done) and Fighter_ChangeMotionState (motion-state flags). Any others you'd want covered up front?