@uniweb/build 1.15.6 → 1.16.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.
@@ -0,0 +1,94 @@
1
+ /**
2
+ * ⭐ WHAT A PUSH LEAVES OUT: a page or a section a pull HELD. The app changed it in a way its files
3
+ * cannot say — a second section in a folder of single-section pages, a setting an `.md` page has no
4
+ * place for, a move to where a page cannot sit — so the pull wrote nothing for it, and the site keeps
5
+ * the app's version (`site-project.js`, `report.held`).
6
+ *
7
+ * The pull records where the files keep each held unit, and what they said there (`heldUnitsOf`). A push
8
+ * sends none whose files still say it: the backend then keeps the app's version, since it deletes only
9
+ * an item a push holds a version for, and a pull banks none for a held one. A push stops on one whose
10
+ * files changed since the pull, because the app's version and the file's would both claim it
11
+ * (`leaveHeldOut`). `--force` sends the files' version over the app's, as it sends everything else.
12
+ *
13
+ * ⛔ Until 2026-11-04 a held page kept the version this copy last agreed on, for the backend's gate to
14
+ * keep the app's. A copy that never agreed on one — a fresh clone, a CI checkout, a copy that lost its
15
+ * `.uniweb/` — banked the backend's version on its first pull, and its next push sent the file over the
16
+ * app's edit.
17
+ *
18
+ * Both sides compare the document the files give before any media is rewritten (`plain`): a push that
19
+ * has uploaded a picture names its serve URL, and the pull that recorded the page named none.
20
+ */
21
+ import { computeUnitHashes, walkSiteUnits } from './site-diff.js'
22
+
23
+ const isPageUnit = (path) => path.endsWith('/page.yml') || path.endsWith('/folder.yml')
24
+ // A page's own units and everything below it share its folder: `pages/docs/guide/…`.
25
+ const belowPage = (path) => `${path.slice(0, path.lastIndexOf('/'))}/`
26
+
27
+ /**
28
+ * The units a pull held, as the files keep them: each held item's unit, and for a page every unit
29
+ * below it, by its path in the files' document, with the hash the files gave each.
30
+ *
31
+ * @param {object} p
32
+ * @param {Object<string,string>} p.hashes - path → hash, of the files' document (`computeUnitHashes`)
33
+ * @param {Object<string,string>} p.uuids - path → `$uuid`, of the same document stamped with the
34
+ * identity this copy held before the pull, so a page the app moved is found where the files keep it
35
+ * @param {Iterable<string>} p.held - the `$uuid`s the pull held
36
+ * @returns {Object<string,string>} path → hash; a held item the files do not hold has no entry
37
+ */
38
+ export function heldUnitsOf({ hashes = {}, uuids = {}, held = [] } = {}) {
39
+ const wanted = new Set(held)
40
+ const out = {}
41
+ const pages = []
42
+ for (const [path, uuid] of Object.entries(uuids)) {
43
+ if (!wanted.has(uuid) || !(path in hashes)) continue
44
+ out[path] = hashes[path]
45
+ if (isPageUnit(path)) pages.push(belowPage(path))
46
+ }
47
+ for (const [path, hash] of Object.entries(hashes)) if (pages.some((p) => path.startsWith(p))) out[path] = hash
48
+ return out
49
+ }
50
+
51
+ /**
52
+ * Take the held units out of a push's document where the files still say what they said at the pull.
53
+ * When any of them changed — its file edited or removed, or a page or section added below a held page —
54
+ * nothing is taken out, and the paths are returned for the push to stop on.
55
+ *
56
+ * @param {object} doc - the site-content document a push sends; changed in place
57
+ * @param {object} p
58
+ * @param {Object<string,string>} p.held - what the pull recorded (`heldUnitsOf`)
59
+ * @param {object} [p.plain] - the same document before any media was rewritten; `doc` when absent
60
+ * @param {string} [p.sourceLocale]
61
+ * @returns {{ left: string[], changed: string[] }} the paths taken out, or the paths that changed
62
+ */
63
+ export function leaveHeldOut(doc, { held = {}, plain = null, sourceLocale } = {}) {
64
+ const paths = Object.keys(held)
65
+ if (!doc || !paths.length) return { left: [], changed: [] }
66
+ const now = computeUnitHashes(plain ?? doc, sourceLocale)
67
+ const changed = new Set(paths.filter((path) => now[path] !== held[path]))
68
+ const pages = paths.filter(isPageUnit).map(belowPage)
69
+ for (const path of Object.keys(now)) if (!(path in held) && pages.some((p) => path.startsWith(p))) changed.add(path)
70
+ if (changed.size) return { left: [], changed: [...changed].sort() }
71
+
72
+ const drop = new Set()
73
+ walkSiteUnits(doc, (path, record) => {
74
+ if (path in held) drop.add(record)
75
+ }, sourceLocale)
76
+ const keep = (list) => list.filter((r) => !drop.has(r))
77
+ const sections = (list) => {
78
+ for (const s of list || []) {
79
+ if (Array.isArray(s.$children)) s.$children = keep(s.$children)
80
+ sections(s.$children)
81
+ }
82
+ }
83
+ const walk = (list) => {
84
+ for (const page of list || []) {
85
+ if (Array.isArray(page.page_sections)) page.page_sections = keep(page.page_sections)
86
+ sections(page.page_sections)
87
+ if (Array.isArray(page.$children)) page.$children = keep(page.$children)
88
+ walk(page.$children)
89
+ }
90
+ }
91
+ if (Array.isArray(doc.pages)) doc.pages = keep(doc.pages)
92
+ walk(doc.pages)
93
+ return { left: paths.sort(), changed: [] }
94
+ }
package/src/uwx/index.js CHANGED
@@ -153,6 +153,8 @@ export {
153
153
  siteItemsByKey,
154
154
  stampUnitUuids,
155
155
  } from './site-diff.js'
156
+ // What a pull held, and what a push leaves out of it (`held-units.js`).
157
+ export { heldUnitsOf, leaveHeldOut } from './held-units.js'
156
158
  // What a backend that cleans rich text at write removed from a push, read against what was sent.
157
159
  export { siteContentRemovals, recordRemovals, cleanedRecord } from './cleaned.js'
158
160
  export {
@@ -8,10 +8,10 @@
8
8
  // in the app was undone by the next push.
9
9
  //
10
10
  // The pages a pull leaves alone are now those it may not or cannot write:
11
- // · every page under a read-only `paths: { pages/<segment>: <dir> }` mount — any the site does not
12
- // declare `writable: true`, or whose folder the caller may not write (`writable`). Its files are
13
- // another repository's, or a folder outside the site; the local folder of that name holds only how
14
- // this site presents them, and a pull writing the mounted pages into it would grow a second copy;
11
+ // · every page under a `paths: { pages/<segment>: <dir> }` mount the caller may not write
12
+ // (`writable`) — for a pull, one it cannot merge into: a clone beside the site, a folder in no
13
+ // repository. The local folder of that name holds only how this site presents the mount's pages,
14
+ // and a pull writing them into it would grow a second copy there;
15
15
  // · a route the files give two pages for — a file and a folder of one name, `topics.md` beside
16
16
  // `topics/` — since a page in the document cannot say which of the two it is.
17
17
  // A pull deletes neither, nor a folder that holds one (`holds`): a pull never deletes what it does not
@@ -23,7 +23,7 @@
23
23
  //
24
24
  // A leaf, read synchronously as the pull projects (`site-project.js`), through the rules the push's
25
25
  // walk reads with — `folderContentMode`, `folderModePageFiles`, `parseNumericPrefix`,
26
- // `layerMountedFolder`, `mountDeclarationsOf` — so the pages it finds are the ones the push sends
26
+ // `layerMountedFolder`, `mountEntriesOf` — so the pages it finds are the ones the push sends
27
27
  // (`tests/uwx-page-files.test.js`).
28
28
 
29
29
  import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
@@ -32,7 +32,7 @@ import yaml from 'js-yaml'
32
32
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
33
33
  import { isIgnoredFolder } from '../utils/content-files.js'
34
34
  import { extractH1, folderContentMode, folderModePageFiles, layerMountedFolder, parseNumericPrefix, prettifySlug } from '../site/content-collector.js'
35
- import { mountDeclarationsOf } from '../site/mount-entries.js'
35
+ import { mountEntriesOf } from '../site/mount-entries.js'
36
36
  import { unwrapLocalized } from './backfill.js'
37
37
  import { isProseMirrorDoc } from './locale-sync.js'
38
38
 
@@ -99,7 +99,7 @@ const isDirectory = (p) => {
99
99
  * @param {{ seen?: Set<string>|null, siteRoot?: string|null, writable?: Iterable<string>|null }} [opts] -
100
100
  * `seen`, the routes of the pages this copy has seen the backend hold: a folder holding an `.md`
101
101
  * page it never saw is one a prune keeps (`holds`). `writable`, the segments of the mounts the
102
- * caller may write — each one the site declares `writable: true` is walked into, from `siteRoot`
102
+ * caller may write, each walked into from `siteRoot`
103
103
  * @returns {{
104
104
  * page: (route: string) => object|null,
105
105
  * levelMode: (dir: string) => 'pages'|'sections'|undefined,
@@ -110,17 +110,17 @@ const isDirectory = (p) => {
110
110
  * mount's segment and folder
111
111
  */
112
112
  export function sitePageFiles(siteYml, pagesDir, { seen = null, siteRoot = null, writable = null } = {}) {
113
- const declared = mountDeclarationsOf(siteYml?.paths)
114
- const mounted = new Set(declared.map((d) => d.segment))
115
- // ⭐ A mount is written only where the site declares it `writable: true` AND the caller may write
116
- // its folder — a pull decides that by the repository holding it, and any other caller writes none.
113
+ const declared = mountEntriesOf(siteYml?.paths)
114
+ const mounted = new Set(declared.map(([segment]) => segment))
115
+ // ⭐ A mount is written where the caller may write its folder — a pull decides that by the repository
116
+ // holding it — and any other caller writes none.
117
117
  const allowed = new Set(writable ?? [])
118
118
  const writableMounts = new Map()
119
- for (const d of declared) {
120
- if (!d.writable || !allowed.has(d.segment) || !siteRoot || typeof d.path !== 'string' || !d.path) continue
119
+ for (const [segment, folder] of declared) {
120
+ if (!allowed.has(segment) || !siteRoot || typeof folder !== 'string' || !folder) continue
121
121
  // The folder as the push reads it: through any link to it (`resolveMounts`).
122
- const dir = resolve(siteRoot, d.path)
123
- writableMounts.set(d.segment, existsSync(dir) ? realpathSync(dir) : dir)
122
+ const dir = resolve(siteRoot, folder)
123
+ writableMounts.set(segment, existsSync(dir) ? realpathSync(dir) : dir)
124
124
  }
125
125
  const places = new Map()
126
126
  const modes = new Map()
@@ -21,6 +21,7 @@ import { parseFrontmatter } from './entity-source.js'
21
21
  import { canonicalJson, sameMarkdownDocument } from './same-content.js'
22
22
  import { spliceBody } from './body-splice.js'
23
23
  import { fileLinksIn } from '../site/file-links.js'
24
+ import { parseNumericPrefix } from '../utils/numeric-prefix.js'
24
25
  import { renderEntityDocument } from './backfill.js'
25
26
  import { queriesYmlPath } from './queries-config.js'
26
27
  import { folderYmlPath } from '../site/records-config.js'
@@ -90,8 +91,9 @@ export function resolveSectionFile(dirPath, stableId) {
90
91
  let name = base.startsWith('@') ? base.slice(1) : base
91
92
  if (name.toLowerCase() === target) return join(dirPath, entry)
92
93
 
93
- const numMatch = name.match(/^\d+-(.+)$/)
94
- if (numMatch && numMatch[1].toLowerCase() === target) return join(dirPath, entry)
94
+ // Its name with the number that orders it dropped, by the one rule: `2.5-setup.md` is `setup`.
95
+ const numbered = parseNumericPrefix(name)
96
+ if (numbered.prefix && numbered.name.toLowerCase() === target) return join(dirPath, entry)
95
97
  }
96
98
  return null
97
99
  }
@@ -302,6 +304,15 @@ function writeYamlIfChanged(filePath, value, prior) {
302
304
 
303
305
  const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
304
306
 
307
+ /**
308
+ * Write `site.yml`'s `paths:` whole, its comments and layout kept; with no entry left it goes. A
309
+ * mounted route renamed or removed in the app renames or removes its key (`site-project.js`).
310
+ * @returns {'updated'|'unchanged'}
311
+ */
312
+ export function writeSitePaths(siteRoot, paths) {
313
+ return mergeYamlConfig(join(siteRoot, 'site.yml'), { paths: paths && Object.keys(paths).length ? paths : null }, { replace: ['paths'] })
314
+ }
315
+
305
316
  /**
306
317
  * Merge `config` into `site.yml` (shallow). Preserves keys not present in the
307
318
  * update (foundation, base, paths, …).
@@ -0,0 +1,18 @@
1
+ /**
2
+ * A route's `mode` on the site-content document: what its pages may hold, which the app honours, and
3
+ * not how the files hold them.
4
+ *
5
+ * - `single-section`: each page under the route holds one section and no page of its own, as a folder
6
+ * in folder mode keeps them, one `.md` file each. A route under it that holds no section is
7
+ * `single-section` too, and the route holds no section of its own, except a page above a mounted
8
+ * folder of `.md` pages.
9
+ * - `page`: any other route.
10
+ *
11
+ * A push writes each route's own value, so nothing says "inherit" (`site.js::walkPagesNested`). A pull
12
+ * reads it only for a route its files do not hold yet; a route they hold takes its form from them
13
+ * (`site-project.js`). `folder` is the old spelling, which a stored document carries until its site's
14
+ * next push: only a unit's identity reads it (`site-diff.js::walkSiteUnits`).
15
+ *
16
+ * A leaf, with no imports.
17
+ */
18
+ export const SINGLE_SECTION = 'single-section'
@@ -49,6 +49,7 @@
49
49
  import { entityContentHash } from './records.js'
50
50
  import { sectionFileBases, pageDirName, layoutSectionPaths } from './site-project.js'
51
51
  import { documentSourceLocale } from './source-locale.js'
52
+ import { SINGLE_SECTION } from './route-mode.js'
52
53
 
53
54
  // A unit's own content, with the nested collections that are their own units
54
55
  // removed — so editing a section never also marks its page (or its parent
@@ -112,8 +113,12 @@ export function walkSiteUnits(doc, cb, sourceLocale = documentSourceLocale(doc))
112
113
  const dirName = pageDirName(record, sourceLocale)
113
114
  if (!dirName) continue
114
115
  const dir = `${parentDir}/${dirName}`
115
- cb(`${dir}/${record.mode === 'folder' ? 'folder.yml' : 'page.yml'}`, record, 'page')
116
- if (record.mode !== 'folder') walkSections(record.page_sections, dir)
116
+ // A route of single-section pages is its `folder.yml`, in either spelling: `folder` is the one a
117
+ // push wrote until 2026-11-04, which a stored document carries until its site's next push, and a
118
+ // unit keyed otherwise would read as one the app changed. Delete `folder` here once no synced site's
119
+ // document carries it.
120
+ cb(`${dir}/${record.mode === SINGLE_SECTION || record.mode === 'folder' ? 'folder.yml' : 'page.yml'}`, record, 'page')
121
+ walkSections(record.page_sections, dir)
117
122
  walkPages(record.$children, dir)
118
123
  }
119
124
  }