@uniweb/build 0.15.13 → 0.16.0

package/src/validate-data.js

@@ -29,8 +29,9 @@ import { readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join, resolve, basename } from 'node:path'
 import yaml from 'js-yaml'
+import { collectionNameFromUrl } from '@uniweb/core'
 
-import { SCALAR_KINDS, FORMAT_TYPES } from './resolve-data-schema.js'
+import { SCALAR_KINDS, FORMAT_TYPES, validateAndNormalizeSchema } from './resolve-data-schema.js'
 import { buildSchema } from './schema.js'
 import { resolveFoundationSrcPath } from './utils/foundation-source-root.js'
 import { collectSiteContent } from './site/content-collector.js'
@@ -352,6 +353,13 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
     })
   }
 
+  // Pass 3 — concept blocks, which join to a schema by CONVENTION rather than
+  // by a foundation binding. Additive and silent unless a schema resolves.
+  const concepts = await validateConceptBlocks(site)
+  violations.push(...concepts.violations)
+  for (const ref of concepts.schemas) schemasSeen.add(ref)
+  recordCount += concepts.checked
+
   return {
     violations,
     deferred,
@@ -365,6 +373,161 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
   }
 }
 
+/**
+ * Check each ```md:<tag> concept block against `@std/<tag>`, when that schema
+ * exists.
+ *
+ * THREE PROPERTIES MAKE THIS SAFE, and all three have to hold:
+ *
+ * 1. It adds NO REGISTRY. The resolution is mechanical — `md:faq` → `@std/faq`,
+ *    the same `@std` → `@uniweb/schemas` mapping every other ref uses. What the
+ *    framework gains is a naming convention; no code branches on the value of a
+ *    tag, and nothing here knows which concepts exist. A hardcoded list of
+ *    concept names is the thing this whole design exists to avoid, and it would
+ *    arrive through this door if the check needed to know what `faq` means.
+ *
+ * 2. It never touches SHAPE. A concept block's shape comes from its fence,
+ *    unconditionally. This runs after the parse and changes nothing: a block
+ *    with no resolvable schema still parses, still delivers items, still
+ *    renders. The schema is a check, never a gate.
+ *
+ * 3. It never fails at RENDER. Findings only — this whole module is a pre-live
+ *    dev/CI gate and the runtime stays tolerant.
+ *
+ * ⛔ A standard schema for a concept MUST be authored in the ITEM vocabulary —
+ * `title`, `paragraphs`, and the rest of the parsed shape — because that is what
+ * a concept block always produces. An `@std/faq` written as `{ question, answer }`
+ * could only be checked with a per-concept field mapping, which is the forbidden
+ * registry arriving by the back door. Author the schema to match the parse, or
+ * do not ship the schema.
+ *
+ * ⛔ AND FOR A PROSE CONCEPT, NO FACET CAN FIRE AT ALL — so do not write an
+ * `@std` schema for one. Measured 2026-07-30:
+ *
+ *   - `required` is inert. The item vocabulary is TOTAL — `flattenGroup` fills
+ *     every field it declares, so a titleless item has `title: ''` rather than
+ *     no title, and `required` fires only on absent or null. "The author
+ *     actually wrote a question" is not expressible.
+ *   - `type` cannot fail either. Inside a concept block `title` is always a
+ *     string (never an array — `alwaysItems` suppresses the same-level merge
+ *     that would make one) and `paragraphs` is always an array of strings.
+ *   - which leaves `enum` / `format`, and neither has a natural application to
+ *     a question or an answer. The test suite had to invent `format: 'url'` on
+ *     a question to make anything fire — that is the tell, not a fixture quirk.
+ *
+ * The mechanism still earns its place, but it is waiting for a different shape:
+ * a concept that carries a tagged DATA BLOCK. Verified that one reaches the item
+ * — ```` ```md:steps ```` holding a ```` ```yaml:meta ```` gives
+ * `items[0].data.meta` — and there `required` fires when an author omits the
+ * block, `enum` constrains a status, `format` constrains a duration. That is the
+ * trigger to write a schema. Until then the frontend holds the concept names and
+ * their shapes, which is where they belong: its extension encodes the shape
+ * executably, and a `standard/faq.js` in `@uniweb/schemas` whose only consumer is
+ * that app would be this framework stating which concepts exist — the registry
+ * this design forbids, spelled as a filename instead of a switch.
+ *
+ * Note on resolution: this deliberately does NOT go through `resolveSchemaRef`,
+ * which resolves a package from a FOUNDATION's node_modules and throws when a
+ * ref is unknown. Neither fits — a concept block needs no foundation (so this
+ * works on a link-mode site whose foundation is a registry ref with nothing
+ * local), and an unresolved tag must be silent rather than an error. So the
+ * package is resolved from this build's own graph, where it is an
+ * optionalDependency, exactly as `i18n/collections.js` resolves it.
+ *
+ * @param {Object} site - collected site content (`{ pages }`)
+ * @returns {Promise<{ violations: Array, schemas: Set<string>, checked: number }>}
+ */
+export async function validateConceptBlocks(site) {
+  const empty = { violations: [], schemas: new Set(), checked: 0 }
+
+  const parse = await loadSemanticParser()
+  if (!parse) return empty // no parser available — nothing to derive items from
+
+  const standards = await loadStandardSchemas()
+  if (!standards) return empty // @uniweb/schemas absent — nothing to check against
+
+  const violations = []
+  const schemasSeen = new Set()
+  let checked = 0
+
+  for (const page of site.pages || []) {
+    walkSections(page.sections || [], (section) => {
+      const doc = section.content
+      if (doc?.type !== 'doc') return
+
+      for (const node of conceptBlockNodes(doc)) {
+        const tag = node.attrs?.tag
+        if (!tag) continue
+
+        const raw = standards(tag)
+        if (!raw) continue // no `@std/<tag>` — say nothing, by design
+
+        let schema
+        try {
+          schema = validateAndNormalizeSchema(raw, `@std/${tag}`)
+        } catch {
+          continue // a malformed standard schema is that package's problem
+        }
+        if (!isStaticallyCheckable(schema)) continue
+
+        schemasSeen.add(`@std/${tag}`)
+        const { items } = parse({ type: 'doc', content: node.content || [] }, { alwaysItems: true })
+
+        items.forEach((item, idx) => {
+          checked++
+          for (const finding of validateItem(schema, item)) {
+            violations.push({
+              file: `${page.route || '/'} › ${section.type || 'section'} › md:${tag}`,
+              schema: `@std/${tag}`,
+              item: `item ${idx + 1}`,
+              users: [{ route: page.route, section: section.type, key: tag }],
+              ...finding,
+            })
+          }
+        })
+      }
+    })
+  }
+
+  return { violations, schemas: schemasSeen, checked }
+}
+
+/** Every concept block in a doc, including any nested inside a container. */
+function conceptBlockNodes(doc) {
+  const out = []
+  const walk = (nodes) => {
+    for (const node of nodes || []) {
+      if (!node) continue
+      if (node.type === 'concept_block') out.push(node)
+      else if (Array.isArray(node.content)) walk(node.content)
+    }
+  }
+  walk(doc?.content)
+  return out
+}
+
+/** `parseContent`, or null when the parser is not installed. */
+async function loadSemanticParser() {
+  try {
+    const mod = await import('@uniweb/semantic-parser')
+    return typeof mod.parseContent === 'function' ? mod.parseContent : null
+  } catch {
+    return null
+  }
+}
+
+/** A `(name) => schema | undefined` lookup over `@std`, or null when absent. */
+async function loadStandardSchemas() {
+  try {
+    const mod = await import('@uniweb/schemas')
+    if (typeof mod.getSchema === 'function') return (name) => mod.getSchema(name)
+    const table = mod.schemas ?? mod.default
+    return table ? (name) => table[name] : null
+  } catch {
+    return null
+  }
+}
+
 /**
  * The data inputs available to a section, deduped by key. A section receives
  * its own fetch plus any inherited page-level and site-level fetch (default-on
@@ -402,8 +565,9 @@ function walkSections(sections, visit) {
  * (hand-authored data) is read from disk. Either way no prior build is needed.
  */
 async function resolveRecords(path, { collections, siteRoot }) {
-  // `/data/<name>.json` → a declared collection? Use the compiled records.
-  const name = path.replace(/^\/?data\//, '').replace(/\.json$/i, '')
+  // A compiled-collection URL → a declared collection? Use the compiled
+  // records. Anything else falls through to the file read below.
+  const name = collectionNameFromUrl(path)
   let records
   if (Object.prototype.hasOwnProperty.call(collections, name)) {
     records = collections[name]