Skip to content

docs(collections): say follower counts arrive in response collections[] #3919

docs(collections): say follower counts arrive in response collections[]

docs(collections): say follower counts arrive in response collections[] #3919

name: Check Schema Links in Docs
on:
pull_request:
branches: [main]
paths:
- 'docs/**/*.mdx'
- 'docs/**/*.md'
jobs:
check-schema-links:
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- uses: actions/checkout@v7.0.1
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: Check for stale schema version references
id: stale-check
run: |
# Get current major version from package.json (e.g., 3.0.0-rc.2 -> 3)
CURRENT_MAJOR=$(node -p "require('./package.json').version.split('.')[0]")
echo "Current major version: $CURRENT_MAJOR"
STALE_FOUND=""
for v in $(seq 1 $((CURRENT_MAJOR - 1))); do
# Search docs/ for /schemas/v{old}/ references, excluding release-notes
MATCHES=$(grep -rn "schemas/v${v}/" docs/ --include='*.md' --include='*.mdx' | grep -v 'docs/reference/release-notes' || true)
if [ -n "$MATCHES" ]; then
STALE_FOUND="$STALE_FOUND\n$MATCHES"
fi
done
if [ -n "$STALE_FOUND" ]; then
echo "❌ Found stale schema version references in docs/ (current major version is v${CURRENT_MAJOR}):"
echo -e "$STALE_FOUND"
echo ""
echo "These should be updated to schemas/v${CURRENT_MAJOR}/"
echo "If these are intentional historical references, move them to docs/reference/release-notes.mdx"
exit 1
else
echo "✅ No stale schema version references found"
fi
- name: Check schema links
id: check
env:
PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
run: |
# Extract schema URLs from docs and validate them
# Schema URLs look like: https://adcontextprotocol.org/schemas/v3/media-buy/sync-audiences-request.json
ERRORS=""
WARNINGS=""
# Get current version from package.json
CURRENT_VERSION=$(node -p "require('./package.json').version")
echo "Current version: $CURRENT_VERSION"
# Find all schema URLs in docs (excluding dist/docs which are versioned snapshots)
# Note: Use [^"')`] instead of [^")\s] for grep compatibility
# The backtick is needed to handle markdown links like [`url`](url)
SCHEMA_URLS=$(grep -rhoE 'https://adcontextprotocol\.org/schemas/(v[0-9]+|latest)/[^"'"'"')\` ]+\.json' docs/ 2>/dev/null | sort -u || true)
if [ -z "$SCHEMA_URLS" ]; then
echo "No schema URLs found in docs/"
echo "has_issues=false" >> $GITHUB_OUTPUT
exit 0
fi
echo "Found schema URLs:"
echo "$SCHEMA_URLS"
echo ""
# Check each URL
while IFS= read -r url; do
[ -z "$url" ] && continue
# Extract version and path from URL
# e.g., https://adcontextprotocol.org/schemas/v3/media-buy/sync-audiences-request.json
VERSION_PATH=$(echo "$url" | sed 's|https://adcontextprotocol.org/schemas/||')
VERSION=$(echo "$VERSION_PATH" | cut -d/ -f1)
SCHEMA_PATH=$(echo "$VERSION_PATH" | cut -d/ -f2-)
# Extract major version number (e.g., v3 -> 3)
MAJOR_NUM=$(echo "$VERSION" | sed 's/v//')
echo "Checking: $url"
echo " Version: $VERSION (major: $MAJOR_NUM), Path: $SCHEMA_PATH"
# Check if schema exists in source
SOURCE_PATH="static/schemas/source/$SCHEMA_PATH"
if [ ! -f "$SOURCE_PATH" ]; then
ERRORS="$ERRORS\n- \`$url\`\n - Schema not found in source: \`$SOURCE_PATH\`"
continue
fi
# `latest` is reserved for source schemas that have not shipped in
# the current major release yet. Once released, docs must switch to
# the stable major alias.
if [ "$VERSION" = "latest" ]; then
CURRENT_MAJOR=$(node -p "require('./package.json').version.split('.')[0]")
# Consult the published alias instead of choosing the newest
# directory. Prerelease directories do not move /schemas/vN/.
CURRENT_RELEASE=$(node -e 'const index = require("./dist/schemas/index.json"); process.stdout.write(index.aliases?.[`v${process.argv[1]}`] || index.latest_by_major?.[process.argv[1]] || "")' "$CURRENT_MAJOR")
if [ -n "$CURRENT_RELEASE" ] && [ -f "dist/schemas/$CURRENT_RELEASE/$SCHEMA_PATH" ]; then
ERRORS="$ERRORS\n- \`$url\`\n - Schema is already released in $CURRENT_RELEASE\n - **Action**: Change URL to /schemas/v${CURRENT_MAJOR}/$SCHEMA_PATH"
else
echo " ✓ Unreleased schema exists in source"
fi
continue
fi
# Check if schema exists in the versioned release
# vN -> the release selected by the published major alias. This
# deliberately excludes newer beta/RC directories.
MAJOR_NUM=$(echo "$VERSION" | sed 's/v//')
LATEST_RELEASE=$(node -e 'const index = require("./dist/schemas/index.json"); process.stdout.write(index.aliases?.[process.argv[1]] || index.latest_by_major?.[process.argv[1].slice(1)] || "")' "$VERSION")
if [ -n "$LATEST_RELEASE" ]; then
RELEASE_PATH="dist/schemas/$LATEST_RELEASE/$SCHEMA_PATH"
# Determine next release name
if echo "$LATEST_RELEASE" | grep -q "beta"; then
BETA_NUM=$(echo "$LATEST_RELEASE" | grep -oE 'beta\.[0-9]+' | cut -d. -f2)
NEXT_BETA=$((BETA_NUM + 1))
NEXT_RELEASE="${MAJOR_NUM}.0.0-beta.${NEXT_BETA} (or later)"
else
NEXT_RELEASE="next ${MAJOR_NUM}.x release"
fi
else
RELEASE_PATH=""
NEXT_RELEASE="first ${MAJOR_NUM}.x release"
fi
if [ -z "$RELEASE_PATH" ]; then
WARNINGS="$WARNINGS\n- \`$url\`\n - No releases found for version $VERSION yet"
elif [ ! -f "$RELEASE_PATH" ]; then
# Schema exists in source but not in the requested version's release
# Check if it exists in other released versions first
AVAILABLE_IN=""
for CHECK_VERSION in 1 2 3; do
if [ "$CHECK_VERSION" = "$MAJOR_NUM" ]; then
continue
fi
CHECK_RELEASE_PATH=$(ls -d dist/schemas/${CHECK_VERSION}.* 2>/dev/null | sort -V | tail -1)
CHECK_RELEASE=$(basename "$CHECK_RELEASE_PATH" 2>/dev/null || echo "")
if [ -n "$CHECK_RELEASE" ] && [ -f "dist/schemas/$CHECK_RELEASE/$SCHEMA_PATH" ]; then
AVAILABLE_IN="$AVAILABLE_IN v$CHECK_VERSION"
fi
done
if [ -n "$AVAILABLE_IN" ]; then
# Schema exists in another released version - use that instead
ERRORS="$ERRORS\n- \`$url\`\n - Schema not released in $VERSION but available in:$AVAILABLE_IN\n - **Action**: Change URL to use the correct version"
else
# Not in any released version - schema is in source which serves as 'latest'
# In production, /schemas/latest/ serves from source, so this link will work
WARNINGS="$WARNINGS\n- \`$url\`\n - Schema exists in \`latest\` (source) but not yet released in $VERSION\n - **Action**: This link will work after **$NEXT_RELEASE** is published"
fi
else
echo " ✓ Schema exists in both source and release"
fi
done <<< "$SCHEMA_URLS"
# Output results
HAS_ERRORS="false"
TOTAL_URLS=$(echo "$SCHEMA_URLS" | wc -l | tr -d ' ')
# Build commit info header - use PR head SHA, not merge commit
COMMIT_SHA="$PR_HEAD_SHA"
COMMIT_SHA_SHORT="${COMMIT_SHA:0:7}"
COMMIT_MSG=$(git log -1 --format='%s' 2>/dev/null || echo "Unknown")
COMMIT_INFO="**Commit**: [\`$COMMIT_SHA_SHORT\`](https://github.com/${{ github.repository }}/commit/$COMMIT_SHA) - $COMMIT_MSG"
# Warnings (unreleased-but-in-source schemas) are expected on pre-release
# docs PRs and self-resolve on the next release. Surface them on the job
# summary only — never as a PR comment — to avoid email noise. Errors
# still post a PR comment because they require author action.
if [ -n "$WARNINGS" ]; then
# Count top-level bullet entries (one per flagged URL).
WARNING_COUNT=$(echo -e "$WARNINGS" | grep -c '^- `' || true)
{
echo "## Schema Link Check — ${WARNING_COUNT} Warning(s)"
echo ""
echo "$COMMIT_INFO"
echo ""
echo "### ⚠️ Warnings (schema not yet released)"
echo ""
echo "These schemas exist in source but haven't been released yet. The links will work after the next version is published."
echo ""
echo -e "$WARNINGS"
} >> "$GITHUB_STEP_SUMMARY"
# Surface on the PR's Checks tab without emailing the author.
echo "::notice title=Schema link warnings::${WARNING_COUNT} schema link(s) reference unreleased schemas — see job summary"
fi
if [ -n "$ERRORS" ]; then
echo "has_issues=true" >> $GITHUB_OUTPUT
HAS_ERRORS="true"
COMMENT="## Schema Link Check Results\n\n$COMMIT_INFO\n\n### ❌ Errors (schema not found)\n\nThese schemas do not exist and the links will be broken:\n$ERRORS\n"
# Escape for GitHub Actions
COMMENT=$(echo -e "$COMMENT" | sed 's/"/\\"/g')
echo "comment<<EOF" >> $GITHUB_OUTPUT
echo -e "$COMMENT" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
else
echo "has_issues=false" >> $GITHUB_OUTPUT
echo "✅ All $TOTAL_URLS schema links are valid (warnings, if any, on job summary)"
fi
echo "has_errors=$HAS_ERRORS" >> $GITHUB_OUTPUT
- name: Comment on PR (only when issues found)
if: steps.check.outputs.has_issues == 'true'
uses: actions/github-script@v9.0.0
env:
COMMENT_BODY: ${{ steps.check.outputs.comment }}
with:
script: |
const comment = process.env.COMMENT_BODY;
// Find existing comment from this workflow
const { data: comments } = await github.rest.issues.listComments({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
});
const botComment = comments.find(c =>
c.user.type === 'Bot' &&
c.body.includes('Schema Link Check Results')
);
if (botComment) {
await github.rest.issues.updateComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: botComment.id,
body: comment
});
} else {
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: comment
});
}
- name: Clean up stale comment on success
if: steps.check.outputs.has_issues == 'false'
uses: actions/github-script@v9.0.0
with:
script: |
const { data: comments } = await github.rest.issues.listComments({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
});
const botComment = comments.find(c =>
c.user.type === 'Bot' &&
c.body.includes('Schema Link Check Results')
);
if (botComment) {
await github.rest.issues.deleteComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: botComment.id
});
}
- name: Fail on errors
if: steps.check.outputs.has_errors == 'true'
run: |
echo "❌ Schema link check failed: some schemas do not exist"
exit 1