You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 43714ca
Browse filesBrowse the repository at this point in the historyBrowse 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>
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.
|**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. |
235
236
|**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. |
236
237
|**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. |
|**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. |
364
366
|**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. |
365
367
|**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. |
|**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. |
383
386
|**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. |
384
387
|**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. |
|**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. |
0 commit comments