From 8a39eba24de1d192c141caf4293eb29d3dd2125a Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 31 Oct 2026 21:36:58 +0000 Subject: [PATCH] docs(impact): explain PDG budget failures --- docs/cli-reference.md | 2 +- docs/mcp-reference.md | 2 +- gitnexus/src/cli/i18n/en.ts | 2 +- gitnexus/src/cli/i18n/zh-CN.ts | 2 +- gitnexus/src/cli/index.ts | 2 +- gitnexus/src/mcp/tools.ts | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 8d2c5595d..3744c7c58 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -43,7 +43,7 @@ query: shared `--http` ran the batch in 7.7 s at a flat 517 MB, versus 30.0 s an You can also query the graph directly from the terminal — `gitnexus query`, `context`, `impact`, `trace`, `cypher`, `detect-changes`, and `check` mirror the MCP tools of the same names, and `gitnexus doctor` prints runtime platform capabilities. -`gitnexus impact --max-tokens 1000` budgets compact JSON at four UTF-8 bytes per token, retaining the nearest dependants first. Counts and risk remain complete; `pagination.trimmedForBudget` describes omitted symbols. If the summary cannot fit, the command returns a JSON error and exits nonzero. Extremely small budgets return JSON `null` with the same failure status. Budgeted output is compact even on a terminal; other direct tool output is compact when piped and indented on a terminal. +`gitnexus impact --max-tokens 1000` budgets compact JSON at four UTF-8 bytes per token. Single-repo callgraph results retain the nearest dependants first. Counts and risk remain complete; `pagination.trimmedForBudget` describes omitted symbols. Group and PDG results must fit intact. If required content cannot fit, the command returns a JSON error and exits nonzero. Extremely small budgets return JSON `null` with the same failure status. Budgeted output is compact even on a terminal; other direct tool output is compact when piped and indented on a terminal. Impact defaults to 30 symbols per depth when pagination is omitted. Use `--limit` and `--offset` for explicit pages, or `GITNEXUS_IMPACT_DEFAULT_LIMIT=0` for all symbols. `--summary-only`, group queries and PDG mode bypass this default. Symbols list at most three processes, with `processCount` preserving the full count when shortened. `--max-tokens` is explicit on the CLI; `GITNEXUS_MCP_DEFAULT_MAX_TOKENS` applies only to MCP. diff --git a/docs/mcp-reference.md b/docs/mcp-reference.md index 53ba4d0c0..3c35ae5e3 100644 --- a/docs/mcp-reference.md +++ b/docs/mcp-reference.md @@ -116,7 +116,7 @@ The `query`, `context`, and `impact` tools accept an optional positive-integer ` Set `GITNEXUS_MCP_DEFAULT_MAX_TOKENS` to apply the budget when callers do not send `maxTokens`. An explicit tool argument takes precedence. Leaving both unset disables token budgeting. The estimate is not an exact model-specific tokenizer limit. -`impact` removes whole symbols from the deepest levels first. Counts, risk and completeness warnings remain intact, and `pagination.trimmedForBudget.shownByDepth` records the returned counts. If metadata alone cannot fit, it returns a JSON error with MCP `isError: true`; increase `maxTokens` or narrow the request. Budgets too small for an error object return JSON `null` with `isError: true`. Group and PDG results are not paginated or trimmed by this mechanism; an oversized result also returns a budget error. +For single-repo callgraph results, `impact` removes whole symbols from the deepest levels first. Counts, risk and completeness warnings remain intact, and `pagination.trimmedForBudget.shownByDepth` records the returned counts. If metadata alone cannot fit, it returns a JSON error with MCP `isError: true`; increase `maxTokens` or narrow the request. Budgets too small for an error object return JSON `null` with `isError: true`. Group and PDG results are not paginated or trimmed by this mechanism; an oversized result also returns a budget error. Without explicit pagination, single-repo callgraph impact returns up to 30 symbols per depth. Client-supplied `offset: 0` and `summaryOnly: false` still use this default. Set `GITNEXUS_IMPACT_DEFAULT_LIMIT=0` for an unpaged result, or set `limit` and `offset` for explicit pages. Each symbol lists at most three processes; `processCount` records the full count when the list is shortened. Backend results used by the web UI and internal callers are unchanged. diff --git a/gitnexus/src/cli/i18n/en.ts b/gitnexus/src/cli/i18n/en.ts index e550640fb..e11f179bb 100644 --- a/gitnexus/src/cli/i18n/en.ts +++ b/gitnexus/src/cli/i18n/en.ts @@ -392,7 +392,7 @@ export const en = { 'help.option.impact.offset': 'Skip N symbols per depth level for pagination', 'help.option.impact.summaryOnly': 'Return counts and risk only, omit symbol list', 'help.option.impact.maxTokens': - 'Fit compact JSON into about N tokens, dropping deepest symbols first; fails if the summary cannot fit', + 'Fit compact JSON into about N tokens; trim deepest callgraph symbols or fail if required content cannot fit. PDG/group results must fit intact', 'help.option.trace.fromUid': 'Source symbol UID (zero-ambiguity lookup)', 'help.option.trace.fromFile': 'Source file path to disambiguate common names', 'help.option.trace.toUid': 'Target symbol UID (zero-ambiguity lookup)', diff --git a/gitnexus/src/cli/i18n/zh-CN.ts b/gitnexus/src/cli/i18n/zh-CN.ts index 46cc71c36..c1594ad3e 100644 --- a/gitnexus/src/cli/i18n/zh-CN.ts +++ b/gitnexus/src/cli/i18n/zh-CN.ts @@ -356,7 +356,7 @@ export const zhCN = { 'help.option.impact.offset': '每层深度跳过 N 个符号(分页用)', 'help.option.impact.summaryOnly': '仅返回计数和风险等级,省略符号列表', 'help.option.impact.maxTokens': - '将紧凑 JSON 控制在约 N 个 token 内,优先舍弃最深层的符号;摘要无法容纳时返回错误', + '将紧凑 JSON 控制在约 N 个 token 内;调用图优先舍弃最深层符号,必要内容无法容纳时返回错误。PDG 和仓库组结果必须完整容纳', 'help.option.trace.fromUid': '源符号 UID(零歧义查找)', 'help.option.trace.fromFile': '源文件路径,用于消除常见名称歧义', 'help.option.trace.toUid': '目标符号 UID(零歧义查找)', diff --git a/gitnexus/src/cli/index.ts b/gitnexus/src/cli/index.ts index 38e80a594..0cb3786ae 100644 --- a/gitnexus/src/cli/index.ts +++ b/gitnexus/src/cli/index.ts @@ -524,7 +524,7 @@ program .option('--summary-only', 'Return counts and risk only, omit symbol list') .option( '--max-tokens ', - 'Fit compact JSON into about N tokens, dropping deepest symbols first; fails if the summary cannot fit', + 'Fit compact JSON into about N tokens; trim deepest callgraph symbols or fail if required content cannot fit. PDG/group results must fit intact', ) .action(createLbugLazyAction(() => import('./tool.js'), 'impactCommand')); diff --git a/gitnexus/src/mcp/tools.ts b/gitnexus/src/mcp/tools.ts index 47a3c1a07..4b65b3a8d 100644 --- a/gitnexus/src/mcp/tools.ts +++ b/gitnexus/src/mcp/tools.ts @@ -701,7 +701,7 @@ ${HOT_READ_STALENESS_NOTE}`, type: 'integer', minimum: 1, description: - 'Token budget including hints. Trims deepest symbols; preserves counts/risk. Errors if the summary cannot fit. Overrides GITNEXUS_MCP_DEFAULT_MAX_TOKENS.', + 'Token budget including hints. Trims callgraph symbols; PDG/group and required content must fit or error. Overrides GITNEXUS_MCP_DEFAULT_MAX_TOKENS.', }, timeoutMs: { type: 'number',