Skip to content

Commit 43714ca

Browse files
feat(spec): ImportRowResultSchema declares errors, every cell error of a failed row (#26454)
<!-- claude-projects-attribution: {"github_login":"os-support-ai"} --> _Requested by **Yibo Wang** · [project thread](https://claude.ai/code/project/chan_01BVUyyPie8gHwoPM18iABwB?thread=cmsg_01BVUyyPie8gHwoPM18iABwB3wFJFHKndij2dsJUvZgBfT)_ Fixes #26425 Clause-②: yes (widening) Metadata-protocol: added ## 维护者速读 - 改了什么:导入结果的每一行新增可选字段 `errors`,列出该行所有转换出错的单元格;原有的 `field` / `code` / `error` 保留,仍指第一个错误。spec 小版本(minor)。 - 为什么改:一行有多个坏单元格时只报第一个,用户改一格、重导、再撞下一格(#25582,hotcrm 表格导入);本 PR 是 spec 半,服务端填值随 #25582。 - 风险与回滚:只加可选键,旧读者与旧服务端完全不受影响;回滚即 revert 本 PR。 - 先看:`packages/spec/src/api/export.zod.ts`(新 `errors` 成员与其说明)、`packages/spec/src/api/export.test.ts`(新 describe 块)。 - 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run src/api/export.test.ts`,预期 57 个测试全绿,其中 7 个是新块。 - 需要你做的:无,席位落地。 ## What changes - `ImportRowResultSchema` (`packages/spec/src/api/export.zod.ts`) declares one optional member, `errors`: `z.array(ValidateDataIssueSchema)`, one element per failed cell of a failed row. Its describe says the list holds the import's cell-coercion errors and that a cell error never carries the advisory-only `rule` or `severity`, that it is present only on a failed row with at least one cell error, that a row failing for another reason (a duplicate or ambiguous match key) omits it, and that the first-error keys `field`, `code` and `error` stay and name element 0. The three first-error describes now say they are element 0 when `errors` is present. The schema docblock gains one paragraph on the key. - `ImportResponseSchema.results` and the async job's `ImportJobResultsSchema.results` carry it through the shared row schema; no other schema changes. - Spec only: `packages/core/src/utils/import-runner.ts` is untouched. Filling the list is #25582's server half. - Generated: `packages/spec/authorable-surface/api.json` gains `api/ImportRowResult:errors`; `content/docs/references/api/export.mdx` regenerated by `gen:docs`. A `minor` changeset for `@objectstack/spec` (`Metadata-protocol: added`: the authorable surface gains `api/ImportRowResult:errors`). ## Why Ruling `6377844879` on #25582 (batch #9 item 3a, letter A), quoted as written: 「一行所有单元格错误一次报全(报告加 `errors: [{ field, code, message }]`,原有第一错字段保留)」. Without a declared key, `ImportRowResultSchema.parse` strips one, so every reader typed by the schema would lose the list. ### Element shape: `ValidateDataIssueSchema`, reused Measured against what the issue asked (reuse unless there is a reason not to): - Its required members are exactly the ruling's `{ field, code, message }`, all `z.string()`. - The producer's element fits it as is: `coerceRow` returns `FieldCoerceError[]` (`packages/core/src/utils/import-coerce.ts`), `{ field: string; code: FieldErrorCode; message: string }`, and `FieldErrorCode` is a string enum, so the server half can copy the list without mapping. - The same row already uses it for `warnings`, and the validate verdict's row `errors` (`ValidateDataResponseSchema`, `protocol.zod.ts`) is `ValidateDataIssueSchema[]` too, so a row speaks one issue shape and a dry-run reader needs no third type. - The only cost: the element also declares the advisory-only optional `rule` and `severity`. A cell error never carries them (the docblock says so), and both are optional, so nothing is required that a cell error cannot give. Not a reason to mint a new shape. The test pins the element by identity (`toBe(ValidateDataIssueSchema)`, and equal to the `warnings` element) and by type (`expectTypeOf` against `ValidateDataIssue`). ## Tests New `describe('ImportRowResultSchema — errors (every cell error of a failed row)')` in `packages/spec/src/api/export.test.ts`, 7 tests: parse keeps every element in order; `field` / `code` / `error` agree with element 0 after parse; the key is optional (a first-error-only failed row parses unchanged, no `errors` key); the element is `ValidateDataIssueSchema` itself; an element without `message` is refused at `['errors', 0, 'message']`; `ImportResponseSchema` and `ImportJobResultsSchema` both keep it; the typed reader sees `ValidateDataIssue`. ## Acceptance notes - **For #25582's server half (carrier: #25582).** On a dry-run row the engine's validate verdict rejects, the runner sets `error` to `composeValidationMessage(verdict.errors)` (`import-runner.ts`, about `:1293`), every finding joined by `; `, not element 0's `message`. A row filled from `coerceRow`'s list (`:1221`) keeps `error` equal to element 0's message. The describe now scopes the list to the cell-coercion errors, so #25582 fills it from `coerceRow` only (option A, confirmed by the spec seat); filling it from verdict rows later would be a visible spec change. - No refine enforces "present only on a failed row" or the element-0 agreement: a refine would refuse rows that parse today, which is a narrowing. The describe states the contract, the test pins it on a conforming row. - `check:dev-prereqs` (local-only family) is red on this container because 37 workspace packages (mostly `ui/`) are not built; it judges local workspace state, not this diff. `packages/spec/dist` itself is fresh (the declaration stamp matches, per `check:generated`). ## Verification Local readings below were taken at head `2c2ade72`; the respin at `eff10df5` (changeset grade and describe sentence only) re-ran the build, `gen:docs`, `check:generated`, the changeset gates and the spec suite, recorded in the next block. <details><summary>spec test, typecheck, generated artifacts</summary> - `pnpm --filter @objectstack/spec test` (under the verify lock): `Test Files 727 passed (727)`, `Tests 22016 passed | 1 todo (22017)`, lock `VERDICT command-exit 0`. - `pnpm --filter @objectstack/spec typecheck`: `VERDICT command-exit 0`; `check:test-typecheck: OK`, debt ledger held. - `pnpm --filter @objectstack/spec check:generated`: first run named `content/docs/references/**` stale; after `gen:docs`, `✓ All 14 generated artifacts are up to date`. </details> <details><summary>respin at eff10df (Metadata-protocol added, minor, describe sentence)</summary> - `pnpm --filter @objectstack/spec build && gen:docs` (lock): `VERDICT command-exit 0`; `check:generated`: `✓ All 14 generated artifacts are up to date`. - `pnpm --filter @objectstack/spec test` (lock): `Test Files 727 passed (727)`, `Tests 22016 passed | 1 todo (22017)`, `VERDICT command-exit 0`. - `node scripts/check-changeset-no-major.mjs --base origin/main` with this body as the event: exit 0, `LEVEL AXIS: this PR declares clause-② yes (widening) and metadata-protocol added, and no package ... is graded patch`. `check-adr-0087-registration`: exit 0, no declared-breaking changeset. </details> <details><summary>ablation (one, on the tested behaviour)</summary> `node scripts/ablation-replace.mjs` renamed the declared key (`errors:` to `ablatedErrors:`, anchor 1 to 0, blob `ee8a1e9b6078` to `69e10a948a46`) and ran `vitest run src/api/export.test.ts`: `Tests 5 failed | 52 passed (57)`; the five red were the parse, element-0 agreement, element identity, refusal and response/job tests. The optional-key test stayed green, as it should. Restored: blob equals HEAD and `git diff HEAD` empty. The test imports `./export.zod` from source, so no dist leg applies. </details> <details><summary>derived gate families (dispatch-gates)</summary> `node scripts/pm/dispatch-gates.mjs --commands` derived 106 commands from 5 changed paths (142 changed lines). All 106 ran; reconciliation with exit codes recorded: `106 derived famil(ies) accounted for — 99 run, 7 NOT-MEASURED (7 DERIVED from a recorded exit 3)`. NOT MEASURED (exit 3, a prerequisite the gate refused on, none about `packages/spec`): - `pnpm --filter @objectstack/lint run check:doc-formula-expressions`, `check:doc-security-posture`: `@objectstack/formula` / `@objectstack/lint` not built. - `pnpm --filter @objectstack/spec run check:skill-examples`: `packages/client-react/dist` not built. - `pnpm check:docs-transcript-drift`: `@objectstack/lint` not built. - `pnpm check:dual-build-cjs-loads`, `pnpm check:lean-entry-closure`: other packages' `dist/` not built. - `node scripts/check-plugin-teardown-shape.mjs --self-test`: shallow checkout (checker health only). CI builds the workspace fresh and runs these families; their verdicts are the PR's check-runs. </details> ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. - [x] 2. Every name I added uses the casing for its kind. - [ ] 3. No formatter ran; `pnpm lint` is CI's run (repo-wide scan, not run locally). - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: its generated artifacts are regenerated and committed. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English (the 维护者速读 block is Chinese by fleet convention). --- _Generated by [Claude Code](https://claude.ai/code/session_01WGufzfC9dmHR7kTAVNHv56)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 00a4593 commit 43714ca

5 files changed

Lines changed: 132 additions & 12 deletions

File tree

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@objectstack/spec': minor
3+
---
4+
5+
feat(spec): an import row result can report every cell error of a failed row in `errors`
6+
7+
Clause-②: yes (widening)
8+
Metadata-protocol: added
9+
10+
`ImportRowResultSchema` (and so `ImportResponseSchema.results` and the async job's `results` sample) declares one optional member, `errors`: an array with one element per failed cell of a failed row, in the validate verdict's issue shape (`ValidateDataIssueSchema`: `field`, `code`, `message`), the same element the row's `warnings` already uses. The list holds the import's cell-coercion errors, and a cell error never carries the advisory-only `rule` or `severity`. It is present only on a failed row that has at least one cell error. The first-error keys `field`, `code` and `error` stay and keep naming element 0, so every current reader sees the same answer. Before, the schema had no such key, so `ImportRowResultSchema.parse` would strip one. This is the contract half: the import runner fills `errors` in a later change, and until then no server sends it.

‎content/docs/references/api/export.mdx‎

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -229,9 +229,10 @@ const result = CreateImportJobRequestSchema.parse(data);
229229
| **ok** | `boolean` | ✅ | Whether the row succeeded |
230230
| **action** | `Enum<'created' \| 'updated' \| 'skipped' \| 'failed'>` | ✅ | What happened to the row |
231231
| **id** | `string` | optional | Record id (created/updated rows) |
232-
| **field** | `string` | optional | Field that caused a coercion/validation error |
233-
| **code** | `string` | optional | Error code (failed rows) |
234-
| **error** | `string` | optional | Human-readable error message (failed rows) |
232+
| **field** | `string` | optional | Field that caused a coercion/validation error (element 0 of `errors` when present) |
233+
| **code** | `string` | optional | Error code (failed rows; element 0 of `errors` when present) |
234+
| **error** | `string` | optional | Human-readable error message (failed rows; element 0 of `errors` when present) |
235+
| **errors** | `{ field: string; code: string; message: string; rule?: string; … }[]` | optional | Every cell error of a failed row, one element per failed cell, in the validate verdict's issue shape (`field`, `code`, `message`). The list holds the import's cell-coercion errors, and a cell error never carries the advisory-only `rule` or `severity`. Present only on a failed row that has at least one cell error, so a row that failed for another reason (a duplicate or ambiguous match key, say) omits it. The first-error keys `field`, `code` and `error` stay and name element 0, so a reader of those keys sees the same answer as before. A server that does not produce this list omits the key, and the row then reports its first error only. |
235236
| **warnings** | `{ field: string; code: string; message: string; rule?: string; … }[]` | optional | Findings this deployment ADMITS rather than rejects, copied verbatim from the validate verdict's row `warnings`: ADR-0104 value shapes under a warn-first posture, then the hits of advisory validation rules (`severity: 'warning'` or `'info'`, each naming its `rule` and `severity`). Set only on a dry-run row the verdict accepted: the row is `ok` because the write would store it. A committed row does not carry it: the import does not copy a write answer's `warnings` onto the row. |
236237
| **droppedFields** | `{ object: string; fields: string[]; reason: Enum<'readonly' \| 'readonly_when' \| 'primary_key' \| 'computed' \| 'stored_expression'> }[]` | optional | Write-observability: caller-supplied fields the engine LEGALLY strips from THIS row, one event per reason, in the engine's own `droppedFields` shape and reason vocabulary. A committed row reports the strips its write made. A dry-run row reports the strips its preview runs, which for a row the import would update excludes `readonlyWhen` and primary-key strips, so that row can name fewer fields than its commit. The row still succeeds: `ok` and `action` are unchanged. Present only when at least one field was dropped. A server or write path that does not produce this report omits the key too, so an absent key alone does not prove nothing was dropped. In an async job's `results`, an ok row's drops reach the reader only if the row falls inside that capped, failures-first sample. |
237238

@@ -358,9 +359,10 @@ Type: `{ sourceField: string; targetField: string; targetLabel?: string; transfo
358359
| **ok** | `boolean` | ✅ | Whether the row succeeded |
359360
| **action** | `Enum<'created' \| 'updated' \| 'skipped' \| 'failed'>` | ✅ | What happened to the row |
360361
| **id** | `string` | optional | Record id (created/updated rows) |
361-
| **field** | `string` | optional | Field that caused a coercion/validation error |
362-
| **code** | `string` | optional | Error code (failed rows) |
363-
| **error** | `string` | optional | Human-readable error message (failed rows) |
362+
| **field** | `string` | optional | Field that caused a coercion/validation error (element 0 of `errors` when present) |
363+
| **code** | `string` | optional | Error code (failed rows; element 0 of `errors` when present) |
364+
| **error** | `string` | optional | Human-readable error message (failed rows; element 0 of `errors` when present) |
365+
| **errors** | `{ field: string; code: string; message: string; rule?: string; … }[]` | optional | Every cell error of a failed row, one element per failed cell, in the validate verdict's issue shape (`field`, `code`, `message`). The list holds the import's cell-coercion errors, and a cell error never carries the advisory-only `rule` or `severity`. Present only on a failed row that has at least one cell error, so a row that failed for another reason (a duplicate or ambiguous match key, say) omits it. The first-error keys `field`, `code` and `error` stay and name element 0, so a reader of those keys sees the same answer as before. A server that does not produce this list omits the key, and the row then reports its first error only. |
364366
| **warnings** | `{ field: string; code: string; message: string; rule?: string; … }[]` | optional | Findings this deployment ADMITS rather than rejects, copied verbatim from the validate verdict's row `warnings`: ADR-0104 value shapes under a warn-first posture, then the hits of advisory validation rules (`severity: 'warning'` or `'info'`, each naming its `rule` and `severity`). Set only on a dry-run row the verdict accepted: the row is `ok` because the write would store it. A committed row does not carry it: the import does not copy a write answer's `warnings` onto the row. |
365367
| **droppedFields** | `{ object: string; fields: string[]; reason: Enum<'readonly' \| 'readonly_when' \| 'primary_key' \| 'computed' \| 'stored_expression'> }[]` | optional | Write-observability: caller-supplied fields the engine LEGALLY strips from THIS row, one event per reason, in the engine's own `droppedFields` shape and reason vocabulary. A committed row reports the strips its write made. A dry-run row reports the strips its preview runs, which for a row the import would update excludes `readonlyWhen` and primary-key strips, so that row can name fewer fields than its commit. The row still succeeds: `ok` and `action` are unchanged. Present only when at least one field was dropped. A server or write path that does not produce this report omits the key too, so an absent key alone does not prove nothing was dropped. In an async job's `results`, an ok row's drops reach the reader only if the row falls inside that capped, failures-first sample. |
366368

@@ -377,12 +379,23 @@ Type: `{ sourceField: string; targetField: string; targetLabel?: string; transfo
377379
| **ok** | `boolean` | ✅ | Whether the row succeeded |
378380
| **action** | `Enum<'created' \| 'updated' \| 'skipped' \| 'failed'>` | ✅ | What happened to the row |
379381
| **id** | `string` | optional | Record id (created/updated rows) |
380-
| **field** | `string` | optional | Field that caused a coercion/validation error |
381-
| **code** | `string` | optional | Error code (failed rows) |
382-
| **error** | `string` | optional | Human-readable error message (failed rows) |
382+
| **field** | `string` | optional | Field that caused a coercion/validation error (element 0 of `errors` when present) |
383+
| **code** | `string` | optional | Error code (failed rows; element 0 of `errors` when present) |
384+
| **error** | `string` | optional | Human-readable error message (failed rows; element 0 of `errors` when present) |
385+
| **errors** | `{ field: string; code: string; message: string; rule?: string; … }[]` | optional | Every cell error of a failed row, one element per failed cell, in the validate verdict's issue shape (`field`, `code`, `message`). The list holds the import's cell-coercion errors, and a cell error never carries the advisory-only `rule` or `severity`. Present only on a failed row that has at least one cell error, so a row that failed for another reason (a duplicate or ambiguous match key, say) omits it. The first-error keys `field`, `code` and `error` stay and name element 0, so a reader of those keys sees the same answer as before. A server that does not produce this list omits the key, and the row then reports its first error only. |
383386
| **warnings** | `{ field: string; code: string; message: string; rule?: string; … }[]` | optional | Findings this deployment ADMITS rather than rejects, copied verbatim from the validate verdict's row `warnings`: ADR-0104 value shapes under a warn-first posture, then the hits of advisory validation rules (`severity: 'warning'` or `'info'`, each naming its `rule` and `severity`). Set only on a dry-run row the verdict accepted: the row is `ok` because the write would store it. A committed row does not carry it: the import does not copy a write answer's `warnings` onto the row. |
384387
| **droppedFields** | `{ object: string; fields: string[]; reason: Enum<'readonly' \| 'readonly_when' \| 'primary_key' \| 'computed' \| 'stored_expression'> }[]` | optional | Write-observability: caller-supplied fields the engine LEGALLY strips from THIS row, one event per reason, in the engine's own `droppedFields` shape and reason vocabulary. A committed row reports the strips its write made. A dry-run row reports the strips its preview runs, which for a row the import would update excludes `readonlyWhen` and primary-key strips, so that row can name fewer fields than its commit. The row still succeeds: `ok` and `action` are unchanged. Present only when at least one field was dropped. A server or write path that does not produce this report omits the key too, so an absent key alone does not prove nothing was dropped. In an async job's `results`, an ok row's drops reach the reader only if the row falls inside that capped, failures-first sample. |
385388

389+
### Nested Shape: `ImportRowResult.errors[number]`
390+
391+
| Property | Type | Required | Description |
392+
| :--- | :--- | :--- | :--- |
393+
| **field** | `string` | ✅ | The field the finding is about (`_record` for an object-level rule). |
394+
| **code** | `string` | ✅ | Machine-readable finding code, e.g. `required`, `invalid_type`, `rule_violation`. |
395+
| **message** | `string` | ✅ | Human-readable message — a validation rule's author-written text where one exists. |
396+
| **rule** | `string` | optional | The `name` of the ADVISORY validation rule this finding reports. Present only on an advisory rule hit. |
397+
| **severity** | `Enum<'warning' \| 'info'>` | optional | The advisory rule's declared severity, `warning` or `info`. Present only on an advisory rule hit. |
398+
386399
### Nested Shape: `ImportRowResult.warnings[number]`
387400

388401
| Property | Type | Required | Description |

‎packages/spec/authorable-surface/api.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -949,6 +949,7 @@
949949
"api/ImportRowResult:code",
950950
"api/ImportRowResult:droppedFields",
951951
"api/ImportRowResult:error",
952+
"api/ImportRowResult:errors",
952953
"api/ImportRowResult:field",
953954
"api/ImportRowResult:id",
954955
"api/ImportRowResult:ok",

‎packages/spec/src/api/export.test.ts‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,11 @@ import {
1111
ImportRequestSchema,
1212
CreateImportJobRequestSchema,
1313
ImportRowResultSchema,
14+
ImportResponseSchema,
1415
ImportJobResultsSchema,
1516
isMatchKeySets,
1617
} from './export.zod';
18+
import { ValidateDataIssueSchema } from './protocol.zod';
1719
import type { ValidateDataIssue } from './protocol.zod';
1820
import { DroppedFieldsEventSchema } from '../data/data-engine.zod';
1921
import type { DroppedFieldsEvent } from '../data/data-engine.zod';
@@ -478,6 +480,81 @@ describe('ImportRowResultSchema — droppedFields and warnings', () => {
478480
});
479481
});
480482

483+
// ==========================================
484+
// Import Row Result — every cell error of a failed row
485+
// ==========================================
486+
487+
/**
488+
* A failed row reports every bad cell in `errors`, and the first-error keys
489+
* `field` / `code` / `error` keep naming element 0. As above, the schema STRIPS
490+
* an undeclared key rather than refusing it, so the pin asserts `errors`
491+
* survives a parse, never bare `success`.
492+
*/
493+
describe('ImportRowResultSchema — errors (every cell error of a failed row)', () => {
494+
const cellErrors = [
495+
{ field: 'close_date', code: 'invalid_date', message: 'Close Date: "31/02/2026" is not a valid date' },
496+
{ field: 'stage', code: 'invalid_option', message: 'Stage: "Wonn" is not one of the options' },
497+
{ field: 'amount', code: 'invalid_number', message: 'Amount: "1,2,3" is not a number' },
498+
];
499+
const first = cellErrors[0]!;
500+
const failedRow = {
501+
row: 4, ok: false, action: 'failed' as const,
502+
field: first.field, code: first.code, error: first.message,
503+
errors: cellErrors,
504+
};
505+
506+
it('keeps every cell error through a parse, in order', () => {
507+
const parsed = ImportRowResultSchema.parse(failedRow);
508+
expect(parsed.errors).toEqual(cellErrors);
509+
});
510+
511+
it('the first-error keys stay, and agree with element 0', () => {
512+
const parsed = ImportRowResultSchema.parse(failedRow);
513+
expect(parsed.field).toBe(parsed.errors?.[0]?.field);
514+
expect(parsed.code).toBe(parsed.errors?.[0]?.code);
515+
expect(parsed.error).toBe(parsed.errors?.[0]?.message);
516+
});
517+
518+
it('is optional: a failed row with only the first-error keys parses unchanged', () => {
519+
const { errors: _omitted, ...firstOnly } = failedRow;
520+
const parsed = ImportRowResultSchema.parse(firstOnly);
521+
expect(parsed).toEqual(firstOnly);
522+
expect('errors' in parsed).toBe(false);
523+
});
524+
525+
it('the element is ValidateDataIssueSchema itself — no third issue shape', () => {
526+
const element = ImportRowResultSchema.shape.errors.unwrap().element;
527+
expect(element).toBe(ValidateDataIssueSchema);
528+
expect(element).toBe(ImportRowResultSchema.shape.warnings.unwrap().element);
529+
});
530+
531+
it('refuses an element without a message', () => {
532+
const partial = ImportRowResultSchema.safeParse({ ...failedRow, errors: [{ field: 'x', code: 'y' }] });
533+
expect(partial.success).toBe(false);
534+
const issue = partial.success ? undefined : partial.error.issues[0];
535+
expect(issue?.path).toEqual(['errors', 0, 'message']);
536+
});
537+
538+
it('the response and the async job sample carry it', () => {
539+
const response = ImportResponseSchema.parse({
540+
object: 'opportunity', dryRun: true, writeMode: 'insert',
541+
total: 1, ok: 0, errors: 1, created: 0, updated: 0, skipped: 0, results: [failedRow],
542+
});
543+
expect(response.results[0]?.errors).toEqual(cellErrors);
544+
const job = ImportJobResultsSchema.parse({
545+
jobId: 'imp_1', object: 'opportunity', status: 'succeeded', dryRun: false, writeMode: 'insert',
546+
total: 1, processed: 1, created: 0, updated: 0, skipped: 0, errors: 1, percentComplete: 100,
547+
undoable: false, createdAt: '2026-10-27T00:00:00.000Z',
548+
results: [failedRow], resultsTruncated: false,
549+
});
550+
expect(job.results[0]?.errors).toEqual(cellErrors);
551+
});
552+
553+
it('the typed reader sees the verdict\'s issue type', () => {
554+
expectTypeOf<NonNullable<ImportRowResult['errors']>[number]>().toEqualTypeOf<ValidateDataIssue>();
555+
});
556+
});
557+
481558
// ==========================================
482559
// applyOn (create-only import columns) and ordered match key sets
483560
// ==========================================

‎packages/spec/src/api/export.zod.ts‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -397,16 +397,35 @@ export type ImportRequestParsed = z.infer<typeof ImportRequestSchema>;
397397
* so that row's dry run can name fewer fields than its commit. The element
398398
* IS {@link DroppedFieldsEventSchema}, so the `reason` vocabulary is the
399399
* engine's — ⛔ never a second enum here.
400+
*
401+
* One optional report key rides on a `failed` row: `errors`, every cell error
402+
* of that row, so one import tells the user about every bad cell instead of
403+
* one per re-import. The first-error keys `field`, `code` and `error` stay and
404+
* keep naming element 0, so a reader of those keys is unchanged. The element
405+
* IS {@link ValidateDataIssueSchema}, the shape the row's `warnings` and the
406+
* validate verdict's `errors` already use, rather than a third issue shape: a
407+
* cell error is `{ field, code, message }`, and it never carries the
408+
* advisory-only `rule` / `severity`.
400409
*/
401410
export const ImportRowResultSchema = lazySchema(() => z.object({
402411
row: z.number().int().describe('1-based row number in the source data'),
403412
ok: z.boolean().describe('Whether the row succeeded'),
404413
action: z.enum(['created', 'updated', 'skipped', 'failed'])
405414
.describe('What happened to the row'),
406415
id: z.string().optional().describe('Record id (created/updated rows)'),
407-
field: z.string().optional().describe('Field that caused a coercion/validation error'),
408-
code: z.string().optional().describe('Error code (failed rows)'),
409-
error: z.string().optional().describe('Human-readable error message (failed rows)'),
416+
field: z.string().optional().describe('Field that caused a coercion/validation error (element 0 of `errors` when present)'),
417+
code: z.string().optional().describe('Error code (failed rows; element 0 of `errors` when present)'),
418+
error: z.string().optional().describe('Human-readable error message (failed rows; element 0 of `errors` when present)'),
419+
errors: z.array(ValidateDataIssueSchema).optional().describe(
420+
'Every cell error of a failed row, one element per failed cell, in the validate verdict\'s issue shape '
421+
+ '(`field`, `code`, `message`). The list holds the import\'s cell-coercion errors, and a cell error never '
422+
+ 'carries the advisory-only `rule` or `severity`. '
423+
+ 'Present only on a failed row that has at least one cell error, so a row '
424+
+ 'that failed for another reason (a duplicate or ambiguous match key, say) omits it. The first-error keys '
425+
+ '`field`, `code` and `error` stay and name element 0, so a reader of those keys sees the same answer '
426+
+ 'as before. A server that does not produce this list omits the key, and the row then reports its first '
427+
+ 'error only.',
428+
),
410429
warnings: z.array(ValidateDataIssueSchema).optional().describe(
411430
'Findings this deployment ADMITS rather than rejects, copied verbatim from the validate verdict\'s row '
412431
+ '`warnings`: ADR-0104 value shapes under a warn-first posture, then the hits of advisory validation rules '

0 commit comments

Comments
 (0)