uniweb 0.46.0 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "^0.24.0",
-    "@uniweb/kit": "^0.17.1",
+    "@uniweb/runtime": "^0.19.0",
     "@uniweb/semantic-parser": "^1.4.0",
-    "@uniweb/runtime": "^0.18.0"
+    "@uniweb/core": "^0.24.1",
+    "@uniweb/kit": "^0.18.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.42.0",
+    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/semantic-parser": "^1.4.0"
+    "@uniweb/build": "^0.43.0"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/src/commands/doctor.js

@@ -195,7 +195,7 @@ function sourceMatches(dir, pattern) {
  * question is always "did the developer write this".
  */
 function forEachSourceFile(dir, fn) {
-  const roots = ['sections', 'layouts', 'components']
+  const roots = ['sections', 'layouts', 'components', 'utils']
   const walk = (d, depth = 0) => {
     if (depth > 6) return
     let entries
@@ -211,7 +211,7 @@ function forEachSourceFile(dir, fn) {
         walk(p, depth + 1)
       } else if (/\.(jsx?|tsx?)$/.test(entry.name)) {
         try {
-          fn(readFileSync(p, 'utf8'))
+          fn(readFileSync(p, 'utf8'), relative(dir, p))
         } catch {
           // unreadable file — not this check's problem to report
         }
@@ -221,34 +221,6 @@ function forEachSourceFile(dir, fn) {
   for (const r of roots) walk(join(dir, r))
 }
 
-/**
- * The host services a foundation's own source actually reaches for.
- *
- * ⚠️ A HINT, NEVER THE ANSWER. This is a regex over source, so it sees only the
- * literal spellings below: `resolveService(website, name)` with a variable name
- * is invisible to it, and so is a service reached through a helper. That makes
- * it usable for "you used this and did not declare it" (a false negative just
- * means no warning) and useless as a source of truth (a false negative would
- * mean a capability silently dropped from what we publish).
- *
- * ⛔ Which is why the declaration is authored and this only checks it. Deriving
- * `uniweb.supports` from a scan would make a missed match into a service the
- * operator cannot buy, with nothing anywhere naming the cause.
- */
-function servicesUsedInSource(dir) {
-  const found = new Set()
-  forEachSourceFile(dir, (text) => {
-    for (const m of text.matchAll(/resolveService\s*\(\s*[^,()]+,\s*['"`]([\w-]+)['"`]/g)) {
-      found.add(m[1])
-    }
-    // The service-specific readers, which name no service string of their own.
-    if (/\bisSearchEnabled\s*\(/.test(text)) found.add('search')
-    if (/\buseTracker\s*\(/.test(text)) found.add('tracking')
-    if (/from\s+['"`]@uniweb\/api['"`]/.test(text)) found.add('api')
-  })
-  return found
-}
-
 // A fenced data block tagged `form`, in any of the serialization formats the
 // parser accepts for one. Matched on the info string only — the body is the
 // author's business.
@@ -426,68 +398,201 @@ const CONSENT_NEAR_MISSES = new Set(['require', 'requires', 'required.', 'true',
  * options — there is nothing in it to be wrong.
  */
 /**
- * `uniweb doctor` — a foundation's `uniweb.supports` declaration.
+ * `uniweb doctor` — is `package.json` behind what the build derived?
  *
  * A host offers services (`config.services.<name>`); a foundation has to render
  * something against one, or an operator who provisioned it gets nothing and no
- * error. `package.json::uniweb.supports` is how a foundation states which ones
- * it honours, and it rides to the registry as `info.supports`
- * (`build/src/uwx/registry-package.js`).
+ * error. `uniweb.supports` states which ones a foundation honours, and it rides
+ * to the registry as `info.supports` (`build/src/uwx/registry-package.js`).
+ *
+ * ## ⭐ THE BUILD ALREADY ANSWERED THIS — so read its answer, do not re-derive
  *
- * ## ⭐ WHY THIS WARNS RATHER THAN THE BUILD FILLING IT IN
+ * `@uniweb/build` derives the set from the post-tree-shake module graph and
+ * writes it to `dist/meta/schema.json`'s `_self.supports`
+ * (`build/src/foundation/derive-supports.js`). That value is what publishes,
+ * with or without this check, so the foundation is already correct on the wire.
  *
- * `servicesUsedInSource` is a regex and cannot see a service reached through a
- * variable or a helper. Deriving the declaration from it would publish a list
- * SHORTER than the truth, and a capability missing from that list is one the
- * operator cannot buy — with nothing anywhere naming the cause. A false negative
- * in a warning costs a missing warning; a false negative in a derivation costs a
- * silently unsellable feature. So the developer authors it and this checks it,
- * at the one moment the person who can fix it is looking.
+ * ⛔ **What was here before was a regex over `sections/`, `layouts/` and
+ * `components/`, and it did not work.** It knew four spellings and
+ * `useFormSubmit()` — the official submit gate — was not one, so it was silent
+ * on `templates/services`, the template written to demonstrate the feature. Its
+ * test could not find that, because the fixture was a source string written to
+ * match the regex. ⇒ **Do not reintroduce a second, weaker derivation here.**
+ * There is one, it runs in the build, and this reads it.
  *
- * ## ⚖️ Nothing here defaults a service ON
+ * ## So what is left for `doctor` to say
  *
- * Absent means UNKNOWN, not "none" and not "all". Assuming search because most
- * foundations have one would claim a service for the developer who never met
- * this key — who is the same developer who forgot to declare it — turning a loud
- * failure (reported unknown) into a silent one (an operator paying for something
- * their site will never render).
+ * Only that the FILE disagrees with the artifact. Nothing is broken when it
+ * does — but `uniweb.supports` is the one place a human can add a service the
+ * graph cannot see (a computed name), so a developer who never sees the derived
+ * set never learns the key exists, and never adds the one thing only they know.
  *
- * Silent when a foundation reaches for no service at all: a check that fires on
- * correct configuration is how everyone learns to ignore the checker.
+ * `--fix` writes the derived names in, where they land in a diff the developer
+ * reads. ⛔ The build never does this itself: rewriting source on every build is
+ * a surprise, and the artifact needs no help.
+ *
+ * Silent when the foundation has not been built — nothing has been measured, so
+ * there is nothing to compare and a guess would be worse than quiet.
  */
-export function checkFoundationSupports({ foundationName, folderName, srcDir, pkg, issues }) {
-  const used = servicesUsedInSource(srcDir)
-  if (used.size === 0) return
+export async function checkFoundationSupports({
+  foundationName,
+  folderName,
+  foundationDir,
+  pkg,
+  issues,
+  shouldFix,
+  fixed,
+}) {
+  const schemaPath = join(foundationDir, 'dist', 'meta', 'schema.json')
+  if (!existsSync(schemaPath)) return
+
+  let derived
+  try {
+    derived = JSON.parse(readFileSync(schemaPath, 'utf8'))?._self?.supports
+  } catch {
+    return // unreadable or malformed build output — not this check's to report
+  }
+  // Absent means the build derived nothing and saw a computed name, so it
+  // reported UNKNOWN. There is no gap to name.
+  if (!Array.isArray(derived) || derived.length === 0) return
 
   const declared = pkg?.uniweb?.supports
   const hasDeclaration = Array.isArray(declared)
-  const missing = [...used]
-    .filter((name) => !hasDeclaration || !declared.includes(name))
-    .sort()
+  const missing = derived.filter((name) => !hasDeclaration || !declared.includes(name)).sort()
   if (missing.length === 0) return
 
   const id = 'foundation-supports-incomplete'
   const list = missing.join(', ')
+  const merged = [...new Set([...(hasDeclaration ? declared : []), ...derived])].sort()
+
+  if (shouldFix?.(id)) {
+    const pkgPath = join(foundationDir, 'package.json')
+    try {
+      const src = readFileSync(pkgPath, 'utf8')
+      const parsed = JSON.parse(src)
+      parsed.uniweb = { ...(parsed.uniweb || {}), supports: merged }
+      writeJsonPreservingStyle(pkgPath, parsed, src)
+      fixed?.(`${folderName}/package.json now declares uniweb.supports: ${merged.join(', ')}`)
+      return
+    } catch (e) {
+      // Fall through to the warning — a failed write must not read as fixed.
+      warn(`[${id}] could not write ${folderName}/package.json: ${e.message}`)
+    }
+  }
+
   issues.push({
     id,
     type: 'warning',
     foundation: foundationName,
     message: hasDeclaration
-      ? `${foundationName} uses ${list} but does not declare ${missing.length === 1 ? 'it' : 'them'} in uniweb.supports`
-      : `${foundationName} uses ${list} but declares no uniweb.supports`,
-    details: { used: [...used].sort(), declared: hasDeclaration ? declared : null }
+      ? `${foundationName} builds against ${list} but does not declare ${missing.length === 1 ? 'it' : 'them'} in uniweb.supports`
+      : `${foundationName} builds against ${list} but declares no uniweb.supports`,
+    details: { derived, declared: hasDeclaration ? declared : null },
+    fixable: true,
   })
 
-  if (hasDeclaration) {
-    warn(`[${id}] ${foundationName} uses ${list}, not listed in uniweb.supports`)
-  } else {
-    warn(`[${id}] ${foundationName} uses ${list} and declares no uniweb.supports`)
-    log(`    Without it a host cannot tell "this foundation supports nothing" from`)
-    log(`    "nobody said" — so what it renders may never be offered to the operator.`)
+  warn(`[${id}] ${foundationName} builds against ${list}, not in ${folderName}/package.json`)
+  log(`    The build already publishes ${colors.dim}${derived.join(', ')}${colors.reset}, so nothing is missing on the wire.`)
+  log(`    Declaring it matters when a service is named by a computed value — the`)
+  log(`    build cannot see those, and yours is the only place they can be added.`)
+  log(`    ${colors.dim}uniweb doctor --fix ${id}${colors.reset}`)
+}
+
+/**
+ * The gates kit exposes for a host service, and the field that IS the gate.
+ *
+ * Each hook returns a boolean saying whether the site actually has the service.
+ * A component that ignores it draws a control the visitor cannot use — a search
+ * box that searches nothing, a form whose answers have nowhere to go.
+ */
+const SERVICE_GATES = [
+  { hook: 'useFormSubmit', gate: 'canSubmit', draws: 'a form' },
+  { hook: 'useSearch', gate: 'isEnabled', draws: 'a search control' },
+  { hook: 'useSearchIndex', gate: 'isEnabled', draws: 'a search control' },
+  // Returns everything `useSearch` does, `isEnabled` included, so it gates the
+  // same way. It was missing from this list until the hook was renamed out of
+  // `useSearchWithIntent` — the kind of gap a list of names grows quietly.
+  { hook: 'useSearchPrefetch', gate: 'isEnabled', draws: 'a search control' },
+]
+
+/**
+ * `uniweb doctor` — a control drawn for a service the site may not have.
+ *
+ * `resolveService` answers with an address or nothing, and nothing is a normal
+ * state: the operator did not provision that service. ⭐ **The rule is that a
+ * control for a service the site does not have must not be drawn** — no error,
+ * no apology, no explanatory string (there is deliberately none to show, since
+ * any wording would be ours to invent, in one language, for a visitor with no
+ * stake in it). The hooks hand you a boolean for exactly this, and a component
+ * that never reads it renders something permanently dead.
+ *
+ * ## ⚖️ WHY A REGEX IS ACCEPTABLE HERE, HAVING JUST BEEN REJECTED NEXT DOOR
+ *
+ * `checkFoundationSupports` above no longer scans source, because deriving
+ * *which services a foundation reaches* requires following calls through
+ * `@uniweb/kit` into `@uniweb/core`, and a missed match there silently costs a
+ * capability on the wire. This question is a different shape:
+ *
+ *   - it is **local to one file** — the hook call and its gate are in the same
+ *     component, in the developer's own source, with no indirection to follow;
+ *   - the gate names are **fixed by kit's API**, not inferred;
+ *   - it only ever **warns**, and changes no artifact. A miss costs a missing
+ *     warning, which is the safe direction.
+ *
+ * ⛔ Its limits, stated rather than discovered: a component that gates in its
+ * parent reads as ungated here, and one that destructures the gate without
+ * using it reads as gated. Both are warnings about a real smell either way, and
+ * neither can produce a wrong artifact.
+ */
+/**
+ * Source with its comments removed.
+ *
+ * ⚠️ MEASURED, NOT PRECAUTIONARY. The first cut of this check searched the raw
+ * text, and passed on `templates/services` with the gate deliberately deleted
+ * from the code — because the component's JSDoc still said `canSubmit`. Prose
+ * about a gate is not a gate.
+ *
+ * ⛔ Whole-line and block comments only, deliberately. A line that begins with
+ * `//` or `*` is unambiguously a comment, so stripping it can never remove real
+ * code; hunting trailing comments would mean deciding whether a `//` sits
+ * inside a string, and getting that wrong deletes code and invents a warning.
+ * The residue is that a gate named ONLY in a trailing comment still reads as
+ * used, which is a missed warning — the safe direction.
+ */
+function stripComments(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^[ \t]*\/\/.*$/gm, '')
+}
+
+export function checkUngatedServiceControls({ foundationName, folderName, srcDir, issues }) {
+  const found = []
+
+  forEachSourceFile(srcDir, (raw, file) => {
+    const text = stripComments(raw)
+    for (const { hook, gate, draws } of SERVICE_GATES) {
+      // A call, not merely an import: re-exporting a hook is not drawing with it.
+      if (!new RegExp(`\\b${hook}\\s*\\(`).test(text)) continue
+      if (new RegExp(`\\b${gate}\\b`).test(text)) continue
+      found.push({ file, hook, gate, draws })
+    }
+  })
+
+  if (found.length === 0) return
+
+  const id = 'ungated-service-control'
+  for (const f of found) {
+    issues.push({
+      id,
+      type: 'warning',
+      foundation: foundationName,
+      message: `${foundationName}/${f.file} calls ${f.hook}() without reading ${f.gate}`,
+      details: f,
+    })
+    warn(`[${id}] ${folderName}/${f.file} calls ${f.hook}() and never reads ${f.gate}`)
+    log(`    It draws ${f.draws} even on a site with no such service, where the`)
+    log(`    control cannot work. Gate on it instead:`)
+    log(`      ${colors.dim}const { ${f.gate} } = ${f.hook}(…)${colors.reset}`)
+    log(`      ${colors.dim}if (!${f.gate}) return null${colors.reset}`)
   }
-  const merged = [...new Set([...(hasDeclaration ? declared : []), ...missing])].sort()
-  log(`    Add to ${folderName}/package.json:`)
-  log(`      ${colors.dim}"uniweb": { "supports": ${JSON.stringify(merged)} }${colors.reset}`)
 }
 
 export function checkTrackingBlock({ siteName, siteYml, issues }) {
@@ -941,11 +1046,41 @@ export async function doctor(args = []) {
 
   // ── uniweb.supports — the services this foundation says it is built against ──
   for (const f of foundations) {
-    checkFoundationSupports({
+    await checkFoundationSupports({
       foundationName: f.name,
       folderName: f.folderName,
-      srcDir: resolveFoundationSrcPath(f.path),
+      foundationDir: f.path,
       pkg: loadPackageJson(f.path),
+      issues,
+      shouldFix,
+      fixed
+    })
+    checkUngatedServiceControls({
+      foundationName: f.name,
+      folderName: f.folderName,
+      srcDir: resolveFoundationSrcPath(f.path),
+      issues
+    })
+  }
+
+  // Extensions carry `uniweb.supports` too — same key, same field, and a site's
+  // answer is the union across its primary foundation and its extensions. The
+  // regex-era check looked at foundations only, so an extension that drew a
+  // search box was never asked about one.
+  for (const e of extensions) {
+    await checkFoundationSupports({
+      foundationName: e.name,
+      folderName: e.folderName,
+      foundationDir: e.path,
+      pkg: loadPackageJson(e.path),
+      issues,
+      shouldFix,
+      fixed
+    })
+    checkUngatedServiceControls({
+      foundationName: e.name,
+      folderName: e.folderName,
+      srcDir: resolveFoundationSrcPath(e.path),
       issues
     })
   }

package/src/framework-index.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-06T21:10:44.136Z",
+  "generatedAt": "2026-09-07T05:09:47.913Z",
   "packages": {
     "@uniweb/api": {
-      "version": "0.2.10",
+      "version": "0.2.11",
       "path": "framework/api",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/build": {
-      "version": "0.42.0",
+      "version": "0.43.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -34,7 +34,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.24.0",
+      "version": "0.24.1",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -54,7 +54,7 @@
       ]
     },
     "@uniweb/kit": {
-      "version": "0.17.1",
+      "version": "0.18.0",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -82,7 +82,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.18.0",
+      "version": "0.19.0",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -110,7 +110,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.12.0",
+      "version": "0.12.1",
       "path": "framework/templates",
       "deps": []
     },
@@ -120,7 +120,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.9.8",
+      "version": "0.9.10",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",