fix(rest,lint): the whole-plus-part collision refusal lists the legal parts too

Ruling item 3 on #20149 says a refusal names the field and lists the
legal parts. The rest door emitted the parts sentence only when an
unknown target was present, and the lint collision hint carried no
part list; both now list the object's compound fields and their parts
on every refusal, and the collision pins assert it. The mapping.zod
docblock now names the reader of the part set.

Claude-Session: https://claude.ai/code/session_01QcAS3qiYYZNezaxZxaUdMV
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/lint/src/validate-mapping-target-fields.test.ts

@@ -117,7 +117,9 @@ describe('validateMappingTargetFields', () => {
     expect(findings[0]).toMatchObject({
       rule: MAPPING_TARGET_FIELD_UNKNOWN,
       path: 'mappings[0].fieldMapping[1].target',
-      hint: 'Map the field whole or by its parts, not both.',
+      // The collision names the field AND lists its legal parts, as every refusal does.
+      hint: 'Map the field whole or by its parts, not both. A declared part of a compound field is written '
+        + 'field.part (mailing_address: street, city, state, postalCode, country, countryCode, formatted).',
     });
     expect(findings[0].message).toContain(
       'writes the compound field "mailing_address" of object "crm_contact" both whole (fieldMapping[0].target) '

packages/lint/src/validate-mapping-target-fields.ts

@@ -152,7 +152,11 @@ export function validateMappingTargetFields(stack: AnyRec): MappingTargetFieldFi
     if (misses.length === 0) continue; // clean, or skip 2
     const index = indexImportMappingTargets(objectDef);
     const known = index?.names ?? new Set<string>();
-    const compound = index ? [...index.parts] : [];
+    // The object's compound fields and their legal parts, which EVERY finding's
+    // hint lists, a collision's included (ruling on #20149, item 3).
+    const compoundParts = index && index.parts.size > 0
+      ? [...index.parts].map(([field, parts]) => `${field}: ${parts.join(', ')}`).join('; ')
+      : '';
     const mappingName = strName(mapping.name) ?? `#${mi}`;
     const where = `mapping "${mappingName}" · object "${objectName}"`;
 
@@ -169,7 +173,9 @@ export function validateMappingTargetFields(stack: AnyRec): MappingTargetFieldFi
             `"${objectName}" both whole (${miss.wholeAt}) and by its part "${miss.target.slice(dot + 1)}" ` +
             `(${miss.path}). One row carries one value for a field, so the two collide, and the import endpoint ` +
             `refuses this mapping before any row, on the dry run and the commit alike (INVALID_FIELD).`,
-          hint: 'Map the field whole or by its parts, not both.',
+          hint:
+            'Map the field whole or by its parts, not both. A declared part of a compound field is ' +
+            `written field.part (${compoundParts}).`,
         });
         continue;
       }
@@ -186,10 +192,7 @@ export function validateMappingTargetFields(stack: AnyRec): MappingTargetFieldFi
         hint:
           `Point the target at a field "${objectName}" declares, or at a column the platform provisions ` +
           `on it` +
-          (compound.length > 0
-            ? `, or at a declared part of a compound field as field.part (` +
-              compound.map(([field, parts]) => `${field}: ${parts.join(', ')}`).join('; ') + ')'
-            : '') +
+          (compoundParts ? `, or at a declared part of a compound field as field.part (${compoundParts})` : '') +
           `. Addressable names: ${listNames(known)}.`,
       });
     }

packages/rest/src/import-integration.test.ts

@@ -855,6 +855,8 @@ describe('import route — a declared part of a compound field (#20149)', () =>
       expect(res._json.error).toContain(
         '(fieldMapping[2].target "mailing_address.street", with the whole field at fieldMapping[1].target)',
       );
+      // …and, like every refusal, it lists the legal parts.
+      expect(res._json.error).toContain(`or at a declared part of a compound field as field.part (mailing_address: ${PARTS})`);
     }
     expect(dry._json).toEqual(commit._json);
     expect(await engine.find('contact', { where: {} })).toHaveLength(0);

packages/rest/src/import-mapping.test.ts

@@ -250,5 +250,7 @@ describe('refuseUnknownMappingTargets — compound-field parts (#20149)', () =>
             + 'with the whole field at fieldMapping[0].target)',
         );
         expect(r?.error).toContain('refused before any row, on the dry run and the commit alike');
+        // A collision-only refusal lists the legal parts too (ruling item 3).
+        expect(r?.error).toContain(`or at a declared part of a compound field as field.part (mailing_address: ${PARTS})`);
     });
 });

packages/rest/src/import-mapping.ts

@@ -171,7 +171,9 @@ export function refuseUnknownMappingTargets(
             + 'Map the field whole or by its parts, not both.',
         );
     }
-    if (unknown.length > 0) sentences.push(`Point each target at a field the object declares${partsHint(objectSchema)}.`);
+    // Every refusal, a collision included, ends by listing the legal parts
+    // (ruling on #20149, item 3: the refusal names the field and lists them).
+    sentences.push(`Point each target at a field the object declares${partsHint(objectSchema)}.`);
     return { ok: false, status: 400, code: 'INVALID_FIELD', error: sentences.join(' ') };
 }
 

packages/spec/src/data/mapping.zod.ts

@@ -191,9 +191,11 @@ export type TransformType = z.input<typeof TransformType>;
  *    single `string`. A target may also name a declared PART of a compound
  *    field, `field.part` (`mailing_address.street`, #20149): the import path
  *    assembles every part one row maps into that field's one value. Which
- *    fields are compound, and which parts they declare, is read from the
- *    field's value schema by `judgeImportMappingTarget`
- *    (`import-mapping-target.ts`), the one verdict every door asks.
+ *    fields are compound, and which parts they declare, is read from each
+ *    field's value schema when `indexImportMappingTargets` indexes the object
+ *    (its module-private `importTargetPartsOf`, `import-mapping-target.ts`);
+ *    `judgeImportMappingTarget`, the one verdict every door asks, then judges
+ *    a `field.part` target against that set.
  * 3. This schema is a {@link strictObject} (#4001): an unknown key THROWS with
  *    an alias/typo prescription. The other two are plain `z.object` and strip
  *    silently. Opposite failure modes under one name is exactly how a snippet