Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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-symbolfrom __future__ import annotationsimport ast-from collections.abc import Iterable, Mapping+from collections.abc import Iterable, Mapping, Sequencefrom collections.abc import Set as AbstractSetfrom pathlib import Path, PurePosixPathfrom typing import Any@@ -397,8 +397,32 @@ def export_roots(parsed: Mapping[str, Any], entries: AbstractSet[str] = frozensereturn 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 methodof 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.pyindex 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_forfrom ..models import Import, ParsedFile, Symbol, combine_load_kindsfrom ..resolvers import ResolverContext, resolve_importfrom ..resolvers.go import read_go_module_path, read_go_modules+from ..resolvers.go_workspace import cached_go_index, go_package_filesfrom ..symbol_identity import has_overload_identityfrom ..type_ref_resolution import resolve_type_refsfrom ._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 indexlog.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.pyindex 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 abinary entry as ``cmd/release/main.go``, so the traverser's stemheuristic 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_indexindex = 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"] = Truedef _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.pyindex 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 longestmodule-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 = Nonebest_len = -1@@ -161,6 +166,17 @@ def _import_path_for_dir(return Nonemodule_dir, mod_path = bestsuffix = 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 = foundreturn 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.pyindex 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 filediff --git a/tests/unit/health/test_plan_annotations.py b/tests/unit/health/test_plan_annotations.pyindex 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.pyindex 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) == []