refactor(mosaic): tighten types to catch misuse at compile time (#10572)

Author: alexcarpenter

.changeset/mosaic-machine-state-names.md

@@ -0,0 +1,2 @@
+---
+---

packages/mosaic/docs/controllers.md

@@ -313,6 +313,8 @@ every successful removal drops focus on the floor.
 - **No machine snapshot in the return value.** Return the plain props the view
   reads (`open`, `pendingKey`, `isDeleting`, `errorMessage`), never `snapshot`
   and `send`.
+- A transition shared across states in a `const` needs `target: 'name' as const`.
+  Without it the target widens to `string` and the machine rejects it.
 - Dismissing must not abandon an in-flight effect. Model `open` as context, and
   give `OPEN`/`CLOSE` no target in the busy state so they don't leave it:
 

packages/mosaic/eslint/config.mjs

@@ -4,7 +4,7 @@ import vitest from '@vitest/eslint-plugin';
 import boundaries from 'eslint-plugin-boundaries';
 import noUnneededEffects from 'eslint-plugin-react-you-might-not-need-an-effect';
 
-import { forwardRefParts, noDynamicMessageCatalogs, noModelReactState } from './rules.mjs';
+import { forwardRefParts, noDynamicMessageCatalogs, noModelReactState, noRawInvoke } from './rules.mjs';
 
 const mosaicRoot = path.resolve(import.meta.dirname, '..');
 
@@ -30,6 +30,7 @@ export default [
           'no-model-react-state': noModelReactState,
           'no-dynamic-message-catalogs': noDynamicMessageCatalogs,
           'forward-ref-parts': forwardRefParts,
+          'no-raw-invoke': noRawInvoke,
         },
       },
     },
@@ -63,6 +64,14 @@ export default [
       'mosaic/forward-ref-parts': 'error',
     },
   },
+  {
+    name: 'packages/mosaic - machines',
+    files: ['src/**/*.{ts,tsx}'],
+    ignores: ['src/**/__tests__/**', 'src/**/*.test.{ts,tsx}', 'src/**/*.test-d.{ts,tsx}'],
+    rules: {
+      'mosaic/no-raw-invoke': 'error',
+    },
+  },
   {
     name: 'packages/mosaic - effects',
     files: ['src/features/**/*.{ts,tsx}'],

packages/mosaic/eslint/import-guards.test.mjs

@@ -349,6 +349,47 @@ describe('Mosaic layers', { timeout: 30_000 }, () => {
   });
 });
 
+describe('Mosaic machines', { timeout: 30_000 }, () => {
+  async function rawInvokeMessages(file, source) {
+    const messages = await lintAt(file, source);
+    expect(messages.find(message => message.fatal)).toBeUndefined();
+    return messages.filter(message => message.ruleId === 'mosaic/no-raw-invoke').map(message => message.message);
+  }
+
+  test('rejects an invoke written without fromPromise', async () => {
+    expect(
+      await rawInvokeMessages(
+        `${featureDir}/sample.controller.ts`,
+        'export const state = { invoke: { src: () => Promise.resolve(1), onDone: { target: "idle" } } };',
+      ),
+    ).toEqual(['Write invoke with fromPromise from setup(), so onDone sees the typed output instead of any.']);
+  });
+
+  test.each([
+    ['a quoted src key', 'export const state = { invoke: { "src": () => Promise.resolve(1) } };'],
+    ['a quoted invoke key', 'export const state = { "invoke": { src: () => Promise.resolve(1) } };'],
+    ['an as cast', 'export const state = { invoke: { src: () => Promise.resolve(1) } as object };'],
+    ['satisfies', 'export const state = { invoke: { src: () => Promise.resolve(1) } satisfies object };'],
+  ])('rejects a raw invoke written with %s', async (_name, source) => {
+    expect(await rawInvokeMessages(`${featureDir}/sample.controller.ts`, source)).toHaveLength(1);
+  });
+
+  test('allows an invoke from fromPromise', async () => {
+    expect(
+      await rawInvokeMessages(
+        `${featureDir}/sample.controller.ts`,
+        'declare const fromPromise: (run: () => Promise<number>) => object;\nexport const state = { invoke: fromPromise(() => Promise.resolve(1)) };',
+      ),
+    ).toEqual([]);
+  });
+
+  test('ignores test files', async () => {
+    expect(
+      await rawInvokeMessages(testFixture, 'export const state = { invoke: { src: () => Promise.resolve(1) } };'),
+    ).toEqual([]);
+  });
+});
+
 describe('Mosaic parts', { timeout: 30_000 }, () => {
   async function forwardRefMessages(file, source) {
     const messages = await lintAt(
@@ -499,6 +540,7 @@ describe('Mosaic package configuration', { timeout: 30_000 }, () => {
       'mosaic/no-model-react-state',
       'mosaic/no-dynamic-message-catalogs',
       'mosaic/forward-ref-parts',
+      'mosaic/no-raw-invoke',
       '@typescript-eslint/no-import-type-side-effects',
       ...Object.keys(noUnneededEffects.configs.strict.rules),
     ]) {

packages/mosaic/eslint/rules.mjs

@@ -268,3 +268,31 @@ export const forwardRefParts = {
     };
   },
 };
+
+export const noRawInvoke = {
+  meta: {
+    type: 'problem',
+    schema: [],
+    messages: {
+      useFromPromise: 'Write invoke with fromPromise from setup(), so onDone sees the typed output instead of any.',
+    },
+  },
+  create(context) {
+    return {
+      Property(node) {
+        if (propertyName(node.key, node.computed) !== 'invoke') {
+          return;
+        }
+        const invoke = unwrapExpression(node.value);
+        if (
+          invoke.type === 'ObjectExpression' &&
+          invoke.properties.some(
+            property => property.type === 'Property' && propertyName(property.key, property.computed) === 'src',
+          )
+        ) {
+          context.report({ node: invoke, messageId: 'useFromPromise' });
+        }
+      },
+    };
+  },
+};

packages/mosaic/src/components/action-bar/action-bar.tsx

@@ -263,8 +263,8 @@ const Action = React.forwardRef<HTMLButtonElement, ActionBarActionProps>(functio
           <Button
             variant='ghost'
             size='md'
-            color={color}
             {...merged}
+            color={color}
             // eslint-disable-next-line react-hooks/rules-of-hooks -- floating-ui's CompositeItem calls this render callback synchronously during its own render, so the hook keeps a stable position.
             ref={useMergeRefs<unknown>([ref, isRef(itemRef) ? itemRef : undefined])}
             xstyle={[color === 'negative' && styles.destructive, xstyle]}

packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-profile-section.model.ts

@@ -4,6 +4,8 @@ import type { OrganizationResource } from '@clerk/shared/types';
 import { useMosaicEnvironment } from '../../../hooks/use-mosaic-environment';
 import { save, SaveError, UNEXPECTED_ERROR } from '../../../utils/errors';
 import { ORGANIZATION_PERMISSIONS } from '../../../utils/permissions';
+import type { OrganizationProfileEditNameValue } from './organization-profile-edit-name.dialog';
+import type { OrganizationProfileEditSlugValue } from './organization-profile-edit-slug.dialog';
 import type { OrganizationProfileProfileSectionViewProps } from './organization-profile-profile-section.view';
 
 type OrganizationProfileProfileSectionModel =
@@ -52,10 +54,11 @@ export function useOrganizationProfileProfileSectionModel(): OrganizationProfile
     ...profile,
     onLogoChange: file => save(() => currentOrganization().setLogo({ file })),
     onRemoveLogo: organization.hasImage ? () => save(() => currentOrganization().setLogo({ file: null })) : undefined,
-    onSubmitName: name => save(() => currentOrganization().update({ name }), ['name']),
+    onSubmitName: name =>
+      save<keyof OrganizationProfileEditNameValue>(() => currentOrganization().update({ name }), ['name']),
     onSubmitSlug: !environment.organizationSettings.slug.disabled
       ? slug =>
-          save(() => {
+          save<keyof OrganizationProfileEditSlugValue>(() => {
             const current = currentOrganization();
             return current.update({ name: current.name, slug });
           }, ['slug'])

packages/mosaic/src/features/reverification/reverification.controller.ts

@@ -176,20 +176,20 @@ const factorEvents = {
   },
   SELECT_METHOD: [
     {
-      target: 'methodPickerPreparing',
+      target: 'methodPickerPreparing' as const,
       guard: (ctx, event) => {
         const method = ctx.methods.find(candidate => candidate.id === event.id);
         return topOverlay(ctx) === 'method-picker' && Boolean(method && needsPrepare(method));
       },
       actions: assign((ctx, event) => selectMethod(ctx, event.id)),
     },
     {
-      target: 'verifying',
+      target: 'verifying' as const,
       guard: ctx => topOverlay(ctx) === 'method-picker',
       actions: assign((ctx, event) => ({ ...selectMethod(ctx, event.id), overlay: [] })),
     },
   ],
-  RESET: 'inactive',
+  RESET: 'inactive' as const,
 } satisfies NonNullable<StateConfig<ReverificationContext, ReverificationEvent>['on']>;
 
 export const reverificationMachine = createMachine({

packages/mosaic/src/features/user-profile/user-profile-email-section/user-profile-add-email.controller.ts

@@ -64,12 +64,12 @@ const LINK_RESEND_SECONDS = 60;
 const tick = { actions: assign(context => ({ resendSeconds: Math.max(0, context.resendSeconds - 1) })) };
 const fail = assign<ErrorInvokeEvent>((_, event) => ({ error: toFormError(event.error) }));
 const resend = {
-  target: 'starting',
+  target: 'starting' as const,
   guard: (context: Context) => context.resendSeconds === 0,
   actions: assign(() => ({ error: undefined })),
 };
 const start = {
-  target: 'starting',
+  target: 'starting' as const,
   actions: assign<Extract<Event, { type: 'START' }>>((_, event) => ({
     verifyingId: event.id,
     emailAddress: event.emailAddress,

packages/mosaic/src/features/user-profile/user-profile-passkeys-section/user-profile-passkeys-section.model.ts

@@ -173,7 +173,7 @@ export function useUserProfilePasskeysModel(): UserProfilePasskeysModel {
       if (feedback) {
         throw new FormSubmitError<UserProfileRenamePasskeyValues>({ fields: { name: feedback.message } });
       }
-      await save(() => passkey.update({ name }), ['name']);
+      await save<keyof UserProfileRenamePasskeyValues>(() => passkey.update({ name }), ['name']);
     },
     onRemove: async id => {
       const passkey = currentUser().passkeys.find(candidate => candidate.id === id);