impeccable 3.3.0 → 3.3.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.
@@ -1195,21 +1195,52 @@ function hookScriptPathForProvider(skillRoot, provider) {
1195
1195
  return null;
1196
1196
  }
1197
1197
 
1198
- function rewriteHookCommandsForSkillRoot(value, provider, skillRoot) {
1198
+ // Wrap a `node "PATH"` hook command so a missing skill file is a silent no-op
1199
+ // (exit 0) instead of a Node module-resolution crash. hook.mjs promises to
1200
+ // "never break a turn. Always exit 0.", but that only holds once Node can load
1201
+ // the file; a stale/missing path crashes before any of that logic runs. The
1202
+ // `[ ! -f X ] || node X` form (NOT `... || true`) preserves Node's own exit
1203
+ // code when the file exists, so Claude's exit-2 blocking signal still reaches
1204
+ // the agent. POSIX-shell form, consistent with the project's other hook
1205
+ // commands (e.g. the GitHub manifest's `$(git rev-parse ...)`).
1206
+ function guardHookCommand(quotedPath) {
1207
+ return `[ ! -f ${quotedPath} ] || node ${quotedPath}`;
1208
+ }
1209
+
1210
+ // Transform bundled hook commands for the actual install target:
1211
+ // * absolute — rewrite the (marker) command to the resolved absolute skill
1212
+ // path. Required when the manifest is a user/global file (~/.claude/
1213
+ // settings.local.json) that fires in EVERY project, so ${CLAUDE_PROJECT_DIR}
1214
+ // would resolve per-project to dirs without a skill copy (issue #399); also
1215
+ // when a project hook points at a skill installed elsewhere (--scope=global).
1216
+ // * otherwise — keep the bundle's own ${CLAUDE_PROJECT_DIR}-relative path,
1217
+ // which correctly resolves for a project-scoped install.
1218
+ // Either way the command is wrapped with the missing-file guard.
1219
+ function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute }) {
1199
1220
  const hookScript = hookScriptPathForProvider(skillRoot, provider);
1221
+ // Providers we don't own a `node "PATH"` command hook for (.github, .grok)
1222
+ // carry their own portable command forms; leave them untouched.
1200
1223
  if (!hookScript) return value;
1201
1224
 
1202
1225
  if (typeof value === 'string') {
1203
- if (valueHasImpeccableHookMarker(value)) return `node ${JSON.stringify(hookScript)}`;
1204
- return value;
1226
+ if (!valueHasImpeccableHookMarker(value)) return value;
1227
+ let quotedPath;
1228
+ if (absolute) {
1229
+ quotedPath = JSON.stringify(hookScript);
1230
+ } else {
1231
+ // Preserve the bundle's own path token (e.g. ${CLAUDE_PROJECT_DIR}/...).
1232
+ const match = value.match(/"([^"]+)"/);
1233
+ quotedPath = match ? JSON.stringify(match[1]) : JSON.stringify(hookScript);
1234
+ }
1235
+ return guardHookCommand(quotedPath);
1205
1236
  }
1206
1237
  if (Array.isArray(value)) {
1207
- return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, skillRoot));
1238
+ return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, { skillRoot, absolute }));
1208
1239
  }
1209
1240
  if (value && typeof value === 'object') {
1210
1241
  const next = {};
1211
1242
  for (const [key, child] of Object.entries(value)) {
1212
- next[key] = rewriteHookCommandsForSkillRoot(child, provider, skillRoot);
1243
+ next[key] = rewriteHookCommandsForSkillRoot(child, provider, { skillRoot, absolute });
1213
1244
  }
1214
1245
  return next;
1215
1246
  }
@@ -1391,9 +1422,14 @@ function copyProviderHooks(bundleDir, root, providers, { force = false, skillRoo
1391
1422
  }
1392
1423
 
1393
1424
  const freshManifest = readJsonFile(src, 'Bundled hook manifest');
1394
- const fresh = skillRoot === root
1395
- ? freshManifest
1396
- : rewriteHookCommandsForSkillRoot(freshManifest, provider, skillRoot);
1425
+ // Rewrite to an absolute skill path when the skill lives elsewhere than
1426
+ // this manifest's root (--scope=global project hook) OR when the manifest
1427
+ // itself is a user/global file. A global settings file fires in every
1428
+ // project, so ${CLAUDE_PROJECT_DIR} there crashes Node wherever no local
1429
+ // skill copy exists (issue #399); the resolved absolute path is correct
1430
+ // for the one global skill it targets.
1431
+ const absolute = skillRoot !== root || isHomeDir(root);
1432
+ const fresh = rewriteHookCommandsForSkillRoot(freshManifest, provider, { skillRoot, absolute });
1397
1433
  let next = fresh;
1398
1434
 
1399
1435
  if (existsSync(dest)) {
@@ -1741,6 +1777,67 @@ function findInstalledProviders(root, scope) {
1741
1777
  return found;
1742
1778
  }
1743
1779
 
1780
+ // Like findInstalledProviders, but only counts a provider whose skills dir
1781
+ // actually holds the IMPECCABLE skill (canonical, prefixed, or legacy teach-).
1782
+ // `update` uses this so it never mistakes a repo that vendors OTHER first-party
1783
+ // skills under .claude/skills for an impeccable install and drops a copy in
1784
+ // (issue #399, part 2).
1785
+ function findImpeccableProviders(root, scope) {
1786
+ const found = [];
1787
+ for (const d of PROVIDER_DIRS) {
1788
+ for (const skillsDir of existingSkillsDirs(root, d, scope)) {
1789
+ let entries;
1790
+ try { entries = readdirSync(skillsDir); } catch { continue; }
1791
+ if (entries.some(e =>
1792
+ e === 'impeccable' || e.endsWith('-impeccable') ||
1793
+ e === 'teach-impeccable' || e.endsWith('-teach-impeccable')
1794
+ )) {
1795
+ found.push(d);
1796
+ break;
1797
+ }
1798
+ }
1799
+ }
1800
+ return found;
1801
+ }
1802
+
1803
+ // Resolve which install `skills update` should refresh: project-level (the CWD's
1804
+ // git root) or user-level (~/.claude etc.). Returns a plain descriptor; the
1805
+ // caller handles the interactive both-exist prompt via `ambiguous`.
1806
+ function resolveUpdateTarget({ projectRoot, home, explicitScope }) {
1807
+ // A home-rooted repo (a dotfiles checkout at $HOME) overlaps project and user
1808
+ // installs under one root; keep the historical unscoped scan so overlapping
1809
+ // layouts (e.g. Pi's ~/.pi/skills and ~/.pi/agent/skills) both refresh.
1810
+ const homeRooted = isHomeDir(projectRoot);
1811
+ if (homeRooted && !explicitScope) {
1812
+ const providers = findInstalledProviders(home);
1813
+ return providers.length ? { root: home, scope: undefined, providers, scopeLabel: 'user level' } : null;
1814
+ }
1815
+
1816
+ const projectProviders = homeRooted ? [] : findImpeccableProviders(projectRoot, 'project');
1817
+ const userProviders = findImpeccableProviders(home, 'user');
1818
+
1819
+ if (explicitScope === 'user') {
1820
+ return userProviders.length
1821
+ ? { root: home, scope: 'user', providers: userProviders, scopeLabel: 'user level' }
1822
+ : null;
1823
+ }
1824
+ if (explicitScope === 'project') {
1825
+ return projectProviders.length
1826
+ ? { root: projectRoot, scope: 'project', providers: projectProviders, scopeLabel: 'this project' }
1827
+ : null;
1828
+ }
1829
+ if (projectProviders.length && userProviders.length) {
1830
+ return { ambiguous: true, projectRoot, home, projectProviders, userProviders };
1831
+ }
1832
+ if (projectProviders.length) {
1833
+ return { root: projectRoot, scope: 'project', providers: projectProviders, scopeLabel: 'this project' };
1834
+ }
1835
+ if (userProviders.length) {
1836
+ return { root: home, scope: 'user', providers: userProviders, scopeLabel: 'user level' };
1837
+ }
1838
+ return null;
1839
+ }
1840
+
1744
1841
  function findLinkedProviders(root, providers, scope) {
1745
1842
  return providers.filter(provider => {
1746
1843
  for (const skillsDir of providerSkillsDirCandidates(root, provider, scope)) {
@@ -1800,21 +1897,56 @@ async function update(flags = []) {
1800
1897
  const yes = flags.includes('-y') || flags.includes('--yes');
1801
1898
  const force = flags.includes('--force');
1802
1899
  const installHooks = !flags.includes('--no-hooks');
1900
+ const scopeValue = getInstallScopeValue(flags);
1901
+ const explicitScope = normalizeInstallScope(scopeValue);
1902
+ if (scopeValue && !explicitScope) {
1903
+ console.error(`Unknown update scope: ${scopeValue}. Use --project or --user.`);
1904
+ process.exit(1);
1905
+ }
1803
1906
 
1804
1907
  // Download the latest skills directly from impeccable.style.
1805
1908
  // We skip `npx skills update` because it has a known upstream bug
1806
1909
  // (vercel-labs/skills#775) where it can't find the lock file.
1807
- const root = findProjectRoot();
1808
- const providers = findInstalledProviders(root);
1809
- const linkedProviders = findLinkedProviders(root, providers);
1810
- const copyProviders = providers.filter(provider => !linkedProviders.includes(provider));
1910
+ const projectRoot = findProjectRoot();
1911
+ const home = homedir();
1811
1912
 
1812
- if (providers.length === 0) {
1813
- console.log('No impeccable skill folders found in this project.');
1913
+ let target = resolveUpdateTarget({ projectRoot, home, explicitScope });
1914
+ if (!target) {
1915
+ if (explicitScope) {
1916
+ const where = explicitScope === 'user' ? `user level (${formatPathForDisplay(home)})` : `this project (${projectRoot})`;
1917
+ console.log(`No impeccable skill folders found at the ${where}.`);
1918
+ } else {
1919
+ console.log('No impeccable skill folders found in this project or at the user level.');
1920
+ }
1814
1921
  console.log('Run `npx impeccable install` to install first.');
1815
1922
  process.exit(1);
1816
1923
  }
1817
1924
 
1925
+ // Both a project and a user-level install exist and no scope was given. Never
1926
+ // silently pick (issue #399, part 2): prompt when interactive, else default to
1927
+ // the project and say how to target the other.
1928
+ if (target.ambiguous) {
1929
+ console.log('Impeccable is installed both here and at the user level:');
1930
+ console.log(` project ${projectRoot} (${target.projectProviders.join(', ')})`);
1931
+ console.log(` user level ${formatPathForDisplay(home)} (${target.userProviders.join(', ')})`);
1932
+ let pickUser = false;
1933
+ if (!yes && process.stdin.isTTY) {
1934
+ const ans = await ask('Update which? [project]/user: ');
1935
+ pickUser = ['user', 'u', 'global', 'home'].includes(ans);
1936
+ } else {
1937
+ console.log('Defaulting to the project. Re-run with --user to update the user-level install instead.');
1938
+ }
1939
+ target = pickUser
1940
+ ? { root: home, scope: 'user', providers: target.userProviders, scopeLabel: 'user level' }
1941
+ : { root: projectRoot, scope: 'project', providers: target.projectProviders, scopeLabel: 'this project' };
1942
+ }
1943
+
1944
+ const { root, scope } = target;
1945
+ console.log(`Updating the ${target.scopeLabel} install: ${formatPathForDisplay(root)} (${target.providers.join(', ')})`);
1946
+ const providers = target.providers;
1947
+ const linkedProviders = findLinkedProviders(root, providers, scope);
1948
+ const copyProviders = providers.filter(provider => !linkedProviders.includes(provider));
1949
+
1818
1950
  if (linkedProviders.length > 0) {
1819
1951
  console.log(`Linked skills found in: ${linkedProviders.join(', ')}`);
1820
1952
  console.log('Update the source checkout with `git submodule update --remote`, then rerun `npx impeccable link --source=.impeccable` if new skills are added.');
@@ -1833,12 +1965,12 @@ async function update(flags = []) {
1833
1965
  }
1834
1966
 
1835
1967
  // Compare local vs remote -- skip if already up to date
1836
- if (isUpToDate(root, copyProviders, tmpDir)) {
1968
+ if (isUpToDate(root, copyProviders, tmpDir, scope)) {
1837
1969
  try {
1838
1970
  const wantHooks = installHooks && await decideHookInstall(root, copyProviders, { yes });
1839
1971
  const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, copyProviders, { force }) : [];
1840
1972
  rmSync(tmpDir, { recursive: true, force: true });
1841
- const v = getSkillsVersion(root);
1973
+ const v = getSkillsVersion(root, scope);
1842
1974
  console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
1843
1975
  if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
1844
1976
  console.log('Nothing else to do.');
@@ -1865,16 +1997,16 @@ async function update(flags = []) {
1865
1997
 
1866
1998
  // Retire any old `i-`-prefixed install up front so the refresh lands on the
1867
1999
  // canonical `impeccable` dir rather than orphaning the prefixed copy.
1868
- const migrated = migrateUnprefixImpeccable(root);
2000
+ const migrated = migrateUnprefixImpeccable(root, scope);
1869
2001
  if (migrated > 0) console.log('Migrated a prefixed install back to /impeccable (the i- prefix is no longer used).');
1870
2002
 
1871
- const updated = refreshProviderSkills(tmpDir, root, copyProviders);
2003
+ const updated = refreshProviderSkills(tmpDir, root, copyProviders, scope);
1872
2004
  const wantHooks = installHooks && await decideHookInstall(root, providers, { yes });
1873
2005
  const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, providers, { force }) : [];
1874
2006
 
1875
2007
  rmSync(tmpDir, { recursive: true, force: true });
1876
2008
 
1877
- const v = getSkillsVersion(root);
2009
+ const v = getSkillsVersion(root, scope);
1878
2010
  console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
1879
2011
  if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
1880
2012
  console.log('Done!\n');
@@ -1223,6 +1223,10 @@ if (IS_BROWSER) {
1223
1223
  type: f.type || f.id,
1224
1224
  category: ap ? ap.category : 'quality',
1225
1225
  severity: f.severity || ap?.severity || 'warning',
1226
+ // Advisory findings (em-dash overuse, etc.) are surfaced but never
1227
+ // treated as failures; carry the flag so the overlay/extension can
1228
+ // render them with the mildest affordance and consumers can filter.
1229
+ advisory: (ap && ap.advisory === true) || f.advisory === true,
1226
1230
  detail: f.detail || f.snippet,
1227
1231
  ignoreValue: f.ignoreValue || f.value || '',
1228
1232
  name: ap ? ap.name : (f.type || f.id),
@@ -1541,6 +1545,17 @@ if (IS_BROWSER) {
1541
1545
  addBrowserFindings(groupMap, document.body, repeatedTextFindings);
1542
1546
  }
1543
1547
 
1548
+ // Em-dash overuse (advisory): browser parity with the static/regex path.
1549
+ // Reads rendered body text so it catches dashes written as HTML entities.
1550
+ // serializeFindings stamps the advisory flag from the registry.
1551
+ const emDashFindings = checkEmDashOveruseDOM()
1552
+ .map(f => ({ type: f.id, detail: f.snippet }))
1553
+ .filter(f => _ruleOk(f.type));
1554
+ if (emDashFindings.length > 0) {
1555
+ pageLevelFindings.push(...emDashFindings);
1556
+ addBrowserFindings(groupMap, document.body, emDashFindings);
1557
+ }
1558
+
1544
1559
  const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
1545
1560
  for (const f of layoutFindings) {
1546
1561
  const el = f.el || document.body;
@@ -1,7 +1,8 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
+ import { fileURLToPath } from 'node:url';
3
4
 
4
- import { loadDesignSystemForCwd } from '../design-system.mjs';
5
+ import { loadDesignSystemForTarget } from '../design-system.mjs';
5
6
  import { RULE_SCOPES, filterByScopes } from '../registry/antipatterns.mjs';
6
7
  import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
7
8
  import { detectHtml } from '../engines/static-html/detect-html.mjs';
@@ -27,9 +28,37 @@ function formatFindingSummary(count) {
27
28
  return `${count} anti-pattern${count === 1 ? '' : 's'} found.`;
28
29
  }
29
30
 
30
- function formatFindings(findings, jsonMode) {
31
- if (jsonMode) return JSON.stringify(findings, null, 2);
31
+ // Local filesystem path behind a file:// URL, or null when it can't be mapped.
32
+ function fileUrlToLocalPath(url) {
33
+ try {
34
+ return fileURLToPath(url);
35
+ } catch {
36
+ return null;
37
+ }
38
+ }
39
+
40
+ // Advisory findings are detected but never treated as failures: they list in a
41
+ // separate, visually dimmed section, are excluded from the failure count that
42
+ // drives the exit code, and carry `"advisory": true` in JSON so consumers can
43
+ // filter. Every advisory finding carries the flag (stamped by the registry via
44
+ // findings.mjs).
45
+ function isAdvisory(finding) {
46
+ return finding && finding.advisory === true;
47
+ }
48
+
49
+ function partitionAdvisory(findings) {
50
+ const primary = [];
51
+ const advisory = [];
52
+ for (const f of findings) (isAdvisory(f) ? advisory : primary).push(f);
53
+ return { primary, advisory };
54
+ }
55
+
56
+ // ANSI dim, when stderr is a TTY. Advisory output is chrome, so keep it quiet.
57
+ function dim(text) {
58
+ return process.stderr.isTTY ? `\x1b[2m${text}\x1b[0m` : text;
59
+ }
32
60
 
61
+ function formatFindingsBody(findings) {
33
62
  const grouped = {};
34
63
  for (const f of findings) {
35
64
  if (!grouped[f.file]) grouped[f.file] = [];
@@ -44,7 +73,28 @@ function formatFindings(findings, jsonMode) {
44
73
  out.push(` → ${item.description}`);
45
74
  }
46
75
  }
47
- out.push(`\n${formatFindingSummary(findings.length)}`);
76
+ return out;
77
+ }
78
+
79
+ function formatAdvisorySection(advisory) {
80
+ if (!advisory || advisory.length === 0) return '';
81
+ const lines = [`\n${dim('── Advisory (not counted as failures) ──')}`];
82
+ for (const line of formatFindingsBody(advisory)) lines.push(dim(line));
83
+ lines.push(dim(`\n${advisory.length} advisory note${advisory.length === 1 ? '' : 's'}. Suppress with --no-advisory.`));
84
+ return lines.join('\n');
85
+ }
86
+
87
+ // Text/JSON formatter. `findings` is the full set; advisory items are separated
88
+ // out into their own section and excluded from the failure summary count. JSON
89
+ // output keeps every finding (each advisory one flagged) in a single array.
90
+ function formatFindings(findings, jsonMode) {
91
+ if (jsonMode) return JSON.stringify(findings, null, 2);
92
+
93
+ const { primary, advisory } = partitionAdvisory(findings);
94
+ const out = [...formatFindingsBody(primary)];
95
+ out.push(`\n${formatFindingSummary(primary.length)}`);
96
+ const advisorySection = formatAdvisorySection(advisory);
97
+ if (advisorySection) out.push(advisorySection);
48
98
  return out.join('\n');
49
99
  }
50
100
 
@@ -52,7 +102,11 @@ function formatFindings(findings, jsonMode) {
52
102
  // Stdin handling
53
103
  // ---------------------------------------------------------------------------
54
104
 
55
- async function handleStdin(options = {}) {
105
+ // `optionsFor` maps a local path to scan options carrying that path's own
106
+ // project design system (or base options when null). Falls back to a plain
107
+ // object so direct/legacy callers still work.
108
+ async function handleStdin(optionsFor = () => ({})) {
109
+ const resolve = typeof optionsFor === 'function' ? optionsFor : () => optionsFor;
56
110
  const chunks = [];
57
111
  for await (const chunk of process.stdin) chunks.push(chunk);
58
112
  const input = Buffer.concat(chunks).toString('utf-8');
@@ -60,11 +114,12 @@ async function handleStdin(options = {}) {
60
114
  const parsed = JSON.parse(input);
61
115
  const fp = parsed?.tool_input?.file_path;
62
116
  if (fp && fs.existsSync(fp)) {
117
+ const options = resolve(fp);
63
118
  return HTML_EXTENSIONS.has(path.extname(fp).toLowerCase())
64
119
  ? detectHtml(fp, options) : detectText(fs.readFileSync(fp, 'utf-8'), fp, options);
65
120
  }
66
121
  } catch { /* not JSON */ }
67
- return detectText(input, '<stdin>', options);
122
+ return detectText(input, '<stdin>', resolve(null));
68
123
  }
69
124
 
70
125
 
@@ -100,8 +155,14 @@ Options:
100
155
  ignore comments, or DESIGN.md
101
156
  --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
102
157
  --no-design-system Do not load local DESIGN.md / .impeccable/design.json context
158
+ --no-advisory Suppress advisory findings entirely (e.g. em-dash overuse)
103
159
  --help Show this help message
104
160
 
161
+ Advisory findings:
162
+ Some rules are advisory: detected and listed in a separate section, but never
163
+ counted as failures and never changing the exit code. They stay out of the
164
+ failure count so they never block automation. --no-advisory hides them.
165
+
105
166
  Project config:
106
167
  Respects .impeccable/config.json and .impeccable/config.local.json detector
107
168
  settings: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues,
@@ -139,6 +200,7 @@ async function detectCli() {
139
200
  const jsonMode = args.includes('--json');
140
201
  const quietMode = args.includes('--quiet');
141
202
  const helpMode = args.includes('--help');
203
+ const noAdvisory = args.includes('--no-advisory');
142
204
  // --fast (regex-only) is deprecated: since the jsdom removal, the static
143
205
  // HTML/CSS analysis is fast and covers every rule, so the regex-only path
144
206
  // only loses coverage for no real speed win. Accept the flag for back-compat
@@ -199,14 +261,23 @@ async function detectCli() {
199
261
  process.exit(1);
200
262
  }
201
263
  const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
202
- const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
203
264
  // Inline `impeccable-disable*` waivers are part of the scanned file, so they
204
265
  // apply by default. `--no-config` (raw scan) and the dedicated
205
266
  // `--no-inline-ignores` both turn them off.
206
267
  const inlineIgnoresEnabled = configEnabled && !args.includes('--no-inline-ignores');
207
- const scanOptions = { inlineIgnores: inlineIgnoresEnabled };
208
- if (designSystem) scanOptions.designSystem = designSystem;
209
- if (viewport) scanOptions.viewport = viewport;
268
+ const baseScanOptions = { inlineIgnores: inlineIgnoresEnabled };
269
+ if (viewport) baseScanOptions.viewport = viewport;
270
+ // DESIGN.md must resolve from EACH scan target's own project root, not from
271
+ // process.cwd(): scanning project B's files from inside project A applied A's
272
+ // design rules (cross-project contamination). Resolve per target, memoized by
273
+ // resolved project root so a multi-file scan pays the read once per project.
274
+ // A target with no project marker above it gets no design system (never cwd's).
275
+ const designSystemCache = new Map();
276
+ const scanOptionsFor = (localPath) => {
277
+ if (!designSystemEnabled || !localPath) return baseScanOptions;
278
+ const designSystem = loadDesignSystemForTarget(localPath, { cache: designSystemCache });
279
+ return designSystem ? { ...baseScanOptions, designSystem } : baseScanOptions;
280
+ };
210
281
  const targets = args.filter(a => !a.startsWith('--'));
211
282
 
212
283
  if (helpMode) { printUsage(); process.exit(0); }
@@ -214,7 +285,7 @@ async function detectCli() {
214
285
  let allFindings = [];
215
286
 
216
287
  if (!process.stdin.isTTY && targets.length === 0) {
217
- allFindings = await handleStdin(scanOptions);
288
+ allFindings = await handleStdin(scanOptionsFor);
218
289
  } else {
219
290
  const paths = targets.length > 0 ? targets : [process.cwd()];
220
291
  // file:// URLs get the same Puppeteer-rendered pass as http(s) — the
@@ -228,10 +299,17 @@ async function detectCli() {
228
299
  try {
229
300
  for (const target of paths) {
230
301
  if (urlRe.test(target)) {
302
+ // A file:// URL points at a local artifact, so its design system
303
+ // resolves from that file's project. A remote http(s) URL has no
304
+ // local project — it gets base options (no design system), never
305
+ // process.cwd()'s.
306
+ const urlOptions = /^file:/i.test(target)
307
+ ? scanOptionsFor(fileUrlToLocalPath(target))
308
+ : baseScanOptions;
231
309
  try {
232
310
  const scanner = browserDetector
233
- ? (url) => browserDetector.detectUrl(url, scanOptions)
234
- : (url) => detectUrl(url, scanOptions);
311
+ ? (url) => browserDetector.detectUrl(url, urlOptions)
312
+ : (url) => detectUrl(url, urlOptions);
235
313
  allFindings.push(...await scanner(target));
236
314
  } catch (e) { process.stderr.write(`Error: ${e.message}\n`); }
237
315
  continue;
@@ -297,11 +375,14 @@ async function detectCli() {
297
375
 
298
376
  for (const file of files) {
299
377
  const ext = path.extname(file).toLowerCase();
378
+ // Each file resolves its own project design system (cached by root),
379
+ // so a scan spanning sibling projects applies the right rules per file.
380
+ const fileOptions = scanOptionsFor(file);
300
381
  let fileFindings;
301
382
  if (HTML_EXTENSIONS.has(ext)) {
302
- fileFindings = await detectHtml(file, scanOptions);
383
+ fileFindings = await detectHtml(file, fileOptions);
303
384
  } else {
304
- fileFindings = detectText(fs.readFileSync(file, 'utf-8'), file, scanOptions);
385
+ fileFindings = detectText(fs.readFileSync(file, 'utf-8'), file, fileOptions);
305
386
  }
306
387
  // Annotate findings with import context
307
388
  const importers = importedByMap.get(file);
@@ -316,10 +397,11 @@ async function detectCli() {
316
397
  } else if (stat.isFile()) {
317
398
  if (shouldIgnoreDetectionFile(resolved, process.cwd(), detectionConfig)) continue;
318
399
  const ext = path.extname(resolved).toLowerCase();
400
+ const fileOptions = scanOptionsFor(resolved);
319
401
  if (HTML_EXTENSIONS.has(ext)) {
320
- allFindings.push(...await detectHtml(resolved, scanOptions));
402
+ allFindings.push(...await detectHtml(resolved, fileOptions));
321
403
  } else {
322
- allFindings.push(...detectText(fs.readFileSync(resolved, 'utf-8'), resolved, scanOptions));
404
+ allFindings.push(...detectText(fs.readFileSync(resolved, 'utf-8'), resolved, fileOptions));
323
405
  }
324
406
  }
325
407
  }
@@ -330,12 +412,24 @@ async function detectCli() {
330
412
 
331
413
  allFindings = filterDetectionFindings(allFindings, detectionConfig);
332
414
  allFindings = filterByScopes(allFindings, scopes);
415
+ // --no-advisory drops advisory findings before any output or exit-code math.
416
+ if (noAdvisory) allFindings = allFindings.filter((f) => !isAdvisory(f));
417
+
418
+ // The exit code and failure count reflect non-advisory findings only. An
419
+ // advisory-only scan still prints its notes but exits 0 (a clean pass), so
420
+ // advisory rules never break CI or block automation.
421
+ const { primary, advisory } = partitionAdvisory(allFindings);
333
422
 
334
423
  if (allFindings.length > 0) {
335
424
  if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
336
- else if (quietMode) process.stderr.write(formatFindingSummary(allFindings.length) + '\n');
425
+ else if (quietMode) {
426
+ process.stderr.write(formatFindingSummary(primary.length) + '\n');
427
+ if (advisory.length > 0) {
428
+ process.stderr.write(dim(`${advisory.length} advisory note${advisory.length === 1 ? '' : 's'} (not counted).`) + '\n');
429
+ }
430
+ }
337
431
  else process.stderr.write(formatFindings(allFindings, false) + '\n');
338
- process.exit(2);
432
+ process.exit(primary.length > 0 ? 2 : 0);
339
433
  }
340
434
  if (jsonMode) process.stdout.write('[]\n');
341
435
  process.exit(0);
@@ -1,4 +1,5 @@
1
1
  import fs from 'node:fs';
2
+ import os from 'node:os';
2
3
  import path from 'node:path';
3
4
 
4
5
  import { finding } from './findings.mjs';
@@ -7,6 +8,11 @@ import { parseAnyColor, resolveLengthPx } from './rules/checks.mjs';
7
8
 
8
9
  const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
9
10
  const FALLBACK_DIRS = ['.agents/context', 'docs'];
11
+ // Files/dirs whose presence marks a directory as a project root. Mirrors the
12
+ // walk-up semantics of skill/scripts/context.mjs (`resolveProject`), which the
13
+ // CLI can't import (separate tree). `.git` and `package.json` are the common
14
+ // boundaries; `.impeccable` is our own project marker.
15
+ const PROJECT_ROOT_MARKERS = ['.git', 'package.json', '.impeccable'];
10
16
  const COLOR_CHANNEL_TOLERANCE = 6;
11
17
  const RADIUS_TOLERANCE_PX = 0.5;
12
18
  const FONT_SIZE_TOLERANCE_PX = 0.5;
@@ -469,6 +475,62 @@ function loadDesignSystemForCwd(cwd = process.cwd()) {
469
475
  });
470
476
  }
471
477
 
478
+ // Directory to begin the project-root walk from, given a scan target that may
479
+ // be a file or a directory (and may not exist yet).
480
+ function designSystemStartDir(targetPath, cwd = process.cwd()) {
481
+ const abs = path.isAbsolute(targetPath) ? targetPath : path.resolve(cwd, targetPath);
482
+ try {
483
+ return fs.statSync(abs).isDirectory() ? abs : path.dirname(abs);
484
+ } catch {
485
+ // Nonexistent path: treat an extension-bearing leaf as a file.
486
+ return path.extname(abs) ? path.dirname(abs) : abs;
487
+ }
488
+ }
489
+
490
+ // Walk up from `startDir` to the directory that governs the target's design
491
+ // system, mirroring skill/scripts/context.mjs's project-boundary semantics:
492
+ //
493
+ // - A directory carrying a DESIGN.md (directly or in a fallback dir) IS the
494
+ // design root — that's where the rules live.
495
+ // - A directory carrying a project marker (.git / package.json / .impeccable)
496
+ // but no DESIGN.md is a project BOUNDARY: the walk stops with no design
497
+ // system, so a sibling project never inherits a parent's or cwd's rules.
498
+ // - Reaching the home directory / filesystem root with neither means no
499
+ // design system at all — never process.cwd()'s.
500
+ //
501
+ // Returns { dir, hasDesign } for the stopping directory, or null when the walk
502
+ // runs out. This is the fix for cross-project contamination.
503
+ export function findDesignRoot(startDir) {
504
+ let dir = path.resolve(startDir);
505
+ const homeDir = path.resolve(os.homedir());
506
+ while (true) {
507
+ if (resolveDesignMdPath(dir)) return { dir, hasDesign: true };
508
+ if (PROJECT_ROOT_MARKERS.some((marker) => fs.existsSync(path.join(dir, marker)))) {
509
+ return { dir, hasDesign: false };
510
+ }
511
+ if (dir === homeDir) return null;
512
+ const parent = path.dirname(dir);
513
+ if (parent === dir) return null;
514
+ dir = parent;
515
+ }
516
+ }
517
+
518
+ // Resolve the design system that governs a specific scan target, by walking up
519
+ // from the target's own location — never process.cwd(). Scanning project B's
520
+ // files from inside project A applies B's DESIGN.md (or none), not A's.
521
+ //
522
+ // Pass a `cache` Map to memoize by resolved design root across a multi-file
523
+ // scan; a target with no design root above it resolves to null.
524
+ export function loadDesignSystemForTarget(targetPath, { cache, cwd = process.cwd() } = {}) {
525
+ const startDir = designSystemStartDir(targetPath, cwd);
526
+ const found = findDesignRoot(startDir);
527
+ const key = found ? `root:${found.dir}` : '\0none';
528
+ if (cache && cache.has(key)) return cache.get(key);
529
+ const loaded = found?.hasDesign ? loadDesignSystemForCwd(found.dir) : null;
530
+ if (cache) cache.set(key, loaded);
531
+ return loaded;
532
+ }
533
+
472
534
  function isAllowedFont(font, designSystem) {
473
535
  if (!font || GENERIC_FONTS.has(font)) return true;
474
536
  if (!designSystem?.hasFonts) return true;
@@ -82,6 +82,15 @@ const GENERIC_FONTS = new Set([
82
82
  const WCAG_LARGE_TEXT_PX = 18 * (96 / 72);
83
83
  const WCAG_LARGE_BOLD_TEXT_PX = 14 * (96 / 72);
84
84
 
85
+ // Em-dash overuse (advisory) thresholds, shared by the regex/static-HTML
86
+ // analyzer and the browser DOM check so both fire on the same saturation
87
+ // pattern. Two gates must hold: an absolute floor of EM_DASH_FLOOR dashes, and
88
+ // a density of at least one dash per EM_DASH_CHARS_PER_DASH characters of body
89
+ // text. A long article that uses a few em-dashes is left alone; a short,
90
+ // dash-per-clause page is not.
91
+ const EM_DASH_FLOOR = 8;
92
+ const EM_DASH_CHARS_PER_DASH = 500;
93
+
85
94
  // Serif faces that show up in italic-display heroes. The rule also fires when
86
95
  // the primary face is unknown but the stack ends in the generic `serif` token,
87
96
  // which catches custom/private faces with a serif fallback.
@@ -315,9 +324,14 @@ const ANTIPATTERNS = [
315
324
  {
316
325
  id: 'em-dash-overuse',
317
326
  category: 'slop',
327
+ // Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
328
+ // rather than a failure. It fires only on the AI saturation pattern, not on
329
+ // ordinary prose. Advisory findings are surfaced separately, never counted
330
+ // as failures, and skipped by the design hook unless a project opts in.
331
+ advisory: true,
318
332
  name: 'Em-dash overuse',
319
333
  description:
320
- 'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
334
+ 'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
321
335
  skillSection: 'Copy',
322
336
  skillGuideline: 'no em dashes',
323
337
  },
@@ -507,6 +521,14 @@ const ANTIPATTERNS = [
507
521
  description:
508
522
  'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
509
523
  },
524
+ {
525
+ id: 'undersized-ui-text',
526
+ category: 'quality',
527
+ scopes: ['type'],
528
+ name: 'Undersized functional text',
529
+ description:
530
+ 'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
531
+ },
510
532
  {
511
533
  id: 'all-caps-body',
512
534
  category: 'quality',
@@ -3367,6 +3389,33 @@ function checkNumberedSectionLabelsDOM() {
3367
3389
  return checkNumberedSectionLabels({ candidates });
3368
3390
  }
3369
3391
 
3392
+ // Em-dash overuse (ADVISORY) — pure logic shared by the browser DOM check.
3393
+ // Mirrors the regex/static-HTML analyzer in engines/regex/detect-text.mjs:
3394
+ // two gates (absolute floor + density) so a long article using a few dashes is
3395
+ // left alone while a short, dash-per-clause page is flagged. Operates on
3396
+ // already-rendered text, so no HTML-entity decoding is needed (the browser has
3397
+ // resolved `&mdash;` to the literal glyph). Exported for jsdom unit tests.
3398
+ function checkEmDashOveruse(text) {
3399
+ const body = typeof text === 'string' ? text.replace(/\s+/g, ' ') : '';
3400
+ let count = 0;
3401
+ const re = /[—]|--(?=\S)/g;
3402
+ while (re.exec(body) !== null) count++;
3403
+ if (count < EM_DASH_FLOOR) return [];
3404
+ if (body.length > count * EM_DASH_CHARS_PER_DASH) return [];
3405
+ return [{ id: 'em-dash-overuse', snippet: `${count} em-dashes in body text` }];
3406
+ }
3407
+
3408
+ function checkEmDashOveruseDOM() {
3409
+ const body = document.body;
3410
+ if (!body) return [];
3411
+ // innerText reflects rendered, visible text; fall back to textContent for
3412
+ // engines (jsdom) that don't compute innerText.
3413
+ const text = typeof body.innerText === 'string' && body.innerText
3414
+ ? body.innerText
3415
+ : (body.textContent || '');
3416
+ return checkEmDashOveruse(text);
3417
+ }
3418
+
3370
3419
  function checkElementMotionDOM(el) {
3371
3420
  const tag = el.tagName.toLowerCase();
3372
3421
  if (SAFE_TAGS.has(tag)) return [];
@@ -3594,6 +3643,27 @@ function textDescendantsFlushSides(el, rect) {
3594
3643
  return flush;
3595
3644
  }
3596
3645
 
3646
+ // Screen-reader-only ("visually hidden") text is exempt from the tiny-text
3647
+ // floors: it is never rendered, so its size is irrelevant. Detect the two
3648
+ // standard idioms — a known sr-only class on the element or an ancestor, and
3649
+ // the clip / 1px-box pattern. Works in both jsdom (declared styles) and the
3650
+ // browser (computed styles).
3651
+ const SR_ONLY_SELECTOR = '.sr-only, .visually-hidden, .visuallyhidden, .screen-reader, .screen-reader-only, .screenreader, .a11y-hidden, .hidden-visually, [class*="sr-only" i], [class*="visually-hidden" i], [class*="visuallyhidden" i], [class*="screen-reader" i], [class*="screenreader" i]';
3652
+ function isVisuallyHidden(el, style) {
3653
+ if ((el.matches && el.matches(SR_ONLY_SELECTOR)) || (el.closest && el.closest(SR_ONLY_SELECTOR))) return true;
3654
+ const pos = style.position || '';
3655
+ if (pos === 'absolute' || pos === 'fixed') {
3656
+ const clip = style.clip || '';
3657
+ const clipPath = style.clipPath || style.webkitClipPath || style['clip-path'] || '';
3658
+ if (/rect\(\s*0/.test(clip) || /inset\(\s*(?:50%|99|100%)/.test(clipPath)) return true;
3659
+ const w = parseFloat(style.width);
3660
+ const h = parseFloat(style.height);
3661
+ const overflow = style.overflow || '';
3662
+ if ((w === 1 || h === 1) && (overflow === 'hidden' || overflow === 'clip')) return true;
3663
+ }
3664
+ return false;
3665
+ }
3666
+
3597
3667
  // Pure quality checks. Most run on computed CSS and DOM-only inputs (work in
3598
3668
  // jsdom and the browser). Two checks (line-length, cramped-padding) gate on
3599
3669
  // element rect dimensions, which jsdom can't compute — pass `rect: null` from
@@ -3878,6 +3948,60 @@ function checkQuality(opts) {
3878
3948
  }
3879
3949
  }
3880
3950
 
3951
+ // --- Undersized functional / UI text ---
3952
+ // Complements `tiny-text` above, which owns long body copy and deliberately
3953
+ // EXEMPTS the UI furniture layer (nav, footer, links, buttons, labels,
3954
+ // uppercase micro-labels). This rule targets exactly that blind spot: the
3955
+ // interactive and short content-bearing text — nav items, buttons, labels,
3956
+ // table cells, meta rows, timecodes — shipped below an 11px floor.
3957
+ //
3958
+ // The live failure it closes: a build shipped its entire furniture layer at
3959
+ // 8px, and the design hook waved it through because 8px had been added to
3960
+ // the DESIGN.md size ramp. Being on the ramp is a token argument, not a
3961
+ // legibility one, so this rule ignores the design system entirely — a value
3962
+ // on the ramp is still flagged.
3963
+ //
3964
+ // Floors: 11px for anything functional. The floor holds inside a footer;
3965
+ // only NON-interactive legal smallprint gets the softer 10px floor. Exempts
3966
+ // sup/sub, visually-hidden (sr-only) text, and code/terminal contexts.
3967
+ // Uppercase letterspaced micro-labels are still functional — not exempt.
3968
+ {
3969
+ const directText = [...el.childNodes]
3970
+ .filter(n => n.nodeType === 3)
3971
+ .map(n => n.textContent || '')
3972
+ .join('')
3973
+ .replace(/\s+/g, ' ')
3974
+ .trim();
3975
+ const dtLen = directText.length;
3976
+ const UI_SKIP_TAGS = new Set(['sub', 'sup', 'script', 'style', 'title', 'option']);
3977
+ const notRendered = style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse';
3978
+ // jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
3979
+ // text that computes at or above the floor never reaches here. The browser
3980
+ // adapter additionally catches values only resolvable with real layout
3981
+ // (e.g. viewport-relative units, cascade winners set in linked sheets).
3982
+ if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !notRendered) {
3983
+ const EXEMPT_CONTEXT = 'pre, code, kbd, samp, var, svg, [aria-hidden="true"], [class*="terminal" i], [class*="console" i], [class*="code" i], [class*="mock" i], [class*="editor" i], [class*="syntax" i], [class*="diff" i]';
3984
+ const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
3985
+ if (!isExemptContext && !isVisuallyHidden(el, style)) {
3986
+ const INTERACTIVE = 'a[href], button, summary, label, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="treeitem"], [tabindex]';
3987
+ const FURNITURE = 'nav, [role="navigation"], td, th, [role="gridcell"], [role="cell"], caption, figcaption, dt, dd, footer, [class*="meta" i], [class*="label" i], [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="kicker" i], [class*="eyebrow" i], [class*="breadcrumb" i], [class*="timestamp" i], [class*="category" i], [class*="caption" i], [class*="nav" i]';
3988
+ const SMALLPRINT = 'small, footer, [class*="legal" i], [class*="copyright" i], [class*="fineprint" i], [class*="fine-print" i], [class*="smallprint" i], [class*="small-print" i], [class*="disclaimer" i], [class*="disclosure" i], [class*="footnote" i]';
3989
+ const isInteractive = (el.matches && el.matches(INTERACTIVE)) || (el.closest && el.closest(INTERACTIVE));
3990
+ const isFurniture = (el.matches && el.matches(FURNITURE)) || (el.closest && el.closest(FURNITURE));
3991
+ const isSmallprint = (el.matches && el.matches(SMALLPRINT)) || (el.closest && el.closest(SMALLPRINT));
3992
+ const floor = (!isInteractive && isSmallprint) ? 10 : 11;
3993
+ // Fire on functional text only: interactive, structural furniture, or
3994
+ // any short (<=20-char) run — the label / meta / timecode shape. Long
3995
+ // non-furniture body copy stays with `tiny-text`, so the two rules
3996
+ // never double-flag the same element.
3997
+ if (fontSize < floor && (isInteractive || isFurniture || dtLen <= 20)) {
3998
+ const excerpt = directText.slice(0, 40);
3999
+ findings.push({ id: 'undersized-ui-text', snippet: `${fontSize}px functional text "${excerpt}" (below ${floor}px floor)` });
4000
+ }
4001
+ }
4002
+ }
4003
+ }
4004
+
3881
4005
  // --- All-caps body text ---
3882
4006
  if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
3883
4007
  if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
@@ -7066,6 +7190,10 @@ if (IS_BROWSER) {
7066
7190
  type: f.type || f.id,
7067
7191
  category: ap ? ap.category : 'quality',
7068
7192
  severity: f.severity || ap?.severity || 'warning',
7193
+ // Advisory findings (em-dash overuse, etc.) are surfaced but never
7194
+ // treated as failures; carry the flag so the overlay/extension can
7195
+ // render them with the mildest affordance and consumers can filter.
7196
+ advisory: (ap && ap.advisory === true) || f.advisory === true,
7069
7197
  detail: f.detail || f.snippet,
7070
7198
  ignoreValue: f.ignoreValue || f.value || '',
7071
7199
  name: ap ? ap.name : (f.type || f.id),
@@ -7384,6 +7512,17 @@ if (IS_BROWSER) {
7384
7512
  addBrowserFindings(groupMap, document.body, repeatedTextFindings);
7385
7513
  }
7386
7514
 
7515
+ // Em-dash overuse (advisory): browser parity with the static/regex path.
7516
+ // Reads rendered body text so it catches dashes written as HTML entities.
7517
+ // serializeFindings stamps the advisory flag from the registry.
7518
+ const emDashFindings = checkEmDashOveruseDOM()
7519
+ .map(f => ({ type: f.id, detail: f.snippet }))
7520
+ .filter(f => _ruleOk(f.type));
7521
+ if (emDashFindings.length > 0) {
7522
+ pageLevelFindings.push(...emDashFindings);
7523
+ addBrowserFindings(groupMap, document.body, emDashFindings);
7524
+ }
7525
+
7387
7526
  const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
7388
7527
  for (const f of layoutFindings) {
7389
7528
  const el = f.el || document.body;
@@ -1,4 +1,4 @@
1
- import { GENERIC_FONTS, OVERUSED_FONTS } from '../../shared/constants.mjs';
1
+ import { GENERIC_FONTS, OVERUSED_FONTS, EM_DASH_FLOOR, EM_DASH_CHARS_PER_DASH } from '../../shared/constants.mjs';
2
2
  import { isNeutralColor } from '../../shared/color.mjs';
3
3
  import { extractGoogleFontFamilies } from '../../shared/fonts.mjs';
4
4
  import { checkSourceDesignSystem } from '../../design-system.mjs';
@@ -16,6 +16,7 @@ const hasRounded = (line) => /\brounded(?:-\w+)?\b/.test(line);
16
16
  const hasBorderRadius = (line) => /border-radius/i.test(line);
17
17
  const isSafeElement = (line) => /<(?:blockquote|nav[\s>]|pre[\s>]|code[\s>]|a\s|input[\s>]|span[\s>])/i.test(line);
18
18
 
19
+
19
20
  /** Strip HTML to plain text — drops script/style/comments/tags so
20
21
  * content-text analyzers don't false-positive on code or CSS. */
21
22
  function stripHtmlToText(html) {
@@ -306,15 +307,34 @@ const REGEX_ANALYZERS = [
306
307
  const dominant = Object.entries(counts).sort((a, b) => b[1] - a[1])[0][0];
307
308
  return [finding('monotonous-spacing', filePath, `~${dominant}px used ${maxCount}/${rounded.length} times (${Math.round(pct * 100)}%)`)];
308
309
  },
309
- // Em-dash overuse: 5+ em-dashes or "--" in body text content
310
- // (occasional em-dash use in prose is fine; the pattern fires only
311
- // when count crosses into AI-cadence territory).
310
+ // Em-dash overuse (ADVISORY): the AI cadence tell is em-dash *saturation*,
311
+ // not the occasional dash. Humans use em-dashes legitimately, so this rule is
312
+ // advisory (surfaced separately, never a failure, hook-skipped by default) and
313
+ // its threshold is deliberately conservative. Two gates must both hold:
314
+ // 1. Absolute floor of EM_DASH_FLOOR (8) dashes — a page with a handful
315
+ // never fires, no matter how short.
316
+ // 2. Density: at least one dash per EM_DASH_CHARS_PER_DASH (500) characters
317
+ // of body text, so a long article that uses eight across several thousand
318
+ // words is left alone while a short, dash-per-clause landing page is not.
319
+ // Raised from the old flat 5-dash floor, which fired on ordinary long prose.
320
+ //
321
+ // stripHtmlToText drops tags but leaves character-entity escapes intact, so
322
+ // a model that writes `&mdash;`, `&#8212;`, or `&#x2014;` renders an em-dash
323
+ // the counter never saw. Decode the em-dash entities (named, zero-padded
324
+ // decimal, upper/lower hex) to the literal glyph first. En-dash entities are
325
+ // deliberately left alone: the rule counts em-dashes, and the literal `–`
326
+ // was never counted either.
312
327
  (content, filePath) => {
313
- const text = stripHtmlToText(content);
328
+ const text = stripHtmlToText(content)
329
+ .replace(/&mdash;|&#0*8212;|&#x0*2014;/gi, '—');
314
330
  let count = 0;
315
331
  const re = /[—]|--(?=\S)/g;
316
332
  while (re.exec(text) !== null) count++;
317
- if (count < 5) return [];
333
+ if (count < EM_DASH_FLOOR) return [];
334
+ // Saturation gate: dashes must be dense in the prose, not sprinkled through
335
+ // a long document. textLength <= count * chars-per-dash means the density is
336
+ // at or above the threshold.
337
+ if (text.length > count * EM_DASH_CHARS_PER_DASH) return [];
318
338
  return [finding('em-dash-overuse', filePath, `${count} em-dashes in body text`)];
319
339
  },
320
340
  // Marketing buzzwords: SaaS phrase list
@@ -6,7 +6,13 @@ function getAP(id) {
6
6
 
7
7
  function finding(id, filePath, snippet, line = 0) {
8
8
  const ap = getAP(id);
9
- return { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', category: ap.category || null, file: filePath, line, snippet };
9
+ const base = { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', category: ap.category || null, file: filePath, line, snippet };
10
+ // Advisory findings are detected but reported separately and never counted as
11
+ // failures. Carry the flag on the finding so every consumer (CLI, JSON, hook)
12
+ // can partition without a registry lookup. Only stamped when true to keep the
13
+ // finding shape stable for the vast majority of rules.
14
+ if (ap.advisory === true) base.advisory = true;
15
+ return base;
10
16
  }
11
17
 
12
18
  export { getAP, finding };
@@ -213,9 +213,14 @@ const ANTIPATTERNS = [
213
213
  {
214
214
  id: 'em-dash-overuse',
215
215
  category: 'slop',
216
+ // Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
217
+ // rather than a failure. It fires only on the AI saturation pattern, not on
218
+ // ordinary prose. Advisory findings are surfaced separately, never counted
219
+ // as failures, and skipped by the design hook unless a project opts in.
220
+ advisory: true,
216
221
  name: 'Em-dash overuse',
217
222
  description:
218
- 'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
223
+ 'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
219
224
  skillSection: 'Copy',
220
225
  skillGuideline: 'no em dashes',
221
226
  },
@@ -405,6 +410,14 @@ const ANTIPATTERNS = [
405
410
  description:
406
411
  'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
407
412
  },
413
+ {
414
+ id: 'undersized-ui-text',
415
+ category: 'quality',
416
+ scopes: ['type'],
417
+ name: 'Undersized functional text',
418
+ description:
419
+ 'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
420
+ },
408
421
  {
409
422
  id: 'all-caps-body',
410
423
  category: 'quality',
@@ -556,6 +569,18 @@ function getAntipattern(id) {
556
569
  return ANTIPATTERNS.find(rule => rule.id === id);
557
570
  }
558
571
 
572
+ // Advisory rules are detected and reported, but never treated as failures:
573
+ // the CLI lists them under a separate "Advisory" section, they do not affect
574
+ // exit codes or the failure count, and the design hook skips them by default.
575
+ // The set is derived from the registry so a rule only needs `advisory: true`.
576
+ const ADVISORY_RULE_IDS = new Set(
577
+ ANTIPATTERNS.filter(rule => rule.advisory === true).map(rule => rule.id),
578
+ );
579
+
580
+ function isAdvisoryRule(id) {
581
+ return ADVISORY_RULE_IDS.has(id);
582
+ }
583
+
559
584
  function getRulesForCategory(category) {
560
585
  return ANTIPATTERNS.filter(rule => rule.category === category);
561
586
  }
@@ -585,8 +610,10 @@ export {
585
610
  ANTIPATTERNS,
586
611
  RULE_SCOPES,
587
612
  RULE_ENGINE_SUPPORT,
613
+ ADVISORY_RULE_IDS,
588
614
  getAntipattern,
589
615
  getRulesForCategory,
590
616
  getRuleEngineSupport,
617
+ isAdvisoryRule,
591
618
  filterByScopes,
592
619
  };
@@ -1,5 +1,7 @@
1
1
  import {
2
2
  BORDER_SAFE_TAGS,
3
+ EM_DASH_CHARS_PER_DASH,
4
+ EM_DASH_FLOOR,
3
5
  GENERIC_FONTS,
4
6
  KNOWN_SERIF_FONTS,
5
7
  OVERUSED_FONTS,
@@ -2594,6 +2596,33 @@ function checkNumberedSectionLabelsDOM() {
2594
2596
  return checkNumberedSectionLabels({ candidates });
2595
2597
  }
2596
2598
 
2599
+ // Em-dash overuse (ADVISORY) — pure logic shared by the browser DOM check.
2600
+ // Mirrors the regex/static-HTML analyzer in engines/regex/detect-text.mjs:
2601
+ // two gates (absolute floor + density) so a long article using a few dashes is
2602
+ // left alone while a short, dash-per-clause page is flagged. Operates on
2603
+ // already-rendered text, so no HTML-entity decoding is needed (the browser has
2604
+ // resolved `&mdash;` to the literal glyph). Exported for jsdom unit tests.
2605
+ function checkEmDashOveruse(text) {
2606
+ const body = typeof text === 'string' ? text.replace(/\s+/g, ' ') : '';
2607
+ let count = 0;
2608
+ const re = /[—]|--(?=\S)/g;
2609
+ while (re.exec(body) !== null) count++;
2610
+ if (count < EM_DASH_FLOOR) return [];
2611
+ if (body.length > count * EM_DASH_CHARS_PER_DASH) return [];
2612
+ return [{ id: 'em-dash-overuse', snippet: `${count} em-dashes in body text` }];
2613
+ }
2614
+
2615
+ function checkEmDashOveruseDOM() {
2616
+ const body = document.body;
2617
+ if (!body) return [];
2618
+ // innerText reflects rendered, visible text; fall back to textContent for
2619
+ // engines (jsdom) that don't compute innerText.
2620
+ const text = typeof body.innerText === 'string' && body.innerText
2621
+ ? body.innerText
2622
+ : (body.textContent || '');
2623
+ return checkEmDashOveruse(text);
2624
+ }
2625
+
2597
2626
  function checkElementMotionDOM(el) {
2598
2627
  const tag = el.tagName.toLowerCase();
2599
2628
  if (SAFE_TAGS.has(tag)) return [];
@@ -2821,6 +2850,27 @@ function textDescendantsFlushSides(el, rect) {
2821
2850
  return flush;
2822
2851
  }
2823
2852
 
2853
+ // Screen-reader-only ("visually hidden") text is exempt from the tiny-text
2854
+ // floors: it is never rendered, so its size is irrelevant. Detect the two
2855
+ // standard idioms — a known sr-only class on the element or an ancestor, and
2856
+ // the clip / 1px-box pattern. Works in both jsdom (declared styles) and the
2857
+ // browser (computed styles).
2858
+ const SR_ONLY_SELECTOR = '.sr-only, .visually-hidden, .visuallyhidden, .screen-reader, .screen-reader-only, .screenreader, .a11y-hidden, .hidden-visually, [class*="sr-only" i], [class*="visually-hidden" i], [class*="visuallyhidden" i], [class*="screen-reader" i], [class*="screenreader" i]';
2859
+ function isVisuallyHidden(el, style) {
2860
+ if ((el.matches && el.matches(SR_ONLY_SELECTOR)) || (el.closest && el.closest(SR_ONLY_SELECTOR))) return true;
2861
+ const pos = style.position || '';
2862
+ if (pos === 'absolute' || pos === 'fixed') {
2863
+ const clip = style.clip || '';
2864
+ const clipPath = style.clipPath || style.webkitClipPath || style['clip-path'] || '';
2865
+ if (/rect\(\s*0/.test(clip) || /inset\(\s*(?:50%|99|100%)/.test(clipPath)) return true;
2866
+ const w = parseFloat(style.width);
2867
+ const h = parseFloat(style.height);
2868
+ const overflow = style.overflow || '';
2869
+ if ((w === 1 || h === 1) && (overflow === 'hidden' || overflow === 'clip')) return true;
2870
+ }
2871
+ return false;
2872
+ }
2873
+
2824
2874
  // Pure quality checks. Most run on computed CSS and DOM-only inputs (work in
2825
2875
  // jsdom and the browser). Two checks (line-length, cramped-padding) gate on
2826
2876
  // element rect dimensions, which jsdom can't compute — pass `rect: null` from
@@ -3105,6 +3155,60 @@ function checkQuality(opts) {
3105
3155
  }
3106
3156
  }
3107
3157
 
3158
+ // --- Undersized functional / UI text ---
3159
+ // Complements `tiny-text` above, which owns long body copy and deliberately
3160
+ // EXEMPTS the UI furniture layer (nav, footer, links, buttons, labels,
3161
+ // uppercase micro-labels). This rule targets exactly that blind spot: the
3162
+ // interactive and short content-bearing text — nav items, buttons, labels,
3163
+ // table cells, meta rows, timecodes — shipped below an 11px floor.
3164
+ //
3165
+ // The live failure it closes: a build shipped its entire furniture layer at
3166
+ // 8px, and the design hook waved it through because 8px had been added to
3167
+ // the DESIGN.md size ramp. Being on the ramp is a token argument, not a
3168
+ // legibility one, so this rule ignores the design system entirely — a value
3169
+ // on the ramp is still flagged.
3170
+ //
3171
+ // Floors: 11px for anything functional. The floor holds inside a footer;
3172
+ // only NON-interactive legal smallprint gets the softer 10px floor. Exempts
3173
+ // sup/sub, visually-hidden (sr-only) text, and code/terminal contexts.
3174
+ // Uppercase letterspaced micro-labels are still functional — not exempt.
3175
+ {
3176
+ const directText = [...el.childNodes]
3177
+ .filter(n => n.nodeType === 3)
3178
+ .map(n => n.textContent || '')
3179
+ .join('')
3180
+ .replace(/\s+/g, ' ')
3181
+ .trim();
3182
+ const dtLen = directText.length;
3183
+ const UI_SKIP_TAGS = new Set(['sub', 'sup', 'script', 'style', 'title', 'option']);
3184
+ const notRendered = style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse';
3185
+ // jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
3186
+ // text that computes at or above the floor never reaches here. The browser
3187
+ // adapter additionally catches values only resolvable with real layout
3188
+ // (e.g. viewport-relative units, cascade winners set in linked sheets).
3189
+ if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !notRendered) {
3190
+ const EXEMPT_CONTEXT = 'pre, code, kbd, samp, var, svg, [aria-hidden="true"], [class*="terminal" i], [class*="console" i], [class*="code" i], [class*="mock" i], [class*="editor" i], [class*="syntax" i], [class*="diff" i]';
3191
+ const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
3192
+ if (!isExemptContext && !isVisuallyHidden(el, style)) {
3193
+ const INTERACTIVE = 'a[href], button, summary, label, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="treeitem"], [tabindex]';
3194
+ const FURNITURE = 'nav, [role="navigation"], td, th, [role="gridcell"], [role="cell"], caption, figcaption, dt, dd, footer, [class*="meta" i], [class*="label" i], [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="kicker" i], [class*="eyebrow" i], [class*="breadcrumb" i], [class*="timestamp" i], [class*="category" i], [class*="caption" i], [class*="nav" i]';
3195
+ const SMALLPRINT = 'small, footer, [class*="legal" i], [class*="copyright" i], [class*="fineprint" i], [class*="fine-print" i], [class*="smallprint" i], [class*="small-print" i], [class*="disclaimer" i], [class*="disclosure" i], [class*="footnote" i]';
3196
+ const isInteractive = (el.matches && el.matches(INTERACTIVE)) || (el.closest && el.closest(INTERACTIVE));
3197
+ const isFurniture = (el.matches && el.matches(FURNITURE)) || (el.closest && el.closest(FURNITURE));
3198
+ const isSmallprint = (el.matches && el.matches(SMALLPRINT)) || (el.closest && el.closest(SMALLPRINT));
3199
+ const floor = (!isInteractive && isSmallprint) ? 10 : 11;
3200
+ // Fire on functional text only: interactive, structural furniture, or
3201
+ // any short (<=20-char) run — the label / meta / timecode shape. Long
3202
+ // non-furniture body copy stays with `tiny-text`, so the two rules
3203
+ // never double-flag the same element.
3204
+ if (fontSize < floor && (isInteractive || isFurniture || dtLen <= 20)) {
3205
+ const excerpt = directText.slice(0, 40);
3206
+ findings.push({ id: 'undersized-ui-text', snippet: `${fontSize}px functional text "${excerpt}" (below ${floor}px floor)` });
3207
+ }
3208
+ }
3209
+ }
3210
+ }
3211
+
3108
3212
  // --- All-caps body text ---
3109
3213
  if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
3110
3214
  if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
@@ -5121,6 +5225,8 @@ export {
5121
5225
  checkNumberedSectionLabels,
5122
5226
  checkNumberedSectionLabelsFromDoc,
5123
5227
  checkNumberedSectionLabelsDOM,
5228
+ checkEmDashOveruse,
5229
+ checkEmDashOveruseDOM,
5124
5230
  isRepeatedTextContainer,
5125
5231
  collectRepeatedContainerTextFindings,
5126
5232
  checkRepeatedContainerTextFromDoc,
@@ -68,6 +68,15 @@ const GENERIC_FONTS = new Set([
68
68
  const WCAG_LARGE_TEXT_PX = 18 * (96 / 72);
69
69
  const WCAG_LARGE_BOLD_TEXT_PX = 14 * (96 / 72);
70
70
 
71
+ // Em-dash overuse (advisory) thresholds, shared by the regex/static-HTML
72
+ // analyzer and the browser DOM check so both fire on the same saturation
73
+ // pattern. Two gates must hold: an absolute floor of EM_DASH_FLOOR dashes, and
74
+ // a density of at least one dash per EM_DASH_CHARS_PER_DASH characters of body
75
+ // text. A long article that uses a few em-dashes is left alone; a short,
76
+ // dash-per-clause page is not.
77
+ const EM_DASH_FLOOR = 8;
78
+ const EM_DASH_CHARS_PER_DASH = 500;
79
+
71
80
  // Serif faces that show up in italic-display heroes. The rule also fires when
72
81
  // the primary face is unknown but the stack ends in the generic `serif` token,
73
82
  // which catches custom/private faces with a serif fallback.
@@ -97,5 +106,7 @@ export {
97
106
  GENERIC_FONTS,
98
107
  WCAG_LARGE_TEXT_PX,
99
108
  WCAG_LARGE_BOLD_TEXT_PX,
109
+ EM_DASH_FLOOR,
110
+ EM_DASH_CHARS_PER_DASH,
100
111
  KNOWN_SERIF_FONTS,
101
112
  };
@@ -43,7 +43,7 @@ function detectorSection(raw) {
43
43
  return raw && raw.detector && typeof raw.detector === 'object' && !Array.isArray(raw.detector) ? raw.detector : null;
44
44
  }
45
45
 
46
- const DETECTOR_CONFIG_KEYS = new Set(['ignoreRules', 'ignoreFiles', 'ignoreValues', 'designSystem']);
46
+ const DETECTOR_CONFIG_KEYS = new Set(['ignoreRules', 'ignoreFiles', 'ignoreValues', 'designSystem', 'advisoryRules']);
47
47
 
48
48
  const DEFAULT_DETECTION_CONFIG = Object.freeze({
49
49
  ignoreRules: [],
@@ -71,6 +71,11 @@ function cloneRawDetectionConfig() {
71
71
 
72
72
  function applyDetectionConfigSource(config, raw) {
73
73
  if (!raw || typeof raw !== 'object') return config;
74
+ // Advisory rules are opt-in for the design hook; the CLI carries the setting
75
+ // so config round-trips (e.g. `impeccable hooks ignore-value`) preserve it.
76
+ if (raw.advisoryRules === 'include' || raw.advisoryRules === 'exclude') {
77
+ config.advisoryRules = raw.advisoryRules;
78
+ }
74
79
  if (raw.designSystem && typeof raw.designSystem === 'object' && !Array.isArray(raw.designSystem)) {
75
80
  config.designSystem = {
76
81
  ...config.designSystem,
@@ -151,6 +156,9 @@ function normalizeDetectionConfigForWrite(config) {
151
156
  out.ignoreFiles = uniqueStrings(config.ignoreFiles.filter(v => typeof v === 'string' && v.trim()).map(v => v.trim()));
152
157
  }
153
158
  out.ignoreValues = normalizeIgnoreValueEntries(config?.ignoreValues || []);
159
+ if (config?.advisoryRules === 'include' || config?.advisoryRules === 'exclude') {
160
+ out.advisoryRules = config.advisoryRules;
161
+ }
154
162
  if (config?.designSystem && typeof config.designSystem === 'object' && !Array.isArray(config.designSystem)) {
155
163
  out.designSystem = {
156
164
  enabled: config.designSystem.enabled === false ? false : true,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "impeccable",
3
- "version": "3.3.0",
3
+ "version": "3.3.1",
4
4
  "author": "Paul Bakaus",
5
5
  "description": "Design skills, commands, and anti-pattern detection for AI coding agents",
6
6
  "keywords": [
@@ -58,6 +58,7 @@
58
58
  "test:cli-remote-e2e": "node scripts/run-tests.mjs cli-remote-e2e",
59
59
  "test:live-e2e": "node scripts/run-tests.mjs live-e2e",
60
60
  "test:live-e2e-accept-cleanup": "node scripts/run-tests.mjs live-e2e-accept-cleanup",
61
+ "test:new-work-e2e": "node scripts/run-tests.mjs new-work-e2e",
61
62
  "test:live-e2e-agent": "node scripts/run-tests.mjs live-e2e-agent",
62
63
  "test:skill-behavior": "node scripts/run-tests.mjs skill-behavior",
63
64
  "test:live-svelte-adapter-deepseek": "node scripts/run-tests.mjs live-svelte-adapter-deepseek",