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: flag public API in published C# projects (#3579)
Aman3cbea1065991
diff --git a/packages/core/src/repowise/core/analysis/dead_code/published_api.py b/packages/core/src/repowise/core/analysis/dead_code/published_api.pyindex 537921335..f729a0b41 100644--- a/packages/core/src/repowise/core/analysis/dead_code/published_api.py+++ b/packages/core/src/repowise/core/analysis/dead_code/published_api.py@@ -7,87 +7,24 @@ floor with a line naming the package, so a reader asking for every candidatestill sees it, labelled as published surface rather than as a cleanup item.Only a build that declares the package counts, never a guess from layout. The-evidence is read per language from :data:`_PUBLISHED_ROOTS`, each entry-returning ``{project dir: package name, or None when that project publishes-nothing}``. A file belongs to its innermost project, and only that project's-own build decides: a sample or test project nested in a packaged library's-folder is not part of the package. Today that is .NET: a project that opts into packing (``IsPackable``,-``PackageId``, ``GeneratePackageOnBuild``), or one that keeps a public-API-baseline (``PublicAPI.Shipped.txt``, the analyzer file a library commits so-every change to its shipped surface is reviewed).+evidence is read by :mod:`repowise.core.analysis.published_packages`, which the+per-symbol ``public_api`` flag reads too, so the two cannot disagree about what+ships. A file belongs to its innermost project, and only that project's own+build decides: a sample or test project nested in a packaged library's folder+is not part of the package."""from __future__ import annotations-from collections.abc import Callable, Iterable, Mapping-from dataclasses import dataclass-from pathlib import Path, PurePosixPath-from typing import Any--from repowise.core.fsutils import repo_relative+from collections.abc import Iterable, Mapping+from ..published_packages import PUBLISHED_ROOTS, BuildFacts, package_offrom .models import DeadCodeFindingData, DeadCodeKind#: Where a published symbol lands: under ``RISK_CAP_CONFIDENCE``, so the#: default report and the stored index leave it out.PUBLISHED_API_CONFIDENCE = 0.3-#: The public-API analyzer's baseline file, beside the project or in a folder-#: of its own (``.PublicAPI/``).-_API_BASELINE = "PublicAPI.Shipped.txt"---@dataclass(frozen=True)-class BuildFacts:- """What the per-language readers may consult; a new language adds a field."""-- repo_root: Path | None- dotnet_index: Any | None---def _keeps_api_baseline(project_dir: Path) -> bool:- try:- folders = [project_dir, *(p for p in project_dir.iterdir() if p.is_dir())]- return any((folder / _API_BASELINE).is_file() for folder in folders)- except OSError:- return False---def _dotnet_published(facts: BuildFacts) -> dict[str, str | None]:- """Every .NET project dir, mapped to the package it ships or None."""- index = facts.dotnet_index- if index is None:- return {}- root = Path(index.repo_path)- out: dict[str, str | None] = {}- for project in index.projects.values():- rel = repo_relative(project.project_dir, root, resolve=True)- if rel is None:- continue- rel = "" if rel == "." else rel- name = project.published_id- if name is None and _keeps_api_baseline(project.project_dir):- name = project.assembly_name or project.path.stem- out[rel] = name- return out---#: Language -> reader of the build files that declare a published package.-#: A language without an entry has no published-surface rule yet.-_PUBLISHED_ROOTS: dict[str, Callable[[BuildFacts], Mapping[str, str | None]]] = {- "csharp": _dotnet_published,- "vbnet": _dotnet_published,-}---def _package_of(path: str, roots: Mapping[str, str | None]) -> str | None:- """The package of the innermost project enclosing *path*, if it ships one."""- for parent in PurePosixPath(path).parents:- key = "" if str(parent) == "." else parent.as_posix()- if key in roots:- return roots[key]- return None-def demote_published_api(findings: list[DeadCodeFindingData],@@ -103,12 +40,12 @@ def demote_published_api(roots: dict[str, Mapping[str, str | None]] = {}for finding in _published_candidates(findings):language = languages.get(finding.file_path)- reader = _PUBLISHED_ROOTS.get(language or "")+ reader = PUBLISHED_ROOTS.get(language or "")if reader is None:continueif language not in roots:roots[language] = reader(facts)- package = _package_of(finding.file_path, roots[language])+ package = package_of(finding.file_path, roots[language])if package is None:continuefinding.confidence = min(finding.confidence, PUBLISHED_API_CONFIDENCE)diff --git a/packages/core/src/repowise/core/analysis/public_api.py b/packages/core/src/repowise/core/analysis/public_api.pyindex ef4302d20..75193851d 100644--- a/packages/core/src/repowise/core/analysis/public_api.py+++ b/packages/core/src/repowise/core/analysis/public_api.py@@ -6,6 +6,8 @@ manifest names as the start (``package.json`` ``bin``/``main``/``exports["."]``,``FileInfo.is_manifest_entry``) declares or re-exports through barrels. It isread off the parsed imports, never guessed by a model, so a class that nothingin the repo imports still appears when the package's front door publishes it.+A .NET project that ships a package (:mod:`.published_packages`) has no front+door: every public type its C# files declare is published.Two readers share it: a wiki page's Public API section, and the per-symbol``public_api`` flag the graph carries (:func:`stamp_public_api`).@@ -420,19 +422,77 @@ def _sibling_owner(return None+def _local_id(sym: Any, path: str) -> str:+ """A top-level symbol's id within its file (``Box`1`` for a generic ``Box<T>``)."""+ return sym.id[len(path) + 2 :]+++def _publish_csharp_types(+ parsed: Mapping[str, Any], roots: Iterable[str], out: dict[str, str]+) -> None:+ """Publish every public top-level type a C# file of a shipped project declares.++ :func:`_declared` keys a file's symbols by name, so ``Box<T>`` and ``Box``+ declared together would leave one of them out; C# tells them apart by+ type-parameter count, which the symbol id carries.+ """+ for root in roots:+ pf = parsed[root]+ if pf.file_info.language != "csharp":+ continue+ for sym in pf.symbols:+ if (+ sym.parent_name is None+ and sym.visibility == "public"+ and sym.kind not in _UNPUBLISHED_KINDS+ ):+ out.setdefault(sym.id, root)+++def _publish_partial_fragments(+ parsed: Mapping[str, Any],+ fragments: Mapping[str, AbstractSet[str]],+ out: dict[str, str],+) -> None:+ """Publish the ``partial`` fragments of a published C# type.++ Every fragment of a partial type has the accessibility of the one that+ declares it, but a fragment written without a modifier reads ``internal``,+ so its type and members would be missed. *fragments* maps a C# file to the+ files holding the other fragments of its partial types. A fragment is+ published when the same type, in one of those files, already is.+ """+ for path, others in sorted(fragments.items()):+ pf = parsed.get(path)+ if pf is None or pf.file_info.is_test:+ continue+ for sym in pf.symbols:+ if sym.parent_name is not None or sym.id in out or "partial" not in sym.modifiers:+ continue+ local = _local_id(sym, path)+ for other in sorted(others):+ twin = next((s for s in parsed[other].symbols if s.id == f"{other}::{local}"), None)+ if twin is not None and "partial" in twin.modifiers and twin.id in out:+ out[sym.id] = path+ break++def public_symbols(parsed: Mapping[str, Any],entries: AbstractSet[str] = frozenset(),package_files: Mapping[str, Sequence[str]] | None = None,+ fragments: Mapping[str, AbstractSet[str]] | None = None,) -> dict[str, str]:"""``{symbol id: the file that exports it}`` for every symbol consumers can import.Exported means a barrel or a package entry publishes it (re-exports and``__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.+ ``package.json`` ``exports`` map names or a shipped .NET project holds+ (: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. *fragments* are the C# files that share a ``partial``+ type (:func:`_publish_partial_fragments`)."""resolver = _Resolver(parsed)out: dict[str, str] = {}@@ -441,7 +501,12 @@ def public_symbols(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)+ _publish_csharp_types(parsed, roots, out)+ if fragments:+ _publish_partial_fragments(parsed, fragments, out)+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@@ -452,6 +517,22 @@ def public_symbols(return out+def _partial_fragments(graph: Any, parsed: Mapping[str, Any]) -> dict[str, set[str]]:+ """``{C# file: the files holding other fragments of its partial types}``.++ The graph links the files of one partial type with ``partial_class``+ import edges, in both directions.+ """+ out: dict[str, set[str]] = {}+ for path, pf in parsed.items():+ if pf.file_info.language != "csharp" or path not in graph:+ continue+ for _u, other, data in graph.out_edges(path, data=True):+ if data.get("hint_source") == "partial_class" and other in parsed:+ out.setdefault(path, set()).add(other)+ return out++def stamp_public_api(graph: Any,parsed: Mapping[str, Any],@@ -461,7 +542,7 @@ def stamp_public_api(entries = {path for path in parsed if graph.nodes.get(path, {}).get("package_export")}- exported = public_symbols(parsed, entries, package_files)+ exported = public_symbols(parsed, entries, package_files, _partial_fragments(graph, parsed))for pf in parsed.values():for sym in pf.symbols:node = graph.nodes.get(sym.id)diff --git a/packages/core/src/repowise/core/analysis/published_packages.py b/packages/core/src/repowise/core/analysis/published_packages.pynew file mode 100644index 000000000..ec761d507--- /dev/null+++ b/packages/core/src/repowise/core/analysis/published_packages.py@@ -0,0 +1,88 @@+"""Which project of a repository ships a package, read from its build files.++Two readers share this: the dead-code pass, which keeps an unused export of a+published package below the review floor, and the per-symbol ``public_api``+flag (:mod:`repowise.core.analysis.public_api`), which marks that same surface+on the graph. They read one answer, so they cannot disagree about what ships.++Only a build that declares the package counts, never a guess from layout. The+evidence is read per language from :data:`PUBLISHED_ROOTS`, each entry+returning ``{project dir: package name, or None when that project publishes+nothing}``. A file belongs to its innermost project, and only that project's+own build decides: a sample or test project nested in a packaged library's+folder is not part of the package. Today that is .NET: a project that opts into+packing (``IsPackable``, ``PackageId``, ``GeneratePackageOnBuild``), or one that+keeps a public-API baseline (``PublicAPI.Shipped.txt``, the analyzer file a+library commits so every change to its shipped surface is reviewed).+"""++from __future__ import annotations++from collections.abc import Callable, Mapping+from dataclasses import dataclass+from pathlib import Path, PurePosixPath+from typing import Any++from repowise.core.fsutils import repo_relative++#: The public-API analyzer's baseline file, beside the project or in a folder+#: of its own (``.PublicAPI/``).+API_BASELINE = "PublicAPI.Shipped.txt"+++@dataclass(frozen=True)+class BuildFacts:+ """What the per-language readers may consult; a new language adds a field."""++ repo_root: Path | None+ dotnet_index: Any | None+++def _relative(path: Path, root: Path) -> str | None:+ rel = repo_relative(path, root, resolve=True)+ if rel is None:+ return None+ return "" if rel == "." else rel+++def keeps_api_baseline(project_dir: Path) -> bool:+ try:+ folders = [project_dir, *(p for p in project_dir.iterdir() if p.is_dir())]+ return any((folder / API_BASELINE).is_file() for folder in folders)+ except OSError:+ return False+++def dotnet_published(facts: BuildFacts) -> dict[str, str | None]:+ """Every .NET project dir, mapped to the package it ships or None."""+ index = facts.dotnet_index+ if index is None:+ return {}+ root = Path(index.repo_path)+ out: dict[str, str | None] = {}+ for project in index.projects.values():+ rel = _relative(project.project_dir, root)+ if rel is None:+ continue+ name = project.published_id+ if name is None and keeps_api_baseline(project.project_dir):+ name = project.assembly_name or project.path.stem+ out[rel] = name+ return out+++#: Language -> reader of the build files that declare a published package.+#: A language without an entry has no published-surface rule yet.+PUBLISHED_ROOTS: dict[str, Callable[[BuildFacts], Mapping[str, str | None]]] = {+ "csharp": dotnet_published,+ "vbnet": dotnet_published,+}+++def package_of(path: str, roots: Mapping[str, str | None]) -> str | None:+ """The package of the innermost project enclosing *path*, if it ships one."""+ for parent in PurePosixPath(path).parents:+ key = "" if str(parent) == "." else parent.as_posix()+ if key in roots:+ return roots[key]+ return Nonediff --git a/packages/core/src/repowise/core/ingestion/graph_warmups.py b/packages/core/src/repowise/core/ingestion/graph_warmups.pyindex a80cae60f..9bd1d3d21 100644--- a/packages/core/src/repowise/core/ingestion/graph_warmups.py+++ b/packages/core/src/repowise/core/ingestion/graph_warmups.py@@ -417,9 +417,32 @@ def _warmup_swift(ctx: ResolverContext) -> None:def _warmup_dotnet(ctx: ResolverContext) -> None:+ """Build the .NET project index, then mark every C# file of a project that+ ships a package as published, for the per-symbol public API flag+ (``analysis.public_api``).++ The package comes from the same reader dead code uses, so the two cannot+ disagree about what ships. A file belongs to its innermost project: a+ sample or test project nested in a library's folder ships nothing. With no+ readable project file nothing is stamped.+ """+ from ..analysis.published_packages import BuildFacts, dotnet_published, package_offrom .resolvers.dotnet import get_or_build_index- get_or_build_index(ctx)+ index = get_or_build_index(ctx)+ graph = getattr(ctx, "graph", None)+ if index is None or graph is None:+ return+ roots = dotnet_published(BuildFacts(repo_root=index.repo_path, dotnet_index=index))+ if not any(roots.values()):+ return+ parsed = getattr(ctx, "parsed_files", None) or {}+ for path, pf in parsed.items():+ if pf.file_info.language != "csharp":+ continue+ node = graph.nodes.get(path)+ if node is not None and package_of(path, roots):+ node["package_export"] = Truedef _warmup_rust(ctx: ResolverContext) -> None:diff --git a/tests/unit/analysis/test_public_api_flag.py b/tests/unit/analysis/test_public_api_flag.pyindex 2e16b328a..758f0a59e 100644--- a/tests/unit/analysis/test_public_api_flag.py+++ b/tests/unit/analysis/test_public_api_flag.py@@ -371,4 +371,161 @@ def test_go_method_of_an_unexported_type_is_not_public(tmp_path: Path) -> None:"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+ assert flags["lib/b.go::client::Send"] == ""++# ---------------------------------------------------------------------------+# C#: a type of a project that ships a package is public API+# ---------------------------------------------------------------------------+++def _csproj(props: str = "") -> str:+ return f'<Project Sdk="Microsoft.NET.Sdk"><PropertyGroup>{props}</PropertyGroup></Project>'+++def build_files(repo: Path, files: dict[str, str]) -> dict[str, str]:+ """Build a graph from *files*; ``{symbol id: public_api}`` for every symbol."""+ for rel, body in files.items():+ (repo / rel).parent.mkdir(parents=True, exist_ok=True)+ (repo / rel).write_text(body, encoding="utf-8")+ parser = ASTParser()+ builder = GraphBuilder(repo)+ for fi in FileTraverser(repo).traverse():+ builder.add_file(parser.parse_file(fi, Path(fi.abs_path).read_bytes()))+ builder.build()+ return {+ node: data["public_api"]+ for node, data in builder.graph().nodes(data=True)+ if data.get("node_type") == "symbol" and "public_api" in data+ }+++_CSHARP_REPO = {+ # Packs by opting in.+ "src/Lib/Lib.csproj": _csproj("<IsPackable>true</IsPackable>"),+ "src/Lib/Client.cs": (+ "namespace Lib;\n"+ "public class Client\n{\n public void Send() { }\n private void Retry() { }\n}\n"+ "internal class Helper\n{\n public void Go() { }\n}\n"+ "class Implicit\n{\n public void Go() { }\n}\n"+ ),+ # Sets no packing property: shipped by the baseline it keeps.+ "src/Base/Base.csproj": _csproj(),+ "src/Base/.PublicAPI/PublicAPI.Shipped.txt": "Base.Thing\n",+ "src/Base/Thing.cs": "namespace Base;\npublic class Thing\n{\n public void Do() { }\n}\n",+ # Says nothing about packing, so ships nothing.+ "samples/App/App.csproj": _csproj(),+ "samples/App/Program.cs": "namespace App;\npublic class Program\n{\n public void Main() { }\n}\n",+ "tests/Lib.Tests/Lib.Tests.csproj": _csproj(),+ "tests/Lib.Tests/ClientTests.cs": (+ "namespace Lib.Tests;\npublic class ClientTests\n{\n public void Works() { }\n}\n"+ ),+ # An explicit no beats a PackageId.+ "src/Nope/Nope.csproj": _csproj("<IsPackable>false</IsPackable><PackageId>Nope</PackageId>"),+ "src/Nope/Widget.cs": "namespace Nope;\npublic class Widget\n{\n public void Spin() { }\n}\n",+ # A sample nested in the packaged library's folder is not part of the package.+ "src/Lib/samples/Demo/Demo.csproj": _csproj(),+ "src/Lib/samples/Demo/Demo.cs": "namespace Demo;\npublic class Demo\n{\n public void Run() { }\n}\n",+}+++def test_public_csharp_types_of_a_shipped_project_are_public_api(tmp_path: Path) -> None:+ flags = build_files(tmp_path, _CSHARP_REPO)+ stamped = {node for node, root in flags.items() if root}+ assert stamped == {+ "src/Lib/Client.cs::Client",+ "src/Lib/Client.cs::Client::Send",+ "src/Base/Thing.cs::Thing",+ "src/Base/Thing.cs::Thing::Do",+ }+ # The file that exports a symbol is the file that declares it.+ assert flags["src/Lib/Client.cs::Client::Send"] == "src/Lib/Client.cs"+ assert flags["src/Base/Thing.cs::Thing"] == "src/Base/Thing.cs"+ # A private member, internal and modifier-less types (and their public+ # members), and every type of a project that ships nothing stay unflagged.+ for node in (+ "src/Lib/Client.cs::Client::Retry",+ "src/Lib/Client.cs::Helper",+ "src/Lib/Client.cs::Helper::Go",+ "src/Lib/Client.cs::Implicit",+ "src/Lib/Client.cs::Implicit::Go",+ "samples/App/Program.cs::Program",+ "samples/App/Program.cs::Program::Main",+ "tests/Lib.Tests/ClientTests.cs::ClientTests",+ "tests/Lib.Tests/ClientTests.cs::ClientTests::Works",+ "src/Nope/Widget.cs::Widget",+ "src/Nope/Widget.cs::Widget::Spin",+ "src/Lib/samples/Demo/Demo.cs::Demo",+ "src/Lib/samples/Demo/Demo.cs::Demo::Run",+ ):+ assert flags[node] == "", node+++def test_a_repo_with_no_readable_project_stamps_no_csharp(tmp_path: Path) -> None:+ files = {rel: body for rel, body in _CSHARP_REPO.items() if not rel.endswith(".csproj")}+ assert not {node for node, root in build_files(tmp_path, files).items() if root}+++def test_every_generic_arity_of_a_public_type_is_public_api(tmp_path: Path) -> None:+ flags = build_files(+ tmp_path,+ {+ "Lib/Lib.csproj": _csproj("<IsPackable>true</IsPackable>"),+ "Lib/Box.cs": (+ "namespace Lib;\n"+ "public class Box<T>\n{\n public void Put() { }\n}\n"+ "public class Box\n{\n public void Open() { }\n}\n"+ ),+ },+ )+ # ``Box<T>`` and ``Box`` share a name; the id tells them apart.+ assert {node for node, root in flags.items() if root} == {+ "Lib/Box.cs::Box`1",+ "Lib/Box.cs::Box`1::Put",+ "Lib/Box.cs::Box",+ "Lib/Box.cs::Box::Open",+ }+++def test_a_partial_fragment_without_a_modifier_takes_the_public_part(tmp_path: Path) -> None:+ flags = build_files(+ tmp_path,+ {+ "src/Lib/Lib.csproj": _csproj("<IsPackable>true</IsPackable>"),+ "src/Lib/Pipeline.cs": (+ "namespace Lib;\npublic partial class Pipeline\n{\n public void Build() { }\n}\n"+ ),+ "src/Lib/Pipeline.Sync.cs": (+ "namespace Lib;\npartial class Pipeline\n{\n"+ " public void Run() { }\n private void Spin() { }\n}\n"+ ),+ },+ )+ assert flags["src/Lib/Pipeline.cs::Pipeline::Build"] == "src/Lib/Pipeline.cs"+ # The part with no modifier is the public type too, and so are its members.+ assert flags["src/Lib/Pipeline.Sync.cs::Pipeline"] == "src/Lib/Pipeline.Sync.cs"+ assert flags["src/Lib/Pipeline.Sync.cs::Pipeline::Run"] == "src/Lib/Pipeline.Sync.cs"+ assert flags["src/Lib/Pipeline.Sync.cs::Pipeline::Spin"] == ""+++def test_partial_fragments_of_an_internal_type_stay_unflagged(tmp_path: Path) -> None:+ flags = build_files(+ tmp_path,+ {+ "Lib/Lib.csproj": _csproj("<IsPackable>true</IsPackable>"),+ "Lib/Engine.cs": "namespace Lib;\ninternal partial class Engine\n{\n public void A() { }\n}\n",+ "Lib/Engine.More.cs": "namespace Lib;\npartial class Engine\n{\n public void B() { }\n}\n",+ },+ )+ assert not {node for node, root in flags.items() if root}+++def test_partial_fragments_in_a_project_that_ships_nothing_stay_unflagged(tmp_path: Path) -> None:+ flags = build_files(+ tmp_path,+ {+ "App/App.csproj": _csproj(),+ "App/Job.cs": "namespace App;\npublic partial class Job\n{\n public void A() { }\n}\n",+ "App/Job.More.cs": "namespace App;\npartial class Job\n{\n public void B() { }\n}\n",+ },+ )+ assert not {node for node, root in flags.items() if root}diff --git a/tests/unit/health/test_plan_annotations.py b/tests/unit/health/test_plan_annotations.pyindex d46c871cb..42f3b1d93 100644--- a/tests/unit/health/test_plan_annotations.py+++ b/tests/unit/health/test_plan_annotations.py@@ -294,6 +294,23 @@ def test_changing_an_exported_go_method_warns_about_outside_callers() -> None:assert notes.risks[0].text.endswith("breaks consumers outside the repo.")+def test_changing_an_exported_csharp_method_warns_about_outside_callers() -> None:+ exported = {+ "src/Lib/Client.cs": {"src/Lib/Client.cs::Client::Send": "src/Lib/Client.cs"},+ }+ facts = AnnotationFacts(exported=exported)+ notes = annotate(plan(file_path="src/Lib/Client.cs", target_symbol="Client.Send"), facts)+ assert notes.risks == (+ PlanRisk(+ "public_api",+ "`Client.Send` is exported from `src/Lib/Client.cs`; changing its signature "+ "breaks consumers outside the repo.",+ ),+ )+ # Only the exported member, never a neighbour in the same file.+ assert not annotate_any(plan(file_path="src/Lib/Client.cs", target_symbol="Retry"), facts)++def test_a_moved_exported_method_carries_one_public_api_risk() -> None:exported = {"svc/orders.py": {