refactor(uv): make uv usage idiomatic (hatchling, dependency-groups, Docker, docs)

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
@@ -24,17 +24,17 @@ jobs:
           enable-cache: true
 
       - name: Install dependencies
-        run: uv sync --frozen --extra dev
+        run: uv sync --frozen
 
       - name: Run tests
-        run: uv run pytest -p no:cacheprovider -o addopts="" tests/ -q
+        run: uv run pytest --cov=codewiki --cov-report=term-missing -p no:cacheprovider tests/ -q
 
   lint:
     name: Lint
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
@@ -43,7 +43,7 @@ jobs:
           enable-cache: true
 
       - name: Install dependencies
-        run: uv sync --frozen --extra dev
+        run: uv sync --frozen
 
       - name: Collect changed Python files
         env:

.gitignore

@@ -38,9 +38,6 @@ MANIFEST
 htmlcov/
 .tox/
 .hypothesis/
-tests/*
-!tests/test_latest_compat.py
-!tests/test_review_changes.py
 
 # Jupyter
 *.ipynb

.python-version

@@ -1 +1 @@
-3.12
+3.12.13

README.md

@@ -98,15 +98,16 @@ pip install codewiki-plus
 codewiki --version
 ```
 
-> **开发者选项**：如需从源码开发（获取最新未发布改动），推荐使用 [uv](https://docs.astral.sh/uv/) 按 `uv.lock` 精确复现开发环境：
+> **开发者选项**：如需从源码开发（获取最新未发布改动），推荐使用 [uv](https://docs.astral.sh/uv/) 按 `uv.lock` 精确复现开发环境（`pyproject.toml:106` `tool.uv.default-groups = ["dev"]` 已包含 dev 工具）：
 > ```bash
 > git clone https://github.com/mambo-wang/CodeWiki-Plus.git
 > cd CodeWiki-Plus
-> uv sync --frozen --extra dev   # 按 uv.lock 复现完整开发环境（含 dev 依赖）
-> uv run codewiki --version      # 通过 uv 环境运行 CLI
-> uv run pytest tests/ -q -o addopts=""  # 运行测试（仓库未装 pytest-cov，须禁用 addopts 默认值）
+> uv sync --frozen              # 按 uv.lock 复现完整开发环境（含 dev 依赖，hatchling 构建）
+> uv run codewiki --version     # 通过 uv 环境运行 CLI
+> uv run pytest tests/ -q       # 运行测试（addopts 已移除 --cov，无需覆盖）
+> # 需要覆盖率时：uv run pytest --cov=codewiki --cov-report=term-missing
 > ```
-> 没有 uv 时也可 `pip install -e .`，但依赖解析不受 `uv.lock` 锁定。
+> 没有 uv 时也可 `pip install -e .[dev]`，但依赖解析不受 `uv.lock` 锁定。
 
 **第 2 步：配置 MCP Server**
 
@@ -832,15 +833,16 @@ Verify:
 codewiki --version
 ```
 
-> **For developers** (latest unreleased changes) — [uv](https://docs.astral.sh/uv/) is recommended to reproduce the dev environment exactly as locked by `uv.lock`:
+> **For developers** (latest unreleased changes) — [uv](https://docs.astral.sh/uv/) is recommended to reproduce the dev environment exactly as locked by `uv.lock` (`tool.uv.default-groups = ["dev"]` includes dev tools):
 > ```bash
 > git clone https://github.com/mambo-wang/CodeWiki-Plus.git
 > cd CodeWiki-Plus
-> uv sync --frozen --extra dev   # reproduce the full dev environment from uv.lock (incl. dev extras)
-> uv run codewiki --version      # run the CLI inside the uv-managed environment
-> uv run pytest tests/ -q -o addopts=""  # run tests (pytest-cov isn't installed; disable default addopts)
+> uv sync --frozen              # reproduce the full dev environment from uv.lock (hatchling build)
+> uv run codewiki --version     # run the CLI inside the uv-managed environment
+> uv run pytest tests/ -q       # run tests (no --cov in addopts; no override needed)
+> # with coverage: uv run pytest --cov=codewiki --cov-report=term-missing
 > ```
-> Without uv, `pip install -e .` still works, but dependency resolution is not locked by `uv.lock`.
+> Without uv, `pip install -e .[dev]` still works, but dependency resolution is not locked by `uv.lock`.
 
 **Step 2: Configure MCP Server**
 

docker/DOCKER_README.md

@@ -143,10 +143,9 @@ The Dockerfile (`docker/Dockerfile`) builds the CodeWiki image with:
 - `nodejs` and `npm` - For mermaid diagram validation
 
 ### Application Setup
-1. Copies `pyproject.toml` + `README.md` + `codewiki/` and installs dependencies via `pip install .` (deps resolved from `pyproject.toml`; no separate `requirements.txt`)
-2. Installs Python dependencies and the package
-3. Copies remaining assets
-4. Creates output directories:
+1. Copies `pyproject.toml` + `uv.lock` + `README.md` + `.python-version` and runs `uv sync --frozen --no-dev` (locked, reproducible)
+2. Copies `codewiki/` + `img/` and runs `uv sync --frozen --no-dev` to install the project
+3. Creates output directories:
    - `output/cache`
    - `output/temp`
    - `output/docs`

docker/Dockerfile

@@ -1,33 +1,35 @@
-# Use Python 3.12 slim image as base
-FROM python:3.12-slim
+# uv-based image: uv binary + Python 3.12 (Debian) in one layer
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
 
 # Set working directory
 WORKDIR /app
 
-# Install system dependencies
+# Install system dependencies (git for cloning, nodejs for mermaid validation)
 RUN apt-get update && apt-get install -y \
     git \
     curl \
     nodejs \
     npm \
     && rm -rf /var/lib/apt/lists/*
 
-# Copy package source and metadata, then install
-COPY pyproject.toml .
-COPY README.md .
-COPY codewiki ./codewiki
+# Leverage Docker layer cache: copy only dependency manifests first
+COPY pyproject.toml uv.lock README.md .python-version ./
 
-# Install Python dependencies and package
-RUN pip install --no-cache-dir .
+# Install locked runtime deps into .venv without the project itself
+RUN uv sync --frozen --no-install-project --no-group dev
 
-# Copy remaining assets
+# Copy project source
+COPY codewiki ./codewiki
 COPY img ./img
 
+# Install the project itself (still frozen, no dev extras)
+RUN uv sync --frozen --no-group dev
+
 # Create output directories
 RUN mkdir -p output/cache output/temp output/docs output/dependency_graphs
 
-# Set environment variables
-ENV PYTHONPATH=/app
+# Make the uv-managed venv the default PATH so `codewiki` / `python` resolve there
+ENV PATH="/app/.venv/bin:$PATH"
 ENV PYTHONUNBUFFERED=1
 
 # Expose port
@@ -37,5 +39,5 @@ EXPOSE 8000
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
     CMD curl -f http://localhost:8000/ || exit 1
 
-# Default command
+# Default command (uses venv python)
 CMD ["python", "codewiki/run_web_app.py", "--host", "0.0.0.0", "--port", "8000"]

pyproject.toml

@@ -1,6 +1,6 @@
 [build-system]
-requires = ["setuptools>=68.0.0", "wheel"]
-build-backend = "setuptools.build_meta"
+requires = ["hatchling"]
+build-backend = "hatchling.build"
 
 [project]
 name = "codewiki-plus"
@@ -65,6 +65,17 @@ dependencies = [
     "pathspec>=0.12.1"
 ]
 
+[dependency-groups]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.0.0",
+    "mypy>=1.5.0",
+    "ruff>=0.1.0",
+]
+
+# Keep pip-compatible extra for `pip install -e .[dev]` fallback (uv canonical is dependency-groups above)
 [project.optional-dependencies]
 dev = [
     "pytest>=7.4.0",
@@ -84,31 +95,15 @@ Documentation = "https://github.com/mambo-wang/CodeWiki-Plus/blob/main/README.md
 Repository = "https://github.com/mambo-wang/CodeWiki-Plus"
 Issues = "https://github.com/mambo-wang/CodeWiki-Plus/issues"
 
-[tool.setuptools]
-packages = [
-    "codewiki", 
-    "codewiki.cli", 
-    "codewiki.cli.commands", 
-    "codewiki.cli.models", 
-    "codewiki.cli.utils", 
-    "codewiki.cli.adapters",
-    "codewiki.src",
-    "codewiki.src.be",
-    "codewiki.src.be.agent_tools",
-    "codewiki.src.be.dependency_analyzer",
-    "codewiki.src.be.dependency_analyzer.analysis",
-    "codewiki.src.be.dependency_analyzer.analyzers",
-    "codewiki.src.be.dependency_analyzer.analyzers.route_extractors",
-    "codewiki.src.be.dependency_analyzer.models",
-    "codewiki.src.be.dependency_analyzer.utils",
-    "codewiki.src.fe",
-    "codewiki.mcp",
-    "codewiki.mcp.tools",
-    "codewiki.hooks"
-]
+[tool.hatch.build]
+artifacts = ["codewiki/templates/**/*", "codewiki/py.typed", "codewiki/agents/**/*"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["codewiki"]
 
-[tool.setuptools.package-data]
-codewiki = ["templates/**/*", "py.typed", "agents/*.md"]
+[tool.uv]
+managed = true
+default-groups = ["dev"]
 
 [tool.black]
 line-length = 100
@@ -137,5 +132,6 @@ testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
-addopts = "-v --cov=codewiki --cov-report=term-missing"
+addopts = "-v"
+# Coverage is CI-only: `uv run pytest --cov=codewiki --cov-report=term-missing` (keeps `uv sync` without dev + local `uv run pytest -q` working without pytest-cov)