The design language that makes your AI harness better at design.
JavaScript
//! Port of `cli/engine/cli/main.mjs`: `detectCli()`, the text formatter, and
//! stdin dispatch.
use std::collections::BTreeSet;
use std::io::Write;
use impeccable_common::Io;
use impeccable_core::findings::Finding;
use impeccable_core::registry::{all_antipatterns, filter_by_scopes, rule_scopes};
use serde_json::Value;
use crate::config::{
filter_detection_findings, normalize_ignore_rule, read_detection_config, should_ignore_detection_file,
DetectionConfig,
};
use crate::design_system::{load_design_system_for_target, DesignSystemCache};
use crate::detect_text::{detect_text, ext_from_file_path, TextOptions};
use crate::project_tokens::{may_need_tokens, ProjectTokens};
use crate::engines::{EngineError, Engines, ScanOptions};
use crate::file_system::{
build_import_graph_reporting, detect_framework_config, is_port_listening, uses_html_engine,
walk_dir_reporting,
};
use crate::github_annotations::{
format_github_annotations, GITHUB_JSON_CONFLICT, GITHUB_LIST_RULES_CONFLICT,
};
use crate::jsp;
use crate::list_rules::{
collect_catalog_rules, format_list_rules_ids, format_list_rules_json, format_list_rules_text,
LIST_RULES_SCAN_ERROR,
};
use crate::util::{exists, re, D};
pub const USAGE: &str = "Usage: impeccable detect [options] [file-or-dir-or-url...]
Scan files or URLs for UI anti-patterns and design quality issues.
Options:
--json Output results as JSON
--quiet In text mode, only print the final findings count
--github Write GitHub Actions annotations for each
finding. Not with --json or --list-rules
--list-rules Print the detector rule catalog and exit. --json
for JSON, --quiet for ids only. Takes no targets
--scope <name> Only report rules in the given design domain
(type, layout). Comma-separated.
--viewport <WxH> Browser viewport for URL scans (default 1280x800),
e.g. --viewport 390x844 for a mobile-width pass
--no-config Do not apply project config, detector ignores, inline
ignore comments, or DESIGN.md
--no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
--no-design-system Do not load local DESIGN.md / .impeccable/design.json context
--no-advisory Suppress advisory findings entirely (e.g. em-dash overuse)
--no-consent-hiding URL scans: keep known consent managers' banners
(OneTrust, Cookiebot, ...) on the page instead of hiding
them before the scan
--no-overlay-hiding URL scans: keep product tours (driver.js) and
preloaders still covering the page instead of hiding
them before the scan
--cdp <port|url> Scan a page of a running Chromium-based desktop app
(Electron, NW.js, CEF, WebView2) through its local
DevTools port instead of loading a URL. The page is
scanned as shown and left as found: never navigated,
resized or closed. Takes no file or URL targets
--target <text> With --cdp: pick the page whose URL or title contains
this text when the app has more than one
--help Show this help message
Advisory findings:
Some rules are advisory: detected and listed in a separate section, but never
counted as failures and never changing the exit code. They stay out of the
failure count so they never block automation. --no-advisory hides them.
Output streams:
Human-readable findings go to stderr so stdout stays available for structured
output. Use --json for JSON on stdout, or redirect text with 2> findings.txt.
--github writes Actions annotations to stdout (no human findings).
--list-rules writes the catalog to stdout (no scan).
Exit status:
0 Scan completed with no primary findings (advisories may still be listed)
1 At least one requested target could not be scanned
2 Scan completed with primary findings
Operational failure takes precedence when a multi-target scan is partial.
Project config:
Respects .impeccable/config.json and .impeccable/config.local.json detector
settings: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues,
and detector.designSystem.enabled.
Inline ignores:
In-file comments waive a finding where it lives and travel with the file:
<!-- impeccable-disable overused-font -- exported brand doc -->
.brand { font-family: Inter } /* impeccable-disable-line overused-font */
// impeccable-disable-next-line bounce-easing: intentional bounce
impeccable-disable applies to the whole file; -line / -next-line are scoped.
List one or more rule ids (comma-separated), or omit them / use * for all.
Detection modes:
HTML files Static HTML/CSS analysis (default, catches linked CSS)
Non-HTML files Regex pattern matching (CSS, JSX, TSX, etc.)
URLs Puppeteer full browser rendering (auto-detected;
http(s):// and file:// URLs; accessible linked CSS included)
Running apps --cdp: a page of a Chromium-based app, attached through its
DevTools port and scanned like a URL
Examples:
impeccable detect src/
impeccable detect index.html
impeccable detect https://example.com
impeccable detect --cdp 9222 --target \"My App\" --json
impeccable detect --json .
impeccable detect --github src/
impeccable detect --list-rules
impeccable detect --no-config src/
";
/// Remove every `--name <value>` / `--name=<value>` from `args`. `None` when
/// the flag is absent, `Some(None)` when it has no value (the end of the
/// arguments, or another `--` flag next), else the last value given.
fn take_value_flag(args: &mut Vec<String>, name: &str) -> Option<Option<String>> {
let inline_prefix = format!("{name}=");
let mut found: Option<Option<String>> = None;
let mut i = 0;
while i < args.len() {
if let Some(v) = args[i].strip_prefix(&inline_prefix) {
found = Some(Some(v.to_string()).filter(|v| !v.is_empty()));
args.remove(i);
continue;
}
if args[i] != name {
i += 1;
continue;
}
args.remove(i);
match args.get(i) {
Some(v) if !v.starts_with("--") => found = Some(Some(args.remove(i))),
_ => found = Some(None),
}
}
found
}
fn format_finding_summary(count: usize) -> String {
format!(
"{count} anti-pattern{} found.",
if count == 1 { "" } else { "s" }
)
}
/// JS: main.mjs#expandJoinedUrlTargets
///
/// Some agent runners hand a shell-ready URL list to the process as one argv
/// value. A browser accepts the spaces as part of one encoded URL, producing a
/// plausible scan attributed to a bogus joined path. Expand only when every
/// whitespace-delimited token is independently a URL, preserving ordinary
/// filesystem paths that contain spaces.
fn expand_joined_url_targets(targets: Vec<String>) -> Vec<String> {
let mut out = Vec::with_capacity(targets.len());
for target in targets {
if !WHITESPACE_RE.is_match(&target) {
out.push(target);
continue;
}
let parts: Vec<&str> = WS_RUN_RE
.split(impeccable_core::js::trim(&target))
.filter(|p| !p.is_empty())
.collect();
if parts.len() > 1 && parts.iter().all(|p| URL_RE.is_match(p)) {
out.extend(parts.into_iter().map(str::to_string));
} else {
out.push(target);
}
}
out
}
fn is_advisory(f: &Finding) -> bool {
f.advisory == Some(true) || f.severity == "advisory"
}
fn partition_advisory(findings: &[Finding]) -> (Vec<&Finding>, Vec<&Finding>) {
let mut primary = Vec::new();
let mut advisory = Vec::new();
for f in findings {
if is_advisory(f) {
advisory.push(f);
} else {
primary.push(f);
}
}
(primary, advisory)
}
/// JS `dim(text)`: ANSI dim only when stderr is a TTY.
fn dim(text: &str, stderr_tty: bool) -> String {
if stderr_tty {
format!("\x1b[2m{text}\x1b[0m")
} else {
text.to_string()
}
}
fn imported_by(f: &Finding) -> Vec<String> {
match f.extras.get("importedBy") {
Some(Value::Array(items)) => items
.iter()
.filter_map(|v| v.as_str().map(|s| s.to_string()))
.collect(),
_ => vec![],
}
}
fn format_findings_body(findings: &[&Finding]) -> Vec<String> {
let mut grouped: Vec<(String, Vec<&Finding>)> = Vec::new();
for f in findings {
if let Some(slot) = grouped.iter_mut().find(|(k, _)| *k == f.file) {
slot.1.push(f);
} else {
grouped.push((f.file.clone(), vec![f]));
}
}
let mut out = Vec::new();
for (file, items) in grouped {
let importers = imported_by(items[0]);
let import_note = if importers.is_empty() {
String::new()
} else {
format!(" (imported by {})", importers.join(", "))
};
out.push(format!("\n{file}{import_note}"));
for item in items {
let line = if item.line != 0.0 && !item.line.is_nan() {
format!(
"line {}: ",
impeccable_core::js::number_to_string(item.line)
)
} else {
String::new()
};
out.push(format!(" {line}[{}] {}", item.antipattern, item.snippet));
out.push(format!(" → {}", item.description));
}
}
out
}
fn format_advisory_section(advisory: &[&Finding], stderr_tty: bool) -> String {
if advisory.is_empty() {
return String::new();
}
let mut lines = vec![format!(
"\n{}",
dim("── Advisory (not counted as failures) ──", stderr_tty)
)];
for line in format_findings_body(advisory) {
lines.push(dim(&line, stderr_tty));
}
lines.push(dim(
&format!(
"\n{} advisory note{}. Suppress with --no-advisory.",
advisory.len(),
if advisory.len() == 1 { "" } else { "s" }
),
stderr_tty,
));
lines.join("\n")
}
/// JS: main.mjs#formatFindings
pub fn format_findings(findings: &[Finding], json_mode: bool, stderr_tty: bool) -> String {
if json_mode {
return serde_json::to_string_pretty(findings).unwrap_or_else(|_| "[]".into());
}
let (primary, advisory) = partition_advisory(findings);
let mut out = format_findings_body(&primary);
out.push(format!("\n{}", format_finding_summary(primary.len())));
let section = format_advisory_section(&advisory, stderr_tty);
if !section.is_empty() {
out.push(section);
}
out.join("\n")
}
/// The reasons `detectCli` stops before scanning: an exit code the router
/// returns as-is.
struct Exit(i32);
struct Ctx<'a> {
io: &'a mut Io,
engines: &'a Engines<'a>,
cwd: String,
home: String,
config: DetectionConfig,
json_mode: bool,
quiet_mode: bool,
github_mode: bool,
design_system_enabled: bool,
base: ScanOptions,
cache: DesignSystemCache,
stdin_tty: bool,
/// JS `hadOperationalFailure`: at least one requested target could not be
/// scanned, which forces exit 1 (#711).
had_operational_failure: bool,
/// Local files that went to the regex engine instead of the static HTML
/// engine, so the run can say its findings are an undercount (#884).
regex_only_files: usize,
/// Their extensions, lowercased and sorted, for the note.
regex_only_exts: BTreeSet<String>,
/// Each scanned directory's framework dev-server port, deduplicated, so
/// the note can spell the URL scan that runs every rule.
dev_server_ports: BTreeSet<u32>,
/// One line per design system that switched a check off for a scanned
/// target (a DESIGN.md that declares a purple), and per URL scan note (a
/// consent banner the engine hid), in first-seen order.
design_notes: Vec<String>,
/// Custom properties per project, read once for the stripe colours a
/// component takes from a token sheet elsewhere.
tokens: ProjectTokens,
}
impl<'a> Ctx<'a> {
/// JS: main.mjs#reportLocalScanFailure
fn report_local_scan_failure(&mut self, target: &str, message: &str) {
self.had_operational_failure = true;
self.io.err(&format!("Error: cannot scan {target}: {message}\n"));
}
fn scan_options_for(&mut self, local_path: Option<&str>) -> ScanOptions {
let (Some(local_path), true) = (local_path, self.design_system_enabled) else {
return self.base.clone();
};
match load_design_system_for_target(
local_path,
Some(&mut self.cache),
&self.cwd,
&self.home,
) {
Some(ds) => {
ScanOptions {
design_system: Some(ds),
..self.base.clone()
}
}
None => self.base.clone(),
}
}
/// Record the note a design system owes for a target once its scan has
/// run: a scan that failed switched nothing off.
fn note_scanned(&mut self, options: &ScanOptions) {
let Some(ds) = options.design_system.as_deref() else { return };
if let Some(note) = crate::design_system::declared_purple_note(ds) {
if !self.design_notes.contains(¬e) {
self.design_notes.push(note);
}
}
}
fn detect_local_file(
&mut self,
file_path: &str,
options: &ScanOptions,
) -> Result<Vec<Finding>, EngineError> {
if uses_html_engine(file_path, &self.config.extensions) {
return self
.engines
.html
.detect_html(file_path, options, &mut *self.io.stderr);
}
let content = match std::fs::read_to_string(file_path) {
Ok(c) => c,
Err(e) => {
// JS `fs.readFileSync` throws with Node's errno message.
return Err(EngineError::new(match e.kind() {
std::io::ErrorKind::PermissionDenied => {
format!("EACCES: permission denied, open '{file_path}'")
}
_ => format!("ENOENT: no such file or directory, open '{file_path}'"),
}));
}
};
self.regex_only_files += 1;
self.regex_only_exts.insert(ext_from_file_path(file_path));
let tokens = may_need_tokens(&content).then(|| self.tokens.for_file(file_path));
Ok(detect_text(
&content,
file_path,
&TextOptions {
profile: options.profile.as_deref(),
design_system: options.design_system.as_deref(),
inline_ignores: options.inline_ignores,
rule_pack: options.rule_pack,
tokens: tokens.as_deref(),
},
))
}
fn handle_stdin(&mut self) -> Result<Vec<Finding>, EngineError> {
let input = self.io.stdin().to_string();
if let Ok(parsed) = serde_json::from_str::<Value>(&input) {
let fp = parsed
.get("tool_input")
.and_then(|t| t.get("file_path"))
.and_then(|f| f.as_str())
.map(|s| s.to_string());
if let Some(fp) = fp {
if !fp.is_empty() && exists(&fp) {
let opts = self.scan_options_for(Some(&fp));
let found = self.detect_local_file(&fp, &opts)?;
self.note_scanned(&opts);
return Ok(found);
}
}
}
let opts = self.scan_options_for(None);
Ok(detect_text(
&input,
"<stdin>",
&TextOptions {
profile: opts.profile.as_deref(),
design_system: opts.design_system.as_deref(),
inline_ignores: opts.inline_ignores,
rule_pack: opts.rule_pack,
tokens: None,
},
))
}
}
re!(VIEWPORT_RE, format!("^({D}{{2,5}})[xX]({D}{{2,5}})$"));
re!(URL_RE, "^(?i:https?|file)://");
re!(WHITESPACE_RE, impeccable_core::js::WS.to_string());
re!(WS_RUN_RE, format!("{}+", impeccable_core::js::WS));
re!(FILE_URL_RE, "^(?i:file):");
/// `fileURLToPath` for the `file:` URLs the CLI accepts; None when it can't map.
fn file_url_to_local_path(url: &str) -> Option<String> {
let rest = url.get(5..)?; // after "file:"
let path = if let Some(r) = rest.strip_prefix("//") {
// file://host/path: only an empty host or localhost maps on posix.
let (host, p) = match r.find('/') {
Some(i) => (&r[..i], &r[i..]),
None => (r, ""),
};
if !host.is_empty() && host != "localhost" && !cfg!(windows) {
return None;
}
p.to_string()
} else {
rest.to_string()
};
if path.is_empty() {
return None;
}
let decoded = crate::config::decode_uri_component(&path);
if decoded.contains('\0') {
return None;
}
if cfg!(windows) {
// Node win32 fileURLToPath: `/C:/x` -> `C:\x` (drive letter required
// for a hostless URL; `file://host/share/x` -> `\\host\share\x`).
let mut host = String::new();
if let Some(r) = rest.strip_prefix("//") {
host = match r.find('/') {
Some(i) => r[..i].to_string(),
None => r.to_string(),
};
}
let win = decoded.replace('/', "\\");
if !host.is_empty() && host != "localhost" {
return Some(format!("\\\\{host}{win}"));
}
let b = win.as_bytes();
// Expect `\X:` after decoding.
if b.len() < 3 || b[0] != b'\\' || !b[1].is_ascii_alphabetic() || b[2] != b':' {
return None;
}
return Some(win[1..].to_string());
}
Some(decoded)
}
/// JS: main.mjs#detectCli. `args` are the argv after the `detect` verb (the
/// leading `detect` the JS strips itself is also stripped here).
pub fn run_detect(args: &[String], io: &mut Io, engines: &Engines) -> i32 {
match detect_cli(args, io, engines) {
Ok(code) => code,
Err(Exit(code)) => code,
}
}
fn detect_cli(args_in: &[String], io: &mut Io, engines: &Engines) -> Result<i32, Exit> {
let mut args: Vec<String> = args_in
.iter()
.map(|a| match a.as_str() {
"-json" => "--json".to_string(),
"-fast" => "--fast".to_string(),
_ => a.clone(),
})
.collect();
if args.first().map(String::as_str) == Some("detect") {
args.remove(0);
}
let has = |args: &[String], flag: &str| args.iter().any(|a| a == flag);
let json_mode = has(&args, "--json");
let quiet_mode = has(&args, "--quiet");
let github_mode = has(&args, "--github");
let help_mode = has(&args, "--help");
let no_advisory = has(&args, "--no-advisory");
if has(&args, "--fast") {
io.err("Note: --fast is deprecated and ignored. The full scan is fast now and runs every rule.\n");
}
if has(&args, "--gpt") || has(&args, "--gemini") {
io.err("Note: --gpt and --gemini are deprecated and ignored. Generated-UI tells now run by default.\n");
}
let config_enabled = !has(&args, "--no-config");
let cwd = io.cwd.to_string_lossy().into_owned();
let detection_config = if config_enabled {
read_detection_config(&cwd)
} else {
DetectionConfig::raw()
};
let scopes_valid = rule_scopes().join(", ");
let mut scopes: Vec<String> = Vec::new();
let mut i = 0;
while i < args.len() {
let inline = args[i].starts_with("--scope=");
if args[i] != "--scope" && !inline {
i += 1;
continue;
}
let value: Option<String> = if inline {
Some(args[i]["--scope=".len()..].to_string())
} else {
args.get(i + 1).cloned()
};
let parsed: Vec<String> = match value {
Some(v) if !v.starts_with("--") => v
.split(',')
.map(|s| impeccable_core::js::trim(s).to_string())
.filter(|s| !s.is_empty())
.collect(),
_ => vec![],
};
if parsed.is_empty() {
io.err(&format!(
"Error: --scope requires a value. Valid scopes: {scopes_valid}\n"
));
return Err(Exit(1));
}
scopes.extend(parsed);
let n = if inline { 1 } else { 2 };
for _ in 0..n {
if i < args.len() {
args.remove(i);
}
}
}
let mut viewport: Option<(u32, u32)> = None;
let mut i = 0;
while i < args.len() {
let inline = args[i].starts_with("--viewport=");
if args[i] != "--viewport" && !inline {
i += 1;
continue;
}
let value: String = if inline {
args[i]["--viewport=".len()..].to_string()
} else {
args.get(i + 1).cloned().unwrap_or_default()
};
let Some(m) = VIEWPORT_RE.captures(&value) else {
io.err("Error: --viewport requires a WxH value, e.g. --viewport 390x844\n");
return Err(Exit(1));
};
viewport = Some((m[1].parse().unwrap_or(0), m[2].parse().unwrap_or(0)));
let n = if inline { 1 } else { 2 };
for _ in 0..n {
if i < args.len() {
args.remove(i);
}
}
}
let valid = rule_scopes();
let unknown: Vec<&String> = scopes
.iter()
.filter(|s| !valid.contains(&s.as_str()))
.collect();
if !unknown.is_empty() {
let list: Vec<&str> = unknown.iter().map(|s| s.as_str()).collect();
io.err(&format!(
"Error: unknown --scope value(s): {}. Valid scopes: {scopes_valid}\n",
list.join(", ")
));
return Err(Exit(1));
}
let cdp_value = take_value_flag(&mut args, "--cdp");
let target_filter = take_value_flag(&mut args, "--target");
let cdp = match cdp_value {
None => None,
Some(None) => {
io.err(crate::cdp_endpoint::CDP_VALUE_ERROR);
return Err(Exit(1));
}
Some(Some(v)) => match crate::cdp_endpoint::parse_cdp_endpoint(&v) {
Ok(endpoint) => Some(endpoint),
Err(line) => {
io.err(&line);
return Err(Exit(1));
}
},
};
let target_filter = match target_filter {
None => None,
Some(Some(v)) if !impeccable_core::js::trim(&v).is_empty() => Some(v),
Some(_) => {
io.err("Error: --target requires a substring of the page's URL or title, e.g. --target localhost:5173\n");
return Err(Exit(1));
}
};
if target_filter.is_some() && cdp.is_none() {
io.err("Error: --target picks a page of the app --cdp attaches to; pass --cdp <port> with it\n");
return Err(Exit(1));
}
if cdp.is_some() && viewport.is_some() {
io.err("Error: --viewport does not apply with --cdp: the attached window keeps its own size\n");
return Err(Exit(1));
}
let design_system_enabled = config_enabled
&& !has(&args, "--no-design-system")
&& detection_config.design_system_not_disabled();
let inline_ignores_enabled = config_enabled && !has(&args, "--no-inline-ignores");
let base = ScanOptions {
inline_ignores: inline_ignores_enabled,
design_system: None,
viewport,
profile: None,
// The `impeccable` binary installs no rule pack; a library caller that
// does sets this before handing the options to an engine.
rule_pack: None,
keep_consent_banners: has(&args, "--no-consent-hiding"),
keep_overlays: has(&args, "--no-overlay-hiding"),
unreported_rules: unreported_rules(&detection_config.ignore_rules, &scopes),
ignored_linked_stylesheet: Some({
let (cwd, config) = (cwd.clone(), detection_config.clone());
std::rc::Rc::new(move |path: &str| should_ignore_detection_file(path, &cwd, &config))
}),
};
let targets: Vec<String> = expand_joined_url_targets(
args.iter()
.filter(|a| !a.starts_with("--"))
.cloned()
.collect(),
);
if help_mode {
io.out(USAGE);
return Ok(0);
}
if has(&args, "--list-rules") {
if github_mode {
io.err(GITHUB_LIST_RULES_CONFLICT);
return Err(Exit(1));
}
if cdp.is_some() || !targets.is_empty() {
io.err(LIST_RULES_SCAN_ERROR);
return Err(Exit(1));
}
let rules = collect_catalog_rules(&scopes, no_advisory);
if json_mode {
io.out(&format!("{}\n", format_list_rules_json(&rules)));
} else if quiet_mode {
io.out(&format_list_rules_ids(&rules));
} else {
io.out(&format_list_rules_text(&rules));
}
return Ok(0);
}
if github_mode && json_mode {
io.err(GITHUB_JSON_CONFLICT);
return Err(Exit(1));
}
if cdp.is_some() && !targets.is_empty() {
io.err("Error: --cdp scans the page of a running app and takes no file or URL targets\n");
return Err(Exit(1));
}
let stdin_tty = io.stdin_is_tty;
let stderr_tty = stderr_is_tty();
let home = io
.home()
.map(|h| h.to_string_lossy().into_owned())
.unwrap_or_default();
let mut ctx = Ctx {
io,
engines,
cwd: cwd.clone(),
home,
config: detection_config,
json_mode,
quiet_mode,
github_mode,
design_system_enabled,
base,
cache: DesignSystemCache::new(),
stdin_tty,
had_operational_failure: false,
regex_only_files: 0,
regex_only_exts: BTreeSet::new(),
dev_server_ports: BTreeSet::new(),
design_notes: Vec::new(),
tokens: ProjectTokens::default(),
};
let mut all: Vec<Finding> = Vec::new();
if let Some(endpoint) = cdp.as_ref() {
// http(s) URL scans never load a design system, and neither does an
// attached page: its URL says nothing about which project it is.
let options = ctx.base.clone();
let result = match ctx.engines.url {
Some(u) => u.detect_cdp_scan(endpoint, target_filter.as_deref(), &options),
None => crate::engines::UrlEngine::detect_cdp_scan(
&crate::engines::MissingUrlEngine,
endpoint,
target_filter.as_deref(),
&options,
),
};
match result {
Ok(scan) => {
all.extend(scan.findings);
for note in scan.notes {
// JSON mode prints no notes, but an attached scan's capture
// notes say which checks did not run (a hidden window skips
// the pixel reads), so they go to stderr there and stdout
// stays the JSON.
if ctx.json_mode || ctx.github_mode {
ctx.io.err(&format!("{note}\n"));
} else if !ctx.design_notes.contains(¬e) {
ctx.design_notes.push(note);
}
}
}
Err(e) => {
ctx.had_operational_failure = true;
ctx.io.err(&format!("Error: {}\n", e.message));
}
}
} else if !stdin_tty && targets.is_empty() {
all = ctx.handle_stdin().map_err(|e| fatal(ctx.io, e))?;
} else {
let paths: Vec<String> = if targets.is_empty() {
vec![cwd.clone()]
} else {
targets.clone()
};
let url_count = paths.iter().filter(|p| URL_RE.is_match(p)).count();
let mut shared = if url_count > 1 {
engines.url.and_then(|u| u.open_shared())
} else {
None
};
// JS: `await createBrowserDetector()` throws before the loop; the
// failure is reported once and every URL target is skipped (#711).
let mut browser_setup_failed = false;
if let Some(s) = shared.as_deref() {
if let Err(e) = s.ensure_launched() {
browser_setup_failed = true;
ctx.had_operational_failure = true;
ctx.io.err(&format!("Error: {}\n", e.message));
}
}
if browser_setup_failed {
if let Some(s) = shared.take() {
s.close();
}
}
let result = scan_targets(
&mut ctx,
&paths,
shared.as_deref(),
browser_setup_failed,
&mut all,
);
if let Some(s) = shared {
s.close();
}
result?;
if !json_mode && !quiet_mode && !github_mode && ctx.regex_only_files > 0 {
let note = regex_only_note(ctx.regex_only_files, &ctx.regex_only_exts, &ctx.dev_server_ports);
ctx.io.err(¬e);
}
}
all = filter_detection_findings(all, &ctx.config);
let scope_refs: Vec<&str> = scopes.iter().map(|s| s.as_str()).collect();
all = filter_by_scopes(all, &scope_refs, |f: &Finding| f.antipattern.as_str());
if no_advisory {
all.retain(|f| !is_advisory(f));
}
let (primary, advisory) = partition_advisory(&all);
let (primary_len, advisory_len) = (primary.len(), advisory.len());
// Exit 1 means at least one requested scan could not complete. It takes
// precedence over exit 2 because findings from the remaining targets do
// not turn a partial scan into a complete one (#711).
let exit_code = if ctx.had_operational_failure {
1
} else if primary_len > 0 {
2
} else {
0
};
if !all.is_empty() {
if json_mode {
let text = format_findings(&all, true, stderr_tty);
ctx.io.out(&format!("{text}\n"));
} else if github_mode {
let workspace = ctx.io.env("GITHUB_WORKSPACE");
let text = format_github_annotations(&all, &ctx.cwd, workspace);
if !text.is_empty() {
ctx.io.out(&text);
}
} else if quiet_mode {
ctx.io
.err(&format!("{}\n", format_finding_summary(primary_len)));
if advisory_len > 0 {
let note = dim(
&format!(
"{advisory_len} advisory note{} (not counted).",
if advisory_len == 1 { "" } else { "s" }
),
stderr_tty,
);
ctx.io.err(&format!("{note}\n"));
}
} else {
let text = format_findings(&all, false, stderr_tty);
ctx.io.err(&format!("{text}\n"));
print_design_notes(&mut ctx, true);
}
return Ok(exit_code);
}
if json_mode {
ctx.io.out("[]\n");
} else if !github_mode && !quiet_mode {
print_design_notes(&mut ctx, false);
}
Ok(exit_code)
}
/// Text mode: say which checks a project's DESIGN.md switched off, after the
/// findings (or alone, when there are none).
/// Template extensions the static HTML engine can parse, so the note can
/// offer the `detector.extensions` opt-in for them. JSX is not on the list:
/// the parser reads nothing useful from it.
const HTML_LIKE_TEMPLATE_EXTS: &[&str] = &[".astro", ".svelte", ".vue"];
/// The #884 note: which files only got the regex engine, what that misses,
/// and the scan that would run every rule.
/// The rules whose findings this run removes after the scan, for the
/// browser engine ([`ScanOptions::unreported_rules`]): every `ignoreRules`
/// entry, and, when `--scope` narrows the report, every registered rule in
/// none of the requested scopes ([`filter_by_scopes`]).
fn unreported_rules(ignore_rules: &[String], scopes: &[String]) -> Vec<String> {
let mut out: Vec<String> = ignore_rules.iter().map(|r| normalize_ignore_rule(r)).collect();
if !scopes.is_empty() {
for rule in all_antipatterns() {
let in_scope = rule.scopes.unwrap_or(&[]).iter().any(|s| scopes.iter().any(|w| w == s));
if !in_scope {
out.push(rule.id.to_string());
}
}
}
out.sort();
out.dedup();
out
}
fn regex_only_note(n: usize, exts: &BTreeSet<String>, ports: &BTreeSet<u32>) -> String {
let listed: Vec<&str> = exts.iter().map(String::as_str).filter(|e| !e.is_empty()).collect();
let mut note = format!(
"\n{n} file{} scanned with regex matching only{}.\nRules that need a parsed page (tiny-text, low-contrast and other element rules) did not run on them; findings are an undercount, not a clean bill of health.\n",
if n == 1 { "" } else { "s" },
if listed.is_empty() { String::new() } else { format!(" ({})", listed.join(", ")) }
);
if ports.is_empty() {
note.push_str(
"For the full check, scan the running dev server (npx impeccable detect http://localhost:PORT) or a static site's built .html.\n",
);
} else {
// One URL per scanned project, so a run over a Vite app and a Next
// app names both.
note.push_str(if ports.len() == 1 {
"For the full check, scan the running app:\n"
} else {
"For the full check, scan each running app:\n"
});
for p in ports {
note.push_str(&format!(" npx impeccable detect http://localhost:{p}\n"));
}
}
let templates: Vec<&str> = listed
.iter()
.copied()
.filter(|e| HTML_LIKE_TEMPLATE_EXTS.contains(e))
.collect();
if let Some(first) = templates.first() {
note.push_str(&format!(
"{} files can take the HTML engine instead: add {{ \"ext\": \"{first}\", \"engine\": \"html\" }} under detector.extensions in .impeccable/config.json (trades the regex rules and line numbers for the element rules).\n",
templates.join("/")
));
}
note
}
fn print_design_notes(ctx: &mut Ctx, after_findings: bool) {
if ctx.design_notes.is_empty() {
return;
}
let lead = if after_findings { "\n" } else { "" };
let text = ctx.design_notes.join("\n");
ctx.io.err(&format!("{lead}{text}\n"));
}
/// The `error.message` Node hands `reportLocalScanFailure` for a failed
/// `readdirSync` / `readFileSync`.
fn node_scan_error(path: &str, err: &std::io::Error) -> String {
let syscall = if std::fs::metadata(path).map(|m| m.is_dir()).unwrap_or(false) {
"scandir"
} else {
"open"
};
match err.kind() {
std::io::ErrorKind::NotFound => {
format!("ENOENT: no such file or directory, {syscall} '{path}'")
}
std::io::ErrorKind::PermissionDenied => {
format!("EACCES: permission denied, {syscall} '{path}'")
}
_ => format!("{err}"),
}
}
/// An engine error outside a per-URL try: the JS lets it propagate to
/// `cli.js`, which prints the message and exits 1.
fn fatal(io: &mut Io, e: EngineError) -> Exit {
io.err(&format!("{}\n", e.message));
Exit(1)
}
fn scan_targets(
ctx: &mut Ctx,
paths: &[String],
shared: Option<&dyn crate::engines::SharedBrowser>,
browser_setup_failed: bool,
all: &mut Vec<Finding>,
) -> Result<(), Exit> {
for target in paths {
if URL_RE.is_match(target) {
if browser_setup_failed {
continue;
}
let url_options = if FILE_URL_RE.is_match(target) {
let local = file_url_to_local_path(target);
ctx.scan_options_for(local.as_deref())
} else {
ctx.base.clone()
};
let result = match (shared, ctx.engines.url) {
(Some(s), _) => s.detect_url_scan(target, &url_options),
(None, Some(u)) => u.detect_url_scan(target, &url_options),
(None, None) => crate::engines::UrlEngine::detect_url_scan(
&crate::engines::MissingUrlEngine,
target,
&url_options,
),
};
match result {
Ok(scan) => {
ctx.note_scanned(&url_options);
all.extend(scan.findings);
for note in scan.notes {
if !ctx.design_notes.contains(¬e) {
ctx.design_notes.push(note);
}
}
}
Err(e) => {
ctx.had_operational_failure = true;
ctx.io.err(&format!("Error: {}\n", e.message));
}
}
continue;
}
let resolved = jsp::resolve(&ctx.cwd, &[target]);
let Ok(stat) = std::fs::metadata(&resolved) else {
ctx.had_operational_failure = true;
ctx.io.err(&format!("Warning: cannot access {target}\n"));
continue;
};
if stat.is_dir() {
if !ctx.json_mode && !ctx.quiet_mode && !ctx.github_mode {
if let Some(fw) = detect_framework_config(&resolved) {
ctx.dev_server_ports.insert(fw.port);
let probe = is_port_listening(fw.port, Some(fw.fingerprint));
let msg = if probe.listening && probe.matched {
format!(
"\n{} dev server detected on localhost:{}.\nFor more accurate results, scan the running site:\n npx impeccable detect http://localhost:{}\n\n",
fw.name, fw.port, fw.port
)
} else if probe.listening && !probe.matched {
format!(
"\n{} project detected ({}).\nPort {} is in use by another service. Start the {} dev server and scan via URL for best results.\n\n",
fw.name,
jsp::basename(&fw.config_path),
fw.port,
fw.name
)
} else {
format!(
"\n{} project detected ({}).\nStart the dev server and scan via URL for best results:\n npx impeccable detect http://localhost:{}\n\n",
fw.name,
jsp::basename(&fw.config_path),
fw.port
)
};
ctx.io.err(&msg);
}
}
let cwd = ctx.cwd.clone();
// Unreadable directories and files are reported, not silently
// skipped, and each one forces exit 1 (#711).
let mut walk_failures: Vec<(String, String)> = Vec::new();
let files: Vec<String> = walk_dir_reporting(&resolved, &ctx.config.extensions, &mut |dir, err| {
walk_failures.push((dir.to_string(), node_scan_error(dir, err)));
})
.into_iter()
.filter(|f| !should_ignore_detection_file(f, &cwd, &ctx.config))
.collect();
for (dir, message) in walk_failures {
ctx.report_local_scan_failure(&dir, &message);
}
let html_count = files
.iter()
.filter(|f| uses_html_engine(f, &ctx.config.extensions))
.count();
if files.len() > 50 && ctx.stdin_tty && !ctx.json_mode && !ctx.quiet_mode && !ctx.github_mode {
ctx.io.err(&format!(
"\nFound {} files ({} HTML) in {}.\nScanning may take a while{}.\nTarget a specific subdirectory to narrow scope.\n",
files.len(),
html_count,
target,
if html_count > 10 { " (static HTML/CSS processes each HTML file individually)" } else { "" }
));
if !confirm(ctx.io, "Continue?") {
ctx.io.err("Aborted.\n");
return Err(Exit(0));
}
}
let mut unreadable_files: Vec<String> = Vec::new();
let mut read_failures: Vec<(String, String)> = Vec::new();
let graph = build_import_graph_reporting(&files, &mut |file, err| {
unreadable_files.push(file.to_string());
read_failures.push((file.to_string(), node_scan_error(file, err)));
});
for (file, message) in read_failures {
ctx.report_local_scan_failure(&file, &message);
}
let mut imported_by_map: Vec<(String, Vec<String>)> = Vec::new();
for (importer, imports) in &graph {
for imported in imports {
if let Some(slot) = imported_by_map.iter_mut().find(|(k, _)| k == imported) {
if !slot.1.contains(importer) {
slot.1.push(importer.clone());
}
} else {
imported_by_map.push((imported.clone(), vec![importer.clone()]));
}
}
}
for file in &files {
if unreadable_files.contains(file) {
continue;
}
let opts = ctx.scan_options_for(Some(file));
let mut file_findings = match ctx.detect_local_file(file, &opts) {
Ok(f) => {
ctx.note_scanned(&opts);
f
}
Err(e) => {
let message = e.message.clone();
ctx.report_local_scan_failure(file, &message);
continue;
}
};
if let Some((_, importers)) = imported_by_map.iter().find(|(k, _)| k == file) {
if !importers.is_empty() {
let names: Vec<Value> = importers
.iter()
.map(|f| Value::String(jsp::basename(f)))
.collect();
for f in &mut file_findings {
f.extras
.insert("importedBy".into(), Value::Array(names.clone()));
}
}
}
all.extend(file_findings);
}
} else if stat.is_file() {
let cwd = ctx.cwd.clone();
if should_ignore_detection_file(&resolved, &cwd, &ctx.config) {
continue;
}
let opts = ctx.scan_options_for(Some(&resolved));
match ctx.detect_local_file(&resolved, &opts) {
Ok(f) => {
ctx.note_scanned(&opts);
all.extend(f)
}
Err(e) => {
let message = e.message.clone();
ctx.report_local_scan_failure(target, &message);
}
}
}
}
Ok(())
}
/// JS `confirm(question)`: readline on a TTY stdin, prompt to stderr.
fn confirm(io: &mut Io, question: &str) -> bool {
io.err(&format!("{question} [Y/n] "));
let _ = io.stderr.flush();
let mut answer = String::new();
// Only reached when stdin is a TTY, so a direct line read is what the
// JS readline does too.
let _ = std::io::stdin().read_line(&mut answer);
let a = impeccable_core::js::trim(&answer);
a.is_empty() || a.eq_ignore_ascii_case("y") || a.eq_ignore_ascii_case("yes")
}
fn stderr_is_tty() -> bool {
#[cfg(unix)]
{
extern "C" {
fn isatty(fd: i32) -> i32;
}
unsafe { isatty(2) == 1 }
}
#[cfg(not(unix))]
{
std::io::IsTerminal::is_terminal(&std::io::stderr())
}
}
#[cfg(test)]
mod design_note_tests {
use super::*;
use crate::engines::{HtmlEngine, MissingHtmlEngine};
struct CleanHtml;
impl HtmlEngine for CleanHtml {
fn detect_html(
&self,
_path: &str,
_options: &ScanOptions,
_stderr: &mut dyn std::io::Write,
) -> Result<Vec<Finding>, EngineError> {
Ok(Vec::new())
}
}
fn run(dir: &std::path::Path, target: &str, html: &dyn HtmlEngine) -> (i32, String) {
let (mut io, captured) = Io::captured_reader(
Box::new(std::io::empty()),
dir.to_path_buf(),
std::collections::HashMap::new(),
);
let engines = Engines { html, url: None };
let code = run_detect(&[target.to_string()], &mut io, &engines);
let err = String::from_utf8(captured.stderr.borrow().clone()).unwrap();
(code, err)
}
#[test]
fn the_purple_note_follows_only_a_scan_that_ran() {
let dir = std::env::temp_dir().join(format!("impeccable-design-note-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("DESIGN.md"), "---\ncolors:\n primary: \"#5c2d91\"\n---\n# Design\n").unwrap();
std::fs::write(dir.join("page.html"), "<!doctype html><p>Hi</p>").unwrap();
let page = dir.join("page.html").to_string_lossy().into_owned();
// The file: URL cannot be scanned here (no URL engine), so the check
// was never switched off for anything.
let (code, err) = run(&dir, &format!("file://{page}"), &MissingHtmlEngine);
assert_eq!(code, 1, "{err}");
assert!(err.contains("Error: "), "{err}");
assert!(!err.contains("check is off"), "{err}");
// A local scan that ran says so.
let (_, err) = run(&dir, &page, &CleanHtml);
assert!(err.contains("purple/violet check is off"), "{err}");
let _ = std::fs::remove_dir_all(&dir);
}
}
#[cfg(test)]
mod unreported_rules_tests {
use super::unreported_rules;
/// `low-contrast` declares no scope, so `--scope type` reports
/// `tiny-text` and never `low-contrast`: the browser engine is told, so
/// a finding the run drops does not stand in for one it keeps.
#[test]
fn ignored_and_out_of_scope_rules_are_unreported() {
assert!(unreported_rules(&[], &[]).is_empty());
let ignored = unreported_rules(&[" Low-Contrast ".to_string()], &[]);
assert_eq!(ignored, vec!["low-contrast".to_string()]);
let scoped = unreported_rules(&[], &["type".to_string()]);
assert!(scoped.iter().any(|r| r == "low-contrast"), "{scoped:?}");
assert!(!scoped.iter().any(|r| r == "tiny-text"), "{scoped:?}");
}
}