@uniweb/build 1.15.5 → 1.16.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.
package/src/uwx/site.js CHANGED
@@ -42,10 +42,12 @@
42
42
  //
43
43
  // v0 scope (stated, not silent): media/asset bytes (favicon/assets — carried out of band). Folder-mode `.md`-as-pages and
44
44
  // `paths: { pages/<segment> }` mounts are carried since 2026-10-23, read by the
45
- // build's own rules; a pull leaves those pages alone (`git-authored.js`).
45
+ // build's own rules; a pull writes a folder-mode page back in place, and leaves a mount's alone
46
+ // (`page-files.js`).
46
47
 
47
48
  import { readdir, readFile } from 'node:fs/promises'
48
49
  import { dataBlockModels } from '../i18n/data-models.js'
50
+ import { SINGLE_SECTION } from './route-mode.js'
49
51
  import { existsSync } from 'node:fs'
50
52
  import { join, parse, relative } from 'node:path'
51
53
  import {
@@ -66,6 +68,7 @@ import {
66
68
  assertRouteFolder,
67
69
  resolveMounts,
68
70
  layerMountedFolder,
71
+ refusePageInFolderMode,
69
72
  folderModePageFiles,
70
73
  folderModeChildren,
71
74
  rootOrderConfig,
@@ -479,7 +482,7 @@ function buildPageData(config, ctx) {
479
482
  // unless the local folder declares one, and the children read from the mount. ⛔ Until 2026-10-23
480
483
  // this lane read no mount, so a mounted route was pushed as an empty container (a local stub) or
481
484
  // not at all (none) — measured 2026-09-18 on a documentation site: 49 pages built, 2 pushed.
482
- async function orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts = null) {
485
+ async function orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts = null, siteRoot = dirPath) {
483
486
  const entries = await readdir(dirPath, { withFileTypes: true })
484
487
  const local = new Map()
485
488
  for (const e of entries) {
@@ -492,6 +495,7 @@ async function orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts =
492
495
  const localConfig = localPath ? await readFolderConfig(localPath, inheritedMode) : null
493
496
  const mountedConfig = mountPath ? await readFolderConfig(mountPath, 'pages') : null
494
497
  const { dirConfig, dirMode, childMode } = layerMountedFolder(dirName, localConfig, mountedConfig, inheritedMode)
498
+ refusePageInFolderMode(inheritedMode, dirMode, relative(siteRoot, localPath ?? mountPath))
495
499
  folders.push({
496
500
  dirName,
497
501
  name: parseNumericPrefix(dirName).name,
@@ -507,12 +511,10 @@ async function orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts =
507
511
  })
508
512
  }
509
513
  // Explicit order, then numeric-prefix filename order, then the parent's `pages:` wildcard —
510
- // one function, which the pull reproduces a level's order with too (`site-project.js`).
511
- // ⚠️ It does NOT match the build's own page-folder sort in one case, and the note that said
512
- // "mirror content-collector's pageFolders sort" here read as if it did: the collector compares
513
- // a level's folder names whole, as strings, and matches `pages:` against them whole, where
514
- // this strips a numeric prefix (`2-about` is `about`, and `10-` sorts after `2-`). Only a level
515
- // with numbered page folders can tell them apart, and which rule is right for them is open.
514
+ // one function, which the pull reproduces a level's order with too (`site-project.js`), on the
515
+ // comparison the build sorts a level's folders with (`compareFolders`). A folder's number orders it
516
+ // and is no part of its name (`2-about` is `about`, and `10-` sorts after `2-`), on every lane
517
+ // [Diego, 2026-11-04]. ⛔ Until then the build kept the number in the route, `/2-about`.
516
518
  return orderFolders(folders, parentConfig?.pages)
517
519
  }
518
520
 
@@ -832,7 +834,7 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
832
834
  const { siteRoot, siteIndex, sourceLocale, translations, pageFields } = ctx
833
835
  const files = inheritedMode === 'pages' ? await folderModePageRecords(ctx, dirPath, parentConfig, isRoot) : []
834
836
  const made = []
835
- const folders = await orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts)
837
+ const folders = await orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts, siteRoot)
836
838
  // A folder inside a `[...path]` folder can never be reached, and `[dir]` /
837
839
  // `[path]` would name a route variable — refused here as the collector refuses
838
840
  // them, so a site that cannot build cannot sync either (ruled 2026-09-11).
@@ -851,7 +853,11 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
851
853
  // ONE page whose sections were its `.md` files while the build rendered each as a
852
854
  // page of its own. Nothing warned, and a pull then wrote a `page.yml` into the
853
855
  // folder, converting the author's own site to the wrong shape.
854
- const mode = f.internalMode === 'pages' ? 'folder' : 'page'
856
+ // ⭐ WHAT ITS PAGES MAY HOLD, not how the files hold them: `single-section` where they are a folder-mode
857
+ // folder's `.md` files, one section each, else `page`. The mode its PAGES are read in (`childMode`), so
858
+ // a page above a mounted folder of `.md` pages says it too, with its own sections. The app reads it to
859
+ // offer no second section there. ⛔ Until 2026-11-04 it was the folder's own mode, spelled `folder`.
860
+ const mode = f.childMode === 'pages' ? SINGLE_SECTION : 'page'
855
861
  const slugPath = parentSlugPath ? `${parentSlugPath}/${slug}` : slug
856
862
 
857
863
  const data = buildPageData(f.config, {
@@ -881,7 +887,7 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
881
887
  }
882
888
 
883
889
  // A folder-mode folder has no sections: its `.md` files are pages, sent among its children.
884
- if (mode === 'page') {
890
+ if (f.internalMode !== 'pages') {
885
891
  const sections = await collectPageSectionsNested(f.path, siteRoot, f.config, ctx.media)
886
892
  if (sections.length > 0) record.page_sections = sections
887
893
  }
@@ -1363,7 +1369,9 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
1363
1369
  setIf(settings, 'head_html', headHtml)
1364
1370
  setIf(settings, 'fetcher', siteYml.fetcher)
1365
1371
  setIf(settings, 'build', siteYml.build)
1366
- setIf(settings, 'paths', siteYml.paths)
1372
+ // ⛔ Not `paths`: where a project keeps its files is the project's, and a pull reads it from the
1373
+ // project's own `site.yml`. Sent until 2026-11-04, it reached a clone, which wrote its pages where
1374
+ // another copy kept them — outside itself, pruning what was there.
1367
1375
  setIf(settings, 'base', siteYml.base)
1368
1376
 
1369
1377
  // Locale configuration.
@@ -29,7 +29,8 @@ import { buildFolderEntity } from './folder.js'
29
29
  import { siteProjectToDocument } from './site.js'
30
30
  import { siteSourceLocale } from './source-locale.js'
31
31
  import { siteSelfScope, refuseOrgOption } from './self-scope.js'
32
- import { stampUnitUuids, collectUnitUuids } from './site-diff.js'
32
+ import { stampUnitUuids, collectUnitUuids, computeUnitHashes } from './site-diff.js'
33
+ import { leaveHeldOut } from './held-units.js'
33
34
  import { emitEntitySyncPackage } from './entity-document.js'
34
35
  import { recordQueriesShown } from './shown-records.js'
35
36
  import { isLocalAssetPath } from '../site/assets.js'
@@ -245,6 +246,13 @@ function rewriteEntityAssets(node, map, ids, bare = null) {
245
246
  * stamped onto the site-content document so the backend matches our items
246
247
  * instead of re-minting them (which deletes and recreates every page and
247
248
  * section row). Sourced from a pull or a push response, cached by the caller.
249
+ * @param {Object<string,string>} [opts.heldUnits] - unit path → hash: what a pull held, where the
250
+ * files keep it (`held-units.js::heldUnitsOf`). Those whose files still say it are left out
251
+ * of the site-content document (`heldLeftOut`); when any changed, none is, and the result's
252
+ * `heldChanged` names them. Omit to send them, as `--force` does.
253
+ * @param {boolean} [opts.unitHashes] - also return each unit of the files' document, before any
254
+ * media is rewritten, by path: its hash and its `$uuid` from `opts.itemUuids`
255
+ * (`unitHashes`, `unitUuids`), for a pull to record what it held.
248
256
  * @param {Object<string,Object<string,string>>} [opts.recordItemUuids] - record `$uuid` → the
249
257
  * identity of its list items, as a previous push or pull banked it
250
258
  * (`record-items.js`); stamped onto each record the backend holds, so a re-sent
@@ -395,9 +403,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
395
403
 
396
404
  // `queryUuids` — identity for the `queries` section, keyed by query
397
405
  // NAME because a declaration has no file of its own (see queriesNested).
398
- const siteDoc = includeSite
399
- ? await siteProjectToDocument(siteRoot, {
400
- media,
406
+ const docOpts = includeSite
407
+ ? {
401
408
  sourceLocale,
402
409
  // Whose $uuid belongs on this wire document — see siteProjectToDocument.
403
410
  ...(opts.backend ? { backend: opts.backend } : {}),
@@ -416,8 +423,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
416
423
  ...(Array.isArray(opts.queryFields) ? { queryFields: opts.queryFields } : {}),
417
424
  ...(Array.isArray(opts.pageFields) ? { pageFields: opts.pageFields } : {}),
418
425
  ...(Array.isArray(opts.settingsFields) ? { settingsFields: opts.settingsFields } : {})
419
- })
426
+ }
420
427
  : null
428
+ const siteDoc = includeSite ? await siteProjectToDocument(siteRoot, { ...docOpts, media }) : null
421
429
  // Deploy-derived `info` fields are stamped here — NOT authored in site.yml, so they
422
430
  // ride the wire but never project back on pull. They are part of the hashed content,
423
431
  // so a changed value correctly re-fires the site-content lane.
@@ -563,6 +571,21 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
563
571
  recordItemIdentity.unknown += n.unknown
564
572
  }
565
573
 
574
+ // ⭐ WHAT A PULL HELD STAYS AS THE APP HAS IT (`held-units.js`): a held unit whose files still say what
575
+ // they said at the pull is not sent, and one whose files changed is named for the caller to stop on.
576
+ // Compared on the document the files give before any media is rewritten (`plain`), which `unitHashes`
577
+ // hands a pull to record. A walk of its own, made only when a pull held something.
578
+ const heldUnits = opts.heldUnits && typeof opts.heldUnits === 'object' && Object.keys(opts.heldUnits).length ? opts.heldUnits : null
579
+ const plain = siteDoc && (heldUnits || opts.unitHashes) ? await siteProjectToDocument(siteRoot, { ...docOpts, media: null }) : null
580
+ const held = heldUnits ? leaveHeldOut(siteDoc, { held: heldUnits, plain, sourceLocale }) : { left: [], changed: [] }
581
+ let unitHashes = null
582
+ let unitUuids = null
583
+ if (plain && opts.unitHashes) {
584
+ stampUnitUuids(plain, opts.itemUuids && typeof opts.itemUuids === 'object' ? opts.itemUuids : {}, sourceLocale)
585
+ unitHashes = computeUnitHashes(plain, sourceLocale)
586
+ unitUuids = collectUnitUuids(plain, sourceLocale)
587
+ }
588
+
566
589
  const siteEntity = siteDoc
567
590
  ? { id: siteDoc.$id, model: siteDoc.$schema, file: 'entities/site-content.json', document: siteDoc }
568
591
  : null
@@ -702,5 +725,13 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
702
725
  // leaves the backend's folder exactly as it is — no records directory, or one holding files
703
726
  // that are not records — so a caller can say so where the backend still holds records.
704
727
  sendsFolder: folder !== null,
728
+ // What a pull held (`opts.heldUnits`): the paths this push left out, its files unchanged, and the paths
729
+ // that changed since the pull, for a caller that submits to stop on — none is left out then.
730
+ heldLeftOut: held.left,
731
+ heldChanged: held.changed,
732
+ // With `opts.unitHashes`: each unit of the files' document before any media is rewritten, by path —
733
+ // its hash, and its `$uuid` from `opts.itemUuids` — for a pull to record what it held (`held-units.js`).
734
+ unitHashes,
735
+ unitUuids,
705
736
  }
706
737
  }
@@ -1,85 +0,0 @@
1
- // The pages a pull leaves alone: those authored in files a pull cannot write back.
2
- //
3
- // ⭐ Two kinds, decided 2026-10-23 [Diego: the pull leaves them alone, since the docs are written in
4
- // git]. A push sends both whole, read by the build's own rules (`site.js`), so the backend holds
5
- // the site as the build makes it. A pull writes neither:
6
- //
7
- // · every page under a `paths: { pages/<segment>: <dir> }` mount. Its files are another
8
- // repository's, outside the site; the local folder of that name holds only how this site
9
- // presents them, and a pull writing the mounted pages into it would grow a second copy there.
10
- // · every `.md` page of a folder-mode folder. The file IS the page, and a pull writes a page as a
11
- // folder (`page.yml` + its sections), which would turn the author's folder of pages into a
12
- // folder of page folders.
13
- //
14
- // ⇒ An edit made to one of these pages in the app is not brought back, and the next push replaces
15
- // it with the file. Pruning skips them too: a pull never deletes what it does not write.
16
- //
17
- // A leaf module, read synchronously as the pull projects (`site-project.js`), through the build's
18
- // mode rule (`folderContentMode`) and its folder-mode page list (`folderModePageFiles`), so the set
19
- // is the one the push walks.
20
-
21
- import { existsSync, readdirSync, readFileSync } from 'node:fs'
22
- import { join } from 'node:path'
23
- import yaml from 'js-yaml'
24
- import { YAML_OPTIONS } from '../utils/yaml-schema.js'
25
- import { isIgnoredFolder } from '../utils/content-files.js'
26
- import { folderContentMode, folderModePageFiles, mountEntriesOf, parseNumericPrefix } from '../site/content-collector.js'
27
-
28
- const DYNAMIC_RE = /^\[(.+)\]$/
29
-
30
- // The collector's own reading of a config file (`parseYaml`): absent or unreadable is empty.
31
- function readYaml(filePath) {
32
- try {
33
- return yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS) || {}
34
- } catch {
35
- return {}
36
- }
37
- }
38
-
39
- // A folder's mode, as `readFolderConfig` reads it.
40
- function modeOf(dir, inheritedMode) {
41
- const folderYml = readYaml(join(dir, 'folder.yml'))
42
- const pageYml = Object.keys(folderYml).length > 0 ? {} : readYaml(join(dir, 'page.yml'))
43
- return folderContentMode(folderYml, pageYml, existsSync(join(dir, 'folder.yml')), inheritedMode).mode
44
- }
45
-
46
- /**
47
- * The pages of a site a pull leaves alone, by route: each a slug path with no leading slash
48
- * (`docs/start/install`), as the pull composes a page's route from the document.
49
- *
50
- * @param {object|null} siteYml - the parsed `site.yml`
51
- * @param {string} pagesDir - the site's pages directory (`siteContentDirs`)
52
- * @returns {{ mounted: Set<string>, files: Set<string>, has: (route: string) => boolean }}
53
- * `mounted` — the mounted segments, each leaving its whole route alone; `files` — the routes of
54
- * folder-mode `.md` pages; `has` — whether a route is either
55
- */
56
- export function gitAuthoredPages(siteYml, pagesDir) {
57
- const mounted = new Set(mountEntriesOf(siteYml?.paths).map(([segment]) => segment))
58
- const files = new Set()
59
- const walk = (dir, prefix, inheritedMode) => {
60
- let entries
61
- try {
62
- entries = readdirSync(dir, { withFileTypes: true })
63
- } catch {
64
- return
65
- }
66
- const mode = modeOf(dir, inheritedMode)
67
- if (mode === 'pages') {
68
- for (const { name } of folderModePageFiles(entries.map((e) => e.name)).files) {
69
- files.add(prefix + name)
70
- }
71
- }
72
- for (const e of entries) {
73
- if (!e.isDirectory() || isIgnoredFolder(e.name)) continue
74
- if (!prefix && mounted.has(e.name)) continue // the whole route is left alone
75
- const dyn = e.name.match(DYNAMIC_RE)
76
- walk(join(dir, e.name), `${prefix}${dyn ? dyn[1] : parseNumericPrefix(e.name).name}/`, mode)
77
- }
78
- }
79
- if (existsSync(pagesDir)) walk(pagesDir, '', 'sections')
80
- return {
81
- mounted,
82
- files,
83
- has: (route) => mounted.has(String(route).split('/')[0]) || files.has(route),
84
- }
85
- }