@uniweb/build 1.3.7 → 1.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.3.7",
+  "version": "1.3.8",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -56,12 +56,12 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/content-writer": "~1.1.2",
     "@uniweb/content-reader": "~1.4.0",
+    "@uniweb/content-writer": "~1.1.2",
     "@uniweb/projections": "~1.1.1",
+    "@uniweb/schemas": "~1.3.1",
     "@uniweb/semantic-parser": "~1.8.1",
-    "@uniweb/theming": "~1.2.0",
-    "@uniweb/schemas": "~1.3.1"
+    "@uniweb/theming": "~1.2.0"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "~1.1.4"
@@ -73,8 +73,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "~1.1.4",
-    "@uniweb/core": "~1.2.2"
+    "@uniweb/core": "~1.2.2",
+    "@uniweb/runtime": "~1.1.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/site/entity-pool.js

@@ -53,8 +53,7 @@
 // there is no population to carry): a leftover `entities/` beside `records/` would
 // otherwise hold records nothing reads, silently.
 
-import { readdir } from 'node:fs/promises'
-import { existsSync, readFileSync, statSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { join, extname, basename, resolve } from 'node:path'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
@@ -263,6 +262,17 @@ export function poolPathReadings(dirs) {
  *   leaves the backend's folder alone for a site with no records directory.
  */
 export async function readEntityPool(siteRoot, opts = {}) {
+  return readEntityPoolSync(siteRoot, opts)
+}
+
+/**
+ * `readEntityPool`, for a caller that cannot wait — the pull's projection, which asks what a
+ * `folder.yml` already says (`records-project.js`). One walk, which the async form returns.
+ *
+ * @param {string} siteRoot
+ * @param {object} [opts] - as `readEntityPool`'s
+ */
+export function readEntityPoolSync(siteRoot, opts = {}) {
   let rel
   if (opts.dir) {
     rel = String(opts.dir).replace(/\/+$/, '')
@@ -280,10 +290,10 @@ export async function readEntityPool(siteRoot, opts = {}) {
   // A file record is named by its stem, so two files of one stem cannot both be one.
   const fileStems = new Map()
 
-  const walk = async (dir, dirs) => {
+  const walk = (dir, dirs) => {
     let listing
     try {
-      listing = await readdir(dir, { withFileTypes: true })
+      listing = readdirSync(dir, { withFileTypes: true })
     } catch {
       return
     }
@@ -304,7 +314,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
           )
           continue
         }
-        await walk(full, [...dirs, e.name])
+        walk(full, [...dirs, e.name])
         continue
       }
       if (!e.isFile()) continue
@@ -356,7 +366,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
     }
   }
 
-  await walk(base, [])
+  walk(base, [])
   return { entities, errors, exists: true, dir: rel }
 }
 

package/src/uwx/backfill.js

@@ -296,7 +296,13 @@ export function renderEntityDocument({ document, declaration, format, sourceLoca
   if (document?.$disabled === true) record.draft = true
 
   if (format === 'json') return JSON.stringify(record, null, 2) + '\n'
-  if (format === 'md') return `---\n${yaml.dump(record)}---\n${dec.body}`
+  if (format === 'md') {
+    // ⭐ Written as a section is (`project-writer.js::assembleSection`): a blank line after the front
+    // matter, and a final newline. ⛔ Until 2026-10-17 it had neither, so a pull that rewrote an
+    // edited record took both out of the author's file.
+    const body = String(dec.body ?? '').replace(/^(?:[ \t]*\n)+/, '').replace(/\s+$/, '')
+    return `---\n${yaml.dump(record)}---\n${body ? `\n${body}\n` : ''}`
+  }
   return yaml.dump(record) // yaml / yaml
 }
 

package/src/uwx/project-writer.js

@@ -418,14 +418,16 @@ function restates(authored, decl) {
  * (`records/`, or wherever `site.yml::paths.records` puts it), as a LIST.
  *
  * ⛔ A FULL WRITE, NOT A MERGE, and that is the one place this differs from every
- * other projected config. The file mirrors the folder's sub-folders: concrete refs
- * on both sides, nothing to invert, so a pull is a mirror rather than an update.
- * There is also nothing a shallow merge could mean here — the file is a sequence,
- * and merging two lists either duplicates entries or silently drops them.
+ * other projected config: the file is a sequence, and merging two lists either
+ * duplicates entries or silently drops them.
  *
- * The caller decides whether there is anything to write: a folder with no
- * sub-folders is no file at all (`folderToFolderYml` removes it), since missing and
- * empty mean the same. ⚠️ *Until 2026-09-21 this said an empty file was destructive
+ * The caller decides whether there is anything to write: a file that already says
+ * what the pulled folder says — its patterns included — is left alone
+ * (`records-project.js::organizesAlike`), and a folder with no sub-folders is no file
+ * at all (`folderToFolderYml` removes it), since missing and empty mean the same.
+ * ⛔ *Until 2026-10-17 this called the file a mirror — "concrete refs on both sides,
+ * nothing to invert" — and every pull wrote the folder's paths over a developer's
+ * patterns.* ⚠️ *Until 2026-09-21 this said an empty file was destructive
  * on the next push; that stopped being true when the directory, not this file,
  * became what decides which records the folder holds.*
  *

package/src/uwx/records-project.js

@@ -43,8 +43,9 @@ import { parseFrontmatter } from './entity-source.js'
 import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './project-writer.js'
 import { foundationDataSchemas, foundationSchemaJson, QUERIES_YML_RELPATH } from './queries-config.js'
 import { dataKeyTypes } from './data-key-types.js'
-import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
-import { folderYmlPath } from '../site/records-config.js'
+import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir, readEntityPoolSync } from '../site/entity-pool.js'
+import { folderYmlPath, resolveFolder } from '../site/records-config.js'
+import { canonicalJson } from './same-content.js'
 import { contentBodyTarget } from './record-layout.js'
 import { qualifyRef } from '@uniweb/schemas/refs'
 import { unresolveSelfScope, ownSchemaNames, refuseOrgOption } from './self-scope.js'
@@ -501,9 +502,14 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
  * Project a pulled `@uniweb/folder` document back to `folder.yml` in the records
  * directory (`records/folder.yml`, or under `site.yml::paths.records`).
  *
- * ⭐ THE FOLDER ROUND-TRIPS TRIVIALLY, and that is by design rather than luck:
- * `folder.yml` holds concrete paths on both sides, so there is nothing to invert.
- * The old shape put QUERY MACROS in the folder — a virtual `folders:` tree naming
+ * ⭐ A FILE THAT SAYS WHAT THE PULLED FOLDER SAYS IS LEFT AS WRITTEN — its patterns
+ * (`member/*.md`), its comments, its order (`organizesAlike`). Otherwise the folder
+ * is written as the paths the backend's folder places, which is what it says.
+ * ⛔ *This read "the folder round-trips trivially: `folder.yml` holds concrete paths
+ * on both sides, so there is nothing to invert" until 2026-10-17 — read as "the file
+ * holds no patterns", which it does — and every pull with a folder wrote its paths
+ * over the developer's patterns: a record added afterwards fell outside them.* The
+ * old shape put QUERY MACROS in the folder — a virtual `folders:` tree naming
  * collections — and inverting a macro is not possible in general. Taking queries
  * out of the folder is what dissolved that.
  *
@@ -600,6 +606,16 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
 
   const entries = walk(folderDoc.contents, false)
   if (unplaceable) return { status: 'skipped', entries: [], warnings, file }
+  if (existsSync(abs) && organizesAlike({ abs, entries, siteRoot, poolPathByUuid })) {
+    return { status: 'unchanged', entries, warnings, file }
+  }
+  // Said when it replaces a developer's pattern: a record they add from here is placed by nothing.
+  if (existsSync(abs) && holdsPattern(abs)) {
+    warnings.push(
+      `${file}: the folder no longer places its records as its patterns say, so it was written as their ` +
+        `paths. A record you add from here sits at the top of the folder until ${file} places it.`
+    )
+  }
   if (entries.length === 0) {
     if (!existsSync(abs)) return { status: 'unchanged', entries, warnings, file }
     unlinkSync(abs)
@@ -608,6 +624,67 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
   return { status: writeRecordsConfig(siteRoot, entries), entries, warnings, file }
 }
 
+/**
+ * Does the `folder.yml` on disk say what the pulled folder says — read by the rule a push reads it
+ * by (`resolveFolder`), over the records directory as this pull left it?
+ *
+ * ⭐ About the records the backend's folder holds, every word: the folders, by name, label and tags,
+ * in order; and each record's folder, its tags and label, and its place among the others. Records
+ * the backend does not hold yet — a file the developer added and has not pushed — are theirs, so a
+ * pattern placing one is not a difference; nor is a folder holding only those. So `member/*.md` is
+ * kept while it places exactly the members the backend's folder has there, and goes on placing the
+ * next one the developer adds.
+ *
+ * @returns {boolean}
+ */
+function organizesAlike({ abs, entries, siteRoot, poolPathByUuid }) {
+  let authored
+  try {
+    authored = yaml.load(readFileSync(abs, 'utf8'), YAML_OPTIONS)
+  } catch {
+    return false
+  }
+  if (!Array.isArray(authored)) return false
+  const pool = readEntityPoolSync(siteRoot).entities
+  const pulled = new Set(poolPathByUuid.values())
+  const held = new Set(pool.filter((e) => pulled.has(e.poolPath)).map((e) => e.id))
+  const mine = resolveFolder(authored, pool)
+  const theirs = resolveFolder(entries, pool)
+  if (mine.errors.length || theirs.errors.length) return false
+  const theirFolders = new Set()
+  const said = (n) => ({ ...(n.label != null ? { label: n.label } : {}), ...(n.tags ? { tags: n.tags } : {}) })
+  // A tree as it reads for the held records. `keep(path, holds)` decides whether a folder stays.
+  const shape = (nodes, at, keep) =>
+    (nodes || []).flatMap((n) => {
+      if (n.kind === 'ref') return held.has(n.$entityId) ? [{ record: n.$entityId, ...said(n) }] : []
+      if (n.kind !== 'branch') return []
+      const path = [...at, n.name]
+      const records = shape(n.$children, path, keep)
+      return keep(path.join('/'), records.length > 0) ? [{ folder: n.name, ...said(n), records }] : []
+    })
+  // Every folder the backend has stays, empty or not; one of the file's stays when it holds a held
+  // record or the backend has it too — else it is the developer's, not pushed yet.
+  const theirShape = shape(theirs.nodes, [], (path) => (theirFolders.add(path), true))
+  const myShape = shape(mine.nodes, [], (path, holds) => holds || theirFolders.has(path))
+  return canonicalJson(myShape) === canonicalJson(theirShape)
+}
+
+// Does the `folder.yml` on disk place records by a pattern (`member/*.md`) anywhere?
+function holdsPattern(abs) {
+  let authored
+  try {
+    authored = yaml.load(readFileSync(abs, 'utf8'), YAML_OPTIONS)
+  } catch {
+    return false
+  }
+  const has = (entries) =>
+    (Array.isArray(entries) ? entries : []).some((entry) => {
+      const path = typeof entry === 'string' ? entry : entry?.path
+      return (typeof path === 'string' && /[*?]/.test(path)) || has(entry?.records)
+    })
+  return has(authored)
+}
+
 /**
  * Project a pulled folder + its record entities to `records/**` files.
  *