Automated Code Example Check

[Aryex]

Overview

Valkey GLIDE documentations contains a lot of code examples, and we expects more to be added. We need an automated solution which allow us to effectively check if each code examples are correct.

Core Idea

In the documentation, code snippets are always wrapped around Markdown code fences. We can extract these code fences into a physical code file and compile them against real Valkey GLIDE client library. This allows us to catch syntax errors, wrong method names, incorrect signatures, missing exports, and more.

From the writer POV, each example should be self-contained. The idea is a users can copy a snippet and run it. To help keep code examples concise, they could also:

• Omit the import and the validator will inject necessary imports during checks. This should only be done when the imports are obvious.
• Omit client and clusterClient definition. Other variable definition should be defined.

Example Checking Step

1. Build GLIDE client from source and install it.
2. Run a script to extract code examples from documentations into a JSON dict.
3. Start validating; Prepare a temp project referencing the built GLIDE client.
4. For each snippet, create a separate code file:
   • Inject ALL imports.
   • Inject client definitions.
   • Prepare other language specifics.
   • Wrap code example in a runnable unit.
5. Compile.
6. Collect errors and report.

On Building GLIDE clients

We expects GLIDE clients to be built and passed to the validator. This keeps it simple. CI checks should always compare against latest changes.

On Imports Injections

The validator should always do an "Import ALL". However, specific language compilers may complain about duplicated import and we would need to handle.

On Client Injections

We only inject client definitions for client and clusterClient. Other variables must be declared by each example to keep them self contained.

The validator is self-contained

The validator script is written in Python. It generate the temp project at runtime and cleaned up automatically. No physical project files are maintained.

The following are validator options:

• --glide-path: Path to the built GLIDE client (required).
• --keep-project: Preserve temp directory for inspection.

Passing Examples

// ✅ Self-contained: declares its own variables
const key = "user:1000";
await client.set(key, "john_doe");
const result = await client.get(key);
console.log(result); // "john_doe"

// ✅ Has its own import, declares everything it needs
import { Script } from "@valkey/valkey-glide";

const script = new Script("return redis.call('GET', KEYS[1])");
const result = await client.invokeScript(script, { keys: ["mykey"] });
console.log(result);

// ✅ Full self-contained example with client creation
import { GlideClient } from "@valkey/valkey-glide";

const client = await GlideClient.createClient({
    addresses: [{ host: "localhost", port: 6379 }],
});
await client.set("key", "value");
client.close();

Failing Examples

// ❌ 'key' is not declared
await client.set(key, "value");

// ❌ 'script' is not declared — references a previous step
const result = await client.invokeScript(script, { keys: ["mykey"] });

// ❌ Wrong method name (should be 'setrange')
await client.setRange("key", 0, "Hello");

// ❌ Imports a non-existent export
import { GlideClientOptions } from "@valkey/valkey-glide";

Adapting to a New Language

1. Define the extraction regex for that language's fenced blocks.
2. Define the wrapping logic (import hoisting, body wrapper, client declarations).
3. Define the project setup (package manager install, compiler config).
4. Define the error parser (regex matching compiler output format).
5. Decide the default imports list and client declarations appropriate for that language's API.

[harish18092002]

#243