@uniweb/build 1.23.4 → 1.23.5

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.
@@ -38,7 +38,13 @@ const TEAM_KEYS = Object.freeze(['label'])
38
38
  * An integration line, as a backend takes it. Refused here exactly as a backend refuses them, and no
39
39
  * more: a line this takes, a backend takes.
40
40
  */
41
- const INTEGRATION_KEYS = Object.freeze(['label', 'mapping', 'channel', 'trigger', 'filter', 'enabled', 'reply', 'reply_about'])
41
+ const INTEGRATION_KEYS = Object.freeze(['label', 'mapping', 'channel', 'trigger', 'filter', 'enabled', 'reply', 'reply_about', 'vendor'])
42
+ /**
43
+ * `vendor:`: a compute function the platform runs in place of an address, `'@/courses#grade'` — a
44
+ * compute file the site's foundations carry, named as a mapping is, then `#` and the function it
45
+ * exports. Only on the answering channel, since a function's answer is what the reply reads.
46
+ */
47
+ const VENDOR_FN = /^[A-Za-z_$][A-Za-z0-9_$]*$/
42
48
  /** The one channel whose endpoint answers, so the one a `reply` mapping may sit on. */
43
49
  const REPLYING = 'http'
44
50
  /** `reply_about`: a field of the reply's type, `section.field`. */
@@ -52,7 +58,10 @@ const PAIRS = Object.freeze({
52
58
  email: ['on_create', 'on_match', 'on_change', 'manual'],
53
59
  http: ['on_create', 'on_match', 'on_change', 'manual'],
54
60
  })
55
- /** The channels a line may switch on with `enabled: true`. */
61
+ /**
62
+ * The channels a line may switch on with `enabled: true` — and an `http` line that names a `vendor:`,
63
+ * which has no address for its owner to give first.
64
+ */
56
65
  const ENABLEABLE = Object.freeze(['file', 'feed'])
57
66
 
58
67
  /** In `all`, every member of the home org: the one name there that is not a team. */
@@ -346,6 +355,13 @@ function integrationProblems(integrations) {
346
355
  found.push(`\`${at}.reply_about\` is a field of the reply's type, \`section.field\` — \`identity.submission\` — not ${described(line.reply_about)}.`)
347
356
  }
348
357
  }
358
+ if ('vendor' in line) {
359
+ const problem = vendorRefProblem(`${at}.vendor`, line.vendor)
360
+ if (problem) found.push(problem)
361
+ if (channelOk && line.channel !== REPLYING) {
362
+ found.push(`\`${at}.vendor\`: a compute function answers, so it sits on an \`${REPLYING}\` integration — not a \`${line.channel}\` one.`)
363
+ }
364
+ }
349
365
  if ('filter' in line && !isMap(line.filter)) {
350
366
  found.push(`\`${at}.filter\` is a map — \`filter: { where: { status: sold } }\` — not ${described(line.filter)}.`)
351
367
  }
@@ -356,7 +372,7 @@ function integrationProblems(integrations) {
356
372
  ? `\`${at}.enabled\` is the text \`${line.enabled}\` — YAML reads yes, no, on and off as words. Write \`enabled: true\`, or leave it out.`
357
373
  : `\`${at}.enabled\` is \`true\`, or left out — not ${described(line.enabled)}.`
358
374
  )
359
- } else if (channelOk && !ENABLEABLE.includes(line.channel)) {
375
+ } else if (channelOk && !ENABLEABLE.includes(line.channel) && !(line.channel === REPLYING && 'vendor' in line)) {
360
376
  found.push(
361
377
  `\`${at}.enabled\`: a \`${line.channel}\` integration is switched on by its owner in the admin app, ` +
362
378
  'once its address is given. Leave `enabled` out.'
@@ -367,6 +383,17 @@ function integrationProblems(integrations) {
367
383
  return found
368
384
  }
369
385
 
386
+ /** A compute function's name, `'@/<file>#<function>'` or `'@scope/<file>#<function>'`, or null. */
387
+ function vendorRefProblem(at, ref) {
388
+ const hash = typeof ref === 'string' ? ref.lastIndexOf('#') : -1
389
+ const file = hash > 0 ? ref.slice(0, hash) : null
390
+ const fn = hash > 0 ? ref.slice(hash + 1) : null
391
+ if (!file || !VENDOR_FN.test(fn)) {
392
+ return `\`${at}\` is a compute file and the function it exports — \`'@/courses#grade'\` — not ${described(ref)}.`
393
+ }
394
+ return refNameProblem(at, file, 'compute file')
395
+ }
396
+
370
397
  /** A name that must be `@/x` or `@scope/x`, or null. */
371
398
  function refNameProblem(at, ref, what) {
372
399
  try {
@@ -92,7 +92,9 @@ export function blueprintForWire(blueprint, scope) {
92
92
  const out = {}
93
93
  for (const [key, value] of Object.entries(blueprint)) {
94
94
  if (TYPE_KEYS.includes(key) && isMap(value)) out[key] = qualifiedTypes(key, value, scope)
95
- else if (key === 'integrations' && isMap(value)) out[key] = mappingsNamed(value, (m) => qualifyRef(m, scope))
95
+ else if (key === 'integrations' && isMap(value)) {
96
+ out[key] = mappingsNamed(value, (m) => qualifyRef(m, scope), (file) => qualifyRef(file, scope))
97
+ }
96
98
  else out[key] = value
97
99
  }
98
100
  return out
@@ -102,20 +104,32 @@ export function blueprintForWire(blueprint, scope) {
102
104
  const MAPPING_KEYS = Object.freeze(['mapping', 'reply'])
103
105
 
104
106
  /**
105
- * Each integration line with the mappings it names (`mapping:`, `reply:`) renamed by `rename`;
106
- * nothing else in the line moves — `reply_about` is a field, and a `filter` names fields.
107
+ * Each integration line with the mappings it names (`mapping:`, `reply:`) renamed by `rename`, and
108
+ * the compute file its `vendor:` names (`'@/courses#grade'`: the part before `#`) by `renameVendor`;
109
+ * nothing else in the line moves — the `#export` is the function's own name, `reply_about` is a
110
+ * field, and a `filter` names fields.
107
111
  */
108
- function mappingsNamed(integrations, rename) {
112
+ function mappingsNamed(integrations, rename, renameVendor) {
109
113
  return Object.fromEntries(
110
114
  Object.entries(integrations).map(([id, line]) => {
111
115
  if (!isMap(line)) return [id, line]
112
116
  const out = { ...line }
113
117
  for (const key of MAPPING_KEYS) if (typeof line[key] === 'string') out[key] = rename(line[key])
118
+ const vendor = splitVendorRef(line.vendor)
119
+ if (vendor && renameVendor) out.vendor = `${renameVendor(vendor.file)}#${vendor.fn}`
114
120
  return [id, out]
115
121
  })
116
122
  )
117
123
  }
118
124
 
125
+ /** `'@/courses#grade'` → `{ file: '@/courses', fn: 'grade' }`, or null when it is not that shape. */
126
+ export function splitVendorRef(ref) {
127
+ if (typeof ref !== 'string') return null
128
+ const at = ref.lastIndexOf('#')
129
+ if (at <= 0 || at === ref.length - 1) return null
130
+ return { file: ref.slice(0, at), fn: ref.slice(at + 1) }
131
+ }
132
+
119
133
  /**
120
134
  * Whether two blueprints, each as a `backend` row holds it (`blueprintForWire`), say the same: keys in
121
135
  * any order, lists in theirs. `undefined` and `null` are no blueprint, the same as each other and
@@ -162,7 +176,11 @@ export function blueprintFromWire(wire, { scope = null, own = null, local = null
162
176
  const out = {}
163
177
  for (const [key, value] of Object.entries(isMap(wire) ? wire : {})) {
164
178
  if (key === 'integrations' && isMap(value)) {
165
- out[key] = mappingsNamed(value, (m) => mappingAsFileSpells(m, local?.integrations, scope))
179
+ out[key] = mappingsNamed(
180
+ value,
181
+ (m) => mappingAsFileSpells(m, local?.integrations, scope),
182
+ (file) => vendorAsFileSpells(file, local?.integrations, scope)
183
+ )
166
184
  continue
167
185
  }
168
186
  if (!TYPE_KEYS.includes(key) || !isMap(value)) {
@@ -196,6 +214,18 @@ function mappingAsFileSpells(full, localIntegrations, scope) {
196
214
  return org && full.startsWith(`@${org}/`) ? `@/${full.slice(org.length + 2)}` : full
197
215
  }
198
216
 
217
+ /** A compute file's full name → as a pull writes it, by the rule `mappingAsFileSpells` follows. */
218
+ function vendorAsFileSpells(full, localIntegrations, scope) {
219
+ if (isMap(localIntegrations)) {
220
+ for (const line of Object.values(localIntegrations)) {
221
+ const vendor = isMap(line) ? splitVendorRef(line.vendor) : null
222
+ if (vendor && qualifyRef(vendor.file, scope) === full) return vendor.file
223
+ }
224
+ }
225
+ const org = bareOrg(scope)
226
+ return org && full.startsWith(`@${org}/`) ? `@/${full.slice(org.length + 2)}` : full
227
+ }
228
+
199
229
  /** Each type a file's key names, in full → as the file spells it. */
200
230
  function spellingsOf(map, scope) {
201
231
  const out = new Map()
@@ -325,6 +355,36 @@ export function blueprintWarnings(blueprint, { scope, declared, sending = false
325
355
  }
326
356
  for (const [id, line] of Object.entries(isMap(blueprint.integrations) ? blueprint.integrations : {})) {
327
357
  for (const key of MAPPING_KEYS) out.push(...mappingWarnings(line, id, key, { scoped, scope, declared, sending }))
358
+ out.push(...vendorWarnings(line, id, { scoped, scope, declared, sending }))
359
+ }
360
+ return out
361
+ }
362
+
363
+ /** What the compute function an integration line names (`vendor: '@/courses#grade'`) warns of. */
364
+ function vendorWarnings(line, id, { scoped, scope, declared, sending }) {
365
+ const vendor = isMap(line) ? splitVendorRef(line.vendor) : null
366
+ if (!vendor) return []
367
+ const out = []
368
+ const at = `integrations.${id}.vendor`
369
+ if (!scoped && vendor.file.startsWith('@/') && sending) {
370
+ out.push(
371
+ `${BLUEPRINT_FILE}: \`${at}\` is the foundation's own compute file, and the foundation has no scope yet, ` +
372
+ "so a push sends it as written — the backend never resolves an `@/x`. A foundation's scope is part " +
373
+ "of its name — `name: '@org/<name>'` in its main.js, which `uniweb register` writes."
374
+ )
375
+ }
376
+ if (declared?.vendors) {
377
+ const exports = declared.vendors.get(qualifyRef(vendor.file, scope))
378
+ if (!exports) {
379
+ out.push(
380
+ `${BLUEPRINT_FILE}: \`${at}\` names a compute file none of this site's foundations carries, so a backend ` +
381
+ "started from this site leaves the line out. A foundation's own is a file in src/compute/; a library's is listed in its main.js, `compute: ['@scope/<name>']`."
382
+ )
383
+ } else if (exports.size && !exports.has(vendor.fn)) {
384
+ out.push(
385
+ `${BLUEPRINT_FILE}: \`${at}\` names the function \`${vendor.fn}\`, which \`${vendor.file}\` does not export — it exports ${[...exports].map((e) => `\`${e}\``).join(', ')}.`
386
+ )
387
+ }
328
388
  }
329
389
  return out
330
390
  }
@@ -396,12 +456,18 @@ function readSiteYml(siteRoot) {
396
456
  * @param {string} [opts.foundationDir] - the site's foundation, when a push was handed its folder
397
457
  * @param {object|null} [opts.primary] - the site's foundation's schema, already read by the caller
398
458
  * (the static build's `foundationSections`)
399
- * @returns {Promise<{ types: Set<string>|null, mappings: Set<string>|null, unread: string[] }>} `mappings`:
400
- * the mappings they define, in full, null when `types` is
459
+ * @returns {Promise<{ types: Set<string>|null, mappings: Set<string>|null, vendors: Map<string, Set<string>>|null, unread: string[] }>}
460
+ * `mappings`: the mappings they define, in full; `vendors`: the compute files they carry, in
461
+ * full → the functions each exports (empty when a library's could not be read); each null
462
+ * when `types` is
401
463
  */
402
464
  export async function siteDeclaredTypes(siteRoot, siteYml, { scope = null, foundationDir, primary } = {}) {
403
465
  const types = new Set()
404
466
  const mappings = new Set()
467
+ const vendors = new Map()
468
+ const addVendors = (schema, at) => {
469
+ for (const [ref, v] of Object.entries(schema._compute || {})) vendors.set(qualifyRef(ref, at), new Set(v?.exports || []))
470
+ }
405
471
  const unread = []
406
472
  const dir = foundationDir ? resolve(foundationDir) : localFoundationDir(siteRoot, siteYml)
407
473
  if (!dir) {
@@ -412,6 +478,7 @@ export async function siteDeclaredTypes(siteRoot, siteYml, { scope = null, found
412
478
  else {
413
479
  for (const ref of Object.keys(schema.dataSchemas || {})) types.add(qualifyRef(ref, scope))
414
480
  for (const ref of Object.keys(schema._mappings || {})) mappings.add(qualifyRef(ref, scope))
481
+ addVendors(schema, scope)
415
482
  }
416
483
  }
417
484
  for (const entry of Array.isArray(siteYml?.extensions) ? siteYml.extensions : []) {
@@ -436,8 +503,14 @@ export async function siteDeclaredTypes(siteRoot, siteYml, { scope = null, found
436
503
  types.add(qualifyRef(ref, extScope))
437
504
  }
438
505
  for (const ref of Object.keys(schema._mappings || {})) mappings.add(qualifyRef(ref, extScope))
506
+ addVendors(schema, extScope)
507
+ }
508
+ return {
509
+ types: unread.length ? null : types,
510
+ mappings: unread.length ? null : mappings,
511
+ vendors: unread.length ? null : vendors,
512
+ unread,
439
513
  }
440
- return { types: unread.length ? null : types, mappings: unread.length ? null : mappings, unread }
441
514
  }
442
515
 
443
516
  /** The site's foundation's folder, when it is in the project — else null (a catalog ref, a URL). */
@@ -13,7 +13,9 @@
13
13
  * …the §3 declaration (from data-schema.js's lowering)…
14
14
  * - model: "@uniweb/mapping-schema" # one per mapping this foundation defines (src/mappings/)
15
15
  * name, label?, description?, rules: { model, keys_from?, …the rest as written }
16
- * - model: "@uniweb/foundation-schema" # the foundation (info/schema/i18n/data-schemas/mappings)
16
+ * - model: "@uniweb/vendor-schema" # one per compute file this foundation defines (src/compute/)
17
+ * name, exports, sha256, size # the file itself goes up after, by its sha256
18
+ * - model: "@uniweb/foundation-schema" # the foundation (info/schema/i18n/data-schemas/mappings/vendors)
17
19
  *
18
20
  * `buildSchemaOnlyPackage` (below) assembles the foundation-LESS variant — only
19
21
  * `@uniweb/data-schema` entities, no foundation-schema — for a schemas-only
@@ -38,6 +40,7 @@ import { checkFoundationName, checkRegistrationScope, splitFoundationName } from
38
40
  const FOUNDATION_SCHEMA = '@uniweb/foundation-schema'
39
41
  const DATA_SCHEMA = '@uniweb/data-schema'
40
42
  const MAPPING_SCHEMA = '@uniweb/mapping-schema'
43
+ const VENDOR_SCHEMA = '@uniweb/vendor-schema'
41
44
 
42
45
  // @uniweb/build's own version, for the exporter envelope when the caller supplies
43
46
  // none. Safe fallback if package.json isn't reachable (e.g. bundled contexts).
@@ -67,9 +70,12 @@ try {
67
70
  * in the foundation-schema entity's `info.digest`; the backend stores it
68
71
  * OPAQUE and returns it on the foundation-latest read so `publish`/`status`
69
72
  * can detect "code changed since release" with no local state.
73
+ * @param {Object} [params.vendors] - `{ '@/<name>': { exports, sha256, size } }`, the compute files
74
+ * the foundation defines, read from disk by the caller (`computeFileDigest`) when it registers.
75
+ * `schema._compute` names them and the library ones; this gives the bytes' digest.
70
76
  * @returns {Object} the `.uwx` document (uwx/1; entities, names only, no uuids).
71
77
  */
72
- export function buildRegistryPackage({ schema, foundationDir, scope, exporter, exportedAt, digest, runtime } = {}) {
78
+ export function buildRegistryPackage({ schema, foundationDir, scope, exporter, exportedAt, digest, runtime, vendors } = {}) {
73
79
  const self = schema?._self
74
80
  if (!self || !self.name || !self.version) {
75
81
  throw new Error('buildRegistryPackage: schema._self with name + version is required')
@@ -97,6 +103,18 @@ export function buildRegistryPackage({ schema, foundationDir, scope, exporter, e
97
103
  .sort((a, b) => a.localeCompare(b))
98
104
  .map((name) => ({ name }))
99
105
 
106
+ const vendorEntities = buildVendorEntities(vendors || {}, scoped)
107
+ // Its own compute files, and the library ones its main.js carries (`_compute` keys in full), which
108
+ // their library registers and uploads: a foundation names those, and registers none.
109
+ const vendorRefs = [
110
+ ...new Set([
111
+ ...vendorEntities.map((e) => e.name),
112
+ ...Object.keys(schema._compute || {}).filter((ref) => !ref.startsWith('@/')),
113
+ ]),
114
+ ]
115
+ .sort((a, b) => a.localeCompare(b))
116
+ .map((name) => ({ name }))
117
+
100
118
  const foundationEntity = {
101
119
  model: FOUNDATION_SCHEMA,
102
120
  info: buildInfo(self, org, digest, runtime),
@@ -104,11 +122,12 @@ export function buildRegistryPackage({ schema, foundationDir, scope, exporter, e
104
122
  i18n: { locales: loadI18nLocales(foundationDir) },
105
123
  'data-schemas': { refs: buildRefs(dataSchemas, scoped) },
106
124
  ...(mappingRefs.length && { mappings: { refs: mappingRefs } }),
125
+ ...(vendorRefs.length && { vendors: { refs: vendorRefs } }),
107
126
  }
108
127
 
109
- // Data schemas, then mappings, then the foundation: a backend installs them in the order they
110
- // arrive, and each names only what came before it or is already registered.
111
- return wrapEntities([...dataSchemaEntities, ...mappingEntities, foundationEntity], exporter, exportedAt)
128
+ // Data schemas, then mappings, then compute files, then the foundation: a backend installs them in
129
+ // the order they arrive, and each names only what came before it or is already registered.
130
+ return wrapEntities([...dataSchemaEntities, ...mappingEntities, ...vendorEntities, foundationEntity], exporter, exportedAt)
112
131
  }
113
132
 
114
133
  /**
@@ -125,12 +144,14 @@ export function buildRegistryPackage({ schema, foundationDir, scope, exporter, e
125
144
  * schemas the package defines (from `collectStandaloneSchemas`).
126
145
  * @param {Object} [params.mappings] - map `{ '@/<name>': declaration }` of the
127
146
  * mappings it defines (`buildMappingMap` over its `mappings/`).
147
+ * @param {Object} [params.vendors] - map `{ '@/<name>': { exports, sha256, size } }` of the
148
+ * compute files it defines (its `compute/`).
128
149
  * @param {string} [params.scope] - org scope (`@std`/`std`) resolving `@/x` -> `@std/x`.
129
150
  * @param {Object} [params.exporter] - `{ tool, version, instance }` envelope.
130
151
  * @param {string} [params.exportedAt] - ISO timestamp (default: now).
131
152
  * @returns {Object} the `.uwx` document (uwx/1; no foundation, no uuids).
132
153
  */
133
- export function buildSchemaOnlyPackage({ schemas, mappings, scope, exporter, exportedAt } = {}) {
154
+ export function buildSchemaOnlyPackage({ schemas, mappings, vendors, scope, exporter, exportedAt } = {}) {
134
155
  // ⛔ The producer's own guard, as `buildInfo`'s name check is for a foundation:
135
156
  // `uniweb register` refuses a reserved scope before it gets here.
136
157
  const reserved = checkRegistrationScope(scope)
@@ -138,10 +159,11 @@ export function buildSchemaOnlyPackage({ schemas, mappings, scope, exporter, exp
138
159
  const { entities, scoped } = buildDataSchemaEntities(schemas || {}, scope)
139
160
  // A library's mappings (its `mappings/`) after its types, as in a foundation's package.
140
161
  const mappingEntities = buildMappingEntities(mappings || {}, scoped)
141
- if (entities.length === 0 && mappingEntities.length === 0) {
142
- throw new Error('buildSchemaOnlyPackage: no data schemas or mappings to register (expected a map of "@/<name>" -> declaration).')
162
+ const vendorEntities = buildVendorEntities(vendors || {}, scoped)
163
+ if (entities.length === 0 && mappingEntities.length === 0 && vendorEntities.length === 0) {
164
+ throw new Error('buildSchemaOnlyPackage: no data schemas, mappings or compute files to register (expected a map of "@/<name>" -> declaration).')
143
165
  }
144
- return wrapEntities([...entities, ...mappingEntities], exporter, exportedAt)
166
+ return wrapEntities([...entities, ...mappingEntities, ...vendorEntities], exporter, exportedAt)
145
167
  }
146
168
 
147
169
  // The scope a foundation registers under: the one in its name, else `scope`.
@@ -229,6 +251,29 @@ function buildMappingEntities(mappings, scoped) {
229
251
  return ordered
230
252
  }
231
253
 
254
+ /**
255
+ * One `@uniweb/vendor-schema` entity per compute file the package defines: its full name, the
256
+ * functions it exports (sorted), and the `sha256` and `size` of its bytes as on disk. No source: the
257
+ * file goes up after the call, addressed by that `sha256` (`vendor-uploads`). No `label` or
258
+ * `description`: a `.js` file has nowhere to declare them.
259
+ *
260
+ * @param {Object<string, { exports: string[], sha256: string, size: number }>} vendors
261
+ * @param {(ref: string) => string} scoped - `@/x` → the registration scope's name
262
+ * @returns {object[]}
263
+ */
264
+ function buildVendorEntities(vendors, scoped) {
265
+ return Object.entries(vendors)
266
+ .filter(([ref]) => ref.startsWith('@/'))
267
+ .sort(([a], [b]) => a.localeCompare(b))
268
+ .map(([ref, v]) => ({
269
+ model: VENDOR_SCHEMA,
270
+ name: scoped(ref),
271
+ exports: [...(v.exports || [])].sort(),
272
+ sha256: v.sha256,
273
+ size: v.size,
274
+ }))
275
+ }
276
+
232
277
  /**
233
278
  * The data schemas in an order a backend can install one at a time: a schema another one in
234
279
  * the package references comes BEFORE it — alphabetical otherwise, so the order is stable.
@@ -320,7 +365,7 @@ function buildInfo(self, org, digest, runtime) {
320
365
  }
321
366
 
322
367
  // The foundation schema an editor reads: the whole renderable schema.json MINUS identity
323
- // and MINUS dataSchemas and _mappings (each registered as its own entity), shipped as one object the backend stores and serves, and never
368
+ // and MINUS dataSchemas, _mappings and _compute (each registered as its own entity, or named by ref), shipped as one object the backend stores and serves, and never
324
369
  // reads into (custodian).
325
370
  //
326
371
  // ⭐ IN ITS NORMALIZED FORM — `schemaFormat: 3` (`@uniweb/schemas/foundation`, ruled
@@ -333,7 +378,7 @@ function buildInfo(self, org, digest, runtime) {
333
378
  // It throws for a `data:` value that cannot be normalized — an inline field map that is
334
379
  // not a valid data schema — naming the component and the key; the build warns of it first.
335
380
  function buildSchemaBlob(schema, org) {
336
- const { dataSchemas: _ds, _mappings: _m, ...rest } = schema
381
+ const { dataSchemas: _ds, _mappings: _m, _compute: _v2, ...rest } = schema
337
382
  // Every key hoisted into `info` is stripped here, so the wire carries each
338
383
  // fact ONCE. Two copies of one fact is a drift liability, and the copy inside
339
384
  // an opaque blob is the one nobody would think to update.