{"record":{"id":"7a8b4c0b8d6a0199","repo":"jdx/mise","slug":"generated-mise-usage-spec","errorCode":null,"errorMessage":"generated mise usage spec","messagePattern":"generated mise usage spec","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cli/usage.rs","lineNumber":32,"sourceCode":"        flag.conflicts.retain(|selector| selector != \"TASK\");\n        flag.requires.retain(|selector| selector != \"TASK\");\n        flag.required_if.retain(|selector| selector != \"TASK\");\n        flag.required_unless.retain(|selector| selector != \"TASK\");\n    }\n    let mut mount = usage::SpecMount::new(\"mise tasks --usage\".to_string());\n    mount.synopsis = Some(\"[TASK] [ARGS]…\".to_string());\n    command.mounts.push(mount);\n    command.restart_token = Some(\":::\".to_string());\n}\n\n/// mise's own usage spec, with everything clap cannot express applied.\n///\n/// Shared with `mise mcp`, which answers \"what does this command do\" from the\n/// same `effect=` data this prints. Two constructions would drift, and the one\n/// an agent reads is the one that must not.\npub(super) fn spec() -> usage::Spec {\n    {\n        let mut spec: usage::Spec = Cli::to_kdl().parse().expect(\"generated mise usage spec\");\n\n        // Enable \"naked\" task completions: `mise foo` completes like `mise run foo`\n        spec.default_subcommand = Some(\"run\".to_string());\n\n        // `run`/`tasks run` redeclare some root globals as their own non-global flags and\n        // add shorts the root global lacks (`-r`/`--raw`, `-S`/`--silent`, see\n        // `cli::run::Run`). Those flags used to be promoted back to global here so the\n        // completion parser would still recognize them before a task name (mise#10069);\n        // jdx/usage#738 makes the parser scan across any known flag, global or not, and\n        // bind each word to the flag it was read as, so the promotion is no longer needed.\n        if let Some(run) = spec.cmd.subcommands.get_mut(\"run\") {\n            prepare_task_runner(run);\n        }\n\n        if let Some(tasks_run) = spec\n            .cmd\n            .subcommands\n            .get_mut(\"tasks\")","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/jdx/mise/blob/afd2eddd3a50c16190efc1c7e94404b48f72af57/src/cli/usage.rs#L14-L50","documentation":"mise generates its CLI completion/usage spec by serializing the clap `Cli` definition to KDL via `Cli::to_kdl()` and parsing it back. If clap's own output cannot be re-parsed by the usage parser, this `.expect()` panics — it is a build-time-consistency invariant between two internal representations that must never drift.","triggerScenarios":"A clap attribute or flag definition that the usage KDL parser does not understand (new/odd clap syntax, unusual value names); a mismatched `clap` and `clap_usage`-style parser version after a dependency bump; local modifications to command definitions.","commonSituations":"Contributors adding a new CLI flag with exotic attributes then running `mise usage` or generating completions; dependency updates changing clap serialization output.","solutions":["Report the panic with the mise version and command to the mise repository (this is a code bug, not user error)","Rebuild from a clean checkout (`mise run clean && mise run build`) to rule out stale artifacts","Check for a recent clap dependency update in Cargo.lock and pin/revert it if this appeared after `cargo update`","Use the latest released mise, where the clap/usage pair is known compatible"],"exampleFix":"// before\nlet mut spec: usage::Spec = Cli::to_kdl().parse().expect(\"generated mise usage spec\");\n// after\nlet mut spec: usage::Spec = Cli::to_kdl().parse()\n    .wrap_err_with(|| format!(\"failed to parse generated usage spec: {}\", Cli::to_kdl()))?;","handlingStrategy":"fallback","validationCode":"# In CI before relying on completions:\ntarget/debug/mise usage >/dev/null || echo \"usage spec generation broken\"","typeGuard":null,"tryCatchPattern":"// When embedding spec generation:\nlet spec = match std::panic::catch_unwind(mise_usage::spec) {\n    Ok(s) => s,\n    Err(_) => return Err(anyhow!(\"mise usage spec generation panicked; report upstream\")),\n};","preventionTips":["Keep clap and usage-parser dependencies updated together","Run `mise run lint`/`mise run test` after adding CLI flags","Never hand-edit generated usage output"],"tags":["rust","panic","internal-invariant","completions","clap"],"backgroundTag":"internal-invariant-violation","analyzedSha":"afd2eddd3a50c16190efc1c7e94404b48f72af57","analyzedAt":"2026-09-09T01:38:25.179Z","contentChangedAt":"2026-09-09T01:38:25.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}