@upstart.gg/vite-plugins 0.1.60 → 0.1.62

package/src/page-meta.ts

@@ -0,0 +1,678 @@
+import { parseSync } from "oxc-parser";
+
+/**
+ * Static analysis of a route module's page metadata (browser-tab title, description,
+ * keywords, robots indexing).
+ *
+ * Routes generated by the AI assistant render their meta with React 19's native hoisting
+ * and take the text from i18next, e.g.:
+ *
+ *     export async function loader({ context }) {
+ *       const i18n = getInstance(context);
+ *       return { title: i18n.t("about.meta.title"), description: i18n.t("about.meta.description") };
+ *     }
+ *     export default function AboutPage({ loaderData }) {
+ *       const { title, description } = loaderData;
+ *       return (<><title>{title}</title><meta name="description" content={description} />…
+ *
+ * so editing "the page title" really means editing a translation key. This module resolves
+ * each meta value back to its origin — an i18n key, a plain string literal, or something we
+ * refuse to touch — and locates the byte ranges the editor needs to rewrite.
+ */
+
+export interface AstNode {
+  type: string;
+  start: number;
+  end: number;
+  [key: string]: unknown;
+}
+
+/** Where a meta value ultimately comes from. */
+export type MetaValueOrigin =
+  /** `i18n.t("key")` in the route's loader — the text lives in the locale files. */
+  | {
+      kind: "i18n";
+      key: string;
+      namespace: string;
+      /** Bounds of the key string, quotes excluded, so it can be repointed to another key. */
+      keyStart: number;
+      keyEnd: number;
+    }
+  /** A string literal in the source (JSX attribute, JSX text or loader value). */
+  | { kind: "literal"; start: number; end: number; value: string; quote: string }
+  /** The element is not in the route at all. */
+  | { kind: "absent" }
+  /**
+   * A prop of the component being analyzed. Only produced while looking inside a shared
+   * SEO component; the caller substitutes the value the route passes for it.
+   */
+  | { kind: "prop"; name: string }
+  /** Computed at runtime (database row, several keys combined…) — read-only. */
+  | { kind: "unsupported"; reason: string };
+
+/**
+ * A piece of a composed value: either literal text from the template, or another dynamic
+ * part that the caller resolves for display (e.g. the site name appended to every title).
+ */
+export type MetaSegment = { text: string } | { origin: MetaValueOrigin };
+
+export interface MetaElement {
+  origin: MetaValueOrigin;
+  /** What is rendered around the editable part, e.g. `{`${title} - ${tagline}`}`. */
+  prefixSegments: MetaSegment[];
+  suffixSegments: MetaSegment[];
+  /** Bounds of the whole JSX element, when the route has one. */
+  elementStart?: number;
+  elementEnd?: number;
+}
+
+export interface RouteMetaAnalysis {
+  title: MetaElement;
+  description: MetaElement;
+  keywords: MetaElement;
+  robots: MetaElement;
+  /** True when the route renders at least one meta element as JSX. */
+  hasJsxMeta: boolean;
+  /**
+   * Offset a new `<meta …/>` sibling can be inserted at (right after the last existing
+   * meta element), plus the indentation of the line it sits on.
+   */
+  insertOffset: number | null;
+  insertIndent: string;
+}
+
+const ABSENT: MetaElement = { origin: { kind: "absent" }, prefixSegments: [], suffixSegments: [] };
+
+function walk(node: unknown, visit: (n: AstNode) => void): void {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visit);
+    return;
+  }
+  const n = node as AstNode;
+  if (typeof n.type === "string") visit(n);
+  for (const key in n) {
+    if (key === "type" || key === "start" || key === "end") continue;
+    const value = n[key];
+    if (value && typeof value === "object") walk(value, visit);
+  }
+}
+
+/** Value of a JSX attribute that is a plain string, e.g. `name="description"`. */
+function jsxAttributeString(element: AstNode, attributeName: string): string | null {
+  const opening = element.openingElement as AstNode | undefined;
+  for (const attr of (opening?.attributes as AstNode[]) ?? []) {
+    if (attr.type !== "JSXAttribute") continue;
+    const name = attr.name as AstNode;
+    if (name?.type !== "JSXIdentifier" || name.name !== attributeName) continue;
+    const value = attr.value as AstNode | null;
+    if (value?.type === "Literal" && typeof value.value === "string") return value.value;
+    return null;
+  }
+  return null;
+}
+
+function jsxAttributeNode(element: AstNode, attributeName: string): AstNode | null {
+  const opening = element.openingElement as AstNode | undefined;
+  for (const attr of (opening?.attributes as AstNode[]) ?? []) {
+    if (attr.type !== "JSXAttribute") continue;
+    const name = attr.name as AstNode;
+    if (name?.type === "JSXIdentifier" && name.name === attributeName) return attr;
+  }
+  return null;
+}
+
+/** A string literal node → an editable origin covering the text between its quotes. */
+function literalOrigin(code: string, node: AstNode): MetaValueOrigin {
+  const quote = code[node.start];
+  const quoted = quote === '"' || quote === "'" || quote === "`";
+  return {
+    kind: "literal",
+    start: quoted ? node.start + 1 : node.start,
+    end: quoted ? node.end - 1 : node.end,
+    value: node.value as string,
+    quote: quoted ? quote : '"',
+  };
+}
+
+/**
+ * Read `t("key")` / `i18n.t("ns:key", { ns })`. Returns null when the call is not a
+ * translation lookup we can address (dynamic key, interpolated values…).
+ */
+function readTranslationCall(node: AstNode): MetaValueOrigin | null {
+  if (node.type !== "CallExpression") return null;
+  const callee = node.callee as AstNode;
+  const isT =
+    (callee.type === "Identifier" && callee.name === "t") ||
+    (callee.type === "MemberExpression" &&
+      !callee.computed &&
+      (callee.property as AstNode)?.type === "Identifier" &&
+      ((callee.property as AstNode).name as string) === "t");
+  if (!isT) return null;
+
+  const args = (node.arguments as AstNode[]) ?? [];
+  const first = args[0];
+  if (first?.type !== "Literal" || typeof first.value !== "string") return null;
+
+  let namespace = "translation";
+  let key = first.value;
+  const colon = key.indexOf(":");
+  if (colon > 0) {
+    namespace = key.slice(0, colon);
+    key = key.slice(colon + 1);
+  }
+  // A second argument is only acceptable when it merely selects the namespace: anything
+  // else (interpolation values, counts) means the stored string is not what is displayed.
+  const second = args[1];
+  if (second) {
+    if (second.type !== "ObjectExpression") return null;
+    const props = (second.properties as AstNode[]) ?? [];
+    if (props.length !== 1) return null;
+    const prop = props[0];
+    if (prop.type !== "Property" || prop.computed) return null;
+    const propKey = prop.key as AstNode;
+    const propValue = prop.value as AstNode;
+    const propName = propKey.type === "Identifier" ? propKey.name : propKey.value;
+    if (propName !== "ns" || propValue.type !== "Literal" || typeof propValue.value !== "string") {
+      return null;
+    }
+    namespace = propValue.value;
+  }
+
+  return { kind: "i18n", key, namespace, keyStart: first.start + 1, keyEnd: first.end - 1 };
+}
+
+interface TraceContext {
+  code: string;
+  program: AstNode;
+  /**
+   * "route": identifiers come from the loader through `loaderData`.
+   * "component": identifiers are local constants or props of the component itself.
+   */
+  mode: "route" | "component";
+}
+
+/** Initializer of a plain `const x = …` declaration, when the module has one. */
+function localDeclaration(ctx: TraceContext, identifier: string): AstNode | null {
+  let found: AstNode | null = null;
+  walk(ctx.program, (node) => {
+    if (found || node.type !== "VariableDeclarator") return;
+    const id = node.id as AstNode;
+    if (id?.type === "Identifier" && id.name === identifier) found = (node.init as AstNode) ?? null;
+  });
+  return found;
+}
+
+/** The key an object pattern binds to `identifier`, following `{ a: b }` and `{ a = 1 }`. */
+function patternKeyFor(pattern: AstNode, identifier: string): string | null {
+  for (const prop of (pattern.properties as AstNode[]) ?? []) {
+    if (prop.type !== "Property") continue;
+    const key = prop.key as AstNode;
+    let value = prop.value as AstNode;
+    // `{ image = "/default.png" }` binds through an assignment pattern.
+    if (value?.type === "AssignmentPattern") value = value.left as AstNode;
+    if (value?.type === "Identifier" && value.name === identifier && key?.type === "Identifier") {
+      return key.name as string;
+    }
+  }
+  return null;
+}
+
+/** Property name an identifier was destructured from, e.g. `const { title } = loaderData`. */
+function destructuredSourceName(ctx: TraceContext, identifier: string): string | null {
+  let found: string | null = null;
+  walk(ctx.program, (node) => {
+    if (found || node.type !== "VariableDeclarator") return;
+    const id = node.id as AstNode;
+    if (id?.type !== "ObjectPattern") return;
+    found = patternKeyFor(id, identifier);
+  });
+  return found;
+}
+
+/**
+ * Prop name an identifier is bound to by a component's signature, e.g.
+ * `function SeoHead({ title }: Props)`. Props arrive as a parameter pattern, not as a
+ * variable declaration, so they need their own lookup.
+ */
+function parameterPropName(ctx: TraceContext, identifier: string): string | null {
+  let found: string | null = null;
+  walk(ctx.program, (node) => {
+    if (found) return;
+    if (
+      node.type !== "FunctionDeclaration" &&
+      node.type !== "ArrowFunctionExpression" &&
+      node.type !== "FunctionExpression"
+    ) {
+      return;
+    }
+    const first = ((node.params as AstNode[]) ?? [])[0];
+    if (first?.type === "ObjectPattern") found = patternKeyFor(first, identifier);
+  });
+  return found;
+}
+
+/** The route's exported `loader` function, whatever declaration form it uses. */
+function findLoader(ctx: TraceContext): AstNode | null {
+  const body = (ctx.program.body as AstNode[]) ?? [];
+  for (const statement of body) {
+    if (statement.type !== "ExportNamedDeclaration") continue;
+    const declaration = statement.declaration as AstNode | null;
+    if (!declaration) continue;
+    if (declaration.type === "FunctionDeclaration") {
+      const id = declaration.id as AstNode | null;
+      if (id?.type === "Identifier" && id.name === "loader") return declaration;
+    } else if (declaration.type === "VariableDeclaration") {
+      for (const decl of (declaration.declarations as AstNode[]) ?? []) {
+        const id = decl.id as AstNode;
+        if (id?.type === "Identifier" && id.name === "loader") return (decl.init as AstNode) ?? null;
+      }
+    }
+  }
+  return null;
+}
+
+/** Value the loader returns for `propertyName`, across every `return { … }` it contains. */
+function loaderReturnValue(loader: AstNode, propertyName: string): AstNode | null {
+  let found: AstNode | null = null;
+  walk(loader, (node) => {
+    if (found || node.type !== "ReturnStatement") return;
+    const argument = node.argument as AstNode | null;
+    if (argument?.type !== "ObjectExpression") return;
+    for (const prop of (argument.properties as AstNode[]) ?? []) {
+      if (prop.type !== "Property" || prop.computed) continue;
+      const key = prop.key as AstNode;
+      const name = key?.type === "Identifier" ? key.name : key?.type === "Literal" ? key.value : null;
+      if (name === propertyName) {
+        found = prop.value as AstNode;
+        return;
+      }
+    }
+  });
+  return found;
+}
+
+const unsupportedElement = (reason: string): MetaElement => ({
+  origin: { kind: "unsupported", reason },
+  prefixSegments: [],
+  suffixSegments: [],
+});
+
+/**
+ * Follow a component identifier back to the loader value that feeds it. The loader may
+ * itself compose several translations, so this returns a full element rather than a single
+ * origin.
+ */
+function traceIdentifier(ctx: TraceContext, identifier: string, depth: number): MetaElement {
+  // Guards against a self-referencing declaration chain.
+  if (depth > 4) return unsupportedElement("This value is computed by code");
+
+  // `const fullTitle = `${title} — Acme`` and friends.
+  const local = localDeclaration(ctx, identifier);
+  if (local) return resolveExpression(ctx, local, depth + 1);
+
+  // Inside a shared SEO component the value is a prop: hand it back to the caller, which
+  // knows what the route passes for it.
+  if (ctx.mode === "component") {
+    const propName = parameterPropName(ctx, identifier) ?? destructuredSourceName(ctx, identifier);
+    if (!propName) return unsupportedElement("This value is computed by code");
+    return { origin: { kind: "prop", name: propName }, prefixSegments: [], suffixSegments: [] };
+  }
+
+  const sourceName = destructuredSourceName(ctx, identifier);
+  if (!sourceName) return unsupportedElement("This value is computed by code");
+
+  const loader = findLoader(ctx);
+  if (!loader) return unsupportedElement("This value is computed by code");
+  const value = loaderReturnValue(loader, sourceName);
+  if (!value) return unsupportedElement("This value is computed by code");
+
+  const translation = readTranslationCall(value);
+  if (translation) return { origin: translation, prefixSegments: [], suffixSegments: [] };
+  if (value.type === "Literal" && typeof value.value === "string") {
+    return { origin: literalOrigin(ctx.code, value), prefixSegments: [], suffixSegments: [] };
+  }
+  if (value.type === "TemplateLiteral") return resolveExpression(ctx, value, depth + 1);
+  return unsupportedElement("This value is built from other content");
+}
+
+/** Resolve any expression used as a meta value, keeping the read-only parts around it. */
+function resolveExpression(ctx: TraceContext, expression: AstNode, depth = 0): MetaElement {
+  if (expression.type === "Literal" && typeof expression.value === "string") {
+    return { origin: literalOrigin(ctx.code, expression), prefixSegments: [], suffixSegments: [] };
+  }
+  if (expression.type === "Identifier") {
+    return traceIdentifier(ctx, expression.name as string, depth);
+  }
+  // `i18n.t("key")` used inline, e.g. in a title composed inside the loader.
+  const translation = readTranslationCall(expression);
+  if (translation) return { origin: translation, prefixSegments: [], suffixSegments: [] };
+  if (expression.type === "TemplateLiteral") {
+    const quasis = (expression.quasis as AstNode[]) ?? [];
+    const expressions = (expression.expressions as AstNode[]) ?? [];
+    if (expressions.length === 0 && quasis.length === 1) {
+      const quasi = quasis[0];
+      const cooked = (quasi.value as { cooked?: string })?.cooked ?? "";
+      return {
+        origin: { kind: "literal", start: quasi.start, end: quasi.end, value: cooked, quote: "`" },
+        prefixSegments: [],
+        suffixSegments: [],
+      };
+    }
+
+    // Interleave the literal chunks with the interpolated values, then take the first part
+    // we can actually address as the editable one. A title built from several translations
+    // (`${pageTitle} - ${siteTagline}`) still has one part that belongs to this page; the
+    // rest becomes read-only context so the user sees the whole rendered string.
+    const segments: MetaSegment[] = [];
+    quasis.forEach((quasi, index) => {
+      segments.push({ text: (quasi.value as { cooked?: string })?.cooked ?? "" });
+      const interpolated = expressions[index];
+      if (!interpolated) return;
+      // Each interpolation can itself be composed — flatten its own parts in place.
+      const resolved = resolveExpression(ctx, interpolated, depth + 1);
+      segments.push(...resolved.prefixSegments, { origin: resolved.origin }, ...resolved.suffixSegments);
+    });
+
+    const editableAt = segments.findIndex(
+      (segment) =>
+        "origin" in segment &&
+        (segment.origin.kind === "i18n" ||
+          segment.origin.kind === "literal" ||
+          segment.origin.kind === "prop"),
+    );
+    if (editableAt === -1) {
+      return {
+        origin: { kind: "unsupported", reason: "This value is computed by code" },
+        prefixSegments: [],
+        suffixSegments: [],
+      };
+    }
+    return {
+      origin: (segments[editableAt] as { origin: MetaValueOrigin }).origin,
+      prefixSegments: segments.slice(0, editableAt),
+      suffixSegments: segments.slice(editableAt + 1),
+    };
+  }
+  return {
+    origin: { kind: "unsupported", reason: "This value is computed by code" },
+    prefixSegments: [],
+    suffixSegments: [],
+  };
+}
+
+/** Read `<title>…</title>` children. */
+function analyzeTitleElement(ctx: TraceContext, element: AstNode): MetaElement {
+  const children = ((element.children as AstNode[]) ?? []).filter(
+    (child) => child.type !== "JSXText" || String(child.value ?? "").trim() !== "",
+  );
+  if (children.length === 1) {
+    const child = children[0];
+    if (child.type === "JSXText") {
+      return {
+        origin: {
+          kind: "literal",
+          start: child.start,
+          end: child.end,
+          value: String(child.value ?? ""),
+          quote: '"',
+        },
+        prefixSegments: [],
+        suffixSegments: [],
+      };
+    }
+    if (child.type === "JSXExpressionContainer") {
+      return resolveExpression(ctx, child.expression as AstNode);
+    }
+  }
+  return {
+    origin: { kind: "unsupported", reason: "This title is computed by code" },
+    prefixSegments: [],
+    suffixSegments: [],
+  };
+}
+
+/** Read the `content` attribute of a `<meta …/>` element. */
+function analyzeMetaElement(ctx: TraceContext, element: AstNode): MetaElement {
+  const attribute = jsxAttributeNode(element, "content");
+  const value = attribute?.value as AstNode | null | undefined;
+  if (!value) {
+    return {
+      origin: { kind: "unsupported", reason: "This tag has no content" },
+      prefixSegments: [],
+      suffixSegments: [],
+    };
+  }
+  if (value.type === "Literal" && typeof value.value === "string") {
+    return { origin: literalOrigin(ctx.code, value), prefixSegments: [], suffixSegments: [] };
+  }
+  if (value.type === "JSXExpressionContainer") {
+    return resolveExpression(ctx, value.expression as AstNode);
+  }
+  return {
+    origin: { kind: "unsupported", reason: "This value is computed by code" },
+    prefixSegments: [],
+    suffixSegments: [],
+  };
+}
+
+/**
+ * Locate and resolve the four meta values a route can render as JSX.
+ */
+
+/** Import specifier a local identifier (a component name) was imported from. */
+function importSpecifierOf(program: AstNode, name: string): string | null {
+  for (const statement of (program.body as AstNode[]) ?? []) {
+    if (statement.type !== "ImportDeclaration") continue;
+    for (const spec of (statement.specifiers as AstNode[]) ?? []) {
+      const local = spec.local as AstNode | undefined;
+      if (local?.type === "Identifier" && local.name === name) {
+        const source = statement.source as AstNode;
+        return typeof source?.value === "string" ? source.value : null;
+      }
+    }
+  }
+  return null;
+}
+
+/** JSX attributes of an element, by name, ignoring spreads. */
+function jsxAttributes(element: AstNode): Map<string, AstNode> {
+  const attributes = new Map<string, AstNode>();
+  const opening = element.openingElement as AstNode | undefined;
+  for (const attr of (opening?.attributes as AstNode[]) ?? []) {
+    if (attr.type !== "JSXAttribute") continue;
+    const name = attr.name as AstNode;
+    if (name?.type === "JSXIdentifier") attributes.set(name.name as string, attr);
+  }
+  return attributes;
+}
+
+/** Rendered components, in source order, that could stand in for the meta tags. */
+function findComponentElements(program: AstNode): AstNode[] {
+  const found: AstNode[] = [];
+  walk(program, (node) => {
+    if (node.type !== "JSXElement") return;
+    const name = (node.openingElement as AstNode)?.name as AstNode | undefined;
+    // Components are capitalized; lowercase names are plain HTML tags.
+    if (name?.type === "JSXIdentifier" && /^[A-Z]/.test(name.name as string)) found.push(node);
+  });
+  return found;
+}
+
+/**
+ * Resolve the value the route passes for one of the component's props. The value is read in
+ * the ROUTE's context, so a prop fed by the loader still resolves to its translation key.
+ */
+function resolveProp(routeCtx: TraceContext, attributes: Map<string, AstNode>, name: string): MetaElement {
+  const attribute = attributes.get(name);
+  const value = attribute?.value as AstNode | null | undefined;
+  if (!value) return unsupportedElement("This value is set by the page's SEO component");
+  if (value.type === "Literal" && typeof value.value === "string") {
+    return { origin: literalOrigin(routeCtx.code, value), prefixSegments: [], suffixSegments: [] };
+  }
+  if (value.type === "JSXExpressionContainer") {
+    return resolveExpression(routeCtx, value.expression as AstNode, 0);
+  }
+  return unsupportedElement("This value is computed by code");
+}
+
+/** Replace every `prop` origin with what the route passes, keeping the surrounding parts. */
+function substituteProps(
+  element: MetaElement,
+  routeCtx: TraceContext,
+  attributes: Map<string, AstNode>,
+): MetaElement {
+  const substituteSegments = (segments: MetaSegment[]): MetaSegment[] =>
+    segments.flatMap((segment) => {
+      if (!("origin" in segment) || segment.origin.kind !== "prop") return [segment];
+      const resolved = resolveProp(routeCtx, attributes, segment.origin.name);
+      return [...resolved.prefixSegments, { origin: resolved.origin }, ...resolved.suffixSegments];
+    });
+
+  const prefixSegments = substituteSegments(element.prefixSegments);
+  const suffixSegments = substituteSegments(element.suffixSegments);
+
+  if (element.origin.kind !== "prop") {
+    // The value lives in the shared component, so it is the same on every page: showing it
+    // as editable here would silently rewrite the whole site.
+    const origin: MetaValueOrigin =
+      element.origin.kind === "literal"
+        ? { kind: "unsupported", reason: "This text comes from the page's SEO component" }
+        : element.origin;
+    return { ...element, origin, prefixSegments, suffixSegments };
+  }
+
+  const resolved = resolveProp(routeCtx, attributes, element.origin.name);
+  return {
+    ...element,
+    origin: resolved.origin,
+    prefixSegments: [...prefixSegments, ...resolved.prefixSegments],
+    suffixSegments: [...resolved.suffixSegments, ...suffixSegments],
+  };
+}
+
+/**
+ * Follow a component the route delegates its metadata to, and express its meta values in
+ * terms of what the route passes it.
+ */
+function analyzeDelegate(
+  routeCtx: TraceContext,
+  program: AstNode,
+  loadModule: ModuleLoader,
+): RouteMetaAnalysis | null {
+  for (const element of findComponentElements(program)) {
+    const componentName = ((element.openingElement as AstNode).name as AstNode).name as string;
+    const specifier = importSpecifierOf(program, componentName);
+    if (!specifier) continue;
+    const module = loadModule(specifier);
+    if (!module) continue;
+
+    const moduleProgram = parseSync(module.filePath, module.code, { sourceType: "module" })
+      .program as unknown as AstNode;
+    const moduleElements = findMetaElements(moduleProgram);
+    if (!moduleElements.title && !moduleElements.description) continue;
+
+    const moduleCtx: TraceContext = { code: module.code, program: moduleProgram, mode: "component" };
+    const attributes = jsxAttributes(element);
+    const read = (
+      node: AstNode | undefined,
+      analyze: (ctx: TraceContext, el: AstNode) => MetaElement,
+    ): MetaElement => (node ? substituteProps(analyze(moduleCtx, node), routeCtx, attributes) : ABSENT);
+
+    // Keywords and robots are page-specific, so they are read from — and written to — the
+    // route itself, next to the component, rather than to the shared component.
+    const routeElements = findMetaElements(program);
+    const routeRead = (node: AstNode | undefined): MetaElement =>
+      node
+        ? { ...analyzeMetaElement(routeCtx, node), elementStart: node.start, elementEnd: node.end }
+        : ABSENT;
+
+    const lineStart = routeCtx.code.lastIndexOf("\n", element.start) + 1;
+    return {
+      title: read(moduleElements.title, analyzeTitleElement),
+      description: read(moduleElements.description, analyzeMetaElement),
+      keywords: routeRead(routeElements.keywords),
+      robots: routeRead(routeElements.robots),
+      hasJsxMeta: true,
+      insertOffset: element.end,
+      insertIndent: routeCtx.code.slice(lineStart, element.start).match(/^[ \t]*/)?.[0] ?? "",
+    };
+  }
+  return null;
+}
+
+/** The four meta elements a module renders, if any. */
+function findMetaElements(program: AstNode) {
+  const elements: Partial<Record<"title" | "description" | "keywords" | "robots", AstNode>> = {};
+  walk(program, (node) => {
+    if (node.type !== "JSXElement") return;
+    const name = (node.openingElement as AstNode)?.name as AstNode | undefined;
+    if (name?.type !== "JSXIdentifier") return;
+    if (name.name === "title") {
+      elements.title ??= node;
+      return;
+    }
+    if (name.name !== "meta") return;
+    const metaName = jsxAttributeString(node, "name");
+    if (metaName === "description" || metaName === "keywords" || metaName === "robots") {
+      elements[metaName] ??= node;
+    }
+  });
+  return elements;
+}
+
+/** Reads a module (by import specifier) so a shared SEO component can be followed. */
+export type ModuleLoader = (specifier: string) => { code: string; filePath: string } | null;
+
+export function analyzeRouteMeta(
+  code: string,
+  filePath: string,
+  loadModule?: ModuleLoader,
+): RouteMetaAnalysis {
+  const ast = parseSync(filePath, code, { sourceType: "module" });
+  const program = ast.program as unknown as AstNode;
+  const ctx: TraceContext = { code, program, mode: "route" };
+
+  const elements = findMetaElements(program);
+
+  const build = (
+    node: AstNode | undefined,
+    read: (ctx: TraceContext, element: AstNode) => MetaElement,
+  ): MetaElement => {
+    if (!node) return ABSENT;
+    return { ...read(ctx, node), elementStart: node.start, elementEnd: node.end };
+  };
+
+  const title = build(elements.title, analyzeTitleElement);
+  const description = build(elements.description, analyzeMetaElement);
+  const keywords = build(elements.keywords, analyzeMetaElement);
+  const robots = build(elements.robots, analyzeMetaElement);
+
+  // Nothing inline: the route may hand its metadata to a shared component
+  // (`<SeoHead title={title} description={description} />`), so follow it.
+  const delegated =
+    !title.elementStart && !description.elementStart && loadModule
+      ? analyzeDelegate(ctx, program, loadModule)
+      : null;
+  if (delegated) return delegated;
+
+  // New tags go after the last meta element already there, so they stay grouped.
+  const present = [title, description, keywords, robots].filter((el) => el.elementEnd !== undefined);
+  const insertOffset = present.length ? Math.max(...present.map((el) => el.elementEnd as number)) : null;
+  let insertIndent = "";
+  if (insertOffset !== null) {
+    const anchor = Math.min(...present.map((el) => el.elementStart as number));
+    const lineStart = code.lastIndexOf("\n", anchor) + 1;
+    insertIndent = code.slice(lineStart, anchor).match(/^[ \t]*/)?.[0] ?? "";
+  }
+
+  return {
+    title,
+    description,
+    keywords,
+    robots,
+    hasJsxMeta: present.length > 0,
+    insertOffset,
+    insertIndent,
+  };
+}