sql-code-graph 1.0.2__py3-none-any.whl → 1.1.0__py3-none-any.whl

sqlcg/indexer/walker.py

@@ -40,6 +40,9 @@ def walk_sql_files(root: Path, spec: pathspec.PathSpec, use_git: bool = True) ->
     Yields:
         Path objects for .sql files not matching ignore patterns
     """
+    # Resolve once so both branches yield absolute paths and is_ignored's
+    # path.relative_to(root) never encounters a relative-vs-absolute mismatch.
+    root = Path(root).resolve()
     if use_git:
         git_files = _git_sql_files(root)
         if git_files is not None:

sqlcg/parsers/ansi_parser.py

@@ -37,11 +37,44 @@ class AnsiParser(SqlParser):
         """
         super().__init__(schema_resolver, schema_aliases=schema_aliases)
 
+    @staticmethod
+    def _compute_start_lines(sql: str) -> list[int]:
+        """Compute 1-based start line for each semicolon-delimited statement.
+
+        Uses the sqlglot tokenizer. Groups tokens by SEMICOLON boundaries and
+        returns the .line of the first token in each group. O(tokens), called
+        once per file before the statement loop.
+
+        Args:
+            sql: SQL text to tokenize
+
+        Returns:
+            List of 1-based line numbers, one per statement. May be shorter
+            than the parsed statement count if the trailing statement lacks a
+            semicolon — callers should guard with ``if stmt_index < len(lines)``.
+        """
+        from sqlglot.tokens import Tokenizer, TokenType  # type: ignore[attr-defined]
+
+        tokens = Tokenizer().tokenize(sql)
+        lines: list[int] = []
+        group_start: int | None = None
+        for tok in tokens:
+            if group_start is None and tok.token_type != TokenType.SEMICOLON:
+                group_start = tok.line
+            elif tok.token_type == TokenType.SEMICOLON:
+                if group_start is not None:
+                    lines.append(group_start)
+                group_start = None
+        if group_start is not None:  # last statement with no trailing semicolon
+            lines.append(group_start)
+        return lines
+
     def parse_file(
         self,
         path: Path,
         sql: str,
         dependency_filter: set[str] | None = None,
+        _precomputed_start_lines: list[int] | None = None,
     ) -> ParsedFile:
         """Parse SQL file and extract table/column lineage.
 
@@ -54,6 +87,13 @@ class AnsiParser(SqlParser):
                 `None` to disable filtering; pass-2 callers
                 (`CrossFileAggregator.resolve_pass2`) compute this from the pass-1
                 `ParsedFile.referenced_tables`.
+            _precomputed_start_lines: optional list of 1-based start lines, one per
+                statement. When provided (e.g. by SnowflakeParser which computes the map
+                from the preprocessed SQL after ``_preprocess_snowflake_sql`` — which
+                preserves line count so preprocessed positions equal original-file
+                positions), this list is used directly and ``_compute_start_lines`` is
+                not called on the ``sql`` argument. When ``None``, ``_compute_start_lines
+                (sql)`` is called here.
 
         Returns:
             ParsedFile with parsed statements and metadata
@@ -68,6 +108,18 @@ class AnsiParser(SqlParser):
             out.parse_quality = ParseQuality.FAILED
             return out
 
+        # Compute 1-based start lines once per file, before the statement loop.
+        # When _precomputed_start_lines is provided (Snowflake non-scripting path),
+        # the caller has already computed the map from the preprocessed SQL.
+        # _preprocess_snowflake_sql preserves line count (lambda replacements emit
+        # the same number of newlines as the matched text), so preprocessed line
+        # positions equal original-file positions — no line-shift desync.
+        start_lines: list[int] = (
+            _precomputed_start_lines
+            if _precomputed_start_lines is not None
+            else self._compute_start_lines(sql)
+        )
+
         # Check for pure-DDL files (still parse table definitions but skip lineage)
         is_pure_ddl = self._is_pure_ddl_file(statements)
         if is_pure_ddl:
@@ -128,6 +180,10 @@ class AnsiParser(SqlParser):
                     skip_column_lineage=is_pure_ddl,
                     schema_dict=schema_dict,
                 )
+                # Assign 1-based start line from the pre-computed map (0 if out of range)
+                query_node.start_line = (
+                    start_lines[stmt_index] if stmt_index < len(start_lines) else 0
+                )
                 out.statements.append(query_node)
 
                 # Register CTAS bodies in sources_map for downstream temp table references

sqlcg/parsers/base.py

@@ -55,6 +55,7 @@ class TableRef:
     db: str | None = None
     name: str = ""
     alias: str | None = None
+    role: str = "table"
 
     def __post_init__(self) -> None:
         """Normalize identity components to lowercase.
@@ -207,6 +208,7 @@ class QueryNode:
         confidence: Overall confidence score for this query's lineage
         parsing_mode: How the query was parsed (e.g., "sqlglot", "fallback", "scripting")
         defined_body: For CTAS statements, the exp.Select or exp.Subquery body being created
+        start_line: 1-based start line of statement in file; 0 = unknown (scripting-path sentinel)
     """
 
     file: Path
@@ -223,6 +225,7 @@ class QueryNode:
     star_sources: list[StarSource] = field(default_factory=list)
     defined_columns: list[str] = field(default_factory=list)
     defined_body: Any | None = None
+    start_line: int = 0  # 1-based start line of statement in file; 0 = unknown
 
 
 @dataclass
@@ -497,7 +500,7 @@ class SqlParser(ABC):
                             src=ColumnRef(src_table_ref, src_col_name),
                             dst=ColumnRef(dst_tbl, dst_col_name),
                             transform="SELECT",
-                            confidence=0.7,
+                            confidence=1.0,
                         )
                     )
                 except Exception as exc:
@@ -956,8 +959,8 @@ class SqlParser(ABC):
                             cte_alias = cte.alias
                             if not cte_alias:
                                 continue
-                            # Treat the CTE as a synthetic destination table
-                            cte_dst_table = TableRef(name=cte_alias)
+                            # Treat the CTE as a synthetic destination table (role="cte")
+                            cte_dst_table = TableRef(name=cte_alias, role="cte")
                             # The CTE's body is its SELECT expression (or UNION ALL, etc.)
                             cte_body = cte.this
                             # Accept both Select and Union (UNION ALL / UNION DISTINCT)

sqlcg/parsers/snowflake_parser.py

@@ -79,10 +79,30 @@ class SnowflakeParser(AnsiParser):
         # Check for scripting blocks
         if self._has_scripting_block(sql):
             logger.debug("Snowflake scripting block detected in %s, using DML extraction", path)
+            # Scripting path uses regex DML extraction; original line positions are lost.
+            # QueryNode.start_line defaults to 0 (unknown sentinel) for these nodes.
             return self._parse_scripting_file(path, sql)
 
-        # Otherwise use standard ANSI parsing with Snowflake dialect
-        return AnsiParser.parse_file(self, path, sql, dependency_filter=dependency_filter)  # type: ignore
+        # Compute start-line map from the PREPROCESSED SQL.
+        # _preprocess_snowflake_sql preserves line count via lambda replacements:
+        # each stripped clause (UNPIVOT, WITH TAG, ALTER … SET TAG;) is replaced
+        # with exactly as many newlines as the matched text contained.  A 3-line
+        # ALTER block becomes 3 blank lines — not a deletion — so the line numbers
+        # of all surviving statements in the preprocessed text still reflect their
+        # positions in the original file.  Computing _compute_start_lines on the
+        # preprocessed SQL therefore gives correct original-file line numbers for
+        # all surviving statements, even when multi-line blocks were stripped.
+        #
+        # Passing the map explicitly avoids AnsiParser recomputing it from `sql`
+        # again (a no-op difference, but explicit is clearer and future-proof).
+        preprocessed_start_lines = AnsiParser._compute_start_lines(sql)  # type: ignore[attr-defined]
+        return AnsiParser.parse_file(  # type: ignore[call-arg]
+            self,  # type: ignore[arg-type]
+            path,
+            sql,
+            dependency_filter=dependency_filter,  # type: ignore[call-arg]
+            _precomputed_start_lines=preprocessed_start_lines,  # type: ignore[call-arg]
+        )
 
     @staticmethod
     def _preprocess_snowflake_sql(sql: str) -> str:
@@ -94,11 +114,20 @@ class SnowflakeParser(AnsiParser):
         3. Gap 4: Strip WITH TAG (...) clauses from column definitions
         4. Gap 4b: Strip ALTER TABLE/VIEW ... MODIFY COLUMN ... SET TAG ...; statements
 
+        Line-count preservation contract:
+            Gaps 3, 4, and 4b replace matched text with the same number of newlines
+            the matched text contained (using a lambda replacement).  The Gap 1
+            normalization is single-line → single-line and never changes newline count.
+            Together, these guarantees ensure that after pre-processing each surviving
+            statement occupies the same 1-based line number it had in the original file,
+            so ``_compute_start_lines`` called on the pre-processed SQL returns correct
+            original-file line numbers.
+
         Args:
             sql: Raw Snowflake SQL text
 
         Returns:
-            Pre-processed SQL text
+            Pre-processed SQL text with line count preserved per the contract above.
         """
         # Gap 1: CREATE TEMP/TEMPORARY TABLE name IF NOT EXISTS -> CREATE TEMPORARY TABLE name
         # This regex matches CREATE TEMP[ORARY] TABLE name IF NOT EXISTS and drops the IF NOT EXISTS
@@ -112,13 +141,18 @@ class SnowflakeParser(AnsiParser):
         # Gap 3: Strip UNPIVOT clauses if present
         # UNPIVOT (...) [AS alias] — strip the entire clause
         # Handle nested parentheses by counting parens
+        #
+        # Line-count preservation: replace the matched text with the same number
+        # of newlines it contained.  This keeps all subsequent statement positions
+        # in the preprocessed SQL aligned with the original file line numbers so
+        # that _compute_start_lines returns correct original-file line numbers.
         if "UNPIVOT" in sql.upper():
             # Strategy: find UNPIVOT, then match everything until we close all parens
             # Use a more permissive pattern: UNPIVOT\s*\([^)]+\([^)]*\)[^)]*\)
             # This matches UNPIVOT (val FOR col IN (...)) AS alias
             sql = re.sub(
                 r"\s+UNPIVOT\s*\([^)]*\([^)]*\)[^)]*\)\s*(?:AS\s+\w+)?",
-                "",
+                lambda m: "\n" * m.group(0).count("\n"),
                 sql,
                 flags=re.IGNORECASE,
             )
@@ -135,10 +169,13 @@ class SnowflakeParser(AnsiParser):
         # A column may carry multiple WITH TAG clauses (chained). Strip each
         # occurrence independently; do not touch COMMENT or WITH MASKING
         # POLICY clauses, which sqlglot already handles.
+        # Line-count preservation: replace the matched text with the same number
+        # of newlines it contained so that statement positions in the preprocessed
+        # SQL remain aligned with the original file (see Gap 3 note above).
         if "WITH TAG" in sql.upper():
             sql = re.sub(
                 r"\s+WITH\s+TAG\s*\((?:[^()]*|\([^()]*\))*\)",
-                "",
+                lambda m: "\n" * m.group(0).count("\n"),
                 sql,
                 flags=re.IGNORECASE,
             )
@@ -146,10 +183,13 @@ class SnowflakeParser(AnsiParser):
         # Gap 4b: Strip ALTER TABLE/VIEW ... MODIFY COLUMN ... SET TAG ...; statements.
         # sqlglot emits these as exp.Command (unsupported syntax). They only carry tag
         # metadata we don't model, so removing them is safe and cleans the error stream.
+        # Line-count preservation: replace the matched text with the same number
+        # of newlines it contained so that statement positions in the preprocessed
+        # SQL remain aligned with the original file (see Gap 3 note above).
         if "SET TAG" in sql.upper():
             sql = re.sub(
                 r"ALTER\s+(?:DYNAMIC\s+)?(?:TABLE|VIEW)\s+[^;]*?MODIFY\s+COLUMN[^;]*?SET\s+TAG[^;]*?;",
-                "",
+                lambda m: "\n" * m.group(0).count("\n"),
                 sql,
                 flags=re.IGNORECASE | re.DOTALL,
             )

sqlcg/server/control.py

@@ -0,0 +1,144 @@
+"""Control-file helpers for the MCP server lifecycle.
+
+Manages the ``.pid`` and ``.sock`` files that allow a second CLI process to
+discover, query, and stop the running MCP server.
+
+All paths are derived from ``get_db_path()`` (i.e. ``KuzuConfig.from_env().db_path``)
+so that two servers on two different databases do not collide on a single control
+file.  Callers may pass an explicit ``db_path`` to override the default; this also
+makes unit tests straightforward (set ``SQLCG_DB_PATH=/tmp/test.db``, assert paths
+are ``/tmp/test.sock`` and ``/tmp/test.pid``).
+
+Path convention::
+
+    graph.db  →  graph.db.sock   (Unix domain socket, owner 0o600)
+               →  graph.db.pid   (JSON record, owner 0o600)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+from sqlcg.core.config import get_db_path
+
+# ---------------------------------------------------------------------------
+# Path helpers
+# ---------------------------------------------------------------------------
+
+
+def sock_path(db_path: Path | None = None) -> Path:
+    """Return the Unix domain socket path for *db_path*.
+
+    Derives from ``get_db_path()`` when *db_path* is ``None``.
+    Example: ``~/.sqlcg/graph.db`` → ``~/.sqlcg/graph.db.sock``.
+    """
+    p = db_path or get_db_path()
+    return p.with_suffix(".sock")
+
+
+def pid_path(db_path: Path | None = None) -> Path:
+    """Return the PID file path for *db_path*.
+
+    Derives from ``get_db_path()`` when *db_path* is ``None``.
+    Example: ``~/.sqlcg/graph.db`` → ``~/.sqlcg/graph.db.pid``.
+    """
+    p = db_path or get_db_path()
+    return p.with_suffix(".pid")
+
+
+# ---------------------------------------------------------------------------
+# PID file management
+# ---------------------------------------------------------------------------
+
+
+def write_pid(db_path: Path | None = None) -> None:
+    """Write a JSON PID record: ``{pid, db_path, started_at}``.
+
+    The file is created with mode ``0o600`` (owner read/write only) to limit
+    access on multi-user machines.
+
+    Args:
+        db_path: Explicit database path. Defaults to ``get_db_path()``.
+    """
+    resolved = db_path or get_db_path()
+    pp = pid_path(resolved)
+    pp.write_text(
+        json.dumps(
+            {
+                "pid": os.getpid(),
+                "db_path": str(resolved),
+                "started_at": time.time(),
+            }
+        )
+    )
+    pp.chmod(0o600)
+
+
+def read_pid(db_path: Path | None = None) -> dict | None:
+    """Return the PID record dict, or ``None`` if the file is missing or corrupt.
+
+    Args:
+        db_path: Explicit database path. Defaults to ``get_db_path()``.
+
+    Returns:
+        Parsed JSON dict with keys ``pid``, ``db_path``, ``started_at``, or
+        ``None`` on any read/parse error.
+    """
+    pp = pid_path(db_path)
+    try:
+        return json.loads(pp.read_text())
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Cleanup
+# ---------------------------------------------------------------------------
+
+
+def cleanup_control_files(db_path: Path | None = None) -> None:
+    """Remove ``.sock`` and ``.pid`` files silently.
+
+    Called from ``server.main`` ``finally`` block so control files are always
+    removed on clean exit or on uncaught exception.
+
+    Args:
+        db_path: Explicit database path. Defaults to ``get_db_path()``.
+    """
+    for p in (sock_path(db_path), pid_path(db_path)):
+        try:
+            p.unlink()
+        except FileNotFoundError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Process liveness
+# ---------------------------------------------------------------------------
+
+
+def is_pid_alive(pid: int) -> bool:
+    """Return ``True`` if a process with *pid* currently exists.
+
+    Uses ``os.kill(pid, 0)`` — signal 0 checks existence without sending a
+    real signal.  Returns ``False`` if the process does not exist
+    (``ProcessLookupError``) or is owned by another user (``PermissionError``
+    means it exists but we cannot signal it, so we treat it as alive).
+
+    Args:
+        pid: Process ID to probe.
+
+    Returns:
+        ``True`` if the process exists, ``False`` if it does not.
+    """
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # Process exists but owned by someone else — treat as alive
+        return True

sqlcg/server/models.py

@@ -56,6 +56,18 @@ class LineageNode(BaseModel):
     )
     file: str | None = Field(None, description="Source file path, if applicable")
     confidence: float | None = Field(None, description="Confidence score 0.0-1.0")
+    line: int | None = Field(None, description="1-based start line of the producing statement")
+    expression: str | None = Field(
+        None, description="SQL text of the producing statement (truncated)"
+    )
+    reason: str | None = Field(
+        None,
+        description="Set only when confidence < 1.0; why the edge is inferred",
+    )
+    table_kind: str | None = Field(
+        None,
+        description="Structural role of the source table: 'table', 'cte', 'derived', or 'external'",
+    )
 
 
 class LineageEdge(BaseModel):
@@ -195,6 +207,12 @@ class DbInfoResult(BaseModel):
         default_factory=list,
         description="Health warnings. Empty means the graph is in a healthy state.",
     )
+    indexed_sha: str | None = Field(None, description="Git SHA of the last index run")
+    head_sha: str | None = Field(None, description="Current HEAD SHA of the indexed repo")
+    stale_by_commits: int | None = Field(
+        None, description="Commits HEAD is ahead of indexed_sha (0 = up to date)"
+    )
+    dirty: bool = Field(False, description="True if working tree has uncommitted changes")
 
 
 class DefinitionFile(BaseModel):
@@ -312,6 +330,13 @@ class DiffImpactResult(BaseModel):
         default_factory=list,
         description="Affected tables in topological rebuild order across the union blast radius.",
     )
+    external_consumers: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Declared external consumers attached to any table in the blast radius "
+            "(via CONSUMED_BY edges). Empty when no consumers are configured."
+        ),
+    )
     noise_excluded: list[str] = Field(
         default_factory=list, description="Affected tables excluded as backup/noise."
     )
@@ -320,6 +345,11 @@ class DiffImpactResult(BaseModel):
         None, description="Diagnostic hint when result is empty or approximate."
     )
 
+    @property
+    def presentation(self) -> list[str]:
+        """Alias for presentation_facing (backward-compatible accessor)."""
+        return self.presentation_facing
+
 
 class ScopeChangeResult(BaseModel):
     """Result of scope_change — single-call synthesis of everything an LLM needs
@@ -376,6 +406,36 @@ class UnusedCandidate(BaseModel):
     )
 
 
+class PresentationCandidate(BaseModel):
+    """A terminal/egress table that has no in-corpus consumer BY DESIGN.
+
+    Surfaced separately from dead_code: its lack of within-corpus consumers is the
+    defining property of a declared presentation/egress layer, not evidence it is dead.
+    """
+
+    table_qualified: str = Field(..., description="Qualified table name (schema.table).")
+    within_corpus_references: int = Field(
+        default=0,
+        description="FACT: count of SELECTS_FROM consumers in the indexed corpus (always 0 here).",
+    )
+    matched_prefix: str = Field(
+        ...,
+        description="FACT: the configured [sqlcg.presentation] schema_prefix this table matched.",
+    )
+    reason: str = Field(
+        default="leaf in a declared egress layer; expected to have no in-corpus consumer",
+        description="Why this table is segregated from dead_code rather than flagged.",
+    )
+    has_external_consumer: bool = Field(
+        default=False,
+        description=(
+            "FACT: True when at least one declared external consumer is attached "
+            "to this table via a CONSUMED_BY edge. Distinguishes a provable egress "
+            "point from a candidate orphan in the egress layer."
+        ),
+    )
+
+
 class UnusedTablesResult(BaseModel):
     """Result of analyze_unused — tables with no within-corpus consumers."""
 
@@ -383,6 +443,14 @@ class UnusedTablesResult(BaseModel):
         default_factory=list,
         description="Tables with zero SELECTS_FROM consumers (noise-filtered).",
     )
+    presentation_facing: list[PresentationCandidate] = Field(
+        default_factory=list,
+        description=(
+            "Terminal/egress leaves matched by [sqlcg.presentation] prefixes; "
+            "expected to have no in-corpus consumer (NOT dead code). Empty when no "
+            "presentation prefix is configured."
+        ),
+    )
     total_tables_scanned: int = Field(
         0, description="FACT: total SqlTable nodes in the graph at time of scan."
     )