qtcloud-devops-cli 0.1.0__tar.gz → 0.2.0__tar.gz

qtcloud_devops_cli-0.2.0/.gitignore

@@ -0,0 +1,90 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+*.manifest
+*.spec
+pip-log.txt
+pip-delete-this-directory.txt
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+*.mo
+*.pot
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+instance/
+.webassets-cache
+.scrapy
+docs/_build/
+.pybuilder/
+target/
+.ipynb_checkpoints
+profile_default/
+ipython_config.py
+.python-version
+poetry.lock
+.pdm.toml
+.pdm-python
+.pdm-build
+__pypackages__/
+celerybeat-schedule
+celerybeat.pid
+*.sage.py
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.spyderproject
+.spyproject
+.ropeproject
+/site
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+cython_debug/
+.idea/
+pdm.lock
+
+# Editor / OS
+*~
+*.swp
+*.swo
+.DS_Store
+*.iml
+.vscode/

qtcloud_devops_cli-0.2.0/AGENTS.md

@@ -0,0 +1,165 @@
+# AGENTS
+
+## ROADMAP
+
+- 只记录**未完成**的事项，已完成的及时删除
+- 按 P0-P3 优先级分组
+- 基本假设放在末尾，不随版本迭代删除
+- 新增需求先定优先级再放入对应分组
+
+## 开发规范
+
+### 单元测试覆盖率（红线 95%，黄线 98%）
+
+所有公开发布的公共函数和模块必须达到一定的单元测试行覆盖率。
+
+| 级别 | 阈值 | 含义 |
+|------|------|------|
+| 红线 | 95% | CI 拦截线，低于此值构建失败 |
+| 黄线 | 98% | 目标值，低于此值应补充测试 |
+
+命令：
+
+```sh
+# Python（红线 95%）
+uv run pytest --cov=app/python --cov-report=term-missing --cov-fail-under=95
+
+# Rust（黄线 98%，仅报告不失败）
+cargo llvm-cov --html --output-dir target/coverage
+```
+
+**例外**（不纳入覆盖率统计）：
+- `__init__.py`（空文件）
+- 纯类型定义（`pydantic` Settings 等，无业务逻辑的 `__init__.py`）
+- CI 配置、入口脚本
+
+集成测试（`integrated_tests/`）不要求覆盖率，但单元测试（`tests/`）必须达标。
+
+### 糟糕单元测试示例（禁止）
+
+以下类型测试不会增加质量，只是徒增维护成本，AI 禁止生成：
+
+**1. 测类型**
+
+```python
+# ❌ pydantic Settings 类型在导入时已校验，运行时测试无意义
+def test_settings_is_basemodel():
+    assert isinstance(settings, BaseSettings)
+```
+
+**2. 测恒真条件**
+
+```python
+# ❌ assert True 是凑行数
+def test_version_string_not_empty():
+    assert __version__ != ""
+```
+
+**3. 测框架行为**
+
+```python
+# ❌ clap/typer 的参数解析不需要你来测
+def test_help_exits_with_zero():
+    """这是集成测试的工作，不是单元测试的"""
+```
+
+**4. 用 mock 模拟简单计算**
+
+```python
+# ❌ mock 了所有输入和输出，实际测的是 mock 本身
+mock_return = {"name": "test", "status": "Clean"}
+monkeypatch.setattr("app.code.rust_call", lambda _: mock_return)
+result = status(".")
+assert result == mock_return  # 永远通过
+```
+
+**5. 测内部实现而非公开行为**
+
+```python
+# ❌ 测私有函数的调用次数，重构时必碎
+def test_sync_calls_internal():
+    spy = mocker.spy(editor, "_do_sync")
+    editor.sync_to_parent("lib")
+    assert spy.called_once
+```
+
+**原则**：单元测试只测公开接口的**输入→输出**逻辑，不测类型、不测框架、不测 mock。
+
+## 提交消息
+
+- `feat:` — 新功能
+- `chore:` — 版本号变更、配置更新
+- `docs:` — 文档更新
+- `fix:` — 修 bug
+- `test:` — 测试
+
+## CLI 设计规则
+
+### `code` 子命令行为
+
+```
+qtcloud-devops code status [path]                # 三路 commit 比对 + 聚合统计
+qtcloud-devops code sync [name] [--repo path]    # 同步子模块指针到父仓库
+qtcloud-devops code retire <name> [--repo path]  # 退役子模块
+```
+
+### 规则
+
+- `status`：路径默认为当前目录 `.`
+- `sync`：`name` 省略时同步全部子模块
+- `retire`：`name` 为必填参数
+- 所有命令通过 `app/qtcloud_devops_cli/code.py` 封装 Rust native 调用，错误处理在该层完成
+
+### release 命令行为
+
+```
+qtcloud-devops release --version v0.1.0                # 标签 + GitHub Release（默认）
+qtcloud-devops release --version v0.1.0 --tag-only      # 仅标签
+qtcloud-devops release --version v0.1.0 --release-only  # 仅 GitHub Release
+```
+
+### 规则
+
+- **默认** = 标签 + GitHub Release（仓库从 git remote 自动检测）
+- `--tag-only` 和 `--release-only` 互斥
+- tag 是否已存在的处理：
+  - `--release-only`：tag **必须**存在，否则拒绝
+  - 默认 / `--tag-only`：tag 存在则跳过创建，不影响后续
+- `--repo` 参数**不存在**，仓库名通过 `get_remote_repo()` 从 `git remote get-url origin` 解析
+- 发布后**不验证** GitHub Release（`verify_release` 函数未使用）
+- 创建标签失败：返回错误码 1
+- 推送标签失败：自动回滚本地标签
+- GitHub Release 创建失败：若之前创建了标签则自动回滚
+
+## 测试目录结构
+
+tests/              ← Python 单元测试
+integrated_tests/   ← Python 集成测试（需要真实 git 仓库等外部依赖）
+
+## 测试覆盖率
+
+### Python
+
+```sh
+uv run pytest --cov=app/python --cov-report=term-missing --cov-fail-under=100
+```
+
+依赖 `pytest-cov`（已配置在 `[dependency-groups] dev` 中）。
+
+### Rust
+
+使用 `cargo-llvm-cov`（推荐）：
+
+```sh
+cargo install cargo-llvm-cov
+cargo llvm-cov --lcov --output-path target/coverage/lcov.info
+# HTML 报告
+cargo llvm-cov --html --output-dir target/coverage
+```
+
+也可使用 `cargo-tarpaulin`：
+
+```sh
+cargo install cargo-tarpaulin
+cargo tarpaulin --out Html
+```

qtcloud_devops_cli-0.2.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# CHANGELOG
+
+## [0.2.0] - 2026-05-24
+
+Rust 原生子模块管理引擎（`code` 命令）。
+
+### Added
+
+- `code status` 命令：三路 commit 比对 + 7 种子模块状态分类，格式化表格输出
+- `code sync` 命令：端到端子模块同步（推送子模块 → 更新父指针 → 推送父仓库）
+- `code retire` 命令：自动化反注册（deinit + .gitmodules + index 清理）
+- `code status` 输出 `parent_dirty` 字段，无子模块时退化到普通 git 状态检测
+- Rust 64 个测试（48 单元 + 6 二进制 + 10 集成），Python 88 个测试
+- 覆盖率（Python 94%, Rust 95.8%）记录到 STATUS.md
+- 子模组管理文档 docs/code.md
+
+### Changed
+
+- Python 包名 `python` → `qtcloud_devops_cli`，native 模块改为 `._native` 子模块
+- `app/` 目录重组为 `src/`，Rust 代码移至 `src/` 根目录
+- `sync` 从只更新本地指针改为完整端到端同步（含 push）
+- 测试目录分组：`tests/python/`、`tests/rust/`、`integrated_tests/`
+
+### Fixed
+
+- `code.py` sync/retire 函数改为 try/except 返回 dict（之前返回 None 导致 TypeError）
+- `#[pymodule]` 函数名与 `module-name` 不匹配导致的 ImportError
+- 子模块 orphaned 判定中 `merge_base` 无共同祖先时应为 orphaned
+
+## [0.1.0] - 2026-05-22
+
+CLI 接口重构与文档体系建立。
+
+### Added
+
+- `--tag-only` / `--release-only` 参数，支持分开执行 tag 和 GitHub Release
+- 从 `git remote get-url origin` 自动检测 GitHub 仓库，移除 `--repo` 参数
+- AGENTS.md CLI 设计规则固化
+- README.md、docs/index.md、docs/commands.md、docs/low-level-api.md 文档体系
+
+### Changed
+
+- 默认行为：标签 + GitHub Release（之前仅标签）
+- Tag 已存在时默认模式跳过 tag 创建继续发 release
+
+### Fixed
+
+- `--release-only` 预检查验证 tag 必须存在
+- 默认模式预检查不再因 tag 已存在而拒绝
+
+## [0.0.2] - 2026-05-21
+
+### Fixed
+
+- 版本号格式校验支持 scope 前缀（`cli/vX.Y.Z` / `python/vX.Y.Z`）
+- CHANGELOG 版本提取逻辑修正，scope 前缀版本不再影响查询
+
+### Added
+
+- STATUS.md：记录工具已知盲区（依赖完整性、uv.lock 同步等）
+
+## [0.0.1] - 2026-05-21
+
+初始版本。
+
+### Added
+
+- `release` 命令：预检查、发布前确认、执行发布、验证、回滚全流程自动化
+- `release --version/-V`：版本号参数
+- `release --dry-run`：仅检查不执行
+- `release -y`：跳过确认直接发布

qtcloud_devops_cli-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# CONTRIBUTING
+
+## 开发环境
+
+### Rust 工具链
+
+```bash
+# 安装 Rust
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# 验证
+rustc --version
+cargo --version
+```
+
+### 系统依赖
+
+```bash
+# Ubuntu / Debian
+sudo apt install libgit2-dev
+
+# macOS
+brew install libgit2
+```
+
+### 构建
+
+```bash
+# 完整安装（自动编译 Rust + 安装 Python CLI）
+pip install -e .[code]
+
+# 仅编译 Rust 核心（独立调试）
+cd packages/code
+cargo build
+cargo build --release
+
+# 仅安装 Python CLI（不编译 Rust）
+pip install -e .
+```
+
+## 目录结构
+
+```
+packages/code/               ← Rust crate
+├── Cargo.toml
+├── src/
+│   ├── lib.rs               ← crate 入口
+│   ├── main.rs              ← standalone CLI 入口
+│   ├── python.rs            ← PyO3 绑定层
+│   ├── model/mod.rs         ← SubmoduleStatus, RepoState 等核心模型
+│   └── commands/
+│       ├── mod.rs           ← SubmoduleEditor trait
+│       └── editor.rs        ← GitSubmoduleEditor 实现
+├── tests/integration.rs
+└── docs/user-guide.md
+
+src/cli/                      ← Python CLI
+├── app/
+│   ├── cli.py               ← Typer 入口（release + code 子命令）
+│   └── code.py              ← Rust native 调用封装
+├── pyproject.toml            ← maturin 构建配置（source-dir 指向 packages/code）
+└── ...
+```
+
+## 测试
+
+```bash
+# Rust 测试
+cd packages/code && cargo test
+
+# Python 测试
+pytest
+
+# 全部测试
+cd packages/code && cargo test && cd ../.. && pytest
+```
+
+## 提交消息
+
+- `feat:` — 新功能
+- `chore:` — 版本号变更、配置更新
+- `docs:` — 文档更新
+- `fix:` — 修 bug
+- `test:` — 测试