pi-weave 0.1.22 → 0.2.0

package/src/core/links/repair.ts

@@ -0,0 +1,330 @@
+/**
+ * Deterministic stale-link detection and repair for the vault.
+ *
+ * A wiki-link goes stale for two reasons: the note it pointed at was renamed
+ * or moved (and nothing rewrote the inbound links), or it was written by hand
+ * as a bare title — `[[Quarterly Roadmap]]` — while the note lives at
+ * `planning/roadmap-2026`.
+ * Graph building already notices both (`GraphModel.danglingLinks`) but only
+ * ever reports a count. This module resolves and repairs them.
+ *
+ * ## Why no fuzzy matching
+ *
+ * The resolver is a ladder of three rules, each of which must produce
+ * **exactly one** candidate to fire:
+ *
+ *   1. exact slug        — the target already names a note; nothing to do
+ *   2. unique basename   — `roadmap-2026` → `planning/roadmap-2026`
+ *   3. unique slug-title — front-matter `title` slugified
+ *
+ * Two candidates is *ambiguous* and is reported, never guessed. Zero is
+ * *unresolvable* and is reported so a human can write the note or drop the
+ * link. There is no edit distance, no scoring, no embedding: a repair pass
+ * that is only probably right is worse than no repair pass, because it
+ * silently rewrites knowledge. The degenerate case here is always "ask the
+ * human", never "wrong link".
+ *
+ * ## Relationship to `GraphModel.danglingLinks`
+ *
+ * Not the same set, deliberately. `buildGraph` counts every `[[…]]` in a body,
+ * including ones inside code fences and below the `## Raw` tail, because
+ * over-reporting a link on a graph is harmless. This module reports the
+ * **safe-to-repair subset**, so it excludes both: a link in a code sample is
+ * a string literal, and a link in the raw tail is the user's quoted words.
+ * An audit total below the graph's dangling count is therefore expected.
+ *
+ * Pure: no I/O lives here. The disk-touching repair entry points are in
+ * `../vault` (`repairVaultLinks`, and the backlink rewrite that rename/move
+ * perform), which already owns the vault lock and the write path. The
+ * dependency runs one way — vault imports repair, never the reverse — so
+ * there is no import cycle to reason about at 3am.
+ */
+
+import { slugify } from "../slug";
+import type { HtmlArtifact, Note } from "../types";
+
+/**
+ * The append-only tail heading.
+ *
+ * Defined here rather than in `vault.ts` (which re-exports it, so its public
+ * API is unchanged) because repair is the module that must *not* cross it,
+ * and vault imports repair. One definition, no cycle.
+ */
+export const RAW_NOTES_HEADING = "## Raw";
+
+/** One `[[wiki-link]]` found in a body, with enough context to rewrite it. */
+export interface LinkOccurrence {
+  /** Index of the opening `[[` in the body. */
+  start: number;
+  /** Index just past the closing `]]`. */
+  end: number;
+  /** The link target as written, before normalisation. */
+  rawTarget: string;
+  /** The target normalised to a slug, the way the graph builder sees it. */
+  target: string;
+  /** The pipe alias, when the link has one. */
+  alias: string | undefined;
+}
+
+/**
+ * Normalise a link target to a slug.
+ *
+ * Deliberately identical to `extractWikilinks` (`../graph/wikilinks.ts`):
+ * if repair normalised differently from graph building, the audit would
+ * report links the graph considers fine, or miss ones it flags. HTML
+ * artifacts keep their extension — it is part of their identity.
+ */
+export function normalizeTarget(raw: string): string {
+  const trimmed = raw.trim();
+  return /\.html?$/i.test(trimmed)
+    ? trimmed.replace(/\\/g, "/").replace(/^\.\//, "")
+    : trimmed
+        .split("/")
+        .map((part) => slugify(part))
+        .join("/");
+}
+
+const WIKILINK_RE = /\[\[([^\][|]+)(?:\|([^\]]*))?\]\]/g;
+const FENCE_RE = /^[ \t]*(`{3,}|~{3,})(.*)$/gm;
+/** A `## Raw` heading on a line of its own — not `## Rawhide`. */
+const RAW_HEADING_RE = new RegExp(`^${RAW_NOTES_HEADING}[ \\t]*\\r?$`, "m");
+
+/**
+ * Half-open `[start, end)` ranges covering fenced code blocks.
+ *
+ * CommonMark, not "every third-backtick-line toggles": a fence is closed only
+ * by the **same marker character**, at **at least the opening length**, and
+ * with no info string. Treating fences as a blind alternation gets two cases
+ * backwards — a `~~~` nested inside a ``` block would close it, and a ```
+ * inside a ```` block would too — and each mistake ends the protected region
+ * early, exposing example links in documentation to rewriting.
+ */
+function fenceRanges(body: string): [number, number][] {
+  const ranges: [number, number][] = [];
+  let open: { at: number; marker: string; length: number } | null = null;
+  for (const match of body.matchAll(FENCE_RE)) {
+    const run = match[1]!;
+    // Group 2 is `(.*)`, which always participates: the info string.
+    const info = match[2]!;
+    if (open === null) {
+      open = { at: match.index, marker: run[0]!, length: run.length };
+    } else if (run[0] === open.marker && run.length >= open.length && info.trim() === "") {
+      ranges.push([open.at, match.index + match[0].length]);
+      open = null;
+    }
+  }
+  // An unterminated fence runs to the end of the body, the way a renderer
+  // treats it.
+  if (open !== null) ranges.push([open.at, body.length]);
+  return ranges;
+}
+
+/**
+ * The byte offset where the `## Raw` tail begins, or the body length when
+ * there is none.
+ *
+ * The tail is append-only and verbatim — "NEVER edit below this line" is
+ * written into every note that has one. A link inside a user's dictation is
+ * *their* text, quoted; repairing it would edit words the vault promises not
+ * to touch.
+ *
+ * Fence-aware, and for the opposite reason to everything else here: a note
+ * *documenting* the raw-tail convention contains `## Raw` inside a code
+ * sample, and treating that as the real tail would silently protect — and so
+ * refuse to repair — every link below it. Matching a whole heading line also
+ * keeps `## Rawhide` from starting a tail.
+ */
+function rawTailStart(body: string, fences: readonly [number, number][]): number {
+  let from = 0;
+  for (;;) {
+    const rest = body.slice(from);
+    const hit = RAW_HEADING_RE.exec(rest);
+    if (hit === null) return body.length;
+    const at = from + hit.index;
+    const fence = fences.find(([a, b]) => at >= a && at < b);
+    if (fence === undefined) return at;
+    from = fence[1]; // skip the whole fenced block and keep looking
+  }
+}
+
+/**
+ * Every repairable `[[wiki-link]]` in a body, in order.
+ *
+ * Skips the `## Raw` tail and fenced code blocks. `extractWikilinks` does
+ * neither, on purpose: it feeds the graph, where over-reporting a link is
+ * harmless. Here the output drives a rewrite, so a `[[…]]` inside a code
+ * sample is a string literal and must stay one.
+ */
+export function scanLinks(body: string): LinkOccurrence[] {
+  const fences = fenceRanges(body);
+  const limit = rawTailStart(body, fences);
+  const out: LinkOccurrence[] = [];
+  for (const match of body.matchAll(WIKILINK_RE)) {
+    const start = match.index;
+    if (start >= limit) break;
+    if (fences.some(([a, b]) => start >= a && start < b)) continue;
+    // Group 1 is mandatory in WIKILINK_RE, and `split` always yields at
+    // least one segment: both `!`s below are the regex's guarantee, not
+    // optimism.
+    const rawTarget = match[1]!;
+    if (rawTarget.trim().length === 0) continue;
+    out.push({
+      start,
+      end: start + match[0].length,
+      rawTarget: rawTarget.trim(),
+      target: normalizeTarget(rawTarget),
+      alias: match[2],
+    });
+  }
+  return out;
+}
+
+/**
+ * Rewrite link targets in a body. `resolve` returns the new slug for a
+ * target, or null to leave the link alone.
+ *
+ * The alias is preserved — `[[Quarterly Roadmap]]` becomes
+ * `[[planning/roadmap-2026|Quarterly Roadmap]]`, and `[[Quarterly Roadmap|Q2]]`
+ * becomes `[[planning/roadmap-2026|Q2]]` — so the rendered
+ * prose is byte-identical before and after a repair. A human rereading the
+ * note sees no diff; only the graph changes.
+ */
+export function rewriteLinks(body: string, resolve: (target: string) => string | null): { body: string; changed: number } {
+  const occurrences = scanLinks(body);
+  let out = "";
+  let cursor = 0;
+  let changed = 0;
+  for (const occ of occurrences) {
+    const to = resolve(occ.target);
+    if (to === null || to === occ.target) continue;
+    const alias = occ.alias ?? occ.rawTarget;
+    out += body.slice(cursor, occ.start) + `[[${to}|${alias}]]`;
+    cursor = occ.end;
+    changed++;
+  }
+  return { body: out + body.slice(cursor), changed };
+}
+
+/** One link that resolves to exactly one note and can be rewritten. */
+export interface LinkFix {
+  /** The note containing the stale link. */
+  slug: string;
+  /** The stale target, normalised. */
+  from: string;
+  /** The note it unambiguously means. */
+  to: string;
+  /** Which ladder rung resolved it. */
+  rule: "basename" | "title";
+  /** Occurrences of this target in this note. */
+  count: number;
+}
+
+/** A stale link with more than one candidate: reported, never repaired. */
+export interface AmbiguousLink {
+  slug: string;
+  target: string;
+  candidates: string[];
+}
+
+/** A stale link with no candidate at all, and who points at it. */
+export interface UnresolvableLink {
+  target: string;
+  /** Note slugs referencing it, sorted. */
+  notes: string[];
+}
+
+/** The result of one audit pass over a vault. */
+export interface LinkAudit {
+  /** Every link occurrence considered (raw tail and code fences excluded). */
+  total: number;
+  /** Occurrences already pointing at a real note or artifact. */
+  resolved: number;
+  /** Unambiguously repairable, sorted by note then target. */
+  fixable: LinkFix[];
+  /** Multiple candidates — a human has to choose. */
+  ambiguous: AmbiguousLink[];
+  /** No candidate: the note was never written. */
+  unresolvable: UnresolvableLink[];
+}
+
+/** The slice of a vault snapshot the audit needs. */
+export interface LinkAuditInput {
+  notes: readonly Pick<Note, "slug" | "title" | "body">[];
+  artifacts?: readonly Pick<HtmlArtifact, "slug">[];
+}
+
+function indexBy<T>(items: readonly T[], key: (item: T) => string): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  for (const item of items) {
+    const k = key(item);
+    const list = out.get(k);
+    if (list) list.push((item as { slug: string }).slug);
+    else out.set(k, [(item as { slug: string }).slug]);
+  }
+  return out;
+}
+
+/**
+ * Audit every wiki-link in a vault. Pure: no I/O, no clock, no randomness —
+ * the same vault always produces the same audit, which is what makes the
+ * repair reviewable.
+ */
+export function auditLinks(input: LinkAuditInput): LinkAudit {
+  const notes = input.notes;
+  const slugs = new Set(notes.map((n) => n.slug));
+  const artifactSlugs = new Set((input.artifacts ?? []).map((a) => a.slug));
+  const byBasename = indexBy(notes, (n) => n.slug.split("/").pop()!);
+  const byTitle = indexBy(notes, (n) => slugify(n.title));
+
+  let total = 0;
+  let resolved = 0;
+  // Keyed `slug\u0000target` so repeated occurrences of the same stale link
+  // in one note collapse into a single fix carrying a count.
+  const fixes = new Map<string, LinkFix>();
+  const ambiguous: AmbiguousLink[] = [];
+  const unresolvable = new Map<string, Set<string>>();
+
+  for (const note of notes) {
+    const seenAmbiguous = new Set<string>();
+    for (const occ of scanLinks(note.body)) {
+      total++;
+      if (slugs.has(occ.target) || artifactSlugs.has(occ.target)) {
+        resolved++;
+        continue;
+      }
+      const basename = occ.target.split("/").pop()!;
+      const byBase = byBasename.get(basename) ?? [];
+      const byTtl = byTitle.get(basename) ?? [];
+      const rule: LinkFix["rule"] | null = byBase.length === 1 ? "basename" : byTtl.length === 1 ? "title" : null;
+      const to = rule === "basename" ? byBase[0] : rule === "title" ? byTtl[0] : undefined;
+      if (rule !== null && to !== undefined) {
+        const key = `${note.slug}\u0000${occ.target}`;
+        const existing = fixes.get(key);
+        if (existing) existing.count++;
+        else fixes.set(key, { slug: note.slug, from: occ.target, to, rule, count: 1 });
+        continue;
+      }
+      const candidates = [...new Set([...byBase, ...byTtl])].sort();
+      if (candidates.length > 1) {
+        if (!seenAmbiguous.has(occ.target)) {
+          seenAmbiguous.add(occ.target);
+          ambiguous.push({ slug: note.slug, target: occ.target, candidates });
+        }
+        continue;
+      }
+      const refs = unresolvable.get(occ.target);
+      if (refs) refs.add(note.slug);
+      else unresolvable.set(occ.target, new Set([note.slug]));
+    }
+  }
+
+  return {
+    total,
+    resolved,
+    fixable: [...fixes.values()].sort((a, b) => a.slug.localeCompare(b.slug) || a.from.localeCompare(b.from)),
+    ambiguous: ambiguous.sort((a, b) => a.slug.localeCompare(b.slug) || a.target.localeCompare(b.target)),
+    unresolvable: [...unresolvable.entries()]
+      .map(([target, notes]) => ({ target, notes: [...notes].sort() }))
+      .sort((a, b) => a.target.localeCompare(b.target)),
+  };
+}

package/src/core/links/similar.ts

@@ -0,0 +1,279 @@
+/**
+ * Suggest connections between notes that are related but not linked.
+ *
+ * The companion to `repair.ts`, and deliberately the opposite kind of tool.
+ * Repair fixes a link that exists and points wrong: the answer is exact, so
+ * repair writes. This finds links that were never written: the answer is a
+ * *ranking*, so this only ever reports. A soft signal must not produce a hard
+ * `[[link]]` — once written into a body it is indistinguishable from one the
+ * user wrote deliberately, and a wrong link is worse than a missing one
+ * because a missing link is visible and a wrong one is believed.
+ *
+ * ## The signal
+ *
+ * Classic IDF-weighted cosine over every term a note carries — title words,
+ * tags, and body words, all in one bag. Terms are weighted by how rare they
+ * are *in this vault*:
+ *
+ *     idf(t) = ln(N / df(t))
+ *
+ * That one line is why nothing here is domain-specific. A tag on 2400 of
+ * 2500 notes scores ~0 and cannot connect anything; a ticket id on 6 notes
+ * scores high and connects them strongly. The vault decides what is
+ * meaningful by frequency, so there is no list of "important" fields to keep
+ * up to date, and a vault of recipes clusters by ingredient exactly as a
+ * vault of meeting notes clusters by project. No field names appear in this
+ * file for the same reason.
+ *
+ * ## Why cosine, not Jaccard
+ *
+ * Weighted Jaccard divides by the union, so it punishes length mismatch: a
+ * short journal entry and a long profile about the same subject score low
+ * purely for differing in size. Cosine normalises each note by its own
+ * magnitude, which is the behaviour wanted when comparing documents of
+ * uneven length.
+ *
+ * Pure: no I/O, no clock.
+ */
+
+import { slugify } from "../slug";
+import type { Note } from "../types";
+import { scanLinks } from "./repair";
+
+/** One suggested connection, with the evidence for it. */
+export interface LinkSuggestion {
+  /** The two notes, ordered so `a` < `b` — a suggestion has no direction. */
+  a: string;
+  b: string;
+  /** Cosine similarity over IDF-weighted terms, 0..1. */
+  score: number;
+  /**
+   * The terms that earned the score, strongest first.
+   *
+   * The most important field here. A bare number is unreviewable — "0.16,
+   * trust me" — while "they share `acme-1234`, `release-pipeline`" is a claim
+   * a human can accept or reject in a second. A suggestion nobody can check
+   * is a suggestion nobody should act on.
+   */
+  shared: string[];
+}
+
+/** What {@link suggestLinks} was asked for, and what it found. */
+export interface SuggestionReport {
+  /** Notes considered (those with at least one distinctive term). */
+  considered: number;
+  /** Suggestions, strongest first, then by slug for determinism. */
+  suggestions: LinkSuggestion[];
+}
+
+export interface SuggestOptions {
+  /** Only suggest neighbours of this note. Omit for vault-wide pairs. */
+  slug?: string;
+  /** Maximum suggestions returned. Default 20. */
+  limit?: number;
+  /**
+   * Ignore terms carried by more than this fraction of notes. Default 0.05.
+   *
+   * Common terms are the vocabulary of a *genre* — every 1:1 note says
+   * "sprint", every recipe says "oven" — so they make unrelated notes of the
+   * same shape look related. Rare terms are what a note is actually about.
+   *
+   * Only a ceiling, never a floor: see {@link MIN_TERM_CEILING}.
+   */
+  maxDocFrequency?: number;
+  /** Suggestions below this score are dropped. Default 0.02. */
+  minScore?: number;
+  /** How many shared terms to cite as evidence. Default 8. */
+  evidence?: number;
+}
+
+/** Words too structural to carry meaning in any vault, in any domain. */
+const TERM_RE = /[\p{L}][\p{L}\p{N}_-]{2,}/gu;
+
+/**
+ * Smallest document-frequency ceiling, whatever `maxDocFrequency` computes.
+ *
+ * A pure percentage collapses on a small vault: at 40 notes, 5% floors to 2,
+ * so a term shared by three notes is discarded as "common" and the tool goes
+ * silent exactly where a user is most likely to try it. This floor keeps a
+ * young vault working while staying far below the point where a term is
+ * genuinely genre vocabulary — on any vault large enough for the percentage
+ * to exceed it, the percentage wins and this never applies.
+ */
+export const MIN_TERM_CEILING = 10;
+
+/**
+ * Split a note into terms.
+ *
+ * Title and tags are folded into the same bag as the body rather than being
+ * weighted separately: a term's importance is already expressed by its
+ * rarity, so boosting "the title" would be a second, redundant opinion about
+ * significance — and a wrong one whenever a title is generic ("Notes",
+ * "Index") or a body mentions the decisive term once.
+ */
+function terms(note: Pick<Note, "title" | "tags" | "body">): Set<string> {
+  const text = `${note.title} ${note.tags.join(" ")} ${note.body}`;
+  const out = new Set<string>();
+  for (const match of text.matchAll(TERM_RE)) out.add(match[0].toLowerCase());
+  return out;
+}
+
+/** The slice of a vault this needs. */
+export interface SuggestInput {
+  notes: readonly Pick<Note, "slug" | "title" | "tags" | "body">[];
+}
+
+/**
+ * Rank pairs of notes that share distinctive vocabulary but no link.
+ *
+ * Already-linked pairs are excluded in both directions: the point is to
+ * surface connections the vault is *missing*, and re-suggesting a link the
+ * user already wrote is noise that buries the real findings.
+ */
+export function suggestLinks(input: SuggestInput, options: SuggestOptions = {}): SuggestionReport {
+  const limit = options.limit ?? 20;
+  const maxDf = options.maxDocFrequency ?? 0.05;
+  const minScore = options.minScore ?? 0.02;
+  const evidenceCount = options.evidence ?? 8;
+  const notes = input.notes;
+  const n = notes.length;
+
+  const df = new Map<string, number>();
+  const bags = new Map<string, Set<string>>();
+  for (const note of notes) {
+    const bag = terms(note);
+    bags.set(note.slug, bag);
+    for (const term of bag) df.set(term, (df.get(term) ?? 0) + 1);
+  }
+
+  // A term in one note connects nothing; a term in most notes connects
+  // everything. Only what lies between can carry a signal.
+  const ceiling = Math.max(MIN_TERM_CEILING, Math.floor(n * maxDf));
+  const idf = new Map<string, number>();
+  for (const [term, count] of df) {
+    if (count < 2 || count > ceiling) continue;
+    idf.set(term, Math.log(n / count));
+  }
+
+  // Unit-normalised vectors, so the dot product below *is* the cosine.
+  const vectors = new Map<string, Map<string, number>>();
+  for (const note of notes) {
+    const vec = new Map<string, number>();
+    let norm = 0;
+    // Every note got a bag above; the `!` is that loop's invariant.
+    for (const term of bags.get(note.slug)!) {
+      const weight = idf.get(term);
+      if (weight === undefined) continue;
+      vec.set(term, weight);
+      norm += weight * weight;
+    }
+    if (norm === 0) continue;
+    const len = Math.sqrt(norm);
+    for (const [term, weight] of vec) vec.set(term, weight / len);
+    vectors.set(note.slug, vec);
+  }
+
+  // Existing links, both directions, so a connection the user already made
+  // is never offered back to them.
+  const linked = new Set<string>();
+  const bySlug = new Set(notes.map((note) => note.slug));
+  const byBasename = new Map<string, string[]>();
+  const byTitle = new Map<string, string[]>();
+  for (const note of notes) {
+    const base = note.slug.split("/").pop()!;
+    byBasename.set(base, [...(byBasename.get(base) ?? []), note.slug]);
+    const title = slugify(note.title);
+    if (title.length > 0) byTitle.set(title, [...(byTitle.get(title) ?? []), note.slug]);
+  }
+  for (const note of notes) {
+    for (const link of scanLinks(note.body)) {
+      // The same three-rung ladder `auditLinks` walks — exact slug, unique
+      // basename, unique title. It has to be all three: a link repair would
+      // resolve counts as a connection that already exists, so resolving a
+      // rung short here would suggest a pair the vault has already linked.
+      const byBase = byBasename.get(link.target) ?? [];
+      const byTtl = byTitle.get(link.target) ?? [];
+      const target = bySlug.has(link.target)
+        ? link.target
+        : byBase.length === 1
+          ? byBase[0]!
+          : byTtl.length === 1
+            ? byTtl[0]!
+            : null;
+      if (target !== null) linked.add(pairKey(note.slug, target));
+    }
+  }
+
+  // Candidate generation through an inverted index on distinctive terms
+  // only. Comparing every pair is O(n²) and mostly compares notes with
+  // nothing in common; postings lists for rare terms are short by
+  // definition, so this touches only pairs that can actually score.
+  const postings = new Map<string, string[]>();
+  for (const [slug, vec] of vectors) {
+    for (const term of vec.keys()) postings.set(term, [...(postings.get(term) ?? []), slug]);
+  }
+
+  const focus = options.slug;
+  if (focus !== undefined && !vectors.has(focus)) {
+    return { considered: vectors.size, suggestions: [] };
+  }
+
+  const scores = new Map<string, number>();
+  const sources = focus !== undefined ? [focus] : [...vectors.keys()];
+  // Vault-wide, every pair is reachable from both of its ends, so each
+  // contribution would be counted twice and the "cosine" could exceed 1.
+  // Accumulating one direction only keeps the score a real cosine; a focused
+  // run walks one source, so it never double-counts to begin with.
+  const oneWay = focus === undefined;
+  for (const slug of sources) {
+    const vec = vectors.get(slug)!;
+    for (const [term, weight] of vec) {
+      // `term` survived the idf filter, so it has a postings list containing
+      // at least this note.
+      for (const other of postings.get(term)!) {
+        if (other === slug || (oneWay && other < slug)) continue;
+        const key = pairKey(slug, other);
+        if (linked.has(key)) continue;
+        // `other` came from this term's postings list, so both lookups are
+        // guaranteed present — the `!`s are the index's invariant.
+        scores.set(key, (scores.get(key) ?? 0) + weight * vectors.get(other)!.get(term)!);
+      }
+    }
+  }
+
+  const suggestions: LinkSuggestion[] = [];
+  for (const [key, score] of scores) {
+    if (score < minScore) continue;
+    const [a, b] = key.split("\u0000") as [string, string];
+    suggestions.push({ a, b, score, shared: sharedTerms(vectors.get(a)!, vectors.get(b)!, evidenceCount) });
+  }
+  suggestions.sort((x, y) => y.score - x.score || x.a.localeCompare(y.a) || x.b.localeCompare(y.b));
+
+  return { considered: vectors.size, suggestions: suggestions.slice(0, limit) };
+}
+
+/** Order-independent key for an unordered pair. */
+function pairKey(a: string, b: string): string {
+  return a < b ? `${a}\u0000${b}` : `${b}\u0000${a}`;
+}
+
+/** The terms contributing most to a pair's score, strongest first. */
+function sharedTerms(a: Map<string, number>, b: Map<string, number>, count: number): string[] {
+  const shared: [string, number][] = [];
+  for (const [term, weight] of a) {
+    const other = b.get(term);
+    if (other !== undefined) shared.push([term, weight * other]);
+  }
+  return shared
+    .sort((x, y) => y[1] - x[1] || x[0].localeCompare(y[0]))
+    .slice(0, count)
+    .map(([term]) => term);
+}
+
+/**
+ * Slugify for comparison. Exported so the adapter can echo a target the way
+ * the resolver would see it.
+ */
+export function suggestionTarget(slug: string): string {
+  return slug.split("/").map(slugify).join("/");
+}