v1.0-RC readiness

Author: vim89

.github/workflows/ci.yml

@@ -3,8 +3,28 @@ name: CI
 on:
   push:
     branches: [ main, mvp-0.0.1-snapshot ]
+    paths:
+      - 'modules/**'
+      - 'build.sbt'
+      - 'project/**'
+      - '.github/workflows/ci.yml'
+      - '!docs/**'
+      - '!**/*.md'
   pull_request:
     branches: [ main, mvp-0.0.1-snapshot ]
+    paths:
+      - 'modules/**'
+      - 'build.sbt'
+      - 'project/**'
+      - '.github/workflows/ci.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 env:
   JAVA_OPTS: -Xmx4G -XX:+UseG1GC
@@ -39,52 +59,34 @@ jobs:
               modules/engines-flink/target
     name: ${{ matrix.module }}
     runs-on: ubuntu-22.04
+    if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Set up JDK 21
+      - name: Set up JDK 17 (with SBT cache)
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: '21'
-
-      - name: Cache SBT and dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.ivy2/cache
-            ~/.cache/coursier
-            ~/.sbt
-            ${{ matrix.paths }}
-          key: ${{ runner.os }}-sbt-${{ matrix.module }}-${{ hashFiles('**/build.sbt', '**/project/**/*.sbt', format('modules/{0}/**', matrix.module)) }}
-          restore-keys: |
-            ${{ runner.os }}-sbt-${{ matrix.module }}-
+          java-version: '17'
+          cache: 'sbt'
 
       - name: Build module
         run: sbt -batch ${{ matrix.commands }}
 
   refactor-lint:
     name: Refactor lint & Unsafe cast gate
     runs-on: ubuntu-22.04
+    if: ${{ !github.event.pull_request.draft }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-      - name: Set up JDK 21
+      - name: Set up JDK 17 (with SBT cache)
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: '21'
-      - name: Cache Ivy and Coursier
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.ivy2/cache
-            ~/.cache/coursier
-            ~/.sbt
-          key: ${{ runner.os }}-sbt-${{ hashFiles('**/build.sbt', '**/project/**/*.sbt', '**/.scalafix.conf') }}
-          restore-keys: |
-            ${{ runner.os }}-sbt-
+          java-version: '17'
+          cache: 'sbt'
       - name: Scalafix check (no rewrites)
         continue-on-error: true
         run: sbt -batch "scalafixAll --check"
@@ -97,7 +99,7 @@ jobs:
           # Whitelist files where reflective casts are intentionally localized
           WHITELIST=(
             "modules/engines-spark/src/main/scala/com/flowforge/engines/spark/SparkDataAlgebra.scala"
-            "modules/core/src/main/scala/com/flowforge/core/contracts/internal/SchemaConformsMacros.scala"
+            "modules/core/src/main/scala/com/flowforge/core/contracts/internal/ContractMacros.scala"
           )
 
           is_whitelisted() {
@@ -127,6 +129,61 @@ jobs:
           fi
           echo "✅ PASS: No unsafe asInstanceOf/Any found outside whitelist"
 
+  doc-lint:
+    name: Scaladoc coverage (report → enforce later)
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install ripgrep
+        run: sudo apt-get update && sudo apt-get install -y ripgrep
+      - name: Scan public packages for missing Scaladoc
+        shell: bash
+        run: |
+          set -euo pipefail
+          ROOTS=(
+            modules/core/src/main/scala/com/flowforge/core
+            modules/core/src/main/scala/com/flowforge/framework
+            modules/core/src/main/scala/com/flowforge/core/contracts
+            modules/core/src/main/scala/com/flowforge/core/algebra
+            modules/engines-spark/src/main/scala/com/flowforge/engines/spark
+            modules/quality-deequ/src/main/scala/com/flowforge/quality/deequ
+          )
+          total=0; missing=0
+          mapfile -t FILES < <(rg -l "^" "${ROOTS[@]}" --glob "**/*.scala" || true)
+          offenders=()
+          for file in "${FILES[@]}"; do
+            # Classes/traits/objects
+            while IFS= read -r line; do
+              ln=${line%%:*}; decl=${line#*:*:}
+              (( total++ ))
+              start=$((ln-3)); [ $start -lt 1 ] && start=1
+              if ! sed -n "$start,$((ln-1))p" "$file" | rg -q "^/\*\*"; then
+                offenders+=("$file:$ln:$decl")
+                (( missing++ ))
+              fi
+            done < <(rg -n "^\s*(final\s+)?(case\s+)?(class|trait|object)\s+\w+" "$file" || true)
+            # Public defs (basic heuristic)
+            while IFS= read -r line; do
+              ln=${line%%:*}; decl=${line#*:*:}
+              (( total++ ))
+              start=$((ln-3)); [ $start -lt 1 ] && start=1
+              if ! sed -n "$start,$((ln-1))p" "$file" | rg -q "^/\*\*"; then
+                offenders+=("$file:$ln:$decl")
+                (( missing++ ))
+              fi
+            done < <(rg -n "^\s*def\s+\w+\s*\(" "$file" | rg -v "^\s*(private|protected)\b" || true)
+          done
+          cov=$(( ( (total-missing) * 100 ) / ( (total==0) ? 1 : total ) ))
+          echo "Scaladoc coverage: $cov% ($((total-missing))/$total)"
+          if [ ${#offenders[@]} -gt 0 ]; then
+            echo "First 200 missing docs:"; printf '%s\n' "${offenders[@]}" | head -n 200
+          fi
+          # ENFORCE: fail when offenders exist (single CI run post-sweep)
+          if [ ${#offenders[@]} -gt 0 ]; then
+            echo "❌ Missing Scaladoc found"; exit 1
+          fi
+
       - name: Try/Try-catch/unsafeRunSync bans (main sources only)
         shell: bash
         run: |

.github/workflows/release.yml

@@ -16,6 +16,11 @@ on:
         default: false
         type: boolean
 
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
 concurrency:
   group: release-${{ github.ref }}
   cancel-in-progress: false
@@ -82,11 +87,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Setup Java 21
+      - name: Setup Java 17
         uses: actions/setup-java@v4
         with:
           distribution: 'temurin'
-          java-version: '21'
+          java-version: '17'
 
       - name: Cache SBT and dependencies
         uses: actions/cache@v4
@@ -148,11 +153,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Setup Java 21
+      - name: Setup Java 17
         uses: actions/setup-java@v4
         with:
           distribution: 'temurin'
-          java-version: '21'
+          java-version: '17'
 
       - name: Cache SBT and dependencies
         uses: actions/cache@v4
@@ -193,9 +198,83 @@ jobs:
           path: release-artifacts/
           retention-days: 30
 
+  publish-docs:
+    name: Publish Scaladoc to GitHub Pages
+    needs: [validate-release, pre-release-tests]
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Java 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+      - name: Cache SBT and dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.sbt
+            ~/.coursier/cache
+            ~/.ivy2/cache
+          key: ${{ runner.os }}-sbt-docs-${{ hashFiles('**/*.sbt', '**/project/**/*.scala') }}
+          restore-keys: |
+            ${{ runner.os }}-sbt-docs-
+            ${{ runner.os }}-sbt-
+      - name: Generate Scaladoc for all modules
+        run: |
+          sbt -batch doc
+          # Try unified docs for Scala 2.13 modules; don't fail release if unidoc fails
+          sbt -batch unidoc || echo "unidoc failed (non-fatal)"
+      - name: Assemble site folder
+        run: |
+          mkdir -p public/api
+          for m in modules/*; do \
+            mod=$(basename "$m"); \
+            api_dir="$m/target/scala-2.13/api"; \
+            if [ -d "$api_dir" ]; then \
+              mkdir -p "public/api/$mod"; \
+              cp -R "$api_dir"/* "public/api/$mod"/; \
+            fi; \
+          done
+          # Root module (if any aggregated docs exist)
+          if [ -d target/scala-2.13/api ]; then \
+            mkdir -p public/api/root && cp -R target/scala-2.13/api/* public/api/root/; \
+          fi
+          # Unified docs (if present)
+          if [ -d target/scala-2.13/unidoc ] || [ -d target/scala-2.13/api-unidoc ]; then \
+            UNIDOC_DIR="$(ls -d target/scala-2.13/*unidoc 2>/dev/null | head -n1)"; \
+            if [ -n "$UNIDOC_DIR" ]; then \
+              mkdir -p public/api/unified && cp -R "$UNIDOC_DIR"/* public/api/unified/; \
+            fi; \
+          fi
+          # Add index
+          cat > public/index.html << 'EOF'
+          <!doctype html>
+          <html><head><meta charset="utf-8"><title>FlowForge API</title></head>
+          <body>
+            <h1>FlowForge API (Scaladoc)</h1>
+            <ul>
+              $(for d in api/*; do echo "<li><a href=\"$d/index.html\">$(basename "$d")</a></li>"; done)
+            </ul>
+          </body></html>
+          EOF
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: public
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
   create-release:
     name: Create GitHub Release
-    needs: [validate-release, pre-release-tests, build-artifacts]
+    needs: [validate-release, pre-release-tests, build-artifacts, publish-docs]
     runs-on: ubuntu-latest
     steps:
       - name: Checkout