feat(extraction+resolution): Astro support — frontmatter/template extraction + src/pages routes (#768) (#815)

.astro files were not indexed at all, leaving a typical Astro site mostly
invisible to search/impact/explore. New AstroExtractor (Svelte/Vue SFC
pattern): component node per file, TS frontmatter + <script> blocks
delegated to the TypeScript extractor, template {fn(...)} calls (incl. the
multiline `{posts.map((post) => (` opening line), PascalCase component-tag
references. New astroResolver: Astro global + astro:* virtual modules as
framework-provided, component resolution with the #764 ambiguity rule,
src/pages/ file-based routes ([param]→:param, [...rest]→*rest, _-prefixed
and *.config.* excluded). SFC languages now preload the TS/JS grammars
their extractors delegate to (a pure-SFC file set previously had none
loaded). Also fixes a pre-existing Svelte/Vue script-block off-by-one that
reported every script symbol one line low.

Validated per the playbook: stalux (the issue's repro) 54/54 .astro files
indexed, getIconNode found at its exact line, 14/14 routes, 93.0% fair
cross-file coverage; AstroPaper 27/27 components, 13/13 routes (underscore
dirs correctly excluded), explore connects page→Card→Datetime through the
jsx-render synthesizer; node/edge counts stable across re-syncs.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

src/extraction/astro-extractor.ts

@@ -0,0 +1,365 @@
+import { Node, Edge, ExtractionResult, ExtractionError, UnresolvedReference } from '../types';
+import { generateNodeId } from './tree-sitter-helpers';
+import { TreeSitterExtractor } from './tree-sitter';
+import { isLanguageSupported } from './grammars';
+
+/**
+ * Astro built-in components — compiler-provided (`<Fragment>`) or shipped by
+ * `astro:components` (`<Code>`, `<Debug>`), not user code.
+ */
+const ASTRO_BUILTIN_COMPONENTS = new Set(['Fragment', 'Code', 'Debug']);
+
+/**
+ * AstroExtractor - Extracts code relationships from Astro component files
+ *
+ * Astro files are multi-language: a TypeScript frontmatter block fenced by
+ * `---` lines, a JSX-like HTML template, and optional <script>/<style> blocks.
+ * Rather than parsing a full Astro grammar, we extract the frontmatter and
+ * <script> contents and delegate them to the TypeScript TreeSitterExtractor
+ * (Astro processes both as TypeScript by default — no `lang` attr needed).
+ *
+ * Also extracts function calls from template expressions (`{fn(...)}`) and
+ * component usages (`<PascalCase>`) so cross-file edges are captured even
+ * when the only reference lives in markup.
+ *
+ * Every .astro file produces a component node (Astro components are always
+ * importable).
+ */
+export class AstroExtractor {
+  private filePath: string;
+  private source: string;
+  private nodes: Node[] = [];
+  private edges: Edge[] = [];
+  private unresolvedReferences: UnresolvedReference[] = [];
+  private errors: ExtractionError[] = [];
+
+  constructor(filePath: string, source: string) {
+    this.filePath = filePath;
+    this.source = source;
+  }
+
+  /**
+   * Extract from Astro source
+   */
+  extract(): ExtractionResult {
+    const startTime = Date.now();
+
+    try {
+      // Create component node for the .astro file itself
+      const componentNode = this.createComponentNode();
+
+      // Extract and process the frontmatter block (--- fenced, TypeScript)
+      const frontmatter = this.extractFrontmatter();
+      if (frontmatter) {
+        this.processScriptContent(frontmatter, componentNode.id, 'frontmatter');
+      }
+
+      // Extract and process <script> blocks (client-side, TypeScript-capable)
+      for (const block of this.extractScriptBlocks()) {
+        this.processScriptContent(block, componentNode.id, 'script');
+      }
+
+      // Ranges the template scans must skip: frontmatter + <script>/<style>
+      const coveredRanges = this.getCoveredRanges(frontmatter);
+
+      // Extract function calls from template expressions ({fn(...)})
+      this.extractTemplateCalls(componentNode.id, coveredRanges);
+
+      // Extract component usages from template (<ComponentName>)
+      this.extractTemplateComponents(componentNode.id, coveredRanges);
+    } catch (error) {
+      this.errors.push({
+        message: `Astro extraction error: ${error instanceof Error ? error.message : String(error)}`,
+        severity: 'error',
+        code: 'parse_error',
+      });
+    }
+
+    return {
+      nodes: this.nodes,
+      edges: this.edges,
+      unresolvedReferences: this.unresolvedReferences,
+      errors: this.errors,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * Create a component node for the .astro file
+   */
+  private createComponentNode(): Node {
+    const lines = this.source.split('\n');
+    const fileName = this.filePath.split(/[/\\]/).pop() || this.filePath;
+    const componentName = fileName.replace(/\.astro$/, '');
+    const id = generateNodeId(this.filePath, 'component', componentName, 1);
+
+    const node: Node = {
+      id,
+      kind: 'component',
+      name: componentName,
+      qualifiedName: `${this.filePath}::${componentName}`,
+      filePath: this.filePath,
+      language: 'astro',
+      startLine: 1,
+      endLine: lines.length,
+      startColumn: 0,
+      endColumn: lines[lines.length - 1]?.length || 0,
+      isExported: true, // Astro components are always importable
+      updatedAt: Date.now(),
+    };
+
+    this.nodes.push(node);
+    return node;
+  }
+
+  /**
+   * Extract the frontmatter block: the content between the opening `---`
+   * fence (first non-blank line of the file) and the closing `---` fence.
+   * An unclosed fence is treated as "no frontmatter" rather than swallowing
+   * the whole template as TypeScript.
+   *
+   * Returns the content plus its 0-indexed start line, or null.
+   */
+  private extractFrontmatter(): { content: string; startLine: number; endLine: number } | null {
+    const lines = this.source.split('\n');
+
+    // Opening fence must be the first non-blank line
+    let openIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+      const trimmed = lines[i]!.trim();
+      if (trimmed === '') continue;
+      if (trimmed === '---') openIdx = i;
+      break;
+    }
+    if (openIdx === -1) return null;
+
+    // Closing fence
+    let closeIdx = -1;
+    for (let i = openIdx + 1; i < lines.length; i++) {
+      if (lines[i]!.trim() === '---') {
+        closeIdx = i;
+        break;
+      }
+    }
+    if (closeIdx === -1) return null;
+
+    return {
+      content: lines.slice(openIdx + 1, closeIdx).join('\n'),
+      startLine: openIdx + 1, // 0-indexed line where content starts
+      endLine: closeIdx, // 0-indexed line of the closing fence
+    };
+  }
+
+  /**
+   * Extract <script> blocks from the template portion
+   */
+  private extractScriptBlocks(): Array<{ content: string; startLine: number }> {
+    const blocks: Array<{ content: string; startLine: number }> = [];
+
+    const scriptRegex = /<script(\s[^>]*)?>(?<content>[\s\S]*?)<\/script>/g;
+    let match;
+
+    while ((match = scriptRegex.exec(this.source)) !== null) {
+      const content = match.groups?.content || match[2] || '';
+
+      // Calculate the 0-indexed line where the content begins. The content
+      // starts right after the opening tag's `>` — its leading `\n` is part
+      // of the content, so relative line 1 sits ON the tag's closing line
+      // (do not add 1 here; that double-counts the embedded newline).
+      const beforeScript = this.source.substring(0, match.index);
+      const scriptTagLine = (beforeScript.match(/\n/g) || []).length;
+      const openingTag = match[0].substring(0, match[0].indexOf('>') + 1);
+      const openingTagLines = (openingTag.match(/\n/g) || []).length;
+      const contentStartLine = scriptTagLine + openingTagLines; // 0-indexed
+
+      blocks.push({ content, startLine: contentStartLine });
+    }
+
+    return blocks;
+  }
+
+  /**
+   * Process frontmatter / script content by delegating to TreeSitterExtractor.
+   * Astro treats both as TypeScript by default.
+   */
+  private processScriptContent(
+    block: { content: string; startLine: number },
+    componentNodeId: string,
+    label: 'frontmatter' | 'script'
+  ): void {
+    if (!isLanguageSupported('typescript')) {
+      this.errors.push({
+        message: `Parser for typescript not available, cannot parse Astro ${label} block`,
+        severity: 'warning',
+      });
+      return;
+    }
+
+    // Delegate to TreeSitterExtractor
+    const extractor = new TreeSitterExtractor(this.filePath, block.content, 'typescript');
+    const result = extractor.extract();
+
+    // Offset line numbers from the block back to .astro file positions
+    for (const node of result.nodes) {
+      node.startLine += block.startLine;
+      node.endLine += block.startLine;
+      node.language = 'astro'; // Mark as astro, not TS
+
+      this.nodes.push(node);
+
+      // Add containment edge from component to this node
+      this.edges.push({
+        source: componentNodeId,
+        target: node.id,
+        kind: 'contains',
+      });
+    }
+
+    // Offset edges (they reference line numbers)
+    for (const edge of result.edges) {
+      if (edge.line) {
+        edge.line += block.startLine;
+      }
+      this.edges.push(edge);
+    }
+
+    // Offset unresolved references
+    for (const ref of result.unresolvedReferences) {
+      ref.line += block.startLine;
+      ref.filePath = this.filePath;
+      ref.language = 'astro';
+      this.unresolvedReferences.push(ref);
+    }
+
+    // Carry over errors
+    for (const error of result.errors) {
+      if (error.line) {
+        error.line += block.startLine;
+      }
+      this.errors.push(error);
+    }
+  }
+
+  /**
+   * Line ranges (0-indexed, inclusive) the template scans must skip:
+   * the frontmatter block and <script>/<style> blocks.
+   */
+  private getCoveredRanges(
+    frontmatter: { startLine: number; endLine: number } | null
+  ): Array<[number, number]> {
+    const coveredRanges: Array<[number, number]> = [];
+
+    if (frontmatter) {
+      // Cover from the opening fence line through the closing fence line
+      coveredRanges.push([frontmatter.startLine - 1, frontmatter.endLine]);
+    }
+
+    const tagRegex = /<(script|style)(\s[^>]*)?>[\s\S]*?<\/\1>/g;
+    let tagMatch;
+    while ((tagMatch = tagRegex.exec(this.source)) !== null) {
+      const startLine = (this.source.substring(0, tagMatch.index).match(/\n/g) || []).length;
+      const endLine = startLine + (tagMatch[0].match(/\n/g) || []).length;
+      coveredRanges.push([startLine, endLine]);
+    }
+
+    return coveredRanges;
+  }
+
+  /**
+   * Extract function calls from Astro template expressions.
+   *
+   * Astro templates embed JSX-like expressions (`{formatDate(post.date)}`,
+   * `class:list={cn(...)}`), so calls frequently live in markup rather than
+   * the frontmatter. We scan template lines for `{expression}` groups and
+   * extract call patterns from them. A `{` group left open at end-of-line
+   * (the pervasive `{posts.map((post) => (` pattern) contributes the calls
+   * on its opening line.
+   */
+  private extractTemplateCalls(
+    componentNodeId: string,
+    coveredRanges: Array<[number, number]>
+  ): void {
+    const lines = this.source.split('\n');
+    // Complete groups: {...} — excluding JSX comments ({/* ... */})
+    const exprRegex = /\{([^}/][^}]*)\}/g;
+    // A group opened but not closed on this line
+    const openExprRegex = /\{([^}/][^}]*)$/;
+
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+      if (coveredRanges.some(([start, end]) => lineIdx >= start && lineIdx <= end)) continue;
+
+      const line = lines[lineIdx]!;
+      const exprs: Array<{ text: string; offset: number }> = [];
+
+      let exprMatch;
+      while ((exprMatch = exprRegex.exec(line)) !== null) {
+        exprs.push({ text: exprMatch[1]!, offset: exprMatch.index });
+      }
+      const openMatch = openExprRegex.exec(line.replace(exprRegex, ''));
+      if (openMatch) {
+        exprs.push({ text: openMatch[1]!, offset: line.lastIndexOf('{') });
+      }
+
+      for (const expr of exprs) {
+        // Extract function calls: identifiers followed by (
+        // Matches: cn(...), formatDate(...), obj.method(...)
+        const callRegex = /\b([a-zA-Z_$][\w$.]*)\s*\(/g;
+        let callMatch;
+        while ((callMatch = callRegex.exec(expr.text)) !== null) {
+          const calleeName = callMatch[1]!;
+          // Skip control-flow keywords valid inside expressions
+          if (calleeName === 'if' || calleeName === 'await' || calleeName === 'function') continue;
+
+          this.unresolvedReferences.push({
+            fromNodeId: componentNodeId,
+            referenceName: calleeName,
+            referenceKind: 'calls',
+            line: lineIdx + 1, // 1-indexed
+            column: expr.offset + callMatch.index,
+            filePath: this.filePath,
+            language: 'astro',
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Extract component usages from the Astro template.
+   *
+   * PascalCase tags like <Layout>, <PostCard /> represent component
+   * instantiations — analogous to function calls in imperative code.
+   * Lowercase tags are native HTML (Astro does not register kebab-case
+   * components the way Vue does, so those are real custom elements and
+   * are skipped).
+   */
+  private extractTemplateComponents(
+    componentNodeId: string,
+    coveredRanges: Array<[number, number]>
+  ): void {
+    const lines = this.source.split('\n');
+    // Opening/self-closing tags (closing tags </Foo> start with </ so won't match)
+    const componentTagRegex = /<([A-Z][a-zA-Z0-9_$]*)\b/g;
+
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+      if (coveredRanges.some(([start, end]) => lineIdx >= start && lineIdx <= end)) continue;
+
+      const line = lines[lineIdx]!;
+      let match;
+      while ((match = componentTagRegex.exec(line)) !== null) {
+        const componentName = match[1]!;
+        if (ASTRO_BUILTIN_COMPONENTS.has(componentName)) continue;
+
+        this.unresolvedReferences.push({
+          fromNodeId: componentNodeId,
+          referenceName: componentName,
+          referenceKind: 'references',
+          line: lineIdx + 1, // 1-indexed
+          column: match.index + 1,
+          filePath: this.filePath,
+          language: 'astro',
+        });
+      }
+    }
+  }
+}

src/extraction/grammars.ts

@@ -10,7 +10,7 @@ import * as path from 'path';
 import { Parser, Language as WasmLanguage } from 'web-tree-sitter';
 import { Language } from '../types';
 
-export type GrammarLanguage = Exclude<Language, 'svelte' | 'vue' | 'liquid' | 'razor' | 'yaml' | 'twig' | 'xml' | 'properties' | 'unknown'>;
+export type GrammarLanguage = Exclude<Language, 'svelte' | 'vue' | 'astro' | 'liquid' | 'razor' | 'yaml' | 'twig' | 'xml' | 'properties' | 'unknown'>;
 
 /**
  * WASM filename map — maps each language to its .wasm grammar file
@@ -93,6 +93,7 @@ export const EXTENSION_MAP: Record<string, Language> = {
   '.liquid': 'liquid',
   '.svelte': 'svelte',
   '.vue': 'vue',
+  '.astro': 'astro',
   '.pas': 'pascal',
   '.dpr': 'pascal',
   '.dpk': 'pascal',
@@ -183,6 +184,14 @@ export async function loadGrammarsForLanguages(languages: Language[]): Promise<v
     await initGrammars();
   }
 
+  // SFC languages (svelte/vue/astro) have no grammar of their own — their
+  // extractors delegate <script>/frontmatter content to the TS/JS extractor,
+  // so those grammars must be loaded even when no plain .ts/.js file is in
+  // the index set (e.g. a pure-.astro content site).
+  if (languages.some((l) => l === 'svelte' || l === 'vue' || l === 'astro')) {
+    languages = [...languages, 'typescript', 'javascript'];
+  }
+
   // Deduplicate and filter to languages that have WASM grammars and aren't already loaded
   const toLoad = [...new Set(languages)].filter(
     (lang): lang is GrammarLanguage =>
@@ -300,6 +309,7 @@ function looksLikeObjc(source: string): boolean {
 export function isLanguageSupported(language: Language): boolean {
   if (language === 'svelte') return true; // custom extractor (script block delegation)
   if (language === 'vue') return true; // custom extractor (script block delegation)
+  if (language === 'astro') return true; // custom extractor (frontmatter/script block delegation)
   if (language === 'liquid') return true; // custom regex extractor
   if (language === 'razor') return true; // custom RazorExtractor (.cshtml/.razor markup)
   if (language === 'yaml') return true; // file-level tracking only; Drupal routing extraction via framework resolver
@@ -314,7 +324,7 @@ export function isLanguageSupported(language: Language): boolean {
  * Check if a grammar has been loaded and is ready for parsing.
  */
 export function isGrammarLoaded(language: Language): boolean {
-  if (language === 'svelte' || language === 'vue' || language === 'liquid' || language === 'razor') return true;
+  if (language === 'svelte' || language === 'vue' || language === 'astro' || language === 'liquid' || language === 'razor') return true;
   if (language === 'yaml' || language === 'twig') return true; // no WASM grammar needed
   if (language === 'xml' || language === 'properties') return true; // no WASM grammar needed
   return languageCache.has(language);
@@ -337,7 +347,7 @@ export function isFileLevelOnlyLanguage(language: Language): boolean {
  * Get all supported languages (those with grammar definitions).
  */
 export function getSupportedLanguages(): Language[] {
-  return [...(Object.keys(WASM_GRAMMAR_FILES) as GrammarLanguage[]), 'svelte', 'vue', 'liquid'];
+  return [...(Object.keys(WASM_GRAMMAR_FILES) as GrammarLanguage[]), 'svelte', 'vue', 'astro', 'liquid'];
 }
 
 /**
@@ -403,6 +413,7 @@ export function getLanguageDisplayName(language: Language): string {
     dart: 'Dart',
     svelte: 'Svelte',
     vue: 'Vue',
+    astro: 'Astro',
     liquid: 'Liquid',
     pascal: 'Pascal / Delphi',
     scala: 'Scala',

src/extraction/svelte-extractor.ts

@@ -135,13 +135,16 @@ export class SvelteExtractor {
       // Detect module script
       const isModule = /context\s*=\s*["']module["']/.test(attrs);
 
-      // Calculate start line of the script content (line after <script>)
+      // Calculate the 0-indexed line where the content begins. The content
+      // starts right after the opening tag's `>` — its leading `\n` is part
+      // of the content, so relative line 1 sits ON the tag's closing line
+      // (adding 1 here double-counted the embedded newline and shifted every
+      // script-block symbol down a line).
       const beforeScript = this.source.substring(0, match.index);
       const scriptTagLine = (beforeScript.match(/\n/g) || []).length;
-      // The content starts on the line after the opening <script> tag
       const openingTag = match[0].substring(0, match[0].indexOf('>') + 1);
       const openingTagLines = (openingTag.match(/\n/g) || []).length;
-      const contentStartLine = scriptTagLine + openingTagLines + 1; // 0-indexed line
+      const contentStartLine = scriptTagLine + openingTagLines; // 0-indexed line
 
       blocks.push({
         content,

src/extraction/tree-sitter.ts

@@ -24,6 +24,7 @@ import { EXTRACTORS } from './languages';
 import { LiquidExtractor } from './liquid-extractor';
 import { RazorExtractor } from './razor-extractor';
 import { SvelteExtractor } from './svelte-extractor';
+import { AstroExtractor } from './astro-extractor';
 import { DfmExtractor } from './dfm-extractor';
 import { VueExtractor } from './vue-extractor';
 import { MyBatisExtractor } from './mybatis-extractor';
@@ -4752,6 +4753,10 @@ export function extractFromSource(
     // Use custom extractor for Vue
     const extractor = new VueExtractor(filePath, source);
     result = extractor.extract();
+  } else if (detectedLanguage === 'astro') {
+    // Use custom extractor for Astro (frontmatter + template delegation)
+    const extractor = new AstroExtractor(filePath, source);
+    result = extractor.extract();
   } else if (detectedLanguage === 'liquid') {
     // Use custom extractor for Liquid
     const extractor = new LiquidExtractor(filePath, source);

src/extraction/vue-extractor.ts

@@ -143,13 +143,16 @@ export class VueExtractor {
       // Detect <script setup>
       const isSetup = /\bsetup\b/.test(attrs);
 
-      // Calculate start line of the script content (line after <script>)
+      // Calculate the 0-indexed line where the content begins. The content
+      // starts right after the opening tag's `>` — its leading `\n` is part
+      // of the content, so relative line 1 sits ON the tag's closing line
+      // (adding 1 here double-counted the embedded newline and shifted every
+      // script-block symbol down a line).
       const beforeScript = this.source.substring(0, match.index);
       const scriptTagLine = (beforeScript.match(/\n/g) || []).length;
-      // The content starts on the line after the opening <script> tag
       const openingTag = match[0].substring(0, match[0].indexOf('>') + 1);
       const openingTagLines = (openingTag.match(/\n/g) || []).length;
-      const contentStartLine = scriptTagLine + openingTagLines + 1; // 0-indexed line
+      const contentStartLine = scriptTagLine + openingTagLines; // 0-indexed line
 
       blocks.push({
         content,

src/mcp/tools.ts

@@ -1446,7 +1446,7 @@ export class ToolHandler {
       // names (Class.method / Class::method) — the agent's most precise input,
       // resolved exactly by findAllSymbols. (The old strip mangled Class.method
       // into Class, throwing the method away.)
-      const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte)$/i;
+      const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte|astro)$/i;
       const tokens = [...new Set(
         query.split(/[\s,()[\]]+/)
           .map((t) => t.replace(FILE_EXT, '').trim())
@@ -1794,7 +1794,7 @@ export class ToolHandler {
     // agent explicitly named is in the subgraph and its file is scored.
     const namedSeedIds = new Set<string>();
     {
-      const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte)$/i;
+      const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte|astro)$/i;
       const CALLABLE = new Set(['method', 'function', 'component', 'constructor']);
       const isTestPath = (p: string) => /(^|\/)(tests?|specs?|__tests__|testdata|mocks?|fixtures?)\//i.test(p) || /\.(test|spec)\.[a-z]+$/i.test(p);
       const bodyLines = (n: Node) => Math.max(0, (n.endLine ?? n.startLine) - n.startLine);

src/resolution/frameworks/astro.ts

@@ -0,0 +1,195 @@
+/**
+ * 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(/\/$/, '');
+}

src/resolution/frameworks/index.ts

@@ -13,6 +13,7 @@ import { nestjsResolver } from './nestjs';
 import { reactResolver } from './react';
 import { svelteResolver } from './svelte';
 import { vueResolver } from './vue';
+import { astroResolver } from './astro';
 import { djangoResolver, flaskResolver, fastapiResolver } from './python';
 import { railsResolver } from './ruby';
 import { springResolver } from './java';
@@ -39,6 +40,7 @@ const FRAMEWORK_RESOLVERS: FrameworkResolver[] = [
   reactResolver,
   svelteResolver,
   vueResolver,
+  astroResolver,
   // Python
   djangoResolver,
   flaskResolver,
@@ -128,6 +130,7 @@ export { nestjsResolver } from './nestjs';
 export { reactResolver } from './react';
 export { svelteResolver } from './svelte';
 export { vueResolver } from './vue';
+export { astroResolver } from './astro';
 export { djangoResolver, flaskResolver, fastapiResolver } from './python';
 export { railsResolver } from './ruby';
 export { springResolver } from './java';

src/resolution/import-resolver.ts

@@ -24,6 +24,7 @@ const EXTENSION_RESOLUTION: Record<string, string[]> = {
   // `.svelte`/`.vue` file resolve to nothing, so barrel callers vanish (#629).
   svelte: ['.ts', '.js', '.svelte', '.tsx', '.jsx', '/index.ts', '/index.js', '/index.svelte'],
   vue: ['.ts', '.js', '.vue', '.tsx', '.jsx', '/index.ts', '/index.js', '/index.vue'],
+  astro: ['.ts', '.js', '.astro', '.tsx', '.jsx', '/index.ts', '/index.js', '/index.astro'],
   python: ['.py', '/__init__.py'],
   go: ['.go'],
   rust: ['.rs', '/mod.rs'],
@@ -582,9 +583,10 @@ export function extractImportMappings(
 
   if (language === 'typescript' || language === 'javascript' || language === 'tsx' || language === 'jsx') {
     mappings.push(...extractJSImports(content));
-  } else if (language === 'svelte' || language === 'vue') {
+  } else if (language === 'svelte' || language === 'vue' || language === 'astro') {
     // Svelte/Vue single-file components import via plain ES6 inside their
-    // `<script>` block. Without this, a `.svelte`/`.vue` consumer produces
+    // `<script>` block (Astro: the `---` frontmatter). Without this, a
+    // `.svelte`/`.vue`/`.astro` consumer produces
     // zero import mappings, so `resolveViaImport` can't run and a barrel
     // import (`import { Foo } from './lib'`) falls back to name-matching —
     // which silently fails whenever the re-export alias differs from the

src/types.ts

@@ -83,6 +83,7 @@ export const LANGUAGES = [
   'dart',
   'svelte',
   'vue',
+  'astro',
   'liquid',
   'pascal',
   'scala',