Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(public-api): flag exported Go identifiers outside internal packages (#3537)

Aman421f1093f76b
diff --git a/packages/core/src/repowise/core/analysis/public_api.py b/packages/core/src/repowise/core/analysis/public_api.py
index 66a581ea8..26ad2af20 100644
--- a/packages/core/src/repowise/core/analysis/public_api.py
+++ b/packages/core/src/repowise/core/analysis/public_api.py
@@ -14,7 +14,7 @@ Two readers share it: a wiki page's Public API section, and the per-symbol
from __future__ import annotations
import ast
-from collections.abc import Iterable, Mapping
+from collections.abc import Iterable, Mapping, Sequence
from collections.abc import Set as AbstractSet
from pathlib import Path, PurePosixPath
from typing import Any
@@ -397,8 +397,32 @@ def export_roots(parsed: Mapping[str, Any], entries: AbstractSet[str] = frozense
return roots
+def _sibling_owner(
+ path: str,
+ parent_name: str,
+ out: Mapping[str, str],
+ roots: AbstractSet[str],
+ package_files: Mapping[str, Sequence[str]],
+) -> str | None:
+ """The export root of a type declared in another file of *path*'s package.
+
+ Go splits a type's methods across the package's files; the receiver type
+ is looked up in each sibling file. The method's own file is its root when
+ it is one, else the type's.
+ """
+ for sibling in package_files.get(path, ()):
+ if sibling == path:
+ continue
+ owner = out.get(f"{sibling}::{parent_name}")
+ if owner is not None:
+ return path if path in roots else owner
+ return None
+
+
def public_symbols(
- parsed: Mapping[str, Any], entries: AbstractSet[str] = frozenset()
+ parsed: Mapping[str, Any],
+ entries: AbstractSet[str] = frozenset(),
+ package_files: Mapping[str, Sequence[str]] | None = None,
) -> dict[str, str]:
"""``{symbol id: the file that exports it}`` for every symbol consumers can import.
@@ -406,27 +430,37 @@ def public_symbols(
``__all__`` followed as for :func:`compute_public_api`); a public method
of an exported class is exported with it. *entries* are the files a
``package.json`` ``exports`` map names (:func:`export_roots`).
+ *package_files* maps a Go file to the files of its package, so a method
+ declared apart from its receiver type is exported with that type.
"""
resolver = _Resolver(parsed)
out: dict[str, str] = {}
- for root in export_roots(parsed, entries):
+ roots = export_roots(parsed, entries)
+ for root in roots:
for _name, sym, declared_in in resolver.exported(root):
if sym is not None and not parsed[declared_in].file_info.is_test:
out.setdefault(sym.id, root)
+ root_set = set(roots)
for path, pf in parsed.items():
for sym in pf.symbols:
owner = out.get(f"{path}::{sym.parent_name}") if sym.parent_name else None
+ if owner is None and sym.parent_name and package_files:
+ owner = _sibling_owner(path, sym.parent_name, out, root_set, package_files)
if owner is not None and sym.visibility == "public":
out.setdefault(sym.id, owner)
return out
-def stamp_public_api(graph: Any, parsed: Mapping[str, Any]) -> None:
+def stamp_public_api(
+ graph: Any,
+ parsed: Mapping[str, Any],
+ package_files: Mapping[str, Sequence[str]] | None = None,
+) -> None:
"""Set ``public_api`` on every symbol node: the exporting file, or ``""``."""
entries = {
path for path in parsed if graph.nodes.get(path, {}).get("package_export")
}
- exported = public_symbols(parsed, entries)
+ exported = public_symbols(parsed, entries, package_files)
for pf in parsed.values():
for sym in pf.symbols:
node = graph.nodes.get(sym.id)
diff --git a/packages/core/src/repowise/core/ingestion/graph/builder.py b/packages/core/src/repowise/core/ingestion/graph/builder.py
index e48d94103..967f38b10 100644
--- a/packages/core/src/repowise/core/ingestion/graph/builder.py
+++ b/packages/core/src/repowise/core/ingestion/graph/builder.py
@@ -25,6 +25,7 @@ from ..languages.python_modules import dotted_module_for
from ..models import Import, ParsedFile, Symbol, combine_load_kinds
from ..resolvers import ResolverContext, resolve_import
from ..resolvers.go import read_go_module_path, read_go_modules
+from ..resolvers.go_workspace import cached_go_index, go_package_files
from ..symbol_identity import has_overload_identity
from ..type_ref_resolution import resolve_type_refs
from ._edges import EdgesMixin
@@ -602,7 +603,12 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd
# Which symbols a package exports, read off the imports just resolved.
try:
- stamp_public_api(self._graph, self._parsed_files)
+ go_index = cached_go_index(ctx)
+ stamp_public_api(
+ self._graph,
+ self._parsed_files,
+ go_package_files(go_index) if go_index is not None else None,
+ )
except Exception as exc: # a reader bug must not fail the index
log.warning("public_api_stamp_failed", error=str(exc))
diff --git a/packages/core/src/repowise/core/ingestion/graph_warmups.py b/packages/core/src/repowise/core/ingestion/graph_warmups.py
index 6d2561cda..5257656fd 100644
--- a/packages/core/src/repowise/core/ingestion/graph_warmups.py
+++ b/packages/core/src/repowise/core/ingestion/graph_warmups.py
@@ -492,8 +492,13 @@ def _warmup_go(ctx: ResolverContext) -> None:
is semantic, not filename-based — ``cmd/task/task.go`` is as much a
binary entry as ``cmd/release/main.go``, so the traverser's stem
heuristic alone misses real binaries.
+
+ Also stamps ``package_export`` on every file of each package a consumer
+ outside the repo can import (:func:`exported_go_files`), the way the
+ TypeScript warmup does for a ``package.json``'s published files, for the
+ per-symbol public API flag (``analysis.public_api``).
"""
- from .resolvers.go_workspace import get_or_build_go_index
+ from .resolvers.go_workspace import exported_go_files, get_or_build_go_index
index = get_or_build_go_index(ctx)
graph = getattr(ctx, "graph", None)
@@ -501,6 +506,12 @@ def _warmup_go(ctx: ResolverContext) -> None:
for pkg in index.packages.values():
for path in pkg.main_files:
_stamp_entry(graph, parsed, path)
+ if graph is None:
+ return
+ for path in exported_go_files(index):
+ node = graph.nodes.get(path)
+ if node is not None:
+ node["package_export"] = True
def _warmup_typescript(ctx: ResolverContext) -> None:
diff --git a/packages/core/src/repowise/core/ingestion/resolvers/go_workspace.py b/packages/core/src/repowise/core/ingestion/resolvers/go_workspace.py
index 22ba59b52..8b8119f4f 100644
--- a/packages/core/src/repowise/core/ingestion/resolvers/go_workspace.py
+++ b/packages/core/src/repowise/core/ingestion/resolvers/go_workspace.py
@@ -59,6 +59,10 @@ class GoPackageIndex:
import_path_to_dir: dict[str, str] = field(default_factory=dict)
"""Maps a fully-qualified import path → its package directory."""
+ modules: tuple[tuple[str, str], ...] = ()
+ """``((module_dir, module_path), ...)`` the index was built from; empty
+ when no ``go.mod`` was readable."""
+
def files_for_import(self, import_path: str) -> tuple[str, ...]:
"""Return the *importable* ``.go`` files of the package the import names.
@@ -140,14 +144,15 @@ def _read_text(ctx: ResolverContext, rel_path: str) -> str:
return source_text(rel_path, ctx.repo_path / rel_path, source_map) or ""
-def _import_path_for_dir(
+def _enclosing_module(
pkg_dir: str, go_modules: tuple[tuple[str, str], ...]
-) -> str | None:
- """Compute a package's import path from the enclosing module.
+) -> tuple[str, str, str] | None:
+ """The module a package directory belongs to, as ``(module_dir, module_path, suffix)``.
*go_modules* is ``((module_dir, module_path), ...)`` sorted longest
module-path first; we re-rank by the longest matching *module_dir* so
- nested modules in a monorepo win over the root module.
+ nested modules in a monorepo win over the root module. *suffix* is the
+ package's path below the module root ("" for the root package).
"""
best: tuple[str, str] | None = None
best_len = -1
@@ -161,6 +166,17 @@ def _import_path_for_dir(
return None
module_dir, mod_path = best
suffix = pkg_dir[len(module_dir):].lstrip("/") if module_dir else pkg_dir
+ return module_dir, mod_path, suffix
+
+
+def _import_path_for_dir(
+ pkg_dir: str, go_modules: tuple[tuple[str, str], ...]
+) -> str | None:
+ """Compute a package's import path from the enclosing module."""
+ found = _enclosing_module(pkg_dir, go_modules)
+ if found is None:
+ return None
+ _module_dir, mod_path, suffix = found
return f"{mod_path}/{suffix}" if suffix else mod_path
@@ -175,6 +191,9 @@ def build_go_package_index(ctx: ResolverContext) -> GoPackageIndex:
# back to a fresh read, then to the legacy single-module field so
# manually-built test contexts still map import paths.
go_modules = ctx.go_modules or read_go_modules(ctx.repo_path)
+ # Only modules read from a real go.mod; ``exported_go_files`` keys off
+ # ``index.modules`` and must export nothing without one.
+ real_modules = tuple(go_modules)
if not go_modules and ctx.go_module_path:
go_modules = (("", ctx.go_module_path),)
@@ -187,7 +206,7 @@ def build_go_package_index(ctx: ResolverContext) -> GoPackageIndex:
parent = ""
files_by_dir.setdefault(parent, []).append(path)
- index = GoPackageIndex()
+ index = GoPackageIndex(modules=real_modules)
for pkg_dir, files in files_by_dir.items():
files.sort()
pkg_name = ""
@@ -228,9 +247,46 @@ def build_go_package_index(ctx: ResolverContext) -> GoPackageIndex:
return index
+def exported_go_files(index: GoPackageIndex) -> list[str]:
+ """Every non-test ``.go`` file a consumer outside the repo can import from.
+
+ A package is importable from outside its module when it sits in a module
+ the index knows, no segment of its path below the module root is
+ ``internal``, and it is not ``package main``. Nothing is exported when no
+ ``go.mod`` was readable. Whether a *symbol* in these files is exported is
+ Go's capitalisation rule, already on ``Symbol.visibility``.
+ """
+ out: list[str] = []
+ for pkg in index.packages.values():
+ if pkg.is_main:
+ continue
+ found = _enclosing_module(pkg.dir, index.modules)
+ if found is None:
+ continue
+ if "internal" in found[2].split("/"):
+ continue
+ out.extend(f for f in pkg.files if not f.endswith("_test.go"))
+ return sorted(out)
+
+
+def go_package_files(index: GoPackageIndex) -> dict[str, tuple[str, ...]]:
+ """``{file: the non-test files of its package}``, for symbols declared across a package's files."""
+ out: dict[str, tuple[str, ...]] = {}
+ for pkg in index.packages.values():
+ files = tuple(f for f in pkg.files if not f.endswith("_test.go"))
+ for f in files:
+ out[f] = files
+ return out
+
+
_INDEX_KEY = "_go_package_index"
+def cached_go_index(ctx: ResolverContext) -> GoPackageIndex | None:
+ """The index :func:`get_or_build_go_index` cached on *ctx*, or None if none was built."""
+ return getattr(ctx, _INDEX_KEY, None)
+
+
def get_or_build_go_index(ctx: ResolverContext) -> GoPackageIndex:
"""Return the cached GoPackageIndex, building it on first access."""
cached = getattr(ctx, _INDEX_KEY, None)
diff --git a/tests/unit/analysis/test_public_api_flag.py b/tests/unit/analysis/test_public_api_flag.py
index f76dd9ee4..2e16b328a 100644
--- a/tests/unit/analysis/test_public_api_flag.py
+++ b/tests/unit/analysis/test_public_api_flag.py
@@ -309,3 +309,66 @@ def test_kotlin_public_api_and_visibility(tmp_path: Path) -> None:
assert flags.get("src/main/kotlin/a/Hidden.kt::HiddenObj", "") == ""
+_GO_REPO = {
+ "go.mod": "module example.com/lib\n\ngo 1.21\n",
+ "lib/client.go": (
+ "package lib\n\ntype Client struct{}\n\nfunc New() *Client { return &Client{} }\n\n"
+ "func helper() {}\n"
+ ),
+ "lib/send.go": (
+ "package lib\n\nfunc (c *Client) Send() error { return nil }\n\n"
+ "func (c *Client) retry() {}\n"
+ ),
+ "lib/internal/x/x.go": "package x\n\nfunc Hidden() {}\n",
+ "lib/x_test.go": "package lib\n\nfunc TestHelper() {}\n",
+ "cmd/tool/main.go": (
+ 'package main\n\nimport "example.com/lib/lib"\n\nfunc Run() { _ = lib.New() }\n\n'
+ "func main() { Run() }\n"
+ ),
+}
+
+
+def _public_flags(graph) -> dict[str, str]:
+ return {
+ node: data["public_api"]
+ for node, data in graph.nodes(data=True)
+ if data.get("node_type") == "symbol" and "public_api" in data
+ }
+
+
+def test_go_exported_identifiers_of_importable_packages_are_public(tmp_path: Path) -> None:
+ flags = _public_flags(build_fixture(tmp_path, _GO_REPO).graph())
+ assert {node: root for node, root in flags.items() if root} == {
+ "lib/client.go::Client": "lib/client.go",
+ "lib/client.go::New": "lib/client.go",
+ # A method declared apart from its receiver type is exported with it.
+ "lib/send.go::Client::Send": "lib/send.go",
+ }
+ # Unexported names, an ``internal`` package, a ``package main``, a test
+ # file's exported func and an unexported method export nothing.
+ for node in (
+ "lib/client.go::helper",
+ "lib/send.go::Client::retry",
+ "lib/internal/x/x.go::Hidden",
+ "cmd/tool/main.go::Run",
+ "cmd/tool/main.go::main",
+ "lib/x_test.go::TestHelper",
+ ):
+ assert flags.get(node, "") == "", node
+
+
+def test_go_without_a_go_mod_exports_nothing(tmp_path: Path) -> None:
+ files = {rel: body for rel, body in _GO_REPO.items() if rel != "go.mod"}
+ flags = _public_flags(build_fixture(tmp_path, files).graph())
+ assert flags
+ assert not {node for node, root in flags.items() if root}
+
+
+def test_go_method_of_an_unexported_type_is_not_public(tmp_path: Path) -> None:
+ files = {
+ "go.mod": "module example.com/lib\n",
+ "lib/a.go": "package lib\n\ntype client struct{}\n",
+ "lib/b.go": "package lib\n\nfunc (c *client) Send() {}\n",
+ }
+ flags = _public_flags(build_fixture(tmp_path, files).graph())
+ assert flags["lib/b.go::client::Send"] == ""
\ No newline at end of file
diff --git a/tests/unit/health/test_plan_annotations.py b/tests/unit/health/test_plan_annotations.py
index f8af0ac20..d46c871cb 100644
--- a/tests/unit/health/test_plan_annotations.py
+++ b/tests/unit/health/test_plan_annotations.py
@@ -284,6 +284,16 @@ def test_changing_an_exported_jvm_symbol_warns_about_outside_callers() -> None:
)
+def test_changing_an_exported_go_method_warns_about_outside_callers() -> None:
+ exported = {"lib/send.go": {"lib/send.go::Client::Send": "lib/send.go"}}
+ notes = annotate(
+ plan(file_path="lib/send.go", target_symbol="Client.Send"),
+ AnnotationFacts(exported=exported),
+ )
+ assert kinds(notes) == ["public_api"]
+ assert notes.risks[0].text.endswith("breaks consumers outside the repo.")
+
+
def test_a_moved_exported_method_carries_one_public_api_risk() -> None:
exported = {
"svc/orders.py": {
diff --git a/tests/unit/ingestion/test_go_resolver.py b/tests/unit/ingestion/test_go_resolver.py
index c07fb0c43..0e319cf62 100644
--- a/tests/unit/ingestion/test_go_resolver.py
+++ b/tests/unit/ingestion/test_go_resolver.py
@@ -12,6 +12,10 @@ from repowise.core.ingestion.resolvers.go import (
resolve_go_import,
resolve_go_import_all,
)
+from repowise.core.ingestion.resolvers.go_workspace import (
+ build_go_package_index,
+ exported_go_files,
+)
def _ctx(repo: Path, paths: list[str], go_modules: tuple = ()) -> ResolverContext:
@@ -110,3 +114,25 @@ class TestResolveGoImportAll:
ctx = _ctx(tmp_path, ["main.go"], go_modules=(("", "github.com/me/app"),))
result = resolve_go_import_all("github.com/spf13/cobra", "main.go", ctx)
assert result == ("external:github.com/spf13/cobra",)
+
+
+class TestLegacyModulePathFallback:
+ def test_fallback_resolves_imports_but_exports_nothing(self, tmp_path: Path) -> None:
+ # Legacy ``go_module_path`` only: no go_modules tuple and no go.mod on disk.
+ (tmp_path / "pkg").mkdir()
+ (tmp_path / "pkg" / "util.go").write_text(
+ "package pkg\n\nfunc Util() {}\n", encoding="utf-8"
+ )
+ ctx = ResolverContext(
+ path_set={"pkg/util.go"},
+ stem_map={"util": ["pkg/util.go"]},
+ graph=nx.DiGraph(),
+ repo_path=tmp_path,
+ go_module_path="github.com/me/root",
+ )
+ index = build_go_package_index(ctx)
+ # The fallback still maps import paths...
+ assert index.import_path_to_dir == {"github.com/me/root/pkg": "pkg"}
+ # ...but it is not a real module, so nothing counts as exported.
+ assert index.modules == ()
+ assert exported_go_files(index) == []