@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.
@@ -0,0 +1,85 @@
1
+ // ⭐ A PULL WRITES THE CHANGE, NOT A NEW RENDERING OF THE FILE.
2
+ // A changed body keeps the author's text for every top-level block the backend's document still holds,
3
+ // and takes the writer's form only for the blocks it changed, added or moved; a removed one goes.
4
+ //
5
+ // ⛔ Until 2026-11-04 a changed body was re-serialized whole. Measured that day over the 133 pages of
6
+ // three mounted docs folders: a one-word edit rewrote a median of 12 lines — every hard-wrapped
7
+ // paragraph joined, every table rule rewritten — in 115 of them.
8
+ //
9
+ // The blocks are the reader's (`markdownBlocks`, `@uniweb/content-reader`), so a block is what the
10
+ // author's text reads as, and a body the reader cannot split so, or whose splice does not read back to
11
+ // the document, is written whole as before.
12
+ //
13
+ // `links` reads a block as the push reads it, and writes a new one as the file writes its links
14
+ // (`site/file-links.js::fileLinksIn`): a block linking another file by its file is the block the
15
+ // backend holds with a page link, and keeps the author's link.
16
+
17
+ import { markdownBlocks } from '@uniweb/content-reader'
18
+ import { proseMirrorToMarkdown } from '@uniweb/content-writer'
19
+ import { canonicalJson, sameMarkdownDocument, withoutDefaults } from './same-content.js'
20
+
21
+ const keyOf = (node) => canonicalJson(withoutDefaults(node))
22
+
23
+ // The longest run of keys the two lists share, in order: each pair `[i, j]`, `a[i]` equal to `b[j]`.
24
+ function commonPairs(a, b) {
25
+ const n = a.length
26
+ const m = b.length
27
+ const dp = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1))
28
+ for (let i = n - 1; i >= 0; i--) {
29
+ for (let j = m - 1; j >= 0; j--) dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1])
30
+ }
31
+ const pairs = []
32
+ for (let i = 0, j = 0; i < n && j < m; ) {
33
+ if (a[i] === b[j]) pairs.push([i++, j++])
34
+ else if (dp[i + 1][j] >= dp[i][j + 1]) i++
35
+ else j++
36
+ }
37
+ return pairs
38
+ }
39
+
40
+ /**
41
+ * The author's body with the backend's document written into it, block by block — or null when it
42
+ * cannot be said so, and the caller writes the document whole.
43
+ *
44
+ * @param {string} authored - the body as the file holds it, frontmatter apart
45
+ * @param {object} doc - the backend's ProseMirror document for it
46
+ * @param {{ links?: { resolve: Function, restore: Function }|null }} [opts]
47
+ * @returns {string|null} the new body, with no trailing whitespace
48
+ */
49
+ export function spliceBody(authored, doc, { links = null } = {}) {
50
+ const split = markdownBlocks(authored)
51
+ if (!split || !Array.isArray(doc?.content)) return null
52
+ // Each block that reads to one node is an item; one that reads to none (a link reference) rides
53
+ // with the item before it, kept where it was. A block of several nodes leaves nothing to align.
54
+ const items = []
55
+ let head = split.head
56
+ for (const block of split.blocks) {
57
+ if (block.nodes.length > 1) return null
58
+ if (block.nodes.length === 0) {
59
+ if (items.length) items[items.length - 1].after += block.text + block.after
60
+ else head += block.text + block.after
61
+ continue
62
+ }
63
+ items.push({ text: block.text, after: block.after, key: keyOf(links ? links.resolve(block.nodes[0]) : block.nodes[0]) })
64
+ }
65
+ const nodes = doc.content
66
+ const kept = new Map(commonPairs(items.map((i) => i.key), nodes.map(keyOf)).map(([i, j]) => [j, i]))
67
+ // The new body's pieces in the document's order: an item the change left as the author wrote it, or a
68
+ // run of nodes the writer writes.
69
+ const pieces = []
70
+ for (let j = 0; j < nodes.length; j++) {
71
+ if (kept.has(j)) pieces.push({ item: kept.get(j) })
72
+ else if (pieces.length && pieces[pieces.length - 1].nodes) pieces[pieces.length - 1].nodes.push(nodes[j])
73
+ else pieces.push({ nodes: [nodes[j]] })
74
+ }
75
+ let out = pieces[0]?.item === 0 ? head : ''
76
+ pieces.forEach((piece, k) => {
77
+ const written = links ? piece.nodes?.map((node) => links.restore(node)) : piece.nodes
78
+ out += written ? proseMirrorToMarkdown({ type: 'doc', content: written }).replace(/\s+$/, '') : items[piece.item].text
79
+ const next = pieces[k + 1]
80
+ // Two of the author's blocks still side by side keep what stood between them.
81
+ if (next) out += piece.item !== undefined && next.item === piece.item + 1 ? items[piece.item].after : '\n\n'
82
+ })
83
+ const body = out.replace(/^\n+/, '').replace(/\s+$/, '')
84
+ return sameMarkdownDocument(body, doc, { resolve: links?.resolve }) ? body : null
85
+ }
@@ -547,6 +547,10 @@ function lowerLeaf(field, resolve, optResolve, { multiple = false, path = '' } =
547
547
  if (field.label) out.label = field.label
548
548
  if (field.description) out.description = field.description
549
549
  if (field.required) out.required = true
550
+ // A value a site's visitor may fill, on any leaf kind, as authored [backend, 2026-11-04]. A type
551
+ // with one takes visitors' submissions; `@uniweb/schemas` refuses it where a registry would, and
552
+ // drops `false`, so only `true` is sent.
553
+ if (field.visitor_fills === true) out.visitor_fills = true
550
554
  // A field's rules, as written — `max_length`, `min`, `max`, `mime_types`, `max_size`,
551
555
  // `pattern` (`FIELD_RULES`): a registry keeps each as the field's own key and checks it on
552
556
  // every write. ⛔ Until 2026-10-15 the normalizer dropped them before this saw them.
@@ -77,9 +77,6 @@
77
77
  "og_title": [
78
78
  "site.yml::seo"
79
79
  ],
80
- "paths": [
81
- "site.yml::paths"
82
- ],
83
80
  "placeholders": [
84
81
  "site.yml::placeholders"
85
82
  ],
@@ -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
@@ -89,6 +89,9 @@ export { dataBlockModels } from '../i18n/data-models.js'
89
89
  // The type a section that names none renders with — a push fills it in, and a pull, handed it up
90
90
  // front like the scope above, leaves it out of the section's file.
91
91
  export { siteDefaultSectionType } from '../site/queries-config.js'
92
+ // Every place a push reads the site's content from, mounts included — the one answer the CLI's
93
+ // committed-content check, a pull's merge and `uniweb status` read (`site-dirs.js`).
94
+ export { siteContentRoots } from './site-dirs.js'
92
95
  export {
93
96
  siteInfoToConfig,
94
97
  sectionRecordToFile,
@@ -150,6 +153,8 @@ export {
150
153
  siteItemsByKey,
151
154
  stampUnitUuids,
152
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'
153
158
  // What a backend that cleans rich text at write removed from a push, read against what was sent.
154
159
  export { siteContentRemovals, recordRemovals, cleanedRecord } from './cleaned.js'
155
160
  export {
@@ -0,0 +1,255 @@
1
+ // WHERE EACH PAGE OF A SITE IS KEPT — found in its files by the build's own rules, never computed from
2
+ // a document: a document says what a page is, not where its files are. A pull writes a page where this
3
+ // says it lives: `2-about/` holds /about, and `guide/1-install.md` holds /guide/install.
4
+ //
5
+ // ⛔ Until 2026-11-04 a pull named a page's folder by its slug (`pageDirName`): `pages/2-about/` came
6
+ // back as `pages/about/`, the numbered folder pruned. And it could not write a folder-mode `.md` page
7
+ // at all, so it left every one alone (`git-authored.js`, which this replaces), and an edit made to one
8
+ // in the app was undone by the next push.
9
+ //
10
+ // The pages a pull leaves alone are now those it may not or cannot write:
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
+ // · a route the files give two pages for — a file and a folder of one name, `topics.md` beside
16
+ // `topics/` — since a page in the document cannot say which of the two it is.
17
+ // A pull deletes neither, nor a folder that holds one (`holds`): a pull never deletes what it does not
18
+ // write.
19
+ //
20
+ // ⭐ A WRITABLE MOUNT'S PAGES ARE WHERE THE PUSH READS THEM: in the mounted folder, its own route layered
21
+ // as the push layers it (`layerMountedFolder`) — the stub's config over the mounted folder's, the
22
+ // route's sections in the stub when there is one, its pages in the mounted folder.
23
+ //
24
+ // A leaf, read synchronously as the pull projects (`site-project.js`), through the rules the push's
25
+ // walk reads with — `folderContentMode`, `folderModePageFiles`, `parseNumericPrefix`,
26
+ // `layerMountedFolder`, `mountEntriesOf` — so the pages it finds are the ones the push sends
27
+ // (`tests/uwx-page-files.test.js`).
28
+
29
+ import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
30
+ import { dirname, join, resolve, sep } from 'node:path'
31
+ import yaml from 'js-yaml'
32
+ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
33
+ import { isIgnoredFolder } from '../utils/content-files.js'
34
+ import { extractH1, folderContentMode, folderModePageFiles, layerMountedFolder, parseNumericPrefix, prettifySlug } from '../site/content-collector.js'
35
+ import { mountEntriesOf } from '../site/mount-entries.js'
36
+ import { unwrapLocalized } from './backfill.js'
37
+ import { isProseMirrorDoc } from './locale-sync.js'
38
+
39
+ const DYNAMIC_RE = /^\[(.+)\]$/
40
+
41
+ // The collector's own reading of a config file (`parseYaml`): absent or unreadable is empty.
42
+ function readYaml(filePath) {
43
+ try {
44
+ return yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS) || {}
45
+ } catch {
46
+ return {}
47
+ }
48
+ }
49
+
50
+ /**
51
+ * A folder's mode as the build reads it now (`readFolderConfig`): `pages` — its `.md` files are pages —
52
+ * or `sections` — they are its page's sections. A folder with no config of its own inherits.
53
+ *
54
+ * @param {string} dir
55
+ * @param {'pages'|'sections'} inheritedMode
56
+ * @returns {'pages'|'sections'}
57
+ */
58
+ export function folderModeOf(dir, inheritedMode) {
59
+ return folderConfigOf(dir, inheritedMode).mode
60
+ }
61
+
62
+ /**
63
+ * A folder's config as the build reads it (`readFolderConfig`): the config, its mode, and the file it
64
+ * is in — `source`, `'inherited'` when there is none.
65
+ *
66
+ * @param {string} dir
67
+ * @param {'pages'|'sections'} inheritedMode
68
+ * @returns {{ config: object, mode: 'pages'|'sections', source: 'folder.yml'|'page.yml'|'inherited' }}
69
+ */
70
+ export function folderConfigOf(dir, inheritedMode) {
71
+ const folderYml = readYaml(join(dir, 'folder.yml'))
72
+ const pageYml = Object.keys(folderYml).length > 0 ? {} : readYaml(join(dir, 'page.yml'))
73
+ const { mode, source } = folderContentMode(folderYml, pageYml, existsSync(join(dir, 'folder.yml')), inheritedMode)
74
+ return { config: source === 'folder.yml' ? folderYml : source === 'page.yml' ? pageYml : {}, mode, source }
75
+ }
76
+
77
+ const isDirectory = (p) => {
78
+ try {
79
+ return statSync(p).isDirectory()
80
+ } catch {
81
+ return false
82
+ }
83
+ }
84
+
85
+ /**
86
+ * The pages of a site, each by its route — a slug path with no leading slash (`docs/start/install`),
87
+ * as the pull composes a page's route from the document — and where it is kept:
88
+ *
89
+ * - `{ kind: 'folder', dir }`: a page folder, with its `page.yml` or `folder.yml` and its sections;
90
+ * - `{ kind: 'md', file, dir }`: a folder-mode `.md` file in the level `dir` — the page and its one section;
91
+ * - `{ kind: 'folder', dir, mount }`: a writable mount's own route — its sections in `dir`, the stub
92
+ * when there is one, else the mounted folder; its pages in `mount.dir`, walked in `mount.childMode`;
93
+ * its config layered from `mount.stub` over `mount.mounted`, each `folderConfigOf` with its folder;
94
+ * - `{ kind: 'mounted', segment }`: a route under a read-only mount, left alone;
95
+ * - `{ kind: 'twice', dir, file }`: a route the files give two pages for, left alone.
96
+ *
97
+ * @param {object|null} siteYml - the parsed `site.yml`
98
+ * @param {string} pagesDir - the site's pages directory (`siteContentDirs`)
99
+ * @param {{ seen?: Set<string>|null, siteRoot?: string|null, writable?: Iterable<string>|null }} [opts] -
100
+ * `seen`, the routes of the pages this copy has seen the backend hold: a folder holding an `.md`
101
+ * page it never saw is one a prune keeps (`holds`). `writable`, the segments of the mounts the
102
+ * caller may write, each walked into from `siteRoot`
103
+ * @returns {{
104
+ * page: (route: string) => object|null,
105
+ * levelMode: (dir: string) => 'pages'|'sections'|undefined,
106
+ * mounted: Set<string>,
107
+ * writable: Map<string, string>,
108
+ * holds: (dir: string) => boolean,
109
+ * }} `mounted`, every mount's segment, whose local folder is a stub; `writable`, each writable
110
+ * mount's segment and folder
111
+ */
112
+ export function sitePageFiles(siteYml, pagesDir, { seen = null, siteRoot = null, writable = null } = {}) {
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
+ const allowed = new Set(writable ?? [])
118
+ const writableMounts = new Map()
119
+ for (const [segment, folder] of declared) {
120
+ if (!allowed.has(segment) || !siteRoot || typeof folder !== 'string' || !folder) continue
121
+ // The folder as the push reads it: through any link to it (`resolveMounts`).
122
+ const dir = resolve(siteRoot, folder)
123
+ writableMounts.set(segment, existsSync(dir) ? realpathSync(dir) : dir)
124
+ }
125
+ const places = new Map()
126
+ const modes = new Map()
127
+ const put = (route, place) => {
128
+ const had = places.get(route)
129
+ if (!had) return places.set(route, place)
130
+ // A file and a folder of one name: both stay, as the push sends both.
131
+ places.set(route, { kind: 'twice', dir: had.kind === 'folder' ? had.dir : place.dir, file: had.kind === 'md' ? had.file : place.file })
132
+ }
133
+ // `ownMode`: the mode a level is read in when its parent decided it — a writable mount's folder, read
134
+ // in the mode its route gives its pages, never by its own config alone.
135
+ const walk = (dir, prefix, inheritedMode, ownMode = null) => {
136
+ let entries
137
+ try {
138
+ entries = readdirSync(dir, { withFileTypes: true })
139
+ } catch {
140
+ return
141
+ }
142
+ const mode = ownMode ?? folderModeOf(dir, inheritedMode)
143
+ modes.set(dir, mode)
144
+ if (mode === 'pages') {
145
+ for (const { file, name } of folderModePageFiles(entries.map((e) => e.name)).files) {
146
+ put(prefix + name, { kind: 'md', file: join(dir, file), dir })
147
+ }
148
+ }
149
+ for (const e of entries) {
150
+ if (!e.isDirectory() || isIgnoredFolder(e.name)) continue
151
+ if (!prefix && mounted.has(e.name)) continue // the whole route is the mount's
152
+ const dyn = e.name.match(DYNAMIC_RE)
153
+ const route = prefix + (dyn ? dyn[1] : parseNumericPrefix(e.name).name)
154
+ put(route, { kind: 'folder', dir: join(dir, e.name) })
155
+ walk(join(dir, e.name), `${route}/`, mode)
156
+ }
157
+ }
158
+ if (existsSync(pagesDir)) walk(pagesDir, '', 'sections')
159
+
160
+ // Each writable mount's own route, as the push reads it at the site's root (`orderedSubfolders`), and
161
+ // its pages, walked in the mounted folder.
162
+ const rootMode = modes.get(pagesDir) ?? 'sections'
163
+ for (const [segment, mountDir] of writableMounts) {
164
+ const stubDir = join(pagesDir, segment)
165
+ const stub = isDirectory(stubDir) ? folderConfigOf(stubDir, rootMode) : null
166
+ const mountedConfig = folderConfigOf(mountDir, 'pages')
167
+ const { dirConfig, dirMode, childMode } = layerMountedFolder(segment, stub, mountedConfig, rootMode)
168
+ put(segment, {
169
+ kind: 'folder',
170
+ dir: stub ? stubDir : mountDir,
171
+ mount: { segment, dir: mountDir, stubDir, stub, mounted: mountedConfig, config: dirConfig, mode: dirMode, childMode },
172
+ })
173
+ walk(mountDir, `${segment}/`, childMode, childMode)
174
+ }
175
+
176
+ // Each folder holding a page a prune must not take, and each one above it, up to the pages directory
177
+ // or the mounted folder it is in: removing any of them would remove that page with it. Those are the
178
+ // pages a pull leaves alone, and an `.md` page this copy never saw the backend hold — ⛔ a push before
179
+ // 2026-10-23 sent no folder-mode page, so a backend can lack one the files have always held, and read
180
+ // as deleted it would go.
181
+ const tops = [pagesDir, ...writableMounts.values()]
182
+ const holding = new Set()
183
+ const hold = (dir) => {
184
+ const top = tops.find((t) => dir === t || dir.startsWith(t + sep))
185
+ if (!top) return
186
+ for (let d = dir; d && d !== top; d = dirname(d)) holding.add(d)
187
+ }
188
+ for (const [route, place] of places) {
189
+ if (place.kind === 'twice') {
190
+ hold(place.dir)
191
+ hold(dirname(place.file))
192
+ } else if (place.kind === 'md' && !seen?.has(route)) hold(place.dir)
193
+ }
194
+ return {
195
+ page: (route) => {
196
+ const segment = String(route).split('/')[0]
197
+ if (mounted.has(segment) && !writableMounts.has(segment)) return { kind: 'mounted', segment }
198
+ return places.get(route) ?? null
199
+ },
200
+ levelMode: (dir) => modes.get(dir),
201
+ mounted,
202
+ writable: writableMounts,
203
+ holds: (dir) => holding.has(dir),
204
+ }
205
+ }
206
+
207
+ // The page fields a push sends for a folder-mode `.md` page are its title and `hidden`
208
+ // (`folderModePageRecords`, `site.js`), and `is_index` where it is the homepage. A page carrying any of
209
+ // these needs a page folder to hold it.
210
+ const NOT_IN_AN_MD_PAGE = ['description', 'label', 'keywords', 'hide_in', 'knowledge', 'track_sections', 'redirect', 'rewrite', 'layout', 'og_title', 'og_description', 'seo', 'fetch']
211
+
212
+ const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
213
+
214
+ // Does a field carry a value, its source locale's for a localized one?
215
+ function holdsValue(value, sourceLocale) {
216
+ if (value === undefined || value === null || value === false || value === '') return false
217
+ if (Array.isArray(value)) return value.length > 0
218
+ if (isPlainObject(value)) {
219
+ if (Object.prototype.hasOwnProperty.call(value, sourceLocale)) return holdsValue(value[sourceLocale], sourceLocale)
220
+ return Object.keys(value).length > 0
221
+ }
222
+ return true
223
+ }
224
+
225
+ /**
226
+ * What of a page a folder-mode `.md` file cannot hold — none, when it can be written as one. The file is
227
+ * the page and its one section: its title is its first heading, else its name prettified, and its
228
+ * frontmatter's `hidden:` drafts it. A second section, pages below it, a route parameter, a title its
229
+ * heading does not give, or any other page setting, it cannot say.
230
+ *
231
+ * ⚖️ A setting such a page might hold in its frontmatter is project-file-organization's §10 decision 1,
232
+ * not settled; until it is, a pull writes none.
233
+ *
234
+ * @param {object} record - the page's record
235
+ * @param {{ name: string, sourceLocale: string }} opts - `name`, the file's page name (`1-install.md` → `install`)
236
+ * @returns {string[]} what it cannot hold, in words
237
+ */
238
+ export function mdPageCannotHold(record, { name, sourceLocale }) {
239
+ const out = []
240
+ const sections = Array.isArray(record?.page_sections) ? record.page_sections : []
241
+ if (sections.length !== 1) out.push(sections.length ? 'more than one section' : 'no section')
242
+ if (Array.isArray(record?.$children) && record.$children.length) out.push('pages below it')
243
+ if (record?.is_dynamic) out.push('a route parameter')
244
+ // Its id is its file's name; one the name does not give needs a page folder's `id:`.
245
+ if (typeof record?.stable_id === 'string' && record.stable_id && record.stable_id !== name) out.push('an id its file name does not give')
246
+ for (const key of NOT_IN_AN_MD_PAGE) if (holdsValue(record?.[key], sourceLocale)) out.push(key)
247
+ if (sections.length === 1) {
248
+ const content = sections[0]?.content
249
+ const doc = isProseMirrorDoc(content) ? content : unwrapLocalized(content, sourceLocale)
250
+ const given = extractH1(doc) || prettifySlug(name)
251
+ const title = unwrapLocalized(record?.title, sourceLocale)
252
+ if (typeof title === 'string' && title && title !== given) out.push('a title its first heading does not give')
253
+ }
254
+ return out
255
+ }
@@ -19,6 +19,9 @@ import { proseMirrorToMarkdown, serializeFrontmatter } from '@uniweb/content-wri
19
19
  import { markdownToProseMirror } from '@uniweb/content-reader'
20
20
  import { parseFrontmatter } from './entity-source.js'
21
21
  import { canonicalJson, sameMarkdownDocument } from './same-content.js'
22
+ import { spliceBody } from './body-splice.js'
23
+ import { fileLinksIn } from '../site/file-links.js'
24
+ import { parseNumericPrefix } from '../utils/numeric-prefix.js'
22
25
  import { renderEntityDocument } from './backfill.js'
23
26
  import { queriesYmlPath } from './queries-config.js'
24
27
  import { folderYmlPath } from '../site/records-config.js'
@@ -88,8 +91,9 @@ export function resolveSectionFile(dirPath, stableId) {
88
91
  let name = base.startsWith('@') ? base.slice(1) : base
89
92
  if (name.toLowerCase() === target) return join(dirPath, entry)
90
93
 
91
- const numMatch = name.match(/^\d+-(.+)$/)
92
- 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)
93
97
  }
94
98
  return null
95
99
  }
@@ -149,6 +153,15 @@ function assembleSection(frontmatter, body) {
149
153
  return ''
150
154
  }
151
155
 
156
+ // The document a body reads to, or null where it reads to none.
157
+ function readsTo(body) {
158
+ try {
159
+ return markdownToProseMirror(body)
160
+ } catch {
161
+ return null
162
+ }
163
+ }
164
+
152
165
  /**
153
166
  * Write a section's `.md` file as the backend holds the section: its `params` and its
154
167
  * data `declaration` replace the file's, `content` (ProseMirror) becomes the markdown
@@ -173,7 +186,7 @@ function assembleSection(frontmatter, body) {
173
186
  * value equal to it is not written into an existing file that leaves the key out
174
187
  * @returns {'updated'|'unchanged'}
175
188
  */
176
- export function writeSectionFile({ filePath, content, params, declaration, reserved = DEFAULT_RESERVED_FRONTMATTER, implied = null }) {
189
+ export function writeSectionFile({ filePath, content, params, declaration, reserved = DEFAULT_RESERVED_FRONTMATTER, implied = null, fileLinks = null }) {
177
190
  let existing = ''
178
191
  try {
179
192
  existing = readFileSync(filePath, 'utf8')
@@ -219,9 +232,14 @@ export function writeSectionFile({ filePath, content, params, declaration, reser
219
232
  // Compared as a push reads it: the body as stored (`content-collector.js::processMarkdownFile`).
220
233
  // ⛔ Until 2026-10-08 the trimmed copy was compared, so a body whose last line ended in a space never
221
234
  // matched what a push had sent from it, and every pull rewrote it — trailing blank lines and all.
222
- const keepsBody = !content || sameMarkdownDocument(existingBody || '', content)
235
+ // ⭐ Its links as the push reads them, and back (`fileLinks`, `site/file-links.js::fileLinksIn`): a link
236
+ // the file writes as a file is the page link the backend holds for it, and stays as the file wrote it.
237
+ const links = fileLinks && existingBody ? fileLinksIn(filePath, fileLinks, readsTo(existingBody)) : null
238
+ const keepsBody = !content || sameMarkdownDocument(existingBody || '', content, { resolve: links?.resolve })
223
239
  if (existing && keepsBody && canonicalJson(nextFrontmatter) === canonicalJson(frontmatter)) return 'unchanged'
224
- const body = keepsBody ? authoredBody : proseMirrorToMarkdown(content)
240
+ // ⭐ A changed body is written block by block: what the change left keeps the author's text, and only
241
+ // the blocks it changed take the writer's form (`body-splice.js`) — whole only when that cannot be said.
242
+ const body = keepsBody ? authoredBody : (spliceBody(existingBody || '', content, { links }) ?? proseMirrorToMarkdown(links ? links.restore(content) : content))
225
243
  return writeIfChanged(filePath, assembleSection(nextFrontmatter, body))
226
244
  }
227
245
 
@@ -286,6 +304,15 @@ function writeYamlIfChanged(filePath, value, prior) {
286
304
 
287
305
  const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
288
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
+
289
316
  /**
290
317
  * Merge `config` into `site.yml` (shallow). Preserves keys not present in the
291
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'
@@ -17,15 +17,18 @@ export const canonicalJson = (value) =>
17
17
  )
18
18
 
19
19
  /**
20
- * Does this markdown parse to `doc`, the way a push parses it?
20
+ * Does this markdown parse to `doc`, the way a push parses it? `resolve` reads it on, as the push does
21
+ * after parsing — a link written as a file, as the page link it sends (`site/file-links.js::fileLinksIn`).
21
22
  *
22
23
  * @param {string} markdown - an author's markdown body
23
24
  * @param {object} doc - a ProseMirror document
25
+ * @param {{ resolve?: (doc: object) => object }} [opts]
24
26
  * @returns {boolean}
25
27
  */
26
- export function sameMarkdownDocument(markdown, doc) {
28
+ export function sameMarkdownDocument(markdown, doc, { resolve = null } = {}) {
27
29
  try {
28
- return canonicalJson(withoutDefaults(markdownToProseMirror(markdown))) === canonicalJson(withoutDefaults(doc))
30
+ const read = markdownToProseMirror(markdown)
31
+ return canonicalJson(withoutDefaults(resolve ? resolve(read) : read)) === canonicalJson(withoutDefaults(doc))
29
32
  } catch {
30
33
  return false
31
34
  }
@@ -34,7 +37,7 @@ export function sameMarkdownDocument(markdown, doc) {
34
37
  // A document without the attributes that only restate a default: an inset's `embedKind: 'visual'`,
35
38
  // which the parser writes and the pull's re-inlining (retired 2026-09-28) left out — so a body holding
36
39
  // an inset never compared as unchanged (measured 2026-09-26 on the `marketing` template's hero).
37
- function withoutDefaults(doc) {
40
+ export function withoutDefaults(doc) {
38
41
  return JSON.parse(JSON.stringify(doc), (_, v) => {
39
42
  if (v?.type !== 'inset_ref' || v.attrs?.embedKind !== 'visual') return v
40
43
  const { embedKind: _visual, ...attrs } = v.attrs
@@ -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
  }