@silverbulletmd/silverbullet 2.9.0 → 2.11.0

package/client/space_lua/labels.ts

@@ -35,7 +35,6 @@ class LabelResolveError extends Error {
   }
 }
 
-// Cache
 const functionMetaByRoot = new WeakMap<LuaBlock, FunctionMeta>();
 const functionMetaByAnyBlock = new WeakMap<LuaBlock, FunctionMeta>();
 
@@ -107,11 +106,9 @@ function resolveFunction(root: LuaBlock): FunctionMeta {
     roleByBlock,
   );
 
-  // Validate gotos
   for (const g of vctx.gotos) {
     const target = g.node.name;
 
-    // Search current block for the label, then ancestors
     let searchBlock: LuaBlock | undefined = g.block;
     let labelIndex: number | undefined;
     let labelDefBlock: LuaBlock | undefined;
@@ -151,7 +148,6 @@ function resolveFunction(root: LuaBlock): FunctionMeta {
       );
     }
 
-    // Local scope forward jump check
     let entersLocalScope = false;
     let entersCloseScope = false;
 

package/client/space_lua/numeric.ts

@@ -7,7 +7,6 @@ export interface LuaTaggedFloat {
   readonly isFloat: true;
 }
 
-// Pre-allocated singletons for float zeros
 const FLOAT_POS_ZERO: LuaTaggedFloat = { value: 0, isFloat: true };
 const FLOAT_NEG_ZERO: LuaTaggedFloat = { value: -0, isFloat: true };
 
@@ -159,7 +158,6 @@ export function coerceNumericPair(
 ): CoerceNumericPairResult {
   const forceFloat = op === "/" || op === "^";
 
-  // Both plain numbers
   if (typeof a === "number" && typeof b === "number") {
     const lt = leftType ?? inferNumericType(a);
     const rt = rightType ?? inferNumericType(b);
@@ -175,7 +173,6 @@ export function coerceNumericPair(
     };
   }
 
-  // One tagged float, one plain number
   if (typeof a === "number" && isTaggedFloat(b)) {
     return {
       left: a,
@@ -192,7 +189,6 @@ export function coerceNumericPair(
     };
   }
 
-  // Both tagged floats
   if (isTaggedFloat(a) && isTaggedFloat(b)) {
     return {
       left: a.value,
@@ -201,7 +197,6 @@ export function coerceNumericPair(
     };
   }
 
-  // General fallback
   const A = coerceNumeric(a, leftType);
   const B = coerceNumeric(b, rightType);
 

package/client/space_lua/parse.ts

@@ -1,8 +1,8 @@
 import { lezerToParseTree } from "../../client/markdown_parser/parse_tree.ts";
 import type { SyntaxNode } from "@lezer/common";
 import {
-  cleanTree,
   type ParseTree,
+  renderToText,
 } from "@silverbulletmd/silverbullet/lib/tree";
 // @ts-expect-error - Local generated JavaScript file without type definitions
 import { parser } from "./parse-lua.js";
@@ -12,6 +12,7 @@ import type {
   ASTCtx,
   LuaAttName,
   LuaBlock,
+  LuaComment,
   LuaExpression,
   LuaFunctionBody,
   LuaFunctionCallExpression,
@@ -25,6 +26,7 @@ import type {
   LuaStatement,
   LuaTableField,
 } from "./ast.ts";
+import type { LuaFunctionDocumentation } from "../../plug-api/types/index.ts";
 import { LuaAttribute } from "./ast.ts";
 import { getBlockGotoMeta } from "./labels.ts";
 import { LuaRuntimeError, LuaStackFrame } from "./runtime.ts";
@@ -48,7 +50,6 @@ const customIndent = indentNodeProp.add({
   },
 });
 
-// Use the customIndent in your language support
 export const luaLanguage = LRLanguage.define({
   name: "space-lua",
   parser: parser.configure({
@@ -67,7 +68,217 @@ function parseChunk(t: ParseTree, ctx: ASTCtx): LuaBlock {
   if (t.type !== "Chunk") {
     throw new Error(`Expected Chunk, got ${t.type}`);
   }
-  return parseBlockNode(t.children![0], ctx);
+  const block = t.children?.find((child) => child.type === "Block");
+  if (!block) {
+    return { type: "Block", statements: [], ctx: context(t, ctx) };
+  }
+  return parseBlockNode(block, ctx);
+}
+
+function collectLuaComments(t: ParseTree, ctx: ASTCtx): LuaComment[] {
+  const comments: LuaComment[] = [];
+  const visit = (node: ParseTree) => {
+    if (node.type === "Comment") {
+      const text = renderToText(node);
+      comments.push({
+        type: "Comment",
+        text,
+        kind: /^--\[(=*)\[/.test(text) ? "long" : "line",
+        ctx: context(node, ctx),
+      });
+      return;
+    }
+    for (const child of node.children ?? []) visit(child);
+  };
+  visit(t);
+  return comments.sort((a, b) => (a.ctx.from ?? 0) - (b.ctx.from ?? 0));
+}
+
+function withoutComments(t: ParseTree): ParseTree {
+  if (!t.children) return t;
+  return {
+    ...t,
+    children: t.children
+      .filter((child) => child.type !== "Comment")
+      .map(withoutComments),
+  };
+}
+
+function assignCommentsToBlocks(
+  root: LuaBlock,
+  comments: LuaComment[],
+  source: string,
+): void {
+  const blocks: LuaBlock[] = [];
+  const seen = new WeakSet<object>();
+  const visit = (value: unknown, key?: string) => {
+    if (!value || typeof value !== "object" || key === "ctx") return;
+    if (seen.has(value)) return;
+    seen.add(value);
+    if ((value as { type?: string }).type === "Block") {
+      blocks.push(value as LuaBlock);
+    }
+    for (const [childKey, child] of Object.entries(value)) {
+      if (
+        childKey !== "ctx" &&
+        childKey !== "comments" &&
+        childKey !== "documentation"
+      ) {
+        visit(child, childKey);
+      }
+    }
+  };
+  visit(root);
+
+  for (const comment of comments) {
+    const from = comment.ctx.from ?? 0;
+    const to = comment.ctx.to ?? from;
+    let owner = root;
+    let ownerSpan = Number.POSITIVE_INFINITY;
+    for (const block of blocks) {
+      if (block === root) continue;
+      const blockFrom = block.ctx.from;
+      const blockTo = block.ctx.to;
+      if (blockFrom === undefined || blockTo === undefined) continue;
+      const contains = blockFrom <= from && blockTo >= to;
+      const immediatelyBefore =
+        to <= blockFrom && !source.slice(to, blockFrom).trim();
+      const immediatelyAfter =
+        blockTo <= from && !source.slice(blockTo, from).trim();
+      if (
+        (contains || immediatelyBefore || immediatelyAfter) &&
+        blockTo - blockFrom < ownerSpan
+      ) {
+        owner = block;
+        ownerSpan = blockTo - blockFrom;
+      }
+    }
+    (owner.comments ??= []).push(comment);
+  }
+}
+
+function parseFunctionDocumentation(
+  comments: LuaComment[],
+): LuaFunctionDocumentation | undefined {
+  const description: string[] = [];
+  const parameters: NonNullable<LuaFunctionDocumentation["parameters"]> = [];
+  const returns: NonNullable<LuaFunctionDocumentation["returns"]> = [];
+  let deprecated: string | boolean | undefined;
+  let see: string | undefined;
+
+  for (const comment of comments) {
+    const line = comment.text.slice(3).replace(/^\s?/, "");
+    const param = /^@param\s+(\S+)\s+(\S+)(?:\s+(.*))?$/.exec(line);
+    if (param) {
+      const optional = param[1].endsWith("?");
+      parameters.push({
+        name: optional ? param[1].slice(0, -1) : param[1],
+        type: param[2],
+        description: param[3] || undefined,
+        optional,
+      });
+      continue;
+    }
+    const returnDoc = /^@return\s+(\S+)(?:\s+(.*))?$/.exec(line);
+    if (returnDoc) {
+      returns.push({
+        type: returnDoc[1],
+        description: returnDoc[2] || undefined,
+      });
+      continue;
+    }
+    const deprecatedDoc = /^@deprecated(?:\s+(.*))?$/.exec(line);
+    if (deprecatedDoc) {
+      deprecated = deprecatedDoc[1] || true;
+      continue;
+    }
+    const seeDoc = /^@see\s+(.+)$/.exec(line);
+    if (seeDoc) {
+      see = seeDoc[1];
+      continue;
+    }
+    if (!line.startsWith("@")) description.push(line);
+  }
+
+  const docs: LuaFunctionDocumentation = {};
+  const descriptionText = description.join("\n").trim();
+  if (descriptionText) docs.description = descriptionText;
+  if (parameters.length) docs.parameters = parameters;
+  if (returns.length) docs.returns = returns;
+  if (deprecated !== undefined) docs.deprecated = deprecated;
+  if (see) docs.see = see;
+  return Object.keys(docs).length ? docs : undefined;
+}
+
+function attachFunctionDocumentation(
+  root: LuaBlock,
+  comments: LuaComment[],
+  source: string,
+): void {
+  const candidates: { from: number; body: LuaFunctionBody }[] = [];
+  const seen = new WeakSet<object>();
+  const claimedBodies = new WeakSet<LuaFunctionBody>();
+
+  const addCandidate = (from: number | undefined, body: LuaFunctionBody) => {
+    if (from === undefined || claimedBodies.has(body)) return;
+    claimedBodies.add(body);
+    candidates.push({ from, body });
+  };
+
+  const visit = (value: unknown, key?: string) => {
+    if (!value || typeof value !== "object" || key === "ctx") return;
+    if (seen.has(value)) return;
+    seen.add(value);
+    const node = value as Record<string, any>;
+    if (node.type === "Function" || node.type === "LocalFunction") {
+      addCandidate(node.ctx?.from, node.body);
+    } else if (
+      (node.type === "Local" || node.type === "Assignment") &&
+      node.expressions?.length === 1 &&
+      node.expressions[0]?.type === "FunctionDefinition"
+    ) {
+      addCandidate(node.ctx?.from, node.expressions[0].body);
+    } else if (node.type === "FunctionDefinition") {
+      addCandidate(node.ctx?.from, node.body);
+    }
+    for (const [childKey, child] of Object.entries(node)) {
+      if (
+        childKey !== "ctx" &&
+        childKey !== "comments" &&
+        childKey !== "documentation"
+      ) {
+        visit(child, childKey);
+      }
+    }
+  };
+  visit(root);
+
+  const docComments = comments.filter(
+    (comment) => comment.kind === "line" && comment.text.startsWith("---"),
+  );
+  for (const candidate of candidates) {
+    const group: LuaComment[] = [];
+    let boundary = candidate.from;
+    for (let i = docComments.length - 1; i >= 0; i--) {
+      const comment = docComments[i];
+      const from = comment.ctx.from ?? 0;
+      const to = comment.ctx.to ?? from;
+      if (to > boundary) continue;
+      const gap = source.slice(to, boundary);
+      const lineStart = source.lastIndexOf("\n", from - 1) + 1;
+      if (
+        gap.trim() ||
+        /\r?\n[ \t]*\r?\n/.test(gap) ||
+        source.slice(lineStart, from).trim()
+      ) {
+        break;
+      }
+      group.unshift(comment);
+      boundary = from;
+    }
+    const documentation = parseFunctionDocumentation(group);
+    if (documentation) candidate.body.documentation = documentation;
+  }
 }
 
 function hasCloseLocal(names: LuaAttName[] | undefined): boolean {
@@ -335,7 +546,6 @@ function functionBodyCapturesNames(
   return blockReferencesNames(body.block, check);
 }
 
-// Walk block using `exprReferencesNames` (inside a function body).
 function blockReferencesNames(block: LuaBlock, names: Set<string>): boolean {
   for (let i = 0; i < block.statements.length; i++) {
     if (statementReferencesNames(block.statements[i], names)) return true;
@@ -438,7 +648,6 @@ function statementReferencesNames(
   }
 }
 
-// Walk block looking for `FunctionDefinition` nodes that capture `names`.
 function blockCapturesNames(block: LuaBlock, names: Set<string>): boolean {
   for (let i = 0; i < block.statements.length; i++) {
     if (statementCapturesNames(block.statements[i], names)) return true;
@@ -531,8 +740,6 @@ function statementCapturesNames(s: LuaStatement, names: Set<string>): boolean {
   }
 }
 
-// At loop block level find `FunctionDefinition` and check if it
-// captures `names`.
 function exprCapturesNames(e: LuaExpression, names: Set<string>): boolean {
   if (!e) return false;
   switch (e.type) {
@@ -659,7 +866,6 @@ function parseBlockNode(t: ParseTree, ctx: ASTCtx): LuaBlock {
       case "Label": {
         hasLabel = true;
         hasLabelHere = true;
-        // Duplicate labels in the same block are illegal
         const name = (s as any).name as string;
         if (!dup) {
           if (seen.has(name)) {
@@ -995,7 +1201,6 @@ function parseStatement(t: ParseTree, ctx: ASTCtx): LuaStatement {
     case "break":
       return { type: "Break", ctx: context(t, ctx) };
     default:
-      // Gracefully ignore unknown empty nodes
       if (!t.children || t.children.length === 0) {
         return {
           type: "Semicolon",
@@ -1151,10 +1356,7 @@ function parseExpList(t: ParseTree, ctx: ASTCtx): LuaExpression[] {
 
 const delimiterRegex = /^(\[=*\[)([\s\S]*)(\]=*\])$/;
 
-// In case of quoted strings, remove the quotes and unescape the string
-// In case of a [[ type ]] literal string, remove the brackets
 function parseString(s: string): string {
-  // Handle long strings with delimiters
   const delimiterMatch = s.match(delimiterRegex);
   if (delimiterMatch) {
     let text = delimiterMatch[2];
@@ -1191,11 +1393,9 @@ function parseString(s: string): string {
           case "'":
             return "'"; // Single quote
           default:
-            // Handle hexadecimal \x00
             if (capture.startsWith("x")) {
               return String.fromCharCode(parseInt(capture.slice(1), 16));
             }
-            // Handle unicode \u{XXXX}
             if (capture.startsWith("u{")) {
               const codePoint = parseInt(capture.slice(2, -1), 16);
               return String.fromCodePoint(codePoint);
@@ -1223,7 +1423,6 @@ function parseExpression(t: ParseTree, ctx: ASTCtx): LuaExpression {
       const text = t.children![0].text!.toLowerCase();
       return {
         type: "Number",
-        // Use the integer parser fox 0x literals
         // biome-ignore lint/correctness/useParseIntRadix: hex strings need auto-detect radix
         value: text.includes("x") ? parseInt(text) : parseFloat(text),
         numericType: /[.eEpP]/.test(text) ? "float" : "int",
@@ -1269,7 +1468,11 @@ function parseExpression(t: ParseTree, ctx: ASTCtx): LuaExpression {
       };
 
     case "Parens":
-      return parseExpression(t.children![1], ctx);
+      return {
+        type: "Parenthesized",
+        expression: parseExpression(t.children![1], ctx),
+        ctx: context(t, ctx),
+      };
     case "FunctionCall": {
       return parseFunctionCall(t, ctx);
     }
@@ -1435,7 +1638,6 @@ function parseQueryClause(t: ParseTree, ctx: ASTCtx): LuaQueryClause {
   }
 }
 
-// Parse a single OrderBy node (shared by query OrderByClause and AggOrderBy)
 function parseOrderByNode(child: ParseTree, ctx: ASTCtx): LuaOrderBy {
   const kids = child.children!;
   let direction: "asc" | "desc" = "asc";
@@ -1469,7 +1671,6 @@ function parseOrderByNode(child: ParseTree, ctx: ASTCtx): LuaOrderBy {
   return ob;
 }
 
-// Parse an AggOrderBy node into LuaOrderBy[]
 function parseAggOrderBy(t: ParseTree, ctx: ASTCtx): LuaOrderBy[] {
   if (t.type !== "AggOrderBy") {
     throw new Error(`Expected AggOrderBy, got ${t.type}`);
@@ -1483,7 +1684,6 @@ function parseAggOrderBy(t: ParseTree, ctx: ASTCtx): LuaOrderBy[] {
   return orderBy;
 }
 
-// Parse function args, extracting AggOrderBy if present inside funcParams
 function parseFunctionArgsWithOrderBy(
   ts: ParseTree[],
   ctx: ASTCtx,
@@ -1585,113 +1785,13 @@ function parseTableField(t: ParseTree, ctx: ASTCtx): LuaTableField {
   }
 }
 
-export function stripLuaComments(s: string): string {
-  let result = "";
-  let i = 0;
-
-  while (i < s.length) {
-    // Check for long string
-    if (s[i] === "[") {
-      let j = i + 1;
-      let equalsCount = 0;
-      while (s[j] === "=") {
-        equalsCount++;
-        j++;
-      }
-      if (s[j] === "[") {
-        // Found long string start
-        const openBracket = s.substring(i, j + 1);
-        const closeBracket = `]${"=".repeat(equalsCount)}]`;
-        result += openBracket;
-        i = j + 1;
-
-        // Find matching closing bracket
-        const content = s.substring(i);
-        const closeIndex = content.indexOf(closeBracket);
-        if (closeIndex !== -1) {
-          // Copy string content verbatim, including any comment-like sequences
-          result += content.substring(0, closeIndex) + closeBracket;
-          i += closeIndex + closeBracket.length;
-          continue;
-        }
-      }
-    }
-
-    // Check for single quoted string
-    if (s[i] === '"' || s[i] === "'") {
-      const quote = s[i];
-      result += quote;
-      i++;
-      while (i < s.length && s[i] !== quote) {
-        if (s[i] === "\\") {
-          result += s[i] + s[i + 1];
-          i += 2;
-        } else {
-          result += s[i];
-          i++;
-        }
-      }
-      if (i < s.length) {
-        result += s[i]; // closing quote
-        i++;
-      }
-      continue;
-    }
-
-    // Check for comments
-    if (s[i] === "-" && s[i + 1] === "-") {
-      // Replace the -- with spaces
-      result += "  ";
-      i += 2;
-
-      // Check for long comment
-      if (s[i] === "[") {
-        let j = i + 1;
-        let equalsCount = 0;
-        while (s[j] === "=") {
-          equalsCount++;
-          j++;
-        }
-        if (s[j] === "[") {
-          // Found long comment start
-          const closeBracket = `]${"=".repeat(equalsCount)}]`;
-          // Replace opening bracket with spaces
-          result += " ".repeat(j - i + 1);
-          i = j + 1;
-
-          // Find matching closing bracket
-          const content = s.substring(i);
-          const closeIndex = content.indexOf(closeBracket);
-          if (closeIndex !== -1) {
-            // Replace comment content and closing bracket with spaces
-            result += " ".repeat(closeIndex) + " ".repeat(closeBracket.length);
-            i += closeIndex + closeBracket.length;
-            continue;
-          }
-        }
-      }
-
-      // Single line comment - replace rest of line with spaces
-      while (i < s.length && s[i] !== "\n") {
-        result += " ";
-        i++;
-      }
-      continue;
-    }
-
-    result += s[i];
-    i++;
-  }
-
-  return result;
-}
-
 export function parseBlock(s: string, ctx: ASTCtx = {}): LuaBlock {
   try {
-    const t = parseToAST(stripLuaComments(s));
-    // console.log("Clean tree", JSON.stringify(t, null, 2));
-    const result = parseChunk(t, ctx);
-    // console.log("Parsed AST", JSON.stringify(result, null, 2));
+    const concreteTree = parseToAST(s);
+    const comments = collectLuaComments(concreteTree, ctx);
+    const result = parseChunk(withoutComments(concreteTree), ctx);
+    assignCommentsToBlocks(result, comments, s);
+    attachFunctionDocumentation(result, comments, s);
     getBlockGotoMeta(result);
     return result;
   } catch (e: any) {
@@ -1716,7 +1816,25 @@ export function parseToAST(t: string): ParseTree {
   }
 
   const n = lezerToParseTree(t, tree.topNode);
-  return cleanTree(n, true);
+  return cleanLuaTree(n);
+}
+
+function cleanLuaTree(tree: ParseTree): ParseTree {
+  if (tree.type === "⚠") {
+    throw new Error(`Parse error at pos ${tree.from}`);
+  }
+  if (tree.text !== undefined) return tree;
+  const result: ParseTree = {
+    type: tree.type,
+    children: [],
+    from: tree.from,
+    to: tree.to,
+  };
+  for (const node of tree.children ?? []) {
+    if (node.type) result.children!.push(cleanLuaTree(node));
+    if (node.text?.trim()) result.children!.push(node);
+  }
+  return result;
 }
 
 function findFirstParseError(node: SyntaxNode): SyntaxNode | null {