@uniweb/build 0.61.0 → 0.62.0

package/src/uwx/backfill.js

@@ -32,7 +32,8 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { proseMirrorToMarkdown } from '@uniweb/content-writer'
 import { parseFrontmatter } from './entity-source.js'
-import { isProseMirrorField, isContentBodyField } from './data-schema.js'
+import { isProseMirrorField } from './data-schema.js'
+import { recordFileLayout, contentBodyTarget } from './record-layout.js'
 import { unwrapLocalizedContent } from './locale-sync.js'
 import { parseBibtex, exportBibtex } from '@citestyle/bibtex'
 
@@ -213,28 +214,32 @@ export function unwrapLocalizedList(value, sourceLocale) {
   return unwrapLocalized(value, sourceLocale)
 }
 
-// The brief is the section marked `brief: true` in the declaration's sections map
-// (the sections-tree has no schema-level `brief:` back-reference). Returned with
-// its name attached (the map key) so callers can key the document by it.
-function briefSectionOf(declaration) {
-  const entry = Object.entries(declaration?.sections || {}).find(([, s]) => s && s.brief === true)
-  return entry ? { name: entry[0], ...entry[1] } : null
-}
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
 
 /**
  * Render an entity `document` a pull brought back to its source-file authoring shape
  * — the file becomes a projection of the backend's state, which is what a pull is
- * (`writeRecordFile`, `records-project.js`). A push never uses it (header ⛔). For a
- * flat/brief entity: the entity `$uuid` + the brief section's fields (localized unwrapped,
- * date/scalars verbatim), with the brief record's own `$uuid` DROPPED (the backend
- * matches a single-section item by singularity) and `$schema`/`$id`/`$meta` omitted.
- * A disabled entity (`$disabled: true`) writes `draft: true`, and an enabled one writes
- * no `draft:` at all.
+ * (`writeRecordFile`, `records-project.js`). A push never uses it (header ⛔).
+ *
+ * The file takes its schema's layout (`./record-layout.js`), the one the push reads:
+ * FLAT for a schema with one top-level section holding one record — that section's
+ * fields at the top — and BY SECTION otherwise, every section the document holds under
+ * its own name: an object for a single section, a list of records for a `many` one, a
+ * self-nesting record's `$children` written back as `children:`. Values are decoded by
+ * their declaration at every depth (localized unwrapped to the source locale, a
+ * ProseMirror doc to markdown, dates and scalars verbatim). Every record's own `$uuid`
+ * is dropped — the backend matches a single section's record by singularity — and
+ * `$schema`/`$id`/`$meta` are omitted; the entity's `$uuid` leads. A disabled entity
+ * (`$disabled: true`) writes `draft: true`, and an enabled one writes no `draft:`.
  * For markdown, the content body field becomes the body; for YAML/JSON it stays a field.
  *
+ * ⛔ Until 2026-09-24 this wrote the BRIEF section alone, flat. Every other section was
+ * dropped from the file — a pulled `@std/article` markdown record came back with an
+ * empty body, its `article_body` gone — and nothing said so.
+ *
  * @param {object} params
- * @param {object} params.document     - pulled `{ $uuid, $schema, <brief>: {…} }`
- * @param {object} params.declaration  - the Model declaration (`brief` + `sections`)
+ * @param {object} params.document     - a pulled `{ $uuid, $schema, <section>: … }`
+ * @param {object} params.declaration  - the data schema's declaration (`sections`)
  * @param {string} params.format       - 'yaml' | 'json' | 'md'
  * @param {string} [params.sourceLocale]
  * @param {object} [params.collector]  - translation collector; target locales of
@@ -244,58 +249,116 @@ function briefSectionOf(declaration) {
  * @param {string} [params.freeformRelPath] - the free-form path for this record's
  *        content body (buildFreeformRecordPath); lets a target-locale full-doc
  *        body be written under locales/freeform/{locale}/ instead of being dropped.
+ * @param {(model: string, uuid: string) => string|null} [params.refName] - the name a
+ *        referenced record goes by in the project, for a reference's uuid; a reference
+ *        it has no name for is written as the uuid.
  * @returns {string} the source-file text
  */
-export function renderEntityDocument({ document, declaration, format, sourceLocale = 'en', collector, freeformRelPath }) {
-  const brief = briefSectionOf(declaration)
-  const section = brief ? document?.[brief.name] : null
-  if (!brief || !section || typeof section !== 'object') {
-    throw new Error('uwx/render: document has no resolvable brief section')
+export function renderEntityDocument({ document, declaration, format, sourceLocale = 'en', collector, freeformRelPath, refName }) {
+  const layout = recordFileLayout(declaration)
+  if (layout.sections.length === 0) {
+    throw new Error('uwx/render: the data schema declares no sections')
+  }
+  // ⛔ An entity holding NONE of its schema's sections — what a partly applied push
+  // left, before the backend's push became one transaction — is not written: rendered,
+  // it would replace the author's record with an empty one. The caller skips it.
+  if (!layout.sections.some(([name]) => document?.[name] != null)) {
+    throw new Error("uwx/render: the entity holds none of its data schema's sections — nothing to write")
   }
-  const fields = brief.fields || {}
-  // The body target is the CONTENT field — a markup `text` field (raw source
-  // string) or a `format: prosemirror` json field (a ProseMirror doc on the wire).
-  const contentKey = Object.entries(fields).find(([, f]) => isContentBodyField(f))?.[0]
+  // Markdown: the content body field, wherever its single section is, becomes the body.
+  const { target } = contentBodyTarget(declaration)
+  const dec = { sourceLocale, collector, freeformRelPath, refName, bodyAt: format === 'md' ? target : null, body: '' }
 
   const record = {}
-  if (document.$uuid) record.$uuid = document.$uuid
-  let body = ''
-  for (const [key, field] of Object.entries(fields)) {
-    const raw = section[key]
-    if (raw === undefined) continue
-
-    // A `format: prosemirror` field is a ProseMirror doc (or localized doc+maps)
-    // on the wire → markdown on disk. unwrapLocalizedContent yields the source doc
-    // and captures target-locale structural maps into the collector.
-    if (isProseMirrorField(field)) {
-      const sourceDoc = field.localized ? unwrapLocalizedContent(raw, sourceLocale, collector, freeformRelPath) : raw
-      const md = sourceDoc ? proseMirrorToMarkdown(sourceDoc) : ''
-      if (format === 'md' && key === contentKey) body = md
-      else record[key] = md
-      continue
-    }
-
-    // Capture target-locale translations of localized SCALAR fields (not the
-    // content body) into the collector when one is supplied.
-    if (field.localized && key !== contentKey) collector?.add(raw)
-    const value = field.localized ? unwrapLocalized(raw, sourceLocale) : raw
-    if (format === 'md' && key === contentKey) {
-      body = typeof value === 'string' ? value : String(value ?? '')
-      continue
+  if (document?.$uuid) record.$uuid = document.$uuid
+  if (layout.flat) {
+    const [name, def] = layout.sections[0]
+    Object.assign(record, decodeRecord(def.fields, document?.[name], dec, name))
+  } else {
+    for (const [name, def] of layout.sections) {
+      const value = document?.[name]
+      if (value == null) continue
+      if (def.multiple === true) {
+        const list = decodeList(def, value, dec)
+        if (list.length) record[name] = list
+      } else {
+        const data = decodeRecord(def.fields, value, dec, name)
+        if (Object.keys(data).length) record[name] = data
+      }
     }
-    record[key] = value
   }
   // ⭐ A DISABLED ENTITY IS A DRAFT ON THE FILE SIDE. It is kept in the folder and never
   // publicly delivered, which is exactly what `draft: true` means. An enabled entity
   // carries no key and writes no `draft:`, so a record re-enabled on the backend
   // comes back without the line.
-  if (document.$disabled === true) record.draft = true
+  if (document?.$disabled === true) record.draft = true
 
   if (format === 'json') return JSON.stringify(record, null, 2) + '\n'
-  if (format === 'md') return `---\n${yaml.dump(record)}---\n${body}`
+  if (format === 'md') return `---\n${yaml.dump(record)}---\n${dec.body}`
   return yaml.dump(record) // yaml / yaml
 }
 
+// One record of a section, its declared fields in declared order. `sectionName` is the
+// top-level section the record belongs to, so the content body can be found; null below.
+function decodeRecord(fields, value, dec, sectionName) {
+  const out = {}
+  if (!isPlainObject(value)) return out
+  for (const [key, field] of Object.entries(fields || {})) {
+    const raw = value[key]
+    if (raw === undefined) continue
+    if (field?.type === 'section') {
+      out[key] = field.multiple === true ? decodeList(field, raw, dec) : decodeRecord(field.fields, raw, dec, null)
+      continue
+    }
+    const isBody = Boolean(dec.bodyAt) && sectionName === dec.bodyAt.section && key === dec.bodyAt.key
+    const decoded = decodeLeaf(raw, field, dec, isBody)
+    if (isBody) dec.body = typeof decoded === 'string' ? decoded : String(decoded ?? '')
+    else out[key] = decoded
+  }
+  return out
+}
+
+// The records of a `many` section; a self-nesting one's `$children` nest back under
+// `children:`, the reserved key the push reads them from.
+function decodeList(def, value, dec) {
+  if (!Array.isArray(value)) return []
+  return value.map((item) => {
+    const out = decodeRecord(def.fields, item, dec, null)
+    if (def.self_nesting === true && Array.isArray(item?.$children) && item.$children.length) {
+      out.children = decodeList(def, item.$children, dec)
+    }
+    return out
+  })
+}
+
+// A leaf's authored value. A localized SCALAR's target locales are captured into the
+// collector (the content body's are captured by `unwrapLocalizedContent`, with its
+// free-form path); a list of localized values is unwrapped element by element.
+function decodeLeaf(raw, field, dec, isBody) {
+  if (field?.type === 'entity_ref') return decodeReference(raw, field, dec)
+  if (isProseMirrorField(field)) {
+    const sourceDoc = field.localized
+      ? unwrapLocalizedContent(raw, dec.sourceLocale, dec.collector, isBody ? dec.freeformRelPath : undefined)
+      : raw
+    return sourceDoc ? proseMirrorToMarkdown(sourceDoc) : ''
+  }
+  if (!field?.localized) return raw
+  if (Array.isArray(raw)) {
+    if (!isBody) for (const item of raw) dec.collector?.add(item)
+    return unwrapLocalizedList(raw, dec.sourceLocale)
+  }
+  if (!isBody) dec.collector?.add(raw)
+  return unwrapLocalized(raw, dec.sourceLocale)
+}
+
+// A reference comes back as the backend's uuid; the file names its record by handle — the
+// name the site's folder gives it (`refName`), which is what a push resolves back to that
+// uuid. A record the folder does not hold keeps its uuid, and a push sends it as it is.
+function decodeReference(raw, field, dec) {
+  const one = (v) => (typeof v === 'string' && dec.refName ? dec.refName(field.model, v) ?? v : v)
+  return Array.isArray(raw) ? raw.map(one) : one(raw)
+}
+
 /**
  * Back-fill the sync response into the source files. Correlation is by **`index`**
  * — `finalized[i].index` is the 0-based position of the entity in the submitted

package/src/uwx/data-schema.js

@@ -91,7 +91,7 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
 
   const { sections, brief } = normalized.sections
     ? lowerSectionsForm(normalized.sections, resolve, optResolve)
-    : lowerFieldsForm(normalized.fields || {}, shortName(name), resolve, optResolve)
+    : lowerFieldsForm(normalized.fields || {}, resolve, optResolve)
 
   // The model-level sort axis is inline: `sort_date: true` on the brief's named
   // date field (replaces the old schema-level `sort_date_field` back-reference).
@@ -139,13 +139,22 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
 
 // --- shapes ------------------------------------------------------------------
 
-// The `fields:` shorthand: a flat field set is ONE single brief section named the
-// model short-name. Our producer-side sugar — the registry's root is always
-// `sections:`; this expands to it.
-function lowerFieldsForm(fields, sectionName, resolve, optResolve) {
+// The `fields:` shorthand: a flat field set is ONE single section, named `brief` and
+// marked `brief: true` — exactly `sections: { brief: { brief: true, fields } }`. Our
+// producer-side sugar — the registry's root is always `sections:`; this expands to it.
+//
+// ⭐ THE NAME IS FIXED, NOT DERIVED (2026-09-22 [Diego]: "We assume it is single section,
+// `brief: true` and named `brief`"). It was the schema's short name until then —
+// `@std/person` → `person` — a name nobody wrote, stored on every entity and in every
+// `item_ref` path, that a schema growing into the `sections:` form had to reuse exactly
+// with nothing to say so. A `sections:` schema still names its own sections; `brief` is
+// only the recommended name for its card.
+export const SHORTHAND_SECTION = 'brief'
+
+function lowerFieldsForm(fields, resolve, optResolve) {
   return {
-    sections: { [sectionName]: lowerSection({ kind: 'single', brief: true, fields }, resolve, optResolve) },
-    brief: sectionName,
+    sections: { [SHORTHAND_SECTION]: lowerSection({ kind: 'single', brief: true, fields }, resolve, optResolve) },
+    brief: SHORTHAND_SECTION,
   }
 }
 
@@ -460,10 +469,6 @@ function sectionAttrsFromField(field) {
   return out
 }
 
-function shortName(name) {
-  return String(name).split('/').pop()
-}
-
 // `@/x` resolves into the schema's own org; other scopes pass through.
 function defaultResolver(ownName) {
   const slash = ownName.indexOf('/')

package/src/uwx/project-writer.js

@@ -380,9 +380,11 @@ export function writeThemeFile(siteRoot, theme) {
  * @param {object} [opts.collector] - translation collector for localized scalar fields
  * @param {string} [opts.freeformRelPath] - free-form path for this record's content
  *        body (so a target-locale full-doc body is captured for locales/freeform/)
+ * @param {(model: string, uuid: string) => string|null} [opts.refName] - the name a
+ *        referenced record goes by, so a reference is written as that name
  * @returns {'updated'|'unchanged'}
  */
-export function writeRecordFile({ filePath, document, declaration, format, sourceLocale = 'en', collector, freeformRelPath }) {
-  const text = renderEntityDocument({ document, declaration, format, sourceLocale, collector, freeformRelPath })
+export function writeRecordFile({ filePath, document, declaration, format, sourceLocale = 'en', collector, freeformRelPath, refName }) {
+  const text = renderEntityDocument({ document, declaration, format, sourceLocale, collector, freeformRelPath, refName })
   return writeIfChanged(filePath, text)
 }

package/src/uwx/record-layout.js

@@ -0,0 +1,61 @@
+// How one record of a data schema is written in its file — the layout the push reads
+// and the pull writes, read off the schema's declaration (`toDataSchemaDeclaration`).
+//
+// ⭐ FLAT ONLY WHEN THE SCHEMA HAS ONE TOP-LEVEL SECTION HOLDING ONE RECORD — the
+// `fields:` shorthand, or a `sections:` schema whose only section is a single one. The
+// file's keys are then that section's fields, and nothing is lost either way.
+//
+// ⭐ EVERY OTHER SCHEMA IS WRITTEN BY SECTION: each top-level section under its own
+// name — an object for a single section, a list of records for a `many` one, an object
+// of child sections for a binder. That is the stored entity's own shape
+// (docs/reference/entity-content.md), so a push sends it and a pull writes it back
+// without a mapping in between. A schema whose only section is `many` (`@std/nav`) is
+// written this way too — `items: [...]` — since a file whose top level is a list holds
+// several records, not one.
+//
+// ⛔ THE FLAT FORM FOR A MULTI-SECTION SCHEMA IS RETIRED (2026-09-22 [Diego]: "we can
+// discontinue the shorthands for multi-section Models"). It matched a file's keys to
+// fields across sections by name, and sections are namespaces: a field name two
+// sections share got one value in both, a `many` section had no place at all, and a
+// pull — writing back only what it could place — returned a record with nothing but its
+// brief. Measured before the change: a pulled `@std/article` markdown record came back
+// with an empty body.
+
+import { isContentBodyField } from './data-schema.js'
+
+/**
+ * @param {object} declaration - `{ name, sections }`
+ * @returns {{ flat: boolean, sections: Array<[string, object]>, brief: string|null }}
+ *   `sections` — the top-level sections in declared order; `brief` — the section the
+ *   declaration marks `brief: true`, or null when it marks none.
+ */
+export function recordFileLayout(declaration) {
+  const sections = Object.entries(declaration?.sections || {}).filter(([, s]) => s && typeof s === 'object')
+  const flat = sections.length === 1 && sections[0][1].multiple !== true
+  const brief = sections.find(([, s]) => s.brief === true)?.[0] ?? null
+  return { flat, sections, brief }
+}
+
+/**
+ * The schema's CONTENT body field — the one a `.md` record's markdown body fills: a
+ * markup `text` field (`format: markdown|html`) or a `format: prosemirror` json field,
+ * declared directly on a top-level single section — the brief or another, like
+ * `@std/article`'s `article_body.content`. The first in declared order.
+ *
+ * ⛔ Not the brief's alone. Until 2026-09-24 the pull and the per-locale body override
+ * looked only in the brief, while the push looked in every single section, so a body
+ * declared outside the brief was pushed and then neither translated nor pulled back.
+ *
+ * @param {object} declaration
+ * @returns {{ target: { section: string, key: string, field: object }|null, count: number }}
+ */
+export function contentBodyTarget(declaration) {
+  const matches = []
+  for (const [section, def] of recordFileLayout(declaration).sections) {
+    if (def.multiple === true) continue
+    for (const [key, field] of Object.entries(def.fields || {})) {
+      if (isContentBodyField(field)) matches.push({ section, key, field })
+    }
+  }
+  return { target: matches[0] || null, count: matches.length }
+}

package/src/uwx/records-project.js

@@ -18,11 +18,12 @@
 //     fact about it.
 //   - an existing local file carrying the same `$uuid` is re-rendered in place;
 //     otherwise a new single-record file is placed at `<slug>.<ext>`, its format
-//     matched to the schema folder's existing files, else markdown when the Model's
-//     brief has a content body field, else YAML.
+//     matched to the schema folder's existing files, else markdown when the schema
+//     has a content body field, else YAML.
 //
-// Field rendering reuses renderEntityDocument (via writeRecordFile) — localized
-// unwrap, date handling, content-body→body are already inverted there. Asset paths
+// Field rendering reuses renderEntityDocument (via writeRecordFile), which writes the
+// record in its schema's layout — flat, or by section — with localized unwrap, date
+// handling and content-body→body inverted. Asset paths
 // are restored before it runs (`restoreAssetRefs`), as the content lane does.
 //
 // Deferred: array-form & BibTeX multi-record files (a pulled record is placed as
@@ -43,7 +44,7 @@ import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './proje
 import { defaultSchema, deferredFromSchema, foundationDataSchemas } from './queries-config.js'
 import { poolDirsForSchema, resolveRecordsDir } from '../site/entity-pool.js'
 import { folderYmlPath } from '../site/records-config.js'
-import { isContentBodyField } from './data-schema.js'
+import { contentBodyTarget } from './record-layout.js'
 import { unresolveSelfScope, refuseOrgOption } from './self-scope.js'
 import { parseCatalogRef } from '../site/foundation-ref.js'
 import { unwrapLocalized } from './backfill.js'
@@ -96,8 +97,8 @@ export function findRecordFileByUuid(poolDir, uuid) {
 }
 
 // The format to give a NEW record file in a collection: match the collection's
-// existing single-record files, else markdown when the Model's brief carries a
-// content body field (so the body has a home), else YAML.
+// existing single-record files, else markdown when the schema has a content body field
+// (so the body has a home), else YAML.
 function defaultFormat(poolDir, declaration) {
   if (existsSync(poolDir)) {
     for (const entry of readdirSync(poolDir)) {
@@ -106,14 +107,9 @@ function defaultFormat(poolDir, declaration) {
       if (format) return format
     }
   }
-  return briefHasContentBody(declaration) ? 'md' : 'yaml'
-}
-
-// Whether the declaration's brief section declares a content body field — a markup
-// `text` field or a `format: prosemirror` json field (the md-body target).
-function briefHasContentBody(declaration) {
-  const brief = Object.values(declaration?.sections || {}).find((s) => s && s.brief === true)
-  return Object.values(brief?.fields || {}).some((f) => isContentBodyField(f))
+  // ⛔ This asked the brief alone until 2026-09-24, so a pulled `@std/article` — its
+  // body in `article_body` — was placed as YAML, the body a field.
+  return contentBodyTarget(declaration).target ? 'md' : 'yaml'
 }
 
 // Build `uuid → { collection, slug }` from the folder document's ref leaves. The
@@ -137,7 +133,8 @@ function indexFolder(folderDoc) {
       } else if (node?.kind === 'ref' && node.entry) {
         // `entry` is `{ schema, entity: <uuid> }`; tolerate a bare uuid defensively.
         const uuid = typeof node.entry === 'object' ? node.entry.entity : node.entry
-        if (uuid) byUuid.set(uuid, { folderPath, slug: node.name })
+        const schema = typeof node.entry === 'object' ? node.entry.schema : undefined
+        if (uuid) byUuid.set(uuid, { folderPath, slug: node.name, schema })
       }
     }
   }
@@ -223,7 +220,7 @@ const DECL_WIRE_CONSUMED = new Set([
 ])
 
 // Is this wire `deferred` exactly what the schema's brief would have derived? Compared
-// as an ORDER-INSENSITIVE set: the deriver walks `flatRecordFields`, and a round trip
+// as an ORDER-INSENSITIVE set: the deriver walks the schema's sections, and a round trip
 // through YAML and the store is not obliged to preserve that order. Comparing as a list
 // would classify a reordered-but-identical value as authored, and persist it.
 function isDerivedDeferred(d, dataSchemas) {
@@ -485,6 +482,14 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   }
 
   const folderIndex = indexFolder(folderDoc)
+  // ⭐ A REFERENCE IS WRITTEN AS THE NAME OF THE RECORD IT POINTS AT — `speaker: ada` —
+  // which is what a push resolves back to this backend's uuid. The folder names every
+  // record of the site; a reference to a record it does not hold (or holds under another
+  // Model) is written as the uuid.
+  const refName = (model, uuid) => {
+    const hit = folderIndex.get(uuid)
+    return hit?.slug && (!hit.schema || hit.schema === model) ? hit.slug : null
+  }
   // Where records land — `site.yml::paths.records`, else `records/`: the one resolver
   // the build and the push read too, so a pulled record lands where the next build
   // looks. ⛔ This wrote into the default directory until 2026-09-21, whatever the
@@ -570,7 +575,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
     const toWrite = own && own !== theirs ? { ...document, $uuid: own } : document
     let status
     try {
-      status = writeRecordFile({ filePath, document: toWrite, declaration, format, sourceLocale, collector, freeformRelPath })
+      status = writeRecordFile({ filePath, document: toWrite, declaration, format, sourceLocale, collector, freeformRelPath, refName })
     } catch (err) {
       // ⛔ A record that could not be written was not placed, so it is a SKIP, not a
       // warning: a caller that counts what it placed (the CLI's pull) must see it.