Stub Layout Reporter

Produce a summary of canonical stub and test directories for a distribution inside a typeshed-style repository. The summary must rely on the repository layout helper dependency so that standard library and third-party layouts follow the expected folder structure without manual path guessing.

Capabilities

Summarize stdlib layout

• For input distribution="stdlib" and repo root /typeshed, report stub /typeshed/stdlib, tests /typeshed/stdlib/@tests, test cases /typeshed/stdlib/@tests/test_cases, and allowlists /typeshed/stdlib/@tests/stubtest_allowlists. @test

Summarize third-party layout

• For input distribution="attrs" and repo root /typeshed, report stub /typeshed/stubs/attrs, tests /typeshed/stubs/attrs/@tests, test cases /typeshed/stubs/attrs/@tests/test_cases, and allowlists /typeshed/stubs/attrs/@tests. @test

Format layout summary

• Convert a layout summary into newline-delimited strings labeled stub, tests, test_cases, and allowlists, relative to the repo root by default or to an override base when provided. @test

Implementation

@generates

API

from dataclasses import dataclass
from pathlib import Path

@dataclass
class LayoutSummary:
    distribution: str
    stub_dir: Path
    tests_dir: Path
    test_cases_dir: Path
    allowlists_dir: Path

def describe_distribution_layout(distribution: str, repo_root: Path | str = Path(".")) -> LayoutSummary:
    """Return canonical stub/test locations for the distribution within the repo_root layout."""


def format_layout(summary: LayoutSummary, relative_to: Path | str | None = None) -> str:
    """Return newline-delimited entries like 'stub: <path>' for each layout path."""

Dependencies { .dependencies }

ts_utils { .dependency }

Canonical path helpers for stub distributions, tests, test cases, and allowlists.