@silverbulletmd/silverbullet 2.10.0 → 2.12.0

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/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_/:-]*))?$/;
@@ -237,9 +252,17 @@ export function coerceAndValidateRef(ref: Ref | string): Ref {
 }
 
 /**
- * The inverse of {@link parseToRef}, encodes a ref object into a reference string.
- * It tries to produce the shortest valid representation
+ * 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

@@ -1,14 +1,7 @@
 import type { Path } from "@silverbulletmd/silverbullet/lib/ref";
 
-/**
- * Determines wether a url points into the world wide web or to the local SB instance
- */
 export function isLocalURL(url: string): boolean {
-  return (
-    !url.includes("://") &&
-    !url.startsWith("mailto:") &&
-    !url.startsWith("tel:")
-  );
+  return !/^[a-z][a-z0-9+.-]*:/i.test(url);
 }
 
 /**
@@ -66,7 +59,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;
 

package/plug-api/lib/resolve_path.ts

@@ -0,0 +1,290 @@
+import type { Path } from "./ref.ts";
+import { fileName, folderName } from "./resolve.ts";
+
+export type ResolveResult = {
+  path: Path;
+  exists: boolean;
+  ambiguous: boolean;
+  candidates?: Path[];
+};
+
+export type PathIndex = {
+  has(path: string): boolean;
+  candidates(basename: string): Path[];
+};
+
+export class BasenameIndex implements PathIndex {
+  private paths = new Set<string>();
+  private byBasename = new Map<string, Set<string>>();
+  // Keys whose bucket holds more than one path, maintained incrementally so a
+  // snapshot of every collision costs O(collisions), not a walk of the space.
+  private collidingKeys = new Set<string>();
+
+  rebuild(paths: Iterable<string>): void {
+    this.clear();
+    for (const path of paths) {
+      this.add(path);
+    }
+  }
+
+  clear(): void {
+    this.paths.clear();
+    this.byBasename.clear();
+    this.collidingKeys.clear();
+  }
+
+  add(path: string): void {
+    if (this.paths.has(path)) {
+      return;
+    }
+    this.paths.add(path);
+    const key = basenameKey(path);
+    let bucket = this.byBasename.get(key);
+    if (!bucket) {
+      bucket = new Set();
+      this.byBasename.set(key, bucket);
+    }
+    bucket.add(path);
+    if (bucket.size > 1) {
+      this.collidingKeys.add(key);
+    }
+  }
+
+  delete(path: string): void {
+    if (!this.paths.delete(path)) {
+      return;
+    }
+    const key = basenameKey(path);
+    const bucket = this.byBasename.get(key);
+    if (!bucket) {
+      return;
+    }
+    bucket.delete(path);
+    if (bucket.size < 2) {
+      this.collidingKeys.delete(key);
+    }
+    if (bucket.size === 0) {
+      this.byBasename.delete(key);
+    }
+  }
+
+  has(path: string): boolean {
+    return this.paths.has(path);
+  }
+
+  candidates(basename: string): Path[] {
+    const bucket = this.byBasename.get(basename.toLowerCase());
+    return bucket ? ([...bucket] as Path[]) : [];
+  }
+
+  /**
+   * Every basename carried by more than one file, with the files that carry
+   * it. Under the "a bare link exists iff its basename is unique" invariant
+   * collisions are rare, so this is a small snapshot of a large space — which
+   * is what makes it cheap to ship across the sandbox boundary.
+   */
+  collidingBuckets(): Record<string, Path[]> {
+    const result: Record<string, Path[]> = {};
+    for (const key of this.collidingKeys) {
+      result[key] = [...this.byBasename.get(key)!] as Path[];
+    }
+    return result;
+  }
+}
+
+function basenameKey(path: string): string {
+  return fileName(path).toLowerCase();
+}
+
+function folderSegments(path: Path): string[] {
+  const folder = folderName(path);
+  return folder === "" ? [] : folder.split("/");
+}
+
+function sharedDepth(a: string[], b: string[]): number {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) {
+    i++;
+  }
+  return i;
+}
+
+/**
+ * Ranks same-basename candidates relative to the linking page: deepest shared
+ * folder prefix first, then shallowest, then lexicographic. Obsidian ranks the
+ * vault root above the linking page's own folder; inverting that is deliberate
+ * (see the design spec) — root-wins would resolve a link inside `docs/api/` to
+ * a sibling project's root-level file whenever a space is opened at a wider
+ * root. Root preference survives as the shallowest-path rule, since the root is
+ * always depth 0.
+ */
+export function rankCandidates(candidates: Path[], fromPage: Path): Path[] {
+  const from = folderSegments(fromPage);
+  return [...candidates].sort((a, b) => {
+    const aFolder = folderSegments(a);
+    const bFolder = folderSegments(b);
+    const proximity = sharedDepth(bFolder, from) - sharedDepth(aFolder, from);
+    if (proximity !== 0) {
+      return proximity;
+    }
+    const depth = aFolder.length - bFolder.length;
+    if (depth !== 0) {
+      return depth;
+    }
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+}
+
+/**
+ * What a sandboxed caller gets back for one requested path: whether that exact
+ * path exists, plus every file sharing its basename. Ranking deliberately stays
+ * out of the syscall — it runs in the caller, from the same pure function the
+ * client uses, so there is only ever one implementation of it.
+ */
+export type PathLookup = {
+  exact: boolean;
+  candidates: Path[];
+};
+
+/**
+ * Adapts a batch of lookups into a {@link PathIndex}. Exact-path answers stay
+ * keyed by the requested path, while candidates are re-keyed by basename —
+ * which is how both `resolvePath` and `writeLinkPath` ask for them. Keying
+ * candidates by the requested path instead silently returns none for anything
+ * in a folder.
+ */
+export function lookupIndex(lookups: Record<string, PathLookup>): PathIndex {
+  const byBasename = new Map<string, Path[]>();
+  for (const [path, lookup] of Object.entries(lookups)) {
+    byBasename.set(basenameKey(path), lookup.candidates);
+  }
+  return {
+    has: (path) => lookups[path]?.exact ?? false,
+    candidates: (basename) => byBasename.get(basename.toLowerCase()) ?? [],
+  };
+}
+
+/**
+ * A {@link PathIndex} for *write-format decisions only*, built from just the
+ * colliding buckets of {@link BasenameIndex.collidingBuckets}. Enough for
+ * {@link writeLinkPath} on paths of files that exist: a basename outside the
+ * buckets is unique by construction, so `candidates` answers with a
+ * single-entry stand-in, and `has` only ever needs to look inside a bucket
+ * (every exact path a suffix could be shadowed by shares the suffix's own
+ * basename). Not a resolution index — do not hand it to `resolvePath` callers.
+ */
+export function collisionIndex(colliding: Record<string, Path[]>): PathIndex {
+  return {
+    has: (path) =>
+      colliding[basenameKey(path)]?.includes(path as Path) ?? false,
+    candidates: (basename) =>
+      colliding[basename.toLowerCase()] ?? ([basename] as Path[]),
+  };
+}
+
+export type LinkWriteFormat = "shortest" | "shortest-suffix" | "full-path";
+
+/**
+ * Renders a target path as link text. `shortest` writes the bare name only when
+ * that name is unique in the space — the rule that maintains the "a bare link
+ * exists iff its basename is unique" invariant on the write side — and the
+ * full path otherwise. `shortest-suffix` differs only in the colliding case:
+ * instead of the full path it writes the shortest path suffix that resolves
+ * back to exactly this file, which keeps even disambiguated links independent
+ * of where the space root sits.
+ */
+export function writeLinkPath(
+  target: Path,
+  format: LinkWriteFormat,
+  index: PathIndex,
+): Path {
+  if (format === "full-path") {
+    return target;
+  }
+  const bare = fileName(target);
+  if (index.candidates(bare).length === 1) {
+    return bare;
+  }
+  if (format === "shortest") {
+    return target;
+  }
+  // Every rival a suffix could collide with shares the target's basename, so
+  // the basename bucket is a complete rival list and resolvePath can verify
+  // each candidate outright: rejected when it is another file's exact path,
+  // ambiguous, or resolving elsewhere. fromPage is irrelevant — only
+  // unambiguous resolutions are accepted, and those are page-independent.
+  const segments = target.split("/");
+  for (let i = segments.length - 2; i >= 1; i--) {
+    const candidate = segments.slice(i).join("/") as Path;
+    const resolution = resolvePath(candidate, "" as Path, index);
+    if (
+      resolution.exists &&
+      !resolution.ambiguous &&
+      resolution.path === target
+    ) {
+      return candidate;
+    }
+  }
+  return target;
+}
+
+/**
+ * Resolves a parsed ref path against the space. Exact paths always win, so
+ * every link that resolves today keeps resolving to the same file. A bare name
+ * falls back to a space-wide basename lookup; more than one survivor means the
+ * "bare link iff unique basename" invariant is violated, which resolves
+ * deterministically but is reported as ambiguous so callers can flag it.
+ *
+ * A qualified path with no exact match falls back to a path-suffix lookup:
+ * `api/Auth` finds `docs/api/Auth.md` when that is the only file whose path
+ * ends that way. This is what lets a space opened at a wider root — the parent
+ * of the `docs/` folder it was authored in — keep its qualified links working,
+ * not just its bare ones, and it matches Obsidian accepting partial paths as
+ * linkpaths.
+ */
+export function resolvePath(
+  path: Path,
+  fromPage: Path,
+  index: PathIndex,
+): ResolveResult {
+  if (path === "") {
+    return { path, exists: true, ambiguous: false };
+  }
+  if (index.has(path)) {
+    // An exact path match is fully determined by the link text, so it is never
+    // reported ambiguous — even when other files share the basename. For a
+    // root-level file the bare and qualified forms are the same string, so
+    // there is nothing the author could write instead and the warning could
+    // never be cleared.
+    return { path, exists: true, ambiguous: false };
+  }
+
+  // A bare name is just the degenerate suffix, so one matcher serves both
+  // lookups: a candidate matches when, `/`-prefixed, its path ends with `/`
+  // plus the ref.
+  const suffix = `/${path.toLowerCase()}`;
+  const candidates = index
+    .candidates(fileName(path))
+    .filter((candidate) => `/${candidate.toLowerCase()}`.endsWith(suffix));
+  if (candidates.length === 0) {
+    return { path, exists: false, ambiguous: false };
+  }
+  // The overwhelmingly common case under the bare-iff-unique invariant, on
+  // the per-rendered-link path: skip the case filter and the ranking sort.
+  if (candidates.length === 1) {
+    return { path: candidates[0], exists: true, ambiguous: false };
+  }
+
+  const caseSuffix = `/${path}`;
+  const exactCase = candidates.filter((candidate) =>
+    `/${candidate}`.endsWith(caseSuffix),
+  );
+  if (exactCase.length === 1) {
+    return { path: exactCase[0], exists: true, ambiguous: false };
+  }
+  const ranked = rankCandidates(
+    exactCase.length > 0 ? exactCase : candidates,
+    fromPage,
+  );
+  return { path: ranked[0], exists: true, ambiguous: true, candidates: ranked };
+}

package/plug-api/lib/shortcut.ts

@@ -2,6 +2,21 @@ export const isMacLike =
   typeof navigator !== "undefined" &&
   /(Mac|iPhone|iPod|iPad)/i.test(navigator.platform);
 
+/**
+ * The key hint a command shows: its platform-appropriate binding(s),
+ * prettified. Several bindings for one command are joined with `|`.
+ */
+export function keyboardHint(def: {
+  key?: string | string[];
+  mac?: string | string[];
+}): string | undefined {
+  const binding = isMacLike && def.mac ? def.mac : def.key;
+  if (!binding) return undefined;
+  const shortcuts = Array.isArray(binding) ? binding : [binding];
+  if (shortcuts.length === 0) return undefined;
+  return shortcuts.map(prettifyShortcut).join(" | ");
+}
+
 export function prettifyShortcut(shortcut: string): string {
   if (!isMacLike) return shortcut;
   const pretty = shortcut

package/plug-api/lib/tags.ts

@@ -6,7 +6,6 @@ export function isMetaTag(tag: string): boolean {
 /** Extract the name from hashtag text, removing # prefix and <angle brackets> if necessary */
 export function extractHashtag(text: string): string {
   if (text[0] !== "#") {
-    // you shouldn't call this function at all
     console.error("extractHashtag called on already clean string", text);
     return text;
   } else if (text[1] === "<") {
@@ -14,11 +13,9 @@ export function extractHashtag(text: string): string {
       // this is malformed: #<name but maybe we're trying to autocomplete
       return text.slice(2);
     } else {
-      // this is correct #<name>
       return text.slice(2, -1);
     }
   } else {
-    // this is just #name
     return text.slice(1);
   }
 }

package/plug-api/lib/transclusion.ts

@@ -3,9 +3,15 @@ import {
   wikiLinkRegex,
 } from "../../client/markdown_parser/constants.ts";
 import {
+  encodeRef,
   getNameFromPath,
   parseToRef,
+  type Path,
 } from "@silverbulletmd/silverbullet/lib/ref";
+import {
+  type PathIndex,
+  resolvePath,
+} from "@silverbulletmd/silverbullet/lib/resolve_path";
 
 export type LinkType = "wikilink" | "markdownlink";
 /**
@@ -83,7 +89,6 @@ export function parseTransclusion(text: string): Transclusion | null {
     ({ stringRef: url, alias } = match.groups);
     linktype = "wikilink";
   } else {
-    // We found no match
     return null;
   }
 
@@ -102,6 +107,28 @@ export function parseTransclusion(text: string): Transclusion | null {
   };
 }
 
+/**
+ * Rewrites a wiki-link transclusion's target to the path it resolves to, the
+ * same way plain wiki links resolve.
+ */
+export function resolveTransclusionUrl(
+  t: Transclusion,
+  fromPage: Path,
+  index: PathIndex,
+): void {
+  if (t.linktype !== "wikilink") {
+    return;
+  }
+  const ref = parseToRef(t.url);
+  if (!ref || ref.path === "") {
+    return;
+  }
+  const resolution = resolvePath(ref.path, fromPage, index);
+  if (resolution.exists && resolution.path !== ref.path) {
+    t.url = encodeRef({ ...ref, path: resolution.path });
+  }
+}
+
 export function nameFromTransclusion(t: Transclusion): string {
   const ref = parseToRef(t.url);
   if (!ref) {

package/plug-api/lib/tree.ts

@@ -114,7 +114,6 @@ export function replaceNodesMatching(
           tree.children[i] = subst;
           i++;
         } else {
-          // null = delete
           tree.children.splice(i, 1);
           // don't increment i — next child shifted into this position
         }
@@ -140,7 +139,6 @@ export async function replaceNodesMatchingAsync(
           tree.children[i] = subst;
           i++;
         } else {
-          // null = delete
           tree.children.splice(i, 1);
         }
       } else {
@@ -281,11 +279,9 @@ export function nodeAtPos(tree: ParseTree, pos: number): ParseTree | null {
   for (const child of tree.children) {
     const n = nodeAtPos(child, pos);
     if (n && n.text !== undefined) {
-      // Got a text node, let's return its parent
       return tree;
     }
     if (n) {
-      // Got it
       return n;
     }
   }
@@ -321,7 +317,6 @@ export function normalizeTableRow(
   // Fix leading-pipe mismatch: row has leading delimiter but header doesn't
   if (headerHasLeadingDelim === false) {
     if (row.children.length > 0 && row.children[0].type === "TableDelimiter") {
-      // Insert empty cell after the leading delimiter
       row.children.splice(1, 0, { type: "TableCell", children: [] });
     }
   }