{"record":{"id":"c4d641629c6db813","repo":"pbakaus/impeccable","slug":"reason-is-not-supported-for-ignore-file-because","errorCode":null,"errorMessage":"--reason is not supported for ignore-file because detector.ignoreFiles stores globs only; use ignore-value when a documented rule-specific exception fits","messagePattern":"--reason is not supported for ignore-file because detector\\.ignoreFiles stores globs only; use ignore-value when a documented rule-specific exception fits","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"skill/scripts/hook-admin.mjs","lineNumber":601,"sourceCode":"  const config = mergeDetectorConfig(readRawDetectorConfig(cwd));\n  if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);\n  writeDetectorConfig(cwd, config);\n  return `Added \"${rule}\" to detector.ignoreRules. Current: ${config.ignoreRules.join(', ')}`;\n}\n\nfunction parseIgnoreFileArgs(args) {\n  const positionals = [];\n  let shared = false;\n  let local = false;\n\n  for (const raw of args) {\n    const arg = String(raw || '');\n    if (arg === '--shared') {\n      shared = true;\n    } else if (arg === '--local') {\n      local = true;\n    } else if (arg === '--reason' || arg.startsWith('--reason=')) {\n      throw new Error('--reason is not supported for ignore-file because detector.ignoreFiles stores globs only; use ignore-value when a documented rule-specific exception fits');\n    } else if (arg.startsWith('--')) {\n      throw new Error(`Unknown ignore-file flag: ${arg}`);\n    } else {\n      positionals.push(arg);\n    }\n  }\n\n  if (shared && local) throw new Error('Pass only one scope flag: --shared or --local');\n  if (positionals.length > 1) throw new Error('Pass exactly one glob to ignore-file');\n\n  return {\n    glob: positionals[0],\n    local,\n  };\n}\n\nfunction addIgnoreFile(cwd, args) {\n  const parsed = parseIgnoreFileArgs(args);","sourceCodeStart":583,"sourceCodeEnd":619,"githubUrl":"https://github.com/pbakaus/impeccable/blob/f88b2837a7d7c3182e46307bbbb091a1ed547571/skill/scripts/hook-admin.mjs#L583-L619","documentation":"Thrown by parseIgnoreFileArgs when --reason (space or equals form) is passed to `hooks ignore-file`. The detector.ignoreFiles config stores plain glob strings with no metadata, so a reason has nowhere to live and would otherwise be silently dropped. The error steers users to ignore-value, whose entries do carry a reason field.","triggerScenarios":"`hooks ignore-file \"src/legacy/**\" --reason \"legacy code\"`; `hooks ignore-file --shared build/** --reason=generated`; scripts that uniformly append --reason to every ignore subcommand.","commonSituations":"Users applying the same flag set across ignore-rule (which accepts --reason for symmetry) and ignore-file; audit trails that want to document why a glob is suppressed.","solutions":["Drop --reason from the ignore-file invocation; document the rationale elsewhere (commit message, PR description).","If the suppression is actually a rule-specific exception for a value, use `hooks ignore-value <rule> <value> --file <glob> --reason \"...\"`, which stores the reason."],"exampleFix":"# before\nimpeccable hooks ignore-file \"src/legacy/**\" --reason \"frozen legacy area\"\n\n# after\nimpeccable hooks ignore-file \"src/legacy/**\"\nimpeccable hooks ignore-value overused-font Roboto --file \"src/legacy/**\" --reason \"legacy brand font\"","handlingStrategy":"validation","validationCode":"const args = ['src/legacy/**'];\nif (reason) {\n  // ignore-file cannot store reasons; route rule-specific exceptions to ignore-value\n  if (ruleId && value) args.push('--file', 'src/legacy/**'); // ignore-value path instead\n}\n// simplest: never append --reason to ignore-file invocations","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep per-subcommand flag lists pinned near your wrapper: ignore-file accepts --shared/--local only.","Record suppression rationale in commit messages or PRs, not in flags the target command cannot store.","Use ignore-value --reason when the reason genuinely belongs to a rule/value exception."],"tags":["cli","unsupported-flag","hook-admin","ignore-file"],"backgroundTag":"unsupported-flag-combination","analyzedSha":"f88b2837a7d7c3182e46307bbbb091a1ed547571","analyzedAt":"2026-08-18T04:58:36.608Z","contentChangedAt":"2026-08-18T04:58:36.608Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}