docs(mfa): simplify and deduplicate the graph-traversal comments

Trim the long debugging guides to their essentials, tell each repeated
story (payload context split, hand-written journey endpoints, navigation
mock) in one place only, and reword the dense graph jargon in plain
language. Move misplaced notes next to the code they describe, promote
comments that document exported declarations to JSDoc, and fix the
comment that wrongly called the shared Navigation mock an implementation.

Author: dariusz-biela

tests/unit/components/MultifactorAuthentication/machine/graphTraversal/coverageStaysComplete.test.ts

@@ -7,11 +7,10 @@ import mfaMachine from '@components/MultifactorAuthentication/machine/mfaMachine
 // The suites in this file guard the generated coverage itself: they analyze the walked paths that
 // `viewMatchesMachine.test.tsx` drives through the real UI, without rendering anything themselves. A
 // failure here usually means the walk stopped covering a state or transition, not that the modal broke.
-// Each failure names the missing piece.
 
 const walkedPaths = getWalkedPaths();
 
-// Every settleable leaf must end a path that the UI walk drives, not merely appear mid-path.
+// Every settleable leaf must end a path that the UI walk drives, not only appear in the middle of one.
 describe('every settleable MFA state is reachable through the real UI', () => {
     const walkedLeafValues = walkedPaths.map((path) => path.state.value);
 
@@ -20,12 +19,10 @@ describe('every settleable MFA state is reachable through the real UI', () => {
     });
 });
 
-// Shortest paths keep a single incoming route per distinct state-and-context vertex, so a transition can
-// silently drop out of the walk once another route to its target is shorter. A failure here has two
-// possible causes. When a transition was added to the machine, the fix is an explicit journey in
-// `DRIVING_JOURNEYS` that drives it. When the machine stopped resetting part of its context, the same
-// state value splits into a second vertex whose transitions have no route, so compare the failing
-// vertex's context with the intended one and fix the machine instead of adding a journey.
+// Shortest paths keep only one route into each distinct state and context, so a transition can
+// silently drop out of the walk when another route to its target is shorter. If this fails after
+// adding a transition, add a journey to `DRIVING_JOURNEYS` that drives it. If the failing entry has an
+// unexpected context, fix the machine so it resets that context again instead of adding a journey.
 describe('every UI-drivable state-changing transition is exercised', () => {
     const exercisedTransitionKeys = getExercisedTransitionKeys(walkedPaths);
 
@@ -34,9 +31,9 @@ describe('every UI-drivable state-changing transition is exercised', () => {
     });
 });
 
-// The payload INIT fixture exists to give the payload flow its own context vertices. When the machine
-// stops copying the payload into its context, every INIT fixture lands in the same vertex, the split
-// disappears, and the explicit journeys keep the walk green. This guard pins the split itself.
+// The payload INIT fixture exists so that the flow with a payload gets its own entries in the graph.
+// When the machine stops copying the payload into its context, the graph no longer tells the two
+// flows apart and the other suites still pass. Only this suite fails in that case.
 describe('INIT fixtures produce distinct context vertices', () => {
     it('keeps at least one landing vertex per distinct INIT fixture', () => {
         const landings = getInitEdgeLandings();

tests/unit/components/MultifactorAuthentication/machine/graphTraversal/everyStateReachable.test.ts

@@ -3,15 +3,13 @@ import getSettleableLeafStates from 'tests/utils/mfa/settleableLeafStates';
 import {matchesState} from 'xstate';
 import mfaMachine from '@components/MultifactorAuthentication/machine/mfaMachine';
 
-// Both suites in this file are generated by traversing the mfaMachine graph automatically instead of
-// enumerating cases by hand, and both analyze the chart alone; nothing renders. `getShortestPaths`
-// derives the coverage from the chart, so a state added to the machine gains a spec here without edits.
-// `settleableLeafStates.ts` defines which states count as settleable. The sibling suites under
-// `graphTraversal/` walk the same generated paths through the real modal UI and guard that coverage.
+// Both suites in this file are generated by traversing the mfaMachine graph, so a state added to the
+// machine gets a test here automatically. Nothing renders in this file. `settleableLeafStates.ts`
+// defines which states count as settleable.
 
 // Reachability is asserted on the unfiltered shortest paths, so it also covers routes the UI walk in
 // `viewMatchesMachine.test.tsx` cannot drive (a delayed transition, for example). A failure here means
-// the chart itself lost the state, not that the view harness broke.
+// the machine itself lost the state, not that the UI harness broke.
 describe('every settleable MFA state is reachable in the machine chart', () => {
     const reachableSnapshots = getMfaShortestPaths().map((path) => path.state);
 
@@ -20,9 +18,9 @@ describe('every settleable MFA state is reachable in the machine chart', () => {
     });
 });
 
-// Every generated expectation in these suites follows the machine under test, so a retargeted transition
-// that keeps every state reachable regenerates matching expectations and passes. Each journey's pinned
-// endpoint is hand-written in `DRIVING_JOURNEYS`, so it fails in that case instead.
+// The journey endpoints are the only hand-written expectations, so a transition that points at the
+// wrong target can only surface here, and only when a journey drives it. The `DRIVING_JOURNEYS` doc
+// explains why.
 describe('every driving journey ends in its pinned state', () => {
     it.each(getDrivingJourneyPaths())('$description', ({paths, endState}) => {
         expect(paths.length).toBeGreaterThan(0);

tests/unit/components/MultifactorAuthentication/machine/graphTraversal/viewMatchesMachine.test.tsx

@@ -13,11 +13,12 @@ import {handleInitialScreenLayout, mfaNavigationRef} from '@components/Multifact
 import CONST from '@src/CONST';
 import SCREENS from '@src/SCREENS';
 
-// This file pins the contract between the machine and the rendered modal: it mounts the production
-// providers and navigator, drives each machine event as a real gesture, and asserts the UI markers of
-// the reached state at every step of every generated path. The paths come from `getWalkedPaths`, so a
-// state or event added to the machine gains steps here without edits. The chart-only suites live in
-// `everyStateReachable.test.ts`, and the guards on the generated coverage in `coverageStaysComplete.test.ts`.
+// This file tests that the rendered modal matches the machine: it mounts the production providers and
+// navigator, drives each machine event as a real gesture, and asserts the UI markers of the reached
+// state at every step of every generated path. A state or event added to the machine appears in the
+// walked paths automatically, and the type checks and guard suites then demand the hand-written
+// pieces it needs, such as an executor, a payload fixture, or a UI assertion. The machine-only suites
+// live in `everyStateReachable.test.ts` and the coverage guards in `coverageStaysComplete.test.ts`.
 
 // This mock forces a wide layout so the navigator renders the backdrop used as the mounted marker.
 jest.mock('@hooks/useResponsiveLayout');
@@ -29,13 +30,11 @@ jest.mock('@libs/XStateInspector', () => ({__esModule: true, default: {inspect:
 jest.mock('@components/MultifactorAuthentication/biometrics/useBiometrics', () => jest.requireActual<typeof MfaRealUiMocks>('tests/utils/mfa/realUi/mocks').biometricsHookMock());
 // Browser and Android history synchronization is outside the contract between the machine and UI.
 jest.mock('@components/MultifactorAuthentication/useSyncMfaModalNavigatorWithHistory', () => jest.requireActual<typeof MfaRealUiMocks>('tests/utils/mfa/realUi/mocks').syncHistoryMock());
-// This mock reuses the shared Navigation implementation and overrides the transition methods used by the MFA flow.
+// jsdom runs no real navigation transitions, so the mock controls when the transition callbacks fire.
 jest.mock('@libs/Navigation/Navigation', () => jest.requireActual<typeof MfaRealUiMocks>('tests/utils/mfa/realUi/mocks').navigationMock());
 
-// These UI markers distinguish the closed, closing, and outcome states. `OutcomeScreenBase` identifies the
-// outcome screen, while the backdrop exists only when the MFA navigator is mounted. Every outcome screen
-// renders the same `OutcomeScreenBase`, so the success assertion also checks the route name to pin which
-// outcome screen is on top.
+// These UI markers distinguish the closed, closing, and outcome states. The backdrop exists only while
+// the MFA navigator is mounted.
 const OUTCOME_SCREEN_TEST_ID = 'OutcomeScreenBase';
 const MODAL_BACKDROP_TEST_ID = 'MultifactorAuthenticationModalBackdrop';
 
@@ -45,14 +44,17 @@ const CONFIRM_BUTTON_TEST_ID = 'MultifactorAuthenticationOutcomeConfirmButton';
 const MFA_STATE = CONST.MULTIFACTOR_AUTHENTICATION.MFA_STATE;
 
 type MfaEventType = MfaEvent['type'];
-// The event carries only its `type` here because `xstate/graph` erases the payload from the executor's
-// step type. The INIT executor recovers the payload through `isTestScenarioInitEvent`.
+
+/**
+ * The event carries only its `type` here because `xstate/graph` erases the payload from the executor's
+ * step type. The INIT executor recovers the payload through `isTestScenarioInitEvent`.
+ */
 type MfaEventExecutor = (step: {event: {type: MfaEventType}}) => Promise<void>;
 
 /**
- * `INIT` enters through the public API with the scenario and payload of the step's own event, so paths
- * built from different INIT fixtures drive different flows. `MODAL_CLOSED` runs the navigator's teardown
- * callback. `satisfies Record<MfaEventType, ...>` requires an explicit executor for every machine event.
+ * `INIT` starts a flow through the public API, using the scenario and payload from the step's own
+ * event. `MODAL_CLOSED` runs the navigator's teardown callback. `satisfies Record<MfaEventType, ...>`
+ * requires an explicit executor for every machine event.
  */
 /* eslint-disable @typescript-eslint/naming-convention -- keys mirror the machine's event type union. */
 const mfaEventExecutors = {
@@ -91,6 +93,7 @@ const testConfig = {
         [`${MFA_STATE.OPEN}.${MFA_STATE.OUTCOME}.${MFA_STATE.SUCCESS}`]: () => {
             expect(screen.queryAllByTestId(MODAL_BACKDROP_TEST_ID)).not.toHaveLength(0);
             expect(screen.queryAllByTestId(OUTCOME_SCREEN_TEST_ID)).not.toHaveLength(0);
+            // Every outcome screen renders the same `OutcomeScreenBase`, so the route name identifies which one is on top.
             expect(mfaNavigationRef.getCurrentRoute()?.name).toBe(SCREENS.MULTIFACTOR_AUTHENTICATION.OUTCOME_SUCCESS);
         },
         [MFA_STATE.CLOSING]: () => {
@@ -102,10 +105,13 @@ const testConfig = {
 
 const walkedPaths = getWalkedPaths();
 
-// `path.description` serializes the complete event payload, so test names use the short labels from
-// `describeTraversalEvent` instead. The synthetic `xstate.init` event is excluded because it is not part
-// of `MfaEvent`.
 const INIT_STEP_EVENT_TYPE = 'xstate.init';
+
+/**
+ * Builds the event part of a test name. `path.description` would serialize the complete event payload,
+ * so the name uses the short labels from `describeTraversalEvent` instead. The synthetic `xstate.init`
+ * event is excluded because it is not part of `MfaEvent`.
+ */
 function describeDrivenEvents(steps: ReadonlyArray<{event: {type: string}}>): string {
     const drivenEventLabels = steps
         .map((step) => step.event)
@@ -115,9 +121,9 @@ function describeDrivenEvents(steps: ReadonlyArray<{event: {type: string}}>): st
 }
 
 describe('the real MFA modal matches the machine at every step of every generated path', () => {
-    // The navigation buffer is deliberately not reset here. The machine owns that cleanup on `closed`
-    // entry, which also runs when each test's fresh actor starts, so a reset here would hide a machine
-    // that stopped performing it.
+    // The navigation buffer is deliberately not reset here. The machine resets it when it enters
+    // `closed`, which also runs when each test's fresh actor starts, so a reset here would hide a
+    // machine that stopped doing that cleanup.
     beforeEach(() => {
         resetMfaUiMocks();
     });
@@ -138,10 +144,9 @@ describe('the real MFA modal matches the machine at every step of every generate
 // TestModel runs only the state assertions whose keys match the reached state, so if no key matches a
 // state, the test passes without checking it. These guards fail in that case.
 //
-// Types cannot do this. TypeScript's inferred type does not record whether a state has an `always`
-// transition, so it cannot tell a real leaf from a pass-through state such as `{open: "preparing"}`. A
-// `Record<leaf, ...>` would then need an empty assertion for every pass-through state, and that empty
-// entry would make the check pass on its own once the state later loses its `always` and becomes settleable.
+// A type cannot enforce this, because TypeScript does not know which states auto-advance. A
+// `Record` over all leaf states would then need empty assertions for the pass-through states, and an
+// empty assertion keeps passing silently.
 describe('testConfig defines a UI assertion for every settleable state and for nothing else', () => {
     const settleableLeafStates = getSettleableLeafStates(mfaMachine.root);
     const configuredStateKeys = Object.keys(testConfig.states);

tests/utils/mfa/flowFixtures.ts

@@ -8,13 +8,16 @@ const MFA_TEST_SCENARIO_NAME = CONST.MULTIFACTOR_AUTHENTICATION.SCENARIO.BIOMETR
 type MfaTestScenarioParams = MultifactorAuthenticationScenarioParams<typeof MFA_TEST_SCENARIO_NAME>;
 
 /**
- * A non-empty payload for the test scenario. The traversal pairs it with the bare fixture so flows with
- * and without a payload occupy distinct context vertices in the graph.
+ * A non-empty payload for the test scenario. The traversal pairs it with the bare fixture so the flow
+ * with a payload is covered separately from the flow without one.
  */
 const MFA_TEST_PAYLOAD: MfaTestScenarioParams = {validateCode: '123456'};
 
-// The narrowed generic ties `scenarioName`, `scenario`, and `payload` to the same scenario, so pairing
-// the name with another scenario's config here is a compile error.
+/**
+ * Builds the INIT event fixture for the test scenario. The narrowed generic ties `scenarioName`,
+ * `scenario`, and `payload` to the same scenario, so pairing the name with another scenario's config
+ * here is a compile error.
+ */
 function createInitEvent(payload?: MfaTestScenarioParams): MultifactorAuthenticationInitEvent<typeof MFA_TEST_SCENARIO_NAME> {
     return {
         type: 'INIT',
@@ -26,18 +29,17 @@ function createInitEvent(payload?: MfaTestScenarioParams): MultifactorAuthentica
 
 /**
  * Narrows a traversal event to the test-scenario INIT fixture shape. The scenario-name check is enough,
- * because {@link createInitEvent} is the only source of INIT events in the traversal and it correlates
- * the payload with the scenario name by construction. The parameter accepts any typed event, because
- * `xstate/graph` erases everything but `type` from the event an executor receives.
+ * because {@link createInitEvent} is the only place that builds INIT events for the traversal. The
+ * parameter accepts any typed event, because `xstate/graph` erases everything but `type` from the
+ * event an executor receives.
  */
 function isTestScenarioInitEvent(event: {type: string}): event is MultifactorAuthenticationInitEvent<typeof MFA_TEST_SCENARIO_NAME> {
     return event.type === 'INIT' && 'scenarioName' in event && event.scenarioName === MFA_TEST_SCENARIO_NAME;
 }
 
 /**
- * Names a traversal event in path titles and transition descriptions. The INIT fixtures differ only in
- * their payload, which the titles otherwise erase, so a failure would not tell which fixture broke. The
- * label lists the payload keys instead of the serialized payload to stay short and stable.
+ * Returns a short label for a traversal event. The INIT fixtures differ only in their payload, so the
+ * label lists the payload keys to tell them apart without serializing the whole payload.
  */
 function describeTraversalEvent(event: {type: string}): string {
     if (!isTestScenarioInitEvent(event)) {