@silverbulletmd/silverbullet 2.9.0 → 2.11.0

package/plug-api/lib/fuzzy.ts

@@ -0,0 +1,282 @@
+function normalize(s: string): string {
+  return s
+    .normalize("NFD")
+    .replace(/\p{Diacritic}/gu, "")
+    .toLowerCase();
+}
+
+const WORD_BOUNDARY_CHARS = new Set(["/", "-", "_", " ", ".", ":"]);
+
+function isWordBoundaryAt(
+  original: string,
+  lowered: string,
+  i: number,
+): boolean {
+  if (i === 0) return true;
+  const prev = lowered[i - 1];
+  if (WORD_BOUNDARY_CHARS.has(prev)) return true;
+  // CamelCase boundary: previous original char is lowercase, current is uppercase
+  const origPrev = original[i - 1];
+  const origCur = original[i];
+  if (
+    origPrev &&
+    origCur &&
+    origPrev === origPrev.toLowerCase() &&
+    origPrev !== origPrev.toUpperCase() &&
+    origCur === origCur.toUpperCase() &&
+    origCur !== origCur.toLowerCase()
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function bestSubstringEditDistance(token: string, candidate: string): number {
+  const tl = token.length;
+  const cl = candidate.length;
+  let prevPrev = new Array(cl + 1).fill(0);
+  let prev = new Array(cl + 1).fill(0);
+  let curr = new Array(cl + 1);
+
+  for (let i = 1; i <= tl; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= cl; j++) {
+      const cost = token[i - 1] === candidate[j - 1] ? 0 : 1;
+      let v = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+      if (
+        i > 1 &&
+        j > 1 &&
+        token[i - 1] === candidate[j - 2] &&
+        token[i - 2] === candidate[j - 1]
+      ) {
+        v = Math.min(v, prevPrev[j - 2] + 1);
+      }
+      curr[j] = v;
+    }
+    const tmp = prevPrev;
+    prevPrev = prev;
+    prev = curr;
+    curr = tmp;
+  }
+
+  let best = prev[0];
+  for (let j = 1; j <= cl; j++) {
+    if (prev[j] < best) best = prev[j];
+  }
+  return best;
+}
+
+export function typoScore(token: string, candidate: string): number {
+  if (token.length < 4) return 0;
+  const max = Math.min(2, Math.floor(token.length / 4));
+  if (max < 1) return 0;
+
+  const bestDist = bestSubstringEditDistance(token, candidate);
+  if (bestDist > max) return 0;
+  return 0.25 - 0.05 * bestDist; // 0.25 / 0.20 / 0.15
+}
+
+function subsequenceScore(
+  token: string,
+  candidate: string,
+  candidateOriginal: string,
+): number {
+  // Greedy left-to-right match; track contiguous runs and word-boundary hits.
+  let ti = 0;
+  let firstMatch = -1;
+  let lastMatch = -1;
+  let contiguousRunSum = 0;
+  let currentRun = 0;
+  let boundaryHits = 0;
+  let prevMatchCi = -2;
+
+  for (let ci = 0; ci < candidate.length && ti < token.length; ci++) {
+    if (candidate[ci] === token[ti]) {
+      if (firstMatch < 0) firstMatch = ci;
+      lastMatch = ci;
+      if (isWordBoundaryAt(candidateOriginal, candidate, ci)) boundaryHits++;
+      if (ci === prevMatchCi + 1) {
+        currentRun++;
+      } else {
+        contiguousRunSum += currentRun * currentRun;
+        currentRun = 1;
+      }
+      prevMatchCi = ci;
+      ti++;
+    }
+  }
+  contiguousRunSum += currentRun * currentRun;
+
+  if (ti < token.length) return 0; // not a subsequence at all
+
+  // Normalize: token length over span (penalizes wide spans)
+  const span = lastMatch - firstMatch + 1;
+  const density = token.length / span; // in (0, 1]
+  const boundaryBonus = boundaryHits / token.length; // in [0, 1]
+  const contiguityBonus = contiguousRunSum / (token.length * token.length); // in (0, 1]
+
+  // Weighted combination scaled into [0.30, 0.65]
+  const raw = 0.5 * density + 0.3 * contiguityBonus + 0.2 * boundaryBonus;
+  return 0.3 + raw * 0.35;
+}
+
+export function scoreToken(token: string, candidate: string): number {
+  if (!token) return 0;
+  const t = normalize(token);
+  const cOrig = candidate;
+  const c = normalize(candidate);
+
+  // Tier 1: exact equality
+  if (c === t) return 1.0;
+
+  // Tier 2: prefix
+  if (c.startsWith(t)) {
+    return isWordBoundaryAt(cOrig, c, 0) ? 0.95 : 0.9;
+  }
+
+  // Tier 3: substring. Search for the best occurrence — a word-boundary
+  // match wins even if it appears later than a non-boundary match.
+  {
+    let bestIdx = -1;
+    let bestBoundary = false;
+    let idx = c.indexOf(t);
+    while (idx >= 0) {
+      const boundary = isWordBoundaryAt(cOrig, c, idx);
+      if (bestIdx < 0 || (boundary && !bestBoundary)) {
+        bestIdx = idx;
+        bestBoundary = boundary;
+        if (boundary) break; // can't get better
+      }
+      idx = c.indexOf(t, idx + 1);
+    }
+    if (bestIdx >= 0) {
+      // For very short tokens (<=2 chars), only count substring matches at
+      // word boundaries — otherwise short tokens generate too much noise.
+      if (t.length > 2 || bestBoundary) {
+        return bestBoundary ? 0.8 : 0.75;
+      }
+      // fall through for short non-boundary substring matches
+    }
+  }
+
+  // Tier 4: subsequence (short tokens skip this tier; substring at boundary
+  // is the only way for them to match)
+  if (t.length > 2) {
+    const subseq = subsequenceScore(t, c, cOrig);
+    if (subseq > 0) return subseq;
+  }
+
+  // Tier 5: bounded typo
+  const typo = typoScore(t, c);
+  if (typo > 0) return typo;
+
+  return 0;
+}
+
+export type RankField = { weight: number; segments?: boolean };
+export type RankOptions<T> = {
+  fields?: Record<string, number | RankField>;
+  orderId?: (obj: T) => number;
+};
+
+const DEFAULT_FIELDS: Record<string, number | RankField> = {
+  name: { weight: 1.0, segments: true },
+  displayName: 0.9,
+  aliases: 0.85,
+};
+
+/**
+ * Whether `phrase` equals one of `obj`'s ranked fields verbatim (normalized).
+ * Per-token scoring (below) never penalizes a candidate for carrying *extra*
+ * words the phrase didn't ask for -- "Foo" and "Foo Bar" score identically
+ * against the phrase "Foo", since each of the phrase's tokens matches
+ * somewhere in either candidate just as well. That leaves same-score ties
+ * exactly where a user's full, exact phrase should still win outright, which
+ * is what this tie-break (see `rank`'s sort) is for.
+ */
+function hasExactFieldMatch<T extends Record<string, any>>(
+  obj: T,
+  normalizedPhrase: string,
+  fields: Record<string, number | RankField>,
+): boolean {
+  for (const fieldName of Object.keys(fields)) {
+    const raw = obj[fieldName];
+    const values: unknown[] = Array.isArray(raw)
+      ? raw
+      : raw != null
+        ? [raw]
+        : [];
+    for (const value of values) {
+      if (normalize(String(value)) === normalizedPhrase) return true;
+    }
+  }
+  return false;
+}
+
+export function rank<T extends Record<string, any>>(
+  objects: T[],
+  phrase: string,
+  options: RankOptions<T> = {},
+): (T & { score: number })[] {
+  const fields = options.fields ?? DEFAULT_FIELDS;
+  const orderId = options.orderId ?? (() => 0);
+  const normalizedPhrase = normalize(phrase);
+  const tokens = normalizedPhrase.split(/\s+/).filter((t) => t.length > 0);
+  if (tokens.length === 0) {
+    return [...objects]
+      .sort(
+        (a, b) =>
+          orderId(a) - orderId(b) ||
+          String(a.name ?? "").localeCompare(String(b.name ?? "")),
+      )
+      .map((o) => ({ ...o, score: 1 }));
+  }
+  const results: (T & { score: number })[] = [];
+  for (const obj of objects) {
+    let product = 1;
+    let excluded = false;
+    for (const token of tokens) {
+      let best = 0;
+      for (const [fieldName, fieldSpec] of Object.entries(fields)) {
+        const spec: RankField =
+          typeof fieldSpec === "number" ? { weight: fieldSpec } : fieldSpec;
+        const raw = obj[fieldName];
+        const values: string[] = Array.isArray(raw)
+          ? raw.map(String)
+          : raw != null
+            ? [String(raw)]
+            : [];
+        for (const value of values) {
+          if (spec.segments && value.includes("/")) {
+            const last = value.slice(value.lastIndexOf("/") + 1);
+            best = Math.max(
+              best,
+              scoreToken(token, last) * spec.weight,
+              scoreToken(token, value) * spec.weight * 0.85,
+            );
+          } else {
+            best = Math.max(best, scoreToken(token, value) * spec.weight);
+          }
+        }
+      }
+      if (best === 0) {
+        excluded = true;
+        break;
+      }
+      product *= best;
+    }
+    if (!excluded) {
+      results.push({ ...obj, score: product ** (1 / tokens.length) });
+    }
+  }
+  return results.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    const aExact = hasExactFieldMatch(a, normalizedPhrase, fields);
+    const bExact = hasExactFieldMatch(b, normalizedPhrase, fields);
+    if (aExact !== bExact) return aExact ? -1 : 1;
+    return (
+      orderId(a) - orderId(b) ||
+      String(a.name ?? "").localeCompare(String(b.name ?? ""))
+    );
+  });
+}

package/plug-api/lib/json.ts

@@ -50,7 +50,6 @@ export function deepEqual(a: any, b: any): boolean {
  * @param d the date to convert
  */
 export function cleanStringDate(d: Date): string {
-  // If no significant time, return a date string only
   if (
     d.getUTCHours() === 0 &&
     d.getUTCMinutes() === 0 &&
@@ -85,7 +84,6 @@ export function cleanupJSON(a: any): any {
   if (Array.isArray(a)) {
     return a.map(cleanupJSON);
   }
-  // If a is a date, convert to a string
   if (a instanceof Date) {
     return cleanStringDate(a);
   }
@@ -106,17 +104,14 @@ export function cleanupJSON(a: any): any {
 }
 
 export function deepClone<T>(obj: T, ignoreKeys: string[] = []): T {
-  // Handle null, undefined, or primitive types (string, number, boolean, symbol, bigint)
   if (obj === null || typeof obj !== "object") {
     return obj;
   }
 
-  // Handle Date
   if (obj instanceof Date) {
     return new Date(obj.getTime()) as any;
   }
 
-  // Handle Array
   if (Array.isArray(obj)) {
     const arrClone: any[] = [];
     for (let i = 0; i < obj.length; i++) {
@@ -125,7 +120,6 @@ export function deepClone<T>(obj: T, ignoreKeys: string[] = []): T {
     return arrClone as any;
   }
 
-  // Handle Object
   if (obj instanceof Object) {
     const objClone: { [key: string]: any } = {};
     for (const key in obj) {

package/plug-api/lib/limited_map.ts

@@ -31,7 +31,6 @@ export class LimitedMap<V> {
       }, ttl);
     }
     if (this.map.size >= this.maxSize) {
-      // Remove the oldest key before adding a new one
       const oldestKey = this.getOldestKey();
       this.map.delete(oldestKey!);
     }
@@ -41,7 +40,6 @@ export class LimitedMap<V> {
   get(key: string): V | undefined {
     const entry = this.map.get(key);
     if (entry) {
-      // Update the last accessed timestamp
       entry.la = Date.now();
       return entry.value;
     }

package/plug-api/lib/link_write.ts

@@ -0,0 +1,27 @@
+import { config } from "../syscalls.ts";
+import { getNameFromPath, type Path } from "./ref.ts";
+import {
+  type LinkWriteFormat,
+  type PathIndex,
+  writeLinkPath,
+} from "./resolve_path.ts";
+
+/**
+ * The space's configured link write format — the one place its config key and
+ * default live. Plug-side only (reads config through a syscall).
+ */
+export function linkWriteFormat(): Promise<LinkWriteFormat> {
+  return config.get<LinkWriteFormat>("linkWriteFormat", "full-path");
+}
+
+/**
+ * Renders a page path as the link text SilverBullet writes for it under the
+ * given format.
+ */
+export function writtenLinkText(
+  path: Path,
+  format: LinkWriteFormat,
+  index: PathIndex,
+): string {
+  return getNameFromPath(writeLinkPath(path, format, index));
+}

package/plug-api/{ui → lib}/panel_styles.ts

@@ -15,9 +15,10 @@ export type PanelStylesOptions = {
  * Order: components first (base), then space styles (so user theming wins),
  * leaving any plug-specific CSS you append afterwards highest-precedence.
  */
-export async function panelStyles(
-  { components = true, spaceStyles = true }: PanelStylesOptions = {},
-): Promise<string> {
+export async function panelStyles({
+  components = true,
+  spaceStyles = true,
+}: PanelStylesOptions = {}): Promise<string> {
   let out = "";
   if (components) {
     out += `<link rel="stylesheet" href=".client/components.css">`;

package/plug-api/lib/ref.ts

@@ -62,13 +62,29 @@ function normalizePath(path: string): Path {
     path = path.slice(1);
   }
 
-  if (/.+\.[a-zA-Z0-9]+$/.test(path) || path === "") {
+  if (endsInExtension(path) || path === "") {
     return path as Path;
   }
 
   return `${path}.md`;
 }
 
+function endsInExtension(path: string): boolean {
+  const dot = path.lastIndexOf(".");
+  if (dot < 1 || dot === path.length - 1) {
+    return false;
+  }
+  for (let i = dot + 1; i < path.length; i++) {
+    const c = path.charCodeAt(i);
+    const alphanumeric =
+      (c >= 48 && c <= 57) || (c >= 65 && c <= 90) || (c >= 97 && c <= 122);
+    if (!alphanumeric) {
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
  * Determines wether a name conforms to all the requirments.
  */
@@ -93,8 +109,7 @@ export function isValidPath(path: string): path is Path {
 }
 
 /**
- * ONLY TOUCH THIS IF YOU REALLY KNOW WHAT YOU ARE DOING. THIS REGEX IS INTEGRAL
- * TO THE INNER WORKINGS OF SILVERBULLET AND CHANGES COULD INTRODUCE MAJOR BUGS
+ * Shared reference grammar for parsing and validation; changes affect both.
  */
 const refRegex =
   /^(?<meta>\^)?(?<path>(?!.*\.[a-zA-Z0-9]+\.md$)(?!\/?(\.|\^))(?!.*(?:\/|^)\.{1,2}(?:\/|$)|.*\/{2})(?!.*(?:\]\]|\[\[))[^@#|<>$]*)(@(?<pos>\d+)|@[Ll](?<line>\d+)(?:[Cc](?<col>\d+))?|#\s*(?<header>.*)|\$(?<anchor>[A-Za-z_][A-Za-z0-9_/:-]*))?$/;
@@ -141,9 +156,113 @@ export function parseToRef(stringRef: string): Ref | null {
 }
 
 /**
- * The inverse of {@link parseToRef}, encodes a ref object into a reference string.
- * It tries to produce the shortest valid representation
+ * Coerces a ref-or-string (including the legacy `{ page, pos, header }` shape)
+ * into a {@link Ref} and validates its structure, throwing on malformed input.
+ * Used wherever an external caller (e.g. a syscall) hands in a ref that may be a
+ * string or a legacy object.
  */
+export function coerceAndValidateRef(ref: Ref | string): Ref {
+  if (typeof ref === "string") {
+    const parsedRef = parseToRef(ref);
+    if (!parsedRef) {
+      throw new Error("Unable to parse string as ref");
+    }
+    ref = parsedRef;
+  }
+
+  if (
+    // @ts-expect-error: Legacy support
+    ref.page !== undefined
+  ) {
+    console.warn(
+      "You are using legacy navigation syntax (`{ page, pos, header }`), this will be phased out in the future",
+    );
+
+    const legacyRef = ref as unknown as {
+      kind: "page" | "document";
+      page: string;
+      pos?: number | { line: number; column: number };
+      header?: string;
+      meta?: boolean;
+    };
+
+    legacyRef.kind ??= "page";
+
+    let details: Ref["details"];
+
+    if (typeof legacyRef.pos === "number") {
+      details = { type: "position", pos: legacyRef.pos };
+    } else if (legacyRef.pos) {
+      details = {
+        type: "linecolumn",
+        line: legacyRef.pos.line,
+        column: legacyRef.pos.column,
+      };
+    } else if (legacyRef.header) {
+      details = { type: "header", header: legacyRef.header };
+    }
+
+    ref = {
+      path: (legacyRef.kind === "page"
+        ? `${legacyRef.page}.md`
+        : legacyRef.page) as Path,
+      details,
+      meta: legacyRef.meta,
+    };
+  }
+
+  if (!isValidPath(ref.path) && ref.path !== "") {
+    throw new Error("Path passed in ref is invalid");
+  } else if (typeof ref.meta !== "boolean" && ref.meta !== undefined) {
+    throw new Error("ref.meta has to be of type `boolean`");
+  } else if (ref.details !== undefined && typeof ref.details !== "object") {
+    throw new Error("ref.details has to be of type `object` or `undefined`");
+  } else if (
+    ref.details &&
+    !["position", "linecolumn", "header", "anchor"].includes(ref.details.type)
+  ) {
+    throw new Error(
+      "ref.details.type has to be 'position', 'linecolumn', 'header' or 'anchor'",
+    );
+  }
+
+  if (ref.details?.type === "position" && typeof ref.details.pos !== "number") {
+    throw new Error("ref.details.pos has to be of type `number`");
+  } else if (
+    ref.details?.type === "header" &&
+    typeof ref.details.header !== "string"
+  ) {
+    throw new Error("ref.details.header has to be of type `string`");
+  } else if (
+    ref.details?.type === "linecolumn" &&
+    typeof ref.details.line !== "number" &&
+    typeof ref.details.column !== "number"
+  ) {
+    throw new Error(
+      "ref.details.line and ref.details.column has to be of type `number`",
+    );
+  } else if (
+    ref.details?.type === "anchor" &&
+    typeof ref.details.name !== "string"
+  ) {
+    throw new Error("ref.details.name has to be of type `string`");
+  }
+
+  return ref;
+}
+
+/**
+ * Renders a ref as wiki link *text*, preserving the `^` meta prefix.
+ *
+ * {@link encodeRef} deliberately drops it — it also builds page URLs, where a
+ * caret would address a page that does not exist — so anything rewriting a link
+ * in a document must use this instead, or `[[^Library/Std]]` silently loses its
+ * caret.
+ */
+export function encodeLinkText(ref: Ref): string {
+  return (ref.meta ? "^" : "") + encodeRef(ref);
+}
+
 export function encodeRef(ref: Ref): string {
   let stringRef: string = ref.path;
 

package/plug-api/lib/resolve.ts

@@ -66,7 +66,6 @@ export function resolveMarkdownLink(
  * Turns an absolute path into a relative path, relative to some base directory. USE WITH CAUTION, definitely buggy
  */
 export function absoluteToRelativePath(base: string, absolute: string): string {
-  // Remove leading /
   base = base.startsWith("/") ? base.slice(1) : base;
   absolute = absolute.startsWith("/") ? absolute.slice(1) : absolute;