ci: make doclint incremental and fix missing scaladoc in schema witness

Author: vim89

.github/workflows/ci.yml

@@ -86,12 +86,15 @@ jobs:
         id: docs_changes
         uses: dorny/paths-filter@v3
         with:
+          list-files: shell
           filters: |
             docs:
               - 'docs/**'
               - '**/*.md'
               - 'scripts/lint-docs.sh'
-              - 'scripts/doclint.sh'
+            api_scala:
+              - 'modules/core/src/main/**/*.scala'
+              - 'modules/contracts/src/main/**/*.scala'
       - name: Skip docs lint (no docs changes)
         if: steps.docs_changes.outputs.docs != 'true'
         run: echo "No docs changes detected; skipping docs lint."
@@ -102,7 +105,9 @@ jobs:
         if: steps.docs_changes.outputs.docs == 'true'
         run: bash scripts/lint-docs.sh
       - name: Scaladoc coverage lint
-        if: steps.docs_changes.outputs.docs == 'true'
+        if: steps.docs_changes.outputs.api_scala == 'true'
+        env:
+          DOC_LINT_FILES: ${{ steps.docs_changes.outputs.api_scala_files }}
         run: |
           chmod +x scripts/doclint.sh
           ./scripts/doclint.sh

modules/core/src/main/scala-2/com/flowforge/core/types/SchemaWitness.scala

@@ -45,6 +45,7 @@ import scala.annotation.implicitNotFound
 )
 sealed trait SchemaWitness[PipelineOut, Contract, Policy <: SchemaEvolutionPolicy]
 
+/** Companion with implicit evidence constructors for schema compatibility policies. */
 object SchemaWitness {
 
   // Type alias for migration - use SchemaConforms instead
@@ -121,8 +122,10 @@ object SchemaEvolutionPolicy {
 ║  🔧 Fix: Ensure all fields in subset exist in superset with same types.      ║
 ╚════════════════════════════════════════════════════════════════════════════════╝
 """)
+/** Evidence that `Subset` is contained within `Superset` at the HList field/type level. */
 trait SubsetSchema[Subset <: HList, Superset <: HList]
 
+/** Constructors for subset evidence used by backward/forward compatibility witnesses. */
 object SubsetSchema {
 
   /**

scripts/doclint.sh

@@ -8,33 +8,50 @@ set -euo pipefail
 ROOTS=(modules/core modules/contracts)
 MISS=0
 echo "🔎 Doc lint: scanning for missing Scaladoc on public declarations"
-for r in "${ROOTS[@]}"; do
-  while IFS= read -r -d '' f; do
-    lines=()
-    while IFS= read -r line; do
-      lines+=("$line")
-    done < <(nl -ba "$f")
-    for ((i=0; i<${#lines[@]}; i++)); do
-      L="${lines[$i]}"
-      # Match top-level public declarations (very simple heuristic)
-      if [[ "$L" =~ [[:space:]]+[0-9]+[[:space:]]+(trait|class|object)[[:space:]]+[A-Z][A-Za-z0-9_]*[[:space:]]*\{? ]]; then
-        # Look back a few lines for a /** ... */ opener
-        hasdoc=0
-        for b in 1 2 3 4 5; do
-          j=$((i-b))
-          if (( j >= 0 )); then
-            if [[ "${lines[$j]}" =~ \/\*\* ]]; then hasdoc=1; break; fi
-            if [[ "${lines[$j]}" =~ ^[[:space:]]*$ ]]; then continue; fi
-          fi
-        done
-        if (( hasdoc == 0 )); then
-          echo "⚠️  Missing Scaladoc: $f:${L%%$'\t'*}"
-          ((MISS++))
+scan_file() {
+  local f="$1"
+  lines=()
+  while IFS= read -r line; do
+    lines+=("$line")
+  done < <(nl -ba "$f")
+  for ((i=0; i<${#lines[@]}; i++)); do
+    L="${lines[$i]}"
+    # Match top-level public declarations (very simple heuristic)
+    if [[ "$L" =~ [[:space:]]+[0-9]+[[:space:]]+(trait|class|object)[[:space:]]+[A-Z][A-Za-z0-9_]*[[:space:]]*\{? ]]; then
+      # Look back a few lines for a /** ... */ opener
+      hasdoc=0
+      for b in 1 2 3 4 5; do
+        j=$((i-b))
+        if (( j >= 0 )); then
+          if [[ "${lines[$j]}" =~ \/\*\* ]]; then hasdoc=1; break; fi
+          if [[ "${lines[$j]}" =~ ^[[:space:]]*$ ]]; then continue; fi
         fi
+      done
+      if (( hasdoc == 0 )); then
+        echo "⚠️  Missing Scaladoc: $f:${L%%$'\t'*}"
+        ((MISS++))
       fi
-    done
-  done < <(find "$r" -type f -path "*/src/main/*" -name "*.scala" -print0)
-done
+    fi
+  done
+}
+
+if [[ -n "${DOC_LINT_FILES:-}" ]]; then
+  while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    [[ ! -f "$f" ]] && continue
+    case "$f" in
+      modules/core/src/main/*|modules/contracts/src/main/*)
+        scan_file "$f"
+        ;;
+    esac
+  done <<< "${DOC_LINT_FILES}"
+else
+  for r in "${ROOTS[@]}"; do
+    while IFS= read -r -d '' f; do
+      scan_file "$f"
+    done < <(find "$r" -type f -path "*/src/main/*" -name "*.scala" -print0)
+  done
+fi
 
 echo "Doclint: $MISS items missing Scaladoc"
 if (( MISS > 0 )); then