Addstx

.github/workflows/README.md

@@ -55,16 +55,16 @@ Workflows that run on **PR to main** use the environment **`approval-required`**
   - Run manually when needed from **Actions → Compatibility → Run workflow**
 
 ### Benchmark Workflow (benchmark.yml)
-- **Triggers**: `workflow_dispatch` only (manual)
-- **Purpose**: Performance benchmarking and trend tracking
+- **Triggers**: `workflow_dispatch` and pull_request/PR paths updates
+- **Purpose**: Performance benchmarking, baseline comparison, and trend tracking
 - **Runs**:
-  - Hash verification benchmark
-  - Disk I/O benchmark
-  - Piece assembly benchmark
-  - Loopback throughput benchmark
-  - Encryption benchmark
+  - Run benchmark suite for `head` changeset and compare against `base`
+  - Evaluate deltas against `dev/benchmark_thresholds.toml`
+  - Render committed docs from the comparison output and trend history
 - **Rationale**:
-  - Run manually when needed; can commit results to the repo when run from `main`
+  - Benchmarks stay out of pre-commit for faster local commits
+  - PRs to `main` can validate regressions before merge
+  - Commits only generated reports under `docs/en/reports/benchmarks/generated/`
 
 ### Security Workflow (security.yml)
 - **Triggers**: PR to `main` (runs after approval), weekly schedule, `workflow_dispatch`
@@ -233,7 +233,8 @@ Workflows that run on **PR to main** use the environment **`approval-required`**
 - **CI Pipeline** (`ci.yml`) and **Test** (`test.yml`): PR to `main` (with approval) or manual run
 - **Version Check** (`version-check.yml`): PR to `main` (with approval) or manual run
 - **Security** (`security.yml`): PR to `main` (with approval), weekly schedule, or manual run
-- **Compatibility** (`compatibility.yml`) and **Benchmarks** (`benchmark.yml`): manual run only
+- **Compatibility** (`compatibility.yml`): manual run only
+- **Benchmark** (`benchmark.yml`): manual run and pull_request flow as defined in the workflow
 
 ---
 

.github/workflows/benchmark.yml

@@ -1,17 +1,32 @@
 name: Benchmark
 
 on:
-  workflow_dispatch:  # Manual only, never automatic
+  workflow_dispatch:
+    inputs:
+      base_ref:
+        description: Base branch/commit to compare against
+        required: false
+        default: main
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+env:
+  BENCH_BASE_DIR: ${{ github.workspace }}/.ci/benchmark_base
+  BENCH_HEAD_DIR: ${{ github.workspace }}/.ci/benchmark_head
+  BENCH_COMPARE_DIR: ${{ github.workspace }}/docs/en/reports/benchmarks/generated
+  BENCH_CONFIG_FILE: docs/examples/example-config-performance.toml
+  BENCH_QUICK: "1"
+  BENCH_KEEP_HISTORY: "20"
 
 concurrency:
   group: benchmark-write-${{ github.ref }}
-  cancel-in-progress: false
+  cancel-in-progress: true
 
 jobs:
   benchmark:
     name: benchmark
     runs-on: ubuntu-latest
-    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
     permissions:
       contents: write  # Required to commit benchmark results
       actions: read
@@ -35,42 +50,131 @@ jobs:
       - name: Install dependencies
         run: |
           uv sync --dev
-
-      - name: Run hash verification benchmark
-        run: |
-          uv run python tests/performance/bench_hash_verify.py --quick --record-mode=commit --config-file docs/examples/example-config-performance.toml
-
-      - name: Run disk I/O benchmark
+
+      - name: Run head benchmark suite
         run: |
-          uv run python tests/performance/bench_disk_io.py --quick --sizes 256KiB 1MiB --record-mode=commit --config-file docs/examples/example-config-performance.toml
-
-      - name: Run piece assembly benchmark
+          mkdir -p "${BENCH_HEAD_DIR}"
+          if [ "${BENCH_QUICK}" = "1" ]; then
+            QUICK_ARG="--quick"
+          else
+            QUICK_ARG=""
+          fi
+
+          uv run python tests/performance/bench_hash_verify.py ${QUICK_ARG} \
+            --record-mode=none \
+            --config-file "${BENCH_CONFIG_FILE}" \
+            --json-out "${BENCH_HEAD_DIR}/bench_hash_verify.json"
+
+          uv run python tests/performance/bench_disk_io.py ${QUICK_ARG} --sizes 256KiB 1MiB \
+            --record-mode=none \
+            --config-file "${BENCH_CONFIG_FILE}" \
+            --json-out "${BENCH_HEAD_DIR}/bench_disk_io.json"
+
+          uv run python tests/performance/bench_piece_assembly.py ${QUICK_ARG} \
+            --record-mode=none \
+            --config-file "${BENCH_CONFIG_FILE}" \
+            --json-out "${BENCH_HEAD_DIR}/bench_piece_assembly.json"
+
+          uv run python tests/performance/bench_loopback_throughput.py ${QUICK_ARG} \
+            --record-mode=none \
+            --config-file "${BENCH_CONFIG_FILE}" \
+            --json-out "${BENCH_HEAD_DIR}/bench_loopback_throughput.json"
+
+          uv run python tests/performance/bench_encryption.py ${QUICK_ARG} \
+            --record-mode=none \
+            --config-file "${BENCH_CONFIG_FILE}" \
+            --json-out "${BENCH_HEAD_DIR}/bench_encryption.json"
+
+      - name: Prepare base checkout
         run: |
-          uv run python tests/performance/bench_piece_assembly.py --quick --record-mode=commit --config-file docs/examples/example-config-performance.toml
-
-      - name: Run loopback throughput benchmark
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE_REF="${{ github.event.pull_request.base.sha }}"
+          else
+            BASE_REF="${{ github.event.inputs.base_ref }}"
+          fi
+          rm -rf "${BENCH_BASE_DIR}"
+          mkdir -p "${BENCH_BASE_DIR}"
+          git worktree add --detach "${BENCH_BASE_DIR}" "${BASE_REF}"
+
+      - name: Run base benchmark suite
         run: |
-          uv run python tests/performance/bench_loopback_throughput.py --quick --record-mode=commit --config-file docs/examples/example-config-performance.toml
-
-      - name: Run encryption benchmark
+          mkdir -p "${BENCH_BASE_DIR}"
+          if [ "${BENCH_QUICK}" = "1" ]; then
+            QUICK_ARG="--quick"
+          else
+            QUICK_ARG=""
+          fi
+
+          (cd "${BENCH_BASE_DIR}" && \
+            uv run python tests/performance/bench_hash_verify.py ${QUICK_ARG} \
+              --record-mode=none \
+              --config-file "${BENCH_CONFIG_FILE}" \
+              --json-out "${BENCH_BASE_DIR}/bench_hash_verify.json")
+
+          (cd "${BENCH_BASE_DIR}" && \
+            uv run python tests/performance/bench_disk_io.py ${QUICK_ARG} --sizes 256KiB 1MiB \
+              --record-mode=none \
+              --config-file "${BENCH_CONFIG_FILE}" \
+              --json-out "${BENCH_BASE_DIR}/bench_disk_io.json")
+
+          (cd "${BENCH_BASE_DIR}" && \
+            uv run python tests/performance/bench_piece_assembly.py ${QUICK_ARG} \
+              --record-mode=none \
+              --config-file "${BENCH_CONFIG_FILE}" \
+              --json-out "${BENCH_BASE_DIR}/bench_piece_assembly.json")
+
+          (cd "${BENCH_BASE_DIR}" && \
+            uv run python tests/performance/bench_loopback_throughput.py ${QUICK_ARG} \
+              --record-mode=none \
+              --config-file "${BENCH_CONFIG_FILE}" \
+              --json-out "${BENCH_BASE_DIR}/bench_loopback_throughput.json")
+
+          (cd "${BENCH_BASE_DIR}" && \
+            uv run python tests/performance/bench_encryption.py ${QUICK_ARG} \
+              --record-mode=none \
+              --config-file "${BENCH_CONFIG_FILE}" \
+              --json-out "${BENCH_BASE_DIR}/bench_encryption.json")
+
+      - name: Compare and render benchmark reports
         run: |
-          uv run python tests/performance/bench_encryption.py --quick --record-mode=commit --config-file docs/examples/example-config-performance.toml
-
+          mkdir -p "${BENCH_COMPARE_DIR}"
+          uv run python dev/scripts/compare_benchmark_json.py \
+            --base "${BENCH_BASE_DIR}" \
+            --head "${BENCH_HEAD_DIR}" \
+            --thresholds dev/benchmark_thresholds.toml \
+            --output "${BENCH_COMPARE_DIR}/comparison_latest.json"
+
+          uv run python dev/scripts/render_benchmark_docs.py \
+            --comparison "${BENCH_COMPARE_DIR}/comparison_latest.json" \
+            --history "${BENCH_COMPARE_DIR}/benchmark_history.json" \
+            --out-dir "${BENCH_COMPARE_DIR}" \
+            --keep "${BENCH_KEEP_HISTORY}"
+
       - name: Upload benchmark artifacts
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: benchmark-results
+          name: benchmark-ci-artifacts
           path: |
-            docs/reports/benchmarks/runs/*.json
-            docs/reports/benchmarks/timeseries/*.json
+            ${{ env.BENCH_BASE_DIR }}/*.json
+            ${{ env.BENCH_HEAD_DIR }}/*.json
+            docs/en/reports/benchmarks/generated/comparison_latest.json
+            docs/en/reports/benchmarks/generated/comparison_latest.md
+            docs/en/reports/benchmarks/generated/trend_charts.md
+            docs/en/reports/benchmarks/generated/benchmark_history.json
           retention-days: 90
 
       - name: Commit benchmark results
-        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        if: github.event_name == 'workflow_dispatch'
         run: |
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
-          git add -f docs/reports/benchmarks/
-          git diff --staged --quiet || git commit -m "ci: record benchmark results [skip ci]"
-          git push
+          git add docs/en/reports/benchmarks/generated/comparison_latest.md \
+            docs/en/reports/benchmarks/generated/comparison_latest.json \
+            docs/en/reports/benchmarks/generated/trend_charts.md \
+            docs/en/reports/benchmarks/generated/benchmark_history.json \
+            docs/en/reports/benchmarks/generated/README.md
+          if ! git diff --cached --quiet; then
+            git commit -m "ci: update benchmark docs artifacts"
+            git push
+          fi

.github/workflows/build-documentation.yml

@@ -8,7 +8,7 @@ on:
     paths:
       - 'docs/**'
       - 'dev/mkdocs.yml'
-      - '.readthedocs.yaml'
+      - 'dev/.readthedocs.yaml'
       - 'dev/requirements-rtd.txt'
       - 'ccbt/**'
   workflow_dispatch:
@@ -147,7 +147,7 @@ jobs:
       - name: Generate Bandit report
         run: |
           uv run python tests/scripts/ensure_bandit_dir.py
-          uv run bandit -r ccbt/ -f json -o docs/reports/bandit/bandit-report.json --severity-level medium -x tests,benchmarks,dev,dist,docs,htmlcov,site,.venv,.pre-commit-cache,.pre-commit-home,.pytest_cache,.ruff_cache,.hypothesis,.github,.ccbt,.cursor,.benchmarks
+          uv run bandit -r ccbt/ -f json -o docs/reports/bandit/bandit-report.json --severity-level medium -x tests,benchmarks,dev,dist,docs,htmlcov,site,.venv,.pre-commit-cache,.pre-commit-home,.pytest_cache,.ruff_cache,.hypothesis,.github,.ccbt,.cursor,.benchmarks,ccbt/i18n/scripts,ccbt/i18n/locale_data
         continue-on-error: true
 
       - name: Ensure report files exist in documentation location

.github/workflows/ci.yml

@@ -77,7 +77,6 @@ jobs:
   i18n:
     name: i18n
     runs-on: ubuntu-latest
-    continue-on-error: true
     environment: approval-required
     permissions:
       contents: read
@@ -104,10 +103,6 @@ jobs:
         run: |
           uv run python -m ccbt.i18n.extract ccbt ccbt/i18n/locales/en/LC_MESSAGES/ccbt.pot
 
-      - name: Check string coverage
-        run: |
-          uv run python -m ccbt.i18n.scripts.check_string_coverage --source-dir ccbt --fail-on-gap
-
       - name: Validate .po files
         run: |
           uv run python -m ccbt.i18n.scripts.validate_po

.github/workflows/generate-reports.yml

@@ -46,7 +46,7 @@ jobs:
       - name: Ensure bandit directory exists
         run: uv run python tests/scripts/ensure_bandit_dir.py
       - name: Run Bandit security scan
-        run: uv run bandit -r ccbt/ -f json -o docs/reports/bandit/bandit-report.json --severity-level medium -x tests,benchmarks,dev,dist,docs,htmlcov,site,.venv,.pre-commit-cache,.pre-commit-home,.pytest_cache,.ruff_cache,.hypothesis,.github,.ccbt,.cursor,.benchmarks
+        run: uv run bandit -r ccbt/ -f json -o docs/reports/bandit/bandit-report.json --severity-level medium -x tests,benchmarks,dev,dist,docs,htmlcov,site,.venv,.pre-commit-cache,.pre-commit-home,.pytest_cache,.ruff_cache,.hypothesis,.github,.ccbt,.cursor,.benchmarks,ccbt/i18n/scripts,ccbt/i18n/locale_data
       - name: Upload Bandit report artifact
         uses: actions/upload-artifact@v4
         with:

.github/workflows/i18n-manual.yml

@@ -1,4 +1,4 @@
-# Manual i18n pipeline: extract, update, validate, coverage, completeness, compile.
+# Manual i18n pipeline: extract, msgmerge, fill English, validate, completeness, compile.
 # Run from Actions tab (workflow_dispatch) to validate translations on main or current branch.
 name: i18n (manual)
 
@@ -35,14 +35,22 @@ jobs:
       - name: Install dependencies
         run: uv sync --dev
 
+      - name: Install gettext (msgmerge)
+        run: sudo apt-get update && sudo apt-get install -y gettext
+
       - name: Extract translatable strings
         run: uv run python -m ccbt.i18n.extract ccbt ccbt/i18n/locales/en/LC_MESSAGES/ccbt.pot
 
-      - name: Update translation files
-        run: uv run python -m ccbt.i18n.scripts.update_translations
+      - name: Merge template into locale catalogs (msgmerge)
+        run: |
+          set -euo pipefail
+          POT=ccbt/i18n/locales/en/LC_MESSAGES/ccbt.pot
+          for po in ccbt/i18n/locales/*/LC_MESSAGES/ccbt.po; do
+            msgmerge --update --backup=none --sort-output "$po" "$POT"
+          done
 
-      - name: Check string coverage
-        run: uv run python -m ccbt.i18n.scripts.check_string_coverage --source-dir ccbt --fail-on-gap
+      - name: Fill English catalog (msgstr = msgid for new entries)
+        run: uv run python -m ccbt.i18n.scripts.fill_english
 
       - name: Validate .po files
         run: uv run python -m ccbt.i18n.scripts.validate_po
@@ -58,4 +66,3 @@ jobs:
 
       - name: Compile .mo files
         run: uv run python -m ccbt.i18n.scripts.compile_all
-        continue-on-error: true

.github/workflows/release.yml

@@ -204,7 +204,11 @@ jobs:
 
       - name: Build documentation
         run: |
-          uv run mkdocs build --strict -f dev/mkdocs.yml
+          mkdir -p site/reports/htmlcov
+          if [ ! -f site/reports/htmlcov/index.html ]; then
+            echo '<html><body><h1>Coverage Report</h1><p>Placeholder for mkdocs-coverage during release build.</p></body></html>' > site/reports/htmlcov/index.html
+          fi
+          MKDOCS_STRICT=true uv run python dev/build_docs_patched_clean.py
 
       - name: Build package
         run: |

.github/workflows/security.yml

@@ -41,7 +41,7 @@ jobs:
 
       - name: Run Bandit security scan
         run: |
-          uv run bandit -r ccbt/ -f json -o docs/reports/bandit/bandit-report.json --severity-level medium -x tests,benchmarks,dev,dist,docs,htmlcov,site,.venv,.pre-commit-cache,.pre-commit-home,.pytest_cache,.ruff_cache,.hypothesis,.github,.ccbt,.cursor,.benchmarks
+          uv run bandit -r ccbt/ -f json -o docs/reports/bandit/bandit-report.json --severity-level medium -x tests,benchmarks,dev,dist,docs,htmlcov,site,.venv,.pre-commit-cache,.pre-commit-home,.pytest_cache,.ruff_cache,.hypothesis,.github,.ccbt,.cursor,.benchmarks,ccbt/i18n/scripts,ccbt/i18n/locale_data
 
       - name: Upload Bandit report
         if: always()

.github/workflows/test.yml

@@ -66,6 +66,10 @@ jobs:
       - name: Install dependencies
         run: |
           uv sync --dev
+
+      - name: Prepare test report directories
+        run: |
+          mkdir -p site/reports
 
       - name: Check for port conflicts
         run: |
@@ -98,6 +102,8 @@ jobs:
 
       - name: Run tests with coverage
         shell: bash
+        env:
+          CCBT_TEST_DEBUG_LOG: /tmp/ccbt-test-debug.log
         run: |
           # Exclude compatibility tests from main test run (they run separately)
           uv run pytest -c dev/pytest.ini tests/ \

.gitignore

@@ -11,7 +11,7 @@ MagicMock
 scripts
 compatibility_tests/
 lint_outputs/
-
+locales
 # Pre-commit, pre-push, and benchmark outputs (CI force-adds when committing reports)
 .pre-commit-cache/
 .pre-commit-home/
@@ -26,6 +26,13 @@ benchmarks/output/
 benchmarks/results/
 benchmark_results/
 docs/reports/
+!docs/
+!docs/en/
+!docs/en/reports/
+!docs/en/reports/benchmarks/
+!docs/en/reports/benchmarks/generated/
+!docs/en/reports/benchmarks/generated/*.md
+!docs/en/reports/benchmarks/generated/*.json
 docs/reports/coverage/
 docs/reports/bandit/
 docs/reports/benchmarks/artifacts/