Skip to content

armgit / Ix

Public Imported from GitHub
0

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

fix(context): report the budget that was used, and one grammar for llm records

Joseph Mikhailbec895421574
diff --git a/docs/llm-format.md b/docs/llm-format.md
index 998c35af..5b7c1d38 100644
--- a/docs/llm-format.md
+++ b/docs/llm-format.md
@@ -83,21 +83,54 @@ contains method=12 field=4
item name=parseFile kind=method
```
+`ix context <target>`:
+
+```
+context target=Widget target_kind=class stale=false classification=current entities=2 relationships=1 claims=1 decisions=0 conflicts=0 intents=0 evidence=7 truncated_entities=0 truncated_relationships=0 truncated_evidence=0 truncated_chars=0
+evidence score=0 kind=target title="Widget (class)"
+evidence score=20 kind=claim title="renders to DOM"
+evidence score=30 kind=relationship title="entity-1 --calls--> entity-2"
+```
+
+One header record, then the ranked evidence. The entity, relationship and claim
+lists stay counts here — `llm` is the token-minimal surface and the ranked
+evidence is what it exists to deliver; `--format json` carries the rest.
+
`ix context --diff <id>`:
```
-diff investigation=widget target=Widget freshness_previous=current freshness_current=stale
+diff investigation=widget target=Widget saved_at=2026-01-03T09:12:44.108Z generated_at=2026-01-19T11:02:07.441Z freshness_previous=current freshness_current=stale
+budgets scope=saved entities=50 relationships=100 evidence=25 chars=12000
+budgets scope=requested entities=10 applied=false
+budgets scope=effective entities=50 relationships=100 evidence=25 chars=12000
count added_entities=1 removed_entities=0 added_relationships=1 removed_relationships=1 added_evidence=2 removed_evidence=1 added_claims=1 removed_claims=0
-entity change=added kind=method name=mount
+entity change=added id=entity-3 kind=method name=mount path=src/widget.ts
relationship change=removed src=entity-1 pred=calls dst=entity-2
evidence change=added score=30 kind=relationship title="entity-1 --holds--> entity-3"
-claim change=added id="claim-mounts to DOM" status=active
+claim change=added id=c-8f31a2 entity=entity-1 status=active statement="mounts to DOM"
```
The counts keep their zeros: "nothing was added" is the answer `--diff` was
asked for, not a default worth dropping. Added and removed share one record
kind and separate on `change=`, so a consumer routing on `entity` sees both
sides of the comparison.
+
+`saved_at` is when the baseline snapshot was taken. `freshness_previous` says
+whether it was fresh *then*, not how long ago that was, so a snapshot from five
+minutes ago and one from three months ago read identically without it.
+
+The three `budgets` records say which limits governed the comparison.
+`scope=saved` is the saved investigation's, `scope=effective` is what the fresh
+bundle was actually built with, and `scope=requested` appears only when
+`--max-*` flags were passed — carrying `applied=`, because saved budgets govern
+`--diff` and a flag that changed nothing is worth saying so in a field a
+consumer can test.
+
+An `entity` record carries `id=` because `relationship` records name their
+endpoints by entity id; without it `src=`/`dst=` resolve to nothing the reader
+has seen. A `claim` record carries `statement=` for the same reason its `id=`
+is not enough: the id is the backend's, and the statement is what changed.
+
`ix context --list`:
```
diff --git a/ix-cli/src/cli/__tests__/context-investigation.test.ts b/ix-cli/src/cli/__tests__/context-investigation.test.ts
index 8fc58909..479a5cdb 100644
--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts
+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts
@@ -20,6 +20,7 @@ import {
loadInvestigation,
mergeDiffOptions,
parseRequestedBudgets,
+ renderBundle,
renderInvestigationDiff,
saveInvestigation,
} from "../commands/context.js";
@@ -62,23 +63,31 @@ function envelope(id: string, bundle: unknown) {
}
/**
- * Capture what renderWarning printed while `fn` ran.
+ * Capture the refusal message `fn` printed, and prove it stayed off stdout.
*
- * The refusal message is the only thing that says *which* guard rejected a
- * fixture; asserting on the return value alone cannot tell the envelope check
- * from the schema check. renderWarning goes to console.log (ui.ts), so that is
- * what gets spied on.
+ * The message is the only thing that says *which* guard rejected a fixture;
+ * asserting on the return value alone cannot tell the envelope check from the
+ * schema check. It goes to stderr: it used to go to console.log, which put a
+ * chalk-coloured prose line inside the payload of the very `--format json` and
+ * `--format llm` callers the refusal was answering. Anything on stdout here is
+ * that defect returning, so this fails on it rather than reading it.
*/
function captureWarnings(fn: () => void): string {
const lines: string[] = [];
- const spy = vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+ const stdout: string[] = [];
+ const outSpy = vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+ stdout.push(args.map(String).join(" "));
+ });
+ const spy = vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
lines.push(args.map(String).join(" "));
});
try {
fn();
} finally {
spy.mockRestore();
+ outSpy.mockRestore();
}
+ expect(stdout).toEqual([]);
// chalk wraps the message as a whole, so the text stays contiguous; strip the
// colour codes anyway so a CI run with colour forced on matches a local one.
return lines.join("\n").replace(/\u001b\[[0-9;]*m/g, "");
@@ -424,55 +433,61 @@ describe("ix context investigation state", () => {
expect(existsSync(join(home, ".version-check.json"))).toBe(false);
});
- it("exposes effective budgets on every --diff diff, sourced from the saved investigation", () => {
- // The reproduction in B-4 showed that --max-* flags on the CLI do not change
- // the fresh side's budget: buildFreshBundle always receives saved.bundle.budgets.
- // The transparency fix surfaces that fact as data instead of hiding it, so
- // agents reading the diff JSON can answer "what budget governed this comparison"
- // without reading the source.
+ it("reports the budget the fresh bundle was actually built with", () => {
+ // `effective` is read off `fresh.budgets`, not restated from
+ // `saved.bundle.budgets`. That distinction is the whole point of the
+ // record: a change that let CLI overrides win would edit the
+ // `buildFreshBundle` argument in the action handler, and a restated
+ // `effective` would go on reporting the saved budget while the fresh side
+ // used another one -- the silent misreport this exists to prevent.
+ //
+ // So the two sides are given different budgets here. The earlier version of
+ // this test pinned `effective` to the *saved* snapshot even though the
+ // fresh bundle in front of it had been built with 50/100/25/12000 -- a
+ // budget neither side of the comparison had used together.
const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);
saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 };
saveInvestigation("widget-check", saved);
const stored = loadInvestigation("widget-check")!;
const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);
+ expect(fresh.budgets).toEqual({ maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 });
- // Without CLI overrides, requested is absent and effective mirrors saved.
const baselineDiff = diffInvestigations(stored, fresh);
expect(baselineDiff.budgets.saved).toEqual({ maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 });
expect(baselineDiff.budgets.requested).toBeUndefined();
- expect(baselineDiff.budgets.effective).toEqual(baselineDiff.budgets.saved);
- expect(baselineDiff.budgets.note).toMatch(/no --max-\* overrides/i);
+ expect(baselineDiff.budgets.effective).toEqual(fresh.budgets);
+ expect(baselineDiff.budgets.requestedApplied).toBe(false);
+ // Nothing was asked for, so there is nothing to explain.
+ expect(baselineDiff.budgets.note).toBeUndefined();
- // With CLI overrides parsed from raw commander strings, requested captures
- // every flag the user passed (even ones that disagree with saved), and the
- // note makes the precedence explicit.
- const requested = parseRequestedBudgets({ maxEntities: "50", maxEvidence: "25", maxRelationships: "100" });
- expect(requested).toEqual({ maxEntities: 50, maxEvidence: 25, maxRelationships: 100 });
+ // With CLI overrides, `requested` captures every flag the caller passed,
+ // and `requestedApplied` says whether they governed -- derived by comparing
+ // against `effective`, not hardcoded.
+ const requested = parseRequestedBudgets({ maxEntities: 5, maxEvidence: 2, maxRelationships: 1 });
+ expect(requested).toEqual({ maxEntities: 5, maxEvidence: 2, maxRelationships: 1 });
const overrideDiff = diffInvestigations(stored, fresh, requested);
expect(overrideDiff.budgets.requested).toEqual(requested);
- // Critical invariant: the fresh bundle was still built with saved budgets,
- // so effective is the saved snapshot, not the requested one.
- expect(overrideDiff.budgets.effective).toEqual(overrideDiff.budgets.saved);
- expect(overrideDiff.budgets.note).toMatch(/--max-\* flags on the CLI are recorded/i);
+ expect(overrideDiff.budgets.effective).toEqual(fresh.budgets);
+ expect(overrideDiff.budgets.requestedApplied).toBe(false);
+ expect(overrideDiff.budgets.note).toMatch(/were not applied to the fresh side/i);
+
+ // …and it reads true when they do match what the bundle was built with.
+ const matching = parseRequestedBudgets({ maxEntities: 50, maxEvidence: 25 });
+ expect(diffInvestigations(stored, fresh, matching).budgets.requestedApplied).toBe(true);
});
- it("treats whitespace, empty, or non-numeric --max-* strings as not provided", () => {
- // parseRequestedBudgets must mirror commander semantics: only flag-shaped
- // arguments count as "user override", not noise from shell quoting or
- // accidental empty strings. This is what stops the diff output from
- // reporting a phantom override. Numeric "0" is a real override (someone
- // asking for "0 entities" forces an empty bundle and is what they meant),
- // so it survives the parse — but non-strings, blanks, and NaN-producing
- // tokens do not.
+ it("records exactly the --max-* flags that were passed", () => {
+ // Validation lives in `parseBudgetOption`, the flags' Commander argParser,
+ // so anything arriving here is already a positive integer. What is left is
+ // "which flags were given", and an absent one must not become a phantom
+ // override in the report.
expect(parseRequestedBudgets({})).toBeUndefined();
- expect(parseRequestedBudgets({ maxEntities: "", maxEvidence: " " })).toBeUndefined();
expect(parseRequestedBudgets({ maxEntities: undefined })).toBeUndefined();
- expect(parseRequestedBudgets({ maxEntities: "abc" })).toBeUndefined();
- expect(parseRequestedBudgets({ maxEntities: "0" })).toEqual({ maxEntities: 0 });
- expect(parseRequestedBudgets({ maxEntities: "10", maxChars: undefined })).toEqual({ maxEntities: 10 });
- const partial = parseRequestedBudgets({ maxEntities: "10", maxEvidence: "5", maxRelationships: "0", maxChars: "12000" });
- expect(partial).toEqual({ maxEntities: 10, maxEvidence: 5, maxRelationships: 0, maxChars: 12000 });
+ expect(parseRequestedBudgets({ maxEntities: 10, maxChars: undefined })).toEqual({ maxEntities: 10 });
+ expect(
+ parseRequestedBudgets({ maxEntities: 10, maxEvidence: 5, maxRelationships: 1, maxChars: 12000 }),
+ ).toEqual({ maxEntities: 10, maxEvidence: 5, maxRelationships: 1, maxChars: 12000 });
});
it("renders the budget block in --diff text and llm output", () => {
@@ -502,9 +517,13 @@ describe("ix context investigation state", () => {
text.restore();
}
expect(text.lines.some((l) => l.includes("budgets:"))).toBe(true);
- expect(text.lines.some((l) => l.includes("saved :"))).toBe(true);
- expect(text.lines.some((l) => l.includes("requested :")) && text.lines.some((l) => l.includes("evidence=25"))).toBe(true);
- expect(text.lines.some((l) => l.includes("effective :") && l.includes("evidence=2"))).toBe(true);
+ expect(text.lines.some((l) => l.includes("saved :") && l.includes("evidence=2"))).toBe(true);
+ // One `some`, not two ANDed: `A.some(requested) && A.some(evidence=25)`
+ // passes when `evidence=25` lands on any line at all — the `saved` or
+ // `effective` line satisfied it — so it survived a `requested` line reading
+ // `evidence=not-given`, and on failure said only "expected false to be true".
+ expect(text.lines.some((l) => l.includes("requested :") && l.includes("evidence=25"))).toBe(true);
+ expect(text.lines.some((l) => l.includes("effective :") && l.includes("evidence=25"))).toBe(true);
const llm = capture();
try {
@@ -513,11 +532,11 @@ describe("ix context investigation state", () => {
llm.restore();
}
// Records, not the prose block with the colons moved. `scope=requested`
- // carries `applied=false` so the precedence rule — saved budgets govern
+ // carries `applied=` so the precedence rule — saved budgets govern
// --diff — is a field an agent can test rather than a sentence to read.
expect(llm.lines).toContain("budgets scope=saved entities=5 relationships=1 evidence=2 chars=12000");
- expect(llm.lines).toContain("budgets scope=requested evidence=25 applied=false");
- expect(llm.lines).toContain("budgets scope=effective entities=5 relationships=1 evidence=2 chars=12000");
+ expect(llm.lines).toContain("budgets scope=requested evidence=25 applied=true");
+ expect(llm.lines).toContain("budgets scope=effective entities=50 relationships=100 evidence=25 chars=12000");
// And none of the prose survives into the record stream.
expect(llm.lines.some((l) => l.includes(":") && l.startsWith(" "))).toBe(false);
@@ -533,7 +552,10 @@ describe("ix context investigation state", () => {
const parsed = JSON.parse(json.lines[0]);
expect(parsed.budgets.saved).toEqual(saved.budgets);
expect(parsed.budgets.requested).toEqual(requested);
- expect(parsed.budgets.effective).toEqual(saved.budgets);
+ expect(parsed.budgets.effective).toEqual(fresh.budgets);
+ // The same fact the llm record carries as `applied=`, so a JSON consumer
+ // does not have to string-match an English sentence for it.
+ expect(parsed.budgets.requestedApplied).toBe(true);
});
// `--diff --format llm` used to fall through to the prose renderer, because
@@ -563,9 +585,15 @@ describe("ix context investigation state", () => {
const lines = captureLog(() => renderInvestigationDiff(stored, fresh, "llm"));
- expect(lines[0]).toBe(
- "diff investigation=widget-llm target=Widget freshness_previous=current freshness_current=current",
- );
+ // `saved_at` and `generated_at` are on the record because
+ // `freshness_previous=current` says the snapshot was fresh when it was
+ // taken and not when that was: a baseline from five minutes ago and one
+ // from three months ago read identically without them.
+ const [header] = lines;
+ expect(header).toContain("diff investigation=widget-llm target=Widget");
+ expect(header).toContain(`saved_at=${stored.savedAt}`);
+ expect(header).toMatch(/generated_at=\d{4}-\d{2}-\d{2}T[\d:.]+Z/);
+ expect(header).toContain("freshness_previous=current freshness_current=current");
// Zero is the answer to the question --diff was asked, so it is carried
// rather than dropped as a default.
expect(lines).toContain(
@@ -637,14 +665,25 @@ describe("ix context investigation state", () => {
// The change is a field, not a prefix fused to the record kind, so a
// consumer routing on `entity` matches both sides of the comparison.
- expect(lines).toContain("entity change=added kind=method name=mount");
+ // `id=` is what makes the stream joinable: the relationship records below
+ // name their endpoints by entity id, so without it `dst=entity-3`
+ // resolves to nothing the reader has seen.
+ expect(lines).toContain(
+ "entity change=added id=entity-3 kind=method name=mount path=src/widget.ts",
+ );
expect(lines).toContain("relationship change=removed src=entity-1 pred=calls dst=entity-2");
expect(lines).toContain("relationship change=added src=entity-1 pred=holds dst=entity-3");
// A claim id carries the statement, so it contains spaces — quoted, per
// docs/llm-format.md. Unquoted, `id=claim-mounts to DOM` is three tokens
// and a consumer reads the id as `claim-mounts`.
- expect(lines).toContain('claim change=added id="claim-mounts to DOM" status=active');
+ // `statement=` is the field that says what changed. In production the id
+ // is the backend's (`c-8f31a2`), so a record carrying only the id told a
+ // reader that a claim changed and not what it says; this fixture's
+ // `claim-<statement>` ids are what hid that.
+ expect(lines).toContain(
+ 'claim change=added id="claim-mounts to DOM" entity=entity-1 status=active statement="mounts to DOM"',
+ );
// An evidence title is a sentence. Same rule, and the reason the value
// must never be built with a template literal.
@@ -659,6 +698,56 @@ describe("ix context investigation state", () => {
for (const line of lines) expect(line).not.toContain("\n");
});
+ it("answers a refusal with a record, not a prose warning", () => {
+ // The refusal path wrote `renderWarning`, which is console.log, so the
+ // one command being made llm-clean answered `--diff nope --format llm`
+ // with a chalk-coloured English sentence in the middle of the record
+ // stream. Every sibling command emits `error code=... message="..."`.
+ const out: string[] = [];
+ const err: string[] = [];
+ const origLog = console.log;
+ const origErr = console.error;
+ console.log = (...a: unknown[]) => void out.push(a.map(String).join(" "));
+ console.error = (...a: unknown[]) => void err.push(a.map(String).join(" "));
+ try {
+ expect(loadInvestigation("does-not-exist", "llm")).toBeUndefined();
+ } finally {
+ console.log = origLog;
+ console.error = origErr;
+ }
+ expect(out).toHaveLength(1);
+ expect(out[0]).toMatch(/^error code=no_saved_investigation message="No saved investigation/);
+ // One record on one line, with the path quoted rather than bare.
+ expect(out[0]).not.toContain("\n");
+ expect(err).toEqual([]);
+ expect(process.exitCode).toBe(1);
+ process.exitCode = undefined;
+ });
+
+ it("emits one grammar for `evidence`, whichever ix context surface produced it", () => {
+ // `renderBundle` built `evidence 30 relationship <title>` from a template
+ // literal: positional, unquoted, newlines stripped and nothing else. An
+ // evidence title is a sentence, so every one of those records split into
+ // tokens — while `--diff` emitted the keyed, quoted form for the same
+ // record kind from the same command.
+ const bundle = bundleWith([makeClaim("renders to DOM", 0.9)]);
+ const lines = captureLog(() => renderBundle(bundle, "llm"));
+
+ const evidence = lines.filter((l) => l.startsWith("evidence"));
+ expect(evidence.length).toBeGreaterThan(0);
+ for (const line of evidence) {
+ expect(line).toMatch(/^evidence score=\d+ kind=[a-z]+ title=/);
+ }
+ // The exact record `--diff` would emit for the same item, minus `change=`.
+ expect(lines).toContain(
+ 'evidence score=30 kind=relationship title="entity-1 --calls--> entity-2"',
+ );
+ // And the header is a record too, not fifteen bare `key=value` lines
+ // built by interpolation — `target=${name}` breaks on any name with a
+ // space in it.
+ expect(lines[0]).toMatch(/^context target=Widget target_kind=class /);
+ });
+
it("does not regress the prose (text) renderer", () => {
const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);
saveInvestigation("widget-llm-text", saved);
diff --git a/ix-cli/src/cli/__tests__/context-pick-validation.test.ts b/ix-cli/src/cli/__tests__/context-pick-validation.test.ts
index 58851153..70c988f6 100644
--- a/ix-cli/src/cli/__tests__/context-pick-validation.test.ts
+++ b/ix-cli/src/cli/__tests__/context-pick-validation.test.ts
@@ -63,3 +63,65 @@ describe("ix context --pick validation", () => {
});
});
});
+
+/**
+ * The `--max-*` flags now validate at parse time too, for a sharper reason than
+ * `--pick` does: `ix context --diff` reports the requested budget back to the
+ * caller. Reading the raw option string back out with `Number.parseInt` — which
+ * is what this replaces — is not a check. It reads `"10abc"` as 10, `"0x10"` as
+ * 0, `"1e3"` as 1 and `"-5"` as -5, so `--max-entities 1e3` was reported as
+ * `budgets scope=requested entities=1 applied=false`: a request the user never
+ * made, on the one record whose whole purpose is saying what they asked for.
+ */
+describe("ix context --max-* validation", () => {
+ beforeEach(() => {
+ resolveFileOrEntity.mockReset().mockResolvedValue(undefined);
+ });
+
+ it.each(["10abc", "0x10", "1e3", "-5", "0", "3.5", "", " "])(
+ "rejects %j before building anything",
+ async (value) => {
+ const result = await runContext(["--max-entities", value]);
+
+ expect(result.error?.exitCode).toBe(1);
+ expect(result.stderr).toContain("must be a positive integer");
+ expect(resolveFileOrEntity).not.toHaveBeenCalled();
+ },
+ );
+
+ it.each(["--max-relationships", "--max-evidence", "--max-chars"])(
+ "applies the same rule to %s",
+ async (flag) => {
+ expect((await runContext([flag, "10abc"])).error?.exitCode).toBe(1);
+ expect((await runContext([flag, "1000"])).error).toBeUndefined();
+ },
+ );
+
+ it("still tells the user each flag's default and range", async () => {
+ // Removing the Commander defaults is what lets an absent flag be told apart
+ // from one set to the default value — but it also removed `(default: "50")`
+ // from `--help`, leaving four flags whose default a user could not discover
+ // from the CLI at all while `--format` still showed its own.
+ const program = new Command().name("ix").exitOverride();
+ registerContextCommand(program);
+ const help = program.commands.find((c) => c.name() === "context")!.helpInformation();
+
+ // Whitespace-flattened: commander pads to a column and wraps a long
+ // description onto the next line, so a per-line search finds the flag on
+ // one line and its range on another. Flattening keeps the assertion about
+ // which text belongs to which flag, which is the whole point of it.
+ const flat = help.replace(/\s+/g, " ");
+ for (const [flag, text, fallback, min, max] of [
+ ["--max-entities", "Maximum entities in the bundle", 50, 1, 500],
+ ["--max-relationships", "Maximum relationships in the bundle", 100, 1, 1000],
+ ["--max-evidence", "Maximum evidence items in the bundle", 25, 1, 200],
+ ["--max-chars", "Maximum characters of evidence output", 12000, 1000, 1000000],
+ ] as const) {
+ // One assertion per flag, so a failure names which one lost its default
+ // rather than reporting that some string was missing from a wall of help.
+ expect(flat, `help for ${flag}`).toContain(
+ `${flag} <n> ${text} (default: ${fallback}, clamped to ${min}-${max})`,
+ );
+ }
+ });
+});
diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.ts
index be4ebf6f..6684996a 100644
--- a/ix-cli/src/cli/commands/context.ts
+++ b/ix-cli/src/cli/commands/context.ts
@@ -19,22 +19,79 @@ import type {
} from "../../client/types.js";
import { getEndpoint } from "../config.js";
import { collectFacts, type EntityFacts } from "../explain/facts.js";
-import { llmLine, printLlmLines, reportModeConflict } from "../llm.js";
-import { parsePickOption } from "../options.js";
+import { llmError, llmLine, printLlmLines, reportModeConflict } from "../llm.js";
+import { parseBudgetOption, parsePickOption } from "../options.js";
import { resolveFileOrEntity } from "../resolve.js";
import { createStaleProbe } from "../stale.js";
import { renderNote, renderSection, renderWarning } from "../ui.js";
-interface ContextOptions {
+/** The four `--max-*` knobs that bound a bundle. */
+interface BudgetSnapshot {
+ maxEntities: number;
+ maxRelationships: number;
+ maxEvidence: number;
+ maxChars: number;
+}
+
+/**
+ * The four budgets, described once: flag key, output label, clamp range, and
+ * the default applied when the flag is absent.
+ *
+ * These four facts used to live in five hand-maintained places -- the option
+ * registration, the `clampInt` calls, the record fields, the prose formatter
+ * and the requested-budget reader -- so a fifth budget meant five edits and
+ * missing one was silent. They had already drifted: a comment on the
+ * registration described `clampInt(opts.max*, 1, 500, 50)` as if it were the
+ * rule for all four, which is right for entities and wrong for the rest
+ * (`--max-chars` is 1000-1000000 defaulting to 12000). Everything below reads
+ * this table, and `--help` interpolates it, so the number a user is told is
+ * the number that is applied.
+ */
+const BUDGETS = [
+ { key: "maxEntities", label: "entities", help: "Maximum entities in the bundle", min: 1, max: 500, fallback: 50 },
+ { key: "maxRelationships", label: "relationships", help: "Maximum relationships in the bundle", min: 1, max: 1000, fallback: 100 },
+ { key: "maxEvidence", label: "evidence", help: "Maximum evidence items in the bundle", min: 1, max: 200, fallback: 25 },
+ { key: "maxChars", label: "chars", help: "Maximum characters of evidence output", min: 1000, max: 1_000_000, fallback: 12_000 },
+] as const satisfies ReadonlyArray<{
+ key: keyof BudgetSnapshot;
+ label: string;
+ help: string;
+ min: number;
+ max: number;
+ fallback: number;
+}>;
+
+/**
+ * `--help` text for one budget flag.
+ *
+ * The Commander defaults were removed so an absent flag is distinguishable
+ * from one set to the default value -- `--diff` reports which budgets the
+ * caller actually asked for. Removing them also removed `(default: "50")` from
+ * `ix context --help`, leaving four flags whose default and range a user could
+ * not discover from the CLI at all, so the text says both, read off the table
+ * that enforces them.
+ */
+function budgetHelp(key: keyof BudgetSnapshot): string {
+ const b = BUDGETS.find((entry) => entry.key === key)!;
+ return `${b.help} (default: ${b.fallback}, clamped to ${b.min}-${b.max})`;
+}
+
+/** Apply the table's range and default to whatever the caller supplied. */
+function clampBudgets(opts: Partial<BudgetSnapshot>): BudgetSnapshot {
+ const out = {} as BudgetSnapshot;
+ for (const b of BUDGETS) {
+ const raw = opts[b.key];
+ out[b.key] = raw === undefined ? b.fallback : Math.min(b.max, Math.max(b.min, raw));
+ }
+ return out;
+}
+
+interface ContextOptions extends Partial<BudgetSnapshot> {
kind?: string;
path?: string;
pick?: number;
depth?: string;
asOfRev?: string;
- maxEntities?: string;
- maxRelationships?: string;
- maxEvidence?: string;
- maxChars?: string;
out?: string;
save?: string;
resume?: string;
@@ -88,7 +145,7 @@ interface ContextBundle {
};
freshness: { stale: boolean; classification: "current" | "stale" | "unverified" };
evidence: EvidenceItem[];
- budgets: { maxEntities: number; maxRelationships: number; maxEvidence: number; maxChars: number };
+ budgets: BudgetSnapshot;
truncation: {
entitiesTruncated: number;
relationshipsTruncated: number;
@@ -122,14 +179,15 @@ export function registerContextCommand(program: Command): void {
.option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption)
.option("--depth <depth>", "Context-graph expansion depth")
.option("--as-of-rev <n>", "Historical context as of a graph revision")
- // The --max-* flags default to undefined rather than "50"/"100"/etc. so
- // parseRequestedBudgets can tell whether the user actually supplied an
- // override on the command line. The numeric defaults are still applied at
- // build time via clampInt(opts.max*, 1, 500, 50).
- .option("--max-entities <n>", "Maximum entities in the bundle")
- .option("--max-relationships <n>", "Maximum relationships in the bundle")
- .option("--max-evidence <n>", "Maximum evidence items in the bundle")
- .option("--max-chars <n>", "Maximum characters of evidence output")
+ // No Commander default on the --max-* flags, so `parseRequestedBudgets`
+ // can tell an absent flag from one set to the default value. The defaults
+ // and ranges are the BUDGETS table's, applied by `clampBudgets` and shown
+ // in the help text by `budgetHelp` -- they differ per flag, so there is no
+ // single pair to name here.
+ .option("--max-entities <n>", budgetHelp("maxEntities"), parseBudgetOption)
+ .option("--max-relationships <n>", budgetHelp("maxRelationships"), parseBudgetOption)
+ .option("--max-evidence <n>", budgetHelp("maxEvidence"), parseBudgetOption)
+ .option("--max-chars <n>", budgetHelp("maxChars"), parseBudgetOption)
.option("--format <fmt>", "Output format (text|json|llm)", "text")
.option("--out <path>", "Write the JSON bundle to this file instead of stdout")
.option("--save <id>", "Persist the bundle as a resumable investigation state")
@@ -159,13 +217,13 @@ export function registerContextCommand(program: Command): void {
return;
}
if (opts.diff) {
- const saved = loadInvestigation(opts.diff);
+ const saved = loadInvestigation(opts.diff, opts.format);
if (!saved) return;
- // The fresh side of --diff is currently built with the saved investigation's
- // own budgets (ix-cli/src/cli/commands/context.ts: `buildFreshBundle(..., saved.bundle.budgets)`),
- // so any --max-* flags the user passes on the CLI are not applied to the
- // fresh bundle. We capture the requested values separately so the diff output
- // can surface them to humans and agents instead of silently dropping them.
+ // The fresh side of --diff is built with the saved investigation's own
+ // budgets, the argument to `buildFreshBundle` below, so any --max-*
+ // flags the caller passed are not applied to it. Captured here so the
+ // diff output can report what was asked for instead of dropping it
+ // silently; what actually governed is read back off the built bundle.
const requestedBudgets = parseRequestedBudgets(opts);
const fresh = await buildFreshBundle(
target ?? saved.bundle.target.name,
@@ -191,10 +249,7 @@ export function registerContextCommand(program: Command): void {
if (!resolved) return;
const asOfRev = opts.asOfRev ? parseInt(opts.asOfRev, 10) : undefined;
- const maxEntities = clampInt(opts.maxEntities, 1, 500, 50);
- const maxRelationships = clampInt(opts.maxRelationships, 1, 1000, 100);
- const maxEvidence = clampInt(opts.maxEvidence, 1, 200, 25);
- const maxChars = clampInt(opts.maxChars, 1000, 1_000_000, 12_000);
+ const budgets = clampBudgets(opts);
const [facts, context, provenance] = await Promise.all([
collectFacts(client, resolved.id, resolved.name, resolved.kind),
@@ -212,7 +267,7 @@ export function registerContextCommand(program: Command): void {
provenance,
asOfRev,
depth: opts.depth,
- budgets: { maxEntities, maxRelationships, maxEvidence, maxChars },
+ budgets,
});
if (opts.save) {
@@ -268,7 +323,7 @@ export function registerContextCommand(program: Command): void {
async function buildFreshBundle(
target: string,
opts: { kind?: string; path?: string; pick?: number; depth?: string; asOfRev?: string },
- budgets: { maxEntities: number; maxRelationships: number; maxEvidence: number; maxChars: number },
+ budgets: BudgetSnapshot,
): Promise<ContextBundle | undefined> {
const client = new IxClient(getEndpoint());
const resolved = await resolveFileOrEntity(client, target, {
@@ -664,16 +719,25 @@ export function renderInvestigationList(
* `--resume`/`--diff` can tell a refusal from a successful render. The sibling
* commands (config, init, map) already signal refusals this way.
*/
-function refuseInvestigation(message: string): undefined {
- renderWarning(message);
+function refuseInvestigation(code: string, message: string, format?: string): undefined {
+ // `--format llm` gets the record every sibling command emits for a failure
+ // (`callers.ts`, `contains.ts`, `depends.ts`, `diff.ts`, `history.ts` all do
+ // this, and docs/llm-format.md specifies the shape). This path used to write
+ // `renderWarning`, which is `console.log`, so the one command being made
+ // llm-clean answered a refusal with a chalk-coloured prose line in the middle
+ // of the record stream — and with a prose line inside the JSON payload for a
+ // `--format json` caller piping to `jq`. The human keeps the same wording, on
+ // stderr, where prose belongs whatever the format.
+ if (format === "llm") console.log(llmError(code, message));
+ else console.error(` Warning ${message}`);
process.exitCode = 1;
return undefined;
}
-export function loadInvestigation(id: string): SavedInvestigation | undefined {
+export function loadInvestigation(id: string, format?: string): SavedInvestigation | undefined {
const path = investigationPath(id);
if (!existsSync(path)) {
- return refuseInvestigation(`No saved investigation "${id}" at ${path}`);
+ return refuseInvestigation("no_saved_investigation", `No saved investigation "${id}" at ${path}`, format);
}
let raw: unknown;
// Scoped to the read and the parse: those are the only calls here that throw,
@@ -682,7 +746,7 @@ export function loadInvestigation(id: string): SavedInvestigation | undefined {
try {
raw = JSON.parse(readFileSync(path, "utf8"));
} catch {
- return refuseInvestigation(`Saved investigation "${id}" is not valid JSON; refusing to resume.`);
+ return refuseInvestigation("invalid_saved_investigation", `Saved investigation "${id}" is not valid JSON; refusing to resume.`, format);
}
// Validate the whole envelope coming back off disk against the same versioned
@@ -699,15 +763,19 @@ export function loadInvestigation(id: string): SavedInvestigation | undefined {
// Distinguish the two version-skew cases from a generic shape mismatch, so
// the warning names which contract was not met.
if (issues.some((issue) => issue.path[0] === "schema")) {
- return refuseInvestigation(`Saved investigation "${id}" has an unknown schema; refusing to resume.`);
+ return refuseInvestigation("invalid_saved_investigation", `Saved investigation "${id}" has an unknown schema; refusing to resume.`, format);
}
if (issues.some((issue) => issue.path[0] === "bundle" && issue.path[1] === "schema")) {
return refuseInvestigation(
+ "invalid_saved_investigation",
`Saved investigation "${id}" holds a bundle from a different contract than ${BUNDLE_SCHEMA}; refusing to resume.`,
+ format,
);
}
return refuseInvestigation(
+ "invalid_saved_investigation",
`Saved investigation "${id}" does not match the ${BUNDLE_SCHEMA} schema (${issues.length} issue(s)); refusing to resume.`,
+ format,
);
}
// Return the validated value, not the raw parse: saveInvestigation persists
@@ -724,23 +792,26 @@ export function loadInvestigation(id: string): SavedInvestigation | undefined {
}
function renderSavedInvestigation(id: string, format: string): void {
- const saved = loadInvestigation(id);
+ const saved = loadInvestigation(id, format);
if (!saved) return;
if (format === "json") {
console.log(JSON.stringify(saved, null, 2));
return;
}
- renderNote(`Resumed investigation "${saved.id}" saved ${saved.savedAt}`);
+ if (format === "llm") {
+ // A record, not the prose note below. `renderNote` would put a
+ // chalk-coloured English sentence at the head of a record stream, and
+ // it carries the one fact the bundle records do not: when this snapshot
+ // was taken. `classification=current` says it was fresh when it was
+ // saved, not when that was.
+ printLlmLines([llmLine("investigation", { id: unsanitizeId(saved.id), saved_at: saved.savedAt })]);
+ renderBundle(saved.bundle, format);
+ return;
+ }
+ renderNote(`Resumed investigation "${unsanitizeId(saved.id)}" saved ${saved.savedAt}`);
renderBundle(saved.bundle, format);
}
-interface BudgetSnapshot {
- maxEntities: number;
- maxRelationships: number;
- maxEvidence: number;
- maxChars: number;
-}
-
/**
* A budget snapshot as llm record fields.
*
@@ -748,48 +819,40 @@ interface BudgetSnapshot {
* override needs no `not-given` sentinel the way the prose form does.
*/
function budgetFields(b: Partial<BudgetSnapshot>): Record<string, number | undefined> {
- return {
- entities: b.maxEntities,
- relationships: b.maxRelationships,
- evidence: b.maxEvidence,
- chars: b.maxChars,
- };
+ return Object.fromEntries(BUDGETS.map((f) => [f.label, b[f.key]]));
}
/** Compact one-line representation of a budget snapshot for human rendering. */
function formatBudgets(b: Partial<BudgetSnapshot>, partial = false): string {
- const fmt = (val: number | undefined, key: string): string =>
- `${key}=${val === undefined ? "not-given" : String(val)}`;
- const segments = [
- fmt(b.maxEntities, "entities"),
- fmt(b.maxRelationships, "relationships"),
- fmt(b.maxEvidence, "evidence"),
- fmt(b.maxChars, "chars"),
- ].join(" ");
+ const segments = BUDGETS.map((f) => {
+ const val = b[f.key];
+ return `${f.label}=${val === undefined ? "not-given" : String(val)}`;
+ }).join(" ");
return partial ? `${segments} (CLI override; not applied to --diff fresh side)` : segments;
}
/**
- * Read the raw `--max-*` strings commander collected into numbers.
+ * Which `--max-*` flags the caller actually passed, or `undefined` for none.
*
- * Deliberately *not* clamped, unlike the action handler's `clampInt` calls for
- * a direct run: these values are reported, never applied — saved budgets
- * govern `--diff` — so clamping them would misreport what the caller actually
- * asked for. If they are ever made to win on the fresh side, they must be
- * clamped at that point, and the ranges live in the handler.
+ * Validation happens once, at parse time: `parseBudgetOption` is the flags'
+ * Commander `argParser`, so a value that reaches here is already a positive
+ * integer. Reading the raw strings back out with `Number.parseInt` was not a
+ * check — it took `"10abc"` as 10, `"1e3"` as 1 and `"-5"` as -5, and this
+ * record's whole purpose is reporting what the caller asked for, so a silently
+ * repaired number is the one error it cannot afford.
*
- * An absent or whitespace-only string means the flag was not passed.
+ * Deliberately *not* clamped, unlike `clampBudgets` on a direct run: these
+ * values are reported, never applied — saved budgets govern `--diff` — so
+ * clamping them would report a budget the caller did not ask for either. If
+ * they are ever made to win on the fresh side, they must be clamped there.
*/
-export function parseRequestedBudgets(opts: Partial<ContextOptions>): Partial<BudgetSnapshot> | undefined {
- const fields: Array<keyof BudgetSnapshot> = ["maxEntities", "maxRelationships", "maxEvidence", "maxChars"];
+export function parseRequestedBudgets(opts: Partial<BudgetSnapshot>): Partial<BudgetSnapshot> | undefined {
const out: Partial<BudgetSnapshot> = {};
let provided = false;
- for (const key of fields) {
- const raw = opts[key] as string | undefined;
- if (typeof raw !== "string" || raw.trim() === "") continue;
- const parsed = Number.parseInt(raw, 10);
- if (!Number.isFinite(parsed)) continue;
- out[key] = parsed;
+ for (const f of BUDGETS) {
+ const value = opts[f.key];
+ if (value === undefined) continue;
+ out[f.key] = value;
provided = true;
}
return provided ? out : undefined;
@@ -814,11 +877,18 @@ export function diffInvestigations(
const addedClaims = fresh.claims.filter((c) => !prev.claims.some((p) => p.id === c.id));
const removedClaims = prev.claims.filter((p) => !fresh.claims.some((c) => c.id === p.id));
- // Surface the silent "saved budgets govern --diff" precedence as data instead
- // of hiding it. Today `effective` always equals `saved`; if a future change
- // ever lets CLI overrides win on the fresh side, this block is the single
- // place that flips and the diff output is the only observable truth.
- const effective: BudgetSnapshot = { ...saved.bundle.budgets };
+ // Read off the bundle that was actually built, not restated from the
+ // argument that built it. `{ ...saved.bundle.budgets }` would assert how the
+ // fresh side was constructed rather than report it: today the two agree, but
+ // letting CLI overrides win would mean editing the `buildFreshBundle` call in
+ // the action handler, and `effective` would go on reporting the saved budget
+ // while the fresh side used another one -- the silent misreport this record
+ // exists to prevent. `ContextBundle.budgets` records the truth on both sides.
+ const effective: BudgetSnapshot = { ...fresh.budgets };
+ // Whether the caller's --max-* flags governed the fresh side. Derived by
+ // comparison rather than hardcoded false, for the same reason.
+ const requestedApplied = requestedBudgets !== undefined
+ && BUDGETS.every((f) => requestedBudgets[f.key] === undefined || requestedBudgets[f.key] === effective[f.key]);
return {
schema: "ix-investigation-diff/1",
@@ -831,12 +901,18 @@ export function diffInvestigations(
saved: saved.bundle.budgets,
requested: requestedBudgets,
effective,
- // The note exists so an agent reading the JSON alone can tell why a
- // --max-* flag it passed on the CLI did not change the comparison
- // footprint, without having to read source to find the precedence rule.
- note: requestedBudgets
- ? "Saved investigation budgets govern --diff; --max-* flags on the CLI are recorded above for transparency but not applied to the fresh side."
- : "Saved investigation budgets govern --diff; no --max-* overrides were supplied on the CLI.",
+ // The same fact the llm record carries as `applied=`. It was prose only
+ // here, so a JSON consumer had to string-match a sentence whose wording
+ // changed with the case, while the llm consumer got a boolean it could
+ // test. One contract, both formats.
+ requestedApplied,
+ // Prose for the human reading the JSON, and only when there is something
+ // to explain: without --max-* flags the sentence said nothing.
+ ...(requestedBudgets
+ ? {
+ note: "Saved investigation budgets govern --diff; the --max-* flags recorded here were not applied to the fresh side.",
+ }
+ : {}),
},
added: {
entities: addedEntities,
@@ -864,12 +940,63 @@ interface InvestigationDiff {
saved: BudgetSnapshot;
requested?: Partial<BudgetSnapshot>;
effective: BudgetSnapshot;
- note: string;
+ /** Did `requested` govern the fresh side? The testable form of `note`. */
+ requestedApplied: boolean;
+ /** Present only when `requested` is: without it there is nothing to explain. */
+ note?: string;
};
added: { entities: ContextBundle["entities"]; relationships: ContextBundle["relationships"]; evidence: EvidenceItem[]; claims: ContextBundle["claims"] };
removed: { entities: ContextBundle["entities"]; relationships: ContextBundle["relationships"]; evidence: EvidenceItem[]; claims: ContextBundle["claims"] };
}
+/** Which side of a comparison a record is on, or neither for a plain bundle. */
+type RecordChange = "added" | "removed" | undefined;
+
+/**
+ * The `entity`, `evidence` and `claim` records, built in one place.
+ *
+ * `ix context <target> --format llm` and `ix context --diff <id> --format llm`
+ * are the same command and emitted two different grammars for the same record
+ * kind: the bundle renderer built `evidence 30 relationship <title>` from a
+ * template literal, positional and unquoted, so a title with a space in it —
+ * which is every title — split into tokens no consumer could reassemble. These
+ * builders are the keyed form, and `llmQuote` handles the spaces and newlines.
+ *
+ * `change` is dropped when absent (`llmField` drops nullish), so the plain
+ * bundle emits the same record without it.
+ */
+function entityRecord(change: RecordChange) {
+ return (e: ContextBundle["entities"][number]): string =>
+ llmLine("entity", {
+ change,
+ // Relationship records name their endpoints by entity id, so this is
+ // what lets a reader resolve `src=`/`dst=` to something it has seen.
+ id: e.id,
+ kind: e.kind,
+ name: e.name,
+ path: e.path,
+ // Only when true: `stale=false` on every entity is noise, and `llmField`
+ // renders a boolean rather than dropping it.
+ stale: e.stale || undefined,
+ });
+}
+
+function evidenceRecord(change: RecordChange) {
+ return (e: EvidenceItem): string =>
+ llmLine("evidence", { change, score: e.score, kind: e.kind, title: e.title });
+}
+
+function claimRecord(change: RecordChange) {
+ return (c: ContextBundle["claims"][number]): string =>
+ llmLine("claim", {
+ change,
+ id: c.id,
+ entity: c.entityId,
+ status: c.status,
+ statement: c.statement,
+ });
+}
+
export function renderInvestigationDiff(
saved: SavedInvestigation,
fresh: ContextBundle,
@@ -897,19 +1024,32 @@ export function renderInvestigationDiff(
// record per line invariant.
printLlmLines([
llmLine("diff", {
- investigation: saved.id,
+ investigation: unsanitizeId(saved.id),
target: fresh.target.name,
+ // How old the saved side is. `freshness_previous=current` says the
+ // snapshot was fresh when it was taken, not when that was — and a
+ // snapshot from five minutes ago and one from three months ago are the
+ // same word. Both timestamps are on the JSON diff; only the prose
+ // renderer showed them, so the llm stream was the one surface that
+ // could not tell how stale the comparison's own baseline is.
+ saved_at: diff.savedAt,
+ generated_at: diff.generatedAt,
freshness_previous: prev.freshness.classification,
freshness_current: fresh.freshness.classification,
}),
// Which budgets governed the comparison. `scope=requested` appears
- // only when --max-* flags were passed, and carries `applied=false`
- // rather than a sentence explaining itself: the precedence rule is
- // that saved budgets govern --diff, and a field an agent can test
- // beats a note it has to read.
+ // only when --max-* flags were passed, and carries `applied=` rather
+ // than a sentence explaining itself: the precedence rule is that saved
+ // budgets govern --diff, and a field an agent can test beats a note it
+ // has to read. `effective` is read off the bundle that was built, so it
+ // is a report and not a restatement of `saved`.
llmLine("budgets", { scope: "saved", ...budgetFields(diff.budgets.saved) }),
...(diff.budgets.requested
- ? [llmLine("budgets", { scope: "requested", ...budgetFields(diff.budgets.requested), applied: false })]
+ ? [llmLine("budgets", {
+ scope: "requested",
+ ...budgetFields(diff.budgets.requested),
+ applied: diff.budgets.requestedApplied,
+ })]
: []),
llmLine("budgets", { scope: "effective", ...budgetFields(diff.budgets.effective) }),
// One record rather than eight, and the zeros are kept: "nothing was
@@ -928,14 +1068,25 @@ export function renderInvestigationDiff(
// `change=` rather than a `+`/`-` prefix on the record kind: a consumer
// routing on the kind should still match `entity` on both sides of the
// comparison, and a fused marker means it matches neither.
- ...diff.added.entities.map((e) => llmLine("entity", { change: "added", kind: e.kind, name: e.name })),
- ...diff.removed.entities.map((e) => llmLine("entity", { change: "removed", kind: e.kind, name: e.name })),
+ //
+ // `id=` on entities is what makes the stream joinable. Relationship
+ // records name their endpoints by entity id, so without it
+ // `relationship src=entity-1 dst=entity-2` resolves to nothing a reader
+ // has seen and an added entity cannot be matched to the edge that
+ // involves it. `--format json` loses none of this, and llm carrying less
+ // than the format it is meant to replace is the wrong trade.
+ ...diff.added.entities.map(entityRecord("added")),
+ ...diff.removed.entities.map(entityRecord("removed")),
...diff.added.relationships.map((r) => llmLine("relationship", { change: "added", src: r.src, pred: r.predicate, dst: r.dst })),
...diff.removed.relationships.map((r) => llmLine("relationship", { change: "removed", src: r.src, pred: r.predicate, dst: r.dst })),
- ...diff.added.evidence.map((e) => llmLine("evidence", { change: "added", score: e.score, kind: e.kind, title: e.title })),
- ...diff.removed.evidence.map((e) => llmLine("evidence", { change: "removed", score: e.score, kind: e.kind, title: e.title })),
- ...diff.added.claims.map((c) => llmLine("claim", { change: "added", id: c.id, status: c.status })),
- ...diff.removed.claims.map((c) => llmLine("claim", { change: "removed", id: c.id, status: c.status })),
+ ...diff.added.evidence.map(evidenceRecord("added")),
+ ...diff.removed.evidence.map(evidenceRecord("removed")),
+ // `statement=` is the field that says what changed. The id is the
+ // backend's (`c-8f31a2`), so `claim change=added id=c-8f31a2
+ // status=active` told a reader that a claim changed and not what it
+ // says. The test fixture hid it by fabricating `claim-<statement>` ids.
+ ...diff.added.claims.map(claimRecord("added")),
+ ...diff.removed.claims.map(claimRecord("removed")),
]);
return;
}
@@ -983,7 +1134,7 @@ interface BuildInput {
provenance: unknown;
asOfRev?: number;
depth?: string;
- budgets: { maxEntities: number; maxRelationships: number; maxEvidence: number; maxChars: number };
+ budgets: BudgetSnapshot;
/**
* Per-entity staleness probe. Injected so buildBundle stays a pure function
* under test; production passes nothing and gets the real baseline-backed one.
@@ -1248,31 +1399,42 @@ function rankEvidence(input: {
return items.sort((a, b) => a.score - b.score || cmp(a.id, b.id));
}
-function renderBundle(bundle: ContextBundle, format: string): void {
+export function renderBundle(bundle: ContextBundle, format: string): void {
if (format === "json") {
console.log(JSON.stringify(bundle, null, 2));
return;
}
if (format === "llm") {
+ // Every line through `llmLine`, none through a template literal. This block
+ // built `target=${name}` and `evidence 30 relationship <title>` by
+ // interpolation: the first breaks on any name containing a space or an `=`,
+ // and the second is positional, unquoted, and breaks on every title, which
+ // is a sentence. `ix context --diff --format llm` emits the keyed form for
+ // the same record kinds, so a consumer routing on `evidence` from the same
+ // command was handed two grammars.
printLlmLines([
- `target=${bundle.target.name}`,
- `target_kind=${bundle.target.kind}`,
- `stale=${bundle.freshness.stale}`,
- `classification=${bundle.freshness.classification}`,
- `entities=${bundle.entities.length}`,
- `relationships=${bundle.relationships.length}`,
- `claims=${bundle.claims.length}`,
- `decisions=${bundle.decisions.length}`,
- `conflicts=${bundle.conflicts.length}`,
- `intents=${bundle.intents.length}`,
- `evidence=${bundle.evidence.length}`,
- `truncated_entities=${bundle.truncation.entitiesTruncated}`,
- `truncated_relationships=${bundle.truncation.relationshipsTruncated}`,
- `truncated_evidence=${bundle.truncation.evidenceTruncated}`,
- `truncated_chars=${bundle.truncation.charactersTruncated}`,
- ...bundle.evidence.map(
- (item) => `evidence ${item.score} ${item.kind} ${item.title.replaceAll("\n", " ")}`,
- ),
+ llmLine("context", {
+ target: bundle.target.name,
+ target_kind: bundle.target.kind,
+ stale: bundle.freshness.stale,
+ classification: bundle.freshness.classification,
+ entities: bundle.entities.length,
+ relationships: bundle.relationships.length,
+ claims: bundle.claims.length,
+ decisions: bundle.decisions.length,
+ conflicts: bundle.conflicts.length,
+ intents: bundle.intents.length,
+ evidence: bundle.evidence.length,
+ truncated_entities: bundle.truncation.entitiesTruncated,
+ truncated_relationships: bundle.truncation.relationshipsTruncated,
+ truncated_evidence: bundle.truncation.evidenceTruncated,
+ truncated_chars: bundle.truncation.charactersTruncated,
+ }),
+ // Evidence only, as before. The entity, relationship and claim lists are
+ // deliberately still counts here: `--format llm` is the token-minimal
+ // surface, the ranked evidence is what it exists to deliver, and
+ // `--format json` carries the rest for a caller that wants it.
+ ...bundle.evidence.map(evidenceRecord(undefined)),
]);
return;
}
@@ -1321,12 +1483,6 @@ function asString(value: unknown): string | undefined {
return typeof value === "string" ? value : undefined;
}
-function clampInt(raw: string | undefined, min: number, max: number, fallback: number): number {
- const parsed = raw ? parseInt(raw, 10) : NaN;
- if (Number.isNaN(parsed)) return fallback;
- return Math.min(max, Math.max(min, parsed));
-}
-
function cmp(a: string, b: string): number {
return a < b ? -1 : a > b ? 1 : 0;
}
diff --git a/ix-cli/src/cli/options.ts b/ix-cli/src/cli/options.ts
index 32732b4d..e76bd150 100644
--- a/ix-cli/src/cli/options.ts
+++ b/ix-cli/src/cli/options.ts
@@ -1,14 +1,42 @@
import { InvalidArgumentError } from "commander";
-export function parsePickOption(value: string): number {
+/**
+ * Parse a flag that must be a positive integer, rejecting anything else.
+ *
+ * The regex is the check; `Number` is only the conversion. `Number.parseInt`
+ * on its own is not a validator and never was: it reads `"10abc"` as 10,
+ * `"0x10"` as 0, `"1e3"` as 1 and `"-5"` as -5, so every one of those reaches
+ * the command as a value the caller never typed. `Number.isSafeInteger` then
+ * rejects the digit strings too large to survive the round trip.
+ *
+ * `example` is interpolated into the message so each flag can show a plausible
+ * value for itself; the wording is otherwise identical, because the rule is.
+ */
+function parsePositiveInt(value: string, example: string): number {
const normalized = value.trim();
- if (!/^\+?[1-9]\d*$/.test(normalized)) {
- throw new InvalidArgumentError("must be a positive integer (for example, 1 or 2)");
- }
+ const reject = () =>
+ new InvalidArgumentError(`must be a positive integer (for example, ${example})`);
+ if (!/^\+?[1-9]\d*$/.test(normalized)) throw reject();
const parsed = Number(normalized);
- if (!Number.isSafeInteger(parsed)) {
- throw new InvalidArgumentError("must be a positive integer (for example, 1 or 2)");
- }
+ if (!Number.isSafeInteger(parsed)) throw reject();
return parsed;
}
+
+export function parsePickOption(value: string): number {
+ return parsePositiveInt(value, "1 or 2");
+}
+
+/**
+ * Parse a `--max-*` budget flag.
+ *
+ * Validated at parse time rather than read back out of the raw option string
+ * later, so the value is parsed once and a malformed one is refused where the
+ * user can see which flag they mistyped. `ix context --diff` reports the
+ * requested budget back to the caller, and a silently repaired number
+ * (`--max-entities 1e3` becoming 1) is a misreport of the one thing that record
+ * exists to carry.
+ */
+export function parseBudgetOption(value: string): number {
+ return parsePositiveInt(value, "50");
+}