@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.
@@ -32,6 +32,7 @@ import { queryNameFromUrl, declaredKeys, fillDeclaredKeys, fetchLevels, pageRout
32
32
  import { parentRouteOf } from '@uniweb/core/route-match'
33
33
 
34
34
  import { validateItem, validateRecordFile, validateBound, validateKeyValue, contentBodyField, rootListSection, referencesOf } from '@uniweb/schemas/conform'
35
+ import { normalizeData } from '@uniweb/schemas/foundation'
35
36
  import { isUuid } from './uwx/uuid.js'
36
37
  import { validateAndNormalizeSchema, buildDataSchemaMap } from './resolve-data-schema.js'
37
38
 
@@ -50,6 +51,32 @@ import { processQueries } from './site/query-processor.js'
50
51
 
51
52
  // --- the join: sections ↔ schemas -------------------------------------------
52
53
 
54
+ /**
55
+ * The keys a section type declares with an inline shape — a field map or a form — whose every
56
+ * field gives a `default:`: the words a section draws itself, which it shows when the section holds
57
+ * no block of its own (`uniweb guide foundation` § A section's own words). Read by the one
58
+ * normalizer every form of a declaration goes through (`normalizeData`).
59
+ *
60
+ * @param {object|undefined} data - a section type's `data:`
61
+ * @returns {Set<string>}
62
+ */
63
+ function keysWithOwnWords(data) {
64
+ const out = new Set()
65
+ let normalized = {}
66
+ try {
67
+ normalized = normalizeData(data, { strict: false }) || {}
68
+ } catch {
69
+ return out // a declaration the foundation's build stops on is reported there
70
+ }
71
+ for (const [key, decl] of Object.entries(normalized)) {
72
+ const fields = decl?.kind === 'fields' ? Object.values(decl.fields || {}) : decl?.kind === 'form' ? decl.fields : null
73
+ if (Array.isArray(fields) && fields.length > 0 && fields.every((f) => f && typeof f === 'object' && f.default !== undefined)) {
74
+ out.add(key)
75
+ }
76
+ }
77
+ return out
78
+ }
79
+
53
80
  /**
54
81
  * Walk a site's sections, pair each governed data input with its schema, and
55
82
  * validate. The section is the join point: it has a *type* (→ `meta.js` → a
@@ -85,7 +112,9 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
85
112
  if (!foundationPath) throw new Error('validateDataInputs: foundationPath is required')
86
113
 
87
114
  const srcDir = resolveFoundationSrcPath(foundationPath)
88
- const foundation = await buildSchema(srcDir)
115
+ // Not strict: validating a site's records reads its foundation's declarations, and warns of one
116
+ // the foundation's build stops on rather than refusing the site (`buildSchema`'s `strict`).
117
+ const foundation = await buildSchema(srcDir, undefined, null, { strict: false })
89
118
  const dataSchemas = foundation.dataSchemas || {}
90
119
  // The type each data key names — a records folder named for a typed key holds records of
91
120
  // that type when no data schema has its name (`uwx/data-key-types.js`).
@@ -183,7 +212,16 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
183
212
  const concepts = new Set(
184
213
  (foundation[type]?.content || []).filter((e) => e?.kind === 'concept').map((e) => e.key)
185
214
  )
186
- const declaredNames = declared.map(([key]) => key).filter((key) => !concepts.has(key))
215
+ // ⛔ NOR IS A SECTION'S OWN WORDS. A key declared with an inline shape whose every field gives
216
+ // a `default:` holds the words a section draws itself, which an author overrides with a
217
+ // ```yaml:labels block (`uniweb guide foundation` § A section's own words): with no block the
218
+ // component shows the type's own, so it renders without data, and a page's query that feeds
219
+ // another section has not failed to reach it. ⛔ Until 2026-11-11 it was counted, and every
220
+ // publish of a site whose blog page queries its articles reported the page's Hero.
221
+ const ownWords = keysWithOwnWords(bindings)
222
+ const declaredNames = declared
223
+ .map(([key]) => key)
224
+ .filter((key) => !concepts.has(key) && !ownWords.has(key))
187
225
  if (declaredNames.length > 0 && inputs.length > 0 && fills.size === 0 && !declaredNames.some((k) => held.includes(k))) {
188
226
  const delivered = inputs.map((i) => i.as).filter(Boolean)
189
227
  setupErrors.push({
@@ -353,8 +391,9 @@ function listViolation(finding, label, base) {
353
391
  * ⭐ A folder named for a data key the foundation types, when no data schema has its name,
354
392
  * holds records of that type and is checked against it — `records/team/` against `@/member`
355
393
  * for `data: { team: '@/member' }` — the way a push sends them [Diego, 2026-09-25]
356
- * (`uwx/data-key-types.js`). A folder whose schema resolves to nothing even so is left out in
357
- * silence: its records are schema-less, delivered as files, and the push says so itself.
394
+ * (`uwx/data-key-types.js`). A folder whose schema this check cannot read (a foundation that is
395
+ * not local) is left out in silence; one it can read and finds nothing for has already stopped
396
+ * `processQueries`, since every record has a data schema [Diego, 2026-11-11].
358
397
  *
359
398
  * @returns {Promise<{ violations: object[], setupErrors: object[], schemas: Set<string>, checked: number }>}
360
399
  */
@@ -602,8 +602,15 @@ export function foundationDevPlugin(options = {}) {
602
602
  if (reason) {
603
603
  console.log(`[foundation] ${reason}, regenerating entry...`)
604
604
  const entryPath = join(resolvedSrcDir, entryFileName)
605
- await generateEntryPoint(resolvedSrcDir, entryPath, { sectionPaths })
606
- server.ws.send({ type: 'full-reload' })
605
+ try {
606
+ await generateEntryPoint(resolvedSrcDir, entryPath, { sectionPaths })
607
+ server.ws.send({ type: 'full-reload' })
608
+ } catch (err) {
609
+ // The last good entry stays, and the page shows why: a `meta.js` that does not load, or a
610
+ // declaration the build cannot use, stops the build (schema.js), and the dev server lives on.
611
+ console.warn('[foundation] Failed to regenerate the entry:', err.message)
612
+ server.ws.send({ type: 'error', err: { message: err.message, stack: '' } })
613
+ }
607
614
  }
608
615
  },
609
616
  }
@@ -1,185 +0,0 @@
1
- /**
2
- * Schema-less collection data — the set, and its local media.
3
- *
4
- * ⭐ **The name carries the scope on purpose.** This is NOT "the site's static
5
- * data" in general. A site's collections partition by **schema presence**: one
6
- * that resolves a data schema syncs as folder entities — content a backend
7
- * genuinely consumes, queryable, editable, with a `brief:` for its lean shape.
8
- * A **schema-less** collection has no entity model, so its compiled
9
- * `dist/data/<name>.json` (plus its per-record files, `<name>/<$name>.json`) is
10
- * delivered as files instead. That fallback tier is all this module is about.
11
- *
12
- * { data: { "<relpath under dist/data>": <json> } } // schema-less only
13
- *
14
- * ⇒ It is an **in-memory enumeration**, not an artifact. `collectSchemalessData`
15
- * gathers the set; the CLI's `site-data-upload` lane PUTs each file to the
16
- * target the backend returns, landing at its serving tail.
17
- *
18
- * ## ⛔ It used to be a "data ball", and that is retired (2026-08-18)
19
- *
20
- * This merged the whole set into ONE uploaded asset that the backend then had
21
- * to fetch, parse and fan out. It was the **only aggregate the CLI produced** —
22
- * media, foundation code and the runtime all upload one object per file — and
23
- * the only place these bytes ever transited the backend. Nothing in the code or
24
- * the docs ever justified the bundling.
25
- *
26
- * ⇒ **Do not reintroduce a bundle here.** One object per file is what the
27
- * reader's static arm already assumes: a plain object GET on the verbatim tail,
28
- * with nothing anywhere that unbundles.
29
- *
30
- * **A search index used to ride here too, and deliberately no longer does**
31
- * (2026-08-01). Only a CLI deploy produced one — a CMS publish produced none —
32
- * so a site's search existed or vanished depending on who published it, which
33
- * is the artifact-flicker rule exactly. A host that wants search derives it from
34
- * the content it already stores. See the note at the removal point below.
35
- */
36
-
37
- import { existsSync } from 'node:fs'
38
- import { readFile, readdir } from 'node:fs/promises'
39
- import { join, relative, sep } from 'node:path'
40
- import { DATA_DIR } from '@uniweb/core'
41
- import { isLocalAssetPath } from './assets.js'
42
-
43
- // Walk a dist subdir for *.json → { "<posix-relpath>": <parsedJson> }. Unparseable
44
- // files are skipped (build-emitted data is always valid JSON; this just stays safe).
45
- async function readJsonTree(dir) {
46
- if (!existsSync(dir)) return {}
47
- const out = {}
48
- const entries = await readdir(dir, { withFileTypes: true, recursive: true })
49
- for (const entry of entries) {
50
- if (!entry.isFile() || !entry.name.endsWith('.json')) continue
51
- const full = join(entry.parentPath || entry.path, entry.name)
52
- const rel = relative(dir, full).split(sep).join('/')
53
- try {
54
- out[rel] = JSON.parse(await readFile(full, 'utf8'))
55
- } catch {
56
- // not valid JSON — skip
57
- }
58
- }
59
- return out
60
- }
61
-
62
- // The collection a `dist/data` relpath belongs to: the first path segment, minus a
63
- // trailing `.json`. `articles.json` → `articles`; `articles/hello.json` → `articles`.
64
- function queryOf(relPath) {
65
- const first = relPath.split('/')[0]
66
- return first.endsWith('.json') ? first.slice(0, -5) : first
67
- }
68
-
69
- /**
70
- * Gather the schema-less set from a built site's dist/ — in memory, one entry per
71
- * file; nothing is bundled (see the header).
72
- *
73
- * @param {string} distDir - the site's built dist/ directory
74
- * @param {string[]} [schemalessNames] - collection names with no data schema (from
75
- * `emitSyncPackages(...).schemaless`); only these contribute `data`.
76
- * @returns {Promise<{ data: Object }|null>} null when there is nothing to deliver.
77
- */
78
- export async function collectSchemalessData(distDir, schemalessNames = []) {
79
- const schemaless = new Set(schemalessNames)
80
- const allData = await readJsonTree(join(distDir, DATA_DIR))
81
- const data = {}
82
- for (const [relPath, value] of Object.entries(allData)) {
83
- if (schemaless.has(queryOf(relPath))) data[relPath] = value
84
- }
85
- // Agent projections deliberately do NOT ride the ball.
86
- //
87
- // A backend that stores the site's content derives them itself at publish —
88
- // one producer, so shipping ours would upload an artifact to the one host
89
- // that does not need it, and invite two answers for one site. The projections
90
- // this build emits into `dist/` are for hosts with no backend to derive them:
91
- // static hosts and foreign backends. That is `@uniweb/projections`' scope and
92
- // it is unchanged.
93
- //
94
- // (An opt-in `projections` bucket lived here while the delivery contract was
95
- // open. It never shipped enabled, and the one-producer ruling closed the
96
- // question — removed rather than left as a flag nobody may turn on.)
97
- //
98
- // THE SEARCH INDEX IS ONE OF THOSE PROJECTIONS, and it rode this ball anyway
99
- // — `const search = readJsonTree(dist/_search)` sat four lines above this
100
- // comment, doing the exact thing the comment forbids. Removed 2026-08-01.
101
- //
102
- // What made it wrong is not symmetry, it is the flicker rule: a CLI deploy
103
- // produced the index and a CMS publish produced none, so a site's search
104
- // oscillated with whoever published it. Deriving it from stored content — one
105
- // input that exists identically on both lanes — makes that unexpressible,
106
- // which is a stronger guarantee than any producer agreement.
107
- //
108
- // The static index for hosts with no backend is UNCHANGED and still emitted:
109
- // `search-index.json`, bundle lane, what GitHub Pages and every other static
110
- // target serve. The framework has more targets than one backend, and that is
111
- // the artifact for the rest of them.
112
-
113
- if (Object.keys(data).length === 0) return null
114
-
115
- // The `search` key is gone too, and that was the SECOND step of a two-step
116
- // retirement, not an afterthought.
117
- //
118
- // Step one shipped `search: {}` — content removed, key kept — because an
119
- // absent field and an empty one are different shapes to a strict
120
- // deserializer, and a missing required field fails exactly as loudly as an
121
- // unknown one. (The producer half of this same contract broke pushes earlier
122
- // the same day by emitting a key the consumer had not declared. Same failure,
123
- // opposite direction.) Step two is this: the consumer retired the field on
124
- // 2026-08-01 and said an older CLI still sending it deploys fine, so the key
125
- // now has nowhere to land and dropping it is safe in both directions.
126
- //
127
- // Worth keeping as a shape: **announce, then remove** — the mirror of
128
- // "declare, then emit". Neither half of a wire can be changed in one step by
129
- // one side, and which side moves first is decided by which direction the
130
- // strictness runs.
131
- return { data }
132
- }
133
-
134
- // --- local media in the ball -------------------------------------------------
135
- // Schema-less collection data rides in the ball, so a local image in a schema-less
136
- // record (e.g. a note's `image: /images/x.png`) needs the same upload + serve-URL
137
- // rewrite the entity content gets (emitSyncPackages' `assetRewrite`) — otherwise the
138
- // served `/data/<name>.json` keeps a dangling local path. The deploy collects the
139
- // ball's refs, uploads them on the SAME asset lane, then rewrites the ball before
140
- // uploading it. The backend serves a `serve_url` in the ball identically to one in an
141
- // entity (it unwraps the ball verbatim), so this is purely producer-side.
142
-
143
- /**
144
- * Site-root local asset refs anywhere in the ball (`/images/x.png`, `/collections/...`).
145
- * Built `dist/data` refs are already site-root (the collection processor copied
146
- * co-located assets to `public/collections/**`), so only `/`-prefixed refs are collected.
147
- * @param {{data:object}|null} ball
148
- * @returns {string[]} deduped refs to upload
149
- */
150
- export function collectSchemalessDataAssets(ball) {
151
- const refs = new Set()
152
- const walk = (n) => {
153
- if (typeof n === 'string') {
154
- if (isLocalAssetPath(n) && n.startsWith('/')) refs.add(n)
155
- return
156
- }
157
- if (Array.isArray(n)) { for (const x of n) walk(x); return }
158
- if (n && typeof n === 'object') for (const v of Object.values(n)) walk(v)
159
- }
160
- walk(ball)
161
- return [...refs]
162
- }
163
-
164
- /**
165
- * Rewrite the ball: replace every local ref the map covers with its serve URL. Pure —
166
- * returns a NEW ball (the input is reused elsewhere). A ref the map omits (upload
167
- * failed/skipped) is left untouched — never a broken URL.
168
- * @param {{data:object}|null} ball
169
- * @param {Record<string,string>} map - ref → serve URL
170
- * @returns {{data:object}|null} a new ball, or the input when there's nothing to do
171
- */
172
- export function rewriteSchemalessDataAssets(ball, map) {
173
- if (!ball || !map || Object.keys(map).length === 0) return ball
174
- const walk = (n) => {
175
- if (typeof n === 'string') return map[n] || n
176
- if (Array.isArray(n)) return n.map(walk)
177
- if (n && typeof n === 'object') {
178
- const out = {}
179
- for (const [k, v] of Object.entries(n)) out[k] = walk(v)
180
- return out
181
- }
182
- return n
183
- }
184
- return walk(ball)
185
- }