Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
7.0 KB
Raw Blame
/**
 * Extract wikilinks, markdown links, and tags from a chunk of Markdown.
 *
 * Anchored in docs/plans/2026-05-16-brain-search-design.md §5 (links
 * table). Returns the link rows that `store.replaceLinks` expects, but
 * leaves the source-chunk binding to the indexer (it knows which
 * chunk produced the content).
 *
 * Code fences and inline-code spans are stripped before extraction so
 * a code sample mentioning `[[foo]]` or `#hash` does not become a real
 * link. This is best-effort: nested fenced fences are rare and we err
 * on the side of stripping too much rather than capturing junk links.
 *
 * Reference-style links (CommonMark) are also resolved: a first pass
 * collects `[label]: target` definitions, then full (`[text][label]`),
 * collapsed (`[text][]`), and shortcut (`[text]`) references are matched
 * against them and emitted as `markdown_link` rows — the same shape and
 * `isUrl`/`isMailto`/anchor-strip filtering the inline form uses. Like
 * inline links, resolution is scoped to the content passed in (a single
 * chunk): a definition and a reference that land in different chunks are
 * not cross-resolved, mirroring the existing per-chunk extraction unit.
 */

import { hasUriScheme } from "../path-safety.ts";
import { WIKILINK_ALIAS_RE } from "../brain/wikilink.ts";
import { extractTagValues, stripCode } from "../tags.ts";

export type LinkType = "wikilink" | "markdown_link" | "tag";

export interface ExtractedLink {
  readonly targetPath: string | null;
  readonly linkText: string | null;
  readonly linkType: LinkType;
}

// Negative lookbehind so `![alt](url)` image embeds are NOT captured as
// markdown_link. CodeRabbit caught this regression on PR #15.
const MD_LINK_RE = /(?<!!)\[([^\]\n]*)\]\(([^)\n\s]+)(?:\s+"[^"\n]*")?\)/g;
// Reference-link definition: `[label]: target` with up to 3 leading spaces
// (4+ would be an indented code block in CommonMark). The target is a bare
// token or an `<...>` form; an optional title (quoted or parenthesised)
// follows. Only single-line definitions are recognised — the rare
// title-on-next-line form is treated as no title.
const REF_DEF_RE =
  /^ {0,3}\[([^\]\n]+)\]:[ \t]*(?:<([^>\n]+)>|(\S+))(?:[ \t]+(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\)))?[ \t]*$/gm;
// Reference usage. Matches `[text]`, `[text][]`, and `[text][label]`. The
// leading `!` is captured (not a lookbehind) so a `![text][label]` image embed
// is consumed as one unit and skipped, rather than leaving its `[label]` to be
// re-read as a shortcut reference. The link text / label may not contain
// unescaped brackets or newlines.
const REF_LINK_RE = /(!?)\[([^\]\n]+)\](?:\[([^\]\n]*)\])?/g;

/** An external address rather than a note path - see {@link hasUriScheme}. */
const isUrl = hasUriScheme;

function isMailto(target: string): boolean {
  return target.toLowerCase().startsWith("mailto:");
}

// Shared target normalisation for inline and reference-style markdown links:
// reject external URLs / mailto, strip the optional `#anchor` fragment, and
// return the bare path — or null when nothing link-worthy remains.
function resolveMarkdownTarget(rawTarget: string): string | null {
  const target = rawTarget.trim();
  if (target === "" || isUrl(target) || isMailto(target)) return null;
  const hashIdx = target.indexOf("#");
  const path = hashIdx >= 0 ? target.slice(0, hashIdx) : target;
  return path === "" ? null : path;
}

// CommonMark reference labels are case-insensitive and collapse internal
// whitespace runs to a single space after trimming.
function normaliseLabel(label: string): string {
  return label.trim().replace(/\s+/g, " ").toLowerCase();
}

function dedupe(links: ExtractedLink[]): ExtractedLink[] {
  const seen = new Set<string>();
  const out: ExtractedLink[] = [];
  for (const l of links) {
    const key = `${l.linkType}|${l.targetPath ?? ""}|${l.linkText ?? ""}`;
    if (seen.has(key)) continue;
    seen.add(key);
    out.push(l);
  }
  return out;
}

/**
 * Resolve CommonMark reference-style links against their definitions and
 * append the resolved `markdown_link` rows to `out`. Operates on
 * already-code-stripped content.
 *
 * Two passes: first collect every `[label]: target` definition (the
 * definition lines are then blanked so their own `[label]` does not read
 * as a shortcut reference), then scan for full / collapsed / shortcut
 * references. Shortcut `[text]` references are only emitted when `text`
 * resolves to a known definition — that gate is what keeps ordinary
 * bracketed prose from becoming spurious edges.
 */
function extractReferenceLinks(cleaned: string, out: ExtractedLink[]): void {
  const defs = new Map<string, string>();
  for (const m of cleaned.matchAll(REF_DEF_RE)) {
    const label = normaliseLabel(m[1] ?? "");
    const rawTarget = m[2] ?? m[3] ?? "";
    if (label === "" || rawTarget === "") continue;
    // First definition wins, matching CommonMark.
    if (!defs.has(label)) defs.set(label, rawTarget);
  }
  if (defs.size === 0) return;

  // Blank out definition lines so the `[label]` in `[label]: target` is not
  // re-read as a shortcut reference below.
  const body = cleaned.replace(REF_DEF_RE, "");

  for (const m of body.matchAll(REF_LINK_RE)) {
    if (m[1] === "!") continue; // image embed — consumed but not an edge
    const text = (m[2] ?? "").trim();
    const second = m[3];
    let label: string;
    let linkText: string;
    if (second === undefined) {
      // Shortcut reference `[text]`. Skip if the next char makes this an
      // inline link `[text](…)` or a definition `[text]:` instead.
      const after = body[m.index + m[0].length];
      if (after === "(" || after === ":") continue;
      label = text;
      linkText = text;
    } else if (second.trim() === "") {
      // Collapsed reference `[text][]`: the text doubles as the label.
      label = text;
      linkText = text;
    } else {
      // Full reference `[text][label]`.
      label = second;
      linkText = text;
    }
    const rawTarget = defs.get(normaliseLabel(label));
    if (rawTarget === undefined) continue;
    const path = resolveMarkdownTarget(rawTarget);
    if (path === null) continue;
    out.push({
      targetPath: path,
      linkText: linkText || null,
      linkType: "markdown_link",
    });
  }
}

export function extractLinks(content: string): ExtractedLink[] {
  const cleaned = stripCode(content);
  const out: ExtractedLink[] = [];

  for (const m of cleaned.matchAll(WIKILINK_ALIAS_RE)) {
    const target = (m[1] ?? "").trim();
    const alt = m[2] ? m[2].trim() : null;
    if (target === "") continue;
    out.push({
      targetPath: target,
      linkText: alt,
      linkType: "wikilink",
    });
  }

  for (const m of cleaned.matchAll(MD_LINK_RE)) {
    const text = (m[1] ?? "").trim();
    const path = resolveMarkdownTarget(m[2] ?? "");
    if (path === null) continue;
    out.push({
      targetPath: path,
      linkText: text || null,
      linkType: "markdown_link",
    });
  }

  extractReferenceLinks(cleaned, out);

  for (const tag of extractTagValues(cleaned)) {
    out.push({
      targetPath: null,
      linkText: tag,
      linkType: "tag",
    });
  }

  return dedupe(out);
}