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
5.1 KB
Raw Blame
/**
 * Shared readers for the sources a Brain page cites.
 *
 * One implementation for every consumer that has to answer "which sources
 * does this page rest on": the delete-by-source cleanup (`source-cleanup.ts`)
 * and the capture-scope hygiene detector. Two readers would drift - a page
 * the cleanup counts as derived from a source and the detector counts as
 * citing nothing is exactly the kind of disagreement neither could explain.
 *
 * Structural only: frontmatter list members and wikilink targets. No prose
 * is interpreted.
 */

import type { FrontmatterMap } from "../types.ts";
import { isLiveWikilinkSpan } from "./wikilink.ts";

/** Heading of the canonical provenance section (`provenance.ts`). */
const SOURCES_HEADING_RE = /^##\s+Sources\s*$/;

/** Any Markdown ATX heading: the line that ends a section. */
const ANY_HEADING_RE = /^#{1,6}\s/;

/** Every `[[ … ]]` wikilink on a line, captured whole. */
const WIKILINK_RE = /\[\[[^\]]+\]\]/g;

/** Line separator for LF and CRLF bodies alike. */
const LINE_SPLIT_RE = /\r?\n/;

/**
 * Opening or closing CommonMark code fence: up to three spaces of indent,
 * three or more backticks or tildes. Same rule as the block resolver
 * (`distill/block-resolve.ts`), copied rather than imported so this reader
 * does not depend on the distill module.
 */
const FENCE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;

/** True when `line` closes a fence opened by `opener`: same character, at least as long, nothing after it. */
function closesFence(line: string, opener: string): boolean {
  const m = FENCE_RE.exec(line);
  return (
    m !== null &&
    m[1]![0] === opener[0] &&
    m[1]!.length >= opener.length &&
    m[2]!.trim().length === 0
  );
}

/**
 * Which lines sit inside a fenced code block, fence lines included. Only a
 * closed fence is a fence: an opener with no closing line before the end of
 * the body is plain text, as are the lines after it, so caller text that
 * opens a fence and never closes it cannot hide the structure that follows.
 * Two linear passes at most: the single pass that pairs fences, then the
 * unmarking of the one span that can be left open.
 *
 * Exported because the write-time neutralizer's heading family must answer
 * "is this line fenced?" with the exact walk the section readers run - a
 * fourth private copy of the shape is one tilde away from disagreeing.
 */
export function fencedLineMask(lines: ReadonlyArray<string>): boolean[] {
  const mask = Array.from({ length: lines.length }, () => false);
  let fence: string | null = null;
  let openedAt = 0;
  for (const [i, line] of lines.entries()) {
    if (fence !== null) {
      mask[i] = true;
      if (closesFence(line, fence)) fence = null;
      continue;
    }
    const opened = FENCE_RE.exec(line);
    if (opened !== null) {
      fence = opened[1]!;
      openedAt = i;
      mask[i] = true;
    }
  }
  if (fence !== null) mask.fill(false, openedAt);
  return mask;
}

/** The string members of a frontmatter list field; anything else reads as empty. */
export function stringArrayField(meta: FrontmatterMap, key: string): ReadonlyArray<string> {
  const value = meta[key];
  if (!Array.isArray(value)) return [];
  return value.filter((item): item is string => typeof item === "string");
}

/** Strip a single enclosing `[[ … ]]` and any `|alias` / `#heading` tail. */
export function wikilinkTarget(raw: string): string {
  const m = /^\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]$/.exec(raw.trim());
  return m ? m[1]!.trim() : raw.trim();
}

/**
 * The wikilink targets listed under the page's LAST `## Sources` heading,
 * in order, read up to the next heading of any level. Targets go through
 * {@link wikilinkTarget}, the same rule the cleanup applies to a frontmatter
 * `source` link. A body without the section cites nothing here.
 *
 * Lines inside fenced code blocks are content, not structure: a heading or
 * link there neither opens, ends nor feeds the section. A fence that never
 * closes is not a fence (see {@link fencedLineMask}). The last section
 * wins because the writer renders the provenance section after everything
 * else on the page, so an earlier `## Sources` line (quoted or planted in
 * caller text) never stands in for it.
 */
export function sourcesSectionTargets(body: string): ReadonlyArray<string> {
  let targets: string[] = [];
  let inSection = false;
  const lines = body.split(LINE_SPLIT_RE);
  const fenced = fencedLineMask(lines);
  for (const [i, line] of lines.entries()) {
    if (fenced[i]) continue;
    if (SOURCES_HEADING_RE.test(line)) {
      inSection = true;
      targets = [];
      continue;
    }
    if (!inSection) continue;
    if (ANY_HEADING_RE.test(line)) {
      inSection = false;
      continue;
    }
    for (const match of line.matchAll(WIKILINK_RE)) {
      // A bracket behind an odd backslash run is escaped data and opens
      // or closes no link - the same rule `extractWikilinks` and the
      // neutralizer's detector apply - so an escaped span cites nothing.
      if (!isLiveWikilinkSpan(line, match.index!, match.index! + match[0].length)) continue;
      targets.push(wikilinkTarget(match[0]));
    }
  }
  return targets;
}