fix(PTH208): add display-only hint for os.listdir

[fly1d]

Summary

Adds a display-only suggestion for PTH208 diagnostics with a path argument:

Path(path).iterdir()

The suggestion is intentionally not an automatic fix because os.listdir returns strings or bytes, while Path.iterdir() returns Path objects and can change downstream behavior. The existing diagnostic remains unchanged, and file-descriptor calls do not receive the suggestion.

Part of #2331.

Verification

• INSTA_FORCE_PASS=1 INSTA_UPDATE=always cargo test -p ruff_linter flake8_use_pathlib::tests --lib (34 passed)
• cargo fmt --all -- --check
• git diff --check

OpenAI Codex assisted with implementation and verification. The contributor reviewed the change before submission.

[astral-sh-bot]

We support using AI (i.e., LLMs) while coding. However, AI should not be used to communicate with maintainers.

Please read and follow our AI policy when submitting issues and pull requests.

[fly1d]

I confirm that I have read the AI policy. However, as a non-native English speaker, I may not have fully understood all the details. Please note that the comments were originally written by me, with AI used solely for language polishing.

[ntBre]

Your test plan specifically read as very LLM-generated to me, but I'll take you at your word and reopen this. Thank you for reading the policy.

[ntBre]

Thanks. This looks reasonable at a high level, but we still need to check that the diagnostic is enabled and also use the importer infrastructure to ensure that Path is in scope for the fix. I also had a couple of smaller suggestions.

[ntBre]

I think we still need to use report_diagnostic_if_enabled here, or we could report the diagnostic when the rule is disabled. Something like this should work:

Suggested change

	let mut diagnostic = checker.report_diagnostic(OsListdir, range);
	if let Some(path) = call.arguments.find_argument_value("path", 0) {
	if let Some(mut diagnostic) = checker.report_diagnostic_if_enabled(OsListdir, range) {
	if let Some(path) = call.arguments.find_argument_value("path", 0) {

It also looks like we don't need to return the diagnostic here, I think the match arms are just missing semicolons so that we can drop the Some(diagnostic).

[fly1d]

Got it. I switched to report_diagnostic_if_enabled, and this branch no longer returns Some(diagnostic).

[ntBre]

Can we reuse the find_argument_value call from above? I'm picturing something like:

let path = call.arguments.find_argument_value("path", 0);

if path.is_some_and(|expr| is_file_descriptor(expr, checker.semantic())) {
    return;
}

then your code from above.

[fly1d]

Sure,I now look up path only once and use it for both the file-descriptor check and the replacement.

[ntBre]

We need to make sure Path is actually in scope. See some other rules for examples:

ruff/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_mkdir.rs

Lines 105 to 110 in 26f4f73

	let (import_edit, binding) = checker.importer().get_or_import_symbol(
	&ImportRequest::import("pathlib", "Path"),
	call.start(),
	checker.semantic(),
	)?;

[fly1d]

Alright – we can also rely on the importer to reuse an existing Path binding, or add the import when needed.

[ntBre]

We should also add a fix_title method now to customize the hint shown for the diagnostic.

[fly1d]

I've added a custom fix_title method per your suggestion.

[ntBre]

As one other note, I think we've mosty added pathlib fixes in preview, but that's only required for safe fixes by our versioning policy. I think this display-only fix is fine to add in stable.