Detector commands and configuration
The detector gives engineers a direct way to scan local UI source, HTML files, and rendered pages without an AI provider. Its command layer turns user arguments into a scan, applies project policy and design context, and reports findings in text or machine-readable JSON. The same CLI also routes the related review and capture commands used to prepare browser evidence.
Scan entrypoints
The impeccable command is the main user entrypoint for scans. Engineers can use the explicit detect command or pass a target directly as shorthand; an installed skill also exposes skill/…/detect.mjs, which locates the bundled detector and forwards its arguments to the same CLI flow. The native binary keeps command routing in one place, so detect and ignores remain distinct from review, capture, and build-phase verbs.
Target forms
Targets tell the detector what kind of input to inspect. A directory or local file uses source analysis, while an http(s):// or file:// target requests a browser-rendered scan. With no target, the command scans the current directory or reads piped input when standard input is not a terminal.
flowchart LR
A[User command] --> B{Target form}
B -->|Local directory| C[Walk project files]
B -->|Local file| D[Scan one file]
B -->|HTTP or file URL| E[Render in browser]
B -->|Piped input| F[Read stdin]
C --> G[Findings and exit status]
D --> G
E --> G
F --> G
The shorthand rule treats flags, URLs, path-shaped values, and existing paths as scan targets. A bare unknown word is rejected as an unknown command instead of being silently treated as a path.
References: cli/…/cli.js• L20-29 cli/…/cli.js• L75-89 cli/…/main.mjs• L292-325 crates/…/main.rs• L27-59 crates/…/main.rs• L105-118
Scan options
Options tailor the report without changing the detector rules. The two output modes serve different callers: text is for people, while JSON preserves findings for scripts and agent workflows.
| Option | User-facing effect |
|---|---|
--json | Print the full finding list as JSON. |
--quiet | Print only the final count in text mode. |
--scope <name> | Limit results to a design domain such as type or layout; comma-separated values are accepted. |
--viewport <WxH> | Set the browser viewport for URL scans. |
--no-config | Run without project config, detector ignores, inline ignores, or design context. |
--no-inline-ignores | Keep project config but honor no in-file waiver comments. |
--no-design-system | Do not load local design-system guidance. |
--no-advisory | Hide advisory findings. |
--help | Show scan usage and examples. |
The command validates scope names and viewport dimensions before scanning. A missing value or unknown scope fails the command instead of silently running a different scan. The old --fast, --gpt, and --gemini flags remain accepted for compatibility but do not change the current scan. The detector does not download or select an AI provider as part of this flow.
References: cli/…/main.mjs• L147-195 cli/…/main.mjs• L198-268
Related command entrypoints
The same impeccable binary exposes review and capture verbs beside detect. These commands support the wider quality workflow: they create or compare visual specifications, check fonts, review components, or run a local capture service for a build-phase check. They do not change the detector rule set.
| Command | User-facing purpose |
|---|---|
component-review | Prepare component previews for human review. |
comp-spec | Create or inspect visual comparison specifications. |
comp-diff | Compare captured output with a reference. |
font-match | Check rendered fonts against a reference. |
capture-server | Keep a project-scoped native capture service available to a host workflow. |
build-phase | Run the build-phase checks with local or remote capture support. |
hook and hook-before-edit | Run edit-time checks through the hook path. |
The command router selects these verbs before it applies the target shorthand rule. A partial native capture-service setup is an error rather than a fallback to another capture path, which keeps the selected review boundary clear.
References: crates/…/main.rs• L57-103 crates/…/capture_service.rs• L373-392 crates/…/capture_service.rs• L456-482
Scan results
The detector separates findings into primary and advisory results. Primary findings determine the failure status; advisory findings remain visible in text and JSON but do not fail the scan, which lets teams review softer signals without blocking automation.
Output and exit status
Text output groups findings by file and includes the rule, location when available, snippet, and description. JSON emits one array containing all findings, with advisory findings marked for consumers that need to filter them.
| Result | Exit status |
|---|---|
| No findings | 0 |
| Advisory findings only | 0 |
| One or more primary findings | 2 |
| Invalid command input or operational error | 1 |
The final count in text mode excludes advisory notes. --no-advisory removes those notes before output and status calculation.
References: cli/…/main.mjs• L40-59 cli/…/main.mjs• L79-99 cli/…/main.mjs• L407-429
Running-site guidance
When a directory looks like a supported framework project, the detector checks whether its expected local development port is serving that project. If so, it suggests a URL scan because rendered behavior gives a more accurate view than source-only analysis. This is guidance only; the directory scan still proceeds.
The suggestion covers common Next.js, SvelteKit, Nuxt, Vite, Astro, Angular, and Remix project markers. A port used by another service is reported as a mismatch so the engineer does not mistake an unrelated page for the target project.
References: cli/…/main.mjs• L328-351 cli/…/file-system.mjs• L105-153 cli/…/file-system.mjs• L155-213
Project configuration
The unified .impeccable configuration gives a project one shared place to define detector policy. .impeccable/config.json holds shared settings; .impeccable/config.local.json adds per-developer settings and is kept out of Git through .git/info/exclude when the CLI writes it. The detector merges both files, so a local exception can narrow or extend the shared policy without changing team configuration.
Detector settings
The detector reads settings under detector. The most important settings control rule suppression, file scope, value-specific exceptions, design-system use, and advisory reporting.
| Setting | Purpose |
|---|---|
ignoreRules | Suppress a rule across the project. |
ignoreFiles | Suppress all detector findings for files matching configured globs. |
ignoreValues | Suppress a rule only for a matching value, with optional file scope. |
designSystem.enabled | Enable or disable local design-system context. |
advisoryRules | Preserve the advisory policy used by hook-aware flows. |
The CLI also reads older detector filters stored under hook for compatibility. New writes place detector settings under detector and preserve unrelated hook settings. Manual scans do not depend on hook.enabled; that field controls automatic hook execution only.
References: cli/…/impeccable-config.mjs• L10-16 cli/…/impeccable-config.mjs• L42-53 cli/…/impeccable-config.mjs• L101-147 skill/…/hooks.md• L11-15
Design-system context
When enabled, a scan loads the design system that governs each target rather than blindly using the process working directory. The system can come from DESIGN.md or a supported fallback location, with optional JSON sidecar data. A project boundary stops the search, which prevents one project’s design rules from affecting another project in a multi-project scan.
This context lets findings describe drift from a project’s documented fonts, colors, radii, or type scale. --no-design-system disables that context for a run, while detector.designSystem.enabled: false makes the choice persistent.
References: cli/…/design-system.mjs• L9-15 cli/…/design-system.mjs• L44-65 cli/…/design-system.mjs• L578-619 cli/…/main.mjs• L268-285
Template extensions
The automatic hook can scan server-side template files when the project declares them under detector.extensions. Each entry names a file ending and selects either markup analysis or text analysis. Built-in file types remain active, so this setting adds coverage rather than replacing the default set.
{
"detector": {
"extensions": [
{ "ext": ".blade.php", "engine": "html" },
{ "ext": ".twig", "engine": "html" }
]
}
}
This extension setting belongs to the hook configuration path because it expands the files considered during edit interception. The standalone CLI scan uses its own local file walk and built-in scan extensions.
References: skill/…/hooks.md• L13-15 skill/…/hook-lib.mjs• L52-71 skill/…/hook-lib.mjs• L323-344 skill/…/hook-lib.mjs• L1658-1665
Ignore controls
Ignore controls let a team record a deliberate exception without hiding unrelated findings. The preferred interface is impeccable ignores, which manages shared and local config entries; inline directives cover artifacts that must carry their waiver with the file itself.
Ignore command interface
The ignore command supports inspection, addition, removal, and clearing. Its scope flags make the persistence choice explicit: shared is the default, local is private, and --all is available for removal and clear operations.
| Command | Scope of the exception |
|---|---|
impeccable ignores list | Show merged, shared, and local detector ignores. |
impeccable ignores add-rule <rule> | Suppress one rule project-wide. |
impeccable ignores add-file <glob> | Suppress every rule for matching files. |
impeccable ignores add-value <rule> <value> | Suppress one rule/value pair. |
impeccable ignores remove-* | Remove a matching rule, file, or value exception. |
impeccable ignores clear | Clear detector ignores in the selected scope. |
Value ignores can carry a reason and can be limited to one or more file globs. The command rejects empty file scopes and unknown value flags instead of writing a broader exception than the user requested. A wildcard value must have a file scope, which prevents a broad rule suppression from being created by mistake. overused-font is value-specific by default; broad suppression requires an explicit all-values choice.
References: cli/…/ignores.mjs• L33-61 cli/…/ignores.mjs• L64-137 cli/…/ignores.mjs• L188-241 cli/…/ignores.mjs• L264-329
Ignore matching
File ignores match normalized paths and support common glob forms such as **, *, ?, and brace alternatives. Rule ignores remove findings by rule id. Value ignores match the finding’s relevant value; CSS colors are compared in a normalized color form so equivalent spellings can share one exception.
The merged config combines shared and local rules and files. For duplicate value entries, the local entry takes precedence, which allows a developer’s reason or scope to refine a shared entry. Malformed config files are ignored rather than stopping a scan.
References: cli/…/impeccable-config.mjs• L72-94 cli/…/impeccable-config.mjs• L325-369 cli/…/impeccable-config.mjs• L371-441 cli/…/impeccable-config.mjs• L443-481
Inline directives
Inline directives are comment markers that suppress findings at the place where the waiver applies. They support whole-file, same-line, and next-line scope, plus one or more rule ids; a bare directive or * means every rule. The syntax works across the comment forms used by HTML, CSS, JavaScript, JSX, and template files.
Use config ignores for project policy. Use an inline directive when a standalone export, generated document, or moved snippet must retain its own narrow waiver. --no-inline-ignores disables these directives for one run, and --no-config disables them as part of a raw scan.
References: cli/…/inline-ignores.mjs• L1-32 cli/…/inline-ignores.mjs• L35-57 cli/…/inline-ignores.mjs• L73-112 cli/…/inline-ignores.mjs• L135-148 cli/…/main.mjs• L268-273
User invocation paths
Engineers can invoke the detector directly, through an installed skill, or through an automatic agent hook. These paths share the detector’s rule and ignore behavior but differ in when they run and how they return findings.
| Invocation path | Best use | User-visible result |
|---|---|---|
npx impeccable detect ... | Full manual scan or CI check. | Text or JSON plus a meaningful exit status. |
node <scripts>/detect.mjs ... | Agent-guided scan of selected web files. | Detector output for the calling workflow. |
| Design hook | Feedback during supported agent edits. | A reminder or write block, depending on the harness. |
| URL scan | Review the rendered page and computed browser state. | Browser-grade findings for the target page. |
The installed skill checks whether a build phase is still open before it runs the detector. If one is open, it writes a warning to standard error and still runs the scan, so JSON output on standard output remains parseable. A detector pass does not by itself mark that build phase complete.
The hook uses the same project detector filters as a manual scan, but hook.enabled only controls whether the automatic path runs. The CLI remains available when the hook is disabled. This separation lets a project turn off edit-time interruptions while keeping explicit scans and CI checks active.
References: skill/…/detect.mjs• L7-30 cli/…/impeccable-config.mjs• L101-115 skill/…/hooks.md• L1-17 skill/…/hook-lib.mjs• L37-44
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the CLI parser, usage text, and the raw scan behavior aligned when adding or removing a scan option.
- Keep the detector config schema and its CLI-side and hook-side readers aligned so a suppression behaves the same in manual and automatic scans.
- Keep shared/local merge rules aligned with ignore command writes, especially for value scopes and local precedence.
- Keep build-phase warnings on standard error so machine-readable detector output stays valid.
- Keep native capture command selection aligned with the local or remote capture service contract. A partial service setup must not silently select a different renderer.
- Keep static entry capture bound to the selected artifact, spec, reference, and declared dependencies. The approved reference must remain bound input and must not become page input.
- Regenerate the browser detector when browser-safe detector source changes; the checked-in browser entrypoint is generated output.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
A bare --scope or malformed --viewport value | The command exits before scanning. | Supply a named scope or a WxH viewport. |
An empty or flag-like --file value | The ignore command refuses the entry instead of creating an unintended project-wide suppression. | Supply a non-empty file glob. |
A wildcard value ignore has no --file scope | The ignore command refuses the broad exception. | Use a file-scoped wildcard or an explicit rule ignore. |
| A non-wildcard value cannot produce a finding value | The ignore command refuses an exception that cannot match a finding. | Use the finding’s supported value or a file-scoped wildcard. |
| A config file is malformed | That file contributes no settings, so expected suppressions may not apply. | Check impeccable ignores list and repair the JSON. |
| A framework dev server port serves another app | A URL scan can inspect the wrong page. | Use the detector’s framework mismatch warning and start the target server. |
| A build phase is open when the skill runs | The scan may pass while the page is still not considered complete. | Read the COMP_ROUND_OPEN warning and follow the build-phase status guidance. |
| Native capture service variables are only partly set | The command refuses the setup instead of silently using local capture. | Set both the valid port and capability or remove both variables. |
| A static entry loads the approved comp or a copy of it | Capture is refused because the page could pass by showing the reference. | Serve only declared dependencies and draw the page without the approved reference. |
| A declared raster region has no matching receipt or the page is unstable | The native entry result is rejected before build-phase comparison. | Keep one stable receipt per declared region and capture from unchanged inputs. |
Key files
| File | Why to read it |
|---|---|
| cli/…/cli.js | Defines the public CLI commands and shorthand target behavior. |
| cli/…/main.mjs | Defines scan options, target routing, output, config use, and exit status. |
| crates/…/main.rs | Routes the detector, ignore, hook, review, and native capture verbs through the shipped binary. |
| cli/…/impeccable-config.mjs | Defines the shared/local detector config model and ignore matching. |
| cli/…/ignores.mjs | Defines the user-facing ignore management commands and their safety checks. |
| cli/…/inline-ignores.mjs | Defines file-local waiver syntax and scope. |
| cli/…/design-system.mjs | Defines how target-specific design context is found and loaded. |
| skill/…/detect.mjs | Defines the installed skill entrypoint, build-phase warning, and detector handoff. |
| skill/…/hooks.md | Describes how manual scans, config, ignores, and automatic hooks relate for users. |
| crates/…/entry_capture.rs | Defines the user-facing native entry capture stages and their input boundaries. |
| crates/…/capture_service.rs | Defines the optional project-scoped capture service and its remote command boundary. |
| crates/…/capture_snapshot.rs | Defines the frozen static inputs used by native capture. |
| crates/…/component_capture.rs | Defines native component preview capture for the component review flow. |
| crates/…/entry_capture.rs | Shows the user-visible refusal and stability guarantees for native entry capture. |