alemtuzlak/kiira

Kiira is a tool that checks whether the TypeScript and JavaScript code examples in your Markdown documentation files actually work against your real project. When documentation is written or updated, it is easy for code snippets to fall out of sync with the actual API: imports that no longer exist, function names that changed, or options that were removed. Kiira extracts every code block from your Markdown files, runs them through TypeScript's type checker using your project's real type definitions, and reports any errors back on the exact line where the broken code block appears. The tool has three interfaces. A command-line tool called kiira check scans your documentation files and prints type errors. A Visual Studio Code extension shows error squiggles directly inside Markdown files as you write them, the same way errors appear in regular code files. A GitHub Actions composite action lets you run the same checks automatically in a continuous integration pipeline, with output formatted as GitHub annotations. For code examples that span multiple fences (for instance, a tutorial that declares a variable in one block and uses it in the next), you can tag related snippets with a shared group identifier so Kiira treats them as a single module. Kiira can also detect when ungrouped snippets would resolve each other's errors and suggest the grouping for you, with a flag to write the tags automatically. In monorepos with multiple packages, Kiira discovers the workspace structure from pnpm, npm, or yarn configuration and maps internal package names to their source locations automatically. This means documentation that imports from your own packages resolves without manually configuring path aliases. Per-file configuration overrides let you specify different JSX runtimes for documentation covering multiple frontend frameworks. If a code block is tagged as ts but actually contains JSX syntax, Kiira detects the mismatch, still type-checks it correctly, and can rewrite the tag with the fix flag. Setup requires installing the kiira npm package, creating a TypeScript configuration file pointing at your documentation, and optionally adding a Kiira configuration file to specify which files to include and how to resolve packages.