@uniweb/build 0.29.0 → 0.30.0

package/src/site/collections-config.js

@@ -1,260 +0,0 @@
-// A site's collection declarations — the ONE resolution, for every lane.
-//
-// ⛔ THIS LIVED IN `uwx/` AND THE SITE BUILD COULD NOT SEE IT, so the site build
-// used `site.yml::collections` directly and the two disagreed. Measured before the
-// move: a collection declared only in `collections/collections.yml` resolved here
-// and was INVISIBLE to the build — no `dist/data/<name>.json`, so `data: <name>`
-// delivered nothing while sync pushed it fine. Declared in both files, the build
-// took `site.yml`'s values and sync took `collections.yml`'s, so an author writing
-// `sort: date desc` here got `date asc` baked into the static file.
-//
-// The broken case was the one the public docs recommend. See
-// `kb/framework/plans/one-collections-config.md`.
-//
-// Resolve a site's collection configuration from the (optional, local-first)
-// `collections/collections.yml`, layered over the legacy `site.yml::collections`
-// and the zero-config subfolder-name convention.
-//
-// `collections.yml` is the co-located home for FILE-BASED collection declarations
-// (it sits with the data it describes). It is useful with NO backend at all — it
-// maps each subfolder to a data schema, declares query/display config, and can lay
-// out a VIRTUAL folder organization decoupled from the on-disk layout. (Sync holds no
-// folder uuid here — the backend owns the site's `@uniweb/folder`, keyed by the
-// site-content uuid.)
-//
-// Precedence (per-collection, per-key): collections.yml  >  site.yml::collections.
-// `site.yml::collections` stays valid for remote `url:` sources and back-compat.
-// When neither declares a schema, the subfolder-name convention fills it
-// (`articles` → `@/article`). Absent the file entirely, behavior is unchanged.
-
-import { join } from 'node:path'
-import { existsSync, readFileSync } from 'node:fs'
-import { briefFields, flatRecordFields } from '@uniweb/schemas/conform'
-import { detectFoundationType } from './foundation-ref.js'
-import { readFile } from 'node:fs/promises'
-import yaml from 'js-yaml'
-
-// Read its own YAML rather than importing the site build's helper. That import
-// pointed the wrong way — a config resolver reaching into the collector that
-// consumes it — and became a cycle the moment the site build started calling
-// this. Four lines beats a dependency between two modules that should not know
-// about each other.
-async function readYamlFile(filePath) {
-  if (!existsSync(filePath)) return {}
-  try {
-    return yaml.load(await readFile(filePath, 'utf8')) || {}
-  } catch {
-    return {}
-  }
-}
-
-export const COLLECTIONS_YML_RELPATH = 'collections/collections.yml'
-
-// The default data-schema ref for a collection that declares none: the collection's
-// OWN NAME, unchanged. `@/` is the self scope — the local foundation's `schemas/` —
-// so this stays backend-independent.
-//
-// ⛔ IT USED TO APPLY AN ENGLISH SINGULAR RULE to every language. Measured:
-// `news` → `@/new`, `series` → `@/sery`, `analyses` → `@/analys`. Right for regular
-// English plurals, right-by-accident elsewhere (`noticias` → `noticia`), and inert
-// for languages with no plural marker.
-//
-// ⚠️ The failure was SILENT, which is why the rule was removed rather than improved.
-// A default that does not resolve is not an error — the collection soft-skips to
-// delivery-only — so a `news` collection simply never synced as entities, and
-// nothing said the cause was a guess about English morphology.
-//
-// A more complete rule would move that boundary, not remove it: every irregular
-// list belongs to one language, and a site names its collections in its own.
-// Identity has no boundary to get wrong, and an author wanting a different schema
-// name writes `schema:`, which is one line and says what it means.
-//
-// Exported so the inverse (projection) can drop a `schema:` that merely restates
-// this default, keeping a projected collections.yml as terse as the author left it.
-export function defaultSchema(name) {
-  return `@/${name}`
-}
-
-// Normalize one site.yml::collections entry (string shorthand or object) to the
-// internal decl shape. Paths here are already site-root-relative (legacy contract).
-function normalizeSiteDecl(name, decl) {
-  if (typeof decl === 'string') return { name, path: decl }
-  const d = decl && typeof decl === 'object' ? decl : {}
-  return { name, ...d }
-}
-
-// Normalize one collections.yml::collections entry. Its `path:` is relative to the
-// collections/ directory (default = the collection name); we lift it to a
-// site-root-relative path so downstream readers resolve it uniformly.
-function normalizeYmlDecl(name, decl) {
-  const d = decl && typeof decl === 'object' ? decl : {}
-  const rel = typeof d.path === 'string' ? d.path : name
-  return { name, ...d, path: `collections/${rel}` }
-}
-
-/**
- * Resolve the merged collection configuration for a site.
- *
- * @param {string} siteRoot - directory containing site.yml + collections/
- * @param {object} [opts]
- * @param {object} [opts.siteYml] - an already-read site.yml (avoids a re-read)
- * @returns {Promise<{
- *   folderSync: boolean,            // collections.yml `sync` (whole-folder opt-out)
- *   hasCollectionsYml: boolean,
- *   declarations: object,           // { name: decl }  — merged, schema-defaulted
- *   folders: Array|null,            // collections.yml `folders` (virtual org) or null
- * }>}
- */
-export async function resolveCollectionsConfig(siteRoot, opts = {}) {
-  const siteYml = opts.siteYml || (await readYamlFile(join(siteRoot, 'site.yml')))
-  const ymlPath = join(siteRoot, COLLECTIONS_YML_RELPATH)
-  const hasCollectionsYml = existsSync(ymlPath)
-  const colYml = hasCollectionsYml ? await readYamlFile(ymlPath) : {}
-
-  const declarations = {}
-
-  // Legacy site.yml::collections first (lower precedence).
-  const siteCols = siteYml?.collections
-  if (siteCols && typeof siteCols === 'object' && !Array.isArray(siteCols)) {
-    for (const [name, decl] of Object.entries(siteCols)) {
-      declarations[name] = normalizeSiteDecl(name, decl)
-    }
-  }
-
-  // collections.yml::collections overlay (higher precedence; per-key merge).
-  const ymlCols = colYml?.collections
-  if (ymlCols && typeof ymlCols === 'object' && !Array.isArray(ymlCols)) {
-    for (const [name, decl] of Object.entries(ymlCols)) {
-      const incoming = normalizeYmlDecl(name, decl)
-      declarations[name] = { ...(declarations[name] || {}), ...incoming, name }
-    }
-  }
-
-  // Schema default (subfolder-name convention) + `model:`→`schema:` synonym.
-  // `schemaExplicit` records whether the author asked for this schema: an explicit
-  // schema that fails to resolve is a hard error; a convention-defaulted one that
-  // fails to resolve soft-skips (so a delivery-only collection never breaks sync).
-  for (const decl of Object.values(declarations)) {
-    if (decl.schema) {
-      decl.schemaExplicit = true
-    } else if (decl.model) {
-      decl.schema = decl.model // migration synonym
-      decl.schemaExplicit = true
-    } else if (decl.path || !decl.url) {
-      decl.schema = defaultSchema(decl.name) // subfolder-name convention
-      decl.schemaExplicit = false
-    }
-  }
-
-  await deriveDeferredFromSchemas(siteRoot, siteYml, declarations)
-
-  const folderSync = colYml?.sync !== false
-  return {
-    folderSync,
-    hasCollectionsYml,
-    declarations,
-    folders: Array.isArray(colYml?.folders) ? colYml.folders : null,
-  }
-}
-
-/**
- * The declarations as `config.collections` should carry them.
- *
- * `schemaExplicit` records whether the AUTHOR asked for a schema or the
- * subfolder-name convention supplied one. That decides how a failed resolution
- * behaves during sync — hard error vs soft skip — and is nobody's business
- * downstream. It is stripped here rather than at each consumer, so the payload
- * has one shape and no consumer has to know the field existed.
- *
- * Returns undefined for a site with no collections, so `config.collections`
- * stays absent rather than becoming an empty object — an empty object reads as
- * "declared, and empty" to anything checking for presence.
- */
-export function toConfigCollections(declarations) {
-  const names = Object.keys(declarations || {})
-  if (names.length === 0) return undefined
-  const out = {}
-  for (const name of names) {
-    const { schemaExplicit, ...rest } = declarations[name]
-    out[name] = rest
-  }
-  return out
-}
-
-
-/**
- * Fill in `deferred:` from each collection's own data schema.
- *
- * ⭐ A schema's **brief** section already states what a record's summary is — the
- * card, the row, the thing a list shows. Everything else is wanted only when one
- * record is the focus. That is exactly what `deferred:` says, so an author with a
- * schema should not have to say it twice, in a second vocabulary, with nothing
- * checking the two against each other.
- *
- * ⇒ `deferred` = the schema's flat-record fields MINUS its brief fields.
- *
- * Derived from the SCHEMA, never from a record. That is what keeps the
- * build-derived keys safe without a reserved list: `slug`, `route`, `path`,
- * `excerpt`, `image` and `lastModified` are not schema fields, so they are never
- * in the difference and never stripped. `content` is not exempt — it is
- * schema-governed, and usually the heavy field the split exists for.
- *
- * ⛔ Silent on every path that cannot answer, because none of them is an error:
- *
- *   - an author-declared `deferred:` wins outright — this never overrides one;
- *   - no local foundation (a linked or cataloged one), or it is unbuilt → nothing
- *     to read, and a site must still build;
- *   - the schema is not in the foundation's built map → the same soft-skip the
- *     sync lane already applies. `dist/meta/schema.json` carries the schemas
- *     COMPONENTS reference, so a collection whose schema no component binds is
- *     simply not there;
- *   - the schema states no brief (`briefFields` → null, e.g. a root list) → there
- *     is no lean shape to honour, so records stay whole.
- *
- * The last two are why this reads the built artifact rather than resolving
- * schemas itself: it is the same input the sync lane uses, so both lanes agree
- * about which schemas exist.
- */
-async function deriveDeferredFromSchemas(siteRoot, siteYml, declarations) {
-  const pending = Object.values(declarations).filter(
-    (d) => d.schema && !Array.isArray(d.deferred)
-  )
-  if (pending.length === 0) return
-
-  const dataSchemas = loadFoundationDataSchemas(siteRoot, siteYml)
-  if (!dataSchemas) return
-
-  for (const decl of pending) {
-    const schema = dataSchemas[decl.schema]
-    if (!schema) continue
-    const brief = briefFields(schema)
-    if (!brief) continue
-    const all = Object.keys(flatRecordFields(schema) || {})
-    const heavy = all.filter((f) => !brief.has(f))
-    if (heavy.length) decl.deferred = heavy
-  }
-}
-
-/** The foundation's built data-schema map, or null when there is nothing to read. */
-function loadFoundationDataSchemas(siteRoot, siteYml) {
-  if (!siteYml?.foundation) return null
-  let info
-  try {
-    info = detectFoundationType(siteYml.foundation, siteRoot)
-  } catch {
-    return null // a declaration this resolver refuses is not this function's error
-  }
-  if (info?.type !== 'local' || !info.path) return null
-  const schemaPath = join(info.path, 'dist', 'meta', 'schema.json')
-  if (!existsSync(schemaPath)) return null
-  try {
-    return JSON.parse(readFileSync(schemaPath, 'utf8'))?.dataSchemas || null
-  } catch {
-    return null
-  }
-}
-
-/** Path to the collections.yml file (whether or not it exists yet). */
-export function collectionsYmlPath(siteRoot) {
-  return join(siteRoot, COLLECTIONS_YML_RELPATH)
-}

package/src/uwx/collection-source.js

@@ -1,180 +0,0 @@
-// Read a file-based collection's ORIGINAL source records for sync — the author's
-// files, untouched. This is deliberately NOT `processCollections`
-// (`build/src/site/collection-processor.js`): that is the DELIVERY pipeline that
-// builds `public/data/<name>.json` — it converts markdown bodies to ProseMirror,
-// derives excerpt/image, rewrites asset paths, and copies files into
-// `public/collections/`. Sync carries the source, so it must read the source:
-// raw frontmatter + raw markdown body, raw YAML/JSON mappings, raw BibTeX entries.
-// No conversion, no derivation, no filter/sort/limit, no asset side effects.
-//
-// A collection `.md` is NOT a page-section `.md`: its frontmatter is structured
-// DATA whose schema is the collection type's data schema (the `model:` Model), and
-// its body is the value of the Model's content body field (a markup `text` field,
-// or a `format: prosemirror` json field) — not foundation/runtime config. See
-// docs/reference/entity-content.md §"Markdown (frontmatter + body)".
-
-import { readFile, readdir } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { join, basename, extname, resolve } from 'node:path'
-import yaml from 'js-yaml'
-import { parseBibtex } from '@citestyle/bibtex'
-
-const SOURCE_EXTENSIONS = new Set(['.md', '.yml', '.yaml', '.json', '.bib'])
-
-/**
- * Split YAML frontmatter from a markdown body. Mirrors the collection
- * processor's split (`---\n` delimited) so a record read here re-renders to the
- * same shape the back-fill writer produces. A file with no frontmatter yields an
- * empty mapping and the whole text as body.
- *
- * @param {string} raw
- * @returns {{ frontmatter: object, body: string }}
- */
-export function parseFrontmatter(raw) {
-  if (!raw.trimStart().startsWith('---')) {
-    return { frontmatter: {}, body: raw }
-  }
-  const parts = raw.split('---\n')
-  if (parts.length < 3) {
-    return { frontmatter: {}, body: raw }
-  }
-  try {
-    const frontmatter = yaml.load(parts[1]) || {}
-    const body = parts.slice(2).join('---\n')
-    return { frontmatter, body }
-  } catch {
-    return { frontmatter: {}, body: raw }
-  }
-}
-
-// Format key from a file extension. Single source of the format vocabulary the
-// reader emits and the writer dispatches on.
-function formatFor(ext) {
-  if (ext === '.md') return 'md'
-  if (ext === '.json') return 'json'
-  if (ext === '.yml' || ext === '.yaml') return 'yaml'
-  if (ext === '.bib') return 'bib'
-  return null
-}
-
-async function readOneFile(filepath) {
-  const ext = extname(filepath).toLowerCase()
-  const format = formatFor(ext)
-  const slugFromName = basename(filepath, ext)
-  const raw = await readFile(filepath, 'utf-8')
-
-  if (format === 'md') {
-    const { frontmatter, body } = parseFrontmatter(raw)
-    const slug = frontmatter.slug || slugFromName
-    return [{ slug, format, data: frontmatter, body, sourceFile: filepath, multiRecord: false }]
-  }
-
-  if (format === 'bib') {
-    // BibTeX always yields an array — the cite key is the slug/$id. Multi-record
-    // file → write-back deferred (no natural in-file `$uuid` slot in v1).
-    const entries = parseBibtex(raw)
-    return entries
-      .filter((e) => e && e.id)
-      .map((e) => ({ slug: e.id, format, data: e, body: undefined, sourceFile: filepath, multiRecord: true }))
-  }
-
-  // yaml / json
-  const data = format === 'json' ? JSON.parse(raw) : yaml.load(raw)
-  if (Array.isArray(data)) {
-    // Many records in one file — each carries its own slug. Write-back deferred.
-    return data
-      .filter((item) => item && typeof item === 'object')
-      .map((item) => ({
-        slug: item.slug,
-        format,
-        data: item,
-        body: undefined,
-        sourceFile: filepath,
-        multiRecord: true,
-      }))
-  }
-  const mapping = data && typeof data === 'object' ? data : {}
-  const slug = mapping.slug || slugFromName
-  return [{ slug, format, data: mapping, body: undefined, sourceFile: filepath, multiRecord: false }]
-}
-
-/**
- * Read every source record in a collection directory, untouched.
- *
- * @param {string} collectionDir - absolute path to the collection folder
- * @returns {Promise<Array<{ slug, format, data, body, sourceFile, multiRecord }>>}
- *   `data` is the raw frontmatter / mapping / entry; `body` is the raw markdown
- *   body (md only, else undefined); `multiRecord` is true for array-form / bib
- *   files (write-back deferred). No delivery processing of any kind.
- */
-export async function readCollectionRecords(collectionDir) {
-  if (!existsSync(collectionDir)) {
-    throw new Error(`uwx/collection-source: collection folder not found: ${collectionDir}`)
-  }
-  const entries = await readdir(collectionDir, { withFileTypes: true })
-  const files = entries
-    .filter((e) => e.isFile())
-    .map((e) => e.name)
-    .filter((f) => !f.startsWith('_') && SOURCE_EXTENSIONS.has(extname(f).toLowerCase()))
-    .sort() // stable order — the wire's package digest depends on it
-
-  await reportNestedRecords(collectionDir, entries)
-
-  const records = []
-  for (const file of files) {
-    const recs = await readOneFile(resolve(collectionDir, file))
-    records.push(...recs)
-  }
-  return records
-}
-
-/**
- * Report source records nested below a collection's top level.
- *
- * ⛔ THIS LANE IS FLAT AND THAT IS A CONTRACT, NOT AN OVERSIGHT. The delivery
- * build reads a collection recursively — an author may organise records into
- * branches, and `path` + the `under` predicate address them
- * (`build/src/site/collection-processor.js`). Sync cannot follow yet: the
- * folder shape agreed with the entity store is one level, records as direct
- * leaves of a collection's branch, and going deeper needs that renegotiated
- * with an explicit order axis rather than assumed.
- *
- * ⚠️ The two lanes therefore disagree, and the failure mode is the dangerous
- * shape: a nested record BUILDS and RENDERS locally, then is simply absent from
- * everything the sync produced — no error, no empty result, just a smaller set
- * than the author is looking at. Losing records silently is the one outcome
- * that must not happen, so this says so. It does not throw: a static site with
- * nested collections is completely valid and must keep working, and an author
- * who never syncs should not be blocked by a lane they do not use.
- */
-async function reportNestedRecords(collectionDir, entries) {
-  const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('_') && !e.name.startsWith('.'))
-  if (dirs.length === 0) return
-
-  const nested = []
-  for (const dir of dirs) {
-    nested.push(...(await findSourceFiles(resolve(collectionDir, dir.name), dir.name)))
-  }
-  if (nested.length === 0) return
-
-  const shown = nested.slice(0, 5).join(', ')
-  const more = nested.length > 5 ? `, and ${nested.length - 5} more` : ''
-  console.warn(
-    `[uwx/collection-source] ${nested.length} record(s) below the top level of ` +
-      `"${basename(collectionDir)}" are NOT synced: ${shown}${more}. ` +
-      `Collection sync is one level deep; these build and render locally but are ` +
-      `absent from the synced set. Move them to the collection's top level to sync them.`
-  )
-}
-
-/** Every source file at or below `dir`, as paths relative to the collection root. */
-async function findSourceFiles(dir, rel) {
-  const out = []
-  for (const entry of await readdir(dir, { withFileTypes: true })) {
-    if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue
-    const relPath = `${rel}/${entry.name}`
-    if (entry.isDirectory()) out.push(...(await findSourceFiles(resolve(dir, entry.name), relPath)))
-    else if (SOURCE_EXTENSIONS.has(extname(entry.name).toLowerCase())) out.push(relPath)
-  }
-  return out
-}

package/src/uwx/collections-config.js

@@ -1,9 +0,0 @@
-// Moved to `../site/collections-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 {
-  resolveCollectionsConfig,
-  collectionsYmlPath,
-  defaultSchema,
-  COLLECTIONS_YML_RELPATH,
-} from '../site/collections-config.js'