Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 empty
diff --git a/ix-cli/src/cli/explain/issue.ts b/ix-cli/src/cli/explain/issue.ts
index 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.md
index 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) |