py-lean-package 0.1.1__tar.gz

py_lean_package-0.1.1/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.3
+Name: py-lean-package
+Version: 0.1.1
+Summary: Detect and fix missing source-exclude patterns in Python projects.
+Author: Raphael Stolt
+Author-email: Raphael Stolt <raphael.stolt@gmail.com>
+License: MIT
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: tomlkit>=0.15.2
+Requires-Dist: typer>=0.27.3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# py-lean
+
+Detect and fix missing `source-exclude` patterns in Python projects built with `uv_build`.
+
+`py-lean` is a Python counterpart to [cargo-lean](https://github.com/raphaelstolt/cargo-lean). It checks the source-distribution configuration in
+`pyproject.toml` so repository-only files don't unnecessarily end up in published archives.
+
+## Why?
+
+A Python package's source repository often contains more than consumers need to install and use it. Tests, CI workflows,
+development configuration, and other repository-specific files can add unnecessary noise and size to source distributions.
+
+`py-lean` helps make distribution contents intentional by identifying common repository artefacts that are missing from
+`tool.uv.build-backend.source-exclude`. It can also add the missing patterns to `pyproject.toml`.
+
+Your working repository remains intact: `py-lean` configures what is excluded from the built source distribution; it does
+not delete those files from your project.
+
+## Features
+
+- __Lint__ — Detect common repository artefacts that are not listed in `source-exclude`.
+- __Create__ — Add a `source-exclude` configuration for detected artefacts.
+- __Update__ — Add missing exclusion patterns to an existing configuration.
+- __Preview changes__ — Use `--dry-run` and `--diff` to review proposed edits before applying them.
+- __Machine-readable output__ — Emit lint results as JSON.
+
+## Requirements
+
+- Python 3.11 or newer
+- [uv](https://github.com/astral-sh/uv) and a project using the `uv_build` build backend
+
+### Required build-system configuration
+
+`py-lean` manages `tool.uv.build-backend.source-exclude`, which is a `uv_build` configuration. The target project must
+therefore use `uv_build` as its build backend for this setting to apply.
+
+For example, the target project's `pyproject.toml` should include:
+
+```toml
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+```
+
+If the project uses a different build backend, `py-lean`'s `source-exclude` configuration will not control that backend's
+source-distribution contents.
+
+## Installation
+
+Install with `uv`:
+
+```bash
+uv tool install py-lean-package
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/raphaelstolt/py-lean.git
+cd py-lean
+uv sync
+uv run --project . py-lean --help
+```
+
+## Usage
+
+### Lint
+
+Check for missing patterns in `source-exclude`:
+
+```bash
+py-lean lint
+```
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `-m, --manifest-path <PATH>` | Path to `pyproject.toml` (default: `pyproject.toml`) |
+| `--format <text\|json>` | Output format (default: `text`) |
+| `-p, --patterns <PATTERN>` | Artefact patterns to check, such as `tests/` |
+| `--dry-run` | Show what would be done without making changes |
+| `--diff` | Show a diff of the proposed changes |
+
+Examples:
+
+```bash
+# Lint with JSON output
+py-lean lint --format json
+
+# Use a custom manifest path
+py-lean lint -m path/to/pyproject.toml
+
+# Check selected artefact patterns
+py-lean lint -p "tests/" -p "benchmarks/"
+```
+
+### Create
+
+Create a `tool.uv.build-backend.source-exclude` configuration containing common repository artefacts:
+
+```bash
+py-lean create
+```
+
+This scans the project for common artefacts, such as `tests/`, `docs/`, and `.git/`, and adds the detected patterns to
+`pyproject.toml`.
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Preview changes without modifying files |
+| `--diff` | Show a unified diff of the proposed changes |
+
+### Update
+
+Add missing patterns to an existing `source-exclude` configuration:
+
+```bash
+py-lean update
+```
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Preview changes without modifying files |
+| `--diff` | Show a unified diff of the proposed changes |
+
+Examples:
+
+```bash
+# Preview changes
+py-lean update --dry-run --diff
+
+# Apply changes
+py-lean update
+```
+
+## Configuration
+
+### Pattern precedence
+
+`py-lean` determines which artefact patterns to check using the following precedence:
+
+1. __CLI `--patterns`__ — highest priority; replaces other pattern sources.
+2. __`tool.uv.build-backend.source-exclude`__ in `pyproject.toml` — patterns already configured for the build backend.
+3. __Built-in defaults__ — used when neither of the above is configured.
+
+Use `--patterns` to override the default patterns:
+
+```bash
+py-lean lint -p "tests/" -p "benchmarks/"
+```
+
+By default, `py-lean` checks a built-in set of common repository artefacts.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development instructions.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE.md](LICENSE.md) for details.
+
+## Related projects
+
+- [lean-package-validator](https://github.com/raphaelstolt/lean-package-validator) — The `PHP` equivalent
+- [cargo-lean](https://github.com/raphaelstolt/cargo-lean) — The `Rust` equivalent.

py_lean_package-0.1.1/README.md

@@ -0,0 +1,170 @@
+# py-lean
+
+Detect and fix missing `source-exclude` patterns in Python projects built with `uv_build`.
+
+`py-lean` is a Python counterpart to [cargo-lean](https://github.com/raphaelstolt/cargo-lean). It checks the source-distribution configuration in
+`pyproject.toml` so repository-only files don't unnecessarily end up in published archives.
+
+## Why?
+
+A Python package's source repository often contains more than consumers need to install and use it. Tests, CI workflows,
+development configuration, and other repository-specific files can add unnecessary noise and size to source distributions.
+
+`py-lean` helps make distribution contents intentional by identifying common repository artefacts that are missing from
+`tool.uv.build-backend.source-exclude`. It can also add the missing patterns to `pyproject.toml`.
+
+Your working repository remains intact: `py-lean` configures what is excluded from the built source distribution; it does
+not delete those files from your project.
+
+## Features
+
+- __Lint__ — Detect common repository artefacts that are not listed in `source-exclude`.
+- __Create__ — Add a `source-exclude` configuration for detected artefacts.
+- __Update__ — Add missing exclusion patterns to an existing configuration.
+- __Preview changes__ — Use `--dry-run` and `--diff` to review proposed edits before applying them.
+- __Machine-readable output__ — Emit lint results as JSON.
+
+## Requirements
+
+- Python 3.11 or newer
+- [uv](https://github.com/astral-sh/uv) and a project using the `uv_build` build backend
+
+### Required build-system configuration
+
+`py-lean` manages `tool.uv.build-backend.source-exclude`, which is a `uv_build` configuration. The target project must
+therefore use `uv_build` as its build backend for this setting to apply.
+
+For example, the target project's `pyproject.toml` should include:
+
+```toml
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+```
+
+If the project uses a different build backend, `py-lean`'s `source-exclude` configuration will not control that backend's
+source-distribution contents.
+
+## Installation
+
+Install with `uv`:
+
+```bash
+uv tool install py-lean-package
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/raphaelstolt/py-lean.git
+cd py-lean
+uv sync
+uv run --project . py-lean --help
+```
+
+## Usage
+
+### Lint
+
+Check for missing patterns in `source-exclude`:
+
+```bash
+py-lean lint
+```
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `-m, --manifest-path <PATH>` | Path to `pyproject.toml` (default: `pyproject.toml`) |
+| `--format <text\|json>` | Output format (default: `text`) |
+| `-p, --patterns <PATTERN>` | Artefact patterns to check, such as `tests/` |
+| `--dry-run` | Show what would be done without making changes |
+| `--diff` | Show a diff of the proposed changes |
+
+Examples:
+
+```bash
+# Lint with JSON output
+py-lean lint --format json
+
+# Use a custom manifest path
+py-lean lint -m path/to/pyproject.toml
+
+# Check selected artefact patterns
+py-lean lint -p "tests/" -p "benchmarks/"
+```
+
+### Create
+
+Create a `tool.uv.build-backend.source-exclude` configuration containing common repository artefacts:
+
+```bash
+py-lean create
+```
+
+This scans the project for common artefacts, such as `tests/`, `docs/`, and `.git/`, and adds the detected patterns to
+`pyproject.toml`.
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Preview changes without modifying files |
+| `--diff` | Show a unified diff of the proposed changes |
+
+### Update
+
+Add missing patterns to an existing `source-exclude` configuration:
+
+```bash
+py-lean update
+```
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Preview changes without modifying files |
+| `--diff` | Show a unified diff of the proposed changes |
+
+Examples:
+
+```bash
+# Preview changes
+py-lean update --dry-run --diff
+
+# Apply changes
+py-lean update
+```
+
+## Configuration
+
+### Pattern precedence
+
+`py-lean` determines which artefact patterns to check using the following precedence:
+
+1. __CLI `--patterns`__ — highest priority; replaces other pattern sources.
+2. __`tool.uv.build-backend.source-exclude`__ in `pyproject.toml` — patterns already configured for the build backend.
+3. __Built-in defaults__ — used when neither of the above is configured.
+
+Use `--patterns` to override the default patterns:
+
+```bash
+py-lean lint -p "tests/" -p "benchmarks/"
+```
+
+By default, `py-lean` checks a built-in set of common repository artefacts.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development instructions.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE.md](LICENSE.md) for details.
+
+## Related projects
+
+- [lean-package-validator](https://github.com/raphaelstolt/lean-package-validator) — The `PHP` equivalent
+- [cargo-lean](https://github.com/raphaelstolt/cargo-lean) — The `Rust` equivalent.

py_lean_package-0.1.1/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[project]
+name = "py-lean-package"
+version = "0.1.1"
+description = "Detect and fix missing source-exclude patterns in Python projects."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.14.1",
+    "tomlkit>=0.15.2",
+    "typer>=0.27.3",
+]
+
+[project.license]
+text = "MIT"
+
+[[project.authors]]
+name = "Raphael Stolt"
+email = "raphael.stolt@gmail.com"
+
+[project.scripts]
+py-lean = "py_lean_package.cli:app"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.170.13",
+    "pytest>=9.2.0",
+    "ruff>=0.17.3",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "N",
+    "W",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+]
+ignore = ["B008"]
+
+[tool.uv.build-backend]
+source-exclude = [
+    ".github/**",
+    "tests/**",
+    ".gitignore",
+    "CHANGELOG.md",
+    "RELEASE.md",
+    "CONTRIBUTING.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

py_lean_package-0.1.1/pyproject.toml.orig

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[project]
+name = "py-lean-package"
+version = "0.1.1"
+description = "Detect and fix missing source-exclude patterns in Python projects."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [
+    {name = "Raphael Stolt", email = "raphael.stolt@gmail.com"},
+]
+dependencies = [
+    "pydantic>=2.14.1",
+    "tomlkit>=0.15.2",
+    "typer>=0.27.3",
+]
+
+[project.scripts]
+py-lean = "py_lean_package.cli:app"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.170.13",
+    "pytest>=9.2.0",
+    "ruff>=0.17.3",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "RUF"]
+ignore = ["B008"]
+
+[tool.uv.build-backend]
+source-exclude = [
+    ".github/**",
+    "tests/**",
+    ".gitignore",
+    "CHANGELOG.md",
+    "RELEASE.md",
+    "CONTRIBUTING.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

py_lean_package-0.1.1/src/py_lean_package/__init__.py

@@ -0,0 +1,5 @@
+"""py-lean: Detect and fix missing source-exclude patterns in Python projects."""
+
+from __future__ import annotations
+
+__version__ = "0.1.1"

py_lean_package-0.1.1/src/py_lean_package/analyzer.py

@@ -0,0 +1,279 @@
+"""Core analysis logic for py-lean."""
+
+from __future__ import annotations
+
+import fnmatch
+import subprocess
+from pathlib import Path
+
+import tomlkit
+
+from py_lean_package.models import AnalysisResult, Issue, IssueType, LeanConfig
+
+
+def read_gitignore(project_root: Path) -> list[str]:
+    """Parse a local `.gitignore` file and return normalized ignore patterns.
+
+    Returns an empty list if the file does not exist or cannot be read.
+    Skips blank lines, comments (lines starting with `#`), and negation patterns (starting with `!`).
+    Normalizes patterns by stripping leading `/` (which anchors to the repo root) and trailing `/`
+    (which indicates a directory-only match).
+    """
+    gitignore_path = project_root / ".gitignore"
+    try:
+        content = gitignore_path.read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError):
+        return []
+
+    patterns: list[str] = []
+    for line in content.splitlines():
+        line = line.strip()
+        # Skip empty lines, comments, and negation patterns
+        if not line or line.startswith("#") or line.startswith("!"):
+            continue
+        # Normalize: strip leading `/` (root anchor) and trailing `/` (directory indicator)
+        line = line.removeprefix("/").removesuffix("/")
+        if line:
+            patterns.append(line)
+    return patterns
+
+
+def read_global_gitignore() -> list[str]:
+    """Read the global gitignore file configured via `core.excludesFile`.
+
+    Returns an empty list if the config is not set or the file cannot be read.
+    Uses the same normalization as `read_gitignore`.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "config", "--get", "core.excludesFile"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            return []
+        excludes_file = result.stdout.strip()
+        if not excludes_file:
+            return []
+
+        content = Path(excludes_file).expanduser().read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
+        return []
+
+    patterns: list[str] = []
+    for line in content.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or line.startswith("!"):
+            continue
+        line = line.removeprefix("/").removesuffix("/")
+        if line:
+            patterns.append(line)
+    return patterns
+
+
+def is_gitignored(pattern: str, gitignore_entries: list[str]) -> bool:
+    """Check if a pattern is already covered by a .gitignore entry.
+
+    Uses simple string matching and basic glob matching.
+    """
+    pattern = pattern.rstrip("/")
+    for entry in gitignore_entries:
+        # Direct match
+        if entry == pattern:
+            return True
+        # Glob-like match
+        if fnmatch.fnmatch(pattern, entry):
+            return True
+    return False
+
+
+def load_manifest(manifest_path: Path) -> tomlkit.TOMLDocument:
+    """Load and parse a pyproject.toml file."""
+    if not manifest_path.exists():
+        raise FileNotFoundError(f"Manifest not found: {manifest_path}")
+    content = manifest_path.read_text(encoding="utf-8")
+    return tomlkit.parse(content)
+
+
+def check_build_system(manifest: tomlkit.TOMLDocument) -> bool:
+    """Verify the project uses uv_build as its build backend.
+
+    Checks for [build-system] with `requires` containing `uv_build` and
+    `build-backend` set to `uv_build.build`.
+
+    Returns:
+        True if the build system is correctly configured for uv_build.
+    """
+    build_system = manifest.get("build-system", {}) or {}
+    requires = build_system.get("requires", []) or []
+    backend = build_system.get("build-backend", "")
+
+    has_uv_build_requires = any("uv_build" in str(r) for r in requires)
+    has_uv_build_backend = str(backend) == "uv_build.build"
+
+    return has_uv_build_requires and has_uv_build_backend
+
+
+def load_config(
+    manifest: tomlkit.TOMLDocument | None = None,
+    patterns: list[str] | None = None,
+) -> LeanConfig:
+    """Load py-lean configuration with the following precedence:
+
+    1. CLI --patterns (highest priority — completely replaces other sources)
+    2. tool.uv.build-backend.source-exclude from pyproject.toml
+    3. DEFAULT_SOURCE_EXCLUDE_PATTERNS (lowest priority — used when nothing is configured)
+
+    Args:
+        manifest: Parsed pyproject.toml document to read source-exclude from.
+        patterns: CLI-provided patterns that override all other sources.
+
+    Returns:
+        LeanConfig with patterns set according to the precedence rules above.
+    """
+    config = LeanConfig()
+
+    # If CLI patterns are provided, they take full precedence
+    if patterns is not None:
+        config.patterns = patterns
+        return config
+
+    # Otherwise, try to load from tool.uv.build-backend.source-exclude
+    if manifest is not None:
+        source_exclude = _get_source_exclude_patterns(manifest)
+        if source_exclude:
+            config.patterns = source_exclude
+
+    # If neither CLI nor source-exclude provides patterns, effective_patterns()
+    # will fall back to DEFAULT_SOURCE_EXCLUDE_PATTERNS
+    return config
+
+
+def _get_source_exclude_patterns(manifest: tomlkit.TOMLDocument) -> list[str]:
+    """Extract source-exclude patterns from tool.uv.build-backend.source-exclude."""
+    patterns: list[str] = []
+    tool = manifest.get("tool", {})
+    if tool is None:
+        return patterns
+    uv = tool.get("uv", {})
+    if uv is None:
+        return patterns
+    build_backend = uv.get("build-backend", {})
+    if build_backend is None:
+        return patterns
+    source_exclude = build_backend.get("source-exclude", [])
+    if source_exclude is not None:
+        patterns = [str(p) for p in source_exclude]
+    return patterns
+
+
+def _pattern_covers(pattern: str, exclude_pattern: str) -> bool:
+    """Check if a source-exclude pattern covers a given artifact pattern.
+
+    Both patterns are treated as glob patterns. The exclude_pattern must match
+    the artifact pattern or be a parent directory of it.
+    """
+    # Direct match
+    if fnmatch.fnmatch(pattern, exclude_pattern):
+        return True
+
+    # Check if the exclude pattern is a parent directory
+    # e.g., exclude "tests" covers "tests/**"
+    if pattern.startswith(exclude_pattern + "/"):
+        return True
+
+    # Check if the pattern's top-level component matches
+    pattern_top = pattern.split("/")[0]
+    exclude_top = exclude_pattern.split("/")[0]
+    return bool(fnmatch.fnmatch(pattern_top, exclude_top))
+
+
+def detect_missing_source_exclude(
+    manifest: tomlkit.TOMLDocument,
+    project_root: Path,
+    config: LeanConfig,
+    gitignore_entries: list[str] | None = None,
+) -> list[Issue]:
+    """Detect common repository artefacts that exist but are not in source-exclude.
+
+    Checks if artefacts listed in the config's patterns (or defaults) exist in the
+    project root but are not covered by tool.uv.build-backend.source-exclude.
+    Artefacts already covered by .gitignore entries are skipped.
+    """
+    if gitignore_entries is None:
+        gitignore_entries = []
+
+    issues: list[Issue] = []
+    exclude_patterns = _get_source_exclude_patterns(manifest)
+    patterns_to_check = config.effective_patterns()
+
+    for pattern in patterns_to_check:
+        # Check if this pattern exists in the project root
+        if not _artifact_exists(project_root, pattern):
+            continue
+
+        # Skip if already covered by .gitignore
+        if is_gitignored(pattern, gitignore_entries):
+            continue
+
+        # Check if it's covered by any source-exclude pattern
+        covered = any(_pattern_covers(pattern, ep) for ep in exclude_patterns)
+        if not covered:
+            issues.append(
+                Issue(
+                    issue_type=IssueType.MISSING_SOURCE_EXCLUDE,
+                    subject=pattern,
+                    description=(
+                        f"Artefact '{pattern}' exists in the project root but is not listed in "
+                        f"tool.uv.build-backend.source-exclude."
+                    ),
+                    location="pyproject.toml",
+                    suggestion=f"Add '{pattern}' to tool.uv.build-backend.source-exclude.",
+                )
+            )
+
+    return issues
+
+
+def _artifact_exists(project_root: Path, pattern: str) -> bool:
+    """Check if an artifact matching the pattern exists in the project root."""
+    # Handle glob patterns like *.egg-info, *.pyc, *.pyo
+    if "*" in pattern:
+        matches = list(project_root.glob(pattern))
+        return len(matches) > 0
+
+    # Handle directory/file patterns
+    path = project_root / pattern
+    return path.exists()
+
+
+def analyze(
+    manifest_path: Path,
+    patterns: list[str] | None = None,
+) -> AnalysisResult:
+    """Run full analysis on a project.
+
+    Checks for missing source-exclude patterns for common repository artefacts.
+    Artefacts already covered by .gitignore (local or global) are skipped.
+
+    Args:
+        manifest_path: Path to the pyproject.toml file.
+        patterns: Optional list of artefact patterns to check for source-exclude.
+
+    Returns:
+        AnalysisResult containing all detected issues.
+    """
+    project_root = manifest_path.parent
+    manifest = load_manifest(manifest_path)
+    config = load_config(manifest=manifest, patterns=patterns)
+
+    # Collect gitignore entries from local .gitignore and global excludesFile
+    gitignore_entries: list[str] = []
+    gitignore_entries.extend(read_gitignore(project_root))
+    gitignore_entries.extend(read_global_gitignore())
+
+    issues: list[Issue] = []
+    issues.extend(detect_missing_source_exclude(manifest, project_root, config, gitignore_entries))
+
+    return AnalysisResult(manifest_path=manifest_path, issues=issues)

py_lean_package-0.1.1/src/py_lean_package/cli.py

@@ -0,0 +1,358 @@
+"""CLI entry point for py-lean."""
+
+from __future__ import annotations
+
+import json
+from difflib import unified_diff
+from pathlib import Path
+
+import tomlkit
+import typer
+
+from py_lean_package import __version__
+from py_lean_package.analyzer import _get_source_exclude_patterns, analyze, check_build_system, load_manifest
+from py_lean_package.models import DEFAULT_SOURCE_EXCLUDE_PATTERNS, IssueType, OutputFormat
+
+app = typer.Typer(
+    name="py-lean",
+    help="Detect and fix missing source-exclude patterns in Python projects.",
+    add_completion=False,
+)
+
+
+# Common options
+def manifest_path_callback(ctx: typer.Context, value: str) -> Path:
+    """Validate and resolve the manifest path."""
+    path = Path(value)
+    if not path.exists():
+        raise typer.Exit(1)
+    return path.resolve()
+
+
+#
+# Commands
+#
+
+
+@app.command("lint")
+def cmd_lint(
+    manifest_path: Path = typer.Option(
+        "pyproject.toml",
+        "-m",
+        "--manifest-path",
+        callback=manifest_path_callback,
+        help="Path to the pyproject.toml file.",
+    ),
+    format: OutputFormat = typer.Option(
+        OutputFormat.TEXT,
+        "--format",
+        help="Output format: text or json.",
+    ),
+    patterns: list[str] | None = typer.Option(
+        None,
+        "-p",
+        "--patterns",
+        help="Artefact patterns to check for source-exclude (e.g., tests).",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show what would be done without making changes.",
+    ),
+    diff: bool = typer.Option(
+        False,
+        "--diff",
+        help="Show a diff of the changes that would be made.",
+    ),
+) -> None:
+    """Analyze a project for missing source-exclude patterns."""
+    manifest = load_manifest(manifest_path)
+    if not check_build_system(manifest):
+        typer.echo(
+            "Error: This project is not configured with uv_build as its build backend.\n\n"
+            "py-lean requires the following in pyproject.toml:\n\n"
+            "  [build-system]\n"
+            '  requires = ["uv_build"]\n'
+            '  build-backend = "uv_build.build"',
+            err=True,
+        )
+        raise typer.Exit(1)
+    result = analyze(manifest_path, patterns)
+
+    if format == OutputFormat.JSON:
+        typer.echo(json.dumps(result.to_dict(), indent=2))
+    else:
+        if result.is_clean:
+            typer.echo("✓ No issues found.")
+        else:
+            _print_issues(result.issues)
+            typer.echo(f"\nFound {len(result.issues)} issue(s).", err=True)
+            raise typer.Exit(1)
+
+    if dry_run:
+        typer.echo("(dry-run: no changes made)")
+    if diff:
+        _show_diff(manifest_path, result.issues)
+
+
+@app.command("create")
+def cmd_create(
+    manifest_path: Path = typer.Option(
+        "pyproject.toml",
+        "-m",
+        "--manifest-path",
+        callback=manifest_path_callback,
+        help="Path to the pyproject.toml file.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show what would be done without making changes.",
+    ),
+    diff: bool = typer.Option(
+        False,
+        "--diff",
+        help="Show a diff of the changes that would be made.",
+    ),
+) -> None:
+    """Add source-exclude patterns for repository artefacts to tool.uv.build-backend in pyproject.toml.
+
+    Merges configured patterns with built-in defaults and validates against the Git repository.
+    Only adds patterns for artefacts that actually exist in the project.
+    """
+    manifest = load_manifest(manifest_path)
+    if not check_build_system(manifest):
+        typer.echo(
+            "Error: This project is not configured with uv_build as its build backend.\n\n"
+            "py-lean requires the following in pyproject.toml:\n\n"
+            "  [build-system]\n"
+            '  requires = ["uv_build"]\n'
+            '  build-backend = "uv_build.build"',
+            err=True,
+        )
+        raise typer.Exit(1)
+    # Merge configured patterns with built-in defaults
+    manifest = tomlkit.parse(manifest_path.read_text(encoding="utf-8"))
+    current_excludes = _get_source_exclude_patterns(manifest)
+    merged_patterns = list(current_excludes)
+    for pattern in DEFAULT_SOURCE_EXCLUDE_PATTERNS:
+        if pattern not in merged_patterns:
+            merged_patterns.append(pattern)
+
+    # Analyze with merged patterns to find which artefacts exist in the repo
+    result = analyze(manifest_path, merged_patterns)
+
+    if result.is_clean:
+        typer.echo("✓ No missing source-exclude patterns to add.")
+        return
+
+    original_content = manifest_path.read_text(encoding="utf-8")
+    manifest = tomlkit.parse(original_content)
+
+    # Ensure tool.uv.build-backend section exists
+    if "tool" not in manifest:
+        manifest["tool"] = {}
+    if "uv" not in manifest["tool"]:
+        manifest["tool"]["uv"] = {}
+    if "build-backend" not in manifest["tool"]["uv"]:
+        manifest["tool"]["uv"]["build-backend"] = {}
+
+    bb = manifest["tool"]["uv"]["build-backend"]
+    current = list(bb.get("source-exclude", []))
+
+    # Add only the missing patterns that exist in the repo
+    added = 0
+    for issue in result.issues:
+        if issue.issue_type == IssueType.MISSING_SOURCE_EXCLUDE:
+            pattern = issue.subject
+            if pattern not in current:
+                current.append(pattern)
+                added += 1
+
+    bb["source-exclude"] = current
+    new_content = tomlkit.dumps(manifest)
+
+    if dry_run or diff:
+        if diff:
+            _print_diff(original_content, new_content, str(manifest_path))
+        if dry_run:
+            typer.echo("(dry-run: no changes made)")
+        return
+
+    manifest_path.write_text(new_content, encoding="utf-8")
+    typer.echo(f"Added {added} source-exclude pattern(s) to {manifest_path}")
+
+
+@app.command("update")
+def cmd_update(
+    manifest_path: Path = typer.Option(
+        "pyproject.toml",
+        "-m",
+        "--manifest-path",
+        callback=manifest_path_callback,
+        help="Path to the pyproject.toml file.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show what would be done without making changes.",
+    ),
+    diff: bool = typer.Option(
+        False,
+        "--diff",
+        help="Show a diff of the changes that would be made.",
+    ),
+) -> None:
+    """Merge configured patterns with built-in defaults and update source-exclude in pyproject.toml.
+
+    Validates against the Git repository — only adds patterns for artefacts that actually exist.
+    """
+    manifest = load_manifest(manifest_path)
+    if not check_build_system(manifest):
+        typer.echo(
+            "Error: This project is not configured with uv_build as its build backend.\n\n"
+            "py-lean requires the following in pyproject.toml:\n\n"
+            "  [build-system]\n"
+            '  requires = ["uv_build"]\n'
+            '  build-backend = "uv_build.build"',
+            err=True,
+        )
+        raise typer.Exit(1)
+    # Merge configured patterns with built-in defaults
+    manifest = tomlkit.parse(manifest_path.read_text(encoding="utf-8"))
+    current_excludes = _get_source_exclude_patterns(manifest)
+    merged_patterns = list(current_excludes)
+    for pattern in DEFAULT_SOURCE_EXCLUDE_PATTERNS:
+        if pattern not in merged_patterns:
+            merged_patterns.append(pattern)
+
+    # Analyze with merged patterns to find which artefacts exist in the repo
+    result = analyze(manifest_path, merged_patterns)
+
+    if result.is_clean:
+        typer.echo("✓ No missing source-exclude patterns to add.")
+        return
+
+    original_content = manifest_path.read_text(encoding="utf-8")
+    manifest = tomlkit.parse(original_content)
+
+    # Ensure tool.uv.build-backend section exists
+    if "tool" not in manifest:
+        manifest["tool"] = {}
+    if "uv" not in manifest["tool"]:
+        manifest["tool"]["uv"] = {}
+    if "build-backend" not in manifest["tool"]["uv"]:
+        manifest["tool"]["uv"]["build-backend"] = {}
+
+    bb = manifest["tool"]["uv"]["build-backend"]
+    current = list(bb.get("source-exclude", []))
+
+    # Add only the missing patterns that exist in the repo
+    added = 0
+    for issue in result.issues:
+        if issue.issue_type == IssueType.MISSING_SOURCE_EXCLUDE:
+            pattern = issue.subject
+            if pattern not in current:
+                current.append(pattern)
+                added += 1
+
+    bb["source-exclude"] = current
+    new_content = tomlkit.dumps(manifest)
+
+    if dry_run or diff:
+        if diff:
+            _print_diff(original_content, new_content, str(manifest_path))
+        if dry_run:
+            typer.echo("(dry-run: no changes made)")
+        return
+
+    manifest_path.write_text(new_content, encoding="utf-8")
+    typer.echo(f"Added {added} source-exclude pattern(s) to {manifest_path}")
+
+
+#
+# Helpers
+#
+
+
+def _print_issues(issues: list) -> None:
+    """Print issues in a human-readable format."""
+    for issue in issues:
+        icon = _issue_icon(issue.issue_type)
+        typer.echo(f"{icon} {issue.subject}")
+        typer.echo(f"   {issue.description}")
+        if issue.suggestion:
+            typer.echo(f"   → {issue.suggestion}")
+        typer.echo()
+
+
+def _issue_icon(issue_type: IssueType) -> str:
+    """Get a display icon for an issue type."""
+    icons = {
+        IssueType.MISSING_SOURCE_EXCLUDE: "✕",
+    }
+    return icons.get(issue_type, "?")
+
+
+def _print_diff(old: str, new: str, path: str) -> None:
+    """Print a unified diff between old and new content."""
+    old_lines = old.splitlines(keepends=True)
+    new_lines = new.splitlines(keepends=True)
+
+    diff_lines = unified_diff(old_lines, new_lines, fromfile=f"a/{path}", tofile=f"b/{path}")
+    for line in diff_lines:
+        typer.echo(line, nl=False)
+
+
+def _show_diff(manifest_path: Path, issues: list) -> None:
+    """Show what changes would be made to fix the issues."""
+    original_content = manifest_path.read_text(encoding="utf-8")
+    manifest = tomlkit.parse(original_content)
+
+    # Handle missing source-exclude
+    missing_excludes = [i for i in issues if i.issue_type == IssueType.MISSING_SOURCE_EXCLUDE]
+    if missing_excludes:
+        if "tool" not in manifest:
+            manifest["tool"] = {}
+        if "uv" not in manifest["tool"]:
+            manifest["tool"]["uv"] = {}
+        if "build-backend" not in manifest["tool"]["uv"]:
+            manifest["tool"]["uv"]["build-backend"] = {}
+
+        bb = manifest["tool"]["uv"]["build-backend"]
+        current_excludes = list(bb.get("source-exclude", []))
+        for issue in missing_excludes:
+            if issue.subject not in current_excludes:
+                current_excludes.append(issue.subject)
+        if current_excludes:
+            bb["source-exclude"] = current_excludes
+
+    new_content = tomlkit.dumps(manifest)
+    if new_content != original_content:
+        _print_diff(original_content, new_content, str(manifest_path))
+
+
+def version_callback(value: bool) -> None:
+    """Print the version and exit."""
+    if value:
+        typer.echo(f"py-lean {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """py-lean: Detect and fix missing source-exclude patterns in Python projects."""
+    pass
+
+
+if __name__ == "__main__":
+    app()

py_lean_package-0.1.1/src/py_lean_package/models.py

@@ -0,0 +1,110 @@
+"""Data models for py-lean."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+
+
+class IssueType(StrEnum):
+    """Types of issues that py-lean can detect."""
+
+    MISSING_SOURCE_EXCLUDE = "missing_source_exclude"
+
+
+class OutputFormat(StrEnum):
+    """Output format for py-lean results."""
+
+    TEXT = "text"
+    JSON = "json"
+
+
+@dataclass
+class Issue:
+    """A single issue detected by py-lean."""
+
+    issue_type: IssueType
+    subject: str
+    description: str
+    location: str | None = None
+    suggestion: str | None = None
+
+    def to_dict(self) -> dict:
+        """Convert the issue to a dictionary for JSON serialization."""
+        result: dict = {
+            "type": self.issue_type.value,
+            "subject": self.subject,
+            "description": self.description,
+        }
+        if self.location:
+            result["location"] = self.location
+        if self.suggestion:
+            result["suggestion"] = self.suggestion
+        return result
+
+
+@dataclass
+class AnalysisResult:
+    """Result of analyzing a project."""
+
+    manifest_path: Path
+    issues: list[Issue] = field(default_factory=list)
+
+    @property
+    def is_clean(self) -> bool:
+        """Return True if no issues were found."""
+        return len(self.issues) == 0
+
+    def to_dict(self) -> dict:
+        """Convert the result to a dictionary for JSON serialization."""
+        return {
+            "manifest_path": str(self.manifest_path),
+            "issues": [issue.to_dict() for issue in self.issues],
+        }
+
+
+# Default artifact patterns that should typically be excluded from builds.
+# These are common repository artefacts that should not end up in wheels or sdists.
+DEFAULT_SOURCE_EXCLUDE_PATTERNS: list[str] = [
+    "tests",
+    "docs",
+    ".venv",
+    "__pycache__",
+    "*.egg-info",
+    ".tox",
+    ".mypy_cache",
+    ".pytest_cache",
+    "dist",
+    "build",
+    ".github",
+    ".idea",
+    ".vscode",
+    ".vs",
+    ".DS_Store",
+    "*.pyc",
+    "*.pyo",
+    ".coverage",
+    "htmlcov",
+    ".ruff_cache",
+]
+
+
+@dataclass
+class LeanConfig:
+    """Configuration for py-lean.
+
+    Patterns are determined by the following precedence:
+    1. CLI --patterns (highest priority)
+    2. tool.uv.build-backend.source-exclude from pyproject.toml
+    3. Built-in defaults (DEFAULT_SOURCE_EXCLUDE_PATTERNS)
+    """
+
+    # Source exclude patterns to check for (defaults to DEFAULT_SOURCE_EXCLUDE_PATTERNS)
+    patterns: list[str] = field(default_factory=list)
+
+    def effective_patterns(self) -> list[str]:
+        """Return the patterns to use, falling back to defaults if none configured."""
+        if self.patterns:
+            return self.patterns
+        return list(DEFAULT_SOURCE_EXCLUDE_PATTERNS)