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
18.6 KB
Raw Blame
/**
 * Deterministic architecture docs generator
 * (Project History Suite, t_929da8a2).
 */

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

import { ArchWriteError, generateArchDocs } from "../../../src/core/brain/architect/generate.ts";
import { ARCHITECT_STAGE, scanProject } from "../../../src/core/brain/architect/scan.ts";
import { PROGRESS_KIND } from "../../../src/core/brain/progress.ts";
import { RegionError } from "../../../src/core/brain/regions.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";
import { CLI_SPAWN_BUDGET_MS } from "../../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

let tmp: string;
let project: string;
let vault: string;

function seed(relPath: string, content = "// x\n"): void {
  const abs = join(project, relPath);
  mkdirSync(join(abs, ".."), { recursive: true });
  writeFileSync(abs, content);
}

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-architect-"));
  project = join(tmp, "demo-app");
  mkdirSync(project, { recursive: true });
  vault = join(tmp, "vault");
  mkdirSync(join(vault, "Brain"), { recursive: true });

  writeFileSync(
    join(project, "package.json"),
    JSON.stringify({
      name: "demo-app",
      version: "1.2.3",
      description: "Fixture project",
      main: "src/index.ts",
      dependencies: { "left-pad": "^1.0.0" },
    }),
  );
  seed("src/index.ts");
  seed("src/core/engine.ts");
  seed("src/core/util.ts");
  seed("src/cli/main.ts");
  seed("tests/engine.test.ts");
  seed("README.md", "# Demo App\n");
  // Noise that must be ignored:
  seed("node_modules/dep/index.js");
  seed(".git/HEAD", "ref: refs/heads/main\n");
});

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

test("scanProject produces deterministic structural facts", () => {
  const facts = scanProject(project);
  expect(facts.name).toBe("demo-app");
  expect(facts.manifest!.version).toBe("1.2.3");
  expect(facts.manifest!.dependencies).toEqual(["left-pad"]);
  expect(facts.modules.map((m) => m.name)).toEqual(["cli", "core"]);
  expect(facts.modules.find((m) => m.name === "core")!.files).toBe(2);
  expect(facts.entryPoints).toContain("src/index.ts");
  expect(facts.testLayout).toBe("tests");
  // node_modules and .git are invisible.
  expect(facts.languages[".js"]).toBeUndefined();
  expect(facts.languages[".ts"]).toBe(5);
  // Determinism: scanning twice gives deep-equal results.
  expect(scanProject(project)).toEqual(facts);
});

test("a dot-directory's contents never reach the facts", () => {
  const before = scanProject(project);
  // Tooling state, not architecture: agent worktrees, CI definitions,
  // caches. On this repository that rule is 88% of every file visited.
  seed(".claude/worktrees/copy/src/index.ts");
  seed(".github/workflows/ci.yml");
  seed(".cache-of-things/blob.ts");
  // A FILE whose name collides with a skipped directory is still a file.
  seed("src/core/build");

  const facts = scanProject(project);
  expect(facts.languages[".yml"]).toBeUndefined();
  expect(facts.totalFiles).toBe(before.totalFiles + 1);
  expect(facts.modules.map((m) => m.name)).toEqual(["cli", "core"]);
  expect(facts.modules.find((m) => m.name === "core")!.topFiles).toContain("build");
});

test("the traversal reads each directory exactly once", () => {
  seed("src/core/deep/nested/util.ts");
  // Every directory the scan is allowed to enter, listed rather than
  // computed: `node_modules/dep` and `.git` are skipped, so reading
  // either of them would show up here as an extra count.
  const walkable = [
    "",
    "src",
    "src/cli",
    "src/core",
    "src/core/deep",
    "src/core/deep/nested",
    "tests",
  ];

  // The progress counter is the instrument: it advances once per
  // directory read, so a subtree walked a second time doubles its count.
  let reads = 0;
  scanProject(project, {
    onProgress: (event) => {
      if (event.kind === PROGRESS_KIND.advanced) reads += 1;
    },
  });

  expect(reads).toBe(walkable.length);
});

test("scanProject skips symlinks instead of following them", () => {
  // A symlink cycle inside the tree must not hang or overflow the scan,
  // and symlinked content outside the module must not be counted.
  symlinkSync(project, join(project, "src", "core", "loop"), "dir");
  const facts = scanProject(project);
  expect(facts.modules.find((m) => m.name === "core")!.files).toBe(2);
});

test("scanProject degrades to a single root module on flat layouts", () => {
  const flat = join(tmp, "flat-proj");
  mkdirSync(flat, { recursive: true });
  writeFileSync(join(flat, "main.py"), "print('x')\n");
  const facts = scanProject(flat);
  expect(facts.modules.map((m) => m.name)).toEqual(["root"]);
  expect(facts.manifest).toBeNull();
  expect(facts.languages[".py"]).toBe(1);
});

test("first generation creates overview + per-module notes under Brain/projects/arch", () => {
  const res = generateArchDocs(vault, project);
  expect(res.created).toBeGreaterThanOrEqual(3); // overview + 2 modules
  expect(res.updated).toBe(0);
  const overview = readFileSync(res.overviewPath, "utf8");
  expect(overview).toContain("kind: arch-overview");
  expect(overview).toContain("<!-- o2b:begin summary -->");
  expect(overview).toContain("demo-app");
  expect(overview).toContain("core");
  const moduleNote = readFileSync(
    res.modulePaths.find((p) => p.endsWith("core.md"))!,
    "utf8",
  );
  expect(moduleNote).toContain("kind: arch-module");
  expect(moduleNote).toContain("engine.ts");
});

test("regeneration preserves operator edits outside regions and refreshes facts inside", () => {
  const first = generateArchDocs(vault, project);
  const operatorNote = "\nOperator: core owns the scheduling invariants.\n";
  writeFileSync(first.overviewPath, readFileSync(first.overviewPath, "utf8") + operatorNote);

  seed("src/api/server.ts"); // new module appears
  const second = generateArchDocs(vault, project);
  const overview = readFileSync(second.overviewPath, "utf8");
  expect(overview).toContain("Operator: core owns the scheduling invariants.");
  expect(overview).toContain("api");
  expect(second.updated).toBeGreaterThanOrEqual(1);
});

/**
 * The renderer must not consult the host's collation.
 *
 * Two children generate the same fixture and their overview bytes are
 * compared. `LC_ALL` alone cannot prove this: measured on this runtime,
 * `new Intl.Collator().resolvedOptions().locale` stays `en-US` whatever
 * `LC_ALL` says, so an env-only test would pass against a collator-based
 * tie-break too. The second child therefore installs a reversed collation
 * on `String.prototype.localeCompare` before importing the generator -
 * that is the collation difference the environment could not supply, and
 * it is exactly what a differently-collating host would do to a
 * `localeCompare` tie-break.
 */
const COLLATION_CHILD = `
if (process.env["O2B_TEST_REVERSE_COLLATION"] === "1") {
  Object.defineProperty(String.prototype, "localeCompare", {
    value(other) { return other < this ? -1 : other > this ? 1 : 0; },
    configurable: true,
    writable: true,
  });
}
const { readFileSync } = await import("node:fs");
const { generateArchDocs } = await import(process.env["O2B_TEST_GENERATE"]);
const res = generateArchDocs(process.env["O2B_TEST_VAULT"], process.env["O2B_TEST_PROJECT"]);
process.stdout.write(readFileSync(res.overviewPath, "utf8"));
`;

function renderUnderCollation(locale: string, reversed: boolean): string {
  const childVault = join(tmp, `vault-${locale}-${reversed ? "rev" : "plain"}`);
  mkdirSync(join(childVault, "Brain"), { recursive: true });
  const child = Bun.spawnSync([process.execPath, "-e", COLLATION_CHILD], {
    env: {
      ...process.env,
      LC_ALL: locale,
      LANG: locale,
      O2B_TEST_REVERSE_COLLATION: reversed ? "1" : "0",
      O2B_TEST_GENERATE: join(import.meta.dir, "../../../src/core/brain/architect/generate.ts"),
      O2B_TEST_VAULT: childVault,
      O2B_TEST_PROJECT: project,
    },
  });
  const stderr = new TextDecoder().decode(child.stderr);
  expect({ locale, code: child.exitCode, stderr }).toEqual({ locale, code: 0, stderr: "" });
  return new TextDecoder().decode(child.stdout);
}

test("the language tie-break does not depend on the host collation", () => {
  // Equal counts, so ONLY the tie-break decides their order.
  seed("src/core/one.aaa");
  seed("src/core/two.aab");

  const plain = renderUnderCollation("C", false);
  const reversed = renderUnderCollation("tr_TR.UTF-8", true);

  expect(reversed).toBe(plain);
  expect(plain).toContain(".aaa (1)");
});

test("a corrupted note aborts the run before any note is written", () => {
  const first = generateArchDocs(vault, project);
  const cliNote = first.modulePaths.find((p) => p.endsWith("cli.md"))!;
  // Unbalanced sentinels: `mergeRegions` fails closed on this note.
  writeFileSync(cliNote, readFileSync(cliNote, "utf8").replace("<!-- o2b:end facts -->", ""));
  const overviewBefore = readFileSync(first.overviewPath, "utf8");
  seed("src/core/added.ts"); // the overview WOULD change

  expect(() => generateArchDocs(vault, project)).toThrow(RegionError);
  // The overview is written first, so a run that wrote as it went would
  // have left it updated next to a module note it could not repair.
  expect(readFileSync(first.overviewPath, "utf8")).toBe(overviewBefore);
});

/**
 * Planning removes the error class that arises while DECIDING a note's
 * bytes. It cannot remove the one that arises while PLACING them, and the
 * module docblock no longer claims otherwise: this is the mid-loop write
 * failure, and it does leave a refreshed prefix beside stale notes.
 *
 * The failure is injected with a real errno rather than a mocked writer -
 * `modules/` is made read-only, so `atomicWriteFileSync`'s temp file
 * cannot be created there. The overview lives one directory up and is
 * written first, so exactly one note is refreshed before the loop stops.
 */
// chmod cannot deny access on Windows (read-only attribute only) or to root.
test.skipIf(CHMOD_CANNOT_DENY)(
  "a write that fails part-way through reports the prefix it already refreshed",
  () => {
    const first = generateArchDocs(vault, project);
    const coreNote = first.modulePaths.find((p) => p.endsWith("core.md"))!;
    const coreBefore = readFileSync(coreNote, "utf8");
    const overviewBefore = readFileSync(first.overviewPath, "utf8");
    seed("src/core/added.ts"); // overview.md AND core.md must both change

    chmodSync(join(first.dir, "modules"), 0o555);
    let caught: unknown = null;
    try {
      generateArchDocs(vault, project);
    } catch (error) {
      caught = error;
    }
    chmodSync(join(first.dir, "modules"), 0o755);

    expect(caught).toBeInstanceOf(ArchWriteError);
    const failure = caught as ArchWriteError;
    expect(failure.path).toBe(coreNote);
    // The overview is on disk; `core.md` and nothing after it are not.
    expect(failure.written).toBe(1);
    expect(failure.pending).toBe(1);
    expect(failure.message).toContain("re-run");
    expect(failure.cause).toBeDefined();

    // The half-refreshed tree the counts describe, observed directly.
    expect(readFileSync(first.overviewPath, "utf8")).not.toBe(overviewBefore);
    expect(readFileSync(coreNote, "utf8")).toBe(coreBefore);
    // A failed write is not a leaked lock.
    expect(existsSync(`${first.dir}.lock`)).toBe(false);

    // And the repair the message promises is real: with the cause gone, one
    // ordinary re-run rewrites the suffix the failure left stale.
    const repaired = generateArchDocs(vault, project);
    expect(repaired.updated).toBe(1);
    expect(readFileSync(coreNote, "utf8")).toContain("added.ts");
  },
);

test("module_paths follows the scan's module order, not the write order", () => {
  const res = generateArchDocs(vault, project);
  const facts = scanProject(project);
  expect(res.modulePaths).toEqual(
    facts.modules.map((m) => join(res.dir, "modules", `${m.name}.md`)),
  );
});

test("the notes are written inside one lock, which is released afterwards", () => {
  const first = generateArchDocs(vault, project);
  const lockPath = `${first.dir}.lock`;
  seed("src/core/added.ts"); // force real writes on the second run

  // The sink runs inside the run, so it can see what the run is holding.
  const heldDuringWrites: boolean[] = [];
  const res = generateArchDocs(vault, project, {
    onProgress: (event) => {
      // `advanced` only: the stage is announced BEFORE the lock is
      // waited for, so a watcher sees "rendering" during the wait too.
      if (event.stage === ARCHITECT_STAGE.render && event.kind === PROGRESS_KIND.advanced) {
        heldDuringWrites.push(existsSync(lockPath));
      }
    },
  });

  expect(res.updated).toBeGreaterThan(0);
  expect(heldDuringWrites.length).toBeGreaterThan(0);
  expect(heldDuringWrites.every(Boolean)).toBe(true);
  expect(existsSync(lockPath)).toBe(false);
});

test("unchanged project regenerates byte-identically", () => {
  const first = generateArchDocs(vault, project);
  const before = readFileSync(first.overviewPath, "utf8");
  const second = generateArchDocs(vault, project);
  expect(readFileSync(second.overviewPath, "utf8")).toBe(before);
  expect(second.created).toBe(0);
  expect(second.unchanged).toBeGreaterThanOrEqual(3);
});

function manifestProject(name: string): string {
  const root = join(tmp, name);
  mkdirSync(root, { recursive: true });
  return root;
}

function put(root: string, relPath: string, content: string): void {
  const abs = join(root, relPath);
  mkdirSync(join(abs, ".."), { recursive: true });
  writeFileSync(abs, content);
}

function pkg(name: string, dependencies: Record<string, string> = {}): string {
  return JSON.stringify({ name, version: "0.1.0", dependencies });
}

/**
 * Manifest facts in the scan: every root manifest and every manifest at a
 * detected module path is read from the walk's path list, a manifest that
 * cannot be read is recorded rather than swallowed, and a module whose
 * manifest names exactly one other module's manifest gets an edge.
 */
describe("manifest facts", () => {
  test("the first read root manifest in precedence order names the project", () => {
    const root = manifestProject("poly");
    put(root, "pyproject.toml", '[project]\nname = "py-name"\ndependencies = ["Requests>=2"]\n');
    put(root, "package.json", pkg("js-name", { "left-pad": "^1" }));
    put(root, "main.py", "print('x')\n");

    const facts = scanProject(root);
    expect(facts.name).toBe("js-name");
    expect(facts.manifest!.dependencies).toEqual(["left-pad"]);
    expect(facts.manifests.map((m) => [m.path, m.ecosystem, m.status])).toEqual([
      ["package.json", "npm", "read"],
      ["pyproject.toml", "pypi", "read"],
    ]);
  });

  test("pyproject.toml names the project when package.json is absent", () => {
    const root = manifestProject("pyonly");
    put(root, "pyproject.toml", '[project]\nname = "py-name"\nversion = "2.0.0"\n');
    const facts = scanProject(root);
    expect(facts.name).toBe("py-name");
    expect(facts.manifest!.version).toBe("2.0.0");
  });

  test("a nameless pyproject.toml does not hide the name of a later Cargo.toml", () => {
    const root = manifestProject("mixed");
    put(root, "pyproject.toml", "[tool.ruff]\nline-length = 100\n");
    put(
      root,
      "Cargo.toml",
      '[package]\nname = "crate-x"\nversion = "1.0.0"\ndescription = "A crate"\n',
    );
    const facts = scanProject(root);
    expect(facts.name).toBe("crate-x");
    expect(facts.manifest).toEqual({
      name: "crate-x",
      version: "1.0.0",
      description: "A crate",
      dependencies: [],
    });
  });

  test("a malformed root manifest is a recorded reading and the name falls back", () => {
    const root = manifestProject("broken-app");
    put(root, "package.json", "{ not json");
    put(root, "index.js", "// x\n");

    const facts = scanProject(root);
    expect(facts.name).toBe("broken-app");
    expect(facts.manifest).toBeNull();
    expect(facts.manifests).toHaveLength(1);
    expect(facts.manifests[0]!.path).toBe("package.json");
    expect(facts.manifests[0]!.status).toBe("malformed");
    expect(facts.manifests[0]!.detail).toBeTruthy();
  });

  test("a project with no manifest has an empty manifest list", () => {
    const root = manifestProject("bare");
    put(root, "main.py", "print('x')\n");
    const facts = scanProject(root);
    expect(facts.manifests).toEqual([]);
    expect(facts.moduleDependencies).toEqual([]);
  });

  test("module manifests are read at the module paths and bind exactly-one edges", () => {
    const root = manifestProject("mono");
    put(root, "package.json", pkg("mono"));
    put(root, "packages/core/package.json", pkg("@mono/core", { lodash: "^4" }));
    put(root, "packages/core/index.ts", "// x\n");
    put(root, "packages/web/package.json", pkg("@mono/web", { "@mono/core": "*", react: "^19" }));
    put(root, "packages/web/index.ts", "// x\n");
    // A manifest deeper than the module root is not the module's manifest.
    put(root, "packages/web/fixtures/package.json", pkg("@mono/fixture"));

    const facts = scanProject(root);
    const web = facts.modules.find((m) => m.name === "web")!;
    expect(web.manifests.map((m) => m.path)).toEqual(["packages/web/package.json"]);
    expect(web.manifests[0]!.fact!.dependencies).toEqual(["@mono/core", "react"]);
    expect(facts.manifests.map((m) => m.path)).toEqual([
      "package.json",
      "packages/core/package.json",
      "packages/web/package.json",
    ]);
    expect(facts.moduleDependencies).toEqual([{ from: "web", to: "core" }]);
  });

  test("a name two modules declare binds nothing, and a self-edge is dropped", () => {
    const root = manifestProject("twins");
    put(root, "packages/a/package.json", pkg("shared"));
    put(root, "packages/b/package.json", pkg("shared"));
    put(root, "packages/c/package.json", pkg("c", { shared: "*", c: "*" }));
    put(root, "packages/d/package.json", pkg("d", { c: "*" }));

    const facts = scanProject(root);
    expect(facts.moduleDependencies).toEqual([{ from: "d", to: "c" }]);
  });

  test("edges bind within one ecosystem under its canonical name", () => {
    const root = manifestProject("pymono");
    put(root, "src/core_lib/pyproject.toml", '[project]\nname = "Core_Lib"\n');
    put(
      root,
      "src/app/pyproject.toml",
      '[project]\nname = "app"\ndependencies = ["core-lib>=1"]\n',
    );
    // An npm package of the same name is a different identity.
    put(root, "src/jsapp/package.json", pkg("jsapp", { "core-lib": "*" }));

    const facts = scanProject(root);
    expect(facts.moduleDependencies).toEqual([{ from: "app", to: "core_lib" }]);
  });
});