pbakaus/impeccable · error · Error

--reason is not supported for ignore-file because detector.i

Error message

--reason is not supported for ignore-file because detector.ignoreFiles stores globs only; use ignore-value when a documented rule-specific exception fits

What it means

Thrown by parseIgnoreFileArgs when --reason or --reason=<text> is passed to ignore-file. detector.ignoreFiles stores only glob patterns, so a per-reason file suppression has no place to live. The error steers the user toward ignore-value, which supports documented rule-specific exceptions. This is a hard refusal, not a warning, because silently dropping --reason would let the user believe a reason-scoped suppression was recorded when it was not.

Source

Thrown at skill/scripts/hook-admin.mjs:601

  const config = mergeDetectorConfig(readRawDetectorConfig(cwd));
  if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
  writeDetectorConfig(cwd, config);
  return `Added "${rule}" to detector.ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
}

function parseIgnoreFileArgs(args) {
  const positionals = [];
  let shared = false;
  let local = false;

  for (const raw of args) {
    const arg = String(raw || '');
    if (arg === '--shared') {
      shared = true;
    } else if (arg === '--local') {
      local = true;
    } else if (arg === '--reason' || arg.startsWith('--reason=')) {
      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');
    } else if (arg.startsWith('--')) {
      throw new Error(`Unknown ignore-file flag: ${arg}`);
    } else {
      positionals.push(arg);
    }
  }

  if (shared && local) throw new Error('Pass only one scope flag: --shared or --local');
  if (positionals.length > 1) throw new Error('Pass exactly one glob to ignore-file');

  return {
    glob: positionals[0],
    local,
  };
}

function addIgnoreFile(cwd, args) {
  const parsed = parseIgnoreFileArgs(args);

View on GitHub (pinned to d14711ae3d)

Solutions

1. Drop --reason from the ignore-file call — detector.ignoreFiles accepts globs only.
2. If a documented rule-specific exception fits, use `impeccable hooks ignore-value <rule> <value> --reason <text>` instead.
3. Record the reason in a commit message or comment rather than expecting ignore-file to store it.

Example fix

# before
impeccable hooks ignore-file "src/legacy/**" --reason "legacy module"

# after (ignore-file stores globs only)
impeccable hooks ignore-file "src/legacy/**"
# if a rule-specific exception fits:
impeccable hooks ignore-value side-tab inter --reason "legacy module"

// Strip --reason from ignore-file invocations before they reach the parser.
function stripReasonForIgnoreFile(args) {
  const out = [];
  for (let i = 0; i < args.length; i++) {
    if (args[i] === '--reason') { i++; continue; }      // skip value too
    if (String(args[i]).startsWith('--reason=')) continue;
    out.push(args[i]);
  }
  return out;
}

When it happens

Trigger: Copy-pasting --reason from an ignore-value invocation into ignore-file; expecting per-reason file exclusions; a wrapper that always forwards --reason.

Common situations: A user who suppresses a finding for 'this legacy file' and wants the reason recorded; CI automation that attaches --reason uniformly.

Related errors

• overused-font is value-specific by default. Use ${IMPECCABLE
• Unknown ignore-rule flag: ${arg}
• Pass a rule id, e.g. ${IMPECCABLE_COMMAND} hooks ignore-rule
• Unknown ignore-file flag: ${arg}
• Pass only one scope flag: --shared or --local

AI-assisted analysis of pbakaus/impeccable@d14711ae3d (2026-08-13). Data as JSON: /api/errors/c4d641629c6db813. Report an issue: GitHub.