uniweb 1.0.0 → 1.0.2

package/src/utils/config.js

@@ -0,0 +1,417 @@
+/**
+ * Workspace Config Management
+ *
+ * Read/write pnpm-workspace.yaml and root package.json, plus URL config
+ * for the platform backend / registry. Used by both `create` and `add`
+ * commands.
+ *
+ * This module is on the CLI's startup path (statically imported by
+ * `commands/login.js`, which is loaded by `src/index.js`). It MUST NOT
+ * import any optional peer dependency — most importantly `@uniweb/build`,
+ * which is absent in `npx uniweb create` scratch dirs and global
+ * installs. Workspace package discovery (which does need `@uniweb/build`)
+ * lives in `./discover.js` and is loaded only by commands that already
+ * require a project context.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import yaml from 'js-yaml'
+import { filterCmd } from './pm.js'
+import { writeJsonPreservingStyleAsync } from './json-file.js'
+import { loggedInOriginOf, readSessionFileSync } from './session-file.js'
+
+// ── Backend origin ─────────────────────────────────────────────
+
+/**
+ * Read ~/.uniweb/config.json for a persistent backend-origin override (e.g.
+ * `{ "registryApiUrl": "http://localhost:8081" }`) — consumed by
+ * getRegistryApiBaseUrl() below.
+ *
+ * @returns {{ registryApiUrl?: string }}
+ */
+let _cliConfig = undefined
+function readCliConfig() {
+  if (_cliConfig !== undefined) return _cliConfig
+
+  try {
+    const configPath = join(homedir(), '.uniweb', 'config.json')
+    if (existsSync(configPath)) {
+      _cliConfig = JSON.parse(readFileSync(configPath, 'utf8'))
+      return _cliConfig
+    }
+  } catch {
+    // ignore
+  }
+
+  _cliConfig = {}
+  return _cliConfig
+}
+
+/**
+ * The origin the LAST `uniweb login` authenticated against — persisted on the
+ * session record so subsequent verbs default to the backend you logged into
+ * (no backend flag per command). Sync read; null when there's no session or it
+ * carries no origin (older sessions). Read directly (not via registry-auth.js)
+ * to keep this module off the optional-peer / import-cycle path.
+ * @returns {string|null}
+ */
+/**
+ * **The backend the user is logged in to** — the one session's backend — or null.
+ *
+ * ⛔ This read `~/.uniweb/registry-auth.json`'s top-level `origin` itself until
+ * 2026-09-21: the v1 shape. The file had become one session per backend, which has no
+ * such field, so this answered null for every new login and the session tier below
+ * silently fell through to the default backend. It reads through the file's one reader
+ * now (utils/session-file.js).
+ *
+ * @returns {string|null}
+ */
+export function loggedInOrigin() {
+  return loggedInOriginOf(readSessionFileSync(DEFAULT_BACKEND_ORIGIN))
+}
+
+/** A value's bare origin, or null when it is not a URL. */
+function originOrNull(value) {
+  if (!value) return null
+  try {
+    // ⛔ http(s) only: `new URL('localhost:8080')` PARSES — as the scheme `localhost:` —
+    // and its origin is the string "null", which is truthy. A bare host:port is the
+    // easy slip, and it must not become a backend.
+    const u = new URL(value)
+    return u.protocol === 'http:' || u.protocol === 'https:' ? u.origin : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * **The default backend** — where a bare `uniweb login` goes, and where a backend command
+ * goes when nobody is logged in (the login it asks for is then this one).
+ *
+ * `UNIWEB_SERVER`, else `~/.uniweb/config.json` `registryApiUrl`, else
+ * https://uniweb.app. ⛔ **Never the current session** *[Diego, 2026-09-21: "the default
+ * backend for login, if not specified, is uniweb.app"]* — a bare `uniweb login` means the
+ * default backend, not "the one I am already on".
+ *
+ * @returns {string}
+ */
+export function getDefaultBackendOrigin() {
+  return (
+    originOrNull(process.env.UNIWEB_SERVER) ||
+    originOrNull(readCliConfig().registryApiUrl) ||
+    DEFAULT_BACKEND_ORIGIN
+  )
+}
+
+/**
+ * The `uniweb login` that SWITCHES the workspace on `origin` — the caller appends `--org @x`
+ * or `--personal` — with `--server` unless a switch without it reaches `origin`
+ * (`resolveLoginOrigin`): the backend you are logged in to, or, logged in nowhere, the
+ * default backend.
+ *
+ * ⚠️ *Measured 2026-10-06 against a local backend, before switches acted on the session:*
+ * `uniweb login --org @acme` went to https://uniweb.app and began a new login there — the
+ * reason a hint about any other backend names it.
+ *
+ * @param {string} origin - the backend the hint is about
+ * @param {string} [prefix='uniweb'] - how the user runs the CLI (`getCliPrefix`)
+ * @returns {string} e.g. `uniweb login`, or `uniweb login --server http://localhost:8080`
+ */
+export function loginCommand(origin, prefix = 'uniweb') {
+  const o = originOrNull(origin)
+  const reached = originOrNull(loggedInOrigin()) || getDefaultBackendOrigin()
+  return o && o !== reached ? `${prefix} login --server ${o}` : `${prefix} login`
+}
+
+/** The flags with which `uniweb login` SIGNS IN — a method, or a credential. */
+const SIGN_IN_FLAGS = ['--token', '--browser', '--password', '--token-paste']
+
+/**
+ * Whether a `uniweb login` is a WORKSPACE SWITCH: `--org` or `--personal`, and nothing that
+ * signs in (`SIGN_IN_FLAGS`).
+ *
+ * @param {string[]} [args]
+ * @returns {boolean}
+ */
+export function isWorkspaceSwitch(args = []) {
+  const names = args.map((a) => String(a).split('=')[0])
+  return (
+    (names.includes('--org') || names.includes('--personal')) &&
+    !SIGN_IN_FLAGS.some((f) => names.includes(f))
+  )
+}
+
+/**
+ * The backend `uniweb login` logs in to: `--server`; else, for a workspace switch, the
+ * backend you are logged in to; else the default backend.
+ *
+ * ⭐ A SWITCH ACTS ON YOUR SESSION *[Diego, 2026-10-06: "`uniweb login --org @x` or
+ * `--personal`, with no `--backend`, should switch to the workspace on the backend you're
+ * already logged in to so we can fullfil the promise 'switches without logging in again'"]*.
+ * Logged in nowhere, it is a first login, and goes where any first login goes. A login that
+ * signs in — a method or a credential named (`isWorkspaceSwitch`) — still goes to the
+ * default backend *[Diego, 2026-09-21: "the default backend for login, if not specified, is
+ * uniweb.app"]*. ⛔ Until 2026-10-06 a switch went to the default backend too, so on any
+ * other backend it began a new login there, logging you out of the one you were on.
+ *
+ * ⛔ A mistyped `--server` is an error, never a fallback — it would log you in, and so
+ * point every command, somewhere you did not name.
+ *
+ * @param {string|null|undefined} flag - `readFlagValue`'s answer: undefined when the
+ *   flag is absent, null when it was given with no value
+ * @param {string[]} [args] - the login's argv, to tell a switch from a sign-in
+ * @returns {string}
+ * @throws {Error} when --server was given and is not a URL
+ */
+export function resolveLoginOrigin(flag, args = []) {
+  if (flag === undefined) {
+    const session = isWorkspaceSwitch(args) ? originOrNull(loggedInOrigin()) : null
+    return session || getDefaultBackendOrigin()
+  }
+  const origin = originOrNull(flag)
+  if (!origin) throw new Error(flag ? `Not a URL: ${flag}` : '--server needs a URL')
+  return origin
+}
+
+/**
+ * **The backend a command talks to** — the base of every `/dev/*` route (`register`
+ * POSTs to {origin}/dev/registry/register, and so on).
+ *
+ * `UNIWEB_SERVER` > **the backend the user is logged in to** > the default
+ * (`getDefaultBackendOrigin`). ⭐ Nothing talks to a backend the user is not logged in
+ * to *[Diego, 2026-09-21]*: when this falls through to the default, the command's first
+ * request asks for that login — so the default is where the login goes, never a
+ * backend reached without one. `resolveBackendOrigin` (backend/client.js) returns this
+ * unchanged: no command takes a backend flag. ⛔ *Until 2026-10-05 this said "when no
+ * `--backend` is given" and that `resolveBackendOrigin` put `--backend` on top — read as
+ * a per-command flag outranking the login. The verbs lost that flag on 2026-09-21.*
+ *
+ * @returns {string}
+ */
+export function getRegistryApiBaseUrl() {
+  return (
+    originOrNull(process.env.UNIWEB_SERVER) ||
+    originOrNull(loggedInOrigin()) ||
+    getDefaultBackendOrigin()
+  )
+}
+
+/**
+ * The built-in backend origin — the last tier of the ladder, and the 98% case.
+ *
+ * Exported because several readers need the *built-in* default, not the resolved one:
+ * a v1 session file with no origin stamp, `login`'s list of known backends, and a
+ * deploy.yml `host: uniweb` target with no `backend:` (its documented meaning).
+ * `getRegistryApiBaseUrl()` cannot give it — that function returns whatever tier won,
+ * so on a machine with a session or a saved config it returns something else
+ * entirely. Two copies of the literal would silently disagree exactly there.
+ */
+export const DEFAULT_BACKEND_ORIGIN = 'https://uniweb.app'
+
+/**
+ * Read workspace package globs.
+ * Tries pnpm-workspace.yaml first, falls back to package.json workspaces.
+ * @param {string} rootDir - Workspace root directory
+ * @returns {Promise<{packages: string[]}>}
+ */
+export async function readWorkspaceConfig(rootDir) {
+  // Try pnpm-workspace.yaml first
+  const configPath = join(rootDir, 'pnpm-workspace.yaml')
+  if (existsSync(configPath)) {
+    const content = await readFile(configPath, 'utf-8')
+    const config = yaml.load(content)
+    return { packages: config?.packages || [] }
+  }
+
+  // Fall back to package.json workspaces
+  const pkg = await readRootPackageJson(rootDir)
+  if (Array.isArray(pkg.workspaces)) {
+    return { packages: pkg.workspaces }
+  }
+
+  return { packages: [] }
+}
+
+/**
+ * Write pnpm-workspace.yaml
+ * @param {string} rootDir - Workspace root directory
+ * @param {{packages: string[]}} config
+ */
+export async function writeWorkspaceConfig(rootDir, config) {
+  const configPath = join(rootDir, 'pnpm-workspace.yaml')
+  const content = yaml.dump(config, { flowLevel: -1, quotingType: '"' })
+  await writeFile(configPath, content)
+}
+
+/**
+ * Add a glob pattern to pnpm-workspace.yaml if not already present
+ * @param {string} rootDir - Workspace root directory
+ * @param {string} glob - Glob pattern to add
+ */
+export async function addWorkspaceGlob(rootDir, glob) {
+  const config = await readWorkspaceConfig(rootDir)
+  if (!config.packages.includes(glob)) {
+    config.packages.push(glob)
+    await writeWorkspaceConfig(rootDir, config)
+  }
+
+  // Sync workspaces array in package.json (for npm compatibility)
+  const pkg = await readRootPackageJson(rootDir)
+  if (!pkg.workspaces) {
+    pkg.workspaces = []
+  }
+  if (!pkg.workspaces.includes(glob)) {
+    pkg.workspaces.push(glob)
+    await writeRootPackageJson(rootDir, pkg)
+  }
+}
+
+/**
+ * Read root package.json
+ * @param {string} rootDir - Workspace root directory
+ * @returns {Promise<Object>}
+ */
+export async function readRootPackageJson(rootDir) {
+  const pkgPath = join(rootDir, 'package.json')
+  if (!existsSync(pkgPath)) {
+    return {}
+  }
+  return JSON.parse(await readFile(pkgPath, 'utf-8'))
+}
+
+/**
+ * Write root package.json, preserving the file's existing indentation
+ * (newly scaffolded workspaces use 2-space; we don't reflow whatever's
+ * already there).
+ * @param {string} rootDir - Workspace root directory
+ * @param {Object} pkg - Package.json object
+ */
+export async function writeRootPackageJson(rootDir, pkg) {
+  const pkgPath = join(rootDir, 'package.json')
+  if (existsSync(pkgPath)) {
+    await writeJsonPreservingStyleAsync(pkgPath, pkg)
+  } else {
+    await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  }
+}
+
+/**
+ * Compute root scripts based on discovered sites.
+ *
+ * `dev` and `build` route through the uniweb CLI verb (PM-agnostic — they
+ * resolve `uniweb` from the project's local node_modules/.bin, so `pnpm
+ * dev` and `npm run dev` both work without locking the scripts to one PM
+ * at create-time). `preview` stays on a PM-specific filter because there
+ * isn't a `uniweb preview` verb yet (the site's own `vite preview` is what
+ * runs); switch it over when one ships.
+ *
+ * @param {Array<{name: string, path: string}>} sites - Discovered sites
+ * @param {'pnpm' | 'npm'} [pm='pnpm'] - Package manager (used only for preview)
+ * @returns {Object} Scripts object for package.json
+ */
+export function computeRootScripts(sites, pm = 'pnpm') {
+  const scripts = {
+    build: 'uniweb build'
+  }
+
+  if (sites.length === 0) {
+    return scripts
+  }
+
+  if (sites.length === 1) {
+    scripts.dev = 'uniweb dev'
+    scripts.preview = filterCmd(pm, sites[0].name, 'preview')
+  } else {
+    // First site gets unqualified dev/preview (matches `uniweb dev`'s
+    // default-to-first-site behavior).
+    scripts.dev = 'uniweb dev'
+    scripts.preview = filterCmd(pm, sites[0].name, 'preview')
+
+    // Subsequent sites get qualified dev:{name}/preview:{name}
+    for (let i = 1; i < sites.length; i++) {
+      scripts[`dev:${sites[i].name}`] = `uniweb dev ${sites[i].name}`
+      scripts[`preview:${sites[i].name}`] = filterCmd(
+        pm,
+        sites[i].name,
+        'preview'
+      )
+    }
+  }
+
+  return scripts
+}
+
+/**
+ * Update root scripts after adding a new site
+ * @param {string} rootDir - Workspace root directory
+ * @param {Array<{name: string, path: string}>} sites - All sites (including new one)
+ * @param {'pnpm' | 'npm'} [pm='pnpm'] - Package manager
+ */
+export async function updateRootScripts(rootDir, sites, pm = 'pnpm') {
+  const pkg = await readRootPackageJson(rootDir)
+  const newScripts = computeRootScripts(sites, pm)
+
+  // If we're adding a second site, rename existing dev/preview to dev:{firstName}
+  if (sites.length === 2 && pkg.scripts?.dev) {
+    const firstName = sites[0].name
+    // Only rename if the existing dev script references the first site's name
+    if (pkg.scripts.dev.includes(firstName)) {
+      pkg.scripts[`dev:${firstName}`] = pkg.scripts.dev
+      pkg.scripts[`preview:${firstName}`] = pkg.scripts.preview
+    }
+  }
+
+  pkg.scripts = { ...pkg.scripts, ...newScripts }
+  await writeRootPackageJson(rootDir, pkg)
+}
+
+// Resolve a workspace glob pattern to actual directories
+export async function resolveGlob(rootDir, pattern) {
+  const clean = pattern.replace(/^["']|["']$/g, '')
+
+  if (clean.endsWith('/*')) {
+    // Pattern like "foundations/*" - list subdirectories
+    const baseDir = clean.slice(0, -2)
+    const fullPath = join(rootDir, baseDir)
+    if (!existsSync(fullPath)) return []
+    try {
+      const { readdirSync } = await import('node:fs')
+      const entries = readdirSync(fullPath, { withFileTypes: true })
+      return entries
+        .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+        .map((e) => join(baseDir, e.name))
+    } catch {
+      return []
+    }
+  }
+
+  if (clean.startsWith('*/')) {
+    // Pattern like "*/foundation" - find subdirs with this child
+    const suffix = clean.slice(2)
+    const { readdirSync } = await import('node:fs')
+    try {
+      const entries = readdirSync(rootDir, { withFileTypes: true })
+      return entries
+        .filter(
+          (e) =>
+            e.isDirectory() &&
+            !e.name.startsWith('.') &&
+            e.name !== 'node_modules'
+        )
+        .filter((e) => existsSync(join(rootDir, e.name, suffix)))
+        .map((e) => join(e.name, suffix))
+    } catch {
+      return []
+    }
+  }
+
+  // Direct path like "foundation" or "site"
+  if (existsSync(join(rootDir, clean))) {
+    return [clean]
+  }
+
+  return []
+}

package/src/utils/conformance.js

@@ -0,0 +1,274 @@
+/**
+ * Content conformance on the paths that SHIP content.
+ *
+ * `uniweb validate` answers "does my data match the schemas my foundation
+ * declares?" — and until this existed, it was the *only* caller. `build`,
+ * `publish`, `push` and `deploy` never ran it, so a malformed data block built
+ * clean, deployed clean, and synced to a backend with nothing having checked
+ * it. The first symptom was a section rendering nothing on a live site, with no
+ * error anywhere in the chain.
+ *
+ * ## On a STATIC host it warns and never blocks — and on a backend it is a gate.
+ *
+ * ⭐ Two answers, one per destination [Diego, 2026-09-24: "The old rationale was in
+ * the context of static sites. It was never meant for pushed sites since that didn't
+ * even exist at the time."]. `push` and `publish` register the foundation first, so
+ * the backend checks the records against the very schemas checked here: a finding
+ * there is a refusal on arrival, or a value lost on the way — never a disagreement to
+ * ship through. `refuseIfContentDoesNotConform` is that gate; `deploy` to a static
+ * host keeps the warning below, whose reasoning is unchanged for it:
+ *
+ * A schema can be newer than the content that was valid when it was authored —
+ * a foundation upgrade, a `@std/*` revision — so a finding does not mean the
+ * content is wrong, it means the two disagree. A framework that refused to
+ * publish over that would make an author's site hostage to a schema release,
+ * for a defect whose real-world cost is one section rendering wrong. `uniweb
+ * validate` is where the gate lives for a static site, and CI is where it belongs.
+ *
+ * So, on a static host: silent when everything conforms, silent when it cannot
+ * check, one compact block when it finds something, and **the ship proceeds
+ * either way**.
+ *
+ * ## Why it is quiet about being unable to check
+ *
+ * A site whose foundation is a registry ref or a URL has no schemas on disk, so
+ * there is nothing to check against — the common case for exactly the sites
+ * `publish` is used on. `uniweb validate` reports that as "skipped" because the
+ * user asked it a direct question and deserves an answer. Here the user asked
+ * to ship, and a line saying what was not done on every deploy is noise that
+ * teaches people to skim past this block — including the times it fires.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, join, relative } from 'node:path'
+import yaml from 'js-yaml'
+import { validateDataInputs } from '@uniweb/build'
+import { discoverFoundations } from './discover.js'
+import { findWorkspaceRoot } from './workspace.js'
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m'
+}
+
+/** How many findings to print before summarizing the rest. */
+const MAX_SHOWN = 3
+
+function readSiteYml(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
+}
+
+/**
+ * Check one site's file-based data against its local foundation's schemas.
+ *
+ * Resolves the foundation the same way `uniweb validate` does, so the two
+ * commands agree about what is checkable — they must, or a deploy would warn
+ * about something `validate` then reports as clean.
+ *
+ * @param {string} siteDir — the site's directory
+ * @returns {Promise<{status: 'checked'|'skipped', reason?: string, report?: object, foundation?: string}>}
+ */
+export async function checkSiteConformance(siteDir) {
+  const workspaceDir = findWorkspaceRoot(siteDir)
+  if (!workspaceDir) return { status: 'skipped', reason: 'not in a workspace' }
+
+  const siteYml = readSiteYml(siteDir)
+  const declared = siteYml?.foundation
+  if (!declared) {
+    return { status: 'skipped', reason: 'no foundation declared in site.yml' }
+  }
+
+  // Resolution is the name/basename match `uniweb validate` uses, and nothing
+  // more. A registry ref (`@ns/name@ver`), a URL or the object form matches no
+  // local foundation and falls through to "skipped" on its own — pre-filtering
+  // those shapes here would be a second, subtly different rule, and the two
+  // commands disagreeing about what is checkable is precisely the bug that
+  // would make a deploy warn about content `validate` then calls clean.
+  const foundations = await discoverFoundations(workspaceDir)
+  const match = foundations.find(
+    (f) => f.name === declared || basename(f.path) === declared
+  )
+  if (!match) {
+    return { status: 'skipped', reason: `foundation "${declared}" is not on disk` }
+  }
+
+  const report = await validateDataInputs({
+    siteRoot: siteDir,
+    foundationPath: join(workspaceDir, match.path)
+  })
+  return { status: 'checked', foundation: match.name, report }
+}
+
+/**
+ * Run the check and print a compact warning if anything does not conform.
+ *
+ * Swallows its own failures deliberately. This runs inside `publish` / `push` /
+ * `deploy`, and an advisory check that can abort a ship is worse than no check:
+ * the thing the user asked for is the ship, and a crash in a warning is a
+ * regression with no upside. A checker that cannot run says nothing.
+ *
+ * @param {string} siteDir
+ * @param {object} [options]
+ * @param {string[]} [options.args] — the command's argv, to honour `--no-validate`
+ * @param {(m: string) => void} [options.warn] — the caller's warning printer
+ * @param {(m: string) => void} [options.dim] — the caller's dim printer
+ * @returns {Promise<number>} how many violations were reported (0 when clean,
+ *   skipped, suppressed, or the check itself failed)
+ */
+export async function warnIfContentDoesNotConform(siteDir, options = {}) {
+  const {
+    args = [],
+    warn = (m) => console.log(`${c.yellow}⚠${c.reset} ${m}`),
+    dim = (m) => console.log(`  ${c.dim}${m}${c.reset}`)
+  } = options
+
+  if (args.includes('--no-validate')) return 0
+
+  let result
+  try {
+    result = await checkSiteConformance(siteDir)
+  } catch {
+    return 0 // see the docstring: a warning must not be able to stop a ship
+  }
+
+  if (result.status !== 'checked') return 0
+
+  const formatted = formatConformanceWarning(result, siteDir)
+  if (!formatted) return 0
+
+  warn(formatted.headline)
+  for (const line of formatted.details) dim(line)
+  return formatted.total
+}
+
+/**
+ * The same check as a GATE, for `push` and `publish` — see the header for why a
+ * backend gets a gate where a static host gets a warning.
+ *
+ * Only VIOLATIONS stop it: a record the backend would refuse, or whose value it would
+ * lose. A setup error is about how data reaches a section — a rendering question, not
+ * a record — so it is still printed as a warning and the ship goes on. A checker that
+ * cannot run says nothing and stops nothing, as above. `--no-validate` skips the check
+ * and leaves the records to the backend.
+ *
+ * @param {string} siteDir
+ * @param {object} [options] - `args`, and the caller's `error` / `warn` / `dim` printers
+ * @returns {Promise<number>} the violations that stop the ship (0 to go on)
+ */
+export async function refuseIfContentDoesNotConform(siteDir, options = {}) {
+  const {
+    args = [],
+    error = (m) => console.log(`${c.red}✗${c.reset} ${m}`),
+    warn = (m) => console.log(`${c.yellow}⚠${c.reset} ${m}`),
+    dim = (m) => console.log(`  ${c.dim}${m}${c.reset}`)
+  } = options
+
+  if (args.includes('--no-validate')) return 0
+
+  let result
+  try {
+    result = await checkSiteConformance(siteDir)
+  } catch {
+    return 0
+  }
+  if (result.status !== 'checked') return 0
+
+  const violations = result.report?.violations?.length || 0
+  const formatted = formatConformanceWarning(result, siteDir, { stops: violations > 0 })
+  if (!formatted) return 0
+
+  ;(violations > 0 ? error : warn)(formatted.headline)
+  for (const line of formatted.details) dim(line)
+  return violations
+}
+
+/**
+ * Turn a report into the lines to print, or `null` when there is nothing to say.
+ *
+ * Split out from the reporting so the *warning* itself is testable without
+ * scaffolding a whole workspace on disk. That is not tidiness: every test of
+ * the silent paths would pass equally well against a function that could never
+ * warn at all, so without this the suite would assert its own inertness.
+ *
+ * @param {{report?: object, foundation?: string}} result
+ * @param {string} siteDir
+ * @param {{ stops?: boolean }} [options] - `stops`: the ship stops on this report
+ *   (`refuseIfContentDoesNotConform`), so the last line says nothing was sent
+ * @returns {{headline: string, details: string[], total: number}|null}
+ */
+export function formatConformanceWarning(result, siteDir = '', { stops = false } = {}) {
+  const violations = result?.report?.violations || []
+  const setupErrors = result?.report?.setupErrors || []
+  const total = violations.length + setupErrors.length
+  if (total === 0) return null
+
+  // ⛔ **Two different kinds of finding share this block, and one sentence cannot
+  // describe both.** A `violation` is a record whose VALUE disagrees with a
+  // schema. A `setupError` is data that could not be read, or that never reached
+  // the section meant to read it — *no record is involved*. Counting the second
+  // as "content records that do not match" sends the reader hunting through their
+  // data for a fault that is in their configuration, which is the worse of the
+  // two searches and the one that ends in "the framework is wrong".
+  //
+  // The total still leads the block; only the naming is split.
+  const parts = []
+  if (violations.length > 0) {
+    parts.push(
+      `${violations.length} content record${violations.length === 1 ? '' : 's'} ` +
+        `that ${violations.length === 1 ? 'does' : 'do'} not match the schemas ` +
+        `${c.bold}${result.foundation}${c.reset} declares`
+    )
+  }
+  if (setupErrors.length > 0) {
+    parts.push(
+      `${setupErrors.length} problem${setupErrors.length === 1 ? '' : 's'} ` +
+        `with how data reaches your sections`
+    )
+  }
+  const headline = `Found ${parts.join(' and ')}.`
+
+  const lines = [
+    // A finding on the record itself carries no `field` — "expected a list of
+    // records, got object" is about the whole value — so naming one would print
+    // an empty path segment.
+    ...violations.map((v) => {
+      const where = v.field ? `item "${v.item}" › ${v.field}` : `item "${v.item}"`
+      return `${rel(siteDir, v.file)} — ${where}: ${v.message}`
+    }),
+    ...setupErrors.map((e) => `${rel(siteDir, e.file)} — ${e.message}`)
+  ]
+
+  const details = lines.slice(0, MAX_SHOWN).map((l) => `• ${l}`)
+  if (lines.length > MAX_SHOWN) details.push(`…and ${lines.length - MAX_SHOWN} more`)
+
+  // Name the command that explains it, and say plainly which this is — a warning
+  // during a ship reads as a failure unless it says so, and a refusal must say what
+  // did not happen.
+  details.push(
+    stops
+      ? 'Nothing was sent. Run `uniweb validate` for the full report, or pass `--no-validate` to send it anyway and let the backend decide.'
+      : 'Shipping anyway. Run `uniweb validate` for the full report.'
+  )
+
+  return { headline, details, total }
+}
+
+/** Site-relative when it helps, the original when it does not. */
+function rel(siteDir, file) {
+  if (!file) return '(unknown file)'
+  const r = relative(siteDir, file)
+  return !r || r.startsWith('..') ? file : r
+}