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.

17.2 KB
Raw Blame
"""Package pages and their computed Public API.

A package root always heads a page covering the whole package, and that page's
prompt carries what the package publishes: read from the manifest's entries
and the re-exports behind them, never guessed. A class nothing in the repo
imports is still public when the package's front door re-exports it.
"""

from __future__ import annotations

import json
from pathlib import Path
from types import SimpleNamespace

import networkx as nx

from repowise.core.analysis.public_api import (
    _Resolver,
    api_roots,
    compute_public_api,
)
from repowise.core.generation.context_assembler import ContextAssembler, FilePageContext
from repowise.core.generation.page_generator import PageGenerator
from repowise.core.generation.page_generator.levels import _rollup_child_pages
from repowise.core.generation.selection.selector import _build_module_groups
from repowise.core.ingestion.graph import GraphBuilder
from repowise.core.ingestion.package_roots import package_roots_from_paths
from repowise.core.ingestion.parser import ASTParser
from repowise.core.ingestion.traverser import FileTraverser
from repowise.core.providers.llm.mock import MockProvider
from tests.unit.generation.test_concept_package_walls import _selection_inputs
from tests.unit.generation.test_selection_contract import FakeFileInfo, FakeParsedFile


def _index(repo: Path, files: dict[str, str]) -> dict:
    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 builder._parsed_files


_SDK = {
    "packages/sdk/package.json": json.dumps({"name": "sdk", "main": "./dist/index.js"}),
    "packages/sdk/src/index.ts": (
        "export * from './client';\nexport { Tool as SdkTool } from './tools';\n"
        "export { Client as LegacyClient } from './client';\n"
        "export * as tools from './tools';\n"
    ),
    "packages/sdk/src/client.ts": (
        "/** Talks to the service. */\nexport class Client {\n  send(): void {}\n}\n"
        "function helper(): number { return 1; }\n"
    ),
    "packages/sdk/src/tools.ts": "export class Tool {}\nexport class Hidden {}\n",
    "packages/sdk/src/internal.ts": "export function notPublished(): void {}\n",
    "packages/py/pyproject.toml": '[project]\nname = "pysdk"\n',
    "packages/py/pysdk/__init__.py": "from ._client import Client\nfrom .models import *\n",
    "packages/py/pysdk/_client.py": 'class Client:\n    """Python client."""\n',
    "packages/py/pysdk/models.py": "class Model:\n    pass\n\ndef _private():\n    pass\n",
}


def _api(parsed: dict, prefix: str) -> list[dict]:
    material = [p for p in parsed if p.startswith(prefix)]
    return compute_public_api(material, parsed, package_roots_from_paths(set(parsed)))


def test_manifest_entries_are_the_roots(tmp_path):
    parsed = _index(tmp_path, _SDK)
    roots = api_roots(list(parsed), parsed, package_roots_from_paths(set(parsed)))
    assert roots == ["packages/py/pysdk/__init__.py", "packages/sdk/src/index.ts"]


def test_reexported_class_with_no_importers_is_public(tmp_path):
    parsed = _index(tmp_path, _SDK)
    ts = {(e["name"], e["file"]) for e in _api(parsed, "packages/sdk/")}
    # ``Client`` has in-degree 0 in the repo; the barrel alone publishes it.
    assert ("Client", "packages/sdk/src/client.ts") in ts
    assert ("SdkTool", "packages/sdk/src/tools.ts") in ts
    names = {name for name, _ in ts}
    assert not names & {"Hidden", "notPublished", "helper", "send", "Tool"}
    by_name = {e["name"]: e for e in _api(parsed, "packages/sdk/")}
    # A second name for one symbol is listed, pointing at the first, with no excerpt.
    assert by_name["LegacyClient"]["alias_of"] == "Client"
    assert not by_name["LegacyClient"]["signature"]
    # ``export * as ns`` publishes the module itself, not its members.
    assert (by_name["tools"]["kind"], by_name["tools"]["file"]) == (
        "module",
        "packages/sdk/src/tools.ts",
    )

    py = {(e["name"], e["file"]) for e in _api(parsed, "packages/py/")}
    assert py == {
        ("Client", "packages/py/pysdk/_client.py"),
        ("Model", "packages/py/pysdk/models.py"),
    }


def test_barrel_is_the_root_when_no_manifest_names_one(tmp_path):
    parsed = _index(
        tmp_path,
        {
            "lib/__init__.py": "from .core import Engine\n",
            "lib/core.py": "class Engine:\n    pass\n",
            "lib/sub/__init__.py": "from .x import Deep\n",
            "lib/sub/x.py": "class Deep:\n    pass\n",
        },
    )
    assert [e["name"] for e in compute_public_api(list(parsed), parsed, set())] == ["Engine"]


class _RecordingProvider(MockProvider):
    async def generate(self, *args, **kwargs):
        response = await super().generate(*args, **kwargs)
        response.content = "# SDK\n\nThe SDK client.\n"
        return response


def _context(path: str) -> FilePageContext:
    return FilePageContext(
        file_path=path,
        language="typescript",
        docstring=None,
        symbols=[],
        imports=[],
        exports=[],
        pagerank_score=0.1,
        betweenness_score=0.0,
        community_id=0,
        dependents=[],
        dependencies=[],
        is_api_contract=False,
        is_entry_point=False,
        is_test=False,
        parse_errors=[],
        estimated_tokens=10,
    )


async def test_public_api_reaches_the_prompt_excerpts(tmp_path, sample_config):
    parsed = _index(tmp_path, _SDK)
    api = _api(parsed, "packages/sdk/")
    provider = _RecordingProvider()
    gen = PageGenerator(provider, ContextAssembler(sample_config), sample_config)
    await gen.generate_module_page(
        "SDK",
        "typescript",
        [_context("packages/sdk/src/index.ts")],
        nx.DiGraph(),
        target_path="packages/sdk",
        public_api=api,
    )
    prompt = provider._calls[-1]["user_prompt"]
    assert '"public_api": [' in prompt
    assert '"name": "Client"' in prompt
    assert '"signature": "class Client' in prompt
    assert "Talks to the service." in prompt


def test_public_api_past_the_budget_keeps_every_name(sample_config):
    api = [
        {"name": f"f{i}", "kind": "function", "file": "a.ts", "signature": "x" * 400, "doc": ""}
        for i in range(200)
    ]
    ctx = ContextAssembler(sample_config).assemble_module_page(
        "A", "typescript", [_context("a.ts")], nx.DiGraph(), public_api=api
    )
    assert [e["name"] for e in ctx.public_api] == [e["name"] for e in api]
    assert ctx.public_api[0]["signature"] and not ctx.public_api[-1]["signature"]


def test_a_package_split_across_groups_gets_its_own_whole_package_page():
    """``packages/kernel`` splits into leaves one level below its root, so no
    chapter would sit at the root itself; being a package puts one there."""
    inputs = _selection_inputs()
    groups = [mg for _, mg in _build_module_groups(inputs).scored]
    kernel = [mg for mg in groups if mg.key == "packages/kernel"]
    assert len(kernel) == 1 and kernel[0].is_rollup
    files = {p.file_info.path for p in inputs.parsed_files}
    assert set(kernel[0].context_paths) == {
        f for f in files if f.startswith("packages/kernel/") and f.endswith(".ts")
    }


def test_a_package_page_is_kept_even_when_it_is_most_of_the_repo():
    files = [f"packages/core/src/{d}/f{i}.py" for d in "abcdef" for i in range(10)]
    parsed = [FakeParsedFile(file_info=FakeFileInfo(path=p)) for p in files]
    parsed.append(FakeParsedFile(file_info=FakeFileInfo(path="packages/core/pyproject.toml")))
    inputs = _selection_inputs()
    inputs.parsed_files = parsed
    keys = {mg.key for _, mg in _build_module_groups(inputs).scored}
    assert "packages/core" in keys


def test_rollup_links_to_leaves_below_it_with_no_chapter_between():
    g = lambda key, rollup=False: SimpleNamespace(key=key, display=key, is_rollup=rollup)  # noqa: E731
    pkg, sub = g("pkgs/a", True), g("pkgs/a/src/x/deep", True)
    groups = [pkg, g("pkgs/a/src/io"), g("pkgs/a/src/model"), sub, g("pkgs/a/src/x/deep/y")]
    assert [c["path"] for c in _rollup_child_pages(pkg, groups)] == [
        "pkgs/a/src/io",
        "pkgs/a/src/model",
        "pkgs/a/src/x/deep",
    ]
    assert [c["path"] for c in _rollup_child_pages(sub, groups)] == ["pkgs/a/src/x/deep/y"]


def test_python_dunder_all_decides_what_is_published(tmp_path):
    parsed = _index(
        tmp_path,
        {
            "pyproject.toml": '[project]\nname = "lib"\n',
            "lib/__init__.py": (
                "from .__version__ import __version__\nfrom ._models import *\n"
                "from ._util import helper\n\n__all__ = ['__version__', 'Request', 'helper']\n"
            ),
            "lib/__version__.py": '__version__ = "1.0"\n',
            "lib/_models.py": "__all__ = ['Request']\n\nclass Request:\n    pass\n\nclass Unlisted:\n    pass\n",
            "lib/_util.py": "__all__ = []\n\ndef helper():\n    pass\n",
        },
    )
    # A named import reaches past the source's ``__all__``; a wildcard does not.
    names = [e["name"] for e in compute_public_api(list(parsed), parsed, set())]
    assert sorted(names) == ["Request", "__version__", "helper"]


def test_python_lazy_getattr_map_publishes_literal_exports(tmp_path):
    parsed = _index(
        tmp_path,
        {
            "pyproject.toml": '[project]\nname = "lazy-lib"\n',
            "lazy_lib/__init__.py": (
                "__all__ = ['extract', 'generate', 'missing']\n"
                "_LAZY: dict[str, str] = {\n"
                "    'extract': ('.extract', 'extract'),\n"
                "    'generate': ('.report', 'generate'),\n"
                "    'missing': '.missing',\n"
                "}\n\n"
                "def __getattr__(name):\n"
                "    if name in _LAZY:\n"
                "        module_name, attr = _LAZY[name]\n"
                "        return getattr(importlib.import_module(module_name, __name__), attr)\n"
                "    raise AttributeError(name)\n"
            ),
            "lazy_lib/extract.py": "def extract():\n    pass\n",
            "lazy_lib/report.py": "def generate():\n    pass\n",
        },
    )

    api = compute_public_api(list(parsed), parsed, set())

    assert {(entry["name"], entry["file"]) for entry in api} == {
        ("extract", "lazy_lib/extract.py"),
        ("generate", "lazy_lib/report.py"),
    }


def test_python_local_lazy_getattr_map_publishes_literal_exports(tmp_path):
    parsed = _index(
        tmp_path,
        {
            "pyproject.toml": '[project]\nname = "lazy-lib"\n',
            "lazy_lib/__init__.py": (
                "def __getattr__(name):\n"
                "    lazy = {'extract': ('lazy_lib.extract', 'extract')}\n"
                "    if name in lazy:\n"
                "        module_name, attr = lazy[name]\n"
                "        return getattr(importlib.import_module(module_name, __name__), attr)\n"
                "    raise AttributeError(name)\n"
            ),
            "lazy_lib/extract.py": "def extract():\n    pass\n",
        },
    )

    api = compute_public_api(list(parsed), parsed, set())

    assert [(entry["name"], entry["file"]) for entry in api] == [
        ("extract", "lazy_lib/extract.py")
    ]


def test_python_computed_lazy_getattr_map_is_ignored(tmp_path):
    parsed = _index(
        tmp_path,
        {
            "pyproject.toml": '[project]\nname = "lazy-lib"\n',
            "lazy_lib/__init__.py": (
                "__all__ = ['extract']\n"
                "_NAMES = ['extract']\n"
                "_LAZY = {name: ('.extract', name) for name in _NAMES}\n\n"
                "def __getattr__(name):\n"
                "    if name in _LAZY:\n"
                "        module_name, attr = _LAZY[name]\n"
                "        return getattr(importlib.import_module(module_name, __name__), attr)\n"
                "    raise AttributeError(name)\n"
            ),
            "lazy_lib/extract.py": "def extract():\n    pass\n",
        },
    )

    api = compute_public_api(list(parsed), parsed, set())

    assert api == []


def test_python_computed_rebinding_invalidates_an_earlier_lazy_map(tmp_path):
    parsed = _index(
        tmp_path,
        {
            "pyproject.toml": '[project]\nname = "lazy-lib"\n',
            "lazy_lib/__init__.py": (
                "__all__ = ['extract']\n"
                "_LAZY = {'extract': '.extract'}\n"
                "_NAMES = ['extract']\n"
                "_LAZY = {name: '.extract' for name in _NAMES}\n\n"
                "def __getattr__(name):\n"
                "    if name in _LAZY:\n"
                "        return getattr(importlib.import_module(_LAZY[name], __name__), name)\n"
                "    raise AttributeError(name)\n"
            ),
            "lazy_lib/extract.py": "def extract():\n    pass\n",
        },
    )

    api = compute_public_api(list(parsed), parsed, set())

    assert api == []


def test_python_lazy_getattr_does_not_shadow_declared_names(tmp_path):
    parsed = _index(
        tmp_path,
        {
            "pyproject.toml": '[project]\nname = "lazy-lib"\n',
            "lazy_lib/__init__.py": (
                "from .eager import Client\n"
                "__all__ = ['Client']\n"
                "_LAZY = {'Client': ('.lazy', 'Client')}\n\n"
                "def __getattr__(name):\n"
                "    if name in _LAZY:\n"
                "        module_name, attr = _LAZY[name]\n"
                "        return getattr(importlib.import_module(module_name, __name__), attr)\n"
                "    raise AttributeError(name)\n"
            ),
            "lazy_lib/eager.py": "class Client:\n    pass\n",
            "lazy_lib/lazy.py": "class Client:\n    pass\n",
        },
    )

    api = compute_public_api(list(parsed), parsed, set())

    assert [(entry["name"], entry["file"]) for entry in api] == [
        ("Client", "lazy_lib/eager.py")
    ]


def test_python_lazy_getattr_does_not_shadow_a_module_alias(tmp_path):
    parsed = _index(
        tmp_path,
        {
            "pyproject.toml": '[project]\nname = "lazy-lib"\n',
            "lazy_lib/__init__.py": (
                "import lazy_lib.eager as Client\n"
                "__all__ = ['Client']\n"
                "_LAZY = {'Client': ('.lazy', 'Client')}\n\n"
                "def __getattr__(name):\n"
                "    if name in _LAZY:\n"
                "        module_name, attr = _LAZY[name]\n"
                "        return getattr(importlib.import_module(module_name, __name__), attr)\n"
                "    raise AttributeError(name)\n"
            ),
            "lazy_lib/eager.py": "class Client:\n    pass\n",
            "lazy_lib/lazy.py": "class Client:\n    pass\n",
        },
    )

    api = compute_public_api(list(parsed), parsed, set())

    assert api == []


def test_python_deferred_imports_do_not_shadow_lazy_exports(tmp_path):
    parsed = _index(
        tmp_path,
        {
            "pyproject.toml": '[project]\nname = "lazy-lib"\n',
            "lazy_lib/__init__.py": (
                "__all__ = ['Client']\n"
                "_LAZY = {'Client': ('.lazy', 'Client')}\n\n"
                "def __getattr__(name):\n"
                "    from .eager import Client\n"
                "    if name in _LAZY:\n"
                "        module_name, attr = _LAZY[name]\n"
                "        return getattr(importlib.import_module(module_name, __name__), attr)\n"
                "    raise AttributeError(name)\n"
            ),
            "lazy_lib/eager.py": "class Client:\n    pass\n",
            "lazy_lib/lazy.py": "class Client:\n    pass\n",
        },
    )

    api = compute_public_api(list(parsed), parsed, set())

    assert [(entry["name"], entry["file"]) for entry in api] == [
        ("Client", "lazy_lib/lazy.py")
    ]


def test_python_lazy_getattr_uses_the_last_map_assignment(tmp_path):
    parsed = _index(
        tmp_path,
        {
            "pyproject.toml": '[project]\nname = "lazy-lib"\n',
            "lazy_lib/__init__.py": (
                "__all__ = ['extract']\n"
                "_LAZY = {'extract': '.first'}\n"
                "_LAZY = {'extract': '.second'}\n\n"
                "def __getattr__(name):\n"
                "    if name in _LAZY:\n"
                "        return getattr(importlib.import_module(_LAZY[name], __name__), name)\n"
                "    raise AttributeError(name)\n"
            ),
            "lazy_lib/first.py": "def extract():\n    pass\n",
            "lazy_lib/second.py": "def extract():\n    pass\n",
        },
    )

    api = compute_public_api(list(parsed), parsed, set())

    assert [(entry["name"], entry["file"]) for entry in api] == [
        ("extract", "lazy_lib/second.py")
    ]


def test_barrels_that_re_export_each_other_publish_everything_from_every_root(tmp_path):
    parsed = _index(
        tmp_path,
        {
            "one/index.ts": "export * from '../two';\nexport class One {}\n",
            "two/index.ts": "export * from '../one';\nexport class Two {}\n",
        },
    )
    resolver = _Resolver(parsed)
    for root in ("one/index.ts", "two/index.ts"):
        # The cycle cut short while walking the first root must not stick to the second.
        assert sorted(name for name, _, _ in resolver.exported(root)) == ["One", "Two"]