{"record":{"id":"555c52213e4739da","repo":"affaan-m/ECC","slug":"write-requires-json-markdown-or-format-j-555c52","errorCode":null,"errorMessage":"--write requires --json, --markdown, or --format json|markdown","messagePattern":"--write requires --json, --markdown, or --format json\\|markdown","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"scripts/platform-audit.js","lineNumber":210,"sourceCode":"    if (arg === '--use-env-github-token') {\n      parsed.useEnvGithubToken = true;\n      continue;\n    }\n\n    if (arg === '--exit-code') {\n      parsed.exitCode = true;\n      continue;\n    }\n\n    throw new Error(`Unknown argument: ${arg}`);\n  }\n\n  if (!['text', 'json', 'markdown'].includes(parsed.format)) {\n    throw new Error(`Invalid format: ${parsed.format}. Use text, json, or markdown.`);\n  }\n\n  if (parsed.writePath && parsed.format === 'text') {\n    throw new Error('--write requires --json, --markdown, or --format json|markdown');\n  }\n\n  parsed.allowUntracked = parsed.allowUntracked.map(normalizeRelativePrefix);\n\n  return parsed;\n}\n\nfunction normalizeRelativePrefix(value) {\n  return String(value || '')\n    .replace(/\\\\/g, '/')\n    .replace(/^\\.\\/+/, '')\n    .replace(/\\/+$/, '') + (String(value || '').endsWith('/') ? '/' : '');\n}\n\nfunction runCommand(command, args, options = {}) {\n  const result = spawnSync(command, args, {\n    cwd: options.cwd,\n    env: options.env || process.env,","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/platform-audit.js#L192-L228","documentation":"This error is thrown by parseArgs in scripts/platform-audit.js when the user passes --write (a file output path) together with the default text output format. The script can only persist results in machine-readable formats, so combining --write with text output is rejected as a contradictory CLI configuration. It prevents writing a text report where a structured output was expected.","triggerScenarios":"Running `node scripts/platform-audit.js --write report.txt` (or any --write value) without also passing --json, --markdown, or --format json|markdown, leaving parsed.format at its 'text' default.","commonSituations":"Developers scripting the audit to save output to disk but forgetting that text format is not writable; copy-pasting an invocation that previously used --json; automation wrappers adding --write unconditionally.","solutions":["Add --json or --markdown to the invocation when using --write","Pass --format json or --format markdown explicitly alongside --write","Drop --write and print the text report to stdout instead"],"exampleFix":"// before\nnode scripts/platform-audit.js --write report.out\n// after\nnode scripts/platform-audit.js --json --write report.json","handlingStrategy":"validation","validationCode":"const formats = ['json', 'markdown'];\nif (args.includes('--write') && !args.some(a => ['--json','--markdown','--format=json','--format=markdown'].includes(a))) {\n  throw new Error('--write also needs --json, --markdown, or --format json|markdown');\n}","typeGuard":"function isWritableFormat(format) {\n  return format === 'json' || format === 'markdown';\n}","tryCatchPattern":"try {\n  await main(argv);\n} catch (e) {\n  if (e.message.includes('--write requires')) {\n    console.error('Usage: add --json or --markdown when using --write');\n    process.exitCode = 2;\n  } else throw e;\n}","preventionTips":["Always pair --write with an explicit structured format flag","Default your shell aliases to include --json when writing output","Validate argv combinations in wrapper scripts before invoking","Read --help output for format/write constraints"],"tags":["cli","argument-validation","format"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}