{"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":"exception","errorClass":"Error","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/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/platform-audit.js#L192-L228","documentation":"Thrown by platform-audit when --write (a file path to persist the report) is set but the output format is still `text`. Writing a human-readable text report to a file is intentionally disallowed; --write requires a machine format (json or markdown) so downstream consumers get structured content. The guard fires after format validation, so format must already be valid.","triggerScenarios":"`--write report.json` with no `--json`/`--markdown` (defaults to text); combining `--write out.md` with `--format text`; an automation script that always passes --write but conditionally sets the format.","commonSituations":"User adds --write to a CI invocation that previously only printed text; mismatch between the --write filename extension and the actual format flag.","solutions":["Add the matching format flag: `--write report.json --json` or `--write report.md --markdown`.","Or set format explicitly: `--write report.json --format json`.","If you only want terminal text output, drop --write entirely."],"exampleFix":"# before\nnode scripts/platform-audit.js --write report.json\n# after\nnode scripts/platform-audit.js --write report.json --json","handlingStrategy":"validation","validationCode":"function reconcileWriteFormat(writePath, format) {\n  if (writePath && format === 'text') {\n    throw new Error('--write requires --json, --markdown, or --format json|markdown');\n  }\n  return { writePath, format };\n}","typeGuard":"function isMachineFormat(format) {\n  return format === 'json' || format === 'markdown';\n}","tryCatchPattern":"try {\n  parseArgs(process.argv);\n} catch (err) {\n  if (err.message.startsWith('--write requires')) {\n    console.error('Add --json or --markdown when using --write.');\n    process.exit(2);\n  }\n  throw err;\n}","preventionTips":["Always pair --write with --json or --markdown.","Match the --write file extension to the format (.json -> json, .md -> markdown).","Drop --write if you only want terminal text output."],"tags":["cli","argument-validation","platform-audit","output-format"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}