feat: add api extractor, semantic diff, and sync workflow

.github/workflows/extract-api.yml

@@ -0,0 +1,143 @@
+name: Extract Typesense API
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "17 4 * * *"
+  push:
+    branches:
+      - master
+    paths:
+      - "src/**"
+      - "config.json"
+      - "package.json"
+      - "package-lock.json"
+      - "tsconfig.json"
+      - ".github/workflows/extract-api.yml"
+
+permissions:
+  contents: write
+  issues: write
+
+jobs:
+  extract:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build CLI
+        run: npm run build
+
+      - name: Save previous extracted spec
+        run: |
+          if git cat-file -e HEAD:output/typesense_api_spec.json 2>/dev/null; then
+            git show HEAD:output/typesense_api_spec.json > "$RUNNER_TEMP/previous-typesense-api-spec.json"
+          else
+            printf '%s\n' '{"rootDir":"","routeFile":"","routes":[],"diagnostics":[]}' > "$RUNNER_TEMP/previous-typesense-api-spec.json"
+          fi
+
+      - name: Run extractor
+        id: extract
+        continue-on-error: true
+        run: node dist/cli.js extract --config ./config.json --fail-on-diagnostics
+
+      - name: Upload extractor artifacts for debugging
+        if: steps.extract.outcome != 'success'
+        uses: actions/upload-artifact@v4
+        with:
+          name: extractor-debug-artifacts
+          if-no-files-found: warn
+          path: |
+            output/typesense_api_spec.json
+            output/typesense_api_diagnostics.json
+
+      - name: Stop on extractor diagnostics
+        if: steps.extract.outcome != 'success'
+        run: exit 1
+
+      - name: Check for extracted output changes
+        id: changes
+        run: |
+          if git diff --quiet -- output/typesense_api_spec.json output/typesense_api_diagnostics.json; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build semantic API diff
+        if: steps.changes.outputs.changed == 'true'
+        run: |
+          node dist/cli.js semantic-diff \
+            --previous "$RUNNER_TEMP/previous-typesense-api-spec.json" \
+            --next output/typesense_api_spec.json \
+            --json-output "$RUNNER_TEMP/typesense-api-diff.json" \
+            --markdown-output "$RUNNER_TEMP/typesense-api-diff.md"
+
+      - name: Read semantic API diff result
+        if: steps.changes.outputs.changed == 'true'
+        id: semantic_diff
+        run: |
+          jq -r '"changed=\(.changed)"' "$RUNNER_TEMP/typesense-api-diff.json" >> "$GITHUB_OUTPUT"
+
+      - name: Commit extracted artifacts
+        if: steps.changes.outputs.changed == 'true'
+        id: commit_artifacts
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add output/typesense_api_spec.json output/typesense_api_diagnostics.json
+          git commit -m "chore: update extracted Typesense API artifacts"
+          git push
+          echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Open OpenAPI update issue
+        if: steps.changes.outputs.changed == 'true' && steps.semantic_diff.outputs.changed == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require("node:fs");
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const commitSha = "${{ steps.commit_artifacts.outputs.sha }}";
+            const shortSha = commitSha.slice(0, 12);
+            const commitUrl = `https://github.com/${owner}/${repo}/commit/${commitSha}`;
+            const title = `Update openapi.yml for extracted Typesense API changes [${shortSha}]`;
+            const existing = await github.paginate(github.rest.issues.listForRepo, {
+              owner,
+              repo,
+              state: "open",
+              per_page: 100,
+            });
+            const alreadyOpen = existing.some((issue) => issue.title === title);
+            if (alreadyOpen) {
+              core.info(`Open issue already exists: ${title}`);
+              return;
+            }
+
+            const bodyPath = `${process.env.RUNNER_TEMP}/typesense-api-diff.md`;
+            const diffBody = fs.readFileSync(bodyPath, "utf8");
+            const body = [
+              "<!-- typesense-api-sync-issue -->",
+              `Commit: ${commitUrl}`,
+              "",
+              diffBody,
+            ].join("\n");
+            await github.rest.issues.create({
+              owner,
+              repo,
+              title,
+              body,
+            });

.github/workflows/lint.yml

@@ -19,10 +19,10 @@ jobs:
         run: npm install 
 
       - name: Lint OpenAPI specification
-        run: npm run lint
+        run: npm run spec:lint
 
       - name: Bundle OpenAPI specification
-        run: npm run bundle
+        run: npm run spec:bundle
 
       - name: Upload bundled specification
         uses: actions/upload-artifact@v4

.gitignore

@@ -1 +1,2 @@
 node_modules
+dist

config.json

@@ -0,0 +1,14 @@
+{
+  "root_dir": "",
+  "route_file": "src/main/typesense_server.cpp",
+  "source_branch": "v30",
+  "output_path": "./output/typesense_api_spec.json",
+  "diagnostics_output_path": "./output/typesense_api_diagnostics.json",
+  "max_call_depth": 4,
+  "fail_on_unresolved": false,
+  "blacklist": {
+    "paths": ["/proxy", "/proxy_sse", "/operations/reset_peers", "/limits"],
+    "params": ["_ArraySize_"]
+  },
+  "overrides": []
+}

eslint.config.mjs

@@ -0,0 +1,33 @@
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  {
+    ignores: ["**/dist/**"],
+  },
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      "@typescript-eslint/consistent-type-imports": [
+        "error",
+        { prefer: "type-imports", fixStyle: "separate-type-imports" },
+      ],
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
+    },
+  },
+  {
+    files: ["**/*.js", "**/*.mjs"],
+    ...tseslint.configs.disableTypeChecked,
+  },
+);

output/typesense_api_diagnostics.json

@@ -0,0 +1 @@
+[]