@wular/pnext 0.0.1 → 0.0.3

package/src/cli/migrate/report.ts

@@ -0,0 +1,80 @@
+// Shared result types and rendering for the migrate command. Edits are what
+// migrate changes on disk; report items are things the user must look at by
+// hand. The body of the output is identical under --dry-run — only the header
+// says whether anything was written.
+
+import { bold, cyan, dim, green } from '../../utils/ansi';
+
+/** Amber for warnings — ansi.ts has no yellow, so hand-roll the same shape. */
+const amber = (value: string) =>
+  process.stdout.isTTY ? `\x1b[38;5;214m${value}\x1b[39m` : value;
+
+export interface Edit {
+  file: string;
+  /** Short phrase joined into the file's summary line. */
+  description: string;
+  /** Dim lines printed under the summary. */
+  details?: string[];
+}
+
+export interface ReportItem {
+  title: string;
+  detail: string;
+  files?: string[];
+}
+
+export interface MigrationResult {
+  edits: Edit[];
+  reports: ReportItem[];
+}
+
+export function emptyResult(): MigrationResult {
+  return { edits: [], reports: [] };
+}
+
+export function printHeader(root: string, dryRun: boolean) {
+  const suffix = dryRun ? 'dry run, nothing will be written' : root;
+  console.log(`\n${cyan('▲')} ${bold('pnext migrate')} ${dim(`— ${suffix}`)}`);
+}
+
+export function printResult(result: MigrationResult, options: { install: string }) {
+  const lines: string[] = [];
+
+  lines.push(`\n${bold('Changes')}`);
+  if (result.edits.length === 0) {
+    lines.push(`  ${dim('nothing to change')}`);
+  }
+  for (const [file, edits] of groupByFile(result.edits)) {
+    lines.push(
+      `${green('✓')} ${bold(file)} ${dim(`— ${edits.map(edit => edit.description).join(', ')}`)}`,
+    );
+    for (const edit of edits) {
+      for (const detail of edit.details ?? []) lines.push(`    ${dim(detail)}`);
+    }
+  }
+
+  lines.push(`\n${bold('Review')}${result.reports.length > 0 ? ` (${result.reports.length})` : ''}`);
+  if (result.reports.length === 0) {
+    lines.push(`  ${dim('nothing flagged')}`);
+  }
+  for (const item of result.reports) {
+    lines.push(`${amber('!')} ${bold(item.title)}`);
+    lines.push(`    ${dim(item.detail)}`);
+    for (const file of item.files ?? []) lines.push(`    ${dim(`· ${file}`)}`);
+  }
+
+  lines.push(`\n${bold('Next steps')}`);
+  lines.push(`  Run ${cyan(options.install)} to install the new dependencies.`);
+  lines.push(`  ${cyan('pnext dev')} to start the app.`);
+  console.log(lines.join('\n'));
+}
+
+function groupByFile(edits: Edit[]) {
+  const grouped = new Map<string, Edit[]>();
+  for (const edit of edits) {
+    const bucket = grouped.get(edit.file);
+    if (bucket) bucket.push(edit);
+    else grouped.set(edit.file, [edit]);
+  }
+  return grouped;
+}

package/src/cli/migrate/scan.ts

@@ -0,0 +1,135 @@
+// Report-only source scan. Import specifiers come from Bun's transpiler, never
+// from regexes over application code; text checks here only classify what to
+// report and never drive a rewrite.
+
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { MigrationResult } from './report';
+
+const SKIP_DIRS = new Set(['node_modules', '.next', '.pnext', '.git', 'dist', 'build']);
+const LOADERS: Record<string, 'ts' | 'tsx' | 'js' | 'jsx'> = {
+  '.ts': 'ts',
+  '.tsx': 'tsx',
+  '.jsx': 'jsx',
+  '.js': 'js',
+  '.mjs': 'js',
+  '.cjs': 'js',
+};
+const STREAMING_APIS = ['renderToReadableStream', 'renderToPipeableStream'];
+const SPECIAL_PAGES = ['_app', '_document', '_error'];
+
+export async function scanSources(root: string, result: MigrationResult) {
+  const { SHIMMED_NEXT_DIST_PATHS } = await import('../../compat');
+  const shimmed = new Set<string>(SHIMMED_NEXT_DIST_PATHS);
+  const deepImports: string[] = [];
+  const streaming: string[] = [];
+  const headImports: string[] = [];
+
+  for await (const file of walk(root)) {
+    const loader = LOADERS[path.extname(file)];
+    if (!loader) continue;
+    const text = await readFile(file, 'utf8');
+    let specifiers: string[];
+    try {
+      specifiers = new Bun.Transpiler({ loader }).scanImports(text).map(item => item.path);
+    } catch {
+      continue; // unparseable source is the app's problem, not migrate's
+    }
+    const relative = path.relative(root, file);
+    for (const specifier of specifiers) {
+      if (specifier.startsWith('next/dist/') && !shimmed.has(specifier.replace(/\.js$/, ''))) {
+        deepImports.push(`${relative} → ${specifier}`);
+      }
+      if (
+        /^react-dom\/server(\.|\/|$)/.test(specifier) &&
+        STREAMING_APIS.some(api => text.includes(api))
+      ) {
+        streaming.push(relative);
+      }
+      if (specifier === 'next/head') headImports.push(relative);
+    }
+  }
+
+  if (deepImports.length > 0) {
+    result.reports.push({
+      title: 'Unsupported next/dist/* deep imports',
+      detail:
+        'Only five next/dist paths are shimmed — replace these with public APIs. See reference/compat.md ("Smaller surfaces").',
+      files: deepImports,
+    });
+  }
+  if (streaming.length > 0) {
+    result.reports.push({
+      title: 'react-dom/server streaming APIs',
+      detail:
+        'preact/compat does not provide renderToReadableStream/renderToPipeableStream — use pnext rendering instead. See reference/compat.md.',
+      files: [...new Set(streaming)],
+    });
+  }
+
+  if (headImports.length > 0) {
+    result.reports.push({
+      title: 'next/head renders nothing',
+      detail:
+        'Move these tags to metadata exports (or the root layout <head>) — next/head is a silent no-op under pnext. See reference/compat.md.',
+      files: [...new Set(headImports)],
+    });
+  }
+
+  scanSpecialPages(root, result);
+  await scanNextConfig(root, result);
+}
+
+function scanSpecialPages(root: string, result: MigrationResult) {
+  const found: string[] = [];
+  for (const base of ['pages', path.join('src', 'pages')]) {
+    for (const name of SPECIAL_PAGES) {
+      for (const extension of ['.tsx', '.ts', '.jsx', '.js']) {
+        const relative = path.join(base, `${name}${extension}`);
+        if (existsSync(path.join(root, relative))) found.push(relative);
+      }
+    }
+  }
+  if (found.length === 0) return;
+  result.reports.push({
+    title: 'pages/_app, _document and _error are ignored',
+    detail:
+      'Move this setup into the app-router root layout — pnext never loads these files. See reference/compat.md.',
+    files: found,
+  });
+}
+
+async function scanNextConfig(root: string, result: MigrationResult) {
+  for (const name of ['next.config.ts', 'next.config.js', 'next.config.mjs', 'next.config.cjs']) {
+    const file = path.join(root, name);
+    if (!existsSync(file)) continue;
+    const text = await readFile(file, 'utf8');
+    if (!text.includes('webpack:') && !text.includes('webpack(')) return;
+    const svgr = text.includes('@svgr/webpack');
+    result.reports.push({
+      title: `${name} defines a webpack function`,
+      detail: svgr
+        ? 'The webpack function is never executed; SVGR is auto-detected from @svgr/webpack, so SVG imports keep working. See reference/compat.md.'
+        : 'The webpack function is never executed — port any custom loaders/plugins to pnext config. See reference/compat.md.',
+    });
+    return;
+  }
+}
+
+async function* walk(dir: string): AsyncGenerator<string> {
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      yield* walk(path.join(dir, entry.name));
+    } else if (entry.isFile()) {
+      yield path.join(dir, entry.name);
+    }
+  }
+}

package/src/cli/migrate/spinner.ts

@@ -0,0 +1,20 @@
+// Minimal braille spinner for the one step that can take a while (the source
+// scan over a large app). TTY-only, so piped/CI output stays clean.
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+export async function withSpinner<T>(label: string, run: () => Promise<T>): Promise<T> {
+  if (!process.stdout.isTTY) return run();
+
+  let frame = 0;
+  const timer = setInterval(() => {
+    process.stdout.write(`\r${FRAMES[frame % FRAMES.length]} ${label}`);
+    frame += 1;
+  }, 80);
+  try {
+    return await run();
+  } finally {
+    clearInterval(timer);
+    process.stdout.write('\r\x1b[2K');
+  }
+}

package/src/cli/migrate/tsconfig.ts

@@ -0,0 +1,77 @@
+// tsconfig.json: drop the `next` TS plugin and repoint the generated-types
+// include glob at .pnext/types. Configs with comments (JSONC) are reported,
+// never rewritten — the same bail compat/tsconfig-defaults.ts takes, since a
+// JSON round-trip would strip the user's comments.
+
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { MigrationResult } from './report';
+
+const MANUAL_STEPS =
+  'remove { "name": "next" } from compilerOptions.plugins and replace ".next/types" includes with ".pnext/types/**/*.ts".';
+
+export async function migrateTsconfig(root: string, result: MigrationResult, dryRun: boolean) {
+  const file = path.join(root, 'tsconfig.json');
+  if (!existsSync(file)) return;
+  const text = await readFile(file, 'utf8');
+
+  let config: Record<string, unknown>;
+  try {
+    config = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    result.reports.push({
+      title: 'tsconfig.json has comments (JSONC) — not edited',
+      detail: `Apply by hand: ${MANUAL_STEPS}`,
+    });
+    return;
+  }
+  if (typeof config !== 'object' || config === null) return;
+
+  const changes: string[] = [];
+  const compilerOptions = config.compilerOptions;
+  if (isObject(compilerOptions) && Array.isArray(compilerOptions.plugins)) {
+    const kept = compilerOptions.plugins.filter(
+      plugin => !(isObject(plugin) && plugin.name === 'next'),
+    );
+    if (kept.length !== compilerOptions.plugins.length) {
+      if (kept.length === 0) delete compilerOptions.plugins;
+      else compilerOptions.plugins = kept;
+      changes.push('next TypeScript plugin removed');
+    }
+  }
+
+  if (Array.isArray(config.include)) {
+    const seen = new Set<string>();
+    const include: unknown[] = [];
+    let repointed = false;
+    for (const entry of config.include) {
+      if (typeof entry !== 'string') {
+        include.push(entry);
+        continue;
+      }
+      const next =
+        entry.includes('.next/types') || entry.includes('.next/dev/types')
+          ? '.pnext/types/**/*.ts'
+          : entry;
+      if (next !== entry) repointed = true;
+      if (seen.has(next)) continue;
+      seen.add(next);
+      include.push(next);
+    }
+    if (repointed) {
+      config.include = include;
+      changes.push('type includes repointed at .pnext/types');
+    }
+  }
+
+  if (changes.length === 0) return;
+  if (!dryRun) await writeFile(file, `${JSON.stringify(config, null, 2)}\n`);
+  for (const change of changes) {
+    result.edits.push({ file: 'tsconfig.json', description: change });
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}