@uniweb/build 0.61.0 → 0.63.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'
@@ -157,7 +157,56 @@ function buildDataSchemaEntities(dataSchemas, scope) {
       // way; item_ref `options` get the full `@org/x/<section>` path (§10.1).
       ...toDataSchemaDeclaration(normalized, { name: scoped(ref), resolveName: scoped, resolveOptions }),
     }))
-  return { entities, scoped, org }
+  return { entities: referencedFirst(entities), scoped, org }
+}
+
+/**
+ * The data schemas in an order a backend can install one at a time: a schema another one in
+ * the package references comes BEFORE it — alphabetical otherwise, so the order is stable.
+ *
+ * ⭐ WHY. A backend installs a package's data schemas in the order they arrive, and refuses a
+ * reference to a Model it holds neither yet nor from before: measured 2026-09-25, a foundation
+ * whose `exhibit` references its own `specimen` was refused whole — *"entity_ref target
+ * `@x/specimen` matches no model declared in this fixture or registered on the host"* — because
+ * `exhibit` sorts first. Alphabetical order was right only by luck (`speaker` before `talk`).
+ *
+ * ⚠️ A CYCLE CANNOT BE ORDERED — `author` names `book` and `book` names `author` — and keeps
+ * the order the walk gives it. Whether one package may reference itself in any order is the
+ * backend's to accept; this only stops refusing what an order can fix. A schema naming ITSELF
+ * is not a dependency.
+ *
+ * @param {Array<{ name: string, sections?: object }>} entities - lowered declarations
+ * @returns {Array} the same entities, referenced ones first
+ */
+function referencedFirst(entities) {
+  const byName = new Map(entities.map((e) => [e.name, e]))
+  const targets = (entity) => {
+    const out = new Set()
+    const walk = (fields) => {
+      for (const field of Object.values(fields || {})) {
+        if (!field || typeof field !== 'object') continue
+        if (field.type === 'entity_ref') for (const m of [field.model].flat()) out.add(m)
+        // `options: '@org/x/<section>'` names a section of Model `@org/x`.
+        if (field.type === 'item_ref' && typeof field.options === 'string') {
+          out.add(field.options.split('/').slice(0, 2).join('/'))
+        }
+        if (field.type === 'section') walk(field.fields)
+      }
+    }
+    for (const section of Object.values(entity.sections || {})) walk(section.fields)
+    return [...out].filter((name) => name !== entity.name && byName.has(name)).sort()
+  }
+  const ordered = []
+  const state = new Map() // name → 'visiting' | 'done'
+  const visit = (entity) => {
+    if (state.get(entity.name)) return // done, or on the walk now — a cycle
+    state.set(entity.name, 'visiting')
+    for (const name of targets(entity)) visit(byName.get(name))
+    state.set(entity.name, 'done')
+    ordered.push(entity)
+  }
+  for (const entity of entities) visit(entity)
+  return ordered
 }
 
 // The shared `.uwx` envelope (uwx/1 + exporter + timestamp) around an entity list.
@@ -231,8 +280,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

@@ -253,7 +253,10 @@ 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, namesNew: string[] }>}
+ *   `namesNew` lists the records this package sends whose references name a record it
+ *   creates — by `$ref`, where the next push will send a uuid — as keys of `hashes`. A
+ *   caller that banks `hashes` re-banks these once the push is applied.
  *   `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
@@ -469,11 +472,22 @@ 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) }))
+  const recordChanged = col.entities.map((e, i) => ({
+    entity: e,
+    index: col.index[i],
+    changed: changed(e),
+  }))
   const changedRecords = recordChanged.filter((r) => r.changed)
 
   let records = null
+  // ⭐ A RECORD THAT NAMES A RECORD THIS PUSH CREATES names it by `$ref`
+  // (`records.js::encodeReference`), and the backend stores the uuid it mints for it. The
+  // next push sends that uuid: the same reference, another encoding — and another hash.
+  // So the caller re-banks these records once the push is applied, or the next push
+  // sends every one of them again.
+  let namesNew = []
   if (folder && (folderChanged || changedRecords.length > 0)) {
+    namesNew = changedRecords.filter((r) => r.entity.namesNew > 0).map((r) => cacheKey(r.entity))
     // Folder first (always, for the `$ref` closure), then changed records. The
     // leading `{ kind: 'folder' }` keeps submission position 0 aligned for record
     // back-fill (backfillEntityUuids skips it — the folder has no uuid to write).
@@ -523,6 +537,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
 
   return {
     siteContent, records, siteContentUuid, hashes, warnings, skipped,
+    // Records that name a record this push creates — see `namesNew` above.
+    namesNew,
     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
 }