chore(mcp): rebuild documentation database

.github/actions/build-framework-docs/action.yml

@@ -0,0 +1,205 @@
+name: Build framework documentation
+description: >
+  Runs the documentation pipeline for a single framework (export → inject → rewrite →
+  compress) and uploads the compressed docs and updated baseline as artifacts.
+  Deliberately stops before build:db — the database must be assembled once, from all
+  frameworks at the same time, or it ends up containing only this one.
+
+inputs:
+  framework:
+    description: angular | react | blazor | webcomponents
+    required: true
+  mode:
+    description: incremental | full
+    required: true
+  model:
+    description: Compression model override. Empty uses the compress scripts' default.
+    required: false
+    default: ""
+  submodule-branch:
+    description: Branch to move the documentation submodules to.
+    required: true
+    default: master
+  openai-api-key:
+    description: OpenAI API key used by the compression step.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/checkout@v6
+
+    # Deliberately not `submodules: recursive` — that also clones blazor/api-docs,
+    # blazor/igniteui-blazor and react/igniteui-react. api-docs is a private repository
+    # the default token cannot read, and none of the three are used by the documentation
+    # pipeline. Only the sources this framework reads are checked out.
+    - name: Check out documentation submodules
+      shell: bash
+      env:
+        FW: ${{ inputs.framework }}
+      run: |
+        set -euo pipefail
+        BASE=packages/igniteui-mcp/igniteui-doc-mcp
+        case "$FW" in
+          angular)
+            SUBS="angular/igniteui-docfx angular/igniteui-angular-samples angular/igniteui-angular-examples" ;;
+          react)
+            SUBS="common/igniteui-xplat-docs react/igniteui-react-examples" ;;
+          blazor)
+            SUBS="common/igniteui-xplat-docs blazor/igniteui-blazor-examples" ;;
+          webcomponents)
+            SUBS="common/igniteui-xplat-docs webcomponents/igniteui-wc-examples" ;;
+          *)
+            echo "::error::Unknown framework '$FW'"; exit 1 ;;
+        esac
+        for sub in $SUBS; do
+          echo "--- $sub ---"
+          git submodule update --init "$BASE/$sub"
+        done
+
+    # Node 24, not 22: rewrite-api-links.ts uses URLPattern, which only became a
+    # global in Node 24. On 22 it fails with "URLPattern is not defined".
+    - uses: actions/setup-node@v6
+      with:
+        node-version: 24.x
+        cache: yarn
+
+    # The cross-platform gulp build restores the docfx dotnet tool.
+    - uses: actions/setup-dotnet@v6
+      if: inputs.framework != 'angular'
+      with:
+        dotnet-version: 8.x
+
+    - name: Install packages
+      shell: bash
+      run: yarn --frozen-lockfile
+
+    - name: Move submodules to ${{ inputs.submodule-branch }}
+      shell: bash
+      working-directory: packages/igniteui-mcp/igniteui-doc-mcp
+      run: ./switch-submodules.sh "${{ inputs.submodule-branch }}"
+
+    - name: Configure OpenAI credentials
+      shell: bash
+      working-directory: packages/igniteui-mcp/igniteui-doc-mcp
+      run: echo "OPENAI_API_KEY=${{ inputs.openai-api-key }}" > .env
+
+    # dist/ is gitignored, so an incremental run starts with no compressed docs at all.
+    # Incremental compression only writes the files that changed, so without this the
+    # artifact would contain a handful of docs instead of the full set.
+    - name: Restore compressed docs from the committed DB
+      if: inputs.mode == 'incremental'
+      shell: bash
+      working-directory: packages/igniteui-mcp/igniteui-doc-mcp
+      run: npx tsx scripts/restore-docs-final.ts --framework "${{ inputs.framework }}"
+
+    - name: Build documentation
+      shell: bash
+      working-directory: packages/igniteui-mcp/igniteui-doc-mcp
+      env:
+        FW: ${{ inputs.framework }}
+        MODE: ${{ inputs.mode }}
+        COMPRESS_MODEL: ${{ inputs.model }}
+      run: |
+        set -euo pipefail
+
+        # Only the xplat gulp target uses an abbreviated name.
+        case "$FW" in
+          webcomponents) XPLAT="wc" ;;
+          angular)       XPLAT="" ;;
+          *)             XPLAT="$FW" ;;
+        esac
+
+        if [ "$MODE" = "full" ]; then
+          npm run "clear:$FW"
+        else
+          npm run clear:build
+        fi
+
+        if [ -n "$XPLAT" ]; then
+          npm run "build:xplat-$XPLAT"
+        fi
+
+        npm run "export:$FW"
+        npm run "inject:$FW"
+        npm run "rewrite-api-urls:$FW"
+
+        if [ "$MODE" = "full" ]; then
+          npm run "compress:$FW" -- --batch submit
+          npm run "compress:$FW" -- --batch poll
+          npm run "derive-components:$FW"
+          npx tsx scripts/update-baseline.ts --framework "$FW" --full
+        else
+          npm run "diff:$FW"
+          # An empty manifest means nothing changed upstream. batchSubmit exits without
+          # writing _batch_state.json, which would make the subsequent poll fail, so
+          # skip compression entirely — the restored docs are already current.
+          CHANGED=$(node -e "const m=require('./dist/diff-manifest.json');console.log((m.changed||[]).length+(m.added||[]).length)")
+          echo "Manifest reports $CHANGED changed/added document(s)"
+          if [ "$CHANGED" -gt 0 ]; then
+            npm run "compress:$FW" -- --batch submit --manifest dist/diff-manifest.json
+            npm run "compress:$FW" -- --batch poll
+            # Only the freshly compressed docs need it; restored ones already carry
+            # derived values from the committed DB.
+            npm run "derive-components:$FW"
+          fi
+          npm run "update-baseline:$FW"
+        fi
+
+        # Compression must yield one document per input. A batch entry that fails is
+        # simply absent from docs_final — the pipeline continues, the DB is published
+        # short, and document-count floors are far too loose to notice one missing file.
+        # This is not hypothetical: a full run reported "375 succeeded, 1 failed" and
+        # silently dropped hierarchicalgrid-editing.md.
+        IN=$(find "dist/docs_prepeared/$FW" -name '*.md' -not -name '_*' | wc -l)
+        OUT=$(find "dist/docs_final/$FW" -name '*.md' -not -name '_*' | wc -l)
+        if [ "$OUT" -lt "$IN" ]; then
+          echo "::warning::$FW: $OUT of $IN documents present after compression — retrying failed batch entries"
+          # `--batch retry` only submits a new batch; polling downloads its results.
+          # batchPoll reads state.retry_batch_id, so it follows the retry batch.
+          if npm run "compress:$FW" -- --batch retry; then
+            npm run "compress:$FW" -- --batch poll || true
+            npm run "derive-components:$FW" || true
+          fi
+          OUT=$(find "dist/docs_final/$FW" -name '*.md' -not -name '_*' | wc -l)
+        fi
+        if [ "$OUT" -lt "$IN" ]; then
+          echo "::error::$FW: compression produced only $OUT of $IN documents. Refusing to publish an incomplete set."
+          comm -23 \
+            <(find "dist/docs_prepeared/$FW" -name '*.md' -not -name '_*' -printf '%f\n' | sort) \
+            <(find "dist/docs_final/$FW" -name '*.md' -not -name '_*' -printf '%f\n' | sort)
+          exit 1
+        fi
+        echo "$FW: $OUT of $IN documents compressed"
+
+    # Always runs, so a framework that skipped compression still reports why.
+    - name: Report build summary
+      if: always()
+      shell: bash
+      working-directory: packages/igniteui-mcp/igniteui-doc-mcp
+      run: |
+        npx tsx scripts/report-build-summary.ts \
+          --framework "${{ inputs.framework }}" \
+          --mode "${{ inputs.mode }}" >> "$GITHUB_STEP_SUMMARY"
+
+    - name: Upload compressed docs
+      uses: actions/upload-artifact@v7
+      with:
+        name: docs-final-${{ inputs.framework }}
+        path: packages/igniteui-mcp/igniteui-doc-mcp/dist/docs_final/${{ inputs.framework }}
+        retention-days: 5
+
+    # build-db reads _tocName from here. Without it every row's toc_name would be NULL.
+    - name: Upload prepared docs
+      uses: actions/upload-artifact@v7
+      with:
+        name: docs-prepeared-${{ inputs.framework }}
+        path: packages/igniteui-mcp/igniteui-doc-mcp/dist/docs_prepeared/${{ inputs.framework }}
+        retention-days: 5
+
+    - name: Upload updated baseline
+      uses: actions/upload-artifact@v7
+      with:
+        name: docs-baseline-${{ inputs.framework }}
+        path: packages/igniteui-mcp/igniteui-doc-mcp/docs_baseline/${{ inputs.framework }}
+        retention-days: 5