@uniweb/build 0.29.0 → 0.30.0

package/src/uwx/folder.js

@@ -1,20 +1,28 @@
-// Build the one `@uniweb/folder` entity that organizes a site's collection records.
+// Build the one `@uniweb/folder` entity that organizes a site's records.
 //
-// A site sync carries the site-content entity, the collection-record entities, and
-// — when the site has collections — ONE `@uniweb/folder` entity describing how those
-// records are organized. `@uniweb/folder` is a normal section-keyed entity (the
-// "structured content all the way down" invariant): its document is `{ info?, contents }`.
+// A site sync carries the site-content entity, the record entities, and — when the
+// site has records — ONE `@uniweb/folder` entity describing how they are
+// organized. `@uniweb/folder` is a normal section-keyed entity (the "structured
+// content all the way down" invariant): its document is `{ info?, contents }`.
 //   - `contents` is the self-nesting tree (an array), nesting via `$children` — the
 //     same mechanism site-content pages/sections use. Each node holds REFERENCES,
 //     never content:
 //       - a LEAF references one record entity: `{ kind: 'ref', path_segment, ... }`
 //         with `entry: <uuid>` once the record was minted (back-filled into its file),
-//         or `$ref: "<collection>/<slug>"` while brand-new (resolved within this payload).
+//         or `$ref: "<id>"` while brand-new (resolved within this payload).
 //       - a BRANCH is a sub-folder: `{ kind: 'branch', path_segment, name?, $children }`.
 //
-// Organization comes from `collections.yml::folders` (a VIRTUAL tree, decoupled from
-// the on-disk layout) when present; otherwise the default is one branch per
-// collection, its records as leaves — mirroring the `collections/` subfolders.
+// ⭐ THE ORGANIZATION IS AUTHORED, IN `records.yml`, AND IT IS THE ONLY SOURCE.
+// It used to be DERIVED — one branch per collection, mirroring the `collections/`
+// subfolders, with an optional `collections.yml::folders` virtual tree layered
+// over it. Both are gone, and the difference is the point: a folder is a thing
+// the author states, not a shadow of a directory layout. `records.yml` also
+// decides WHAT syncs at all, since listing an entity is what makes it a record.
+//
+// ⛔ SO THERE IS NO DEFAULT. A site with no `records.yml` has no folder and syncs
+// no records — which is the model's `missing ⇒ inert` ruling, not an empty folder.
+// Do not reintroduce a fallback grouping: it would resurrect exactly the
+// three-jobs-in-one-directory conflation the layout was changed to remove.
 //
 // The folder carries NO `$uuid` of its own: the backend owns the site's
 // `@uniweb/folder` and resolves it from the site-content uuid (the folder sync lane
@@ -23,11 +31,12 @@
 export const FOLDER_MODEL_NAME = '@uniweb/folder'
 export const FOLDER_ENTITY_KEY = '@folder'
 
-// One record → a `ref` leaf. The folder's `contents` field is polymorphic (it can
-// reference any Model), so the ref uses the entity_ref OPEN form `{ model, entity }`
-// — not a bare uuid (a bare uuid is only valid when the field pins a single model).
-// Known uuid → `entry: { model, entity: <uuid> }`; brand-new → `$ref` handle
-// (resolved within this payload to the minted entity).
+// Point one authored leaf at the record entity it names. The folder's `contents`
+// field is polymorphic (it can reference any Model), so the ref uses the
+// entity_ref OPEN form `{ model, entity }` — not a bare uuid (a bare uuid is only
+// valid when the field pins a single model). Known uuid → `entry: { model, entity
+// }`; brand-new → `$ref` handle (resolved within this payload to the minted
+// entity).
 //
 // TODO: the sync lane is uuid-keyed, so `model` should be the resolved Model UUID;
 // it currently carries the Model NAME (e.g. `@std/article`). Wire the name→uuid
@@ -35,68 +44,42 @@ export const FOLDER_ENTITY_KEY = '@folder'
 function refLeaf(entity) {
   const leaf = { kind: 'ref', path_segment: entity.slug }
   if (entity.uuid) leaf.entry = { model: entity.model, entity: entity.uuid }
-  else leaf.$ref = entity.id // the `<collection>/<slug>` payload-local handle
+  else leaf.$ref = entity.id // the payload-local handle
   return leaf
 }
 
-// Group record entities by their collection (the `<collection>` prefix of `$id`).
-function groupByCollection(recordEntities) {
-  const groups = new Map()
-  for (const e of recordEntities) {
-    const collection = e.collection ?? String(e.id).split('/')[0]
-    if (!groups.has(collection)) groups.set(collection, [])
-    groups.get(collection).push(e)
-  }
-  return groups
-}
-
-// Default org: one branch per collection (declaration order), records as leaves.
-function defaultContents(groups) {
-  const contents = []
-  for (const [collection, records] of groups) {
-    contents.push({
-      kind: 'branch',
-      path_segment: collection,
-      $children: records.map(refLeaf),
-    })
-  }
-  return contents
-}
-
-// Virtual org from `collections.yml::folders`. Each node is either a collection
-// NAME (string — expands to that collection's record leaves under a branch named
-// after it) or a `{ segment, label?, entries: [...] }` branch (recursively).
-function virtualContents(folders, groups) {
-  const buildNode = (node) => {
-    if (typeof node === 'string') {
-      const records = groups.get(node) || []
-      return {
-        kind: 'branch',
-        path_segment: node,
-        $children: records.map(refLeaf),
-      }
+/**
+ * Turn the resolved `records.yml` tree into folder `contents`.
+ *
+ * ⛔ A LEAF WHOSE ENTITY IS MISSING IS DROPPED AND REPORTED, never emitted empty.
+ * A `ref` with neither `entry` nor `$ref` is a placement pointing at nothing —
+ * the backend cannot resolve it, and the failure would surface there rather than
+ * here, as somebody else's error.
+ *
+ * @param {Array} nodes - from `site/records-config.js::resolveFolder`
+ * @param {Map<string, object>} byEntityId - record entities, keyed by pool id
+ * @param {string[]} missing - collects ids that resolved to no entity
+ */
+function contentsFromNodes(nodes, byEntityId, missing) {
+  const out = []
+  for (const node of nodes || []) {
+    if (node.kind === 'branch') {
+      const branch = { kind: 'branch', path_segment: node.path_segment }
+      if (node.name !== undefined) branch.name = node.name
+      branch.$children = contentsFromNodes(node.$children, byEntityId, missing)
+      out.push(branch)
+      continue
     }
-    if (node && typeof node === 'object') {
-      const segment = node.segment ?? node.path_segment
-      const branch = { kind: 'branch', path_segment: segment }
-      if (node.label !== undefined) branch.name = node.label
-      const children = Array.isArray(node.entries) ? node.entries : []
-      branch.$children = children.flatMap((child) => {
-        // A bare collection name inside `entries:` expands to its leaves directly
-        // (so the records sit in THIS branch, not a nested one).
-        if (typeof child === 'string' && groups.has(child)) {
-          return (groups.get(child) || []).map(refLeaf)
-        }
-        return [buildNode(child)]
-      })
-      return branch
+    const entity = byEntityId.get(node.$entityId)
+    if (!entity) {
+      missing.push(node.$entityId)
+      continue
     }
-    return null
+    out.push(refLeaf(entity))
   }
-  return folders.map(buildNode).filter(Boolean)
+  return out
 }
 
-
 /**
  * Walk a folder document's `contents` tree, visiting every item with the
  * slash-joined `path_segment` chain that addresses it.
@@ -167,24 +150,48 @@ export function stampFolderItemUuids(doc, pathToUuid = {}) {
 }
 
 /**
- * Build the `@uniweb/folder` entity descriptor, or null when there are no records.
+ * Build the `@uniweb/folder` entity descriptor, or null when the folder is empty.
  *
  * Carries no `$uuid`: the backend owns the site's folder (resolved from the
  * site-content uuid), so the framework never mints, holds, or sends a folder uuid.
  *
  * @param {object} params
- * @param {object[]} params.recordEntities - the collection-record entities (full
- *        set, BEFORE send-only-changed filtering), each `{ id, uuid, slug, collection? }`
- * @param {Array|null} [params.folders] - `collections.yml::folders` virtual org
+ * @param {object[]} params.recordEntities - the record entities (full set, BEFORE
+ *        send-only-changed filtering), each `{ id, uuid, slug, model }`
+ * @param {Array} params.folderNodes - the resolved `records.yml` tree
+ * @param {boolean} [params.declared] - whether `records.yml` EXISTS. See below.
  * @param {Record<string,string>} [params.itemUuids] - path → `$uuid`, harvested
  *        from the folder document a previous push returned. Absent on a first
  *        push, where every item is genuinely new.
- * @returns {{ id, uuid, model, file, document, collection: '@folder' }|null}
+ * @returns {{ id, uuid, model, file, document, warnings }|null}
  */
-export function buildFolderEntity({ recordEntities, folders = null, itemUuids = null }) {
-  if (!Array.isArray(recordEntities) || recordEntities.length === 0) return null
-  const groups = groupByCollection(recordEntities)
-  const contents = folders ? virtualContents(folders, groups) : defaultContents(groups)
+export function buildFolderEntity({ recordEntities, folderNodes = [], declared, itemUuids = null }) {
+  // ⛔ `missing` AND `empty` ARE DIFFERENT, AND THE ASYMMETRY IS DELIBERATE.
+  //
+  //   no records.yml       → null. INERT: nothing is sent, and the server's
+  //                          folder is left exactly as it is.
+  //   records.yml, empty   → a folder with `contents: []`. DESTRUCTIVE: it says
+  //                          the folder holds nothing, so the backend removes
+  //                          what is there.
+  //
+  // ⭐ The safe state is the ABSENCE of a file and the destructive act requires
+  // affirmatively CREATING one — so a live folder cannot be wiped by deleting
+  // something. ⛔ Do not "simplify" these into one behaviour to avoid the
+  // placeholder hazard (an empty file created meaning to fill it in): that would
+  // delete a capability to avoid writing a prompt. The CLI asks, with a count.
+  const empty = !Array.isArray(folderNodes) || folderNodes.length === 0
+  if (empty && !declared) return null
+
+  const byEntityId = new Map()
+  for (const e of recordEntities || []) byEntityId.set(e.id, e)
+
+  const missing = []
+  const contents = contentsFromNodes(folderNodes, byEntityId, missing)
+  const warnings = missing.map(
+    (id) =>
+      `folder: "${id}" is placed in records.yml but produced no record entity — ` +
+      `the placement was dropped rather than sent pointing at nothing.`
+  )
 
   const document = {
     $id: FOLDER_ENTITY_KEY,
@@ -202,5 +209,6 @@ export function buildFolderEntity({ recordEntities, folders = null, itemUuids =
     model: FOLDER_MODEL_NAME,
     file: 'entities/folder.json',
     document,
+    warnings,
   }
 }

package/src/uwx/index.js

@@ -50,20 +50,21 @@ export {
   isSiteRelativeExtensionUrl,
 } from './site.js'
 export {
-  resolveCollectionsConfig,
-  collectionsYmlPath,
-  COLLECTIONS_YML_RELPATH,
-} from './collections-config.js'
+  resolveQueriesConfig,
+  queriesYmlPath,
+  QUERIES_YML_RELPATH,
+} from './queries-config.js'
 export { upsertYamlScalar } from './yaml-upsert.js'
 export { buildFolderEntity,
   collectFolderItemUuids,
   stampFolderItemUuids
 } from './folder.js'
 export {
-  collectionsToProject,
-  declarationsToCollectionsYml,
+  recordsToProject,
+  declarationsToQueriesYml,
+  folderToRecordsYml,
   findRecordFileByUuid,
-} from './collections-project.js'
+} from './records-project.js'
 export {
   siteInfoToConfig,
   sectionRecordToFile,
@@ -90,16 +91,36 @@ export {
   collectSiteUnits,
   walkSiteUnits,
   collectUnitUuids,
+  collectQueryUuids,
   stampUnitUuids,
 } from './site-diff.js'
 export {
-  collectionRecordsToEntities,
-  buildCollectionEntities,
+  recordsToEntities,
+  buildRecordEntities,
   filterChanged,
-  emitCollectionSyncPackage,
+  emitRecordSyncPackage,
   entityContentHash,
-} from './collections.js'
-export { readCollectionRecords, parseFrontmatter } from './collection-source.js'
+} from './records.js'
+export { readEntityFile, parseFrontmatter } from './entity-source.js'
+
+// The folder's own vocabulary, so a verb can ask what `records.yml` SAYS without
+// re-reading or re-parsing it. ⛔ Note the allowlist: an export added to
+// `site/records-config.js` does not reach a caller until it is named here.
+// The pool's grammar — a schema ref to its directory and back. ⛔ Allowlist: an
+// export added to `site/entity-pool.js` does not reach a caller until it is here.
+export {
+  poolDirsForSchema,
+  schemaForPoolDirs,
+  ENTITIES_DIR,
+} from '../site/entity-pool.js'
+
+export {
+  readRecordsConfig,
+  RECORDS_YML_RELPATH,
+  FOLDER_MISSING,
+  FOLDER_EMPTY,
+  FOLDER_DECLARED,
+} from '../site/records-config.js'
 export {
   findRecordFile,
   backfillUuid,

package/src/uwx/locale-sync.js

@@ -28,8 +28,8 @@ const FREEFORM_MANIFEST = '.manifest.json'
 
 // The `locales/` directory for a site (the i18n localesDir default; `paths` can
 // override it, but the default is `locales` — keep this the single place to change).
-// `subdir` scopes a lane: '' → site-content (locales/), 'collections' → collection
-// records (locales/collections/), matching the i18n manifest layout.
+// `subdir` scopes a lane: '' → site-content (locales/), 'records' → record
+// translations (locales/records/), matching the i18n manifest layout.
 export function localesDir(siteRoot, subdir = '') {
   return subdir ? join(siteRoot, 'locales', subdir) : join(siteRoot, 'locales')
 }

package/src/uwx/project-writer.js

@@ -15,9 +15,10 @@ import { join, resolve, dirname } from 'node:path'
 import { randomBytes } from 'node:crypto'
 import yaml from 'js-yaml'
 import { proseMirrorToMarkdown, serializeFrontmatter } from '@uniweb/content-writer'
-import { parseFrontmatter } from './collection-source.js'
+import { parseFrontmatter } from './entity-source.js'
 import { renderEntityDocument } from './backfill.js'
-import { collectionsYmlPath } from './collections-config.js'
+import { queriesYmlPath } from './queries-config.js'
+import { recordsYmlPath } from '../site/records-config.js'
 
 // Frontmatter keys that belong to the CCA framework / the developer's local
 // authoring, not to externally-editable params. On a section write an existing
@@ -259,16 +260,41 @@ export function writeMergedYaml(filePath, projected, managedKeys) {
 }
 
 /**
- * Merge `config` into `collections/collections.yml` (shallow). Preserves sibling
- * keys the update doesn't touch — the folder `$uuid`, `sync`, `folders`, and any
- * collections not in the incoming set. A `collections:` object value is merged one
- * level deep (per-collection), so each declaration is replaced wholesale while
- * untouched collections stay. Same key-preserving (comment-dropping) bar as
- * `writeSiteConfig`.
+ * Merge `queries` into `queries.yml` (shallow). Preserves queries not in the
+ * incoming set; each incoming one is replaced wholesale. Same key-preserving
+ * (comment-dropping) bar as `writeSiteConfig`.
+ *
+ * ⛔ `queries.yml` IS THE MAP — there is no root key, so `queries` is passed bare.
+ * The predecessor wrote `{ collections: {...} }` into `collections.yml`; handing
+ * that same wrapper to this file would produce a query NAMED `collections`, which
+ * is a silent corruption rather than an error. The one caller was updated with it.
+ *
+ * @param {string} siteRoot
+ * @param {object} queries - `{ [name]: decl }`, bare
+ * @returns {'updated'|'unchanged'}
+ */
+export function writeQueriesConfig(siteRoot, queries) {
+  return mergeYamlConfig(queriesYmlPath(siteRoot), queries)
+}
+
+/**
+ * Write `records.yml` — the site's folder, as a LIST.
+ *
+ * ⛔ A FULL WRITE, NOT A MERGE, and that is the one place this differs from every
+ * other projected config. `records.yml` IS the folder: 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.
+ *
+ * ⚠️ WHICH IS WHY AN EMPTY LIST IS NOT WRITTEN AS A FILE-WITH-NOTHING BY ACCIDENT.
+ * An empty `records.yml` is DESTRUCTIVE on the next push — it says the folder holds
+ * nothing. A pull that carried no folder must leave the file alone, so the caller
+ * decides, and this only writes what it was actually given.
+ *
  * @returns {'updated'|'unchanged'}
  */
-export function writeCollectionsConfig(siteRoot, config) {
-  return mergeYamlConfig(collectionsYmlPath(siteRoot), config)
+export function writeRecordsConfig(siteRoot, entries) {
+  return writeYamlFile(recordsYmlPath(siteRoot), entries)
 }
 
 /**

package/src/uwx/queries-config.js

@@ -0,0 +1,11 @@
+// Moved to `../site/queries-config.js` — a site's collection declarations are
+// a site-build question first, and keeping the resolver here meant the build could
+// not reach it and answered differently. Re-exported so no caller moved.
+export {
+  resolveQueriesConfig,
+  queriesYmlPath,
+  defaultSchema,
+  deferredFromSchema,
+  foundationDataSchemas,
+  QUERIES_YML_RELPATH,
+} from '../site/queries-config.js'