@uniweb/build 1.10.4 → 1.10.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.10.4",
+  "version": "1.10.5",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -56,11 +56,11 @@
     "js-yaml": "^4.3.2",
     "sharp": "^0.35.5",
     "yaml": "^2.5.0",
-    "@uniweb/semantic-parser": "~1.13.0",
     "@uniweb/content-reader": "~1.5.7",
-    "@uniweb/content-writer": "~1.3.1",
     "@uniweb/schemas": "~1.6.5",
+    "@uniweb/semantic-parser": "~1.13.0",
     "@uniweb/projections": "~1.2.1",
+    "@uniweb/content-writer": "~1.3.1",
     "@uniweb/theming": "~1.2.1"
   },
   "optionalDependencies": {
@@ -73,8 +73,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "~1.4.7",
-    "@uniweb/runtime": "~1.2.3"
+    "@uniweb/runtime": "~1.2.3",
+    "@uniweb/core": "~1.4.7"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/site/content-collector.js

@@ -40,6 +40,7 @@ import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig
 import { authoredRedirectTarget } from '@uniweb/core/resolve-route'
 import { parentRouteOf } from '@uniweb/core/route-match'
 import { parseFrontmatter } from '../utils/frontmatter.js'
+import { valuesCutByComment } from '../utils/yaml-comment-trap.js'
 import { parseGrid } from '@uniweb/schemas/grid'
 import { runtimeServicesConfig, refuseRetiredServiceKeys, refuseUnreadableServices } from '../uwx/services-request.js'
 import { refuseUnreadableAddress } from './site-address.js'
@@ -438,6 +439,20 @@ let yamlFailures = []
  */
 let sectionTypes = null
 
+/** The site being collected, so a warning names a file as its author sees it. Reset per collect, as `yamlFailures` is. */
+let collectRoot = null
+
+/**
+ * Say each value the file's YAML cut short at a `#` its author meant as part of it — a
+ * gradient, a color (`../utils/yaml-comment-trap.js`). A warning, not a failure: the YAML is
+ * valid, and the site builds without the value, as it did before anything said so.
+ */
+function warnCutByComment(text, parsed, file) {
+  for (const { message } of valuesCutByComment(text, parsed)) {
+    console.warn(`[content-collector] ${collectRoot ? relative(collectRoot, file) : file}: ${message}`)
+  }
+}
+
 /**
  * Parse YAML, recording a failure against the file it came from.
  *
@@ -449,7 +464,9 @@ let sectionTypes = null
  */
 function parseYaml(yamlString, source = '<unknown>') {
   try {
-    return yaml.load(yamlString, YAML_OPTIONS) || {}
+    const parsed = yaml.load(yamlString, YAML_OPTIONS) || {}
+    warnCutByComment(yamlString, parsed, source)
+    return parsed
   } catch (err) {
     yamlFailures.push({ source, message: err.message })
     console.warn(`[content-collector] YAML parse error in ${source}: ${err.message}`)
@@ -1097,6 +1114,7 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
     const parsed = parseFrontmatter(content, filePath)
     frontMatter = parsed.frontmatter
     markdown = parsed.body
+    warnCutByComment(parsed.yaml, frontMatter, filePath)
   } catch (err) {
     yamlFailures.push({ source: filePath, message: err.message })
     console.warn(`[content-collector] ${err.message}`)
@@ -2556,6 +2574,7 @@ export async function collectSiteContent(sitePath, options = {}) {
   // still be counted.
   yamlFailures = []
   sectionTypes = null
+  collectRoot = sitePath
 
   // Read site config and raw theme config
   const siteConfig = await readYamlFile(join(sitePath, configFile))

package/src/utils/frontmatter.js

@@ -51,24 +51,25 @@ import { YAML_OPTIONS } from './yaml-schema.js'
  * @param {string} [filepath] - where it came from. Optional only because a
  *   caller may genuinely not have one; pass it whenever you do, since the file
  *   name is the difference between a fixable error and a hunt.
- * @returns {{ frontmatter: object, body: string }}
+ * @returns {{ frontmatter: object, body: string, yaml: string }} `yaml` is the block as
+ *   written, for a caller that reads what the parse cannot say (`./yaml-comment-trap.js`)
  * @throws {Error} when a `---` block is present and does not parse as YAML
  */
 export function parseFrontmatter(raw, filepath) {
   const text = raw ?? ''
   if (!text.trimStart().startsWith('---')) {
-    return { frontmatter: {}, body: text }
+    return { frontmatter: {}, body: text, yaml: '' }
   }
 
   const parts = text.split('---\n')
   if (parts.length < 3) {
-    return { frontmatter: {}, body: text }
+    return { frontmatter: {}, body: text, yaml: '' }
   }
 
   try {
     const frontmatter = yaml.load(parts[1], YAML_OPTIONS) || {}
     const body = parts.slice(2).join('---\n')
-    return { frontmatter, body }
+    return { frontmatter, body, yaml: parts[1] }
   } catch (err) {
     const where = filepath ? `${filepath}: ` : ''
     throw new Error(

package/src/utils/yaml-comment-trap.js

@@ -0,0 +1,77 @@
+/**
+ * Values YAML cut short at a `#` the author meant as part of them.
+ *
+ * YAML reads a `#` with a space before it as the start of a comment, so in a plain (unquoted)
+ * value it ends the value there: `gradient: linear-gradient(165deg, #0c1226 0%, #05060f 100%)`
+ * is `linear-gradient(165deg,` — an invalid value, which the browser drops — and
+ * `primary: #3b82f6` is no value at all. YAML is right; nothing in the file is malformed, so
+ * nothing fails, and the color or the gradient is just not there.
+ *
+ * Said only where the file shows it, so a comment meant as one is never questioned:
+ *   - **cut** — a value left with a `(` it never closes, followed in the file by ` #`;
+ *   - **empty** — a key left with no value, followed in the file by a color: `#` and 3 to 8
+ *     hex digits.
+ *
+ * ⭐ Quoting the value is the fix, and the one the message gives:
+ * `gradient: "linear-gradient(165deg, #0c1226 0%, #05060f 100%)"`. Measured 2026-10-26: a book
+ * page's gradient had not shown since the page was written, in either renderer, and nothing
+ * said so.
+ *
+ * @module @uniweb/build/utils/yaml-comment-trap
+ */
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** More `(` than `)`: a function the value opens and never closes. */
+function unclosed(value) {
+  let depth = 0
+  for (const ch of value) {
+    if (ch === '(') depth++
+    else if (ch === ')' && depth > 0) depth--
+  }
+  return depth > 0
+}
+
+/**
+ * @param {string} text - the YAML as written
+ * @param {*} parsed - what it parsed to
+ * @returns {{ path: string, kind: 'cut'|'empty', message: string }[]}
+ */
+export function valuesCutByComment(text, parsed) {
+  if (!text || !text.includes('#') || !parsed || typeof parsed !== 'object') return []
+  const found = []
+  const walk = (value, path, key) => {
+    if (Array.isArray(value)) {
+      value.forEach((v, i) => walk(v, `${path}[${i}]`, null))
+      return
+    }
+    if (value && typeof value === 'object' && !(value instanceof Date)) {
+      for (const [k, v] of Object.entries(value)) walk(v, path ? `${path}.${k}` : k, k)
+      return
+    }
+    if (typeof value === 'string' && unclosed(value)) {
+      const m = text.match(new RegExp(`${escapeRe(value)}[ \\t]+(#.*?)[ \\t]*$`, 'm'))
+      if (!m) return
+      const meant = `${value} ${m[1]}`
+      found.push({
+        path,
+        kind: 'cut',
+        message:
+          `\`${path}\` is cut short at \`${value}\` — YAML reads a \`#\` after a space as a comment. ` +
+          `Quote the value: ${key ?? path}: "${meant.replace(/"/g, '\\"')}"`
+      })
+      return
+    }
+    if (value === null && key) {
+      const m = text.match(new RegExp(`^[ \\t]*(?:-[ \\t]+)?${escapeRe(key)}[ \\t]*:[ \\t]+(#[0-9A-Fa-f]{3,8})\\b`, 'm'))
+      if (!m) return
+      found.push({
+        path,
+        kind: 'empty',
+        message: `\`${path}\` is empty — YAML reads \`${m[1]}\` as a comment. Quote the value: ${key}: "${m[1]}"`
+      })
+    }
+  }
+  walk(parsed, '', null)
+  return found
+}