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(context): --lean issue view: trusted starting points only, or none
KageBinary2936058c963a
diff --git a/ix-cli/src/cli/__tests__/context-from-issue-lean.test.ts b/ix-cli/src/cli/__tests__/context-from-issue-lean.test.tsnew file mode 100644index 00000000..3412c184--- /dev/null+++ b/ix-cli/src/cli/__tests__/context-from-issue-lean.test.ts@@ -0,0 +1,129 @@+// Copyright 2026 Ix Infrastructure Inc.++import { describe, expect, it } from "vitest";++import {+ detectContextModeConflict,+ renderLeanIssueLlm,+ renderLeanIssueText,+} from "../commands/context.js";+import {+ isGenericIdentifier,+ issueConfidence,+ leanIssueView,+ LEAN_RANKED,+ type IssuePlan,+ type StartingPoint,+} from "../explain/issue.js";++/**+ * `ix context --from-issue --lean`: the starting points Ix trusts and a few+ * ranked files, or one line saying it trusts none. A full bundle is ~1.5k+ * tokens an agent re-reads every turn; on SWE-PolyBench it added a median 14%+ * tokens even where its start was right.+ */++function ident(token: string, path: string, extra: Partial<StartingPoint> = {}): StartingPoint {+ return { token, id: `n-${token}`, name: token, kind: "class", path, lineStart: 10, lineEnd: 40,+ via: "identifier in issue", ...extra };+}++function plan(starts: StartingPoint[], extra: Partial<IssuePlan> = {}): IssuePlan {+ return {+ starts,+ unresolved: [],+ fallback: false,+ bm25: [+ { path: "src/a.ts", score: 9 }, { path: "src/b.ts", score: 8 }, { path: "src/c.ts", score: 7 },+ { path: "src/d.ts", score: 6 }, { path: "src/e.ts", score: 5 }, { path: "src/f.ts", score: 4 },+ ],+ ...extra,+ } as IssuePlan;+}++describe("isGenericIdentifier", () => {+ it.each(["debug", "bind", "config", "render", "version", "ignore", "Service", "parse"])(+ "treats %s as too common to point anywhere", (t) => expect(isGenericIdentifier(t)).toBe(true));++ it.each(["toJsonTree", "JsonWriter", "get_openai_callback", "KerasTensor", "PojoUtils", "computeIfAbsent", "recurrent"])(+ "treats %s as specific", (t) => expect(isGenericIdentifier(t)).toBe(false));+});++describe("issueConfidence", () => {+ it("never trusts a BM25 fallback", () => {+ const c = issueConfidence(plan([{ token: "src/a.ts", name: "a.ts", kind: "file", path: "src/a.ts", via: "bm25 fallback" }],+ { fallback: true }));+ expect(c.confident).toBe(false);+ expect(c.reason).toMatch(/no code name in the issue resolved/);+ });++ it("does not trust a plan whose only starts are common words", () => {+ const c = issueConfidence(plan([ident("debug", "src/ssr.ts"), ident("bind", "src/dom.ts")]));+ expect(c.confident).toBe(false);+ expect(c.reason).toContain("debug, bind");+ });++ it("keeps named paths and specific identifiers, and drops the common words beside them", () => {+ const c = issueConfidence(plan([+ ident("config", "src/config.ts"),+ ident("JsonWriter", "src/JsonWriter.java"),+ { token: "lib/deploy.js", name: "deploy.js", kind: "file", path: "lib/deploy.js", via: "path in issue" },+ ]));+ expect(c.confident).toBe(true);+ expect(c.starts.map((s) => s.token)).toEqual(["JsonWriter", "lib/deploy.js"]);+ });+});++describe("leanIssueView", () => {+ it("lists the trusted starts, then the next files by BM25 without repeating a start", () => {+ const view = leanIssueView(plan([ident("JsonWriter", "src/b.ts")]));+ expect(view.confidence).toBe("high");+ expect(view.startingPoints.map((s) => s.path)).toEqual(["src/b.ts"]);+ expect(view.alsoRanked.map((f) => f.path)).toEqual(["src/a.ts", "src/c.ts", "src/d.ts", "src/e.ts"]);+ expect(view.alsoRanked).toHaveLength(LEAN_RANKED);+ });++ it("points at nothing when it trusts nothing", () => {+ const view = leanIssueView(plan([ident("debug", "src/ssr.ts")]));+ expect(view).toMatchObject({ confidence: "low", startingPoints: [], alsoRanked: [] });+ });+});++describe("lean rendering", () => {+ const high = leanIssueView(plan([ident("JsonWriter", "src/b.ts")]));+ const low = leanIssueView(plan([], { fallback: true }));++ it("is a few lines, each start a path:lines with why", () => {+ const text = renderLeanIssueText(high);+ expect(text).toContain("src/b.ts:10-40 JsonWriter (class) — the issue names `JsonWriter`");+ expect(text).toContain("Then, by the issue's text: src/a.ts, src/c.ts, src/d.ts, src/e.ts");+ expect(text.length / 4).toBeLessThan(150);+ });++ it("says so in one line when there is no confident start", () => {+ expect(renderLeanIssueText(low).split("\n")).toHaveLength(1);+ expect(renderLeanIssueText(low)).toMatch(/^Ix found no confident starting point/);+ });++ it("renders llm records", () => {+ const lines = renderLeanIssueLlm(high);+ expect(lines[0]).toBe("issue confidence=high");+ expect(lines[1]).toMatch(/^start path=src\/b.ts lines=10-40 name=JsonWriter kind=class why=/);+ expect(lines.filter((l) => l.startsWith("ranked "))).toHaveLength(LEAN_RANKED);+ expect(renderLeanIssueLlm(low)[0]).toMatch(/^issue confidence=low reason=/);+ });+});++describe("--lean flag conflicts", () => {+ it("needs --from-issue", () => {+ expect(detectContextModeConflict({ lean: true }, "Widget")).toMatch(/--lean only shapes a bundle built with --from-issue/);+ });++ it("cannot be saved", () => {+ expect(detectContextModeConflict({ lean: true, fromIssue: "i.md", save: "x" })).toMatch(/--lean cannot be combined with --save/);+ });++ it("is accepted with --from-issue", () => {+ expect(detectContextModeConflict({ lean: true, fromIssue: "i.md" })).toBeUndefined();+ });+});diff --git a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts b/ix-cli/src/cli/__tests__/context-mode-conflict.test.tsindex 5fd5d919..51fd1740 100644--- a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts+++ b/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts@@ -251,6 +251,11 @@ describe("mode-flag coverage does not drift from the command", () => {* so `--out` and `--save` take it, and every budget applies to it.*/const CONTEXT_TARGET_FLAGS = ["fromIssue"];+ /**+ * Shapes what `--from-issue` prints, and means nothing without it: refused+ * on its own, with every mode, and with `--save`/`--out`.+ */+ const CONTEXT_ISSUE_SHAPE_FLAGS = ["lean"];function registeredAttributes(register: (p: Command) => void, name: string): string[] {const program = new Command();@@ -262,10 +267,19 @@ describe("mode-flag coverage does not drift from the command", () => {it("classifies every option ix context registers", () => {expect(registeredAttributes(registerContextCommand, "context")).toEqual(- [...CONTEXT_MODE_FLAGS, ...CONTEXT_BUILD_FLAGS, ...CONTEXT_UNIVERSAL_FLAGS, ...CONTEXT_TARGET_FLAGS].sort(),+ [...CONTEXT_MODE_FLAGS, ...CONTEXT_BUILD_FLAGS, ...CONTEXT_UNIVERSAL_FLAGS, ...CONTEXT_TARGET_FLAGS,+ ...CONTEXT_ISSUE_SHAPE_FLAGS].sort(),);});+ it("refuses an issue-shape flag without --from-issue, in every mode", () => {+ for (const flag of CONTEXT_ISSUE_SHAPE_FLAGS) {+ for (const mode of [{}, { list: true }, { resume: "x" }, { diff: "x" }]) {+ expect(detectContextModeConflict({ ...mode, [flag]: true }), `--${flag} with ${JSON.stringify(mode)}`).toBeTruthy();+ }+ }+ });+it("refuses every build flag given to a mode that builds nothing", () => {for (const mode of ["list", "resume"] as const) {for (const flag of CONTEXT_BUILD_FLAGS) {diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex 8eac3d7b..b762cdfc 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -25,10 +25,12 @@ import {CENTRE_FALLBACK_TRIES,chooseCentre,CLOSENESS_BOOST,+ leanIssueView,planIssue,rankIssueFiles,readIssueText,type Closeness,+ type LeanIssueView,type RankedFile,type StartingPoint,type SymbolHit,@@ -168,6 +170,8 @@ export function clampBudgets(opts: Partial<BudgetSnapshot>): BudgetSnapshot {interface ContextOptions extends Partial<BudgetSnapshot> {/** An issue or bug report to start from, in place of a target: a file, or `-` for stdin. */fromIssue?: string;+ /** With `--from-issue`: only the trusted starting points and a few ranked files. */+ lean?: boolean;kind?: string;path?: string;pick?: number;@@ -328,6 +332,10 @@ export function registerContextCommand(program: Command): void {"--from-issue <file>","Start from an issue or bug report instead of a target: a file, or - for stdin",)+ .option(+ "--lean",+ "With --from-issue: only the starting points Ix trusts and the next few files, or one line saying it trusts none",+ ).option("--kind <kind>", "Filter target entity by kind").option("--path <path>", "Restrict to symbols from files matching this path substring").option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption)@@ -414,6 +422,10 @@ export function registerContextCommand(program: Command): void {renderInvestigationDiff(saved, fresh, opts.format, requestedBudgets);return;}+ if (opts.fromIssue && opts.lean) {+ await emitLeanIssue(opts.fromIssue, opts);+ return;+ }if (opts.fromIssue) {const bundle = await buildIssueBundle(opts.fromIssue, opts, clampBudgets(opts));if (bundle) await emitBundle(bundle, opts);@@ -629,6 +641,12 @@ export function detectContextModeConflict(opts: ContextModeOptions,target?: string,): string | undefined {+ if (opts.lean && opts.fromIssue === undefined) {+ return "--lean only shapes a bundle built with --from-issue; add --from-issue <file>, or drop --lean.";+ }+ if (opts.lean && (opts.save || opts.out)) {+ return `--lean cannot be combined with ${opts.save ? "--save" : "--out"}; a lean view is a few lines of pointers, not a bundle to persist. Drop --lean to save the full bundle.`;+ }if (opts.list && target) {return `--list takes no target; it enumerates every saved investigation. Drop "${target}", or drop --list to build a fresh bundle for it.`;}@@ -1630,30 +1648,10 @@ async function buildIssueBundle(opts: ContextOptions,budgets: BudgetSnapshot,): Promise<ContextBundle | undefined> {- let text: string;- try {- text = await readIssueText(arg);- } catch (error) {- issueFailure(- "issue_unreadable",- `Cannot read the issue from ${arg === "-" ? "stdin" : `"${arg}"`}: ${(error as Error).message}`,- opts.format,- );- return undefined;- }- if (!text.trim()) {- issueFailure("empty_issue", `The issue ${arg === "-" ? "on stdin" : `in "${arg}"`} is empty.`, opts.format);- return undefined;- }-+ const text = await readIssueOrReport(arg, opts.format);+ if (text === undefined) return undefined;const client = new IxClient(getEndpoint());- await ensureReadScope(client);- const scope = activeReadScope();- const plan = await planIssue(text, {- repo: gitRepoAccess(resolveWorkspaceRoot()),- search: async (name) =>- (await client.search(name, { limit: ISSUE_SEARCH_LIMIT, nameOnly: true, ...scope })).map(symbolHit),- });+ const plan = await planIssueWith(client, text);// A path start has no node yet, and the graph may not have one either: it// does not index every tracked file. chooseCentre walks BM25 for one it does.const { starts, centre, walked } = await chooseCentre(@@ -1707,6 +1705,95 @@ async function buildIssueBundle(});}+/** The issue's text, or undefined after reporting why it has none. */+async function readIssueOrReport(arg: string, format: string | undefined): Promise<string | undefined> {+ let text: string;+ try {+ text = await readIssueText(arg);+ } catch (error) {+ issueFailure(+ "issue_unreadable",+ `Cannot read the issue from ${arg === "-" ? "stdin" : `"${arg}"`}: ${(error as Error).message}`,+ format,+ );+ return undefined;+ }+ if (!text.trim()) {+ issueFailure("empty_issue", `The issue ${arg === "-" ? "on stdin" : `in "${arg}"`} is empty.`, format);+ return undefined;+ }+ return text;+}++/** The issue's starting points and lexical ranking, against this workspace's graph. */+async function planIssueWith(client: IxClient, text: string) {+ await ensureReadScope(client);+ const scope = activeReadScope();+ return planIssue(text, {+ repo: gitRepoAccess(resolveWorkspaceRoot()),+ search: async (name) =>+ (await client.search(name, { limit: ISSUE_SEARCH_LIMIT, nameOnly: true, ...scope })).map(symbolHit),+ });+}++/**+ * `ix context --from-issue --lean`: the starting points Ix trusts and the+ * next few files, with no bundle around them. See `leanIssueView` for why.+ * Nothing here needs a centre node, so it is also the cheap path: one search+ * per name the issue mentions, and BM25 over the tracked files.+ */+async function emitLeanIssue(arg: string, opts: ContextOptions): Promise<void> {+ const text = await readIssueOrReport(arg, opts.format);+ if (text === undefined) return;+ const view = leanIssueView(await planIssueWith(new IxClient(getEndpoint()), text));+ if (opts.format === "json") {+ printJson({ kind: "issue_lean", ...view });+ } else if (opts.format === "llm") {+ printLlmLines(renderLeanIssueLlm(view));+ } else {+ console.log(renderLeanIssueText(view));+ }+}++function spanOf(s: StartingPoint): string {+ return s.lineStart !== undefined ? `${s.path}:${s.lineStart}-${s.lineEnd ?? s.lineStart}` : s.path;+}++/** Why a start was trusted, in the words an agent reads. */+function startWhy(s: StartingPoint): string {+ return s.via === "path in issue" ? "the issue names this file" : `the issue names \`${s.token}\``;+}++export function renderLeanIssueText(view: LeanIssueView): string {+ if (view.confidence === "low") {+ return `Ix found no confident starting point for this issue: ${view.reason}.`;+ }+ const lines = ["Where to start (Ix resolved these from the issue's own words):"];+ for (const s of view.startingPoints) {+ lines.push(` ${spanOf(s)} ${s.kind === "file" ? "" : `${s.name} (${s.kind}) — `}${startWhy(s)}`);+ }+ if (view.alsoRanked.length > 0) {+ lines.push(`Then, by the issue's text: ${view.alsoRanked.map((f) => f.path).join(", ")}`);+ }+ return lines.join("\n");+}++export function renderLeanIssueLlm(view: LeanIssueView): string[] {+ const out = [llmLine("issue", [+ ["confidence", view.confidence],+ ...(view.reason ? [["reason", view.reason] as [string, string]] : []),+ ])];+ for (const s of view.startingPoints) {+ out.push(llmLine("start", [+ ["path", s.path],+ ...(s.lineStart !== undefined ? [["lines", `${s.lineStart}-${s.lineEnd ?? s.lineStart}`] as [string, string]] : []),+ ["name", s.name], ["kind", s.kind], ["why", startWhy(s)],+ ]));+ }+ for (const f of view.alsoRanked) out.push(llmLine("ranked", [["path", f.path]]));+ return out;+}+/*** A `--from-issue` failure, readable by the format asked for. `reportFailure`* writes nothing to stdout under `--format json`, so a JSON caller got an emptydiff --git a/ix-cli/src/cli/explain/issue.ts b/ix-cli/src/cli/explain/issue.tsindex 52a811ad..ee385ff5 100644--- a/ix-cli/src/cli/explain/issue.ts+++ b/ix-cli/src/cli/explain/issue.ts@@ -350,6 +350,89 @@ export async function planIssue(};}++/**+ * Whether an identifier the issue names is too common to point anywhere: a+ * short all-lowercase word such as `debug`, `bind`, `config` or `render`+ * resolves to *a* definition, rarely the one the fix touches. Specific names+ * carry an inner capital (`toJsonTree`, `JsonWriter`), an underscore+ * (`get_openai_callback`), or length.+ *+ * Fixed before it was scored on held-out samples: on SWE-PolyBench issues the+ * starts it keeps were in the gold patch 20 times in 32, the ones it drops 2+ * in 7.+ */+export function isGenericIdentifier(token: string): boolean {+ return !(/[a-z][A-Z]/.test(token) || /^[A-Z][a-z]+[A-Z]/.test(token) || token.includes("_") || token.length >= 8);+}++/** How far a plan's starting points can be trusted, and which ones. */+export interface IssueConfidence {+ confident: boolean;+ /** The starts worth pointing an agent at: named paths and specific identifiers. */+ starts: StartingPoint[];+ /** Why not, when not confident. */+ reason?: string;+}++/**+ * A plan is confident when the issue named a path, or a specific identifier,+ * that resolved. A BM25 fallback never is: across four samples of+ * SWE-PolyBench issues its start was in the gold patch once in 55.+ */+export function issueConfidence(plan: Pick<IssuePlan, "starts" | "fallback">): IssueConfidence {+ if (plan.fallback) {+ return { confident: false, starts: [], reason: "no code name in the issue resolved to a definition" };+ }+ const starts = plan.starts.filter((s) => s.via === "path in issue"+ || (s.via === "identifier in issue" && !isGenericIdentifier(s.token)));+ if (starts.length === 0) {+ const names = plan.starts.map((s) => s.token);+ return {+ confident: false,+ starts,+ reason: names.length > 0+ ? `only common words resolved (${names.join(", ")}), which name many definitions`+ : "nothing in the issue resolved to a definition",+ };+ }+ return { confident: true, starts };+}++/** Files after the starting points in a lean view. */+export const LEAN_RANKED = 4;++/** `ix context --from-issue --lean`: where to start, and nothing else. */+export interface LeanIssueView {+ confidence: "high" | "low";+ reason?: string;+ startingPoints: StartingPoint[];+ /** The next files by BM25 against the issue, starting files excluded. */+ alsoRanked: RankedFile[];+ unresolved: string[];+}++/**+ * The lean view of a plan. A full bundle costs about 1.5k tokens, and an+ * agent re-reads it on every turn; on SWE-PolyBench it added a median 14%+ * tokens even where its start was right, and saved no turns. What the agent+ * uses is the pointer, so that is all this keeps: the trusted starting points+ * and a few ranked files -- Ix's starts, then BM25, the ordering that beat+ * both alone on held-out issues. When nothing is trusted it says so, rather+ * than pointing the agent at a guess.+ */+export function leanIssueView(plan: IssuePlan, ranked = LEAN_RANKED): LeanIssueView {+ const c = issueConfidence(plan);+ if (!c.confident) {+ return { confidence: "low", reason: c.reason, startingPoints: [], alsoRanked: [], unresolved: plan.unresolved };+ }+ const startPaths = new Set(c.starts.map((s) => s.path));+ const alsoRanked = rankIssueFiles({ starts: [], bm25: plan.bm25, near: new Map() }, ranked + startPaths.size)+ .filter((f) => !startPaths.has(f.path))+ .slice(0, ranked);+ return { confidence: "high", startingPoints: c.starts, alsoRanked, unresolved: plan.unresolved };+}+/** BM25 files tried, best first, for one the graph has a node for. */export const CENTRE_FALLBACK_TRIES = 10;diff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.mdindex 970f83e1..2e7e2938 100644--- a/skills/ix/references/flags.md+++ b/skills/ix/references/flags.md@@ -197,6 +197,7 @@ Build a bounded, deterministic context bundle for a symbol, file, or entity (or| Flag | Value | Default | Effect ||---|---|---|---|| `--from-issue` | `<file>` | — | Start from an issue or bug report instead of a target: a file, or `-` for stdin. Resolves the paths and code names it mentions to up to 3 definitions (tests, docs, build output and imports excluded), builds the bundle around the first, and adds a `rankedFiles` list: starting files first, then BM25 against the issue text, nudged by graph closeness. Falls back to the best BM25 file when nothing resolves. Not combinable with a target, `--kind`, `--path`, `--pick` or `--diff` |+| `--lean` | — | off | With `--from-issue`: only the starting points Ix trusts (a path the issue names, or a specific identifier) as `path:lines` with why, then the next 4 files by the issue's text — about 150 tokens instead of a full bundle. When it trusts none (a BM25 fallback, or only common words like `debug` resolved), one line saying so. Not combinable with `--save` or `--out` || `--kind` | `<kind>` | — | Filter target entity by kind || `--path` | `<path>` | — | Restrict to symbols from files matching this path substring || `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) |