Add validate output shaping controls

README.md

@@ -425,11 +425,13 @@ GPG 検証が成功した後にこの fingerprint の設定も必須です。
 
 ### Validate
 
-`cdidx validate [--db <path>] [--json] [--verbose] [--kind <kind>] [--path <glob>]`
+`cdidx validate [--db <path>] [--json[=array]] [--verbose] [--limit <n>|--top <n>] [--kind <kind>] [--severity <info|warning|error>] [--path <glob>]`
 は、index 済みファイルの replacement character (`U+FFFD`)、BOM、NUL byte、
 混在改行、UTF-16 BOM、非 UTF-8 らしい内容などを報告します。validation finding は
 出力で報告され、それ自体では command failure になりません。DB を読めない場合や
-引数が不正な場合は non-zero で終了します。機械処理には `--json` を使えます。
+引数が不正な場合は non-zero で終了します。`--severity warning` を使うと、
+意図的な U+FFFD literal などの informational finding を除外できます。
+機械処理には `--json` を使え、配列だけが必要な pipeline では `--json=array` を使えます。
 
 ### シェル補完
 

USER_GUIDE.md

@@ -405,7 +405,9 @@ conflicting instructions.
 ```bash
 cdidx validate
 cdidx validate --kind replacement_char --path src/
-cdidx validate --json --path legacy/
+cdidx validate --kind replacement_char --severity warning --path src/
+cdidx validate --json=array --limit 50 --path legacy/
+cdidx validate --json --limit 50 --path legacy/
 ```
 
 `validate` reports indexed files that are likely to produce misleading snippets
@@ -414,6 +416,10 @@ CR-only line endings, likely non-UTF-8 content, and Git LFS pointer placeholders
 For `replacement_char`, JSON and MCP responses include `origin` (`source_literal`
 or `decode_replacement`) and `severity` so agents can distinguish intentional
 U+FFFD literals from likely encoding damage.
+Use `--severity warning` to hide informational source literals and focus on
+findings that indicate likely encoding damage.
+Use `--json=array` when a pipeline expects a bare issue array instead of the
+default `{ "count": ..., "issues": [...] }` object.
 LFS pointers are recorded as `lfs_pointer_skipped` and their placeholder body is
 not indexed; run `git lfs pull` and then `cdidx index .` to index the real file
 content.
@@ -2593,15 +2599,20 @@ render できます。
 ```bash
 cdidx validate
 cdidx validate --kind replacement_char --path src/
-cdidx validate --json --path legacy/
+cdidx validate --kind replacement_char --severity warning --path src/
+cdidx validate --json=array --limit 50 --path legacy/
+cdidx validate --json --limit 50 --path legacy/
 ```
 
 `validate` は、snippet や symbol name を誤らせやすい indexed file を報告します。
 対象は U+FFFD replacement character、UTF-16 BOM、null byte、mixed / CR-only line
 ending、likely non-UTF-8 content、Git LFS pointer placeholder などです。
 `replacement_char` の JSON / MCP response には `origin` (`source_literal` /
 `decode_replacement`) と `severity` が入り、意図的な U+FFFD literal と
-エンコーディング破損の可能性を agent が区別できます。LFS pointer
+エンコーディング破損の可能性を agent が区別できます。`--severity warning`
+を使うと、informational な source literal を隠して、エンコーディング破損の
+可能性がある finding に集中できます。pipeline が既定の `{ "count": ..., "issues": [...] }`
+object ではなく bare issue array を期待する場合は `--json=array` を使えます。LFS pointer
 は `lfs_pointer_skipped` として記録され、placeholder 本文は index されません。
 実体を index するには `git lfs pull` の後に `cdidx index .` を再実行してください。
 

changelog.d/unreleased/2992.fixed.md

@@ -0,0 +1,18 @@
+---
+category: fixed
+issues:
+  - 2992
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - src/CodeIndex/Database/DbReader.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerValidateTests.cs
+---
+
+## English
+
+- **`validate` now supports explicit result limits (#2992)** — pass `--limit <n>` or `--top <n>` to cap reported validation issues for large repositories and agent audit loops while preserving the existing all-results default.
+
+## 日本語
+
+- **`validate` が明示的な結果件数制限に対応しました (#2992)** — `--limit <n>` または `--top <n>` で、大きなリポジトリや agent audit loop の validation issue 表示件数を制限できます。既定の全件表示は維持されます。

changelog.d/unreleased/3008.fixed.md

@@ -0,0 +1,17 @@
+---
+category: fixed
+issues:
+  - 3008
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Database/DbReader.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerValidateMetadataTests.cs
+---
+
+## English
+
+- **`validate` can filter findings by severity (#3008)** — `--severity warning` focuses JSON and human output on warning-level findings such as likely decode replacements while hiding informational source literals.
+
+## 日本語
+
+- **`validate` で finding の severity filter を指定できるようにしました (#3008)** — `--severity warning` により、informational な source literal を隠し、decode replacement の可能性がある warning-level finding に集中できます。

changelog.d/unreleased/3010.fixed.md

@@ -0,0 +1,16 @@
+---
+category: fixed
+issues:
+  - 3010
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerValidateTests.cs
+---
+
+## English
+
+- **`validate` supports JSON array shaping (#3010)** — `--json=array` now returns a bare issue array, including `[]` for clean indexes, while plain `--json` keeps the existing `{ count, issues }` object.
+
+## 日本語
+
+- **`validate` が JSON array shaping に対応しました (#3010)** — `--json=array` は clean index では `[]`、finding がある場合は bare issue array を返し、通常の `--json` は従来どおり `{ count, issues }` object を維持します。

src/CodeIndex/Cli/CliFlagSchema.cs

@@ -75,10 +75,14 @@ internal static class CliFlagSchema
     private static readonly string[] LimitCapableCommands =
     [
         "search", "definition", "goto", "references", "callers", "callees", "symbols",
-        "files", "find", "map", "inspect", "deps", "impact", "unused", "hotspots",
+        "files", "find", "map", "inspect", "deps", "impact", "unused", "hotspots", "validate",
     ];
 
-    private static readonly string[] LangCapableCommands = LimitCapableCommands;
+    private static readonly string[] LangCapableCommands =
+    [
+        "search", "definition", "goto", "references", "callers", "callees", "symbols",
+        "files", "find", "map", "inspect", "deps", "impact", "unused", "hotspots",
+    ];
 
     private static readonly string[] PathFilterCommands =
     [
@@ -107,6 +111,7 @@ internal static class CliFlagSchema
     [
         "definition", "goto", "references", "callers", "callees", "symbols", "unused", "hotspots", "validate",
     ];
+    private static readonly string[] SeverityCommands = ["validate"];
     private static readonly string[] VisibilityCommands =
     [
         "definition", "symbols", "unused", "hotspots",
@@ -207,7 +212,7 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--immutable", Description = "Alias for --read-only", Commands = Set(ReadOnlyDbCommands) },
             new() { Name = "--workspace-db", ValuePlaceholder = "<path>", Description = "Additional workspace member database path for dependency aggregation", Commands = Set(WorkspaceDbCommands) },
             new() { Name = "--data-dir", ValuePlaceholder = "<dir>", Description = "Directory containing codeindex.db; overrides CDIDX_DATA_DIR/XDG/workspace defaults", Commands = Set(DataDirCommands) },
-            new() { Name = "--json", Description = "JSON output; search/files also accept --json=array for a single JSON array", Commands = Set(JsonCommands) },
+            new() { Name = "--json", Description = "JSON output; search/files/validate also accept --json=array for a single JSON array", Commands = Set(JsonCommands) },
             new() { Name = "--format", ValuePlaceholder = "<text|json|count|compact|csv|tsv|lsp|qf|sarif>", Description = "Standard output format for token budgets, editor integrations, and CI", Commands = Set(FormatCommands) },
             new() { Name = "--quiet", ShortName = "-q", Description = "Suppress informational stderr output; errors still print", Commands = Set(AllCommands.ToArray()) },
             new() { Name = "--silent", Description = "Alias for --quiet", Commands = Set(AllCommands.ToArray()) },
@@ -226,6 +231,7 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--exclude-tests", Description = "Exclude tests", Commands = Set(ExcludeFilterCommands) },
             new() { Name = "--include-generated", Description = "Include generated files", Commands = Set(ExcludeFilterCommands) },
             new() { Name = "--kind", ValuePlaceholder = "<kind>", Description = "Filter by kind", Commands = Set(KindCommands) },
+            new() { Name = "--severity", ValuePlaceholder = "<info|warning|error>", Description = "Validate: filter validation issues by severity", Commands = Set(SeverityCommands) },
             new() { Name = "--visibility", ValuePlaceholder = "<visibility[,visibility]>", Description = "Filter by symbol visibility", Commands = Set(VisibilityCommands) },
             new() { Name = "--exclude-visibility", ValuePlaceholder = "<visibility[,visibility]>", Description = "Exclude symbol visibility", Commands = Set(VisibilityCommands) },
             new() { Name = "--by-bucket", Description = "Unused: include per-bucket grouped result arrays in JSON output", Commands = Set(ByBucketCommands) },

src/CodeIndex/Cli/ConsoleUi.cs

@@ -99,7 +99,7 @@ private static readonly (string Command, string Usage)[] CommandUsageLines =
         ("db", "cdidx db --integrity-check|schema|prune [--dry-run|--apply] [--db <path>] [--json] | cdidx db checkpoint [name] [--db <path>] [--json] | cdidx db checkpoints --list [--db <path>] [--json] | cdidx db restore <name> [--db <path>] [--json]"),
         ("diff", "cdidx diff <db1> <db2> [--json] [--summary-only] [--detailed] [--limit <n>]"),
         ("report", "cdidx report --output <path> [--db <path>] [--json] [--log-lines <n<=2000>] [--no-log] [--include-args]"),
-        ("validate", "cdidx validate [--db <path>] [--json] [--format <text|json|count|compact|csv|tsv|lsp|qf|sarif>] [--verbose] [--kind <kind>] [--path <glob>]"),
+        ("validate", "cdidx validate [--db <path>] [--json[=array]] [--format <text|json|count|compact|csv|tsv|lsp|qf|sarif>] [--verbose] [--limit <n>|--top <n>] [--kind <kind>] [--severity <info|warning|error>] [--path <glob>]"),
         ("impact", "cdidx impact <query>|--query <query>|-- <query> [--db <path>] [--json] [--verbose] [--limit <n>|--top <n>] [--lang <lang>] [--path <glob>] [--exclude-path <glob>] [--exclude-tests] [--body] [--snippet-lines <n>] [--max-line-width <n>] [--max-hops <n>] [--count] [--with-paths]"),
         ("deps", "cdidx deps [--db <path>] [--json] [--format <dot|graphml|json-graph|edgelist>] [--verbose] [--limit <n>|--top <n>] [--lang <lang>] [--path <glob>] [--exclude-path <glob>] [--exclude-tests] [--reverse] [--cycles]"),
         ("unused", "cdidx unused [--db <path>] [--json] [--verbose] [--limit <n>|--top <n>] [--kind <kind>] [--visibility <v[,v]>] [--exclude-visibility <v[,v]>] [--lang <lang>] [--path <glob>] [--exclude-path <glob>] [--exclude-tests] [--count]"),
@@ -943,7 +943,7 @@ private static void PrintFlagReference(Action<string> WriteHelpLine)
         Console.WriteLine();
         Console.WriteLine("Query options:");
         Console.WriteLine("  --db <path>                Database file path (default: .cdidx/codeindex.db in current directory)");
-        WriteHelpLine("  --json                     Output as JSON (search/files stream ndjson by default; use --json=array for one array)");
+        WriteHelpLine("  --json                     Output as JSON (search/files stream ndjson by default; search/files/validate accept --json=array for one array)");
         WriteHelpLine("  --verbose                  Query commands: emit debug diagnostics to stderr; with --json, append an _debug JSON object");
         WriteHelpLine("  --quiet, -q, --silent      Query commands: suppress informational stderr output, including zero-result hints and summaries; errors still print. Overrides --verbose stderr text.");
         WriteHelpLine("  --profile                  Read commands: append SQL timing, row-count, and EXPLAIN QUERY PLAN JSON after the normal result");
@@ -975,6 +975,7 @@ private static void PrintFlagReference(Action<string> WriteHelpLine)
         Console.WriteLine("                              Legacy/stale-fold DBs fall back to ASCII NOCASE;");
         Console.WriteLine("                              run `cdidx backfill-fold` or check fold_ready.");
         WriteHelpLine("  --kind <kind>              definition/symbols/hotspots/unused: symbol kind; references: reference kind (call/instantiate/subscribe/attribute/annotation); callers/callees: call-graph kinds only (call/instantiate/subscribe — metadata kinds rejected, use references instead); validate: issue kind");
+        Console.WriteLine("  --severity <s>             validate only: filter issues by severity: info, warning, error");
         Console.WriteLine("  --visibility <v[,v]>       Filter symbols/definitions/unused/hotspots by visibility: public, protected, internal, private");
         WriteHelpLine("  --exclude-visibility <v[,v]> Exclude symbols/definitions/unused/hotspots by visibility");
         WriteHelpLine("  --count                    Count only; search/definition/references/callers/callees/symbols/files/find/unused ignore --limit, impact/hotspots still use visible page counts");