{"record":{"id":"e0692f4534e35652","repo":"ccusage/ccusage","slug":"parse-cli-help-spec","errorCode":null,"errorMessage":"parse CLI help spec","messagePattern":"parse CLI help spec","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"rust/crates/ccusage-cli-parser/build.rs","lineNumber":24,"sourceCode":"mod help_codegen;\n\nconst CLI_HELP_JSON: &str = \"src/cli-help.json\";\nconst CLI_COMMANDS_JSON: &str = \"src/cli-commands.json\";\n\nfn main() {\n    println!(\"cargo:rerun-if-changed={CLI_HELP_JSON}\");\n    println!(\"cargo:rerun-if-changed={CLI_COMMANDS_JSON}\");\n    generate_cli_help_rs();\n}\n\nfn out_dir_path(file_name: &str) -> PathBuf {\n    PathBuf::from(env::var_os(\"OUT_DIR\").expect(\"OUT_DIR is set by cargo\")).join(file_name)\n}\n\nfn generate_cli_help_rs() {\n    let option_source = fs::read_to_string(CLI_HELP_JSON).expect(\"read CLI help spec\");\n    let command_source = fs::read_to_string(CLI_COMMANDS_JSON).expect(\"read CLI command spec\");\n    let option_sets = serde_json::from_str::<Value>(&option_source).expect(\"parse CLI help spec\");\n    let command_spec =\n        serde_json::from_str::<Value>(&command_source).expect(\"parse CLI command spec\");\n    let output = help_codegen::generate_cli_help_source(&option_sets, &command_spec);\n    fs::write(out_dir_path(\"cli-help.rs\"), output).expect(\"write generated CLI help\");\n}\n","sourceCodeStart":6,"sourceCodeEnd":30,"githubUrl":"https://github.com/ccusage/ccusage/blob/afebc5d2e0867eafbb525d1b660ce5558c1034cc/rust/crates/ccusage-cli-parser/build.rs#L6-L30","documentation":"generate_cli_help_rs parses the CLI help JSON with serde_json::from_str::<Value> and unwraps with expect(\"parse CLI help spec\"). If cli-help.json (the option_source file) contains invalid JSON or a structure that cannot deserialize as serde_json::Value (practically: any malformed JSON), the build script panics with 'parse CLI help spec' and the crate fails to compile. This is the parse step for the options spec, distinct from error [3] which is the read of the commands spec.","triggerScenarios":"cargo build/check on ccusage-cli-parser when the CLI help JSON file contains a syntax error (trailing comma, unquoted key, truncated file from a failed write or bad merge conflict resolution), or the file is empty/encoded incorrectly (BOM, non-UTF8).","commonSituations":"A merge conflict in cli-help.json resolved by committing conflict markers (<<<<<<) into the JSON; a codegen script that wrote a partial file; editing the spec by hand and introducing a JSON syntax error; a non-UTF8 file saved by an editor.","solutions":["Validate the CLI help JSON with a linter (jq . cli-help.json or any JSON validator) to find the exact syntax error and line.","Fix the malformed JSON — common culprits are leftover git conflict markers, trailing commas, or a truncated file from a failed generation run.","Regenerate the spec with its authoring/codegen script instead of editing it by hand.","Re-encode the file as UTF-8 without BOM if an editor changed the encoding."],"exampleFix":"// before (cli-help.json, bad merge resolution)\n{\n<<<<<<< HEAD\n  \"verbose\": {\"short\": \"v\"},\n=======\n  \"quiet\": {\"short\": \"q\"}\n>>>>>>> main\n}\n// after\n{\n  \"verbose\": {\"short\": \"v\"},\n  \"quiet\": {\"short\": \"q\"}\n}","handlingStrategy":"validation","validationCode":"// validate spec JSON before the build script consumes it\nlet option_source = fs::read_to_string(CLI_HELP_JSON).expect(\"read CLI help spec\");\nserde_json::from_str::<serde_json::Value>(&option_source)\n    .unwrap_or_else(|e| panic!(\"parse CLI help spec at {CLI_HELP_JSON}: {e}\"));\n// CI pre-flight:\n// jq empty cli-help.json || { echo \"invalid cli-help.json\"; exit 1; }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run jq (or a JSON schema check) on spec files in CI before building.","Regenerate specs with scripts rather than hand-editing them.","Resolve merge conflicts in JSON specs by regenerating, never by hand-editing markers.","Always save spec files as UTF-8 without BOM."],"tags":["build-script","json","parse-error","code-generation","serde"],"backgroundTag":"json-parse-error","analyzedSha":"afebc5d2e0867eafbb525d1b660ce5558c1034cc","analyzedAt":"2026-09-02T22:50:54.420Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}