Log Call-Site Directory

.github/workflows/main_base.yml

@@ -31,6 +31,37 @@ jobs:
     with:
       toolchain: ${{ inputs.toolchain }}
 
+  log-index-check:
+    name: Log index — log-reference.md in sync with source
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      - name: Check log-reference.md is up to date
+        id: check
+        run: python3 scripts/update_log_index.py --check --no-color
+
+      - name: How to fix
+        if: failure()
+        run: |
+          echo ""
+          echo "════════════════════════════════════════════════════════════"
+          echo "  log-reference.md is out of sync with the source code."
+          echo ""
+          echo "  Fix it locally by running:"
+          echo ""
+          echo "    python3 scripts/update_log_index.py --non-interactive --no-color"
+          echo ""
+          echo "  Then review the diff, stage, and commit:"
+          echo ""
+          echo "    git diff documentation/docs/configuration/log-reference.md"
+          echo "    git add documentation/docs/configuration/log-reference.md"
+          echo "    git commit -m 'docs: sync log-reference.md'"
+          echo ""
+          echo "════════════════════════════════════════════════════════════"
+
   forward-proxy:
     uses: ./.github/workflows/forward_proxy.yml
     with:

.mise/scripts/docs/generate_docs.sh

@@ -14,6 +14,8 @@
 #   3. kmip-tables     — scan KMIP operations, update README.md KMIP table
 #   4. crypto-inventory— scan Rust source → crypto_inventory.md (CBOM sensor)
 #   5. cbom            — generate cbom/cbom.cdx.json (CycloneDX 1.6)
+#   6. log-index       — sync documentation/docs/configuration/log-reference.md
+#                        with actual log call-sites in source (Python, no build needed)
 #
 # Usage:
 #   bash .mise/scripts/docs/generate_docs.sh [OPTIONS]
@@ -24,6 +26,7 @@
 #   --skip-kmip-tables  Skip step 3 (KMIP table update — no build needed)
 #   --skip-crypto       Skip step 4 (crypto inventory — no build needed)
 #   --skip-cbom         Skip step 5 (CBOM generation — requires cdxgen)
+#   --skip-log-index    Skip step 6 (log-reference.md sync — no build needed)
 #   --quick             Alias for --skip-server --skip-ckms (no Rust build needed)
 #   --help              Show this message
 #
@@ -56,6 +59,7 @@ SKIP_CKMS=false
 SKIP_KMIP=false
 SKIP_CRYPTO=false
 SKIP_CBOM=false
+SKIP_LOG_INDEX=false
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -79,6 +83,10 @@ while [[ $# -gt 0 ]]; do
       SKIP_CBOM=true
       shift
       ;;
+    --skip-log-index)
+      SKIP_LOG_INDEX=true
+      shift
+      ;;
     --quick)
       SKIP_SERVER=true
       SKIP_CKMS=true
@@ -101,46 +109,46 @@ ERRORS=0
 
 # ─── Step 1: Server docs ──────────────────────────────────────────────────────
 if [[ "$SKIP_SERVER" == false ]]; then
-  banner "1/5 — Server docs (server_cli.md + server_configuration_file.md)"
+  banner "1/6 — Server docs (server_cli.md + server_configuration_file.md)"
   if bash "$SCRIPT_DIR/renew_server_doc.sh"; then
     ok "Server docs regenerated"
   else
     fail "renew_server_doc.sh failed"
     ERRORS=$((ERRORS + 1))
   fi
 else
-  warn "Step 1/5 skipped (--skip-server)"
+  warn "Step 1/6 skipped (--skip-server)"
 fi
 
 # ─── Step 2: ckms CLI docs ────────────────────────────────────────────────────
 if [[ "$SKIP_CKMS" == false ]]; then
-  banner "2/5 — ckms CLI docs (main_commands.md + usage.md)"
+  banner "2/6 — ckms CLI docs (main_commands.md + usage.md)"
   if bash "$SCRIPT_DIR/renew_ckms_markdown.sh"; then
     ok "ckms CLI docs regenerated"
   else
     fail "renew_ckms_markdown.sh failed"
     ERRORS=$((ERRORS + 1))
   fi
 else
-  warn "Step 2/5 skipped (--skip-ckms)"
+  warn "Step 2/6 skipped (--skip-ckms)"
 fi
 
 # ─── Step 3: KMIP support table ───────────────────────────────────────────────
 if [[ "$SKIP_KMIP" == false ]]; then
-  banner "3/5 — KMIP support tables (README.md + kmip_support/support.md)"
+  banner "3/6 — KMIP support tables (README.md + kmip_support/support.md)"
   if python3 "$SCRIPT_DIR/update_readme_kmip.py"; then
     ok "KMIP support tables updated"
   else
     fail "update_readme_kmip.py failed"
     ERRORS=$((ERRORS + 1))
   fi
 else
-  warn "Step 3/5 skipped (--skip-kmip-tables)"
+  warn "Step 3/6 skipped (--skip-kmip-tables)"
 fi
 
 # ─── Step 4: Cryptographic inventory (CBOM sensor) ───────────────────────────
 if [[ "$SKIP_CRYPTO" == false ]]; then
-  banner "4/5 — Cryptographic inventory (crypto_inventory.md)"
+  banner "4/6 — Cryptographic inventory (crypto_inventory.md)"
   if bash "$REPO_ROOT/.mise/scripts/audit/crypto_sensor.sh" \
     --repo-root "$REPO_ROOT" \
     --quick; then
@@ -150,22 +158,33 @@ if [[ "$SKIP_CRYPTO" == false ]]; then
     ERRORS=$((ERRORS + 1))
   fi
 else
-  warn "Step 4/5 skipped (--skip-crypto)"
+  warn "Step 4/6 skipped (--skip-crypto)"
 fi
 
 # ─── Step 5: CBOM ─────────────────────────────────────────────────────────────
 if [[ "$SKIP_CBOM" == false ]]; then
-  banner "5/5 — CBOM (cbom/cbom.cdx.json)"
+  banner "5/6 — CBOM (cbom/cbom.cdx.json)"
   if bash "$REPO_ROOT/.mise/scripts/release/generate_cbom.sh"; then
     ok "CBOM regenerated"
   else
     fail "generate_cbom.sh failed"
     ERRORS=$((ERRORS + 1))
   fi
 else
-  warn "Step 5/5 skipped (--skip-cbom)"
+  warn "Step 5/6 skipped (--skip-cbom)"
+fi
+# ─── Step 6: Log call-site index ────────────────────────────────────────────────────
+if [[ "$SKIP_LOG_INDEX" == false ]]; then
+  banner "6/6 — Log call-site index (log-reference.md)"
+  if python3 "${REPO_ROOT}/scripts/update_log_index.py" --non-interactive --no-color; then
+    ok "log-reference.md synced"
+  else
+    fail "update_log_index.py failed"
+    ERRORS=$((ERRORS + 1))
+  fi
+else
+  warn "Step 6/6 skipped (--skip-log-index)"
 fi
-
 # ─── Summary ──────────────────────────────────────────────────────────────────
 echo
 if [[ "$ERRORS" -eq 0 ]]; then

.mise/tasks/docs/log-index-check

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+#MISE description="Check log-reference.md is in sync with source (fails if out of date)"
+set -euo pipefail
+source "${MISE_CONFIG_ROOT}/.mise/lib/common.sh"
+
+print_header "Checking log-reference.md"
+REPO_ROOT="$(get_repo_root)"
+
+if python3 "${REPO_ROOT}/scripts/update_log_index.py" --check --no-color; then
+  print_success "log-reference.md is up to date"
+else
+  print_error "log-reference.md is out of sync with the source code."
+  echo ""
+  echo "  Fix it by running one of:"
+  echo ""
+  echo "    python3 scripts/update_log_index.py --non-interactive --no-color"
+  echo "    mise run docs:generate"
+  echo ""
+  echo "  Then review, stage, and commit:"
+  echo ""
+  echo "    git diff documentation/docs/configuration/log-reference.md"
+  echo "    git add documentation/docs/configuration/log-reference.md"
+  echo "    git commit -m 'docs: sync log-reference.md'"
+  exit 1
+fi

.pre-commit-config.yaml

@@ -191,6 +191,19 @@ repos:
         pass_filenames: false
         stages: [manual]
 
+      - id: update-log-index
+        name: Update log call-site index (log-reference.md)
+        description: |
+          Syncs documentation/docs/configuration/log-reference.md against the
+          actual log call-sites in Rust and TypeScript source files.
+          Flags stale entries with [REMOVED], appends new entries, and updates
+          ×N multiplicity counts. Exits 1 when any change is made so the commit
+          is blocked until the updated file is reviewed and re-staged.
+        entry: python3 scripts/update_log_index.py --non-interactive --no-color
+        language: system
+        pass_filenames: false
+        files: \.(rs|ts|tsx)$
+
       - id: cargo-deny-licenses
         name: Release - generate SBOM licenses list
         entry: bash -c 'cargo deny list -l crate > sbom/licenses.txt'