hooks-lib/scripts/internal/anti-corruption.js

// scripts/internal/anti-corruption.js
//
// HOOK_CONTRACT.md §9-§10: absorb Foundry hook shape churn so
// consumers see stable envelope.hook names and a documented
// args[] shape.
//
// v0.3.0 is Foundry v14 only (per tests/PLAN.md file header). v0.2.0
// supported both v13 and v14; v0.3.0 narrows to v14. The dual v13
// `renderChatLog` listener is dropped, and arg-normalization shapes
// assume v14's arity. If a future v14 micro-release renames a hook
// again, add the mapping here.
//
// §9 Hook rename mapping: the envelope.hook name is always the v14
// name. v13 mapping is out of scope.
//
// §10 Arg normalization: for hooks with unstable arity, pad/truncate
// to a documented shape. Consumers can rely on args[N].
//
// This module exports the *normalization functions* and the
// per-hook arg shape definitions. The dispatcher in envelope.js
// calls these for every fire.

import { getEntryForRawName } from "./registered-hooks.js";

// Arg shape per envelope name. undefined = no normalization
// (the args array is passed verbatim from Foundry).
//
// Each shape is a function (rawArgs) -> normalizedArgs.
//
// v0.3.0 documents shapes for: combatStart, combatEnd, combatTurn,
// combatRound, preUpdateActor, updateActor, preUpdateToken,
// updateToken, dnd5e.rollAttackV2, dnd5e.rollDamageV2.

export const ARG_SHAPES = {
  // combatStart(combat, updateData) — arity 2. Stable in v14.
  combatStart: (args) => normalizeArity(args, 2),

  // combatEnd(combat) — arity 1. Stable in v14.
  combatEnd: (args) => normalizeArity(args, 2),

  // combatTurn(combat, updateData, updateOptions) — arity 3. Stable in v14.
  combatTurn: (args) => normalizeArity(args, 3),

  // combatRound(combat, updateData, updateOptions) — arity 3 in v14.
  // Normalized to 4 args: [combat, updateData, updateOptions.round, updateOptions]
  // The third arg is always the round number; the fourth is options.
  // v13's (combat, updateData, roundNum) shape is out of scope.
  combatRound: (args) => {
    const out = [args[0], args[1], null, args[2] ?? null];
    if (args.length >= 3 && args[2] && typeof args[2] === "object") {
      out[2] = args[2].round ?? null;
    }
    return out;
  },

  // preUpdateActor(actor, updateData, options, userId) — arity 4.
  preUpdateActor: (args) => normalizeArity(args, 4),

  // updateActor(actor, updateData, options, userId) — arity 4.
  updateActor: (args) => normalizeArity(args, 4),

  // preUpdateToken(token, updateData, options, userId) — arity 4.
  preUpdateToken: (args) => normalizeArity(args, 4),

  // updateToken(token, updateData, options, userId) — arity 4.
  updateToken: (args) => normalizeArity(args, 4),

  // dnd5e.rollAttackV2(rolls, { subject, ammoUpdate }) — arity 2.
  "dnd5e.rollAttackV2": (args) => normalizeArity(args, 2),

  // dnd5e.rollDamageV2(rolls, { subject }) — arity 2.
  "dnd5e.rollDamageV2": (args) => normalizeArity(args, 2),
};

function normalizeArity(args, target) {
  const out = new Array(target).fill(undefined);
  for (let i = 0; i < Math.min(args.length, target); i++) {
    out[i] = args[i];
  }
  return out;
}

// §9 anti-corruption: synthesize combatInactive from updateCombat
// when active flips true→false. The synthesized envelope has
// hook === "combatInactive" and args === [combat].
//
// Returns an array of envelopes to emit (usually 1, possibly 2 if
// both updateCombat and combatInactive fire for the same event).
export function maybeSynthesize(rawHookName, args) {
  if (rawHookName !== "updateCombat") return null;
  const [combat, updateData] = args;
  if (!combat || !updateData) return null;
  if (!("active" in updateData)) return null;
  if (updateData.active !== false) return null;
  // combatInactive envelope: { ts, hook: "combatInactive", args: [combat] }
  // ts is set by the envelope builder, not here. We return the partial.
  return [{ hook: "combatInactive", args: [combat] }];
}