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
8.8 KB
Raw Blame
/**
 * Unit tests for `buildAliasIndex` and `listAliasClaims`. The helper walks Brain
 * preferences + retired artifacts, reads their frontmatter
 * `aliases:` arrays, and returns a frozen Map keyed by NFC-normalised
 * lowercase alias text, valued at the canonical artifact id.
 *
 * Collisions (two artifacts claiming the same alias) resolve
 * first-wins by sorted canonical id - deterministic without an
 * extra timestamp lookup. Empty / non-array aliases are skipped.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import {
  buildAliasIndex,
  listAliasClaims,
} from "../../../../src/core/brain/link-graph/alias-index.ts";
import { bootstrapBrain } from "../../../../src/core/brain/init.ts";

let vault: string;

function writePref(slug: string, body: string): void {
  writeFileSync(join(vault, "Brain", "preferences", `${slug}.md`), `${body}\n`);
}

function writeRetired(slug: string, body: string): void {
  writeFileSync(join(vault, "Brain", "retired", `${slug}.md`), `${body}\n`);
}

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-alias-index-"));
  bootstrapBrain(vault);
  mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
  mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

describe("buildAliasIndex - happy path", () => {
  test("registers single alias", () => {
    writePref(
      "pref-second-order",
      [
        "---",
        "kind: preference",
        "topic: second-order",
        "status: confirmed",
        "principle: thinking ahead",
        "aliases: [downstream]",
        "---",
        "",
        "Body.",
      ].join("\n"),
    );
    const idx = buildAliasIndex(vault);
    expect(idx.get("downstream")).toBe("pref-second-order");
  });

  test("registers multiple aliases per artifact", () => {
    writePref(
      "pref-second-order",
      [
        "---",
        "kind: preference",
        "topic: second-order",
        "status: confirmed",
        "principle: thinking ahead",
        "aliases: [downstream, knock-on, second-order-effects]",
        "---",
      ].join("\n"),
    );
    const idx = buildAliasIndex(vault);
    expect(idx.get("downstream")).toBe("pref-second-order");
    expect(idx.get("knock-on")).toBe("pref-second-order");
    expect(idx.get("second-order-effects")).toBe("pref-second-order");
  });

  test("collects aliases from retired artifacts", () => {
    writeRetired(
      "ret-old",
      [
        "---",
        "kind: retired",
        "topic: old",
        "principle: superseded",
        "aliases: [legacy-rule]",
        "---",
      ].join("\n"),
    );
    const idx = buildAliasIndex(vault);
    expect(idx.get("legacy-rule")).toBe("ret-old");
  });
});

describe("buildAliasIndex - normalisation", () => {
  test("case-insensitive lookup", () => {
    writePref(
      "pref-foo",
      [
        "---",
        "kind: preference",
        "topic: foo",
        "status: confirmed",
        "principle: bar",
        "aliases: [Downstream]",
        "---",
      ].join("\n"),
    );
    const idx = buildAliasIndex(vault);
    expect(idx.get("downstream")).toBe("pref-foo");
    // Original casing also accessible via the lower-case key only;
    // callers normalise the lookup key themselves.
    expect(idx.get("Downstream")).toBeUndefined();
  });

  test("NFC normalisation collapses pre-composed and decomposed forms", () => {
    // "café" composed (U+00E9) vs decomposed (U+0065 U+0301).
    const composed = "café";
    const decomposed = "café";
    writePref(
      "pref-cafe",
      [
        "---",
        "kind: preference",
        "topic: cafe",
        "status: confirmed",
        "principle: x",
        `aliases: [${decomposed}]`,
        "---",
      ].join("\n"),
    );
    const idx = buildAliasIndex(vault);
    // Lookup with composed form should hit (NFC normalises both
    // sides).
    expect(idx.get(composed.normalize("NFC").toLowerCase())).toBe("pref-cafe");
  });

  test("trims whitespace from alias entries", () => {
    writePref(
      "pref-trim",
      [
        "---",
        "kind: preference",
        "topic: trim",
        "status: confirmed",
        "principle: x",
        "aliases: [ spaced , another  ]",
        "---",
      ].join("\n"),
    );
    const idx = buildAliasIndex(vault);
    expect(idx.get("spaced")).toBe("pref-trim");
    expect(idx.get("another")).toBe("pref-trim");
  });

  test("skips empty alias strings", () => {
    writePref(
      "pref-empty",
      [
        "---",
        "kind: preference",
        "topic: empty",
        "status: confirmed",
        "principle: x",
        "aliases: [valid, '', ok]",
        "---",
      ].join("\n"),
    );
    const idx = buildAliasIndex(vault);
    expect(idx.get("valid")).toBe("pref-empty");
    expect(idx.get("ok")).toBe("pref-empty");
    expect(idx.get("")).toBeUndefined();
  });
});

describe("buildAliasIndex - collision handling", () => {
  test("first-wins by sorted canonical id", () => {
    writePref(
      "pref-aaa",
      [
        "---",
        "kind: preference",
        "topic: a",
        "status: confirmed",
        "principle: x",
        "aliases: [shared]",
        "---",
      ].join("\n"),
    );
    writePref(
      "pref-bbb",
      [
        "---",
        "kind: preference",
        "topic: b",
        "status: confirmed",
        "principle: x",
        "aliases: [shared]",
        "---",
      ].join("\n"),
    );
    const idx = buildAliasIndex(vault);
    expect(idx.get("shared")).toBe("pref-aaa");
  });

  test("alias that shadows an existing canonical id is silently dropped (no hijack)", () => {
    // pref-foo declares alias "pref-bar"; pref-bar exists on disk.
    // Without the on-disk-collision guard, [[pref-bar]] backlinks
    // would re-route to pref-foo and the real pref-bar would lose
    // every inbound reference. The alias-index drops the offending
    // entry so the canonical artifact keeps owning its id.
    writePref(
      "pref-foo",
      [
        "---",
        "kind: preference",
        "topic: foo",
        "status: confirmed",
        "principle: x",
        "aliases: [pref-bar]",
        "---",
      ].join("\n"),
    );
    writePref(
      "pref-bar",
      ["---", "kind: preference", "topic: bar", "status: confirmed", "principle: y", "---"].join(
        "\n",
      ),
    );
    const idx = buildAliasIndex(vault);
    expect(idx.get("pref-bar")).toBeUndefined();
  });
});

describe("listAliasClaims", () => {
  function claimant(topic: string, aliases: string): string {
    return [
      "---",
      "kind: preference",
      `topic: ${topic}`,
      "status: confirmed",
      "principle: x",
      `aliases: ${aliases}`,
      "---",
    ].join("\n");
  }

  test("keeps every claimant of a colliding alias in the index's order, each once", () => {
    writePref("pref-bbb", claimant("b", "[shared, Shared]"));
    writePref("pref-aaa", claimant("a", "[shared]"));
    writeRetired("ret-ccc", claimant("c", "[shared]"));

    expect(listAliasClaims(vault).get("shared")).toEqual(["pref-aaa", "pref-bbb", "ret-ccc"]);
    expect(buildAliasIndex(vault).get("shared")).toBe("pref-aaa");
  });

  test("an alias shadowing an existing canonical id has no claimant", () => {
    writePref("pref-foo", claimant("foo", "[pref-bar]"));
    writePref("pref-bar", claimant("bar", "[]"));

    expect(listAliasClaims(vault).has("pref-bar")).toBe(false);
  });
});

describe("buildAliasIndex - degenerate inputs", () => {
  test("empty vault returns empty frozen map", () => {
    const idx = buildAliasIndex(vault);
    expect(idx.size).toBe(0);
    expect(Object.isFrozen(idx)).toBe(true);
  });

  test("artifact without aliases is skipped", () => {
    writePref(
      "pref-noalias",
      ["---", "kind: preference", "topic: x", "status: confirmed", "principle: y", "---"].join(
        "\n",
      ),
    );
    const idx = buildAliasIndex(vault);
    expect(idx.size).toBe(0);
  });

  test("non-array aliases value is skipped without throwing", () => {
    writePref(
      "pref-scalar",
      [
        "---",
        "kind: preference",
        "topic: x",
        "status: confirmed",
        "principle: y",
        "aliases: not-an-array",
        "---",
      ].join("\n"),
    );
    const idx = buildAliasIndex(vault);
    expect(idx.size).toBe(0);
  });

  test("malformed frontmatter row is silently skipped", () => {
    writePref("pref-bad", ["no frontmatter here", "just body content"].join("\n"));
    writePref(
      "pref-good",
      [
        "---",
        "kind: preference",
        "topic: g",
        "status: confirmed",
        "principle: y",
        "aliases: [ok]",
        "---",
      ].join("\n"),
    );
    const idx = buildAliasIndex(vault);
    expect(idx.get("ok")).toBe("pref-good");
  });
});