no-mistakes(review): Narrow export withCount refusal, wire-aware JVM export cells

Author: dmealing

CHANGELOG.md

@@ -19,10 +19,11 @@ here.**
   generator emit the `format` branch. Without `format`, or with no export generator wired, a
   response is byte-identical to before. CSV is RFC 4180 with CRLF, a header row of the derived
   field names, wire-form values and a formula-injection guard on every string cell (the render
-  escapers' rule); JSON is the list route's array plus `Content-Disposition`; XML is
-  `<{Report}><row><{field}>...` with a pinnable null form (`xmlNulls`). A format the route does not
-  wire answers `400 {"error":"invalid_format","expected":[...]}`, `withCount` with a format answers
-  `400 export_with_count`, and more rows than the generator option `maxRows` (default 100,000)
+  escapers' rule); JSON is the list route's body (the array, or the `withCount` envelope) plus
+  `Content-Disposition`; XML is `<{Report}><row><{field}>...` with a pinnable null form
+  (`xmlNulls`). A format the route does not wire answers
+  `400 {"error":"invalid_format","expected":[...]}`, `withCount` with `format=csv` or `format=xml`
+  answers `400 export_with_count`, and more rows than the generator option `maxRows` (default 100,000)
   answers `400 {"error":"export_too_large","maxRows":N}` before a byte is written; nothing is ever
   truncated. With `format` set `maxRows` governs and the list route's `report_too_large` cap does
   not. The export adds no dependency an adopter must install in any port, and `xlsx` is reserved

docs/features/api-contract.md

@@ -295,11 +295,11 @@ never consulted**: the selector is the query parameter, in every port.
 | Request | Answer |
 |---|---|
 | no `format` | Exactly the list route above: same body, same headers, same caps. |
-| `format=json` | The list route's JSON array, unchanged, plus `Content-Disposition`. `Content-Type: application/json`. |
+| `format=json` | The list route's JSON body, unchanged, plus `Content-Disposition`: the array, or with `withCount=1` the `{ rows, total }` envelope. `Content-Type: application/json`. |
 | `format=csv` | RFC 4180 CSV. `Content-Type: text/csv; charset=utf-8`. |
 | `format=xml` | `application/xml`, shape below. |
 | any other value (`xlsx`, `pdf`, `CSV`, empty) | `400 { "error": "invalid_format", "expected": ["csv", "json", "xml"] }`. `expected` lists the formats this route wires, in that order. `xlsx` is reserved for a later generator (`report-export-xlsx`) and is refused today like any unknown value. Matching is case-sensitive. |
-| `format` set and `withCount` truthy | `400 { "error": "export_with_count" }` (`message` is free prose). An export has no `{ rows, total }` envelope, JSON included. |
+| `format=csv` or `format=xml` and `withCount` truthy | `400 { "error": "export_with_count" }` (`message` is free prose). Only JSON carries the `{ rows, total }` envelope. |
 | more rows than `maxRows` | `400 { "error": "export_too_large", "maxRows": N }` before a byte of the body is written. |
 
 - **Header comparison.** Header names are case-insensitive. A runner compares `Content-Type` with the whitespace around `;` normalized (`text/csv;charset=utf-8` equals `text/csv; charset=utf-8`), because some servers re-spell it; every other header is compared exactly.

docs/features/own-your-codegen.md

@@ -1150,8 +1150,8 @@ function, the digest and the renderer and filter hook types stay in the package.
 with its own command (`meta eject report-export`, `metaobjects eject`, `mvn metaobjects:eject
 -Dnames=report-export`, `dotnet meta eject report-export`). The copy holds the CSV and XML writers,
 so the guard, quoting and null form are yours to change. The routes generator emits the `format`
-branch only when the generator is wired (the TypeScript, C# and Python runners detect it from the
-generator list; Java and Kotlin take `reportExport=true` on `routes`). Options and defaults:
+branch only when the generator is wired: every port's runner detects it from the generator list (on
+Java and Kotlin the Maven plugin hands that list to `routes`). Options and defaults:
 [reporting.md](reporting.md#exporting-a-report).
 
 ### Java `entity` and `extractor`

docs/features/reporting.md

@@ -784,7 +784,11 @@ guard, XML escaping).
 **The cap, once.** A report has two caps and they never both apply to one request. Without
 `format`, the list route's cap (`reportMaxRows` or its port's name, default 10,000, answers
 `report_too_large`) is untouched. With `format`, `maxRows` governs and `export_too_large` answers,
-including for `format=json`, so an export can be larger than the list. The route fetches
+including for `format=json`, so an export can be larger than the list.
+
+**`withCount`.** `format=json&withCount=1` downloads the list route's `{ rows, total }` envelope.
+CSV and XML have no place for a total, so `withCount` with `format=csv` or `format=xml` is
+refused with `400 export_with_count`. The route fetches
 `maxRows + 1` rows to tell exactly the cap from more than the cap before writing a byte. A report
 is materialised up to the cap; there is no streaming in this version.
 

docs/ports/csharp.md

@@ -371,7 +371,7 @@ new ReportExportGenerator { MaxRows = 50_000, XmlNulls = ReportExportXmlNulls.Ni
   declares `xmlns:xsi`. That is what `XmlSerializer` writes for a nullable value type and what
   `DataContractSerializer` writes for any null, and it keeps a null apart from an empty string. `Empty`
   writes a bare empty element and declares nothing.
-- **JSON** is the list route's array through the host's configured JSON options (so a `wire` setting and
+- **JSON** is the list route's body (the array, or `{ rows, total }` with `withCount`) through the host's configured JSON options (so a `wire` setting and
   a `JsonStringEnumConverter` apply as on the list route), served as `application/json`.
 - A character XML 1.0 cannot carry is written as U+FFFD rather than failing the export.
 

docs/ports/java.md

@@ -447,27 +447,31 @@ generates nothing. The contract is in
 
 `GET <apiPrefix>/<segment>?format=csv|json|xml` downloads a served report's rows (the contract is
 [api-contract](../features/api-contract.md#report-export), the how-to
-[reporting](../features/reporting.md#exporting-a-report)). Two entries turn it on, and both are
-needed: wire the `report-export` generator, and give the `routes` generator the arg
-`<reportExport>true</reportExport>`. The routes arg is what mounts the `format` branch in each report
-`<R>Controller` (the generator list is not visible to a sibling generator, so the wiring is a
-visible arg, not a guess); the branch reads its cap from `<R>Export.MAX_ROWS`, so the cap is set
-once, as `maxRows` on `report-export`. A project with the arg unset gets controllers byte-identical to
-today, and `?format=` is ignored like any unknown parameter.
+[reporting](../features/reporting.md#exporting-a-report)). Wire the `report-export` generator to turn
+it on. The Maven plugin hands the whole configured generator list to the `routes` generator
+(`com.metaobjects.generator.RunAware`), which mounts the `format` branch in each report
+`<R>Controller` when that list holds a `report-export` generator (`EmitsReportExport`, so an
+ejected copy counts too). The branch reads its cap from `<R>Export.MAX_ROWS`, so the cap is set
+once, as `maxRows` on `report-export`. A project that does not wire it gets controllers
+byte-identical to today, and `?format=` is ignored like any unknown parameter.
 
 With `?format` set the export cap (`maxRows`, default 100,000) governs and `report_too_large` never
 answers; without it `reportMaxRows` (default 10,000) is untouched. The handler reads `maxRows + 1`
 rows and answers `export_too_large` before writing a byte. The request side (format parsing, the
 three 400 envelopes, the `Content-Disposition` and `Content-Type` values) is
 `com.metaobjects.generator.spring.runtime.ReportExport`, a JDK-only class. (The Kotlin port generates its own copy of these helpers into its writer module.) With the branch mounted, the list route answers an explicit `application/json`, so a
 request's `Accept` header is never consulted (a client sending `Accept: text/csv` without `format`
-still gets JSON, not a 406). `withCount` is read as text on such a route (`1` or `true`).
+still gets JSON, not a 406). `withCount` is read as text on such a route: `1` or `true` with `csv` or
+`xml` is `export_with_count`, and `format=json&withCount=1` is the list route's `{ rows, total }`
+envelope.
 
 `xmlNulls` defaults to `empty`: a null field is an empty element, which is what Jackson's XML mapper
 writes for a null, the Java standard (ADR-0019 Amendment 2). `nil` writes `xsi:nil="true"` and declares
-`xmlns:xsi` on the root. A decimal cell is its canonical plain string (no exponent, no trailing zeros)
-under either `wire` setting, and an array or map dimension is its compact JSON text. The JSON export is
-the list route's array through the application's `ObjectMapper`, so a `wire` setting applies to it as
+`xmlns:xsi` on the root. A decimal cell is written as the `wire` setting writes the list route: under
+`decimals: string` its canonical plain string (`12.5`), under the default `native` what Jackson writes
+for a `BigDecimal` (`12.50`). A time or a zone-less timestamp keeps its seconds (`10:00:00`), as
+Jackson's JSR-310 serializers write it, and an array or map dimension is its compact JSON text. The JSON export is
+the list route's body through the application's `ObjectMapper`, so a `wire` setting applies to it as
 it does to the list. CSV and XML are written as `byte[]`, which every Spring MVC setup has a converter
 for.
 

docs/ports/kotlin.md

@@ -549,13 +549,13 @@ follows the output mode: `options` and `storageParameters` are `Table` members o
 
 `GET <apiPrefix>/<segment>?format=csv|json|xml` downloads a served report's rows (the contract is
 [api-contract](../features/api-contract.md#report-export), the how-to
-[reporting](../features/reporting.md#exporting-a-report)). Two entries turn it on, and both are
-needed: wire `KotlinReportExportGenerator` (`report-export`), and give `KotlinSpringControllerGenerator`
-the arg `<reportExport>true</reportExport>`. The routes arg is what mounts the `format` branch in each
-report `<Report>Controller` (a generator cannot see its siblings, so the wiring is a visible arg); the
-branch reads its cap from `<Report>Export.MAX_ROWS`, so the cap is set once, as `maxRows` on
-`report-export`. With the arg unset the controllers are byte-identical to today and `?format=` is
-ignored like any unknown parameter.
+[reporting](../features/reporting.md#exporting-a-report)). Wire `KotlinReportExportGenerator`
+(`report-export`) to turn it on. The Maven plugin hands the whole configured generator list to
+`KotlinSpringControllerGenerator` (`com.metaobjects.generator.RunAware`), which mounts the `format`
+branch in each report `<Report>Controller` when that list holds a `report-export` generator
+(`EmitsReportExport`, so an ejected copy counts too). The branch reads its cap from
+`<Report>Export.MAX_ROWS`, so the cap is set once, as `maxRows` on `report-export`. Without it the
+controllers are byte-identical to today and `?format=` is ignored like any unknown parameter.
 
 The Kotlin controllers import nothing from MetaObjects, so the request side (format parsing, the three
 400 envelopes, the `Content-Disposition` and `Content-Type` values) is generated into the shared
@@ -564,14 +564,17 @@ use Jackson (already present) and the JDK's StAX, so nothing new is on the class
 set the export cap (`maxRows`, default 100,000) governs and `report_too_large` never answers; without
 it `reportMaxRows` (default 10,000) is untouched. The handler reads `maxRows + 1` rows and answers
 `export_too_large` before writing a byte. With the branch mounted, every answer of the list route
-carries an explicit `application/json`, so `Accept` is never consulted, and `withCount` is read as text
-(`1` or `true`). CSV and XML are written as `ByteArray`, for which every Spring MVC setup has a converter.
+carries an explicit `application/json`, so `Accept` is never consulted, and `withCount` is read as text:
+`1` or `true` with `csv` or `xml` is `export_with_count`, and `format=json&withCount=1` is the list
+route's `{ rows, total }` envelope. CSV and XML are written as `ByteArray`, for which every Spring MVC setup has a converter.
 
 `xmlNulls` defaults to `empty`: a null field is an empty element, which is what Jackson's XML mapper
 writes for a null, the JVM standard (ADR-0019 Amendment 2, the same default as the Java port). `nil`
-writes `xsi:nil="true"` and declares `xmlns:xsi` on the root. A decimal cell is its canonical plain
-string (no exponent, no trailing zeros) under either `wire` setting, and an array or map dimension is
-its compact JSON text. The JSON export is the list route's array through the application's
+writes `xsi:nil="true"` and declares `xmlns:xsi` on the root. A decimal cell is written as the `wire`
+setting writes the list route: under `decimals: string` its canonical plain string (`12.5`), under the
+default `native` what Jackson writes for a `BigDecimal` (`12.50`). A time or a zone-less timestamp keeps
+its seconds (`10:00:00`), as Jackson's JSR-310 serializers write it, and an array or map dimension is
+its compact JSON text. The JSON export is the list route's body through the application's
 `ObjectMapper`. `csvBom` flips the generated constant `EXPORT_CSV_BOM`.
 
 ### Decimals and null members on the wire

docs/ports/python.md

@@ -175,7 +175,8 @@ xml_nulls="empty", csv_bom=False)`. `xml_nulls` defaults to `"empty"` (an empty
 is what Python's own XML serializers write for `None`; `"nil"` writes `xsi:nil="true"` and
 declares `xmlns:xsi` on the root. With `?format` set the export cap (`max_rows`,
 `export_too_large`) governs; without it the list route's `report_max_rows` cap
-(`report_too_large`) is unchanged. JSON export is the list route's array through the same
+(`report_too_large`) is unchanged. JSON export is the list route's body (the array, or
+`{rows, total}` with `withCount=1`) through the same
 `render_wire` and FastAPI encoder, so the `wire` setting applies. A column holding an array,
 map or object is written as compact JSON text in CSV and XML. `routes` imports the request
 helper `metaobjects.codegen.runtime.report_export` (an owned `routes` emits it under

examples/advanced-modeling/codegen/runtime/drizzle-fastify/mount-read-only.ts

@@ -211,7 +211,7 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
       const withCount = isTruthyFlag(parsed["withCount"]);
       // Export mode: the selector is validated before any query runs, and the export cap governs.
       const format = exportSpec ? readExportFormat(parsed, exportSpec) : undefined;
-      if (exportSpec && format !== undefined && isExportCountFlag(parsed["withCount"])) throw exportWithCountError();
+      if (format !== undefined && format !== "json" && isExportCountFlag(parsed["withCount"])) throw exportWithCountError();
       const reportPage = exportSpec && format !== undefined
         ? parseExportPage(parsed, exportSpec.maxRows)
         : isReport ? parseReportPage(parsed, reportMaxRows) : undefined;
@@ -246,24 +246,25 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
       }
       const rows = fetched.map(toWire);
 
+      let total: number | undefined;
+      if (withCount) {
+        // Count query: same WHERE, no limit/offset/orderBy.
+        let cq = db.select({ c: count() }).from(view);
+        if (combinedWhere) cq = cq.where(combinedWhere);
+        const countRow = (await cq)[0] as { c: number } | undefined;
+        total = countRow?.c ?? 0;
+      }
       if (exportSpec && format !== undefined) {
         // Render first: a writer that throws must not leave download headers on the 500.
         // A Buffer, not a string: Fastify appends "; charset=utf-8" to a string body's
         // application/json, and the contract pins the content type exactly.
-        const body = Buffer.from(renderExport(exportSpec, format, rows as Record<string, unknown>[]), "utf8");
+        const body = Buffer.from(renderExport(exportSpec, format, rows as Record<string, unknown>[], total), "utf8");
         reply
           .header("content-disposition", exportContentDisposition(path, format))
           .header("content-type", EXPORT_CONTENT_TYPES[format]);
         return body;
       }
-      if (!withCount) return rows;
-
-      // Count query: same WHERE, no limit/offset/orderBy.
-      let cq = db.select({ c: count() }).from(view);
-      if (combinedWhere) cq = cq.where(combinedWhere);
-      const countRow = (await cq)[0] as { c: number } | undefined;
-      const total = countRow?.c ?? 0;
-      return { rows, total };
+      return total === undefined ? rows : { rows, total };
     } catch (err) {
       if (err instanceof ReportTooLargeError) {
         reply.code(400).send({ error: "report_too_large", maxRows: err.maxRows });

examples/advanced-modeling/codegen/runtime/drizzle-fastify/report-export.ts

@@ -70,10 +70,10 @@ export function readExportFormat(query: Record<string, unknown>, spec: ReportExp
 }
 
 /**
- * Whether `withCount` is set, for the `export_with_count` refusal. Wider than the list route's
- * own flag (`1`): the contract says "truthy", and a client that sends `withCount=true` to an export
- * must be told it cannot have a count rather than silently get the file. The list route's
- * flag is unchanged.
+ * Whether `withCount` is set, for the `export_with_count` refusal of a CSV or XML export. Wider
+ * than the list route's own flag (`1`): the contract says "truthy", and a client that sends
+ * `withCount=true` to a CSV export must be told it cannot have a count rather than silently get
+ * the file. The list route's flag is unchanged, and a JSON export reads that one.
  */
 export function isExportCountFlag(v: unknown): boolean {
   if (v === undefined || v === null) return false;
@@ -82,11 +82,11 @@ export function isExportCountFlag(v: unknown): boolean {
   return s === "1" || s === "true";
 }
 
-/** `export_with_count`: an export has no `{ rows, total }` envelope, JSON included. */
+/** `export_with_count`: a CSV or XML export has no `{ rows, total }` envelope. */
 export function exportWithCountError(): ReportExportError {
   return new ReportExportError(
-    { error: "export_with_count", message: "withCount cannot be combined with format; an export has no { rows, total } envelope." },
-    "withCount cannot be combined with format.",
+    { error: "export_with_count", message: "withCount cannot be combined with format=csv or format=xml; only JSON carries the { rows, total } envelope." },
+    "withCount cannot be combined with format=csv or format=xml.",
   );
 }
 
@@ -124,9 +124,12 @@ export function exportContentDisposition(path: string, format: ExportFormat): st
   return `attachment; filename="${segment}.${format}"`;
 }
 
-/** The response body of an export. JSON is the list route's array, serialized as `JSON.stringify` does. */
-export function renderExport(spec: ReportExportSpec, format: ExportFormat, rows: ExportRows): string {
-  if (format === "json") return JSON.stringify(rows);
+/**
+ * The response body of an export. JSON is the list route's own body, serialized as
+ * `JSON.stringify` does: the array, or `{ rows, total }` when the request asked for a count.
+ */
+export function renderExport(spec: ReportExportSpec, format: ExportFormat, rows: ExportRows, total?: number): string {
+  if (format === "json") return JSON.stringify(total === undefined ? rows : { rows, total });
   const write = spec[format];
   if (write === undefined) throw new Error(`report export: no ${format} writer is wired.`);
   return write(rows);