@webjsdev/ui 0.3.14 → 0.3.16

package/src/lint/index.js

@@ -0,0 +1,205 @@
+/**
+ * The `webjsui lint` orchestrator: walks the app, reads each module, runs the
+ * scanner, dispatches every class site to every enabled rule, and returns the
+ * violations. It does the filesystem work so the rules stay pure (the same
+ * split `@webjsdev/server`'s check runner uses: collect first, then hand pure
+ * rule functions the collected set).
+ *
+ * Scope (D7): `app/**`, `components/**`, `modules/**` and `lib/**` under the
+ * config's cwd, over `.ts .tsx .js .jsx .mts .mjs`; `node_modules`, `.webjs`,
+ * `dist` and `public` are never walked. `resolvedPaths.ui` (default
+ * `components/ui`) is skipped by default: a copied primitive legitimately owns
+ * structural values no variant can express (`ring-[3px]`, `[&_svg]:size-4`)
+ * and is what every other file's variants are measured against, so linting it
+ * with the app's rules is backwards. An app widens the scope with a negated
+ * ignore entry (`"!components/ui/**"`) or narrows it with more globs.
+ *
+ * @module lint
+ */
+
+import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { scanClassSites, collectHelperImports } from './scan.js';
+import { readThemeTokens } from './theme-tokens.js';
+import { extractHelperAxes } from '../registry/extract.js';
+import { RULES, RULE_NAMES } from './rules/index.js';
+
+const SCAN_DIRS = ['app', 'components', 'modules', 'lib'];
+const EXTENSIONS = /\.(?:ts|tsx|js|jsx|mts|mjs)$/;
+const NEVER_WALK = new Set(['node_modules', '.webjs', 'dist', 'public']);
+
+/**
+ * @typedef {{
+ *   rule: string, severity: 'warn'|'error', file: string,
+ *   line: number, column: number, class: string, message: string, fix?: string,
+ * }} Violation
+ */
+
+/**
+ * Normalize `config.lint.rules` into `{ name: { severity, allow } }` for the
+ * rules that are on. A bare severity string and the object form both land
+ * here; an absent rule is off.
+ *
+ * @param {any} lint the parsed `lint` block, or undefined
+ * @returns {Record<string, { severity: 'warn'|'error', allow: string[] }>}
+ */
+export function enabledRules(lint) {
+  /** @type {Record<string, { severity: 'warn'|'error', allow: string[] }>} */
+  const out = {};
+  const rules = lint?.rules ?? {};
+  for (const name of RULE_NAMES) {
+    const raw = rules[name];
+    if (raw === undefined) continue;
+    const severity = typeof raw === 'string' ? raw : raw.severity;
+    if (severity === 'off') continue;
+    out[name] = { severity, allow: typeof raw === 'string' ? [] : (raw.allow ?? []) };
+  }
+  return out;
+}
+
+/** A minimal glob (`**`, `*`, `?`) to RegExp over a posix relative path. */
+export function globToRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        i++;
+        if (glob[i + 1] === '/') { i++; re += '(?:.*/)?'; } else re += '.*';
+      } else re += '[^/]*';
+    } else if (c === '?') re += '[^/]';
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${re}$`);
+}
+
+function toPosix(p) {
+  return p.split(sep).join('/');
+}
+
+/**
+ * Walk the D7 scope and return every lintable file, relative to `cwd` (posix).
+ * @param {string} cwd
+ */
+function collectFiles(cwd) {
+  /** @type {string[]} */
+  const files = [];
+  const walk = (dir) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (NEVER_WALK.has(e.name)) continue;
+      const full = join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile() && EXTENSIONS.test(e.name)) files.push(toPosix(relative(cwd, full)));
+    }
+  };
+  for (const d of SCAN_DIRS) {
+    const full = join(cwd, d);
+    if (existsSync(full) && statSync(full).isDirectory()) walk(full);
+  }
+  return files.sort();
+}
+
+/**
+ * Lint the app at `cwd` against the parsed `components.json` config.
+ *
+ * @param {string} cwd
+ * @param {ReturnType<import('../utils/get-config.js').getConfig>} config
+ * @returns {{ violations: Violation[], warnings: string[], configured: boolean }}
+ *   `warnings` are non-violation notices (an unreadable theme path);
+ *   `configured` is false when no rule is on, the opt-in guarantee.
+ */
+export function lintApp(cwd, config) {
+  const root = resolve(cwd);
+  const rules = enabledRules(config.lint);
+  /** @type {string[]} */
+  const warnings = [];
+  if (Object.keys(rules).length === 0) return { violations: [], warnings, configured: false };
+
+  // Ignore set: the ui dir by default, plus the app's entries. A `!` entry
+  // un-ignores whatever it MATCHES, so `!components/ui/**` widens the scope
+  // over the whole ui dir and `!components/ui/button.ts` over one file.
+  const uiRel = toPosix(relative(root, config.resolvedPaths.ui));
+  const ignore = [`${uiRel}/**`];
+  const unignore = [];
+  for (const entry of config.lint?.ignore ?? []) {
+    if (entry.startsWith('!')) unignore.push(entry.slice(1));
+    else ignore.push(entry);
+  }
+  // An entry also covers its own subtree, and a leading `./` or a trailing `/`
+  // is dropped, so the directory spellings (`app/legacy`, `app/legacy/`,
+  // `./app/legacy/**`) work instead of silently matching no file.
+  const toRes = (glob) => {
+    const g = glob.replace(/^\.\//, '').replace(/\/+$/, '');
+    return [globToRegExp(g), globToRegExp(`${g}/**`)];
+  };
+  const ignoreRes = ignore.flatMap(toRes);
+  const unignoreRes = unignore.flatMap(toRes);
+  const isIgnored = (rel) => ignoreRes.some((re) => re.test(rel)) && !unignoreRes.some((re) => re.test(rel));
+
+  // Theme tokens, read once; no tokens disables no-raw-colors for the run.
+  let tokens = [];
+  let themePath = toPosix(relative(root, config.resolvedPaths.tailwindCss));
+  if (rules['no-raw-colors']) {
+    const theme = readThemeTokens(config.resolvedPaths.tailwindCss);
+    tokens = theme.tokens;
+    if (tokens.length === 0) {
+      warnings.push(`no-raw-colors is off for this run: no --color-* tokens found in a @theme block of ${themePath} (tailwind.css in components.json)`);
+      delete rules['no-raw-colors'];
+      if (Object.keys(rules).length === 0) return { violations: [], warnings, configured: true };
+    }
+  }
+
+  /** @type {Map<string, Record<string, Record<string, string[]>>>} axes per helper file */
+  const axesCache = new Map();
+  const axesForFile = (absPath) => {
+    const candidates = [absPath, `${absPath}.ts`, `${absPath}.js`];
+    for (const p of candidates) {
+      if (axesCache.has(p)) return { axes: axesCache.get(p), file: toPosix(relative(root, p)) };
+      let src;
+      try { src = readFileSync(p, 'utf8'); } catch { continue; }
+      const axes = extractHelperAxes(src);
+      axesCache.set(p, axes);
+      return { axes, file: toPosix(relative(root, p)) };
+    }
+    return { axes: {}, file: null };
+  };
+
+  /** @type {Violation[]} */
+  const violations = [];
+  for (const rel of collectFiles(root)) {
+    if (isIgnored(rel)) continue;
+    const abs = join(root, rel);
+    let src;
+    try { src = readFileSync(abs, 'utf8'); } catch { continue; }
+    const imports = collectHelperImports(src, {
+      filePath: abs,
+      appRoot: root,
+      uiDir: config.resolvedPaths.ui,
+      utilsPath: config.resolvedPaths.utils,
+    });
+    // `cnNames` is passed even when empty ON PURPOSE: the scanner's own default
+    // recognizes a bare `cn`, but here `cn` counts only when imported from the
+    // configured utils alias, so an unrecognized `cn` never opens a call site.
+    const sites = scanClassSites(src, { helpers: imports.helpers, cnNames: imports.cnNames });
+    if (!sites.length) continue;
+    const axesFor = (helper) => {
+      const target = imports.helperFiles[helper];
+      if (!target) return { axes: {}, file: null };
+      const r = axesForFile(target);
+      return { axes: r.axes[imports.helperExports[helper] ?? helper] ?? {}, file: r.file };
+    };
+    for (const site of sites) {
+      for (const [name, conf] of Object.entries(rules)) {
+        const ctx = { tokens, themePath, allow: conf.allow, axesFor };
+        for (const v of RULES[name](site, ctx)) {
+          violations.push({ rule: name, severity: conf.severity, file: rel, ...v });
+        }
+      }
+    }
+  }
+  // Two rules can flag one token (an arbitrary colour beside a helper); keep both, ordered.
+  violations.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column || a.rule.localeCompare(b.rule));
+  return { violations, warnings, configured: true };
+}

package/src/lint/rules/index.js

@@ -0,0 +1,12 @@
+/** The rule table `webjsui lint` dispatches over. Each rule is pure: `(site, ctx) => violations`. */
+import { noRawColors } from './no-raw-colors.js';
+import { noArbitraryValues } from './no-arbitrary-values.js';
+import { noRestyle } from './no-restyle.js';
+
+export const RULES = {
+  'no-raw-colors': noRawColors,
+  'no-arbitrary-values': noArbitraryValues,
+  'no-restyle': noRestyle,
+};
+
+export const RULE_NAMES = Object.keys(RULES);

package/src/lint/rules/no-arbitrary-values.js

@@ -0,0 +1,33 @@
+/**
+ * `no-arbitrary-values`: a token whose UTILITY carries a bracket (`p-[13px]`,
+ * `ring-[3px]`, `[padding:13px]`), which sidesteps the theme's scale. An
+ * arbitrary VARIANT (`[&_svg]:size-4`, `has-[>svg]:px-3`) never fires, and the
+ * `(--var)` shorthand never fires, per the grammar. `allow` takes category
+ * names (`layout`, `spacing`) and class-group ids (`rounded`).
+ *
+ * @module lint/rules/no-arbitrary-values
+ */
+
+import { parseToken, isAllowed } from '../grammar.js';
+
+/**
+ * @param {import('../scan.js').ClassSite} site
+ * @param {{ allow?: string[] }} ctx
+ * @returns {Array<{ line: number, column: number, class: string, message: string }>}
+ */
+export function noArbitraryValues(site, ctx) {
+  const out = [];
+  for (const token of site.classes) {
+    const parsed = parseToken(token.name);
+    if (!parsed.arbitraryValue) continue;
+    if (isAllowed(parsed, ctx.allow)) continue;
+    const category = parsed.category ?? 'layout';
+    out.push({
+      line: token.line,
+      column: token.column,
+      class: token.name,
+      message: `${parsed.utility} is an arbitrary value (${category}${parsed.group ? `, group ${parsed.group}` : ''}). Use a theme scale step instead, or allow "${category}"${parsed.group && !parsed.group.startsWith('arbitrary..') ? ` or "${parsed.group}"` : ''} in the rule's allow list.`,
+    });
+  }
+  return out;
+}

package/src/lint/rules/no-raw-colors.js

@@ -0,0 +1,86 @@
+/**
+ * `no-raw-colors`: a Tailwind palette utility (`text-red-600`, `bg-sky-500`)
+ * in a class site, where the app's theme declares a token that should carry
+ * the role instead.
+ *
+ * The message names ONLY utilities the app's own theme declares (read from the
+ * configured Tailwind CSS by `theme-tokens.js`), joined to the offender's own
+ * prefix, so `--color-destructive` offers `text-destructive` for a `text-`
+ * offender. A nearest-role suggestion is added only where the mapping is
+ * unambiguous and the role is actually declared. When the theme yields no
+ * tokens the orchestrator never calls this rule, because a message that
+ * cannot name an alternative reproduces the prose-guidance failure at higher
+ * volume.
+ *
+ * @module lint/rules/no-raw-colors
+ */
+
+import { parseToken } from '../grammar.js';
+
+const PREFIXES = ['text', 'bg', 'border', 'ring', 'divide', 'outline', 'fill', 'stroke', 'from', 'via', 'to', 'shadow', 'decoration', 'placeholder', 'caret', 'accent'];
+const FAMILIES = ['red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal', 'cyan', 'sky', 'blue', 'indigo', 'violet', 'purple', 'fuchsia', 'pink', 'rose', 'slate', 'gray', 'zinc', 'neutral', 'stone'];
+const STEPS = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950'];
+
+const RAW = new RegExp(`^(${PREFIXES.join('|')})-(${FAMILIES.join('|')})-(${STEPS.join('|')})$`);
+
+/** Families whose role match is unambiguous. */
+const ROLE = {
+  red: () => 'destructive',
+  rose: () => 'destructive',
+  slate: (prefix) => (prefix === 'text' ? 'muted-foreground' : 'muted'),
+  gray: (prefix) => (prefix === 'text' ? 'muted-foreground' : 'muted'),
+  zinc: (prefix) => (prefix === 'text' ? 'muted-foreground' : 'muted'),
+  neutral: (prefix) => (prefix === 'text' ? 'muted-foreground' : 'muted'),
+  stone: (prefix) => (prefix === 'text' ? 'muted-foreground' : 'muted'),
+};
+
+/** The tokens worth listing first for a given prefix, in this order, then the rest of the theme. */
+const LEAD = ['destructive', 'muted-foreground', 'primary', 'foreground', 'muted', 'accent', 'secondary', 'background', 'border'];
+const LIST_MAX = 6;
+
+/**
+ * @param {import('../scan.js').ClassSite} site
+ * @param {{ tokens: string[], themePath: string }} ctx
+ * @returns {Array<{ line: number, column: number, class: string, message: string, fix?: string }>}
+ */
+export function noRawColors(site, ctx) {
+  const out = [];
+  for (const token of site.classes) {
+    const parsed = parseToken(token.name);
+    const m = RAW.exec(parsed.base);
+    if (!m) continue;
+    const [, prefix, family] = m;
+    const role = ROLE[family]?.(prefix);
+    const roleDeclared = role !== undefined && ctx.tokens.includes(role);
+    const ordered = [...LEAD.filter((t) => ctx.tokens.includes(t)), ...ctx.tokens.filter((t) => !LEAD.includes(t))];
+    const list = ordered.slice(0, LIST_MAX).map((t) => `${prefix}-${t}`);
+    let message = `${parsed.base} is a raw palette color. Use a theme token: ${list.join(', ')} (declared in ${ctx.themePath}).`;
+    if (roleDeclared) {
+      const what = family === 'red' || family === 'rose' ? 'error' : 'muted';
+      const noun = prefix === 'bg' ? 'surfaces' : prefix === 'text' ? 'text' : `${prefix} colors`;
+      message += ` For ${what} ${noun}, ${prefix}-${role} is the role match`;
+      message += role === 'destructive' && prefix === 'text' ? ', or use errorClass() from the kit.' : '.';
+    }
+    out.push({
+      line: token.line,
+      column: token.column,
+      class: token.name,
+      message,
+      ...(roleDeclared ? { fix: swapBase(token.name, parsed.base, `${prefix}-${role}`) } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * `raw` with its base utility swapped and everything else kept, so `fix` is a
+ * drop-in replacement for the reported `class`: the variants, the opacity
+ * modifier and a `!` all survive (`hover:text-red-600/50` to
+ * `hover:text-destructive/50`). The LAST occurrence is the utility, since an
+ * arbitrary variant ahead of it can spell the same text.
+ */
+function swapBase(raw, base, replacement) {
+  const at = raw.lastIndexOf(base);
+  if (at === -1) return replacement;
+  return raw.slice(0, at) + replacement + raw.slice(at + base.length);
+}

package/src/lint/rules/no-restyle.js

@@ -0,0 +1,66 @@
+/**
+ * `no-restyle`: a class composed NEXT TO a kit helper, in either shape WebJs
+ * writes: a `cn()` call whose arguments include both a `*Class()` call and a
+ * string literal, or a `class` attribute holding both a `${helperCall()}` hole
+ * and static text. The scanner records the helpers a site is composed with,
+ * so the rule fires on every class of a site that has at least one.
+ *
+ * The message names the helper's REAL variant and size values, read from the
+ * app's own copied helper source through `extractHelperAxes` (the shared
+ * projector in `registry/extract.js`), never from a second parser and never
+ * invented: a helper matching neither authored shape yields no value list.
+ *
+ * `allow` takes category names and class-group ids. The documented starting
+ * configuration is `["layout", "rounded"]`, which is what lets the skill's
+ * sanctioned one-off (`cn(buttonClass({ size: 'none' }), 'w-9 h-9
+ * rounded-full')`) pass: `w-9 h-9` is layout, and `rounded-full` is the plain
+ * radius group granted by name without opening the whole `shape` category.
+ *
+ * @module lint/rules/no-restyle
+ */
+
+import { parseToken, isAllowed } from '../grammar.js';
+
+/**
+ * @param {import('../scan.js').ClassSite} site
+ * @param {{ allow?: string[], axesFor: (helper: string) => { axes: Record<string, string[]>, file: string|null } }} ctx
+ * @returns {Array<{ line: number, column: number, class: string, message: string }>}
+ */
+export function noRestyle(site, ctx) {
+  if (!site.helpers.length) return [];
+  const out = [];
+  // Every composed helper is named; the axes come from the LAST one, since a
+  // later argument is what `cn` lets win.
+  const helper = site.helpers[site.helpers.length - 1];
+  const named = site.helpers.length === 1 ? helper : `${site.helpers.slice(0, -1).join(', ')} and ${helper}`;
+  const { axes, file } = ctx.axesFor(helper);
+  for (const token of site.classes) {
+    const parsed = parseToken(token.name);
+    if (isAllowed(parsed, ctx.allow)) continue;
+    let message = `${parsed.utility} overrides what ${named} already ${site.helpers.length === 1 ? 'sets' : 'set'}.`;
+    const axisNames = Object.keys(axes);
+    if (axisNames.length) {
+      const axis = pickAxis(parsed, axisNames);
+      message += ` Use a ${helper} ${axis}: ${axes[axis].join(', ')}`;
+      message += file ? ` (declared in ${file}).` : '.';
+    } else {
+      message += ` Pick a variant ${helper} exposes${file ? ` (declared in ${file})` : ''}, or allow "${parsed.category ?? 'layout'}"${parsed.group ? ` or "${parsed.group}"` : ''} in the rule's allow list.`;
+    }
+    out.push({ line: token.line, column: token.column, class: token.name, message });
+  }
+  return out;
+}
+
+/**
+ * A colour or typography override reads as a variant, and a size-ish one as a
+ * size when the helper has one. Font size and line height are the two
+ * typography groups a kit SIZE carries (`text-xs` in the button's `xs`), so they
+ * read as a size, while a weight or an underline stays a variant.
+ */
+function pickAxis(parsed, axisNames) {
+  const cat = parsed.category;
+  const sizeLike = cat === null || cat === 'spacing' || cat === 'shape' || parsed.group === 'font-size' || parsed.group === 'leading';
+  if (sizeLike && axisNames.includes('size')) return 'size';
+  if (axisNames.includes('variant')) return 'variant';
+  return axisNames[0];
+}