@uniweb/build 0.29.1 → 0.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.29.1",
+  "version": "0.30.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -60,14 +60,14 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.4",
+    "@uniweb/projections": "^0.5.2",
+    "@uniweb/semantic-parser": "^1.3.1",
     "@uniweb/schemas": "^0.2.11",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/projections": "^0.5.1",
-    "@uniweb/semantic-parser": "^1.3.1",
     "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.13.1"
+    "@uniweb/runtime": "^0.13.3"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -76,7 +76,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.13.1"
+    "@uniweb/core": "^0.14.1"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/content/index.js

@@ -12,15 +12,15 @@
 
 export { collectSiteContent } from '../site/content-collector.js'
 
-// Collections + fetch resolution. Pure functions on the clean dep
+// Query + fetch resolution. Pure functions on the clean dep
 // chain — re-exported here so headless callers (unipress, sidecars)
-// can resolve `collections:` declarations without importing
+// can resolve `queries:` declarations without importing
 // `@uniweb/build/site` (which pulls Vite via its plugin index).
 export {
-  processCollections,
-  writeCollectionFiles,
-  getCollectionLastModified,
-} from '../site/collection-processor.js'
+  processQueries,
+  writeQueryFiles,
+  getQueryLastModified,
+} from '../site/query-processor.js'
 export {
   parseFetchConfig,
   executeFetch,

package/src/dev-backend.js

@@ -2,7 +2,7 @@
 /**
  * Dev backend for testing Uniweb sites with `supports: [where, limit, sort]`.
  *
- * Reads a directory of YAML collections (each subfolder is a collection,
+ * Reads a directory of YAML recordsByQuery (each subfolder is a collection,
  * each .yml file inside is a record) and exposes them via HTTP. Evaluates
  * where-objects on the server side using @uniweb/core's matchWhere — the
  * exact same evaluator the runtime uses as a fallback. This lets you
@@ -11,7 +11,7 @@
  * Wire format matches the framework default fetcher's pushdown conventions
  * (see framework/runtime/src/default-fetcher.js):
  *
- *   GET  /api/{collection}                        — full collection
+ *   GET  /api/{collection}                        — all records
  *   GET  /api/{collection}?_where=<JSON>          — filtered by where-object
  *   GET  /api/{collection}?_limit=N               — first N records
  *   GET  /api/{collection}?_sort=field:dir        — sorted
@@ -19,11 +19,11 @@
  *   GET  /api/{collection}/{slug}                 — single record
  *
  * Usage:
- *   node scripts/framework/dev-backend.js --collections <path> [--port N]
+ *   node scripts/framework/dev-backend.js --recordsByQuery <path> [--port N]
  *
  * Example (academic-metrics):
  *   node scripts/framework/dev-backend.js \
- *     --collections framework/templates/academic-metrics/site/collections \
+ *     --recordsByQuery framework/templates/academic-metrics/site/recordsByQuery \
  *     --port 8080
  *
  * Then in the site's site.yml:
@@ -45,27 +45,27 @@ import { matchWhere } from '@uniweb/core'
 
 const { values } = parseArgs({
   options: {
-    collections: { type: 'string', short: 'c' },
+    entities: { type: 'string', short: 'e' },
     port: { type: 'string', short: 'p', default: '8080' },
   },
 })
 
-if (!values.collections) {
-  console.error('Usage: dev-backend.js --collections <path> [--port N]')
+if (!values.entities) {
+  console.error('Usage: dev-backend.js --entities <path> [--port N]')
   process.exit(1)
 }
 
-const COLLECTIONS_DIR = resolve(values.collections)
+const ENTITIES_ROOT = resolve(values.entities)
 const PORT = Number(values.port)
 
-if (!existsSync(COLLECTIONS_DIR)) {
-  console.error(`Collections directory not found: ${COLLECTIONS_DIR}`)
+if (!existsSync(ENTITIES_ROOT)) {
+  console.error(`Entities directory not found: ${ENTITIES_ROOT}`)
   process.exit(1)
 }
 
-// ─── Load collections from disk ─────────────────────────────────────────────
+// ─── Load recordsByQuery from disk ─────────────────────────────────────────────
 
-async function loadCollection(dir) {
+async function loadRecords(dir) {
   const files = await readdir(dir)
   const items = []
   for (const file of files) {
@@ -94,17 +94,17 @@ async function loadCollection(dir) {
   return items
 }
 
-async function loadAllCollections() {
-  const entries = await readdir(COLLECTIONS_DIR)
-  const collections = {}
+async function loadAllRecords() {
+  const entries = await readdir(ENTITIES_ROOT)
+  const recordsByQuery = {}
   for (const name of entries) {
-    const fullPath = join(COLLECTIONS_DIR, name)
+    const fullPath = join(ENTITIES_ROOT, name)
     const s = await stat(fullPath)
     if (!s.isDirectory()) continue
-    collections[name] = await loadCollection(fullPath)
-    console.log(`[dev-backend] Loaded ${collections[name].length} items from "${name}"`)
+    recordsByQuery[name] = await loadRecords(fullPath)
+    console.log(`[dev-backend] Loaded ${recordsByQuery[name].length} items from "${name}"`)
   }
-  return collections
+  return recordsByQuery
 }
 
 // ─── Operator handling (mirrors default-fetcher pushdown wire format) ───────
@@ -182,16 +182,16 @@ function send(res, status, body) {
   res.end(typeof body === 'string' ? body : JSON.stringify(body))
 }
 
-async function handleRequest(req, res, collections) {
+async function handleRequest(req, res, recordsByQuery) {
   if (req.method === 'OPTIONS') return send(res, 204, '')
 
   const url = new URL(req.url, `http://${req.headers.host}`)
   const match = url.pathname.match(/^\/api\/([^/]+)(?:\/([^/]+))?$/)
   if (!match) return send(res, 404, { error: 'Not found' })
 
-  const [, collectionName, slug] = match
-  const items = collections[collectionName]
-  if (!items) return send(res, 404, { error: `Unknown collection: ${collectionName}` })
+  const [, queryName, slug] = match
+  const items = recordsByQuery[queryName]
+  if (!items) return send(res, 404, { error: `Unknown query: ${queryName}` })
 
   // Single record by slug.
   if (slug) {
@@ -221,14 +221,14 @@ async function handleRequest(req, res, collections) {
 
 // ─── Boot ───────────────────────────────────────────────────────────────────
 
-const collections = await loadAllCollections()
-const knownCollections = Object.keys(collections)
-if (knownCollections.length === 0) {
-  console.warn('[dev-backend] No collections found.')
+const recordsByQuery = await loadAllRecords()
+const knownQueries = Object.keys(recordsByQuery)
+if (knownQueries.length === 0) {
+  console.warn('[dev-backend] No recordsByQuery found.')
 }
 
 const server = createServer((req, res) => {
-  handleRequest(req, res, collections).catch((err) => {
+  handleRequest(req, res, recordsByQuery).catch((err) => {
     console.error('[dev-backend] Request handler threw:', err)
     send(res, 500, { error: 'Internal server error' })
   })
@@ -236,10 +236,10 @@ const server = createServer((req, res) => {
 
 server.listen(PORT, () => {
   console.log(`[dev-backend] Listening on http://localhost:${PORT}`)
-  console.log(`[dev-backend] Collections: ${knownCollections.join(', ') || '(none)'}`)
+  console.log(`[dev-backend] Queries: ${knownQueries.join(', ') || '(none)'}`)
   console.log('[dev-backend] Endpoints:')
-  for (const name of knownCollections) {
-    console.log(`  GET  /api/${name}                  — full collection`)
+  for (const name of knownQueries) {
+    console.log(`  GET  /api/${name}                  — all records`)
     console.log(`  GET  /api/${name}?_where=<JSON>    — filtered`)
     console.log(`  GET  /api/${name}/{slug}            — single record`)
     console.log(`  POST /api/${name}  body: { where } — operators in body`)

package/src/i18n/freeform.js

@@ -10,7 +10,7 @@
  *   locales/freeform/{locale}/
  *     pages/{pageRoute}/{stableId}.md      - By route
  *     page-ids/{pageId}/{stableId}.md      - By page ID (stable)
- *     collections/{collectionName}/{slug}.md - Collection items
+ *     collections/{queryName}/{slug}.md - Collection items
  *
  * Resolution order for sections:
  *   1. page-ids/{pageId}/{stableId}.md (if page has id:)
@@ -22,6 +22,7 @@ import { readFile, readdir, stat } from 'fs/promises'
 import { existsSync } from 'node:fs'
 import { join, relative, dirname } from 'node:path'
 import yaml from 'js-yaml'
+import { poolDirsForSchema, ENTITIES_DIR } from '../site/entity-pool.js'
 
 // Try to import content-reader for markdown → ProseMirror conversion
 let markdownToProseMirror
@@ -140,24 +141,35 @@ export async function loadFreeformTranslation(section, page, locale, localesDir)
 }
 
 /**
- * Load free-form translation for a collection item
+ * Load a free-form translation for one ENTITY.
  *
- * Path: collections/{collectionName}/{slug}.md
+ * Path: entities/{schema dirs}/{slug}.md — mirroring the pool exactly.
  *
- * @param {Object} item - Collection item with slug
- * @param {string} collectionName - Name of the collection
+ * ⛔ KEYED BY THE ENTITY, NOT BY A QUERY. It used to be
+ * `collections/{queryName}/{slug}.md`, which was fine only while a
+ * collection was also a directory of files. With `entities/{schema}/` as the pool,
+ * TWO queries can cover one schema — so a query-keyed path would make an author
+ * write the same translation once per query, and finding neither from the other.
+ * ⚠️ And a query is renameable where a record's model is not: keying on the query
+ * orphaned every translation the moment someone renamed one.
+ *
+ * @param {Object} item - entity with a slug
+ * @param {string} schema - the entity's model ref (`@/name` or `@org/name`)
  * @param {string} locale - Locale code
  * @param {string} localesDir - Path to locales directory
  * @returns {Promise<Object|null>} Parsed translation { frontmatter, content } or null
  */
-export async function loadFreeformCollectionItem(item, collectionName, locale, localesDir) {
+export async function loadFreeformRecord(item, schema, locale, localesDir) {
   const slug = item.slug
   if (!slug) return null
 
+  const rel = buildFreeformRecordPath(schema, slug)
+  if (!rel) return null
+
   const freeformDir = join(localesDir, 'freeform', locale)
   if (!existsSync(freeformDir)) return null
 
-  const filePath = join(freeformDir, 'collections', collectionName, `${slug}.md`)
+  const filePath = join(freeformDir, rel)
   if (!existsSync(filePath)) return null
 
   try {
@@ -174,7 +186,7 @@ export async function loadFreeformCollectionItem(item, collectionName, locale, l
       relativePath: relative(join(localesDir, 'freeform', locale), filePath)
     }
   } catch (err) {
-    console.warn(`[i18n] Failed to load free-form collection item ${filePath}: ${err.message}`)
+    console.warn(`[i18n] Failed to load free-form record ${filePath}: ${err.message}`)
     return null
   }
 }
@@ -221,7 +233,7 @@ export async function discoverFreeformTranslations(locale, localesDir) {
   const result = {
     pages: [],
     pageIds: [],
-    collections: []
+    records: []
   }
 
   if (!existsSync(freeformDir)) return result
@@ -238,10 +250,10 @@ export async function discoverFreeformTranslations(locale, localesDir) {
     result.pageIds = await discoverMarkdownFiles(pageIdsDir, pageIdsDir)
   }
 
-  // Discover collection translations
-  const collectionsDir = join(freeformDir, 'collections')
-  if (existsSync(collectionsDir)) {
-    result.collections = await discoverMarkdownFiles(collectionsDir, collectionsDir)
+  // Discover entity translations
+  const entitiesDir = join(freeformDir, ENTITIES_DIR)
+  if (existsSync(entitiesDir)) {
+    result.records = await discoverMarkdownFiles(entitiesDir, entitiesDir)
   }
 
   return result
@@ -267,7 +279,7 @@ export async function getFreeformFileMeta(filePath) {
  * Parse a free-form translation file path to extract metadata
  *
  * @param {string} relativePath - Path relative to locale's freeform dir
- * @returns {Object} { type, pageRoute?, pageId?, collectionName?, stableId, slug? }
+ * @returns {Object} { type, pageRoute?, pageId?, queryName?, stableId, slug? }
  */
 export function parseFreeformPath(relativePath) {
   const parts = relativePath.split('/')
@@ -287,11 +299,11 @@ export function parseFreeformPath(relativePath) {
     return { type: 'pageId', pageId, stableId }
   }
 
-  if (parts[0] === 'collections') {
-    // collections/articles/getting-started.md → { type: 'collection', collectionName: 'articles', slug: 'getting-started' }
+  if (parts[0] === ENTITIES_DIR) {
+    // collections/articles/getting-started.md → { type: 'collection', queryName: 'articles', slug: 'getting-started' }
     const slug = parts[parts.length - 1].replace('.md', '')
-    const collectionName = parts[1]
-    return { type: 'collection', collectionName, slug }
+    const queryName = parts[1]
+    return { type: 'record', queryName, slug }
   }
 
   return { type: 'unknown', relativePath }
@@ -325,12 +337,20 @@ export function buildFreeformPath(section, page, preferPageId = true) {
 }
 
 /**
- * Build the expected free-form translation path for a collection item
+ * The free-form translation path for one entity — the pool's own layout, under
+ * `locales/freeform/{locale}/`.
+ *
+ * ⛔ ONE DERIVATION, shared by the producer (which looks a translation up) and the
+ * projector (which writes one). `poolDirsForSchema` is the same inverse the pull
+ * side places records with, so a translation cannot land beside a record it is not
+ * for.
  *
- * @param {string} collectionName - Name of the collection
- * @param {string} slug - Item slug
- * @returns {string} Relative path (e.g., 'collections/articles/getting-started.md')
+ * @param {string} schema - the entity's model ref (`@/name` or `@org/name`)
+ * @param {string} slug - the entity's slug
+ * @returns {string|null} e.g. `entities/article/getting-started.md`, or null for a
+ *   ref this layout cannot express
  */
-export function buildFreeformCollectionPath(collectionName, slug) {
-  return `collections/${collectionName}/${slug}.md`
+export function buildFreeformRecordPath(schema, slug) {
+  const dirs = poolDirsForSchema(schema)
+  return dirs ? `${ENTITIES_DIR}/${dirs.join('/')}/${slug}.md` : null
 }

package/src/i18n/index.js

@@ -17,23 +17,23 @@ import { syncManifests, formatSyncReport } from './sync.js'
 import { mergeTranslations, generateAllLocales } from './merge.js'
 import { auditLocale, cleanLocale, formatAuditReport } from './audit.js'
 import {
-  extractCollectionContent,
-  buildLocalizedCollections,
-  getCollectionLocales,
-  translateCollectionData,
-  COLLECTIONS_DIR
-} from './collections.js'
+  extractRecordContent,
+  buildLocalizedRecords,
+  getRecordLocales,
+  translateRecordData,
+  RECORDS_DIR
+} from './records.js'
 import { generateSearchIndex, isSearchEnabled } from '../search/index.js'
 
 // Free-form translation support
 import {
   loadFreeformTranslation,
-  loadFreeformCollectionItem,
+  loadFreeformRecord,
   discoverFreeformTranslations,
   getFreeformFileMeta,
   parseFreeformPath,
   buildFreeformPath,
-  buildFreeformCollectionPath
+  buildFreeformRecordPath
 } from './freeform.js'
 import {
   computeSourceHash,
@@ -67,11 +67,11 @@ export {
   formatAuditReport,
 
   // Collection functions
-  extractCollectionContent,
-  buildLocalizedCollections,
-  getCollectionLocales,
-  translateCollectionData,
-  COLLECTIONS_DIR,
+  extractRecordContent,
+  buildLocalizedRecords,
+  getRecordLocales,
+  translateRecordData,
+  RECORDS_DIR,
 
   // Locale resolution
   getAvailableLocales,
@@ -79,12 +79,12 @@ export {
 
   // Free-form translation functions
   loadFreeformTranslation,
-  loadFreeformCollectionItem,
+  loadFreeformRecord,
   discoverFreeformTranslations,
   getFreeformFileMeta,
   parseFreeformPath,
   buildFreeformPath,
-  buildFreeformCollectionPath,
+  buildFreeformRecordPath,
 
   // Free-form manifest functions
   computeSourceHash,
@@ -221,19 +221,19 @@ export async function extractManifest(siteRoot, siteContent, options = {}) {
  * @param {Object} options - Options
  * @returns {Promise<Object>} { manifest, report }
  */
-export async function extractCollectionManifest(siteRoot, options = {}) {
+export async function extractRecordManifest(siteRoot, options = {}) {
   const { localesDir = DEFAULTS.localesDir, dryRun = false } = options
 
   // Extract translatable content from collections
-  const manifest = await extractCollectionContent(siteRoot)
+  const manifest = await extractRecordContent(siteRoot)
 
   // Ensure collections locales directory exists
-  const collectionsDir = join(siteRoot, localesDir, COLLECTIONS_DIR)
-  if (!existsSync(collectionsDir)) {
-    await mkdir(collectionsDir, { recursive: true })
+  const recordLocalesDir = join(siteRoot, localesDir, RECORDS_DIR)
+  if (!existsSync(recordLocalesDir)) {
+    await mkdir(recordLocalesDir, { recursive: true })
   }
 
-  const manifestPath = join(collectionsDir, 'manifest.json')
+  const manifestPath = join(recordLocalesDir, 'manifest.json')
 
   // Load previous manifest for comparison
   let previousManifest = null
@@ -458,7 +458,7 @@ async function warnAboutFreeformIssues(locale, freeformDir, siteContent) {
 
     // Check for unregistered translations (new files)
     const discovered = await discoverFreeformTranslations(locale, dirname(dirname(freeformDir)))
-    const allPaths = [...discovered.pages, ...discovered.pageIds, ...discovered.collections]
+    const allPaths = [...discovered.pages, ...discovered.pageIds, ...discovered.records]
     const unregistered = await getUnregisteredTranslations(freeformDir, allPaths)
     for (const path of unregistered) {
       // Auto-register new free-form translations