@uniweb/build 1.19.2 → 1.20.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.19.2",
3
+ "version": "1.20.0",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -57,10 +57,10 @@
57
57
  "sharp": "^0.35.5",
58
58
  "yaml": "^2.5.0",
59
59
  "@uniweb/content-reader": "~1.5.9",
60
- "@uniweb/schemas": "~1.6.11",
60
+ "@uniweb/schemas": "~1.7.0",
61
61
  "@uniweb/semantic-parser": "~1.13.2",
62
- "@uniweb/theming": "~1.3.2",
63
62
  "@uniweb/content-writer": "~1.3.1",
63
+ "@uniweb/theming": "~1.3.2",
64
64
  "@uniweb/projections": "~1.2.13"
65
65
  },
66
66
  "optionalDependencies": {
@@ -1,8 +1,10 @@
1
1
  /**
2
- * ⭐ A REGISTERED DATA SCHEMA IS USABLE BY ANY FOUNDATION OR SITE, by its full name — `@acme/member`.
3
- * Its scope is a namespace, so that names never collide, and says who may publish under it, never who
4
- * may use it *[Diego, 2026-09-25; 2026-11-08]*. A foundation that renders another's type declares it by
5
- * that name, and a register names it and sends no definition of it (`uwx/registry-package.js`).
2
+ * ⭐ A DATA SCHEMA IS USABLE BY ANY FOUNDATION OR SITE, by its full name — `@acme/member`: locally,
3
+ * through `schemas.config.js` or a shared `@acme/schemas` package, with no backend, and from a backend
4
+ * once it is registered, which is optional. Its scope is a namespace, so that names never collide, and
5
+ * says who may publish under it, never who may use it *[Diego, 2026-09-25; 2026-11-08]*. A foundation
6
+ * that renders another's type declares it by that name, and a register names it and sends no
7
+ * definition of it (`uwx/registry-package.js`).
6
8
  *
7
9
  * So a copy of a type's file in a second package of the same scope is a second definition of one type,
8
10
  * and the copies come apart the first time one is edited. `typesDefinedTwice` names each such type, for
@@ -11,13 +13,16 @@
11
13
  * changed definition does is the registry's to judge.
12
14
  */
13
15
 
14
- import { existsSync, readFileSync, realpathSync } from 'node:fs'
15
- import { join, resolve } from 'node:path'
16
+ import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
17
+ import { join, relative, resolve, isAbsolute, sep } from 'node:path'
16
18
  import { readFoundationName } from '../schema.js'
17
19
  import { splitFoundationName } from '../foundation-name.js'
18
20
  import { ownSchemaFiles, resolveSchemaRef } from '../resolve-data-schema.js'
19
21
  import { resolveFoundationSrcDir } from '../utils/foundation-source-root.js'
20
22
  import { canonicalJson } from '../uwx/same-content.js'
23
+ import { workspacePackages } from '../workspace-patterns.js'
24
+ import { workspaceRootOf } from '../site/workspace-extension.js'
25
+ import { classifyPackage, isSchemasPackage } from '../utils/classify-package.js'
21
26
 
22
27
  const real = (path) => {
23
28
  try {
@@ -109,3 +114,71 @@ export async function typesDefinedTwice(packages) {
109
114
  }
110
115
  return out
111
116
  }
117
+
118
+ // A package's scope, read again only when its `main.js` or `package.json` changes: reading a
119
+ // foundation's name loads its `main.js`, and a dev server asks for every type it resolves.
120
+ const scopeCache = new Map()
121
+
122
+ function changedAt(dir) {
123
+ let t = 0
124
+ for (const f of ['package.json', 'main.js', 'src/main.js']) {
125
+ try {
126
+ t = Math.max(t, statSync(join(dir, f)).mtimeMs)
127
+ } catch {
128
+ // absent
129
+ }
130
+ }
131
+ return t
132
+ }
133
+
134
+ async function cachedTypeScope(dir, kind) {
135
+ const at = changedAt(dir)
136
+ const hit = scopeCache.get(dir)
137
+ if (hit && hit.at === at && hit.kind === kind) return hit.scope
138
+ const scope = await packageTypeScope(dir, kind)
139
+ scopeCache.set(dir, { at, kind, scope })
140
+ return scope
141
+ }
142
+
143
+ const within = (dir, path) => {
144
+ const rel = relative(dir, path)
145
+ return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
146
+ }
147
+
148
+ /**
149
+ * ⭐ A TYPE ANOTHER PACKAGE OF THE WORKSPACE DEFINES, found with nothing configured. Foundations a
150
+ * team develops together share a type by its full name, `@acme/member`, and a local build reads it
151
+ * from the package that defines it: a foundation whose name gives the `@acme` scope and whose own
152
+ * `schemas/` holds `member`, or a schemas package of that scope. No `schemas.config.js`, no package to
153
+ * install, nothing registered: sharing a type never needs a backend *[Diego, 2026-11-08: "it should be
154
+ * easy and good DX to share schemas"]*.
155
+ *
156
+ * Only packages of one workspace share this way: `fromDir` must be in one of the workspace's
157
+ * packages, as pnpm reads its list (`../workspace-patterns.js`), so a copy kept outside the list, a
158
+ * backup folder say, is never read. Found by the same rule `typesDefinedTwice` names copies by.
159
+ *
160
+ * @param {string} ref - `@scope/name`
161
+ * @param {string} fromDir - the foundation (its source folder) or site asking
162
+ * @returns {Promise<string[]>} the files that define it, each once; the caller refuses more than one
163
+ */
164
+ export async function workspaceTypeFiles(ref, fromDir) {
165
+ const m = /^(@[^/]+)\/(.+)$/.exec(ref || '')
166
+ if (!m) return []
167
+ const [, scope, name] = m
168
+ const root = workspaceRootOf(fromDir)
169
+ if (!root) return []
170
+ const packages = workspacePackages(root).map((rel) => join(root, rel))
171
+ if (!packages.some((dir) => within(dir, resolve(fromDir)))) return []
172
+ const files = new Map()
173
+ for (const dir of packages) {
174
+ const kind = classifyPackage(dir) === 'foundation' ? 'foundation' : isSchemasPackage(dir) ? 'schemas' : null
175
+ if (!kind) continue
176
+ if ((await cachedTypeScope(dir, kind)) !== scope) continue
177
+ const typesAt = typeRoot(dir, kind)
178
+ if (!existsSync(join(typesAt, 'schemas'))) continue
179
+ for (const own of ownSchemaFiles(typesAt)) {
180
+ if (own.name === name) files.set(real(own.file), own.file)
181
+ }
182
+ }
183
+ return [...files.values()]
184
+ }
@@ -110,9 +110,7 @@ function warnUnreadable(siteRoot, where, reason, declaration) {
110
110
  const fieldsCalledType = declaration && typeof declaration === 'object' && typeof declaration.type === 'string' && 'values' in declaration && !('fields' in declaration)
111
111
  const hint = fieldsCalledType
112
112
  ? ` A data key is declared as its block's fields: { type: '${declaration.type}', values: … } declares two fields, named "type" and "values" — name the block's fields instead ({ email: 'string', time: 'string' }).`
113
- : /open map/.test(reason)
114
- ? " An open map is read when its values are records: values: { type: 'object', fields: { … } }."
115
- : ''
113
+ : ''
116
114
  console.warn(
117
115
  `Warning: ${who} declares data key "${key}" with a shape the translation step cannot read (${reason}), so its blocks' strings are guessed — a field named email, time, href or the like is never offered for translation.${hint}`
118
116
  )
@@ -7,8 +7,6 @@
7
7
  * One walk for two things a model describes: a record (`records.js`), and a tagged data block whose
8
8
  * key a section type declares the shape of (`data-strings.js::visitDataBlockStrings`).
9
9
  */
10
- import { isOpenMapSection } from '../uwx/data-schema.js'
11
-
12
10
  export function isPlainObject(value) {
13
11
  return !!value && typeof value === 'object' && !Array.isArray(value)
14
12
  }
@@ -50,10 +48,6 @@ export function eachModelField(record, model, visit) {
50
48
  function eachSectionValue(value, section, path, visit) {
51
49
  if (!section?.multiple) return eachSectionField(value, section?.fields, path, visit)
52
50
  if (Array.isArray(value)) value.forEach((item, i) => eachSectionField(item, section.fields, `${path}[${i}]`, visit))
53
- // An open map as its file holds it: each entry is one of the rows a push sends (`isOpenMapSection`).
54
- else if (isOpenMapSection(section) && isPlainObject(value)) {
55
- for (const [key, item] of Object.entries(value)) eachSectionField(item, section.fields, `${path}.${key}`, visit)
56
- }
57
51
  }
58
52
 
59
53
  export function eachSectionField(holder, fields, path, visit) {
@@ -11,10 +11,13 @@
11
11
  * '@std/name' → the shared standard schemas, shipped in the framework's
12
12
  * `@uniweb/schemas` package (resolved from the FOUNDATION's
13
13
  * node_modules)
14
- * '@org/name' → an org's own schemas, resolved from that org's
15
- * `@org/schemas` package — define schemas once and share
16
- * them across foundations, locally, no backend. (The org
17
- * becomes a real registry scope at publish time.)
14
+ * '@org/name' → an org's own schemas: the package of this workspace whose
15
+ * name gives the scope and that defines `name` (a foundation's
16
+ * own `schemas/`, or a schemas package), with nothing
17
+ * configured; else that org's installed `@org/schemas`
18
+ * package. Either way shared across foundations locally, no
19
+ * backend. (The org becomes a real registry scope at publish
20
+ * time.)
18
21
  * '@uniweb/name' → reserved: the platform system namespace, not a data
19
22
  * schema source (rejected, with a pointer to '@std').
20
23
  *
@@ -22,8 +25,9 @@
22
25
  * directory of schema files ('@org' → a folder), so '@org/name' resolves to a
23
26
  * bare folder anywhere on disk — no package, no install. It may also override a
24
27
  * SINGLE schema to an exact file ('@org/name' → a file), which wins over the
25
- * scope directory for that one name. Both take precedence over the '@org/schemas'
26
- * package convention (file over directory over package); see `loadSchemaAliases`.
28
+ * scope directory for that one name. Both take precedence over the workspace and
29
+ * the '@org/schemas' package (file over directory over workspace over package); see
30
+ * `loadSchemaAliases` and `workspaceTypeFiles`.
27
31
  *
28
32
  * The authoring format itself — the type vocabulary and the normalization of its
29
33
  * friendly aliases to canonical kinds — lives in `@uniweb/schemas/format`, and is
@@ -35,6 +39,7 @@
35
39
  * disk: finding a ref's file, alias routing, and closing the resolution graph.
36
40
  */
37
41
 
42
+ import { workspaceTypeFiles } from './foundation/shared-types.js'
38
43
  import { readFile } from 'node:fs/promises'
39
44
  import { existsSync, readdirSync, statSync } from 'node:fs'
40
45
  import { join, resolve, isAbsolute, extname, basename } from 'node:path'
@@ -132,7 +137,7 @@ function normalizeNamedSchema(schema, ref) {
132
137
  return normalized
133
138
  }
134
139
 
135
- // A field that lowers into a section — a nested object, an open map, a list of records — and so
140
+ // A field that lowers into a section — a nested object, a list of records — and so
136
141
  // may carry a section's `constraints`.
137
142
  function isSectionShaped(spec) {
138
143
  if (spec.type === 'object') return true
@@ -151,7 +156,6 @@ function fieldsWhere(schema, test) {
151
156
  if (test(spec)) found.push(path)
152
157
  walkFields(spec.fields, `${path}.`)
153
158
  if (spec.items) walkSpec(spec.items, `${path}[]`)
154
- if (spec.values) walkSpec(spec.values, `${path}{}`)
155
159
  }
156
160
  const walkSections = (sections, prefix) => {
157
161
  if (!sections || typeof sections !== 'object') return
@@ -280,11 +284,38 @@ export async function resolveSchemaRef(ref, { srcDir, aliases }) {
280
284
  return normalizeNamedSchema(await loadSchemaFile(file), ref)
281
285
  }
282
286
 
287
+ // ⭐ A type another package of this workspace defines: a foundation whose name gives the scope,
288
+ // or a schemas package of it, read with nothing configured (`workspaceTypeFiles`). After the
289
+ // routes `schemas.config.js` gives, which are explicit, and before an installed package, since a
290
+ // workspace is the copy being worked on. Two packages defining it are refused, naming both:
291
+ // there is one definition of a type.
292
+ const inWorkspace = await workspaceTypeFiles(`@${scope}/${name}`, srcDir)
293
+ if (inWorkspace.length > 1) {
294
+ throw new Error(
295
+ `Data schema '${ref}' is defined by ${inWorkspace.length} packages of this workspace: ` +
296
+ `${inWorkspace.join(', ')}. A type has one definition: keep one file, and name the type in ` +
297
+ `full in the others (\`uniweb doctor\` lists them as type-defined-twice).`
298
+ )
299
+ }
300
+ if (inWorkspace.length === 1) return normalizeNamedSchema(await loadSchemaFile(inWorkspace[0]), ref)
301
+
283
302
  // Every other scope is an org namespace: '@org/name' resolves `name` from that
284
303
  // org's '@org/schemas' package (the standards live under '@std', which ships in
285
304
  // '@uniweb/schemas'). Resolved from the foundation's node_modules, so a
286
305
  // workspace package shared across foundations works locally with no backend.
287
306
  const pkg = packageForScope(scope)
307
+ if (pkg !== SCOPE_PACKAGE.std && !isScopePackageInstalled(scope, srcDir)) {
308
+ throw Object.assign(
309
+ new Error(
310
+ `Data schema '${ref}' is defined nowhere this foundation can read: no package of its workspace ` +
311
+ `whose name gives the scope '@${scope}' defines '${name}', and '${pkg}' is not installed. ` +
312
+ `Name the foundation that defines it '@${scope}/<name>' in its main.js, route the type with ` +
313
+ `schemas.config.js ('@${scope}/${name}': '<its file>'), or add '${pkg}' to the foundation's ` +
314
+ `devDependencies.`
315
+ ),
316
+ { code: SCHEMA_NOT_FOUND }
317
+ )
318
+ }
288
319
  const schema = await resolveScopedSchema(pkg, name, srcDir)
289
320
  if (!schema) {
290
321
  throw new Error(`Unknown data schema '${ref}': '${pkg}' exports no schema named '${name}'.`)
@@ -54,7 +54,7 @@
54
54
  // otherwise hold records nothing reads, silently.
55
55
 
56
56
  import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
57
- import { join, extname, basename, resolve } from 'node:path'
57
+ import { join, extname, basename, resolve, dirname } from 'node:path'
58
58
  import yaml from 'js-yaml'
59
59
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
60
60
 
@@ -168,6 +168,71 @@ export function resolveRecordsDir(siteRoot, paths) {
168
168
  return { rel, abs: resolve(siteRoot, rel) }
169
169
  }
170
170
 
171
+ /**
172
+ * ⭐ ANOTHER SITE'S RECORDS, MOUNTED — `site.yml::paths`, as a pages folder is mounted:
173
+ *
174
+ * paths:
175
+ * records/acme/member: ../../hub/site/records/acme/member
176
+ *
177
+ * The mounted directory is this site's records of that type: the build, `uniweb dev`, `validate`
178
+ * and translation read its files where the key puts them. They stay the owning site's, so a push
179
+ * links the entities the owner's push made rather than sending them again, and a pull writes
180
+ * nothing into the directory (`uwx/records.js`, `uwx/records-project.js`). On a backend a site's
181
+ * folder is references to entities, and one entity can be in several sites' folders
182
+ * *[Diego, 2026-11-08: "the same entities can be reference from more than one sites records
183
+ * (folder of entity references)"]*.
184
+ *
185
+ * A key names one type, as a records folder does: `records/<name>` or `records/<org>/<name>`. Link
186
+ * and file records are not mounted: they are entries of a site's own folder. The site's own folder
187
+ * at that path holds no records of its own (`readEntityPoolSync` says so). The owner is the nearest
188
+ * folder at or above the mounted directory holding a `site.yml`.
189
+ *
190
+ * @param {string} siteRoot
191
+ * @param {object} [paths] - `site.yml::paths`, when the caller has already read it
192
+ * @returns {Array<{ key: string, dirs: string[], abs: string, owner: string|null }>}
193
+ */
194
+ export function resolveRecordMounts(siteRoot, paths) {
195
+ const p = paths === undefined ? readSitePaths(siteRoot) : paths || {}
196
+ const mounts = []
197
+ for (const [key, value] of Object.entries(p)) {
198
+ if (!key.startsWith(`${RECORDS_DIR}/`)) continue
199
+ const dirs = key.slice(RECORDS_DIR.length + 1).replace(/\/+$/, '').split('/')
200
+ const named = schemaForPoolDirs(dirs)
201
+ if (!named || dirs.some((d) => !d || d === '.' || d === '..' || isHidden(d))) {
202
+ throw new Error(
203
+ `[uniweb] site.yml: \`paths.${key}\` names no type. A records mount is one type's folder: ` +
204
+ `\`${RECORDS_DIR}/<name>\` for \`@/<name>\`, or \`${RECORDS_DIR}/<org>/<name>\` for \`@<org>/<name>\`.`
205
+ )
206
+ }
207
+ if (named === LINK_RECORDS || isFileRecordDir(dirs)) {
208
+ throw new Error(
209
+ `[uniweb] site.yml: \`paths.${key}\` mounts link or file records, which are entries of a site's ` +
210
+ `own folder. Mount a type of data records.`
211
+ )
212
+ }
213
+ if (typeof value !== 'string' || !value.trim()) {
214
+ throw new Error(`[uniweb] site.yml: \`paths.${key}\` must be the path of the directory it mounts.`)
215
+ }
216
+ const abs = resolve(siteRoot, value.trim())
217
+ if (!isDirectory(abs)) {
218
+ throw new Error(`[uniweb] site.yml: \`paths.${key}\` mounts \`${value.trim()}\`, which is not a directory here.`)
219
+ }
220
+ mounts.push({ key, dirs, abs, owner: owningSiteRoot(abs) })
221
+ }
222
+ return mounts
223
+ }
224
+
225
+ // The site a mounted records directory belongs to: the nearest folder at or above it with a site.yml.
226
+ function owningSiteRoot(dir) {
227
+ for (let d = resolve(dir); ; d = dirname(d)) {
228
+ if (existsSync(join(d, 'site.yml'))) return d
229
+ if (dirname(d) === d) return null
230
+ }
231
+ }
232
+
233
+ // A link record's type, which no mount takes (`resolveRecordMounts`).
234
+ const LINK_RECORDS = '@uniweb/link'
235
+
171
236
  /** Source extensions a record file may have. Mirrors the sync-lane reader. */
172
237
  export const ENTITY_EXTENSIONS = new Set(['.md', '.yml', '.yaml', '.json', '.bib'])
173
238
 
@@ -283,10 +348,14 @@ export function readEntityPoolSync(siteRoot, opts = {}) {
283
348
  // ⛔ `resolve`, not `join`: an absolute `paths.records` is supported, and
284
349
  // `join(siteRoot, '/abs')` is a path under the site root that does not exist.
285
350
  const base = resolve(siteRoot, rel)
286
- if (!isDirectory(base)) return { entities: [], errors: [], exists: false, dir: rel }
351
+ const mounts = opts.mounts !== undefined ? opts.mounts : resolveRecordMounts(siteRoot)
352
+ if (!isDirectory(base) && mounts.length === 0) return { entities: [], errors: [], exists: false, dir: rel }
287
353
 
288
354
  const entities = []
289
355
  const errors = []
356
+ // A mounted type's folder, by its path below the records directory.
357
+ const mountAt = new Map(mounts.map((m) => [m.dirs.join('/'), m]))
358
+ let mountedFrom = null
290
359
  // A file record is named by its stem, so two files of one stem cannot both be one.
291
360
  const fileStems = new Map()
292
361
 
@@ -301,6 +370,19 @@ export function readEntityPoolSync(siteRoot, opts = {}) {
301
370
  if (isHidden(e.name)) continue
302
371
  const full = join(dir, e.name)
303
372
  if (e.isDirectory()) {
373
+ // ⭐ A mounted type's folder is read from its mount (below), never from here.
374
+ const mount = mountedFrom ? null : mountAt.get([...dirs, e.name].join('/'))
375
+ if (mount) {
376
+ const own = readdirSync(full).filter((n) => !isHidden(n))
377
+ if (own.length) {
378
+ errors.push(
379
+ `${rel}/${[...dirs, e.name].join('/')}/ is mounted from ${mount.abs} (site.yml \`paths.${mount.key}\`), ` +
380
+ `and holds ${own.length} file(s) of its own, which are not read. A mounted type's records are ` +
381
+ `the owner's: move these to the owning site, or remove the mount.`
382
+ )
383
+ }
384
+ continue
385
+ }
304
386
  if (dirs.length >= 2) {
305
387
  // Deeper than a schema dir. Say what the path was read AS, because the
306
388
  // author's intent (organising records inside a schema) is the reading
@@ -362,11 +444,17 @@ export function readEntityPoolSync(siteRoot, opts = {}) {
362
444
  absPath: full,
363
445
  ext,
364
446
  ...(fileRecord ? { fileRecord: true } : {}),
447
+ ...(mountedFrom ? { mounted: mountedFrom } : {}),
365
448
  })
366
449
  }
367
450
  }
368
451
 
369
- walk(base, [])
452
+ if (isDirectory(base)) walk(base, [])
453
+ for (const mount of mounts) {
454
+ mountedFrom = { from: mount.abs, owner: mount.owner, key: mount.key }
455
+ walk(mount.abs, [...mount.dirs])
456
+ }
457
+ mountedFrom = null
370
458
  return { entities, errors, exists: true, dir: rel }
371
459
  }
372
460
 
@@ -37,7 +37,7 @@ import { collectTranslatedAssets } from './assets.js'
37
37
  import { processAdvancedAssets } from './advanced-processors.js'
38
38
  import { devMediaPaths } from './dev-media.js'
39
39
  import { processQueries, writeQueryFiles } from './query-processor.js'
40
- import { RECORDS_DIR, resolveRecordsDir } from './entity-pool.js'
40
+ import { RECORDS_DIR, resolveRecordsDir, resolveRecordMounts } from './entity-pool.js'
41
41
  import { executeFetch, mergeDataIntoContent, toFetchList } from './data-fetcher.js'
42
42
  import { shouldSplitContent } from './split-content.js'
43
43
  import { jsonForScript } from '@uniweb/core/data-script'
@@ -938,6 +938,13 @@ export function siteContentPlugin(options = {}) {
938
938
  const contentPaths = new Set([
939
939
  resolve(resolvedSitePath, resolvedRecordsDir || RECORDS_DIR)
940
940
  ])
941
+ // ⭐ And each records directory the site mounts from another site (`site.yml::paths`),
942
+ // so an edit to the owner's file reaches this site's pages too.
943
+ try {
944
+ for (const mount of resolveRecordMounts(resolvedSitePath)) contentPaths.add(mount.abs)
945
+ } catch (err) {
946
+ console.warn(`[site-content] ${err.message}`)
947
+ }
941
948
 
942
949
  for (const contentPath of contentPaths) {
943
950
  if (existsSync(contentPath)) {
@@ -813,7 +813,10 @@ function readPooledRecords(pooled, config, siteDir, recordsRoot, basePath) {
813
813
  pooled.map((e) => {
814
814
  // ⭐ The file itself is the record (`file-records.js`) — nothing in it is read.
815
815
  if (e.fileRecord) return processFileRecord(e, config, siteDir, recordsRoot, basePath)
816
- const dir = resolve(recordsRoot, ...e.dirs)
816
+ // Where the pool found the file: under the records root, or in a mounted directory, another
817
+ // site's (`entity-pool.js::resolveRecordMounts`). An asset beside a mounted record is outside
818
+ // the root, so it publishes as `_external/…` (`recordAssetPath`).
819
+ const dir = dirname(e.absPath)
817
820
  const file = `${e.slug}${e.ext}`
818
821
  if (e.ext === '.bib') {
819
822
  return processBibtexItem(dir, file, siteDir, config.includeDrafts)
@@ -64,6 +64,20 @@ function isWorkspaceRoot(dir) {
64
64
  }
65
65
  }
66
66
 
67
+ /**
68
+ * The workspace a folder is in: the nearest folder at or above it that holds a workspace manifest,
69
+ * the marker the CLI finds a workspace by. Null when no workspace holds it.
70
+ *
71
+ * @param {string} fromDir
72
+ * @returns {string|null}
73
+ */
74
+ export function workspaceRootOf(fromDir) {
75
+ for (let dir = resolve(fromDir); ; dir = dirname(dir)) {
76
+ if (isWorkspaceRoot(dir)) return dir
77
+ if (dirname(dir) === dir) return null
78
+ }
79
+ }
80
+
67
81
  /** One folder name — never a path, so a declaration cannot walk the search out of a folder. */
68
82
  function isExtensionName(name) {
69
83
  return typeof name === 'string' && name !== '' && name !== '.' && name !== '..' && !/[\\/]/.test(name)
@@ -41,7 +41,7 @@ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
41
41
  import { proseMirrorToMarkdown } from '@uniweb/content-writer'
42
42
  import { parseFrontmatter } from './entity-source.js'
43
43
  import { setYamlKeyFirst } from './yaml-edit.js'
44
- import { isProseMirrorField, isOpenMapSection, openMapFromRows } from './data-schema.js'
44
+ import { isProseMirrorField } from './data-schema.js'
45
45
  import { recordFileLayout, contentBodyTarget } from './record-layout.js'
46
46
  import { recordFieldPlace, unwrapLocalizedContent } from './locale-sync.js'
47
47
  import { parseBibtex, exportBibtex } from '@citestyle/bibtex'
@@ -347,7 +347,7 @@ function decodeRecord(fields, value, dec, sectionName) {
347
347
  const raw = value[key]
348
348
  if (raw === undefined) continue
349
349
  if (field?.type === 'section') {
350
- out[key] = field.multiple === true ? decodeSectionList(field, raw, dec) : decodeRecord(field.fields, raw, dec, null)
350
+ out[key] = field.multiple === true ? decodeList(field, raw, dec) : decodeRecord(field.fields, raw, dec, null)
351
351
  continue
352
352
  }
353
353
  const isBody = Boolean(dec.bodyAt) && sectionName === dec.bodyAt.section && key === dec.bodyAt.key
@@ -359,14 +359,6 @@ function decodeRecord(fields, value, dec, sectionName) {
359
359
  return out
360
360
  }
361
361
 
362
- // A `many` field's records — an OPEN MAP's written back as the author's map, keyed by each row's
363
- // `name` (`isOpenMapSection`), which is what the push reads a map from. Rows that cannot be a map
364
- // stay a list, which the push reads too.
365
- function decodeSectionList(def, value, dec) {
366
- const list = decodeList(def, value, dec)
367
- return (isOpenMapSection(def) && openMapFromRows(list)) || list
368
- }
369
-
370
362
  // The records of a `many` section; a self-nesting one's `$children` nest back under
371
363
  // `children:`, the reserved key the push reads them from.
372
364
  function decodeList(def, value, dec) {
@@ -34,48 +34,6 @@ const TEXT_KINDS = new Set(['string', 'text'])
34
34
  // ⛔ `html` was one until 2026-10-14; `@uniweb/schemas` refuses it by name since.
35
35
  const CONTENT_TEXT_FORMATS = new Set(['markdown'])
36
36
 
37
- // The field an open map's key lowers into. `name` matches the idiom already in use
38
- // for this shape (the backend's site-content `collections` section), so an open map
39
- // and a hand-authored row set produce the same wire shape rather than two spellings
40
- // of one thing. Not configurable on purpose: a second way to spell it would be a
41
- // vocabulary addition for a collision that does not exist yet — a value schema that
42
- // declares its own `name` is an error instead, which names the problem precisely.
43
- const OPEN_MAP_KEY = 'name'
44
-
45
- /**
46
- * ⭐ AN OPEN MAP'S LOWERED SECTION. `values:` lowers to rows (`lowerField`): a `multiple` section
47
- * whose required string `name` — the map's key — is made each row's identity by a `unique_field`
48
- * rule. A record FILE holds it as the author wrote it, a map from key to value; the WIRE holds the
49
- * rows. This is the one test, read off the declaration alone, because a pull into a clone has
50
- * nothing else: the push turns a file's map into rows by it, and the pull the rows back into a map.
51
- */
52
- export function isOpenMapSection(def) {
53
- if (def?.multiple !== true || def.self_nesting === true) return false
54
- const key = def.fields?.[OPEN_MAP_KEY]
55
- if (key?.type !== 'string' || key.required !== true || key.localized === true) return false
56
- return (def.constraints || []).some((c) => c?.kind === 'unique_field' && c.field === OPEN_MAP_KEY && c.scope === 'section')
57
- }
58
-
59
- /** A file's open map as the rows it lowers to, in the map's key order: each key is its row's `name`. */
60
- export function openMapEntries(map) {
61
- return Object.entries(map).map(([key, value]) => ({ key, value, row: { ...value, [OPEN_MAP_KEY]: key } }))
62
- }
63
-
64
- /**
65
- * Rows back as the map a file holds, or null when they cannot be one — a row with no key, or a key
66
- * two rows share — so a caller keeps them a list, which a push reads too, and nothing is lost.
67
- */
68
- export function openMapFromRows(rows) {
69
- const map = {}
70
- for (const row of rows || []) {
71
- const key = row?.[OPEN_MAP_KEY]
72
- if (typeof key !== 'string' || key === '' || Object.hasOwn(map, key)) return null
73
- const { [OPEN_MAP_KEY]: _key, ...value } = row
74
- map[key] = value
75
- }
76
- return map
77
- }
78
-
79
37
  /**
80
38
  * A `text` field marked as rich content (`format: markdown` or `html`): the
81
39
  * file-based body target. Round-trips as the raw source string — what the retired
@@ -408,59 +366,6 @@ function lowerField(rawField, resolve, optResolve, path = '') {
408
366
  const type = field.type
409
367
 
410
368
  if (type === 'object') {
411
- // An OPEN MAP (`values:`) is ROWS, not a singleton. Its keys belong to the
412
- // author, which makes them data — so the map lowers to a `multi` section whose
413
- // key field carries what was the object key, with a section-scoped uniqueness
414
- // rule making that key the row's identity. This is the same shape `array of
415
- // object` already lowers to, and the idiom the backend's own site-content
416
- // `collections` section uses; no new wire construct is involved.
417
- //
418
- // Identity is the KEY, never row position — a round-trip that rebuilds the map
419
- // from order looks correct and drifts the first time rows are reordered.
420
- // Authoring order is still preserved into row order, because for a form the
421
- // field order is what the visitor sees.
422
- if (field.values !== undefined) {
423
- const value = asField(field.values)
424
- if (value.type !== 'object' || !value.fields) {
425
- throw new Error(
426
- `Data schema: open map at '${path}' declares 'values' that is not an object with ` +
427
- `'fields'. An open map lowers to rows, and a row needs declared columns.`
428
- )
429
- }
430
- if (value.fields[OPEN_MAP_KEY]) {
431
- throw new Error(
432
- `Data schema: open map at '${path}' has a value field named '${OPEN_MAP_KEY}', which ` +
433
- `is the field the map's key lowers into. Rename that field.`
434
- )
435
- }
436
- return {
437
- type: 'section',
438
- ...lowerSection(
439
- {
440
- kind: 'multi',
441
- ...sectionAttrsFromField(field),
442
- // `translatable: false` is load-bearing, not tidiness: a string field is
443
- // localized by default, and a localized key could differ per locale —
444
- // which would destroy the identity the key exists to carry. The key is an
445
- // identifier, never content.
446
- fields: {
447
- [OPEN_MAP_KEY]: { type: 'string', required: true, translatable: false },
448
- ...value.fields
449
- },
450
- // The uniqueness rule is STRUCTURAL — it is what makes the map's key the
451
- // row's identity — so it is prepended rather than assigned: an author's
452
- // own constraints on this field add to it and can never replace it.
453
- constraints: [
454
- { kind: 'unique_field', field: OPEN_MAP_KEY, scope: 'section' },
455
- ...(sectionAttrsFromField(field).constraints || [])
456
- ]
457
- },
458
- resolve,
459
- optResolve,
460
- path
461
- )
462
- }
463
- }
464
369
  return {
465
370
  type: 'section',
466
371
  ...lowerSection({ kind: 'single', ...sectionAttrsFromField(field), fields: field.fields }, resolve, optResolve, path)
@@ -690,13 +595,12 @@ export function assertOptionsTargets(dataSchemas) {
690
595
  }
691
596
 
692
597
  // Every field of a normalized schema that declares `options:`, with its dotted path — in any
693
- // section, nested object, list of records or open map.
598
+ // section, nested object or list of records.
694
599
  function forEachOptionsField(schema, fn) {
695
600
  const visitField = (raw, path) => {
696
601
  const field = asField(raw)
697
602
  if (typeof field.options === 'string') fn(path, field.options)
698
603
  if (field.items) visitField(field.items, path)
699
- if (field.values) visitField(field.values, path)
700
604
  for (const [key, child] of Object.entries(field.fields || {})) visitField(child, `${path}.${key}`)
701
605
  }
702
606
  const visitSection = (section, prefix) => {
@@ -709,8 +613,7 @@ function forEachOptionsField(schema, fn) {
709
613
 
710
614
  // The sections of a normalized Model by the path the registry names each one by, and whether each
711
615
  // holds items — the lowering's own shapes (`lowerField`): a child in `sections:`, a nested object
712
- // (one record), a list of records, an open map (rows). A section holding only sections — a binder —
713
- // holds none.
616
+ // (one record), a list of records. A section holding only sections — a binder — holds none.
714
617
  function sectionPathsOf(normalized) {
715
618
  const out = []
716
619
  const visit = (path, node) => {
@@ -729,10 +632,7 @@ function sectionPathsOf(normalized) {
729
632
  // The section a section-shaped FIELD lowers into (`lowerField`), or null for a leaf.
730
633
  function sectionOfField(raw) {
731
634
  const field = asField(raw)
732
- if (field.type === 'object') {
733
- if (field.values !== undefined) return { kind: 'multi', fields: { [OPEN_MAP_KEY]: { type: 'string' }, ...asField(field.values).fields } }
734
- return { kind: 'single', fields: field.fields }
735
- }
635
+ if (field.type === 'object') return { kind: 'single', fields: field.fields }
736
636
  if (field.type === 'array' && field.items && asField(field.items).type === 'object') {
737
637
  return { kind: 'multi', fields: asField(field.items).fields }
738
638
  }
@@ -43,7 +43,7 @@ import { parseFrontmatter } from './entity-source.js'
43
43
  import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './project-writer.js'
44
44
  import { foundationDataSchemas, foundationSchemaJson, QUERIES_YML_RELPATH } from './queries-config.js'
45
45
  import { dataKeyTypes } from './data-key-types.js'
46
- import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir, readEntityPoolSync } from '../site/entity-pool.js'
46
+ import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir, readEntityPoolSync, resolveRecordMounts } from '../site/entity-pool.js'
47
47
  import { folderYmlPath, resolveFolder } from '../site/records-config.js'
48
48
  import { canonicalJson } from './same-content.js'
49
49
  import { contentBodyTarget } from './record-layout.js'
@@ -778,6 +778,14 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
778
778
  }
779
779
  // BibTeX files holding a pulled record — never rewritten by a pull, and said once each.
780
780
  const keptBib = new Set()
781
+ // ⭐ ANOTHER SITE'S RECORDS, MOUNTED (`site/entity-pool.js::resolveRecordMounts`): their files are
782
+ // the owner's, so a pull writes nothing there. It finds each one's file by the owner's id for it
783
+ // (the owner's `sync.json`), so the folder is written with the record where it is.
784
+ const mounts = resolveRecordMounts(siteRoot).map((m) => {
785
+ const ownerMap = opts.backend && m.owner ? readBackendState(m.owner, opts.backend).records || {} : {}
786
+ return { ...m, at: resolve(recordsRoot, ...m.dirs), ownerOwnId: new Map(Object.entries(ownerMap).map(([o, t]) => [t, o])) }
787
+ })
788
+ const leftToOwner = []
781
789
 
782
790
  for (const document of recordDocs) {
783
791
  const where = locate(document, folderIndex)
@@ -801,6 +809,22 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
801
809
  })
802
810
  continue
803
811
  }
812
+ const mount = mounts.find((m) => m.at === resolve(poolDir))
813
+ if (mount) {
814
+ const theirs = document.$uuid || null
815
+ const hit = theirs ? findRecordFileByUuid(mount.abs, mount.ownerOwnId.get(theirs) || theirs) : null
816
+ if (!hit) {
817
+ skipped.push({
818
+ uuid: theirs,
819
+ slug: where.slug,
820
+ reason: `a record of a type mounted from ${mount.abs} (site.yml \`paths.${mount.key}\`), which holds no file for it`,
821
+ })
822
+ continue
823
+ }
824
+ poolPathByUuid.set(theirs, [...mount.dirs, basename(hit.path)].join('/'))
825
+ leftToOwner.push(hit.path)
826
+ continue
827
+ }
804
828
  // ⭐ The incoming `$uuid` is the BACKEND's. The file holds the record's OWN id, so
805
829
  // reverse this backend's map to find it. With no mapping the two are the same —
806
830
  // the first backend a record reaches minted the id it keeps — so the backend's
@@ -916,5 +940,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
916
940
  updated, placed, unchanged, skipped, warnings, locales, freeform, records: records.status, recordsFile: records.file,
917
941
  // The file records' bytes to fetch — `{ url, path, poolPath }` each (`./file-records.js`).
918
942
  fileDownloads: pulledFiles.downloads,
943
+ // Mounted records, another site's files, which this pull read and left as they are.
944
+ leftToOwner,
919
945
  }
920
946
  }
@@ -56,7 +56,7 @@ import {
56
56
  poolPathReadings,
57
57
  poolDirsForSchema,
58
58
  } from '../site/entity-pool.js'
59
- import { toDataSchemaDeclaration, isProseMirrorField, isMarkupTextField, isOpenMapSection, openMapEntries } from './data-schema.js'
59
+ import { toDataSchemaDeclaration, isProseMirrorField, isMarkupTextField } from './data-schema.js'
60
60
  import { recordFileLayout, contentBodyTarget } from './record-layout.js'
61
61
  import { emitEntitySyncPackage } from './entity-document.js'
62
62
  import { qualifyRef } from '@uniweb/schemas/refs'
@@ -430,20 +430,6 @@ function readBySection(layout, record, enc) {
430
430
  // are its child sections), a list of records for a `many` one.
431
431
  function encodeSection(def, value, enc, path) {
432
432
  if (def.multiple === true) {
433
- // ⭐ AN OPEN MAP is the author's map in a file and rows on the wire (`isOpenMapSection`): each
434
- // key becomes its row's `name`. ⛔ Until 2026-09-26 the map was refused as "a list of records",
435
- // so no record holding one could be pushed. Rows written as a list are read as they are.
436
- if (isOpenMapSection(def) && isPlainObject(value)) {
437
- const rows = []
438
- for (const { key, value: entry, row } of openMapEntries(value)) {
439
- if (!isPlainObject(entry)) {
440
- enc.shape.push(`"${path}.${key}" is one entry of a map — write it as a map of its fields.`)
441
- continue
442
- }
443
- rows.push(encodeItem(def, row, enc, `${path}.${key}`))
444
- }
445
- return rows
446
- }
447
433
  if (!Array.isArray(value)) {
448
434
  enc.shape.push(`"${path}" holds a list of records — write it as a list ("- …" under "${path}:").`)
449
435
  return undefined
@@ -554,12 +540,12 @@ function describeUnresolved({ path, model, value, invalid, ambiguous }) {
554
540
  // `{ $ref: <$id> }` for a record of the same package. A uuid it did not mint is never
555
541
  // sent (see `buildRecordEntities`).
556
542
  const AMBIGUOUS = Symbol('ambiguous')
557
- function refResolver(readSchemas, recordMap, moved = new Map()) {
543
+ function refResolver(readSchemas, recordMap, moved = new Map(), shared = []) {
558
544
  const byModel = new Map() // Model → handle → the record: its own id (null before its first push) and `$id`
559
545
  const byOwnId = new Map() // the record's own id → the record
546
+ const namesOf = (model) => byModel.get(model) || byModel.set(model, new Map()).get(model)
560
547
  for (const { declaration, flat } of readSchemas) {
561
- let names = byModel.get(declaration.name)
562
- if (!names) byModel.set(declaration.name, (names = new Map()))
548
+ const names = namesOf(declaration.name)
563
549
  for (const rec of flat) {
564
550
  const own = typeof rec.$uuid === 'string' && rec.$uuid ? rec.$uuid : null
565
551
  const record = { own, id: rec.$id }
@@ -567,8 +553,19 @@ function refResolver(readSchemas, recordMap, moved = new Map()) {
567
553
  if (own) byOwnId.set(own, record)
568
554
  }
569
555
  }
556
+ // A mounted record is named by its handle too, and answers with the uuid its owner's push was given.
557
+ for (const s of shared) {
558
+ const names = namesOf(s.model)
559
+ names.set(s.slug, names.has(s.slug) ? AMBIGUOUS : { uuid: s.uuid })
560
+ if (s.own) byOwnId.set(s.own, { uuid: s.uuid })
561
+ }
570
562
  // A record moved to another data schema is new on the wire, so a reference names it by `$id`.
571
- const sent = ({ own, id }) => (own && recordMap[own] && !moved.has(own) ? { uuid: recordMap[own] } : { ref: id })
563
+ const sent = (record) =>
564
+ record.uuid
565
+ ? { uuid: record.uuid }
566
+ : record.own && recordMap[record.own] && !moved.has(record.own)
567
+ ? { uuid: recordMap[record.own] }
568
+ : { ref: record.id }
572
569
  return {
573
570
  resolve(model, value) {
574
571
  if (typeof value !== 'string' || value === '') return { invalid: true }
@@ -1121,6 +1118,11 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1121
1118
  // label and tags.
1122
1119
  const links = []
1123
1120
  const linkNames = new Map() // slug → the file that gave it, so two files cannot claim one name
1121
+ // ⭐ A MOUNTED RECORD IS ANOTHER SITE'S ENTITY (`site/entity-pool.js::resolveRecordMounts`): this
1122
+ // site's folder holds a reference to it, never a second copy. Its leaf names the uuid the owning
1123
+ // site's push was given on this backend, read from the owner's `sync.json`; its file is the
1124
+ // owner's, so nothing is written back into it.
1125
+ const shared = []
1124
1126
  for (const pooled of poolBySchema.get(LINK_MODEL) || []) {
1125
1127
  const produced = []
1126
1128
  for (const r of await readEntityFile(pooled.absPath)) {
@@ -1191,6 +1193,28 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1191
1193
  const sourceBySlug = new Map()
1192
1194
  for (const pooled of poolEntities) {
1193
1195
  const produced = []
1196
+ if (pooled.mounted) {
1197
+ const { owner, from } = pooled.mounted
1198
+ const ownerMap = opts.backend && owner ? readBackendState(owner, opts.backend).records || {} : {}
1199
+ for (const r of await readEntityFile(pooled.absPath)) {
1200
+ if (!r.slug) continue
1201
+ const own = typeof r.data?.$uuid === 'string' && r.data.$uuid ? r.data.$uuid : null
1202
+ const uuid = own ? ownerMap[own] : undefined
1203
+ if (!uuid) {
1204
+ refusals.push(
1205
+ `${pooled.relPath}: mounted from ${from}, a record of ${owner ? `the site in ${owner}` : 'another site'} ` +
1206
+ `that ${own ? 'is not on this backend yet' : 'has never been pushed'}. Push that site first, and this ` +
1207
+ `site's folder then holds the entity its push made.`
1208
+ )
1209
+ continue
1210
+ }
1211
+ const id = [...pooled.dirs, r.slug].join('/')
1212
+ shared.push({ id, slug: r.slug, model: declaration.name, uuid, own })
1213
+ produced.push({ id, slug: r.slug })
1214
+ }
1215
+ producedBy.set(pooled.id, produced)
1216
+ continue
1217
+ }
1194
1218
  for (const r of await readEntityFile(pooled.absPath)) {
1195
1219
  if (!r.slug) {
1196
1220
  warnings.push(`${pooled.relPath}: a record without a slug was skipped`)
@@ -1235,7 +1259,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1235
1259
  }
1236
1260
  readSchemas.push({ label, declaration, flat, sourceBySlug })
1237
1261
  }
1238
- const refs = refResolver(readSchemas, recordMap, moved)
1262
+ const refs = refResolver(readSchemas, recordMap, moved, shared)
1239
1263
 
1240
1264
  for (const { label, declaration, flat, sourceBySlug } of readSchemas) {
1241
1265
  const ownIds = new Map()
@@ -1363,7 +1387,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1363
1387
  colConfig,
1364
1388
  folder: { ...folder, nodes },
1365
1389
  recordsDirExists: pool.exists,
1366
- sendFolder: sendsFolder(pool, entities, [...links, ...files]),
1390
+ sendFolder: sendsFolder(pool, entities, [...links, ...files, ...shared]),
1367
1391
  // Each entity's declaration, by its Model — what walks a record's lists
1368
1392
  // (`record-items.js`).
1369
1393
  declarations: new Map(readSchemas.map(({ declaration }) => [declaration.name, declaration])),
@@ -1374,6 +1398,8 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1374
1398
  links,
1375
1399
  // The file records, likewise (`./file-records.js`).
1376
1400
  files,
1401
+ // Mounted records: another site's entities, placed in this site's folder by reference.
1402
+ shared,
1377
1403
  }
1378
1404
  }
1379
1405
 
@@ -1130,7 +1130,7 @@ function writeMdPage({ record, place, route, ctx, report, pageContext, sourceLoc
1130
1130
  * Its `title:` is kept as the author wrote it: a file that holds one keeps it, holding the page's
1131
1131
  * title, and a file that holds none gains one only where its first heading, else its name, does not
1132
1132
  * give the title. So a pull of what was pushed leaves the file as it was, and a title the author fixed
1133
- * in the file stays fixed when the heading changes. ⛔ Until 2026-11-09 a `title:` equal to the
1133
+ * in the file stays fixed when the heading changes. ⛔ Until 2026-11-08 a `title:` equal to the
1134
1134
  * heading's was removed, a change nobody made, after which the heading named the page.
1135
1135
  *
1136
1136
  * @returns {object}
@@ -363,7 +363,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
363
363
  const { values: fileValues, uploads: localFiles } = await fileRecordUploads({ files: col.files || [], siteRoot })
364
364
  const files = (col.files || []).map((f) => ({ ...f, value: fileValues.get(f.poolPath) }))
365
365
  const folder = buildFolderEntity({
366
- recordEntities: col.entities,
366
+ // ⭐ With the mounted records: another site's entities, placed by reference to the uuid its push
367
+ // was given, and never sent as entities of this site (`records.js`, `shared`).
368
+ recordEntities: [...col.entities, ...(col.shared || [])],
367
369
  // Link records ride the folder as entries of their own kind (`./link-records.js`).
368
370
  links: col.links || [],
369
371
  files,
@@ -9,7 +9,7 @@
9
9
  * Two layers, and only the second one lives here:
10
10
  * - `validateItem(schema, item)` — pure, facet-driven: walks a normalized
11
11
  * schema's declared facets (required / type / enum / format / nested
12
- * object+array / open map) and emits one finding per failed facet. No I/O.
12
+ * object+array) and emits one finding per failed facet. No I/O.
13
13
  * It now lives in `@uniweb/schemas/conform`, beside the vocabulary it must
14
14
  * agree with, and is re-exported below so every caller here is unchanged.
15
15
  * - `validateDataInputs({ siteRoot, foundationPath })` — the join: pairs each
@@ -0,0 +1,272 @@
1
+ // THE WORKSPACE'S PACKAGES, READ AS PNPM READS THEM: the reading half of the CLI's
2
+ // `utils/workspace-packages.js`, in a module of its own, so that `@uniweb/build` holds the same rule
3
+ // without either package importing the other.
4
+ //
5
+ // ⛔ THIS FILE IS MIRRORED, BYTE FOR BYTE: `framework/cli/src/utils/workspace-patterns.js` and
6
+ // `framework/build/src/workspace-patterns.js`. The CLI's startup path reads it before any project,
7
+ // and so any `@uniweb/build`, is installed; the build reads it to find a data schema another package
8
+ // of the workspace defines (`foundation/shared-types.js`). Edit one and copy it over the other:
9
+ // `_contracts/workspace-patterns-mirror.test.js` fails until they match.
10
+ //
11
+ // A workspace lists its packages as folder patterns: `packages:` in pnpm-workspace.yaml, or
12
+ // `workspaces` in package.json for npm and yarn. Patterns are read as pnpm reads them: `*`, `?` and
13
+ // `[...]` within one folder name, `**` for any depth, `{a,b}` for alternatives, and a leading `!` to
14
+ // exclude what the other patterns match. A folder a wildcard finds counts when it holds a
15
+ // package.json, as pnpm counts it — so `**` never sweeps in a `pages/` or `dist/` folder — and a
16
+ // wildcard never enters `node_modules` or a dot-folder. A folder listed by its own path counts if it
17
+ // exists: listing it says it is one, and a command that reads content only (`validate`) works on a
18
+ // folder with no manifest yet. Any other syntax is refused by name, never read as a path.
19
+ //
20
+ // Node built-ins and js-yaml only.
21
+
22
+ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
23
+ import { join } from 'node:path'
24
+ import yaml from 'js-yaml'
25
+
26
+ export const WORKSPACE_FILE = 'pnpm-workspace.yaml'
27
+
28
+ // Read as the build reads YAML (`build/src/utils/yaml-schema.js`): js-yaml's types without the
29
+ // implicit timestamp, so a folder named like a date, `packages: [2025-06-01]`, stays its name instead
30
+ // of becoming a Date that the list then drops. Restated here, since this file imports only js-yaml.
31
+ const YAML_OPTIONS = Object.freeze({ schema: yaml.CORE_SCHEMA.extend({ implicit: [yaml.types.merge] }) })
32
+
33
+ // ─── Reading ────────────────────────────────────────────────────────────────
34
+
35
+ /**
36
+ * The package patterns a workspace declares, and the file they are read from:
37
+ * pnpm-workspace.yaml when the workspace has one, else package.json's `workspaces`.
38
+ *
39
+ * @param {string} rootDir
40
+ * @returns {{ source: string|null, patterns: string[] }}
41
+ */
42
+ export function readWorkspacePatterns(rootDir) {
43
+ const ymlPath = join(rootDir, WORKSPACE_FILE)
44
+ if (existsSync(ymlPath)) {
45
+ const doc = yaml.load(readFileSync(ymlPath, 'utf8'), YAML_OPTIONS)
46
+ return { source: WORKSPACE_FILE, patterns: strings(doc?.packages) }
47
+ }
48
+ try {
49
+ const pkg = JSON.parse(readFileSync(join(rootDir, 'package.json'), 'utf8'))
50
+ if (Array.isArray(pkg.workspaces)) return { source: 'package.json', patterns: strings(pkg.workspaces) }
51
+ } catch {
52
+ // No package.json, or not JSON — a workspace with no packages declared.
53
+ }
54
+ return { source: null, patterns: [] }
55
+ }
56
+
57
+ /**
58
+ * The workspace's packages: the folders its patterns name.
59
+ *
60
+ * @param {string} rootDir
61
+ * @returns {string[]} see {@link resolveWorkspacePackages}
62
+ */
63
+ export function workspacePackages(rootDir) {
64
+ return resolveWorkspacePackages(rootDir, readWorkspacePatterns(rootDir).patterns)
65
+ }
66
+
67
+ /**
68
+ * The folders `patterns` name under `rootDir`, as workspace-relative paths in `/`
69
+ * form, each once, in the order of the first pattern that names it — alphabetical
70
+ * within a pattern. A folder a wildcard finds counts only when it holds a
71
+ * package.json; one a pattern names by its own path counts if it exists.
72
+ *
73
+ * @param {string} rootDir
74
+ * @param {string[]} patterns
75
+ * @returns {string[]}
76
+ */
77
+ export function resolveWorkspacePackages(rootDir, patterns) {
78
+ const { include, exclude } = parsePatterns(patterns)
79
+ const seen = new Set()
80
+ const out = []
81
+ for (const pattern of include) {
82
+ const byWildcard = pattern.some((segment) => segment === '**' || hasMagic(segment))
83
+ for (const rel of expand(rootDir, pattern, [], 0, [])) {
84
+ // The root is the workspace itself, never one of its packages.
85
+ if (!rel || seen.has(rel)) continue
86
+ if (byWildcard && !existsSync(join(rootDir, rel, 'package.json'))) continue
87
+ if (exclude.some((ex) => matches(ex, rel.split('/')))) continue
88
+ seen.add(rel)
89
+ out.push(rel)
90
+ }
91
+ }
92
+ return out
93
+ }
94
+
95
+ /**
96
+ * Do `patterns` cover the folder at `relPath` — would it be one of the workspace's
97
+ * packages? Answered from the patterns alone, so it holds for a folder about to be
98
+ * created.
99
+ *
100
+ * @param {string[]} patterns
101
+ * @param {string} relPath - workspace-relative
102
+ * @returns {boolean}
103
+ */
104
+ export function patternsCover(patterns, relPath) {
105
+ const path = normalizePath(relPath)
106
+ if (!path) return false
107
+ const segments = path.split('/')
108
+ const { include, exclude } = parsePatterns(patterns)
109
+ return (
110
+ include.some((p) => matches(p, segments)) &&
111
+ !exclude.some((p) => matches(p, segments))
112
+ )
113
+ }
114
+
115
+ // ─── Patterns ───────────────────────────────────────────────────────────────
116
+
117
+ // `@(…)`, `+(…)`, `!(…)`, `*(…)`, `?(…)` — extended globs, which this does not read.
118
+ const EXTGLOB = /[@+!*?]\(/
119
+ const warned = new Set()
120
+
121
+ /** Positive and negative patterns as folder-name lists, `{a,b}` expanded. */
122
+ function parsePatterns(patterns) {
123
+ const include = []
124
+ const exclude = []
125
+ for (const raw of strings(patterns)) {
126
+ let pattern = raw.trim()
127
+ const negated = pattern.startsWith('!')
128
+ if (negated) pattern = pattern.slice(1)
129
+ if (EXTGLOB.test(pattern)) {
130
+ if (!warned.has(raw)) {
131
+ warned.add(raw)
132
+ process.stderr.write(
133
+ `⚠ uniweb does not read the workspace pattern "${raw}" (extended glob syntax) — ` +
134
+ `list the folders it stands for instead.\n`
135
+ )
136
+ }
137
+ continue
138
+ }
139
+ for (const one of expandBraces(pattern)) {
140
+ const path = normalizePath(one)
141
+ if (path) (negated ? exclude : include).push(path.split('/'))
142
+ }
143
+ }
144
+ return { include, exclude }
145
+ }
146
+
147
+ /** `a/{b,c}/d` → `a/b/d`, `a/c/d`; nested lists expand innermost first. */
148
+ function expandBraces(pattern) {
149
+ const m = /\{([^{}]*)\}/.exec(pattern)
150
+ if (!m) return [pattern]
151
+ const options = m[1].split(',')
152
+ // `{x}` lists nothing to choose between: a literal brace, as in pnpm.
153
+ if (options.length < 2) return [pattern]
154
+ const head = pattern.slice(0, m.index)
155
+ const tail = pattern.slice(m.index + m[0].length)
156
+ return options.flatMap((o) => expandBraces(head + o + tail))
157
+ }
158
+
159
+ /** `./a//b/` → `a/b`; `\` becomes `/`; `.` and `` are the root. */
160
+ function normalizePath(path) {
161
+ let s = String(path).replace(/\\/g, '/').replace(/\/{2,}/g, '/')
162
+ while (s.startsWith('./')) s = s.slice(2)
163
+ s = s.replace(/^\/+/, '').replace(/\/+$/, '')
164
+ return s === '.' ? '' : s
165
+ }
166
+
167
+ const hasMagic = (segment) => /[*?[]/.test(segment)
168
+
169
+ /** Can a wildcard step into this folder? Never `node_modules`, never a dot-folder. */
170
+ const wildcardMayEnter = (name) => !name.startsWith('.') && name !== 'node_modules'
171
+
172
+ const regexCache = new Map()
173
+
174
+ /** One folder-name pattern as a regex: `*`, `?` and `[...]`, everything else literal. */
175
+ function segmentRegex(segment) {
176
+ let re = regexCache.get(segment)
177
+ if (re) return re
178
+ let src = ''
179
+ for (let i = 0; i < segment.length; i++) {
180
+ const c = segment[i]
181
+ if (c === '*') src += '[^/]*'
182
+ else if (c === '?') src += '[^/]'
183
+ else if (c === '[' && segment.indexOf(']', i + 2) > i) {
184
+ const end = segment.indexOf(']', i + 2)
185
+ let body = segment.slice(i + 1, end).replace(/\\/g, '\\\\')
186
+ if (body.startsWith('!')) body = `^${body.slice(1)}`
187
+ src += `[${body}]`
188
+ i = end
189
+ } else src += c.replace(/[.+^$(){}|\\[\]]/g, '\\$&')
190
+ }
191
+ re = new RegExp(`^${src}$`)
192
+ regexCache.set(segment, re)
193
+ return re
194
+ }
195
+
196
+ function segmentMatches(segment, name) {
197
+ if (!hasMagic(segment)) return segment === name
198
+ // A wildcard does not match a dot-folder unless the pattern spells the dot.
199
+ if (name.startsWith('.') && !segment.startsWith('.')) return false
200
+ if (name === 'node_modules') return false
201
+ return segmentRegex(segment).test(name)
202
+ }
203
+
204
+ /** Does the folder-name list `path` match the pattern `pattern`? `**` is any depth. */
205
+ function matches(pattern, path, i = 0, j = 0) {
206
+ if (i === pattern.length) return j === path.length
207
+ if (pattern[i] === '**') {
208
+ for (let k = j; k <= path.length; k++) {
209
+ if (k > j && !wildcardMayEnter(path[k - 1])) break
210
+ if (matches(pattern, path, i + 1, k)) return true
211
+ }
212
+ return false
213
+ }
214
+ if (j === path.length || !segmentMatches(pattern[i], path[j])) return false
215
+ return matches(pattern, path, i + 1, j + 1)
216
+ }
217
+
218
+ /** The folders under `rootDir` that `pattern` names, found on disk. */
219
+ function expand(rootDir, pattern, base, i, out) {
220
+ if (i === pattern.length) {
221
+ out.push(base.join('/'))
222
+ return out
223
+ }
224
+ const segment = pattern[i]
225
+ const here = join(rootDir, ...base)
226
+ if (segment === '**') {
227
+ expand(rootDir, pattern, base, i + 1, out)
228
+ // Real folders only: a symlink back up the tree would never end.
229
+ for (const name of subfolders(here, { followLinks: false })) {
230
+ if (wildcardMayEnter(name)) expand(rootDir, pattern, [...base, name], i, out)
231
+ }
232
+ return out
233
+ }
234
+ if (!hasMagic(segment)) {
235
+ if (segment === '.') return expand(rootDir, pattern, base, i + 1, out)
236
+ if (isFolder(join(here, segment))) expand(rootDir, pattern, [...base, segment], i + 1, out)
237
+ return out
238
+ }
239
+ for (const name of subfolders(here)) {
240
+ if (segmentMatches(segment, name)) expand(rootDir, pattern, [...base, name], i + 1, out)
241
+ }
242
+ return out
243
+ }
244
+
245
+ function subfolders(dir, { followLinks = true } = {}) {
246
+ let entries
247
+ try {
248
+ entries = readdirSync(dir, { withFileTypes: true })
249
+ } catch {
250
+ return []
251
+ }
252
+ return entries
253
+ .filter(
254
+ (e) => e.isDirectory() || (followLinks && e.isSymbolicLink() && isFolder(join(dir, e.name)))
255
+ )
256
+ .map((e) => e.name)
257
+ .sort()
258
+ }
259
+
260
+ function isFolder(path) {
261
+ try {
262
+ return statSync(path).isDirectory()
263
+ } catch {
264
+ return false
265
+ }
266
+ }
267
+
268
+ // ─── Helpers ────────────────────────────────────────────────────────────────
269
+
270
+ export function strings(list) {
271
+ return Array.isArray(list) ? list.filter((v) => typeof v === 'string') : []
272
+ }