Metadata-Version: 2.3
Name: vumper
Version: 2.2.1
Summary: A compact, fully‑dynamic tool to inspect or bump the semantic version of any project that follows the uv‑package layout
Author: Anthony Camilo
Author-email: Anthony Camilo <1643025+gargolito@users.noreply.github.com>
Requires-Dist: aqdlog>=2.1.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: shtab>=1.8.0
Requires-Dist: tomlkit>=0.14.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown

## vumper

A compact, configurable tool to inspect or bump semantic versions in uv-style
projects.

By default, vumper auto-detects version surfaces in:

```
    repo_root/
        ├─ pyproject.toml
        ├─ src/<project_name>/__init__.py
        └─ manifest.json
```

### Features:

* Automatic discovery of repo root and package name (no hard-coded feature names)
* Dynamic targets instead of fixed backend/frontend/custom components
* `all` applies get/set/bump across every non-overlapping detected target
* Output labels default to target labels, with optional single-target `--label` overrides
* Bump `major`, `minor`, or `patch`; or set an explicit version
* `--get` flag to display current version(s)
* `--discover` flag to automatically detect version targets and generate vumper.yaml
* After a successful bump, runs `uv lock` to keep the lockfile up‑to‑date
* Configurable target files from either:
  * `./vumper.yaml` (project-local)
  * `$HOME/.config/vumper.yaml` (global fallback)
* Robust error messages and clean code style (type hints, small helper
  functions, docstrings)

## Installation

`uv tool install vumper`

### Usage

#### Show versions

    # Show current default target version
    vumper default --get

    # Show default target with a custom display label
    vumper default --get --label api

    # Show all detected/configured non-overlapping target versions
    vumper all --get

#### Bump versions

    # Bump the default target (patch increment)
    vumper default

    # Bump a configured custom target
    vumper release patch

    # Bump a specific target to a specific version
    vumper docs --set 1.0.0

#### Set versions

    # Set all selected targets to an explicit version
    vumper all --set 2.3.0

#### Discover and generate configuration

    # Automatically detect version targets and generate vumper.yaml
    vumper --discover

This scans the project directory for files containing version variables (`__version__` or `version`) and generates a `vumper.yaml` configuration file with the discovered targets. The generated file includes a comment indicating it can be regenerated with `vumper --discover`.

### Configuration

Create `vumper.yaml` in either:

* **Project-local**: `./vumper.yaml` (higher precedence, overrides global)
* **Global fallback**: `$HOME/.config/vumper.yaml`

Both files support the same schema; local config merges with global config.

#### Target definition

Each target defines which files to update and how to read/write the version.

```yaml
targets:
  release:
    var: __version__    # Variable name in Python files (optional, default: __version__)
    files:
      - pyproject.toml
      - src/{package}/__init__.py
      - manifest.json
      - docs/version.txt
```

#### Project-specific overrides

Use `projects` to define per-project targets:

```yaml
projects:
  my-project:
    targets:
      docs:
        files:
          - docs/version.txt
```

When running in `my-project`, the `docs` target becomes available.

#### Auto-discovery

The `--discover` command scans the project directory for files containing version variables and generates a `vumper.yaml` configuration. It:

* Scans all `.py`, `.toml`, and `.json` files
* Looks for `__version__` or `version` variables with string values
* Groups files by their parent directory
* Excludes common directories like `.venv`, `venv`, `.git`, `__pycache__`, etc.
* Uses the first matching version variable name for each directory

Generated configuration can be reviewed and modified as needed.

#### Path placeholders in `files`

* `{package}` → detected project/package name from `pyproject.toml`
* `{project}` → repository root directory name

#### Example: global config (`$HOME/.config/vumper.yaml`)

```yaml
targets:
  release:
    label: release-version
    files:
      - pyproject.toml
      - src/{package}/__init__.py
```

#### Example: project-local config (`./vumper.yaml`)

```yaml
targets:
  docs:
    label: docs
    files:
      - docs/version.txt
  frontend:
    label: frontend
    files:
      - frontend/package.json
```

This project-local config adds `docs` and `frontend` targets to the default auto-detected target.

- - -
**What can vumper do?**

* **Dynamic repository detection** – locates nearest `pyproject.toml` and
  corresponding package name automatically.
* **Auto-detected default target** – uses detected `pyproject.toml`,
  `src/<pkg>/__init__.py`, and `manifest.json` version surfaces.
* **Auto-discovery** – `--discover` scans the project for version variables and
  generates `vumper.yaml` with detected targets.
* **Config-driven targets** – define any additional files to update via YAML.
  Supports both global (`$HOME/.config/vumper.yaml`) and project-local
  (`./vumper.yaml`) configs with merge semantics.
* **Whole-project actions** – `all` runs across selected non-overlapping targets,
  automatically de-duplicating overlapping file surfaces.
* **Project-aware labels** – output defaults to configured labels or sensible
  target names; `--label` can override for single-target operations.
* **Flexible file formats** – supports `pyproject.toml`, `__init__.py`,
  `manifest.json`, and arbitrary text files with version strings.
* **Optional **uv lock** sync** – executed after a successful bump, mirroring the
  original script's behavior.
* **Clear error messages** – explicit RuntimeError reports for missing files or
  invalid arguments.
* **Typings and docstrings** – improves readability and maintainability.
