ci: typecheck the documented TypeScript blocks, with the shadowing check repaired

.changeset/hybrid-search-query-value.md

@@ -0,0 +1,5 @@
+---
+'@opensaas/stack-rag': minor
+---
+
+The hybrid-search sample in the package guidance now uses the query-value surface: `context.db.Article.where({ OR: [...] }).all()` rather than the removed `findMany`.

.github/workflows/test.yml

@@ -95,6 +95,47 @@ jobs:
           git add --intent-to-add -- packages/cli/tests/fixtures/contract-project
           git diff --exit-code -- packages/cli/tests/fixtures/contract-project
 
+      # Unlike its two sibling checks above, this one reads compiled output: it
+      # resolves @opensaas/* through each package's own `exports` to its dist,
+      # so it measures this branch's own declarations. The contract-fixture
+      # step above builds only the CLI, so the packages the doc blocks import
+      # are built here. turbo caches it, and the test steps below depend on the
+      # same task, so this is a reordering rather than an extra build.
+      #
+      # THE GATE. PRs into `main` are excluded because the fixtures cannot
+      # describe that tree: `files.txt` names this branch's documents and
+      # `fragments.json` keys entries by `file:line`, so against main's RAG
+      # documents every entry would report as orphaned. Unlike the test steps
+      # below, the exclusion has no `== 'main'` run counterpart, so it cannot
+      # expire on its own: once prisma-8 lands, base_ref is always 'main' and
+      # the check would stop running for good. Flipping it is part of that
+      # merge — drop the `!= 'main'` gates on the steps below, delete the
+      # notice step, and re-key scripts/doc-blocks/fragments.json against
+      # main's documents. Tracked on #1301. Every other mention of the flip
+      # points here.
+      - name: Build packages for the doc-block check
+        if: github.base_ref != 'main'
+        run: turbo run build --filter='./packages/*'
+
+      # The checker's own fixture of known-bad and known-good blocks: every bad
+      # block must be reported FAIL and every good one must pass, before the
+      # real documents are trusted to a run of it.
+      - name: Self-test the doc-block checker
+        if: github.base_ref != 'main'
+        run: node scripts/check-doc-typescript-blocks.mjs --self-test
+
+      - name: Check documented TypeScript blocks compile
+        if: github.base_ref != 'main'
+        run: pnpm check:doc-ts-blocks
+
+      # The counterpart the skip above would otherwise lack. It does not run
+      # the check — it makes the gap visible on every PR into main, so the
+      # flip is prompted by CI rather than remembered.
+      - name: Note the skipped doc-block check
+        if: github.base_ref == 'main'
+        run: |
+          echo "::warning title=Doc-block typecheck did not run::pnpm check:doc-ts-blocks runs on PRs into prisma-8 only. The instruction for flipping that gate is the comment above it in .github/workflows/test.yml (#1301)."
+
       - name: Run tests
         if: github.base_ref == 'main'
         run: turbo run test

.gitignore

@@ -61,3 +61,8 @@ ds-bundle/
 # node resolution reaches its node_modules)
 packages/cli/tests/tmp-*/
 packages/auth/tests/tmp-*/
+
+# Doc-block compile check scratch (evaluated inside packages/rag so node
+# resolution reaches its node_modules; removed on exit and on SIGINT/SIGTERM,
+# ignored in case a run is killed outright)
+packages/rag/.doc-blocks-check-*/

docs/content/how-to/rag-advanced.md

@@ -1093,13 +1093,7 @@ import { writeFile } from 'fs/promises'
 export async function backupEmbeddings() {
   const context = await getContext()
 
-  const articles = await context.db.Article.findMany({
-    select: {
-      id: true,
-      title: true,
-      contentEmbedding: true,
-    },
-  })
+  const articles = await context.db.Article.select('id', 'title', 'contentEmbedding').all()
 
   const backup = {
     timestamp: new Date().toISOString(),

eslint.config.js

@@ -28,6 +28,8 @@ export default [
       'packages/cli/tests/fixtures/contract-project/prisma.config.ts',
       'packages/cli/tests/fixtures/contract-project/migrations/**',
       'packages/cli/tests/tmp-*/**',
+      // Doc-block compile check scratch (ESLint 9 flat config does not read .gitignore)
+      'packages/rag/.doc-blocks-check-*/**',
     ],
   },
   js.configs.recommended,

package.json

@@ -18,6 +18,7 @@
     "format:check": "prettier --check .",
     "check:adr-duplicates": "node scripts/check-adr-duplicates.mjs",
     "check:prisma-error-codes": "node scripts/check-prisma-error-codes.mjs",
+    "check:doc-ts-blocks": "node scripts/check-doc-typescript-blocks.mjs",
     "release": "pnpm build && changeset publish",
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",

packages/rag/CLAUDE.md

@@ -529,11 +529,9 @@ const vectors = await provider.embedBatch(chunks.map((chunk) => chunk.text))
 
 ```typescript
 // Combine traditional search with semantic search
-const keywordResults = await context.db.Article.findMany({
-  where: {
-    OR: [{ title: { contains: query } }, { content: { contains: query } }],
-  },
-})
+const keywordResults = await context.db.Article.where({
+  OR: [{ title: { contains: query } }, { content: { contains: query } }],
+}).all()
 
 const semanticResults = await context.db.Article.nearest('contentEmbedding', queryVector)