@getrefino/onboarding 0.1.0-rc.1

package/dist/ids.js

@@ -0,0 +1,367 @@
+/**
+ * Semantic content ID proposals: `<page>.<section>.<role>` built from the
+ * route, the enclosing component or landmark, and the element's role.
+ * Never from line numbers or array indexes. When naming is uncertain the
+ * candidate is flagged for review instead of accepting a poor ID.
+ */
+import { isContentId } from "@getrefino/core";
+const STOP_WORDS = new Set(["a", "an", "the", "and", "or", "of", "to", "in", "on", "for", "with", "your", "our", "is", "are", "that", "this", "it", "at", "by", "from", "you", "we", "i", "can", "do", "does", "how", "what", "will", "my", "me", "be", "when", "where", "why", "as"]);
+export function camel(words) {
+    const clean = words.map((word) => word.replace(/[^\p{L}\p{N}]/gu, "")).filter(Boolean);
+    if (clean.length === 0)
+        return "";
+    return clean
+        .map((word, index) => {
+        const lower = word.toLowerCase();
+        return index === 0 ? lower : lower.charAt(0).toUpperCase() + lower.slice(1);
+    })
+        .join("");
+}
+export function slugFromText(text, maxWords = 3) {
+    const words = text
+        .replace(/['’]/g, "")
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter(Boolean);
+    const significant = words.filter((word) => !STOP_WORDS.has(word.toLowerCase()));
+    const seen = new Set();
+    const unique = (significant.length > 0 ? significant : words).filter((word) => {
+        const key = word.toLowerCase();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    return camel(unique.slice(0, maxWords));
+}
+/** Last meaningful segment of a site path: "/features/privacy" -> "privacy", "/#how-it-works" -> "howItWorks", "/" -> "home". */
+export function pathSegment(path) {
+    const cleaned = path.replace(/^\/#?/, "").replace(/#/g, "/");
+    const last = cleaned.split("/").filter(Boolean).pop() ?? "home";
+    return slugFromText(last.replace(/[-_.]+/g, " "), 3) || "home";
+}
+function segmentFromIdentifier(name) {
+    const words = name
+        .replace(/[-_]+/g, " ")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .split(/\s+/)
+        .filter(Boolean);
+    return camel(words);
+}
+const COMPONENT_ALIASES = {
+    nav: "nav",
+    navbar: "nav",
+    navigation: "nav",
+    header: "nav",
+    siteheader: "nav",
+    topbar: "nav",
+    footer: "footer",
+    sitefooter: "footer",
+    hero: "hero",
+    faq: "faq",
+    faqs: "faq",
+    cta: "cta",
+    calltoaction: "cta",
+    ctaband: "cta",
+    testimonial: "testimonial",
+    testimonials: "testimonial",
+    pricing: "pricing",
+    features: "features",
+    feature: "features",
+};
+const PAGE_COMPONENT = /^(home|homepage|index|page|app|root|main|layout|rootlayout|default)(page|screen|view)?$/i;
+export function componentSegment(component) {
+    if (!component)
+        return null;
+    const stripped = component.replace(/(Section|Component|Block|Widget|Container|Wrapper|Page|Screen|View|Route)$/, "") || component;
+    if (PAGE_COMPONENT.test(stripped) || PAGE_COMPONENT.test(component))
+        return null;
+    const alias = COMPONENT_ALIASES[stripped.toLowerCase()];
+    if (alias)
+        return alias;
+    const segment = segmentFromIdentifier(stripped);
+    return segment || null;
+}
+export function routeSegment(route, scope) {
+    if (scope === "shared")
+        return "shared";
+    if (!route || route === "/")
+        return "home";
+    const parts = route
+        .split("/")
+        .filter(Boolean)
+        .map((part) => segmentFromIdentifier(part.replace(/^\[+\.*|\]+$/g, "")))
+        .filter(Boolean);
+    return parts.join(".") || "home";
+}
+/** Map component names to the native element they stand in for. */
+export function normalizeElement(element) {
+    if (!element)
+        return "";
+    const bare = element.replace(/^.*\./, "");
+    if (/^(a|A|Anchor)$/.test(bare) || /Link$/.test(bare))
+        return "a";
+    if (/^(button|Btn)$/.test(bare) || /Button$/.test(bare))
+        return "button";
+    if (/^(Heading|Title|H1|H2)$/.test(bare))
+        return "h2";
+    if (/^(Text|Paragraph|P|Body)$/.test(bare))
+        return "p";
+    return bare.toLowerCase() === bare ? bare : bare;
+}
+/** Components named after a typographic role (`<Eyebrow>`, `<Lead>`, `<Note>`). */
+const COMPONENT_ROLES = [
+    [/^(Eyebrow|Kicker|Overline|Pretitle|SuperTitle)$/i, "eyebrow"],
+    [/^(Tagline)$/i, "tagline"],
+    [/^(Subtitle|Subheading|Lead|Intro|Description)$/i, "subtitle"],
+    [/^(Note|Caption|FinePrint|Hint|Disclaimer|Footnote)$/i, "note"],
+    [/^(Badge|Pill|Tag|Chip)$/i, "badge"],
+    [/^(Quote|Testimonial|Blockquote)$/i, "quote"],
+    [/^(Label)$/i, "label"],
+];
+function componentRole(element) {
+    if (!element)
+        return null;
+    const bare = element.replace(/^.*\./, "");
+    if (!/^[A-Z]/.test(bare))
+        return null;
+    for (const [pattern, role] of COMPONENT_ROLES)
+        if (pattern.test(bare))
+            return role;
+    return null;
+}
+function isButtonLike(candidate) {
+    const className = candidate.context.className ?? "";
+    const element = normalizeElement(candidate.element);
+    return element === "button" || /(^|[\s_-])(btn|button|cta)([\s_-]|$)/i.test(className) || (element === "a" && /(^|[\s_-])(btn|button|cta)/i.test(className));
+}
+const CLASS_ROLES = [
+    [/(^|[\s_-])(eyebrow|kicker|overline|pretitle|pre-title)([\s_-]|$)/i, "eyebrow"],
+    [/(^|[\s_-])(tagline)([\s_-]|$)/i, "tagline"],
+    [/(^|[\s_-])(subtitle|sub-title|subheading|lead|intro|description|desc)([\s_-]|$)/i, "subtitle"],
+    [/(^|[\s_-])(note|fine-print|fineprint|disclaimer|caption|hint)([\s_-]|$)/i, "note"],
+    [/(^|[\s_-])(badge|pill|tag|chip)([\s_-]|$)/i, "badge"],
+    [/(^|[\s_-])(quote|testimonial)([\s_-]|$)/i, "quote"],
+    [/(^|[\s_-])(author|name)([\s_-]|$)/i, "name"],
+    [/(^|[\s_-])(role|job-title|position)([\s_-]|$)/i, "role"],
+    [/(^|[\s_-])(price|amount)([\s_-]|$)/i, "price"],
+    [/(^|[\s_-])(copyright)([\s_-]|$)/i, "copyright"],
+    // Typographic scale utilities (text-display, text-h3, text-body) say what an element is.
+    [/(^|\s)(text-)?(display|headline)(\s|$)/i, "title"],
+    [/(^|\s)text-h[1-6](\s|$)/i, "heading"],
+    [/(^|\s)text-body(\s|$)/i, "body"],
+];
+function classRole(className) {
+    if (!className)
+        return null;
+    for (const [pattern, role] of CLASS_ROLES)
+        if (pattern.test(className))
+            return role;
+    return null;
+}
+function isShortLabel(text) {
+    return text.split(/\s+/).length <= 3 && text.length <= 32;
+}
+function roleFor(candidate) {
+    const element = normalizeElement(candidate.element);
+    const text = candidate.text;
+    const inNav = candidate.context.ancestors.includes("nav") || candidate.context.landmark === "nav" || candidate.component?.toLowerCase().includes("nav") === true;
+    const inFooter = candidate.context.ancestors.includes("footer") || candidate.context.landmark === "footer";
+    const inFaq = /faq/i.test(candidate.context.landmark ?? "") || /faq/i.test(candidate.component ?? "");
+    if (candidate.source === "jsx-attribute" || candidate.source === "data-object") {
+        return { role: candidate.key ?? "text", fromText: false };
+    }
+    if (isButtonLike(candidate))
+        return { role: "cta", fromText: false };
+    const fromComponent = componentRole(candidate.element);
+    if (fromComponent)
+        return { role: fromComponent, fromText: false };
+    const hinted = classRole(candidate.context.className);
+    if (hinted && ["span", "p", "div", "small", "em", "strong"].includes(element))
+        return { role: hinted, fromText: false };
+    switch (element) {
+        case "h1":
+            return { role: "title", fromText: false };
+        case "h2":
+            return { role: "title", fromText: false };
+        case "h3":
+        case "h4":
+        case "h5":
+        case "h6":
+            return { role: "heading", fromText: false };
+        case "p":
+            return { role: "body", fromText: false };
+        case "blockquote":
+        case "q":
+            return { role: "quote", fromText: false };
+        case "figcaption":
+            return { role: "caption", fromText: false };
+        case "label":
+        case "legend":
+            return { role: "label", fromText: false };
+        case "small":
+            return { role: "note", fromText: false };
+        case "dt":
+            return { role: inFaq ? "question" : "term", fromText: false };
+        case "dd":
+            return { role: inFaq ? "answer" : "definition", fromText: false };
+        case "summary":
+            return { role: "question", fromText: false };
+        case "a":
+        case "li":
+        case "span":
+        case "th":
+        case "td":
+        case "strong":
+        case "em":
+        case "b":
+        case "i":
+            if ((inNav || inFooter || element === "a" || element === "li") && isShortLabel(text))
+                return { role: slugFromText(text), fromText: true };
+            return { role: element === "a" ? "link" : "text", fromText: false };
+        default:
+            return { role: "text", fromText: false };
+    }
+}
+function itemSegment(candidate) {
+    const { itemKey, itemTitle } = candidate.context;
+    if (itemKey)
+        return { segment: segmentFromIdentifier(itemKey) || null, derivedFromText: false };
+    if (itemTitle)
+        return { segment: slugFromText(itemTitle, 2) || null, derivedFromText: true };
+    return { segment: null, derivedFromText: false };
+}
+function baseIdFor(candidate) {
+    const page = routeSegment(candidate.context.route, candidate.scope);
+    const pageLeaf = page.slice(page.lastIndexOf(".") + 1).toLowerCase();
+    const componentRaw = componentSegment(candidate.component);
+    // A page component named after its route (About, PricingPage) adds nothing.
+    const component = componentRaw && componentRaw.toLowerCase() === pageLeaf ? null : componentRaw;
+    const rawLandmark = candidate.context.landmark ? segmentFromIdentifier(candidate.context.landmark) : null;
+    const landmark = rawLandmark ? (COMPONENT_ALIASES[rawLandmark.toLowerCase()] ?? rawLandmark) : null;
+    const sectionCandidates = [component, landmark].filter((value) => value !== null && value.toLowerCase() !== pageLeaf);
+    const section = sectionCandidates[0] ?? null;
+    const second = sectionCandidates[1] ?? null;
+    const redundant = !second ||
+        !section ||
+        second === section ||
+        second.toLowerCase().includes(section.toLowerCase()) ||
+        section.toLowerCase().includes(second.toLowerCase()) ||
+        /^(nav|header|footer|section|aside|article|main|card|grid|list|item)$/.test(second);
+    const extraSection = redundant ? null : second;
+    if (candidate.source === "data-object") {
+        // Named after the component that maps the array, then the array when it adds information
+        // (a footer that maps GUIDES and COMPANY_LINKS), then the item, then the field.
+        const collectionIdentifier = candidate.context.collection ? segmentFromIdentifier(candidate.context.collection) : null;
+        const collectionRaw = collectionIdentifier ? (COMPONENT_ALIASES[collectionIdentifier.toLowerCase()] ?? collectionIdentifier) : null;
+        const overlaps = collectionRaw && section && (collectionRaw.toLowerCase().includes(section.toLowerCase()) || section.toLowerCase().includes(collectionRaw.toLowerCase()));
+        // An array imported from a data module may be rendered by several components (nav links in
+        // the header and the footer); the module's own collection name is its stable section, whichever
+        // component happens to map it.
+        const sectionForData = candidate.context.collectionImported && collectionRaw ? collectionRaw : section;
+        const collection = overlaps || sectionForData === collectionRaw ? null : collectionRaw;
+        const item = itemSegment(candidate);
+        const parts = [page, sectionForData, collection, item.segment, candidate.key].filter((value) => Boolean(value));
+        const id = parts.join(".");
+        if (!item.segment)
+            return { id: null, review: true, reason: "Data item has no id/key/slug or title to name it by." };
+        return { id, review: item.derivedFromText, reason: item.derivedFromText ? `Item key "${item.segment}" was derived from its text; give it a semantic key (edit the id, then apply it to every field of the item).` : null };
+    }
+    if (candidate.source === "jsx-attribute") {
+        const owner = candidate.element ? segmentFromIdentifier(candidate.element.replace(/^.*\./, "")) : null;
+        const item = itemSegment(candidate);
+        const ownerSegment = owner && owner !== section ? owner : null;
+        // The item key is only needed to tell several same-named components apart; a lone
+        // <SectionHeader title="…"> is simply section.sectionHeader.title.
+        const needsItem = candidate.context.siblingCount > 1 || (item.segment !== null && !item.derivedFromText);
+        const parts = [page, section, extraSection, ownerSegment, needsItem ? item.segment : null, candidate.key].filter((value) => Boolean(value));
+        const id = parts.join(".");
+        const reviewItem = needsItem && item.derivedFromText;
+        return { id, review: reviewItem, reason: reviewItem ? `Element key "${item.segment}" was derived from its text; rename it to something semantic.` : null };
+    }
+    const role = roleFor(candidate);
+    // FAQ-style pairs are keyed by their question, and texts inside a figure / list item /
+    // article by that item's first short label, so each group stays together.
+    const pairKey = candidate.context.itemTitle ? slugFromText(candidate.context.itemTitle, 3) : null;
+    const parts = [page, section, extraSection, pairKey, role.role].filter((value) => Boolean(value));
+    return { id: parts.join("."), review: false, reason: null };
+}
+function isShortHeadingLabel(text) {
+    return text.split(/\s+/).length <= 3 && text.length <= 32;
+}
+/**
+ * Assign IDs to all candidates, resolving collisions semantically where
+ * possible (second CTA -> secondaryCta) and flagging the rest for review.
+ */
+export function proposeIds(candidates) {
+    const results = [];
+    const bases = candidates.map((raw) => ({ raw, base: baseIdFor(raw) }));
+    // Several short headings sharing one base id (footer columns, a row of feature titles)
+    // are told apart by their own label: shared.footer.company.title, not title3.
+    const headingGroups = new Map();
+    for (const { raw, base } of bases) {
+        if (!base.id || !/\.(title|heading)$/.test(base.id) || raw.source !== "jsx-text")
+            continue;
+        headingGroups.set(base.id, (headingGroups.get(base.id) ?? 0) + 1);
+    }
+    const labelledHeadings = new Set();
+    for (const [id, count] of headingGroups) {
+        if (count > 1 && bases.every(({ raw, base }) => base.id !== id || isShortHeadingLabel(raw.text)))
+            labelledHeadings.add(id);
+    }
+    /** How many times each base id was proposed. */
+    const proposed = new Map();
+    /** Final ids handed out. */
+    const used = new Set();
+    for (const { raw, base } of bases) {
+        if (!base.id || !isContentId(base.id)) {
+            results.push({ raw, id: null, idReason: base.reason ?? `Could not build a valid ID from "${raw.text.slice(0, 40)}".`, review: true });
+            continue;
+        }
+        let id = base.id;
+        let review = base.review;
+        let reason = base.reason;
+        if (labelledHeadings.has(id) && raw.source === "jsx-text") {
+            const leaf = id.slice(id.lastIndexOf(".") + 1);
+            const prefix = id.slice(0, id.lastIndexOf("."));
+            const label = slugFromText(raw.text, 3);
+            if (label && isContentId(`${prefix}.${label}.${leaf}`))
+                id = `${prefix}.${label}.${leaf}`;
+        }
+        const count = proposed.get(id) ?? 0;
+        proposed.set(id, count + 1);
+        if (count > 0) {
+            const leaf = id.slice(id.lastIndexOf(".") + 1);
+            const prefix = id.slice(0, id.lastIndexOf("."));
+            const hrefKey = raw.source === "jsx-text" && raw.context.href && (leaf === "cta" || leaf === "link") ? pathSegment(raw.context.href) : null;
+            // Alternative states of one element ("Saving…" / "Save") are not a second
+            // call to action or a subtitle; they are the same slot, so they keep an
+            // ordinal and the reviewer names them.
+            const alternative = raw.context.ambiguous === true;
+            if (leaf === "cta" && count === 1 && !alternative) {
+                id = `${prefix}.secondaryCta`;
+            }
+            else if (hrefKey && hrefKey !== "home" && isContentId(`${prefix}.${hrefKey}${leaf === "cta" ? "Cta" : "Link"}`)) {
+                // A third call to action or another long link: the path it points to is its stable identity.
+                id = `${prefix}.${hrefKey}${leaf === "cta" ? "Cta" : "Link"}`;
+            }
+            else if (leaf === "title" && count === 1 && !alternative) {
+                id = `${prefix}.subtitle`;
+                review = true;
+                reason = `Second title-level heading in the same section; confirm "${id}" is the right name.`;
+            }
+            else {
+                id = `${prefix}.${leaf}${count + 1}`;
+                review = true;
+                reason = `Repeated "${leaf}" in the same section; the ordinal suffix is a placeholder, choose a semantic name.`;
+            }
+        }
+        while (used.has(id)) {
+            id = `${id}x`;
+            review = true;
+        }
+        used.add(id);
+        results.push({ raw, id, idReason: reason, review });
+    }
+    return results;
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { inspectRepository, appDirectory, packageManagerInstall, packageManagerRun } from "./inspect.js";
+export type { InspectOptions } from "./inspect.js";
+export { scanCopy, scanFile, decodeJsxEntities, isUtilityClass } from "./scan.js";
+export type { ScanOptions } from "./scan.js";
+export { proposeIds, slugFromText, componentSegment, routeSegment } from "./ids.js";
+export { buildPlan, planMigration, planContent, defaultContentFile, integrationPoints, hostIntegration, hostLabel, resolveRefinoSite, verificationCommands, PLAN_DIR, PLAN_FILE, INSTRUCTIONS_FILE, CONFIG_FILE, BOILERPLATE_DIR, TOOL_NAME, TOOL_VERSION, dependencyRange, } from "./plan.js";
+export { renderAgentInstructions } from "./agent.js";
+export { applyPlan } from "./apply.js";
+export type { ApplyOptions, RefinoConfig } from "./apply.js";
+export { boilerplateFiles, ENV_EXAMPLE_BLOCK } from "./templates.js";
+export type { TemplateFile } from "./templates.js";
+export { DEFAULT_REFINO_APP_URL, REFINO_SITE_ID_PATTERN, hostedFiles } from "./templates-hosted.js";
+export type { RefinoSiteConfig } from "./templates-hosted.js";
+export { verifyIntegration } from "./verify.js";
+export type { VerifyOptions } from "./verify.js";
+export type { ApplyResult, CandidateStatus, CheckStatus, CopyCandidate, CopyClassification, DetectedPackage, Framework, GitState, HostIntegration, HostKind, Language, MigrationPlan, PackageManager, PlanOptions, PlannedFile, RefinoSite, RepositoryInspection, RouteInfo, Router, ScanResult, ScriptSet, VerificationCheck, VerificationResult, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { inspectRepository, appDirectory, packageManagerInstall, packageManagerRun } from "./inspect.js";
+export { scanCopy, scanFile, decodeJsxEntities, isUtilityClass } from "./scan.js";
+export { proposeIds, slugFromText, componentSegment, routeSegment } from "./ids.js";
+export { buildPlan, planMigration, planContent, defaultContentFile, integrationPoints, hostIntegration, hostLabel, resolveRefinoSite, verificationCommands, PLAN_DIR, PLAN_FILE, INSTRUCTIONS_FILE, CONFIG_FILE, BOILERPLATE_DIR, TOOL_NAME, TOOL_VERSION, dependencyRange, } from "./plan.js";
+export { renderAgentInstructions } from "./agent.js";
+export { applyPlan } from "./apply.js";
+export { boilerplateFiles, ENV_EXAMPLE_BLOCK } from "./templates.js";
+export { DEFAULT_REFINO_APP_URL, REFINO_SITE_ID_PATTERN, hostedFiles } from "./templates-hosted.js";
+export { verifyIntegration } from "./verify.js";

package/dist/inspect.d.ts

@@ -0,0 +1,19 @@
+import type { PackageManager, RepositoryInspection } from "./types.js";
+export interface InspectOptions {
+    /** Path of the app inside a monorepo, relative to root. Auto-detected otherwise. */
+    readonly app?: string;
+}
+/** The `packages:` entries of a pnpm-workspace.yaml (block list or inline array). */
+export declare function pnpmWorkspacePackages(yaml: string): string[];
+/** The runtime packages a migrated site depends on, and the names they had before the Refino rename. */
+export declare const REFINO_PACKAGES: readonly ["@getrefino/core", "@getrefino/react", "@getrefino/github"];
+export declare const LEGACY_PACKAGES: readonly ["@inline-copy/core", "@inline-copy/react", "@inline-copy/github"];
+export declare const CONFIG_FILE_NAME = "refino.config.json";
+export declare const LEGACY_CONFIG_FILE_NAME = "inline-copy.config.json";
+export declare function inspectRepository(rootPath: string, options?: InspectOptions): RepositoryInspection;
+/** Absolute path of the app directory for an inspection. */
+export declare function appDirectory(inspection: RepositoryInspection): string;
+export declare function packageManagerRun(pm: PackageManager, script: string): string;
+/** Run a binary from node_modules through the package manager. */
+export declare function packageManagerExec(pm: PackageManager, command: string): string;
+export declare function packageManagerInstall(pm: PackageManager): string;