@uniweb/build 0.47.1 → 0.48.0

package/src/uwx/site-project.js

@@ -32,9 +32,10 @@
 // we unwrap to the source locale for the file surface (other locales stay in
 // the i18n pipeline). Absent `info` keys are left untouched on disk.
 
-import { join, relative, extname, basename } from 'node:path'
+import { join, relative, extname, basename, dirname } from 'node:path'
 import { readAssetMap, restoreAssetRefs } from './asset-map.js'
-import { readFileSync, existsSync, unlinkSync, renameSync, rmSync, readdirSync, statSync } from 'node:fs'
+import { readFileSync, existsSync, unlinkSync, renameSync, rmSync, readdirSync, statSync, mkdirSync } from 'node:fs'
+import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
 import { createHash } from 'node:crypto'
 import yaml from 'js-yaml'
 import { writeSiteConfig, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
@@ -695,59 +696,90 @@ function prunePagesTree(pages, pagesDir, sourceLocale, report) {
   if (incomingDirs.size > 0) pruneOrphanPageDirs(pagesDir, incomingDirs, report)
 }
 
-// The file a layout section maps to: `layout/<area>.md` (the 'default' layout) or
-// `layout/<layout_name>/<area>.md`. Inverse of site.js collectLayoutNested.
-function layoutFilePath(layoutBaseDir, record) {
-  const area = record.area || recordStableId(record)
-  if (!area) return null
-  const named = record.layout_name && record.layout_name !== 'default' ? record.layout_name : null
-  return named ? join(layoutBaseDir, named, `${area}.md`) : join(layoutBaseDir, `${area}.md`)
-}
-
-// A layout subdir the producer treats as a named layout (not an `_`-prefixed
-// organizational folder, the only thing collectLayoutNested skips).
-function isNamedLayoutDir(name) {
-  return !name.startsWith('_')
+/**
+ * Where each layout section lives, relative to the layout folder — the ONE placement,
+ * shared by the pull (`projectLayout`) and the site diff's unit keys (`site-diff.js`).
+ *
+ * The inverse of `readLayoutFolder` (`../site/layout-folder.js`): an area with one
+ * section is a file — `<area>.md` in the default layout, `<layout>/<area>.md` in a
+ * named one — and an area with several is a folder of prefixed files,
+ * `<layout>/<area>/<n>-<id>.md`, with `default/<area>/` for the default layout.
+ * A layout name is compared regardless of case, as the runtime matches it.
+ *
+ * @param {Array<object>} layoutSections - `layout_sections` records, in order
+ * @returns {Array<{ record: object, relPath: string }>}
+ */
+export function layoutSectionPaths(layoutSections) {
+  const groups = new Map()
+  for (const record of layoutSections || []) {
+    const area = record?.area || recordStableId(record)
+    if (!area) continue
+    const named = typeof record.layout_name === 'string' && record.layout_name && record.layout_name.toLowerCase() !== 'default'
+    const layout = named ? record.layout_name : 'default'
+    const key = `${layout.toLowerCase()}/${area}`
+    if (!groups.has(key)) groups.set(key, { layout, area, records: [] })
+    groups.get(key).records.push(record)
+  }
+  const out = []
+  for (const { layout, area, records } of groups.values()) {
+    if (records.length === 1) {
+      out.push({ record: records[0], relPath: layout === 'default' ? `${area}.md` : `${layout}/${area}.md` })
+      continue
+    }
+    records.forEach((record, i) => {
+      const id = recordStableId(record) || `s${i + 1}`
+      out.push({ record, relPath: `${layout}/${area}/${i + 1}-${safeStableIdFilename(id)}.md` })
+    })
+  }
+  return out
 }
 
-// Delete orphan layout `.md` files (default-layout files in layoutBaseDir and
-// named-layout files in its subdirs) not in `keep`, and remove a named-layout dir
-// left empty. `_`-prefixed organizational folders are never touched.
+// Delete orphan layout section files not in `keep` — at every depth the layout
+// folder reader reads (`<area>.md`, `<layout>/<area>.md`, `<layout>/<area>/*.md`) —
+// and remove an area or layout folder left empty. Only files the reader treats as
+// sections are touched: `_`-prefixed drafts, READMEs and `_`/`.` folders are left alone.
 function pruneOrphanLayout(layoutBaseDir, keep, report) {
   if (!existsSync(layoutBaseDir)) return
-  for (const entry of readdirSync(layoutBaseDir)) {
-    const p = join(layoutBaseDir, entry)
-    const st = statSync(p)
-    if (st.isFile()) {
-      if (extname(entry).toLowerCase() === '.md' && !keep.has(p)) {
-        unlinkSync(p)
-        report.deleted.push(p)
-      }
-    } else if (st.isDirectory() && isNamedLayoutDir(entry)) {
-      for (const f of readdirSync(p)) {
-        const fp = join(p, f)
-        if (statSync(fp).isFile() && extname(f).toLowerCase() === '.md' && !keep.has(fp)) {
-          unlinkSync(fp)
-          report.deleted.push(fp)
-        }
-      }
-      if (readdirSync(p).length === 0) {
-        rmSync(p, { recursive: true, force: true })
-        report.deleted.push(p)
+  const pruneSectionFiles = (dir) => {
+    for (const f of readdirSync(dir)) {
+      const fp = join(dir, f)
+      if (isMarkdownFile(f) && statSync(fp).isFile() && !keep.has(fp)) {
+        unlinkSync(fp)
+        report.deleted.push(fp)
       }
     }
   }
+  const removeIfEmpty = (dir) => {
+    if (readdirSync(dir).length === 0) {
+      rmSync(dir, { recursive: true, force: true })
+      report.deleted.push(dir)
+    }
+  }
+  pruneSectionFiles(layoutBaseDir)
+  for (const entry of readdirSync(layoutBaseDir)) {
+    const layoutDir = join(layoutBaseDir, entry)
+    if (isIgnoredFolder(entry) || !statSync(layoutDir).isDirectory()) continue
+    pruneSectionFiles(layoutDir)
+    for (const sub of readdirSync(layoutDir)) {
+      const areaDir = join(layoutDir, sub)
+      if (isIgnoredFolder(sub) || !statSync(areaDir).isDirectory()) continue
+      pruneSectionFiles(areaDir)
+      removeIfEmpty(areaDir)
+    }
+    removeIfEmpty(layoutDir)
+  }
 }
 
 // Project layout_sections → layout/**. TWO PASSES (like projectPages): pass 1
 // writes + relocates each file (uuid-anchored, so an app-side (layout_name, area)
 // change is a move, not delete + create); pass 2 prunes orphan files + emptied
-// named-layout dirs. Pruning is guarded against an empty incoming set.
+// layout and area folders. Pruning is guarded against an empty incoming set.
 function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
   const written = []
-  for (const record of layoutSections || []) {
-    const filePath = layoutFilePath(layoutBaseDir, record)
-    if (!filePath) continue
+  for (const { record, relPath } of layoutSectionPaths(layoutSections)) {
+    const filePath = join(layoutBaseDir, relPath)
+    // A relocation into a new area folder needs the folder first.
+    mkdirSync(dirname(filePath), { recursive: true })
     placeByUuid(ctx, record.$uuid, filePath)
     sectionRecordToFile({ filePath, record, sourceLocale: ctx?.sourceLocale, collector: ctx?.collector })
     report.layout.push(filePath)

package/src/uwx/site.js

@@ -57,7 +57,8 @@ import {
   fetchFromQueryShorthand,
   assertRouteFolder,
 } from '../site/content-collector.js'
-import { refuseUnder } from '../site/data-fetcher.js'
+import { refuseBinding, refuseUnder, refuseOutsideLanguage, warnDuplicateBindings } from '../site/data-fetcher.js'
+import { readLayoutFolder } from '../site/layout-folder.js'
 import { normalizeHideIn } from '../site/nav-visibility.js'
 import { resolveDefaultLocale, validateLanguageConfig, queryDataUrl } from '@uniweb/core'
 import { emitEntitySyncPackage } from './entity-document.js'
@@ -242,10 +243,11 @@ function buildPageData(config, ctx) {
   // `fetch:`, or the `query:` shorthand, read and refused exactly as the build
   // reads them (`declaredFetch`) — a `folder.yml` as much as a `page.yml`.
   let fetch = declaredFetch(config, where ?? 'page.yml')
-  // `where: { path: { under } }` is refused here as the build refuses it
-  // (`parseFetchConfig`): a site that cannot build must not sync either. A
-  // section's fetch is refused where the collector parses it.
-  for (const one of [fetch].flat()) refuseUnder(one?.where, 'fetch')
+  // Refused here as the build refuses it (`refuseBinding`, the one list): a site
+  // that cannot build must not sync either. A section's fetch is refused where the
+  // collector parses it.
+  for (const one of [fetch].flat()) refuseBinding(one, where ?? 'page.yml', { level: 'page' })
+  warnDuplicateBindings([fetch].flat(), where ?? 'page.yml')
   // Resolve the authored `query:` shorthand to the runtime-fetchable
   // `path: /data/<name>.json` (the static convention the default-fetcher uses).
   // A shell/backend-hosted site renders client-side with NO prerender, so the
@@ -259,6 +261,8 @@ function buildPageData(config, ctx) {
   // `path`, no `as` and no `schema`. That is the silent-empty class: a payload
   // that arrives, parses, and resolves to nothing.
   const resolveWireFetch = (one) => {
+    // ⭐ A string is a query name — the wire carries the object form.
+    if (typeof one === 'string') one = { query: one }
     if (!one || typeof one.query !== 'string') return one
     const { query, ...rest } = one
     // ⭐ BOTH, deliberately, and they are not redundant.
@@ -599,34 +603,28 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
   return out
 }
 
-// layout_sections: top-level self-nesting, keyed by (layout_name, area) in data.
-// Same per-area walk as collectLayoutSections, emitted as `$`-records.
+// layout_sections: top-level self-nesting, keyed by (layout_name, area) in data —
+// one `$`-record per section, in area order and then section order.
+//
+// ⭐ Read through `readLayoutFolder` (`../site/layout-folder.js`), the ONE reader the
+// build uses too, so the two cannot disagree about what `layout/` holds. ⛔ They did
+// until 2026-09-13: this walk called every folder a named layout and read only the
+// files directly inside it, while the build called a folder an area of the default
+// layout unless the foundation declared a layout by that name.
 async function collectLayoutNested(layoutDir, siteRoot) {
-  if (!existsSync(layoutDir)) return []
+  const areas = await readLayoutFolder(layoutDir, { siteRoot })
   const items = []
   let order = 0
-  async function addArea(filePath, layoutName, area) {
-    const { section } = await processMarkdownFile(filePath, String(order + 1), siteRoot, area)
-    const stable = section.stableId || String(order)
-    items.push(
-      withIdentity(stable, { layout_name: layoutName, area, ...mapSectionData(section) })
-    )
-    order++
-  }
-  const entries = await readdir(layoutDir, { withFileTypes: true })
-  const rootMd = entries
-    .filter((e) => e.isFile() && isMarkdownFile(e.name))
-    .map((e) => e.name)
-    .sort(compareFilenames)
-  for (const file of rootMd) {
-    await addArea(join(layoutDir, file), 'default', parseNumericPrefix(parse(file).name).name)
-  }
-  for (const e of entries) {
-    if (!e.isDirectory() || isIgnoredFolder(e.name)) continue
-    const sub = join(layoutDir, e.name)
-    const md = (await readdir(sub)).filter(isMarkdownFile).sort(compareFilenames)
-    for (const file of md) {
-      await addArea(join(sub, file), e.name, parseNumericPrefix(parse(file).name).name)
+  for (const area of areas) {
+    for (const file of area.files) {
+      // A one-section area's stable id is the area's name, as it always was; a
+      // section of a multi-section area is named the way a page's section is.
+      const { name } = parse(file)
+      const fallback = area.form === 'file' ? area.area : (parseNumericPrefix(name).name || name)
+      const { section } = await processMarkdownFile(join(area.dir, file), String(order + 1), siteRoot, fallback)
+      const stable = section.stableId || String(order)
+      items.push(withIdentity(stable, { layout_name: area.layout, area: area.area, ...mapSectionData(section) }))
+      order++
     }
   }
   return items
@@ -774,11 +772,10 @@ export function isSiteRelativeExtensionUrl(decl) {
 // that is neither emitted nor listed here.
 // Authored keys the explicit block in `queriesNested` already consumes. Kept
 // separate from the framework-local set below because these DO reach the wire —
-// just under a wire spelling. ⚠️ `detailUrl` is the one that matters: it is emitted
-// as `detail_url`, so a pass-through keyed on "is it already in `data`?" does not
-// see it and the field rides TWICE. Measured 2026-08-29, in the first draft of this
-// very change — and the push test missed it because both its controls (`limit`,
-// `schema`) keep their names.
+// some under a wire spelling. ⚠️ A key emitted under another name is the one that
+// matters: a pass-through keyed on "is it already in `data`?" does not see it and
+// the field rides TWICE (measured 2026-08-29 with `detailUrl` → `detail_url`, which
+// was retired on 2026-09-13 — an external query's `record:` rides in `source`).
 const DECL_EMITTED_ABOVE = new Set([
   'source',
   'schema',
@@ -787,16 +784,19 @@ const DECL_EMITTED_ABOVE = new Set([
   'limit',
   'excerpt',
   'deferred',
-  'detailUrl',
   'queryable'
 ])
 
 const DECL_NOT_ON_WIRE = new Set([
   // Identity — rides as the record's own `name`, not inside `data`.
   'name',
-  // Folded into `source` above.
+  // Folded into `source` above — an external query's whole source.
   'path',
   'url',
+  'method',
+  'body',
+  'transform',
+  'record',
   // Folded into `schema` above (the migration synonym).
   'model',
   // Build state: whether the AUTHOR asked for the schema or the subfolder-name
@@ -816,12 +816,26 @@ const DECL_NOT_ON_WIRE = new Set([
   'filter'
 ])
 
+/** An external query's source, as it rides in the `queries` Section's `source`. */
+function externalSource(d) {
+  const source = { url: d.url }
+  setIf(source, 'method', d.method)
+  setIf(source, 'body', d.body)
+  setIf(source, 'transform', d.transform)
+  setIf(source, 'record', d.record)
+  return source
+}
+
 function queriesNested(declarations, uuids = null, org = null) {
   const out = []
   for (const [name, d] of Object.entries(declarations)) {
     refuseUnder(d.where, `queries.${name}`)
+    refuseOutsideLanguage(d.where, `queries.${name}`)
     const data = {}
-    const source = d.path ? { path: d.path } : d.url ? { url: d.url } : d.source
+    // ⭐ AN EXTERNAL QUERY'S SOURCE, WHOLE — `url`, `method`, `body`, `transform` and
+    // `record` — so a host can put it on the payload's `config.queries[<name>]`, where
+    // the runtime fetches it from (never the records service).
+    const source = d.path ? { path: d.path } : d.url !== undefined ? externalSource(d) : d.source
     setIf(data, 'source', source)
     // ⛔ QUALIFIED, WITH THE SAME RULE AND THE SAME ORG AS THE RECORDS' `$model`
     // (`records.js::buildRecordEntities`). A consumer answers a query by matching
@@ -837,7 +851,6 @@ function queriesNested(declarations, uuids = null, org = null) {
     setIf(data, 'limit', d.limit)
     setIf(data, 'excerpt', d.excerpt)
     setIf(data, 'deferred', d.deferred)
-    setIf(data, 'detail_url', d.detailUrl)
     setIf(data, 'queryable', d.queryable)
     // ⛔ EMIT WHAT WE DO NOT MODEL. The decl's field set is the BACKEND's Model
     // (this document mirrors `@uniweb/site-content` — see the lane header), and
@@ -1092,7 +1105,8 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // the `query:` shorthand carries no `where`. ⚠️ The desugaring stays inline in
   // `setIf`: `gen-emit-surface.mjs` reads the published key's sources off it.
   checkDeclaration(siteYml, 'site.yml')
-  for (const one of [siteYml.fetch].flat()) refuseUnder(one?.where, 'site.yml fetch')
+  for (const one of [siteYml.fetch].flat()) refuseBinding(one, 'site.yml fetch', { level: 'site' })
+  warnDuplicateBindings([siteYml.fetch ?? fetchFromQueryShorthand(siteYml.query)].flat(), 'site.yml')
   setIf(settings, 'fetch', siteYml.fetch ?? fetchFromQueryShorthand(siteYml.query))
 
   // ⭐ The SITE TIER of framework's own `{name, hide, params}` layout object, which

package/src/validate-data.js

@@ -27,7 +27,7 @@ import { readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join, resolve, basename } from 'node:path'
 import yaml from 'js-yaml'
-import { queryNameFromUrl } from '@uniweb/core'
+import { queryNameFromUrl, siteReaches } from '@uniweb/core'
 
 import { validateItem, isStaticallyCheckable, validateBound } from '@uniweb/schemas/conform'
 import { validateAndNormalizeSchema } from './resolve-data-schema.js'
@@ -108,7 +108,8 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
       const type = section.type
       if (!type) return
       const bindings = foundation[type]?.data
-      const inputs = collectInputs(section, page.fetch, config.fetch)
+      // the site's binding reaches a top-level page's sections only (`siteReaches`)
+      const inputs = collectInputs(section, page.fetch, siteReaches(page.parent) ? config.fetch : null)
 
       // ⭐ **THE JOIN, RUN THE OTHER WAY: data arrived, but under no name this
       // section reads.** Everything below asks "for each input, is there a
@@ -150,8 +151,10 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
       for (const input of inputs) {
         const key = input.as // the content.data KEY
 
-        if (input.url) {
-          deferred.push({ route: page.route, section: type, key, reason: 'remote url: source', url: input.url })
+        // An external query's records are its address's, fetched where the page renders.
+        const external = typeof input.query === 'string' ? config.queries?.[input.query]?.url : undefined
+        if (input.url || external) {
+          deferred.push({ route: page.route, section: type, key, reason: 'external query', url: input.url ?? external })
           continue
         }
         if (!input.path) continue