From 527c81505848018a82a4524e45935c90712eaea3 Mon Sep 17 00:00:00 2001 From: Ivan Date: Mon, 26 Oct 2026 23:10:10 +0200 Subject: [PATCH 1/2] refactor(cli): give the either/or usage error a thiserror type conflict() built its message with format! and passed the string to Command::error. It now passes a Conflict struct whose fields are the two arguments as given, so the message lives with its type like the other usage errors (#9194). The text is unchanged. Co-authored-by: Claude Opus 5.5 --- crates/automation/src/args.rs | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/crates/automation/src/args.rs b/crates/automation/src/args.rs index 5c6dd666a7..24abac69e7 100644 --- a/crates/automation/src/args.rs +++ b/crates/automation/src/args.rs @@ -99,8 +99,16 @@ pub fn conflict(cmd: &mut Command, m: &ArgMatches, a: &str, b: &str) -> Result<( _ => arg.map_or_else(|| id.to_owned(), |arg| arg.to_string()), } }; - let message = format!("the argument '{}' cannot be used with '{}'", shown(a), shown(b)); - Err(cmd.error(ErrorKind::ArgumentConflict, message)) + let both = Conflict { a: shown(a), b: shown(b) }; + Err(cmd.error(ErrorKind::ArgumentConflict, both)) +} + +/// A [`conflict`]: two arguments, each named as it was given (the flag, or its variable). +#[derive(Debug, thiserror::Error)] +#[error("the argument '{a}' cannot be used with '{b}'")] +struct Conflict { + a: String, + b: String, } #[cfg(test)] From 695590c106c8e061dc69cdf9b4ec192723ccb062 Mon Sep 17 00:00:00 2001 From: Ivan Date: Mon, 26 Oct 2026 23:10:11 +0200 Subject: [PATCH 2/2] ci(cli): check the command-line code with ast-grep rules lint/ast-grep holds four rules from RFC-0012 for the CLI code (apps/photocraft-cli, the shared launch options in crates/automation/src/args.rs, and the desktop app's main.rs and launch_args.rs, which read its arguments): - clap-error-message: no string literal, format!, .to_string() or SCREAMING_CASE const passed to Command::error or Error::raw. - clap-error-message-variable: the same, through a variable built with format!, .to_string(), String::from or a literal's .to_owned() in the block around the call. - string-error: no Result<_, String>, Err(format!(..)), Err("..") or Err(x.to_string()). - args-os: no std::env::args() (also when imported or renamed), which panics on a non-Unicode argument. Each rule has valid and invalid cases in rule-tests/. The workflow calls craft-common-actions' ast-grep.yml, which runs the rule tests and then the scan. It takes seconds and builds nothing. Co-authored-by: Claude Opus 5.5 --- .github/workflows/ast-grep.yml | 26 +++++++++ lint/ast-grep/rule-tests/args-os-test.yml | 26 +++++++++ .../rule-tests/clap-error-message-test.yml | 15 +++++ .../clap-error-message-variable-test.yml | 56 +++++++++++++++++++ .../ast-grep/rule-tests/string-error-test.yml | 15 +++++ lint/ast-grep/rules/args-os.yml | 31 ++++++++++ .../rules/clap-error-message-variable.yml | 35 ++++++++++++ lint/ast-grep/rules/clap-error-message.yml | 27 +++++++++ lint/ast-grep/rules/string-error.yml | 24 ++++++++ lint/ast-grep/sgconfig.yml | 6 ++ 10 files changed, 261 insertions(+) create mode 100644 .github/workflows/ast-grep.yml create mode 100644 lint/ast-grep/rule-tests/args-os-test.yml create mode 100644 lint/ast-grep/rule-tests/clap-error-message-test.yml create mode 100644 lint/ast-grep/rule-tests/clap-error-message-variable-test.yml create mode 100644 lint/ast-grep/rule-tests/string-error-test.yml create mode 100644 lint/ast-grep/rules/args-os.yml create mode 100644 lint/ast-grep/rules/clap-error-message-variable.yml create mode 100644 lint/ast-grep/rules/clap-error-message.yml create mode 100644 lint/ast-grep/rules/string-error.yml create mode 100644 lint/ast-grep/sgconfig.yml diff --git a/.github/workflows/ast-grep.yml b/.github/workflows/ast-grep.yml new file mode 100644 index 0000000000..71e10920cb --- /dev/null +++ b/.github/workflows/ast-grep.yml @@ -0,0 +1,26 @@ +# Structural rules for the command-line code (RFC-0012): lint/ast-grep's rule tests, then a scan. +# Seconds, no Rust build. +name: ast-grep + +on: + push: + branches: [main] + paths: ["lint/ast-grep/**", "apps/photocraft-cli/**", "crates/automation/src/args.rs", "apps/photocraft/src/launch_args.rs", "apps/photocraft/src/main.rs", ".github/workflows/ast-grep.yml"] + pull_request: + paths: ["lint/ast-grep/**", "apps/photocraft-cli/**", "crates/automation/src/args.rs", "apps/photocraft/src/launch_args.rs", "apps/photocraft/src/main.rs", ".github/workflows/ast-grep.yml"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: ast-grep-${{ github.ref }} + cancel-in-progress: true + +jobs: + scan: + # Tracked at @main like the other shared workflows. + uses: storytold/craft-common-actions/.github/workflows/ast-grep.yml@main + with: + config: lint/ast-grep/sgconfig.yml + paths: apps/photocraft-cli crates/automation/src/args.rs apps/photocraft/src/launch_args.rs apps/photocraft/src/main.rs diff --git a/lint/ast-grep/rule-tests/args-os-test.yml b/lint/ast-grep/rule-tests/args-os-test.yml new file mode 100644 index 0000000000..e3dea767f1 --- /dev/null +++ b/lint/ast-grep/rule-tests/args-os-test.yml @@ -0,0 +1,26 @@ +id: args-os +valid: + - let code = photocraft_cli::run(std::env::args_os().skip(1), &mut out, &mut err); + - "let args: Vec = env::args_os().collect();" + - | + use std::env::args_os; + fn main() { let a: Vec<_> = args_os().collect(); } + - | + fn args() -> Vec { Vec::new() } + fn main() { let a = args(); } + - | + use std::env::args as os_args; + fn args() -> Vec { Vec::new() } + fn main() { let a = args(); } +invalid: + - "let args: Vec = std::env::args().collect();" + - for a in env::args().skip(1) {} + - | + use std::env::args; + fn main() { let a: Vec = args().collect(); } + - | + use std::env::{args, var}; + fn main() { for a in args() {} } + - | + use std::env::args as os_args; + fn main() { let a: Vec = os_args().collect(); } diff --git a/lint/ast-grep/rule-tests/clap-error-message-test.yml b/lint/ast-grep/rule-tests/clap-error-message-test.yml new file mode 100644 index 0000000000..b2b1b0a8d4 --- /dev/null +++ b/lint/ast-grep/rule-tests/clap-error-message-test.yml @@ -0,0 +1,15 @@ +id: clap-error-message +valid: + - cmd.error(ErrorKind::ArgumentConflict, UsageError::BridgeRoots) + - cmd.error(ErrorKind::ArgumentConflict, Conflict { a, b }) + - sub.error(kind, self) + - log.error("not a clap error") + - cmd.error(ErrorKind::ValueValidation, e.to_owned()) +invalid: + - cmd.error(ErrorKind::ArgumentConflict, "configure automation roots on the desktop app") + - sub.error(ErrorKind::MissingRequiredArgument, format!("{flag} requires {transport}")) + - sub.error(ErrorKind::ArgumentConflict, BRIDGE_ROOTS) + - cmd.error(ErrorKind::InvalidValue, e.to_string()) + - cmd.error(ErrorKind::InvalidValue, String::from("bad value")) + - cmd.error(ErrorKind::InvalidValue, "bad value".to_owned()) + - clap::Error::raw(ErrorKind::InvalidValue, "bad value") diff --git a/lint/ast-grep/rule-tests/clap-error-message-variable-test.yml b/lint/ast-grep/rule-tests/clap-error-message-variable-test.yml new file mode 100644 index 0000000000..b7f3207e93 --- /dev/null +++ b/lint/ast-grep/rule-tests/clap-error-message-variable-test.yml @@ -0,0 +1,56 @@ +id: clap-error-message-variable +valid: + - | + fn conflict(cmd: &mut Command, a: String, b: String) -> clap::Error { + cmd.error(ErrorKind::ArgumentConflict, Conflict { a, b }) + } + - | + fn wrap(cmd: &mut Command, e: UsageError) -> clap::Error { + cmd.error(ErrorKind::ValueValidation, e) + } + - | + fn unrelated(cmd: &mut Command, e: UsageError) -> clap::Error { + let shown = format!("{e}"); + eprintln!("{shown}"); + cmd.error(ErrorKind::ValueValidation, e) + } + - | + fn cloned(cmd: &mut Command, e: &UsageError) -> clap::Error { + let owned = e.to_owned(); + cmd.error(ErrorKind::ValueValidation, owned) + } + - | + fn shadowed(cmd: &mut Command, e: UsageError) -> clap::Error { + let message = e; + { + let message = format!("debug"); + eprintln!("{message}"); + } + cmd.error(ErrorKind::ValueValidation, message) + } +invalid: + - | + fn conflict(cmd: &mut Command, a: &str, b: &str) -> clap::Error { + let message = format!("the argument '{a}' cannot be used with '{b}'"); + cmd.error(ErrorKind::ArgumentConflict, message) + } + - | + fn bad(cmd: &mut Command, e: UsageError) -> clap::Error { + let message = e.to_string(); + cmd.error(ErrorKind::ValueValidation, message) + } + - | + fn typed(cmd: &mut Command, flag: &str) -> clap::Error { + let message: String = flag.into(); + clap::Error::raw(ErrorKind::InvalidValue, message) + } + - | + fn literal(cmd: &mut Command) -> clap::Error { + let message = "bad value".to_owned(); + cmd.error(ErrorKind::InvalidValue, message) + } + - | + fn from(cmd: &mut Command) -> clap::Error { + let message = String::from("bad value"); + cmd.error(ErrorKind::InvalidValue, message) + } diff --git a/lint/ast-grep/rule-tests/string-error-test.yml b/lint/ast-grep/rule-tests/string-error-test.yml new file mode 100644 index 0000000000..dfb1d89f38 --- /dev/null +++ b/lint/ast-grep/rule-tests/string-error-test.yml @@ -0,0 +1,15 @@ +id: string-error +valid: + - "fn parse(s: &str) -> Result { todo!() }" + - "fn name() -> Option { None }" + - "fn ok() -> Result { Ok(String::new()) }" + - Err(PortError::Range) + - Err(e) +invalid: + - "fn parse(s: &str) -> Result { todo!() }" + - "type R = Result<(), String>;" + - "fn parse(s: &str) -> std::result::Result { todo!() }" + - Err(format!("bad port {s}")) + - Err(e.to_string()) + - Err(String::from("bad port")) + - Err("bad port") diff --git a/lint/ast-grep/rules/args-os.yml b/lint/ast-grep/rules/args-os.yml new file mode 100644 index 0000000000..b6b881ee18 --- /dev/null +++ b/lint/ast-grep/rules/args-os.yml @@ -0,0 +1,31 @@ +id: args-os +language: rust +severity: error +message: std::env::args() panics on an argument that isn't valid Unicode +note: | + Read std::env::args_os() and let clap parse the OsStrings, so a Latin-1 file name reaches the + command (or is a usage error) instead of aborting before anything is printed (#1108). +rule: + any: + - pattern: std::env::args() + - pattern: env::args() + # A bare args() only where the file imports std::env::args under that name, not any function + # named args (`args as os_args` binds os_args, so a local args() stays valid). + - all: + - pattern: args() + - inside: + kind: source_file + stopBy: end + has: + kind: use_declaration + stopBy: end + regex: std::env::(args\s*;|\{[^}]*\bargs\s*[,}]) + # The renamed import: the call binds $F, then the file must import std::env::args as $F. + - all: + - pattern: $F() + - inside: + kind: source_file + stopBy: end + has: + stopBy: end + pattern: use std::env::args as $F; diff --git a/lint/ast-grep/rules/clap-error-message-variable.yml b/lint/ast-grep/rules/clap-error-message-variable.yml new file mode 100644 index 0000000000..4cc95bc90d --- /dev/null +++ b/lint/ast-grep/rules/clap-error-message-variable.yml @@ -0,0 +1,35 @@ +id: clap-error-message-variable +language: rust +severity: error +message: clap error built from a string held in a variable +note: | + The message was built with format!, .to_string(), String::from or a literal's .to_owned() a + few lines up. Give it a variant on a + #[derive(thiserror::Error)] enum instead, with the parts as fields, and pass the variant. +rule: + # In this order: the call binds $MSG, then a block around the call must hold a `let` of that + # same name as a direct statement. A `let` in a sibling block is out of scope at the call. + all: + - any: + - pattern: $CMD.error($KIND, $MSG) + - pattern: Error::raw($KIND, $MSG) + - pattern: clap::Error::raw($KIND, $MSG) + - inside: + kind: block + stopBy: end + has: + any: + - pattern: let $MSG = format!($$$); + - pattern: "let $MSG: String = $VAL;" + - pattern: let $MSG = $SRC.to_string(); + - pattern: let $MSG = String::from($$$); + # .to_owned() only on a string literal: on anything else it may clone a typed error. + - all: + - kind: let_declaration + - regex: '=\s*"(?s:.*)"\s*\.to_owned\(\)\s*;?$' + - has: + field: pattern + pattern: $MSG +constraints: + MSG: + kind: identifier diff --git a/lint/ast-grep/rules/clap-error-message.yml b/lint/ast-grep/rules/clap-error-message.yml new file mode 100644 index 0000000000..556a8f959d --- /dev/null +++ b/lint/ast-grep/rules/clap-error-message.yml @@ -0,0 +1,27 @@ +id: clap-error-message +language: rust +severity: error +message: clap error built from a string +note: | + Give the message a variant on a #[derive(thiserror::Error)] enum and pass the variant, e.g. + `cmd.error(ErrorKind::ArgumentConflict, UsageError::BridgeRoots)`. A string literal, format!, + .to_string() or a SCREAMING_CASE const keeps the message apart from the error's type. +rule: + any: + - pattern: $CMD.error($KIND, $MSG) + - pattern: Error::raw($KIND, $MSG) + - pattern: clap::Error::raw($KIND, $MSG) +constraints: + MSG: + any: + - kind: string_literal + - all: + - kind: macro_invocation + - regex: ^format! + - all: + - kind: identifier + - regex: ^[A-Z][A-Z0-9_]*$ + - all: + - kind: call_expression + # .to_owned() only on a string literal: on anything else it may clone a typed error. + - regex: \.to_string\(\)$|^String::from\(|^"(?s:.*)"\s*\.to_owned\(\)$ diff --git a/lint/ast-grep/rules/string-error.yml b/lint/ast-grep/rules/string-error.yml new file mode 100644 index 0000000000..fc61ff197d --- /dev/null +++ b/lint/ast-grep/rules/string-error.yml @@ -0,0 +1,24 @@ +id: string-error +language: rust +severity: error +message: String as an error type +note: | + Return a #[derive(thiserror::Error)] enum, so a caller can match on what failed and the + messages live with their variants. +rule: + any: + - pattern: + context: type T = Result<$OK, String>; + selector: generic_type + - pattern: + context: type T = std::result::Result<$OK, String>; + selector: generic_type + - pattern: Err(format!($$$)) + - pattern: Err($S.to_string()) + - pattern: Err(String::from($$$)) + - all: + - pattern: Err($S) + - has: + kind: arguments + has: + kind: string_literal diff --git a/lint/ast-grep/sgconfig.yml b/lint/ast-grep/sgconfig.yml new file mode 100644 index 0000000000..9c94bd0ae6 --- /dev/null +++ b/lint/ast-grep/sgconfig.yml @@ -0,0 +1,6 @@ +# Structural rules for the command-line code (RFC-0012), run by .github/workflows/ast-grep.yml. +# Each rule in rules/ has its cases in rule-tests/, which CI checks before the scan. +ruleDirs: + - rules +testConfigs: + - testDir: rule-tests