Feature/provider dev

.env.example

@@ -0,0 +1,21 @@
+# Live smoke-test credentials (copy to .env - gitignored - and fill in).
+# `make smoke`, `make smoke-live` and `make validate-complexity` source .env
+# when present. The provider is read-only, so a read_api token is enough and
+# nothing is ever created.
+
+# Personal access token with the read_api scope (GitLab -> User settings ->
+# Access tokens). The same variable the Terraform gitlab provider reads.
+GITLAB_TOKEN=glpat-...
+
+# Optional: self-managed host (and port). Resolves the `host` server variable
+# via x-stackQL-envVar so queries need no WHERE host clause. Leave unset for
+# gitlab.com. (The Terraform provider's GITLAB_BASE_URL carries the REST v4
+# path and cannot be reused as a bare host.)
+# GITLAB_HOST=gitlab.example.com
+
+# Optional: the group and the seeded fixture project the authenticated smoke
+# tier reads (make seed-fixtures creates the project; the group is used for
+# group-scoped reads and must be readable by the token). Defaults: the public
+# gitlab-org group and the seeded javen-infraql/stackql-provider-smoke project.
+# GITLAB_SMOKE_GROUP=stackql
+# GITLAB_SMOKE_PROJECT=stackql/stackql-provider-smoke

.github/workflows/build-and-test.yml

@@ -0,0 +1,174 @@
+name: build-and-test
+
+# Build the gitlab provider from the pinned GraphQL introspection schema and
+# run every token-free test layer on each push / PR (the anonymous
+# complexity gate against gitlab.com included); the live smoke suite runs
+# only where GITLAB_TOKEN is configured; a scheduled schema-drift job diffs
+# the served schema against the pin (gitlab.com deploys continuously -
+# drift is expected and must be reviewed, never silent).
+
+on:
+  push:
+    branches: [main, 'feature/**']
+    paths-ignore: ['website/**']
+  pull_request:
+    branches: [main]
+    paths-ignore: ['website/**']
+  schedule:
+    - cron: '41 3 * * 1'   # weekly schema-drift check (Monday 03:41 UTC)
+  workflow_dispatch:
+
+jobs:
+  build-and-test:
+    if: github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      # puts the latest stackql on PATH; bin/start-server.sh and the test
+      # runners resolve it from there
+      - name: Install stackql
+        uses: stackql/setup-stackql@v2
+
+      - name: stackql version
+        run: stackql --version
+
+      # Drift is reported, not fatal, here: the committed pin is what gets
+      # built and tested. The schema-drift job below opens the review issue.
+      - name: Verify the pinned schema against gitlab.com (warns on drift)
+        run: |
+          if ! make fetch-schema; then
+            echo "::warning title=GitLab GraphQL schema drift::The served introspection schema no longer matches provider-dev/config/schema_pin.json - run 'make refresh-schema && make inventory generate && make test' and review the diff. Building from the committed pin."
+          fi
+
+      - name: Build provider from the pinned schema
+        run: make inventory generate
+
+      - name: Fail on uncommitted generation drift
+        run: |
+          git add -N .
+          if ! git diff --quiet -- provider-dev/openapi provider-dev/config; then
+            echo "Generated output differs from the committed artifacts - run 'make inventory generate' and commit."
+            git diff --stat -- provider-dev/openapi provider-dev/config
+            exit 1
+          fi
+
+      # Authenticated when the GITLAB_TOKEN secret is configured (limit 250,
+      # and the resolvers that answer anonymous callers with a 500 score
+      # normally); anonymous otherwise (forks, outside PRs), where the
+      # validator bounds server-side failures conservatively.
+      - name: Complexity gate (gitlab.com)
+        env:
+          GITLAB_TOKEN: ${{ secrets.GITLAB_TOKEN }}
+        run: make validate-complexity
+
+      - name: Offline validation
+        run: make test-offline
+
+      - name: Integration tests (mock GitLab GraphQL server)
+        run: make test-integration
+
+      - name: Meta-route tests
+        run: make test-meta
+
+      - name: Generate docs (sanity - the site build runs on the web workflows)
+        run: make docs
+
+  smoke:
+    # secret-gated live read smoke suite against gitlab.com; skipped with a
+    # notice when the token is not configured (forks, PRs from outside).
+    # Read-only by architecture: nothing is created, nothing to sweep.
+    runs-on: ubuntu-latest
+    needs: build-and-test
+    if: github.event_name != 'pull_request' && github.event_name != 'schedule'
+    env:
+      GITLAB_TOKEN: ${{ secrets.GITLAB_TOKEN }}
+      GITLAB_SMOKE_GROUP: ${{ secrets.GITLAB_SMOKE_GROUP }}
+      GITLAB_SMOKE_PROJECT: ${{ secrets.GITLAB_SMOKE_PROJECT }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+          cache: npm
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Live smoke suite (read tiers, authenticated)
+        if: env.GITLAB_TOKEN != ''
+        run: make smoke
+
+      - name: Live smoke skipped (no credentials)
+        if: env.GITLAB_TOKEN == ''
+        run: |
+          echo "::notice title=Live smoke suite skipped::GITLAB_TOKEN secret is not configured - the live smoke suite did not run. Token-free coverage still ran via the mock-server integration suite and the anonymous complexity gate."
+
+  schema-drift:
+    # Diff the served introspection schema against the pin on a schedule and
+    # on demand, and open an issue when it moves.
+    runs-on: ubuntu-latest
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Fetch and compare against the pin
+        id: drift
+        run: |
+          set +e
+          make fetch-schema > fetch.log 2>&1
+          rc=$?
+          set -e
+          cat fetch.log
+          if [ "$rc" -eq 0 ]; then
+            echo "drift=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "drift=true" >> "$GITHUB_OUTPUT"
+            # materialise the diff for the issue body (refresh into the working tree only)
+            npm run fetch-schema -- --update > /dev/null 2>&1 || true
+            npm run build-inventory > /dev/null 2>&1 || true
+            git diff --stat -- provider-dev/config > drift.txt || true
+            cat drift.txt
+          fi
+
+      - name: Report drift
+        if: steps.drift.outputs.drift == 'true'
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const fs = require('fs');
+            const stat = fs.existsSync('drift.txt') ? fs.readFileSync('drift.txt', 'utf8') : '(diff unavailable)';
+            const title = 'GitLab GraphQL schema drift detected';
+            const body = 'The introspection schema served at https://gitlab.com/-/graphql/introspection_result_no_deprecated.json no longer matches the pin in provider-dev/config/schema_pin.json.\n\n```\n' + stat + '\n```\nRun `make refresh-schema && make inventory generate && make validate-complexity test`, review the inventory and all_services.csv diffs (new, removed or moved resources fail `make generate` until accepted with `make generate-accept`), update NOTES.md, and commit.';
+            await core.summary.addHeading(title).addCodeBlock(stat).write();
+            const { data: issues } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner, repo: context.repo.repo, state: 'open', labels: 'schema-drift'
+            });
+            if (issues.some(i => i.title === title)) return;
+            await github.rest.issues.create({
+              owner: context.repo.owner, repo: context.repo.repo, title, body, labels: ['schema-drift']
+            });

.github/workflows/prod-web-deploy.yml

@@ -0,0 +1,58 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'website/**'      
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: yarn
+          cache-dependency-path: website/yarn.lock
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+        working-directory: website
+
+      - name: Build website
+        run: yarn build
+        working-directory: website
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: website/build # Ensure the path is correctly set to the Docusaurus build output
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
+        with:
+          working-directory: website/build # Ensures the correct directory is used for deployment

.github/workflows/test-web-deploy.yml

@@ -0,0 +1,31 @@
+name: Test deployment
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'website/**'
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: yarn
+          cache-dependency-path: website/yarn.lock
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+        working-directory: website
+
+      - name: Test build website
+        run: yarn build
+        working-directory: website

.gitignore

@@ -1,3 +1,8 @@
+# StackQL binary and server logs
+/stackql
+/stackql.exe
+stackql-server.log
+
 # Logs
 logs
 *.log
@@ -141,3 +146,8 @@ dist
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
 .vite/
+
+# python venv for the smoke suite, scratch files
+.venv/
+.scratch/
+__pycache__/

.npmrc

@@ -0,0 +1 @@
+@jsr:registry=https://npm.jsr.io