@uniweb/build 1.21.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.
@@ -4,17 +4,18 @@
4
4
  * Extract translatable strings from collection items and merge translations.
5
5
  * Collections are separate from page content (stored in public/data/*.json).
6
6
  *
7
- * Supports three extraction modes:
8
- * 1. Schema-guided — companion .schema.js or standard @uniweb/schemas
9
- * 2. Heuristic — recursive walk, extract all strings, skip structural patterns
10
- * 3. Legacy — flat field list (fallback within heuristic)
7
+ * A record is translated as its data schema says: by the model a push sends it as, which marks
8
+ * the fields that travel per language (`extractByModel`, `translateByModel`). Every record has a
9
+ * data schema [Diego, 2026-11-11]; where this build cannot read it — a site whose foundation is
10
+ * not in the project, such as a clone — a heuristic walk reads the record instead (`extractHeuristic`).
11
+ * ⛔ Until 2026-11-11 a record with no data schema was read by a companion `records/<query>.schema.js`,
12
+ * or by a standard schema guessed from the query's name made singular (`events` → `@std/event`).
11
13
  */
12
14
 
13
15
  import { readFile, writeFile, readdir, mkdir, rm } from 'fs/promises'
14
16
  import { RESERVED_LOCALE_FILES } from './locales.js'
15
17
  import { existsSync } from 'node:fs'
16
18
  import { join, resolve, sep } from 'node:path'
17
- import { pathToFileURL } from 'node:url'
18
19
  import { DATA_DIR, resolveDefaultLocale } from '@uniweb/core'
19
20
  import yaml from 'js-yaml'
20
21
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
@@ -30,7 +31,7 @@ import { toDeliveredRecord, contentBodyField, misplacedFields, mergedFromStored,
30
31
  import { resolveDocForLocale } from './merge.js'
31
32
  import { extractUnitsFromDoc } from './extract.js'
32
33
  import { flatFormRefusal, extractExcerpt } from '../site/query-processor.js'
33
- import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir, readEntityPool, groupPoolBySchema } from '../site/entity-pool.js'
34
+ import { poolDirsForSchema, schemaForPoolDirs, readEntityPool, groupPoolBySchema } from '../site/entity-pool.js'
34
35
  import { readRecordsConfig, resolveFolder } from '../site/records-config.js'
35
36
  import { labelIn } from '../site/entry-label.js'
36
37
  // The heuristic judgement about which strings inside structured data are prose.
@@ -39,7 +40,6 @@ import { labelIn } from '../site/entry-label.js'
39
40
  // is not, wherever the value came from. Moved rather than copied: two tuned
40
41
  // denylists would drift, and drift here is silent.
41
42
  import {
42
- NON_TRANSLATABLE_TYPES,
43
43
  HEURISTIC_SKIP_FIELDS,
44
44
  MAX_HEURISTIC_DEPTH,
45
45
  isStructuralString,
@@ -57,113 +57,6 @@ import {
57
57
  // `locales/records/` — two directories, one word, so the constant says which.
58
58
  export const RECORD_LOCALES_DIR = 'records'
59
59
 
60
- // ---------------------------------------------------------------------------
61
- // Schema resolution
62
- // ---------------------------------------------------------------------------
63
-
64
- /** Cache for resolved schemas (query name → schema or null) */
65
- const schemaCache = new Map()
66
-
67
- /**
68
- * Resolve schema for a collection.
69
- *
70
- * Discovery order:
71
- * 1. Companion file: public/data/<name>.schema.js (ESM default export)
72
- * 2. Standard schema: @uniweb/schemas by collection name (with naive singularization)
73
- * 3. null (no schema found → heuristic fallback)
74
- *
75
- * @param {string} queryName
76
- * @param {string} siteRoot
77
- * @returns {Promise<Object|null>}
78
- */
79
- async function resolveSchema(queryName, siteRoot) {
80
- if (schemaCache.has(queryName)) {
81
- return schemaCache.get(queryName)
82
- }
83
-
84
- let schema = null
85
-
86
- // 1. Companion schema file, beside the collection it describes.
87
- //
88
- // This used to be looked up in `public/<DATA_DIR>/` — next to the compiled
89
- // output rather than the source. That directory is the build's, and asking
90
- // an author to write into it was the one remaining place the framework
91
- // contradicted its own rule that `collections/` is the only way to provide
92
- // structured data. The schema describes the source, so it lives with it.
93
- const companionPath = join(resolveRecordsDir(siteRoot).abs, `${queryName}.schema.js`)
94
- if (existsSync(companionPath)) {
95
- try {
96
- const mod = await import(pathToFileURL(companionPath).href)
97
- schema = mod.default || mod
98
- schemaCache.set(queryName, schema)
99
- return schema
100
- } catch (err) {
101
- console.warn(`[i18n] Failed to load companion schema ${companionPath}: ${err.message}`)
102
- }
103
- }
104
-
105
- // 2. Standard schema from @uniweb/schemas (try exact name + singularized)
106
- const schemasModule = await import('@uniweb/schemas')
107
- const names = [queryName, singularize(queryName)]
108
-
109
- for (const name of names) {
110
- if (schemasModule.schemas[name]) {
111
- schema = schemasModule.schemas[name]
112
- break
113
- }
114
- }
115
-
116
- schemaCache.set(queryName, schema)
117
- return schema
118
- }
119
-
120
- /**
121
- * Naive singularization for schema lookup.
122
- * Handles common plural suffixes: articles→article, opportunities→opportunity
123
- */
124
- function singularize(name) {
125
- if (name.endsWith('ies')) return name.slice(0, -3) + 'y'
126
- if (name.endsWith('ses') || name.endsWith('xes') || name.endsWith('zes')) return name.slice(0, -2)
127
- if (name.endsWith('s') && !name.endsWith('ss')) return name.slice(0, -1)
128
- return name
129
- }
130
-
131
- // ---------------------------------------------------------------------------
132
- // Field translatability
133
- // ---------------------------------------------------------------------------
134
-
135
- /**
136
- * Determine if a schema field should be extracted for translation.
137
- *
138
- * @param {Object} fieldDef - Schema field definition
139
- * @returns {'yes'|'no'|'recurse'} Whether the field is translatable
140
- */
141
- function isFieldTranslatable(fieldDef) {
142
- // Explicit override always wins
143
- if (fieldDef.translatable === true) return 'yes'
144
- if (fieldDef.translatable === false) return 'no'
145
-
146
- const type = fieldDef.type
147
-
148
- // Types that are never translatable
149
- if (NON_TRANSLATABLE_TYPES.has(type)) return 'no'
150
-
151
- // Markdown is always translatable
152
- if (type === 'markdown') return 'yes'
153
-
154
- // Strings with enum default to NOT translatable (status codes, types)
155
- if (type === 'string' && fieldDef.enum) return 'no'
156
-
157
- // Plain strings default to translatable
158
- if (type === 'string') return 'yes'
159
-
160
- // Objects and arrays: recurse into their nested definitions
161
- if (type === 'object' || type === 'array') return 'recurse'
162
-
163
- // Unknown types: skip
164
- return 'no'
165
- }
166
-
167
60
  // ---------------------------------------------------------------------------
168
61
  // A record's model — what a push sends it as
169
62
  // ---------------------------------------------------------------------------
@@ -393,74 +286,14 @@ function translateDocs(value, context, translations, depth = 0) {
393
286
  // Schema-guided extraction
394
287
  // ---------------------------------------------------------------------------
395
288
 
396
- /**
397
- * Extract translatable fields from an item using a schema.
398
- *
399
- * @param {Object} item - Data item
400
- * @param {Object} schema - Schema with `fields`
401
- * @param {string} queryName
402
- * @param {Object} units - Accumulator
403
- */
404
- function extractWithSchema(item, schema, recordDir, units) {
405
- const context = { record: `${recordDir}/${recordHandle(item)}` }
406
-
407
- extractFromItemWithSchema(item, schema.fields, '', context, units)
408
-
409
- // Also extract the record's ProseMirror documents (not covered by schema fields)
410
- for (const { path, doc } of proseMirrorDocs(item)) extractFromProseMirrorDoc(doc, context, units, path)
411
- }
412
-
413
- /**
414
- * Recursively extract translatable fields guided by schema.
415
- */
416
- function extractFromItemWithSchema(data, fields, pathPrefix, context, units) {
417
- if (!data || typeof data !== 'object') return
418
-
419
- for (const [fieldName, fieldDef] of Object.entries(fields)) {
420
- if (isRecordSystemField(fieldName, !pathPrefix)) continue
421
- const value = data[fieldName]
422
- if (value === undefined || value === null) continue
423
-
424
- const fieldPath = pathPrefix ? `${pathPrefix}.${fieldName}` : fieldName
425
- const translatable = isFieldTranslatable(fieldDef)
426
-
427
- if (translatable === 'yes') {
428
- if (typeof value === 'string' && value.trim()) {
429
- addUnit(units, value, fieldPath, context)
430
- }
431
- } else if (translatable === 'recurse') {
432
- if (fieldDef.type === 'object' && fieldDef.fields && typeof value === 'object' && !Array.isArray(value)) {
433
- extractFromItemWithSchema(value, fieldDef.fields, fieldPath, context, units)
434
- } else if (fieldDef.type === 'array' && Array.isArray(value)) {
435
- const itemDef = fieldDef.items
436
- if (itemDef) {
437
- value.forEach((elem, i) => {
438
- const elemPath = `${fieldPath}[${i}]`
439
- if (itemDef.type === 'object' && itemDef.fields && typeof elem === 'object') {
440
- extractFromItemWithSchema(elem, itemDef.fields, elemPath, context, units)
441
- } else if (itemDef.type === 'string') {
442
- // Array of strings — check item-level translatable
443
- const itemTranslatable = isFieldTranslatable(itemDef)
444
- if (itemTranslatable === 'yes' && typeof elem === 'string' && elem.trim()) {
445
- addUnit(units, elem, elemPath, context)
446
- }
447
- }
448
- })
449
- }
450
- }
451
- }
452
- // translatable === 'no' → skip
453
- }
454
- }
455
-
456
289
  // ---------------------------------------------------------------------------
457
- // Heuristic extraction (no schema)
290
+ // Heuristic extraction (a data schema this build cannot read)
458
291
  // ---------------------------------------------------------------------------
459
292
 
460
293
  /**
461
- * Extract translatable fields from an item using heuristics — a record with no data schema, which
462
- * says nothing of its fields. Recursively walks the data, extracting strings that look like
463
- * human-readable text.
294
+ * Extract translatable fields from an item using heuristics — a record whose data schema this
295
+ * build cannot read (a foundation not in the project, such as a clone's). Recursively walks the
296
+ * data, extracting strings that look like human-readable text.
464
297
  *
465
298
  * @param {Set<string>|null} skip - fields of the record's own level to leave out (`EXCERPT`)
466
299
  */
@@ -516,59 +349,7 @@ function extractFromItemHeuristic(data, pathPrefix, context, units, depth, skip
516
349
  }
517
350
 
518
351
  // ---------------------------------------------------------------------------
519
- // Schema-guided translation
520
- // ---------------------------------------------------------------------------
521
-
522
- /**
523
- * Translate item fields using schema guidance.
524
- */
525
- function translateWithSchema(item, schema, context, translations) {
526
- const translated = translateDocs(item, context, translations)
527
- translateItemWithSchema(translated, schema.fields, context, translations)
528
- return translated
529
- }
530
-
531
- /**
532
- * Recursively translate fields guided by schema.
533
- */
534
- function translateItemWithSchema(data, fields, context, translations, topLevel = true) {
535
- if (!data || typeof data !== 'object') return
536
-
537
- for (const [fieldName, fieldDef] of Object.entries(fields)) {
538
- if (isRecordSystemField(fieldName, topLevel)) continue
539
- const value = data[fieldName]
540
- if (value === undefined || value === null) continue
541
-
542
- const translatable = isFieldTranslatable(fieldDef)
543
-
544
- if (translatable === 'yes') {
545
- if (typeof value === 'string') {
546
- data[fieldName] = lookupTranslation(value, context, translations)
547
- }
548
- } else if (translatable === 'recurse') {
549
- if (fieldDef.type === 'object' && fieldDef.fields && typeof value === 'object' && !Array.isArray(value)) {
550
- translateItemWithSchema(value, fieldDef.fields, context, translations, false)
551
- } else if (fieldDef.type === 'array' && Array.isArray(value)) {
552
- const itemDef = fieldDef.items
553
- if (itemDef) {
554
- value.forEach((elem, i) => {
555
- if (itemDef.type === 'object' && itemDef.fields && typeof elem === 'object') {
556
- translateItemWithSchema(elem, itemDef.fields, context, translations, false)
557
- } else if (itemDef.type === 'string') {
558
- const itemTranslatable = isFieldTranslatable(itemDef)
559
- if (itemTranslatable === 'yes' && typeof elem === 'string') {
560
- value[i] = lookupTranslation(elem, context, translations)
561
- }
562
- }
563
- })
564
- }
565
- }
566
- }
567
- }
568
- }
569
-
570
- // ---------------------------------------------------------------------------
571
- // Heuristic translation (no schema)
352
+ // Heuristic translation (a data schema this build cannot read)
572
353
  // ---------------------------------------------------------------------------
573
354
 
574
355
  /**
@@ -774,8 +555,6 @@ export async function extractRecordContent(siteRoot, options = {}) {
774
555
 
775
556
  if (!Array.isArray(items)) continue
776
557
 
777
- // Resolve schema once per collection
778
- const schema = await resolveSchema(queryName, siteRoot)
779
558
  const recordDir = poolDirs.get(queryName) ?? queryName
780
559
  const model = models.get(queryName) ?? null
781
560
  // ⭐ AND THE QUERY'S PER-RECORD FILES. A query with `deferred:` fields writes each
@@ -788,8 +567,6 @@ export async function extractRecordContent(siteRoot, options = {}) {
788
567
  const skip = derivesExcerpt(item, whole, dataSchemas.get(queryName), excerpts.get(queryName)) ? EXCERPT : null
789
568
  if (model) {
790
569
  extractByModel(item, model, { record: `${recordDir}/${recordHandle(item)}` }, units, skip)
791
- } else if (schema?.fields) {
792
- extractWithSchema(item, schema, recordDir, units)
793
570
  } else {
794
571
  extractHeuristic(item, recordDir, units, skip)
795
572
  }
@@ -1007,8 +784,6 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
1007
784
  continue
1008
785
  }
1009
786
 
1010
- // Resolve schema once per collection
1011
- const schema = await resolveSchema(queryName, siteRoot)
1012
787
  const recordDir = poolDirs.get(queryName) ?? queryName
1013
788
  const recordOptions = {
1014
789
  locale,
@@ -1040,7 +815,7 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
1040
815
  const { dataSchema } = recordOptions
1041
816
  const record = dataSchema && isPlainObject(stored) ? mergedFromStored(dataSchema, stored) : stored
1042
817
  const translatedRecord = isPlainObject(record)
1043
- ? await translateItemAsync(record, recordDir, translations, schema, recordOptions)
818
+ ? await translateItemAsync(record, recordDir, translations, recordOptions)
1044
819
  : record
1045
820
  if (isPlainObject(record)) wholes.set(recordHandle(record), { source: record, translated: translatedRecord })
1046
821
  const written = relabel(
@@ -1062,7 +837,7 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
1062
837
  // Translate each item (with free-form support)
1063
838
  const translatedItems = await Promise.all(
1064
839
  items.map((item) =>
1065
- translateItemAsync(item, recordDir, translations, schema, { ...recordOptions, whole: wholes.get(recordHandle(item)) })
840
+ translateItemAsync(item, recordDir, translations, { ...recordOptions, whole: wholes.get(recordHandle(item)) })
1066
841
  )
1067
842
  )
1068
843
 
@@ -1110,10 +885,10 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
1110
885
  * @param {{ source: Object, translated: Object }} [options.whole] - for an item of a lean list, its
1111
886
  * record whole and translated, whose body a derived excerpt is derived from
1112
887
  */
1113
- async function translateItemAsync(item, recordDir, translations, schema, options = {}) {
888
+ async function translateItemAsync(item, recordDir, translations, options = {}) {
1114
889
  const { locale, localesDir, freeformEnabled, dataSchema = null, model = null, targets = null, excerpt = null, whole = null } = options
1115
890
  const derived = derivesExcerpt(item, whole?.source, dataSchema, excerpt)
1116
- let translated = translateItemSync(item, recordDir, translations, schema, { model, targets, skip: derived ? EXCERPT : null })
891
+ let translated = translateItemSync(item, recordDir, translations, { model, targets, skip: derived ? EXCERPT : null })
1117
892
  if (freeformEnabled && locale && localesDir) translated = await applyFreeformFile(translated, item, recordDir, locale, localesDir, dataSchema)
1118
893
  if (!derived) return translated
1119
894
  return { ...translated, excerpt: derivedExcerptOf(whole ? whole.translated : translated, dataSchema, excerpt) }
@@ -1170,17 +945,13 @@ function applyFreeform(record, freeform, dataSchema, schemaRef) {
1170
945
 
1171
946
  /**
1172
947
  * Apply translations to a collection item (sync, hash-based only) — by the model it is pushed as
1173
- * when it has one (`translateByModel`), else a companion schema's fields, else the heuristic.
948
+ * (`translateByModel`), or by the heuristic where this build cannot read its data schema.
1174
949
  */
1175
- function translateItemSync(item, recordDir, translations, schema, { model = null, targets = null, skip = null } = {}) {
950
+ function translateItemSync(item, recordDir, translations, { model = null, targets = null, skip = null } = {}) {
1176
951
  const context = { record: `${recordDir}/${recordHandle(item)}` }
1177
952
 
1178
953
  if (model) return translateByModel(item, model, context, translations, targets, skip)
1179
- const translated = { ...item }
1180
- if (schema?.fields) {
1181
- return translateWithSchema(translated, schema, context, translations)
1182
- }
1183
- return translateHeuristic(translated, context, translations, skip)
954
+ return translateHeuristic({ ...item }, context, translations, skip)
1184
955
  }
1185
956
 
1186
957
  // ---------------------------------------------------------------------------
@@ -1264,7 +1035,6 @@ export async function translateRecordData(items, queryName, siteRoot, options =
1264
1035
  const one = !!items && typeof items === 'object' && !Array.isArray(items)
1265
1036
  if (!Array.isArray(items) && !one) return items
1266
1037
 
1267
- const schema = await resolveSchema(queryName, siteRoot)
1268
1038
  const { poolDirs, schemas: dataSchemas, models, targets, excerpts, labels, defaultLocale } = await recordQueries(siteRoot)
1269
1039
  const recordDir = poolDirs.get(queryName) ?? queryName
1270
1040
  const recordOptions = {
@@ -1285,11 +1055,11 @@ export async function translateRecordData(items, queryName, siteRoot, options =
1285
1055
  const wholes = new Map()
1286
1056
  if (!one) {
1287
1057
  for (const [handle, record] of await wholeRecords(join(siteRoot, 'public', DATA_DIR), queryName, dataSchema)) {
1288
- wholes.set(handle, { source: record, translated: await translateItemAsync(record, recordDir, translations, schema, recordOptions) })
1058
+ wholes.set(handle, { source: record, translated: await translateItemAsync(record, recordDir, translations, recordOptions) })
1289
1059
  }
1290
1060
  }
1291
1061
  const translated = await Promise.all(
1292
- records.map((item) => translateItemAsync(item, recordDir, translations, schema, { ...recordOptions, whole: wholes.get(recordHandle(item)) }))
1062
+ records.map((item) => translateItemAsync(item, recordDir, translations, { ...recordOptions, whole: wholes.get(recordHandle(item)) }))
1293
1063
  )
1294
1064
 
1295
1065
  const labelsOf = labels.get(queryName)
@@ -82,9 +82,10 @@ export {
82
82
  const SCOPE_PACKAGE = { std: '@uniweb/schemas' }
83
83
 
84
84
  /**
85
- * The `code` of the error a `@/name` ref raises when the foundation defines no schema of
86
- * that name — the one failure that is an answer rather than a fault: a query named after
87
- * no schema is a query over schema-less records.
85
+ * The `code` of the error a ref raises when nothing this foundation reads defines it — the
86
+ * one failure that is an answer rather than a fault. For a `@/name` a folder or a query
87
+ * named, it is the answer a build refuses with: every record has a data schema
88
+ * (`site/query-processor.js::refuseRecordsWithoutSchema`).
88
89
  */
89
90
  export const SCHEMA_NOT_FOUND = 'SCHEMA_NOT_FOUND'
90
91
  const RESERVED_SYSTEM_SCOPE = 'uniweb'
package/src/schema.js CHANGED
@@ -19,7 +19,7 @@ import { pathToFileURL } from 'node:url'
19
19
  import { jsxInJsMessage } from './jsx-extension.js'
20
20
  import { areaNames, describeChildren, describePlacement, describeVisuals, lowerChildren } from '@uniweb/schemas/component'
21
21
  import { describeContent, lowerData } from '@uniweb/schemas/content'
22
- import { normalizeData, schemaDeclarationOf } from '@uniweb/schemas/foundation'
22
+ import { normalizeData, normalizePlaceholders, schemaDeclarationOf } from '@uniweb/schemas/foundation'
23
23
  import { rootListSection } from '@uniweb/schemas/conform'
24
24
  import { SECTION_PARAMS, SECTION_KEYS, stickyDeclaration, underHeaderDeclaration, heightDeclaration } from '@uniweb/schemas/section'
25
25
  import { collectSchemaRefs, buildDataSchemaMap, ownSchemaRefs } from './resolve-data-schema.js'
@@ -89,6 +89,12 @@ async function loadMetaFile(filePath) {
89
89
  /**
90
90
  * Find and load meta file for a component directory
91
91
  * Returns null if no meta file found
92
+ *
93
+ * ⭐ A `meta.js` that does not load STOPS THE BUILD, naming the file and the error [Diego,
94
+ * 2026-11-11: "It's okay for the foundation build to fail if it has problems in any `meta.js` or
95
+ * elsewhere."]. ⛔ Until then it warned and went on as if the file were not there: a type at the
96
+ * root of `sections/` lost everything its `meta.js` declares, its name, params, presets, labels and
97
+ * data keys (so it was given no records), and a nested one vanished, under a green build.
92
98
  */
93
99
  export async function loadComponentMeta(componentDir) {
94
100
  const filePath = join(componentDir, META_FILE_NAME)
@@ -99,8 +105,7 @@ export async function loadComponentMeta(componentDir) {
99
105
  const meta = await loadMetaFile(filePath)
100
106
  return { meta, fileName: META_FILE_NAME, filePath }
101
107
  } catch (error) {
102
- console.warn(`Warning: Failed to load ${filePath}:`, error.message)
103
- return null
108
+ throw new Error(`[uniweb] ${filePath} could not be loaded: ${error.message}`, { cause: error })
104
109
  }
105
110
  }
106
111
 
@@ -232,8 +237,9 @@ export async function loadPackageJson(srcDir) {
232
237
  ...normalizeSupports(pkg.uniweb?.supports, packagePath),
233
238
  }
234
239
  } catch (error) {
235
- console.warn(`Warning: Failed to load package.json:`, error.message)
236
- return {}
240
+ // A package.json that is there and cannot be read stops the build, as a `meta.js` does
241
+ // (`loadComponentMeta`): it holds the foundation's identity, and an empty one is a quiet lie.
242
+ throw new Error(`[uniweb] ${packagePath} could not be read: ${error.message}`, { cause: error })
237
243
  }
238
244
  }
239
245
 
@@ -1220,43 +1226,92 @@ function reportSupports(srcDir, authored, derived, emitted) {
1220
1226
  }
1221
1227
 
1222
1228
  /**
1223
- * Warn of a `data:` value `register` will refuse — one the normalized form it sends cannot
1224
- * write (`@uniweb/schemas/foundation`): an inline field map that is not a valid data schema.
1225
- * The build goes on; the site renders the map as before. `register` is where it stops, since
1226
- * a registered schema is written in one spelling per meaning or not at all.
1229
+ * Stop the build on a `data:` value `register` will refuse — one the normalized form it sends
1230
+ * cannot write (`@uniweb/schemas/foundation`): an inline field map that is not a valid data schema.
1231
+ * Every such value is named at once. ⛔ Until 2026-11-11 the build warned and went on, since the
1232
+ * site renders the map as before, and `register` was where it stopped; a foundation build now fails
1233
+ * on a problem in its declarations [Diego, 2026-11-11], as it already did for the other `data:`
1234
+ * declarations it cannot read.
1227
1235
  *
1228
1236
  * @param {Object} components - discovered section types, by name
1229
1237
  * @param {Object} [layouts] - discovered layouts, by name
1230
1238
  * @param {Object} [foundationConfig] - the foundation's `main.js`, whose `data:` reaches every section
1231
1239
  */
1232
- export function reportUnregistrableData(components, layouts = {}, foundationConfig = {}) {
1240
+ export function reportUnregistrableData(components, layouts = {}, foundationConfig = {}, { strict = true } = {}) {
1233
1241
  const owners = [
1234
1242
  ...Object.entries(components).map(([name, entry]) => [`${name} (meta.js)`, entry?.data]),
1235
1243
  ...Object.entries(layouts || {}).map(([name, entry]) => [`layout ${name} (meta.js)`, entry?.data]),
1236
1244
  ['the foundation (main.js)', foundationConfig?.data],
1237
1245
  ]
1246
+ const problems = []
1238
1247
  for (const [owner, data] of owners) {
1239
1248
  try {
1240
1249
  normalizeData(data, { owner })
1241
1250
  } catch (err) {
1242
- console.warn(`Warning: ${err.message} \`uniweb register\` refuses it until it is one.`)
1251
+ problems.push(`${err.message} \`uniweb register\` refuses it too.`)
1243
1252
  }
1244
1253
  }
1254
+ stopOrWarn(problems, strict)
1255
+ }
1256
+
1257
+ /**
1258
+ * The site values the foundation reads, as `main.js` declares them in `placeholders:`: one field
1259
+ * map in the shape an inline `data:` map takes, checked as `register` will normalize it
1260
+ * (`normalizePlaceholders`), and carried in `_self` as written. An editor shows a site's
1261
+ * placeholders as the fields it declares; a page reads them at `website.config.placeholders`, and
1262
+ * the runtime fills no `default`, so a declaration never reaches a page.
1263
+ *
1264
+ * @param {*} placeholders - `main.js`'s `placeholders`, as written
1265
+ * @param {{ strict: boolean }} options - stop, or warn as a site reading its foundation does
1266
+ */
1267
+ function checkPlaceholders(placeholders, { strict }) {
1268
+ if (placeholders === undefined) return
1269
+ try {
1270
+ normalizePlaceholders(placeholders)
1271
+ } catch (err) {
1272
+ stopOrWarn([err.message], strict)
1273
+ }
1274
+ }
1275
+
1276
+ /**
1277
+ * One error naming every declaration problem the build found, so a developer fixes them in one
1278
+ * pass rather than one build at a time.
1279
+ *
1280
+ * @param {string[]} problems - each a sentence that names its owner (`Hero (meta.js): …`)
1281
+ */
1282
+ function declarationsError(problems) {
1283
+ return [`[uniweb] The foundation declares what its build cannot use:`, ...problems.map((p) => ` - ${p}`)].join('\n')
1284
+ }
1285
+
1286
+ /**
1287
+ * The foundation's build stops on them; a site reading its foundation warns of each and goes on
1288
+ * (`buildSchema`'s `strict`).
1289
+ *
1290
+ * @param {string[]} problems
1291
+ * @param {boolean} strict
1292
+ */
1293
+ function stopOrWarn(problems, strict) {
1294
+ if (!problems.length) return
1295
+ if (strict) throw new Error(declarationsError(problems))
1296
+ for (const problem of problems) console.warn(`Warning: ${problem} The foundation's build stops on it.`)
1245
1297
  }
1246
1298
 
1247
1299
  /**
1248
- * Warn about `content` and `children` declarations an editor cannot use — what lowering
1249
- * them could not read (`@uniweb/schemas`, the grammar the editor reads them with). The
1250
- * entry is emitted lowered either way; these are warnings, never refusals.
1300
+ * Stop the build on `content`, `children` and `params` declarations a section type cannot use:
1301
+ * what lowering them could not read (`@uniweb/schemas`, the grammar the editor reads them with),
1302
+ * and a param the component is never given. Every one is named at once [Diego, 2026-11-11: "It's
1303
+ * okay for the foundation build to fail if it has problems in any `meta.js` or elsewhere."]. ⛔ Until
1304
+ * then these were warnings under a green build, and a foundation registered with them.
1251
1305
  *
1252
1306
  * ⭐ A `children.types` entry must name one of this foundation's section types. A hidden
1253
1307
  * one is not a section type at all, and a child of a type nothing provides renders
1254
- * "Component not found". The one false alarm is a type an extension provides, which
1255
- * this foundation cannot see — the message says so.
1308
+ * "Component not found". It stays a WARNING, since it has one false alarm: a type an extension
1309
+ * provides, which this foundation cannot see — the message says so.
1256
1310
  *
1257
1311
  * @param {Object} components - discovered section types, by name
1258
1312
  */
1259
- export function reportPlacementDeclarations(components) {
1313
+ export function reportPlacementDeclarations(components, { strict = true } = {}) {
1314
+ const errors = []
1260
1315
  for (const [name, entry] of Object.entries(components)) {
1261
1316
  // An entry built here was lowered, and kept what it could not read aside; one handed
1262
1317
  // in as written is read now. (A lowered entry reads as itself, with no problems.)
@@ -1267,7 +1322,7 @@ export function reportPlacementDeclarations(components) {
1267
1322
  ...children.problems,
1268
1323
  ]
1269
1324
  for (const problem of problems) {
1270
- console.warn(`Warning: ${name} (meta.js): ${problem}`)
1325
+ errors.push(`${name} (meta.js): ${problem}`)
1271
1326
  }
1272
1327
  for (const type of children.types || []) {
1273
1328
  if (components[type]) continue
@@ -1285,8 +1340,8 @@ export function reportPlacementDeclarations(components) {
1285
1340
  const params = entry.params && typeof entry.params === 'object' ? entry.params : {}
1286
1341
  for (const [param, reserved] of Object.entries(SECTION_PARAMS)) {
1287
1342
  if (reserved.component || !Object.hasOwn(params, param)) continue
1288
- console.warn(
1289
- `Warning: ${name} (meta.js): params declares "${param}", a setting of the section, not of its ` +
1343
+ errors.push(
1344
+ `${name} (meta.js): params declares "${param}", a setting of the section, not of its ` +
1290
1345
  `component — framework applies an author's ${param}: to the section and never passes it to the ` +
1291
1346
  `component, and an editor offers it for every section (@uniweb/schemas/section). Remove it from params:.` +
1292
1347
  (param === 'grid'
@@ -1298,12 +1353,13 @@ export function reportPlacementDeclarations(components) {
1298
1353
  // takes it out before the params are stored, so a param of that name is never given one.
1299
1354
  for (const [key, { is }] of Object.entries(SECTION_KEYS)) {
1300
1355
  if (!Object.hasOwn(params, key)) continue
1301
- console.warn(
1302
- `Warning: ${name} (meta.js): params declares "${key}", a key a section's frontmatter keeps for ` +
1356
+ errors.push(
1357
+ `${name} (meta.js): params declares "${key}", a key a section's frontmatter keeps for ` +
1303
1358
  `itself — ${is} — so the component is never given it (@uniweb/schemas/section). Remove it from params:.`
1304
1359
  )
1305
1360
  }
1306
1361
  }
1362
+ stopOrWarn(errors, strict)
1307
1363
  }
1308
1364
 
1309
1365
  /**
@@ -1319,8 +1375,14 @@ export function reportPlacementDeclarations(components) {
1319
1375
  * @param {{services: string[], blind: boolean}} [derivedSupports] - what the
1320
1376
  * module graph says this foundation reaches for (`foundation/derive-supports.js`).
1321
1377
  * Omitted on a dev rebuild, where nothing reads the result.
1378
+ * @param {Object} [options]
1379
+ * @param {boolean} [options.strict=true] - stop on a declaration the build cannot use (the
1380
+ * foundation's own build, `register`). ⭐ A SITE reading its foundation's declarations passes
1381
+ * false (`foundationSections`, `validate`): it warns as it always did and keeps reading, since
1382
+ * the foundation's build is what stops, and a site step that threw would lose every
1383
+ * declaration in silence (it falls back to a schema.json, or to none).
1322
1384
  */
1323
- export async function buildSchema(srcDir, sectionPaths, derivedSupports = null) {
1385
+ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null, { strict = true } = {}) {
1324
1386
  // Load identity from package.json
1325
1387
  const identity = await loadPackageJson(srcDir)
1326
1388
 
@@ -1328,10 +1390,11 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
1328
1390
  const foundationConfig = await loadFoundationConfig(srcDir)
1329
1391
 
1330
1392
  refuseDataDeclarations('the foundation (main.js)', lowerData(foundationConfig.data))
1393
+ checkPlaceholders(foundationConfig.placeholders, { strict })
1331
1394
 
1332
1395
  // Discover section types
1333
1396
  const components = await discoverComponents(srcDir, sectionPaths)
1334
- reportPlacementDeclarations(components)
1397
+ reportPlacementDeclarations(components, { strict })
1335
1398
 
1336
1399
  // Resolve the data schemas the foundation DEFINES — every file in its `schemas/`
1337
1400
  // folder (`ownSchemaRefs`) — and the ones its section bindings reference, carried
@@ -1361,7 +1424,7 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
1361
1424
  dataSchemas,
1362
1425
  srcDir,
1363
1426
  )
1364
- reportUnregistrableData(components, layouts, foundationConfig)
1427
+ reportUnregistrableData(components, layouts, foundationConfig, { strict })
1365
1428
 
1366
1429
  // Determine extension role
1367
1430
  const isExtension = !!foundationConfig.extension