Remove unsupported RUSTDOC_FLAGS warning from Cargo documentation tests

[coderabbitai]

Summary

Remove the Cargo warning emitted during documentation tests:

warning: ignoring environment variable `RUSTDOC_FLAGS`

Rationale

Makefile defines and exports RUSTDOC_FLAGS for repository-level configuration. Cargo recognizes RUSTDOCFLAGS, without an underscore between DOC and FLAGS. The doctest target runs cargo test --workspace --doc --all-features and inherits the unsupported RUSTDOC_FLAGS variable. Cargo emits the warning in the Windows CI test job.

The repository treats warnings as errors for quality gates. Remove this warning without weakening Rustdoc or compiler warning denial.

Required changes

• Update the Makefile environment-variable contract for the doctest target.
• Ensure Cargo documentation tests receive the intended Rustdoc flags through Cargo's supported RUSTDOCFLAGS environment variable, or prevent the unsupported RUSTDOC_FLAGS variable from reaching Cargo when it is not required.
• Preserve -D warnings for the existing documentation and lint targets.
• Preserve caller overrides where the current Makefile contract permits them.
• Add or update focused Makefile contract coverage for the documentation-test environment contract.

Affected areas

• Makefile, including RUSTDOC_FLAGS, doctest, and Rustdoc-related targets.
• Makefile contract tests under tests/.

Acceptance criteria

• make SHELL=bash doctest does not emit warning: ignoring environment variable \RUSTDOC_FLAGS`` on Windows.
• Documentation tests retain the intended Rustdoc configuration and warning-denial policy.
• Existing lint-clippy and documentation-coverage Rustdoc invocations retain their required flags.
• A focused automated contract test prevents the unsupported variable from being passed to Cargo documentation tests.
• Run make check-fmt, make lint, and make test.

Backlinks

• Originating pull request: Enforce Markdown formatting in check-fmt #619
• Originating comment: Enforce Markdown formatting in check-fmt #619 (comment)
• Requested by: @leynos

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

Interpolate $(RUSTDOC_FLAGS) into a RUSTDOCFLAGS="..." prefix on the doctest and doc-coverage recipes, matching the working lint-clippy line, so Cargo receives the supported name.

Never export the misspelled RUSTDOC_FLAGS, so it cannot reach Cargo and cannot trigger the warning.

Preserve -D warnings, --cfg docsrs, and the ?= caller override throughout.

Add a tests/makefile_test_target/rustdocflags.rs contract with absence and completeness guards to lock the behaviour in.

Follow-up agent prompt

Run the ticket's stated gates after implementation and report failures verbatim:
make check-fmt
make lint
make test
Additionally run `make SHELL=bash doctest` and confirm the output does not contain
`warning: ignoring environment variable ` followed by the misspelled RUSTDOC_FLAGS name.

Design Choices

Design Choice 1: How must the intended Rustdoc flags reach the `doctest` and `doc-coverage` targets without leaking the misspelled name?

Options Considered:

1. Rename the Make macro to RUSTDOCFLAGS and export it, so every cargo recipe inherits the supported name.
2. Keep the macro named RUSTDOC_FLAGS, never export it, and interpolate $(RUSTDOC_FLAGS) into a per-recipe RUSTDOCFLAGS="..." prefix on each target that needs it.

Chosen Option: 2

Rationale: Option 2 matches the working lint-clippy pattern, keeps the flags scoped to the targets that need them, and guarantees the misspelled RUSTDOC_FLAGS never enters the environment of any cargo process. The Makefile can either export a variable so recipes inherit it, or interpolate the macro directly into each recipe line. The exploration shows that any export RUSTDOC_FLAGS (the misspelled name) is exactly what Cargo warns about, so the export route reintroduces the defect.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Fix the Makefile Rustdoc-flag environment contract

This phase makes every Rustdoc-related target pass the intended flags through the supported RUSTDOCFLAGS name using Make substitution. It removes any reliance on the misspelled exported name, and preserves -D warnings and caller overrides. Group these tasks together, because they share one macro and one contract.

Task 1: Pass `RUSTDOCFLAGS` to the `doctest` recipe

Deny Rustdoc-level warnings during doctests and pass the intended flags under the supported name.

• Update the doctest recipe in Makefile to add a RUSTDOCFLAGS="$(RUSTDOC_FLAGS)" environment prefix alongside the existing RUSTFLAGS="$${RUSTFLAGS:+$$RUSTFLAGS }-D warnings" prefix.
• Use Make substitution $(RUSTDOC_FLAGS), not the shell form, to mirror the working lint-clippy line.
• Keep the caller-override path intact: RUSTDOC_FLAGS ?= --cfg docsrs -D warnings continues to allow make doctest RUSTDOC_FLAGS=....
• Do not add export RUSTDOC_FLAGS. The misspelled name must never reach Cargo.

Task 2: Repair the `doc-coverage` Rustdoc-flag reference

Restore the intended Rustdoc flags to the cargo rustdoc --show-coverage calls that scripts/doc-coverage.py performs.

• Change the doc-coverage recipe in Makefile from the shell form RUSTDOCFLAGS="$${RUSTDOC_FLAGS}" to the Make-substitution form RUSTDOCFLAGS="$(RUSTDOC_FLAGS)".
• Keep the surrounding $(UV_ENV) $(UV) run ... invocation and the exported DOC_COVERAGE_TOOLCHAIN/DOC_COVERAGE_THRESHOLD references unchanged.
• Retain the double quotes around the value. The macro holds a fixed flag list, and the quotes contain the space-separated flags safely.

Task 3: Confirm the `lint-clippy` and macro-definition lines stay correct

Preserve the existing working contract for the cargo doc gate.

• Leave the lint-clippy line RUSTDOCFLAGS="$(RUSTDOC_FLAGS)" ... in Makefile unchanged.
• Leave RUSTDOC_FLAGS ?= --cfg docsrs -D warnings unchanged, so the default flags and caller override remain.
• Verify no export RUSTDOC_FLAGS, no .EXPORT_ALL_VARIABLES:, and no bare export directive exists that would export the misspelled name.

🤖 Prompt for AI agents

Fix the Makefile so Rustdoc-related targets pass the intended flags to Cargo
through the supported `RUSTDOCFLAGS` name, and stop the misspelled
`RUSTDOC_FLAGS` from ever reaching Cargo's environment.

- In the `doctest` recipe in `Makefile`, add a `RUSTDOCFLAGS="$(RUSTDOC_FLAGS)"`
environment prefix alongside the existing `RUSTFLAGS="$${RUSTFLAGS:+$$RUSTFLAGS
}-D warnings"` prefix. Use Make substitution `$(RUSTDOC_FLAGS)`, not the shell
form `$${RUSTDOC_FLAGS}`, to mirror the working `lint-clippy` line. Keep
`RUSTDOC_FLAGS ?= --cfg docsrs -D warnings` intact, so `make doctest
RUSTDOC_FLAGS=...` still works. Do not add `export RUSTDOC_FLAGS`.
- In the `doc-coverage` recipe in `Makefile`, change the shell form
`RUSTDOCFLAGS="$${RUSTDOC_FLAGS}"` to the Make-substitution form
`RUSTDOCFLAGS="$(RUSTDOC_FLAGS)"`. Keep the surrounding `$(UV_ENV) $(UV) run
...` invocation and the exported
`DOC_COVERAGE_TOOLCHAIN`/`DOC_COVERAGE_THRESHOLD` references unchanged. Retain
the double quotes around the value.
- Leave the `lint-clippy` line `RUSTDOCFLAGS="$(RUSTDOC_FLAGS)" ...` and the
macro definition `RUSTDOC_FLAGS ?= --cfg docsrs -D warnings` unchanged. Verify
no `export RUSTDOC_FLAGS`, no `.EXPORT_ALL_VARIABLES:`, and no bare `export`
directive exists anywhere in the Makefile that would export the misspelled name.

Phase 2: Guard the Rustdoc-flag contract with a focused test

This phase adds a static contract test that keeps the Rustdoc-flag behaviour honest and fails if any recipe reintroduces the misspelled variable. It follows the established rustflags.rs pattern.

Task 1: Add a `RUSTDOCFLAGS` contract module

Assert that every Rustdoc-flag recipe line uses the supported name and the intended default flags.

• Create tests/makefile_test_target/rustdocflags.rs, modelled on tests/makefile_test_target/rustflags.rs.
• Reuse read_repo_file and target_recipe from tests/support/makefile.rs unchanged.
• Declare a case per RUSTDOCFLAGS="-setting recipe line: doctest, lint-clippy (the doc --workspace --no-deps line), and doc-coverage.
• For each case, extract the assignment value between RUSTDOCFLAGS=" and the next ", and assert it equals the Make-substitution token $(RUSTDOC_FLAGS).
• Assert the macro default RUSTDOC_FLAGS ?= --cfg docsrs -D warnings contains both --cfg docsrs and -D warnings, so warning denial is preserved.
• Note in the module doc comment that these lines use Make substitution $(RUSTDOC_FLAGS), so the sh -c expansion used by rustflags.rs does not apply here. Assert on the extracted Make token directly instead.

Task 2: Add absence and completeness guards

Prevent the misspelled variable from reaching Cargo and prevent future recipes from drifting.

• Add a guard test that scans the whole Makefile and fails if any line exports RUSTDOC_FLAGS, or passes RUSTDOC_FLAGS= as an environment prefix to a cargo command, or uses the shell form $${RUSTDOC_FLAGS} in a recipe.
• Add a completeness test that scans every RUSTDOCFLAGS=" recipe line and fails if any line is not covered by a declared case, mirroring behavioural_every_rustflags_recipe_line_is_under_contract.
• Add a targeted assertion that the doctest recipe contains a RUSTDOCFLAGS= prefix, so the doctest fix cannot silently regress.

Task 3: Wire the new module into the test binary

Register the contract module so it runs with the existing suite.

• Update tests/makefile_test_target.rs to include the new module via #[path = "makefile_test_target/rustdocflags.rs"] mod rustdocflags;, matching how rustflags is wired.

🤖 Prompt for AI agents

Add a static contract test that locks in the Rustdoc-flag fix and fails if the
misspelled `RUSTDOC_FLAGS` ever reaches Cargo again. Follow the established
`rustflags.rs` pattern.

- Create `tests/makefile_test_target/rustdocflags.rs`, modelled on
`tests/makefile_test_target/rustflags.rs`. Reuse `read_repo_file` and
`target_recipe` from `tests/support/makefile.rs` unchanged.
- Declare a case per `RUSTDOCFLAGS="`-setting recipe line: `doctest`,
`lint-clippy` (the `doc --workspace --no-deps` line), and `doc-coverage`. For
each case, extract the assignment value between `RUSTDOCFLAGS="` and the next
`"`, and assert it equals the Make-substitution token `$(RUSTDOC_FLAGS)`.
- Assert the macro default `RUSTDOC_FLAGS ?= --cfg docsrs -D warnings` contains
both `--cfg docsrs` and `-D warnings`.
- Add a module doc comment noting that these lines use Make substitution
`$(RUSTDOC_FLAGS)`, so the `sh -c` expansion used by `rustflags.rs` does not
apply. Assert on the extracted Make token directly instead.
- Add a guard test that scans the whole `Makefile` and fails if any line exports
`RUSTDOC_FLAGS`, passes `RUSTDOC_FLAGS=` as an environment prefix to a `cargo`
command, or uses the shell form `$${RUSTDOC_FLAGS}` in a recipe.
- Add a completeness test that scans every `RUSTDOCFLAGS="` recipe line and
fails if any line is not covered by a declared case, mirroring
`behavioural_every_rustflags_recipe_line_is_under_contract`.
- Add a targeted assertion that the `doctest` recipe contains a `RUSTDOCFLAGS=`
prefix.
- Update `tests/makefile_test_target.rs` to include the new module via `#[path =
"makefile_test_target/rustdocflags.rs"] mod rustdocflags;`, matching how
`rustflags` is wired.

Research

Netsuke is a Rust workspace. The Makefile drives the build, test, lint, and documentation-coverage gates. RUSTDOC_FLAGS ?= --cfg docsrs -D warnings is a plain, overridable Make macro. The lint-clippy target maps it into RUSTDOCFLAGS for cargo doc with Make substitution $(RUSTDOC_FLAGS). The doc-coverage target references the shell form $${RUSTDOC_FLAGS}, which resolves to an empty value because the macro is not exported. The doctest target runs cargo test --workspace --doc --all-features and sets only RUSTFLAGS. Makefile behaviour is guarded by static contract tests: tests/makefile_test_target.rs includes tests/support/makefile.rs (parsing helpers) and wires in tests/makefile_test_target/rustflags.rs, which extracts recipe-line assignments and expands them with sh -c to assert the resulting flags.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Fix the Makefile so Rustdoc-related targets pass the intended flags to Cargo
through the supported `RUSTDOCFLAGS` name, and stop the misspelled
`RUSTDOC_FLAGS` from ever reaching Cargo's environment.

- In the `doctest` recipe in `Makefile`, add a `RUSTDOCFLAGS="$(RUSTDOC_FLAGS)"`
environment prefix alongside the existing `RUSTFLAGS="$${RUSTFLAGS:+$$RUSTFLAGS
}-D warnings"` prefix. Use Make substitution `$(RUSTDOC_FLAGS)`, not the shell
form `$${RUSTDOC_FLAGS}`, to mirror the working `lint-clippy` line. Keep
`RUSTDOC_FLAGS ?= --cfg docsrs -D warnings` intact, so `make doctest
RUSTDOC_FLAGS=...` still works. Do not add `export RUSTDOC_FLAGS`.
- In the `doc-coverage` recipe in `Makefile`, change the shell form
`RUSTDOCFLAGS="$${RUSTDOC_FLAGS}"` to the Make-substitution form
`RUSTDOCFLAGS="$(RUSTDOC_FLAGS)"`. Keep the surrounding `$(UV_ENV) $(UV) run
...` invocation and the exported
`DOC_COVERAGE_TOOLCHAIN`/`DOC_COVERAGE_THRESHOLD` references unchanged. Retain
the double quotes around the value.
- Leave the `lint-clippy` line `RUSTDOCFLAGS="$(RUSTDOC_FLAGS)" ...` and the
macro definition `RUSTDOC_FLAGS ?= --cfg docsrs -D warnings` unchanged. Verify
no `export RUSTDOC_FLAGS`, no `.EXPORT_ALL_VARIABLES:`, and no bare `export`
directive exists anywhere in the Makefile that would export the misspelled name.
===============================================================================

Task: 2

Add a static contract test that locks in the Rustdoc-flag fix and fails if the
misspelled `RUSTDOC_FLAGS` ever reaches Cargo again. Follow the established
`rustflags.rs` pattern.

- Create `tests/makefile_test_target/rustdocflags.rs`, modelled on
`tests/makefile_test_target/rustflags.rs`. Reuse `read_repo_file` and
`target_recipe` from `tests/support/makefile.rs` unchanged.
- Declare a case per `RUSTDOCFLAGS="`-setting recipe line: `doctest`,
`lint-clippy` (the `doc --workspace --no-deps` line), and `doc-coverage`. For
each case, extract the assignment value between `RUSTDOCFLAGS="` and the next
`"`, and assert it equals the Make-substitution token `$(RUSTDOC_FLAGS)`.
- Assert the macro default `RUSTDOC_FLAGS ?= --cfg docsrs -D warnings` contains
both `--cfg docsrs` and `-D warnings`.
- Add a module doc comment noting that these lines use Make substitution
`$(RUSTDOC_FLAGS)`, so the `sh -c` expansion used by `rustflags.rs` does not
apply. Assert on the extracted Make token directly instead.
- Add a guard test that scans the whole `Makefile` and fails if any line exports
`RUSTDOC_FLAGS`, passes `RUSTDOC_FLAGS=` as an environment prefix to a `cargo`
command, or uses the shell form `$${RUSTDOC_FLAGS}` in a recipe.
- Add a completeness test that scans every `RUSTDOCFLAGS="` recipe line and
fails if any line is not covered by a declared case, mirroring
`behavioural_every_rustflags_recipe_line_is_under_contract`.
- Add a targeted assertion that the `doctest` recipe contains a `RUSTDOCFLAGS=`
prefix.
- Update `tests/makefile_test_target.rs` to include the new module via `#[path =
"makefile_test_target/rustdocflags.rs"] mod rustdocflags;`, matching how
`rustflags` is wired.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---