{"record":{"id":"3a925097608b88a0","repo":"affaan-m/ECC","slug":"write-requires-json-markdown-or-format-j-3a9250","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/operator-readiness-dashboard.js","lineNumber":222,"sourceCode":"    if (arg.startsWith('--generated-at=')) {\n      parsed.generatedAt = arg.slice('--generated-at='.length);\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).filter(Boolean);\n\n  return parsed;\n}\n\nfunction readText(rootDir, relativePath) {\n  try {\n    return fs.readFileSync(path.join(rootDir, relativePath), 'utf8');\n  } catch (_error) {\n    return '';\n  }\n}\n\nfunction fileExists(rootDir, relativePath) {\n  return fs.existsSync(path.join(rootDir, relativePath));\n}","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/operator-readiness-dashboard.js#L204-L240","documentation":"Thrown by parseArgs in scripts/operator-readiness-dashboard.js when --write is supplied but the output format remains 'text' (the default). Writing to a file only makes sense for a machine-readable format, so the combination is rejected. Set --json or --markdown (or --format json|markdown) alongside --write.","triggerScenarios":"Running `--write report.txt` with no format flag; passing `--write` with `--format text` explicitly. The check fires only when format === 'text', so any of --json/--markdown/--format=json/--format=markdown satisfies it.","commonSituations":"Adding --write to an existing text-mode invocation without changing the format; assuming text output can be dumped to a file (the script deliberately disallows it).","solutions":["Add --json or --markdown when using --write: `--write report.json --json`.","Or use `--format json` / `--format markdown` alongside --write.","If you only want terminal text output, drop --write entirely."],"exampleFix":"// before\nnode scripts/operator-readiness-dashboard.js --write report.txt\n// after\nnode scripts/operator-readiness-dashboard.js --write report.json --json","handlingStrategy":"validation","validationCode":"function reconcileWriteWithFormat(args) {\n  const wantsWrite = args.includes('--write') || args.some(a => a.startsWith('--write='));\n  const isMachine = args.includes('--json') || args.includes('--markdown') || args.some(a => /^--format=(json|markdown)$/.test(a));\n  if (wantsWrite && !isMachine) {\n    throw new Error('--write requires --json, --markdown, or --format=json|markdown');\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair --write with --json or --markdown in wrappers.","If a CI variable toggles --write conditionally, toggle the format flag in lockstep.","Treat text output as terminal-only and never route it to --write."],"tags":["cli","operator-dashboard","argument-validation"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}