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

package/scripts/build/registry/__tests__/route-file-rule.test.mjs

@@ -0,0 +1,170 @@
+/**
+ * One rule decides what becomes of a theme template's route file, for every
+ * generator core exposes that writes route files or registers template
+ * components (`routeFileAction` in page-generator.mjs):
+ * - a template the page generator writes a route file for gets one;
+ * - a template over a route the app already has gets none, and the generator
+ *   goes on without failing;
+ * - a page whose route file would import a default export it doesn't have is
+ *   rejected, and nothing is written.
+ *
+ * Each generator runs over the same cases, with an analysis and without one.
+ *
+ * Run: node --test packages/core/scripts/build/registry/__tests__/route-file-rule.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 { analyzeTemplates, generateMissingPages, generateTemplatePage } from '../post-build/page-generator.mjs'
+
+const PAGE = 'export default function Page() { return null }\n'
+const METADATA_ONLY = "export const metadata = { title: 'Docs' }\n"
+const ROUTE_FILE = 'app/(templates)/docs/page.tsx'
+
+/**
+ * - `route`: what the page generator does with the template's route file
+ * - `component`: how the registries register the template
+ */
+const CASES = [
+  { name: 'a page.tsx with a default export, no app page', file: 'page.tsx', content: PAGE, appPage: false, route: 'write', component: 'deferred' },
+  { name: 'a page.tsx with a default export, over an app page', file: 'page.tsx', content: PAGE, appPage: true, route: 'skip', component: 'deferred' },
+  { name: 'a page.tsx with no default export, no app page', file: 'page.tsx', content: METADATA_ONLY, appPage: false, route: 'reject' },
+  { name: 'a page.tsx with no default export, over an app page', file: 'page.tsx', content: METADATA_ONLY, appPage: true, route: 'skip', component: 'none' },
+  { name: 'a page.meta.ts, no app page', file: 'page.meta.ts', content: METADATA_ONLY, appPage: false, route: 'reject' },
+  { name: 'a page.meta.ts, over an app page', file: 'page.meta.ts', content: METADATA_ONLY, appPage: true, route: 'skip', component: 'none' },
+]
+
+async function writeProjectFile(root, relativePath, content) {
+  const absolutePath = join(root, relativePath)
+  await mkdir(dirname(absolutePath), { recursive: true })
+  await writeFile(absolutePath, content, 'utf8')
+}
+
+/** A project with the case's theme template for app/docs/page.tsx, and that app page when the case has one. */
+async function projectFor(testCase) {
+  const root = await mkdtemp(join(tmpdir(), 'nextspark-route-file-rule-test-'))
+  const relativePath = `docs/${testCase.file}`
+  await writeProjectFile(root, join('contents/themes/testtheme/templates', relativePath), testCase.content)
+  if (testCase.appPage) {
+    await writeProjectFile(root, 'app/docs/page.tsx', PAGE)
+  }
+
+  const template = {
+    name: 'docs/page',
+    themeName: 'testtheme',
+    templateType: 'page',
+    fileName: testCase.file,
+    relativePath,
+    appPath: 'app/docs/page.tsx',
+    templatePath: `@/contents/themes/testtheme/templates/${relativePath}`,
+    priority: 10
+  }
+  const config = { outputDir: join(root, '.nextspark/registries'), projectRoot: root }
+
+  return { root, template, config, cleanup: () => rm(root, { recursive: true, force: true }) }
+}
+
+/**
+ * The analysis a caller hands a generator. For a template analyzeTemplates
+ * accepts, that is its analysis. analyzeTemplates rejects the others itself, so
+ * for those this is the entry it would record - which leaves the generator's
+ * own use of the rule as the thing under test.
+ */
+async function analysisFor(testCase, template, config) {
+  if (testCase.route !== 'reject') {
+    return analyzeTemplates([template], config)
+  }
+  return new Map([
+    [template.templatePath, { segmentConfig: {}, moduleExports: ['metadata'], hasDefaultExport: false, generatesRoute: true }]
+  ])
+}
+
+/** Run `check` for every case, with and without an analysis, in a fresh project each time. */
+async function forEachCase(check) {
+  for (const testCase of CASES) {
+    for (const withAnalysis of [false, true]) {
+      const label = `${testCase.name}, ${withAnalysis ? 'with' : 'without'} an analysis`
+      const project = await projectFor(testCase)
+      try {
+        const analysis = withAnalysis ? await analysisFor(testCase, project.template, project.config) : undefined
+        await check({ testCase, label, analysis, ...project })
+      } finally {
+        await project.cleanup()
+      }
+    }
+  }
+}
+
+test('generateTemplatePage writes a route file only where one is generated, and rejects one that would break', async () => {
+  await forEachCase(async ({ testCase, label, analysis, root, template }) => {
+    // generateTemplatePage resolves templates against the last project root generateMissingPages was given
+    await generateMissingPages([], { projectRoot: root })
+    const outputPath = join(root, ROUTE_FILE)
+
+    if (testCase.route === 'reject') {
+      await assert.rejects(() => generateTemplatePage(template, outputPath, analysis), /has no default export/, label)
+      assert.equal(existsSync(outputPath), false, label)
+      return
+    }
+
+    const result = await generateTemplatePage(template, outputPath, analysis)
+    assert.equal(result?.written, testCase.route === 'write', label)
+    assert.equal(existsSync(outputPath), testCase.route === 'write', label)
+    if (testCase.route === 'write') {
+      assert.match(await readFile(outputPath, 'utf8'), /import TemplateComponent from/, label)
+    }
+  })
+})
+
+test('generateMissingPages writes a route file only where one is generated, and rejects one that would break before writing anything', async () => {
+  await forEachCase(async ({ testCase, label, analysis, root, template, config }) => {
+    if (testCase.route === 'reject') {
+      await assert.rejects(() => generateMissingPages([template], config, analysis), /has no default export/, label)
+      assert.equal(existsSync(join(root, 'app/(templates)')), false, label)
+      return
+    }
+
+    await generateMissingPages([template], config, analysis)
+    assert.equal(existsSync(join(root, ROUTE_FILE)), testCase.route === 'write', label)
+  })
+})
+
+test('generateTemplateRegistry registers a component only for a template that has one, and rejects a route that would break', async () => {
+  await forEachCase(async ({ testCase, label, analysis, template, config }) => {
+    if (testCase.route === 'reject') {
+      await assert.rejects(() => generateTemplateRegistry([template], config, analysis), /has no default export/, label)
+      return
+    }
+
+    const out = await generateTemplateRegistry([template], config, analysis)
+    const component = testCase.component === 'deferred'
+      ? /component: lazyTemplate\('app\/docs\/page\.tsx'/
+      : /'app\/docs\/page\.tsx': \{\n\s*appPath: 'app\/docs\/page\.tsx',\n\s*component: null,/
+    assert.match(out, component, label)
+  })
+})
+
+test('generateTemplateRegistryClient registers a component only for a template that has one, and rejects a route that would break', async () => {
+  await forEachCase(async ({ testCase, label, analysis, template, config }) => {
+    if (testCase.route === 'reject') {
+      await assert.rejects(() => generateTemplateRegistryClient([template], config, analysis), /has no default export/, label)
+      return
+    }
+
+    const out = await generateTemplateRegistryClient([template], config, analysis)
+    if (testCase.component === 'deferred') {
+      assert.match(out, /'app\/docs\/page\.tsx': dynamic\(/, label)
+    } else {
+      assert.doesNotMatch(out, /'app\/docs\/page\.tsx'/, label)
+    }
+  })
+})

package/scripts/build/registry/__tests__/safe-fs.test.mjs

@@ -0,0 +1,333 @@
+/**
+ * Tests for safe-fs, the one way the generator changes the file system: each of
+ * its calls refuses a path out of its root, through a symlink or into a file
+ * with other hard links, and changes nothing anywhere when it does; the build's
+ * steps that write refuse through it even when the check the build runs first
+ * is not asked; and no file of the generator changes the file system any other
+ * way.
+ *
+ * Run: node --test packages/core/scripts/build/registry/__tests__/safe-fs.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createHash, randomBytes } from 'node:crypto'
+import { execFileSync, spawn } from 'node:child_process'
+import { once } from 'node:events'
+import { chmod, link, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { COPY_BLOCK_SIZE, isUnsafeWrite, projectFiles, UNSAFE_WRITE, unsafeWriteProblem } from '../../safe-fs.mjs'
+import { cleanupDeletedTemplate, cleanupOldRouteFiles, cleanupOrphanedTemplates } from '../post-build/route-cleanup.mjs'
+import { generateTestBlocksJson, generateTestEntitiesJson } from '../post-build/test-fixtures.mjs'
+import { generateMissingPages } from '../post-build/page-generator.mjs'
+import { syncAppGlobalsCss } from '../../theme.mjs'
+import { directFsWrites, directFsWritesIn, generatorFiles } from './direct-fs-writes.mjs'
+
+const CORE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..')
+const RUNS_AS_ROOT = process.getuid?.() === 0
+
+async function directory() {
+  const root = await mkdtemp(join(tmpdir(), 'nextspark-safe-fs-test-'))
+  return { root, cleanup: () => rm(root, { recursive: true, force: true }) }
+}
+
+async function writeIn(root, path, content = '') {
+  await mkdir(dirname(join(root, path)), { recursive: true })
+  await writeFile(join(root, path), content)
+}
+
+/** Every entry under `root`: a symlink's target, 'dir', or a file's sha256. */
+async function snapshot(root) {
+  const entries = {}
+  const walk = async relative => {
+    for (const entry of await readdir(join(root, relative), { withFileTypes: true })) {
+      const path = relative ? `${relative}/${entry.name}` : entry.name
+      const stats = await lstat(join(root, path))
+      if (stats.isSymbolicLink()) entries[path] = `-> ${await readlink(join(root, path))}`
+      else if (stats.isDirectory()) {
+        entries[path] = 'dir'
+        await walk(path)
+      } else entries[path] = createHash('sha256').update(await readFile(join(root, path))).digest('hex')
+    }
+  }
+  await walk('')
+  return entries
+}
+
+/** What `call` throws, or null. */
+async function thrown(call) {
+  try {
+    await call()
+    return null
+  } catch (error) {
+    return error
+  }
+}
+
+test('each call refuses a path through a symlink, out of the root or into a hard-linked file, and changes nothing inside or outside', async () => {
+  const project = await directory()
+  const outside = await directory()
+  try {
+    await writeIn(outside.root, 'target/file.txt', 'outside\n')
+    await writeIn(outside.root, 'target/v1/plugin/legacy/route.ts', '// Auto-generated Plugin Route Proxy\n')
+    await writeIn(outside.root, 'lone.txt', 'outside\n')
+    await writeIn(project.root, 'app/page.tsx', 'inside\n')
+    await symlink(join(outside.root, 'target'), join(project.root, 'app/linked'))
+    await symlink(join(outside.root, 'lone.txt'), join(project.root, 'app/lone.txt'))
+    await link(join(outside.root, 'lone.txt'), join(project.root, 'hard.txt'))
+    await writeIn(project.root, 'source.txt', 'source\n')
+
+    const files = projectFiles(project.root)
+    const cases = [
+      ['writeFileSync through a symlinked directory', () => files.writeFileSync(join(project.root, 'app/linked/file.txt'), 'x'), 'app/linked', 'is a symlink'],
+      ['writeFile onto a symlink', () => files.writeFile(join(project.root, 'app/lone.txt'), 'x'), 'app/lone.txt', 'is a symlink'],
+      ['writeFile into a hard-linked file', () => files.writeFile(join(project.root, 'hard.txt'), 'x'), 'hard.txt', 'has other hard links'],
+      ['writeFile with wx through a symlink', () => files.writeFile(join(project.root, 'app/linked/new.txt'), 'x', { flag: 'wx' }), 'app/linked', 'is a symlink'],
+      ['writeFile out of the root with ..', () => files.writeFile('app/linked/../../../escape.txt', 'x'), null, null],
+      ['writeFile to the root itself', () => files.writeFile(project.root, 'x'), '.', 'is the root itself, which is not changed'],
+      ['writeFile to an absolute path outside', () => files.writeFile(join(outside.root, 'lone.txt'), 'x'), null, null],
+      ['mkdirSync through a symlink', () => files.mkdirSync(join(project.root, 'app/linked/made'), { recursive: true }), 'app/linked', 'is a symlink'],
+      ['mkdtemp beside a path through a symlink', () => files.mkdtemp(join(project.root, 'app/linked/backup-')), 'app/linked', 'is a symlink'],
+      ['copyFile to a path through a symlink', () => files.copyFile(join(project.root, 'source.txt'), join(project.root, 'app/linked/copy.txt')), 'app/linked', 'is a symlink'],
+      ['rm of a tree through a symlink', () => files.rm(join(project.root, 'app/linked/v1/plugin/legacy'), { recursive: true, force: true }), 'app/linked', 'is a symlink'],
+      ['rm of the symlink itself', () => files.rm(join(project.root, 'app/linked'), { recursive: true, force: true }), 'app/linked', 'is a symlink'],
+      ['rmdir through a symlink', () => files.rmdir(join(project.root, 'app/linked/v1')), 'app/linked', 'is a symlink'],
+      ['unlink through a symlink', () => files.unlink(join(project.root, 'app/linked/file.txt')), 'app/linked', 'is a symlink'],
+      ['rename out through a symlink', () => files.rename(join(project.root, 'app/page.tsx'), join(project.root, 'app/linked/page.tsx')), 'app/linked', 'is a symlink'],
+      ['rename in from a symlink', () => files.rename(join(project.root, 'app/linked/file.txt'), join(project.root, 'app/file.txt')), 'app/linked', 'is a symlink'],
+      ['a path from the root through a symlink', () => files.writeFile('app/linked/file.txt', 'x'), 'app/linked', 'is a symlink'],
+    ]
+
+    const before = { project: await snapshot(project.root), outside: await snapshot(outside.root) }
+    const wrong = []
+    for (const [label, call, path, problem] of cases) {
+      const error = await thrown(call)
+      if (!isUnsafeWrite(error)) {
+        wrong.push(`${label}: ${error ? `threw ${error.code} ${error.message}` : 'did not refuse'}`)
+        continue
+      }
+      if (error.code !== UNSAFE_WRITE) wrong.push(`${label}: code ${error.code}`)
+      if (path !== null && (error.path !== path || error.problem !== problem)) wrong.push(`${label}: named ${error.path} ${error.problem}`)
+      if (path === null && !error.problem.startsWith('is outside')) wrong.push(`${label}: named ${error.path} ${error.problem}`)
+      if (!error.message.includes('nothing was written')) wrong.push(`${label}: the message doesn't say nothing was written`)
+    }
+    assert.deepEqual(wrong, [])
+    assert.deepEqual(await snapshot(outside.root), before.outside, 'nothing outside changed')
+    assert.deepEqual(await snapshot(project.root), before.project, 'nothing inside changed')
+  } finally {
+    await outside.cleanup()
+    await project.cleanup()
+  }
+})
+
+test('each call does its work inside the root, reached through a symlink above it or not', async () => {
+  const holder = await directory()
+  try {
+    const real = join(holder.root, 'real')
+    await mkdir(real)
+    await symlink(real, join(holder.root, 'alias'))
+
+    for (const root of [real, join(holder.root, 'alias')]) {
+      const files = projectFiles(root)
+      await files.mkdir(join(root, 'a/b'), { recursive: true })
+      await files.writeFile(join(root, 'a/b/c.txt'), 'one', 'utf8')
+      files.writeFileSync(join(root, 'a/b/c.txt'), 'two')
+      await assert.rejects(files.writeFile(join(root, 'a/b/c.txt'), 'three', { flag: 'wx' }), { code: 'EEXIST' })
+      await files.copyFile(join(root, 'a/b/c.txt'), join(root, 'a/copy.txt'))
+      const temp = await files.mkdtemp(join(root, 'a/backup-'))
+      await files.rename(join(root, 'a/copy.txt'), join(temp, 'moved.txt'))
+      assert.equal(await readFile(join(temp, 'moved.txt'), 'utf8'), 'two')
+      await files.unlink(join(temp, 'moved.txt'))
+      await files.rmdir(temp)
+      await files.rm(join(root, 'a'), { recursive: true, force: true })
+      assert.equal(existsSync(join(root, 'a')), false)
+    }
+
+    // A path spelled with another path to the root than the one it was given as
+    const files = projectFiles(join(holder.root, 'alias'))
+    await files.writeFile(join(real, 'spelled-real.txt'), 'x')
+    assert.equal(await readFile(join(real, 'spelled-real.txt'), 'utf8'), 'x')
+    await files.writeFile(join(await realpath(real), 'spelled-resolved.txt'), 'x')
+    assert.equal(await readFile(join(real, 'spelled-resolved.txt'), 'utf8'), 'x')
+    await symlink(real, join(real, 'self'))
+    assert.deepEqual(
+      unsafeWriteProblem(join(holder.root, 'alias'), join(real, 'self/file.txt')),
+      { target: 'self/file.txt', path: 'self', problem: 'is a symlink' },
+      'a symlink back to the root inside it is still a symlink'
+    )
+    assert.equal(unsafeWriteProblem(join(holder.root, 'alias'), join(holder.root, 'elsewhere.txt'))?.problem.startsWith('is outside'), true)
+  } finally {
+    await holder.cleanup()
+  }
+})
+
+test('copyFile opens its destination without following a symlink put there after safe-fs checked it', async () => {
+  const project = await directory()
+  const outside = await directory()
+  try {
+    const secret = join(outside.root, 'secret.txt')
+    await writeFile(secret, 'secret\n')
+    await writeIn(project.root, 'source.txt', 'copied content\n')
+    const dest = join(project.root, 'theme.mjs')
+    await writeFile(dest, 'placeholder\n')
+    const fifo = join(project.root, 'source.fifo')
+    execFileSync('mkfifo', [fifo])
+
+    // The child blocks opening the FIFO as its copy source - inside copyFileSync's own work,
+    // after safe-fs's check on `dest` already passed while it was still an ordinary file.
+    const child = spawn(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), 'copy-race-child.mjs'), project.root, fifo, dest], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    let out = ''
+    child.stdout.on('data', chunk => { out += chunk })
+    await new Promise(resolve => setTimeout(resolve, 400))
+
+    await rm(dest, { force: true })
+    await symlink(secret, dest)
+
+    // Unblock the child's read with an empty write, so its copy proceeds against the now-swapped destination.
+    const writer = await open(fifo, 'w')
+    await writer.close()
+    const [exitCode] = await once(child, 'exit')
+
+    assert.equal(exitCode, 0, 'the child process itself must not crash')
+    assert.deepEqual(JSON.parse(out), { code: 'ELOOP' }, 'the destination open must refuse the symlink instead of following it')
+    assert.equal(await readFile(secret, 'utf8'), 'secret\n', 'the outside file the symlink points to must survive untouched')
+  } finally {
+    await outside.cleanup()
+    await project.cleanup()
+  }
+})
+
+test('copyFile copies a source of several blocks, including a partial last one, byte for byte and with the source mode', async () => {
+  const project = await directory()
+  try {
+    const content = randomBytes(COPY_BLOCK_SIZE * 2 + 12345)
+    const source = join(project.root, 'source.bin')
+    await writeFile(source, content)
+    await chmod(source, 0o640)
+    const dest = join(project.root, 'dest.bin')
+    await projectFiles(project.root).copyFile(source, dest)
+    assert.equal((await readFile(dest)).equals(content), true, 'the destination holds the exact bytes of the source')
+    assert.equal((await lstat(dest)).mode & 0o777, 0o640, 'the destination keeps the source mode')
+  } finally {
+    await project.cleanup()
+  }
+})
+
+test('copyFile leaves no descriptor open when its destination open fails partway through the copy', { skip: RUNS_AS_ROOT }, async () => {
+  const project = await directory()
+  try {
+    await writeIn(project.root, 'source.txt', 'x'.repeat(64))
+    const readonly = join(project.root, 'readonly')
+    await mkdir(readonly)
+    await chmod(readonly, 0o500)
+    try {
+      const files = projectFiles(project.root)
+      const before = await readdir('/dev/fd')
+      const error = await thrown(() => files.copyFile(join(project.root, 'source.txt'), join(readonly, 'dest.txt')))
+      assert.equal(error?.code, 'EACCES')
+      const after = await readdir('/dev/fd')
+      assert.deepEqual(after.filter(fd => !before.includes(fd)), [], 'no descriptor from the failed copy is left open')
+    } finally {
+      await chmod(readonly, 0o700)
+    }
+  } finally {
+    await project.cleanup()
+  }
+})
+
+test("the build's steps that write refuse through safe-fs even when the check before the build is not asked", async () => {
+  const project = await directory()
+  const outside = await directory()
+  try {
+    const root = project.root
+    const config = { projectRoot: root, monorepoRoot: null, isMonorepoMode: false, activeTheme: 'acme', themesDir: join(root, 'contents/themes'), pluginsDir: join(root, 'contents/plugins') }
+
+    // app/api linked outside, holding an old generated plugin route and a file of its own
+    await writeIn(outside.root, 'api/v1/plugin/legacy/route.ts', '// Auto-generated Plugin Route Proxy\n')
+    await writeIn(outside.root, 'api/v1/plugin/legacy/other.ts', 'export const other = 1\n')
+    await mkdir(join(root, 'app'), { recursive: true })
+    await symlink(join(outside.root, 'api'), join(root, 'app/api'))
+
+    // The theme's fixtures linked outside
+    await writeIn(outside.root, 'fixtures/entities.json', '{"outside":true}\n')
+    await writeIn(outside.root, 'fixtures/blocks.json', '{"outside":true}\n')
+    await mkdir(join(root, 'contents/themes/acme/tests/cypress'), { recursive: true })
+    await symlink(join(outside.root, 'fixtures'), join(root, 'contents/themes/acme/tests/cypress/fixtures'))
+
+    // app/(templates) linked outside, and app/globals.css linked to a file outside
+    await writeIn(outside.root, 'templates/(public)/orphan/page.tsx', 'export default function Orphan() { return null }\n')
+    await symlink(join(outside.root, 'templates'), join(root, 'app/(templates)'))
+    await writeIn(outside.root, 'globals.css', '@import "../elsewhere.css";\n')
+    await symlink(join(outside.root, 'globals.css'), join(root, 'app/globals.css'))
+
+    const before = await snapshot(outside.root)
+    const steps = [
+      ['cleanupOldRouteFiles', () => cleanupOldRouteFiles(config), 'app/api'],
+      ['generateTestEntitiesJson', () => generateTestEntitiesJson([], [{ name: 'acme' }], config), 'contents/themes/acme/tests/cypress/fixtures'],
+      ['generateTestBlocksJson', () => generateTestBlocksJson([], config), 'contents/themes/acme/tests/cypress/fixtures'],
+      ['cleanupOrphanedTemplates', () => cleanupOrphanedTemplates([], config), 'app/(templates)'],
+      ['cleanupDeletedTemplate', () => cleanupDeletedTemplate(join(root, 'contents/themes/acme/templates/(public)/orphan/page.tsx'), config), 'app/(templates)'],
+      ['generateMissingPages', () => generateMissingPages([], config, new Map()), 'app/(templates)'],
+      ['syncAppGlobalsCss', () => syncAppGlobalsCss(config, 'acme'), 'app/globals.css'],
+    ]
+    const wrong = []
+    for (const [label, step, path] of steps) {
+      const error = await thrown(step)
+      if (!isUnsafeWrite(error)) wrong.push(`${label}: ${error ? `threw ${error.message}` : 'did not refuse'}`)
+      else if (error.path !== path) wrong.push(`${label}: named ${error.path}`)
+    }
+    assert.deepEqual(wrong, [])
+    assert.deepEqual(await snapshot(outside.root), before, 'nothing outside changed')
+  } finally {
+    await outside.cleanup()
+    await project.cleanup()
+  }
+})
+
+test('the scan finds each way a file can change the file system without safe-fs, and lets reads through', () => {
+  const found = source => directFsWrites(source, 'example.mjs').map(({ what }) => what)
+  assert.deepEqual(found("import { existsSync, readFileSync, lstatSync, constants } from 'fs'\nimport { readdir } from 'node:fs/promises'\n"), [])
+  assert.deepEqual(found("import { writeFileSync } from 'fs'"), ['imports writeFileSync from fs'])
+  assert.deepEqual(found("import { rm as remove } from 'node:fs/promises'"), ['imports rm from node:fs/promises'])
+  assert.deepEqual(found("import { promises } from 'fs'"), ['imports promises from fs'])
+  assert.deepEqual(found("import { cpSync, symlinkSync, openSync } from 'fs'"), ['imports cpSync from fs', 'imports symlinkSync from fs', 'imports openSync from fs'])
+  assert.deepEqual(found("import fs from 'fs'"), ['imports fs whole, as fs'])
+  assert.deepEqual(found("import * as fsp from 'fs/promises'"), ['imports fs/promises whole, as fsp'])
+  assert.deepEqual(found("import fse from 'fs-extra'"), ['imports fs-extra whole, as fse'])
+  assert.deepEqual(found("export { writeFile } from 'fs/promises'"), ['re-exports fs/promises'])
+  assert.deepEqual(found("const { unlink } = await import('fs/promises')"), ['loads fs/promises with a call'])
+  assert.deepEqual(found("const fs = require('node:fs')"), ['loads node:fs with a call'])
+  assert.deepEqual(found("const fs = createRequire(import.meta.url)('fs')"), ['loads fs with a call'])
+  assert.deepEqual(directFsWrites("import fs = require('fs')", 'example.ts').map(({ what }) => what), ['imports fs whole, as fs'])
+  assert.deepEqual(directFsWrites("import type { Stats, WriteStream } from 'node:fs'", 'example.ts'), [])
+})
+
+test('no file of the registry build, the rest of scripts/build or the postinstall changes the file system except through safe-fs', () => {
+  const files = generatorFiles({
+    directories: [join(CORE_DIR, 'scripts/build')],
+    entries: [join(CORE_DIR, 'scripts/postinstall.mjs')],
+    within: join(CORE_DIR, 'scripts'),
+  })
+  const names = files.map(file => file.slice(CORE_DIR.length + 1))
+  for (const expected of [
+    'scripts/build/registry.mjs',
+    'scripts/build/theme.mjs',
+    'scripts/build/templates-plan.mjs',
+    'scripts/build/registry/post-build/page-generator.mjs',
+    'scripts/build/registry/post-build/route-cleanup.mjs',
+    'scripts/build/registry/post-build/test-fixtures.mjs',
+    'scripts/build/registry/post-build/own-gitignores.mjs',
+    'scripts/utils/logging.mjs',
+    'scripts/postinstall.mjs',
+  ]) {
+    assert.ok(names.includes(expected), `${expected} is scanned`)
+  }
+  assert.equal(names.some(name => name.includes('__tests__') || name.endsWith('.test.mjs')), false, 'tests are not the generator')
+  assert.deepEqual(directFsWritesIn(files, { base: CORE_DIR, allowed: [join(CORE_DIR, 'scripts/build/safe-fs.mjs')] }), [])
+})

package/scripts/build/registry/__tests__/template-analysis.test.mjs

@@ -0,0 +1,142 @@
+/**
+ * Tests that both template registries and the page generator take what they
+ * know about a theme template from the analysis the registry build parses it
+ * into once (`analyzeTemplates`), instead of parsing the template again.
+ *
+ * Each test hands a consumer an analysis that no longer matches the template
+ * on disk: the state a watch-mode rebuild reaches when a template is saved
+ * between two phases of the same build. A consumer that parses the file itself
+ * sees a different template than the others, and its output gives it away.
+ *
+ * Run: node --test packages/core/scripts/build/registry/__tests__/template-analysis.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 } from '../post-build/page-generator.mjs'
+
+async function createProject() {
+  return mkdtemp(join(tmpdir(), 'nextspark-template-analysis-test-'))
+}
+
+async function writeThemeTemplate(root, relativePath, content) {
+  const absolutePath = join(root, 'contents/themes/testtheme/templates', relativePath)
+  await mkdir(dirname(absolutePath), { recursive: true })
+  await writeFile(absolutePath, content, 'utf8')
+  return `@/contents/themes/testtheme/templates/${relativePath}`
+}
+
+/**
+ * A layout that had a default export when the build read it and has lost it
+ * on disk since.
+ */
+async function layoutThatLostItsDefaultExport(root) {
+  const templatePath = await writeThemeTemplate(root, 'docs/layout.tsx', "export const viewport = { themeColor: 'black' }\n")
+  const template = {
+    name: 'docs/layout',
+    themeName: 'testtheme',
+    templateType: 'layout',
+    fileName: 'layout.tsx',
+    relativePath: 'docs/layout.tsx',
+    appPath: 'app/docs/layout.tsx',
+    templatePath,
+    priority: 10
+  }
+  const analysis = new Map([
+    [templatePath, { hasDefaultExport: true, generatesRoute: true, segmentConfig: {}, moduleExports: ['viewport'] }]
+  ])
+  return { template, analysis, config: { outputDir: join(root, '.nextspark/registries'), projectRoot: root } }
+}
+
+test('the server registry takes the default export from the analysis, not from the template file', async () => {
+  const root = await createProject()
+  try {
+    const { template, analysis, config } = await layoutThatLostItsDefaultExport(root)
+
+    const out = await generateTemplateRegistry([template], config, analysis)
+
+    assert.match(
+      out,
+      /component: lazyTemplate\('app\/docs\/layout\.tsx', \(\) => import\('@\/contents\/themes\/testtheme\/templates\/docs\/layout'\)\)/
+    )
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('the client registry takes the default export from the analysis, not from the template file', async () => {
+  const root = await createProject()
+  try {
+    const { template, analysis, config } = await layoutThatLostItsDefaultExport(root)
+
+    const out = await generateTemplateRegistryClient([template], config, analysis)
+
+    assert.match(out, /'app\/docs\/layout\.tsx': dynamic\(\(\) => import\('@\/contents\/themes\/testtheme\/templates\/docs\/layout'\)\)/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('the page generator takes the default export and route-level exports from the analysis, not from the template file', async () => {
+  const root = await createProject()
+  try {
+    const { template, analysis, config } = await layoutThatLostItsDefaultExport(root)
+
+    await generateMissingPages([template], config, analysis)
+
+    const generated = await readFile(join(root, 'app/(templates)/docs/layout.tsx'), 'utf8')
+    assert.match(generated, /import TemplateComponent from '@\/contents\/themes\/testtheme\/templates\/docs\/layout'/)
+    assert.match(generated, /export \{ viewport \} from/)
+    assert.doesNotMatch(generated, /Pass-through component/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('the page generator takes whether to write a route file from the analysis, not from the app on disk', async () => {
+  const root = await createProject()
+  try {
+    // The analysis was taken while app/pricing/page.tsx existed; it is gone now.
+    const templatePath = await writeThemeTemplate(root, 'pricing/page.tsx', 'export default function Page() { return null }\n')
+    const template = {
+      name: 'pricing/page',
+      themeName: 'testtheme',
+      templateType: 'page',
+      fileName: 'page.tsx',
+      relativePath: 'pricing/page.tsx',
+      appPath: 'app/pricing/page.tsx',
+      templatePath,
+      priority: 10
+    }
+    const analysis = new Map([
+      [templatePath, { hasDefaultExport: true, generatesRoute: false, segmentConfig: {}, moduleExports: [] }]
+    ])
+
+    await generateMissingPages([template], { projectRoot: root }, analysis)
+
+    assert.equal(existsSync(join(root, 'app/(templates)/pricing/page.tsx')), false)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('a registry given no analysis for a template fails instead of reading the template itself', async () => {
+  const root = await createProject()
+  try {
+    const { template, config } = await layoutThatLostItsDefaultExport(root)
+
+    await assert.rejects(() => generateTemplateRegistry([template], config, new Map()), /was not read by analyzeTemplates/)
+    await assert.rejects(() => generateTemplateRegistryClient([template], config, new Map()), /was not read by analyzeTemplates/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})