Expose search and excerpt JSON recovery metadata

changelog.d/unreleased/3556.fixed.md

@@ -0,0 +1,18 @@
+---
+category: fixed
+issues:
+  - 3556
+affected:
+  - DEVELOPER_GUIDE.md
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - src/CodeIndex/Cli/SearchSnippetFormatter.cs
+  - tests/CodeIndex.Tests/SearchSnippetFormatterTests.cs
+---
+
+## English
+
+- **Search snippets now explain focus selection and dropped-match navigation (#3556)** — compact search JSON includes `focus_mode`, `focus_line`, `focus_column`, `focus_reason`, and `next_match` metadata so clients can understand the selected window and jump to omitted matches.
+
+## 日本語
+
+- **検索 snippet が focus 選択理由と dropped match の移動先を返すようになりました (#3556)** — compact search JSON に `focus_mode` / `focus_line` / `focus_column` / `focus_reason` / `next_match` を追加し、クライアントが選択された window を理解して省略された一致へ移動できるようにしました。

changelog.d/unreleased/3557.fixed.md

@@ -0,0 +1,18 @@
+---
+category: fixed
+issues:
+  - 3557
+affected:
+  - DEVELOPER_GUIDE.md
+  - src/CodeIndex/Cli/SearchSnippetFormatter.cs
+  - src/CodeIndex/Database/LineWidthFormatter.cs
+  - tests/CodeIndex.Tests/SearchSnippetFormatterTests.cs
+---
+
+## English
+
+- **Search highlight occurrences now expose visible ranges after line clamping (#3557)** — search JSON keeps original source coordinates while adding `visible`, `visible_column`, and `visible_length` so clients can highlight only text present in the returned snippet.
+
+## 日本語
+
+- **行幅クランプ後の検索 highlight occurrence が可視範囲を返すようになりました (#3557)** — search JSON は元ソース座標を維持しつつ、返却 snippet 内に存在する文字だけを強調できるよう `visible` / `visible_column` / `visible_length` を追加しました。

changelog.d/unreleased/3558.fixed.md

@@ -0,0 +1,20 @@
+---
+category: fixed
+issues:
+  - 3558
+affected:
+  - DEVELOPER_GUIDE.md
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Cli/SearchSnippetFormatter.cs
+  - src/CodeIndex/Mcp/McpToolHandlers.cs
+  - tests/CodeIndex.Tests/McpServerTests.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerSearchHintTests.cs
+---
+
+## English
+
+- **Search JSON now exposes effective snippet options and raw-FTS highlight availability (#3558)** — compact CLI and MCP search rows include effective snippet/mode metadata so clients can distinguish literal highlight support from raw FTS syntax gaps.
+
+## 日本語
+
+- **検索 JSON が有効な snippet options と raw FTS の highlight 可否を返すようになりました (#3558)** — compact CLI と MCP search row に有効な snippet / mode metadata を追加し、literal highlight 対応と raw FTS 構文由来の不足を区別できるようにしました。

changelog.d/unreleased/3561.fixed.md

@@ -0,0 +1,19 @@
+---
+category: fixed
+issues:
+  - 3561
+affected:
+  - DEVELOPER_GUIDE.md
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - src/CodeIndex/Database/DbReader.FilesStatus.cs
+  - src/CodeIndex/Models/QueryResults.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs
+---
+
+## English
+
+- **Find JSON now exposes match spans and snippet truncation context (#3561)** — `cdidx find --json` rows include `length`, `original_line_length`, and `snippet_truncation_context` so clients can highlight repeated file matches and detect line-width elisions without parsing snippet markers.
+
+## 日本語
+
+- **find JSON が match span と snippet truncation context を返すようになりました (#3561)** — `cdidx find --json` の各 row に `length` / `original_line_length` / `snippet_truncation_context` を追加し、クライアントが同一ファイル内の複数一致を highlight し、snippet marker を解析せずに行幅省略を検出できるようにしました。

changelog.d/unreleased/3562.fixed.md

@@ -0,0 +1,23 @@
+---
+category: fixed
+issues:
+  - 3562
+affected:
+  - DEVELOPER_GUIDE.md
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Database/DbReader.FilesStatus.cs
+  - src/CodeIndex/Database/DbSymbolReader.cs
+  - src/CodeIndex/Models/QueryResults.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerSearchTests.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerSymbolTests.cs
+  - tests/CodeIndex.Tests/golden/excerpt.json
+---
+
+## English
+
+- **Excerpt and body JSON now expose range and recovery metadata (#3562)** — excerpt rows include requested/effective ranges, truncation reasons, and replayable recovery commands, while body JSON reports line and byte cap reasons with follow-up excerpt ranges.
+
+## 日本語
+
+- **excerpt と body JSON が range と recovery metadata を返すようになりました (#3562)** — excerpt row に requested/effective range、truncation reason、再実行可能な recovery command を追加し、body JSON でも行数上限と byte 上限の reason と follow-up excerpt range を返すようにしました。

src/CodeIndex/Cli/ExcerptRecoveryCommandFormatter.cs

@@ -0,0 +1,49 @@
+using CodeIndex.Database;
+
+namespace CodeIndex.Cli;
+
+internal static class ExcerptRecoveryCommandFormatter
+{
+    public static void ApplyDbPath(FileExcerptResult excerpt, string dbPath)
+    {
+        ApplyDbPath(excerpt.ContentRecovery, excerpt.Path, dbPath);
+    }
+
+    public static void ApplyDbPath(ExcerptRecoveryHint? recovery, string path, string dbPath)
+    {
+        if (recovery is null)
+            return;
+
+        recovery.Command = BuildCommand(path, recovery.StartLine, recovery.EndLine, dbPath);
+    }
+
+    private static string BuildCommand(string path, int startLine, int endLine, string dbPath)
+    {
+        var dbOption = string.IsNullOrWhiteSpace(dbPath)
+            ? string.Empty
+            : $" --db {QuoteShellArgument(NormalizeDbPath(dbPath))}";
+        return $"cdidx excerpt {QuoteShellArgument(path)}{dbOption} --start {startLine} --end {endLine} --max-line-width 0 --json";
+    }
+
+    private static string NormalizeDbPath(string dbPath)
+    {
+        if (dbPath.StartsWith("file:", StringComparison.OrdinalIgnoreCase))
+            return dbPath;
+
+        var normalized = DbPathResolver.NormalizeDbPath(dbPath);
+        return normalized.StartsWith("file:", StringComparison.OrdinalIgnoreCase)
+            ? normalized
+            : Path.GetFullPath(normalized);
+    }
+
+    private static string QuoteShellArgument(string value)
+    {
+        if (!string.IsNullOrEmpty(value) && value.All(IsSafeShellArgumentChar))
+            return value;
+
+        return "'" + value.Replace("'", "'\\''", StringComparison.Ordinal) + "'";
+    }
+
+    private static bool IsSafeShellArgumentChar(char c)
+        => char.IsLetterOrDigit(c) || c is '/' or '.' or '_' or '-' or ':';
+}

src/CodeIndex/Cli/JsonOutputContracts.cs

@@ -436,10 +436,12 @@ internal sealed record VersionInfoJsonResult(
 [JsonSerializable(typeof(ExportImportCommandRunner.ExportManifest))]
 [JsonSerializable(typeof(ExportImportCommandRunner.ImportDryRunResult))]
 [JsonSerializable(typeof(ExportImportCommandRunner.ImportValidationPhaseResult))]
+[JsonSerializable(typeof(ExcerptRecoveryHint))]
 [JsonSerializable(typeof(ExcerptSemanticToken))]
 [JsonSerializable(typeof(FileDependencyResult))]
 [JsonSerializable(typeof(FileExcerptResult))]
 [JsonSerializable(typeof(FileFindResult))]
+[JsonSerializable(typeof(FileFindSnippetTruncationContext))]
 [JsonSerializable(typeof(FileIssue))]
 [JsonSerializable(typeof(FileResult))]
 [JsonSerializable(typeof(FreshnessHintResult))]
@@ -517,6 +519,7 @@ internal sealed record VersionInfoJsonResult(
 [JsonSerializable(typeof(SearchIssueDraftExportJsonResult))]
 [JsonSerializable(typeof(SearchIssueDraftJsonResult))]
 [JsonSerializable(typeof(SearchIssueDraftSourceJsonResult))]
+[JsonSerializable(typeof(SearchNextMatchHint))]
 [JsonSerializable(typeof(SearchResult))]
 [JsonSerializable(typeof(SearchTermOccurrence))]
 [JsonSerializable(typeof(SearchTruncationContext))]