@uniweb/build 1.22.0 → 1.23.1

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.
@@ -2607,6 +2607,28 @@ function payloadSiteConfig(siteConfig) {
2607
2607
  return runtimeSiteConfig
2608
2608
  }
2609
2609
 
2610
+ /**
2611
+ * Warn when a page writes `{name}` for one of the site's placeholders and the foundation has no
2612
+ * content handler to resolve it, so the page prints the braces. A placeholder no page writes
2613
+ * says nothing: a foundation may read it as a site value (`website.config.placeholders`).
2614
+ *
2615
+ * @param {string[]} names - the site's placeholder names, or none when the foundation resolves them
2616
+ * @param {Array<object>} pages - the collected pages
2617
+ */
2618
+ function warnUnresolvedPlaceholders(names, pages) {
2619
+ if (!names.length) return
2620
+ const escaped = names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
2621
+ const written = new RegExp(`\\{\\s*(${escaped.join('|')})(?=[\\s.}])`, 'g')
2622
+ const text = JSON.stringify(pages)
2623
+ const used = [...new Set([...text.matchAll(written)].map((m) => m[1]))]
2624
+ if (!used.length) return
2625
+ console.warn(
2626
+ `[uniweb] Pages write ${used.map((n) => `\`{${n}}\``).join(', ')}, which site.yml declares under \`placeholders:\`, ` +
2627
+ `but the foundation has no \`handlers.content\` to resolve them — those pages render the braces as text.\n` +
2628
+ `[uniweb] A foundation opts in with \`handlers: createLoomHandlers({ vars })\` from @uniweb/loom.`
2629
+ )
2630
+ }
2631
+
2610
2632
  /** What this process has said of a site's `blueprint.yml` (`collectSiteContent`). */
2611
2633
  const saidOfBlueprint = new Set()
2612
2634
 
@@ -2727,13 +2749,16 @@ export async function collectSiteContent(sitePath, options = {}) {
2727
2749
  // ⚖️ A WARNING, never an error: the site may be mid-migration, or the author
2728
2750
  // may be about to switch foundations, and a declared-but-unread value harms
2729
2751
  // nothing. Same rule as the retired-`fetcher:` keys above — warn once, carry on.
2730
- if (siteConfig.placeholders && !hasContentHandler) {
2731
- console.warn(
2732
- `[uniweb] site.yml declares \`placeholders:\` but the foundation has no \`handlers.content\`, ` +
2733
- `so nothing will resolve them — pages will render the literal \`{name}\` text.\n` +
2734
- `[uniweb] A foundation opts in with \`handlers: createLoomHandlers({ vars })\` from @uniweb/loom.`
2735
- )
2736
- }
2752
+ //
2753
+ // ⭐ ONLY WHEN A PAGE WRITES ONE (`warnUnresolvedPlaceholders`, once the pages are read). A
2754
+ // foundation's components may read a site's placeholders themselves
2755
+ // (`website.config.placeholders.currency`), with no content handler: a site value set once.
2756
+ // ⛔ Until 2026-11-11 the warning fired on any `placeholders:`, and told such a site its pages
2757
+ // would print `{name}` when none did.
2758
+ const placeholderNames =
2759
+ !hasContentHandler && siteConfig.placeholders && typeof siteConfig.placeholders === 'object' && !Array.isArray(siteConfig.placeholders)
2760
+ ? Object.keys(siteConfig.placeholders)
2761
+ : []
2737
2762
  // `base` reaches the theme because self-hosted font faces are authored
2738
2763
  // root-relative (`/fonts/x.woff2`) and the emitted @font-face lives in an
2739
2764
  // inline <style> — under a subdirectory deployment it must carry the base.
@@ -2798,6 +2823,8 @@ export async function collectSiteContent(sitePath, options = {}) {
2798
2823
  assetCollection = mergeAssetCollections(assetCollection, layoutAssets)
2799
2824
  iconCollection = mergeIconCollections(iconCollection, layoutIcons)
2800
2825
 
2826
+ warnUnresolvedPlaceholders(placeholderNames, pages)
2827
+
2801
2828
  // One manifest key per file: a co-located ref written the same way in two
2802
2829
  // folders (`./media/shot.png`) names two files, and would otherwise share one
2803
2830
  // entry — every page rendering the last one collected. Before the config
@@ -402,6 +402,16 @@ export function readEntityPoolSync(siteRoot, opts = {}) {
402
402
  if (!e.isFile()) continue
403
403
  // The folder's organization, not a record — see the header.
404
404
  if (dirs.length === 0 && e.name === FOLDER_YML) continue
405
+ // ⛔ A COMPANION SCHEMA IS RETIRED (2026-11-11): every record has a data schema, which says
406
+ // how it is translated, so `records/<query>.schema.js` is read by nothing and said so.
407
+ if (dirs.length === 0 && e.name.endsWith('.schema.js')) {
408
+ errors.push(
409
+ `${rel}/${e.name} is not read: a companion schema is retired. A record's data schema says ` +
410
+ `which of its fields are translated — define it in the foundation's schemas/ ` +
411
+ `(\`uniweb guide data\`), and delete this file.`
412
+ )
413
+ continue
414
+ }
405
415
  const ext = extname(e.name).toLowerCase()
406
416
  const fileRecord = isFileRecordDir(dirs)
407
417
  if (!fileRecord && !ENTITY_EXTENSIONS.has(ext)) continue
package/src/site/index.js CHANGED
@@ -51,7 +51,6 @@ export {
51
51
  processQueries,
52
52
  writeQueryFiles
53
53
  } from './query-processor.js'
54
- export { collectSchemalessData, collectSchemalessDataAssets, rewriteSchemalessDataAssets } from './schemaless-data.js'
55
54
  export {
56
55
  parseFetchConfig,
57
56
  executeFetch,
@@ -246,13 +246,25 @@ import { mountDevApi } from '../dev/api-mount.js'
246
246
  import { mountDevSubmit } from '../dev/submit-mount.js'
247
247
 
248
248
  /**
249
- * The pre-paint appearance script for a shell, the runtime's own (`@uniweb/runtime/ssr`, which a
250
- * prerendered page's seam writes too), or '' for a site with no dark scheme. Loaded once.
249
+ * A shell carrying the page's look by the runtime's own rule (`@uniweb/runtime/ssr`, which a
250
+ * prerendered page's seam writes too): the scheme class on its `<html>`, and the pre-paint script
251
+ * where the browser decides. Unchanged for a site with no dark scheme. Loaded once.
252
+ *
253
+ * ⛔ A runtime without the rule (before @uniweb/runtime 1.6.2) stops with what to do. Until
254
+ * 2026-11-11 every page threw `(intermediate value) is not a function` instead: a runtime held back
255
+ * while this package moved, or a linked runtime whose SSR bundle wasn't rebuilt.
251
256
  */
252
- let bootScriptOf = null
253
- async function appearanceBootScript(appearance) {
254
- bootScriptOf ||= import('@uniweb/runtime/ssr').then((runtime) => runtime.renderAppearanceBootScript)
255
- return (await bootScriptOf)(appearance)
257
+ let writeAppearanceOf = null
258
+ async function writeShellAppearance(html, appearance) {
259
+ writeAppearanceOf ||= import('@uniweb/runtime/ssr').then(({ writePageAppearance }) => {
260
+ if (typeof writePageAppearance === 'function') return writePageAppearance
261
+ throw new Error(
262
+ '@uniweb/runtime has no writePageAppearance, which this @uniweb/build needs (@uniweb/runtime 1.6.2 or later). ' +
263
+ 'Update the Uniweb packages together: npx uniweb@latest update --yes. ' +
264
+ 'For a linked @uniweb/runtime, rebuild its SSR bundle (pnpm build:ssr), then restart.'
265
+ )
266
+ })
267
+ return (await writeAppearanceOf)(html, appearance)
256
268
  }
257
269
 
258
270
  /**
@@ -1165,14 +1177,6 @@ export function siteContentPlugin(options = {}) {
1165
1177
  headInjection += ` <style id="uniweb-theme">\n${contentToInject.theme.css}\n </style>\n`
1166
1178
  }
1167
1179
 
1168
- // ⭐ THE PRE-PAINT APPEARANCE SCRIPT, so a page the browser renders itself — every page under
1169
- // `uniweb dev`, and a build that doesn't prerender — shows the site's look before the bundle
1170
- // boots. A prerendered page keeps this one: its render adds none where the shell has it
1171
- // (`injectPageContent`). ⛔ Until 2026-11-11 only a prerendered page had it, so a dark site
1172
- // under `uniweb dev` painted light for about 0.4 s on every load.
1173
- const bootScript = await appearanceBootScript(contentToInject.theme?.appearance)
1174
- if (bootScript) headInjection += ` ${bootScript}\n`
1175
-
1176
1180
  // ⛔ No page's head tags — canonical, Open Graph, hreflang — go into the shell, which every
1177
1181
  // page is rendered into: the prerender writes each page's own (`injectPageContent`), and the
1178
1182
  // browser keeps them (`useHeadMeta`). Until 2026-10-25 the home page's were written here.
@@ -1211,11 +1215,18 @@ export function siteContentPlugin(options = {}) {
1211
1215
  result = result.replace(/<title>[\s\S]*?<\/title>/, () => `<title>${escapeHtml(siteName)}</title>`)
1212
1216
  }
1213
1217
 
1214
- if (!headInjection) return result
1215
-
1216
1218
  // Insert before </head>
1217
1219
  // A replacer function: `$$` or `$&` in the content, the theme or head.html is text, not a pattern.
1218
- return result.replace('</head>', () => headInjection + ' </head>')
1220
+ if (headInjection) result = result.replace('</head>', () => headInjection + ' </head>')
1221
+
1222
+ // ⭐ THE PAGE'S LOOK, so a page the browser renders itself — every page under `uniweb dev`, and
1223
+ // a build that doesn't prerender — shows the site's look before the bundle boots: the scheme
1224
+ // class on `<html>` where every first visit gets one look, and the pre-paint script where the
1225
+ // browser decides (`writePageAppearance`). A prerendered page is rendered into this shell and
1226
+ // keeps both; its render adds neither again. ⛔ Until 2026-11-11 the shell carried no class,
1227
+ // and at first no script either, so a dark site under `uniweb dev` painted light for about
1228
+ // 0.4 s on every load.
1229
+ return writeShellAppearance(result, contentToInject.theme?.appearance)
1219
1230
  },
1220
1231
 
1221
1232
  async generateBundle() {
@@ -43,6 +43,8 @@ import { readFile } from 'node:fs/promises'
43
43
  import yaml from 'js-yaml'
44
44
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
45
45
  import { dataKeyTypes } from '../uwx/data-key-types.js'
46
+ import { siteSelfScope } from '../uwx/self-scope.js'
47
+ import { qualifyRef } from '@uniweb/schemas/refs'
46
48
 
47
49
  // Read its own YAML rather than importing the site build's helper. That import
48
50
  // pointed the wrong way — a config resolver reaching into the collector that
@@ -403,33 +405,57 @@ export async function dataKeyTyping(siteRoot, declarations, opts = {}) {
403
405
  * built would compile its records in one shape under `pnpm dev` and another in
404
406
  * production — and a component reads them in exactly one.
405
407
  *
406
- * A `@/name` ref the foundation defines no schema for is absent without a word: a query
407
- * is named after no schema when its records have none. Any other ref that does not
408
- * resolve is absent too, and reported in `failures`. With no local foundation only
409
- * `@std/*` refs resolve — from the build's own copy of the standard schemas — and the
410
- * system Models a record may name (`@uniweb/link`), since nothing else is on disk.
408
+ * A `@/name` ref the foundation's own `schemas/` does not define is looked for under the
409
+ * foundation's scope (`@acme/name`), as a push names it — a library of that scope may define
410
+ * it. When neither does, it is in `missing`: a ref this build could check, and found nothing
411
+ * for, which a record cannot be of (`query-processor.js` refuses it). A ref of another scope
412
+ * found nowhere on disk is absent without a word, since it may be registered where this build
413
+ * cannot read; one that fails to load is reported in `failures`. With no local foundation only
414
+ * `@std/*` refs resolve — from the build's own copy of the standard schemas — and the system
415
+ * Models a record may name (`@uniweb/link`), since nothing else is on disk; nothing is `missing`
416
+ * then, as nothing could be checked.
411
417
  *
412
418
  * @param {string} siteRoot
413
419
  * @param {Iterable<string>} refs - the `schema:` refs of the site's queries
414
420
  * @param {{ siteYml?: object }} [opts] - an already-read site.yml
415
- * @returns {Promise<{ schemas: object, failures: Array<{ ref: string, message: string }> }>}
421
+ * @returns {Promise<{ schemas: object, failures: Array<{ ref: string, message: string }>, missing: string[] }>}
416
422
  */
417
423
  export async function resolveRecordSchemas(siteRoot, refs, opts = {}) {
418
424
  const wanted = [...new Set([...(refs || [])].filter((r) => typeof r === 'string' && r))]
419
425
  const schemas = {}
420
426
  const failures = []
421
- if (wanted.length === 0) return { schemas, failures }
427
+ const missing = []
428
+ if (wanted.length === 0) return { schemas, failures, missing }
422
429
  const siteYml = opts.siteYml || (await readYamlFile(join(siteRoot, 'site.yml')))
423
430
  const srcDir = localFoundationSrcDir(siteRoot, siteYml)
431
+ let scope // the foundation's, read once, when a foundation-relative ref needs it
424
432
  for (const ref of wanted) {
425
433
  if (!srcDir && !ref.startsWith('@std/') && !isSystemRecordRef(ref)) continue
426
434
  try {
427
435
  Object.assign(schemas, await buildDataSchemaMap([ref], { srcDir: srcDir ?? siteRoot }))
428
436
  } catch (err) {
429
- if (err?.code !== SCHEMA_NOT_FOUND) failures.push({ ref, message: err?.message || String(err) })
437
+ if (err?.code !== SCHEMA_NOT_FOUND) {
438
+ failures.push({ ref, message: err?.message || String(err) })
439
+ continue
440
+ }
441
+ if (!srcDir || !ref.startsWith('@/')) continue
442
+ if (scope === undefined) scope = (await siteSelfScope(siteRoot)) ?? null
443
+ const qualified = scope ? qualifyRef(ref, scope) : ref
444
+ if (qualified !== ref && (await definedOnDisk(qualified, srcDir))) continue
445
+ missing.push(ref)
430
446
  }
431
447
  }
432
- return { schemas, failures }
448
+ return { schemas, failures, missing }
449
+ }
450
+
451
+ /** Whether a scoped ref resolves on disk — a package of the foundation's workspace or a library. */
452
+ async function definedOnDisk(ref, srcDir) {
453
+ try {
454
+ await buildDataSchemaMap([ref], { srcDir })
455
+ return true
456
+ } catch (err) {
457
+ return err?.code !== SCHEMA_NOT_FOUND
458
+ }
433
459
  }
434
460
 
435
461
  /** The source directory of the site's foundation when it is local, else null. */
@@ -68,6 +68,7 @@ import { isDraftRecord } from './record-draft.js'
68
68
  import { refuseNotOneRecord } from './record-file.js'
69
69
  import { resolveRecordSchemas, resolveQueriesConfig, dataKeyTyping } from './queries-config.js'
70
70
  import { keyOfDefaultRef } from '../uwx/data-key-types.js'
71
+ import { standardTypeFor } from './standard-type-for.js'
71
72
  import { parseFrontmatter } from '../utils/frontmatter.js'
72
73
  import { toDeliveredRecord, toStoredRecord, storedPath, briefFieldMap, contentBodyField, misplacedFields, mapReferences, recordLayout } from '@uniweb/schemas/conform'
73
74
  import { collectNestedRefs } from '@uniweb/schemas/format'
@@ -588,9 +589,10 @@ export const WHOLE_RECORD = Symbol.for('uniweb.query.whole')
588
589
  * `$name` is the record's handle, taken BEFORE the lift: a brief may declare a `slug`
589
590
  * field of its own (`@std/article`'s does), and the lift puts that one over the file's.
590
591
  *
591
- * A record whose query has no data schema (`resolveRecordSchemas`) is delivered as its
592
- * file holds it, a markdown body as `content`, which is what the static lane always did;
593
- * so is a body its schema has no field for — a push refuses that one. A markdown record
592
+ * A record whose data schema this build cannot read (`resolveRecordSchemas`: a foundation that
593
+ * is not local, a schema registered under another scope) is delivered as its file holds it, a
594
+ * markdown body as `content`; so is a body its schema has no field for — a push refuses that one.
595
+ * One whose schema the build can read and finds nothing for stops the build (`processQueries`). A markdown record
594
596
  * also gets `excerpt` and `image` where it states none, derived from its body: the
595
597
  * static lane's own, and not what a host adds.
596
598
  *
@@ -1203,9 +1205,20 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
1203
1205
  }
1204
1206
 
1205
1207
  // ⭐ THE DATA SCHEMA EACH QUERY'S RECORDS ARE DELIVERED IN (`deliverRecord`) — resolved
1206
- // from the foundation's source once for every query. A query with none compiles its
1207
- // records as their files hold them.
1208
- const dataSchemas = options.dataSchemas ?? (await querySchemas(siteDir, queriesConfig, typing))
1208
+ // from the foundation's source once for every query and every folder of records.
1209
+ //
1210
+ // ⭐ EVERY RECORD HAS A DATA SCHEMA [Diego, 2026-11-11]: a folder or a query whose schema the
1211
+ // build can check and finds nothing for stops it (`refuseRecordsWithoutSchema`), as a push
1212
+ // refuses it (`uwx/records.js`). One the build cannot check — a foundation that is not local,
1213
+ // a schema registered under another scope — compiles its records as their files hold them,
1214
+ // and the push checks it against the backend. ⛔ Until 2026-11-11 a folder with no schema was
1215
+ // "schema-less": compiled as files, which a publish uploaded in one language.
1216
+ let dataSchemas = options.dataSchemas
1217
+ if (!dataSchemas) {
1218
+ const resolved = await querySchemas(siteDir, queriesConfig, typing, poolBySchema)
1219
+ refuseRecordsWithoutSchema(resolved.missing, { dir: pool.dir, poolBySchema, queriesConfig })
1220
+ dataSchemas = resolved.schemas
1221
+ }
1209
1222
  const references = referenceHydrator({ poolBySchema, dataSchemas, siteDir, recordsRoot, basePath, includeDrafts })
1210
1223
 
1211
1224
  const results = {}
@@ -1243,26 +1256,63 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
1243
1256
  }
1244
1257
 
1245
1258
  /**
1246
- * The data schemas of the site's record queries, by ref (`resolveRecordSchemas`). A ref
1247
- * that is not a schema-less query's name and still does not resolve is warned about:
1248
- * its records are compiled as their files hold them, which is not the shape a
1249
- * component receives from a host.
1259
+ * The data schemas of the site's record queries and of its folders of records, by ref
1260
+ * (`resolveRecordSchemas`), and the refs it checked and found nothing for (`missing`). A ref of
1261
+ * another scope found nowhere on disk is left to the push, which may find it registered; one
1262
+ * that fails to load is warned about. Either way its records are compiled as their files hold
1263
+ * them, which is not the shape a component receives from a host.
1250
1264
  */
1251
- async function querySchemas(siteDir, queriesConfig, typing = new Map()) {
1265
+ async function querySchemas(siteDir, queriesConfig, typing = new Map(), poolBySchema = new Map()) {
1252
1266
  const refs = [...typing.values()]
1253
1267
  for (const config of Object.values(queriesConfig)) {
1254
1268
  if (config && typeof config === 'object' && config.url !== undefined) continue
1255
1269
  const ref = typeof config === 'string' ? config : config?.schema
1256
1270
  if (typeof ref === 'string' && !typing.has(ref)) refs.push(ref)
1257
1271
  }
1258
- const { schemas, failures } = await resolveRecordSchemas(siteDir, refs)
1272
+ // A folder no query reads is checked too, for a schema it names relative to the foundation —
1273
+ // the only kind this build can find missing; a scoped one is resolved where a query reads it.
1274
+ for (const ref of poolBySchema.keys()) if (ref.startsWith('@/')) refs.push(ref)
1275
+ const { schemas, failures, missing } = await resolveRecordSchemas(siteDir, refs)
1259
1276
  for (const { ref, message } of failures) {
1260
1277
  console.warn(
1261
1278
  `[query-processor] Data schema ${ref} did not resolve, so its records are compiled as ` +
1262
1279
  `their files hold them rather than as a component receives them: ${message}`
1263
1280
  )
1264
1281
  }
1265
- return schemas
1282
+ return { schemas, missing }
1283
+ }
1284
+
1285
+ /**
1286
+ * Stop the build for records whose data schema resolves to nothing, naming each folder and
1287
+ * query and what to write: every record has a data schema [Diego, 2026-11-11]. `missing` holds
1288
+ * only what the build could check (`resolveRecordSchemas`).
1289
+ *
1290
+ * @param {string[]} missing - foundation-relative refs no schema answers
1291
+ * @param {{ dir: string, poolBySchema: Map<string, Array>, queriesConfig: Object }} ctx
1292
+ */
1293
+ export function refuseRecordsWithoutSchema(missing, { dir, poolBySchema, queriesConfig }) {
1294
+ if (!missing?.length) return
1295
+ const lines = missing.map((ref) => {
1296
+ const readers = Object.entries(queriesConfig || {})
1297
+ .filter(([, c]) => (typeof c === 'string' ? c : c?.schema) === ref)
1298
+ .map(([name]) => `query "${name}"`)
1299
+ const held = poolBySchema.get(ref)
1300
+ const where = held?.length ? `${dir}/${held[0].dirs.join('/')}/` : readers.shift()
1301
+ const std = standardTypeFor(ref.replace(/^@\//, ''))
1302
+ return (
1303
+ ` ${where} — ${ref}${readers.length ? `, read by ${readers.join(', ')}` : ''}` +
1304
+ (std ? ` — a standard type fits: @std/${std}, kept in ${dir}/std/${std}/` : '')
1305
+ )
1306
+ })
1307
+ const name = missing[0].replace(/^@\//, '')
1308
+ throw new Error(
1309
+ `[uniweb] Every record needs a data schema, and nothing defines ${missing.length === 1 ? 'this one' : 'these'}:\n` +
1310
+ `${lines.join('\n')}\n` +
1311
+ ` A folder's name is its records' data schema. Use a standard type where one fits: records/std/<name>/ ` +
1312
+ 'holds @std/<name>, which the app edits with its own form (`uniweb guide data` lists them). Keep records ' +
1313
+ 'of a type registered under another scope in records/<scope>/<name>/. Else define your own in the ' +
1314
+ `foundation, as schemas/${name}.yml.`
1315
+ )
1266
1316
  }
1267
1317
 
1268
1318
  /**
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The standard data schema a records folder's or a query's name points to, if any: `testimonials`
3
+ * and `testimonial` → `testimonial` (`@std/testimonial`). Named in a refusal of records with no
4
+ * data schema, so the agent that meets it reaches for the type the app already edits with a form
5
+ * made for it rather than writing a new one [Diego, 2026-11-11: "we should question what we
6
+ * explain … so as to not reinvent the wheel"]. A suggestion only: nothing is typed by it — a guess
7
+ * applied silently is what the retired schema-guessing of record translation was.
8
+ */
9
+ import { isStandardSchema } from '@uniweb/schemas'
10
+
11
+ /**
12
+ * @param {string|null|undefined} name - a folder's or a query's name (`testimonials`)
13
+ * @returns {string|null} the standard schema's name (`testimonial`), or null
14
+ */
15
+ export function standardTypeFor(name) {
16
+ if (typeof name !== 'string' || !name) return null
17
+ const candidates = [name]
18
+ if (name.endsWith('ies')) candidates.push(name.slice(0, -3) + 'y')
19
+ if (name.endsWith('es')) candidates.push(name.slice(0, -2))
20
+ if (name.endsWith('s')) candidates.push(name.slice(0, -1))
21
+ return candidates.find((n) => isStandardSchema(n)) || null
22
+ }
@@ -89,7 +89,8 @@ export function classifyPackage(packagePath) {
89
89
  * framework's `@uniweb/schemas`, referenced as `@std`) — the same convention
90
90
  * `@org/x` data-schema refs already resolve through.
91
91
  * 2. a `schemas/` directory at the package root holding ≥1 schema file
92
- * (`*.{js,json,yml,yaml}`) — a bare folder of schema files with no index.
92
+ * (`*.{js,json,yml,yaml}`) — a bare folder of schema files with no index —
93
+ * or a `mappings/` directory holding ≥1 mapping file.
93
94
  *
94
95
  * Gated on the directory NOT already classifying as a foundation/site, so a
95
96
  * foundation that happens to carry schemas is never misread. The enumeration of
@@ -113,13 +114,15 @@ export function isSchemasPackage(packagePath) {
113
114
  }
114
115
  }
115
116
 
116
- // 2. A schemas/ directory of schema files.
117
- const dir = join(packagePath, 'schemas')
118
- if (existsSync(dir)) {
117
+ // 2. A schemas/ directory of schema files, or a mappings/ one of mappings (a library of
118
+ // mappings alone is one too: `register` in it registers them).
119
+ for (const folder of ['schemas', 'mappings']) {
120
+ const dir = join(packagePath, folder)
121
+ if (!existsSync(dir)) continue
119
122
  try {
120
- return readdirSync(dir).some((f) => /\.(js|json|ya?ml)$/.test(f))
123
+ if (readdirSync(dir).some((f) => /\.(js|json|ya?ml)$/.test(f))) return true
121
124
  } catch {
122
- return false
125
+ // unreadable: not this signal
123
126
  }
124
127
  }
125
128
  return false
@@ -38,15 +38,19 @@ 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'])
41
+ const INTEGRATION_KEYS = Object.freeze(['label', 'mapping', 'channel', 'trigger', 'filter', 'enabled', 'reply', 'reply_about'])
42
+ /** The one channel whose endpoint answers, so the one a `reply` mapping may sit on. */
43
+ const REPLYING = 'http'
44
+ /** `reply_about`: a field of the reply's type, `section.field`. */
45
+ const SECTION_FIELD = /^[^.\s]+\.[^.\s]+$/
42
46
  const CHANNELS = Object.freeze(['file', 'feed', 'email', 'http'])
43
- const TRIGGERS = Object.freeze(['manual', 'on_fetch', 'on_create', 'on_match'])
47
+ const TRIGGERS = Object.freeze(['manual', 'on_fetch', 'on_create', 'on_match', 'on_change'])
44
48
  /** Each channel → the triggers it pairs with. */
45
49
  const PAIRS = Object.freeze({
46
50
  file: ['manual'],
47
51
  feed: ['on_fetch'],
48
- email: ['on_create', 'on_match', 'manual'],
49
- http: ['on_create', 'on_match', 'manual'],
52
+ email: ['on_create', 'on_match', 'on_change', 'manual'],
53
+ http: ['on_create', 'on_match', 'on_change', 'manual'],
50
54
  })
51
55
  /** The channels a line may switch on with `enabled: true`. */
52
56
  const ENABLEABLE = Object.freeze(['file', 'feed'])
@@ -328,6 +332,20 @@ function integrationProblems(integrations) {
328
332
  if (channelOk && triggerOk && !PAIRS[line.channel].includes(line.trigger)) {
329
333
  found.push(`\`${at}\`: a \`${line.channel}\` integration's trigger is one of ${listed(PAIRS[line.channel])} — not \`${line.trigger}\`.`)
330
334
  }
335
+ if ('reply' in line) {
336
+ const name = refNameProblem(`${at}.reply`, line.reply, 'mapping')
337
+ if (name) found.push(name)
338
+ if (channelOk && line.channel !== REPLYING) {
339
+ found.push(`\`${at}.reply\`: only an \`${REPLYING}\` integration is answered, so only one takes a \`reply\` — not a \`${line.channel}\` one.`)
340
+ }
341
+ }
342
+ if ('reply_about' in line) {
343
+ if (!('reply' in line)) {
344
+ found.push(`\`${at}.reply_about\` names a field of the reply's type, so it goes with a \`reply\` mapping — the line has none.`)
345
+ } else if (typeof line.reply_about !== 'string' || !SECTION_FIELD.test(line.reply_about)) {
346
+ found.push(`\`${at}.reply_about\` is a field of the reply's type, \`section.field\` — \`identity.submission\` — not ${described(line.reply_about)}.`)
347
+ }
348
+ }
331
349
  if ('filter' in line && !isMap(line.filter)) {
332
350
  found.push(`\`${at}.filter\` is a map — \`filter: { where: { status: sold } }\` — not ${described(line.filter)}.`)
333
351
  }
@@ -26,8 +26,9 @@
26
26
  * full name for any other, as `data:` and `queries.yml` name types — and a push names each in full
27
27
  * by the rule every ref it sends follows (`qualifyRef`, with the scope `siteSelfScope` reads). The
28
28
  * backend never resolves an `@/x`. A pull writes `@/x` back, and keeps a name the file already
29
- * spells another way when it names the same type. An integration's `mapping:` — one of the
30
- * foundation's mappings (`src/mappings/`) — is named the same way; nothing in its `filter` is.
29
+ * spells another way when it names the same type. An integration's `mapping:` and `reply:` — each
30
+ * one of the foundation's mappings (`src/mappings/`) — are named the same way; its `reply_about`
31
+ * (a field) and nothing in its `filter` are.
31
32
  *
32
33
  * ⭐ ITS SHAPE IS THE BACKEND'S, AND THE BACKEND CHECKS IT AT EVERY DOOR THAT WRITES THE ROW. The
33
34
  * checks here come earlier — a build, a push, `uniweb doctor`, offline — and refuse no more than
@@ -97,12 +98,21 @@ export function blueprintForWire(blueprint, scope) {
97
98
  return out
98
99
  }
99
100
 
100
- /** Each integration line with its `mapping:` renamed by `rename`; nothing else in the line moves. */
101
+ /** The keys of an integration line that name a mapping. */
102
+ const MAPPING_KEYS = Object.freeze(['mapping', 'reply'])
103
+
104
+ /**
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
+ */
101
108
  function mappingsNamed(integrations, rename) {
102
109
  return Object.fromEntries(
103
- Object.entries(integrations).map(([id, line]) =>
104
- isMap(line) && typeof line.mapping === 'string' ? [id, { ...line, mapping: rename(line.mapping) }] : [id, line]
105
- )
110
+ Object.entries(integrations).map(([id, line]) => {
111
+ if (!isMap(line)) return [id, line]
112
+ const out = { ...line }
113
+ for (const key of MAPPING_KEYS) if (typeof line[key] === 'string') out[key] = rename(line[key])
114
+ return [id, out]
115
+ })
106
116
  )
107
117
  }
108
118
 
@@ -169,13 +179,17 @@ export function blueprintFromWire(wire, { scope = null, own = null, local = null
169
179
 
170
180
  /**
171
181
  * A mapping's full name → as a pull writes it: as the file already spells it when it names the same
172
- * one, else `@/x` when it is in the site's foundation's scope. A foundation registers only its own
173
- * mappings, so every mapping in that scope is the foundation's.
182
+ * one, else `@/x` when it is in the site's foundation's scope — which a push names in full the same
183
+ * way, so the two agree whoever registered it. A library's mapping, in its own scope, comes back in
184
+ * full, as the file wrote it.
174
185
  */
175
186
  function mappingAsFileSpells(full, localIntegrations, scope) {
176
187
  if (isMap(localIntegrations)) {
177
188
  for (const line of Object.values(localIntegrations)) {
178
- if (isMap(line) && typeof line.mapping === 'string' && qualifyRef(line.mapping, scope) === full) return line.mapping
189
+ if (!isMap(line)) continue
190
+ for (const key of MAPPING_KEYS) {
191
+ if (typeof line[key] === 'string' && qualifyRef(line[key], scope) === full) return line[key]
192
+ }
179
193
  }
180
194
  }
181
195
  const org = bareOrg(scope)
@@ -310,22 +324,29 @@ export function blueprintWarnings(blueprint, { scope, declared, sending = false
310
324
  }
311
325
  }
312
326
  for (const [id, line] of Object.entries(isMap(blueprint.integrations) ? blueprint.integrations : {})) {
313
- const mapping = isMap(line) ? line.mapping : null
314
- if (typeof mapping !== 'string') continue
315
- const at = `integrations.${id}.mapping`
316
- if (!scoped && mapping.startsWith('@/') && sending) {
317
- out.push(
318
- `${BLUEPRINT_FILE}: \`${at}\` is the foundation's own mapping, and the foundation has no scope yet, ` +
319
- "so a push sends it as written — the backend never resolves an `@/x`. A foundation's scope is part " +
320
- "of its name — `name: '@org/<name>'` in its main.js, which `uniweb register` writes."
321
- )
322
- }
323
- if (declared?.mappings && !declared.mappings.has(qualifyRef(mapping, scope))) {
324
- out.push(
325
- `${BLUEPRINT_FILE}: \`${at}\` names a mapping none of this site's foundations declares, so a backend ` +
326
- `started from this site leaves the line out. Check the name against the foundation's src/mappings/.`
327
- )
328
- }
327
+ for (const key of MAPPING_KEYS) out.push(...mappingWarnings(line, id, key, { scoped, scope, declared, sending }))
328
+ }
329
+ return out
330
+ }
331
+
332
+ /** What one mapping an integration line names (`mapping:`, `reply:`) warns of. */
333
+ function mappingWarnings(line, id, key, { scoped, scope, declared, sending }) {
334
+ const mapping = isMap(line) ? line[key] : null
335
+ if (typeof mapping !== 'string') return []
336
+ const out = []
337
+ const at = `integrations.${id}.${key}`
338
+ if (!scoped && mapping.startsWith('@/') && sending) {
339
+ out.push(
340
+ `${BLUEPRINT_FILE}: \`${at}\` is the foundation's own mapping, and the foundation has no scope yet, ` +
341
+ "so a push sends it as written — the backend never resolves an `@/x`. A foundation's scope is part " +
342
+ "of its name — `name: '@org/<name>'` in its main.js, which `uniweb register` writes."
343
+ )
344
+ }
345
+ if (declared?.mappings && !declared.mappings.has(qualifyRef(mapping, scope))) {
346
+ out.push(
347
+ `${BLUEPRINT_FILE}: \`${at}\` names a mapping none of this site's foundations declares, so a backend ` +
348
+ `started from this site leaves the line out. Check the name against the foundation's src/mappings/.`
349
+ )
329
350
  }
330
351
  return out
331
352
  }
package/src/uwx/index.js CHANGED
@@ -75,6 +75,7 @@ export {
75
75
  export {
76
76
  recordsToProject,
77
77
  declarationsToQueriesYml,
78
+ readSiteFoundationDeclarations,
78
79
  folderToFolderYml,
79
80
  findRecordFileByUuid,
80
81
  indexFolder,