The design language that makes your AI harness better at design.
JavaScript
Add detect `--github` for GitHub Actions annotations (#1065)
Matt Van Horne3083ac3301e
diff --git a/README.md b/README.mdindex 36941e4b3..1cbe2dad2 100644--- a/README.md+++ b/README.md@@ -473,6 +473,7 @@ npx impeccable detect src/ # scan a directorynpx impeccable detect index.html # scan an HTML filenpx impeccable detect https://example.com # scan a URL (uses an installed Chrome, Chromium, or Edge)npx impeccable detect --json . # CI-friendly JSON output+npx impeccable detect --github src/ # GitHub Actions annotations on stdoutnpx impeccable detect --list-rules # catalog of detector rule ids, names, and descriptionsnpx impeccable detect --no-config src/ # raw scan, ignoring project config/contextnpx impeccable ignores list # show detector ignores@@ -482,7 +483,7 @@ npx impeccable ignores add-value overused-font Inter --reason "Brand font"The detector catches 61 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).-Human-readable findings are diagnostics written to stderr, so redirect them with `2> findings.txt`. Use `--json` for machine-readable results on stdout. `--list-rules` prints the detector catalog to stdout and does not scan. Exit `0` means the scan completed without primary findings, exit `2` means it completed with primary findings, and exit `1` means at least one requested target could not be scanned; operational failure takes precedence for a partial multi-target scan. URL scans inspect the rendered DOM, computed layout, and accessible linked stylesheets; browser security still prevents reading cross-origin CSS without CORS. A clean detector run is evidence, not proof of visual or accessibility quality: it does not replace inspecting the rendered experience across relevant viewports.+Human-readable findings are diagnostics written to stderr, so redirect them with `2> findings.txt`. Use `--json` for machine-readable results on stdout, or `--github` for GitHub Actions annotations (one workflow command per finding). GitHub displays at most 10 annotations of each type per step and 50 per job, and the rest stay in the log; findings from the HTML engine may carry no line number, so they annotate the file. `--list-rules` prints the detector catalog to stdout and does not scan. Exit `0` means the scan completed without primary findings, exit `2` means it completed with primary findings, and exit `1` means at least one requested target could not be scanned; operational failure takes precedence for a partial multi-target scan. URL scans inspect the rendered DOM, computed layout, and accessible linked stylesheets; browser security still prevents reading cross-origin CSS without CORS. A clean detector run is evidence, not proof of visual or accessibility quality: it does not replace inspecting the rendered experience across relevant viewports.By default, `detect` respects the same `.impeccable/config.json` and `.impeccable/config.local.json` detector config as the design hook: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. Hook lifecycle settings such as `hook.enabled` only affect automatic hook execution.diff --git a/README.npm.md b/README.npm.mdindex 90894117a..fcf466824 100644--- a/README.npm.md+++ b/README.npm.md@@ -37,6 +37,8 @@ npx impeccable detect https://example.com# JSON output for CI/toolingnpx impeccable detect --json src/+# GitHub Actions annotations+npx impeccable detect --github src/# Catalog of detector rules (no scan)npx impeccable detect --list-rules```@@ -68,7 +70,7 @@ npx impeccable detect --list-rules- `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. In JSON mode, stdout remains a findings array and diagnostics are written to stderr.+Operational failure takes precedence when a multi-target scan is partial. In JSON mode, stdout remains a findings array and diagnostics are written to stderr. With `--github`, stdout is one GitHub Actions annotation per finding; GitHub displays at most 10 annotations of each type per step and 50 per job, and the rest stay in the log.## Options@@ -76,6 +78,7 @@ Operational failure takes precedence when a multi-target scan is partial. In JSOimpeccable detect [options] [file-or-dir-or-url...]--json Output findings as JSON+ --github Write GitHub Actions annotations for each finding--list-rules Print the detector rule catalog and exit--scope Only report rules in a design domain (type, layout)--help Show helpdiff --git a/crates/detect/src/cli.rs b/crates/detect/src/cli.rsindex 7fe220a9b..b83830f4f 100644--- a/crates/detect/src/cli.rs+++ b/crates/detect/src/cli.rs@@ -20,6 +20,9 @@ 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,@@ -34,6 +37,8 @@ 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. --jsonfor JSON, --quiet for ids only. Takes no targets--scope <name> Only report rules in the given design domain@@ -68,6 +73,7 @@ Advisory findings:Output streams:Human-readable findings go to stderr so stdout stays available for structuredoutput. 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:@@ -103,6 +109,7 @@ Examples:impeccable detect https://example.comimpeccable detect --cdp 9222 --target \"My App\" --jsonimpeccable detect --json .+ impeccable detect --github src/impeccable detect --list-rulesimpeccable detect --no-config src/";@@ -286,6 +293,7 @@ struct Ctx<'a> {config: DetectionConfig,json_mode: bool,quiet_mode: bool,+ github_mode: bool,design_system_enabled: bool,base: ScanOptions,cache: DesignSystemCache,@@ -490,6 +498,7 @@ fn detect_cli(args_in: &[String], io: &mut Io, engines: &Engines) -> Result<i32,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") {@@ -643,6 +652,10 @@ fn detect_cli(args_in: &[String], io: &mut Io, engines: &Engines) -> Result<i32,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));@@ -657,6 +670,10 @@ fn detect_cli(args_in: &[String], io: &mut Io, engines: &Engines) -> Result<i32,}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));@@ -676,6 +693,7 @@ fn detect_cli(args_in: &[String], io: &mut Io, engines: &Engines) -> Result<i32,config: detection_config,json_mode,quiet_mode,+ github_mode,design_system_enabled,base,cache: DesignSystemCache::new(),@@ -709,7 +727,7 @@ fn detect_cli(args_in: &[String], io: &mut Io, engines: &Engines) -> Result<i32,// 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 {+ 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);@@ -761,7 +779,7 @@ fn detect_cli(args_in: &[String], io: &mut Io, engines: &Engines) -> Result<i32,s.close();}result?;- if !json_mode && !quiet_mode && ctx.regex_only_files > 0 {+ 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);}@@ -789,6 +807,12 @@ fn detect_cli(args_in: &[String], io: &mut Io, engines: &Engines) -> Result<i32,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)));@@ -811,7 +835,7 @@ fn detect_cli(args_in: &[String], io: &mut Io, engines: &Engines) -> Result<i32,}if json_mode {ctx.io.out("[]\n");- } else if !quiet_mode {+ } else if !github_mode && !quiet_mode {print_design_notes(&mut ctx, false);}Ok(exit_code)@@ -968,7 +992,7 @@ fn scan_targets(continue;};if stat.is_dir() {- if !ctx.json_mode && !ctx.quiet_mode {+ 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));@@ -1013,7 +1037,7 @@ fn scan_targets(.iter().filter(|f| uses_html_engine(f, &ctx.config.extensions)).count();- if files.len() > 50 && ctx.stdin_tty && !ctx.json_mode && !ctx.quiet_mode {+ 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(),diff --git a/crates/detect/src/github_annotations.rs b/crates/detect/src/github_annotations.rsnew file mode 100644index 000000000..1ff1c3d9d--- /dev/null+++ b/crates/detect/src/github_annotations.rs@@ -0,0 +1,237 @@+//! GitHub Actions workflow commands for `impeccable detect --github`.+//!+//! One annotation per finding, on stdout. Encoding follows+//! https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions+//! : `%`, `\r`, `\n` in every value; `:` and `,` also in parameter values.++use std::path::{Path, PathBuf};++use impeccable_core::findings::Finding;+use impeccable_core::js::number_to_string;++pub const GITHUB_JSON_CONFLICT: &str = "Error: --github cannot be used with --json\n";+pub const GITHUB_LIST_RULES_CONFLICT: &str =+ "Error: --github annotates scan findings and cannot be used with --list-rules\n";++/// `%` first so a later replacement is not itself percent-encoded.+pub fn escape_data(value: &str) -> String {+ value+ .replace('%', "%25")+ .replace('\r', "%0D")+ .replace('\n', "%0A")+}++pub fn escape_property(value: &str) -> String {+ escape_data(value).replace(':', "%3A").replace(',', "%2C")+}++fn is_advisory(finding: &Finding) -> bool {+ finding.advisory == Some(true) || finding.severity == "advisory"+}++fn workflow_command(finding: &Finding) -> &'static str {+ if is_advisory(finding) {+ "notice"+ } else if finding.severity == "error" {+ "error"+ } else {+ "warning"+ }+}++fn strip_root(path: &Path, root: &Path) -> Option<String> {+ path.strip_prefix(root).ok().and_then(|rel| {+ if rel.as_os_str().is_empty() {+ None+ } else {+ Some(rel.to_string_lossy().replace('\\', "/"))+ }+ })+}++/// Path GitHub should annotate: relative to `GITHUB_WORKSPACE` when that is+/// a prefix, else relative to cwd. URLs and empty paths stay as given.+pub fn annotation_file(file: &str, cwd: &str, workspace: Option<&str>) -> String {+ if file.is_empty() || file.contains("://") {+ return file.replace('\\', "/");+ }+ let file_path = Path::new(file);+ let abs: PathBuf = if file_path.is_absolute() {+ file_path.to_path_buf()+ } else {+ Path::new(cwd).join(file_path)+ };+ if let Some(ws) = workspace.filter(|s| !s.is_empty()) {+ if let Some(rel) = strip_root(&abs, Path::new(ws)) {+ return rel;+ }+ }+ if let Some(rel) = strip_root(&abs, Path::new(cwd)) {+ return rel;+ }+ file.replace('\\', "/")+}++fn annotation_line(line: f64) -> Option<String> {+ if line == 0.0 || !line.is_finite() {+ None+ } else {+ Some(number_to_string(line))+ }+}++fn annotation_message(finding: &Finding) -> String {+ let mut msg = format!("[{}]", finding.antipattern);+ if !finding.snippet.is_empty() {+ msg.push(' ');+ msg.push_str(&finding.snippet);+ }+ if !finding.description.is_empty() {+ msg.push('\n');+ msg.push_str(&finding.description);+ }+ msg+}++pub fn format_annotation(finding: &Finding, cwd: &str, workspace: Option<&str>) -> String {+ let command = workflow_command(finding);+ let mut props: Vec<String> = Vec::new();+ let file = annotation_file(&finding.file, cwd, workspace);+ if !file.is_empty() {+ props.push(format!("file={}", escape_property(&file)));+ }+ if let Some(line) = annotation_line(finding.line) {+ props.push(format!("line={}", escape_property(&line)));+ }+ if !finding.name.is_empty() {+ props.push(format!("title={}", escape_property(&finding.name)));+ }+ let value = escape_data(&annotation_message(finding));+ if props.is_empty() {+ format!("::{command}::{value}")+ } else {+ format!("::{command} {}::{value}", props.join(","))+ }+}++/// One workflow command per finding, in scan order. Empty when there are+/// none. Always a trailing newline when there is at least one annotation.+pub fn format_github_annotations(+ findings: &[Finding],+ cwd: &str,+ workspace: Option<&str>,+) -> String {+ let mut out = String::new();+ for finding in findings {+ out.push_str(&format_annotation(finding, cwd, workspace));+ out.push('\n');+ }+ out+}++#[cfg(test)]+mod tests {+ use super::*;+ use impeccable_core::findings::finding;++ #[test]+ fn data_encodes_percent_and_newlines_but_keeps_colon_comma() {+ assert_eq!(escape_data("a%b\nc,d:e\r"), "a%25b%0Ac,d:e%0D");+ }++ #[test]+ fn properties_also_encode_colon_and_comma() {+ assert_eq!(escape_property("C:\\x,y"), "C%3A\\x%2Cy");+ assert_eq!(escape_property("a%b"), "a%25b");+ }++ #[test]+ fn percent_is_encoded_before_other_escapes() {+ assert_eq!(escape_data("%0A"), "%250A");+ assert_eq!(escape_property("%3A"), "%253A");+ }++ #[test]+ fn warning_omits_line_zero_and_relativizes_to_cwd() {+ let f = finding("side-tab", "/repo/src/card.html", "border-left: 4px", 0.0);+ let line = format_annotation(&f, "/repo", None);+ assert!(line.starts_with("::warning file=src/card.html,title=Side-tab accent border::"));+ assert!(!line.contains("line="));+ assert!(line.contains("[side-tab] border-left: 4px%0A"));+ assert!(line.contains("Thick colored border"));+ }++ #[test]+ fn warning_includes_a_real_line() {+ let f = finding("side-tab", "card.html", "snip", 12.0);+ let line = format_annotation(&f, "/repo", None);+ assert!(line.contains("file=card.html"));+ assert!(line.contains("line=12"));+ assert!(line.starts_with("::warning "));+ }++ #[test]+ fn nan_and_infinite_lines_are_omitted() {+ let mut f = finding("side-tab", "a.html", "s", 1.0);+ f.line = f64::NAN;+ assert!(!format_annotation(&f, "/x", None).contains("line="));+ f.line = f64::INFINITY;+ assert!(!format_annotation(&f, "/x", None).contains("line="));+ }++ #[test]+ fn advisory_is_a_notice_and_error_is_an_error() {+ let adv = finding("em-dash-overuse", "copy.html", "—", 3.0);+ assert!(format_annotation(&adv, "/x", None).starts_with("::notice "));+ let err = finding("script-error", "app.js", "TypeError: x", 8.0);+ assert!(format_annotation(&err, "/x", None).starts_with("::error "));+ }++ #[test]+ fn github_workspace_wins_over_cwd() {+ let f = finding("side-tab", "/ws/packages/web/src/card.html", "snip", 2.0);+ let line = format_annotation(&f, "/ws/packages/web", Some("/ws"));+ assert!(line.contains("file=packages/web/src/card.html"));+ assert!(!line.contains("file=/ws/"));+ }++ #[test]+ fn relative_file_joins_cwd_before_stripping_workspace() {+ let f = finding("side-tab", "src/card.html", "snip", 1.0);+ let line = format_annotation(&f, "/ws/packages/web", Some("/ws"));+ assert!(line.contains("file=packages/web/src/card.html"));+ }++ #[test]+ fn urls_are_not_rewritten() {+ let f = finding("side-tab", "https://example.com/x", "snip", 1.0);+ let line = format_annotation(&f, "/repo", Some("/repo"));+ assert!(line.contains("file=https%3A//example.com/x"));+ }++ #[test]+ fn title_and_file_escape_colon_and_comma() {+ let mut f = finding("side-tab", "src/a,b.html", "k:v,w", 1.0);+ f.name = "A, B: C".into();+ let line = format_annotation(&f, "/repo", None);+ assert!(line.contains("file=src/a%2Cb.html"));+ assert!(line.contains("title=A%2C B%3A C"));+ // The message keeps colon and comma; only percent-encodes newlines.+ assert!(line.contains("[side-tab] k:v,w%0A"));+ }++ #[test]+ fn catalog_is_one_line_per_finding_in_order() {+ let findings = vec![+ finding("side-tab", "a.html", "one", 1.0),+ finding("em-dash-overuse", "a.html", "two", 2.0),+ ];+ let text = format_github_annotations(&findings, "/x", None);+ let lines: Vec<&str> = text.lines().collect();+ assert_eq!(lines.len(), 2);+ assert!(lines[0].starts_with("::warning "));+ assert!(lines[1].starts_with("::notice "));+ assert!(text.ends_with('\n'));+ assert_eq!(format_github_annotations(&[], "/x", None), "");+ }+}diff --git a/crates/detect/src/lib.rs b/crates/detect/src/lib.rsindex ae52494bf..4565dcb86 100644--- a/crates/detect/src/lib.rs+++ b/crates/detect/src/lib.rs@@ -17,6 +17,7 @@ pub mod design_system;pub mod detect_text;pub mod engines;pub mod file_system;+pub mod github_annotations;pub mod ignores;pub mod jsp;pub mod list_rules;diff --git a/crates/detect/tests/github_annotations.rs b/crates/detect/tests/github_annotations.rsnew file mode 100644index 000000000..8c93077e2--- /dev/null+++ b/crates/detect/tests/github_annotations.rs@@ -0,0 +1,319 @@+//! `impeccable detect --github` writes Actions workflow commands and skips+//! the human-readable findings stream.++use std::collections::HashMap;+use std::io::Write;+use std::path::Path;++use impeccable_common::Io;+use impeccable_core::findings::{finding, Finding};+use impeccable_detect::cli::run_detect;+use impeccable_detect::engines::EngineError;+use impeccable_detect::{Engines, HtmlEngine, MissingHtmlEngine, ScanOptions};++struct CannedHtml(Vec<Finding>);++impl HtmlEngine for CannedHtml {+ fn detect_html(+ &self,+ path: &str,+ _options: &ScanOptions,+ _stderr: &mut dyn Write,+ ) -> Result<Vec<Finding>, EngineError> {+ Ok(self+ .0+ .iter()+ .map(|f| {+ let mut row = f.clone();+ row.file = path.to_string();+ row+ })+ .collect())+ }+}++fn run_with(+ dir: &Path,+ args: &[&str],+ html: &dyn HtmlEngine,+ env: HashMap<String, String>,+) -> (i32, String, String) {+ let argv: Vec<String> = args.iter().map(|s| s.to_string()).collect();+ let (mut io, cap) = Io::captured("", dir.to_path_buf(), env);+ let engines = Engines { html, url: None };+ let code = run_detect(&argv, &mut io, &engines);+ let out = String::from_utf8(cap.stdout.borrow().clone()).unwrap();+ let err = String::from_utf8(cap.stderr.borrow().clone()).unwrap();+ (code, out, err)+}++fn stage_card(dir: &Path) {+ std::fs::create_dir_all(dir).unwrap();+ std::fs::write(+ dir.join("card.html"),+ "<div style=\"border-left: 4px solid #ff0000; border-radius: 10px\">x</div>\n",+ )+ .unwrap();+}++#[test]+fn github_writes_annotations_to_stdout() {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-ann-{}", std::process::id()));+ stage_card(&dir);+ let html = CannedHtml(vec![finding("side-tab", "", "border-left: 4px", 1.0)]);+ let (code, out, err) = run_with(+ &dir,+ &["--no-config", "--github", "card.html"],+ &html,+ HashMap::new(),+ );+ assert_eq!(code, 2, "{err}");+ assert!(err.is_empty(), "{err}");+ assert!(out.starts_with("::warning file=card.html,line=1,title=Side-tab accent border::"));+ assert!(out.contains("[side-tab] border-left: 4px%0A"));+ assert!(out.ends_with('\n'));+ std::fs::remove_dir_all(&dir).unwrap();+}++#[test]+fn github_conflicts_with_json() {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-json-{}", std::process::id()));+ stage_card(&dir);+ let (code, out, err) = run_with(+ &dir,+ &["--github", "--json", "card.html"],+ &MissingHtmlEngine,+ HashMap::new(),+ );+ assert_eq!(code, 1);+ assert!(out.is_empty(), "{out}");+ assert_eq!(err, "Error: --github cannot be used with --json\n");+ std::fs::remove_dir_all(&dir).unwrap();+}++#[test]+fn github_help_wins() {+ let (code, out, err) = run_with(+ Path::new("/tmp"),+ &["--github", "--help"],+ &MissingHtmlEngine,+ HashMap::new(),+ );+ assert_eq!(code, 0, "{err}");+ assert!(err.is_empty(), "{err}");+ assert!(out.starts_with("Usage: impeccable detect"));+ assert!(out.contains("--github"));+ assert!(!out.contains("::warning"));+}++#[test]+fn github_quiet_still_annotates() {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-quiet-{}", std::process::id()));+ stage_card(&dir);+ let html = CannedHtml(vec![finding("side-tab", "", "snip", 4.0)]);+ let (code, out, err) = run_with(+ &dir,+ &["--no-config", "--github", "--quiet", "card.html"],+ &html,+ HashMap::new(),+ );+ assert_eq!(code, 2, "{err}");+ assert!(err.is_empty(), "{err}");+ assert!(out.contains("::warning file=card.html,line=4,"));+ std::fs::remove_dir_all(&dir).unwrap();+}++#[test]+fn github_no_advisory_drops_notices() {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-adv-{}", std::process::id()));+ stage_card(&dir);+ let html = CannedHtml(vec![+ finding("side-tab", "", "primary", 1.0),+ finding("em-dash-overuse", "", "—", 2.0),+ ]);+ let (code, out, err) = run_with(+ &dir,+ &["--no-config", "--github", "--no-advisory", "card.html"],+ &html,+ HashMap::new(),+ );+ assert_eq!(code, 2, "{err}");+ assert!(out.contains("::warning "));+ assert!(!out.contains("::notice "));+ assert!(!out.contains("em-dash-overuse"));+ std::fs::remove_dir_all(&dir).unwrap();+}++#[test]+fn github_advisory_is_notice_and_does_not_fail() {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-notice-{}", std::process::id()));+ stage_card(&dir);+ let html = CannedHtml(vec![finding("em-dash-overuse", "", "—", 2.0)]);+ let (code, out, err) = run_with(+ &dir,+ &["--no-config", "--github", "card.html"],+ &html,+ HashMap::new(),+ );+ assert_eq!(code, 0, "{err}");+ assert!(out.starts_with("::notice file=card.html,line=2,title=Em-dash overuse::"));+ std::fs::remove_dir_all(&dir).unwrap();+}++#[test]+fn github_error_severity_is_an_error_annotation() {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-err-{}", std::process::id()));+ stage_card(&dir);+ let html = CannedHtml(vec![finding("script-error", "", "TypeError: x", 9.0)]);+ let (code, out, err) = run_with(+ &dir,+ &["--no-config", "--github", "card.html"],+ &html,+ HashMap::new(),+ );+ assert_eq!(code, 2, "{err}");+ assert!(out.starts_with("::error file=card.html,line=9,title=Uncaught script error on load::"));+ std::fs::remove_dir_all(&dir).unwrap();+}++#[test]+fn github_clean_scan_is_silent() {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-clean-{}", std::process::id()));+ stage_card(&dir);+ let (code, out, err) = run_with(+ &dir,+ &["--no-config", "--github", "card.html"],+ &CannedHtml(vec![]),+ HashMap::new(),+ );+ assert_eq!(code, 0, "{err}");+ assert!(out.is_empty(), "{out}");+ assert!(err.is_empty(), "{err}");+ std::fs::remove_dir_all(&dir).unwrap();+}++#[test]+fn github_workspace_relativizes_nested_cwd() {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-ws-{}", std::process::id()));+ let nested = dir.join("packages").join("web");+ stage_card(&nested);+ let html = CannedHtml(vec![finding("side-tab", "", "snip", 1.0)]);+ let mut env = HashMap::new();+ env.insert(+ "GITHUB_WORKSPACE".into(),+ dir.to_string_lossy().into_owned(),+ );+ let (code, out, err) = run_with(+ &nested,+ &["--no-config", "--github", "card.html"],+ &html,+ env,+ );+ assert_eq!(code, 2, "{err}");+ assert!(+ out.contains("file=packages/web/card.html"),+ "{out}"+ );+ std::fs::remove_dir_all(&dir).unwrap();+}++#[test]+fn github_skips_the_regex_only_note() {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-regex-{}", std::process::id()));+ std::fs::create_dir_all(&dir).unwrap();+ std::fs::write(dir.join("probe.astro"), "<p>ok</p>\n").unwrap();+ let (code, out, err) = run_with(+ &dir,+ &["--no-config", "--github", "probe.astro"],+ &MissingHtmlEngine,+ HashMap::new(),+ );+ assert_eq!(code, 0, "{err}");+ assert!(out.is_empty(), "{out}");+ assert!(+ !err.contains("regex matching only"),+ "{err}"+ );+ std::fs::remove_dir_all(&dir).unwrap();+}++fn stage_framework_dir(tag: &str) -> std::path::PathBuf {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-fw-{tag}-{}", std::process::id()));+ stage_card(&dir);+ // An unlikely port keeps the probe from finding a real dev server.+ std::fs::write(dir.join("next.config.js"), "module.exports = { port: 59871 };\n").unwrap();+ dir+}++#[test]+fn github_skips_the_framework_note() {+ let dir = stage_framework_dir("gh");+ let (code, _out, err) = run_with(+ &dir,+ &["--no-config", "--github", "."],+ &CannedHtml(vec![]),+ HashMap::new(),+ );+ assert_eq!(code, 0, "{err}");+ assert!(!err.contains("project detected"), "{err}");+ assert!(!err.contains("dev server detected"), "{err}");+ std::fs::remove_dir_all(&dir).unwrap();+}++#[test]+fn text_mode_prints_the_framework_note() {+ let dir = stage_framework_dir("text");+ let (_code, _out, err) = run_with(&dir, &["--no-config", "."], &CannedHtml(vec![]), HashMap::new());+ assert!(err.contains("Next.js"), "{err}");+ std::fs::remove_dir_all(&dir).unwrap();+}++#[test]+fn github_conflicts_with_list_rules() {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-list-{}", std::process::id()));+ std::fs::create_dir_all(&dir).unwrap();+ for args in [&["--list-rules", "--github"][..], &["--list-rules", "--github", "--json"][..]] {+ let (code, out, err) = run_with(&dir, args, &MissingHtmlEngine, HashMap::new());+ assert_eq!(code, 1, "{args:?}");+ assert!(out.is_empty(), "{out}");+ assert_eq!(+ err,+ "Error: --github annotates scan findings and cannot be used with --list-rules\n"+ );+ }+ std::fs::remove_dir_all(&dir).unwrap();+}++// The prompt reads the process's real stdin, so only the suppressed path is+// driven here; a regression would read stdin (EOF under cargo test < /dev/null+// or CI) and print the "Found 51 files" banner this test rejects.+fn run_tty(dir: &Path, args: &[&str]) -> (i32, String, String) {+ let argv: Vec<String> = args.iter().map(|s| s.to_string()).collect();+ let (mut io, cap) = Io::captured("", dir.to_path_buf(), HashMap::new());+ io.stdin_is_tty = true;+ let html = CannedHtml(vec![]);+ let engines = Engines { html: &html, url: None };+ let code = run_detect(&argv, &mut io, &engines);+ let out = String::from_utf8(cap.stdout.borrow().clone()).unwrap();+ let err = String::from_utf8(cap.stderr.borrow().clone()).unwrap();+ (code, out, err)+}++fn stage_many(tag: &str) -> std::path::PathBuf {+ let dir = std::env::temp_dir().join(format!("impeccable-gh-many-{tag}-{}", std::process::id()));+ std::fs::create_dir_all(&dir).unwrap();+ for i in 0..51 {+ std::fs::write(dir.join(format!("f{i}.css")), "body { margin: 0; }\n").unwrap();+ }+ dir+}++#[test]+fn github_skips_the_large_scan_prompt() {+ let dir = stage_many("gh");+ let (code, _out, err) = run_tty(&dir, &["--no-config", "--github", "."]);+ assert_eq!(code, 0, "{err}");+ assert!(!err.contains("Found 51 files"), "{err}");+ assert!(!err.contains("Continue?"), "{err}");+ std::fs::remove_dir_all(&dir).unwrap();+}diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.mdindex fde4fe7eb..fb0595eaa 100644--- a/docs/CLI-CONTRACT.md+++ b/docs/CLI-CONTRACT.md@@ -93,8 +93,10 @@ Notation: `stdout>` / `stderr>` are literal writes; `exit N`; template strings u| Flag | Effect ||---|---|| `--json` | JSON output to **stdout** |+| `--quiet` | text mode prints only summary line(s) to stderr |+| `--github` | GitHub Actions workflow commands to **stdout**, one per finding (`::warning` / `::notice` / `::error file=…,line=…,title=…::[id] snippet%0Adescription`). Paths are relative to `GITHUB_WORKSPACE` when set, else cwd. `line` is omitted when the finding has no line (`0` / NaN). Like `--json` it skips the text-mode notes (purple, scan and regex-only notes), the directory framework note and its port probe, and the >50-files prompt; an attached (`--cdp`) scan's capture notes go to stderr, as under `--json`. Combined with `--json` → `stderr> Error: --github cannot be used with --json\n`, `exit 1`. Combined with `--list-rules` (with or without `--json`) → `stderr> Error: --github annotates scan findings and cannot be used with --list-rules\n`, `exit 1`. Evaluated after `--help` (so `--github --help` prints usage). Exit codes are unchanged || `--quiet` | text mode prints only summary line(s) to stderr; under `--list-rules` it instead prints one rule id per line to **stdout** |-| `--list-rules` | print every registered rule (`all_antipatterns()`: the built-ins plus any installed rule pack) and **exit 0** without scanning. Catalog goes to **stdout**. `--json` pretty-prints an array of `{id,name,category,severity,scopes,description}` (plus `advisory: true` on advisory rules). `--quiet` prints one rule id per line. `--scope` and `--no-advisory` filter the catalog the same way they filter a scan; config ignores (`ignoreRules`) are not applied, so the catalog lists rules a project has switched off. A positional target or `--cdp` with it → `stderr> Error: --list-rules prints the rule catalog and takes no file, URL, or --cdp scan\n`, `exit 1`. Evaluated after `--help` (so `--list-rules --help` prints usage) |+| `--list-rules` | print every registered rule (`all_antipatterns()`: the built-ins plus any installed rule pack) and **exit 0** without scanning. Catalog goes to **stdout**. `--json` pretty-prints an array of `{id,name,category,severity,scopes,description}` (plus `advisory: true` on advisory rules). `--quiet` prints one rule id per line. `--scope` and `--no-advisory` filter the catalog the same way they filter a scan; config ignores (`ignoreRules`) are not applied, so the catalog lists rules a project has switched off. `--github` with it is rejected (see `--github`). A positional target or `--cdp` with it → `stderr> Error: --list-rules prints the rule catalog and takes no file, URL, or --cdp scan\n`, `exit 1`. Evaluated after `--help` (so `--list-rules --help` prints usage) || `--help` | print usage (stdout) and `exit 0` — evaluated *after* scope/viewport parsing (so a bad `--scope` still errors first) || `--no-advisory` | drop findings with `advisory === true` before output/exit-code || `--no-consent-hiding` | URL scans only (Rust engine): leave known consent managers' banners on the page instead of hiding them before the scan (see **Consent banners** under URL scans). No effect on file scans |@@ -119,6 +121,8 @@ 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. --jsonfor JSON, --quiet for ids only. Takes no targets--scope <name> Only report rules in the given design domain@@ -153,6 +157,7 @@ Advisory findings:Output streams:Human-readable findings go to stderr so stdout stays available for structuredoutput. 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:@@ -188,6 +193,7 @@ Examples:impeccable detect https://example.comimpeccable detect --cdp 9222 --target "My App" --jsonimpeccable detect --json .+ impeccable detect --github src/impeccable detect --list-rulesimpeccable detect --no-config src/```@@ -196,7 +202,7 @@ Examples:**Design system per target**: `scanOptionsFor(localPath)`: if design system enabled and `localPath` given, `loadDesignSystemForTarget(localPath, {cache})` walks up from the target's own dir (never cwd): a dir with `DESIGN.md`/`Design.md`/`design.md` (directly, or under fallback dirs `.agents/context`, `docs`) is the design root; a dir with a project marker (`.git`, `package.json`, `.impeccable`) but no DESIGN.md is a boundary → no design system; reaching `os.homedir()` or fs root → none. Sidecar candidates: `<root>/.impeccable/design.json`, `<root>/DESIGN.json`, `<contextDir>/DESIGN.json`. Cache key `root:<dir>` or `\0none`. Options become `{...baseScanOptions, designSystem}` when found. `design-system.mjs` has **no CLI surface** (no main guard, no argv parsing); it only exports functions.-**A DESIGN.md purple switches the purple AI-palette check off** (Rust engine, corpus decision r3-23-ai-color-palette-brand-hue). When a target's design system declares a purple or violet colour (a DESIGN.md frontmatter `colors` entry or a sidecar colour, chroma at least 30 and hue 250 to 320 degrees: `is_declared_purple` in `crates/core/src/checks/rules.rs`), every engine drops the purple/violet forms of `ai-color-palette` for that target: the static HTML engine (`Purple/violet text (#hex) on heading`, `text-purple-* on heading`, `Purple/violet gradient (Tailwind)`, `Purple/violet accent colors detected`), the regex engine (`text-(purple|violet|indigo)-* on heading`, `from-(purple|violet|indigo)-* gradient`) and the URL engine on a `file:` target (the same forms plus `Purple/violet gradient background` and `Purple/violet neon text on dark background`). A form is purple when its snippet names purple, violet or indigo (`is_purple_palette_finding`); the cyan forms (`Cyan gradient background`, `Cyan neon text on dark background`) keep reporting, and so does every other rule. The drop runs after the built-in passes and before a rule pack and inline ignores, so the design hook, which scans through the same engines with the project's design system, and the wasm `detect` exports get it too. `http(s)` targets never load a design system (above) and are unaffected. In text mode (not `--json`, not `--quiet`) the CLI then prints, once per design system that applied to a scanned target and after the findings or alone when there are none: `stderr> \nNote: ai-color-palette's purple/violet check is off: ${source_path} declares ${label} (${hex}).\n` (no leading blank line when there are no findings; `${label}` is the first purple's declared name, `colors.primary` or `sidecar.<name>`). JSON output has no place for notes and is unchanged apart from the dropped findings.+**A DESIGN.md purple switches the purple AI-palette check off** (Rust engine, corpus decision r3-23-ai-color-palette-brand-hue). When a target's design system declares a purple or violet colour (a DESIGN.md frontmatter `colors` entry or a sidecar colour, chroma at least 30 and hue 250 to 320 degrees: `is_declared_purple` in `crates/core/src/checks/rules.rs`), every engine drops the purple/violet forms of `ai-color-palette` for that target: the static HTML engine (`Purple/violet text (#hex) on heading`, `text-purple-* on heading`, `Purple/violet gradient (Tailwind)`, `Purple/violet accent colors detected`), the regex engine (`text-(purple|violet|indigo)-* on heading`, `from-(purple|violet|indigo)-* gradient`) and the URL engine on a `file:` target (the same forms plus `Purple/violet gradient background` and `Purple/violet neon text on dark background`). A form is purple when its snippet names purple, violet or indigo (`is_purple_palette_finding`); the cyan forms (`Cyan gradient background`, `Cyan neon text on dark background`) keep reporting, and so does every other rule. The drop runs after the built-in passes and before a rule pack and inline ignores, so the design hook, which scans through the same engines with the project's design system, and the wasm `detect` exports get it too. `http(s)` targets never load a design system (above) and are unaffected. In text mode (not `--json`, `--quiet` or `--github`) the CLI then prints, once per design system that applied to a scanned target and after the findings or alone when there are none: `stderr> \nNote: ai-color-palette's purple/violet check is off: ${source_path} declares ${label} (${hex}).\n` (no leading blank line when there are no findings; `${label}` is the first purple's declared name, `colors.primary` or `sidecar.<name>`). JSON output has no place for notes and is unchanged apart from the dropped findings.**Input resolution**:1. If `!process.stdin.isTTY && targets.length === 0` → **stdin mode** (`handleStdin`): read all stdin; try `JSON.parse`; if `parsed.tool_input.file_path` exists on disk → `detectLocalFile(fp, scanOptionsFor(fp))` (hook payload dispatch); else `detectText(input, '<stdin>', scanOptionsFor(null))`.@@ -204,15 +210,15 @@ Examples:3. For each target, in order:- URL: `file:` URLs get `scanOptionsFor(fileURLToPath(url) or null)`; http(s) get `baseScanOptions` (never cwd's design system). Errors: `stderr> Error: ${e.message}\n`, continue.- Else `resolved = path.resolve(target)`; `fs.statSync` failure → `stderr> Warning: cannot access ${target}\n`, continue.- - **Directory**: unless `--json`/`--quiet`, `detectFrameworkConfig(resolved)` (see below) and if found probes the port, writing one of three stderr notices:+ - **Directory**: unless `--json`/`--quiet`/`--github`, `detectFrameworkConfig(resolved)` (see below) and if found probes the port, writing one of three stderr notices:- listening & matched: `\n${name} dev server detected on localhost:${port}.\nFor more accurate results, scan the running site:\n npx impeccable detect http://localhost:${port}\n\n`- listening & !matched: `\n${name} project detected (${basename(configPath)}).\nPort ${port} is in use by another service. Start the ${name} dev server and scan via URL for best results.\n\n`- not listening: `\n${name} project detected (${basename(configPath)}).\nStart the dev server and scan via URL for best results:\n npx impeccable detect http://localhost:${port}\n\n`- Then `files = walkDir(resolved, config.extensions).filter(f => !shouldIgnoreDetectionFile(f, cwd, config))`. The walk collects built-in scannable extensions plus any `detector.extensions` from cwd config (empty under `--no-config`). If `files.length > 50 && stdin.isTTY && !json && !quiet`: `stderr> \nFound ${n} files (${htmlCount} HTML) in ${target}.\nScanning may take a while${htmlCount > 10 ? ' (static HTML/CSS processes each HTML file individually)' : ''}.\nTarget a specific subdirectory to narrow scope.\n` then readline prompt `Continue? [Y/n] ` on stderr; empty or `/^y(es)?$/i` continues; otherwise `stderr> Aborted.\n`, `exit 0`. Then `buildImportGraph(files)` → reverse map; each file scanned with its own options; findings from a file that is imported get `f.importedBy = [basename(importer), ...]` (Set iteration order).+ Then `files = walkDir(resolved, config.extensions).filter(f => !shouldIgnoreDetectionFile(f, cwd, config))`. The walk collects built-in scannable extensions plus any `detector.extensions` from cwd config (empty under `--no-config`). If `files.length > 50 && stdin.isTTY && !json && !quiet && !github`: `stderr> \nFound ${n} files (${htmlCount} HTML) in ${target}.\nScanning may take a while${htmlCount > 10 ? ' (static HTML/CSS processes each HTML file individually)' : ''}.\nTarget a specific subdirectory to narrow scope.\n` then readline prompt `Continue? [Y/n] ` on stderr; empty or `/^y(es)?$/i` continues; otherwise `stderr> Aborted.\n`, `exit 0`. Then `buildImportGraph(files)` → reverse map; each file scanned with its own options; findings from a file that is imported get `f.importedBy = [basename(importer), ...]` (Set iteration order).- **File**: skipped if `shouldIgnoreDetectionFile`; else `detectLocalFile`.- `detectLocalFile(fp, opts)`: a configured `detector.extensions` entry matching the file (longest suffix) picks the engine (`html` → `detectHtml(fp, opts)`, `text` → `detectText`); otherwise extension (lowercased) in `HTML_EXTENSIONS = {'.html','.htm'}` → `detectHtml(fp, opts)`; else `detectText(readFileSync(fp,'utf-8'), fp, opts)`. The design hook uses the same rule.- **Linked stylesheets (#1087)**: the static HTML engine reads every local `<link rel=stylesheet>` for the cascade, but a linked sheet that `detector.ignoreFiles` waives is left out of the page-level pattern scan, so a pattern found only in that sheet is no longer reported under the page at line 0. Element rules still apply its styles through the cascade, and sheets that are not waived join the pattern scan as before. The design hook waives linked sheets the same way, matching each one the way it matches the edited file.- - **Regex-only note (#884)**: after every target is scanned (never in stdin mode), unless `--json`/`--quiet`, if `n > 0` local files went to `detectText` (by the `detectLocalFile` routing above, so a configured `html`-engine extension is not counted): `stderr> \n${n} file${n === 1 ? '' : 's'} scanned with regex matching only${exts.length ? ` (${exts.join(', ')})` : ''}.\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` where `exts` is the sorted set of those files' lowercased extensions (`extFromFilePath`, empty ones dropped). Then the full scan: `ports` = the sorted, deduplicated `port` of every scanned directory that matched `FRAMEWORK_CONFIGS` (whether or not the dev-server nudge found it listening); when non-empty, `For the full check, scan ${ports.length === 1 ? 'the running app' : 'each running app'}:\n` followed by ` npx impeccable detect http://localhost:${port}\n` per port, else `For the full check, scan the running dev server (npx impeccable detect http://localhost:PORT) or a static site's built .html.\n`. Then, only when `exts` intersects `HTML_LIKE_TEMPLATE_EXTS = ['.astro', '.svelte', '.vue']` (in that order, `t` = the intersection): `${t.join('/')} files can take the HTML engine instead: add { "ext": "${t[0]}", "engine": "html" } under detector.extensions in .impeccable/config.json (trades the regex rules and line numbers for the element rules).\n`. JSX/TSX get no opt-in line because the HTML parser reads nothing useful from them. The note precedes the findings output and changes neither stdout nor the exit code.+ - **Regex-only note (#884)**: after every target is scanned (never in stdin mode), unless `--json`/`--quiet`/`--github`, if `n > 0` local files went to `detectText` (by the `detectLocalFile` routing above, so a configured `html`-engine extension is not counted): `stderr> \n${n} file${n === 1 ? '' : 's'} scanned with regex matching only${exts.length ? ` (${exts.join(', ')})` : ''}.\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` where `exts` is the sorted set of those files' lowercased extensions (`extFromFilePath`, empty ones dropped). Then the full scan: `ports` = the sorted, deduplicated `port` of every scanned directory that matched `FRAMEWORK_CONFIGS` (whether or not the dev-server nudge found it listening); when non-empty, `For the full check, scan ${ports.length === 1 ? 'the running app' : 'each running app'}:\n` followed by ` npx impeccable detect http://localhost:${port}\n` per port, else `For the full check, scan the running dev server (npx impeccable detect http://localhost:PORT) or a static site's built .html.\n`. Then, only when `exts` intersects `HTML_LIKE_TEMPLATE_EXTS = ['.astro', '.svelte', '.vue']` (in that order, `t` = the intersection): `${t.join('/')} files can take the HTML engine instead: add { "ext": "${t[0]}", "engine": "html" } under detector.extensions in .impeccable/config.json (trades the regex rules and line numbers for the element rules).\n`. JSX/TSX get no opt-in line because the HTML parser reads nothing useful from them. The note precedes the findings output and changes neither stdout nor the exit code.4. Post-filter: `filterDetectionFindings(all, config)` (ignoreRules/ignoreValues), then `filterByScopes(all, scopes)` (keeps findings whose rule declares any requested scope; empty scopes = no filter), then `--no-advisory` drop.5. Partition `{primary, advisory}` by `f.advisory === true || f.severity === 'advisory'`.@@ -233,7 +239,7 @@ reports no findings and prints `stderr> Error: the page is ...`.- text: `stderr> formatFindings(all,false) + '\n'`.- `exit(hadOperationalFailure ? 1 : (primary.length > 0 ? 2 : 0))`.- no findings: json → `stdout> []\n`; text/quiet → nothing. `exit(hadOperationalFailure ? 1 : 0)`.-- Text mode (not `--json`, not `--quiet`) prints scan notes after the findings, or alone when there are none, one line each in first-seen order: the DESIGN.md purple note; for a URL scan that hid consent banners `Hid the <names> consent banner(s) on <url> before scanning. Pass --no-consent-hiding to scan it.` (`<names>` joined `A, B and C`); for one that hid tours or preloaders `Hid <items> on <url> before scanning. Pass --no-overlay-hiding to scan it.`, each item `the <library> tour`, `the <builder> badge` or `the preloader <name>`, joined the same way; and for a URL scan whose capture held sliders that never started, the capture note under `content-hidden-at-rest` below.+- Text mode (not `--json`, `--quiet` or `--github`) prints scan notes after the findings, or alone when there are none, one line each in first-seen order: the DESIGN.md purple note; for a URL scan that hid consent banners `Hid the <names> consent banner(s) on <url> before scanning. Pass --no-consent-hiding to scan it.` (`<names>` joined `A, B and C`); for one that hid tours or preloaders `Hid <items> on <url> before scanning. Pass --no-overlay-hiding to scan it.`, each item `the <library> tour`, `the <builder> badge` or `the preloader <name>`, joined the same way; and for a URL scan whose capture held sliders that never started, the capture note under `content-hidden-at-rest` below.- Exit 1 takes precedence over exit 2: findings from the targets that did scando not turn a partial scan into a complete one (#711).- Any other exit: `1` for arg errors above; uncaught exceptions propagate to `cli.js` catch (`exit 1`).diff --git a/tests/oracle/DELTAS.md b/tests/oracle/DELTAS.mdindex 636ac40a5..7653d6f77 100644--- a/tests/oracle/DELTAS.md+++ b/tests/oracle/DELTAS.md@@ -7087,12 +7087,18 @@ A variants wrapper with no `data-impeccable-variant="original"` element (the han## Recorded 2026-10-17: detect --list-rules prints the detector catalog-`impeccable detect --list-rules` prints every built-in detector rule and exits 0 without scanning (`docs/CLI-CONTRACT.md`). Text mode groups rules by category on stdout; `--json` pretty-prints the array; `--quiet` prints one id per line. `--scope` and `--no-advisory` filter the catalog the same way they filter a scan. A file/URL target or `--cdp` with it is `Error: --list-rules prints the rule catalog and takes no file, URL, or --cdp scan` and exit 1. `--help` still wins. `detect-help` gains the flag, an Output streams line, and one example. New cases: `detect-list-rules`, `detect-list-rules-json`, `detect-list-rules-quiet`, `detect-list-rules-with-target`, `detect-list-rules-with-cdp`. Recorded from the binary and reviewed by hand; no golden other than `detect-help` moved.+`impeccable detect --list-rules` prints every registered detector rule and exits 0 without scanning (`docs/CLI-CONTRACT.md`). Text mode groups rules by category on stdout; `--json` pretty-prints the array; `--quiet` prints one id per line. `--scope` and `--no-advisory` filter the catalog the same way they filter a scan. A file/URL target or `--cdp` with it is `Error: --list-rules prints the rule catalog and takes no file, URL, or --cdp scan` and exit 1. `--help` still wins. `detect-help` gains the flag, an Output streams line, and one example. New cases: `detect-list-rules`, `detect-list-rules-json`, `detect-list-rules-quiet`, `detect-list-rules-with-target`, `detect-list-rules-with-cdp`. Recorded from the binary and reviewed by hand; no golden other than `detect-help` moved.## Recorded 2026-10-16: target selection lists only workspaces with a UI signal (#1014)`TARGET_SELECTION_REQUIRED` offered every workspace a package glob or the `apps/`/`packages/` fallback found, tsconfig and eslint-config packages included. Those candidates are now kept only with a UI signal: a UI framework dependency in `dependencies`, `devDependencies` or `peerDependencies`, their own PRODUCT/DESIGN file, a fixed entry path (`index.html`, iOS and Android project markers), a Flutter `pubspec.yaml` (a pure Dart package does not count), or a UI or style file in a one-level listing of the root or a usual source dir. Nothing walks a tree, per the Tier-1 boot budget. `projectRoots` matches are never filtered, a `!` projectRoots entry still hides a workspace, and when nothing would remain the full list is kept. A non-zero `skippedNonUiWorkspaces` count joins the JSON and one sentence joins the directive; with nothing skipped both are absent, so no existing golden moved (`ctx-monorepo` names its apps through `projectRoots`). `doctor` and bare-name `--target` resolution still see every workspace. New cases on the `ctx-monorepo-tooling` fixture, recorded from the binary and reviewed by hand: `context-monorepo-tooling-root` (web, the Flutter `apps/mobile` and ui listed; api, the pure Dart `packages/models` and three tooling packages skipped, 5), `context-monorepo-tooling-explicit-roots` (`apps/api` and `packages/scripts` kept because projectRoots names them, 3 skipped), `context-monorepo-tooling-negated-root` (`!packages/ui` leaves mobile and web, 5 skipped), `context-monorepo-tooling-no-ui` (UI workspaces removed, all five left listed, no count) and `context-monorepo-tooling-bare-name` (`--target tsconfig` still resolves the hidden package).+## Recorded 2026-10-17: detect --github writes GitHub Actions annotations++`impeccable detect --github` prints one GitHub Actions workflow command per finding on stdout (`docs/CLI-CONTRACT.md`). Primary findings are `::warning` (or `::error` when the rule's severity is error); advisories are `::notice`. Paths are relative to `GITHUB_WORKSPACE` when set, else cwd; `line` is omitted when the finding has none. `--json` with it is `Error: --github cannot be used with --json` and exit 1. `--help` still wins. Exit codes match a normal scan. `detect-help` gains the flag, an Output streams line, and one example. New cases: `detect-github` (a rounded side-tab card), `detect-github-clean` (a CSS file with no findings, stdout empty), `detect-github-json` (the conflict). Recorded from the binary and reviewed by hand; no golden other than `detect-help` moved.++Re-recorded 2026-10-21 after merging main (with `--list-rules`, #1064): `detect-help` carries both flags, the `--github` line now reads `Not with --json or --list-rules`. New case `detect-github-list-rules`: `--list-rules --github` is `Error: --github annotates scan findings and cannot be used with --list-rules` and exit 1, since a catalog has no findings to annotate. A directory scan with `--github` also skips the framework note and its port probe now, as `--json` and `--quiet` do. Recorded from the binary and reviewed by hand.+## Recorded 2026-10-16: the CSS border accent reads the element's rules, not a seven-line window (#1027)In stylesheet text `border-accent-on-rounded` took its radius from the three lines before and after the accent, so blank lines or an unrelated neighbour changed the finding. It now reads the accent's own rule scope and the rules tied to its selector in the file, the way `side-tab` does. A radius counts only when a declaration sets one (a mixin, `@apply` or a custom property does not), and markup still reads the line. New fixture `border-accent-blank-lines.css` and its cases `detect-fixture-json-border-accent-blank-lines-css` and `detect-fixture-text-border-accent-blank-lines-css` (five findings: the adjacent pair, the pair with five blank lines, the long block, the media query, a pseudo-element's split rules; the other-selector, custom-property, `@apply`, descendant and pseudo-element-radius rows are quiet). The directory and no-advisory sweeps (`detect-dir-json-all-fixtures`, `detect-dir-text-all-fixtures`, `detect-dir-quiet-all-fixtures`, `detect-no-advisory-json`, `detect-no-advisory-text`) and `detect-scope-layout-text` gain only that file: five findings in the JSON sweeps, the count moves 950 to 955, and the file count 57 to 58. Recorded from the binary and reviewed by hand; no other golden moved.diff --git a/tests/oracle/cases/detect.mjs b/tests/oracle/cases/detect.mjsindex 1f25590c5..e43a3a484 100644--- a/tests/oracle/cases/detect.mjs+++ b/tests/oracle/cases/detect.mjs@@ -127,6 +127,21 @@ function Thumb({ url }: { url?: string }) {// Flag surface and errors{ id: 'detect-help', verb: 'detect', args: ['--help'] },+ { id: 'detect-github-json', verb: 'detect', args: ['--github', '--json'] },+ { id: 'detect-github-list-rules', verb: 'detect', args: ['--list-rules', '--github'] },+ {+ id: 'detect-github', verb: 'detect',+ setup: (ws) => fs.writeFileSync(+ path.join(ws, 'card.html'),+ '<div style="border-left: 4px solid #ff0000; border-radius: 10px">x</div>\n',+ ),+ args: ['--no-config', '--github', 'card.html'],+ },+ {+ id: 'detect-github-clean', verb: 'detect',+ setup: (ws) => fs.writeFileSync(path.join(ws, 'ok.css'), 'body { margin: 0; }\n'),+ args: ['--no-config', '--github', 'ok.css'],+ },{ id: 'detect-list-rules', verb: 'detect', args: ['--list-rules'] },{ id: 'detect-list-rules-json', verb: 'detect', args: ['--list-rules', '--json'] },{ id: 'detect-list-rules-quiet', verb: 'detect', args: ['--list-rules', '--quiet'] },diff --git a/tests/oracle/golden/detect-github-clean.json b/tests/oracle/golden/detect-github-clean.jsonnew file mode 100644index 000000000..7ea122487--- /dev/null+++ b/tests/oracle/golden/detect-github-clean.json@@ -0,0 +1,7 @@+{+ "stdout": "",+ "stderr": "",+ "exit": 0,+ "signal": null,+ "files": {}+}diff --git a/tests/oracle/golden/detect-github-json.json b/tests/oracle/golden/detect-github-json.jsonnew file mode 100644index 000000000..02621935d--- /dev/null+++ b/tests/oracle/golden/detect-github-json.json@@ -0,0 +1,7 @@+{+ "stdout": "",+ "stderr": "Error: --github cannot be used with --json\n",+ "exit": 1,+ "signal": null,+ "files": {}+}diff --git a/tests/oracle/golden/detect-github-list-rules.json b/tests/oracle/golden/detect-github-list-rules.jsonnew file mode 100644index 000000000..f227395aa--- /dev/null+++ b/tests/oracle/golden/detect-github-list-rules.json@@ -0,0 +1,7 @@+{+ "stdout": "",+ "stderr": "Error: --github annotates scan findings and cannot be used with --list-rules\n",+ "exit": 1,+ "signal": null,+ "files": {}+}diff --git a/tests/oracle/golden/detect-github.json b/tests/oracle/golden/detect-github.jsonnew file mode 100644index 000000000..05f285598--- /dev/null+++ b/tests/oracle/golden/detect-github.json@@ -0,0 +1,7 @@+{+ "stdout": "::warning file=card.html,title=Side-tab accent border::[side-tab] border-left: 4px + border-radius: 10px%0AThick colored border on one side of a card — the most recognizable tell of AI-generated UIs. Use a subtler accent or remove it entirely.\n",+ "stderr": "",+ "exit": 2,+ "signal": null,+ "files": {}+}diff --git a/tests/oracle/golden/detect-help.json b/tests/oracle/golden/detect-help.jsonindex 00623a547..81f480cf1 100644--- a/tests/oracle/golden/detect-help.json+++ b/tests/oracle/golden/detect-help.json@@ -1,5 +1,5 @@{- "stdout": "Usage: impeccable detect [options] [file-or-dir-or-url...]\n\nScan files or URLs for UI anti-patterns and design quality issues.\n\nOptions:\n --json Output results as JSON\n --quiet In text mode, only print the final findings count\n --list-rules Print the detector rule catalog and exit. --json\n for JSON, --quiet for ids only. Takes no targets\n --scope <name> Only report rules in the given design domain\n (type, layout). Comma-separated.\n --viewport <WxH> Browser viewport for URL scans (default 1280x800),\n e.g. --viewport 390x844 for a mobile-width pass\n --no-config Do not apply project config, detector ignores, inline\n ignore comments, or DESIGN.md\n --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments\n --no-design-system Do not load local DESIGN.md / .impeccable/design.json context\n --no-advisory Suppress advisory findings entirely (e.g. em-dash overuse)\n --no-consent-hiding URL scans: keep known consent managers' banners\n (OneTrust, Cookiebot, ...) on the page instead of hiding\n them before the scan\n --no-overlay-hiding URL scans: keep product tours (driver.js) and\n preloaders still covering the page instead of hiding\n them before the scan\n --cdp <port|url> Scan a page of a running Chromium-based desktop app\n (Electron, NW.js, CEF, WebView2) through its local\n DevTools port instead of loading a URL. The page is\n scanned as shown and left as found: never navigated,\n resized or closed. Takes no file or URL targets\n --target <text> With --cdp: pick the page whose URL or title contains\n this text when the app has more than one\n --help Show this help message\n\nAdvisory findings:\n Some rules are advisory: detected and listed in a separate section, but never\n counted as failures and never changing the exit code. They stay out of the\n failure count so they never block automation. --no-advisory hides them.\n\nOutput streams:\n Human-readable findings go to stderr so stdout stays available for structured\n output. Use --json for JSON on stdout, or redirect text with 2> findings.txt.\n --list-rules writes the catalog to stdout (no scan).\n\nExit status:\n 0 Scan completed with no primary findings (advisories may still be listed)\n 1 At least one requested target could not be scanned\n 2 Scan completed with primary findings\n Operational failure takes precedence when a multi-target scan is partial.\n\nProject config:\n Respects .impeccable/config.json and .impeccable/config.local.json detector\n settings: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues,\n and detector.designSystem.enabled.\n\nInline ignores:\n In-file comments waive a finding where it lives and travel with the file:\n <!-- impeccable-disable overused-font -- exported brand doc -->\n .brand { font-family: Inter } /* impeccable-disable-line overused-font */\n // impeccable-disable-next-line bounce-easing: intentional bounce\n impeccable-disable applies to the whole file; -line / -next-line are scoped.\n List one or more rule ids (comma-separated), or omit them / use * for all.\n\nDetection modes:\n HTML files Static HTML/CSS analysis (default, catches linked CSS)\n Non-HTML files Regex pattern matching (CSS, JSX, TSX, etc.)\n URLs Puppeteer full browser rendering (auto-detected;\n http(s):// and file:// URLs; accessible linked CSS included)\n Running apps --cdp: a page of a Chromium-based app, attached through its\n DevTools port and scanned like a URL\n\nExamples:\n impeccable detect src/\n impeccable detect index.html\n impeccable detect https://example.com\n impeccable detect --cdp 9222 --target \"My App\" --json\n impeccable detect --json .\n impeccable detect --list-rules\n impeccable detect --no-config src/\n",+ "stdout": "Usage: impeccable detect [options] [file-or-dir-or-url...]\n\nScan files or URLs for UI anti-patterns and design quality issues.\n\nOptions:\n --json Output results as JSON\n --quiet In text mode, only print the final findings count\n --github Write GitHub Actions annotations for each\n finding. Not with --json or --list-rules\n --list-rules Print the detector rule catalog and exit. --json\n for JSON, --quiet for ids only. Takes no targets\n --scope <name> Only report rules in the given design domain\n (type, layout). Comma-separated.\n --viewport <WxH> Browser viewport for URL scans (default 1280x800),\n e.g. --viewport 390x844 for a mobile-width pass\n --no-config Do not apply project config, detector ignores, inline\n ignore comments, or DESIGN.md\n --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments\n --no-design-system Do not load local DESIGN.md / .impeccable/design.json context\n --no-advisory Suppress advisory findings entirely (e.g. em-dash overuse)\n --no-consent-hiding URL scans: keep known consent managers' banners\n (OneTrust, Cookiebot, ...) on the page instead of hiding\n them before the scan\n --no-overlay-hiding URL scans: keep product tours (driver.js) and\n preloaders still covering the page instead of hiding\n them before the scan\n --cdp <port|url> Scan a page of a running Chromium-based desktop app\n (Electron, NW.js, CEF, WebView2) through its local\n DevTools port instead of loading a URL. The page is\n scanned as shown and left as found: never navigated,\n resized or closed. Takes no file or URL targets\n --target <text> With --cdp: pick the page whose URL or title contains\n this text when the app has more than one\n --help Show this help message\n\nAdvisory findings:\n Some rules are advisory: detected and listed in a separate section, but never\n counted as failures and never changing the exit code. They stay out of the\n failure count so they never block automation. --no-advisory hides them.\n\nOutput streams:\n Human-readable findings go to stderr so stdout stays available for structured\n output. Use --json for JSON on stdout, or redirect text with 2> findings.txt.\n --github writes Actions annotations to stdout (no human findings).\n --list-rules writes the catalog to stdout (no scan).\n\nExit status:\n 0 Scan completed with no primary findings (advisories may still be listed)\n 1 At least one requested target could not be scanned\n 2 Scan completed with primary findings\n Operational failure takes precedence when a multi-target scan is partial.\n\nProject config:\n Respects .impeccable/config.json and .impeccable/config.local.json detector\n settings: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues,\n and detector.designSystem.enabled.\n\nInline ignores:\n In-file comments waive a finding where it lives and travel with the file:\n <!-- impeccable-disable overused-font -- exported brand doc -->\n .brand { font-family: Inter } /* impeccable-disable-line overused-font */\n // impeccable-disable-next-line bounce-easing: intentional bounce\n impeccable-disable applies to the whole file; -line / -next-line are scoped.\n List one or more rule ids (comma-separated), or omit them / use * for all.\n\nDetection modes:\n HTML files Static HTML/CSS analysis (default, catches linked CSS)\n Non-HTML files Regex pattern matching (CSS, JSX, TSX, etc.)\n URLs Puppeteer full browser rendering (auto-detected;\n http(s):// and file:// URLs; accessible linked CSS included)\n Running apps --cdp: a page of a Chromium-based app, attached through its\n DevTools port and scanned like a URL\n\nExamples:\n impeccable detect src/\n impeccable detect index.html\n impeccable detect https://example.com\n impeccable detect --cdp 9222 --target \"My App\" --json\n impeccable detect --json .\n impeccable detect --github src/\n impeccable detect --list-rules\n impeccable detect --no-config src/\n","stderr": "","exit": 0,"signal": null,