uniweb 1.0.0 → 1.0.2

package/src/commands/validate.js

@@ -0,0 +1,376 @@
+/**
+ * uniweb validate - Check your content against the data schemas your
+ * foundation declares.
+ *
+ * For each section that consumes file-based data, this resolves the schema the
+ * foundation bound to that input (via `meta.js` `data:`) and checks the data
+ * items against it — and every record file in the records directory against the
+ * schema its folder names, whether or not a section reads it. It answers "does my
+ * data match what I promised?" — distinct from `doctor`, which checks your project
+ * against framework conventions.
+ *
+ * ⭐ A violation fails it (exit 1); `--lax` reports without failing. It warned by
+ * default until 2026-09-24, with `--strict` to fail — a gate that passes is one
+ * nobody reads, and `push` / `publish` now refuse the same findings. The live render
+ * path stays tolerant. Remote (`url:`) inputs are not in the project, so they're
+ * reported as deferred, never silently skipped. The value of an entity reference is
+ * not checked against the entity it names. ⛔ This said references were "reported as
+ * deferred" until 2026-09-24; no check ever reported them.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve, basename } from 'node:path'
+import yaml from 'js-yaml'
+import { validateDataInputs } from '@uniweb/build'
+import { discoverFoundations, discoverSites } from '../utils/discover.js'
+import { findWorkspaceRoot } from '../utils/workspace.js'
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[36m'
+}
+
+const log = console.log
+const success = (msg) => log(`${colors.green}✓${colors.reset} ${msg}`)
+const warn = (msg) => log(`${colors.yellow}⚠${colors.reset} ${msg}`)
+const error = (msg) => console.error(`${colors.red}✗${colors.reset} ${msg}`)
+const info = (msg) => log(`${colors.blue}→${colors.reset} ${msg}`)
+
+/**
+ * Read a flag that takes a value: `--site foo` or `--site=foo`.
+ */
+function flagValue(args, name) {
+  const eq = args.find((a) => a.startsWith(`${name}=`))
+  if (eq) return eq.slice(name.length + 1)
+  const idx = args.indexOf(name)
+  if (idx !== -1 && args[idx + 1] && !args[idx + 1].startsWith('--'))
+    return args[idx + 1]
+  return null
+}
+
+function loadSiteYml(dir) {
+  for (const f of ['site.yml', 'site.yaml']) {
+    const p = join(dir, f)
+    if (existsSync(p)) {
+      try {
+        return yaml.load(readFileSync(p, 'utf8'))
+      } catch {
+        return null
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Validate one site against its local foundation.
+ *
+ * @returns {Promise<Object>} { site, foundation, status, report?, reason? }
+ *   status: 'checked' | 'skipped'
+ */
+async function validateSite(site, foundations, workspaceDir) {
+  const sitePath = join(workspaceDir, site.path)
+  const siteYml = loadSiteYml(sitePath)
+  const foundationName = siteYml?.foundation
+
+  // No local foundation to check against → out of static scope (the schemas
+  // live in the foundation; a registry-ref / URL foundation isn't on disk).
+  if (!foundationName) {
+    return {
+      site: site.name,
+      status: 'skipped',
+      reason: 'no foundation declared in site.yml (runtime-loaded?)'
+    }
+  }
+  const match = foundations.find(
+    (f) => f.name === foundationName || basename(f.path) === foundationName
+  )
+  if (!match) {
+    return {
+      site: site.name,
+      status: 'skipped',
+      reason: `foundation "${foundationName}" is not a local workspace foundation — its schemas aren't on disk to check against`
+    }
+  }
+
+  const foundationPath = join(workspaceDir, match.path)
+  const report = await validateDataInputs({
+    siteRoot: sitePath,
+    foundationPath
+  })
+  return { site: site.name, foundation: match.name, status: 'checked', report }
+}
+
+/**
+ * Print one site's findings in human form. Groups by the (file, schema) pair
+ * so a collection feeding many sections lists its findings once, with the
+ * sections that use it — every link of the chain (route › section › key › file
+ * › item › field) is present, de-duped.
+ */
+function printSiteHuman(result) {
+  log('')
+  if (result.status === 'skipped') {
+    warn(
+      `${colors.bright}${result.site}${colors.reset} — skipped: ${result.reason}`
+    )
+    return
+  }
+
+  const { report, foundation } = result
+  const { violations, deferred, setupErrors, summary } = report
+  const header = `${colors.bright}${result.site}${colors.reset} ${colors.dim}(foundation: ${foundation})${colors.reset}`
+
+  if (violations.length === 0 && setupErrors.length === 0) {
+    success(
+      `${header} — ${summary.records} record(s) / ${summary.schemas} schema(s) conform`
+    )
+  } else {
+    info(header)
+  }
+
+  // Group violations by file+schema pair.
+  const groups = new Map()
+  for (const v of violations) {
+    const key = `${v.file} ${v.schema}`
+    if (!groups.has(key))
+      groups.set(key, {
+        file: v.file,
+        schema: v.schema,
+        users: v.users,
+        findings: []
+      })
+    groups.get(key).findings.push(v)
+  }
+  for (const g of groups.values()) {
+    log(
+      `  ${colors.red}✗${colors.reset} ${g.file} ${colors.dim}· schema ${g.schema}${colors.reset}`
+    )
+    for (const u of dedupeUsers(g.users)) {
+      log(
+        `      ${colors.dim}used by${colors.reset} ${u.route} › ${u.section} › data.${u.key}`
+      )
+    }
+    for (const f of g.findings) {
+      log(
+        `      ${colors.yellow}•${colors.reset} item ${colors.bright}"${f.item}"${colors.reset} › ${f.field} — ${f.message}`
+      )
+    }
+  }
+
+  for (const e of setupErrors) {
+    log(`  ${colors.red}✗${colors.reset} ${e.file} — ${e.message}`)
+    for (const u of dedupeUsers(e.users)) {
+      log(
+        `      ${colors.dim}used by${colors.reset} ${u.route} › ${u.section} › data.${u.key}`
+      )
+    }
+  }
+
+  if (deferred.length > 0) {
+    log(`  ${colors.dim}↪ deferred (not checked):${colors.reset}`)
+    for (const d of deferred) {
+      const extra = d.url
+        ? ` ${colors.dim}(${d.url})${colors.reset}`
+        : d.ref
+          ? ` ${colors.dim}(${d.ref})${colors.reset}`
+          : ''
+      log(
+        `      ${colors.dim}•${colors.reset} ${d.route} › ${d.section} › data.${d.key} — ${d.reason}${extra}`
+      )
+    }
+  }
+
+  log(
+    `  ${colors.dim}${summary.records} record(s) · ${summary.schemas} schema(s) · ` +
+      `${summary.violations} violation(s) · ${summary.deferred} deferred${colors.reset}`
+  )
+}
+
+function dedupeUsers(users) {
+  const seen = new Set()
+  const out = []
+  for (const u of users || []) {
+    const k = `${u.route} ${u.section} ${u.key}`
+    if (seen.has(k)) continue
+    seen.add(k)
+    out.push(u)
+  }
+  return out
+}
+
+export async function validate(args = []) {
+  const asJson = args.includes('--json')
+  // A violation fails the run unless `--lax` says to only report it. (`--strict`, the
+  // flag that turned failing on until 2026-09-24, is simply the default now.)
+  const strict = !args.includes('--lax')
+  const siteFilter = flagValue(args, '--site')
+  const positional = args.find(
+    (a, i) => !a.startsWith('--') && args[i - 1] !== '--site'
+  )
+
+  const target = positional ? resolve(process.cwd(), positional) : process.cwd()
+  const workspaceDir = findWorkspaceRoot(target)
+
+  if (!workspaceDir) {
+    if (asJson)
+      log(
+        JSON.stringify(
+          { ok: false, error: 'not in a Uniweb workspace' },
+          null,
+          2
+        )
+      )
+    else
+      error(
+        'Not in a Uniweb workspace. Run this from a project root or a site directory.'
+      )
+    return { exitCode: 2 }
+  }
+
+  const [sites, foundations] = await Promise.all([
+    discoverSites(workspaceDir),
+    discoverFoundations(workspaceDir)
+  ])
+
+  // Select which sites to check: --site filter, an explicitly targeted site
+  // directory, or all sites in the workspace.
+  let selected = sites
+  if (siteFilter) {
+    selected = sites.filter(
+      (s) => s.name === siteFilter || basename(s.path) === siteFilter
+    )
+    if (selected.length === 0) {
+      const names = sites.map((s) => s.name).join(', ') || '(none)'
+      if (asJson)
+        log(
+          JSON.stringify(
+            {
+              ok: false,
+              error: `site "${siteFilter}" not found`,
+              sites: sites.map((s) => s.name)
+            },
+            null,
+            2
+          )
+        )
+      else error(`Site "${siteFilter}" not found. Available: ${names}`)
+      return { exitCode: 2 }
+    }
+  } else if (target !== workspaceDir) {
+    const match = sites.find((s) => join(workspaceDir, s.path) === target)
+    if (match) selected = [match]
+  }
+
+  if (selected.length === 0) {
+    if (asJson)
+      log(
+        JSON.stringify({ ok: true, sites: [], note: 'no sites found' }, null, 2)
+      )
+    else warn('No sites found in this workspace.')
+    return { exitCode: 0 }
+  }
+
+  // The data pipeline (collectSiteContent / processQueries) prints progress
+  // via console.log. Route that to stderr while the engine runs so stdout stays
+  // clean — pure JSON for `--json`, just the report otherwise. `log` captured
+  // the original stdout writer at module load, so our own output is unaffected.
+  const results = []
+  const origConsoleLog = console.log
+  console.log = (...a) => process.stderr.write(a.join(' ') + '\n')
+  try {
+    for (const site of selected) {
+      try {
+        results.push(await validateSite(site, foundations, workspaceDir))
+      } catch (err) {
+        results.push({ site: site.name, status: 'error', reason: err.message })
+      }
+    }
+  } finally {
+    console.log = origConsoleLog
+  }
+
+  const totalViolations = results.reduce(
+    (n, r) => n + (r.report?.violations.length || 0),
+    0
+  )
+  const totalSetupErrors = results.reduce(
+    (n, r) => n + (r.report?.setupErrors.length || 0),
+    0
+  )
+  const hadError = results.some((r) => r.status === 'error')
+
+  if (asJson) {
+    const payload = {
+      ok: totalViolations === 0 && !hadError,
+      strict,
+      sites: results.map((r) => ({
+        site: r.site,
+        foundation: r.foundation || null,
+        status: r.status,
+        reason: r.reason || null,
+        ...(r.report || {})
+      })),
+      summary: {
+        sites: results.length,
+        violations: totalViolations,
+        setupErrors: totalSetupErrors,
+        deferred: results.reduce(
+          (n, r) => n + (r.report?.deferred.length || 0),
+          0
+        )
+      }
+    }
+    log(JSON.stringify(payload, null, 2))
+  } else {
+    log('')
+    log(`${colors.blue}${colors.bright}Uniweb Validate${colors.reset}`)
+    log(
+      `${colors.dim}Checking content against the data schemas your foundation declares…${colors.reset}`
+    )
+    for (const r of results) {
+      if (r.status === 'error') {
+        log('')
+        error(
+          `${colors.bright}${r.site}${colors.reset} — could not check: ${r.reason}`
+        )
+      } else {
+        printSiteHuman(r)
+      }
+    }
+
+    log('')
+    log('─'.repeat(50))
+    if (totalViolations === 0 && !hadError) {
+      log('')
+      success(`${colors.bright}All data conforms.${colors.reset}`)
+      if (!strict && totalSetupErrors === 0) {
+        // nothing more to say
+      }
+      log('')
+    } else {
+      log('')
+      if (totalViolations > 0) {
+        const mode = strict
+          ? `${colors.red}error${colors.reset}`
+          : `${colors.yellow}warning${colors.reset}`
+        log(
+          `${totalViolations} violation(s) — reported as ${mode}${strict ? '' : ` ${colors.dim}(--lax: without it, this fails)${colors.reset}`}`
+        )
+      }
+      if (hadError)
+        log(`${colors.red}Some sites could not be checked.${colors.reset}`)
+      log('')
+    }
+  }
+
+  // Exit semantics: 2 = couldn't run; 1 = violations (unless --lax); 0 = clean, or
+  // violations reported under --lax. Setup/read failures are surfaced but don't fail.
+  if (hadError) return { exitCode: 2 }
+  if (totalViolations > 0 && strict) return { exitCode: 1 }
+  return { exitCode: 0 }
+}

package/src/framework-index.json

@@ -0,0 +1,248 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-10-13T14:23:15.630Z",
+  "packages": {
+    "@uniweb/api": {
+      "version": "1.0.1"
+    },
+    "@uniweb/build": {
+      "version": "1.0.1"
+    },
+    "@uniweb/content-reader": {
+      "version": "1.2.8"
+    },
+    "@uniweb/content-writer": {
+      "version": "1.0.1"
+    },
+    "@uniweb/core": {
+      "version": "1.0.1"
+    },
+    "@uniweb/frame-bridge": {
+      "version": "1.0.1"
+    },
+    "@uniweb/icons": {
+      "version": "1.0.1"
+    },
+    "@uniweb/kit": {
+      "version": "1.0.1"
+    },
+    "@uniweb/loom": {
+      "version": "1.0.1"
+    },
+    "@uniweb/press": {
+      "version": "1.0.1"
+    },
+    "@uniweb/projections": {
+      "version": "1.0.1"
+    },
+    "@uniweb/runtime": {
+      "version": "1.0.2"
+    },
+    "@uniweb/scene": {
+      "version": "1.0.1"
+    },
+    "@uniweb/schemas": {
+      "version": "1.0.1"
+    },
+    "@uniweb/scholar": {
+      "version": "1.0.1"
+    },
+    "@uniweb/semantic-parser": {
+      "version": "1.5.1"
+    },
+    "@uniweb/snapshot": {
+      "version": "1.0.1"
+    },
+    "@uniweb/templates": {
+      "version": "1.0.1"
+    },
+    "@uniweb/theming": {
+      "version": "1.0.1"
+    },
+    "@uniweb/unipress": {
+      "version": "1.0.2"
+    }
+  },
+  "templates": {
+    "marketing": {
+      "name": "Marketing",
+      "description": "Landing pages and marketing sites with Tailwind CSS v4",
+      "tags": [
+        "marketing",
+        "landing-page",
+        "tailwind"
+      ]
+    },
+    "academic": {
+      "name": "Academic",
+      "description": "Academic sites for researchers, labs, and departments",
+      "tags": [
+        "academic",
+        "research",
+        "portfolio"
+      ]
+    },
+    "docs": {
+      "name": "Docs",
+      "description": "Documentation sites with navigation levels",
+      "tags": [
+        "docs",
+        "documentation",
+        "technical"
+      ]
+    },
+    "international": {
+      "name": "International",
+      "description": "Multilingual corporate website with English, Spanish, and French",
+      "tags": [
+        "i18n",
+        "multilingual",
+        "corporate",
+        "business",
+        "localization"
+      ]
+    },
+    "blog": {
+      "name": "Blog",
+      "description": "A blog built on the @std/article standard schema. Markdown articles render as a card grid and as full posts on a parametric [slug] page. The first template to use a shared standard data schema — no custom schema file needed.",
+      "tags": [
+        "blog",
+        "articles",
+        "collections",
+        "standard-schema",
+        "data-schema"
+      ]
+    },
+    "dynamic": {
+      "name": "Dynamic",
+      "description": "Live API data fetching with loading states, transforms, and the portable data pattern",
+      "tags": [
+        "data",
+        "api",
+        "fetch",
+        "loading-states",
+        "dynamic"
+      ]
+    },
+    "store": {
+      "name": "Store",
+      "description": "Artisan e-commerce with a product catalog, Shopify Buy Button, journal blog, and stone-amber design",
+      "tags": [
+        "store",
+        "e-commerce",
+        "shopify",
+        "artisan",
+        "products"
+      ]
+    },
+    "learning": {
+      "name": "Learning",
+      "description": "Course-based learning site with quizzes, code challenges, and AI grading integration",
+      "tags": [
+        "learning",
+        "course",
+        "education",
+        "quiz",
+        "lms",
+        "tutorial"
+      ]
+    },
+    "extensions": {
+      "name": "Extensions",
+      "description": "Primary foundation with a visual effects extension, demonstrating multi-foundation sites",
+      "tags": [
+        "extensions",
+        "multi-foundation",
+        "visual-effects",
+        "runtime"
+      ]
+    },
+    "cv-loom": {
+      "name": "CV (Loom + Press)",
+      "description": "An academic CV whose sections are written with Loom {placeholder} expressions, filled in from a single profile at render time by the foundation's content handler, and downloadable as a branded Word document through Press. Ships with Charles Darwin's CV as sample data.",
+      "tags": [
+        "cv",
+        "loom",
+        "template-engine",
+        "content-handler",
+        "dynamic-prose",
+        "academic"
+      ]
+    },
+    "monograph": {
+      "name": "Monograph",
+      "description": "A richly illustrated long-form document — numbered chapters with nested subsections, figures with captions, data-driven specimen and measurement tables, and a citestyle bibliography. The same JSX drives the themed web preview and a branded .docx with headers, footers, and page numbers. Ships with Darwin's Galapagos observations as sample content.",
+      "tags": [
+        "monograph",
+        "docusite",
+        "press",
+        "document",
+        "figures",
+        "tables",
+        "bibliography"
+      ]
+    },
+    "academic-metrics": {
+      "name": "Academic Metrics",
+      "description": "A docusite whose content is also a downloadable Excel workbook. Aggregates academic metrics (publications, funding, supervisions) across multiple members of a university unit. Rich web previews + flat tabular xlsx sheets from the same data. Ships with three 19th-century naturalists as sample members.",
+      "tags": [
+        "academic-metrics",
+        "docusite",
+        "press",
+        "xlsx",
+        "report",
+        "members",
+        "aggregate",
+        "academic"
+      ]
+    },
+    "business-docs": {
+      "name": "Business Documents",
+      "description": "A complete business-document site: invoice and SOW records, pages listing them, and a filtered engagement report with XLSX export. Built on @uniweb/business-docs and demonstrates the same foundation that ships the unipress invoice template.",
+      "tags": [
+        "business-docs",
+        "invoice",
+        "sow",
+        "report",
+        "press",
+        "xlsx",
+        "docx",
+        "pagedjs"
+      ]
+    },
+    "paste": {
+      "name": "Paste a Design (Level 0)",
+      "description": "Bring an existing React design (AI-generated or hand-built) into Uniweb with zero rewiring — replace App.jsx and run. Ships lucide-react preinstalled and SPA-first. The Level 0 conversion starting point.",
+      "tags": [
+        "paste",
+        "level-0",
+        "convert",
+        "ai-generated",
+        "starter"
+      ]
+    },
+    "services": {
+      "name": "Services",
+      "description": "Local-services site built around an author-designed quote request form",
+      "tags": [
+        "services",
+        "local-business",
+        "forms",
+        "quote",
+        "trades"
+      ]
+    },
+    "conference": {
+      "name": "Conference",
+      "description": "A site that is also an app — sign-in, per-viewer data, and an editable programme. Ships a local backend so it runs with nothing installed.",
+      "tags": [
+        "app",
+        "api",
+        "backend",
+        "auth",
+        "permissions",
+        "conference"
+      ]
+    }
+  }
+}