From fe3777c9768f0f0a180a2a17589cd1f767712ac4 Mon Sep 17 00:00:00 2001
From: mick-gsk <mick.gottsch@gmail.com>
Date: Thu, 30 Jul 2026 01:04:34 +0200
Subject: [PATCH] feat(guard): guard Go
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #779

Measured on real Go repositories: cobra speaks on 0 of 36 files, gin on 2 of 99
— and gin's two are real, `Binding` being defined in both `binding.go` and
`binding_nomsgpack.go`.

Two decisions worth naming.

**Methods on receivers are not indexed.** #779 argued for including them, since
`func (s *Store) Validate()` is package-level API in Go. The noise measurement
that came between then and now argued louder: `String`, `Error`, `Read` and
`Close` sit on every type in a package, and methods are excluded in Python and
TypeScript for exactly that reason. Evidence beat the plan.

**Trailing-segment matching is reserved for Go.** Go imports carry the whole
module path (`github.com/org/repo/internal/db`) while the repository knows
itself as `internal/db`, so the resolver drops leading segments until something
matches — no `go.mod` parsing needed. Applying the same rule to TypeScript
would resolve `lodash/fp` onto a directory named `fp`, and date-fns has one; a
test pins that boundary.

The `type (...)` block form is deliberately unsupported. Matching names at one
indent level would also match struct fields, and a struct field read as a type
declaration is the invented symbol these patterns exist to prevent.

One bug in the measurement tool, found by the same instinct that has paid off
twice today: gin reported zero cross-directory imports, which was too clean.
`measure_boundary_reach` called `import_to_dir` without a suffix, so every Go
module path fell through the TypeScript branch and resolved to nothing. With
the suffix passed, gin goes from 0 to 21 files across 14 edges.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md                    |   1 +
 README.md                       |   8 +-
 docs-site/claude-code-plugin.md |  10 +-
 scripts/gates/measure_noise.py  |   8 +-
 src/drift/guard/build.py        |  28 ++++-
 src/drift/guard/extract.py      |  71 ++++++++++++-
 src/drift/guard/lookup.py       |   5 +-
 tests/guard/test_extract_go.py  | 175 ++++++++++++++++++++++++++++++++
 tests/guard/test_extract_ts.py  |   2 +-
 9 files changed, 291 insertions(+), 17 deletions(-)
 create mode 100644 tests/guard/test_extract_go.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 83924216..cd55b754 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ Short version: Drift installs as a Claude Code plugin and works inside the agent
 - add amphetamin — hold the session open on machine-checked work
 - guard TypeScript and JavaScript, not only Python
 - notice when the index describes a tree that has moved
+- guard Go
 
 ### Fixed
 
diff --git a/README.md b/README.md
index ac2062eb..f02362f2 100644
--- a/README.md
+++ b/README.md
@@ -20,10 +20,10 @@ plugin that fires in every project you open has no business leaving a directory
 in each of them. A project that wants the index alongside its source opts in by
 creating a `.drift/` directory.
 
-**Python, TypeScript and JavaScript** (`.py .ts .tsx .js .jsx .mjs .cjs`), in one
-index — a name defined in Python is found from TypeScript, because
-`validate_token` and `validateToken` normalise to the same thing. Other
-languages pass through untouched.
+**Python, TypeScript, JavaScript and Go** (`.py .ts .tsx .js .jsx .mjs .cjs .go`),
+in one index — a name defined in Python is found from TypeScript, because
+`validate_token`, `validateToken` and `ValidateToken` all normalise to the same
+thing. Other languages pass through untouched.
 
 <!-- Re-enable once GitHub Actions is unlocked (billing) — runs currently fail before starting, which renders a misleading red badge:
 [![CI](https://github.com/mick-gsk/drift/actions/workflows/ci.yml/badge.svg)](https://github.com/mick-gsk/drift/actions/workflows/ci.yml)
diff --git a/docs-site/claude-code-plugin.md b/docs-site/claude-code-plugin.md
index f80f31cb..b6b6e0a8 100644
--- a/docs-site/claude-code-plugin.md
+++ b/docs-site/claude-code-plugin.md
@@ -17,11 +17,11 @@ business leaving a directory in each of them. A project that wants the index
 alongside its source opts in by creating a `.drift/` directory; `DRIFT_CACHE_HOME`
 overrides both.
 
-!!! note "Python, TypeScript and JavaScript"
-    `.py .ts .tsx .js .jsx .mjs .cjs`, all in one index — a name defined in
-    Python is found from TypeScript, because `validate_token` and
-    `validateToken` normalise to the same thing. Python is parsed with `ast`;
-    TypeScript and JavaScript are matched against top-level declarations,
+!!! note "Python, TypeScript, JavaScript and Go"
+    `.py .ts .tsx .js .jsx .mjs .cjs .go`, all in one index — a name defined in
+    Python is found from Go, because `validate_token`, `validateToken` and
+    `ValidateToken` all normalise to the same thing. Python is parsed with `ast`;
+    the others are matched against top-level declarations,
     because the guard may not grow a parser dependency. That trade costs recall,
     never precision: every pattern is anchored to column zero and to a
     declaration keyword, so a miss is possible and an invented symbol is not.
diff --git a/scripts/gates/measure_noise.py b/scripts/gates/measure_noise.py
index 1af75ccc..a6e4ea74 100644
--- a/scripts/gates/measure_noise.py
+++ b/scripts/gates/measure_noise.py
@@ -57,11 +57,15 @@ def measure_boundary_reach(repo: pathlib.Path, conn) -> dict:
             source = (repo / rel).read_text(encoding="utf-8")
         except (OSError, UnicodeDecodeError):
             continue
-        _, imports = extract.extract(source, pathlib.PurePosixPath(rel).suffix)
+        suffix = pathlib.PurePosixPath(rel).suffix
+        _, imports = extract.extract(source, suffix)
         src_dir = build.dir_of(rel)
         edges = set()
         for specifier in imports:
-            destination = build.import_to_dir(specifier, src_dir, known_dirs)
+            # The suffix matters: without it every Go module path falls through
+            # the TypeScript branch and resolves to nothing, which reports a
+            # tidy zero for a signal that is working fine.
+            destination = build.import_to_dir(specifier, src_dir, known_dirs, suffix)
             if destination and destination != src_dir:
                 edges.add((src_dir, destination))
         per_file[rel] = edges
diff --git a/src/drift/guard/build.py b/src/drift/guard/build.py
index 975aba3f..28121f52 100644
--- a/src/drift/guard/build.py
+++ b/src/drift/guard/build.py
@@ -71,7 +71,27 @@ def relative_to_dir(specifier: str, src_dir: str, known_dirs: set[str]) -> str |
     return parent if parent in known_dirs else None
 
 
-def import_to_dir(specifier: str, src_dir: str, known_dirs: set[str]) -> str | None:
+def suffix_to_dir(specifier: str, known_dirs: set[str]) -> str | None:
+    """Match the trailing segments of a full module path onto a directory.
+
+    Go imports carry the whole module path — `github.com/org/repo/internal/db`
+    — and the repository knows itself as `internal/db`. Dropping leading
+    segments until something matches finds it without reading `go.mod`.
+
+    This is reserved for Go. Applying it to TypeScript would resolve
+    `lodash/fp` onto a directory named `fp`, and date-fns has one.
+    """
+    parts = specifier.split("/")
+    for start in range(len(parts)):
+        candidate = "/".join(parts[start:])
+        if candidate in known_dirs:
+            return candidate
+    return None
+
+
+def import_to_dir(
+    specifier: str, src_dir: str, known_dirs: set[str], suffix: str = ".py"
+) -> str | None:
     """Map any import specifier onto a repository directory, if it is one.
 
     Bare TypeScript specifiers (`react`, `@scope/pkg`) name packages rather
@@ -79,6 +99,8 @@ def import_to_dir(specifier: str, src_dir: str, known_dirs: set[str]) -> str | N
     """
     if specifier.startswith("."):
         return relative_to_dir(specifier, src_dir, known_dirs)
+    if suffix in extract.GO_SUFFIXES:
+        return suffix_to_dir(specifier, known_dirs)
     if "/" in specifier:
         return None
     return module_to_dir(specifier, known_dirs)
@@ -171,7 +193,7 @@ def build_full(repo_root: pathlib.Path) -> dict:
         file_rows.append((rel, _sha256(path), now))
         symbol_rows.extend((rel, s.name, s.norm_name, s.kind, s.sig_hash, s.line) for s in symbols)
         for module in imports:
-            dst_dir = import_to_dir(module, src_dir, known_dirs)
+            dst_dir = import_to_dir(module, src_dir, known_dirs, path.suffix)
             if dst_dir is None or dst_dir == src_dir:
                 continue
             edge_counts[(src_dir, dst_dir)] = edge_counts.get((src_dir, dst_dir), 0) + 1
@@ -230,7 +252,7 @@ def update_file(repo_root: pathlib.Path, rel_path: str) -> None:
         known_dirs |= {dir_of(row[0]) for row in conn.execute("SELECT path FROM files")}
         src_dir = dir_of(rel_path)
         for module in imports:
-            dst_dir = import_to_dir(module, src_dir, known_dirs)
+            dst_dir = import_to_dir(module, src_dir, known_dirs, path.suffix)
             if dst_dir is None or dst_dir == src_dir:
                 continue
             conn.execute(
diff --git a/src/drift/guard/extract.py b/src/drift/guard/extract.py
index 513f3229..5d3f631e 100644
--- a/src/drift/guard/extract.py
+++ b/src/drift/guard/extract.py
@@ -24,7 +24,8 @@
 #: File types the guard indexes. Everything else passes through untouched.
 PYTHON_SUFFIXES = frozenset({".py"})
 TS_JS_SUFFIXES = frozenset({".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"})
-GUARDED_SUFFIXES = PYTHON_SUFFIXES | TS_JS_SUFFIXES
+GO_SUFFIXES = frozenset({".go"})
+GUARDED_SUFFIXES = PYTHON_SUFFIXES | TS_JS_SUFFIXES | GO_SUFFIXES
 
 #: Normalized names too common to ever be a meaningful duplicate.
 STOPWORDS = frozenset(
@@ -102,6 +103,36 @@
 )
 
 
+#: Go declarations. `func (r *Receiver) Name(` is deliberately absent: methods
+#: repeat across every type in a package — `String`, `Error`, `Read`, `Close` —
+#: exactly as they do in Python and TypeScript, where they are excluded for the
+#: same reason. The issue that scoped this work argued for including them; the
+#: noise measurement that came before it argued louder.
+_GO_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("function", re.compile(r"^func\s+([A-Za-z_][\w]*)\s*\(", re.MULTILINE)),
+    # Only the single-declaration form. A `type (...)` block would need the
+    # names matched at one indent level, which is also where struct fields
+    # live — and a struct field read as a type declaration is the kind of
+    # invented symbol these patterns exist to avoid.
+    (
+        "type",
+        re.compile(
+            r"^type\s+([A-Za-z_][\w]*)\s+(?:struct|interface|func|map|chan|\[|\*|[A-Za-z_])",
+            re.MULTILINE,
+        ),
+    ),
+)
+
+#: Import paths, both the single form and the parenthesised block. Go writes
+#: them as full module paths (`github.com/org/repo/internal/db`), so the
+#: resolver matches trailing segments against the repository's directories.
+_GO_IMPORTS: tuple[re.Pattern[str], ...] = (
+    re.compile(r'^import\s+(?:[A-Za-z_.]\w*\s+)?"([^"]+)"', re.MULTILINE),
+    re.compile(r"^import\s*\(([^)]*)\)", re.MULTILINE | re.DOTALL),
+)
+_GO_IMPORT_LINE = re.compile(r'^\s*(?:[A-Za-z_.]\w*\s+)?"([^"]+)"', re.MULTILINE)
+
+
 class Symbol(NamedTuple):
     name: str
     norm_name: str
@@ -139,9 +170,47 @@ def extract(source: str, suffix: str = ".py") -> tuple[list[Symbol], list[str]]:
         return extract_ts(source)
     if suffix in PYTHON_SUFFIXES:
         return extract_python(source)
+    if suffix in GO_SUFFIXES:
+        return extract_go(source)
     return ([], [])
 
 
+def extract_go(source: str) -> tuple[list[Symbol], list[str]]:
+    """Go, matched rather than parsed, on the same terms as TypeScript.
+
+    Package-level `func` and `type` only. Anchoring to column zero is unusually
+    reliable here because gofmt is not optional in practice: every declaration
+    that is package-level starts at column zero in formatted code.
+    """
+    symbols: list[Symbol] = []
+    seen: set[str] = set()
+
+    for kind, pattern in _GO_PATTERNS:
+        for match in pattern.finditer(source):
+            name = match.group(1)
+            if name in seen:
+                continue
+            seen.add(name)
+            symbols.append(
+                Symbol(
+                    name=name,
+                    norm_name=normalize(name),
+                    kind=kind,
+                    sig_hash=signature_hash(kind, []),
+                    line=source.count("\n", 0, match.start()) + 1,
+                )
+            )
+
+    imports: list[str] = []
+    for match in _GO_IMPORTS[0].finditer(source):
+        imports.append(match.group(1))
+    for block in _GO_IMPORTS[1].finditer(source):
+        imports.extend(line.group(1) for line in _GO_IMPORT_LINE.finditer(block.group(1)))
+
+    symbols.sort(key=lambda s: s.line)
+    return (symbols, imports)
+
+
 def extract_ts(source: str) -> tuple[list[Symbol], list[str]]:
     """TypeScript and JavaScript, matched rather than parsed.
 
diff --git a/src/drift/guard/lookup.py b/src/drift/guard/lookup.py
index a919cf10..66406476 100644
--- a/src/drift/guard/lookup.py
+++ b/src/drift/guard/lookup.py
@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import pathlib
 import sqlite3
 from typing import NamedTuple
 
@@ -160,7 +161,9 @@ def find_novel_edges(conn: sqlite3.Connection, rel_path: str, imports: list[str]
     hits: list[Hit] = []
     reported: set[str] = set()
     for module in imports:
-        dst_dir = build.import_to_dir(module, src_dir, known_dirs)
+        dst_dir = build.import_to_dir(
+            module, src_dir, known_dirs, pathlib.PurePosixPath(rel_path).suffix
+        )
         if dst_dir is None or dst_dir == src_dir:
             continue
         if dst_dir in existing or dst_dir in reported:
diff --git a/tests/guard/test_extract_go.py b/tests/guard/test_extract_go.py
new file mode 100644
index 00000000..fabd658e
--- /dev/null
+++ b/tests/guard/test_extract_go.py
@@ -0,0 +1,175 @@
+"""Go: what the matcher finds, and what it refuses to invent."""
+
+from __future__ import annotations
+
+from drift.guard import build, extract, lookup, schema
+
+SAMPLE = """\
+package auth
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/org/repo/internal/db"
+)
+
+import "os"
+
+// ValidateToken checks a bearer token.
+func ValidateToken(token string, audience string) bool {
+	return true
+}
+
+func unexportedHelper() {}
+
+type TokenStore struct {
+	entries map[string]string
+}
+
+type Validator interface {
+	Validate(token string) bool
+}
+
+func (s *TokenStore) Validate(token string) bool {
+	return strings.HasPrefix(token, "x")
+}
+
+func (s TokenStore) String() string {
+	return fmt.Sprint(db.Name)
+}
+"""
+
+
+def _names(source: str) -> list[str]:
+    symbols, _ = extract.extract(source, ".go")
+    return [s.name for s in symbols]
+
+
+def test_it_finds_package_level_declarations():
+    names = _names(SAMPLE)
+
+    assert "ValidateToken" in names
+    assert "unexportedHelper" in names
+    assert "TokenStore" in names
+    assert "Validator" in names
+
+
+def test_methods_on_receivers_are_not_indexed():
+    """`String`, `Error`, `Read` and `Close` sit on every type in a package.
+
+    The issue that scoped this work argued for including them, since a method
+    is package-level API in Go. The noise measurement that came before argued
+    louder: methods are excluded in Python and TypeScript for exactly this
+    reason, and Go's method names repeat harder than either.
+    """
+    names = _names(SAMPLE)
+
+    assert "Validate" not in names
+    assert "String" not in names
+
+
+def test_it_reads_both_import_forms():
+    _, imports = extract.extract(SAMPLE, ".go")
+
+    assert "fmt" in imports
+    assert "strings" in imports
+    assert "github.com/org/repo/internal/db" in imports
+    assert "os" in imports, "the single-line import form is real Go"
+
+
+def test_a_word_inside_a_string_is_not_a_declaration():
+    source = 'package main\n\nvar msg = "func NotARealFunction() {}"\n'
+
+    assert _names(source) == []
+
+
+def test_indented_declarations_are_not_package_level():
+    """gofmt makes column zero an unusually reliable proxy for package level."""
+    source = "package main\n\nfunc outer() {\n\tinner := func() {}\n\t_ = inner\n}\n"
+
+    assert _names(source) == ["outer"]
+
+
+def test_module_paths_resolve_by_their_trailing_segments():
+    """The repository knows itself as `internal/db`, not as its module path."""
+    known = {"internal/db", "internal/api", "."}
+
+    assert build.suffix_to_dir("github.com/org/repo/internal/db", known) == "internal/db"
+    assert build.suffix_to_dir("github.com/other/pkg", known) is None
+
+
+def test_trailing_segment_matching_is_reserved_for_go():
+    """`lodash/fp` must not resolve onto a directory named `fp`; date-fns has one."""
+    known = {"src/fp", "fp", "."}
+
+    assert build.import_to_dir("lodash/fp", "src", known, ".ts") is None
+    assert build.import_to_dir("github.com/org/repo/fp", "src", known, ".go") == "fp"
+
+
+def _write_go_repo(root):
+    (root / "internal" / "auth").mkdir(parents=True)
+    (root / "internal" / "db").mkdir(parents=True)
+    (root / "api").mkdir(parents=True)
+    (root / "internal" / "auth" / "tokens.go").write_text(
+        "package auth\n\nfunc ValidateToken(token string) bool {\n\treturn true\n}\n",
+        encoding="utf-8",
+    )
+    (root / "internal" / "db" / "client.go").write_text(
+        "package db\n\nfunc OpenConnection() error {\n\treturn nil\n}\n", encoding="utf-8"
+    )
+    (root / "api" / "routes.go").write_text(
+        'package api\n\nimport "github.com/org/repo/internal/auth"\n\n'
+        "func RegisterRoutes() {\n\t_ = auth.ValidateToken\n}\n",
+        encoding="utf-8",
+    )
+
+
+def test_a_go_repository_reports_a_duplicate(tmp_path):
+    _write_go_repo(tmp_path)
+    build.build_full(tmp_path)
+    conn = schema.connect(tmp_path)
+
+    symbols, _ = extract.extract(
+        "package api\n\nfunc ValidateToken(t string) bool {\n\treturn false\n}\n", ".go"
+    )
+    hits = lookup.find_duplicates(conn, "api/schemas.go", symbols)
+
+    assert hits
+    assert "internal/auth/tokens.go:3" in hits[0].message
+
+
+def test_a_go_repository_reports_a_first_ever_boundary(tmp_path):
+    _write_go_repo(tmp_path)
+    build.build_full(tmp_path)
+    conn = schema.connect(tmp_path)
+
+    hits = lookup.find_novel_edges(conn, "api/routes.go", ["github.com/org/repo/internal/db"])
+
+    assert hits, "api has never imported from internal/db"
+    assert "api" in hits[0].message and "internal/db" in hits[0].message
+
+
+def test_an_established_go_edge_is_not_reported(tmp_path):
+    _write_go_repo(tmp_path)
+    build.build_full(tmp_path)
+    conn = schema.connect(tmp_path)
+
+    assert (
+        lookup.find_novel_edges(conn, "api/routes.go", ["github.com/org/repo/internal/auth"]) == []
+    )
+
+
+def test_go_shares_the_index_with_python_and_typescript(tmp_path):
+    _write_go_repo(tmp_path)
+    (tmp_path / "internal" / "auth" / "session.py").write_text(
+        "def rotate_secret(a):\n    return a\n", encoding="utf-8"
+    )
+    build.build_full(tmp_path)
+    conn = schema.connect(tmp_path)
+
+    symbols, _ = extract.extract("package api\n\nfunc RotateSecret(a string) {}\n", ".go")
+    hits = lookup.find_duplicates(conn, "api/new.go", symbols)
+
+    assert hits, "one index, not one per language"
+    assert "session.py" in hits[0].message
diff --git a/tests/guard/test_extract_ts.py b/tests/guard/test_extract_ts.py
index bd8de881..a1f494e0 100644
--- a/tests/guard/test_extract_ts.py
+++ b/tests/guard/test_extract_ts.py
@@ -87,7 +87,7 @@ def test_camel_case_and_snake_case_collide():
 
 def test_an_unsupported_suffix_yields_nothing():
     """A new file type stays silent until it is supported on purpose."""
-    assert extract.extract("func main() {}\n", ".go") == ([], [])
+    assert extract.extract("fn main() {}\n", ".rs") == ([], [])
 
 
 def test_line_numbers_point_at_the_declaration():