docs: fix include syntax to match implementation by jdx · Pull Request #540 · jdx/usage

jdx · 2026-03-13T13:20:06Z

Summary

Fixes the include syntax in the spec reference docs to match the actual implementation
Docs showed include "./file.kdl" but the parser expects include file="./file.kdl"

Closes #534

Test plan

Verify usage lint accepts the documented syntax

🤖 Generated with Claude Code

Note

Low Risk
Low risk documentation-only change; no runtime code paths are modified.

Overview
Aligns the spec reference documentation with the implemented include directive syntax by changing the example from include "./file.kdl" to include file="./file.kdl" in docs/spec/reference/index.md.

^{Written by Cursor Bugbot for commit 0379e99. This will update automatically on new commits. Configure here.}

The docs showed `include "./file.kdl"` but the parser expects `include file="./file.kdl"`. Co-Authored-By: Claude Opus 4.6 <[email protected]>

codecov · 2026-03-13T13:20:56Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.94%. Comparing base (15a13d3) to head (0379e99).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #540   +/-   ##
=======================================
  Coverage   77.94%   77.94%           
=======================================
  Files          48       48           
  Lines        6682     6682           
  Branches     6682     6682           
=======================================
  Hits         5208     5208           
  Misses       1114     1114           
  Partials      360      360

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

gemini-code-assist · 2026-03-13T13:20:57Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request focuses on improving the accuracy of the project's documentation by correcting a discrepancy in the include directive's syntax. The change ensures that the examples provided in the specification reference align perfectly with the behavior of the underlying parser, enhancing clarity and reducing potential confusion for users.

Highlights

Documentation Correction: The include syntax in the specification reference documentation has been updated to accurately reflect the actual implementation.
Syntax Alignment: The documented syntax for include was changed from include "./file.kdl" to include file="./file.kdl" to match what the parser expects.

Changelog

docs/spec/reference/index.md
- Updated the include directive example to use file= attribute, matching the parser's expected syntax.

Activity

The pull request addresses and closes issue Syntax of the include top-level metadata #534.
A test plan was outlined to verify that usage lint accepts the newly documented syntax.
The PR was generated with Claude Code.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

Copilot

Pull request overview

Updates the spec reference documentation so the include directive matches the parser’s implemented KDL shape (include file="..."), resolving the mismatch reported in #534.

Changes:

Fix include example syntax in the spec reference from a positional arg form to a file=... property form.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

greptile-apps · 2026-03-13T13:21:28Z

Greptile Summary

This PR is a single-line documentation fix that corrects the include directive syntax in docs/spec/reference/index.md to match the actual parser implementation.

The old doc showed include "./my_overrides.usage.kdl" (positional argument), which the parser in lib/src/spec/mod.rs does not support — it only reads a named file= property via .props().get("file"), returning a "missing file" error for positional arguments.
The fix changes it to include file="./my_overrides.usage.kdl", which is the correct and only supported syntax.
No other documentation files, example KDL files, or runtime code are affected.

Confidence Score: 5/5

This PR is safe to merge — it is a one-line documentation correction with no runtime code changes.
The change is docs-only and correctly aligns the documented syntax with the verified parser implementation. No logic, tests, or other files are affected.
No files require special attention.

Important Files Changed

Filename	Overview
docs/spec/reference/index.md	Corrects the `include` directive example from the positional-argument syntax `include "./file.kdl"` to the named-property syntax `include file="./file.kdl"`, which matches the parser implementation in `lib/src/spec/mod.rs`.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Parse KDL node"] --> B{"Node name?"}
    B -->|"include"| C["Read props().get('file')"]
    B -->|"other"| Z["Handle other node types"]
    C --> D{"file property present?"}
    D -->|"No"| E["Error: 'missing file'"]
    D -->|"Yes"| F["Resolve path\n(relative or absolute)"]
    F --> G["Parse included file"]
    G --> H["schema.merge(other)"]

    style E fill:#ff6b6b,color:#fff
    style H fill:#51cf66,color:#fff

_{Last reviewed commit: 0379e99}

gemini-code-assist

Code Review

This pull request addresses an inconsistency in the documentation by correcting the syntax for the include directive in the KDL usage specification. The change in docs/spec/reference/index.md updates the example from include "./my_overrides.usage.kdl" to include file="./my_overrides.usage.kdl", which now matches the parser's expected implementation. The fix is accurate and well-contained. The review of related files did not reveal any other instances of the incorrect syntax.

@jdx

⚠️ **CAUTION: this is a major update, indicating a breaking change!** ⚠️ This MR contains the following updates: | Package | Update | Change | |---|---|---| | [usage](https://github.com/jdx/usage) | major | `2.18.2` → `3.2.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>jdx/usage (usage)</summary> ### [`v3.2.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#320---2026-03-23) [Compare Source](jdx/usage@v3.1.0...v3.2.0) ##### 🚀 Features - Support env-backed choices with `choices env=...` by [@mustafa0x](https://github.com/mustafa0x) in [#548](jdx/usage#548) ##### 🐛 Bug Fixes - **(zsh)** escape parentheses and brackets in completion descriptions by [@jdx](https://github.com/jdx) in [#559](jdx/usage#559) ##### New Contributors - [@mustafa0x](https://github.com/mustafa0x) made their first contribution in [#548](jdx/usage#548) ### [`v3.1.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#310---2026-03-22) [Compare Source](jdx/usage@v3.0.0...v3.1.0) ##### 🚀 Features - **(cli)** render all doc-related fields in --help output by [@jdx](https://github.com/jdx) in [#554](jdx/usage#554) - **(cli)** support reading spec from stdin via --file - by [@jdx](https://github.com/jdx) in [#555](jdx/usage#555) ##### 🐛 Bug Fixes - **(zsh)** remove trailing space from completions and add directory slash by [@jdx](https://github.com/jdx) in [#556](jdx/usage#556) - use field assignment for non-exhaustive Spec in benchmarks by [@jdx](https://github.com/jdx) in [#552](jdx/usage#552) ##### 📦️ Dependency Updates - update apple-actions/import-codesign-certs digest to [`fe74d46`](jdx/usage@fe74d46) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#550](jdx/usage#550) - update codecov/codecov-action digest to [`1af5884`](jdx/usage@1af5884) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#551](jdx/usage#551) - lock file maintenance by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#547](jdx/usage#547) ### [`v3.0.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#300---2026-03-13) [Compare Source](jdx/usage@v2.18.2...v3.0.0) ##### 🚀 Features - **(spec)** **breaking** add support for license, before/after help metadata by [@jdx](https://github.com/jdx) in [#542](jdx/usage#542) ##### 🐛 Bug Fixes - **(cobra)** escape newlines, tabs, and carriage returns in kdlQuoteAlways by [@thecodesmith](https://github.com/thecodesmith) in [#539](jdx/usage#539) - bump major version for breaking changes in release automation by [@jdx](https://github.com/jdx) in [#544](jdx/usage#544) - add custom\_major\_increment\_regex for breaking change detection by [@jdx](https://github.com/jdx) in [#545](jdx/usage#545) - handle all breaking change commit formats in major bump regex by [@jdx](https://github.com/jdx) in [27e1ab1](jdx/usage@27e1ab1) - normalize breaking change commit format in preprocessor by [@jdx](https://github.com/jdx) in [aa72b92](jdx/usage@aa72b92) ##### 📚 Documentation - add argparse-usage integration by [@jdx](https://github.com/jdx) in [#531](jdx/usage#531) - mark KDL code blocks as KDL and use correct inline-comment `//` by [@muzimuzhi](https://github.com/muzimuzhi) in [#536](jdx/usage#536) - fix include syntax to match implementation by [@jdx](https://github.com/jdx) in [#540](jdx/usage#540) - consolidate integration list to single source by [@jdx](https://github.com/jdx) in [#541](jdx/usage#541) - fix link to integrations by [@muzimuzhi](https://github.com/muzimuzhi) in [#543](jdx/usage#543) ##### 🛡️ Security - **(deps)** update dependency eslint to v10 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#526](jdx/usage#526) ##### 🔍 Other Changes - Added an integration with ruby's OptionParser by [@packrat386](https://github.com/packrat386) in [#533](jdx/usage#533) ##### 📦️ Dependency Updates - update actions/setup-node digest to [`53b8394`](jdx/usage@53b8394) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#525](jdx/usage#525) - update jdx/mise-action action to v3 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#528](jdx/usage#528) - update rust crate roff to v1 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#529](jdx/usage#529) ##### New Contributors - [@thecodesmith](https://github.com/thecodesmith) made their first contribution in [#539](jdx/usage#539) - [@packrat386](https://github.com/packrat386) made their first contribution in [#533](jdx/usage#533) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

docs: fix include syntax to match implementation (#534)

0379e99

The docs showed `include "./file.kdl"` but the parser expects `include file="./file.kdl"`. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot AI review requested due to automatic review settings March 13, 2026 13:20

Copilot started reviewing on behalf of jdx March 13, 2026 13:20 View session

Copilot AI reviewed Mar 13, 2026

View reviewed changes

jdx merged commit 5b90bf8 into main Mar 13, 2026
16 checks passed

jdx deleted the fix/534-include-syntax branch March 13, 2026 13:21

gemini-code-assist Bot reviewed Mar 13, 2026

View reviewed changes

mise-en-dev mentioned this pull request Mar 13, 2026

chore: release v3.0.0 #527

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: fix include syntax to match implementation#540

docs: fix include syntax to match implementation#540
jdx merged 1 commit intomainfrom
fix/534-include-syntax

jdx commented Mar 13, 2026 •

edited by cursor Bot

Loading

Uh oh!

codecov Bot commented Mar 13, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot commented Mar 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

greptile-apps Bot commented Mar 13, 2026

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

jdx commented Mar 13, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

codecov Bot commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

gemini-code-assist Bot commented Mar 13, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

greptile-apps Bot commented Mar 13, 2026

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jdx commented Mar 13, 2026 •

edited by cursor Bot

Loading

codecov Bot commented Mar 13, 2026 •

edited

Loading