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
/**
* Unit tests for `src/core/vault-scope/index.ts`.
*
* Anchored in docs/plans/2026-05-19-vault-scope-design.md §5.
*/
import { afterEach, beforeEach, test, expect } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
inspectPath,
matchRules,
matchScope,
mayDescend,
resolveVaultScope,
walkVaultScope,
type VaultScope,
} from "../../src/core/vault-scope/index.ts";
// The cycle-safe leaf, imported directly: `pathCovers` is shared by modules
// that must not reach the resolver above it.
import {
classifyVaultPathRule,
DEFAULT_VAULT_IGNORE_PATHS,
normalisePathSegments,
pathCovers,
type VaultPathRule,
type VaultScopeRules,
} from "../../src/core/vault-scope/defaults.ts";
/** Build a `VaultScope` by hand, the way a resolver would. */
function scopeOf(ignore: ReadonlyArray<string>, include: ReadonlyArray<string> | null): VaultScope {
return {
ignorePaths: ignore,
includePaths: include,
rules: {
ignore: ignore.map(classifyVaultPathRule),
include: include === null ? null : include.map(classifyVaultPathRule),
},
source: "_brain.yaml",
declared: { ignore: true, include: include !== null },
};
}
test("DEFAULT_VAULT_IGNORE_PATHS contains the v0.10.9 baseline", () => {
expect([...DEFAULT_VAULT_IGNORE_PATHS]).toEqual([
".git",
"node_modules",
".open-second-brain",
".obsidian",
".trash",
".stversions",
"Brain/.snapshots",
]);
});
test("DEFAULT_VAULT_IGNORE_PATHS is frozen", () => {
expect(Object.isFrozen(DEFAULT_VAULT_IGNORE_PATHS)).toBe(true);
});
test("VaultPathRule kind union covers the two semantic cases", () => {
const a: VaultPathRule = { raw: ".git", kind: "name" };
const b: VaultPathRule = { raw: "Brain/.snapshots", kind: "path" };
expect(a.kind).toBe("name");
expect(b.kind).toBe("path");
});
// ----- classifyVaultPathRule normalisation ---------------------------------
test("classifyVaultPathRule strips trailing slash on path rules", () => {
const r = classifyVaultPathRule("Brain/.snapshots/");
expect(r.raw).toBe("Brain/.snapshots");
expect(r.kind).toBe("path");
});
test("classifyVaultPathRule strips leading ./ on path rules", () => {
const r = classifyVaultPathRule("./Brain/.snapshots");
expect(r.raw).toBe("Brain/.snapshots");
expect(r.kind).toBe("path");
});
test("classifyVaultPathRule collapses double slashes", () => {
const r = classifyVaultPathRule("Brain//.snapshots");
expect(r.raw).toBe("Brain/.snapshots");
expect(r.kind).toBe("path");
});
test("classifyVaultPathRule preserves bare names verbatim", () => {
const r = classifyVaultPathRule(".git");
expect(r.raw).toBe(".git");
expect(r.kind).toBe("name");
});
// ----- pathCovers -----------------------------------------------------------
//
// The shared segment-wise coverage predicate (unit B1). Five modules carried
// their own copy of this test before it had a home: the write-binding prefix
// matcher, the index-admission lane check, the note-walk root narrowing, the
// index root-coverage scan and the snapshot manifest exclusion. The cases
// below are the union of the edge cases those five disagreed on, so the
// deduplication cannot quietly move any of them.
test("pathCovers: a prefix covers itself", () => {
expect(pathCovers("Notes", "Notes")).toBe(true);
expect(pathCovers("Brain/state", "Brain/state")).toBe(true);
});
test("pathCovers: a prefix covers its children at any depth", () => {
expect(pathCovers("Notes", "Notes/idea.md")).toBe(true);
expect(pathCovers("Notes", "Notes/2026/05/idea.md")).toBe(true);
});
test("pathCovers: the comparison is segment-wise, not textual", () => {
// The whole reason this predicate exists: a character-prefix test would
// let `Notes` cover a folder the operator never named.
expect(pathCovers("Notes", "Notes-archive/idea.md")).toBe(false);
expect(pathCovers("Notes", "Notesy")).toBe(false);
expect(pathCovers("Brain/state", "Brain/stateful/x.md")).toBe(false);
expect(pathCovers("Brain/state", "Brain/state-notes.md")).toBe(false);
});
test("pathCovers: a parent of the prefix is not covered by it", () => {
expect(pathCovers("Notes/sub", "Notes")).toBe(false);
expect(pathCovers("Notes/sub", "")).toBe(false);
});
test("pathCovers: the empty prefix covers the vault root and nothing else", () => {
// A normalised target never starts with a separator, so the empty prefix
// is the root itself rather than an accidental match-everything.
expect(pathCovers("", "")).toBe(true);
expect(pathCovers("", ".")).toBe(true);
expect(pathCovers("", "Notes/idea.md")).toBe(false);
expect(pathCovers("", "/Notes/idea.md")).toBe(false);
});
test("pathCovers: a prefix that kept its trailing slash covers nothing", () => {
// Callers normalise their prefixes; one that did not is a declaration
// this grammar cannot honour, and reading it as `Notes` would be a guess.
expect(pathCovers("Notes/", "Notes/idea.md")).toBe(false);
expect(pathCovers("Notes/", "Notes/")).toBe(false);
expect(pathCovers("Notes/", "Notes")).toBe(false);
});
test("pathCovers: the target is normalised before comparison", () => {
expect(pathCovers("Notes", "./Notes/idea.md")).toBe(true);
expect(pathCovers("Notes", "Notes//idea.md")).toBe(true);
expect(pathCovers("Notes", "Notes/")).toBe(true);
expect(pathCovers("Notes", "/Notes/idea.md")).toBe(true);
expect(pathCovers("Notes", "Notes/./idea.md")).toBe(true);
});
test("pathCovers: a backslash is an ordinary filename character", () => {
// On POSIX `Projects\evil.md` is a one-segment name that lands at the
// vault ROOT, so reading structure into it would admit a path the
// declaration never covered.
expect(pathCovers("Projects", "Projects\\evil.md")).toBe(false);
expect(pathCovers("Projects", "Projects/evil.md")).toBe(true);
});
test("pathCovers: `..` is a segment like any other, never traversal", () => {
// The manifest walk uses this to drop `..`-anchored entries; the
// predicate must not resolve the segment away.
expect(pathCovers("..", "..")).toBe(true);
expect(pathCovers("..", "../outside.md")).toBe(true);
expect(pathCovers("..", "..notes.md")).toBe(false);
expect(pathCovers("Notes", "Notes/../evil.md")).toBe(true);
});
test("normalisePathSegments drops empty and `.` segments", () => {
expect(normalisePathSegments("Notes/idea.md")).toBe("Notes/idea.md");
expect(normalisePathSegments("./Notes//idea.md/")).toBe("Notes/idea.md");
expect(normalisePathSegments("/Notes/./idea.md")).toBe("Notes/idea.md");
});
test("normalisePathSegments returns the empty string for a path with no segments", () => {
for (const raw of ["", ".", "/", "///", "./", "/./"]) {
expect(normalisePathSegments(raw)).toBe("");
}
});
// ----- matchRules (polarity-free) -------------------------------------------
//
// The matcher answers ONE question - "does any of these rules cover this
// path" - and knows nothing about what a match means. Both polarities read
// the same grammar through it, which is why the include side needs no second
// implementation and cannot drift from the exclude side.
const rules: ReadonlyArray<VaultPathRule> = [
{ raw: ".git", kind: "name" },
{ raw: "node_modules", kind: "name" },
{ raw: "Brain/.snapshots", kind: "path" },
];
test("matchRules returns matched=false on a path no rule covers", () => {
const r = matchRules("Notes/idea.md", rules);
expect(r.matched).toBe(false);
expect(r.rule).toBeNull();
expect(r.matchedAt).toBeNull();
});
test("matchRules catches a bare-name rule at the root", () => {
const r = matchRules(".git/HEAD", rules);
expect(r.matched).toBe(true);
expect(r.rule?.raw).toBe(".git");
expect(r.matchedAt).toBe(".git");
});
test("matchRules catches a bare-name rule at any depth", () => {
const r = matchRules("deep/nested/.git/HEAD", rules);
expect(r.matched).toBe(true);
expect(r.rule?.raw).toBe(".git");
expect(r.matchedAt).toBe("deep/nested/.git");
});
test("matchRules catches a path rule by exact prefix", () => {
const r = matchRules("Brain/.snapshots/2026-05-19.tar.zst", rules);
expect(r.matched).toBe(true);
expect(r.rule?.raw).toBe("Brain/.snapshots");
expect(r.matchedAt).toBe("Brain/.snapshots");
});
test("matchRules does NOT match a path rule on a prefix collision", () => {
// "Brain/.snapshots-old" must NOT be eaten by "Brain/.snapshots".
expect(matchRules("Brain/.snapshots-old/x.md", rules).matched).toBe(false);
});
test("matchRules on an empty relPath matches nothing (vault root)", () => {
expect(matchRules("", rules).matched).toBe(false);
});
test("matchRules with no rules matches nothing", () => {
expect(matchRules(".git/HEAD", []).matched).toBe(false);
});
// ----- matchScope (the composed verdict) -----------------------------------
const excludeOnly: VaultScopeRules = { ignore: rules, include: null };
const withInclude: VaultScopeRules = {
ignore: rules,
include: [
{ raw: "Brain", kind: "name" },
{ raw: "Notes/Daily", kind: "path" },
],
};
test("matchScope: no allowlist declared means exclusion decides alone", () => {
expect(matchScope("Notes/idea.md", excludeOnly)).toEqual({
inScope: true,
reason: null,
rule: null,
matchedAt: null,
});
const refused = matchScope(".git/HEAD", excludeOnly);
expect(refused.inScope).toBe(false);
expect(refused.reason).toBe("ignored");
expect(refused.rule?.raw).toBe(".git");
expect(refused.matchedAt).toBe(".git");
});
test("matchScope: a declared allowlist admits only what it names", () => {
expect(matchScope("Brain/preferences/p.md", withInclude).inScope).toBe(true);
expect(matchScope("Notes/Daily/2026-05-19.md", withInclude).inScope).toBe(true);
const outside = matchScope("Notes/idea.md", withInclude);
expect(outside.inScope).toBe(false);
expect(outside.reason).toBe("not-included");
// Nothing REFUSED it by name: there is no rule to blame, only the
// absence of one that admits.
expect(outside.rule).toBeNull();
});
test("matchScope: the allowlist narrows segment-wise, never textually", () => {
expect(matchScope("Notes/Daily-archive/x.md", withInclude).inScope).toBe(false);
expect(matchScope("Brainstorm/x.md", withInclude).inScope).toBe(false);
});
test("matchScope: exclusion still wins inside an included root", () => {
const both = matchScope("Brain/.snapshots/2026-05-19.tar.zst", withInclude);
expect(both.inScope).toBe(false);
// The refusal names the polarity an operator can act on: the entry
// they wrote under ignore_paths, not the allowlist that would have
// admitted the path.
expect(both.reason).toBe("ignored");
expect(both.rule?.raw).toBe("Brain/.snapshots");
});
test("matchScope: the vault root is in scope under an allowlist", () => {
// The root is not "a path outside every include root" - it is the
// container of all of them, and a walker that refused it would walk
// nothing at all.
expect(matchScope("", withInclude).inScope).toBe(true);
expect(matchScope("", excludeOnly).inScope).toBe(true);
});
test("matchScope: an allowlist entry matches at any depth, like the exclude grammar", () => {
// One grammar, both polarities: a slashless entry is a NAME rule. The
// depth-agnostic reading is inherited deliberately rather than given a
// second syntax nobody asked for.
expect(matchScope("projects/Brain/notes.md", withInclude).inScope).toBe(true);
});
// ----- mayDescend ----------------------------------------------------------
const pathInclude: VaultScopeRules = {
ignore: rules,
include: [{ raw: "Notes/Daily", kind: "path" }],
};
test("mayDescend: the allowlist narrows FILES, so a parent of a root is descended", () => {
// `Notes` holds no included file itself, but `Notes/Daily` lives under
// it. A walker that stopped here would never reach the declared root.
expect(mayDescend("Notes", pathInclude)).toBe(true);
expect(mayDescend("Notes/Daily", pathInclude)).toBe(true);
expect(mayDescend("Notes/Daily/2026", pathInclude)).toBe(true);
});
test("mayDescend: a directory that can hold no included file is not descended", () => {
expect(mayDescend("Archive", pathInclude)).toBe(false);
expect(mayDescend("Notes/Weekly", pathInclude)).toBe(false);
});
test("mayDescend: an excluded directory is never descended, either polarity", () => {
expect(mayDescend("Brain/.snapshots", withInclude)).toBe(false);
expect(mayDescend("node_modules", excludeOnly)).toBe(false);
});
test("mayDescend: without an allowlist only exclusion stops descent", () => {
expect(mayDescend("Archive", excludeOnly)).toBe(true);
expect(mayDescend("", excludeOnly)).toBe(true);
});
test("mayDescend: the vault root is always descended", () => {
expect(mayDescend("", pathInclude)).toBe(true);
});
test("mayDescend: a name-kind include root can appear at any depth, so descent continues", () => {
// `Brain` is a name rule: `projects/Brain/` is included, so no
// directory can be ruled out on the way there.
expect(mayDescend("projects", withInclude)).toBe(true);
expect(mayDescend("", withInclude)).toBe(true);
});
// ----- resolveVaultScope ---------------------------------------------------
let scopeVault: string;
beforeEach(() => {
scopeVault = mkdtempSync(join(tmpdir(), "osb-scope-"));
mkdirSync(join(scopeVault, "Brain"), { recursive: true });
});
afterEach(() => {
rmSync(scopeVault, { recursive: true, force: true });
});
function writeBrain(body: string): void {
writeFileSync(join(scopeVault, "Brain", "_brain.yaml"), body, "utf8");
}
test("resolveVaultScope: defaults when _brain.yaml is absent", () => {
const scope = resolveVaultScope(scopeVault);
expect(scope.source).toBe("defaults");
expect(scope.ignorePaths).toContain(".obsidian");
expect(scope.ignorePaths).toContain("Brain/.snapshots");
expect(scope.rules.ignore.find((r) => r.raw === "Brain/.snapshots")?.kind).toBe("path");
expect(scope.rules.ignore.find((r) => r.raw === ".obsidian")?.kind).toBe("name");
});
test("resolveVaultScope: an undeclared allowlist is null, never an empty array", () => {
// The distinction is the whole feature: `null` is "no allowlist", and
// an empty array would read as "admit nothing".
expect(resolveVaultScope(scopeVault).includePaths).toBeNull();
expect(resolveVaultScope(scopeVault).rules.include).toBeNull();
});
test("resolveVaultScope: reads vault.ignore_paths when present", () => {
writeBrain(`schema_version: 1
vault:
ignore_paths:
- .git
- my-cache
`);
const scope = resolveVaultScope(scopeVault);
expect(scope.source).toBe("_brain.yaml");
expect(scope.ignorePaths).toEqual([".git", "my-cache"]);
expect(scope.rules.ignore.map((r) => r.kind)).toEqual(["name", "name"]);
expect(scope.includePaths).toBeNull();
});
test("resolveVaultScope: reads vault.include_paths when present", () => {
writeBrain(`schema_version: 1
vault:
include_paths:
- Brain
- Notes/Daily
`);
const scope = resolveVaultScope(scopeVault);
expect(scope.source).toBe("_brain.yaml");
expect(scope.includePaths).toEqual(["Brain", "Notes/Daily"]);
expect(scope.rules.include?.map((r) => r.kind)).toEqual(["name", "path"]);
// An allowlist alone does not disable the built-in exclusions: the two
// keys are independent, and a vault that declared only include_paths
// still skips `.git` and friends.
expect(scope.ignorePaths).toEqual([...DEFAULT_VAULT_IGNORE_PATHS]);
});
test("resolveVaultScope: explicit empty list excludes nothing", () => {
writeBrain(`schema_version: 1
vault:
ignore_paths:
`);
const scope = resolveVaultScope(scopeVault);
expect(scope.source).toBe("_brain.yaml");
expect(scope.ignorePaths).toEqual([]);
expect(scope.rules.ignore).toEqual([]);
});
test("resolveVaultScope: absent vault block falls back to defaults", () => {
writeBrain(`schema_version: 1\n`);
const scope = resolveVaultScope(scopeVault);
expect(scope.source).toBe("defaults");
});
test("resolveVaultScope: vault block without ignore_paths falls back to defaults", () => {
writeBrain(`schema_version: 1
vault:
some_future_key: 42
`);
const scope = resolveVaultScope(scopeVault);
expect(scope.source).toBe("defaults");
});
test("resolveVaultScope: invalid _brain.yaml fails closed instead of defaulting", () => {
writeBrain("schema_version: 1\n nested_without_parent: 1\n");
expect(() => resolveVaultScope(scopeVault)).toThrow(/unexpected indentation/);
});
test("resolveVaultScope: returns an immutable object", () => {
const scope = resolveVaultScope(scopeVault);
expect(Object.isFrozen(scope)).toBe(true);
expect(Object.isFrozen(scope.rules)).toBe(true);
expect(Object.isFrozen(scope.rules.ignore)).toBe(true);
expect(Object.isFrozen(scope.ignorePaths)).toBe(true);
});
// ----- walkVaultScope ------------------------------------------------------
test("walkVaultScope: counts included files+dirs and reports excluded subtree once", () => {
mkdirSync(join(scopeVault, "Notes"), { recursive: true });
writeFileSync(join(scopeVault, "Notes", "a.md"), "x");
writeFileSync(join(scopeVault, "Notes", "b.md"), "x");
mkdirSync(join(scopeVault, ".obsidian", "plugins", "foo"), { recursive: true });
writeFileSync(join(scopeVault, ".obsidian", "app.json"), "{}");
writeFileSync(join(scopeVault, ".obsidian", "plugins", "foo", "note.md"), "x");
const scope = resolveVaultScope(scopeVault);
const walk = walkVaultScope(scopeVault, scope);
expect(walk.includedFiles).toBeGreaterThanOrEqual(2);
const obsidianHit = walk.excludedDirs.find((d) => d.relPath === ".obsidian");
expect(obsidianHit).toBeTruthy();
expect(obsidianHit?.rule?.raw).toBe(".obsidian");
expect(obsidianHit?.reason).toBe("ignored");
// Subtree descendants must NOT be reported separately.
expect(walk.excludedDirs.filter((d) => d.relPath.startsWith(".obsidian/"))).toHaveLength(0);
});
test("walkVaultScope: file-level rule excludes a single file but not the parent", () => {
writeFileSync(join(scopeVault, "note.md"), "x");
writeFileSync(join(scopeVault, "secret.md"), "x");
const walk = walkVaultScope(scopeVault, scopeOf(["secret.md"], null));
expect(walk.excludedFiles.map((f) => f.relPath)).toContain("secret.md");
expect(walk.includedFiles).toBe(1);
});
test("walkVaultScope: an allowlist walks only the named roots, minus exclusions", () => {
writeFileSync(join(scopeVault, "top.md"), "x");
mkdirSync(join(scopeVault, "Notes"), { recursive: true });
writeFileSync(join(scopeVault, "Notes", "idea.md"), "x");
mkdirSync(join(scopeVault, "Notes", "private"), { recursive: true });
writeFileSync(join(scopeVault, "Notes", "private", "diary.md"), "x");
mkdirSync(join(scopeVault, "Archive"), { recursive: true });
writeFileSync(join(scopeVault, "Archive", "old.md"), "x");
const walk = walkVaultScope(scopeVault, scopeOf(["Notes/private"], ["Notes"]));
// `Notes/idea.md` only: `Archive/old.md` and `top.md` are outside the
// allowlist, `Notes/private` is excluded inside it.
expect(walk.includedFiles).toBe(1);
expect(walk.excludedFiles.map((f) => f.relPath).toSorted()).toEqual(["Archive/old.md", "top.md"]);
expect(walk.excludedFiles.find((f) => f.relPath === "top.md")?.reason).toBe("not-included");
expect(walk.excludedDirs.find((d) => d.relPath === "Notes/private")?.reason).toBe("ignored");
// `Archive` itself is DESCENDED, not pruned: `Notes` is a bare name,
// which matches at any depth, so a nested `Archive/Notes/` would be in
// scope and no directory can be ruled out on the way to one.
expect(walk.excludedDirs.find((d) => d.relPath === "Archive")).toBeUndefined();
});
test("walkVaultScope: a path-kind include root prunes whole directories", () => {
writeFileSync(join(scopeVault, "top.md"), "x");
mkdirSync(join(scopeVault, "Notes", "Daily"), { recursive: true });
writeFileSync(join(scopeVault, "Notes", "Daily", "2026-05-19.md"), "x");
mkdirSync(join(scopeVault, "Archive"), { recursive: true });
writeFileSync(join(scopeVault, "Archive", "old.md"), "x");
const walk = walkVaultScope(scopeVault, scopeOf([], ["Notes/Daily"]));
expect(walk.includedFiles).toBe(1);
// Named a path, so the root is exactly one place: `Archive` cannot
// hold an included file and is refused whole, while `Notes` is
// descended because the declared root lives under it.
expect(walk.excludedDirs.find((d) => d.relPath === "Archive")?.reason).toBe("not-included");
expect(walk.excludedDirs.find((d) => d.relPath === "Notes")).toBeUndefined();
});
test("walkVaultScope: index-admission refusals are reported, not counted as included", () => {
// The adjacent defect this release fixes: the search walker refuses the
// exact-state lane and `o2b vault status` did not, so the two disagreed
// about the same vault and status over-reported index coverage.
mkdirSync(join(scopeVault, "Brain", "state"), { recursive: true });
writeFileSync(join(scopeVault, "Brain", "state", "live.md"), "x");
const walk = walkVaultScope(scopeVault, resolveVaultScope(scopeVault));
expect(walk.includedFiles).toBe(0);
const lane = walk.excludedDirs.find((d) => d.relPath === "Brain/state");
expect(lane?.reason).toBe("not-admitted");
expect(lane?.rule).toBeNull();
});
test("walkVaultScope: empty vault yields zero counts", () => {
rmSync(join(scopeVault, "Brain"), { recursive: true, force: true });
const scope = resolveVaultScope(scopeVault);
const walk = walkVaultScope(scopeVault, scope);
expect(walk.includedFiles).toBe(0);
expect(walk.excludedDirs).toEqual([]);
});
test("walkVaultScope: symlinked file escaping vault is not counted (symmetric with search walker)", () => {
const outside = mkdtempSync(join(tmpdir(), "osb-scope-outside-"));
try {
writeFileSync(join(outside, "leak.md"), "secret");
writeFileSync(join(scopeVault, "real.md"), "x");
symlinkSync(join(outside, "leak.md"), join(scopeVault, "evil.md"));
const scope = resolveVaultScope(scopeVault);
const walk = walkVaultScope(scopeVault, scope);
// `real.md` plus the Brain config file should count; `evil.md`
// resolves outside the vault and must be dropped before being
// counted.
expect(walk.includedFiles).toBeLessThanOrEqual(2);
expect(walk.excludedFiles.map((f) => f.relPath)).not.toContain("evil.md");
} finally {
rmSync(outside, { recursive: true, force: true });
}
});
// ----- inspectPath ---------------------------------------------------------
test("inspectPath: included path that exists on disk", () => {
writeFileSync(join(scopeVault, "idea.md"), "x");
const scope = resolveVaultScope(scopeVault);
const r = inspectPath("idea.md", scope, scopeVault);
expect(r.excluded).toBe(false);
expect(r.rule).toBeNull();
expect(r.matchedAt).toBeNull();
expect(r.relPath).toBe("idea.md");
expect(r.source).toBe("defaults");
expect(r.existsOnDisk).toBe(true);
});
test("inspectPath: included path that does NOT exist on disk reports existsOnDisk=false", () => {
const scope = resolveVaultScope(scopeVault);
const r = inspectPath("Notes/hypothetical.md", scope, scopeVault);
expect(r.excluded).toBe(false);
expect(r.existsOnDisk).toBe(false);
});
test("inspectPath: a path outside the allowlist is excluded, naming that polarity", () => {
const r = inspectPath("Archive/old.md", scopeOf([], ["Notes"]), scopeVault);
expect(r.excluded).toBe(true);
expect(r.reason).toBe("not-included");
expect(r.rule).toBeNull();
});
test("inspectPath: the vault root is in scope under an allowlist", () => {
const r = inspectPath("", scopeOf([], ["Notes"]), scopeVault);
expect(r.excluded).toBe(false);
expect(r.reason).toBeNull();
});
test("inspectPath: a lane-owned path is in scope but not admitted to the index", () => {
// Two independent verdicts. Vault scope admits `Brain/state`; the
// index refuses it. Collapsing them would tell an operator their
// exact-state file is searchable.
const scope = resolveVaultScope(scopeVault);
const r = inspectPath("Brain/state/live.md", scope, scopeVault);
expect(r.excluded).toBe(false);
expect(r.indexAdmitted).toBe(false);
expect(r.admissionReason).toBe("exact-state-lane");
});
test("inspectPath: an ordinary path is admitted to the index", () => {
const scope = resolveVaultScope(scopeVault);
const r = inspectPath("Notes/idea.md", scope, scopeVault);
expect(r.indexAdmitted).toBe(true);
expect(r.admissionReason).toBeNull();
});
test("inspectPath: excluded by name rule reports the matched directory", () => {
const scope = resolveVaultScope(scopeVault);
const r = inspectPath(".obsidian/plugins/foo/note.md", scope, scopeVault);
expect(r.excluded).toBe(true);
expect(r.reason).toBe("ignored");
expect(r.rule?.raw).toBe(".obsidian");
expect(r.rule?.kind).toBe("name");
expect(r.matchedAt).toBe(".obsidian");
// The file does not exist on disk; the rule decision is still meaningful.
expect(r.existsOnDisk).toBe(false);
});
test("inspectPath: excluded by path rule on exact match", () => {
const scope = resolveVaultScope(scopeVault);
const r = inspectPath("Brain/.snapshots/2026-05-19.tar.zst", scope, scopeVault);
expect(r.excluded).toBe(true);
expect(r.rule?.raw).toBe("Brain/.snapshots");
expect(r.rule?.kind).toBe("path");
});
test("inspectPath: strips leading ./ and surrounding slashes", () => {
const scope = resolveVaultScope(scopeVault);
const r = inspectPath("/./Notes/idea.md/", scope, scopeVault);
expect(r.relPath).toBe("Notes/idea.md");
expect(r.excluded).toBe(false);
});
test("inspectPath: throws on .. traversal", () => {
const scope = resolveVaultScope(scopeVault);
expect(() => inspectPath("../outside", scope, scopeVault)).toThrow(/traverse/);
});
// ----- absent include_paths: today's behaviour, byte for byte ---------------
//
// The most important test in this unit. Every literal below was RECORDED
// from the implementation as it stood before `vault.include_paths` existed
// (v1.45.1, one fixture vault, three walkers), so the assertion is a
// measurement rather than a restatement of the new code. A vault that never
// mentions the key must be walked exactly as it was.
//
// The one deliberate difference is stated in its own test rather than
// folded in here: `Brain/state` is now refused by the index-admission
// filter that `walkVaultScope` previously omitted.
const FIXTURE_FILES: ReadonlyArray<string> = [
"Brain/_brain.yaml",
"Brain/preferences/pref-a.md",
"Brain/.snapshots/2026-01-01.txt",
"Notes/idea.md",
"Notes/deep/nested.md",
"Notes-archive/old.md",
"Journal/2026/entry.md",
"top.md",
".obsidian/app.json",
".git/HEAD",
"node_modules/pkg/readme.md",
];
function buildFixtureVault(root: string): void {
for (const rel of FIXTURE_FILES) {
const abs = join(root, rel);
mkdirSync(join(abs, ".."), { recursive: true });
writeFileSync(abs, rel === "Brain/_brain.yaml" ? "schema_version: 1\n" : "x");
}
}
test("absent include_paths: the fixture vault walks exactly as it did before the key existed", () => {
buildFixtureVault(scopeVault);
const scope = resolveVaultScope(scopeVault);
const walk = walkVaultScope(scopeVault, scope);
expect(scope.source).toBe("defaults");
expect(scope.includePaths).toBeNull();
expect(walk.includedFiles).toBe(7);
expect(walk.includedDirs).toBe(7);
expect(walk.excludedDirs.map((d) => [d.relPath, d.rule?.raw ?? null])).toEqual([
[".git", ".git"],
[".obsidian", ".obsidian"],
["Brain/.snapshots", "Brain/.snapshots"],
["node_modules", "node_modules"],
]);
expect(walk.excludedFiles).toEqual([]);
});