Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
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.tsnew file mode 100644index 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.tsindex 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 graphdiff --git a/skills/ix/references/troubleshooting.md b/skills/ix/references/troubleshooting.mdindex 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