@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/scripts/check-snippets.mjs

@@ -0,0 +1,993 @@
+#!/usr/bin/env node
+/**
+ * Type-checks the TypeScript code fences that readers and AI agents copy.
+ *
+ * The root and package `llms.txt` guides, the skills, the READMEs and the
+ * other AI-context files are where an agent in a consumer project learns the
+ * API, and it pastes their snippets as they stand. `check:ai-context` keeps
+ * their versions and links current but never compiles a line of code, so a
+ * renamed export or a changed signature left a snippet that no longer
+ * compiles with every gate green.
+ *
+ * This extracts every ```ts, ```tsx and ```typescript fence from those files,
+ * writes each one to its own module in a temporary directory, and compiles them
+ * all as one TypeScript program with the compiler options of Vite's React
+ * template (`strict`, `jsx: react-jsx`, `moduleResolution: bundler`,
+ * `verbatimModuleSyntax`). The directory reaches the `@ic-reactor/*` packages
+ * through symlinks, so a snippet compiles against the declarations
+ * `pnpm build` wrote to `packages/<name>/dist`, through each package's
+ * `exports` map, as it would in an app that installed them. Build first.
+ *
+ * ## The app a snippet runs in
+ *
+ * A snippet takes an app for granted: a canister's generated
+ * `./declarations/backend`, a `./reactor` module holding the setup, a
+ * name built earlier on the page. `scripts/check-snippets/` holds that app,
+ * and a document whose snippets assume another one gets its own, because
+ * documents can disagree. On the `v4` line the app holds only what no
+ * library export provides (`app/globals.ts`), the modules
+ * `meant gen` writes (`app/generated/`, for the guide's
+ * `./generated/icrc1` and `./generated/backend`) and the third-party
+ * declarations (`ambient.d.ts`). The 3.x fixtures went with the 3.x runtime.
+ *
+ * - `scripts/check-snippets/app/` is the app of every document not listed in
+ *   CONTEXTS below. A context directory holds only what differs for its
+ *   documents; everything else falls through to `app/`.
+ * - A relative import that resolves to nothing (`./reactor`,
+ *   `../declarations/backend`) resolves to the module of the same path in the
+ *   snippet's context directory, then in `app/`. The longest trailing part of
+ *   the path that names one wins, so `./declarations/backend/declarations/backend`
+ *   finds `declarations/backend.ts`.
+ * - An `@/` import, the alias Next.js and Vite apps give their `src/`
+ *   (`@/canisters/ledger/reactor`), resolves the same way with the `@` taken
+ *   off: to `canisters/ledger/reactor.ts` in the context directory, then in
+ *   `app/`. An alias names a path from the root, so only the whole path is
+ *   tried, never a trailing part of it: `reactor` alone would be some other
+ *   module. The fixture is the app's module at that path, shaped as the real
+ *   app's is.
+ * - The names `globals.ts` exports stand for names a snippet uses without
+ *   importing or declaring them, such as a `clientManager` from an earlier
+ *   snippet. Each snippet imports those it does not declare itself, on a line
+ *   added above its first.
+ * - A third-party module a snippet imports is the real package when an example
+ *   app installs it (DEPENDENCY_SOURCES below links their dependencies), such
+ *   as `@tanstack/react-router`, `@tanstack/react-form`, `react-hook-form` and
+ *   `next`. `ambient.d.ts` declares each of the rest once, after the package's
+ *   own types, and only as far as the snippets reach. Two declarations of one
+ *   module would merge into overloads and hide a snippet's mistake, and an
+ *   ambient declaration wins over an installed package, so a module an app
+ *   installs is never declared there.
+ *
+ * Declare a missing app name in a fixture. Do not rewrite a snippet to suit the
+ * checker. A `globals.ts` never exports a library export, or a hook that one
+ * returns: a snippet that uses one must import it, from the library or from the
+ * module that binds it, or an agent pasting it cannot run it. Nor is an ambient declaration bent
+ * to make a snippet pass: fix the snippet, as a reader would have to.
+ *
+ * ## The consumer guides
+ *
+ * `llms.txt`, `llms-full.txt`, each package's `llms.txt` and the consumer skill
+ * (`skill-packages/ic-reactor/`) are what an agent in another project reads,
+ * and it pastes their snippets into an app that has none of the names above.
+ * Two rules are stricter there:
+ *
+ * - A snippet gets no globals. Every name it uses is imported or declared in
+ *   it.
+ * - A relative import resolves first to a module the guide shows: a snippet
+ *   of the same document (or of the same skill) whose first line names its
+ *   file, such as `// src/reactor.ts` for `./reactor`. Only a module the guide
+ *   never shows, such as the canister's declarations, comes from a fixture.
+ *
+ * The docs site's build guides (`build/` under the docs content root) follow
+ * the same two rules: each one takes an app from nothing to working and shows
+ * every file of it, so a reader can paste each file as it stands.
+ *
+ * ## Hooks
+ *
+ * The compiler cannot see the rule the guides teach first: a React hook runs
+ * only inside a component or a custom hook. An agent pastes a snippet as it
+ * stands, so a snippet that calls `useActorQuery(...)` or `query.useQuery()` at
+ * the top of the module teaches code that throws. A call of a `useXxx`
+ * function or method fails the snippet when it is outside every function, in a
+ * class, or in a function that is neither a component (a capitalised name) nor
+ * a custom hook (`useXxx`); an anonymous callback such as `renderHook(() =>
+ * useX())` is let through, since it can be either. Wrap it in a component, as a
+ * reader's code would be.
+ *
+ * ## Opting out
+ *
+ * A fence that is not code to paste, such as a type signature or an interface
+ * restating a library type, opts out with `nocheck` after its language,
+ * ```ts nocheck, or with a first line of `// @snippet-skip`. Use it sparingly:
+ * a skipped snippet is one nothing verifies. Give a placeholder such as `...`
+ * a real value instead.
+ *
+ * Usage
+ *   node scripts/check-snippets.mjs [--docs] [--verbose] [--keep] [path...]
+ *
+ *   path...    check only the files whose repo-relative path contains one of
+ *              these strings
+ *   --docs     also check the docs site's MDX pages, gated like the rest
+ *              (`pnpm check:snippets:docs`). A page compiles against its
+ *              section's fixtures in `scripts/check-snippets/docs/<section>/`
+ *              (the page's directory under the docs content root, `root` for
+ *              a top-level page), then against the default app. Their
+ *              examples import libraries the example apps install, so it
+ *              needs `pnpm install` to have run for the examples too.
+ *   --verbose  list every snippet with its result
+ *   --keep     leave the temporary directory in place (debugging)
+ */
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs"
+import { createRequire } from "node:module"
+import { tmpdir } from "node:os"
+import { dirname, join, relative, sep } from "node:path"
+import { fileURLToPath } from "node:url"
+import { AI_CONTEXT_FILES } from "./ai-context-files.js"
+import { closesFence, fenceOpening } from "./lib/markdown-fences.mjs"
+
+const rootDir = join(dirname(fileURLToPath(import.meta.url)), "..")
+const fixturesDir = join(rootDir, "scripts", "check-snippets")
+const ts = createRequire(import.meta.url)("typescript")
+
+const args = process.argv.slice(2)
+const includeDocs = args.includes("--docs")
+const verbose = args.includes("--verbose")
+const keep = args.includes("--keep")
+const filters = args.filter((arg) => !arg.startsWith("--"))
+
+/** Fence languages that are compiled, and the extension each module gets. */
+const LANGUAGES = { ts: ".ts", typescript: ".ts", tsx: ".tsx" }
+
+const SKIP_INFO = "nocheck"
+const SKIP_COMMENT = /^\s*\/\/\s*@snippet-skip\b/
+/** A first line that is a triple-slash directive, such as `/// <reference lib="..." />`. */
+const TRIPLE_SLASH = /^\s*\/\/\/\s*</
+
+/**
+ * A first line naming the file the snippet is, such as `// src/reactor.ts`
+ * or `// app/Supply.tsx: a React Server Component`. It captures the path
+ * without its extension.
+ */
+const MODULE_HEADER = /^\s*\/\/\s*((?:[\w.-]+\/)*[\w-]+)\.tsx?\b/
+
+/**
+ * The guides an agent in a consumer project reads: the docs site's
+ * `llms.txt` and `llms-full.txt`, each package's `llms.txt` (shipped in its
+ * tarball) and the consumer skill. The agent pastes their snippets into an app
+ * that has none of this checker's globals, so a snippet there gets no
+ * globals: every name it uses is imported, declared, or exported by a module
+ * the guide itself shows.
+ */
+function isConsumerGuide(file) {
+  return (
+    file === "llms.txt" ||
+    file === "llms-full.txt" ||
+    /^packages\/[^/]+\/llms\.txt$/.test(file) ||
+    file.startsWith("skill-packages/ic-reactor/")
+  )
+}
+
+/**
+ * The documents whose snippets share the modules they define: all the files
+ * of one skill (its SKILL.md and references), otherwise one document.
+ */
+function moduleGroup(file) {
+  const skill = /^skill-packages\/[^/]+\//.exec(file)
+  return skill ? skill[0] : file
+}
+
+/** The default app, `scripts/check-snippets/app/`. */
+const DEFAULT_CONTEXT = "app"
+
+const DOCS_ROOT = "docs/src/content/docs/"
+
+/**
+ * The context of a docs page: `docs/<section>` when
+ * `scripts/check-snippets/docs/<section>/` exists, where the section is the
+ * page's directory under the docs content root (`reference/factories`,
+ * `framework`) or `root` for a page at the top. A section's directory holds
+ * only what its pages assume beyond the default app; without one, the page
+ * gets the default app.
+ */
+/**
+ * A build guide of the docs site: a page under `build/` that shows every file
+ * of the app it builds. Its snippets are held to the consumer guides' rules.
+ */
+function isBuildGuide(file) {
+  return file.startsWith(`${DOCS_ROOT}build/`)
+}
+
+function docsContext(file) {
+  if (!file.startsWith(DOCS_ROOT)) return undefined
+  const dir = dirname(file.slice(DOCS_ROOT.length))
+  const context = `docs/${dir === "." ? "root" : dir}`
+  return existsSync(join(fixturesDir, context)) ? context : undefined
+}
+
+/**
+ * Documents whose snippets assume an app other than the default one, by
+ * repo-relative path, and the directory under `scripts/check-snippets/` that
+ * holds what differs.
+ */
+const CONTEXTS = {}
+
+/**
+ * The compiler options of Vite's React + TypeScript template, the setup most
+ * consumers paste into. `verbatimModuleSyntax` is on there, so a snippet that
+ * imports a type without `type` fails in that app and fails here. Unlike the
+ * template, `noUnusedLocals` and `noUnusedParameters` are off (a snippet
+ * declares names to show them, not to use them), and `@types/node` joins the
+ * template's `vite/client`, for the `vite.config.ts` and script snippets.
+ * `vite/client` types `import.meta.env`, where a Vite app reads a canister id.
+ * `allowImportingTsExtensions` is on, as in the template, so a script that
+ * Node runs as TypeScript can import `./tools.ts` as Node needs it to.
+ */
+const COMPILER_OPTIONS = {
+  target: "ES2022",
+  lib: ["ES2022", "DOM", "DOM.Iterable"],
+  module: "ESNext",
+  moduleResolution: "bundler",
+  moduleDetection: "force",
+  verbatimModuleSyntax: true,
+  erasableSyntaxOnly: true,
+  allowImportingTsExtensions: true,
+  jsx: "react-jsx",
+  strict: true,
+  noEmit: true,
+  skipLibCheck: true,
+  noFallthroughCasesInSwitch: true,
+  types: ["node", "vite/client"],
+}
+
+/**
+ * Where third-party packages are linked from, in order of preference. A
+ * snippet can import anything a workspace package installs, and the first
+ * directory listed here that has it wins, so `react` and `@tanstack/*`
+ * resolve to the copies `@ic-reactor/react` itself compiles against.
+ *
+ * A docs page whose examples import a library no package installs (a router,
+ * a form library, `next`) needs an example app that installs it listed after
+ * the runtime packages, so that `react`, `@tanstack/react-query` and the rest
+ * keep the versions the packages themselves compile against.
+ * `examples/next-ssr` provides `next` for the SSR guide's App Router
+ * snippets (`next/server`, `next/headers`). A library only a build guide's app
+ * uses, and no example, is a devDependency of `docs`, listed last:
+ * `@modelcontextprotocol/server`, `@modelcontextprotocol/client` and `zod` for
+ * the agent tools guide.
+ */
+const DEPENDENCY_SOURCES = [
+  "packages/react",
+  "packages/core",
+  "packages/vite-plugin",
+  ".",
+  "examples/next-ssr",
+  "docs",
+]
+
+// ── Source files ─────────────────────────────────────────────────────────────
+
+function walk(dir, predicate, out = []) {
+  // A tree that does not exist, such as skill-packages/ before a skill lands,
+  // holds no files.
+  if (!existsSync(dir)) return out
+  for (const entry of readdirSync(dir).sort()) {
+    const path = join(dir, entry)
+    if (statSync(path).isDirectory()) {
+      if (entry === "node_modules" || entry === "dist") continue
+      walk(path, predicate, out)
+    } else if (predicate(path)) {
+      out.push(path)
+    }
+  }
+  return out
+}
+
+const toPosix = (path) => path.split(sep).join("/")
+
+const packageDirs = readdirSync(join(rootDir, "packages"))
+  .filter((dir) => existsSync(join(rootDir, "packages", dir, "package.json")))
+  .sort()
+
+/**
+ * The files agents and npm readers are pointed at: the READMEs and guides, the
+ * skills, and every file of `scripts/ai-context-files.js`. The last is what
+ * ties this gate to `check:ai-context`: a file that script checks for stale
+ * versions and removed names, this one compiles the snippets of, so a guide
+ * (the DX3 `packages/core/llms.txt`, a skill, a pointer) is gated from the
+ * commit that adds it, with no second list to forget.
+ */
+function gatedFiles() {
+  return [
+    ...new Set([
+      "llms.txt",
+      "llms-full.txt",
+      "README.md",
+      ...packageDirs.flatMap((dir) => [
+        `packages/${dir}/llms.txt`,
+        `packages/${dir}/README.md`,
+      ]),
+      ...walk(join(rootDir, "skill-packages"), (path) =>
+        path.endsWith(".md")
+      ).map((path) => toPosix(relative(rootDir, path))),
+      ...AI_CONTEXT_FILES,
+    ]),
+  ].filter((file) => existsSync(join(rootDir, file)))
+}
+
+/** The docs site's hand-written pages; `libs/` is TypeDoc output. */
+function docsFiles() {
+  const docsDir = join(rootDir, "docs", "src", "content", "docs")
+  return walk(docsDir, (path) => path.endsWith(".mdx"))
+    .filter((path) => !path.startsWith(join(docsDir, "libs") + sep))
+    .map((path) => toPosix(relative(rootDir, path)))
+}
+
+// ── Fence extraction ─────────────────────────────────────────────────────────
+
+/**
+ * The fenced code blocks of a Markdown (or MDX) file, by the rule in
+ * `lib/markdown-fences.mjs`. A fence that is never closed runs to the end of
+ * the file, as CommonMark has it, so its code is checked rather than dropped
+ * (#980). The opening fence's indentation is removed from each line (fences
+ * nested in lists and MDX components are indented).
+ *
+ * @returns {{ lang: string, info: string[], line: number, code: string }[]}
+ *   `line` is the 1-based line of the fence's first line of code.
+ */
+function extractFences(text) {
+  const lines = text.split("\n")
+  const fences = []
+  let open = null
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (open === null) {
+      const opening = fenceOpening(line)
+      if (opening) open = { ...opening, line: i + 2, body: [] }
+      continue
+    }
+    if (closesFence(line, open.marker)) {
+      const { lang, info, line: start, body } = open
+      fences.push({ lang, info, line: start, code: body.join("\n") })
+      open = null
+      continue
+    }
+    const indent = /^\s*/.exec(line)[0].length
+    open.body.push(line.slice(Math.min(indent, open.indent)))
+  }
+  if (open !== null) {
+    const { lang, info, line: start, body } = open
+    fences.push({ lang, info, line: start, code: body.join("\n") })
+  }
+  return fences
+}
+
+function collectSnippets(files, docs) {
+  const snippets = []
+  for (const file of files) {
+    const text = readFileSync(join(rootDir, file), "utf8")
+    for (const fence of extractFences(text)) {
+      if (!(fence.lang in LANGUAGES)) continue
+      const firstLine = fence.code.split("\n").find((l) => l.trim() !== "")
+      const skipped =
+        fence.info.includes(SKIP_INFO) ||
+        (firstLine !== undefined && SKIP_COMMENT.test(firstLine))
+      const defines =
+        firstLine === undefined ? undefined : MODULE_HEADER.exec(firstLine)
+      snippets.push({
+        file,
+        line: fence.line,
+        lang: fence.lang,
+        code: fence.code,
+        context: CONTEXTS[file] ?? docsContext(file) ?? DEFAULT_CONTEXT,
+        group: moduleGroup(file),
+        defines: defines ? defines[1].split("/") : undefined,
+        selfContained: isConsumerGuide(file) || isBuildGuide(file),
+        skipped,
+        docs,
+      })
+    }
+  }
+  return snippets
+}
+
+// ── The app a snippet assumes ────────────────────────────────────────────────
+
+/** Whether a statement carries the `export` modifier. */
+const isExported = (node) =>
+  ts.getModifiers?.(node)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+
+/** The names a binding (`a`, `{ a, b: c }`, `[d, ...e]`) declares. */
+function bindingNames(name, out = []) {
+  if (ts.isIdentifier(name)) out.push(name.text)
+  else
+    for (const element of name.elements) {
+      if (!ts.isOmittedExpression(element)) bindingNames(element.name, out)
+    }
+  return out
+}
+
+function parse(fileName, text) {
+  return ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true)
+}
+
+/**
+ * The names a context's `globals.ts` exports, each marked as a type or a
+ * value, following its `export * from "..."` statements.
+ *
+ * @returns {Map<string, "type" | "value">}
+ */
+function globalNames(file, seen = new Set()) {
+  const names = new Map()
+  if (seen.has(file)) return names
+  seen.add(file)
+  for (const statement of parse(file, readFileSync(file, "utf8")).statements) {
+    if (
+      ts.isExportDeclaration(statement) &&
+      !statement.exportClause &&
+      statement.moduleSpecifier
+    ) {
+      const target = join(dirname(file), statement.moduleSpecifier.text)
+      for (const [name, kind] of globalNames(`${target}.ts`, seen)) {
+        if (!names.has(name)) names.set(name, kind)
+      }
+    } else if (ts.isExportDeclaration(statement) && statement.exportClause) {
+      for (const element of statement.exportClause.elements) {
+        const isType = statement.isTypeOnly || element.isTypeOnly
+        names.set(element.name.text, isType ? "type" : "value")
+      }
+    } else if (!isExported(statement)) {
+      continue
+    } else if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        for (const name of bindingNames(declaration.name)) {
+          names.set(name, "value")
+        }
+      }
+    } else if (
+      ts.isInterfaceDeclaration(statement) ||
+      ts.isTypeAliasDeclaration(statement)
+    ) {
+      names.set(statement.name.text, "type")
+    } else if (statement.name && ts.isIdentifier(statement.name)) {
+      names.set(statement.name.text, "value")
+    }
+  }
+  return names
+}
+
+/** The names a snippet declares or imports at its top level. */
+function declaredNames(sourceFile) {
+  const names = new Set()
+  for (const statement of sourceFile.statements) {
+    if (ts.isImportDeclaration(statement)) {
+      const clause = statement.importClause
+      if (!clause) continue
+      if (clause.name) names.add(clause.name.text)
+      const bindings = clause.namedBindings
+      if (bindings && ts.isNamespaceImport(bindings)) {
+        names.add(bindings.name.text)
+      } else if (bindings) {
+        for (const element of bindings.elements) names.add(element.name.text)
+      }
+    } else if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        for (const name of bindingNames(declaration.name)) names.add(name)
+      }
+    } else if (statement.name && ts.isIdentifier(statement.name)) {
+      names.add(statement.name.text)
+    }
+  }
+  return names
+}
+
+/**
+ * The `@/` alias of Next.js and Vite apps: `@/canisters/ledger/reactor` is
+ * `src/canisters/ledger/reactor`, whichever module imports it.
+ */
+const isAppAlias = (specifier) => specifier.startsWith("@/")
+
+/**
+ * The path segments of an import that name the module: a relative import's
+ * without its `.` and `..`, an `@/` import's without the alias, and either
+ * without a `.ts` or `.tsx` extension, which a script Node runs as
+ * TypeScript writes (`./generated/icrc1.ts`).
+ */
+function moduleSegments(specifier) {
+  return (isAppAlias(specifier) ? specifier.slice(1) : specifier)
+    .replace(/\.tsx?$/, "")
+    .split("/")
+    .filter((segment) => segment !== "" && segment !== "." && segment !== "..")
+}
+
+/**
+ * The module a relative or `@/` import names in `context`: the longest
+ * trailing part of its path that is a file in the context directory, then in
+ * `app/`. An `@/` import is anchored at the alias's root (`src/`), so only its
+ * whole path is tried: a trailing part of `@/canisters/ledger/reactor` such as
+ * `reactor` would name some other module.
+ */
+function findFixture(project, context, specifier) {
+  const segments = moduleSegments(specifier)
+  const contexts = [...new Set([context, DEFAULT_CONTEXT])]
+  const last = isAppAlias(specifier) ? 1 : segments.length
+  for (let start = 0; start < last; start++) {
+    const path = segments.slice(start).join("/")
+    for (const name of contexts) {
+      for (const candidate of [
+        `${path}.ts`,
+        `${path}.tsx`,
+        `${path}/index.ts`,
+      ]) {
+        const file = join(project, "fixtures", name, candidate)
+        if (existsSync(file)) return file
+      }
+    }
+  }
+  return undefined
+}
+
+/**
+ * The snippet module a relative import of a consumer guide or a build guide
+ * names when the guide shows that module itself: a snippet of the same
+ * document, or of the same skill, whose first line names a path ending in the
+ * import's
+ * (`// src/reactor.ts` for `./reactor`). The nearest one above the importing
+ * snippet wins, then the first below it, then the first in another file of
+ * the skill. The import is then checked against the module the reader was
+ * shown, and a fixture cannot hide a name that module does not export.
+ *
+ * The READMEs keep their fixtures: they show a module such as `src/reactor.ts`
+ * several times, once per alternative setup, and later sections mean the
+ * first.
+ */
+function findPageModule(byModule, snippet, specifier) {
+  if (!snippet.selfContained) return undefined
+  const segments = moduleSegments(specifier)
+  const matches = (other) =>
+    other !== snippet &&
+    other.group === snippet.group &&
+    other.defines !== undefined &&
+    other.defines.length >= segments.length &&
+    other.defines.slice(-segments.length).join("/") === segments.join("/")
+  const candidates = [...byModule].filter(([, other]) => matches(other))
+  const rank = ([, other]) =>
+    other.file !== snippet.file
+      ? Number.MAX_SAFE_INTEGER
+      : other.line < snippet.line
+        ? snippet.line - other.line
+        : Number.MAX_SAFE_INTEGER / 2 + other.line
+  candidates.sort((a, b) => rank(a) - rank(b))
+  return candidates[0]?.[0]
+}
+
+// ── The compilation ──────────────────────────────────────────────────────────
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"))
+}
+
+/** The installed packages under `nodeModules`, scoped ones as `@scope/name`. */
+function installedPackages(nodeModules) {
+  if (!existsSync(nodeModules)) return []
+  return readdirSync(nodeModules)
+    .filter((entry) => !entry.startsWith("."))
+    .flatMap((entry) =>
+      entry.startsWith("@")
+        ? readdirSync(join(nodeModules, entry)).map((n) => `${entry}/${n}`)
+        : [entry]
+    )
+}
+
+/**
+ * Links every workspace package, and every dependency installed for one, into
+ * `project/node_modules`. Returns the links, so they can be removed before the
+ * directory is: they point into the workspace.
+ */
+function linkPackages(project) {
+  // The docs pages import libraries only an example app installs. Without
+  // them their imports fail one by one as missing modules, which hides what
+  // is wrong. CI installs the workspace without the examples, and checks only
+  // the guides, skills and READMEs, which need none of them.
+  for (const source of DEPENDENCY_SOURCES) {
+    if (
+      includeDocs &&
+      source.startsWith("examples/") &&
+      !existsSync(join(rootDir, source, "node_modules"))
+    ) {
+      throw new Error(
+        `${source} is not installed, and the docs pages import libraries it provides. Run \`pnpm install\` without \`--filter '!./examples/**'\`.`
+      )
+    }
+  }
+  const links = []
+  const linked = new Set()
+  const link = (target, name) => {
+    if (linked.has(name)) return
+    linked.add(name)
+    const path = join(project, "node_modules", name)
+    mkdirSync(dirname(path), { recursive: true })
+    symlinkSync(target, path, "dir")
+    links.push(path)
+  }
+  for (const dir of packageDirs) {
+    const packageDir = join(rootDir, "packages", dir)
+    const manifest = readJson(join(packageDir, "package.json"))
+    if (manifest.private !== true && !existsSync(join(packageDir, "dist"))) {
+      throw new Error(
+        `${manifest.name} is not built (no dist/). Run \`pnpm build\` first.`
+      )
+    }
+    link(packageDir, manifest.name)
+  }
+  for (const source of DEPENDENCY_SOURCES) {
+    const sourceModules = join(rootDir, source, "node_modules")
+    for (const name of installedPackages(sourceModules)) {
+      link(join(sourceModules, name), name)
+    }
+  }
+  return links
+}
+
+/**
+ * Writes each snippet to `project/snippets/`, preceded by an import of the
+ * globals it does not declare, and returns them by absolute module path.
+ */
+function writeSnippets(project, snippets) {
+  const globals = new Map()
+  const byModule = new Map()
+  mkdirSync(join(project, "snippets"), { recursive: true })
+  for (const snippet of snippets) {
+    const slug = snippet.file.replace(/[^A-Za-z0-9]+/g, "_")
+    const modulePath = toPosix(
+      join(
+        project,
+        "snippets",
+        `${slug}_L${snippet.line}${LANGUAGES[snippet.lang]}`
+      )
+    )
+
+    const contextDir = join(project, "fixtures", snippet.context)
+    const globalsFile = existsSync(join(contextDir, "globals.ts"))
+      ? join(contextDir, "globals.ts")
+      : join(project, "fixtures", DEFAULT_CONTEXT, "globals.ts")
+    if (!globals.has(globalsFile)) {
+      globals.set(globalsFile, globalNames(globalsFile))
+    }
+    const declared = declaredNames(parse(modulePath, snippet.code))
+    const imported = snippet.selfContained
+      ? []
+      : [...globals.get(globalsFile)]
+          .filter(([name]) => !declared.has(name))
+          .map(([name, kind]) => (kind === "type" ? `type ${name}` : name))
+    const specifier = toPosix(
+      relative(dirname(modulePath), globalsFile)
+    ).replace(/\.ts$/, "")
+    const prelude =
+      imported.length > 0
+        ? `import { ${imported.join(", ")} } from "${specifier}"\n`
+        : ""
+
+    // A triple-slash directive (`/// <reference lib="es2023.intl" />`) counts
+    // only above the first statement, so a snippet that opens with one gets
+    // the import after its code instead: an import is hoisted wherever it is.
+    const directive = TRIPLE_SLASH.test(snippet.code)
+    writeFileSync(
+      modulePath,
+      directive ? snippet.code + "\n" + prelude : prelude + snippet.code + "\n"
+    )
+    snippet.offset = prelude === "" || directive ? 0 : 1
+    byModule.set(modulePath, snippet)
+  }
+  return byModule
+}
+
+/**
+ * Compiles the snippets in one program and returns its diagnostics, each
+ * mapped back to the Markdown line it came from.
+ *
+ * This drives the compiler API rather than `tsc`: `tsc` reports no type errors
+ * at all while any file has a syntax error, so one malformed snippet would
+ * hide every other failure. Here a snippet with a syntax error reports only
+ * those, and every other snippet is still checked.
+ */
+function compile(project, byModule) {
+  const { options, errors } = ts.convertCompilerOptionsFromJson(
+    COMPILER_OPTIONS,
+    project
+  )
+  if (errors.length > 0) {
+    throw new Error(
+      ts.flattenDiagnosticMessageText(errors[0].messageText, "\n")
+    )
+  }
+  const host = ts.createCompilerHost(options)
+  // `types` and the other lookups a program without a tsconfig makes start
+  // from the current directory; make that the project, wherever this runs.
+  host.getCurrentDirectory = () => project
+  const cache = ts.createModuleResolutionCache(project, (name) => name, options)
+  const snippetModule = (fileName) => ({
+    resolvedModule: {
+      resolvedFileName: fileName,
+      extension: fileName.endsWith(".tsx") ? ts.Extension.Tsx : ts.Extension.Ts,
+      isExternalLibraryImport: false,
+    },
+  })
+  host.resolveModuleNameLiterals = (
+    literals,
+    containingFile,
+    redirectedReference,
+    compilerOptions,
+    containingSourceFile
+  ) =>
+    literals.map((literal) => {
+      const snippet = byModule.get(containingFile)
+      const resolved = ts.resolveModuleName(
+        literal.text,
+        containingFile,
+        compilerOptions,
+        host,
+        cache,
+        redirectedReference,
+        ts.getModeForUsageLocation(
+          containingSourceFile,
+          literal,
+          compilerOptions
+        )
+      )
+      if (
+        resolved.resolvedModule ||
+        !snippet ||
+        !(literal.text.startsWith(".") || isAppAlias(literal.text))
+      ) {
+        return resolved
+      }
+      const shown = findPageModule(byModule, snippet, literal.text)
+      if (shown) return snippetModule(shown)
+      const fixture = findFixture(project, snippet.context, literal.text)
+      return fixture ? snippetModule(fixture) : resolved
+    })
+
+  const program = ts.createProgram({
+    rootNames: [join(project, "fixtures", "ambient.d.ts"), ...byModule.keys()],
+    options,
+    host,
+  })
+
+  const found = [
+    ...program.getOptionsDiagnostics(),
+    ...program.getGlobalDiagnostics(),
+  ]
+  for (const sourceFile of program.getSourceFiles()) {
+    if (!sourceFile.fileName.startsWith(toPosix(project) + "/")) continue
+    if (sourceFile.fileName.includes("/node_modules/")) continue
+    const syntactic = program.getSyntacticDiagnostics(sourceFile)
+    found.push(
+      ...(syntactic.length > 0
+        ? syntactic
+        : program.getSemanticDiagnostics(sourceFile))
+    )
+  }
+
+  return found.map((diagnostic) => {
+    const message = ts.flattenDiagnosticMessageText(
+      diagnostic.messageText,
+      "\n    "
+    )
+    const code = `TS${diagnostic.code}`
+    if (!diagnostic.file || diagnostic.start === undefined) {
+      return { snippet: undefined, where: "", code, message }
+    }
+    const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(
+      diagnostic.start
+    )
+    const snippet = byModule.get(diagnostic.file.fileName)
+    if (!snippet) {
+      const file = toPosix(relative(project, diagnostic.file.fileName))
+      return {
+        snippet: undefined,
+        where: `${file.replace(/^fixtures\//, "scripts/check-snippets/")}:${line + 1}:${character + 1}`,
+        code,
+        message,
+      }
+    }
+    // An error on the added import line names a global the snippet shadows
+    // or misuses; report it on the snippet's first line.
+    const row = Math.max(line - snippet.offset, 0)
+    return {
+      snippet,
+      where: `${snippet.file}:${snippet.line + row}:${character + 1}`,
+      code,
+      message,
+    }
+  })
+}
+
+// ── Hooks outside a component ────────────────────────────────────────────────
+
+/** The name a function is declared or assigned under, if it has one. */
+function functionName(node) {
+  if (node.name && ts.isIdentifier(node.name)) return node.name.text
+  const parent = node.parent
+  if (
+    parent &&
+    ts.isVariableDeclaration(parent) &&
+    ts.isIdentifier(parent.name)
+  )
+    return parent.name.text
+  if (parent && ts.isPropertyAssignment(parent) && ts.isIdentifier(parent.name))
+    return parent.name.text
+  return undefined
+}
+
+/**
+ * What surrounds a hook call: `"ok"` inside a component (a function named with
+ * a capital) or a custom hook (`useXxx`), or inside an anonymous callback of
+ * some call (`renderHook(() => useX())`, `memo(() => ...)`), which can be
+ * either; `"outside"` with no function at all; `"helper"` in a class or in a
+ * function named otherwise (`handleClick`, `load`), where React throws.
+ */
+function hookContext(call) {
+  let anonymousCallback = false
+  for (let node = call.parent; node; node = node.parent) {
+    if (ts.isClassLike(node)) return "helper"
+    if (!ts.isFunctionLike(node)) continue
+    const name = functionName(node)
+    if (name !== undefined) {
+      return /^[A-Z]/.test(name) || /^use[A-Z]/.test(name) ? "ok" : "helper"
+    }
+    if (node.parent && ts.isCallExpression(node.parent))
+      anonymousCallback = true
+  }
+  return anonymousCallback ? "ok" : "outside"
+}
+
+/**
+ * A call of a hook (`useXxx(...)` or `something.useXxx(...)`) outside a
+ * component or a custom hook, reported as a diagnostic of its snippet.
+ * TypeScript accepts one, and React throws when it runs.
+ */
+function hookDiagnostics(byModule) {
+  const found = []
+  for (const snippet of byModule.values()) {
+    const extension = LANGUAGES[snippet.lang]
+    const source = ts.createSourceFile(
+      `snippet${extension}`,
+      snippet.code,
+      ts.ScriptTarget.Latest,
+      true,
+      extension === ".tsx" ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+    )
+    const visit = (node) => {
+      if (ts.isCallExpression(node)) {
+        const callee = node.expression
+        const name = ts.isIdentifier(callee)
+          ? callee.text
+          : ts.isPropertyAccessExpression(callee)
+            ? callee.name.text
+            : ""
+        if (/^use[A-Z]/.test(name)) {
+          const context = hookContext(node)
+          if (context !== "ok") {
+            const { line, character } = source.getLineAndCharacterOfPosition(
+              node.getStart(source)
+            )
+            found.push({
+              snippet,
+              where: `${snippet.file}:${snippet.line + line}:${character + 1}`,
+              code: "hooks",
+              message: `\`${name}\` is a React hook, called ${context === "outside" ? "outside any function" : "in a helper or a class, which is neither a component (capitalised) nor a custom hook (useXxx)"}. Call it from a component or a custom hook.`,
+            })
+          }
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(source)
+  }
+  return found
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+const matches = (file) =>
+  filters.length === 0 || filters.some((filter) => file.includes(filter))
+const snippets = [
+  ...collectSnippets(gatedFiles().filter(matches), false),
+  ...(includeDocs ? collectSnippets(docsFiles().filter(matches), true) : []),
+]
+
+// Its real path: TypeScript names the files it reads by theirs, and a
+// temporary directory can sit behind a symlink (/var -> /private/var on macOS).
+const project = realpathSync(
+  mkdtempSync(join(tmpdir(), "ic-reactor-snippets-"))
+)
+let links = []
+let exitCode = 1
+try {
+  links = linkPackages(project)
+  cpSync(fixturesDir, join(project, "fixtures"), { recursive: true })
+  const byModule = writeSnippets(
+    project,
+    snippets.filter((snippet) => !snippet.skipped)
+  )
+  const diagnostics = [
+    ...compile(project, byModule),
+    ...hookDiagnostics(byModule),
+  ]
+
+  const failed = new Set(diagnostics.map((d) => d.snippet).filter(Boolean))
+  const fixtureErrors = diagnostics.filter((d) => !d.snippet)
+
+  if (verbose) {
+    for (const snippet of snippets) {
+      const state = snippet.skipped
+        ? "skip"
+        : failed.has(snippet)
+          ? "FAIL"
+          : "ok  "
+      // The line of the opening fence
+      console.log(`${state} ${snippet.file}:${snippet.line - 1}`)
+    }
+    console.log("")
+  }
+  for (const { snippet, where, code, message } of diagnostics) {
+    console.log(`${where ? `${where} ` : ""}${code}: ${message}`)
+  }
+  if (diagnostics.length > 0) console.log("")
+
+  const report = (label, list) => {
+    const failures = list.filter((s) => failed.has(s)).length
+    const skipped = list.filter((s) => s.skipped).length
+    console.log(
+      `${label}: ${list.length - skipped} checked (${list.length - skipped - failures} passed, ${failures} failed), ${skipped} skipped`
+    )
+    return failures
+  }
+  let gatedFailures = report(
+    "Guides, skills and READMEs",
+    snippets.filter((s) => !s.docs)
+  )
+  if (includeDocs) {
+    gatedFailures += report(
+      "Docs pages",
+      snippets.filter((s) => s.docs)
+    )
+  }
+
+  if (fixtureErrors.length > 0) {
+    console.error(
+      "✖ The snippets' app in scripts/check-snippets/ does not compile."
+    )
+  } else if (gatedFailures > 0) {
+    console.error(
+      "✖ Fix each failing snippet in its file. Only a name the snippet's app would define belongs in scripts/check-snippets/ (a docs page's in scripts/check-snippets/docs/<section>/); a deliberate fragment is marked ```ts nocheck."
+    )
+  } else {
+    exitCode = 0
+    console.log("✔ Every checked snippet compiles")
+  }
+} catch (error) {
+  console.error(`✖ ${error.stack ?? error.message}`)
+} finally {
+  if (keep) {
+    console.log(`  project kept at ${project}`)
+  } else {
+    for (const link of links) unlinkSync(link)
+    rmSync(project, { recursive: true, force: true })
+  }
+}
+// Not process.exit(): it can cut off output still being written to a pipe.
+process.exitCode = exitCode