codegraph/src/resolution/frameworks/astro.ts

/**
 * Astro Framework Resolver
 *
 * Handles Astro component references, the `Astro` global, `astro:*` virtual
 * module imports, and Astro's `src/pages/` file-based routing.
 */

import { Node } from '../../types';
import { FrameworkResolver, UnresolvedRef, ResolvedRef, ResolutionContext } from '../types';

/**
 * Astro virtual module prefixes — framework-provided, not user code
 */
const ASTRO_VIRTUAL_MODULES = [
  'astro:content',
  'astro:assets',
  'astro:actions',
  'astro:env',
  'astro:i18n',
  'astro:middleware',
  'astro:transitions',
  'astro:components',
  'astro:schema',
];

export const astroResolver: FrameworkResolver = {
  name: 'astro',

  detect(context: ResolutionContext): boolean {
    // Check for astro in package.json
    const packageJson = context.readFile('package.json');
    if (packageJson) {
      try {
        const pkg = JSON.parse(packageJson);
        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
        if (deps.astro) {
          return true;
        }
      } catch {
        // Invalid JSON
      }
    }

    // Check for .astro files in project
    const allFiles = context.getAllFiles();
    return allFiles.some((f) => f.endsWith('.astro'));
  },

  resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null {
    // Pattern 1: the `Astro` global (Astro.props, Astro.url, Astro.params, …)
    // — runtime-provided in every component's frontmatter. Resolving it as
    // framework-provided keeps it from name-matching a user symbol named Astro.
    if (ref.referenceName === 'Astro' || ref.referenceName.startsWith('Astro.')) {
      return {
        original: ref,
        targetNodeId: ref.fromNodeId,
        confidence: 1.0,
        resolvedBy: 'framework',
      };
    }

    // Pattern 2: astro:* virtual module imports (astro:content, astro:assets, …)
    if (ref.referenceKind === 'imports' && ref.referenceName.startsWith('astro:')) {
      if (ASTRO_VIRTUAL_MODULES.some((prefix) => ref.referenceName.startsWith(prefix))) {
        return {
          original: ref,
          targetNodeId: ref.fromNodeId,
          confidence: 1.0,
          resolvedBy: 'framework',
        };
      }
    }

    // Pattern 3: Component references (PascalCase) — resolve to component
    // nodes. Template tags arrive as `references`, frontmatter expression
    // usages as `calls`.
    if (
      isPascalCase(ref.referenceName) &&
      (ref.referenceKind === 'references' || ref.referenceKind === 'calls')
    ) {
      const result = resolveComponent(ref.referenceName, ref.filePath, context);
      if (result) {
        return {
          original: ref,
          targetNodeId: result,
          confidence: 0.8,
          resolvedBy: 'framework',
        };
      }
    }

    return null;
  },

  extract(filePath: string, _content: string) {
    const nodes: Node[] = [];
    const now = Date.now();

    // Normalize to forward slashes
    const normalized = filePath.replace(/\\/g, '/');

    // Astro file-based routing lives under src/pages/ — .astro files are
    // pages, .ts/.js files are API endpoints. (.md/.mdx pages exist too but
    // aren't indexed as source.) Underscore-prefixed segments are excluded
    // from routing by Astro.
    const pagesMatch = /(?:^|\/)src\/pages\//.exec(normalized);
    if (pagesMatch && /\.(astro|ts|js|mjs)$/.test(normalized)) {
      const afterPages = normalized.substring(pagesMatch.index + pagesMatch[0].length);
      const base = afterPages.split('/').pop() || '';

      // Underscore-prefixed segments are excluded from routing by Astro;
      // a stray `*.config.*` in a pages dir is never a route.
      if (
        !afterPages.split('/').some((segment) => segment.startsWith('_')) &&
        !/\.config\.[a-z]+$/.test(base)
      ) {
        const routePath = filePathToAstroRoute(afterPages);

        nodes.push({
          id: `route:${filePath}:${routePath}:1`,
          kind: 'route',
          name: routePath,
          qualifiedName: `${filePath}::route:${routePath}`,
          filePath,
          startLine: 1,
          endLine: 1,
          startColumn: 0,
          endColumn: 0,
          language: normalized.endsWith('.astro') ? 'astro' : 'typescript',
          updatedAt: now,
        });
      }
    }

    return { nodes, references: [] };
  },
};

/**
 * Check if string is PascalCase
 */
function isPascalCase(str: string): boolean {
  return /^[A-Z][a-zA-Z0-9]*$/.test(str);
}

/**
 * Resolve an Astro component reference using name-based lookup
 */
function resolveComponent(
  name: string,
  fromFile: string,
  context: ResolutionContext
): string | null {
  // Look for component nodes by name
  const candidates = context.getNodesByName(name);
  const components = candidates.filter((n) => n.kind === 'component');

  if (components.length === 0) return null;

  // Prefer same directory
  const fromDir = fromFile.substring(0, fromFile.lastIndexOf('/'));
  const sameDir = components.filter((n) => n.filePath.startsWith(fromDir));
  if (sameDir.length > 0) return sameDir[0]!.id;

  // No positional signal: only an UNAMBIGUOUS name may resolve — picking
  // components[0] would choose an arbitrary same-named component in a
  // multi-app monorepo (#764). Ambiguity falls through to the name-matcher,
  // whose proximity scoring decides.
  return components.length === 1 ? components[0]!.id : null;
}

/**
 * Convert a path under src/pages/ to an Astro route path.
 *
 * blog/[slug].astro        -> /blog/:slug
 * blog/[...path].astro     -> /blog/*path
 * api/posts.ts             -> /api/posts
 * index.astro              -> /
 */
function filePathToAstroRoute(afterPages: string): string {
  // Remove the extension
  const withoutExt = afterPages.replace(/\.(astro|ts|js|mjs)$/, '');

  // index files map to their parent path (index -> /, blog/index -> /blog)
  const withoutIndex = withoutExt.replace(/(^|\/)index$/, '$1').replace(/\/$/, '');

  // Convert Astro param syntax
  const route = '/' + withoutIndex
    .replace(/\[\.\.\.([^\]]+)\]/g, '*$1') // [...rest] -> *rest (catch-all)
    .replace(/\[([^\]]+)\]/g, ':$1'); // [param] -> :param

  if (route === '/') return '/';
  // Remove trailing slash
  return route.replace(/\/$/, '');
}