@getrefino/onboarding 0.1.0-rc.1

package/dist/scan.js

@@ -0,0 +1,1486 @@
+/**
+ * Visible-copy discovery. Walks React source with the TypeScript parser and
+ * collects string candidates from JSX text, literal JSX children, display
+ * attributes and data arrays that feed JSX. Never mutates anything.
+ *
+ * Every candidate gets a classification and a reason, so a human or an
+ * agent can see why something was or was not selected.
+ */
+import ts from "typescript";
+import { isTestOrStoryFile, readText, rel, walkFiles } from "./fs.js";
+import { appDirectory } from "./inspect.js";
+import { computeFileScopes, parseSource, readPathAliases, resolveImport } from "./graph.js";
+import { arrayOfStrings, callbackRendersItem, componentRenderInfo, createDataflowContext, enclosingScope, fieldNameOf, findBinding, literalText, mapCallbackOf, recordOfStringArrays, resolveComponent, stateLiterals, } from "./dataflow.js";
+import { pathSegment, proposeIds, slugFromText } from "./ids.js";
+const DISPLAY_PROPS = new Set([
+    "title",
+    "subtitle",
+    "heading",
+    "subheading",
+    "description",
+    "label",
+    "text",
+    "tagline",
+    "caption",
+    "cta",
+    "ctaText",
+    "ctaLabel",
+    "buttonText",
+    "buttonLabel",
+    "eyebrow",
+    "quote",
+    "body",
+    "summary",
+    "message",
+    "question",
+    "answer",
+    "name",
+    "role",
+    "author",
+    "badge",
+    "note",
+    "lead",
+    "intro",
+    "kicker",
+    "overline",
+    "blurb",
+    "excerpt",
+    "headline",
+    "subheadline",
+    "footnote",
+    "disclaimer",
+    "hint",
+]);
+/** Elements whose first short label names everything inside them (a card, a figure, a list item). */
+const ITEM_CONTAINER_TAGS = new Set(["figure", "li", "article"]);
+const ACCESSIBILITY_PROPS = new Set(["alt", "aria-label", "aria-description", "placeholder"]);
+const DEVELOPER_TAGS = new Set(["code", "pre", "kbd", "samp", "script", "style", "var"]);
+const LANDMARK_TAGS = new Set(["section", "header", "footer", "nav", "main", "aside", "article", "form", "dialog"]);
+const UI_WORDS = new Set([
+    "ok",
+    "cancel",
+    "close",
+    "submit",
+    "save",
+    "delete",
+    "edit",
+    "loading",
+    "loading...",
+    "loading…",
+    "error",
+    "retry",
+    "back",
+    "next",
+    "previous",
+    "prev",
+    "yes",
+    "no",
+    "menu",
+    "open menu",
+    "close menu",
+    "toggle menu",
+    "search",
+    "skip to content",
+    "skip to main content",
+    "×",
+    "✕",
+]);
+function collapse(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+const NAMED_ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: "\u00a0",
+    ensp: "\u2002",
+    emsp: "\u2003",
+    thinsp: "\u2009",
+    shy: "",
+    lsquo: "\u2018",
+    rsquo: "\u2019",
+    ldquo: "\u201c",
+    rdquo: "\u201d",
+    hellip: "\u2026",
+    ndash: "\u2013",
+    mdash: "\u2014",
+    middot: "\u00b7",
+    bull: "\u2022",
+    copy: "\u00a9",
+    reg: "\u00ae",
+    trade: "\u2122",
+    times: "\u00d7",
+    laquo: "\u00ab",
+    raquo: "\u00bb",
+    deg: "\u00b0",
+    euro: "\u20ac",
+    pound: "\u00a3",
+};
+/** JSX text keeps entities as written (`&amp;`); the copy file must hold the real characters. */
+export function decodeJsxEntities(text) {
+    return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, body) => {
+        if (body[0] === "#") {
+            const code = body[1]?.toLowerCase() === "x" ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+            return Number.isFinite(code) ? String.fromCodePoint(code) : match;
+        }
+        return NAMED_ENTITIES[body] ?? match;
+    });
+}
+const UTILITY_KEYWORDS = new Set([
+    "flex", "grid", "block", "inline", "inline-block", "inline-flex", "hidden", "contents", "flow-root", "table",
+    "relative", "absolute", "fixed", "sticky", "static", "isolate", "container", "group", "peer",
+    "truncate", "antialiased", "italic", "uppercase", "lowercase", "capitalize", "invisible", "visible",
+    "sr-only", "not-sr-only", "underline", "overline", "line-through", "no-underline", "shadow", "border", "rounded",
+    "transition", "shrink-0", "grow", "shrink", "outline-none", "resize", "appearance-none",
+]);
+const UTILITY_PREFIX = /^-?(p|m|px|py|pt|pb|pl|pr|ps|pe|mx|my|mt|mb|ml|mr|ms|me|w|h|min-w|min-h|max-w|max-h|size|gap|gap-x|gap-y|space-x|space-y|inset|top|left|right|bottom|start|end|z|text|bg|border|border-[trblxy]|rounded|rounded-[trbl]{1,2}|shadow|opacity|font|leading|tracking|flex|grid|grid-cols|grid-rows|col|row|col-span|row-span|order|basis|overflow|object|aspect|scroll-[mp][trblxy]?|divide|divide-[xy]|ring|ring-offset|outline|decoration|underline-offset|translate|translate-[xy]|rotate|scale|skew|origin|duration|delay|ease|cursor|select|pointer-events|place-(items|content|self)|items|justify|content|self|columns|break|break-(inside|before|after)|whitespace|list|align|fill|stroke|blur|backdrop|animate|will-change|accent|caret|from|via|to|line-clamp|indent|hyphens|mix-blend)(-|$)/;
+/** Tailwind-style utility tokens (`sticky`, `py-24`, `lg:grid-cols-2`, `text-[1rem]`) never name a section. */
+export function isUtilityClass(token) {
+    if (token.includes(":") || token.includes("[") || token.includes("/"))
+        return true;
+    if (UTILITY_KEYWORDS.has(token))
+        return true;
+    if (/^-?[a-z]+(-[a-z0-9.]+)*-\d+(\.\d+)?$/.test(token))
+        return true;
+    return UTILITY_PREFIX.test(token);
+}
+const SENTENCE_END = /[.!?\u2026]$/u;
+const WORD_WITH_JOINERS = /^\p{L}+(?:[-'\u2019]\p{L}+)*$/u;
+/**
+ * One word a person reads rather than an identifier: "Dinner.", "Really?",
+ * "Kid-friendly". A lowercase hyphenated token ("lunchbox-guides", "text-sm")
+ * is still a slug, so it stays out.
+ */
+function isProseWord(text) {
+    const bare = text.replace(SENTENCE_END, "");
+    if (!WORD_WITH_JOINERS.test(bare))
+        return false;
+    if (SENTENCE_END.test(text))
+        return true;
+    return /[-'\u2019]/u.test(bare) && /\p{Lu}/u.test(bare);
+}
+function looksLikeCode(text) {
+    if (/^[A-Z0-9_]{3,}$/.test(text) && !/\s/.test(text))
+        return true; // ENV_VAR
+    if (/^(https?:)?\/\//.test(text) || /^\/[\w./-]*$/.test(text))
+        return true; // url or route
+    if (/^[\w-]+\.(png|jpe?g|svg|gif|webp|ico|css|js|ts|json|md)$/i.test(text))
+        return true;
+    if (!/\s/.test(text) && /[-_./:{}[\]()<>=]/.test(text) && text.length > 2 && !isProseWord(text))
+        return true; // class names, paths, keys
+    if (!/\s/.test(text) && /^[a-z]+[A-Z]/.test(text))
+        return true; // camelCase identifier
+    if (/^#[0-9a-f]{3,8}$/i.test(text))
+        return true;
+    if (/^\$?\d+(\.\d+)?%?$/.test(text) && text.length < 3)
+        return true;
+    return false;
+}
+function isPunctuationOnly(text) {
+    return !/[\p{L}\p{N}]/u.test(text);
+}
+function hasLetters(text) {
+    return /\p{L}/u.test(text);
+}
+function tagName(node) {
+    const name = node.tagName;
+    if (ts.isIdentifier(name))
+        return name.text;
+    if (ts.isPropertyAccessExpression(name))
+        return name.getText();
+    return name.getText();
+}
+function attributeString(node, name) {
+    for (const attr of node.attributes.properties) {
+        if (!ts.isJsxAttribute(attr) || !ts.isIdentifier(attr.name) || attr.name.text !== name)
+            continue;
+        if (!attr.initializer)
+            return null;
+        if (ts.isStringLiteral(attr.initializer))
+            return attr.initializer.text;
+        if (ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
+            const expression = attr.initializer.expression;
+            if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression))
+                return expression.text;
+            if (ts.isTemplateExpression(expression))
+                return expression.head.text;
+        }
+    }
+    return null;
+}
+function attributeIsTrue(node, name) {
+    const value = attributeString(node, name);
+    if (value === "true")
+        return true;
+    for (const attr of node.attributes.properties) {
+        if (ts.isJsxAttribute(attr) && ts.isIdentifier(attr.name) && attr.name.text === name && !attr.initializer)
+            return true;
+        if (ts.isJsxAttribute(attr) && ts.isIdentifier(attr.name) && attr.name.text === name && attr.initializer && ts.isJsxExpression(attr.initializer) && attr.initializer.expression?.kind === ts.SyntaxKind.TrueKeyword)
+            return true;
+    }
+    return false;
+}
+function enclosingComponentName(node) {
+    let current = node;
+    while (current) {
+        if (ts.isFunctionDeclaration(current) && current.name)
+            return current.name.text;
+        if ((ts.isArrowFunction(current) || ts.isFunctionExpression(current)) && current.parent && ts.isVariableDeclaration(current.parent) && ts.isIdentifier(current.parent.name)) {
+            return current.parent.name.text;
+        }
+        if (ts.isClassDeclaration(current) && current.name)
+            return current.name.text;
+        current = current.parent;
+    }
+    return null;
+}
+function insideMapCallback(node) {
+    let current = node;
+    while (current) {
+        if ((ts.isArrowFunction(current) || ts.isFunctionExpression(current)) && current.parent && ts.isCallExpression(current.parent)) {
+            const callee = current.parent.expression;
+            if (ts.isPropertyAccessExpression(callee) && ["map", "flatMap", "forEach"].includes(callee.name.text))
+                return true;
+        }
+        current = current.parent;
+    }
+    return false;
+}
+function jsxAncestors(node) {
+    const result = [];
+    let current = node.parent;
+    while (current && !ts.isFunctionLike(current) && !ts.isSourceFile(current)) {
+        if (ts.isJsxElement(current))
+            result.unshift({ tag: tagName(current.openingElement), node: current.openingElement });
+        else if (ts.isJsxSelfClosingElement(current))
+            result.unshift({ tag: tagName(current), node: current });
+        current = current.parent;
+    }
+    return result;
+}
+function landmarkFor(ancestors) {
+    for (let index = ancestors.length - 1; index >= 0; index -= 1) {
+        const { tag, node } = ancestors[index];
+        const id = attributeString(node, "id");
+        if (id && LANDMARK_TAGS.has(tag))
+            return id;
+        if (id && index < ancestors.length - 1 && tag === "div")
+            return id;
+        if (LANDMARK_TAGS.has(tag)) {
+            const className = attributeString(node, "className") ?? attributeString(node, "class");
+            const token = className
+                ?.split(/\s+/)
+                .filter(Boolean)
+                .map((entry) => entry.split(/__|--/)[0])
+                .find((entry) => !isUtilityClass(entry) && !/^(container|wrapper|inner|content|row|col|section)$/.test(entry));
+            if (token)
+                return token;
+            if (tag !== "main" && tag !== "form")
+                return tag;
+        }
+    }
+    return null;
+}
+function metadataContext(node) {
+    let current = node;
+    while (current) {
+        if (ts.isVariableDeclaration(current) && ts.isIdentifier(current.name) && /^(metadata|viewport)$/.test(current.name.text))
+            return true;
+        if (ts.isFunctionDeclaration(current) && current.name && /^generate(Metadata|Viewport)$/.test(current.name.text))
+            return true;
+        current = current.parent;
+    }
+    return false;
+}
+function jsxElementText(element) {
+    const parts = [];
+    for (const child of element.children) {
+        if (ts.isJsxText(child))
+            parts.push(child.text);
+        else if (ts.isJsxExpression(child) && child.expression && (ts.isStringLiteral(child.expression) || ts.isNoSubstitutionTemplateLiteral(child.expression)))
+            parts.push(child.expression.text);
+        else
+            return null;
+    }
+    const text = collapse(parts.join(" "));
+    return text || null;
+}
+/** For a <dd>, the text of the <dt> right before it; for a <dt>, its own text. */
+function pairTitleFor(elementNode, tag) {
+    if (!elementNode || !ts.isJsxElement(elementNode))
+        return null;
+    if (tag === "dt" || tag === "summary")
+        return jsxElementText(elementNode);
+    if (tag !== "dd")
+        return null;
+    const parent = elementNode.parent;
+    if (!parent || !ts.isJsxElement(parent))
+        return null;
+    let previous = null;
+    for (const child of parent.children) {
+        if (child === elementNode)
+            break;
+        if (ts.isJsxElement(child))
+            previous = child;
+    }
+    return previous && tagName(previous.openingElement) === "dt" ? jsxElementText(previous) : null;
+}
+const SITE_PATH = /^\/[\w./#-]*$/;
+/** A literal `href`/`to` that points inside the site ("/pricing", "/#features"), else null. */
+function sitePathOf(node) {
+    if (!node)
+        return null;
+    const value = attributeString(node, "href") ?? attributeString(node, "to");
+    return value && SITE_PATH.test(value) ? value : null;
+}
+function isLabelElement(tag, className) {
+    if (/^(h[1-6]|dt|strong|b|summary)$/.test(tag))
+        return true;
+    if (/^(Eyebrow|Kicker|Overline|Heading|Title|Label)$/.test(tag))
+        return true;
+    return className !== null && /(^|[\s_-])(eyebrow|kicker|overline|label|title|heading)([\s_-]|$)/i.test(className);
+}
+function isShortLabelText(text) {
+    return text.split(/\s+/).length <= 4 && text.length <= 40;
+}
+/** The first short label text directly inside `element` (its own heading, eyebrow or bold lead-in), and how many texts it holds. */
+function firstLabelIn(element) {
+    let label = null;
+    let texts = 0;
+    const visit = (node) => {
+        if (ts.isJsxText(node) && !node.containsOnlyTriviaWhiteSpaces) {
+            const text = collapse(decodeJsxEntities(node.text));
+            if (!hasLetters(text))
+                return;
+            texts += 1;
+            if (label === null && node.parent && ts.isJsxElement(node.parent) && isShortLabelText(text)) {
+                const opening = node.parent.openingElement;
+                if (isLabelElement(tagName(opening), attributeString(opening, "className") ?? attributeString(opening, "class")))
+                    label = text;
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(element);
+    return { label, texts };
+}
+/** Same-tag siblings of `element` under its parent that are JSX elements. */
+function elementSiblings(element) {
+    const parent = element.parent;
+    if (!parent || !ts.isJsxElement(parent))
+        return [element];
+    const tag = tagName(element.openingElement);
+    return parent.children.filter((child) => ts.isJsxElement(child) && tagName(child.openingElement) === tag);
+}
+/**
+ * For text inside an item container, the container's first short label (a
+ * heading, eyebrow or bold lead-in) names the whole item:
+ * `home.story.howYouFeel.body` instead of `body3`. A container is a figure,
+ * list item or article, or any element that is one of at least two same-tag
+ * siblings that each open with such a label (a row of feature cards built
+ * from divs). Never inside a map callback: mapped items are named by their data.
+ */
+function containerLabelFor(textNode) {
+    let current = textNode.parent;
+    while (current && !ts.isFunctionLike(current) && !ts.isSourceFile(current)) {
+        if (ts.isJsxElement(current)) {
+            if (insideMapCallback(current))
+                return null;
+            const tag = tagName(current.openingElement);
+            if (ITEM_CONTAINER_TAGS.has(tag)) {
+                const { label, texts } = firstLabelIn(current);
+                return texts >= 2 ? label : null;
+            }
+            const siblings = elementSiblings(current);
+            if (siblings.length >= 2) {
+                const groups = siblings.map((sibling) => firstLabelIn(sibling));
+                const own = groups[siblings.indexOf(current)];
+                // Every sibling must be a labelled group holding more than its label; then the structure is a repeated card/step pattern.
+                if (own.label && own.texts >= 2 && groups.every((group) => group.label !== null && group.texts >= 2))
+                    return own.label;
+            }
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * Heading-then-content flow without wrappers (`<h3>Guides</h3><p>…</p><h3>Company</h3><p>…</p>`):
+ * when the parent holds at least two short labelled headings, a non-heading
+ * element is named by the nearest heading before it.
+ */
+function precedingLabelFor(elementNode) {
+    if (!elementNode || !ts.isJsxElement(elementNode))
+        return null;
+    const tag = tagName(elementNode.openingElement);
+    if (/^h[1-6]$/.test(tag) || tag === "dt" || tag === "dd" || tag === "summary")
+        return null;
+    const parent = elementNode.parent;
+    if (!parent || !ts.isJsxElement(parent) || insideMapCallback(elementNode))
+        return null;
+    let preceding = null;
+    let headings = 0;
+    for (const child of parent.children) {
+        if (!ts.isJsxElement(child))
+            continue;
+        const childTag = tagName(child.openingElement);
+        if (/^h[2-6]$/.test(childTag)) {
+            const text = jsxElementText(child);
+            if (text && isShortLabelText(text)) {
+                headings += 1;
+                if (child.pos < elementNode.pos)
+                    preceding = text;
+            }
+        }
+    }
+    return headings >= 2 ? preceding : null;
+}
+function isInlineInSentence(elementNode) {
+    if (!elementNode || !ts.isJsxElement(elementNode))
+        return false;
+    const grandparent = elementNode.parent;
+    if (!grandparent || !ts.isJsxElement(grandparent))
+        return false;
+    return grandparent.children.some((child) => ts.isJsxText(child) && !child.containsOnlyTriviaWhiteSpaces);
+}
+function siblingCountOf(node, tag) {
+    const parent = node.parent;
+    if (!parent || !ts.isJsxElement(parent))
+        return 1;
+    let count = 0;
+    for (const child of parent.children) {
+        const childTag = ts.isJsxElement(child) ? tagName(child.openingElement) : ts.isJsxSelfClosingElement(child) ? tagName(child) : null;
+        if (childTag === tag)
+            count += 1;
+    }
+    return Math.max(count, 1);
+}
+function siblingIndexOf(node, tag) {
+    const parent = node.parent;
+    if (!parent || !ts.isJsxElement(parent))
+        return 0;
+    let index = 0;
+    for (const child of parent.children) {
+        if (child === node)
+            return index;
+        const childTag = ts.isJsxElement(child) ? tagName(child.openingElement) : ts.isJsxSelfClosingElement(child) ? tagName(child) : null;
+        if (childTag === tag)
+            index += 1;
+    }
+    return index;
+}
+function pushJsx(ctx, sourceFile, textNode, rawText, source) {
+    const text = collapse(source === "jsx-text" ? decodeJsxEntities(rawText) : rawText);
+    if (!text)
+        return;
+    const ancestors = jsxAncestors(textNode);
+    const parent = ancestors[ancestors.length - 1] ?? null;
+    const element = parent?.tag ?? null;
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(textNode.getStart(sourceFile));
+    const component = enclosingComponentName(textNode);
+    const inMap = insideMapCallback(textNode);
+    let classification = "visible-text";
+    let reason = "Plain text inside a rendered element.";
+    const parentNode = textNode.parent;
+    const siblings = parentNode && ts.isJsxElement(parentNode) ? parentNode.children : [];
+    const hasElementSiblings = siblings.some((child) => ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child) || ts.isJsxFragment(child));
+    const hasExpressionSiblings = siblings.some((child) => ts.isJsxExpression(child) && child.expression && !ts.isStringLiteral(child.expression) && !ts.isNoSubstitutionTemplateLiteral(child.expression));
+    if (metadataContext(textNode)) {
+        classification = "metadata";
+        reason = "Inside page metadata; out of scope unless explicitly requested.";
+    }
+    else if (element && DEVELOPER_TAGS.has(element)) {
+        classification = "developer-text";
+        reason = `Inside <${element}>, which shows code rather than copy.`;
+    }
+    else if (ancestors.some((a) => attributeIsTrue(a.node, "aria-hidden"))) {
+        classification = "decorative";
+        reason = "Inside an aria-hidden element; decorative, not copy.";
+    }
+    else if (isPunctuationOnly(text)) {
+        classification = "decorative";
+        reason = "Punctuation or symbols only.";
+    }
+    else if (looksLikeCode(text) || !hasLetters(text)) {
+        classification = "developer-text";
+        reason = "Looks like an identifier, path, URL or number rather than prose.";
+    }
+    else if (hasExpressionSiblings) {
+        classification = "dynamic";
+        reason = "Shares its element with an interpolated expression; the sentence is assembled at runtime.";
+    }
+    else if (hasElementSiblings) {
+        classification = "mixed-markup";
+        reason = "Shares its element with inline markup (a link, icon or emphasis). Split the element or leave it in code.";
+    }
+    else if (UI_WORDS.has(text.toLowerCase()) && !(element && /^(h[1-6]|p|dt|dd|blockquote|figcaption)$/.test(element))) {
+        // "Save" on a button is a control; "Save" as a step heading is copy.
+        classification = "ui-text";
+        reason = "Common interface control label, not marketing copy.";
+    }
+    else if (text.length < 2) {
+        classification = "uncertain";
+        reason = "Too short to be sure it is copy.";
+    }
+    ctx.candidates.push({
+        text,
+        file: ctx.relFile,
+        line: line + 1,
+        column: character + 1,
+        source,
+        element,
+        key: null,
+        component,
+        scope: ctx.scope,
+        classification,
+        reason,
+        context: {
+            ancestors: ancestors.map((a) => a.tag),
+            landmark: landmarkFor(ancestors),
+            className: parent ? (attributeString(parent.node, "className") ?? attributeString(parent.node, "class")) : null,
+            collection: null,
+            itemKey: null,
+            itemTitle: pairTitleFor(parentNode, element) ?? containerLabelFor(textNode) ?? precedingLabelFor(parentNode),
+            siblingIndex: parentNode ? siblingIndexOf(parentNode, element ?? "") : 0,
+            siblingCount: parentNode ? siblingCountOf(parentNode, element ?? "") : 1,
+            insideMap: inMap,
+            inlineInSentence: isInlineInSentence(parentNode),
+            href: sitePathOf(parent?.node ?? null),
+            collectionImported: false,
+            route: ctx.route,
+        },
+    });
+}
+function pushAttribute(ctx, sourceFile, attr, owner, name, value, renderedBy) {
+    const text = collapse(value);
+    if (!text)
+        return;
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(attr.getStart(sourceFile));
+    // The element this attribute belongs to: the self-closing node itself, or the JsxElement around an opening tag.
+    const elementNode = ts.isJsxSelfClosingElement(owner) ? owner : owner.parent;
+    const ancestors = jsxAncestors(elementNode);
+    const tag = tagName(owner);
+    const isComponent = /^[A-Z]/.test(tag);
+    let classification;
+    let reason;
+    if (metadataContext(attr)) {
+        classification = "metadata";
+        reason = "Inside page metadata; out of scope unless explicitly requested.";
+    }
+    else if (ACCESSIBILITY_PROPS.has(name)) {
+        classification = "accessibility";
+        reason = `"${name}" is assistive or placeholder text; editable later, not part of the first migration.`;
+    }
+    else if (looksLikeCode(text) || !hasLetters(text)) {
+        classification = "developer-text";
+        reason = "Looks like an identifier, path or URL rather than prose.";
+    }
+    else if (isComponent && (DISPLAY_PROPS.has(name) || renderedBy)) {
+        classification = "display-prop";
+        reason = renderedBy ?? `String passed as the "${name}" prop of <${tag}>, which renders it.`;
+    }
+    else if (!isComponent && name === "title") {
+        classification = "accessibility";
+        reason = "Native title attribute renders as a tooltip only.";
+    }
+    else {
+        classification = "uncertain";
+        reason = `String prop "${name}" on <${tag}>; cannot tell whether it is rendered.`;
+    }
+    const titleProp = attributeString(owner, "title") ?? attributeString(owner, "heading") ?? attributeString(owner, "name") ?? attributeString(owner, "label");
+    // A component keyed by where it links (`<FeatureCard href="/features/privacy">`) has a stable, non-text identity.
+    const ownerPath = sitePathOf(owner) ?? (attributeString(owner, "path") && SITE_PATH.test(attributeString(owner, "path")) ? attributeString(owner, "path") : null);
+    ctx.candidates.push({
+        text,
+        file: ctx.relFile,
+        line: line + 1,
+        column: character + 1,
+        source: "jsx-attribute",
+        element: tag,
+        key: name,
+        component: enclosingComponentName(attr),
+        scope: ctx.scope,
+        classification,
+        reason,
+        context: {
+            ancestors: ancestors.map((a) => a.tag),
+            landmark: landmarkFor(ancestors),
+            className: null,
+            collection: null,
+            itemKey: attributeString(owner, "id") ?? attributeString(owner, "key") ?? attributeString(owner, "slug") ?? (ownerPath ? pathSegment(ownerPath) : null),
+            itemTitle: titleProp,
+            siblingIndex: siblingIndexOf(elementNode, tag),
+            siblingCount: siblingCountOf(elementNode, tag),
+            insideMap: insideMapCallback(attr),
+            inlineInSentence: false,
+            href: ownerPath,
+            collectionImported: false,
+            route: ctx.route,
+        },
+    });
+}
+/** Find `VARIABLE.map((item) => <jsx/>)` inside `scope` and record which item fields it renders. */
+function mapUsageFor(scope, variable) {
+    let usage = null;
+    const visit = (node) => {
+        if (usage)
+            return;
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ["map", "flatMap"].includes(node.expression.name.text) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === variable) {
+            const callback = node.arguments[0];
+            const renderedFields = new Set();
+            let keyField = null;
+            let spread = false;
+            if (callback && (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback))) {
+                const param = callback.parameters[0]?.name;
+                const paramName = param && ts.isIdentifier(param) ? param.text : null;
+                const destructured = new Set();
+                if (param && ts.isObjectBindingPattern(param))
+                    for (const binding of param.elements)
+                        if (ts.isIdentifier(binding.name))
+                            destructured.add((binding.propertyName && ts.isIdentifier(binding.propertyName) ? binding.propertyName : binding.name).text);
+                const fieldOf = (expression) => {
+                    if (paramName && ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.expression) && expression.expression.text === paramName)
+                        return expression.name.text;
+                    if (ts.isIdentifier(expression) && destructured.has(expression.text))
+                        return expression.text;
+                    return null;
+                };
+                const walk = (inner) => {
+                    if (ts.isJsxExpression(inner) && inner.expression && inner.parent && ts.isJsxElement(inner.parent)) {
+                        const field = fieldOf(inner.expression);
+                        if (field)
+                            renderedFields.add(field);
+                    }
+                    else if (ts.isJsxAttribute(inner) && ts.isIdentifier(inner.name) && inner.initializer && ts.isJsxExpression(inner.initializer) && inner.initializer.expression) {
+                        const owner = inner.parent.parent;
+                        if (inner.name.text === "key") {
+                            keyField ??= fieldOf(inner.initializer.expression);
+                        }
+                        else if (DISPLAY_PROPS.has(inner.name.text)) {
+                            const field = /^[A-Z]/.test(tagName(owner)) ? fieldOf(inner.initializer.expression) : null;
+                            if (field)
+                                renderedFields.add(field);
+                        }
+                    }
+                    else if (ts.isJsxSpreadAttribute(inner) && paramName && ts.isIdentifier(inner.expression) && inner.expression.text === paramName) {
+                        const owner = inner.parent.parent;
+                        if (/^[A-Z]/.test(tagName(owner)))
+                            spread = true;
+                    }
+                    ts.forEachChild(inner, walk);
+                };
+                walk(callback.body);
+            }
+            usage = { renderedFields, component: enclosingComponentName(node), keyField, spread };
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(scope);
+    return usage;
+}
+function unwrapExpression(expression) {
+    let current = expression;
+    while (ts.isAsExpression(current) || ts.isSatisfiesExpression(current) || ts.isParenthesizedExpression(current) || ts.isTypeAssertionExpression(current))
+        current = current.expression;
+    return current;
+}
+/** The enclosing function body of a declaration, or the source file for a top-level one. */
+function declarationScope(node) {
+    let current = node.parent;
+    while (current && !ts.isSourceFile(current)) {
+        if (ts.isFunctionLike(current))
+            return current;
+        current = current.parent;
+    }
+    return node.getSourceFile();
+}
+/** `const X = [...]` declarations anywhere in a file (top level or inside a component function). */
+function arrayDeclarations(sourceFile) {
+    const found = [];
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+            const initializer = unwrapExpression(node.initializer);
+            if (ts.isArrayLiteralExpression(initializer))
+                found.push({ declaration: node, array: initializer });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return found;
+}
+/** Exported array literals of a data module: `export const X = [...]`, `const X = [...]; export { X }`, `export default [...]`. */
+function exportedArrays(sourceFile) {
+    const arrays = new Map();
+    const local = new Map();
+    for (const { declaration, array } of arrayDeclarations(sourceFile)) {
+        if (!ts.isIdentifier(declaration.name) || !ts.isSourceFile(declarationScope(declaration)))
+            continue;
+        local.set(declaration.name.text, array);
+        const statement = declaration.parent.parent;
+        if (ts.isVariableStatement(statement) && statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword))
+            arrays.set(declaration.name.text, array);
+    }
+    for (const statement of sourceFile.statements) {
+        if (ts.isExportDeclaration(statement) && statement.exportClause && ts.isNamedExports(statement.exportClause) && !statement.moduleSpecifier) {
+            for (const element of statement.exportClause.elements) {
+                const source = local.get((element.propertyName ?? element.name).text);
+                if (source)
+                    arrays.set(element.name.text, source);
+            }
+        }
+        else if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+            const expression = unwrapExpression(statement.expression);
+            if (ts.isArrayLiteralExpression(expression))
+                arrays.set("default", expression);
+            else if (ts.isIdentifier(expression) && local.has(expression.text))
+                arrays.set("default", local.get(expression.text));
+        }
+    }
+    return arrays;
+}
+/** Arrays this file imports from local data modules, keyed by the local binding name. */
+function importedArrays(ctx, sourceFile, absoluteFile, aliases) {
+    const result = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !statement.importClause || statement.importClause.isTypeOnly)
+            continue;
+        const resolved = resolveImport(absoluteFile, statement.moduleSpecifier.text, ctx.appDir, aliases);
+        if (!resolved || resolved.includes("/node_modules/"))
+            continue;
+        const text = readText(resolved);
+        if (!text)
+            continue;
+        const moduleSource = parseSource(resolved, text);
+        const exported = exportedArrays(moduleSource);
+        if (exported.size === 0)
+            continue;
+        const file = rel(ctx.appDir, resolved);
+        const add = (localName, exportName) => {
+            const array = exported.get(exportName);
+            if (array)
+                result.set(localName, { variable: localName, elements: array.elements, sourceFile: moduleSource, file });
+        };
+        if (statement.importClause.name)
+            add(statement.importClause.name.text, "default");
+        const bindings = statement.importClause.namedBindings;
+        if (bindings && ts.isNamedImports(bindings))
+            for (const element of bindings.elements)
+                add(element.name.text, (element.propertyName ?? element.name).text);
+    }
+    return result;
+}
+const SHORT_LABEL_WORDS = 4;
+function isShortLabelValue(value) {
+    return Boolean(value && hasLetters(value) && !looksLikeCode(value) && value.split(/\s+/).length <= SHORT_LABEL_WORDS && value.length <= 40);
+}
+/** Emit the display fields of one array's object items. */
+function collectArrayItems(ctx, declaration, usage, emitted) {
+    const { variable, sourceFile } = declaration;
+    const rendered = usage?.renderedFields ?? new Set();
+    for (const element of declaration.elements) {
+        if (!ts.isObjectLiteralExpression(element))
+            continue;
+        const props = new Map();
+        for (const prop of element.properties) {
+            if (!ts.isPropertyAssignment(prop))
+                continue;
+            const key = ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name) ? prop.name.text : null;
+            if (!key)
+                continue;
+            if (ts.isStringLiteral(prop.initializer) || ts.isNoSubstitutionTemplateLiteral(prop.initializer))
+                props.set(key, prop.initializer.text);
+        }
+        // A link item is naturally keyed by where it goes: { path: "/ftp-calculator" } -> ftpCalculator.
+        const pathKey = [props.get("path"), props.get("href"), props.get("to"), props.get("url")].find((value) => value && SITE_PATH.test(value));
+        // The React key the callback uses is the developer's statement of the item's identity ({ factor: "Sleep" } with key={item.factor}).
+        const reactKey = usage?.keyField ? props.get(usage.keyField) : undefined;
+        const keyedByReactKey = !props.get("id") && !props.get("key") && !props.get("slug") && !pathKey && isShortLabelValue(reactKey);
+        const itemKey = props.get("id") ?? props.get("key") ?? props.get("slug") ?? (pathKey ? pathSegment(pathKey) : null) ?? (keyedByReactKey ? slugFromText(reactKey, 3) || null : null);
+        // Without a title-like field, the first rendered short label ({ factor: "Sleep", line: "…" }) names the item.
+        const renderedLabel = [...rendered].map((field) => props.get(field)).find((value) => isShortLabelValue(value));
+        const itemTitle = props.get("title") ?? props.get("name") ?? props.get("heading") ?? props.get("label") ?? props.get("question") ?? renderedLabel ?? null;
+        for (const prop of element.properties) {
+            if (!ts.isPropertyAssignment(prop))
+                continue;
+            const key = ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name) ? prop.name.text : null;
+            if (!key || (!DISPLAY_PROPS.has(key) && !rendered.has(key)))
+                continue;
+            if (!ts.isStringLiteral(prop.initializer) && !ts.isNoSubstitutionTemplateLiteral(prop.initializer))
+                continue;
+            const value = collapse(prop.initializer.text);
+            if (!value || looksLikeCode(value) || !hasLetters(value))
+                continue;
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(prop.initializer.getStart(sourceFile));
+            const identity = `${declaration.file}:${line + 1}:${character + 1}`;
+            if (emitted.has(identity))
+                continue;
+            emitted.add(identity);
+            const how = rendered.has(key) ? "the .map callback renders it as text" : usage?.spread ? `the .map callback spreads each item into <${usage.component ?? "a component"}>` : "which the file maps into JSX";
+            const where = declaration.file === ctx.relFile ? variable : `${variable} (imported from ${declaration.file})`;
+            ctx.candidates.push({
+                text: value,
+                file: declaration.file,
+                line: line + 1,
+                column: character + 1,
+                source: "data-object",
+                element: null,
+                key,
+                component: usage?.component ?? variable,
+                scope: ctx.scope,
+                classification: "data-object",
+                reason: `"${key}" field of an item in ${where}; ${how}${keyedByReactKey ? `; the item is keyed by its React key (${usage.keyField})` : ""}.`,
+                context: {
+                    ancestors: [],
+                    landmark: null,
+                    className: null,
+                    collection: variable,
+                    itemKey,
+                    itemTitle,
+                    siblingIndex: 0,
+                    siblingCount: 1,
+                    insideMap: false,
+                    inlineInSentence: false,
+                    href: pathKey ?? null,
+                    collectionImported: declaration.file !== ctx.relFile,
+                    route: ctx.route,
+                },
+            });
+        }
+    }
+}
+/**
+ * `const ITEMS = [{ title: "...", ... }]` arrays that JSX maps over: declared
+ * at the top of the file, inside the component function, or imported from a
+ * local data module. Arrays nothing maps are ignored.
+ */
+function collectDataObjects(ctx, sourceFile, absoluteFile, aliases, emitted) {
+    const text = sourceFile.text;
+    for (const { declaration, array } of arrayDeclarations(sourceFile)) {
+        const variable = declaration.name.text;
+        const scope = declarationScope(declaration);
+        const usage = mapUsageFor(scope, variable);
+        const usedInJsx = usage !== null || (ts.isSourceFile(scope) && new RegExp(`\\{\\s*${variable}\\s*\\}`).test(text));
+        if (!usedInJsx)
+            continue;
+        collectArrayItems(ctx, { variable, elements: array.elements, sourceFile, file: ctx.relFile }, usage, emitted);
+    }
+    for (const [variable, declaration] of importedArrays(ctx, sourceFile, absoluteFile, aliases)) {
+        const usage = mapUsageFor(sourceFile, variable);
+        if (!usage)
+            continue;
+        collectArrayItems(ctx, declaration, usage, emitted);
+    }
+}
+const aliasCache = new Map();
+function aliasesFor(appDir) {
+    let aliases = aliasCache.get(appDir);
+    if (!aliases)
+        aliasCache.set(appDir, (aliases = readPathAliases(appDir)));
+    return aliases;
+}
+export function scanFile(appDir, absoluteFile, scope, route, options = {}) {
+    const text = readText(absoluteFile);
+    if (text === null)
+        return [];
+    const sourceFile = parseSource(absoluteFile, text);
+    const aliases = aliasesFor(appDir);
+    const emitted = options.emitted ?? new Set();
+    const ctx = {
+        appDir,
+        relFile: rel(appDir, absoluteFile),
+        scope,
+        route,
+        candidates: [],
+        flow: options.flow ?? createDataflowContext(appDir, aliases),
+        sourceFile,
+        absoluteFile,
+        emitted,
+        ordinals: new Map(),
+    };
+    const visit = (node) => {
+        if (ts.isJsxText(node)) {
+            if (!node.containsOnlyTriviaWhiteSpaces)
+                pushJsx(ctx, sourceFile, node, node.text, "jsx-text");
+        }
+        else if (ts.isJsxExpression(node) && node.expression && node.parent && (ts.isJsxElement(node.parent) || ts.isJsxFragment(node.parent))) {
+            handleExpressionChild(ctx, node);
+        }
+        else if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.initializer) {
+            handleAttribute(ctx, sourceFile, node);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    collectDataObjects(ctx, sourceFile, absoluteFile, aliases, emitted);
+    collectMappedValues(ctx, sourceFile);
+    collectPropDefaults(ctx, sourceFile);
+    return ctx.candidates;
+}
+function isMigratable(candidate) {
+    return candidate.classification === "visible-text" || candidate.classification === "display-prop" || candidate.classification === "data-object";
+}
+export function scanCopy(inspection, options = {}) {
+    const appDir = appDirectory(inspection);
+    const includeShared = options.includeShared ?? true;
+    const requestedRoutes = options.all ? inspection.routes.map((route) => route.path) : (options.routes ?? (inspection.routes.some((route) => route.path === "/") ? ["/"] : inspection.routes.slice(0, 1).map((route) => route.path)));
+    const scopes = computeFileScopes(appDir, inspection.routes, inspection.layouts);
+    const files = new Map();
+    const allSource = walkFiles(appDir).filter((file) => !isTestOrStoryFile(rel(appDir, file)));
+    if (options.all && inspection.routes.length === 0) {
+        for (const file of allSource)
+            files.set(file, { scope: "unrouted", route: null });
+    }
+    else {
+        for (const file of allSource) {
+            const routesReaching = scopes.byFile.get(file);
+            const isShared = scopes.shared.has(file);
+            if (isShared) {
+                // Chrome a layout renders always belongs to the migration. A component that several
+                // routes share (a blog CTA, a calculator widget) belongs only when a requested route
+                // renders it; otherwise it is another page's copy.
+                const relevant = scopes.fromLayouts.has(file) || [...(routesReaching ?? [])].some((route) => requestedRoutes.includes(route));
+                if (includeShared && relevant)
+                    files.set(file, { scope: "shared", route: null });
+                continue;
+            }
+            if (!routesReaching)
+                continue;
+            const matching = [...routesReaching].filter((route) => requestedRoutes.includes(route));
+            if (matching.length === 0)
+                continue;
+            files.set(file, { scope: matching[0], route: matching[0] });
+        }
+        if (options.all) {
+            for (const file of allSource) {
+                if (!files.has(file) && !scopes.byFile.has(file) && !scopes.shared.has(file))
+                    files.set(file, { scope: "unrouted", route: null });
+            }
+        }
+    }
+    // Shared chrome only counts when it is reachable from a selected route or a layout.
+    const raw = [];
+    const scanned = [];
+    const emitted = new Set();
+    const flow = createDataflowContext(appDir, aliasesFor(appDir));
+    for (const [file, info] of [...files.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        scanned.push(rel(appDir, file));
+        raw.push(...scanFile(appDir, file, info.scope, info.route, { emitted, flow }));
+    }
+    const withIds = proposeIds(raw);
+    const candidates = withIds.map(({ raw: candidate, id, idReason, review }) => {
+        let status;
+        let reason = candidate.reason;
+        if (!isMigratable(candidate)) {
+            status = candidate.classification === "mixed-markup" || candidate.classification === "dynamic" ? "unsupported" : "excluded";
+        }
+        else if (!id) {
+            status = "needs-review";
+            reason = idReason ?? "No sensible ID could be derived.";
+        }
+        else if (candidate.context.inlineInSentence) {
+            status = "needs-review";
+            reason = "Inline element inside a sentence whose surrounding text is not editable; migrate the whole sentence by splitting it, or leave it in code.";
+        }
+        else if (review || candidate.context.ambiguous === true) {
+            status = "needs-review";
+            // Keep both halves: why the string counts as copy, and why its id still
+            // needs a decision. An agent renaming it needs the provenance too.
+            reason = idReason && idReason !== reason ? `${reason} ${idReason}` : reason;
+        }
+        else {
+            status = "selected";
+        }
+        return {
+            id,
+            text: candidate.text,
+            file: candidate.file,
+            line: candidate.line,
+            column: candidate.column,
+            source: candidate.source,
+            element: candidate.element,
+            key: candidate.key,
+            component: candidate.component,
+            scope: candidate.scope,
+            classification: candidate.classification,
+            status,
+            reason,
+        };
+    });
+    return { filesScanned: scanned, candidates };
+}
+/** Emit one resolved literal, once per source position. */
+function emitValue(ctx, options) {
+    const raw = ts.isStringLiteral(options.node) || ts.isNoSubstitutionTemplateLiteral(options.node) ? options.node.text : null;
+    if (raw === null)
+        return;
+    const text = collapse(raw);
+    if (!text || looksLikeCode(text) || !hasLetters(text) || isPunctuationOnly(text))
+        return;
+    const { line, character } = options.sourceFile.getLineAndCharacterOfPosition(options.node.getStart(options.sourceFile));
+    const identity = `${options.file}:${line + 1}:${character + 1}`;
+    if (ctx.emitted.has(identity))
+        return;
+    ctx.emitted.add(identity);
+    ctx.candidates.push({
+        text,
+        file: options.file,
+        line: line + 1,
+        column: character + 1,
+        source: options.source,
+        element: options.element,
+        key: options.key,
+        component: options.component,
+        scope: ctx.scope,
+        classification: options.classification,
+        reason: options.reason,
+        context: {
+            ancestors: options.ancestors ?? [],
+            landmark: options.landmark ?? null,
+            className: options.className ?? null,
+            collection: options.collection,
+            itemKey: options.itemKey,
+            itemTitle: options.itemTitle,
+            siblingIndex: 0,
+            siblingCount: 1,
+            insideMap: false,
+            inlineInSentence: false,
+            href: null,
+            collectionImported: options.collectionImported ?? false,
+            ...(options.ambiguous === true ? { ambiguous: true } : {}),
+            route: ctx.route,
+        },
+    });
+}
+/** JSX context of a node, for naming. */
+function jsxContextOf(node) {
+    const ancestors = jsxAncestors(node);
+    const parent = ancestors[ancestors.length - 1] ?? null;
+    return {
+        element: parent?.tag ?? null,
+        ancestors: ancestors.map((entry) => entry.tag),
+        landmark: landmarkFor(ancestors),
+        className: parent ? (attributeString(parent.node, "className") ?? attributeString(parent.node, "class")) : null,
+    };
+}
+/** A non-literal `{expression}` child: a constant, a state value or a choice between two strings. */
+function handleExpressionChild(ctx, node) {
+    if (!node.expression)
+        return;
+    const expression = unwrapExpression(node.expression);
+    const literal = literalText(expression);
+    if (literal !== null) {
+        pushJsx(ctx, ctx.sourceFile, node, literal, "jsx-child-literal");
+        return;
+    }
+    const where = jsxContextOf(node);
+    const component = enclosingComponentName(node);
+    const common = {
+        sourceFile: ctx.sourceFile,
+        file: ctx.relFile,
+        source: "jsx-child-literal",
+        element: where.element,
+        key: null,
+        component,
+        collection: null,
+        itemTitle: null,
+        classification: "visible-text",
+        ancestors: where.ancestors,
+        landmark: where.landmark,
+        className: where.className,
+    };
+    if (ts.isConditionalExpression(expression)) {
+        const branches = [expression.whenTrue, expression.whenFalse].map((branch) => unwrapExpression(branch));
+        if (branches.every((branch) => literalText(branch) !== null)) {
+            for (const branch of branches) {
+                emitValue(ctx, {
+                    ...common,
+                    node: branch,
+                    itemKey: null,
+                    ambiguous: true,
+                    reason: "One of two alternative states of this element; both are shown to a reader, so each needs its own id.",
+                });
+            }
+        }
+        return;
+    }
+    if (!ts.isIdentifier(expression))
+        return;
+    const states = stateLiterals(enclosingScope(node), expression.text);
+    if (states) {
+        for (const state of states) {
+            emitValue(ctx, {
+                ...common,
+                node: state,
+                itemKey: null,
+                ambiguous: true,
+                reason: `A value the "${expression.text}" state can hold: the component sets it to this string and this element renders it.`,
+            });
+        }
+        return;
+    }
+    const binding = findBinding(node, expression.text);
+    if (binding?.initializer && literalText(binding.initializer) !== null) {
+        emitValue(ctx, {
+            ...common,
+            node: unwrapExpression(binding.initializer),
+            collection: expression.text,
+            itemKey: null,
+            reason: `The ${expression.text} constant, interpolated into this element.`,
+        });
+    }
+}
+/** A component tag as an id segment: `Findings` -> `findings`. */
+function segmentFromTag(tag) {
+    const bare = tag.replace(/^.*\./, "");
+    return bare.charAt(0).toLowerCase() + bare.slice(1);
+}
+/** Next ordinal for a collection within this file. */
+function nextOrdinal(ctx, collection) {
+    const next = (ctx.ordinals.get(collection) ?? 0) + 1;
+    ctx.ordinals.set(collection, next);
+    return next;
+}
+/** A prop with a literal value, or a literal array, that the receiving component renders. */
+function handleAttribute(ctx, sourceFile, attr) {
+    if (!ts.isIdentifier(attr.name) || !attr.initializer)
+        return;
+    const owner = attr.parent.parent;
+    const name = attr.name.text;
+    const tag = tagName(owner);
+    let value = null;
+    if (ts.isStringLiteral(attr.initializer))
+        value = attr.initializer.text;
+    else if (ts.isJsxExpression(attr.initializer) && attr.initializer.expression)
+        value = literalText(attr.initializer.expression);
+    if (value !== null && (DISPLAY_PROPS.has(name) || ACCESSIBILITY_PROPS.has(name) || name === "title")) {
+        pushAttribute(ctx, sourceFile, attr, owner, name, value);
+        return;
+    }
+    if (!/^[A-Z]/.test(tag) || tag.includes("."))
+        return;
+    const info = resolveComponent(ctx.flow, ctx.sourceFile, ctx.absoluteFile, tag);
+    const role = info?.props.get(name)?.role;
+    if (!role)
+        return;
+    if (value !== null && role === "text") {
+        pushAttribute(ctx, sourceFile, attr, owner, name, value, `String passed as the "${name}" prop of <${tag}>, which renders it as text (${info.file}).`);
+        return;
+    }
+    if (role === "list" && ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
+        const elements = arrayOfStrings(attr.initializer.expression);
+        if (!elements)
+            return;
+        const where = jsxContextOf(owner);
+        // The component names the collection, so two different list components stay apart.
+        const collection = segmentFromTag(tag);
+        for (const element of elements) {
+            const ordinal = nextOrdinal(ctx, collection);
+            emitValue(ctx, {
+                node: element,
+                sourceFile,
+                file: ctx.relFile,
+                source: "data-object",
+                element: tag,
+                key: null,
+                component: enclosingComponentName(attr),
+                collection,
+                itemKey: String(ordinal),
+                itemTitle: null,
+                classification: "data-object",
+                ambiguous: true,
+                ancestors: where.ancestors,
+                landmark: where.landmark,
+                reason: `Item ${ordinal} of the "${name}" prop of <${tag}>, which renders each item as text; the ordinal is a placeholder, choose a semantic name.`,
+            });
+        }
+    }
+}
+/** A literal default for a prop the component renders: visible whenever the caller omits it. */
+function collectPropDefaults(ctx, sourceFile) {
+    const names = new Set();
+    const visit = (node) => {
+        if (ts.isFunctionDeclaration(node) && node.name && /^[A-Z]/.test(node.name.text))
+            names.add(node.name.text);
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && /^[A-Z]/.test(node.name.text) && node.initializer) {
+            const initializer = unwrapExpression(node.initializer);
+            if (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer))
+                names.add(node.name.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    for (const name of names) {
+        const info = componentRenderInfo(sourceFile, ctx.relFile, name);
+        if (!info)
+            continue;
+        for (const [prop, detail] of info.props) {
+            if (detail.role !== "text" || detail.defaultText === null || !detail.defaultNode)
+                continue;
+            emitValue(ctx, {
+                node: unwrapExpression(detail.defaultNode),
+                sourceFile,
+                file: ctx.relFile,
+                source: "jsx-attribute",
+                element: name,
+                key: prop,
+                component: name,
+                collection: null,
+                itemKey: null,
+                itemTitle: null,
+                classification: "display-prop",
+                reason: `Default for the "${prop}" prop of <${name}>, which renders it as text; visible whenever a caller omits the prop.`,
+            });
+        }
+    }
+}
+/** Object literals of an array, when the array resolves to one. */
+function objectElementsOf(elements) {
+    const objects = elements.map((element) => unwrapExpression(element)).filter((element) => ts.isObjectLiteralExpression(element));
+    return objects.length === elements.length && objects.length > 0 ? objects : null;
+}
+function propertyOf(object, key) {
+    for (const property of object.properties) {
+        if (!ts.isPropertyAssignment(property))
+            continue;
+        const name = ts.isIdentifier(property.name) || ts.isStringLiteral(property.name) ? property.name.text : null;
+        if (name === key)
+            return property.initializer;
+    }
+    return null;
+}
+function stableKeyOf(object, fallback) {
+    for (const key of ["id", "key", "slug"]) {
+        const value = literalText(propertyOf(object, key) ?? undefined);
+        if (value)
+            return value;
+    }
+    for (const key of ["href", "path", "to", "url"]) {
+        const value = literalText(propertyOf(object, key) ?? undefined);
+        if (value && SITE_PATH.test(value))
+            return pathSegment(value);
+    }
+    return String(fallback + 1);
+}
+/** The array a map call reads, when it can be resolved statically in this file. */
+function resolveArrayTarget(ctx, node, target) {
+    if (ts.isArrayLiteralExpression(target))
+        return { elements: target.elements, collection: null, recordKey: null };
+    if (ts.isIdentifier(target)) {
+        const binding = findBinding(node, target.text);
+        const initializer = binding?.initializer ? unwrapExpression(binding.initializer) : null;
+        if (initializer && ts.isArrayLiteralExpression(initializer))
+            return { elements: initializer.elements, collection: target.text, recordKey: null };
+        return null;
+    }
+    if (ts.isElementAccessExpression(target) && ts.isIdentifier(target.expression)) {
+        const binding = findBinding(node, target.expression.text);
+        const record = binding?.initializer ? recordOfStringArrays(binding.initializer) : null;
+        if (!record)
+            return null;
+        // Indexed by a variable: every branch of the record can be shown.
+        const elements = [];
+        for (const values of record.values())
+            elements.push(...values);
+        return { elements, collection: target.expression.text, recordKey: null };
+    }
+    return null;
+}
+/** Record key an element belongs to, for naming values of `Record<string, string[]>`. */
+function recordKeyFor(ctx, node, target, element) {
+    if (!ts.isElementAccessExpression(target) || !ts.isIdentifier(target.expression))
+        return null;
+    const binding = findBinding(node, target.expression.text);
+    const record = binding?.initializer ? recordOfStringArrays(binding.initializer) : null;
+    if (!record)
+        return null;
+    for (const [key, values] of record)
+        if (values.includes(element))
+            return key;
+    return null;
+}
+/** `X.map((item) => …)` where the callback renders the item, or one field of it. */
+function collectMappedValues(ctx, sourceFile) {
+    const visit = (node) => {
+        const mapped = mapCallbackOf(node);
+        if (mapped)
+            emitMapped(ctx, sourceFile, node, mapped.target, mapped.callback);
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+}
+function emitMapped(ctx, sourceFile, node, target, callback) {
+    const resolved = resolveArrayTarget(ctx, node, target);
+    if (!resolved)
+        return;
+    const body = callback.body;
+    if (!body)
+        return;
+    const where = jsxContextOf(node);
+    const component = enclosingComponentName(node);
+    const collection = resolved.collection;
+    const label = collection ?? "the inline list";
+    // Case 1: the callback renders the item itself, so the array holds visible strings.
+    const strings = arrayOfStrings(ts.factory.createArrayLiteralExpression(resolved.elements.map((element) => unwrapExpression(element))));
+    if (callbackRendersItem(callback) && strings) {
+        const perKey = new Map();
+        resolved.elements.forEach((raw, index) => {
+            const element = unwrapExpression(raw);
+            const recordKey = recordKeyFor(ctx, node, target, element);
+            // Values of one record entry are numbered within that entry; a plain list is numbered once.
+            const position = recordKey ? (perKey.set(recordKey, (perKey.get(recordKey) ?? 0) + 1), perKey.get(recordKey)) : index + 1;
+            emitValue(ctx, {
+                node: element,
+                sourceFile,
+                file: ctx.relFile,
+                source: "data-object",
+                element: where.element,
+                key: recordKey ? String(position) : null,
+                component,
+                collection,
+                itemKey: recordKey ?? String(position),
+                itemTitle: null,
+                classification: "data-object",
+                ambiguous: true,
+                ancestors: where.ancestors,
+                landmark: where.landmark,
+                reason: recordKey
+                    ? `Item ${position} under "${recordKey}" in ${label}, which this element renders as text; confirm the id before migrating.`
+                    : `Item ${position} of ${label}, which this element renders as text; the ordinal is a placeholder, choose a semantic name.`,
+            });
+        });
+        return;
+    }
+    // Case 2: the callback renders fields of each object, including nested lists.
+    const objects = objectElementsOf(resolved.elements);
+    if (!objects)
+        return;
+    const parameter = callback.parameters[0]?.name;
+    const paramName = parameter && ts.isIdentifier(parameter) ? parameter.text : null;
+    const destructured = new Set();
+    if (parameter && ts.isObjectBindingPattern(parameter)) {
+        for (const binding of parameter.elements)
+            if (ts.isIdentifier(binding.name))
+                destructured.add((binding.propertyName && ts.isIdentifier(binding.propertyName) ? binding.propertyName : binding.name).text);
+    }
+    const renderedFields = new Set();
+    const nestedFields = new Set();
+    const walk = (inner) => {
+        if (ts.isJsxExpression(inner) && inner.expression && inner.parent && (ts.isJsxElement(inner.parent) || ts.isJsxFragment(inner.parent))) {
+            const field = fieldNameOf(inner.expression, paramName, destructured);
+            if (field)
+                renderedFields.add(field);
+        }
+        const innerMap = mapCallbackOf(inner);
+        if (innerMap) {
+            const field = fieldNameOf(innerMap.target, paramName, destructured);
+            if (field)
+                nestedFields.add(field);
+        }
+        ts.forEachChild(inner, walk);
+    };
+    walk(body);
+    objects.forEach((object, index) => {
+        const itemKey = stableKeyOf(object, index);
+        const title = ["title", "name", "heading", "label", "question"].map((key) => literalText(propertyOf(object, key) ?? undefined)).find((value) => value) ?? null;
+        for (const field of renderedFields) {
+            const value = propertyOf(object, field);
+            if (!value || literalText(value) === null)
+                continue;
+            emitValue(ctx, {
+                node: unwrapExpression(value),
+                sourceFile,
+                file: ctx.relFile,
+                source: "data-object",
+                element: where.element,
+                key: field,
+                component,
+                collection,
+                itemKey,
+                itemTitle: title,
+                classification: "data-object",
+                reason: `"${field}" field of an item in ${label}; the .map callback renders it as text.`,
+            });
+        }
+        for (const field of nestedFields) {
+            const nested = propertyOf(object, field);
+            if (!nested)
+                continue;
+            const nestedArray = unwrapExpression(nested);
+            if (!ts.isArrayLiteralExpression(nestedArray))
+                continue;
+            const nestedStrings = arrayOfStrings(nestedArray);
+            if (nestedStrings) {
+                nestedStrings.forEach((element, nestedIndex) => {
+                    emitValue(ctx, {
+                        node: element,
+                        sourceFile,
+                        file: ctx.relFile,
+                        source: "data-object",
+                        element: where.element,
+                        // The field and position sit after the item, so the id reads item.field.n.
+                        key: `${field}.${nestedIndex + 1}`,
+                        component,
+                        collection,
+                        itemKey,
+                        itemTitle: title,
+                        classification: "data-object",
+                        ambiguous: true,
+                        reason: `Item ${nestedIndex + 1} of the "${field}" list on an item of ${label}, rendered as text; the ordinal is a placeholder, choose a semantic name.`,
+                    });
+                });
+                continue;
+            }
+            const nestedObjects = objectElementsOf(nestedArray.elements);
+            if (!nestedObjects)
+                continue;
+            const nestedRendered = new Set();
+            const findNested = (inner) => {
+                const innerMap = mapCallbackOf(inner);
+                if (innerMap && fieldNameOf(innerMap.target, paramName, destructured) === field) {
+                    const innerParam = innerMap.callback.parameters[0]?.name;
+                    const innerName = innerParam && ts.isIdentifier(innerParam) ? innerParam.text : null;
+                    const innerBody = innerMap.callback.body;
+                    const innerWalk = (deeper) => {
+                        if (ts.isJsxExpression(deeper) && deeper.expression && deeper.parent && (ts.isJsxElement(deeper.parent) || ts.isJsxFragment(deeper.parent))) {
+                            const nestedField = fieldNameOf(deeper.expression, innerName, new Set());
+                            if (nestedField)
+                                nestedRendered.add(nestedField);
+                        }
+                        ts.forEachChild(deeper, innerWalk);
+                    };
+                    if (innerBody)
+                        innerWalk(innerBody);
+                }
+                ts.forEachChild(inner, findNested);
+            };
+            findNested(body);
+            nestedObjects.forEach((nestedObject, nestedIndex) => {
+                const nestedKey = stableKeyOf(nestedObject, nestedIndex);
+                // A nested item with its own stable key (an href, id or slug) needs no parent prefix.
+                const stable = !/^\d+$/.test(nestedKey);
+                for (const nestedField of nestedRendered) {
+                    const value = propertyOf(nestedObject, nestedField);
+                    if (!value || literalText(value) === null)
+                        continue;
+                    emitValue(ctx, {
+                        node: unwrapExpression(value),
+                        sourceFile,
+                        file: ctx.relFile,
+                        source: "data-object",
+                        element: where.element,
+                        key: nestedField,
+                        component,
+                        collection: field,
+                        itemKey: stable ? nestedKey : `${itemKey}-${nestedKey}`,
+                        itemTitle: title,
+                        classification: "data-object",
+                        reason: `"${nestedField}" of an item in the nested "${field}" list of ${label}; the inner .map renders it as text.`,
+                    });
+                }
+            });
+        }
+    });
+}