Repository navigation
Add snippet-check: compile-check docs code snippets - #9256
Draft
vladaskorohodova wants to merge 2 commits into
Draft
vladaskorohodova wants to merge 2 commits into
vladaskorohodova wants to merge 2 commits into
Conversation
### 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"
```
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
tscvue-tscngc(strict templates)tsc+@types/jquery+ DevExtreme jQuery typingsASP.NET MVC and Core snippets are not checked.
Errors point at the markdown
file:line. Running the whole docs tree (about 8,700 snippets) takes under a minute. The README intools/snippet-check/has the full options.Where to look
src/extract.tsfinds 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.tsis 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, andglobals.d.tsfor sample names such asemployees.config.jsonholds the ignore rules. Each rule has a reason..github/skills/check-snippets/SKILL.mdis a skill so an agent can run the same flow.Reliability
npm run test-snippet-checkruns 12 tests, including real compiles of one valid and one deliberately broken fixture article for all four frameworks.Limitations
themes.modeandrefreshModearticles fail for this reason.{WidgetName}with an unknown widget.Not in scope
--changedas a CI check in a follow-up, once the existing failures are fixed or baselined.How to test