@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/package.json +4 -4
- package/src/content/index.js +3 -0
- package/src/site/add-version.js +44 -7
- package/src/site/content-collector.js +93 -69
- package/src/site/file-links.js +91 -26
- package/src/site/mount-entries.js +29 -0
- package/src/utils/numeric-prefix.js +7 -3
- package/src/uwx/body-splice.js +85 -0
- package/src/uwx/data-schema.js +4 -0
- package/src/uwx/emit-surface.json +0 -3
- package/src/uwx/held-units.js +94 -0
- package/src/uwx/index.js +5 -0
- package/src/uwx/page-files.js +255 -0
- package/src/uwx/project-writer.js +32 -5
- package/src/uwx/route-mode.js +18 -0
- package/src/uwx/same-content.js +7 -4
- package/src/uwx/site-diff.js +7 -2
- package/src/uwx/site-dirs.js +50 -6
- package/src/uwx/site-project.js +561 -60
- package/src/uwx/site.js +20 -12
- package/src/uwx/sync-package.js +36 -5
- package/src/uwx/git-authored.js +0 -85
|
@@ -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
|
+
}
|
package/src/uwx/data-schema.js
CHANGED
|
@@ -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.
|
|
@@ -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
|
-
|
|
92
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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'
|
package/src/uwx/same-content.js
CHANGED
|
@@ -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
|
-
|
|
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
|
package/src/uwx/site-diff.js
CHANGED
|
@@ -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
|
-
|
|
116
|
-
|
|
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
|
}
|