Skip to content

feat: add catalog inspection commands #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kingsword09 merged 1 commit into from
Jun 5, 2026
Merged

feat: add catalog inspection commands #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-stable-orange.svg)](https://www.rust-lang.org)

A fast, standalone CLI for managing Gradle version catalogs (`libs.versions.toml`): check, list, update, add, audit, and diagnose dependencies or plugins with confidence.
A fast, standalone CLI for managing Gradle version catalogs (`libs.versions.toml`): check, list, explain, update, add, audit, and diagnose dependencies or plugins with confidence.

English | [简体中文](README_ZH.md)

Expand All @@ -13,11 +13,12 @@ English | [简体中文](README_ZH.md)
- 🚀 **Direct Maven repository queries** - No Gradle runtime needed, pure Rust performance
- 📦 **Multi-repository support** - Maven Central, Google Maven, custom repositories with smart filtering
- 🎯 **Intelligent version detection** - Semantic versioning with stability filtering (alpha, beta, RC, dev)
- 📋 **Seven commands**:
- 📋 **Eight commands**:
- `check` - View available updates without applying
- `outdated` - Show outdated entries in a package-manager style table
- `update` - Apply dependency updates
- `list` - Display all dependencies in Maven coordinate format
- `why` - Explain a catalog entry by alias or coordinate
- `audit` - Find catalog quality issues such as duplicate coordinates or missing version refs
- `add` - Insert dependencies or plugins directly into the catalog with version aliasing
- `doctor` - Diagnose Kotlin/Android catalog consistency
Expand Down Expand Up @@ -71,6 +72,7 @@ cargo build --release
```bash
gvc check # validate project and list available upgrades
gvc outdated # show outdated catalog entries in a table
gvc why androidx-core # explain a catalog entry by alias or coordinate
gvc audit # inspect catalog quality without network access
gvc update --no-git # apply upgrades without creating a Git branch
gvc check --format json --fail-on-updates # agent/CI-friendly update gate
Expand All @@ -91,6 +93,7 @@ gvc doctor --format json --fail-on-issues # Kotlin/Android catalog diagnostics
| `gvc outdated` | Prints outdated version aliases, libraries, and plugins in a package-manager style table. | `--include-unstable` to include pre-releases; `--fail-on-updates` exits with code 2 for automation. |
| `gvc update` | Applies or previews catalog updates, honoring stability filters and optional Git integration. | `--dry-run` to preview; `--apply` to be explicit; `--target "*glob*"` for targeted upgrades; `--no-git` to skip branch/commit; `--no-stable-only` to include pre-releases. |
| `gvc list` | Displays the resolved version catalog as Maven coordinates for quick auditing. | `--path` to point at another project. |
| `gvc why <query>` | Explains a catalog entry's coordinate, version source, duplicate aliases, and recommendations. | Query by alias, library coordinate (`group:artifact`), or plugin id; `--format json` for automation. |
| `gvc audit` | Checks catalog maintainability without network access. | `--fail-on-issues` exits with code 2 when warnings/errors are found; `--format json` for automation. |
| `gvc doctor` | Checks Kotlin, KSP, Android Gradle Plugin, and Compose catalog consistency without network access. | `--fail-on-issues` exits with code 2 when warnings/errors are found; `--format json` for automation. |
| `gvc add` | Inserts a new entry into `[libraries]` (default) or `[plugins]`. | `-P/--plugin` targets plugins; `--no-stable-only` allows pre-releases when resolving `:latest`; `--alias` / `--version-alias` override generated keys. |
Expand Down Expand Up @@ -187,6 +190,18 @@ Summary:
2 plugins
```

### Explain a Catalog Entry

Use `why` to inspect how an alias or coordinate is declared and resolved:

```bash
gvc why androidx-core
gvc why androidx.core:core-ktx
gvc why com.android.application --format json
```

The report shows the matched entry, coordinate, inline version or `version.ref`, resolved version, duplicate aliases for the same coordinate, and any low-risk recommendations.

### Diagnose Kotlin/Android Catalogs

Run catalog-only diagnostics for Kotlin-heavy Gradle projects:
Expand Down
19 changes: 17 additions & 2 deletions README_ZH.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-stable-orange.svg)](https://www.rust-lang.org)

一个快速、独立的 CLI 工具，用于检查、列出、更新、新增、审计并诊断 Gradle 版本目录（`libs.versions.toml`）中的依赖与插件。
一个快速、独立的 CLI 工具，用于检查、列出、解释、更新、新增、审计并诊断 Gradle 版本目录（`libs.versions.toml`）中的依赖与插件。

[English](README.md) | 简体中文

Expand All @@ -13,11 +13,12 @@
- 🚀 **直接查询 Maven 仓库** - 无需 Gradle 运行时，纯 Rust 性能
- 📦 **多仓库支持** - Maven Central、Google Maven、自定义仓库，智能过滤
- 🎯 **智能版本检测** - 语义化版本控制，稳定性过滤（alpha、beta、RC、dev）
- 📋 **七个命令**：
- 📋 **八个命令**：
- `check` - 查看可用更新但不应用
- `outdated` - 以类似包管理器的表格展示过期条目
- `update` - 应用依赖更新
- `list` - 以 Maven 坐标格式显示所有依赖
- `why` - 按 alias 或坐标解释版本目录条目
- `audit` - 发现重复坐标、缺失版本引用等版本目录质量问题
- `add` - 直接向版本目录写入依赖或插件并自动管理版本别名
- `doctor` - 诊断 Kotlin/Android 版本目录一致性
Expand Down Expand Up @@ -71,6 +72,7 @@ cargo build --release
```bash
gvc check # 验证项目并列出可用更新
gvc outdated # 以表格展示过期的版本目录条目
gvc why androidx-core # 按 alias 或坐标解释版本目录条目
gvc audit # 离线检查版本目录质量
gvc update --no-git # 在不创建 Git 分支的情况下应用更新
gvc check --format json --fail-on-updates # 适合 agent/CI 的更新检查
Expand All @@ -91,6 +93,7 @@ gvc doctor --format json --fail-on-issues # Kotlin/Android 版本目录诊断
| `gvc outdated` | 以类似包管理器的表格展示过期的版本别名、库和插件。 | `--include-unstable` 包含预发布版本；`--fail-on-updates` 在自动化场景中以退出码 2 表示发现更新。 |
| `gvc update` | 预览或应用版本目录更新，支持稳定性过滤与 Git 集成。 | `--dry-run` 预览；`--apply` 明确应用；`--target "*glob*"` 定向升级；`--no-git` 跳过 Git；`--no-stable-only` 允许预发布版本。 |
| `gvc list` | 以 Maven 坐标格式展示版本目录中的所有条目。 | `--path` 指向其他项目。 |
| `gvc why <query>` | 解释某个条目的坐标、版本来源、重复 alias 和建议。 | 可用 alias、库坐标（`group:artifact`）或插件 ID 查询；`--format json` 适合自动化。 |
| `gvc audit` | 离线检查版本目录的可维护性。 | `--fail-on-issues` 在发现 warning/error 时以退出码 2 结束；`--format json` 适合自动化。 |
| `gvc doctor` | 离线检查 Kotlin、KSP、Android Gradle Plugin 与 Compose 的版本目录一致性。 | `--fail-on-issues` 在发现 warning/error 时以退出码 2 结束；`--format json` 适合自动化。 |
| `gvc add` | 默认向 `[libraries]` 插入新条目，也可写入 `[plugins]`。 | `-P/--plugin` 指定插件；`--no-stable-only` 解析 `:latest` 时允许预发布版本；`--alias` / `--version-alias` 自定义键名。 |
Expand Down Expand Up @@ -187,6 +190,18 @@ Summary:
2 plugins
```

### 解释版本目录条目

使用 `why` 查看某个 alias 或坐标是如何声明并解析的：

```bash
gvc why androidx-core
gvc why androidx.core:core-ktx
gvc why com.android.application --format json
```

报告会展示匹配到的条目、坐标、inline version 或 `version.ref`、解析后的版本、同一坐标的重复 alias，以及低风险建议。

### 诊断 Kotlin/Android 版本目录

对 Kotlin/Android 项目的版本目录运行离线诊断：
Expand Down
Loading
Loading