@uniweb/build 0.61.0 → 0.62.0

package/src/uwx/registry-package.js

@@ -26,7 +26,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { toDataSchemaDeclaration } from './data-schema.js'
+import { toDataSchemaDeclaration, SHORTHAND_SECTION } from './data-schema.js'
 import { checkFoundationName, splitFoundationName } from '../foundation-name.js'
 
 const FOUNDATION_SCHEMA = '@uniweb/foundation-schema'
@@ -231,8 +231,8 @@ function makeOptionsResolver(dataSchemas, scoped) {
 }
 
 function itemBearingSectionName(normalized, ref) {
-  // fields-form → the synthesized single section (named by the ref's short segment)
-  if (normalized.fields) return String(ref).split('/').pop()
+  // fields-form → the shorthand's one section, always named `brief`
+  if (normalized.fields) return SHORTHAND_SECTION
   // sections-form → the first item-bearing (single/multi) section
   for (const [name, sec] of Object.entries(normalized.sections || {})) {
     const kind = sec.kind || 'single'

package/src/uwx/sync-package.js

@@ -33,6 +33,18 @@ const SITE_ENTITY_KEY = 'site-content'
 
 const cacheKey = (entity) => `${entity.model} ${entity.id}`
 
+// The folder's placements without the records a push leaves out — `{ kind: 'ref' }` leaves
+// naming them by `$entityId`, inside any branch.
+function withoutRecords(nodes, ids) {
+  if (!ids.size) return nodes
+  const out = []
+  for (const node of nodes || []) {
+    if (node?.kind === 'branch') out.push({ ...node, $children: withoutRecords(node.$children, ids) })
+    else if (!ids.has(node?.$entityId)) out.push(node)
+  }
+  return out
+}
+
 // Attach the push gate's optimistic-concurrency token to an entity, keyed by the
 // BACKEND uuid in its document body (`$uuid`). A never-synced entity has no
 // `$uuid` and therefore no base — correctly unconditional, since there is no
@@ -253,7 +265,11 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  *   records: { buffer, entityCount, index, models }|null,
  *   hashes: Object<string,string>, warnings: string[], refusals: string[],
  *   skipped: number, schemaless: Array<{name: string, model: string}>,
- *   localAssets: string[], applied: object }>}
+ *   localAssets: string[], applied: object,
+ *   waiting: Array<{id: string, model: string, slug: string, held: boolean, pending: object[]}> }>}
+ *   `waiting` lists the records whose references name a record this backend has not
+ *   minted yet — sent without them, or held back. A caller that sends pushes again
+ *   once this push has been applied (`records.js::encodeReference`).
  *   `refusals` names the records that cannot be sent as written, one line each
  *   (`records.js::recordsToEntities`). A caller that submits must not submit while
  *   any is present: the backend would refuse the records lane — or, for a record
@@ -300,10 +316,43 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   })
   const warnings = [...col.warnings, ...(col.folder?.warnings ?? [])]
 
+  // ⭐ RECORDS WAITING FOR A REFERENCE (`records.js::encodeReference`). A record whose
+  // reference names a record this backend has not minted yet cannot name it on the wire,
+  // so this push sends what it can and the next pass completes it (the CLI's
+  // `pushInPasses`):
+  //   · new, and nothing it waits for is required → sent now without those references,
+  //     so after one pass every record exists, whatever refers to what;
+  //   · new, and a required reference waits → HELD and placed nowhere: it cannot be
+  //     created without it;
+  //   · already on this backend → HELD, left as it is there: sent without a reference it
+  //     has, it would lose that reference until the next pass.
+  // A held record is not sent and keeps the hash last banked for it, so the next pass
+  // sees it as changed.
+  const held = new Set()
+  const unplaced = new Set()
+  for (const e of col.entities) {
+    if (!e.pending?.length) continue
+    if (e.uuid) held.add(e.id)
+    else if (e.pending.some((p) => p.required)) {
+      held.add(e.id)
+      unplaced.add(e.id)
+    }
+  }
+  const waiting = col.entities
+    .filter((e) => e.pending?.length)
+    .map((e) => ({ id: e.id, model: e.model, slug: e.slug, held: held.has(e.id), pending: e.pending }))
+  const placedEntities = []
+  const placedIndex = []
+  col.entities.forEach((e, i) => {
+    if (unplaced.has(e.id)) return
+    placedEntities.push(e)
+    placedIndex.push(col.index[i])
+  })
+
   // The folder rides over the FULL record set (before filtering) so its references
   // are complete — new records by `$ref`, already-minted ones by `entry: <uuid>`.
   const folder = buildFolderEntity({
-    recordEntities: col.entities,
+    recordEntities: placedEntities,
     ...(sourceLocale ? { sourceLocale } : {}),
     // ⭐ Every record in the directory, at the top of the folder or in the
     // sub-folder `folder.yml` places it in — and NOTHING when there is no folder to
@@ -311,7 +360,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // non-empty tree: a `folder.yml` whose folders hold only records that resolved
     // no schema is a tree of empty branches, and sending it would replace the
     // backend's folder with them (measured on the `dynamic` template, 2026-09-21).
-    folderNodes: col.sendFolder === true ? (col.folder?.nodes ?? []) : [],
+    folderNodes: col.sendFolder === true ? withoutRecords(col.folder?.nodes ?? [], unplaced) : [],
     // ⛔ Whether the file side HAS a folder to state (`records.js::sendsFolder`) —
     // not whether it holds anything. A site with no records directory sends none
     // and leaves the backend's alone; an empty directory sends an empty folder,
@@ -469,7 +518,17 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   // changed() has side effects (hashes/skipped), so evaluate every entity exactly
   // once, in a stable order: folder, then each record.
   const folderChanged = folder ? changed(folder) : false
-  const recordChanged = col.entities.map((e, i) => ({ entity: e, index: col.index[i], changed: changed(e) }))
+  // A held record keeps its last banked hash — it was not sent (see `held` above).
+  const keepBanked = (entity) => {
+    const key = cacheKey(entity)
+    if (priorHashes[key] !== undefined) hashes[key] = priorHashes[key]
+    return false
+  }
+  const recordChanged = placedEntities.map((e, i) => ({
+    entity: e,
+    index: placedIndex[i],
+    changed: held.has(e.id) ? keepBanked(e) : changed(e),
+  }))
   const changedRecords = recordChanged.filter((r) => r.changed)
 
   let records = null
@@ -523,6 +582,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
 
   return {
     siteContent, records, siteContentUuid, hashes, warnings, skipped,
+    // Records waiting for a reference's record — see `held` above. Non-empty ⇒ the caller
+    // pushes again once this push has been applied.
+    waiting,
     refusals: col.refusals || [],
     schemaless: col.schemaless, localAssets, applied,
     // { stamped, unknown } when identity was applied; null when the caller passed

package/src/uwx/uuid.js

@@ -42,3 +42,10 @@ export function mintUuidV7() {
     hex.slice(20)
   )
 }
+
+const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** Is this a uuid (any version), as the exchange writes one? */
+export function isUuid(value) {
+  return typeof value === 'string' && UUID_SHAPE.test(value)
+}

package/src/validate-data.js

@@ -31,7 +31,8 @@ import { YAML_OPTIONS } from './utils/yaml-schema.js'
 import { queryNameFromUrl, declaredKeys, fillDeclaredKeys, fetchLevels, pageRouteQuery } from '@uniweb/core'
 import { parentRouteOf } from '@uniweb/core/route-match'
 
-import { validateItem, validateBound, flatRecordFields, rootListSection } from '@uniweb/schemas/conform'
+import { validateItem, validateRecordFile, validateBound, contentBodyField, rootListSection, referencesOf } from '@uniweb/schemas/conform'
+import { isUuid } from './uwx/uuid.js'
 import { validateAndNormalizeSchema, buildDataSchemaMap } from './resolve-data-schema.js'
 
 // The pure checker, re-exported so `@uniweb/build/validate` stays the one import
@@ -41,7 +42,6 @@ export { validateItem, isStaticallyCheckable } from '@uniweb/schemas/conform'
 import { buildSchema } from './schema.js'
 import { resolveRecordsDir, readEntityPool, groupPoolBySchema } from './site/entity-pool.js'
 import { readEntityFile } from './uwx/entity-source.js'
-import { isContentBodyField } from './uwx/data-schema.js'
 import { toFetchList } from './site/data-fetcher.js'
 import { resolveFoundationSrcPath } from './utils/foundation-source-root.js'
 import { collectSiteContent } from './site/content-collector.js'
@@ -310,9 +310,16 @@ function listViolation(finding, label, base) {
  * Check the records in the records directory that pass 2 did not, each against the
  * data schema its folder names (`records/member/` → `@/member`).
  *
- * A record is read the way a push reads it (`uwx/entity-source.js`), and a markdown
- * record's body is the value of its schema's content body field unless its
- * frontmatter sets one — which is what a push sends it as (`uwx/records.js`).
+ * A record is checked as its FILE holds it (`validateRecordFile`) — read the way a push
+ * reads it (`uwx/entity-source.js`), a markdown body in its schema's content body field
+ * unless the file sets that field, which is what a push sends it as (`uwx/records.js`).
+ * So a finding names the path an author edits (`article.title`), and a field written in
+ * the retired flat form is reported under the rule `section`. Pass 2 checks the records
+ * a section receives, in the shape it receives them (`validateItem`).
+ *
+ * Every record's references are checked here too, whichever pass checked the rest: one
+ * that names no record of its schema is reported under the rule `ref`, since a push
+ * cannot send it.
  *
  * A folder whose schema resolves to nothing is left out in silence: its records are
  * schema-less, delivered as files, and the push says so itself.
@@ -322,11 +329,14 @@ function listViolation(finding, label, base) {
 async function validateRecordFiles(siteRoot, { srcDir, dataSchemas, paths, checked }) {
   const out = { violations: [], setupErrors: [], schemas: new Set(), checked: 0 }
   const pool = await readEntityPool(siteRoot, { dir: resolveRecordsDir(siteRoot, paths).rel })
+  // Every record is read first: a reference names a record of another schema by its
+  // name — its file's, or its `slug:` — or by the id its file carries.
+  const read = []
+  const names = new Map() // schema (as its folder names it) → the names and ids of its records
   for (const [ref, entities] of groupPoolBySchema(pool.entities)) {
     const schema = await schemaForRecords(ref, { srcDir, dataSchemas })
-    // An entity of a list-rooted schema too: it holds the list under its section's key.
-    // ⛔ Until 2026-09-24 such a folder was skipped here without a word.
-    if (!schema) continue
+    const known = names.get(ref) ?? new Set()
+    names.set(ref, known)
     for (const pooled of entities) {
       let records
       try {
@@ -336,13 +346,39 @@ async function validateRecordFiles(siteRoot, { srcDir, dataSchemas, paths, check
         continue
       }
       for (const r of records) {
-        if (!r.slug || checked.has(recordKey(ref, r.slug))) continue
+        if (r.slug) known.add(String(r.slug))
+        if (typeof r.data?.$uuid === 'string') known.add(r.data.$uuid)
+      }
+      // An entity of a list-rooted schema too: it holds the list under its section's key.
+      // ⛔ Until 2026-09-24 such a folder was skipped here without a word.
+      if (schema) read.push({ ref, schema, pooled, records })
+    }
+  }
+  for (const { ref, schema, pooled, records } of read) {
+    for (const r of records) {
+      if (!r.slug) continue
+      const record = withBody(schema, r)
+      if (!checked.has(recordKey(ref, r.slug))) {
         out.checked++
         out.schemas.add(ref)
-        for (const finding of validateItem(schema, withBody(schema, r))) {
+        for (const finding of validateRecordFile(schema, record)) {
           out.violations.push({ file: pooled.relPath, schema: ref, item: r.slug, users: [], ...finding })
         }
       }
+      // ⭐ A reference must name a record — a push refuses one that does not. A uuid is
+      // left alone: it may be a record the backend holds and this project does not.
+      for (const { path, ref: target, value } of referencesOf(schema, record)) {
+        if (typeof value !== 'string' || isUuid(value) || names.get(target)?.has(value)) continue
+        out.violations.push({
+          file: pooled.relPath,
+          schema: ref,
+          item: r.slug,
+          users: [],
+          field: path,
+          rule: 'ref',
+          message: `names "${value}", and no record of ${target} is called that`,
+        })
+      }
     }
   }
   return out
@@ -359,13 +395,20 @@ async function schemaForRecords(ref, { srcDir, dataSchemas }) {
   }
 }
 
-// A record as a push sends it: a markdown body fills the schema's content body field
-// when the frontmatter does not set it.
+// A record as its file holds it, with a markdown body in the schema's content body field
+// — under its section, in a file written by section — when the file does not set it.
 function withBody(schema, r) {
   const record = { ...(r.data || {}) }
   if (typeof r.body !== 'string' || r.body.trim() === '') return record
-  const key = Object.entries(flatRecordFields(schema) || {}).find(([, f]) => isContentBodyField(f))?.[0]
-  if (key && record[key] === undefined) record[key] = r.body
+  const target = contentBodyField(schema)
+  if (!target) return record
+  if (!target.fileSection) {
+    if (record[target.key] === undefined) record[target.key] = r.body
+    return record
+  }
+  const held = record[target.fileSection]
+  if (held != null && (typeof held !== 'object' || Array.isArray(held))) return record
+  if (held?.[target.key] === undefined) record[target.fileSection] = { ...(held || {}), [target.key]: r.body }
   return record
 }