@uniweb/build 0.50.0 → 0.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,15 +57,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/content-reader": "^1.2.4",
+    "@uniweb/content-reader": "^1.2.5",
     "@uniweb/schemas": "^0.2.13",
-    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/theming": "^0.1.15",
     "@uniweb/projections": "^0.7.2",
+    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/content-writer": "^0.3.4"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.25.0"
+    "@uniweb/runtime": "^0.26.1"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,7 +74,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.29.0"
+    "@uniweb/core": "^0.29.2"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/dev/api-mount.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs'
 import { resolve, join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 
 /**
  * Mount a site's own request handler in the dev server.
@@ -67,7 +68,7 @@ export function mountDevApi(server, { root }) {
   // rule working: if it were readable from `config`, it would also be published.
   let site
   try {
-    site = yaml.load(readFileSync(join(root, 'site.yml'), 'utf8')) || {}
+    site = yaml.load(readFileSync(join(root, 'site.yml'), 'utf8'), YAML_OPTIONS) || {}
   } catch {
     return false
   }

package/src/dev/plugin.js

@@ -27,6 +27,7 @@ import { existsSync, readdirSync } from 'node:fs'
 import { build } from 'vite'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
 import { DEV_REBUILD_MARKER } from '../vite-foundation-plugin.js'
+import { shouldRegenerateForFile } from '../generate-entry.js'
 
 /** Directories that never hold foundation source and must never be walked. */
 const UNWATCHABLE_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage'])
@@ -237,19 +238,22 @@ export function foundationDevPlugin(options = {}) {
           }, 200)
         }
 
-        const onChange = (eventType, filename) => {
+        // `filename` is relative to the watched target, so each target gets its own handler
+        const onChange = (target) => (eventType, filename) => {
           // Ignore generated files (build output triggers entry regeneration)
-          if (filename && filename.includes('_entry.generated')) return
+          if (!filename || filename.includes('_entry.generated')) return
 
-          // Only rebuild for source file changes
+          // Rebuild for source file changes, and for any file the entry is generated
+          // from — a data schema under `schemas/` is `.yml` or `.json` as often as `.js`
+          // (`shouldRegenerateForFile`)
           if (
-            filename &&
-            (filename.endsWith('.js') ||
-              filename.endsWith('.jsx') ||
-              filename.endsWith('.ts') ||
-              filename.endsWith('.tsx') ||
-              filename.endsWith('.css') ||
-              filename.endsWith('.svg'))
+            filename.endsWith('.js') ||
+            filename.endsWith('.jsx') ||
+            filename.endsWith('.ts') ||
+            filename.endsWith('.tsx') ||
+            filename.endsWith('.css') ||
+            filename.endsWith('.svg') ||
+            shouldRegenerateForFile(join(target.path, filename), srcPath)
           ) {
             console.log(`[foundation] ${filename} changed`)
             scheduleRebuild()
@@ -259,7 +263,7 @@ export function foundationDevPlugin(options = {}) {
         const watchers = []
         for (const target of resolveWatchTargets(srcPath)) {
           try {
-            watchers.push(watch(target.path, { recursive: target.recursive }, onChange))
+            watchers.push(watch(target.path, { recursive: target.recursive }, onChange(target)))
           } catch (err) {
             console.warn(`[foundation] Could not watch ${target.path}:`, err.message)
           }

package/src/generate-entry.js

@@ -30,7 +30,15 @@ import {
   LAYOUTS_PATH
 } from './schema.js'
 import { extractAllRuntimeSchemas, extractAllLayoutRuntimeSchemas } from './runtime-schema.js'
-import { collectSchemaRefs, buildDataSchemaMap } from './resolve-data-schema.js'
+import { collectSchemaRefs, buildDataSchemaMap, SCHEMA_EXTENSIONS } from './resolve-data-schema.js'
+
+/**
+ * The files a foundation's data schemas are read from, relative to its source root:
+ * `@/name` is `schemas/name.<ext>` (`resolve-data-schema.js::findSelfSchemaFile`), and
+ * `schemas.config.js` says where a scope's schemas live (`loadSchemaAliases`).
+ */
+const SCHEMAS_PATH = 'schemas'
+const SCHEMA_ALIASES_FILE = 'schemas.config.js'
 
 /**
  * Packages that may be bundled inside a foundation but require single-instance
@@ -407,12 +415,14 @@ export function getStructuralWatchPaths(srcDir, options = {}) {
     'main.js',
     'main.jsx',
     'styles.css',
-    'index.css'
+    'index.css',
+    SCHEMA_ALIASES_FILE
   ]
 
   return [
     ...sectionPaths.map(path => join(srcDir, path)),
     join(srcDir, LAYOUTS_PATH),
+    join(srcDir, SCHEMAS_PATH),
     ...rootFiles.map(file => join(srcDir, file))
   ]
 }
@@ -503,5 +513,22 @@ export function shouldRegenerateForFile(file, srcDir) {
     }
   }
 
+  // ⭐ The foundation's data schemas — `schemas/<name>.<ext>` and `schemas.config.js`.
+  // The entry's `meta` carries each declared `data:` key with its schema's field
+  // defaults, and a `@/name` ref whose file is missing stops entry generation. A
+  // section receives only the keys its entry declares (2026-09-14), so an entry that
+  // falls behind withholds data: a `data:` key declaring `@/member` before
+  // `schemas/member.yml` exists fails the regeneration, and until 2026-09-14 writing
+  // the file triggered no other — the dev server kept the entry without the key.
+  if (rel.startsWith(`${SCHEMAS_PATH}/`)) {
+    const inner = rel.slice(SCHEMAS_PATH.length + 1)
+    if (!inner.includes('/') && SCHEMA_EXTENSIONS.some(ext => inner.endsWith(ext))) {
+      return `data schema: ${inner}`
+    }
+  }
+  if (rel === SCHEMA_ALIASES_FILE) {
+    return 'schema aliases changed'
+  }
+
   return null
 }

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/{queryName}/{slug}.md - Collection items
+ *     entities/{schema dirs}/{slug}.md     - Records
  *
  * Resolution order for sections:
  *   1. page-ids/{pageId}/{stableId}.md (if page has id:)
@@ -20,10 +20,11 @@
 
 import { readFile, readdir, stat } from 'fs/promises'
 import { existsSync } from 'node:fs'
-import { join, relative, dirname } from 'node:path'
+import { join, relative, dirname, sep } from 'node:path'
 import yaml from 'js-yaml'
 import { poolDirsForSchema, ENTITIES_DIR } from '../site/entity-pool.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
+import { computeSourceHash } from './freeform-manifest.js'
 
 // Try to import content-reader for markdown → ProseMirror conversion
 let markdownToProseMirror
@@ -70,30 +71,11 @@ function normalizeRouteForPath(route) {
  * @returns {Promise<Object|null>} Parsed translation { content } or null
  */
 export async function loadFreeformTranslation(section, page, locale, localesDir) {
-  const stableId = section.stableId
-  if (!stableId) return null
-
   const freeformDir = join(localesDir, 'freeform', locale)
   if (!existsSync(freeformDir)) return null
 
-  const candidates = []
-
-  // 1. Try page-ids path (if page has stable id)
-  if (page.id) {
-    candidates.push(join(freeformDir, 'page-ids', page.id, `${stableId}.md`))
-  }
-
-  // 2. Try pages path (by route)
-  const routePath = normalizeRouteForPath(page.route)
-  if (routePath) {
-    candidates.push(join(freeformDir, 'pages', routePath, `${stableId}.md`))
-  } else {
-    // Root page
-    candidates.push(join(freeformDir, 'pages', `${stableId}.md`))
-  }
-
   // Try each candidate in order
-  for (const filePath of candidates) {
+  for (const filePath of freeformPathsFor(section, page).map((rel) => join(freeformDir, rel))) {
     if (!existsSync(filePath)) continue
 
     try {
@@ -189,7 +171,7 @@ async function discoverMarkdownFiles(dir, baseDir) {
       const subFiles = await discoverMarkdownFiles(fullPath, baseDir)
       files.push(...subFiles)
     } else if (entry.isFile() && entry.name.endsWith('.md')) {
-      files.push(relative(baseDir, fullPath))
+      files.push(relative(baseDir, fullPath).split(sep).join('/'))
     }
   }
 
@@ -199,11 +181,18 @@ async function discoverMarkdownFiles(dir, baseDir) {
 /**
  * Discover all free-form translation files for a locale
  *
- * Used by status commands to show what translations exist.
+ * Used by status commands to show what translations exist, and by the build to
+ * register a translation that has no manifest entry yet.
+ *
+ * ⭐ Each path is relative to the locale's free-form directory — `pages/about/story.md`,
+ * `page-ids/<id>/intro.md`, `entities/article/hello.md` — the form the manifest keys a
+ * translation by and `freeformPathsFor` derives. ⛔ Until 2026-09-14 each was relative
+ * to its own subdirectory (`about/story.md`), so none matched a manifest key: the build
+ * registered no new file, and a status counted every stale or orphaned file as up to date.
  *
  * @param {string} locale - Locale code
  * @param {string} localesDir - Path to locales directory
- * @returns {Promise<Object>} { pages: string[], pageIds: string[], collections: string[] }
+ * @returns {Promise<{ pages: string[], pageIds: string[], records: string[] }>}
  */
 export async function discoverFreeformTranslations(locale, localesDir) {
   const freeformDir = join(localesDir, 'freeform', locale)
@@ -219,19 +208,19 @@ export async function discoverFreeformTranslations(locale, localesDir) {
   // Discover pages translations
   const pagesDir = join(freeformDir, 'pages')
   if (existsSync(pagesDir)) {
-    result.pages = await discoverMarkdownFiles(pagesDir, pagesDir)
+    result.pages = (await discoverMarkdownFiles(pagesDir, freeformDir)).sort()
   }
 
   // Discover page-ids translations
   const pageIdsDir = join(freeformDir, 'page-ids')
   if (existsSync(pageIdsDir)) {
-    result.pageIds = await discoverMarkdownFiles(pageIdsDir, pageIdsDir)
+    result.pageIds = (await discoverMarkdownFiles(pageIdsDir, freeformDir)).sort()
   }
 
   // Discover entity translations
   const entitiesDir = join(freeformDir, ENTITIES_DIR)
   if (existsSync(entitiesDir)) {
-    result.records = await discoverMarkdownFiles(entitiesDir, entitiesDir)
+    result.records = (await discoverMarkdownFiles(entitiesDir, freeformDir)).sort()
   }
 
   return result
@@ -287,6 +276,105 @@ export function parseFreeformPath(relativePath) {
   return { type: 'unknown', relativePath }
 }
 
+/**
+ * Every path a section's free-form translation is read from, in the order the renderer
+ * tries them (`loadFreeformTranslation`): `page-ids/<page id>/<section>.md` when the page
+ * has an `id`, then `pages/<route>/<section>.md` (`pages/<section>.md` for the root page).
+ *
+ * ⭐ ONE LIST, for the loader and for whatever judges a translation file against the
+ * site. ⛔ Until 2026-09-14 the orphan and stale check derived the first path alone
+ * (`buildFreeformPath`), so on a page with an `id` a route-addressed file the page
+ * rendered was reported orphaned and never checked for staleness.
+ *
+ * @param {Object} section - Section with stableId
+ * @param {Object} page - Page with route and optional id
+ * @returns {string[]} Paths relative to the locale's free-form directory; none when the
+ *   section has no stable id
+ */
+export function freeformPathsFor(section, page) {
+  const stableId = section?.stableId
+  if (!stableId) return []
+  const paths = []
+  if (page?.id) paths.push(`page-ids/${page.id}/${stableId}.md`)
+  const routePath = normalizeRouteForPath(page?.route || '/')
+  paths.push(routePath ? `pages/${routePath}/${stableId}.md` : `pages/${stableId}.md`)
+  return paths
+}
+
+/**
+ * Every section whose free-form translation the renderer looks up, with the page it
+ * looks it up for — the traversal `merge.js::mergeTranslationsAsync` makes: each page's
+ * sections, the 404 page's, and each layout area's (whose route it defaults to
+ * `/layout/[<name>/]<area>`), subsections included. Keep the two the same.
+ *
+ * @param {Object} siteContent
+ * @returns {Array<{ section: Object, page: Object }>}
+ */
+function freeformSections(siteContent) {
+  const out = []
+  const visit = (sections, page) => {
+    for (const section of sections || []) {
+      out.push({ section, page })
+      visit(section.subsections, page)
+    }
+  }
+  for (const page of siteContent?.pages || []) visit(page.sections, page)
+  if (siteContent?.notFound) visit(siteContent.notFound.sections, siteContent.notFound)
+  for (const [layoutName, areas] of Object.entries(siteContent?.layouts || {})) {
+    if (!areas || typeof areas !== 'object') continue
+    for (const [areaKey, layoutPage] of Object.entries(areas)) {
+      if (!layoutPage?.sections) continue
+      const route = layoutPage.route || `/layout/${layoutName === 'default' ? '' : layoutName + '/'}${areaKey}`
+      visit(layoutPage.sections, { ...layoutPage, route })
+    }
+  }
+  return out
+}
+
+/**
+ * What a site's content says about its free-form translations — the ONE index for the
+ * build's stale and orphan check and for the CLI's `status --freeform`, `update-hash` and
+ * `prune --freeform`, so no two of them can judge a file differently.
+ *
+ *   - `validPaths` — every path the renderer reads a section's translation from
+ *     (`freeformPathsFor`), for every section it translates;
+ *   - `sourceHashes` — the hash of the source a translation at each of those paths
+ *     translates, which a recorded hash is compared with;
+ *   - `canJudge(path)` — whether this content can say a translation at `path` is
+ *     orphaned. ⛔ Only a page section's (`pages/…`, `page-ids/…`), and not one for a page
+ *     whose sections the content does not carry — a prerendered site with split content
+ *     rewrites `site-content.json` without them. A record's (`entities/…`) is read from
+ *     records this content does not hold. A check that cannot see the source must never
+ *     call its translation orphaned: `prune --freeform` deletes what it is told is.
+ *
+ * @param {Object} siteContent - collected site content, as `dist/site-content.json` holds it
+ * @returns {{ validPaths: Set<string>, sourceHashes: Object<string, string>, canJudge: (path: string) => boolean }}
+ */
+export function freeformSourceIndex(siteContent) {
+  const validPaths = new Set()
+  const sourceHashes = {}
+  for (const { section, page } of freeformSections(siteContent)) {
+    for (const path of freeformPathsFor(section, page)) {
+      validPaths.add(path)
+      if (section.content) sourceHashes[path] = computeSourceHash(section.content)
+    }
+  }
+
+  // The directories a translation for a page with no `sections` would sit in.
+  const unseen = new Set()
+  for (const page of siteContent?.pages || []) {
+    if (Array.isArray(page?.sections)) continue
+    for (const path of freeformPathsFor({ stableId: '_' }, page)) unseen.add(dirname(path))
+  }
+
+  const canJudge = (path) =>
+    typeof path === 'string' &&
+    (path.startsWith('pages/') || path.startsWith('page-ids/')) &&
+    !unseen.has(dirname(path))
+
+  return { validPaths, sourceHashes, canJudge }
+}
+
 /**
  * Build the expected free-form translation path for a section
  *

package/src/i18n/index.js

@@ -34,6 +34,8 @@ import {
   getFreeformFileMeta,
   parseFreeformPath,
   buildFreeformPath,
+  freeformPathsFor,
+  freeformSourceIndex,
   buildFreeformRecordPath
 } from './freeform.js'
 import {
@@ -85,6 +87,8 @@ export {
   getFreeformFileMeta,
   parseFreeformPath,
   buildFreeformPath,
+  freeformPathsFor,
+  freeformSourceIndex,
   buildFreeformRecordPath,
 
   // Free-form manifest functions
@@ -426,24 +430,10 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
  */
 async function warnAboutFreeformIssues(locale, freeformDir, siteContent) {
   try {
-    // Build map of valid source hashes
-    const sourceHashes = {}
-    const validPaths = new Set()
-
-    for (const page of siteContent.pages || []) {
-      for (const section of page.sections || []) {
-        if (section.stableId) {
-          const path = buildFreeformPath(section, page)
-          if (path) {
-            validPaths.add(path)
-            // Compute source hash for staleness check
-            if (section.content) {
-              sourceHashes[path] = computeSourceHash(section.content)
-            }
-          }
-        }
-      }
-    }
+    // Every path the renderer reads a section's translation from, for every section it
+    // translates, with the hash of each source — the index the CLI's free-form commands
+    // judge by too (`freeformSourceIndex`).
+    const { validPaths, sourceHashes, canJudge } = freeformSourceIndex(siteContent)
 
     // Check for stale translations
     const stale = await getStaleTranslations(freeformDir, sourceHashes)
@@ -451,9 +441,11 @@ async function warnAboutFreeformIssues(locale, freeformDir, siteContent) {
       console.warn(`[i18n] Free-form translation stale: ${locale}/${item.path} (source changed ${item.recordedDate})`)
     }
 
-    // Check for orphaned translations
+    // Check for orphaned translations — only those this content can judge: never a
+    // record's (`entities/…`), which is read from records the site content does not hold.
     const orphaned = await getOrphanedTranslations(freeformDir, validPaths)
     for (const item of orphaned) {
+      if (!canJudge(item.path)) continue
       console.warn(`[i18n] Free-form translation orphaned: ${locale}/${item.path}`)
     }