seam-code 0.3.0__py3-none-any.whl

seam/indexer/parser.py

@@ -0,0 +1,204 @@
+"""Tree-sitter parsing layer — one function per supported language.
+
+Returns raw tree-sitter root Nodes for graph.py to interpret.
+Never raises on parse errors; returns None instead.
+
+Guards applied before parsing:
+  1. File size > SEAM_MAX_FILE_BYTES  → None
+  2. Binary file (null byte in first 1KB) → None
+  3. Any read / OS error               → None
+  4. broad Exception backstop          → None
+"""
+
+from pathlib import Path
+
+import tree_sitter_c as tsc
+import tree_sitter_c_sharp as tscsharp
+import tree_sitter_cpp as tscpp
+import tree_sitter_go as tsgo
+import tree_sitter_java as tsjava
+import tree_sitter_php as tsphp
+import tree_sitter_python as tspython
+import tree_sitter_ruby as tsruby
+import tree_sitter_rust as tsrust
+import tree_sitter_swift as tsswift
+import tree_sitter_typescript as tstypescript
+from tree_sitter import Language, Node, Parser
+
+import seam.config as config
+
+# Build Language objects once at module level (cheap singletons).
+# Phase 9: six new grammars added alongside the original five.
+_PY_LANG = Language(tspython.language())
+_TS_LANG = Language(tstypescript.language_typescript())
+# TSX grammar is a superset of JS+JSX — used for .js/.mjs/.cjs (no separate JS dep)
+_TSX_LANG = Language(tstypescript.language_tsx())
+_GO_LANG = Language(tsgo.language())
+_RUST_LANG = Language(tsrust.language())
+# Phase 9 grammars
+_JAVA_LANG = Language(tsjava.language())
+_CSHARP_LANG = Language(tscsharp.language())
+_RUBY_LANG = Language(tsruby.language())
+_C_LANG = Language(tsc.language())
+_CPP_LANG = Language(tscpp.language())
+# PHP: language_php() (not language()) to handle the <?php open tag correctly.
+_PHP_LANG = Language(tsphp.language_php())
+# Phase 10 — Swift
+_SWIFT_LANG = Language(tsswift.language())
+
+
+def _parse(path: Path, language: Language) -> Node | None:
+    """Internal helper: guard checks then parse with tree-sitter.
+
+    Returns the root_node of the parsed tree, or None if the file should
+    be skipped.  Never raises — the outer except is the final backstop.
+    """
+    try:
+        # Guard 1: file size
+        try:
+            file_size = path.stat().st_size
+        except OSError:
+            return None  # file does not exist or unreadable
+
+        if file_size > config.SEAM_MAX_FILE_BYTES:
+            return None
+
+        # Guard 2: binary check — read first 1 KB and look for null byte
+        try:
+            with path.open("rb") as fh:
+                header = fh.read(1024)
+        except OSError:
+            return None
+
+        if b"\x00" in header:
+            return None  # binary file, skip gracefully
+
+        # Guard 3: read full content
+        try:
+            source_bytes = path.read_bytes()
+        except OSError:
+            return None
+
+        # Parse — tree-sitter never raises on syntax errors, returns ERROR nodes
+        parser = Parser(language)
+        tree = parser.parse(source_bytes)
+        return tree.root_node
+
+    except Exception:  # noqa: BLE001 — broad backstop so parsers never raise
+        return None
+
+
+def parse_python(path: Path) -> Node | None:
+    """Parse a Python source file.
+
+    Returns tree-sitter root Node, or None for binary/oversized/unreadable files.
+    Malformed Python still returns a (possibly partial) tree with ERROR nodes.
+    """
+    return _parse(path, _PY_LANG)
+
+
+def parse_typescript(path: Path) -> Node | None:
+    """Parse a TypeScript (.ts / .tsx) source file.
+
+    Returns tree-sitter root Node, or None for binary/oversized/unreadable files.
+    """
+    return _parse(path, _TS_LANG)
+
+
+def parse_javascript(path: Path) -> Node | None:
+    """Parse a JavaScript (.js / .mjs / .cjs) source file using the TSX grammar.
+
+    tree-sitter-typescript's TSX grammar is a superset that covers JS+JSX.
+    No separate JS grammar is needed; this is a deliberate Phase 0 decision.
+    See lessons.md: '2026-06-01 — JavaScript parsed via the TSX grammar'.
+    """
+    return _parse(path, _TSX_LANG)
+
+
+def parse_go(path: Path) -> Node | None:
+    """Parse a Go source file (.go).
+
+    Returns tree-sitter root Node, or None for binary/oversized/unreadable files.
+    Malformed Go still returns a (possibly partial) tree with ERROR nodes.
+    """
+    return _parse(path, _GO_LANG)
+
+
+def parse_rust(path: Path) -> Node | None:
+    """Parse a Rust source file (.rs).
+
+    Returns tree-sitter root Node, or None for binary/oversized/unreadable files.
+    Malformed Rust still returns a (possibly partial) tree with ERROR nodes.
+    """
+    return _parse(path, _RUST_LANG)
+
+
+# ── Phase 9 parsers ────────────────────────────────────────────────────────────
+
+
+def parse_java(path: Path) -> Node | None:
+    """Parse a Java source file (.java).
+
+    Returns tree-sitter root Node, or None for binary/oversized/unreadable files.
+    Malformed Java still returns a (possibly partial) tree with ERROR nodes.
+    """
+    return _parse(path, _JAVA_LANG)
+
+
+def parse_csharp(path: Path) -> Node | None:
+    """Parse a C# source file (.cs).
+
+    Returns tree-sitter root Node, or None for binary/oversized/unreadable files.
+    Malformed C# still returns a (possibly partial) tree with ERROR nodes.
+    """
+    return _parse(path, _CSHARP_LANG)
+
+
+def parse_ruby(path: Path) -> Node | None:
+    """Parse a Ruby source file (.rb).
+
+    Returns tree-sitter root Node, or None for binary/oversized/unreadable files.
+    Malformed Ruby still returns a (possibly partial) tree with ERROR nodes.
+    """
+    return _parse(path, _RUBY_LANG)
+
+
+def parse_c(path: Path) -> Node | None:
+    """Parse a C source file (.c / .h).
+
+    Returns tree-sitter root Node, or None for binary/oversized/unreadable files.
+    Both .c and .h files use the same C grammar — .h→C is a deliberate MVP decision.
+    Malformed C still returns a (possibly partial) tree with ERROR nodes.
+    """
+    return _parse(path, _C_LANG)
+
+
+def parse_cpp(path: Path) -> Node | None:
+    """Parse a C++ source file (.cpp / .cc / .cxx / .hpp / .hh / .hxx / .c++).
+
+    Returns tree-sitter root Node, or None for binary/oversized/unreadable files.
+    Malformed C++ still returns a (possibly partial) tree with ERROR nodes.
+    """
+    return _parse(path, _CPP_LANG)
+
+
+def parse_php(path: Path) -> Node | None:
+    """Parse a PHP source file (.php).
+
+    Uses language_php() (not language()) which handles the <?php open tag.
+    Returns tree-sitter root Node, or None for binary/oversized/unreadable files.
+    Malformed PHP still returns a (possibly partial) tree with ERROR nodes.
+    """
+    return _parse(path, _PHP_LANG)
+
+
+# ── Phase 10 parser ────────────────────────────────────────────────────────────
+
+
+def parse_swift(path: Path) -> Node | None:
+    """Parse a Swift source file (.swift).
+
+    Returns tree-sitter root Node, or None for binary/oversized/unreadable files.
+    Malformed Swift still returns a (possibly partial) tree with ERROR nodes.
+    """
+    return _parse(path, _SWIFT_LANG)

seam/indexer/pipeline.py

@@ -0,0 +1,197 @@
+"""Indexing pipeline — the shared parse -> extract -> upsert path.
+
+Lives in indexer/ (not cli/) because BOTH the CLI (`seam init`) and the watcher
+daemon consume it. Putting it here keeps the import hierarchy intact:
+  cli -> indexer.pipeline   and   watcher -> indexer.pipeline
+(watcher importing from cli would violate the layer rules in BACKEND_STRUCTURE.md).
+
+Pure-ish glue: no Typer, no watchdog — just stdlib + the indexer modules.
+"""
+
+import hashlib
+import logging
+import sqlite3
+from pathlib import Path
+
+import seam.config as config
+from seam.analysis.imports import extract_import_mappings
+from seam.indexer.db import upsert_file, upsert_import_mappings
+from seam.indexer.graph import extract_comments, extract_edges, extract_symbols
+from seam.indexer.parser import (
+    parse_c,
+    parse_cpp,
+    parse_csharp,
+    parse_go,
+    parse_java,
+    parse_javascript,
+    parse_php,
+    parse_python,
+    parse_ruby,
+    parse_rust,
+    parse_swift,
+    parse_typescript,
+)
+
+logger = logging.getLogger(__name__)
+
+# Directories to skip when walking the project tree.
+# Dot-dirs are skipped by default; this list catches common non-dot dirs.
+#
+# WHY build/output dirs matter: indexing compiled artifacts (e.g. a minified JS
+# bundle in seam/_web/assets/) injects thousands of garbage symbols and pollutes
+# clustering with meaningless "areas" named after the bundle file. We skip the
+# standard build/output/vendor dir names so `seam init` indexes SOURCE, not
+# generated output. (`dist`/`build`/`node_modules` were always here; `_web`,
+# `target`, `out`, `coverage`, `vendor` close the remaining common gaps.)
+SKIP_DIRS: frozenset[str] = frozenset(
+    {
+        ".git",
+        "node_modules",
+        ".venv",
+        "__pycache__",
+        ".seam",
+        "dist",
+        "build",
+        "_web",       # built SPA output (seam/_web/) — minified, not source
+        "out",        # common JS/TS build output
+        "target",     # Rust/Maven/Gradle compiled output
+        "vendor",     # Go/PHP third-party deps (not first-party source)
+        "coverage",   # coverage report output
+        "site",       # mkdocs default build output (bundled/minified JS — pollutes clusters)
+        "_site",      # Jekyll default build output
+        ".mypy_cache",
+        ".ruff_cache",
+        ".pytest_cache",
+    }
+)
+
+
+def sha1(content: bytes) -> str:
+    """Return the SHA-1 hex digest of file content bytes (change detection only)."""
+    return hashlib.sha1(content).hexdigest()  # noqa: S324 — not used for security
+
+
+def _dispatch_parser(path: Path, language: str):  # type: ignore[return]
+    """Call the correct parser for a language string. Returns root Node or None."""
+    if language == "python":
+        return parse_python(path)
+    if language == "typescript":
+        return parse_typescript(path)
+    if language == "javascript":
+        return parse_javascript(path)
+    if language == "go":
+        return parse_go(path)
+    if language == "rust":
+        return parse_rust(path)
+    # Phase 9 — new languages
+    if language == "java":
+        return parse_java(path)
+    if language == "csharp":
+        return parse_csharp(path)
+    if language == "ruby":
+        return parse_ruby(path)
+    if language == "c":
+        return parse_c(path)
+    if language == "cpp":
+        return parse_cpp(path)
+    if language == "php":
+        return parse_php(path)
+    # Phase 10 — Swift
+    if language == "swift":
+        return parse_swift(path)
+    return None
+
+
+def index_one_file(conn: sqlite3.Connection, path: Path) -> tuple[int, int] | None:
+    """Parse, extract, and upsert a single source file.
+
+    Returns:
+        (symbol_count, edge_count) when the file was INDEXED (upserted) — note
+            this is (0, 0) for a valid-but-empty file like an empty __init__.py,
+            which IS indexed.
+        None when the file was SKIPPED (unsupported ext, oversize, binary/
+            unreadable, or an error) — the reason is logged at DEBUG so a
+            systematic failure (e.g. a grammar mismatch breaking every .ts file)
+            is recoverable instead of silently invisible.
+
+    Distinguishing None (skipped) from (0, 0) (indexed-but-empty) lets callers
+    report an honest skipped-file count. Never raises.
+    """
+    try:
+        ext = path.suffix.lower()
+        language = config.SEAM_LANGUAGE_MAP.get(ext)
+        if language is None:
+            logger.debug("skip %s: unsupported extension", path)
+            return None
+
+        try:
+            if path.stat().st_size > config.SEAM_MAX_FILE_BYTES:
+                logger.debug("skip %s: over size limit", path)
+                return None
+        except OSError as exc:
+            logger.debug("skip %s: stat failed: %s", path, exc)
+            return None
+
+        root = _dispatch_parser(path, language)
+        if root is None:
+            logger.debug("skip %s: parser returned None (binary/unreadable)", path)
+            return None
+
+        try:
+            content = path.read_bytes()
+        except OSError as exc:
+            logger.debug("skip %s: read failed: %s", path, exc)
+            return None
+
+        file_hash = sha1(content)
+        symbols = extract_symbols(root, language, path)
+        # Pass symbols so extract_edges can resolve confidence (EXTRACTED/AMBIGUOUS/INFERRED)
+        # against the same-file symbol set. Cross-file ambiguity is handled at query time.
+        edges = extract_edges(root, language, path, symbols=symbols)
+        # Extract semantic comments (WHY/HACK/NOTE/TODO/FIXME); never raises.
+        comments = extract_comments(root, language, path)
+
+        upsert_file(conn, path, language, file_hash, symbols, edges, comments)
+
+        # Phase 5: extract and store import mappings for this file.
+        # Only runs when SEAM_IMPORT_RESOLUTION is 'on' (default).
+        # extract_import_mappings never raises; failures silently return [].
+        if config.SEAM_IMPORT_RESOLUTION == "on":
+            import_mappings = extract_import_mappings(root, path, language)
+            upsert_import_mappings(conn, path, import_mappings)
+
+        return len(symbols), len(edges)
+
+    except Exception as exc:  # noqa: BLE001 — one bad file must not abort the run
+        logger.debug("skip %s: unexpected error: %s", path, exc)
+        return None
+
+
+def walk_project(root: Path) -> list[Path]:
+    """Walk root recursively, skipping ignored dirs, returning indexable files.
+
+    Rules:
+      - Skip any directory whose name starts with '.' (hidden dirs).
+      - Skip any directory in SKIP_DIRS.
+      - Skip minified bundles (name contains '.min.', e.g. foo.min.js) — they are
+        generated, not source, and inject garbage symbols that pollute clustering.
+      - Collect files whose suffix is in config.SEAM_LANGUAGE_MAP.
+
+    The dot/skip check uses only the parts BELOW root (root may itself sit under
+    a dot-dir, e.g. ~/.config/proj — that must not exclude everything).
+    """
+    files: list[Path] = []
+    root_depth = len(root.parts)
+    for item in root.rglob("*"):
+        if any(
+            part.startswith(".") or part in SKIP_DIRS
+            for part in item.parts[root_depth:]
+        ):
+            continue
+        if (
+            item.is_file()
+            and item.suffix.lower() in config.SEAM_LANGUAGE_MAP
+            and ".min." not in item.name  # skip minified bundles (foo.min.js, bundle.min.mjs)
+        ):
+            files.append(item)
+    return files