@mohou/host 1.0.20

package/src/compile/review.ts

@@ -0,0 +1,342 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import type * as ts from 'typescript'
+
+import { appEntries, appTrees, type DefinitionCode } from '@mohou/contract'
+
+import { snapshotSkip } from '../files/skip.ts'
+import type { CompileCode } from './codes.ts'
+import { importDecision, sideOf } from './imports.ts'
+
+/** A finding that does not fail reload. Callers match `code`. */
+export const reviewNoticeCodes = [
+  'keyframe-duplicate',
+  'keyframe-collision',
+  'identifier-skipped',
+] as const
+
+export type ReviewNoticeCode = (typeof reviewNoticeCodes)[number]
+
+export interface ReviewNotice {
+  readonly code: ReviewNoticeCode
+  readonly message: string
+  readonly path?: string
+  readonly name?: string
+}
+
+export interface ReviewError {
+  readonly code: CompileCode | DefinitionCode
+  readonly message: string
+}
+
+export interface AppReview {
+  readonly errors: ReviewError[]
+  readonly notices: ReviewNotice[]
+}
+
+type Ts = typeof import('typescript')
+
+interface ReviewOptions {
+  readonly reservedKeyframes?: readonly string[]
+  readonly loadParser?: () => Promise<Ts | undefined>
+}
+
+/**
+ * Keyframe collisions are notices. An unbound component, or a one-edit typo of a
+ * declared name, fails that side. Other free names are not a list this module owns.
+ * A missing parser is a notice and does not fail reload.
+ * @param appDir - absolute app directory
+ */
+export async function reviewApp(appDir: string, options: ReviewOptions = {}): Promise<AppReview> {
+  const notices = keyframeNotices(appDir, new Set(options.reservedKeyframes ?? []))
+  const parser = await loadParser(options.loadParser)
+  if (parser === undefined) {
+    notices.push({
+      code: 'identifier-skipped',
+      message: 'identifier pass skipped: parser did not load',
+    })
+    return { errors: [], notices }
+  }
+  const errors: ReviewError[] = []
+  const events = { push: new Map<string, string>(), on: new Map<string, string>() }
+  for (const file of sourceFiles(appDir)) {
+    const rel = relative(appDir, file)
+    try {
+      reviewFile(parser, rel, readFileSync(file, 'utf8'), errors, events)
+    } catch (error) {
+      errors.push({
+        code: codeFor(rel),
+        message: error instanceof Error ? error.message : `could not parse ${rel}`,
+      })
+    }
+  }
+  for (const [name, pushPath] of events.push) {
+    const onPath = events.on.get(name)
+    if (onPath === undefined) continue
+    errors.push({
+      code: 'event-undeclared',
+      message: `event ${name} is used in ${pushPath} and ${onPath}; declare it once in ${appTrees.shared}/`,
+    })
+  }
+  return { errors, notices }
+}
+
+async function loadParser(injected: ReviewOptions['loadParser']): Promise<Ts | undefined> {
+  try {
+    if (injected !== undefined) return await injected()
+    return await import('typescript')
+  } catch {
+    return undefined
+  }
+}
+
+const sharedForbidden = new Set([
+  'ctx',
+  'React',
+  'document',
+  'window',
+  'navigator',
+  'localStorage',
+  'sessionStorage',
+  'process',
+  'Buffer',
+  'require',
+])
+
+function reviewFile(
+  parser: Ts,
+  rel: string,
+  text: string,
+  errors: ReviewError[],
+  events: { push: Map<string, string>; on: Map<string, string> },
+): void {
+  const source = parser.createSourceFile(rel, text, parser.ScriptTarget.Latest, true, scriptKind(parser, rel))
+  const declared = declaredNames(parser, source)
+  const shared = rel.startsWith(`${appTrees.shared}/`)
+  const visit = (node: ts.Node): void => {
+    if (shared && isJsx(parser, node)) {
+      errors.push({ code: 'shared-invalid', message: `${rel} cannot contain JSX` })
+    }
+    if (shared && parser.isIdentifier(node) && sharedForbidden.has(node.text) && !isPropertyName(parser, node)) {
+      errors.push({ code: 'shared-invalid', message: `${rel} cannot use ${node.text}` })
+    }
+    const specifier = importedSpecifier(parser, node)
+    if (specifier !== undefined) {
+      const decision = importDecision(sideOf(rel), specifier, rel)
+      if (decision !== 'allow' && decision !== 'install' && decision !== 'builtin') errors.push(decision)
+    }
+    const unbound = unboundName(parser, node, declared)
+    if (unbound !== undefined) {
+      errors.push({ code: codeFor(rel), message: `${rel} uses ${unbound}, which is not declared` })
+    }
+    const pushed = pushLiteral(parser, node)
+    if (pushed !== undefined && sideOf(rel) === 'backend' && !events.push.has(pushed)) events.push.set(pushed, rel)
+    const listened = onLiteral(parser, node)
+    if (listened !== undefined && sideOf(rel) === 'ui' && !events.on.has(listened)) events.on.set(listened, rel)
+    parser.forEachChild(node, visit)
+  }
+  visit(source)
+}
+
+function pushLiteral(parser: Ts, node: ts.Node): string | undefined {
+  if (!parser.isCallExpression(node) || !parser.isPropertyAccessExpression(node.expression)) return undefined
+  if (node.expression.name.text !== 'push') return undefined
+  if (!parser.isIdentifier(node.expression.expression) || node.expression.expression.text !== 'ctx') return undefined
+  return stringArg(parser, node)
+}
+
+function onLiteral(parser: Ts, node: ts.Node): string | undefined {
+  if (!parser.isCallExpression(node) || !parser.isPropertyAccessExpression(node.expression)) return undefined
+  if (node.expression.name.text !== 'on') return undefined
+  const target = node.expression.expression
+  if (!parser.isCallExpression(target) || !parser.isIdentifier(target.expression) || target.expression.text !== 'useApp') {
+    return undefined
+  }
+  const name = stringArg(parser, node)
+  return name === undefined || name === '*' ? undefined : name
+}
+
+function stringArg(parser: Ts, node: ts.CallExpression): string | undefined {
+  const arg = node.arguments[0]
+  if (arg === undefined || !parser.isStringLiteral(arg) || arg.text.length === 0) return undefined
+  return arg.text
+}
+
+function declaredNames(parser: Ts, source: ts.SourceFile): Set<string> {
+  const names = new Set<string>()
+  const visit = (node: ts.Node): void => {
+    if (parser.isImportDeclaration(node) && node.importClause?.phaseModifier !== parser.SyntaxKind.TypeKeyword) {
+      addImport(parser, node.importClause, names)
+    }
+    if ((parser.isFunctionDeclaration(node) || parser.isClassDeclaration(node)) && node.name !== undefined) {
+      names.add(node.name.text)
+    }
+    if (parser.isVariableDeclaration(node) && parser.isIdentifier(node.name)) names.add(node.name.text)
+    if (parser.isParameter(node) && parser.isIdentifier(node.name)) names.add(node.name.text)
+    if (parser.isBindingElement(node) && parser.isIdentifier(node.name)) names.add(node.name.text)
+    if (parser.isCatchClause(node) && node.variableDeclaration !== undefined && parser.isIdentifier(node.variableDeclaration.name)) {
+      names.add(node.variableDeclaration.name.text)
+    }
+    parser.forEachChild(node, visit)
+  }
+  visit(source)
+  return names
+}
+
+function addImport(parser: Ts, clause: ts.ImportClause | undefined, names: Set<string>): void {
+  if (clause === undefined) return
+  if (clause.name !== undefined) names.add(clause.name.text)
+  const bindings = clause.namedBindings
+  if (bindings === undefined) return
+  if (parser.isNamespaceImport(bindings)) {
+    names.add(bindings.name.text)
+    return
+  }
+  for (const specifier of bindings.elements) {
+    if (!specifier.isTypeOnly) names.add(specifier.name.text)
+  }
+}
+
+function isJsx(parser: Ts, node: ts.Node): boolean {
+  return parser.isJsxElement(node)
+    || parser.isJsxSelfClosingElement(node)
+    || parser.isJsxFragment(node)
+}
+
+function isPropertyName(parser: Ts, node: ts.Node): boolean {
+  const parent = node.parent
+  return (parser.isPropertyAccessExpression(parent) || parser.isPropertyAssignment(parent)) && parent.name === node
+}
+
+function importedSpecifier(parser: Ts, node: ts.Node): string | undefined {
+  if (parser.isImportDeclaration(node) || parser.isExportDeclaration(node)) {
+    const specifier = node.moduleSpecifier
+    if (specifier !== undefined && parser.isStringLiteral(specifier)) return specifier.text
+  }
+  if (parser.isCallExpression(node) && node.expression.kind === parser.SyntaxKind.ImportKeyword) {
+    const arg = node.arguments[0]
+    if (arg !== undefined && parser.isStringLiteral(arg)) return arg.text
+  }
+  return undefined
+}
+
+function unboundName(parser: Ts, node: ts.Node, declared: Set<string>): string | undefined {
+  if (parser.isJsxOpeningElement(node) || parser.isJsxSelfClosingElement(node)) {
+    const name = jsxRoot(parser, node.tagName)
+    if (name !== undefined && !declared.has(name)) return name
+  }
+  if (!parser.isCallExpression(node) || !parser.isIdentifier(node.expression)) return undefined
+  const name = node.expression.text
+  if (declared.has(name) || near(name, declared) === undefined) return undefined
+  return name
+}
+
+function jsxRoot(parser: Ts, tag: ts.JsxTagNameExpression): string | undefined {
+  if (parser.isIdentifier(tag) && /^[A-Z]/.test(tag.text)) return tag.text
+  if (parser.isPropertyAccessExpression(tag) && parser.isIdentifier(tag.expression)) return tag.expression.text
+  return undefined
+}
+
+function near(name: string, declared: Set<string>): string | undefined {
+  for (const known of declared) {
+    if (oneEdit(name, known)) return known
+  }
+  return undefined
+}
+
+function oneEdit(left: string, right: string): boolean {
+  if (left === right || Math.abs(left.length - right.length) > 1) return false
+  let edits = 0
+  let i = 0
+  let j = 0
+  while (i < left.length && j < right.length) {
+    if (left[i] === right[j]) {
+      i += 1
+      j += 1
+      continue
+    }
+    edits += 1
+    if (edits > 1) return false
+    if (left.length > right.length) i += 1
+    else if (right.length > left.length) j += 1
+    else {
+      i += 1
+      j += 1
+    }
+  }
+  return edits + (left.length - i) + (right.length - j) === 1
+}
+
+function keyframeNotices(appDir: string, reserved: Set<string>): ReviewNotice[] {
+  const seen = new Map<string, string>()
+  const notices: ReviewNotice[] = []
+  for (const file of textFiles(appDir)) {
+    const rel = relative(appDir, file)
+    for (const match of readFileSync(file, 'utf8').matchAll(/@keyframes\s+([A-Za-z_][\w-]*)/g)) {
+      const name = match[1] ?? ''
+      if (name.length === 0) continue
+      const first = seen.get(name)
+      if (first !== undefined) {
+        notices.push({
+          code: 'keyframe-duplicate',
+          message: `@keyframes ${name} is declared in ${first} and ${rel}`,
+          path: rel,
+          name,
+        })
+      } else {
+        seen.set(name, rel)
+      }
+      if (reserved.has(name)) {
+        notices.push({
+          code: 'keyframe-collision',
+          message: `@keyframes ${name} is reserved`,
+          path: rel,
+          name,
+        })
+      }
+    }
+  }
+  return notices
+}
+
+function codeFor(rel: string): CompileCode {
+  if (rel === appEntries.ui || rel.startsWith(`${appTrees.ui}/`)) return 'ui-invalid'
+  if (rel.startsWith(`${appTrees.shared}/`)) return 'shared-invalid'
+  return 'backend-invalid'
+}
+
+function scriptKind(parser: Ts, rel: string): ts.ScriptKind {
+  if (rel.endsWith('.tsx')) return parser.ScriptKind.TSX
+  if (rel.endsWith('.jsx')) return parser.ScriptKind.JSX
+  if (rel.endsWith('.js')) return parser.ScriptKind.JS
+  return parser.ScriptKind.TS
+}
+
+function sourceFiles(appDir: string): string[] {
+  return textFiles(appDir).filter((file) => {
+    const rel = relative(appDir, file)
+    return rel === appEntries.ui
+      || rel === appEntries.backend
+      || rel.startsWith(`${appTrees.ui}/`)
+      || rel.startsWith(`${appTrees.api}/`)
+      || rel.startsWith(`${appTrees.shared}/`)
+  }).filter(file => /\.(ts|tsx|js|jsx)$/.test(file))
+}
+
+function textFiles(appDir: string): string[] {
+  const found: string[] = []
+  const walk = (dir: string): void => {
+    for (const name of readdirSync(dir)) {
+      if (snapshotSkip.has(name)) continue
+      const full = path.join(dir, name)
+      if (statSync(full).isDirectory()) walk(full)
+      else if (/\.(css|ts|tsx|js|jsx)$/.test(name)) found.push(full)
+    }
+  }
+  walk(appDir)
+  return found
+}
+
+function relative(appDir: string, file: string): string {
+  return path.relative(appDir, file).split(path.sep).join('/')
+}

package/src/compile/runner.ts

@@ -0,0 +1,205 @@
+import { renderViewBridge } from '../events/view-bridge.ts'
+import { appResource, httpLayout } from '../http/layout.ts'
+import { diagnosticUrl } from '../tools/diagnostics.ts'
+import { platformImportMap } from './allowlist.ts'
+import { leaveGuardSource } from './leave.ts'
+import { hostWrapperBinding, renderHostWrapper } from './wrapper.ts'
+
+/** Thin bar on WKWebView and WebView2. `scrollbar-width` covers the rest. */
+const thinScrollbarCss = 'html{scrollbar-width:thin;scrollbar-color:color-mix(in srgb,CanvasText 32%,transparent) transparent}*{scrollbar-width:thin;scrollbar-color:color-mix(in srgb,CanvasText 32%,transparent) transparent}::-webkit-scrollbar{-webkit-appearance:none;width:8px;height:8px}::-webkit-scrollbar-track,::-webkit-scrollbar-corner{background:transparent}::-webkit-scrollbar-thumb{background:color-mix(in srgb,CanvasText 32%,transparent);border:2px solid transparent;border-radius:999px;background-clip:padding-box}'
+
+/**
+ * The first document for one app. The iframe runner route serves it.
+ * Boot art is cleared before the component mounts. The host injects the error boundary.
+ * The UI bundle is a later request. This document does not wait for it.
+ * @param input - app id, entry URL, and first-paint CSS
+ */
+export function renderRunnerDocument(input: {
+  readonly appId: string
+  readonly entry: string
+  readonly style: string
+  readonly appearance: 'system' | 'light' | 'dark'
+  /** Host chrome locale. Kit uses `en` | `zh`. */
+  readonly locale?: string
+}): string {
+  const errors = diagnosticUrl(input.appId, 'errors')
+  const alive = diagnosticUrl(input.appId, 'alive')
+  return `<!doctype html>
+<html${appearanceAttribute(input.appearance)}>
+<head>
+<meta charset="utf-8">
+<link rel="stylesheet" href="${appResource(input.appId, httpLayout.ui, httpLayout.sheet)}">
+<style id="mma-first-paint">${escapeStyle(input.style)}</style>
+<style>html,body,#root{height:100%;margin:0}#root>div{height:100%;min-height:0;display:flex;flex-direction:column}${thinScrollbarCss}</style>
+<script type="importmap">
+${JSON.stringify({ imports: platformImportMap() })}
+</script>
+${appearanceScript(input.appearance)}
+<script>
+${leaveGuardSource()}
+</script>
+</head>
+<body>
+<div id="boot"></div>
+<div id="root"></div>
+<script>
+${renderViewBridge({ appId: input.appId, evalUrl: diagnosticUrl(input.appId, 'viewEval') })}
+${renderHostWrapper(input.appId)}
+</script>
+<script type="module">
+${reportedMessageSource()}
+const boot = document.getElementById('boot')
+if (boot) boot.remove()
+await fetch(${JSON.stringify(alive)}, { method: 'POST', body: '{}' })
+${uncaughtReporterSource(errors)}
+${asyncReporterSource(errors)}
+${moduleErrorPaintSource(kitLocale(input.locale))}
+try {
+  const module = await import(${JSON.stringify(input.entry)})
+  const component = module.default
+  if (typeof component !== 'function') {
+    const message = 'default export is not a component'
+    void fetch(${JSON.stringify(errors)}, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ kind: 'module', message }) })
+    paintModuleError(${JSON.stringify(input.appId)}, message)
+  } else {
+  const React = await import('react')
+  const ui = await import('@mohou/ui')
+  const frame = window[${JSON.stringify(hostWrapperBinding.host)}]
+  function HostFrame(props) {
+    return frame.runInside(() => props.component({}))
+  }
+  const root = React.createElement(
+    ui.AppRuntime,
+    { appId: ${JSON.stringify(input.appId)} },
+    React.createElement(
+      ui.UiProvider,
+      { locale: ${JSON.stringify(kitLocale(input.locale))} },
+      React.createElement(ui.AppErrorBoundary, null, React.createElement(HostFrame, { component })),
+    ),
+  )
+  const target = document.getElementById('root')
+  if (target) target.replaceChildren(document.createTextNode(''))
+  const host = document.createElement('div')
+  target?.append(host)
+  const client = React.createRoot?.(host)
+  if (client) client.render(root)
+  }
+} catch (error) {
+  const message = reportedMessage(error)
+  const text = message.length > 0 ? message : 'UI module failed to load'
+  if (message.length > 0) {
+  void fetch(${JSON.stringify(errors)}, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ kind: 'module', message }) })
+  }
+  paintModuleError(${JSON.stringify(input.appId)}, text)
+}
+</script>
+</body>
+</html>`
+}
+
+/** Message already on an error. Empty and non-errors are not given a stand-in. */
+export function reportedMessageSource(): string {
+  return `function reportedMessage(error) {
+  if (error instanceof Error) return error.message
+  return typeof error === 'string' ? error : ''
+}`
+}
+
+/**
+ * Vanilla fallback when the UI module never mounts React.
+ * Does not import the kit — module failure may be the kit itself.
+ */
+export function moduleErrorPaintSource(locale: 'en' | 'zh'): string {
+  const copy = locale === 'zh'
+    ? {
+      title: '小程序未能加载',
+      hint: '入口模块没有起来，通常是依赖导出缺失或需要重新编译。',
+      reload: '重新加载',
+    }
+    : {
+      title: 'This mini-app failed to load',
+      hint: 'The UI bundle did not load — a missing export or a compile is the usual cause.',
+      reload: 'Reload',
+    }
+  return `function paintModuleError(appId, message) {
+  const target = document.getElementById('root')
+  if (!target) return
+  target.replaceChildren()
+  const card = document.createElement('div')
+  card.setAttribute('role', 'alert')
+  card.dataset.moduleError = '1'
+  card.style.cssText = 'box-sizing:border-box;margin:24px;padding:16px 18px;border-radius:12px;border:1px solid var(--destructive,#dc2626);background:var(--card,#fff);color:var(--foreground,#111);font:13px/1.6 var(--font-sans,ui-sans-serif,system-ui,sans-serif);max-width:720px'
+  const head = document.createElement('div')
+  head.style.cssText = 'display:flex;align-items:center;gap:8px;margin-bottom:6px'
+  const dot = document.createElement('span')
+  dot.style.cssText = 'width:8px;height:8px;border-radius:50%;background:var(--destructive,#dc2626);flex:0 0 auto'
+  const title = document.createElement('strong')
+  title.style.fontSize = '14px'
+  title.textContent = ${JSON.stringify(copy.title)}
+  const id = document.createElement('code')
+  id.style.cssText = 'margin-left:auto;padding:1px 6px;border-radius:6px;background:var(--muted,#f3f4f6);color:var(--muted-foreground,#6b7280);font-size:11px'
+  id.textContent = appId
+  head.append(dot, title, id)
+  const hint = document.createElement('p')
+  hint.style.cssText = 'margin:0 0 8px;color:var(--muted-foreground,#6b7280)'
+  hint.textContent = ${JSON.stringify(copy.hint)}
+  const pre = document.createElement('pre')
+  pre.style.cssText = 'margin:0;padding:10px 12px;border-radius:8px;background:var(--muted,#f3f4f6);white-space:pre-wrap;word-break:break-word;font-family:var(--font-mono,ui-monospace,SFMono-Regular,monospace);font-size:12px'
+  pre.textContent = message
+  const row = document.createElement('div')
+  row.style.cssText = 'display:flex;gap:8px;align-items:center;margin-top:12px'
+  const btn = document.createElement('button')
+  btn.type = 'button'
+  btn.textContent = ${JSON.stringify(copy.reload)}
+  btn.style.cssText = 'padding:5px 12px;border-radius:8px;border:1px solid var(--border,#e5e7eb);background:var(--primary,#2563eb);color:var(--primary-foreground,#fff);font:inherit;cursor:pointer'
+  btn.onclick = () => { location.reload() }
+  row.append(btn)
+  card.append(head, hint, pre, row)
+  target.append(card)
+}`
+}
+
+/** Post an unhandled rejection only when it already has a message. */
+export function asyncReporterSource(errorsUrl: string): string {
+  return `window.addEventListener('unhandledrejection', (event) => {
+  const reason = event.reason
+  const message = reason instanceof Error ? reason.message : typeof reason === 'string' ? reason : ''
+  if (message.length === 0) return
+  void fetch(${JSON.stringify(errorsUrl)}, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ kind: 'async', message }) })
+})`
+}
+
+/** Drop a resource-load error. Those events have no message and are not script failures. */
+export function uncaughtReporterSource(errorsUrl: string): string {
+  return `window.addEventListener('error', (event) => {
+  if (event.target && event.target !== window) return
+  if (typeof event.message !== 'string' || event.message.length === 0) return
+  void fetch(${JSON.stringify(errorsUrl)}, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ kind: 'uncaught', message: event.message }) })
+})`
+}
+
+function escapeStyle(style: string): string {
+  return style.replaceAll('</', '<\\/')
+}
+
+/** Map host `en` | `zh-CN` onto kit `en` | `zh`. */
+export function kitLocale(host: string | undefined): 'en' | 'zh' {
+  if (host === 'zh-CN' || host === 'zh') return 'zh'
+  return 'en'
+}
+
+function appearanceAttribute(appearance: 'system' | 'light' | 'dark'): string {
+  if (appearance === 'system') return ''
+  return ` data-mode="${appearance}"`
+}
+
+function appearanceScript(appearance: 'system' | 'light' | 'dark'): string {
+  if (appearance !== 'system') return ''
+  return `<script>
+const applyMode = () => {
+  document.documentElement.dataset.mode = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+}
+applyMode()
+matchMedia('(prefers-color-scheme: dark)').addEventListener('change', applyMode)
+</script>`
+}