-
- # CodeBoarding [Diagram-First Documentation]
-
- [](https://github.com/marketplace/actions/codeboarding-diagram-first-documentation)
+
+ # CodeBoarding Architecture Review
+
+ Posts a PR comment with an architecture diagram showing which components changed (added/modified/removed) — green/yellow/red.
-Generates diagram-first visualizations of your codebase using static analysis and large language models.
+## What it does
+
+On every pull request, this action:
+
+1. Reads the `.codeboarding/analysis.json` committed at the PR base commit (the "before" snapshot).
+2. Runs an incremental analysis on the PR head — only LLM-calls components whose code actually changed, so a typical PR costs a handful of LLM calls and a docs-only PR costs none.
+3. Diffs the two analyses and renders the architecture diagram with changed components colored:
+ - **green** for added components,
+ - **yellow** for modified,
+ - **red** (dashed + hatched) for removed.
+4. Pushes the PNG to an orphan branch (`codeboarding-images`) in your repo and posts a sticky PR comment with the image.
## Usage
```yaml
-name: Generate Documentation
+name: Architecture review
on:
- push:
- branches: [ main ]
pull_request:
- branches: [ main ]
- types: [opened, synchronize, reopened]
+ types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+ pull-requests: write
+ contents: write # for pushing the rendered PNG to the image branch
jobs:
- documentation:
+ diagram:
runs-on: ubuntu-latest
+ if: github.event.pull_request.draft == false
+ timeout-minutes: 60
steps:
- - name: Checkout
- uses: actions/checkout@v4
+ - uses: codeboarding/codeboarding-action@v1
with:
- fetch-depth: 0 # Required to access branch history
-
- - name: Generate Documentation
- uses: codeboarding/codeboarding-ghaction@v1
- with:
- repository_url: ${{ github.server_url }}/${{ github.repository }}
- source_branch: ${{ github.head_ref || github.ref_name }}
- target_branch: ${{ github.base_ref || 'main' }}
- output_directory: 'docs'
- output_format: '.md'
-
- - name: Upload Documentation
- uses: actions/upload-artifact@v4
- with:
- name: documentation
- path: |
- docs/
- .codeboarding/
+ llm_api_key: ${{ secrets.OPENROUTER_API_KEY }}
```
+You need **one secret**: an LLM API key. OpenRouter is the default; pass your own model via `agent_model` / `parsing_model` inputs if you prefer.
+
## Inputs
-| Input | Description | Required | Default |
-|-------|-------------|----------|---------|
-| `repository_url` | Repository URL for which documentation will be generated | Yes | - |
-| `source_branch` | Source branch for comparison (typically the PR branch) | Yes | - |
-| `target_branch` | Target branch for comparison (typically the base branch) | Yes | - |
-| `output_directory` | Directory where documentation files will be saved | No | `docs` |
-| `output_format` | Format for documentation files (either `.md` or `.rst`) | No | `.md` |
+| Input | Default | Description |
+|---|---|---|
+| `llm_api_key` | (required) | LLM API key. Currently OpenRouter (`OPENROUTER_API_KEY`). |
+| `github_token` | `${{ github.token }}` | Token used to post the comment and push the image. |
+| `engine_ref` | `main` | Git ref of `CodeBoarding/CodeBoarding`. Pin in production. |
+| `depth_level` | `1` | Diagram depth (1–3). Higher = slower + more detail. |
+| `agent_model` | `openrouter/anthropic/claude-sonnet-4` | LLM for analysis. |
+| `parsing_model` | `openrouter/anthropic/claude-sonnet-4` | LLM for parsing. |
+| `image_branch` | `codeboarding-images` | Orphan branch where rendered PNGs are stored. |
+| `comment_header` | `Architecture review` | Header line of the PR comment. |
## Outputs
| Output | Description |
-|--------|-------------|
-| `markdown_files_created` | Number of documentation files created |
-| `json_files_created` | Number of JSON files created |
-| `output_directory` | Directory where documentation files were saved |
-| `json_directory` | Directory where JSON files were saved (always `.codeboarding`) |
-| `has_changes` | Whether any files were created or changed |
+|---|---|
+| `diff_png` | Path to the rendered PNG in the runner workspace. |
+| `diff_json` | Path to the computed diff JSON. |
+| `image_url` | Public raw URL of the uploaded PNG (empty on fork PRs). |
-## How It Works
+## Establishing the baseline
-The action works by:
+The action reads the `.codeboarding/analysis.json` that was committed at the PR base commit. If your repo has never been analyzed, the first PR will skip the diff and post a "no baseline yet" comment.
-1. Analyzing the differences introduced in the source branch and putting the results in the target branch
-2. Generating documentation files based on the latest version of the source branch
-3. Outputting two types of files:
- - Documentation files (Markdown or RST) in the specified output directory
- - Metadata files in the `.codeboarding` directory
+To create the baseline:
-## License
+1. Run the existing CodeBoarding docs workflow ([`CodeBoarding/.github/workflows/docs.yml`](https://github.com/CodeBoarding/CodeBoarding/blob/main/.github/workflows/docs.yml)) once on `main`. It commits a fresh `.codeboarding/analysis.json` to your repo.
+2. After that, every PR opened against `main` shows what changed.
-MIT License - see [LICENSE](LICENSE) file for details.
+We recommend a companion workflow that keeps the baseline fresh on every push to `main`. A pre-canned snippet for this is on the roadmap — see TODOs below.
-# CodeBoarding GitHub Action
+## Fork PRs
-## Important: Timeout Configuration
+PRs from forks cannot push to your image branch. The action still computes the diff and posts a comment, but without the rendered image. A maintainer can re-run the workflow from the Actions tab once they trust the PR.
-For large repositories, the analysis can take 15-45 minutes. Make sure to configure appropriate timeouts in your workflow:
+## Limitations (V1)
-```yaml
-jobs:
- generate-docs:
- runs-on: ubuntu-latest
- timeout-minutes: 60 # Set to 60+ minutes for large repositories
- steps:
- - uses: actions/checkout@v4
- - uses: your-username/codeboarding-ghaction@v1
- with:
- # your inputs here
-```
+- **Baseline must be committed.** If `.codeboarding/analysis.json` isn't in the repo at the PR base commit, the action posts a "no baseline" message and exits without rendering.
+- **Fork PRs get no image** (text-only summary instead).
+- **No focus / crop mode** for huge diagrams with tiny changes — the whole graph is rendered. Coming in V2.
+- **Re-clones the target repo** inside the analysis engine (legacy `generate_analysis()` API). One extra clone per run; harmless but measurable on huge repos.
+- **Image branch grows unbounded.** A scheduled cleanup workflow is on the roadmap.
+- **Webview bundle is committed in this repo** (`webview-dist/`). Until the upstream `CodeBoarding-vscode` repo ships its dist as a public release asset, rebuilding is a manual step: `cd CodeBoarding-vscode/webview-ui && npm ci && npm run build`, then copy `dist/` into this repo's `webview-dist/`.
+
+## TODOs (require changes outside this repo)
-## Timeout Guidelines
+The action vendors a few small pieces that should ideally live upstream. Each one is a clean refactor that would let us drop ~250 lines from `scripts/`:
-- **Small repositories** (<1k files): 10-15 minutes
-- **Medium repositories** (1k-5k files): 20-30 minutes
-- **Large repositories** (5k+ files): 30-60 minutes
-- **Very large repositories** (10k+ files): 45-90 minutes
+- **Move `diff_component_trees` from `CodeBoarding-wrapper/codeboarding_pro/diff/tree_diff.py` into `CodeBoarding/diagram_analysis/`.** It's ~140 lines of set arithmetic with no LLM logic and no wrapper-side dependencies (only depends on `ComponentJson`/`RelationJson` from core). The wrapper's `DiffService` orchestrator can stay; just move the algorithm.
+- **Expose a slim `analyze-only-this-checkout(repo_path, base_ref) -> analysis.json` entry point in core.** Today `generate_analysis()` re-clones the repo from a URL, which forces us to do a redundant clone even when the runner already has the code checked out.
+- **Add a `mode: baseline` entry point in this action** that publishes a refresh-on-push workflow snippet (so users get the companion workflow with one input flag instead of copy-paste).
+- **Bundle the webview-ui as a pre-built release asset** of the `CodeBoarding-vscode` repo so the action can download a small tarball instead of cloning + `npm ci` + `vite build` (~60s saved per cold run).
+- **Move image hosting off the consumer's repo** by adding a CodeBoarding-hosted `/render` endpoint. The action would POST the diff JSON and receive a hosted PNG URL — no orphan branch, no `contents: write` permission needed, fork PRs work.
+
+## License
-If your workflow consistently times out, consider:
-1. Increasing `timeout-minutes` to 90 or higher
-2. Running the action on a schedule during off-peak hours
-3. Analyzing specific branches with smaller diffs
+MIT — see [LICENSE](LICENSE).
diff --git a/action.yml b/action.yml
index 6f17d1d..1c84592 100644
--- a/action.yml
+++ b/action.yml
@@ -1,447 +1,540 @@
-name: 'CodeBoarding [Diagram-First Documentation]'
-description: 'Generates diagram-first visualizations of your codebase using static analysis and large language models.'
+name: 'CodeBoarding Architecture Review'
+description: 'Posts a PR comment with an architecture diagram showing which components changed (added/modified/removed).'
author: 'CodeBoarding'
branding:
- icon: 'book-open' # or 'layers', 'git-branch', 'book-open', 'target'
+ icon: 'git-pull-request'
color: 'blue'
inputs:
- output_directory:
- description: 'Directory where documentation files will be saved'
- required: false
- default: 'docs'
- repository_url:
- description: 'Repository URL to fetch documentation for (defaults to current repository)'
- required: true
- source_branch:
- description: 'Source branch for comparison'
- required: true
- target_branch:
- description: 'Target branch for comparison'
+ llm_api_key:
+ description: 'LLM API key (OpenRouter by default). Required.'
required: true
- output_format:
- description: 'Output format for documentation files (.md, .mdx, .rst, or .html)'
+ github_token:
+ description: 'GITHUB_TOKEN used to post the PR comment and (optionally) push the image. Defaults to the workflow token.'
+ required: false
+ default: ${{ github.token }}
+ engine_ref:
+ description: 'Git ref of CodeBoarding/CodeBoarding to use as the analysis engine.'
+ required: false
+ default: 'main'
+ depth_level:
+ description: 'Diagram depth (1-3). Higher is slower and more detailed.'
+ required: false
+ default: '1'
+ agent_model:
+ description: 'LLM model identifier used for analysis (passed through as AGENT_MODEL env var).'
required: false
- default: '.md'
+ default: 'openrouter/anthropic/claude-sonnet-4'
+ parsing_model:
+ description: 'LLM model identifier used for parsing (passed through as PARSING_MODEL env var).'
+ required: false
+ default: 'openrouter/anthropic/claude-sonnet-4'
+ image_branch:
+ description: 'Orphan branch in this repo where rendered diff PNGs are stored. Created on first run.'
+ required: false
+ default: 'codeboarding-images'
+ comment_header:
+ description: 'Header line used inside the sticky PR comment.'
+ required: false
+ default: 'Architecture review'
outputs:
- markdown_files_created:
- description: 'Number of Markdown files created'
- value: ${{ steps.process-docs.outputs.markdown_files_created }}
- json_files_created:
- description: 'Number of JSON files created'
- value: ${{ steps.process-docs.outputs.json_files_created }}
- output_directory:
- description: 'Directory where Markdown files were saved'
- value: ${{ steps.process-docs.outputs.output_directory }}
- json_directory:
- description: 'Directory where JSON files were saved (.codeboarding)'
- value: ${{ steps.process-docs.outputs.json_directory }}
- has_changes:
- description: 'Whether any files were created or changed'
- value: ${{ steps.process-docs.outputs.has_changes }}
- repo_url:
- description: 'Repository URL that was analyzed'
- value: ${{ steps.repo-url.outputs.repo_url }}
+ diff_png:
+ description: 'Path to the rendered diff PNG (in the runner workspace).'
+ value: ${{ steps.render.outputs.png_path }}
+ diff_json:
+ description: 'Path to the computed diff JSON.'
+ value: ${{ steps.diff.outputs.json_path }}
+ image_url:
+ description: 'Public URL of the uploaded diff image (empty if upload skipped, e.g. on fork PRs).'
+ value: ${{ steps.upload.outputs.image_url }}
runs:
using: 'composite'
steps:
- - name: Determine repository URL
- id: repo-url
+ - name: Guard — PR event only
+ id: guard
shell: bash
run: |
- # Use the provided repository URL if it's not empty
- if [ -n "${{ inputs.repository_url }}" ]; then
- REPO_URL="${{ inputs.repository_url }}"
- echo "Using provided repository URL: $REPO_URL"
- # Otherwise try to determine from git if we're in a git repository
- elif git config --get remote.origin.url > /dev/null 2>&1; then
- REPO_URL=$(git config --get remote.origin.url)
- # Convert SSH URL to HTTPS if needed
- if [[ $REPO_URL == git@* ]]; then
- REPO_URL=$(echo $REPO_URL | sed 's|git@github.com:|https://github.com/|')
- fi
- echo "Using git remote URL: $REPO_URL"
+ if [ -z "${{ github.event.pull_request.number }}" ]; then
+ echo "::warning::CodeBoarding Architecture Review only runs on pull_request events. Skipping."
+ echo "skip=true" >> $GITHUB_OUTPUT
else
- REPO_URL="${{ github.server_url }}/${{ github.repository }}"
- echo "Using GitHub context URL: $REPO_URL"
+ # Fork PRs: head repo != base repo. We can't push to the base repo
+ # from a fork-triggered workflow, so we skip the image-hosting step
+ # and post a text-only fallback comment.
+ if [ "${{ github.event.pull_request.head.repo.full_name }}" != "${{ github.repository }}" ]; then
+ echo "is_fork=true" >> $GITHUB_OUTPUT
+ else
+ echo "is_fork=false" >> $GITHUB_OUTPUT
+ fi
+ echo "skip=false" >> $GITHUB_OUTPUT
+ echo "base_sha=${{ github.event.pull_request.base.sha }}" >> $GITHUB_OUTPUT
+ echo "head_sha=${{ github.event.pull_request.head.sha }}" >> $GITHUB_OUTPUT
+ echo "pr_number=${{ github.event.pull_request.number }}" >> $GITHUB_OUTPUT
fi
- echo "repo_url=$REPO_URL" >> $GITHUB_OUTPUT
- - name: Create and poll documentation job
- id: fetch-docs
+ - name: Checkout CodeBoarding engine
+ if: steps.guard.outputs.skip != 'true'
+ uses: actions/checkout@v4
+ with:
+ repository: CodeBoarding/CodeBoarding
+ ref: ${{ inputs.engine_ref }}
+ path: codeboarding-engine
+
+ - name: Checkout target repository (PR head)
+ if: steps.guard.outputs.skip != 'true'
+ uses: actions/checkout@v4
+ with:
+ path: target-repo
+ fetch-depth: 0
+ ref: ${{ steps.guard.outputs.head_sha }}
+
+ - name: Ensure PR base commit is fetched
+ if: steps.guard.outputs.skip != 'true'
shell: bash
+ working-directory: target-repo
run: |
- CREATE_JOB_URL="https://server.codeboarding.org/github_action/jobs"
- REPO_URL="${{ steps.repo-url.outputs.repo_url }}"
- SOURCE_BRANCH="${{ inputs.source_branch }}"
- TARGET_BRANCH="${{ inputs.target_branch }}"
- OUTPUT_DIRECTORY="${{ inputs.output_directory }}"
- OUTPUT_FORMAT="${{ inputs.output_format }}"
-
- echo "🚀 Creating CodeBoarding analysis job...$CREATE_JOB_URL"
- echo "📊 Repository: $REPO_URL"
- echo "🌿 Source branch: $SOURCE_BRANCH"
- echo "🎯 Target branch: $TARGET_BRANCH"
- echo "📄 Output format: $OUTPUT_FORMAT"
-
- # Create JSON payload
- JSON_PAYLOAD=$(jq -n \
- --arg url "$REPO_URL" \
- --arg source_branch "$SOURCE_BRANCH" \
- --arg target_branch "$TARGET_BRANCH" \
- --arg output_directory "$OUTPUT_DIRECTORY" \
- --arg extension "$OUTPUT_FORMAT" \
- '{
- url: $url,
- source_branch: $source_branch,
- target_branch: $target_branch,
- output_directory: $output_directory,
- extension: $extension
- }')
-
- echo "📋 Request payload:"
- echo "$JSON_PAYLOAD"
-
- # Create temporary file for response
- TEMP_FILE=$(mktemp)
-
- echo "🌐 Making API request to create job..."
-
- # Make the API call to create job
- response=$(curl -s -w "%{http_code}" -o "$TEMP_FILE" \
- -X POST \
- -H "Content-Type: application/json" \
- -d "$JSON_PAYLOAD" \
- --max-time 60 \
- --connect-timeout 30 \
- "$CREATE_JOB_URL")
- curl_exit_code=$?
-
- http_code=${response: -3}
-
- echo "✅ Job creation request completed!"
- echo "📋 Response status code: $http_code"
- echo "🔧 Curl exit code: $curl_exit_code"
-
- # Handle curl errors
- if [ $curl_exit_code -ne 0 ]; then
- echo "❌ Error: Curl failed with exit code $curl_exit_code"
- case $curl_exit_code in
- 6) echo "🌐 Couldn't resolve host - check network connectivity" ;;
- 7) echo "🔌 Failed to connect to host - server might be down" ;;
- 28) echo "⏰ Request timed out - server might be busy" ;;
- *) echo "❓ Unknown curl error - check network and server status" ;;
- esac
- rm -f "$TEMP_FILE"
- exit 1
+ # actions/checkout@v4 with fetch-depth: 0 already grabs all branches,
+ # but the base SHA may be unreachable from head on stacked / fork PRs.
+ git fetch origin "${{ steps.guard.outputs.base_sha }}" --depth=1 || true
+ git cat-file -e "${{ steps.guard.outputs.base_sha }}" && echo "Base commit reachable." || \
+ (echo "::error::Base commit ${{ steps.guard.outputs.base_sha }} is not reachable." && exit 1)
+
+ - name: Set up Python 3.13
+ if: steps.guard.outputs.skip != 'true'
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.13'
+
+ - name: Set up Node.js 20
+ if: steps.guard.outputs.skip != 'true'
+ uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+
+ - name: Install uv
+ if: steps.guard.outputs.skip != 'true'
+ uses: astral-sh/setup-uv@v4
+
+ - name: Cache uv venv (engine)
+ if: steps.guard.outputs.skip != 'true'
+ uses: actions/cache@v4
+ with:
+ path: codeboarding-engine/.venv
+ key: cb-uv-${{ runner.os }}-${{ hashFiles('codeboarding-engine/pyproject.toml', 'codeboarding-engine/uv.lock') }}
+ restore-keys: |
+ cb-uv-${{ runner.os }}-
+
+ - name: Cache LSP servers
+ if: steps.guard.outputs.skip != 'true'
+ uses: actions/cache@v4
+ with:
+ path: |
+ codeboarding-engine/static_analyzer/servers/node_modules
+ codeboarding-engine/static_analyzer/servers/bin
+ key: cb-lsp-${{ runner.os }}-v1
+ restore-keys: |
+ cb-lsp-${{ runner.os }}-
+
+ - name: Cache Playwright browsers
+ if: steps.guard.outputs.skip != 'true'
+ uses: actions/cache@v4
+ with:
+ path: ~/.cache/ms-playwright
+ key: cb-playwright-${{ runner.os }}-v1
+
+ - name: Install Python dependencies
+ if: steps.guard.outputs.skip != 'true'
+ shell: bash
+ working-directory: codeboarding-engine
+ run: |
+ uv venv --clear
+ uv pip install -e .
+
+ - name: Install LSP servers
+ if: steps.guard.outputs.skip != 'true'
+ shell: bash
+ working-directory: codeboarding-engine
+ run: |
+ uv run python install.py --auto-install-npm
+
+ - name: Seed base analysis.json (from PR base commit)
+ if: steps.guard.outputs.skip != 'true'
+ id: base
+ shell: bash
+ working-directory: target-repo
+ run: |
+ BASE_SHA="${{ steps.guard.outputs.base_sha }}"
+ BASE_SEED_DIR=$(mktemp -d)
+ if git show "${BASE_SHA}:.codeboarding/analysis.json" > "${BASE_SEED_DIR}/analysis.json" 2>/dev/null; then
+ # Also copy manifest + static_analysis.pkl if present (manifest is
+ # harmless if absent; pkl avoids IncrementalCacheMissingError).
+ git show "${BASE_SHA}:.codeboarding/analysis_manifest.json" > "${BASE_SEED_DIR}/analysis_manifest.json" 2>/dev/null || true
+ git show "${BASE_SHA}:.codeboarding/static_analysis.pkl" > "${BASE_SEED_DIR}/static_analysis.pkl" 2>/dev/null && \
+ echo "Seeded static_analysis.pkl from base" || \
+ (rm -f "${BASE_SEED_DIR}/static_analysis.pkl"; echo "No static_analysis.pkl at base; full re-cluster will run")
+ echo "found=true" >> $GITHUB_OUTPUT
+ echo "seed_dir=${BASE_SEED_DIR}" >> $GITHUB_OUTPUT
+ echo "Base analysis seeded into ${BASE_SEED_DIR}"
+ else
+ rm -rf "${BASE_SEED_DIR}"
+ echo "found=false" >> $GITHUB_OUTPUT
+ echo "::warning::No .codeboarding/analysis.json at PR base commit ${BASE_SHA}. First-run mode."
fi
-
- if [ "$http_code" != "202" ]; then
- echo "❌ Error: Job creation failed with status code $http_code"
- echo "📄 Response content:"
- cat "$TEMP_FILE"
-
- # Try to parse as JSON for better error message
- if jq -e '.detail' "$TEMP_FILE" > /dev/null 2>&1; then
- echo "🔍 Error details: $(jq -r '.detail' "$TEMP_FILE")"
- fi
-
- rm -f "$TEMP_FILE"
+
+ - name: Run CodeBoarding analysis (PR head)
+ if: steps.guard.outputs.skip != 'true' && steps.base.outputs.found == 'true'
+ id: analyze
+ shell: bash
+ working-directory: codeboarding-engine
+ env:
+ OPENROUTER_API_KEY: ${{ inputs.llm_api_key }}
+ AGENT_MODEL: ${{ inputs.agent_model }}
+ PARSING_MODEL: ${{ inputs.parsing_model }}
+ STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
+ PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
+ DIAGRAM_DEPTH_LEVEL: ${{ inputs.depth_level }}
+ CACHING_DOCUMENTATION: 'false'
+ ENABLE_MONITORING: 'false'
+ run: |
+ if [ -z "$OPENROUTER_API_KEY" ]; then
+ echo "::error::OPENROUTER_API_KEY is empty. Set it as a repo secret and pass via the 'llm_api_key' input."
exit 1
fi
-
- # Check if response is valid JSON
- if ! jq empty "$TEMP_FILE" 2>/dev/null; then
- echo "❌ Error: Invalid JSON response"
- echo "📄 Response content:"
- cat "$TEMP_FILE"
- rm -f "$TEMP_FILE"
+
+ # Strip whitespace and surrounding quotes — pasting a key into the
+ # GitHub secret UI often picks up trailing newlines or wrap-around
+ # quotes from `KEY=value` lines, both of which break Bearer auth.
+ _strip() {
+ printf '%s' "$1" | tr -d '[:space:]' | sed -e 's/^"//;s/"$//' -e "s/^'//;s/'\$//"
+ }
+ OPENROUTER_API_KEY="$(_strip "$OPENROUTER_API_KEY")"; export OPENROUTER_API_KEY
+ AGENT_MODEL="$(_strip "$AGENT_MODEL")"; export AGENT_MODEL
+ PARSING_MODEL="$(_strip "$PARSING_MODEL")"; export PARSING_MODEL
+
+ # If the user pasted `OPENROUTER_API_KEY=sk-...` (whole env line)
+ # into the secret UI, drop the prefix.
+ case "$OPENROUTER_API_KEY" in
+ OPENROUTER_API_KEY=*) OPENROUTER_API_KEY="${OPENROUTER_API_KEY#OPENROUTER_API_KEY=}";;
+ openrouter_api_key=*) OPENROUTER_API_KEY="${OPENROUTER_API_KEY#openrouter_api_key=}";;
+ esac
+ OPENROUTER_API_KEY="$(_strip "$OPENROUTER_API_KEY")"; export OPENROUTER_API_KEY
+
+ KEY_LEN=${#OPENROUTER_API_KEY}
+ case "$OPENROUTER_API_KEY" in
+ sk-or-v1-*) KEY_PREFIX_OK=1 ;;
+ *) KEY_PREFIX_OK=0 ;;
+ esac
+ echo "OPENROUTER_API_KEY length after strip: $KEY_LEN chars; prefix-looks-like-OpenRouter: $KEY_PREFIX_OK"
+ AUTH_STATUS=$(curl -sS -o /tmp/openrouter-auth.json -w "%{http_code}" \
+ -H "Authorization: Bearer $OPENROUTER_API_KEY" \
+ --max-time 10 \
+ https://openrouter.ai/api/v1/auth/key || echo "curl-fail")
+ echo "OpenRouter /auth/key response: HTTP $AUTH_STATUS"
+ if [ "$AUTH_STATUS" != "200" ]; then
+ echo "::error::OpenRouter rejected the API key (HTTP $AUTH_STATUS). Verify the OPENROUTER_API_KEY secret value."
+ cat /tmp/openrouter-auth.json 2>/dev/null || true
exit 1
fi
-
- # Extract job_id from response
- JOB_ID=$(jq -r '.job_id' "$TEMP_FILE")
-
- if [ "$JOB_ID" = "null" ] || [ -z "$JOB_ID" ]; then
- echo "❌ Error: No job_id found in response"
- echo "📄 Response content:"
- cat "$TEMP_FILE"
- rm -f "$TEMP_FILE"
+
+ TARGET_REPO="${{ github.workspace }}/target-repo"
+ SEED_DIR="${{ steps.base.outputs.seed_dir }}"
+ BASE_SHA="${{ steps.guard.outputs.base_sha }}"
+ HEAD_SHA="${{ steps.guard.outputs.head_sha }}"
+ REPO_NAME="${{ github.event.repository.name }}"
+ RUN_ID="${{ github.run_id }}-${{ github.run_attempt }}"
+
+ # Use run_incremental against the already-checked-out PR head.
+ # On IncrementalCacheMissingError (legacy pkl, tiny repo with no
+ # cluster baseline, first-ever incremental run) fall back to a full
+ # run — yields a fresh analysis.json that we can still diff against
+ # the base SHA's analysis.json.
+ uv run python -c "
+ from pathlib import Path
+ from codeboarding_workflows.analysis import run_incremental, run_full
+ from diagram_analysis.exceptions import IncrementalCacheMissingError
+ try:
+ result = run_incremental(
+ repo_path=Path('$TARGET_REPO'),
+ output_dir=Path('$SEED_DIR'),
+ project_name='$REPO_NAME',
+ run_id='$RUN_ID',
+ log_path='/tmp/cb-analysis.log',
+ base_ref='$BASE_SHA',
+ target_ref='$HEAD_SHA',
+ source_sha='$HEAD_SHA',
+ )
+ except IncrementalCacheMissingError as exc:
+ print(f'Incremental unavailable ({exc}); falling back to full analysis.')
+ # Wipe the seed dir so run_full starts clean (it picks up
+ # depth_level from env / default).
+ for p in Path('$SEED_DIR').glob('*'):
+ if p.is_file():
+ p.unlink()
+ result = run_full(
+ repo_name='$REPO_NAME',
+ repo_path=Path('$TARGET_REPO'),
+ output_dir=Path('$SEED_DIR'),
+ run_id='$RUN_ID',
+ log_path='/tmp/cb-analysis.log',
+ depth_level=int('${{ inputs.depth_level }}'),
+ source_sha='$HEAD_SHA',
+ )
+ print(f'Wrote: {result}')
+ "
+
+ if [ ! -f "$SEED_DIR/analysis.json" ]; then
+ echo "::error::Analysis ran but $SEED_DIR/analysis.json is missing."
exit 1
fi
-
- echo "✅ Job created successfully!"
- echo "🆔 Job ID: $JOB_ID"
-
- # Start polling job status
- STATUS_URL="https://server.codeboarding.org/github_action/jobs/$JOB_ID"
-
- echo "📊 Starting job status polling..."
- echo "⏰ This may take 15-45 minutes for large repositories..."
- echo "💡 If your workflow times out, increase 'timeout-minutes' in your job configuration"
-
- # Polling loop
- POLL_COUNT=0
- MAX_POLLS=90 # 90 minutes max (90 * 1 minute intervals)
-
- while [ $POLL_COUNT -lt $MAX_POLLS ]; do
- POLL_COUNT=$((POLL_COUNT + 1))
-
- echo "🔍 Polling attempt $POLL_COUNT of $MAX_POLLS ($(date '+%H:%M:%S'))"
-
- # Make status check API call
- response=$(curl -s -w "%{http_code}" -o "$TEMP_FILE" \
- --max-time 30 \
- --connect-timeout 10 \
- "$STATUS_URL")
-
- curl_exit_code=$?
- http_code=${response: -3}
-
- # Handle curl errors
- if [ $curl_exit_code -ne 0 ]; then
- echo "⚠️ Warning: Status check failed with curl exit code $curl_exit_code"
- echo "🔄 Retrying in 30 seconds..."
- sleep 30
- continue
- fi
-
- if [ "$http_code" != "200" ]; then
- echo "⚠️ Warning: Status check failed with HTTP code $http_code"
- echo "📄 Response content:"
- cat "$TEMP_FILE"
- echo "🔄 Retrying in 30 seconds..."
- sleep 30
- continue
- fi
-
- # Check if response is valid JSON
- if ! jq empty "$TEMP_FILE" 2>/dev/null; then
- echo "⚠️ Warning: Invalid JSON response"
- echo "📄 Response content:"
- cat "$TEMP_FILE"
- echo "🔄 Retrying in 30 seconds..."
- sleep 30
- continue
- fi
-
- # Extract status from response
- STATUS=$(jq -r '.status' "$TEMP_FILE")
-
- echo "📊 Current job status: $STATUS"
-
- if [ "$STATUS" = "COMPLETED" ]; then
- echo "✅ Job completed successfully!"
-
- # Check if result field exists and contains files
- if jq -e '.result' "$TEMP_FILE" > /dev/null; then
- echo "📦 Result field found, preparing output..."
-
- # Check if result is a JSON string or already a JSON object
- RESULT_TYPE=$(jq -r '.result | type' "$TEMP_FILE")
-
- if [ "$RESULT_TYPE" = "string" ]; then
- echo "🔧 Result is a JSON string, parsing it..."
- # Parse the JSON string in the result field
- jq -r '.result' "$TEMP_FILE" | jq '.' > "${TEMP_FILE}_result"
- else
- echo "🔧 Result is already a JSON object, extracting it..."
- # Extract the result object directly
- jq '.result' "$TEMP_FILE" > "${TEMP_FILE}_result"
- fi
-
- # Verify the extracted result
- if jq -e '.files' "${TEMP_FILE}_result" > /dev/null; then
- echo "✅ Files extracted successfully"
- mv "${TEMP_FILE}_result" "$TEMP_FILE"
- echo "response_file=$TEMP_FILE" >> $GITHUB_OUTPUT
- exit 0 # Successfully extracted files, exit with success
- else
- echo "❌ Error: Extracted result is missing files structure"
- echo "📄 Extracted content:"
- cat "${TEMP_FILE}_result"
- rm -f "${TEMP_FILE}_result" "$TEMP_FILE"
- exit 1
- fi
- else
- echo "❌ Error: Job completed but no result or result.files found in response"
- echo "📄 Response structure:"
- jq '.' "$TEMP_FILE"
-
- # If result exists, show what it contains
- if jq -e '.result' "$TEMP_FILE" > /dev/null; then
- echo "📄 Result field content:"
- RESULT_TYPE=$(jq -r '.result | type' "$TEMP_FILE")
- echo "Result type: $RESULT_TYPE"
-
- if [ "$RESULT_TYPE" = "string" ]; then
- echo "Result string content:"
- jq -r '.result' "$TEMP_FILE"
- else
- echo "Result object content:"
- jq '.result' "$TEMP_FILE"
- fi
- fi
-
- rm -f "$TEMP_FILE"
- exit 1
- fi
- elif [ "$STATUS" = "FAILED" ] || [ "$STATUS" = "ERROR" ]; then
- echo "❌ Job failed with status: $STATUS"
- echo "📄 Response content:"
- cat "$TEMP_FILE"
- rm -f "$TEMP_FILE"
- exit 1
- else
- # Job still in progress
- echo "⏳ Job in progress (status: $STATUS)..."
-
- # Show additional progress information if available
- if jq -e '.updated_at' "$TEMP_FILE" > /dev/null; then
- UPDATED_AT=$(jq -r '.updated_at' "$TEMP_FILE")
- echo "🕐 Last updated: $UPDATED_AT"
- fi
-
- echo "💤 Waiting 15 seconds before next check..."
- sleep 15
- fi
- done
-
- # Only reach here if we've exceeded max polls without completion
- echo "❌ Error: Job polling timed out after $MAX_POLLS attempts"
- echo "🏗️ The repository analysis is taking longer than expected."
- echo "📊 This might be due to:"
- echo " • Very large repository size (>10k files)"
- echo " • Complex codebase requiring extensive analysis"
- echo " • Server load or processing delays"
- echo ""
- echo "💡 Suggestions:"
- echo " • Try again later when server load might be lower"
- echo " • Consider analyzing smaller branches or specific directories"
- echo " • Increase your GitHub Actions job timeout-minutes to 120+"
- echo " • Contact support if the issue persists"
-
- rm -f "$TEMP_FILE"
- exit 1
-
- - name: Process documentation files
- id: process-docs
+ echo "current_analysis=$SEED_DIR/analysis.json" >> $GITHUB_OUTPUT
+
+ # Run health checks; persist counts + a couple of sample findings
+ # to /tmp/health.json so the comment-build step can surface them.
+ uv run python -c "
+ import json
+ from pathlib import Path
+ # check_name -> short human phrase used in the inline examples
+ LABELS = {
+ 'circular_dependencies': 'circular dependency',
+ 'god_classes': 'god class',
+ 'function_size': 'oversized function',
+ 'fan_out': 'high fan-out',
+ 'fan_in': 'high fan-in',
+ 'package_instability': 'unstable package',
+ 'inheritance_depth': 'deep inheritance hierarchy',
+ 'unused_code_diagnostics': 'unused code',
+ }
+ def humanize(check_name: str) -> str:
+ return LABELS.get(check_name, check_name.replace('_', ' '))
+ def display_name(entity) -> str:
+ # Prefer the last identifier-like segment of the qualified name.
+ # Filter out placeholders like '