@uniweb/build 0.29.1 → 0.30.1

package/src/uwx/collections-project.js

@@ -1,335 +0,0 @@
-// Collections projection — write a folder + its record entities back to the
-// site's `collections/**` source files. The inverse of the collections producer
-// (collections.js + folder.js): the producer reads source records and emits the
-// `@uniweb/folder` entity + one section-keyed `$`-document per record; this takes
-// those documents back and renders them to files.
-//
-// Identity & placement. A record's on-disk home is `(collection, slug)`:
-//   - `slug` and `collection` come from the FOLDER document — each ref leaf is
-//     `{ entry: { model, entity: <uuid> }, path_segment: <slug> }` inside a branch
-//     (its `$children`) whose `path_segment` is the collection name (folder.js
-//     `defaultContents`). The
-//     folder is the authoritative organization on a read (the record document's
-//     own `$id` envelope is not guaranteed to be echoed back), with the record
-//     document's `$id` (`<collection>/<slug>`) used as a fallback when present.
-//   - the collection's directory is resolved from the collections config
-//     (`collections.yml`/`site.yml` `path:`), defaulting to `collections/<name>`.
-//   - an existing local file carrying the same `$uuid` is re-rendered in place;
-//     otherwise a new single-record file is placed at `<slug>.<ext>`, its format
-//     matched to the collection's existing files, else markdown when the Model's
-//     brief has a content body field, else YAML.
-//
-// Field rendering reuses renderEntityDocument (via writeRecordFile) — localized
-// unwrap, date handling, content-body→body are already inverted there.
-//
-// v1 scope / deferred: array-form & BibTeX multi-record files (a pulled record is
-// placed as its own single-record file; merging into an existing array file is a
-// later nicety); deriving an on-disk collection from a deeply NESTED virtual
-// folder org when the record carries no `$id`; and rewriting `collections.yml`'s
-// `folders:` organization + synthesizing declarations for newly-introduced collections
-// (a comment-preserving config rewrite is a separate quality bar). The folder itself
-// carries no `$uuid` — the backend owns it, keyed by the site-content uuid — so
-// nothing is written into `collections.yml` here. Nothing is silently dropped: an
-// unplaceable or unresolvable record is reported.
-
-import { readFileSync, readdirSync, existsSync } from 'node:fs'
-import { join, resolve, extname, basename } from 'node:path'
-import yaml from 'js-yaml'
-import { parseFrontmatter } from './collection-source.js'
-import { writeRecordFile, writeCollectionsConfig, writeSiteConfig } from './project-writer.js'
-import { defaultSchema } from './collections-config.js'
-import { isContentBodyField } from './data-schema.js'
-import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations } from './locale-sync.js'
-import { buildFreeformCollectionPath } from '../i18n/freeform.js'
-
-// Single-record source extensions we scan + place (BibTeX is multi-record → out).
-const EXT_FOR_FORMAT = { md: '.md', yaml: '.yml', json: '.json' }
-
-function formatForExt(ext) {
-  if (ext === '.md') return 'md'
-  if (ext === '.yml' || ext === '.yaml') return 'yaml'
-  if (ext === '.json') return 'json'
-  return null
-}
-
-// Read the `$uuid` declared in a single-record source file, or null (array-form,
-// unreadable, or no `$uuid`). Used to find an existing local file for a record.
-function readFileUuid(filePath, format) {
-  let raw
-  try {
-    raw = readFileSync(filePath, 'utf8')
-  } catch {
-    return null
-  }
-  try {
-    if (format === 'md') return parseFrontmatter(raw).frontmatter?.$uuid ?? null
-    const parsed = format === 'json' ? JSON.parse(raw) : yaml.load(raw)
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
-    return parsed.$uuid ?? null
-  } catch {
-    return null
-  }
-}
-
-/**
- * Find the single-record file in `collectionDir` whose `$uuid` matches, or null.
- * @returns {{ path: string, format: 'md'|'yaml'|'json' }|null}
- */
-export function findRecordFileByUuid(collectionDir, uuid) {
-  if (!uuid || !existsSync(collectionDir)) return null
-  for (const entry of readdirSync(collectionDir)) {
-    if (entry.startsWith('_')) continue
-    const format = formatForExt(extname(entry).toLowerCase())
-    if (!format) continue
-    const path = join(collectionDir, entry)
-    if (readFileUuid(path, format) === uuid) return { path, format }
-  }
-  return null
-}
-
-// The format to give a NEW record file in a collection: match the collection's
-// existing single-record files, else markdown when the Model's brief carries a
-// content body field (so the body has a home), else YAML.
-function defaultFormat(collectionDir, declaration) {
-  if (existsSync(collectionDir)) {
-    for (const entry of readdirSync(collectionDir)) {
-      if (entry.startsWith('_')) continue
-      const format = formatForExt(extname(entry).toLowerCase())
-      if (format) return format
-    }
-  }
-  return briefHasContentBody(declaration) ? 'md' : 'yaml'
-}
-
-// Whether the declaration's brief section declares a content body field — a markup
-// `text` field or a `format: prosemirror` json field (the md-body target).
-function briefHasContentBody(declaration) {
-  const brief = Object.values(declaration?.sections || {}).find((s) => s && s.brief === true)
-  return Object.values(brief?.fields || {}).some((f) => isContentBodyField(f))
-}
-
-// Build `uuid → { collection, slug }` from the folder document's ref leaves. The
-// folder is a self-nesting tree under `contents`, nesting via `$children` (the
-// site-content invariant — folder.js). A leaf sits in a branch whose
-// `path_segment` is the collection; the leaf's `path_segment` is the slug and its
-// `entry` is the entity_ref open form `{ model, entity: <uuid> }`. Nested branches
-// are walked; the collection is the NEAREST enclosing branch segment (correct for
-// the default one-branch-per-collection org; a deeply nested virtual org may
-// differ — see the module header).
-function indexFolder(folderDoc) {
-  const byUuid = new Map()
-  const walk = (nodes, collection) => {
-    for (const node of nodes || []) {
-      if (node?.kind === 'branch') {
-        walk(node.$children, node.path_segment ?? collection)
-      } else if (node?.kind === 'ref' && node.entry) {
-        // `entry` is `{ model, entity: <uuid> }`; tolerate a bare uuid defensively.
-        const uuid = typeof node.entry === 'object' ? node.entry.entity : node.entry
-        if (uuid) byUuid.set(uuid, { collection, slug: node.path_segment })
-      }
-    }
-  }
-  walk(folderDoc?.contents, null)
-  return byUuid
-}
-
-// Resolve a collection's directory from the collections config `path:` (already
-// site-root-relative), defaulting to `collections/<name>`.
-function collectionDirFor(siteRoot, collection, collectionsConfig) {
-  const declPath = collectionsConfig?.declarations?.[collection]?.path
-  return declPath ? resolve(siteRoot, declPath) : join(siteRoot, 'collections', collection)
-}
-
-// Resolve a record's (collection, slug): the folder index first (authoritative on
-// a read), the record document's `$id` (`<collection>/<slug>`) as a fallback.
-function locate(document, folderIndex) {
-  const fromFolder = document.$uuid ? folderIndex.get(document.$uuid) : null
-  if (fromFolder?.collection && fromFolder.slug) return fromFolder
-  if (typeof document.$id === 'string' && document.$id.includes('/')) {
-    const [collection, ...rest] = document.$id.split('/')
-    return { collection, slug: rest.join('/') }
-  }
-  return fromFolder || null
-}
-
-const COLLECTIONS_PREFIX = 'collections/'
-
-// Skip undefined when copying optional fields into a projected declaration.
-function setIf(obj, key, value) {
-  if (value !== undefined) obj[key] = value
-}
-
-// Invert one wire declaration (`collectionsNested` output) back to its file-side
-// shape, and decide its home. Returns `{ target: 'col'|'site', name, decl }`.
-//
-//  - A `path:` under `collections/` is the canonical collections.yml home; the
-//    prefix is stripped (collections.yml `path:` is relative to `collections/`)
-//    and omitted entirely when it equals the default (the collection name).
-//  - A `path:` NOT under `collections/` is a legacy `site.yml::collections` local
-//    path (kept verbatim there — collections.yml can't express it), so it routes
-//    back to site.yml to round-trip faithfully.
-//  - `url:` (remote source) and a bare `source:` object go to collections.yml.
-//  - `schema:` is dropped when it only restates the subfolder-name convention
-//    default, so a terse author file stays terse.
-function declToFileShape(d) {
-  const name = d.name || d.$id
-  const decl = {}
-  let target = 'col'
-
-  const source = d.source || {}
-  if (typeof source.url === 'string') {
-    decl.url = source.url
-  } else if (typeof source.path === 'string') {
-    if (source.path.startsWith(COLLECTIONS_PREFIX)) {
-      const rel = source.path.slice(COLLECTIONS_PREFIX.length)
-      if (rel !== name) decl.path = rel
-    } else {
-      target = 'site'
-      decl.path = source.path
-    }
-  } else if (source && typeof source === 'object' && Object.keys(source).length > 0) {
-    decl.source = source
-  }
-
-  if (d.schema && d.schema !== defaultSchema(name)) decl.schema = d.schema
-  setIf(decl, 'sort', d.sort)
-  setIf(decl, 'where', d.where)
-  setIf(decl, 'limit', d.limit)
-  setIf(decl, 'excerpt', d.excerpt)
-  setIf(decl, 'deferred', d.deferred)
-  // wire `detail_url` → file-side `detailUrl` (the key the producer reads).
-  if (d.detail_url !== undefined) decl.detailUrl = d.detail_url
-  setIf(decl, 'queryable', d.queryable)
-
-  return { target, name, decl }
-}
-
-/**
- * Project the collection DECLARATIONS carried in a site-content document
- * (`document.collections`, the inverse of site.js `collectionsNested`) back to
- * their config home — `collections/collections.yml::collections` for the canonical
- * file-based + remote sources, `site.yml::collections` for legacy local paths
- * outside `collections/`. Sibling keys (`$uuid`, `sync`, `folders`, untouched
- * collections) are preserved via the shallow-merge writers. The record FILES and
- * the folder `$uuid` are written elsewhere (collectionsToProject); this is only
- * the declaration config.
- *
- * Idempotent and non-destructive: with no declarations it writes nothing (so a
- * pull that doesn't carry collections never clobbers a hand-authored file).
- *
- * @param {object} params
- * @param {object} params.document - a site-content `$`-document (`{ collections }`)
- * @param {string} params.siteRoot
- * @returns {{ collections?: 'updated'|'unchanged', site?: 'updated'|'unchanged' }}
- */
-export function declarationsToCollectionsYml({ document, siteRoot }) {
-  const decls = Array.isArray(document?.collections) ? document.collections : []
-  const report = {}
-  if (decls.length === 0) return report
-
-  const colCollections = {}
-  const siteCollections = {}
-  for (const d of decls) {
-    const { target, name, decl } = declToFileShape(d)
-    if (!name) continue
-    if (target === 'site') siteCollections[name] = decl
-    else colCollections[name] = decl
-  }
-
-  if (Object.keys(colCollections).length > 0) {
-    report.collections = writeCollectionsConfig(siteRoot, { collections: colCollections })
-  }
-  if (Object.keys(siteCollections).length > 0) {
-    report.site = writeSiteConfig(siteRoot, { collections: siteCollections })
-  }
-  return report
-}
-
-/**
- * Project a pulled folder + its record entities to `collections/**` files.
- *
- * @param {object} params
- * @param {object} params.folderDoc   - the `@uniweb/folder` document `{ contents }` (no `$uuid`)
- * @param {object[]} params.recordDocs - record `$`-documents `{ $uuid?, $id?, $model, <brief> }`
- * @param {string} params.siteRoot
- * @param {object} params.opts
- * @param {(modelName: string) => object|null|undefined} params.opts.resolveDeclaration
- *        - resolve a Model's data-schema declaration by name (`$model`).
- * @param {object} [params.opts.collectionsConfig] - from resolveCollectionsConfig
- *        (for `path:` overrides); optional — defaults to `collections/<name>`.
- * @param {string} [params.opts.sourceLocale]
- * @returns {{ updated: string[], placed: string[], unchanged: string[], skipped: object[], warnings: string[], locales: object }}
- */
-export function collectionsToProject({ folderDoc, recordDocs = [], siteRoot, opts = {} }) {
-  const { resolveDeclaration, collectionsConfig, sourceLocale = 'en' } = opts
-  if (typeof resolveDeclaration !== 'function') {
-    throw new Error('uwx/collections-project: opts.resolveDeclaration(modelName) is required')
-  }
-
-  const folderIndex = indexFolder(folderDoc)
-  // Captures target-locale translations of localized record fields: SCALARs →
-  // locales/collections/{locale}.json (structural maps too), and a prosemirror
-  // BODY's free-form per-locale override → locales/freeform/{locale}/collections/.
-  const collector = createTranslationCollector(sourceLocale)
-  const updated = []
-  const placed = []
-  const unchanged = []
-  const skipped = []
-  const warnings = []
-
-  for (const document of recordDocs) {
-    const where = locate(document, folderIndex)
-    if (!where?.collection || !where?.slug) {
-      skipped.push({ uuid: document.$uuid, reason: 'no collection/slug (not in folder, no $id)' })
-      continue
-    }
-    const declaration = document.$model ? resolveDeclaration(document.$model) : null
-    if (!declaration) {
-      skipped.push({ uuid: document.$uuid, slug: where.slug, reason: `unresolved model ${document.$model || '(none)'}` })
-      continue
-    }
-
-    const collectionDir = collectionDirFor(siteRoot, where.collection, collectionsConfig)
-    const existing = document.$uuid ? findRecordFileByUuid(collectionDir, document.$uuid) : null
-
-    let filePath
-    let format
-    let isNew
-    if (existing) {
-      filePath = existing.path
-      format = existing.format
-      isNew = false
-    } else {
-      format = defaultFormat(collectionDir, declaration)
-      filePath = join(collectionDir, where.slug + EXT_FOR_FORMAT[format])
-      isNew = true
-    }
-
-    // The free-form home for this record's content body (locale-independent); a
-    // target-locale full-doc body is written under locales/freeform/{locale}/here.
-    const freeformRelPath = buildFreeformCollectionPath(where.collection, where.slug)
-
-    let status
-    try {
-      status = writeRecordFile({ filePath, document, declaration, format, sourceLocale, collector, freeformRelPath })
-    } catch (err) {
-      warnings.push(`${where.collection}/${where.slug}: ${err.message}`)
-      continue
-    }
-    if (status === 'unchanged') unchanged.push(filePath)
-    else if (isNew) placed.push(filePath)
-    else updated.push(filePath)
-  }
-
-  // The folder carries no `$uuid` we persist — the backend owns the site's folder,
-  // keyed by the site-content uuid (the folder pull lane is keyed by `site.yml::$uuid`).
-  // The virtual `folders:` org + declarations for newly-introduced collections are a
-  // later, comment-sensitive rewrite.
-
-  // Flush localized record-field translations to locales/collections/{locale}.json,
-  // and any prosemirror free-form body overrides to locales/freeform/{locale}/.
-  const locales = writeLocaleTranslations(siteRoot, collector.byLocale, 'collections')
-  const freeform = writeFreeformTranslations(siteRoot, collector.freeformPending)
-
-  return { updated, placed, unchanged, skipped, warnings, locales, freeform }
-}