@uniweb/build 1.13.10 → 1.14.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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uniweb/build",
3
- "version": "1.13.10",
3
+ "version": "1.14.0",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -57,14 +57,14 @@
57
57
  "sharp": "^0.35.5",
58
58
  "yaml": "^2.5.0",
59
59
  "@uniweb/content-reader": "~1.5.8",
60
- "@uniweb/content-writer": "~1.3.1",
61
- "@uniweb/projections": "~1.2.9",
62
- "@uniweb/semantic-parser": "~1.13.1",
60
+ "@uniweb/projections": "~1.2.10",
61
+ "@uniweb/schemas": "~1.6.7",
63
62
  "@uniweb/theming": "~1.2.1",
64
- "@uniweb/schemas": "~1.6.7"
63
+ "@uniweb/semantic-parser": "~1.13.2",
64
+ "@uniweb/content-writer": "~1.3.1"
65
65
  },
66
66
  "optionalDependencies": {
67
- "@uniweb/runtime": "~1.3.6"
67
+ "@uniweb/runtime": "~1.3.9"
68
68
  },
69
69
  "peerDependencies": {
70
70
  "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -73,8 +73,8 @@
73
73
  "@tailwindcss/vite": "^4.0.0",
74
74
  "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
75
75
  "vite-plugin-svgr": "^4.0.0",
76
- "@uniweb/runtime": "~1.3.6",
77
- "@uniweb/core": "~1.5.2"
76
+ "@uniweb/core": "~1.6.0",
77
+ "@uniweb/runtime": "~1.3.9"
78
78
  },
79
79
  "peerDependenciesMeta": {
80
80
  "vite": {
@@ -19,12 +19,14 @@
19
19
  * is missing classes would be false. With a kit from before that, the loss is real: its stylesheet
20
20
  * names nothing, so the line is still reported.
21
21
  *
22
+ * A folder no `@source` names is the same loss from the other side: see `unreadFolders`.
23
+ *
22
24
  * @module @uniweb/build/foundation/stale-sources
23
25
  */
24
26
 
25
- import { existsSync, readFileSync, realpathSync } from 'node:fs'
27
+ import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs'
26
28
  import { createRequire } from 'node:module'
27
- import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
29
+ import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
28
30
 
29
31
  // `@source not "…"` excludes a path and `@source inline("…")` names no path: neither has a quote
30
32
  // right after the keyword.
@@ -116,6 +118,117 @@ function foundAbove(dir, missing) {
116
118
  }
117
119
  }
118
120
 
121
+ // `@source not "…"` is the author's decision about that path, which is all `unreadFolders` asks.
122
+ const NOT_SOURCE = /@source\s+not\s+(["'])(.+?)\1/g
123
+
124
+ const USES_TAILWIND = /@import\s+["']tailwindcss/
125
+
126
+ // `source(…)` on the import sets Tailwind's root: "./" reads the foundation in every build, `none`
127
+ // in no build. Either way a site build and the foundation's own agree.
128
+ const SETS_ITS_ROOT = /@import\s+["']tailwindcss[^"']*["'][^;]*\bsource\(/
129
+
130
+ // ⚖️ A class written here, not one passed along (`className={className}`), nor a param declared
131
+ // with that name (`className: { type: 'string' }`).
132
+ const WRITES_CLASSES = /\bclassName\s*(?:=\s*\{[^}]*["'`]|[=:]\s*["'`])|\bcn\(|\bclass=["']/
133
+
134
+ const NOT_THE_FOUNDATIONS_CODE = new Set(['node_modules', 'dist', 'public', 'test', 'tests', '__tests__'])
135
+
136
+ function codeFiles(dir, found = []) {
137
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
138
+ if (entry.name.startsWith('.') || NOT_THE_FOUNDATIONS_CODE.has(entry.name)) continue
139
+ const path = join(dir, entry.name)
140
+ if (entry.isDirectory()) codeFiles(path, found)
141
+ else if (/\.[jt]sx?$/.test(entry.name) && !/\.(?:test|spec|generated)\./.test(entry.name)) found.push(path)
142
+ }
143
+ return found
144
+ }
145
+
146
+ /** The paths a stylesheet's `@source` lines start from, and those of the stylesheets it imports. */
147
+ function pathsRead(file, seen = new Set()) {
148
+ if (seen.has(file)) return []
149
+ seen.add(file)
150
+ let css
151
+ try {
152
+ css = withoutComments(readFileSync(file, 'utf8'))
153
+ } catch {
154
+ return []
155
+ }
156
+ const read = [...css.matchAll(SOURCE), ...css.matchAll(NOT_SOURCE)].map((m) => resolve(dirname(file), fixedPrefix(m[2])))
157
+ const require = createRequire(file)
158
+ for (const [, , specifier] of css.matchAll(IMPORT)) {
159
+ // ⛔ Only a `.css` specifier, as in `readByAnImport`.
160
+ if (!specifier.endsWith('.css')) continue
161
+ let imported
162
+ try {
163
+ imported = require.resolve(specifier)
164
+ } catch {
165
+ continue
166
+ }
167
+ read.push(...pathsRead(imported, seen))
168
+ }
169
+ return read
170
+ }
171
+
172
+ /**
173
+ * The code in a foundation that writes classes no `@source` reads.
174
+ *
175
+ * Tailwind reads everything under Vite's root, and whatever `@source` names. A foundation's own build
176
+ * has the foundation for its root, so it finds every class. A site build and `uniweb dev` have the
177
+ * site: there, `@source` is all that reaches the foundation. So a class only such code uses is in the
178
+ * foundation's CSS and missing from the site's, with both builds exiting 0, and a page on a host
179
+ * loading the foundation's own CSS looks right. Measured 2026-11-01 on the `dynamic` template, whose
180
+ * stylesheet named `./sections` alone: its home page's weather card came out a blank white box, 27
181
+ * classes short, under `uniweb dev` and in a site build.
182
+ *
183
+ * ⚖️ It errs toward saying nothing. Any `@source` starting at or above a file reads that file, whatever
184
+ * its glob, and a foundation that doesn't import Tailwind by name is not looked at. A word here is a
185
+ * line to add, whose only cost is a stylesheet naming one more folder.
186
+ *
187
+ * @param {string} stylesPath - the foundation's stylesheet; none there, nothing to say
188
+ * @returns {Array<{ path: string, files: number, line: string }>} each folder (or file) beside the
189
+ * stylesheet, how many of its files write classes, and the line that reads it
190
+ */
191
+ export function unreadFolders(stylesPath) {
192
+ // ⛔ The real path: an import resolves to one, so a line it holds would never match a file reached
193
+ // through a link (a macOS temp folder, a workspace dependency).
194
+ let stylesheet, css
195
+ try {
196
+ stylesheet = realpathSync(stylesPath)
197
+ css = withoutComments(readFileSync(stylesheet, 'utf8'))
198
+ } catch {
199
+ return []
200
+ }
201
+ if (!USES_TAILWIND.test(css) || SETS_ITS_ROOT.test(css)) return []
202
+
203
+ const dir = dirname(stylesheet)
204
+ const read = pathsRead(stylesheet)
205
+ const unread = new Map()
206
+ for (const file of codeFiles(dir)) {
207
+ if (read.some((path) => file === path || file.startsWith(path + sep))) continue
208
+ if (!WRITES_CLASSES.test(withoutComments(readFileSync(file, 'utf8')))) continue
209
+ const [top, ...below] = relative(dir, file).split(sep)
210
+ const entry = unread.get(top) ?? { path: top, files: 0, isFolder: below.length > 0, typed: false }
211
+ entry.files++
212
+ entry.typed ||= /\.tsx?$/.test(file)
213
+ unread.set(top, entry)
214
+ }
215
+ return [...unread.values()]
216
+ .sort((a, b) => a.path.localeCompare(b.path))
217
+ .map(({ path, files, isFolder, typed }) => ({
218
+ path,
219
+ files,
220
+ line: `@source "./${path}${isFolder ? `/**/*.{js,jsx${typed ? ',ts,tsx' : ''}}` : ''}";`
221
+ }))
222
+ }
223
+
224
+ /** What a site build and `uniweb dev` print when `unreadFolders` finds any: it is them that lose the classes. */
225
+ export function unreadFoldersWarning(unread) {
226
+ return [
227
+ "[uniweb] The foundation's styles.css names no @source for code that writes classes, so a site build and `uniweb dev` miss any class only that code uses, though the foundation's own build has it. Add:",
228
+ ...unread.map(({ line }) => ` ${line}`)
229
+ ].join('\n')
230
+ }
231
+
119
232
  /** A stale line's note: what is missing, and where it is instead when that is known. */
120
233
  export const staleSourceNote = ({ missing, foundAt }) => `no ${missing}${foundAt ? `; it is at ${foundAt}` : ''}`
121
234
 
package/src/index.js CHANGED
@@ -85,7 +85,7 @@ export {
85
85
 
86
86
  // Foundation source root resolution (reads package.json::main)
87
87
  export { resolveFoundationSrcDir, resolveFoundationSrcPath } from './utils/foundation-source-root.js'
88
- export { staleSources, staleSourceNote } from './foundation/stale-sources.js'
88
+ export { staleSources, staleSourceNote, unreadFolders } from './foundation/stale-sources.js'
89
89
 
90
90
  // Package classification (foundation vs site vs standalone schemas package)
91
91
  export { classifyPackage, isExtensionPackage, isSchemasPackage } from './utils/classify-package.js'
package/src/prerender.js CHANGED
@@ -888,6 +888,9 @@ export async function prerenderSite(siteDir, options = {}) {
888
888
  const sitemapEntries = []
889
889
  // A redirect stub names its target as the target's own pages do: absolutely, on the site's address.
890
890
  const stubCanonical = (target) => absoluteUrl(defaultSiteContent.config?.url, target) || target
891
+ // With no icon named, a browser asks for `/favicon.ico` on its way through a stub, and logs a 404
892
+ // on any site whose icon is called something else. A stub is gone at once, so it names none.
893
+ const STUB_ICON = '<link rel="icon" href="data:,">'
891
894
 
892
895
  for (const localeConfig of localeConfigs) {
893
896
  const { locale, contentPath: localeContentPath, htmlPath, isDefault, routePrefix } = localeConfig
@@ -1042,7 +1045,7 @@ export async function prerenderSite(siteDir, options = {}) {
1042
1045
  ? (website.basePath || '') + location
1043
1046
  : location
1044
1047
  onProgress(` Redirect ${outputRoute} → ${target}`)
1045
- const redirectHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${target}"><link rel="canonical" href="${stubCanonical(target)}"><title>Redirecting...</title></head><body><p>Redirecting to <a href="${target}">${target}</a></p></body></html>`
1048
+ const redirectHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${target}"><link rel="canonical" href="${stubCanonical(target)}">${STUB_ICON}<title>Redirecting...</title></head><body><p>Redirecting to <a href="${target}">${target}</a></p></body></html>`
1046
1049
  const outputPath = getOutputPath(distDir, outputRoute)
1047
1050
  await mkdir(dirname(outputPath), { recursive: true })
1048
1051
  await writeFile(outputPath, redirectHtml)
@@ -1075,7 +1078,7 @@ export async function prerenderSite(siteDir, options = {}) {
1075
1078
  routePrefix
1076
1079
  })
1077
1080
  onProgress(` Auto-redirect ${outputRoute} → ${targetPath}`)
1078
- const redirectHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${targetPath}"><link rel="canonical" href="${stubCanonical(targetPath)}"><title>Redirecting...</title></head><body><p>Redirecting to <a href="${targetPath}">${targetPath}</a></p></body></html>`
1081
+ const redirectHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${targetPath}"><link rel="canonical" href="${stubCanonical(targetPath)}">${STUB_ICON}<title>Redirecting...</title></head><body><p>Redirecting to <a href="${targetPath}">${targetPath}</a></p></body></html>`
1079
1082
  const outputPath = getOutputPath(distDir, outputRoute)
1080
1083
  await mkdir(dirname(outputPath), { recursive: true })
1081
1084
  await writeFile(outputPath, redirectHtml)
@@ -0,0 +1,385 @@
1
+ /**
2
+ * Freezing a site's docs as a version: `uniweb add version v2`.
3
+ *
4
+ * The docs stay where they are, at their URLs. A copy goes into a folder named `v2` beside them, and
5
+ * from then on it is an ordinary folder of pages at its own URL (`@uniweb/projections/versions`).
6
+ * What makes this more than `cp -R` is what a copy gets wrong:
7
+ *
8
+ * - **Page ids.** An id is unique across a site, and it's how a `page:` link finds its page, so a
9
+ * copy that keeps them makes every such link an accident of page order. A frozen copy never moves,
10
+ * which is what an id is for, so it gets none. The app mints its own for a page it receives.
11
+ * - **Links.** A link into the pages being copied must lead to the copy, or an old version's pages
12
+ * send a reader to the latest with nothing to say so. Each becomes a path into the copy. A relative
13
+ * link inside the copy already works, and one that leaves it needs one more `../`.
14
+ * - **Search engines.** An older version is kept out of them, so a search sends people to the latest.
15
+ *
16
+ * ⛔ Text, not a parse. These are an author's files, and a parse and a print would drop their
17
+ * comments and reflow them. A code sample that reads `[a](page:b)` is words about a link, as it is to
18
+ * the sync (`uwx/page-refs.js`); a tagged data block (`yaml:nav`) is content, and its links count.
19
+ *
20
+ * Nothing is written until the whole copy is planned, so a refusal leaves no trace.
21
+ */
22
+
23
+ import { existsSync, statSync } from 'node:fs'
24
+ import { copyFile, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
25
+ import { dirname, join, posix, resolve, relative } from 'node:path'
26
+ import yaml from 'js-yaml'
27
+ import { isVersionFolder } from '@uniweb/projections/versions'
28
+ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
29
+ import { collectSiteContent, mountEntriesOf, readFolderConfig, readYamlFile, rootOrderConfig } from './content-collector.js'
30
+
31
+ const routeKey = (route) => String(route).replace(/^\/+/, '').replace(/\/+$/, '')
32
+ const CONFIG_FILES = new Set(['page.yml', 'folder.yml'])
33
+ // What of the docs folder's own config still describes the copy. The rest names the folder itself.
34
+ const CARRIED_KEYS = ['pages', 'sections', 'nest', 'redirect']
35
+
36
+ /**
37
+ * The folder holding the docs, as a path under `pages/`.
38
+ *
39
+ * Named, or the one that already holds versions, or `docs`. Refused rather than guessed otherwise.
40
+ */
41
+ function findFolder(named, { pages, pagesDir, mounts, homepage }) {
42
+ if (named !== undefined && named !== null) {
43
+ const clean = routeKey(String(named).replace(/^\.\/?/, '').replace(/^pages(\/|$)/, ''))
44
+ if (clean.split('/').some(isVersionFolder)) {
45
+ throw new Error(`"${named}" is a version. Name the folder that holds the versions.`)
46
+ }
47
+ return clean
48
+ }
49
+
50
+ const holding = new Set()
51
+ for (const { route } of pages) {
52
+ const segments = route.split('/').filter(Boolean)
53
+ const at = segments.findIndex(isVersionFolder)
54
+ if (at === -1) continue
55
+ const above = segments.slice(0, at).join('/')
56
+ holding.add(!above && homepage && existsSync(join(pagesDir, homepage, segments[0])) ? homepage : above)
57
+ }
58
+ if (holding.size === 1) return [...holding][0]
59
+ if (holding.size > 1) {
60
+ throw new Error(
61
+ `More than one folder holds versions: ${[...holding].map((f) => f || '.').join(', ')}. Say which with --in <folder>.`
62
+ )
63
+ }
64
+ if (mounts.has('docs') || existsSync(join(pagesDir, 'docs'))) return 'docs'
65
+ throw new Error('Say which folder holds the docs with --in <folder>, or --in . for the whole site.')
66
+ }
67
+
68
+ /** One link's new address, or null if it leads nowhere the copy changes. */
69
+ function linkRewriter({ routes, ids }) {
70
+ const count = { links: 0 }
71
+ const rewrite = (dest) => {
72
+ const cut = dest.search(/[#?]/)
73
+ const [path, tail] = cut === -1 ? [dest, ''] : [dest.slice(0, cut), dest.slice(cut)]
74
+ if (path.startsWith('page:')) {
75
+ const name = path.slice('page:'.length)
76
+ const to = ids.get(name) ?? routes.get(routeKey(name))
77
+ if (to === undefined) return null
78
+ count.links++
79
+ return `page:${routeKey(to)}${tail}`
80
+ }
81
+ if (path.startsWith('/')) {
82
+ const to = routes.get(routeKey(path))
83
+ if (to === undefined) return null
84
+ count.links++
85
+ return `${to}${tail}`
86
+ }
87
+ return null
88
+ }
89
+ return { rewrite, count }
90
+ }
91
+
92
+ /** A relative link that leaves the copied tree, or enters another version, is one level further now. */
93
+ function deeperLink(dest, fileDir) {
94
+ if (!/^\.\.?\//.test(dest)) return null
95
+ const target = posix.normalize(posix.join(fileDir, dest))
96
+ const first = target.split('/')[0]
97
+ return first === '..' || isVersionFolder(first) ? `../${dest}` : null
98
+ }
99
+
100
+ /** One line's links, outside its code spans. */
101
+ function rewriteInline(line, { rewrite, count }, fileDir) {
102
+ const replaceLinks = (text) =>
103
+ text.replace(/(\]\(\s*<?)([^)\s>]+)/g, (whole, open, dest) => {
104
+ const next = rewrite(dest) ?? deeperLink(dest, fileDir)
105
+ if (next === null) return whole
106
+ if (!dest.startsWith('page:') && !dest.startsWith('/')) count.links++
107
+ return `${open}${next}`
108
+ })
109
+
110
+ let out = ''
111
+ let at = 0
112
+ while (at < line.length) {
113
+ const tick = line.indexOf('`', at)
114
+ if (tick === -1) break
115
+ let run = tick
116
+ while (line[run] === '`') run++
117
+ const fence = line.slice(tick, run)
118
+ let close = line.indexOf(fence, run)
119
+ while (close !== -1 && (line[close - 1] === '`' || line[close + fence.length] === '`')) {
120
+ close = line.indexOf(fence, close + 1)
121
+ }
122
+ out += replaceLinks(line.slice(at, tick))
123
+ if (close === -1) {
124
+ out += fence
125
+ at = run
126
+ } else {
127
+ out += line.slice(tick, close + fence.length)
128
+ at = close + fence.length
129
+ }
130
+ }
131
+ return out + replaceLinks(line.slice(at))
132
+ }
133
+
134
+ /** A line of YAML whose whole value is an address: `link: page:guide`, `- /docs/guide`. */
135
+ function rewriteYamlLine(line, { rewrite }) {
136
+ const match = line.match(/^(\s*(?:-\s+)?(?:[\w.-]+:\s+)?)(['"]?)((?:page:|\/)[^'"\s]*)\2(\s*(?:#.*)?)$/)
137
+ if (!match) return line
138
+ const [, lead, quote, dest, rest] = match
139
+ const next = rewrite(dest)
140
+ return next === null ? line : `${lead}${quote}${next}${quote}${rest}`
141
+ }
142
+
143
+ /** JSON strings that are an address. */
144
+ function rewriteJsonLine(line, { rewrite }) {
145
+ return line.replace(/"((?:page:|\/)[^"\s]*)"/g, (whole, dest) => {
146
+ const next = rewrite(dest)
147
+ return next === null ? whole : `"${next}"`
148
+ })
149
+ }
150
+
151
+ /** A markdown file: its frontmatter's addresses, and its links outside of code. */
152
+ function rewriteMarkdown(text, links, fileDir) {
153
+ const lines = text.split('\n')
154
+ let i = 0
155
+ if (lines[0]?.trim() === '---') {
156
+ for (i = 1; i < lines.length && lines[i].trim() !== '---'; i++) lines[i] = rewriteYamlLine(lines[i], links)
157
+ i++
158
+ }
159
+ let fence = null
160
+ for (; i < lines.length; i++) {
161
+ const opens = lines[i].match(/^ {0,3}(`{3,}|~{3,})\s*([^\s`]*)/)
162
+ if (fence) {
163
+ const closes = opens && opens[1][0] === fence.mark[0] && opens[1].length >= fence.mark.length && !opens[2]
164
+ if (closes) fence = null
165
+ else if (fence.kind === 'yaml') lines[i] = rewriteYamlLine(lines[i], links)
166
+ else if (fence.kind === 'json') lines[i] = rewriteJsonLine(lines[i], links)
167
+ else if (fence.kind === 'md') lines[i] = rewriteInline(lines[i], links, fileDir)
168
+ } else if (opens) {
169
+ // A tagged block holds content; any other fence holds a sample, and is left as written.
170
+ const tagged = opens[2].match(/^(yaml|yml|json|md):/)
171
+ fence = { mark: opens[1], kind: tagged ? tagged[1].replace('yml', 'yaml') : null }
172
+ } else {
173
+ lines[i] = rewriteInline(lines[i], links, fileDir)
174
+ }
175
+ }
176
+ return lines.join('\n')
177
+ }
178
+
179
+ /** A page's config: no id, and its addresses into the copy. */
180
+ function rewriteConfig(text, links) {
181
+ const lines = text.split('\n').filter((line) => !/^id\s*:/.test(line))
182
+ return lines.map((line) => rewriteYamlLine(line, links)).join('\n')
183
+ }
184
+
185
+ /** `seo: { noindex: true }` added to a page's config, for a page a folder's can't speak for. */
186
+ function withNoindex(text) {
187
+ const parsed = yaml.load(text, YAML_OPTIONS) || {}
188
+ if (parsed.seo?.noindex === true) return text
189
+ if (/^seo\s*:\s*$/m.test(text)) return text.replace(/^seo\s*:\s*$/m, 'seo:\n noindex: true')
190
+ if (parsed.seo) return yaml.dump({ ...parsed, seo: { ...parsed.seo, noindex: true } })
191
+ return `${text.replace(/\n*$/, '\n')}seo:\n noindex: true\n`
192
+ }
193
+
194
+ /** Every file below a folder, as paths relative to it. The folder's own versions stay out. */
195
+ async function filesBelow(dir, { top = false, base = '' } = {}) {
196
+ const files = []
197
+ for (const entry of await readdir(dir, { withFileTypes: true })) {
198
+ if (entry.name.startsWith('.') || entry.name === 'node_modules') continue
199
+ const rel = base ? `${base}/${entry.name}` : entry.name
200
+ const isDirectory = entry.isDirectory() || (entry.isSymbolicLink() && statSync(join(dir, entry.name)).isDirectory())
201
+ if (isDirectory) {
202
+ if (top && isVersionFolder(entry.name)) continue
203
+ files.push(...(await filesBelow(join(dir, entry.name), { base: rel })))
204
+ } else if (!(top && CONFIG_FILES.has(entry.name))) {
205
+ files.push(rel)
206
+ }
207
+ }
208
+ return files
209
+ }
210
+
211
+ /**
212
+ * Freeze the docs in a folder as a version beside them.
213
+ *
214
+ * @param {string} siteRoot
215
+ * @param {Object} options
216
+ * @param {string} options.name - the version's folder name: `v2`, `v2.1`
217
+ * @param {string} [options.folder] - the folder holding the docs, under `pages/`; `.` for all of it
218
+ * @param {string} [options.label] - what a version switcher calls it (default: the name)
219
+ * @param {boolean} [options.keepInSearch=false] - leave it open to search engines
220
+ * @param {boolean} [options.dryRun=false] - say what would happen, and write nothing
221
+ * @returns {Promise<Object>} what it did: `{ name, folder, path, route, url, pages, files, ids, links, notes }`
222
+ */
223
+ export async function addVersion(siteRoot, { name, folder: named, label, keepInSearch = false, dryRun = false } = {}) {
224
+ if (!isVersionFolder(name)) {
225
+ const bare = /^\d/.test(String(name)) ? ` Did you mean v${name}?` : ''
226
+ throw new Error(`"${name}" isn't a version's name. It's a "v" and a number: v2, v2.1.${bare}`)
227
+ }
228
+
229
+ const site = await readYamlFile(join(siteRoot, 'site.yml'))
230
+ const pagesDir = resolve(siteRoot, site.paths?.pages ?? 'pages')
231
+ const mounts = new Map(mountEntriesOf(site.paths).map(([key, value]) => [key, resolve(siteRoot, value)]))
232
+ const { config: rootConfig } = await readFolderConfig(pagesDir, 'sections')
233
+ const homepage = rootOrderConfig(site, rootConfig).homepage
234
+ const { pages } = await collectSiteContent(siteRoot)
235
+
236
+ const folder = findFolder(named, { pages, pagesDir, mounts, homepage })
237
+ const segments = folder ? folder.split('/') : []
238
+ const dir = mounts.has(segments[0])
239
+ ? join(mounts.get(segments[0]), ...segments.slice(1))
240
+ : join(pagesDir, ...segments)
241
+ if (!existsSync(dir) || !statSync(dir).isDirectory()) {
242
+ throw new Error(`There's no folder pages/${folder}.`)
243
+ }
244
+ const target = join(dir, name)
245
+ if (existsSync(target)) {
246
+ throw new Error(`pages/${posix.join(folder, name)} already exists. To freeze the docs again, name a new version.`)
247
+ }
248
+
249
+ // Where the folder's pages are. A folder promoted to the homepage puts its pages at the root.
250
+ const isHomepage = segments[0] === homepage
251
+ const scope = `/${(isHomepage ? segments.slice(1) : segments).join('/')}`
252
+ const prefix = scope === '/' ? '' : scope
253
+ const versionRoute = `${prefix}/${name}`
254
+ const names = new Set(
255
+ (await readdir(dir, { withFileTypes: true }))
256
+ .filter((entry) => entry.isDirectory() || entry.name.endsWith('.md'))
257
+ .map((entry) => entry.name.replace(/^\d+(\.\d+)*-/, '').replace(/\.md$/, ''))
258
+ .filter((entry) => !isVersionFolder(entry) && !(folder === '' && entry === '404'))
259
+ )
260
+
261
+ // Every page being copied: where it is, and where its copy will be.
262
+ const copied = []
263
+ const routes = new Map()
264
+ const ids = new Map()
265
+ for (const page of pages) {
266
+ const from = page.sourcePath || page.route
267
+ let rest
268
+ if (scope === '/') rest = from === '/' || (isHomepage && from === `/${homepage}`) ? '' : from
269
+ else if (from === scope) rest = ''
270
+ else if (from.startsWith(`${scope}/`)) rest = from.slice(scope.length)
271
+ else continue
272
+ const first = rest.split('/').filter(Boolean)[0]
273
+ if (first && !names.has(first)) {
274
+ // A homepage's own pages sit at the root, and in the copy under its folder, like any other's.
275
+ if (scope !== '/' || !names.has(homepage)) continue
276
+ rest = `/${homepage}${rest}`
277
+ }
278
+ if (!first && page.route !== scope && !(isHomepage && from === `/${homepage}`)) continue
279
+ const to = `${versionRoute}${rest}`
280
+ copied.push({ page, to })
281
+ routes.set(routeKey(page.route), to)
282
+ routes.set(routeKey(from), to)
283
+ if (page.id !== null && page.id !== undefined && page.id !== '') ids.set(String(page.id), to)
284
+ }
285
+
286
+ const links = linkRewriter({ routes, ids })
287
+ const { config: ownConfig, mode } = await readFolderConfig(dir, 'sections')
288
+ const files = await filesBelow(dir, { top: true })
289
+ const hasOwnContent = mode !== 'pages' && files.some((file) => !file.includes('/') && file.endsWith('.md'))
290
+
291
+ // The copy, planned in full: text for what changes, a source for what doesn't.
292
+ const plan = []
293
+ let idsDropped = 0
294
+ for (const file of files) {
295
+ const from = join(dir, file)
296
+ const to = join(target, file)
297
+ const base = posix.basename(file)
298
+ if (CONFIG_FILES.has(base)) {
299
+ const original = await readFile(from, 'utf8')
300
+ if (/^id\s*:/m.test(original)) idsDropped++
301
+ let text = rewriteConfig(original, links)
302
+ // A folder with content speaks only for itself, so here each page has to say it.
303
+ if (hasOwnContent && !keepInSearch && base === 'page.yml') text = withNoindex(text)
304
+ plan.push({ to, text })
305
+ } else if (base.endsWith('.md')) {
306
+ plan.push({ to, text: rewriteMarkdown(await readFile(from, 'utf8'), links, posix.dirname(file)) })
307
+ } else {
308
+ plan.push({ to, from })
309
+ }
310
+ }
311
+
312
+ // The version's own page: what a switcher calls it, and how far search engines go.
313
+ const own = { title: label || name }
314
+ if (!keepInSearch) own.seo = { noindex: true }
315
+ for (const key of CARRIED_KEYS) {
316
+ if (ownConfig[key] === undefined) continue
317
+ own[key] =
318
+ key === 'pages' && Array.isArray(ownConfig.pages)
319
+ ? ownConfig.pages.filter((entry) => !isVersionFolder(entry))
320
+ : ownConfig[key]
321
+ }
322
+ if (typeof own.redirect === 'string') own.redirect = links.rewrite(own.redirect) ?? own.redirect
323
+ if (Array.isArray(own.pages) && !own.pages.length) delete own.pages
324
+ plan.push({ to: join(target, mode === 'pages' ? 'folder.yml' : 'page.yml'), text: yaml.dump(own, { lineWidth: -1 }) })
325
+
326
+ // Translations written by hand are kept by route or by id, and the copy has only a route.
327
+ const notes = []
328
+ const freeformRoot = join(resolve(siteRoot, site.paths?.locales ?? 'locales'), 'freeform')
329
+ if (existsSync(freeformRoot)) {
330
+ for (const locale of await readdir(freeformRoot, { withFileTypes: true })) {
331
+ if (!locale.isDirectory()) continue
332
+ const root = join(freeformRoot, locale.name)
333
+ for (const { page, to } of copied) {
334
+ const sources = [
335
+ page.id ? join(root, 'page-ids', String(page.id)) : null,
336
+ join(root, 'pages', routeKey(page.route)),
337
+ ].filter((source) => source && existsSync(source))
338
+ const seen = new Set()
339
+ for (const source of sources) {
340
+ for (const entry of await readdir(source, { withFileTypes: true })) {
341
+ if (!entry.isFile() || !entry.name.endsWith('.md') || seen.has(entry.name)) continue
342
+ seen.add(entry.name)
343
+ const text = rewriteMarkdown(await readFile(join(source, entry.name), 'utf8'), links, '.')
344
+ plan.push({ to: join(root, 'pages', routeKey(to), entry.name), text })
345
+ }
346
+ }
347
+ }
348
+ }
349
+ }
350
+
351
+ if (mounts.has(segments[0])) {
352
+ notes.push(`pages/${segments[0]} is mounted from ${relative(siteRoot, mounts.get(segments[0]))}, so the copy went there.`)
353
+ }
354
+ if (hasOwnContent && !keepInSearch) {
355
+ notes.push(
356
+ `pages/${folder} has content of its own, so its noindex can't speak for the pages below it. Each copied page.yml says it, and a page added to this version later needs to as well.`
357
+ )
358
+ }
359
+
360
+ if (!dryRun) {
361
+ try {
362
+ for (const { to, text, from } of plan) {
363
+ await mkdir(dirname(to), { recursive: true })
364
+ if (from) await copyFile(from, to)
365
+ else await writeFile(to, text)
366
+ }
367
+ } catch (err) {
368
+ await rm(target, { recursive: true, force: true })
369
+ throw err
370
+ }
371
+ }
372
+
373
+ return {
374
+ name,
375
+ folder,
376
+ path: relative(siteRoot, target),
377
+ route: versionRoute,
378
+ pages: copied.filter(({ page }) => page.hasContent !== false).length,
379
+ files: plan.length,
380
+ ids: idsDropped,
381
+ links: links.count.links,
382
+ keptOutOfSearch: !keepInSearch,
383
+ notes,
384
+ }
385
+ }
@@ -24,6 +24,7 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs'
24
24
  import { resolve, dirname, join } from 'node:path'
25
25
  import yaml from 'js-yaml'
26
26
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
27
+ import { unreadFolders, unreadFoldersWarning } from '../foundation/stale-sources.js'
27
28
  import {
28
29
  generateEntryPoint,
29
30
  shouldRegenerateForFile,
@@ -286,6 +287,11 @@ export async function defineSiteConfig(options = {}) {
286
287
  siteRoot,
287
288
  })
288
289
  if (!agreement.ok) console.warn(`\n${agreement.message}\n`)
290
+
291
+ // Code the foundation's stylesheet names no `@source` for: here is where its classes go
292
+ // missing, in a site build and under `uniweb dev`, while its own build has them all.
293
+ const unread = unreadFolders(join(srcDir, 'styles.css'))
294
+ if (unread.length) console.warn(unreadFoldersWarning(unread))
289
295
  }
290
296
  },
291
297