Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Relative markdown-link resolution — cross-dir links must resolve against the
* LINKING page's own directory, not the git root.
*
* The markdown-link regex strips the leading `../` run, so `extractPageLinks`
* historically resolved `[x](../concepts/x.md)` to the root-relative
* `concepts/x` regardless of where the linking page lived. For the canonical
* flat layout (entity dirs at the git root, pages one level down) that happens
* to be correct — `../` unwinds exactly to the root. But for content nested
* under a prefix — e.g. a source ingested with `--src-subpath wiki`, whose
* slugs are `wiki/concepts/x` — every cross-dir link missed: the target
* `concepts/x` doesn't exist, only `wiki/concepts/x` does, so `extract`/sync
* produced ZERO cross-dir edges (the graph showed only `contains` edges).
*
* Fix: preserve the `../` depth (`EntityRef.upLevels`) and resolve the target
* against the linking page's directory. Backward-compatible — a page one level
* below the root lands at the root, matching the old behavior; it only diverges
* (correctly) for deeper nesting. Every "wiki/..." case below FAILS on master.
*/
import { describe, test, expect } from 'bun:test';
import {
extractPageLinks,
extractEntityRefs,
LINK_EXTRACTOR_VERSION_TS,
type SlugResolver,
} from '../src/core/link-extraction.ts';
const nullResolver: SlugResolver = { resolve: async () => null };
describe('relative markdown-link resolution (nested / subtree-scoped content)', () => {
test('single ../ resolves against the linking page dir, keeping the prefix (was: dropped)', async () => {
const { candidates } = await extractPageLinks(
'wiki/sources/2026-04-03-memory',
'Builds on [Agent Memory](../concepts/agent-memory.md).',
{}, 'source', nullResolver, { skipFrontmatter: true },
);
const c = candidates.find(x => x.targetSlug === 'wiki/concepts/agent-memory');
expect(c).toBeDefined();
expect(c!.linkSource).toBe('markdown');
// The old root-relative miss must NOT be emitted.
expect(candidates.map(x => x.targetSlug)).not.toContain('concepts/agent-memory');
});
test('multiple ../ walk up multiple directory levels', async () => {
const { candidates } = await extractPageLinks(
'wiki/a/b/deep-page',
'See [X](../../concepts/x.md).',
{}, 'concept', nullResolver, { skipFrontmatter: true },
);
// dir = wiki/a/b ; up 2 -> wiki ; + concepts/x
expect(candidates.map(c => c.targetSlug)).toContain('wiki/concepts/x');
});
test('over-long ../ run clamps at the root', async () => {
const { candidates } = await extractPageLinks(
'wiki/foo',
'See [P](../../../people/alice.md).',
{}, 'concept', nullResolver, { skipFrontmatter: true },
);
expect(candidates.map(c => c.targetSlug)).toContain('people/alice');
});
test('absolute engine-slug refs (no ../) are unchanged', async () => {
const { candidates } = await extractPageLinks(
'wiki/sources/foo',
'See [C](concepts/agent-memory) for context.',
{}, 'source', nullResolver, { skipFrontmatter: true },
);
expect(candidates.map(c => c.targetSlug)).toContain('concepts/agent-memory');
expect(candidates.map(c => c.targetSlug)).not.toContain('wiki/sources/concepts/agent-memory');
});
test('extractEntityRefs records the ../ depth as upLevels', () => {
const refs = extractEntityRefs('[A](../../concepts/x.md) and [B](people/y)');
const a = refs.find(r => r.slug === 'concepts/x');
const b = refs.find(r => r.slug === 'people/y');
expect(a?.upLevels).toBe(2);
// Absolute refs carry no depth key (treated as 0).
expect(b?.upLevels ?? 0).toBe(0);
});
// ── regression pins: the canonical flat layout must NOT change ──────────
test('flat layout unchanged: one-level page + single ../ still resolves to root', async () => {
// notes/index is one level deep, so ../ops/... unwinds to the root exactly
// as before the fix (this is the #2576 case, kept green here).
const { candidates } = await extractPageLinks(
'notes/index', '[Pointer](../ops/services/pointer-agent.md) runs the fleet.',
{}, 'concept', nullResolver, { skipFrontmatter: true },
);
expect(candidates.map(c => c.targetSlug)).toContain('ops/services/pointer-agent');
});
test('LINK_EXTRACTOR_VERSION_TS was bumped so stamped pages re-extract', () => {
// Behavior changed, so previously-stamped pages must re-sweep to pick up
// the newly-resolvable cross-dir edges.
expect(LINK_EXTRACTOR_VERSION_TS > '2026-08-01T00:00:00Z').toBe(true);
});
});
// A parent-dir SIBLING link (`../y.md`, `./../y.md`) has no directory segment,
// so pass 1 never claimed it and pass 1b's relative arm only took `./`. The FS
// walker's join() resolved it, the DB path produced no candidate, and the
// serve-resident sweep's reconcile pruned the FS-created edge — the #4873
// class. Every "wiki/y" case below FAILS on the pre-fix regex.
describe('dot-relative sibling links without a directory segment (#4873 class)', () => {
test('`../y.md` resolves one level up from the linking page dir', async () => {
const { candidates } = await extractPageLinks(
'wiki/sources/foo', 'See [Y](../y.md).', {}, 'concept', nullResolver, { skipFrontmatter: true },
);
expect(candidates.map(c => c.targetSlug)).toEqual(['wiki/y']);
expect(candidates[0].linkSource).toBe('markdown');
});
test('`./../y.md` folds the `./` and climbs once', async () => {
const { candidates } = await extractPageLinks(
'wiki/sources/foo', 'See [Y](./../y.md).', {}, 'concept', nullResolver, { skipFrontmatter: true },
);
expect(candidates.map(c => c.targetSlug)).toEqual(['wiki/y']);
});
test('`../../y.md` climbs twice', async () => {
const { candidates } = await extractPageLinks(
'wiki/a/b/foo', 'See [Y](../../y.md).', {}, 'concept', nullResolver, { skipFrontmatter: true },
);
expect(candidates.map(c => c.targetSlug)).toEqual(['wiki/y']);
});
test('a `../` run that climbs above the root is dangling — no candidate', async () => {
const { candidates } = await extractPageLinks(
'wiki/foo', 'See [Y](../../y.md).', {}, 'concept', nullResolver, { skipFrontmatter: true },
);
expect(candidates).toEqual([]);
});
test('extractEntityRefs tags the sibling form sameDir with its `..` depth', () => {
const refs = extractEntityRefs('See [Y](./../y.md) and [Z](../../z.md).');
expect(refs.map(r => ({ slug: r.slug, sameDir: r.sameDir, upLevels: r.upLevels }))).toEqual([
{ slug: 'y', sameDir: true, upLevels: 1 },
{ slug: 'z', sameDir: true, upLevels: 2 },
]);
});
test('`../dir/x.md` stays a pass-1 ref — the widened sameDir arm does not double-emit', async () => {
const refs = extractEntityRefs('See [X](../concepts/x.md).');
expect(refs).toHaveLength(1);
expect(refs[0].sameDir).toBeUndefined();
const { candidates } = await extractPageLinks(
'wiki/sources/foo', 'See [X](../concepts/x.md).', {}, 'concept', nullResolver, { skipFrontmatter: true },
);
expect(candidates.map(c => c.targetSlug)).toEqual(['wiki/concepts/x']);
});
});