@gmickel/gno 2.8.2 → 2.8.4

package/src/converters/adapters/xlsx/sheet-markdown.ts

@@ -0,0 +1,312 @@
+/**
+ * Worksheet to Markdown table, linear in cells (fn-198).
+ *
+ * Reproduces the Markdown the markitdown-ts chain produces for a worksheet
+ * (SheetJS `sheet_to_html` -> jsdom -> turndown + Joplin GFM tables) without
+ * building a DOM. That chain is O(columns x rows^2) and uses about 20 KB per
+ * cell: the GFM plugin's column-alignment scan re-reads `table.rows.length`
+ * through a jsdom proxy for every row of every column. Here each cell is
+ * rendered once from the sheet data:
+ *
+ * - cell text is chosen as `sheet_to_html` does (`h`, or escaped `w`),
+ * - plain text goes through turndown's whitespace collapsing and Markdown
+ *   escaping, per line (a line break starts a new text node),
+ * - cells whose HTML carries markup (rich-text runs, hyperlinks) are
+ *   converted by turndown itself with the same rules, one cell at a time,
+ * - rows, the empty heading row, `---` borders (SheetJS never sets an
+ *   alignment), merges (`colspan` padding, covered cells skipped) and the
+ *   single-cell-table case follow the GFM plugin.
+ *
+ * @module src/converters/adapters/xlsx/sheet-markdown
+ */
+
+import type { CellObject, WorkSheet } from "xlsx";
+
+// @ts-expect-error -- @joplin/turndown-plugin-gfm ships no types
+import turndownPluginGfm from "@joplin/turndown-plugin-gfm";
+// @ts-expect-error -- turndown ships no types
+import TurndownService from "turndown";
+import * as XLSX from "xlsx";
+
+/** The part of turndown's API this module uses. */
+interface Turndown {
+  turndown(html: string): string;
+  use(plugin: unknown): Turndown;
+  addRule(
+    key: string,
+    rule: {
+      filter: string[];
+      replacement: (
+        content: string,
+        node: { getAttribute(name: string): string | null; title: string }
+      ) => string;
+    }
+  ): Turndown;
+}
+const TurndownConstructor = TurndownService as new (options: {
+  headingStyle: "atx";
+}) => Turndown;
+
+/** SheetJS `escapehtml` (xlsx 0.20.3), used to recognise plain cell HTML. */
+const HTML_ENCODINGS: Record<string, string> = {
+  '"': "&quot;",
+  "'": "&apos;",
+  ">": "&gt;",
+  "<": "&lt;",
+  "&": "&amp;",
+};
+const escapeHtml = (text: string): string =>
+  text
+    .replace(/[&<>'"]/g, (char) => HTML_ENCODINGS[char] ?? char)
+    .replace(/\n/g, "<br/>")
+    .replace(
+      // oxlint-disable-next-line no-control-regex -- SheetJS htmlcharegex: C0 controls become numeric references
+      /[\u0000-\u001f]/g,
+      (char) => `&#x${`000${char.charCodeAt(0).toString(16)}`.slice(-4)};`
+    );
+
+/** turndown 7.2 `escapeMarkdown`, applied to each text node. */
+const MARKDOWN_ESCAPES: Array<[RegExp, string]> = [
+  [/\\/g, "\\\\"],
+  [/\*/g, "\\*"],
+  [/^-/g, "\\-"],
+  [/^\+ /g, "\\+ "],
+  [/^(=+)/g, "\\$1"],
+  [/^(#{1,6}) /g, "\\$1 "],
+  [/`/g, "\\`"],
+  [/^~~~/g, "\\~~~"],
+  [/\[/g, "\\["],
+  [/\]/g, "\\]"],
+  [/^>/g, "\\>"],
+  [/_/g, "\\_"],
+  [/^(\d+)\. /g, "$1\\. "],
+];
+/** Cheap pre-test: text that no escape rule can touch skips the chain. */
+const MAY_NEED_ESCAPE = /[\\*`[\]_]|^[-+=#~>\d]/;
+
+const escapeMarkdown = (text: string): string =>
+  MAY_NEED_ESCAPE.test(text)
+    ? MARKDOWN_ESCAPES.reduce(
+        (value, [pattern, replacement]) => value.replace(pattern, replacement),
+        text
+      )
+    : text;
+
+/** turndown's `<br>` replacement with the default `br: "  "` option. */
+const LINE_BREAK = "  \n";
+
+/**
+ * Plain cell text as turndown renders it inside a table cell: each line is a
+ * text node whose whitespace runs collapse to one space, with the leading
+ * and trailing space dropped (cells and line breaks are block boundaries),
+ * escaped on its own; every line break renders, empty lines included.
+ */
+const plainCellContent = (text: string): string => {
+  const lines: string[] = [];
+  for (const raw of text.split("\n")) {
+    // The HTML parser turns the escaped NUL (&#x0000;) into U+FFFD.
+    const line = raw
+      .replaceAll("\u0000", "\uFFFD")
+      .replace(/[ \r\n\t]+/g, " ")
+      .replace(/^ | $/g, "");
+    lines.push(line ? escapeMarkdown(line) : "");
+  }
+  return lines.join(LINE_BREAK);
+};
+
+let markupTurndown: Turndown | null = null;
+const markupCache = new Map<string, string>();
+
+/**
+ * Cell HTML with markup (rich-text runs, a hyperlink), converted by turndown
+ * with markitdown's rules. A paragraph gives the same block context as a
+ * table cell.
+ */
+const markupCellContent = (html: string): string => {
+  const cached = markupCache.get(html);
+  if (cached !== undefined) return cached;
+  markupTurndown ??= createMarkitdownTurndown();
+  const content = markupTurndown.turndown(`<p>${html}</p>`);
+  markupCache.set(html, content);
+  return content;
+};
+
+/** markitdown-ts `CustomTurnDown` configuration (vendored dist). */
+function createMarkitdownTurndown(): Turndown {
+  const service = new TurndownConstructor({ headingStyle: "atx" });
+  service.use((turndownPluginGfm as { gfm: unknown }).gfm);
+  service.addRule("anchor tags", {
+    filter: ["a"],
+    replacement(content, node) {
+      if (content === "") return "";
+      const prefix = content[0] === " " ? " " : "";
+      const suffix = content.at(-1) === " " ? " " : "";
+      const text = content.trim().replace(/\n\n.*/g, "");
+      if (text === "") return "";
+      const href = node.getAttribute("href");
+      let title = node.title;
+      if (href) {
+        try {
+          const parsed = new URL(href);
+          if (!["https:", "http:", "file:"].includes(parsed.protocol)) {
+            return `${prefix}${text}${suffix}`;
+          }
+        } catch {
+          if (!/^https?:|^file:/.test(href)) {
+            return `${prefix}[${text}](${href} "${title}")${suffix}`;
+          }
+          return `${prefix}${text}${suffix}`;
+        }
+      }
+      if (text.replace(/\\_/g, "_") === href && !title) return `<${href}>`;
+      if (!title && href) title = href;
+      const titlePart = title ? ` "${title}"` : "";
+      return `${prefix}[${text}](${href}${titlePart})${suffix}`;
+    },
+  });
+  return service;
+}
+
+/** Joplin GFM `cell()`: trim, `<br>` for newlines, escape pipes, pad. */
+const formatCell = (content: string, first: boolean, colspan: number) => {
+  let value = content
+    .trim()
+    .replace(/\n\r/g, "<br>")
+    .replace(/\n/g, "<br>")
+    .replace(/\|+/g, "\\|");
+  while (value.length < 3) value += " ";
+  for (let extra = 1; extra < colspan; extra += 1) value += " |    ";
+  return `${first ? "| " : " "}${value} |`;
+};
+
+/** SheetJS error text for non-finite numbers (`make_html_row`). */
+const nonFiniteText = (value: number): string =>
+  Number.isNaN(value) ? "#NUM!" : "#DIV/0!";
+
+/**
+ * Cell Markdown content (before `formatCell`), from the HTML `make_html_row`
+ * (xlsx 0.20.3) writes for it: `h` if present, else the escaped formatted
+ * text, wrapped in a link for an external hyperlink. HTML that is exactly
+ * the escaped text is rendered from the text; any other HTML goes through
+ * turndown.
+ */
+const cellContent = (cell: CellObject | undefined): string => {
+  if (!cell || cell.v == null) return "";
+  let text: string;
+  let html: string;
+  if (cell.t === "n" && !Number.isFinite(cell.v as number)) {
+    // SheetJS swaps in an error cell, which has no `h` and no hyperlink.
+    text = nonFiniteText(cell.v as number);
+    return text ? plainCellContent(text) : "";
+  }
+  if (cell.h) {
+    html = cell.h;
+    text = typeof cell.v === "string" ? cell.v : "";
+  } else {
+    text =
+      cell.w ||
+      (XLSX.utils.format_cell(cell), cell.w as string | undefined) ||
+      "";
+    html = escapeHtml(text);
+  }
+  if (!html) return "";
+  const target = cell.l?.Target;
+  if (target && target.charAt(0) !== "#") {
+    return markupCellContent(`<a href="${escapeHtml(target)}">${html}</a>`);
+  }
+  return escapeHtml(text) === html
+    ? plainCellContent(text)
+    : markupCellContent(html);
+};
+
+interface MergeSpan {
+  rowspan: number;
+  colspan: number;
+}
+
+/**
+ * Merge lookup as `make_html_row` resolves it: the first merge (in sheet
+ * order) containing a cell decides; its top-left cell carries the span and
+ * the other covered cells are skipped.
+ */
+const mergeLookup = (
+  merges: XLSX.Range[]
+): ((row: number, col: number) => MergeSpan | "covered" | undefined) => {
+  if (merges.length === 0) return () => undefined;
+  const byCell = new Map<string, MergeSpan | "covered">();
+  for (let index = merges.length - 1; index >= 0; index -= 1) {
+    const merge = merges[index];
+    if (!merge) continue;
+    for (let row = merge.s.r; row <= merge.e.r; row += 1) {
+      for (let col = merge.s.c; col <= merge.e.c; col += 1) {
+        byCell.set(
+          `${row}:${col}`,
+          row === merge.s.r && col === merge.s.c
+            ? {
+                rowspan: merge.e.r - merge.s.r + 1,
+                colspan: merge.e.c - merge.s.c + 1,
+              }
+            : "covered"
+        );
+      }
+    }
+  }
+  return (row, col) => byCell.get(`${row}:${col}`);
+};
+
+const readCell = (
+  sheet: WorkSheet,
+  row: number,
+  col: number
+): CellObject | undefined => {
+  const dense = (sheet as { "!data"?: CellObject[][] })["!data"];
+  if (dense) return dense[row]?.[col];
+  return sheet[XLSX.utils.encode_cell({ r: row, c: col })] as
+    | CellObject
+    | undefined;
+};
+
+/**
+ * Markdown for one worksheet with a `!ref`, trimmed as markitdown trims it.
+ * Output matches `turndown(sheet_to_html(sheet))` for the same sheet.
+ */
+export function sheetToMarkdown(sheet: WorkSheet): string {
+  // Memoized markup is per sheet: the file processor reuses one worker across
+  // files, so a process-wide cache would retain every earlier workbook.
+  markupCache.clear();
+  const range = XLSX.utils.decode_range(sheet["!ref"] ?? "A1");
+  const mergeAt = mergeLookup(sheet["!merges"] ?? []);
+  const rows: string[] = [];
+  let columnCount = 0;
+  let onlyCell: string | null = null;
+  let firstRowCells = 0;
+  for (let row = range.s.r; row <= range.e.r; row += 1) {
+    const cells: string[] = [];
+    let cellCount = 0;
+    for (let col = range.s.c; col <= range.e.c; col += 1) {
+      const merge = mergeAt(row, col);
+      if (merge === "covered") continue;
+      const content = cellContent(readCell(sheet, row, col));
+      cells.push(formatCell(content, cellCount === 0, merge?.colspan ?? 1));
+      cellCount += 1;
+      onlyCell = content;
+    }
+    columnCount = Math.max(columnCount, cellCount);
+    if (row === range.s.r) firstRowCells = cellCount;
+    // A row whose cells are all covered by merges renders as an empty line,
+    // which the GFM plugin collapses away.
+    if (cells.length > 0) rows.push(cells.join(""));
+  }
+
+  // A one-row table with at most one cell is left as plain content.
+  if (range.e.r === range.s.r && firstRowCells <= 1) {
+    return (onlyCell ?? "").trim();
+  }
+
+  const secondLine = rows[1] ?? "";
+  const header =
+    columnCount && !/\| :?---/.test(secondLine)
+      ? `|${"     |".repeat(columnCount)}\n|${" --- |".repeat(columnCount)}\n`
+      : "";
+  return `${header}${rows.join("\n")}`.trim();
+}

package/src/converters/registry.ts

@@ -10,7 +10,7 @@ import type {
   RecordAdapter,
 } from "./types";
 
-import { unsupportedError } from "./errors";
+import { adapterError, unsupportedError } from "./errors";
 
 export class ConverterRegistry {
   private readonly converters: Converter[] = [];
@@ -71,13 +71,48 @@ export class ConverterRegistry {
   }
 }
 
+/**
+ * Load an adapter module; if it cannot load in this runtime, stand in a
+ * converter that fails its file types with ADAPTER_FAILURE and the reason.
+ */
+export async function loadAdapter(
+  load: () => Promise<Converter>,
+  id: string,
+  extensions: readonly string[],
+  mimes: readonly string[]
+): Promise<Converter> {
+  try {
+    return await load();
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    return {
+      id,
+      version: "unavailable",
+      // Same matching as the real adapter, so a sniffed MIME without an
+      // extension still reports ADAPTER_FAILURE, not UNSUPPORTED.
+      canHandle: (mime, ext) =>
+        extensions.includes(ext) || mimes.includes(mime),
+      convert: (input) =>
+        Promise.resolve({
+          ok: false,
+          error: adapterError(
+            input,
+            id,
+            `${id} is unavailable in this build: ${reason}`
+          ),
+        }),
+    };
+  }
+}
+
 /**
  * Create the default registry with all MVP converters.
  * Priority order per PRD §8.6:
  * 1. native/markdown - handles .md
  * 2. native/plaintext - handles .txt
- * 3. adapter/markitdown-ts - handles .pdf, .docx, .xlsx
- * 4. adapter/officeparser - handles .pptx
+ * 3. adapter/xlsx - handles .xlsx (linear SheetJS -> Markdown tables)
+ * 4. adapter/markitdown-ts - handles .pdf, .docx
+ * 5. adapter/officeparser - handles .pptx
  */
 export async function createDefaultRegistry(): Promise<ConverterRegistry> {
   const registry = new ConverterRegistry();
@@ -85,9 +120,29 @@ export async function createDefaultRegistry(): Promise<ConverterRegistry> {
   // Import converters dynamically to avoid circular deps
   const { markdownConverter } = await import("./native/markdown");
   const { plaintextConverter } = await import("./native/plaintext");
-  const { markitdownAdapter } = await import("./adapters/markitdownTs/adapter");
-  const { officeparserAdapter } =
-    await import("./adapters/officeparser/adapter");
+  const { xlsxAdapter } = await import("./adapters/xlsx/adapter");
+  // The PDF/Office adapters load pdf.js, which cannot initialize where its
+  // native canvas binding is missing (a standalone compiled executable). A
+  // failed adapter only fails its own file types.
+  const markitdownAdapter = await loadAdapter(
+    async () =>
+      (await import("./adapters/markitdownTs/adapter")).markitdownAdapter,
+    "adapter/markitdown-ts",
+    [".pdf", ".docx"],
+    [
+      "application/pdf",
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ]
+  );
+  const officeparserAdapter = await loadAdapter(
+    async () =>
+      (await import("./adapters/officeparser/adapter")).officeparserAdapter,
+    "adapter/officeparser",
+    [".pptx"],
+    [
+      "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ]
+  );
   const { jsonlAdapter } = await import("./adapters/jsonl/adapter");
   const { transcriptAdapter } = await import("./adapters/transcript/adapter");
   const { emailRecordAdapter } = await import("./adapters/email/adapter");
@@ -98,6 +153,7 @@ export async function createDefaultRegistry(): Promise<ConverterRegistry> {
   // Register in priority order
   registry.register(markdownConverter);
   registry.register(plaintextConverter);
+  registry.register(xlsxAdapter);
   registry.register(markitdownAdapter);
   registry.register(officeparserAdapter);
   registry.registerRecordAdapter(jsonlAdapter);

package/src/converters/versions.ts

@@ -18,5 +18,7 @@ export const NATIVE_VERSIONS = {
  */
 export const ADAPTER_VERSIONS = {
   "markitdown-ts": "0.0.10+xlsx.0.20.3",
+  /** Direct SheetJS -> Markdown tables (fn-198); output matches markitdown. */
+  xlsx: "sheetjs-0.20.3+md.1",
   officeparser: "7.8.0+pdfjs.6.3.289",
 } as const;

package/src/core/activation-empty.ts

@@ -0,0 +1,16 @@
+/**
+ * Empty-collection rule shared by server surfaces and the Web UI bundle, so
+ * it carries type imports only.
+ */
+
+import type { ActivationCollectionStatus } from "./activation-status";
+
+/**
+ * A collection with nothing indexed yet: its only activation problem is
+ * `no_documents`. Surfaces show it as informational, never as a failure.
+ */
+export function isEmptyActivationCollection(
+  collection: Pick<ActivationCollectionStatus, "ready" | "remediation">
+): boolean {
+  return !collection.ready && collection.remediation?.code === "no_documents";
+}

package/src/core/activation-status.ts

@@ -14,6 +14,7 @@ import type {
   ConnectorVerificationTarget,
 } from "./connector-verifier";
 
+import { isEmptyActivationCollection } from "./activation-empty";
 import { createEphemeralActivationProbePlan } from "./activation-probe-plan";
 import { verifyLexicalActivation } from "./activation-verifier";
 import {
@@ -73,7 +74,13 @@ export interface ActivationConnectorStatus {
 
 export interface ActivationStatus {
   schemaVersion: "1.0";
+  /** At least one collection passed the lexical proof. */
   usable: boolean;
+  /**
+   * At least one collection is configured and none failed its proof. A
+   * collection with no documents yet is not a failure (see
+   * `isEmptyActivationCollection`), so it does not clear this flag.
+   */
   healthy: boolean;
   collections: ActivationCollectionStatus[];
   /** Only fingerprint-current persisted connector receipts may appear here. */
@@ -178,10 +185,13 @@ function remediationFor(
   stage: ActivationStageName,
   code: ActivationVerificationCode
 ): ActivationRemediation {
-  const command = `gno index ${collection} --no-embed`;
+  const command =
+    code === "no_documents"
+      ? "gno update"
+      : `gno index ${collection} --no-embed`;
   const messages: Partial<Record<ActivationVerificationCode, string>> = {
     no_documents:
-      "Index at least one supported text document in this collection.",
+      "No documents are indexed yet. Add supported files to this collection's folder, then run gno update.",
     no_probe_term:
       "Add searchable text or adjust the collection filters, then reindex.",
     index_query_failed:
@@ -322,7 +332,11 @@ async function buildConnectorStatuses(
 ): Promise<{ items: ActivationConnectorStatus[]; total: number }> {
   const sortedTargets = [...targets].sort((a, b) => a.id.localeCompare(b.id));
   const boundedTargets = sortedTargets.slice(0, MAX_CONNECTOR_TARGETS);
-  const allPairs = collections.flatMap((collection) =>
+  // A collection with no documents gives a connector nothing to prove.
+  const provable = collections.filter(
+    ({ projected }) => !isEmptyActivationCollection(projected)
+  );
+  const allPairs = provable.flatMap((collection) =>
     boundedTargets.map((target) => ({ collection, target }))
   );
   const items = await mapBounded(
@@ -363,7 +377,7 @@ async function buildConnectorStatuses(
       };
     }
   );
-  return { items, total: collections.length * sortedTargets.length };
+  return { items, total: provable.length * sortedTargets.length };
 }
 
 async function verifyCoalesced(
@@ -501,7 +515,11 @@ export async function buildActivationStatus(
     schemaVersion: "1.0",
     usable: projected.some((collection) => collection.ready),
     healthy:
-      projected.length > 0 && projected.every((collection) => collection.ready),
+      projected.length > 0 &&
+      projected.every(
+        (collection) =>
+          collection.ready || isEmptyActivationCollection(collection)
+      ),
     collections: projected,
     connectors: connectorStatuses.items,
     connectorProjection: {

package/src/core/audit-freshness.ts

@@ -144,7 +144,7 @@ export const evaluateFreshnessAudit = (
           document,
           kind: "stale-indexed-revision",
           message: document.lastErrorCode
-            ? "The latest indexing attempt recorded an error"
+            ? `The latest indexing attempt recorded an error (${document.lastErrorCode})`
             : "The document has no indexed-at revision evidence",
           detail: {
             indexedAt: document.indexedAt,

package/src/core/audit-outside-index.ts

@@ -19,7 +19,10 @@ import { readdir, realpath, stat } from "node:fs/promises";
 // node:path join: platform path algebra; no Bun equivalent.
 import { join } from "node:path";
 
-import type { AuditLinkSnapshot } from "../store/sqlite/graph-link-resolver";
+import type {
+  AuditLinkSnapshot,
+  AuditLinkSnapshotLink,
+} from "../store/sqlite/graph-link-resolver";
 
 import {
   createWorkspaceFileMatcher,
@@ -30,6 +33,27 @@ import { pathContains, placeDocument } from "./link-workspace";
 /** Path identity for exact-path matching: NFC, case-insensitive. */
 const pathKey = (path: string): string => path.normalize("NFC").toLowerCase();
 
+/**
+ * A Markdown link names the file's exact path; as with wiki links, `.md` is
+ * optional, so `[x](Note)` matches an unindexed `Note.md`. An indexed
+ * `Note.md` is not outside the index, so that link keeps its status. Indexed
+ * paths are compared under the same key as listed files (NFC, Unicode
+ * lowercase), never SQLite's ASCII-only NOCASE.
+ */
+const markdownTargetExists = (
+  link: AuditLinkSnapshotLink,
+  targetPath: string,
+  paths: ReadonlySet<string> | undefined,
+  indexedKeys: (collection: string) => ReadonlySet<string>
+): boolean => {
+  const key = pathKey(targetPath);
+  if (paths?.has(key) === true) return true;
+  if (key.endsWith(".md") || paths?.has(`${key}.md`) !== true) return false;
+  return !indexedKeys(link.targetCollection).has(
+    pathKey(`${link.targetRefNorm}.md`)
+  );
+};
+
 /** Upper bound of files listed per workspace; beyond it the listing is partial. */
 export const WORKSPACE_FILE_LISTING_MAX_FILES = 200_000;
 
@@ -152,7 +176,7 @@ export const listWorkspaceFiles = async (
  * Mark unresolved plain wiki links and relative Markdown links of audited
  * documents inside a link workspace whose target exists as a workspace file.
  * A wiki link matches under workspace resolution rules; a Markdown link must
- * name the file's exact path (NFC, case-insensitive). Each involved workspace
+ * name the file's exact path (NFC, case-insensitive), `.md` optional. Each involved workspace
  * is listed once per call. A failed or partial listing never marks a link
  * that is not in it; the snapshot then carries one diagnostic.
  */
@@ -220,12 +244,33 @@ export const markOutsideIndexLinks = async (
       paths: new Set(listing.files.map(pathKey)),
     });
   }
+  const indexedByCollection = new Map<string, Set<string>>();
+  const indexedKeys = (collection: string): ReadonlySet<string> => {
+    let keys = indexedByCollection.get(collection);
+    if (!keys) {
+      keys = new Set(
+        db
+          .query<{ relPath: string }, [string]>(
+            "SELECT rel_path AS relPath FROM documents WHERE active = 1 AND collection = ?"
+          )
+          .all(collection)
+          .map(({ relPath }) => pathKey(relPath))
+      );
+      indexedByCollection.set(collection, keys);
+    }
+    return keys;
+  };
   const links = [...snapshot.links];
   for (const entry of placed) {
     const listing = listings.get(entry.key);
     const exists =
       "targetPath" in entry
-        ? listing?.paths.has(pathKey(entry.targetPath)) === true
+        ? markdownTargetExists(
+            entry.link,
+            entry.targetPath,
+            listing?.paths,
+            indexedKeys
+          )
         : listing?.matches(entry.link.targetRefNorm, entry.sourcePath) === true;
     if (exists) {
       links[entry.index] = { ...entry.link, outsideIndex: true };

package/src/core/change-diff.ts

@@ -104,15 +104,27 @@ const extractTypedEdges = (markdown: string): string[] => {
   return [...new Set(values)].sort();
 };
 
+export interface DocumentStructureOptions {
+  /** Only Markdown sources carry links (matches link extraction at sync). */
+  markdownSource: boolean;
+  excludedRanges?: ExcludedRange[];
+}
+
 export const extractDocumentStructure = (
   markdown: string,
   relPath: string,
   dateFields: Readonly<Record<string, string>> | null | undefined,
-  excludedRanges: ExcludedRange[] = getExcludedRanges(markdown)
+  { markdownSource, excludedRanges }: DocumentStructureOptions
 ): DocumentStructureSnapshot => {
-  const links = parseLinks(markdown, buildLineOffsets(markdown), excludedRanges)
-    .map((link) => linkSummary(link, relPath))
-    .filter((value): value is string => value !== null);
+  const links = markdownSource
+    ? parseLinks(
+        markdown,
+        buildLineOffsets(markdown),
+        excludedRanges ?? getExcludedRanges(markdown)
+      )
+        .map((link) => linkSummary(link, relPath))
+        .filter((value): value is string => value !== null)
+    : [];
 
   return {
     headings: withOccurrences(

package/src/core/link-destination-parse.ts

@@ -42,6 +42,19 @@ const COMMONMARK_ESCAPABLE = new Set([
   " ",
 ]);
 
+/**
+ * True when the character at `index` is backslash-escaped: preceded by an odd
+ * number of backslashes. An escaped `[` is literal text in CommonMark and
+ * cannot open a link.
+ */
+export function isBackslashEscaped(text: string, index: number): boolean {
+  let backslashes = 0;
+  for (let i = index - 1; i >= 0 && text[i] === "\\"; i -= 1) {
+    backslashes += 1;
+  }
+  return backslashes % 2 === 1;
+}
+
 export interface LinkEncodingStyle {
   spaces: "percent" | "backslash" | "raw";
   parens: "percent" | "backslash" | "raw";
@@ -220,10 +233,10 @@ export function parseParenthesizedDestination(
         i += 1;
         continue;
       }
-      if (
-        depth === 0 &&
-        (ch === " " || ch === "\t" || ch === "\n" || ch === "\r")
-      ) {
+      if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+        // CommonMark: a bare destination has no unescaped whitespace, inside
+        // nested parentheses too (`(foo(bar baz).md)` is not a link).
+        if (depth > 0) return null;
         destEnd = i;
         break;
       }
@@ -262,6 +275,10 @@ export function parseParenthesizedDestination(
     close = j;
   }
 
+  // The destination and optional title must end at a real `)`:
+  // `[x](<note.md>` or `[x](<note.md>.` is not a link.
+  if (markdown[close] !== ")") return null;
+
   const destinationRaw = markdown.slice(destStart, destEnd);
   if (!destinationRaw) return null;
   return {