fix: update based on PR comments

documentation/docs/governors/draws-governor.md

@@ -328,7 +328,7 @@ Fills as many qualifier drawPositions as possible with qualified participants, e
 engine.qualifierProgression({
   drawId,
   eventId,
-  mainStructureId,
+  targetRoundNumber, // optional - defaults to 1
   tournamentId,
 });
 ```

src/constants/errorConditionConstants.ts

@@ -192,6 +192,10 @@ export const MISSING_STRUCTURE = {
   message: 'Missing structure',
   code: 'ERR_MISSING_STRUCTURE',
 };
+export const MISSING_MAIN_STRUCTURE = {
+  message: 'Missing MAIN structure',
+  code: 'ERR_MISSING_MAIN_STRUCTURE',
+};
 export const UNLINKED_STRUCTURES = {
   message: 'drawDefinition contains unlinked structures',
   code: 'ERR_MISSING_STRUCTURE_LINKS',
@@ -929,6 +933,7 @@ export const errorConditionConstants = {
   MISSING_STAGE,
   MISSING_STRUCTURE_ID,
   MISSING_STRUCTURE,
+  MISSING_MAIN_STRUCTURE,
   MISSING_STRUCTURES,
   MISSING_TARGET_LINK,
   MISSING_TIE_FORMAT,

src/mutate/drawDefinitions/positionGovernor/qualifierProgression.ts

@@ -1,8 +1,9 @@
 import { findExtension } from '@Acquire/findExtension';
-import { findStructure } from '@Acquire/findStructure';
 import { qualifierDrawPositionAssignment } from '@Assemblies/governors/drawsGovernor';
-import { POSITION, QUALIFYING, WINNER } from '@Constants/drawDefinitionConstants';
+import { DRAW_DEFINITION, EVENT, TOURNAMENT_RECORD } from '@Constants/attributeConstants';
+import { MAIN, POSITION, QUALIFYING, WINNER } from '@Constants/drawDefinitionConstants';
 import {
+  MISSING_MAIN_STRUCTURE,
   MISSING_QUALIFIED_PARTICIPANTS,
   NO_DRAW_POSITIONS_AVAILABLE_FOR_QUALIFIERS,
 } from '@Constants/errorConditionConstants';
@@ -11,6 +12,7 @@ import { BYE } from '@Constants/matchUpStatusConstants';
 import { POLICY_TYPE_POSITION_ACTIONS } from '@Constants/policyConstants';
 import { SUCCESS } from '@Constants/resultConstants';
 import { decorateResult } from '@Functions/global/decorateResult';
+import { checkRequiredParameters } from '@Helpers/parameters/checkRequiredParameters';
 import { getPositionAssignments, structureAssignedDrawPositions } from '@Query/drawDefinition/positionsGetter';
 import { isCompletedStructure } from '@Query/drawDefinition/structureActions';
 import { getAppliedPolicies } from '@Query/extensions/getAppliedPolicies';
@@ -19,36 +21,55 @@ import { getSourceStructureIdsAndRelevantLinks } from '@Query/structure/getSourc
 import { randomPop } from '@Tools/arrays';
 import { definedAttributes } from '@Tools/definedAttributes';
 import { ResultType } from '@Types/factoryTypes';
-import { DrawDefinition, Event, Structure, Tournament } from '@Types/tournamentTypes';
+import { DrawDefinition, Event, Tournament } from '@Types/tournamentTypes';
 
 interface QualifierProgressionArgs {
   drawDefinition: DrawDefinition;
   event: Event;
-  mainStructureId: string;
+  targetRoundNumber?: number;
   tournamentRecord: Tournament;
 }
 
 export function qualifierProgression({
   drawDefinition,
   event,
-  mainStructureId,
+  targetRoundNumber = 1,
   tournamentRecord,
 }: QualifierProgressionArgs): ResultType {
+  const paramsCheck = checkRequiredParameters(
+    {
+      drawDefinition,
+      event,
+      tournamentRecord,
+    },
+    [{ [DRAW_DEFINITION]: true, [EVENT]: true, [TOURNAMENT_RECORD]: true }],
+  );
+  if (paramsCheck.error) return paramsCheck;
+
   const qualifyingParticipantIds: string[] = [];
+  const assignedParticipants: {
+    participantId: string;
+    drawPosition: number;
+  }[] = [];
+
+  const mainStructure = drawDefinition.structures?.find(
+    (structure) => structure.stage === MAIN && structure.stageSequence === 1,
+  );
+
+  if (!mainStructure) return decorateResult({ result: { error: MISSING_MAIN_STRUCTURE } });
 
-  const structure = findStructure({ drawDefinition, structureId: mainStructureId })?.structure ?? ({} as Structure);
   const appliedPolicies =
     getAppliedPolicies({
       tournamentRecord,
       drawDefinition,
-      structure,
+      structure: mainStructure,
       event,
     }).appliedPolicies ?? {};
 
   const policy = appliedPolicies[POLICY_TYPE_POSITION_ACTIONS];
   const requireCompletedStructures = policy?.requireCompletedStructures;
 
-  const { qualifierPositions, positionAssignments } = structureAssignedDrawPositions({ structure });
+  const { qualifierPositions, positionAssignments } = structureAssignedDrawPositions({ structure: mainStructure });
 
   if (!qualifierPositions.length)
     return decorateResult({ result: { error: NO_DRAW_POSITIONS_AVAILABLE_FOR_QUALIFIERS } });
@@ -57,16 +78,18 @@ export function qualifierProgression({
 
   const { relevantLinks: eliminationSourceLinks } =
     getSourceStructureIdsAndRelevantLinks({
+      targetRoundNumber,
       linkType: WINNER, // WINNER of qualifying structures will traverse link
       drawDefinition,
-      structureId: structure.structureId,
+      structureId: mainStructure.structureId,
     }) || {};
 
   const { relevantLinks: roundRobinSourceLinks } =
     getSourceStructureIdsAndRelevantLinks({
+      targetRoundNumber,
       linkType: POSITION, // link will define how many finishingPositions traverse the link
       drawDefinition,
-      structureId: structure.structureId,
+      structureId: mainStructure.structureId,
     }) || {};
 
   for (const sourceLink of eliminationSourceLinks) {
@@ -119,7 +142,7 @@ export function qualifierProgression({
       drawDefinition,
     });
 
-    if (!requireCompletedStructures || structureCompleted) {
+    if (structureCompleted) {
       const { positionAssignments } = getPositionAssignments({ structure });
       const relevantParticipantIds: any =
         positionAssignments
@@ -145,19 +168,25 @@ export function qualifierProgression({
 
   qualifierPositions.forEach((position) => {
     const randomParticipantId = randomPop(qualifyingParticipantIds);
-    randomParticipantId &&
-      qualifierDrawPositionAssignment({
+
+    if (randomParticipantId) {
+      const positionAssignmentResult: ResultType = qualifierDrawPositionAssignment({
         qualifyingParticipantId: randomParticipantId,
         tournamentRecord,
         drawDefinition,
         drawPosition: position.drawPosition,
-        structureId: structure.structureId,
+        structureId: mainStructure.structureId,
       });
+
+      positionAssignmentResult?.success &&
+        assignedParticipants.push({ participantId: randomParticipantId, drawPosition: position.drawPosition });
+    }
   });
 
   return decorateResult({
     result: definedAttributes({
       ...SUCCESS,
+      assignedParticipants,
     }),
   });
 }

src/query/structure/getSourceStructureIdsAndRelevantLinks.ts

@@ -5,7 +5,7 @@ import { findStructure } from '@Acquire/findStructure';
 type GetSourceStructureDetailArgs = {
   drawDefinition: DrawDefinition;
   finishingPosition?: string;
-  targetRoundNumber?: number;
+  targetRoundNumber: number;
   structureId: string;
   linkType: string;
 };

src/tests/mutations/drawDefinitions/structures/qualifying/qualifierProgression.test.ts

@@ -75,7 +75,7 @@ it('can assign all available qualified participants to the main structure qualif
   // assert no MAIN draw qualifying positions are available
   const noMainProgressionResult = tournamentEngine.qualifierProgression({
     drawId: qualifyingDrawDefinition.drawId,
-    mainStructureId: mainStructure.structureId,
+    targetRoundNumber: 1,
     tournamentId: tournamentRecord.tournamentId,
     eventId: eventId,
   });
@@ -108,7 +108,7 @@ it('can assign all available qualified participants to the main structure qualif
   // assert no qualified participants are available
   const noQualifiersProgressionResult = tournamentEngine.qualifierProgression({
     drawId: drawDefinition.drawId,
-    mainStructureId: populatedMainStructure.structureId,
+    targetRoundNumber: 1,
     tournamentId: tournamentRecord.tournamentId,
     eventId: eventId,
   });
@@ -127,11 +127,12 @@ it('can assign all available qualified participants to the main structure qualif
 
   const progressQualifiersResult = tournamentEngine.qualifierProgression({
     drawId: drawDefinition.drawId,
-    mainStructureId: populatedMainStructure.structureId,
+    targetRoundNumber: 1,
     tournamentId: tournamentRecord.tournamentId,
     eventId: eventId,
   });
 
+  expect(progressQualifiersResult.assignedParticipants.length).toEqual(4);
   expect(progressQualifiersResult.success).toEqual(true);
 
   // assert qualified participants have been assigned to the main draw positions