impeccable 3.2.0 → 3.2.1

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
@@ -1,6 +1,6 @@
1
1
  # Impeccable CLI
2
2
 
3
- Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 45 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 46 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
56
56
 
57
57
  **Quality**: tiny body text, cramped padding, long line lengths, small touch targets
58
58
 
59
- 45 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 46 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
60
60
 
61
61
  ## Exit Codes
62
62
 
@@ -75,7 +75,7 @@ impeccable detect [options] [file-or-dir-or-url...]
75
75
 
76
76
  ## Requirements
77
77
 
78
- - Node.js 24+
78
+ - Node.js 22.12+
79
79
  - `jsdom` (included as dependency, used for HTML scanning)
80
80
  - `puppeteer` (optional, only needed for URL scanning)
81
81
 
package/README.npm.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable CLI
2
2
 
3
- Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 45 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 46 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
56
56
 
57
57
  **Quality**: tiny body text, cramped padding, long line lengths, small touch targets
58
58
 
59
- 45 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 46 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
60
60
 
61
61
  ## Exit Codes
62
62
 
@@ -75,7 +75,7 @@ impeccable detect [options] [file-or-dir-or-url...]
75
75
 
76
76
  ## Requirements
77
77
 
78
- - Node.js 24+
78
+ - Node.js 22.12+
79
79
  - `jsdom` (included as dependency, used for HTML scanning)
80
80
  - `puppeteer` (optional, only needed for URL scanning)
81
81
 
package/README.repo.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable
2
2
 
3
- Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 45 deterministic detector rules for AI-generated frontend design.
3
+ Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 46 deterministic detector rules for AI-generated frontend design.
4
4
 
5
5
  > **Quick start:** From your project root, run `npx impeccable install`, then run `/impeccable init` inside your AI coding tool. Full docs: [impeccable.style](https://impeccable.style).
6
6
 
@@ -13,7 +13,7 @@ Every model trained on the same SaaS templates. Skip the guidance and you get th
13
13
  Impeccable adds:
14
14
  - **One setup flow.** `/impeccable init` writes `PRODUCT.md` and offers `DESIGN.md`, so later commands know the audience, brand/product lane, voice, anti-references, colors, type, and components.
15
15
  - **23 commands.** A shared design vocabulary with your AI: `polish`, `audit`, `critique`, `distill`, `animate`, `bolder`, `quieter`, and more.
16
- - **45 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
16
+ - **46 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
17
17
 
18
18
  ## What's Included
19
19
 
@@ -91,7 +91,7 @@ The skill includes explicit guidance on what to avoid:
91
91
 
92
92
  ## See It In Action
93
93
 
94
- Visit [impeccable.style](https://impeccable.style#casestudies) to see before/after case studies of real projects transformed with Impeccable commands.
94
+ Visit [the Neo Mirai case study](https://impeccable.style/cases/neo-mirai) to see a before/after case study of a real project transformed with Impeccable commands.
95
95
 
96
96
  ## Installation
97
97
 
@@ -103,7 +103,7 @@ From the root of your project, run:
103
103
  npx impeccable install
104
104
  ```
105
105
 
106
- This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, and Codex, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, and every other supported tool. Reload your harness afterward.
106
+ This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, and Codex, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, and every other supported tool. Reload your harness afterward.
107
107
 
108
108
  To refresh an existing install, run:
109
109
 
@@ -133,11 +133,27 @@ git submodule update --remote .impeccable
133
133
  npx impeccable link --source=.impeccable --providers=claude,cursor
134
134
  ```
135
135
 
136
- ### Option 3: Download from Website
136
+ ### Option 3: Plugin install
137
+
138
+ **Claude Code:**
139
+ ```bash
140
+ /plugin marketplace add pbakaus/impeccable
141
+ ```
142
+
143
+ > Claude Code only. After adding the marketplace, open `/plugin` and install Impeccable from the list.
144
+
145
+ **Grok Build:**
146
+ ```bash
147
+ grok plugin install pbakaus/impeccable --trust
148
+ ```
149
+
150
+ > Grok Build only. Then run `/impeccable init` in a Grok session.
151
+
152
+ ### Option 4: Download from Website
137
153
 
138
154
  Visit [impeccable.style](https://impeccable.style), download the ZIP for your tool, and extract to your project.
139
155
 
140
- ### Option 4: Copy from Repository
156
+ ### Option 5: Copy from Repository
141
157
 
142
158
  **Cursor:**
143
159
  ```bash
@@ -341,7 +357,7 @@ npx impeccable ignores add-file "src/legacy/**"
341
357
  npx impeccable ignores add-value overused-font Inter --reason "Brand font"
342
358
  ```
343
359
 
344
- The detector catches 45 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).
360
+ The detector catches 46 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).
345
361
 
346
362
  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.
347
363
 
@@ -356,6 +372,7 @@ Full detector docs: [impeccable.style/docs/detector](https://impeccable.style/do
356
372
  - [GitHub Copilot](https://github.com/features/copilot)
357
373
  - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
358
374
  - [Codex CLI](https://github.com/openai/codex)
375
+ - [Grok Build](https://x.ai/cli)
359
376
  - [OpenCode](https://opencode.ai)
360
377
  - [Pi](https://pi.dev)
361
378
  - [Kiro](https://kiro.dev)
@@ -59,6 +59,13 @@ const PROVIDER_DISPLAY = {
59
59
  };
60
60
  const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev'];
61
61
 
62
+ // Providers whose GLOBAL (home) skills dir is not `<provider>/skills`.
63
+ // Pi discovers global skills from ~/.pi/agent/skills/; project scope
64
+ // stays .pi/skills/. See issue #327.
65
+ const HOME_SKILLS_DIR_OVERRIDES = {
66
+ '.pi': join('.pi', 'agent', 'skills'),
67
+ };
68
+
62
69
  // When a project has no harness folder yet, infer the target from globally
63
70
  // installed harnesses (~/.claude, ~/.codex, ...). Codex reads skills from
64
71
  // .agents/skills, so ~/.codex maps to the .agents bundle variant.
@@ -69,6 +76,7 @@ const GLOBAL_HARNESS_HINTS = [
69
76
  { home: '.gemini', provider: '.gemini' },
70
77
  { home: '.kiro', provider: '.kiro' },
71
78
  { home: '.opencode', provider: '.opencode' },
79
+ { home: '.pi', provider: '.pi' },
72
80
  { home: '.qoder', provider: '.qoder' },
73
81
  { home: '.rovodev', provider: '.rovodev' },
74
82
  ];
@@ -111,6 +119,45 @@ const PROVIDER_HOOK_ARTIFACTS = {
111
119
  ],
112
120
  };
113
121
 
122
+ function userProviderSkillsDir(home, provider) {
123
+ if (HOME_SKILLS_DIR_OVERRIDES[provider]) return join(home, HOME_SKILLS_DIR_OVERRIDES[provider]);
124
+ return join(home, provider, 'skills');
125
+ }
126
+
127
+ // Compare via realpath: the project root comes from process.cwd() (symlinks
128
+ // resolved) while homedir() reflects $HOME verbatim, so a home dir reached
129
+ // through a symlink (e.g. /tmp -> /private/tmp) would fail a string compare.
130
+ function isHomeDir(root) {
131
+ if (root === homedir()) return true;
132
+ try {
133
+ return realpathSync(root) === realpathSync(homedir());
134
+ } catch {
135
+ return false;
136
+ }
137
+ }
138
+
139
+ // Every layout a provider's installed skills can live in under `root`.
140
+ // `scope` narrows the answer when the caller knows which install it is
141
+ // acting on: 'user' means the provider's global layout, 'project' means
142
+ // `<provider>/skills`. Without a scope (update/check, where installs of
143
+ // either kind may live under `root`) both layouts are candidates when
144
+ // `root` is the home dir, since an overridden provider (Pi) keeps its
145
+ // global skills elsewhere while a repo rooted at ~ still uses the project
146
+ // layout. Scoping matters for the same reason: a project-scope install in
147
+ // a home-rooted repo must not be conflated with an existing global one.
148
+ function providerSkillsDirCandidates(root, provider, scope) {
149
+ if (scope === 'user') return [userProviderSkillsDir(root, provider)];
150
+ const dirs = [join(root, provider, 'skills')];
151
+ if (scope !== 'project' && HOME_SKILLS_DIR_OVERRIDES[provider] && isHomeDir(root)) {
152
+ dirs.unshift(userProviderSkillsDir(root, provider));
153
+ }
154
+ return dirs;
155
+ }
156
+
157
+ function existingSkillsDirs(root, provider, scope) {
158
+ return providerSkillsDirCandidates(root, provider, scope).filter(existsSync);
159
+ }
160
+
114
161
  let pipedAnswers = null;
115
162
  class PromptAbortError extends Error {
116
163
  constructor() {
@@ -415,13 +462,15 @@ async function showHelp() {
415
462
  /**
416
463
  * Read the skills version from the impeccable SKILL.md frontmatter.
417
464
  */
418
- function getSkillsVersion(root) {
465
+ function getSkillsVersion(root, scope) {
419
466
  for (const d of PROVIDER_DIRS) {
420
- const skillMd = join(root, d, 'skills', 'impeccable', 'SKILL.md');
421
- if (!existsSync(skillMd)) continue;
422
- const content = readFileSync(skillMd, 'utf-8');
423
- const match = content.match(/^version:\s*(.+)$/m);
424
- if (match) return match[1].trim().replace(/^["']|["']$/g, '');
467
+ for (const skillsDir of providerSkillsDirCandidates(root, d, scope)) {
468
+ const skillMd = join(skillsDir, 'impeccable', 'SKILL.md');
469
+ if (!existsSync(skillMd)) continue;
470
+ const content = readFileSync(skillMd, 'utf-8');
471
+ const match = content.match(/^version:\s*(.+)$/m);
472
+ if (match) return match[1].trim().replace(/^["']|["']$/g, '');
473
+ }
425
474
  }
426
475
  return null;
427
476
  }
@@ -535,14 +584,17 @@ function hashSkillFile(filePath) {
535
584
  * per unique real path. The first provider that maps to a real path
536
585
  * wins (so the bundle uses that provider's build).
537
586
  */
538
- function deduplicateProviders(root, providers) {
587
+ function deduplicateProviders(root, providers, scope) {
539
588
  const seen = new Map(); // realPath -> { provider, localSkillsDir }
540
589
  for (const provider of providers) {
541
- const skillsDir = join(root, provider, 'skills');
542
- if (!existsSync(skillsDir)) continue;
543
- const real = realpathSync(skillsDir);
544
- if (!seen.has(real)) {
545
- seen.set(real, { provider, localSkillsDir: skillsDir });
590
+ // A provider can hold real installs in more than one layout (a home-rooted
591
+ // repo may carry both ~/.pi/agent/skills and ~/.pi/skills). Keep each as
592
+ // its own entry so update/check touch every tree, not just the first.
593
+ for (const skillsDir of existingSkillsDirs(root, provider, scope)) {
594
+ const real = realpathSync(skillsDir);
595
+ if (!seen.has(real)) {
596
+ seen.set(real, { provider, localSkillsDir: skillsDir });
597
+ }
546
598
  }
547
599
  }
548
600
  return [...seen.values()];
@@ -556,8 +608,8 @@ function deduplicateProviders(root, providers) {
556
608
  * SKILL.md, so script-only fixes and removed files are detected.
557
609
  * Returns true if every bundle skill matches the local copy.
558
610
  */
559
- function isUpToDate(root, providers, bundleDir) {
560
- const unique = deduplicateProviders(root, providers);
611
+ function isUpToDate(root, providers, bundleDir, scope) {
612
+ const unique = deduplicateProviders(root, providers, scope);
561
613
  if (unique.length === 0) return false;
562
614
 
563
615
  for (const { provider, localSkillsDir } of unique) {
@@ -621,20 +673,20 @@ async function check() {
621
673
  // ─── skills install ───────────────────────────────────────────────────────────
622
674
 
623
675
  // Check if impeccable skills are already present in any provider folder
624
- function isAlreadyInstalled(root) {
676
+ function isAlreadyInstalled(root, scope) {
625
677
  for (const d of PROVIDER_DIRS) {
626
- const skillsDir = join(root, d, 'skills');
627
- if (!existsSync(skillsDir)) continue;
628
- try {
629
- const entries = readdirSync(skillsDir);
630
- // Look for 'impeccable' skill (or prefixed variant, or legacy 'teach-impeccable')
631
- if (entries.some(e =>
632
- e === 'impeccable' || e.endsWith('-impeccable') ||
633
- e === 'teach-impeccable' || e.endsWith('-teach-impeccable')
634
- )) {
635
- return d;
636
- }
637
- } catch {}
678
+ for (const skillsDir of existingSkillsDirs(root, d, scope)) {
679
+ try {
680
+ const entries = readdirSync(skillsDir);
681
+ // Look for 'impeccable' skill (or prefixed variant, or legacy 'teach-impeccable')
682
+ if (entries.some(e =>
683
+ e === 'impeccable' || e.endsWith('-impeccable') ||
684
+ e === 'teach-impeccable' || e.endsWith('-teach-impeccable')
685
+ )) {
686
+ return d;
687
+ }
688
+ } catch {}
689
+ }
638
690
  }
639
691
  return null;
640
692
  }
@@ -678,26 +730,26 @@ function isRealSkillDir(skillsDir, name) {
678
730
  * by name -- never touches third-party skills that happen to start with `i-`.
679
731
  * Returns the number of skills migrated.
680
732
  */
681
- function migrateUnprefixImpeccable(root) {
733
+ function migrateUnprefixImpeccable(root, scope) {
682
734
  let migrated = 0;
683
735
  for (const d of PROVIDER_DIRS) {
684
- const skillsDir = join(root, d, 'skills');
685
- if (!existsSync(skillsDir)) continue;
686
- let entries;
687
- try { entries = readdirSync(skillsDir); } catch { continue; }
688
- for (const name of entries) {
689
- // A prefixed impeccable skill is `<prefix>impeccable`, not the canonical
690
- // `impeccable` and not an unrelated legacy skill name.
691
- if (name === 'impeccable' || name === 'teach-impeccable') continue;
692
- if (!name.endsWith('-impeccable')) continue;
693
- if (!isRealSkillDir(skillsDir, name)) continue;
694
-
695
- const dest = join(skillsDir, 'impeccable');
696
- try {
697
- rmSync(dest, { recursive: true, force: true });
698
- renameSync(join(skillsDir, name), dest);
699
- migrated++;
700
- } catch {}
736
+ for (const skillsDir of existingSkillsDirs(root, d, scope)) {
737
+ let entries;
738
+ try { entries = readdirSync(skillsDir); } catch { continue; }
739
+ for (const name of entries) {
740
+ // A prefixed impeccable skill is `<prefix>impeccable`, not the canonical
741
+ // `impeccable` and not an unrelated legacy skill name.
742
+ if (name === 'impeccable' || name === 'teach-impeccable') continue;
743
+ if (!name.endsWith('-impeccable')) continue;
744
+ if (!isRealSkillDir(skillsDir, name)) continue;
745
+
746
+ const dest = join(skillsDir, 'impeccable');
747
+ try {
748
+ rmSync(dest, { recursive: true, force: true });
749
+ renameSync(join(skillsDir, name), dest);
750
+ migrated++;
751
+ } catch {}
752
+ }
701
753
  }
702
754
  }
703
755
  return migrated;
@@ -774,7 +826,7 @@ function uniquePaths(paths) {
774
826
 
775
827
  function userSkillProbePaths(home, harnessDir, provider) {
776
828
  return uniquePaths([
777
- join(home, provider, 'skills'),
829
+ userProviderSkillsDir(home, provider),
778
830
  join(home, harnessDir, 'skills'),
779
831
  ]);
780
832
  }
@@ -804,7 +856,7 @@ function collectInstallDetections(root, home = homedir()) {
804
856
  scope: 'user',
805
857
  foundPath,
806
858
  installRoot: home,
807
- installPath: join(home, provider, 'skills'),
859
+ installPath: userProviderSkillsDir(home, provider),
808
860
  skillProbePaths,
809
861
  hasRealSkills: skillProbePaths.some(hasRealSkillEntries),
810
862
  reason: 'user harness folder',
@@ -1044,13 +1096,17 @@ function isInProjectProviderLink(localSkillsDir, root, provider) {
1044
1096
  * Copy each target provider's compiled skill variant from an extracted bundle
1045
1097
  * into the project. Writes real directories (copy, never symlink) so every
1046
1098
  * harness keeps the build that was compiled for it. Returns skills written.
1099
+ * `scope: 'user'` writes to the provider's global skills layout (see
1100
+ * HOME_SKILLS_DIR_OVERRIDES); anything else writes `<provider>/skills`.
1047
1101
  */
1048
- function copyProviderSkills(bundleDir, root, targets) {
1102
+ function copyProviderSkills(bundleDir, root, targets, { scope } = {}) {
1049
1103
  let written = 0;
1050
1104
  for (const provider of targets) {
1051
1105
  const srcDir = join(bundleDir, provider, 'skills');
1052
1106
  if (existsSync(srcDir)) {
1053
- const localSkillsDir = join(root, provider, 'skills');
1107
+ const localSkillsDir = scope === 'user'
1108
+ ? userProviderSkillsDir(root, provider)
1109
+ : join(root, provider, 'skills');
1054
1110
  // A previous `npx skills` install may have left this provider's skills dir
1055
1111
  // as a symlink to ANOTHER in-project provider's canonical copy. Drop only
1056
1112
  // that link so we write a real, provider-specific directory. A user's
@@ -1072,8 +1128,8 @@ function copyProviderSkills(bundleDir, root, targets) {
1072
1128
  return written;
1073
1129
  }
1074
1130
 
1075
- function refreshProviderSkills(bundleDir, root, providers) {
1076
- const unique = deduplicateProviders(root, providers);
1131
+ function refreshProviderSkills(bundleDir, root, providers, scope) {
1132
+ const unique = deduplicateProviders(root, providers, scope);
1077
1133
  let updated = 0;
1078
1134
  for (const { provider, localSkillsDir } of unique) {
1079
1135
  const srcDir = join(bundleDir, provider, 'skills');
@@ -1532,13 +1588,13 @@ async function install(flags) {
1532
1588
  }
1533
1589
 
1534
1590
  const { targets, installRoot, hookRoot, scope } = plan;
1535
- const existing = isAlreadyInstalled(installRoot);
1591
+ const existing = isAlreadyInstalled(installRoot, scope);
1536
1592
 
1537
1593
  if (existing && !force) {
1538
1594
  console.log(`Impeccable skills are already installed (found in ${existing}/).`);
1539
- const installedTargets = findInstalledProviders(installRoot);
1595
+ const installedTargets = findInstalledProviders(installRoot, scope);
1540
1596
  const selectedInstalledTargets = targets.filter(provider => installedTargets.includes(provider));
1541
- const linkedTargets = findLinkedProviders(installRoot, selectedInstalledTargets);
1597
+ const linkedTargets = findLinkedProviders(installRoot, selectedInstalledTargets, scope);
1542
1598
  const copyTargets = selectedInstalledTargets.filter(provider => !linkedTargets.includes(provider));
1543
1599
  const hookTargets = selectedInstalledTargets;
1544
1600
  const wantHooks = installHooks && await decideHookInstall(hookRoot, hookTargets, { yes });
@@ -1565,10 +1621,10 @@ async function install(flags) {
1565
1621
  }
1566
1622
  }
1567
1623
 
1568
- if (!updateCheckSkipped && copyTargets.length > 0 && !isUpToDate(installRoot, copyTargets, bundleDir)) {
1569
- migrateUnprefixImpeccable(installRoot);
1570
- updated = refreshProviderSkills(bundleDir, installRoot, copyTargets);
1571
- const v = getSkillsVersion(installRoot);
1624
+ if (!updateCheckSkipped && copyTargets.length > 0 && !isUpToDate(installRoot, copyTargets, bundleDir, scope)) {
1625
+ migrateUnprefixImpeccable(installRoot, scope);
1626
+ updated = refreshProviderSkills(bundleDir, installRoot, copyTargets, scope);
1627
+ const v = getSkillsVersion(installRoot, scope);
1572
1628
  console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
1573
1629
  }
1574
1630
 
@@ -1581,7 +1637,7 @@ async function install(flags) {
1581
1637
  console.log('Existing skills were left unchanged.');
1582
1638
  console.log('Run with --force to reinstall.\n');
1583
1639
  } else if (updated === 0 && writtenHookTargets.length === 0) {
1584
- const v = getSkillsVersion(installRoot);
1640
+ const v = getSkillsVersion(installRoot, scope);
1585
1641
  console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
1586
1642
  console.log('Run with --force to reinstall.\n');
1587
1643
  } else {
@@ -1620,12 +1676,12 @@ async function install(flags) {
1620
1676
 
1621
1677
  // Retire any old `i-`-prefixed install so the fresh copy lands on the
1622
1678
  // canonical `impeccable` dir instead of orphaning the prefixed one.
1623
- migrateUnprefixImpeccable(installRoot);
1679
+ migrateUnprefixImpeccable(installRoot, scope);
1624
1680
 
1625
1681
  let written = 0;
1626
1682
  let hookTargets = [];
1627
1683
  try {
1628
- written = copyProviderSkills(bundleDir, installRoot, targets);
1684
+ written = copyProviderSkills(bundleDir, installRoot, targets, { scope });
1629
1685
  hookTargets = wantHooks ? copyProviderHooks(bundleDir, hookRoot, targets, { force, skillRoot: installRoot }) : [];
1630
1686
  } catch (e) {
1631
1687
  rmSync(bundleDir, { recursive: true, force: true });
@@ -1655,27 +1711,31 @@ function findProjectRoot() {
1655
1711
  return process.cwd();
1656
1712
  }
1657
1713
 
1658
- function findInstalledProviders(root) {
1714
+ function findInstalledProviders(root, scope) {
1659
1715
  const found = [];
1660
1716
  for (const d of PROVIDER_DIRS) {
1661
- const skillsDir = join(root, d, 'skills');
1662
- if (!existsSync(skillsDir)) continue;
1663
- try {
1664
- const entries = readdirSync(skillsDir);
1665
- if (entries.some(name => isSkillDir(skillsDir, name))) found.push(d);
1666
- } catch {}
1717
+ for (const skillsDir of existingSkillsDirs(root, d, scope)) {
1718
+ try {
1719
+ const entries = readdirSync(skillsDir);
1720
+ if (entries.some(name => isSkillDir(skillsDir, name))) {
1721
+ found.push(d);
1722
+ break;
1723
+ }
1724
+ } catch {}
1725
+ }
1667
1726
  }
1668
1727
  return found;
1669
1728
  }
1670
1729
 
1671
- function findLinkedProviders(root, providers) {
1730
+ function findLinkedProviders(root, providers, scope) {
1672
1731
  return providers.filter(provider => {
1673
- const skillDir = join(root, provider, 'skills', 'impeccable');
1674
- try {
1675
- return lstatSync(skillDir).isSymbolicLink();
1676
- } catch {
1677
- return false;
1732
+ for (const skillsDir of providerSkillsDirCandidates(root, provider, scope)) {
1733
+ const skillDir = join(skillsDir, 'impeccable');
1734
+ try {
1735
+ if (lstatSync(skillDir).isSymbolicLink()) return true;
1736
+ } catch {}
1678
1737
  }
1738
+ return false;
1679
1739
  });
1680
1740
  }
1681
1741
 
@@ -2,6 +2,7 @@ import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
 
4
4
  import { loadDesignSystemForCwd } from '../design-system.mjs';
5
+ import { RULE_SCOPES, filterByScopes } from '../registry/antipatterns.mjs';
5
6
  import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
6
7
  import { detectHtml } from '../engines/static-html/detect-html.mjs';
7
8
  import { detectText } from '../engines/regex/detect-text.mjs';
@@ -93,6 +94,8 @@ Options:
93
94
  --quiet In text mode, only print the final findings count
94
95
  --gpt Also report GPT-specific provider tells (off by default)
95
96
  --gemini Also report Gemini-specific provider tells (off by default)
97
+ --scope <name> Only report rules in the given design domain
98
+ (type, layout). Comma-separated.
96
99
  --no-config Do not apply project config, detector ignores, inline
97
100
  ignore comments, or DESIGN.md
98
101
  --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
@@ -151,6 +154,33 @@ async function detectCli() {
151
154
  const providers = [];
152
155
  if (args.includes('--gpt')) providers.push('gpt');
153
156
  if (args.includes('--gemini')) providers.push('gemini');
157
+ const scopes = [];
158
+ for (let i = 0; i < args.length; i++) {
159
+ if (args[i] !== '--scope' && !args[i].startsWith('--scope=')) continue;
160
+ const inline = args[i].startsWith('--scope=');
161
+ const value = inline ? args[i].slice('--scope='.length) : args[i + 1];
162
+ const parsed = (value && !value.startsWith('--'))
163
+ ? value.split(',').map(s => s.trim()).filter(Boolean)
164
+ : [];
165
+ // A bare `--scope` would otherwise fall out of `targets` and scan unscoped;
166
+ // fail loudly so a mistyped pre-scan never runs the wrong rule set.
167
+ if (parsed.length === 0) {
168
+ process.stderr.write(
169
+ `Error: --scope requires a value. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
170
+ );
171
+ process.exit(1);
172
+ }
173
+ scopes.push(...parsed);
174
+ args.splice(i, inline ? 1 : 2);
175
+ i -= 1;
176
+ }
177
+ const unknownScopes = scopes.filter(s => !RULE_SCOPES.has(s));
178
+ if (unknownScopes.length > 0) {
179
+ process.stderr.write(
180
+ `Error: unknown --scope value(s): ${unknownScopes.join(', ')}. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
181
+ );
182
+ process.exit(1);
183
+ }
154
184
  const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
155
185
  const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
156
186
  // Inline `impeccable-disable*` waivers are part of the scanned file, so they
@@ -276,6 +306,7 @@ async function detectCli() {
276
306
  }
277
307
 
278
308
  allFindings = filterDetectionFindings(allFindings, detectionConfig);
309
+ allFindings = filterByScopes(allFindings, scopes);
279
310
 
280
311
  if (allFindings.length > 0) {
281
312
  if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');