fix: handle remix-flat-routes folder route pattern (route.tsx) in migration CLI

- Fix isColocatedFile() misclassifying route entry files as colocated
- Fix route ID generation for route.tsx folder routes
- Fix snapshot normalization for route segment
- Add rewriteTypesRouteSpecifier() for +types/route imports
- Add stripTsExtension() for index.ts extension imports
- Add route source path exclusion in collectColocatedMappings

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

Author: coji

src/migration/fs-helpers.ts

@@ -8,6 +8,23 @@ export function visitFiles(dir: string, visitor: (file: string) => void): void {
   walkFiles(dir, visitor, { followSymlinks: false })
 }
 
+const ROUTE_ENTRY_BASENAMES = new Set(['route', 'index', '_index', '_layout'])
+
+function isRouteEntryBasename(basename: string): boolean {
+  const ext = path.extname(basename)
+  const name = ext ? basename.slice(0, -ext.length) : basename
+  return ROUTE_ENTRY_BASENAMES.has(name)
+}
+
+function isRouteSegment(segment: string): boolean {
+  if (segment === '' || segment === '.') return true
+  if (segment.endsWith('+')) return true
+  if (segment.startsWith('(') && segment.endsWith(')')) return true
+  if (segment.startsWith('__')) return true
+  if (segment.startsWith('_')) return true
+  return false
+}
+
 export function isColocatedFile(filename: string): boolean {
   const normalized = filename.replace(/\\/g, '/')
   const segments = normalized.split('/')
@@ -25,13 +42,32 @@ export function isColocatedFile(filename: string): boolean {
     return true
   }
 
-  return directorySegments.some((segment) => {
-    if (segment === '' || segment === '.') return false
-    if (segment.endsWith('+')) return false
-    if (segment.startsWith('(') && segment.endsWith(')')) return false
-    if (segment.startsWith('__')) return false
-    return true
-  })
+  // Count how many "regular" (non-route) directory segments exist after the
+  // last `+` parent. In remix-flat-routes, the first directory after a `+`
+  // folder is a route folder (e.g. `demo+/about/route.tsx`). Files named as
+  // route entries directly inside such a folder are route modules, not
+  // colocated files. Deeper regular directories indicate colocated content.
+  let lastPlusIndex = -1
+  for (let i = directorySegments.length - 1; i >= 0; i--) {
+    if (directorySegments[i].endsWith('+')) {
+      lastPlusIndex = i
+      break
+    }
+  }
+
+  const segmentsAfterPlus = directorySegments.slice(lastPlusIndex + 1)
+  const regularSegments = segmentsAfterPlus.filter(
+    (segment) => !isRouteSegment(segment),
+  )
+
+  // If there's exactly one regular directory after the last `+` folder and
+  // the file is a route entry (route.tsx, index.tsx, etc.), this is a folder
+  // route — not a colocated file.
+  if (regularSegments.length <= 1 && isRouteEntryBasename(basename)) {
+    return false
+  }
+
+  return regularSegments.length > 0
 }
 
 export function defaultTargetDir(sourceDir: string): string {

src/migration/import-rewriter.ts

@@ -208,7 +208,10 @@ function computeSpecifierReplacement(
 
   const relativeReplacement = rewriteRelativeSpecifier(base, context)
   if (relativeReplacement) {
-    const nextSpecifier = relativeReplacement + suffix
+    // Also strip /index.ts(x) from relative specifiers
+    const stripped =
+      stripTsExtension(relativeReplacement) ?? relativeReplacement
+    const nextSpecifier = stripped + suffix
     if (nextSpecifier !== specifier) {
       return nextSpecifier
     }
@@ -217,7 +220,19 @@ function computeSpecifierReplacement(
   let nextBase = base
   let changed = false
 
-  const aliasedReplacement = rewriteAliasedSpecifier(base, context)
+  const typesReplacement = rewriteTypesRouteSpecifier(nextBase, context)
+  if (typesReplacement) {
+    nextBase = typesReplacement
+    changed = true
+  }
+
+  const extensionReplacement = stripTsExtension(nextBase)
+  if (extensionReplacement) {
+    nextBase = extensionReplacement
+    changed = true
+  }
+
+  const aliasedReplacement = rewriteAliasedSpecifier(nextBase, context)
   if (aliasedReplacement) {
     nextBase = aliasedReplacement
     changed = true
@@ -239,6 +254,54 @@ function computeSpecifierReplacement(
   return null
 }
 
+/**
+ * When a folder route (`about/route.tsx`) is converted to a flat file
+ * (`about.tsx`), the virtual `+types/route` import must be updated to
+ * reference the new filename (e.g. `+types/about`).
+ */
+function rewriteTypesRouteSpecifier(
+  specifier: string,
+  context: ImportRewriteContext,
+): string | null {
+  const normalized = specifier.replace(/\\/g, '/')
+  const typesRoutePattern = /\/\+types\/route$/
+  if (!typesRoutePattern.test(normalized)) {
+    return null
+  }
+
+  const sourceBasename = path.basename(context.sourcePath)
+  const targetBasename = path.basename(context.targetPath)
+  const sourceNameWithoutExt = sourceBasename.replace(/\.[^.]+$/, '')
+  const targetNameWithoutExt = targetBasename.replace(/\.[^.]+$/, '')
+
+  // Only rewrite if the source file is `route.{ext}` and the target is
+  // different (i.e. the file was converted from a folder route to a flat file).
+  if (sourceNameWithoutExt !== 'route' || targetNameWithoutExt === 'route') {
+    return null
+  }
+
+  return normalized.replace(
+    typesRoutePattern,
+    `/+types/${targetNameWithoutExt}`,
+  )
+}
+
+/**
+ * Strips explicit `.ts` / `.tsx` extensions from import specifiers that
+ * reference barrel files (e.g. `./components/index.ts` → `./components`).
+ */
+function stripTsExtension(specifier: string): string | null {
+  const normalized = specifier.replace(/\\/g, '/')
+
+  // Strip /index.ts or /index.tsx suffix → import from directory
+  const indexTsPattern = /\/index\.tsx?$/
+  if (indexTsPattern.test(normalized)) {
+    return normalized.replace(indexTsPattern, '')
+  }
+
+  return null
+}
+
 function splitImportSpecifier(specifier: string): {
   base: string
   suffix: string

src/migration/migrate.ts

@@ -51,7 +51,14 @@ export function migrate(
   })
 
   const routeMappings = collectRouteMappings(routes, sourceDir, targetDir)
-  const colocatedMappings = collectColocatedMappings(sourceDir, targetDir)
+  const routeSourcePaths = new Set(
+    routeMappings.map((m) => normalizeAbsolutePath(m.source)),
+  )
+  const colocatedMappings = collectColocatedMappings(
+    sourceDir,
+    targetDir,
+    routeSourcePaths,
+  )
   const mappings = [...routeMappings, ...colocatedMappings]
   const normalizedMapping = createNormalizedMapping(mappings)
   const specifierReplacements = createSpecifierReplacements(
@@ -94,6 +101,7 @@ function collectRouteMappings(
 function collectColocatedMappings(
   sourceDir: string,
   targetDir: string,
+  routeSourcePaths: Set<string>,
 ): FileMapping[] {
   const mappings: FileMapping[] = []
 
@@ -103,6 +111,10 @@ function collectColocatedMappings(
     }
 
     const sourcePath = path.resolve(sourceDir, file)
+    if (routeSourcePaths.has(normalizeAbsolutePath(sourcePath))) {
+      return
+    }
+
     const targetPath = path.resolve(targetDir, convertColocatedPath(file))
     mappings.push({ source: sourcePath, target: targetPath })
   })

src/migration/normalizers.ts

@@ -88,6 +88,12 @@ export function normalizeSnapshotRouteFilePath(filePath: string): string {
       continue
     }
 
+    // Treat folder route convention (`about/route.tsx`) the same as flat file
+    // (`about.tsx`). The `route` segment is a marker, not a path component.
+    if (segment === 'route' && result.length > 0) {
+      continue
+    }
+
     if (segment === 'index' && result.length > 0) {
       const parent = result.pop()!
       result.push(`${parent}.index`)

src/migration/route-scanner.ts

@@ -50,7 +50,19 @@ export function scanRouteModules(
     const extension = path.extname(file)
     if (MIGRATION_ROUTE_EXTENSIONS.includes(extension)) {
       const relativePath = path.join(routesDirectory, file)
-      const routeId = createRouteId(relativePath)
+      const basename = path.basename(file, extension)
+      // In the folder route convention, `route.tsx` inside a folder means
+      // the folder itself is the route. Strip the `/route` segment so the
+      // route ID matches the folder name (same as remix-flat-routes).
+      let routeId: string
+      if (basename === 'route') {
+        // Use directory path directly as route ID — don't use createRouteId
+        // here because it strips dot-segments (e.g. `.biography` from
+        // `($lang).biography`).
+        routeId = path.dirname(relativePath).split(path.win32.sep).join('/')
+      } else {
+        routeId = createRouteId(relativePath)
+      }
       files[routeId] = relativePath
       return
     }