Skip to content

build: migrate Markdown code-block linting to ESLint flat config - #14668

Open
Planeshifter wants to merge 5 commits into
developfrom
philipp/fix-markdown-lint-eslint-flat-config
Open

build: migrate Markdown code-block linting to ESLint flat config#14668
Planeshifter wants to merge 5 commits into
developfrom
philipp/fix-markdown-lint-eslint-flat-config

Conversation

@Planeshifter

@Planeshifter Planeshifter commented Aug 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Resolves stdlib-js/metr-issue-tracker#1223.

Description

What is the purpose of this pull request?

This pull request:

  • migrates Markdown code-block linting to ESLint "flat" configuration, unblocking the ESLint v9 upgrade (build: upgrade ESLint core to v9 (gh54 part VI) #10972). Works on both v8 (via FlatESLint) and v9 (default ESLint class); the removed useEslintrc option is no longer used.
  • adds etc/eslint/eslint.flat.config.markdown.js, which extends the root flat config with the Markdown rule overrides from .eslintrc.markdown.js (the legacy file is left in place until nothing depends on it).
  • lints code blocks in the context of the containing Markdown file (via lintText()'s filePath), with companion updates so readme-driven development leniency and doctest evaluation continue to work under .md file paths.
  • annotates this package's self-referential README/example code (which runs the linter within the linter and deadlocks when executed by the stdlib/doctest rule or the example runner) so it is neither executed nor doctested; both remain runnable standalone.

Verified byte-identical lint output between the legacy and new configurations on fixtures with deliberate errors (including doctests and inline <!-- eslint ... --> comments), and that errors in READMEs under lib/node_modules are still detected (flat-config ESLint ignores node_modules by default; an unignore pattern in the config handles this). Implementation notes and pitfalls (e.g., ignore: false disabling unignore patterns) are documented in the config and commit messages.

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

#10972 has been rebased on top of this PR and should land after it.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

  • Yes
  • No

If you answered "yes" above, how did you use AI assistance?

  • Code generation (e.g., when writing an implementation or fixing a bug)
  • Test/benchmark generation
  • Documentation (including examples)
  • Research and understanding

Disclosure

This PR was written primarily by Claude Code, including root-cause investigation, implementation, and verification, under human direction and review.

@stdlib-js/reviewers

@Planeshifter
build: migrate Markdown code-block linting to ESLint flat config
b88c746 
Ref: stdlib-js/metr-issue-tracker#1223
@Planeshifter
build: lint Markdown code blocks in the context of the containing file
aabd378 
Ref: stdlib-js/metr-issue-tracker#1223

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown_pkg_readmes
    status: na
  - task: lint_markdown_docs
    status: na
  - task: lint_markdown
    status: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---
@Planeshifter
build: skip linting and running self-referential README example
9cf54ff 
Executing the example would run the linter within the linter and
deadlock, which caused the "Run changed examples" CI job to time out.

Ref: stdlib-js/metr-issue-tracker#1223

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown_pkg_readmes
    status: passed
  - task: lint_markdown_docs
    status: na
  - task: lint_markdown
    status: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: na
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---
@Planeshifter
build: disable doctest rule for self-referential example
7ae9555 
Executing the example via the `stdlib/doctest` rule would run the
linter within the linter and deadlock, which caused the "Lint Changed
Files" CI job to time out.

Ref: stdlib-js/metr-issue-tracker#1223

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown_pkg_readmes
    status: na
  - task: lint_markdown_docs
    status: na
  - task: lint_markdown
    status: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: na
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: passed
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---
@Planeshifter
build: support Markdown file paths in doctest and lint rules
759dfa3 
Now that Markdown code blocks are linted using the path of the
containing file, rules which special-cased anonymous (`<text>`) input
to tolerate not-yet-implemented packages (readme-driven development)
must apply the same leniency to Markdown file paths. Also share the
host realm's error constructors with the doctest sandbox so that
`instanceof` checks on host-created errors succeed.

Ref: stdlib-js/metr-issue-tracker#1223
Co-authored-by: Athan Reines <kgryte@gmail.com>

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown_pkg_readmes
    status: na
  - task: lint_markdown_docs
    status: na
  - task: lint_markdown
    status: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---
@Planeshifter Planeshifter mentioned this pull request Aug 26, 2026
Open
7 tasks
@Planeshifter
Planeshifter requested a review from kgryte August 27, 2026 01:50
@stdlib-bot stdlib-bot added the Needs Review A pull request which needs code review. label Aug 27, 2026
@Planeshifter
Planeshifter marked this pull request as ready for review August 27, 2026 06:13
@Planeshifter
Planeshifter requested a review from a team August 27, 2026 06:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kgryte kgryte Awaiting requested review from kgryte

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

Needs Review A pull request which needs code review.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[BUG]: Fix broken Markdown linting due the ongoing ESLint v9 migration

2 participants

@Planeshifter @stdlib-bot