diff --git a/.env.example b/.env.example new file mode 100644 index 000000000..564283a56 --- /dev/null +++ b/.env.example @@ -0,0 +1,26 @@ +# Content Indexer Environment Variables +# Copy this file to .env.local and fill in your actual values + +# ============================================================================ +# GitHub API (Required for SDK indexer and production mode) +# ============================================================================ +# Get a token at: https://github.com/settings/tokens +# Permissions needed: public_repo (read access to public repositories) +GH_TOKEN=your_github_token_here + +# ============================================================================ +# Redis / Upstash KV (Required for all indexers) +# ============================================================================ +# Used to store path indices and navigation trees +# Get these from your Upstash dashboard: https://console.upstash.com/ +KV_REST_API_URL=your_kv_url_here +KV_REST_API_TOKEN=your_kv_token_here + +# ============================================================================ +# Algolia (Required for all indexers) +# ============================================================================ +# Used for search indexing +# Get these from your Algolia dashboard: https://www.algolia.com/ +ALGOLIA_APP_ID=your_app_id_here +ALGOLIA_ADMIN_API_KEY=your_admin_api_key_here + diff --git a/.github/workflows/gh-pages-deploy.yml b/.github/workflows/gh-pages-deploy.yml index f39f45165..6aec52833 100644 --- a/.github/workflows/gh-pages-deploy.yml +++ b/.github/workflows/gh-pages-deploy.yml @@ -8,8 +8,6 @@ on: - main types: - completed - repository_dispatch: - types: [trigger-gh-pages-deploy] concurrency: group: "pages" cancel-in-progress: false diff --git a/.github/workflows/index-changelog.yml b/.github/workflows/index-changelog.yml new file mode 100644 index 000000000..4c91baf01 --- /dev/null +++ b/.github/workflows/index-changelog.yml @@ -0,0 +1,40 @@ +name: Index Changelog + +on: + push: + branches: + - main + paths: + - "fern/changelog/**" + +jobs: + index-changelog: + name: Index Changelog + runs-on: ubuntu-latest + # Only run when files are added or removed, not modified + if: | + github.event.head_commit && + ( + github.event.head_commit.added[0] != null || + github.event.head_commit.removed[0] != null + ) && + ( + contains(join(github.event.head_commit.added, ','), 'fern/changelog/') || + contains(join(github.event.head_commit.removed, ','), 'fern/changelog/') + ) + permissions: + contents: read + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup pnpm + uses: ./.github/actions/setup-pnpm + + - name: Run changelog indexer + run: pnpm index:changelog + env: + KV_REST_API_TOKEN: ${{ secrets.KV_REST_API_TOKEN }} + KV_REST_API_URL: ${{ secrets.KV_REST_API_URL }} + ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }} + ALGOLIA_ADMIN_API_KEY: ${{ secrets.ALGOLIA_ADMIN_API_KEY }} diff --git a/.github/workflows/index-main-content.yml b/.github/workflows/index-main-content.yml new file mode 100644 index 000000000..3da3fb772 --- /dev/null +++ b/.github/workflows/index-main-content.yml @@ -0,0 +1,30 @@ +name: Index Main Content + +on: + push: + branches: + - main + paths: + - "fern/docs.yml" + +jobs: + index-main: + name: Index Main Content + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup pnpm + uses: ./.github/actions/setup-pnpm + + - name: Run main content indexer + run: pnpm index:main + env: + KV_REST_API_TOKEN: ${{ secrets.KV_REST_API_TOKEN }} + KV_REST_API_URL: ${{ secrets.KV_REST_API_URL }} + ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }} + ALGOLIA_ADMIN_API_KEY: ${{ secrets.ALGOLIA_ADMIN_API_KEY }} + GH_TOKEN: ${{ secrets.GH_TOKEN }} diff --git a/.github/workflows/index-sdk-references.yml b/.github/workflows/index-sdk-references.yml new file mode 100644 index 000000000..5a31e3211 --- /dev/null +++ b/.github/workflows/index-sdk-references.yml @@ -0,0 +1,30 @@ +name: Index SDK References + +on: + repository_dispatch: + types: + - index-sdk-references + +jobs: + index-sdk: + name: Index SDK References + runs-on: ubuntu-latest + # Only run if the dispatch came from the aa-sdk repository + if: github.event.client_payload.source == 'alchemyplatform/aa-sdk' + permissions: + contents: read + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup pnpm + uses: ./.github/actions/setup-pnpm + + - name: Run SDK indexer + run: pnpm index:sdk + env: + KV_REST_API_TOKEN: ${{ secrets.KV_REST_API_TOKEN }} + KV_REST_API_URL: ${{ secrets.KV_REST_API_URL }} + ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }} + ALGOLIA_ADMIN_API_KEY: ${{ secrets.ALGOLIA_ADMIN_API_KEY }} + GH_TOKEN: ${{ secrets.GH_TOKEN }} diff --git a/.gitignore b/.gitignore index c2c2cc1cf..8fdaa6c0a 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,7 @@ node_modules/ # dotenv environment variables file .env* +!.env.example # misc .DS_Store @@ -35,3 +36,5 @@ fern/api-specs/ # local files *.local +# vitests +coverage/ diff --git a/eslint.config.ts b/eslint.config.ts index 083deb8ad..90c1d53a3 100644 --- a/eslint.config.ts +++ b/eslint.config.ts @@ -71,6 +71,7 @@ const tslintConfigs = tseslint.config({ }, ], "@typescript-eslint/consistent-type-imports": "error", + "@typescript-eslint/no-non-null-assertion": "error", }, }) as ConfigWithExtends[]; diff --git a/fern/components/CodeConsole/codeData.ts b/fern/components/CodeConsole/codeData.ts index 52bd43b35..99d3676a7 100644 --- a/fern/components/CodeConsole/codeData.ts +++ b/fern/components/CodeConsole/codeData.ts @@ -1,132 +1,132 @@ -import alchemyGetAssetTransfersEthereumRequest from "./code-samples/alchemy_getAssetTransfers/ethereum-request"; -import alchemyGetAssetTransfersEthereumResponse from "./code-samples/alchemy_getAssetTransfers/ethereum-response"; -import alchemyGetTokenBalancesEthereumRequest from "./code-samples/alchemy_getTokenBalances/ethereum-request"; -import alchemyGetTokenBalancesEthereumResponse from "./code-samples/alchemy_getTokenBalances/ethereum-response"; -import ethBlockNumberArbitrumRequest from "./code-samples/eth_blockNumber/arbitrum-request"; -import ethBlockNumberArbitrumResponse from "./code-samples/eth_blockNumber/arbitrum-response"; -import ethBlockNumberBaseRequest from "./code-samples/eth_blockNumber/base-request"; -import ethBlockNumberBaseResponse from "./code-samples/eth_blockNumber/base-response"; -import ethBlockNumberEthereumRequest from "./code-samples/eth_blockNumber/ethereum-request"; -import ethBlockNumberEthereumResponse from "./code-samples/eth_blockNumber/ethereum-response"; -import ethBlockNumberOptimismRequest from "./code-samples/eth_blockNumber/optimism-request"; -import ethBlockNumberOptimismResponse from "./code-samples/eth_blockNumber/optimism-response"; -import ethBlockNumberPolygonRequest from "./code-samples/eth_blockNumber/polygon-request"; -import ethBlockNumberPolygonResponse from "./code-samples/eth_blockNumber/polygon-response"; -import ethChainIdArbitrumRequest from "./code-samples/eth_chainId/arbitrum-request"; -import ethChainIdArbitrumResponse from "./code-samples/eth_chainId/arbitrum-response"; -import ethChainIdBaseRequest from "./code-samples/eth_chainId/base-request"; -import ethChainIdBaseResponse from "./code-samples/eth_chainId/base-response"; -import ethChainIdEthereumRequest from "./code-samples/eth_chainId/ethereum-request"; -import ethChainIdEthereumResponse from "./code-samples/eth_chainId/ethereum-response"; -import ethChainIdOptimismRequest from "./code-samples/eth_chainId/optimism-request"; -import ethChainIdOptimismResponse from "./code-samples/eth_chainId/optimism-response"; -import ethChainIdPolygonRequest from "./code-samples/eth_chainId/polygon-request"; -import ethChainIdPolygonResponse from "./code-samples/eth_chainId/polygon-response"; -import ethEstimateGasArbitrumRequest from "./code-samples/eth_estimateGas/arbitrum-request"; -import ethEstimateGasArbitrumResponse from "./code-samples/eth_estimateGas/arbitrum-response"; -import ethEstimateGasBaseRequest from "./code-samples/eth_estimateGas/base-request"; -import ethEstimateGasBaseResponse from "./code-samples/eth_estimateGas/base-response"; -import ethEstimateGasEthereumRequest from "./code-samples/eth_estimateGas/ethereum-request"; -import ethEstimateGasEthereumResponse from "./code-samples/eth_estimateGas/ethereum-response"; -import ethEstimateGasOptimismRequest from "./code-samples/eth_estimateGas/optimism-request"; -import ethEstimateGasOptimismResponse from "./code-samples/eth_estimateGas/optimism-response"; -import ethEstimateGasPolygonRequest from "./code-samples/eth_estimateGas/polygon-request"; -import ethEstimateGasPolygonResponse from "./code-samples/eth_estimateGas/polygon-response"; -import ethGasPriceArbitrumRequest from "./code-samples/eth_gasPrice/arbitrum-request"; -import ethGasPriceArbitrumResponse from "./code-samples/eth_gasPrice/arbitrum-response"; -import ethGasPriceBaseRequest from "./code-samples/eth_gasPrice/base-request"; -import ethGasPriceBaseResponse from "./code-samples/eth_gasPrice/base-response"; -import ethGasPriceEthereumRequest from "./code-samples/eth_gasPrice/ethereum-request"; -import ethGasPriceEthereumResponse from "./code-samples/eth_gasPrice/ethereum-response"; -import ethGasPriceOptimismRequest from "./code-samples/eth_gasPrice/optimism-request"; -import ethGasPriceOptimismResponse from "./code-samples/eth_gasPrice/optimism-response"; -import ethGasPricePolygonRequest from "./code-samples/eth_gasPrice/polygon-request"; -import ethGasPricePolygonResponse from "./code-samples/eth_gasPrice/polygon-response"; -import ethGetBalanceArbitrumRequest from "./code-samples/eth_getBalance/arbitrum-request"; -import ethGetBalanceArbitrumResponse from "./code-samples/eth_getBalance/arbitrum-response"; -import ethGetBalanceBaseRequest from "./code-samples/eth_getBalance/base-request"; -import ethGetBalanceBaseResponse from "./code-samples/eth_getBalance/base-response"; -import ethGetBalanceEthereumRequest from "./code-samples/eth_getBalance/ethereum-request"; -import ethGetBalanceEthereumResponse from "./code-samples/eth_getBalance/ethereum-response"; -import ethGetBalanceOptimismRequest from "./code-samples/eth_getBalance/optimism-request"; -import ethGetBalanceOptimismResponse from "./code-samples/eth_getBalance/optimism-response"; -import ethGetBalancePolygonRequest from "./code-samples/eth_getBalance/polygon-request"; -import ethGetBalancePolygonResponse from "./code-samples/eth_getBalance/polygon-response"; -import ethGetBlockByNumberArbitrumRequest from "./code-samples/eth_getBlockByNumber/arbitrum-request"; -import ethGetBlockByNumberArbitrumResponse from "./code-samples/eth_getBlockByNumber/arbitrum-response"; -import ethGetBlockByNumberBaseRequest from "./code-samples/eth_getBlockByNumber/base-request"; -import ethGetBlockByNumberBaseResponse from "./code-samples/eth_getBlockByNumber/base-response"; -import ethGetBlockByNumberEthereumRequest from "./code-samples/eth_getBlockByNumber/ethereum-request"; -import ethGetBlockByNumberEthereumResponse from "./code-samples/eth_getBlockByNumber/ethereum-response"; -import ethGetBlockByNumberOptimismRequest from "./code-samples/eth_getBlockByNumber/optimism-request"; -import ethGetBlockByNumberOptimismResponse from "./code-samples/eth_getBlockByNumber/optimism-response"; -import ethGetBlockByNumberPolygonRequest from "./code-samples/eth_getBlockByNumber/polygon-request"; -import ethGetBlockByNumberPolygonResponse from "./code-samples/eth_getBlockByNumber/polygon-response"; -import ethGetBlockReceiptsArbitrumRequest from "./code-samples/eth_getBlockReceipts/arbitrum-request"; -import ethGetBlockReceiptsArbitrumResponse from "./code-samples/eth_getBlockReceipts/arbitrum-response"; -import ethGetBlockReceiptsBaseRequest from "./code-samples/eth_getBlockReceipts/base-request"; -import ethGetBlockReceiptsBaseResponse from "./code-samples/eth_getBlockReceipts/base-response"; -import ethGetBlockReceiptsEthereumRequest from "./code-samples/eth_getBlockReceipts/ethereum-request"; -import ethGetBlockReceiptsEthereumResponse from "./code-samples/eth_getBlockReceipts/ethereum-response"; -import ethGetBlockReceiptsOptimismRequest from "./code-samples/eth_getBlockReceipts/optimism-request"; -import ethGetBlockReceiptsOptimismResponse from "./code-samples/eth_getBlockReceipts/optimism-response"; -import ethGetBlockReceiptsPolygonRequest from "./code-samples/eth_getBlockReceipts/polygon-request"; -import ethGetBlockReceiptsPolygonResponse from "./code-samples/eth_getBlockReceipts/polygon-response"; -import ethGetLogsArbitrumRequest from "./code-samples/eth_getLogs/arbitrum-request"; -import ethGetLogsArbitrumResponse from "./code-samples/eth_getLogs/arbitrum-response"; -import ethGetLogsBaseRequest from "./code-samples/eth_getLogs/base-request"; -import ethGetLogsBaseResponse from "./code-samples/eth_getLogs/base-response"; -import ethGetLogsEthereumRequest from "./code-samples/eth_getLogs/ethereum-request"; -import ethGetLogsEthereumResponse from "./code-samples/eth_getLogs/ethereum-response"; -import ethGetLogsOptimismRequest from "./code-samples/eth_getLogs/optimism-request"; -import ethGetLogsOptimismResponse from "./code-samples/eth_getLogs/optimism-response"; -import ethGetLogsPolygonRequest from "./code-samples/eth_getLogs/polygon-request"; -import ethGetLogsPolygonResponse from "./code-samples/eth_getLogs/polygon-response"; -import ethGetTransactionByHashArbitrumRequest from "./code-samples/eth_getTransactionByHash/arbitrum-request"; -import ethGetTransactionByHashArbitrumResponse from "./code-samples/eth_getTransactionByHash/arbitrum-response"; -import ethGetTransactionByHashBaseRequest from "./code-samples/eth_getTransactionByHash/base-request"; -import ethGetTransactionByHashBaseResponse from "./code-samples/eth_getTransactionByHash/base-response"; -import ethGetTransactionByHashEthereumRequest from "./code-samples/eth_getTransactionByHash/ethereum-request"; -import ethGetTransactionByHashEthereumResponse from "./code-samples/eth_getTransactionByHash/ethereum-response"; -import ethGetTransactionByHashOptimismRequest from "./code-samples/eth_getTransactionByHash/optimism-request"; -import ethGetTransactionByHashOptimismResponse from "./code-samples/eth_getTransactionByHash/optimism-response"; -import ethGetTransactionByHashPolygonRequest from "./code-samples/eth_getTransactionByHash/polygon-request"; -import ethGetTransactionByHashPolygonResponse from "./code-samples/eth_getTransactionByHash/polygon-response"; -import ethGetTransactionCountArbitrumRequest from "./code-samples/eth_getTransactionCount/arbitrum-request"; -import ethGetTransactionCountArbitrumResponse from "./code-samples/eth_getTransactionCount/arbitrum-response"; -import ethGetTransactionCountBaseRequest from "./code-samples/eth_getTransactionCount/base-request"; -import ethGetTransactionCountBaseResponse from "./code-samples/eth_getTransactionCount/base-response"; -import ethGetTransactionCountEthereumRequest from "./code-samples/eth_getTransactionCount/ethereum-request"; -import ethGetTransactionCountEthereumResponse from "./code-samples/eth_getTransactionCount/ethereum-response"; -import ethGetTransactionCountOptimismRequest from "./code-samples/eth_getTransactionCount/optimism-request"; -import ethGetTransactionCountOptimismResponse from "./code-samples/eth_getTransactionCount/optimism-response"; -import ethGetTransactionCountPolygonRequest from "./code-samples/eth_getTransactionCount/polygon-request"; -import ethGetTransactionCountPolygonResponse from "./code-samples/eth_getTransactionCount/polygon-response"; -import ethGetTransactionReceiptArbitrumRequest from "./code-samples/eth_getTransactionReceipt/arbitrum-request"; -import ethGetTransactionReceiptArbitrumResponse from "./code-samples/eth_getTransactionReceipt/arbitrum-response"; -import ethGetTransactionReceiptBaseRequest from "./code-samples/eth_getTransactionReceipt/base-request"; -import ethGetTransactionReceiptBaseResponse from "./code-samples/eth_getTransactionReceipt/base-response"; -import ethGetTransactionReceiptEthereumRequest from "./code-samples/eth_getTransactionReceipt/ethereum-request"; -import ethGetTransactionReceiptEthereumResponse from "./code-samples/eth_getTransactionReceipt/ethereum-response"; -import ethGetTransactionReceiptOptimismRequest from "./code-samples/eth_getTransactionReceipt/optimism-request"; -import ethGetTransactionReceiptOptimismResponse from "./code-samples/eth_getTransactionReceipt/optimism-response"; -import ethGetTransactionReceiptPolygonRequest from "./code-samples/eth_getTransactionReceipt/polygon-request"; -import ethGetTransactionReceiptPolygonResponse from "./code-samples/eth_getTransactionReceipt/polygon-response"; -import getAccountInfoSolanaRequest from "./code-samples/getAccountInfo/solana-request"; -import getAccountInfoSolanaResponse from "./code-samples/getAccountInfo/solana-response"; -import getBalanceSolanaRequest from "./code-samples/getBalance/solana-request"; -import getBalanceSolanaResponse from "./code-samples/getBalance/solana-response"; -import getLatestBlockhashSolanaRequest from "./code-samples/getLatestBlockhash/solana-request"; -import getLatestBlockhashSolanaResponse from "./code-samples/getLatestBlockhash/solana-response"; -import getSignaturesForAddressSolanaRequest from "./code-samples/getSignaturesForAddress/solana-request"; -import getSignaturesForAddressSolanaResponse from "./code-samples/getSignaturesForAddress/solana-response"; -import getTokenAccountBalanceSolanaRequest from "./code-samples/getTokenAccountBalance/solana-request"; -import getTokenAccountBalanceSolanaResponse from "./code-samples/getTokenAccountBalance/solana-response"; -import getTokenAccountsByOwnerSolanaRequest from "./code-samples/getTokenAccountsByOwner/solana-request"; -import getTokenAccountsByOwnerSolanaResponse from "./code-samples/getTokenAccountsByOwner/solana-response"; -import getTransactionSolanaRequest from "./code-samples/getTransaction/solana-request"; -import getTransactionSolanaResponse from "./code-samples/getTransaction/solana-response"; -import type { Option } from "./CodeblockSelect"; +import alchemyGetAssetTransfersEthereumRequest from "./code-samples/alchemy_getAssetTransfers/ethereum-request.ts"; +import alchemyGetAssetTransfersEthereumResponse from "./code-samples/alchemy_getAssetTransfers/ethereum-response.ts"; +import alchemyGetTokenBalancesEthereumRequest from "./code-samples/alchemy_getTokenBalances/ethereum-request.ts"; +import alchemyGetTokenBalancesEthereumResponse from "./code-samples/alchemy_getTokenBalances/ethereum-response.ts"; +import ethBlockNumberArbitrumRequest from "./code-samples/eth_blockNumber/arbitrum-request.ts"; +import ethBlockNumberArbitrumResponse from "./code-samples/eth_blockNumber/arbitrum-response.ts"; +import ethBlockNumberBaseRequest from "./code-samples/eth_blockNumber/base-request.ts"; +import ethBlockNumberBaseResponse from "./code-samples/eth_blockNumber/base-response.ts"; +import ethBlockNumberEthereumRequest from "./code-samples/eth_blockNumber/ethereum-request.ts"; +import ethBlockNumberEthereumResponse from "./code-samples/eth_blockNumber/ethereum-response.ts"; +import ethBlockNumberOptimismRequest from "./code-samples/eth_blockNumber/optimism-request.ts"; +import ethBlockNumberOptimismResponse from "./code-samples/eth_blockNumber/optimism-response.ts"; +import ethBlockNumberPolygonRequest from "./code-samples/eth_blockNumber/polygon-request.ts"; +import ethBlockNumberPolygonResponse from "./code-samples/eth_blockNumber/polygon-response.ts"; +import ethChainIdArbitrumRequest from "./code-samples/eth_chainId/arbitrum-request.ts"; +import ethChainIdArbitrumResponse from "./code-samples/eth_chainId/arbitrum-response.ts"; +import ethChainIdBaseRequest from "./code-samples/eth_chainId/base-request.ts"; +import ethChainIdBaseResponse from "./code-samples/eth_chainId/base-response.ts"; +import ethChainIdEthereumRequest from "./code-samples/eth_chainId/ethereum-request.ts"; +import ethChainIdEthereumResponse from "./code-samples/eth_chainId/ethereum-response.ts"; +import ethChainIdOptimismRequest from "./code-samples/eth_chainId/optimism-request.ts"; +import ethChainIdOptimismResponse from "./code-samples/eth_chainId/optimism-response.ts"; +import ethChainIdPolygonRequest from "./code-samples/eth_chainId/polygon-request.ts"; +import ethChainIdPolygonResponse from "./code-samples/eth_chainId/polygon-response.ts"; +import ethEstimateGasArbitrumRequest from "./code-samples/eth_estimateGas/arbitrum-request.ts"; +import ethEstimateGasArbitrumResponse from "./code-samples/eth_estimateGas/arbitrum-response.ts"; +import ethEstimateGasBaseRequest from "./code-samples/eth_estimateGas/base-request.ts"; +import ethEstimateGasBaseResponse from "./code-samples/eth_estimateGas/base-response.ts"; +import ethEstimateGasEthereumRequest from "./code-samples/eth_estimateGas/ethereum-request.ts"; +import ethEstimateGasEthereumResponse from "./code-samples/eth_estimateGas/ethereum-response.ts"; +import ethEstimateGasOptimismRequest from "./code-samples/eth_estimateGas/optimism-request.ts"; +import ethEstimateGasOptimismResponse from "./code-samples/eth_estimateGas/optimism-response.ts"; +import ethEstimateGasPolygonRequest from "./code-samples/eth_estimateGas/polygon-request.ts"; +import ethEstimateGasPolygonResponse from "./code-samples/eth_estimateGas/polygon-response.ts"; +import ethGasPriceArbitrumRequest from "./code-samples/eth_gasPrice/arbitrum-request.ts"; +import ethGasPriceArbitrumResponse from "./code-samples/eth_gasPrice/arbitrum-response.ts"; +import ethGasPriceBaseRequest from "./code-samples/eth_gasPrice/base-request.ts"; +import ethGasPriceBaseResponse from "./code-samples/eth_gasPrice/base-response.ts"; +import ethGasPriceEthereumRequest from "./code-samples/eth_gasPrice/ethereum-request.ts"; +import ethGasPriceEthereumResponse from "./code-samples/eth_gasPrice/ethereum-response.ts"; +import ethGasPriceOptimismRequest from "./code-samples/eth_gasPrice/optimism-request.ts"; +import ethGasPriceOptimismResponse from "./code-samples/eth_gasPrice/optimism-response.ts"; +import ethGasPricePolygonRequest from "./code-samples/eth_gasPrice/polygon-request.ts"; +import ethGasPricePolygonResponse from "./code-samples/eth_gasPrice/polygon-response.ts"; +import ethGetBalanceArbitrumRequest from "./code-samples/eth_getBalance/arbitrum-request.ts"; +import ethGetBalanceArbitrumResponse from "./code-samples/eth_getBalance/arbitrum-response.ts"; +import ethGetBalanceBaseRequest from "./code-samples/eth_getBalance/base-request.ts"; +import ethGetBalanceBaseResponse from "./code-samples/eth_getBalance/base-response.ts"; +import ethGetBalanceEthereumRequest from "./code-samples/eth_getBalance/ethereum-request.ts"; +import ethGetBalanceEthereumResponse from "./code-samples/eth_getBalance/ethereum-response.ts"; +import ethGetBalanceOptimismRequest from "./code-samples/eth_getBalance/optimism-request.ts"; +import ethGetBalanceOptimismResponse from "./code-samples/eth_getBalance/optimism-response.ts"; +import ethGetBalancePolygonRequest from "./code-samples/eth_getBalance/polygon-request.ts"; +import ethGetBalancePolygonResponse from "./code-samples/eth_getBalance/polygon-response.ts"; +import ethGetBlockByNumberArbitrumRequest from "./code-samples/eth_getBlockByNumber/arbitrum-request.ts"; +import ethGetBlockByNumberArbitrumResponse from "./code-samples/eth_getBlockByNumber/arbitrum-response.ts"; +import ethGetBlockByNumberBaseRequest from "./code-samples/eth_getBlockByNumber/base-request.ts"; +import ethGetBlockByNumberBaseResponse from "./code-samples/eth_getBlockByNumber/base-response.ts"; +import ethGetBlockByNumberEthereumRequest from "./code-samples/eth_getBlockByNumber/ethereum-request.ts"; +import ethGetBlockByNumberEthereumResponse from "./code-samples/eth_getBlockByNumber/ethereum-response.ts"; +import ethGetBlockByNumberOptimismRequest from "./code-samples/eth_getBlockByNumber/optimism-request.ts"; +import ethGetBlockByNumberOptimismResponse from "./code-samples/eth_getBlockByNumber/optimism-response.ts"; +import ethGetBlockByNumberPolygonRequest from "./code-samples/eth_getBlockByNumber/polygon-request.ts"; +import ethGetBlockByNumberPolygonResponse from "./code-samples/eth_getBlockByNumber/polygon-response.ts"; +import ethGetBlockReceiptsArbitrumRequest from "./code-samples/eth_getBlockReceipts/arbitrum-request.ts"; +import ethGetBlockReceiptsArbitrumResponse from "./code-samples/eth_getBlockReceipts/arbitrum-response.ts"; +import ethGetBlockReceiptsBaseRequest from "./code-samples/eth_getBlockReceipts/base-request.ts"; +import ethGetBlockReceiptsBaseResponse from "./code-samples/eth_getBlockReceipts/base-response.ts"; +import ethGetBlockReceiptsEthereumRequest from "./code-samples/eth_getBlockReceipts/ethereum-request.ts"; +import ethGetBlockReceiptsEthereumResponse from "./code-samples/eth_getBlockReceipts/ethereum-response.ts"; +import ethGetBlockReceiptsOptimismRequest from "./code-samples/eth_getBlockReceipts/optimism-request.ts"; +import ethGetBlockReceiptsOptimismResponse from "./code-samples/eth_getBlockReceipts/optimism-response.ts"; +import ethGetBlockReceiptsPolygonRequest from "./code-samples/eth_getBlockReceipts/polygon-request.ts"; +import ethGetBlockReceiptsPolygonResponse from "./code-samples/eth_getBlockReceipts/polygon-response.ts"; +import ethGetLogsArbitrumRequest from "./code-samples/eth_getLogs/arbitrum-request.ts"; +import ethGetLogsArbitrumResponse from "./code-samples/eth_getLogs/arbitrum-response.ts"; +import ethGetLogsBaseRequest from "./code-samples/eth_getLogs/base-request.ts"; +import ethGetLogsBaseResponse from "./code-samples/eth_getLogs/base-response.ts"; +import ethGetLogsEthereumRequest from "./code-samples/eth_getLogs/ethereum-request.ts"; +import ethGetLogsEthereumResponse from "./code-samples/eth_getLogs/ethereum-response.ts"; +import ethGetLogsOptimismRequest from "./code-samples/eth_getLogs/optimism-request.ts"; +import ethGetLogsOptimismResponse from "./code-samples/eth_getLogs/optimism-response.ts"; +import ethGetLogsPolygonRequest from "./code-samples/eth_getLogs/polygon-request.ts"; +import ethGetLogsPolygonResponse from "./code-samples/eth_getLogs/polygon-response.ts"; +import ethGetTransactionByHashArbitrumRequest from "./code-samples/eth_getTransactionByHash/arbitrum-request.ts"; +import ethGetTransactionByHashArbitrumResponse from "./code-samples/eth_getTransactionByHash/arbitrum-response.ts"; +import ethGetTransactionByHashBaseRequest from "./code-samples/eth_getTransactionByHash/base-request.ts"; +import ethGetTransactionByHashBaseResponse from "./code-samples/eth_getTransactionByHash/base-response.ts"; +import ethGetTransactionByHashEthereumRequest from "./code-samples/eth_getTransactionByHash/ethereum-request.ts"; +import ethGetTransactionByHashEthereumResponse from "./code-samples/eth_getTransactionByHash/ethereum-response.ts"; +import ethGetTransactionByHashOptimismRequest from "./code-samples/eth_getTransactionByHash/optimism-request.ts"; +import ethGetTransactionByHashOptimismResponse from "./code-samples/eth_getTransactionByHash/optimism-response.ts"; +import ethGetTransactionByHashPolygonRequest from "./code-samples/eth_getTransactionByHash/polygon-request.ts"; +import ethGetTransactionByHashPolygonResponse from "./code-samples/eth_getTransactionByHash/polygon-response.ts"; +import ethGetTransactionCountArbitrumRequest from "./code-samples/eth_getTransactionCount/arbitrum-request.ts"; +import ethGetTransactionCountArbitrumResponse from "./code-samples/eth_getTransactionCount/arbitrum-response.ts"; +import ethGetTransactionCountBaseRequest from "./code-samples/eth_getTransactionCount/base-request.ts"; +import ethGetTransactionCountBaseResponse from "./code-samples/eth_getTransactionCount/base-response.ts"; +import ethGetTransactionCountEthereumRequest from "./code-samples/eth_getTransactionCount/ethereum-request.ts"; +import ethGetTransactionCountEthereumResponse from "./code-samples/eth_getTransactionCount/ethereum-response.ts"; +import ethGetTransactionCountOptimismRequest from "./code-samples/eth_getTransactionCount/optimism-request.ts"; +import ethGetTransactionCountOptimismResponse from "./code-samples/eth_getTransactionCount/optimism-response.ts"; +import ethGetTransactionCountPolygonRequest from "./code-samples/eth_getTransactionCount/polygon-request.ts"; +import ethGetTransactionCountPolygonResponse from "./code-samples/eth_getTransactionCount/polygon-response.ts"; +import ethGetTransactionReceiptArbitrumRequest from "./code-samples/eth_getTransactionReceipt/arbitrum-request.ts"; +import ethGetTransactionReceiptArbitrumResponse from "./code-samples/eth_getTransactionReceipt/arbitrum-response.ts"; +import ethGetTransactionReceiptBaseRequest from "./code-samples/eth_getTransactionReceipt/base-request.ts"; +import ethGetTransactionReceiptBaseResponse from "./code-samples/eth_getTransactionReceipt/base-response.ts"; +import ethGetTransactionReceiptEthereumRequest from "./code-samples/eth_getTransactionReceipt/ethereum-request.ts"; +import ethGetTransactionReceiptEthereumResponse from "./code-samples/eth_getTransactionReceipt/ethereum-response.ts"; +import ethGetTransactionReceiptOptimismRequest from "./code-samples/eth_getTransactionReceipt/optimism-request.ts"; +import ethGetTransactionReceiptOptimismResponse from "./code-samples/eth_getTransactionReceipt/optimism-response.ts"; +import ethGetTransactionReceiptPolygonRequest from "./code-samples/eth_getTransactionReceipt/polygon-request.ts"; +import ethGetTransactionReceiptPolygonResponse from "./code-samples/eth_getTransactionReceipt/polygon-response.ts"; +import getAccountInfoSolanaRequest from "./code-samples/getAccountInfo/solana-request.ts"; +import getAccountInfoSolanaResponse from "./code-samples/getAccountInfo/solana-response.ts"; +import getBalanceSolanaRequest from "./code-samples/getBalance/solana-request.ts"; +import getBalanceSolanaResponse from "./code-samples/getBalance/solana-response.ts"; +import getLatestBlockhashSolanaRequest from "./code-samples/getLatestBlockhash/solana-request.ts"; +import getLatestBlockhashSolanaResponse from "./code-samples/getLatestBlockhash/solana-response.ts"; +import getSignaturesForAddressSolanaRequest from "./code-samples/getSignaturesForAddress/solana-request.ts"; +import getSignaturesForAddressSolanaResponse from "./code-samples/getSignaturesForAddress/solana-response.ts"; +import getTokenAccountBalanceSolanaRequest from "./code-samples/getTokenAccountBalance/solana-request.ts"; +import getTokenAccountBalanceSolanaResponse from "./code-samples/getTokenAccountBalance/solana-response.ts"; +import getTokenAccountsByOwnerSolanaRequest from "./code-samples/getTokenAccountsByOwner/solana-request.ts"; +import getTokenAccountsByOwnerSolanaResponse from "./code-samples/getTokenAccountsByOwner/solana-response.ts"; +import getTransactionSolanaRequest from "./code-samples/getTransaction/solana-request.ts"; +import getTransactionSolanaResponse from "./code-samples/getTransaction/solana-response.ts"; +import type { Option } from "./CodeblockSelect.tsx"; export const CODE_SAMPLES = { arbitrum: { diff --git a/fern/components/CodeConsole/index.tsx b/fern/components/CodeConsole/index.tsx index 47608ace8..69b169bff 100644 --- a/fern/components/CodeConsole/index.tsx +++ b/fern/components/CodeConsole/index.tsx @@ -1,4 +1,4 @@ -import { CodeblockSelect } from "./CodeblockSelect"; +import { CodeblockSelect } from "./CodeblockSelect.tsx"; import { CHAIN_OPTIONS, CODE_SAMPLES, @@ -6,9 +6,9 @@ import { type Method, getDefaultMethodForChain, getMethodOptionsForChain, -} from "./codeData"; -import { highlightCode } from "./highlightCode"; -import useTheme from "./useTheme"; +} from "./codeData.ts"; +import { highlightCode } from "./highlightCode.ts"; +import useTheme from "./useTheme.tsx"; export const CodeConsole = () => { const { isDark } = useTheme(); diff --git a/fern/components/Footer.tsx b/fern/components/Footer.tsx index bf7da1c57..2e6cdc68b 100644 --- a/fern/components/Footer.tsx +++ b/fern/components/Footer.tsx @@ -1,13 +1,13 @@ -import BuiltByFern from "./BuiltWithFern"; -import AlchemyLogo from "./icons/AlchemyLogo"; -import AlchemyUniversityIcon from "./icons/AlchemyUniversityIcon"; -import DiscordIcon from "./icons/DiscordIcon"; -import EmailIcon from "./icons/EmailIcon"; -import NewsletterIcon from "./icons/NewsletterIcon"; -import RobotIcon from "./icons/RobotIcon"; -import StatusIcon from "./icons/StatusIcon"; -import SupportHubIcon from "./icons/SupportHubIcon"; -import XIcon from "./icons/XIcon"; +import BuiltByFern from "./BuiltWithFern.tsx"; +import AlchemyLogo from "./icons/AlchemyLogo.tsx"; +import AlchemyUniversityIcon from "./icons/AlchemyUniversityIcon.tsx"; +import DiscordIcon from "./icons/DiscordIcon.tsx"; +import EmailIcon from "./icons/EmailIcon.tsx"; +import NewsletterIcon from "./icons/NewsletterIcon.tsx"; +import RobotIcon from "./icons/RobotIcon.tsx"; +import StatusIcon from "./icons/StatusIcon.tsx"; +import SupportHubIcon from "./icons/SupportHubIcon.tsx"; +import XIcon from "./icons/XIcon.tsx"; /** * CONFIG diff --git a/package.json b/package.json index 7424d57ef..9db7a6a70 100644 --- a/package.json +++ b/package.json @@ -4,6 +4,7 @@ "description": "API Specs and content files for Alchemy's documentation", "packageManager": "pnpm@10.9.0", "license": "CC-BY-4.0", + "type": "module", "engines": { "node": "22.x" }, @@ -15,16 +16,18 @@ "fern:preview": "fern generate --docs --preview", "fern:publish": "fern generate --docs", "generate:rest": "./scripts/generate-open-api.sh", - "generate:rpc": "ts-node ./scripts/generate-rpc.ts", + "generate:rpc": "tsx ./scripts/generate-rpc.ts", "generate:rpc:watch": "onchange \"src/openrpc/**/*.{yaml,yml}\" -- pnpm run generate:rpc", "generate:rest:watch": "onchange \"src/openapi/**/*.{yaml,yml}\" -- pnpm run generate:rest", "generate:watch": "pnpm run generate:rpc:watch & pnpm run generate:rest:watch", - "generate:metadata": "ts-node ./scripts/generate-metadata.ts", + "generate:metadata": "tsx ./scripts/generate-metadata.ts", "generate": "pnpm run generate:rest & pnpm run generate:rpc", "clean": "rm -rf fern/api-specs", "validate:rest": "./scripts/generate-open-api.sh --validate-only", - "validate:rpc": "ts-node ./scripts/validate-rpc.ts", + "validate:rpc": "tsx ./scripts/validate-rpc.ts", "validate": "pnpm run validate:rest & pnpm run validate:rpc", + "test:run": "vitest run", + "test:coverage": "vitest run --coverage", "typecheck": "tsc --noEmit", "lint": "pnpm run lint:eslint & pnpm run lint:prettier & pnpm run typecheck", "lint:fix": "pnpm run lint:eslint:fix & pnpm run lint:prettier:fix", @@ -33,15 +36,25 @@ "lint:prettier": "prettier --cache --check \"{src,scripts}/**/*.{js,jsx,ts,tsx,md,mjs,mts,json,yml,yaml}\"", "lint:prettier:fix": "pnpm run lint:prettier --write", "lint:broken-links": "lychee .", - "add-evm-chain": "ts-node ./scripts/add-evm-chain.ts", - "prepare": "husky" + "add-evm-chain": "tsx ./scripts/add-evm-chain.ts", + "prepare": "husky", + "index:main": "tsx --env-file=.env src/content-indexer/index.ts --indexer=main --branch=main", + "index:main:preview": "tsx --env-file=.env src/content-indexer/index.ts --indexer=main --mode=preview --branch=$(git rev-parse --abbrev-ref HEAD)", + "index:sdk": "tsx --env-file=.env src/content-indexer/index.ts --indexer=sdk --branch=main", + "index:changelog": "tsx --env-file=.env src/content-indexer/index.ts --indexer=changelog --branch=main" }, "dependencies": { "@apidevtools/json-schema-ref-parser": "^12.0.2", "@open-rpc/schema-utils-js": "^2.1.2", + "@upstash/redis": "^1.35.7", + "algoliasearch": "^5.46.1", "fern-api": "3.13.0", + "gray-matter": "^4.0.3", + "js-yaml": "^4.1.1", "json-schema-merge-allof": "^0.8.1", - "ts-node": "^10.9.2" + "lodash-es": "^4.17.21", + "octokit": "^5.0.5", + "remove-markdown": "^0.6.2" }, "devDependencies": { "@eslint/js": "^9.25.0", @@ -50,9 +63,12 @@ "@trivago/prettier-plugin-sort-imports": "^5.2.2", "@types/js-yaml": "^4.0.9", "@types/json-schema-merge-allof": "^0.6.5", + "@types/lodash-es": "^4.17.12", "@types/node": "^22.14.1", "@types/react": "^19.1.12", + "@types/remove-markdown": "^0.3.4", "@typescript-eslint/parser": "^8.31.0", + "@vitest/coverage-v8": "^4.0.16", "eslint": "^9.25.1", "eslint-config-prettier": "^10.1.2", "eslint-plugin-mdx": "^3.4.1", @@ -61,13 +77,17 @@ "jiti": "^2.4.2", "lint-staged": "^15.5.1", "onchange": "^7.1.0", + "openapi-types": "^12.1.3", "prettier": "3.4.2", "remark-frontmatter": "^5.0.0", "remark-mdx": "^3.1.0", "remark-preset-lint-consistent": "^6.0.1", "remark-preset-lint-markdown-style-guide": "^6.0.1", "remark-preset-lint-recommended": "^7.0.1", + "tsx": "^4.20.6", "typescript": "^5.8.3", - "typescript-eslint": "^8.31.0" + "typescript-eslint": "^8.31.0", + "vite-tsconfig-paths": "^6.0.3", + "vitest": "^4.0.14" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index e06d33c6f..23d3c2db3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -14,15 +14,33 @@ importers: '@open-rpc/schema-utils-js': specifier: ^2.1.2 version: 2.1.2 + '@upstash/redis': + specifier: ^1.35.7 + version: 1.36.1 + algoliasearch: + specifier: ^5.46.1 + version: 5.46.2 fern-api: specifier: 3.13.0 version: 3.13.0 + gray-matter: + specifier: ^4.0.3 + version: 4.0.3 + js-yaml: + specifier: ^4.1.1 + version: 4.1.1 json-schema-merge-allof: specifier: ^0.8.1 version: 0.8.1 - ts-node: - specifier: ^10.9.2 - version: 10.9.2(@types/node@22.14.1)(typescript@5.8.3) + lodash-es: + specifier: ^4.17.21 + version: 4.17.22 + octokit: + specifier: ^5.0.5 + version: 5.0.5 + remove-markdown: + specifier: ^0.6.2 + version: 0.6.2 devDependencies: '@eslint/js': specifier: ^9.25.0 @@ -42,15 +60,24 @@ importers: '@types/json-schema-merge-allof': specifier: ^0.6.5 version: 0.6.5 + '@types/lodash-es': + specifier: ^4.17.12 + version: 4.17.12 '@types/node': specifier: ^22.14.1 version: 22.14.1 '@types/react': specifier: ^19.1.12 version: 19.1.12 + '@types/remove-markdown': + specifier: ^0.3.4 + version: 0.3.4 '@typescript-eslint/parser': specifier: ^8.31.0 version: 8.31.0(eslint@9.25.1(jiti@2.4.2))(typescript@5.8.3) + '@vitest/coverage-v8': + specifier: ^4.0.16 + version: 4.0.16(vitest@4.0.16(@opentelemetry/api@1.9.0)(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1)) eslint: specifier: ^9.25.1 version: 9.25.1(jiti@2.4.2) @@ -75,6 +102,9 @@ importers: onchange: specifier: ^7.1.0 version: 7.1.0 + openapi-types: + specifier: ^12.1.3 + version: 12.1.3 prettier: specifier: 3.4.2 version: 3.4.2 @@ -93,15 +123,80 @@ importers: remark-preset-lint-recommended: specifier: ^7.0.1 version: 7.0.1 + tsx: + specifier: ^4.20.6 + version: 4.21.0 typescript: specifier: ^5.8.3 version: 5.8.3 typescript-eslint: specifier: ^8.31.0 version: 8.31.0(eslint@9.25.1(jiti@2.4.2))(typescript@5.8.3) + vite-tsconfig-paths: + specifier: ^6.0.3 + version: 6.0.3(typescript@5.8.3)(vite@7.3.1(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1)) + vitest: + specifier: ^4.0.14 + version: 4.0.16(@opentelemetry/api@1.9.0)(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1) packages: + '@algolia/abtesting@1.12.2': + resolution: {integrity: sha512-oWknd6wpfNrmRcH0vzed3UPX0i17o4kYLM5OMITyMVM2xLgaRbIafoxL0e8mcrNNb0iORCJA0evnNDKRYth5WQ==} + engines: {node: '>= 14.0.0'} + + '@algolia/client-abtesting@5.46.2': + resolution: {integrity: sha512-oRSUHbylGIuxrlzdPA8FPJuwrLLRavOhAmFGgdAvMcX47XsyM+IOGa9tc7/K5SPvBqn4nhppOCEz7BrzOPWc4A==} + engines: {node: '>= 14.0.0'} + + '@algolia/client-analytics@5.46.2': + resolution: {integrity: sha512-EPBN2Oruw0maWOF4OgGPfioTvd+gmiNwx0HmD9IgmlS+l75DatcBkKOPNJN+0z3wBQWUO5oq602ATxIfmTQ8bA==} + engines: {node: '>= 14.0.0'} + + '@algolia/client-common@5.46.2': + resolution: {integrity: sha512-Hj8gswSJNKZ0oyd0wWissqyasm+wTz1oIsv5ZmLarzOZAp3vFEda8bpDQ8PUhO+DfkbiLyVnAxsPe4cGzWtqkg==} + engines: {node: '>= 14.0.0'} + + '@algolia/client-insights@5.46.2': + resolution: {integrity: sha512-6dBZko2jt8FmQcHCbmNLB0kCV079Mx/DJcySTL3wirgDBUH7xhY1pOuUTLMiGkqM5D8moVZTvTdRKZUJRkrwBA==} + engines: {node: '>= 14.0.0'} + + '@algolia/client-personalization@5.46.2': + resolution: {integrity: sha512-1waE2Uqh/PHNeDXGn/PM/WrmYOBiUGSVxAWqiJIj73jqPqvfzZgzdakHscIVaDl6Cp+j5dwjsZ5LCgaUr6DtmA==} + engines: {node: '>= 14.0.0'} + + '@algolia/client-query-suggestions@5.46.2': + resolution: {integrity: sha512-EgOzTZkyDcNL6DV0V/24+oBJ+hKo0wNgyrOX/mePBM9bc9huHxIY2352sXmoZ648JXXY2x//V1kropF/Spx83w==} + engines: {node: '>= 14.0.0'} + + '@algolia/client-search@5.46.2': + resolution: {integrity: sha512-ZsOJqu4HOG5BlvIFnMU0YKjQ9ZI6r3C31dg2jk5kMWPSdhJpYL9xa5hEe7aieE+707dXeMI4ej3diy6mXdZpgA==} + engines: {node: '>= 14.0.0'} + + '@algolia/ingestion@1.46.2': + resolution: {integrity: sha512-1Uw2OslTWiOFDtt83y0bGiErJYy5MizadV0nHnOoHFWMoDqWW0kQoMFI65pXqRSkVvit5zjXSLik2xMiyQJDWQ==} + engines: {node: '>= 14.0.0'} + + '@algolia/monitoring@1.46.2': + resolution: {integrity: sha512-xk9f+DPtNcddWN6E7n1hyNNsATBCHIqAvVGG2EAGHJc4AFYL18uM/kMTiOKXE/LKDPyy1JhIerrh9oYb7RBrgw==} + engines: {node: '>= 14.0.0'} + + '@algolia/recommend@5.46.2': + resolution: {integrity: sha512-NApbTPj9LxGzNw4dYnZmj2BoXiAc8NmbbH6qBNzQgXklGklt/xldTvu+FACN6ltFsTzoNU6j2mWNlHQTKGC5+Q==} + engines: {node: '>= 14.0.0'} + + '@algolia/requester-browser-xhr@5.46.2': + resolution: {integrity: sha512-ekotpCwpSp033DIIrsTpYlGUCF6momkgupRV/FA3m62SreTSZUKjgK6VTNyG7TtYfq9YFm/pnh65bATP/ZWJEg==} + engines: {node: '>= 14.0.0'} + + '@algolia/requester-fetch@5.46.2': + resolution: {integrity: sha512-gKE+ZFi/6y7saTr34wS0SqYFDcjHW4Wminv8PDZEi0/mE99+hSrbKgJWxo2ztb5eqGirQTgIh1AMVacGGWM1iw==} + engines: {node: '>= 14.0.0'} + + '@algolia/requester-node-http@5.46.2': + resolution: {integrity: sha512-ciPihkletp7ttweJ8Zt+GukSVLp2ANJHU+9ttiSxsJZThXc4Y2yJ8HGVWesW5jN1zrsZsezN71KrMx/iZsOYpg==} + engines: {node: '>= 14.0.0'} + '@apidevtools/json-schema-ref-parser@12.0.2': resolution: {integrity: sha512-SoZWqQz4YMKdw4kEMfG5w6QAy+rntjsoAT1FtvZAnVEnCR4uy9YSuDBNoVAFHgzSz0dJbISLLCSrGR2Zd7bcvA==} engines: {node: '>= 16'} @@ -118,15 +213,28 @@ packages: resolution: {integrity: sha512-4A/SCr/2KLd5jrtOMFzaKjVtAei3+2r/NChoBNoZ3EyP/+GlhoaEGoWOZUmFmoITP7zOJyHIMm+DYRd8o3PvHA==} engines: {node: '>=6.9.0'} + '@babel/helper-string-parser@7.27.1': + resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==} + engines: {node: '>=6.9.0'} + '@babel/helper-validator-identifier@7.25.9': resolution: {integrity: sha512-Ed61U6XJc3CVRfkERJWDz4dJwKe7iLmmJsbOGu9wSloNSFttHV0I8g6UAgb7qnK5ly5bGLPd4oXZlxCdANBOWQ==} engines: {node: '>=6.9.0'} + '@babel/helper-validator-identifier@7.28.5': + resolution: {integrity: sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==} + engines: {node: '>=6.9.0'} + '@babel/parser@7.27.0': resolution: {integrity: sha512-iaepho73/2Pz7w2eMS0Q5f83+0RKI7i4xmiYeBmDzfRVbQtTOG7Ts0S4HzJVsTMGI9keU8rNfuZr8DKfSt7Yyg==} engines: {node: '>=6.0.0'} hasBin: true + '@babel/parser@7.28.5': + resolution: {integrity: sha512-KKBU1VGYR7ORr3At5HAtUQ+TV3SzRCXmA/8OdDZiLDBIZxVyzXuztPjfLd3BV1PRAQGCMWWSHYhL0F8d5uHBDQ==} + engines: {node: '>=6.0.0'} + hasBin: true + '@babel/runtime@7.27.0': resolution: {integrity: sha512-VtPOkrdPHZsKc/clNqyi9WUA8TINkZ4cGk63UUE3u4pmB2k+ZMQRDuIOagv8UVd6j7k0T3+RRIb7beKTebNbcw==} engines: {node: '>=6.9.0'} @@ -143,6 +251,14 @@ packages: resolution: {integrity: sha512-H45s8fVLYjbhFH62dIJ3WtmJ6RSPt/3DRO0ZcT2SUiYiQyz3BLVb9ADEnLl91m74aQPS3AzzeajZHYOalWe3bg==} engines: {node: '>=6.9.0'} + '@babel/types@7.28.5': + resolution: {integrity: sha512-qQ5m48eI/MFLQ5PxQj4PFaprjyCTLI37ElWMmNs0K8Lk3dVeOdNpB3ks8jc7yM5CDmVC73eMVk/trk3fgmrUpA==} + engines: {node: '>=6.9.0'} + + '@bcoe/v8-coverage@1.0.2': + resolution: {integrity: sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==} + engines: {node: '>=18'} + '@blakeembrey/deque@1.0.5': resolution: {integrity: sha512-6xnwtvp9DY1EINIKdTfvfeAtCYw4OqBZJhtiqkT3ivjnEfa25VQ3TsKvaFfKm8MyGIEfE95qLe+bNEt3nB0Ylg==} @@ -196,10 +312,6 @@ packages: engines: {node: '>= 10'} hasBin: true - '@cspotcode/source-map-support@0.8.1': - resolution: {integrity: sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==} - engines: {node: '>=12'} - '@emotion/is-prop-valid@1.2.2': resolution: {integrity: sha512-uNsoYd37AFmaCdXlg6EYD1KaPOaRWRByMCYzbKUX4+hhMfrxdVSelShywL4JVaAeM/eHUOSprYBQls+/neX3pw==} @@ -209,6 +321,162 @@ packages: '@emotion/unitless@0.8.1': resolution: {integrity: sha512-KOEGMu6dmJZtpadb476IsZBclKvILjopjUii3V+7MnXIQCYh8W3NgNcgwo21n9LXZX6EDIKvqfjYxXebDwxKmQ==} + '@esbuild/aix-ppc64@0.27.2': + resolution: {integrity: sha512-GZMB+a0mOMZs4MpDbj8RJp4cw+w1WV5NYD6xzgvzUJ5Ek2jerwfO2eADyI6ExDSUED+1X8aMbegahsJi+8mgpw==} + engines: {node: '>=18'} + cpu: [ppc64] + os: [aix] + + '@esbuild/android-arm64@0.27.2': + resolution: {integrity: sha512-pvz8ZZ7ot/RBphf8fv60ljmaoydPU12VuXHImtAs0XhLLw+EXBi2BLe3OYSBslR4rryHvweW5gmkKFwTiFy6KA==} + engines: {node: '>=18'} + cpu: [arm64] + os: [android] + + '@esbuild/android-arm@0.27.2': + resolution: {integrity: sha512-DVNI8jlPa7Ujbr1yjU2PfUSRtAUZPG9I1RwW4F4xFB1Imiu2on0ADiI/c3td+KmDtVKNbi+nffGDQMfcIMkwIA==} + engines: {node: '>=18'} + cpu: [arm] + os: [android] + + '@esbuild/android-x64@0.27.2': + resolution: {integrity: sha512-z8Ank4Byh4TJJOh4wpz8g2vDy75zFL0TlZlkUkEwYXuPSgX8yzep596n6mT7905kA9uHZsf/o2OJZubl2l3M7A==} + engines: {node: '>=18'} + cpu: [x64] + os: [android] + + '@esbuild/darwin-arm64@0.27.2': + resolution: {integrity: sha512-davCD2Zc80nzDVRwXTcQP/28fiJbcOwvdolL0sOiOsbwBa72kegmVU0Wrh1MYrbuCL98Omp5dVhQFWRKR2ZAlg==} + engines: {node: '>=18'} + cpu: [arm64] + os: [darwin] + + '@esbuild/darwin-x64@0.27.2': + resolution: {integrity: sha512-ZxtijOmlQCBWGwbVmwOF/UCzuGIbUkqB1faQRf5akQmxRJ1ujusWsb3CVfk/9iZKr2L5SMU5wPBi1UWbvL+VQA==} + engines: {node: '>=18'} + cpu: [x64] + os: [darwin] + + '@esbuild/freebsd-arm64@0.27.2': + resolution: {integrity: sha512-lS/9CN+rgqQ9czogxlMcBMGd+l8Q3Nj1MFQwBZJyoEKI50XGxwuzznYdwcav6lpOGv5BqaZXqvBSiB/kJ5op+g==} + engines: {node: '>=18'} + cpu: [arm64] + os: [freebsd] + + '@esbuild/freebsd-x64@0.27.2': + resolution: {integrity: sha512-tAfqtNYb4YgPnJlEFu4c212HYjQWSO/w/h/lQaBK7RbwGIkBOuNKQI9tqWzx7Wtp7bTPaGC6MJvWI608P3wXYA==} + engines: {node: '>=18'} + cpu: [x64] + os: [freebsd] + + '@esbuild/linux-arm64@0.27.2': + resolution: {integrity: sha512-hYxN8pr66NsCCiRFkHUAsxylNOcAQaxSSkHMMjcpx0si13t1LHFphxJZUiGwojB1a/Hd5OiPIqDdXONia6bhTw==} + engines: {node: '>=18'} + cpu: [arm64] + os: [linux] + + '@esbuild/linux-arm@0.27.2': + resolution: {integrity: sha512-vWfq4GaIMP9AIe4yj1ZUW18RDhx6EPQKjwe7n8BbIecFtCQG4CfHGaHuh7fdfq+y3LIA2vGS/o9ZBGVxIDi9hw==} + engines: {node: '>=18'} + cpu: [arm] + os: [linux] + + '@esbuild/linux-ia32@0.27.2': + resolution: {integrity: sha512-MJt5BRRSScPDwG2hLelYhAAKh9imjHK5+NE/tvnRLbIqUWa+0E9N4WNMjmp/kXXPHZGqPLxggwVhz7QP8CTR8w==} + engines: {node: '>=18'} + cpu: [ia32] + os: [linux] + + '@esbuild/linux-loong64@0.27.2': + resolution: {integrity: sha512-lugyF1atnAT463aO6KPshVCJK5NgRnU4yb3FUumyVz+cGvZbontBgzeGFO1nF+dPueHD367a2ZXe1NtUkAjOtg==} + engines: {node: '>=18'} + cpu: [loong64] + os: [linux] + + '@esbuild/linux-mips64el@0.27.2': + resolution: {integrity: sha512-nlP2I6ArEBewvJ2gjrrkESEZkB5mIoaTswuqNFRv/WYd+ATtUpe9Y09RnJvgvdag7he0OWgEZWhviS1OTOKixw==} + engines: {node: '>=18'} + cpu: [mips64el] + os: [linux] + + '@esbuild/linux-ppc64@0.27.2': + resolution: {integrity: sha512-C92gnpey7tUQONqg1n6dKVbx3vphKtTHJaNG2Ok9lGwbZil6DrfyecMsp9CrmXGQJmZ7iiVXvvZH6Ml5hL6XdQ==} + engines: {node: '>=18'} + cpu: [ppc64] + os: [linux] + + '@esbuild/linux-riscv64@0.27.2': + resolution: {integrity: sha512-B5BOmojNtUyN8AXlK0QJyvjEZkWwy/FKvakkTDCziX95AowLZKR6aCDhG7LeF7uMCXEJqwa8Bejz5LTPYm8AvA==} + engines: {node: '>=18'} + cpu: [riscv64] + os: [linux] + + '@esbuild/linux-s390x@0.27.2': + resolution: {integrity: sha512-p4bm9+wsPwup5Z8f4EpfN63qNagQ47Ua2znaqGH6bqLlmJ4bx97Y9JdqxgGZ6Y8xVTixUnEkoKSHcpRlDnNr5w==} + engines: {node: '>=18'} + cpu: [s390x] + os: [linux] + + '@esbuild/linux-x64@0.27.2': + resolution: {integrity: sha512-uwp2Tip5aPmH+NRUwTcfLb+W32WXjpFejTIOWZFw/v7/KnpCDKG66u4DLcurQpiYTiYwQ9B7KOeMJvLCu/OvbA==} + engines: {node: '>=18'} + cpu: [x64] + os: [linux] + + '@esbuild/netbsd-arm64@0.27.2': + resolution: {integrity: sha512-Kj6DiBlwXrPsCRDeRvGAUb/LNrBASrfqAIok+xB0LxK8CHqxZ037viF13ugfsIpePH93mX7xfJp97cyDuTZ3cw==} + engines: {node: '>=18'} + cpu: [arm64] + os: [netbsd] + + '@esbuild/netbsd-x64@0.27.2': + resolution: {integrity: sha512-HwGDZ0VLVBY3Y+Nw0JexZy9o/nUAWq9MlV7cahpaXKW6TOzfVno3y3/M8Ga8u8Yr7GldLOov27xiCnqRZf0tCA==} + engines: {node: '>=18'} + cpu: [x64] + os: [netbsd] + + '@esbuild/openbsd-arm64@0.27.2': + resolution: {integrity: sha512-DNIHH2BPQ5551A7oSHD0CKbwIA/Ox7+78/AWkbS5QoRzaqlev2uFayfSxq68EkonB+IKjiuxBFoV8ESJy8bOHA==} + engines: {node: '>=18'} + cpu: [arm64] + os: [openbsd] + + '@esbuild/openbsd-x64@0.27.2': + resolution: {integrity: sha512-/it7w9Nb7+0KFIzjalNJVR5bOzA9Vay+yIPLVHfIQYG/j+j9VTH84aNB8ExGKPU4AzfaEvN9/V4HV+F+vo8OEg==} + engines: {node: '>=18'} + cpu: [x64] + os: [openbsd] + + '@esbuild/openharmony-arm64@0.27.2': + resolution: {integrity: sha512-LRBbCmiU51IXfeXk59csuX/aSaToeG7w48nMwA6049Y4J4+VbWALAuXcs+qcD04rHDuSCSRKdmY63sruDS5qag==} + engines: {node: '>=18'} + cpu: [arm64] + os: [openharmony] + + '@esbuild/sunos-x64@0.27.2': + resolution: {integrity: sha512-kMtx1yqJHTmqaqHPAzKCAkDaKsffmXkPHThSfRwZGyuqyIeBvf08KSsYXl+abf5HDAPMJIPnbBfXvP2ZC2TfHg==} + engines: {node: '>=18'} + cpu: [x64] + os: [sunos] + + '@esbuild/win32-arm64@0.27.2': + resolution: {integrity: sha512-Yaf78O/B3Kkh+nKABUF++bvJv5Ijoy9AN1ww904rOXZFLWVc5OLOfL56W+C8F9xn5JQZa3UX6m+IktJnIb1Jjg==} + engines: {node: '>=18'} + cpu: [arm64] + os: [win32] + + '@esbuild/win32-ia32@0.27.2': + resolution: {integrity: sha512-Iuws0kxo4yusk7sw70Xa2E2imZU5HoixzxfGCdxwBdhiDgt9vX9VUCBhqcwY7/uh//78A1hMkkROMJq9l27oLQ==} + engines: {node: '>=18'} + cpu: [ia32] + os: [win32] + + '@esbuild/win32-x64@0.27.2': + resolution: {integrity: sha512-sRdU18mcKf7F+YgheI/zGf5alZatMUTKj/jNS6l744f9u3WFu4v7twcUI9vu4mknF4Y9aDlblIie0IM+5xxaqQ==} + engines: {node: '>=18'} + cpu: [x64] + os: [win32] + '@eslint-community/eslint-utils@4.6.1': resolution: {integrity: sha512-KTsJMmobmbrFLe3LDh0PC2FXpcSYJt/MLjlkh/9LEnmKYLSYmT/0EW9JWANjeoemiuZrmogti0tW5Ch+qNUYDw==} engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0} @@ -301,11 +569,14 @@ packages: '@jridgewell/sourcemap-codec@1.5.0': resolution: {integrity: sha512-gv3ZRaISU3fjPAgNsriBRqGWQL6quFx04YMPW/zD8XMLsU32mhCCbfbO6KZFLjvYpCZ8zyDEgqsgf+PwPaM7GQ==} + '@jridgewell/sourcemap-codec@1.5.5': + resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==} + '@jridgewell/trace-mapping@0.3.25': resolution: {integrity: sha512-vNk6aEwybGtawWmy/PzwnGDOjCkLWSD2wqvjGGAgOAwCGWySYXfYoxt00IJkTF+8Lb57DwOb3Aa0o9CApepiYQ==} - '@jridgewell/trace-mapping@0.3.9': - resolution: {integrity: sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==} + '@jridgewell/trace-mapping@0.3.31': + resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==} '@jsdevtools/ono@7.1.3': resolution: {integrity: sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==} @@ -373,6 +644,113 @@ packages: resolution: {integrity: sha512-xhfYPXoV5Dy4UkY0D+v2KkwvnDfiA/8Mt3sWCGI/hM03NsYIH8ZaG6QzS9x7pje5vHZBZJ2v6VRFVTWACnqcmQ==} engines: {node: ^16.14.0 || >=18.0.0} + '@octokit/app@16.1.2': + resolution: {integrity: sha512-8j7sEpUYVj18dxvh0KWj6W/l6uAiVRBl1JBDVRqH1VHKAO/G5eRVl4yEoYACjakWers1DjUkcCHyJNQK47JqyQ==} + engines: {node: '>= 20'} + + '@octokit/auth-app@8.1.2': + resolution: {integrity: sha512-db8VO0PqXxfzI6GdjtgEFHY9tzqUql5xMFXYA12juq8TeTgPAuiiP3zid4h50lwlIP457p5+56PnJOgd2GGBuw==} + engines: {node: '>= 20'} + + '@octokit/auth-oauth-app@9.0.3': + resolution: {integrity: sha512-+yoFQquaF8OxJSxTb7rnytBIC2ZLbLqA/yb71I4ZXT9+Slw4TziV9j/kyGhUFRRTF2+7WlnIWsePZCWHs+OGjg==} + engines: {node: '>= 20'} + + '@octokit/auth-oauth-device@8.0.3': + resolution: {integrity: sha512-zh2W0mKKMh/VWZhSqlaCzY7qFyrgd9oTWmTmHaXnHNeQRCZr/CXy2jCgHo4e4dJVTiuxP5dLa0YM5p5QVhJHbw==} + engines: {node: '>= 20'} + + '@octokit/auth-oauth-user@6.0.2': + resolution: {integrity: sha512-qLoPPc6E6GJoz3XeDG/pnDhJpTkODTGG4kY0/Py154i/I003O9NazkrwJwRuzgCalhzyIeWQ+6MDvkUmKXjg/A==} + engines: {node: '>= 20'} + + '@octokit/auth-token@6.0.0': + resolution: {integrity: sha512-P4YJBPdPSpWTQ1NU4XYdvHvXJJDxM6YwpS0FZHRgP7YFkdVxsWcpWGy/NVqlAA7PcPCnMacXlRm1y2PFZRWL/w==} + engines: {node: '>= 20'} + + '@octokit/auth-unauthenticated@7.0.3': + resolution: {integrity: sha512-8Jb1mtUdmBHL7lGmop9mU9ArMRUTRhg8vp0T1VtZ4yd9vEm3zcLwmjQkhNEduKawOOORie61xhtYIhTDN+ZQ3g==} + engines: {node: '>= 20'} + + '@octokit/core@7.0.6': + resolution: {integrity: sha512-DhGl4xMVFGVIyMwswXeyzdL4uXD5OGILGX5N8Y+f6W7LhC1Ze2poSNrkF/fedpVDHEEZ+PHFW0vL14I+mm8K3Q==} + engines: {node: '>= 20'} + + '@octokit/endpoint@11.0.2': + resolution: {integrity: sha512-4zCpzP1fWc7QlqunZ5bSEjxc6yLAlRTnDwKtgXfcI/FxxGoqedDG8V2+xJ60bV2kODqcGB+nATdtap/XYq2NZQ==} + engines: {node: '>= 20'} + + '@octokit/graphql@9.0.3': + resolution: {integrity: sha512-grAEuupr/C1rALFnXTv6ZQhFuL1D8G5y8CN04RgrO4FIPMrtm+mcZzFG7dcBm+nq+1ppNixu+Jd78aeJOYxlGA==} + engines: {node: '>= 20'} + + '@octokit/oauth-app@8.0.3': + resolution: {integrity: sha512-jnAjvTsPepyUaMu9e69hYBuozEPgYqP4Z3UnpmvoIzHDpf8EXDGvTY1l1jK0RsZ194oRd+k6Hm13oRU8EoDFwg==} + engines: {node: '>= 20'} + + '@octokit/oauth-authorization-url@8.0.0': + resolution: {integrity: sha512-7QoLPRh/ssEA/HuHBHdVdSgF8xNLz/Bc5m9fZkArJE5bb6NmVkDm3anKxXPmN1zh6b5WKZPRr3697xKT/yM3qQ==} + engines: {node: '>= 20'} + + '@octokit/oauth-methods@6.0.2': + resolution: {integrity: sha512-HiNOO3MqLxlt5Da5bZbLV8Zarnphi4y9XehrbaFMkcoJ+FL7sMxH/UlUsCVxpddVu4qvNDrBdaTVE2o4ITK8ng==} + engines: {node: '>= 20'} + + '@octokit/openapi-types@27.0.0': + resolution: {integrity: sha512-whrdktVs1h6gtR+09+QsNk2+FO+49j6ga1c55YZudfEG+oKJVvJLQi3zkOm5JjiUXAagWK2tI2kTGKJ2Ys7MGA==} + + '@octokit/openapi-webhooks-types@12.1.0': + resolution: {integrity: sha512-WiuzhOsiOvb7W3Pvmhf8d2C6qaLHXrWiLBP4nJ/4kydu+wpagV5Fkz9RfQwV2afYzv3PB+3xYgp4mAdNGjDprA==} + + '@octokit/plugin-paginate-graphql@6.0.0': + resolution: {integrity: sha512-crfpnIoFiBtRkvPqOyLOsw12XsveYuY2ieP6uYDosoUegBJpSVxGwut9sxUgFFcll3VTOTqpUf8yGd8x1OmAkQ==} + engines: {node: '>= 20'} + peerDependencies: + '@octokit/core': '>=6' + + '@octokit/plugin-paginate-rest@14.0.0': + resolution: {integrity: sha512-fNVRE7ufJiAA3XUrha2omTA39M6IXIc6GIZLvlbsm8QOQCYvpq/LkMNGyFlB1d8hTDzsAXa3OKtybdMAYsV/fw==} + engines: {node: '>= 20'} + peerDependencies: + '@octokit/core': '>=6' + + '@octokit/plugin-rest-endpoint-methods@17.0.0': + resolution: {integrity: sha512-B5yCyIlOJFPqUUeiD0cnBJwWJO8lkJs5d8+ze9QDP6SvfiXSz1BF+91+0MeI1d2yxgOhU/O+CvtiZ9jSkHhFAw==} + engines: {node: '>= 20'} + peerDependencies: + '@octokit/core': '>=6' + + '@octokit/plugin-retry@8.0.3': + resolution: {integrity: sha512-vKGx1i3MC0za53IzYBSBXcrhmd+daQDzuZfYDd52X5S0M2otf3kVZTVP8bLA3EkU0lTvd1WEC2OlNNa4G+dohA==} + engines: {node: '>= 20'} + peerDependencies: + '@octokit/core': '>=7' + + '@octokit/plugin-throttling@11.0.3': + resolution: {integrity: sha512-34eE0RkFCKycLl2D2kq7W+LovheM/ex3AwZCYN8udpi6bxsyjZidb2McXs69hZhLmJlDqTSP8cH+jSRpiaijBg==} + engines: {node: '>= 20'} + peerDependencies: + '@octokit/core': ^7.0.0 + + '@octokit/request-error@7.1.0': + resolution: {integrity: sha512-KMQIfq5sOPpkQYajXHwnhjCC0slzCNScLHs9JafXc4RAJI+9f+jNDlBNaIMTvazOPLgb4BnlhGJOTbnN0wIjPw==} + engines: {node: '>= 20'} + + '@octokit/request@10.0.7': + resolution: {integrity: sha512-v93h0i1yu4idj8qFPZwjehoJx4j3Ntn+JhXsdJrG9pYaX6j/XRz2RmasMUHtNgQD39nrv/VwTWSqK0RNXR8upA==} + engines: {node: '>= 20'} + + '@octokit/types@16.0.0': + resolution: {integrity: sha512-sKq+9r1Mm4efXW1FCk7hFSeJo4QKreL/tTbR0rz/qx/r1Oa2VV83LTA/H/MuCOX7uCIJmQVRKBcbmWoySjAnSg==} + + '@octokit/webhooks-methods@6.0.0': + resolution: {integrity: sha512-MFlzzoDJVw/GcbfzVC1RLR36QqkTLUf79vLVO3D+xn7r0QgxnFoLZgtrzxiQErAjFUOdH6fas2KeQJ1yr/qaXQ==} + engines: {node: '>= 20'} + + '@octokit/webhooks@14.2.0': + resolution: {integrity: sha512-da6KbdNCV5sr1/txD896V+6W0iamFWrvVl8cHkBSPT+YlvmT3DwXa4jxZnQc+gnuTEqSWbBeoSZYTayXH9wXcw==} + engines: {node: '>= 20'} + '@open-rpc/meta-schema@1.14.9': resolution: {integrity: sha512-2/CbDzOVpcaSnMs28TsRv8MKJwJi0TTYFlQ6q6qobAH26oIuhYgcZooKf4l71emgntU6MMcFQCA0h4mJ4dBCdA==} @@ -524,12 +902,140 @@ packages: resolution: {integrity: sha512-X6VR9bbHXrI01Wh5t6TIHxFCVHcP4Iy42micKLIk/Cg6EmHVbaSDGOD6mxChXtEIrwnY+bqyUbjlXr9+YM7B9A==} engines: {node: '>=18.17.0', npm: '>=9.5.0'} + '@rollup/rollup-android-arm-eabi@4.55.1': + resolution: {integrity: sha512-9R0DM/ykwfGIlNu6+2U09ga0WXeZ9MRC2Ter8jnz8415VbuIykVuc6bhdrbORFZANDmTDvq26mJrEVTl8TdnDg==} + cpu: [arm] + os: [android] + + '@rollup/rollup-android-arm64@4.55.1': + resolution: {integrity: sha512-eFZCb1YUqhTysgW3sj/55du5cG57S7UTNtdMjCW7LwVcj3dTTcowCsC8p7uBdzKsZYa8J7IDE8lhMI+HX1vQvg==} + cpu: [arm64] + os: [android] + + '@rollup/rollup-darwin-arm64@4.55.1': + resolution: {integrity: sha512-p3grE2PHcQm2e8PSGZdzIhCKbMCw/xi9XvMPErPhwO17vxtvCN5FEA2mSLgmKlCjHGMQTP6phuQTYWUnKewwGg==} + cpu: [arm64] + os: [darwin] + + '@rollup/rollup-darwin-x64@4.55.1': + resolution: {integrity: sha512-rDUjG25C9qoTm+e02Esi+aqTKSBYwVTaoS1wxcN47/Luqef57Vgp96xNANwt5npq9GDxsH7kXxNkJVEsWEOEaQ==} + cpu: [x64] + os: [darwin] + + '@rollup/rollup-freebsd-arm64@4.55.1': + resolution: {integrity: sha512-+JiU7Jbp5cdxekIgdte0jfcu5oqw4GCKr6i3PJTlXTCU5H5Fvtkpbs4XJHRmWNXF+hKmn4v7ogI5OQPaupJgOg==} + cpu: [arm64] + os: [freebsd] + + '@rollup/rollup-freebsd-x64@4.55.1': + resolution: {integrity: sha512-V5xC1tOVWtLLmr3YUk2f6EJK4qksksOYiz/TCsFHu/R+woubcLWdC9nZQmwjOAbmExBIVKsm1/wKmEy4z4u4Bw==} + cpu: [x64] + os: [freebsd] + + '@rollup/rollup-linux-arm-gnueabihf@4.55.1': + resolution: {integrity: sha512-Rn3n+FUk2J5VWx+ywrG/HGPTD9jXNbicRtTM11e/uorplArnXZYsVifnPPqNNP5BsO3roI4n8332ukpY/zN7rQ==} + cpu: [arm] + os: [linux] + + '@rollup/rollup-linux-arm-musleabihf@4.55.1': + resolution: {integrity: sha512-grPNWydeKtc1aEdrJDWk4opD7nFtQbMmV7769hiAaYyUKCT1faPRm2av8CX1YJsZ4TLAZcg9gTR1KvEzoLjXkg==} + cpu: [arm] + os: [linux] + + '@rollup/rollup-linux-arm64-gnu@4.55.1': + resolution: {integrity: sha512-a59mwd1k6x8tXKcUxSyISiquLwB5pX+fJW9TkWU46lCqD/GRDe9uDN31jrMmVP3feI3mhAdvcCClhV8V5MhJFQ==} + cpu: [arm64] + os: [linux] + + '@rollup/rollup-linux-arm64-musl@4.55.1': + resolution: {integrity: sha512-puS1MEgWX5GsHSoiAsF0TYrpomdvkaXm0CofIMG5uVkP6IBV+ZO9xhC5YEN49nsgYo1DuuMquF9+7EDBVYu4uA==} + cpu: [arm64] + os: [linux] + + '@rollup/rollup-linux-loong64-gnu@4.55.1': + resolution: {integrity: sha512-r3Wv40in+lTsULSb6nnoudVbARdOwb2u5fpeoOAZjFLznp6tDU8kd+GTHmJoqZ9lt6/Sys33KdIHUaQihFcu7g==} + cpu: [loong64] + os: [linux] + + '@rollup/rollup-linux-loong64-musl@4.55.1': + resolution: {integrity: sha512-MR8c0+UxAlB22Fq4R+aQSPBayvYa3+9DrwG/i1TKQXFYEaoW3B5b/rkSRIypcZDdWjWnpcvxbNaAJDcSbJU3Lw==} + cpu: [loong64] + os: [linux] + + '@rollup/rollup-linux-ppc64-gnu@4.55.1': + resolution: {integrity: sha512-3KhoECe1BRlSYpMTeVrD4sh2Pw2xgt4jzNSZIIPLFEsnQn9gAnZagW9+VqDqAHgm1Xc77LzJOo2LdigS5qZ+gw==} + cpu: [ppc64] + os: [linux] + + '@rollup/rollup-linux-ppc64-musl@4.55.1': + resolution: {integrity: sha512-ziR1OuZx0vdYZZ30vueNZTg73alF59DicYrPViG0NEgDVN8/Jl87zkAPu4u6VjZST2llgEUjaiNl9JM6HH1Vdw==} + cpu: [ppc64] + os: [linux] + + '@rollup/rollup-linux-riscv64-gnu@4.55.1': + resolution: {integrity: sha512-uW0Y12ih2XJRERZ4jAfKamTyIHVMPQnTZcQjme2HMVDAHY4amf5u414OqNYC+x+LzRdRcnIG1YodLrrtA8xsxw==} + cpu: [riscv64] + os: [linux] + + '@rollup/rollup-linux-riscv64-musl@4.55.1': + resolution: {integrity: sha512-u9yZ0jUkOED1BFrqu3BwMQoixvGHGZ+JhJNkNKY/hyoEgOwlqKb62qu+7UjbPSHYjiVy8kKJHvXKv5coH4wDeg==} + cpu: [riscv64] + os: [linux] + + '@rollup/rollup-linux-s390x-gnu@4.55.1': + resolution: {integrity: sha512-/0PenBCmqM4ZUd0190j7J0UsQ/1nsi735iPRakO8iPciE7BQ495Y6msPzaOmvx0/pn+eJVVlZrNrSh4WSYLxNg==} + cpu: [s390x] + os: [linux] + + '@rollup/rollup-linux-x64-gnu@4.55.1': + resolution: {integrity: sha512-a8G4wiQxQG2BAvo+gU6XrReRRqj+pLS2NGXKm8io19goR+K8lw269eTrPkSdDTALwMmJp4th2Uh0D8J9bEV1vg==} + cpu: [x64] + os: [linux] + + '@rollup/rollup-linux-x64-musl@4.55.1': + resolution: {integrity: sha512-bD+zjpFrMpP/hqkfEcnjXWHMw5BIghGisOKPj+2NaNDuVT+8Ds4mPf3XcPHuat1tz89WRL+1wbcxKY3WSbiT7w==} + cpu: [x64] + os: [linux] + + '@rollup/rollup-openbsd-x64@4.55.1': + resolution: {integrity: sha512-eLXw0dOiqE4QmvikfQ6yjgkg/xDM+MdU9YJuP4ySTibXU0oAvnEWXt7UDJmD4UkYialMfOGFPJnIHSe/kdzPxg==} + cpu: [x64] + os: [openbsd] + + '@rollup/rollup-openharmony-arm64@4.55.1': + resolution: {integrity: sha512-xzm44KgEP11te3S2HCSyYf5zIzWmx3n8HDCc7EE59+lTcswEWNpvMLfd9uJvVX8LCg9QWG67Xt75AuHn4vgsXw==} + cpu: [arm64] + os: [openharmony] + + '@rollup/rollup-win32-arm64-msvc@4.55.1': + resolution: {integrity: sha512-yR6Bl3tMC/gBok5cz/Qi0xYnVbIxGx5Fcf/ca0eB6/6JwOY+SRUcJfI0OpeTpPls7f194as62thCt/2BjxYN8g==} + cpu: [arm64] + os: [win32] + + '@rollup/rollup-win32-ia32-msvc@4.55.1': + resolution: {integrity: sha512-3fZBidchE0eY0oFZBnekYCfg+5wAB0mbpCBuofh5mZuzIU/4jIVkbESmd2dOsFNS78b53CYv3OAtwqkZZmU5nA==} + cpu: [ia32] + os: [win32] + + '@rollup/rollup-win32-x64-gnu@4.55.1': + resolution: {integrity: sha512-xGGY5pXj69IxKb4yv/POoocPy/qmEGhimy/FoTpTSVju3FYXUQQMFCaZZXJVidsmGxRioZAwpThl/4zX41gRKg==} + cpu: [x64] + os: [win32] + + '@rollup/rollup-win32-x64-msvc@4.55.1': + resolution: {integrity: sha512-SPEpaL6DX4rmcXtnhdrQYgzQ5W2uW3SCJch88lB2zImhJRhIIK44fkUrgIV/Q8yUNfw5oyZ5vkeQsZLhCb06lw==} + cpu: [x64] + os: [win32] + '@scarf/scarf@1.4.0': resolution: {integrity: sha512-xxeapPiUXdZAE3che6f3xogoJPeZgig6omHEy1rIY5WVsB3H2BHNnZH+gHG6x91SCWyQCzWGsuL2Hh3ClO5/qQ==} '@sinclair/typebox@0.27.8': resolution: {integrity: sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA==} + '@standard-schema/spec@1.1.0': + resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==} + '@trivago/prettier-plugin-sort-imports@5.2.2': resolution: {integrity: sha512-fYDQA9e6yTNmA13TLVSA+WMQRc5Bn/c0EUBditUHNfMMxN7M82c38b1kEggVE3pLpZ0FwkwJkUEKMiOi52JXFA==} engines: {node: '>18.12'} @@ -546,17 +1052,11 @@ packages: svelte: optional: true - '@tsconfig/node10@1.0.11': - resolution: {integrity: sha512-DcRjDCujK/kCk/cUe8Xz8ZSpm8mS3mNNpta+jGCA6USEDfktlNvm1+IuZ9eTcDbNk41BHwpHHeW+N1lKCz4zOw==} - - '@tsconfig/node12@1.0.11': - resolution: {integrity: sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag==} + '@types/aws-lambda@8.10.159': + resolution: {integrity: sha512-SAP22WSGNN12OQ8PlCzGzRCZ7QDCwI85dQZbmpz7+mAk+L7j+wI7qnvmdKh+o7A5LaOp6QnOZ2NJphAZQTTHQg==} - '@tsconfig/node14@1.0.3': - resolution: {integrity: sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow==} - - '@tsconfig/node16@1.0.4': - resolution: {integrity: sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==} + '@types/chai@5.2.3': + resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==} '@types/concat-stream@2.0.3': resolution: {integrity: sha512-3qe4oQAPNwVNwK4C9c8u+VJqv9kez+2MR4qJpoPFfXtgxxif1QbFusvXzK0/Wra2VX07smostI2VMmJNSpZjuQ==} @@ -564,12 +1064,18 @@ packages: '@types/debug@4.1.12': resolution: {integrity: sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==} + '@types/deep-eql@4.0.2': + resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==} + '@types/estree-jsx@1.0.5': resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==} '@types/estree@1.0.7': resolution: {integrity: sha512-w28IoSUCJpidD/TGviZwwMJckNESJZXFu7NBZ5YJ4mEUnNraUn9Pm8HSZm/jDF1pDWYKspWE7oVphigUPRakIQ==} + '@types/estree@1.0.8': + resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==} + '@types/hast@3.0.4': resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==} @@ -585,6 +1091,12 @@ packages: '@types/json-schema@7.0.15': resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==} + '@types/lodash-es@4.17.12': + resolution: {integrity: sha512-0NgftHUcV4v34VhXm8QBSftKVXtbkBG3ViCjs6+eJ5a6y6Mi/jiFGPc1sC7QK+9BFhWrURE3EOggmWaSxL9OzQ==} + + '@types/lodash@4.17.21': + resolution: {integrity: sha512-FOvQ0YPD5NOfPgMzJihoT+Za5pdkDJWcbpuj1DjaKZIr/gxodQjY/uWEFlTNqW2ugXHUiL8lRQgw63dzKHZdeQ==} + '@types/mdast@4.0.4': resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==} @@ -597,6 +1109,9 @@ packages: '@types/react@19.1.12': resolution: {integrity: sha512-cMoR+FoAf/Jyq6+Df2/Z41jISvGZZ2eTlnsaJRptmZ76Caldwy1odD4xTr/gNV9VLj0AWgg/nmkevIyUfIIq5w==} + '@types/remove-markdown@0.3.4': + resolution: {integrity: sha512-i753EH/p02bw7bLlpfS/4CV1rdikbGiLabWyVsAvsFid3cA5RNU1frG7JycgY+NSnFwtoGlElvZVceCytecTDA==} + '@types/stylis@4.2.5': resolution: {integrity: sha512-1Xve+NMN7FWjY14vLoY5tL3BVEQ/n42YLwaqJIPYhotZ9uBHt87VceMwWQpzmdEt2TNXIorIFG+YeCUUW7RInw==} @@ -659,6 +1174,47 @@ packages: resolution: {integrity: sha512-QcGHmlRHWOl93o64ZUMNewCdwKGU6WItOU52H0djgNmn1EOrhVudrDzXz4OycCRSCPwFCDrE2iIt5vmuUdHxuQ==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + '@upstash/redis@1.36.1': + resolution: {integrity: sha512-N6SjDcgXdOcTAF+7uNoY69o7hCspe9BcA7YjQdxVu5d25avljTwyLaHBW3krWjrP0FfocgMk94qyVtQbeDp39A==} + + '@vitest/coverage-v8@4.0.16': + resolution: {integrity: sha512-2rNdjEIsPRzsdu6/9Eq0AYAzYdpP6Bx9cje9tL3FE5XzXRQF1fNU9pe/1yE8fCrS0HD+fBtt6gLPh6LI57tX7A==} + peerDependencies: + '@vitest/browser': 4.0.16 + vitest: 4.0.16 + peerDependenciesMeta: + '@vitest/browser': + optional: true + + '@vitest/expect@4.0.16': + resolution: {integrity: sha512-eshqULT2It7McaJkQGLkPjPjNph+uevROGuIMJdG3V+0BSR2w9u6J9Lwu+E8cK5TETlfou8GRijhafIMhXsimA==} + + '@vitest/mocker@4.0.16': + resolution: {integrity: sha512-yb6k4AZxJTB+q9ycAvsoxGn+j/po0UaPgajllBgt1PzoMAAmJGYFdDk0uCcRcxb3BrME34I6u8gHZTQlkqSZpg==} + peerDependencies: + msw: ^2.4.9 + vite: ^6.0.0 || ^7.0.0-0 + peerDependenciesMeta: + msw: + optional: true + vite: + optional: true + + '@vitest/pretty-format@4.0.16': + resolution: {integrity: sha512-eNCYNsSty9xJKi/UdVD8Ou16alu7AYiS2fCPRs0b1OdhJiV89buAXQLpTbe+X8V9L6qrs9CqyvU7OaAopJYPsA==} + + '@vitest/runner@4.0.16': + resolution: {integrity: sha512-VWEDm5Wv9xEo80ctjORcTQRJ539EGPB3Pb9ApvVRAY1U/WkHXmmYISqU5E79uCwcW7xYUV38gwZD+RV755fu3Q==} + + '@vitest/snapshot@4.0.16': + resolution: {integrity: sha512-sf6NcrYhYBsSYefxnry+DR8n3UV4xWZwWxYbCJUt2YdvtqzSPR7VfGrY0zsv090DAbjFZsi7ZaMi1KnSRyK1XA==} + + '@vitest/spy@4.0.16': + resolution: {integrity: sha512-4jIOWjKP0ZUaEmJm00E0cOBLU+5WE0BpeNr3XN6TEF05ltro6NJqHWxXD0kA8/Zc8Nh23AT8WQxwNG+WeROupw==} + + '@vitest/utils@4.0.16': + resolution: {integrity: sha512-h8z9yYhV3e1LEfaQ3zdypIrnAg/9hguReGZoS7Gl0aBG5xgA410zBqECqmaF/+RkTggRsfnzc1XaAHA6bmUufA==} + abbrev@2.0.0: resolution: {integrity: sha512-6/mh1E2u2YgEsCHdY0Yx5oW+61gZU+1vXaoiHHrpKeuRNNgFvS+/jrwHiQhB5apAf5oB7UB7E19ol2R2LKH8hQ==} engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0} @@ -672,10 +1228,6 @@ packages: peerDependencies: acorn: ^6.0.0 || ^7.0.0 || ^8.0.0 - acorn-walk@8.3.4: - resolution: {integrity: sha512-ueEepnujpqee2o5aIYnvHU6C0A42MNdsIDeqy5BydrkuC5R1ZuUFnm27EeFJGoEHJQgn3uleRvmTXaJgfXbt4g==} - engines: {node: '>=0.4.0'} - acorn@8.14.1: resolution: {integrity: sha512-OvQ/2pUDKmgfCg++xsTX1wGxfTaszcHVcTctW4UJB4hibJx2HXxxO5UmVgyjMa+ZDsiaf5wWLXYpRWMmBI0QHg==} engines: {node: '>=0.4.0'} @@ -688,6 +1240,10 @@ packages: ajv@6.12.6: resolution: {integrity: sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==} + algoliasearch@5.46.2: + resolution: {integrity: sha512-qqAXW9QvKf2tTyhpDA4qXv1IfBwD2eduSW6tUEBFIfCeE9gn9HQ9I5+MaKoenRuHrzk5sQoNh1/iof8mY7uD6Q==} + engines: {node: '>= 14.0.0'} + ansi-escapes@7.0.0: resolution: {integrity: sha512-GdYO7a61mR0fOlAsvC9/rIHf7L96sBc6dEWzeOu+KAea5bZyQRPIpojrVoI4AXGJS/ycu/fBTdLrUkA4ODrvjw==} engines: {node: '>=18'} @@ -719,9 +1275,19 @@ packages: arg@4.1.3: resolution: {integrity: sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==} + argparse@1.0.10: + resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==} + argparse@2.0.1: resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==} + assertion-error@2.0.1: + resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==} + engines: {node: '>=12'} + + ast-v8-to-istanbul@0.3.10: + resolution: {integrity: sha512-p4K7vMz2ZSk3wN8l5o3y2bJAoZXT3VuJI5OLTATY/01CYWumWvwkUw0SqDBnNq6IiTO3qDa1eSQDibAV8g7XOQ==} + asynckit@0.4.0: resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==} @@ -731,6 +1297,9 @@ packages: balanced-match@1.0.2: resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==} + before-after-hook@4.0.0: + resolution: {integrity: sha512-q6tR3RPqIB1pMiTRMFcZwuG5T8vwp+vUvEG0vuI6B+Rikh5BfPp2fQ82c925FOs+b0lcFQ8CFrL+KbilfZFhOQ==} + better-ajv-errors@1.2.0: resolution: {integrity: sha512-UW+IsFycygIo7bclP9h5ugkNH8EjCSgqyFB/yQ4Hqqa1OEYDtb0uFIkYE0b6+CjkgJYVM5UKI/pJPxjYe9EZlA==} engines: {node: '>= 12.13.0'} @@ -741,6 +1310,9 @@ packages: resolution: {integrity: sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==} engines: {node: '>=8'} + bottleneck@2.19.5: + resolution: {integrity: sha512-VHiNCbI1lKdl44tGrhNfU3lup0Tj/ZBMJB5/2ZbNXRCPuRCO7ed2mgcK4r17y+KB2EfuYuRaVlwNbAeaWGSpbw==} + brace-expansion@1.1.11: resolution: {integrity: sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==} @@ -775,6 +1347,10 @@ packages: ccount@2.0.1: resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==} + chai@6.2.2: + resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==} + engines: {node: '>=18'} + chalk@4.1.2: resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==} engines: {node: '>=10'} @@ -869,9 +1445,6 @@ packages: core-js@3.41.0: resolution: {integrity: sha512-SJ4/EHwS36QMJd6h/Rg+GyR4A5xE0FSI3eZ+iBVpfqf1x0eTSg1smWLHrA+2jQThZSh97fmSgFSU8B61nxosxA==} - create-require@1.1.1: - resolution: {integrity: sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==} - cross-spawn@7.0.6: resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==} engines: {node: '>= 8'} @@ -934,10 +1507,6 @@ packages: resolution: {integrity: sha512-EjePK1srD3P08o2j4f0ExnylqRs5B9tJjcp9t1krH2qRi8CCdsYfwe9JgSLurFBWwq4uOlipzfk5fHNvwFKr8Q==} engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0} - diff@4.0.2: - resolution: {integrity: sha512-58lmxKSA4BNyLz+HHMUzlOEpg09FV+ev6ZMe3vJihgdxzgcwZ8VoEEPmALCZG9LmqfVoNMMKpttIYTVG6uDY7A==} - engines: {node: '>=0.3.1'} - diff@5.2.0: resolution: {integrity: sha512-uIFDxqpRZGZ6ThOk84hEfqWoHx2devRFvpTZcTHur85vImfaxUbTW9Ryh4CpCuDnToOP1CEtXKIgytHBPVff5A==} engines: {node: '>=0.3.1'} @@ -987,6 +1556,9 @@ packages: resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==} engines: {node: '>= 0.4'} + es-module-lexer@1.7.0: + resolution: {integrity: sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==} + es-object-atoms@1.1.1: resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==} engines: {node: '>= 0.4'} @@ -998,6 +1570,11 @@ packages: es6-promise@3.3.1: resolution: {integrity: sha512-SOp9Phqvqn7jtEUxPWdWfWoLmyt2VaJ6MpvP9Comy1MceMXqE6bxvaTu4iaxpYYPzhny28Lc+M87/c2cPK6lDg==} + esbuild@0.27.2: + resolution: {integrity: sha512-HyNQImnsOC7X9PMNaCIeAm4ISCQXs5a5YasTXVliKv4uuBo1dKrG0A+uQS8M5eXjVMnLg3WgXaKvprHlFJQffw==} + engines: {node: '>=18'} + hasBin: true + escalade@3.2.0: resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==} engines: {node: '>=6'} @@ -1058,6 +1635,11 @@ packages: resolution: {integrity: sha512-0QYC8b24HWY8zjRnDTL6RiHfDbAWn63qb4LMj1Z4b076A4une81+z03Kg7l7mn/48PUTqoLptSXez8oknU8Clg==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + esprima@4.0.1: + resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==} + engines: {node: '>=4'} + hasBin: true + esquery@1.6.0: resolution: {integrity: sha512-ca9pw9fomFcKPvFLXhBKUK90ZvGibiGOvRJNbjljY7s7uq/5YO4BOzcYtJqExdx99rF6aAcnRxHmcUHcz6sQsg==} engines: {node: '>=0.10'} @@ -1076,6 +1658,9 @@ packages: estree-util-visit@2.0.0: resolution: {integrity: sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==} + estree-walker@3.0.3: + resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==} + esutils@2.0.3: resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==} engines: {node: '>=0.10.0'} @@ -1091,9 +1676,20 @@ packages: resolution: {integrity: sha512-VyhnebXciFV2DESc+p6B+y0LjSm0krU4OgJN44qFAhBY0TJ+1V61tYD2+wHusZ6F9n5K+vl8k0sTy7PEfV4qpg==} engines: {node: '>=16.17'} + expect-type@1.3.0: + resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==} + engines: {node: '>=12.0.0'} + + extend-shallow@2.0.1: + resolution: {integrity: sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==} + engines: {node: '>=0.10.0'} + extend@3.0.2: resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==} + fast-content-type-parse@3.0.0: + resolution: {integrity: sha512-ZvLdcY8P+N8mGQJahJV5G4U88CSvT1rP8ApL6uETe88MBXrBHAkZlSEySdUlyztF7ccb+Znos3TFqaepHxdhBg==} + fast-deep-equal@3.1.3: resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==} @@ -1120,6 +1716,15 @@ packages: fault@2.0.1: resolution: {integrity: sha512-WtySTkS4OKev5JtpHXnib4Gxiurzh5NCGvWrFaZ34m6JehfTUhKZvn9njTfw48t6JumVQOmrKqpmGcdwxnhqBQ==} + fdir@6.5.0: + resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==} + engines: {node: '>=12.0.0'} + peerDependencies: + picomatch: ^3 || ^4 + peerDependenciesMeta: + picomatch: + optional: true + fern-api@3.13.0: resolution: {integrity: sha512-TSWJSt6fLvcKzZMDT/t9+FPCGgNHVuaKSWkLMUKoM68SYwGkbOZ67PTBDIz5tSYWKTsUmeFVE+YK9G+xqBMzIA==} hasBin: true @@ -1200,6 +1805,9 @@ packages: resolution: {integrity: sha512-VaUJspBffn/LMCJVoMvSAdmscJyS1auj5Zulnn5UoYcY531UWmdwhRWkcGKnGU93m5HSXP9LP2usOryrBtQowA==} engines: {node: '>=16'} + get-tsconfig@4.13.0: + resolution: {integrity: sha512-1VKTZJCwBrvbd+Wn3AOgQP/2Av+TfTCOlE4AcRJE72W1ksZXbAx8PPBR9RzgTeSPzlPMHrbANMH3LbltH73wxQ==} + glob-parent@5.1.2: resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==} engines: {node: '>= 6'} @@ -1228,6 +1836,9 @@ packages: resolution: {integrity: sha512-7ACyT3wmyp3I61S4fG682L0VA2RGD9otkqGJIwNUMF1SWUombIIk+af1unuDYgMm082aHYwD+mzJvv9Iu8dsgg==} engines: {node: '>=18'} + globrex@0.1.2: + resolution: {integrity: sha512-uHJgbwAMwNFf5mLst7IWLNg14x1CkeqglJb/K3doi4dw6q2IvAAmM/Y81kevy83wP+Sst+nutFTYOGg3d1lsxg==} + gopd@1.2.0: resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==} engines: {node: '>= 0.4'} @@ -1238,6 +1849,10 @@ packages: graphemer@1.4.0: resolution: {integrity: sha512-EtKwoO6kxCL9WO5xipiHTZlSzBm7WLT627TqC/uVRd0HKmq8NXyebnNYxDoBi7wt8eTWrUrKXCOVaFq9x1kgag==} + gray-matter@4.0.3: + resolution: {integrity: sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==} + engines: {node: '>=6.0'} + handlebars@4.7.8: resolution: {integrity: sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ==} engines: {node: '>=0.4.7'} @@ -1263,6 +1878,9 @@ packages: resolution: {integrity: sha512-puUZAUKT5m8Zzvs72XWy3HtvVbTWljRE66cP60bxJzAqf2DgICo7lYTY2IHUmLnNpjYvw5bvmoHvPc0QO2a62w==} engines: {node: ^16.14.0 || >=18.0.0} + html-escaper@2.0.2: + resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==} + http2-client@1.3.5: resolution: {integrity: sha512-EC2utToWl4RKfs5zd36Mxq7nzHHBuomZboI0yYL6Y0RmBgT7Sgkq4rQ0ezFTYoIsSs7Tm9SJe+o2FcAg6GBhGA==} @@ -1333,6 +1951,10 @@ packages: is-empty@1.2.0: resolution: {integrity: sha512-F2FnH/otLNJv0J6wc73A5Xo7oHLNnqplYqZhUu01tD54DIPvxIRSTSLkrUB/M0nHO4vo1O9PDfN4KoTxCzLh/w==} + is-extendable@0.1.1: + resolution: {integrity: sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==} + engines: {node: '>=0.10.0'} + is-extglob@2.1.1: resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==} engines: {node: '>=0.10.0'} @@ -1390,6 +2012,22 @@ packages: isomorphic-fetch@3.0.0: resolution: {integrity: sha512-qvUtwJ3j6qwsF3jLxkZ72qCgjMysPzDfeV240JHiGZsANBYd+EEuu35v7dfrJ9Up0Ak07D7GGSkGhCHTqg/5wA==} + istanbul-lib-coverage@3.2.2: + resolution: {integrity: sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==} + engines: {node: '>=8'} + + istanbul-lib-report@3.0.1: + resolution: {integrity: sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==} + engines: {node: '>=10'} + + istanbul-lib-source-maps@5.0.6: + resolution: {integrity: sha512-yg2d+Em4KizZC5niWhQaIomgf5WlL4vOOjZ5xGCmF8SnPE/mDWWXgvRExdcpCgh9lLRRa1/fSYp2ymmbJ1pI+A==} + engines: {node: '>=10'} + + istanbul-reports@3.2.0: + resolution: {integrity: sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==} + engines: {node: '>=8'} + jackspeak@3.4.3: resolution: {integrity: sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==} @@ -1419,10 +2057,21 @@ packages: js-tokens@4.0.0: resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==} + js-tokens@9.0.1: + resolution: {integrity: sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==} + + js-yaml@3.14.2: + resolution: {integrity: sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==} + hasBin: true + js-yaml@4.1.0: resolution: {integrity: sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==} hasBin: true + js-yaml@4.1.1: + resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==} + hasBin: true + jsep@1.4.0: resolution: {integrity: sha512-B7qPcEVE3NVkmSJbaYxvv4cHkVW7DQsZz13pUMrfS8z8Q/BuShN+gcTXrUlPiGqM2/t/EEaI030bpxMqY8gMlw==} engines: {node: '>= 10.16.0'} @@ -1473,6 +2122,10 @@ packages: keyv@4.5.4: resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==} + kind-of@6.0.3: + resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==} + engines: {node: '>=0.10.0'} + kleur@4.1.5: resolution: {integrity: sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==} engines: {node: '>=6'} @@ -1509,6 +2162,9 @@ packages: resolution: {integrity: sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==} engines: {node: '>=10'} + lodash-es@4.17.22: + resolution: {integrity: sha512-XEawp1t0gxSi9x01glktRZ5HDy0HXqrM0x5pXQM98EaI0NxO6jVM7omDOxsuEo5UIASAnm2bRp1Jt/e0a2XU8Q==} + lodash.merge@4.6.2: resolution: {integrity: sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==} @@ -1535,8 +2191,15 @@ packages: lunr@2.3.9: resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} - make-error@1.3.6: - resolution: {integrity: sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==} + magic-string@0.30.21: + resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==} + + magicast@0.5.1: + resolution: {integrity: sha512-xrHS24IxaLrvuo613F719wvOIv9xPHFWQHuvGUBmPnCA/3MQxKI3b+r7n1jAoDHmsbC5bRhTZYR77invLAxVnw==} + + make-dir@4.0.0: + resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==} + engines: {node: '>=10'} mark.js@8.11.1: resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==} @@ -1834,6 +2497,13 @@ packages: resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==} engines: {node: '>=0.10.0'} + obug@2.1.1: + resolution: {integrity: sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==} + + octokit@5.0.5: + resolution: {integrity: sha512-4+/OFSqOjoyULo7eN7EA97DE0Xydj/PW5aIckxqQIoFjFwqXKuFCvXUJObyJfBF9Khu4RL/jlDRI9FPaMGfPnw==} + engines: {node: '>= 20'} + once@1.4.0: resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==} @@ -1856,6 +2526,9 @@ packages: openapi-sampler@1.6.1: resolution: {integrity: sha512-s1cIatOqrrhSj2tmJ4abFYZQK6l5v+V4toO5q1Pa0DyN8mtyqy2I+Qrj5W9vOELEtybIMQs/TBZGVO/DtTFK8w==} + openapi-types@12.1.3: + resolution: {integrity: sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw==} + optionator@0.9.4: resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==} engines: {node: '>= 0.8.0'} @@ -1908,6 +2581,9 @@ packages: resolution: {integrity: sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==} engines: {node: '>=16 || 14 >=14.18'} + pathe@2.0.3: + resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==} + perfect-scrollbar@1.5.6: resolution: {integrity: sha512-rixgxw3SxyJbCaSpo1n35A/fwI1r2rdwMKOTCg/AcG+xOEyZcE8UHVjpZMFCVImzsFoCZeJTT+M/rdEIQYO2nw==} @@ -1918,6 +2594,10 @@ packages: resolution: {integrity: sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==} engines: {node: '>=8.6'} + picomatch@4.0.3: + resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==} + engines: {node: '>=12'} + pidtree@0.6.0: resolution: {integrity: sha512-eG2dWTVw5bzqGRztnHExczNxt5VGsE6OwTeCG3fdUf9KBsZzO3R5OIIIzWR+iZA0NtZ+RDVdaoE2dK1cn6jH4g==} engines: {node: '>=0.10'} @@ -1938,6 +2618,10 @@ packages: resolution: {integrity: sha512-OCVPnIObs4N29kxTjzLfUryOkvZEq+pf8jTF0lg8E7uETuWHA+v7j3c/xJmiqpX450191LlmZfUKkXxkTry7nA==} engines: {node: ^10 || ^12 || >=14} + postcss@8.5.6: + resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==} + engines: {node: ^10 || ^12 || >=14} + prelude-ls@1.2.1: resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==} engines: {node: '>= 0.8.0'} @@ -2213,6 +2897,9 @@ packages: remark-stringify@11.0.0: resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==} + remove-markdown@0.6.2: + resolution: {integrity: sha512-EijDXJZbzpGbQBd852ViUzcqgpMujthM+SAEHiWCMcZonRbZ+xViWKLJA/vrwbDwYdxrs1aFDjpBhcGrZoJRGA==} + require-directory@2.1.1: resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==} engines: {node: '>=0.10.0'} @@ -2225,6 +2912,9 @@ packages: resolution: {integrity: sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==} engines: {node: '>=4'} + resolve-pkg-maps@1.0.0: + resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==} + restore-cursor@5.1.0: resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==} engines: {node: '>=18'} @@ -2240,6 +2930,11 @@ packages: rfdc@1.4.1: resolution: {integrity: sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==} + rollup@4.55.1: + resolution: {integrity: sha512-wDv/Ht1BNHB4upNbK74s9usvl7hObDnvVzknxqY/E/O3X6rW1U1rV1aENEfJ54eFZDTNo7zv1f5N4edCluH7+A==} + engines: {node: '>=18.0.0', npm: '>=8.0.0'} + hasBin: true + run-applescript@7.0.0: resolution: {integrity: sha512-9by4Ij99JUr/MCFBUkDKLWK3G9HVXmabKz9U5MlIAIuvuzkiOicRYs8XJLxX+xahD+mLiiCYDqF9dKAgtzKP1A==} engines: {node: '>=18'} @@ -2257,6 +2952,10 @@ packages: scheduler@0.26.0: resolution: {integrity: sha512-NlHwttCI/l5gCPR3D1nNXtWABUmBwvZpEQiD4IXSbIDq8BzLIK/7Ir5gTFSGZDUu37K5cMNp0hFtzO38sC7gWA==} + section-matter@1.0.0: + resolution: {integrity: sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==} + engines: {node: '>=4'} + semver@7.7.1: resolution: {integrity: sha512-hlq8tAfn0m/61p4BVRcPzIGr6LKiMwo4VM6dGi6pt4qcRkmNzTcWq6eCEjEh+qXjkMDvPlOFFSGwQjoEa6gyMA==} engines: {node: '>=10'} @@ -2294,6 +2993,9 @@ packages: should@13.2.3: resolution: {integrity: sha512-ggLesLtu2xp+ZxI+ysJTmNjh2U0TsC+rQ/pfED9bUZZ4DKefP27D+7YJVVTvKsmjLpIi9jAa7itwDGkDDmt1GQ==} + siginfo@2.0.0: + resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==} + signal-exit@4.1.0: resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==} engines: {node: '>=14'} @@ -2336,6 +3038,15 @@ packages: spdx-license-ids@3.0.21: resolution: {integrity: sha512-Bvg/8F5XephndSK3JffaRqdT+gyhfqIPwDHpX80tJrF8QQRYMo8sNMeaZ2Dp5+jhwKnUmIOyFFQfHRkjJm5nXg==} + sprintf-js@1.0.3: + resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==} + + stackback@0.0.2: + resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==} + + std-env@3.10.0: + resolution: {integrity: sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==} + stickyfill@1.1.1: resolution: {integrity: sha512-GCp7vHAfpao+Qh/3Flh9DXEJ/qSi0KJwJw6zYlZOtRYXWUIpMM6mC2rIep/dK8RQqwW0KxGJIllmjPIBOGN8AA==} @@ -2373,6 +3084,10 @@ packages: resolution: {integrity: sha512-iq6eVVI64nQQTRYq2KtEg2d2uU7LElhTJwsH4YzIHZshxlgZms/wIc4VoDQTlG/IvVIrBKG06CrZnp0qv7hkcQ==} engines: {node: '>=12'} + strip-bom-string@1.0.0: + resolution: {integrity: sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g==} + engines: {node: '>=0.10.0'} + strip-final-newline@3.0.0: resolution: {integrity: sha512-dOESqjYr96iWYylGObzd39EuNTa5VJxyvVAEm5Jnh7KGo75V43Hk1odPQkNDyXNmUR6k+gEiDVXnjB8HJ3crXw==} engines: {node: '>=12'} @@ -2410,10 +3125,29 @@ packages: resolution: {integrity: sha512-Q/XQKRaJiLiFIBNN+mndW7S/RHxvwzuZS6ZwmRzUBqJBv/5QIKCEwkBC8GBf8EQJKYnaFs0wOZbKTXBPj8L9oQ==} engines: {node: ^14.18.0 || >=16.0.0} + tinybench@2.9.0: + resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==} + + tinyexec@1.0.2: + resolution: {integrity: sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==} + engines: {node: '>=18'} + + tinyglobby@0.2.15: + resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==} + engines: {node: '>=12.0.0'} + + tinyrainbow@3.0.3: + resolution: {integrity: sha512-PSkbLUoxOFRzJYjjxHJt9xro7D+iilgMX/C9lawzVuYiIdcihh9DXmVibBe8lmcFrRi/VzlPjBxbN7rH24q8/Q==} + engines: {node: '>=14.0.0'} + to-regex-range@5.0.1: resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==} engines: {node: '>=8.0'} + toad-cache@3.7.0: + resolution: {integrity: sha512-/m8M+2BJUpoJdgAHoG+baCwBT+tf2VraSfkBgl0Y00qIWt41DJ8R5B8nsEw0I58YwF5IZH6z24/2TobDKnqSWw==} + engines: {node: '>=12'} + tr46@0.0.3: resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==} @@ -2430,18 +3164,14 @@ packages: peerDependencies: typescript: '>=4.8.4' - ts-node@10.9.2: - resolution: {integrity: sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==} + tsconfck@3.1.6: + resolution: {integrity: sha512-ks6Vjr/jEw0P1gmOVwutM3B7fWxoWBL2KRDb1JfqGVawBmO5UsvmWOQFGHBPl5yxYz4eERr19E6L7NMv+Fej4w==} + engines: {node: ^18 || >=20} hasBin: true peerDependencies: - '@swc/core': '>=1.2.50' - '@swc/wasm': '>=1.2.50' - '@types/node': '*' - typescript: '>=2.7' + typescript: ^5.0.0 peerDependenciesMeta: - '@swc/core': - optional: true - '@swc/wasm': + typescript: optional: true tslib@2.6.2: @@ -2450,6 +3180,11 @@ packages: tslib@2.8.1: resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==} + tsx@4.21.0: + resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==} + engines: {node: '>=18.0.0'} + hasBin: true + type-check@0.4.0: resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==} engines: {node: '>= 0.8.0'} @@ -2478,6 +3213,9 @@ packages: engines: {node: '>=0.8.0'} hasBin: true + uncrypto@0.1.3: + resolution: {integrity: sha512-Ql87qFHB3s/De2ClA9e0gsnS6zXG27SkTiSJwjCc9MebbfapQfuPzumMIUMi38ezPZVNFcHI9sUIepeQfw8J8Q==} + undici-types@6.21.0: resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==} @@ -2518,6 +3256,12 @@ packages: unist-util-visit@5.0.0: resolution: {integrity: sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==} + universal-github-app-jwt@2.2.2: + resolution: {integrity: sha512-dcmbeSrOdTnsjGjUfAlqNDJrhxXizjAz94ija9Qw8YkZ1uu0d+GoZzyH+Jb9tIIqvGsadUfwg+22k5aDqqwzbw==} + + universal-user-agent@7.0.3: + resolution: {integrity: sha512-TmnEAEAsBJVZM/AADELsK76llnwcf9vMKuPz8JflO1frO8Lchitr0fNaN9d+Ap0BjKtqWqd/J17qeDnXh8CL2A==} + universalify@2.0.1: resolution: {integrity: sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==} engines: {node: '>= 10.0.0'} @@ -2544,9 +3288,6 @@ packages: engines: {node: '>=8'} hasBin: true - v8-compile-cache-lib@3.0.1: - resolution: {integrity: sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==} - validate-npm-package-license@3.0.4: resolution: {integrity: sha512-DpKm2Ui/xN7/HQKCtpZxoRWBhZ9Z0kqtygG8XCgNQ8ZlDnxuQmWhj566j8fN4Cu3/JmbhsDo7fcAJq4s9h27Ew==} @@ -2587,6 +3328,88 @@ packages: vfile@6.0.3: resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==} + vite-tsconfig-paths@6.0.3: + resolution: {integrity: sha512-7bL7FPX/DSviaZGYUKowWF1AiDVWjMjxNbE8lyaVGDezkedWqfGhlnQ4BZXre0ZN5P4kAgIJfAlgFDVyjrCIyg==} + peerDependencies: + vite: '*' + peerDependenciesMeta: + vite: + optional: true + + vite@7.3.1: + resolution: {integrity: sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==} + engines: {node: ^20.19.0 || >=22.12.0} + hasBin: true + peerDependencies: + '@types/node': ^20.19.0 || >=22.12.0 + jiti: '>=1.21.0' + less: ^4.0.0 + lightningcss: ^1.21.0 + sass: ^1.70.0 + sass-embedded: ^1.70.0 + stylus: '>=0.54.8' + sugarss: ^5.0.0 + terser: ^5.16.0 + tsx: ^4.8.1 + yaml: ^2.4.2 + peerDependenciesMeta: + '@types/node': + optional: true + jiti: + optional: true + less: + optional: true + lightningcss: + optional: true + sass: + optional: true + sass-embedded: + optional: true + stylus: + optional: true + sugarss: + optional: true + terser: + optional: true + tsx: + optional: true + yaml: + optional: true + + vitest@4.0.16: + resolution: {integrity: sha512-E4t7DJ9pESL6E3I8nFjPa4xGUd3PmiWDLsDztS2qXSJWfHtbQnwAWylaBvSNY48I3vr8PTqIZlyK8TE3V3CA4Q==} + engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0} + hasBin: true + peerDependencies: + '@edge-runtime/vm': '*' + '@opentelemetry/api': ^1.9.0 + '@types/node': ^20.0.0 || ^22.0.0 || >=24.0.0 + '@vitest/browser-playwright': 4.0.16 + '@vitest/browser-preview': 4.0.16 + '@vitest/browser-webdriverio': 4.0.16 + '@vitest/ui': 4.0.16 + happy-dom: '*' + jsdom: '*' + peerDependenciesMeta: + '@edge-runtime/vm': + optional: true + '@opentelemetry/api': + optional: true + '@types/node': + optional: true + '@vitest/browser-playwright': + optional: true + '@vitest/browser-preview': + optional: true + '@vitest/browser-webdriverio': + optional: true + '@vitest/ui': + optional: true + happy-dom: + optional: true + jsdom: + optional: true + walk-up-path@3.0.1: resolution: {integrity: sha512-9YlCL/ynK3CTlrSRrDxZvUauLzAswPCrsaCgilqFevUYpeEW0/3ScEjaa3kbW/T0ghhkEr7mv+fpjqn1Y1YuTA==} @@ -2609,6 +3432,11 @@ packages: engines: {node: ^16.13.0 || >=18.0.0} hasBin: true + why-is-node-running@2.3.0: + resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==} + engines: {node: '>=8'} + hasBin: true + word-wrap@1.2.5: resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==} engines: {node: '>=0.10.0'} @@ -2667,10 +3495,6 @@ packages: resolution: {integrity: sha512-xBBulfCc8Y6gLFcrPvtqKz9hz8SO0l1Ni8GgDekvBX2ro0HRQImDGnikfc33cgzcYUSncapnNcZDjVFIH3f6KQ==} engines: {node: '>=12'} - yn@3.1.1: - resolution: {integrity: sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q==} - engines: {node: '>=6'} - yocto-queue@0.1.0: resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==} engines: {node: '>=10'} @@ -2680,11 +3504,95 @@ packages: snapshots: + '@algolia/abtesting@1.12.2': + dependencies: + '@algolia/client-common': 5.46.2 + '@algolia/requester-browser-xhr': 5.46.2 + '@algolia/requester-fetch': 5.46.2 + '@algolia/requester-node-http': 5.46.2 + + '@algolia/client-abtesting@5.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + '@algolia/requester-browser-xhr': 5.46.2 + '@algolia/requester-fetch': 5.46.2 + '@algolia/requester-node-http': 5.46.2 + + '@algolia/client-analytics@5.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + '@algolia/requester-browser-xhr': 5.46.2 + '@algolia/requester-fetch': 5.46.2 + '@algolia/requester-node-http': 5.46.2 + + '@algolia/client-common@5.46.2': {} + + '@algolia/client-insights@5.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + '@algolia/requester-browser-xhr': 5.46.2 + '@algolia/requester-fetch': 5.46.2 + '@algolia/requester-node-http': 5.46.2 + + '@algolia/client-personalization@5.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + '@algolia/requester-browser-xhr': 5.46.2 + '@algolia/requester-fetch': 5.46.2 + '@algolia/requester-node-http': 5.46.2 + + '@algolia/client-query-suggestions@5.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + '@algolia/requester-browser-xhr': 5.46.2 + '@algolia/requester-fetch': 5.46.2 + '@algolia/requester-node-http': 5.46.2 + + '@algolia/client-search@5.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + '@algolia/requester-browser-xhr': 5.46.2 + '@algolia/requester-fetch': 5.46.2 + '@algolia/requester-node-http': 5.46.2 + + '@algolia/ingestion@1.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + '@algolia/requester-browser-xhr': 5.46.2 + '@algolia/requester-fetch': 5.46.2 + '@algolia/requester-node-http': 5.46.2 + + '@algolia/monitoring@1.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + '@algolia/requester-browser-xhr': 5.46.2 + '@algolia/requester-fetch': 5.46.2 + '@algolia/requester-node-http': 5.46.2 + + '@algolia/recommend@5.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + '@algolia/requester-browser-xhr': 5.46.2 + '@algolia/requester-fetch': 5.46.2 + '@algolia/requester-node-http': 5.46.2 + + '@algolia/requester-browser-xhr@5.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + + '@algolia/requester-fetch@5.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + + '@algolia/requester-node-http@5.46.2': + dependencies: + '@algolia/client-common': 5.46.2 + '@apidevtools/json-schema-ref-parser@12.0.2': dependencies: '@jsdevtools/ono': 7.1.3 '@types/json-schema': 7.0.15 - js-yaml: 4.1.0 + js-yaml: 4.1.1 '@babel/code-frame@7.26.2': dependencies: @@ -2702,12 +3610,20 @@ snapshots: '@babel/helper-string-parser@7.25.9': {} + '@babel/helper-string-parser@7.27.1': {} + '@babel/helper-validator-identifier@7.25.9': {} + '@babel/helper-validator-identifier@7.28.5': {} + '@babel/parser@7.27.0': dependencies: '@babel/types': 7.27.0 + '@babel/parser@7.28.5': + dependencies: + '@babel/types': 7.28.5 + '@babel/runtime@7.27.0': dependencies: regenerator-runtime: 0.14.1 @@ -2735,6 +3651,13 @@ snapshots: '@babel/helper-string-parser': 7.25.9 '@babel/helper-validator-identifier': 7.25.9 + '@babel/types@7.28.5': + dependencies: + '@babel/helper-string-parser': 7.27.1 + '@babel/helper-validator-identifier': 7.28.5 + + '@bcoe/v8-coverage@1.0.2': {} + '@blakeembrey/deque@1.0.5': {} '@blakeembrey/template@1.2.0': {} @@ -2772,17 +3695,91 @@ snapshots: '@boundaryml/baml-linux-x64-musl': 0.211.2 '@boundaryml/baml-win32-x64-msvc': 0.211.2 - '@cspotcode/source-map-support@0.8.1': - dependencies: - '@jridgewell/trace-mapping': 0.3.9 - '@emotion/is-prop-valid@1.2.2': dependencies: '@emotion/memoize': 0.8.1 '@emotion/memoize@0.8.1': {} - '@emotion/unitless@0.8.1': {} + '@emotion/unitless@0.8.1': {} + + '@esbuild/aix-ppc64@0.27.2': + optional: true + + '@esbuild/android-arm64@0.27.2': + optional: true + + '@esbuild/android-arm@0.27.2': + optional: true + + '@esbuild/android-x64@0.27.2': + optional: true + + '@esbuild/darwin-arm64@0.27.2': + optional: true + + '@esbuild/darwin-x64@0.27.2': + optional: true + + '@esbuild/freebsd-arm64@0.27.2': + optional: true + + '@esbuild/freebsd-x64@0.27.2': + optional: true + + '@esbuild/linux-arm64@0.27.2': + optional: true + + '@esbuild/linux-arm@0.27.2': + optional: true + + '@esbuild/linux-ia32@0.27.2': + optional: true + + '@esbuild/linux-loong64@0.27.2': + optional: true + + '@esbuild/linux-mips64el@0.27.2': + optional: true + + '@esbuild/linux-ppc64@0.27.2': + optional: true + + '@esbuild/linux-riscv64@0.27.2': + optional: true + + '@esbuild/linux-s390x@0.27.2': + optional: true + + '@esbuild/linux-x64@0.27.2': + optional: true + + '@esbuild/netbsd-arm64@0.27.2': + optional: true + + '@esbuild/netbsd-x64@0.27.2': + optional: true + + '@esbuild/openbsd-arm64@0.27.2': + optional: true + + '@esbuild/openbsd-x64@0.27.2': + optional: true + + '@esbuild/openharmony-arm64@0.27.2': + optional: true + + '@esbuild/sunos-x64@0.27.2': + optional: true + + '@esbuild/win32-arm64@0.27.2': + optional: true + + '@esbuild/win32-ia32@0.27.2': + optional: true + + '@esbuild/win32-x64@0.27.2': + optional: true '@eslint-community/eslint-utils@4.6.1(eslint@9.25.1(jiti@2.4.2))': dependencies: @@ -2813,7 +3810,7 @@ snapshots: globals: 14.0.0 ignore: 5.3.2 import-fresh: 3.3.1 - js-yaml: 4.1.0 + js-yaml: 4.1.1 minimatch: 3.1.2 strip-json-comments: 3.1.1 transitivePeerDependencies: @@ -2872,15 +3869,17 @@ snapshots: '@jridgewell/sourcemap-codec@1.5.0': {} + '@jridgewell/sourcemap-codec@1.5.5': {} + '@jridgewell/trace-mapping@0.3.25': dependencies: '@jridgewell/resolve-uri': 3.1.2 '@jridgewell/sourcemap-codec': 1.5.0 - '@jridgewell/trace-mapping@0.3.9': + '@jridgewell/trace-mapping@0.3.31': dependencies: '@jridgewell/resolve-uri': 3.1.2 - '@jridgewell/sourcemap-codec': 1.5.0 + '@jridgewell/sourcemap-codec': 1.5.5 '@jsdevtools/ono@7.1.3': {} @@ -2977,6 +3976,153 @@ snapshots: dependencies: which: 4.0.0 + '@octokit/app@16.1.2': + dependencies: + '@octokit/auth-app': 8.1.2 + '@octokit/auth-unauthenticated': 7.0.3 + '@octokit/core': 7.0.6 + '@octokit/oauth-app': 8.0.3 + '@octokit/plugin-paginate-rest': 14.0.0(@octokit/core@7.0.6) + '@octokit/types': 16.0.0 + '@octokit/webhooks': 14.2.0 + + '@octokit/auth-app@8.1.2': + dependencies: + '@octokit/auth-oauth-app': 9.0.3 + '@octokit/auth-oauth-user': 6.0.2 + '@octokit/request': 10.0.7 + '@octokit/request-error': 7.1.0 + '@octokit/types': 16.0.0 + toad-cache: 3.7.0 + universal-github-app-jwt: 2.2.2 + universal-user-agent: 7.0.3 + + '@octokit/auth-oauth-app@9.0.3': + dependencies: + '@octokit/auth-oauth-device': 8.0.3 + '@octokit/auth-oauth-user': 6.0.2 + '@octokit/request': 10.0.7 + '@octokit/types': 16.0.0 + universal-user-agent: 7.0.3 + + '@octokit/auth-oauth-device@8.0.3': + dependencies: + '@octokit/oauth-methods': 6.0.2 + '@octokit/request': 10.0.7 + '@octokit/types': 16.0.0 + universal-user-agent: 7.0.3 + + '@octokit/auth-oauth-user@6.0.2': + dependencies: + '@octokit/auth-oauth-device': 8.0.3 + '@octokit/oauth-methods': 6.0.2 + '@octokit/request': 10.0.7 + '@octokit/types': 16.0.0 + universal-user-agent: 7.0.3 + + '@octokit/auth-token@6.0.0': {} + + '@octokit/auth-unauthenticated@7.0.3': + dependencies: + '@octokit/request-error': 7.1.0 + '@octokit/types': 16.0.0 + + '@octokit/core@7.0.6': + dependencies: + '@octokit/auth-token': 6.0.0 + '@octokit/graphql': 9.0.3 + '@octokit/request': 10.0.7 + '@octokit/request-error': 7.1.0 + '@octokit/types': 16.0.0 + before-after-hook: 4.0.0 + universal-user-agent: 7.0.3 + + '@octokit/endpoint@11.0.2': + dependencies: + '@octokit/types': 16.0.0 + universal-user-agent: 7.0.3 + + '@octokit/graphql@9.0.3': + dependencies: + '@octokit/request': 10.0.7 + '@octokit/types': 16.0.0 + universal-user-agent: 7.0.3 + + '@octokit/oauth-app@8.0.3': + dependencies: + '@octokit/auth-oauth-app': 9.0.3 + '@octokit/auth-oauth-user': 6.0.2 + '@octokit/auth-unauthenticated': 7.0.3 + '@octokit/core': 7.0.6 + '@octokit/oauth-authorization-url': 8.0.0 + '@octokit/oauth-methods': 6.0.2 + '@types/aws-lambda': 8.10.159 + universal-user-agent: 7.0.3 + + '@octokit/oauth-authorization-url@8.0.0': {} + + '@octokit/oauth-methods@6.0.2': + dependencies: + '@octokit/oauth-authorization-url': 8.0.0 + '@octokit/request': 10.0.7 + '@octokit/request-error': 7.1.0 + '@octokit/types': 16.0.0 + + '@octokit/openapi-types@27.0.0': {} + + '@octokit/openapi-webhooks-types@12.1.0': {} + + '@octokit/plugin-paginate-graphql@6.0.0(@octokit/core@7.0.6)': + dependencies: + '@octokit/core': 7.0.6 + + '@octokit/plugin-paginate-rest@14.0.0(@octokit/core@7.0.6)': + dependencies: + '@octokit/core': 7.0.6 + '@octokit/types': 16.0.0 + + '@octokit/plugin-rest-endpoint-methods@17.0.0(@octokit/core@7.0.6)': + dependencies: + '@octokit/core': 7.0.6 + '@octokit/types': 16.0.0 + + '@octokit/plugin-retry@8.0.3(@octokit/core@7.0.6)': + dependencies: + '@octokit/core': 7.0.6 + '@octokit/request-error': 7.1.0 + '@octokit/types': 16.0.0 + bottleneck: 2.19.5 + + '@octokit/plugin-throttling@11.0.3(@octokit/core@7.0.6)': + dependencies: + '@octokit/core': 7.0.6 + '@octokit/types': 16.0.0 + bottleneck: 2.19.5 + + '@octokit/request-error@7.1.0': + dependencies: + '@octokit/types': 16.0.0 + + '@octokit/request@10.0.7': + dependencies: + '@octokit/endpoint': 11.0.2 + '@octokit/request-error': 7.1.0 + '@octokit/types': 16.0.0 + fast-content-type-parse: 3.0.0 + universal-user-agent: 7.0.3 + + '@octokit/types@16.0.0': + dependencies: + '@octokit/openapi-types': 27.0.0 + + '@octokit/webhooks-methods@6.0.0': {} + + '@octokit/webhooks@14.2.0': + dependencies: + '@octokit/openapi-webhooks-types': 12.1.0 + '@octokit/request-error': 7.1.0 + '@octokit/webhooks-methods': 6.0.0 + '@open-rpc/meta-schema@1.14.9': {} '@open-rpc/schema-utils-js@2.1.2': @@ -3166,7 +4312,7 @@ snapshots: colorette: 1.4.0 https-proxy-agent: 7.0.6 js-levenshtein: 1.1.6 - js-yaml: 4.1.0 + js-yaml: 4.1.1 minimatch: 5.1.6 pluralize: 8.0.0 yaml-ast-parser: 0.0.43 @@ -3198,10 +4344,87 @@ snapshots: - ajv - supports-color + '@rollup/rollup-android-arm-eabi@4.55.1': + optional: true + + '@rollup/rollup-android-arm64@4.55.1': + optional: true + + '@rollup/rollup-darwin-arm64@4.55.1': + optional: true + + '@rollup/rollup-darwin-x64@4.55.1': + optional: true + + '@rollup/rollup-freebsd-arm64@4.55.1': + optional: true + + '@rollup/rollup-freebsd-x64@4.55.1': + optional: true + + '@rollup/rollup-linux-arm-gnueabihf@4.55.1': + optional: true + + '@rollup/rollup-linux-arm-musleabihf@4.55.1': + optional: true + + '@rollup/rollup-linux-arm64-gnu@4.55.1': + optional: true + + '@rollup/rollup-linux-arm64-musl@4.55.1': + optional: true + + '@rollup/rollup-linux-loong64-gnu@4.55.1': + optional: true + + '@rollup/rollup-linux-loong64-musl@4.55.1': + optional: true + + '@rollup/rollup-linux-ppc64-gnu@4.55.1': + optional: true + + '@rollup/rollup-linux-ppc64-musl@4.55.1': + optional: true + + '@rollup/rollup-linux-riscv64-gnu@4.55.1': + optional: true + + '@rollup/rollup-linux-riscv64-musl@4.55.1': + optional: true + + '@rollup/rollup-linux-s390x-gnu@4.55.1': + optional: true + + '@rollup/rollup-linux-x64-gnu@4.55.1': + optional: true + + '@rollup/rollup-linux-x64-musl@4.55.1': + optional: true + + '@rollup/rollup-openbsd-x64@4.55.1': + optional: true + + '@rollup/rollup-openharmony-arm64@4.55.1': + optional: true + + '@rollup/rollup-win32-arm64-msvc@4.55.1': + optional: true + + '@rollup/rollup-win32-ia32-msvc@4.55.1': + optional: true + + '@rollup/rollup-win32-x64-gnu@4.55.1': + optional: true + + '@rollup/rollup-win32-x64-msvc@4.55.1': + optional: true + '@scarf/scarf@1.4.0': {} '@sinclair/typebox@0.27.8': {} + '@standard-schema/spec@1.1.0': {} + '@trivago/prettier-plugin-sort-imports@5.2.2(prettier@3.4.2)': dependencies: '@babel/generator': 7.27.0 @@ -3214,13 +4437,12 @@ snapshots: transitivePeerDependencies: - supports-color - '@tsconfig/node10@1.0.11': {} - - '@tsconfig/node12@1.0.11': {} + '@types/aws-lambda@8.10.159': {} - '@tsconfig/node14@1.0.3': {} - - '@tsconfig/node16@1.0.4': {} + '@types/chai@5.2.3': + dependencies: + '@types/deep-eql': 4.0.2 + assertion-error: 2.0.1 '@types/concat-stream@2.0.3': dependencies: @@ -3230,12 +4452,16 @@ snapshots: dependencies: '@types/ms': 2.1.0 + '@types/deep-eql@4.0.2': {} + '@types/estree-jsx@1.0.5': dependencies: '@types/estree': 1.0.7 '@types/estree@1.0.7': {} + '@types/estree@1.0.8': {} + '@types/hast@3.0.4': dependencies: '@types/unist': 3.0.3 @@ -3250,6 +4476,12 @@ snapshots: '@types/json-schema@7.0.15': {} + '@types/lodash-es@4.17.12': + dependencies: + '@types/lodash': 4.17.21 + + '@types/lodash@4.17.21': {} + '@types/mdast@4.0.4': dependencies: '@types/unist': 3.0.3 @@ -3264,6 +4496,8 @@ snapshots: dependencies: csstype: 3.1.3 + '@types/remove-markdown@0.3.4': {} + '@types/stylis@4.2.5': {} '@types/supports-color@8.1.3': {} @@ -3352,6 +4586,66 @@ snapshots: '@typescript-eslint/types': 8.31.0 eslint-visitor-keys: 4.2.0 + '@upstash/redis@1.36.1': + dependencies: + uncrypto: 0.1.3 + + '@vitest/coverage-v8@4.0.16(vitest@4.0.16(@opentelemetry/api@1.9.0)(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1))': + dependencies: + '@bcoe/v8-coverage': 1.0.2 + '@vitest/utils': 4.0.16 + ast-v8-to-istanbul: 0.3.10 + istanbul-lib-coverage: 3.2.2 + istanbul-lib-report: 3.0.1 + istanbul-lib-source-maps: 5.0.6 + istanbul-reports: 3.2.0 + magicast: 0.5.1 + obug: 2.1.1 + std-env: 3.10.0 + tinyrainbow: 3.0.3 + vitest: 4.0.16(@opentelemetry/api@1.9.0)(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1) + transitivePeerDependencies: + - supports-color + + '@vitest/expect@4.0.16': + dependencies: + '@standard-schema/spec': 1.1.0 + '@types/chai': 5.2.3 + '@vitest/spy': 4.0.16 + '@vitest/utils': 4.0.16 + chai: 6.2.2 + tinyrainbow: 3.0.3 + + '@vitest/mocker@4.0.16(vite@7.3.1(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1))': + dependencies: + '@vitest/spy': 4.0.16 + estree-walker: 3.0.3 + magic-string: 0.30.21 + optionalDependencies: + vite: 7.3.1(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1) + + '@vitest/pretty-format@4.0.16': + dependencies: + tinyrainbow: 3.0.3 + + '@vitest/runner@4.0.16': + dependencies: + '@vitest/utils': 4.0.16 + pathe: 2.0.3 + + '@vitest/snapshot@4.0.16': + dependencies: + '@vitest/pretty-format': 4.0.16 + magic-string: 0.30.21 + pathe: 2.0.3 + + '@vitest/spy@4.0.16': {} + + '@vitest/utils@4.0.16': + dependencies: + '@vitest/pretty-format': 4.0.16 + tinyrainbow: 3.0.3 + abbrev@2.0.0: {} abort-controller@3.0.0: @@ -3362,10 +4656,6 @@ snapshots: dependencies: acorn: 8.14.1 - acorn-walk@8.3.4: - dependencies: - acorn: 8.14.1 - acorn@8.14.1: {} agent-base@7.1.3: {} @@ -3377,6 +4667,23 @@ snapshots: json-schema-traverse: 0.4.1 uri-js: 4.4.1 + algoliasearch@5.46.2: + dependencies: + '@algolia/abtesting': 1.12.2 + '@algolia/client-abtesting': 5.46.2 + '@algolia/client-analytics': 5.46.2 + '@algolia/client-common': 5.46.2 + '@algolia/client-insights': 5.46.2 + '@algolia/client-personalization': 5.46.2 + '@algolia/client-query-suggestions': 5.46.2 + '@algolia/client-search': 5.46.2 + '@algolia/ingestion': 1.46.2 + '@algolia/monitoring': 1.46.2 + '@algolia/recommend': 5.46.2 + '@algolia/requester-browser-xhr': 5.46.2 + '@algolia/requester-fetch': 5.46.2 + '@algolia/requester-node-http': 5.46.2 + ansi-escapes@7.0.0: dependencies: environment: 1.1.0 @@ -3400,14 +4707,28 @@ snapshots: arg@4.1.3: {} + argparse@1.0.10: + dependencies: + sprintf-js: 1.0.3 + argparse@2.0.1: {} + assertion-error@2.0.1: {} + + ast-v8-to-istanbul@0.3.10: + dependencies: + '@jridgewell/trace-mapping': 0.3.31 + estree-walker: 3.0.3 + js-tokens: 9.0.1 + asynckit@0.4.0: {} bail@2.0.2: {} balanced-match@1.0.2: {} + before-after-hook@4.0.0: {} + better-ajv-errors@1.2.0(ajv@6.12.6): dependencies: '@babel/code-frame': 7.26.2 @@ -3419,6 +4740,8 @@ snapshots: binary-extensions@2.3.0: {} + bottleneck@2.19.5: {} + brace-expansion@1.1.11: dependencies: balanced-match: 1.0.2 @@ -3451,6 +4774,8 @@ snapshots: ccount@2.0.1: {} + chai@6.2.2: {} + chalk@4.1.2: dependencies: ansi-styles: 4.3.0 @@ -3547,8 +4872,6 @@ snapshots: core-js@3.41.0: {} - create-require@1.1.1: {} - cross-spawn@7.0.6: dependencies: path-key: 3.1.1 @@ -3598,8 +4921,6 @@ snapshots: diff-sequences@29.6.3: {} - diff@4.0.2: {} - diff@5.2.0: {} dompurify@3.2.5: @@ -3636,6 +4957,8 @@ snapshots: es-errors@1.3.0: {} + es-module-lexer@1.7.0: {} + es-object-atoms@1.1.1: dependencies: es-errors: 1.3.0 @@ -3649,6 +4972,35 @@ snapshots: es6-promise@3.3.1: {} + esbuild@0.27.2: + optionalDependencies: + '@esbuild/aix-ppc64': 0.27.2 + '@esbuild/android-arm': 0.27.2 + '@esbuild/android-arm64': 0.27.2 + '@esbuild/android-x64': 0.27.2 + '@esbuild/darwin-arm64': 0.27.2 + '@esbuild/darwin-x64': 0.27.2 + '@esbuild/freebsd-arm64': 0.27.2 + '@esbuild/freebsd-x64': 0.27.2 + '@esbuild/linux-arm': 0.27.2 + '@esbuild/linux-arm64': 0.27.2 + '@esbuild/linux-ia32': 0.27.2 + '@esbuild/linux-loong64': 0.27.2 + '@esbuild/linux-mips64el': 0.27.2 + '@esbuild/linux-ppc64': 0.27.2 + '@esbuild/linux-riscv64': 0.27.2 + '@esbuild/linux-s390x': 0.27.2 + '@esbuild/linux-x64': 0.27.2 + '@esbuild/netbsd-arm64': 0.27.2 + '@esbuild/netbsd-x64': 0.27.2 + '@esbuild/openbsd-arm64': 0.27.2 + '@esbuild/openbsd-x64': 0.27.2 + '@esbuild/openharmony-arm64': 0.27.2 + '@esbuild/sunos-x64': 0.27.2 + '@esbuild/win32-arm64': 0.27.2 + '@esbuild/win32-ia32': 0.27.2 + '@esbuild/win32-x64': 0.27.2 + escalade@3.2.0: {} escape-string-regexp@4.0.0: {} @@ -3758,6 +5110,8 @@ snapshots: acorn-jsx: 5.3.2(acorn@8.14.1) eslint-visitor-keys: 4.2.0 + esprima@4.0.1: {} + esquery@1.6.0: dependencies: estraverse: 5.3.0 @@ -3775,6 +5129,10 @@ snapshots: '@types/estree-jsx': 1.0.5 '@types/unist': 3.0.3 + estree-walker@3.0.3: + dependencies: + '@types/estree': 1.0.8 + esutils@2.0.3: {} event-target-shim@5.0.1: {} @@ -3793,8 +5151,16 @@ snapshots: signal-exit: 4.1.0 strip-final-newline: 3.0.0 + expect-type@1.3.0: {} + + extend-shallow@2.0.1: + dependencies: + is-extendable: 0.1.1 + extend@3.0.2: {} + fast-content-type-parse@3.0.0: {} + fast-deep-equal@3.1.3: {} fast-glob@3.3.3: @@ -3823,6 +5189,10 @@ snapshots: dependencies: format: 0.2.2 + fdir@6.5.0(picomatch@4.0.3): + optionalDependencies: + picomatch: 4.0.3 + fern-api@3.13.0: dependencies: '@boundaryml/baml': 0.211.2 @@ -3909,6 +5279,10 @@ snapshots: get-stream@8.0.1: {} + get-tsconfig@4.13.0: + dependencies: + resolve-pkg-maps: 1.0.0 + glob-parent@5.1.2: dependencies: is-glob: 4.0.3 @@ -3941,12 +5315,21 @@ snapshots: globals@15.15.0: {} + globrex@0.1.2: {} + gopd@1.2.0: {} graceful-fs@4.2.11: {} graphemer@1.4.0: {} + gray-matter@4.0.3: + dependencies: + js-yaml: 3.14.2 + kind-of: 6.0.3 + section-matter: 1.0.0 + strip-bom-string: 1.0.0 + handlebars@4.7.8: dependencies: minimist: 1.2.8 @@ -3972,6 +5355,8 @@ snapshots: dependencies: lru-cache: 10.4.3 + html-escaper@2.0.2: {} + http2-client@1.3.5: {} https-proxy-agent@7.0.6: @@ -4026,6 +5411,8 @@ snapshots: is-empty@1.2.0: {} + is-extendable@0.1.1: {} + is-extglob@2.1.1: {} is-fullwidth-code-point@3.0.0: {} @@ -4069,6 +5456,27 @@ snapshots: transitivePeerDependencies: - encoding + istanbul-lib-coverage@3.2.2: {} + + istanbul-lib-report@3.0.1: + dependencies: + istanbul-lib-coverage: 3.2.2 + make-dir: 4.0.0 + supports-color: 7.2.0 + + istanbul-lib-source-maps@5.0.6: + dependencies: + '@jridgewell/trace-mapping': 0.3.25 + debug: 4.4.0 + istanbul-lib-coverage: 3.2.2 + transitivePeerDependencies: + - supports-color + + istanbul-reports@3.2.0: + dependencies: + html-escaper: 2.0.2 + istanbul-lib-report: 3.0.1 + jackspeak@3.4.3: dependencies: '@isaacs/cliui': 8.0.2 @@ -4099,10 +5507,21 @@ snapshots: js-tokens@4.0.0: {} + js-tokens@9.0.1: {} + + js-yaml@3.14.2: + dependencies: + argparse: 1.0.10 + esprima: 4.0.1 + js-yaml@4.1.0: dependencies: argparse: 2.0.1 + js-yaml@4.1.1: + dependencies: + argparse: 2.0.1 + jsep@1.4.0: {} jsesc@3.1.0: {} @@ -4149,6 +5568,8 @@ snapshots: dependencies: json-buffer: 3.0.1 + kind-of@6.0.3: {} + kleur@4.1.5: {} leven@3.1.0: {} @@ -4197,6 +5618,8 @@ snapshots: dependencies: p-locate: 5.0.0 + lodash-es@4.17.22: {} + lodash.merge@4.6.2: {} lodash@4.17.21: {} @@ -4221,7 +5644,19 @@ snapshots: lunr@2.3.9: {} - make-error@1.3.6: {} + magic-string@0.30.21: + dependencies: + '@jridgewell/sourcemap-codec': 1.5.5 + + magicast@0.5.1: + dependencies: + '@babel/parser': 7.28.5 + '@babel/types': 7.28.5 + source-map-js: 1.2.1 + + make-dir@4.0.0: + dependencies: + semver: 7.7.1 mark.js@8.11.1: {} @@ -4709,6 +6144,22 @@ snapshots: object-assign@4.1.1: {} + obug@2.1.1: {} + + octokit@5.0.5: + dependencies: + '@octokit/app': 16.1.2 + '@octokit/core': 7.0.6 + '@octokit/oauth-app': 8.0.3 + '@octokit/plugin-paginate-graphql': 6.0.0(@octokit/core@7.0.6) + '@octokit/plugin-paginate-rest': 14.0.0(@octokit/core@7.0.6) + '@octokit/plugin-rest-endpoint-methods': 17.0.0(@octokit/core@7.0.6) + '@octokit/plugin-retry': 8.0.3(@octokit/core@7.0.6) + '@octokit/plugin-throttling': 11.0.3(@octokit/core@7.0.6) + '@octokit/request-error': 7.1.0 + '@octokit/types': 16.0.0 + '@octokit/webhooks': 14.2.0 + once@1.4.0: dependencies: wrappy: 1.0.2 @@ -4744,6 +6195,8 @@ snapshots: fast-xml-parser: 4.5.3 json-pointer: 0.6.2 + openapi-types@12.1.3: {} + optionator@0.9.4: dependencies: deep-is: 0.1.4 @@ -4802,12 +6255,16 @@ snapshots: lru-cache: 10.4.3 minipass: 7.1.2 + pathe@2.0.3: {} + perfect-scrollbar@1.5.6: {} picocolors@1.1.1: {} picomatch@2.3.1: {} + picomatch@4.0.3: {} + pidtree@0.6.0: {} pluralize@8.0.0: {} @@ -4824,6 +6281,12 @@ snapshots: picocolors: 1.1.1 source-map-js: 1.2.1 + postcss@8.5.6: + dependencies: + nanoid: 3.3.11 + picocolors: 1.1.1 + source-map-js: 1.2.1 + prelude-ls@1.2.1: {} prettier@3.4.2: {} @@ -5518,12 +6981,16 @@ snapshots: mdast-util-to-markdown: 2.1.2 unified: 11.0.5 + remove-markdown@0.6.2: {} + require-directory@2.1.1: {} require-from-string@2.0.2: {} resolve-from@4.0.0: {} + resolve-pkg-maps@1.0.0: {} + restore-cursor@5.1.0: dependencies: onetime: 7.0.0 @@ -5535,6 +7002,37 @@ snapshots: rfdc@1.4.1: {} + rollup@4.55.1: + dependencies: + '@types/estree': 1.0.8 + optionalDependencies: + '@rollup/rollup-android-arm-eabi': 4.55.1 + '@rollup/rollup-android-arm64': 4.55.1 + '@rollup/rollup-darwin-arm64': 4.55.1 + '@rollup/rollup-darwin-x64': 4.55.1 + '@rollup/rollup-freebsd-arm64': 4.55.1 + '@rollup/rollup-freebsd-x64': 4.55.1 + '@rollup/rollup-linux-arm-gnueabihf': 4.55.1 + '@rollup/rollup-linux-arm-musleabihf': 4.55.1 + '@rollup/rollup-linux-arm64-gnu': 4.55.1 + '@rollup/rollup-linux-arm64-musl': 4.55.1 + '@rollup/rollup-linux-loong64-gnu': 4.55.1 + '@rollup/rollup-linux-loong64-musl': 4.55.1 + '@rollup/rollup-linux-ppc64-gnu': 4.55.1 + '@rollup/rollup-linux-ppc64-musl': 4.55.1 + '@rollup/rollup-linux-riscv64-gnu': 4.55.1 + '@rollup/rollup-linux-riscv64-musl': 4.55.1 + '@rollup/rollup-linux-s390x-gnu': 4.55.1 + '@rollup/rollup-linux-x64-gnu': 4.55.1 + '@rollup/rollup-linux-x64-musl': 4.55.1 + '@rollup/rollup-openbsd-x64': 4.55.1 + '@rollup/rollup-openharmony-arm64': 4.55.1 + '@rollup/rollup-win32-arm64-msvc': 4.55.1 + '@rollup/rollup-win32-ia32-msvc': 4.55.1 + '@rollup/rollup-win32-x64-gnu': 4.55.1 + '@rollup/rollup-win32-x64-msvc': 4.55.1 + fsevents: 2.3.3 + run-applescript@7.0.0: {} run-parallel@1.2.0: @@ -5549,6 +7047,11 @@ snapshots: scheduler@0.26.0: {} + section-matter@1.0.0: + dependencies: + extend-shallow: 2.0.1 + kind-of: 6.0.3 + semver@7.7.1: {} set-cookie-parser@2.7.1: {} @@ -5587,6 +7090,8 @@ snapshots: should-type-adaptors: 1.1.0 should-util: 1.0.1 + siginfo@2.0.0: {} + signal-exit@4.1.0: {} simple-websocket@9.1.0: @@ -5633,6 +7138,12 @@ snapshots: spdx-license-ids@3.0.21: {} + sprintf-js@1.0.3: {} + + stackback@0.0.2: {} + + std-env@3.10.0: {} + stickyfill@1.1.1: {} string-argv@0.3.2: {} @@ -5678,6 +7189,8 @@ snapshots: dependencies: ansi-regex: 6.1.0 + strip-bom-string@1.0.0: {} + strip-final-newline@3.0.0: {} strip-json-comments@3.1.1: {} @@ -5727,10 +7240,23 @@ snapshots: '@pkgr/core': 0.2.4 tslib: 2.8.1 + tinybench@2.9.0: {} + + tinyexec@1.0.2: {} + + tinyglobby@0.2.15: + dependencies: + fdir: 6.5.0(picomatch@4.0.3) + picomatch: 4.0.3 + + tinyrainbow@3.0.3: {} + to-regex-range@5.0.1: dependencies: is-number: 7.0.0 + toad-cache@3.7.0: {} + tr46@0.0.3: {} tree-kill@1.2.2: {} @@ -5741,28 +7267,21 @@ snapshots: dependencies: typescript: 5.8.3 - ts-node@10.9.2(@types/node@22.14.1)(typescript@5.8.3): - dependencies: - '@cspotcode/source-map-support': 0.8.1 - '@tsconfig/node10': 1.0.11 - '@tsconfig/node12': 1.0.11 - '@tsconfig/node14': 1.0.3 - '@tsconfig/node16': 1.0.4 - '@types/node': 22.14.1 - acorn: 8.14.1 - acorn-walk: 8.3.4 - arg: 4.1.3 - create-require: 1.1.1 - diff: 4.0.2 - make-error: 1.3.6 + tsconfck@3.1.6(typescript@5.8.3): + optionalDependencies: typescript: 5.8.3 - v8-compile-cache-lib: 3.0.1 - yn: 3.1.1 tslib@2.6.2: {} tslib@2.8.1: {} + tsx@4.21.0: + dependencies: + esbuild: 0.27.2 + get-tsconfig: 4.13.0 + optionalDependencies: + fsevents: 2.3.3 + type-check@0.4.0: dependencies: prelude-ls: 1.2.1 @@ -5786,6 +7305,8 @@ snapshots: uglify-js@3.19.3: optional: true + uncrypto@0.1.3: {} + undici-types@6.21.0: {} undici@6.21.2: {} @@ -5876,6 +7397,10 @@ snapshots: unist-util-is: 6.0.0 unist-util-visit-parents: 6.0.1 + universal-github-app-jwt@2.2.2: {} + + universal-user-agent@7.0.3: {} + universalify@2.0.1: {} uri-js-replace@1.0.1: {} @@ -5899,8 +7424,6 @@ snapshots: kleur: 4.1.5 sade: 1.8.1 - v8-compile-cache-lib@3.0.1: {} - validate-npm-package-license@3.0.4: dependencies: spdx-correct: 3.2.0 @@ -5959,6 +7482,70 @@ snapshots: '@types/unist': 3.0.3 vfile-message: 4.0.2 + vite-tsconfig-paths@6.0.3(typescript@5.8.3)(vite@7.3.1(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1)): + dependencies: + debug: 4.4.0 + globrex: 0.1.2 + tsconfck: 3.1.6(typescript@5.8.3) + optionalDependencies: + vite: 7.3.1(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1) + transitivePeerDependencies: + - supports-color + - typescript + + vite@7.3.1(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1): + dependencies: + esbuild: 0.27.2 + fdir: 6.5.0(picomatch@4.0.3) + picomatch: 4.0.3 + postcss: 8.5.6 + rollup: 4.55.1 + tinyglobby: 0.2.15 + optionalDependencies: + '@types/node': 22.14.1 + fsevents: 2.3.3 + jiti: 2.4.2 + tsx: 4.21.0 + yaml: 2.7.1 + + vitest@4.0.16(@opentelemetry/api@1.9.0)(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1): + dependencies: + '@vitest/expect': 4.0.16 + '@vitest/mocker': 4.0.16(vite@7.3.1(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1)) + '@vitest/pretty-format': 4.0.16 + '@vitest/runner': 4.0.16 + '@vitest/snapshot': 4.0.16 + '@vitest/spy': 4.0.16 + '@vitest/utils': 4.0.16 + es-module-lexer: 1.7.0 + expect-type: 1.3.0 + magic-string: 0.30.21 + obug: 2.1.1 + pathe: 2.0.3 + picomatch: 4.0.3 + std-env: 3.10.0 + tinybench: 2.9.0 + tinyexec: 1.0.2 + tinyglobby: 0.2.15 + tinyrainbow: 3.0.3 + vite: 7.3.1(@types/node@22.14.1)(jiti@2.4.2)(tsx@4.21.0)(yaml@2.7.1) + why-is-node-running: 2.3.0 + optionalDependencies: + '@opentelemetry/api': 1.9.0 + '@types/node': 22.14.1 + transitivePeerDependencies: + - jiti + - less + - lightningcss + - msw + - sass + - sass-embedded + - stylus + - sugarss + - terser + - tsx + - yaml + walk-up-path@3.0.1: {} webidl-conversions@3.0.1: {} @@ -5978,6 +7565,11 @@ snapshots: dependencies: isexe: 3.1.1 + why-is-node-running@2.3.0: + dependencies: + siginfo: 2.0.0 + stackback: 0.0.2 + word-wrap@1.2.5: {} wordwrap@1.0.0: {} @@ -6024,8 +7616,6 @@ snapshots: y18n: 5.0.8 yargs-parser: 20.2.9 - yn@3.1.1: {} - yocto-queue@0.1.0: {} zwitch@2.0.4: {} diff --git a/prettier.config.js b/prettier.config.cjs similarity index 100% rename from prettier.config.js rename to prettier.config.cjs diff --git a/scripts/add-evm-chain.ts b/scripts/add-evm-chain.ts index e80a87ee7..413dba172 100644 --- a/scripts/add-evm-chain.ts +++ b/scripts/add-evm-chain.ts @@ -11,7 +11,7 @@ import { validateChainName, validateUrl, writeChainFiles, -} from "../src/utils/addEvmChainHelpers"; +} from "../src/utils/addEvmChainHelpers.js"; const rl = readline.createInterface({ input: process.stdin, diff --git a/scripts/generate-rpc.ts b/scripts/generate-rpc.ts index 440eef045..091645e6f 100644 --- a/scripts/generate-rpc.ts +++ b/scripts/generate-rpc.ts @@ -1,10 +1,10 @@ import { mkdirSync, readdirSync } from "fs"; -import { generateOpenRpcSpec } from "../src/utils/generateRpcSpecs"; +import { generateOpenRpcSpec } from "../src/utils/generateRpcSpecs.ts"; import { type DerefErrorGroup, handleDerefErrors, -} from "../src/utils/generationHelpers"; +} from "../src/utils/generationHelpers.js"; const isHiddenDir = (file: string) => !file.startsWith("_") && !file.startsWith("."); diff --git a/scripts/validate-rpc.ts b/scripts/validate-rpc.ts index a035fdaac..a73a25e3c 100644 --- a/scripts/validate-rpc.ts +++ b/scripts/validate-rpc.ts @@ -1,7 +1,7 @@ import { existsSync, readFileSync } from "fs"; -import { findFilesOfType } from "../src/utils/findFilesOfType"; -import { validateRpcSpec } from "../src/utils/validateRpcSpec"; +import { findFilesOfType } from "../src/utils/findFilesOfType.ts"; +import { validateRpcSpec } from "../src/utils/validateRpcSpec.ts"; const validateOpenRpcSpecs = async (directory: string) => { if (!directory) { diff --git a/src/content-indexer/README.md b/src/content-indexer/README.md new file mode 100644 index 000000000..e4909ccf2 --- /dev/null +++ b/src/content-indexer/README.md @@ -0,0 +1,523 @@ +# Content Indexer + +Content Indexer is the indexing system that builds path indexes, navigation trees, and Algolia search records for the Alchemy docs site. It lives in the `docs` repository and processes documentation from three sources: + +1. **Main Docs** - Manual content from `docs/fern/docs.yml` (local filesystem) +2. **SDK References** - Generated content from `aa-sdk/docs/docs.yml` (GitHub API) +3. **Changelog** - Entries from `docs/fern/changelog/*.md` (local filesystem) + +## Three Indexers + +The system provides three independent indexers, each triggered by different content changes: + +### 1. Main Indexer (`pnpm index:main`) + +Indexes manual documentation content from the local `docs` repository. + +* **Trigger**: Changes to `docs/fern/docs.yml` or manual content files +* **Source**: Local filesystem (`docs/fern/`) +* **Modes**: + * `production` - Full indexing with Algolia upload (default) + * `preview` - Branch-scoped indexing without Algolia upload +* **Updates**: + * `{branch}/path-index:main` (Redis, 30-day TTL for preview branches) + * `{branch}/nav-tree:{tab}` for all tabs (Redis, 30-day TTL for preview branches) + * `{branch}_alchemy_docs` (Algolia, production mode only) + +### 2. SDK Indexer (`pnpm index:sdk`) + +Indexes SDK reference documentation from the `aa-sdk` repository. + +* **Trigger**: Changes to `aa-sdk/docs/docs.yml` +* **Source**: GitHub API (aa-sdk repo) +* **Updates**: + * `{branch}/path-index:sdk` (Redis) + * `{branch}/nav-tree:wallets` (Redis, merged with existing manual content) + * `{branch}_alchemy_docs_sdk` (Algolia) + +### 3. Changelog Indexer (`pnpm index:changelog`) + +Indexes changelog entries from date-based markdown files. + +* **Trigger**: Changes to `docs/fern/changelog/*.md` +* **Source**: Local filesystem (`docs/fern/changelog/`) +* **Updates**: + * `{branch}/path-index:changelog` (Redis) + * No navigation tree (changelogs don't have a sidebar) + * `{branch}_alchemy_docs_changelog` (Algolia) + +## Key Outputs + +Each indexer generates up to three outputs: + +1. **Path Index**: Maps URL paths to content sources (MDX files, API specs) +2. **Navigation Trees**: Hierarchical sidebar navigation for each documentation tab +3. **Algolia Index**: Searchable content records with metadata + +All data is **branch-scoped** to support preview environments. + +### Preview Mode vs Production Mode + +**Production Mode** (default): + +* Uploads to both Redis and Algolia +* Redis keys have no expiration (permanent) +* Creates branch-scoped Algolia indices + +**Preview Mode** (`--mode=preview`): + +* Uploads to Redis only (skips Algolia) +* Redis keys expire after 30 days (automatic cleanup) +* Uses production Algolia indices for search +* Only available for main and changelog indexers (SDK indexer is production-only) + +## Architecture + +### Main & SDK Indexers: 3-Phase Processing + +Both the main and SDK indexers use a unified `buildDocsContentIndex` function that processes `docs.yml` files through three phases: + +```mermaid +flowchart TD + Start[buildDocsContentIndex] --> ReadYml[Read docs.yml] + ReadYml --> Phase1[Phase 1: SCAN] + + Phase1 --> ScanDocs[scanDocsYml] + ScanDocs --> CollectPaths[Collect all MDX paths] + ScanDocs --> CollectSpecs[Collect all spec names] + + CollectPaths --> Phase2[Phase 2: BATCH FETCH] + CollectSpecs --> Phase2 + + Phase2 --> FetchContent[Fetch all content in parallel] + FetchContent --> Cache[ContentCache] + + Cache --> Phase3[Phase 3: PROCESS] + + Phase3 --> ProcessNav[visitNavigationItem with cache] + ProcessNav --> BuildOutputs[Build all outputs] + + BuildOutputs --> PathIdx[PathIndex] + BuildOutputs --> NavTrees[Navigation Trees] + BuildOutputs --> Algolia[Algolia Records] + + PathIdx --> Upload[Upload in parallel] + NavTrees --> Upload + Algolia --> Upload + + Upload --> Redis[storeToRedis] + Upload --> AlgoliaUpload[uploadToAlgolia] +``` + +**Key difference between main and SDK:** + +* **Main**: Reads from local filesystem (`docs/fern/`) +* **SDK**: Fetches from GitHub API (`aa-sdk/docs/`) + +### Changelog Indexer: Simpler Flow + +The changelog indexer reads date-based markdown files directly: + +```mermaid +flowchart TD + Start[buildChangelogIndex] --> ReadDir[Read fern/changelog/] + ReadDir --> ParseFiles[Parse date from filenames] + ParseFiles --> Parallel[Fetch all files in parallel] + Parallel --> BuildOutputs[Build PathIndex + Algolia records] + BuildOutputs --> Upload[Upload in parallel] + Upload --> Redis[storeToRedis] + Upload --> AlgoliaUpload[uploadToAlgolia] +``` + +**Simpler because:** + +* No `docs.yml` to parse +* No navigation trees needed +* Direct file-to-route mapping + +### Why This Architecture? + +With **4000+ pages**, this 3-phase approach: + +1. **Maximizes parallelization**: All content fetched simultaneously +2. **Eliminates duplicate fetches**: Single fetch per file, cached for all uses +3. **Single-pass processing**: Build all outputs in one traversal + +## Key Concepts + +### Branch-Scoped Keys + +All Redis keys and Algolia indices are scoped by branch to support preview environments: + +```text +Redis (with TTL for preview branches): +- main/path-index:main (no expiration) +- main/nav-tree:wallets (no expiration) +- feature-abc/path-index:main (30-day TTL) +- feature-abc/nav-tree:wallets (30-day TTL) + +Algolia (production mode only): +- main_alchemy_docs +- main_alchemy_docs_sdk +- main_alchemy_docs_changelog + +Note: Preview branches do NOT create Algolia indices. +Preview environments use production search indices. +``` + +### Wallets Navigation Tree Merging + +The wallets tab navigation tree requires special handling because it contains both: + +* **Manual content** (from main indexer) +* **SDK references** (from SDK indexer) + +**Bidirectional merging** ensures neither indexer overwrites the other: + +* **Main indexer**: Reads existing wallets tree → preserves SDK sections → merges with new manual sections +* **SDK indexer**: Reads existing wallets tree → preserves manual sections → merges with new SDK sections + +SDK Reference sections are always positioned **second-to-last** (before Resources section). + +### Output Data Structures + +* **Path Index**: Used by Next.js routing to determine which content to render for a given URL + * Maps paths like `wallets/getting-started` to MDX files or API operations + * Contains metadata: type (mdx/openapi/openrpc), file path, source, tab + * Stored in Redis for fast lookup at runtime: `{branch}/path-index:{type}` + +* **Navigation Trees**: Used to render sidebar navigation + * Hierarchical structure with sections, pages, and API endpoints + * One tree per top-level tab (guides, wallets, reference, etc.) + * Stored in Redis: `{branch}/nav-tree:{tab}` + +* **Algolia Index**: Used for site-wide search + * Flat list of searchable pages with content, title, breadcrumbs + * Markdown automatically stripped to plain text for better search results + * Uploaded to Algolia for full-text search: `{branch}_alchemy_docs[_{type}]` + * Updated atomically to avoid search downtime + +### ContentCache + +The `ContentCache` class provides O(1) lookup for all fetched content: + +* **MDX files**: Stores frontmatter and raw MDX body +* **API specs**: Stores parsed OpenAPI/OpenRPC specifications + +By fetching everything upfront in Phase 2, we eliminate duplicate API calls during processing. + +### Markdown Stripping + +All Algolia records automatically have markdown syntax stripped using the `remove-markdown` package in `truncateRecord()`. This ensures search results contain clean, readable text without formatting artifacts. + +### Stable ObjectIDs for Algolia + +Algolia requires unique `objectID` for each record. We generate deterministic +hashes (SHA-256, first 16 chars) from URL paths: + +* **All pages (MDX and API methods)**: Hash of the URL path (e.g., hash of + `"reference/eth-getbalance"`) + * Uniqueness: URLs are guaranteed unique by the routing system + * Stability: Paths are designed to be stable. Changes happen but infrequently + * Enables incremental index updates in the future + * Generates clean IDs like `"a3f2c8e1b9d4f6a7"` + +**Why path-based?** Paths are the web's natural unique identifier and are specifically +designed to be stable. Unlike titles or breadcrumbs, URL changes are typically +rare and intentional (considered breaking changes for SEO and bookmarks). + +**Why hashes?** Provides compact, opaque identifiers that don't expose internal +structure while maintaining the URL's uniqueness guarantee. + +## Design Decisions + +### 1. Three Independent Indexers + +**Why?** Content updates happen independently: + +* Main docs change frequently (manual edits) +* SDK refs change when aa-sdk releases +* Changelog entries added weekly + +Running separate indexers allows efficient, targeted updates without re-processing unrelated content. + +### 2. Wallets Navigation Tree Merging + +The wallets tab requires special handling because it contains both manual and SDK content. We use **bidirectional merging**: + +* **Main indexer**: Preserves existing SDK sections when updating manual content +* **SDK indexer**: Preserves existing manual sections when updating SDK refs + +This prevents either indexer from accidentally overwriting the other's content. The merge logic lives in `utils/nav-tree-merge.ts`. + +### 3. Branch-Scoped Storage + +All Redis keys and Algolia indices include the branch name to support preview environments: + +```text +main/path-index:main → Production +feature-xyz/path-index:main → Preview branch +``` + +This allows preview deployments to have independent data without interfering with production. + +### 4. Separate Algolia Indices + +Main, SDK, and changelog content use separate Algolia indices: + +```text +- main_alchemy_docs +- main_alchemy_docs_sdk +- main_alchemy_docs_changelog +``` + +**Why?** Each indexer runs independently, so separate indices allow atomic updates without affecting other content. The frontend searches all indices simultaneously using Algolia's multi-index feature. + +### 5. Atomic Index Swap for Algolia + +Each indexer fully replaces its Algolia index on every run using atomic swap: + +1. Upload to temporary index +2. Copy settings from production +3. Atomic move (replace production with temp) + +**Why?** Our objectIDs are content-based. When files move or are renamed, we generate new IDs, leaving old records orphaned. Full replacement ensures the index is always clean and up-to-date with zero search downtime. + +### 6. Markdown Stripping for Search + +All Algolia records have markdown syntax automatically stripped using `remove-markdown`. This happens in `truncateRecord()` before size checking, ensuring search results contain clean, readable text. + +## Directory Structure + +```text +content-indexer/ +├── index.ts # CLI entry point with unified runner +├── indexers/ # Indexer implementations +│ ├── main.ts # buildDocsContentIndex (main & SDK) +│ └── changelog.ts # buildChangelogIndex +├── collectors/ # Output collectors (Phase 3) +│ ├── algolia.ts # Collects Algolia search records +│ ├── navigation-trees.ts # Collects navigation trees by tab +│ ├── path-index.ts # Collects path index entries +│ └── processing-context.ts # Unified context encapsulating all collectors +├── core/ # Core processing logic (3-phase pipeline) +│ ├── scanner.ts # Phase 1: Scan docs.yml for paths/specs +│ ├── batch-fetcher.ts # Phase 2: Parallel fetch all content +│ ├── content-cache.ts # Phase 2: In-memory cache for fetched content +│ ├── build-all-outputs.ts # Phase 3: Main orchestrator +│ └── path-builder.ts # Hierarchical URL path builder +├── visitors/ # Visitor pattern for processing (Phase 3) +│ ├── index.ts # Main dispatcher (visitNavigationItem) +│ ├── visit-page.ts # Processes MDX pages +│ ├── visit-section.ts # Processes sections (with recursion) +│ ├── visit-link.ts # Processes external links +│ ├── visit-api-reference.ts # Orchestrates API spec processing +│ └── processors/ +│ ├── process-openapi.ts # Processes OpenAPI specifications +│ └── process-openrpc.ts # Processes OpenRPC specifications +├── uploaders/ # Upload to external services +│ ├── algolia.ts # Uploads to Algolia with atomic swap +│ └── redis.ts # Stores to Redis with branch scoping +├── utils/ # Utility functions +│ ├── filesystem.ts # Local file reading utilities +│ ├── github.ts # GitHub API utilities +│ ├── nav-tree-merge.ts # Wallets nav tree merging logic +│ ├── openapi.ts # OpenAPI-specific utilities +│ ├── openrpc.ts # OpenRPC-specific utilities +│ ├── navigation-helpers.ts # Navigation construction helpers +│ ├── truncate-record.ts # Truncates Algolia records to size limit +│ └── normalization.ts # Path normalization utilities +└── types/ # TypeScript type definitions + ├── indexer.ts # IndexerResult interface + └── ... # Other type definitions +``` + +## Data Flow (Main & SDK Indexers) + +### Phase 1: Scan + +Read `docs.yml` (from filesystem or GitHub), then scan it: + +```typescript +scanDocsYml(docsYml) → { mdxPaths: Set, specNames: Set } +``` + +* Recursively walks `docs.yml` navigation structure +* Collects all unique MDX file paths from `page` and `section` items +* Collects all unique API spec names from `api` items +* Uses Sets to avoid duplicates +* **No additional I/O** - just traversing the YAML structure + +### Phase 2: Batch Fetch + +```typescript +batchFetchContent(scanResult, source) → ContentCache +``` + +* Converts Sets to arrays and maps over them +* Fetches all content in parallel with `Promise.all` + * **Filesystem source**: Reads local files with `fs.readFile` + * **GitHub source**: Fetches via GitHub API with `octokit` +* Parses frontmatter from MDX files using `gray-matter` +* Stores everything in `ContentCache` for O(1) lookup +* **Maximum parallelization** - all I/O happens simultaneously + +### Phase 3: Process + +```typescript +buildAllOutputs(docsYml, contentCache, repoConfig) + → { pathIndex, navigationTrees, algoliaRecords } +``` + +* Uses visitor pattern to walk `docs.yml` navigation structure +* `visitNavigationItem` dispatcher routes to type-specific visitors: + * `visitPage` for MDX pages + * `visitSection` for sections (recursive) + * `visitApiReference` for API specs (delegates to OpenAPI/OpenRPC processors) + * `visitLink` for external links +* For each item, looks up content in cache (O(1) lookup) +* `ProcessingContext` encapsulates three collectors: + * `PathIndexCollector` for path index entries + * `NavigationTreesCollector` for navigation tree items + * `AlgoliaCollector` for search records +* Passes `navigationAncestors` through recursion for breadcrumbs +* Returns all three outputs simultaneously + +### Upload Phase + +```typescript +Promise.all([ + storeToRedis(pathIndex, navigationTrees, { branchId, indexerType }), + uploadToAlgolia(algoliaRecords, { indexerType, branchId }), +]); +``` + +* Writes to Redis and Algolia in parallel +* Branch-scoped keys for preview support +* Special handling for wallets nav tree (bidirectional merge) +* Algolia uses atomic swap (temp index → production) + +## Changelog Indexer Flow + +The changelog indexer uses a simpler flow: + +1. **Read directory**: List all files in `fern/changelog/` +2. **Parse filenames**: Extract dates from `YYYY-MM-DD.md` pattern +3. **Fetch in parallel**: Read all files with `Promise.all` +4. **Build outputs**: Create path index + Algolia records (no nav trees) +5. **Upload**: Write to Redis and Algolia in parallel + +## Usage + +### Running the Indexers + +```bash +# Main indexer (production mode - default) +pnpm index:main + +# Main indexer (preview mode - branch-scoped) +pnpm index:main:preview + +# SDK indexer (fetches from aa-sdk repo, production only) +pnpm index:sdk + +# Changelog indexer +pnpm index:changelog +``` + +### Environment Variables + +Create a `.env` file (see `.env.example`): + +```bash +# Redis (required for path index and navigation trees) +KV_REST_API_TOKEN=your_token +KV_REST_API_URL=your_url + +# Algolia (required for search index) +ALGOLIA_APP_ID=your_app_id +ALGOLIA_ADMIN_API_KEY=your_admin_key + +# GitHub (required for SDK indexer, optional for main - increases API rate limits) +GH_TOKEN=your_personal_access_token +``` + +### Testing + +```bash +# Run all tests +pnpm test:run + +# Run with coverage report +pnpm test:coverage + +# Watch mode +pnpm test +``` + +## Development + +### Running Locally + +1. Set up environment variables in `.env` +2. Run an indexer: + ```bash + pnpm index:main:preview + ``` +3. Check Redis/Algolia to verify data was written + +### Adding New Content Types + +To add a new content type that requires indexing: + +1. Create a new indexer in `indexers/` (or extend existing) +2. Add npm script to `package.json` +3. Update `index.ts` entry point to include new indexer type +4. Update `storeToRedis` and `uploadToAlgolia` if new storage patterns needed + +### Testing + +The test suite covers: + +* **Core logic**: 95-100% coverage for collectors, visitors, processors +* **Integration**: Full pipeline tests for each indexer +* **Edge cases**: Truncation, merging, error handling + +Low coverage in I/O utilities (`filesystem.ts`, `github.ts`) is expected and acceptable. + +## Troubleshooting + +### "No cached spec found for api-name" + +**Cause:** Spec name in docs.yml doesn't match filename in metadata.json + +**Fix:** Check `API_NAME_TO_FILENAME` mapping in `utils/apiSpecs.ts` + +### "Failed to read docs.yml" + +**Cause:** + +* (Main indexer) File doesn't exist locally at `fern/docs.yml` +* (SDK indexer) GitHub API authentication failed or file path incorrect + +**Fix:** + +1. Verify file exists at expected location +2. Check `GH_TOKEN` environment variable is set (for SDK indexer) +3. Verify `repoConfig.docsPrefix` is correct + +### "Failed to read changelog file" + +**Cause:** Changelog file doesn't follow expected `YYYY-MM-DD.md` naming pattern + +**Fix:** Ensure all changelog files in `fern/changelog/` are named like `2025-11-20.md` + +### SDK References not appearing in wallets sidebar + +**Cause:** Main indexer ran after SDK indexer and didn't preserve SDK sections + +**Fix:** + +1. Verify `mergeWalletsNavTree` is being called in `storeToRedis` +2. Check Redis to see if SDK sections exist: `GET main/nav-tree:wallets` +3. Re-run SDK indexer after main indexer to restore SDK sections diff --git a/src/content-indexer/__tests__/index.test.ts b/src/content-indexer/__tests__/index.test.ts new file mode 100644 index 000000000..f89cbdadd --- /dev/null +++ b/src/content-indexer/__tests__/index.test.ts @@ -0,0 +1,155 @@ +import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"; + +import { batchFetchContent } from "@/content-indexer/core/batch-fetcher.ts"; +import { buildAllOutputs } from "@/content-indexer/core/build-all-outputs.ts"; +import { ContentCache } from "@/content-indexer/core/content-cache.ts"; +import { scanDocsYml } from "@/content-indexer/core/scanner.ts"; +import { buildDocsContentIndex } from "@/content-indexer/indexers/main.ts"; +import { readLocalDocsYml } from "@/content-indexer/utils/filesystem.ts"; +import { fetchFileFromGitHub } from "@/content-indexer/utils/github.ts"; +import { repoConfigFactory } from "@/content-indexer/utils/test-factories.ts"; + +// Mock dependencies +vi.mock("@/content-indexer/utils/github", async () => { + const actual = await vi.importActual("@/content-indexer/utils/github"); + return { + ...actual, + fetchFileFromGitHub: vi.fn(), + }; +}); + +vi.mock("@/content-indexer/utils/filesystem", async () => { + const actual = await vi.importActual("@/content-indexer/utils/filesystem"); + return { + ...actual, + readLocalDocsYml: vi.fn(), + }; +}); + +vi.mock("@/content-indexer/core/scanner", () => ({ + scanDocsYml: vi.fn(), +})); + +vi.mock("@/content-indexer/core/batch-fetcher", () => ({ + batchFetchContent: vi.fn(), +})); + +vi.mock("@/content-indexer/core/build-all-outputs", () => ({ + buildAllOutputs: vi.fn(), +})); + +describe("buildDocsContentIndex", () => { + let consoleInfoSpy: ReturnType; + + beforeEach(() => { + consoleInfoSpy = vi.spyOn(console, "info").mockImplementation(() => {}); + }); + + afterEach(() => { + consoleInfoSpy.mockRestore(); + vi.clearAllMocks(); + }); + + test("should orchestrate all 3 phases successfully in preview mode", async () => { + const mockDocsYml = { + navigation: [ + { + tab: "guides", + layout: [{ page: "quickstart.mdx", path: "quickstart.mdx" }], + }, + ], + }; + vi.mocked(readLocalDocsYml).mockResolvedValue(mockDocsYml); + + const mockScanResult = { + mdxPaths: new Set(["quickstart.mdx"]), + specNames: new Set(["ethereum-api"]), + }; + vi.mocked(scanDocsYml).mockReturnValue(mockScanResult); + + // Mock Phase 2: Batch fetch + const mockCache = new ContentCache(); + vi.mocked(batchFetchContent).mockResolvedValue(mockCache); + + // Mock Phase 3: Process + const mockResult = { + pathIndex: { + "guides/quickstart": { + type: "mdx" as const, + source: "docs-yml" as const, + filePath: "quickstart.mdx", + tab: "guides", + }, + }, + navigationTrees: { + guides: [], + }, + algoliaRecords: [], + }; + vi.mocked(buildAllOutputs).mockReturnValue(mockResult); + + const repoConfig = repoConfigFactory({ docsPrefix: "docs" }); + + const result = await buildDocsContentIndex({ + source: { type: "filesystem", basePath: "/test/fern" }, + branchId: "test-branch", + repoConfig, + mode: "preview", + }); + + // Verify all phases were called + expect(scanDocsYml).toHaveBeenCalled(); + expect(batchFetchContent).toHaveBeenCalledWith(mockScanResult, { + type: "filesystem", + basePath: "/test/fern", + }); + expect(buildAllOutputs).toHaveBeenCalledWith( + expect.any(Object), + mockCache, + repoConfig, + ); + + // Verify result + expect(result).toEqual(mockResult); + }); + + test("should read from GitHub for GitHub source type", async () => { + const repoConfig = repoConfigFactory({ docsPrefix: "docs" }); + const docsYmlContent = ` +navigation: + - tab: guides + layout: + - page: quickstart.mdx +`; + + vi.mocked(fetchFileFromGitHub).mockResolvedValue(docsYmlContent); + vi.mocked(scanDocsYml).mockReturnValue({ + mdxPaths: new Set(["quickstart.mdx"]), + specNames: new Set(), + }); + vi.mocked(batchFetchContent).mockResolvedValue(new ContentCache()); + vi.mocked(buildAllOutputs).mockReturnValue({ + pathIndex: {}, + navigationTrees: {}, + algoliaRecords: [], + }); + + await buildDocsContentIndex({ + source: { type: "github", repoConfig }, + branchId: "main", + repoConfig, + mode: "production", + }); + + // Verify GitHub API was used for docs.yml + expect(fetchFileFromGitHub).toHaveBeenCalledWith( + "docs/docs.yml", + repoConfig, + ); + // Verify GitHub source was used for batch fetch + expect(batchFetchContent).toHaveBeenCalledWith(expect.any(Object), { + type: "github", + repoConfig, + }); + }); +}); diff --git a/src/content-indexer/collectors/__tests__/algolia.test.ts b/src/content-indexer/collectors/__tests__/algolia.test.ts new file mode 100644 index 000000000..3a4de838d --- /dev/null +++ b/src/content-indexer/collectors/__tests__/algolia.test.ts @@ -0,0 +1,206 @@ +import { describe, expect, test } from "vitest"; + +import { AlgoliaCollector } from "../algolia.ts"; + +describe("AlgoliaCollector", () => { + test("should initialize with empty records", () => { + const collector = new AlgoliaCollector(); + expect(collector.getRecords()).toEqual([]); + }); + + test("should add Guide record without httpMethod", () => { + const collector = new AlgoliaCollector(); + collector.addRecord({ + pageType: "Guide", + path: "guides/quickstart", + title: "Quickstart Guide", + content: "This is a quickstart guide content", + breadcrumbs: [ + { title: "Guides", path: "/guides", type: "section", children: [] }, + { + title: "Getting Started", + path: "/guides/getting-started", + type: "section", + children: [], + }, + ], + }); + + const records = collector.getRecords(); + expect(records).toHaveLength(1); + expect(records[0].pageType).toBe("Guide"); + expect(records[0].title).toBe("Quickstart Guide"); + expect(records[0].breadcrumbs).toEqual(["Guides", "Getting Started"]); + expect(records[0].httpMethod).toBeUndefined(); + }); + + test("should add API Method record with httpMethod", () => { + const collector = new AlgoliaCollector(); + collector.addRecord({ + pageType: "API Method", + path: "reference/eth-getbalance", + title: "eth_getBalance", + content: "Get the balance of an address", + httpMethod: "POST", + breadcrumbs: [ + { + title: "NFT API", + path: "/reference/nft-api", + type: "api-section", + children: [], + }, + { title: "NFT API Endpoints", type: "section", children: [] }, + ], + }); + + const records = collector.getRecords(); + expect(records).toHaveLength(1); + expect(records[0].pageType).toBe("API Method"); + expect(records[0].httpMethod).toBe("POST"); + expect(records[0].breadcrumbs).toEqual(["NFT API", "NFT API Endpoints"]); + }); + + test("should generate stable objectID from path", () => { + const collector = new AlgoliaCollector(); + collector.addRecord({ + pageType: "API Method", + path: "reference/eth-getbalance", + title: "eth_getBalance", + content: "Description", + httpMethod: "POST", + breadcrumbs: [ + { title: "NFT API", type: "section", children: [] }, + { title: "NFT API Endpoints", type: "section", children: [] }, + ], + }); + + const records = collector.getRecords(); + expect(records[0].objectID).toBeDefined(); + expect(records[0].objectID).toHaveLength(16); // SHA-256 hash first 16 chars + expect(typeof records[0].objectID).toBe("string"); + }); + + test("should filter out link breadcrumbs", () => { + const collector = new AlgoliaCollector(); + collector.addRecord({ + pageType: "Guide", + path: "guides/quickstart", + title: "Quickstart", + content: "Content", + breadcrumbs: [ + { title: "Guides", path: "/guides", type: "section", children: [] }, + { title: "External Link", href: "https://example.com", type: "link" }, + { + title: "Getting Started", + path: "/guides/getting-started", + type: "section", + children: [], + }, + ], + }); + + const records = collector.getRecords(); + expect(records[0].breadcrumbs).toEqual(["Guides", "Getting Started"]); + expect(records[0].breadcrumbs).not.toContain("External Link"); + }); + + test("should handle multiple records", () => { + const collector = new AlgoliaCollector(); + collector.addRecord({ + pageType: "Guide", + path: "guides/quickstart", + title: "Quickstart", + content: "Content 1", + breadcrumbs: [], + }); + collector.addRecord({ + pageType: "API Method", + path: "reference/method", + title: "method1", + content: "Content 2", + httpMethod: "GET", + breadcrumbs: [], + }); + + const records = collector.getRecords(); + expect(records).toHaveLength(2); + }); + + test("should handle empty breadcrumbs", () => { + const collector = new AlgoliaCollector(); + collector.addRecord({ + pageType: "Guide", + path: "guides/quickstart", + title: "Quickstart", + content: "Content", + breadcrumbs: [], + }); + + const records = collector.getRecords(); + expect(records[0].breadcrumbs).toEqual([]); + // ObjectID should still be generated (using path) + expect(records[0].objectID).toBeDefined(); + }); + + test("should generate consistent objectID for same path", () => { + const collector1 = new AlgoliaCollector(); + collector1.addRecord({ + pageType: "API Method", + path: "reference/eth-getbalance", + title: "eth_getBalance", + content: "Content 1", + httpMethod: "POST", + breadcrumbs: [ + { title: "API", type: "section", children: [] }, + { title: "Ethereum Endpoints", type: "section", children: [] }, + ], + }); + + const collector2 = new AlgoliaCollector(); + collector2.addRecord({ + pageType: "API Method", + path: "reference/eth-getbalance", // Same path + title: "eth_getBalance_v2", // Different title + content: "Content 2", // Different content + httpMethod: "GET", // Different method + breadcrumbs: [ + { title: "Different API", type: "section", children: [] }, // Different breadcrumbs + ], + }); + + const records1 = collector1.getRecords(); + const records2 = collector2.getRecords(); + // Same path should generate same objectID, regardless of other metadata + expect(records1[0].objectID).toBe(records2[0].objectID); + }); + + test("should generate different objectIDs for different paths", () => { + const collector = new AlgoliaCollector(); + collector.addRecord({ + pageType: "API Method", + path: "reference/eth-getbalance", + title: "eth_getBalance", + content: "Content", + httpMethod: "POST", + breadcrumbs: [ + { title: "API", type: "section", children: [] }, + { title: "Ethereum Endpoints", type: "section", children: [] }, + ], + }); + collector.addRecord({ + pageType: "API Method", + path: "reference/eth-blocknumber", + title: "eth_getBalance", // Same title + content: "Content", + httpMethod: "POST", + breadcrumbs: [ + { title: "API", type: "section", children: [] }, + { title: "Ethereum Endpoints", type: "section", children: [] }, // Same breadcrumbs + ], + }); + + const records = collector.getRecords(); + // Different paths should generate different objectIDs, even with same title/breadcrumbs + expect(records[0].objectID).not.toBe(records[1].objectID); + }); +}); diff --git a/src/content-indexer/collectors/__tests__/navigation-trees.test.ts b/src/content-indexer/collectors/__tests__/navigation-trees.test.ts new file mode 100644 index 000000000..6871f1ee4 --- /dev/null +++ b/src/content-indexer/collectors/__tests__/navigation-trees.test.ts @@ -0,0 +1,136 @@ +import { describe, expect, test } from "vitest"; + +import { NavigationTreesCollector } from "../navigation-trees.ts"; + +describe("NavigationTreesCollector", () => { + test("should initialize with empty trees", () => { + const collector = new NavigationTreesCollector(); + expect(collector.getTrees()).toEqual({}); + }); + + test("should add item to new tab", () => { + const collector = new NavigationTreesCollector(); + collector.addItem("guides", { + title: "Quickstart", + path: "/guides/quickstart", + type: "page", + }); + + const trees = collector.getTrees(); + expect(trees.guides).toHaveLength(1); + expect(trees.guides[0]).toEqual({ + title: "Quickstart", + path: "/guides/quickstart", + type: "page", + }); + }); + + test("should add multiple items to same tab", () => { + const collector = new NavigationTreesCollector(); + collector.addItem("guides", { + title: "Quickstart", + path: "/guides/quickstart", + type: "page", + }); + collector.addItem("guides", { + title: "Advanced", + path: "/guides/advanced", + type: "page", + }); + + const trees = collector.getTrees(); + expect(trees.guides).toHaveLength(2); + }); + + test("should handle items with children", () => { + const collector = new NavigationTreesCollector(); + collector.addItem("reference", { + title: "NFT API", + type: "section", + children: [ + { + title: "getNFTs", + path: "/reference/getnfts", + method: "POST", + type: "endpoint", + }, + ], + }); + + const trees = collector.getTrees(); + const firstItem = trees.reference[0]; + expect(firstItem.type).toBe("section"); + if (firstItem.type === "section" || firstItem.type === "api-section") { + expect(firstItem.children).toHaveLength(1); + } + }); + + test("should handle multiple tabs", () => { + const collector = new NavigationTreesCollector(); + collector.addItem("guides", { + title: "Quickstart", + path: "/guides/quickstart", + type: "page", + }); + collector.addItem("reference", { + title: "API Reference", + path: "/reference", + type: "page", + }); + + const trees = collector.getTrees(); + expect(Object.keys(trees)).toHaveLength(2); + expect(trees.guides).toBeDefined(); + expect(trees.reference).toBeDefined(); + }); + + test("should return correct stats", () => { + const collector = new NavigationTreesCollector(); + collector.addItem("guides", { + title: "Page1", + path: "/guides/page1", + type: "page", + }); + collector.addItem("guides", { + title: "Page2", + path: "/guides/page2", + type: "page", + }); + collector.addItem("reference", { + title: "Page3", + path: "/reference/page3", + type: "page", + }); + + const stats = collector.getStats(); + expect(stats.tabCount).toBe(2); + expect(stats.itemCounts.guides).toBe(2); + expect(stats.itemCounts.reference).toBe(1); + }); + + test("should count nested items in stats", () => { + const collector = new NavigationTreesCollector(); + collector.addItem("reference", { + title: "API Section", + type: "section", + children: [ + { + title: "Method1", + path: "/reference/method1", + method: "POST", + type: "endpoint", + }, + { + title: "Method2", + path: "/reference/method2", + method: "GET", + type: "endpoint", + }, + ], + }); + + const stats = collector.getStats(); + expect(stats.tabCount).toBe(1); + expect(stats.itemCounts.reference).toBe(3); // 1 section + 2 children + }); +}); diff --git a/src/content-indexer/collectors/__tests__/path-index.test.ts b/src/content-indexer/collectors/__tests__/path-index.test.ts new file mode 100644 index 000000000..1caca3f04 --- /dev/null +++ b/src/content-indexer/collectors/__tests__/path-index.test.ts @@ -0,0 +1,144 @@ +import { describe, expect, test } from "vitest"; + +import { PathIndexCollector } from "../path-index.ts"; + +describe("PathIndexCollector", () => { + test("should initialize with empty index", () => { + const collector = new PathIndexCollector(); + expect(collector.getIndex()).toEqual({}); + }); + + test("should add MDX entry to index", () => { + const collector = new PathIndexCollector(); + collector.add("guides/quickstart", { + type: "mdx", + filePath: "fern/guides/quickstart.mdx", + source: "docs-yml", + tab: "guides", + }); + + const index = collector.getIndex(); + expect(index["guides/quickstart"]).toEqual({ + type: "mdx", + filePath: "fern/guides/quickstart.mdx", + source: "docs-yml", + tab: "guides", + }); + }); + + test("should add OpenAPI entry to index", () => { + const collector = new PathIndexCollector(); + collector.add("reference/eth-getbalance", { + type: "openapi", + specUrl: "https://example.com/spec.json", + operationId: "eth_getBalance", + source: "docs-yml", + tab: "reference", + }); + + const index = collector.getIndex(); + expect(index["reference/eth-getbalance"]).toEqual({ + type: "openapi", + specUrl: "https://example.com/spec.json", + operationId: "eth_getBalance", + source: "docs-yml", + tab: "reference", + }); + }); + + test("should add OpenRPC entry to index", () => { + const collector = new PathIndexCollector(); + collector.add("reference/getAsset", { + type: "openrpc", + specUrl: "https://example.com/spec.json", + methodName: "getAsset", + source: "docs-yml", + tab: "reference", + }); + + const index = collector.getIndex(); + expect(index["reference/getAsset"]).toEqual({ + type: "openrpc", + specUrl: "https://example.com/spec.json", + methodName: "getAsset", + source: "docs-yml", + tab: "reference", + }); + }); + + test("should handle multiple entries", () => { + const collector = new PathIndexCollector(); + collector.add("guides/quickstart", { + type: "mdx", + filePath: "fern/guides/quickstart.mdx", + source: "docs-yml", + tab: "guides", + }); + collector.add("guides/advanced", { + type: "mdx", + filePath: "fern/guides/advanced.mdx", + source: "frontmatter", + tab: "guides", + }); + + const index = collector.getIndex(); + expect(Object.keys(index)).toHaveLength(2); + expect(index["guides/quickstart"]).toBeDefined(); + expect(index["guides/advanced"]).toBeDefined(); + }); + + test("should overwrite existing path", () => { + const collector = new PathIndexCollector(); + collector.add("guides/quickstart", { + type: "mdx", + filePath: "fern/guides/quickstart.mdx", + source: "docs-yml", + tab: "guides", + }); + collector.add("guides/quickstart", { + type: "mdx", + filePath: "fern/guides/quickstart-v2.mdx", + source: "frontmatter", + tab: "guides", + }); + + const index = collector.getIndex(); + const entry = index["guides/quickstart"]; + if (entry && "filePath" in entry) { + expect(entry.filePath).toBe("fern/guides/quickstart-v2.mdx"); + if ("source" in entry) { + expect(entry.source).toBe("frontmatter"); + } + } + }); + + test("should return correct stats", () => { + const collector = new PathIndexCollector(); + collector.add("path1", { + type: "mdx", + filePath: "file1.mdx", + source: "docs-yml", + tab: "tab1", + }); + collector.add("path2", { + type: "openapi", + specUrl: "spec.json", + operationId: "op1", + source: "docs-yml", + tab: "tab1", + }); + collector.add("path3", { + type: "openrpc", + specUrl: "spec.json", + methodName: "method1", + source: "docs-yml", + tab: "tab1", + }); + + const stats = collector.getStats(); + expect(stats.total).toBe(3); + expect(stats.byType.mdx).toBe(1); + expect(stats.byType.openapi).toBe(1); + expect(stats.byType.openrpc).toBe(1); + }); +}); diff --git a/src/content-indexer/collectors/__tests__/processing-context.test.ts b/src/content-indexer/collectors/__tests__/processing-context.test.ts new file mode 100644 index 000000000..994548db7 --- /dev/null +++ b/src/content-indexer/collectors/__tests__/processing-context.test.ts @@ -0,0 +1,165 @@ +import { describe, expect, test } from "vitest"; + +import type { NavItem } from "@/content-indexer/types/navigation.ts"; + +import { ProcessingContext } from "../processing-context.ts"; + +describe("ProcessingContext", () => { + test("should initialize with empty state", () => { + const context = new ProcessingContext(); + const results = context.getResults(); + + expect(results.pathIndex).toEqual({}); + expect(results.navigationTrees).toEqual({}); + expect(results.algoliaRecords).toEqual([]); + }); + + test("should add path index entry", () => { + const context = new ProcessingContext(); + context.addPathIndexEntry("guides/quickstart", { + type: "mdx", + filePath: "fern/guides/quickstart.mdx", + source: "docs-yml", + tab: "guides", + }); + + const results = context.getResults(); + expect(results.pathIndex["guides/quickstart"]).toBeDefined(); + expect(results.pathIndex["guides/quickstart"].type).toBe("mdx"); + }); + + test("should add navigation item", () => { + const context = new ProcessingContext(); + context.addNavigationItem("guides", { + title: "Quickstart", + path: "/guides/quickstart", + type: "page", + }); + + const results = context.getResults(); + expect(results.navigationTrees.guides).toHaveLength(1); + expect(results.navigationTrees.guides[0].title).toBe("Quickstart"); + }); + + test("should add Guide Algolia record", () => { + const context = new ProcessingContext(); + const breadcrumbs: NavItem[] = [ + { title: "Guides", path: "/guides", type: "section", children: [] }, + ]; + + context.addAlgoliaRecord({ + pageType: "Guide", + path: "guides/quickstart", + title: "Quickstart", + content: "Quick start guide content", + breadcrumbs, + }); + + const results = context.getResults(); + expect(results.algoliaRecords).toHaveLength(1); + expect(results.algoliaRecords[0].pageType).toBe("Guide"); + expect(results.algoliaRecords[0].httpMethod).toBeUndefined(); + }); + + test("should add API Method Algolia record with httpMethod", () => { + const context = new ProcessingContext(); + const breadcrumbs: NavItem[] = [ + { title: "API", path: "/api", type: "section", children: [] }, + ]; + + context.addAlgoliaRecord({ + pageType: "API Method", + path: "reference/eth-getbalance", + title: "eth_getBalance", + content: "Get balance", + httpMethod: "POST", + breadcrumbs, + }); + + const results = context.getResults(); + expect(results.algoliaRecords).toHaveLength(1); + expect(results.algoliaRecords[0].pageType).toBe("API Method"); + expect(results.algoliaRecords[0].httpMethod).toBe("POST"); + }); + + test("should accumulate multiple outputs simultaneously", () => { + const context = new ProcessingContext(); + + // Add path index + context.addPathIndexEntry("guides/quickstart", { + type: "mdx", + filePath: "fern/guides/quickstart.mdx", + source: "docs-yml", + tab: "guides", + }); + + // Add navigation + context.addNavigationItem("guides", { + title: "Quickstart", + path: "/guides/quickstart", + type: "page", + }); + + // Add Algolia record + context.addAlgoliaRecord({ + pageType: "Guide", + path: "guides/quickstart", + title: "Quickstart", + content: "Content", + breadcrumbs: [], + }); + + const results = context.getResults(); + expect(Object.keys(results.pathIndex)).toHaveLength(1); + expect(results.navigationTrees.guides).toHaveLength(1); + expect(results.algoliaRecords).toHaveLength(1); + }); + + test("should return correct stats", () => { + const context = new ProcessingContext(); + + context.addPathIndexEntry("path1", { + type: "mdx", + filePath: "file1.mdx", + source: "docs-yml", + tab: "guides", + }); + context.addNavigationItem("guides", { + title: "Page1", + path: "/guides/page1", + type: "page", + }); + context.addAlgoliaRecord({ + pageType: "Guide", + path: "guides/page1", + title: "Page1", + content: "Content", + breadcrumbs: [], + }); + + const stats = context.getStats(); + expect(stats.pathIndex.total).toBe(1); + expect(stats.navigationTrees.tabCount).toBe(1); + expect(stats.algoliaRecords.count).toBe(1); + }); + + test("should handle multiple tabs in navigation", () => { + const context = new ProcessingContext(); + + context.addNavigationItem("guides", { + title: "Guide1", + path: "/guides/guide1", + type: "page", + }); + context.addNavigationItem("reference", { + title: "Ref1", + path: "/reference/ref1", + type: "page", + }); + + const results = context.getResults(); + expect(Object.keys(results.navigationTrees)).toHaveLength(2); + expect(results.navigationTrees.guides).toBeDefined(); + expect(results.navigationTrees.reference).toBeDefined(); + }); +}); diff --git a/src/content-indexer/collectors/algolia.ts b/src/content-indexer/collectors/algolia.ts new file mode 100644 index 000000000..7958382ca --- /dev/null +++ b/src/content-indexer/collectors/algolia.ts @@ -0,0 +1,81 @@ +import { createHash } from "crypto"; + +import type { AlgoliaRecord } from "@/content-indexer/types/algolia.ts"; +import type { NavItem } from "@/content-indexer/types/navigation.ts"; + +/** + * Extracts breadcrumb titles from NavItems for Algolia. + * Returns only the titles in hierarchical order. + */ +const extractBreadcrumbTitles = (navItems: NavItem[]): string[] => { + return navItems + .filter((item) => item.type !== "link") // Skip links + .map((item) => item.title); +}; + +type AddRecordBaseParams = { + path: string; + title: string; + description?: string; + content: string; + breadcrumbs: NavItem[]; +}; + +type AddGuideRecordParams = AddRecordBaseParams & { + pageType: "Guide"; + httpMethod?: never; // Not allowed for Guide +}; + +type AddApiMethodRecordParams = AddRecordBaseParams & { + pageType: "API Method"; + httpMethod: string; // Required for API Method +}; +export type AddRecordParams = AddGuideRecordParams | AddApiMethodRecordParams; + +/** + * Collector for Algolia search records during content processing. + * Records are built with all required data including breadcrumbs. + */ +export class AlgoliaCollector { + private records: AlgoliaRecord[] = []; + + /** + * Add a search record for either MDX pages or API methods. + * + * ObjectID strategy: + * Uses hash of the URL path for stable, unique identification. + * - Uniqueness: URLs are guaranteed unique by the routing system + * - Stability: Paths are designed to be stable (SEO, bookmarks, external links) + * - Enables incremental index updates in the future + */ + addRecord(params: AddRecordParams): void { + const breadcrumbTitles = extractBreadcrumbTitles(params.breadcrumbs); + const objectID = this.generateHash(params.path); + + this.records.push({ + objectID, + path: params.path, + pageType: params.pageType, + title: params.title, + content: params.content, + breadcrumbs: breadcrumbTitles, + ...(params.httpMethod && { httpMethod: params.httpMethod }), + ...(params.description && { description: params.description }), + }); + } + + /** + * Get all built records. + */ + getRecords(): AlgoliaRecord[] { + return this.records; + } + + /** + * Generate a stable hash-based objectID from a source string. + * Returns first 16 characters of SHA-256 hash for a clean ID format. + */ + private generateHash(source: string): string { + return createHash("sha256").update(source).digest("hex").substring(0, 16); + } +} diff --git a/src/content-indexer/collectors/navigation-trees.ts b/src/content-indexer/collectors/navigation-trees.ts new file mode 100644 index 000000000..03820a22d --- /dev/null +++ b/src/content-indexer/collectors/navigation-trees.ts @@ -0,0 +1,58 @@ +import type { + NavItem, + NavigationTreesByTab, +} from "@/content-indexer/types/navigation.js"; + +/** + * Collector for accumulating navigation trees during content processing. + * Organizes navigation items by tab. + */ +export class NavigationTreesCollector { + private trees: NavigationTreesByTab = {}; + + /** + * Add a navigation item to a specific tab's tree. + */ + addItem(tab: string, item: NavItem): void { + if (!this.trees[tab]) { + this.trees[tab] = []; + } + this.trees[tab].push(item); + } + + /** + * Get the complete navigation trees. + */ + getTrees(): NavigationTreesByTab { + return this.trees; + } + + /** + * Get statistics about the navigation trees. + */ + getStats(): { tabCount: number; itemCounts: Record } { + return { + tabCount: Object.keys(this.trees).length, + itemCounts: Object.entries(this.trees).reduce( + (acc, [tab, items]) => { + acc[tab] = this.countItems(items); + return acc; + }, + {} as Record, + ), + }; + } + + /** + * Recursively count navigation items including nested children. + */ + private countItems(items: NavItem[]): number { + return items.reduce((sum, item) => { + const childCount = + item.type === "section" || item.type === "api-section" + ? this.countItems(item.children) + : 0; + return sum + 1 + childCount; + }, 0); + } +} diff --git a/src/content-indexer/collectors/path-index.ts b/src/content-indexer/collectors/path-index.ts new file mode 100644 index 000000000..010657743 --- /dev/null +++ b/src/content-indexer/collectors/path-index.ts @@ -0,0 +1,49 @@ +import type { + PathIndex, + PathIndexEntry, +} from "@/content-indexer/types/pathIndex.js"; + +/** + * Collector for accumulating path index entries during content processing. + * Provides validation to prevent duplicate paths. + */ +export class PathIndexCollector { + private index: PathIndex = {}; + + /** + * Add a path index entry for URL routing. + * Warns if the path already exists to catch configuration errors. + */ + add(path: string, entry: PathIndexEntry): void { + if (this.index[path]) { + console.warn( + `⚠️ Duplicate path detected: ${path} (overwriting previous entry)`, + ); + } + this.index[path] = entry; + } + + /** + * Get the complete path index. + */ + getIndex(): PathIndex { + return this.index; + } + + /** + * Get statistics about the index. + */ + getStats(): { total: number; byType: Record } { + const entries = Object.values(this.index); + return { + total: entries.length, + byType: entries.reduce( + (acc, entry) => { + acc[entry.type] = (acc[entry.type] || 0) + 1; + return acc; + }, + {} as Record, + ), + }; + } +} diff --git a/src/content-indexer/collectors/processing-context.ts b/src/content-indexer/collectors/processing-context.ts new file mode 100644 index 000000000..70f630ee9 --- /dev/null +++ b/src/content-indexer/collectors/processing-context.ts @@ -0,0 +1,77 @@ +import type { AlgoliaRecord } from "@/content-indexer/types/algolia.ts"; +import type { + NavItem, + NavigationTreesByTab, +} from "@/content-indexer/types/navigation.js"; +import type { + PathIndex, + PathIndexEntry, +} from "@/content-indexer/types/pathIndex.js"; + +import { AlgoliaCollector, type AddRecordParams } from "./algolia.ts"; +import { NavigationTreesCollector } from "./navigation-trees.ts"; +import { PathIndexCollector } from "./path-index.ts"; + +/** + * Result of building all outputs from content processing. + */ +export interface BuildAllOutputsResult { + pathIndex: PathIndex; + navigationTrees: NavigationTreesByTab; + algoliaRecords: AlgoliaRecord[]; +} + +/** + * Encapsulates the three output collectors for Phase 3 processing. + * Provides a unified interface for accumulating results while traversing docs.yml. + */ +export class ProcessingContext { + constructor( + private pathIndexCollector = new PathIndexCollector(), + private navigationTreesCollector = new NavigationTreesCollector(), + private algoliaCollector = new AlgoliaCollector(), + ) {} + + /** + * Add an entry to the path index for URL routing. + */ + addPathIndexEntry(path: string, entry: PathIndexEntry): void { + this.pathIndexCollector.add(path, entry); + } + + /** + * Add a navigation item to a specific tab's tree. + */ + addNavigationItem(tab: string, item: NavItem): void { + this.navigationTreesCollector.addItem(tab, item); + } + + /** + * Add a record to the Algolia index. + */ + addAlgoliaRecord(params: AddRecordParams): void { + this.algoliaCollector.addRecord(params); + } + + /** + * Get all accumulated results. + */ + getResults(): BuildAllOutputsResult { + return { + pathIndex: this.pathIndexCollector.getIndex(), + navigationTrees: this.navigationTreesCollector.getTrees(), + algoliaRecords: this.algoliaCollector.getRecords(), + }; + } + + /** + * Get statistics about accumulated data. + */ + getStats() { + return { + pathIndex: this.pathIndexCollector.getStats(), + navigationTrees: this.navigationTreesCollector.getStats(), + algoliaRecords: { count: this.algoliaCollector.getRecords().length }, + }; + } +} diff --git a/src/content-indexer/constants/changelog.ts b/src/content-indexer/constants/changelog.ts new file mode 100644 index 000000000..4c76ec4ca --- /dev/null +++ b/src/content-indexer/constants/changelog.ts @@ -0,0 +1,10 @@ +/** + * Number of changelog entries to show per page + */ +export const ENTRIES_PER_PAGE = 10; + +/** + * Sticky position for date badges + * Calculated as: header height (~80px) + badge height (~40px) + */ +export const DATE_BADGE_STICKY_TOP = 120; diff --git a/src/content-indexer/constants/http.ts b/src/content-indexer/constants/http.ts new file mode 100644 index 000000000..625173bd0 --- /dev/null +++ b/src/content-indexer/constants/http.ts @@ -0,0 +1,12 @@ +export const HTTP_METHODS = [ + "get", + "post", + "put", + "patch", + "delete", + "options", + "head", + "trace", +] as const; + +export type HttpMethod = Uppercase<(typeof HTTP_METHODS)[number]>; diff --git a/src/content-indexer/constants/links.ts b/src/content-indexer/constants/links.ts new file mode 100644 index 000000000..979e0751e --- /dev/null +++ b/src/content-indexer/constants/links.ts @@ -0,0 +1,2 @@ +export const BASE_PATH = "/docs"; +export const DOCS_BASE_URL = "https://www.alchemy.com/docs"; diff --git a/src/content-indexer/constants/metadata.ts b/src/content-indexer/constants/metadata.ts new file mode 100644 index 000000000..040916f2b --- /dev/null +++ b/src/content-indexer/constants/metadata.ts @@ -0,0 +1,56 @@ +import { DOCS_BASE_URL } from "./links.ts"; + +// TODO: This file is copied from docs-site but not used in the content indexer +// It's kept for potential future use but Next.js types are stubbed +type Metadata = { + title?: { template?: string; default?: string } | string; + description?: string; + robots?: { index?: boolean; follow?: boolean }; + alternates?: { canonical?: string }; + openGraph?: Record; + twitter?: Record; +}; + +export const DEFAULT_OG_IMAGE = { + url: "https://alchemyapi-res.cloudinary.com/image/upload/v1753213834/docs/docs-og-image.png", + width: 1200, + height: 630, +}; + +export const DEFAULT_OPEN_GRAPH: Metadata["openGraph"] = { + title: "Alchemy Documentation - Build anything onchain", + description: + "Learn how to use Node APIs, Data APIs, Webhooks, Smart Wallets and Rollups to create powerful onchain experiences.", + siteName: "Alchemy Documentation", + url: DOCS_BASE_URL, + locale: "en_US", + type: "website", + images: [DEFAULT_OG_IMAGE], +}; + +const DEFAULT_TWITTER: Metadata["twitter"] = { + card: "summary_large_image", + title: "Alchemy Documentation - Build anything onchain", + description: + "Learn how to use Node APIs, Data APIs, Webhooks, Smart Wallets and Rollups to create powerful onchain experiences.", + site: "@alchemy", + images: [DEFAULT_OG_IMAGE.url], +}; + +export const DEFAULT_METADATA: Metadata = { + title: { + template: "%s | Alchemy Docs", + default: "Alchemy Documentation - Build anything onchain", + }, + description: + "Learn how to use Node APIs, Data APIs, Webhooks, Smart Wallets and Rollups to create powerful onchain experiences.", + robots: { + index: true, + follow: true, + }, + alternates: { + canonical: DOCS_BASE_URL, + }, + openGraph: DEFAULT_OPEN_GRAPH, + twitter: DEFAULT_TWITTER, +}; diff --git a/src/content-indexer/core/__tests__/batch-fetcher.test.ts b/src/content-indexer/core/__tests__/batch-fetcher.test.ts new file mode 100644 index 000000000..2446a1207 --- /dev/null +++ b/src/content-indexer/core/__tests__/batch-fetcher.test.ts @@ -0,0 +1,221 @@ +import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"; + +import type { OpenApiSpec } from "@/content-indexer/types/specs.ts"; +import { fetchApiSpec } from "@/content-indexer/utils/apiSpecs.ts"; +import { fetchFileFromGitHub } from "@/content-indexer/utils/github.ts"; +import { + openApiSpecFactory, + repoConfigFactory, +} from "@/content-indexer/utils/test-factories.js"; + +import { batchFetchContent } from "../batch-fetcher.ts"; + +// Mock dependencies +vi.mock("@/content-indexer/utils/github", async () => { + const actual = await vi.importActual("@/content-indexer/utils/github"); + return { + ...actual, + fetchFileFromGitHub: vi.fn(), + }; +}); + +vi.mock("@/content-indexer/utils/apiSpecs", () => ({ + fetchApiSpec: vi.fn(), +})); + +describe("batchFetchContent", () => { + let consoleInfoSpy: ReturnType; + let consoleWarnSpy: ReturnType; + + beforeEach(() => { + consoleInfoSpy = vi.spyOn(console, "info").mockImplementation(() => {}); + consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + }); + + afterEach(() => { + consoleInfoSpy.mockRestore(); + consoleWarnSpy.mockRestore(); + vi.clearAllMocks(); + }); + + test("should fetch MDX files and populate cache", async () => { + const repoConfig = repoConfigFactory({ docsPrefix: "docs" }); + const scanResult = { + mdxPaths: new Set(["quickstart.mdx", "guides/intro.mdx"]), + specNames: new Set(), + }; + + const mdxContent = `--- +title: Test Page +--- +# Content`; + + vi.mocked(fetchFileFromGitHub).mockResolvedValue(mdxContent); + + const cache = await batchFetchContent(scanResult, { + type: "github", + repoConfig, + }); + + // Verify fetches were made + expect(fetchFileFromGitHub).toHaveBeenCalledTimes(2); + expect(fetchFileFromGitHub).toHaveBeenCalledWith( + "docs/quickstart.mdx", + repoConfig, + ); + expect(fetchFileFromGitHub).toHaveBeenCalledWith( + "docs/guides/intro.mdx", + repoConfig, + ); + + // Verify cache was populated + const stats = cache.getStats(); + expect(stats.mdxCount).toBe(2); + expect(stats.specCount).toBe(0); + + // Verify cache entries + const entry = cache.getMdxContent("quickstart.mdx"); + expect(entry).toBeDefined(); + expect(entry?.frontmatter.title).toBe("Test Page"); + expect(entry?.content).toContain("# Content"); + }); + + test("should fetch API specs and populate cache", async () => { + const repoConfig = repoConfigFactory({ docsPrefix: "docs" }); + const scanResult = { + mdxPaths: new Set(), + specNames: new Set(["ethereum-api", "solana-api"]), + }; + + const mockSpec = { + specType: "openapi" as const, + spec: openApiSpecFactory({ + openapi: "3.0.0", + info: { title: "Test", version: "1.0" }, + }), + specUrl: "https://example.com/spec.json", + }; + + vi.mocked(fetchApiSpec).mockResolvedValue(mockSpec); + + const cache = await batchFetchContent(scanResult, { + type: "github", + repoConfig, + }); + + // Verify fetches were made + expect(fetchApiSpec).toHaveBeenCalledTimes(2); + expect(fetchApiSpec).toHaveBeenCalledWith("ethereum-api"); + expect(fetchApiSpec).toHaveBeenCalledWith("solana-api"); + + // Verify cache was populated + const stats = cache.getStats(); + expect(stats.mdxCount).toBe(0); + expect(stats.specCount).toBe(2); + }); + + test("should handle stripPathPrefix configuration", async () => { + const repoConfig = repoConfigFactory({ + docsPrefix: "docs", + stripPathPrefix: "fern/", + }); + const scanResult = { + mdxPaths: new Set(["fern/guides/intro.mdx"]), + specNames: new Set(), + }; + + vi.mocked(fetchFileFromGitHub).mockResolvedValue("---\n---\nContent"); + + await batchFetchContent(scanResult, { + type: "github", + repoConfig, + }); + + // Verify path was transformed (strip "fern/" prefix) + expect(fetchFileFromGitHub).toHaveBeenCalledWith( + "docs/guides/intro.mdx", + repoConfig, + ); + }); + + test("should handle fetch failures gracefully", async () => { + const repoConfig = repoConfigFactory({ docsPrefix: "docs" }); + const scanResult = { + mdxPaths: new Set(["missing.mdx"]), + specNames: new Set(["missing-api"]), + }; + + vi.mocked(fetchFileFromGitHub).mockRejectedValue( + new Error("File not found"), + ); + vi.mocked(fetchApiSpec).mockRejectedValue(new Error("Spec not found")); + + const cache = await batchFetchContent(scanResult, { + type: "github", + repoConfig, + }); + + // Verify warnings were logged + expect(consoleWarnSpy).toHaveBeenCalledWith( + expect.stringContaining("Failed to fetch MDX file"), + expect.any(Error), + ); + expect(consoleWarnSpy).toHaveBeenCalledWith( + expect.stringContaining("Failed to fetch spec"), + expect.any(Error), + ); + + // Verify cache is empty + const stats = cache.getStats(); + expect(stats.mdxCount).toBe(0); + expect(stats.specCount).toBe(0); + }); + + test("should handle null responses from fetchers", async () => { + const repoConfig = repoConfigFactory({ docsPrefix: "docs" }); + const scanResult = { + mdxPaths: new Set(["missing.mdx"]), + specNames: new Set(["missing-api"]), + }; + + vi.mocked(fetchFileFromGitHub).mockResolvedValue(null); + vi.mocked(fetchApiSpec).mockResolvedValue(undefined); + + const cache = await batchFetchContent(scanResult, { + type: "github", + repoConfig, + }); + + // Cache should be empty + const stats = cache.getStats(); + expect(stats.mdxCount).toBe(0); + expect(stats.specCount).toBe(0); + }); + + test("should log progress information", async () => { + const repoConfig = repoConfigFactory({ docsPrefix: "docs" }); + const scanResult = { + mdxPaths: new Set(["test.mdx"]), + specNames: new Set(["test-api"]), + }; + + vi.mocked(fetchFileFromGitHub).mockResolvedValue("---\n---\nContent"); + vi.mocked(fetchApiSpec).mockResolvedValue({ + specType: "openapi", + spec: {} as OpenApiSpec, + specUrl: "url", + }); + + await batchFetchContent(scanResult, { + type: "github", + repoConfig, + }); + + expect(consoleInfoSpy).toHaveBeenCalledWith( + expect.stringContaining("Fetching 1 MDX files and 1 specs"), + ); + expect(consoleInfoSpy).toHaveBeenCalledWith( + expect.stringContaining("Fetched 1/1 MDX files and 1/1 specs"), + ); + }); +}); diff --git a/src/content-indexer/core/__tests__/build-all-outputs.test.ts b/src/content-indexer/core/__tests__/build-all-outputs.test.ts new file mode 100644 index 000000000..0e5d355ce --- /dev/null +++ b/src/content-indexer/core/__tests__/build-all-outputs.test.ts @@ -0,0 +1,273 @@ +import { beforeEach, describe, expect, test, vi } from "vitest"; + +import type { DocsYml } from "@/content-indexer/types/docsYaml.ts"; +import { repoConfigFactory } from "@/content-indexer/utils/test-factories.ts"; +import { visitNavigationItem } from "@/content-indexer/visitors/index.ts"; + +import { buildAllOutputs } from "../build-all-outputs.ts"; +import { ContentCache } from "../content-cache.ts"; + +// Mock the visitor +vi.mock("@/content-indexer/visitors", () => ({ + visitNavigationItem: vi.fn(), +})); + +describe("buildAllOutputs", () => { + beforeEach(() => { + vi.clearAllMocks(); + }); + + test("should process navigation items and return results", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "guides", + layout: [ + { + page: "quickstart.mdx", + path: "quickstart.mdx", + }, + ], + }, + ], + }; + + const cache = new ContentCache(); + const repoConfig = repoConfigFactory(); + + vi.mocked(visitNavigationItem).mockReturnValue({ + indexEntries: { + "guides/quickstart": { + type: "mdx", + source: "docs-yml", + filePath: "quickstart.mdx", + tab: "guides", + }, + }, + navItem: { + type: "page", + title: "Quickstart", + path: "/guides/quickstart", + }, + }); + + const result = buildAllOutputs(docsYml, cache, repoConfig); + + // Verify visitor was called + expect(visitNavigationItem).toHaveBeenCalled(); + + // Verify results + expect(result.pathIndex).toHaveProperty("guides/quickstart"); + expect(result.navigationTrees).toHaveProperty("guides"); + expect(result.navigationTrees.guides).toHaveLength(1); + }); + + test("should handle multiple tabs", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "guides", + layout: [{ page: "intro.mdx", path: "intro.mdx" }], + }, + { + tab: "reference", + layout: [{ api: "API", "api-name": "ethereum-api" }], + }, + ], + }; + + const cache = new ContentCache(); + + vi.mocked(visitNavigationItem) + .mockReturnValueOnce({ + indexEntries: { + "guides/intro": { + type: "mdx", + source: "docs-yml", + filePath: "intro.mdx", + tab: "guides", + }, + }, + navItem: { type: "page", title: "Intro", path: "/guides/intro" }, + }) + .mockReturnValueOnce({ + indexEntries: { + "reference/api": { + type: "openapi", + source: "docs-yml", + operationId: "getBalance", + specUrl: "url", + tab: "reference", + }, + }, + navItem: { + type: "api-section", + title: "API", + children: [], + }, + }); + + const result = buildAllOutputs(docsYml, cache); + + // Verify both tabs were processed + expect(visitNavigationItem).toHaveBeenCalledTimes(2); + expect(result.navigationTrees).toHaveProperty("guides"); + expect(result.navigationTrees).toHaveProperty("reference"); + }); + + test("should skip items without tab or layout", () => { + const docsYml = { + navigation: [ + { + // Missing tab and layout + }, + { + tab: "guides", + // Missing layout + }, + { + tab: "valid", + layout: [{ page: "test.mdx", path: "test.mdx" }], + }, + ], + } as DocsYml; + + const cache = new ContentCache(); + + vi.mocked(visitNavigationItem).mockReturnValue({ + indexEntries: {}, + navItem: { type: "page", title: "Test", path: "/test" }, + }); + + buildAllOutputs(docsYml, cache); + + // Only the valid item should be processed + expect(visitNavigationItem).toHaveBeenCalledTimes(1); + }); + + test("should apply tab configuration", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "api-reference", + layout: [{ page: "intro.mdx", path: "intro.mdx" }], + }, + ], + tabs: { + "api-reference": { + "display-name": "API Reference", + slug: "reference", + "skip-slug": false, + }, + }, + }; + + const cache = new ContentCache(); + + vi.mocked(visitNavigationItem).mockReturnValue({ + indexEntries: {}, + }); + + buildAllOutputs(docsYml, cache); + + // Verify visitor was called with correct path builder + expect(visitNavigationItem).toHaveBeenCalledWith( + expect.objectContaining({ + tab: "api-reference", + }), + ); + }); + + test("should handle skip-slug configuration", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "home", + layout: [{ page: "index.mdx", path: "index.mdx" }], + }, + ], + tabs: { + home: { + "display-name": "Home", + slug: "home", + "skip-slug": true, + }, + }, + }; + + const cache = new ContentCache(); + + vi.mocked(visitNavigationItem).mockReturnValue({ + indexEntries: {}, + }); + + buildAllOutputs(docsYml, cache); + + expect(visitNavigationItem).toHaveBeenCalled(); + }); + + test("should handle array navigation items", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "guides", + layout: [{ page: "test.mdx", path: "test.mdx" }], + }, + ], + }; + + const cache = new ContentCache(); + + // Return array of nav items + vi.mocked(visitNavigationItem).mockReturnValue({ + indexEntries: {}, + navItem: [ + { type: "page", title: "Page 1", path: "/page1" }, + { type: "page", title: "Page 2", path: "/page2" }, + ], + }); + + const result = buildAllOutputs(docsYml, cache); + + // Both items should be added + expect(result.navigationTrees.guides).toHaveLength(2); + }); + + test("should collect Algolia records from context", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "guides", + layout: [{ page: "test.mdx", path: "test.mdx" }], + }, + ], + }; + + const cache = new ContentCache(); + cache.setMdxContent("test.mdx", { + frontmatter: { title: "Test" }, + content: "Content", + }); + + // Mock visitor to use ProcessingContext + vi.mocked(visitNavigationItem).mockImplementation(({ context }) => { + context?.addAlgoliaRecord({ + title: "Test", + content: "Content", + path: "/guides/test", + breadcrumbs: [], + pageType: "Guide", + }); + + return { + indexEntries: {}, + navItem: { type: "page", title: "Test", path: "/guides/test" }, + }; + }); + + const result = buildAllOutputs(docsYml, cache); + + expect(result.algoliaRecords).toHaveLength(1); + expect(result.algoliaRecords[0].title).toBe("Test"); + }); +}); diff --git a/src/content-indexer/core/__tests__/content-cache.test.ts b/src/content-indexer/core/__tests__/content-cache.test.ts new file mode 100644 index 000000000..8f14a039f --- /dev/null +++ b/src/content-indexer/core/__tests__/content-cache.test.ts @@ -0,0 +1,169 @@ +import { describe, expect, test } from "vitest"; + +import { + openApiSpecFactory, + openRpcSpecFactory, +} from "@/content-indexer/utils/test-factories.js"; + +import { ContentCache } from "../content-cache.ts"; + +describe("ContentCache", () => { + test("should initialize with empty caches", () => { + const cache = new ContentCache(); + const stats = cache.getStats(); + + expect(stats.mdxCount).toBe(0); + expect(stats.specCount).toBe(0); + }); + + test("should store and retrieve MDX content", () => { + const cache = new ContentCache(); + const mdxEntry = { + frontmatter: { title: "Quickstart", slug: "guides/quickstart" }, + content: "# Quickstart\n\nContent here", + }; + + cache.setMdxContent("fern/guides/quickstart.mdx", mdxEntry); + const retrieved = cache.getMdxContent("fern/guides/quickstart.mdx"); + + expect(retrieved).toEqual(mdxEntry); + expect(retrieved?.frontmatter.title).toBe("Quickstart"); + }); + + test("should return undefined for non-existent MDX", () => { + const cache = new ContentCache(); + const retrieved = cache.getMdxContent("non-existent.mdx"); + + expect(retrieved).toBeUndefined(); + }); + + test("should store and retrieve OpenAPI spec", () => { + const cache = new ContentCache(); + const spec = openApiSpecFactory(); + const specEntry = { + specType: "openapi" as const, + spec: spec, + specUrl: "https://example.com/spec.json", + }; + + cache.setSpec("ethereum-api", specEntry); + const retrieved = cache.getSpec("ethereum-api"); + + expect(retrieved).toEqual(specEntry); + expect(retrieved?.specType).toBe("openapi"); + }); + + test("should store and retrieve OpenRPC spec", () => { + const cache = new ContentCache(); + const spec = openRpcSpecFactory(); + const specEntry = { + specType: "openrpc" as const, + spec: spec, + specUrl: "https://example.com/rpc-spec.json", + }; + + cache.setSpec("solana-das-api", specEntry); + const retrieved = cache.getSpec("solana-das-api"); + + expect(retrieved).toEqual(specEntry); + expect(retrieved?.specType).toBe("openrpc"); + }); + + test("should return undefined for non-existent spec", () => { + const cache = new ContentCache(); + const retrieved = cache.getSpec("non-existent-api"); + + expect(retrieved).toBeUndefined(); + }); + + test("should handle multiple MDX entries", () => { + const cache = new ContentCache(); + + cache.setMdxContent("file1.mdx", { + frontmatter: { title: "Page 1" }, + content: "Content 1", + }); + cache.setMdxContent("file2.mdx", { + frontmatter: { title: "Page 2" }, + content: "Content 2", + }); + + expect(cache.getMdxContent("file1.mdx")?.frontmatter.title).toBe("Page 1"); + expect(cache.getMdxContent("file2.mdx")?.frontmatter.title).toBe("Page 2"); + }); + + test("should handle multiple spec entries", () => { + const cache = new ContentCache(); + + cache.setSpec("api1", { + specType: "openapi", + spec: openApiSpecFactory(), + specUrl: "url1", + }); + cache.setSpec("api2", { + specType: "openrpc", + spec: openRpcSpecFactory(), + specUrl: "url2", + }); + + expect(cache.getSpec("api1")?.specType).toBe("openapi"); + expect(cache.getSpec("api2")?.specType).toBe("openrpc"); + }); + + test("should return correct stats with mixed content", () => { + const cache = new ContentCache(); + + cache.setMdxContent("file1.mdx", { + frontmatter: {}, + content: "Content 1", + }); + cache.setMdxContent("file2.mdx", { + frontmatter: {}, + content: "Content 2", + }); + cache.setSpec("api1", { + specType: "openapi", + spec: openApiSpecFactory(), + specUrl: "url1", + }); + + const stats = cache.getStats(); + expect(stats.mdxCount).toBe(2); + expect(stats.specCount).toBe(1); + }); + + test("should overwrite existing MDX entry", () => { + const cache = new ContentCache(); + + cache.setMdxContent("file.mdx", { + frontmatter: { title: "Old Title" }, + content: "Old content", + }); + cache.setMdxContent("file.mdx", { + frontmatter: { title: "New Title" }, + content: "New content", + }); + + const retrieved = cache.getMdxContent("file.mdx"); + expect(retrieved?.frontmatter.title).toBe("New Title"); + }); + + test("should overwrite existing spec entry", () => { + const cache = new ContentCache(); + + cache.setSpec("api", { + specType: "openapi", + spec: openApiSpecFactory({ info: { title: "API", version: "1.0.0" } }), + specUrl: "url1", + }); + cache.setSpec("api", { + specType: "openrpc", + spec: openRpcSpecFactory({ info: { title: "API", version: "2.0.0" } }), + specUrl: "url2", + }); + + const retrieved = cache.getSpec("api"); + expect(retrieved?.specType).toBe("openrpc"); + expect(retrieved?.specUrl).toBe("url2"); + }); +}); diff --git a/src/content-indexer/core/__tests__/path-builder.test.ts b/src/content-indexer/core/__tests__/path-builder.test.ts new file mode 100644 index 000000000..757a59266 --- /dev/null +++ b/src/content-indexer/core/__tests__/path-builder.test.ts @@ -0,0 +1,93 @@ +import { describe, expect, test } from "vitest"; + +import { PathBuilder } from "../path-builder.ts"; + +describe("PathBuilder", () => { + test("should initialize with empty parts", () => { + const builder = PathBuilder.init(); + expect(builder.get()).toBe(""); + }); + + test("should initialize with base path", () => { + const builder = PathBuilder.init("guides/getting-started"); + expect(builder.get()).toBe("guides/getting-started"); + }); + + test("should build path with single urlSlug", () => { + const builder = PathBuilder.init(); + const newBuilder = builder.apply({ urlSlug: "guides" }); + expect(newBuilder.get()).toBe("guides"); + }); + + test("should chain multiple urlSlug applications", () => { + const builder = PathBuilder.init(); + const newBuilder = builder + .apply({ urlSlug: "guides" }) + .apply({ urlSlug: "quickstart" }); + expect(newBuilder.get()).toBe("guides/quickstart"); + }); + + test("should handle fullSlug override", () => { + const builder = PathBuilder.init(); + const newBuilder = builder + .apply({ urlSlug: "guides" }) + .apply({ fullSlug: ["reference", "ethereum", "getbalance"] }); + expect(newBuilder.get()).toBe("reference/ethereum/getbalance"); + }); + + test("should build immutable path - original unchanged", () => { + const builder1 = PathBuilder.init(); + const builder2 = builder1.apply({ urlSlug: "guides" }); + const builder3 = builder2.apply({ urlSlug: "quickstart" }); + + expect(builder1.get()).toBe(""); + expect(builder2.get()).toBe("guides"); + expect(builder3.get()).toBe("guides/quickstart"); + }); + + test("should handle empty fullSlug array", () => { + const builder = PathBuilder.init(); + const newBuilder = builder.apply({ fullSlug: [] }); + expect(newBuilder.get()).toBe(""); + }); + + test("should handle fullSlug with single element", () => { + const builder = PathBuilder.init(); + const newBuilder = builder.apply({ fullSlug: ["guides"] }); + expect(newBuilder.get()).toBe("guides"); + }); + + test("should prefer fullSlug over urlSlug when both provided", () => { + const builder = PathBuilder.init(); + const newBuilder = builder.apply({ + urlSlug: "ignored", + fullSlug: ["reference", "ethereum"], + }); + expect(newBuilder.get()).toBe("reference/ethereum"); + }); + + test("should handle skipUrlSlug flag", () => { + const builder = PathBuilder.init(); + const step1 = builder.apply({ urlSlug: "guides" }); + const step2 = step1.apply({ skipUrlSlug: true }); + expect(step2.get()).toBe("guides"); + }); + + test("should handle complex path building scenario", () => { + const builder = PathBuilder.init(); + const step1 = builder.apply({ urlSlug: "reference" }); + const step2 = step1.apply({ urlSlug: "nft-api" }); + const step3 = step2.apply({ urlSlug: "getnfts" }); + + expect(step3.get()).toBe("reference/nft-api/getnfts"); + }); + + test("should handle path replacement mid-chain", () => { + const builder = PathBuilder.init(); + const step1 = builder.apply({ urlSlug: "guides" }); + const step2 = step1.apply({ urlSlug: "advanced" }); + const step3 = step2.apply({ fullSlug: ["reference", "api"] }); + + expect(step3.get()).toBe("reference/api"); + }); +}); diff --git a/src/content-indexer/core/__tests__/scanner.test.ts b/src/content-indexer/core/__tests__/scanner.test.ts new file mode 100644 index 000000000..ab3ee8c02 --- /dev/null +++ b/src/content-indexer/core/__tests__/scanner.test.ts @@ -0,0 +1,265 @@ +import { describe, expect, test } from "vitest"; + +import type { DocsYml } from "@/content-indexer/types/docsYaml.ts"; + +import { scanDocsYml } from "../scanner.ts"; + +describe("scanner", () => { + test("should throw error if navigation is missing", () => { + const docsYml = {} as DocsYml; + + expect(() => scanDocsYml(docsYml)).toThrow( + "Can't find navigation section in docs.yml", + ); + }); + + test("should scan pages from navigation", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "guides", + layout: [ + { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + { + page: "Advanced", + path: "fern/guides/advanced.mdx", + }, + ], + }, + ], + }; + + const result = scanDocsYml(docsYml); + expect(result.mdxPaths).toContain("fern/guides/quickstart.mdx"); + expect(result.mdxPaths).toContain("fern/guides/advanced.mdx"); + expect(result.mdxPaths.size).toBe(2); + }); + + test("should scan API specs from navigation", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "reference", + layout: [ + { + api: "Ethereum API", + "api-name": "ethereum-api", + }, + { + api: "NFT API", + "api-name": "nft-api", + }, + ], + }, + ], + }; + + const result = scanDocsYml(docsYml); + expect(result.specNames).toContain("ethereum-api"); + expect(result.specNames).toContain("nft-api"); + expect(result.specNames.size).toBe(2); + }); + + test("should handle sections with nested pages", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "guides", + layout: [ + { + section: "Getting Started", + contents: [ + { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + { + page: "Installation", + path: "fern/guides/installation.mdx", + }, + ], + }, + ], + }, + ], + }; + + const result = scanDocsYml(docsYml); + expect(result.mdxPaths).toContain("fern/guides/quickstart.mdx"); + expect(result.mdxPaths).toContain("fern/guides/installation.mdx"); + expect(result.mdxPaths.size).toBe(2); + }); + + test("should handle section with overview page", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "guides", + layout: [ + { + section: "Getting Started", + path: "fern/guides/overview.mdx", + contents: [ + { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + ], + }, + ], + }, + ], + }; + + const result = scanDocsYml(docsYml); + expect(result.mdxPaths).toContain("fern/guides/overview.mdx"); + expect(result.mdxPaths).toContain("fern/guides/quickstart.mdx"); + expect(result.mdxPaths.size).toBe(2); + }); + + test("should skip links in navigation", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "guides", + layout: [ + { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + { + link: "External Link", + href: "https://example.com", + }, + ], + }, + ], + }; + + const result = scanDocsYml(docsYml); + expect(result.mdxPaths.size).toBe(1); + expect(result.mdxPaths).toContain("fern/guides/quickstart.mdx"); + }); + + test("should skip changelog in navigation", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "guides", + layout: [ + { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + { + changelog: "CHANGELOG.md", + }, + ], + }, + ], + }; + + const result = scanDocsYml(docsYml); + expect(result.mdxPaths.size).toBe(1); + }); + + test("should handle deeply nested sections", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "guides", + layout: [ + { + section: "Level 1", + contents: [ + { + section: "Level 2", + contents: [ + { + page: "Deep Page", + path: "fern/guides/deep.mdx", + }, + ], + }, + ], + }, + ], + }, + ], + }; + + const result = scanDocsYml(docsYml); + expect(result.mdxPaths).toContain("fern/guides/deep.mdx"); + }); + + test("should deduplicate paths using Set", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "tab1", + layout: [ + { + page: "Page", + path: "fern/guides/page.mdx", + }, + ], + }, + { + tab: "tab2", + layout: [ + { + page: "Page", + path: "fern/guides/page.mdx", // Duplicate + }, + ], + }, + ], + }; + + const result = scanDocsYml(docsYml); + expect(result.mdxPaths.size).toBe(1); + }); + + test("should handle mixed content types", () => { + const docsYml: DocsYml = { + navigation: [ + { + tab: "all", + layout: [ + { + page: "Guide", + path: "fern/guides/guide.mdx", + }, + { + api: "API", + "api-name": "my-api", + }, + { + section: "Section", + contents: [ + { + page: "Nested", + path: "fern/guides/nested.mdx", + }, + ], + }, + { + link: "Link", + href: "https://example.com", + }, + ], + }, + ], + }; + + const result = scanDocsYml(docsYml); + expect(result.mdxPaths.size).toBe(2); + expect(result.specNames.size).toBe(1); + expect(result.mdxPaths).toContain("fern/guides/guide.mdx"); + expect(result.mdxPaths).toContain("fern/guides/nested.mdx"); + expect(result.specNames).toContain("my-api"); + }); +}); diff --git a/src/content-indexer/core/batch-fetcher.ts b/src/content-indexer/core/batch-fetcher.ts new file mode 100644 index 000000000..c6e3ae4bb --- /dev/null +++ b/src/content-indexer/core/batch-fetcher.ts @@ -0,0 +1,104 @@ +import matter from "gray-matter"; +import path from "path"; + +import { fetchApiSpec } from "@/content-indexer/utils/apiSpecs.ts"; +import { readLocalMdxFile } from "@/content-indexer/utils/filesystem.ts"; +import { + fetchFileFromGitHub, + type RepoConfig, +} from "@/content-indexer/utils/github.js"; + +import { ContentCache } from "./content-cache.ts"; +import type { ScanResult } from "./scanner.ts"; + +/** + * Content source configuration - either filesystem or GitHub API + */ +export type ContentSource = + | { type: "filesystem"; basePath: string } + | { type: "github"; repoConfig: RepoConfig }; + +/** + * Fetches all MDX files and API specs in parallel and populates the cache. + * This is the core optimization: all I/O happens upfront in parallel. + * + * Supports two modes: + * - filesystem: Reads from local filesystem (for preview mode) + * - github: Fetches from GitHub API (for production/SDK indexer) + * + * @param scanResult - Result from scanDocsYml containing all paths and spec names + * @param source - Content source (filesystem or GitHub) + * @returns Populated ContentCache ready for processing + */ +export const batchFetchContent = async ( + scanResult: ScanResult, + source: ContentSource, +): Promise => { + const cache = new ContentCache(); + + const sourceType = source.type; + console.info( + ` ${sourceType === "filesystem" ? "Reading" : "Fetching"} ${scanResult.mdxPaths.size} MDX files and ${scanResult.specNames.size} specs...`, + ); + + // Fetch/read all MDX files in parallel + const mdxPromises = Array.from(scanResult.mdxPaths).map(async (mdxPath) => { + try { + if (source.type === "filesystem") { + // Read from local filesystem + const fullPath = path.join(source.basePath, mdxPath); + const result = await readLocalMdxFile(fullPath); + + if (result) { + cache.setMdxContent(mdxPath, { + frontmatter: result.frontmatter, + content: result.content, + }); + } + } else { + // Fetch from GitHub API + const actualPath = mdxPath.replace( + source.repoConfig.stripPathPrefix || "", + "", + ); + const fullPath = `${source.repoConfig.docsPrefix}/${actualPath}`; + + const content = await fetchFileFromGitHub(fullPath, source.repoConfig); + if (content) { + const { data, content: body } = matter(content); + cache.setMdxContent(mdxPath, { + frontmatter: data, + content: body, + }); + } + } + } catch (error) { + console.warn( + ` ⚠️ Failed to ${source.type === "filesystem" ? "read" : "fetch"} MDX file: ${mdxPath}`, + error, + ); + } + }); + + // Fetch all API specs in parallel (always from remote) + const specPromises = Array.from(scanResult.specNames).map(async (apiName) => { + try { + const result = await fetchApiSpec(apiName); + if (result) { + cache.setSpec(apiName, result); + } + } catch (error) { + console.warn(` ⚠️ Failed to fetch spec: ${apiName}`, error); + } + }); + + // Wait for all fetches to complete + await Promise.all([...mdxPromises, ...specPromises]); + + const stats = cache.getStats(); + console.info( + ` ✓ ${sourceType === "filesystem" ? "Read" : "Fetched"} ${stats.mdxCount}/${scanResult.mdxPaths.size} MDX files and ${stats.specCount}/${scanResult.specNames.size} specs`, + ); + + return cache; +}; diff --git a/src/content-indexer/core/build-all-outputs.ts b/src/content-indexer/core/build-all-outputs.ts new file mode 100644 index 000000000..2b0811226 --- /dev/null +++ b/src/content-indexer/core/build-all-outputs.ts @@ -0,0 +1,85 @@ +import { kebabCase } from "lodash-es"; + +import { + ProcessingContext, + type BuildAllOutputsResult, +} from "@/content-indexer/collectors/processing-context.js"; +import type { ContentCache } from "@/content-indexer/core/content-cache.ts"; +import type { DocsYml } from "@/content-indexer/types/docsYaml.ts"; +import { DOCS_REPO, type RepoConfig } from "@/content-indexer/utils/github.ts"; +import { visitNavigationItem } from "@/content-indexer/visitors/index.ts"; + +import { PathBuilder } from "./path-builder.ts"; + +/** + * Phase 3 of the content indexing pipeline. + * Builds path index, navigation trees, and Algolia records in a single traversal. + * + * Uses visitor pattern to process each navigation item type and accumulates + * results in ProcessingContext. Maintains navigation hierarchy and breadcrumb + * context during traversal. + */ +export const buildAllOutputs = ( + docsYml: DocsYml, + contentCache: ContentCache, + repo: RepoConfig = DOCS_REPO, +): BuildAllOutputsResult => { + const context = new ProcessingContext(); + + // Process each tab in docs.yml + docsYml.navigation.forEach((navItem) => { + // Skip navigation items without a tab or layout + if (!navItem.tab || !navItem.layout) { + return; + } + + // Tab identifier for the index entries + const tab = kebabCase(navItem.tab); + + // Build base path for this tab + let basePathBuilder = PathBuilder.init(); + + // Apply tab slug to path (use slug from tab config if available) + const tabConfig = docsYml.tabs?.[navItem.tab]; + if (tabConfig) { + const tabSlugForPath = tabConfig.slug ?? tab; + const skipTabSlug = tabConfig["skip-slug"] ?? false; + + basePathBuilder = basePathBuilder.apply({ + urlSlug: tabSlugForPath, + skipUrlSlug: skipTabSlug, + }); + } + + // Visit all layout items using visitor pattern + const results = navItem.layout.map((layoutItem) => + visitNavigationItem({ + item: layoutItem, + parentPath: basePathBuilder, + tab, + repo, + contentCache, + context, + navigationAncestors: [], // Empty ancestors at top level + }), + ); + + // Add results to context + results.forEach((result) => { + // Add path index entries + Object.entries(result.indexEntries).forEach(([path, entry]) => { + context.addPathIndexEntry(path, entry); + }); + + // Add navigation items + if (result.navItem) { + const items = Array.isArray(result.navItem) + ? result.navItem + : [result.navItem]; + items.forEach((item) => context.addNavigationItem(tab, item)); + } + }); + }); + + return context.getResults(); +}; diff --git a/src/content-indexer/core/content-cache.ts b/src/content-indexer/core/content-cache.ts new file mode 100644 index 000000000..8b5d6fdb2 --- /dev/null +++ b/src/content-indexer/core/content-cache.ts @@ -0,0 +1,86 @@ +import type { + OpenApiSpec, + OpenRpcSpec, +} from "@/content-indexer/types/specs.js"; + +/** + * Cached MDX content with parsed frontmatter and body. + */ +export interface MdxCacheEntry { + frontmatter: { + slug?: string; + title?: string; + sidebarTitle?: string; + [key: string]: unknown; + }; + content: string; // Raw MDX body (without frontmatter) +} + +/** + * Cached API spec with type information. + */ +export interface SpecCacheEntry { + specType: "openrpc" | "openapi"; + spec: OpenRpcSpec | OpenApiSpec; + specUrl: string; +} + +/** + * Cache statistics returned by getStats(). + */ +export interface CacheStats { + mdxCount: number; + specCount: number; +} + +/** + * In-memory cache for all fetched content. + * Provides O(1) lookup for MDX files and API specs. + */ +export class ContentCache { + private mdxCache: Map; + private specCache: Map; + + constructor() { + this.mdxCache = new Map(); + this.specCache = new Map(); + } + + /** + * Store MDX content by normalized file path. + */ + setMdxContent(filePath: string, entry: MdxCacheEntry): void { + this.mdxCache.set(filePath, entry); + } + + /** + * Retrieve MDX content by file path. + */ + getMdxContent(filePath: string): MdxCacheEntry | undefined { + return this.mdxCache.get(filePath); + } + + /** + * Store API spec by api-name. + */ + setSpec(apiName: string, entry: SpecCacheEntry): void { + this.specCache.set(apiName, entry); + } + + /** + * Retrieve API spec by api-name. + */ + getSpec(apiName: string): SpecCacheEntry | undefined { + return this.specCache.get(apiName); + } + + /** + * Get cache statistics for debugging. + */ + getStats(): CacheStats { + return { + mdxCount: this.mdxCache.size, + specCount: this.specCache.size, + }; + } +} diff --git a/src/content-indexer/core/path-builder.ts b/src/content-indexer/core/path-builder.ts new file mode 100644 index 000000000..a9fa30de6 --- /dev/null +++ b/src/content-indexer/core/path-builder.ts @@ -0,0 +1,58 @@ +/** + * PathBuilder mimics Fern's slug generation logic to build full URL paths. + * Maintains an array of path segments and provides methods to build paths hierarchically. + * @note Fern incorrectly refers to full paths as "slugs" in their terminology + * @see https://buildwithfern.com/learn/docs/seo/configuring-slugs + */ +export class PathBuilder { + private segments: string[]; + + private constructor(segments: string[]) { + this.segments = segments; + } + + /** + * Creates a new PathBuilder instance with optional base path segments. + */ + static init(basePath: string = ""): PathBuilder { + const segments = basePath ? basePath.split("/").filter(Boolean) : []; + return new PathBuilder(segments); + } + + /** + * Applies slug generation rules to create a new PathBuilder. + * Supports three modes: + * - fullSlug: Completely replaces the path (used for frontmatter overrides) + * - skipUrlSlug: Returns unchanged path (used for skip-slug sections) + * - urlSlug: Appends to existing path (default behavior) + */ + apply(options: { + fullSlug?: string[]; + urlSlug?: string; + skipUrlSlug?: boolean; + }): PathBuilder { + // If fullSlug is provided (from frontmatter), it completely overrides the path + if (options.fullSlug) { + return new PathBuilder(options.fullSlug.filter(Boolean)); + } + + // If skipUrlSlug is true, don't add anything to the path + if (options.skipUrlSlug) { + return new PathBuilder([...this.segments]); + } + + // Otherwise, add the urlSlug to the path + if (options.urlSlug) { + return new PathBuilder([...this.segments, options.urlSlug]); + } + + return new PathBuilder([...this.segments]); + } + + /** + * Returns the full path as a string by joining all segments with "/". + */ + get(): string { + return this.segments.filter(Boolean).join("/"); + } +} diff --git a/src/content-indexer/core/scanner.ts b/src/content-indexer/core/scanner.ts new file mode 100644 index 000000000..bdc3558bb --- /dev/null +++ b/src/content-indexer/core/scanner.ts @@ -0,0 +1,85 @@ +import { + isApiConfig, + isChangelogConfig, + isLinkConfig, + isPageConfig, + isSectionConfig, + type DocsYml, + type NavigationItem, +} from "@/content-indexer/types/docsYaml.js"; + +/** + * Result of scanning docs.yml for all file paths and API specs. + */ +export interface ScanResult { + mdxPaths: Set; // All unique MDX file paths + specNames: Set; // All unique api-name values +} + +/** + * Recursively scans a navigation item to collect MDX paths and spec names. + */ +const scanNavigationItem = (item: NavigationItem, result: ScanResult): void => { + // Skip changelog items + if (isChangelogConfig(item)) { + return; + } + + // Skip external links + if (isLinkConfig(item)) { + return; + } + + // Collect API spec names + if (isApiConfig(item)) { + result.specNames.add(item["api-name"]); + return; + } + + // Collect page paths + if (isPageConfig(item)) { + result.mdxPaths.add(item.path); + return; + } + + // Collect section overview paths and recurse into contents + if (isSectionConfig(item)) { + if (item.path) { + result.mdxPaths.add(item.path); + } + + // Recursively scan all child items + item.contents.forEach((childItem) => { + scanNavigationItem(childItem, result); + }); + } +}; + +/** + * Scans the entire docs.yml to collect all MDX file paths and API spec names. + * This enables batch fetching all content in parallel. + * + * @param docsYml - The parsed docs.yml configuration + * @returns Object with Sets of unique MDX paths and spec names + */ +export const scanDocsYml = (docsYml: DocsYml): ScanResult => { + if (!docsYml.navigation) { + throw new Error("Can't find navigation section in docs.yml"); + } + + const result: ScanResult = { + mdxPaths: new Set(), + specNames: new Set(), + }; + + // Scan all navigation items across all tabs + docsYml.navigation.forEach((navItem) => { + if (navItem.layout) { + navItem.layout.forEach((layoutItem) => { + scanNavigationItem(layoutItem, result); + }); + } + }); + + return result; +}; diff --git a/src/content-indexer/index.ts b/src/content-indexer/index.ts new file mode 100644 index 000000000..c308d5f61 --- /dev/null +++ b/src/content-indexer/index.ts @@ -0,0 +1,144 @@ +#!/usr/bin/env tsx +import path from "path"; + +import { buildChangelogIndex } from "@/content-indexer/indexers/changelog.ts"; +import { buildDocsContentIndex } from "@/content-indexer/indexers/main.ts"; +import type { IndexerResult } from "@/content-indexer/types/indexer.ts"; +import { uploadToAlgolia } from "@/content-indexer/uploaders/algolia.ts"; +import { storeToRedis } from "@/content-indexer/uploaders/redis.ts"; +import { DOCS_REPO, WALLET_REPO } from "@/content-indexer/utils/github.ts"; + +// ============================================================================ +// CLI Argument Parsing +// ============================================================================ + +const parseArgs = () => { + const args = process.argv.slice(2); + + const indexer = + args.find((arg) => arg.startsWith("--indexer="))?.split("=")[1] || "main"; + const mode = + args.find((arg) => arg.startsWith("--mode="))?.split("=")[1] || + "production"; + const branch = + args.find((arg) => arg.startsWith("--branch="))?.split("=")[1] || "main"; + + // Validate arguments + if (!["main", "sdk", "changelog"].includes(indexer)) { + throw new Error( + `Invalid indexer: ${indexer}. Must be 'main', 'sdk', or 'changelog'`, + ); + } + + if (!["preview", "production"].includes(mode)) { + throw new Error(`Invalid mode: ${mode}. Must be 'preview' or 'production'`); + } + + return { + indexer: indexer as "main" | "sdk" | "changelog", + mode: mode as "preview" | "production", + branchId: branch, + }; +}; + +// ============================================================================ +// Indexer Runner +// ============================================================================ + +const buildIndexResults = async ( + indexerType: "main" | "sdk" | "changelog", + branchId: string, + mode: "preview" | "production" = "production", +): Promise => { + switch (indexerType) { + case "changelog": + return buildChangelogIndex({ + localBasePath: path.join(process.cwd(), "fern/changelog"), + branchId, + }); + case "main": + return buildDocsContentIndex({ + source: { + type: "filesystem", + basePath: path.join(process.cwd(), "fern"), + }, + repoConfig: DOCS_REPO, + branchId, + mode, + }); + case "sdk": { + const result = await buildDocsContentIndex({ + source: { type: "github", repoConfig: WALLET_REPO }, + repoConfig: WALLET_REPO, + branchId, + }); + return { + ...result, + navigationTrees: { + wallets: result.navigationTrees?.wallets || [], + }, + }; + } + } +}; + +const runIndexer = async ( + indexerType: "main" | "sdk" | "changelog", + branchId: string, + mode?: "preview" | "production", +) => { + console.info( + `\n🔍 Running ${indexerType.toUpperCase()} indexer${indexerType === "main" && mode ? ` (${mode} mode)` : ""} (branch: ${branchId})\n`, + ); + + const { pathIndex, algoliaRecords, navigationTrees } = + await buildIndexResults(indexerType, branchId, mode); + + const shouldUploadToAlgolia = mode !== "preview"; + + // Build upload promises array + const uploadPromises = [ + storeToRedis(pathIndex, navigationTrees, { branchId, indexerType }), + ]; + + if (shouldUploadToAlgolia) { + uploadPromises.push( + uploadToAlgolia(algoliaRecords, { indexerType, branchId }), + ); + console.info("\n📤 Uploading to Redis and Algolia..."); + } else { + console.info("\n📤 Uploading to Redis..."); + console.info( + " ℹ️ Skipping Algolia upload (preview mode uses prod search)", + ); + } + + await Promise.all(uploadPromises); + + console.info( + `\n✅ ${indexerType.charAt(0).toUpperCase() + indexerType.slice(1)} indexer completed! (${Object.keys(pathIndex).length} routes${shouldUploadToAlgolia ? `, ${algoliaRecords.length} records` : ""})`, + ); +}; + +// ============================================================================ +// Main Entry Point +// ============================================================================ + +const main = async () => { + try { + const { indexer, mode, branchId } = parseArgs(); + + console.info("🚀 Content Indexer"); + console.info("=================="); + console.info(` Indexer: ${indexer}`); + console.info(` Mode: ${mode}`); + console.info(` Branch: ${branchId}`); + + await runIndexer(indexer, branchId, mode); + } catch (error) { + console.error("\n❌ Error:", error); + process.exit(1); + } +}; + +void main(); diff --git a/src/content-indexer/indexers/changelog.ts b/src/content-indexer/indexers/changelog.ts new file mode 100644 index 000000000..b4e173786 --- /dev/null +++ b/src/content-indexer/indexers/changelog.ts @@ -0,0 +1,135 @@ +import { promises as fs } from "fs"; +import path from "path"; + +import type { AlgoliaRecord } from "@/content-indexer/types/algolia.ts"; +import type { IndexerResult } from "@/content-indexer/types/indexer.ts"; +import type { PathIndex } from "@/content-indexer/types/pathIndex.ts"; +import { readLocalFile } from "@/content-indexer/utils/filesystem.ts"; +import { truncateRecord } from "@/content-indexer/utils/truncate-record.ts"; + +export interface ChangelogIndexerConfig { + localBasePath: string; // Path to fern/changelog/ directory + branchId: string; +} + +/** + * Parse a changelog filename (e.g., "2025-11-20.md") into date components + */ +const parseChangelogFilename = ( + filename: string, +): { + date: string; + year: string; + month: string; + day: string; +} | null => { + const match = filename.match(/^(\d{4})-(\d{2})-(\d{2})\.md$/); + if (!match) return null; + + const [, year, month, day] = match; + return { + date: `${year}-${month}-${day}`, + year, + month, + day, + }; +}; + +/** + * Changelog indexer for changelog entries. + * Simpler than main indexer - no nav trees, just path index and Algolia. + * + * Updates: + * - {branch}/path-index:changelog + * - {branch}_alchemy_docs_changelog Algolia index + */ +export const buildChangelogIndex = async ( + config: ChangelogIndexerConfig, +): Promise => { + console.info(`🔍 Building changelog index (branch: ${config.branchId})...`); + + // Read all files from changelog directory + const files = await fs.readdir(config.localBasePath); + + // Filter and parse changelog files + const changelogFiles = files + .map((filename) => { + const parsed = parseChangelogFilename(filename); + if (!parsed) { + // Silently skip dotfiles (.gitkeep, .DS_Store, etc.) + if (!filename.startsWith(".")) { + console.warn(` ⚠️ Skipping non-date file: ${filename}`); + } + return null; + } + return { filename, ...parsed }; + }) + .filter((entry): entry is NonNullable => entry !== null); + + // Sort by date descending (newest first) + changelogFiles.sort((a, b) => b.date.localeCompare(a.date)); + + console.info(` 📄 Found ${changelogFiles.length} changelog entries`); + + const resultPromises = changelogFiles.map( + async ({ filename, date, year, month, day }) => { + const filePath = path.join(config.localBasePath, filename); + const content = await readLocalFile(filePath); + + if (!content) { + console.warn(` ⚠️ Failed to read: ${filename}`); + return null; + } + + // Build route: e.g., "2025/11/20" + const route = `${year}/${Number(month)}/${Number(day)}`; + + // Create path index entry + const pathIndexEntry = { + type: "mdx" as const, + filePath: `fern/changelog/${filename}`, + source: "changelog" as const, + tab: "changelog", + }; + + // Create Algolia record + const algoliaRecord = truncateRecord({ + objectID: `changelog-${date}`, + title: `Changelog - ${date}`, + content, // Raw markdown - truncateRecord will clean it + path: `changelog/${route}`, + pageType: "Changelog" as const, + breadcrumbs: ["Changelog", date], + }); + + return { route, pathIndexEntry, algoliaRecord }; + }, + ); + + const results = await Promise.all(resultPromises); + + // Build final outputs from results + const { pathIndex, algoliaRecords } = results.reduce<{ + pathIndex: PathIndex; + algoliaRecords: AlgoliaRecord[]; + }>( + (acc, result) => { + if (result) { + acc.pathIndex[result.route] = result.pathIndexEntry; + acc.algoliaRecords.push(result.algoliaRecord); + } + return acc; + }, + { pathIndex: {}, algoliaRecords: [] }, + ); + + console.info( + `\n📊 Changelog index complete: ${Object.keys(pathIndex).length} routes, ${algoliaRecords.length} Algolia records`, + ); + + return { + pathIndex, + algoliaRecords, + navigationTrees: undefined, // changelog has no sidebar nav + }; +}; diff --git a/src/content-indexer/indexers/main.ts b/src/content-indexer/indexers/main.ts new file mode 100644 index 000000000..d26921aaf --- /dev/null +++ b/src/content-indexer/indexers/main.ts @@ -0,0 +1,75 @@ +import yaml from "js-yaml"; + +import { + batchFetchContent, + type ContentSource, +} from "@/content-indexer/core/batch-fetcher.js"; +import { buildAllOutputs } from "@/content-indexer/core/build-all-outputs.ts"; +import { scanDocsYml } from "@/content-indexer/core/scanner.ts"; +import type { DocsYml } from "@/content-indexer/types/docsYaml.ts"; +import type { IndexerResult } from "@/content-indexer/types/indexer.ts"; +import { readLocalDocsYml } from "@/content-indexer/utils/filesystem.ts"; +import { + fetchFileFromGitHub, + type RepoConfig, +} from "@/content-indexer/utils/github.js"; + +export interface DocsIndexerConfig { + source: ContentSource; // filesystem or github + repoConfig: RepoConfig; + branchId: string; + mode?: "preview" | "production"; // Only relevant for logging +} + +/** + * Unified docs content indexer. + * Handles both main docs (local filesystem) and SDK refs (GitHub API). + * + * Processes docs.yml through 3 phases: + * 1. SCAN - Parse docs.yml to discover all paths and specs + * 2. BATCH FETCH - Read all content (filesystem or GitHub) + * 3. PROCESS - Build path index, navigation trees, and Algolia records + */ +export const buildDocsContentIndex = async ( + config: DocsIndexerConfig, +): Promise => { + console.info(`🔍 Building content index (branch: ${config.branchId})...`); + + // Read docs.yml based on source type + let docsYml: DocsYml; + if (config.source.type === "filesystem") { + const result = await readLocalDocsYml(config.source.basePath); + if (!result) { + throw new Error(`Failed to read docs.yml from ${config.source.basePath}`); + } + docsYml = result; + } else { + const docsYmlPath = `${config.repoConfig.docsPrefix}/docs.yml`; + const content = await fetchFileFromGitHub(docsYmlPath, config.repoConfig); + if (!content) { + throw new Error(`Failed to fetch ${docsYmlPath} from GitHub`); + } + docsYml = yaml.load(content) as DocsYml; + } + + // PHASE 1: SCAN + console.info("📋 Phase 1: Scanning docs.yml..."); + const scanResult = scanDocsYml(docsYml); + console.info( + ` Found ${scanResult.mdxPaths.size} MDX files, ${scanResult.specNames.size} specs`, + ); + + // PHASE 2: BATCH FETCH + console.info("📥 Phase 2: Fetching content..."); + const contentCache = await batchFetchContent(scanResult, config.source); + + // PHASE 3: PROCESS + console.info("⚙️ Phase 3: Processing..."); + const outputs = buildAllOutputs(docsYml, contentCache, config.repoConfig); + + console.info( + `📊 Generated ${Object.keys(outputs.pathIndex).length} routes, ${outputs.algoliaRecords.length} Algolia records`, + ); + + return outputs; +}; diff --git a/src/content-indexer/types/algolia.ts b/src/content-indexer/types/algolia.ts new file mode 100644 index 000000000..2bc35e6ea --- /dev/null +++ b/src/content-indexer/types/algolia.ts @@ -0,0 +1,14 @@ +/** + * Algolia search record structure. + * Each record represents a searchable page (Guide or API method). + */ +export interface AlgoliaRecord { + objectID: string; // Hash-based unique identifier - REQUIRED by Algolia + path: string; // Full pathname without leading slash (e.g., "reference/ethereum/eth-getbalance"). + pageType: "API Method" | "Guide" | "Changelog"; + title: string; + description?: string; // Brief 1-2 sentence summary of the content + breadcrumbs: string[]; // Navigation ancestry titles for context (e.g., ["NFT API", "NFT API Endpoints"]) + httpMethod?: string; // For API methods: "GET" | "POST" | etc. + content: string; // MDX content or endpoint description +} diff --git a/src/content-indexer/types/breadcrumb.ts b/src/content-indexer/types/breadcrumb.ts new file mode 100644 index 000000000..da84b74a9 --- /dev/null +++ b/src/content-indexer/types/breadcrumb.ts @@ -0,0 +1,8 @@ +/** + * Represents a single item in the breadcrumb trail + */ +export interface BreadcrumbItem { + title: string; + path: string; + type: "tab" | "section" | "page" | "endpoint"; +} diff --git a/src/content-indexer/types/changelog.ts b/src/content-indexer/types/changelog.ts new file mode 100644 index 000000000..6c8c77483 --- /dev/null +++ b/src/content-indexer/types/changelog.ts @@ -0,0 +1,28 @@ +// TODO: This file is copied from docs-site but not fully used in Phase 2 +// MDXRemoteSerializeResult type is stubbed until changelog indexer is implemented in Phase 3 +type MDXRemoteSerializeResult = unknown; + +export interface ChangelogIndexEntry { + date: string; // YYYY-MM-DD format + fileName: string; // e.g., "2025-11-20.md" +} + +/** + * Maps changelog routes (e.g., "2025/11/20") to their metadata. Sorted by date (newest first). + */ +export type ChangelogIndex = Record; + +export interface SerializedChangelogEntry { + date: string; + serializedContent: MDXRemoteSerializeResult; +} + +export interface ChangelogApiSuccess { + entries: SerializedChangelogEntry[]; + hasMore: boolean; + total: number; +} + +export interface ChangelogApiError { + error: string; +} diff --git a/src/content-indexer/types/docsYaml.ts b/src/content-indexer/types/docsYaml.ts new file mode 100644 index 000000000..e3fa0f1ae --- /dev/null +++ b/src/content-indexer/types/docsYaml.ts @@ -0,0 +1,91 @@ +// Types for parsing Fern's docs.yml structure + +export interface PageConfig { + page: string; + path: string; + slug?: string; + hidden?: boolean; + noindex?: boolean; +} + +export interface SectionConfig { + section: string; + slug?: string; + "skip-slug"?: boolean; + hidden?: boolean; + contents: NavigationItem[]; + path?: string; // Optional overview page +} + +export interface LinkConfig { + link: string; + href: string; +} + +export interface ApiConfig { + api: string; + "api-name": string; + slug?: string; + "skip-slug"?: boolean; + hidden?: boolean; + flattened?: boolean; + paginated?: boolean; +} + +export interface ChangelogConfig { + changelog: string; + slug?: string; +} + +export type NavigationItem = + | PageConfig + | SectionConfig + | LinkConfig + | ApiConfig + | ChangelogConfig; + +export interface TabConfig { + "display-name": string; + slug?: string; + "skip-slug"?: boolean; +} + +export interface DocsYml { + tabs?: Record; + navigation: Array<{ + tab: string; + layout: NavigationItem[]; + }>; +} + +// ============================================================================ +// Type Guards +// ============================================================================ + +export const isPageConfig = (item: NavigationItem): item is PageConfig => { + return item && typeof item === "object" && "page" in item && "path" in item; +}; + +export const isSectionConfig = ( + item: NavigationItem, +): item is SectionConfig => { + return ( + item && typeof item === "object" && "section" in item && "contents" in item + ); +}; + +export const isLinkConfig = (item: NavigationItem): item is LinkConfig => { + return item && typeof item === "object" && "link" in item && "href" in item; +}; + +export const isApiConfig = (item: NavigationItem): item is ApiConfig => { + return ( + item && typeof item === "object" && "api" in item && "api-name" in item + ); +}; + +export const isChangelogConfig = ( + item: NavigationItem, +): item is ChangelogConfig => { + return item && typeof item === "object" && "changelog" in item; +}; diff --git a/src/content-indexer/types/indexer.ts b/src/content-indexer/types/indexer.ts new file mode 100644 index 000000000..a7d80ed45 --- /dev/null +++ b/src/content-indexer/types/indexer.ts @@ -0,0 +1,12 @@ +import type { AlgoliaRecord } from "@/content-indexer/types/algolia.ts"; +import type { NavigationTreesByTab } from "@/content-indexer/types/navigation.ts"; +import type { PathIndex } from "@/content-indexer/types/pathIndex.ts"; + +/** + * Standard result structure returned by all indexers. + */ +export interface IndexerResult { + pathIndex: PathIndex; + algoliaRecords: AlgoliaRecord[]; + navigationTrees: NavigationTreesByTab | undefined; +} diff --git a/src/content-indexer/types/navigation.ts b/src/content-indexer/types/navigation.ts new file mode 100644 index 000000000..715487492 --- /dev/null +++ b/src/content-indexer/types/navigation.ts @@ -0,0 +1,37 @@ +// Types for navigation tree structure stored in Redis + +interface BaseNavItem { + title: string; +} + +interface PageNavItem extends BaseNavItem { + type: "page"; + path: string; +} + +interface EndpointNavItem extends BaseNavItem { + type: "endpoint"; + path: string; + method: string; +} + +interface SectionNavItem extends BaseNavItem { + type: "section" | "api-section"; + path?: string; + children: NavItem[]; +} + +interface LinkNavItem extends BaseNavItem { + type: "link"; + href: string; +} + +export type NavItem = + | PageNavItem + | EndpointNavItem + | SectionNavItem + | LinkNavItem; + +export type NavigationTree = NavItem[]; + +export type NavigationTreesByTab = Record; diff --git a/src/content-indexer/types/openRpc.ts b/src/content-indexer/types/openRpc.ts new file mode 100644 index 000000000..41a8d3f79 --- /dev/null +++ b/src/content-indexer/types/openRpc.ts @@ -0,0 +1,12 @@ +export type AuthParamLocation = "path" | "header" | "query"; + +export interface AuthParameter { + name: string; + in: AuthParamLocation; + schema: { + type: string; + default?: string; + description?: string; + }; + required: boolean; +} diff --git a/src/content-indexer/types/page.ts b/src/content-indexer/types/page.ts new file mode 100644 index 000000000..b794cbdd9 --- /dev/null +++ b/src/content-indexer/types/page.ts @@ -0,0 +1,57 @@ +/** + * Frontmatter for a documentation page + * @see https://buildwithfern.com/learn/docs/configuration/page-level-settings + */ +export interface DocPageFrontmatter { + title?: string; + "sidebar-title"?: string; + subtitle?: string; + slug?: string; + description?: string; + "edit-this-page-url"?: string; + image?: string; + + "hide-toc"?: boolean; + "max-toc-depth"?: number; + + "hide-nav-links"?: boolean; + "hide-feedback"?: boolean; + + logo?: { + light: string; + dark: string; + }; + layout?: "guide" | "overview" | "reference" | "page" | "custom"; + headline?: string; + "canonical-url"?: string; + keywords?: string; + + "og:site_name"?: string; + "og:title"?: string; + "og:description"?: string; + "og:url"?: string; + "og:image"?: string; + "og:image:width"?: number; + "og:image:height"?: number; + "og:locale"?: string; + "og:logo"?: string; + + // SEO - Twitter properties + "twitter:title"?: string; + "twitter:description"?: string; + "twitter:handle"?: string; + "twitter:image"?: string; + "twitter:site"?: string; + "twitter:url"?: string; + "twitter:card"?: "summary" | "summary_large_image" | "app" | "player"; + + noindex?: boolean; + nofollow?: boolean; + tags?: string[]; +} + +export interface DocPage { + slug: string[]; + frontmatter: DocPageFrontmatter; + content: string; +} diff --git a/src/content-indexer/types/pathIndex.ts b/src/content-indexer/types/pathIndex.ts new file mode 100644 index 000000000..e02aa4f5d --- /dev/null +++ b/src/content-indexer/types/pathIndex.ts @@ -0,0 +1,29 @@ +export interface MdxPathIndexEntry { + type: "mdx"; + filePath: string; + source: "frontmatter" | "docs-yml" | "runtime-discovery" | "changelog"; + tab: string; +} + +export interface OpenRpcPathIndexEntry { + type: "openrpc"; + specUrl: string; + methodName: string; + source: "docs-yml"; + tab: string; +} + +export interface OpenApiPathIndexEntry { + type: "openapi"; + specUrl: string; + operationId: string; + source: "docs-yml"; + tab: string; +} + +export type PathIndexEntry = + | MdxPathIndexEntry + | OpenRpcPathIndexEntry + | OpenApiPathIndexEntry; + +export type PathIndex = Record; diff --git a/src/content-indexer/types/specs.ts b/src/content-indexer/types/specs.ts new file mode 100644 index 000000000..ea0764fdd --- /dev/null +++ b/src/content-indexer/types/specs.ts @@ -0,0 +1,14 @@ +import type { OpenrpcDocument, ReferenceObject } from "@open-rpc/meta-schema"; +import type { OpenAPIV3 } from "openapi-types"; + +// Remove all $ref references since we only work with dereferenced specs +type NoRefs = T extends ReferenceObject | { $ref: string } + ? never + : T extends object + ? { [K in keyof T]: NoRefs } + : T; + +export type OpenRpcSpec = NoRefs; +export type OpenApiSpec = NoRefs; + +export type SpecType = "openrpc" | "openapi"; diff --git a/src/content-indexer/uploaders/__tests__/algolia.test.ts b/src/content-indexer/uploaders/__tests__/algolia.test.ts new file mode 100644 index 000000000..9d9f45ce4 --- /dev/null +++ b/src/content-indexer/uploaders/__tests__/algolia.test.ts @@ -0,0 +1,49 @@ +import { describe, expect, test, vi } from "vitest"; + +import type { AlgoliaRecord } from "@/content-indexer/types/algolia.ts"; + +import { uploadToAlgolia } from "../algolia.ts"; + +describe("uploadToAlgolia", () => { + test("should skip if no ALGOLIA_APP_ID", async () => { + const originalAppId = process.env.ALGOLIA_APP_ID; + const originalKey = process.env.ALGOLIA_ADMIN_API_KEY; + + delete process.env.ALGOLIA_APP_ID; + process.env.ALGOLIA_ADMIN_API_KEY = "test-key"; + + const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + const records: AlgoliaRecord[] = []; + + await uploadToAlgolia(records, { indexerType: "main", branchId: "main" }); + + expect(consoleSpy).toHaveBeenCalledWith( + expect.stringContaining("Algolia credentials not found"), + ); + + consoleSpy.mockRestore(); + process.env.ALGOLIA_APP_ID = originalAppId; + process.env.ALGOLIA_ADMIN_API_KEY = originalKey; + }); + + test("should skip if no ALGOLIA_ADMIN_API_KEY", async () => { + const originalAppId = process.env.ALGOLIA_APP_ID; + const originalKey = process.env.ALGOLIA_ADMIN_API_KEY; + + process.env.ALGOLIA_APP_ID = "test-app-id"; + delete process.env.ALGOLIA_ADMIN_API_KEY; + + const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + const records: AlgoliaRecord[] = []; + + await uploadToAlgolia(records, { indexerType: "main", branchId: "main" }); + + expect(consoleSpy).toHaveBeenCalledWith( + expect.stringContaining("Algolia credentials not found"), + ); + + consoleSpy.mockRestore(); + process.env.ALGOLIA_APP_ID = originalAppId; + process.env.ALGOLIA_ADMIN_API_KEY = originalKey; + }); +}); diff --git a/src/content-indexer/uploaders/__tests__/redis.test.ts b/src/content-indexer/uploaders/__tests__/redis.test.ts new file mode 100644 index 000000000..bdc745a0e --- /dev/null +++ b/src/content-indexer/uploaders/__tests__/redis.test.ts @@ -0,0 +1,171 @@ +import { beforeEach, describe, expect, test, vi } from "vitest"; + +import type { NavigationTreesByTab } from "@/content-indexer/types/navigation.ts"; +import type { PathIndex } from "@/content-indexer/types/pathIndex.ts"; + +import { storeToRedis } from "../redis.ts"; + +// Mock Redis +const mockSet = vi.fn().mockResolvedValue("OK"); +const mockGet = vi.fn(); + +vi.mock("@/content-indexer/utils/redis", () => ({ + getRedis: vi.fn(() => ({ + set: mockSet, + get: mockGet, + })), +})); + +describe("storeToRedis", () => { + beforeEach(() => { + mockSet.mockClear(); + }); + + test("should store path index to Redis without TTL for main branch", async () => { + const pathIndex: PathIndex = { + "guides/quickstart": { + type: "mdx", + filePath: "fern/guides/quickstart.mdx", + source: "docs-yml", + tab: "guides", + }, + }; + + await storeToRedis(pathIndex, undefined, { + branchId: "main", + indexerType: "main", + }); + + expect(mockSet).toHaveBeenCalledWith( + "main/path-index:main", + JSON.stringify(pathIndex, null, 2), + {}, // No TTL for main branch + ); + }); + + test("should store path index to Redis with 30-day TTL for preview branches", async () => { + const pathIndex: PathIndex = { + "guides/quickstart": { + type: "mdx", + filePath: "fern/guides/quickstart.mdx", + source: "docs-yml", + tab: "guides", + }, + }; + + await storeToRedis(pathIndex, undefined, { + branchId: "feature-abc", + indexerType: "main", + }); + + expect(mockSet).toHaveBeenCalledWith( + "feature-abc/path-index:main", + JSON.stringify(pathIndex, null, 2), + { ex: 2592000 }, // 30 days in seconds + ); + }); + + test("should store navigation trees to Redis without TTL for main branch", async () => { + const navigationTrees: NavigationTreesByTab = { + guides: [ + { + title: "Quickstart", + path: "/guides/quickstart", + type: "page", + }, + ], + }; + + await storeToRedis({}, navigationTrees, { + branchId: "main", + indexerType: "main", + }); + + expect(mockSet).toHaveBeenCalledWith( + "main/nav-tree:guides", + JSON.stringify(navigationTrees.guides, null, 2), + {}, // No TTL for main branch + ); + }); + + test("should store multiple navigation trees with correct TTL", async () => { + const navigationTrees: NavigationTreesByTab = { + guides: [ + { + title: "Guide1", + path: "/guides/guide1", + type: "page", + }, + ], + reference: [ + { + title: "Ref1", + path: "/reference/ref1", + type: "page", + }, + ], + }; + + await storeToRedis({}, navigationTrees, { + branchId: "main", + indexerType: "main", + }); + + expect(mockSet).toHaveBeenCalledWith( + "main/nav-tree:guides", + JSON.stringify(navigationTrees.guides, null, 2), + {}, // No TTL for main branch + ); + expect(mockSet).toHaveBeenCalledWith( + "main/nav-tree:reference", + JSON.stringify(navigationTrees.reference, null, 2), + {}, // No TTL for main branch + ); + }); + + test("should use sdk suffix for SDK indexer", async () => { + const pathIndex: PathIndex = { + "wallets/metamask": { + type: "mdx", + filePath: "wallets/metamask.mdx", + source: "docs-yml", + tab: "wallets", + }, + }; + + await storeToRedis(pathIndex, undefined, { + branchId: "main", + indexerType: "sdk", + }); + + expect(mockSet).toHaveBeenCalledWith( + "main/path-index:sdk", + JSON.stringify(pathIndex, null, 2), + {}, // No TTL for main branch + ); + }); + + test("should store all data in parallel", async () => { + const pathIndex: PathIndex = { + "guides/quickstart": { + type: "mdx", + filePath: "file.mdx", + source: "docs-yml", + tab: "guides", + }, + }; + + const navigationTrees: NavigationTreesByTab = { + guides: [{ title: "Guide", path: "/guides", type: "page" }], + reference: [{ title: "Ref", path: "/reference", type: "page" }], + }; + + await storeToRedis(pathIndex, navigationTrees, { + branchId: "main", + indexerType: "main", + }); + + // Should have called set 3 times (1 pathIndex + 2 nav trees) + expect(mockSet).toHaveBeenCalledTimes(3); + }); +}); diff --git a/src/content-indexer/uploaders/algolia.ts b/src/content-indexer/uploaders/algolia.ts new file mode 100644 index 000000000..91c47ade4 --- /dev/null +++ b/src/content-indexer/uploaders/algolia.ts @@ -0,0 +1,123 @@ +import { algoliasearch } from "algoliasearch"; + +import type { AlgoliaRecord } from "@/content-indexer/types/algolia.ts"; +import { truncateRecord } from "@/content-indexer/utils/truncate-record.ts"; + +const ALGOLIA_INDEX_NAME_BASE = "alchemy_docs"; + +/** + * Builds an Algolia index name with branch and type scoping. + * Pattern: {branchId}_{baseName}[_{indexerType}] + * + * Examples: + * - main_alchemy_docs (main branch, main content) + * - main_alchemy_docs_sdk (main branch, SDK content) + * - abc_alchemy_docs (branch-abc, main content) + * - abc_alchemy_docs_sdk (branch-abc, SDK content) + */ +const buildIndexName = ( + base: string, + indexerType: "main" | "sdk" | "changelog", + branchId: string, +): string => { + const parts = [branchId, base]; + + // Add type suffix (except for main content) + if (indexerType !== "main") { + parts.push(indexerType); + } + + return parts.join("_"); +}; + +/** + * Uploads records to Algolia using atomic index swap for zero-downtime updates. + * + * Process: + * 1. Upload all records to a temporary index + * 2. Copy settings/synonyms from production index (if exists) + * 3. Atomically swap temp index to production + * + * This ensures users never see empty search results during updates. + * + * @param records - Algolia records to upload + * @param options - Configuration options + * @param options.indexerType - Type of indexer ("main", "sdk", or "changelog") + * @param options.branchId - Branch identifier for index naming (e.g., "main", "branch-abc") + */ +export const uploadToAlgolia = async ( + records: AlgoliaRecord[], + options: { + indexerType: "main" | "sdk" | "changelog"; + branchId: string; + }, +): Promise => { + const appId = process.env.ALGOLIA_APP_ID; + const adminKey = process.env.ALGOLIA_ADMIN_API_KEY; + + if (!appId || !adminKey) { + console.warn("⚠️ Algolia credentials not found. Skipping Algolia upload."); + console.warn( + " Set ALGOLIA_APP_ID and ALGOLIA_ADMIN_API_KEY to enable search indexing.", + ); + return; + } + + const targetIndexName = buildIndexName( + ALGOLIA_INDEX_NAME_BASE, + options.indexerType, + options.branchId, + ); + + const client = algoliasearch(appId, adminKey); + const tempIndexName = `${targetIndexName}_temp`; + + console.info( + `📤 Uploading ${records.length} records to Algolia (${targetIndexName})...`, + ); + + // Truncate records to fit Algolia's 100KB limit + const truncatedRecords = records.map(truncateRecord); + + try { + // 1. Upload all records to temporary index + await client.saveObjects({ + indexName: tempIndexName, + objects: truncatedRecords as unknown as Array>, + }); + + console.info(` ✓ Uploaded ${records.length} records to ${tempIndexName}`); + + // 2. Copy settings/synonyms from production index (if it exists) + try { + await client.operationIndex({ + indexName: targetIndexName, + operationIndexParams: { + operation: "copy", + destination: tempIndexName, + scope: ["settings", "synonyms", "rules"], + }, + }); + console.info(" ✓ Copied settings from production index"); + } catch (_error) { + console.info( + " ℹ️ No existing production index found (might be first run)", + ); + } + + // 3. Atomic swap: move temp index to production + console.info(` 🔄 Swapping ${tempIndexName} → ${targetIndexName}...`); + await client.operationIndex({ + indexName: tempIndexName, + operationIndexParams: { + operation: "move", + destination: targetIndexName, + }, + }); + + console.info(`✅ Successfully updated Algolia index: ${targetIndexName}`); + } catch (error) { + console.error("❌ Failed to upload to Algolia:", error); + throw error; + } +}; diff --git a/src/content-indexer/uploaders/redis.ts b/src/content-indexer/uploaders/redis.ts new file mode 100644 index 000000000..88c8584b9 --- /dev/null +++ b/src/content-indexer/uploaders/redis.ts @@ -0,0 +1,106 @@ +import type { SetCommandOptions } from "@upstash/redis"; + +import type { + NavigationTree, + NavigationTreesByTab, +} from "@/content-indexer/types/navigation.js"; +import type { PathIndex } from "@/content-indexer/types/pathIndex.ts"; +import { mergeWalletsNavTree } from "@/content-indexer/utils/nav-tree-merge.ts"; +import { getRedis } from "@/content-indexer/utils/redis.ts"; + +const stringify = (data: unknown) => JSON.stringify(data, null, 2); + +// Helper to count nav items recursively +const countItems = (items: NavigationTree): number => { + return items.reduce((sum, item) => { + const childCount = + item.type === "section" || item.type === "api-section" + ? countItems(item.children) + : 0; + return sum + 1 + childCount; + }, 0); +}; + +const PREVIEW_TTL_SECONDS = 30 * 24 * 60 * 60; // 30 days + +/** + * Stores path index and navigation trees to Redis with branch scoping. + * + * @param pathIndex - The path index to store + * @param navigationTrees - Navigation trees (optional for SDK/changelog indexers) + * @param options - Configuration options + * @param options.branchId - Branch identifier for Redis keys (e.g., "main", "branch-abc123") + * @param options.indexerType - Type of indexer ("main", "sdk", or "changelog") + */ +export const storeToRedis = async ( + pathIndex: PathIndex, + navigationTrees: NavigationTreesByTab | undefined, + options: { + branchId: string; + indexerType: "main" | "sdk" | "changelog"; + }, +): Promise => { + const redis = getRedis(); + + // Determine TTL: no expiration for main branch, 30 days for preview branches + const isMainBranch = options.branchId === "main"; + const setOptions: SetCommandOptions = isMainBranch + ? {} + : { ex: PREVIEW_TTL_SECONDS }; + const ttlInfo = isMainBranch ? "" : " (30-day TTL)"; + + // Store path index with branch scope + const pathIndexKey = `${options.branchId}/path-index:${options.indexerType}`; + const pathIndexPromise = redis + .set(pathIndexKey, stringify(pathIndex), setOptions) + .then(() => { + console.info( + `✅ Path index saved to Redis (${Object.keys(pathIndex).length} routes) -> ${pathIndexKey}${ttlInfo}`, + ); + }); + + // Handle navigation trees + let navTreePromises: Promise[] = []; + + if (options.indexerType === "sdk" && navigationTrees?.wallets) { + // SDK indexer: merge SDK section into existing wallets nav tree + const navTreeKey = `${options.branchId}/nav-tree:wallets`; + const existingTree = await redis.get(navTreeKey); + + const mergedTree = mergeWalletsNavTree( + navigationTrees.wallets, + existingTree, + "sdk", + ); + + navTreePromises = [ + redis.set(navTreeKey, stringify(mergedTree), setOptions).then(() => { + console.info( + `✅ Updated wallets nav tree with SDK refs (${countItems(mergedTree)} total items) -> ${navTreeKey}${ttlInfo}`, + ); + }), + ]; + } else if (navigationTrees) { + // Main indexer: store all navigation trees + navTreePromises = Object.entries(navigationTrees).map( + async ([tab, navTree]) => { + const redisKey = `${options.branchId}/nav-tree:${tab}`; + let finalTree = navTree; + + // Main indexer: preserve SDK references in wallets tab + if (tab === "wallets" && options.indexerType === "main") { + const existingTree = await redis.get(redisKey); + finalTree = mergeWalletsNavTree(navTree, existingTree, "main"); + } + + const itemCount = countItems(finalTree); + await redis.set(redisKey, stringify(finalTree), setOptions); + console.info( + `✅ Navigation tree for '${tab}' saved to Redis (${itemCount} items) -> ${redisKey}${ttlInfo}`, + ); + }, + ); + } + + await Promise.all([pathIndexPromise, ...navTreePromises]); +}; diff --git a/src/content-indexer/utils/__tests__/navigation-helpers.test.ts b/src/content-indexer/utils/__tests__/navigation-helpers.test.ts new file mode 100644 index 000000000..04f58f3b5 --- /dev/null +++ b/src/content-indexer/utils/__tests__/navigation-helpers.test.ts @@ -0,0 +1,33 @@ +import { describe, expect, test } from "vitest"; + +import { createBreadcrumbNavItem } from "../navigation-helpers.ts"; + +describe("navigation-helpers", () => { + describe("createBreadcrumbNavItem", () => { + test("should create api-section breadcrumb", () => { + const result = createBreadcrumbNavItem("NFT API", "api-section"); + + expect(result).toEqual({ + title: "NFT API", + type: "api-section", + children: [], + }); + }); + + test("should always have empty children array", () => { + const result = createBreadcrumbNavItem("Ethereum API", "api-section"); + + if (result.type === "section" || result.type === "api-section") { + expect(result.children).toEqual([]); + expect(result.children).toHaveLength(0); + } + }); + + test("should preserve title exactly", () => { + const title = "Complex API Name with Spaces & Special Chars!"; + const result = createBreadcrumbNavItem(title, "api-section"); + + expect(result.title).toBe(title); + }); + }); +}); diff --git a/src/content-indexer/utils/__tests__/normalization.test.ts b/src/content-indexer/utils/__tests__/normalization.test.ts new file mode 100644 index 000000000..24f0c516d --- /dev/null +++ b/src/content-indexer/utils/__tests__/normalization.test.ts @@ -0,0 +1,122 @@ +import { describe, expect, test } from "vitest"; + +import { + normalizeFilePath, + normalizeSlug, +} from "@/content-indexer/utils/normalization.js"; +import { repoConfigFactory } from "@/content-indexer/utils/test-factories.ts"; + +describe("normalization utils", () => { + describe("normalizeSlug", () => { + test("should return undefined for undefined input", () => { + expect(normalizeSlug(undefined)).toBeUndefined(); + }); + + test("should return undefined for empty string", () => { + expect(normalizeSlug("")).toBeUndefined(); + }); + + test("should remove docs/ prefix", () => { + expect(normalizeSlug("docs/guides/quickstart")).toBe("guides/quickstart"); + }); + + test("should handle slug without docs/ prefix", () => { + expect(normalizeSlug("guides/quickstart")).toBe("guides/quickstart"); + }); + + test("should only remove leading docs/ prefix", () => { + expect(normalizeSlug("docs/reference/docs/api")).toBe( + "reference/docs/api", + ); + }); + + test("should handle docs/ as entire slug", () => { + expect(normalizeSlug("docs/")).toBe(""); + }); + + test("should preserve internal slashes", () => { + expect(normalizeSlug("docs/guides/getting-started/quickstart")).toBe( + "guides/getting-started/quickstart", + ); + }); + }); + + describe("normalizeFilePath", () => { + test("should remove stripPathPrefix", () => { + const result = normalizeFilePath( + "fern/guides/quickstart.mdx", + repoConfigFactory({ + stripPathPrefix: "fern/", + docsPrefix: "docs/fern/", + }), + ); + expect(result).toBe("guides/quickstart.mdx"); + }); + + test("should handle path without matching prefix", () => { + const result = normalizeFilePath( + "guides/quickstart.mdx", + repoConfigFactory({ + stripPathPrefix: "fern/", + docsPrefix: "docs/fern/", + }), + ); + expect(result).toBe("guides/quickstart.mdx"); + }); + + test("should handle empty stripPathPrefix", () => { + const result = normalizeFilePath( + "guides/quickstart.mdx", + repoConfigFactory({ + stripPathPrefix: "", + docsPrefix: "docs/", + }), + ); + expect(result).toBe("guides/quickstart.mdx"); + }); + + test("should handle undefined stripPathPrefix", () => { + const result = normalizeFilePath( + "guides/quickstart.mdx", + repoConfigFactory({ + docsPrefix: "docs/", + }), + ); + expect(result).toBe("guides/quickstart.mdx"); + }); + + test("should handle complex path", () => { + const result = normalizeFilePath( + "fern/docs/reference/ethereum/methods/eth_getBalance.mdx", + repoConfigFactory({ + stripPathPrefix: "fern/docs/", + docsPrefix: "docs/fern/docs/", + }), + ); + expect(result).toBe("reference/ethereum/methods/eth_getBalance.mdx"); + }); + + test("should handle path with no prefix", () => { + const result = normalizeFilePath( + "api/spec.json", + repoConfigFactory({ + stripPathPrefix: "", + docsPrefix: "", + }), + ); + expect(result).toBe("api/spec.json"); + }); + + test("should strip multiple occurrences of prefix", () => { + const result = normalizeFilePath( + "fern/fern/guides/quickstart.mdx", + repoConfigFactory({ + stripPathPrefix: "fern/", + docsPrefix: "docs/", + }), + ); + // replace() only replaces first occurrence by default + expect(result).toBe("fern/guides/quickstart.mdx"); + }); + }); +}); diff --git a/src/content-indexer/utils/__tests__/openapi.test.ts b/src/content-indexer/utils/__tests__/openapi.test.ts new file mode 100644 index 000000000..372cdcfac --- /dev/null +++ b/src/content-indexer/utils/__tests__/openapi.test.ts @@ -0,0 +1,284 @@ +import { describe, expect, test } from "vitest"; + +import { PathBuilder } from "@/content-indexer/core/path-builder.ts"; + +import { + buildOperationPath, + extractOpenApiOperations, + getOperation, + getOperationDescription, + getOperationTitle, +} from "../openapi.js"; + +describe("openapi utils", () => { + describe("extractOpenApiOperations", () => { + test("should extract operations from paths", () => { + const paths = { + "/users": { + get: { + operationId: "getUsers", + tags: ["users"], + }, + post: { + operationId: "createUser", + tags: ["users"], + }, + }, + }; + + const operations = extractOpenApiOperations(paths); + expect(operations).toHaveLength(2); + expect(operations[0].operationId).toBe("getUsers"); + expect(operations[0].method).toBe("GET"); + expect(operations[1].operationId).toBe("createUser"); + expect(operations[1].method).toBe("POST"); + }); + + test("should handle operation without explicit operationId", () => { + const paths = { + "/users": { + get: { + summary: "Get all users", + }, + }, + }; + + const operations = extractOpenApiOperations(paths); + expect(operations).toHaveLength(1); + expect(operations[0].operationId).toBe("Get all users"); + }); + + test("should generate operationId from method and path if missing", () => { + const paths = { + "/users/{id}": { + get: {}, + }, + }; + + const operations = extractOpenApiOperations(paths); + expect(operations).toHaveLength(1); + expect(operations[0].operationId).toBe("get_/users/{id}"); + }); + + test("should extract first tag from tags array", () => { + const paths = { + "/users": { + get: { + operationId: "getUsers", + tags: ["users", "admin", "v2"], + }, + }, + }; + + const operations = extractOpenApiOperations(paths); + expect(operations[0].tag).toBe("users"); + }); + + test("should handle operation without tags", () => { + const paths = { + "/users": { + get: { + operationId: "getUsers", + }, + }, + }; + + const operations = extractOpenApiOperations(paths); + expect(operations[0].tag).toBeUndefined(); + }); + + test("should skip non-HTTP method properties", () => { + const paths = { + "/users": { + get: { + operationId: "getUsers", + }, + parameters: [], // Not an HTTP method + description: "Users endpoint", // Not an HTTP method + }, + }; + + const operations = extractOpenApiOperations(paths); + expect(operations).toHaveLength(1); + }); + + test("should handle multiple paths", () => { + const paths = { + "/users": { + get: { operationId: "getUsers" }, + }, + "/posts": { + get: { operationId: "getPosts" }, + post: { operationId: "createPost" }, + }, + }; + + const operations = extractOpenApiOperations(paths); + expect(operations).toHaveLength(3); + }); + + test("should handle empty paths object", () => { + const operations = extractOpenApiOperations({}); + expect(operations).toEqual([]); + }); + }); + + describe("getOperationTitle", () => { + test("should return summary if available", () => { + const spec = { + paths: { + "/users": { + get: { + operationId: "getUsers", + summary: "Get All Users", + }, + }, + }, + }; + + const operation = getOperation(spec, "/users", "get"); + const title = getOperationTitle(operation, "getUsers"); + expect(title).toBe("Get All Users"); + }); + + test("should fallback to operationId if no summary", () => { + const spec = { + paths: { + "/users": { + get: { + operationId: "getUsers", + }, + }, + }, + }; + + const operation = getOperation(spec, "/users", "get"); + const title = getOperationTitle(operation, "getUsers"); + expect(title).toBe("getUsers"); + }); + + test("should return operationId if path not found", () => { + const spec = { + paths: {}, + }; + + const operation = getOperation(spec, "/users", "get"); + const title = getOperationTitle(operation, "getUsers"); + expect(title).toBe("getUsers"); + }); + + test("should return operationId if operation not found in path", () => { + const spec = { + paths: { + "/users": { + post: { + operationId: "createUser", + summary: "Create User", + }, + }, + }, + }; + + const operation = getOperation(spec, "/users", "get"); + const title = getOperationTitle(operation, "getUsers"); + expect(title).toBe("getUsers"); + }); + }); + + describe("getOperationDescription", () => { + test("should return description if available", () => { + const spec = { + paths: { + "/users": { + get: { + description: "Retrieves all users from the system", + }, + }, + }, + }; + + const operation = getOperation(spec, "/users", "get"); + const description = getOperationDescription(operation); + expect(description).toBe("Retrieves all users from the system"); + }); + + test("should return empty string if path not found", () => { + const spec = { + paths: {}, + }; + + const operation = getOperation(spec, "/users", "get"); + const description = getOperationDescription(operation); + expect(description).toBe(""); + }); + + test("should return empty string if method not found", () => { + const spec = { + paths: { + "/users": { + post: { + description: "Create user", + }, + }, + }, + }; + + const operation = getOperation(spec, "/users", "get"); + const description = getOperationDescription(operation); + expect(description).toBe(""); + }); + + test("should return empty string if description not present", () => { + const spec = { + paths: { + "/users": { + get: { + operationId: "getUsers", + }, + }, + }, + }; + + const operation = getOperation(spec, "/users", "get"); + const description = getOperationDescription(operation); + expect(description).toBe(""); + }); + }); + + describe("buildOperationPath", () => { + test("should build path without tag", () => { + const builder = PathBuilder.init("reference/api"); + const path = buildOperationPath(builder, "getUsers", undefined); + + expect(path).toBe("reference/api/get-users"); + }); + + test("should build path with tag", () => { + const builder = PathBuilder.init("reference/api"); + const path = buildOperationPath(builder, "getUsers", "users"); + + expect(path).toBe("reference/api/users/get-users"); + }); + + test("should kebab-case operationId", () => { + const builder = PathBuilder.init("reference"); + const path = buildOperationPath(builder, "getUsersById", undefined); + + expect(path).toBe("reference/get-users-by-id"); + }); + + test("should kebab-case tag", () => { + const builder = PathBuilder.init("reference"); + const path = buildOperationPath(builder, "getUsers", "User Management"); + + expect(path).toBe("reference/user-management/get-users"); + }); + + test("should handle empty base path", () => { + const builder = PathBuilder.init(); + const path = buildOperationPath(builder, "getUsers", "users"); + + expect(path).toBe("users/get-users"); + }); + }); +}); diff --git a/src/content-indexer/utils/__tests__/openrpc.test.ts b/src/content-indexer/utils/__tests__/openrpc.test.ts new file mode 100644 index 000000000..51bcea332 --- /dev/null +++ b/src/content-indexer/utils/__tests__/openrpc.test.ts @@ -0,0 +1,71 @@ +import { describe, expect, test } from "vitest"; + +import type { OpenRpcSpec } from "@/content-indexer/types/specs.ts"; + +import { isValidOpenRpcSpec } from "../openrpc.ts"; + +describe("openrpc utils", () => { + describe("isValidOpenRpcSpec", () => { + test("should return true for valid OpenRPC spec", () => { + const spec: OpenRpcSpec = { + openrpc: "1.0.0", + info: { title: "API", version: "1.0.0" }, + methods: [ + { + name: "getAsset", + params: [], + result: { name: "result", schema: {} }, + }, + ], + }; + + expect(isValidOpenRpcSpec(spec)).toBe(true); + }); + + test("should return false for spec without methods", () => { + const spec = { + openrpc: "1.0.0", + info: { title: "API", version: "1.0.0" }, + }; + + expect(isValidOpenRpcSpec(spec)).toBe(false); + }); + + test("should return true for spec with empty methods array", () => { + const spec = { + openrpc: "1.0.0", + info: { title: "API", version: "1.0.0" }, + methods: [], + }; + + // Type guard only checks structure, not content validity + expect(isValidOpenRpcSpec(spec)).toBe(true); + }); + + test("should return false for spec with non-array methods", () => { + const spec = { + openrpc: "1.0.0", + info: { title: "API", version: "1.0.0" }, + methods: "invalid", + }; + + expect(isValidOpenRpcSpec(spec)).toBe(false); + }); + + test("should return false for undefined spec", () => { + expect(isValidOpenRpcSpec(undefined as unknown as OpenRpcSpec)).toBe( + false, + ); + }); + + test("should return false for null spec", () => { + expect(isValidOpenRpcSpec(null as unknown as OpenRpcSpec)).toBe(false); + }); + + test("should return false for non-object spec", () => { + expect(isValidOpenRpcSpec("string" as unknown as OpenRpcSpec)).toBe( + false, + ); + }); + }); +}); diff --git a/src/content-indexer/utils/__tests__/truncate-record.test.ts b/src/content-indexer/utils/__tests__/truncate-record.test.ts new file mode 100644 index 000000000..d21d243c3 --- /dev/null +++ b/src/content-indexer/utils/__tests__/truncate-record.test.ts @@ -0,0 +1,121 @@ +import { describe, expect, test, vi } from "vitest"; + +import type { AlgoliaRecord } from "@/content-indexer/types/algolia.ts"; + +import { truncateRecord } from "../truncate-record.ts"; + +describe("truncateRecord", () => { + test("should return record unchanged if under size limit", () => { + const record: AlgoliaRecord = { + objectID: "abc123", + path: "guides/quickstart", + pageType: "Guide", + title: "Quickstart", + content: "Short content", + breadcrumbs: ["Guides"], + }; + + const result = truncateRecord(record); + expect(result).toEqual(record); + expect(result.content).toBe("Short content"); + }); + + test("should truncate content for oversized record", () => { + // Create a record with content exceeding 100KB + const largeContent = "x".repeat(150_000); + const record: AlgoliaRecord = { + objectID: "abc123", + path: "guides/large", + pageType: "Guide", + title: "Large Page", + content: largeContent, + breadcrumbs: ["Guides"], + }; + + const result = truncateRecord(record); + expect(result.content).not.toBe(largeContent); + expect(result.content.length).toBeLessThan(largeContent.length); + expect(result.content).toMatch(/\.\.\.$/); // Ends with "..." + expect( + Buffer.byteLength(JSON.stringify(result), "utf8"), + ).toBeLessThanOrEqual(100_000); + }); + + test("should preserve all fields except content", () => { + const largeContent = "x".repeat(150_000); + const record: AlgoliaRecord = { + objectID: "abc123", + path: "reference/method", + pageType: "API Method", + title: "eth_getBalance", + content: largeContent, + breadcrumbs: ["API", "Ethereum"], + httpMethod: "POST", + }; + + const result = truncateRecord(record); + expect(result.objectID).toBe(record.objectID); + expect(result.path).toBe(record.path); + expect(result.pageType).toBe(record.pageType); + expect(result.title).toBe(record.title); + expect(result.breadcrumbs).toEqual(record.breadcrumbs); + expect(result.httpMethod).toBe(record.httpMethod); + }); + + test("should throw error if overhead is too large", () => { + const record: AlgoliaRecord = { + objectID: "abc123", + path: "guides/test", + pageType: "Guide", + title: "Test", + content: "Content", + breadcrumbs: Array(50_000).fill("B"), // Many breadcrumbs = huge overhead + }; + + expect(() => truncateRecord(record)).toThrow( + /Record overhead .* is too large/, + ); + }); + + test("should log warning for oversized record", () => { + const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + + const largeContent = "x".repeat(150_000); + const record: AlgoliaRecord = { + objectID: "abc123", + path: "guides/large", + pageType: "Guide", + title: "Large Page", + content: largeContent, + breadcrumbs: [], + }; + + truncateRecord(record); + + expect(warnSpy).toHaveBeenCalled(); + expect(warnSpy.mock.calls[0][0]).toContain("exceeds"); + expect(warnSpy.mock.calls[0][0]).toContain("Large Page"); + + warnSpy.mockRestore(); + }); + + test("should handle record at exactly the size limit", () => { + // Create content to make record exactly 100KB + const targetSize = 100_000; + const overhead = 200; // Approximate overhead + const content = "x".repeat(targetSize - overhead); + + const record: AlgoliaRecord = { + objectID: "abc", + path: "path", + pageType: "Guide", + title: "Title", + content, + breadcrumbs: [], + }; + + const result = truncateRecord(record); + const resultSize = Buffer.byteLength(JSON.stringify(result), "utf8"); + expect(resultSize).toBeLessThanOrEqual(100_000); + }); +}); diff --git a/src/content-indexer/utils/apiSpecs.ts b/src/content-indexer/utils/apiSpecs.ts new file mode 100644 index 000000000..bdaf662dd --- /dev/null +++ b/src/content-indexer/utils/apiSpecs.ts @@ -0,0 +1,136 @@ +// Utilities for fetching and processing OpenRPC/OpenAPI specifications +import type { + OpenApiSpec, + OpenRpcSpec, + SpecType, +} from "@/content-indexer/types/specs.js"; + +import { fetchWithRetries } from "./fetchWithRetries.ts"; + +interface MetadataJson { + files: string[]; +} + +const METADATA_URL = "https://dev-docs.alchemy.com/metadata.json"; + +// Map api-name values that don't match their filename in metadata.json +const API_NAME_TO_FILENAME: Record = { + avalanche: "avax", + arbitrum: "arb", + "polygon-zkevm": "polygonzkevm", +}; + +let cachedMetadata: MetadataJson | null = null; + +/** + * Fetches the metadata.json file which contains all available spec URLs. + */ +const getMetadata = async (): Promise => { + if (cachedMetadata) { + return cachedMetadata; + } + + const response = await fetchWithRetries(METADATA_URL); + + if (!response.ok) { + console.warn(`Failed to fetch metadata.json`); + return undefined; + } + + try { + const metadata = (await response.json()) as MetadataJson; + cachedMetadata = metadata; + return metadata; + } catch (error) { + console.warn(`Error parsing metadata.json:`, error); + return undefined; + } +}; + +/** + * Determines the spec type from the URL path. + * - /chains/ → openrpc + * - /alchemy/json-rpc/ → openrpc + * - /alchemy/rest/ → openapi + */ +const getSpecTypeFromUrl = (url: string): SpecType => { + if (url.includes("/rest/")) { + return "openapi"; + } + return "openrpc"; +}; + +/** + * Finds the spec URL and type for a given API name from metadata.json. + * The api-name should match the filename (e.g., "eth" → "eth.json"). + */ +export const getSpecInfo = async ( + apiName: string, +): Promise<{ specUrl: string; specType: SpecType } | undefined> => { + const metadata = await getMetadata(); + + if (!metadata) { + console.warn(`Could not fetch metadata.json`); + return undefined; + } + + // Map api-name to filename if there's an exception + const filename = API_NAME_TO_FILENAME[apiName] ?? apiName; + + // Look for a file that matches the filename + const specUrl = metadata.files.find((file) => + file.endsWith(`/${filename}.json`), + ); + + if (!specUrl) { + console.warn( + `Could not find spec for api-name: ${apiName} (filename: ${filename})`, + ); + return undefined; + } + + const specType = getSpecTypeFromUrl(specUrl); + + return { specUrl, specType }; +}; + +/** + * Fetches spec info and the spec itself for a given API name. + */ +export const fetchApiSpec = async ( + apiName: string, +): Promise< + | { specType: "openrpc"; spec: OpenRpcSpec; specUrl: string } + | { specType: "openapi"; spec: OpenApiSpec; specUrl: string } + | undefined +> => { + const specInfo = await getSpecInfo(apiName); + + if (!specInfo) { + console.warn(`Could not determine spec info for api: ${apiName}`); + return undefined; + } + + const { specUrl, specType } = specInfo; + + // Fetch the spec directly + const response = await fetchWithRetries(specUrl); + + if (!response.ok) { + return undefined; + } + + try { + const spec = await response.json(); + + // Return with proper typing based on specType + if (specType === "openrpc") { + return { specType: "openrpc", spec: spec as OpenRpcSpec, specUrl }; + } else { + return { specType: "openapi", spec: spec as OpenApiSpec, specUrl }; + } + } catch (error) { + console.warn(`Error parsing spec JSON for ${apiName}:`, error); + return undefined; + } +}; diff --git a/src/content-indexer/utils/fetchWithRetries.ts b/src/content-indexer/utils/fetchWithRetries.ts new file mode 100644 index 000000000..d47f46e54 --- /dev/null +++ b/src/content-indexer/utils/fetchWithRetries.ts @@ -0,0 +1,35 @@ +type FetchOptions = Parameters[1]; + +const delay = (ms: number) => new Promise((res) => setTimeout(res, ms)); + +export const fetchWithRetries = async ( + url: string, + options: FetchOptions = {}, + retries = 3, +): Promise => { + let errorMessage = ""; + let response = new Response(null, { status: 500 }); + + for (let attempt = 0; attempt < retries; attempt++) { + try { + response = await fetch(url, options); + + if (response.status === 404) { + // no need to retry 404s + return response; + } + + if (!response.ok) { + errorMessage = `HTTP error! Status: ${response.statusText}`; + throw new Error(errorMessage); + } + + return response; + } catch (error) { + console.error(error); + await delay(Math.pow(2, attempt) * 300); // Exponential backoff + } + } + + return response; +}; diff --git a/src/content-indexer/utils/filesystem.ts b/src/content-indexer/utils/filesystem.ts new file mode 100644 index 000000000..054841a6e --- /dev/null +++ b/src/content-indexer/utils/filesystem.ts @@ -0,0 +1,71 @@ +import { promises as fs } from "fs"; +import matter from "gray-matter"; +import yaml from "js-yaml"; +import path from "path"; + +import type { DocsYml } from "@/content-indexer/types/docsYaml.ts"; + +/** + * Reads a file from the local filesystem + */ +export const readLocalFile = async ( + filePath: string, +): Promise => { + try { + const content = await fs.readFile(filePath, "utf-8"); + return content; + } catch (error) { + console.warn(`Failed to read file: ${filePath}`, error); + return null; + } +}; + +/** + * Reads and parses a local docs.yml file + */ +export const readLocalDocsYml = async ( + baseDir: string, +): Promise => { + try { + const docsYmlPath = path.join(baseDir, "docs.yml"); + const content = await readLocalFile(docsYmlPath); + + if (!content) { + throw new Error(`Failed to read docs.yml from ${docsYmlPath}`); + } + + const docsYml = yaml.load(content) as DocsYml; + return docsYml; + } catch (error) { + console.error(`Error reading/parsing docs.yml from ${baseDir}:`, error); + return null; + } +}; + +/** + * Reads a local MDX file and parses its frontmatter + */ +export const readLocalMdxFile = async ( + filePath: string, +): Promise<{ + frontmatter: Record; + content: string; +} | null> => { + try { + const fileContent = await readLocalFile(filePath); + + if (!fileContent) { + return null; + } + + const { data, content } = matter(fileContent); + + return { + frontmatter: data, + content, + }; + } catch (error) { + console.warn(`Failed to parse MDX file: ${filePath}`, error); + return null; + } +}; diff --git a/src/content-indexer/utils/github.ts b/src/content-indexer/utils/github.ts new file mode 100644 index 000000000..cc75ce5d7 --- /dev/null +++ b/src/content-indexer/utils/github.ts @@ -0,0 +1,165 @@ +import { Octokit, RequestError } from "octokit"; + +type GetContentResponse = Awaited< + ReturnType["rest"]["repos"]["getContent"]> +>; +type GetContentData = GetContentResponse["data"]; + +type ContentDirectoryItem = Extract>[number]; + +// ============================================================================ +// Repository Configuration +// ============================================================================ + +export interface RepoConfig { + owner: string; + repo: string; + branch: string; + docsPrefix: string; // "fern" or "docs" - folder where MDX files are stored + stripPathPrefix?: string; // Optional prefix to strip from paths in docs.yml (e.g., "wallets/") +} + +export const DOCS_REPO: RepoConfig = { + owner: "alchemyplatform", + repo: "docs", + branch: "main", + docsPrefix: "fern", +}; + +export const WALLET_REPO: RepoConfig = { + owner: "alchemyplatform", + repo: "aa-sdk", + branch: "main", + docsPrefix: "docs", + stripPathPrefix: "wallets/", // aa-sdk docs.yml uses "wallets/pages/..." but actual files are at "docs/pages/..." +}; + +const octokit = new Octokit({ + auth: process.env.GH_TOKEN, +}); + +function isRequestError(error: unknown): error is RequestError { + return error instanceof RequestError; +} + +/** + * Fetch a single file's text content from GitHub + */ +export async function fetchFileFromGitHub( + filePath: string, + repoConfig: RepoConfig = DOCS_REPO, +): Promise { + try { + const { data } = await octokit.rest.repos.getContent({ + owner: repoConfig.owner, + repo: repoConfig.repo, + path: filePath, + ref: repoConfig.branch, + mediaType: { + format: "raw", + }, + }); + + // When using raw format, data is a string + return data as unknown as string; + } catch (error: unknown) { + if (isRequestError(error) && error.status === 404) { + return null; // File doesn't exist + } + console.error(`Error fetching ${filePath} from ${repoConfig.repo}:`, error); + return null; + } +} + +/** + * Fetch directory contents from GitHub (non-recursive) + */ +export async function fetchGitHubDirectory( + dirPath: string, + repoConfig: RepoConfig = DOCS_REPO, +): Promise { + try { + const { data } = await octokit.rest.repos.getContent({ + owner: repoConfig.owner, + repo: repoConfig.repo, + path: dirPath, + ref: repoConfig.branch, + }); + + // GitHub API returns array for directories, object for files + if (!Array.isArray(data)) { + throw new Error(`Expected directory but got file: ${dirPath}`); + } + + return data; + } catch (error) { + console.error( + `Error fetching directory ${dirPath} from ${repoConfig.repo}:`, + error, + ); + throw error; + } +} + +/** + * Check if a file exists on GitHub + */ +export async function fileExistsOnGitHub( + filePath: string, + repoConfig: RepoConfig = DOCS_REPO, +): Promise { + try { + await octokit.rest.repos.getContent({ + owner: repoConfig.owner, + repo: repoConfig.repo, + path: filePath, + ref: repoConfig.branch, + }); + return true; + } catch (error: unknown) { + if (isRequestError(error) && error.status === 404) { + return false; + } + // For other errors, log but return false to be safe + console.error(`Error checking if ${filePath} exists:`, error); + return false; + } +} + +/** + * Get file metadata without downloading content + */ +export async function getGitHubFileMetadata( + filePath: string, + repoConfig: RepoConfig = DOCS_REPO, +): Promise<{ sha: string; size: number } | null> { + try { + const { data } = await octokit.rest.repos.getContent({ + owner: repoConfig.owner, + repo: repoConfig.repo, + path: filePath, + ref: repoConfig.branch, + }); + + // Ensure we got a file, not a directory + if (Array.isArray(data)) { + return null; + } + + // Type guard for file object + if ("sha" in data && "size" in data) { + return { + sha: data.sha, + size: data.size, + }; + } + + return null; + } catch (error: unknown) { + if (isRequestError(error) && error.status === 404) { + return null; + } + console.error(`Error fetching metadata for ${filePath}:`, error); + return null; + } +} diff --git a/src/content-indexer/utils/nav-tree-merge.ts b/src/content-indexer/utils/nav-tree-merge.ts new file mode 100644 index 000000000..b7f5da2a6 --- /dev/null +++ b/src/content-indexer/utils/nav-tree-merge.ts @@ -0,0 +1,93 @@ +import type { + NavItem, + NavigationTree, +} from "@/content-indexer/types/navigation.js"; + +/** + * Checks if a navigation item is an SDK reference section. + * SDK sections are identified by title containing "sdk reference" (case-insensitive) + * WARNING: This is an assumption and will break if the title for this section is changed + */ +const isSDKReferenceSection = (item: NavItem): boolean => { + if (item.type === "section" || item.type === "api-section") { + return item.title.toLowerCase().includes("sdk reference"); + } + return false; +}; + +/** + * Identifies SDK reference sections vs manual sections in a navigation tree. + * SDK sections are identified by title containing "sdk reference" (case-insensitive). + * + * @param tree - The navigation tree to separate + * @returns Object with sdk and manual sections + */ +export const separateSDKAndManualSections = ( + tree: NavigationTree, +): { sdk: NavigationTree; manual: NavigationTree } => { + return tree.reduce<{ sdk: NavigationTree; manual: NavigationTree }>( + (acc, item) => { + if (isSDKReferenceSection(item)) { + acc.sdk.push(item); + } else { + acc.manual.push(item); + } + return acc; + }, + { sdk: [], manual: [] }, + ); +}; + +/** + * Merges navigation trees for the wallets tab, handling SDK references and manual sections. + * SDK References are always inserted second-to-last (before Resources section). + * + * @param newTree - New sections from current indexer run + * @param existingTree - Existing wallets navigation tree from Redis (or null if none) + * @param indexerType - Type of indexer: "sdk" means newTree is SDK refs, "main" means newTree is manual content + * @returns Merged tree with manual sections + SDK sections at second-to-last position + */ +export const mergeWalletsNavTree = ( + newTree: NavigationTree, + existingTree: NavigationTree | null, + indexerType: "main" | "sdk", +): NavigationTree => { + if (!existingTree) { + if (indexerType === "sdk") { + console.warn("⚠️ No existing wallets nav tree found, creating new one"); + } + return newTree; + } + + console.info("📖 Read existing wallets nav tree from Redis"); + + // Separate SDK and manual sections from existing tree + const { sdk: existingSDK, manual: existingManual } = + separateSDKAndManualSections(existingTree); + + // Determine which sections are new and which to preserve + const manualSections = indexerType === "main" ? newTree : existingManual; + const sdkSections = indexerType === "sdk" ? newTree : existingSDK; + + // Log preservation info + if (indexerType === "main" && sdkSections.length > 0) { + console.info( + `📖 Preserved ${sdkSections.length} SDK reference section(s) in wallets nav tree`, + ); + } + + // Handle edge cases + if (sdkSections.length === 0) { + return manualSections; + } + if (manualSections.length === 0) { + return sdkSections; + } + + // Insert SDK sections at second-to-last position (before Resources) + return [ + ...manualSections.slice(0, -1), // All manual sections except last + ...sdkSections, // SDK sections + manualSections[manualSections.length - 1], // Last section (Resources) + ]; +}; diff --git a/src/content-indexer/utils/navigation-helpers.ts b/src/content-indexer/utils/navigation-helpers.ts new file mode 100644 index 000000000..590cfeb99 --- /dev/null +++ b/src/content-indexer/utils/navigation-helpers.ts @@ -0,0 +1,14 @@ +import type { NavItem } from "@/content-indexer/types/navigation.ts"; + +/** + * Creates breadcrumb-safe navigation item (without populated children). + * Prevents circular references in breadcrumb trails by creating a shallow copy. + */ +export const createBreadcrumbNavItem = ( + title: string, + type: "api-section", +): NavItem => ({ + title, + type, + children: [], +}); diff --git a/src/content-indexer/utils/normalization.ts b/src/content-indexer/utils/normalization.ts new file mode 100644 index 000000000..195116efa --- /dev/null +++ b/src/content-indexer/utils/normalization.ts @@ -0,0 +1,22 @@ +import type { RepoConfig } from "@/content-indexer/utils/github.ts"; + +/** + * Normalizes a frontmatter slug by removing the "docs/" prefix. + * This prefix is used in some legacy frontmatter from the main docs repo + * but should be stripped when generating URL paths. + */ +export const normalizeSlug = (slug: string | undefined): string | undefined => { + if (!slug) return undefined; + return slug.replace(/^docs\//, ""); +}; + +/** + * Normalizes a file path by stripping the repo's configured prefix. + * This ensures the stored filePath can be used directly with the repo's docsPrefix. + */ +export const normalizeFilePath = ( + filePath: string, + repo: RepoConfig, +): string => { + return filePath.replace(repo.stripPathPrefix || "", ""); +}; diff --git a/src/content-indexer/utils/openapi.ts b/src/content-indexer/utils/openapi.ts new file mode 100644 index 000000000..945ebfebc --- /dev/null +++ b/src/content-indexer/utils/openapi.ts @@ -0,0 +1,173 @@ +import { kebabCase } from "lodash-es"; +import type { OpenAPIV3 } from "openapi-types"; +import removeMd from "remove-markdown"; + +import { HTTP_METHODS } from "@/content-indexer/constants/http.ts"; +import type { PathBuilder } from "@/content-indexer/core/path-builder.ts"; + +export interface ExtractedOperation { + operationId: string; + path: string; + method: string; + tag?: string; +} + +/** + * Retrieves an operation object from a spec given a path and method. + * Returns undefined if the path or method doesn't exist. + */ +export const getOperation = ( + spec: { paths: Record }, + path: string, + method: string, +): OpenAPIV3.OperationObject | undefined => { + const pathItem = spec.paths[path]; + if (!pathItem || typeof pathItem !== "object") { + return undefined; + } + + const operation = (pathItem as Record)[method]; + if (!operation || typeof operation !== "object") { + return undefined; + } + + return operation as OpenAPIV3.OperationObject; +}; + +/** + * Extracts operationId from an OpenAPI operation object. + * Falls back to summary or generates from method + path if operationId is missing. + */ +const getOperationId = ( + operation: Record, + method: string, + path: string, +): string => { + if ("operationId" in operation && operation.operationId) { + return operation.operationId as string; + } + + if ("summary" in operation && operation.summary) { + return (operation.summary as string).replace(/^\//, ""); + } + + return `${method}_${path}`; +}; + +/** + * Extracts the title for an OpenAPI operation. + * Prefers the summary field, falls back to operationId. + */ +export const getOperationTitle = ( + operation: OpenAPIV3.OperationObject | undefined, + operationId: string, +): string => { + if (!operation) { + return operationId; + } + + return operation.summary || operationId; +}; + +/** + * Extracts all operations from an OpenAPI paths object. + * + * Iterates through all paths and HTTP methods, extracting metadata for each operation including: + * - operationId (with fallback logic via getOperationId) + * - path (the URL path from the spec) + * - method (the HTTP method, normalized to uppercase) + * - tag (the first tag from the operation's tags array, used for grouping) + */ +export const extractOpenApiOperations = ( + paths: Record, +): ExtractedOperation[] => { + return Object.entries(paths).flatMap(([path, pathItem]) => { + if (!pathItem || typeof pathItem !== "object") return []; + + return Object.entries(pathItem) + .filter( + ([method, operation]) => + (HTTP_METHODS as readonly string[]).includes(method) && + operation && + typeof operation === "object", + ) + .map(([method, operation]) => { + const op = operation as Record; + // Extract the first tag (Fern uses tags[0] for organization) + const tags = Array.isArray(op.tags) ? op.tags : []; + const tag = tags[0] as string | undefined; + + return { + operationId: getOperationId(op, method, path), + path, + method: method.toUpperCase(), + tag, + }; + }); + }); +}; + +/** + * Builds the final URL path for an OpenAPI operation. + * + * Constructs the path by: + * 1. Optionally adding a tag slug (for grouping operations by tag) + * 2. Adding the operation slug (kebab-cased operationId) + */ +export const buildOperationPath = ( + apiPathBuilder: PathBuilder, + operationId: string, + tag?: string, +): string => { + let pathBuilder = apiPathBuilder; + + // Add tag slug to path if operation has a tag + if (tag) { + const tagSlug = kebabCase(tag); + pathBuilder = apiPathBuilder.apply({ urlSlug: tagSlug }); + } + + // Add operation slug to path + const operationSlug = kebabCase(operationId); + pathBuilder = pathBuilder.apply({ urlSlug: operationSlug }); + + return pathBuilder.get(); +}; + +/** + * Extracts the description from an OpenAPI operation object. + * Falls back to summary if description is not available. + */ +export const getOperationDescription = ( + operation: OpenAPIV3.OperationObject | undefined, +): string => { + if (!operation) { + return ""; + } + + return operation.description + ? removeMd(operation.description) + : operation.summary || ""; +}; + +/** + * Extracts a brief summary for an OpenAPI operation to use in search tooltip + */ +export const getOperationSummary = ( + operation: OpenAPIV3.OperationObject | undefined, +): string | undefined => { + if (!operation) { + return undefined; + } + + if (operation.summary) { + return operation.summary; + } + + // If no summary but description exists, strip markdown and use it + if (operation.description) { + return removeMd(operation.description); + } + + return undefined; +}; diff --git a/src/content-indexer/utils/openrpc.ts b/src/content-indexer/utils/openrpc.ts new file mode 100644 index 000000000..89fc5a69c --- /dev/null +++ b/src/content-indexer/utils/openrpc.ts @@ -0,0 +1,13 @@ +import type { OpenRpcSpec } from "@/content-indexer/types/specs.ts"; + +/** + * Type guard to check if a spec is a valid OpenRPC spec with methods array. + */ +export const isValidOpenRpcSpec = (spec: unknown): spec is OpenRpcSpec => { + return ( + typeof spec === "object" && + spec !== null && + "methods" in spec && + Array.isArray((spec as { methods: unknown }).methods) + ); +}; diff --git a/src/content-indexer/utils/redis.ts b/src/content-indexer/utils/redis.ts new file mode 100644 index 000000000..529d35e3d --- /dev/null +++ b/src/content-indexer/utils/redis.ts @@ -0,0 +1,32 @@ +import { Redis } from "@upstash/redis"; + +/** + * Creates and returns an Upstash Redis client instance. + */ +const getRedisClient = (): Redis => { + const url = process.env.KV_REST_API_URL; + const token = process.env.KV_REST_API_TOKEN; + + if (!url || !token) { + throw new Error( + "Missing required environment variables: KV_REST_API_URL and/or KV_REST_API_TOKEN", + ); + } + + return new Redis({ + url, + token, + }); +}; + +/** + * Singleton instance of Redis client to reuse across requests + */ +let redisClient: Redis | undefined; + +export const getRedis = (): Redis => { + if (!redisClient) { + redisClient = getRedisClient(); + } + return redisClient; +}; diff --git a/src/content-indexer/utils/test-factories.ts b/src/content-indexer/utils/test-factories.ts new file mode 100644 index 000000000..0b80e6cd4 --- /dev/null +++ b/src/content-indexer/utils/test-factories.ts @@ -0,0 +1,49 @@ +import type { + OpenApiSpec, + OpenRpcSpec, +} from "@/content-indexer/types/specs.js"; +import type { RepoConfig } from "@/content-indexer/utils/github.ts"; + +/** + * Factory for creating OpenAPI spec with minimal required fields for testing + */ +export const openApiSpecFactory = ( + overrides: Partial = {}, +): OpenApiSpec => ({ + openapi: "3.0.0", + info: { + title: "Test API", + version: "1.0.0", + }, + paths: {}, + ...overrides, +}); + +/** + * Factory for creating OpenRPC spec with minimal required fields for testing + */ +export const openRpcSpecFactory = ( + overrides: Partial = {}, +): OpenRpcSpec => ({ + openrpc: "1.0.0", + info: { + title: "Test API", + version: "1.0.0", + }, + methods: [], + ...overrides, +}); + +/** + * Factory for creating RepoConfig with minimal required fields for testing + */ +export const repoConfigFactory = ( + overrides: Partial = {}, +): RepoConfig => ({ + owner: "test-owner", + repo: "test-repo", + branch: "main", + docsPrefix: "docs/", + stripPathPrefix: "", + ...overrides, +}); diff --git a/src/content-indexer/utils/truncate-record.ts b/src/content-indexer/utils/truncate-record.ts new file mode 100644 index 000000000..3fa7d8a75 --- /dev/null +++ b/src/content-indexer/utils/truncate-record.ts @@ -0,0 +1,77 @@ +import removeMd from "remove-markdown"; + +import type { AlgoliaRecord } from "@/content-indexer/types/algolia.ts"; + +const MAX_RECORD_BYTES = 100_000; // Algolia imposes a 100KB limit on each record +const BUFFER_BYTES = 1_000; +const MAX_ITERATIONS = 5; + +/** + * Truncate record content to ensure entire JSON payload fits within Algolia limit. + * Also strips markdown formatting from content for better search experience. + */ +export const truncateRecord = (rawRecord: AlgoliaRecord): AlgoliaRecord => { + // Strip markdown formatting to get clean, searchable text + const cleanedContent = removeMd(rawRecord.content); + const record = { ...rawRecord, content: cleanedContent }; + + const fullRecordJson = JSON.stringify(record); + const recordBytes = Buffer.byteLength(fullRecordJson, "utf8"); + + if (recordBytes <= MAX_RECORD_BYTES) { + return record; // Record is fine as-is - should be the case for over 99% of records + } + + // Calculate overhead (everything except content field) + const recordWithoutContent = { ...record, content: "" }; + const overheadBytes = Buffer.byteLength( + JSON.stringify(recordWithoutContent), + "utf8", + ); + + console.warn( + `⚠️ Record "${record.title}" (${record.path}) exceeds ${MAX_RECORD_BYTES} bytes\n`, + ` Total: ${recordBytes} bytes\n`, + ` Content: ${Buffer.byteLength(record.content, "utf8")} bytes\n`, + ` Overhead (all non-content data): ${overheadBytes} bytes`, + ); + + if (overheadBytes > MAX_RECORD_BYTES - 1000) { + throw new Error( + `Record overhead (${overheadBytes} bytes) is too large! Something is wrong with the record data.`, + ); + } + + // Iteratively truncate content while measuring full JSON record size + // This accounts for JSON escaping overhead (quotes, backslashes, etc.) + let truncatedContent = cleanedContent; + let truncatedRecord: AlgoliaRecord = { ...record, content: truncatedContent }; + let currentBytes = recordBytes; + let iterations = 0; + + while (currentBytes > MAX_RECORD_BYTES && iterations < MAX_ITERATIONS) { + // Calculate reduction ratio to reach target size + const reductionRatio = (MAX_RECORD_BYTES - BUFFER_BYTES) / currentBytes; + + // Use code point-aware truncation to avoid splitting multi-byte UTF-8 characters (emoji, etc.) + const codePoints = Array.from(truncatedContent); + const targetCodePoints = Math.floor(codePoints.length * reductionRatio); + truncatedContent = codePoints.slice(0, targetCodePoints).join("") + "..."; + + truncatedRecord = { ...record, content: truncatedContent }; + currentBytes = Buffer.byteLength(JSON.stringify(truncatedRecord), "utf8"); + iterations++; + } + + if (currentBytes > MAX_RECORD_BYTES) { + throw new Error( + `Failed to truncate record after ${MAX_ITERATIONS} iterations. Final size: ${currentBytes} bytes`, + ); + } + + console.warn( + ` ✓ Truncated to ${currentBytes} bytes (${truncatedContent.length} chars) in ${iterations} iteration${iterations === 1 ? "" : "s"}\n`, + ); + + return truncatedRecord; +}; diff --git a/src/content-indexer/visitors/__tests__/index.test.ts b/src/content-indexer/visitors/__tests__/index.test.ts new file mode 100644 index 000000000..d436c5c93 --- /dev/null +++ b/src/content-indexer/visitors/__tests__/index.test.ts @@ -0,0 +1,120 @@ +import { describe, expect, test } from "vitest"; + +import { ProcessingContext } from "@/content-indexer/collectors/processing-context.ts"; +import { ContentCache } from "@/content-indexer/core/content-cache.ts"; +import { PathBuilder } from "@/content-indexer/core/path-builder.ts"; +import { DOCS_REPO } from "@/content-indexer/utils/github.ts"; +import { openApiSpecFactory } from "@/content-indexer/utils/test-factories.ts"; + +import { visitNavigationItem } from "../index.ts"; + +describe("visitNavigationItem dispatcher", () => { + test("should route page config to visitPage", () => { + const context = new ProcessingContext(); + const result = visitNavigationItem({ + item: { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }); + + expect(result.navItem).toBeDefined(); + expect(result.navItem).toHaveProperty("type", "page"); + }); + + test("should route link config to visitLink", () => { + const context = new ProcessingContext(); + const result = visitNavigationItem({ + item: { + link: "External", + href: "https://example.com", + }, + parentPath: PathBuilder.init(), + tab: "guides", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }); + + expect(result.navItem).toBeDefined(); + expect(result.navItem).toHaveProperty("type", "link"); + }); + + test("should route section config to visitSection", () => { + const context = new ProcessingContext(); + const result = visitNavigationItem({ + item: { + section: "Getting Started", + contents: [ + { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + ], + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }); + + expect(result.navItem).toBeDefined(); + expect(result.navItem).toHaveProperty("type", "section"); + }); + + test("should skip changelog config", () => { + const context = new ProcessingContext(); + const result = visitNavigationItem({ + item: { + changelog: "CHANGELOG.md", + }, + parentPath: PathBuilder.init(), + tab: "guides", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }); + + expect(result.indexEntries).toEqual({}); + expect(result.navItem).toBeUndefined(); + }); + + test("should handle API config routing", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + // Add a mock spec to cache + cache.setSpec("ethereum-api", { + specType: "openapi", + spec: openApiSpecFactory(), + specUrl: "https://example.com/spec.json", + }); + + const result = visitNavigationItem({ + item: { + api: "Ethereum API", + "api-name": "ethereum-api", + }, + parentPath: PathBuilder.init("reference"), + tab: "reference", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + // Should return a result (even if empty due to no operations in spec) + expect(result).toBeDefined(); + expect(result.indexEntries).toBeDefined(); + }); +}); diff --git a/src/content-indexer/visitors/__tests__/visit-api-reference.test.ts b/src/content-indexer/visitors/__tests__/visit-api-reference.test.ts new file mode 100644 index 000000000..8452535db --- /dev/null +++ b/src/content-indexer/visitors/__tests__/visit-api-reference.test.ts @@ -0,0 +1,260 @@ +import { describe, expect, test } from "vitest"; + +import { ProcessingContext } from "@/content-indexer/collectors/processing-context.ts"; +import { ContentCache } from "@/content-indexer/core/content-cache.ts"; +import { PathBuilder } from "@/content-indexer/core/path-builder.ts"; +import { DOCS_REPO } from "@/content-indexer/utils/github.ts"; +import { + openApiSpecFactory, + openRpcSpecFactory, +} from "@/content-indexer/utils/test-factories.js"; + +import { visitApiReference } from "../visit-api-reference.ts"; + +describe("visitApiReference", () => { + test("should return empty result if spec not in cache", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitApiReference({ + item: { + api: "Ethereum API", + "api-name": "ethereum-api", + }, + parentPath: PathBuilder.init("reference"), + tab: "reference", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + expect(result.indexEntries).toEqual({}); + expect(result.navItem).toBeUndefined(); + }); + + test("should process OpenAPI spec", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setSpec("ethereum-api", { + specType: "openapi", + spec: openApiSpecFactory({ + paths: { + "/balance": { + get: { + operationId: "getBalance", + summary: "Get Balance", + description: "Get the balance of an address", + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + }); + + const result = visitApiReference({ + item: { + api: "Ethereum API", + "api-name": "ethereum-api", + }, + parentPath: PathBuilder.init("reference"), + tab: "reference", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + expect(Object.keys(result.indexEntries).length).toBeGreaterThan(0); + expect(result.navItem).toBeDefined(); + }); + + test("should process OpenRPC spec", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setSpec("solana-api", { + specType: "openrpc", + spec: openRpcSpecFactory({ + info: { title: "Solana API", version: "1.0.0" }, + methods: [ + { + name: "getAsset", + description: "Get asset information", + params: [], + result: { name: "result", schema: {} }, + }, + ], + }), + specUrl: "https://example.com/rpc-spec.json", + }); + + const result = visitApiReference({ + item: { + api: "Solana API", + "api-name": "solana-api", + }, + parentPath: PathBuilder.init("reference"), + tab: "reference", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + expect(Object.keys(result.indexEntries).length).toBeGreaterThan(0); + expect(result.navItem).toBeDefined(); + }); + + test("should use custom slug for API", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setSpec("ethereum-api", { + specType: "openapi", + spec: openApiSpecFactory({ + paths: { + "/balance": { + get: { + operationId: "getBalance", + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + }); + + const result = visitApiReference({ + item: { + api: "Ethereum API", + "api-name": "ethereum-api", + slug: "eth-api", + }, + parentPath: PathBuilder.init("reference"), + tab: "reference", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + const firstPath = Object.keys(result.indexEntries)[0]; + expect(firstPath).toContain("eth-api"); + }); + + test("should skip slug if skip-slug is true", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setSpec("ethereum-api", { + specType: "openapi", + spec: openApiSpecFactory({ + paths: { + "/balance": { + get: { + operationId: "getBalance", + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + }); + + const result = visitApiReference({ + item: { + api: "Ethereum API", + "api-name": "ethereum-api", + "skip-slug": true, + }, + parentPath: PathBuilder.init("reference"), + tab: "reference", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + const firstPath = Object.keys(result.indexEntries)[0]; + // Should not include "ethereum-api" segment + expect(firstPath).toBe("reference/get-balance"); + }); + + test("should return no nav for hidden API", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setSpec("ethereum-api", { + specType: "openapi", + spec: openApiSpecFactory({ + paths: { + "/balance": { + get: { + operationId: "getBalance", + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + }); + + const result = visitApiReference({ + item: { + api: "Ethereum API", + "api-name": "ethereum-api", + hidden: true, + }, + parentPath: PathBuilder.init("reference"), + tab: "reference", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + expect(result.navItem).toBeUndefined(); + expect(Object.keys(result.indexEntries).length).toBeGreaterThan(0); // Index still created + }); + + test("should flatten API structure if flattened is true", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setSpec("ethereum-api", { + specType: "openapi", + spec: openApiSpecFactory({ + paths: { + "/balance": { + get: { + operationId: "getBalance", + tags: ["ethereum"], + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + }); + + const result = visitApiReference({ + item: { + api: "Ethereum API", + "api-name": "ethereum-api", + flattened: true, + }, + parentPath: PathBuilder.init("reference"), + tab: "reference", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + // Should return array instead of wrapped in API section + expect(Array.isArray(result.navItem)).toBe(true); + }); +}); diff --git a/src/content-indexer/visitors/__tests__/visit-link.test.ts b/src/content-indexer/visitors/__tests__/visit-link.test.ts new file mode 100644 index 000000000..fea50803e --- /dev/null +++ b/src/content-indexer/visitors/__tests__/visit-link.test.ts @@ -0,0 +1,76 @@ +import { describe, expect, test } from "vitest"; + +import { ProcessingContext } from "@/content-indexer/collectors/processing-context.ts"; +import { ContentCache } from "@/content-indexer/core/content-cache.ts"; +import { PathBuilder } from "@/content-indexer/core/path-builder.ts"; +import { DOCS_REPO } from "@/content-indexer/utils/github.ts"; + +import { visitLink } from "../visit-link.ts"; + +describe("visitLink", () => { + test("should create link nav item", () => { + const context = new ProcessingContext(); + const result = visitLink({ + item: { + link: "External Resource", + href: "https://example.com/docs", + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }); + + expect(result.indexEntries).toEqual({}); + expect(result.navItem).toEqual({ + title: "External Resource", + href: "https://example.com/docs", + type: "link", + }); + }); + + test("should not add path index entries for links", () => { + const context = new ProcessingContext(); + const result = visitLink({ + item: { + link: "GitHub", + href: "https://github.com", + }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }); + + expect(result.indexEntries).toEqual({}); + expect(Object.keys(result.indexEntries)).toHaveLength(0); + }); + + test("should preserve exact link title and href", () => { + const context = new ProcessingContext(); + const result = visitLink({ + item: { + link: "API Reference (External)", + href: "https://api.example.com/v2/docs#section", + }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }); + + expect(result.navItem).toBeDefined(); + if (result.navItem && "href" in result.navItem) { + expect(result.navItem.title).toBe("API Reference (External)"); + expect(result.navItem.href).toBe( + "https://api.example.com/v2/docs#section", + ); + } + }); +}); diff --git a/src/content-indexer/visitors/__tests__/visit-page.test.ts b/src/content-indexer/visitors/__tests__/visit-page.test.ts new file mode 100644 index 000000000..ae4631668 --- /dev/null +++ b/src/content-indexer/visitors/__tests__/visit-page.test.ts @@ -0,0 +1,253 @@ +import { describe, expect, test } from "vitest"; + +import { ProcessingContext } from "@/content-indexer/collectors/processing-context.ts"; +import { ContentCache } from "@/content-indexer/core/content-cache.ts"; +import { PathBuilder } from "@/content-indexer/core/path-builder.ts"; +import { DOCS_REPO } from "@/content-indexer/utils/github.ts"; + +import { visitPage } from "../visit-page.ts"; + +describe("visitPage", () => { + test("should create path index entry for page", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitPage({ + item: { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + expect(result.indexEntries["guides/quickstart"]).toEqual({ + type: "mdx", + filePath: "fern/guides/quickstart.mdx", + source: "docs-yml", + tab: "guides", + }); + }); + + test("should create nav item for visible page", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitPage({ + item: { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + expect(result.navItem).toEqual({ + title: "Quickstart", + path: "/guides/quickstart", + type: "page", + }); + }); + + test("should skip nav item for hidden page", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitPage({ + item: { + page: "Hidden Page", + path: "fern/guides/hidden.mdx", + hidden: true, + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + expect(result.navItem).toBeUndefined(); + expect(result.indexEntries["guides/hidden-page"]).toBeDefined(); // Index still created + }); + + test("should use custom slug if provided", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitPage({ + item: { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + slug: "custom-slug", + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + expect(result.indexEntries["guides/custom-slug"]).toBeDefined(); + expect(result.navItem).toBeDefined(); + if ( + result.navItem && + !Array.isArray(result.navItem) && + "path" in result.navItem + ) { + expect(result.navItem.path).toBe("/guides/custom-slug"); + } + }); + + test("should use frontmatter slug if available", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setMdxContent("fern/guides/quickstart.mdx", { + frontmatter: { + slug: "docs/custom/frontmatter/path", + title: "Custom Title", + }, + content: "Content", + }); + + const result = visitPage({ + item: { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + expect(result.indexEntries["custom/frontmatter/path"]).toBeDefined(); + expect(result.indexEntries["custom/frontmatter/path"].source).toBe( + "frontmatter", + ); + }); + + test("should add Algolia record if content cached and not hidden", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setMdxContent("fern/guides/quickstart.mdx", { + frontmatter: { + title: "Quick Start Guide", + }, + content: "This is the content of the quickstart guide", + }); + + visitPage({ + item: { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [ + { + title: "Guides", + path: "/guides", + type: "section", + children: [], + }, + ], + }); + + const results = context.getResults(); + expect(results.algoliaRecords).toHaveLength(1); + expect(results.algoliaRecords[0].title).toBe("Quick Start Guide"); + expect(results.algoliaRecords[0].pageType).toBe("Guide"); + expect(results.algoliaRecords[0].breadcrumbs).toEqual(["Guides"]); + }); + + test("should fallback to page name for Algolia title if no frontmatter title", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setMdxContent("fern/guides/quickstart.mdx", { + frontmatter: {}, + content: "Content without title", + }); + + visitPage({ + item: { + page: "Quickstart Page Name", + path: "fern/guides/quickstart.mdx", + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + const results = context.getResults(); + expect(results.algoliaRecords[0].title).toBe("Quickstart Page Name"); + }); + + test("should not add Algolia record if content not cached", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + visitPage({ + item: { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + const results = context.getResults(); + expect(results.algoliaRecords).toHaveLength(0); + }); + + test("should not add Algolia record if page is hidden", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setMdxContent("fern/guides/hidden.mdx", { + frontmatter: { title: "Hidden Page" }, + content: "Secret content", + }); + + visitPage({ + item: { + page: "Hidden", + path: "fern/guides/hidden.mdx", + hidden: true, + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }); + + const results = context.getResults(); + expect(results.algoliaRecords).toHaveLength(0); + }); +}); diff --git a/src/content-indexer/visitors/__tests__/visit-section.test.ts b/src/content-indexer/visitors/__tests__/visit-section.test.ts new file mode 100644 index 000000000..45e7b6505 --- /dev/null +++ b/src/content-indexer/visitors/__tests__/visit-section.test.ts @@ -0,0 +1,337 @@ +import { describe, expect, test } from "vitest"; + +import { ProcessingContext } from "@/content-indexer/collectors/processing-context.ts"; +import { ContentCache } from "@/content-indexer/core/content-cache.ts"; +import { PathBuilder } from "@/content-indexer/core/path-builder.ts"; +import { DOCS_REPO } from "@/content-indexer/utils/github.ts"; + +import { visitNavigationItem } from "../index.ts"; +import { visitSection } from "../visit-section.ts"; + +describe("visitSection", () => { + test("should create section nav item with children", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitSection( + { + item: { + section: "Getting Started", + contents: [ + { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + ], + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }, + visitNavigationItem, + ); + + expect(result.navItem).toBeDefined(); + expect(result.navItem).toHaveProperty("type", "section"); + expect(result.navItem).toHaveProperty("title", "Getting Started"); + if ( + result.navItem && + !Array.isArray(result.navItem) && + (result.navItem.type === "section" || + result.navItem.type === "api-section") + ) { + expect(result.navItem.children).toHaveLength(1); + } + }); + + test("should process all child items", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitSection( + { + item: { + section: "API Reference", + contents: [ + { + page: "Overview", + path: "fern/reference/overview.mdx", + }, + { + page: "Authentication", + path: "fern/reference/auth.mdx", + }, + ], + }, + parentPath: PathBuilder.init("reference"), + tab: "reference", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }, + visitNavigationItem, + ); + + if ( + result.navItem && + !Array.isArray(result.navItem) && + (result.navItem.type === "section" || + result.navItem.type === "api-section") + ) { + expect(result.navItem.children).toHaveLength(2); + } + expect(Object.keys(result.indexEntries)).toHaveLength(2); + }); + + test("should handle section with overview page", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setMdxContent("fern/guides/overview.mdx", { + frontmatter: { title: "Overview" }, + content: "Overview content", + }); + + const result = visitSection( + { + item: { + section: "Getting Started", + path: "fern/guides/overview.mdx", + contents: [ + { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + ], + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }, + visitNavigationItem, + ); + + // Should have overview path index entry + expect(result.indexEntries["guides/getting-started"]).toBeDefined(); + expect(result.navItem).toHaveProperty("path"); + }); + + test("should use custom slug if provided", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitSection( + { + item: { + section: "Getting Started", + slug: "custom-section", + contents: [ + { + page: "Page", + path: "fern/guides/page.mdx", + }, + ], + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }, + visitNavigationItem, + ); + + expect(result.indexEntries["guides/custom-section/page"]).toBeDefined(); + }); + + test("should skip slug if skip-slug is true", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitSection( + { + item: { + section: "Getting Started", + "skip-slug": true, + contents: [ + { + page: "Page", + path: "fern/guides/page.mdx", + }, + ], + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }, + visitNavigationItem, + ); + + // Page should be directly under guides, not guides/getting-started + expect(result.indexEntries["guides/page"]).toBeDefined(); + }); + + test("should handle hidden section", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitSection( + { + item: { + section: "Hidden Section", + hidden: true, + contents: [ + { + page: "Page", + path: "fern/guides/page.mdx", + }, + ], + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }, + visitNavigationItem, + ); + + expect(result.navItem).toBeUndefined(); + // Index entries should still be created + expect(Object.keys(result.indexEntries).length).toBeGreaterThan(0); + }); + + test("should recursively process nested sections", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitSection( + { + item: { + section: "Level 1", + contents: [ + { + section: "Level 2", + contents: [ + { + page: "Deep Page", + path: "fern/guides/deep.mdx", + }, + ], + }, + ], + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }, + visitNavigationItem, + ); + + // Should have deeply nested path + expect( + result.indexEntries["guides/level-1/level-2/deep-page"], + ).toBeDefined(); + }); + + test("should add section to breadcrumbs for children", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + cache.setMdxContent("fern/guides/quickstart.mdx", { + frontmatter: { title: "Quickstart" }, + content: "Content", + }); + + visitSection( + { + item: { + section: "Getting Started", + contents: [ + { + page: "Quickstart", + path: "fern/guides/quickstart.mdx", + }, + ], + }, + parentPath: PathBuilder.init("guides"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }, + visitNavigationItem, + ); + + const results = context.getResults(); + // Child page should have "Getting Started" in breadcrumbs + expect(results.algoliaRecords[0].breadcrumbs).toContain("Getting Started"); + }); + + test("should handle section with mix of pages and subsections", () => { + const context = new ProcessingContext(); + const cache = new ContentCache(); + + const result = visitSection( + { + item: { + section: "Documentation", + contents: [ + { + page: "Overview", + path: "fern/docs/overview.mdx", + }, + { + section: "API Reference", + contents: [ + { + page: "Authentication", + path: "fern/docs/auth.mdx", + }, + ], + }, + { + link: "External", + href: "https://example.com", + }, + ], + }, + parentPath: PathBuilder.init("docs"), + tab: "guides", + repo: DOCS_REPO, + contentCache: cache, + context, + navigationAncestors: [], + }, + visitNavigationItem, + ); + + if ( + result.navItem && + !Array.isArray(result.navItem) && + (result.navItem.type === "section" || + result.navItem.type === "api-section") + ) { + expect(result.navItem.children).toHaveLength(3); // page + section + link + expect(result.navItem.children[0].type).toBe("page"); + expect(result.navItem.children[1].type).toBe("section"); + expect(result.navItem.children[2].type).toBe("link"); + } + }); +}); diff --git a/src/content-indexer/visitors/index.ts b/src/content-indexer/visitors/index.ts new file mode 100644 index 000000000..5d2a6d636 --- /dev/null +++ b/src/content-indexer/visitors/index.ts @@ -0,0 +1,76 @@ +import type { ProcessingContext } from "@/content-indexer/collectors/processing-context.ts"; +import type { ContentCache } from "@/content-indexer/core/content-cache.ts"; +import type { PathBuilder } from "@/content-indexer/core/path-builder.ts"; +import { + isApiConfig, + isChangelogConfig, + isLinkConfig, + isPageConfig, + isSectionConfig, + type NavigationItem, +} from "@/content-indexer/types/docsYaml.js"; +import type { NavItem } from "@/content-indexer/types/navigation.ts"; +import type { PathIndex } from "@/content-indexer/types/pathIndex.ts"; +import type { RepoConfig } from "@/content-indexer/utils/github.ts"; + +import { visitApiReference } from "./visit-api-reference.ts"; +import { visitLink } from "./visit-link.ts"; +import { visitPage } from "./visit-page.ts"; +import { visitSection } from "./visit-section.ts"; + +export interface VisitorConfigBase { + parentPath: PathBuilder; + tab: string; + repo: RepoConfig; + contentCache: ContentCache; + context: ProcessingContext; + navigationAncestors: NavItem[]; +} + +export interface VisitorConfig extends VisitorConfigBase { + item: NavigationItem; +} + +export interface VisitorResult { + indexEntries: PathIndex; + navItem?: NavItem | NavItem[]; +} + +/** + * Dispatcher that routes navigation items to the appropriate visitor. + * + * Uses type guards to determine item type and delegates to specialized visitors: + * - Pages → visitPage + * - Sections → visitSection (recursive) + * - API references → visitApiReference + * - Links → visitLink + * - Changelog → skip (no processing needed) + */ +export const visitNavigationItem = (config: VisitorConfig): VisitorResult => { + const { item } = config; + + // Skip changelog items + if (isChangelogConfig(item)) { + return { indexEntries: {}, navItem: undefined }; + } + + // Delegate to appropriate visitor based on item type + if (isLinkConfig(item)) { + return visitLink({ ...config, item }); + } + + if (isPageConfig(item)) { + return visitPage({ ...config, item }); + } + + if (isSectionConfig(item)) { + return visitSection({ ...config, item }, visitNavigationItem); + } + + if (isApiConfig(item)) { + return visitApiReference({ ...config, item }); + } + + // Unknown item type - skip + return { indexEntries: {}, navItem: undefined }; +}; diff --git a/src/content-indexer/visitors/processors/__tests__/process-openapi.test.ts b/src/content-indexer/visitors/processors/__tests__/process-openapi.test.ts new file mode 100644 index 000000000..e75f06cec --- /dev/null +++ b/src/content-indexer/visitors/processors/__tests__/process-openapi.test.ts @@ -0,0 +1,329 @@ +import { describe, expect, test } from "vitest"; + +import { ProcessingContext } from "@/content-indexer/collectors/processing-context.ts"; +import { ContentCache } from "@/content-indexer/core/content-cache.ts"; +import { PathBuilder } from "@/content-indexer/core/path-builder.ts"; +import { DOCS_REPO } from "@/content-indexer/utils/github.ts"; +import { openApiSpecFactory } from "@/content-indexer/utils/test-factories.ts"; + +import { processOpenApiSpec } from "../process-openapi.ts"; + +describe("processOpenApiSpec", () => { + test("should process operations and create index entries", () => { + const context = new ProcessingContext(); + + const result = processOpenApiSpec({ + spec: openApiSpecFactory({ + paths: { + "/balance": { + get: { + operationId: "getBalance", + summary: "Get Balance", + description: "Get the balance of an address", + responses: { "200": { description: "Success" } }, + }, + }, + "/transfer": { + post: { + operationId: "transfer", + summary: "Transfer", + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "Ethereum API", "api-name": "ethereum-api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/ethereum"), + apiTitle: "Ethereum API", + isHidden: false, + isFlattened: false, + }); + + expect(Object.keys(result.indexEntries)).toHaveLength(2); + expect(result.indexEntries["reference/ethereum/get-balance"]).toBeDefined(); + expect(result.indexEntries["reference/ethereum/transfer"]).toBeDefined(); + }); + + test("should group operations by tag", () => { + const context = new ProcessingContext(); + + const result = processOpenApiSpec({ + spec: openApiSpecFactory({ + paths: { + "/users": { + get: { + operationId: "getUsers", + tags: ["users"], + responses: { "200": { description: "Success" } }, + }, + }, + "/posts": { + get: { + operationId: "getPosts", + tags: ["posts"], + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "API", "api-name": "api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/api"), + apiTitle: "API", + isHidden: false, + isFlattened: false, + }); + + if ( + result.navItem && + !Array.isArray(result.navItem) && + (result.navItem.type === "section" || + result.navItem.type === "api-section") + ) { + expect(result.navItem.children).toHaveLength(2); // 2 tag sections + const firstChild = result.navItem.children[0]; + expect(firstChild.type).toBe("section"); + if (firstChild.type === "section" || firstChild.type === "api-section") { + expect(firstChild.title).toMatch(/users|posts/); + } + } + }); + + test("should use summary as operation title", () => { + const context = new ProcessingContext(); + + processOpenApiSpec({ + spec: openApiSpecFactory({ + paths: { + "/balance": { + get: { + operationId: "getBalance", + summary: "Get Account Balance", + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "API", "api-name": "api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/api"), + apiTitle: "API", + isHidden: false, + isFlattened: false, + }); + + const results = context.getResults(); + expect(results.algoliaRecords[0].title).toBe("Get Account Balance"); + }); + + test("should fallback to operationId for title if no summary", () => { + const context = new ProcessingContext(); + + processOpenApiSpec({ + spec: openApiSpecFactory({ + paths: { + "/balance": { + get: { + operationId: "getBalance", + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "API", "api-name": "api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/api"), + apiTitle: "API", + isHidden: false, + isFlattened: false, + }); + + const results = context.getResults(); + expect(results.algoliaRecords[0].title).toBe("getBalance"); + }); + + test("should include tag in path if tag exists", () => { + const context = new ProcessingContext(); + + const result = processOpenApiSpec({ + spec: openApiSpecFactory({ + paths: { + "/users": { + get: { + operationId: "getUsers", + tags: ["users"], + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "API", "api-name": "api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/api"), + apiTitle: "API", + isHidden: false, + isFlattened: false, + }); + + expect(result.indexEntries["reference/api/users/get-users"]).toBeDefined(); + }); + + test("should add Algolia records with breadcrumbs", () => { + const context = new ProcessingContext(); + + processOpenApiSpec({ + spec: openApiSpecFactory({ + paths: { + "/balance": { + get: { + operationId: "getBalance", + description: "Get balance description", + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "Ethereum API", "api-name": "ethereum-api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [ + { + title: "Reference", + path: "/reference", + type: "section", + children: [], + }, + ], + }, + apiPathBuilder: PathBuilder.init("reference/ethereum"), + apiTitle: "Ethereum API", + isHidden: false, + isFlattened: false, + }); + + const results = context.getResults(); + expect(results.algoliaRecords[0].breadcrumbs).toContain("Reference"); + expect(results.algoliaRecords[0].breadcrumbs).toContain("Ethereum API"); + }); + + test("should not add Algolia records if hidden", () => { + const context = new ProcessingContext(); + + processOpenApiSpec({ + spec: openApiSpecFactory({ + paths: { + "/balance": { + get: { + operationId: "getBalance", + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "API", "api-name": "api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/api"), + apiTitle: "API", + isHidden: true, + isFlattened: false, + }); + + const results = context.getResults(); + expect(results.algoliaRecords).toHaveLength(0); + }); + + test("should handle operations without tags", () => { + const context = new ProcessingContext(); + + const result = processOpenApiSpec({ + spec: openApiSpecFactory({ + paths: { + "/balance": { + get: { + operationId: "getBalance", + responses: { "200": { description: "Success" } }, + }, + }, + }, + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "API", "api-name": "api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/api"), + apiTitle: "API", + isHidden: false, + isFlattened: false, + }); + + // Operations without tags should be added directly without tag wrapper + if ( + result.navItem && + !Array.isArray(result.navItem) && + (result.navItem.type === "section" || + result.navItem.type === "api-section") + ) { + expect(result.navItem.children[0].type).toBe("endpoint"); + } + }); +}); diff --git a/src/content-indexer/visitors/processors/__tests__/process-openrpc.test.ts b/src/content-indexer/visitors/processors/__tests__/process-openrpc.test.ts new file mode 100644 index 000000000..040cd78e6 --- /dev/null +++ b/src/content-indexer/visitors/processors/__tests__/process-openrpc.test.ts @@ -0,0 +1,306 @@ +import { describe, expect, test, vi } from "vitest"; + +import { ProcessingContext } from "@/content-indexer/collectors/processing-context.ts"; +import { ContentCache } from "@/content-indexer/core/content-cache.ts"; +import { PathBuilder } from "@/content-indexer/core/path-builder.ts"; +import type { OpenRpcSpec } from "@/content-indexer/types/specs.ts"; +import { DOCS_REPO } from "@/content-indexer/utils/github.ts"; +import { openRpcSpecFactory } from "@/content-indexer/utils/test-factories.ts"; + +import { processOpenRpcSpec } from "../process-openrpc.ts"; + +describe("processOpenRpcSpec", () => { + test("should return empty result for invalid spec", () => { + const context = new ProcessingContext(); + const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {}); + + const result = processOpenRpcSpec({ + spec: {} as OpenRpcSpec, // Invalid spec without methods array + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "API", "api-name": "api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/api"), + apiTitle: "Test API", + isHidden: false, + isFlattened: false, + }); + + expect(result.indexEntries).toEqual({}); + expect(consoleSpy).toHaveBeenCalledWith( + expect.stringContaining("Invalid OpenRPC spec"), + ); + + consoleSpy.mockRestore(); + }); + + test("should process methods and create index entries", () => { + const context = new ProcessingContext(); + + const result = processOpenRpcSpec({ + spec: openRpcSpecFactory({ + methods: [ + { + name: "getAsset", + description: "Get asset information", + params: [], + result: { name: "result", schema: {} }, + }, + { + name: "getAccountInfo", + summary: "Get account info", + params: [], + result: { name: "result", schema: {} }, + }, + ], + }), + specUrl: "https://example.com/rpc-spec.json", + visitorConfig: { + item: { api: "Solana API", "api-name": "solana-api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/solana"), + apiTitle: "Solana API", + isHidden: false, + isFlattened: false, + }); + + expect(Object.keys(result.indexEntries)).toHaveLength(2); + const entry = result.indexEntries["reference/solana/get-asset"]; + expect(entry).toBeDefined(); + expect(entry.type).toBe("openrpc"); + if (entry.type === "openrpc") { + expect(entry.methodName).toBe("getAsset"); + } + }); + + test("should create navigation with API section wrapper", () => { + const context = new ProcessingContext(); + + const result = processOpenRpcSpec({ + spec: openRpcSpecFactory({ + methods: [ + { + name: "getAsset", + params: [], + result: { name: "result", schema: {} }, + }, + ], + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "Solana API", "api-name": "solana-api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/solana"), + apiTitle: "Solana API", + isHidden: false, + isFlattened: false, + }); + + expect(result.navItem).toBeDefined(); + expect(result.navItem).toHaveProperty("type", "api-section"); + expect(result.navItem).toHaveProperty("title", "Solana API"); + if ( + result.navItem && + !Array.isArray(result.navItem) && + (result.navItem.type === "section" || + result.navItem.type === "api-section") + ) { + expect(result.navItem.children).toHaveLength(1); + } + }); + + test("should flatten navigation if flattened is true", () => { + const context = new ProcessingContext(); + + const result = processOpenRpcSpec({ + spec: openRpcSpecFactory({ + methods: [ + { + name: "getAsset", + params: [], + result: { name: "result", schema: {} }, + }, + ], + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "Solana API", "api-name": "solana-api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/solana"), + apiTitle: "Solana API", + isHidden: false, + isFlattened: true, + }); + + expect(Array.isArray(result.navItem)).toBe(true); + }); + + test("should not create nav if hidden", () => { + const context = new ProcessingContext(); + + const result = processOpenRpcSpec({ + spec: openRpcSpecFactory({ + methods: [ + { + name: "getAsset", + params: [], + result: { name: "result", schema: {} }, + }, + ], + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "Solana API", "api-name": "solana-api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/solana"), + apiTitle: "Solana API", + isHidden: true, + isFlattened: false, + }); + + expect(result.navItem).toBeUndefined(); + expect(Object.keys(result.indexEntries).length).toBeGreaterThan(0); // Index still created + }); + + test("should add Algolia records for methods", () => { + const context = new ProcessingContext(); + + processOpenRpcSpec({ + spec: openRpcSpecFactory({ + methods: [ + { + name: "getAsset", + description: "Get asset information", + params: [], + result: { name: "result", schema: {} }, + }, + ], + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "Solana API", "api-name": "solana-api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [ + { + title: "Reference", + path: "/reference", + type: "section", + children: [], + }, + ], + }, + apiPathBuilder: PathBuilder.init("reference/solana"), + apiTitle: "Solana API", + isHidden: false, + isFlattened: false, + }); + + const results = context.getResults(); + expect(results.algoliaRecords).toHaveLength(1); + expect(results.algoliaRecords[0].title).toBe("getAsset"); + expect(results.algoliaRecords[0].pageType).toBe("API Method"); + expect(results.algoliaRecords[0].httpMethod).toBe("POST"); + }); + + test("should use method name as title", () => { + const context = new ProcessingContext(); + + processOpenRpcSpec({ + spec: openRpcSpecFactory({ + methods: [ + { + name: "customMethodName", + params: [], + result: { name: "result", schema: {} }, + }, + ], + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "API", "api-name": "api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/api"), + apiTitle: "Test API", + isHidden: false, + isFlattened: false, + }); + + const results = context.getResults(); + expect(results.algoliaRecords[0].title).toBe("customMethodName"); + }); + + test("should use description over summary for Algolia content", () => { + const context = new ProcessingContext(); + + processOpenRpcSpec({ + spec: openRpcSpecFactory({ + methods: [ + { + name: "getAsset", + description: "Full description", + summary: "Short summary", + params: [], + result: { name: "result", schema: {} }, + }, + ], + }), + specUrl: "https://example.com/spec.json", + visitorConfig: { + item: { api: "API", "api-name": "api" }, + parentPath: PathBuilder.init(), + tab: "reference", + repo: DOCS_REPO, + contentCache: new ContentCache(), + context, + navigationAncestors: [], + }, + apiPathBuilder: PathBuilder.init("reference/api"), + apiTitle: "Test API", + isHidden: false, + isFlattened: false, + }); + + const results = context.getResults(); + expect(results.algoliaRecords[0].content).toBe("Full description"); + }); +}); diff --git a/src/content-indexer/visitors/processors/process-openapi.ts b/src/content-indexer/visitors/processors/process-openapi.ts new file mode 100644 index 000000000..4bd63fa65 --- /dev/null +++ b/src/content-indexer/visitors/processors/process-openapi.ts @@ -0,0 +1,217 @@ +import type { ProcessingContext } from "@/content-indexer/collectors/processing-context.ts"; +import type { PathBuilder } from "@/content-indexer/core/path-builder.ts"; +import type { NavItem } from "@/content-indexer/types/navigation.ts"; +import type { PathIndex } from "@/content-indexer/types/pathIndex.ts"; +import type { OpenApiSpec } from "@/content-indexer/types/specs.ts"; +import { createBreadcrumbNavItem } from "@/content-indexer/utils/navigation-helpers.ts"; +import { + buildOperationPath, + extractOpenApiOperations, + getOperation, + getOperationDescription, + getOperationSummary, + getOperationTitle, + type ExtractedOperation, +} from "@/content-indexer/utils/openapi.js"; +import type { + VisitorConfig, + VisitorResult, +} from "@/content-indexer/visitors/index.js"; + +/** + * Configuration for processing an OpenAPI specification + */ +export interface ProcessOpenApiConfig { + spec: OpenApiSpec; + specUrl: string; + visitorConfig: VisitorConfig; + apiPathBuilder: PathBuilder; + apiTitle: string; + isHidden: boolean; + isFlattened: boolean; +} + +interface BuildOpenApiIndexEntriesConfig { + operations: ExtractedOperation[]; + apiPathBuilder: PathBuilder; + specUrl: string; + tab: string; +} + +interface BuildOpenApiNavigationConfig { + operations: ExtractedOperation[]; + apiPathBuilder: PathBuilder; + spec: OpenApiSpec; + context: ProcessingContext; + navigationAncestors: NavItem[]; + apiSectionBreadcrumb: NavItem | undefined; + isHidden: boolean; +} + +/** + * Builds path index entries for OpenAPI operations. + */ +const buildOpenApiIndexEntries = ({ + operations, + apiPathBuilder, + specUrl, + tab, +}: BuildOpenApiIndexEntriesConfig): PathIndex => { + const indexEntries: PathIndex = {}; + + operations.forEach((operation) => { + const finalPath = buildOperationPath( + apiPathBuilder, + operation.operationId, + operation.tag, + ); + + indexEntries[finalPath] = { + type: "openapi", + specUrl, + operationId: operation.operationId, + source: "docs-yml", + tab, + }; + }); + + return indexEntries; +}; + +/** + * Builds navigation items for OpenAPI operations, grouped by tag. + */ +const buildOpenApiNavigation = ({ + operations, + apiPathBuilder, + spec, + context, + navigationAncestors, + apiSectionBreadcrumb, + isHidden, +}: BuildOpenApiNavigationConfig): NavItem[] => { + // Group operations by tag + const operationsByTag = new Map(); + operations.forEach((operation) => { + const existing = operationsByTag.get(operation.tag) || []; + existing.push(operation); + operationsByTag.set(operation.tag, existing); + }); + + const tagSections: NavItem[] = []; + + for (const [tag, tagOperations] of operationsByTag.entries()) { + const endpointNavItems: NavItem[] = tagOperations.map((operation) => { + const finalPath = buildOperationPath( + apiPathBuilder, + operation.operationId, + operation.tag, + ); + + const operationObj = getOperation( + spec, + operation.path, + operation.method.toLowerCase(), + ); + + const title = getOperationTitle(operationObj, operation.operationId); + + // Build Algolia record if not hidden + if (!isHidden) { + const description = getOperationDescription(operationObj); + const summary = getOperationSummary(operationObj); + + const breadcrumbs = apiSectionBreadcrumb + ? [...navigationAncestors, apiSectionBreadcrumb] + : navigationAncestors; + + context.addAlgoliaRecord({ + pageType: "API Method", + path: finalPath, + title, + content: description, + httpMethod: operation.method, + breadcrumbs, + description: summary, + }); + } + + return { + title, + path: `/${finalPath}`, + method: operation.method, + type: "endpoint" as const, + }; + }); + + // Wrap in tag section if tag exists + if (tag) { + tagSections.push({ + title: tag, + type: "section", + children: endpointNavItems, + }); + } else { + tagSections.push(...endpointNavItems); + } + } + + return tagSections; +}; + +/** + * Processes an OpenAPI specification. + * Extracts operations, builds path index, navigation, and Algolia records. + */ +export const processOpenApiSpec = ({ + spec, + specUrl, + visitorConfig, + apiPathBuilder, + apiTitle, + isHidden, + isFlattened, +}: ProcessOpenApiConfig): VisitorResult => { + const { tab, context, navigationAncestors } = visitorConfig; + + // Extract operations and build index entries + const operations = extractOpenApiOperations(spec.paths); + const indexEntries = buildOpenApiIndexEntries({ + operations, + apiPathBuilder, + specUrl, + tab, + }); + + // Return early if hidden (index only, no navigation) + if (isHidden) { + return { indexEntries, navItem: undefined }; + } + + // Create breadcrumb for Algolia + const apiSectionBreadcrumb = isFlattened + ? undefined + : createBreadcrumbNavItem(apiTitle, "api-section"); + + // Build navigation items + const tagSections = buildOpenApiNavigation({ + operations, + apiPathBuilder, + spec, + context, + navigationAncestors, + apiSectionBreadcrumb, + isHidden, + }); + + // Return flattened or wrapped navigation + const navItem: NavItem | NavItem[] = isFlattened + ? tagSections + : { + title: apiTitle, + type: "api-section", + children: tagSections, + }; + + return { indexEntries, navItem }; +}; diff --git a/src/content-indexer/visitors/processors/process-openrpc.ts b/src/content-indexer/visitors/processors/process-openrpc.ts new file mode 100644 index 000000000..21efc5a7c --- /dev/null +++ b/src/content-indexer/visitors/processors/process-openrpc.ts @@ -0,0 +1,119 @@ +import { kebabCase } from "lodash-es"; +import removeMd from "remove-markdown"; + +import type { PathBuilder } from "@/content-indexer/core/path-builder.ts"; +import type { NavItem } from "@/content-indexer/types/navigation.ts"; +import type { PathIndex } from "@/content-indexer/types/pathIndex.ts"; +import type { OpenRpcSpec } from "@/content-indexer/types/specs.ts"; +import { createBreadcrumbNavItem } from "@/content-indexer/utils/navigation-helpers.ts"; +import { isValidOpenRpcSpec } from "@/content-indexer/utils/openrpc.ts"; +import type { + VisitorConfig, + VisitorResult, +} from "@/content-indexer/visitors/index.js"; + +/** + * Configuration for processing an OpenRPC specification + */ +export interface ProcessOpenRpcConfig { + spec: OpenRpcSpec; + specUrl: string; + visitorConfig: VisitorConfig; + apiPathBuilder: PathBuilder; + apiTitle: string; + isHidden: boolean; + isFlattened: boolean; +} + +/** + * Processes an OpenRPC specification. + * Validates spec, builds path index, navigation, and Algolia records. + */ +export const processOpenRpcSpec = ({ + spec, + specUrl, + visitorConfig, + apiPathBuilder, + apiTitle, + isHidden, + isFlattened, +}: ProcessOpenRpcConfig): VisitorResult => { + const { tab, context, navigationAncestors } = visitorConfig; + + if (!isValidOpenRpcSpec(spec)) { + console.error(` ⚠️ Invalid OpenRPC spec for ${apiTitle}`); + return { indexEntries: {} }; + } + + const indexEntries: PathIndex = {}; + const endpointNavItems: NavItem[] = []; + + // Create breadcrumb for Algolia + const apiSectionBreadcrumb = + !isHidden && !isFlattened + ? createBreadcrumbNavItem(apiTitle, "api-section") + : undefined; + + // Process each RPC method + spec.methods.forEach((method) => { + const slug = kebabCase(method.name); + const pathBuilder = apiPathBuilder.apply({ urlSlug: slug }); + const finalPath = pathBuilder.get(); + + // Add to path index + indexEntries[finalPath] = { + type: "openrpc", + specUrl, + methodName: method.name, + source: "docs-yml", + tab, + }; + + // Build Algolia record if not hidden + if (!isHidden) { + const description = method.description + ? removeMd(method.description) + : method.summary || ""; + const summary = + method.summary || + (method.description ? removeMd(method.description) : undefined); + const breadcrumbs = apiSectionBreadcrumb + ? [...navigationAncestors, apiSectionBreadcrumb] + : navigationAncestors; + + context.addAlgoliaRecord({ + pageType: "API Method", + path: finalPath, + title: method.name, + content: description, + httpMethod: "POST", + breadcrumbs, + description: summary, + }); + } + + // Add navigation item + endpointNavItems.push({ + title: method.name, + path: `/${finalPath}`, + method: "POST", + type: "endpoint", + }); + }); + + // Return early if hidden + if (isHidden) { + return { indexEntries, navItem: undefined }; + } + + // Return flattened or wrapped navigation + const navItem: NavItem | NavItem[] = isFlattened + ? endpointNavItems + : { + title: apiTitle, + type: "api-section", + children: endpointNavItems, + }; + + return { indexEntries, navItem }; +}; diff --git a/src/content-indexer/visitors/visit-api-reference.ts b/src/content-indexer/visitors/visit-api-reference.ts new file mode 100644 index 000000000..0249aa3cd --- /dev/null +++ b/src/content-indexer/visitors/visit-api-reference.ts @@ -0,0 +1,74 @@ +import { kebabCase } from "lodash-es"; + +import type { ApiConfig } from "@/content-indexer/types/docsYaml.ts"; +import type { + OpenApiSpec, + OpenRpcSpec, +} from "@/content-indexer/types/specs.js"; + +import type { VisitorConfigBase, VisitorResult } from "./index.ts"; +import { processOpenApiSpec } from "./processors/process-openapi.ts"; +import { processOpenRpcSpec } from "./processors/process-openrpc.ts"; + +export interface ApiVisitorConfig extends VisitorConfigBase { + item: ApiConfig; +} + +/** + * Visits an API reference item from docs.yml. + * + * Handles both OpenAPI and OpenRPC specifications by delegating to + * spec-specific processors. Extracts config, loads cached spec, + * and routes to the appropriate processor. + */ +export const visitApiReference = (config: ApiVisitorConfig): VisitorResult => { + const { item: apiConfig, parentPath, contentCache } = config; + + // Extract configuration + const apiName = apiConfig["api-name"]; + const apiUrlSlug = apiConfig.slug ?? kebabCase(apiConfig.api); + const skipSlug = apiConfig["skip-slug"] ?? false; + const isHidden = apiConfig.hidden ?? false; + const isFlattened = apiConfig.flattened ?? false; + + // Build path for this API + const apiPathBuilder = skipSlug + ? parentPath + : parentPath.apply({ urlSlug: apiUrlSlug }); + + // Retrieve cached spec + const cached = contentCache.getSpec(apiName); + if (!cached) { + console.warn( + ` ⚠️ No cached spec found for api-name: ${apiName} (skipping)`, + ); + return { indexEntries: {} }; + } + + const { specType, spec, specUrl } = cached; + + // Delegate to spec-specific processor + switch (specType) { + case "openapi": + return processOpenApiSpec({ + spec: spec as OpenApiSpec, + specUrl, + visitorConfig: config, + apiPathBuilder, + apiTitle: apiConfig.api, + isHidden, + isFlattened, + }); + + case "openrpc": + return processOpenRpcSpec({ + spec: spec as OpenRpcSpec, + specUrl, + visitorConfig: config, + apiPathBuilder, + apiTitle: apiConfig.api, + isHidden, + isFlattened, + }); + } +}; diff --git a/src/content-indexer/visitors/visit-link.ts b/src/content-indexer/visitors/visit-link.ts new file mode 100644 index 000000000..c26f1c616 --- /dev/null +++ b/src/content-indexer/visitors/visit-link.ts @@ -0,0 +1,25 @@ +import type { LinkConfig } from "@/content-indexer/types/docsYaml.ts"; + +import type { VisitorConfigBase, VisitorResult } from "./index.ts"; + +export interface LinkVisitorConfig extends VisitorConfigBase { + item: LinkConfig; +} + +/** + * Visits a link item from docs.yml. + * + * Links are external URLs - they only appear in navigation, not in path index. + */ +export const visitLink = (config: LinkVisitorConfig): VisitorResult => { + const { item: linkItem } = config; + + return { + indexEntries: {}, + navItem: { + title: linkItem.link, + href: linkItem.href, + type: "link", + }, + }; +}; diff --git a/src/content-indexer/visitors/visit-page.ts b/src/content-indexer/visitors/visit-page.ts new file mode 100644 index 000000000..864f1a84a --- /dev/null +++ b/src/content-indexer/visitors/visit-page.ts @@ -0,0 +1,84 @@ +import { kebabCase } from "lodash-es"; + +import type { PageConfig } from "@/content-indexer/types/docsYaml.ts"; +import type { NavItem } from "@/content-indexer/types/navigation.ts"; +import { + normalizeFilePath, + normalizeSlug, +} from "@/content-indexer/utils/normalization.js"; + +import type { VisitorConfigBase, VisitorResult } from "./index.ts"; + +export interface PageVisitorConfig extends VisitorConfigBase { + item: PageConfig; +} + +/** + * Visits a page item from docs.yml. + * + * Builds: + * - Path index entry for URL routing + * - Navigation item for sidebar (unless hidden) + * - Algolia record for search (unless hidden) + */ +export const visitPage = ({ + item: pageItem, + parentPath, + tab, + repo, + contentCache, + context, + navigationAncestors, +}: PageVisitorConfig): VisitorResult => { + // Look up cached MDX content + const cached = contentCache.getMdxContent(pageItem.path); + const frontmatterSlug = normalizeSlug(cached?.frontmatter.slug); + const urlSlug = pageItem.slug ?? kebabCase(pageItem.page); + + const pagePathBuilder = parentPath.apply({ + fullSlug: frontmatterSlug?.split("/"), + urlSlug, + }); + + const finalPath = pagePathBuilder.get(); + + // Build index entry + const indexEntries = { + [finalPath]: { + type: "mdx" as const, + filePath: normalizeFilePath(pageItem.path, repo), + source: frontmatterSlug + ? ("frontmatter" as const) + : ("docs-yml" as const), + tab, + }, + }; + + // Build nav item (skip if hidden) + const navItem: NavItem | undefined = pageItem.hidden + ? undefined + : { + title: pageItem.page, + path: `/${finalPath}`, + type: "page", + }; + + // Build Algolia record (if content available and not hidden) + if (cached && navItem) { + const title = cached.frontmatter.title || pageItem.page; + const descriptionRaw = + cached.frontmatter.description || cached.frontmatter.subtitle; + const description = + typeof descriptionRaw === "string" ? descriptionRaw : undefined; + context.addAlgoliaRecord({ + pageType: "Guide", + path: finalPath, + title, + content: cached.content, + breadcrumbs: navigationAncestors, // Excludes current page + description, + }); + } + + return { indexEntries, navItem }; +}; diff --git a/src/content-indexer/visitors/visit-section.ts b/src/content-indexer/visitors/visit-section.ts new file mode 100644 index 000000000..03cb06644 --- /dev/null +++ b/src/content-indexer/visitors/visit-section.ts @@ -0,0 +1,150 @@ +import { kebabCase } from "lodash-es"; + +import type { SectionConfig } from "@/content-indexer/types/docsYaml.ts"; +import type { NavItem } from "@/content-indexer/types/navigation.ts"; +import type { PathIndex } from "@/content-indexer/types/pathIndex.ts"; +import { + normalizeFilePath, + normalizeSlug, +} from "@/content-indexer/utils/normalization.js"; + +import type { + VisitorConfig, + VisitorConfigBase, + VisitorResult, +} from "./index.js"; + +export interface SectionVisitorConfig extends VisitorConfigBase { + item: SectionConfig; +} + +/** + * Visits a section item from docs.yml. + * + * Builds: + * - Path index entry for overview page (if exists) + * - Hierarchical navigation with children + * - Algolia record for overview page (if exists) + * - Recursively processes all child items + */ +export const visitSection = ( + config: SectionVisitorConfig, + visitNavigationItem: (config: VisitorConfig) => VisitorResult, +): VisitorResult => { + const { + item: sectionItem, + parentPath, + tab, + repo, + contentCache, + context, + navigationAncestors, + } = config; + const sectionUrlSlug = sectionItem.slug ?? kebabCase(sectionItem.section); + const skipSlug = sectionItem["skip-slug"] ?? false; + + let sectionFullSlug: string[] | undefined; + let sectionPath: string | undefined; + const indexEntries: PathIndex = {}; + + // If there's an overview page, look up cached content + if (sectionItem.path) { + const cached = contentCache.getMdxContent(sectionItem.path); + const normalizedSlug = normalizeSlug(cached?.frontmatter.slug as string); + sectionFullSlug = normalizedSlug?.split("/"); + + const sectionPathBuilder = parentPath.apply({ + fullSlug: sectionFullSlug, + urlSlug: sectionUrlSlug, + skipUrlSlug: skipSlug, + }); + + const finalPath = sectionPathBuilder.get(); + sectionPath = `/${finalPath}`; + + // Add overview page to index + indexEntries[finalPath] = { + type: "mdx", + filePath: normalizeFilePath(sectionItem.path, repo), + source: normalizedSlug ? "frontmatter" : "docs-yml", + tab, + }; + + // Build Algolia record for section overview page (if content available) + if (cached) { + const title = (cached.frontmatter.title as string) || sectionItem.section; + const descriptionRaw = + cached.frontmatter.description || cached.frontmatter.subtitle; + const description = + typeof descriptionRaw === "string" ? descriptionRaw : undefined; + context.addAlgoliaRecord({ + pageType: "Guide", + path: finalPath, + title, + content: cached.content, + breadcrumbs: navigationAncestors, // Excludes current section + description, + }); + } + } + + // Create path builder for children + const childPathBuilder = parentPath.apply({ + fullSlug: sectionFullSlug, + urlSlug: sectionUrlSlug, + skipUrlSlug: skipSlug, + }); + + // Build section nav item first (for navigation tree) + const sectionNavItem: NavItem = { + title: sectionItem.section, + path: sectionPath, + type: "section", + children: [], // Will be populated below + }; + + // Create breadcrumb (simple copy, no path computation needed) + // If section has no overview page, path will be undefined - this is OK + const sectionBreadcrumb: NavItem = { + title: sectionItem.section, + path: sectionPath, // undefined if no overview page + type: "section", + children: [], + }; + + // Update ancestors to include current section (using breadcrumb copy) + const childAncestors = sectionItem.hidden + ? navigationAncestors // Don't include hidden sections in breadcrumbs + : [...navigationAncestors, sectionBreadcrumb]; + + // Process all children with correct breadcrumbs + const childResults = sectionItem.contents.map((childItem) => + visitNavigationItem({ + ...config, + item: childItem, + parentPath: childPathBuilder, + navigationAncestors: childAncestors, + }), + ); + + // Merge child index entries + childResults.forEach((result) => { + Object.assign(indexEntries, result.indexEntries); + }); + + // Build children nav items (flatten arrays from API refs) + const children: NavItem[] = childResults + .map((result) => result.navItem) + .flat() + .filter((child): child is NavItem => child !== undefined); + + // Only include section in nav if it has children and is not hidden + if (children.length === 0 || sectionItem.hidden) { + return { indexEntries, navItem: undefined }; + } + + // Update section nav item with children + sectionNavItem.children = children; + + return { indexEntries, navItem: sectionNavItem }; +}; diff --git a/src/utils/generateRpcSpecs.ts b/src/utils/generateRpcSpecs.ts index edffff2f2..fae58e884 100644 --- a/src/utils/generateRpcSpecs.ts +++ b/src/utils/generateRpcSpecs.ts @@ -1,8 +1,8 @@ import { dereference } from "@apidevtools/json-schema-ref-parser"; -import type { DerefedOpenRpcDoc } from "../types/openRpc"; -import { formatOpenRpcDoc, writeOpenRpcDoc } from "./generationHelpers"; -import { validateRpcSpec } from "./validateRpcSpec"; +import type { DerefedOpenRpcDoc } from "../types/openRpc.ts"; +import { formatOpenRpcDoc, writeOpenRpcDoc } from "./generationHelpers.ts"; +import { validateRpcSpec } from "./validateRpcSpec.ts"; /** * Generates an OpenRPC specification for the Alchemy JSON-RPC API. diff --git a/src/utils/generationHelpers.ts b/src/utils/generationHelpers.ts index 5e64000fc..4e8bd07f8 100644 --- a/src/utils/generationHelpers.ts +++ b/src/utils/generationHelpers.ts @@ -2,7 +2,7 @@ import type { JSONSchema, OpenrpcDocument } from "@open-rpc/meta-schema"; import { writeFileSync } from "fs"; import mergeAllOf from "json-schema-merge-allof"; -import type { DerefedOpenRpcDoc } from "../types/openRpc"; +import type { DerefedOpenRpcDoc } from "../types/openRpc.ts"; /** * Formats an OpenRPC document by removing components, merging allOf schemas, and sorting methods diff --git a/src/utils/validateRpcSpec.ts b/src/utils/validateRpcSpec.ts index dede0e0ad..1174bb7b9 100644 --- a/src/utils/validateRpcSpec.ts +++ b/src/utils/validateRpcSpec.ts @@ -1,6 +1,6 @@ import { validateOpenRPCDocument } from "@open-rpc/schema-utils-js"; -import type { DerefedOpenRpcDoc } from "../types/openRpc"; +import type { DerefedOpenRpcDoc } from "../types/openRpc.ts"; interface ValidationError { keyword: string; diff --git a/tsconfig.json b/tsconfig.json index c70f63164..1718bfccf 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -7,7 +7,13 @@ "jsx": "react-jsx", "jsxImportSource": "react", "strict": true, - "skipLibCheck": true + "skipLibCheck": true, + "baseUrl": ".", + "allowImportingTsExtensions": true, + "noEmit": true, + "paths": { + "@/*": ["src/*"] + } }, "include": ["**/*.ts", "**/*.tsx", "**/*.mts"] } diff --git a/vitest.config.ts b/vitest.config.ts new file mode 100644 index 000000000..6c6f7d616 --- /dev/null +++ b/vitest.config.ts @@ -0,0 +1,21 @@ +import tsconfigPaths from "vite-tsconfig-paths"; +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + plugins: [tsconfigPaths()], + test: { + globals: true, + environment: "node", + coverage: { + provider: "v8", + reporter: ["text", "json", "html"], + exclude: [ + "**/__tests__/**", + "**/node_modules/**", + "**/dist/**", + "**/*.config.*", + "**/coverage/**", + ], + }, + }, +});