1import fs from 'node:fs';
2import path from 'node:path';
3 
4import { loadDesignSystemForCwd } from '../design-system.mjs';
5import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
6import { detectHtml } from '../engines/static-html/detect-html.mjs';
7import { detectText } from '../engines/regex/detect-text.mjs';
8import {
9  filterDetectionFindings,
10  readDetectionConfig,
11  shouldIgnoreDetectionFile,
12} from '../../lib/impeccable-config.mjs';
13import {
14  HTML_EXTENSIONS,
15  buildImportGraph,
16  detectFrameworkConfig,
17  isPortListening,
18  walkDir,
19} from '../node/file-system.mjs';
20 
21// ---------------------------------------------------------------------------
22// Output formatting
23// ---------------------------------------------------------------------------
24 
25function formatFindingSummary(count) {
26  return `${count} anti-pattern${count === 1 ? '' : 's'} found.`;
27}
28 
29function formatFindings(findings, jsonMode) {
30  if (jsonMode) return JSON.stringify(findings, null, 2);
31 
32  const grouped = {};
33  for (const f of findings) {
34    if (!grouped[f.file]) grouped[f.file] = [];
35    grouped[f.file].push(f);
36  }
37  const out = [];
38  for (const [file, items] of Object.entries(grouped)) {
39    const importNote = items[0]?.importedBy?.length ? ` (imported by ${items[0].importedBy.join(', ')})` : '';
40    out.push(`\n${file}${importNote}`);
41    for (const item of items) {
42      out.push(`  ${item.line ? `line ${item.line}: ` : ''}[${item.antipattern}] ${item.snippet}`);
43      out.push(`    → ${item.description}`);
44    }
45  }
46  out.push(`\n${formatFindingSummary(findings.length)}`);
47  return out.join('\n');
48}
49 
50// ---------------------------------------------------------------------------
51// Stdin handling
52// ---------------------------------------------------------------------------
53 
54async function handleStdin(options = {}) {
55  const chunks = [];
56  for await (const chunk of process.stdin) chunks.push(chunk);
57  const input = Buffer.concat(chunks).toString('utf-8');
58  try {
59    const parsed = JSON.parse(input);
60    const fp = parsed?.tool_input?.file_path;
61    if (fp && fs.existsSync(fp)) {
62      return HTML_EXTENSIONS.has(path.extname(fp).toLowerCase())
63        ? detectHtml(fp, options) : detectText(fs.readFileSync(fp, 'utf-8'), fp, options);
64    }
65  } catch { /* not JSON */ }
66  return detectText(input, '<stdin>', options);
67}
68 
69 
70// ---------------------------------------------------------------------------
71// CLI
72// ---------------------------------------------------------------------------
73 
74async function confirm(question) {
75  const rl = (await import('node:readline')).default.createInterface({
76    input: process.stdin, output: process.stderr,
77  });
78  return new Promise((resolve) => {
79    rl.question(`${question} [Y/n] `, (answer) => {
80      rl.close();
81      resolve(!answer || /^y(es)?$/i.test(answer.trim()));
82    });
83  });
84}
85 
86function printUsage() {
87  console.log(`Usage: impeccable detect [options] [file-or-dir-or-url...]
88 
89Scan files or URLs for UI anti-patterns and design quality issues.
90 
91Options:
92  --json              Output results as JSON
93  --quiet             In text mode, only print the final findings count
94  --gpt               Also report GPT-specific provider tells (off by default)
95  --gemini            Also report Gemini-specific provider tells (off by default)
96  --no-config         Do not apply project config, detector ignores, inline
97                      ignore comments, or DESIGN.md
98  --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
99  --no-design-system  Do not load local DESIGN.md / .impeccable/design.json context
100  --help              Show this help message
101 
102Project config:
103  Respects .impeccable/config.json and .impeccable/config.local.json detector
104  settings: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues,
105  and detector.designSystem.enabled.
106 
107Inline ignores:
108  In-file comments waive a finding where it lives and travel with the file:
109    <!-- impeccable-disable overused-font -- exported brand doc -->
110    .brand { font-family: Inter } /* impeccable-disable-line overused-font */
111    // impeccable-disable-next-line bounce-easing: intentional bounce
112  impeccable-disable applies to the whole file; -line / -next-line are scoped.
113  List one or more rule ids (comma-separated), or omit them / use * for all.
114 
115Detection modes:
116  HTML files     Static HTML/CSS analysis (default, catches linked CSS)
117  Non-HTML files Regex pattern matching (CSS, JSX, TSX, etc.)
118  URLs           Puppeteer full browser rendering (auto-detected)
119 
120Examples:
121  impeccable detect src/
122  impeccable detect index.html
123  impeccable detect https://example.com
124  impeccable detect --json .
125  impeccable detect --no-config src/`);
126}
127 
128async function detectCli() {
129  let args = process.argv.slice(2).map(arg => {
130    if (arg === '-json') return '--json';
131    if (arg === '-fast') return '--fast';
132    return arg;
133  });
134  if (args[0] === 'detect') args = args.slice(1);
135  const jsonMode = args.includes('--json');
136  const quietMode = args.includes('--quiet');
137  const helpMode = args.includes('--help');
138  // --fast (regex-only) is deprecated: since the jsdom removal, the static
139  // HTML/CSS analysis is fast and covers every rule, so the regex-only path
140  // only loses coverage for no real speed win. Accept the flag for back-compat
141  // but ignore it and run the full scan.
142  if (args.includes('--fast')) {
143    process.stderr.write(
144      'Note: --fast is deprecated and ignored. The full scan is fast now and runs every rule.\n',
145    );
146  }
147  const configEnabled = !args.includes('--no-config');
148  const detectionConfig = configEnabled
149    ? readDetectionConfig(process.cwd())
150    : { ignoreRules: [], ignoreFiles: [], ignoreValues: [] };
151  const providers = [];
152  if (args.includes('--gpt')) providers.push('gpt');
153  if (args.includes('--gemini')) providers.push('gemini');
154  const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
155  const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
156  // Inline `impeccable-disable*` waivers are part of the scanned file, so they
157  // apply by default. `--no-config` (raw scan) and the dedicated
158  // `--no-inline-ignores` both turn them off.
159  const inlineIgnoresEnabled = configEnabled && !args.includes('--no-inline-ignores');
160  const scanOptions = { providers, inlineIgnores: inlineIgnoresEnabled };
161  if (designSystem) scanOptions.designSystem = designSystem;
162  const targets = args.filter(a => !a.startsWith('--'));
163 
164  if (helpMode) { printUsage(); process.exit(0); }
165 
166  let allFindings = [];
167 
168  if (!process.stdin.isTTY && targets.length === 0) {
169    allFindings = await handleStdin(scanOptions);
170  } else {
171    const paths = targets.length > 0 ? targets : [process.cwd()];
172    const urlTargetCount = paths.filter(target => /^https?:\/\//i.test(target)).length;
173    const browserDetector = urlTargetCount > 1 ? await createBrowserDetector() : null;
174 
175    try {
176      for (const target of paths) {
177        if (/^https?:\/\//i.test(target)) {
178          try {
179            const scanner = browserDetector
180              ? (url) => browserDetector.detectUrl(url, scanOptions)
181              : (url) => detectUrl(url, scanOptions);
182            allFindings.push(...await scanner(target));
183          } catch (e) { process.stderr.write(`Error: ${e.message}\n`); }
184          continue;
185        }
186 
187        const resolved = path.resolve(target);
188        let stat;
189        try { stat = fs.statSync(resolved); }
190        catch { process.stderr.write(`Warning: cannot access ${target}\n`); continue; }
191 
192        if (stat.isDirectory()) {
193          // Check for framework dev server config (skip in JSON/quiet modes to avoid polluting output)
194          if (!jsonMode && !quietMode) {
195            const fwConfig = detectFrameworkConfig(resolved);
196            if (fwConfig) {
197              const probe = await isPortListening(fwConfig.port, fwConfig.fingerprint);
198              if (probe.listening && probe.matched) {
199                process.stderr.write(
200                  `\n${fwConfig.name} dev server detected on localhost:${fwConfig.port}.\n` +
201                  `For more accurate results, scan the running site:\n` +
202                  `  npx impeccable detect http://localhost:${fwConfig.port}\n\n`
203                );
204              } else if (probe.listening && !probe.matched) {
205                process.stderr.write(
206                  `\n${fwConfig.name} project detected (${path.basename(fwConfig.configPath)}).\n` +
207                  `Port ${fwConfig.port} is in use by another service. Start the ${fwConfig.name} dev server and scan via URL for best results.\n\n`
208                );
209              } else {
210                process.stderr.write(
211                  `\n${fwConfig.name} project detected (${path.basename(fwConfig.configPath)}).\n` +
212                  `Start the dev server and scan via URL for best results:\n` +
213                  `  npx impeccable detect http://localhost:${fwConfig.port}\n\n`
214                );
215              }
216            }
217          }
218 
219          const files = walkDir(resolved)
220            .filter(file => !shouldIgnoreDetectionFile(file, process.cwd(), detectionConfig));
221          const htmlCount = files.filter(f => HTML_EXTENSIONS.has(path.extname(f).toLowerCase())).length;
222 
223          // Warn and confirm if scanning many files (static HTML/CSS processes each HTML file)
224          if (files.length > 50 && process.stdin.isTTY && !jsonMode && !quietMode) {
225            process.stderr.write(
226              `\nFound ${files.length} files (${htmlCount} HTML) in ${target}.\n` +
227              `Scanning may take a while${htmlCount > 10 ? ' (static HTML/CSS processes each HTML file individually)' : ''}.\n` +
228              `Target a specific subdirectory to narrow scope.\n`
229            );
230            const ok = await confirm('Continue?');
231            if (!ok) { process.stderr.write('Aborted.\n'); process.exit(0); }
232          }
233 
234          // Build import graph for multi-file awareness
235          const graph = buildImportGraph(files);
236          // Build reverse map: file -> set of files that import it
237          const importedByMap = new Map();
238          for (const [importer, imports] of graph) {
239            for (const imported of imports) {
240              if (!importedByMap.has(imported)) importedByMap.set(imported, new Set());
241              importedByMap.get(imported).add(importer);
242            }
243          }
244 
245          for (const file of files) {
246            const ext = path.extname(file).toLowerCase();
247            let fileFindings;
248            if (HTML_EXTENSIONS.has(ext)) {
249              fileFindings = await detectHtml(file, scanOptions);
250            } else {
251              fileFindings = detectText(fs.readFileSync(file, 'utf-8'), file, scanOptions);
252            }
253            // Annotate findings with import context
254            const importers = importedByMap.get(file);
255            if (importers && importers.size > 0) {
256              const importerNames = [...importers].map(f => path.basename(f));
257              for (const f of fileFindings) {
258                f.importedBy = importerNames;
259              }
260            }
261            allFindings.push(...fileFindings);
262          }
263        } else if (stat.isFile()) {
264          if (shouldIgnoreDetectionFile(resolved, process.cwd(), detectionConfig)) continue;
265          const ext = path.extname(resolved).toLowerCase();
266          if (HTML_EXTENSIONS.has(ext)) {
267            allFindings.push(...await detectHtml(resolved, scanOptions));
268          } else {
269            allFindings.push(...detectText(fs.readFileSync(resolved, 'utf-8'), resolved, scanOptions));
270          }
271        }
272      }
273    } finally {
274      if (browserDetector) await browserDetector.close();
275    }
276  }
277 
278  allFindings = filterDetectionFindings(allFindings, detectionConfig);
279 
280  if (allFindings.length > 0) {
281    if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
282    else if (quietMode) process.stderr.write(formatFindingSummary(allFindings.length) + '\n');
283    else process.stderr.write(formatFindings(allFindings, false) + '\n');
284    process.exit(2);
285  }
286  if (jsonMode) process.stdout.write('[]\n');
287  process.exit(0);
288}
289 
290export { formatFindings, handleStdin, confirm, printUsage, detectCli };
291