code-explore-by-sql 0.1.0__py3-none-any.whl

code_explore_by_sql-0.1.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: code-explore-by-sql
+Version: 0.1.0
+Summary: SQLite FTS5 (trigram) MCP server for code source search.
+Project-URL: Repository, https://github.com/didi514354875/code-explore-by-sql
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# code-explore-by-sql
+
+Local stdio MCP server for fast source code navigation using **SQLite FTS5** (trigram tokenizer) + **bracket skeleton indexing**.
+
+## Features
+
+- **Full-text search**: FTS5 with trigram tokenizer for code-symbol-precise search (`GetGBuffer`, `FMaterial`, `UE_LOG`)
+- **Symbol lookup**: read code by qualified name with fuzzy matching (`Jump` → `ACharacter::Jump`)
+- **Bracket skeleton index**: lightweight structural indexing via FSM brace matching (no AST parser needed)
+- **12 language support**: C, C++, C#, Go, HLSL, GLSL, Java, JavaScript, Kotlin, Python, Rust, Swift
+- **Multi-database**: query multiple codebases simultaneously via `CODE_SOURCE_DBS`
+- **Token-efficient responses**: compact snippets (~2,600 tokens/20 results, 95% reduction vs full file reads)
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+# Run the MCP server directly (no clone needed)
+uvx code-explore-by-sql
+
+# Or install persistently
+pip install code-explore-by-sql
+```
+
+### Build a database
+
+```bash
+# Build index for your codebase
+uvx code-source-sql-build-db /path/to/source /path/to/output.db
+
+# Smoke test with limited files
+uvx code-source-sql-build-db /path/to/source /path/to/output.db --limit 1000
+```
+
+Performance: ~84,700 files indexed in ~3.3 minutes on a 2-core machine.
+
+### Configure in MCP clients
+
+**Claude Code** (`.claude/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "code-source-sql": {
+      "command": "uvx",
+      "args": ["code-explore-by-sql"],
+      "env": {
+        "CODE_SOURCE_DB": "/path/to/your/code.db",
+        "CODE_SOURCE_DBS": "/path/to/your/code.db:/path/to/another.db"
+      }
+    }
+  }
+}
+```
+
+**VS Code** (`.vscode/mcp.json`):
+```json
+{
+  "servers": {
+    "code-source-sql": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["code-explore-by-sql"],
+      "env": {
+        "CODE_SOURCE_DB": "/path/to/your/code.db"
+      }
+    }
+  }
+}
+```
+
+**OpenAI Codex** (`~/.codex/config.toml`):
+```toml
+[mcp_servers.code-source-sql]
+command = "uvx"
+args = ["code-explore-by-sql"]
+
+[mcp_servers.code-source-sql.env]
+CODE_SOURCE_DB = "/path/to/your/code.db"
+```
+
+**Hermes Agent** (`~/.hermes/config.yaml`):
+```yaml
+mcp_servers:
+  code-source-sql:
+    command: uvx
+    args:
+      - code-explore-by-sql
+    env:
+      CODE_SOURCE_DB: /path/to/your/code.db
+```
+
+## Tools (5)
+
+| Tool | Purpose |
+|------|---------|
+| `list_databases` | Discover available databases with stats |
+| `search_fts_tool` | FTS5 search — locate code blocks by keyword or raw FTS5 query |
+| `read_symbol` | Read symbol code by qualified name (exact or fuzzy) |
+| `read_file_range` | Read source code by file path and line range |
+| `get_directory_structure` | Module/file counts overview |
+
+### Multi-database
+
+Each tool accepts an optional `db` parameter to select a database by alias. Aliases are derived from database filenames (`unreal.db` → `"unreal"`). Use `list_databases` to discover available aliases. Default (`db=""`) uses the primary database (`CODE_SOURCE_DB`).
+
+### Search query modes
+
+**Simple mode** (`keyword`):
+```
+keyword="GetGBuffer"
+keyword="FMaterial Render"
+```
+
+**Advanced mode** (`raw_query`) — full FTS5 boolean:
+```
+raw_query='"GetGBuffer" AND "Emissive"'
+raw_query='"Material" NOT "hlsl"'
+raw_query='(file_path : "BasePass") AND "roughness"'
+raw_query='(module_name : "Renderer") AND "VirtualTexture"'
+```
+
+### Three-level funnel
+
+1. **`search_fts_tool(keyword)`** → file candidates + block QNs
+2. **`search_fts_tool(raw_query, file_path filter)`** → precise block in target file
+3. **`read_symbol(block QN)`** or **`read_file_range(file, line)`** → full code
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    MCP Server (FastMCP)                       │
+├──────────┬──────────┬──────────┬──────────┬──────────────────┤
+│ search   │ read     │ read     │ get_dir  │ list             │
+│ fts_tool │ _symbol  │ _file    │ _struct  │ _databases       │
+│          │          │ _range   │          │                  │
+├──────────┴──────────┴──────────┴──────────┴──────────────────┤
+│                     Query Pipeline                            │
+│  FTS5 trigram → Symbol match → Edge extraction               │
+├──────────────────────────────────────────────────────────────┤
+│                    SQLite Database                            │
+│  file_content + FTS5 │ symbol_index │ strict_edges           │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Bracket skeleton index
+
+A 6-state finite state machine (CODE, LINE_COMMENT, BLOCK_COMMENT, STRING, CHAR_LITERAL, RAW_STRING) scans source code tracking brace pairs while correctly ignoring braces in comments and string literals. Each matched pair records `open_line`, `close_line`, `depth`, and `is_complete`.
+
+Top-level blocks are classified by a **symbol analyzer** producing `block_type` (namespace/class/enum/function/macro) and `block_name` (qualified name).
+
+### Multi-database registry
+
+Databases are registered via environment variables at server startup:
+- `CODE_SOURCE_DB` — primary database (default when `db` is omitted)
+- `CODE_SOURCE_DBS` — colon-separated list of additional databases
+
+Aliases are auto-derived from filename stems. Connections are cached with health checks.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CODE_SOURCE_DB` | Yes | Path to primary SQLite database |
+| `CODE_SOURCE_DBS` | No | Colon-separated paths to additional databases |
+
+## Development
+
+```bash
+# Clone and setup
+git clone https://github.com/didi514354875/code-explore-by-sql.git
+cd code-explore-by-sql
+uv sync --dev
+
+# Run tests
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT

code_explore_by_sql-0.1.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+code_source_sql/__init__.py,sha256=jsHrPvnls-PZakFA6Smi4LmIn5Mqwh8IgYMovpduwww,206
+code_source_sql/__main__.py,sha256=BbeiAT_uKtmwhiW_6UjrUTp6uwZPBXozuvw0igKJT6Q,114
+code_source_sql/bracket_scanner.py,sha256=A9x0ABbiE7mOr7DQmUDWq2y8En9OAK2IZqqxW-_BdoA,13720
+code_source_sql/build_db.py,sha256=7cRI6LTF8QSNlE0kdszMBlkdEDYuUKL5WmkAPLb4FDs,9957
+code_source_sql/code_block_summary.py,sha256=VxMjyIVdryB2o7jYMwLgjBvR63-nBCCB-g_P9RlfYRo,16519
+code_source_sql/configs.py,sha256=7WvjFR7Fyi4lPLTmbWPT5AoVIxxRqq2399fRYmLAjbk,15907
+code_source_sql/db.py,sha256=4ScaahbeEFtUE1VU4GgLSKz0lYF91d_HNP67A2XbkJA,22254
+code_source_sql/edge_extractor.py,sha256=bWGedGYFWeNCxtYXsPlI79vqoUZG8fKVpjl7UFp4-UI,7157
+code_source_sql/server.py,sha256=4KUTvQP4UbZ-SWP3BE8nVTCI32pUlhTV1u4PfNaSREU,8587
+code_source_sql/symbol_analyzer.py,sha256=lbuKCim5Pg7sJhSeq7l86NaGPWxWkCHRKYwy2tNXvUQ,17225
+code_source_sql/unreal_rules.py,sha256=brv_Ktg5BoOKwaZhqWSa0POrJjzBcFF4eyQUb8oNOxo,6452
+code_source_sql/languages/__init__.py,sha256=vsN0FMT2Zw2uN8ngwrPSbCzx99IUre8SXNZszc0VKdM,1273
+code_source_sql/languages/c.py,sha256=2p4oPjiWk64-35A7pkHDGIeaJh2YePi_LR55lF8To_I,4632
+code_source_sql/languages/cpp.py,sha256=q8Q4Md2wDBunpOoPkLkWW4qbQkhVxc3G-7d0bR_-TGc,4723
+code_source_sql/languages/csharp.py,sha256=KuE3L_kSVzARIE5mo6FtzDMYFtt5A7bzsyOLe7yU_14,4405
+code_source_sql/languages/glsl.py,sha256=ODyNfLDIOFkffIeDj5QTunQDIwz27g0TeHd573pywjM,6121
+code_source_sql/languages/go.py,sha256=1nJoIc1oFw-zyKC4Ak-IsTykyfv7HluJu3BXWIbJdQQ,3896
+code_source_sql/languages/hlsl.py,sha256=Rzahkljdww3PXcjPhc3hR3_UbF_KGi3cKTd2wXpBx_E,6158
+code_source_sql/languages/java.py,sha256=Bx-G8MXWJ4bAyLWI-Hp7zZMGek-yYzMREh_9Mz4_cmo,4109
+code_source_sql/languages/javascript.py,sha256=al1OhJ1OmECrNOftOg92FUHXlwQ19dGA0r6BOrcYzgc,8247
+code_source_sql/languages/kotlin.py,sha256=AsuDQHFG4Z6QWLNaPXS3L4xXP70hfpmcif2qrEMNRi8,4093
+code_source_sql/languages/python.py,sha256=CLEVm3UcXKVi-5Ue1FkgNaixvsP_jB7QDfpot39aA-0,3987
+code_source_sql/languages/rust.py,sha256=vBqMsyeFMptk2Hl9Tp5rbj3F8QHTvqWi8whlhwJDYAc,4073
+code_source_sql/languages/swift.py,sha256=UtFiQki14A-QXwJlg2JK61PoMI_e9ZUtlLb3SUqtIe0,4325
+code_explore_by_sql-0.1.0.dist-info/METADATA,sha256=MKx9wA1szklj1C7QJ63O3u0r7VTIOX0lCp32Kchmhko,7332
+code_explore_by_sql-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+code_explore_by_sql-0.1.0.dist-info/entry_points.txt,sha256=6WGaA6HTPD_ZLScWXGUpK81hl9MRM_McDqPu0OWD6Tc,114
+code_explore_by_sql-0.1.0.dist-info/licenses/LICENSE,sha256=SC5Fwf9HNtdRRBSyPXU9NWn3it1kbpEpXGOQbhxa7KQ,1063
+code_explore_by_sql-0.1.0.dist-info/RECORD,,

code_explore_by_sql-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

code_explore_by_sql-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+code-source-sql = code_source_sql:main
+code-source-sql-build-db = code_source_sql.build_db:main

code_explore_by_sql-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 yanwei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

code_source_sql/__init__.py

@@ -0,0 +1,9 @@
+"""UE Semantic Search — plan.md implementation.
+
+Three-table architecture:
+  file_content (FTS5) -> symbol_index (QN + UE meta) -> strict_edges (4 types)
+"""
+
+from .server import main
+
+__all__ = ["main"]

code_source_sql/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m code_source_sql"""
+from .server import main
+
+if __name__ == "__main__":
+    main()

code_source_sql/bracket_scanner.py

@@ -0,0 +1,385 @@
+"""Bracket skeleton scanner — lightweight structural indexing for source code.
+
+FSM tracks brace depth while correctly ignoring braces inside comments,
+string literals, character literals, raw strings, verbatim strings,
+triple-quoted strings, and template literals. Supports multiple languages
+via optional LanguageConfig parameter. When `lang is None`, defaults to
+C/C++ syntax (backward compatible).
+
+For indent-based languages (Python), delegates to _scan_indent_blocks().
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .configs import LanguageConfig
+
+# FSM states
+_CODE = 0
+_LINE_COMMENT = 1
+_BLOCK_COMMENT = 2
+_STRING = 3
+_CHAR_LITERAL = 4
+_RAW_STRING = 5
+_VERBATIM_STRING = 6
+_TRIPLE_STRING = 7
+_TEMPLATE_LITERAL = 8
+
+_TRIGGER_CHARS_BASE = frozenset('{}"/\'R@')
+
+
+@dataclass(frozen=True)
+class BracketBlock:
+    open_line: int      # 1-based
+    close_line: int     # 1-based
+    depth: int
+    is_complete: bool
+
+
+def scan_brackets(
+    content: str,
+    verbatim_string_prefix: str | None = None,
+    raw_string_char: str | None = None,
+    lang: LanguageConfig | None = None,
+) -> list[BracketBlock]:
+    """Scan content and return matched brace pairs with depth info.
+
+    Args:
+        content: Source code text to scan.
+        verbatim_string_prefix: If set (e.g. '@' for C#), enables verbatim
+            string handling. Braces inside verbatim strings are ignored.
+            Ignored when `lang` is provided (resolved from lang instead).
+        raw_string_char: If set (e.g. 'R' for C++), enables raw string
+            literal handling. Braces inside raw strings are ignored.
+            Ignored when `lang` is provided (resolved from lang instead).
+        lang: Optional LanguageConfig for multi-language support. When
+            provided, all syntax parameters are resolved from it. When
+            None, defaults to C/C++ syntax (backward compatible).
+    """
+    # Indent-based language dispatch
+    if lang and lang.uses_indent_blocks:
+        return _scan_indent_blocks(content, lang)
+
+    # Resolve syntax parameters from lang or legacy params
+    if lang:
+        _line_comment = lang.line_comment
+        _block_comment_open, _block_comment_close = lang.block_comment_pair or (None, None)
+        _string_delims = lang.string_delimiters
+        _escape_char = lang.string_escape_char
+        _triple_quotes = lang.triple_quote_strings
+        _has_template_strings = lang.has_template_strings
+        _raw_style = lang.raw_string_style
+        # Override legacy params from lang
+        raw_string_char = lang.raw_string_char
+        verbatim_string_prefix = lang.verbatim_string_prefix
+    else:
+        _line_comment = "//"
+        _block_comment_open, _block_comment_close = "/*", "*/"
+        _string_delims = frozenset({'"', "'"})
+        _escape_char = "\\"
+        _triple_quotes = ()
+        _has_template_strings = False
+        _raw_style = "cpp"
+
+    depth = 0
+    stack: list[tuple[int, int]] = []  # (open_line, open_depth)
+    blocks: list[BracketBlock] = []
+    state = _CODE
+    raw_delim = ""
+    _current_string_delim = '"'
+    _current_triple_end = '"""'
+
+    # Build trigger chars for line-skip optimisation
+    _base = frozenset('{}"/\'')
+    extras = set()
+    if raw_string_char:
+        extras.add(raw_string_char)
+    if verbatim_string_prefix:
+        extras.add(verbatim_string_prefix)
+    if _has_template_strings:
+        extras.add('`')
+    trigger_chars = _base | frozenset(extras)
+
+    lines = content.split("\n")
+    last_line = len(lines)
+
+    for line_idx, line in enumerate(lines, start=1):
+        if state == _CODE and not any(c in line for c in trigger_chars):
+            continue
+
+        i = 0
+        n = len(line)
+        while i < n:
+            ch = line[i]
+            next_ch = line[i + 1] if i + 1 < n else ""
+
+            if state == _CODE:
+                # Line comment
+                if _line_comment and line[i:i + len(_line_comment)] == _line_comment:
+                    state = _LINE_COMMENT
+                    i += len(_line_comment)
+                    continue
+                # Block comment open
+                if _block_comment_open and line[i:i + len(_block_comment_open)] == _block_comment_open:
+                    state = _BLOCK_COMMENT
+                    i += len(_block_comment_open)
+                    continue
+                # Raw string (C++ R"delim(...)delim" or Rust r#"..."#)
+                if raw_string_char and ch == raw_string_char and next_ch == '"':
+                    if _raw_style == "rust":
+                        # Rust: r"...", r#"..."#, r##"..."##
+                        j = i + 2
+                        hash_count = 0
+                        while j < n and line[j] == '#':
+                            hash_count += 1
+                            j += 1
+                        raw_delim = "#" * hash_count
+                        state = _RAW_STRING
+                        i = j
+                        continue
+                    else:
+                        # C++ style: R"delim(...)delim"
+                        delim_end = line.find("(", i + 2)
+                        if delim_end != -1:
+                            raw_delim = line[i + 2 : delim_end]
+                            state = _RAW_STRING
+                            i = delim_end + 1
+                            continue
+                # Verbatim string: @"..." (C#) — doubles "" are escaped quotes
+                if verbatim_string_prefix and ch == verbatim_string_prefix and next_ch == '"':
+                    state = _VERBATIM_STRING
+                    i += 2
+                    continue
+                # Triple-quoted strings (Python """ and ''')
+                if _triple_quotes:
+                    matched_tq = None
+                    for tq in _triple_quotes:
+                        if line[i:i + len(tq)] == tq:
+                            matched_tq = tq
+                            break
+                    if matched_tq:
+                        _current_triple_end = matched_tq
+                        state = _TRIPLE_STRING
+                        i += len(matched_tq)
+                        continue
+                # Template literals (JavaScript/TypeScript backtick)
+                if _has_template_strings and ch == '`':
+                    state = _TEMPLATE_LITERAL
+                    i += 1
+                    continue
+                # String delimiters
+                if ch in _string_delims:
+                    state = _STRING
+                    _current_string_delim = ch
+                    i += 1
+                    continue
+                # Char literal (only when ' is NOT a string delimiter)
+                if ch == "'" and "'" not in _string_delims:
+                    state = _CHAR_LITERAL
+                    i += 1
+                    continue
+
+                if ch == "{":
+                    depth += 1
+                    stack.append((line_idx, depth))
+                elif ch == "}":
+                    if stack:
+                        open_line, open_depth = stack.pop()
+                        blocks.append(BracketBlock(
+                            open_line=open_line,
+                            close_line=line_idx,
+                            depth=open_depth,
+                            is_complete=True,
+                        ))
+                    depth = max(0, depth - 1)
+
+                i += 1
+
+            elif state == _LINE_COMMENT:
+                break
+
+            elif state == _BLOCK_COMMENT:
+                if _block_comment_close and line[i:i + len(_block_comment_close)] == _block_comment_close:
+                    state = _CODE
+                    i += len(_block_comment_close)
+                    continue
+                i += 1
+
+            elif state == _STRING:
+                if _escape_char and ch == _escape_char:
+                    i += 2
+                    continue
+                if ch == _current_string_delim:
+                    state = _CODE
+                i += 1
+
+            elif state == _CHAR_LITERAL:
+                if _escape_char and ch == _escape_char:
+                    i += 2
+                    continue
+                if ch == "'":
+                    state = _CODE
+                i += 1
+
+            elif state == _RAW_STRING:
+                if _raw_style == "rust":
+                    end_marker = raw_delim + '"'
+                else:
+                    end_marker = ")" + raw_delim + '"'
+                pos = line.find(end_marker, i)
+                if pos != -1:
+                    state = _CODE
+                    i = pos + len(end_marker)
+                    continue
+                break
+
+            elif state == _VERBATIM_STRING:
+                # In verbatim strings, "" is an escaped quote, " alone ends the string
+                if ch == '"':
+                    if next_ch == '"':
+                        i += 2  # skip escaped quote
+                        continue
+                    else:
+                        state = _CODE
+                        i += 1
+                        continue
+                i += 1
+
+            elif state == _TRIPLE_STRING:
+                tq_end = _current_triple_end
+                pos = line.find(tq_end, i)
+                if pos != -1:
+                    state = _CODE
+                    i = pos + len(tq_end)
+                    continue
+                break  # multi-line triple string
+
+            elif state == _TEMPLATE_LITERAL:
+                if _escape_char and ch == _escape_char:
+                    i += 2
+                    continue
+                if ch == '`':
+                    state = _CODE
+                i += 1
+
+        if state == _LINE_COMMENT:
+            state = _CODE
+
+    for open_line, open_depth in stack:
+        blocks.append(BracketBlock(
+            open_line=open_line,
+            close_line=last_line,
+            depth=open_depth,
+            is_complete=False,
+        ))
+
+    return blocks
+
+
+def _scan_indent_blocks(content: str, lang: LanguageConfig) -> list[BracketBlock]:
+    """Scan indent-based source and return pseudo-brace blocks.
+
+    Detects block openings when indentation increases relative to the
+    previous significant line. Closes blocks on dedent. Tracks
+    triple-quoted strings to avoid false positives from colons inside
+    string literals.
+    """
+    lines = content.split("\n")
+    blocks: list[BracketBlock] = []
+    stack: list[tuple[int, int, int]] = []  # (open_line_1based, depth, indent_level)
+    depth = 0
+    in_triple_string = False
+    triple_end = ""
+    prev_indent = 0  # indent of previous significant line
+    prev_line_idx = 0  # 1-based line number of previous significant line
+
+    _line_comment = lang.line_comment
+    _triple_quotes = lang.triple_quote_strings
+
+    for line_idx, line in enumerate(lines, start=1):
+        stripped = line.strip()
+
+        # Track triple-quoted strings (they may contain colons)
+        if _triple_quotes and not in_triple_string:
+            for tq in _triple_quotes:
+                idx = stripped.find(tq)
+                if idx != -1:
+                    # Check if it closes on same line
+                    after = stripped[idx + len(tq):]
+                    if tq in after:
+                        continue  # opens and closes on same line
+                    in_triple_string = True
+                    triple_end = tq
+                    break
+            if in_triple_string:
+                continue
+
+        if in_triple_string:
+            if triple_end in line:
+                in_triple_string = False
+            continue
+
+        # Skip blank and comment-only lines for indent comparison
+        if not stripped or (_line_comment and stripped.startswith(_line_comment)):
+            continue
+
+        indent = len(line) - len(line.lstrip())
+
+        # Dedent: pop stack until matching indent
+        while stack and indent < stack[-1][2]:
+            open_line, block_depth, _ = stack.pop()
+            blocks.append(BracketBlock(
+                open_line=open_line,
+                close_line=line_idx - 1,
+                depth=block_depth,
+                is_complete=True,
+            ))
+            depth -= 1
+
+        # Indent increase: open a new block (open_line is previous significant line)
+        if indent > prev_indent and prev_line_idx > 0:
+            depth += 1
+            stack.append((prev_line_idx, depth, indent))
+
+        prev_indent = indent
+        prev_line_idx = line_idx
+
+    # Close remaining open blocks
+    total_lines = len(lines)
+    for open_line, block_depth, _ in stack:
+        blocks.append(BracketBlock(
+            open_line=open_line,
+            close_line=total_lines,
+            depth=block_depth,
+            is_complete=False,
+        ))
+
+    return blocks
+
+
+def compute_parent_map(blocks: list[BracketBlock]) -> dict[tuple[int, int], tuple[int, int] | None]:
+    """Compute parent for each block based on nesting.
+
+    Returns dict mapping (open_line, depth) -> parent's (open_line, depth) or None.
+    """
+    sorted_blocks = sorted(blocks, key=lambda b: b.open_line)
+    active: dict[int, BracketBlock] = {}
+    parent_map: dict[tuple[int, int], tuple[int, int] | None] = {}
+
+    for b in sorted_blocks:
+        for depth in sorted(active, reverse=True):
+            if active[depth].close_line < b.open_line:
+                del active[depth]
+
+        if b.depth > 1 and (b.depth - 1) in active:
+            parent = active[b.depth - 1]
+            parent_map[(b.open_line, b.depth)] = (parent.open_line, parent.depth)
+        else:
+            parent_map[(b.open_line, b.depth)] = None
+
+        active[b.depth] = b
+
+    return parent_map