feat(parser): Gleam import extraction and module-path resolution

get_call_hierarchy, get_impact_preview and the dead-code analysis
silently reported 0 callers for every Gleam symbol: _LANGUAGE_EXTRACTORS
had no "gleam" entry, so no import edges were ever extracted, and
resolve_specifier had no way to map a Gleam module path like
webse/config_types to cells/webse/src/webse/config_types.gleam.

- _extract_gleam_imports: plain imports, .{...} unqualified lists
  (including "type X" entries and "X as Y" aliases), module aliases,
  deep module paths, and multi-line lists as emitted by gleam format
- _gleam_source_roots: derives package src/ and test/ roots structurally
  from indexed .gleam paths, plus gleam.toml locations when indexed
  (cached by source_files identity, like _python_source_roots)
- resolve_specifier: resolves slash-style specifiers from .gleam
  importers against those roots, preferring the importer's own package
  (module paths are only unique per package); stdlib and hex-dependency
  imports resolve to nothing, so no edge is created
- tests: extraction, root detection, resolution (cross-package,
  test-to-src, test-only helpers, stdlib negatives), and the
  index_folder missing_extractors integration

Verified against a ~1200-file Gleam monorepo: a widely used helper now
reports 24 callers across 9 files (previously 0), and find_importers
matches full-text ground truth file-for-file (31/31).

Author: oderwat

src/jcodemunch_mcp/parser/imports.py

@@ -124,6 +124,17 @@ def _parse_reexport_clause(raw: str) -> list[dict]:
 # Haskell: import Data.Map (fromList)
 _HASKELL_IMPORT = re.compile(r"""^import\s+(?:qualified\s+)?(\S+)""", re.MULTILINE)
 
+# Gleam: import gleam/option.{type Option, None, Some} as opt
+# Module paths are lowercase snake_case segments joined by '/'. The optional
+# `.{...}` clause lists unqualified imports (values, constructors, and
+# `type X` entries); the optional trailing `as` alias renames the module but
+# does not change the specifier. gleam format may wrap long `.{...}` lists
+# across lines, so the brace body must span newlines ([^}] does).
+_GLEAM_IMPORT = re.compile(
+    r"""^\s*import\s+([a-z][a-z0-9_]*(?:/[a-z][a-z0-9_]*)*)(?:\.\{([^}]*)\})?""",
+    re.MULTILINE,
+)
+
 
 def _clean_names(raw: str) -> list[str]:
     """Parse comma-separated names from an import clause, stripping aliases/whitespace."""
@@ -389,6 +400,32 @@ def _extract_haskell_imports(content: str) -> list[dict]:
     return [{"specifier": m.group(1), "names": []} for m in _HASKELL_IMPORT.finditer(content)]
 
 
+def _extract_gleam_imports(content: str) -> list[dict]:
+    """Extract Gleam import statements.
+
+    Handles:
+        import gleam/io
+        import gleam/option.{type Option, None, Some}
+        import holmes_msg as msg
+        import webse/config_types.{type Config, Config}
+
+    ``names`` are the unqualified imports from the ``.{...}`` clause with the
+    ``type `` prefix stripped and ``X as Y`` reduced to the original name
+    (both handled by :func:`_clean_names`). Gleam forbids duplicate imports
+    of the same module, so first-wins dedup is sufficient.
+    """
+    edges: list[dict] = []
+    seen: set[str] = set()
+    for m in _GLEAM_IMPORT.finditer(content):
+        specifier, names_raw = m.group(1), m.group(2)
+        if specifier in seen:
+            continue
+        seen.add(specifier)
+        names = _clean_names(names_raw) if names_raw else []
+        edges.append({"specifier": specifier, "names": names})
+    return edges
+
+
 # Dart: import 'package:flutter/material.dart' / import 'dart:async' / import './foo.dart'
 _DART_IMPORT = re.compile(
     r"""^\s*(?:import|export)\s+['"]([^'"]+)['"]""", re.MULTILINE
@@ -642,6 +679,7 @@ def _extract_svelte_imports(content: str) -> list[dict]:
     "swift": _extract_swift_imports,
     "scala": _extract_scala_imports,
     "haskell": _extract_haskell_imports,
+    "gleam": _extract_gleam_imports,
     "dart": _extract_dart_imports,
     "sql": _extract_sql_dbt_imports,
     "asm": _extract_asm_imports,
@@ -890,6 +928,46 @@ def _python_source_roots(source_files) -> tuple[str, ...]:
     return result
 
 
+# Cache: frozenset(source_files) -> tuple of Gleam source root prefixes.
+# Same keying rationale as _python_roots_cache above.
+_gleam_roots_cache: dict[frozenset, tuple[str, ...]] = {}
+
+
+def _gleam_source_roots(source_files) -> tuple[str, ...]:
+    """Detect Gleam source roots from the indexed file set.
+
+    A Gleam module path like ``webse/config_types`` is relative to a
+    package's ``src/`` or ``test/`` directory, so those directories are the
+    source roots. They are derived structurally: every path prefix of an
+    indexed ``.gleam`` file that ends in a ``src`` or ``test`` segment
+    (``cells/webse/src/webse/config.gleam`` -> ``cells/webse/src``), plus
+    ``<dir>/src`` and ``<dir>/test`` for every indexed ``gleam.toml``. The
+    two signals overlap for normal packages; the gleam.toml one also covers
+    packages whose files did not make it into the index, and the structural
+    one covers indexes that exclude toml files.
+    """
+    cache_key = source_files if isinstance(source_files, frozenset) else frozenset(source_files)
+    cached = _gleam_roots_cache.get(cache_key)
+    if cached is not None:
+        return cached
+
+    roots: set[str] = set()
+    for f in source_files:
+        if f.endswith(".gleam"):
+            parts = f.split("/")
+            for i, seg in enumerate(parts[:-1]):
+                if seg in ("src", "test"):
+                    roots.add("/".join(parts[: i + 1]))
+        elif f == "gleam.toml" or f.endswith("/gleam.toml"):
+            pkg_dir = f[: -len("/gleam.toml")] if "/" in f else ""
+            for sub in ("src", "test"):
+                roots.add(f"{pkg_dir}/{sub}" if pkg_dir else sub)
+
+    result = tuple(sorted(roots))
+    _gleam_roots_cache[cache_key] = result
+    return result
+
+
 def _python_package_parents(source_files) -> dict[str, tuple[str, ...]]:
     """Map every package basename to the parent dirs where it appears.
 
@@ -1276,6 +1354,31 @@ def resolve_specifier(
         if c in source_files:
             return c
 
+    # Gleam module-style import: 'webse/config_types' →
+    # 'cells/webse/src/webse/config_types.gleam'. Gleam module paths are
+    # slash-joined lowercase segments resolved against a package's src/ or
+    # test/ root; the target extension is always .gleam, so candidates are
+    # built directly instead of via _candidates. The importer's own package
+    # root is tried first: module paths are only unique per package, and
+    # same-package imports are the common case. Stdlib and hex-dependency
+    # imports (gleam/io, gleam/list) resolve to nothing — no edge is created.
+    if importer_path.endswith(".gleam") and not specifier.startswith("."):
+        candidate = specifier + ".gleam"
+        if candidate in source_files:
+            return candidate
+        roots = _gleam_source_roots(source_files)
+        # "Own" roots share the importer's package dir (the part above
+        # src/test), so a test module prefers its package's src/ root too.
+        # A root-level src/test (dirname "") means a single-package repo.
+        own = [
+            r for r in roots
+            if not posixpath.dirname(r) or importer_path.startswith(posixpath.dirname(r) + "/")
+        ]
+        for root in own + [r for r in roots if r not in own]:
+            prefixed = f"{root}/{candidate}"
+            if prefixed in source_files:
+                return prefixed
+
     # Python module-style absolute import: 'app.notifications.mentions' →
     # 'app/notifications/mentions.py'. Also try prefixing with detected
     # Python source roots so layouts like backend/app/... or src/app/...

tests/test_gleam_imports.py

@@ -0,0 +1,183 @@
+"""Tests for Gleam import extraction and specifier resolution."""
+
+import pytest
+
+from jcodemunch_mcp.parser.imports import (
+    _LANGUAGE_EXTRACTORS,
+    _gleam_source_roots,
+    extract_imports,
+    resolve_specifier,
+)
+
+
+GLEAM_SOURCE = """\
+import gleam/io
+import gleam/option.{type Option, None, Some}
+import holmes_msg as msg
+import webse/config_types.{type Config, Config}
+import cx/commands/vetf/aggregate
+
+pub fn main() {
+  io.println("import ignored inside a string")
+}
+"""
+
+
+class TestGleamImportExtraction:
+
+    def test_gleam_in_language_extractors(self):
+        """Gleam must be registered in _LANGUAGE_EXTRACTORS."""
+        assert "gleam" in _LANGUAGE_EXTRACTORS
+
+    def test_extracts_plain_import(self):
+        edges = extract_imports(GLEAM_SOURCE, "src/app.gleam", "gleam")
+        specifiers = [e["specifier"] for e in edges]
+        assert "gleam/io" in specifiers
+
+    def test_extracts_unqualified_names_stripping_type_prefix(self):
+        edges = extract_imports(GLEAM_SOURCE, "src/app.gleam", "gleam")
+        by_spec = {e["specifier"]: e["names"] for e in edges}
+        assert by_spec["gleam/option"] == ["Option", "None", "Some"]
+        # `{type Config, Config}` imports the type and the constructor —
+        # both surface as the mention name "Config".
+        assert by_spec["webse/config_types"] == ["Config", "Config"]
+
+    def test_module_alias_keeps_specifier(self):
+        edges = extract_imports(GLEAM_SOURCE, "src/app.gleam", "gleam")
+        by_spec = {e["specifier"]: e["names"] for e in edges}
+        assert "holmes_msg" in by_spec
+        assert by_spec["holmes_msg"] == []
+
+    def test_extracts_deep_module_path(self):
+        edges = extract_imports(GLEAM_SOURCE, "src/app.gleam", "gleam")
+        specifiers = [e["specifier"] for e in edges]
+        assert "cx/commands/vetf/aggregate" in specifiers
+
+    def test_edge_count(self):
+        edges = extract_imports(GLEAM_SOURCE, "src/app.gleam", "gleam")
+        assert len(edges) == 5
+
+    def test_multiline_unqualified_list(self):
+        source = (
+            "import holmes_msg.{\n"
+            "  type HolmesMsg, type Envelope,\n"
+            "  decode_msg,\n"
+            "}\n"
+        )
+        edges = extract_imports(source, "src/app.gleam", "gleam")
+        assert len(edges) == 1
+        assert edges[0]["specifier"] == "holmes_msg"
+        assert edges[0]["names"] == ["HolmesMsg", "Envelope", "decode_msg"]
+
+    def test_unqualified_name_alias(self):
+        source = "import gleam/option.{Some as S}\n"
+        edges = extract_imports(source, "src/app.gleam", "gleam")
+        assert edges[0]["names"] == ["Some"]
+
+    def test_no_false_positives_from_non_import_lines(self):
+        source = 'pub fn main() {\n  io.println("import gleam/io")\n}\n'
+        edges = extract_imports(source, "src/app.gleam", "gleam")
+        assert edges == []
+
+
+WEVE_STYLE_FILES = {
+    "packages/yamlutils/src/yamlutils.gleam",
+    "packages/ion/src/ion/ion_yaml.gleam",
+    "cells/webse/src/webse/config_yaml.gleam",
+    "cells/webse/src/webse/config_types.gleam",
+    "cells/webse/test/webse_test.gleam",
+    "cells/webse/test/support/helper.gleam",
+    "soma/src/soma/config_yaml.gleam",
+    "cx/src/cx/cluster_config_yaml.gleam",
+    "cells/webse/gleam.toml",
+    "packages/yamlutils/gleam.toml",
+}
+
+
+class TestGleamSourceRoots:
+
+    def test_structural_roots_from_gleam_files(self):
+        roots = _gleam_source_roots(frozenset(WEVE_STYLE_FILES))
+        assert "packages/yamlutils/src" in roots
+        assert "cells/webse/src" in roots
+        assert "cells/webse/test" in roots
+        assert "soma/src" in roots
+        assert "cx/src" in roots
+
+    def test_gleam_toml_derived_roots(self):
+        files = frozenset({"cells/empty/gleam.toml"})
+        roots = _gleam_source_roots(files)
+        assert "cells/empty/src" in roots
+        assert "cells/empty/test" in roots
+
+    def test_root_level_package(self):
+        files = frozenset({"src/app.gleam", "test/app_test.gleam", "gleam.toml"})
+        roots = _gleam_source_roots(files)
+        assert "src" in roots
+        assert "test" in roots
+
+
+class TestGleamSpecifierResolution:
+
+    @pytest.mark.parametrize("specifier,importer,expected", [
+        # Cross-package import into another package's src root
+        ("yamlutils", "packages/ion/src/ion/ion_yaml.gleam",
+         "packages/yamlutils/src/yamlutils.gleam"),
+        # Same-package import
+        ("webse/config_types", "cells/webse/src/webse/config_yaml.gleam",
+         "cells/webse/src/webse/config_types.gleam"),
+        # Test module importing its package's src module
+        ("webse/config_types", "cells/webse/test/webse_test.gleam",
+         "cells/webse/src/webse/config_types.gleam"),
+        # Test module importing a test-only helper module
+        ("support/helper", "cells/webse/test/webse_test.gleam",
+         "cells/webse/test/support/helper.gleam"),
+        # Stdlib / hex dependency: unresolvable, no edge
+        ("gleam/io", "cells/webse/src/webse/config_yaml.gleam", None),
+        ("gleam/list", "soma/src/soma/config_yaml.gleam", None),
+    ], ids=[
+        "cross_package", "same_package", "test_to_src", "test_helper",
+        "stdlib_io", "stdlib_list",
+    ])
+    def test_resolution(self, specifier, importer, expected):
+        result = resolve_specifier(specifier, importer, set(WEVE_STYLE_FILES))
+        assert result == expected
+
+    def test_non_gleam_importer_unaffected(self):
+        """A slash specifier from a non-.gleam importer must not hit gleam roots."""
+        result = resolve_specifier(
+            "webse/config_types", "scripts/tool.py", set(WEVE_STYLE_FILES)
+        )
+        assert result is None
+
+    def test_end_to_end_extract_and_resolve(self):
+        source = "import webse/config_types.{type Config}\n"
+        edges = extract_imports(source, "cells/webse/src/webse/config_yaml.gleam", "gleam")
+        assert len(edges) == 1
+        resolved = resolve_specifier(
+            edges[0]["specifier"],
+            "cells/webse/src/webse/config_yaml.gleam",
+            set(WEVE_STYLE_FILES),
+        )
+        assert resolved == "cells/webse/src/webse/config_types.gleam"
+
+    def test_gleam_not_in_missing_extractors(self, tmp_path):
+        """After the extractor lands, index_folder must not flag gleam."""
+        from jcodemunch_mcp.tools.index_folder import index_folder
+
+        src = tmp_path / "src"
+        store = tmp_path / "store"
+        src.mkdir()
+        store.mkdir()
+
+        (src / "app.gleam").write_text(
+            "import gleam/io\n\npub fn main() {\n  io.println(\"hello\")\n}\n"
+        )
+
+        r = index_folder(str(src), use_ai_summaries=False, storage_path=str(store))
+        assert r["success"] is True
+
+        missing = r.get("missing_extractors", [])
+        assert "gleam" not in missing, (
+            f"gleam should no longer be in missing_extractors: {missing}"
+        )