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

feat: codegraph-partner skill + o2b doctor check (v0.10.13) (#28)

Sol Aitken7d81f0b98bc5
diff --git a/.gitignore b/.gitignore
index 29ae0138..797ef03d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,3 +22,4 @@ node_modules/
!.env.example
.open-second-brain.local.yaml
sandbox-vault/
+.codegraph/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b3f60230..88723868 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.10.13] - 2026-05-24
+
+Partner integration with [codegraph](https://github.com/colbymchenry/codegraph):
+detection-only doctor check plus an agent-facing playbook. OSB stays
+in the vault / prose / Brain lane; codegraph keeps its codebase
+symbol-graph lane. No data is mirrored between them.
+
+### Added
+
+- `code_graph` check in `o2b doctor` - reports installed / not_indexed
+ / missing / error for the current code-project scope. Scope is the
+ current working directory plus top-level siblings of the vault's
+ parent, capped at 50 inspected directories. Configurable through
+ `DoctorOptions.partner.codegraph` (`disabled`, `scanExtraPaths`).
+- `skills/codegraph-partner/SKILL.md` - agent-facing playbook with
+ detection algorithm, branch-by-state behaviour, a hard rule to
+ append `.codegraph/` to `.gitignore` after any `codegraph init`,
+ and a `codegraph_*` vs `brain_*` disambiguation table.
+- `src/core/partner/codegraph.ts` - module exposing `isCodeProject`,
+ `findCodeProjects`, and `checkCodegraph` with dependency-injection
+ hooks for testable `which` / `status -j` interactions.
+
+### Notes
+
+- OSB does not call `codegraph install`, `codegraph init`, or
+ `codegraph index` automatically. The partner CLI is detected, never driven.
+- `.codegraph/` is now in `.gitignore` so any local index inside the
+ OSB repo itself does not land in commits.
+
## [0.10.12] - 2026-05-20
Operational friction reduction: one-command update across all
@@ -2262,6 +2291,7 @@ Hermes / Claude Code / Codex / OpenClaw configurations do not change.
[0.10.0]: https://github.com/itechmeat/open-second-brain/compare/v0.9.1...v0.10.0
[0.9.1]: https://github.com/itechmeat/open-second-brain/compare/v0.9.0...v0.9.1
[0.9.0]: https://github.com/itechmeat/open-second-brain/compare/v0.8.1...v0.9.0
+[0.10.13]: https://github.com/itechmeat/open-second-brain/compare/v0.10.12...v0.10.13
[0.8.1]: https://github.com/itechmeat/open-second-brain/compare/v0.8.0...v0.8.1
[0.8.0]: https://github.com/itechmeat/open-second-brain/compare/v0.7.0...v0.8.0
[0.7.0]: https://github.com/itechmeat/open-second-brain/compare/v0.6.2...v0.7.0
diff --git a/README.md b/README.md
index 0aa10828..1224b6be 100644
--- a/README.md
+++ b/README.md
@@ -590,6 +590,20 @@ you want to.
the pre-v0.10.6 direct-restore path with a stderr warning.
Retention is configurable in `_brain.yaml`.
+## Partner tools
+
+OSB stays in the vault / Brain / prose lane. When the user works on
+code next to the vault, the agent benefits from a complementary index
+over the source - call graphs, callers, callees, impact. The
+[codegraph](https://github.com/colbymchenry/codegraph) CLI and its
+stdio MCP server cover that surface. OSB detects codegraph through
+`o2b doctor` (a `code_graph` line appears when a code project is in
+scope) and ships an agent-facing playbook at
+`skills/codegraph-partner/SKILL.md` that tells the agent when to
+recommend installation and how to disambiguate `codegraph_*` vs
+`brain_*` queries. OSB never installs, initializes, or writes data
+for codegraph - that stays in codegraph's own installer.
+
## Repository
GitHub: <https://github.com/itechmeat/open-second-brain>
diff --git a/install/prerequisites.md b/install/prerequisites.md
index 729a7e09..37aa6533 100644
--- a/install/prerequisites.md
+++ b/install/prerequisites.md
@@ -60,3 +60,15 @@ covers vault invariants — they are complementary, not substitutes.
Then send one event without an explicit `agent` argument and confirm
that the new `Daily/YYYY.MM.DD.md` line begins with the chosen
`@<agent_name>` prefix, not the literal `@agent` placeholder.
+
+## Plays well with codegraph
+
+If your vault sits next to code repositories, OSB cooperates with
+[codegraph](https://github.com/colbymchenry/codegraph) as a partner
+tool: codegraph owns the symbol graph and call relationships in a
+codebase, OSB owns the prose / Brain / preferences in the vault. When
+`o2b doctor` runs from inside or beside a code project, it adds a
+`code_graph` line that summarises whether codegraph is installed and
+indexed there. Installation is performed by codegraph's own installer,
+not by OSB. See `skills/codegraph-partner/SKILL.md` for the agent-side
+playbook.
diff --git a/skills/codegraph-partner/SKILL.md b/skills/codegraph-partner/SKILL.md
new file mode 100644
index 00000000..63b0018b
--- /dev/null
+++ b/skills/codegraph-partner/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: codegraph-partner
+description: Use when the user explicitly mentions codegraph, asks structural code questions such as callers/callees/impact, asks where a symbol is defined, asks what breaks if a symbol changes, or asks for an architectural overview of a code repository. Skip for prose-only or vault-only questions.
+---
+
+# Codegraph partner
+
+OSB and codegraph are complementary, not overlapping. OSB owns the vault
+(Markdown prose, the Brain layer, preferences, paid-action audit). The
+codegraph CLI and its MCP server own the code-symbol graph of a
+repository - callers, callees, impact radius, AST. This skill teaches the
+agent to detect codegraph in the current scope and to use, recommend, or
+stay quiet about it, depending on what is actually nearby.
+
+This skill never installs, initializes, or writes data for codegraph
+itself. Those actions stay in the user's hands or in codegraph's own
+installer.
+
+## Step 1 - detect
+
+Run these checks in order. Stop at the first state that matches.
+
+1. CLI presence: `which codegraph` (or, in Bun runtimes, `Bun.which("codegraph")`).
+2. Code-project signal in the current working directory: a `.git/`
+ directory plus at least one of `package.json`, `pyproject.toml`,
+ `Cargo.toml`, `go.mod`, `tsconfig.json`, `Gemfile`, `composer.json`,
+ `build.gradle`, `pom.xml`.
+3. If neither cwd nor the user's named project is a code project, look
+ at the vault's parent directory and inspect the top-level entries
+ (one level only). Many users keep their repos as siblings of the
+ vault.
+4. Index state: a `.codegraph/` directory inside the code project root.
+5. Confirmed index: `codegraph status -j <project_path>` returns
+ `{"initialized": true, ...}`. The same command on an uninitialized
+ project returns `{"initialized": false, ...}` rather than failing.
+
+The structured way to ask is `o2b doctor`. When OSB is installed in the
+workspace, the doctor report carries a `code_graph` line that
+summarises detection result with node count and file count.
+
+## Step 2 - branch on result
+
+| State | Agent behaviour |
+|-------|-----------------|
+| ok (CLI present, indexed) | Use codegraph for AST and graph queries. No install talk. |
+| not_indexed (CLI present, no `.codegraph/` or `initialized: false`) | Offer one line: "run `codegraph init <path>` to index this repo". Do not run it yourself unless the user asks. |
+| missing + code project | Argued recommendation (Step 5). |
+| missing + no code project in scope | Stay quiet. |
+| error (CLI present, `status -j` errors with a lock or schema issue) | Suggest `codegraph unlock <path>` or a rebuild, but do not run it. |
+
+## Step 3 - hard rule after `codegraph init`
+
+Whenever you run `codegraph init` in any repository on the user's
+behalf, immediately read that repo's `.gitignore` and append a
+`.codegraph/` line if one is not already present. The append must be
+atomic, must preserve the existing trailing newline policy, and must
+not touch any other line.
+
+If the repo does not have a `.gitignore`, do not create one yourself.
+Tell the user the file is missing and that they should decide whether
+to add it.
+
+This rule exists so the local codegraph index never lands in a commit.
+
+## Step 4 - tool-vs-tool disambiguation
+
+Use this table to pick the right tool for each kind of question. Do not
+duplicate a codegraph answer by also running a grep; treat its output
+as authoritative.
+
+| Question shape | Tool |
+|----------------|------|
+| Where is symbol X defined? | `codegraph_search` |
+| Who calls function Y? | `codegraph_callers` |
+| What does Y call? | `codegraph_callees` |
+| What would break if I change Z? | `codegraph_impact` |
+| Show Y's signature or body. | `codegraph_node` |
+| Survey several related symbols at once. | `codegraph_explore` |
+| What files exist under path P? | `codegraph_files` |
+| Prose, page bodies, MOC content, daily notes. | `brain_search` |
+| Confirmed preferences, taste rules. | `brain_query` |
+| Free-text fallback when neither index helps. | Plain grep, last resort. |
+
+## Step 5 - argued install recommendation
+
+Trigger only when both conditions hold: there is a code project in the
+current scope, and `codegraph` is not on the user's PATH.
+
+Show the user a short paragraph that uses real numbers from their
+project, with no emoji and no marketing voice. Template:
+
+> Found a code project at `<path>` with N source files. Without an
+> index, every structural question (callers, impact, "where is X")
+> spawns a grep+read loop that burns several thousand tokens per
+> answer. codegraph keeps a SQLite knowledge graph and serves the
+> same question in sub-millisecond time. Installer:
+> `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh`
+> (or `npm i -g @colbymchenry/codegraph`). After install: `codegraph
+> init <path>` from inside the repo.
+
+If the user says no, drop the topic for the rest of the session. Do
+not nag.
+
+## Out of scope
+
+- Do not call `codegraph install`, `codegraph init`, or `codegraph
+ index` automatically.
+- Do not read or write `.codegraph/codegraph.db`.
+- Do not mirror codegraph data into the Brain or the vault search
+ index.
+- Do not modify `~/.claude.json`, `.cursor/rules/`, or any other agent
+ config on behalf of codegraph.
diff --git a/src/core/doctor.ts b/src/core/doctor.ts
index e5b2294f..797c83b2 100644
--- a/src/core/doctor.ts
+++ b/src/core/doctor.ts
@@ -18,6 +18,7 @@ import {
import { dirname, join } from "node:path";
import { isFile } from "./fs-utils.ts";
+import { checkCodegraph } from "./partner/codegraph.ts";
import type { CheckResult } from "./types.ts";
export function checkVaultWriteable(vault: string): CheckResult {
@@ -299,6 +300,13 @@ export interface DoctorOptions {
readonly vault: string;
readonly config?: string | null;
readonly repoRoot?: string | null;
+ readonly cwd?: string;
+ readonly partner?: {
+ readonly codegraph?: {
+ readonly disabled?: boolean;
+ readonly scanExtraPaths?: ReadonlyArray<string>;
+ };
+ };
}
export function doctor(opts: DoctorOptions): CheckResult[] {
@@ -313,5 +321,12 @@ export function doctor(opts: DoctorOptions): CheckResult[] {
results.push(checkOpenclawManifest(join(root, "openclaw.plugin.json")));
results.push(...checkOpenclawInstallability(root));
}
+ const cg = checkCodegraph({
+ cwd: opts.cwd ?? process.cwd(),
+ vault: opts.vault,
+ scanExtraPaths: opts.partner?.codegraph?.scanExtraPaths,
+ disabled: opts.partner?.codegraph?.disabled,
+ });
+ if (cg) results.push(cg);
return results;
}
diff --git a/src/core/partner/codegraph.ts b/src/core/partner/codegraph.ts
new file mode 100644
index 00000000..de15f74f
--- /dev/null
+++ b/src/core/partner/codegraph.ts
@@ -0,0 +1,238 @@
+/**
+ * Partner integration with codegraph (https://github.com/colbymchenry/codegraph).
+ *
+ * OSB never installs, initializes, or writes data for codegraph. This
+ * module only detects presence and reports back through the standard
+ * doctor `CheckResult` shape so agents (and humans) know whether the
+ * partner tool is available, indexed, or missing in the current scope.
+ *
+ * Detection scope is intentionally narrow: the current working directory
+ * plus the top-level siblings of the vault's parent (where users often
+ * keep their code projects next to the vault) plus any explicit extras
+ * from config. No deep filesystem walk.
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import type { CheckResult } from "../types.ts";
+
+const CODE_MANIFESTS: ReadonlyArray<string> = [
+ "package.json",
+ "pyproject.toml",
+ "Cargo.toml",
+ "go.mod",
+ "tsconfig.json",
+ "Gemfile",
+ "composer.json",
+ "build.gradle",
+ "pom.xml",
+];
+
+const DEFAULT_LIMIT = 50;
+const CODEGRAPH_REPO = "https://github.com/colbymchenry/codegraph";
+
+function isDir(path: string): boolean {
+ try {
+ return statSync(path).isDirectory();
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * Heuristic check: does `dir` look like a code project root?
+ * Requires BOTH a `.git/` directory AND at least one recognised
+ * manifest file (the two-signal rule rejects a stray `package.json`
+ * inside a notes folder).
+ */
+export function isCodeProject(dir: string): boolean {
+ try {
+ if (!existsSync(dir)) return false;
+ if (!isDir(join(dir, ".git"))) return false;
+ return CODE_MANIFESTS.some((m) => existsSync(join(dir, m)));
+ } catch {
+ return false;
+ }
+}
+
+export interface FindCodeProjectsOptions {
+ readonly cwd: string;
+ readonly vault: string;
+ readonly scanExtraPaths?: ReadonlyArray<string>;
+ readonly limit?: number;
+}
+
+/**
+ * Walk the candidate scope (cwd + top-level siblings of `dirname(vault)`
+ * + explicit extras) and return every path that passes `isCodeProject`.
+ * The scan is bounded at `limit` inspected directories (default 50)
+ * so a huge vault parent cannot slow doctor down.
+ */
+export function findCodeProjects(opts: FindCodeProjectsOptions): string[] {
+ const limit = opts.limit ?? DEFAULT_LIMIT;
+ const seen = new Set<string>();
+ const found: string[] = [];
+ let scanned = 0;
+
+ const consider = (raw: string): void => {
+ if (scanned >= limit) return;
+ const path = resolve(raw);
+ if (seen.has(path)) return;
+ seen.add(path);
+ if (!isDir(path)) return;
+ scanned += 1;
+ if (isCodeProject(path)) found.push(path);
+ };
+
+ consider(opts.cwd);
+
+ const vaultParent = dirname(resolve(opts.vault));
+ if (isDir(vaultParent)) {
+ let entries: string[] = [];
+ try {
+ entries = readdirSync(vaultParent);
+ } catch {
+ entries = [];
+ }
+ entries.sort((a, b) => a.localeCompare(b));
+ for (const name of entries) {
+ if (scanned >= limit) break;
+ consider(join(vaultParent, name));
+ }
+ }
+
+ for (const extra of opts.scanExtraPaths ?? []) {
+ if (scanned >= limit) break;
+ consider(extra);
+ }
+
+ return found;
+}
+
+export interface CodegraphStatusData {
+ readonly initialized: boolean;
+ readonly nodeCount?: number;
+ readonly fileCount?: number;
+ readonly edgeCount?: number;
+}
+
+export type CodegraphStatusResult =
+ | { readonly ok: true; readonly data: CodegraphStatusData }
+ | { readonly ok: false; readonly error: string };
+
+export interface CodegraphCheckDeps {
+ readonly whichCodegraph?: () => string | null;
+ readonly runStatusJson?: (projectPath: string) => CodegraphStatusResult;
+}
+
+export interface CodegraphCheckOptions {
+ readonly cwd: string;
+ readonly vault: string;
+ readonly scanExtraPaths?: ReadonlyArray<string>;
+ readonly limit?: number;
+ readonly disabled?: boolean;
+}
+
+function defaultWhichCodegraph(): string | null {
+ if (typeof Bun !== "undefined" && typeof (Bun as { which?: unknown }).which === "function") {
+ const found = (Bun as unknown as { which: (cmd: string) => string | null }).which(
+ "codegraph",
+ );
+ return found ?? null;
+ }
+ return null;
+}
+
+function defaultRunStatusJson(projectPath: string): CodegraphStatusResult {
+ try {
+ const proc = Bun.spawnSync({
+ cmd: ["codegraph", "status", "-j", projectPath],
+ stdout: "pipe",
+ stderr: "pipe",
+ });
+ const stdout = new TextDecoder().decode(proc.stdout).trim();
+ const stderr = new TextDecoder().decode(proc.stderr).trim();
+ if (!proc.success) {
+ if (stdout) {
+ try {
+ const parsed = JSON.parse(stdout) as CodegraphStatusData;
+ return { ok: true, data: parsed };
+ } catch {}
+ }
+ return { ok: false, error: stderr || `codegraph status exited ${proc.exitCode}` };
+ }
+ if (!stdout) {
+ return { ok: false, error: stderr || "empty status output" };
+ }
+ const parsed = JSON.parse(stdout) as CodegraphStatusData;
+ return { ok: true, data: parsed };
+ } catch (exc) {
+ return { ok: false, error: (exc as Error).message ?? String(exc) };
+ }
+}
+
+/**
+ * Doctor-grade check for codegraph partnership. Returns `null` when
+ * the current scope is not a code project (so the doctor printer can
+ * stay quiet) or when the user has explicitly disabled the check.
+ *
+ * Non-null results carry a single `code_graph` `CheckResult` describing
+ * one of four states: `missing`, `not_indexed`, `ok`, or `error`.
+ */
+export function checkCodegraph(
+ opts: CodegraphCheckOptions,
+ deps?: CodegraphCheckDeps,
+): CheckResult | null {
+ if (opts.disabled) return null;
+
+ const projects = findCodeProjects(opts);
+ if (projects.length === 0) return null;
+
+ const project = projects[0]!;
+ const whichFn = deps?.whichCodegraph ?? defaultWhichCodegraph;
+ const cliPath = whichFn();
+
+ if (!cliPath) {
+ return {
+ name: "code_graph",
+ ok: false,
+ message: `code project at ${project}: codegraph not installed (install: ${CODEGRAPH_REPO})`,
+ };
+ }
+
+ const indexDir = join(project, ".codegraph");
+ if (!isDir(indexDir)) {
+ return {
+ name: "code_graph",
+ ok: false,
+ message: `code project at ${project}: not indexed (run: codegraph init ${project})`,
+ };
+ }
+
+ const runFn = deps?.runStatusJson ?? defaultRunStatusJson;
+ const status = runFn(project);
+ if (!status.ok) {
+ return {
+ name: "code_graph",
+ ok: false,
+ message: `code project at ${project}: codegraph status failed: ${status.error}`,
+ };
+ }
+
+ if (!status.data.initialized) {
+ return {
+ name: "code_graph",
+ ok: false,
+ message: `code project at ${project}: not indexed (run: codegraph init ${project})`,
+ };
+ }
+
+ const nodes = status.data.nodeCount ?? 0;
+ const files = status.data.fileCount ?? 0;
+ return {
+ name: "code_graph",
+ ok: true,
+ message: `code project at ${project}: indexed (${nodes} nodes, ${files} files)`,
+ };
+}
diff --git a/tests/core/doctor.test.ts b/tests/core/doctor.test.ts
index cc9eaed4..070dfaf3 100644
--- a/tests/core/doctor.test.ts
+++ b/tests/core/doctor.test.ts
@@ -1,5 +1,5 @@
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -75,7 +75,12 @@ describe("manifest schema checks accept fixture repo", () => {
test("doctor passes on a valid plugin-repo fixture", () => {
const vault = createSandboxVault(tmp);
const repo = createPluginRepo(tmp, true);
- const results = doctor({ vault, repoRoot: repo });
+ const results = doctor({
+ vault,
+ repoRoot: repo,
+ cwd: tmp,
+ partner: { codegraph: { disabled: true } },
+ });
for (const r of results) {
expect(r.ok).toBe(true);
}
@@ -121,4 +126,35 @@ describe("doctor aggregator", () => {
const results = doctor({ vault: tmp });
expect(results.length).toBeGreaterThan(0);
});
+
+ test("omits code_graph when no code project is reachable from cwd or vault", () => {
+ const vaultDir = join(tmp, "vault");
+ mkdirSync(vaultDir);
+ const results = doctor({ vault: vaultDir, cwd: vaultDir });
+ expect(results.some((r) => r.name === "code_graph")).toBe(false);
+ });
+
+ test("omits code_graph when partner.codegraph.disabled is true", () => {
+ const repo = join(tmp, "myrepo");
+ mkdirSync(join(repo, ".git"), { recursive: true });
+ writeFileSync(join(repo, "package.json"), "{}\n");
+ const vaultDir = join(tmp, "vault");
+ mkdirSync(vaultDir);
+ const results = doctor({
+ vault: vaultDir,
+ cwd: repo,
+ partner: { codegraph: { disabled: true } },
+ });
+ expect(results.some((r) => r.name === "code_graph")).toBe(false);
+ });
+
+ test("includes code_graph when cwd is a code project", () => {
+ const repo = join(tmp, "myrepo");
+ mkdirSync(join(repo, ".git"), { recursive: true });
+ writeFileSync(join(repo, "package.json"), "{}\n");
+ const vaultDir = join(tmp, "vault");
+ mkdirSync(vaultDir);
+ const results = doctor({ vault: vaultDir, cwd: repo });
+ expect(results.some((r) => r.name === "code_graph")).toBe(true);
+ });
});
diff --git a/tests/core/partner/codegraph.test.ts b/tests/core/partner/codegraph.test.ts
new file mode 100644
index 00000000..a97665a8
--- /dev/null
+++ b/tests/core/partner/codegraph.test.ts
@@ -0,0 +1,235 @@
+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 {
+ checkCodegraph,
+ findCodeProjects,
+ isCodeProject,
+} from "../../../src/core/partner/codegraph.ts";
+
+let tmp: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-codegraph-partner-"));
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+function makeRepo(dir: string, manifest: string = "package.json"): string {
+ mkdirSync(dir, { recursive: true });
+ mkdirSync(join(dir, ".git"));
+ writeFileSync(join(dir, manifest), "{}\n");
+ return dir;
+}
+
+function makeIndexed(dir: string): void {
+ mkdirSync(join(dir, ".codegraph"), { recursive: true });
+ writeFileSync(join(dir, ".codegraph", "codegraph.db"), "");
+}
+
+describe("isCodeProject", () => {
+ test("empty directory is not a code project", () => {
+ expect(isCodeProject(tmp)).toBe(false);
+ });
+
+ test(".git alone is not enough", () => {
+ mkdirSync(join(tmp, ".git"));
+ expect(isCodeProject(tmp)).toBe(false);
+ });
+
+ test("manifest alone is not enough", () => {
+ writeFileSync(join(tmp, "package.json"), "{}\n");
+ expect(isCodeProject(tmp)).toBe(false);
+ });
+
+ test(".git + package.json -> code project", () => {
+ makeRepo(tmp);
+ expect(isCodeProject(tmp)).toBe(true);
+ });
+
+ test(".git + tsconfig.json -> code project", () => {
+ makeRepo(tmp, "tsconfig.json");
+ expect(isCodeProject(tmp)).toBe(true);
+ });
+
+ test(".git + pyproject.toml -> code project", () => {
+ makeRepo(tmp, "pyproject.toml");
+ expect(isCodeProject(tmp)).toBe(true);
+ });
+
+ test(".git + Cargo.toml -> code project", () => {
+ makeRepo(tmp, "Cargo.toml");
+ expect(isCodeProject(tmp)).toBe(true);
+ });
+
+ test(".git + go.mod -> code project", () => {
+ makeRepo(tmp, "go.mod");
+ expect(isCodeProject(tmp)).toBe(true);
+ });
+
+ test("non-existent dir -> false", () => {
+ expect(isCodeProject(join(tmp, "missing"))).toBe(false);
+ });
+});
+
+describe("findCodeProjects", () => {
+ test("cwd as a code project is included", () => {
+ const repo = makeRepo(join(tmp, "repo"));
+ const out = findCodeProjects({ cwd: repo, vault: join(tmp, "vault") });
+ expect(out).toContain(repo);
+ });
+
+ test("empty scope yields empty result", () => {
+ mkdirSync(join(tmp, "vault"));
+ mkdirSync(join(tmp, "vault-sibling"));
+ const out = findCodeProjects({ cwd: tmp, vault: join(tmp, "vault") });
+ expect(out).toEqual([]);
+ });
+
+ test("vault parent siblings are inspected", () => {
+ const vault = join(tmp, "vault");
+ mkdirSync(vault);
+ const sibling = makeRepo(join(tmp, "my-app"));
+ const out = findCodeProjects({ cwd: vault, vault });
+ expect(out).toContain(sibling);
+ });
+
+ test("does not descend below depth 1 in vault parent", () => {
+ const vault = join(tmp, "vault");
+ mkdirSync(vault);
+ const nested = makeRepo(join(tmp, "outer", "inner", "deep-repo"));
+ const out = findCodeProjects({ cwd: vault, vault });
+ expect(out).not.toContain(nested);
+ });
+
+ test("honors scanExtraPaths", () => {
+ mkdirSync(join(tmp, "vault"));
+ const extra = makeRepo(join(tmp, "elsewhere", "ext-repo"));
+ const out = findCodeProjects({
+ cwd: join(tmp, "vault"),
+ vault: join(tmp, "vault"),
+ scanExtraPaths: [extra],
+ });
+ expect(out).toContain(extra);
+ });
+
+ test("dedupes overlapping scopes", () => {
+ const repo = makeRepo(join(tmp, "repo"));
+ const out = findCodeProjects({
+ cwd: repo,
+ vault: join(tmp, "vault"),
+ scanExtraPaths: [repo],
+ });
+ expect(out.filter((p: string) => p === repo).length).toBe(1);
+ });
+
+ test("bails out at the scan limit", () => {
+ const vault = join(tmp, "vault");
+ mkdirSync(vault);
+ for (let i = 0; i < 60; i++) {
+ makeRepo(join(tmp, `repo-${i}`));
+ }
+ const out = findCodeProjects({ cwd: vault, vault, limit: 10 });
+ expect(out.length).toBeLessThanOrEqual(10);
+ });
+});
+
+describe("checkCodegraph", () => {
+ test("null when nothing in scope is a code project", () => {
+ mkdirSync(join(tmp, "vault"));
+ const r = checkCodegraph(
+ { cwd: tmp, vault: join(tmp, "vault") },
+ { whichCodegraph: () => null },
+ );
+ expect(r).toBeNull();
+ });
+
+ test("null when disabled", () => {
+ const repo = makeRepo(join(tmp, "repo"));
+ const r = checkCodegraph(
+ { cwd: repo, vault: join(tmp, "vault"), disabled: true },
+ { whichCodegraph: () => "/usr/bin/codegraph" },
+ );
+ expect(r).toBeNull();
+ });
+
+ test("code project + no CLI -> missing", () => {
+ const repo = makeRepo(join(tmp, "repo"));
+ const r = checkCodegraph(
+ { cwd: repo, vault: join(tmp, "vault") },
+ { whichCodegraph: () => null },
+ );
+ expect(r).not.toBeNull();
+ expect(r!.name).toBe("code_graph");
+ expect(r!.ok).toBe(false);
+ expect(r!.message.toLowerCase()).toContain("not installed");
+ });
+
+ test("code project + CLI + no .codegraph/ -> not_indexed", () => {
+ const repo = makeRepo(join(tmp, "repo"));
+ const r = checkCodegraph(
+ { cwd: repo, vault: join(tmp, "vault") },
+ { whichCodegraph: () => "/usr/bin/codegraph" },
+ );
+ expect(r!.ok).toBe(false);
+ expect(r!.message.toLowerCase()).toContain("not indexed");
+ expect(r!.message).toContain("codegraph init");
+ });
+
+ test("code project + CLI + indexed + status ok -> ok", () => {
+ const repo = makeRepo(join(tmp, "repo"));
+ makeIndexed(repo);
+ const r = checkCodegraph(
+ { cwd: repo, vault: join(tmp, "vault") },
+ {
+ whichCodegraph: () => "/usr/bin/codegraph",
+ runStatusJson: () => ({
+ ok: true,
+ data: { initialized: true, nodeCount: 4737, fileCount: 392, edgeCount: 11342 },
+ }),
+ },
+ );
+ expect(r!.ok).toBe(true);
+ expect(r!.message).toContain("4737");
+ expect(r!.message).toContain("392");
+ });
+
+ test("status reports initialized:false -> not_indexed", () => {
+ const repo = makeRepo(join(tmp, "repo"));
+ makeIndexed(repo);
+ const r = checkCodegraph(
+ { cwd: repo, vault: join(tmp, "vault") },
+ {
+ whichCodegraph: () => "/usr/bin/codegraph",
+ runStatusJson: () => ({ ok: true, data: { initialized: false } }),
+ },
+ );
+ expect(r!.ok).toBe(false);
+ expect(r!.message.toLowerCase()).toContain("not indexed");
+ });
+
+ test("status returns an error -> error state surfaced", () => {
+ const repo = makeRepo(join(tmp, "repo"));
+ makeIndexed(repo);
+ const r = checkCodegraph(
+ { cwd: repo, vault: join(tmp, "vault") },
+ {
+ whichCodegraph: () => "/usr/bin/codegraph",
+ runStatusJson: () => ({ ok: false, error: "stale lock" }),
+ },
+ );
+ expect(r!.ok).toBe(false);
+ expect(r!.message.toLowerCase()).toContain("stale lock");
+ });
+
+ test("falls back to real PATH lookup when no whichCodegraph dep provided", () => {
+ const repo = makeRepo(join(tmp, "repo"));
+ const r = checkCodegraph({ cwd: repo, vault: join(tmp, "vault") });
+ expect(r).not.toBeNull();
+ expect(r!.name).toBe("code_graph");
+ });
+});