@nextsparkjs/core 0.1.0-beta.189 → 0.1.0-beta.190

package/scripts/build/registry/__tests__/page-generator.test.mjs

@@ -20,9 +20,11 @@ import { join, dirname } from 'node:path'
 import {
   SEGMENT_CONFIG_EXPORTS,
   MODULE_LEVEL_EXPORTS,
+  analyzeTemplates,
   extractRouteExports,
   generateTemplatePage,
-  generateMissingPages,
+  selectTypeScriptModule,
+  willGenerateRoute,
 } from '../post-build/page-generator.mjs'
 
 const FIXTURE_FILE = '/virtual/theme/templates/(public)/page.tsx'
@@ -34,13 +36,11 @@ async function createProjectRoot() {
   return mkdtemp(join(tmpdir(), 'nextspark-page-generator-test-'))
 }
 
-// generateTemplatePage resolves '@/...' template paths against the
-// generator's module-level rootDir, which is only ever set as a side effect
-// of generateMissingPages. Templates being empty makes it a no-op beyond
-// that assignment (cleanupOrphanedTemplates returns early when app/(templates)
-// doesn't exist yet under the given root).
-async function useProjectRoot(root) {
-  await generateMissingPages([], { projectRoot: root })
+// The registry build parses templates once, with analyzeTemplates, and the page
+// generator renders from that analysis. Generating a single page does the same.
+async function generatePage(template, outputPath, root) {
+  const analysis = await analyzeTemplates([template], { projectRoot: root })
+  await generateTemplatePage(template, outputPath, analysis)
 }
 
 async function writeThemeTemplate(root, relativePath, content) {
@@ -198,7 +198,6 @@ test('the error names the line the bad export is declared on', async () => {
 test('the generated page re-declares segment config as a literal and forwards module exports separately', async () => {
   const root = await createProjectRoot()
   try {
-    await useProjectRoot(root)
     const templatePath = await writeThemeTemplate(
       root,
       '(public)/blog/[slug]/page.tsx',
@@ -206,9 +205,10 @@ test('the generated page re-declares segment config as a literal and forwards mo
     )
 
     const outputPath = join(root, 'app/(templates)/(public)/blog/[slug]/page.tsx')
-    await generateTemplatePage(
+    await generatePage(
       { appPath: 'app/(public)/blog/[slug]/page.tsx', templateType: 'page', name: '(public)/blog/[slug]/page', templatePath },
-      outputPath
+      outputPath,
+      root
     )
 
     const generated = await readFile(outputPath, 'utf8')
@@ -228,13 +228,13 @@ test('the generated page re-declares segment config as a literal and forwards mo
 test('a page with no route-level exports is generated unchanged (no forwarded-exports section)', async () => {
   const root = await createProjectRoot()
   try {
-    await useProjectRoot(root)
     const templatePath = await writeThemeTemplate(root, 'plain/page.tsx', 'export default function Page() { return null }\n')
 
     const outputPath = join(root, 'app/(templates)/plain/page.tsx')
-    await generateTemplatePage(
+    await generatePage(
       { appPath: 'app/plain/page.tsx', templateType: 'page', name: 'plain/page', templatePath },
-      outputPath
+      outputPath,
+      root
     )
 
     const generated = await readFile(outputPath, 'utf8')
@@ -249,7 +249,6 @@ test('a page with no route-level exports is generated unchanged (no forwarded-ex
 test('an invalid segment config value fails page generation instead of being silently dropped', async () => {
   const root = await createProjectRoot()
   try {
-    await useProjectRoot(root)
     const templatePath = await writeThemeTemplate(
       root,
       'broken/page.tsx',
@@ -259,9 +258,10 @@ test('an invalid segment config value fails page generation instead of being sil
     const outputPath = join(root, 'app/(templates)/broken/page.tsx')
     await assert.rejects(
       () =>
-        generateTemplatePage(
+        generatePage(
           { appPath: 'app/broken/page.tsx', templateType: 'page', name: 'broken/page', templatePath },
-          outputPath
+          outputPath,
+          root
         ),
       /"revalidate"/
     )
@@ -273,7 +273,6 @@ test('an invalid segment config value fails page generation instead of being sil
 test('a layout with a default export and metadata forwards both, unlike the previous component-only behavior', async () => {
   const root = await createProjectRoot()
   try {
-    await useProjectRoot(root)
     const templatePath = await writeThemeTemplate(
       root,
       'dashboard/layout.tsx',
@@ -281,9 +280,10 @@ test('a layout with a default export and metadata forwards both, unlike the prev
     )
 
     const outputPath = join(root, 'app/(templates)/dashboard/layout.tsx')
-    await generateTemplatePage(
+    await generatePage(
       { appPath: 'app/dashboard/layout.tsx', templateType: 'layout', name: 'dashboard/layout', templatePath },
-      outputPath
+      outputPath,
+      root
     )
 
     const generated = await readFile(outputPath, 'utf8')
@@ -297,13 +297,13 @@ test('a layout with a default export and metadata forwards both, unlike the prev
 test('a layout template with no exports at all still gets the plain pass-through wrapper', async () => {
   const root = await createProjectRoot()
   try {
-    await useProjectRoot(root)
     const templatePath = await writeThemeTemplate(root, 'empty/layout.tsx', '')
 
     const outputPath = join(root, 'app/(templates)/empty/layout.tsx')
-    await generateTemplatePage(
+    await generatePage(
       { appPath: 'app/empty/layout.tsx', templateType: 'layout', name: 'empty/layout', templatePath },
-      outputPath
+      outputPath,
+      root
     )
 
     const generated = await readFile(outputPath, 'utf8')
@@ -335,7 +335,6 @@ for (const [label, source, expected] of [
 test('a metadata-only layout whose comment mentions export default gets the pass-through, not an import of a missing default', async () => {
   const root = await createProjectRoot()
   try {
-    await useProjectRoot(root)
     const templatePath = await writeThemeTemplate(
       root,
       'docs/layout.tsx',
@@ -343,13 +342,14 @@ test('a metadata-only layout whose comment mentions export default gets the pass
     )
 
     const outputPath = join(root, 'app/(templates)/docs/layout.tsx')
-    await generateTemplatePage(
+    await generatePage(
       { appPath: 'app/docs/layout.tsx', templateType: 'layout', name: 'docs/layout', templatePath },
-      outputPath
+      outputPath,
+      root
     )
 
     const generated = await readFile(outputPath, 'utf8')
-    assert.match(generated, /Layout template - metadata-only/)
+    assert.match(generated, /Pass-through component/)
     assert.doesNotMatch(generated, /import TemplateComponent from/)
     assert.match(generated, /export \{ metadata \} from/)
   } finally {
@@ -357,10 +357,45 @@ test('a metadata-only layout whose comment mentions export default gets the pass
   }
 })
 
+test('a pass-through layout on an unprotected path does not claim to be PROTECTED_RENDER', async () => {
+  const root = await createProjectRoot()
+  try {
+    const templatePath = await writeThemeTemplate(root, '(public)/docs/layout.tsx', "export const viewport = { themeColor: 'black' }\n")
+
+    const outputPath = join(root, 'app/(templates)/(public)/docs/layout.tsx')
+    await generatePage(
+      { appPath: 'app/(public)/docs/layout.tsx', templateType: 'layout', name: '(public)/docs/layout', templatePath },
+      outputPath,
+      root
+    )
+
+    const generated = await readFile(outputPath, 'utf8')
+    assert.match(generated, /Pass-through component \(the theme template exports no component/)
+    assert.doesNotMatch(generated, /PROTECTED_RENDER/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('a pass-through layout on a PROTECTED_RENDER path is labeled as one', async () => {
+  const root = await createProjectRoot()
+  try {
+    const templatePath = await writeThemeTemplate(root, 'layout.tsx', "export const metadata = { title: 'App' }\n")
+
+    const outputPath = join(root, 'app/(templates)/layout.tsx')
+    await generatePage({ appPath: 'app/layout.tsx', templateType: 'layout', name: 'layout', templatePath }, outputPath, root)
+
+    const generated = await readFile(outputPath, 'utf8')
+    assert.match(generated, /Layout template - metadata-only \(PROTECTED_RENDER\)/)
+    assert.match(generated, /Pass-through component \(actual rendering blocked by PROTECTED_RENDER\)/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
 test('a layout exported through `export { X as default }` imports the theme component instead of a pass-through', async () => {
   const root = await createProjectRoot()
   try {
-    await useProjectRoot(root)
     const templatePath = await writeThemeTemplate(
       root,
       'dashboard/layout.tsx',
@@ -368,9 +403,10 @@ test('a layout exported through `export { X as default }` imports the theme comp
     )
 
     const outputPath = join(root, 'app/(templates)/dashboard/layout.tsx')
-    await generateTemplatePage(
+    await generatePage(
       { appPath: 'app/dashboard/layout.tsx', templateType: 'layout', name: 'dashboard/layout', templatePath },
-      outputPath
+      outputPath,
+      root
     )
 
     const generated = await readFile(outputPath, 'utf8')
@@ -392,7 +428,6 @@ test('a .ts template is parsed as TypeScript, so syntax a TSX parse reads as JSX
 test('a .ts layout with TypeScript-only syntax imports the theme component instead of a pass-through', async () => {
   const root = await createProjectRoot()
   try {
-    await useProjectRoot(root)
     const templatePath = await writeThemeTemplate(
       root,
       'reports/layout.ts',
@@ -400,9 +435,10 @@ test('a .ts layout with TypeScript-only syntax imports the theme component inste
     )
 
     const outputPath = join(root, 'app/(templates)/reports/layout.ts')
-    await generateTemplatePage(
+    await generatePage(
       { appPath: 'app/reports/layout.ts', templateType: 'layout', name: 'reports/layout', templatePath },
-      outputPath
+      outputPath,
+      root
     )
 
     const generated = await readFile(outputPath, 'utf8')
@@ -420,11 +456,149 @@ test('a template that does not parse fails with its file and line instead of bei
   )
 })
 
-test('syntax Next.js parses but the installed TypeScript does not (a source phase import) is read instead of rejected', async () => {
+test('a template using syntax TypeScript rejects but Next.js accepts retains its route exports', async () => {
   const source = "import source wasm from './module.wasm'\nexport const runtime = 'edge'\nexport default wasm\n"
   for (const file of ['/virtual/theme/templates/(public)/page.ts', FIXTURE_FILE]) {
-    const { segmentConfig, hasDefaultExport } = await extractRouteExports(source, file)
-    assert.deepEqual(segmentConfig, { runtime: 'edge' }, file)
-    assert.equal(hasDefaultExport, true, file)
+    const routeExports = await extractRouteExports(source, file)
+    assert.deepEqual(routeExports.segmentConfig, { runtime: 'edge' })
+    assert.equal(routeExports.hasDefaultExport, true)
+  }
+})
+
+test('a syntax error rejected by both TypeScript and Next.js is rejected even when TypeScript recovers later route exports', async () => {
+  const source = "import = './module.wasm'\nexport const runtime = 'edge'\nexport default wasm\n"
+  for (const file of ['/virtual/theme/templates/(public)/page.ts', FIXTURE_FILE]) {
+    await assert.rejects(() => extractRouteExports(source, file), /the template does not parse/)
+  }
+})
+
+// --- selectTypeScriptModule: picking a candidate with the TS 5/6 compiler API (#195) --
+
+// A stand-in for TypeScript 7's native port: it has a version but none of the
+// compiler API (`createSourceFile`, `getScriptKindFromFileName`, `ScriptKind`)
+// this generator parses templates with.
+const fakeTypeScript7 = { version: '7.0.2' }
+
+const fakeTypeScript5 = {
+  version: '5.9.3',
+  createSourceFile: () => ({}),
+  getScriptKindFromFileName: () => 1,
+  ScriptKind: { TSX: 4 },
+}
+
+test('a candidate with the compiler API is used', async () => {
+  const ts = await selectTypeScriptModule([{ label: 'only candidate', load: async () => fakeTypeScript5 }])
+  assert.equal(ts, fakeTypeScript5)
+})
+
+test('a candidate module shaped like an ESM default export is unwrapped', async () => {
+  const ts = await selectTypeScriptModule([{ label: 'only candidate', load: async () => ({ default: fakeTypeScript5 }) }])
+  assert.equal(ts, fakeTypeScript5)
+})
+
+test('a TypeScript 7 candidate without the compiler API is skipped in favor of the next candidate that has it', async () => {
+  const ts = await selectTypeScriptModule([
+    { label: '@nextsparkjs/core', load: async () => fakeTypeScript7 },
+    { label: 'the project', load: async () => fakeTypeScript5 },
+  ])
+  assert.equal(ts, fakeTypeScript5)
+})
+
+test('a candidate whose load() rejects is skipped in favor of the next candidate', async () => {
+  const ts = await selectTypeScriptModule([
+    { label: '@nextsparkjs/core', load: async () => { throw new Error('Cannot find module \'typescript\'') } },
+    { label: 'the project', load: async () => fakeTypeScript5 },
+  ])
+  assert.equal(ts, fakeTypeScript5)
+})
+
+test('no candidate providing the compiler API fails with a message naming each candidate and what was found', async () => {
+  await assert.rejects(
+    () =>
+      selectTypeScriptModule([
+        { label: '@nextsparkjs/core', load: async () => fakeTypeScript7 },
+        { label: 'the project at /virtual/project', load: async () => { throw new Error('Cannot find module \'typescript\'') } },
+      ]),
+    error => {
+      assert.match(error.message, /TypeScript 5 or 6 compiler API/)
+      assert.match(error.message, /@nextsparkjs\/core.*TypeScript 7\.0\.2/)
+      assert.match(error.message, /the project at \/virtual\/project.*could not be loaded/)
+      assert.doesNotMatch(error.message, /createSourceFile is not a function/)
+      return true
+    }
+  )
+})
+
+// --- willGenerateRoute: whether the page generator writes a route file importing the template (#197) --
+
+test('willGenerateRoute is always true for a layout, whether or not the app already has one', async () => {
+  const root = await createProjectRoot()
+  try {
+    assert.equal(willGenerateRoute('app/dashboard/layout.tsx', 'layout', root), true)
+
+    await mkdir(join(root, 'app/dashboard'), { recursive: true })
+    await writeFile(join(root, 'app/dashboard/layout.tsx'), 'export default function Layout({ children }) { return children }\n', 'utf8')
+    assert.equal(willGenerateRoute('app/dashboard/layout.tsx', 'layout', root), true)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+// --- analyzeTemplates: what the build reads from each template, and generates from (#197) --
+
+test('analyzeTemplates records, per template path, its route-level exports, whether it has a default export and whether a route file is generated', async () => {
+  const root = await createProjectRoot()
+  try {
+    const layoutPath = await writeThemeTemplate(root, 'docs/layout.tsx', "export const revalidate = 60\nexport const viewport = { themeColor: 'black' }\n")
+    const pagePath = await writeThemeTemplate(root, 'pricing/page.tsx', 'export default function Page() { return null }\n')
+    await mkdir(join(root, 'app/pricing'), { recursive: true })
+    await writeFile(join(root, 'app/pricing/page.tsx'), 'export default function Page() { return null }\n', 'utf8')
+    const layout = { appPath: 'app/docs/layout.tsx', templateType: 'layout', name: 'docs/layout', templatePath: layoutPath }
+    const page = { appPath: 'app/pricing/page.tsx', templateType: 'page', name: 'pricing/page', templatePath: pagePath }
+
+    const analysis = await analyzeTemplates([layout, page, { ...page }], { projectRoot: root })
+
+    assert.deepEqual([...analysis.keys()], [layoutPath, pagePath])
+    assert.deepEqual(analysis.get(layoutPath), {
+      segmentConfig: { revalidate: 60 },
+      moduleExports: ['viewport'],
+      hasDefaultExport: false,
+      generatesRoute: true,
+    })
+    assert.deepEqual(analysis.get(pagePath), { segmentConfig: {}, moduleExports: [], hasDefaultExport: true, generatesRoute: false })
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('generating a page from an analysis that never read its template fails instead of reading the template', async () => {
+  const root = await createProjectRoot()
+  try {
+    const templatePath = await writeThemeTemplate(root, 'plain/page.tsx', 'export default function Page() { return null }\n')
+
+    await assert.rejects(
+      () =>
+        generateTemplatePage(
+          { appPath: 'app/plain/page.tsx', templateType: 'page', name: 'plain/page', templatePath },
+          join(root, 'app/(templates)/plain/page.tsx'),
+          new Map()
+        ),
+      /was not read by analyzeTemplates/
+    )
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('willGenerateRoute is true for a page only when the app has no file there yet', async () => {
+  const root = await createProjectRoot()
+  try {
+    assert.equal(willGenerateRoute('app/docs/page.tsx', 'page', root), true)
+
+    await mkdir(join(root, 'app/docs'), { recursive: true })
+    await writeFile(join(root, 'app/docs/page.tsx'), 'export default function Page() { return null }\n', 'utf8')
+    assert.equal(willGenerateRoute('app/docs/page.tsx', 'page', root), false)
+  } finally {
+    await rm(root, { recursive: true, force: true })
   }
 })

package/scripts/build/registry/__tests__/published-signatures.test.mjs

@@ -0,0 +1,239 @@
+/**
+ * The template generators @nextsparkjs/core exposes through `./scripts/*`
+ * keep the signatures they were published with. A caller that doesn't pass
+ * the analysis `analyzeTemplates` produces gets one taken for that call, with
+ * the same output the registry build produces, and no generator deletes
+ * anything before its input has been checked.
+ *
+ * Run: node --test packages/core/scripts/build/registry/__tests__/published-signatures.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+
+import {
+  generateTemplateRegistry,
+  generateTemplateRegistryClient
+} from '../generators/template-registry.mjs'
+import { generateMissingPages, generateTemplatePage } from '../post-build/page-generator.mjs'
+
+async function createProject() {
+  return mkdtemp(join(tmpdir(), 'nextspark-published-signatures-test-'))
+}
+
+async function writeProjectFile(root, relativePath, content) {
+  const absolutePath = join(root, relativePath)
+  await mkdir(dirname(absolutePath), { recursive: true })
+  await writeFile(absolutePath, content, 'utf8')
+}
+
+/** A theme template at `contents/themes/testtheme/templates/<relativePath>`, overriding `app/<relativePath>`. */
+async function writeTemplate(root, relativePath, templateType, content) {
+  await writeProjectFile(root, join('contents/themes/testtheme/templates', relativePath), content)
+  return {
+    name: relativePath.replace(/\.(tsx|ts)$/, ''),
+    themeName: 'testtheme',
+    templateType,
+    fileName: relativePath.split('/').pop(),
+    relativePath,
+    appPath: `app/${relativePath}`,
+    templatePath: `@/contents/themes/testtheme/templates/${relativePath}`,
+    priority: 10
+  }
+}
+
+const LAYOUT_WITHOUT_COMPONENT = "export const viewport = { themeColor: 'black' }\n"
+const PAGE_WITH_COMPONENT = 'export default function Page() { return null }\n'
+
+test('generateTemplateRegistry(templates, config) decides component vs metadata-only without being handed an analysis', async () => {
+  const root = await createProject()
+  try {
+    const layout = await writeTemplate(root, 'docs/layout.tsx', 'layout', LAYOUT_WITHOUT_COMPONENT)
+    const page = await writeTemplate(root, 'pricing/page.tsx', 'page', PAGE_WITH_COMPONENT)
+
+    const out = await generateTemplateRegistry([layout, page], { outputDir: join(root, '.nextspark/registries'), projectRoot: root })
+
+    assert.match(out, /'app\/docs\/layout\.tsx': \{\n\s*appPath: 'app\/docs\/layout\.tsx',\n\s*component: null,/)
+    assert.match(out, /component: lazyTemplate\('app\/pricing\/page\.tsx', \(\) => import\('@\/contents\/themes\/testtheme\/templates\/pricing\/page'\)\)/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('generateTemplateRegistryClient(templates, config) leaves out a template with no component without being handed an analysis', async () => {
+  const root = await createProject()
+  try {
+    const layout = await writeTemplate(root, 'docs/layout.tsx', 'layout', LAYOUT_WITHOUT_COMPONENT)
+    const page = await writeTemplate(root, 'pricing/page.tsx', 'page', PAGE_WITH_COMPONENT)
+
+    const out = await generateTemplateRegistryClient([layout, page], { outputDir: join(root, '.nextspark/registries'), projectRoot: root })
+
+    assert.doesNotMatch(out, /app\/docs\/layout\.tsx/)
+    assert.match(out, /'app\/pricing\/page\.tsx': dynamic\(\(\) => import\('@\/contents\/themes\/testtheme\/templates\/pricing\/page'\)\)/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('generateMissingPages(templates, config) writes the same routes the registry build does without being handed an analysis', async () => {
+  const root = await createProject()
+  try {
+    const layout = await writeTemplate(root, 'docs/layout.tsx', 'layout', LAYOUT_WITHOUT_COMPONENT)
+    const page = await writeTemplate(root, 'pricing/page.tsx', 'page', PAGE_WITH_COMPONENT)
+
+    await generateMissingPages([layout, page], { projectRoot: root })
+
+    const generatedLayout = await readFile(join(root, 'app/(templates)/docs/layout.tsx'), 'utf8')
+    assert.match(generatedLayout, /Pass-through component/)
+    assert.match(generatedLayout, /export \{ viewport \} from '@\/contents\/themes\/testtheme\/templates\/docs\/layout'/)
+
+    const generatedPage = await readFile(join(root, 'app/(templates)/pricing/page.tsx'), 'utf8')
+    assert.match(generatedPage, /import TemplateComponent from '@\/contents\/themes\/testtheme\/templates\/pricing\/page'/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('generateTemplatePage(template, outputPath) writes a route file without being handed an analysis', async () => {
+  const root = await createProject()
+  try {
+    // generateTemplatePage resolves templates against the project root the last
+    // generateMissingPages call was given.
+    await generateMissingPages([], { projectRoot: root })
+    const page = await writeTemplate(root, 'blog/page.tsx', 'page', `export const revalidate = 3600\n${PAGE_WITH_COMPONENT}`)
+    const outputPath = join(root, 'app/(templates)/blog/page.tsx')
+
+    await generateTemplatePage(page, outputPath)
+
+    const generated = await readFile(outputPath, 'utf8')
+    assert.match(generated, /import TemplateComponent from '@\/contents\/themes\/testtheme\/templates\/blog\/page'/)
+    assert.match(generated, /export const revalidate = 3600/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('generateTemplatePage(template, outputPath) still rejects segment config Next.js would not read', async () => {
+  const root = await createProject()
+  try {
+    await generateMissingPages([], { projectRoot: root })
+    const page = await writeTemplate(root, 'broken/page.tsx', 'page', `export const revalidate = 60 * 60\n${PAGE_WITH_COMPONENT}`)
+    const outputPath = join(root, 'app/(templates)/broken/page.tsx')
+
+    await assert.rejects(() => generateTemplatePage(page, outputPath), /segment config export "revalidate" is not a literal/)
+    assert.equal(existsSync(outputPath), false)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('generateMissingPages(templates, config) rejects a template it cannot generate before deleting anything', async () => {
+  const root = await createProject()
+  try {
+    await writeProjectFile(root, 'app/(templates)/old/page.tsx', PAGE_WITH_COMPONENT)
+    const page = await writeTemplate(root, 'docs/page.tsx', 'page', "export const metadata = { title: 'Docs' }\n")
+
+    await assert.rejects(() => generateMissingPages([page], { projectRoot: root }), /has no default export/)
+
+    assert.equal(existsSync(join(root, 'app/(templates)/old/page.tsx')), true)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('generateMissingPages rejects an analysis that is missing one of its templates before deleting anything', async () => {
+  const root = await createProject()
+  try {
+    await writeProjectFile(root, 'app/(templates)/old/page.tsx', PAGE_WITH_COMPONENT)
+    const page = await writeTemplate(root, 'pricing/page.tsx', 'page', PAGE_WITH_COMPONENT)
+
+    await assert.rejects(() => generateMissingPages([page], { projectRoot: root }, new Map()), /was not read by analyzeTemplates/)
+
+    assert.equal(existsSync(join(root, 'app/(templates)/old/page.tsx')), true)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+/** A standalone `page.meta.ts` - which never has a default export - overriding `app/<route>/page.tsx`. */
+async function writeMetaTemplate(root, route) {
+  const relativePath = `${route}/page.meta.ts`
+  await writeProjectFile(root, join('contents/themes/testtheme/templates', relativePath), "export const metadata = { title: 'Docs' }\n")
+  return {
+    name: `${route}/page`,
+    themeName: 'testtheme',
+    templateType: 'page',
+    fileName: 'page.meta.ts',
+    relativePath,
+    appPath: `app/${route}/page.tsx`,
+    templatePath: `@/contents/themes/testtheme/templates/${relativePath}`,
+    priority: 10
+  }
+}
+
+test('generateTemplatePage(template, outputPath) rejects a page.meta.ts for a route the app has no page at, without writing it', async () => {
+  const root = await createProject()
+  try {
+    await generateMissingPages([], { projectRoot: root })
+    const meta = await writeMetaTemplate(root, 'docs')
+    const outputPath = join(root, 'app/(templates)/docs/page.tsx')
+
+    await assert.rejects(
+      () => generateTemplatePage(meta, outputPath),
+      /page\.meta\.ts has no default export, and the app has no existing route at "app\/docs\/page\.tsx"/
+    )
+    assert.equal(existsSync(outputPath), false)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('generateTemplatePage(template, outputPath) rejects a page.tsx with no default export for a route the app has no page at, without writing it', async () => {
+  const root = await createProject()
+  try {
+    await generateMissingPages([], { projectRoot: root })
+    const page = await writeTemplate(root, 'docs/page.tsx', 'page', "export const metadata = { title: 'Docs' }\n")
+    const outputPath = join(root, 'app/(templates)/docs/page.tsx')
+
+    await assert.rejects(
+      () => generateTemplatePage(page, outputPath),
+      /docs\/page\.tsx has no default export, and the app has no existing route at "app\/docs\/page\.tsx"/
+    )
+    assert.equal(existsSync(outputPath), false)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('generateMissingPages(templates, config) rejects a page.meta.ts for a route the app has no page at, without writing anything', async () => {
+  const root = await createProject()
+  try {
+    const meta = await writeMetaTemplate(root, 'docs')
+
+    await assert.rejects(() => generateMissingPages([meta], { projectRoot: root }), /page\.meta\.ts has no default export/)
+
+    assert.equal(existsSync(join(root, 'app/(templates)')), false)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('a page.meta.ts over a page the app already has is accepted, and no route file is written for it', async () => {
+  const root = await createProject()
+  try {
+    await writeProjectFile(root, 'app/docs/page.tsx', PAGE_WITH_COMPONENT)
+    const meta = await writeMetaTemplate(root, 'docs')
+
+    await generateMissingPages([meta], { projectRoot: root })
+    assert.equal(existsSync(join(root, 'app/(templates)/docs/page.tsx')), false)
+
+    const out = await generateTemplateRegistry([meta], { outputDir: join(root, '.nextspark/registries'), projectRoot: root })
+    assert.match(out, /'app\/docs\/page\.tsx': \{\n\s*appPath: 'app\/docs\/page\.tsx',\n\s*component: null,/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})