From c40c1611dd84d115acf0c38f6f8d109d8018bfbe Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 29 Jul 2026 13:21:48 +0900
Subject: [PATCH 1/5] Fix JSON array symbol hierarchy (#4874)

---
 DEVELOPER_GUIDE.md                            |   4 +-
 changelog.d/unreleased/4874.fixed.md          |  19 +++
 .../Database/DbSymbolReader.Outline.cs        |  30 +++-
 .../Symbols/SymbolExtractor.StructuredData.cs | 125 +++++++++++-----
 .../QueryCommandRunnerInspectTests.cs         | 136 ++++++++++++++++++
 tests/CodeIndex.Tests/SymbolExtractorTests.cs |  97 +++++++++++++
 6 files changed, 363 insertions(+), 48 deletions(-)
 create mode 100644 changelog.d/unreleased/4874.fixed.md

diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
index 9c347a6ce..4b85f4d34 100644
--- a/DEVELOPER_GUIDE.md
+++ b/DEVELOPER_GUIDE.md
@@ -1523,7 +1523,7 @@ Extractor strategy by language surface:
 | Scala | Uses a separate block-call pass for `name { ... }` / `name { x => ... }` forms so idiomatic calls such as `foreach {}`, `Try {}`, and `synchronized {}` stay visible. |
 | Common Lisp / Racket | Use a lightweight S-expression scanner that masks strings, line comments, and `#| ... |#` block comments before extracting definitions and function ranges. |
 | HTML | Uses a dedicated character-level state machine instead of the regex pattern loop. It walks tag openers, quoted/unquoted attribute values including multi-line values, and masks `<script>` / `<style>` / `<textarea>` / `<title>` bodies plus `<!-- ... -->` comments so attribute-lookalike strings inside those regions do not leak phantom symbols. |
-| JSON / JSON Lines | JSON emits `object`, `array`, `property`, and bounded primitive-array `value` symbols with indexed paths. `.jsonl` and `.ndjson` parse each non-empty physical line independently, prefix symbols with a stable zero-based record path such as `[0].result.path`, and emit repository-local path references from each valid record without flattening malformed neighbors. |
+| JSON / JSON Lines | JSON emits `object`, `array`, `property`, and bounded primitive-array `value` symbols with indexed paths. Array indexes attach directly to the parent path (`command_cases[0]`, not `command_cases.command_cases[0]`), and object/array parent kinds preserve the hierarchy used by outline depth. Root arrays start at paths such as `[0]`. `.jsonl` and `.ndjson` parse each non-empty physical line independently, prefix symbols with a stable zero-based record path such as `[0].result.path`, and emit repository-local path references from each valid record without flattening malformed neighbors. |
 | TOML / repository metadata | TOML tables and keys, EditorConfig sections and keys, Git/Docker ignore rules, Git attribute rules/attributes, and `.rules` blocks/keys are emitted as bounded structural symbols. References are limited to repository-local paths or globs; remote URLs, absolute filesystem paths, and parent traversal are suppressed. |
 | Windows application manifests | Manifest element paths, assembly identities, execution levels, and supported-OS values remain structural symbols. Dependent assembly identities emit `dependency` references, while local `file`, `codeBase`, and probing paths emit `project_reference` edges. |
 | XML / NuGet.config | Generic XML emits bounded element and attribute paths. NuGet.config additionally promotes package sources, source mappings, signature validation mode, trusted signer names, certificate fingerprints, and `allowUntrustedRoot` values to semantic `property` symbols with `nuget.*` subkinds. |
@@ -4875,7 +4875,7 @@ LIMIT 20;
 | Scala | `name { ... }` / `name { x => ... }` 形式を拾う専用の block-call path があり、`foreach {}`、`Try {}`、`synchronized {}` のような慣用的な呼び出しも graph から消えないようにしています。 |
 | Common Lisp / Racket | 文字列、行 comment、`#| ... |#` block comment を mask してから definition と function range を抽出する軽量な S-expression scanner を使います。 |
 | HTML | 汎用の正規表現 loop を使わず、専用の文字単位 state machine で tag opener、引用符付き/なし attribute value（複数行値を含む）、`<script>` / `<style>` / `<textarea>` / `<title>` body、`<!-- ... -->` comment を扱い、attribute 名に似た body 内文字列から phantom symbol が漏れないようにします。 |
-| JSON / JSON Lines | JSON は `object`、`array`、`property` と、上限付きの primitive-array `value` symbol を index 付き path で出力します。`.jsonl` と `.ndjson` は空でない物理行を個別に parse し、`[0].result.path` のような安定した 0 始まり record path を付けます。各有効 record から repository-local path reference を出し、不正な隣接 record の内容は平坦化しません。 |
+| JSON / JSON Lines | JSON は `object`、`array`、`property` と、上限付きの primitive-array `value` symbol を index 付き path で出力します。配列 index は親 path に直接連結し（`command_cases.command_cases[0]` ではなく `command_cases[0]`）、object / array の親 kind を保持して outline の depth に階層を反映します。root array は `[0]` のような path から始まります。`.jsonl` と `.ndjson` は空でない物理行を個別に parse し、`[0].result.path` のような安定した 0 始まり record path を付けます。各有効 record から repository-local path reference を出し、不正な隣接 record の内容は平坦化しません。 |
 | TOML / repository metadata | TOML の table / key、EditorConfig の section / key、Git / Docker ignore rule、Git attribute の rule / attribute、`.rules` の block / key を上限付き structural symbol として出力します。reference は repository-local な path / glob に限定し、remote URL、絶対 filesystem path、親 directory traversal は抑止します。 |
 | Windows application manifest | manifest element path、assembly identity、execution level、supported OS value を structural symbol として維持します。依存 assembly identity は `dependency` reference、local な `file` / `codeBase` / probing path は `project_reference` edge を出力します。 |
 | XML / NuGet.config | 汎用 XML は上限付きの element / attribute path を出力します。NuGet.config ではさらに package source、source mapping、署名検証モード、trusted signer 名、証明書 fingerprint、`allowUntrustedRoot` の値を `nuget.*` subkind 付きの semantic `property` symbol にします。 |
diff --git a/changelog.d/unreleased/4874.fixed.md b/changelog.d/unreleased/4874.fixed.md
new file mode 100644
index 000000000..879529875
--- /dev/null
+++ b/changelog.d/unreleased/4874.fixed.md
@@ -0,0 +1,19 @@
+---
+category: fixed
+issues:
+  - 4874
+affected:
+  - src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
+  - src/CodeIndex/Database/DbSymbolReader.Outline.cs
+  - tests/CodeIndex.Tests/SymbolExtractorTests.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **JSON arrays now preserve their paths and hierarchy (#4874)** — array indexes attach directly to their parent path, root arrays are extracted, and object/array parent metadata keeps `symbols`, `outline`, and `definition` results at the correct depth without duplicated names such as `command_cases.command_cases[0]`.
+
+## 日本語
+
+- **JSON 配列の path と階層を正しく保持するようになりました (#4874)** — 配列 index を親 path に直接連結し、root array を抽出するとともに、object / array の親 metadata を保持することで、`symbols`、`outline`、`definition` が `command_cases.command_cases[0]` のような重複名を出さず正しい depth を返すようになりました。
diff --git a/src/CodeIndex/Database/DbSymbolReader.Outline.cs b/src/CodeIndex/Database/DbSymbolReader.Outline.cs
index d89d3da18..e59648b58 100644
--- a/src/CodeIndex/Database/DbSymbolReader.Outline.cs
+++ b/src/CodeIndex/Database/DbSymbolReader.Outline.cs
@@ -177,11 +177,22 @@ private static string BuildOutlineSymbolPath(string? containerQualifiedName, str
         if (string.IsNullOrWhiteSpace(containerQualifiedName))
             return name;
 
-        return name.StartsWith(containerQualifiedName + ".", StringComparison.Ordinal)
+        return IsQualifiedOutlineChildPath(containerQualifiedName, name)
             ? name
             : $"{containerQualifiedName}.{name}";
     }
 
+    private static bool IsQualifiedOutlineChildPath(string containerPath, string childPath)
+    {
+        if (!childPath.StartsWith(containerPath, StringComparison.Ordinal)
+            || childPath.Length <= containerPath.Length)
+        {
+            return false;
+        }
+
+        return childPath[containerPath.Length] is '.' or '[';
+    }
+
     private static bool IsCallableOutlineSymbol(string kind)
     {
         return kind is "function" or "operator" or "method" or "constructor";
@@ -388,9 +399,14 @@ private static int FindOutlineContainerIndex(List<OutlineSymbol> symbols, int ch
             return null;
 
         var suffix = "." + symbol.Name;
-        return symbol.Path.EndsWith(suffix, StringComparison.Ordinal)
-            ? symbol.Path[..^suffix.Length]
-            : null;
+        if (symbol.Path.EndsWith(suffix, StringComparison.Ordinal))
+            return symbol.Path[..^suffix.Length];
+
+        return !string.IsNullOrWhiteSpace(symbol.ContainerName)
+            && string.Equals(symbol.Path, symbol.Name, StringComparison.Ordinal)
+            && IsQualifiedOutlineChildPath(symbol.ContainerName, symbol.Name)
+                ? symbol.ContainerName
+                : null;
     }
 
     private static bool IsOutlineContainerMatch(OutlineSymbol candidate, int childLine)
@@ -398,9 +414,9 @@ private static bool IsOutlineContainerMatch(OutlineSymbol candidate, int childLi
         if (candidate.StartLine <= childLine && candidate.EndLine >= childLine)
             return true;
 
-        // file-scoped namespaces have no body range, so they do not enclose children by lines
-        // even though they are the correct logical container.
-        return candidate.Kind == "namespace"
+        // File-scoped namespaces and structured-data containers have no body range, so they
+        // do not enclose children by lines even though their exact paths identify the parent.
+        return candidate.Kind is "namespace" or "object" or "array" or "record"
             && candidate.BodyStartLine == null
             && candidate.BodyEndLine == null
             && candidate.Line <= childLine;
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
index 92db92bf2..19f9b98c8 100644
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
@@ -50,13 +50,6 @@ private static List<SymbolRecord> ExtractJsonSymbols(long fileId, string content
                 JsonCommentHandling.Skip,
                 allowTrailingCommas: true);
 
-            if (document.RootElement.ValueKind != JsonValueKind.Object)
-                return [];
-
-            var rootProperties = document.RootElement.EnumerateObject();
-            if (!rootProperties.MoveNext())
-                return [];
-
             var symbols = CreateSymbolListForLines(lines.Length);
             int[]? lineStarts = null;
             var searchOffset = 0;
@@ -66,19 +59,40 @@ private static List<SymbolRecord> ExtractJsonSymbols(long fileId, string content
                 && content.IndexOf('\r', StringComparison.Ordinal) < 0
                 ? null
                 : BuildJsonPropertyLineQueues(content);
-            ExtractJsonObjectSymbols(
-                fileId,
-                content,
-                lines,
-                ref lineStarts,
-                document.RootElement,
-                parentPath: null,
-                ref searchOffset,
-                symbols,
-                propertyLines,
-                depth: 0,
-                ref traversalNodes,
-                ref truncated);
+            if (document.RootElement.ValueKind == JsonValueKind.Object)
+            {
+                ExtractJsonObjectSymbols(
+                    fileId,
+                    content,
+                    lines,
+                    ref lineStarts,
+                    document.RootElement,
+                    parentPath: null,
+                    ref searchOffset,
+                    symbols,
+                    propertyLines,
+                    depth: 0,
+                    ref traversalNodes,
+                    ref truncated);
+            }
+            else if (document.RootElement.ValueKind == JsonValueKind.Array)
+            {
+                ExtractJsonArraySymbols(
+                    fileId,
+                    content,
+                    lines,
+                    ref lineStarts,
+                    document.RootElement,
+                    arrayPath: string.Empty,
+                    arrayLine: 1,
+                    ref searchOffset,
+                    symbols,
+                    propertyLines,
+                    depth: 0,
+                    ref traversalNodes,
+                    ref truncated);
+            }
+
             return symbols;
         }
         catch (Exception ex) when (ex is JsonException or InvalidDataException)
@@ -117,10 +131,8 @@ private static void ExtractJsonObjectSymbols(
 
             traversalNodes++;
             var propertyName = property.Name;
-            var nameLength = string.IsNullOrEmpty(parentPath)
-                ? propertyName.Length
-                : parentPath.Length + 1 + propertyName.Length;
-            if (nameLength > StructuredDataMaxPathLength)
+            var name = CombineStructuredDataPath(parentPath, propertyName);
+            if (name.Length > StructuredDataMaxPathLength)
             {
                 if (propertyLines != null)
                     _ = TryDequeueJsonPropertyLine(propertyLines, propertyName, out _);
@@ -128,9 +140,6 @@ private static void ExtractJsonObjectSymbols(
                 continue;
             }
 
-            var name = string.IsNullOrEmpty(parentPath)
-                ? propertyName
-                : parentPath + "." + propertyName;
             var propertyOffset = FindJsonPropertyOffset(content, propertyName, ref searchOffset);
             var line = propertyLines != null
                 && TryDequeueJsonPropertyLine(propertyLines, propertyName, out var mappedLine)
@@ -144,7 +153,17 @@ private static void ExtractJsonObjectSymbols(
                 _ => "property",
             };
 
-            if (!TryAddStructuredDataSymbol(fileId, kind, name, line, lines, parentPath, symbols, "structured_data_symbol_budget_exceeded", ref truncated))
+            if (!TryAddStructuredDataSymbol(
+                    fileId,
+                    kind,
+                    name,
+                    line,
+                    lines,
+                    parentPath,
+                    symbols,
+                    "structured_data_symbol_budget_exceeded",
+                    ref truncated,
+                    parentKind: "object"))
                 return;
 
             if (property.Value.ValueKind == JsonValueKind.Object)
@@ -206,7 +225,7 @@ private static void ExtractJsonArraySymbols(
             }
 
             traversalNodes++;
-            var itemPath = $"{arrayPath}[{index}]";
+            var itemPath = CombineStructuredDataPath(arrayPath, $"[{index}]");
             if (itemPath.Length > StructuredDataMaxPathLength)
             {
                 DrainJsonPropertyLines(item, propertyLines);
@@ -221,7 +240,17 @@ private static void ExtractJsonArraySymbols(
                 _ => "value",
             };
             var itemLine = FindJsonElementLine(content, lines, ref lineStarts, item, arrayLine, ref searchOffset);
-            if (!TryAddStructuredDataSymbol(fileId, kind, itemPath, itemLine, lines, arrayPath, symbols, "structured_data_symbol_budget_exceeded", ref truncated))
+            if (!TryAddStructuredDataSymbol(
+                    fileId,
+                    kind,
+                    itemPath,
+                    itemLine,
+                    lines,
+                    string.IsNullOrEmpty(arrayPath) ? null : arrayPath,
+                    symbols,
+                    "structured_data_symbol_budget_exceeded",
+                    ref truncated,
+                    parentKind: "array"))
                 return;
 
             if (item.ValueKind == JsonValueKind.Object)
@@ -337,7 +366,7 @@ private static List<SymbolRecord> ExtractJsonLinesSymbols(long fileId, string co
                     StructuredDataMaxJsonDepth + 2,
                     JsonCommentHandling.Skip,
                     allowTrailingCommas: true);
-                if (document.RootElement.ValueKind != JsonValueKind.Object)
+                if (document.RootElement.ValueKind is not (JsonValueKind.Object or JsonValueKind.Array))
                 {
                     recordIndex++;
                     continue;
@@ -356,14 +385,20 @@ private static List<SymbolRecord> ExtractJsonLinesSymbols(long fileId, string co
                     if (symbols.Count >= StructuredDataMaxSymbols)
                         return symbols;
 
-                    symbol.Name = recordPath + "." + symbol.Name;
+                    symbol.Name = CombineStructuredDataPath(recordPath, symbol.Name);
                     symbol.Line = lineIndex + 1;
                     symbol.StartLine = lineIndex + 1;
                     symbol.EndLine = lineIndex + 1;
                     symbol.Signature = LimitStructuredDataSignature(recordText.Trim());
-                    symbol.ContainerName = symbol.ContainerName == null
-                        ? recordPath
-                        : recordPath + "." + symbol.ContainerName;
+                    if (symbol.ContainerName == null)
+                    {
+                        symbol.ContainerName = recordPath;
+                        symbol.ContainerKind = "record";
+                    }
+                    else
+                    {
+                        symbol.ContainerName = CombineStructuredDataPath(recordPath, symbol.ContainerName);
+                    }
                     symbol.ContainerQualifiedName = symbol.ContainerName;
                     symbols.Add(symbol);
                 }
@@ -502,11 +537,12 @@ private static bool TryAddStructuredDataSymbol(
         string? parentPath,
         List<SymbolRecord> symbols,
         string category,
-        ref bool truncated)
+        ref bool truncated,
+        string? parentKind = "namespace")
     {
         if (symbols.Count < StructuredDataMaxSymbols)
         {
-            symbols.Add(CreateStructuredDataSymbol(fileId, kind, name, line, lines, parentPath));
+            symbols.Add(CreateStructuredDataSymbol(fileId, kind, name, line, lines, parentPath, parentKind));
             return true;
         }
 
@@ -587,7 +623,8 @@ private static SymbolRecord CreateStructuredDataSymbol(
         string name,
         int line,
         string[] lines,
-        string? parentPath)
+        string? parentPath,
+        string? parentKind)
     {
         var signatureIndex = Math.Clamp(line - 1, 0, Math.Max(0, lines.Length - 1));
         return new SymbolRecord
@@ -599,12 +636,22 @@ private static SymbolRecord CreateStructuredDataSymbol(
             StartLine = line,
             EndLine = line,
             Signature = lines.Length == 0 ? null : LimitStructuredDataLineSignature(lines[signatureIndex]),
-            ContainerKind = parentPath == null ? null : "namespace",
+            ContainerKind = parentPath == null ? null : parentKind,
             ContainerName = parentPath,
             ContainerQualifiedName = parentPath,
         };
     }
 
+    private static string CombineStructuredDataPath(string? parentPath, string childPath)
+    {
+        if (string.IsNullOrEmpty(parentPath))
+            return childPath;
+
+        return childPath.Length > 0 && childPath[0] == '['
+            ? parentPath + childPath
+            : parentPath + "." + childPath;
+    }
+
     private static string LimitStructuredDataSignature(string signature) =>
         signature.Length <= StructuredDataMaxSignatureLength
             ? signature
diff --git a/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs b/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
index d0284db55..cd58fcf88 100644
--- a/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+++ b/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
@@ -18,6 +18,142 @@ private static JsonElement GetInspectCandidateBundle(JsonElement analysis, strin
                 qualifiedName,
                 StringComparison.Ordinal)));
 
+    [Fact]
+    public void RunSymbolsOutlineAndDefinition_JsonArraysPreservePathsDepthAndPagination_Issue4874()
+    {
+        var projectRoot = TestProjectHelper.CreateTempProject("cdidx_json_array_paths_4874");
+        try
+        {
+            var dbPath = TestProjectHelper.CreateProjectDb(projectRoot);
+            TestProjectHelper.InsertIndexedFile(dbPath, "src/fixture.json", "json", """
+                {
+                  "command_cases": [
+                    {
+                      "command_cases": "nested",
+                      "nested": [
+                        ["scalar", { "leaf": true }],
+                        [],
+                        {}
+                      ]
+                    },
+                    7,
+                    [],
+                    {}
+                  ],
+                  "empty_object": {},
+                  "empty_array": []
+                }
+                """);
+            var commonSymbolArgs = new[]
+            {
+                "--db", dbPath,
+                "--lang", "json",
+                "--path", "src/fixture.json",
+                "--sort", "path",
+            };
+
+            var (allExitCode, allStdout, allStderr) = CaptureConsole(() => QueryCommandRunner.RunSymbols(
+                [.. commonSymbolArgs, "--json=array", "--limit", "100"],
+                _jsonOptions));
+            using var allDocument = ParseJsonOutput(allStdout);
+            var allSymbols = allDocument.RootElement.EnumerateArray().ToArray();
+
+            var commonOutlineArgs = new[] { "src/fixture.json", "--db", dbPath, "--json" };
+            var (outlineExitCode, outlineStdout, outlineStderr) = CaptureConsole(() => QueryCommandRunner.RunOutline(
+                commonOutlineArgs,
+                _jsonOptions));
+            using var outlineDocument = ParseJsonOutput(outlineStdout);
+            var outlineSymbols = outlineDocument.RootElement.GetProperty("symbols").EnumerateArray().ToArray();
+
+            var (firstPageExitCode, firstPageStdout, firstPageStderr) = CaptureConsole(() => QueryCommandRunner.RunOutline(
+                [.. commonOutlineArgs, "--limit", "4"],
+                _jsonOptions));
+            using var firstPageDocument = ParseJsonOutput(firstPageStdout);
+            var firstPage = firstPageDocument.RootElement;
+            var firstPageSymbols = firstPage.GetProperty("symbols").EnumerateArray().ToArray();
+            var nextCursor = firstPage.GetProperty("next_cursor").GetString();
+
+            var (secondPageExitCode, secondPageStdout, secondPageStderr) = CaptureConsole(() => QueryCommandRunner.RunOutline(
+                [.. commonOutlineArgs, "--limit", "4", "--cursor", nextCursor!],
+                _jsonOptions));
+            using var secondPageDocument = ParseJsonOutput(secondPageStdout);
+            var secondPageSymbols = secondPageDocument.RootElement.GetProperty("symbols").EnumerateArray().ToArray();
+            var pagedPaths = firstPageSymbols
+                .Concat(secondPageSymbols)
+                .Select(symbol => symbol.GetProperty("path").GetString())
+                .ToArray();
+
+            var (definitionExitCode, definitionStdout, definitionStderr) = CaptureConsole(() => QueryCommandRunner.RunDefinition(
+                [
+                    "command_cases[0].command_cases",
+                    "--db", dbPath,
+                    "--json",
+                    "--exact-name",
+                    "--lang", "json",
+                    "--path", "src/fixture.json",
+                ],
+                _jsonOptions));
+            using var definitionDocument = ParseJsonOutput(definitionStdout);
+            var definition = definitionDocument.RootElement;
+
+            Assert.Equal(CommandExitCodes.Success, allExitCode);
+            Assert.Equal(string.Empty, allStderr);
+            Assert.Equal(CommandExitCodes.Success, outlineExitCode);
+            Assert.Equal(string.Empty, outlineStderr);
+            Assert.Equal(CommandExitCodes.Success, firstPageExitCode);
+            Assert.Equal(string.Empty, firstPageStderr);
+            Assert.Equal(CommandExitCodes.Success, secondPageExitCode);
+            Assert.Equal(string.Empty, secondPageStderr);
+            Assert.False(string.IsNullOrWhiteSpace(nextCursor));
+            Assert.Equal(
+                outlineSymbols.Take(8).Select(symbol => symbol.GetProperty("path").GetString()),
+                pagedPaths);
+            Assert.Equal(pagedPaths.Length, pagedPaths.Distinct(StringComparer.Ordinal).Count());
+
+            var arrayObject = Assert.Single(allSymbols, symbol => symbol.GetProperty("name").GetString() == "command_cases[0]");
+            Assert.Equal("array", arrayObject.GetProperty("container_kind").GetString());
+            Assert.Equal("command_cases", arrayObject.GetProperty("container_name").GetString());
+
+            Assert.DoesNotContain(
+                outlineSymbols,
+                symbol => symbol.GetProperty("path").GetString()!.Contains("command_cases.command_cases[0]", StringComparison.Ordinal));
+            AssertOutlineJsonSymbol(outlineSymbols, "command_cases", "command_cases", 0, null, null);
+            AssertOutlineJsonSymbol(outlineSymbols, "command_cases[0]", "command_cases[0]", 1, "array", "command_cases");
+            AssertOutlineJsonSymbol(outlineSymbols, "command_cases[0].command_cases", "command_cases[0].command_cases", 2, "object", "command_cases[0]");
+            AssertOutlineJsonSymbol(outlineSymbols, "command_cases[0].nested[0][1].leaf", "command_cases[0].nested[0][1].leaf", 5, "object", "command_cases[0].nested[0][1]");
+            AssertOutlineJsonSymbol(outlineSymbols, "command_cases[2]", "command_cases[2]", 1, "array", "command_cases");
+            AssertOutlineJsonSymbol(outlineSymbols, "command_cases[3]", "command_cases[3]", 1, "array", "command_cases");
+            AssertOutlineJsonSymbol(outlineSymbols, "empty_object", "empty_object", 0, null, null);
+            AssertOutlineJsonSymbol(outlineSymbols, "empty_array", "empty_array", 0, null, null);
+
+            Assert.Equal(CommandExitCodes.Success, definitionExitCode);
+            Assert.Equal(string.Empty, definitionStderr);
+            Assert.Equal("command_cases[0].command_cases", definition.GetProperty("name").GetString());
+            Assert.Equal(4, definition.GetProperty("line").GetInt32());
+            Assert.Equal("object", definition.GetProperty("container_kind").GetString());
+            Assert.Equal("command_cases[0]", definition.GetProperty("container_name").GetString());
+        }
+        finally
+        {
+            TestProjectHelper.DeleteDirectory(projectRoot);
+        }
+    }
+
+    private static void AssertOutlineJsonSymbol(
+        JsonElement[] symbols,
+        string name,
+        string path,
+        int depth,
+        string? containerKind,
+        string? containerName)
+    {
+        var symbol = Assert.Single(symbols, candidate => candidate.GetProperty("name").GetString() == name);
+        Assert.Equal(path, symbol.GetProperty("path").GetString());
+        Assert.Equal(depth, symbol.GetProperty("depth").GetInt32());
+        Assert.Equal(containerKind, symbol.TryGetProperty("container_kind", out var kind) ? kind.GetString() : null);
+        Assert.Equal(containerName, symbol.TryGetProperty("container_name", out var container) ? container.GetString() : null);
+    }
+
     [Fact]
     public void RunInspect_CompactCandidateBundlesOmitBodiesAndKeepIndependentTruncationCounts()
     {
diff --git a/tests/CodeIndex.Tests/SymbolExtractorTests.cs b/tests/CodeIndex.Tests/SymbolExtractorTests.cs
index 6711655a0..205255f3f 100644
--- a/tests/CodeIndex.Tests/SymbolExtractorTests.cs
+++ b/tests/CodeIndex.Tests/SymbolExtractorTests.cs
@@ -841,6 +841,103 @@ public void Extract_Json_IndexesConfigurationKeyPaths()
         Assert.Contains(symbols, symbol => symbol.Kind == "property" && symbol.Name == "dependencies.xunit" && symbol.ContainerName == "dependencies");
     }
 
+    [Fact]
+    public void Extract_Json_ArraysPreservePathsParentsAndEmptyContainers_Issue4874()
+    {
+        const string objectRoot = """
+            {
+              "command_cases": [
+                {
+                  "command_cases": "nested",
+                  "nested": [
+                    ["scalar", { "leaf": true }],
+                    [],
+                    {}
+                  ]
+                },
+                7,
+                [],
+                {}
+              ],
+              "empty_object": {},
+              "empty_array": []
+            }
+            """;
+        const string arrayRoot = """
+            [
+              { "name": "first" },
+              1,
+              [2],
+              [],
+              {}
+            ]
+            """;
+        const string jsonLines = """
+            {"items":[{"leaf":1}]}
+            [{"name":"first"},[]]
+            """;
+
+        var objectSymbols = SymbolExtractor.Extract(1, "json", objectRoot);
+        var rootSymbols = SymbolExtractor.Extract(1, "json", arrayRoot);
+        var jsonLineSymbols = SymbolExtractor.Extract(1, "jsonl", jsonLines);
+
+        Assert.Collection(
+            objectSymbols,
+            symbol => AssertStructuredJsonSymbol(symbol, "array", "command_cases", 2, null, null),
+            symbol => AssertStructuredJsonSymbol(symbol, "object", "command_cases[0]", 3, "array", "command_cases"),
+            symbol => AssertStructuredJsonSymbol(symbol, "property", "command_cases[0].command_cases", 4, "object", "command_cases[0]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "array", "command_cases[0].nested", 5, "object", "command_cases[0]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "array", "command_cases[0].nested[0]", 6, "array", "command_cases[0].nested"),
+            symbol => AssertStructuredJsonSymbol(symbol, "value", "command_cases[0].nested[0][0]", 6, "array", "command_cases[0].nested[0]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "object", "command_cases[0].nested[0][1]", 6, "array", "command_cases[0].nested[0]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "property", "command_cases[0].nested[0][1].leaf", 6, "object", "command_cases[0].nested[0][1]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "array", "command_cases[0].nested[1]", 7, "array", "command_cases[0].nested"),
+            symbol => AssertStructuredJsonSymbol(symbol, "object", "command_cases[0].nested[2]", 8, "array", "command_cases[0].nested"),
+            symbol => AssertStructuredJsonSymbol(symbol, "value", "command_cases[1]", 11, "array", "command_cases"),
+            symbol => AssertStructuredJsonSymbol(symbol, "array", "command_cases[2]", 12, "array", "command_cases"),
+            symbol => AssertStructuredJsonSymbol(symbol, "object", "command_cases[3]", 13, "array", "command_cases"),
+            symbol => AssertStructuredJsonSymbol(symbol, "object", "empty_object", 15, null, null),
+            symbol => AssertStructuredJsonSymbol(symbol, "array", "empty_array", 16, null, null));
+        Assert.Collection(
+            rootSymbols,
+            symbol => AssertStructuredJsonSymbol(symbol, "object", "[0]", 2, null, null),
+            symbol => AssertStructuredJsonSymbol(symbol, "property", "[0].name", 2, "object", "[0]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "value", "[1]", 3, null, null),
+            symbol => AssertStructuredJsonSymbol(symbol, "array", "[2]", 4, null, null),
+            symbol => AssertStructuredJsonSymbol(symbol, "value", "[2][0]", 4, "array", "[2]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "array", "[3]", 5, null, null),
+            symbol => AssertStructuredJsonSymbol(symbol, "object", "[4]", 6, null, null));
+        Assert.Collection(
+            jsonLineSymbols,
+            symbol => AssertStructuredJsonSymbol(symbol, "record", "[0]", 1, null, null),
+            symbol => AssertStructuredJsonSymbol(symbol, "array", "[0].items", 1, "record", "[0]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "object", "[0].items[0]", 1, "array", "[0].items"),
+            symbol => AssertStructuredJsonSymbol(symbol, "property", "[0].items[0].leaf", 1, "object", "[0].items[0]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "record", "[1]", 2, null, null),
+            symbol => AssertStructuredJsonSymbol(symbol, "object", "[1][0]", 2, "record", "[1]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "property", "[1][0].name", 2, "object", "[1][0]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "array", "[1][1]", 2, "record", "[1]"));
+        Assert.Empty(SymbolExtractor.Extract(1, "json", "[]"));
+    }
+
+    private static void AssertStructuredJsonSymbol(
+        SymbolRecord symbol,
+        string kind,
+        string name,
+        int line,
+        string? containerKind,
+        string? containerName)
+    {
+        Assert.Equal(kind, symbol.Kind);
+        Assert.Equal(name, symbol.Name);
+        Assert.Equal(line, symbol.Line);
+        Assert.Equal(line, symbol.StartLine);
+        Assert.Equal(line, symbol.EndLine);
+        Assert.Equal(containerKind, symbol.ContainerKind);
+        Assert.Equal(containerName, symbol.ContainerName);
+        Assert.Equal(containerName, symbol.ContainerQualifiedName);
+    }
+
     [Fact]
     public void Extract_Json_IndexesReflectionSensitivePropertyNames_Issue4709()
     {

From bad3d791a7f672c4878d6be5bd4588cb253fa0be Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 29 Jul 2026 14:04:53 +0900
Subject: [PATCH 2/5] Address JSON hierarchy review findings (#4874)

---
 changelog.d/unreleased/4874.fixed.md          |  4 +
 .../Database/DbSymbolReader.Outline.cs        | 83 +++++++++++++++----
 .../Symbols/SymbolExtractor.Contracts.cs      |  8 +-
 .../Symbols/SymbolExtractor.StructuredData.cs | 51 ++++++++----
 tests/CodeIndex.Tests/DatabaseTests.cs        | 25 ++++++
 .../IndexCommandRunnerTests.cs                |  4 +-
 .../QueryCommandRunnerInspectTests.cs         | 33 ++++++++
 .../SymbolExtractorRepositoryMetadataTests.cs |  6 +-
 tests/CodeIndex.Tests/SymbolExtractorTests.cs | 18 ++--
 9 files changed, 187 insertions(+), 45 deletions(-)

diff --git a/changelog.d/unreleased/4874.fixed.md b/changelog.d/unreleased/4874.fixed.md
index 879529875..75dac7b20 100644
--- a/changelog.d/unreleased/4874.fixed.md
+++ b/changelog.d/unreleased/4874.fixed.md
@@ -4,7 +4,11 @@ issues:
   - 4874
 affected:
   - src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
+  - src/CodeIndex/Indexer/Symbols/SymbolExtractor.Contracts.cs
   - src/CodeIndex/Database/DbSymbolReader.Outline.cs
+  - tests/CodeIndex.Tests/DatabaseTests.cs
+  - tests/CodeIndex.Tests/IndexCommandRunnerTests.cs
+  - tests/CodeIndex.Tests/SymbolExtractorRepositoryMetadataTests.cs
   - tests/CodeIndex.Tests/SymbolExtractorTests.cs
   - tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
   - DEVELOPER_GUIDE.md
diff --git a/src/CodeIndex/Database/DbSymbolReader.Outline.cs b/src/CodeIndex/Database/DbSymbolReader.Outline.cs
index e59648b58..83947e81b 100644
--- a/src/CodeIndex/Database/DbSymbolReader.Outline.cs
+++ b/src/CodeIndex/Database/DbSymbolReader.Outline.cs
@@ -104,6 +104,7 @@ FROM symbols s
             SqliteCommandPolicy.AddNullableText(symCmd, "@lang", lang);
 
         var symbols = new List<OutlineSymbol>();
+        var isJsonStructuredData = lang is "json" or "jsonl";
         using (var reader = symCmd.ExecuteTrackedReader())
         {
             while (reader.TrackedRead())
@@ -123,7 +124,10 @@ FROM symbols s
                     Signature = GetNullableString(reader, 7),
                     ContainerKind = GetNullableString(reader, 8),
                     ContainerName = containerName,
-                    Path = BuildOutlineSymbolPath(containerQualifiedName ?? containerName, name),
+                    Path = BuildOutlineSymbolPath(
+                        containerQualifiedName ?? containerName,
+                        name,
+                        isJsonStructuredData),
                     Visibility = GetNullableString(reader, 11),
                     ReturnType = GetNullableString(reader, 12),
                     ReferenceCount = GetNullableInt32(reader, 13),
@@ -131,7 +135,7 @@ FROM symbols s
             }
         }
 
-        PopulateOutlineDepths(symbols);
+        PopulateOutlineDepths(symbols, isJsonStructuredData);
         ApplyQueryOutputSignatureLimits(symbols);
         PopulateOutlineDisplayNames(symbols, lang);
 
@@ -172,17 +176,23 @@ private static string BuildOutlineDisplayName(OutlineSymbol symbol, string? lang
             : symbol.Name;
     }
 
-    private static string BuildOutlineSymbolPath(string? containerQualifiedName, string name)
+    private static string BuildOutlineSymbolPath(
+        string? containerQualifiedName,
+        string name,
+        bool allowArrayIndexBoundary)
     {
         if (string.IsNullOrWhiteSpace(containerQualifiedName))
             return name;
 
-        return IsQualifiedOutlineChildPath(containerQualifiedName, name)
+        return IsQualifiedOutlineChildPath(containerQualifiedName, name, allowArrayIndexBoundary)
             ? name
             : $"{containerQualifiedName}.{name}";
     }
 
-    private static bool IsQualifiedOutlineChildPath(string containerPath, string childPath)
+    private static bool IsQualifiedOutlineChildPath(
+        string containerPath,
+        string childPath,
+        bool allowArrayIndexBoundary)
     {
         if (!childPath.StartsWith(containerPath, StringComparison.Ordinal)
             || childPath.Length <= containerPath.Length)
@@ -190,7 +200,8 @@ private static bool IsQualifiedOutlineChildPath(string containerPath, string chi
             return false;
         }
 
-        return childPath[containerPath.Length] is '.' or '[';
+        var boundary = childPath[containerPath.Length];
+        return boundary == '.' || (allowArrayIndexBoundary && boundary == '[');
     }
 
     private static bool IsCallableOutlineSymbol(string kind)
@@ -338,15 +349,27 @@ private static string SimplifyParameterForOutline(string parameter, string? lang
         return string.Join(" ", parts.Take(parts.Length - 1));
     }
 
-    private static void PopulateOutlineDepths(List<OutlineSymbol> symbols)
+    private static void PopulateOutlineDepths(
+        List<OutlineSymbol> symbols,
+        bool isJsonStructuredData)
     {
         var depthCache = new Dictionary<int, int>();
         var activeStack = new HashSet<int>();
         for (var i = 0; i < symbols.Count; i++)
-            symbols[i].Depth = GetOutlineDepth(symbols, i, depthCache, activeStack);
+            symbols[i].Depth = GetOutlineDepth(
+                symbols,
+                i,
+                depthCache,
+                activeStack,
+                isJsonStructuredData);
     }
 
-    private static int GetOutlineDepth(List<OutlineSymbol> symbols, int index, Dictionary<int, int> depthCache, HashSet<int> activeStack)
+    private static int GetOutlineDepth(
+        List<OutlineSymbol> symbols,
+        int index,
+        Dictionary<int, int> depthCache,
+        HashSet<int> activeStack,
+        bool isJsonStructuredData)
     {
         if (depthCache.TryGetValue(index, out var cachedDepth))
             return cachedDepth;
@@ -358,9 +381,19 @@ private static int GetOutlineDepth(List<OutlineSymbol> symbols, int index, Dicti
         var depth = 0;
         if (!string.IsNullOrEmpty(symbol.ContainerName))
         {
-            var parentIndex = FindOutlineContainerIndex(symbols, index, symbol.ContainerName, symbol.ContainerKind);
+            var parentIndex = FindOutlineContainerIndex(
+                symbols,
+                index,
+                symbol.ContainerName,
+                symbol.ContainerKind,
+                isJsonStructuredData);
             if (parentIndex >= 0)
-                depth = GetOutlineDepth(symbols, parentIndex, depthCache, activeStack) + 1;
+                depth = GetOutlineDepth(
+                    symbols,
+                    parentIndex,
+                    depthCache,
+                    activeStack,
+                    isJsonStructuredData) + 1;
         }
 
         activeStack.Remove(index);
@@ -368,10 +401,15 @@ private static int GetOutlineDepth(List<OutlineSymbol> symbols, int index, Dicti
         return depth;
     }
 
-    private static int FindOutlineContainerIndex(List<OutlineSymbol> symbols, int childIndex, string containerName, string? containerKind)
+    private static int FindOutlineContainerIndex(
+        List<OutlineSymbol> symbols,
+        int childIndex,
+        string containerName,
+        string? containerKind,
+        bool isJsonStructuredData)
     {
         var child = symbols[childIndex];
-        var expectedContainerPath = GetOutlineContainerPath(child);
+        var expectedContainerPath = GetOutlineContainerPath(child, isJsonStructuredData);
         for (var i = childIndex - 1; i >= 0; i--)
         {
             var candidate = symbols[i];
@@ -386,14 +424,16 @@ private static int FindOutlineContainerIndex(List<OutlineSymbol> symbols, int ch
             }
             if (candidate.Line > child.Line)
                 continue;
-            if (IsOutlineContainerMatch(candidate, child.Line))
+            if (IsOutlineContainerMatch(candidate, child.Line, isJsonStructuredData))
                 return i;
         }
 
         return -1;
     }
 
-    private static string? GetOutlineContainerPath(OutlineSymbol symbol)
+    private static string? GetOutlineContainerPath(
+        OutlineSymbol symbol,
+        bool allowArrayIndexBoundary)
     {
         if (string.IsNullOrWhiteSpace(symbol.Path) || string.IsNullOrWhiteSpace(symbol.Name))
             return null;
@@ -404,19 +444,26 @@ private static int FindOutlineContainerIndex(List<OutlineSymbol> symbols, int ch
 
         return !string.IsNullOrWhiteSpace(symbol.ContainerName)
             && string.Equals(symbol.Path, symbol.Name, StringComparison.Ordinal)
-            && IsQualifiedOutlineChildPath(symbol.ContainerName, symbol.Name)
+            && IsQualifiedOutlineChildPath(
+                symbol.ContainerName,
+                symbol.Name,
+                allowArrayIndexBoundary)
                 ? symbol.ContainerName
                 : null;
     }
 
-    private static bool IsOutlineContainerMatch(OutlineSymbol candidate, int childLine)
+    private static bool IsOutlineContainerMatch(
+        OutlineSymbol candidate,
+        int childLine,
+        bool isJsonStructuredData)
     {
         if (candidate.StartLine <= childLine && candidate.EndLine >= childLine)
             return true;
 
         // File-scoped namespaces and structured-data containers have no body range, so they
         // do not enclose children by lines even though their exact paths identify the parent.
-        return candidate.Kind is "namespace" or "object" or "array" or "record"
+        return (candidate.Kind == "namespace"
+                || (isJsonStructuredData && candidate.Kind is "object" or "array" or "record"))
             && candidate.BodyStartLine == null
             && candidate.BodyEndLine == null
             && candidate.Line <= childLine;
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Contracts.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Contracts.cs
index 43c4cada5..59acc6e61 100644
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Contracts.cs
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.Contracts.cs
@@ -20,6 +20,8 @@ public static partial class SymbolExtractor
     public const int ApplicationManifestContractVersion = 3;
     public const int MarkdownContractVersion = 3;
     public const int DependencyLockContractVersion = 3;
+    public const int JsonContractVersion = 3;
+    public const int JsonLinesContractVersion = 3;
 
     private static readonly string[] ExplicitReferenceGraphContractLanguages =
         ["crystal", "groovy", "tcl", "prolog", "ambiguous_pl"];
@@ -68,11 +70,13 @@ public static int GetContractVersion(string? lang)
             "crystal" or "groovy" or "tcl" => DynamicReferenceGraphContractVersion,
             "prolog" or "ambiguous_pl" => PrologReferenceGraphContractVersion,
             "ada" or "ambiguous_m" or "cython" or "d" or "julia" or "matlab" or "nim" or "objc" => ScientificNativeGraphContractVersion,
-            "config" or "dockerignore" or "editorconfig" or "gitattributes" or "gitignore" or "jsonl" or "toml" => RepositoryMetadataContractVersion,
+            "config" or "dockerignore" or "editorconfig" or "gitattributes" or "gitignore" or "toml" => RepositoryMetadataContractVersion,
             "app_manifest" => ApplicationManifestContractVersion,
             "markdown" => MarkdownContractVersion,
             "dependency_lock" => DependencyLockContractVersion,
-            "cmake" or "dependency_manifest" or "graphql" or "html" or "json" or "justfile" or "msbuild" or "solution" or "yaml" => ExpandedLanguageContractVersion,
+            "json" => JsonContractVersion,
+            "jsonl" => JsonLinesContractVersion,
+            "cmake" or "dependency_manifest" or "graphql" or "html" or "justfile" or "msbuild" or "solution" or "yaml" => ExpandedLanguageContractVersion,
             _ => DefaultContractVersion,
         };
     }
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
index 19f9b98c8..179c72800 100644
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
@@ -131,7 +131,7 @@ private static void ExtractJsonObjectSymbols(
 
             traversalNodes++;
             var propertyName = property.Name;
-            var name = CombineStructuredDataPath(parentPath, propertyName);
+            var name = CombineJsonObjectPath(parentPath, propertyName);
             if (name.Length > StructuredDataMaxPathLength)
             {
                 if (propertyLines != null)
@@ -225,7 +225,7 @@ private static void ExtractJsonArraySymbols(
             }
 
             traversalNodes++;
-            var itemPath = CombineStructuredDataPath(arrayPath, $"[{index}]");
+            var itemPath = CombineJsonArrayIndexPath(arrayPath, index);
             if (itemPath.Length > StructuredDataMaxPathLength)
             {
                 DrainJsonPropertyLines(item, propertyLines);
@@ -239,7 +239,14 @@ private static void ExtractJsonArraySymbols(
                 JsonValueKind.Array => "array",
                 _ => "value",
             };
-            var itemLine = FindJsonElementLine(content, lines, ref lineStarts, item, arrayLine, ref searchOffset);
+            var itemLine = FindJsonElementLine(
+                content,
+                lines,
+                ref lineStarts,
+                item,
+                arrayLine,
+                ref searchOffset,
+                out var itemEndOffset);
             if (!TryAddStructuredDataSymbol(
                     fileId,
                     kind,
@@ -264,6 +271,7 @@ private static void ExtractJsonArraySymbols(
 
             if (truncated)
                 return;
+            searchOffset = Math.Max(searchOffset, itemEndOffset);
             index++;
         }
     }
@@ -274,19 +282,24 @@ private static int FindJsonElementLine(
         ref int[]? lineStarts,
         JsonElement element,
         int fallbackLine,
-        ref int searchOffset)
+        ref int searchOffset,
+        out int elementEndOffset)
     {
-        if (lines.Length <= 1)
-            return fallbackLine;
-
         var rawText = element.GetRawText();
         var offset = content.IndexOf(rawText, searchOffset, StringComparison.Ordinal);
         if (offset < 0 && searchOffset > 0)
             offset = content.IndexOf(rawText, StringComparison.Ordinal);
         if (offset < 0)
+        {
+            elementEndOffset = searchOffset;
             return fallbackLine;
+        }
 
         searchOffset = offset + 1;
+        elementEndOffset = offset + rawText.Length;
+        if (lines.Length <= 1)
+            return fallbackLine;
+
         return FindLineNumberForOffset(lineStarts ??= BuildLineStarts(lines), offset);
     }
 
@@ -371,6 +384,7 @@ private static List<SymbolRecord> ExtractJsonLinesSymbols(long fileId, string co
                     recordIndex++;
                     continue;
                 }
+                var rootIsArray = document.RootElement.ValueKind == JsonValueKind.Array;
 
                 if (symbols.Count >= StructuredDataMaxSymbols)
                     return symbols;
@@ -385,7 +399,7 @@ private static List<SymbolRecord> ExtractJsonLinesSymbols(long fileId, string co
                     if (symbols.Count >= StructuredDataMaxSymbols)
                         return symbols;
 
-                    symbol.Name = CombineStructuredDataPath(recordPath, symbol.Name);
+                    symbol.Name = CombineJsonLinesPath(recordPath, symbol.Name, rootIsArray);
                     symbol.Line = lineIndex + 1;
                     symbol.StartLine = lineIndex + 1;
                     symbol.EndLine = lineIndex + 1;
@@ -397,7 +411,7 @@ private static List<SymbolRecord> ExtractJsonLinesSymbols(long fileId, string co
                     }
                     else
                     {
-                        symbol.ContainerName = CombineStructuredDataPath(recordPath, symbol.ContainerName);
+                        symbol.ContainerName = CombineJsonLinesPath(recordPath, symbol.ContainerName, rootIsArray);
                     }
                     symbol.ContainerQualifiedName = symbol.ContainerName;
                     symbols.Add(symbol);
@@ -642,15 +656,18 @@ private static SymbolRecord CreateStructuredDataSymbol(
         };
     }
 
-    private static string CombineStructuredDataPath(string? parentPath, string childPath)
-    {
-        if (string.IsNullOrEmpty(parentPath))
-            return childPath;
+    private static string CombineJsonObjectPath(string? parentPath, string propertyName)
+        => string.IsNullOrEmpty(parentPath)
+            ? propertyName
+            : parentPath + "." + propertyName;
 
-        return childPath.Length > 0 && childPath[0] == '['
-            ? parentPath + childPath
-            : parentPath + "." + childPath;
-    }
+    private static string CombineJsonArrayIndexPath(string arrayPath, int index)
+        => $"{arrayPath}[{index}]";
+
+    private static string CombineJsonLinesPath(string recordPath, string symbolPath, bool rootIsArray)
+        => rootIsArray
+            ? recordPath + symbolPath
+            : recordPath + "." + symbolPath;
 
     private static string LimitStructuredDataSignature(string signature) =>
         signature.Length <= StructuredDataMaxSignatureLength
diff --git a/tests/CodeIndex.Tests/DatabaseTests.cs b/tests/CodeIndex.Tests/DatabaseTests.cs
index 6ec6601b0..b10ecb1b7 100644
--- a/tests/CodeIndex.Tests/DatabaseTests.cs
+++ b/tests/CodeIndex.Tests/DatabaseTests.cs
@@ -5505,6 +5505,31 @@ public void GetUnchangedFileId_InvalidatesPriorDependencyLockContract_Issue4845(
         Assert.Null(_writer.GetUnchangedFileId(file.Path, modified, language: language));
     }
 
+    [Theory]
+    [InlineData("json")]
+    [InlineData("jsonl")]
+    public void GetUnchangedFileId_InvalidatesPriorJsonHierarchyContracts_Issue4874(
+        string language)
+    {
+        const int previousContractVersion = 2;
+        var modified = new DateTime(2025, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+        var file = new FileRecord
+        {
+            Path = $"src/legacy-hierarchy.{language}",
+            Lang = language,
+            Size = 50,
+            Lines = 5,
+            Modified = modified,
+        };
+        _writer.UpsertFile(file);
+        _writer.SetMeta(
+            DbContext.GetSymbolExtractorVersionMetaKey(language),
+            previousContractVersion.ToString(CultureInfo.InvariantCulture));
+
+        Assert.True(SymbolExtractor.GetContractVersion(language) > previousContractVersion);
+        Assert.Null(_writer.GetUnchangedFileId(file.Path, modified, language: language));
+    }
+
     [Theory]
     [InlineData("crystal", 2)]
     [InlineData("groovy", 2)]
diff --git a/tests/CodeIndex.Tests/IndexCommandRunnerTests.cs b/tests/CodeIndex.Tests/IndexCommandRunnerTests.cs
index a96dcb272..7a18bdb28 100644
--- a/tests/CodeIndex.Tests/IndexCommandRunnerTests.cs
+++ b/tests/CodeIndex.Tests/IndexCommandRunnerTests.cs
@@ -7159,7 +7159,7 @@ public void Run_FilesUpdate_ReindexesUnchangedNuGetConfigWhenXmlExtractorVersion
     }
 
     [Fact]
-    public void Run_FilesUpdate_ReindexesUnchangedJsonFileWhenExpandedLanguageExtractorVersionChanged()
+    public void Run_FilesUpdate_ReindexesUnchangedJsonFileWhenJsonExtractorVersionChanged_Issue4874()
     {
         var projectRoot = CreateTempProject();
         try
@@ -7186,7 +7186,7 @@ public void Run_FilesUpdate_ReindexesUnchangedJsonFileWhenExpandedLanguageExtrac
                 cmd.CommandText = """
                     DELETE FROM symbols WHERE file_id = (SELECT id FROM files WHERE path = 'settings.json');
                     DELETE FROM symbol_references WHERE file_id = (SELECT id FROM files WHERE path = 'settings.json');
-                    INSERT OR REPLACE INTO codeindex_meta(key, value) VALUES('symbol_extractor_version_json', '1');
+                    INSERT OR REPLACE INTO codeindex_meta(key, value) VALUES('symbol_extractor_version_json', '2');
                     """;
                 cmd.ExecuteNonQuery();
             }
diff --git a/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs b/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
index cd58fcf88..cc242b1e4 100644
--- a/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+++ b/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
@@ -154,6 +154,39 @@ private static void AssertOutlineJsonSymbol(
         Assert.Equal(containerName, symbol.TryGetProperty("container_name", out var container) ? container.GetString() : null);
     }
 
+    [Fact]
+    public void RunOutline_JavaScriptBracketedPropertyRemainsContainerQualified_Issue4874()
+    {
+        var projectRoot = TestProjectHelper.CreateTempProject("cdidx_js_bracket_path_4874");
+        try
+        {
+            var dbPath = TestProjectHelper.CreateProjectDb(projectRoot);
+            TestProjectHelper.InsertIndexedFile(
+                dbPath,
+                "web/fixture.js",
+                "javascript",
+                """export const foo = { "foo[bar]": 1, "other": 2 };""");
+
+            var (exitCode, stdout, stderr) = CaptureConsole(() => QueryCommandRunner.RunOutline(
+                ["web/fixture.js", "--db", dbPath, "--json"],
+                _jsonOptions));
+            using var document = ParseJsonOutput(stdout);
+            var symbols = document.RootElement.GetProperty("symbols").EnumerateArray().ToArray();
+            var bracketedProperty = Assert.Single(
+                symbols,
+                symbol => symbol.GetProperty("name").GetString() == "foo[bar]");
+
+            Assert.Equal(CommandExitCodes.Success, exitCode);
+            Assert.Equal(string.Empty, stderr);
+            Assert.Equal("foo.foo[bar]", bracketedProperty.GetProperty("path").GetString());
+            Assert.Equal("foo", bracketedProperty.GetProperty("container_name").GetString());
+        }
+        finally
+        {
+            TestProjectHelper.DeleteDirectory(projectRoot);
+        }
+    }
+
     [Fact]
     public void RunInspect_CompactCandidateBundlesOmitBodiesAndKeepIndependentTruncationCounts()
     {
diff --git a/tests/CodeIndex.Tests/SymbolExtractorRepositoryMetadataTests.cs b/tests/CodeIndex.Tests/SymbolExtractorRepositoryMetadataTests.cs
index 8e6b64cd9..904942ce7 100644
--- a/tests/CodeIndex.Tests/SymbolExtractorRepositoryMetadataTests.cs
+++ b/tests/CodeIndex.Tests/SymbolExtractorRepositoryMetadataTests.cs
@@ -84,12 +84,16 @@ public void SupportedLanguages_RepositoryMetadataIncludesJsonLines_Issue4740()
     {
         var supported = SymbolExtractor.GetSupportedLanguages();
 
-        foreach (var language in new[] { "toml", "jsonl", "gitignore", "gitattributes", "editorconfig", "dockerignore", "config" })
+        foreach (var language in new[] { "toml", "gitignore", "gitattributes", "editorconfig", "dockerignore", "config" })
         {
             Assert.Contains(language, supported);
             Assert.Equal(SymbolExtractor.RepositoryMetadataContractVersion, SymbolExtractor.GetContractVersion(language));
         }
 
+        Assert.Contains("jsonl", supported);
+        Assert.Equal(
+            SymbolExtractor.JsonLinesContractVersion,
+            SymbolExtractor.GetContractVersion("jsonl"));
         Assert.Equal(
             SymbolExtractor.ApplicationManifestContractVersion,
             SymbolExtractor.GetContractVersion("app_manifest"));
diff --git a/tests/CodeIndex.Tests/SymbolExtractorTests.cs b/tests/CodeIndex.Tests/SymbolExtractorTests.cs
index 205255f3f..cc270ad8f 100644
--- a/tests/CodeIndex.Tests/SymbolExtractorTests.cs
+++ b/tests/CodeIndex.Tests/SymbolExtractorTests.cs
@@ -859,21 +859,22 @@ public void Extract_Json_ArraysPreservePathsParentsAndEmptyContainers_Issue4874(
                 [],
                 {}
               ],
+              "literal_keys": { "[0]": true },
               "empty_object": {},
               "empty_array": []
             }
             """;
         const string arrayRoot = """
             [
-              { "name": "first" },
-              1,
+              { "name": "duplicate" },
+              "duplicate",
               [2],
               [],
               {}
             ]
             """;
         const string jsonLines = """
-            {"items":[{"leaf":1}]}
+            {"items":[{"leaf":1}],"[0]":true}
             [{"name":"first"},[]]
             """;
 
@@ -896,8 +897,10 @@ public void Extract_Json_ArraysPreservePathsParentsAndEmptyContainers_Issue4874(
             symbol => AssertStructuredJsonSymbol(symbol, "value", "command_cases[1]", 11, "array", "command_cases"),
             symbol => AssertStructuredJsonSymbol(symbol, "array", "command_cases[2]", 12, "array", "command_cases"),
             symbol => AssertStructuredJsonSymbol(symbol, "object", "command_cases[3]", 13, "array", "command_cases"),
-            symbol => AssertStructuredJsonSymbol(symbol, "object", "empty_object", 15, null, null),
-            symbol => AssertStructuredJsonSymbol(symbol, "array", "empty_array", 16, null, null));
+            symbol => AssertStructuredJsonSymbol(symbol, "object", "literal_keys", 15, null, null),
+            symbol => AssertStructuredJsonSymbol(symbol, "property", "literal_keys.[0]", 15, "object", "literal_keys"),
+            symbol => AssertStructuredJsonSymbol(symbol, "object", "empty_object", 16, null, null),
+            symbol => AssertStructuredJsonSymbol(symbol, "array", "empty_array", 17, null, null));
         Assert.Collection(
             rootSymbols,
             symbol => AssertStructuredJsonSymbol(symbol, "object", "[0]", 2, null, null),
@@ -913,6 +916,7 @@ public void Extract_Json_ArraysPreservePathsParentsAndEmptyContainers_Issue4874(
             symbol => AssertStructuredJsonSymbol(symbol, "array", "[0].items", 1, "record", "[0]"),
             symbol => AssertStructuredJsonSymbol(symbol, "object", "[0].items[0]", 1, "array", "[0].items"),
             symbol => AssertStructuredJsonSymbol(symbol, "property", "[0].items[0].leaf", 1, "object", "[0].items[0]"),
+            symbol => AssertStructuredJsonSymbol(symbol, "property", "[0].[0]", 1, "record", "[0]"),
             symbol => AssertStructuredJsonSymbol(symbol, "record", "[1]", 2, null, null),
             symbol => AssertStructuredJsonSymbol(symbol, "object", "[1][0]", 2, "record", "[1]"),
             symbol => AssertStructuredJsonSymbol(symbol, "property", "[1][0].name", 2, "object", "[1][0]"),
@@ -12884,6 +12888,10 @@ public void GetContractVersion_LanguageSpecificKinds_UseDedicatedVersions()
         Assert.True(SymbolExtractor.MakefileContractVersion > SymbolExtractor.DefaultContractVersion);
         Assert.Equal(SymbolExtractor.DependencyLockContractVersion, SymbolExtractor.GetContractVersion("dependency_lock"));
         Assert.True(SymbolExtractor.DependencyLockContractVersion > SymbolExtractor.ExpandedLanguageContractVersion);
+        Assert.Equal(SymbolExtractor.JsonContractVersion, SymbolExtractor.GetContractVersion("json"));
+        Assert.True(SymbolExtractor.JsonContractVersion > SymbolExtractor.ExpandedLanguageContractVersion);
+        Assert.Equal(SymbolExtractor.JsonLinesContractVersion, SymbolExtractor.GetContractVersion("jsonl"));
+        Assert.True(SymbolExtractor.JsonLinesContractVersion > SymbolExtractor.RepositoryMetadataContractVersion);
         Assert.Equal(SymbolExtractor.StyleAndXamlContractVersion, SymbolExtractor.GetContractVersion("sass"));
         Assert.Equal(SymbolExtractor.StyleAndXamlContractVersion, SymbolExtractor.GetContractVersion("stylus"));
         Assert.True(SymbolExtractor.StyleAndXamlContractVersion > SymbolExtractor.DefaultContractVersion);

From 80b289126d2aa5a7f7412cad6bc285de440fcf63 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 29 Jul 2026 14:27:39 +0900
Subject: [PATCH 3/5] Handle compact and commented JSON arrays (#4874)

---
 .../Database/DbSymbolReader.Outline.cs        |  4 +
 .../Symbols/SymbolExtractor.StructuredData.cs | 84 ++++++++++---------
 .../QueryCommandRunnerInspectTests.cs         | 45 ++++++++++
 tests/CodeIndex.Tests/SymbolExtractorTests.cs | 21 +++++
 4 files changed, 115 insertions(+), 39 deletions(-)

diff --git a/src/CodeIndex/Database/DbSymbolReader.Outline.cs b/src/CodeIndex/Database/DbSymbolReader.Outline.cs
index 83947e81b..f18be8465 100644
--- a/src/CodeIndex/Database/DbSymbolReader.Outline.cs
+++ b/src/CodeIndex/Database/DbSymbolReader.Outline.cs
@@ -30,6 +30,9 @@ public partial class DbReader
         }
 
         var startColumnOrderSql = GetSymbolColumnSql("start_column", "CAST(2147483647 AS INTEGER)");
+        var structuredHierarchyOrderSql = lang is "json" or "jsonl"
+            ? "LENGTH(s.name) ASC,"
+            : string.Empty;
         var includeReferenceCountSql = includeReferenceCounts && _hasReferencesTable;
         var referenceCountSql = includeReferenceCountSql
             ? "CASE WHEN COALESCE(symbol_defs.definition_sites, 0) = 1 THEN COALESCE(symbol_rank.reference_count, 0) ELSE 0 END"
@@ -96,6 +99,7 @@ FROM symbols s
             WHERE s.file_id = @fileId
             ORDER BY s.line ASC,
                      {startColumnOrderSql} ASC,
+                     {structuredHierarchyOrderSql}
                      s.kind COLLATE BINARY ASC,
                      s.name COLLATE BINARY ASC,
                      s.id ASC";
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
index 179c72800..7681a70b0 100644
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
@@ -59,6 +59,9 @@ private static List<SymbolRecord> ExtractJsonSymbols(long fileId, string content
                 && content.IndexOf('\r', StringComparison.Ordinal) < 0
                 ? null
                 : BuildJsonPropertyLineQueues(content);
+            var arrayItemLines = propertyLines == null
+                ? null
+                : BuildJsonArrayItemLineQueue(content);
             if (document.RootElement.ValueKind == JsonValueKind.Object)
             {
                 ExtractJsonObjectSymbols(
@@ -71,6 +74,7 @@ private static List<SymbolRecord> ExtractJsonSymbols(long fileId, string content
                     ref searchOffset,
                     symbols,
                     propertyLines,
+                    arrayItemLines,
                     depth: 0,
                     ref traversalNodes,
                     ref truncated);
@@ -88,6 +92,7 @@ private static List<SymbolRecord> ExtractJsonSymbols(long fileId, string content
                     ref searchOffset,
                     symbols,
                     propertyLines,
+                    arrayItemLines,
                     depth: 0,
                     ref traversalNodes,
                     ref truncated);
@@ -111,6 +116,7 @@ private static void ExtractJsonObjectSymbols(
         ref int searchOffset,
         List<SymbolRecord> symbols,
         Dictionary<string, Queue<int>>? propertyLines,
+        Queue<int>? arrayItemLines,
         int depth,
         ref int traversalNodes,
         ref bool truncated)
@@ -168,7 +174,7 @@ private static void ExtractJsonObjectSymbols(
 
             if (property.Value.ValueKind == JsonValueKind.Object)
             {
-                ExtractJsonObjectSymbols(fileId, content, lines, ref lineStarts, property.Value, name, ref searchOffset, symbols, propertyLines, depth + 1, ref traversalNodes, ref truncated);
+                ExtractJsonObjectSymbols(fileId, content, lines, ref lineStarts, property.Value, name, ref searchOffset, symbols, propertyLines, arrayItemLines, depth + 1, ref traversalNodes, ref truncated);
                 if (truncated)
                     return;
             }
@@ -185,6 +191,7 @@ private static void ExtractJsonObjectSymbols(
                     ref searchOffset,
                     symbols,
                     propertyLines,
+                    arrayItemLines,
                     depth + 1,
                     ref traversalNodes,
                     ref truncated);
@@ -205,6 +212,7 @@ private static void ExtractJsonArraySymbols(
         ref int searchOffset,
         List<SymbolRecord> symbols,
         Dictionary<string, Queue<int>>? propertyLines,
+        Queue<int>? arrayItemLines,
         int depth,
         ref int traversalNodes,
         ref bool truncated)
@@ -225,6 +233,9 @@ private static void ExtractJsonArraySymbols(
             }
 
             traversalNodes++;
+            var itemLine = arrayItemLines is { Count: > 0 }
+                ? arrayItemLines.Dequeue()
+                : arrayLine;
             var itemPath = CombineJsonArrayIndexPath(arrayPath, index);
             if (itemPath.Length > StructuredDataMaxPathLength)
             {
@@ -239,14 +250,6 @@ private static void ExtractJsonArraySymbols(
                 JsonValueKind.Array => "array",
                 _ => "value",
             };
-            var itemLine = FindJsonElementLine(
-                content,
-                lines,
-                ref lineStarts,
-                item,
-                arrayLine,
-                ref searchOffset,
-                out var itemEndOffset);
             if (!TryAddStructuredDataSymbol(
                     fileId,
                     kind,
@@ -262,47 +265,19 @@ private static void ExtractJsonArraySymbols(
 
             if (item.ValueKind == JsonValueKind.Object)
             {
-                ExtractJsonObjectSymbols(fileId, content, lines, ref lineStarts, item, itemPath, ref searchOffset, symbols, propertyLines, depth + 1, ref traversalNodes, ref truncated);
+                ExtractJsonObjectSymbols(fileId, content, lines, ref lineStarts, item, itemPath, ref searchOffset, symbols, propertyLines, arrayItemLines, depth + 1, ref traversalNodes, ref truncated);
             }
             else if (item.ValueKind == JsonValueKind.Array)
             {
-                ExtractJsonArraySymbols(fileId, content, lines, ref lineStarts, item, itemPath, itemLine, ref searchOffset, symbols, propertyLines, depth + 1, ref traversalNodes, ref truncated);
+                ExtractJsonArraySymbols(fileId, content, lines, ref lineStarts, item, itemPath, itemLine, ref searchOffset, symbols, propertyLines, arrayItemLines, depth + 1, ref traversalNodes, ref truncated);
             }
 
             if (truncated)
                 return;
-            searchOffset = Math.Max(searchOffset, itemEndOffset);
             index++;
         }
     }
 
-    private static int FindJsonElementLine(
-        string content,
-        string[] lines,
-        ref int[]? lineStarts,
-        JsonElement element,
-        int fallbackLine,
-        ref int searchOffset,
-        out int elementEndOffset)
-    {
-        var rawText = element.GetRawText();
-        var offset = content.IndexOf(rawText, searchOffset, StringComparison.Ordinal);
-        if (offset < 0 && searchOffset > 0)
-            offset = content.IndexOf(rawText, StringComparison.Ordinal);
-        if (offset < 0)
-        {
-            elementEndOffset = searchOffset;
-            return fallbackLine;
-        }
-
-        searchOffset = offset + 1;
-        elementEndOffset = offset + rawText.Length;
-        if (lines.Length <= 1)
-            return fallbackLine;
-
-        return FindLineNumberForOffset(lineStarts ??= BuildLineStarts(lines), offset);
-    }
-
     private static void DrainJsonPropertyLines(JsonElement element, Dictionary<string, Queue<int>>? propertyLines)
     {
         if (propertyLines == null)
@@ -710,6 +685,37 @@ private static Dictionary<string, Queue<int>> BuildJsonPropertyLineQueues(string
         return propertyLines;
     }
 
+    private static Queue<int> BuildJsonArrayItemLineQueue(string content)
+    {
+        var itemLines = new Queue<int>();
+        var bytes = Encoding.UTF8.GetBytes(content);
+        var byteLineStarts = Utf8LineStarts.Build(bytes);
+        var reader = new Utf8JsonReader(bytes, StructuredJsonReaderOptions);
+        List<JsonTokenType> containerStack = [];
+        while (reader.Read())
+        {
+            if (reader.TokenType is JsonTokenType.EndObject or JsonTokenType.EndArray)
+            {
+                if (containerStack.Count > 0)
+                    containerStack.RemoveAt(containerStack.Count - 1);
+                continue;
+            }
+
+            if (reader.TokenType is not (JsonTokenType.PropertyName or JsonTokenType.Comment)
+                && containerStack.Count > 0
+                && containerStack[^1] == JsonTokenType.StartArray)
+            {
+                var byteOffset = (int)Math.Min(reader.TokenStartIndex, (long)bytes.Length);
+                itemLines.Enqueue(FindLineNumberForOffset(byteLineStarts, byteOffset));
+            }
+
+            if (reader.TokenType is JsonTokenType.StartObject or JsonTokenType.StartArray)
+                containerStack.Add(reader.TokenType);
+        }
+
+        return itemLines;
+    }
+
     private static bool TryDequeueJsonPropertyLine(
         Dictionary<string, Queue<int>> propertyLines,
         string propertyName,
diff --git a/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs b/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
index cc242b1e4..98d3329df 100644
--- a/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+++ b/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
@@ -154,6 +154,51 @@ private static void AssertOutlineJsonSymbol(
         Assert.Equal(containerName, symbol.TryGetProperty("container_name", out var container) ? container.GetString() : null);
     }
 
+    [Fact]
+    public void RunOutline_CompactJsonAndJsonLinesKeepParentFirstDepth_Issue4874()
+    {
+        var projectRoot = TestProjectHelper.CreateTempProject("cdidx_compact_json_depth_4874");
+        try
+        {
+            var dbPath = TestProjectHelper.CreateProjectDb(projectRoot);
+            TestProjectHelper.InsertIndexedFile(dbPath, "src/compact.json", "json", """[{"arr":[1]}]""");
+            TestProjectHelper.InsertIndexedFile(dbPath, "src/compact.jsonl", "jsonl", """[{"arr":[1]}]""");
+
+            var fixtures = new[]
+            {
+                (
+                    Path: "src/compact.json",
+                    Expected: new[] { ("[0]", 0), ("[0].arr", 1), ("[0].arr[0]", 2) }),
+                (
+                    Path: "src/compact.jsonl",
+                    Expected: new[] { ("[0]", 0), ("[0][0]", 1), ("[0][0].arr", 2), ("[0][0].arr[0]", 3) }),
+            };
+
+            foreach (var fixture in fixtures)
+            {
+                var (exitCode, stdout, stderr) = CaptureConsole(() => QueryCommandRunner.RunOutline(
+                    [fixture.Path, "--db", dbPath, "--json"],
+                    _jsonOptions));
+                using var document = ParseJsonOutput(stdout);
+                var actual = document.RootElement
+                    .GetProperty("symbols")
+                    .EnumerateArray()
+                    .Select(symbol => (
+                        symbol.GetProperty("path").GetString()!,
+                        symbol.GetProperty("depth").GetInt32()))
+                    .ToArray();
+
+                Assert.Equal(CommandExitCodes.Success, exitCode);
+                Assert.Equal(string.Empty, stderr);
+                Assert.Equal(fixture.Expected, actual);
+            }
+        }
+        finally
+        {
+            TestProjectHelper.DeleteDirectory(projectRoot);
+        }
+    }
+
     [Fact]
     public void RunOutline_JavaScriptBracketedPropertyRemainsContainerQualified_Issue4874()
     {
diff --git a/tests/CodeIndex.Tests/SymbolExtractorTests.cs b/tests/CodeIndex.Tests/SymbolExtractorTests.cs
index cc270ad8f..a90287f23 100644
--- a/tests/CodeIndex.Tests/SymbolExtractorTests.cs
+++ b/tests/CodeIndex.Tests/SymbolExtractorTests.cs
@@ -873,6 +873,14 @@ public void Extract_Json_ArraysPreservePathsParentsAndEmptyContainers_Issue4874(
               {}
             ]
             """;
+        const string commentedArrayRoot = """
+            [
+              // option 1
+              1,
+              // "duplicate"
+              "duplicate"
+            ]
+            """;
         const string jsonLines = """
             {"items":[{"leaf":1}],"[0]":true}
             [{"name":"first"},[]]
@@ -880,6 +888,7 @@ public void Extract_Json_ArraysPreservePathsParentsAndEmptyContainers_Issue4874(
 
         var objectSymbols = SymbolExtractor.Extract(1, "json", objectRoot);
         var rootSymbols = SymbolExtractor.Extract(1, "json", arrayRoot);
+        var commentedRootSymbols = SymbolExtractor.Extract(1, "json", commentedArrayRoot);
         var jsonLineSymbols = SymbolExtractor.Extract(1, "jsonl", jsonLines);
 
         Assert.Collection(
@@ -910,6 +919,18 @@ public void Extract_Json_ArraysPreservePathsParentsAndEmptyContainers_Issue4874(
             symbol => AssertStructuredJsonSymbol(symbol, "value", "[2][0]", 4, "array", "[2]"),
             symbol => AssertStructuredJsonSymbol(symbol, "array", "[3]", 5, null, null),
             symbol => AssertStructuredJsonSymbol(symbol, "object", "[4]", 6, null, null));
+        Assert.Collection(
+            commentedRootSymbols,
+            symbol =>
+            {
+                AssertStructuredJsonSymbol(symbol, "value", "[0]", 3, null, null);
+                Assert.Equal("1,", symbol.Signature);
+            },
+            symbol =>
+            {
+                AssertStructuredJsonSymbol(symbol, "value", "[1]", 5, null, null);
+                Assert.Equal("\"duplicate\"", symbol.Signature);
+            });
         Assert.Collection(
             jsonLineSymbols,
             symbol => AssertStructuredJsonSymbol(symbol, "record", "[0]", 1, null, null),

From 4252ad97659a78017f88ad10f18e966223f1ab02 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 29 Jul 2026 14:59:25 +0900
Subject: [PATCH 4/5] Preserve JSON lines after bounded skips (#4874)

---
 .../Symbols/SymbolExtractor.StructuredData.cs | 23 +++++----
 tests/CodeIndex.Tests/SymbolExtractorTests.cs | 50 +++++++++++++++++++
 2 files changed, 64 insertions(+), 9 deletions(-)

diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
index 7681a70b0..f2b898ff5 100644
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
@@ -142,7 +142,7 @@ private static void ExtractJsonObjectSymbols(
             {
                 if (propertyLines != null)
                     _ = TryDequeueJsonPropertyLine(propertyLines, propertyName, out _);
-                DrainJsonPropertyLines(property.Value, propertyLines);
+                DrainJsonLineQueues(property.Value, propertyLines, arrayItemLines);
                 continue;
             }
 
@@ -239,7 +239,7 @@ private static void ExtractJsonArraySymbols(
             var itemPath = CombineJsonArrayIndexPath(arrayPath, index);
             if (itemPath.Length > StructuredDataMaxPathLength)
             {
-                DrainJsonPropertyLines(item, propertyLines);
+                DrainJsonLineQueues(item, propertyLines, arrayItemLines);
                 index++;
                 continue;
             }
@@ -278,23 +278,28 @@ private static void ExtractJsonArraySymbols(
         }
     }
 
-    private static void DrainJsonPropertyLines(JsonElement element, Dictionary<string, Queue<int>>? propertyLines)
+    private static void DrainJsonLineQueues(
+        JsonElement element,
+        Dictionary<string, Queue<int>>? propertyLines,
+        Queue<int>? arrayItemLines)
     {
-        if (propertyLines == null)
-            return;
-
         if (element.ValueKind == JsonValueKind.Object)
         {
             foreach (var property in element.EnumerateObject())
             {
-                _ = TryDequeueJsonPropertyLine(propertyLines, property.Name, out _);
-                DrainJsonPropertyLines(property.Value, propertyLines);
+                if (propertyLines != null)
+                    _ = TryDequeueJsonPropertyLine(propertyLines, property.Name, out _);
+                DrainJsonLineQueues(property.Value, propertyLines, arrayItemLines);
             }
         }
         else if (element.ValueKind == JsonValueKind.Array)
         {
             foreach (var item in element.EnumerateArray())
-                DrainJsonPropertyLines(item, propertyLines);
+            {
+                if (arrayItemLines is { Count: > 0 })
+                    _ = arrayItemLines.Dequeue();
+                DrainJsonLineQueues(item, propertyLines, arrayItemLines);
+            }
         }
     }
 
diff --git a/tests/CodeIndex.Tests/SymbolExtractorTests.cs b/tests/CodeIndex.Tests/SymbolExtractorTests.cs
index a90287f23..e8f85a853 100644
--- a/tests/CodeIndex.Tests/SymbolExtractorTests.cs
+++ b/tests/CodeIndex.Tests/SymbolExtractorTests.cs
@@ -1059,6 +1059,56 @@ public void Extract_Json_SkippedOverlongSubtreesDoNotStealDuplicateKeyLines_Issu
         Assert.Equal(5, symbol.Line);
     }
 
+    [Fact]
+    public void Extract_Json_SkippedOverlongPropertySubtreesDoNotStealArrayItemLines_Issue4874()
+    {
+        var longName = new string('a', SymbolExtractor.StructuredDataMaxPathLength + 1);
+        var content = $$"""
+            [
+              {
+                "{{longName}}": [
+                  [
+                    1
+                  ]
+                ]
+              },
+              2
+            ]
+            """;
+
+        var symbol = Assert.Single(
+            SymbolExtractor.Extract(1, "json", content),
+            candidate => candidate.Name == "[1]");
+
+        Assert.Equal(9, symbol.Line);
+        Assert.Equal("2", symbol.Signature);
+    }
+
+    [Fact]
+    public void Extract_Json_SkippedOverlongArraySubtreesDoNotStealArrayItemLines_Issue4874()
+    {
+        var longName = new string('a', SymbolExtractor.StructuredDataMaxPathLength - 6);
+        var content = $$"""
+            [
+              {
+                "{{longName}}": [
+                  [
+                    1
+                  ]
+                ]
+              },
+              2
+            ]
+            """;
+
+        var symbol = Assert.Single(
+            SymbolExtractor.Extract(1, "json", content),
+            candidate => candidate.Name == "[1]");
+
+        Assert.Equal(9, symbol.Line);
+        Assert.Equal("2", symbol.Signature);
+    }
+
     [Fact]
     public void Extract_Json_CapsStructuredSignatureLength_Issue3808()
     {

From 85ab56ed141594c05a07f76c81d3906174553025 Mon Sep 17 00:00:00 2001
From: Widthdom <widthdom@gmail.com>
Date: Wed, 29 Jul 2026 15:36:36 +0900
Subject: [PATCH 5/5] Handle legal JSON hierarchy edge cases (#4874)

---
 .../Database/DbSymbolReader.Outline.cs        |  2 +-
 .../Symbols/SymbolExtractor.StructuredData.cs |  2 +-
 .../QueryCommandRunnerInspectTests.cs         |  4 ++++
 tests/CodeIndex.Tests/SymbolExtractorTests.cs | 22 +++++++++++++++++++
 4 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/src/CodeIndex/Database/DbSymbolReader.Outline.cs b/src/CodeIndex/Database/DbSymbolReader.Outline.cs
index f18be8465..3e4fe46a2 100644
--- a/src/CodeIndex/Database/DbSymbolReader.Outline.cs
+++ b/src/CodeIndex/Database/DbSymbolReader.Outline.cs
@@ -31,7 +31,7 @@ public partial class DbReader
 
         var startColumnOrderSql = GetSymbolColumnSql("start_column", "CAST(2147483647 AS INTEGER)");
         var structuredHierarchyOrderSql = lang is "json" or "jsonl"
-            ? "LENGTH(s.name) ASC,"
+            ? "LENGTH(CAST(s.name AS BLOB)) ASC,"
             : string.Empty;
         var includeReferenceCountSql = includeReferenceCounts && _hasReferencesTable;
         var referenceCountSql = includeReferenceCountSql
diff --git a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
index f2b898ff5..2b5c9307e 100644
--- a/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
+++ b/src/CodeIndex/Indexer/Symbols/SymbolExtractor.StructuredData.cs
@@ -674,7 +674,7 @@ private static Dictionary<string, Queue<int>> BuildJsonPropertyLineQueues(string
                 continue;
 
             var name = reader.GetString();
-            if (string.IsNullOrEmpty(name))
+            if (name == null)
                 continue;
 
             var byteOffset = (int)Math.Min(reader.TokenStartIndex, (long)bytes.Length);
diff --git a/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs b/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
index 0e1bedb02..c9af43028 100644
--- a/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+++ b/tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
@@ -163,6 +163,7 @@ public void RunOutline_CompactJsonAndJsonLinesKeepParentFirstDepth_Issue4874()
             var dbPath = TestProjectHelper.CreateProjectDb(projectRoot);
             TestProjectHelper.InsertIndexedFile(dbPath, "src/compact.json", "json", """[{"arr":[1]}]""");
             TestProjectHelper.InsertIndexedFile(dbPath, "src/compact.jsonl", "jsonl", """[{"arr":[1]}]""");
+            TestProjectHelper.InsertIndexedFile(dbPath, "src/compact-nul.json", "json", """[{"\u0000":{"a":[]}}]""");
 
             var fixtures = new[]
             {
@@ -172,6 +173,9 @@ public void RunOutline_CompactJsonAndJsonLinesKeepParentFirstDepth_Issue4874()
                 (
                     Path: "src/compact.jsonl",
                     Expected: new[] { ("[0]", 0), ("[0][0]", 1), ("[0][0].arr", 2), ("[0][0].arr[0]", 3) }),
+                (
+                    Path: "src/compact-nul.json",
+                    Expected: new[] { ("[0]", 0), ("[0].\0", 1), ("[0].\0.a", 2) }),
             };
 
             foreach (var fixture in fixtures)
diff --git a/tests/CodeIndex.Tests/SymbolExtractorTests.cs b/tests/CodeIndex.Tests/SymbolExtractorTests.cs
index e8f85a853..74c702760 100644
--- a/tests/CodeIndex.Tests/SymbolExtractorTests.cs
+++ b/tests/CodeIndex.Tests/SymbolExtractorTests.cs
@@ -1109,6 +1109,28 @@ public void Extract_Json_SkippedOverlongArraySubtreesDoNotStealArrayItemLines_Is
         Assert.Equal("2", symbol.Signature);
     }
 
+    [Fact]
+    public void Extract_Json_EmptyPropertyAfterEmptyArrayValueKeepsItsLine_Issue4874()
+    {
+        const string content = """
+            {
+              "items": [
+                "",
+                {
+                  "": 1
+                }
+              ]
+            }
+            """;
+
+        var symbol = Assert.Single(
+            SymbolExtractor.Extract(1, "json", content),
+            candidate => candidate.Name == "items[1].");
+
+        Assert.Equal(5, symbol.Line);
+        Assert.Equal("\"\": 1", symbol.Signature);
+    }
+
     [Fact]
     public void Extract_Json_CapsStructuredSignatureLength_Issue3808()
     {