Skip to content

Add snippet-check: compile-check docs code snippets - #9256

Draft
vladaskorohodova wants to merge 2 commits into
DevExpress:mainfrom
vladaskorohodova:snippet-check
Draft

vladaskorohodova wants to merge 2 commits into
DevExpress:mainfrom
vladaskorohodova:snippet-check

Conversation

@vladaskorohodova

@vladaskorohodova vladaskorohodova commented Oct 19, 2026 •

Copy link
Copy Markdown
Collaborator

Why

Code snippets in the articles have no automated check. Typos and invalid code reach the published docs, and the React function-component migration produces many new snippets to review by hand.

What this adds

A tool that compiles the jQuery, Angular, Vue, and React snippets in the markdown articles against pinned DevExtreme packages.

Framework Compiler Checked
React tsc TS/JSX types; JS tabs: syntax only
Vue vue-tsc SFC template and script types; JS blocks: syntax only
Angular ngc (strict templates) TS types and template bindings
jQuery tsc + @types/jquery + DevExtreme jQuery typings TS tabs fully; JS tabs: syntax only

ASP.NET MVC and Core snippets are not checked.

npm run snippet-check:setup                      # once
npm run check-snippets -- "<article or folder>"
npm run check-snippets -- --changed --framework react
npm run test-snippet-check

Errors point at the markdown file:line. Running the whole docs tree (about 8,700 snippets) takes under a minute. The README in tools/snippet-check/ has the full options.

Where to look

  • src/extract.ts finds snippets by framework heading and <!-- tab: ... --> markers. Tabs of one group stay together, and alternative variants (for example Options API and Composition API) are split.
  • src/resolve.ts is the most important file to review. Articles show incomplete code, so it normalizes snippets before compiling: it fills {WidgetName} placeholders from the article path, replaces ... elisions with valid code, and fixes a few doc conventions. It never changes line counts, so error locations stay accurate.
  • src/adapters/ holds one small adapter per compiler.
  • playground/ has the pinned dependencies, a lock file, and globals.d.ts for sample names such as employees.
  • config.json holds the ignore rules. Each rule has a reason.
  • .github/skills/check-snippets/SKILL.md is a skill so an agent can run the same flow.

Reliability

  • If a compiler crashes, or reports an error outside a snippet, the tool stops with that output. It never reports a pass in that case.
  • Unused imports are warnings only. Other unused code is not reported, because snippets elide the code that would use it.
  • npm run test-snippet-check runs 12 tests, including real compiles of one valid and one deliberately broken fixture article for all four frameworks.

Limitations

  • A pass means the snippet compiles. It does not mean the snippet does what the article says, and nothing is run.
  • The playground pins the latest published DevExtreme (26.1.5). APIs that are new in 26.2 fail with "no exported member" until matching packages are published and the pin is updated. For example, the Fluent Next themes.mode and refreshMode articles fail for this reason.
  • Snippets are skipped, with a reason, when an article has no code tab for a framework or uses {WidgetName} with an unknown widget.

Not in scope

  • A CI job. Compiling every snippet would flag existing failures. I would add --changed as a CI check in a follow-up, once the existing failures are fixed or baselined.

How to test

npm run snippet-check:setup
npm run test-snippet-check
npm run check-snippets -- "concepts/05 UI Components/TreeList"

### Why

Code snippets in the articles have no automated check. Typos and invalid code reach the published docs, and the React function-component migration produces many new snippets to review by hand.

### What this adds

A tool that compiles the jQuery, Angular, Vue, and React snippets in the markdown articles against pinned DevExtreme packages.

| Framework | Compiler | Checked |
|---|---|---|
| React | `tsc` | TS/JSX types; JS tabs: syntax only |
| Vue | `vue-tsc` | SFC template and script types; JS blocks: syntax only |
| Angular | `ngc` (strict templates) | TS types and template bindings |
| jQuery | `tsc` + `@types/jquery` + DevExtreme jQuery typings | TS tabs fully; JS tabs: syntax only |

ASP.NET MVC and Core snippets are not checked.

```console
npm run snippet-check:setup                      # once
npm run check-snippets -- "<article or folder>"
npm run check-snippets -- --changed --framework react
npm run test-snippet-check
```

Errors point at the markdown `file:line`. Running the whole docs tree (about 8,700 snippets) takes under a minute. The README in `tools/snippet-check/` has the full options.

### Where to look

- `src/extract.ts` finds snippets by framework heading and `<!-- tab: ... -->` markers. Tabs of one group stay together, and alternative variants (for example Options API and Composition API) are split.
- `src/resolve.ts` is the most important file to review. Articles show incomplete code, so it normalizes snippets before compiling: it fills `{WidgetName}` placeholders from the article path, replaces `...` elisions with valid code, and fixes a few doc conventions. It never changes line counts, so error locations stay accurate.
- `src/adapters/` holds one small adapter per compiler.
- `playground/` has the pinned dependencies, a lock file, and `globals.d.ts` for sample names such as `employees`.
- `config.json` holds the ignore rules. Each rule has a reason.
- `.github/skills/check-snippets/SKILL.md` is a skill so an agent can run the same flow.

### Reliability

- If a compiler crashes, or reports an error outside a snippet, the tool stops with that output. It never reports a pass in that case.
- Unused imports are warnings only. Other unused code is not reported, because snippets elide the code that would use it.
- `npm run test-snippet-check` runs 12 tests, including real compiles of one valid and one deliberately broken fixture article for all four frameworks.

### Limitations

- A pass means the snippet compiles. It does not mean the snippet does what the article says, and nothing is run.
- The playground pins the latest published DevExtreme (26.1.5). APIs that are new in 26.2 fail with "no exported member" until matching packages are published and the pin is updated. For example, the Fluent Next `themes.mode` and `refreshMode` articles fail for this reason.
- Snippets are skipped, with a reason, when an article has no code tab for a framework or uses `{WidgetName}` with an unknown widget.

### Not in scope

- A CI job. Compiling every snippet would flag existing failures. I would add `--changed` as a CI check in a follow-up, once the existing failures are fixed or baselined.

### How to test

```console
npm run snippet-check:setup
npm run test-snippet-check
npm run check-snippets -- "concepts/05 UI Components/TreeList"
```
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant