@silverbulletmd/silverbullet 2.10.0 → 2.11.0

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: [] });
     }
   }

package/plug-api/lib/yaml.ts

@@ -1,19 +1,16 @@
-// Define the patch structure
 export interface YamlPatch {
   op: "set-key" | "delete-key";
-  path: string; // Still assuming simple, top-level key names
+  path: string; // Top-level key names only
   value?: any; // Required for set-key, not used for delete-key
 }
 
-// Helper function specifically for serializing scalar types
 function serializeToYamlScalar(
   value: string | number | boolean | null,
 ): string {
   if (typeof value === "string") {
-    // Always quote empty strings and strings with special characters
     if (
       value === "" || // Empty string
-      value.match(/[:{#}[],&*!|>'"%@`]/) || // Special YAML characters (added % and ")
+      value.match(/[:{#}[],&*!|>'"%@`]/) || // Special YAML characters
       /^\d+(\.\d+)?([eE][+-]?\d+)?$/.test(value) || // Looks like a number
       value.includes(":") || // Contains colons
       ["true", "false", "null", "yes", "no", "on", "off"].includes(
@@ -22,7 +19,6 @@ function serializeToYamlScalar(
     ) {
       return JSON.stringify(value);
     }
-    // Simple strings without special chars/meaning don't need quotes
     return value;
   } else if (
     typeof value === "number" ||
@@ -31,12 +27,9 @@ function serializeToYamlScalar(
   ) {
     return String(value);
   }
-  // Default for unsupported scalar types (e.g., undefined)
   return "null";
 }
 
-// Updated helper function to serialize various JS types to YAML string representations
-// Added baseIndentation parameter for handling nested lists correctly (though we only use it for top-level lists here)
 function serializeToYamlValue(
   value: any,
   baseIndentation: string = "",
@@ -45,9 +38,7 @@ function serializeToYamlValue(
     if (value.length === 0) {
       return "[]"; // Use flow style for empty arrays for simplicity
     }
-    // Determine indentation for list items (base + 2 spaces)
     const itemIndentation = `${baseIndentation}  `;
-    // Format each item recursively, preceded by '- ' marker
     return (
       "\n" +
       value
@@ -57,11 +48,8 @@ function serializeToYamlValue(
         )
         .join("\n")
     );
-    // Note: serializeToYamlValue is used recursively here to handle nested arrays/objects if needed in future
-    // However, the current `applyMinimalSetKeyPatches` only handles top-level keys.
   } else if (typeof value === "object" && value !== null) {
-    // Basic object serialization (not requested, but good to consider)
-    // This is highly simplified and doesn't handle nesting well without more context
+    // Nested object serialization is limited.
     const itemIndentation = `${baseIndentation}  `;
     const entries = Object.entries(value);
     if (entries.length === 0) return "{}"; // Flow style empty objects
@@ -78,7 +66,6 @@ function serializeToYamlValue(
         .join("\n")
     );
   } else {
-    // Handle scalars using the dedicated function
     return serializeToYamlScalar(value);
   }
 }
@@ -88,14 +75,12 @@ export function applyPatches(yamlString: string, patches: YamlPatch[]): string {
 
   for (const patch of patches) {
     if (patch.op === "delete-key") {
-      // Handle delete operation
       const key = patch.path;
       const lines = currentYaml.split("\n");
       let keyLineIndex = -1;
       let startDeleteIndex = -1;
       let endDeleteIndex = -1;
 
-      // Find the key line
       for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         const trimmedLine = line.trim();
@@ -121,16 +106,12 @@ export function applyPatches(yamlString: string, patches: YamlPatch[]): string {
             }
           }
 
-          // Determine the indentation of the key
           const keyIndent = lines[i].match(/^(\s*)/)?.[1] || "";
 
-          // Look forwards to find all content belonging to this key
-          // This includes list items and nested objects
           for (let j = i + 1; j < lines.length; j++) {
             const nextLine = lines[j];
             const trimmedNextLine = nextLine.trim();
 
-            // Empty line - continue looking
             if (trimmedNextLine === "") {
               continue;
             }
@@ -147,13 +128,10 @@ export function applyPatches(yamlString: string, patches: YamlPatch[]): string {
               }
             }
 
-            // Check indentation of next non-empty, non-comment line
             const nextIndent = nextLine.match(/^(\s*)/)?.[1] || "";
             if (nextIndent.length > keyIndent.length) {
-              // This line is indented more than the key, so it belongs to the key
               endDeleteIndex = j;
             } else {
-              // This line is at same or less indentation, so it's a new key
               break;
             }
           }
@@ -163,12 +141,9 @@ export function applyPatches(yamlString: string, patches: YamlPatch[]): string {
       }
 
       if (keyLineIndex !== -1) {
-        // Delete the lines from startDeleteIndex to endDeleteIndex (inclusive)
         const beforeDelete = lines.slice(0, startDeleteIndex);
         const afterDelete = lines.slice(endDeleteIndex + 1);
 
-        // Clean up excessive empty lines at the boundary
-        // Remove trailing empty lines from beforeDelete
         while (
           beforeDelete.length > 0 &&
           beforeDelete[beforeDelete.length - 1].trim() === ""
@@ -194,7 +169,6 @@ export function applyPatches(yamlString: string, patches: YamlPatch[]): string {
           currentYaml += "\n";
         }
       }
-      // If key not found, do nothing
       continue;
     }
 
@@ -202,25 +176,21 @@ export function applyPatches(yamlString: string, patches: YamlPatch[]): string {
 
     const key = patch.path;
 
-    // Split the YAML into lines for easier processing
     const lines = currentYaml.split("\n");
     let keyLineIndex = -1;
     let commentBlock = "";
     let trailingComments = "";
     let inlineComment = "";
 
-    // Find the key line and collect comments
     for (let i = 0; i < lines.length; i++) {
       const line = lines[i];
       const trimmedLine = line.trim();
       if (trimmedLine.startsWith(`${key}:`)) {
         keyLineIndex = i;
-        // Extract inline comment if present
         const commentMatch = line.match(/#.*$/);
         if (commentMatch) {
           inlineComment = commentMatch[0];
         }
-        // Look backwards for comments
         for (let j = i - 1; j >= 0; j--) {
           const prevLine = lines[j].trim();
           if (prevLine.startsWith("#")) {
@@ -229,7 +199,6 @@ export function applyPatches(yamlString: string, patches: YamlPatch[]): string {
             break;
           }
         }
-        // Look forwards for comments
         for (let j = i + 1; j < lines.length; j++) {
           const nextLine = lines[j].trim();
           if (nextLine.startsWith("#")) {
@@ -242,16 +211,12 @@ export function applyPatches(yamlString: string, patches: YamlPatch[]): string {
       }
     }
 
-    // Serialize the new value
     const serializedNewValue = serializeToYamlValue(patch.value);
 
-    // Create the replacement line
     let replacementLine: string;
     if (serializedNewValue.startsWith("\n")) {
-      // For lists/objects, the key line ends with just ':'
       replacementLine = `${key}:${inlineComment}${serializedNewValue}`;
     } else {
-      // For scalars, format as key: value
       replacementLine = `${key}: ${serializedNewValue}${
         inlineComment ? ` ${inlineComment}` : ""
       }`;
@@ -267,7 +232,6 @@ export function applyPatches(yamlString: string, patches: YamlPatch[]): string {
         keyLineIndex + 1 + trailingComments.split("\n").filter(Boolean).length,
       );
 
-      // Build the new content
       const newContent = [
         ...beforeKey,
         ...commentBlock.split("\n").filter(Boolean),
@@ -276,10 +240,8 @@ export function applyPatches(yamlString: string, patches: YamlPatch[]): string {
         ...afterKey,
       ];
 
-      // Join lines and ensure proper newlines
       currentYaml = `${newContent.join("\n").replace(/\n*$/, "\n")}\n`;
     } else {
-      // Key not found: Add the new key-value pair to the end
       const newLineBlock = replacementLine;
       if (currentYaml.trim() === "") {
         currentYaml = `${newLineBlock}\n`;
@@ -289,6 +251,5 @@ export function applyPatches(yamlString: string, patches: YamlPatch[]): string {
     }
   }
 
-  // Ensure the result ends with a newline
   return currentYaml.replace(/\n*$/, "\n");
 }

package/plug-api/syscall.ts

@@ -1,8 +1,4 @@
-// declare global {
-//   function syscall(name: string, ...args: any[]): Promise<any>;
-// }
-
-// This is the case when running tests only, so giving it a dummy syscall function
+// Tests may load this module without a syscall host.
 if (typeof (globalThis as any).syscall === "undefined") {
   (globalThis as any).syscall = () => {
     throw new Error("Not implemented here");

package/plug-api/syscalls/config.ts

@@ -15,14 +15,14 @@ export function get<T>(path: string | string[], defaultValue: T): Promise<T> {
  * @param path The path to set the value at
  * @param value The value to set
  */
-export function set<T>(path: string, value: T): Promise<void>;
+export function set<T>(path: string | string[], value: T): Promise<void>;
 /**
  * Sets multiple config values at once.
  * @param values An object containing key-value pairs to set
  */
 export function set(values: Record<string, any>): Promise<void>;
 export function set<T>(
-  pathOrValues: string | Record<string, any>,
+  pathOrValues: string | string[] | Record<string, any>,
   value?: T,
 ): Promise<void> {
   return syscall("config.set", pathOrValues, value);