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.
- package/cli/bin/commands/skills.mjs +151 -19
- package/cli/engine/browser/injected/index.mjs +15 -0
- package/cli/engine/cli/main.mjs +113 -19
- package/cli/engine/design-system.mjs +62 -0
- package/cli/engine/detect-antipatterns-browser.js +140 -1
- package/cli/engine/engines/regex/detect-text.mjs +26 -6
- package/cli/engine/findings.mjs +7 -1
- package/cli/engine/registry/antipatterns.mjs +28 -1
- package/cli/engine/rules/checks.mjs +106 -0
- package/cli/engine/shared/constants.mjs +11 -0
- package/cli/lib/impeccable-config.mjs +9 -1
- package/package.json +2 -1
|
@@ -1195,21 +1195,52 @@ function hookScriptPathForProvider(skillRoot, provider) {
|
|
|
1195
1195
|
return null;
|
|
1196
1196
|
}
|
|
1197
1197
|
|
|
1198
|
-
|
|
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
|
|
1204
|
-
|
|
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
|
-
|
|
1395
|
-
|
|
1396
|
-
|
|
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
|
|
1808
|
-
const
|
|
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
|
-
|
|
1813
|
-
|
|
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;
|
package/cli/engine/cli/main.mjs
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
31
|
-
|
|
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
|
|
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
|
-
|
|
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>',
|
|
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
|
|
208
|
-
if (
|
|
209
|
-
|
|
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(
|
|
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,
|
|
234
|
-
: (url) => detectUrl(url,
|
|
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,
|
|
383
|
+
fileFindings = await detectHtml(file, fileOptions);
|
|
303
384
|
} else {
|
|
304
|
-
fileFindings = detectText(fs.readFileSync(file, 'utf-8'), file,
|
|
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,
|
|
402
|
+
allFindings.push(...await detectHtml(resolved, fileOptions));
|
|
321
403
|
} else {
|
|
322
|
-
allFindings.push(...detectText(fs.readFileSync(resolved, 'utf-8'), resolved,
|
|
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)
|
|
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
|
-
'
|
|
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 `—` 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:
|
|
310
|
-
//
|
|
311
|
-
//
|
|
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 `—`, `—`, or `—` 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(/—|�*8212;|�*2014;/gi, '—');
|
|
314
330
|
let count = 0;
|
|
315
331
|
const re = /[—]|--(?=\S)/g;
|
|
316
332
|
while (re.exec(text) !== null) count++;
|
|
317
|
-
if (count <
|
|
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
|
package/cli/engine/findings.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
-
'
|
|
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 `—` 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.
|
|
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",
|