@avocadostudio-ai/shared 0.3.2 → 0.4.0

package/dist/links.js

@@ -0,0 +1,509 @@
+/**
+ * What a link field's string actually means.
+ *
+ * A link is stored as a plain string — `/pricing`, `https://example.com`,
+ * `mailto:hi@example.com` — and three places need to agree on how to read it:
+ * the editor's link control (which icon, which label, which warning), the
+ * `seo.internal-link-dead` check (is this route real?), and the rename rewriter
+ * (is this string a route at all?). Before this module each answered the
+ * question with its own inline `startsWith("/")`, and they did not agree: the
+ * rename rewriter matched on prop *names* containing "href", so a link stored
+ * under `url` or inside Footer's `label|url` text went stale on every rename.
+ *
+ * Nothing here validates in the blocking sense. A path this module cannot
+ * resolve is still a legitimate link — on a CMS-backed site Avocado sees only
+ * the pages it was handed, and a route can exist in Next, in the CMS, or behind
+ * a rewrite and be invisible from here. `resolveLink` reports what it knows; it
+ * never decides what the editor may type.
+ */
+/**
+ * Extensions that mean "this path is a document, not a route".
+ *
+ * A site's menu PDF lives at `/downloads/menu-de.pdf`, which has every
+ * syntactic property of an internal route and is not one. Classified as a page
+ * it resolves against the slug list, matches nothing, and comes back
+ * `missing: true` — so the editor's link field shows a broken-page warning on
+ * a link that works, and `seo.internal-link-dead` would report every document
+ * on the site. The distinction cannot come from the shape of the string; the
+ * extension is the only signal there is.
+ *
+ * Deliberately documents and archives only. Images are absent because an image
+ * belongs to the `image` kind and its own picker, and media extensions are
+ * absent because a `.mp4` in a link is nearly always an embed URL. A path with
+ * no extension, or one not listed here, stays a page — the failure that costs
+ * something is calling a route a file, not the reverse.
+ */
+const FILE_EXTENSIONS = new Set([
+    "pdf",
+    "doc", "docx", "rtf", "odt",
+    "xls", "xlsx", "csv", "ods",
+    "ppt", "pptx", "odp",
+    "zip", "gz", "tar",
+    "txt", "ics", "vcf", "epub"
+]);
+/**
+ * The extension of a path, lowercased, or "" — from the last segment only, so
+ * a dot in a directory name (`/v1.2/guide`) is not read as one.
+ */
+function extensionOf(path) {
+    const segment = path.split("/").pop() ?? "";
+    const dot = segment.lastIndexOf(".");
+    if (dot <= 0 || dot === segment.length - 1)
+        return "";
+    return segment.slice(dot + 1).toLowerCase();
+}
+/** Does this route-shaped path name a document rather than a page? */
+export function isFilePath(path) {
+    return FILE_EXTENSIONS.has(extensionOf(path));
+}
+/**
+ * The file extensions this module recognises, for a caller that has to describe
+ * them — an upload control's `accept`, a picker's filter, a docs page.
+ */
+export function knownFileExtensions() {
+    return [...FILE_EXTENSIONS];
+}
+/**
+ * A bare "/" is the default value every link field is born with
+ * (`defaultScalarForField`), so treating it as a real link to the homepage
+ * would make every freshly added card claim to link somewhere.
+ */
+function isEmptyValue(value) {
+    return value === "" || value === "/";
+}
+/** Classify a link string. Never throws; anything unrecognised parses as `page`-ish text. */
+export function parseLink(value) {
+    const raw = typeof value === "string" ? value : "";
+    const trimmed = raw.trim();
+    if (isEmptyValue(trimmed))
+        return { kind: "empty", raw };
+    if (/^mailto:/i.test(trimmed)) {
+        return { kind: "email", raw, target: trimmed.replace(/^mailto:/i, "") };
+    }
+    if (/^tel:/i.test(trimmed)) {
+        return { kind: "phone", raw, target: trimmed.replace(/^tel:/i, "") };
+    }
+    if (trimmed.startsWith("#")) {
+        return { kind: "anchor", raw, target: trimmed.slice(1) };
+    }
+    if (/^https?:\/\//i.test(trimmed)) {
+        let target = trimmed;
+        try {
+            const u = new URL(trimmed);
+            target = u.host + (u.pathname === "/" ? "" : u.pathname);
+        }
+        catch {
+            /* keep the raw string — a half-typed URL is still an external link */
+        }
+        return { kind: "external", raw, target };
+    }
+    /*
+     * A protocol-relative `//host/path` is external, not a route. Without this it
+     * would parse as a path and be reported dead against every site's slug list —
+     * and `draft-mode.ts` already rejects it for the same reason on the way in.
+     */
+    if (trimmed.startsWith("//"))
+        return { kind: "external", raw, target: trimmed.slice(2) };
+    /*
+     * Anything else is a route. Not only strings starting with "/": an editor who
+     * types "pricing" means the pricing page, and `normalizeLinkPath` is what
+     * turns that into one. Treating it as a page is also what lets the picker
+     * offer matches while you type.
+     */
+    const [pathPart = "", ...rest] = trimmed.split(/(?=[?#])/);
+    const suffix = rest.join("") || undefined;
+    /*
+     * A document is not a route. Decided here rather than at each call site so
+     * the editor's warning, the dead-link check and the rename rewriter cannot
+     * disagree about it — the reason this module exists at all.
+     */
+    if (isFilePath(pathPart)) {
+        return { kind: "file", raw, path: pathPart, suffix, target: pathPart };
+    }
+    return { kind: "page", raw, path: pathPart, suffix };
+}
+/**
+ * Give a route its leading slash and drop a trailing one.
+ *
+ * `pricing`, `/pricing`, `/pricing/` are the same page. The editor accepts all
+ * three and stores the middle one. The homepage keeps its lone slash.
+ */
+export function normalizeLinkPath(path) {
+    const trimmed = path.trim();
+    if (trimmed === "" || trimmed === "/")
+        return "/";
+    const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return withSlash.length > 1 ? withSlash.replace(/\/+$/, "") : withSlash;
+}
+/**
+ * Does this route exist among the site's known pages?
+ *
+ * Compares on the path alone — a link may legitimately carry a query or a
+ * fragment, and neither changes which page it points at — and accepts a
+ * trailing slash on either side. This is the matcher `seo.internal-link-dead`
+ * uses, extracted so the inline field warning and the checks panel cannot
+ * disagree about what "dead" means.
+ */
+export function isKnownRoute(path, knownSlugs) {
+    const known = knownSlugs instanceof Set ? knownSlugs : new Set(knownSlugs);
+    const target = path.split(/[?#]/)[0] ?? "";
+    const normalized = normalizeLinkPath(target);
+    return known.has(target) || known.has(normalized) || known.has(`${normalized}/`);
+}
+/** Compare two link paths the way a reader would: slashes and case-in-host aside. */
+function samePath(a, b) {
+    return normalizeLinkPath(a) === normalizeLinkPath(b);
+}
+/**
+ * Classify a link *and* look up its target. Pages may be keyed by `slug` or by
+ * `path` (they differ on locale-prefixed sites — see
+ * `docs/ideas/page-identity-punch-list.md`), so both are matched.
+ *
+ * `files` is optional and its absence is meaningful — see `missing` above.
+ */
+export function resolveLink(value, pages = [], files) {
+    const parsed = parseLink(value);
+    if (parsed.kind === "file") {
+        if (!files)
+            return parsed;
+        const wanted = parsed.path ?? "";
+        const file = files.find((f) => samePath(f.path, wanted));
+        return file ? { ...parsed, file } : { ...parsed, missing: true };
+    }
+    if (parsed.kind !== "page")
+        return parsed;
+    const wanted = normalizeLinkPath(parsed.path ?? "");
+    const page = pages.find((p) => normalizeLinkPath(p.slug) === wanted || (p.path != null && normalizeLinkPath(p.path) === wanted));
+    if (page)
+        return { ...parsed, page };
+    return { ...parsed, missing: true };
+}
+// ---------------------------------------------------------------------------
+// Suggesting a page
+// ---------------------------------------------------------------------------
+/** Words in a slug, a path or a title, lowercased and punctuation-free. */
+function tokenize(value) {
+    return value.toLowerCase().split(/[^a-z0-9]+/i).filter((t) => t.length > 0);
+}
+/** Everything a page can be recognised by: its slug, its URL and its title. */
+function pageTokens(page) {
+    return [...new Set([...tokenize(page.slug), ...tokenize(page.path ?? ""), ...tokenize(page.title ?? "")])];
+}
+/**
+ * How much each word says about *which* page is meant.
+ *
+ * A word every page carries — a locale prefix, the company name — identifies
+ * nothing, and counting it equally is what makes a naive matcher propose
+ * `/de/impressum` for `/de/veranstaltungen`: the two share only the "de". This
+ * is inverse document frequency over the site's own pages, smoothed so a word
+ * on no page at all still has a finite weight.
+ */
+function tokenWeights(pages) {
+    const total = pages.length;
+    const seen = new Map();
+    for (const page of pages) {
+        for (const token of pageTokens(page))
+            seen.set(token, (seen.get(token) ?? 0) + 1);
+    }
+    const weights = new Map();
+    for (const [token, count] of seen)
+        weights.set(token, Math.log(1 + total / (count + 1)));
+    return weights;
+}
+function weightOf(token, weights, total) {
+    if (!weights)
+        return 1;
+    return weights.get(token) ?? Math.log(1 + total);
+}
+/**
+ * How well a page answers what was typed, from 0 (nothing in common) to 1.
+ *
+ * The balanced mean of precision and recall over shared words. Balanced because
+ * both halves are wrong alone: precision by itself ranks a sprawling page that
+ * happens to contain the word above the page actually named for it, and recall
+ * by itself ranks a one-word slug above every longer match.
+ *
+ * Pass the site's pages as `corpus` to weight words by how distinctive they are
+ * (see `tokenWeights`); without it every word counts the same.
+ */
+export function scoreLinkCandidate(query, page, corpus) {
+    const wanted = [...new Set(tokenize(query))];
+    if (wanted.length === 0)
+        return 0;
+    const have = pageTokens(page);
+    if (have.length === 0)
+        return 0;
+    const weights = corpus ? tokenWeights(corpus) : undefined;
+    const total = corpus?.length ?? 0;
+    const w = (token) => weightOf(token, weights, total);
+    const sum = (tokens) => tokens.reduce((acc, t) => acc + w(t), 0);
+    const shared = wanted.filter((t) => have.includes(t));
+    if (shared.length === 0)
+        return 0;
+    const overlap = sum(shared);
+    const precision = overlap / sum(wanted);
+    const recall = overlap / sum(have);
+    return (2 * precision * recall) / (precision + recall);
+}
+/**
+ * Below this a "did you mean" is noise, and a wrong suggestion is worse than
+ * none — the editor has to stop and rule it out.
+ */
+const SUGGESTION_MIN_SCORE = 0.45;
+/**
+ * Known pages ranked by how well they answer `query`, best first.
+ *
+ * Held to the same floor as `suggestLinkTarget`, which it did not used to be:
+ * anything sharing a single token came back, so on a tri-lingual site every
+ * `/fr/*` page answered every French-flavoured query. Typing a document path
+ * into the link picker listed `/fr/`, `/fr/faq/` and `/fr/evenements/` — six
+ * rows of pages, each one click away from replacing a working PDF link with a
+ * link to the FAQ. A near-miss still ranks well above the floor; what the floor
+ * removes is the coincidence.
+ */
+export function rankLinkTargets(query, pages) {
+    return pages
+        .map((page) => ({ page, score: scoreLinkCandidate(query, page, pages) }))
+        .filter((entry) => entry.score >= SUGGESTION_MIN_SCORE)
+        .sort((a, b) => b.score - a.score)
+        .map((entry) => entry.page);
+}
+/** A document, in the shape the page scorer reads. */
+function fileAsPage(file) {
+    return { slug: file.path, ...(file.name ? { title: file.name } : {}) };
+}
+/**
+ * Known documents ranked by how well they answer `query`, best first.
+ *
+ * The same scorer as pages, and the corpus weighting is what makes it work
+ * here: every document on a site shares its directory and its extension, so
+ * `downloads` and `pdf` identify nothing and are weighted to nearly nothing,
+ * while the part of the filename someone got wrong is what decides the order.
+ *
+ * This is the half a substring filter cannot do. `AadventureArenaBerm` is a
+ * real filename on a real site, typo included; a person typing it from memory
+ * gets one character wrong and a substring match returns nothing at all —
+ * which reads exactly like "this site has no such document".
+ */
+export function rankFileTargets(query, files) {
+    const corpus = files.map(fileAsPage);
+    return files
+        .map((file) => ({ file, score: scoreLinkCandidate(query, fileAsPage(file), corpus) }))
+        .filter((entry) => entry.score >= SUGGESTION_MIN_SCORE)
+        .sort((a, b) => b.score - a.score)
+        .map((entry) => entry.file);
+}
+/**
+ * The pages and documents to offer for a partly-typed link.
+ *
+ * Two surfaces ask this question — the property panel's link field and the
+ * prose editor's link popover — and they answered it with their own inline
+ * copies of "substring, else rank". The copies disagreed, and both made the
+ * same mistake: they ranked *pages* for a query the parser had already
+ * classified as a document. A screenshot of the result is why this function
+ * exists — `/downloads/…-Gruppen-FR.pdf` typed in, six pages offered, not one
+ * of the site's fifteen PDFs among them.
+ *
+ * So the kind decides which list is offered at all:
+ *
+ * - a document path offers documents, never pages;
+ * - a route offers pages, and any document whose path literally contains what
+ *   was typed (`menu` should still find the menu PDFs);
+ * - `mailto:`, `tel:`, `#anchor` and `https://` offer neither — there is
+ *   nothing on this site they could mean, and the caller's empty state can say
+ *   so instead.
+ *
+ * Within a kind, a literal substring is what a person typing into a box
+ * expects, and ranking is the fallback for when nothing matches literally.
+ */
+export function suggestLinkTargets(query, options = {}) {
+    const { pages = [], files, limit = 6, browseFiles = false } = options;
+    const trimmed = query.trim();
+    const kind = parseLink(trimmed).kind;
+    if (kind === "empty") {
+        return {
+            pages: pages.slice(0, limit),
+            files: browseFiles ? (files ?? []).slice(0, limit) : []
+        };
+    }
+    if (kind !== "page" && kind !== "file")
+        return { pages: [], files: [] };
+    const needle = trimmed.toLowerCase();
+    const matchesFile = (file) => file.path.toLowerCase().includes(needle) || (file.name ?? "").toLowerCase().includes(needle);
+    const known = files ?? [];
+    const literalFiles = known.filter(matchesFile);
+    const fileMatches = literalFiles.length > 0 ? literalFiles : kind === "file" ? rankFileTargets(trimmed, known) : [];
+    if (kind === "file")
+        return { pages: [], files: fileMatches.slice(0, limit) };
+    const literalPages = pages.filter((page) => page.slug.toLowerCase().includes(needle) ||
+        (page.path ?? "").toLowerCase().includes(needle) ||
+        (page.title ?? "").toLowerCase().includes(needle));
+    const pageMatches = literalPages.length > 0 ? literalPages : rankLinkTargets(trimmed, pages);
+    return { pages: pageMatches.slice(0, limit), files: fileMatches.slice(0, limit) };
+}
+/**
+ * The page a dead internal link probably meant.
+ *
+ * `/avocado-sustainability` on a site that has `/sustainability` is a typo, a
+ * stale link, or a slug someone renamed by hand — and the site already holds
+ * everything needed to say so. Returns undefined when nothing scores well
+ * enough, or when the link already resolves; the caller offers what comes back,
+ * and never applies it on the editor's behalf.
+ */
+export function suggestLinkTarget(value, pages) {
+    const resolved = resolveLink(value, pages);
+    if (resolved.kind !== "page" || !resolved.missing)
+        return undefined;
+    const best = pages
+        .map((page) => ({ page, score: scoreLinkCandidate(resolved.path ?? "", page, pages) }))
+        .sort((a, b) => b.score - a.score)[0];
+    return best && best.score >= SUGGESTION_MIN_SCORE ? best.page : undefined;
+}
+/**
+ * The absolute URL a viewer would copy out of the address bar, turned back into
+ * an internal route — when it belongs to this site.
+ *
+ * Pasting the address bar is how people actually get a URL, and an absolute one
+ * survives right up until the site moves domain. Returns undefined when the
+ * origin is someone else's, so the caller leaves the link alone.
+ */
+export function internalPathForUrl(value, siteOrigin) {
+    if (!siteOrigin)
+        return undefined;
+    let url;
+    let origin;
+    try {
+        url = new URL(value);
+        origin = new URL(siteOrigin);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.host !== origin.host)
+        return undefined;
+    return normalizeLinkPath(url.pathname) + url.search + url.hash;
+}
+/**
+ * The prop holding the "open in new tab" flag for a link prop, by convention.
+ *
+ * `ctaHref` → `ctaNewTab`, `secondaryCtaHref` → `secondaryCtaNewTab`,
+ * `href` → `newTab`. The same shape as the `image`/`imageAlt` pairing the
+ * property panel already resolves by name, so a block declares two props and
+ * the editor renders one control.
+ */
+export function newTabKeyFor(linkKey) {
+    const base = linkKey.replace(/href$/i, "");
+    return base ? `${base}NewTab` : "newTab";
+}
+/** Anchor attributes for a link, given its stored value and new-tab flag. */
+export function linkAttrs(href, newTab) {
+    const value = typeof href === "string" && href.length > 0 ? href : "#";
+    /*
+     * `noopener` is not decoration. A `_blank` link without it hands the opened
+     * page a live `window.opener` handle on this one, which is a real
+     * cross-origin hazard and the reason the pair always ships together.
+     */
+    if (newTab === true && parseLink(value).kind === "external") {
+        return { href: value, target: "_blank", rel: "noopener noreferrer" };
+    }
+    return { href: value };
+}
+// ---------------------------------------------------------------------------
+// Links written inside prose
+// ---------------------------------------------------------------------------
+/**
+ * Every href inside a richtext value.
+ *
+ * A link is not only a `link`-kind prop. Most of the links on a real page are
+ * written *into* prose — `[Menükarte](/downloads/menu-de.pdf)` — and every
+ * link-aware surface we have was walking declared fields only. So the four
+ * menu-PDF links on a live site's Bistro section were not checked, not
+ * rewritten on rename, and not reported; the one linking to a filename with a
+ * typo in it had been wrong since August with nothing able to notice.
+ *
+ * Three shapes, because a richtext value is three things depending on where it
+ * came from: markdown (a site that projects its CMS prose to markdown), a
+ * ProseMirror document (the editor's own format), and raw HTML (a block with a
+ * loose schema). Walking all three costs one function and means a caller never
+ * has to know which it was handed.
+ *
+ * Returns hrefs in document order, duplicates included — a caller that reports
+ * findings wants one per occurrence, and a caller that wants a set can make one.
+ */
+export function linksInRichText(value) {
+    const out = [];
+    collectLinks(value, out);
+    return out;
+}
+/**
+ * Markdown inline links. Images (`![alt](src)`) are matched only so the leading
+ * `!` can be seen and the match discarded — an image src is not a link and must
+ * not be route-checked.
+ *
+ * Two forms for the destination, because markdown has two: `<...>`, which
+ * exists precisely so a path may contain spaces, and the bare form, which may
+ * not. Written as separate branches rather than one optional bracket, since a
+ * pattern that forbids spaces inside the brackets silently drops exactly the
+ * links the brackets were there for.
+ */
+const MARKDOWN_LINK_RE = /(!?)\[(?:[^\]\\]|\\.)*\]\(\s*(?:<([^>]*)>|([^\s)]+))(?:\s+["'(][^)]*)?\s*\)/g;
+const HTML_HREF_RE = /<a\b[^>]*?\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s">]+))/gi;
+function collectLinks(value, out) {
+    if (typeof value === "string") {
+        for (const m of value.matchAll(MARKDOWN_LINK_RE)) {
+            // `!` marks an image, whose src is not a link and must not be route-checked.
+            if (m[1] === "!")
+                continue;
+            const href = m[2] ?? m[3];
+            if (href)
+                out.push(href);
+        }
+        for (const m of value.matchAll(HTML_HREF_RE)) {
+            const href = m[1] ?? m[2] ?? m[3];
+            if (href)
+                out.push(href);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collectLinks(entry, out);
+        return;
+    }
+    if (typeof value !== "object" || value === null)
+        return;
+    const node = value;
+    /*
+     * A ProseMirror link is a mark on a text node, and Portable Text keeps the
+     * same idea in `markDefs`. Both put the target under `href`, so reading that
+     * covers the editor's own documents and a CMS's alike.
+     */
+    const marks = node.marks;
+    if (Array.isArray(marks)) {
+        for (const mark of marks) {
+            if (typeof mark !== "object" || mark === null)
+                continue;
+            const attrs = mark.attrs;
+            const href = isRecordish(attrs) ? attrs.href : undefined;
+            if (typeof href === "string" && href)
+                out.push(href);
+        }
+    }
+    const markDefs = node.markDefs;
+    if (Array.isArray(markDefs)) {
+        for (const def of markDefs) {
+            const href = isRecordish(def) ? def.href : undefined;
+            if (typeof href === "string" && href)
+                out.push(href);
+        }
+    }
+    if (typeof node.href === "string" && node.href && node.type !== "image")
+        out.push(node.href);
+    for (const key of ["content", "children", "blocks"]) {
+        if (Array.isArray(node[key]))
+            collectLinks(node[key], out);
+    }
+}
+function isRecordish(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/shared",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/richtext": "^0.3.2"
+    "@avocadostudio-ai/richtext": "^0.4.0"
   },
   "devDependencies": {
     "tsx": "^4.21.0",