Skip to content

Open-source status page, incident response and uptime monitoring

chore: cmdk category group (#2255)

Maximilian Kaske4f09390bff75
diff --git a/apps/web/src/content/cmdk.tsx b/apps/web/src/content/cmdk.tsx
index 8a3d7dabb..cdc572efc 100644
--- a/apps/web/src/content/cmdk.tsx
+++ b/apps/web/src/content/cmdk.tsx
@@ -50,38 +50,28 @@ type ConfigSection = {
items: (ConfigItem | ConfigGroup)[];
};
-// TODO: missing shortcuts
const CONFIG: ConfigSection[] = [
{
type: "group",
heading: "Resources",
items: [
{
- type: "group",
- label: "Search in all pages...",
- heading: "All pages",
- page: "all",
+ type: "item",
+ label: "Go to Docs",
+ href: "/docs",
+ shortcut: "⌘D",
},
{
type: "item",
label: "Go to Home",
href: "/",
+ shortcut: "⌘H",
},
{
type: "item",
label: "Go to Pricing",
href: "/pricing",
- },
- {
- type: "group",
- label: "Search in Docs...",
- heading: "Docs",
- page: "docs",
- },
- {
- type: "item",
- label: "Go to Docs",
- href: "/docs",
+ shortcut: "⌘P",
},
{
type: "item",
@@ -89,6 +79,18 @@ const CONFIG: ConfigSection[] = [
href: "/play/checker",
shortcut: "⌘G",
},
+ {
+ type: "group",
+ label: "Search in all pages...",
+ heading: "All pages",
+ page: "all",
+ },
+ {
+ type: "group",
+ label: "Search in Docs...",
+ heading: "Docs",
+ page: "docs",
+ },
{
type: "group",
label: "Search in Products...",
@@ -272,10 +274,6 @@ export function CmdK({
return () => document.removeEventListener("keydown", down);
}, [open, router]);
- React.useEffect(() => {
- inputRef.current?.focus();
- }, []);
-
// NOTE: Reset search and pages after dialog closes (with delay for animation)
// - if within 1 second of closing, the dialog will not reset
React.useEffect(() => {
@@ -322,7 +320,13 @@ export function CmdK({
</kbd>
</button>
<Dialog open={open} onOpenChange={setOpen}>
- <DialogContent className="top-[15%] translate-y-0 overflow-hidden rounded-none p-0 font-mono shadow-2xl lg:max-w-2xl xl:max-w-3xl">
+ <DialogContent
+ onOpenAutoFocus={(e) => {
+ e.preventDefault();
+ inputRef.current?.focus();
+ }}
+ className="top-[15%] translate-y-0 overflow-hidden rounded-none p-0 font-mono shadow-2xl lg:max-w-2xl xl:max-w-3xl"
+ >
<DialogTitle className="sr-only">Search</DialogTitle>
<Command
onKeyDown={(e) => {
@@ -362,6 +366,7 @@ export function CmdK({
</span>
) : null}
<CommandPrimitive.Input
+ ref={inputRef}
className="placeholder:text-foreground-muted flex h-11 w-full rounded-none bg-transparent py-3 text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50"
placeholder={
page
@@ -395,6 +400,7 @@ export function CmdK({
items={items}
search={search}
setOpen={setOpen}
+ scope={scope}
/>
) : null}
</CommandList>
@@ -489,77 +495,108 @@ function Home({
);
}
+// Bucket, preserving the server's rank order — first key seen is the best-scoring one.
+function bucket<K>(list: SearchResult[], keyOf: (item: SearchResult) => K) {
+ const groups: { key: K; items: SearchResult[] }[] = [];
+ const map = new Map<K, SearchResult[]>();
+ for (const item of list) {
+ const key = keyOf(item);
+ let b = map.get(key);
+ if (!b) {
+ b = [];
+ map.set(key, b);
+ groups.push({ key, items: b });
+ }
+ b.push(item);
+ }
+ return groups;
+}
+
function SearchResults({
items,
search,
setOpen,
+ scope,
}: {
items: SearchResult[];
search: string;
setOpen: React.Dispatch<React.SetStateAction<boolean>>;
+ scope: Corpus | "all";
}) {
const router = useRouter();
- // Bucket by corpus, preserving the server's rank order for both groups and rows.
- const groups: { type: Corpus; items: SearchResult[] }[] = [];
- const byType = new Map<Corpus, SearchResult[]>();
- for (const item of items) {
- let bucket = byType.get(item.type);
- if (!bucket) {
- bucket = [];
- byType.set(item.type, bucket);
- groups.push({ type: item.type, items: bucket });
- }
- bucket.push(item);
- }
-
+ const highlightRe = React.useMemo(
+ () =>
+ search
+ ? new RegExp(search.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i")
+ : null,
+ [search],
+ );
const highlight = (text: string) =>
- search
- ? text.replace(
- new RegExp(search.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i"),
- (match) => `<mark>${match}</mark>`,
- )
+ highlightRe
+ ? text.replace(highlightRe, (match) => `<mark>${match}</mark>`)
: text;
+ const renderRow = (item: SearchResult) => (
+ <CommandItem
+ key={item.href}
+ value={item.href}
+ keywords={[item.metadata.title, item.content, search]}
+ onSelect={() => {
+ router.push(item.href);
+ setOpen(false);
+ }}
+ >
+ <div className="grid min-w-0">
+ <span
+ className="block truncate"
+ // oxlint-disable-next-line react/no-danger
+ dangerouslySetInnerHTML={{ __html: highlight(item.metadata.title) }}
+ />
+ {item.content && search ? (
+ <span
+ className="text-muted-foreground block truncate text-xs"
+ // oxlint-disable-next-line react/no-danger
+ dangerouslySetInnerHTML={{ __html: highlight(item.content) }}
+ />
+ ) : null}
+ </div>
+ </CommandItem>
+ );
+
+ // Split full vs partial matches, then sub-group each tier: by corpus in "all"
+ // scope (kept flat — no category level), by category within a single corpus.
+ const keyOf: (item: SearchResult) => string =
+ scope === "all"
+ ? (item) => CORPUS_LABELS[item.type]
+ : (item) => item.metadata.category || CORPUS_LABELS[item.type];
+
+ const full = bucket(
+ items.filter((i) => i.tier !== "partial"),
+ keyOf,
+ );
+ const partial = bucket(
+ items.filter((i) => i.tier === "partial"),
+ keyOf,
+ );
+
+ const renderGroups = (
+ groups: { key: string; items: SearchResult[] }[],
+ prefix: string,
+ ) =>
+ groups.map((group, index) => (
+ <React.Fragment key={`${prefix}-${group.key}`}>
+ {index > 0 && <CommandSeparator />}
+ <CommandGroup heading={group.key}>
+ {group.items.map(renderRow)}
+ </CommandGroup>
+ </React.Fragment>
+ ));
+
return (
<>
- {groups.map((group, index) => (
- <React.Fragment key={group.type}>
- {index > 0 && <CommandSeparator />}
- <CommandGroup heading={CORPUS_LABELS[group.type]}>
- {group.items.map((item) => (
- <CommandItem
- key={item.href}
- value={item.href}
- keywords={[item.metadata.title, item.content, search]}
- onSelect={() => {
- router.push(item.href);
- setOpen(false);
- }}
- >
- <div className="grid min-w-0">
- <span
- className="block truncate"
- // oxlint-disable-next-line react/no-danger -- highlight markup, content sanitized server-side
- dangerouslySetInnerHTML={{
- __html: highlight(item.metadata.title),
- }}
- />
- {item.content && search ? (
- <span
- className="text-muted-foreground block truncate text-xs"
- // oxlint-disable-next-line react/no-danger -- highlight markup, content sanitized server-side
- dangerouslySetInnerHTML={{
- __html: highlight(item.content),
- }}
- />
- ) : null}
- </div>
- </CommandItem>
- ))}
- </CommandGroup>
- </React.Fragment>
- ))}
+ {renderGroups(full, "full")}
+ {partial.length > 0 ? renderGroups(partial, "partial") : null}
</>
);
}
diff --git a/apps/web/src/content/search-meta.ts b/apps/web/src/content/search-meta.ts
index acb0dd005..69e46dc9f 100644
--- a/apps/web/src/content/search-meta.ts
+++ b/apps/web/src/content/search-meta.ts
@@ -3,17 +3,22 @@ import type { MDXData, PageType } from "./utils";
export type Corpus = Exclude<PageType, "all">;
export const CORPUS_LABELS: Record<Corpus, string> = {
- blog: "blog",
- changelog: "changelog",
- product: "product",
- unrelated: "pages",
- compare: "compare",
- tools: "tools",
- tooling: "tooling",
- customers: "customers",
- guides: "guides",
- "use-case": "use-case",
- docs: "docs",
+ blog: "Blog",
+ changelog: "Changelog",
+ product: "Product",
+ unrelated: "Pages",
+ compare: "Compare",
+ tools: "Tools",
+ tooling: "Tooling",
+ customers: "Customers",
+ guides: "Guides",
+ "use-case": "Use-case",
+ docs: "Docs",
};
-export type SearchResult = MDXData & { type: Corpus };
+export type SearchResult = MDXData & {
+ type: Corpus;
+ // "full" = the query fits (contiguous phrase, or the lone term for 1-word queries);
+ // "partial" = everything weaker (scattered terms, single term of many). Absent when browsing.
+ tier?: "full" | "partial";
+};
diff --git a/apps/web/src/content/utils/search-index.ts b/apps/web/src/content/utils/search-index.ts
index 08657d73a..39f4ee687 100644
--- a/apps/web/src/content/utils/search-index.ts
+++ b/apps/web/src/content/utils/search-index.ts
@@ -3,6 +3,13 @@ import { slugify } from "@/content/mdx";
import { type MDXData, PAGE_TYPES, getHomePage, getPages } from ".";
import type { Corpus, SearchResult } from "../search-meta";
+import {
+ closestHeadingSlug,
+ getContentSnippet,
+ makeMatcher,
+ sanitizeContent,
+ scoreDoc,
+} from "./search-match";
type Heading = { slug: string; index: number };
@@ -81,62 +88,6 @@ function getAll(): IndexedDoc[] {
];
}
-const WEIGHTS = {
- phraseTitle: 100,
- phraseHeading: 60,
- phraseContent: 30,
- termTitle: 10,
- termHeading: 6,
- termContent: 2,
- allTermsBonus: 20,
-} as const;
-
-function scoreDoc(
- entry: IndexedDoc,
- phrase: string,
- terms: string[],
-): { score: number; needle: string | null } {
- let score = 0;
- let needle: string | null = null;
-
- if (entry.titleLower.includes(phrase)) score += WEIGHTS.phraseTitle;
- if (entry.headingsLower.includes(phrase)) score += WEIGHTS.phraseHeading;
- if (entry.sanitizedLower.includes(phrase)) {
- score += WEIGHTS.phraseContent;
- needle = phrase;
- }
-
- let matched = 0;
- for (const term of terms) {
- const inTitle = entry.titleLower.includes(term);
- const inHeading = entry.headingsLower.includes(term);
- const inContent = entry.sanitizedLower.includes(term);
- if (inTitle) score += WEIGHTS.termTitle;
- if (inHeading) score += WEIGHTS.termHeading;
- if (inContent) {
- score += WEIGHTS.termContent;
- if (!needle) needle = term;
- }
- if (inTitle || inHeading || inContent) matched++;
- }
-
- if (terms.length > 1 && matched === terms.length)
- score += WEIGHTS.allTermsBonus;
-
- return { score, needle };
-}
-
-function closestHeadingSlug(entry: IndexedDoc, needle: string): string | null {
- const matchIndex = entry.rawLower.indexOf(needle);
- if (matchIndex === -1 || entry.headings.length === 0) return null;
- let best: string | null = null;
- for (const h of entry.headings) {
- if (h.index <= matchIndex) best = h.slug;
- else break;
- }
- return best;
-}
-
export function searchCorpus(params: {
p: Corpus | "all";
q: string | null | undefined;
@@ -146,7 +97,8 @@ export function searchCorpus(params: {
const query = q?.trim() ?? "";
const phrase = query.toLowerCase();
- const terms = phrase.split(/\s+/).filter(Boolean);
+ // Drop 1-char terms — pure noise that word-boundary matching can't tame.
+ const terms = phrase.split(/\s+/).filter((t) => t.length >= 2);
if (!query) {
return entries
@@ -154,25 +106,37 @@ export function searchCorpus(params: {
.sort(byRecency);
}
- const scored: { entry: IndexedDoc; score: number; needle: string | null }[] =
- [];
+ const matchers = terms.map(makeMatcher);
+ const usePhrase = phrase.includes(" ");
+
+ const scored: {
+ entry: IndexedDoc;
+ score: number;
+ needle: string | null;
+ full: boolean;
+ }[] = [];
for (const entry of entries) {
- const { score, needle } = scoreDoc(entry, phrase, terms);
- if (score > 0) scored.push({ entry, score, needle });
+ const { score, needle, full } = scoreDoc(
+ entry,
+ phrase,
+ usePhrase,
+ matchers,
+ );
+ if (score > 0) scored.push({ entry, score, needle, full });
}
scored.sort(
(a, b) => b.score - a.score || recency(b.entry) - recency(a.entry),
);
- return scored.map(({ entry, needle }) => {
+ return scored.map(({ entry, needle, full }) => {
let href = `${entry.doc.href}?q=${encodeURIComponent(query)}`;
if (needle) {
const slug = closestHeadingSlug(entry, needle);
if (slug) href = `${href}#${slug}`;
}
const snippet = getContentSnippet(entry.sanitized, needle);
- return toResult(entry, snippet, href);
+ return toResult(entry, snippet, href, full ? "full" : "partial");
});
}
@@ -180,8 +144,9 @@ function toResult(
entry: IndexedDoc,
content: string,
href: string,
+ tier?: "full" | "partial",
): SearchResult {
- return { ...entry.doc, type: entry.type, content, href };
+ return { ...entry.doc, type: entry.type, content, href, tier };
}
function recency(entry: IndexedDoc) {
@@ -191,61 +156,3 @@ function recency(entry: IndexedDoc) {
function byRecency(a: SearchResult, b: SearchResult) {
return b.metadata.publishedAt.getTime() - a.metadata.publishedAt.getTime();
}
-
-const WORDS_BEFORE = 2;
-const WORDS_AFTER = 20;
-
-function getContentSnippet(sanitized: string, needle: string | null): string {
- if (!needle) return `${sanitized.slice(0, 100)}...`;
-
- const matchIndex = sanitized.toLowerCase().indexOf(needle.toLowerCase());
- if (matchIndex === -1) return `${sanitized.slice(0, 100)}...`;
-
- let start = matchIndex;
- for (let i = 0; i < WORDS_BEFORE && start > 0; i++) {
- const prevSpace = sanitized.lastIndexOf(" ", start - 2);
- if (prevSpace === -1) break;
- start = prevSpace + 1;
- }
-
- let end = matchIndex + needle.length;
- for (let i = 0; i < WORDS_AFTER && end < sanitized.length; i++) {
- const nextSpace = sanitized.indexOf(" ", end + 1);
- if (nextSpace === -1) {
- end = sanitized.length;
- break;
- }
- end = nextSpace;
- }
-
- let snippet = sanitized.slice(start, end).trim();
- if (!snippet) return snippet;
- if (start > 0) snippet = `...${snippet}`;
- if (end < sanitized.length) snippet = `${snippet}...`;
- return snippet;
-}
-
-export function sanitizeContent(input: string) {
- return stripTags(input)
- .replace(/^#{1,6}\s+/gm, "") // strip markdown heading symbols, keep text
- .replace(/!\[.*?\]\(.*?\)/g, "") // strip images
- .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1") // keep link text
- .replace(/\*\*(.*?)\*\*/g, "$1") // strip bold
- .replace(/__(.*?)__/g, "$1") // strip italic
- .replace(/_(.*?)_/g, "$1") // strip underline
- .replace(/[`*>~]/g, "") // strip most formatting
- .replace(/\s+/g, " ") // collapse whitespace
- .replace(/[<>]/g, (c) => (c === "<" ? "&lt;" : "&gt;")) // escape stray brackets for safe innerHTML
- .trim();
-}
-
-// Loop until stable: stripping a tag can splice fragments into a new tag (`<scr<b>ipt>` → `<script>`).
-function stripTags(input: string) {
- let prev: string;
- let out = input;
- do {
- prev = out;
- out = out.replace(/<[^>]+>/g, "");
- } while (out !== prev);
- return out;
-}
diff --git a/apps/web/src/content/utils/search-match.test.ts b/apps/web/src/content/utils/search-match.test.ts
new file mode 100644
index 000000000..a5c689109
--- /dev/null
+++ b/apps/web/src/content/utils/search-match.test.ts
@@ -0,0 +1,200 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+ type Matcher,
+ closestHeadingSlug,
+ getContentSnippet,
+ makeMatcher,
+ needleIndex,
+ sanitizeContent,
+ scoreDoc,
+} from "./search-match";
+
+describe("makeMatcher", () => {
+ test("prefix match at a word start", () => {
+ expect(makeMatcher("monitor").test("synthetic monitoring")).toBe(true);
+ });
+
+ test("does not match mid-word", () => {
+ expect(makeMatcher("as").test("edge case")).toBe(false);
+ expect(makeMatcher("on").test("python")).toBe(false);
+ });
+
+ test("matches the whole word too", () => {
+ expect(makeMatcher("status").test("openstatus status page")).toBe(true);
+ });
+
+ test("symbol-led term falls back to substring", () => {
+ expect(makeMatcher("@openstatus").test("ping @openstatus now")).toBe(true);
+ // word-boundary would fail here since \b doesn't sit before "@"
+ expect(makeMatcher("@openstatus").test("openstatus")).toBe(false);
+ });
+
+ test("regex metacharacters in the term are escaped", () => {
+ expect(makeMatcher("c++").test("learn c++ today")).toBe(true);
+ expect(makeMatcher("a.b").test("a.b.c")).toBe(true);
+ expect(makeMatcher("a.b").test("axb")).toBe(false);
+ });
+});
+
+describe("needleIndex", () => {
+ test("finds first word-start occurrence, not a mid-word one", () => {
+ // "on" appears mid-word in "python" (index 2) before the standalone "on"
+ expect(needleIndex("python on rails", "on")).toBe(7);
+ });
+
+ test("returns -1 when absent", () => {
+ expect(needleIndex("hello world", "xyz")).toBe(-1);
+ });
+
+ test("symbol-led needle uses substring", () => {
+ expect(needleIndex("ping @here team", "@here")).toBe(5);
+ });
+});
+
+function scorable(parts: {
+ title?: string;
+ headings?: string;
+ content?: string;
+}) {
+ return {
+ titleLower: (parts.title ?? "").toLowerCase(),
+ headingsLower: (parts.headings ?? "").toLowerCase(),
+ sanitizedLower: (parts.content ?? "").toLowerCase(),
+ };
+}
+
+function matchers(...terms: string[]): Matcher[] {
+ return terms.map(makeMatcher);
+}
+
+describe("scoreDoc tiering", () => {
+ test("single-word match is full tier", () => {
+ const r = scoreDoc(
+ scorable({ title: "Monitoring guide" }),
+ "monitor",
+ false,
+ matchers("monitor"),
+ );
+ expect(r.score).toBeGreaterThan(0);
+ expect(r.full).toBe(true);
+ });
+
+ test("multi-word: contiguous phrase is full tier", () => {
+ const r = scoreDoc(
+ scorable({ content: "configure your status page here" }),
+ "status page",
+ true,
+ matchers("status", "page"),
+ );
+ expect(r.full).toBe(true);
+ expect(r.needle).toBe("status page");
+ });
+
+ test("multi-word: scattered all-term match is partial tier", () => {
+ const r = scoreDoc(
+ scorable({ title: "status", content: "the page loads fast" }),
+ "status page",
+ true,
+ matchers("status", "page"),
+ );
+ expect(r.score).toBeGreaterThan(0);
+ expect(r.full).toBe(false);
+ });
+
+ test("scattered all-term outranks a single-term match", () => {
+ const allTerms = scoreDoc(
+ scorable({ title: "status", content: "the page loads" }),
+ "status page",
+ true,
+ matchers("status", "page"),
+ );
+ const oneTerm = scoreDoc(
+ scorable({ title: "status only" }),
+ "status page",
+ true,
+ matchers("status", "page"),
+ );
+ expect(allTerms.score).toBeGreaterThan(oneTerm.score);
+ });
+
+ test("no match scores zero and is not full", () => {
+ const r = scoreDoc(
+ scorable({ title: "unrelated" }),
+ "monitor",
+ false,
+ matchers("monitor"),
+ );
+ expect(r.score).toBe(0);
+ expect(r.full).toBe(false);
+ });
+});
+
+describe("closestHeadingSlug", () => {
+ const entry = {
+ rawLower: "# intro\nwelcome\n## setup\nconfigure the probe here",
+ headings: [
+ { slug: "intro", index: 0 },
+ { slug: "setup", index: 16 },
+ ],
+ };
+
+ test("returns the nearest preceding heading for the needle", () => {
+ expect(closestHeadingSlug(entry, "probe")).toBe("setup");
+ });
+
+ test("returns null when needle is absent", () => {
+ expect(closestHeadingSlug(entry, "missing")).toBeNull();
+ });
+
+ test("uses word-boundary index, ignoring a mid-word occurrence", () => {
+ // "on" appears mid-word in "python" (heading 1) but stands alone under "deploy".
+ // Plain indexOf would anchor on "python"; word-boundary matching reaches "deploy".
+ const e = {
+ rawLower: "# python\n## deploy\nrun on this",
+ headings: [
+ { slug: "python", index: 0 },
+ { slug: "deploy", index: 9 },
+ ],
+ };
+ expect(closestHeadingSlug(e, "on")).toBe("deploy");
+ });
+});
+
+describe("getContentSnippet", () => {
+ test("no needle returns a leading excerpt", () => {
+ expect(getContentSnippet("hello world of monitoring", null)).toBe(
+ "hello world of monitoring...",
+ );
+ });
+
+ test("centers the snippet on the needle with surrounding context", () => {
+ const text = "alpha beta gamma delta epsilon zeta eta theta";
+ const snippet = getContentSnippet(text, "delta");
+ expect(snippet).toContain("delta");
+ expect(snippet.startsWith("...")).toBe(true);
+ });
+
+ test("falls back to leading excerpt when needle is absent from content", () => {
+ expect(getContentSnippet("hello world", "xyz").startsWith("hello")).toBe(
+ true,
+ );
+ });
+});
+
+describe("sanitizeContent", () => {
+ test("strips markdown and escapes stray brackets", () => {
+ const out = sanitizeContent("# Title\n**bold** [link](/x) <3");
+ expect(out).toContain("Title");
+ expect(out).toContain("bold");
+ expect(out).toContain("link");
+ expect(out).not.toContain("(/x)");
+ expect(out).toContain("&lt;3");
+ });
+
+ test("removes spliced tags that reform after a single pass", () => {
+ expect(sanitizeContent("<scr<b>ipt>alert(1)</scr<b>ipt>")).not.toContain(
+ "<script>",
+ );
+ });
+});
diff --git a/apps/web/src/content/utils/search-match.ts b/apps/web/src/content/utils/search-match.ts
new file mode 100644
index 000000000..1a7ec59d9
--- /dev/null
+++ b/apps/web/src/content/utils/search-match.ts
@@ -0,0 +1,187 @@
+// Pure text matching + scoring for the search index. No `server-only`, no corpus
+// imports — kept dependency-free so it's unit-testable in isolation.
+
+export const WEIGHTS = {
+ phraseTitle: 100,
+ phraseHeading: 60,
+ phraseContent: 30,
+ termTitle: 10,
+ termHeading: 6,
+ termContent: 2,
+ allTermsBonus: 20,
+} as const;
+
+const WORDS_BEFORE = 2;
+const WORDS_AFTER = 20;
+
+function escapeRegExp(input: string): string {
+ return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// True when the term begins with a letter/number, so a `\b` anchor is meaningful.
+// Symbol-led terms (e.g. "@openstatus") can't anchor — `\b` doesn't sit before a
+// non-word char — and fall back to substring matching.
+function isWordLed(term: string): boolean {
+ return /^[\p{L}\p{N}]/u.test(term);
+}
+
+export type Matcher = { term: string; test: (text: string) => boolean };
+
+// Match at a word start, prefix allowed: "monitor" hits "monitoring", but "as" no
+// longer hits "case". Note `\b` is ASCII-only even under the `u` flag, so boundary
+// detection around accented letters is approximate — acceptable for our corpus.
+export function makeMatcher(term: string): Matcher {
+ if (!isWordLed(term)) {
+ return { term, test: (text) => text.includes(term) };
+ }
+ const re = new RegExp(`\\b${escapeRegExp(term)}`, "u");
+ return { term, test: (text) => re.test(text) };
+}
+
+// Index of the first word-start occurrence (ASCII boundary), or the first substring
+// occurrence for symbol-led needles. Both inputs must already be lowercased.
+export function needleIndex(
+ haystackLower: string,
+ needleLower: string,
+): number {
+ if (isWordLed(needleLower)) {
+ const m = new RegExp(`\\b${escapeRegExp(needleLower)}`, "u").exec(
+ haystackLower,
+ );
+ if (m) return m.index;
+ }
+ return haystackLower.indexOf(needleLower);
+}
+
+type Scorable = {
+ titleLower: string;
+ headingsLower: string;
+ sanitizedLower: string;
+};
+
+export function scoreDoc(
+ entry: Scorable,
+ phrase: string,
+ usePhrase: boolean,
+ matchers: Matcher[],
+): { score: number; needle: string | null; full: boolean } {
+ let score = 0;
+ let needle: string | null = null;
+ let phraseMatched = false;
+
+ // Skip phrase scoring for single-word queries — there the lone term matcher already
+ // covers it, and `.includes` on one word would reintroduce mid-word matches.
+ if (usePhrase) {
+ if (entry.titleLower.includes(phrase)) {
+ score += WEIGHTS.phraseTitle;
+ phraseMatched = true;
+ }
+ if (entry.headingsLower.includes(phrase)) {
+ score += WEIGHTS.phraseHeading;
+ phraseMatched = true;
+ }
+ if (entry.sanitizedLower.includes(phrase)) {
+ score += WEIGHTS.phraseContent;
+ phraseMatched = true;
+ needle = phrase;
+ }
+ }
+
+ let matched = 0;
+ for (const m of matchers) {
+ const inTitle = m.test(entry.titleLower);
+ const inHeading = m.test(entry.headingsLower);
+ const inContent = m.test(entry.sanitizedLower);
+ if (inTitle) score += WEIGHTS.termTitle;
+ if (inHeading) score += WEIGHTS.termHeading;
+ if (inContent) {
+ score += WEIGHTS.termContent;
+ if (!needle) needle = m.term;
+ }
+ if (inTitle || inHeading || inContent) matched++;
+ }
+
+ if (matchers.length > 1 && matched === matchers.length)
+ score += WEIGHTS.allTermsBonus;
+
+ // Tier 1 = the query "fits": the contiguous phrase for multi-word queries, or the
+ // lone term for single-word. Scattered all-term matches drop to tier 2 (they still
+ // rank above single-term ones there, via allTermsBonus).
+ const full = usePhrase
+ ? phraseMatched
+ : matchers.length > 0 && matched === matchers.length;
+
+ return { score, needle, full };
+}
+
+export function closestHeadingSlug(
+ entry: { rawLower: string; headings: { slug: string; index: number }[] },
+ needle: string,
+): string | null {
+ const matchIndex = needleIndex(entry.rawLower, needle);
+ if (matchIndex === -1 || entry.headings.length === 0) return null;
+ let best: string | null = null;
+ for (const h of entry.headings) {
+ if (h.index <= matchIndex) best = h.slug;
+ else break;
+ }
+ return best;
+}
+
+export function getContentSnippet(
+ sanitized: string,
+ needle: string | null,
+): string {
+ if (!needle) return `${sanitized.slice(0, 100)}...`;
+
+ const matchIndex = needleIndex(sanitized.toLowerCase(), needle.toLowerCase());
+ if (matchIndex === -1) return `${sanitized.slice(0, 100)}...`;
+
+ let start = matchIndex;
+ for (let i = 0; i < WORDS_BEFORE && start > 0; i++) {
+ const prevSpace = sanitized.lastIndexOf(" ", start - 2);
+ if (prevSpace === -1) break;
+ start = prevSpace + 1;
+ }
+
+ let end = matchIndex + needle.length;
+ for (let i = 0; i < WORDS_AFTER && end < sanitized.length; i++) {
+ const nextSpace = sanitized.indexOf(" ", end + 1);
+ if (nextSpace === -1) {
+ end = sanitized.length;
+ break;
+ }
+ end = nextSpace;
+ }
+
+ let snippet = sanitized.slice(start, end).trim();
+ if (!snippet) return `${sanitized.slice(0, 100)}...`;
+ if (start > 0) snippet = `...${snippet}`;
+ if (end < sanitized.length) snippet = `${snippet}...`;
+ return snippet;
+}
+
+export function sanitizeContent(input: string) {
+ return stripTags(input)
+ .replace(/^#{1,6}\s+/gm, "") // strip markdown heading symbols, keep text
+ .replace(/!\[.*?\]\(.*?\)/g, "") // strip images
+ .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1") // keep link text
+ .replace(/\*\*(.*?)\*\*/g, "$1") // strip bold
+ .replace(/__(.*?)__/g, "$1") // strip italic
+ .replace(/_(.*?)_/g, "$1") // strip underline
+ .replace(/[`*>~]/g, "") // strip most formatting
+ .replace(/\s+/g, " ") // collapse whitespace
+ .replace(/[<>]/g, (c) => (c === "<" ? "&lt;" : "&gt;")) // escape stray brackets for safe innerHTML
+ .trim();
+}
+
+// Loop until stable: stripping a tag can splice fragments into a new tag (`<scr<b>ipt>` → `<script>`).
+function stripTags(input: string) {
+ let prev: string;
+ let out = input;
+ do {
+ prev = out;
+ out = out.replace(/<[^>]+>/g, "");
+ } while (out !== prev);
+ return out;
+}