feat(migrate): check every user against the instance before writing

.changeset/migrate-slice-1c.md

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

packages/cli-core/src/commands/migrate/lib/analysis.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+import { analyzeFields, hasValue } from "./analysis.ts";
+
+describe("hasValue", () => {
+  test.each([
+    ["a string", "x", true],
+    ["zero", 0, true],
+    ["false", false, true],
+    ["a populated array", ["a"], true],
+    ["an object", {}, true],
+    ["an empty string", "", false],
+    ["an empty array", [], false],
+    ["null", null, false],
+    ["undefined", undefined, false],
+  ])("treats %s as present: %p", (_label, value, expected) => {
+    expect(hasValue(value)).toBe(expected);
+  });
+});
+
+describe("analyzeFields", () => {
+  test("returns zeroed counts for an empty file", () => {
+    const result = analyzeFields([]);
+    expect(result.totalUsers).toBe(0);
+    expect(result.identifiers.hasAnyIdentifier).toBe(0);
+    expect(result.fieldCounts).toEqual({});
+  });
+
+  test("counts each identifier kind separately", () => {
+    const result = analyzeFields([
+      { userId: "1", email: "a@x.dev" },
+      { userId: "2", unverifiedEmailAddresses: ["b@x.dev"] },
+      { userId: "3", phone: "+15555550100" },
+      { userId: "4", unverifiedPhoneNumbers: ["+15555550101"] },
+      { userId: "5", username: "carol" },
+    ]);
+
+    expect(result.identifiers).toMatchObject({
+      verifiedEmails: 1,
+      unverifiedEmails: 1,
+      verifiedPhones: 1,
+      unverifiedPhones: 1,
+      username: 1,
+      hasAnyIdentifier: 5,
+    });
+  });
+
+  test("counts emailAddresses towards verified emails", () => {
+    const result = analyzeFields([{ userId: "1", emailAddresses: ["a@x.dev"] }]);
+    expect(result.identifiers.verifiedEmails).toBe(1);
+  });
+
+  test("counts a user with several identifiers once", () => {
+    const result = analyzeFields([
+      { userId: "1", email: "a@x.dev", phone: "+15555550100", username: "ada" },
+    ]);
+    expect(result.identifiers.hasAnyIdentifier).toBe(1);
+    expect(result.identifiers.verifiedEmails).toBe(1);
+    expect(result.identifiers.verifiedPhones).toBe(1);
+  });
+
+  // These users cannot be imported under any instance configuration, which is
+  // what makes the count worth surfacing separately.
+  test("counts users carrying no identifier at all", () => {
+    const result = analyzeFields([
+      { userId: "1", email: "a@x.dev" },
+      { userId: "2", firstName: "Nobody" },
+      { userId: "3" },
+    ]);
+    expect(result.totalUsers).toBe(3);
+    expect(result.identifiers.hasAnyIdentifier).toBe(1);
+  });
+
+  test("counts the analyzed non-identifier fields", () => {
+    const result = analyzeFields([
+      { userId: "1", email: "a@x.dev", firstName: "Ada", password: "d", totpSecret: "s" },
+      { userId: "2", email: "b@x.dev", firstName: "Grace" },
+      { userId: "3", email: "c@x.dev", lastName: "Hopper" },
+    ]);
+    expect(result.fieldCounts).toEqual({
+      firstName: 2,
+      lastName: 1,
+      password: 1,
+      totpSecret: 1,
+    });
+  });
+
+  test("omits fields no user carries, rather than reporting them as zero", () => {
+    const result = analyzeFields([{ userId: "1", email: "a@x.dev" }]);
+    expect("password" in result.fieldCounts).toBe(false);
+  });
+
+  test("does not count an empty value as present", () => {
+    const result = analyzeFields([{ userId: "1", email: "a@x.dev", firstName: "", lastName: [] }]);
+    expect(result.fieldCounts.firstName).toBeUndefined();
+    expect(result.fieldCounts.lastName).toBeUndefined();
+  });
+});

packages/cli-core/src/commands/migrate/lib/analysis.ts

@@ -0,0 +1,88 @@
+/**
+ * Counts what an import file actually contains, per field.
+ *
+ * Ported from the standalone migration-tool's `src/lib/analysis.ts`. Runs on
+ * transformed-but-unvalidated users so the report describes the whole file,
+ * including the rows that will be skipped.
+ */
+
+import type { User } from "../types.ts";
+
+/** Non-identifier fields the readiness rows report coverage for. */
+export const ANALYZED_FIELDS = [
+  { key: "firstName", label: "First name" },
+  { key: "lastName", label: "Last name" },
+  { key: "password", label: "Password" },
+  { key: "totpSecret", label: "TOTP secret" },
+] as const;
+
+export type IdentifierCounts = {
+  verifiedEmails: number;
+  unverifiedEmails: number;
+  verifiedPhones: number;
+  unverifiedPhones: number;
+  username: number;
+  /** Users with any email, verified or not: each user counted once. */
+  anyEmail: number;
+  /** Users with any phone, verified or not: each user counted once. */
+  anyPhone: number;
+  /** Users with at least one identifier — the rest cannot be imported at all. */
+  hasAnyIdentifier: number;
+};
+
+export type FieldAnalysis = {
+  identifiers: IdentifierCounts;
+  totalUsers: number;
+  fieldCounts: Record<string, number>;
+};
+
+/** True for anything with real content — `0` and `false` count, `""` and `[]` do not. */
+export function hasValue(value: unknown): boolean {
+  if (value === undefined || value === null || value === "") return false;
+  if (Array.isArray(value)) return value.length > 0;
+  return true;
+}
+
+export function analyzeFields(users: (User | Record<string, unknown>)[]): FieldAnalysis {
+  const identifiers: IdentifierCounts = {
+    verifiedEmails: 0,
+    unverifiedEmails: 0,
+    verifiedPhones: 0,
+    unverifiedPhones: 0,
+    username: 0,
+    anyEmail: 0,
+    anyPhone: 0,
+    hasAnyIdentifier: 0,
+  };
+  const fieldCounts: Record<string, number> = {};
+
+  for (const entry of users) {
+    const user = entry as Record<string, unknown>;
+
+    for (const field of ANALYZED_FIELDS) {
+      if (hasValue(user[field.key])) {
+        fieldCounts[field.key] = (fieldCounts[field.key] ?? 0) + 1;
+      }
+    }
+
+    const verifiedEmail = hasValue(user.email) || hasValue(user.emailAddresses);
+    const unverifiedEmail = hasValue(user.unverifiedEmailAddresses);
+    const verifiedPhone = hasValue(user.phone) || hasValue(user.phoneNumbers);
+    const unverifiedPhone = hasValue(user.unverifiedPhoneNumbers);
+    const username = hasValue(user.username);
+
+    if (verifiedEmail) identifiers.verifiedEmails++;
+    if (unverifiedEmail) identifiers.unverifiedEmails++;
+    if (verifiedPhone) identifiers.verifiedPhones++;
+    if (unverifiedPhone) identifiers.unverifiedPhones++;
+    if (username) identifiers.username++;
+    if (verifiedEmail || unverifiedEmail) identifiers.anyEmail++;
+    if (verifiedPhone || unverifiedPhone) identifiers.anyPhone++;
+
+    if (verifiedEmail || unverifiedEmail || verifiedPhone || unverifiedPhone || username) {
+      identifiers.hasAnyIdentifier++;
+    }
+  }
+
+  return { identifiers, totalUsers: users.length, fieldCounts };
+}