@remix-run/cli 0.0.0 → 0.1.0

package/src/lib/controller-ownership.ts

@@ -0,0 +1,397 @@
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+
+import {
+  getActionOwnerCandidates,
+  getControllerOwnerCandidates,
+  getOwnerModuleBaseName,
+  getPreferredOwnerDisplayPath,
+  getRouteSubtreePath,
+  isActionFileName,
+  isControllerEntryFileName,
+  toDiskSegment,
+} from './controller-files.ts'
+import type { RouteOwnerKind, RouteTreeNodeKind } from './route-map.ts'
+
+export interface OwnershipRouteNode {
+  children: OwnershipRouteNode[]
+  key: string
+  kind: RouteTreeNodeKind
+  method?: string
+  name: string
+}
+
+export interface ControllerDirectoryScan {
+  actionEntryPaths: Set<string>
+  controllerEntryPaths: Set<string>
+  rootDirectoryPaths: Set<string>
+  routeLocalFilePaths: Set<string>
+}
+
+export interface OwnedSubtreePlan {
+  alternateCandidates: string[]
+  alternateDisplayPath: string
+  entryCandidates: string[]
+  entryDisplayPath: string
+  kind: RouteOwnerKind
+  routeName: string
+  subtreePath: string
+}
+
+export interface OwnedSubtree extends OwnedSubtreePlan {
+  actualAlternatePath: string | null
+  actualAlternatePaths: string[]
+  actualEntryPath: string | null
+  actualEntryPaths: string[]
+  claimedFilePaths: string[]
+  claimedRouteLocalFilePaths: string[]
+}
+
+export interface ControllerOwnership {
+  orphanActionPaths: string[]
+  orphanControllerPaths: string[]
+  orphanRouteDirectoryPaths: string[]
+  scan: ControllerDirectoryScan
+  subtrees: OwnedSubtree[]
+}
+
+export async function inspectControllerOwnership(
+  appRoot: string,
+  tree: OwnershipRouteNode[],
+): Promise<ControllerOwnership> {
+  let subtreePlans = buildOwnedSubtrees(tree)
+  let scan = await scanControllersDirectory(appRoot)
+  let subtrees = applyScanToSubtrees(subtreePlans, scan)
+
+  return {
+    orphanActionPaths: getOrphanActionPaths(subtreePlans, scan),
+    orphanControllerPaths: getOrphanControllerPaths(subtreePlans, scan),
+    orphanRouteDirectoryPaths: getOrphanRouteDirectoryPaths(subtreePlans, scan),
+    scan,
+    subtrees,
+  }
+}
+
+export function buildOwnedSubtrees(
+  tree: OwnershipRouteNode[],
+  parentSegments: string[] = [],
+  subtrees: OwnedSubtreePlan[] = [],
+): OwnedSubtreePlan[] {
+  for (let node of tree) {
+    let segments = [...parentSegments, toDiskSegment(node.key)]
+
+    if (node.kind === 'group') {
+      let alternateCandidates = getActionOwnerCandidates(segments)
+      let entryCandidates = getControllerOwnerCandidates(segments)
+
+      subtrees.push({
+        alternateCandidates,
+        alternateDisplayPath: getPreferredOwnerDisplayPath(alternateCandidates),
+        entryCandidates,
+        entryDisplayPath: getPreferredOwnerDisplayPath(entryCandidates),
+        kind: 'controller',
+        routeName: node.name,
+        subtreePath: getRouteSubtreePath(segments),
+      })
+      buildOwnedSubtrees(node.children, segments, subtrees)
+      continue
+    }
+
+    if (parentSegments.length > 0) {
+      continue
+    }
+
+    let alternateCandidates = getControllerOwnerCandidates(segments)
+    let entryCandidates = getActionOwnerCandidates(segments)
+
+    subtrees.push({
+      alternateCandidates,
+      alternateDisplayPath: getPreferredOwnerDisplayPath(alternateCandidates),
+      entryCandidates,
+      entryDisplayPath: getPreferredOwnerDisplayPath(entryCandidates),
+      kind: 'action',
+      routeName: node.name,
+      subtreePath: getRouteSubtreePath(segments),
+    })
+  }
+
+  return subtrees
+}
+
+async function scanControllersDirectory(appRoot: string): Promise<ControllerDirectoryScan> {
+  let controllersDir = path.join(appRoot, 'app', 'controllers')
+  let controllerEntryPaths = new Set<string>()
+  let actionEntryPaths = new Set<string>()
+  let rootDirectoryPaths = new Set<string>()
+  let routeLocalFilePaths = new Set<string>()
+
+  async function walk(currentDir: string, isRoot: boolean): Promise<void> {
+    let entries
+    try {
+      entries = await fs.readdir(currentDir, { withFileTypes: true })
+    } catch (error) {
+      let nodeError = error as NodeJS.ErrnoException
+      if (nodeError.code === 'ENOENT' && isRoot) {
+        return
+      }
+
+      throw error
+    }
+
+    for (let entry of entries) {
+      let entryPath = path.join(currentDir, entry.name)
+      let relativePath = normalizeRelativePath(path.relative(appRoot, entryPath))
+
+      if (entry.isDirectory()) {
+        if (isRoot) {
+          rootDirectoryPaths.add(relativePath)
+        }
+
+        await walk(entryPath, false)
+        continue
+      }
+
+      if (!entry.isFile()) {
+        continue
+      }
+
+      if (isControllerEntryFileName(entry.name)) {
+        controllerEntryPaths.add(relativePath)
+        continue
+      }
+
+      if (isRoot && isActionCandidate(entry.name)) {
+        actionEntryPaths.add(relativePath)
+        continue
+      }
+
+      if (!isRoot && isRouteLocalFileName(entry.name)) {
+        routeLocalFilePaths.add(relativePath)
+      }
+    }
+  }
+
+  await walk(controllersDir, true)
+
+  return {
+    actionEntryPaths,
+    controllerEntryPaths,
+    rootDirectoryPaths,
+    routeLocalFilePaths,
+  }
+}
+
+function applyScanToSubtrees(
+  subtreePlans: OwnedSubtreePlan[],
+  scan: ControllerDirectoryScan,
+): OwnedSubtree[] {
+  let claimedRouteLocalPaths = claimFilesToDeepestSubtree(
+    [...scan.routeLocalFilePaths],
+    subtreePlans,
+  )
+  let claimedContentPaths = claimFilesToDeepestSubtree(getNestedContentPaths(scan), subtreePlans)
+
+  return subtreePlans.map((subtree) => {
+    let actualAlternatePaths = findOwnerPaths(
+      scan,
+      invertOwnerKind(subtree.kind),
+      subtree.alternateCandidates,
+    )
+    let actualEntryPaths = findOwnerPaths(scan, subtree.kind, subtree.entryCandidates)
+
+    return {
+      ...subtree,
+      actualAlternatePath: actualAlternatePaths[0] ?? null,
+      actualAlternatePaths,
+      actualEntryPath: actualEntryPaths[0] ?? null,
+      actualEntryPaths,
+      claimedFilePaths: claimedContentPaths.get(subtree.routeName) ?? [],
+      claimedRouteLocalFilePaths: claimedRouteLocalPaths.get(subtree.routeName) ?? [],
+    }
+  })
+}
+
+function getNestedContentPaths(scan: ControllerDirectoryScan): string[] {
+  let nestedControllerPaths = [...scan.controllerEntryPaths].filter((filePath) =>
+    isNestedControllerPath(filePath),
+  )
+
+  return [...new Set([...nestedControllerPaths, ...scan.routeLocalFilePaths])].sort()
+}
+
+function claimFilesToDeepestSubtree(
+  filePaths: string[],
+  subtreePlans: OwnedSubtreePlan[],
+): Map<string, string[]> {
+  let subtreesByDepth = [...subtreePlans].sort((left, right) => {
+    if (right.subtreePath.length !== left.subtreePath.length) {
+      return right.subtreePath.length - left.subtreePath.length
+    }
+
+    return left.routeName.localeCompare(right.routeName)
+  })
+  let claims = new Map<string, string[]>()
+
+  for (let filePath of filePaths.sort()) {
+    let matchingSubtree = subtreesByDepth.find((subtree) =>
+      isWithinDirectory(filePath, subtree.subtreePath),
+    )
+
+    if (matchingSubtree == null) {
+      continue
+    }
+
+    let claimedPaths = claims.get(matchingSubtree.routeName)
+    if (claimedPaths == null) {
+      claims.set(matchingSubtree.routeName, [filePath])
+      continue
+    }
+
+    claimedPaths.push(filePath)
+  }
+
+  return claims
+}
+
+function getOrphanActionPaths(
+  subtreePlans: OwnedSubtreePlan[],
+  scan: ControllerDirectoryScan,
+): string[] {
+  let expectedActionPaths = new Set(
+    subtreePlans
+      .filter((subtree) => subtree.kind === 'action')
+      .flatMap((subtree) => subtree.entryCandidates),
+  )
+  let alternateActionPaths = new Set(
+    subtreePlans
+      .filter((subtree) => subtree.kind === 'controller')
+      .flatMap((subtree) => subtree.alternateCandidates),
+  )
+
+  return [...scan.actionEntryPaths]
+    .filter((filePath) => !expectedActionPaths.has(filePath))
+    .filter((filePath) => !alternateActionPaths.has(filePath))
+    .sort()
+}
+
+function getOrphanControllerPaths(
+  subtreePlans: OwnedSubtreePlan[],
+  scan: ControllerDirectoryScan,
+): string[] {
+  let expectedControllerPaths = new Set(
+    subtreePlans
+      .filter((subtree) => subtree.kind === 'controller')
+      .flatMap((subtree) => subtree.entryCandidates),
+  )
+  let alternateControllerPaths = new Set(
+    subtreePlans
+      .filter((subtree) => subtree.kind === 'action')
+      .flatMap((subtree) => subtree.alternateCandidates),
+  )
+
+  return [...scan.controllerEntryPaths]
+    .filter((filePath) => !expectedControllerPaths.has(filePath))
+    .filter((filePath) => !alternateControllerPaths.has(filePath))
+    .sort()
+}
+
+function getOrphanRouteDirectoryPaths(
+  subtreePlans: OwnedSubtreePlan[],
+  scan: ControllerDirectoryScan,
+): string[] {
+  let expectedRootDirectories = new Set(
+    subtreePlans.map((subtree) => getTopLevelSubtreePath(subtree.subtreePath)),
+  )
+  let actualControllerDirectories = [...scan.controllerEntryPaths].map((controllerPath) =>
+    normalizeRelativePath(path.dirname(controllerPath)),
+  )
+
+  return [...scan.rootDirectoryPaths]
+    .filter((directoryPath) => !expectedRootDirectories.has(directoryPath))
+    .filter(
+      (directoryPath) =>
+        !actualControllerDirectories.some((controllerPath) =>
+          isDirectoryWithinDirectory(controllerPath, directoryPath),
+        ),
+    )
+    .sort()
+}
+
+function hasOwnerPath(
+  scan: ControllerDirectoryScan,
+  kind: RouteOwnerKind,
+  filePath: string,
+): boolean {
+  return kind === 'action'
+    ? scan.actionEntryPaths.has(filePath)
+    : scan.controllerEntryPaths.has(filePath)
+}
+
+function invertOwnerKind(kind: RouteOwnerKind): RouteOwnerKind {
+  return kind === 'action' ? 'controller' : 'action'
+}
+
+function isActionCandidate(fileName: string): boolean {
+  return isActionFileName(fileName)
+}
+
+function isRouteLocalFileName(fileName: string): boolean {
+  let baseName = getOwnerModuleBaseName(fileName)
+
+  return (
+    baseName != null &&
+    baseName !== 'controller' &&
+    !baseName.endsWith('.test') &&
+    !baseName.endsWith('.spec')
+  )
+}
+
+function findOwnerPath(
+  scan: ControllerDirectoryScan,
+  kind: RouteOwnerKind,
+  candidatePaths: string[],
+): string | null {
+  return findOwnerPaths(scan, kind, candidatePaths)[0] ?? null
+}
+
+function findOwnerPaths(
+  scan: ControllerDirectoryScan,
+  kind: RouteOwnerKind,
+  candidatePaths: string[],
+): string[] {
+  let existingPaths: string[] = []
+
+  for (let candidatePath of candidatePaths) {
+    if (hasOwnerPath(scan, kind, candidatePath)) {
+      existingPaths.push(candidatePath)
+    }
+  }
+
+  return existingPaths
+}
+
+function isNestedControllerPath(filePath: string): boolean {
+  return (
+    filePath.startsWith('app/controllers/') &&
+    filePath.slice('app/controllers/'.length).includes('/')
+  )
+}
+
+function isWithinDirectory(filePath: string, directoryPath: string): boolean {
+  return filePath.startsWith(`${directoryPath}/`)
+}
+
+function isDirectoryWithinDirectory(directoryPath: string, parentDirectoryPath: string): boolean {
+  return (
+    directoryPath === parentDirectoryPath || isWithinDirectory(directoryPath, parentDirectoryPath)
+  )
+}
+
+function getTopLevelSubtreePath(subtreePath: string): string {
+  let subtreeSegments = subtreePath.slice('app/controllers/'.length).split('/')
+  return getRouteSubtreePath([subtreeSegments[0]])
+}
+
+function normalizeRelativePath(filePath: string): string {
+  return filePath.split(path.sep).join('/')
+}

package/src/lib/display-path.ts

@@ -0,0 +1,16 @@
+import * as path from 'node:path'
+import * as process from 'node:process'
+
+export function getDisplayPath(filePath: string, cwd: string = process.cwd()): string {
+  let relativePath = path.relative(path.resolve(cwd), path.resolve(filePath))
+
+  if (relativePath.length === 0) {
+    return '.'
+  }
+
+  if (path.isAbsolute(relativePath)) {
+    return filePath
+  }
+
+  return relativePath
+}

package/src/lib/doctor/controller-findings.ts

@@ -0,0 +1,157 @@
+import type { ControllerOwnership, OwnedSubtree } from '../controller-ownership.ts'
+import type { DoctorFinding, DoctorFixPlan } from './types.ts'
+
+export function getControllerFindings(
+  ownership: ControllerOwnership,
+  fixPlans: DoctorFixPlan[],
+): DoctorFinding[] {
+  return [
+    ...getSubtreeFindings(ownership.subtrees, fixPlans),
+    ...ownership.orphanActionPaths.map((actualPath) => ({
+      actualPath,
+      code: 'orphan-action' as const,
+      message: `Standalone action ${actualPath} does not match any top-level route.`,
+      severity: 'warn' as const,
+      suite: 'controllers' as const,
+    })),
+    ...ownership.orphanControllerPaths.map((actualPath) => ({
+      actualPath,
+      code: 'orphan-controller' as const,
+      message: `Controller ${actualPath} does not match any route group.`,
+      severity: 'warn' as const,
+      suite: 'controllers' as const,
+    })),
+    ...ownership.orphanRouteDirectoryPaths.map((actualPath) => ({
+      actualPath,
+      code: 'orphan-route-directory' as const,
+      message: `Directory ${actualPath} does not match any route subtree.`,
+      severity: 'warn' as const,
+      suite: 'controllers' as const,
+    })),
+  ]
+}
+
+function getSubtreeFindings(subtrees: OwnedSubtree[], fixPlans: DoctorFixPlan[]): DoctorFinding[] {
+  let findings: DoctorFinding[] = []
+  let fixableFindingKeys = new Set(
+    fixPlans.map((fixPlan) => `${fixPlan.code}:${fixPlan.routeName ?? ''}`),
+  )
+
+  for (let subtree of subtrees) {
+    let actualEntryPath = subtree.actualEntryPath ?? undefined
+    let actualAlternatePath = subtree.actualAlternatePath ?? undefined
+
+    if (subtree.actualEntryPaths.length > 1) {
+      findings.push({
+        actualPath: subtree.actualEntryPaths[0],
+        code: 'duplicate-owner-file',
+        expectedPath: subtree.entryDisplayPath,
+        message: `Route "${subtree.routeName}" has multiple ${subtree.kind} files: ${subtree.actualEntryPaths.join(', ')}. Keep only one ${subtree.kind} owner file.`,
+        routeName: subtree.routeName,
+        severity: 'warn',
+        suite: 'controllers',
+      })
+      continue
+    }
+
+    if (subtree.actualAlternatePaths.length > 1) {
+      let alternateKind = subtree.kind === 'action' ? 'controller' : 'action'
+
+      findings.push({
+        actualPath: subtree.actualAlternatePaths[0],
+        code: 'duplicate-owner-file',
+        expectedPath: subtree.entryDisplayPath,
+        message: `Route "${subtree.routeName}" has multiple ${alternateKind} files: ${subtree.actualAlternatePaths.join(', ')}. Keep only one ${alternateKind} owner file.`,
+        routeName: subtree.routeName,
+        severity: 'warn',
+        suite: 'controllers',
+      })
+      continue
+    }
+
+    if (actualEntryPath != null && actualAlternatePath != null) {
+      findings.push({
+        actualPath: actualAlternatePath,
+        code: 'ambiguous-owner',
+        expectedPath: actualEntryPath,
+        message:
+          subtree.kind === 'action'
+            ? `Route "${subtree.routeName}" has both action ${actualEntryPath} and controller ${actualAlternatePath}.`
+            : `Route "${subtree.routeName}" has both controller ${actualEntryPath} and standalone action ${actualAlternatePath}.`,
+        routeName: subtree.routeName,
+        severity: 'warn',
+        suite: 'controllers',
+      })
+      continue
+    }
+
+    if (actualAlternatePath != null) {
+      findings.push({
+        actualPath: actualAlternatePath,
+        code: 'wrong-owner-kind',
+        expectedPath: subtree.entryDisplayPath,
+        message:
+          subtree.kind === 'action'
+            ? `Route "${subtree.routeName}" expects action ${subtree.entryDisplayPath}, but found controller ${actualAlternatePath}.`
+            : `Route "${subtree.routeName}" expects controller ${subtree.entryDisplayPath}, but found standalone action ${actualAlternatePath}.`,
+        fixable: fixableFindingKeys.has(`wrong-owner-kind:${subtree.routeName}`),
+        routeName: subtree.routeName,
+        severity: 'warn',
+        suite: 'controllers',
+      })
+      continue
+    }
+
+    if (subtree.kind === 'controller' && subtree.actualEntryPath == null) {
+      let code =
+        subtree.claimedFilePaths.length > 0
+          ? ('incomplete-controller' as const)
+          : ('missing-owner' as const)
+
+      findings.push({
+        actualPath: subtree.claimedFilePaths.length > 0 ? subtree.subtreePath : undefined,
+        code,
+        expectedPath: subtree.entryDisplayPath,
+        fixable: fixableFindingKeys.has(`${code}:${subtree.routeName}`),
+        message:
+          subtree.claimedFilePaths.length > 0
+            ? `Route "${subtree.routeName}" has files under ${subtree.subtreePath}, but is missing controller ${subtree.entryDisplayPath}.`
+            : `Route "${subtree.routeName}" is missing controller ${subtree.entryDisplayPath}.`,
+        routeName: subtree.routeName,
+        severity: 'warn',
+        suite: 'controllers',
+      })
+      continue
+    }
+
+    if (subtree.kind === 'action' && subtree.claimedFilePaths.length > 0) {
+      findings.push({
+        actualPath: subtree.subtreePath,
+        code: 'promotion-drift',
+        expectedPath: actualEntryPath ?? subtree.entryDisplayPath,
+        message:
+          actualEntryPath == null
+            ? `Route "${subtree.routeName}" has files under ${subtree.subtreePath}, but is still expected to use action ${subtree.entryDisplayPath}. Promote it to controller ${subtree.alternateDisplayPath} or move the files back into ${subtree.entryDisplayPath}.`
+            : `Route "${subtree.routeName}" uses action ${actualEntryPath}, but also has files under ${subtree.subtreePath}. Promote it to controller ${subtree.alternateDisplayPath} or keep the route in ${actualEntryPath}.`,
+        routeName: subtree.routeName,
+        severity: 'warn',
+        suite: 'controllers',
+      })
+      continue
+    }
+
+    if (subtree.actualEntryPath == null) {
+      findings.push({
+        code: 'missing-owner',
+        expectedPath: subtree.entryDisplayPath,
+        fixable: fixableFindingKeys.has(`missing-owner:${subtree.routeName}`),
+        message: `Route "${subtree.routeName}" is missing action ${subtree.entryDisplayPath}.`,
+        routeName: subtree.routeName,
+        severity: 'warn',
+        suite: 'controllers',
+      })
+    }
+  }
+
+  return findings
+}