Skip to content

chore(lint): check the code samples on the pages a PR changes - #2623

Merged
bruno-andrade-azion merged 3 commits into
mainfrom
chore/mm-16258-code-block-lint
Nov 16, 2026
Merged

bruno-andrade-azion merged 3 commits into
mainfrom
chore/mm-16258-code-block-lint

Conversation

@bruno-andrade-azion

@bruno-andrade-azion bruno-andrade-azion commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

What & why

Related issue: MM-16258
Pages affected: none. This PR adds tooling (apps/docs/scripts/lint-codeblocks.mjs, .github/workflows/code-blocks.yml, the lint:codeblocks scripts) and documents it in AGENTS.md, .github/CONTRIBUTING.md and .github/GOVERNANCE.md.

The October docs review found samples that readers cannot paste. Seven Marketplace integration guides had Arguments JSON with trailing commas, // comments and keys missing a closing quote. An API body sent "service_id": :id, and two JSON responses never closed their braces. Checking that the samples parse would have caught all of those before review.

What the lint checks. pnpm lint:codeblocks [files] parses every json block, checks JavaScript and TypeScript blocks for syntax errors (with the TypeScript parser, no type checking), and parses the JSON body of a curl --data in bash/sh blocks. Shell quoting is read the way the shell reads it, so '\'' and '"'"' are handled. A body that expands a variable is skipped. A path that is not a .md or .mdx file, such as a mistyped one, exits 2 instead of checking nothing and passing, as lint:changelog does.

Some conventions are deliberate, and the lint accepts them:

  • a bare <placeholder>;
  • ... or … elisions;
  • member fragments without their braces, or the body of a class or interface;
  • diff in the fence meta, where each side is checked;
  • jsonc and jsonl blocks.

A block that is partial on purpose opts out with nolint in its fence meta. JSON errors point at the exact line, through a small validator, because V8 gives no position for an unexpected token. The contributor docs list the conventions.

How it runs. A new Code blocks workflow runs the script on every PR, over the .md/.mdx pages under apps/docs/src/{content,includes} that the PR changes. A PR that changes the script or the workflow itself checks every page instead, as the Changelog entries workflow does, so a change to the lint is always run in CI. It annotates each finding on its line and writes a table to the run Summary. A manual run (workflow_dispatch) checks every page.

The workflow is advisory on purpose. A finding turns the check red, but it is not a required status check (the ruleset on main requires only Design system adoption), so the PR author decides whether to fix the sample. It also stays out of the CI gate, whose workflow, scripts and baselines this PR does not touch.

What it finds today. On main (0d8178e94) it reports 16 findings in 12 of 2,298 files, 8 in each language:

  • unclosed JSON in the user session timeout guide (two blocks);
  • a trailing comma in the account lockout unlock guide;
  • an error log tagged json in the Send Event Endpoint integration guide;
  • JSON Lines tagged json in the Data Stream payload page;
  • two alternative response bodies in one json block in the AI Inference troubleshooting reference;
  • bare handler signatures in the Runtime handlers reference (two blocks).

That is why the Code blocks check is red on this PR: it changes the script, so it checks every page and reports those 16. Fixing them is content work, so it goes in a separate PR, not this one.

Rebased onto main. The Changelog entries PR added lint:changelog on the same lines of both package.json files, AGENTS.md, CONTRIBUTING.md and GOVERNANCE.md. Each conflict keeps both sides, the changelog lines first. In GOVERNANCE.md, "it is not one of the three" became "it is not a ratchet", the wording of the Changelog entries paragraph that now sits before it.

How I checked it

  • A fixture of 20 cases, valid and invalid: every invalid case was flagged at the right line, and no valid one was. A second fixture of 16 edge cases after the rebase (placeholders, elisions, fragments, \" and '\'' quoting, # inside quotes, --data @file) agreed.
  • The JSON validator agrees with JSON.parse on 3,428 JSON texts from the corpus and on 5,080 random one-character mutations.
  • On the tree as reviewed on 2026-10-29, it flags 6 of the 7 Marketplace guides; the reCAPTCHA defect is structural, valid JSON. It also flags the run-scripts body at line 254. These are the lines the review reported.
  • A full run on main takes about 22 seconds locally.
  • I ran the changed-page step against three diffs: this PR gives count=all, a page-only PR (fix(opennext): migrate the OpenNext guide to the v4 azion.config.js format #2651) gives count=2, and a PR without pages (chore(lint): accept the use-case closing in lint-links #2632) takes the "no page changed" path.
  • The workflow ran on this PR after the rebase (run 43922828699): it checked every page and reported the same 16 findings. Every other check passed.
  • A mistyped path exits 2 with <path> is not a .md or .mdx file.
  • eslint --max-warnings 0 and prettier --check pass on the changed files.
  • A fence with nolint in its meta, rendered through @astrojs/markdown-remark, has no trace of the meta in the HTML.
  • pnpm build:local passed before the rebase. I did not run it again after the rebase; the CI Build job passed on the rebased head.

Not verified: the per-page path (a PR that changes pages but not the script) has not run on GitHub; it was simulated locally only. workflow_dispatch only becomes available once the file is on main.

Type of change

  • 🆕 New content (feat)
  • 🩹 Fix (fix) — typo, broken link, wrong information
  • ♻️ Content update (docs) — rewrite, expansion, upkeep
  • 🌐 Translation sync (i18n)
  • 🏗️ Platform / structure (refactor / chore) — reviewed by UXE, no content mixed in

Author checklist

  • PR title follows type(scope): summary (see GOVERNANCE.md §4)
  • Frontmatter complete: title, description, meta_tags, namespace, permalink, last_reviewed — no page is added or changed
  • No legacy "edge-" product names in the copy
  • How-to/tutorial content includes at least one runnable, copy-paste-tested code block — no how-to or tutorial is changed
  • Screenshots (if any) have alt text and follow image standards — no screenshot is added or changed
  • Internal links are relative and resolve locally — the one link added, in AGENTS.md, points to .github/CONTRIBUTING.md#code-samples
  • If any permalink changed or page moved: redirect added in this PR — no permalink changed and no page moved
  • i18n: pt-br updated in this PR or follow-up i18n issue created: — no page text changed; the lint covers en and pt-br pages alike
  • I ran pnpm build:local (build + frontmatter check) without errors — it passed before the rebase onto main; not rerun since, though the CI Build job passed on the rebased head

Add `pnpm lint:codeblocks`, which parses the code samples in the docs: a
json block must be JSON, a JavaScript or TypeScript block must be free of
syntax errors, and the JSON body of a curl --data in a shell block must
parse. It reads the conventions the docs use on purpose (bare
<placeholder> values, ... and … elisions, member fragments, diff in the
fence meta, jsonc, jsonl) and lets a partial block opt out with nolint.

A new Code blocks workflow runs it over the pages each PR changes and
annotates every finding on its line. It is advisory: it turns red but is
not a required check and sits outside the CI gate, so the PR author
decides whether to fix the sample.
A PR that changes lint-codeblocks.mjs or its workflow changes no page, so it
took the "no page changed" path and the script never ran in CI. It now checks
every page, as the Changelog entries workflow does. A mistyped path passed to
the script now exits 2 instead of checking nothing and passing.
@bruno-andrade-azion
bruno-andrade-azion force-pushed the chore/mm-16258-code-block-lint branch from 7426af0 to d59bdbd Compare November 16, 2026 17:51
… parses

A bare <placeholder> is accepted in json blocks and curl bodies only; in
JavaScript and TypeScript it goes inside a string. A method signature alone
parses with an elided body. Aligns the lint:codeblocks line with the other
commands in CONTRIBUTING.
@bruno-andrade-azion
bruno-andrade-azion merged commit 9944681 into main Nov 16, 2026
9 of 10 checks passed
@bruno-andrade-azion
bruno-andrade-azion deleted the chore/mm-16258-code-block-lint branch November 16, 2026 19:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants