@uniweb/build 0.63.2 → 0.63.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.63.2",
+  "version": "0.63.4",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,12 +57,12 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/projections": "^0.7.3",
     "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/projections": "^0.7.3",
     "@uniweb/schemas": "^0.7.0",
-    "@uniweb/theming": "^0.1.15",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "^0.27.4"

package/src/i18n/index.js

@@ -7,11 +7,12 @@
  *   import { extractManifest, syncManifest, mergeLocale } from '@uniweb/build/i18n'
  */
 
-import { readFile, writeFile, mkdir, readdir } from 'fs/promises'
+import { readFile, writeFile, mkdir } from 'fs/promises'
 import { existsSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 
 import { computeHash, normalizeText } from './hash.js'
+import { availableLocales, resolveLocaleList } from './locales.js'
 import { extractTranslatableContent } from './extract.js'
 import { syncManifests, formatSyncReport } from './sync.js'
 import { mergeTranslations, generateAllLocales } from './merge.js'
@@ -118,7 +119,6 @@ const DEFAULTS = {
 /**
  * Reserved files in the locales directory (not locale translation files)
  */
-const RESERVED_FILES = new Set(['manifest.json', '_memory.json'])
 
 /**
  * Get available locales by scanning the locales directory for *.json files
@@ -126,19 +126,7 @@ const RESERVED_FILES = new Set(['manifest.json', '_memory.json'])
  * @returns {Promise<string[]>} Array of locale codes found
  */
 async function getAvailableLocales(localesPath) {
-  if (!existsSync(localesPath)) {
-    return []
-  }
-
-  try {
-    const files = await readdir(localesPath)
-    return files
-      .filter(f => f.endsWith('.json') && !RESERVED_FILES.has(f))
-      .map(f => f.replace('.json', ''))
-      .sort()
-  } catch {
-    return []
-  }
+  return availableLocales(localesPath)
 }
 
 /**
@@ -154,23 +142,8 @@ async function getAvailableLocales(localesPath) {
  * @returns {Promise<string[]>} Resolved array of locale codes
  */
 async function resolveLocales(configLocales, localesPath) {
-  // Explicit list of locales
-  if (Array.isArray(configLocales) && configLocales.length > 0) {
-    // Check for '*' in array (e.g., locales: ['*'])
-    if (configLocales.includes('*')) {
-      return getAvailableLocales(localesPath)
-    }
-    // Normalize: support both string codes and objects ({code, label})
-    return configLocales.map(l => typeof l === 'string' ? l : l.code)
-  }
-
-  // String value '*' means all available
-  if (configLocales === '*') {
-    return getAvailableLocales(localesPath)
-  }
-
-  // undefined, null, or empty array → all available
-  return getAvailableLocales(localesPath)
+  // The one rule, shared with the push (`uwx/site.js`) — see `./locales.js`.
+  return resolveLocaleList(configLocales, localesPath)
 }
 
 /**

package/src/i18n/locales.js

@@ -0,0 +1,51 @@
+// ⭐ WHICH LOCALES A SITE HAS — one rule, for the build and for the push.
+//
+// An explicit `languages:` list is the set, as written. `'*'`, or no `languages:` at all, is every
+// translation file in the locales directory. ⛔ Until 2026-09-25 the push read an explicit
+// `languages:` alone, so a site whose set comes from its files — the `international` template,
+// which has none — was pushed as a one-language site, and none of its translations left the
+// machine, while the build of the same site produced every one of them.
+//
+// A leaf, with nothing but `node:fs` beneath it, so the sync lane can use it without pulling in
+// the rest of the i18n module.
+
+import { existsSync, readdirSync } from 'node:fs'
+
+// Files in the locales directory that are not a locale's translations.
+export const RESERVED_LOCALE_FILES = new Set(['manifest.json', '_memory.json'])
+
+/**
+ * The locales a directory holds translations for — one per `<locale>.json` — sorted.
+ *
+ * @param {string} localesPath
+ * @returns {string[]}
+ */
+export function availableLocales(localesPath) {
+  if (!existsSync(localesPath)) return []
+  try {
+    return readdirSync(localesPath)
+      .filter((f) => f.endsWith('.json') && !RESERVED_LOCALE_FILES.has(f))
+      .map((f) => f.slice(0, -'.json'.length))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * A site's locales, from its `languages:` and its locales directory.
+ *
+ * - `['es', 'fr']` → those, as written (an entry may be `{ code, label }`)
+ * - `'*'`, a list holding `'*'`, or nothing → every locale the directory holds
+ *
+ * @param {string[]|string|undefined} configLocales - `site.yml::languages`
+ * @param {string} localesPath
+ * @returns {string[]}
+ */
+export function resolveLocaleList(configLocales, localesPath) {
+  if (Array.isArray(configLocales) && configLocales.length > 0) {
+    if (configLocales.includes('*')) return availableLocales(localesPath)
+    return configLocales.map((l) => (typeof l === 'string' ? l : l.code))
+  }
+  return availableLocales(localesPath)
+}

package/src/uwx/index.js

@@ -71,7 +71,10 @@ export {
   declarationsToQueriesYml,
   folderToFolderYml,
   findRecordFileByUuid,
+  indexFolder,
 } from './records-project.js'
+// Which stored record each of a copy's records is, when its map lost the answer.
+export { matchStoredRecords } from './record-identity.js'
 // The scope a site's `@/x` refs resolve into — its foundation's. A pull resolves it
 // up front and hands it to the synchronous projections above.
 export { siteSelfScope } from './self-scope.js'

package/src/uwx/record-identity.js

@@ -0,0 +1,46 @@
+// ⭐ WHICH STORED RECORD EACH OF A COPY'S RECORDS IS — recovered from what the backend holds.
+//
+// A push sends a record with the uuid THIS backend minted for it: `sync.json`'s `records` map,
+// the record's own id (its file's `$uuid`) → theirs. A copy bound to the site whose map lost an
+// entry sends that record with none, and the backend mints a second entity for it — silently,
+// since a new record is never refused. The folder that places it is refused instead, because its
+// placements then carry no identity while the stored ones do (`identity_required`, measured
+// 2026-09-25 on a blog site whose binding held neither map).
+//
+// ⭐ MATCHED THE WAY A PULL PLACES THEM: a record whose own id IS a stored uuid is that record —
+// the first backend a record reaches mints the id its file keeps. Otherwise it is the stored
+// record the folder places under the same Model and slug. ⛔ A Model and slug two stored records
+// share names neither, and a stored record already mapped to another is not taken again: a wrong
+// match would overwrite a record the author did not edit, where no match only re-creates one.
+
+import { indexFolder } from './records-project.js'
+
+/**
+ * The stored uuid of each record the map does not name, where the backend's folder says which.
+ *
+ * @param {object} params
+ * @param {Array<{ ownId?: string|null, model?: string, slug?: string }>} params.index - the
+ *        records a push is about to send (`emitSyncPackages().records.index`)
+ * @param {Object<string,string>} [params.recordMap] - this backend's map: own id → its uuid
+ * @param {object} params.folderDoc - the backend's `@uniweb/folder` document for the site
+ * @returns {Object<string,string>} own id → the stored uuid, for the records recovered
+ */
+export function matchStoredRecords({ index, recordMap = {}, folderDoc }) {
+  const placed = indexFolder(folderDoc)
+  const byName = new Map()
+  for (const [theirs, { slug, schema }] of placed) {
+    if (!slug || !schema) continue
+    const key = `${schema} ${slug}`
+    byName.set(key, byName.has(key) ? null : theirs)
+  }
+  const taken = new Set(Object.values(recordMap))
+  const learned = {}
+  for (const e of index || []) {
+    if (!e?.ownId || recordMap[e.ownId] || learned[e.ownId]) continue
+    const theirs = placed.has(e.ownId) ? e.ownId : byName.get(`${e.model} ${e.slug}`)
+    if (!theirs || taken.has(theirs)) continue
+    taken.add(theirs)
+    learned[e.ownId] = theirs
+  }
+  return learned
+}

package/src/uwx/records-project.js

@@ -41,7 +41,7 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { parseFrontmatter } from './entity-source.js'
 import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './project-writer.js'
-import { defaultSchema, deferredFromSchema, foundationDataSchemas, foundationSchemaJson } from './queries-config.js'
+import { defaultSchema, deferredFromSchema, 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'
@@ -125,7 +125,7 @@ function defaultFormat(poolDir, declaration) {
 // 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) {
+export function indexFolder(folderDoc) {
   const byUuid = new Map()
   const walk = (nodes, folderPath) => {
     for (const node of nodes || []) {
@@ -283,7 +283,7 @@ function isDerivedDeferred(d, dataSchemas) {
   return d.deferred.every((f) => a.has(f))
 }
 
-function declToFileShape(wire, dataSchemas = null, scope = null, own = null, keyTypes = null) {
+function declToFileShape(wire, dataSchemas = null, scope = null, own = null, keyTypes = null, authored = null) {
   // ⛔ UNDO THE PRODUCER'S QUALIFICATION FIRST, before anything compares against
   // `schema`. The push qualifies a foundation-relative `@/x` to `@scope/x`
   // (`site.js::queriesNested`), and both checks below are keyed by the author's
@@ -317,8 +317,14 @@ function declToFileShape(wire, dataSchemas = null, scope = null, own = null, key
   // The default is the query's name — or, when no data schema has that name, the type the
   // foundation declares for the data key of that name (`data-key-types.js`), which is what a
   // push sent in its place. Either one stays unwritten, so the terse file stays terse.
+  // ⛔ UNLESS THE AUTHOR WROTE IT: a `schema:` the local file already states for this query is
+  // written back as it is. Until 2026-09-25 a pull into a working copy dropped international's
+  // `articles: { schema: '@std/article' }`, because a section types `articles` as `@std/article`.
   const keyDefault = name && !own?.has(name) ? keyTypes?.get(name) : null
-  if (d.schema && d.schema !== defaultSchema(name) && d.schema !== keyDefault) decl.schema = d.schema
+  const written = name ? authored?.get(name) : undefined
+  if (d.schema && (d.schema === written || (d.schema !== defaultSchema(name) && d.schema !== keyDefault))) {
+    decl.schema = d.schema
+  }
   setIf(decl, 'sort', d.sort)
   setIf(decl, 'where', d.where)
   setIf(decl, 'limit', d.limit)
@@ -383,6 +389,26 @@ function declToFileShape(wire, dataSchemas = null, scope = null, own = null, key
  *        (`info.foundation`, the pinned `@org/name@version`), which is that scope.
  * @returns {{ collections?: 'updated'|'unchanged' }}
  */
+// The `schema:` each query's author wrote, by query name — `queries.yml` over `site.yml::queries`,
+// the precedence the build reads them in. A query written without one is absent.
+function authoredQuerySchemas(siteRoot, siteYml) {
+  let file = null
+  try {
+    file = yaml.load(readFileSync(join(siteRoot, QUERIES_YML_RELPATH), 'utf8'), YAML_OPTIONS)
+  } catch {
+    file = null
+  }
+  const out = new Map()
+  for (const decls of [siteYml?.queries, file]) {
+    if (!decls || typeof decls !== 'object') continue
+    for (const [name, decl] of Object.entries(decls)) {
+      if (typeof decl?.schema === 'string') out.set(name, decl.schema)
+      else if (out.has(name)) out.delete(name)
+    }
+  }
+  return out
+}
+
 export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest }) {
   refuseOrgOption(rest, 'declarationsToQueriesYml')
   const decls = Array.isArray(document?.queries) ? document.queries : []
@@ -408,10 +434,11 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
   // (`unresolveSelfScope`) — and the types of its data keys.
   const own = ownSchemaNames(dataSchemas)
   const keyTypes = siteYml ? dataKeyTypes(foundationSchemaJson(siteRoot, siteYml)) : null
+  const authored = authoredQuerySchemas(siteRoot, siteYml)
 
   const queries = {}
   for (const d of decls) {
-    const { name, decl } = declToFileShape(d, dataSchemas, selfScope, own, keyTypes)
+    const { name, decl } = declToFileShape(d, dataSchemas, selfScope, own, keyTypes, authored)
     if (!name) continue
     queries[name] = decl
   }

package/src/uwx/site.js

@@ -74,6 +74,7 @@ import { emitEntitySyncPackage } from './entity-document.js'
 import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent } from './locale-sync.js'
 import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
+import { resolveLocaleList } from '../i18n/locales.js'
 import { updateBackendState, readBackendState } from './sync-store.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
@@ -1287,7 +1288,10 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // Target-locale translations (locales/{locale}.json) for wrapping localized
   // scalars back into per-locale form. Source-locale-only when no target locales /
   // no locale files exist (single-locale sites are unaffected).
-  const targetLocales = (Array.isArray(siteYml.languages) ? siteYml.languages : []).filter(
+  // ⭐ The site's locales by the build's own rule (`i18n/locales.js`): an explicit
+  // `languages:` list, else every translation file. ⛔ Until 2026-09-25 only an explicit list
+  // counted, so a site with none — the `international` template — pushed no translations.
+  const targetLocales = resolveLocaleList(siteYml.languages, localesDir(siteRoot)).filter(
     (l) => l !== sourceLocale
   )
   const translations = targetLocales.length > 0 ? loadLocaleTranslations(siteRoot, targetLocales) : null