Doc audit #499
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Doc audit | |
| # Runs the Layer C doc↔code alignment audit: enumerate TS source into a | |
| # TS-native surface snapshot, type-check every example, and verify that every | |
| # method-call reference in docs/ + examples/ resolves to a real TS symbol or | |
| # is explicitly listed in DOC_AUDIT_IGNORE.md with a rationale. | |
| env: | |
| # Opt into Node.js 24 ahead of GitHub's 2026-06-02 default switch. | |
| FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" | |
| on: | |
| pull_request: | |
| push: | |
| branches: [main] | |
| schedule: | |
| # Nightly at 06:30 UTC — runs right after the Layer B surface audit so | |
| # doc drift surfaces alongside surface drift. | |
| - cron: '30 6 * * *' | |
| jobs: | |
| doc-audit: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout TypeScript SDK | |
| uses: actions/checkout@v7 | |
| with: | |
| path: typescript-sdk | |
| - name: Checkout porting-sdk (contains audit_docs.py) | |
| uses: actions/checkout@v7 | |
| with: | |
| repository: signalwire/porting-sdk | |
| # Coordinated-pass pin: 'main' normally; set the PORTING_SDK_REF repo variable | |
| # to a wave branch to test a coordinated porting-sdk change, declared on the PR | |
| # (see porting-sdk/COORDINATED_PASS.md). No revert commit. | |
| ref: ${{ vars.PORTING_SDK_REF || 'main' }} | |
| path: porting-sdk | |
| token: ${{ secrets.PORTING_SDK_TOKEN }} | |
| - name: Setup Node | |
| uses: actions/setup-node@v7 | |
| with: | |
| node-version: '22' | |
| cache: 'npm' | |
| cache-dependency-path: typescript-sdk/package-lock.json | |
| - name: Setup Python (for audit_docs.py) | |
| uses: actions/setup-python@v6 | |
| with: | |
| python-version: '3.14' | |
| - name: Install porting-sdk script dependencies | |
| # NOT optional: the gate scripts reach the reference oracle through | |
| # generate_rest.py, which needs PyYAML, and a swallowed ImportError turned its | |
| # absence into an EMPTY oracle — 266 gated members silently vanished and the diff | |
| # reported "311 symbols missing from port" against a port that was correct. | |
| run: python3 -m pip install --quiet -r ${{ github.workspace }}/porting-sdk/scripts/requirements.txt | |
| - name: Install TS deps | |
| working-directory: typescript-sdk | |
| run: npm ci | |
| - name: Type-check examples (tsc --noEmit) | |
| working-directory: typescript-sdk | |
| run: npx tsc --noEmit --project tsconfig.examples.json | |
| - name: Enumerate TS-native doc-audit surface | |
| working-directory: typescript-sdk | |
| env: | |
| PORTING_SDK_PATH: ${{ github.workspace }}/porting-sdk | |
| run: npx tsx scripts/enumerate-doc-surface.ts | |
| - name: Audit doc / example references | |
| working-directory: typescript-sdk | |
| run: | | |
| python3 ${{ github.workspace }}/porting-sdk/scripts/audit_docs.py \ | |
| --root . \ | |
| --surface docs_audit_surface.json \ | |
| --ignore DOC_AUDIT_IGNORE.md |