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
17.5 KB
Raw Blame
/**
 * Manifest readers of the architecture scanner: one reading per manifest,
 * a closed status for every outcome, never a throw on project content.
 */

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

import {
  canonicalDependencyName,
  MANIFEST_MAX_BYTES,
  MANIFEST_STATUS,
  readManifestAt,
} from "../../../src/core/brain/architect/manifests.ts";
import { MANIFEST_ECOSYSTEM } from "../../../src/core/project-manifests.ts";
import { CHMOD_CANNOT_DENY, IS_WINDOWS } 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 root: string;

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

/** Report `size` from the next fstat, as if the file grew after it. */
function fstatReportsSize(size: number): { mockRestore(): void; mock: { calls: unknown[] } } {
  const real = fs.fstatSync;
  const spy = spyOn(fs, "fstatSync").mockImplementation(((fd: number) => {
    const stat = real(fd);
    return Object.assign(Object.create(Object.getPrototypeOf(stat)), stat, { size });
  }) as typeof fs.fstatSync);
  return spy;
}

beforeEach(() => {
  root = mkdtempSync(join(tmpdir(), "o2b-architect-manifests-"));
});

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

describe("package.json", () => {
  test("a read manifest lists runtime dependencies and counts the other groups", () => {
    seed(
      "package.json",
      JSON.stringify({
        name: "demo",
        version: "1.2.3",
        description: "A demo",
        main: "index.js",
        dependencies: { zod: "^3", "@scope/b": "1", alpha: "2" },
        devDependencies: { typescript: "5", vitest: "1" },
        optionalDependencies: { fsevents: "2" },
        peerDependencies: { react: "18", "react-dom": "18", vue: "3" },
      }),
    );
    const reading = readManifestAt(root, "package.json");
    expect(reading.path).toBe("package.json");
    expect(reading.ecosystem).toBe(MANIFEST_ECOSYSTEM.npm);
    expect(reading.status).toBe(MANIFEST_STATUS.read);
    expect(reading.detail).toBeUndefined();
    expect(reading.fact).toEqual({
      name: "demo",
      version: "1.2.3",
      description: "A demo",
      dependencies: ["@scope/b", "alpha", "zod"],
    });
    expect(reading.otherGroups).toEqual([
      { group: "dev", count: 2 },
      { group: "optional", count: 1 },
      { group: "peer", count: 3 },
    ]);
    expect(reading.raw?.["main"]).toBe("index.js");
  });

  test("a module manifest keeps its project-relative path with forward slashes", () => {
    seed("packages/web/package.json", JSON.stringify({ name: "web" }));
    const reading = readManifestAt(root, join("packages", "web", "package.json"));
    expect(reading.path).toBe("packages/web/package.json");
    expect(reading.fact?.dependencies).toEqual([]);
    expect(reading.otherGroups).toEqual([]);
  });

  test("broken JSON is malformed, not absent", () => {
    seed("package.json", "{ not json");
    const reading = readManifestAt(root, "package.json");
    expect(reading.status).toBe(MANIFEST_STATUS.malformed);
    expect(reading.detail).toBeTruthy();
    expect(reading.fact).toBeNull();
    expect(reading.raw).toBeNull();
    expect(reading.otherGroups).toEqual([]);
  });

  test("a package.json that starts with a UTF-8 byte order mark is read", () => {
    seed(
      "package.json",
      `\uFEFF${JSON.stringify({ name: "bomtool", dependencies: { zod: "^3" } })}`,
    );
    const reading = readManifestAt(root, "package.json");
    expect(reading.status).toBe(MANIFEST_STATUS.read);
    expect(reading.fact?.name).toBe("bomtool");
  });

  test("a JSON value that is not an object is malformed", () => {
    seed("package.json", "[1, 2]");
    const reading = readManifestAt(root, "package.json");
    expect(reading.status).toBe(MANIFEST_STATUS.malformed);
    expect(reading.detail).toBeTruthy();
  });

  test.skipIf(CHMOD_CANNOT_DENY)(
    "a file that cannot be read is unreadable with its errno code",
    () => {
      seed("package.json", "{}");
      chmodSync(join(root, "package.json"), 0o000);
      try {
        const reading = readManifestAt(root, "package.json");
        expect(reading.status).toBe(MANIFEST_STATUS.unreadable);
        expect(reading.detail).toBe("EACCES");
        expect(reading.fact).toBeNull();
      } finally {
        chmodSync(join(root, "package.json"), 0o644);
      }
    },
  );
});

describe("pyproject.toml", () => {
  test("PEP 621 dependencies are named by their PEP 508 prefix and PEP 503 name", () => {
    seed(
      "pyproject.toml",
      [
        "[project]",
        'name = "demo-py"',
        'version = "0.1.0"',
        'description = "Python demo"',
        "dependencies = [",
        '  "Requests[security]>=2.0",',
        '  "zope.interface (>=5)",',
        "  \"typing_extensions; python_version < '3.11'\",",
        '  "pkg @ https://example.org/pkg.whl",',
        '  "Flask~=3.0",',
        '  "flask>=2",',
        '  "attrs",',
        "]",
        "",
        "[project.optional-dependencies]",
        'docs = ["sphinx", "furo"]',
        'test = ["pytest"]',
        "",
        "[dependency-groups]",
        'lint = ["ruff", "mypy"]',
      ].join("\n"),
    );
    const reading = readManifestAt(root, "pyproject.toml");
    expect(reading.status).toBe(MANIFEST_STATUS.read);
    expect(reading.ecosystem).toBe(MANIFEST_ECOSYSTEM.pypi);
    expect(reading.raw).toBeNull();
    expect(reading.fact).toEqual({
      name: "demo-py",
      version: "0.1.0",
      description: "Python demo",
      dependencies: ["attrs", "flask", "pkg", "requests", "typing-extensions", "zope-interface"],
    });
    expect(reading.otherGroups).toEqual([
      { group: "dev", count: 2 },
      { group: "optional", count: 3 },
    ]);
  });

  test("Poetry dependencies are read and the python constraint is dropped", () => {
    seed(
      "pyproject.toml",
      [
        "[tool.poetry]",
        'name = "poetry-demo"',
        'version = "2.0.0"',
        "",
        "[tool.poetry.dependencies]",
        'python = "^3.11"',
        'Django = "^5"',
        'my_lib = { path = "../my_lib" }',
        "",
        "[tool.poetry.group.dev.dependencies]",
        'pytest = "^8"',
        "",
        "[tool.poetry.dev-dependencies]",
        'black = "*"',
      ].join("\n"),
    );
    const reading = readManifestAt(root, "pyproject.toml");
    expect(reading.status).toBe(MANIFEST_STATUS.read);
    expect(reading.fact).toEqual({
      name: "poetry-demo",
      version: "2.0.0",
      description: null,
      dependencies: ["django", "my-lib"],
    });
    expect(reading.otherGroups).toEqual([{ group: "dev", count: 2 }]);
  });

  test("the Poetry interpreter key is dropped whatever its case", () => {
    seed("pyproject.toml", '[tool.poetry.dependencies]\nPython = "^3.11"\nDjango = "^5"\n');
    expect(readManifestAt(root, "pyproject.toml").fact?.dependencies).toEqual(["django"]);
  });
});

describe("canonicalDependencyName", () => {
  test("PyPI names follow PEP 503; other ecosystems keep the declared name", () => {
    expect(canonicalDependencyName(MANIFEST_ECOSYSTEM.pypi, "Foo__Bar.baz-Qux")).toBe(
      "foo-bar-baz-qux",
    );
    expect(canonicalDependencyName(MANIFEST_ECOSYSTEM.npm, "@Scope/Pkg_x")).toBe("@Scope/Pkg_x");
  });
});

describe("Cargo.toml", () => {
  test("runtime dependencies come from every dependencies table, renames resolved", () => {
    seed(
      "Cargo.toml",
      [
        "[package]",
        'name = "demo-rs"',
        'version = "0.3.0"',
        'description = "Rust demo"',
        "",
        "[dependencies]",
        'serde = { version = "1", features = ["derive"] }',
        'rand_core = "0.6"',
        'web = { package = "actix-web", version = "4" }',
        "",
        "[dependencies.tokio]",
        'version = "1"',
        "",
        "[target.'cfg(windows)'.dependencies]",
        'winapi = "0.3"',
        "",
        "[target.'cfg(unix)'.dependencies]",
        'serde = "1"',
        "",
        "[dev-dependencies]",
        'proptest = "1"',
        'criterion = "0.5"',
        "",
        "[target.'cfg(unix)'.dev-dependencies]",
        'tempfile = "3"',
        "",
        "[build-dependencies]",
        'cc = "1"',
      ].join("\n"),
    );
    const reading = readManifestAt(root, "Cargo.toml");
    expect(reading.status).toBe(MANIFEST_STATUS.read);
    expect(reading.ecosystem).toBe(MANIFEST_ECOSYSTEM.cargo);
    expect(reading.raw).toBeNull();
    expect(reading.fact).toEqual({
      name: "demo-rs",
      version: "0.3.0",
      description: "Rust demo",
      dependencies: ["actix-web", "rand_core", "serde", "tokio", "winapi"],
    });
    expect(reading.otherGroups).toEqual([
      { group: "build", count: 1 },
      { group: "dev", count: 3 },
    ]);
  });

  test("a workspace-inherited version is not a version string", () => {
    seed("Cargo.toml", '[package]\nname = "member"\nversion = { workspace = true }\n');
    expect(readManifestAt(root, "Cargo.toml").fact).toEqual({
      name: "member",
      version: null,
      description: null,
      dependencies: [],
    });
  });

  test("broken TOML is malformed", () => {
    seed("Cargo.toml", "[dependencies\nserde = ");
    expect(readManifestAt(root, "Cargo.toml").status).toBe(MANIFEST_STATUS.malformed);
  });
});

describe("go.mod", () => {
  test("require lines and blocks are read; indirect counted; replace and exclude ignored", () => {
    seed(
      "go.mod",
      [
        "// The demo module.",
        'module "example.com/demo"',
        "",
        "go 1.22",
        "",
        "require github.com/single/dep v1.0.0",
        "",
        "require (",
        "\tgithub.com/b/lib v1.2.3",
        '\t"github.com/quoted/path" v0.1.0 // pinned',
        "\tgolang.org/x/text v0.14.0 // indirect",
        "\tgithub.com/c/other v2.0.0+incompatible // indirect; needed by b",
        ")",
        "",
        "replace github.com/b/lib => ../lib",
        "replace (",
        "\tgithub.com/replaced/only v1.0.0 => ./local",
        ")",
        "exclude github.com/excluded/only v0.9.0",
        "exclude (",
        "\tgithub.com/excluded/block v0.8.0",
        ")",
      ].join("\n"),
    );
    const reading = readManifestAt(root, "go.mod");
    expect(reading.status).toBe(MANIFEST_STATUS.read);
    expect(reading.ecosystem).toBe(MANIFEST_ECOSYSTEM.go);
    expect(reading.fact).toEqual({
      name: "example.com/demo",
      version: null,
      description: null,
      dependencies: ["github.com/b/lib", "github.com/quoted/path", "github.com/single/dep"],
    });
    expect(reading.otherGroups).toEqual([{ group: "indirect", count: 2 }]);
  });

  test("an unterminated require block is malformed", () => {
    seed("go.mod", "module example.com/x\n\nrequire (\n\tgithub.com/a/b v1.0.0\n");
    const reading = readManifestAt(root, "go.mod");
    expect(reading.status).toBe(MANIFEST_STATUS.malformed);
    expect(reading.detail).toBeTruthy();
    expect(reading.fact).toBeNull();
  });

  test("a block opener written without a space before the parenthesis is still a block", () => {
    seed(
      "go.mod",
      "module example.com/x\n\nrequire(\n\tgithub.com/a/b v1.0.0\n)\n\nreplace(\n\tgithub.com/r/s v1.0.0 => ./s\n)\n",
    );
    const reading = readManifestAt(root, "go.mod");
    expect(reading.status).toBe(MANIFEST_STATUS.read);
    expect(reading.fact?.dependencies).toEqual(["github.com/a/b"]);
  });

  test.each(["require ()", "require ( )", "require()"])(
    "an empty block on one line, %s, is read",
    (line) => {
      seed("go.mod", `module example.com/x\n\n${line}\nrequire github.com/a/b v1.0.0\n`);
      const reading = readManifestAt(root, "go.mod");
      expect(reading.status).toBe(MANIFEST_STATUS.read);
      expect(reading.fact?.dependencies).toEqual(["github.com/a/b"]);
    },
  );

  test("a require entry without a version is malformed", () => {
    seed("go.mod", "module example.com/x\n\nrequire github.com/a/b\n");
    expect(readManifestAt(root, "go.mod").status).toBe(MANIFEST_STATUS.malformed);
  });
});

describe("strings a region body cannot carry", () => {
  test("a dependency name a manifest cannot honestly declare is dropped and counted", () => {
    seed(
      "package.json",
      JSON.stringify({
        name: "demo",
        dependencies: { zod: "^3", "x\n<!-- o2b:end dependencies -->": "1", "a b": "1" },
        devDependencies: { "[[Brain/x]]": "1", vitest: "1" },
      }),
    );
    const reading = readManifestAt(root, "package.json");
    expect(reading.fact?.dependencies).toEqual(["zod"]);
    expect(reading.otherGroups).toEqual([
      { group: "dev", count: 1 },
      { group: "unrepresentable", count: 3 },
    ]);
  });

  test("head fields are one line and cannot open a wikilink", () => {
    seed(
      "Cargo.toml",
      [
        "[package]",
        'name = "demo\\u0007rs"',
        'version = "1.0.0\\r\\n2"',
        'description = """',
        "First line.",
        "See [[Brain/preferences/x]].",
        '"""',
      ].join("\n"),
    );
    expect(readManifestAt(root, "Cargo.toml").fact).toEqual({
      name: "demo rs",
      version: "1.0.0 2",
      description: "First line. See [\\[Brain/preferences/x]].",
      dependencies: [],
    });
  });

  test.each([
    ["package.json", "{ not json", "invalid JSON"],
    ["package.json", "[1, 2]", "top-level value is not a table"],
    ["pyproject.toml", "[project\nname = ", "invalid TOML"],
    ["Cargo.toml", 'x = "tok3n', "invalid TOML"],
  ])("a %s that does not parse carries a fixed detail", (file, content, detail) => {
    seed(file, content);
    const reading = readManifestAt(root, file);
    expect(reading.status).toBe(MANIFEST_STATUS.malformed);
    expect(reading.detail).toBe(detail);
  });
});

describe("what the reader opens", () => {
  test("a manifest larger than the cap is unreadable and not read", () => {
    seed("package.json", `{"name":"big","description":"${"x".repeat(MANIFEST_MAX_BYTES)}"}`);
    const reading = readManifestAt(root, "package.json");
    expect(reading.status).toBe(MANIFEST_STATUS.unreadable);
    expect(reading.detail).toBe(`larger than ${MANIFEST_MAX_BYTES} bytes`);
    expect(reading.fact).toBeNull();
  });

  test("a manifest that grows after the fstat but stays under the cap is read in full", () => {
    const description = "y".repeat(8192);
    seed("package.json", JSON.stringify({ name: "grown", description }));
    const spy = fstatReportsSize(16);
    try {
      const reading = readManifestAt(root, "package.json");
      expect(spy.mock.calls.length).toBe(1);
      expect(reading.status).toBe(MANIFEST_STATUS.read);
      expect(reading.fact?.name).toBe("grown");
      expect(reading.fact?.description).toBe(description);
    } finally {
      spy.mockRestore();
    }
  });

  test("a manifest that grows past the cap after the fstat is unreadable", () => {
    seed("package.json", `{"name":"big","description":"${"x".repeat(MANIFEST_MAX_BYTES)}"}`);
    const spy = fstatReportsSize(16);
    try {
      const reading = readManifestAt(root, "package.json");
      expect(spy.mock.calls.length).toBe(1);
      expect(reading.status).toBe(MANIFEST_STATUS.unreadable);
      expect(reading.detail).toBe(`larger than ${MANIFEST_MAX_BYTES} bytes`);
    } finally {
      spy.mockRestore();
    }
  });

  // Windows has no FIFOs, and creating a symlink there needs a privilege.
  test.skipIf(IS_WINDOWS)("a FIFO is not a regular file and the read does not block", () => {
    const fifo = join(root, "go.mod");
    const made = Bun.spawnSync(["mkfifo", fifo]);
    expect(made.exitCode).toBe(0);
    // A writer that holds the FIFO open for two seconds and writes
    // nothing: a reader that blocks fails on its status after two seconds
    // instead of hanging the run.
    const writer = Bun.spawn(["sh", "-c", 'exec 3>"$0"; exec sleep 2', fifo]);
    try {
      const reading = readManifestAt(root, "go.mod");
      expect(reading.status).toBe(MANIFEST_STATUS.unreadable);
      expect(reading.detail).toBe("not a regular file");
    } finally {
      writer.kill();
    }
  });

  test.skipIf(IS_WINDOWS)("a manifest swapped for a symlink is not followed", () => {
    seed("elsewhere.json", JSON.stringify({ name: "elsewhere" }));
    symlinkSync(join(root, "elsewhere.json"), join(root, "package.json"));
    const reading = readManifestAt(root, "package.json");
    expect(reading.status).toBe(MANIFEST_STATUS.unreadable);
    expect(reading.detail).toBe("ELOOP");
  });
});

describe("unsupported manifests and caller errors", () => {
  test.each([
    ["pom.xml", MANIFEST_ECOSYSTEM.maven],
    ["build.gradle", MANIFEST_ECOSYSTEM.gradle],
    ["Gemfile", MANIFEST_ECOSYSTEM.rubygems],
    ["composer.json", MANIFEST_ECOSYSTEM.composer],
  ])("%s is reported unsupported with its ecosystem and no fact", (file, ecosystem) => {
    seed(`api/${file}`, "anything");
    const reading = readManifestAt(root, `api/${file}`);
    expect(reading).toEqual({
      path: `api/${file}`,
      ecosystem,
      status: MANIFEST_STATUS.unsupported,
      fact: null,
      otherGroups: [],
      raw: null,
    });
  });

  test("a basename that is not a dependency manifest throws a TypeError naming the path", () => {
    seed("tsconfig.json", "{}");
    expect(() => readManifestAt(root, "tsconfig.json")).toThrow(TypeError);
    expect(() => readManifestAt(root, "src/README.md")).toThrow("src/README.md");
  });
});