@uniweb/build 1.24.2 → 1.24.3

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uniweb/build",
3
- "version": "1.24.2",
3
+ "version": "1.24.3",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -57,12 +57,12 @@
57
57
  "js-yaml": "^4.3.2",
58
58
  "sharp": "^0.35.5",
59
59
  "yaml": "^2.5.0",
60
- "@uniweb/theming": "~1.3.2",
61
- "@uniweb/schemas": "~1.7.4",
60
+ "@uniweb/content-writer": "~1.3.2",
62
61
  "@uniweb/content-reader": "~1.5.11",
63
- "@uniweb/semantic-parser": "~1.13.5",
64
62
  "@uniweb/projections": "~1.2.17",
65
- "@uniweb/content-writer": "~1.3.2"
63
+ "@uniweb/semantic-parser": "~1.13.5",
64
+ "@uniweb/theming": "~1.3.2",
65
+ "@uniweb/schemas": "~1.7.4"
66
66
  },
67
67
  "optionalDependencies": {
68
68
  "@uniweb/runtime": "~1.6.5"
@@ -381,38 +381,75 @@ export function deriveRecordsSupport(components, foundationData) {
381
381
  *
382
382
  * | authored | derived | emitted |
383
383
  * |---|---|---|
384
- * | absent | some | the derived set |
384
+ * | absent | some, nothing blind | the derived set |
385
385
  * | absent | none, nothing blind | ⭐ `[]` — a **proven** none, not an assumed one |
386
- * | absent | none, something blind | ⛔ nothing — UNKNOWN, honestly |
386
+ * | absent | anything, something blind | ⛔ nothing — UNKNOWN, honestly |
387
387
  * | a list | any | the union |
388
388
  * | `[]` | some | the union, with a warning: the evidence contradicts the claim |
389
389
  *
390
- * ⭐ **The union only ever grows the set**, so the failure the authored-only
391
- * design guarded against — publishing a set shorter than the truth — stays
392
- * unreachable: whatever a developer wrote is still there.
390
+ * ⭐ **A published list is COMPLETE** (since 2026-11-16). So a blind derivation
391
+ * with nothing authored publishes nothing even when it found some services: a
392
+ * partial list would read as "these and only these" to a reader that hides what is
393
+ * not listed. Until then such a list went
394
+ * out short with a warning, and a reader could trust it only in the presence
395
+ * direction. A list the developer authored is theirs to make complete, and the build
396
+ * says so when it was blind (`reportSupports`).
397
+ *
398
+ * ⭐ **The union only ever grows the set**, so whatever a developer wrote is still
399
+ * there — `required` (`uniweb.requires`) included: a service a foundation cannot work
400
+ * without is one it supports, so `requires ⊆ supports` holds by construction.
393
401
  *
394
402
  * @param {string[]|undefined} authored - normalized `uniweb.supports`; `undefined` when absent
395
403
  * @param {{services: string[], blind: boolean}|null} derived - null when not derived (a dev rebuild)
404
+ * @param {string[]} [required] - `composeRequires`' result
396
405
  * @returns {{supports?: string[]}} spread into `_self`; `{}` keeps the key absent
397
406
  */
398
- export function composeSupports(authored, derived) {
407
+ export function composeSupports(authored, derived, required = []) {
399
408
  // An authored name this field may not carry is dropped HERE rather than at
400
409
  // its source: `package.json` is the developer's file, and rewriting it is
401
410
  // `doctor --fix`'s job. `reportSupports` says what was dropped and why.
402
411
  // ⛔ Absence must survive the filter — `undefined` is UNKNOWN, `[]` is a
403
412
  // declaration, and mapping one to the other loses a state.
404
413
  const declared = authored === undefined ? undefined : nameable(authored)
414
+ const needs = nameable(required || [])
415
+ const nothingAuthored = declared === undefined && needs.length === 0
405
416
 
406
417
  // No derivation ran (dev rebuild): the authored value is the whole answer,
407
418
  // and an absent one stays absent.
408
- if (!derived) return declared === undefined ? {} : { supports: declared }
419
+ if (!derived) return nothingAuthored ? {} : { supports: union(declared, needs) }
409
420
 
410
421
  const { services, blind } = derived
411
422
 
412
- if (declared === undefined && services.length === 0) {
413
- return blind ? {} : { supports: [] }
414
- }
423
+ // Nothing authored: the derivation is the whole answer, if it saw everything.
424
+ if (nothingAuthored) return blind ? {} : { supports: union(services) }
425
+
426
+ return { supports: union(declared, services, needs) }
427
+ }
428
+
429
+ /**
430
+ * Compose `info.requires` — the services a foundation cannot work without.
431
+ *
432
+ * ⭐ **Authored only, never derived.** Code that reaches a service and code that cannot
433
+ * work without one look the same in the bundle: a search box shown only when
434
+ * `isSearchEnabled()` is true reaches `search` exactly as a course site reaches
435
+ * `backend`. Telling them apart would mean proving a code path has no fallback.
436
+ *
437
+ * ⭐ **Emitted only when authored.** A foundation that declares nothing sends no
438
+ * `requires`, so its register document is what it was before the field existed and
439
+ * any backend takes it. One that declares it (`[]` included) says two things: what it
440
+ * cannot work without, and that its `supports`, when present, is complete
441
+ * (`composeSupports`). Absent means unknown: nothing required, and `supports` a lower
442
+ * bound. A backend that predates the field refuses a document carrying it, so only an
443
+ * author who opts in needs one that knows it.
444
+ *
445
+ * @param {string[]|undefined} authored - normalized `uniweb.requires`
446
+ * @returns {string[]|undefined} sorted; undefined when nothing was authored
447
+ */
448
+ export function composeRequires(authored) {
449
+ return authored === undefined ? undefined : union(nameable(authored))
450
+ }
415
451
 
416
- const union = [...new Set([...(declared || []), ...services])].sort()
417
- return { supports: union }
452
+ /** Sorted, de-duplicated union of name lists; `undefined` lists contribute nothing. */
453
+ function union(...lists) {
454
+ return [...new Set(lists.flatMap((l) => l || []))].sort()
418
455
  }
package/src/schema.js CHANGED
@@ -25,6 +25,7 @@ import { SECTION_PARAMS, SECTION_KEYS, stickyDeclaration, underHeaderDeclaration
25
25
  import { collectSchemaRefs, buildDataSchemaMap, ownSchemaRefs } from './resolve-data-schema.js'
26
26
  import { buildMappingMap } from './foundation/mappings.js'
27
27
  import {
28
+ composeRequires,
28
29
  composeSupports,
29
30
  deriveRecordsSupport,
30
31
  unnameableIn,
@@ -147,17 +148,24 @@ export async function loadComponentMeta(componentDir) {
147
148
  * Sorted and de-duplicated so a re-export of one foundation version is
148
149
  * byte-identical — the same reason `buildRefs` sorts.
149
150
  *
150
- * @param {*} value - the raw `uniweb.supports` value, if any
151
+ * ⭐ `uniweb.requires` — the services the foundation cannot work without — takes the
152
+ * same grammar through the same function (`key`), so the two lists can never be
153
+ * spelled differently. What it becomes on the wire is `composeRequires`' to say.
154
+ *
155
+ * @param {*} value - the raw `uniweb.supports` (or `uniweb.requires`) value, if any
151
156
  * @param {string} packagePath - for the warning message
152
- * @returns {{supports?: string[]}} `{}` when undeclared
157
+ * @param {'supports'|'requires'} [key]
158
+ * @returns {{supports?: string[]}} `{}` when undeclared, keyed by `key`
153
159
  */
154
- function normalizeSupports(value, packagePath) {
160
+ function normalizeSupports(value, packagePath, key = 'supports') {
155
161
  if (value === undefined || value === null) return {}
156
162
 
157
163
  if (!Array.isArray(value)) {
158
164
  console.warn(
159
- `Warning: ${packagePath} declares \`uniweb.supports\` as ${typeof value}; expected an array of service names. Ignoring it.\n` +
160
- ` An ignored declaration reads downstream as UNKNOWN, not as "supports nothing".`,
165
+ `Warning: ${packagePath} declares \`uniweb.${key}\` as ${typeof value}; expected an array of service names. Ignoring it.\n` +
166
+ (key === 'supports'
167
+ ? ` An ignored declaration reads downstream as UNKNOWN, not as "supports nothing".`
168
+ : ` An ignored declaration requires nothing.`),
161
169
  )
162
170
  return {}
163
171
  }
@@ -170,11 +178,11 @@ function normalizeSupports(value, packagePath) {
170
178
  }
171
179
  if (dropped.length > 0) {
172
180
  console.warn(
173
- `Warning: ${packagePath} has ${dropped.length} non-name entr${dropped.length === 1 ? 'y' : 'ies'} in \`uniweb.supports\`. Ignoring ${dropped.length === 1 ? 'it' : 'them'}.`,
181
+ `Warning: ${packagePath} has ${dropped.length} non-name entr${dropped.length === 1 ? 'y' : 'ies'} in \`uniweb.${key}\`. Ignoring ${dropped.length === 1 ? 'it' : 'them'}.`,
174
182
  )
175
183
  }
176
184
 
177
- return { supports: [...new Set(names)].sort() }
185
+ return { [key]: [...new Set(names)].sort() }
178
186
  }
179
187
 
180
188
  /**
@@ -235,6 +243,8 @@ export async function loadPackageJson(srcDir) {
235
243
  // Spread rather than assigned so an absent declaration stays ABSENT — see
236
244
  // normalizeSupports for why that is load-bearing.
237
245
  ...normalizeSupports(pkg.uniweb?.supports, packagePath),
246
+ // `uniweb.requires`, the same grammar: the services it cannot work without.
247
+ ...normalizeSupports(pkg.uniweb?.requires, packagePath, 'requires'),
238
248
  }
239
249
  } catch (error) {
240
250
  // A package.json that is there and cannot be read stops the build, as a `meta.js` does
@@ -1136,14 +1146,15 @@ export async function discoverComponents(srcDir, sectionPaths = DEFAULT_SECTION_
1136
1146
  * developer is working.
1137
1147
  *
1138
1148
  * @param {string} srcDir
1139
- * @param {string[]|undefined} authored - normalized `uniweb.supports`
1149
+ * @param {string[]|undefined} authored - normalized `uniweb.supports` (or `uniweb.requires`)
1150
+ * @param {'supports'|'requires'} [key]
1140
1151
  * @throws {Error} naming each old name and the new one
1141
1152
  */
1142
- function refuseRenamedSupports(srcDir, authored) {
1153
+ function refuseRenamedSupports(srcDir, authored, key = 'supports') {
1143
1154
  const renamed = (authored || []).filter((s) => RENAMED_SERVICES[s])
1144
1155
  if (!renamed.length) return
1145
1156
  throw new Error(
1146
- `${srcDir}/package.json: \`uniweb.supports\` names ${renamed.map((s) => `\`${s}\``).join(', ')}, which is now ` +
1157
+ `${srcDir}/package.json: \`uniweb.${key}\` names ${renamed.map((s) => `\`${s}\``).join(', ')}, which is now ` +
1147
1158
  `${renamed.map((s) => `\`${RENAMED_SERVICES[s]}\``).join(', ')} — the site's own backend is the \`backend\` ` +
1148
1159
  'service. Rename it in package.json.',
1149
1160
  )
@@ -1162,23 +1173,27 @@ function refuseRenamedSupports(srcDir, authored) {
1162
1173
  * read in a diff — a build that rewrites source on every run is a surprise, and
1163
1174
  * the artifact is already correct without it.
1164
1175
  */
1165
- function reportSupports(srcDir, authored, derived, emitted) {
1176
+ function reportSupports(srcDir, authored, derived, emitted, required) {
1166
1177
  // ⛔ BEFORE the dev-rebuild bail: a name this field may not carry is dropped
1167
1178
  // from what ships, and a developer who typed one has to hear it. Left below
1168
1179
  // the bail it would be silent in dev, which is where they are working.
1169
- const dropped = unnameableIn(authored)
1170
- if (dropped.length > 0) {
1171
- console.warn(
1172
- `Warning: ${srcDir}/package.json declares \`uniweb.supports: ${dropped.join(', ')}\`, ` +
1173
- `which this field does not carry. A foundation renders no surface for it — the runtime ` +
1174
- `handles it for every foundation alike — so naming it would tell a consumer that any ` +
1175
- `foundation NOT naming it lacks the capability, which is false. Dropped.`,
1176
- )
1180
+ for (const [key, names] of [['supports', authored], ['requires', required]]) {
1181
+ const dropped = unnameableIn(names)
1182
+ if (dropped.length > 0) {
1183
+ console.warn(
1184
+ `Warning: ${srcDir}/package.json declares \`uniweb.${key}: ${dropped.join(', ')}\`, ` +
1185
+ `which this field does not carry. A foundation renders no surface for it — the runtime ` +
1186
+ `handles it for every foundation alike — so naming it would tell a consumer that any ` +
1187
+ `foundation NOT naming it lacks the capability, which is false. Dropped.`,
1188
+ )
1189
+ }
1177
1190
  }
1178
1191
 
1179
1192
  if (!derived) return
1180
1193
 
1181
- const added = (emitted || []).filter((s) => !(authored || []).includes(s))
1194
+ // What the BUNDLE added: a required name the code never reaches is said below, and is
1195
+ // not "derived".
1196
+ const added = (emitted || []).filter((s) => derived.services.includes(s) && !(authored || []).includes(s))
1182
1197
 
1183
1198
  if (added.length > 0) {
1184
1199
  const list = added.join(', ')
@@ -1200,26 +1215,36 @@ function reportSupports(srcDir, authored, derived, emitted) {
1200
1215
  }
1201
1216
  }
1202
1217
 
1218
+ // A required service the code never reaches: published as declared (a need is the
1219
+ // developer's claim, and the reach may be a computed name), but likely a typo or a
1220
+ // leftover, and a site would have it locked on for nothing.
1221
+ const unreached = (composeRequires(required) || []).filter((s) => !derived.services.includes(s))
1222
+ if (unreached.length > 0) {
1223
+ console.warn(
1224
+ `Warning: ${srcDir}/package.json declares \`uniweb.requires: ${unreached.join(', ')}\`, ` +
1225
+ `but no code in the bundle reaches ${unreached.length === 1 ? 'it' : 'them'}. ` +
1226
+ `A site using this foundation will have ${unreached.length === 1 ? 'it' : 'them'} always on. ` +
1227
+ `Check the name, unless the code reaches ${unreached.length === 1 ? 'it' : 'them'} by a computed name.`,
1228
+ )
1229
+ }
1230
+
1203
1231
  // ⛔ WARN WHENEVER THE DERIVATION WAS BLIND — not only when it came back empty.
1204
1232
  //
1205
- // This used to require an empty result, which left the more likely case
1206
- // silent: a foundation that reaches `submit` through a literal and `booking`
1207
- // through a computed name publishes `["submit"]` — short, with no warning, and
1208
- // the one person who could fix it never hears about it.
1209
- //
1210
- // ⭐ That is what makes the lower bound tolerable. How often a foundation
1211
- // computes a service name is unknowable from here — foundations are
1212
- // third-party — but it does not need to be known, because the build detects
1213
- // its own blindness and can say so to the developer at the moment they build.
1233
+ // A published list is complete (`composeSupports`), so a blind derivation with
1234
+ // nothing authored publishes NO list, even when it found some services: the
1235
+ // developer is the one person who can complete it. With something authored, the
1236
+ // authored list is published and claimed complete, so they must hear the build
1237
+ // could not check it.
1214
1238
  if (derived.blind) {
1215
- const empty = emitted === undefined || emitted.length === 0
1239
+ const found = derived.services.length > 0 ? ` It found ${derived.services.join(', ')}.` : ''
1216
1240
  console.warn(
1217
- empty
1241
+ emitted === undefined
1218
1242
  ? `Warning: a service is resolved by a computed name, so \`uniweb.supports\` cannot be ` +
1219
- `derived and is left undeclared. List it in package.json to publish it.`
1220
- : `Warning: a service is resolved by a computed name, so the derived ` +
1221
- `\`uniweb.supports\` may be incomplete. Add any service missing from ` +
1222
- `[${(emitted || []).join(', ')}] to package.json.`,
1243
+ `derived completely and is left undeclared — a published list must be complete.${found} ` +
1244
+ `List every service the foundation uses in package.json to publish it.`
1245
+ : `Warning: a service is resolved by a computed name, so the build cannot check that ` +
1246
+ `\`uniweb.supports\` [${emitted.join(', ')}] is complete, and a consumer reads it as complete. ` +
1247
+ `Add any service missing from it to package.json.`,
1223
1248
  )
1224
1249
  for (const at of derived.blindAt || []) console.warn(` at ${at}`)
1225
1250
  }
@@ -1493,6 +1518,7 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null,
1493
1518
  // convenience — the artifact would disagree with itself depending on which
1494
1519
  // command wrote it. One rule: the derivation runs on a real build.
1495
1520
  refuseRenamedSupports(srcDir, identity.supports)
1521
+ refuseRenamedSupports(srcDir, identity.requires, 'requires')
1496
1522
  const derived = derivedSupports && {
1497
1523
  ...derivedSupports,
1498
1524
  services: deriveRecordsSupport(components, foundationConfig.data)
@@ -1500,8 +1526,11 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null,
1500
1526
  : derivedSupports.services,
1501
1527
  }
1502
1528
 
1503
- const supports = composeSupports(identity.supports, derived)
1504
- reportSupports(srcDir, identity.supports, derived, supports.supports)
1529
+ // `requires` is authored only, and emitted only when authored (`composeRequires`): its
1530
+ // presence tells a reader the `supports` beside it is complete. It is unioned into `supports`.
1531
+ const requires = composeRequires(identity.requires)
1532
+ const supports = composeSupports(identity.supports, derived, requires)
1533
+ reportSupports(srcDir, identity.supports, derived, supports.supports, identity.requires)
1505
1534
 
1506
1535
  // The foundation's name, by the one rule every reader shares (`foundation-name.js`):
1507
1536
  // `main.js`'s `name`, else `package.json`'s. ⚠️ Until 2026-09-21 the `main.js` value
@@ -1514,6 +1543,7 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null,
1514
1543
  ...configWithoutExtension,
1515
1544
  ...identity,
1516
1545
  ...supports,
1546
+ ...(requires && { requires }),
1517
1547
  ...(name && { name }),
1518
1548
  ...(foundationConfig.description && { description: foundationConfig.description }),
1519
1549
  ...(defaultLayout && { defaultLayout }),
@@ -90,6 +90,10 @@ export function foundationSchemaToEntity(schema, opts = {}) {
90
90
  // "none"; an ABSENT key means UNKNOWN. Mirrors `buildInfo` in
91
91
  // `registry-package.js`, which is the path `uniweb register` actually takes.
92
92
  if (Array.isArray(self.supports)) info.supports = self.supports
93
+ // The services it cannot work without (`uniweb.requires`, `composeRequires`). A build
94
+ // that knows the field always writes it, `[]` included, and its presence is what says
95
+ // `supports` is complete; ABSENT means a build from before the field.
96
+ if (Array.isArray(self.requires)) info.requires = self.requires
93
97
 
94
98
  // ── schema — the whole renderable schema.json minus identity and minus
95
99
  // dataSchemas, shipped WHOLE as one opaque blob. ───────────────────────────
@@ -100,6 +104,7 @@ export function foundationSchemaToEntity(schema, opts = {}) {
100
104
  description: _d,
101
105
  role: _r,
102
106
  supports: _s,
107
+ requires: _q,
103
108
  ...selfConfig
104
109
  } = rest._self || {}
105
110
  const schemaBlob = { ...rest, _self: selfConfig }
@@ -361,6 +361,10 @@ function buildInfo(self, org, digest, runtime) {
361
361
  // "none" and must survive as one, while an ABSENT key means UNKNOWN — the
362
362
  // same three-state rule `runtime` states above, for the same reason.
363
363
  if (Array.isArray(self.supports)) info.supports = self.supports
364
+ // The services it cannot work without (`uniweb.requires`, `composeRequires`). A build
365
+ // that knows the field always writes it, `[]` included, and its presence is what says
366
+ // `supports` is complete; ABSENT means a build from before the field.
367
+ if (Array.isArray(self.requires)) info.requires = self.requires
364
368
  return info
365
369
  }
366
370
 
@@ -382,7 +386,7 @@ function buildSchemaBlob(schema, org) {
382
386
  // Every key hoisted into `info` is stripped here, so the wire carries each
383
387
  // fact ONCE. Two copies of one fact is a drift liability, and the copy inside
384
388
  // an opaque blob is the one nobody would think to update.
385
- const { name: _n, version: _v, description: _d, role: _r, supports: _s, ...selfConfig } =
389
+ const { name: _n, version: _v, description: _d, role: _r, supports: _s, requires: _q, ...selfConfig } =
386
390
  rest._self || {}
387
391
  return normalizeFoundationSchema({ ...rest, _self: selfConfig }, { scope: org || undefined })
388
392
  }