doc-check 🚦

Turn Your README Code Examples Into Real Tests

A Project by SILICON VALLEY GLOBAL PH INC

doc-check extracts and executes code examples in your README and markdown documentation as live assertions, failing your build if they no longer work.

⚠️ The Problem

Documentation code snippets rot silently. You refactor a function, rename a parameter, or change a return shape, and nothing forces the README to keep up — nobody re-runs docs by hand. Months later a new user copy-pastes the example, it breaks, and they assume the package is broken. Rust bakes doc-testing into cargo test; JS has nothing comparably popular. doc-check treats every runnable snippet in your markdown as a live assertion instead of dead text.

🧩 Key Architecture Pillars

Snippet Extraction (src/scan/extract.ts)

Walks markdown files and extracts fenced code blocks tagged for testing (e.g. ```js doctest or ```ts doctest), preserving language tag, line numbers, annotations (skip, expect-error), and inline expected-output comments (// =>).

Snippet Execution (src/run/executor.ts)

Runs each snippet in an isolated Node.js context with the package under test available, capturing console output and return values. Exposes a pluggable SnippetExecutor interface for adding additional language executors.

Output Assertion (src/compare/assert.ts)

Compares actual console output and return values against // => expectation comments or expect-error tags, reporting detailed diffs on mismatch.

Gate Enforcement (src/cli/index.ts)

Command-line interface that scans markdown files and exits with a non-zero status code if any doc snippet fails, serving as a gate for CI or pre-commit/pre-publish hooks.

Fail-Safe Annotations (src/config/annotate.ts)

Supports skip and expect-error tags on code blocks so intentionally partial, illustrative, or error-demonstrating snippets don't produce false failures, logging skipped blocks and reasons in the summary report.

📊 Supported Languages

| Language | Executor | Status | | :--- | :--- | :--- | | JavaScript / TypeScript | Node.js Executor (src/run/executor.ts) | Supported (v1.0) | | Python | Python Executor | Planned | | Others | Pluggable Executors | Planned — contributions welcome |

📦 Installation

npm install @siliconvalleyglobal/doc-check

💻 Usage Example

1. Tag a Code Block in your README.md

Add doctest to the code fence and use // => for expected output:

```js doctest
const greeting = "Hello, World!";
console.log(greeting);
// => Hello, World!
```

For error-demonstrating snippets, use expect-error:

```js doctest expect-error
throw new Error("Invalid configuration");
```

To skip illustrative snippets:

```js doctest skip
// Illustrative snippet skipped during doc-check run
```

2. Run doc-check CLI

npx doc-check README.md

doc-check will execute the snippet, compare output, and exit with status code 1 if assertions fail.

📄 License

Distributed under the MIT License. See LICENSE for more information.

Copyright (c) 2026 SILICON VALLEY GLOBAL PH INC.