/**
* Larissa RPG System - Ability Node Graph Validation
* ABILITY-01: Validates fixed targeting/filter/sequence/condition/effect nodes,
* parameter constraints, node references, and directed cycle detection.
*/
/** Fixed node vocabulary supported by the Larissa ability composition runtime. */
export const ABILITY_NODE_VOCABULARY = Object.freeze([
'target',
'filter',
'sequence',
'condition',
'projectile',
'area_effect',
'damage',
'heal',
'status',
'knockback',
'timed_action',
'presentation'
]);
export const ABILITY_NODE_TYPES = ABILITY_NODE_VOCABULARY;
const NODE_TYPE_SET = new Set(ABILITY_NODE_VOCABULARY);
export const VALID_TARGET_TYPES = Object.freeze([
'self',
'caster',
'target',
'cursor',
'point',
'direction',
'directional',
'area',
'cone',
'radius',
'nearest_enemy',
'nearest_ally',
'hostile',
'friendly',
'any',
'allies',
'enemies',
'entity',
'enemy',
'ally',
'neutral',
'player',
'npc'
]);
const TARGET_TYPE_SET = new Set(VALID_TARGET_TYPES);
export const VALID_DIRECTION_MODES = Object.freeze([
'cursor',
'target',
'forward',
'caster_facing',
'target_facing',
'away_from_caster',
'towards_caster',
'away_from_source',
'towards_source',
'movement',
'cardinal',
'random'
]);
const DIRECTION_MODE_SET = new Set(VALID_DIRECTION_MODES);
/** Custom error thrown when ability definition validation fails in assertValid(). */
export class AbilityValidationError extends Error {
constructor(message, diagnostics = {}) {
super(message);
this.name = 'AbilityValidationError';
this.errors = diagnostics.errors ?? [];
this.warnings = diagnostics.warnings ?? [];
}
}
function isPositiveNumber(val) {
return typeof val === 'number' && Number.isFinite(val) && val > 0;
}
function isNonNegativeNumber(val) {
return typeof val === 'number' && Number.isFinite(val) && val >= 0;
}
function isPositiveInteger(val) {
return typeof val === 'number' && Number.isInteger(val) && val > 0;
}
function isValidDirection(val) {
if (typeof val === 'string') {
return DIRECTION_MODE_SET.has(val.toLowerCase());
}
if (val && typeof val === 'object') {
return Number.isFinite(val.x) && Number.isFinite(val.y) && (val.x !== 0 || val.y !== 0);
}
return false;
}
function isValidTargetType(val) {
if (typeof val !== 'string') return false;
return TARGET_TYPE_SET.has(val.toLowerCase());
}
/**
* Returns all outgoing reference edges from a node for flow & cycle tracking.
* @param {Object} node
* @returns {Array<{ targetId: string, field: string }>}
*/
function getOutgoingEdges(node) {
const edges = [];
if (!node || typeof node !== 'object') return edges;
if (typeof node.next === 'string' && node.next) {
edges.push({ targetId: node.next, field: 'next' });
}
if (Array.isArray(node.children)) {
for (let i = 0; i < node.children.length; i++) {
if (typeof node.children[i] === 'string' && node.children[i]) {
edges.push({ targetId: node.children[i], field: `children[${i}]` });
}
}
}
const singleRefFields = [
'onTrue',
'onFalse',
'onExpire',
'onComplete',
'onTick',
'onMiss',
'targetNode',
'success',
'failure'
];
for (const field of singleRefFields) {
if (typeof node[field] === 'string' && node[field]) {
edges.push({ targetId: node[field], field });
}
}
if (typeof node.onHit === 'string' && node.onHit) {
edges.push({ targetId: node.onHit, field: 'onHit' });
} else if (Array.isArray(node.onHit)) {
for (let i = 0; i < node.onHit.length; i++) {
if (typeof node.onHit[i] === 'string' && node.onHit[i]) {
edges.push({ targetId: node.onHit[i], field: `onHit[${i}]` });
}
}
}
return edges;
}
export class AbilityValidator {
/**
* Validates an ability graph definition against structural, parameter, and graph rules.
* @param {Object} abilityDef
* @returns {{ valid: boolean, errors: Array<{ code: string, message: string, path: string, nodeId: string|null }>, warnings: Array<{ message: string, path: string, nodeId: string|null }> }}
*/
static validate(abilityDef) {
const errors = [];
const warnings = [];
if (!abilityDef || typeof abilityDef !== 'object' || Array.isArray(abilityDef)) {
errors.push({
code: 'INVALID_ROOT',
message: 'Ability definition must be a non-null object',
path: '',
nodeId: null
});
return { valid: false, errors, warnings };
}
// 1. Root fields validation
if (typeof abilityDef.id !== 'string' || !abilityDef.id.trim()) {
errors.push({
code: 'MISSING_ROOT_FIELD',
message: "Ability 'id' must be a non-empty string",
path: 'id',
nodeId: null
});
}
if (typeof abilityDef.name !== 'string' || !abilityDef.name.trim()) {
errors.push({
code: 'MISSING_ROOT_FIELD',
message: "Ability 'name' must be a non-empty string",
path: 'name',
nodeId: null
});
}
if (!abilityDef.nodes || typeof abilityDef.nodes !== 'object') {
errors.push({
code: 'MISSING_ROOT_FIELD',
message: "Ability 'nodes' must be a non-null object or array",
path: 'nodes',
nodeId: null
});
}
if (typeof abilityDef.entryNodeId !== 'string' || !abilityDef.entryNodeId.trim()) {
errors.push({
code: 'MISSING_ROOT_FIELD',
message: "Ability 'entryNodeId' must be a non-empty string",
path: 'entryNodeId',
nodeId: null
});
}
if (errors.length > 0 && !abilityDef.nodes) {
return { valid: false, errors, warnings };
}
// 2. Index nodes into a Map
const nodeMap = new Map();
if (Array.isArray(abilityDef.nodes)) {
if (abilityDef.nodes.length === 0) {
errors.push({
code: 'EMPTY_NODES',
message: "Ability 'nodes' array cannot be empty",
path: 'nodes',
nodeId: null
});
}
for (let i = 0; i < abilityDef.nodes.length; i++) {
const item = abilityDef.nodes[i];
if (!item || typeof item !== 'object') {
errors.push({
code: 'INVALID_NODE',
message: `Node at index ${i} must be an object`,
path: `nodes[${i}]`,
nodeId: null
});
continue;
}
if (typeof item.id !== 'string' || !item.id.trim()) {
errors.push({
code: 'MISSING_NODE_ID',
message: `Node at index ${i} is missing a string 'id'`,
path: `nodes[${i}].id`,
nodeId: null
});
continue;
}
if (nodeMap.has(item.id)) {
errors.push({
code: 'DUPLICATE_NODE_ID',
message: `Duplicate node ID '${item.id}'`,
path: `nodes[${i}].id`,
nodeId: item.id
});
continue;
}
nodeMap.set(item.id, { node: item, path: `nodes[${i}]` });
}
} else if (abilityDef.nodes && typeof abilityDef.nodes === 'object') {
const entries = Object.entries(abilityDef.nodes);
if (entries.length === 0) {
errors.push({
code: 'EMPTY_NODES',
message: "Ability 'nodes' object cannot be empty",
path: 'nodes',
nodeId: null
});
}
for (const [key, item] of entries) {
if (!item || typeof item !== 'object') {
errors.push({
code: 'INVALID_NODE',
message: `Node '${key}' must be an object`,
path: `nodes.${key}`,
nodeId: key
});
continue;
}
if (item.id !== undefined && item.id !== key) {
errors.push({
code: 'MISMATCHED_NODE_ID',
message: `Node key '${key}' does not match node.id '${item.id}'`,
path: `nodes.${key}.id`,
nodeId: key
});
}
nodeMap.set(key, { node: item, path: `nodes.${key}` });
}
}
// Check entryNodeId existence
if (abilityDef.entryNodeId && typeof abilityDef.entryNodeId === 'string') {
if (!nodeMap.has(abilityDef.entryNodeId)) {
errors.push({
code: 'MISSING_ENTRY_NODE',
message: `Entry node '${abilityDef.entryNodeId}' not found in 'nodes'`,
path: 'entryNodeId',
nodeId: abilityDef.entryNodeId
});
}
}
// 3. Node type and parameter validation
for (const [nodeId, { node, path }] of nodeMap.entries()) {
if (typeof node.type !== 'string' || !node.type.trim()) {
errors.push({
code: 'MISSING_NODE_TYPE',
message: `Node '${nodeId}' is missing a valid 'type'`,
path: `${path}.type`,
nodeId
});
continue;
}
if (!NODE_TYPE_SET.has(node.type)) {
errors.push({
code: 'UNKNOWN_NODE_TYPE',
message: `Unknown node type '${node.type}' in node '${nodeId}'`,
path: `${path}.type`,
nodeId
});
continue;
}
// Per-node-type parameter validation
switch (node.type) {
case 'target': {
if (node.targetType !== undefined && !isValidTargetType(node.targetType)) {
errors.push({
code: 'INVALID_TARGET_TYPE',
message: `Invalid targetType '${node.targetType}' in target node '${nodeId}'`,
path: `${path}.targetType`,
nodeId
});
}
if (node.mode !== undefined && !isValidTargetType(node.mode)) {
errors.push({
code: 'INVALID_TARGET_TYPE',
message: `Invalid targeting mode '${node.mode}' in target node '${nodeId}'`,
path: `${path}.mode`,
nodeId
});
}
if (node.targeting !== undefined && !['hostile', 'friendly', 'any', 'allies', 'enemies'].includes(node.targeting)) {
errors.push({
code: 'INVALID_TARGET_TYPE',
message: `Invalid targeting '${node.targeting}' in target node '${nodeId}'`,
path: `${path}.targeting`,
nodeId
});
}
if (node.range !== undefined && !isPositiveNumber(node.range)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'range' in node '${nodeId}' must be a positive number, got ${node.range}`,
path: `${path}.range`,
nodeId
});
}
if (node.radius !== undefined && !isPositiveNumber(node.radius)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'radius' in node '${nodeId}' must be a positive number, got ${node.radius}`,
path: `${path}.radius`,
nodeId
});
}
if (node.angle !== undefined && !isPositiveNumber(node.angle)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'angle' in node '${nodeId}' must be a positive number, got ${node.angle}`,
path: `${path}.angle`,
nodeId
});
}
if (node.maxTargets !== undefined && !isPositiveInteger(node.maxTargets)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'maxTargets' in node '${nodeId}' must be a positive integer, got ${node.maxTargets}`,
path: `${path}.maxTargets`,
nodeId
});
}
if (node.duration !== undefined && !isPositiveNumber(node.duration)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'duration' in node '${nodeId}' must be a positive number, got ${node.duration}`,
path: `${path}.duration`,
nodeId
});
}
break;
}
case 'filter': {
if (node.targetType !== undefined && !isValidTargetType(node.targetType)) {
errors.push({
code: 'INVALID_TARGET_TYPE',
message: `Invalid targetType '${node.targetType}' in filter node '${nodeId}'`,
path: `${path}.targetType`,
nodeId
});
}
if (node.maxTargets !== undefined && !isPositiveInteger(node.maxTargets)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'maxTargets' in node '${nodeId}' must be a positive integer, got ${node.maxTargets}`,
path: `${path}.maxTargets`,
nodeId
});
}
break;
}
case 'sequence': {
if (!Array.isArray(node.children) || node.children.length === 0) {
errors.push({
code: 'INVALID_PARAMETER',
message: `Sequence node '${nodeId}' must have a non-empty array of children`,
path: `${path}.children`,
nodeId
});
}
break;
}
case 'condition': {
if (!node.onTrue && !node.onFalse && !node.next) {
errors.push({
code: 'INVALID_PARAMETER',
message: `Condition node '${nodeId}' must define at least 'onTrue', 'onFalse', or 'next'`,
path: path,
nodeId
});
}
break;
}
case 'projectile': {
const speed = node.speed ?? node.projectileSpeed;
if (speed === undefined || !isPositiveNumber(speed)) {
const field = node.projectileSpeed !== undefined ? 'projectileSpeed' : 'speed';
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property '${field}' in projectile node '${nodeId}' must be a positive number, got ${speed}`,
path: `${path}.${field}`,
nodeId
});
}
const range = node.range ?? node.maxDistance;
if (range !== undefined && !isPositiveNumber(range)) {
const field = node.maxDistance !== undefined ? 'maxDistance' : 'range';
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property '${field}' in projectile node '${nodeId}' must be a positive number, got ${range}`,
path: `${path}.${field}`,
nodeId
});
}
const radius = node.radius ?? node.size;
if (radius !== undefined && !isPositiveNumber(radius)) {
const field = node.size !== undefined ? 'size' : 'radius';
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property '${field}' in projectile node '${nodeId}' must be a positive number, got ${radius}`,
path: `${path}.${field}`,
nodeId
});
}
const duration = node.duration ?? node.lifetime;
if (duration !== undefined && !isPositiveNumber(duration)) {
const field = node.lifetime !== undefined ? 'lifetime' : 'duration';
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property '${field}' in projectile node '${nodeId}' must be a positive number, got ${duration}`,
path: `${path}.${field}`,
nodeId
});
}
const dir = node.direction ?? node.directionMode;
if (dir !== undefined && !isValidDirection(dir)) {
const field = node.directionMode !== undefined ? 'directionMode' : 'direction';
errors.push({
code: 'INVALID_DIRECTION_MODE',
message: `Invalid direction mode in projectile node '${nodeId}'`,
path: `${path}.${field}`,
nodeId
});
}
break;
}
case 'area_effect': {
if (node.radius !== undefined && !isPositiveNumber(node.radius)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'radius' in area_effect node '${nodeId}' must be a positive number, got ${node.radius}`,
path: `${path}.radius`,
nodeId
});
}
if (node.width !== undefined && !isPositiveNumber(node.width)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'width' in area_effect node '${nodeId}' must be a positive number, got ${node.width}`,
path: `${path}.width`,
nodeId
});
}
if (node.height !== undefined && !isPositiveNumber(node.height)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'height' in area_effect node '${nodeId}' must be a positive number, got ${node.height}`,
path: `${path}.height`,
nodeId
});
}
if (node.range !== undefined && !isPositiveNumber(node.range)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'range' in area_effect node '${nodeId}' must be a positive number, got ${node.range}`,
path: `${path}.range`,
nodeId
});
}
if (node.duration !== undefined && !isNonNegativeNumber(node.duration)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'duration' in area_effect node '${nodeId}' must be a non-negative number, got ${node.duration}`,
path: `${path}.duration`,
nodeId
});
}
const tickRate = node.tickRate ?? node.interval;
if (tickRate !== undefined && !isPositiveNumber(tickRate)) {
const field = node.interval !== undefined ? 'interval' : 'tickRate';
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property '${field}' in area_effect node '${nodeId}' must be a positive number, got ${tickRate}`,
path: `${path}.${field}`,
nodeId
});
}
const dir = node.direction ?? node.directionMode;
if (dir !== undefined && !isValidDirection(dir)) {
const field = node.directionMode !== undefined ? 'directionMode' : 'direction';
errors.push({
code: 'INVALID_DIRECTION_MODE',
message: `Invalid direction mode in area_effect node '${nodeId}'`,
path: `${path}.${field}`,
nodeId
});
}
break;
}
case 'damage': {
const dmg = node.amount ?? node.damage ?? node.value;
if (dmg === undefined || !isPositiveNumber(dmg)) {
const field = node.damage !== undefined ? 'damage' : (node.value !== undefined ? 'value' : 'amount');
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property '${field}' in damage node '${nodeId}' must be a positive number, got ${dmg}`,
path: `${path}.${field}`,
nodeId
});
}
if (node.multiplier !== undefined && !isPositiveNumber(node.multiplier)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'multiplier' in damage node '${nodeId}' must be a positive number, got ${node.multiplier}`,
path: `${path}.multiplier`,
nodeId
});
}
if (node.criticalMultiplier !== undefined && !isPositiveNumber(node.criticalMultiplier)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'criticalMultiplier' in damage node '${nodeId}' must be a positive number, got ${node.criticalMultiplier}`,
path: `${path}.criticalMultiplier`,
nodeId
});
}
if (node.criticalChance !== undefined && (!Number.isFinite(node.criticalChance) || node.criticalChance < 0 || node.criticalChance > 1)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'criticalChance' in damage node '${nodeId}' must be a number between 0 and 1, got ${node.criticalChance}`,
path: `${path}.criticalChance`,
nodeId
});
}
break;
}
case 'heal': {
const heal = node.amount ?? node.heal ?? node.value;
if (heal === undefined || !isPositiveNumber(heal)) {
const field = node.heal !== undefined ? 'heal' : (node.value !== undefined ? 'value' : 'amount');
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property '${field}' in heal node '${nodeId}' must be a positive number, got ${heal}`,
path: `${path}.${field}`,
nodeId
});
}
break;
}
case 'status': {
const statusId = node.statusId ?? node.status ?? node.name ?? node.effect;
if (typeof statusId !== 'string' || !statusId.trim()) {
errors.push({
code: 'INVALID_PARAMETER',
message: `Status node '${nodeId}' requires a non-empty status identifier string`,
path: `${path}.status`,
nodeId
});
}
if (node.duration === undefined || !isPositiveNumber(node.duration)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'duration' in status node '${nodeId}' must be a positive number, got ${node.duration}`,
path: `${path}.duration`,
nodeId
});
}
if (node.stacks !== undefined && !isPositiveInteger(node.stacks)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'stacks' in status node '${nodeId}' must be a positive integer, got ${node.stacks}`,
path: `${path}.stacks`,
nodeId
});
}
if (node.maxStacks !== undefined && !isPositiveInteger(node.maxStacks)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'maxStacks' in status node '${nodeId}' must be a positive integer, got ${node.maxStacks}`,
path: `${path}.maxStacks`,
nodeId
});
}
const tickRate = node.tickRate ?? node.interval;
if (tickRate !== undefined && !isPositiveNumber(tickRate)) {
const field = node.interval !== undefined ? 'interval' : 'tickRate';
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property '${field}' in status node '${nodeId}' must be a positive number, got ${tickRate}`,
path: `${path}.${field}`,
nodeId
});
}
break;
}
case 'knockback': {
const force = node.force ?? node.distance ?? node.speed;
if (force === undefined || !isPositiveNumber(force)) {
const field = node.distance !== undefined ? 'distance' : (node.speed !== undefined ? 'speed' : 'force');
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property '${field}' in knockback node '${nodeId}' must be a positive number, got ${force}`,
path: `${path}.${field}`,
nodeId
});
}
const dir = node.direction ?? node.directionMode;
if (dir !== undefined && !isValidDirection(dir)) {
const field = node.directionMode !== undefined ? 'directionMode' : 'direction';
errors.push({
code: 'INVALID_DIRECTION_MODE',
message: `Invalid direction mode in knockback node '${nodeId}'`,
path: `${path}.${field}`,
nodeId
});
}
if (node.duration !== undefined && !isPositiveNumber(node.duration)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'duration' in knockback node '${nodeId}' must be a positive number, got ${node.duration}`,
path: `${path}.duration`,
nodeId
});
}
break;
}
case 'timed_action': {
const dur = node.duration ?? node.delay;
if (dur === undefined || !isPositiveNumber(dur)) {
const field = node.delay !== undefined ? 'delay' : 'duration';
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property '${field}' in timed_action node '${nodeId}' must be a positive number, got ${dur}`,
path: `${path}.${field}`,
nodeId
});
}
break;
}
case 'presentation': {
if (node.duration !== undefined && !isNonNegativeNumber(node.duration)) {
errors.push({
code: 'OUT_OF_RANGE_NUMERIC',
message: `Property 'duration' in presentation node '${nodeId}' must be a non-negative number, got ${node.duration}`,
path: `${path}.duration`,
nodeId
});
}
break;
}
}
// 4. Validate referenced node IDs exist in nodes
if (node.next !== undefined) {
if (typeof node.next !== 'string' || !node.next.trim()) {
errors.push({
code: 'INVALID_NODE_REFERENCE',
message: `Reference 'next' in node '${nodeId}' must be a non-empty string`,
path: `${path}.next`,
nodeId
});
} else if (!nodeMap.has(node.next)) {
errors.push({
code: 'MISSING_NODE_REFERENCE',
message: `Node '${nodeId}' references non-existent node '${node.next}' in 'next'`,
path: `${path}.next`,
nodeId
});
}
}
if (Array.isArray(node.children)) {
for (let i = 0; i < node.children.length; i++) {
const childId = node.children[i];
if (typeof childId !== 'string' || !childId.trim()) {
errors.push({
code: 'INVALID_NODE_REFERENCE',
message: `Child reference at index ${i} in node '${nodeId}' must be a non-empty string`,
path: `${path}.children[${i}]`,
nodeId
});
} else if (!nodeMap.has(childId)) {
errors.push({
code: 'MISSING_NODE_REFERENCE',
message: `Sequence node '${nodeId}' references non-existent node '${childId}' in 'children'`,
path: `${path}.children[${i}]`,
nodeId
});
}
}
}
const singleRefProps = [
'onTrue',
'onFalse',
'onComplete',
'onExpire',
'onTick',
'onMiss',
'targetNode',
'success',
'failure'
];
for (const field of singleRefProps) {
if (node[field] !== undefined) {
if (typeof node[field] !== 'string' || !node[field].trim()) {
errors.push({
code: 'INVALID_NODE_REFERENCE',
message: `Reference '${field}' in node '${nodeId}' must be a non-empty string`,
path: `${path}.${field}`,
nodeId
});
} else if (!nodeMap.has(node[field])) {
errors.push({
code: 'MISSING_NODE_REFERENCE',
message: `Node '${nodeId}' references non-existent node '${node[field]}' in '${field}'`,
path: `${path}.${field}`,
nodeId
});
}
}
}
if (node.onHit !== undefined) {
if (typeof node.onHit === 'string') {
if (!node.onHit.trim()) {
errors.push({
code: 'INVALID_NODE_REFERENCE',
message: `Reference 'onHit' in node '${nodeId}' must be a non-empty string`,
path: `${path}.onHit`,
nodeId
});
} else if (!nodeMap.has(node.onHit)) {
errors.push({
code: 'MISSING_NODE_REFERENCE',
message: `Node '${nodeId}' references non-existent node '${node.onHit}' in 'onHit'`,
path: `${path}.onHit`,
nodeId
});
}
} else if (Array.isArray(node.onHit)) {
for (let i = 0; i < node.onHit.length; i++) {
const hitRef = node.onHit[i];
if (typeof hitRef !== 'string' || !hitRef.trim()) {
errors.push({
code: 'INVALID_NODE_REFERENCE',
message: `Reference 'onHit[${i}]' in node '${nodeId}' must be a non-empty string`,
path: `${path}.onHit[${i}]`,
nodeId
});
} else if (!nodeMap.has(hitRef)) {
errors.push({
code: 'MISSING_NODE_REFERENCE',
message: `Node '${nodeId}' references non-existent node '${hitRef}' in 'onHit'`,
path: `${path}.onHit[${i}]`,
nodeId
});
}
}
}
}
}
// 5. Reachability warnings from entryNodeId
if (abilityDef.entryNodeId && nodeMap.has(abilityDef.entryNodeId)) {
const reachable = new Set();
const markReachable = (id) => {
if (reachable.has(id) || !nodeMap.has(id)) return;
reachable.add(id);
const edges = getOutgoingEdges(nodeMap.get(id)?.node);
for (const edge of edges) {
markReachable(edge.targetId);
}
};
markReachable(abilityDef.entryNodeId);
for (const [id, { path }] of nodeMap.entries()) {
if (!reachable.has(id)) {
warnings.push({
message: `Node '${id}' is unreachable from entryNodeId '${abilityDef.entryNodeId}'`,
path,
nodeId: id
});
}
}
}
// 6. Directed cycle detection using 3-color DFS
const visited = new Set();
const visiting = new Map();
const currentPath = [];
const detectedCycles = new Set();
function dfs(currentId) {
visiting.set(currentId, currentPath.length);
currentPath.push(currentId);
const nodeInfo = nodeMap.get(currentId);
const outgoing = getOutgoingEdges(nodeInfo?.node);
for (const edge of outgoing) {
const nextId = edge.targetId;
if (!nodeMap.has(nextId)) continue;
if (visiting.has(nextId)) {
// Cycle found!
const cycleStartIdx = visiting.get(nextId);
const cycleNodes = currentPath.slice(cycleStartIdx).concat(nextId);
const cycleKey = cycleNodes.join(' -> ');
if (!detectedCycles.has(cycleKey)) {
detectedCycles.add(cycleKey);
errors.push({
code: 'CYCLE_DETECTED',
message: `Cycle detected in graph flow: ${cycleKey}`,
path: `${nodeInfo.path}.${edge.field}`,
nodeId: currentId,
cycle: cycleNodes,
nodePath: cycleNodes
});
}
} else if (!visited.has(nextId)) {
dfs(nextId);
}
}
visiting.delete(currentId);
currentPath.pop();
visited.add(currentId);
}
// Prioritize checking from entryNodeId
if (abilityDef.entryNodeId && nodeMap.has(abilityDef.entryNodeId)) {
dfs(abilityDef.entryNodeId);
}
// Check all remaining unvisited nodes for disconnected cycles
for (const id of nodeMap.keys()) {
if (!visited.has(id)) {
dfs(id);
}
}
return {
valid: errors.length === 0,
errors,
warnings
};
}
/**
* Asserts that an ability definition is valid, throwing AbilityValidationError on failure.
* @param {Object} abilityDef
* @returns {{ valid: true, errors: Array, warnings: Array }}
*/
static assertValid(abilityDef) {
const result = AbilityValidator.validate(abilityDef);
if (!result.valid) {
const summary = result.errors
.map(e => `[${e.code}] ${e.path ? `${e.path}: ` : ''}${e.message}`)
.join('\n ');
throw new AbilityValidationError(
`Ability '${abilityDef?.id || 'unknown'}' validation failed with ${result.errors.length} error(s):\n ${summary}`,
result
);
}
return result;
}
validate(abilityDef) {
return AbilityValidator.validate(abilityDef);
}
assertValid(abilityDef) {
return AbilityValidator.assertValid(abilityDef);
}
}
export default AbilityValidator;