feat(contracts): Route/Render/Theme Manifest 契约 v1 冻结

Co-Authored-By: Claude Code <noreply@anthropic.com>

packages/contracts/src/index.ts

@@ -1 +1,4 @@
 export * from './universal-row.js'
+export * from './route-manifest.js'
+export * from './render-snapshot.js'
+export * from './theme-manifest.js'

packages/contracts/src/render-snapshot.ts

@@ -0,0 +1,17 @@
+export const RENDER_SNAPSHOT_VERSION = 1
+
+export const RENDER_SNAPSHOT_FILES = [
+  'site.json', 'content.json', 'taxonomies.json', 'routes.json', 'assets.json', 'render-manifest.json',
+] as const
+
+export type RenderSnapshotFile = (typeof RENDER_SNAPSHOT_FILES)[number]
+
+// 契约冻结锁（spec §9.2）：清单与冻结集双向咬合——漏改/多改/改名任何一项 → TS2322
+type FrozenRenderSnapshotFiles =
+  | 'site.json' | 'content.json' | 'taxonomies.json'
+  | 'routes.json' | 'assets.json' | 'render-manifest.json'
+
+type _RenderFilesMatchSpec = [RenderSnapshotFile] extends [FrozenRenderSnapshotFiles]
+  ? ([FrozenRenderSnapshotFiles] extends [RenderSnapshotFile] ? true : never)
+  : never
+const _renderFilesComplete: _RenderFilesMatchSpec = true

packages/contracts/src/route-manifest.ts

@@ -0,0 +1,45 @@
+export const ROUTE_MANIFEST_VERSION = 1
+
+export type RouteKind = 'html' | 'asset' | 'redirect' | 'gone' | 'dynamic' | 'unresolved'
+export type QueryPolicy = 'ignore' | 'exact' | 'preserve' | 'dynamic'
+
+export interface RouteManifestRoute {
+  exact_key: string
+  query_policy: QueryPolicy
+  query_key?: string | null
+  kind: RouteKind
+  target_file?: string
+  status: number
+  location?: string
+  content_type?: string
+  indexable: boolean
+}
+
+export interface RouteManifest {
+  manifest_version: number
+  site_id: string
+  build_job_id: string
+  origin: string
+  generated_from_route_snapshot_hash: string
+  routes: RouteManifestRoute[]
+}
+
+const KINDS = ['html', 'asset', 'redirect', 'gone', 'dynamic', 'unresolved'] as const
+const QUERY_POLICIES = ['ignore', 'exact', 'preserve', 'dynamic'] as const
+
+// 守卫查值类型（不只查键存在）：版本号、顶层必填字符串、routes 元素的枚举与标量类型全部校验
+export function isRouteManifest(v: unknown): v is RouteManifest {
+  if (typeof v !== 'object' || v === null) return false
+  const m = v as RouteManifest
+  return m.manifest_version === ROUTE_MANIFEST_VERSION
+    && typeof m.site_id === 'string'
+    && typeof m.build_job_id === 'string'
+    && typeof m.origin === 'string'
+    && typeof m.generated_from_route_snapshot_hash === 'string'
+    && Array.isArray(m.routes) && m.routes.every((r) =>
+      typeof r.exact_key === 'string'
+      && (QUERY_POLICIES as readonly string[]).includes(r.query_policy)
+      && (KINDS as readonly string[]).includes(r.kind)
+      && typeof r.status === 'number'
+      && typeof r.indexable === 'boolean')
+}

packages/contracts/src/theme-manifest.ts

@@ -0,0 +1,29 @@
+export const THEME_MANIFEST_VERSION = 1
+
+export interface ThemeManifest {
+  key: string
+  version: string
+  renderContractVersion: string
+  supportedContentTypes: string[]
+  requiredSiteConfig: string[]
+  templates: Array<{ key: string; appliesTo: string }>
+}
+
+const SEMVER = /^\d+\.\d+\.\d+$/
+
+// 守卫查值类型（不只查键存在）：semver 格式、字符串字段、数组元素类型全部校验
+export function isThemeManifest(v: unknown): v is ThemeManifest {
+  if (typeof v !== 'object' || v === null) return false
+  const m = v as ThemeManifest
+  return typeof m.key === 'string'
+    && typeof m.version === 'string' && SEMVER.test(m.version)
+    && typeof m.renderContractVersion === 'string'
+    && Array.isArray(m.supportedContentTypes)
+      && m.supportedContentTypes.every((t) => typeof t === 'string')
+    && Array.isArray(m.requiredSiteConfig)
+      && m.requiredSiteConfig.every((t) => typeof t === 'string')
+    && Array.isArray(m.templates)
+      && m.templates.every((t) => typeof t === 'object' && t !== null
+        && typeof (t as { key: unknown }).key === 'string'
+        && typeof (t as { appliesTo: unknown }).appliesTo === 'string')
+}

packages/contracts/test/manifests.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from 'vitest'
+import {
+  ROUTE_MANIFEST_VERSION, RENDER_SNAPSHOT_VERSION, THEME_MANIFEST_VERSION,
+  RENDER_SNAPSHOT_FILES, isRouteManifest, isThemeManifest,
+} from '../src/index.js'
+
+const validRouteManifest: any = {
+  manifest_version: 1, site_id: 's1', build_job_id: 'b1', origin: 'https://fixture.example',
+  generated_from_route_snapshot_hash: 'abc',
+  routes: [{ exact_key: '/', query_policy: 'ignore', kind: 'html', target_file: 'index.html', status: 200, indexable: true }],
+}
+
+const validThemeManifest: any = {
+  key: 'pilot-minimal', version: '0.1.0', renderContractVersion: '1',
+  supportedContentTypes: ['news_article', 'product', 'basic_page'],
+  requiredSiteConfig: ['origin', 'listPaths'],
+  templates: [{ key: 'home', appliesTo: 'home' }],
+}
+
+describe('manifest 契约', () => {
+  it('三个版本号冻结为 1', () => {
+    expect([ROUTE_MANIFEST_VERSION, RENDER_SNAPSHOT_VERSION, THEME_MANIFEST_VERSION]).toEqual([1, 1, 1])
+  })
+  it('Render Snapshot 文件清单冻结（spec §9.2）', () => {
+    expect(RENDER_SNAPSHOT_FILES).toEqual([
+      'site.json', 'content.json', 'taxonomies.json', 'routes.json', 'assets.json', 'render-manifest.json',
+    ])
+  })
+  it('合法 RouteManifest 通过守卫', () => {
+    expect(isRouteManifest({
+      manifest_version: 1, site_id: 's1', build_job_id: 'b1', origin: 'https://fixture.example',
+      generated_from_route_snapshot_hash: 'abc',
+      routes: [{ exact_key: '/', query_policy: 'ignore', kind: 'html', target_file: 'index.html', status: 200, indexable: true }],
+    })).toBe(true)
+  })
+  it('非法 kind 拒绝', () => {
+    const m: any = { manifest_version: 1, site_id: 's', build_job_id: 'b', origin: 'o', generated_from_route_snapshot_hash: 'h', routes: [{ exact_key: '/', query_policy: 'ignore', kind: 'weird', status: 200, indexable: true }] }
+    expect(isRouteManifest(m)).toBe(false)
+  })
+  it('合法 ThemeManifest 通过守卫', () => {
+    expect(isThemeManifest({
+      key: 'pilot-minimal', version: '0.1.0', renderContractVersion: '1',
+      supportedContentTypes: ['news_article', 'product', 'basic_page'],
+      requiredSiteConfig: ['origin', 'listPaths'],
+      templates: [{ key: 'home', appliesTo: 'home' }],
+    })).toBe(true)
+  })
+})
+
+describe('RouteManifest 守卫拒绝路径', () => {
+  it('manifest_version ≠ 1 拒绝（2 与字符串 "1"）', () => {
+    expect(isRouteManifest({ ...validRouteManifest, manifest_version: 2 })).toBe(false)
+    expect(isRouteManifest({ ...validRouteManifest, manifest_version: '1' })).toBe(false)
+  })
+
+  it('routes 非数组拒绝（字符串）', () => {
+    expect(isRouteManifest({ ...validRouteManifest, routes: 'x' })).toBe(false)
+  })
+
+  it('routes 元素缺 exact_key 拒绝', () => {
+    const { exact_key: _omit, ...route } = validRouteManifest.routes[0]
+    expect(isRouteManifest({ ...validRouteManifest, routes: [route] })).toBe(false)
+  })
+
+  it('status 非数字拒绝（status: "200"）', () => {
+    expect(isRouteManifest({
+      ...validRouteManifest,
+      routes: [{ ...validRouteManifest.routes[0], status: '200' }],
+    })).toBe(false)
+  })
+
+  it('indexable 非布尔拒绝（indexable: 1）', () => {
+    expect(isRouteManifest({
+      ...validRouteManifest,
+      routes: [{ ...validRouteManifest.routes[0], indexable: 1 }],
+    })).toBe(false)
+  })
+
+  it('query_policy 非四值之一拒绝', () => {
+    expect(isRouteManifest({
+      ...validRouteManifest,
+      routes: [{ ...validRouteManifest.routes[0], query_policy: 'loose' }],
+    })).toBe(false)
+  })
+
+  it('顶层必填字符串字段非字符串拒绝（site_id 数字）', () => {
+    expect(isRouteManifest({ ...validRouteManifest, site_id: 101 })).toBe(false)
+  })
+
+  it('非对象输入拒绝（null / number / array）', () => {
+    expect(isRouteManifest(null)).toBe(false)
+    expect(isRouteManifest(42)).toBe(false)
+    expect(isRouteManifest([])).toBe(false)
+  })
+})
+
+describe('ThemeManifest 守卫拒绝路径', () => {
+  it('version 非 semver 拒绝（"abc" 与 "1"）', () => {
+    expect(isThemeManifest({ ...validThemeManifest, version: 'abc' })).toBe(false)
+    expect(isThemeManifest({ ...validThemeManifest, version: '1' })).toBe(false)
+  })
+
+  it('key 非字符串拒绝（数字）', () => {
+    expect(isThemeManifest({ ...validThemeManifest, key: 42 })).toBe(false)
+  })
+
+  it('templates 非数组拒绝', () => {
+    expect(isThemeManifest({ ...validThemeManifest, templates: 'x' })).toBe(false)
+  })
+
+  it('templates 元素缺 appliesTo 拒绝（查值类型，不只查键存在）', () => {
+    expect(isThemeManifest({
+      ...validThemeManifest,
+      templates: [{ key: 'home', appliesTo: 42 }],
+    })).toBe(false)
+  })
+
+  it('renderContractVersion 非字符串拒绝', () => {
+    expect(isThemeManifest({ ...validThemeManifest, renderContractVersion: 1 })).toBe(false)
+  })
+
+  it('非对象输入拒绝（null / number）', () => {
+    expect(isThemeManifest(null)).toBe(false)
+    expect(isThemeManifest(42)).toBe(false)
+  })
+})