docs: add plugin file scoping (includes) documentation#3993
docs: add plugin file scoping (includes) documentation#3993chocky335 wants to merge 8 commits intobiomejs:nextfrom
Conversation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
✅ Deploy Preview for biomejs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughDocumentation was expanded to add file-scoping for linter plugins and to document plugin configuration. The linter plugins page now explains Possibly related PRs
🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/content/docs/linter/plugins.mdx (1)
61-75:⚠️ Potential issue | 🟡 MinorThe "For example:" doesn't illustrate file scoping.
The shell block that follows (lines 63–75) is the generic
Object.assigndiagnostic from the introduction — it doesn't demonstrateincludes/excludesin action. Placing it right after the file-scoping explanation with "For example:" implies it does, which will leave readers scratching their heads.Either replace the example with one that actually shows a file being skipped or scoped (e.g., showing that a file in
tests/**produces no output whenexcludes: ["tests/**"]is set), or move this existing block back to its original location without the "For example:" preamble.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/linter/plugins.mdx` around lines 61 - 75, The "For example:" paragraph currently precedes the generic Object.assign diagnostic (the shell block showing resolveConfig(Object.assign(...))) but doesn't illustrate file scoping; either replace that shell block with a concrete file-scoping example that demonstrates includes/excludes (e.g., show a lint run where a file under tests/** produces no output when excludes: ["tests/**"] is set) or move the existing Object.assign diagnostic back to its previous location and remove the "For example:" lead-in so the documentation correctly shows file scoping via the includes/excludes example rather than the generic diagnostic.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/content/docs/linter/plugins.mdx`:
- Line 35: Change the orphaned h3 heading "### File Scoping" to an h2 ("## File
Scoping") so it matches the other top-level headings like "## Target Languages"
and "## Plugin API" and appears correctly in the autogenerated TOC; update the
heading text only (no other content) to preserve structure.
In `@src/content/docs/reference/configuration.mdx`:
- Around line 88-96: Update the documentation for plugins.<ITEM>.includes and
plugins.<ITEM>.excludes to state their default/omission behavior (i.e., if
plugins.<ITEM>.includes is omitted the plugin runs on all files; if
plugins.<ITEM>.excludes is omitted nothing is skipped) and add a link or
cross-reference to the existing "Glob syntax reference" (use the same anchor
used by files.includes/linter.includes) so readers can see the supported glob
patterns; keep wording concise and consistent with other entries in the
document.
---
Outside diff comments:
In `@src/content/docs/linter/plugins.mdx`:
- Around line 61-75: The "For example:" paragraph currently precedes the generic
Object.assign diagnostic (the shell block showing
resolveConfig(Object.assign(...))) but doesn't illustrate file scoping; either
replace that shell block with a concrete file-scoping example that demonstrates
includes/excludes (e.g., show a lint run where a file under tests/** produces no
output when excludes: ["tests/**"] is set) or move the existing Object.assign
diagnostic back to its previous location and remove the "For example:" lead-in
so the documentation correctly shows file scoping via the includes/excludes
example rather than the generic diagnostic.
chocky335
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/content/docs/linter/plugins.mdx (1)
60-74:⚠️ Potential issue | 🟡 MinorThe "For example:" shell block doesn't illustrate file scoping.
The shell output shows the generic Object.assign diagnostic introduced at the very top of the page — it has no visible connection to the
includesconfig just described. The file path/packages/tailwindcss-config-analyzer/src/introspect.tsdoesn't obviously match either of the two example plugin configs above (src/components/**orsrc/**/*.ts), so readers can't infer what "scoping in action" looks like.Either replace it with an example that shows a file being skipped because it doesn't match
includes, or remove it entirely — the JSON snippet above already tells the story.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/linter/plugins.mdx` around lines 60 - 74, The example shell output currently uses /packages/tailwindcss-config-analyzer/src/introspect.ts which doesn't demonstrate the plugin "includes" scoping (e.g., src/components/** or src/**/*.ts); update the shell block under "For example:" to either (a) replace the output with a lint run that shows a file being skipped or not reported because it does not match the includes pattern (so readers see scoping in action), or (b) swap the path to a matching file path that clearly aligns with one of the example include patterns (for instance a file under src/components/**) so the diagnostic reflects the described scope; alternatively remove the shell block entirely if you prefer the JSON snippet to stand alone.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/content/docs/linter/plugins.mdx`:
- Around line 56-58: Update the wording that currently claims "following the
same semantics as .gitignore" to instead state that the plugin `includes` option
uses Biome's own `biome_glob` semantics (reference the `includes` option and
`biome_glob` by name), and replace or remove the `.gitignore` link—preferably
swap it for Biome's glob syntax reference
(https://biomejs.dev/reference/configuration/#glob-syntax) and add a brief note
about negated patterns only working as exceptions to regular globs and requiring
a leading `**` to match files and folders; ensure the sentence about negated
patterns and examples reference `includes`/`biome_glob` rather than gitignore.
---
Outside diff comments:
In `@src/content/docs/linter/plugins.mdx`:
- Around line 60-74: The example shell output currently uses
/packages/tailwindcss-config-analyzer/src/introspect.ts which doesn't
demonstrate the plugin "includes" scoping (e.g., src/components/** or
src/**/*.ts); update the shell block under "For example:" to either (a) replace
the output with a lint run that shows a file being skipped or not reported
because it does not match the includes pattern (so readers see scoping in
action), or (b) swap the path to a matching file path that clearly aligns with
one of the example include patterns (for instance a file under
src/components/**) so the diagnostic reflects the described scope; alternatively
remove the shell block entirely if you prefer the JSON snippet to stand alone.
---
Duplicate comments:
In `@src/content/docs/linter/plugins.mdx`:
- Line 35: The "File Scoping" heading is using an h3 ("### File Scoping") but
should be an h2 to match its sibling sections; update the heading token from
"### File Scoping" to "## File Scoping" so it is a proper sibling of "## Target
Languages" and "## Plugin API" (look for the literal heading text "File Scoping"
in the document and change its leading hashes).
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
src/content/docs/linter/plugins.mdx (1)
49-51: Nit: tighten the negated glob to match the positive pattern's scope.The positive pattern restricts to
src/**/*.ts, but the negation uses!**/*.test.ts(project-wide). The net result is identical since no file outsidesrc/can be selected anyway, but scoping the exclusion to match makes the intent self-documenting.✏️ Suggested tweak
- "includes": ["src/**/*.ts", "!**/*.test.ts"] + "includes": ["src/**/*.ts", "!src/**/*.test.ts"]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/linter/plugins.mdx` around lines 49 - 51, Tighten the negated glob so it matches the positive pattern's scope by replacing the project-wide exclusion "!**/*.test.ts" with a scoped exclusion like "!src/**/*.test.ts" in the plugin config (the JSON object containing "path": "./ts-only-plugin.grit" and "includes": ["src/**/*.ts", ...]); this keeps the intent explicit and ensures the exclusion only applies within the same "src/**/*.ts" pattern.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/content/docs/linter/plugins.mdx`:
- Around line 56-57: The phrase about "matching at least one of the patterns" is
ambiguous when negated globs exist; update the sentence that references the
includes option to state that the plugin runs only on files that match at least
one positive (non‑negated) pattern, and that negated patterns (those beginning
with "!") act as exclusions—files matching a negated pattern are explicitly
excluded rather than included (e.g., "!**/*.test.ts" excludes test files).
Ensure the updated text mentions both positive vs. negated semantics and gives
the "!**/*.test.ts" example for clarity.
---
Nitpick comments:
In `@src/content/docs/linter/plugins.mdx`:
- Around line 49-51: Tighten the negated glob so it matches the positive
pattern's scope by replacing the project-wide exclusion "!**/*.test.ts" with a
scoped exclusion like "!src/**/*.test.ts" in the plugin config (the JSON object
containing "path": "./ts-only-plugin.grit" and "includes": ["src/**/*.ts",
...]); this keeps the intent explicit and ensures the exclusion only applies
within the same "src/**/*.ts" pattern.
src/content/docs/linter/plugins.mdx
Outdated
| By default, a plugin runs on every file the linter processes. If a plugin only | ||
| applies to certain files, you can restrict it using `includes` glob patterns. | ||
| Use negated globs (prefixed with `!`) for exclusions: |
There was a problem hiding this comment.
In our docs, when we provide code examples like here, we follow this pattern, in this order
- explain the feature
- talk about the example in the specifics
- then show the example
In this case, we miss a description of the example you added. It should explain which plugin matches which paths
There was a problem hiding this comment.
Added a paragraph before the example describing which plugin matches which paths.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/content/docs/linter/plugins.mdx`:
- Around line 42-54: Update the mismatch between the prose and the glob in the
second plugin: either change the includes glob in the plugin object with "path":
"./ts-only-plugin.grit" from "src/**/*.ts" to a broader pattern that includes
TSX (for example use "src/**/*.{ts,tsx}" or add "src/**/*.tsx"), or else change
the documentation text that says "TypeScript files" to explicitly say
"TypeScript (.ts) files" so the description matches the existing "src/**/*.ts"
include pattern; locate the includes key in the plugin entry for
"./ts-only-plugin.grit" to apply the change.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
src/content/docs/linter/plugins.mdxsrc/content/docs/reference/configuration.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- src/content/docs/reference/configuration.mdx
|
@coderabbitai resume |
✅ Actions performedReviews resumed. |
There was a problem hiding this comment.
🧹 Nitpick comments (1)
src/content/docs/linter/plugins.mdx (1)
37-39: Optional: mention the "positive pattern first" constraint for negated globs.When using a negated pattern, you should always specify
**first to match all files and folders, otherwise the negated pattern will not match any files. The intro text currently says "Use negated globs (prefixed with!) for exclusions" without this caveat, which could lead readers astray if they try"includes": ["!src/**/*.test.ts"]alone.The linked glob-syntax reference should cover this in full — so this is purely a "nice to have" callout rather than a required fix.
✏️ Suggested addition
Use negated globs (prefixed with `!`) for exclusions. +Note that a negated pattern alone has no effect; it must be preceded by at +least one positive pattern (e.g. `**`) to function as an exclusion.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/linter/plugins.mdx` around lines 37 - 39, Add a short caveat to the plugins "includes" explanation that when using negated globs (prefixed with '!') you must include a positive pattern first (commonly "**") so the negation can match—e.g., explain that `"includes": ["**", "!src/**/*.test.ts"]` is required and that `"includes": ["!src/**/*.test.ts"]` alone will match nothing; update the sentence referencing "Use negated globs (prefixed with `!`) for exclusions" to include this constraint and optionally link the existing glob-syntax reference for full details.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@src/content/docs/linter/plugins.mdx`:
- Around line 37-39: Add a short caveat to the plugins "includes" explanation
that when using negated globs (prefixed with '!') you must include a positive
pattern first (commonly "**") so the negation can match—e.g., explain that
`"includes": ["**", "!src/**/*.test.ts"]` is required and that `"includes":
["!src/**/*.test.ts"]` alone will match nothing; update the sentence referencing
"Use negated globs (prefixed with `!`) for exclusions" to include this
constraint and optionally link the existing glob-syntax reference for full
details.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
src/content/docs/linter/plugins.mdxsrc/content/docs/reference/configuration.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- src/content/docs/reference/configuration.mdx
|
Re CodeRabbit nitpick on negated globs needing a positive pattern first: this is already covered by the glob syntax reference linked at the bottom of the section, and our example already demonstrates the correct usage. |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: Length of output: 3334
|
2 participants
Summary
Documents the
includesfile-scoping option for plugin configuration, added in biomejs/biome#9171.Changes:
linter/plugins.mdx: Added "File Scoping" section showing how to useincludeswith negated globs for exclusions.reference/configuration.mdx: Addedpluginssection documenting the configuration schema (path,includes).