Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

feat(doctor): flag stray workspaces registered inside another

KageBinarya36bdf97316d
diff --git a/ix-cli/src/cli/__tests__/doctor-nested-workspaces.test.ts b/ix-cli/src/cli/__tests__/doctor-nested-workspaces.test.ts
new file mode 100644
index 00000000..6a5cbf64
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/doctor-nested-workspaces.test.ts
@@ -0,0 +1,89 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { afterEach, describe, expect, it } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { checkNestedWorkspaces, findStrayNestedWorkspaces, isGitTopLevel } from "../commands/doctor.js";
+import type { WorkspaceConfig } from "../config.js";
+
+function workspace(rootPath: string, name: string): WorkspaceConfig {
+ return { workspace_id: `${name}-id`, workspace_name: name, root_path: rootPath, default: false };
+}
+
+describe("stray nested workspaces", () => {
+ const repo = workspace("/work/repo", "repo");
+ // What `ix ingest src/a.ts` left behind before it looked for the workspace
+ // a path belongs to.
+ const stray = workspace("/work/repo/src", "src");
+ // Resolved, as the roots handed to `isGitRoot` are: on Windows `/work/repo`
+ // is `C:\work\repo` by then.
+ const gitRoots = new Set(["/work/repo", "/work/system/alpha", "/work/system/beta"].map(p => resolve(p)));
+ const isGitRoot = (root: string): boolean => gitRoots.has(root);
+
+ it("flags a workspace inside another that is not a git root", () => {
+ expect(findStrayNestedWorkspaces([repo, stray], isGitRoot)).toEqual([{ nested: stray, parent: repo }]);
+ });
+
+ it("names the nearest enclosing workspace as the parent", () => {
+ const deeper = workspace("/work/repo/src/util", "util");
+ expect(findStrayNestedWorkspaces([repo, stray, deeper], isGitRoot)).toEqual([
+ { nested: stray, parent: repo },
+ { nested: deeper, parent: stray },
+ ]);
+ });
+
+ it("leaves member repos of a system alone: they are git roots", () => {
+ const system = workspace("/work/system", "system");
+ const alpha = workspace("/work/system/alpha", "alpha");
+ const beta = workspace("/work/system/beta", "beta");
+ expect(findStrayNestedWorkspaces([system, alpha, beta], isGitRoot)).toEqual([]);
+ });
+
+ it("leaves siblings and unrelated workspaces alone", () => {
+ const sibling = workspace("/work/repo-copy", "repo-copy");
+ const elsewhere = workspace("/elsewhere/app", "app");
+ expect(findStrayNestedWorkspaces([repo, sibling, elsewhere], () => false)).toEqual([]);
+ });
+
+ it("does not count a duplicate entry for the same root as nesting", () => {
+ expect(findStrayNestedWorkspaces([repo, workspace("/work/repo", "again")], () => false)).toEqual([]);
+ });
+
+ it("reports as a warning with the repair, and passes when there is nothing to report", () => {
+ const flagged = checkNestedWorkspaces([repo, stray], isGitRoot, "/home/u/.ix/config.yaml");
+ expect(flagged.ok).toBe(false);
+ expect(flagged.warn, "a warning: doctor reports, the user decides").toBe(true);
+ expect(flagged.detail).toContain("'src' (/work/repo/src) is inside 'repo' (/work/repo)");
+ expect(flagged.detail).toContain('cd "/work/repo/src" && ix reset --workspace --yes');
+ expect(flagged.detail).toContain("/home/u/.ix/config.yaml");
+
+ expect(checkNestedWorkspaces([repo], isGitRoot, "/c")).toEqual({
+ ok: true,
+ detail: "no stray workspace registered inside another",
+ });
+ });
+});
+
+describe("isGitTopLevel", () => {
+ const dirs: string[] = [];
+ afterEach(() => {
+ for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+ });
+
+ it("is true for a repository's top level only", () => {
+ const repo = realpathSync.native(mkdtempSync(join(tmpdir(), "ix-doctor-nested-")));
+ dirs.push(repo);
+ mkdirSync(join(repo, "src"));
+ mkdirSync(join(repo, "member"));
+ execFileSync("git", ["init", "-q"], { cwd: repo, stdio: "ignore" });
+ execFileSync("git", ["init", "-q"], { cwd: join(repo, "member"), stdio: "ignore" });
+
+ expect(isGitTopLevel(repo)).toBe(true);
+ expect(isGitTopLevel(join(repo, "src"))).toBe(false);
+ expect(isGitTopLevel(join(repo, "member")), "a nested repository is its own top level").toBe(true);
+ expect(isGitTopLevel(join(repo, "missing"))).toBe(false);
+ });
+});
diff --git a/ix-cli/src/cli/commands/doctor.ts b/ix-cli/src/cli/commands/doctor.ts
index 65843d90..d8341ddf 100644
--- a/ix-cli/src/cli/commands/doctor.ts
+++ b/ix-cli/src/cli/commands/doctor.ts
@@ -4,7 +4,17 @@ import type { Command } from "commander";
import chalk from "chalk";
import { renderSection, renderSuccess, renderError } from "../ui.js";
import { IxClient } from "../../client/api.js";
-import { findWorkspaceForCwd, getDefaultWorkspace, getEndpoint } from "../config.js";
+import {
+ canonicalWorkspacePath,
+ findWorkspaceForCwd,
+ getDefaultWorkspace,
+ getEndpoint,
+ gitRootFor,
+ loadWorkspaces,
+ selectWorkspaceForCwd,
+ type WorkspaceConfig,
+} from "../config.js";
+import { ixHome } from "../ix-home.js";
import { resolveReadSystemId } from "../resolve.js";
import { assessGraphStats } from "../graph-health.js";
import { llmLine, printLlmLines } from "../llm.js";
@@ -121,6 +131,75 @@ export function checkWindowsLauncher(
};
}
+/** A registered workspace sitting inside another one. */
+export interface NestedWorkspace {
+ nested: WorkspaceConfig;
+ parent: WorkspaceConfig;
+}
+
+/**
+ * Registered workspaces nested inside another registered workspace whose own
+ * root is not a git root.
+ *
+ * Before `ix ingest <path>` looked for the workspace a path belongs to, it
+ * registered the path itself (or a file's directory) as a new workspace: `ix
+ * ingest src/a.ts` in a mapped repo left a `repo/src` workspace holding one
+ * file, and every read under `src/` resolved to it from then on. A nested
+ * workspace that is its own git root is the legitimate shape -- a member repo
+ * of a multi-repo system mapped on its own -- and is not reported.
+ *
+ * `isGitRoot` is injected so the rule can be tested without spawning git.
+ */
+export function findStrayNestedWorkspaces(
+ workspaces: WorkspaceConfig[],
+ isGitRoot: (root: string) => boolean,
+): NestedWorkspace[] {
+ const found: NestedWorkspace[] = [];
+ for (const ws of workspaces) {
+ const root = canonicalWorkspacePath(ws.root_path);
+ const others = workspaces.filter(o => o !== ws && canonicalWorkspacePath(o.root_path) !== root);
+ const parent = selectWorkspaceForCwd(others, root);
+ if (parent && !isGitRoot(root)) found.push({ nested: ws, parent });
+ }
+ return found;
+}
+
+/** Whether `dir` is the top level of a git working tree. */
+export function isGitTopLevel(dir: string): boolean {
+ const top = gitRootFor(dir);
+ return top !== undefined && canonicalWorkspacePath(top) === canonicalWorkspacePath(dir);
+}
+
+/**
+ * The doctor check over {@link findStrayNestedWorkspaces}. Read-only: it names
+ * the repair and leaves the deleting to the user. There is no command that
+ * unregisters a workspace, so the repair is the scoped graph reset (run from
+ * inside the stray workspace, which `ix reset --workspace` resolves to because
+ * the nearest registration wins) and then removing its entry by hand.
+ */
+export function checkNestedWorkspaces(
+ workspaces: WorkspaceConfig[],
+ isGitRoot: (root: string) => boolean,
+ configPath: string,
+): CheckResult {
+ const stray = findStrayNestedWorkspaces(workspaces, isGitRoot);
+ if (stray.length === 0) return { ok: true, detail: "no stray workspace registered inside another" };
+ const lines = stray.map(({ nested, parent }) =>
+ `'${nested.workspace_name}' (${nested.root_path}) is inside '${parent.workspace_name}' (${parent.root_path}) ` +
+ `and is not a git root, so reads under it resolve to it instead of '${parent.workspace_name}'. ` +
+ `Fix: cd "${nested.root_path}" && ix reset --workspace --yes, ` +
+ `then delete its entry (root_path: ${nested.root_path}) from ${configPath}`,
+ );
+ return {
+ ok: false,
+ warn: true,
+ detail:
+ `${stray.length} workspace(s) registered inside another, most likely left by \`ix ingest <path>\` ` +
+ `on a path below a mapped workspace, which older versions registered as a workspace of its own:\n ` +
+ lines.join("\n "),
+ };
+}
+
export function registerDoctorCommand(program: Command): void {
program
.command("doctor")
@@ -233,6 +312,11 @@ export function registerDoctorCommand(program: Command): void {
return { ok: false, warn: true, detail: "none registered yet — run `ix map`" };
},
},
+ {
+ name: "No stray nested workspaces",
+ run: async () =>
+ checkNestedWorkspaces(loadWorkspaces(), isGitTopLevel, pathJoin(ixHome(), "config.yaml")),
+ },
{
// Ix#525: a partially committed graph still has nodes and edges, so
// every check below it passes and doctor calls a half-built graph
diff --git a/skills/ix/references/troubleshooting.md b/skills/ix/references/troubleshooting.md
index 7c4d9e8a..0c0666d7 100644
--- a/skills/ix/references/troubleshooting.md
+++ b/skills/ix/references/troubleshooting.md
@@ -40,6 +40,7 @@ again.
| Slow or stale results | Re-run `ix map --silent` to refresh the graph |
| `error code=workspace_not_mapped` | The directory is in no registered workspace. Graph reads no longer fall back to the `default: true` workspace (an unrelated repo) or to every workspace on the backend. Run `ix map` in the repo (the error names the root it would map), or run from inside a mapped one |
| `graph status=degraded` / `classification=degraded` | The graph kept its nodes but lost its edges, so zero callers/members mean *unknown*, not none. Usually another checkout of the same repo was ingested into this backend later (Ix-memory#211). `ix map` and `ix ingest --force` do not repair it; `ix reset --workspace --yes --ingest` (this workspace only) does. It hollows the other checkout in turn until the backend fix ships |
+| Reads under one subdirectory find almost nothing, while the repo root answers | A stray workspace registered for that subdirectory, left by an older `ix ingest <subdir or file>`. `ix doctor` names it under "No stray nested workspaces" with the repair: `ix reset --workspace --yes` from inside it, then delete its entry from `config.yaml` |
| `Commits against <endpoint> kept failing` | Commits kept failing, so `ix map` gave up rather than sending one doomed request per file. Read the `Last error` line it prints — the CLI cannot tell the two causes apart, because the memory layer answers 500 for both. **A saturated database:** `ix doctor` still passes (it asks whether the backend is reachable and the graph consistent, and an ArangoDB too busy to begin a transaction is both), so check `docker stats` and `GET /_db/<db>/_api/query/current`, then re-map once it is idle. **Patches the backend will not accept:** the error names the patch or the field; re-map after fixing it, or `IX_COMMIT_FAILURE_LIMIT=0` to send the rest regardless. |
## Environment flags