Merge pull request #78 from focusreactive/refactor/translator-schemamap-fieldlike

refactor(translator): typed FieldLike projection for schemaMap (replaces JSON round-trip)

Author: SearheiParkhamchuk

packages/payload-plugin-translator/docs/plans/2026-07-15-schemamap-fieldlike-projection.md

@@ -1,9 +1,9 @@
 # Task — Replace the `schemaMap` JSON round-trip with a typed `FieldLike` projection
 
-**Date:** 2026-07-15
-**Status:** backlog (internal). Deferred out of the `TranslateCollectionPlugin` reshape
-(`2026-07-14-translate-collection-plugin-reshape.md`) as a separate, test-backed task.
-**Scope:** internal only — no public API change.
+**Date:** 2026-07-15 · **implemented:** 2026-07-17 (after the core/ layering redesign).
+**Status:** implemented. Preceded by a read-only code investigation that de-risked the property
+contract, the Payload-sanitize premise, and placement (findings folded in below).
+**Scope:** internal only — no public API change. Ships as `refactor:` (patch).
 
 ## Problem
 
@@ -41,9 +41,32 @@ properties the pipeline uses (`name`, `type`, `localized`, `fields`, `blocks`, `
 every nesting level, and build `schemaMap` from it instead of the JSON round-trip. This makes the
 schema contract explicit and typed.
 
-`FieldLike` already exists in `core/field-traversal` (see `fieldLike.types.test.ts`) and the pipeline
+`FieldLike` already exists in `core/kernel/field-traversal` (post-refactor location) and the pipeline
 already operates on it — the gap is only the `schemaMap` construction in `plugin.ts`.
 
+## Findings from the pre-implementation investigation (evidence-based)
+
+- **Contract is complete but `blocks`/`tabs` are not scalars.** Every `schemaMap` consumer (pipeline,
+  provenance fingerprint, auto-translate drift gate, field-path resolver) reads only
+  `type` · `name` · `localized` · `custom` (just `custom.translateKit.exclude`) · `fields` · `blocks` ·
+  `tabs`. Nothing else is read (`editor`/`admin`/`relationTo`/`validate` — none; `relationTo` appears only
+  in dead code). BUT the projector must recurse into sub-shapes: **`block.slug` is load-bearing**
+  (block-type dispatch) and `tab.name`/`tab.fields` (+`tab.localized`) are required — copying `blocks`/`tabs`
+  opaquely would silently break translation. This corrected the doc's original flat property list.
+- **Premise confirmed in Payload source.** `sanitizeFields` does `delete field.localized` **in place** on
+  any field under a localized ancestor (propagated via `parentIsLocalized`). The pipeline reads per-field
+  `localized` (no inherited computation), so a **deep** pre-sanitize copy is mandatory — a shared reference
+  re-introduces the silent no-translate bug.
+- **richText needs no schema data.** The lexical config lives in `field.editor` (async functions), but the
+  pipeline reads the lexical tree from the **document value** at runtime, never from the field schema — so
+  dropping `editor` (and all functions) is safe. This is exactly why `structuredClone` was impossible and
+  the projection is sound.
+- **Placement without breaking payload-free core.** The projector is a pure `FieldLike[] → FieldLike[]`
+  deep copy living in `core/kernel/field-traversal/projectFieldLike.ts` — it never imports Payload. The
+  `Field[] → FieldLike[]` assignment happens at the call site in `plugin.ts` (where Payload types are
+  legal), since Payload's `Field` is structurally assignable to `FieldLike`. `custom` is copied by
+  reference (passthrough bag Payload never mutates; deep-copying it would hit the same function problem).
+
 ## Risk / why it's a separate task
 
 This is content-projection work with a real data-correctness trap, not cosmetics:
@@ -56,15 +79,18 @@ This is content-projection work with a real data-correctness trap, not cosmetics
 
 ## Acceptance criteria
 
-- [ ] A typed `Field[] → FieldLike[]` projector replaces the JSON round-trip in `plugin.ts`.
-- [ ] `localized: true` is preserved on deeply-nested fields across group / array / blocks / named &
-      unnamed tabs / row / collapsible.
-- [ ] The projected schema is an independent deep copy — unaffected by later mutation of the source
-      collection objects (regression test simulating Payload's `localized` stripping).
-- [ ] `schemaMap` is typed as `FieldLike[]` (no `any` at the boundary).
-- [ ] Type-check + lint clean; existing translation/staleness tests unchanged and green.
+- [x] A typed `FieldLike[] → FieldLike[]` projector (`projectFieldsToFieldLike`) replaces the JSON
+      round-trip in `plugin.ts` (Payload's `Field[]` assigns structurally at the call site).
+- [x] `localized: true` is preserved on deeply-nested fields across group / array / blocks / named &
+      unnamed tabs / row / collapsible (copied by value at projection time).
+- [x] The projected schema is an independent deep copy — regression test simulates Payload's in-place
+      `delete field.localized` on the source and asserts the projection is unaffected.
+- [x] `schemaMap` (`CollectionSchemaMap`) is typed as `FieldLike[]` (no `any` at the boundary); the two
+      internal consumers that annotated `Field[]` (`resolveFieldSubtree`, `Provenance.service`) retyped to `FieldLike[]`.
+- [x] Type-check + lint clean (repo baseline, no new warnings); full suite green.
 
 ## References
 
-- `src/plugin.ts` — the `TODO` next to `schemaMap` marks this.
-- `src/core/field-traversal/` — existing `FieldLike` + traversal walkers to reuse.
+- `src/plugin.ts` — the JSON round-trip (now `projectFieldsToFieldLike`).
+- `src/core/kernel/field-traversal/projectFieldLike.ts` (+ `.test.ts`) — the projector + regression test.
+- `src/core/kernel/field-traversal/` — existing `FieldLike` types the projection produces.

packages/payload-plugin-translator/src/core/kernel/field-traversal/index.ts

@@ -2,6 +2,7 @@ export { findFieldByPath } from "./findFieldByPath";
 export type { FieldPathResult } from "./findFieldByPath";
 export { hasFields, isBlockItem, isTabsField } from "./guards";
 export { classifyField, matchElementById, resolveBlockFields, tabScopes } from "./kernel";
+export { projectFieldsToFieldLike } from "./projectFieldLike";
 export {
   fieldAffectsData,
   fieldIsArrayType,

packages/payload-plugin-translator/src/core/kernel/field-traversal/projectFieldLike.test.ts

@@ -0,0 +1,285 @@
+import { describe, it, expect } from "vitest";
+
+import type { FieldLike } from "./types";
+import { projectFieldsToFieldLike } from "./projectFieldLike";
+
+// Tests are derived from the projection CONTRACT (design doc + Payload field model), not from the
+// implementation: the projector must deep-copy exactly { type, name, localized, custom, fields,
+// blocks(+slug), tabs(name/localized/fields) }, drop everything else, keep every field 1:1, and be
+// independent of later in-place mutation of the source (Payload's `delete field.localized`).
+
+const one = (fields: FieldLike[]): FieldLike => projectFieldsToFieldLike(fields)[0];
+
+describe("projectFieldsToFieldLike — property whitelist (leaf level)", () => {
+  it("keeps type, name, localized, and custom", () => {
+    const leaf = one([
+      {
+        type: "text",
+        name: "title",
+        localized: true,
+        custom: { translateKit: { exclude: false } },
+      },
+    ]);
+    expect(leaf).toEqual({
+      type: "text",
+      name: "title",
+      localized: true,
+      custom: { translateKit: { exclude: false } },
+    });
+  });
+
+  it("drops every non-whitelisted property (admin, required, validate, editor, hooks, defaultValue, access)", () => {
+    const leaf = one([
+      {
+        type: "richText",
+        name: "body",
+        localized: true,
+        required: true,
+        admin: { position: "sidebar" },
+        defaultValue: "x",
+        editor: { config: async () => ({}) },
+        validate: () => true,
+        hooks: { beforeChange: [() => undefined] },
+        access: { read: () => true },
+      },
+    ] as unknown as FieldLike[]);
+    expect(leaf).toEqual({ type: "richText", name: "body", localized: true });
+    for (const dropped of [
+      "required",
+      "admin",
+      "defaultValue",
+      "editor",
+      "validate",
+      "hooks",
+      "access",
+    ]) {
+      expect(leaf).not.toHaveProperty(dropped);
+    }
+  });
+
+  it("preserves `localized: false` verbatim (not dropped, not coerced)", () => {
+    const leaf = one([{ type: "text", name: "sku", localized: false }]);
+    expect(leaf.localized).toBe(false);
+    expect(leaf).toEqual({ type: "text", name: "sku", localized: false });
+  });
+
+  it("omits name/localized/custom keys when absent on the source", () => {
+    const leaf = one([{ type: "text" }]);
+    expect(leaf).toEqual({ type: "text" });
+    expect(leaf).not.toHaveProperty("name");
+    expect(leaf).not.toHaveProperty("localized");
+    expect(leaf).not.toHaveProperty("custom");
+  });
+
+  it("preserves arbitrary and empty custom contents", () => {
+    expect(one([{ type: "text", name: "a", custom: { k: 1, nested: { x: [2] } } }]).custom).toEqual(
+      {
+        k: 1,
+        nested: { x: [2] },
+      }
+    );
+    expect(one([{ type: "text", name: "b", custom: {} }]).custom).toEqual({});
+  });
+});
+
+describe("projectFieldsToFieldLike — containers (kept 1:1, recursed)", () => {
+  it("named group: keeps name, recurses fields", () => {
+    expect(
+      one([{ type: "group", name: "seo", fields: [{ type: "text", name: "title" }] }])
+    ).toEqual({
+      type: "group",
+      name: "seo",
+      fields: [{ type: "text", name: "title" }],
+    });
+  });
+
+  it("unnamed group: recurses fields, no name", () => {
+    const g = one([{ type: "group", fields: [{ type: "text", name: "loose" }] }]);
+    expect(g).toEqual({ type: "group", fields: [{ type: "text", name: "loose" }] });
+    expect(g).not.toHaveProperty("name");
+  });
+
+  it("array: keeps name, recurses element fields", () => {
+    expect(
+      one([{ type: "array", name: "items", fields: [{ type: "text", name: "label" }] }])
+    ).toEqual({
+      type: "array",
+      name: "items",
+      fields: [{ type: "text", name: "label" }],
+    });
+  });
+
+  it("blocks: keeps name and each block's slug + fields, across multiple blocks", () => {
+    expect(
+      one([
+        {
+          type: "blocks",
+          name: "sections",
+          blocks: [
+            { slug: "hero", fields: [{ type: "text", name: "heading", localized: true }] },
+            { slug: "cta", fields: [{ type: "text", name: "label" }] },
+          ],
+        },
+      ])
+    ).toEqual({
+      type: "blocks",
+      name: "sections",
+      blocks: [
+        { slug: "hero", fields: [{ type: "text", name: "heading", localized: true }] },
+        { slug: "cta", fields: [{ type: "text", name: "label" }] },
+      ],
+    });
+  });
+
+  it("tabs: keeps named (name/localized/fields) and unnamed (fields) tabs", () => {
+    expect(
+      one([
+        {
+          type: "tabs",
+          tabs: [
+            { name: "meta", localized: true, fields: [{ type: "text", name: "slug" }] },
+            { fields: [{ type: "text", name: "loose", localized: true }] },
+          ],
+        },
+      ])
+    ).toEqual({
+      type: "tabs",
+      tabs: [
+        { name: "meta", localized: true, fields: [{ type: "text", name: "slug" }] },
+        { fields: [{ type: "text", name: "loose", localized: true }] },
+      ],
+    });
+  });
+
+  it("presentational row/collapsible are transparent (fields recursed, no name)", () => {
+    const [row, collapsible] = projectFieldsToFieldLike([
+      { type: "row", fields: [{ type: "text", name: "a" }] },
+      { type: "collapsible", fields: [{ type: "text", name: "b" }] },
+    ]);
+    expect(row).toEqual({ type: "row", fields: [{ type: "text", name: "a" }] });
+    expect(collapsible).toEqual({ type: "collapsible", fields: [{ type: "text", name: "b" }] });
+  });
+
+  it("ui field is kept 1:1 with no fields", () => {
+    expect(one([{ type: "ui", name: "spacer" } as FieldLike])).toEqual({
+      type: "ui",
+      name: "spacer",
+    });
+  });
+
+  it("keeps an empty fields array as [] (does not drop the container)", () => {
+    expect(one([{ type: "group", name: "empty", fields: [] }])).toEqual({
+      type: "group",
+      name: "empty",
+      fields: [],
+    });
+  });
+
+  it("preserves sibling order and count at the root", () => {
+    const projected = projectFieldsToFieldLike([
+      { type: "text", name: "a" },
+      { type: "group", name: "b", fields: [] },
+      { type: "ui", name: "c" } as FieldLike,
+      { type: "array", name: "d", fields: [] },
+    ]);
+    expect(projected.map((f) => `${f.type}:${f.name ?? ""}`)).toEqual([
+      "text:a",
+      "group:b",
+      "ui:c",
+      "array:d",
+    ]);
+  });
+});
+
+describe("projectFieldsToFieldLike — deep independence (the localized-stripping trap)", () => {
+  it("nested `localized` survives Payload's in-place `delete` under a group", () => {
+    const leaf = { type: "text", name: "body", localized: true } as FieldLike;
+    const source: FieldLike[] = [{ type: "group", name: "g", localized: true, fields: [leaf] }];
+    const projected = projectFieldsToFieldLike(source);
+
+    delete (source[0] as { localized?: boolean }).localized;
+    delete (leaf as { localized?: boolean }).localized;
+
+    expect(projected[0].localized).toBe(true);
+    expect(projected[0].fields?.[0]).toEqual({ type: "text", name: "body", localized: true });
+  });
+
+  it("nested `localized` survives under an array element", () => {
+    const leaf = { type: "text", name: "label", localized: true } as FieldLike;
+    const source: FieldLike[] = [{ type: "array", name: "items", fields: [leaf] }];
+    const projected = projectFieldsToFieldLike(source);
+    delete (leaf as { localized?: boolean }).localized;
+    expect(projected[0].fields?.[0]?.localized).toBe(true);
+  });
+
+  it("nested `localized` survives inside a block and under a named tab", () => {
+    const blockLeaf = { type: "text", name: "heading", localized: true } as FieldLike;
+    const tabLeaf = { type: "text", name: "slug", localized: true } as FieldLike;
+    const source: FieldLike[] = [
+      { type: "blocks", name: "s", blocks: [{ slug: "hero", fields: [blockLeaf] }] },
+      { type: "tabs", tabs: [{ name: "meta", localized: true, fields: [tabLeaf] }] },
+    ];
+    const projected = projectFieldsToFieldLike(source);
+    delete (blockLeaf as { localized?: boolean }).localized;
+    delete (tabLeaf as { localized?: boolean }).localized;
+    expect(projected[0].blocks?.[0]?.fields?.[0]?.localized).toBe(true);
+    expect(projected[1].tabs?.[0]?.fields?.[0]?.localized).toBe(true);
+  });
+
+  it("deep mixed nesting (group > array > blocks > named tab > leaf) preserves the bottom `localized`", () => {
+    const deepLeaf = { type: "text", name: "text", localized: true } as FieldLike;
+    const source: FieldLike[] = [
+      {
+        type: "group",
+        name: "g",
+        fields: [
+          {
+            type: "array",
+            name: "rows",
+            fields: [
+              {
+                type: "blocks",
+                name: "blk",
+                blocks: [
+                  {
+                    slug: "b",
+                    fields: [{ type: "tabs", tabs: [{ name: "t", fields: [deepLeaf] }] }],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ];
+    const projected = projectFieldsToFieldLike(source);
+    delete (deepLeaf as { localized?: boolean }).localized;
+
+    const bottom =
+      projected[0].fields?.[0]?.fields?.[0]?.blocks?.[0]?.fields?.[0]?.tabs?.[0]?.fields?.[0];
+    expect(bottom).toEqual({ type: "text", name: "text", localized: true });
+  });
+
+  it("adding a sibling to the source field list does not affect the projection", () => {
+    const source: FieldLike[] = [
+      { type: "group", name: "g", fields: [{ type: "text", name: "a" }] },
+    ];
+    const projected = projectFieldsToFieldLike(source);
+    source[0].fields?.push({ type: "text", name: "injected" });
+    expect(projected[0].fields).toHaveLength(1);
+  });
+
+  it("produces distinct object identities at every level (deep copy, not shared references)", () => {
+    const source: FieldLike[] = [
+      {
+        type: "blocks",
+        name: "s",
+        blocks: [{ slug: "hero", fields: [{ type: "text", name: "h" }] }],
+      },
+    ];
+    const projected = projectFieldsToFieldLike(source);
+    expect(projected[0]).not.toBe(source[0]);
+    expect(projected[0].blocks?.[0]).not.toBe(source[0].blocks?.[0]);
+    expect(projected[0].blocks?.[0]?.fields?.[0]).not.toBe(source[0].blocks?.[0]?.fields?.[0]);
+  });
+});