# Manage detector ignores

> Add, list, and remove ignoreRules, ignoreFiles, and ignoreValues in shared or local config, including value scoping, reasons, and inline disable comments.

- Repository: pbakaus/impeccable
- GitHub: https://github.com/pbakaus/impeccable
- Human docs: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4
- Complete Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/llms-full.txt

## Source Files

- `cli/bin/commands/ignores.mjs`
- `cli/lib/impeccable-config.mjs`
- `cli/engine/shared/inline-ignores.mjs`
- `skill/scripts/hook-lib.mjs`
- `tests/cli-ignores.test.js`
- `tests/inline-ignores.test.mjs`

---

---
title: "Manage detector ignores"
description: "Add, list, and remove ignoreRules, ignoreFiles, and ignoreValues in shared or local config, including value scoping, reasons, and inline disable comments."
---

Detector ignores live under the `detector` key in `.impeccable/config.json` (shared) and `.impeccable/config.local.json` (per-developer). `npx impeccable detect` and the design hook both load the merged config; `npx impeccable ignores` is the CLI CRUD surface for the same keys. Inline `impeccable-disable*` comments suppress findings inside a single file without writing config.

## Ignore kinds

| Config key | Effect | Typical use |
|---|---|---|
| `ignoreRules` | Drop every finding for listed rule ids project-wide | Rule is never relevant for this product |
| `ignoreFiles` | Skip matching paths entirely (all rules) | Fixtures, generated assets, deliberate slop demos |
| `ignoreValues` | Drop findings for a rule when the extracted value matches; optional `files` globs scope the entry | Brand fonts, intentional motion, one noisy rule in one file |

```json
{
  "detector": {
    "ignoreRules": ["side-tab"],
    "ignoreFiles": ["src/legacy/**", "tests/fixtures/**"],
    "ignoreValues": [
      {
        "rule": "overused-font",
        "value": "inter",
        "createdAt": "2026-04-01T12:00:00.000Z",
        "reason": "Brand font"
      },
      {
        "rule": "side-tab",
        "value": "*",
        "files": ["**/TopicCard.jsx"],
        "createdAt": "2026-04-01T12:05:00.000Z",
        "reason": "CSS triangle decoration"
      }
    ]
  }
}
```

<Info>
Legacy builds stored the same arrays under `hook.*`. Readers still accept that layout, but every write migrates detector keys into `detector` and strips them from `hook`.
</Info>

## Shared vs local scope

| File | Default for writes | Intended ownership |
|---|---|---|
| `.impeccable/config.json` | Yes (`--shared`) | Team-reviewed, commit with the repo |
| `.impeccable/config.local.json` | `--local` | Personal exceptions |

`config.local.json` is added to `.git/info/exclude` on first local write (`# impeccable-config-ignore-start` … `# impeccable-config-ignore-end`). Merged reads apply shared first, then local: arrays union; `ignoreValues` dedupe on `rule` + normalized `value` + sorted `files`.

| Flag | Where it applies |
|---|---|
| `--shared` | Shared config only (default for add) |
| `--local` | Local config only |
| `--all` | Shared **and** local; remove and clear only |

## CLI: `impeccable ignores`

```bash
npx impeccable ignores <action> [options]
# alias: npx impeccable ignore ...
```

### Actions

| Action | Aliases | Arguments |
|---|---|---|
| `list` | `status`, `ls` (default) | none |
| `add-rule` | `ignore-rule` | `<rule>` [`--all-values`] |
| `add-file` | `ignore-file` | `<glob>` |
| `add-value` | `ignore-value`, `update-value` | `<rule> <value>` [`--file <glob>`…] [`--reason <text>`] |
| `remove-rule` | `rm-rule` | `<rule>` |
| `remove-file` | `rm-file` | `<glob>` |
| `remove-value` | `rm-value` | `<rule> <value>` [`--file <glob>`…] |
| `clear` | | none (clears all three arrays in the selected scope) |

### Value and rule options

<ParamField body="--file" type="string">
Scope an `add-value` / `remove-value` entry to one or more globs. Repeatable. Empty globs and flag-looking values (for example `--file --reason`) are rejected.
</ParamField>

<ParamField body="--reason" type="string">
Optional documentation stored on the `ignoreValues` entry. On re-add with the same key, updates the stored reason. Accepted on `add-rule` for symmetry but not stored on `ignoreRules`.
</ParamField>

<ParamField body="--all-values" type="boolean">
Required to put `overused-font` into `ignoreRules`. Without it the CLI refuses and points at `add-value`.
</ParamField>

### Value normalization

Stored and compared values are normalized: trim, strip wrapping quotes, `+` → space, collapse whitespace, lowercase. `design-system-color` also matches equivalent colors across hex / `rgb()` / `hsl()` forms.

Value-bearing rules for extraction and ignore matching:

- `overused-font`
- `bounce-easing`
- `design-system-font`
- `design-system-color`
- `design-system-radius`
- `design-system-font-size`

Rules without an extractable value (for example `side-tab`) only match a value ignore when the entry is a file-scoped wildcard (`value: "*"` plus `files`).

### Wildcard policy

A bare `add-value <rule> "*"` is refused. Scope it:

```bash
npx impeccable ignores add-value side-tab "*" --file "components/TopicCard.jsx"
```

Project-wide rule silence uses `add-rule`, not an unscoped wildcard. Existing unscoped wildcards on disk can still be removed with `remove-value` (removal allows unscoped `*`).

### Examples

```bash
# List merged + per-file views
npx impeccable ignores list

# Ignore a whole path tree (shared)
npx impeccable ignores add-file "src/legacy/**"

# Brand font (shared, with reason)
npx impeccable ignores add-value overused-font Inter --reason "Brand font"

# One rule, one file only
npx impeccable ignores add-value design-system-color "*" --file "src/demo.css"

# Personal exception
npx impeccable ignores add-value overused-font Roboto --local --reason "Sandbox prototype"

# Broad rule suppress (overused-font needs the flag)
npx impeccable ignores add-rule overused-font --all-values

# Remove and clear
npx impeccable ignores remove-value overused-font Inter
npx impeccable ignores remove-file "src/legacy/**" --all
npx impeccable ignores clear --local
```

### List output shape

```text
Impeccable detector ignores
  shared file: .impeccable/config.json
  local file:  .impeccable/config.local.json

Merged:
  ignoreRules:  ...
  ignoreFiles:  ...
  ignoreValues: overused-font=inter - Brand font, side-tab=* [**/TopicCard.jsx]
  designSystem: enabled

Shared:
  ...

Local:
  ...
```

`ignoreValues` lines print as `rule=value`, optional `[file, …]`, optional `- reason`.

## Prefer the narrowest exception

| Situation | Prefer |
|---|---|
| Confirmed brand font / motion / token value | `add-value <rule> <value>` |
| One non-value rule noisy in one file | `add-value <rule> "*" --file <glob>` |
| Entire path out of design review | `add-file <glob>` |
| Rule never applies product-wide | `add-rule <id>` (and `--all-values` for `overused-font`) |
| Waiver must travel with an exported standalone file | Inline `impeccable-disable*` comment |

<Warning>
`ignoreFiles` silences **every** current and future rule for matching paths. Prefer a file-scoped `ignoreValues` entry when the surface should still be reviewed for other issues.
</Warning>

## Design hook path

The skill’s hooks admin writes the same `detector` keys. Prefer the dedicated CLI for bulk CRUD; use the hook flow when confirming an intentional finding from an edit-time scan.

```bash
# Skill-invoked admin (same config files)
node <scripts_path>/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
node <scripts_path>/hook-admin.mjs ignore-value side-tab "*" --file "src/components/TopicCard.jsx"
node <scripts_path>/hook-admin.mjs ignore-file "src/legacy/**"
node <scripts_path>/hook-admin.mjs ignore-rule overused-font --all-values
```

The hook never auto-writes ignores. Persist only after explicit confirmation that the finding is intentional.

## Inline disable comments

Config is the default for repo policy. Inline directives cover waivers that belong **in the file** (exported HTML, emailed docs, snippets scanned out of context).

| Directive | Scope |
|---|---|
| `impeccable-disable <rule>[, <rule>...]` | Whole file |
| `impeccable-disable-line <rule>...` | Same line |
| `impeccable-disable-next-line <rule>...` | Following line |
| bare `impeccable-disable` or `impeccable-disable *` | Every rule |

Reasons are optional after eslint-style `--` or biome-style `:` and are discarded at scan time (they only keep free text out of the rule list). Keyword match is case-insensitive. Comment syntax is ignored: `//`, `/* */`, `<!-- -->`, `#`, `{/* */}`, `{# #}` all work; trailing closers are stripped.

```css
/* impeccable-disable overused-font -- exported brand doc */
.brand { font-family: Inter; }

.a { font-family: Inter; } /* impeccable-disable-line overused-font */

/* impeccable-disable-next-line bounce-easing: intentional playful affordance */
.ball { animation: bounce-ball 1s; }
```

```html
<!-- impeccable-disable overused-font -- standalone export -->
```

Findings without a line number (common for static HTML page-level rules) only match whole-file directives.

### Engine integration

`detectText` and `detectHtml` apply inline directives after rule evaluation unless disabled:

| Detect flag | Behavior |
|---|---|
| (default) | Load project config + honor inline directives |
| `--no-inline-ignores` | Keep config filters; ignore inline comments |
| `--no-config` | Skip project ignores **and** inline directives |

```bash
npx impeccable detect src/
npx impeccable detect --no-inline-ignores src/widget.css
npx impeccable detect --no-config --json src/   # raw scan
```

After per-file detection, the CLI runs `filterDetectionFindings` (rules + values) and skips paths matched by `ignoreFiles` before scanning.

## Glob matching

`ignoreFiles` and per-entry `files` support `*`, `**`, `?`, and `{a,b}` alternation. Matching tries the raw path, absolute path, path relative to the project root, and for value scopes each path suffix (so `**/TopicCard.jsx` and `TopicCard.jsx` can both match `components/TopicCard.jsx`).

## Verify

```bash
npx impeccable ignores list
npx impeccable detect --json path/to/file.tsx
# Expect: suppressed findings absent; exit 0 when no non-advisory findings remain
npx impeccable detect --no-config --json path/to/file.tsx
# Expect: same issues return if only config was suppressing them
```

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| `Wildcard value ignores must be scoped with --file` | `add-value … "*"` without `--file`; use `--file` or `add-rule` |
| `overused-font is value-specific by default` | Used `add-rule overused-font` without `--all-values` |
| `--file` / `--reason` errors | Empty glob, or a flag consumed as a glob; pass a non-empty glob string |
| Remove reports “No matching…” | Scope mismatch (`--local` vs shared), different `files` set, or value not normalized the same way |
| Local file missing from git status | Expected: local config is exclude-listed under `.git/info/exclude` |
| Inline comment not honored | Typo in directive name; or scan used `--no-inline-ignores` / `--no-config` |
| Line-scoped directive missed a page-level finding | Line-less findings only match whole-file `impeccable-disable` |

## Related pages

<CardGroup>
  <Card title="Design hook" href="/design-hook">
    Edit-time scans, intentional-finding workflow, and quiet/disabled controls that share these ignores.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Full `detect` / `ignores` flags, JSON output, and exit codes.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    Complete `.impeccable/config.json` and `config.local.json` schema.
  </Card>
  <Card title="Detector rules" href="/detector-rules">
    Rule ids, categories, and finding shape used in ignore keys.
  </Card>
  <Card title="Detect in CI" href="/detect-in-ci">
    Non-interactive detect with project ignores and exit code 0 vs 2.
  </Card>
</CardGroup>