Repository navigation
Commit c4b49c3
Fixes #25078
Clause-②: no (narrowing)
Metadata-protocol: none
The CSV export now writes a text cell its consumer would interpret in a
form that consumer reads as text, and the CSV import reverses exactly
that. This is this repository's half of the maintainer's choice B on
#25078 (comment `6319255545`): the rule is defined once, server-side,
and both directions read it.
Both landing prerequisites are on `main`: objectstack-ai/objectui#13316,
merged as `56cf4d8e89`, and this repository's `.objectui-sha` bump over
it, PR #25160, merged as `06900c9c2`.
## Contract
**Served answers that change**
- `GET /api/v1/data/:object/export?format=csv`, on the metadata path and
on the raw path (no field metadata). A CSV text cell is served with one
apostrophe (U+0027) in front of its content, before the RFC-4180
quoting, when both of these hold:
- its first character is one of a small fixed set that the file's
consumer interprets;
- it is not made only of digits, spaces and the characters a signed
number or a phone number is written with.
- A text cell is a string in a column whose field is not declared
numeric, boolean, date or datetime. The declared type decides, never the
JS type. Header labels and reference display titles are text cells too.
On the raw path every string cell is one.
- Every other byte of the file is unchanged.
- `parseCsvToRows`, exported from `@objectstack/rest`, and through it
the CSV payload of three doors:
- `POST /api/v1/data/:object/import`;
- `POST /api/v1/data/:object/import/jobs`;
- `POST /api/v1/auth/admin/import-users`.
- Every cell, header row included, loses exactly one leading apostrophe
when the rest of the cell is one the export would mark. Cells without
that shape are unchanged.
- The reversal runs at the parse, before an inline or a named mapping,
and it reads the cell text only. With a named mapping, rows keep their
source headers until core's `applyMappingToRows`, so no target field
type is known at that point.
**Unchanged by construction:** phone numbers and signed amounts; every
cell that does not begin with one of the set; numeric, boolean, date and
datetime cells; the xlsx and json export formats; json and xlsx import
payloads.
**Stated consequences**
- A user-authored CSV cell that is an apostrophe followed by a cell the
export would mark now imports without that apostrophe. A cell that
begins with an apostrophe followed by anything else imports unchanged.
- A stored text value of that same shape is written unchanged by the
export, so it comes back without its leading apostrophe. Measured with a
one-shot script against this branch: it is the one stored shape the
round trip does not return unchanged. The maintainer kept the rule as
chosen (ruling record `6328219098` on the card).
- A value beginning with TAB or CR is marked, and the import removes the
mark. Core's default `trimWhitespace: true` then trims the leading TAB
or CR, exactly as it did before this change. With `trimWhitespace:
false` the value returns exactly. Both cases are pinned in
`csv-text-cell-round-trip.test.ts`.
The rule lives in `packages/rest/src/export-format.ts`
(`csvTextCellNeedsMark`, `markCsvTextCell`, `unmarkCsvTextCell`,
`isCsvTextColumn`). The writer is `formatCsvCell` / `rowsToCsv` in
`rest-server.ts`. The reversal is in `parseCsvToRows` in
`import-prepare.ts`.
## Files
- `packages/rest/src/export-format.ts`: the rule, defined once. The set
of non-text types is composed from the spec's `NUMERIC_VALUE_TYPES`,
`BOOLEAN_VALUE_TYPES`, `CALENDAR_DATE_TYPES` and `INSTANT_TYPES`, not
re-listed.
- `packages/rest/src/rest-server.ts`: `formatCsvCell` takes a
text-column flag, and `rowsToCsv` derives that flag per column from the
declared type.
- `packages/rest/src/import-prepare.ts`: `parseCsvToRows` reverses every
cell, and reverses header cells before trimming and mapping.
- `packages/rest/src/data-action-routes.ts`: comment only. The export
route's doc said the raw path streams stored values unchanged, which
this change makes false for csv.
- Pins:
- `packages/rest/src/csv-text-cell.test.ts` (new);
- `packages/rest/src/csv-text-cell-round-trip.test.ts` (new);
- one new `describe` in
`packages/plugins/plugin-auth/src/admin-import-users.test.ts`, on that
file's existing engine double, so the engine-double ledger does not
move.
- `.changeset/25078-csv-text-cell.md`: `@objectstack/rest` `patch`. It
carries the BREAKING banner and one ADR-0087 marker, `not-required
(no-migration-prescription)`. Its "What to do" line points at the rule
in this repository's `packages/rest/src/export-format.ts`, not at a
function name the package does not publish.
## Tests
The tables and the ablations below were measured at `bf8244cb20`. The
suites were run again on the merged head `2e4476001`.
- **The predicate:** one table of 56 cases, with the boundary characters
on both halves of the rule.
- The code-point neighbours of each trigger as a first character.
- Every character of the numeric-text set, after each trigger character
the rule's second half applies to.
- A letter or a trailing word outside that set.
- **The writer table**, per value, on the metadata path and on the raw
path:
- plain words after a trigger character are marked;
- two phone numbers, a signed amount, a company name and an unsigned
amount are byte-identical;
- `number`, `currency` and `percent` fields holding a negative amount
stay numeric and unprefixed;
- a string in a numeric, boolean, date or datetime column is never
marked;
- header labels and reference titles that start with a trigger character
are marked.
- **The round trip, through each CSV door:**
- the sync import, with an inline mapping and with a named mapping;
- the async import job;
- the admin user import, whose file comes from the real export route of
`RestServer`.
- Each case asserts that the file carried the marks, and that every
stored value came back exactly, including a value that begins with an
apostrophe followed by a plain word.
- **Suites, at `2e4476001`:**
- This PR's pins: `csv-text-cell.test.ts` and
`csv-text-cell-round-trip.test.ts`, 2 files / 133 tests passed;
`admin-import-users.test.ts`, 41 of 41 passed.
- `@objectstack/rest` local project: 314 files / 6318 tests passed, 326
skipped.
- `@objectstack/plugin-auth`: 183 files / 3464 tests passed, 10 skipped.
- Both packages' `typecheck`, the test layer included, exit 0.
- `@objectstack/dogfood` (the full battery, owed by the `!` title): 287
files passed and 3 skipped; 2395 tests passed and 18 skipped.
**Ablations,** measured at `bf8244cb20` and not run again: this round
changes no tested behaviour. Each leg goes through
`scripts/ablation-replace.mjs`. The anchor must hit, and the restore is
proven by blob equal to HEAD and an empty `git diff HEAD`. The whole
tree's porcelain is empty after every leg.
- Writer ablated (`formatCsvCell` never marks): 20 red of 133.
- Header marking ablated: 5 red.
- Declared-type decision ablated (`isCsvTextColumn` always true): 12
red.
- The predicate's second half removed: 36 red.
- Cell reversal removed: 14 red.
- Header reversal removed: 6 red.
- Admin door, which resolves `@objectstack/rest` through `dist/`:
- The reversal was removed and rest was rebuilt.
`ablation-dist-preflight` then reported the marker absent from all 6
built files, and the admin round trip went red, 1 of 1.
- After the restore and a rebuild, the preflight reported the marker
present in 2 built files and a clean tree, and the pin was green again.
## Gates
All readings are on the merged head `2e4476001`, with each exit code
captured before any pipe.
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 71 commands from the 8 changed paths
against the merge base `06900c9c2`. All 71 exited 0 in one run, after a
full workspace build.
- The reconciliation printed: `✓ dispatch-gates --ran: 71 derived
famil(ies) accounted for — 71 run, 0 NOT-MEASURED (a DERIVED zero — all
71 recorded an exit code and none of them is 3)`.
- `node scripts/check-changeset-no-major.mjs --base origin/main --event`
with this body: exit 0, `LEVEL AXIS ... a non-protocol change at patch`.
- The families the derivation declares too wide to place, and `pnpm
lint`, are CI's runs and were not run locally.
- CI runs the full farm.
`main` at `fccbd9d0d5` was merged once into this branch. The incoming
commits touch no file this PR edits. One of them adds the NOT NULL
tenant column, and that is why the round-trip harness calls
`installDefaultOrganization`.
`main` at `06900c9c2` was then merged for landing, with no conflict. Of
the files this PR edits, it changes only `rest-server.ts`, and only
comments there (PR #25124). The pre-landing round, which is that merge
and the changeset's "What to do" line, is by session
`session_01AFrKwndmrCLtF5V9hNtrw3`.
## Acceptance notes
- **The changeset level is `patch`**, with `Metadata-protocol: none`.
That follows AGENTS.md Post-Task Checklist step 3 as it reads on `main`
since `f2b6cf230b`: a non-protocol change, widening or breaking, ships
`patch` and keeps its BREAKING banner and its ADR-0087 disposition.
- **For objectstack-ai/objectui#13315:** an inline mapping sent with CSV
text must name a column by its header as this parse reads it, that is
after the reversal. This only matters for a column whose label begins
with one of the set. At the pin `56cf4d8e89`, the wizard sends no inline
mapping. Its hand-mapped rows are keyed by field name in the browser,
and a named mapping travels by name (`buildImportRequest` in
`ImportWizard.tsx`, read with `git show`).
- **The round-trip harness calls `installDefaultOrganization`.** The
async job door's `sys_import_job` write needs the Default Organization
on the NOT NULL tenant column that landed on `main` in `5e9b100743`.
Without that call one test is red, measured.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01LmjU2x1faLZ39DVTFyVca6)_
---------
Co-authored-by: Claude <noreply@anthropic.com>
1 parent 82cfaf7 commit c4b49c3
8 files changed
Lines changed: 740 additions & 10 deletions
File tree
- .changeset
- packages
- plugins/plugin-auth/src
- rest/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
| 8 | + | |
8 | 9 | | |
9 | 10 | | |
10 | 11 | | |
| |||
719 | 720 | | |
720 | 721 | | |
721 | 722 | | |
| 723 | + | |
| 724 | + | |
| 725 | + | |
| 726 | + | |
| 727 | + | |
| 728 | + | |
| 729 | + | |
| 730 | + | |
| 731 | + | |
| 732 | + | |
| 733 | + | |
| 734 | + | |
| 735 | + | |
| 736 | + | |
| 737 | + | |
| 738 | + | |
| 739 | + | |
| 740 | + | |
| 741 | + | |
| 742 | + | |
| 743 | + | |
| 744 | + | |
| 745 | + | |
| 746 | + | |
| 747 | + | |
| 748 | + | |
| 749 | + | |
| 750 | + | |
| 751 | + | |
| 752 | + | |
| 753 | + | |
| 754 | + | |
| 755 | + | |
| 756 | + | |
| 757 | + | |
| 758 | + | |
| 759 | + | |
| 760 | + | |
| 761 | + | |
| 762 | + | |
| 763 | + | |
| 764 | + | |
| 765 | + | |
| 766 | + | |
| 767 | + | |
| 768 | + | |
| 769 | + | |
| 770 | + | |
| 771 | + | |
| 772 | + | |
| 773 | + | |
| 774 | + | |
| 775 | + | |
| 776 | + | |
| 777 | + | |
| 778 | + | |
| 779 | + | |
| 780 | + | |
| 781 | + | |
| 782 | + | |
| 783 | + | |
| 784 | + | |
| 785 | + | |
| 786 | + | |
| 787 | + | |
| 788 | + | |
| 789 | + | |
| 790 | + | |
| 791 | + | |
722 | 792 | | |
723 | 793 | | |
724 | 794 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
| 209 | + | |
| 210 | + | |
| 211 | + | |
| 212 | + | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
0 commit comments