Add nested inspect field projections (#5136)

* Add nested inspect field projections (#5098)

* Fix inspect projection edge cases (#5098)

* Preserve inspect projection metadata (#5098)

Author: Widthdom

DEVELOPER_GUIDE.md

@@ -2190,6 +2190,18 @@ case-sensitive; unknown values use the versioned `E010_USAGE_ERROR` command
 error when JSON is requested, and discovery runs before query or database
 access.
 
+`inspect` keeps a dedicated typed schema in the same registry because its
+established JSON bundle is not a shared bounded-response envelope. It accepts
+top-level groups and exactly one `collection.field` level for definitions,
+nearby symbols, references, callers, and callees. Inspect selectors normalize
+case and hyphens, resolve aliases before first-occurrence deduplication, and
+preserve canonical request order. A selected parent dominates its children and
+keeps complete rows; otherwise the row projector emits only selected leaves.
+Projection runs before final serialization and byte budgeting while preserving
+root metadata, section totals/cursors/truncation, partial-family metadata, and
+definition body paging/recovery fields. The queryless `inspect --fields list`
+catalog and unknown-field errors are generated from that same schema.
+
 | Output mode | Contract |
 |---|---|
 | Human-readable default | Query commands (`search`, `definition`, `references`, `callers`, `callees`, `symbols`, `files`, `excerpt`, `map`, `inspect`, `outline`, `suggestions`) default to **human-readable output**. |
@@ -6113,6 +6125,17 @@ help はすべてこのレジストリを参照します。field 名は大文字
 値で JSON が要求されている場合は versioned `E010_USAGE_ERROR` command error を
 返します。発見処理は query や database access より先に実行します。
 
+`inspect` は従来の JSON bundle を shared bounded-response envelope に変更しないため、
+同じレジストリ内に専用の typed schema を持ちます。top-level group に加え、definitions、
+nearby symbols、references、callers、callees では 1 階層だけの `collection.field` を
+受け付けます。inspect selector は大小文字と hyphen を正規化し、alias 解決後に最初の出現を
+残して重複を除き、canonical な指定順を維持します。parent が選択されていれば child より
+優先して完全な row を保持し、それ以外は選択した leaf だけを row projector が出力します。
+projection は最終 serialization と byte budget 適用より前に行い、root metadata、section の
+total / cursor / truncation、partial-family metadata、definition body の paging / recovery field を
+維持します。query 不要の `inspect --fields list` catalog と未知 field error も同じ schema から
+生成します。
+
 | output mode | 契約 |
 |---|---|
 | human-readable default | query command（`search`、`definition`、`references`、`callers`、`callees`、`symbols`、`files`、`excerpt`、`map`、`inspect`、`outline`、`suggestions`）は既定で**人間向け出力**です。 |

TESTING_GUIDE.md

@@ -19,6 +19,7 @@ Use the full suite by default. Use targeted filters only while iterating locally
 
 ## Test Stack
 
+- Issue #5098 inspect projection coverage belongs in `QueryCommandRunnerInspectTests.cs`. Keep one graph-ready partial-type fixture covering canonical and alias selectors, multiple leaves across collections, parent-over-child precedence, stable row order, empty arrays, compact truncation, byte bounds, body paging/recovery, partial-family metadata, queryless catalog discovery, and typed unknown parent/leaf errors. `ConsoleUiTests.cs` separately pins the `<csv|list>` usage, nested-field help text, and examples.
 - Path-containment coverage for #5091 pairs platform-independent `PathCasingTests` seams for mixed parent-namespace case policies and directory identities with `FileIndexerTests` integration through an internal file symlink. Keep both checks when changing internal-symlink policy: a case-insensitive project mount must not make a distinct case-only sibling in its case-sensitive parent namespace appear internal, while genuine same-namespace aliases remain accepted.
 - `WorkspaceCheckTruncationIssue5055Tests` owns the bounded `workspace_check` list contract. Keep zero, below-limit, exact-limit, and over-limit coverage for all six categories, plus the 1260/20/1240 example and one shared filesystem fixture for raw JSON, list-only projection, compact output, byte-budget trimming, deterministic order, and human sample labeling.
 - Recipe issue-draft summary coverage in `QueryCommandRunnerSearchTests` keeps the dedicated compact DTO separate from full draft bodies, asserts returned/total/omitted row cardinality (including `count == drafts.length` and positive queries hidden by `--total-limit`), preserves pre-limit evidence-path counts with authority/lower-bound metadata, measures the complete UTF-8 document with multibyte paths and its final newline, verifies whole-row truncation and typed `E028` audit identity, and preserves the full-output contract.
@@ -1107,6 +1108,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
 
 ## テストスタック
 
+- Issue #5098 の inspect projection coverage は `QueryCommandRunnerInspectTests.cs` が担当します。graph-ready な partial type fixture 1つで canonical / alias selector、collection をまたぐ複数 leaf、parent の child に対する優先、安定した row 順、空配列、compact truncation、byte 上限、body paging / recovery、partial-family metadata、query 不要の catalog discovery、未知 parent / leaf の型付き error を維持してください。`ConsoleUiTests.cs` では `<csv|list>` usage、nested-field help text、例を別途固定します。
 - #5091 の path containment coverage は、親 directory namespace の case policy と directory identity が混在する状況を OS 非依存で再現する `PathCasingTests` の seam と、内部 file symlink を通す `FileIndexerTests` の integration を対にします。internal-symlink policy を変更するときは両方を維持し、case-insensitive な project mount の policy で、case-sensitive な親 namespace にある別 identity の case-only sibling を内部 path と誤認しないこと、および同一 namespace の正当な alias は引き続き受理されることを検証してください。
 - `WorkspaceCheckTruncationIssue5055Tests` は上限付き `workspace_check` 一覧の契約を担当します。6カテゴリすべての0件・上限未満・上限一致・上限超過、1260/20/1240 の例、および raw JSON、一覧単独 projection、compact 出力、byte budget による短縮、決定的順序、human 向け sample 表示を1つの共有 filesystem fixture で検証する coverage を維持してください。
 - `QueryCommandRunnerSearchTests` の recipe issue-draft summary coverage は、専用 compact DTO を完全版 draft body から分離し、返却 / total / omitted row の cardinality（`count == drafts.length` と `--total-limit` に隠れた positive query を含む）、limit 適用前の evidence-path count と authority / lower-bound metadata の維持、multibyte path と末尾改行を含む UTF-8 document 全体の計測、完全な row 単位の truncation、型付き `E028` の audit identity、完全版 output contract の維持を検証します。

USER_GUIDE.md

@@ -390,7 +390,7 @@ When a bounded `find --all` scan exits partially, its terminal record includes
 `next_cursor`; replaying it resumes after the last scanned line.
 The bounded-response commands `search`, `definition`, `find`, `status`,
 `hotspots`, `references`, `callers`, `callees`, `symbols`, `files`,
-`languages`, `impact`, and `map` validate `--fields` values case-sensitively
+`languages`, `impact`, `map`, and `inspect` validate `--fields` values
 against one command-specific registry. Unknown names return a typed
 `E010_USAGE_ERROR` instead of successful empty objects. Run
 `cdidx <command> --fields list` before a query to obtain the machine-readable
@@ -415,9 +415,18 @@ same section envelopes and accepts their cursors. In path/line mode, `--path`
 locates the definition but does not restrict inbound references or callers to
 that file. Inspect graph cursors are accepted only by `inspect`; passing one to
 another command is a usage error.
-For narrower `inspect` evidence, `--fields <csv>` implies JSON and selects
+For narrower `inspect` evidence, `--fields <csv|list>` implies JSON and selects
 top-level groups such as `definitions`, `file`, `graph`, `references`,
-`callers`, and `callees`; `--outline-only` is shorthand for
+`callers`, and `callees`. Collection selectors accept one nested level, for
+example `definitions.name`, `definitions.path`, `definitions.line`,
+`references.path`, or `callers.path`. Selecting a parent keeps the full rows;
+when a parent and child are both requested, the parent wins. Child rows follow
+the canonical request order, aliases and duplicates are normalized
+deterministically, empty arrays remain arrays, and response counts, truncation,
+cursor, body recovery, and partial-family metadata remain available. Unknown
+parents or leaves return a typed usage error with the field catalog. Run
+`cdidx inspect --fields list` without a query or database to inspect that
+catalog. `--outline-only` is shorthand for
 `--fields file,definitions,nearby_symbols`, and `--body-only` is shorthand for
 `--body --fields definitions`. When a definition body is longer than the returned slice,
 `body_content_next_start_line` points to the next source line to pass with
@@ -457,6 +466,8 @@ cdidx inspect Compute --body-only         # definitions with body_content only
 cdidx inspect Compute --body --body-start 40 --body-lines 40
 cdidx inspect Compute --line 42 --context 2 --json
 cdidx inspect Compute --json --limit 1 --cursor '<next_cursor>'
+cdidx inspect Compute --json --fields definitions.name,definitions.path,references.line
+cdidx inspect --fields list
 ```
 
 ## Editor and index portability
@@ -2243,7 +2254,7 @@ same source location.
 | `--summary-only` | `map`, `recipes`, `audit`, `deps`, `hotspots`, and supported `search` JSON contexts | Emit aggregate/context JSON while omitting heavy result arrays where supported. For `deps`, use `--json` or `--format json-graph`; for `hotspots`, use `--json`. Machine-readable `deps` output emits `Progress:` diagnostics only with `--verbose`; other large graph queries emit them at `--limit 80+` or with `--verbose`. |
 | `--sort <mode>` | `symbols`, `outline` | For `outline`, sort one file's symbols by `source`, `kind`, `references`, `size` / `span`, `complexity`, `path`, or `name` before `--limit` / cursor paging. |
 | `--outline-fields <csv>` | `outline` | Project outline JSON symbol fields such as `name`, `line`, `kind`, `signature`, `container`, `range`, `body`, `reference_count`, `size_lines`, `complexity_score`, or `sort_mode`; pass `all` for the full symbol payload with paging metadata. |
-| `--fields <csv>` | `inspect` | Select top-level inspect JSON groups: `file`, `workspace`, `graph`, `definitions`, `body`, `source_excerpt`, `nearby_symbols`, `references`, `callers`, `callees`, or `all`. `body` includes definition bodies and maps to `definitions`. |
+| `--fields <csv\|list>` | `inspect` | Select top-level inspect JSON groups or one-level collection leaves such as `definitions.name`, `definitions.path`, `references.line`, and `callers.path`. A parent keeps full rows and wins over its children; aliases, duplicates, and output order are normalized deterministically. `body` includes definition bodies and maps to `definitions`. Use `list` for the queryless typed catalog. |
 | `--outline-only` | `inspect` | Shorthand for `--fields file,definitions,nearby_symbols`, useful for outline-first review of large classes/types before requesting body or graph evidence. |
 | `--body-only` | `inspect` | Shorthand for `--body --fields definitions`, useful when large audits need implementation text without graph context. |
 | `--body-start <line>` | `inspect` | Start the returned definition body slice at a 1-based source line inside the symbol body. Pair with `body_content_next_start_line` from JSON to page a long body. |
@@ -4000,9 +4011,16 @@ path/line mode の `--path` は定義の位置を特定しますが、inbound re
 そのファイルだけに制限しません。MCP `analyze_symbol` も同じ section envelope を公開し、
 その cursor を受け付けます。inspect graph cursor は `inspect` だけが受理し、別 command に
 渡すと usage error になります。
-`inspect` の証跡をさらに絞りたい場合、`--fields <csv>` は JSON 出力を暗黙に有効化し、
+`inspect` の証跡をさらに絞りたい場合、`--fields <csv|list>` は JSON 出力を暗黙に有効化し、
 `definitions`、`file`、`graph`、`references`、`callers`、`callees` などの
-top-level group を選択します。`--outline-only` は
+top-level group を選択します。collection selector は 1 階層の nested field に対応し、
+たとえば `definitions.name`、`definitions.path`、`definitions.line`、
+`references.path`、`callers.path` を指定できます。parent を選ぶと row 全体を保持し、
+parent と child を同時指定した場合は parent が優先されます。child row は canonical な
+指定順を保ち、alias と重複は決定的に正規化されます。空配列は配列のまま保持され、count、
+truncation、cursor、body recovery、partial-family metadata も維持されます。未知の parent / leaf
+は field catalog 付きの型付き usage error になります。query や DB なしで
+`cdidx inspect --fields list` を実行すると catalog を確認できます。`--outline-only` は
 `--fields file,definitions,nearby_symbols` の shorthand で、`--body-only` は
 `--body --fields definitions` の shorthand です。definition body が返却 slice より長い場合は
 `body_content_next_start_line` が次に `--body-start` へ渡す source line を示します。
@@ -4040,6 +4058,8 @@ cdidx inspect Compute --body-only         # body_content 付き definitions の
 cdidx inspect Compute --body --body-start 40 --body-lines 40
 cdidx inspect Compute --line 42 --context 2 --json
 cdidx inspect Compute --json --limit 1 --cursor '<next_cursor>'
+cdidx inspect Compute --json --fields definitions.name,definitions.path,references.line
+cdidx inspect --fields list
 ```
 
 ## Editor / index portability
@@ -5747,7 +5767,7 @@ raw match density を正確に測る、といった理由で全 raw chunk hit 
 | `--summary-only` | `map`、`recipes`、`audit`、`deps`、`hotspots`、および対応する `search` JSON 文脈 | 対応コマンドで重い結果配列を省き、集計と文脈中心の JSON を返す。`deps` では `--json` または `--format json-graph`、`hotspots` では `--json` と組み合わせる。machine-readable な `deps` 出力は `--verbose` 指定時だけ stderr へ `Progress:` 診断を出し、それ以外の大きい graph query は `--limit 80` 以上または `--verbose` 指定時に出す。 |
 | `--sort <mode>` | `symbols`、`outline` | `outline` では 1ファイル内のシンボルを `source`、`kind`、`references`、`size` / `span`、`complexity`、`path`、`name` で並べ替えてから `--limit` / カーソルページングを適用する。 |
 | `--outline-fields <csv>` | `outline` | outline JSON のシンボルフィールドを投影する。`name`、`line`、`kind`、`signature`、`container`、`range`、`body`、`reference_count`、`size_lines`、`complexity_score`、`sort_mode` などを指定でき、`all` を渡すとシンボルペイロード全体とページングメタデータを返す。 |
-| `--fields <csv>` | `inspect` | inspect JSON の top-level group を選択。`file`、`workspace`、`graph`、`definitions`、`body`、`source_excerpt`、`nearby_symbols`、`references`、`callers`、`callees`、`all` を指定できる。`body` は definition body を含め、`definitions` に対応する。 |
+| `--fields <csv\|list>` | `inspect` | inspect JSON の top-level group または `definitions.name`、`definitions.path`、`references.line`、`callers.path` など 1 階層の collection leaf を選択する。parent は row 全体を保持して child より優先され、alias、重複、出力順は決定的に正規化される。`body` は definition body を含め、`definitions` に対応する。query 不要の型付き catalog は `list` で取得できる。 |
 | `--outline-only` | `inspect` | `--fields file,definitions,nearby_symbols` の shorthand。大きな class / type を body や graph evidence なしでアウトライン優先で確認したい場合に使う。 |
 | `--body-only` | `inspect` | `--body --fields definitions` の shorthand。大規模 audit で graph context なしに実装本文だけが必要な場合に使う。 |
 | `--body-start <line>` | `inspect` | symbol body 内の 1-based source line から definition body slice を返す。長い body の page 送りでは JSON の `body_content_next_start_line` を次の値として渡す。 |

changelog.d/unreleased/5098.added.md

@@ -0,0 +1,22 @@
+---
+category: added
+issues:
+  - 5098
+affected:
+  - src/CodeIndex/Cli/ProjectionFieldRegistry.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.ArgumentParser.Filters.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.ArgumentParser.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.Inspect.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+  - USER_GUIDE.md
+  - DEVELOPER_GUIDE.md
+  - TESTING_GUIDE.md
+---
+
+## English
+
+- **Inspect JSON supports nested collection field projections (#5098)** — `cdidx inspect --fields` can now select one-level leaves such as `definitions.name`, `references.path`, and `callers.line`, while preserving response and coupled row truncation metadata, compact and byte-bounded behavior, definition-body recovery fields, deterministic parent/alias/order and repeated-option semantics, typed unknown-field errors, and a queryless `--fields list` catalog.
+
+## 日本語
+
+- **inspect JSON で collection の nested field projection に対応しました (#5098)** — `cdidx inspect --fields` で `definitions.name`、`references.path`、`callers.line` など 1 階層の leaf を選択できるようになりました。response metadata と行内の関連 truncation metadata、compact / byte 上限制御、definition body の recovery field、決定的な parent / alias / 順序 / 重複 option の規則、未知 field の型付き error、query 不要の `--fields list` catalog も維持します。

src/CodeIndex/Cli/CliFlagSchema.cs

@@ -547,7 +547,7 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--body-start", ValuePlaceholder = "<line>", Description = "Inspect: start definition body slice at this 1-based source line", PrimaryCommands = Set(InspectFieldCommands) },
             new() { Name = "--body-lines", ValuePlaceholder = "<n>", Description = "Inspect: return at most this many definition body lines", PrimaryCommands = Set(InspectFieldCommands) },
             new() { Name = "--body-line-count", ValuePlaceholder = "<n>", Description = "Inspect: alias for --body-lines", PrimaryCommands = Set(InspectFieldCommands) },
-            new() { Name = "--fields", ValuePlaceholder = "<csv>", Description = "Project bounded-response row fields; inspect selects top-level evidence groups; nested collections accept collection.field", PrimaryCommands = Set(InspectFieldCommands.Concat(BoundedProjectionCommands).ToArray()) },
+            new() { Name = "--fields", ValuePlaceholder = "<csv>", Description = "Project bounded-response fields; inspect accepts top-level groups or collection.field and `list` prints its typed catalog", PrimaryCommands = Set(InspectFieldCommands.Concat(BoundedProjectionCommands).ToArray()) },
             new() { Name = "--body-only", Description = "Inspect: body-focused JSON shorthand for --body --fields definitions", PrimaryCommands = Set(InspectFieldCommands) },
             new() { Name = "--outline-only", Description = "Inspect: outline-first JSON shorthand for --fields file,definitions,nearby_symbols", PrimaryCommands = Set(InspectFieldCommands) },
             new() { Name = "--exact", Description = "Backward-compatible exact shorthand; search mode is incompatible with --fts", PrimaryCommands = Set(ExactCommands) },