@uniweb/build 1.22.0 → 1.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -740,7 +740,7 @@ function siteQueries(declarations) {
740
740
  // those files, and on every push once every file in the directory is placed.
741
741
  //
742
742
  // ⚠️ A file that produced nothing is dropped WITHOUT a warning here: its schema did
743
- // not resolve (reported as schemaless), or its records were skipped (reported while
743
+ // not resolve (refused, `noDataSchema`), or its records were skipped (reported while
744
744
  // reading them). Saying it a second time, as a folder problem, names the wrong cause.
745
745
  function placeProducedRecords(nodes, producedBy) {
746
746
  const out = []
@@ -869,12 +869,9 @@ function resolveDeclaration(schema, modelName) {
869
869
  * Defaults to the site's foundation's (`siteSelfScope`); a caller that has it
870
870
  * already passes it, so one emit reads it once.
871
871
  * @returns {Promise<{ entities: object[], index: object[], warnings: string[],
872
- * refusals: string[], schemaless: Array<{name: string, model: string}>,
873
- * colConfig: object, folder: object, recordsDirExists: boolean }>}
874
- * `refusals` — records that cannot be sent as written (`recordsToEntities`).
875
- * `schemaless` lists the QUERIES whose schema resolved to nothing (the
876
- * convention-default soft-skip) — their records are not pushed as entities, and
877
- * the composite deploy delivers those queries statically instead.
872
+ * refusals: string[], colConfig: object, folder: object, recordsDirExists: boolean }>}
873
+ * `refusals` — records that cannot be sent as written (`recordsToEntities`), and the
874
+ * folders and queries whose data schema resolves to nothing (`noDataSchema`).
878
875
  * `recordsDirExists` is false for a site with no records directory at all.
879
876
  * `sendFolder` is whether a push sends the folder — see `sendsFolder`.
880
877
  */
@@ -922,7 +919,6 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
922
919
  index: [],
923
920
  warnings,
924
921
  refusals,
925
- schemaless: [],
926
922
  colConfig,
927
923
  folder: { ...folder, nodes: [] },
928
924
  recordsDirExists: pool.exists,
@@ -941,8 +937,8 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
941
937
  const resolveModel = typeof opts.resolveModel === 'function' ? opts.resolveModel : null
942
938
  // The local foundation is REQUIRED only when a query asked for a schema
943
939
  // EXPLICITLY (and there's no remote resolver). A schema that only a folder name
944
- // or a query name supplied soft-skips when nothing resolves, so a delivery-only
945
- // site with no foundation must not be forced to have one.
940
+ // or a query name supplied and that nothing resolves is refused per folder and per
941
+ // query below (`noDataSchema`), which says which records it is about.
946
942
  const explicitBy = new Map() // schema (as written) → the first query that asked for it
947
943
  for (const { name, decl } of queries) {
948
944
  if (decl.schemaExplicit && !explicitBy.has(decl.schema)) explicitBy.set(decl.schema, name)
@@ -1005,6 +1001,21 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1005
1001
  return modelName
1006
1002
  }
1007
1003
 
1004
+ // ⭐ EVERY RECORD HAS A DATA SCHEMA [Diego, 2026-11-11]. A schema only a folder's name or a
1005
+ // query's name supplied, which resolves to nothing, is refused, one line per folder and per
1006
+ // query that reads no folder: the push sends nothing, and says what to write. ⛔ Until
1007
+ // 2026-11-11 it was a soft skip: the records were not sent, a publish uploaded their compiled
1008
+ // files instead, in the site's own language only, and the app could not edit them.
1009
+ const noDataSchema = (where, modelName) =>
1010
+ `${where}: no data schema resolves for ${modelName}` +
1011
+ (resolveModel?.offline === true
1012
+ ? ' here (this run does not ask the backend)'
1013
+ : resolveModel
1014
+ ? ', in the foundation or on the backend'
1015
+ : '') +
1016
+ ', and every record needs one. Define it in the foundation (`schemas/<name>.yml`), or name a ' +
1017
+ 'registered one on the query (`schema:` in queries.yml) — `uniweb guide data`.'
1018
+
1008
1019
  // ⚠️ AN EXPLICIT SCHEMA THAT RESOLVES TO NOTHING IS THE AUTHOR'S ERROR — and a
1009
1020
  // depth-2 folder has two readings worth naming. `records/person/2024/ada.md`
1010
1021
  // resolves as `@person/2024` — the rule is total, so it is not ambiguous — but an
@@ -1103,7 +1114,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1103
1114
  const index = []
1104
1115
  // pool id (the FILE) → the records it produced, so the folder places records.
1105
1116
  const producedBy = new Map()
1106
- // Schemas (as written) whose Model resolved to nothing — soft-skipped.
1117
+ // Schemas (as written) whose Model resolved to nothing — refused (`noDataSchema`).
1107
1118
  const unresolved = new Set()
1108
1119
  // The sync response is keyed per ($schema, $id), so the pair must be unique
1109
1120
  // within one submission.
@@ -1188,9 +1199,10 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1188
1199
  const declaration = (await declarationFor(modelName)) || (await typedFor(schema))
1189
1200
  if (!declaration) {
1190
1201
  // An explicit schema the author asked for is a hard error; one only the
1191
- // folder's name supplied is a soft skip, reported below.
1202
+ // folder's name supplied is refused for the folder, with the rest of the push.
1192
1203
  if (explicitBy.has(schema)) throw unresolvedExplicit(modelName, explicitBy.get(schema))
1193
1204
  unresolved.add(schema)
1205
+ refusals.push(noDataSchema(`${pool.dir}/${label}/`, modelName))
1194
1206
  continue
1195
1207
  }
1196
1208
 
@@ -1342,18 +1354,10 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1342
1354
  refusals.push(...mappedOut.refusals)
1343
1355
  }
1344
1356
 
1345
- // Queries whose schema resolved to nothing — not pushed as entities. Their compiled
1346
- // data is delivered as static files instead (`site/schemaless-data.js`), so the caller
1347
- // can route it there; and their declarations are sent naming no Model
1348
- // (`site.js::queriesNested`).
1349
- //
1350
- // ⛔ Deliberately NOT a `warnings` string. This is a product decision the author
1351
- // is making — entities or static files — and it needs to be reported at a
1352
- // prominence a prose warning cannot carry. Callers get the structured entry and
1353
- // say it themselves (`cli/src/commands/{publish,push}.js`). It used to push
1354
- // `"… — not synced"`, printed dim among everything else, and an author read that
1355
- // as "my data did not upload" when it is delivered, as static files.
1356
- const schemaless = []
1357
+ // A query reads records of one data schema, so its schema must resolve too. A query over a
1358
+ // folder whose schema resolved to nothing is refused with the folder, above; one that reads no
1359
+ // folder is refused here (`noDataSchema`). ⛔ Until 2026-11-11 such a query was "schema-less":
1360
+ // its declaration went up naming no Model and a publish uploaded its compiled files.
1357
1361
  for (const { name, decl } of queries) {
1358
1362
  const schema = decl.schema || decl.model
1359
1363
  const hasRecords = poolBySchema.has(schema)
@@ -1363,7 +1367,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1363
1367
  : Boolean((await declarationFor(modelFor(schema, `query "${name}"`))) || (await typedFor(schema))))
1364
1368
  if (!resolved) {
1365
1369
  if (decl.schemaExplicit) throw unresolvedExplicit(qualifyRef(schema, scope), name)
1366
- schemaless.push({ name, model: qualifyRef(schema, scope) })
1370
+ if (!hasRecords) refusals.push(noDataSchema(`query "${name}"`, qualifyRef(schema, scope)))
1367
1371
  continue
1368
1372
  }
1369
1373
  if (!hasRecords) {
@@ -1375,16 +1379,6 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1375
1379
  )
1376
1380
  }
1377
1381
  }
1378
- // Records whose schema resolved to nothing and that no query reads: they are not
1379
- // pushed, and no static file carries them either — say so, once per folder.
1380
- for (const schema of unresolved) {
1381
- if (queries.some(({ decl }) => (decl.schema || decl.model) === schema)) continue
1382
- const n = poolBySchema.get(schema).length
1383
- warnings.push(
1384
- `${pool.dir}/${poolBySchema.get(schema)[0].dirs.join('/')}/: no data schema resolves for ${schema}, ` +
1385
- `and no query reads ${n === 1 ? 'this record' : `these ${n} records`} — not pushed.`
1386
- )
1387
- }
1388
1382
 
1389
1383
  const nodes = placeProducedRecords(folder.nodes, producedBy)
1390
1384
 
@@ -1393,7 +1387,6 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1393
1387
  index,
1394
1388
  warnings,
1395
1389
  refusals,
1396
- schemaless,
1397
1390
  colConfig,
1398
1391
  folder: { ...folder, nodes },
1399
1392
  recordsDirExists: pool.exists,
@@ -1419,10 +1412,12 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1419
1412
  // the records directory is there and holds nothing at all (the deliberate empty,
1420
1413
  // which removes what the backend has — the CLI asks first).
1421
1414
  //
1422
- // ⛔ NOT when every record's schema resolved to nothing, nor when the directory
1423
- // holds only files that are not records (warned). Neither is an author emptying
1424
- // the folder, and sending one would remove the backend's records — including any
1425
- // authored there — for a state nobody chose. Inert instead, like no directory.
1415
+ // ⛔ NOT when the directory holds only files that are not records (warned), nor when
1416
+ // every record's schema resolved to nothing — which a push refuses (`noDataSchema`),
1417
+ // and which a comparison that does not stop on refusals (`status`) must not read as
1418
+ // an emptied folder. Neither is an author emptying the folder, and sending one would
1419
+ // remove the backend's records — including any authored there — for a state nobody
1420
+ // chose. Inert instead, like no directory.
1426
1421
  function sendsFolder(pool, entities, links = []) {
1427
1422
  if (!pool.exists) return false
1428
1423
  if (entities.length > 0 || links.length > 0) return true
@@ -180,8 +180,8 @@ function buildDataSchemaEntities(dataSchemas, scope) {
180
180
  * One `@uniweb/mapping-schema` entity per mapping the foundation defines (`schema._mappings`,
181
181
  * `foundation/mappings.js`): its identity flat, as a data schema's is, and the rest of the file under
182
182
  * `rules` — the envelope's `model:` names the exchange type, so the mapping's own `model:` cannot sit
183
- * beside it. `rules.model` and `rules.keys_from` are named in full; nothing else in `rules` is
184
- * touched, since a backend judges it. A mapping another one names in `keys_from` comes first.
183
+ * beside it. `rules.model`, `rules.keys_from` and a reverse `follow` line's `model` are named in
184
+ * full; nothing else in `rules` is touched, since a backend judges it. A mapping another one names in `keys_from` comes first.
185
185
  *
186
186
  * @param {Object<string, object>} mappings - `{ '@/<name>': declaration }`
187
187
  * @param {(ref: string) => string} scoped - `@/x` → the registration scope's name
@@ -195,6 +195,7 @@ function buildMappingEntities(mappings, scoped) {
195
195
  const { label, description, ...rules } = decl
196
196
  if (typeof rules.model === 'string') rules.model = scoped(rules.model)
197
197
  if (typeof rules.keys_from === 'string') rules.keys_from = scoped(rules.keys_from)
198
+ if (Array.isArray(rules.follow)) rules.follow = rules.follow.map((line) => followNamed(line, scoped))
198
199
  return {
199
200
  model: MAPPING_SCHEMA,
200
201
  name: scoped(ref),
@@ -217,6 +218,18 @@ function buildMappingEntities(mappings, scoped) {
217
218
  return ordered
218
219
  }
219
220
 
221
+ /** One `follow` line, `{ alias: { model?, … } }`, with each `model` named in full; a copy, never the file's. */
222
+ function followNamed(line, scoped) {
223
+ if (line === null || typeof line !== 'object' || Array.isArray(line)) return line
224
+ return Object.fromEntries(
225
+ Object.entries(line).map(([alias, spec]) =>
226
+ spec && typeof spec === 'object' && !Array.isArray(spec) && typeof spec.model === 'string'
227
+ ? [alias, { ...spec, model: scoped(spec.model) }]
228
+ : [alias, spec]
229
+ )
230
+ )
231
+ }
232
+
220
233
  /**
221
234
  * The data schemas in an order a backend can install one at a time: a schema another one in
222
235
  * the package references comes BEFORE it — alphabetical otherwise, so the order is stable.
@@ -7,8 +7,8 @@
7
7
  * site needs it is what its published pages fetch — never whether it has records to sync.
8
8
  * A query counts when a page, a section or the site fetches it, and its records have a
9
9
  * data schema (the declaration names one) and come from the site's own folder (no `url:`).
10
- * A schema-less query's records are delivered as static files, which `records` does not
11
- * touch; an external query is fetched from its own address.
10
+ * Every such query names one, since every record has a data schema [Diego, 2026-11-11];
11
+ * an external query is fetched from its own address.
12
12
  *
13
13
  * @module
14
14
  */
package/src/uwx/site.js CHANGED
@@ -1162,7 +1162,7 @@ function externalSource(d) {
1162
1162
  return source
1163
1163
  }
1164
1164
 
1165
- function queriesNested(declarations, uuids = null, scope = null, keyTyped = null, queryFields = null, schemaless = null) {
1165
+ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null, queryFields = null) {
1166
1166
  const out = []
1167
1167
  for (const [name, d] of Object.entries(declarations)) {
1168
1168
  refuseUnder(d.where, `queries.${name}`)
@@ -1183,14 +1183,11 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
1183
1183
  // names that type — the data schema its records are sent as (`data-key-types.js`).
1184
1184
  const typed = (!d.schemaExplicit && keyTyped?.get(d.schema)) || null
1185
1185
  const schema = typed || d.schema
1186
- // ⛔ NO MODEL FOR A QUERY WHOSE RECORDS RESOLVED NONE (`schemaless`, decided by the records
1187
- // lane — `records.js`). Its name-defaulted `schema` names a Model nothing declares, its records
1188
- // are not pushed, and its compiled data travels as static files — so the declaration goes up
1189
- // with no `schema`. ⛔ Until 2026-09-28 it named that Model anyway (`videos` → `@std/videos`),
1190
- // and a store that checks a query's `schema` against the site's declared types refused the
1191
- // whole content push for it. An explicit `schema:` that does not resolve never reaches here:
1192
- // the records lane refuses it.
1193
- if (!schemaless?.has(name)) setIf(data, 'schema', qualifyRef(schema, scope))
1186
+ // ⭐ EVERY RECORD QUERY NAMES ITS MODEL. One whose schema resolves to nothing never reaches a
1187
+ // backend: the records lane refuses it (`records.js::noDataSchema`), since every record has a
1188
+ // data schema [Diego, 2026-11-11]. ⛔ Until then such a query was "schema-less" and went up
1189
+ // naming no `schema` here, while a publish uploaded its compiled files.
1190
+ setIf(data, 'schema', qualifyRef(schema, scope))
1194
1191
  // ⭐ …AND SAYS SO, so a pull can tell the author's form (`team:`, no schema) from an explicit
1195
1192
  // one — sent only where the deployment's `queries` Section declares the key (`GET /dev/config`
1196
1193
  // → `siteContent.queryFields`), since one that does not refuses a push carrying it.
@@ -1537,8 +1534,6 @@ function touchIconValue(named, settingsFields) {
1537
1534
  * resolves into (`@/x` → `@scope/x`): the site's foundation's. Defaults to
1538
1535
  * `siteSelfScope`; pass the scope the records are emitted with. With none
1539
1536
  * known, `@/x` ships as written.
1540
- * @param {string[]} [opts.schemaless] - the queries whose records resolved no data schema
1541
- * (the records lane's `schemaless`): their declarations name no `schema`.
1542
1537
  * @param {object} [opts.media] - a push's sink for the sections' co-located media
1543
1538
  * (`located-media.js::locatedMediaSink`): each file to upload, and — where its upload
1544
1539
  * map names the file — the reference replaced by the file's key. Absent, nothing is located.
@@ -1826,8 +1821,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
1826
1821
  opts.queryUuids,
1827
1822
  scope,
1828
1823
  opts.keyTyped,
1829
- opts.queryFields,
1830
- Array.isArray(opts.schemaless) ? new Set(opts.schemaless) : null
1824
+ opts.queryFields
1831
1825
  )
1832
1826
  // Emitted only when there is something to state — see the header above
1833
1827
  // `serviceRecords`. ⭐ What this copy holds is per backend — a service is bought on
@@ -295,8 +295,7 @@ function rewriteEntityAssets(node, map, ids, bare = null) {
295
295
  * siteContent: { buffer, entityCount, index, models }|null,
296
296
  * records: { buffer, entityCount, index, models, links }|null,
297
297
  * hashes: Object<string,string>, warnings: string[], refusals: string[],
298
- * skipped: number, schemaless: Array<{name: string, model: string}>,
299
- * localAssets: string[], applied: object, namesNew: string[],
298
+ * skipped: number, localAssets: string[], applied: object, namesNew: string[],
300
299
  * recordItemIdentity: { stamped: number, unknown: number, unbanked: string[] } }>}
301
300
  * Each record entry of `records.index` carries `lists`: the record's list items as
302
301
  * sent (`record-items.js::recordItemLists`), for the caller to bank against the
@@ -305,11 +304,11 @@ function rewriteEntityAssets(node, map, ids, bare = null) {
305
304
  * creates — by `$ref`, where the next push will send a uuid — as keys of `hashes`. A
306
305
  * caller that banks `hashes` re-banks these once the push is applied.
307
306
  * `refusals` names the records that cannot be sent as written, one line each
308
- * (`records.js::recordsToEntities`). A caller that submits must not submit while
309
- * any is present: the backend would refuse the records lane — or, for a record
310
- * written by section whose brief requires nothing, store it empty.
311
- * `schemaless` lists queries that resolved no data schema (soft-skipped from
312
- * the sync) — the composite deploy delivers these statically via the data ball.
307
+ * (`records.js::recordsToEntities`), and each folder or query whose data schema
308
+ * resolves to nothing, since every record needs one (`records.js::noDataSchema`). A
309
+ * caller that submits must not submit while any is present: the backend would refuse
310
+ * the records lane — or, for a record written by section whose brief requires nothing,
311
+ * store it empty.
313
312
  * `localAssets` lists the site-root local media refs (`/images/x.png`) the deploy
314
313
  * must upload + rewrite to serve URLs. A section's co-located files ride `localFiles`,
315
314
  * under their keys from the site root (`located-media.js`); any other co-located ref is
@@ -420,8 +419,6 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
420
419
  // …and the same data schema, where a name stands for the type of its data key
421
420
  // (`@/team` → `@/member`, `data-key-types.js`): decided once, by the records.
422
421
  keyTyped: col.keyTyped,
423
- // …and which queries resolved NO data schema — their declarations go up naming none.
424
- schemaless: col.schemaless.map((q) => q.name),
425
422
  // …and whether this deployment takes the key that says so (`siteContent.queryFields`) —
426
423
  // and the page and `settings` keys that carry Open Graph texts per language.
427
424
  ...(Array.isArray(opts.queryFields) ? { queryFields: opts.queryFields } : {}),
@@ -722,7 +719,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
722
719
  // Records that name a record this push creates — see `namesNew` above.
723
720
  namesNew,
724
721
  refusals,
725
- schemaless: col.schemaless, localAssets, applied,
722
+ localAssets, applied,
726
723
  // The files a push uploads for its file records, each `{ ref, path, contentType }` — the file, and
727
724
  // a PDF's preview — and for its sections' co-located media, each `{ ref, path }`. Uploaded through
728
725
  // the media lane; `ref` is the key the second emit rewrites.
@@ -32,6 +32,7 @@ import { queryNameFromUrl, declaredKeys, fillDeclaredKeys, fetchLevels, pageRout
32
32
  import { parentRouteOf } from '@uniweb/core/route-match'
33
33
 
34
34
  import { validateItem, validateRecordFile, validateBound, validateKeyValue, contentBodyField, rootListSection, referencesOf } from '@uniweb/schemas/conform'
35
+ import { normalizeData } from '@uniweb/schemas/foundation'
35
36
  import { isUuid } from './uwx/uuid.js'
36
37
  import { validateAndNormalizeSchema, buildDataSchemaMap } from './resolve-data-schema.js'
37
38
 
@@ -50,6 +51,32 @@ import { processQueries } from './site/query-processor.js'
50
51
 
51
52
  // --- the join: sections ↔ schemas -------------------------------------------
52
53
 
54
+ /**
55
+ * The keys a section type declares with an inline shape — a field map or a form — whose every
56
+ * field gives a `default:`: the words a section draws itself, which it shows when the section holds
57
+ * no block of its own (`uniweb guide foundation` § A section's own words). Read by the one
58
+ * normalizer every form of a declaration goes through (`normalizeData`).
59
+ *
60
+ * @param {object|undefined} data - a section type's `data:`
61
+ * @returns {Set<string>}
62
+ */
63
+ function keysWithOwnWords(data) {
64
+ const out = new Set()
65
+ let normalized = {}
66
+ try {
67
+ normalized = normalizeData(data, { strict: false }) || {}
68
+ } catch {
69
+ return out // a declaration the foundation's build stops on is reported there
70
+ }
71
+ for (const [key, decl] of Object.entries(normalized)) {
72
+ const fields = decl?.kind === 'fields' ? Object.values(decl.fields || {}) : decl?.kind === 'form' ? decl.fields : null
73
+ if (Array.isArray(fields) && fields.length > 0 && fields.every((f) => f && typeof f === 'object' && f.default !== undefined)) {
74
+ out.add(key)
75
+ }
76
+ }
77
+ return out
78
+ }
79
+
53
80
  /**
54
81
  * Walk a site's sections, pair each governed data input with its schema, and
55
82
  * validate. The section is the join point: it has a *type* (→ `meta.js` → a
@@ -185,7 +212,16 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
185
212
  const concepts = new Set(
186
213
  (foundation[type]?.content || []).filter((e) => e?.kind === 'concept').map((e) => e.key)
187
214
  )
188
- const declaredNames = declared.map(([key]) => key).filter((key) => !concepts.has(key))
215
+ // ⛔ NOR IS A SECTION'S OWN WORDS. A key declared with an inline shape whose every field gives
216
+ // a `default:` holds the words a section draws itself, which an author overrides with a
217
+ // ```yaml:labels block (`uniweb guide foundation` § A section's own words): with no block the
218
+ // component shows the type's own, so it renders without data, and a page's query that feeds
219
+ // another section has not failed to reach it. ⛔ Until 2026-11-11 it was counted, and every
220
+ // publish of a site whose blog page queries its articles reported the page's Hero.
221
+ const ownWords = keysWithOwnWords(bindings)
222
+ const declaredNames = declared
223
+ .map(([key]) => key)
224
+ .filter((key) => !concepts.has(key) && !ownWords.has(key))
189
225
  if (declaredNames.length > 0 && inputs.length > 0 && fills.size === 0 && !declaredNames.some((k) => held.includes(k))) {
190
226
  const delivered = inputs.map((i) => i.as).filter(Boolean)
191
227
  setupErrors.push({
@@ -355,8 +391,9 @@ function listViolation(finding, label, base) {
355
391
  * ⭐ A folder named for a data key the foundation types, when no data schema has its name,
356
392
  * holds records of that type and is checked against it — `records/team/` against `@/member`
357
393
  * for `data: { team: '@/member' }` — the way a push sends them [Diego, 2026-09-25]
358
- * (`uwx/data-key-types.js`). A folder whose schema resolves to nothing even so is left out in
359
- * silence: its records are schema-less, delivered as files, and the push says so itself.
394
+ * (`uwx/data-key-types.js`). A folder whose schema this check cannot read (a foundation that is
395
+ * not local) is left out in silence; one it can read and finds nothing for has already stopped
396
+ * `processQueries`, since every record has a data schema [Diego, 2026-11-11].
360
397
  *
361
398
  * @returns {Promise<{ violations: object[], setupErrors: object[], schemas: Set<string>, checked: number }>}
362
399
  */
@@ -1,185 +0,0 @@
1
- /**
2
- * Schema-less collection data — the set, and its local media.
3
- *
4
- * ⭐ **The name carries the scope on purpose.** This is NOT "the site's static
5
- * data" in general. A site's collections partition by **schema presence**: one
6
- * that resolves a data schema syncs as folder entities — content a backend
7
- * genuinely consumes, queryable, editable, with a `brief:` for its lean shape.
8
- * A **schema-less** collection has no entity model, so its compiled
9
- * `dist/data/<name>.json` (plus its per-record files, `<name>/<$name>.json`) is
10
- * delivered as files instead. That fallback tier is all this module is about.
11
- *
12
- * { data: { "<relpath under dist/data>": <json> } } // schema-less only
13
- *
14
- * ⇒ It is an **in-memory enumeration**, not an artifact. `collectSchemalessData`
15
- * gathers the set; the CLI's `site-data-upload` lane PUTs each file to the
16
- * target the backend returns, landing at its serving tail.
17
- *
18
- * ## ⛔ It used to be a "data ball", and that is retired (2026-08-18)
19
- *
20
- * This merged the whole set into ONE uploaded asset that the backend then had
21
- * to fetch, parse and fan out. It was the **only aggregate the CLI produced** —
22
- * media, foundation code and the runtime all upload one object per file — and
23
- * the only place these bytes ever transited the backend. Nothing in the code or
24
- * the docs ever justified the bundling.
25
- *
26
- * ⇒ **Do not reintroduce a bundle here.** One object per file is what the
27
- * reader's static arm already assumes: a plain object GET on the verbatim tail,
28
- * with nothing anywhere that unbundles.
29
- *
30
- * **A search index used to ride here too, and deliberately no longer does**
31
- * (2026-08-01). Only a CLI deploy produced one — a CMS publish produced none —
32
- * so a site's search existed or vanished depending on who published it, which
33
- * is the artifact-flicker rule exactly. A host that wants search derives it from
34
- * the content it already stores. See the note at the removal point below.
35
- */
36
-
37
- import { existsSync } from 'node:fs'
38
- import { readFile, readdir } from 'node:fs/promises'
39
- import { join, relative, sep } from 'node:path'
40
- import { DATA_DIR } from '@uniweb/core'
41
- import { isLocalAssetPath } from './assets.js'
42
-
43
- // Walk a dist subdir for *.json → { "<posix-relpath>": <parsedJson> }. Unparseable
44
- // files are skipped (build-emitted data is always valid JSON; this just stays safe).
45
- async function readJsonTree(dir) {
46
- if (!existsSync(dir)) return {}
47
- const out = {}
48
- const entries = await readdir(dir, { withFileTypes: true, recursive: true })
49
- for (const entry of entries) {
50
- if (!entry.isFile() || !entry.name.endsWith('.json')) continue
51
- const full = join(entry.parentPath || entry.path, entry.name)
52
- const rel = relative(dir, full).split(sep).join('/')
53
- try {
54
- out[rel] = JSON.parse(await readFile(full, 'utf8'))
55
- } catch {
56
- // not valid JSON — skip
57
- }
58
- }
59
- return out
60
- }
61
-
62
- // The collection a `dist/data` relpath belongs to: the first path segment, minus a
63
- // trailing `.json`. `articles.json` → `articles`; `articles/hello.json` → `articles`.
64
- function queryOf(relPath) {
65
- const first = relPath.split('/')[0]
66
- return first.endsWith('.json') ? first.slice(0, -5) : first
67
- }
68
-
69
- /**
70
- * Gather the schema-less set from a built site's dist/ — in memory, one entry per
71
- * file; nothing is bundled (see the header).
72
- *
73
- * @param {string} distDir - the site's built dist/ directory
74
- * @param {string[]} [schemalessNames] - collection names with no data schema (from
75
- * `emitSyncPackages(...).schemaless`); only these contribute `data`.
76
- * @returns {Promise<{ data: Object }|null>} null when there is nothing to deliver.
77
- */
78
- export async function collectSchemalessData(distDir, schemalessNames = []) {
79
- const schemaless = new Set(schemalessNames)
80
- const allData = await readJsonTree(join(distDir, DATA_DIR))
81
- const data = {}
82
- for (const [relPath, value] of Object.entries(allData)) {
83
- if (schemaless.has(queryOf(relPath))) data[relPath] = value
84
- }
85
- // Agent projections deliberately do NOT ride the ball.
86
- //
87
- // A backend that stores the site's content derives them itself at publish —
88
- // one producer, so shipping ours would upload an artifact to the one host
89
- // that does not need it, and invite two answers for one site. The projections
90
- // this build emits into `dist/` are for hosts with no backend to derive them:
91
- // static hosts and foreign backends. That is `@uniweb/projections`' scope and
92
- // it is unchanged.
93
- //
94
- // (An opt-in `projections` bucket lived here while the delivery contract was
95
- // open. It never shipped enabled, and the one-producer ruling closed the
96
- // question — removed rather than left as a flag nobody may turn on.)
97
- //
98
- // THE SEARCH INDEX IS ONE OF THOSE PROJECTIONS, and it rode this ball anyway
99
- // — `const search = readJsonTree(dist/_search)` sat four lines above this
100
- // comment, doing the exact thing the comment forbids. Removed 2026-08-01.
101
- //
102
- // What made it wrong is not symmetry, it is the flicker rule: a CLI deploy
103
- // produced the index and a CMS publish produced none, so a site's search
104
- // oscillated with whoever published it. Deriving it from stored content — one
105
- // input that exists identically on both lanes — makes that unexpressible,
106
- // which is a stronger guarantee than any producer agreement.
107
- //
108
- // The static index for hosts with no backend is UNCHANGED and still emitted:
109
- // `search-index.json`, bundle lane, what GitHub Pages and every other static
110
- // target serve. The framework has more targets than one backend, and that is
111
- // the artifact for the rest of them.
112
-
113
- if (Object.keys(data).length === 0) return null
114
-
115
- // The `search` key is gone too, and that was the SECOND step of a two-step
116
- // retirement, not an afterthought.
117
- //
118
- // Step one shipped `search: {}` — content removed, key kept — because an
119
- // absent field and an empty one are different shapes to a strict
120
- // deserializer, and a missing required field fails exactly as loudly as an
121
- // unknown one. (The producer half of this same contract broke pushes earlier
122
- // the same day by emitting a key the consumer had not declared. Same failure,
123
- // opposite direction.) Step two is this: the consumer retired the field on
124
- // 2026-08-01 and said an older CLI still sending it deploys fine, so the key
125
- // now has nowhere to land and dropping it is safe in both directions.
126
- //
127
- // Worth keeping as a shape: **announce, then remove** — the mirror of
128
- // "declare, then emit". Neither half of a wire can be changed in one step by
129
- // one side, and which side moves first is decided by which direction the
130
- // strictness runs.
131
- return { data }
132
- }
133
-
134
- // --- local media in the ball -------------------------------------------------
135
- // Schema-less collection data rides in the ball, so a local image in a schema-less
136
- // record (e.g. a note's `image: /images/x.png`) needs the same upload + serve-URL
137
- // rewrite the entity content gets (emitSyncPackages' `assetRewrite`) — otherwise the
138
- // served `/data/<name>.json` keeps a dangling local path. The deploy collects the
139
- // ball's refs, uploads them on the SAME asset lane, then rewrites the ball before
140
- // uploading it. The backend serves a `serve_url` in the ball identically to one in an
141
- // entity (it unwraps the ball verbatim), so this is purely producer-side.
142
-
143
- /**
144
- * Site-root local asset refs anywhere in the ball (`/images/x.png`, `/collections/...`).
145
- * Built `dist/data` refs are already site-root (the collection processor copied
146
- * co-located assets to `public/collections/**`), so only `/`-prefixed refs are collected.
147
- * @param {{data:object}|null} ball
148
- * @returns {string[]} deduped refs to upload
149
- */
150
- export function collectSchemalessDataAssets(ball) {
151
- const refs = new Set()
152
- const walk = (n) => {
153
- if (typeof n === 'string') {
154
- if (isLocalAssetPath(n) && n.startsWith('/')) refs.add(n)
155
- return
156
- }
157
- if (Array.isArray(n)) { for (const x of n) walk(x); return }
158
- if (n && typeof n === 'object') for (const v of Object.values(n)) walk(v)
159
- }
160
- walk(ball)
161
- return [...refs]
162
- }
163
-
164
- /**
165
- * Rewrite the ball: replace every local ref the map covers with its serve URL. Pure —
166
- * returns a NEW ball (the input is reused elsewhere). A ref the map omits (upload
167
- * failed/skipped) is left untouched — never a broken URL.
168
- * @param {{data:object}|null} ball
169
- * @param {Record<string,string>} map - ref → serve URL
170
- * @returns {{data:object}|null} a new ball, or the input when there's nothing to do
171
- */
172
- export function rewriteSchemalessDataAssets(ball, map) {
173
- if (!ball || !map || Object.keys(map).length === 0) return ball
174
- const walk = (n) => {
175
- if (typeof n === 'string') return map[n] || n
176
- if (Array.isArray(n)) return n.map(walk)
177
- if (n && typeof n === 'object') {
178
- const out = {}
179
- for (const [k, v] of Object.entries(n)) out[k] = walk(v)
180
- return out
181
- }
182
- return n
183
- }
184
- return walk(ball)
185
- }