impeccable 3.0.2 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -81,7 +81,7 @@ impeccable detect [options] [file-or-dir-or-url...]
81
81
 
82
82
  ## Part of Impeccable
83
83
 
84
- This CLI is part of [Impeccable](https://impeccable.style), a cross-provider design skill pack for AI-powered development tools. The full suite includes 23 commands for Claude, Cursor, Gemini, Codex, and more.
84
+ This CLI is part of [Impeccable](https://impeccable.style), a cross-provider design skill pack for AI-powered development tools. The full suite includes 23 commands for Claude, Cursor, GitHub Copilot, Gemini, Codex, and more.
85
85
 
86
86
  ## License
87
87
 
package/README.npm.md CHANGED
@@ -81,7 +81,7 @@ impeccable detect [options] [file-or-dir-or-url...]
81
81
 
82
82
  ## Part of Impeccable
83
83
 
84
- This CLI is part of [Impeccable](https://impeccable.style), a cross-provider design skill pack for AI-powered development tools. The full suite includes 23 commands for Claude, Cursor, Gemini, Codex, and more.
84
+ This CLI is part of [Impeccable](https://impeccable.style), a cross-provider design skill pack for AI-powered development tools. The full suite includes 23 commands for Claude, Cursor, GitHub Copilot, Gemini, Codex, and more.
85
85
 
86
86
  ## License
87
87
 
package/README.repo.md CHANGED
@@ -260,11 +260,12 @@ If you reach for one command often, pin it with `/impeccable pin audit` to get `
260
260
 
261
261
  ## Design hook
262
262
 
263
- On Claude Code, Codex, and Cursor, `npx impeccable install` and `npx impeccable update` install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code and Codex surface findings after the edit. Cursor blocks bad proposed writes before they land.
263
+ On Claude Code, GitHub Copilot, Codex, and Cursor, `npx impeccable install` and `npx impeccable update` install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, and Codex surface findings after the edit. Cursor blocks bad proposed writes before they land.
264
264
 
265
265
  Installed hook surfaces:
266
266
 
267
267
  - Claude Code: `.claude/settings.local.json` (gitignored, machine-local) runs `${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs`. A hook moved into the shared `settings.json` is honored in place.
268
+ - GitHub Copilot: `.github/hooks/impeccable.json` (committed, shared by the Copilot CLI and the cloud agent) runs `.github/skills/impeccable/scripts/hook.mjs`. The Copilot CLI activates it once the file is on the repository's default branch and the folder is trusted.
268
269
  - Cursor: `.cursor/hooks.json` runs `.cursor/skills/impeccable/scripts/hook-before-edit.mjs`.
269
270
  - Codex: `.codex/hooks.json` runs `.agents/skills/impeccable/scripts/hook.mjs`.
270
271
 
@@ -304,17 +305,19 @@ The detector catches 44 deterministic issues across AI slop (side-tab borders, p
304
305
 
305
306
  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.
306
307
 
308
+ For a waiver that should travel with one file instead of the repo config, add an inline comment in the file: `<!-- impeccable-disable overused-font: exported brand doc -->`. The marker works in any comment syntax, scopes to the whole file (or one line with `impeccable-disable-line` / `impeccable-disable-next-line`), and is bypassed by `--no-inline-ignores` or `--no-config`.
309
+
307
310
  Full detector docs: [impeccable.style/docs/detector](https://impeccable.style/docs/detector).
308
311
 
309
312
  ## Supported Tools
310
313
 
311
314
  - [Cursor](https://cursor.com)
312
315
  - [Claude Code](https://claude.ai/code)
313
- - [OpenCode](https://opencode.ai)
314
- - [Pi](https://pi.dev)
316
+ - [GitHub Copilot](https://github.com/features/copilot)
315
317
  - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
316
318
  - [Codex CLI](https://github.com/openai/codex)
317
- - [VS Code Copilot](https://code.visualstudio.com)
319
+ - [OpenCode](https://opencode.ai)
320
+ - [Pi](https://pi.dev)
318
321
  - [Kiro](https://kiro.dev)
319
322
  - [Trae](https://trae.ai)
320
323
  - [Rovo Dev](https://www.atlassian.com/software/rovo)
package/cli/bin/cli.js CHANGED
@@ -10,13 +10,24 @@
10
10
  * npx impeccable --help
11
11
  */
12
12
 
13
- import { readFileSync } from 'node:fs';
14
- import { join, dirname } from 'node:path';
13
+ import { readFileSync, existsSync } from 'node:fs';
14
+ import { join, dirname, resolve } from 'node:path';
15
15
  import { fileURLToPath } from 'node:url';
16
16
 
17
17
  const __dirname = dirname(fileURLToPath(import.meta.url));
18
18
  const SKILL_COMMANDS = new Set(['help', 'install', 'link', 'update', 'check']);
19
19
 
20
+ // Is this a detect target (the `npx impeccable src/` shorthand) or a mistyped
21
+ // command? Flags, URLs, path-shaped args, and real files/dirs (e.g. an
22
+ // extension-less `Dockerfile`) are targets; anything else is an unknown command.
23
+ function looksLikeDetectTarget(arg) {
24
+ const isFlag = arg.startsWith('-');
25
+ const isUrl = /^https?:\/\//i.test(arg);
26
+ const isPathShaped = arg.includes('/') || arg.includes('\\') || arg.includes('.');
27
+ const isExistingPath = existsSync(resolve(arg));
28
+ return isFlag || isUrl || isPathShaped || isExistingPath;
29
+ }
30
+
20
31
  async function main() {
21
32
  const args = process.argv.slice(2);
22
33
  const command = args[0];
@@ -61,11 +72,16 @@ Compatibility:
61
72
  } else if (SKILL_COMMANDS.has(command)) {
62
73
  const { run } = await import('./commands/skills.mjs');
63
74
  await run(args);
64
- } else {
75
+ } else if (looksLikeDetectTarget(command)) {
65
76
  // Default: treat as detect arguments (allow `npx impeccable src/` shorthand)
66
77
  process.argv = [process.argv[0], process.argv[1], ...args];
67
78
  const { detectCli } = await import('../engine/detect-antipatterns.mjs');
68
79
  await detectCli();
80
+ } else {
81
+ // An unknown bareword: a mistyped command (or an old cached version run
82
+ // against newer docs). Fail loudly instead of silently statting it as a path.
83
+ console.error(`Unknown command: "${command}"\n\nTo see a list of supported commands, run:\n impeccable --help`);
84
+ process.exit(1);
69
85
  }
70
86
  }
71
87
 
@@ -103,6 +103,12 @@ const PROVIDER_HOOK_ARTIFACTS = {
103
103
  '.agents': [
104
104
  { sourceProvider: '.codex', rel: 'hooks.json', destProvider: '.codex' },
105
105
  ],
106
+ // GitHub Copilot reads repo-level hooks from `.github/hooks/*.json`. Unlike
107
+ // Claude, this is a team-shared, committed file (not a machine-local override),
108
+ // so source and dest are the same path.
109
+ '.github': [
110
+ { sourceProvider: '.github', rel: 'hooks/impeccable.json', destProvider: '.github' },
111
+ ],
106
112
  };
107
113
 
108
114
  let pipedAnswers = null;
@@ -421,19 +427,20 @@ function getSkillsVersion(root) {
421
427
  }
422
428
 
423
429
  /**
424
- * Hash all SKILL.md files in a directory tree for comparison.
425
- * Returns a sorted string of "name:hash" pairs.
430
+ * Return every file in a directory tree, sorted and relative to the tree root.
426
431
  */
427
- function hashSkillsDir(skillsDir) {
428
- if (!existsSync(skillsDir)) return '';
429
- const entries = [];
430
- for (const name of readdirSync(skillsDir).sort()) {
431
- const skillMd = join(skillsDir, name, 'SKILL.md');
432
- if (!existsSync(skillMd)) continue;
433
- const hash = createHash('sha256').update(readFileSync(skillMd)).digest('hex').slice(0, 12);
434
- entries.push(`${name}:${hash}`);
432
+ function listSkillTreeFiles(root, dir = root) {
433
+ if (!existsSync(dir)) return [];
434
+ const files = [];
435
+ for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
436
+ const full = join(dir, entry.name);
437
+ if (entry.isDirectory()) {
438
+ files.push(...listSkillTreeFiles(root, full));
439
+ } else if (entry.isFile()) {
440
+ files.push(relative(root, full).split(sep).join('/'));
441
+ }
435
442
  }
436
- return entries.join(',');
443
+ return files;
437
444
  }
438
445
 
439
446
  /**
@@ -507,11 +514,18 @@ async function copyOrExtractLocalBundle(sourceValue) {
507
514
  * provider-specific paths. Different install methods (npx skills add
508
515
  * vs our bundle) resolve {{scripts_path}} to different provider dirs
509
516
  * (e.g. .agents vs .claude), so we strip those differences.
517
+ * Version fields intentionally remain part of the comparison so metadata-only
518
+ * releases still refresh installed files.
510
519
  */
511
520
  function normalizeForHash(content) {
512
521
  return content
513
- .replace(/\.(claude|cursor|agents|github|gemini|codex|kiro|opencode|pi|qoder|trae|trae-cn|rovodev)\/skills\//g, '.PROVIDER/skills/')
514
- .replace(/^version:\s*.+$/m, 'version: NORMALIZED');
522
+ .replace(/\.(claude|cursor|agents|github|gemini|codex|kiro|opencode|pi|qoder|trae|trae-cn|rovodev)\/skills\//g, '.PROVIDER/skills/');
523
+ }
524
+
525
+ function hashSkillFile(filePath) {
526
+ return createHash('sha256')
527
+ .update(normalizeForHash(readFileSync(filePath, 'utf-8')))
528
+ .digest('hex');
515
529
  }
516
530
 
517
531
  /**
@@ -536,10 +550,10 @@ function deduplicateProviders(root, providers) {
536
550
 
537
551
  /**
538
552
  * Compare local skills against a downloaded bundle.
539
- * Only checks skills that exist in the bundle (ignores user's custom
540
- * skills that aren't part of impeccable). Deduplicates providers that
541
- * share the same real path (symlinks). Normalizes provider-specific
542
- * paths and version fields before comparing.
553
+ * Only checks skills that exist in the bundle (ignores user's custom skills
554
+ * that aren't part of impeccable). Deduplicates providers that share the same
555
+ * real path (symlinks). Compares the full bundled skill tree, not just
556
+ * SKILL.md, so script-only fixes and removed files are detected.
543
557
  * Returns true if every bundle skill matches the local copy.
544
558
  */
545
559
  function isUpToDate(root, providers, bundleDir) {
@@ -551,14 +565,21 @@ function isUpToDate(root, providers, bundleDir) {
551
565
  if (!existsSync(bundleSkillsDir)) continue;
552
566
 
553
567
  for (const name of readdirSync(bundleSkillsDir)) {
554
- const bundleMd = join(bundleSkillsDir, name, 'SKILL.md');
555
- const localMd = join(localSkillsDir, name, 'SKILL.md');
568
+ const bundleSkillDir = join(bundleSkillsDir, name);
569
+ const localSkillDir = join(localSkillsDir, name);
570
+ const bundleMd = join(bundleSkillDir, 'SKILL.md');
556
571
  if (!existsSync(bundleMd)) continue;
557
- if (!existsSync(localMd)) return false;
572
+ if (!existsSync(localSkillDir)) return false;
573
+
574
+ const bundleFiles = listSkillTreeFiles(bundleSkillDir);
575
+ const localFiles = listSkillTreeFiles(localSkillDir);
576
+ if (bundleFiles.join('\n') !== localFiles.join('\n')) return false;
558
577
 
559
- const bundleHash = createHash('sha256').update(normalizeForHash(readFileSync(bundleMd, 'utf-8'))).digest('hex');
560
- const localHash = createHash('sha256').update(normalizeForHash(readFileSync(localMd, 'utf-8'))).digest('hex');
561
- if (bundleHash !== localHash) return false;
578
+ for (const relPath of bundleFiles) {
579
+ const bundleHash = hashSkillFile(join(bundleSkillDir, ...relPath.split('/')));
580
+ const localHash = hashSkillFile(join(localSkillDir, ...relPath.split('/')));
581
+ if (bundleHash !== localHash) return false;
582
+ }
562
583
  }
563
584
  }
564
585
  return true;
@@ -1019,6 +1040,26 @@ function copyProviderSkills(bundleDir, root, targets) {
1019
1040
  return written;
1020
1041
  }
1021
1042
 
1043
+ function refreshProviderSkills(bundleDir, root, providers) {
1044
+ const unique = deduplicateProviders(root, providers);
1045
+ let updated = 0;
1046
+ for (const { provider, localSkillsDir } of unique) {
1047
+ const srcDir = join(bundleDir, provider, 'skills');
1048
+ if (!existsSync(srcDir)) continue;
1049
+
1050
+ const skills = readdirSync(srcDir, { withFileTypes: true });
1051
+ for (const skill of skills) {
1052
+ if (!skill.isDirectory()) continue;
1053
+ const src = join(srcDir, skill.name);
1054
+ const dest = join(localSkillsDir, skill.name);
1055
+ if (existsSync(dest)) rmSync(dest, { recursive: true, force: true });
1056
+ copyDirSync(src, dest);
1057
+ updated++;
1058
+ }
1059
+ }
1060
+ return updated;
1061
+ }
1062
+
1022
1063
  function hookArtifactsForProvider(bundleDir, root, provider) {
1023
1064
  return (PROVIDER_HOOK_ARTIFACTS[provider] || []).map(({ sourceProvider, rel, destProvider, destRel }) => {
1024
1065
  const writeRel = destRel || rel;
@@ -1037,6 +1078,12 @@ function hookArtifactsForProvider(bundleDir, root, provider) {
1037
1078
  }
1038
1079
 
1039
1080
  function hookScriptPathForProvider(skillRoot, provider) {
1081
+ // `.github` is intentionally absent: its hook manifest (`.github/hooks/
1082
+ // impeccable.json`) is a committed, team-shared file that the Copilot cloud
1083
+ // agent and every teammate read, so the command must stay portable
1084
+ // (`$(git rev-parse --show-toplevel)/.github/skills/...`). Rewriting it to a
1085
+ // machine-local absolute skillRoot path would break those. GitHub skills are
1086
+ // project-scoped (not a home-provider), so the project-relative path resolves.
1040
1087
  if (provider === '.cursor') {
1041
1088
  return join(skillRoot, provider, 'skills', 'impeccable', 'scripts', 'hook-before-edit.mjs');
1042
1089
  }
@@ -1125,7 +1172,10 @@ function valueHasImpeccableHookMarker(value) {
1125
1172
 
1126
1173
  function stripImpeccableHookEntry(entry) {
1127
1174
  if (!entry || typeof entry !== 'object') return entry;
1128
- if (valueHasImpeccableHookMarker(entry.command) || valueHasImpeccableHookMarker(entry.args)) {
1175
+ // `command`/`args`: Claude/Codex/Cursor. `bash`/`powershell`: GitHub Copilot's
1176
+ // flat entry shape, where the marker lives under the shell-command keys.
1177
+ if (valueHasImpeccableHookMarker(entry.command) || valueHasImpeccableHookMarker(entry.args)
1178
+ || valueHasImpeccableHookMarker(entry.bash) || valueHasImpeccableHookMarker(entry.powershell)) {
1129
1179
  return null;
1130
1180
  }
1131
1181
  if (!Array.isArray(entry.hooks)) return entry;
@@ -1455,25 +1505,62 @@ async function install(flags) {
1455
1505
  if (existing && !force) {
1456
1506
  console.log(`Impeccable skills are already installed (found in ${existing}/).`);
1457
1507
  const installedTargets = findInstalledProviders(installRoot);
1458
- const hookTargets = targets.filter(provider => installedTargets.includes(provider));
1508
+ const selectedInstalledTargets = targets.filter(provider => installedTargets.includes(provider));
1509
+ const linkedTargets = findLinkedProviders(installRoot, selectedInstalledTargets);
1510
+ const copyTargets = selectedInstalledTargets.filter(provider => !linkedTargets.includes(provider));
1511
+ const hookTargets = selectedInstalledTargets;
1459
1512
  const wantHooks = installHooks && await decideHookInstall(hookRoot, hookTargets, { yes });
1460
- const missingHookTargets = wantHooks
1461
- ? hookTargets.filter(provider => !hookInstalledForProvider(hookRoot, provider))
1462
- : [];
1463
- if (missingHookTargets.length > 0) {
1464
- let bundleDir;
1465
- try {
1466
- bundleDir = await downloadAndExtractBundle();
1467
- const writtenHookTargets = copyProviderHooks(bundleDir, hookRoot, missingHookTargets, { skillRoot: installRoot });
1468
- if (writtenHookTargets.length > 0) console.log(`Installed hooks into: ${writtenHookTargets.join(', ')}`);
1469
- } catch (e) {
1470
- console.error(`Hook install failed: ${e.message}`);
1471
- process.exit(1);
1472
- } finally {
1473
- if (bundleDir) rmSync(bundleDir, { recursive: true, force: true });
1513
+ let bundleDir;
1514
+ try {
1515
+ if (linkedTargets.length > 0) {
1516
+ console.log(`Linked skills found in: ${linkedTargets.join(', ')}`);
1517
+ console.log('Update the source checkout with `git submodule update --remote`, then rerun `npx impeccable link --source=.impeccable` if new skills are added.');
1518
+ if (copyTargets.length > 0) console.log(`Continuing with copied installs in: ${copyTargets.join(', ')}\n`);
1519
+ }
1520
+
1521
+ let updated = 0;
1522
+ const missingHookTargets = wantHooks
1523
+ ? hookTargets.filter(provider => !hookInstalledForProvider(hookRoot, provider))
1524
+ : [];
1525
+ let updateCheckSkipped = false;
1526
+ if (copyTargets.length > 0 || missingHookTargets.length > 0) {
1527
+ try {
1528
+ bundleDir = await downloadAndExtractBundle();
1529
+ } catch (e) {
1530
+ if (missingHookTargets.length > 0) throw e;
1531
+ updateCheckSkipped = true;
1532
+ console.log(`Could not check for skill updates: ${e.message}`);
1533
+ }
1474
1534
  }
1535
+
1536
+ if (!updateCheckSkipped && copyTargets.length > 0 && !isUpToDate(installRoot, copyTargets, bundleDir)) {
1537
+ migrateUnprefixImpeccable(installRoot);
1538
+ updated = refreshProviderSkills(bundleDir, installRoot, copyTargets);
1539
+ const v = getSkillsVersion(installRoot);
1540
+ console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
1541
+ }
1542
+
1543
+ const writtenHookTargets = missingHookTargets.length > 0
1544
+ ? copyProviderHooks(bundleDir, hookRoot, missingHookTargets, { skillRoot: installRoot })
1545
+ : [];
1546
+ if (writtenHookTargets.length > 0) console.log(`Installed hooks into: ${writtenHookTargets.join(', ')}`);
1547
+
1548
+ if (updateCheckSkipped) {
1549
+ console.log('Existing skills were left unchanged.');
1550
+ console.log('Run with --force to reinstall.\n');
1551
+ } else if (updated === 0 && writtenHookTargets.length === 0) {
1552
+ const v = getSkillsVersion(installRoot);
1553
+ console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
1554
+ console.log('Run with --force to reinstall.\n');
1555
+ } else {
1556
+ console.log('Done!\n');
1557
+ }
1558
+ } catch (e) {
1559
+ console.error(`Install check failed: ${e.message}`);
1560
+ process.exit(1);
1561
+ } finally {
1562
+ if (bundleDir) rmSync(bundleDir, { recursive: true, force: true });
1475
1563
  }
1476
- console.log('Run with --force to reinstall.\n');
1477
1564
  process.exit(0);
1478
1565
  }
1479
1566
 
@@ -1675,25 +1762,7 @@ async function update(flags = []) {
1675
1762
  const migrated = migrateUnprefixImpeccable(root);
1676
1763
  if (migrated > 0) console.log('Migrated a prefixed install back to /impeccable (the i- prefix is no longer used).');
1677
1764
 
1678
- // Copy from the bundle to each unique provider folder.
1679
- // Deduplicate so symlinked dirs (e.g. .claude/skills -> .agents/skills)
1680
- // are only written once with the correct provider's content.
1681
- const unique = deduplicateProviders(root, copyProviders);
1682
- let updated = 0;
1683
- for (const { provider, localSkillsDir } of unique) {
1684
- const srcDir = join(tmpDir, provider, 'skills');
1685
- if (!existsSync(srcDir)) continue;
1686
-
1687
- const skills = readdirSync(srcDir, { withFileTypes: true });
1688
- for (const skill of skills) {
1689
- if (!skill.isDirectory()) continue;
1690
- const src = join(srcDir, skill.name);
1691
- const dest = join(localSkillsDir, skill.name);
1692
- if (existsSync(dest)) rmSync(dest, { recursive: true });
1693
- copyDirSync(src, dest);
1694
- updated++;
1695
- }
1696
- }
1765
+ const updated = refreshProviderSkills(tmpDir, root, copyProviders);
1697
1766
  const wantHooks = installHooks && await decideHookInstall(root, providers, { yes });
1698
1767
  const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, providers, { force }) : [];
1699
1768
 
@@ -22,6 +22,10 @@ import {
22
22
  // Output formatting
23
23
  // ---------------------------------------------------------------------------
24
24
 
25
+ function formatFindingSummary(count) {
26
+ return `${count} anti-pattern${count === 1 ? '' : 's'} found.`;
27
+ }
28
+
25
29
  function formatFindings(findings, jsonMode) {
26
30
  if (jsonMode) return JSON.stringify(findings, null, 2);
27
31
 
@@ -39,7 +43,7 @@ function formatFindings(findings, jsonMode) {
39
43
  out.push(` → ${item.description}`);
40
44
  }
41
45
  }
42
- out.push(`\n${findings.length} anti-pattern${findings.length === 1 ? '' : 's'} found.`);
46
+ out.push(`\n${formatFindingSummary(findings.length)}`);
43
47
  return out.join('\n');
44
48
  }
45
49
 
@@ -86,9 +90,12 @@ Scan files or URLs for UI anti-patterns and design quality issues.
86
90
 
87
91
  Options:
88
92
  --json Output results as JSON
93
+ --quiet In text mode, only print the final findings count
89
94
  --gpt Also report GPT-specific provider tells (off by default)
90
95
  --gemini Also report Gemini-specific provider tells (off by default)
91
- --no-config Do not apply project config, detector ignores, or DESIGN.md
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
92
99
  --no-design-system Do not load local DESIGN.md / .impeccable/design.json context
93
100
  --help Show this help message
94
101
 
@@ -97,6 +104,14 @@ Project config:
97
104
  settings: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues,
98
105
  and detector.designSystem.enabled.
99
106
 
107
+ Inline 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
+
100
115
  Detection modes:
101
116
  HTML files Static HTML/CSS analysis (default, catches linked CSS)
102
117
  Non-HTML files Regex pattern matching (CSS, JSX, TSX, etc.)
@@ -118,6 +133,7 @@ async function detectCli() {
118
133
  });
119
134
  if (args[0] === 'detect') args = args.slice(1);
120
135
  const jsonMode = args.includes('--json');
136
+ const quietMode = args.includes('--quiet');
121
137
  const helpMode = args.includes('--help');
122
138
  // --fast (regex-only) is deprecated: since the jsdom removal, the static
123
139
  // HTML/CSS analysis is fast and covers every rule, so the regex-only path
@@ -137,7 +153,12 @@ async function detectCli() {
137
153
  if (args.includes('--gemini')) providers.push('gemini');
138
154
  const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
139
155
  const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
140
- const scanOptions = designSystem ? { providers, designSystem } : { providers };
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;
141
162
  const targets = args.filter(a => !a.startsWith('--'));
142
163
 
143
164
  if (helpMode) { printUsage(); process.exit(0); }
@@ -169,8 +190,8 @@ async function detectCli() {
169
190
  catch { process.stderr.write(`Warning: cannot access ${target}\n`); continue; }
170
191
 
171
192
  if (stat.isDirectory()) {
172
- // Check for framework dev server config (skip in JSON mode to avoid polluting output)
173
- if (!jsonMode) {
193
+ // Check for framework dev server config (skip in JSON/quiet modes to avoid polluting output)
194
+ if (!jsonMode && !quietMode) {
174
195
  const fwConfig = detectFrameworkConfig(resolved);
175
196
  if (fwConfig) {
176
197
  const probe = await isPortListening(fwConfig.port, fwConfig.fingerprint);
@@ -200,7 +221,7 @@ async function detectCli() {
200
221
  const htmlCount = files.filter(f => HTML_EXTENSIONS.has(path.extname(f).toLowerCase())).length;
201
222
 
202
223
  // Warn and confirm if scanning many files (static HTML/CSS processes each HTML file)
203
- if (files.length > 50 && process.stdin.isTTY && !jsonMode) {
224
+ if (files.length > 50 && process.stdin.isTTY && !jsonMode && !quietMode) {
204
225
  process.stderr.write(
205
226
  `\nFound ${files.length} files (${htmlCount} HTML) in ${target}.\n` +
206
227
  `Scanning may take a while${htmlCount > 10 ? ' (static HTML/CSS processes each HTML file individually)' : ''}.\n` +
@@ -258,6 +279,7 @@ async function detectCli() {
258
279
 
259
280
  if (allFindings.length > 0) {
260
281
  if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
282
+ else if (quietMode) process.stderr.write(formatFindingSummary(allFindings.length) + '\n');
261
283
  else process.stderr.write(formatFindings(allFindings, false) + '\n');
262
284
  process.exit(2);
263
285
  }
@@ -1,6 +1,8 @@
1
1
  import { GENERIC_FONTS } from '../../shared/constants.mjs';
2
+ import { isNeutralColor } from '../../shared/color.mjs';
2
3
  import { checkSourceDesignSystem } from '../../design-system.mjs';
3
4
  import { isFullPage } from '../../shared/page.mjs';
5
+ import { applyInlineIgnores } from '../../shared/inline-ignores.mjs';
4
6
  import { finding } from '../../findings.mjs';
5
7
  import { filterByProviders } from '../../registry/antipatterns.mjs';
6
8
  import { profileFindings, profileStep } from '../../profile/profiler.mjs';
@@ -37,10 +39,11 @@ function shouldRunPageAnalyzers(content, filePath) {
37
39
  }
38
40
 
39
41
  function isNeutralBorderColor(str) {
40
- const m = str.match(/solid\s+(#[0-9a-f]{3,8}|rgba?\([^)]+\)|\w+)/i);
42
+ const m = str.match(/solid\s+((?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color)\([^)]*\)|#[0-9a-f]{3,8}\b|[a-z]+)/i);
41
43
  if (!m) return false;
42
44
  const c = m[1].toLowerCase();
43
45
  if (['gray', 'grey', 'silver', 'white', 'black', 'transparent', 'currentcolor'].includes(c)) return true;
46
+ if (/^(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(/i.test(c)) return isNeutralColor(c);
44
47
  const hex = c.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/);
45
48
  if (hex) {
46
49
  const [r, g, b] = [parseInt(hex[1], 16), parseInt(hex[2], 16), parseInt(hex[3], 16)];
@@ -57,10 +60,10 @@ function isNeutralBorderColor(str) {
57
60
  const REGEX_MATCHERS = [
58
61
  // --- Side-tab ---
59
62
  { id: 'side-tab', regex: /\bborder-[lrse]-(\d+)\b/g,
60
- test: (m, line) => { const n = +m[1]; return hasRounded(line) ? n >= 1 : n >= 4; },
63
+ test: (m, line) => { const n = +m[1]; return hasRounded(line) ? n >= 2 : n >= 4; },
61
64
  fmt: (m) => m[0] },
62
65
  { id: 'side-tab', regex: /border-(?:left|right)\s*:\s*(\d+)px\s+solid[^;]*/gi,
63
- test: (m, line) => { if (isSafeElement(line)) return false; if (isNeutralBorderColor(m[0])) return false; const n = +m[1]; return hasBorderRadius(line) ? n >= 1 : n >= 3; },
66
+ test: (m, line) => { if (isSafeElement(line)) return false; if (isNeutralBorderColor(m[0])) return false; const n = +m[1]; return hasBorderRadius(line) ? n >= 2 : n >= 3; },
64
67
  fmt: (m) => m[0].replace(/\s*;?\s*$/, '') },
65
68
  { id: 'side-tab', regex: /border-(?:left|right)-width\s*:\s*(\d+)px/gi,
66
69
  test: (m, line) => !isSafeElement(line) && +m[1] >= 3,
@@ -547,7 +550,10 @@ function detectText(content, filePath, options = {}) {
547
550
  }
548
551
  }
549
552
 
550
- return filterByProviders(deduped, options?.providers);
553
+ const byProvider = filterByProviders(deduped, options?.providers);
554
+ // Inline `impeccable-disable*` waivers travel with the file; honor them unless
555
+ // explicitly bypassed (`--no-config` / `--no-inline-ignores`).
556
+ return options?.inlineIgnores === false ? byProvider : applyInlineIgnores(byProvider, content);
551
557
  }
552
558
 
553
559
  export {
@@ -8,6 +8,7 @@ import {
8
8
  mergeDesignSystemFindings,
9
9
  } from '../../design-system.mjs';
10
10
  import { isFullPage } from '../../shared/page.mjs';
11
+ import { applyInlineIgnores } from '../../shared/inline-ignores.mjs';
11
12
  import { finding } from '../../findings.mjs';
12
13
  import { profileFindings, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
13
14
  import {
@@ -223,7 +224,11 @@ async function detectHtml(filePath, options = {}) {
223
224
  }
224
225
  }
225
226
 
226
- return filterByProviders(findings, options.providers);
227
+ const byProvider = filterByProviders(findings, options.providers);
228
+ // Static-HTML findings carry no line number, so only whole-file
229
+ // `impeccable-disable` directives apply here — exactly the standalone-document
230
+ // waiver this primitive targets. Bypassed by `--no-config` / `--no-inline-ignores`.
231
+ return options?.inlineIgnores === false ? byProvider : applyInlineIgnores(byProvider, html);
227
232
  }
228
233
 
229
234
  export { checkStaticPageTypography, STATIC_ELEMENT_RULES, detectHtml };
@@ -0,0 +1,148 @@
1
+ /**
2
+ * Inline, in-file ignore directives — eslint-disable-style waivers that live at
3
+ * the point they apply and travel with the artifact instead of (or alongside)
4
+ * an ignore in `.impeccable/config.json`.
5
+ *
6
+ * A config ignore is the right default for repo-wide policy. This complements it
7
+ * for the one case config can't cover: a waiver that belongs to a single file and
8
+ * needs to follow that file when it leaves the repo — a generated/exported
9
+ * standalone document, an emailed HTML file, a snippet scanned out of context.
10
+ *
11
+ * Comment-syntax-agnostic: the directive is a raw token matched anywhere on a
12
+ * line, so the same marker works across every comment style impeccable scans —
13
+ * `//`, `/* *\/`, `<!-- -->`, `#`, `{/* *\/}`, `{# #}`. Trailing comment closers
14
+ * are stripped before the rule list is parsed.
15
+ *
16
+ * Syntax (reason optional; eslint `--` or biome `:` separator):
17
+ *
18
+ * impeccable-disable <rule>[, <rule>...] [-- reason] whole file
19
+ * impeccable-disable-line <rule>... [-- reason] the same line
20
+ * impeccable-disable-next-line <rule>... [-- reason] the following line
21
+ * impeccable-disable bare / `*` = every rule
22
+ *
23
+ * Examples:
24
+ *
25
+ * <!-- impeccable-disable overused-font -- exported brand doc, font is first-party -->
26
+ * .brand { font-family: Inter; } /* impeccable-disable-line overused-font *\/
27
+ * // impeccable-disable-next-line bounce-easing: intentional playful affordance
28
+ *
29
+ * Behavior is suppression, for parity with config ignores: a matched directive
30
+ * drops the finding. The inline reason is self-documenting in the diff; it is not
31
+ * required and is discarded at scan time (only used here to keep reason words out
32
+ * of the parsed rule list).
33
+ */
34
+
35
+ const DIRECTIVE_RE = /impeccable-(disable-next-line|disable-line|disable)\b[ \t]*([^\n\r]*)/gi;
36
+
37
+ // Trailing comment closers, so `*/`, `*/}`, `-->`, `*}`, `#}`, `%>`, `}}` don't
38
+ // leak into the rule list. Anchored to end-of-line; the leading `\s*` mops up the
39
+ // space before the closer. `--+>` covers `-->` and any longer dash run.
40
+ const TRAILING_CLOSER_RE = /\s*(?:\*\/\}?|--+>|\*\}|#\}|%>|\}\})\s*$/;
41
+
42
+ function normalizeRule(token) {
43
+ return String(token || '').trim().toLowerCase();
44
+ }
45
+
46
+ // Split the directive remainder into rule tokens, dropping any human reason that
47
+ // follows an eslint-style `--` or biome-style `:` separator. Rule ids only ever
48
+ // contain single hyphens (`overused-font`, `bounce-easing`), so `--` and `:`
49
+ // are unambiguous separators.
50
+ function parseRuleList(remainder) {
51
+ let text = String(remainder || '').replace(TRAILING_CLOSER_RE, '').trim();
52
+ // Cut off a human reason at the first `--` (eslint) or `:` (biome) separator.
53
+ const reasonSep = text.match(/\s*(?:--+|:)\s*/);
54
+ if (reasonSep) text = text.slice(0, reasonSep.index);
55
+ const tokens = text.split(/[\s,]+/).map(normalizeRule).filter(Boolean);
56
+ if (tokens.length === 0 || tokens.includes('*')) return ['*'];
57
+ return tokens;
58
+ }
59
+
60
+ function addRules(set, rules) {
61
+ for (const rule of rules) set.add(rule);
62
+ }
63
+
64
+ function getSet(map, key) {
65
+ let set = map.get(key);
66
+ if (!set) {
67
+ set = new Set();
68
+ map.set(key, set);
69
+ }
70
+ return set;
71
+ }
72
+
73
+ /**
74
+ * Parse every inline ignore directive in a file's raw text.
75
+ *
76
+ * Returns sets keyed by the 1-based line the directive *targets* so matching is a
77
+ * direct lookup:
78
+ * - file: rules disabled for the whole file
79
+ * - line: line -> rules disabled on that exact line (disable-line)
80
+ * - nextLine: line -> rules disabled on that line (disable-next-line on line-1)
81
+ *
82
+ * `*` in any set means "every rule".
83
+ */
84
+ function parseInlineIgnores(content) {
85
+ const result = { file: new Set(), line: new Map(), nextLine: new Map() };
86
+ const text = typeof content === 'string' ? content : '';
87
+ // Cheap bail-out: the substring must be present for any directive to exist.
88
+ // Case-insensitive to match DIRECTIVE_RE's `i` flag (e.g. `Impeccable-Disable`).
89
+ if (!/impeccable-disable/i.test(text)) return result;
90
+
91
+ // Split on `\n` only, exactly as detectText numbers lines, so directive line
92
+ // keys line up with finding `line` values (incl. on `\r`-only line endings).
93
+ // The directive regex excludes `\r`, so a trailing `\r` on `\r\n` files is
94
+ // never captured into the rule list.
95
+ const lines = text.split('\n');
96
+ for (let i = 0; i < lines.length; i++) {
97
+ DIRECTIVE_RE.lastIndex = 0;
98
+ let m;
99
+ while ((m = DIRECTIVE_RE.exec(lines[i])) !== null) {
100
+ const variant = m[1].toLowerCase();
101
+ const rules = parseRuleList(m[2]);
102
+ if (variant === 'disable') {
103
+ addRules(result.file, rules);
104
+ } else if (variant === 'disable-line') {
105
+ addRules(getSet(result.line, i + 1), rules);
106
+ } else {
107
+ // disable-next-line on line i+1 targets line i+2.
108
+ addRules(getSet(result.nextLine, i + 2), rules);
109
+ }
110
+ }
111
+ }
112
+ return result;
113
+ }
114
+
115
+ function setMatches(set, rule) {
116
+ return Boolean(set) && (set.has('*') || set.has(rule));
117
+ }
118
+
119
+ function isInlineIgnored(finding, directives) {
120
+ const rule = normalizeRule(finding && finding.antipattern);
121
+ if (!rule) return false;
122
+ if (setMatches(directives.file, rule)) return true;
123
+ const line = Number(finding && finding.line) || 0;
124
+ if (line > 0) {
125
+ if (setMatches(directives.line.get(line), rule)) return true;
126
+ if (setMatches(directives.nextLine.get(line), rule)) return true;
127
+ }
128
+ return false;
129
+ }
130
+
131
+ function hasDirectives(directives) {
132
+ return directives.file.size > 0 || directives.line.size > 0 || directives.nextLine.size > 0;
133
+ }
134
+
135
+ /**
136
+ * Drop findings waived by an inline directive in the same file's source text.
137
+ * Findings without a usable line number (e.g. static-HTML page-level findings)
138
+ * are only matched by whole-file directives — which is the standalone-document
139
+ * case this primitive exists for.
140
+ */
141
+ function applyInlineIgnores(findings, content) {
142
+ if (!Array.isArray(findings) || findings.length === 0) return findings;
143
+ const directives = parseInlineIgnores(content);
144
+ if (!hasDirectives(directives)) return findings;
145
+ return findings.filter((finding) => !isInlineIgnored(finding, directives));
146
+ }
147
+
148
+ export { parseInlineIgnores, applyInlineIgnores, isInlineIgnored };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "impeccable",
3
- "version": "3.0.2",
3
+ "version": "3.1.0",
4
4
  "author": "Paul Bakaus",
5
5
  "description": "Design skills, commands, and anti-pattern detection for AI coding agents",
6
6
  "keywords": [
@@ -93,7 +93,7 @@
93
93
  "@ai-sdk/google": "^3.0.75",
94
94
  "@ai-sdk/openai": "^3.0.53",
95
95
  "@anthropic-ai/claude-agent-sdk": "^0.3.165",
96
- "@anthropic-ai/sdk": "^0.102.0",
96
+ "@anthropic-ai/sdk": "^0.104.2",
97
97
  "@google/genai": "^2.8.0",
98
98
  "@paper-design/shaders": "^0.0.76",
99
99
  "ai": "^6.0.168",